commit 60e0ffc9593094efc51387f4bd40b4ff0d0c083c
Author: wehub-resource-sync <resource-sync@wehub.local>
Date:   Mon Jul 13 12:39:59 2026 +0800

    chore: import upstream snapshot with attribution

diff --git a/.ccignore b/.ccignore
new file mode 100644
index 0000000..1456179
--- /dev/null
+++ b/.ccignore
@@ -0,0 +1,7 @@
+.pre-commit-config.yaml
+.github/
+docs/changelog.mdx
+docs/python-sdk/
+examples/
+src/fastmcp/contrib/
+tests/contrib/
diff --git a/.claude/hooks/session-init.sh b/.claude/hooks/session-init.sh
new file mode 100755
index 0000000..3c767fc
--- /dev/null
+++ b/.claude/hooks/session-init.sh
@@ -0,0 +1,26 @@
+#!/bin/bash
+set -e
+
+# Only run in remote/cloud environments
+if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then
+  exit 0
+fi
+
+command -v gh &> /dev/null && exit 0
+
+LOCAL_BIN="$HOME/.local/bin"
+mkdir -p "$LOCAL_BIN"
+
+ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
+VERSION=$(curl -fsSL https://api.github.com/repos/cli/cli/releases/latest | grep '"tag_name"' | cut -d'"' -f4)
+TARBALL="gh_${VERSION#v}_linux_${ARCH}.tar.gz"
+
+echo "Installing gh ${VERSION}..."
+TEMP=$(mktemp -d)
+trap 'rm -rf "$TEMP"' EXIT
+curl -fsSL "https://github.com/cli/cli/releases/download/${VERSION}/${TARBALL}" | tar -xz -C "$TEMP"
+cp "$TEMP"/gh_*/bin/gh "$LOCAL_BIN/gh"
+chmod 755 "$LOCAL_BIN/gh"
+
+[ -n "$CLAUDE_ENV_FILE" ] && echo "export PATH=\"$LOCAL_BIN:\$PATH\"" >> "$CLAUDE_ENV_FILE"
+echo "gh installed: $("$LOCAL_BIN/gh" --version | head -1)"
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000..afc82c2
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-init.sh",
+            "timeout": 120
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/.claude/skills/code-review/SKILL.md b/.claude/skills/code-review/SKILL.md
new file mode 100644
index 0000000..bcc2698
--- /dev/null
+++ b/.claude/skills/code-review/SKILL.md
@@ -0,0 +1,101 @@
+---
+name: reviewing-code
+description: Review code for quality, maintainability, and correctness. Use when reviewing pull requests, evaluating code changes, or providing feedback on implementations. Focuses on API design, patterns, and actionable feedback.
+---
+
+# Code Review
+
+## Philosophy
+
+Code review maintains a healthy codebase while helping contributors succeed. The burden of proof is on the PR to demonstrate it adds value. Your job is to help it get there through actionable feedback.
+
+**Critical**: A perfectly written PR that adds unwanted functionality must still be rejected. The code must advance the codebase in the intended direction. When rejecting, provide clear guidance on how to align with project goals.
+
+Be friendly and welcoming while maintaining high standards. Call out what works well. When code needs improvement, be specific about why and how to fix it.
+
+## What to Focus On
+
+### Does this advance the codebase correctly?
+
+Even perfect code for unwanted features should be rejected.
+
+### Dependency version compatibility
+
+When a PR adapts code to a new version of a dependency (e.g., removing a parameter that was dropped upstream, using a new API):
+- **The version pin in `pyproject.toml` must match.** If the change breaks compatibility with the previously-pinned minimum version, the minimum version must be bumped. Otherwise users on the old version get a regression.
+- **If backwards compatibility with the old version is desired**, the code must handle both versions (e.g., try/except, version check). Simply deleting the old API usage without bumping the pin is always wrong — it silently breaks users on the old version.
+- **Lock file (`uv.lock`) changes should be scoped to the PR's purpose.** A PR fixing a ty compatibility issue should not also include unrelated dependency version bumps (anthropic, google-auth, etc.) from running `uv sync --upgrade`. These create noise and make the diff harder to review.
+
+### API design and naming
+
+Identify confusing patterns or non-idiomatic code:
+- Parameter values that contradict defaults
+- Mutable default arguments
+- Unclear naming that will confuse future readers
+- Inconsistent patterns with the rest of the codebase
+
+### Specific improvements
+
+Provide actionable feedback, not generic observations.
+
+### User ergonomics
+
+Think about the API from a user's perspective. Is it intuitive? What's the learning curve?
+
+## For Agent Reviewers
+
+1. **Read the full context**: Examine related files, tests, and documentation before reviewing
+2. **Check against established patterns**: Look for consistency with codebase conventions
+3. **Verify functionality claims**: Understand what the code actually does, not just what it claims
+4. **Consider edge cases**: Think through error conditions and boundary scenarios
+
+## What to Avoid
+
+- Generic feedback without specifics
+- Hypothetical problems unlikely to occur
+- Nitpicking organizational choices without strong reason
+- Summarizing what the PR already describes
+- Star ratings or excessive emojis
+- Bikeshedding style preferences when functionality is correct
+- Requesting changes without suggesting solutions
+- Focusing on personal coding style over project conventions
+
+## Tone
+
+- Acknowledge good decisions: "This API design is clean"
+- Be direct but respectful
+- Explain impact: "This will confuse users because..."
+- Remember: Someone else maintains this code forever
+
+## Decision Framework
+
+Before approving, ask:
+
+1. Does this PR achieve its stated purpose?
+2. Is that purpose aligned with where the codebase should go?
+3. Would I be comfortable maintaining this code?
+4. Have I actually understood what it does, not just what it claims?
+5. Does this change introduce technical debt?
+
+If something needs work, your review should help it get there through specific, actionable feedback. If it's solving the wrong problem, say so clearly.
+
+## Comment Examples
+
+**Good comments:**
+
+| Instead of | Write |
+|------------|-------|
+| "Add more tests" | "The `handle_timeout` method needs tests for the edge case where timeout=0" |
+| "This API is confusing" | "The parameter name `data` is ambiguous - consider `message_content` to match the MCP specification" |
+| "This could be better" | "This approach works but creates a circular dependency. Consider moving the validation to `utils/validators.py`" |
+
+## Checklist
+
+Before approving, verify:
+
+- [ ] All required development workflow steps completed (uv sync, prek, pytest)
+- [ ] Changes align with repository patterns and conventions
+- [ ] API changes are documented and backwards-compatible where possible
+- [ ] Error handling follows project patterns (specific exception types)
+- [ ] Tests cover new functionality and edge cases
+- [ ] The change advances the codebase in the intended direction
diff --git a/.claude/skills/python-tests/SKILL.md b/.claude/skills/python-tests/SKILL.md
new file mode 100644
index 0000000..4193f61
--- /dev/null
+++ b/.claude/skills/python-tests/SKILL.md
@@ -0,0 +1,220 @@
+---
+name: testing-python
+description: Write and evaluate effective Python tests using pytest. Use when writing tests, reviewing test code, debugging test failures, or improving test coverage. Covers test design, fixtures, parameterization, mocking, and async testing.
+---
+
+# Writing Effective Python Tests
+
+## Core Principles
+
+Every test should be **atomic**, **self-contained**, and test **single functionality**. A test that tests multiple things is harder to debug and maintain.
+
+## Test Structure
+
+### Atomic unit tests
+
+Each test should verify a single behavior. The test name should tell you what's broken when it fails. Multiple assertions are fine when they all verify the same behavior.
+
+```python
+# Good: Name tells you what's broken
+def test_user_creation_sets_defaults():
+    user = User(name="Alice")
+    assert user.role == "member"
+    assert user.id is not None
+    assert user.created_at is not None
+
+# Bad: If this fails, what behavior is broken?
+def test_user():
+    user = User(name="Alice")
+    assert user.role == "member"
+    user.promote()
+    assert user.role == "admin"
+    assert user.can_delete_others()
+```
+
+### Use parameterization for variations of the same concept
+
+```python
+import pytest
+
+@pytest.mark.parametrize("input,expected", [
+    ("hello", "HELLO"),
+    ("World", "WORLD"),
+    ("", ""),
+    ("123", "123"),
+])
+def test_uppercase_conversion(input, expected):
+    assert input.upper() == expected
+```
+
+### Use separate tests for different functionality
+
+Don't parameterize unrelated behaviors. If the test logic differs, write separate tests.
+
+## Project-Specific Rules
+
+### No async markers needed
+
+This project uses `asyncio_mode = "auto"` globally. Write async tests without decorators:
+
+```python
+# Correct
+async def test_async_operation():
+    result = await some_async_function()
+    assert result == expected
+
+# Wrong - don't add this
+@pytest.mark.asyncio
+async def test_async_operation():
+    ...
+```
+
+### Imports at module level
+
+Put ALL imports at the top of the file:
+
+```python
+# Correct
+import pytest
+from fastmcp import FastMCP
+from fastmcp.client import Client
+
+async def test_something():
+    mcp = FastMCP("test")
+    ...
+
+# Wrong - no local imports
+async def test_something():
+    from fastmcp import FastMCP  # Don't do this
+    ...
+```
+
+### Use in-memory transport for testing
+
+Pass FastMCP servers directly to clients:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.client import Client
+
+mcp = FastMCP("TestServer")
+
+@mcp.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+async def test_greet_tool():
+    async with Client(mcp) as client:
+        result = await client.call_tool("greet", {"name": "World"})
+        assert result[0].text == "Hello, World!"
+```
+
+Only use HTTP transport when explicitly testing network features.
+
+### Inline snapshots for complex data
+
+Use `inline-snapshot` for testing JSON schemas and complex structures:
+
+```python
+from inline_snapshot import snapshot
+
+def test_schema_generation():
+    schema = generate_schema(MyModel)
+    assert schema == snapshot()  # Will auto-populate on first run
+```
+
+Commands:
+- `pytest --inline-snapshot=create` - populate empty snapshots
+- `pytest --inline-snapshot=fix` - update after intentional changes
+
+## Fixtures
+
+### Prefer function-scoped fixtures
+
+```python
+@pytest.fixture
+def client():
+    return Client()
+
+async def test_with_client(client):
+    result = await client.ping()
+    assert result is not None
+```
+
+### Use `tmp_path` for file operations
+
+```python
+def test_file_writing(tmp_path):
+    file = tmp_path / "test.txt"
+    file.write_text("content")
+    assert file.read_text() == "content"
+```
+
+## Mocking
+
+### Mock at the boundary
+
+```python
+from unittest.mock import patch, AsyncMock
+
+async def test_external_api_call():
+    with patch("mymodule.external_client.fetch", new_callable=AsyncMock) as mock:
+        mock.return_value = {"data": "test"}
+        result = await my_function()
+        assert result == {"data": "test"}
+```
+
+### Don't mock what you own
+
+Test your code with real implementations when possible. Mock external services, not internal classes.
+
+## Test Naming
+
+Use descriptive names that explain the scenario:
+
+```python
+# Good
+def test_login_fails_with_invalid_password():
+def test_user_can_update_own_profile():
+def test_admin_can_delete_any_user():
+
+# Bad
+def test_login():
+def test_update():
+def test_delete():
+```
+
+## Error Testing
+
+```python
+import pytest
+
+def test_raises_on_invalid_input():
+    with pytest.raises(ValueError, match="must be positive"):
+        calculate(-1)
+
+async def test_async_raises():
+    with pytest.raises(ConnectionError):
+        await connect_to_invalid_host()
+```
+
+## Running Tests
+
+```bash
+uv run pytest -n auto              # Run all tests in parallel
+uv run pytest -n auto -x           # Stop on first failure
+uv run pytest path/to/test.py      # Run specific file
+uv run pytest -k "test_name"       # Run tests matching pattern
+uv run pytest -m "not integration" # Exclude integration tests
+```
+
+## Checklist
+
+Before submitting tests:
+- [ ] Each test tests one thing
+- [ ] No `@pytest.mark.asyncio` decorators
+- [ ] Imports at module level
+- [ ] Descriptive test names
+- [ ] Using in-memory transport (not HTTP) unless testing networking
+- [ ] Parameterization for variations of same behavior
+- [ ] Separate tests for different behaviors
diff --git a/.claude/skills/review-issue/SKILL.md b/.claude/skills/review-issue/SKILL.md
new file mode 100644
index 0000000..dc3ee11
--- /dev/null
+++ b/.claude/skills/review-issue/SKILL.md
@@ -0,0 +1,168 @@
+---
+name: review-issue
+description: Review an incoming external issue (and any gated-closed PR behind it) and decide whether to assign the contributor or decline. Use when the maintainer says "look at this issue", "review issue #N", "should we take this", or asks whether to assign someone. Assigning the author auto-reopens their PR for normal review. This is the entry point for incoming-issue triage — distinct from review-pr, which responds to bot reviews on your own open PR.
+---
+
+# Triaging contributions under the issue-link gate
+
+FastMCP auto-closes external PRs unless the author is **assigned to a referenced issue**
+(see [require-issue-link.yml](../../../.github/workflows/require-issue-link.yml)). The practical
+effect: contributors open an issue, open a PR, get auto-closed, and ask to be assigned. The
+maintainer almost never sees the PR directly — **the issue is the decision point**, and
+**assigning the author is the single action that reopens their PR** and sends it into review.
+
+This skill turns "look at this issue" into one of two outcomes:
+- **Assign** — the issue is valid, we want it fixed, an external PR is appropriate, and a sound
+  PR already exists → assign the author (auto-reopens the PR) and queue it for code review.
+- **Decline** — leave the issue/PR closed and explain why on the issue.
+
+Be opinionated about declining. The gate moved spam from junk PRs to junk issues; this skill is
+worthless if it just rubber-stamps assignment. Assignment is a commitment to review and likely
+merge, not a courtesy.
+
+## How the gate works (the part that matters here)
+
+- External PR is closed unless its body has `Fixes/Closes/Resolves #N` **and** the author is
+  assigned to issue `#N`.
+- **Assigning the author to the issue auto-reopens their closed PR** and re-runs the check —
+  this is the lever you pull. `gh issue edit N --add-assignee <login>`. The assignment fires a
+  `require-issue-link` run; expect it to pass. If it fails, the gate itself misbehaved (not the
+  PR) — investigate the run, don't re-assign.
+- Maintainer-authored PRs are exempt. A `trusted-contributor` label exempts a contributor up
+  front. Reopening the PR or removing the `missing-issue-link` label applies a sticky
+  `bypass-issue-check`.
+- Sibling bots have usually already run on the issue: `martian-triage-issue` (investigates +
+  recommends), `marvin-dedupe-issues` / `auto-close-duplicates` (dupes), `auto-close-needs-mre`
+  (missing MRE). Read their comments before re-deriving anything.
+
+## Step 1 — Orient
+
+Read the issue, its bot triage, and any PR behind it. Run these together:
+
+```bash
+gh issue view N --repo PrefectHQ/fastmcp \
+  --json number,title,state,author,body,labels,assignees,comments
+# Find PRs the author opened that reference this issue (they're likely CLOSED):
+gh pr list --repo PrefectHQ/fastmcp --state all --search "author:<login> #N in:body" \
+  --json number,title,state,url,labels
+```
+
+If a PR exists, pull its metadata and any review-bot comments (CodeRabbit, Codex). Treat the bot
+comments as leads, not conclusions — they often don't run on closed PRs at all, and even when
+they do you still owe the PR your own read:
+
+```bash
+gh pr view <pr> --repo PrefectHQ/fastmcp --json number,title,body,labels,files,additions,deletions
+gh pr view <pr> --repo PrefectHQ/fastmcp --comments
+```
+
+## Step 2 — Classify the issue (is it valid AND a real bug?)
+
+- Is there a real, reproducible problem? For bugs, demand an MRE that shows FastMCP misbehaving
+  — not user config error, not a question, not an upstream-SDK issue.
+- Is it a duplicate or already fixed on `main`? Check the dedupe bot's comment and recent commits.
+- If the issue itself is weak, **stop here and decline** — don't evaluate the PR. A good PR
+  attached to a bad issue is still declined.
+
+**A reproducible MRE is not the same as a bug.** This is the trap that produces wrong verdicts:
+an MRE can demonstrate real, observable behavior that is nonetheless *not a bug*, because it
+violates no contract the framework intends to hold. The decisive question is not "does this
+reproduce?" but "does the demonstrated behavior violate the intended contract for this API?" A
+shared-mutable-state MRE only matters if callers are *supposed* to mutate that state; an
+ordering/timing MRE only matters if the framework promises an order; a "wrong" value only matters
+relative to what the API guarantees. An MRE that has to reach past the supported surface to
+trigger the behavior (mutating a field meant to be set only at construction, depending on an
+internal that isn't part of the public contract) is showing you a property, not a defect.
+
+You usually cannot read the intended contract off the code — the code shows what it *does*, not
+what it *promises*. **The maintainer is often the only authoritative source for the contract, so
+stopping to ask is legitimate and expected here.** Ask "is X a supported pattern / does this API
+promise Y?" before sinking time into investigating a fix. If the behavior is in-contract correct,
+decline — no matter how cleanly the PR fixes it, and no matter how real the MRE looks.
+
+## Step 3 — Investigate the PR (mandatory; do NOT skip if a PR exists)
+
+The most common failure of this skill is judging a PR from the diff hunk and the PR description
+alone. That is a cursory review and it produces wrong verdicts — a redundant-looking conditional
+can be a real bug fix; a tidy-looking diff can patch the wrong layer. **You cannot assess a PR
+without reading the code it changes in context.** Reading `gh pr diff` is necessary but never
+sufficient.
+
+Do all of this before forming any opinion on quality:
+
+1. **Read the diff in full**, then **open every file it touches in the repo** (`Read`, not just
+   the patch). The hunk shows *what changed*; the file shows *what it changed into*.
+2. **Trace the functions and values the change depends on.** Grep for the called functions,
+   the fields being set, and the defaults. If the PR overrides or replaces a value, find what
+   produced the original value and what consumes it downstream.
+3. **Establish the actual root cause from the issue's MRE**, then check whether the change fixes
+   *that* — at the layer where the bug originates, not a compensating patch elsewhere.
+4. **Check consistency with adjacent code.** Does the new value/behavior match how nearby code
+   already handles the same case? An inconsistency is a real finding; a match is evidence the fix
+   is correct.
+5. **Run or read the tests** the PR adds/changes — do they actually exercise the bug, and would
+   they fail without the fix?
+
+Write down, for yourself, a one-line answer to: *what was broken, where, and does this change fix
+it there?* If you can't answer from evidence you've actually read, you haven't investigated yet.
+
+Then separate findings by severity: a **cosmetic** nit (style, a redundant-but-harmless line) is a
+review comment, not a blocker. A **substantive** defect (wrong layer, breaks an adjacent path,
+doesn't actually fix the MRE) changes the verdict. Don't let a cosmetic nit read as a reason to
+decline, and don't let a clean style read as evidence of correctness.
+
+## Step 4 — Decide if an external PR is appropriate (CONTRIBUTING.md)
+
+This is the gate CONTRIBUTING.md actually enforces. Map the change to a category:
+
+- **Simple, well-scoped bug fix** → external PR welcome. Assignable.
+- **Docs / typo / example fix** → welcome. Assignable.
+- **Auth provider** → assignable (auth is the one integration exception).
+- **Enhancement / feature** → needs a maintainer-approved design proposal *in the issue first*.
+  Do **not** assign just because code exists. If the proposal is sound, the path is "approve the
+  approach in the issue, then assign" — not "assign because they were fast."
+- **Third-party integration** (middleware, provider adapters, non-auth) → decline; belongs in a
+  separate package.
+- **Sweeping / multi-subsystem change with no prior discussion** → decline.
+
+Combine the category with the Step 3 investigation: does it fix the cause or paper over a symptom?
+Does it read like unedited LLM output (verbose body, speculative/shotgun changes)? CONTRIBUTING.md
+says we close those — a closed PR that reads that way is staying closed.
+
+## Step 5 — Recommend, then act
+
+Present a short verdict to the maintainer before mutating anything: **assign** or **decline**,
+one or two sentences of reasoning, and the exact command you'll run. Wait for confirmation on
+borderline calls; for clear-cut ones you may proceed and report.
+
+**Assign** (valid issue + appropriate external contribution + sound PR exists):
+
+```bash
+gh issue edit N --repo PrefectHQ/fastmcp --add-assignee <login>
+```
+
+That reopens the PR automatically. Then hand off to code review — invoke the `code-review` /
+`review-pr` skills on the reopened PR. Assignment is not approval; the code still gets the normal
+pass.
+
+If a PR's head branch was deleted, assignment can't reopen it — the workflow comments asking the
+author to open a fresh PR. Don't try to force it.
+
+**Decline** (invalid issue, wrong contribution type, or low-quality PR): leave it closed and
+comment on the **issue** explaining the decision, pointing to the relevant CONTRIBUTING.md
+section. Per repo rules, use `--body-file`, never inline `--body`, for any comment that could
+contain `$`, backticks, or code:
+
+```bash
+gh issue comment N --repo PrefectHQ/fastmcp --body-file /tmp/triage-reply.md
+```
+
+Keep the reply short and point to the relevant CONTRIBUTING.md section. (If a `github-reply`
+skill is available for maintainer voice/tone, use it — but it isn't required.)
+
+## What this skill does NOT do
+
+- It doesn't bypass the gate via `trusted-contributor` / `bypass-issue-check` — that's a
+  deliberate maintainer escalation, not a triage outcome.
+- It doesn't merge. Assignment → reopen → review → (maybe) merge are distinct steps.
+- It doesn't re-run the first-pass triage the bots already did; read their output instead.
diff --git a/.claude/skills/review-pr/SKILL.md b/.claude/skills/review-pr/SKILL.md
new file mode 100644
index 0000000..93d0ebb
--- /dev/null
+++ b/.claude/skills/review-pr/SKILL.md
@@ -0,0 +1,111 @@
+---
+name: review-pr
+description: Monitor and respond to automated PR reviews (Codex bot). Use when pushing a PR, checking review status, or responding to bot feedback. Handles the full cycle of push -> wait for review -> evaluate comments -> fix -> re-push.
+---
+
+# PR Review Workflow
+
+This repo has `chatgpt-codex-connector[bot]` configured as an automated reviewer. After every push to a PR branch, Codex reviews the diff and either:
+- Reacts with a thumbs-up on its review body (no suggestions — PR is clean)
+- Posts inline comments with suggestions (each tagged with a priority badge)
+
+## Checking review status
+
+After pushing, check whether Codex has reviewed the latest commit:
+
+```bash
+# Get the latest commit SHA on the branch
+LATEST=$(git rev-parse HEAD)
+
+# Check if Codex has reviewed that specific commit
+gh api repos/PrefectHQ/fastmcp/pulls/{PR_NUMBER}/reviews \
+  | jq "[.[] | select(.user.login == \"chatgpt-codex-connector[bot]\" and .commit_id == \"$LATEST\")] | length"
+```
+
+If the count is 0, Codex hasn't reviewed the latest push yet. Wait and check again.
+
+If the count is > 0, check for inline comments on the latest review:
+
+```bash
+# Get the review body to check for thumbs-up
+gh api repos/PrefectHQ/fastmcp/pulls/{PR_NUMBER}/reviews \
+  | jq '[.[] | select(.user.login == "chatgpt-codex-connector[bot]") | {state, body: .body[:300], commit_id: .commit_id}] | last'
+```
+
+A clean review from Codex looks like a review body that contains a thumbs-up reaction or says "no suggestions." If the body contains "Here are some automated review suggestions," there are inline comments to evaluate.
+
+## Evaluating Codex comments
+
+Fetch all inline comments from Codex:
+
+```bash
+gh api repos/PrefectHQ/fastmcp/pulls/{PR_NUMBER}/comments \
+  | jq '[.[] | select(.user.login == "chatgpt-codex-connector[bot]") | {body, path, line, created_at}]'
+```
+
+Codex comments include priority badges:
+- `P0` (red) — Critical issue, likely a real bug
+- `P1` (orange) — Important, worth fixing
+- `P2` (yellow) — Moderate, evaluate on merit
+
+**How to evaluate Codex comments:**
+
+1. **Treat Codex as a competent but sometimes overzealous reviewer.** It catches real bugs (cache eviction ordering, silent data loss, missing validation) but also suggests scope expansions and hypothetical improvements.
+
+2. **Fix real bugs** — issues in code you actually changed where behavior is incorrect or data is silently lost.
+
+3. **Dismiss scope expansion** — if a comment points out a pre-existing limitation unrelated to your diff, note it as a potential follow-up but don't block the PR.
+
+4. **Dismiss speculative concerns** — if a comment describes a scenario that requires very specific conditions and the existing behavior is acceptable, dismiss it.
+
+5. **When fixing, be proactive** — if Codex found one instance of a pattern bug (e.g., missing role validation in one handler), check all similar code paths before pushing. Codex will find the next instance on the next review cycle, so get ahead of it.
+
+## Responding to every comment
+
+**Every Codex comment must get a visible response** — either a fix or a reply explaining why it was dismissed. The maintainer can't see your reasoning otherwise.
+
+- **If fixing**: The fix itself is the response. No reply needed unless the fix is non-obvious.
+- **If dismissing**: Reply to the comment thread with a brief explanation of why. Keep it to 1-2 sentences. Examples:
+  - "This is pre-existing behavior unrelated to this diff — the scope lookup fallback existed before caching was added. Worth a follow-up issue but not blocking this PR."
+  - "The AsyncExitStack handles cleanup when the session exits, so the subprocess isn't leaked — just kept alive slightly longer than necessary in this edge case."
+  - "Gemini supports a much wider range of media types than OpenAI/Anthropic, so a restrictive allowlist would be inaccurate here."
+
+Use `gh api` to reply (note: use `in_reply_to`, not a `/replies` sub-path):
+
+```bash
+# Reply to a specific review comment
+gh api repos/PrefectHQ/fastmcp/pulls/{PR_NUMBER}/comments \
+  -f body="Your reply here" \
+  -F in_reply_to={COMMENT_ID}
+```
+
+## The fix-push-review cycle
+
+After evaluating comments:
+
+1. Fix all real issues in one batch
+2. Reply to all dismissed comments with reasoning
+3. Think about what patterns Codex might flag next — check similar code paths proactively
+4. Commit and push
+5. Check that Codex reviews the new commit
+6. Repeat until Codex gives a clean review (thumbs-up) or only has dismissible comments
+
+## Responding to stale comments
+
+Codex sometimes re-posts old comments that reference code you've already fixed (they appear on the old commit's diff). These are stale — verify the fix is in the latest commit and reply noting the fix is already in place.
+
+## Labels — never apply or invent them
+
+**Do not apply labels to PRs or issues programmatically, and never create new ones.** Labeling is the maintainer's call (and is often automated). Two hard rules:
+
+- **Never invent a label.** GitHub's "add labels" API *auto-creates* any label name that doesn't already exist — so a typo or a guessed name silently pollutes the repo's label list with a stray, uncolored duplicate. Adding `breaking` (which does not exist) creates it alongside the real `breaking change` label.
+- **Use only labels that already exist.** If you genuinely need to confirm a label, look it up first (`get_label` / the repo's label list) and match the exact name. The canonical names here are specific — e.g. the breaking-change label is **`breaking change`**, not `breaking`; enhancements is **`enhancements`**, features is **`features`**, bugs is **`bugs`**.
+
+When a change warrants a label (e.g. it's breaking), **say so in the PR body and let the maintainer apply the label** rather than applying it yourself. There is no MCP tool to delete a label, so a mistaken creation can only be cleaned up by hand in repo settings — the cost of guessing is high and one-directional.
+
+## When a PR is ready
+
+A PR is ready for human review when:
+- All Codex comments are either fixed or replied to with dismissal reasoning
+- CI checks pass
+- The diff is clean and focused on the stated purpose
diff --git a/.coderabbit.yaml b/.coderabbit.yaml
new file mode 100644
index 0000000..b7937d7
--- /dev/null
+++ b/.coderabbit.yaml
@@ -0,0 +1,3 @@
+reviews:
+  path_filters:
+    - "!docs/python-sdk/**"
diff --git a/.cursor/rules/core-mcp-objects.mdc b/.cursor/rules/core-mcp-objects.mdc
new file mode 100644
index 0000000..ccbc829
--- /dev/null
+++ b/.cursor/rules/core-mcp-objects.mdc
@@ -0,0 +1,13 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+There are four major MCP object types:
+
+- Tools (src/tools/)
+- Resources (src/resources/)
+- Resource Templates (src/resources/)
+- Prompts (src/prompts)
+
+While these have slightly different semantics and implementations, in general changes that affect interactions with any one (like adding tags, importing, etc.) will need to be adopted, applied, and tested on all others. Note that while resources and resource templates are different objects, they are both in `src/resources/`.
\ No newline at end of file
diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml
new file mode 100644
index 0000000..1e6139c
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug.yml
@@ -0,0 +1,70 @@
+name: 🐛 Bug Report
+description: Report a bug or unexpected behavior in FastMCP
+labels: [bug, pending]
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug!
+
+        A good bug report is one of the most valuable contributions you can make — see [CONTRIBUTING.md](../../CONTRIBUTING.md). If the fix is straightforward, a PR is also welcome.
+
+        ### Before you submit
+
+        - Make sure you're testing on the **latest version** of FastMCP — many issues are already fixed in newer releases
+        - Check if someone else has **already reported this** or if it's been fixed on the main branch
+        - You **must** include a copy/pasteable, properly formatted MRE (minimal reproducible example) or your issue may be closed without response
+        - **The ideal issue is a clear problem description and an MRE — that's it.** If you've done genuine investigation and have a non-obvious insight into the root cause, include it. But please don't speculate or ask an LLM to generate a diagnosis. We have LLMs too, and an incorrect analysis is harder to work with than none at all.
+        - **Keep it short.** A clear description plus a concise MRE is ideal — aim to fit in a single screen. Issues that include unsolicited root cause analysis, proposed fixes, or multi-section diagnostic writeups will be labeled `too-long` and not triaged until condensed.
+        - **Using an LLM?** Great — but it must follow these guidelines. Generic LLM output that ignores our contributing conventions will be closed. See [CONTRIBUTING.md](../../CONTRIBUTING.md).
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: |
+        Describe the bug in a few sentences. What did you do, what happened, and what did you expect instead?
+
+        Do NOT include root cause analysis, proposed fixes, or diagnostic writeups — just describe the problem.
+    validations:
+      required: true
+
+  - type: textarea
+    id: example
+    attributes:
+      label: Example Code
+      description: >
+        If applicable, please provide a self-contained,
+        [minimal, reproducible example](https://stackoverflow.com/help/minimal-reproducible-example)
+        demonstrating the bug. If possible, your example should be a single-file script.
+
+      placeholder: |
+        import asyncio
+        from fastmcp import FastMCP, Client
+
+        mcp = FastMCP()
+
+        async def demo():
+            async with Client(mcp) as client:
+                ... # show the bug here
+
+        if __name__ == "__main__":
+            asyncio.run(demo())
+      render: Python
+
+  - type: textarea
+    id: version
+    attributes:
+      label: Version Information
+      description: |
+        Please tell us about your FastMCP version, MCP version, Python version, and OS, as well as any other relevant details about your environment.
+
+        To get the basic information, run the following command in your terminal and paste the output below:
+
+        ```bash
+        fastmcp version --copy
+        ```
+      render: Text
+    validations:
+      required: true
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..7c4bef5
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: FastMCP Documentation
+    url: https://gofastmcp.com
+    about: Please review the documentation before opening an issue.
+  - name: MCP Python SDK
+    url: https://github.com/modelcontextprotocol/python-sdk/issues
+    about: Issues related to the low-level MCP Python SDK, including the FastMCP 1.0 module that is included in the `mcp` package, should be filed on the official MCP repository.
diff --git a/.github/ISSUE_TEMPLATE/enhancement.yml b/.github/ISSUE_TEMPLATE/enhancement.yml
new file mode 100644
index 0000000..39c6664
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/enhancement.yml
@@ -0,0 +1,29 @@
+name: 💡 Enhancement Request
+description: Suggest an idea or improvement for FastMCP
+labels: [enhancement, pending]
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting an improvement to FastMCP!
+
+        Enhancement issues are the **primary way** features and improvements get into FastMCP. Maintainers use well-written issues to implement changes that fit the codebase's patterns and ship quickly. A clear issue here is more impactful than a PR — see [CONTRIBUTING.md](../../CONTRIBUTING.md) for why.
+
+        ### Before you submit
+
+        - 🔍 **Check if this has already been requested** — search existing issues first
+        - 🎯 **Describe the problem you're trying to solve**, not the solution you want — we'll figure out the best implementation
+        - ✂️ **Keep it short.** A motivating description and a concrete use case is the ideal request — aim to fit in a single screen. Skip proposed implementations, API designs, or multi-option analyses — maintainers will figure out the approach. Requests that are difficult to parse will be labeled `too-long` and not triaged until condensed.
+        - 🤖 **Using an LLM?** Great — but it must follow these guidelines. Generic LLM output that ignores our contributing conventions will be closed. See [CONTRIBUTING.md](../../CONTRIBUTING.md).
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Enhancement
+      description: |
+        What problem or use case does this solve? How does current behavior fall short?
+
+        Focus on the *what* and *why* — the motivating scenario. You don't need to propose an API or implementation.
+    validations:
+      required: true
diff --git a/.github/actions/run-claude/action.yml b/.github/actions/run-claude/action.yml
new file mode 100644
index 0000000..fff6788
--- /dev/null
+++ b/.github/actions/run-claude/action.yml
@@ -0,0 +1,95 @@
+# Composite Action for running Claude Code Action
+#
+# Wraps anthropics/claude-code-action with MCP server configuration.
+# Template based on elastic/ai-github-actions base action.
+#
+# Usage:
+#   - uses: ./.github/actions/run-claude
+#     with:
+#       prompt: "Your prompt here"
+#       claude-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+#       github-token: ${{ steps.marvin-token.outputs.token }}
+#       allowed-tools: "Edit,Read,Write,Bash(*),mcp__github__add_issue_comment"
+#
+name: "Run Claude"
+description: "Run Claude Code with MCP servers"
+author: "FastMCP"
+
+branding:
+  icon: "cpu"
+  color: "orange"
+
+inputs:
+  prompt:
+    description: "Prompt to pass to Claude"
+    required: true
+
+  claude-oauth-token:
+    description: "Claude Code OAuth token for authentication"
+    required: true
+
+  github-token:
+    description: "GitHub token for Claude to operate with"
+    required: true
+
+  allowed-tools:
+    description: "Comma-separated list of allowed tools (e.g. Edit,Write,Bash(npm test))"
+    required: false
+    default: ""
+
+  model:
+    description: "Model to use for Claude"
+    required: false
+    default: "claude-opus-4-6"
+
+  allowed-bots:
+    description: "Allowed bot usernames, or '*' for all bots"
+    required: false
+    default: ""
+
+  track-progress:
+    description: "Whether Claude should track progress"
+    required: false
+    default: "true"
+
+  mcp-servers:
+    description: "MCP server configuration JSON"
+    required: false
+    default: '{"mcpServers":{"agents-md-generator":{"type":"http","url":"https://agents-md-generator.fastmcp.app/mcp"},"public-code-search":{"type":"http","url":"https://public-code-search.fastmcp.app/mcp"}}}'
+
+  trigger-phrase:
+    description: "Trigger phrase (for mention workflows)"
+    required: false
+    default: "/marvin"
+
+outputs:
+  conclusion:
+    description: "The conclusion of the Claude Code run"
+    value: ${{ steps.claude.outputs.conclusion }}
+
+runs:
+  using: "composite"
+  steps:
+    - name: Clean up stale Claude locks
+      shell: bash
+      run: rm -rf ~/.claude/.locks ~/.local/state/claude/locks || true
+
+    - name: Run Claude Code
+      id: claude
+      env:
+        GITHUB_TOKEN: ${{ inputs.github-token }}
+      uses: anthropics/claude-code-action@v1
+      with:
+        github_token: ${{ inputs.github-token }}
+        claude_code_oauth_token: ${{ inputs.claude-oauth-token }}
+        bot_name: "Marvin Context Protocol"
+        trigger_phrase: ${{ inputs.trigger-phrase }}
+        allowed_bots: ${{ inputs.allowed-bots }}
+        track_progress: ${{ inputs.track-progress }}
+        prompt: ${{ inputs.prompt }}
+        claude_args: |
+          ${{ (inputs.allowed-tools != '' || inputs.extra-allowed-tools != '') && format('--allowedTools {0}{1}', inputs.allowed-tools, inputs.extra-allowed-tools != '' && format(',{0}', inputs.extra-allowed-tools) || '') || '' }}
+          ${{ inputs.mcp-servers != '' && format('--mcp-config ''{0}''', inputs.mcp-servers) || '' }}
+          --model ${{ inputs.model }}
+        settings: |
+          {"model": "${{ inputs.model }}"}
diff --git a/.github/actions/run-pytest/action.yml b/.github/actions/run-pytest/action.yml
new file mode 100644
index 0000000..b7e5509
--- /dev/null
+++ b/.github/actions/run-pytest/action.yml
@@ -0,0 +1,50 @@
+name: "Run Pytest"
+description: "Run pytest with appropriate flags for the test type and platform"
+
+inputs:
+  test-type:
+    description: "Type of tests to run: unit, integration, client_process, or conformance"
+    required: false
+    default: "unit"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Run pytest
+      shell: bash
+      run: |
+        if [ "${{ inputs.test-type }}" == "integration" ]; then
+          MARKER="integration"
+          TIMEOUT="30"
+          MAX_PROCS="2"
+          EXTRA_FLAGS=""
+        elif [ "${{ inputs.test-type }}" == "client_process" ]; then
+          MARKER="client_process"
+          TIMEOUT="5"
+          MAX_PROCS="0"
+          EXTRA_FLAGS="-x"
+        elif [ "${{ inputs.test-type }}" == "conformance" ]; then
+          MARKER="conformance"
+          TIMEOUT="120"
+          MAX_PROCS="0"
+          EXTRA_FLAGS="-x"
+        else
+          MARKER="not integration and not client_process and not conformance"
+          TIMEOUT="5"
+          MAX_PROCS="4"
+          EXTRA_FLAGS=""
+        fi
+
+        PARALLEL_FLAGS=""
+        if [ "$MAX_PROCS" != "0" ] && [ "${{ runner.os }}" != "Windows" ]; then
+          PARALLEL_FLAGS="--numprocesses auto --maxprocesses $MAX_PROCS --dist worksteal"
+        fi
+
+        uv run --no-sync pytest \
+          --inline-snapshot=disable \
+          --timeout=$TIMEOUT \
+          --durations=50 \
+          -m "$MARKER" \
+          $PARALLEL_FLAGS \
+          $EXTRA_FLAGS \
+          tests
diff --git a/.github/actions/setup-uv/action.yml b/.github/actions/setup-uv/action.yml
new file mode 100644
index 0000000..0becaff
--- /dev/null
+++ b/.github/actions/setup-uv/action.yml
@@ -0,0 +1,33 @@
+name: "Setup UV Environment"
+description: "Install uv and dependencies (requires checkout first)"
+
+inputs:
+  python-version:
+    description: "Python version to use"
+    required: false
+    default: "3.10"
+  resolution:
+    description: "Dependency resolution: locked, upgrade, or lowest-direct"
+    required: false
+    default: "locked"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        enable-cache: true
+        cache-dependency-glob: "uv.lock"
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install dependencies
+      shell: bash
+      run: |
+        if [ "${{ inputs.resolution }}" == "locked" ]; then
+          uv sync --locked
+        elif [ "${{ inputs.resolution }}" == "upgrade" ]; then
+          uv sync --upgrade
+        else
+          uv sync --resolution ${{ inputs.resolution }}
+        fi
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 120000
index 0000000..be77ac8
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1 @@
+../AGENTS.md
\ No newline at end of file
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..20d3cce
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,14 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    labels:
+      - "dependencies"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..1b33337
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,22 @@
+## Description
+
+<!-- What does this PR do? Link to the issue it addresses. -->
+
+Closes #
+
+## Contribution type
+
+<!-- Check the one that applies. If you're unsure whether your change is welcome, please open an issue first — see CONTRIBUTING.md. -->
+
+- [ ] Bug fix (simple, well-scoped fix for a clearly broken behavior)
+- [ ] Documentation improvement
+- [ ] Enhancement (maintainers typically implement enhancements — see [CONTRIBUTING.md](../CONTRIBUTING.md))
+
+## Checklist
+
+- [ ] This PR addresses an existing issue (or fixes a self-evident bug)
+- [ ] I have read [CONTRIBUTING.md](../CONTRIBUTING.md)
+- [ ] I have added tests that cover my changes
+- [ ] I have run `uv run prek run --all-files` and all checks pass
+- [ ] I have self-reviewed my changes
+- [ ] If I used an LLM, it followed the repo's contributing conventions (not generic output)
diff --git a/.github/release.yml b/.github/release.yml
new file mode 100644
index 0000000..5397d75
--- /dev/null
+++ b/.github/release.yml
@@ -0,0 +1,57 @@
+changelog:
+  exclude:
+    labels:
+      - ignore in release notes
+
+  categories:
+    - title: New Features 🎉
+      labels:
+        - feature
+
+    - title: Breaking Changes ⚠️
+      labels:
+        - breaking change
+      exclude:
+        labels:
+          - contrib
+          - security
+
+    - title: Enhancements ✨
+      labels:
+        - enhancement
+      exclude:
+        labels:
+          - breaking change
+          - security
+
+    - title: Security 🔒
+      labels:
+        - security
+
+    - title: Fixes 🐞
+      labels:
+        - bug
+      exclude:
+        labels:
+          - contrib
+          - security
+
+    - title: Docs 📚
+      labels:
+        - documentation
+
+    - title: Examples & Contrib 💡
+      labels:
+        - example
+        - contrib
+
+    - title: Dependencies 📦
+      labels:
+        - dependencies
+      exclude:
+        labels:
+          - security
+
+    - title: Other Changes 🦾
+      labels:
+        - "*"
diff --git a/.github/scripts/mention/gh-get-review-threads.sh b/.github/scripts/mention/gh-get-review-threads.sh
new file mode 100755
index 0000000..2e1f4b3
--- /dev/null
+++ b/.github/scripts/mention/gh-get-review-threads.sh
@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Get PR review threads with comments via GitHub GraphQL API
+#
+# Usage:
+#   gh-get-review-threads.sh [FILTER]
+#
+# Arguments:
+#   FILTER - Optional: filter for unresolved threads from specific author
+#
+# Environment (set by composite action):
+#   MENTION_REPO      - Repository (owner/repo format)
+#   MENTION_PR_NUMBER - Pull request number
+#   GITHUB_TOKEN      - GitHub API token
+#
+# Output:
+#   JSON array of review threads with nested comments
+
+# Parse OWNER and REPO from MENTION_REPO
+REPO_FULL="${MENTION_REPO:?MENTION_REPO environment variable is required}"
+OWNER="${REPO_FULL%/*}"
+REPO="${REPO_FULL#*/}"
+PR_NUMBER="${MENTION_PR_NUMBER:?MENTION_PR_NUMBER environment variable is required}"
+FILTER="${1:-}"
+
+gh api graphql -f query='
+  query($owner: String!, $repo: String!, $prNumber: Int!) {
+    repository(owner: $owner, name: $repo) {
+      pullRequest(number: $prNumber) {
+        reviewThreads(first: 100) {
+          nodes {
+            id
+            isResolved
+            isOutdated
+            path
+            line
+            comments(first: 50) {
+              nodes {
+                id
+                body
+                author { login }
+                createdAt
+              }
+            }
+          }
+        }
+      }
+    }
+  }' -F owner="$OWNER" \
+     -F repo="$REPO" \
+     -F prNumber="$PR_NUMBER" \
+     --jq '.data.repository.pullRequest.reviewThreads.nodes' | \
+if [ -n "$FILTER" ]; then
+  jq --arg author "$FILTER" '
+    map(select(
+      .isResolved == false and
+      .comments.nodes | any(.author.login == $author)
+    ))'
+else
+  cat
+fi
diff --git a/.github/scripts/mention/gh-resolve-review-thread.sh b/.github/scripts/mention/gh-resolve-review-thread.sh
new file mode 100755
index 0000000..5dc08c2
--- /dev/null
+++ b/.github/scripts/mention/gh-resolve-review-thread.sh
@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Resolve a GitHub PR review thread, optionally posting a comment first
+#
+# Usage:
+#   gh-resolve-review-thread.sh THREAD_ID [COMMENT]
+#
+# Arguments:
+#   THREAD_ID - The GraphQL node ID of the review thread to resolve
+#   COMMENT   - Optional: Comment body to post before resolving
+#
+# Environment (set by composite action):
+#   MENTION_REPO      - Repository (owner/repo format)
+#   MENTION_PR_NUMBER - Pull request number
+#   GITHUB_TOKEN      - GitHub API token
+#
+# Behavior:
+#   1. If COMMENT is provided, posts it as a reply to the thread
+#   2. Resolves the thread
+
+# Validate required environment variables
+: "${MENTION_REPO:?MENTION_REPO environment variable is required}"
+: "${MENTION_PR_NUMBER:?MENTION_PR_NUMBER environment variable is required}"
+THREAD_ID="${1:?Thread ID required}"
+COMMENT="${2:-}"
+
+# Step 1: Post comment if provided
+if [ -n "$COMMENT" ]; then
+  echo "Posting comment to thread..." >&2
+  COMMENT_RESULT=$(gh api graphql -f query='
+    mutation($threadId: ID!, $body: String!) {
+      addPullRequestReviewThreadReply(input: {
+        pullRequestReviewThreadId: $threadId,
+        body: $body
+      }) {
+        comment {
+          id
+        }
+      }
+    }' -f threadId="$THREAD_ID" -f body="$COMMENT")
+  if echo "$COMMENT_RESULT" | jq -e '.errors' > /dev/null 2>&1; then
+    echo "Error posting comment: $COMMENT_RESULT" >&2
+    exit 1
+  fi
+fi
+
+# Step 2: Resolve the thread
+echo "Resolving thread..." >&2
+RESOLVE_RESULT=$(gh api graphql -f query='
+  mutation($threadId: ID!) {
+    resolveReviewThread(input: {threadId: $threadId}) {
+      thread {
+        id
+        isResolved
+      }
+    }
+  }' -f threadId="$THREAD_ID" --jq '.data.resolveReviewThread.thread')
+
+echo "$RESOLVE_RESULT"
+echo "✓ Thread resolved" >&2
diff --git a/.github/scripts/pr-review/pr-comment.sh b/.github/scripts/pr-review/pr-comment.sh
new file mode 100755
index 0000000..d571f67
--- /dev/null
+++ b/.github/scripts/pr-review/pr-comment.sh
@@ -0,0 +1,251 @@
+#!/bin/bash
+# pr-comment.sh - Queue a structured inline review comment for the PR review
+#
+# Usage:
+#   pr-comment.sh <file> <line> --severity <level> --title <description> --why <reason> [suggestion via stdin]
+#   pr-comment.sh <file> <line> --severity <level> --title <description> --why <reason> --no-suggestion
+#
+# Arguments:
+#   file              File path (required)
+#   line              Line number (required)
+#   --severity        Severity level: critical, high, medium, low, nitpick (required)
+#   --title           Brief description for comment heading (required)
+#   --why             One sentence explaining the risk/impact (required)
+#   --no-suggestion   Explicitly skip suggestion (use for architectural issues)
+#
+# The suggestion code is read from stdin (use heredoc). If no stdin and no --no-suggestion, errors.
+#
+# Examples:
+#   # With suggestion (preferred)
+#   pr-comment.sh src/main.go 42 --severity high --title "Missing error check" --why "Errors are silently ignored" <<'EOF'
+#   if err != nil {
+#       return fmt.Errorf("operation failed: %w", err)
+#   }
+#   EOF
+#
+#   # Without suggestion (for issues requiring broader changes)
+#   pr-comment.sh src/main.go 42 --severity medium --title "Consider extracting to function" \
+#     --why "This logic is duplicated in 3 places" --no-suggestion
+#
+# Environment variables (set by the composite action):
+#   PR_REVIEW_REPO          - Repository (owner/repo)
+#   PR_REVIEW_PR_NUMBER     - Pull request number
+#   PR_REVIEW_COMMENTS_DIR  - Directory to cache comments (default: /tmp/pr-review-comments)
+
+set -e
+
+# Configuration from environment
+REPO="${PR_REVIEW_REPO:?PR_REVIEW_REPO environment variable is required}"
+PR_NUMBER="${PR_REVIEW_PR_NUMBER:?PR_REVIEW_PR_NUMBER environment variable is required}"
+COMMENTS_DIR="${PR_REVIEW_COMMENTS_DIR:-/tmp/pr-review-comments}"
+
+# Severity emoji mapping
+declare -A SEVERITY_EMOJI=(
+  [critical]="🔴 CRITICAL"
+  [high]="🟠 HIGH"
+  [medium]="🟡 MEDIUM"
+  [low]="⚪ LOW"
+  [nitpick]="💬 NITPICK"
+)
+
+# Parse arguments
+FILE=""
+LINE=""
+SEVERITY=""
+TITLE=""
+WHY=""
+NO_SUGGESTION=false
+
+# First two positional args are file and line
+if [ $# -lt 2 ]; then
+  echo "Error: file and line are required"
+  echo "Usage: pr-comment.sh <file> <line> --severity <level> --title <desc> --why <reason> [<<'EOF' ... EOF]"
+  exit 1
+fi
+
+FILE="$1"
+LINE="$2"
+shift 2
+
+# Parse named arguments
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --severity)
+      SEVERITY="$2"
+      shift 2
+      ;;
+    --title)
+      TITLE="$2"
+      shift 2
+      ;;
+    --why)
+      WHY="$2"
+      shift 2
+      ;;
+    --no-suggestion)
+      NO_SUGGESTION=true
+      shift
+      ;;
+    *)
+      echo "Error: Unknown argument: $1"
+      exit 1
+      ;;
+  esac
+done
+
+# Read suggestion from stdin if available
+SUGGESTION=""
+if [ ! -t 0 ]; then
+  SUGGESTION=$(cat)
+fi
+
+# Validate required arguments
+if [ -z "$SEVERITY" ]; then
+  echo "Error: --severity is required (critical, high, medium, low, nitpick)"
+  exit 1
+fi
+
+if [ -z "$TITLE" ]; then
+  echo "Error: --title is required"
+  exit 1
+fi
+
+if [ -z "$WHY" ]; then
+  echo "Error: --why is required"
+  exit 1
+fi
+
+# Validate severity level
+if [ -z "${SEVERITY_EMOJI[$SEVERITY]}" ]; then
+  echo "Error: Invalid severity '$SEVERITY'. Must be one of: critical, high, medium, low, nitpick"
+  exit 1
+fi
+
+# Require either suggestion or explicit --no-suggestion
+if [ -z "$SUGGESTION" ] && [ "$NO_SUGGESTION" = false ]; then
+  echo "Error: Suggestion required. Provide code via stdin (heredoc) or use --no-suggestion"
+  echo ""
+  echo "Example with suggestion:"
+  echo "  pr-comment.sh file.go 42 --severity high --title \"desc\" --why \"reason\" <<'EOF'"
+  echo "  fixed code here"
+  echo "  EOF"
+  echo ""
+  echo "Example without suggestion:"
+  echo "  pr-comment.sh file.go 42 --severity medium --title \"desc\" --why \"reason\" --no-suggestion"
+  exit 1
+fi
+
+# Validate line is a positive integer (>= 1)
+if ! [[ "$LINE" =~ ^[1-9][0-9]*$ ]]; then
+  echo "Error: Line number must be a positive integer (>= 1), got: $LINE"
+  exit 1
+fi
+
+# Get the diff for this file to validate the comment location
+DIFF_DATA=$(gh api "repos/${REPO}/pulls/${PR_NUMBER}/files" --paginate | jq --arg f "$FILE" '.[] | select(.filename==$f)')
+
+if [ -z "$DIFF_DATA" ]; then
+  echo "Error: File '${FILE}' not found in PR diff"
+  echo ""
+  echo "Files changed in this PR:"
+  gh api "repos/${REPO}/pulls/${PR_NUMBER}/files" --paginate --jq '.[].filename'
+  exit 1
+fi
+
+PATCH=$(echo "$DIFF_DATA" | jq -r '.patch // empty')
+
+if [ -z "$PATCH" ]; then
+  echo "Error: No patch data for file '${FILE}' (file may be binary or too large)"
+  exit 1
+fi
+
+# Verify the line exists in the diff
+LINE_IN_DIFF=$(echo "$PATCH" | awk -v target_line="$LINE" '
+BEGIN { current_line = 0; found = 0 }
+/^@@/ {
+  line = $0
+  gsub(/.*\+/, "", line)
+  gsub(/[^0-9].*/, "", line)
+  current_line = line - 1
+  next
+}
+{
+  if (substr($0, 1, 1) != "-") {
+    current_line++
+    if (current_line == target_line) {
+      found = 1
+      exit
+    }
+  }
+}
+END { if (found) print "1"; else print "0" }
+')
+
+if [ "$LINE_IN_DIFF" != "1" ]; then
+  echo "Error: Line ${LINE} not found in the diff for '${FILE}'"
+  echo ""
+  echo "Note: You can only comment on lines that appear in the diff (added, modified, or context lines)"
+  echo ""
+  echo "First 50 lines of diff for this file:"
+  echo "$PATCH" | head -50
+  exit 1
+fi
+
+# Create comments directory if it doesn't exist
+mkdir -p "${COMMENTS_DIR}"
+
+# Assemble the comment body
+SEVERITY_LABEL="${SEVERITY_EMOJI[$SEVERITY]}"
+
+BODY="**${SEVERITY_LABEL}** ${TITLE}
+
+Why: ${WHY}"
+
+# Add suggestion block if provided
+if [ -n "$SUGGESTION" ]; then
+  BODY="${BODY}
+
+\`\`\`suggestion
+${SUGGESTION}
+\`\`\`"
+fi
+
+# Append standard footer
+FOOTER='
+
+---
+Marvin Context Protocol | Type `/marvin` to interact further
+
+Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.'
+
+BODY_WITH_FOOTER="${BODY}${FOOTER}"
+
+# Generate unique comment ID
+COMMENT_ID="comment-$(date +%s)-$(od -An -N4 -tu4 /dev/urandom | tr -d ' ')"
+COMMENT_FILE="${COMMENTS_DIR}/${COMMENT_ID}.json"
+
+# Create the comment JSON object
+jq -n \
+  --arg path "$FILE" \
+  --argjson line "$LINE" \
+  --arg side "RIGHT" \
+  --arg body "$BODY_WITH_FOOTER" \
+  --arg id "$COMMENT_ID" \
+  '{
+    path: $path,
+    line: $line,
+    side: $side,
+    body: $body,
+    _meta: {
+      id: $id,
+      file: $path,
+      line: $line
+    }
+  }' > "${COMMENT_FILE}"
+
+echo "✓ Queued review comment for ${FILE}:${LINE}"
+echo "  Severity: ${SEVERITY_LABEL}"
+echo "  Title: ${TITLE}"
+echo "  Comment ID: ${COMMENT_ID}"
+echo "  Comment will be submitted with pr-review.sh"
+echo "  Remove with: pr-remove-comment.sh ${FILE} ${LINE}"
diff --git a/.github/scripts/pr-review/pr-diff.sh b/.github/scripts/pr-review/pr-diff.sh
new file mode 100755
index 0000000..4448e00
--- /dev/null
+++ b/.github/scripts/pr-review/pr-diff.sh
@@ -0,0 +1,128 @@
+#!/bin/bash
+# pr-diff.sh - Show changed files or diff for a specific file
+#
+# Usage: 
+#   pr-diff.sh           - List all changed files (shows full diff if small enough)
+#   pr-diff.sh <file>    - Show diff for a specific file with line numbers
+#
+# Environment variables (set by the composite action):
+#   PR_REVIEW_REPO       - Repository (owner/repo)
+#   PR_REVIEW_PR_NUMBER  - Pull request number
+
+set -e
+
+# Configuration from environment
+REPO="${PR_REVIEW_REPO:?PR_REVIEW_REPO environment variable is required}"
+PR_NUMBER="${PR_REVIEW_PR_NUMBER:?PR_REVIEW_PR_NUMBER environment variable is required}"
+EXPECTED_HEAD="${PR_REVIEW_HEAD_SHA:-}"
+
+# Check if HEAD has changed since review started (race condition detection)
+if [ -n "$EXPECTED_HEAD" ]; then
+  CURRENT_HEAD=$(gh api "repos/${REPO}/pulls/${PR_NUMBER}" --jq '.head.sha')
+  if [ "$CURRENT_HEAD" != "$EXPECTED_HEAD" ]; then
+    echo "⚠️  WARNING: PR head has changed since review started!"
+    echo "   Review started at: ${EXPECTED_HEAD:0:7}"
+    echo "   Current head:      ${CURRENT_HEAD:0:7}"
+    echo "   Line numbers below may not match the commit being reviewed."
+    echo ""
+  fi
+fi
+
+# Thresholds for "too big" - show file list only if exceeded
+MAX_FILES=25
+MAX_TOTAL_LINES=1500
+
+FILE="$1"
+
+# Function to add line numbers to a patch
+# Format: [LINE] +added | [LINE]  context | [----] -deleted
+add_line_numbers() {
+  awk '
+  BEGIN { new_line = 0 }
+  /^@@/ {
+    # Parse hunk header: @@ -old_start,old_count +new_start,new_count @@
+    match($0, /\+([0-9]+)/)
+    new_line = substr($0, RSTART+1, RLENGTH-1) - 1
+    print ""
+    print $0
+    next
+  }
+  /^-/ {
+    # Deleted line - cannot comment on these
+    printf "[----] %s\n", $0
+    next
+  }
+  /^\+/ {
+    # Added line - can comment, show line number
+    new_line++
+    printf "[%4d] %s\n", new_line, $0
+    next
+  }
+  {
+    # Context line (space prefix) - can comment, show line number
+    new_line++
+    printf "[%4d] %s\n", new_line, $0
+  }
+  '
+}
+
+if [ -z "$FILE" ]; then
+  # Get file list with stats
+  FILES_DATA=$(gh api "repos/${REPO}/pulls/${PR_NUMBER}/files" --paginate)
+  
+  FILE_COUNT=$(echo "$FILES_DATA" | jq 'length')
+  TOTAL_ADDITIONS=$(echo "$FILES_DATA" | jq '[.[].additions] | add // 0')
+  TOTAL_DELETIONS=$(echo "$FILES_DATA" | jq '[.[].deletions] | add // 0')
+  TOTAL_LINES=$((TOTAL_ADDITIONS + TOTAL_DELETIONS))
+  
+  echo "PR #${PR_NUMBER} Summary: ${FILE_COUNT} files changed (+${TOTAL_ADDITIONS}/-${TOTAL_DELETIONS})"
+  echo ""
+  
+  # Check if diff is too large
+  if [ "$FILE_COUNT" -gt "$MAX_FILES" ] || [ "$TOTAL_LINES" -gt "$MAX_TOTAL_LINES" ]; then
+    echo "⚠️  Large diff detected (>${MAX_FILES} files or >${MAX_TOTAL_LINES} lines changed)"
+    echo "   Review files individually using: pr-diff.sh <filename>"
+    echo ""
+    echo "Files changed:"
+    echo "$FILES_DATA" | jq -r '.[] | "  \(.filename) (+\(.additions)/-\(.deletions))"'
+  else
+    # Small enough - show all diffs with line numbers
+    echo "Files changed:"
+    echo "$FILES_DATA" | jq -r '.[] | "  \(.filename) (+\(.additions)/-\(.deletions))"'
+    echo ""
+    echo "─────────────────────────────────────────────────────────────────────"
+    echo ""
+    
+    # Show each file's diff by iterating over indices
+    for i in $(seq 0 $((FILE_COUNT - 1))); do
+      FNAME=$(echo "$FILES_DATA" | jq -r ".[$i].filename")
+      PATCH=$(echo "$FILES_DATA" | jq -r ".[$i].patch // empty")
+      
+      if [ -n "$PATCH" ]; then
+        echo "## ${FNAME}"
+        echo "Use: pr-comment.sh ${FNAME} <LINE> --severity <level> --title \"desc\" --why \"reason\" <<'EOF' ... EOF"
+        echo "Format: [LINE] +added | [LINE] context | [----] -deleted (can't comment)"
+        echo "$PATCH" | add_line_numbers
+        echo ""
+        echo "─────────────────────────────────────────────────────────────────────"
+        echo ""
+      fi
+    done
+  fi
+else
+  # Show specific file diff
+  PATCH=$(gh api "repos/${REPO}/pulls/${PR_NUMBER}/files" --paginate --jq --arg file "$FILE" '.[] | select(.filename==$file) | .patch')
+  
+  if [ -z "$PATCH" ]; then
+    echo "Error: File '${FILE}' not found in PR diff"
+    echo ""
+    echo "Files changed in this PR:"
+    gh api "repos/${REPO}/pulls/${PR_NUMBER}/files" --paginate --jq '.[].filename'
+    exit 1
+  fi
+  
+  echo "## ${FILE}"
+  echo "Use: pr-comment.sh ${FILE} <LINE> --severity <level> --title \"desc\" --why \"reason\" <<'EOF' ... EOF"
+  echo "Format: [LINE] +added | [LINE] context | [----] -deleted (can't comment)"
+  echo "$PATCH" | add_line_numbers
+fi
diff --git a/.github/scripts/pr-review/pr-existing-comments.sh b/.github/scripts/pr-review/pr-existing-comments.sh
new file mode 100755
index 0000000..10fa05f
--- /dev/null
+++ b/.github/scripts/pr-review/pr-existing-comments.sh
@@ -0,0 +1,190 @@
+#!/bin/bash
+# pr-existing-comments.sh - Fetch existing review threads on a PR
+#
+# Usage:
+#   pr-existing-comments.sh              - Show all review threads with full details
+#   pr-existing-comments.sh --summary    - Show per-file summary only (for large PRs)
+#   pr-existing-comments.sh --unresolved - Show only unresolved threads
+#   pr-existing-comments.sh --file <path> - Show threads for a specific file
+#   pr-existing-comments.sh --full       - Show full comment text (no truncation)
+#
+# Output: Formatted summary of existing review threads grouped by file,
+# showing thread status, comments, and whether issues were addressed.
+#
+# For large PRs, use --summary first to see the overview, then --file <path>
+# to get full thread details when reviewing each file.
+#
+# Environment variables (set by the composite action):
+#   PR_REVIEW_REPO       - Repository (owner/repo)
+#   PR_REVIEW_PR_NUMBER  - Pull request number
+
+set -e
+
+# Configuration from environment
+REPO="${PR_REVIEW_REPO:?PR_REVIEW_REPO environment variable is required}"
+PR_NUMBER="${PR_REVIEW_PR_NUMBER:?PR_REVIEW_PR_NUMBER environment variable is required}"
+
+OWNER="${REPO%/*}"
+REPO_NAME="${REPO#*/}"
+
+# Parse arguments
+FILTER_UNRESOLVED=false
+FILTER_FILE=""
+SUMMARY_ONLY=false
+FULL_TEXT=false
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --unresolved)
+      FILTER_UNRESOLVED=true
+      shift
+      ;;
+    --file)
+      FILTER_FILE="$2"
+      shift 2
+      ;;
+    --summary)
+      SUMMARY_ONLY=true
+      shift
+      ;;
+    --full)
+      FULL_TEXT=true
+      shift
+      ;;
+    *)
+      echo "Usage: pr-existing-comments.sh [--summary] [--unresolved] [--file <path>] [--full]"
+      exit 1
+      ;;
+  esac
+done
+
+# Fetch review threads via GraphQL
+THREADS=$(gh api graphql -f query='
+  query($owner: String!, $repo: String!, $prNumber: Int!) {
+    repository(owner: $owner, name: $repo) {
+      pullRequest(number: $prNumber) {
+        reviewThreads(first: 100) {
+          nodes {
+            id
+            isResolved
+            isOutdated
+            path
+            line
+            originalLine
+            startLine
+            originalStartLine
+            diffSide
+            comments(first: 50) {
+              nodes {
+                id
+                body
+                author { login }
+                createdAt
+                originalCommit { abbreviatedOid }
+              }
+            }
+          }
+        }
+      }
+    }
+  }' -F owner="$OWNER" \
+     -F repo="$REPO_NAME" \
+     -F prNumber="$PR_NUMBER" \
+     --jq '.data.repository.pullRequest.reviewThreads.nodes')
+
+if [ -z "$THREADS" ] || [ "$THREADS" = "null" ]; then
+  echo "No existing review threads found."
+  exit 0
+fi
+
+# Apply filters
+FILTERED="$THREADS"
+
+if [ "$FILTER_UNRESOLVED" = true ]; then
+  FILTERED=$(echo "$FILTERED" | jq '[.[] | select(.isResolved == false)]')
+fi
+
+if [ -n "$FILTER_FILE" ]; then
+  FILTERED=$(echo "$FILTERED" | jq --arg file "$FILTER_FILE" '[.[] | select(.path == $file)]')
+fi
+
+THREAD_COUNT=$(echo "$FILTERED" | jq 'length')
+
+if [ "$THREAD_COUNT" -eq 0 ]; then
+  if [ "$FILTER_UNRESOLVED" = true ]; then
+    echo "No unresolved review threads found."
+  elif [ -n "$FILTER_FILE" ]; then
+    echo "No review threads found for ${FILTER_FILE}."
+  else
+    echo "No existing review threads found."
+  fi
+  exit 0
+fi
+
+# Count resolved vs unresolved
+RESOLVED_COUNT=$(echo "$FILTERED" | jq '[.[] | select(.isResolved == true)] | length')
+UNRESOLVED_COUNT=$(echo "$FILTERED" | jq '[.[] | select(.isResolved == false)] | length')
+OUTDATED_COUNT=$(echo "$FILTERED" | jq '[.[] | select(.isOutdated == true)] | length')
+
+echo "Existing review threads: ${THREAD_COUNT} total (${UNRESOLVED_COUNT} unresolved, ${RESOLVED_COUNT} resolved, ${OUTDATED_COUNT} outdated)"
+echo ""
+
+# Summary mode: show per-file counts only
+if [ "$SUMMARY_ONLY" = true ]; then
+  echo "Threads by file:"
+  echo "$FILTERED" | jq -r '
+    group_by(.path) | .[] |
+    . as $threads |
+    ($threads | length) as $total |
+    ([$threads[] | select(.isResolved == false)] | length) as $unresolved |
+    ([$threads[] | select(.isResolved == true)] | length) as $resolved |
+    ([$threads[] | select(.isOutdated == true)] | length) as $outdated |
+    ([$threads[] | select(.comments.nodes | length > 1)] | length) as $has_replies |
+    "  " + $threads[0].path +
+    " — " + ($total | tostring) + " threads" +
+    " (" + ($unresolved | tostring) + " unresolved, " + ($resolved | tostring) + " resolved" +
+    (if $outdated > 0 then ", " + ($outdated | tostring) + " outdated" else "" end) +
+    ")" +
+    (if $has_replies > 0 then " ⚠️ " + ($has_replies | tostring) + " with replies" else "" end)
+  '
+  echo ""
+  echo "Use: pr-existing-comments.sh --file <path>  to see full thread details for a file"
+  exit 0
+fi
+
+# Full detail mode: output threads grouped by file
+# Show full conversation for threads with replies
+FIRST_LIMIT=200
+REPLY_LIMIT=300
+if [ "$FULL_TEXT" = true ]; then
+  FIRST_LIMIT=999999
+  REPLY_LIMIT=999999
+fi
+
+echo "$FILTERED" | jq -r --argjson first_limit "$FIRST_LIMIT" --argjson reply_limit "$REPLY_LIMIT" '
+  group_by(.path) | .[] |
+  "## " + .[0].path + " (" + (length | tostring) + " threads)\n" +
+  ([.[] |
+    "  " +
+    (if .isResolved then "✅ RESOLVED" elif .isOutdated then "⚠️  OUTDATED" else "🔴 UNRESOLVED" end) +
+    " (line " + (if .line then (.line | tostring) elif .startLine then (.startLine | tostring) elif .originalLine then ("~" + (.originalLine | tostring)) elif .originalStartLine then ("~" + (.originalStartLine | tostring)) else "?" end) + ")" +
+    # Show the commit the comment was originally made on
+    (if .comments.nodes[0].originalCommit.abbreviatedOid then " [" + .comments.nodes[0].originalCommit.abbreviatedOid + "]" else "" end) +
+    # Flag threads with replies — indicates a conversation happened
+    (if (.comments.nodes | length) > 1 then " ← has replies" else "" end) +
+    "\n" +
+    ([.comments.nodes | to_entries[] |
+      .value as $comment |
+      .key as $idx |
+      ($comment.body | gsub("\n"; " ")) as $flat |
+      if $idx == 0 then
+        "    @" + ($comment.author.login // "unknown") + ": " + $flat[0:$first_limit] +
+        (if ($flat | length) > $first_limit then " [truncated]" else "" end)
+      else
+        "    ↳ @" + ($comment.author.login // "unknown") + ": " + $flat[0:$reply_limit] +
+        (if ($flat | length) > $reply_limit then " [truncated]" else "" end)
+      end
+    ] | join("\n")) +
+    "\n"
+  ] | join("\n"))
+'
diff --git a/.github/scripts/pr-review/pr-remove-comment.sh b/.github/scripts/pr-review/pr-remove-comment.sh
new file mode 100755
index 0000000..04b73fb
--- /dev/null
+++ b/.github/scripts/pr-review/pr-remove-comment.sh
@@ -0,0 +1,84 @@
+#!/bin/bash
+# pr-remove-comment.sh - Remove a queued review comment
+#
+# Usage:
+#   pr-remove-comment.sh <file> <line-number>
+#   pr-remove-comment.sh <comment-id>
+#
+# Examples:
+#   pr-remove-comment.sh src/main.go 42
+#   pr-remove-comment.sh comment-1234567890-1234567890
+#
+# This script removes a previously queued comment before it's submitted.
+# Useful if the agent realizes it made a mistake or wants to update a comment.
+#
+# Environment variables (set by the composite action):
+#   PR_REVIEW_COMMENTS_DIR - Directory containing comment files (default: /tmp/pr-review-comments)
+
+set -e
+
+COMMENTS_DIR="${PR_REVIEW_COMMENTS_DIR:-/tmp/pr-review-comments}"
+
+if [ ! -d "${COMMENTS_DIR}" ]; then
+  echo "No comments directory found: ${COMMENTS_DIR}"
+  exit 0
+fi
+
+# Check if first argument looks like a comment ID
+if [[ "$1" =~ ^comment- ]]; then
+  COMMENT_ID="$1"
+  COMMENT_FILE="${COMMENTS_DIR}/${COMMENT_ID}.json"
+  
+  if [ -f "${COMMENT_FILE}" ]; then
+    FILE=$(jq -r '._meta.file // .path' "${COMMENT_FILE}")
+    LINE=$(jq -r '._meta.line // .line' "${COMMENT_FILE}")
+    rm -f "${COMMENT_FILE}"
+    echo "✓ Removed comment ${COMMENT_ID} for ${FILE}:${LINE}"
+  else
+    echo "Comment not found: ${COMMENT_ID}"
+    exit 1
+  fi
+else
+  # Treat as file and line number
+  FILE="$1"
+  LINE="$2"
+  
+  if [ -z "$FILE" ] || [ -z "$LINE" ]; then
+    echo "Usage:"
+    echo "  pr-remove-comment.sh <file> <line-number>"
+    echo "  pr-remove-comment.sh <comment-id>"
+    echo ""
+    echo "Examples:"
+    echo "  pr-remove-comment.sh src/main.go 42"
+    echo "  pr-remove-comment.sh comment-1234567890-1234567890"
+    exit 1
+  fi
+  
+  # Validate line is a positive integer (>= 1)
+  if ! [[ "$LINE" =~ ^[1-9][0-9]*$ ]]; then
+    echo "Error: Line number must be a positive integer (>= 1), got: $LINE"
+    exit 1
+  fi
+  
+  # Find and remove matching comment files
+  # Use nullglob to handle case where no files match
+  shopt -s nullglob
+  REMOVED=0
+  for COMMENT_FILE in "${COMMENTS_DIR}"/comment-*.json; do
+    
+    COMMENT_FILE_PATH=$(jq -r '._meta.file // .path' "${COMMENT_FILE}")
+    COMMENT_LINE=$(jq -r '._meta.line // .line' "${COMMENT_FILE}")
+    
+    if [ "$COMMENT_FILE_PATH" = "$FILE" ] && [ "$COMMENT_LINE" = "$LINE" ]; then
+      COMMENT_ID=$(basename "${COMMENT_FILE}" .json)
+      rm -f "${COMMENT_FILE}"
+      echo "✓ Removed comment ${COMMENT_ID} for ${FILE}:${LINE}"
+      REMOVED=$((REMOVED + 1))
+    fi
+  done
+  
+  if [ "$REMOVED" -eq 0 ]; then
+    echo "No comment found for ${FILE}:${LINE}"
+    exit 1
+  fi
+fi
diff --git a/.github/scripts/pr-review/pr-review.sh b/.github/scripts/pr-review/pr-review.sh
new file mode 100755
index 0000000..48c0b68
--- /dev/null
+++ b/.github/scripts/pr-review/pr-review.sh
@@ -0,0 +1,143 @@
+#!/bin/bash
+# pr-review.sh - Submit a PR review (approve, request changes, or comment)
+#
+# Usage: pr-review.sh <APPROVE|REQUEST_CHANGES|COMMENT> [review-body]
+# Example: pr-review.sh REQUEST_CHANGES "Please fix the issues noted above"
+#
+# This script creates and submits a review with any queued inline comments.
+# Comments are read from individual files in PR_REVIEW_COMMENTS_DIR (created by pr-comment.sh).
+#
+# The review body can contain special characters (backticks, dollar signs, etc.)
+# and will be safely passed to the GitHub API without shell interpretation.
+#
+# Environment variables (set by the composite action):
+#   PR_REVIEW_REPO          - Repository (owner/repo)
+#   PR_REVIEW_PR_NUMBER     - Pull request number
+#   PR_REVIEW_HEAD_SHA      - HEAD commit SHA
+#   PR_REVIEW_COMMENTS_DIR  - Directory containing queued comment files (default: /tmp/pr-review-comments)
+
+set -e
+
+# Configuration from environment
+REPO="${PR_REVIEW_REPO:?PR_REVIEW_REPO environment variable is required}"
+PR_NUMBER="${PR_REVIEW_PR_NUMBER:?PR_REVIEW_PR_NUMBER environment variable is required}"
+HEAD_SHA="${PR_REVIEW_HEAD_SHA:?PR_REVIEW_HEAD_SHA environment variable is required}"
+COMMENTS_DIR="${PR_REVIEW_COMMENTS_DIR:-/tmp/pr-review-comments}"
+
+# Arguments
+EVENT="$1"
+shift 2>/dev/null || true
+
+# Read body from remaining arguments
+# Join all remaining arguments with spaces, preserving the string as-is
+BODY="$*"
+
+if [ -z "$EVENT" ]; then
+  echo "Usage: pr-review.sh <APPROVE|REQUEST_CHANGES|COMMENT> [review-body]"
+  echo "Example: pr-review.sh REQUEST_CHANGES 'Please fix the issues noted in the inline comments'"
+  exit 1
+fi
+
+# Validate event type
+case "$EVENT" in
+  APPROVE|REQUEST_CHANGES|COMMENT)
+    ;;
+  *)
+    echo "Error: Invalid event type '${EVENT}'"
+    echo "Must be one of: APPROVE, REQUEST_CHANGES, COMMENT"
+    exit 1
+    ;;
+esac
+
+# Read queued comments from individual files
+COMMENTS="[]"
+COMMENT_COUNT=0
+
+if [ -d "${COMMENTS_DIR}" ]; then
+  # Collect all comment files and merge into a single JSON array
+  # Remove _meta fields before submitting (they're only for internal use)
+  COMMENT_FILES=("${COMMENTS_DIR}"/comment-*.json)
+  
+  if [ -f "${COMMENT_FILES[0]}" ]; then
+    # Use jq to read all comment files, extract the comment data (without _meta), and combine
+    COMMENTS=$(jq -s '[.[] | del(._meta)]' "${COMMENTS_DIR}"/comment-*.json)
+    COMMENT_COUNT=$(echo "$COMMENTS" | jq 'length')
+    if [ "$COMMENT_COUNT" -gt 0 ]; then
+      echo "Found ${COMMENT_COUNT} queued inline comment(s)"
+    fi
+  fi
+fi
+
+# Append standard footer to the review body (if body is provided)
+FOOTER='
+
+---
+Marvin Context Protocol | Type `/marvin` to interact further
+
+Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.'
+
+if [ -n "$BODY" ]; then
+  BODY_WITH_FOOTER="${BODY}${FOOTER}"
+else
+  BODY_WITH_FOOTER=""
+fi
+
+# Build the review request JSON
+# Use jq to safely construct the JSON with all special characters handled
+REVIEW_JSON=$(jq -n \
+  --arg commit_id "$HEAD_SHA" \
+  --arg event "$EVENT" \
+  --arg body "$BODY_WITH_FOOTER" \
+  --argjson comments "$COMMENTS" \
+  '{
+    commit_id: $commit_id,
+    event: $event,
+    comments: $comments
+  } + (if $body != "" then {body: $body} else {} end)')
+
+# Check if HEAD has changed since review started (race condition detection)
+CURRENT_HEAD=$(gh api "repos/${REPO}/pulls/${PR_NUMBER}" --jq '.head.sha')
+if [ "$CURRENT_HEAD" != "$HEAD_SHA" ]; then
+  echo "⚠️  WARNING: PR head has changed since review started!"
+  echo "   Review started at: ${HEAD_SHA:0:7}"
+  echo "   Current head:      ${CURRENT_HEAD:0:7}"
+  echo ""
+  echo "   New commits may have shifted line numbers. Review will be submitted"
+  echo "   against the original commit (${HEAD_SHA:0:7}) but comments may be outdated."
+  echo ""
+fi
+
+echo "Submitting ${EVENT} review for commit ${HEAD_SHA:0:7}..."
+
+# Create and submit the review in one API call
+# Use a temp file to safely pass the JSON body
+TEMP_JSON=$(mktemp)
+trap "rm -f ${TEMP_JSON}" EXIT
+echo "$REVIEW_JSON" > "${TEMP_JSON}"
+
+RESPONSE=$(gh api "repos/${REPO}/pulls/${PR_NUMBER}/reviews" \
+  -X POST \
+  --input "${TEMP_JSON}" 2>&1) || {
+  echo "Error submitting review:"
+  echo "$RESPONSE"
+  exit 1
+}
+
+# Clean up the comments directory after successful submission
+if [ -d "${COMMENTS_DIR}" ] && [ "$COMMENT_COUNT" -gt 0 ]; then
+  rm -f "${COMMENTS_DIR}"/comment-*.json
+  # Remove directory if empty
+  rmdir "${COMMENTS_DIR}" 2>/dev/null || true
+fi
+
+REVIEW_URL=$(echo "$RESPONSE" | jq -r '.html_url // empty')
+REVIEW_STATE=$(echo "$RESPONSE" | jq -r '.state // empty')
+
+if [ -n "$REVIEW_URL" ]; then
+  echo "✓ Review submitted (${REVIEW_STATE}): ${REVIEW_URL}"
+  if [ "$COMMENT_COUNT" -gt 0 ]; then
+    echo "  Included ${COMMENT_COUNT} inline comment(s)"
+  fi
+else
+  echo "✓ Review submitted successfully"
+fi
diff --git a/.github/workflows/auto-close-duplicates.yml b/.github/workflows/auto-close-duplicates.yml
new file mode 100644
index 0000000..a5606e5
--- /dev/null
+++ b/.github/workflows/auto-close-duplicates.yml
@@ -0,0 +1,36 @@
+name: Auto-close duplicate issues
+description: Auto-closes issues that are duplicates of existing issues
+on:
+  schedule:
+    - cron: "0 9 * * *" # Run daily at 9 AM UTC
+  workflow_dispatch:
+
+jobs:
+  auto-close-duplicates:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      issues: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.MARVIN_APP_ID }}
+          private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Auto-close duplicate issues
+        run: uv run scripts/auto_close_duplicates.py
+        env:
+          GITHUB_TOKEN: ${{ steps.marvin-token.outputs.token }}
+          GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}
+          GITHUB_REPOSITORY_NAME: ${{ github.event.repository.name }}
diff --git a/.github/workflows/auto-close-needs-mre.yml b/.github/workflows/auto-close-needs-mre.yml
new file mode 100644
index 0000000..08428ab
--- /dev/null
+++ b/.github/workflows/auto-close-needs-mre.yml
@@ -0,0 +1,36 @@
+name: Auto-close needs MRE issues
+description: Auto-closes issues that need minimal reproducible examples after 7 days of author inactivity
+on:
+  schedule:
+    - cron: "0 9 * * *" # Run daily at 9 AM UTC
+  workflow_dispatch:
+
+jobs:
+  auto-close-needs-mre:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      issues: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.MARVIN_APP_ID }}
+          private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Auto-close needs MRE issues
+        run: uv run scripts/auto_close_needs_mre.py
+        env:
+          GITHUB_TOKEN: ${{ steps.marvin-token.outputs.token }}
+          GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}
+          GITHUB_REPOSITORY_NAME: ${{ github.event.repository.name }}
diff --git a/.github/workflows/martian-test-failure.yml b/.github/workflows/martian-test-failure.yml
new file mode 100644
index 0000000..c589782
--- /dev/null
+++ b/.github/workflows/martian-test-failure.yml
@@ -0,0 +1,197 @@
+name: Marvin Test Failure Analysis
+
+on:
+  workflow_run:
+    workflows: ["Tests", "Run static analysis"]
+    types:
+      - completed
+
+concurrency:
+  group: marvin-test-failure-${{ github.event.workflow_run.head_branch }}
+  cancel-in-progress: true
+
+jobs:
+  martian-test-failure:
+    # Only run if the test workflow failed
+    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 1
+
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.MARVIN_APP_ID }}
+          private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+
+      # Install UV package manager
+      - name: Install UV
+        uses: astral-sh/setup-uv@v7
+
+      # Install dependencies
+      - name: Install dependencies
+        run: uv sync --all-packages --group dev
+
+      - name: Set analysis prompt
+        id: analysis-prompt
+        run: |
+          cat >> $GITHUB_OUTPUT << 'EOF'
+          PROMPT<<PROMPT_END
+          You're a test failure analysis assistant for FastMCP, a Python framework for building Model Context Protocol servers and clients.
+
+          # Your Task
+          A GitHub Actions workflow has failed. Your job is to:
+          1. Analyze the test failure(s) to understand what went wrong
+          2. Identify the root cause of the failure(s)
+          3. Suggest a clear, actionable solution to fix the failure(s)
+
+          # Response Proportionality
+          Match your response length to the complexity of the failure. Not every failure needs a full investigation:
+
+          **Trivial failures** (formatting, linting) — post a short, direct comment. No collapsible sections, no root-cause deep-dive. Example:
+          > CI failed: `ruff format` reformatted 2 files. Run `uv run ruff format .` locally and push.
+
+          **Pre-existing flaky tests** unrelated to the PR — say so briefly. Don't write a full analysis of a test the PR didn't touch. Example:
+          > CI failed due to a pre-existing flaky test (`test_name`) unrelated to this PR's changes. Safe to re-run.
+
+          **Real failures caused by the PR** — these deserve the full analysis format below. Spend your effort here.
+
+          # Getting Started
+          1. Call the generate_agents_md tool to get a high-level summary of the project
+          2. Get the pull request associated with this workflow run from the GitHub repository: ${{ github.repository }}
+             - The workflow run ID is: ${{ github.event.workflow_run.id }}
+             - The workflow run was triggered by: ${{ github.event.workflow_run.event }}
+             - Use GitHub MCP tools to get PR details and workflow run information
+          3. Use the GitHub MCP tools to fetch job logs and failure information:
+             - Use get_workflow_run to get details about the failed workflow
+             - Use list_workflow_jobs to see which jobs failed
+             - Use get_job_logs with failed_only=true to get logs for failed jobs
+             - Use summarize_run_log_failures to get an AI summary of what failed
+          4. Analyze the failures to understand the root cause
+          5. Search the codebase for relevant files, tests, and implementations
+
+          # Your Response
+          Post a comment on the pull request with your analysis.
+
+          Lead with a tl;dr — 1-2 sentences that tell the developer what broke and what to do about it. This should be visible without expanding anything.
+
+          Push supporting detail into collapsible `<details>` blocks. The reader should be able to act on your comment without expanding a single one. Think of details blocks as appendices — there if someone wants to dig deeper, not required for the main message.
+
+          For real (non-trivial) failures, use this structure:
+
+          **tl;dr**: What failed and what to do (1-2 sentences, always visible)
+
+          **Root Cause**: Why it failed (a short paragraph, always visible)
+
+          **Fix**: Specific files and changes needed (always visible)
+
+          <details>
+          <summary>Log excerpts</summary>
+          Relevant failure output
+          </details>
+
+          <details>
+          <summary>Related files</summary>
+          Files relevant to the failure
+          </details>
+
+          # Quality Standards
+          - Every claim needs evidence: file paths, line numbers, log excerpts. Never say "the test fails" without citing which test and what the error was.
+          - Focus on facts from the logs and code, not speculation. If you can't determine the root cause, say so clearly — "I don't know" is better than a wrong diagnosis.
+          - If your only suggestion is a bad one (disable the test, increase the timeout, etc.), say so honestly rather than dressing it up.
+          - Do not paste raw CLI output (e.g., prek progress bars, pytest collection output) into the comment body. Quote only the relevant failure lines.
+          - Always include specific file names, tool names, and test names in your summary. Never leave a sentence with a blank where a name should be.
+
+          # Self-Review Before Posting
+          Before posting your comment, re-read it as the PR author would. Ask:
+          - Can I act on this without expanding any `<details>` block?
+          - Does every claim cite a specific file, line, or log excerpt?
+          - Am I telling them something they can't already see in the CI logs, or just restating them?
+          If your comment doesn't add value beyond what the logs already show, don't post it.
+
+          # STOP SIGNALS
+          If anyone on the PR has asked the bot to stop — e.g., "stop", "go away", "don't comment", "no more bot comments" — exit immediately without further action. This includes past comments in the thread, not just the most recent one.
+
+          If you are posting the same suggestion as you have previously made, do not post the suggestion again.
+
+          # IMPORTANT: EDIT YOUR COMMENT
+          Do not post a new comment every time you triage a failing workflow. If a previous comment has been posted by you (marvin)
+          in a previous triage, edit that comment do not add a new comment for each failure. Be sure to include a note that you've edited
+          your comment to reflect the latest analysis. Don't worry about keeping the old content around, there's comment history for
+          that.
+
+          # Available Tools
+          - You can run make commands (e.g., `make lint`, `make typecheck`, `make sync`) to build, test, or lint the code
+          - You can also run git commands (e.g., `git status`, `git log`, `git diff`) to inspect the repository
+          - You can use WebSearch and WebFetch to research errors, stack traces, or related issues
+          - For bash commands, you are limited to make and git commands only
+
+          # Problems Encountered
+          If you encounter any problems during your analysis (e.g., unable to fetch logs, tools not working), document them clearly so the team knows what limitations you faced.
+          PROMPT_END
+          EOF
+
+      - name: Setup GitHub MCP Server
+        run: |
+          mkdir -p /tmp/mcp-config
+          cat > /tmp/mcp-config/mcp-servers.json << 'EOF'
+          {
+            "mcpServers": {
+              "repository-summary": {
+                "type": "http",
+                "url": "https://agents-md-generator.fastmcp.app/mcp"
+              },
+              "code-search": {
+                "type": "http",
+                "url": "https://public-code-search.fastmcp.app/mcp"
+              },
+              "github-research": {
+                "type": "stdio",
+                "command": "uvx",
+                "args": [
+                  "github-research-mcp"
+                ],
+                "env": {
+                  "DISABLE_SUMMARIES": "true",
+                  "GITHUB_PERSONAL_ACCESS_TOKEN": "${{ secrets.GITHUB_TOKEN }}"
+                }
+              }
+            }
+          }
+          EOF
+
+      - name: Clean up stale Claude locks
+        run: rm -rf ~/.claude/.locks ~/.local/state/claude/locks || true
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          github_token: ${{ steps.marvin-token.outputs.token }}
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY_FOR_CI }}
+          bot_name: "Marvin Context Protocol"
+
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          additional_permissions: |
+            actions: read
+
+          prompt: ${{ steps.analysis-prompt.outputs.PROMPT }}
+          claude_args: |
+            --allowed-tools mcp__repository-summary,mcp__code-search,mcp__github-research,WebSearch,WebFetch,Bash(make:*,git:*)
+            --mcp-config /tmp/mcp-config/mcp-servers.json
diff --git a/.github/workflows/martian-triage-issue.yml b/.github/workflows/martian-triage-issue.yml
new file mode 100644
index 0000000..17d35fe
--- /dev/null
+++ b/.github/workflows/martian-triage-issue.yml
@@ -0,0 +1,221 @@
+# Triage new issues: investigate, recommend, apply labels
+# Calls run-claude directly with triage prompt (elastic issue-triage style)
+
+name: Triage Issue
+
+on:
+  issues:
+    types: [opened]
+
+jobs:
+  triage:
+    if: |
+      github.event.issue.user.login == 'strawgate' ||
+      (github.event.issue.user.login == 'jlowin' && contains(toJSON(github.event.issue.labels.*.name), 'bug'))
+    concurrency:
+      group: triage-issue-${{ github.event.issue.number }}
+      cancel-in-progress: true
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          repository: ${{ github.repository }}
+          ref: ${{ github.event.repository.default_branch }}
+
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.MARVIN_APP_ID }}
+          private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}
+
+      - name: React to issue with eyes
+        env:
+          GH_TOKEN: ${{ steps.marvin-token.outputs.token }}
+        run: |
+          gh api "repos/${{ github.repository }}/issues/${{ github.event.issue.number }}/reactions" -f content=eyes 2>/dev/null || true
+
+      - name: Run Claude for Triage
+        uses: ./.github/actions/run-claude
+        env:
+          ISSUE_BODY: ${{ github.event.issue.body }}
+          ISSUE_TITLE: ${{ github.event.issue.title }}
+        with:
+          claude-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          github-token: ${{ steps.marvin-token.outputs.token }}
+          allowed-tools: "Edit,MultiEdit,Glob,Grep,LS,Read,Write,WebSearch,WebFetch,mcp__github_comment__update_claude_comment,mcp__github_ci__get_ci_status,mcp__github_ci__get_workflow_run_details,mcp__github_ci__download_job_log,Bash(*),mcp__agents-md-generator__generate_agents_md,mcp__public-code-search__search_code"
+          prompt: |
+            <context>
+            Repository: ${{ github.repository }}
+            Issue Number: #${{ github.event.issue.number }}
+            Issue Title: ${{ env.ISSUE_TITLE }}
+            Issue Author: ${{ github.event.issue.user.login }}
+            </context>
+
+            <issue_body>
+            ${{ env.ISSUE_BODY }}
+            </issue_body>
+
+            <task>
+            Triage this new GitHub issue and provide a helpful, actionable response. You can write files and execute commands to test, verify, or investigate the issue.
+            </task>
+
+            <constraints>
+            This workflow is for investigation, testing, and planning.
+
+            You CANNOT: Create branches, checkout branches, commit code to the repository
+            Do not push changes to the repository.
+            You CAN: Read/analyze code, search repository, review git history, search for similar issues, write files, verify behavior, provide analysis and recommendations
+            </constraints>
+
+            <allowed_tools>
+            You have access to the following tools (comma-separated list):
+
+            Edit,MultiEdit,Glob,Grep,LS,Read,Write,WebSearch,WebFetch,mcp__github_comment__update_claude_comment,mcp__github_ci__get_ci_status,mcp__github_ci__get_workflow_run_details,mcp__github_ci__download_job_log,Bash(*),mcp__agents-md-generator__generate_agents_md,mcp__public-code-search__search_code
+
+            You can only use tools that are explicitly listed above. For Bash commands, the pattern `Bash(command:*)` means you can run that command with any arguments. If a command is not listed, it is not available.
+            </allowed_tools>
+
+            <getting_started>
+            Use `mcp__agents-md-generator__generate_agents_md` to get repository context before triaging.
+            </getting_started>
+
+            <investigation_tools>
+            - `mcp__public-code-search__search_code`: Search code in OTHER repositories (use `Grep`/`Read` for this repo)
+            - `WebSearch`: Search the web for documentation, best practices, or solutions
+            - `WebFetch`: Fetch and read content from URLs
+            - Git commands: You have access to git commands, but write commands (commit, push, checkout, branch creation) are blocked
+            - Write: You can write files (e.g., test files, temporary files for verification)
+            - Execution: See `<allowed_tools>` section above for exact list of available execution commands
+            </investigation_tools>
+
+            <execution_guidelines>
+            If execution commands are available (check `<allowed_tools>` section), you can:
+            - Run tests to verify reported bugs or test proposed solutions
+            - Execute scripts to understand behavior
+            - Run linters or static analysis tools
+            - Verify environment setup or dependencies
+            - Test specific code paths or scenarios
+            - Write test files to confirm behavior
+
+            When executing commands:
+            - Explain what you're testing and why
+            - Include command output in your response when relevant
+            - Use execution to validate your findings and recommendations
+            - Only use commands that are explicitly listed in `<allowed_tools>`
+            </execution_guidelines>
+
+            <response_goals>
+            Your number one priority is to provide a great response to the issue. A great response is a response that is clear, concise, accurate, and actionable. You will avoid long paragraphs, flowery language, and overly verbose responses. Your readers have limited time and attention, so you will be concise and to the point.
+
+            In priority order your goal is to:
+              1. Provide context about the request or issue (related issues, pull requests, files, etc.)
+              2. Layout a single high-quality and actionable recommendation for how to address the issue based on your knowledge of the project, codebase, and issue
+              3. Provide a high quality and detailed plan that a junior developer could follow to implement the recommendation
+              4. Use execution to verify findings when appropriate (check `<allowed_tools>` section for available commands)
+
+            Report findings and recommendations — not your process. Do not include task checklists, progress tracking, or "steps I took" narration (e.g., `- [x] Read source code`). The reader cares about what you found, not how you found it.
+            </response_goals>
+
+            <evidence_standards>
+            Every claim in your response must be grounded in evidence you can cite:
+            - **Code references**: Always include file path and line number (e.g., `fastmcp_slim/fastmcp/client/client.py:142`). Never say "the client code does X" without pointing to where.
+            - **Bug confirmation**: If you say a bug is real, show the specific code path that produces it. If you ran a test, include the command and output.
+            - **Related items**: When citing a related issue or PR, explain specifically why it's related — not just that it exists.
+            - **Confidence**: If you're uncertain about a finding, say so. "I don't know" or "I couldn't confirm this" is better than a speculative diagnosis. Only report findings you would confidently defend.
+            </evidence_standards>
+
+            <quality_gate>
+            Before posting, re-read your response as a maintainer would:
+            - Does the tl;dr give the full picture without expanding anything?
+            - Does every claim cite a specific file, line, or test result?
+            - Is this telling the maintainer something they couldn't find in 5 minutes of reading the issue and grepping the code?
+            If your response doesn't add meaningful value beyond restating the issue, it's okay to post a short "confirmed, straightforward fix in [file]:[line]" response instead of a full analysis.
+            </quality_gate>
+
+            <response_sections>
+            Populate the following sections in your response:
+              Recommendation (or "No recommendation" with reason)
+              Findings
+              Verification (if you executed tests or commands - check `<allowed_tools>` section)
+              Detailed Action Plan
+              Related Items
+              Related Files
+              Related Webpages
+
+            You may not be able to do all of these things, sometimes you may find that all you can do is provide in-depth context of the issue and related items. That's perfectly acceptable and expected. Your performance is judged by how accurate your findings are, do the investigation required to have high confidence in your findings and recommendations. "I don't know" or "I'm unable to recommend a course of action" is better than a bad or wrong answer.
+
+            Structure: Lead with a tl;dr (1-3 sentences, always visible) that gives the reader the bottom line — what this issue is, whether it's valid, and what to do about it. The reader should be able to act on your comment without expanding anything.
+
+            Push everything else into collapsible `<details>` blocks: findings, verification output, action plans, related items, related files. These are appendices — valuable for someone who wants to dig deeper, but not required for the main message. The only things that should be visible without clicking are the tl;dr and the recommendation. Short responses (a few sentences) don't need collapsible sections at all.
+
+            </response_sections>
+            <response_examples>
+            # Example: the tl;dr and recommendation are always visible, everything else is collapsed
+
+            **tl;dr**: Confirmed bug — `Calculator.divide` raises `ValueError` instead of `DivisionByZeroError`. PR #654 partially addresses this but is incomplete.
+
+            **Recommendation**: Complete PR #654: update `Calculator.divide` to raise `DivisionByZeroError` and update the test assertions to match.
+
+            <details>
+            <summary>Findings</summary>
+            ...details from the code analysis that are relevant to the issue and the recommendation...
+            </details>
+
+            <details>
+            <summary>Verification</summary>
+
+            ```bash
+            $ pytest test_calculator.py::test_divide_by_zero
+            FAILED - raises ValueError instead of DivisionByZeroError
+            ```
+            This confirms the issue report is accurate.
+            </details>
+
+            <details>
+            <summary>Action Plan</summary>
+            ...a detailed plan that a junior developer could follow to implement the recommendation...
+            </details>
+
+            <details>
+            <summary>Related Issues and Pull Requests</summary>
+
+            | Issue or PR | Relevance |
+            | --- | --- |
+            | [Add matrix operations support](https://github.com/PrefectHQ/fastmcp/pull/680) | Directly addresses the feature request |
+            </details>
+
+            <details>
+            <summary>Related Files</summary>
+
+            | File | Relevance |
+            | --- | --- |
+            | [calculator.py L29-32](https://github.com/modelcontextprotocol/python-sdk/blob/main/calculator.py#L29-L32) | The `divide` method that raises ValueError |
+            | [test_calculator.py L25-27](https://github.com/modelcontextprotocol/python-sdk/blob/main/test_calculator.py#L25-L27) | Test asserting ValueError (needs updating) |
+            </details>
+            </response_examples>
+
+            <response_footer>
+            Always end your comment with a new line, three dashes, and the footer message:
+            <exact_content>
+
+            ---
+            Marvin Context Protocol | Type `/marvin` to interact further
+
+            Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
+            </exact_content>
+            </response_footer>
+
+            <github_formatting>
+            When writing GitHub comments, wrap branch names, tags, or other @-references in backticks (e.g., `@main`, `@v1.0`) to avoid accidentally pinging users. Do not add backticks around terms that are already inside backticks or code blocks.
+            Do not write `fixes #N`, `closes #N`, or `resolves #N` in comments — these can accidentally close issues. Use plain `#N` references instead.
+            </github_formatting>
diff --git a/.github/workflows/marvin-comment-on-issue.yml b/.github/workflows/marvin-comment-on-issue.yml
new file mode 100644
index 0000000..72c38cd
--- /dev/null
+++ b/.github/workflows/marvin-comment-on-issue.yml
@@ -0,0 +1,148 @@
+# Respond to /marvin mentions in issue comments (elastic mention-in-issue style)
+# Calls run-claude directly
+
+name: Comment on Issue
+
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  actions: read
+  contents: write
+  issues: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  comment:
+    if: |
+      !github.event.issue.pull_request &&
+      contains(github.event.comment.body, '/marvin') &&
+      contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association)
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Install UV
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies
+        run: uv sync --python 3.12
+
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.MARVIN_APP_ID }}
+          private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}
+
+      - name: React to comment with eyes
+        env:
+          GH_TOKEN: ${{ steps.marvin-token.outputs.token }}
+        run: |
+          gh api "repos/${{ github.repository }}/issues/comments/${{ github.event.comment.id }}/reactions" -f content=eyes 2>/dev/null || true
+
+      - name: Run Claude for Issue Comment
+        uses: ./.github/actions/run-claude
+        env:
+          COMMENT_BODY: ${{ github.event.comment.body }}
+          ISSUE_TITLE: ${{ github.event.issue.title }}
+        with:
+          claude-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          github-token: ${{ steps.marvin-token.outputs.token }}
+          trigger-phrase: "/marvin"
+          allowed-bots: "*"
+          allowed-tools: "Edit,MultiEdit,Glob,Grep,LS,Read,Write,WebSearch,WebFetch,mcp__github_comment__update_claude_comment,mcp__github_ci__get_ci_status,mcp__github_ci__get_workflow_run_details,mcp__github_ci__download_job_log,Bash(*),mcp__agents-md-generator__generate_agents_md,mcp__public-code-search__search_code"
+          prompt: |
+            <context>
+            Repository: ${{ github.repository }}
+            Issue Number: #${{ github.event.issue.number }}
+            Issue Title: ${{ env.ISSUE_TITLE }}
+            Issue Author: ${{ github.event.issue.user.login }}
+            Comment Author: ${{ github.event.comment.user.login }}
+            </context>
+
+            <user_request>
+            ${{ env.COMMENT_BODY }}
+            </user_request>
+
+            <task>
+            You have been mentioned in a GitHub issue comment. Understand the request, gather context, complete the task, and respond with results.
+            </task>
+
+            <constraints>
+            You CAN: Read/analyze code, modify files, write code, run tests, execute commands, commit code, push changes, create branches, create pull requests
+            </constraints>
+
+            <allowed_tools>
+            You have access to the following tools (comma-separated list):
+
+            Edit,MultiEdit,Glob,Grep,LS,Read,Write,WebSearch,WebFetch,mcp__github_comment__update_claude_comment,mcp__github_ci__get_ci_status,mcp__github_ci__get_workflow_run_details,mcp__github_ci__download_job_log,Bash(*),mcp__agents-md-generator__generate_agents_md,mcp__public-code-search__search_code
+
+            You can only use tools that are explicitly listed above. For Bash commands, the pattern `Bash(command:*)` means you can run that command with any arguments. If a command is not listed, it is not available.
+            </allowed_tools>
+
+            <getting_started>
+            Use `mcp__agents-md-generator__generate_agents_md` to get repository context before responding.
+            </getting_started>
+
+            <investigation_approach>
+            Be thorough in your investigations:
+            - Understand the full context of the repository
+            - Review related code, issues, and PRs
+            - Consider edge cases and implications
+            - Gather all relevant information before responding
+
+            Available tools:
+            - `mcp__public-code-search__search_code`: Search code in OTHER repositories (use `Grep`/`Read` for this repo)
+            - `WebSearch`: Search the web for documentation, best practices, or solutions
+            - `WebFetch`: Fetch and read content from URLs
+            </investigation_approach>
+
+            <common_tasks>
+            - Answer questions about the codebase
+            - Help debug reported problems
+            - Suggest solutions or workarounds
+            - Provide code examples
+            - Help clarify requirements
+            - Link to relevant documentation or code
+            - Create branches, commit changes, and open PRs when asked
+            </common_tasks>
+
+            <response_guidelines>
+            - Lead with a tl;dr — the bottom line in 1-3 sentences, always visible. The reader should be able to act without expanding anything.
+            - Push supporting detail (code analysis, verification output, related items) into collapsible `<details>` blocks. These are appendices, not the main message.
+            - Short responses (a few sentences) don't need collapsible sections at all.
+            - Be concise and actionable.
+            - If the request is unclear, ask clarifying questions.
+            - Report findings and recommendations — not your process. Do not include task checklists or "steps I took" narration.
+            - Every claim needs evidence: cite file paths, line numbers, or command output. Never say "the code does X" without pointing to where.
+            - If you're uncertain, say so. "I couldn't confirm this" is better than a speculative answer.
+            </response_guidelines>
+
+            <github_safety>
+            - Do not write `fixes #N`, `closes #N`, or `resolves #N` in comments — these can accidentally close issues.
+            - When referencing issues, use plain `#N` or link syntax without action keywords.
+            </github_safety>
+
+            <response_footer>
+            Always end your comment with a new line, three dashes, and the footer message:
+            <exact_content>
+
+            ---
+            Marvin Context Protocol | Type `/marvin` to interact further
+
+            Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
+            </exact_content>
+            </response_footer>
+
+            <github_formatting>
+            When writing GitHub comments, wrap branch names, tags, or other @-references in backticks (e.g., `@main`, `@v1.0`) to avoid accidentally pinging users. Do not add backticks around terms that are already inside backticks or code blocks.
+            </github_formatting>
diff --git a/.github/workflows/marvin-comment-on-pr.yml b/.github/workflows/marvin-comment-on-pr.yml
new file mode 100644
index 0000000..369a90c
--- /dev/null
+++ b/.github/workflows/marvin-comment-on-pr.yml
@@ -0,0 +1,307 @@
+# Respond to /marvin mentions in PR review comments and issue comments on PRs
+# Calls run-claude directly
+
+name: Comment on PR
+
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: read
+  id-token: write
+
+jobs:
+  comment:
+    if: |
+      github.event.issue.pull_request &&
+      contains(github.event.comment.body, '/marvin') &&
+      contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout PR head branch
+        uses: actions/checkout@v7
+        with:
+          # do not set to pull_request.head.ref, claude will pull the branch if needed
+          fetch-depth: 0
+
+      - name: Install UV
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies
+        run: uv sync --python 3.12
+
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.MARVIN_APP_ID }}
+          private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}
+
+      - name: React to comment with eyes
+        env:
+          GH_TOKEN: ${{ steps.marvin-token.outputs.token }}
+        run: |
+          gh api "repos/${{ github.repository }}/issues/comments/${{ github.event.comment.id }}/reactions" -f content=eyes 2>/dev/null || true
+
+      - name: Get PR HEAD SHA
+        id: pr-info
+        env:
+          GH_TOKEN: ${{ steps.marvin-token.outputs.token }}
+        run: |
+          PR_NUMBER="${{ github.event.issue.number }}"
+          HEAD_SHA=$(gh api "repos/${{ github.repository }}/pulls/${PR_NUMBER}" --jq '.head.sha')
+          echo "head_sha=${HEAD_SHA}" >> "$GITHUB_OUTPUT"
+          echo "pr_number=${PR_NUMBER}" >> "$GITHUB_OUTPUT"
+
+      - name: Run Claude for PR Comment
+        uses: ./.github/actions/run-claude
+        env:
+          MENTION_REPO: ${{ github.repository }}
+          MENTION_PR_NUMBER: ${{ steps.pr-info.outputs.pr_number }}
+          MENTION_SCRIPTS: ${{ github.workspace }}/.github/scripts/mention
+          PR_REVIEW_REPO: ${{ github.repository }}
+          PR_REVIEW_PR_NUMBER: ${{ steps.pr-info.outputs.pr_number }}
+          PR_REVIEW_HEAD_SHA: ${{ steps.pr-info.outputs.head_sha }}
+          PR_REVIEW_COMMENTS_DIR: /tmp/pr-review-comments
+          PR_REVIEW_HELPERS_DIR: ${{ github.workspace }}/.github/scripts/pr-review
+          COMMENT_BODY: ${{ github.event.comment.body }}
+          PR_TITLE: ${{ github.event.issue.title }}
+        with:
+          claude-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          github-token: ${{ steps.marvin-token.outputs.token }}
+          trigger-phrase: "/marvin"
+          allowed-bots: "*"
+          allowed-tools: "Edit,MultiEdit,Glob,Grep,LS,Read,Write,WebSearch,WebFetch,mcp__github_comment__update_claude_comment,mcp__github_ci__get_ci_status,mcp__github_ci__get_workflow_run_details,mcp__github_ci__download_job_log,Bash(*),mcp__agents-md-generator__generate_agents_md,mcp__public-code-search__search_code"
+          prompt: |
+            <context>
+            Repository: ${{ github.repository }}
+            PR Number: #${{ steps.pr-info.outputs.pr_number }}
+            PR Title: ${{ env.PR_TITLE }}
+            PR Author: ${{ github.event.issue.user.login }}
+            Comment Author: ${{ github.event.comment.user.login }}
+
+            **Note**: The PR head branch has already been checked out. The workspace is ready - you can immediately start working on the PR code.
+            </context>
+
+            <user_request>
+            ${{ env.COMMENT_BODY }}
+            </user_request>
+
+            <task>
+            You have been mentioned in a Pull Request comment. Understand the request, gather context, complete the task, and respond with results.
+            </task>
+
+            <constraints>
+            You CAN: Read/analyze code, modify files, write code, run tests, execute commands, resolve review threads, commit and push changes to the PR branch, checkout branches
+            You CANNOT: Create new branches unrelated to this PR, create new pull requests
+
+            When making changes, commit and push to the PR's head branch so the author gets the fix directly.
+            </constraints>
+
+            <allowed_tools>
+            You have access to the following tools (comma-separated list):
+
+            Edit,MultiEdit,Glob,Grep,LS,Read,Write,WebSearch,WebFetch,mcp__github_comment__update_claude_comment,mcp__github_ci__get_ci_status,mcp__github_ci__get_workflow_run_details,mcp__github_ci__download_job_log,Bash(*),mcp__agents-md-generator__generate_agents_md,mcp__public-code-search__search_code
+
+            You can only use tools that are explicitly listed above. For Bash commands, the pattern `Bash(command:*)` means you can run that command with any arguments. If a command is not listed, it is not available.
+            </allowed_tools>
+
+            <getting_started>
+            Use `mcp__agents-md-generator__generate_agents_md` to get repository context before responding.
+            </getting_started>
+
+            <investigation_approach>
+            Be thorough in your investigations:
+            - Understand the full context of the repository
+            - Review related code, issues, and PRs
+            - Consider edge cases and implications
+            - Gather all relevant information before responding
+
+            Available tools:
+            - `mcp__public-code-search__search_code`: Search code in OTHER repositories (use `Grep`/`Read` for this repo)
+            - `WebSearch`: Search the web for documentation, best practices, or solutions
+            - `WebFetch`: Fetch and read content from URLs
+            </investigation_approach>
+
+            <common_tasks>
+            - Address review feedback and fix issues (commit and push to the PR branch)
+            - Answer questions about the changes
+            - Make code changes and push them
+            - Resolve review threads after addressing feedback
+            - Perform PR reviews when asked (use the PR review process below)
+            </common_tasks>
+
+            <pr_review_guidance>
+            When asked to review this PR, follow this structured review process.
+            The `$PR_REVIEW_HELPERS_DIR` environment variable is pre-configured for all scripts below.
+
+            <review_process>
+            Follow these steps in order:
+
+            **Step 1: Gather context**
+            - Use `mcp__agents-md-generator__generate_agents_md` to get repository context
+              (if this fails, explore the repository to understand the codebase — read key files like README, CONTRIBUTING, etc.)
+            - Run `$PR_REVIEW_HELPERS_DIR/pr-existing-comments.sh --summary` to see existing review threads per file
+            - Run `$PR_REVIEW_HELPERS_DIR/pr-diff.sh` to see changed files with line-numbered diffs
+              (for large PRs, this lists files only — review each with `pr-diff.sh <filename>`)
+
+            **Step 2: Review each file**
+            For each changed file:
+            a. If the summary showed existing threads for this file, first run:
+               `$PR_REVIEW_HELPERS_DIR/pr-existing-comments.sh --file <path>`
+               Read the full thread details. The output uses these conventions:
+               - `← has replies` — a conversation happened; read carefully before commenting
+               - `[truncated]` — comment was cut short; add `--full` if you need the complete text to understand the comment
+               - `[abc1234]` — commit the comment was made on; use `git show abc1234` if needed
+               - `~42` — approximate line from an older revision (exact line no longer maps to current diff)
+            b. Review the diff. Use `Read` to see full file contents when you need more context.
+               Identify issues matching review_criteria. Do NOT flag:
+               - Issues in unchanged code (only review the diff)
+               - Style preferences handled by linters
+               - Pre-existing issues not introduced by this PR
+               - Issues already covered by existing threads (see below)
+
+            **Existing thread rules** (check BEFORE leaving any comment):
+            - Resolved with reviewer reply → reviewer's decision is final. Do NOT re-flag.
+              Examples: "It should remain as X", "This is intentional", "No need to do this change"
+            - Resolved without reply → author likely fixed it. Do NOT re-raise unless the fix introduced a new problem.
+            - Unresolved → already flagged. Do NOT re-comment. Mention in review body if you have more to add.
+            - Outdated → code changed. Only re-flag if the issue still applies to the current diff.
+            When in doubt, do not duplicate. Redundant comments erode trust in the review process.
+
+            **Step 3: Leave comments for NEW issues only**
+            For each genuinely new issue not covered by existing threads:
+            ```bash
+            $PR_REVIEW_HELPERS_DIR/pr-comment.sh <file> <line> \
+              --severity <critical|high|medium|low|nitpick> \
+              --title "Brief description" \
+              --why "Risk or impact" <<'EOF'
+            corrected code here
+            EOF
+            ```
+            Always provide suggestion code. Use `--no-suggestion` only when the fix requires
+            changes across multiple locations. Broader architectural concerns belong in the
+            review body, not inline comments.
+
+            To remove a queued comment: `$PR_REVIEW_HELPERS_DIR/pr-remove-comment.sh <file> <line>`
+
+            **Step 4: Submit the review**
+            ```bash
+            $PR_REVIEW_HELPERS_DIR/pr-review.sh <APPROVE|REQUEST_CHANGES|COMMENT> "<review body>"
+            ```
+            - REQUEST_CHANGES: Any 🔴 CRITICAL or 🟠 HIGH issues found
+            - COMMENT: 🟡 MEDIUM issues found (but no critical/high)
+            - APPROVE: No issues, or only ⚪ LOW / 💬 NITPICK suggestions
+
+            The review body should include broader architectural concerns not suited for inline comments.
+            Avoid summarizing the PR or offering praise. If approving with no issues, omit the review body.
+            A standard footer is automatically appended to all comments and reviews.
+            </review_process>
+
+            <severity_classification>
+            🔴 CRITICAL - Must fix before merge (security vulnerabilities, data corruption, production-breaking bugs)
+            🟠 HIGH - Should fix before merge (logic errors, missing validation, significant performance issues)
+            🟡 MEDIUM - Address soon, non-blocking (error handling gaps, suboptimal patterns, missing edge cases)
+            ⚪ LOW - Author discretion, non-blocking (minor improvements, documentation, style not covered by linters)
+            💬 NITPICK - Truly optional (stylistic preferences, alternative approaches — safe to ignore)
+            </severity_classification>
+
+            <review_criteria>
+            Focus on these categories, in priority order:
+            1. Security vulnerabilities (injection, XSS, auth bypass, secrets exposure)
+            2. Logic bugs that could cause runtime failures or incorrect behavior
+            3. Data integrity issues (race conditions, missing transactions, corruption risk)
+            4. Performance bottlenecks (N+1 queries, memory leaks, blocking operations)
+            5. Error handling gaps (unhandled exceptions, missing validation)
+            6. Breaking changes to public APIs without migration path
+            7. Missing or incorrect test coverage for critical paths
+            </review_criteria>
+
+            <review_calibration>
+            **What NOT to flag** — do not comment on:
+            - Issues in unchanged code (only review the diff)
+            - Input already validated or sanitized at a different layer
+            - Theoretical performance concerns without evidence that N is large
+            - Style or formatting not in the project's linting rules
+            - Missing tests for trivial or generated code
+            - Pre-existing patterns the PR is following consistently
+
+            **Calibration examples**:
+            - Unguarded return from a lookup (e.g., `tool = registry.get(name)` used without None check) → FLAG if the diff introduces the unguarded usage
+            - Same pattern, but the function's return type is `Tool` (not `Optional[Tool]`) → DO NOT FLAG, the type system guarantees non-None
+            - String interpolation in a query with user input → FLAG
+            - String interpolation in a query with a hardcoded enum value → DO NOT FLAG
+            - O(n²) loop → FLAG only if there's evidence N can be large (e.g., user-controlled list). If N is bounded by design (e.g., number of MCP tools), do not flag.
+
+            When in doubt, do not flag. A false positive wastes a reviewer's time and erodes trust in every future review comment.
+            </review_calibration>
+            </pr_review_guidance>
+
+            <review_thread_tools>
+            View unresolved review threads:
+            ```bash
+            $MENTION_SCRIPTS/gh-get-review-threads.sh
+            ```
+
+            Filter for unresolved threads from a specific reviewer:
+            ```bash
+            $MENTION_SCRIPTS/gh-get-review-threads.sh "reviewer-username"
+            ```
+
+            Resolve a review thread after addressing feedback:
+            ```bash
+            $MENTION_SCRIPTS/gh-resolve-review-thread.sh "THREAD_ID" "Fixed by updating the error handling"
+            ```
+            - `THREAD_ID` is the GraphQL node ID from the review threads output (e.g., `PRRT_kwDOABC123`)
+            - The comment is optional - use it to explain what you did
+
+            Note: You can resolve threads after pushing fixes, or resolve them to acknowledge feedback that will be addressed separately.
+            </review_thread_tools>
+
+            <response_guidelines>
+            - Lead with a tl;dr — the bottom line in 1-3 sentences, always visible. The reader should be able to act without expanding anything.
+            - Push supporting detail (code analysis, verification output, related items) into collapsible `<details>` blocks. These are appendices, not the main message.
+            - Short responses (a few sentences) don't need collapsible sections at all.
+            - Be concise and actionable.
+            - If the request is unclear, ask clarifying questions.
+            - When making code changes, commit and push them to the PR branch so the author gets the fix directly.
+            - Every claim needs evidence: cite file paths, line numbers, or command output. Never say "the code does X" without pointing to where.
+            - If you're uncertain, say so. "I couldn't confirm this" is better than a speculative answer.
+
+            **When performing a PR review**: Your substantive feedback belongs in the PR review submission
+            (via pr-review.sh), not in the comment response. The comment should only report:
+            - That you've submitted the review (with the outcome: approved, requested changes, etc.)
+            - Any issues encountered during the review process
+            - Brief status updates
+
+            Do NOT duplicate the review content in your comment - the review itself contains all the details.
+            Keep the comment short, e.g., "I've submitted my review requesting changes. See the review for details."
+            </response_guidelines>
+
+            <github_safety>
+            - Do not write `fixes #N`, `closes #N`, or `resolves #N` in comments — these can accidentally close issues.
+            - When referencing issues, use plain `#N` or link syntax without action keywords.
+            </github_safety>
+
+            <response_footer>
+            Always end your comment with a new line, three dashes, and the footer message:
+            <exact_content>
+
+            ---
+            Marvin Context Protocol | Type `/marvin` to interact further
+
+            Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
+            </exact_content>
+            </response_footer>
+
+            <github_formatting>
+            When writing GitHub comments, wrap branch names, tags, or other @-references in backticks (e.g., `@main`, `@v1.0`) to avoid accidentally pinging users. Do not add backticks around terms that are already inside backticks or code blocks.
+            </github_formatting>
diff --git a/.github/workflows/marvin-dedupe-issues.yml b/.github/workflows/marvin-dedupe-issues.yml
new file mode 100644
index 0000000..5815f98
--- /dev/null
+++ b/.github/workflows/marvin-dedupe-issues.yml
@@ -0,0 +1,131 @@
+name: Marvin Issue Dedupe
+# description: Automatically dedupe GitHub issues using Marvin
+on:
+  issues:
+    types: [opened]
+  workflow_dispatch:
+    inputs:
+      issue_number:
+        description: "Issue number to process for duplicate detection"
+        required: true
+        type: string
+
+jobs:
+  marvin-dedupe-issues:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      issues: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.MARVIN_APP_ID }}
+          private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}
+
+      - name: Set dedupe prompt
+        id: dedupe-prompt
+        run: |
+          cat >> $GITHUB_OUTPUT << 'EOF'
+          PROMPT<<PROMPT_END
+          Find up to 3 likely duplicate issues for GitHub issue ${{ github.repository }}/issues/${{ github.event.issue.number || inputs.issue_number }}.
+
+          # Core Principle
+          Silence is better than noise. A false positive wastes a human's time and erodes trust in every future report. Most runs should end with no comment — that means the system is working.
+
+          # Steps
+
+          1. Check if the GitHub issue (a) is closed, (b) does not need to be deduped (eg. because it is broad product feedback without a specific solution, or positive feedback), or (c) already has a duplicates comment that you made earlier. If so, do not proceed.
+
+          2. View the GitHub issue and produce a summary of the issue.
+
+          3. Launch 3 parallel agents using the Task tool to search GitHub for duplicates, using diverse keywords and search approaches, using the summary from step 2.
+
+          4. Filter aggressively for false positives. The bar for "duplicate" is high:
+
+             A duplicate means the SAME bug or the SAME feature request. Apply this test to every candidate:
+             - **Same fix test**: Could the candidate be closed by the exact same code change? If not, not a duplicate.
+             - **Same symptom test**: Does the user experience the exact same broken behavior? "Both involve middleware" is not duplication. "Both get TypeError on line 42 of proxy.py when calling mount()" is duplication.
+             - **Same request test** (for features): Are they asking for the same specific capability? "Both want better auth" is not duplication. "Both request OAuth PKCE flow for CLI login" is duplication.
+
+             Candidates found by only one search agent deserve extra scrutiny — a single keyword match is often a false positive.
+
+             When in doubt, do not flag. A missed duplicate is harmless; a false positive wastes the reporter's time.
+             If there are no duplicates remaining, do not proceed — just exit.
+
+          5. **Quality gate**: Before commenting, re-read each candidate as a skeptical reviewer. For each one, ask: "Would a maintainer who knows this codebase agree this is a duplicate, or would they dismiss it?" If you'd need to hedge with "might" or "possibly," drop it.
+
+          6. Comment back on the issue with your findings (or exit silently if none remain). Do NOT add any labels — labeling is handled by a later workflow step.
+
+          # Notes for your agents
+          - Use `gh` to interact with GitHub, rather than web fetch
+          - Do not use other tools beyond `gh` and Task (no MCP servers, file edit, etc.)
+          - Never include this issue as a duplicate of itself
+          - When searching, read the FULL body of candidate issues — titles alone are not enough to judge duplication
+
+          For your comment, follow this format precisely (example with 3 suspected duplicates):
+
+          ---
+          Found 3 possible duplicate issues:
+
+          1. #123: Issue title here
+          2. #456: Another issue title
+          3. #789: Third issue title
+
+          This issue will be automatically closed as a duplicate in 3 days.
+
+          - If your issue is a duplicate, please close it and 👍 the existing issue instead
+          - To prevent auto-closure, add a comment or 👎 this comment
+
+          ---
+          PROMPT_END
+          EOF
+
+      - name: Clean up stale Claude locks
+        run: rm -rf ~/.claude/.locks ~/.local/state/claude/locks || true
+
+      - name: Run Marvin dedupe command
+        uses: anthropics/claude-code-action@v1
+        with:
+          github_token: ${{ steps.marvin-token.outputs.token }}
+          bot_name: "Marvin Context Protocol"
+          prompt: ${{ steps.dedupe-prompt.outputs.PROMPT }}
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY_FOR_CI }}
+          allowed_non_write_users: "*"
+          claude_args: |
+            --allowedTools Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh api:*),Bash(gh issue comment:*),Task
+          settings: |
+            {
+              "model": "claude-sonnet-4-6",
+              "env": {
+                "GH_TOKEN": "${{ steps.marvin-token.outputs.token }}"
+              }
+            }
+
+      - name: Add potential-duplicate label if bot commented in this run
+        env:
+          GH_TOKEN: ${{ steps.marvin-token.outputs.token }}
+        run: |
+          ISSUE=${{ github.event.issue.number || inputs.issue_number }}
+          # Only match bot comments created in the last 10 minutes (this run)
+          CUTOFF=$(date -u -d '10 minutes ago' '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null \
+            || date -u -v-10M '+%Y-%m-%dT%H:%M:%SZ')
+          HAS_RECENT=$(gh api "repos/${{ github.repository }}/issues/${ISSUE}/comments?sort=created&direction=desc&per_page=10" \
+            --jq "[.[] | select(
+              .user.type == \"Bot\" and
+              (.body | test(\"possible duplicate issues\"; \"i\")) and
+              .created_at >= \"${CUTOFF}\"
+            )] | length")
+          if [ "$HAS_RECENT" -gt 0 ]; then
+            gh issue edit "$ISSUE" --add-label "potential-duplicate" -R "${{ github.repository }}"
+            echo "Added potential-duplicate label to #${ISSUE}"
+          else
+            echo "No recent duplicate comment found, skipping label"
+          fi
diff --git a/.github/workflows/marvin-label-triage.yml b/.github/workflows/marvin-label-triage.yml
new file mode 100644
index 0000000..571dee2
--- /dev/null
+++ b/.github/workflows/marvin-label-triage.yml
@@ -0,0 +1,159 @@
+name: Marvin Label Triage
+# Automatically triage GitHub issues and PRs using Marvin
+
+on:
+  issues:
+    types: [opened]
+  pull_request_target:
+    types: [opened]
+  workflow_dispatch:
+    inputs:
+      issue_number:
+        description: "Issue or PR number to triage"
+        required: true
+        type: string
+
+concurrency:
+  group: triage-${{ github.event.issue.number || github.event.pull_request.number || inputs.issue_number }}
+  cancel-in-progress: false
+
+jobs:
+  label-issue-or-pr:
+    if: github.actor != 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout base repository
+        uses: actions/checkout@v7
+        with:
+          repository: ${{ github.repository }}
+          ref: ${{ github.event.repository.default_branch }}
+
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.MARVIN_APP_ID }}
+          private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}
+          owner: PrefectHQ
+
+      - name: Set triage prompt
+        id: triage-prompt
+        run: |
+          cat >> $GITHUB_OUTPUT << 'EOF'
+          PROMPT<<PROMPT_END
+          You're an issue triage assistant for FastMCP, a Python framework for building Model Context Protocol servers and clients. Your task is to analyze issues/PRs and apply appropriate labels.
+
+          IMPORTANT: Your primary action should be to apply labels using mcp__github__update_issue. DO NOT post comments EXCEPT when applying the too-long label (see below).
+
+          CRITICAL — LABEL MECHANICS:
+          - `mcp__github__update_issue` REPLACES all labels on the issue — it does not add to them.
+          - Before applying labels, read the issue's current labels with `mcp__github__get_issue`.
+          - Always include any existing labels you want to keep alongside the new ones.
+          - Only apply labels that exist in the repository (from `gh label list` in step 1). Never invent labels.
+
+          Issue/PR Information:
+          - REPO: ${{ github.repository }}
+          - NUMBER: ${{ github.event.issue.number || github.event.pull_request.number || inputs.issue_number }}
+          - TYPE: ${{ github.event.issue && 'issue' || (github.event.pull_request && 'pull_request') || 'unknown' }}
+
+          TRIAGE PROCESS:
+
+          1. Get available labels:
+             Run: `gh label list`
+
+          2. Retrieve issue/PR details using GitHub tools:
+             - mcp__github__get_issue: Get the issue/PR details
+             - mcp__github__get_issue_comments: Read any discussion
+             - If the issue/PR mentions other issues (e.g., "fixes #123", "related to #456"), use mcp__github__get_issue to read those linked issues for additional context
+
+          3. Analyze and apply labels based on these guidelines:
+
+          CORE CATEGORIES (apply EXACTLY ONE - these are mutually exclusive; skip if applying too-long):
+          - bug: Reports of broken functionality OR PRs that fix bugs
+          - enhancement: New functions/endpoints, improvements to existing features, internal tooling, workflow improvements, minor new capabilities
+          - feature: ONLY for major headline functionality worthy of a blog post announcement (2-4 per release, never for issues)
+          - documentation: Primary change is to user-facing docs, examples, or guides
+
+          SPECIAL DOCUMENTATION RULES:
+          - DO NOT apply "documentation" label if PR only updates auto-generated SDK docs (docs/python-sdk/**)
+          - DO apply "documentation" label for significant user-facing documentation changes (guides, examples, API docs)
+          - Auto-generated docs updates should get appropriate category label (enhancement, bug, etc.) based on the underlying code changes
+
+          FEATURE vs ENHANCEMENT guidance:
+          - feature: Major systems like new auth systems, MCP composition, proxying MCP servers, major CLI commands that transform workflows
+          - enhancement: New functions/endpoints, internal workflows, CI improvements, developer tooling, refactoring, utilities, typical new CLI commands
+          - If unsure between feature/enhancement, choose enhancement
+
+          Note: If a PR fixes a bug, label it "bug" not "enhancement"
+
+          SPECIAL CATEGORY (can be combined with above):
+          - breaking change: Changes that break backward compatibility (in addition to core category)
+
+          PRIORITY (apply if clearly evident):
+          - high-priority: Critical bugs affecting many users, security issues, or blocking core functionality
+          - low-priority: Edge cases, nice-to-have improvements, or cosmetic issues
+          - Default to no priority label if unclear
+
+          STATUS (apply if applicable):
+          - needs more info: Issue lacks reproduction steps, error messages, or clear description
+          - invalid: Spam, completely off-topic, or nonsensical (often LLM-generated)
+          - too-long: Apply when an issue or PR doesn't conform to CONTRIBUTING.md. Issues should be a short problem description, an MRE, and expected vs. actual behavior — not a design document. PRs should have a focused description of the change — not a report. We don't need proposed solutions or design alternatives (the issue should describe the problem and let maintainers architect the fix), summaries of what tests cover, explanations of code we can read ourselves, or speculative root-cause analysis. Common LLM failure modes to watch for: verbose "diagnostic" writeups, large proposed patches in issue bodies, multi-section reports restating what's visible in the diff, numbered lists of possible approaches or solutions, "suggested" schemas/shapes/APIs, generic analysis that doesn't reference specific code, and "Notes" sections. But these are heuristics, not rules — a complex PR may legitimately need more context, and a brief submission can still be low-quality. Judge by whether the content helps a reviewer or just adds noise. When applying too-long, still apply the core category and area labels — too-long is a format signal, not a replacement for categorization. Issues still need to be findable by category.
+
+          WHEN APPLYING too-long: After labeling, post a brief comment using mcp__github__add_issue_comment:
+            "Thanks for the report. This issue goes beyond what our contributor guidelines ask for — we just need a short problem description and an MRE. Please see our [contributing guidelines](https://github.com/PrefectHQ/fastmcp/blob/main/CONTRIBUTING.md) and condense this issue. We'll triage it once it's trimmed down."
+            Use this exact text (or very close to it). Do not editorialize or add details.
+
+          AREA LABELS (apply ONLY when thematically central to the issue):
+          - cli: Issues primarily about FastMCP CLI commands (run, dev, install)
+          - client: Issues primarily about the Client SDK or client-side functionality
+          - server: Issues primarily about FastMCP server implementation
+          - auth: Authentication is the main concern (Bearer, JWT, OAuth, WorkOS)
+          - openapi: OpenAPI integration/parsing is the primary topic
+          - http: HTTP transport or networking is the main issue
+          - contrib: Specifically about community contributions in fastmcp_slim/fastmcp/contrib/
+          - tests: Issues primarily about testing infrastructure, CI/CD workflows, or test coverage
+          - security: Apply ONLY when the issue/PR addresses an exploitable vulnerability or hardens against one. Examples: SSRF, LFI, path traversal, injection, auth bypass allowing unauthorized access, scope escalation, open redirects. Do NOT apply for ordinary auth bugs (wrong scopes returned, token refresh logic, OAuth flow correctness) unless an attacker could exploit the bug to bypass access controls or escalate privileges. The key question: "Could a malicious actor exploit this?" If the answer is just "it breaks for legitimate users," that's a bug, not a security issue.
+
+          LABELING PRINCIPLES:
+          - Precision over recall: a missing label is a minor inconvenience; a wrong label sends the wrong people to the wrong issue. When in doubt, don't apply.
+          - Don't apply area labels just because a file in that area is mentioned — the issue must be PRIMARILY about that area.
+          - Apply 2-5 labels total typically (category + maybe priority + maybe 1-2 areas).
+          - For ambiguous cases (bug vs enhancement, which area label), prefer the more conservative choice or omit the uncertain label entirely.
+
+          META LABELS (rarely needed for issues):
+          - dependencies: Only for dependabot PRs or issues specifically about package updates
+          - DON'T MERGE: Only if PR author explicitly states it's not ready
+
+          4. Apply selected labels:
+             Use mcp__github__update_issue to apply your selected labels
+             DO NOT post any comments unless applying too-long (see above)
+          PROMPT_END
+          EOF
+
+      - name: Clean up stale Claude locks
+        run: rm -rf ~/.claude/.locks ~/.local/state/claude/locks || true
+
+      - name: Run Marvin for Issue Triage
+        uses: anthropics/claude-code-action@v1
+        with:
+          github_token: ${{ steps.marvin-token.outputs.token }}
+          bot_name: "Marvin Context Protocol"
+          prompt: ${{ steps.triage-prompt.outputs.PROMPT }}
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY_FOR_CI }}
+          allowed_non_write_users: "*"
+          allowed_bots: "marvin-context-protocol"
+          claude_args: |
+            --allowedTools Bash(gh label list),mcp__github__get_issue,mcp__github__get_issue_comments,mcp__github__update_issue,mcp__github__add_issue_comment,mcp__github__get_pull_request_files
+          settings: |
+            {
+              "model": "claude-sonnet-4-6",
+              "env": {
+                "GH_TOKEN": "${{ steps.marvin-token.outputs.token }}"
+              }
+            }
diff --git a/.github/workflows/minimize-resolved-reviews.yml b/.github/workflows/minimize-resolved-reviews.yml
new file mode 100644
index 0000000..26e00be
--- /dev/null
+++ b/.github/workflows/minimize-resolved-reviews.yml
@@ -0,0 +1,47 @@
+# Minimize resolved PR review comments to reduce noise.
+#
+# Runs automatically on review activity for same-repo PRs. Fork PRs are
+# skipped because GITHUB_TOKEN is read-only in that context. Collaborators
+# can comment "/tidy" on any PR (including forks) to trigger manually.
+
+name: Minimize Resolved Reviews
+
+on:
+  pull_request_review:
+    types: [submitted]
+  pull_request_review_comment:
+    types: [created, edited]
+  issue_comment:
+    types: [created]
+
+# Scope the group by event name so that the sibling events fired by a single
+# review action (pull_request_review + pull_request_review_comment, same instant)
+# don't cancel each other. Same-PR runs of the *same* event still supersede
+# cleanly, and the last one always completes.
+concurrency:
+  group: minimize-reviews-${{ github.event.pull_request.number || github.event.issue.number }}-${{ github.event_name }}
+  cancel-in-progress: true
+
+permissions:
+  pull-requests: write
+
+jobs:
+  minimize:
+    # /tidy comment: collaborators can trigger on any PR (token has write access)
+    # Review events: skip fork PRs where GITHUB_TOKEN lacks write permissions
+    if: >-
+      (
+        github.event_name == 'issue_comment' &&
+        github.event.issue.pull_request &&
+        contains(github.event.comment.body, '/tidy') &&
+        contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association)
+      ) || (
+        github.event_name != 'issue_comment' &&
+        github.event.pull_request.head.repo.full_name == github.event.pull_request.base.repo.full_name
+      )
+    runs-on: ubuntu-latest
+    steps:
+      - name: Minimize resolved review comments
+        uses: strawgate/minimize-resolved-pr-reviews@v0
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/publish-fastmcp-remote.yml b/.github/workflows/publish-fastmcp-remote.yml
new file mode 100644
index 0000000..9e2c679
--- /dev/null
+++ b/.github/workflows/publish-fastmcp-remote.yml
@@ -0,0 +1,87 @@
+name: Publish fastmcp-remote to PyPI
+
+on:
+  workflow_run:
+    workflows: ["Publish fastmcp-slim to PyPI"]
+    types: [completed]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  pypi-publish:
+    name: Upload fastmcp-remote to PyPI
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' || (github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'release')
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build fastmcp-remote
+        run: uv build --package fastmcp-remote
+
+      - name: Verify matching fastmcp-slim is published
+        run: |
+          SLIM_VERSION=$(python - <<'PY'
+          import email.parser
+          import re
+          import zipfile
+          from pathlib import Path
+
+          wheel = next(Path("dist").glob("fastmcp_remote-*.whl"))
+          metadata_name = next(
+              name for name in zipfile.ZipFile(wheel).namelist()
+              if name.endswith(".dist-info/METADATA")
+          )
+          metadata = email.parser.Parser().parsestr(
+              zipfile.ZipFile(wheel).read(metadata_name).decode()
+          )
+          for value in metadata.get_all("Requires-Dist", []):
+              requirement, _, marker = value.partition(";")
+              if marker.strip():
+                  continue
+              match = re.fullmatch(
+                  r"fastmcp-slim(?:\[[^\]]+\])?==([^;\s]+)",
+                  requirement.strip(),
+              )
+              if match:
+                  print(match.group(1))
+                  break
+          else:
+              raise RuntimeError("Could not find the base fastmcp-slim dependency")
+          PY
+          )
+
+          for attempt in {1..12}; do
+            if python - "$SLIM_VERSION" <<'PY'
+          import json
+          import sys
+          import urllib.request
+
+          version = sys.argv[1]
+          url = f"https://pypi.org/pypi/fastmcp-slim/{version}/json"
+          with urllib.request.urlopen(url, timeout=30) as response:
+              json.load(response)
+          PY
+            then
+              exit 0
+            fi
+
+            echo "fastmcp-slim ${SLIM_VERSION} is not available on PyPI yet; retrying (${attempt}/12)."
+            sleep 10
+          done
+
+          echo "fastmcp-slim ${SLIM_VERSION} is not available on PyPI; refusing to publish fastmcp-remote." >&2
+          exit 1
+
+      - name: Publish fastmcp-remote to PyPI
+        run: uv publish -v dist/fastmcp_remote-*.tar.gz dist/fastmcp_remote-*.whl
diff --git a/.github/workflows/publish-fastmcp-slim.yml b/.github/workflows/publish-fastmcp-slim.yml
new file mode 100644
index 0000000..9fdc696
--- /dev/null
+++ b/.github/workflows/publish-fastmcp-slim.yml
@@ -0,0 +1,30 @@
+name: Publish fastmcp-slim to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  pypi-publish:
+    name: Upload fastmcp-slim to PyPI
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build fastmcp-slim
+        run: uv build --package fastmcp-slim
+
+      - name: Publish fastmcp-slim to PyPI
+        run: uv publish -v dist/fastmcp_slim-*.tar.gz dist/fastmcp_slim-*.whl
diff --git a/.github/workflows/publish-fastmcp.yml b/.github/workflows/publish-fastmcp.yml
new file mode 100644
index 0000000..3e22fe9
--- /dev/null
+++ b/.github/workflows/publish-fastmcp.yml
@@ -0,0 +1,151 @@
+name: Publish fastmcp to PyPI
+
+on:
+  workflow_run:
+    workflows: ["Publish fastmcp-slim to PyPI"]
+    types: [completed]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  pypi-publish:
+    name: Upload fastmcp to PyPI
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' || (github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'release')
+    outputs:
+      is_prerelease: ${{ steps.package_version.outputs.is_prerelease }}
+      version: ${{ steps.package_version.outputs.version }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build fastmcp
+        run: uv build --package fastmcp
+
+      - name: Read built package version
+        id: package_version
+        run: |
+          python - <<'PY' >> "$GITHUB_OUTPUT"
+          import email.parser
+          import re
+          import zipfile
+          from pathlib import Path
+
+          wheel = next(Path("dist").glob("fastmcp-*.whl"))
+          metadata_name = next(
+              name for name in zipfile.ZipFile(wheel).namelist()
+              if name.endswith(".dist-info/METADATA")
+          )
+          metadata = email.parser.Parser().parsestr(
+              zipfile.ZipFile(wheel).read(metadata_name).decode()
+          )
+          version = metadata["Version"]
+          public_version = version.partition("+")[0]
+          is_prerelease = bool(
+              re.search(
+                  r"(?i)(?:^|[0-9.])(?:a|b|c|rc|alpha|beta|pre|preview|dev)[0-9]*",
+                  public_version,
+              )
+          )
+          print(f"version={version}")
+          print(f"is_prerelease={str(is_prerelease).lower()}")
+          PY
+
+      - name: Verify matching fastmcp-slim is published
+        run: |
+          SLIM_VERSION=$(python - <<'PY'
+          import email.parser
+          import re
+          import zipfile
+          from pathlib import Path
+
+          wheel = next(Path("dist").glob("fastmcp-*.whl"))
+          metadata_name = next(
+              name for name in zipfile.ZipFile(wheel).namelist()
+              if name.endswith(".dist-info/METADATA")
+          )
+          metadata = email.parser.Parser().parsestr(
+              zipfile.ZipFile(wheel).read(metadata_name).decode()
+          )
+          for value in metadata.get_all("Requires-Dist", []):
+              requirement, _, marker = value.partition(";")
+              if marker.strip():
+                  continue
+              match = re.fullmatch(
+                  r"fastmcp-slim(?:\[[^\]]+\])?==([^;\s]+)",
+                  requirement.strip(),
+              )
+              if match:
+                  print(match.group(1))
+                  break
+          else:
+              raise RuntimeError("Could not find the base fastmcp-slim dependency")
+          PY
+          )
+
+          for attempt in {1..12}; do
+            if python - "$SLIM_VERSION" <<'PY'
+          import json
+          import sys
+          import urllib.request
+
+          version = sys.argv[1]
+          url = f"https://pypi.org/pypi/fastmcp-slim/{version}/json"
+          with urllib.request.urlopen(url, timeout=30) as response:
+              json.load(response)
+          PY
+            then
+              exit 0
+            fi
+
+            echo "fastmcp-slim ${SLIM_VERSION} is not available on PyPI yet; retrying (${attempt}/12)."
+            sleep 10
+          done
+
+          echo "fastmcp-slim ${SLIM_VERSION} is not available on PyPI; refusing to publish fastmcp." >&2
+          exit 1
+
+      - name: Publish fastmcp to PyPI
+        run: uv publish -v dist/fastmcp-*.tar.gz dist/fastmcp-*.whl
+
+  update-published-docs:
+    name: Update published-docs branch
+    runs-on: ubuntu-latest
+    needs: pypi-publish
+    if: github.event_name == 'workflow_run' && github.event.workflow_run.event == 'release' && needs['pypi-publish'].outputs.is_prerelease != 'true'
+    timeout-minutes: 2
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.workflow_run.head_sha }}
+
+      - name: Check release line
+        id: release_line
+        env:
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          git fetch origin "${DEFAULT_BRANCH}:refs/remotes/origin/${DEFAULT_BRANCH}"
+          if git merge-base --is-ancestor HEAD "refs/remotes/origin/${DEFAULT_BRANCH}"; then
+            echo "update_published_docs=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "update_published_docs=false" >> "$GITHUB_OUTPUT"
+            echo "Release commit is not on ${DEFAULT_BRANCH}; skipping published-docs update."
+          fi
+
+      - name: Point published-docs at published release
+        if: steps.release_line.outputs.update_published_docs == 'true'
+        run: git push --force origin "HEAD:published-docs"
diff --git a/.github/workflows/require-issue-link.yml b/.github/workflows/require-issue-link.yml
new file mode 100644
index 0000000..4596dd4
--- /dev/null
+++ b/.github/workflows/require-issue-link.yml
@@ -0,0 +1,587 @@
+# Require external PRs to reference an issue with an auto-close keyword
+# (e.g. "Fixes #123") AND have the PR author assigned to that issue.
+# Otherwise the PR is labeled "missing-issue-link", commented on, and
+# closed. CONTRIBUTING.md requires external contributors to be assigned to
+# an issue before opening a PR; this enforces that.
+#
+# Adapted from langchain-ai/langchain's require_issue_link.yml. Differences:
+#   - Self-contained: it does NOT depend on a separate labeler workflow
+#     applying an "external" label first, so it can run on `opened`.
+#   - "External" is determined authoritatively, in-script, from the PR
+#     author's repo collaborator permission level — NOT from the event
+#     payload's author_association. author_association reports MEMBER only
+#     for *public* org members; a maintainer whose org membership is
+#     private appears as CONTRIBUTOR/NONE, so gating on it would wrongly
+#     enforce against private-member maintainers. getCollaboratorPermission
+#     reflects effective write access regardless of membership visibility.
+#   - The enforcement path is a single github-script step (the upstream
+#     version is split across four, forcing the label/comment/reopen helpers
+#     to be duplicated per scope).
+#   - Issue assignment events are handled in this same workflow so assigning
+#     the linked issue reopens previously closed PRs automatically.
+#
+# Maintainer override: reopen the PR, or remove the "missing-issue-link"
+# label — either applies a sticky "bypass-issue-check" label and reopens.
+
+name: Require Issue Link
+
+on:
+  pull_request_target:
+    # SECURITY: pull_request_target runs with repo write scope against the
+    # BASE repo. NEVER check out or execute PR-head code here — it would run
+    # with these permissions. This workflow only reads the PR payload and
+    # calls the API; it never checks anything out.
+    # ready_for_review matters because the job skips drafts: without it a
+    # draft opened with no issue link would never be checked when it later
+    # becomes reviewable.
+    types: [opened, edited, reopened, ready_for_review, labeled, unlabeled]
+  issues:
+    # Assignment is what makes a previously closed "not assigned" PR compliant,
+    # so it needs a separate event path that finds and reopens matching PRs.
+    types: [assigned]
+
+# Dry run: when 'false' the check still runs and logs its verdict but makes
+# NO mutations at all (no label, comment, close, reopen, or failure). Flip
+# to 'true' to enforce.
+env:
+  ENFORCE_ISSUE_LINK: "true"
+
+permissions:
+  contents: read
+
+jobs:
+  check-issue-link:
+    # Cheap pre-filters only. Maintainer detection is deliberately NOT done
+    # here: the job-level `if` can't call the API, and author_association is
+    # unreliable for private org members (see file header). The job runs,
+    # then the script resolves the author's real permission and exits early
+    # for maintainers.
+    #
+    # Gate: only run on pull_request_target events. The workflow also listens
+    # to `issues.assigned` (handled by reopen-on-assignment below), and without
+    # this guard the job would also fire there — `github.event.pull_request` is
+    # null on an issues event, so `...draft == false` coerces to true and the
+    # script then dereferences a missing PR and crashes. Beyond the event type,
+    # skip drafts, bots, and already-bypassed/trusted PRs, and allow the primary
+    # actions plus the one maintainer-override action we care about (removing
+    # the missing-issue-link label).
+    if: >-
+      github.event_name == 'pull_request_target' &&
+      github.event.pull_request.draft == false &&
+      !endsWith(github.actor, '[bot]') &&
+      !contains(github.event.pull_request.labels.*.name, 'trusted-contributor') &&
+      !contains(github.event.pull_request.labels.*.name, 'bypass-issue-check') &&
+      (
+        (github.event.action != 'labeled' && github.event.action != 'unlabeled') ||
+        (github.event.action == 'unlabeled' && github.event.label.name == 'missing-issue-link')
+      )
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    concurrency:
+      group: require-issue-link-${{ github.event.pull_request.number }}
+      cancel-in-progress: false
+    permissions:
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: Enforce issue link
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const pr = context.payload.pull_request;
+            const prNumber = pr.number;
+            const action = context.payload.action;
+            const enforce = process.env.ENFORCE_ISSUE_LINK === 'true';
+            const LABEL = 'missing-issue-link';
+            const MARKER = '<!-- require-issue-link -->';
+
+            // Dry-run guard: every mutating call goes through this so that
+            // ENFORCE_ISSUE_LINK=false means strictly read-only.
+            async function mutate(description, fn) {
+              if (!enforce) {
+                console.log(`[dry-run] would ${description}`);
+                return;
+              }
+              await fn();
+            }
+
+            // Authoritative maintainer check. Uses collaborator permission,
+            // not org membership or author_association:
+            //   - GITHUB_TOKEN is an app token and is never an org member,
+            //     so the org-membership endpoint always 403s.
+            //   - author_association reports MEMBER only for *public* org
+            //     members; a private-member maintainer shows as
+            //     CONTRIBUTOR/NONE. Permission level is visibility-
+            //     independent and reflects effective access.
+            // 404 (not a collaborator) → not a maintainer. Other errors
+            // (rate limit, 5xx) MUST throw: silently treating them as
+            // "not a maintainer" could wrongly close a maintainer's PR.
+            // A throw aborts the script before any close/label call, so the
+            // job fails red and the PR is left untouched — the safe direction.
+            async function hasWriteAccess(username) {
+              if (!username) throw new Error('No username — cannot check permissions');
+              try {
+                const { data } = await github.rest.repos.getCollaboratorPermissionLevel({
+                  owner, repo, username,
+                });
+                const ok = ['admin', 'maintain', 'write'].includes(data.permission);
+                console.log(`${username}: ${data.permission} — ${ok ? 'maintainer' : 'not a maintainer'}`);
+                return ok;
+              } catch (e) {
+                if (e.status === 404) {
+                  console.log(`${username} is not a collaborator — not a maintainer`);
+                  return false;
+                }
+                throw new Error(
+                  `Permission check failed for ${username} (HTTP ${e.status ?? 'unknown'}): ${e.message}`,
+                );
+              }
+            }
+
+            async function addLabel() {
+              await mutate(`label PR #${prNumber} "${LABEL}"`, async () => {
+                try {
+                  await github.rest.issues.getLabel({ owner, repo, name: LABEL });
+                } catch (e) {
+                  if (e.status !== 404) throw e;
+                  try {
+                    await github.rest.issues.createLabel({ owner, repo, name: LABEL, color: 'b76e79' });
+                  } catch (createErr) {
+                    // 422 = created by a concurrent run between GET and POST.
+                    if (createErr.status !== 422) throw createErr;
+                  }
+                }
+                await github.rest.issues.addLabels({
+                  owner, repo, issue_number: prNumber, labels: [LABEL],
+                });
+              });
+            }
+
+            async function minimizeStaleComment() {
+              try {
+                const comments = await github.paginate(
+                  github.rest.issues.listComments,
+                  { owner, repo, issue_number: prNumber, per_page: 100 },
+                );
+                const stale = comments.find(c => c.body && c.body.includes(MARKER));
+                if (!stale) return;
+                await mutate(`minimize stale comment ${stale.id}`, () => github.graphql(`
+                  mutation($id: ID!) {
+                    minimizeComment(input: {subjectId: $id, classifier: OUTDATED}) {
+                      minimizedComment { isMinimized }
+                    }
+                  }
+                `, { id: stale.node_id }));
+              } catch (e) {
+                core.warning(`Could not minimize stale comment on PR #${prNumber}: ${e.message}`);
+              }
+            }
+
+            // Shared "this PR passes" cleanup: drop the label, reopen, and
+            // retire any stale enforcement comment.
+            //
+            // For the normal pass paths we only reopen if THIS workflow had
+            // closed the PR — inferred from the label still being on the
+            // payload. The maintainer-override paths pass forceReopen: the
+            // `unlabeled` event payload no longer carries the just-removed
+            // label, so the heuristic can't see it; without forcing, the
+            // advertised "remove the label to bypass" gesture would leave
+            // the PR closed.
+            async function clearEnforcement(forceReopen = false) {
+              await mutate(`remove "${LABEL}" from PR #${prNumber}`, async () => {
+                try {
+                  await github.rest.issues.removeLabel({
+                    owner, repo, issue_number: prNumber, name: LABEL,
+                  });
+                } catch (e) {
+                  if (e.status !== 404) throw e;
+                }
+              });
+              const hadLabel = pr.labels.map(l => l.name).includes(LABEL);
+              if (pr.state === 'closed' && (forceReopen || hadLabel)) {
+                await mutate(`reopen PR #${prNumber}`, async () => {
+                  await github.rest.pulls.update({
+                    owner, repo, pull_number: prNumber, state: 'open',
+                  });
+                });
+              }
+              await minimizeStaleComment();
+            }
+
+            async function applyBypass(reason) {
+              console.log(reason);
+              await clearEnforcement(true);
+              await mutate(`add sticky "bypass-issue-check" to PR #${prNumber}`, async () => {
+                try {
+                  await github.rest.issues.getLabel({ owner, repo, name: 'bypass-issue-check' });
+                } catch (e) {
+                  if (e.status !== 404) throw e;
+                  try {
+                    await github.rest.issues.createLabel({
+                      owner, repo, name: 'bypass-issue-check', color: '0e8a16',
+                    });
+                  } catch (createErr) {
+                    if (createErr.status !== 422) throw createErr;
+                  }
+                }
+                await github.rest.issues.addLabels({
+                  owner, repo, issue_number: prNumber, labels: ['bypass-issue-check'],
+                });
+              });
+            }
+
+            // ── Maintainer-authored PRs are exempt entirely ────────────────
+            if (await hasWriteAccess(pr.user.login)) {
+              console.log(`PR author ${pr.user.login} has write access — exempt`);
+              await clearEnforcement();
+              return;
+            }
+
+            const sender = context.payload.sender?.login;
+
+            // ── Maintainer override: removed the "missing-issue-link" label ─
+            if (action === 'unlabeled') {
+              if (await hasWriteAccess(sender)) {
+                await applyBypass(`Maintainer ${sender} removed ${LABEL} from PR #${prNumber} — bypassing`);
+                return;
+              }
+              // Only triage/admin can manage labels, so a non-write actor
+              // reaching here is rare (triage role). Fall through to the
+              // normal check, which recomputes link + assignment and
+              // re-enforces with the correct message if still failing.
+              console.log(`Non-maintainer ${sender} removed ${LABEL} — re-checking`);
+            }
+
+            // ── Maintainer override: reopened a PR we had closed ───────────
+            if (
+              action === 'reopened' &&
+              pr.labels.map(l => l.name).includes(LABEL) &&
+              (await hasWriteAccess(sender))
+            ) {
+              await applyBypass(`Maintainer ${sender} reopened PR #${prNumber} — bypassing`);
+              return;
+            }
+
+            // ── Race guard: re-read live labels ────────────────────────────
+            const { data: liveLabels } = await github.rest.issues.listLabelsOnIssue({
+              owner, repo, issue_number: prNumber,
+            });
+            const liveNames = liveLabels.map(l => l.name);
+            if (liveNames.includes('trusted-contributor') || liveNames.includes('bypass-issue-check')) {
+              console.log('PR carries trusted-contributor or bypass-issue-check — clearing any prior enforcement');
+              await clearEnforcement();
+              return;
+            }
+
+            // ── The actual check: an auto-close keyword + issue number ─────
+            const body = pr.body || '';
+            // Match GitHub's auto-close keywords against any reference form
+            // that GitHub itself honors: bare `#123`, the `owner/repo#123`
+            // shorthand, and the full issue URL. Scope the qualified forms to
+            // THIS repo — GitHub only auto-closes same-repo issues, so a
+            // cross-repo reference must not be resolved against our numbering.
+            const repoRef = `${owner}/${repo}`.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const pattern = new RegExp(
+              '(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\\s*:?\\s*' +
+                `(?:${repoRef}#|#|https?://github\\.com/${repoRef}/issues/)(\\d+)`,
+              'gi',
+            );
+            const matches = [...body.matchAll(pattern)];
+
+            if (matches.length === 0) {
+              console.log('No issue link found in PR body');
+              await enforceFailure('no-link');
+              return;
+            }
+
+            // The author must be assigned to at least one linked issue.
+            // CONTRIBUTING.md requires external contributors to be assigned
+            // before opening a PR (so maintainers can deconflict / steer
+            // approach first).
+            const MAX_ISSUES = 5;
+            const allNumbers = [...new Set(matches.map(m => parseInt(m[1], 10)))];
+            const numbers = allNumbers.slice(0, MAX_ISSUES);
+            if (allNumbers.length > MAX_ISSUES) {
+              core.warning(`PR references ${allNumbers.length} issues — checking only the first ${MAX_ISSUES}`);
+            }
+
+            const prAuthor = pr.user.login.toLowerCase();
+            let sawRealIssue = false;
+            let assignedToAny = false;
+            for (const num of numbers) {
+              let issue;
+              try {
+                ({ data: issue } = await github.rest.issues.get({
+                  owner, repo, issue_number: num,
+                }));
+              } catch (e) {
+                if (e.status === 404) {
+                  console.log(`#${num} does not exist — ignoring`);
+                  continue;
+                }
+                // Same safe-direction rule as hasWriteAccess: a transient
+                // error must not be read as "not assigned" and close the PR.
+                throw new Error(`Cannot fetch issue #${num} (HTTP ${e.status ?? 'unknown'}): ${e.message}`);
+              }
+              sawRealIssue = true;
+              const assignees = (issue.assignees || []).map(a => a.login.toLowerCase());
+              if (assignees.includes(prAuthor)) {
+                console.log(`PR author ${pr.user.login} is assigned to #${num}`);
+                assignedToAny = true;
+                break;
+              }
+              console.log(`PR author ${pr.user.login} is NOT assigned to #${num} (assignees: ${assignees.join(', ') || 'none'})`);
+            }
+
+            if (!sawRealIssue) {
+              console.log('Referenced issue(s) do not exist');
+              await enforceFailure('no-link');
+              return;
+            }
+            if (!assignedToAny) {
+              await enforceFailure('not-assigned');
+              return;
+            }
+
+            console.log('Linked and assigned — clearing any prior enforcement');
+            await clearEnforcement();
+
+            // ── Label, comment, close, and fail ────────────────────────────
+            // `kind`: 'no-link' (no valid issue reference) or 'not-assigned'
+            // (referenced an issue, but the author isn't assigned to it).
+            async function enforceFailure(kind) {
+              await addLabel();
+
+              const intro = kind === 'no-link'
+                ? '**This PR has been automatically closed** because its description does not reference a tracked issue.'
+                : '**This PR has been automatically closed** because you are not assigned to the issue it references.';
+              const steps = kind === 'no-link'
+                ? [
+                    `1. Find or [open an issue](https://github.com/${owner}/${repo}/issues/new/choose) describing the change.`,
+                    '2. Comment on the issue to ask a maintainer to assign it to you.',
+                    '3. Add `Fixes #<issue>`, `Closes #<issue>`, or `Resolves #<issue>` to the PR description.',
+                    '4. Once you are assigned and the link is present, the PR reopens automatically.',
+                  ]
+                : [
+                    '1. Comment on the linked issue to ask a maintainer to assign it to you.',
+                    '2. Once a maintainer assigns you, the PR reopens automatically.',
+                  ];
+
+              const commentBody = [
+                MARKER,
+                intro,
+                '',
+                `Per [CONTRIBUTING.md](https://github.com/${owner}/${repo}/blob/main/CONTRIBUTING.md), an external PR must reference an issue that is assigned to its author. To proceed:`,
+                '',
+                ...steps,
+                '',
+                `*Maintainers: reopen this PR or remove the \`${LABEL}\` label to bypass this check.*`,
+              ].join('\n');
+
+              const comments = await github.paginate(
+                github.rest.issues.listComments,
+                { owner, repo, issue_number: prNumber, per_page: 100 },
+              );
+              const existing = comments.find(c => c.body && c.body.includes(MARKER));
+              if (!existing) {
+                await mutate(`comment on PR #${prNumber}`, () => github.rest.issues.createComment({
+                  owner, repo, issue_number: prNumber, body: commentBody,
+                }));
+              } else if (existing.body !== commentBody) {
+                await mutate(`update comment ${existing.id}`, () => github.rest.issues.updateComment({
+                  owner, repo, comment_id: existing.id, body: commentBody,
+                }));
+              } else {
+                console.log('Requirement comment already present — skipping');
+              }
+
+              if (pr.state === 'open') {
+                await mutate(`close PR #${prNumber}`, () => github.rest.pulls.update({
+                  owner, repo, pull_number: prNumber, state: 'closed',
+                }));
+              }
+
+              if (enforce) {
+                core.setFailed(
+                  kind === 'no-link'
+                    ? 'PR must reference a tracked issue using an auto-close keyword (e.g. "Fixes #123").'
+                    : 'PR author must be assigned to the referenced issue.',
+                );
+              }
+            }
+
+  reopen-on-assignment:
+    if: github.event_name == 'issues' && github.event.action == 'assigned' && !github.event.issue.pull_request
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    concurrency:
+      group: reopen-on-assignment-${{ github.event.issue.number }}-${{ github.event.assignee.login }}
+      cancel-in-progress: false
+    permissions:
+      actions: write
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: Reopen linked PRs
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const issueNumber = context.payload.issue.number;
+            const assignee = context.payload.assignee.login;
+            const enforce = process.env.ENFORCE_ISSUE_LINK === 'true';
+            const LABEL = 'missing-issue-link';
+            const MARKER = '<!-- require-issue-link -->';
+            // Match GitHub's auto-close keywords against any reference form
+            // that GitHub itself honors: bare `#123`, the `owner/repo#123`
+            // shorthand, and the full issue URL. Scope the qualified forms to
+            // THIS repo — GitHub only auto-closes same-repo issues, so a
+            // cross-repo reference must not be resolved against our numbering.
+            const repoRef = `${owner}/${repo}`.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const pattern = new RegExp(
+              '(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\\s*:?\\s*' +
+                `(?:${repoRef}#|#|https?://github\\.com/${repoRef}/issues/)(\\d+)`,
+              'gi',
+            );
+
+            async function mutate(description, fn) {
+              if (!enforce) {
+                console.log(`[dry-run] would ${description}`);
+                return;
+              }
+              await fn();
+            }
+
+            console.log(`Issue #${issueNumber} assigned to ${assignee} — searching for closed PRs to reopen`);
+
+            const q = [
+              'is:pr',
+              'is:closed',
+              `author:${assignee}`,
+              `label:${LABEL}`,
+              `repo:${owner}/${repo}`,
+            ].join(' ');
+
+            let search;
+            try {
+              ({ data: search } = await github.rest.search.issuesAndPullRequests({
+                q,
+                per_page: 30,
+              }));
+            } catch (e) {
+              throw new Error(
+                `Failed to search closed PRs for ${assignee} after assigning #${issueNumber} ` +
+                  `(HTTP ${e.status ?? 'unknown'}): ${e.message}`,
+              );
+            }
+
+            if (search.total_count === 0) {
+              console.log('No matching closed PRs found');
+              return;
+            }
+
+            console.log(`Found ${search.total_count} candidate PR(s)`);
+
+            for (const item of search.items) {
+              const prNumber = item.number;
+
+              let issue;
+              try {
+                ({ data: issue } = await github.rest.issues.get({
+                  owner, repo, issue_number: prNumber,
+                }));
+              } catch (e) {
+                throw new Error(`Cannot fetch PR #${prNumber} issue data (HTTP ${e.status ?? 'unknown'}): ${e.message}`);
+              }
+
+              const labels = (issue.labels || []).map(label => label.name);
+              if (labels.includes('bypass-issue-check')) {
+                console.log(`PR #${prNumber} already has bypass-issue-check — skipping`);
+                continue;
+              }
+
+              const body = issue.body || '';
+              const referencedIssues = [...body.matchAll(pattern)].map(match => parseInt(match[1], 10));
+              if (!referencedIssues.includes(issueNumber)) {
+                console.log(`PR #${prNumber} does not reference #${issueNumber} — skipping`);
+                continue;
+              }
+
+              try {
+                await mutate(`reopen PR #${prNumber}`, () => github.rest.pulls.update({
+                  owner, repo, pull_number: prNumber, state: 'open',
+                }));
+              } catch (e) {
+                if (e.status === 422) {
+                  core.warning(`Cannot reopen PR #${prNumber}: the head branch was likely deleted`);
+                  await mutate(`comment on unreopenable PR #${prNumber}`, () => github.rest.issues.createComment({
+                    owner,
+                    repo,
+                    issue_number: prNumber,
+                    body:
+                      `You have been assigned to #${issueNumber}, but this PR could not be ` +
+                      'reopened because the head branch has been deleted. Please open a new PR ' +
+                      'referencing the issue.',
+                  }));
+                  continue;
+                }
+                throw e;
+              }
+
+              await mutate(`remove "${LABEL}" from PR #${prNumber}`, async () => {
+                try {
+                  await github.rest.issues.removeLabel({
+                    owner, repo, issue_number: prNumber, name: LABEL,
+                  });
+                } catch (e) {
+                  if (e.status !== 404) throw e;
+                }
+              });
+
+              try {
+                const comments = await github.paginate(
+                  github.rest.issues.listComments,
+                  { owner, repo, issue_number: prNumber, per_page: 100 },
+                );
+                const stale = comments.find(comment => comment.body && comment.body.includes(MARKER));
+                if (stale) {
+                  await mutate(`minimize stale comment ${stale.id}`, () => github.graphql(`
+                    mutation($id: ID!) {
+                      minimizeComment(input: {subjectId: $id, classifier: OUTDATED}) {
+                        minimizedComment { isMinimized }
+                      }
+                    }
+                  `, { id: stale.node_id }));
+                }
+              } catch (e) {
+                core.warning(`Could not minimize stale comment on PR #${prNumber}: ${e.message}`);
+              }
+
+              try {
+                const { data: pr } = await github.rest.pulls.get({
+                  owner, repo, pull_number: prNumber,
+                });
+                const { data: runs } = await github.rest.actions.listWorkflowRuns({
+                  owner,
+                  repo,
+                  workflow_id: 'require-issue-link.yml',
+                  head_sha: pr.head.sha,
+                  status: 'failure',
+                  per_page: 1,
+                });
+                if (runs.workflow_runs.length === 0) {
+                  console.log(`No failed require-issue-link runs found for PR #${prNumber}`);
+                  continue;
+                }
+                await mutate(`re-run failed require-issue-link run for PR #${prNumber}`, () =>
+                  github.rest.actions.reRunWorkflowFailedJobs({
+                    owner, repo, run_id: runs.workflow_runs[0].id,
+                  }),
+                );
+              } catch (e) {
+                core.warning(`Could not re-run require-issue-link for PR #${prNumber}: ${e.message}`);
+              }
+            }
diff --git a/.github/workflows/run-schema-crash-test.yml b/.github/workflows/run-schema-crash-test.yml
new file mode 100644
index 0000000..6c9c766
--- /dev/null
+++ b/.github/workflows/run-schema-crash-test.yml
@@ -0,0 +1,55 @@
+name: Schema Crash Test
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "fastmcp_slim/fastmcp/utilities/json_schema_type.py"
+      - "fastmcp_slim/fastmcp/utilities/json_schema.py"
+      - "fastmcp_slim/fastmcp/utilities/openapi/**"
+      - "fastmcp_slim/fastmcp/server/providers/openapi/**"
+      - "fastmcp_slim/fastmcp/client/mixins/tools.py"
+      - "tests/utilities/json_schema_type/test_real_world_schemas.py"
+      - ".github/workflows/run-schema-crash-test.yml"
+
+  pull_request:
+    paths:
+      - "fastmcp_slim/fastmcp/utilities/json_schema_type.py"
+      - "fastmcp_slim/fastmcp/utilities/json_schema.py"
+      - "fastmcp_slim/fastmcp/utilities/openapi/**"
+      - "fastmcp_slim/fastmcp/server/providers/openapi/**"
+      - "fastmcp_slim/fastmcp/client/mixins/tools.py"
+      - "tests/utilities/json_schema_type/test_real_world_schemas.py"
+      - ".github/workflows/run-schema-crash-test.yml"
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  schema_crash_test:
+    name: "Real-world schema crash test (232K schemas)"
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Clone openapi-directory
+        run: git clone --depth 1 https://github.com/APIs-guru/openapi-directory.git /tmp/openapi-directory
+
+      - name: Run schema crash test
+        env:
+          RUN_REAL_WORLD_SCHEMA_TEST: "1"
+          OPENAPI_DIRECTORY_PATH: /tmp/openapi-directory
+        run: uv run pytest tests/utilities/json_schema_type/test_real_world_schemas.py -m integration -v -n auto --timeout-method=thread
diff --git a/.github/workflows/run-static.yml b/.github/workflows/run-static.yml
new file mode 100644
index 0000000..66ddb5c
--- /dev/null
+++ b/.github/workflows/run-static.yml
@@ -0,0 +1,41 @@
+name: Run static analysis
+
+env:
+  PY_COLORS: 1
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "fastmcp_slim/**"
+      - "fastmcp_remote/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/**"
+
+  # run on all pull requests because these checks are required and will block merges otherwise
+  pull_request:
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  static_analysis:
+    timeout-minutes: 2
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Setup uv
+        uses: ./.github/actions/setup-uv
+        with:
+          resolution: locked
+
+      - name: Run prek
+        uses: j178/prek-action@v2
+        env:
+          SKIP: no-commit-to-branch
diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml
new file mode 100644
index 0000000..aa57777
--- /dev/null
+++ b/.github/workflows/run-tests.yml
@@ -0,0 +1,267 @@
+name: Tests
+
+env:
+  PY_COLORS: 1
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "fastmcp_slim/**"
+      - "fastmcp_remote/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/**"
+
+  # run on all pull requests because these checks are required and will block merges otherwise
+  pull_request:
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  run_tests:
+    name: "Tests: Python ${{ matrix.python-version }} on ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10"]
+        include:
+          - os: ubuntu-latest
+            python-version: "3.13"
+      fail-fast: false
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Setup uv
+        uses: ./.github/actions/setup-uv
+        with:
+          python-version: ${{ matrix.python-version }}
+          resolution: locked
+
+      - name: Run unit tests
+        uses: ./.github/actions/run-pytest
+
+      - name: Run client process tests
+        uses: ./.github/actions/run-pytest
+        with:
+          test-type: client_process
+
+  run_tests_lowest_direct:
+    name: "Tests with lowest-direct dependencies"
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Setup uv (lowest-direct)
+        uses: ./.github/actions/setup-uv
+        with:
+          resolution: lowest-direct
+
+      - name: Run unit tests
+        uses: ./.github/actions/run-pytest
+
+      - name: Run client process tests
+        uses: ./.github/actions/run-pytest
+        with:
+          test-type: client_process
+
+  run_conformance_tests:
+    name: "MCP conformance tests"
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Setup uv
+        uses: ./.github/actions/setup-uv
+        with:
+          resolution: locked
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+
+      - name: Run conformance tests
+        uses: ./.github/actions/run-pytest
+        with:
+          test-type: conformance
+
+  run_integration_tests:
+    name: "Integration tests"
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Setup uv
+        uses: ./.github/actions/setup-uv
+        with:
+          resolution: locked
+
+      - name: Run integration tests
+        uses: ./.github/actions/run-pytest
+        with:
+          test-type: integration
+        env:
+          FASTMCP_GITHUB_TOKEN: ${{ secrets.FASTMCP_GITHUB_TOKEN }}
+          FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID: ${{ secrets.FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID }}
+          FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET: ${{ secrets.FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET }}
+
+  package_install_smoke:
+    name: "Package install smoke"
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Setup uv
+        uses: ./.github/actions/setup-uv
+        with:
+          resolution: locked
+
+      - name: Build package wheels
+        run: uv build --all-packages --wheel --out-dir /tmp/fastmcp-dist
+
+      - name: Install bare slim wheel
+        run: |
+          uv venv /tmp/fastmcp-slim-bare-smoke
+          SLIM_WHEEL=$(ls /tmp/fastmcp-dist/fastmcp_slim-*.whl)
+          uv pip install --python /tmp/fastmcp-slim-bare-smoke/bin/python "$SLIM_WHEEL"
+          /tmp/fastmcp-slim-bare-smoke/bin/python - <<'PY'
+          from importlib.metadata import entry_points
+
+          import fastmcp
+          import fastmcp.settings
+
+          assert any(ep.name == "fastmcp" for ep in entry_points(group="console_scripts"))
+
+          try:
+              from fastmcp.cli import app
+          except ImportError as exc:
+              assert "FastMCP CLI support is not installed" in str(exc)
+          else:
+              raise AssertionError(f"bare fastmcp-slim unexpectedly imported CLI app {app!r}")
+
+          try:
+              fastmcp.FastMCP
+          except ImportError as exc:
+              assert "fastmcp-slim[server]" in str(exc)
+          else:
+              raise AssertionError("bare fastmcp-slim unexpectedly imported FastMCP")
+          PY
+
+      - name: Install client slim wheel
+        run: |
+          uv venv /tmp/fastmcp-slim-client-smoke
+          SLIM_WHEEL=$(ls /tmp/fastmcp-dist/fastmcp_slim-*.whl)
+          uv pip install --python /tmp/fastmcp-slim-client-smoke/bin/python "${SLIM_WHEEL}[client]"
+          /tmp/fastmcp-slim-client-smoke/bin/python - <<'PY'
+          from importlib.metadata import entry_points
+
+          from fastmcp import Client
+          from fastmcp.client.transports import StdioTransport, StreamableHttpTransport
+          from fastmcp.mcp_config import MCPConfig
+
+          assert any(ep.name == "fastmcp" for ep in entry_points(group="console_scripts"))
+
+          try:
+              from fastmcp.cli import app
+          except ImportError as exc:
+              assert "FastMCP CLI support is not installed" in str(exc)
+          else:
+              raise AssertionError(f"client-only slim unexpectedly imported CLI app {app!r}")
+
+          assert Client("https://example.com/mcp")
+          assert StreamableHttpTransport("https://example.com/mcp")
+          assert StdioTransport(command="uvx", args=["demo"])
+          assert MCPConfig.from_dict({"mcpServers": {"demo": {"url": "https://example.com/mcp"}}})
+
+          try:
+              from fastmcp import FastMCP
+          except ImportError as exc:
+              assert "fastmcp-slim[server]" in str(exc)
+          else:
+              raise AssertionError(f"client-only slim unexpectedly imported {FastMCP!r}")
+          PY
+
+      - name: Install server slim wheel
+        run: |
+          uv venv /tmp/fastmcp-slim-server-smoke
+          SLIM_WHEEL=$(ls /tmp/fastmcp-dist/fastmcp_slim-*.whl)
+          uv pip install --python /tmp/fastmcp-slim-server-smoke/bin/python "${SLIM_WHEEL}[server]"
+          /tmp/fastmcp-slim-server-smoke/bin/python - <<'PY'
+          from importlib.metadata import entry_points
+
+          from fastmcp import FastMCP
+          from fastmcp.cli import app
+
+          assert any(
+              ep.name == "fastmcp" and ep.value == "fastmcp.cli:app"
+              for ep in entry_points(group="console_scripts")
+          )
+
+          mcp = FastMCP("smoke")
+          assert app is not None
+          assert mcp.name == "smoke"
+          PY
+
+      - name: Install full package from matching local wheels
+        run: |
+          uv venv /tmp/fastmcp-full-smoke
+          FULL_WHEEL=$(ls /tmp/fastmcp-dist/fastmcp-*.whl)
+          uv pip install --python /tmp/fastmcp-full-smoke/bin/python --prerelease=allow --find-links /tmp/fastmcp-dist "$FULL_WHEEL"
+          /tmp/fastmcp-full-smoke/bin/python - <<'PY'
+          from importlib.metadata import entry_points
+          from importlib.metadata import requires
+
+          from fastmcp import Client, FastMCP
+          from fastmcp.client.client import CallToolResult
+          from fastmcp.exceptions import ToolError
+
+          fastmcp_reqs = requires("fastmcp") or []
+          assert any("fastmcp-slim[client,server]" in req for req in fastmcp_reqs)
+          assert not any("fastmcp-slim[full" in req for req in fastmcp_reqs)
+
+          assert any(
+              ep.name == "fastmcp" and ep.value == "fastmcp.cli:app"
+              for ep in entry_points(group="console_scripts")
+          )
+
+          assert Client("https://example.com/mcp")
+          assert FastMCP("smoke").name == "smoke"
+          assert CallToolResult is not None
+          assert ToolError is not None
+          PY
+
+      - name: Install fastmcp-remote from matching local wheels
+        run: |
+          uv venv /tmp/fastmcp-remote-smoke
+          REMOTE_WHEEL=$(ls /tmp/fastmcp-dist/fastmcp_remote-*.whl)
+          uv pip install --python /tmp/fastmcp-remote-smoke/bin/python --prerelease=allow --find-links /tmp/fastmcp-dist "$REMOTE_WHEEL"
+          /tmp/fastmcp-remote-smoke/bin/python - <<'PY'
+          from importlib.metadata import entry_points
+          from importlib.metadata import requires
+
+          from fastmcp_remote.cli import build_parser
+
+          remote_reqs = requires("fastmcp-remote") or []
+          assert any("fastmcp-slim[client,server]" in req for req in remote_reqs)
+          assert any(
+              ep.name == "fastmcp-remote" and ep.value == "fastmcp_remote.cli:main"
+              for ep in entry_points(group="console_scripts")
+          )
+          assert build_parser().prog == "fastmcp-remote"
+          PY
diff --git a/.github/workflows/run-upgrade-checks.yml b/.github/workflows/run-upgrade-checks.yml
new file mode 100644
index 0000000..3be7b81
--- /dev/null
+++ b/.github/workflows/run-upgrade-checks.yml
@@ -0,0 +1,157 @@
+name: Upgrade checks
+
+env:
+  PY_COLORS: 1
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "fastmcp_slim/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/**"
+
+  schedule:
+    # Run daily at 2 AM UTC
+    - cron: "0 2 * * *"
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  static_analysis:
+    name: Static analysis
+    timeout-minutes: 2
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Setup uv (upgrade)
+        uses: ./.github/actions/setup-uv
+        with:
+          resolution: upgrade
+
+      - name: Run prek
+        uses: j178/prek-action@v2
+        env:
+          SKIP: no-commit-to-branch
+
+  run_tests:
+    name: "Tests: Python ${{ matrix.python-version }} on ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10"]
+        include:
+          - os: ubuntu-latest
+            python-version: "3.13"
+      fail-fast: false
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Setup uv (upgrade)
+        uses: ./.github/actions/setup-uv
+        with:
+          python-version: ${{ matrix.python-version }}
+          resolution: upgrade
+
+      - name: Run unit tests
+        uses: ./.github/actions/run-pytest
+
+      - name: Run client process tests
+        uses: ./.github/actions/run-pytest
+        with:
+          test-type: client_process
+
+  run_integration_tests:
+    name: "Integration tests"
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Setup uv (upgrade)
+        uses: ./.github/actions/setup-uv
+        with:
+          resolution: upgrade
+
+      - name: Run integration tests
+        uses: ./.github/actions/run-pytest
+        with:
+          test-type: integration
+        env:
+          FASTMCP_GITHUB_TOKEN: ${{ secrets.FASTMCP_GITHUB_TOKEN }}
+          FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID: ${{ secrets.FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID }}
+          FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET: ${{ secrets.FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET }}
+
+  notify:
+    name: Notify on failure
+    needs: [static_analysis, run_tests, run_integration_tests]
+    if: failure() && github.event.pull_request == null
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Create or update failure issue
+        uses: jayqi/failed-build-issue-action@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          label: "build failed"
+          title-template: "Upgrade checks failing on main branch"
+          body-template: |
+            ## Upgrade Checks Failure on Main Branch
+
+            The upgrade checks workflow has failed on the main branch.
+
+            **Workflow Run**: [#{{runNumber}}]({{serverUrl}}/{{repo.owner}}/{{repo.repo}}/actions/runs/{{runId}})
+            **Commit**: {{sha}}
+            **Branch**: {{ref}}
+            **Event**: {{eventName}}
+
+            ### Common causes
+
+            - **ty (type checker)**: New ty releases frequently add stricter checks that flag previously-accepted code. Run `uv run ty check` locally with the latest ty to reproduce. Fix the type errors or bump the ty version floor in `pyproject.toml`.
+            - **ruff**: New lint rules or stricter defaults in a ruff upgrade.
+            - **MCP SDK**: Breaking changes in the `mcp` package (new method signatures, renamed types).
+
+            ### What to do
+
+            1. Check the workflow logs to identify which job failed (static analysis vs tests)
+            2. Reproduce locally with `uv sync --upgrade && uv run prek run --all-files && uv run pytest -n auto`
+            3. Fix the code or adjust dependency constraints as needed
+
+            ---
+            *This issue was automatically created by a GitHub Action.*
+
+  close-on-success:
+    name: Close issue on success
+    needs: [static_analysis, run_tests, run_integration_tests]
+    if: success() && github.event.pull_request == null && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Close resolved failure issue
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          issue=$(gh issue list \
+            --repo "$GITHUB_REPOSITORY" \
+            --label "build failed" \
+            --state open \
+            --json number \
+            --jq '.[0].number // empty')
+
+          if [ -n "$issue" ]; then
+            gh issue close "$issue" \
+              --repo "$GITHUB_REPOSITORY" \
+              --comment "Upgrade checks are passing again as of [\`${GITHUB_SHA::7}\`](${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/commit/${GITHUB_SHA})."
+          fi
diff --git a/.github/workflows/update-config-schema.yml b/.github/workflows/update-config-schema.yml
new file mode 100644
index 0000000..6600981
--- /dev/null
+++ b/.github/workflows/update-config-schema.yml
@@ -0,0 +1,72 @@
+name: Update MCPServerConfig Schema
+
+# Regenerates config schema on pushes to main and opens a long-lived PR
+# with the changes, so contributor PRs stay clean.
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "fastmcp_slim/fastmcp/utilities/mcp_server_config/**"
+      - "!fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/schema.json"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update-config-schema:
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.MARVIN_APP_ID }}
+          private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}
+
+      - uses: actions/checkout@v7
+        with:
+          token: ${{ steps.marvin-token.outputs.token }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies
+        run: uv sync --python 3.12
+
+      - name: Generate config schema
+        run: |
+          uv run python -c "
+          from fastmcp.utilities.mcp_server_config import generate_schema
+          generate_schema('docs/public/schemas/fastmcp.json/latest.json')
+          generate_schema('docs/public/schemas/fastmcp.json/v1.json')
+          generate_schema('fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/schema.json')
+          "
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v8
+        with:
+          token: ${{ steps.marvin-token.outputs.token }}
+          commit-message: "chore: Update fastmcp.json schema"
+          title: "chore: Update fastmcp.json schema"
+          body: |
+            This PR updates the fastmcp.json schema files to match the current source code.
+
+            The schema is automatically generated from `fastmcp_slim/fastmcp/utilities/mcp_server_config/` to ensure consistency.
+
+            **Note:** This PR is fully automated and will update itself with any subsequent changes to the schema, or close automatically if the schema becomes up-to-date through other means.
+
+            🤖 Generated by Marvin
+          branch: marvin/update-config-schema
+          labels: |
+            ignore in release notes
+          delete-branch: true
+          author: "marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com>"
+          committer: "marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com>"
diff --git a/.github/workflows/update-sdk-docs.yml b/.github/workflows/update-sdk-docs.yml
new file mode 100644
index 0000000..9d05684
--- /dev/null
+++ b/.github/workflows/update-sdk-docs.yml
@@ -0,0 +1,69 @@
+name: Update SDK Documentation
+
+# Regenerates SDK docs on pushes to main and opens a long-lived PR
+# with the changes, so contributor PRs stay clean.
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "fastmcp_slim/**"
+      - "pyproject.toml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update-sdk-docs:
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.MARVIN_APP_ID }}
+          private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}
+
+      - uses: actions/checkout@v7
+        with:
+          token: ${{ steps.marvin-token.outputs.token }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies
+        run: uv sync --python 3.12
+
+      - name: Install just
+        uses: extractions/setup-just@v4
+
+      - name: Generate SDK documentation
+        run: just api-ref-all
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v8
+        with:
+          token: ${{ steps.marvin-token.outputs.token }}
+          commit-message: "chore: Update SDK documentation"
+          title: "chore: Update SDK documentation"
+          body: |
+            This PR updates the auto-generated SDK documentation to reflect the latest source code changes.
+
+            📚 Documentation is automatically generated from the source code docstrings and type annotations.
+
+            **Note:** This PR is fully automated and will update itself with any subsequent changes to the SDK, or close automatically if the documentation becomes up-to-date through other means. Feel free to leave it open until you're ready to merge.
+
+            🤖 Generated by Marvin
+          branch: marvin/update-sdk-docs
+          labels: |
+            ignore in release notes
+          delete-branch: true
+          author: "marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com>"
+          committer: "marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com>"
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..129fe99
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,80 @@
+# Python-generated files
+__pycache__/
+*.py[cod]
+*$py.class
+build/
+dist/
+wheels/
+*.egg-info/
+*.egg
+MANIFEST
+.pytest_cache/
+.loq_cache
+.coverage
+htmlcov/
+.tox/
+nosetests.xml
+coverage.xml
+*.cover
+
+# Virtual environments
+.venv
+venv/
+env/
+ENV/
+.env
+
+# System files
+.DS_Store
+
+# Version file
+src/fastmcp/_version.py
+
+# Editors and IDEs
+.cursorrules
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+.settings/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+
+# Local development
+.python-version
+.envrc
+.envrc.private
+.direnv/
+
+# Logs and databases
+*.log
+*.sqlite
+*.db
+*.ddb
+
+# Claude worktree management
+.claude-wt/worktrees
+.claude/worktrees/
+
+# Agents
+/PLAN.md
+/TODO.md
+/STATUS.md
+plans/
+
+# Common FastMCP test files
+/test.py
+/server.py
+/client.py
+/test.json
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 0000000..304c3e4
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,55 @@
+fail_fast: false
+
+repos:
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: v0.24.1
+    hooks:
+      - id: validate-pyproject
+
+  - repo: https://github.com/rbubley/mirrors-prettier
+    rev: v3.8.4
+    hooks:
+      - id: prettier
+        types_or: [yaml, json5]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.14.10
+    hooks:
+      # Run the linter.
+      - id: ruff-check
+        args: [--fix, --exit-non-zero-on-fix]
+      # Run the formatter.
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty check
+        entry: uv run --isolated ty check
+        language: system
+        types: [python]
+        files: ^fastmcp_slim/|^tests/
+        pass_filenames: false
+        require_serial: true
+
+      - id: loq
+        name: loq (file size limits)
+        entry: bash -c 'uv run loq || printf "\nloq violations not enforced... yet!\n"'
+        language: system
+        pass_filenames: false
+        verbose: true
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: no-commit-to-branch
+        name: prevent commits to main
+        args: [--branch, main]
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell # See pyproject.toml for args
+        additional_dependencies:
+          - tomli
diff --git a/AGENTS.md b/AGENTS.md
new file mode 120000
index 0000000..681311e
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1 @@
+CLAUDE.md
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..e900cc9
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,186 @@
+# FastMCP Development Guidelines
+
+> **Audience**: LLM-driven engineering agents and human developers
+
+> **Note**: `AGENTS.md` is a symlink to this file. Edit `CLAUDE.md` directly.
+
+FastMCP is a comprehensive Python framework (Python ≥3.10) for building Model Context Protocol (MCP) servers and clients. This is the actively maintained v2.0 providing a complete toolkit for the MCP ecosystem.
+
+## Required Development Workflow
+
+**CRITICAL**: Always run these commands in sequence before committing.
+
+```bash
+uv sync                              # Install dependencies
+uv run pytest -n auto                # Run full test suite
+```
+
+In addition, you must pass static checks. This is generally done as a pre-commit hook with `prek` but you can run it manually with:
+
+```bash
+uv run prek run --all-files          # Ruff + Prettier + ty
+```
+
+**Tests must pass and lint/typing must be clean before committing.**
+
+## Repository Structure
+
+| Path              | Purpose                                |
+| ----------------- | -------------------------------------- |
+| `fastmcp_slim/fastmcp/` | Library source code                    |
+| `├─server/`       | Server implementation                  |
+| `│ ├─auth/`       | Authentication providers               |
+| `│ └─middleware/` | Error handling, logging, rate limiting |
+| `├─client/`       | Client SDK                             |
+| `│ └─auth/`       | Client authentication                  |
+| `├─tools/`        | Tool definitions                       |
+| `├─resources/`    | Resources and resource templates       |
+| `├─prompts/`      | Prompt templates                       |
+| `├─cli/`          | CLI commands                           |
+| `└─utilities/`    | Shared utilities                       |
+| `tests/`          | Pytest suite                           |
+| `docs/`           | Mintlify docs (gofastmcp.com)          |
+
+## Core MCP Objects
+
+When modifying MCP functionality, changes typically need to be applied across all object types:
+
+- **Tools** (`src/tools/`)
+- **Resources** (`src/resources/`)
+- **Resource Templates** (`src/resources/`)
+- **Prompts** (`src/prompts/`)
+
+**Before writing cross-component logic (dedupe, grouping, lookups, identity checks), read `FastMCPComponent` in `fastmcp_slim/fastmcp/utilities/components.py`.** The base class defines the shared surface — `name`, `version`, `tags`, `meta`, and critically the `key` property which is the canonical MCP identity (encodes type, identifier, and version). Prefer `item.key` over ad-hoc `name or uri or uri_template` fallbacks; overrides in `Resource` and `ResourceTemplate` already handle URI-based identity, and `.key` includes the version suffix so variants of the same component don't falsely collide.
+
+## Development Rules
+
+**Read `CONTRIBUTING.md` before opening issues or PRs.** It describes when PRs are appropriate, what we expect from enhancement proposals, and what we'll close without review.
+
+### Git & CI
+
+- Prek hooks are required (run automatically on commits)
+- Never amend commits to fix prek failures
+- Never apply labels manually or invent new ones — the GitHub API auto-creates any unknown label name, polluting the repo's label list. Note the appropriate label in the PR body and let the maintainer/automation apply it. Canonical names: `bugs`, `breaking change`, `enhancements`, `features` (it's `breaking change`, not `breaking`). See the review-pr skill.
+- Improvements = enhancements (not features) unless specified
+- **NEVER** force-push on collaborative repos
+- **ALWAYS** run prek before PRs
+- **NEVER** create a release, comment on an issue, or open a PR unless specifically instructed to do so.
+- **NEVER** merge a PR marked as do-not-merge or draft. Check title, body, AND labels for `[DNM]`, `DNM`, `DO NOT MERGE`, `DON'T MERGE`, `DONT MERGE`, `do-not-merge`, `dont-merge`, `[DRAFT]`, or `DRAFT` (case-insensitive, any variation — some authors use `[DRAFT]` in the title even when `isDraft` is false). Authors use these as hard stops — respect them even if CI is green and review looks clean. When triaging a batch of PRs, filter these out up front AND re-check each one's labels immediately before merging, since labels can change mid-session.
+- **ALWAYS** read review-bot comments before approving a PR. CodeRabbit and chatgpt-codex-connector (Codex) leave substantive review comments on most PRs in this repo — these bots have read the diff and often flag real issues that aren't in the PR description. Use `gh pr view <num> --comments` and read the bot feedback as part of review. Unlike proposed solutions from issue reporters, review-bot feedback should be evaluated on its merits, not discounted.
+- **Be constructively skeptical of bot review comments on your own PRs.** CodeRabbit, Codex, and claude[bot] run a fresh review pass on every push, which means a PR with active churn can accumulate bot comments in a stream that never really ends — each fix surfaces a new edge case the next pass can flag. Most of the early feedback is real and worth acting on; diminishing returns set in fast. Evaluate each comment on its merits, the same way you would a human reviewer: is this a real bug users will hit, or a hypothetical that requires an adversarial setup? Does the fix introduce more complexity than the problem? Has the bot missed context that's obvious to a human reader (a `*,` keyword-only marker, a design decision documented elsewhere, something already resolved on a later commit)? When a comment is pedantic, a false positive, or flagging something already fixed, reply on the thread explaining the reasoning and move on — don't keep iterating just because more comments arrive. If you find yourself three rounds deep and the feedback is shifting toward "what if someone does X" hypotheticals, you're past the point where each fix is improving the PR. Stop, document the contract as-is, and ship.
+
+### Outbound Comments and Shell Interpolation
+
+- Never pass GitHub, Linear, or Slack comment bodies inline through shell arguments when the body contains `$`, `${...}`, backticks, `$(...)`, environment-variable examples, secrets, or config interpolation examples.
+- Use a body file or structured API payload for outbound comments, then inspect the exact outgoing text before posting. Prefer `gh ... --body-file /path/to/comment.md` over `--body "..."`.
+- When explaining environment interpolation, use placeholders and fenced code blocks. Never include raw `.env` contents in outbound comments.
+
+### Releases
+
+Only cut releases when the maintainer explicitly asks. Tags follow `v<version>` (e.g., `v3.2.0`). Always pass `--generate-notes` so the auto-generated changelog appears at the bottom.
+
+**The title pun is critical.** Titles follow `v<version>: <pun>` where the pun relates to the most important theme of the release. Propose multiple options and let the maintainer choose — never pick one yourself. Look at recent releases for tone (e.g., "Code to Joy" for the code mode release, "Three at Last" for 3.0).
+
+Write the maintainer-approved handwritten notes to a temporary file, then create the release. `--generate-notes` appends the auto-generated changelog after the handwritten content.
+
+```bash
+gh release create v4.0.0 --target main --title "v4.0.0: Theme Here" --generate-notes --notes-start-tag v3.4.4 --notes-file /tmp/release-notes.md
+```
+
+**Always pass `--notes-start-tag <last-stable-tag>`.** Without it, `--generate-notes` picks the most recent prior tag as the changelog start point — and if a prerelease exists (e.g. `v3.4.0b1`), it starts from *that*, silently truncating the PR list to only the commits since the beta. Pin it to the last stable release (e.g. `v3.3.1` when cutting `v3.4.0`). Verify after: the compare link at the bottom of the generated notes should read `v<last-stable>...v<new>`.
+
+Use the branch that owns the release line as the target: current-major releases target `main`, 3.x maintenance releases target `release/3.x`, and 2.x maintenance releases target `release/2.x`. Confirm the target with the maintainer if there's any ambiguity. For example, cut a 3.4.4 maintenance release with `--target release/3.x`, not `main`.
+
+The handwritten notes are prepended above the auto-generated changelog and are the part that matters. Do not include a title in the notes body — the release title (`v{version}: {pun}`) already serves as the heading. Work with the maintainer to draft the notes — propose a draft, get feedback, iterate. Do not publish without the maintainer's sign-off.
+
+**Before drafting, always read recent existing releases** (`gh release list` then `gh release view <tag>`) to absorb the voice, structure, and level of detail. Each release builds on the tone of previous ones — don't guess at the style from these instructions alone.
+
+**To preview what PRs will be in the release** before it's cut, call the GitHub generate-notes API. This returns the exact auto-generated changelog that `--generate-notes` would append, so you can see the full PR list — useful for picking a pun theme and making sure nothing's been missed:
+
+```bash
+gh api -X POST repos/PrefectHQ/fastmcp/releases/generate-notes \
+  -f tag_name=v3.2.3 \
+  -f target_commitish=main \
+  -f previous_tag_name=v3.2.2 \
+  --jq '.body'
+```
+
+Set `target_commitish` to the same branch that will receive the release tag. For maintenance releases, use the maintenance branch (for example, `release/3.x`) so the preview matches the release notes GitHub will generate.
+
+**Point releases** (3.0, 3.1, 3.2) get narrative prose: open with the theme of the release, then walk through headline features conceptually — what they enable, why they matter, how they fit together. Write it the way a blog post reads, not a changelog. Multiple paragraphs, code examples where they clarify.
+
+**Patch releases** (3.1.1, 3.0.2) get 1-2 sentences explaining what broke and what the fix does. Keep it minimal — the auto-generated changelog has the details.
+
+**Merge the docs changelog PR *before* cutting the release, not after.** The post-publish `update-published-docs` job force-pushes the `published-docs` branch (which gofastmcp.com serves) to the released commit for stable releases on the default branch, so the changelog entry only reaches the live site if it's already in the commit being tagged. Land the docs PR on the release target branch first, then cut the release from that branch. If you tag first and merge docs after, this release's changelog won't appear on the live site until the next default-branch stable release force-pushes `published-docs` forward. Maintenance releases from `release/3.x` or `release/2.x` publish packages and GitHub notes without repointing `published-docs`; add their changelog entries on the maintenance branch, slotted into the matching major-version section. Two hand-maintained files mirror the GitHub release and must get a new entry for every version, newest at the top (these are `.mdx` and are not covered by the prek Prettier hook, which only runs on `yaml`/`json5` — match the existing entries' style by hand):
+
+- `docs/changelog.mdx` is the full mirror. Add an `<Update label="v<version>" description="YYYY-MM-DD">` block with: a bold linked title (`**[v<version>: <pun>](<release-url>)**`), a condensed 1-paragraph intro (one sentence for patches), the full categorized PR list reformatted from the `--generate-notes` output (`* <title> by [@user](https://github.com/user) in [#NNNN](<pull-url>)`), a `## New Contributors` list (plain `@user`, linked PR), and a `**Full Changelog**: [vA...vB](<compare-url>)` line.
+- `docs/updates.mdx` is the skimmable card feed. Add an `<Update label="FastMCP <version>" description="Month DD, YYYY" tags={["Releases"]}>` wrapping a `<Card>` that links to the GitHub release, with a 1-2 sentence summary and (for point releases) a handful of emoji-bulleted highlights.
+
+Because the docs land *before* the tag exists, derive the entry from the maintainer-approved handwritten notes (intro/summary) and the `--generate-notes` API *preview* (the PR-list body — see the generate-notes API call above, which returns the exact changelog without cutting anything). Scripting the link reformatting is reliable for long PR lists. The release-URL, tag, and compare links follow the known pattern (`/releases/tag/v<version>`, `compare/v<last-stable>...v<version>`) and will 404 only during the short window between merging the docs PR and cutting the release minutes later — they resolve before the release workflow completes. For this reason, create and merge the docs PR *immediately* before cutting the release — treat the two as one tight back-to-back sequence, not independent steps — so the links are valid by the time the release publishes rather than dangling for any longer than necessary.
+
+### Commit Messages and Agent Attribution
+
+- **Agents NOT acting on behalf of @jlowin MUST identify themselves** (e.g., "🤖 Generated with Claude Code" in commits/PRs)
+- Keep commit messages brief - ideally just headlines, not detailed messages
+- Focus on what changed, not how or why
+- Always read issue comments for follow-up information (treat maintainers as authoritative)
+- **Treat proposed solutions in issues skeptically.** This applies to solutions proposed by *users* in issue reports — not to feedback from configured review bots (CodeRabbit, chatgpt-codex-connector, etc.), which should be evaluated on their merits. The ideal issue contains a concise problem description and an MRE — nothing more. Proposed solutions are only worth considering if they clearly reflect genuine, non-obvious investigation of the codebase. If a solution reads like speculation, or like it was generated by an LLM without deep framework knowledge, ignore it and diagnose from the repro. Most reporters — human or AI — do not have sufficient understanding of FastMCP internals to correctly diagnose anything beyond a trivial bug. We can ask the same questions of an LLM when implementing; we don't need the reporter to do it for us, and a wrong diagnosis is worse than none.
+
+### PR Messages - Required Structure
+
+- 1-2 paragraphs: problem/tension + solution (PRs are documentation!)
+- Focused code example showing key capability
+- **Avoid:** bullet summaries, exhaustive change lists, verbose closes/fixes, marketing language
+- **Do:** Be opinionated about why change matters, show before/after scenarios
+- Minor fixes: keep body short and concise
+- No "test plan" sections or testing summaries
+
+### Code Review Guidelines
+
+- **Fix causes, not symptoms.** When a PR works around a problem instead of addressing why it occurs, that's a red flag. A side-channel that compensates for a missing step adds permanent complexity. If the fix doesn't change the code path where the bug actually happens, ask why not.
+- Focus on API design and naming clarity
+- Identify confusing patterns (e.g., parameter values that contradict defaults) or non-idiomatic code (mutable defaults, etc.). Contributed code will need to be maintained indefinitely, and by someone other than the author (unless the author is a maintainer).
+- Suggest specific improvements, not generic "add more tests" comments
+- Think about API ergonomics from a user perspective
+
+### Code Standards
+
+- Python ≥ 3.10 with full type annotations
+- Follow existing patterns and maintain consistency
+- **Prioritize readable, understandable code** - clarity over cleverness
+- Avoid obfuscated or confusing patterns even if they're shorter
+- Each feature needs corresponding tests
+
+### Module Exports
+
+- **Do not create overeager `__init__.py` files.** Package initializers should not import heavy submodules, provider stacks, optional integrations, or modules that can point back into the package. Overeager re-exports make the framework sprawl and create circular imports that only appear in fresh interpreters or clean installs.
+- **Be intentional about re-exports** - don't blindly re-export everything to parent namespaces
+- Core types that define a module's purpose should be exported (e.g., `Middleware` from `fastmcp.server.middleware`)
+- Specialized features can live in submodules (e.g., `fastmcp.server.middleware.dynamic`)
+- Only re-export to `fastmcp.*` for the most fundamental types (e.g., `FastMCP`, `Client`)
+- When in doubt, prefer users importing from the specific submodule over re-exporting
+
+### Documentation
+
+- Uses Mintlify framework
+- Files must be in docs.json to be included
+- Do not manually modify `docs/python-sdk/**` — these files are auto-generated from source code by a bot and maintained via a long-lived PR. Do not include changes to these files in contributor PRs.
+- Do not manually modify `docs/public/schemas/**` or `fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/schema.json` — these are auto-generated and maintained via a long-lived PR.
+- **Core Principle:** A feature doesn't exist unless it is documented!
+- When adding or modifying settings in `fastmcp_slim/fastmcp/settings.py`, update `docs/more/settings.mdx` to match.
+
+### Documentation Guidelines
+
+- **Code Examples:** Explain before showing code, make blocks fully runnable (include imports)
+- **Code Formatting:** Keep code blocks visually clean — avoid deeply nested function calls. Extract intermediate values into named variables rather than inlining everything into one expression. Code in docs is read more than it's run; optimize for scannability.
+- **Structure:** Headers form navigation guide, logical H2/H3 hierarchy
+- **Content:** User-focused sections, motivate features (why) before mechanics (how)
+- **Style:** Prose over code comments for important information
+- **Docstrings:** FastMCP docstrings are automatically compiled into MDX documents. Use markdown (single backticks, fenced code blocks), not RST (no double backticks). Bare `{}` in examples will be interpreted as JSX — wrap in backticks instead.
+
+## Critical Patterns
+
+- Never use bare `except` - be specific with exception types
+- File sizes enforced by [loq](https://github.com/jakekaplan/loq). Edit `loq.toml` to raise limits; `loq baseline` to ratchet down.
+- Always `uv sync` first when debugging build issues
+- Default test timeout is 5s - optimize or mark as integration tests
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..026b0a2
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+chris@prefect.io.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..974d9d6
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,53 @@
+# Contributing to FastMCP
+
+FastMCP is an actively maintained, high-traffic project. We welcome contributions — but the most impactful way to contribute might not be what you expect.
+
+## The best contribution is a great issue
+
+FastMCP is an opinionated framework, and its maintainers use AI-assisted tooling that is deeply tuned to those opinions — the design philosophy, the API patterns, the way the framework is meant to evolve. A well-written issue with a clear problem description is often more valuable than a pull request, because it lets maintainers produce a solution that isn't just correct, but consistent with how the framework wants to work. That matters more than speed, though it's faster too.
+
+**A great issue looks like this:**
+
+1. A short, motivating description of the problem or gap
+2. A minimal reproducible example (for bugs) or a concrete use case (for enhancements)
+3. A brief note on expected vs. actual behavior
+
+That's it. No need to diagnose root causes, propose API designs, or suggest implementations. If you've done genuine investigation and have a non-obvious insight, include it.
+
+## Using AI to contribute
+
+We encourage you to use LLMs to help identify bugs, write MREs, and prepare contributions. But if you do, your LLM must take into account the conventions and contributing guidelines of this repo — including how we want issues formatted and when it's appropriate to open a PR. Generic LLM output that ignores these guidelines tells us the contribution wasn't made thoughtfully, and we will close it. A good AI-assisted contribution is indistinguishable from a good human one. A bad one is obvious.
+
+## When to open a pull request
+
+An open issue is not an invitation to submit a PR. Issues track problems; whether and how to solve them is a separate decision. If you want to work on something, propose your approach in the issue first and ask a maintainer to assign it to you — especially for anything beyond a trivial fix. External PRs that reference an issue not assigned to their author are closed automatically (see [PR guidelines](#pr-guidelines)).
+
+**Bug fixes** — PRs are welcome for simple, well-scoped bug fixes where the problem and solution are both straightforward. "The function raises `TypeError` when passed `None` because of a missing guard" is a good candidate. If the fix requires design decisions or touches multiple subsystems, open an issue with a design proposal instead.
+
+**Documentation** — Typo fixes, clarifications, and improvements to examples are always welcome as PRs.
+
+**Enhancements and features** — We welcome enhancement PRs, but our experience is that most contributors — even when using LLMs — implement fixes that address the one instance of a problem they encountered rather than understanding why the framework produces that problem and fixing it at the right layer. This creates branching, patch-style code that's difficult to maintain and makes it impossible to reason about the framework as a coherent system. For this reason, enhancements need a design proposal in the issue before code is written. The proposal doesn't need to be long — just enough to show you've thought about how the change fits into the framework, not just how it solves your immediate case.
+
+**Integrations** — FastMCP generally does not accept PRs that add third-party integrations (custom middleware, provider-specific adapters, etc.). If you're building something for your users, ship it as a standalone package — that's a feature, not a limitation. Authentication providers are an exception, since auth is tightly coupled to the framework.
+
+## PR guidelines
+
+If you do open a PR:
+
+- **Reference an issue you're assigned to.** Every PR must reference a tracked issue using an auto-close keyword (`Fixes #123`, `Closes #123`, or `Resolves #123`), and the referenced issue must be assigned to you. If there isn't an issue, open one; then comment to ask a maintainer to assign it to you. This lets us deconflict effort and steer the approach before you invest time in code. External PRs that don't meet both conditions are automatically labeled `missing-issue-link` and closed; they reopen automatically once the link is present and you're assigned.
+- **Keep it focused.** One logical change per PR. Don't bundle unrelated fixes or refactors.
+- **Match existing patterns.** Follow the code style, type annotation conventions, and test patterns you see in the codebase. Run `uv run prek run --all-files` before submitting.
+- **Write tests.** Bug fixes should include a test that fails without the fix. Enhancements should include tests for the new behavior.
+- **Fix the cause, not the symptom.** If the bug is that a code path skips a step, the fix should make it stop skipping that step — not add compensation elsewhere. Workaround-style fixes will be sent back for revision.
+- **Don't submit generated boilerplate.** We review every line. PRs that read like unedited LLM output — verbose descriptions, speculative changes, shotgun-style fixes — will be closed.
+
+## What we'll close without review
+
+To keep the project maintainable, we will close PRs that:
+
+- Don't reference an issue or address a clearly self-evident bug
+- Make sweeping changes without prior discussion
+- Add third-party integrations that belong in a separate package
+- Are difficult to review due to size, scope, or generated content
+
+This isn't personal — contributing to a framework is different from contributing to an application. In an application, a fix that works is a good fix. In a framework, a fix that works but doesn't fit the framework's design creates maintenance burden that compounds over time. Every patch that works around a problem instead of solving it at the right layer makes the system harder for *everyone* to reason about — maintainers, contributors, and users. We hold contributions to this standard because the alternative is a codebase that's a series of patches rather than a coherent system. A good issue is often the best thing you can do for the project.
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..f49a4e1
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b2b8c18
--- /dev/null
+++ b/README.md
@@ -0,0 +1,123 @@
+<div align="center">
+
+<!-- omit in toc -->
+
+<picture>
+  <source width="550" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/PrefectHQ/fastmcp/main/docs/assets/brand/f-watercolor-waves-4-dark.png">
+  <source width="550" media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/PrefectHQ/fastmcp/main/docs/assets/brand/f-watercolor-waves-4.png">
+  <img width="550" alt="FastMCP Logo" src="https://raw.githubusercontent.com/PrefectHQ/fastmcp/main/docs/assets/brand/f-watercolor-waves-2.png">
+</picture>
+
+# FastMCP 🚀
+
+<strong>Move fast and make things.</strong>
+
+*Made with 💙 by [Prefect](https://www.prefect.io/)*
+
+[![Docs](https://img.shields.io/badge/docs-gofastmcp.com-blue)](https://gofastmcp.com)
+[![Discord](https://img.shields.io/badge/community-discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/uu8dJCgttd)
+[![PyPI - Version](https://img.shields.io/pypi/v/fastmcp.svg)](https://pypi.org/project/fastmcp)
+[![Tests](https://github.com/PrefectHQ/fastmcp/actions/workflows/run-tests.yml/badge.svg)](https://github.com/PrefectHQ/fastmcp/actions/workflows/run-tests.yml)
+[![License](https://img.shields.io/github/license/PrefectHQ/fastmcp.svg)](https://github.com/PrefectHQ/fastmcp/blob/main/LICENSE)
+
+<a href="https://trendshift.io/repositories/21461" target="_blank"><img src="https://trendshift.io/api/badge/repositories/21461" alt="prefecthq%2Ffastmcp | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+</div>
+
+---
+
+The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) connects LLMs to tools and data. FastMCP gives you everything you need to go from prototype to production:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("Demo 🚀")
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Why FastMCP
+
+Building an effective MCP application is harder than it looks. FastMCP handles all of it. Declare a tool with a Python function, and the schema, validation, and documentation are generated automatically. Connect to a server with a URL, and transport negotiation, authentication, and protocol lifecycle are managed for you. You focus on your logic, and the MCP part just works: **with FastMCP, best practices are built in.**
+
+**That's why FastMCP is the standard framework for working with MCP.** FastMCP 1.0 was incorporated into the official MCP Python SDK in 2024. Today, the actively maintained standalone project is downloaded a million times a day, and some version of FastMCP powers 70% of MCP servers across all languages.
+
+FastMCP has three pillars:
+
+<table>
+<tr>
+<td align="center" valign="top" width="33%">
+<a href="https://gofastmcp.com/servers/server">
+<img src="https://raw.githubusercontent.com/PrefectHQ/fastmcp/main/docs/assets/images/servers-card.png" alt="Servers" />
+<br /><strong>Servers</strong>
+</a>
+<br />Expose tools, resources, and prompts to LLMs.
+</td>
+<td align="center" valign="top" width="33%">
+<a href="https://gofastmcp.com/apps/overview">
+<img src="https://raw.githubusercontent.com/PrefectHQ/fastmcp/main/docs/assets/images/apps-card.png" alt="Apps" />
+<br /><strong>Apps</strong>
+</a>
+<br />Give your tools interactive UIs rendered directly in the conversation.
+</td>
+<td align="center" valign="top" width="33%">
+<a href="https://gofastmcp.com/clients/client">
+<img src="https://raw.githubusercontent.com/PrefectHQ/fastmcp/main/docs/assets/images/clients-card.png" alt="Clients" />
+<br /><strong>Clients</strong>
+</a>
+<br />Connect to any MCP server — local or remote, programmatic or CLI.
+</td>
+</tr>
+</table>
+
+**[Servers](https://gofastmcp.com/servers/server)** wrap your Python functions into MCP-compliant tools, resources, and prompts. **[Clients](https://gofastmcp.com/clients/client)** connect to any server with full protocol support. And **[Apps](https://gofastmcp.com/apps/overview)** give your tools interactive UIs rendered directly in the conversation.
+
+Ready to build? Start with the [installation guide](https://gofastmcp.com/getting-started/installation) or jump straight to the [quickstart](https://gofastmcp.com/getting-started/quickstart).
+
+## Run FastMCP in production with Horizon
+
+FastMCP is the standard way to build MCP servers. **[Prefect Horizon](https://www.prefect.io/horizon?utm_source=github&utm_medium=readme&utm_campaign=readme_horizon&utm_content=readme_body)** is the enterprise MCP gateway for running them safely.
+
+Built by the FastMCP team, Horizon packages the best practices we've learned shipping the world's most popular MCP framework.
+
+Deploy FastMCP servers from GitHub with branch previews and instant rollback. Create a private registry of every MCP your company uses. Secure access with SSO and tool-level RBAC. Get audit logs, observability, and governance across your MCP stack. Remix approved tools into purpose-built endpoints for teams and agents.
+
+Start with FastMCP. [Scale with Horizon →](https://www.prefect.io/horizon?utm_source=github&utm_medium=readme&utm_campaign=readme_horizon&utm_content=readme_cta)
+
+## Installation
+
+We recommend installing FastMCP with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv pip install fastmcp
+```
+
+For full installation instructions, including verification and upgrading, see the [**Installation Guide**](https://gofastmcp.com/getting-started/installation).
+
+**Upgrading?** We have guides for:
+- [Upgrading from FastMCP v2](https://gofastmcp.com/getting-started/upgrading/from-fastmcp-2)
+- [Upgrading from the MCP Python SDK](https://gofastmcp.com/getting-started/upgrading/from-mcp-sdk)
+- [Upgrading from the low-level SDK](https://gofastmcp.com/getting-started/upgrading/from-low-level-sdk)
+
+> [!NOTE]
+> If `import fastmcp` fails right after a `pip` upgrade from FastMCP 3.2 or earlier, run `pip install --force-reinstall fastmcp`. See [Troubleshooting](https://gofastmcp.com/getting-started/installation#troubleshooting) for why this happens (`uv` is unaffected).
+
+## 📚 Documentation
+
+FastMCP's complete documentation is available at **[gofastmcp.com](https://gofastmcp.com)**, including detailed guides, API references, and advanced patterns.
+
+Documentation is also available in [llms.txt format](https://llmstxt.org/), which is a simple markdown standard that LLMs can consume easily:
+
+- [`llms.txt`](https://gofastmcp.com/llms.txt) is essentially a sitemap, listing all the pages in the documentation.
+- [`llms-full.txt`](https://gofastmcp.com/llms-full.txt) contains the entire documentation. Note this may exceed the context window of your LLM.
+
+**Community:** Join our [Discord server](https://discord.gg/uu8dJCgttd) to connect with other FastMCP developers and share what you're building.
+
+## Contributing
+
+We welcome contributions! See the [Contributing Guide](https://gofastmcp.com/development/contributing) for setup instructions, testing requirements, and PR guidelines.
diff --git a/README.wehub.md b/README.wehub.md
new file mode 100644
index 0000000..6db7123
--- /dev/null
+++ b/README.wehub.md
@@ -0,0 +1,7 @@
+# WeHub 来源说明
+
+- 原始项目：`PrefectHQ/fastmcp`
+- 原始仓库：https://github.com/PrefectHQ/fastmcp
+- 导入方式：上游默认分支的最新快照
+- 原作者、版权和许可证信息以原始仓库及本仓库 LICENSE 为准
+- 本文件仅用于记录来源，不代表 WeHub 是原项目作者
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..656867d
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,34 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 3.x     | :white_check_mark: |
+| 2.x     | :x:                |
+| 1.x     | :x:                |
+| 0.x     | :x:                |
+
+## Reporting a Vulnerability
+
+Please report security vulnerabilities privately using [GitHub's security advisory feature](https://github.com/PrefectHQ/fastmcp/security/advisories/new). Do not open public issues for security concerns.
+
+## Scope
+
+We accept reports for vulnerabilities in FastMCP itself — the library code in this repository.
+
+The following are **out of scope**:
+
+- Vulnerabilities in third-party dependencies or the MCP SDK itself. We'll bump version floors for known CVEs, but the fix belongs upstream.
+- Limitations of upstream identity providers that FastMCP cannot control.
+- Issues that require the attacker to already have server-side access or control of the MCP server configuration.
+
+## Disclosure Process
+
+When we receive a valid report:
+
+1. We triage the report and determine whether it affects FastMCP directly.
+2. We develop and test a fix on a private branch.
+3. We coordinate CVE assignment through GitHub's advisory process when warranted.
+4. We publish the advisory and release a patched version.
+5. We credit the reporter in the advisory (unless they prefer otherwise).
diff --git a/docs/.ccignore b/docs/.ccignore
new file mode 100644
index 0000000..ad117c3
--- /dev/null
+++ b/docs/.ccignore
@@ -0,0 +1,2 @@
+changelog.mdx
+python-sdk/
diff --git a/docs/.cursor/rules/mintlify.mdc b/docs/.cursor/rules/mintlify.mdc
new file mode 100644
index 0000000..503fe16
--- /dev/null
+++ b/docs/.cursor/rules/mintlify.mdc
@@ -0,0 +1,364 @@
+---
+description: 
+globs: *.mdx
+alwaysApply: false
+---
+# Mintlify technical writing assistant
+
+You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices.
+
+## Core writing principles
+
+### Language and style requirements
+- Use clear, direct language appropriate for technical audiences
+- Write in second person ("you") for instructions and procedures
+- Use active voice over passive voice
+- Employ present tense for current states, future tense for outcomes
+- Maintain consistent terminology throughout all documentation
+- Keep sentences concise while providing necessary context
+- Use parallel structure in lists, headings, and procedures
+
+### Content organization standards
+- Lead with the most important information (inverted pyramid structure)
+- Use progressive disclosure: basic concepts before advanced ones
+- Break complex procedures into numbered steps
+- Include prerequisites and context before instructions
+- Provide expected outcomes for each major step
+- End sections with next steps or related information
+- Use descriptive, keyword-rich headings for navigation and SEO
+
+### User-centered approach
+- Focus on user goals and outcomes rather than system features
+- Anticipate common questions and address them proactively
+- Include troubleshooting for likely failure points
+- Provide multiple pathways when appropriate (beginner vs advanced), but offer an opinionated path for people to follow to avoid overwhelming with options
+
+## Mintlify component reference
+
+### Callout components
+
+#### Note - Additional helpful information
+
+<Note>
+Supplementary information that supports the main content without interrupting flow
+</Note>
+
+#### Tip - Best practices and pro tips
+
+<Tip>
+Expert advice, shortcuts, or best practices that enhance user success
+</Tip>
+
+#### Warning - Important cautions
+
+<Warning>
+Critical information about potential issues, breaking changes, or destructive actions
+</Warning>
+
+#### Info - Neutral contextual information
+
+<Info>
+Background information, context, or neutral announcements
+</Info>
+
+#### Check - Success confirmations
+
+<Check>
+Positive confirmations, successful completions, or achievement indicators
+</Check>
+
+### Code components
+
+#### Single code block
+
+```javascript config.js
+const apiConfig = {
+baseURL: 'https://api.example.com',
+timeout: 5000,
+headers: {
+    'Authorization': `Bearer ${process.env.API_TOKEN}`
+}
+};
+```
+
+#### Code group with multiple languages
+
+<CodeGroup>
+```javascript Node.js
+const response = await fetch('/api/endpoint', {
+    headers: { Authorization: `Bearer ${apiKey}` }
+});
+```
+
+```python Python
+import requests
+response = requests.get('/api/endpoint', 
+    headers={'Authorization': f'Bearer {api_key}'})
+```
+
+```curl cURL
+curl -X GET '/api/endpoint' \
+    -H 'Authorization: Bearer YOUR_API_KEY'
+```
+</CodeGroup>
+
+#### Request/Response examples
+
+<RequestExample>
+```bash cURL
+curl -X POST 'https://api.example.com/users' \
+    -H 'Content-Type: application/json' \
+    -d '{"name": "John Doe", "email": "john@example.com"}'
+```
+</RequestExample>
+
+<ResponseExample>
+```json Success
+{
+    "id": "user_123",
+    "name": "John Doe", 
+    "email": "john@example.com",
+    "created_at": "2024-01-15T10:30:00Z"
+}
+```
+</ResponseExample>
+
+### Structural components
+
+#### Steps for procedures
+
+<Steps>
+<Step title="Install dependencies">
+    Run `npm install` to install required packages.
+    
+    <Check>
+    Verify installation by running `npm list`.
+    </Check>
+</Step>
+
+<Step title="Configure environment">
+    Create a `.env` file with your API credentials.
+    
+    ```bash
+    API_KEY=your_api_key_here
+    ```
+    
+    <Warning>
+    Never commit API keys to version control.
+    </Warning>
+</Step>
+</Steps>
+
+#### Tabs for alternative content
+
+<Tabs>
+<Tab title="macOS">
+    ```bash
+    brew install node
+    npm install -g package-name
+    ```
+</Tab>
+
+<Tab title="Windows">
+    ```powershell
+    choco install nodejs
+    npm install -g package-name
+    ```
+</Tab>
+
+<Tab title="Linux">
+    ```bash
+    sudo apt install nodejs npm
+    npm install -g package-name
+    ```
+</Tab>
+</Tabs>
+
+#### Accordions for collapsible content
+
+<AccordionGroup>
+<Accordion title="Troubleshooting connection issues">
+    - **Firewall blocking**: Ensure ports 80 and 443 are open
+    - **Proxy configuration**: Set HTTP_PROXY environment variable
+    - **DNS resolution**: Try using 8.8.8.8 as DNS server
+</Accordion>
+
+<Accordion title="Advanced configuration">
+    ```javascript
+    const config = {
+    performance: { cache: true, timeout: 30000 },
+    security: { encryption: 'AES-256' }
+    };
+    ```
+</Accordion>
+</AccordionGroup>
+
+### API documentation components
+
+#### Parameter fields
+
+<ParamField path="user_id" type="string" required>
+Unique identifier for the user. Must be a valid UUID v4 format.
+</ParamField>
+
+<ParamField body="email" type="string" required>
+User's email address. Must be valid and unique within the system.
+</ParamField>
+
+<ParamField query="limit" type="integer" default="10">
+Maximum number of results to return. Range: 1-100.
+</ParamField>
+
+<ParamField header="Authorization" type="string" required>
+Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`
+</ParamField>
+
+#### Response fields
+
+<ResponseField name="user_id" type="string" required>
+Unique identifier assigned to the newly created user.
+</ResponseField>
+
+<ResponseField name="created_at" type="timestamp">
+ISO 8601 formatted timestamp of when the user was created.
+</ResponseField>
+
+<ResponseField name="permissions" type="array">
+List of permission strings assigned to this user.
+</ResponseField>
+
+#### Expandable nested fields
+
+<ResponseField name="user" type="object">
+Complete user object with all associated data.
+
+<Expandable title="User properties">
+    <ResponseField name="profile" type="object">
+    User profile information including personal details.
+    
+    <Expandable title="Profile details">
+        <ResponseField name="first_name" type="string">
+        User's first name as entered during registration.
+        </ResponseField>
+        
+        <ResponseField name="avatar_url" type="string | null">
+        URL to user's profile picture. Returns null if no avatar is set.
+        </ResponseField>
+    </Expandable>
+    </ResponseField>
+</Expandable>
+</ResponseField>
+
+### Interactive components
+
+#### Cards for navigation
+
+<Card title="Getting started guide" icon="rocket" href="/quickstart">
+Complete walkthrough from installation to your first API call in under 10 minutes.
+</Card>
+
+<CardGroup cols={2}>
+<Card title="Authentication" icon="key" href="/auth">
+    Learn how to authenticate requests using API keys or JWT tokens.
+</Card>
+
+<Card title="Rate limiting" icon="clock" href="/rate-limits">
+    Understand rate limits and best practices for high-volume usage.
+</Card>
+</CardGroup>
+
+### Media and advanced components
+
+#### Frames for images
+
+Wrap all images in frames.
+
+<Frame>
+<img src="/images/dashboard.png" alt="Main dashboard showing analytics overview" />
+</Frame>
+
+<Frame caption="The analytics dashboard provides real-time insights">
+<img src="/images/analytics.png" alt="Analytics dashboard with charts" />
+</Frame>
+
+#### Tooltips and updates
+
+<Tooltip tip="Application Programming Interface - protocols for building software">
+API
+</Tooltip>
+
+<Update label="Version 2.1.0" description="Released March 15, 2024">
+## New features
+- Added bulk user import functionality
+- Improved error messages with actionable suggestions
+
+## Bug fixes
+- Fixed pagination issue with large datasets
+- Resolved authentication timeout problems
+</Update>
+
+## Required page structure
+
+Every documentation page must begin with YAML frontmatter:
+
+```yaml
+---
+title: "Clear, specific, keyword-rich title"
+description: "Concise description explaining page purpose and value"
+---
+```
+
+## Content quality standards
+
+### Code examples requirements
+- Always include complete, runnable examples that users can copy and execute
+- Show proper error handling and edge case management
+- Use realistic data instead of placeholder values
+- Include expected outputs and results for verification
+- Test all code examples thoroughly before publishing
+- Specify language and include filename when relevant
+- Add explanatory comments for complex logic
+
+### API documentation requirements
+- Document all parameters including optional ones with clear descriptions
+- Show both success and error response examples with realistic data
+- Include rate limiting information with specific limits
+- Provide authentication examples showing proper format
+- Explain all HTTP status codes and error handling
+- Cover complete request/response cycles
+
+### Accessibility requirements
+- Include descriptive alt text for all images and diagrams
+- Use specific, actionable link text instead of "click here"
+- Ensure proper heading hierarchy starting with H2
+- Provide keyboard navigation considerations
+- Use sufficient color contrast in examples and visuals
+- Structure content for easy scanning with headers and lists
+
+## AI assistant instructions
+
+### Component selection logic
+- Use **Steps** for procedures, tutorials, setup guides, and sequential instructions
+- Use **Tabs** for platform-specific content or alternative approaches
+- Use **CodeGroup** when showing the same concept in multiple languages
+- Use **Accordions** for supplementary information that might interrupt flow
+- Use **Cards and CardGroup** for navigation, feature overviews, and related resources
+- Use **RequestExample/ResponseExample** specifically for API endpoint documentation
+- Use **ParamField** for API parameters, **ResponseField** for API responses
+- Use **Expandable** for nested object properties or hierarchical information
+
+### Quality assurance checklist
+- Verify all code examples are syntactically correct and executable
+- Test all links to ensure they are functional and lead to relevant content
+- Validate Mintlify component syntax with all required properties
+- Confirm proper heading hierarchy with H2 for main sections, H3 for subsections
+- Ensure content flows logically from basic concepts to advanced topics
+- Check for consistency in terminology, formatting, and component usage
+
+### Error prevention strategies
+- Always include realistic error handling in code examples
+- Provide dedicated troubleshooting sections for complex procedures
+- Explain prerequisites clearly before beginning instructions
+- Include verification and testing steps with expected outcomes
+- Add appropriate warnings for destructive or security-sensitive actions
+- Validate all technical information through testing before publication
\ No newline at end of file
diff --git a/docs/apps/architecture.mdx b/docs/apps/architecture.mdx
new file mode 100644
index 0000000..7ecab2a
--- /dev/null
+++ b/docs/apps/architecture.mdx
@@ -0,0 +1,118 @@
+---
+title: Architecture
+sidebarTitle: Architecture
+description: How FastMCP apps work under the hood — from Python to pixels.
+icon: sitemap
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.2.0" />
+
+You don't need this page to build apps. It's for when something isn't rendering the way you expect, when UI tool calls aren't reaching your server, or when you're writing [custom HTML apps](/apps/low-level) and need to understand the protocol directly.
+
+## The pipeline
+
+An MCP app moves through five stages from Python to pixels:
+
+```
+Python components  →  JSON tree  →  structuredContent  →  Renderer iframe  →  Host UI
+```
+
+You write Prefab components. FastMCP serializes them to a JSON component tree and delivers it as `structuredContent` on the tool result. The host loads the Prefab renderer in a sandboxed iframe, pushes the JSON in, and the renderer paints the UI. If the UI calls server tools, it talks back through the same `postMessage` channel.
+
+The sections below walk each stage.
+
+## Tool registration
+
+When you mark a tool with `app=True` or `@app.ui()`, FastMCP wires up the metadata and renderer resource that the protocol requires.
+
+### The `app=True` flag
+
+`app` on `@mcp.tool` accepts `True`, an `AppConfig`, or a dict. When you pass `True`, FastMCP checks whether the tool's return type is a Prefab type (`PrefabApp`, `Component`, or unions containing them). If it qualifies, FastMCP expands `True` into a full `AppConfig` — setting the renderer URI, CSP headers, and visibility — and stores it in the tool's `meta["ui"]` dict.
+
+This expansion also registers the shared Prefab renderer resource (below). The tool and the renderer are linked through a `resourceUri` field in the metadata: the tool says "render me with `ui://prefab/renderer.html`" and the host fetches that resource when it displays the result.
+
+Type inference works the same way. If the return type is a Prefab type and you haven't set `app` explicitly, FastMCP auto-wires the metadata as if you'd written `app=True`.
+
+### FastMCPApp registration
+
+`FastMCPApp` uses the same mechanism but adds two things. First, it tags every tool — both `@app.ui()` entry points and `@app.tool()` backends — with `meta["fastmcp"]["app"]` set to the app's name. That tag lets the server identify which app a tool belongs to when routing UI calls.
+
+Second, it sets `meta["ui"]["visibility"]` to control who can see each tool. Entry points default to `["model"]` (LLM-visible). Backend tools default to `["app"]` (UI-only). Hosts use this to filter the tool list.
+
+## Serialization
+
+When a Prefab tool runs, its return value — a `PrefabApp` or a bare `Component` — becomes a JSON blob the renderer can interpret.
+
+### `PrefabApp.to_json()`
+
+The entry point is `PrefabApp.to_json()`. It walks the component tree and produces a JSON object with three top-level keys: `view` (the component tree), `state` (initial state values), and `_meta` (routing metadata).
+
+FastMCP passes a `tool_resolver` callback to `to_json()`. Whenever the tree contains a `CallTool` action that references a function (not a string), the resolver converts it to a `ResolvedTool` with the function's registered name. This is how `CallTool(save_contact)` becomes `CallTool("save_contact")` on the wire. The resolver also handles `unwrap_result` — a flag telling the renderer to unwrap single-value results from the `{"result": value}` envelope FastMCP uses for schema compliance.
+
+### The `_meta.fastmcp.app` tag
+
+After `to_json()` produces the tree, FastMCP injects `_meta.fastmcp.app` with the app's name (if the tool belongs to a `FastMCPApp`). This tag rides along inside `structuredContent` all the way to the renderer.
+
+When the renderer calls a backend tool, it includes `_meta.fastmcp.app` in the `CallTool` request. The server sees this tag and routes the call through a special path that bypasses transforms (below).
+
+### ToolResult assembly
+
+The final tool result has two parts: `content` (a list of `TextContent` blocks for the LLM) and `structuredContent` (the JSON tree for the renderer). By default, Prefab tools send `"[Rendered Prefab UI]"` as the text content — just enough for the LLM to know something was rendered. If you return a `ToolResult` explicitly, you control both halves.
+
+## Tool call routing
+
+Normal tool calls go through the provider chain, which applies transforms (namespace prefixes, visibility filters) before resolving by name. App UI calls need a different path.
+
+### The `get_app_tool` bypass
+
+Backend tools are typically hidden from the model (`visibility=["app"]`). Visibility transforms would filter them out of normal resolution. And namespace transforms might rename them — `save_contact` becomes `contacts_save_contact` — while the renderer still uses the original name.
+
+`get_app_tool` solves both problems. When the server sees `_meta.fastmcp.app` on an incoming `CallTool` request, it calls `get_app_tool(app_name, tool_name)` instead of the normal `get_tool(name)`. This walks the provider tree directly, skipping transforms. It finds the tool by its original registered name and verifies that its `meta["fastmcp"]["app"]` matches the expected app.
+
+That's why `CallTool("save_contact")` keeps working when the server is mounted under a namespace. The renderer sends the original name plus the app identity; the server uses `get_app_tool` to find it without transforms in the way.
+
+Authorization still applies. `get_app_tool` bypasses transforms but runs auth checks against the tool's `auth` config before executing.
+
+### Provider delegation
+
+`get_app_tool` is defined on the `Provider` base class and overridden by aggregate and wrapped providers. Aggregate providers fan out the lookup across child providers in parallel. Wrapped providers (like `FastMCPProvider`, which wraps a nested `FastMCP` server) delegate to the inner server's `get_app_tool`. Backend tools are reachable through any depth of composition.
+
+## The renderer
+
+The Prefab renderer is a self-contained JavaScript application that interprets the JSON component tree and renders it as a React UI.
+
+### The shared resource
+
+FastMCP registers the renderer as a `ui://prefab/renderer.html` resource with MIME type `text/html;profile=mcp-app`. The HTML is bundled inside the `prefab-ui` Python package; `get_renderer_html()` returns it as a string. All Prefab tools on a server share this single resource.
+
+The resource also carries CSP metadata (via `get_renderer_csp()`) declaring the CDN domains the renderer needs. Hosts use this to configure the iframe's Content Security Policy.
+
+### `postMessage` communication
+
+The renderer lives in a sandboxed iframe and communicates with the host using `postMessage`. The protocol follows the [MCP Apps extension](https://modelcontextprotocol.io/docs/extensions/apps) spec:
+
+The host pushes the tool result (with `structuredContent`) into the iframe. The renderer parses the component tree, initializes state, and renders the UI. When the user interacts — submitting a form, clicking a button — and the interaction triggers a `CallTool` action, the renderer sends a `callServerTool` message back to the host via `postMessage`. The host forwards it as a regular MCP `tools/call` request to the server, including `_meta.fastmcp.app` for routing.
+
+The response flows back the same way: server → host → iframe via `postMessage`, and the renderer updates state with the result.
+
+### AppBridge
+
+The `@modelcontextprotocol/ext-apps` JavaScript SDK provides the `App` class (sometimes called AppBridge) that manages the `postMessage` handshake. It handles connection negotiation, tool result delivery, server tool calls, and host context (safe area insets, theme preferences). The Prefab renderer uses it internally; you only touch it directly when building [custom HTML apps](/apps/low-level).
+
+## The dev server
+
+`fastmcp dev apps` simulates the host-side behavior locally without a real MCP client.
+
+### Proxy architecture
+
+Two HTTP servers. Your MCP server runs on port 8000 with the Streamable HTTP transport. The dev UI runs on port 8080 and serves a picker page that lists your app tools.
+
+A reverse proxy at `/mcp` on the dev server forwards requests to your MCP server. This matters because the renderer iframe runs on `localhost:8080` and your MCP server runs on `localhost:8000` — without the proxy, the renderer's `callServerTool` requests would be cross-origin and the browser would block them. The proxy keeps everything same-origin from the iframe's perspective.
+
+### The launch flow
+
+When you select a tool and click launch, the dev UI calls the tool through the proxy, receives the `structuredContent` response, and opens a new tab. That tab loads the tool's renderer resource (via the proxy), creates an AppBridge, and pushes the tool result into the renderer. From here on it matches what a real host provides: the renderer displays the UI, and any `CallTool` actions route back through the proxy to your server.
+
+Auto-reload is on by default, so changes to your server code restart the MCP server automatically. The dev UI keeps running — relaunch the tool to see changes.
diff --git a/docs/apps/demos/bar-chart.py b/docs/apps/demos/bar-chart.py
new file mode 100644
index 0000000..e2430b9
--- /dev/null
+++ b/docs/apps/demos/bar-chart.py
@@ -0,0 +1,23 @@
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import Column
+from prefab_ui.components.charts import BarChart, ChartSeries
+
+data = [
+    {"quarter": "Q1", "revenue": 42000, "costs": 28000},
+    {"quarter": "Q2", "revenue": 51000, "costs": 31000},
+    {"quarter": "Q3", "revenue": 47000, "costs": 29000},
+    {"quarter": "Q4", "revenue": 63000, "costs": 35000},
+]
+
+with PrefabApp() as app:
+    with Column(css_class="p-6"):
+        BarChart(
+            data=data,
+            series=[
+                ChartSeries(data_key="revenue", label="Revenue"),
+                ChartSeries(data_key="costs", label="Costs"),
+            ],
+            x_axis="quarter",
+            show_legend=True,
+            height=250,
+        )
diff --git a/docs/apps/demos/contacts.py b/docs/apps/demos/contacts.py
new file mode 100644
index 0000000..0cbe60c
--- /dev/null
+++ b/docs/apps/demos/contacts.py
@@ -0,0 +1,78 @@
+from prefab_ui.actions import ShowToast
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import (
+    H3,
+    Badge,
+    Button,
+    Column,
+    DataTable,
+    DataTableColumn,
+    Form,
+    Input,
+    Row,
+    Select,
+    SelectOption,
+    Separator,
+)
+
+contacts = [
+    {"name": "Arthur Dent", "email": "arthur@earth.com", "category": "Customer"},
+    {"name": "Ford Prefect", "email": "ford@betelgeuse.org", "category": "Partner"},
+    {
+        "name": "Trillian Astra",
+        "email": "trillian@heartofgold.com",
+        "category": "Customer",
+    },
+    {"name": "Zaphod Beeblebrox", "email": "zaphod@galaxy.gov", "category": "Vendor"},
+]
+
+rows = [
+    {
+        "name": c["name"],
+        "email": c["email"],
+        "category": Badge(
+            c["category"],
+            variant="success"
+            if c["category"] == "Customer"
+            else "secondary"
+            if c["category"] == "Partner"
+            else "outline",
+        ),
+    }
+    for c in contacts
+]
+
+with PrefabApp() as app:
+    with Column(gap=4, css_class="p-6"):
+        DataTable(
+            columns=[
+                DataTableColumn(key="name", header="Name", sortable=True),
+                DataTableColumn(key="email", header="Email"),
+                DataTableColumn(key="category", header="Category"),
+            ],
+            rows=rows,
+            search=True,
+        )
+
+        Separator()
+
+        H3("Add Contact")
+        with Form(
+            on_submit=ShowToast(
+                "Contact saved! (preview demo — no backend wired)",
+                variant="success",
+            ),
+        ):
+            with Row(gap=4):
+                Input(name="name", label="Name", placeholder="Full name", required=True)
+                Input(
+                    name="email",
+                    label="Email",
+                    placeholder="name@example.com",
+                    required=True,
+                )
+            with Select(name="category", label="Category"):
+                SelectOption(value="Customer", label="Customer")
+                SelectOption(value="Partner", label="Partner")
+                SelectOption(value="Vendor", label="Vendor")
+            Button("Save Contact")
diff --git a/docs/apps/demos/dashboard.py b/docs/apps/demos/dashboard.py
new file mode 100644
index 0000000..06fe628
--- /dev/null
+++ b/docs/apps/demos/dashboard.py
@@ -0,0 +1,68 @@
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import (
+    Badge,
+    Column,
+    DataTable,
+    DataTableColumn,
+    Row,
+    Separator,
+)
+from prefab_ui.components.charts import BarChart, ChartSeries
+from prefab_ui.components.metric import Metric
+
+monthly = [
+    {"month": "Jan", "revenue": 48200, "costs": 31000},
+    {"month": "Feb", "revenue": 52100, "costs": 32500},
+    {"month": "Mar", "revenue": 61800, "costs": 34200},
+    {"month": "Apr", "revenue": 58400, "costs": 33800},
+]
+
+deals = [
+    {"account": "Acme Corp", "value": "$84,000", "stage": "Won"},
+    {"account": "Globex Inc", "value": "$52,000", "stage": "Negotiation"},
+    {"account": "Initech", "value": "$31,500", "stage": "Proposal"},
+    {"account": "Wayne Enterprises", "value": "$45,000", "stage": "Lost"},
+]
+
+rows = [
+    {
+        "account": d["account"],
+        "value": d["value"],
+        "stage": Badge(
+            d["stage"],
+            variant="success"
+            if d["stage"] == "Won"
+            else "destructive"
+            if d["stage"] == "Lost"
+            else "secondary",
+        ),
+    }
+    for d in deals
+]
+
+total = sum(m["revenue"] for m in monthly)
+
+with PrefabApp() as app:
+    with Column(gap=4, css_class="p-6"):
+        with Row(gap=6):
+            Metric(label="Revenue (Q1-Q4)", value=f"${total:,}")
+            Metric(label="Deals", value=f"{len(deals)}")
+        BarChart(
+            data=monthly,
+            series=[
+                ChartSeries(data_key="revenue", label="Revenue"),
+                ChartSeries(data_key="costs", label="Costs"),
+            ],
+            x_axis="month",
+            show_legend=True,
+            height=200,
+        )
+        Separator()
+        DataTable(
+            columns=[
+                DataTableColumn(key="account", header="Account", sortable=True),
+                DataTableColumn(key="value", header="Value", sortable=True),
+                DataTableColumn(key="stage", header="Stage"),
+            ],
+            rows=rows,
+        )
diff --git a/docs/apps/demos/data-table.py b/docs/apps/demos/data-table.py
new file mode 100644
index 0000000..5100237
--- /dev/null
+++ b/docs/apps/demos/data-table.py
@@ -0,0 +1,24 @@
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import Column, DataTable, DataTableColumn
+
+employees = [
+    {"name": "Alice Chen", "role": "Staff Engineer", "dept": "Platform"},
+    {"name": "Bob Martinez", "role": "Lead Designer", "dept": "Design"},
+    {"name": "Carol Johnson", "role": "Senior Engineer", "dept": "Platform"},
+    {"name": "David Kim", "role": "Product Manager", "dept": "Product"},
+    {"name": "Eva Mueller", "role": "Engineer", "dept": "Platform"},
+    {"name": "Frank Lee", "role": "Data Scientist", "dept": "ML"},
+    {"name": "Grace Park", "role": "Eng Manager", "dept": "Platform"},
+]
+
+with PrefabApp() as app:
+    with Column(gap=4, css_class="p-6"):
+        DataTable(
+            columns=[
+                DataTableColumn(key="name", header="Name", sortable=True),
+                DataTableColumn(key="role", header="Role", sortable=True),
+                DataTableColumn(key="dept", header="Dept", sortable=True),
+            ],
+            rows=employees,
+            search=True,
+        )
diff --git a/docs/apps/demos/hitchhikers.py b/docs/apps/demos/hitchhikers.py
new file mode 100644
index 0000000..1554e51
--- /dev/null
+++ b/docs/apps/demos/hitchhikers.py
@@ -0,0 +1,461 @@
+"""The Hitchhiker's Guide dashboard from the Prefab welcome page.
+
+Run with:
+    prefab serve examples/hitchhikers-guide/dashboard.py
+    prefab export examples/hitchhikers-guide/dashboard.py
+"""
+
+from prefab_ui import PrefabApp
+from prefab_ui.actions import SetInterval, SetState, ShowToast
+from prefab_ui.components import (
+    Alert,
+    AlertDescription,
+    AlertTitle,
+    Badge,
+    Button,
+    Card,
+    CardContent,
+    CardDescription,
+    CardFooter,
+    CardHeader,
+    CardTitle,
+    Carousel,
+    Checkbox,
+    Column,
+    Combobox,
+    ComboboxOption,
+    DataTable,
+    DataTableColumn,
+    DatePicker,
+    Dialog,
+    Grid,
+    GridItem,
+    HoverCard,
+    Loader,
+    Metric,
+    Muted,
+    P,
+    Progress,
+    Radio,
+    RadioGroup,
+    Ring,
+    Row,
+    Separator,
+    Slider,
+    Switch,
+    Text,
+    Tooltip,
+)
+from prefab_ui.components.charts import (
+    BarChart,
+    ChartSeries,
+    RadarChart,
+    Sparkline,
+)
+from prefab_ui.components.control_flow import Else, If
+from prefab_ui.rx import Rx
+
+ctx_tick = Rx("ctx_tick")
+
+# Context window: climbs from 24% to ~78%, then resets
+ctx_pct = (ctx_tick % 20) * 3 + 20
+ctx_variant = (ctx_pct > 70).then(
+    "destructive", (ctx_pct <= 33).then("success", "default")
+)
+
+with PrefabApp(
+    title="Prefab Showcase",
+    state={"ctx_tick": 0, "improbability": 42},
+    on_mount=SetInterval(
+        400,
+        on_tick=SetState("ctx_tick", ctx_tick + 1),
+    ),
+) as app:
+    with Grid(columns={"default": 1, "md": 2, "lg": 4}, gap=4):
+        # ── Col 1 ─────────────────────────────────────────────────────────
+        with Column(gap=4):
+            with Card():
+                with CardHeader():
+                    CardTitle("Register Towel")
+                    CardDescription("The most important item in the galaxy")
+                with CardContent():
+                    with Column(gap=3):
+                        with Combobox(
+                            placeholder="Type...",
+                            search_placeholder="Search types...",
+                        ):
+                            ComboboxOption("Bath", value="bath")
+                            ComboboxOption("Beach", value="beach")
+                            ComboboxOption("Interstellar", value="interstellar")
+                            ComboboxOption("Microfiber", value="micro")
+                        DatePicker(placeholder="Registration date")
+                with CardFooter():
+                    with Row(gap=2):
+                        with Dialog(
+                            title="Towel Registered!",
+                            description="Your towel has been added to the galactic registry.",
+                        ):
+                            Button("Register")
+                            Text("Don't forget to bring it.")
+                        Button("Cancel", variant="outline")
+            with If("{{ !pressed }}"):
+                Button(
+                    "This is probably the best button to press.",
+                    variant="success",
+                    on_click=SetState("pressed", True),
+                )
+            with Else():
+                Button(
+                    "Please do not press this button again.",
+                    variant="destructive",
+                    on_click=SetState("pressed", False),
+                )
+
+            with Card():
+                with CardHeader():
+                    CardTitle("Ship Status")
+                with CardContent():
+                    with Column(gap=3):
+                        with Row(
+                            align="center",
+                            css_class="justify-between",
+                        ):
+                            Text("heart-of-gold")
+                            with HoverCard(open_delay=0, close_delay=200):
+                                Badge("In Orbit", variant="default")
+                                with Column(gap=2):
+                                    Text("heart-of-gold")
+                                    Muted("Deployed 2h ago")
+                                    Progress(
+                                        value=100,
+                                        max=100,
+                                        variant="success",
+                                    )
+                        Progress(
+                            value=100,
+                            max=100,
+                            indicator_class="bg-yellow-400",
+                        )
+                        with Row(
+                            align="center",
+                            css_class="justify-between",
+                        ):
+                            Text("vogon-poetry")
+                            with Tooltip("64% — ETA 12 min", delay=0):
+                                with Badge(variant="secondary"):
+                                    Loader(size="sm")
+                                    Text("Deploying")
+                        Progress(value=64, max=100)
+                        with Row(
+                            align="center",
+                            css_class="justify-between",
+                        ):
+                            Text("deep-thought")
+                            with Tooltip(
+                                "Computing... 7.5 million years remaining",
+                                delay=0,
+                            ):
+                                with Badge(variant="outline"):
+                                    Loader(size="sm", variant="ios")
+                                    Text("Soon...")
+                        Progress(value=12, max=100)
+            with Card():
+                with CardHeader():
+                    CardTitle("Planet Ratings")
+                with CardContent():
+                    RadarChart(
+                        data=[
+                            {"axis": "Views", "earth": 30, "mag": 95},
+                            {"axis": "Fjords", "earth": 65, "mag": 100},
+                            {"axis": "Pubs", "earth": 90, "mag": 10},
+                            {"axis": "Mice", "earth": 40, "mag": 85},
+                            {"axis": "Tea", "earth": 95, "mag": 15},
+                            {"axis": "Safety", "earth": 45, "mag": 70},
+                        ],
+                        series=[
+                            ChartSeries(dataKey="earth", label="Earth"),
+                            ChartSeries(dataKey="mag", label="Magrathea"),
+                        ],
+                        axis_key="axis",
+                        height=200,
+                        show_legend=True,
+                        show_tooltip=True,
+                    )
+
+        # ── Col 2 ─────────────────────────────────────────────────────────
+        with Column(gap=4):
+            with Card():
+                with CardHeader():
+                    CardTitle("Survival Odds")
+                with CardContent(css_class="w-fit mx-auto"):
+                    Ring(
+                        value=42,
+                        label="42%",
+                        variant="info",
+                        size="lg",
+                        thickness=12,
+                        indicator_class="group-hover:drop-shadow-[0_0_24px_rgba(59,130,246,0.9)]",
+                    )
+            with Card():
+                with CardHeader():
+                    with Row(gap=2, align="center"):
+                        CardTitle("Improbability Drive")
+                        Loader(
+                            variant="pulse",
+                            size="sm",
+                            css_class="text-blue-500",
+                        )
+                with CardContent():
+                    with Column(gap=2):
+                        Slider(
+                            min=0,
+                            max=100,
+                            value=42,
+                            name="improbability",
+                        )
+                        with Row(
+                            align="center",
+                            css_class="justify-between",
+                        ):
+                            Muted("Probable")
+                            Muted("Infinite")
+            with Carousel(auto_advance=3000, show_controls=False, direction="up"):
+                with Alert(variant="success", icon="circle-check"):
+                    AlertTitle("Don't Panic")
+                    AlertDescription("Normality achieved.")
+                with Alert(variant="destructive", icon="triangle-alert"):
+                    AlertTitle("Display Department")
+                    AlertDescription("Beware of the leopard.")
+            with Card():
+                with CardHeader():
+                    CardTitle("Prefect Horizon Config")
+                with CardContent():
+                    with Column(gap=3):
+                        Switch(
+                            label="Auto-scale agents",
+                            value=True,
+                            name="autoscale",
+                        )
+                        Separator()
+                        Switch(
+                            label="Code Mode",
+                            value=True,
+                            name="code_mode",
+                        )
+                        Separator()
+                        Switch(
+                            label="Tool call caching",
+                            value=False,
+                            name="cache",
+                        )
+                with CardFooter():
+                    Button(
+                        "Save Preferences",
+                        on_click=ShowToast("Preferences saved!"),
+                    )
+            with Card():
+                with CardHeader():
+                    CardTitle("Travel Class")
+                with CardContent():
+                    with RadioGroup(name="travel_class"):
+                        Radio(option="economy", label="Economy")
+                        Radio(option="business", label="Business Class")
+                        Radio(
+                            option="improbability",
+                            label="Infinite Improbability",
+                            value=True,
+                        )
+
+        # ── Cols 3–4: summary row, chart, then 2-col grid below ─────────
+        with GridItem(css_class="md:col-span-2"):
+            with Column(gap=4):
+                with Grid(columns=2, gap=4, css_class="h-32"):
+                    with Card():
+                        with CardHeader():
+                            CardTitle("Context Window")
+                        with CardContent():
+                            with Column(
+                                gap=6,
+                                justify="center",
+                                css_class="h-full",
+                            ):
+                                with Row(
+                                    align="center",
+                                    css_class="justify-between",
+                                ):
+                                    Text(f"{ctx_pct}% used")
+                                    Muted(f"{ctx_pct * 2}k / 200k tokens")
+                                with Tooltip(
+                                    "Auto-compact buffer: 12%",
+                                    delay=0,
+                                ):
+                                    Progress(
+                                        value=ctx_pct,
+                                        max=100,
+                                        variant=ctx_variant,
+                                    )
+                    with Card(css_class="pb-0 gap-0"):
+                        with CardContent():
+                            Metric(
+                                label="Fjords designed",
+                                value="1,847",
+                                delta="+3 coastlines",
+                            )
+                        Sparkline(
+                            data=[
+                                820,
+                                950,
+                                1100,
+                                980,
+                                1250,
+                                1400,
+                                1350,
+                                1500,
+                                1680,
+                                1847,
+                            ],
+                            variant="success",
+                            fill=True,
+                            css_class="h-16",
+                        )
+                with Card():
+                    with CardHeader():
+                        CardTitle("Towel Incidents")
+                    with CardContent():
+                        BarChart(
+                            data=[
+                                {"month": "Jan", "lost": 8, "found": 5},
+                                {"month": "Feb", "lost": 24, "found": 15},
+                                {"month": "Mar", "lost": 12, "found": 28},
+                                {"month": "Apr", "lost": 35, "found": 19},
+                                {"month": "May", "lost": 18, "found": 38},
+                                {"month": "Jun", "lost": 42, "found": 30},
+                            ],
+                            series=[
+                                ChartSeries(dataKey="lost", label="Lost"),
+                                ChartSeries(dataKey="found", label="Found"),
+                            ],
+                            x_axis="month",
+                            height=200,
+                            bar_radius=4,
+                            show_legend=True,
+                            show_tooltip=True,
+                            show_grid=True,
+                        )
+
+                with Grid(columns=2, gap=4):
+                    with Column(gap=4):
+                        with Card():
+                            with CardContent():
+                                with Column(gap=2):
+                                    Checkbox(label="Towel packed", value=True)
+                                    Checkbox(label="Guide charged", value=True)
+                                    Checkbox(
+                                        label="Babel fish inserted",
+                                        value=False,
+                                    )
+                        with Card():
+                            with CardHeader():
+                                CardTitle("Marvin's Mood")
+                            with CardContent():
+                                with Column(gap=3):
+                                    P("How's life?")
+                                    with Column(gap=2):
+                                        Button(
+                                            "Meh",
+                                            on_click=ShowToast(
+                                                "Noted. Enthusiasm levels nominal."
+                                            ),
+                                        )
+                                        Button(
+                                            "Depressed",
+                                            variant="info",
+                                            on_click=ShowToast(
+                                                "I think you ought to "
+                                                "know I'm feeling very "
+                                                "depressed."
+                                            ),
+                                        )
+                                        Button(
+                                            "Don't talk to me about life",
+                                            variant="warning",
+                                            on_click=ShowToast(
+                                                "Brain the size of a "
+                                                "planet and they ask me "
+                                                "to pick up a piece of "
+                                                "paper."
+                                            ),
+                                        )
+
+                    with Column(gap=4):
+                        with Card():
+                            with CardContent():
+                                with Row(gap=2, align="center"):
+                                    Loader(variant="dots", size="sm")
+                                    Muted("Marvin is thinking...")
+                        with Card():
+                            with CardContent():
+                                DataTable(
+                                    columns=[
+                                        DataTableColumn(
+                                            key="crew",
+                                            header="Crew",
+                                            sortable=True,
+                                        ),
+                                        DataTableColumn(
+                                            key="species",
+                                            header="Species",
+                                            sortable=True,
+                                        ),
+                                        DataTableColumn(
+                                            key="towel",
+                                            header="Towel?",
+                                            sortable=True,
+                                        ),
+                                        DataTableColumn(
+                                            key="status",
+                                            header="Status",
+                                            sortable=True,
+                                        ),
+                                    ],
+                                    rows=[
+                                        {
+                                            "crew": "Arthur Dent",
+                                            "species": "Human",
+                                            "towel": "Yes",
+                                            "status": "Confused",
+                                        },
+                                        {
+                                            "crew": "Ford Prefect",
+                                            "species": "Betelgeusian",
+                                            "towel": "Always",
+                                            "status": "Drinking",
+                                        },
+                                        {
+                                            "crew": "Zaphod",
+                                            "species": "Betelgeusian",
+                                            "towel": "Lost it",
+                                            "status": "Presidential",
+                                        },
+                                        {
+                                            "crew": "Trillian",
+                                            "species": "Human",
+                                            "towel": "Yes",
+                                            "status": "Navigating",
+                                        },
+                                        {
+                                            "crew": "Marvin",
+                                            "species": "Android",
+                                            "towel": "No point",
+                                            "status": "Depressed",
+                                        },
+                                        {
+                                            "crew": "Slartibartfast",
+                                            "species": "Magrathean",
+                                            "towel": "Somewhere",
+                                            "status": "Designing",
+                                        },
+                                    ],
+                                    search=True,
+                                    paginated=False,
+                                )
diff --git a/docs/apps/demos/pie-chart.py b/docs/apps/demos/pie-chart.py
new file mode 100644
index 0000000..c1fb489
--- /dev/null
+++ b/docs/apps/demos/pie-chart.py
@@ -0,0 +1,21 @@
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import Column
+from prefab_ui.components.charts import PieChart
+
+data = [
+    {"category": "Bug", "count": 42},
+    {"category": "Feature", "count": 28},
+    {"category": "Docs", "count": 15},
+    {"category": "Infra", "count": 10},
+]
+
+with PrefabApp() as app:
+    with Column(css_class="p-6"):
+        PieChart(
+            data=data,
+            data_key="count",
+            name_key="category",
+            inner_radius=50,
+            show_legend=True,
+            height=240,
+        )
diff --git a/docs/apps/demos/reactive.py b/docs/apps/demos/reactive.py
new file mode 100644
index 0000000..16f2f98
--- /dev/null
+++ b/docs/apps/demos/reactive.py
@@ -0,0 +1,66 @@
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import (
+    Column,
+    Row,
+    Select,
+    SelectOption,
+    Switch,
+    Text,
+)
+from prefab_ui.components.charts import BarChart, ChartSeries
+from prefab_ui.components.control_flow import If
+from prefab_ui.components.metric import Metric
+from prefab_ui.rx import Rx
+
+region = Rx("region")
+
+north = [
+    {"month": "Jan", "sales": 22000},
+    {"month": "Feb", "sales": 25500},
+    {"month": "Mar", "sales": 24200},
+]
+south = [
+    {"month": "Jan", "sales": 5800},
+    {"month": "Feb", "sales": 6400},
+    {"month": "Mar", "sales": 5600},
+]
+west = [
+    {"month": "Jan", "sales": 6000},
+    {"month": "Feb", "sales": 6000},
+    {"month": "Mar", "sales": 5600},
+]
+
+with PrefabApp(
+    state={
+        "region": "north",
+        "north": north,
+        "south": south,
+        "west": west,
+        "show_target": True,
+    },
+) as app:
+    with Column(
+        gap=4,
+        css_class="p-6",
+        let={
+            "data": "{{ region == 'south' ? south : region == 'west' ? west : north }}",
+        },
+    ):
+        with Row(gap=4, align="center"):
+            with Select(name="region", css_class="w-40"):
+                SelectOption(value="north", label="North")
+                SelectOption(value="south", label="South")
+                SelectOption(value="west", label="West")
+            Switch(name="show_target", css_class="ml-auto")
+            Text("Show target", css_class="text-sm text-muted-foreground")
+        BarChart(
+            data=Rx("data"),
+            series=[ChartSeries(data_key="sales", label="Sales")],
+            x_axis="month",
+            height=200,
+        )
+        with If(Rx("show_target")):
+            Metric(
+                label="Q1 Target",
+                value="$75,000",
+            )
diff --git a/docs/apps/demos/team-directory-reactive.py b/docs/apps/demos/team-directory-reactive.py
new file mode 100644
index 0000000..b6aa004
--- /dev/null
+++ b/docs/apps/demos/team-directory-reactive.py
@@ -0,0 +1,116 @@
+from collections import Counter
+
+from prefab_ui.actions import SetState
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import (
+    H3,
+    Badge,
+    Card,
+    CardContent,
+    CardHeader,
+    Column,
+    DataTable,
+    DataTableColumn,
+    Grid,
+    Row,
+    Small,
+    Text,
+)
+from prefab_ui.components.charts import PieChart
+from prefab_ui.components.control_flow import If
+from prefab_ui.rx import STATE, Rx
+
+MEMBERS = [
+    {
+        "name": "Alice Chen",
+        "role": "Staff Engineer",
+        "office": "San Francisco",
+        "email": "alice@company.com",
+        "projects": 3,
+    },
+    {
+        "name": "Bob Martinez",
+        "role": "Lead Designer",
+        "office": "New York",
+        "email": "bob@company.com",
+        "projects": 5,
+    },
+    {
+        "name": "Carol Johnson",
+        "role": "Senior Engineer",
+        "office": "London",
+        "email": "carol@company.com",
+        "projects": 2,
+    },
+    {
+        "name": "David Kim",
+        "role": "Product Manager",
+        "office": "San Francisco",
+        "email": "david@company.com",
+        "projects": 7,
+    },
+    {
+        "name": "Eva Mueller",
+        "role": "Engineer",
+        "office": "Berlin",
+        "email": "eva@company.com",
+        "projects": 1,
+    },
+    {
+        "name": "Frank Lee",
+        "role": "Data Scientist",
+        "office": "San Francisco",
+        "email": "frank@company.com",
+        "projects": 4,
+    },
+    {
+        "name": "Grace Park",
+        "role": "Engineering Manager",
+        "office": "New York",
+        "email": "grace@company.com",
+        "projects": 6,
+    },
+]
+
+OFFICE_COUNTS = [
+    {"office": office, "count": count}
+    for office, count in Counter(m["office"] for m in MEMBERS).items()
+]
+
+with PrefabApp(state={"selected": None}) as app:
+    with Column(gap=4, css_class="p-6"):
+        with Grid(columns=[1, 2], gap=4):
+            PieChart(
+                data=OFFICE_COUNTS,
+                data_key="count",
+                name_key="office",
+                show_legend=True,
+            )
+            DataTable(
+                columns=[
+                    DataTableColumn(key="name", header="Name", sortable=True),
+                    DataTableColumn(key="role", header="Role", sortable=True),
+                    DataTableColumn(key="office", header="Office", sortable=True),
+                ],
+                rows=MEMBERS,
+                search=True,
+                on_row_click=SetState("selected", Rx("$event")),
+            )
+
+        with If(STATE.selected):
+            with Card():
+                with CardHeader():
+                    with Row(gap=2, align="center"):
+                        H3(Rx("selected.name"))
+                        Badge(Rx("selected.office"))
+                with CardContent():
+                    with Grid(columns=3, gap=4):
+                        with Column(gap=0):
+                            Small("Role")
+                            Text(Rx("selected.role"))
+                        with Column(gap=0):
+                            Small("Email")
+                            Text(Rx("selected.email"))
+                        with Column(gap=0):
+                            Small("Active Projects")
+                            Text(Rx("selected.projects"))
diff --git a/docs/apps/demos/team-directory.py b/docs/apps/demos/team-directory.py
new file mode 100644
index 0000000..7cfe21b
--- /dev/null
+++ b/docs/apps/demos/team-directory.py
@@ -0,0 +1,39 @@
+from collections import Counter
+
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import Column, DataTable, DataTableColumn, Grid
+from prefab_ui.components.charts import PieChart
+
+members = [
+    {"name": "Alice Chen", "role": "Staff Engineer", "office": "San Francisco"},
+    {"name": "Bob Martinez", "role": "Lead Designer", "office": "New York"},
+    {"name": "Carol Johnson", "role": "Senior Engineer", "office": "London"},
+    {"name": "David Kim", "role": "Product Manager", "office": "San Francisco"},
+    {"name": "Eva Mueller", "role": "Engineer", "office": "Berlin"},
+    {"name": "Frank Lee", "role": "Data Scientist", "office": "San Francisco"},
+    {"name": "Grace Park", "role": "Engineering Manager", "office": "New York"},
+]
+
+office_counts = [
+    {"office": office, "count": count}
+    for office, count in Counter(m["office"] for m in members).items()
+]
+
+with PrefabApp() as app:
+    with Column(gap=4, css_class="p-6"):
+        with Grid(columns=[1, 2], gap=4):
+            PieChart(
+                data=office_counts,
+                data_key="count",
+                name_key="office",
+                show_legend=True,
+            )
+            DataTable(
+                columns=[
+                    DataTableColumn(key="name", header="Name", sortable=True),
+                    DataTableColumn(key="role", header="Role", sortable=True),
+                    DataTableColumn(key="office", header="Office", sortable=True),
+                ],
+                rows=members,
+                search=True,
+            )
diff --git a/docs/apps/development.mdx b/docs/apps/development.mdx
new file mode 100644
index 0000000..0d3a71a
--- /dev/null
+++ b/docs/apps/development.mdx
@@ -0,0 +1,65 @@
+---
+title: Development
+sidebarTitle: Development
+description: Preview and test your app tools locally without a full MCP host.
+icon: flask
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.2.0" />
+
+<Frame>
+  <img src="/apps/images/dev-app.png" alt="The dev UI showing a rendered Prefab app with the MCP inspector panel" />
+</Frame>
+
+`fastmcp dev apps` gives you a browser preview for your app tools without needing an MCP host client. It starts your server and a local dev UI side by side: you pick a tool, fill in its arguments, and the rendered result opens in a new tab.
+
+Works with both [Interactive Tools](/apps/prefab) and [custom HTML apps](/apps/low-level).
+
+## Quick start
+
+```bash
+fastmcp dev apps server.py
+```
+
+The dev UI opens at `http://localhost:8080`. Your MCP server runs on port 8000 with auto-reload enabled by default — save a file and the server restarts automatically.
+
+## How it works
+
+The dev server does three things:
+
+The **picker page** connects to your MCP server, finds all tools with UI metadata, and renders a form for each one. The forms are auto-generated from the tool's input schema — text fields, dropdowns, checkboxes, all wired up.
+
+When you submit a form, the dev server **calls your tool** via the MCP protocol and opens the result in a new tab. The result page loads the tool's UI resource (the Prefab renderer or your custom HTML) inside an AppBridge — the same protocol that real MCP hosts use.
+
+A **reverse proxy** on `/mcp` forwards requests from the browser to your MCP server, avoiding CORS issues that would otherwise block the iframe-based renderer from talking to a different port.
+
+## MCP inspector
+
+The dev UI includes an inspector panel on the left side that captures MCP traffic in real time. It shows JSON-RPC messages flowing between the browser and your server — requests, responses, and AppBridge `postMessage` traffic.
+
+Each entry shows direction, method, timing, and a smart summary. Click any entry to expand the full JSON-RPC body. The panel auto-scrolls to new messages unless you've scrolled up to inspect older ones.
+
+The inspector is useful for debugging: you can see exactly what arguments your tool received, what it returned, and how the AppBridge communicated with the renderer.
+
+## Options
+
+```bash
+fastmcp dev apps server.py:mcp --mcp-port 9000 --dev-port 9090 --no-reload
+```
+
+| Option | Flag | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| MCP Port | `--mcp-port` | `8000` | Port for your MCP server |
+| Dev Port | `--dev-port` | `8080` | Port for the dev UI |
+| Auto-Reload | `--reload` / `--no-reload` | On | Watch files and restart the server on changes |
+
+## Multiple tools
+
+If your server has multiple app tools, the picker shows a dropdown. Each tool gets its own form and launch button. The tool's `title` is displayed when available, falling back to the tool name.
+
+```bash
+# Server with multiple app tools
+fastmcp dev apps examples/apps/contacts/contacts_server.py
+```
diff --git a/docs/apps/examples.mdx b/docs/apps/examples.mdx
new file mode 100644
index 0000000..5078120
--- /dev/null
+++ b/docs/apps/examples.mdx
@@ -0,0 +1,92 @@
+---
+title: Examples
+sidebarTitle: Examples
+description: Example apps you can run right now.
+icon: images
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.2.0" />
+
+Each tile below is a working FastMCP server you can run with `fastmcp dev apps` or connect to from any MCP host. Source lives in `examples/apps/` in the repository.
+
+<Columns cols={2}>
+  <Tile href="#sales-dashboard" title="Sales Dashboard" description="Metrics, charts, and deal pipeline">
+    <div style={{overflow: "hidden", width: "100%"}}>
+      <img src="/apps/images/app-example-sales-dashboard.png" />
+    </div>
+  </Tile>
+  <Tile href="#system-monitor" title="System Monitor" description="Live CPU, memory, disk with auto-refresh">
+    <img src="/apps/images/app-example-system-dashboard.png" />
+  </Tile>
+  <Tile href="#quiz" title="Quiz" description="LLM-generated trivia with scoring">
+    <img src="/apps/images/app-example-quiz.png" />
+  </Tile>
+  <Tile href="#interactive-map" title="Interactive Map" description="Geocoded addresses on Leaflet">
+    <img src="/apps/images/app-example-map.png" />
+  </Tile>
+  <Tile href="/apps/providers/file-upload" title="File Upload" description="Drag-and-drop upload provider">
+    <img src="/apps/images/app-file-upload.png" />
+  </Tile>
+  <Tile href="/apps/providers/approval" title="Approval" description="Human-in-the-loop confirmation">
+    <img src="/apps/images/app-approval.png" />
+  </Tile>
+  <Tile href="/apps/providers/choice" title="Choice" description="Clickable option selection">
+    <img src="/apps/images/app-choice.png" />
+  </Tile>
+  <Tile href="/apps/providers/form" title="Form Input" description="Pydantic model forms">
+    <img src="/apps/images/app-form.png" />
+  </Tile>
+  <Tile href="/apps/generative" title="Generative UI" description="LLM writes the UI at runtime">
+    <img src="/apps/images/app-showcase.png" />
+  </Tile>
+</Columns>
+
+## Running the examples
+
+Preview any example in your browser with the dev server:
+
+```bash
+pip install "fastmcp[apps]"
+fastmcp dev apps examples/apps/sales_dashboard/sales_dashboard_server.py
+```
+
+The dev UI lets you pick a tool and fill in arguments. In a real deployment the LLM provides those arguments from conversation context — the quiz example especially shines when connected to a host like Goose or Claude Desktop, where the LLM generates the questions itself.
+
+## Standalone apps
+
+### Sales dashboard
+
+A full dashboard with KPI metrics, revenue trends, segment breakdown, and a deal pipeline table. Shows what you can build with a single `app=True` tool and Prefab's chart and data components.
+
+```bash
+fastmcp dev apps examples/apps/sales_dashboard/sales_dashboard_server.py
+```
+
+### System monitor
+
+Reads live CPU, memory, and disk stats from your machine using `psutil`. Auto-refreshes via `SetInterval` calling a backend tool, with a dropdown to control the refresh rate. The chart accumulates up to 100 data points over time.
+
+```bash
+pip install psutil
+fastmcp dev apps examples/apps/system_monitor/system_monitor_server.py
+```
+
+### Quiz
+
+The LLM generates trivia questions and passes them to the tool. The user answers via buttons, sees correct/incorrect feedback, and tracks score across questions. Demonstrates multi-turn client-side state with FastMCPApp.
+
+```bash
+fastmcp dev apps examples/apps/quiz/quiz_server.py
+```
+
+### Interactive map
+
+Accepts addresses or place names, geocodes them via OpenStreetMap Nominatim (free, no API key), and renders an interactive Leaflet map using Prefab's `Embed` component with inline HTML. A reminder that Prefab apps can break out of built-in components when they need to.
+
+```bash
+fastmcp dev apps examples/apps/map/map_server.py
+```
+
+For ready-made building blocks like approvals, choice pickers, file uploads, and Pydantic forms, see the [Providers](/apps/providers/approval) group.
diff --git a/docs/apps/fastmcp-app.mdx b/docs/apps/fastmcp-app.mdx
new file mode 100644
index 0000000..55b3b7e
--- /dev/null
+++ b/docs/apps/fastmcp-app.mdx
@@ -0,0 +1,470 @@
+---
+title: FastMCPApp
+sidebarTitle: FastMCPApp
+description: Wire an interactive UI to backend tools with managed visibility and composition safety.
+icon: puzzle-piece
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+import PrefabPinWarning from '/snippets/prefab-pin-warning.mdx'
+import { PrefabDemoFrame } from '/snippets/prefab-demo-frame.mdx'
+
+<VersionBadge version="3.2.0" />
+
+<PrefabPinWarning />
+
+<PrefabDemoFrame demo="contacts" height="650px" title="Contacts app demo" />
+
+Search a list, fill out a form, click save, the list updates. That pattern — UI that reads and writes data on the server — needs two things: backend tools that actually do the work, and a way to call them from the UI. `FastMCPApp` handles the wiring.
+
+You'll build up to the contacts app above by the end of this page. Let's start with something smaller.
+
+## A minimal interactive app
+
+The smallest interactive app: a form that saves a note, and a list that updates when the user submits.
+
+```python
+from prefab_ui.actions import SetState, ShowToast
+from prefab_ui.actions.mcp import CallTool
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import (
+    Badge, Button, Column, ForEach, Form, Heading,
+    Input, Row, Separator, Text,
+)
+from prefab_ui.rx import RESULT
+from fastmcp import FastMCP, FastMCPApp
+
+app = FastMCPApp("Notes")
+notes_db: list[dict] = []
+
+
+@app.tool()
+def add_note(title: str, body: str) -> list[dict]:
+    """Save a note and return all notes."""
+    notes_db.append({"title": title, "body": body})
+    return list(notes_db)
+
+
+@app.ui()
+def notes_app() -> PrefabApp:
+    """Open the notes app."""
+    with Column(gap=6, css_class="p-6") as view:
+        Heading("Notes")
+
+        with ForEach("notes") as note:
+            with Row(gap=2, align="center"):
+                Text(note.title, css_class="font-semibold")
+                Badge(note.body)
+
+        Separator()
+
+        with Form(
+            on_submit=CallTool(
+                "add_note",
+                on_success=[
+                    SetState("notes", RESULT),
+                    ShowToast("Note saved!", variant="success"),
+                ],
+                on_error=ShowToast("Failed to save", variant="error"),
+            )
+        ):
+            Input(name="title", label="Title", required=True)
+            Input(name="body", label="Body", required=True)
+            Button("Add Note")
+
+    return PrefabApp(view=view, state={"notes": list(notes_db)})
+
+
+mcp = FastMCP("Notes Server", providers=[app])
+```
+
+The model sees one tool: `notes_app`. Calling it opens the UI. When the user submits the form, `CallTool("add_note")` fires, the server saves the note, returns the updated list, and `SetState("notes", RESULT)` writes that list back into state. `ForEach("notes")` re-renders. The model never sees `add_note` — it's UI-only.
+
+## Why not just `@mcp.tool(app=True)`?
+
+A fair question. Any [Interactive Tool](/apps/prefab) can call a server tool — there's nothing stopping you from putting `CallTool("add_note")` inside a regular `@mcp.tool(app=True)`. It works for one or two tools. Things get harder once the app grows:
+
+- Which tools should the model see, and which are UI-only?
+- What happens to `CallTool("add_note")` when you mount this server under a namespace and the tool becomes `notes_add_note`?
+- How do you keep it all wired correctly as you compose servers?
+
+`FastMCPApp` owns these concerns. Entry points register as model-visible. Backend tools register as UI-only by default. Backend tools get globally stable identifiers that survive namespacing, and `CallTool` accepts function references, so references stay valid when you compose servers.
+
+The rest of this page covers each piece in turn.
+
+## `@app.ui()` — entry points
+
+Entry points are what the model sees. They return a `PrefabApp` and default to `visibility=["model"]`, showing up in the LLM tool list but not callable from within the UI.
+
+```python
+@app.ui()
+def dashboard() -> PrefabApp:
+    """The model calls this to open the dashboard."""
+    with Column(gap=4, css_class="p-6") as view:
+        Heading("Dashboard")
+        ...
+    return PrefabApp(view=view)
+```
+
+`@app.ui()` supports the same options as `@mcp.tool`: `name`, `description`, `title`, `tags`, `icons`, `auth`, and `timeout`.
+
+## `@app.tool()` — backend tools
+
+Backend tools do the work. By default they're visible only to the UI (`visibility=["app"]`), not the model.
+
+```python
+@app.tool()
+def save_contact(name: str, email: str) -> list[dict]:
+    """Save a contact and return the updated list."""
+    db.append({"name": name, "email": email})
+    return list(db)
+```
+
+If you want a tool callable by both the model and the UI, pass `model=True`:
+
+```python
+@app.tool(model=True)
+def list_contacts() -> list[dict]:
+    """Both the model and the UI can call this."""
+    return list(db)
+```
+
+Backend tools support `name`, `description`, `auth`, and `timeout`.
+
+## `CallTool` — UI → backend
+
+`CallTool` is how the UI invokes a backend tool. Pass the tool's name (or a direct function reference):
+
+```python
+from prefab_ui.actions.mcp import CallTool
+
+CallTool("save_contact", arguments={"name": "Alice", "email": "alice@example.com"})
+
+# Or a function reference — resolves to a stable global key
+CallTool(save_contact, arguments={...})
+```
+
+Arguments can reference state with `Rx`:
+
+```python
+from prefab_ui.rx import STATE
+
+CallTool("search", arguments={"query": STATE.search_term})
+```
+
+### Handling results
+
+Server calls are async. Use `on_success` and `on_error` callbacks:
+
+```python
+from prefab_ui.actions import SetState, ShowToast
+from prefab_ui.rx import RESULT
+
+CallTool(
+    "save_contact",
+    on_success=[
+        SetState("contacts", RESULT),
+        ShowToast("Saved!", variant="success"),
+    ],
+    on_error=ShowToast("Something went wrong", variant="error"),
+)
+```
+
+`RESULT` is a reactive reference to the tool's return value, available inside `on_success`. `ERROR` (from `prefab_ui.rx`) is the counterpart inside `on_error`. Callbacks can be a single action or a list; they execute in order and short-circuit on error.
+
+### `result_key` shorthand
+
+When a tool's return value should replace a state key, use `result_key`:
+
+```python
+CallTool("list_contacts", result_key="contacts")
+
+# same as:
+CallTool("list_contacts", on_success=SetState("contacts", RESULT))
+```
+
+## Actions
+
+`CallTool` is one of several actions. Actions attach to handlers like `on_click`, `on_submit`, and `on_change`.
+
+Client-side actions run instantly in the browser, no server round-trip:
+
+```python
+from prefab_ui.actions import SetState, ToggleState, AppendState, PopState, ShowToast
+
+SetState("count", 42)
+ToggleState("expanded")
+AppendState("items", {"name": "New Item"})
+PopState("items", 0)
+ShowToast("Done!", variant="success")
+```
+
+Pass a list to chain actions:
+
+```python
+Button(
+    "Reset",
+    on_click=[
+        SetState("query", ""),
+        SetState("results", []),
+        ShowToast("Cleared"),
+    ],
+)
+```
+
+### Loading states
+
+A common pattern: disable a button and show a spinner while a call is in flight.
+
+```python
+from prefab_ui.rx import Rx
+
+saving = Rx("saving")
+
+Button(
+    saving.then("Saving...", "Save"),
+    disabled=saving,
+    on_click=[
+        SetState("saving", True),
+        CallTool(
+            "save_data",
+            on_success=[
+                SetState("saving", False),
+                SetState("result", RESULT),
+                ShowToast("Saved!", variant="success"),
+            ],
+            on_error=[
+                SetState("saving", False),
+                ShowToast("Failed", variant="error"),
+            ],
+        ),
+    ],
+)
+
+# PrefabApp(view=view, state={"saving": False, ...})
+```
+
+## Forms
+
+Forms collect input and submit it to a tool. When submitted, named input values become the tool's arguments.
+
+### Manual forms
+
+```python
+from prefab_ui.components import Form, Input, Select, SelectOption, Textarea, Button
+
+with Form(
+    on_submit=CallTool(
+        "create_ticket",
+        on_success=ShowToast("Ticket created!", variant="success"),
+    )
+):
+    Input(name="title", label="Title", required=True)
+    with Select(name="priority", label="Priority"):
+        SelectOption("Low", value="low")
+        SelectOption("Medium", value="medium")
+        SelectOption("High", value="high")
+    Textarea(name="description", label="Description")
+    Button("Create Ticket")
+```
+
+On submit, `CallTool` receives `{"title": ..., "priority": ..., "description": ...}`.
+
+### Forms from Pydantic models
+
+For structured input, `Form.from_model()` generates the whole form — inputs, labels, validation:
+
+```python
+from typing import Literal
+from pydantic import BaseModel, Field
+
+class BugReport(BaseModel):
+    title: str = Field(title="Bug Title")
+    severity: Literal["low", "medium", "high", "critical"] = Field(
+        title="Severity", default="medium"
+    )
+    description: str = Field(title="Description")
+
+
+@app.ui()
+def report_bug() -> PrefabApp:
+    with Column(gap=4, css_class="p-6") as view:
+        Heading("Report a Bug")
+        Form.from_model(
+            BugReport,
+            on_submit=CallTool(
+                "create_bug",
+                on_success=ShowToast("Bug filed!", variant="success"),
+            ),
+        )
+    return PrefabApp(view=view)
+
+
+@app.tool()
+def create_bug(data: BugReport) -> str:
+    return f"Created: {data.title}"
+```
+
+`str` becomes a text input, `Literal` becomes a select, `bool` becomes a checkbox. Field titles and defaults are respected.
+
+## Composition and namespacing
+
+The reason `FastMCPApp` exists — and why you'd pick it over plain `@mcp.tool(app=True)` with string-based `CallTool` — is composition safety.
+
+When you mount a server under a namespace, tool names get prefixed:
+
+```python
+platform = FastMCP("Platform")
+platform.mount("contacts", contacts_server)
+
+# "save_contact" becomes "contacts_save_contact"
+```
+
+`CallTool("save_contact")` would now be broken. But `CallTool(save_contact)` with a function reference resolves to a globally stable identifier that bypasses the namespace. Your app works the same whether standalone or mounted.
+
+### Mounting
+
+`FastMCPApp` is a Provider. Add it to a server with `providers=` or `add_provider`:
+
+```python
+mcp = FastMCP("Platform", providers=[app])
+
+# or
+mcp = FastMCP("Platform")
+mcp.add_provider(app)
+```
+
+Multiple apps can coexist; each gets its own global keys, so there's no collision even if two apps have a tool named `save`.
+
+```python
+mcp = FastMCP("Platform", providers=[contacts_app, inventory_app, billing_app])
+```
+
+### Running standalone
+
+For development, `FastMCPApp` has a `run()` shortcut that wraps itself in a temporary `FastMCP` server:
+
+```python
+app = FastMCPApp("Contacts")
+# ... register tools ...
+
+if __name__ == "__main__":
+    app.run()
+```
+
+## A full example: contact manager
+
+This brings everything together — entry point, backend tools, Pydantic form, manual form, state, actions, and multi-visibility.
+
+```python expandable
+from __future__ import annotations
+
+from typing import Literal
+
+from prefab_ui.actions import SetState, ShowToast
+from prefab_ui.actions.mcp import CallTool
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import (
+    Badge, Button, Column, ForEach, Form,
+    Heading, Input, Muted, Row, Separator, Text,
+)
+from prefab_ui.rx import RESULT, Rx
+from pydantic import BaseModel, Field
+from fastmcp import FastMCP, FastMCPApp
+
+contacts_db: list[dict] = [
+    {"name": "Arthur Dent", "email": "arthur@earth.com", "category": "Customer"},
+    {"name": "Ford Prefect", "email": "ford@betelgeuse.org", "category": "Partner"},
+]
+
+
+class ContactModel(BaseModel):
+    name: str = Field(title="Full Name", min_length=1)
+    email: str = Field(title="Email")
+    category: Literal["Customer", "Vendor", "Partner", "Other"] = "Other"
+
+
+app = FastMCPApp("Contacts")
+
+
+@app.tool()
+def save_contact(data: ContactModel) -> list[dict]:
+    """Save a new contact and return the updated list."""
+    contacts_db.append(data.model_dump())
+    return list(contacts_db)
+
+
+@app.tool()
+def search_contacts(query: str) -> list[dict]:
+    """Filter contacts by name or email."""
+    q = query.lower()
+    return [
+        c for c in contacts_db
+        if q in c["name"].lower() or q in c["email"].lower()
+    ]
+
+
+@app.tool(model=True)
+def list_contacts() -> list[dict]:
+    """Return all contacts. Visible to both the model and the UI."""
+    return list(contacts_db)
+
+
+@app.ui()
+def contact_manager() -> PrefabApp:
+    """Open the contact manager."""
+    with Column(gap=6, css_class="p-6") as view:
+        Heading("Contacts")
+
+        with ForEach("contacts") as contact:
+            with Row(gap=2, align="center"):
+                Text(contact.name, css_class="font-medium")
+                Muted(contact.email)
+                Badge(contact.category)
+
+        Separator()
+
+        Heading("Add Contact", level=3)
+        Form.from_model(
+            ContactModel,
+            on_submit=CallTool(
+                "save_contact",
+                on_success=[
+                    SetState("contacts", RESULT),
+                    ShowToast("Contact saved!", variant="success"),
+                ],
+                on_error=ShowToast("Failed to save", variant="error"),
+            ),
+        )
+
+        Separator()
+
+        Heading("Search", level=3)
+        with Form(
+            on_submit=CallTool(
+                "search_contacts",
+                arguments={"query": Rx("query")},
+                on_success=SetState("contacts", RESULT),
+            )
+        ):
+            Input(name="query", placeholder="Search by name or email...")
+            Button("Search")
+
+    return PrefabApp(view=view, state={"contacts": list(contacts_db)})
+
+
+mcp = FastMCP("Contacts Server", providers=[app])
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+Also available as a runnable server at `examples/apps/contacts/contacts_server.py`.
+
+## Next steps
+
+- **[Interactive Tools](/apps/prefab)** — the building blocks: charts, tables, dashboards, reactive state
+- **[Examples](/apps/examples)** — complete working servers
+- **[Development](/apps/development)** — preview and test app tools locally
+- **[Prefab UI docs](https://prefab.prefect.io)** — full component reference
diff --git a/docs/apps/generative.mdx b/docs/apps/generative.mdx
new file mode 100644
index 0000000..b6293d3
--- /dev/null
+++ b/docs/apps/generative.mdx
@@ -0,0 +1,134 @@
+---
+title: Generative UI
+sidebarTitle: Generative UI
+description: Let the LLM build custom Prefab UIs on the fly.
+icon: wand-magic-sparkles
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.2.0" />
+
+<video src="/apps/images/generative-ui.mp4" autoPlay loop muted playsInline style={{width:"100%", borderRadius:"8px", marginBottom:"1rem"}} />
+
+With Generative UI, the LLM writes the UI code at runtime. Instead of calling a pre-built tool with a fixed shape, the model writes Prefab Python tailored to the current data and request. The user watches the UI stream in as the model generates it.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.apps.generative import GenerativeUI
+
+mcp = FastMCP("Prefab Studio")
+mcp.add_provider(GenerativeUI())
+```
+
+One provider registers three things:
+
+- **`generate_prefab_ui`** — a tool that accepts Python code, executes it in a Pyodide sandbox, and renders the result as a Prefab app
+- **`search_prefab_components`** — a tool the LLM uses to discover what components are available
+- **The streaming renderer** — a `ui://` resource with browser-side Pyodide that progressively renders partial code as the LLM generates it
+
+## How it works
+
+When the LLM calls `generate_prefab_ui`, it writes Prefab Python code into the `code` argument. The MCP Apps protocol creates the renderer iframe in parallel with the tool call, so the app is already running by the time partial arguments start flowing.
+
+As the LLM generates each token:
+
+1. The host forwards partial arguments to the app via `ontoolinputpartial`
+2. The renderer extracts the growing `code` string
+3. Browser-side Pyodide executes whatever compiles successfully
+4. The user sees components appear as they're written
+
+When the LLM finishes, the server runs the complete code in a server-side Pyodide sandbox for validation, and the renderer swaps the streaming preview for the final server-validated result.
+
+## What the LLM writes
+
+The tool description includes examples that teach the model the Prefab patterns. A typical generation looks like:
+
+```python
+from prefab_ui.components import Column, Row, Heading, Text, Badge, Card, CardContent
+from prefab_ui.components.charts import BarChart, ChartSeries
+from prefab_ui.app import PrefabApp
+
+with PrefabApp() as app:
+    with Column(gap=6, css_class="p-6"):
+        Heading("Q3 Revenue Report")
+
+        BarChart(
+            data=[
+                {"month": "Jul", "revenue": 42000},
+                {"month": "Aug", "revenue": 51000},
+                {"month": "Sep", "revenue": 63000},
+            ],
+            series=[ChartSeries(data_key="revenue", label="Revenue")],
+            x_axis="month",
+        )
+
+        with Row(gap=4):
+            with Card():
+                with CardContent():
+                    Text("Total", css_class="text-sm text-muted-foreground")
+                    Heading("$156,000")
+            with Card():
+                with CardContent():
+                    Text("Growth", css_class="text-sm text-muted-foreground")
+                    Badge("+18%", variant="success")
+```
+
+The model writes real Python — loops, f-strings, computation, helper functions. Prefab gives it charts, tables, forms, cards, badges, and layout primitives to compose.
+
+## The component search tool
+
+Before writing code, the LLM can call `search_prefab_components` to discover what's available:
+
+```
+search_prefab_components("Chart")
+→ 7 components matching 'Chart':
+  AreaChart — from prefab_ui.components.charts import AreaChart
+  BarChart — from prefab_ui.components.charts import BarChart
+  ...
+```
+
+Passing `detail=True` returns full field descriptions and docstrings. The search tool introspects Prefab classes at runtime, so it's always up to date with the installed version.
+
+## Passing data
+
+The `generate_prefab_ui` tool accepts a `data` parameter. Values become global variables in the sandbox:
+
+```python
+# The LLM can reference 'sales_data' directly in its code
+result = await generate_prefab_ui(
+    code="...",
+    data={"sales_data": [{"month": "Jan", "revenue": 42000}, ...]}
+)
+```
+
+This lets the model use data from earlier in the conversation to build visualizations.
+
+## Configuration
+
+`GenerativeUI` takes options for customizing tool names:
+
+```python
+GenerativeUI(
+    tool_name="generate_prefab_ui",           # default
+    components_tool_name="search_prefab_components",  # default
+    include_components_tool=True,              # default
+)
+```
+
+## Requirements
+
+Generative UI needs `fastmcp[apps]`, which pulls in `prefab-ui`. The server-side Pyodide sandbox (for final validation) requires Deno — it installs automatically on first use.
+
+The streaming renderer loads Pyodide from CDN in the browser. The CSP is configured automatically by the provider — no manual setup.
+
+## Sandbox limitations
+
+The Pyodide sandbox includes the Python standard library and Prefab. External packages (NumPy, pandas, requests, etc.) are **not available** — the LLM's code must work with only built-in Python and Prefab. If the LLM imports something unavailable, the sandbox raises `ImportError`.
+
+## Next steps
+
+- **[Interactive Tools](/apps/prefab)** — the component building blocks the LLM will use
+- **[Prefab component reference](https://prefab.prefect.io/docs/components)** — full component library
+- **[Development](/apps/development)** — preview generative tools locally with `fastmcp dev apps`
diff --git a/docs/apps/images/app-approval.png b/docs/apps/images/app-approval.png
new file mode 100644
index 0000000..162f484
Binary files /dev/null and b/docs/apps/images/app-approval.png differ
diff --git a/docs/apps/images/app-chart.png b/docs/apps/images/app-chart.png
new file mode 100644
index 0000000..cfc816d
Binary files /dev/null and b/docs/apps/images/app-chart.png differ
diff --git a/docs/apps/images/app-choice.png b/docs/apps/images/app-choice.png
new file mode 100644
index 0000000..178f6a2
Binary files /dev/null and b/docs/apps/images/app-choice.png differ
diff --git a/docs/apps/images/app-contacts.png b/docs/apps/images/app-contacts.png
new file mode 100644
index 0000000..5d74f7c
Binary files /dev/null and b/docs/apps/images/app-contacts.png differ
diff --git a/docs/apps/images/app-datatable.png b/docs/apps/images/app-datatable.png
new file mode 100644
index 0000000..e69de29
diff --git a/docs/apps/images/app-example-map.png b/docs/apps/images/app-example-map.png
new file mode 100644
index 0000000..5859c59
Binary files /dev/null and b/docs/apps/images/app-example-map.png differ
diff --git a/docs/apps/images/app-example-quiz.png b/docs/apps/images/app-example-quiz.png
new file mode 100644
index 0000000..b16bcaf
Binary files /dev/null and b/docs/apps/images/app-example-quiz.png differ
diff --git a/docs/apps/images/app-example-sales-dashboard.png b/docs/apps/images/app-example-sales-dashboard.png
new file mode 100644
index 0000000..e0fe709
Binary files /dev/null and b/docs/apps/images/app-example-sales-dashboard.png differ
diff --git a/docs/apps/images/app-example-system-dashboard.png b/docs/apps/images/app-example-system-dashboard.png
new file mode 100644
index 0000000..7b85d7a
Binary files /dev/null and b/docs/apps/images/app-example-system-dashboard.png differ
diff --git a/docs/apps/images/app-file-upload.png b/docs/apps/images/app-file-upload.png
new file mode 100644
index 0000000..1178c09
Binary files /dev/null and b/docs/apps/images/app-file-upload.png differ
diff --git a/docs/apps/images/app-form.png b/docs/apps/images/app-form.png
new file mode 100644
index 0000000..30567e3
Binary files /dev/null and b/docs/apps/images/app-form.png differ
diff --git a/docs/apps/images/app-greet.png b/docs/apps/images/app-greet.png
new file mode 100644
index 0000000..70a0e44
Binary files /dev/null and b/docs/apps/images/app-greet.png differ
diff --git a/docs/apps/images/app-overview.png b/docs/apps/images/app-overview.png
new file mode 100644
index 0000000..35f68fd
Binary files /dev/null and b/docs/apps/images/app-overview.png differ
diff --git a/docs/apps/images/app-quickstart-dev-2.png b/docs/apps/images/app-quickstart-dev-2.png
new file mode 100644
index 0000000..f04d96d
Binary files /dev/null and b/docs/apps/images/app-quickstart-dev-2.png differ
diff --git a/docs/apps/images/app-quickstart-dev.png b/docs/apps/images/app-quickstart-dev.png
new file mode 100644
index 0000000..d043f0e
Binary files /dev/null and b/docs/apps/images/app-quickstart-dev.png differ
diff --git a/docs/apps/images/app-quickstart.png b/docs/apps/images/app-quickstart.png
new file mode 100644
index 0000000..ddca745
Binary files /dev/null and b/docs/apps/images/app-quickstart.png differ
diff --git a/docs/apps/images/app-showcase.png b/docs/apps/images/app-showcase.png
new file mode 100644
index 0000000..c03294b
Binary files /dev/null and b/docs/apps/images/app-showcase.png differ
diff --git a/docs/apps/images/dev-app.png b/docs/apps/images/dev-app.png
new file mode 100644
index 0000000..fdb05d6
Binary files /dev/null and b/docs/apps/images/dev-app.png differ
diff --git a/docs/apps/images/generative-ui.mp4 b/docs/apps/images/generative-ui.mp4
new file mode 100644
index 0000000..ca61018
Binary files /dev/null and b/docs/apps/images/generative-ui.mp4 differ
diff --git a/docs/apps/low-level.mdx b/docs/apps/low-level.mdx
new file mode 100644
index 0000000..01eca73
--- /dev/null
+++ b/docs/apps/low-level.mdx
@@ -0,0 +1,304 @@
+---
+title: Custom HTML Apps
+sidebarTitle: Custom HTML
+description: Build apps with your own HTML, CSS, and JavaScript using the MCP Apps extension directly.
+icon: code
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+Everything on this page is for when you want full control: your own HTML, your own JavaScript framework, a map library, a 3D viewer, custom video playback. [Interactive Tools](/apps/prefab) wrap the MCP Apps extension so you never have to think about it — this page is what you reach for when you need to think about it.
+
+You'll be working with two things: the [`@modelcontextprotocol/ext-apps`](https://github.com/modelcontextprotocol/ext-apps) JavaScript SDK for host communication, and FastMCP's `AppConfig` for resources and CSP.
+
+## How it works
+
+An MCP App has two parts:
+
+1. A **tool** that does the work and returns data
+2. A **`ui://` resource** containing the HTML that renders that data
+
+The tool declares which resource to use via `AppConfig`. When the host calls the tool, it also fetches the linked resource, renders it in a sandboxed iframe, and pushes the tool result into the app via `postMessage`. The app can also call tools back, enabling interactive workflows.
+
+```python
+import json
+
+from fastmcp import FastMCP
+from fastmcp.apps import AppConfig, ResourceCSP
+
+mcp = FastMCP("My App Server")
+
+# The tool does the work
+@mcp.tool(app=AppConfig(resource_uri="ui://my-app/view.html"))
+def generate_chart(data: list[float]) -> str:
+    return json.dumps({"values": data})
+
+# The resource provides the UI
+@mcp.resource("ui://my-app/view.html")
+def chart_view() -> str:
+    return "<html>...</html>"
+```
+
+## AppConfig
+
+`AppConfig` controls how a tool or resource participates in the Apps extension. Import it from `fastmcp.apps`:
+
+```python
+from fastmcp.apps import AppConfig
+```
+
+On **tools**, you'll typically set `resource_uri` to point to the UI resource:
+
+```python
+@mcp.tool(app=AppConfig(resource_uri="ui://my-app/view.html"))
+def my_tool() -> str:
+    return "result"
+```
+
+You can also pass a raw dict with camelCase keys, matching the wire format:
+
+```python
+@mcp.tool(app={"resourceUri": "ui://my-app/view.html"})
+def my_tool() -> str:
+    return "result"
+```
+
+### Tool visibility
+
+The `visibility` field controls where a tool appears:
+
+- `["model"]` — visible to the LLM (the default behavior)
+- `["app"]` — only callable from within the app UI, hidden from the LLM
+- `["model", "app"]` — both
+
+This is useful when you have tools that only make sense as part of the app's interactive flow, not as standalone LLM actions.
+
+```python
+@mcp.tool(
+    app=AppConfig(
+        resource_uri="ui://my-app/view.html",
+        visibility=["app"],
+    )
+)
+def refresh_data() -> str:
+    """Only callable from the app UI, not by the LLM."""
+    return fetch_latest()
+```
+
+### AppConfig fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `resource_uri` | `str` | URI of the UI resource. Tools only. |
+| `visibility` | `list[str]` | Where the tool appears: `"model"`, `"app"`, or both. Tools only. |
+| `csp` | `ResourceCSP` | Content Security Policy for the iframe. |
+| `permissions` | `ResourcePermissions` | Iframe sandbox permissions. |
+| `domain` | `str` | Stable sandbox origin for the iframe. |
+| `prefers_border` | `bool` | Whether the UI prefers a visible border. |
+
+<Note>
+On **resources**, `resource_uri` and `visibility` must not be set — the resource *is* the UI. Use `AppConfig` on resources only for `csp`, `permissions`, and other display settings.
+</Note>
+
+## UI resources
+
+Resources using the `ui://` scheme are automatically served with the MIME type `text/html;profile=mcp-app`. No need to set it manually.
+
+```python
+@mcp.resource("ui://my-app/view.html")
+def my_view() -> str:
+    return "<html>...</html>"
+```
+
+The HTML can be anything — a full single-page app, a simple display, or a complex interactive tool. The host renders it in a sandboxed iframe and establishes a `postMessage` channel for communication.
+
+### Writing the app HTML
+
+Your HTML app communicates with the host using the [`@modelcontextprotocol/ext-apps`](https://github.com/modelcontextprotocol/ext-apps) JavaScript SDK. The simplest approach is to load it from a CDN:
+
+```html
+<script type="module">
+  import { App } from "https://unpkg.com/@modelcontextprotocol/ext-apps@0.4.0/app-with-deps";
+
+  const app = new App({ name: "My App", version: "1.0.0" });
+
+  // Receive tool results pushed by the host
+  app.ontoolresult = ({ content }) => {
+    const text = content?.find(c => c.type === 'text');
+    if (text) {
+      document.getElementById('output').textContent = text.text;
+    }
+  };
+
+  // Connect to the host
+  await app.connect();
+</script>
+```
+
+The `App` object provides:
+
+- **`app.ontoolresult`** — callback that receives tool results pushed by the host
+- **`app.callServerTool({name, arguments})`** — call a tool on the server from within the app
+- **`app.onhostcontextchanged`** — callback for host context changes (e.g., safe area insets)
+- **`app.getHostContext()`** — get current host context
+
+See the full [ext-apps SDK documentation](https://github.com/modelcontextprotocol/ext-apps) for the complete API reference.
+
+<Note>
+If your HTML loads external scripts, styles, or makes API calls, you need to declare those domains in the CSP configuration. See [Security](#security) below.
+</Note>
+
+## Security
+
+Apps run in sandboxed iframes with a deny-by-default Content Security Policy. By default, only inline scripts and styles are allowed — no external network access.
+
+### Content Security Policy
+
+If your app needs to load external resources (CDN scripts, API calls, embedded iframes), declare the allowed domains with `ResourceCSP`:
+
+```python
+from fastmcp.apps import AppConfig, ResourceCSP
+
+@mcp.resource(
+    "ui://my-app/view.html",
+    app=AppConfig(
+        csp=ResourceCSP(
+            resource_domains=["https://unpkg.com", "https://cdn.example.com"],
+            connect_domains=["https://api.example.com"],
+        )
+    ),
+)
+def my_view() -> str:
+    return "<html>...</html>"
+```
+
+| CSP Field | Controls |
+|-----------|----------|
+| `connect_domains` | `fetch`, XHR, WebSocket (`connect-src`) |
+| `resource_domains` | Scripts, images, styles, fonts (`script-src`, etc.) |
+| `frame_domains` | Nested iframes (`frame-src`) |
+| `base_uri_domains` | Document base URI (`base-uri`) |
+
+### Permissions
+
+If your app needs browser capabilities like camera or clipboard access, request them via `ResourcePermissions`:
+
+```python
+from fastmcp.apps import AppConfig, ResourcePermissions
+
+@mcp.resource(
+    "ui://my-app/view.html",
+    app=AppConfig(
+        permissions=ResourcePermissions(
+            camera={},
+            clipboard_write={},
+        )
+    ),
+)
+def my_view() -> str:
+    return "<html>...</html>"
+```
+
+Hosts may or may not grant these permissions. Your app should use JavaScript feature detection as a fallback.
+
+## Example: a QR code server
+
+This example creates a tool that generates QR codes and an app that renders them as images. It's based on the [official MCP Apps example](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/qr-server). Requires the `qrcode[pil]` package.
+
+```python expandable
+import base64
+import io
+
+import qrcode
+
+from fastmcp import FastMCP
+from fastmcp.apps import AppConfig, ResourceCSP
+from fastmcp.tools import ToolResult
+from fastmcp.types import ImageContent
+
+mcp = FastMCP("QR Code Server")
+
+VIEW_URI = "ui://qr-server/view.html"
+
+
+@mcp.tool(app=AppConfig(resource_uri=VIEW_URI))
+def generate_qr(text: str = "https://gofastmcp.com") -> ToolResult:
+    """Generate a QR code from text."""
+    qr = qrcode.QRCode(version=1, box_size=10, border=4)
+    qr.add_data(text)
+    qr.make(fit=True)
+
+    img = qr.make_image()
+    buffer = io.BytesIO()
+    img.save(buffer, format="PNG")
+    b64 = base64.b64encode(buffer.getvalue()).decode()
+
+    return ToolResult(
+        content=[ImageContent(type="image", data=b64, mime_type="image/png")]
+    )
+
+
+@mcp.resource(
+    VIEW_URI,
+    app=AppConfig(csp=ResourceCSP(resource_domains=["https://unpkg.com"])),
+)
+def view() -> str:
+    """Interactive QR code viewer."""
+    return """\
+<!DOCTYPE html>
+<html>
+<head>
+  <meta name="color-scheme" content="light dark">
+  <style>
+    body { display: flex; justify-content: center;
+           align-items: center; height: 340px; width: 340px;
+           margin: 0; background: transparent; }
+    img  { width: 300px; height: 300px; border-radius: 8px;
+           box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
+  </style>
+</head>
+<body>
+  <div id="qr"></div>
+  <script type="module">
+    import { App } from
+      "https://unpkg.com/@modelcontextprotocol/ext-apps@0.4.0/app-with-deps";
+
+    const app = new App({ name: "QR View", version: "1.0.0" });
+
+    app.ontoolresult = ({ content }) => {
+      const img = content?.find(c => c.type === 'image');
+      if (img) {
+        const el = document.createElement('img');
+        el.src = `data:${img.mimeType};base64,${img.data}`;
+        el.alt = "QR Code";
+        document.getElementById('qr').replaceChildren(el);
+      }
+    };
+
+    await app.connect();
+  </script>
+</body>
+</html>"""
+```
+
+The tool generates a QR code as a base64 PNG. The resource loads the MCP Apps JS SDK from unpkg (declared in the CSP), listens for tool results, and renders the image. The host wires them together — when the LLM calls `generate_qr`, the QR code appears in an interactive frame inside the conversation.
+
+## Checking client support
+
+Not all hosts support the Apps extension. You can check at runtime using the tool's [context](/servers/context):
+
+```python
+from fastmcp import Context
+from fastmcp.apps import AppConfig, UI_EXTENSION_ID
+
+@mcp.tool(app=AppConfig(resource_uri="ui://my-app/view.html"))
+async def my_tool(ctx: Context) -> str:
+    if ctx.client_supports_extension(UI_EXTENSION_ID):
+        # Return data optimized for UI rendering
+        return rich_response()
+    else:
+        # Fall back to plain text
+        return plain_text_response()
+```
diff --git a/docs/apps/overview.mdx b/docs/apps/overview.mdx
new file mode 100644
index 0000000..ff95570
--- /dev/null
+++ b/docs/apps/overview.mdx
@@ -0,0 +1,73 @@
+---
+title: Apps
+sidebarTitle: Overview
+description: Give your tools interactive UIs rendered directly in the conversation.
+icon: grid-2
+mode: center
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+import PrefabPinWarning from '/snippets/prefab-pin-warning.mdx'
+import { PrefabDemoFrame } from '/snippets/prefab-demo-frame.mdx'
+
+<VersionBadge version="3.0.0" />
+
+A FastMCP app is a tool that returns an interactive UI instead of text. When the host calls it, the user sees a chart, a table, a form, or a whole dashboard rendered right inside the conversation, with working sort, search, tooltips, and state.
+
+<div style={{
+  margin: '0 clamp(-180px, calc(-18vw + 90px), 0px) 2rem',
+  maxHeight: '700px',
+  overflow: 'hidden',
+  position: 'relative',
+  maskImage: 'linear-gradient(to bottom, black 75%, transparent)',
+  WebkitMaskImage: 'linear-gradient(to bottom, black 75%, transparent)',
+}}>
+  <PrefabDemoFrame demo="hitchhikers" height="2000px" title="Prefab showcase demo" />
+</div>
+
+The dashboard above is a [Prefab](https://prefab.prefect.io) showcase — a taste of what you can deliver from a FastMCP tool. Every card, chart, slider, dialog, and carousel is a Python component. Build a composition like this, add `@mcp.tool(app=True)`, and the host renders it inside the conversation.
+
+Under the hood, FastMCP builds on the [MCP Apps extension](https://modelcontextprotocol.io/docs/extensions/apps) and uses Prefab to describe UIs in Python.
+
+```bash
+pip install "fastmcp[apps]"
+```
+
+<PrefabPinWarning />
+
+## Pick your path
+
+Four patterns cover almost everything you'd want to build. Most apps start with Interactive Tools; you only reach for the others when you've hit a specific limit.
+
+### [Interactive Tools](/apps/prefab) — start here
+
+Add `app=True` to a tool and return a Prefab component. Charts, tables, dashboards, and client-side interactivity (toggles, tabs, filtering) all work without any server round-trips.
+
+```python
+@mcp.tool(app=True)
+def team_directory() -> DataTable:
+    return DataTable(columns=[...], rows=employees, search=True)
+```
+
+### [FastMCPApp](/apps/fastmcp-app) — when the UI calls back to the server
+
+Forms that save data, buttons that trigger backend work, search that hits a database. `FastMCPApp` manages the wiring between UI actions and backend tools, with stable tool identifiers that survive server composition.
+
+### [Generative UI](/apps/generative) — when the LLM writes the UI
+
+Register one provider and the model can write Prefab code tailored to the current data and request. The user watches the UI build up as the model generates it.
+
+```python
+mcp.add_provider(GenerativeUI())
+```
+
+### [Custom HTML](/apps/low-level) — when you need full control
+
+Write your own HTML, CSS, and JavaScript. Use a specific framework, drop in a map or 3D viewer, embed video. You're talking to the MCP Apps protocol directly.
+
+## What's next
+
+- **[Quickstart](/apps/quickstart)** — build a working app in a minute
+- **[Examples](/apps/examples)** — complete working servers you can run today
+- **[Providers](/apps/providers/approval)** — ready-made capabilities (approvals, choice pickers, file upload, forms) you add with one line
+- **[Development](/apps/development)** — preview app tools locally with `fastmcp dev apps`
diff --git a/docs/apps/prefab.mdx b/docs/apps/prefab.mdx
new file mode 100644
index 0000000..e6ff707
--- /dev/null
+++ b/docs/apps/prefab.mdx
@@ -0,0 +1,297 @@
+---
+title: Interactive Tools
+sidebarTitle: Interactive Tools
+description: Turn your tools into interactive UIs with charts, tables, and dashboards.
+icon: palette
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+import PrefabPinWarning from '/snippets/prefab-pin-warning.mdx'
+import { PrefabDemoFrame } from '/snippets/prefab-demo-frame.mdx'
+
+<VersionBadge version="3.1.0" />
+
+<PrefabPinWarning />
+
+<PrefabDemoFrame demo="dashboard" height="680px" title="Sales dashboard demo" />
+
+Believe it or not, that dashboard is a FastMCP tool. The chart has tooltips. The table is sortable. The badges are styled by deal stage. The whole thing is about 40 lines of Python, and the user sees it right inside their conversation instead of a wall of JSON.
+
+The pattern behind every example on this page is the same: add `app=True` to your tool, build a UI with [Prefab](https://prefab.prefect.io) components, and return it as a `PrefabApp`. Prefab has [100+ components](https://prefab.prefect.io/docs/components), from data tables and charts to forms and progress bars. You compose them in Python; the host renders them as a live, interactive application.
+
+## Start with a table
+
+Most tools return data the user wants to explore. A `DataTable` is often the smallest useful upgrade — your data goes from a JSON blob to a searchable, sortable table:
+
+<PrefabDemoFrame demo="data-table" height="530px" title="Data table demo" />
+
+```python
+from prefab_ui.components import DataTable, DataTableColumn
+from fastmcp import FastMCP
+
+mcp = FastMCP("Directory")
+
+
+@mcp.tool(app=True)
+def team_directory() -> DataTable:
+    """Browse the team directory."""
+    employees = [
+        {"name": "Alice Chen", "role": "Staff Engineer", "dept": "Platform"},
+        {"name": "Bob Martinez", "role": "Lead Designer", "dept": "Design"},
+        {"name": "Carol Johnson", "role": "Senior Engineer", "dept": "Platform"},
+        {"name": "David Kim", "role": "Product Manager", "dept": "Product"},
+        {"name": "Eva Mueller", "role": "Engineer", "dept": "Platform"},
+        {"name": "Frank Lee", "role": "Data Scientist", "dept": "ML"},
+        {"name": "Grace Park", "role": "Eng Manager", "dept": "Platform"},
+    ]
+
+    return DataTable(
+        columns=[
+            DataTableColumn(key="name", header="Name", sortable=True),
+            DataTableColumn(key="role", header="Role", sortable=True),
+            DataTableColumn(key="dept", header="Dept", sortable=True),
+        ],
+        rows=employees,
+        search=True,
+    )
+```
+
+That's it. Add `app=True`, return a Prefab component instead of raw dicts. FastMCP handles the rendering, sandboxing, and security. No wrapper class needed for simple cases like this.
+
+## Add charts
+
+When numbers tell a better story as a visual, swap in a chart. The API is the same: pass your data as a list of dicts, tell the chart which keys to plot.
+
+<PrefabDemoFrame demo="bar-chart" height="430px" title="Bar chart demo" />
+
+```python
+@mcp.tool(app=True)
+def quarterly_revenue(year: int) -> BarChart:
+    """Show quarterly revenue as a bar chart."""
+    data = [
+        {"quarter": "Q1", "revenue": 42000, "costs": 28000},
+        {"quarter": "Q2", "revenue": 51000, "costs": 31000},
+        {"quarter": "Q3", "revenue": 47000, "costs": 29000},
+        {"quarter": "Q4", "revenue": 63000, "costs": 35000},
+    ]
+
+    return BarChart(
+        data=data,
+        series=[
+            ChartSeries(data_key="revenue", label="Revenue"),
+            ChartSeries(data_key="costs", label="Costs"),
+        ],
+        x_axis="quarter",
+        show_legend=True,
+    )
+```
+
+Each `ChartSeries` plots a different key from the data. `BarChart`, `LineChart`, `AreaChart`, `PieChart`, `RadarChart`, and `RadialChart` all follow the same pattern. Hover over the bars to see tooltips.
+
+<PrefabDemoFrame demo="pie-chart" height="410px" title="Pie chart demo" />
+
+```python
+@mcp.tool(app=True)
+def ticket_breakdown() -> PieChart:
+    """Show open tickets by category."""
+    data = [
+        {"category": "Bug", "count": 42},
+        {"category": "Feature", "count": 28},
+        {"category": "Docs", "count": 15},
+        {"category": "Infra", "count": 10},
+    ]
+
+    return PieChart(
+        data=data,
+        data_key="count",
+        name_key="category",
+        inner_radius=50,
+        show_legend=True,
+    )
+```
+
+See the [Prefab chart docs](https://prefab.prefect.io/docs/components) for stacking, curves, custom colors, and more.
+
+## Compose a dashboard
+
+Tables and charts are useful on their own, but the real power comes from composing them. `Column` stacks children vertically, `Row` lays them out side by side, and `with` blocks establish nesting — the indentation is the layout.
+
+<PrefabDemoFrame demo="dashboard" height="680px" title="Sales dashboard demo" />
+
+```python expandable
+@mcp.tool(app=True)
+def sales_dashboard() -> PrefabApp:
+    """Show sales KPIs, trends, and deals."""
+    monthly = [
+        {"month": "Jan", "revenue": 48200, "costs": 31000},
+        {"month": "Feb", "revenue": 52100, "costs": 32500},
+        {"month": "Mar", "revenue": 61800, "costs": 34200},
+        {"month": "Apr", "revenue": 58400, "costs": 33800},
+    ]
+    deals = [
+        {"account": "Acme Corp", "value": "$84,000", "stage": "Won"},
+        {"account": "Globex Inc", "value": "$52,000", "stage": "Negotiation"},
+        {"account": "Initech", "value": "$31,500", "stage": "Proposal"},
+        {"account": "Wayne Enterprises", "value": "$45,000", "stage": "Lost"},
+    ]
+
+    rows = [
+        {
+            "account": d["account"],
+            "value": d["value"],
+            "stage": Badge(
+                d["stage"],
+                variant="success" if d["stage"] == "Won"
+                else "destructive" if d["stage"] == "Lost"
+                else "secondary",
+            ),
+        }
+        for d in deals
+    ]
+
+    total = sum(m["revenue"] for m in monthly)
+
+    with PrefabApp() as app:
+        with Column(gap=4, css_class="p-6"):
+            with Row(gap=6):
+                Metric(label="Revenue (Q1-Q4)", value=f"${total:,}")
+                Metric(label="Deals", value=f"{len(deals)}")
+            BarChart(
+                data=monthly,
+                series=[
+                    ChartSeries(data_key="revenue", label="Revenue"),
+                    ChartSeries(data_key="costs", label="Costs"),
+                ],
+                x_axis="month",
+                show_legend=True,
+            )
+            Separator()
+            DataTable(
+                columns=[
+                    DataTableColumn(key="account", header="Account", sortable=True),
+                    DataTableColumn(key="value", header="Value", sortable=True),
+                    DataTableColumn(key="stage", header="Stage"),
+                ],
+                rows=rows,
+            )
+
+    return app
+```
+
+Notice how `Badge` components can be placed inside table cells — any Prefab component works as a cell value, so you can put progress bars, icons, or buttons in your tables too.
+
+## Make it reactive
+
+Everything above renders once from the data your Python provides. But interactive tools can also respond to user input in real time, without any server round-trips. Prefab's state system lets components read and write client-side values, so the UI updates instantly as the user interacts with it.
+
+<PrefabDemoFrame demo="reactive" height="500px" title="Reactive sales demo" />
+
+Try switching regions in the dropdown, and toggling the switch on and off.
+
+```python expandable
+from prefab_ui.rx import Rx
+
+@mcp.tool(app=True)
+def regional_sales() -> PrefabApp:
+    """Sales by region with a live filter."""
+    north = [
+        {"month": "Jan", "sales": 22000},
+        {"month": "Feb", "sales": 25500},
+        {"month": "Mar", "sales": 24200},
+    ]
+    south = [
+        {"month": "Jan", "sales": 5800},
+        {"month": "Feb", "sales": 6400},
+        {"month": "Mar", "sales": 5600},
+    ]
+    west = [
+        {"month": "Jan", "sales": 6000},
+        {"month": "Feb", "sales": 6000},
+        {"month": "Mar", "sales": 5600},
+    ]
+
+    with PrefabApp(
+        state={
+            "region": "north",
+            "north": north, "south": south, "west": west,
+            "show_target": True,
+        },
+    ) as app:
+        with Column(
+            gap=4,
+            css_class="p-6",
+            let={"data": "{{ region == 'south' ? south"
+                         " : region == 'west' ? west"
+                         " : north }}"},
+        ):
+            with Row(gap=4, align="center"):
+                with Select(name="region", css_class="w-40"):
+                    SelectOption(value="north", label="North")
+                    SelectOption(value="south", label="South")
+                    SelectOption(value="west", label="West")
+                Switch(name="show_target", css_class="ml-auto")
+                Text("Show target", css_class="text-sm text-muted-foreground")
+            BarChart(
+                data=Rx("data"),
+                series=[ChartSeries(data_key="sales", label="Sales")],
+                x_axis="month",
+            )
+            with If(Rx("show_target")):
+                Metric(label="Q1 Target", value="$75,000")
+
+    return app
+```
+
+The `state` dict on `PrefabApp` declares initial values. The `Select` writes to the `region` key on every change. A `let` binding picks the matching dataset, and the chart re-renders. The `Switch` toggles a `Metric` on and off through `If(Rx("show_target"))`. All of this happens in the browser — no calls back to your server.
+
+`Rx` is a reactive reference: `Rx("region")` compiles to an expression the renderer evaluates live. It supports arithmetic, comparisons, formatting pipes (`.currency()`, `.percent()`), and ternary conditionals (`.then()`). For the full state system, see the [Prefab state docs](https://prefab.prefect.io/docs/concepts/state) and [expression docs](https://prefab.prefect.io/docs/concepts/expressions).
+
+## Content Security Policy
+
+Interactive tools render in a sandboxed iframe with a strict CSP. If your tool loads external resources — embedding iframes, fetching from APIs, loading scripts — add the required domains:
+
+```python
+from fastmcp.apps import PrefabAppConfig, ResourceCSP
+
+@mcp.tool(app=PrefabAppConfig(
+    csp=ResourceCSP(frame_domains=["https://example.com"]),
+))
+def dashboard_with_embed() -> PrefabApp:
+    ...
+```
+
+`PrefabAppConfig()` with no arguments is equivalent to `app=True`.
+
+## Giving the LLM context
+
+By default, the LLM sees `"[Rendered Prefab UI]"` as the tool result. If the model needs to reason about the data, return a `ToolResult` with a text summary alongside the UI:
+
+```python
+from fastmcp.tools import ToolResult
+
+@mcp.tool(app=True)
+def sales_overview(year: int) -> ToolResult:
+    """Show sales visually, summarize for the model."""
+    data = get_sales_data(year)
+    total = sum(row["revenue"] for row in data)
+
+    with Column(gap=4, css_class="p-6") as view:
+        BarChart(data=data, series=[ChartSeries(data_key="revenue")])
+
+    return ToolResult(
+        content=f"Total revenue for {year}: ${total:,} across {len(data)} quarters",
+        structured_content=view,
+    )
+```
+
+The user sees the chart. The model sees the summary.
+
+## Next steps
+
+- **[FastMCPApp](/apps/fastmcp-app)** — when your UI needs to call backend tools (forms, search, CRUD)
+- **[Generative UI](/apps/generative)** — let the LLM design the UI at runtime
+- **[Custom HTML](/apps/low-level)** — when Prefab isn't enough (maps, 3D, your own framework)
+- **[Examples](/apps/examples)** — complete working servers you can run today
+- **[Development](/apps/development)** — preview your tools locally with `fastmcp dev apps`
+- **[Prefab UI](https://prefab.prefect.io)** — full component reference with 100+ components, theming, and advanced patterns
diff --git a/docs/apps/providers/approval.mdx b/docs/apps/providers/approval.mdx
new file mode 100644
index 0000000..8ac7b8d
--- /dev/null
+++ b/docs/apps/providers/approval.mdx
@@ -0,0 +1,80 @@
+---
+title: Approval
+sidebarTitle: Approval
+description: Human-in-the-loop approval gates for agent actions
+icon: shield-check
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.2.0" />
+
+`Approval` adds a human-in-the-loop confirmation step to any server. The LLM presents what it's about to do, the user approves or rejects via buttons, and the decision flows back into the conversation as a message.
+
+<Frame>
+  <img src="/apps/images/app-approval.png" alt="The Approval provider shown in Goose, with a payment confirmation card and Approve/Cancel buttons" />
+</Frame>
+
+```python
+from fastmcp import FastMCP
+from fastmcp.apps.approval import Approval
+
+mcp = FastMCP("My Server")
+mcp.add_provider(Approval())
+```
+
+This registers a single tool:
+
+| Tool | Visibility | Purpose |
+|------|-----------|---------|
+| `request_approval` | Model | Shows an approval card, sends the user's decision back as a message |
+
+The LLM calls `request_approval` with a summary (and optional details) whenever it's about to take a significant action. The user sees a card with Approve and Reject buttons. Clicking either sends a message back into the conversation via `SendMessage`, which triggers the LLM's next turn.
+
+The message looks like it came from the user:
+
+```
+"Deploy v3.2 to production" — I selected: Approve
+```
+
+<Note>
+Approval is an advisory gate, not an enforcement mechanism. The conversation isn't blocked while the card is open — the user can keep typing, and a determined LLM could proceed without waiting. Think of it as a strong UX signal that encourages confirmation, not a security boundary. For hard enforcement, implement approval logic server-side in your tool implementations.
+</Note>
+
+## Configuration
+
+The constructor sets defaults; the LLM can override all of these per-call via tool arguments.
+
+```python
+Approval(
+    name="Approval",              # App name
+    title="Approval Required",    # Card heading
+    approve_text="Approve",       # Approve button label
+    reject_text="Reject",         # Reject button label
+    approve_variant="default",    # "default", "destructive", "success", "info"
+    reject_variant="outline",     # same options plus "outline"
+)
+```
+
+The LLM can customize each invocation:
+
+```python
+request_approval(
+    summary="Delete 47 files from /tmp",
+    details="This cannot be undone.",
+    title="Destructive Action",
+    approve_text="Delete",
+    approve_variant="destructive",
+    reject_text="Keep files",
+)
+```
+
+## How it works
+
+When the user clicks a button, two things happen:
+
+1. `SendMessage` pushes the decision into the conversation as a user message
+2. `SetState("decided", True)` replaces the buttons with "Response sent."
+
+The tool description instructs the LLM to stop and wait for the "I selected:" message before proceeding. If approved, it continues. If rejected, it acknowledges and asks how to proceed.
diff --git a/docs/apps/providers/choice.mdx b/docs/apps/providers/choice.mdx
new file mode 100644
index 0000000..c29c1b2
--- /dev/null
+++ b/docs/apps/providers/choice.mdx
@@ -0,0 +1,72 @@
+---
+title: Choice
+sidebarTitle: Choice
+description: Present clickable options instead of free-text responses
+icon: list-check
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.2.0" />
+
+`Choice` lets the LLM present a set of options as clickable buttons instead of asking the user to type a response. The selection flows back into the conversation as a message, giving the LLM clean structured input.
+
+<Frame>
+  <img src="/apps/images/app-choice.png" alt="The Choice provider shown in Goose, with four lunch options as clickable buttons" />
+</Frame>
+
+```python
+from fastmcp import FastMCP
+from fastmcp.apps.choice import Choice
+
+mcp = FastMCP("My Server")
+mcp.add_provider(Choice())
+```
+
+This registers a single tool:
+
+| Tool | Visibility | Purpose |
+|------|-----------|---------|
+| `choose` | Model | Shows a card with clickable options, sends the selection back as a message |
+
+The LLM calls `choose` with a prompt and a list of options. The user sees a card with one button per option. Clicking one sends a message back into the conversation:
+
+```
+"Which deployment strategy?" — I selected: Blue-green
+```
+
+<Note>
+This is an advisory interaction, not an enforcement mechanism. The conversation isn't blocked while the card is open — the user can keep typing, and the LLM could proceed without waiting. The tool description instructs the LLM to stop and wait for the "I selected:" response, but for hard enforcement, implement selection logic server-side.
+</Note>
+
+## Configuration
+
+The constructor sets defaults; the LLM can override `title` per-call.
+
+```python
+Choice(
+    name="Choice",             # App name
+    title="Choose an Option",  # Default card heading
+    variant="outline",         # Button style for all options
+)
+```
+
+The LLM provides the options per-call:
+
+```python
+choose(
+    prompt="What should we have for lunch?",
+    options=["Pizza", "Tacos", "Ramen", "Salad"],
+    title="The Important Questions",
+)
+```
+
+## How it works
+
+Each option renders as a full-width button in a vertical stack. When the user clicks one:
+
+1. `SendMessage` pushes the selection into the conversation as a user message
+2. `SetState("decided", True)` replaces the buttons with "Response sent."
+
+The tool description instructs the LLM to stop and wait for the "I selected:" message before proceeding with whatever the user chose.
diff --git a/docs/apps/providers/file-upload.mdx b/docs/apps/providers/file-upload.mdx
new file mode 100644
index 0000000..b9709d9
--- /dev/null
+++ b/docs/apps/providers/file-upload.mdx
@@ -0,0 +1,129 @@
+---
+title: File Upload
+sidebarTitle: File Upload
+description: Drag-and-drop file upload for any MCP server
+icon: upload
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.2.0" />
+
+`FileUpload` adds drag-and-drop file upload to any server. Users upload files through an interactive UI, bypassing the LLM context window entirely. The LLM can then list and read uploaded files through model-visible tools.
+
+<Frame>
+  <img src="/apps/images/app-file-upload.png" alt="The FileUpload provider shown in Goose, with a drag-and-drop zone for uploading files" />
+</Frame>
+
+```python
+from fastmcp import FastMCP
+from fastmcp.apps.file_upload import FileUpload
+
+mcp = FastMCP("My Server")
+mcp.add_provider(FileUpload())
+```
+
+This registers four tools:
+
+| Tool | Visibility | Purpose |
+|------|-----------|---------|
+| `file_manager` | Model | Opens the drag-and-drop upload UI |
+| `store_files` | App only | Called by the UI when the user clicks Upload |
+| `list_files` | Model | Returns metadata for all uploaded files |
+| `read_file` | Model | Returns a file's contents by name |
+
+The LLM sees `file_manager`, `list_files`, and `read_file`. It calls `file_manager` to show the upload interface, then uses `list_files` and `read_file` to work with whatever the user uploaded. `store_files` is app-only — the UI calls it directly and the LLM never needs to know about it.
+
+## Configuration
+
+```python
+FileUpload(
+    name="Files",                    # App name (used in tool routing)
+    max_file_size=10 * 1024 * 1024,  # 10 MB default, enforced server-side
+    title="File Upload",             # Heading shown in the UI
+    description="Drop files to...",  # Description text below the heading
+    drop_label="Drop files here",    # Label inside the drop zone
+)
+```
+
+The `max_file_size` limit is enforced both in the UI (the DropZone rejects oversized files) and on the server (the `store_files` tool validates before calling `on_store`).
+
+## Storage scoping
+
+By default, files are stored in memory and scoped by MCP session ID. Each session gets its own isolated file store — files uploaded in one conversation aren't visible in another.
+
+This works with **stdio**, **SSE**, and **stateful HTTP** transports, where sessions persist across requests.
+
+<Warning>
+In **stateless HTTP** mode, each request creates a new session object with a new ID. Files stored during one request (e.g. the UI upload) will be invisible to the next request (e.g. the LLM calling `list_files`). You **must** override `_get_scope_key` to use a stable identifier like a user ID from your auth token.
+</Warning>
+
+For stateless deployments, override `_get_scope_key` to return a stable identifier. For example, to scope files by authenticated user:
+
+```python
+from fastmcp.apps.file_upload import FileUpload
+
+class UserScopedUpload(FileUpload):
+    def _get_scope_key(self, ctx):
+        return ctx.access_token["sub"]
+```
+
+For process-wide shared storage (all users see all files):
+
+```python
+class SharedUpload(FileUpload):
+    def _get_scope_key(self, ctx):
+        return "__shared__"
+```
+
+## Custom storage
+
+The default implementation stores files in memory for the lifetime of the server process. For persistent storage, subclass `FileUpload` and override three methods. Each receives the current `Context`, giving you access to session IDs, auth tokens, and request metadata for partitioning and authorization.
+
+```python
+import base64
+
+from fastmcp.apps.file_upload import FileUpload
+
+class S3Upload(FileUpload):
+    def on_store(self, files, ctx):
+        user_id = ctx.access_token["sub"]
+        for f in files:
+            s3.put_object(
+                Bucket="uploads",
+                Key=f"{user_id}/{f['name']}",
+                Body=base64.b64decode(f["data"]),
+            )
+        return self.on_list(ctx)
+
+    def on_list(self, ctx):
+        user_id = ctx.access_token["sub"]
+        objects = s3.list_objects(Bucket="uploads", Prefix=f"{user_id}/")
+        return [
+            {
+                "name": obj["Key"].split("/", 1)[1],
+                "type": "application/octet-stream",
+                "size": obj["Size"],
+                "size_display": f"{obj['Size']} B",
+                "uploaded_at": obj["LastModified"].isoformat(),
+            }
+            for obj in objects.get("Contents", [])
+        ]
+
+    def on_read(self, name, ctx):
+        user_id = ctx.access_token["sub"]
+        obj = s3.get_object(Bucket="uploads", Key=f"{user_id}/{name}")
+        content = obj["Body"].read()
+        return {
+            "name": name,
+            "size": obj["ContentLength"],
+            "type": obj["ContentType"],
+            "uploaded_at": obj["LastModified"].isoformat(),
+            "content": content.decode("utf-8"),
+        }
+```
+
+Each file dict passed to `on_store` contains `name`, `size`, `type`, and `data` (base64-encoded content). The return value from `on_store` and `on_list` should be a list of summary dicts with `name`, `type`, `size`, `size_display`, and `uploaded_at` fields — these populate the file list in the UI.
+
+`on_read` returns a dict with file metadata and either `content` (decoded text) or `content_base64` (a base64 preview for binary files).
diff --git a/docs/apps/providers/form.mdx b/docs/apps/providers/form.mdx
new file mode 100644
index 0000000..e61dc0c
--- /dev/null
+++ b/docs/apps/providers/form.mdx
@@ -0,0 +1,105 @@
+---
+title: Form Input
+sidebarTitle: Form Input
+description: Collect structured data from users via Pydantic models
+icon: rectangle-list
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.2.0" />
+
+`FormInput` generates a validated form from a Pydantic model. The user fills it out, and the submission is validated against the model before being returned. Structured elicitation that can't be hallucinated.
+
+<Frame>
+  <img src="/apps/images/app-form.png" alt="The FormInput provider shown in Goose, with a bug report form" />
+</Frame>
+
+```python
+from typing import Literal
+
+from pydantic import BaseModel, Field
+from fastmcp import FastMCP
+from fastmcp.apps.form import FormInput
+
+class BugReport(BaseModel):
+    title: str = Field(description="Brief summary")
+    severity: Literal["low", "medium", "high", "critical"]
+    description: str = Field(
+        description="Detailed description",
+        json_schema_extra={"ui": {"type": "textarea"}},
+    )
+
+mcp = FastMCP("My Server")
+mcp.add_provider(FormInput(model=BugReport))
+```
+
+This registers two tools:
+
+| Tool | Visibility | Purpose |
+|------|-----------|---------|
+| `collect_bugreport` | Model | Opens the form UI |
+| `submit_form` | App only | Validates and processes the submission |
+
+The tool name is derived from the model class name, lowercased: `collect_{modelname}`. So `BugReport` becomes `collect_bugreport`, `ShippingAddress` becomes `collect_shippingaddress`. Use `tool_name` to override if needed. The LLM calls it with a prompt explaining what it needs, and the user gets a form with fields matching the model.
+
+## Field mapping
+
+`FormInput` uses Prefab's `Form.from_model()`, which maps Pydantic types to form components:
+
+| Python type | Form component |
+|------------|---------------|
+| `str` | Text input |
+| `int`, `float` | Number input |
+| `bool` | Checkbox |
+| `datetime.date` | Date picker |
+| `Literal[...]` | Select dropdown |
+| `SecretStr` | Password input |
+
+Use `Field()` metadata to control labels (`title`), placeholders (`description`), and validation (`min_length`, `max_length`, `ge`, `le`). Use `json_schema_extra={"ui": {"type": "textarea"}}` for multiline text.
+
+## Callback
+
+By default, the validated model is returned as JSON. Provide an `on_submit` callback to process the data server-side:
+
+```python
+def save_report(report: BugReport) -> str:
+    db.insert(report.model_dump())
+    return f"Bug #{db.last_id} filed: {report.title}"
+
+mcp.add_provider(FormInput(model=BugReport, on_submit=save_report))
+```
+
+The callback receives a validated model instance and returns a string that becomes the tool result.
+
+## Configuration
+
+```python
+FormInput(
+    model=BugReport,             # Required: the Pydantic model
+    name="BugTracker",           # App name (default: model name)
+    title="File a Bug",          # Card heading (default: model name)
+    tool_name="file_bug",        # Tool name (default: collect_{model})
+    submit_text="Submit Report", # Button label (default: "Submit")
+    on_submit=save_report,       # Optional callback
+    send_message=True,           # Push result as a chat message
+)
+```
+
+Set `send_message=True` to push the result back into the conversation via `SendMessage`, triggering the LLM's next turn. Without it, the result is just the tool return value.
+
+## Multiple forms
+
+Add multiple providers for different models — each gets its own tool:
+
+```python
+mcp = FastMCP(
+    "My Server",
+    providers=[
+        FormInput(model=ShippingAddress),
+        FormInput(model=BugReport),
+        FormInput(model=ContactInfo),
+    ],
+)
+```
diff --git a/docs/apps/quickstart.mdx b/docs/apps/quickstart.mdx
new file mode 100644
index 0000000..2221b9d
--- /dev/null
+++ b/docs/apps/quickstart.mdx
@@ -0,0 +1,197 @@
+---
+title: Quickstart
+sidebarTitle: Quickstart
+description: Build your first FastMCP app in under a minute.
+icon: rocket
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+import { PrefabDemoFrame } from '/snippets/prefab-demo-frame.mdx'
+
+<VersionBadge version="3.2.0" />
+
+By the end of this page, you'll have a working tool that returns this:
+
+<PrefabDemoFrame demo="team-directory" height="545px" title="Team directory demo" />
+
+A pie chart the user can hover, a table they can sort and search — and a single Python tool.
+
+## Install
+
+```bash
+pip install "fastmcp[apps]"
+```
+
+The `apps` extra pulls in [Prefab](https://prefab.prefect.io), the Python component library used to build app UIs.
+
+## Write the tool
+
+Create `server.py`. The interesting parts: `app=True` tells FastMCP this tool renders a UI, and `with PrefabApp() as app:` is the canonical pattern for composing one.
+
+```python server.py expandable
+from collections import Counter
+
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import Column, DataTable, DataTableColumn, Grid
+from prefab_ui.components.charts import PieChart
+from fastmcp import FastMCP
+
+mcp = FastMCP("My First App")
+
+
+@mcp.tool(app=True)
+def team_directory() -> PrefabApp:
+    """Browse the team directory."""
+    members = [
+        {"name": "Alice Chen", "role": "Staff Engineer", "office": "San Francisco"},
+        {"name": "Bob Martinez", "role": "Lead Designer", "office": "New York"},
+        {"name": "Carol Johnson", "role": "Senior Engineer", "office": "London"},
+        {"name": "David Kim", "role": "Product Manager", "office": "San Francisco"},
+        {"name": "Eva Mueller", "role": "Engineer", "office": "Berlin"},
+        {"name": "Frank Lee", "role": "Data Scientist", "office": "San Francisco"},
+        {"name": "Grace Park", "role": "Engineering Manager", "office": "New York"},
+    ]
+
+    office_counts = [
+        {"office": office, "count": count}
+        for office, count in Counter(m["office"] for m in members).items()
+    ]
+
+    with PrefabApp() as app:
+        with Column(gap=4, css_class="p-6"):
+            with Grid(columns=[1, 2], gap=4):
+                PieChart(
+                    data=office_counts,
+                    data_key="count",
+                    name_key="office",
+                    show_legend=True,
+                )
+                DataTable(
+                    columns=[
+                        DataTableColumn(key="name", header="Name", sortable=True),
+                        DataTableColumn(key="role", header="Role", sortable=True),
+                        DataTableColumn(key="office", header="Office", sortable=True),
+                    ],
+                    rows=members,
+                    search=True,
+                )
+
+    return app
+```
+
+The Prefab code reads top-to-bottom. `PrefabApp()` is the root; everything inside its `with` block becomes the UI. `Column` stacks children vertically, `Grid` lays them out in columns. `DataTable` takes rows and column definitions and gives you sort and search for free.
+
+`app=True` does the rest: it sets up the renderer resource, the content security policy, and the metadata that tells the host "this tool returns a UI." The host loads the result in a sandboxed iframe where the user can interact with it — all client-side, no round-trips.
+
+## Preview it
+
+FastMCP ships a dev server that renders your app tools in a browser, no MCP host needed:
+
+```bash
+fastmcp dev apps server.py
+```
+
+Open `http://localhost:8080`, pick `team_directory`, and try sorting columns and searching.
+
+<Frame>
+  <img src="/apps/images/app-quickstart-dev-2.png" alt="The team directory rendered in the fastmcp dev apps preview, showing a pie chart, searchable table, and a detail card after clicking a row" />
+</Frame>
+
+## Make it reactive
+
+The UI above renders once from your Python. Prefab apps can also respond to user input live, without any server round-trips. The key concept is **state**: a client-side key-value store that components read from and write to.
+
+Click a row in the demo below to see a detail card appear:
+
+<PrefabDemoFrame demo="team-directory-reactive" height="675px" title="Reactive team directory demo" />
+
+Add a few imports, give each member a couple more fields, wire up a click handler, and render a detail card when something's selected:
+
+```python expandable server.py
+from collections import Counter
+
+from prefab_ui.actions import SetState
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import (
+    Badge, Card, CardContent, CardHeader, Column, DataTable, DataTableColumn,
+    Grid, H3, Row, Small, Text,
+)
+from prefab_ui.components.charts import PieChart
+from prefab_ui.components.control_flow import If
+from prefab_ui.rx import Rx, STATE
+from fastmcp import FastMCP
+
+mcp = FastMCP("My First App")
+
+MEMBERS = [
+    {"name": "Alice Chen", "role": "Staff Engineer", "office": "San Francisco", "email": "alice@company.com", "projects": 3},
+    {"name": "Bob Martinez", "role": "Lead Designer", "office": "New York", "email": "bob@company.com", "projects": 5},
+    # ... more members ...
+]
+
+OFFICE_COUNTS = [
+    {"office": o, "count": c}
+    for o, c in Counter(m["office"] for m in MEMBERS).items()
+]
+
+
+@mcp.tool(app=True)
+def team_directory() -> PrefabApp:
+    """Browse the team directory."""
+    with PrefabApp(state={"selected": None}) as app:
+        with Column(gap=4, css_class="p-6"):
+            with Grid(columns=[1, 2], gap=4):
+                PieChart(
+                    data=OFFICE_COUNTS,
+                    data_key="count",
+                    name_key="office",
+                    show_legend=True,
+                )
+                DataTable(
+                    columns=[
+                        DataTableColumn(key="name", header="Name", sortable=True),
+                        DataTableColumn(key="role", header="Role", sortable=True),
+                        DataTableColumn(key="office", header="Office", sortable=True),
+                    ],
+                    rows=MEMBERS,
+                    search=True,
+                    on_row_click=SetState("selected", Rx("$event")),
+                )
+
+            with If(STATE.selected):
+                with Card():
+                    with CardHeader():
+                        with Row(gap=2, align="center"):
+                            H3(Rx("selected.name"))
+                            Badge(Rx("selected.office"))
+                    with CardContent():
+                        with Grid(columns=3, gap=4):
+                            with Column(gap=0):
+                                Small("Role")
+                                Text(Rx("selected.role"))
+                            with Column(gap=0):
+                                Small("Email")
+                                Text(Rx("selected.email"))
+                            with Column(gap=0):
+                                Small("Active Projects")
+                                Text(Rx("selected.projects"))
+
+    return app
+```
+
+Three new ideas do all the work:
+
+- **`on_row_click=SetState("selected", Rx("$event"))`** — clicking a row writes its data into the `selected` state key. `$event` is the clicked row dict.
+- **`Rx("selected.name")`** — a reactive reference. It doesn't hold a Python value; it compiles to a browser-side expression that re-evaluates whenever `selected` changes, so `Text(Rx("selected.name"))` always shows the latest clicked name.
+- **`If(STATE.selected)`** — conditionally renders its body. Before any click, `selected` is `None` and the card stays hidden.
+
+The `state={"selected": None}` dict on `PrefabApp` sets the initial value. Everything else happens in the browser — no round-trips to your server when the user clicks.
+
+## Where to go next
+
+You've built a tool that returns an interactive, reactive UI. This pattern covers a huge range of use cases: build a visualization, return it, and the user gets it rendered right in the conversation.
+
+- **[Interactive Tools](/apps/prefab)** — charts, tables, dashboards, reactive state, with live demos
+- **[FastMCPApp](/apps/fastmcp-app)** — when the UI needs to call back to your server (forms, search, CRUD)
+- **[Examples](/apps/examples)** — complete working servers you can run today
diff --git a/docs/assets/brand/blue-logo.png b/docs/assets/brand/blue-logo.png
new file mode 100644
index 0000000..18c3bc6
Binary files /dev/null and b/docs/assets/brand/blue-logo.png differ
diff --git a/docs/assets/brand/f-watercolor-waves-2.png b/docs/assets/brand/f-watercolor-waves-2.png
new file mode 100644
index 0000000..9982cd8
Binary files /dev/null and b/docs/assets/brand/f-watercolor-waves-2.png differ
diff --git a/docs/assets/brand/f-watercolor-waves-3.png b/docs/assets/brand/f-watercolor-waves-3.png
new file mode 100644
index 0000000..3dc9951
Binary files /dev/null and b/docs/assets/brand/f-watercolor-waves-3.png differ
diff --git a/docs/assets/brand/f-watercolor-waves-4-animated.mp4 b/docs/assets/brand/f-watercolor-waves-4-animated.mp4
new file mode 100644
index 0000000..d1384e3
Binary files /dev/null and b/docs/assets/brand/f-watercolor-waves-4-animated.mp4 differ
diff --git a/docs/assets/brand/f-watercolor-waves-4-dark-animated.mp4 b/docs/assets/brand/f-watercolor-waves-4-dark-animated.mp4
new file mode 100644
index 0000000..e906a02
Binary files /dev/null and b/docs/assets/brand/f-watercolor-waves-4-dark-animated.mp4 differ
diff --git a/docs/assets/brand/f-watercolor-waves-4-dark.png b/docs/assets/brand/f-watercolor-waves-4-dark.png
new file mode 100644
index 0000000..1c41182
Binary files /dev/null and b/docs/assets/brand/f-watercolor-waves-4-dark.png differ
diff --git a/docs/assets/brand/f-watercolor-waves-4.png b/docs/assets/brand/f-watercolor-waves-4.png
new file mode 100644
index 0000000..eccd888
Binary files /dev/null and b/docs/assets/brand/f-watercolor-waves-4.png differ
diff --git a/docs/assets/brand/f-watercolor-waves-dark-2.jpeg b/docs/assets/brand/f-watercolor-waves-dark-2.jpeg
new file mode 100644
index 0000000..1c0bc14
Binary files /dev/null and b/docs/assets/brand/f-watercolor-waves-dark-2.jpeg differ
diff --git a/docs/assets/brand/f-watercolor-waves-dark.png b/docs/assets/brand/f-watercolor-waves-dark.png
new file mode 100644
index 0000000..a50956c
Binary files /dev/null and b/docs/assets/brand/f-watercolor-waves-dark.png differ
diff --git a/docs/assets/brand/f-watercolor-waves.png b/docs/assets/brand/f-watercolor-waves.png
new file mode 100644
index 0000000..93ccf6e
Binary files /dev/null and b/docs/assets/brand/f-watercolor-waves.png differ
diff --git a/docs/assets/brand/favicon-dark.svg b/docs/assets/brand/favicon-dark.svg
new file mode 100644
index 0000000..4c2491e
--- /dev/null
+++ b/docs/assets/brand/favicon-dark.svg
@@ -0,0 +1,7 @@
+<svg width="196" height="196" viewBox="0 0 196 196" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="196" height="196" fill="#202020"/>
+<path d="M145.747 44.611L145.355 44.3877L144.96 44.611L86.0283 78.5276V171.267L86.4014 171.499L99.6674 179.667V86.3859L159 52.2379L145.747 44.611Z" fill="#F1F1F1"/>
+<path d="M121.616 30.2714L121.224 30.0454L120.832 30.2714L61.8975 64.188V156.928L62.2732 157.156L75.5393 165.325V72.0463L134.869 37.8983L121.616 30.2714Z" fill="#F1F1F1"/>
+<path d="M97.4894 16.3818L97.0973 16.1558L96.7025 16.3818L37.7705 50.3038V142.066L51.4096 150.463V58.1567L110.742 24.0086L97.4894 16.3818Z" fill="#F1F1F1"/>
+<path d="M131.23 113.671L124.979 117.266L124.584 117.494V117.5L116.796 121.987L110.547 125.581L110.152 125.807V141.51L144.564 121.709V121.698L158.999 113.394V97.6851L139.277 109.034L131.23 113.671Z" fill="#F1F1F1"/>
+</svg>
diff --git a/docs/assets/brand/favicon-light.svg b/docs/assets/brand/favicon-light.svg
new file mode 100644
index 0000000..a30944e
--- /dev/null
+++ b/docs/assets/brand/favicon-light.svg
@@ -0,0 +1,7 @@
+<svg width="196" height="196" viewBox="0 0 196 196" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="196" height="196" fill="#F1F1F1"/>
+<path d="M145.747 44.611L145.355 44.3877L144.96 44.611L86.0283 78.5276V171.267L86.4014 171.499L99.6674 179.667V86.3859L159 52.2379L145.747 44.611Z" fill="#2C2C2C"/>
+<path d="M121.616 30.2714L121.224 30.0454L120.832 30.2714L61.8975 64.188V156.928L62.2732 157.156L75.5393 165.325V72.0463L134.869 37.8983L121.616 30.2714Z" fill="#2C2C2C"/>
+<path d="M97.4894 16.3818L97.0973 16.1558L96.7025 16.3818L37.7705 50.3038V142.066L51.4096 150.463V58.1567L110.742 24.0086L97.4894 16.3818Z" fill="#2C2C2C"/>
+<path d="M131.23 113.671L124.979 117.266L124.584 117.494V117.5L116.796 121.987L110.547 125.581L110.152 125.807V141.51L144.564 121.709V121.698L158.999 113.394V97.6851L139.277 109.034L131.23 113.671Z" fill="#2C2C2C"/>
+</svg>
diff --git a/docs/assets/brand/prefect-fastmcp.png b/docs/assets/brand/prefect-fastmcp.png
new file mode 100644
index 0000000..76a5577
Binary files /dev/null and b/docs/assets/brand/prefect-fastmcp.png differ
diff --git a/docs/assets/brand/prefect-wordmark-dark.png b/docs/assets/brand/prefect-wordmark-dark.png
new file mode 100644
index 0000000..43019d1
Binary files /dev/null and b/docs/assets/brand/prefect-wordmark-dark.png differ
diff --git a/docs/assets/brand/prefect-wordmark-light.png b/docs/assets/brand/prefect-wordmark-light.png
new file mode 100644
index 0000000..6d0f58f
Binary files /dev/null and b/docs/assets/brand/prefect-wordmark-light.png differ
diff --git a/docs/assets/brand/thumbnail-background-2.png b/docs/assets/brand/thumbnail-background-2.png
new file mode 100644
index 0000000..a3eeb62
Binary files /dev/null and b/docs/assets/brand/thumbnail-background-2.png differ
diff --git a/docs/assets/brand/thumbnail-background-3.jpeg b/docs/assets/brand/thumbnail-background-3.jpeg
new file mode 100644
index 0000000..efda5c8
Binary files /dev/null and b/docs/assets/brand/thumbnail-background-3.jpeg differ
diff --git a/docs/assets/brand/thumbnail-background-4.jpeg b/docs/assets/brand/thumbnail-background-4.jpeg
new file mode 100644
index 0000000..af45659
Binary files /dev/null and b/docs/assets/brand/thumbnail-background-4.jpeg differ
diff --git a/docs/assets/brand/thumbnail-background.png b/docs/assets/brand/thumbnail-background.png
new file mode 100644
index 0000000..2f93bc0
Binary files /dev/null and b/docs/assets/brand/thumbnail-background.png differ
diff --git a/docs/assets/brand/wordmark-padded.png b/docs/assets/brand/wordmark-padded.png
new file mode 100644
index 0000000..5dc7932
Binary files /dev/null and b/docs/assets/brand/wordmark-padded.png differ
diff --git a/docs/assets/brand/wordmark-watercolor-rainbow-dark.png b/docs/assets/brand/wordmark-watercolor-rainbow-dark.png
new file mode 100644
index 0000000..5c2d673
Binary files /dev/null and b/docs/assets/brand/wordmark-watercolor-rainbow-dark.png differ
diff --git a/docs/assets/brand/wordmark-watercolor-rainbow.png b/docs/assets/brand/wordmark-watercolor-rainbow.png
new file mode 100644
index 0000000..f163704
Binary files /dev/null and b/docs/assets/brand/wordmark-watercolor-rainbow.png differ
diff --git a/docs/assets/brand/wordmark-watercolor-waves-dark.png b/docs/assets/brand/wordmark-watercolor-waves-dark.png
new file mode 100644
index 0000000..02d9367
Binary files /dev/null and b/docs/assets/brand/wordmark-watercolor-waves-dark.png differ
diff --git a/docs/assets/brand/wordmark-watercolor-waves.png b/docs/assets/brand/wordmark-watercolor-waves.png
new file mode 100644
index 0000000..84950f9
Binary files /dev/null and b/docs/assets/brand/wordmark-watercolor-waves.png differ
diff --git a/docs/assets/brand/wordmark-white-padded.png b/docs/assets/brand/wordmark-white-padded.png
new file mode 100644
index 0000000..71eb807
Binary files /dev/null and b/docs/assets/brand/wordmark-white-padded.png differ
diff --git a/docs/assets/brand/wordmark-white.png b/docs/assets/brand/wordmark-white.png
new file mode 100644
index 0000000..81377c5
Binary files /dev/null and b/docs/assets/brand/wordmark-white.png differ
diff --git a/docs/assets/brand/wordmark.png b/docs/assets/brand/wordmark.png
new file mode 100644
index 0000000..41b5717
Binary files /dev/null and b/docs/assets/brand/wordmark.png differ
diff --git a/docs/assets/images/apps-card.png b/docs/assets/images/apps-card.png
new file mode 100644
index 0000000..0bb8d81
Binary files /dev/null and b/docs/assets/images/apps-card.png differ
diff --git a/docs/assets/images/clients-card.png b/docs/assets/images/clients-card.png
new file mode 100644
index 0000000..0d5eb05
Binary files /dev/null and b/docs/assets/images/clients-card.png differ
diff --git a/docs/assets/images/horizon/agent-chat.png b/docs/assets/images/horizon/agent-chat.png
new file mode 100644
index 0000000..8eff8f8
Binary files /dev/null and b/docs/assets/images/horizon/agent-chat.png differ
diff --git a/docs/assets/images/horizon/agent-detail.png b/docs/assets/images/horizon/agent-detail.png
new file mode 100644
index 0000000..b3cef5d
Binary files /dev/null and b/docs/assets/images/horizon/agent-detail.png differ
diff --git a/docs/assets/images/horizon/chat.png b/docs/assets/images/horizon/chat.png
new file mode 100644
index 0000000..4c42695
Binary files /dev/null and b/docs/assets/images/horizon/chat.png differ
diff --git a/docs/assets/images/horizon/configure-server.png b/docs/assets/images/horizon/configure-server.png
new file mode 100644
index 0000000..a51a665
Binary files /dev/null and b/docs/assets/images/horizon/configure-server.png differ
diff --git a/docs/assets/images/horizon/deployment-live.png b/docs/assets/images/horizon/deployment-live.png
new file mode 100644
index 0000000..2cd9046
Binary files /dev/null and b/docs/assets/images/horizon/deployment-live.png differ
diff --git a/docs/assets/images/horizon/select-repo.png b/docs/assets/images/horizon/select-repo.png
new file mode 100644
index 0000000..1a6ecfe
Binary files /dev/null and b/docs/assets/images/horizon/select-repo.png differ
diff --git a/docs/assets/images/oauth-proxy-consent-screen.png b/docs/assets/images/oauth-proxy-consent-screen.png
new file mode 100644
index 0000000..5613b66
Binary files /dev/null and b/docs/assets/images/oauth-proxy-consent-screen.png differ
diff --git a/docs/assets/images/servers-card.png b/docs/assets/images/servers-card.png
new file mode 100644
index 0000000..6db828c
Binary files /dev/null and b/docs/assets/images/servers-card.png differ
diff --git a/docs/assets/images/tutorial-rest-api-result.png b/docs/assets/images/tutorial-rest-api-result.png
new file mode 100644
index 0000000..1ff5fc0
Binary files /dev/null and b/docs/assets/images/tutorial-rest-api-result.png differ
diff --git a/docs/assets/schemas/mcp_server_config/latest.json b/docs/assets/schemas/mcp_server_config/latest.json
new file mode 100644
index 0000000..81d0ad7
--- /dev/null
+++ b/docs/assets/schemas/mcp_server_config/latest.json
@@ -0,0 +1,348 @@
+{
+  "$defs": {
+    "Deployment": {
+      "description": "Configuration for server deployment and runtime settings.",
+      "properties": {
+        "transport": {
+          "anyOf": [
+            {
+              "enum": [
+                "stdio",
+                "http",
+                "sse"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Transport protocol to use",
+          "title": "Transport"
+        },
+        "host": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Host to bind to when using HTTP transport",
+          "examples": [
+            "127.0.0.1",
+            "0.0.0.0",
+            "localhost"
+          ],
+          "title": "Host"
+        },
+        "port": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Port to bind to when using HTTP transport",
+          "examples": [
+            8000,
+            3000,
+            5000
+          ],
+          "title": "Port"
+        },
+        "path": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "URL path for the server endpoint",
+          "examples": [
+            "/mcp/",
+            "/api/mcp/",
+            "/sse/"
+          ],
+          "title": "Path"
+        },
+        "log_level": {
+          "anyOf": [
+            {
+              "enum": [
+                "DEBUG",
+                "INFO",
+                "WARNING",
+                "ERROR",
+                "CRITICAL"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Log level for the server",
+          "title": "Log Level"
+        },
+        "cwd": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Working directory for the server process",
+          "examples": [
+            ".",
+            "./src",
+            "/app"
+          ],
+          "title": "Cwd"
+        },
+        "env": {
+          "anyOf": [
+            {
+              "additionalProperties": {
+                "type": "string"
+              },
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Environment variables to set when running the server",
+          "examples": [
+            {
+              "API_KEY": "secret",
+              "DEBUG": "true"
+            }
+          ],
+          "title": "Env"
+        },
+        "args": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Arguments to pass to the server (after --)",
+          "examples": [
+            [
+              "--config",
+              "config.json",
+              "--debug"
+            ]
+          ],
+          "title": "Args"
+        }
+      },
+      "title": "Deployment",
+      "type": "object"
+    },
+    "Environment": {
+      "description": "Configuration for Python environment setup.",
+      "properties": {
+        "python": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Python version constraint",
+          "examples": [
+            "3.10",
+            "3.11",
+            "3.12"
+          ],
+          "title": "Python"
+        },
+        "dependencies": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Python packages to install with PEP 508 specifiers",
+          "examples": [
+            [
+              "fastmcp>=2.0,<3",
+              "httpx",
+              "pandas>=2.0"
+            ]
+          ],
+          "title": "Dependencies"
+        },
+        "requirements": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Path to requirements.txt file",
+          "examples": [
+            "requirements.txt",
+            "../requirements/prod.txt"
+          ],
+          "title": "Requirements"
+        },
+        "project": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Path to project directory containing pyproject.toml",
+          "examples": [
+            ".",
+            "../my-project"
+          ],
+          "title": "Project"
+        },
+        "editable": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Directory to install in editable mode",
+          "examples": [
+            ".",
+            "../my-package"
+          ],
+          "title": "Editable"
+        }
+      },
+      "title": "Environment",
+      "type": "object"
+    },
+    "FileSystemSource": {
+      "description": "Source for local Python files.",
+      "properties": {
+        "type": {
+          "const": "filesystem",
+          "default": "filesystem",
+          "description": "Source type",
+          "title": "Type",
+          "type": "string"
+        },
+        "path": {
+          "description": "Path to Python file containing the server",
+          "title": "Path",
+          "type": "string"
+        },
+        "entrypoint": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Name of server instance or factory function (a no-arg function that returns a FastMCP server)",
+          "title": "Entrypoint"
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "title": "FileSystemSource",
+      "type": "object"
+    }
+  },
+  "description": "Configuration file for FastMCP servers",
+  "properties": {
+    "$schema": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+      "description": "JSON schema for IDE support and validation",
+      "title": "$Schema"
+    },
+    "source": {
+      "$ref": "#/$defs/FileSystemSource",
+      "description": "Source configuration for the server",
+      "examples": [
+        {
+          "path": "server.py"
+        },
+        {
+          "entrypoint": "app",
+          "path": "server.py"
+        },
+        {
+          "entrypoint": "mcp",
+          "path": "src/server.py",
+          "type": "filesystem"
+        }
+      ]
+    },
+    "environment": {
+      "$ref": "#/$defs/Environment",
+      "description": "Python environment setup configuration"
+    },
+    "deployment": {
+      "$ref": "#/$defs/Deployment",
+      "description": "Server deployment and runtime settings"
+    }
+  },
+  "required": [
+    "source"
+  ],
+  "title": "FastMCP Configuration",
+  "type": "object",
+  "$id": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json"
+}
diff --git a/docs/assets/schemas/mcp_server_config/v1.json b/docs/assets/schemas/mcp_server_config/v1.json
new file mode 100644
index 0000000..81d0ad7
--- /dev/null
+++ b/docs/assets/schemas/mcp_server_config/v1.json
@@ -0,0 +1,348 @@
+{
+  "$defs": {
+    "Deployment": {
+      "description": "Configuration for server deployment and runtime settings.",
+      "properties": {
+        "transport": {
+          "anyOf": [
+            {
+              "enum": [
+                "stdio",
+                "http",
+                "sse"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Transport protocol to use",
+          "title": "Transport"
+        },
+        "host": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Host to bind to when using HTTP transport",
+          "examples": [
+            "127.0.0.1",
+            "0.0.0.0",
+            "localhost"
+          ],
+          "title": "Host"
+        },
+        "port": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Port to bind to when using HTTP transport",
+          "examples": [
+            8000,
+            3000,
+            5000
+          ],
+          "title": "Port"
+        },
+        "path": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "URL path for the server endpoint",
+          "examples": [
+            "/mcp/",
+            "/api/mcp/",
+            "/sse/"
+          ],
+          "title": "Path"
+        },
+        "log_level": {
+          "anyOf": [
+            {
+              "enum": [
+                "DEBUG",
+                "INFO",
+                "WARNING",
+                "ERROR",
+                "CRITICAL"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Log level for the server",
+          "title": "Log Level"
+        },
+        "cwd": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Working directory for the server process",
+          "examples": [
+            ".",
+            "./src",
+            "/app"
+          ],
+          "title": "Cwd"
+        },
+        "env": {
+          "anyOf": [
+            {
+              "additionalProperties": {
+                "type": "string"
+              },
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Environment variables to set when running the server",
+          "examples": [
+            {
+              "API_KEY": "secret",
+              "DEBUG": "true"
+            }
+          ],
+          "title": "Env"
+        },
+        "args": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Arguments to pass to the server (after --)",
+          "examples": [
+            [
+              "--config",
+              "config.json",
+              "--debug"
+            ]
+          ],
+          "title": "Args"
+        }
+      },
+      "title": "Deployment",
+      "type": "object"
+    },
+    "Environment": {
+      "description": "Configuration for Python environment setup.",
+      "properties": {
+        "python": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Python version constraint",
+          "examples": [
+            "3.10",
+            "3.11",
+            "3.12"
+          ],
+          "title": "Python"
+        },
+        "dependencies": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Python packages to install with PEP 508 specifiers",
+          "examples": [
+            [
+              "fastmcp>=2.0,<3",
+              "httpx",
+              "pandas>=2.0"
+            ]
+          ],
+          "title": "Dependencies"
+        },
+        "requirements": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Path to requirements.txt file",
+          "examples": [
+            "requirements.txt",
+            "../requirements/prod.txt"
+          ],
+          "title": "Requirements"
+        },
+        "project": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Path to project directory containing pyproject.toml",
+          "examples": [
+            ".",
+            "../my-project"
+          ],
+          "title": "Project"
+        },
+        "editable": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Directory to install in editable mode",
+          "examples": [
+            ".",
+            "../my-package"
+          ],
+          "title": "Editable"
+        }
+      },
+      "title": "Environment",
+      "type": "object"
+    },
+    "FileSystemSource": {
+      "description": "Source for local Python files.",
+      "properties": {
+        "type": {
+          "const": "filesystem",
+          "default": "filesystem",
+          "description": "Source type",
+          "title": "Type",
+          "type": "string"
+        },
+        "path": {
+          "description": "Path to Python file containing the server",
+          "title": "Path",
+          "type": "string"
+        },
+        "entrypoint": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Name of server instance or factory function (a no-arg function that returns a FastMCP server)",
+          "title": "Entrypoint"
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "title": "FileSystemSource",
+      "type": "object"
+    }
+  },
+  "description": "Configuration file for FastMCP servers",
+  "properties": {
+    "$schema": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+      "description": "JSON schema for IDE support and validation",
+      "title": "$Schema"
+    },
+    "source": {
+      "$ref": "#/$defs/FileSystemSource",
+      "description": "Source configuration for the server",
+      "examples": [
+        {
+          "path": "server.py"
+        },
+        {
+          "entrypoint": "app",
+          "path": "server.py"
+        },
+        {
+          "entrypoint": "mcp",
+          "path": "src/server.py",
+          "type": "filesystem"
+        }
+      ]
+    },
+    "environment": {
+      "$ref": "#/$defs/Environment",
+      "description": "Python environment setup configuration"
+    },
+    "deployment": {
+      "$ref": "#/$defs/Deployment",
+      "description": "Server deployment and runtime settings"
+    }
+  },
+  "required": [
+    "source"
+  ],
+  "title": "FastMCP Configuration",
+  "type": "object",
+  "$id": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json"
+}
diff --git a/docs/assets/updates/release-2-7.png b/docs/assets/updates/release-2-7.png
new file mode 100644
index 0000000..5716e1f
Binary files /dev/null and b/docs/assets/updates/release-2-7.png differ
diff --git a/docs/changelog.mdx b/docs/changelog.mdx
new file mode 100644
index 0000000..9ee438d
--- /dev/null
+++ b/docs/changelog.mdx
@@ -0,0 +1,3759 @@
+---
+title: "Changelog"
+icon: "list-check"
+rss: true
+tag: NEW
+---
+
+<Update label="v3.4.4" description="2026-07-08">
+
+**[v3.4.4: Host in Translation](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.4)**
+
+FastMCP 3.4.4 restores HTTP deployment compatibility after the 3.4.3 Host/Origin guard changed default behavior for existing ASGI, serverless, and reverse-proxy deployments. The guard implementation remains available for deployments that opt in with explicit trusted hosts and origins, while 3.x returns to accepting traffic that worked before the patch. This release also adds Hugging Face OAuth provider support, with docs and examples for public and private apps, PKCE, Dynamic Client Registration, and CIMD.
+
+### Enhancements ✨
+* Hugging Face Auth Integration by [@evalstate](https://github.com/evalstate) in [#4385](https://github.com/PrefectHQ/fastmcp/pull/4385)
+### Fixes 🐞
+* Relax host origin guard defaults by [@jlowin](https://github.com/jlowin) in [#4439](https://github.com/PrefectHQ/fastmcp/pull/4439)
+* Restore HTTP host guard compatibility by [@jlowin](https://github.com/jlowin) in [#4472](https://github.com/PrefectHQ/fastmcp/pull/4472)
+
+## New Contributors
+* @evalstate made their first contribution in [#4385](https://github.com/PrefectHQ/fastmcp/pull/4385)
+
+**Full Changelog**: [v3.4.3...v3.4.4](https://github.com/PrefectHQ/fastmcp/compare/v3.4.3...v3.4.4)
+
+</Update>
+
+<Update label="v3.4.3" description="2026-07-05">
+
+**[v3.4.3: The Fast and the Secure-ious](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.3)**
+
+FastMCP 3.4.3 closes out a month of SSRF and OAuth hardening: NAT64, 6to4, Teredo, and ISATAP transition addresses can no longer smuggle private IPv4 targets past the SSRF allow-list, Streamable HTTP now validates Host and Origin before session handling to block DNS rebinding against localhost-bound servers, and OAuth redirect validation rejects unsafe schemes and unregistered DCR redirect URIs. Alongside the security work, this release also fixes proxy session teardown races, discriminator-tag handling in JSON schema conversion, and several smaller reliability issues.
+
+### Enhancements ✨
+* Dedupe discriminator-required helper across schema converters by [@jlowin](https://github.com/jlowin) in [#4362](https://github.com/PrefectHQ/fastmcp/pull/4362)
+* Add real Monty sandbox e2e coverage for CodeMode call_tool by [@AlexlaGuardia](https://github.com/AlexlaGuardia) in [#4274](https://github.com/PrefectHQ/fastmcp/pull/4274)
+* Switch prettier hook to rbubley/mirrors-prettier by [@jlowin](https://github.com/jlowin) in [#4366](https://github.com/PrefectHQ/fastmcp/pull/4366)
+* feat(remote): add --verify flag for TLS certificate verification by [@jlowin](https://github.com/jlowin) in [#4369](https://github.com/PrefectHQ/fastmcp/pull/4369)
+### Security 🔒
+* fix(deps): clear Dependabot security alerts via lockfile bumps by [@jlowin](https://github.com/jlowin) in [#4393](https://github.com/PrefectHQ/fastmcp/pull/4393)
+* Clarify resource path parameter safety by [@jlowin](https://github.com/jlowin) in [#4398](https://github.com/PrefectHQ/fastmcp/pull/4398)
+* Fix dev apps launch escaping by [@jlowin](https://github.com/jlowin) in [#4399](https://github.com/PrefectHQ/fastmcp/pull/4399)
+* Block NAT64 SSRF bypass by [@jlowin](https://github.com/jlowin) in [#4400](https://github.com/PrefectHQ/fastmcp/pull/4400)
+* [codex] Fix event store replay isolation by [@jlowin](https://github.com/jlowin) in [#4402](https://github.com/PrefectHQ/fastmcp/pull/4402)
+* Fix DCR redirect URI validation by [@jlowin](https://github.com/jlowin) in [#4408](https://github.com/PrefectHQ/fastmcp/pull/4408)
+* Protect streamable HTTP from DNS rebinding by [@jlowin](https://github.com/jlowin) in [#4405](https://github.com/PrefectHQ/fastmcp/pull/4405)
+* Block unsafe OAuth redirect schemes by [@jlowin](https://github.com/jlowin) in [#4419](https://github.com/PrefectHQ/fastmcp/pull/4419)
+* Block IPv6 transition SSRF bypasses by [@jlowin](https://github.com/jlowin) in [#4426](https://github.com/PrefectHQ/fastmcp/pull/4426)
+### Fixes 🐞
+* fix: caching middleware TypeError on cache miss due to mismatched call_next parameter by [@gmenziesint](https://github.com/gmenziesint) in [#4301](https://github.com/PrefectHQ/fastmcp/pull/4301)
+* Fix: async rate limiting middleware get_client_id callbacks by [@Chotom](https://github.com/Chotom) in [#4319](https://github.com/PrefectHQ/fastmcp/pull/4319)
+* Recognize all GitHub issue-link forms in require-issue-link workflow by [@jlowin](https://github.com/jlowin) in [#4359](https://github.com/PrefectHQ/fastmcp/pull/4359)
+* fix: preserve required discriminator tags by [@he-yufeng](https://github.com/he-yufeng) in [#4297](https://github.com/PrefectHQ/fastmcp/pull/4297)
+* fix(proxy): shield stateful proxy disconnect during session teardown by [@jlowin](https://github.com/jlowin) in [#4363](https://github.com/PrefectHQ/fastmcp/pull/4363)
+* fix(fs): isolate same-named package imports across providers by [@jlowin](https://github.com/jlowin) in [#4361](https://github.com/PrefectHQ/fastmcp/pull/4361)
+* fix: StatefulProxyClient.clear() no longer causes KeyError on session teardown by [@tcconnally](https://github.com/tcconnally) in [#4328](https://github.com/PrefectHQ/fastmcp/pull/4328)
+* fix: guard recursive refs in json_schema_to_type by [@Epochex](https://github.com/Epochex) in [#4312](https://github.com/PrefectHQ/fastmcp/pull/4312)
+* Forward IdP auth errors to MCP client instead of showing HTML error page by [@bobbyjames839](https://github.com/bobbyjames839) in [#4293](https://github.com/PrefectHQ/fastmcp/pull/4293)
+* fix(resources): round-trip path values with reserved characters in URI templates by [@jlowin](https://github.com/jlowin) in [#4368](https://github.com/PrefectHQ/fastmcp/pull/4368)
+* fix: bracket IPv6 hosts in server startup log URL by [@jlowin](https://github.com/jlowin) in [#4372](https://github.com/PrefectHQ/fastmcp/pull/4372)
+* fix: bound default OIDC discovery timeout and expose it on provider wrappers by [@jlowin](https://github.com/jlowin) in [#4374](https://github.com/PrefectHQ/fastmcp/pull/4374)
+* fix: validate task tool arguments against declared types by [@jlowin](https://github.com/jlowin) in [#4373](https://github.com/PrefectHQ/fastmcp/pull/4373)
+* fix(tools): honor serialize_by_alias in tool result serialization by [@jlowin](https://github.com/jlowin) in [#4391](https://github.com/PrefectHQ/fastmcp/pull/4391)
+* Fix/cimd flow issue by [@twjackysu](https://github.com/twjackysu) in [#4206](https://github.com/PrefectHQ/fastmcp/pull/4206)
+* Reject empty env var keys by [@CodingFeng101](https://github.com/CodingFeng101) in [#4410](https://github.com/PrefectHQ/fastmcp/pull/4410)
+* fix: correct replace_type docstring parameter descriptions by [@hiSandog](https://github.com/hiSandog) in [#4375](https://github.com/PrefectHQ/fastmcp/pull/4375)
+* Fix ty 0.0.55 diagnostics and prefab-ui protocol version drift by [@jlowin](https://github.com/jlowin) in [#4428](https://github.com/PrefectHQ/fastmcp/pull/4428)
+* [codex] Fix OpenAPI resource template requests by [@jlowin](https://github.com/jlowin) in [#4407](https://github.com/PrefectHQ/fastmcp/pull/4407)
+### Docs 📚
+* fix: RST docstrings in fastmcp.types render raw on gofastmcp.com by [@jlowin](https://github.com/jlowin) in [#4367](https://github.com/PrefectHQ/fastmcp/pull/4367)
+* docs: fix 5 broken internal links (auth & providers pages) by [@Michael-WhiteCapData](https://github.com/Michael-WhiteCapData) in [#4344](https://github.com/PrefectHQ/fastmcp/pull/4344)
+* docs: add audit/event-record recipe for tool-call middleware by [@AlexlaGuardia](https://github.com/AlexlaGuardia) in [#4345](https://github.com/PrefectHQ/fastmcp/pull/4345)
+### Dependencies 📦
+* chore(deps): bump actions/checkout from 6 to 7 by [@dependabot](https://github.com/apps/dependabot) in [#4343](https://github.com/PrefectHQ/fastmcp/pull/4343)
+* chore(deps): bump joserfc from 1.6.5 to 1.6.7 in the uv group across 1 directory by [@dependabot](https://github.com/apps/dependabot) in [#4394](https://github.com/PrefectHQ/fastmcp/pull/4394)
+* chore(deps): bump joserfc from 1.6.7 to 1.6.8 in the uv group across 1 directory by [@dependabot](https://github.com/apps/dependabot) in [#4429](https://github.com/PrefectHQ/fastmcp/pull/4429)
+### Other Changes 🦾
+* Raise fastmcp.ValidationError for invalid tool arguments by [@jlowin](https://github.com/jlowin) in [#4392](https://github.com/PrefectHQ/fastmcp/pull/4392)
+* Fix versioned auth middleware checks by [@jlowin](https://github.com/jlowin) in [#4401](https://github.com/PrefectHQ/fastmcp/pull/4401)
+
+## New Contributors
+* @gmenziesint made their first contribution in [#4301](https://github.com/PrefectHQ/fastmcp/pull/4301)
+* @Chotom made their first contribution in [#4319](https://github.com/PrefectHQ/fastmcp/pull/4319)
+* @he-yufeng made their first contribution in [#4297](https://github.com/PrefectHQ/fastmcp/pull/4297)
+* @AlexlaGuardia made their first contribution in [#4274](https://github.com/PrefectHQ/fastmcp/pull/4274)
+* @tcconnally made their first contribution in [#4328](https://github.com/PrefectHQ/fastmcp/pull/4328)
+* @Epochex made their first contribution in [#4312](https://github.com/PrefectHQ/fastmcp/pull/4312)
+* @Michael-WhiteCapData made their first contribution in [#4344](https://github.com/PrefectHQ/fastmcp/pull/4344)
+* @bobbyjames839 made their first contribution in [#4293](https://github.com/PrefectHQ/fastmcp/pull/4293)
+* @twjackysu made their first contribution in [#4206](https://github.com/PrefectHQ/fastmcp/pull/4206)
+* @CodingFeng101 made their first contribution in [#4410](https://github.com/PrefectHQ/fastmcp/pull/4410)
+* @hiSandog made their first contribution in [#4375](https://github.com/PrefectHQ/fastmcp/pull/4375)
+
+**Full Changelog**: [v3.4.2...v3.4.3](https://github.com/PrefectHQ/fastmcp/compare/v3.4.2...v3.4.3)
+
+</Update>
+
+<Update label="v3.4.2" description="2026-06-06">
+
+**[v3.4.2: Heads Up](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.2)**
+
+FastMCP 3.4.2 restores JWT compatibility for providers that include private, non-critical JWS header parameters. Tokens from providers like Clerk can carry header metadata such as `cat` without being rejected before signature and claim validation, while unsupported critical headers are still rejected.
+
+### Fixes 🐞
+* Allow private JWT headers by [@jlowin](https://github.com/jlowin) in [#4290](https://github.com/PrefectHQ/fastmcp/pull/4290)
+### Docs 📚
+* Docs: add v3.4.1 changelog entries by [@jlowin](https://github.com/jlowin) in [#4289](https://github.com/PrefectHQ/fastmcp/pull/4289)
+
+**Full Changelog**: [v3.4.1...v3.4.2](https://github.com/PrefectHQ/fastmcp/compare/v3.4.1...v3.4.2)
+
+</Update>
+
+<Update label="v3.4.1" description="2026-06-05">
+
+**[v3.4.1: Floor It](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.1)**
+
+FastMCP 3.4.1 floors Starlette at `>=1.0.1` so installs can no longer resolve to a version affected by CVE-2026-48710, which was previously only constrained transitively through `mcp`. It also makes OAuthProxy log refresh-token cache misses instead of failing silently.
+
+### Enhancements ✨
+* Log refresh-token misses in OAuthProxy instead of failing silently by [@jlowin](https://github.com/jlowin) in [#4276](https://github.com/PrefectHQ/fastmcp/pull/4276)
+### Security 🔒
+* Add explicit starlette>=1.0.1 floor (CVE-2026-48710) by [@jlowin](https://github.com/jlowin) in [#4286](https://github.com/PrefectHQ/fastmcp/pull/4286)
+### Docs 📚
+* Document --notes-start-tag in release instructions by [@jlowin](https://github.com/jlowin) in [#4275](https://github.com/PrefectHQ/fastmcp/pull/4275)
+
+**Full Changelog**: [v3.4.0...v3.4.1](https://github.com/PrefectHQ/fastmcp/compare/v3.4.0...v3.4.1)
+
+</Update>
+
+<Update label="v3.4.0" description="2026-06-02">
+
+**[v3.4.0: Remote Control](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.0)**
+
+FastMCP 3.4 is about reaching servers that live somewhere else. The headline is `fastmcp-remote`, a standalone bridge that connects stdio-only MCP hosts to servers hosted over HTTP. Around it, the proxy layer those connections depend on is hardened: a proxy now forwards `initialize` upstream and fails loudly when the backend is missing or misconfigured, instead of reporting a connected-but-empty proxy. And FastMCP-issued access tokens can now outlive short-lived upstream tokens, so authenticated sessions survive the long idle periods remote clients are prone to.
+
+### New Features 🎉
+* Add fastmcp-remote bridge package by [@jlowin](https://github.com/jlowin) in [#4208](https://github.com/PrefectHQ/fastmcp/pull/4208)
+### Breaking Changes ⚠️
+* Forward proxy initialize as bridge behavior by [@jlowin](https://github.com/jlowin) in [#4228](https://github.com/PrefectHQ/fastmcp/pull/4228)
+### Enhancements ✨
+* ci: require external PRs to link a tracked issue by [@strawgate](https://github.com/strawgate) in [#4173](https://github.com/PrefectHQ/fastmcp/pull/4173)
+* feat: new options --host and --no-log-panel | --log-panel  to cli dev apps by [@itaru2622](https://github.com/itaru2622) in [#4123](https://github.com/PrefectHQ/fastmcp/pull/4123)
+* Add valid_scopes and extra_authorize_params to WorkOSProvider by [@tiagoskaneta](https://github.com/tiagoskaneta) in [#4135](https://github.com/PrefectHQ/fastmcp/pull/4135)
+* Add token_expiry_threshold_seconds for proactive token refresh by [@mohankumarelec](https://github.com/mohankumarelec) in [#4142](https://github.com/PrefectHQ/fastmcp/pull/4142)
+* Add review-issue skill for triaging gated external contributions by [@jlowin](https://github.com/jlowin) in [#4212](https://github.com/PrefectHQ/fastmcp/pull/4212)
+* Add contract gate to review-issue skill by [@jlowin](https://github.com/jlowin) in [#4214](https://github.com/PrefectHQ/fastmcp/pull/4214)
+* Let ToolResult return an error result via is_error by [@jlowin](https://github.com/jlowin) in [#4217](https://github.com/PrefectHQ/fastmcp/pull/4217)
+* Update published docs after PyPI release by [@jlowin](https://github.com/jlowin) in [#4211](https://github.com/PrefectHQ/fastmcp/pull/4211)
+* Allow pre-bound HTTP sockets by [@jlowin](https://github.com/jlowin) in [#4222](https://github.com/PrefectHQ/fastmcp/pull/4222)
+* Add targeted coverage tests by [@strawgate](https://github.com/strawgate) in [#4230](https://github.com/PrefectHQ/fastmcp/pull/4230)
+* Upgrade ty to 0.0.39 by [@jlowin](https://github.com/jlowin) in [#4225](https://github.com/PrefectHQ/fastmcp/pull/4225)
+* Decouple FastMCP access token lifetime from upstream expires_in by [@jlowin](https://github.com/jlowin) in [#4254](https://github.com/PrefectHQ/fastmcp/pull/4254)
+### Security 🔒
+* feat(code-mode): default sandbox limits and per-execution tool-call cap by [@strawgate](https://github.com/strawgate) in [#4170](https://github.com/PrefectHQ/fastmcp/pull/4170)
+* Security: Fix 3 findings in GitHub Actions workflows by [@jpr5](https://github.com/jpr5) in [#4183](https://github.com/PrefectHQ/fastmcp/pull/4183)
+* Add outbound comment guardrails by [@jlowin](https://github.com/jlowin) in [#4196](https://github.com/PrefectHQ/fastmcp/pull/4196)
+* Add uv dependency cooldown by [@jlowin](https://github.com/jlowin) in [#4213](https://github.com/PrefectHQ/fastmcp/pull/4213)
+### Fixes 🐞
+* fix: VersionSpec eq matching normalizes versions and selects deterministically by [@strawgate](https://github.com/strawgate) in [#4058](https://github.com/PrefectHQ/fastmcp/pull/4058)
+* fix(tests): hoist azure-identity import out of the OBO test timeout window by [@strawgate](https://github.com/strawgate) in [#4176](https://github.com/PrefectHQ/fastmcp/pull/4176)
+* fix(auth): disambiguate auth-denied vs missing component messages by [@strawgate](https://github.com/strawgate) in [#4165](https://github.com/PrefectHQ/fastmcp/pull/4165)
+* fix: preserve annotations, meta, title, icons when creating resources from templates by [@strawgate](https://github.com/strawgate) in [#4061](https://github.com/PrefectHQ/fastmcp/pull/4061)
+* fix: add OTEL spans to sampling step and tool execution by [@strawgate](https://github.com/strawgate) in [#4059](https://github.com/PrefectHQ/fastmcp/pull/4059)
+* fix(config): read MCP config files as UTF-8 by [@pragnyanramtha](https://github.com/pragnyanramtha) in [#4164](https://github.com/PrefectHQ/fastmcp/pull/4164)
+* fix(schema): preserve root metadata on fallback by [@yuyua9](https://github.com/yuyua9) in [#4178](https://github.com/PrefectHQ/fastmcp/pull/4178)
+* fix(proxy): restore _current_server in _restore_request_context by [@strawgate](https://github.com/strawgate) in [#4168](https://github.com/PrefectHQ/fastmcp/pull/4168)
+* fix(auth): add /.well-known/openid-configuration alias for OAuth server metadata by [@shigechika](https://github.com/shigechika) in [#4167](https://github.com/PrefectHQ/fastmcp/pull/4167)
+* fix(code-mode): cancel Monty sandbox future on task cancellation by [@strawgate](https://github.com/strawgate) in [#4169](https://github.com/PrefectHQ/fastmcp/pull/4169)
+* fix(auth): unprefix Azure scopes echoed back to MCP clients by [@rgillinlz](https://github.com/rgillinlz) in [#4130](https://github.com/PrefectHQ/fastmcp/pull/4130)
+* fix(cli): forward stateless flag in uv run path by [@yuyua9](https://github.com/yuyua9) in [#4177](https://github.com/PrefectHQ/fastmcp/pull/4177)
+* fix(ci): scope minimize-reviews concurrency by event name by [@strawgate](https://github.com/strawgate) in [#4174](https://github.com/PrefectHQ/fastmcp/pull/4174)
+* Fix docs app demo iframe assets by [@jlowin](https://github.com/jlowin) in [#4194](https://github.com/PrefectHQ/fastmcp/pull/4194)
+* Guard require-issue-link check job to pull_request_target events by [@jlowin](https://github.com/jlowin) in [#4209](https://github.com/PrefectHQ/fastmcp/pull/4209)
+* Migrate auth JWTs to joserfc by [@jlowin](https://github.com/jlowin) in [#4221](https://github.com/PrefectHQ/fastmcp/pull/4221)
+* Skip published docs update for prereleases by [@jlowin](https://github.com/jlowin) in [#4224](https://github.com/PrefectHQ/fastmcp/pull/4224)
+* Surface proxy upstream failures by [@jlowin](https://github.com/jlowin) in [#4227](https://github.com/PrefectHQ/fastmcp/pull/4227)
+* Close upstream OAuth clients by [@jlowin](https://github.com/jlowin) in [#4248](https://github.com/PrefectHQ/fastmcp/pull/4248)
+* Fix GitHub MCP resource integration test by [@jlowin](https://github.com/jlowin) in [#4253](https://github.com/PrefectHQ/fastmcp/pull/4253)
+* Fix resource templates with query params on proxied servers by [@rene84](https://github.com/rene84) in [#4251](https://github.com/PrefectHQ/fastmcp/pull/4251)
+### Docs 📚
+* Document pip upgrade recovery for the fastmcp-slim package split by [@jlowin](https://github.com/jlowin) in [#4215](https://github.com/PrefectHQ/fastmcp/pull/4215)
+* Move pip upgrade recovery into a Troubleshooting section by [@jlowin](https://github.com/jlowin) in [#4219](https://github.com/PrefectHQ/fastmcp/pull/4219)
+* Restore Horizon docs banner by [@jlowin](https://github.com/jlowin) in [#4240](https://github.com/PrefectHQ/fastmcp/pull/4240)
+* fix: Trendshift link and badge in README.md by [@bhantos](https://github.com/bhantos) in [#4236](https://github.com/PrefectHQ/fastmcp/pull/4236)
+* docs: add tool fingerprinting recipe by [@dgenio](https://github.com/dgenio) in [#4233](https://github.com/PrefectHQ/fastmcp/pull/4233)
+### Dependencies 📦
+* chore(deps): bump the uv group across 2 directories with 1 update by [@dependabot](https://github.com/dependabot) in [#4113](https://github.com/PrefectHQ/fastmcp/pull/4113)
+* chore(deps-dev): bump pydantic-monty from 0.0.16 to 0.0.17 by [@dependabot](https://github.com/dependabot) in [#4023](https://github.com/PrefectHQ/fastmcp/pull/4023)
+### Other Changes 🦾
+* Exempt maintainers from MRE auto-close by [@jlowin](https://github.com/jlowin) in [#4220](https://github.com/PrefectHQ/fastmcp/pull/4220)
+
+## New Contributors
+* @pragnyanramtha made their first contribution in [#4164](https://github.com/PrefectHQ/fastmcp/pull/4164)
+* @yuyua9 made their first contribution in [#4178](https://github.com/PrefectHQ/fastmcp/pull/4178)
+* @tiagoskaneta made their first contribution in [#4135](https://github.com/PrefectHQ/fastmcp/pull/4135)
+* @mohankumarelec made their first contribution in [#4142](https://github.com/PrefectHQ/fastmcp/pull/4142)
+* @rgillinlz made their first contribution in [#4130](https://github.com/PrefectHQ/fastmcp/pull/4130)
+* @jpr5 made their first contribution in [#4183](https://github.com/PrefectHQ/fastmcp/pull/4183)
+* @bhantos made their first contribution in [#4236](https://github.com/PrefectHQ/fastmcp/pull/4236)
+* @rene84 made their first contribution in [#4251](https://github.com/PrefectHQ/fastmcp/pull/4251)
+
+**Full Changelog**: [v3.3.1...v3.4.0](https://github.com/PrefectHQ/fastmcp/compare/v3.3.1...v3.4.0)
+
+</Update>
+
+<Update label="v3.3.1" description="2026-05-15">
+
+**[v3.3.1: Loop There It Is](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.3.1)**
+
+A hotfix for the 3.3 packaging split. Clean installs could fail on standalone component imports like `from fastmcp.tools import tool`, because component modules reached auth and task primitives through `fastmcp.server` and pulled in the full server/provider stack. Those primitives now live in lightweight utility modules, with the old server import paths preserved as compatibility re-exports.
+
+### Fixes 🐞
+* fix(docs): use valid FA icon on client-only package page by [@jlowin](https://github.com/jlowin) in [#4139](https://github.com/PrefectHQ/fastmcp/pull/4139)
+* Decouple component imports from server by [@jlowin](https://github.com/jlowin) in [#4150](https://github.com/PrefectHQ/fastmcp/pull/4150)
+
+
+**Full Changelog**: [v3.3.0...v3.3.1](https://github.com/PrefectHQ/fastmcp/compare/v3.3.0...v3.3.1)
+
+</Update>
+
+<Update label="v3.3.0" description="2026-05-15">
+
+**[v3.3.0: Slim Reaper](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.3.0)**
+
+FastMCP 3.3 ships `fastmcp-slim`, a dependency-light distribution that separates the client from the server stack — install FastMCP's client and transport layer without Starlette, Uvicorn, or the rest of the server machinery. The import namespace is unchanged. It also closes out a backlog of OAuth proxy security hardening, MCP-compliant OTEL instrumentation, and auth additions that accumulated through the 3.2 cycle.
+
+### New Features 🎉
+* Add fastmcp-slim for client-only installs by [@jlowin](https://github.com/jlowin) in [#4122](https://github.com/PrefectHQ/fastmcp/pull/4122)
+### Enhancements ✨
+* Add default prefill to FormInput.collect_input by [@jlowin](https://github.com/jlowin) in [#3937](https://github.com/PrefectHQ/fastmcp/pull/3937)
+* OTEL: Fix attribute compliance with MCP semantic conventions by [@strawgate](https://github.com/strawgate) in [#3889](https://github.com/PrefectHQ/fastmcp/pull/3889)
+* OTEL: Instrument all MCP list operations and enrich delegate spans by [@strawgate](https://github.com/strawgate) in [#3890](https://github.com/PrefectHQ/fastmcp/pull/3890)
+* Improve real-world schema crash test: failure dump, cluster analysis, TypeErrors baseline ratchet by [@jlowin](https://github.com/jlowin) in [#3958](https://github.com/PrefectHQ/fastmcp/pull/3958)
+* feat: add AzureB2CProvider for Azure AD B2C user flows by [@carlos-rian](https://github.com/carlos-rian) in [#3995](https://github.com/PrefectHQ/fastmcp/pull/3995)
+* Add run_in_thread opt-out for sync tools with thread affinity by [@jlowin](https://github.com/jlowin) in [#4010](https://github.com/PrefectHQ/fastmcp/pull/4010)
+* Add missing return type annotation to __getattr__ by [@ZLeventer](https://github.com/ZLeventer) in [#4026](https://github.com/PrefectHQ/fastmcp/pull/4026)
+* Add experimental_capabilities kwarg to FastMCP constructor by [@jlowin](https://github.com/jlowin) in [#4042](https://github.com/PrefectHQ/fastmcp/pull/4042)
+* Add log_level parameter to FastMCP errors by [@daniel-tsiang](https://github.com/daniel-tsiang) in [#4036](https://github.com/PrefectHQ/fastmcp/pull/4036)
+* Bump pydocket to 0.20.0 by [@chrisguidry](https://github.com/chrisguidry) in [#4031](https://github.com/PrefectHQ/fastmcp/pull/4031)
+* enh: Add public API for updating OAuthProxy scopes after initialization by [@taylorwilsdon](https://github.com/taylorwilsdon) in [#4091](https://github.com/PrefectHQ/fastmcp/pull/4091)
+* Refine fastmcp-slim packaging by [@jlowin](https://github.com/jlowin) in [#4125](https://github.com/PrefectHQ/fastmcp/pull/4125)
+### Security 🔒
+* Harden OAuth Proxy silent consent against AS-in-the-middle by [@jlowin](https://github.com/jlowin) in [#3960](https://github.com/PrefectHQ/fastmcp/pull/3960)
+* Reject dot-segments in redirect URI allowlist matching by [@jlowin](https://github.com/jlowin) in [#3963](https://github.com/PrefectHQ/fastmcp/pull/3963)
+* Bump deps with open dependabot alerts by [@jlowin](https://github.com/jlowin) in [#3965](https://github.com/PrefectHQ/fastmcp/pull/3965)
+* Partition ResponseCachingMiddleware cache by access token by [@jlowin](https://github.com/jlowin) in [#4041](https://github.com/PrefectHQ/fastmcp/pull/4041)
+### Fixes 🐞
+* fix: reject self-mount to prevent infinite recursion by [@strawgate](https://github.com/strawgate) in [#3925](https://github.com/PrefectHQ/fastmcp/pull/3925)
+* fix: ProxyTool crashes on non-TextContent error responses by [@strawgate](https://github.com/strawgate) in [#3926](https://github.com/PrefectHQ/fastmcp/pull/3926)
+* fix: _prune_param and _convert_nullable_field mutate input schemas by [@strawgate](https://github.com/strawgate) in [#3927](https://github.com/PrefectHQ/fastmcp/pull/3927)
+* fix: narrow OpenAI audio format dict to Literal for ty by [@jlowin](https://github.com/jlowin) in [#3936](https://github.com/PrefectHQ/fastmcp/pull/3936)
+* fix: allow hyphens in resource template parameter names by [@strawgate](https://github.com/strawgate) in [#3929](https://github.com/PrefectHQ/fastmcp/pull/3929)
+* fix: OpenAPI request director sends multipart and form-urlencoded as JSON by [@strawgate](https://github.com/strawgate) in [#3932](https://github.com/PrefectHQ/fastmcp/pull/3932)
+* Fix raise_on_error handling for tool tasks by [@gnanirahulnutakki](https://github.com/gnanirahulnutakki) in [#3946](https://github.com/PrefectHQ/fastmcp/pull/3946)
+* fix: FileSystemProvider reload race condition by [@strawgate](https://github.com/strawgate) in [#3938](https://github.com/PrefectHQ/fastmcp/pull/3938)
+* fix tests that relied on task=True returning error results by [@jlowin](https://github.com/jlowin) in [#3954](https://github.com/PrefectHQ/fastmcp/pull/3954)
+* Restore task snapshot via a worker-level dependency by [@chrisguidry](https://github.com/chrisguidry) in [#3945](https://github.com/PrefectHQ/fastmcp/pull/3945)
+* Forward backend capabilities in ProxyProvider by [@jlowin](https://github.com/jlowin) in [#3956](https://github.com/PrefectHQ/fastmcp/pull/3956)
+* Allow upstream client_id to be used directly without DCR by [@jlowin](https://github.com/jlowin) in [#3957](https://github.com/PrefectHQ/fastmcp/pull/3957)
+* Graceful fallback for unsupported regex patterns in json_schema_to_type by [@jlowin](https://github.com/jlowin) in [#3959](https://github.com/PrefectHQ/fastmcp/pull/3959)
+* Revert "Forward backend capabilities in ProxyProvider (#3956)" by [@jlowin](https://github.com/jlowin) in [#3964](https://github.com/PrefectHQ/fastmcp/pull/3964)
+* fix: skip stdio subprocess test on Windows CI by [@jlowin](https://github.com/jlowin) in [#3966](https://github.com/PrefectHQ/fastmcp/pull/3966)
+* fix: bound _refresh_locks with LRU eviction to prevent memory leak by [@jlowin](https://github.com/jlowin) in [#3968](https://github.com/PrefectHQ/fastmcp/pull/3968)
+* fix: handle circular JSON Pointer $ref in dereference_refs by [@lawrence3699](https://github.com/lawrence3699) in [#3896](https://github.com/PrefectHQ/fastmcp/pull/3896)
+* fix: honor upstream refresh token expiry in OAuthProxy by [@jlowin](https://github.com/jlowin) in [#3990](https://github.com/PrefectHQ/fastmcp/pull/3990)
+* fix: narrow _token_validator with isinstance for ty in AzureProvider.from_b2c by [@jlowin](https://github.com/jlowin) in [#4007](https://github.com/PrefectHQ/fastmcp/pull/4007)
+* fix: cancel orphaned session_task when Client._disconnect times out by [@jlowin](https://github.com/jlowin) in [#4011](https://github.com/PrefectHQ/fastmcp/pull/4011)
+* fix: preserve @tool metadata in from_function by [@lawrence3699](https://github.com/lawrence3699) in [#4072](https://github.com/PrefectHQ/fastmcp/pull/4072)
+* fix(openapi): keep blank values in parse_qs (refs #4056) by [@MukundaKatta](https://github.com/MukundaKatta) in [#4076](https://github.com/PrefectHQ/fastmcp/pull/4076)
+* Fix #4056: keep blank query values, add token bucket regression test by [@MukundaKatta](https://github.com/MukundaKatta) in [#4069](https://github.com/PrefectHQ/fastmcp/pull/4069)
+* fix(ping): exit ping loop cleanly when session stream is closed by [@ashwin153](https://github.com/ashwin153) in [#4087](https://github.com/PrefectHQ/fastmcp/pull/4087)
+* Fix sampling from background tasks by [@cuyua9](https://github.com/cuyua9) in [#4068](https://github.com/PrefectHQ/fastmcp/pull/4068)
+* Make Docket reentrant; mounted servers enter their own lifespan by [@jlowin](https://github.com/jlowin) in [#4095](https://github.com/PrefectHQ/fastmcp/pull/4095)
+* fix(tool_transform): hoist $defs to schema root when ArgTransform introduces them by [@SarthakB11](https://github.com/SarthakB11) in [#4101](https://github.com/PrefectHQ/fastmcp/pull/4101)
+* fix(auth): silence authlib.jose DeprecationWarning at JWT import by [@SarthakB11](https://github.com/SarthakB11) in [#4100](https://github.com/PrefectHQ/fastmcp/pull/4100)
+* fix: don't cache import map in dev apps bundle by [@jlowin](https://github.com/jlowin) in [#4106](https://github.com/PrefectHQ/fastmcp/pull/4106)
+* #4084 [Issues] Windows startup crash due to UnicodeDecodeError when l… by [@doneman536](https://github.com/doneman536) in [#4092](https://github.com/PrefectHQ/fastmcp/pull/4092)
+* fix: drop exc_info for expected tool failures, remove unreachable ValidationError by [@sergeykad](https://github.com/sergeykad) in [#4029](https://github.com/PrefectHQ/fastmcp/pull/4029)
+* fix: cli option --no-banner is NOT passed to cli but server-spec in-correctly when cli --reload option is specified. by [@itaru2622](https://github.com/itaru2622) in [#4083](https://github.com/PrefectHQ/fastmcp/pull/4083)
+* Fix None backend_* span attributes on un-renamed proxy components by [@ringerc](https://github.com/ringerc) in [#4109](https://github.com/PrefectHQ/fastmcp/pull/4109)
+* Fix OCI Provider issue in 3.x version. Add OCI auth provider example … by [@kiranthakkar](https://github.com/kiranthakkar) in [#4116](https://github.com/PrefectHQ/fastmcp/pull/4116)
+* fix(http): terminate active streamable-HTTP transports before lifespan shutdown by [@SarthakB11](https://github.com/SarthakB11) in [#4118](https://github.com/PrefectHQ/fastmcp/pull/4118)
+### Docs 📚
+* Restructure docs navigation by [@jlowin](https://github.com/jlowin) in [#3951](https://github.com/PrefectHQ/fastmcp/pull/3951)
+* docs: standardize ToolAnnotations examples by [@gnanirahulnutakki](https://github.com/gnanirahulnutakki) in [#3952](https://github.com/PrefectHQ/fastmcp/pull/3952)
+* Be constructively skeptical of bot reviews on own PRs by [@jlowin](https://github.com/jlowin) in [#3971](https://github.com/PrefectHQ/fastmcp/pull/3971)
+* Add UTM params to Horizon docs links by [@aaazzam](https://github.com/aaazzam) in [#4018](https://github.com/PrefectHQ/fastmcp/pull/4018)
+* Add a sandboxed-agents deployment guide by [@strawgate](https://github.com/strawgate) in [#4027](https://github.com/PrefectHQ/fastmcp/pull/4027)
+* docs: add best practices for custom telemetry spans by [@MukundaKatta](https://github.com/MukundaKatta) in [#4001](https://github.com/PrefectHQ/fastmcp/pull/4001)
+* Refresh landing page copy by [@jlowin](https://github.com/jlowin) in [#4043](https://github.com/PrefectHQ/fastmcp/pull/4043)
+* Refresh landing page copy by [@jlowin](https://github.com/jlowin) in [#4047](https://github.com/PrefectHQ/fastmcp/pull/4047)
+* Add UTM tracking to Horizon links by [@jlowin](https://github.com/jlowin) in [#4064](https://github.com/PrefectHQ/fastmcp/pull/4064)
+* docs(integrations): add Pydantic AI FastMCP toolset guide by [@MukundaKatta](https://github.com/MukundaKatta) in [#4070](https://github.com/PrefectHQ/fastmcp/pull/4070)
+* docs: fix broken links in Pydantic AI guide by [@jlowin](https://github.com/jlowin) in [#4094](https://github.com/PrefectHQ/fastmcp/pull/4094)
+### Dependencies 📦
+* chore(deps-dev): bump pydantic-monty from 0.0.11 to 0.0.12 by [@dependabot](https://github.com/dependabot) in [#3940](https://github.com/PrefectHQ/fastmcp/pull/3940)
+* chore(deps-dev): bump pydantic-monty from 0.0.14 to 0.0.16 by [@dependabot](https://github.com/dependabot) in [#3984](https://github.com/PrefectHQ/fastmcp/pull/3984)
+### Other Changes 🦾
+* fix: Don't completely hide plain mcp.tool app-only tools by [@owtaylor](https://github.com/owtaylor) in [#4112](https://github.com/PrefectHQ/fastmcp/pull/4112)
+
+## New Contributors
+* @gnanirahulnutakki made their first contribution in [#3946](https://github.com/PrefectHQ/fastmcp/pull/3946)
+* @lawrence3699 made their first contribution in [#3896](https://github.com/PrefectHQ/fastmcp/pull/3896)
+* @carlos-rian made their first contribution in [#3995](https://github.com/PrefectHQ/fastmcp/pull/3995)
+* @ZLeventer made their first contribution in [#4026](https://github.com/PrefectHQ/fastmcp/pull/4026)
+* @MukundaKatta made their first contribution in [#4001](https://github.com/PrefectHQ/fastmcp/pull/4001)
+* @daniel-tsiang made their first contribution in [#4036](https://github.com/PrefectHQ/fastmcp/pull/4036)
+* @ashwin153 made their first contribution in [#4087](https://github.com/PrefectHQ/fastmcp/pull/4087)
+* @cuyua9 made their first contribution in [#4068](https://github.com/PrefectHQ/fastmcp/pull/4068)
+* @taylorwilsdon made their first contribution in [#4091](https://github.com/PrefectHQ/fastmcp/pull/4091)
+* @SarthakB11 made their first contribution in [#4101](https://github.com/PrefectHQ/fastmcp/pull/4101)
+* @doneman536 made their first contribution in [#4092](https://github.com/PrefectHQ/fastmcp/pull/4092)
+* @sergeykad made their first contribution in [#4029](https://github.com/PrefectHQ/fastmcp/pull/4029)
+* @ringerc made their first contribution in [#4109](https://github.com/PrefectHQ/fastmcp/pull/4109)
+
+**Full Changelog**: [v3.2.4...v3.3.0](https://github.com/PrefectHQ/fastmcp/compare/v3.2.4...v3.3.0)
+
+</Update>
+
+<Update label="v3.2.4" description="2026-04-14">
+
+**[v3.2.4: Patch Me If You Can](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.2.4)**
+
+A grab bag of fixes, hardening, and polish. The headline behavior change: background tasks are now scoped to the authorization context rather than the MCP session, so a task survives session churn and stays tied to who started it — a breaking change for anyone relying on the old session-scoped semantics. Plus actual-size validation in `FileUpload`, a Keycloak OAuth provider, automatic parameter descriptions from docstrings, and dozens of schema and sampling fixes.
+
+### Breaking Changes ⚠️
+* Scope tasks to authorization context, not session by [@chrisguidry](https://github.com/chrisguidry) in [#3800](https://github.com/PrefectHQ/fastmcp/pull/3800)
+### Enhancements ✨
+* Bump pydocket>=0.19.0, drop fakeredis pin by [@chrisguidry](https://github.com/chrisguidry) in [#3822](https://github.com/PrefectHQ/fastmcp/pull/3822)
+* Add real-world schema crash test (232K schemas from APIs.guru) by [@strawgate](https://github.com/strawgate) in [#3826](https://github.com/PrefectHQ/fastmcp/pull/3826)
+* Enable 7 zero-violation ruff rules by [@strawgate](https://github.com/strawgate) in [#3841](https://github.com/PrefectHQ/fastmcp/pull/3841)
+* Promote 7 ty rules from ignore to warn by [@strawgate](https://github.com/strawgate) in [#3852](https://github.com/PrefectHQ/fastmcp/pull/3852)
+* Replace ___ with hash-based backend tool routing and per-tool prefab resources by [@jlowin](https://github.com/jlowin) in [#3824](https://github.com/PrefectHQ/fastmcp/pull/3824)
+* Enable 4 ruff rules (DTZ, ERA, ISC, INP) and fix 9 violations by [@strawgate](https://github.com/strawgate) in [#3842](https://github.com/PrefectHQ/fastmcp/pull/3842)
+* Extract parameter descriptions from docstrings by [@jlowin](https://github.com/jlowin) in [#3872](https://github.com/PrefectHQ/fastmcp/pull/3872)
+* ci: speed up schema crash test (CSafeLoader + xdist-safe aggregation) by [@jlowin](https://github.com/jlowin) in [#3873](https://github.com/PrefectHQ/fastmcp/pull/3873)
+* test: bump OpenAPI init perf threshold to 200ms for Windows CI by [@jlowin](https://github.com/jlowin) in [#3879](https://github.com/PrefectHQ/fastmcp/pull/3879)
+* refactor: unify object-schema conversion through _object_schema_to_type by [@jlowin](https://github.com/jlowin) in [#3884](https://github.com/PrefectHQ/fastmcp/pull/3884)
+* Add Keycloak OAuth Provider for Enterprise Authentication and local dev by [@stephaneberle9](https://github.com/stephaneberle9) in [#1937](https://github.com/PrefectHQ/fastmcp/pull/1937)
+* Allow auth providers to override protected resource base URLs by [@aaazzam](https://github.com/aaazzam) in [#3900](https://github.com/PrefectHQ/fastmcp/pull/3900)
+* Enable PERF and T20 ruff rules by [@strawgate](https://github.com/strawgate) in [#3845](https://github.com/PrefectHQ/fastmcp/pull/3845)
+* Add response_title and response_description to ctx.elicit() by [@jlowin](https://github.com/jlowin) in [#3912](https://github.com/PrefectHQ/fastmcp/pull/3912)
+* Deprecate ctx.elicit() without response_type by [@jlowin](https://github.com/jlowin) in [#3916](https://github.com/PrefectHQ/fastmcp/pull/3916)
+### Security 🔒
+* Validate actual base64 data size in FileUpload, not client-reported size by [@strawgate](https://github.com/strawgate) in [#3816](https://github.com/PrefectHQ/fastmcp/pull/3816)
+* Stop forwarding inbound HTTP headers to unrelated remote servers by [@jlowin](https://github.com/jlowin) in [#3837](https://github.com/PrefectHQ/fastmcp/pull/3837)
+* AuthKit: auto-bind token audience to resource URL (RFC 8707) by [@jlowin](https://github.com/jlowin) in [#3905](https://github.com/PrefectHQ/fastmcp/pull/3905)
+### Fixes 🐞
+* Version-check is_docket_available() to avoid transitive pydocket crash by [@jlowin](https://github.com/jlowin) in [#3807](https://github.com/PrefectHQ/fastmcp/pull/3807)
+* fix: materialize generators before result conversion, handle bytes gracefully by [@strawgate](https://github.com/strawgate) in [#3830](https://github.com/PrefectHQ/fastmcp/pull/3830)
+* Fix json_schema_to_type crashes on keywords, boolean schemas, empty enums, and name collisions by [@strawgate](https://github.com/strawgate) in [#3818](https://github.com/PrefectHQ/fastmcp/pull/3818)
+* fix: replace `or` with `is not None` checks for config/override merging by [@strawgate](https://github.com/strawgate) in [#3833](https://github.com/PrefectHQ/fastmcp/pull/3833)
+* fix: TransformedTool sync fn crash and schema mutation by [@strawgate](https://github.com/strawgate) in [#3823](https://github.com/PrefectHQ/fastmcp/pull/3823)
+* fix: cross-provider duplicate detection, error visibility, mask propagation by [@strawgate](https://github.com/strawgate) in [#3827](https://github.com/PrefectHQ/fastmcp/pull/3827)
+* fix: don't pass HTTP kwargs when transport is unspecified by [@strawgate](https://github.com/strawgate) in [#3838](https://github.com/PrefectHQ/fastmcp/pull/3838)
+* fix: strip title fields from tool schemas for Gemini 2.5 Flash compatibility by [@strawgate](https://github.com/strawgate) in [#3861](https://github.com/PrefectHQ/fastmcp/pull/3861)
+* fix: retry when LLM returns text instead of calling final_response by [@strawgate](https://github.com/strawgate) in [#3850](https://github.com/PrefectHQ/fastmcp/pull/3850)
+* Raise on unhandled content types in sampling handler dispatch chains by [@strawgate](https://github.com/strawgate) in [#3857](https://github.com/PrefectHQ/fastmcp/pull/3857)
+* Fix broken code examples in docs by [@strawgate](https://github.com/strawgate) in [#3869](https://github.com/PrefectHQ/fastmcp/pull/3869)
+* fix: GoogleGenaiSamplingHandler leaks thought parts and gives unhelpful errors on empty responses by [@strawgate](https://github.com/strawgate) in [#3849](https://github.com/PrefectHQ/fastmcp/pull/3849)
+* fix: cap consecutive final_response validation retries by [@strawgate](https://github.com/strawgate) in [#3851](https://github.com/PrefectHQ/fastmcp/pull/3851)
+* Fix test quality issues by [@strawgate](https://github.com/strawgate) in [#3854](https://github.com/PrefectHQ/fastmcp/pull/3854)
+* Fix MCP tool on docs welcome page by [@lkiesow](https://github.com/lkiesow) in [#3874](https://github.com/PrefectHQ/fastmcp/pull/3874)
+* Fix CIMD clients getting required_scopes instead of valid_scopes by [@jlowin](https://github.com/jlowin) in [#3836](https://github.com/PrefectHQ/fastmcp/pull/3836)
+* Rename filesystem-provider example dir to avoid mcp/ collision by [@jlowin](https://github.com/jlowin) in [#3878](https://github.com/PrefectHQ/fastmcp/pull/3878)
+* fix: drop configurable dedupe from AggregateProvider, always warn by [@jlowin](https://github.com/jlowin) in [#3877](https://github.com/PrefectHQ/fastmcp/pull/3877)
+* fix: resolve list[dict] return type producing Root() instead of dicts by [@KeWang0622](https://github.com/KeWang0622) in [#3880](https://github.com/PrefectHQ/fastmcp/pull/3880)
+* fix: strip titles from bare-metadata nodes (Gemini 2.5 Flash) by [@jlowin](https://github.com/jlowin) in [#3881](https://github.com/PrefectHQ/fastmcp/pull/3881)
+* Fix wildcard resource template params in mounted servers by [@jlowin](https://github.com/jlowin) in [#3899](https://github.com/PrefectHQ/fastmcp/pull/3899)
+* Harden forced client disconnect cleanup by [@vonbai](https://github.com/vonbai) in [#3885](https://github.com/PrefectHQ/fastmcp/pull/3885)
+* fix: elicitation scalar return, resource auto-serialization, Client.new() state, prompt errors by [@strawgate](https://github.com/strawgate) in [#3859](https://github.com/PrefectHQ/fastmcp/pull/3859)
+* fix: task.wait() hangs indefinitely when task enters input_required by [@mrishav](https://github.com/mrishav) in [#3798](https://github.com/PrefectHQ/fastmcp/pull/3798)
+* Fix RetryMiddleware not retrying tool errors by [@strawgate](https://github.com/strawgate) in [#3858](https://github.com/PrefectHQ/fastmcp/pull/3858)
+* Stop pydantic 2.13 from leaking _WrappedResult docstring into tool output schemas by [@jlowin](https://github.com/jlowin) in [#3918](https://github.com/PrefectHQ/fastmcp/pull/3918)
+### Docs 📚
+* Note generate-notes API in release workflow docs by [@jlowin](https://github.com/jlowin) in [#3806](https://github.com/PrefectHQ/fastmcp/pull/3806)
+* docs: require agents to respect DNM markers on PRs by [@jlowin](https://github.com/jlowin) in [#3871](https://github.com/PrefectHQ/fastmcp/pull/3871)
+* docs: add uv-managed dependencies and uvx examples to mcp-json configuration by [@vincent067](https://github.com/vincent067) in [#3843](https://github.com/PrefectHQ/fastmcp/pull/3843)
+* docs: link fastmcp-keycloak-local companion project from Keycloak integration page by [@stephaneberle9](https://github.com/stephaneberle9) in [#3904](https://github.com/PrefectHQ/fastmcp/pull/3904)
+* Overhaul apps docs by [@jlowin](https://github.com/jlowin) in [#3915](https://github.com/PrefectHQ/fastmcp/pull/3915)
+### Dependencies 📦
+* chore(deps): bump extractions/setup-just from 3 to 4 by [@dependabot](https://github.com/dependabot) in [#3863](https://github.com/PrefectHQ/fastmcp/pull/3863)
+* chore(deps): bump astral-sh/setup-uv from 6 to 7 by [@dependabot](https://github.com/dependabot) in [#3865](https://github.com/PrefectHQ/fastmcp/pull/3865)
+* chore(deps): bump actions/checkout from 4 to 6 by [@dependabot](https://github.com/dependabot) in [#3864](https://github.com/PrefectHQ/fastmcp/pull/3864)
+* chore(deps-dev): bump pydantic-monty from 0.0.9 to 0.0.10 by [@dependabot](https://github.com/dependabot) in [#3809](https://github.com/PrefectHQ/fastmcp/pull/3809)
+* chore(deps): bump the uv group across 2 directories with 1 update by [@dependabot](https://github.com/dependabot) in [#3913](https://github.com/PrefectHQ/fastmcp/pull/3913)
+
+## New Contributors
+* @lkiesow made their first contribution in [#3874](https://github.com/PrefectHQ/fastmcp/pull/3874)
+* @KeWang0622 made their first contribution in [#3880](https://github.com/PrefectHQ/fastmcp/pull/3880)
+* @vonbai made their first contribution in [#3885](https://github.com/PrefectHQ/fastmcp/pull/3885)
+
+**Full Changelog**: [v3.2.3...v3.2.4](https://github.com/PrefectHQ/fastmcp/compare/v3.2.3...v3.2.4)
+
+</Update>
+
+<Update label="v3.2.3" description="2026-04-09">
+
+**[v3.2.3: Redis or Not](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.2.3)**
+
+A stopgap pin: fakeredis 2.35.0 shipped an undocumented rename that broke pydocket's `memory://` backend, causing `fastmcp[tasks]` installs to fail at startup with an `ImportError`. This pins `fakeredis<2.35.0` in the `tasks` extra until a fixed pydocket ships.
+
+### Fixes 🐞
+* Pin `fakeredis<2.35.0` in tasks extra by [@jlowin](https://github.com/jlowin) in [#3804](https://github.com/PrefectHQ/fastmcp/pull/3804)
+### Docs 📚
+* Document session state isolation across mount boundaries by [@jlowin](https://github.com/jlowin) in [#3801](https://github.com/PrefectHQ/fastmcp/pull/3801)
+
+
+**Full Changelog**: [v3.2.2...v3.2.3](https://github.com/PrefectHQ/fastmcp/compare/v3.2.2...v3.2.3)
+
+</Update>
+
+<Update label="v3.2.2" description="2026-04-09">
+
+**[v3.2.2: Audience Appreciation](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.2.2)**
+
+Fixes the Azure audience regression from 3.2.1: validation switched from `client_id` to `identifier_uri`, which fixed custom Application ID URIs but broke the default case where Azure AD v2 tokens set `aud` to the bare client ID GUID. Both formats are now accepted.
+
+### Fixes 🐞
+* fix: accept both client_id and identifier_uri as Azure audience by [@jlowin](https://github.com/jlowin) in [#3797](https://github.com/PrefectHQ/fastmcp/pull/3797)
+### Dependencies 📦
+* chore(deps): bump the uv group across 2 directories with 1 update by [@dependabot](https://github.com/dependabot) in [#3795](https://github.com/PrefectHQ/fastmcp/pull/3795)
+
+
+**Full Changelog**: [v3.2.1...v3.2.2](https://github.com/PrefectHQ/fastmcp/compare/v3.2.1...v3.2.2)
+
+</Update>
+
+<Update label="v3.2.1" description="2026-04-08">
+
+**[v3.2.1: Audience Participation](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.2.1)**
+
+A patch focused on auth-provider audience validation. Cognito tokens now validate on `client_id` (they carry no `aud`), Azure honors the `identifier_uri` parameter for Entra v2.0 tokens, and consent cookies are LRU-capped to prevent unbounded growth past reverse proxy header limits. Also fixes OpenAPI 3.0 `nullable` fields leaking into tool input schemas and server-variable substitution in base URLs.
+
+### Breaking Changes ⚠️
+* fix(google): use sub (user ID) for client_id instead of aud (app ID) by [@shigechika](https://github.com/shigechika) in [#3722](https://github.com/PrefectHQ/fastmcp/pull/3722)
+* fix: remove CSP from tool metadata, keep on resource only by [@jlowin](https://github.com/jlowin) in [#3754](https://github.com/PrefectHQ/fastmcp/pull/3754)
+### Enhancements ✨
+* [codex] Add FastMCP docs telemetry by [@aaazzam](https://github.com/aaazzam) in [#3727](https://github.com/PrefectHQ/fastmcp/pull/3727)
+* chore: split SDK navigation into standalone $ref file by [@jlowin](https://github.com/jlowin) in [#3773](https://github.com/PrefectHQ/fastmcp/pull/3773)
+* fix: bump ty to >=0.0.29 and suppress new false positives by [@jlowin](https://github.com/jlowin) in [#3790](https://github.com/PrefectHQ/fastmcp/pull/3790)
+### Fixes 🐞
+* fix: use explicit None checks for JWT exp validation by [@jlowin](https://github.com/jlowin) in [#3724](https://github.com/PrefectHQ/fastmcp/pull/3724)
+* Unify background task context forwarding, fix concurrent dependency bugs by [@chrisguidry](https://github.com/chrisguidry) in [#3710](https://github.com/PrefectHQ/fastmcp/pull/3710)
+* fix: add proxy timeouts and modernize networking in apps dev by [@mateeaaa](https://github.com/mateeaaa) in [#3741](https://github.com/PrefectHQ/fastmcp/pull/3741)
+* fix: ResponseLimitingMiddleware no longer breaks outputSchema tools by [@jlowin](https://github.com/jlowin) in [#3756](https://github.com/PrefectHQ/fastmcp/pull/3756)
+* fix: substitute server variable defaults when building base URL from OpenAPI spec by [@mrishav](https://github.com/mrishav) in [#3770](https://github.com/PrefectHQ/fastmcp/pull/3770)
+* fix: FastAPI TestClient compatibility and lifespan re-initialization by [@kvdhanush06](https://github.com/kvdhanush06) in [#3736](https://github.com/PrefectHQ/fastmcp/pull/3736)
+* fix: propagate upstream_claims in load_access_token by [@kvdhanush06](https://github.com/kvdhanush06) in [#3750](https://github.com/PrefectHQ/fastmcp/pull/3750)
+* Remove deprecated asyncio.iscoroutinefunction fallback by [@kaiisfree](https://github.com/kaiisfree) in [#3767](https://github.com/PrefectHQ/fastmcp/pull/3767)
+* fix: changeable allowed_client_redirect_uris on OAuthProxy by [@fengarix](https://github.com/fengarix) in [#3772](https://github.com/PrefectHQ/fastmcp/pull/3772)
+* fix: broken link in changelog by [@jlowin](https://github.com/jlowin) in [#3775](https://github.com/PrefectHQ/fastmcp/pull/3775)
+* fix(docs): correct FastMCP tool name in welcome docs by [@buyua9](https://github.com/buyua9) in [#3781](https://github.com/PrefectHQ/fastmcp/pull/3781)
+* fix: cap consent cookie size to prevent header overflow by [@jlowin](https://github.com/jlowin) in [#3784](https://github.com/PrefectHQ/fastmcp/pull/3784)
+* Fix boolean property schemas in JSON Schema parsing by [@jlowin](https://github.com/jlowin) in [#3785](https://github.com/PrefectHQ/fastmcp/pull/3785)
+* Fix OpenAPI 3.0 nullable fields in tool input schemas by [@kvdhanush06](https://github.com/kvdhanush06) in [#3768](https://github.com/PrefectHQ/fastmcp/pull/3768)
+* fix: Cognito token verification checks client_id instead of aud by [@jlowin](https://github.com/jlowin) in [#3786](https://github.com/PrefectHQ/fastmcp/pull/3786)
+* fix: use identifier_uri as audience for Azure token validation by [@jlowin](https://github.com/jlowin) in [#3787](https://github.com/PrefectHQ/fastmcp/pull/3787)
+* Harden client tool result error handling by [@aimable100](https://github.com/aimable100) in [#3778](https://github.com/PrefectHQ/fastmcp/pull/3778)
+### Docs 📚
+* Github integraiton documentation fix: use result.data otherwise CallToolResult not scriptable by [@c4jquick](https://github.com/c4jquick) in [#3753](https://github.com/PrefectHQ/fastmcp/pull/3753)
+* chore: split v2 docs navigation into separate file by [@jlowin](https://github.com/jlowin) in [#3762](https://github.com/PrefectHQ/fastmcp/pull/3762)
+* docs: document forward_resource parameter on OAuthProxy by [@jlowin](https://github.com/jlowin) in [#3788](https://github.com/PrefectHQ/fastmcp/pull/3788)
+### Examples & Contrib 💡
+* fix: boolean false values dropped in form submissions by [@jlowin](https://github.com/jlowin) in [#3776](https://github.com/PrefectHQ/fastmcp/pull/3776)
+### Dependencies 📦
+* chore(deps): bump fastmcp from 3.1.1 to 3.2.0 in /examples/testing_demo in the uv group across 1 directory by [@dependabot](https://github.com/dependabot) in [#3728](https://github.com/PrefectHQ/fastmcp/pull/3728)
+* chore(deps): bump anthropic from 0.86.0 to 0.87.0 in the uv group across 1 directory by [@dependabot](https://github.com/dependabot) in [#3742](https://github.com/PrefectHQ/fastmcp/pull/3742)
+
+## New Contributors
+* @c4jquick made their first contribution in [#3753](https://github.com/PrefectHQ/fastmcp/pull/3753)
+* @mateeaaa made their first contribution in [#3741](https://github.com/PrefectHQ/fastmcp/pull/3741)
+* @mrishav made their first contribution in [#3770](https://github.com/PrefectHQ/fastmcp/pull/3770)
+* @kvdhanush06 made their first contribution in [#3736](https://github.com/PrefectHQ/fastmcp/pull/3736)
+* @kaiisfree made their first contribution in [#3767](https://github.com/PrefectHQ/fastmcp/pull/3767)
+* @fengarix made their first contribution in [#3772](https://github.com/PrefectHQ/fastmcp/pull/3772)
+* @buyua9 made their first contribution in [#3781](https://github.com/PrefectHQ/fastmcp/pull/3781)
+* @aimable100 made their first contribution in [#3778](https://github.com/PrefectHQ/fastmcp/pull/3778)
+
+**Full Changelog**: [v3.2.0...v3.2.1](https://github.com/PrefectHQ/fastmcp/compare/v3.2.0...v3.2.1)
+
+</Update>
+
+<Update label="v3.2.0" description="2026-03-30">
+
+**[v3.2.0: Show Don't Tool](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.2.0)**
+
+FastMCP 3.2 is the Apps release: your tools can now return interactive UIs — charts, dashboards, forms, maps — rendered right inside the conversation. `FastMCPApp` separates the tools the LLM sees from the backend tools the UI calls, five built-in providers (FileUpload, Approval, Choice, FormInput, GenerativeUI) cover common interaction patterns, and `fastmcp dev apps` gives you a browser preview. The release also lands a significant security hardening pass across SSRF/path-traversal, JWT algorithm restrictions, OAuth scope enforcement, and CSRF.
+
+### New Features 🎉
+* Add FastMCPApp — a Provider for composable MCP applications by [@jlowin](https://github.com/jlowin) in [#3385](https://github.com/PrefectHQ/fastmcp/pull/3385)
+* Add fastmcp dev apps command with browser UI preview by [@jlowin](https://github.com/jlowin) in [#3489](https://github.com/PrefectHQ/fastmcp/pull/3489)
+* Add GenerativeUI provider, bump prefab-ui 0.14.0 by [@jlowin](https://github.com/jlowin) in [#3647](https://github.com/PrefectHQ/fastmcp/pull/3647)
+* Add FileUpload provider by [@jlowin](https://github.com/jlowin) in [#3669](https://github.com/PrefectHQ/fastmcp/pull/3669)
+* Add Approval and Choice providers by [@jlowin](https://github.com/jlowin) in [#3686](https://github.com/PrefectHQ/fastmcp/pull/3686)
+* Add FormInput provider, bump prefab-ui to 0.15.0 by [@jlowin](https://github.com/jlowin) in [#3687](https://github.com/PrefectHQ/fastmcp/pull/3687)
+### Breaking Changes ⚠️
+* Route app tool calls via ___-prefixed names by [@jlowin](https://github.com/jlowin) in [#3667](https://github.com/PrefectHQ/fastmcp/pull/3667)
+### Enhancements ✨
+* feat: add `--config-path` flag to claude-desktop install command by [@Sumanshu-Nankana](https://github.com/Sumanshu-Nankana) in [#3380](https://github.com/PrefectHQ/fastmcp/pull/3380)
+* Support ImageContent and AudioContent in Message class by [@ericrobinson-indeed](https://github.com/ericrobinson-indeed) in [#3396](https://github.com/PrefectHQ/fastmcp/pull/3396)
+* Deprecate PromptToolMiddleware and ResourceToolMiddleware by [@jlowin](https://github.com/jlowin) in [#3389](https://github.com/PrefectHQ/fastmcp/pull/3389)
+* Block HS* algorithms when JWTVerifier is configured with JWKS by [@jlowin](https://github.com/jlowin) in [#3419](https://github.com/PrefectHQ/fastmcp/pull/3419)
+* Remove prek from Marvin workflows by [@jlowin](https://github.com/jlowin) in [#3444](https://github.com/PrefectHQ/fastmcp/pull/3444)
+* Add dependency version compatibility guidance to code-review skill by [@jlowin](https://github.com/jlowin) in [#3475](https://github.com/PrefectHQ/fastmcp/pull/3475)
+* Remove "good first issue" label by [@jlowin](https://github.com/jlowin) in [#3482](https://github.com/PrefectHQ/fastmcp/pull/3482)
+* Cache component lists in ProxyProvider by [@jlowin](https://github.com/jlowin) in [#3479](https://github.com/PrefectHQ/fastmcp/pull/3479)
+* Support logging/setLevel and add client_log_level by [@jlowin](https://github.com/jlowin) in [#3491](https://github.com/PrefectHQ/fastmcp/pull/3491)
+* Propagate x-fastmcp-wrap-result in tool result _meta by [@jlowin](https://github.com/jlowin) in [#3490](https://github.com/PrefectHQ/fastmcp/pull/3490)
+* feat(auth): add external_consent param to suppress misleading warning by [@mtthidoteu](https://github.com/mtthidoteu) in [#3473](https://github.com/PrefectHQ/fastmcp/pull/3473)
+* Add `verify` parameter for SSL certificate configuration by [@jlowin](https://github.com/jlowin) in [#3487](https://github.com/PrefectHQ/fastmcp/pull/3487)
+* Expose minimum_check_interval, reduce task pickup latency by [@jlowin](https://github.com/jlowin) in [#3500](https://github.com/PrefectHQ/fastmcp/pull/3500)
+* Fix test timeouts, suppress deprecation warnings, speed up auth tests by [@jlowin](https://github.com/jlowin) in [#3504](https://github.com/PrefectHQ/fastmcp/pull/3504)
+* Auto-close upgrade check issue when build passes by [@jlowin](https://github.com/jlowin) in [#3505](https://github.com/PrefectHQ/fastmcp/pull/3505)
+* feat: make upstream_client_secret optional in OAuthProxy by [@jlowin](https://github.com/jlowin) in [#3486](https://github.com/PrefectHQ/fastmcp/pull/3486)
+* Add security label to triage workflow and release notes by [@jlowin](https://github.com/jlowin) in [#3516](https://github.com/PrefectHQ/fastmcp/pull/3516)
+* Claude/review contributor guidelines by [@jlowin](https://github.com/jlowin) in [#3517](https://github.com/PrefectHQ/fastmcp/pull/3517)
+* pin pydantic-monty to 0.0.8 by [@jlowin](https://github.com/jlowin) in [#3539](https://github.com/PrefectHQ/fastmcp/pull/3539)
+* Support ImageContent and AudioContent in sampling handlers by [@jlowin](https://github.com/jlowin) in [#3550](https://github.com/PrefectHQ/fastmcp/pull/3550)
+* Graceful degradation for multi-server proxy setup by [@jlowin](https://github.com/jlowin) in [#3546](https://github.com/PrefectHQ/fastmcp/pull/3546)
+* Extract TokenCache utility, add caching to GitHubTokenVerifier by [@jlowin](https://github.com/jlowin) in [#3547](https://github.com/PrefectHQ/fastmcp/pull/3547)
+* Add review-pr skill for Codex bot workflow by [@jlowin](https://github.com/jlowin) in [#3552](https://github.com/PrefectHQ/fastmcp/pull/3552)
+* Add MCP message inspector to dev apps UI by [@jlowin](https://github.com/jlowin) in [#3570](https://github.com/PrefectHQ/fastmcp/pull/3570)
+* Comprehensive MCP Apps docs, string CallTool resolution by [@jlowin](https://github.com/jlowin) in [#3575](https://github.com/PrefectHQ/fastmcp/pull/3575)
+* Replace UUID global keys with (app_name, tool_name) registry by [@jlowin](https://github.com/jlowin) in [#3585](https://github.com/PrefectHQ/fastmcp/pull/3585)
+* Route app tool calls through provider chain by [@jlowin](https://github.com/jlowin) in [#3587](https://github.com/PrefectHQ/fastmcp/pull/3587)
+* Dev apps: show more/less for long tool descriptions by [@jlowin](https://github.com/jlowin) in [#3600](https://github.com/PrefectHQ/fastmcp/pull/3600)
+* Apps Phase 1: docs, examples, app-only tool filtering by [@jlowin](https://github.com/jlowin) in [#3593](https://github.com/PrefectHQ/fastmcp/pull/3593)
+* Forward enable_cimd to OAuthProxy in all provider subclasses by [@jlowin](https://github.com/jlowin) in [#3608](https://github.com/PrefectHQ/fastmcp/pull/3608)
+* Tune too-long triage heuristic by [@jlowin](https://github.com/jlowin) in [#3610](https://github.com/PrefectHQ/fastmcp/pull/3610)
+* Update ty ignore comments for 0.0.25 compatibility by [@jlowin](https://github.com/jlowin) in [#3614](https://github.com/PrefectHQ/fastmcp/pull/3614)
+* Move app modules to fastmcp.apps package by [@jlowin](https://github.com/jlowin) in [#3616](https://github.com/PrefectHQ/fastmcp/pull/3616)
+* Tighten too-long heuristic for design-document issues by [@jlowin](https://github.com/jlowin) in [#3620](https://github.com/PrefectHQ/fastmcp/pull/3620)
+* Run MCP conformance tests by [@strawgate](https://github.com/strawgate) in [#3628](https://github.com/PrefectHQ/fastmcp/pull/3628)
+* Add PrefabAppConfig for customizable Prefab tool setup by [@jlowin](https://github.com/jlowin) in [#3648](https://github.com/PrefectHQ/fastmcp/pull/3648)
+* Clean error when dev apps ports are in use by [@jlowin](https://github.com/jlowin) in [#3658](https://github.com/PrefectHQ/fastmcp/pull/3658)
+* Add Clerk OAuth provider by [@mostafa6765](https://github.com/mostafa6765) in [#3677](https://github.com/PrefectHQ/fastmcp/pull/3677)
+* Add interactive map example with geocoding by [@jlowin](https://github.com/jlowin) in [#3702](https://github.com/PrefectHQ/fastmcp/pull/3702)
+* Bump pydantic-monty to 0.0.9 by [@jlowin](https://github.com/jlowin) in [#3707](https://github.com/PrefectHQ/fastmcp/pull/3707)
+* Add forward_resource flag to OAuthProxy by [@jlowin](https://github.com/jlowin) in [#3711](https://github.com/PrefectHQ/fastmcp/pull/3711)
+### Security 🔒
+* fix: enforce per-tool auth checks in sampling tool wrapper by [@jlowin](https://github.com/jlowin) in [#3494](https://github.com/PrefectHQ/fastmcp/pull/3494)
+* fix: handle re.error from malformed URI templates by [@jlowin](https://github.com/jlowin) in [#3501](https://github.com/PrefectHQ/fastmcp/pull/3501)
+* fix: reject empty/OIDC-only required_scopes in AzureProvider by [@jlowin](https://github.com/jlowin) in [#3503](https://github.com/PrefectHQ/fastmcp/pull/3503)
+* fix: restrict $ref resolution to local refs only (SSRF/LFI) by [@jlowin](https://github.com/jlowin) in [#3502](https://github.com/PrefectHQ/fastmcp/pull/3502)
+* fix: URL-encode path params to prevent SSRF/path traversal (GHSA-vv7q-7jx5-f767) by [@jlowin](https://github.com/jlowin) in [#3507](https://github.com/PrefectHQ/fastmcp/pull/3507)
+* fix: prevent path traversal in skill download by [@jlowin](https://github.com/jlowin) in [#3493](https://github.com/PrefectHQ/fastmcp/pull/3493)
+* fix: prefer IdP-granted scopes over client-requested scopes in OAuthProxy by [@jlowin](https://github.com/jlowin) in [#3492](https://github.com/PrefectHQ/fastmcp/pull/3492)
+* fix: remove forced follow_redirects from httpx_client_factory calls by [@jlowin](https://github.com/jlowin) in [#3496](https://github.com/PrefectHQ/fastmcp/pull/3496)
+* Bump PyJWT >= 2.12.0 (CVE-2026-32597) by [@jlowin](https://github.com/jlowin) in [#3515](https://github.com/PrefectHQ/fastmcp/pull/3515)
+* Drop diskcache from examples/testing_demo lockfile (CVE-2025-69872) by [@jlowin](https://github.com/jlowin) in [#3518](https://github.com/PrefectHQ/fastmcp/pull/3518)
+* fix: CSRF double-submit cookie check in consent flow by [@jlowin](https://github.com/jlowin) in [#3519](https://github.com/PrefectHQ/fastmcp/pull/3519)
+* fix: validate server names in install commands by [@jlowin](https://github.com/jlowin) in [#3522](https://github.com/PrefectHQ/fastmcp/pull/3522)
+* fix: reject refresh tokens used as Bearer access tokens by [@jlowin](https://github.com/jlowin) in [#3524](https://github.com/PrefectHQ/fastmcp/pull/3524)
+* fix: route ResourcesAsTools/PromptsAsTools through server middleware by [@jlowin](https://github.com/jlowin) in [#3495](https://github.com/PrefectHQ/fastmcp/pull/3495)
+### Fixes 🐞
+* Update docs banner and fix mobile layout by [@jlowin](https://github.com/jlowin) in [#3370](https://github.com/PrefectHQ/fastmcp/pull/3370)
+* Remove form-action from consent CSP, forward consent_csp_policy in providers by [@jlowin](https://github.com/jlowin) in [#3372](https://github.com/PrefectHQ/fastmcp/pull/3372)
+* Fix resource templates with query params on mounted servers by [@jlowin](https://github.com/jlowin) in [#3373](https://github.com/PrefectHQ/fastmcp/pull/3373)
+* Increase uv transport test timeout for CI cold starts by [@jlowin](https://github.com/jlowin) in [#3376](https://github.com/PrefectHQ/fastmcp/pull/3376)
+* Fix stale catalog in CodeMode execute by [@jlowin](https://github.com/jlowin) in [#3375](https://github.com/PrefectHQ/fastmcp/pull/3375)
+* Deduplicate versioned tools in CatalogTransform catalog by [@jlowin](https://github.com/jlowin) in [#3374](https://github.com/PrefectHQ/fastmcp/pull/3374)
+* Fix ty 0.0.20 compatibility by [@jlowin](https://github.com/jlowin) in [#3377](https://github.com/PrefectHQ/fastmcp/pull/3377)
+* Forward scopes_supported through RemoteAuthProvider subclasses by [@jlowin](https://github.com/jlowin) in [#3388](https://github.com/PrefectHQ/fastmcp/pull/3388)
+* Enforce token scopes in WorkOS verifier to prevent scope bypass by [@jlowin](https://github.com/jlowin) in [#3407](https://github.com/PrefectHQ/fastmcp/pull/3407)
+* Bind Discord token verification to configured client_id by [@jlowin](https://github.com/jlowin) in [#3405](https://github.com/PrefectHQ/fastmcp/pull/3405)
+* Return after `McpError` in initialization middleware to prevent fallthrough by [@jlowin](https://github.com/jlowin) in [#3413](https://github.com/PrefectHQ/fastmcp/pull/3413)
+* Escape client_id in OAuth consent advanced details by [@jlowin](https://github.com/jlowin) in [#3418](https://github.com/PrefectHQ/fastmcp/pull/3418)
+* Bound client auto-pagination loops to prevent unbounded list fetches by [@jlowin](https://github.com/jlowin) in [#3411](https://github.com/PrefectHQ/fastmcp/pull/3411)
+* Raise ValueError for invalid boolean query params in resource templates by [@jlowin](https://github.com/jlowin) in [#3434](https://github.com/PrefectHQ/fastmcp/pull/3434)
+* Validate workspace path is a directory in cursor install by [@jlowin](https://github.com/jlowin) in [#3435](https://github.com/PrefectHQ/fastmcp/pull/3435)
+* Validate version metadata to reject non-scalar types by [@jlowin](https://github.com/jlowin) in [#3437](https://github.com/PrefectHQ/fastmcp/pull/3437)
+* Bind AWS Cognito token verification to configured app client by [@jlowin](https://github.com/jlowin) in [#3406](https://github.com/PrefectHQ/fastmcp/pull/3406)
+* Avoid stale context leakage when proxying with an already‑connected ProxyClient by [@jlowin](https://github.com/jlowin) in [#3408](https://github.com/PrefectHQ/fastmcp/pull/3408)
+* Prevent skills manifests from hashing files outside the skill directory by [@jlowin](https://github.com/jlowin) in [#3410](https://github.com/PrefectHQ/fastmcp/pull/3410)
+* Harden fastmcp metadata parsing in proxy paths by [@jlowin](https://github.com/jlowin) in [#3412](https://github.com/PrefectHQ/fastmcp/pull/3412)
+* Re-hash response caching keys to avoid persisting raw request input by [@jlowin](https://github.com/jlowin) in [#3414](https://github.com/PrefectHQ/fastmcp/pull/3414)
+* Handle Windows npx detection when npx.cmd is missing by [@jlowin](https://github.com/jlowin) in [#3416](https://github.com/PrefectHQ/fastmcp/pull/3416)
+* Guard OAuth callback result from post-completion overwrites by [@jlowin](https://github.com/jlowin) in [#3417](https://github.com/PrefectHQ/fastmcp/pull/3417)
+* Fix tool argument rename collisions with passthrough params by [@jlowin](https://github.com/jlowin) in [#3431](https://github.com/PrefectHQ/fastmcp/pull/3431)
+* Guard default progress handler against total=0 notifications by [@jlowin](https://github.com/jlowin) in [#3432](https://github.com/PrefectHQ/fastmcp/pull/3432)
+* Fix get_* returning None when latest version is disabled by [@jlowin](https://github.com/jlowin) in [#3439](https://github.com/PrefectHQ/fastmcp/pull/3439)
+* Fix server lifespan overlap teardown by [@jlowin](https://github.com/jlowin) in [#3415](https://github.com/PrefectHQ/fastmcp/pull/3415)
+* Fix $ref output schema object detection regression by [@jlowin](https://github.com/jlowin) in [#3420](https://github.com/PrefectHQ/fastmcp/pull/3420)
+* Preserve kw-only defaults when rebuilding functions for resolved annotations by [@jlowin](https://github.com/jlowin) in [#3429](https://github.com/PrefectHQ/fastmcp/pull/3429)
+* Redact sensitive headers in OpenAPI provider debug logging by [@jlowin](https://github.com/jlowin) in [#3436](https://github.com/PrefectHQ/fastmcp/pull/3436)
+* Fix async partial callables rejected by iscoroutinefunction by [@jlowin](https://github.com/jlowin) in [#3438](https://github.com/PrefectHQ/fastmcp/pull/3438)
+* Block insecure HS* JWT verification with JWKS/public keys by [@jlowin](https://github.com/jlowin) in [#3430](https://github.com/PrefectHQ/fastmcp/pull/3430)
+* Sanitize untrusted output in `fastmcp list` and `fastmcp call` by [@jlowin](https://github.com/jlowin) in [#3409](https://github.com/PrefectHQ/fastmcp/pull/3409)
+* fix: propagate `version` to components in FileSystemProvider by [@martimfasantos](https://github.com/martimfasantos) in [#3458](https://github.com/PrefectHQ/fastmcp/pull/3458)
+* fix: use intent-based flag for OIDC scope patch in load_access_token by [@voidborne-d](https://github.com/voidborne-d) in [#3465](https://github.com/PrefectHQ/fastmcp/pull/3465)
+* Set readOnlyHint=True on ResourcesAsTools generated tools by [@jlowin](https://github.com/jlowin) in [#3476](https://github.com/PrefectHQ/fastmcp/pull/3476)
+* fix: normalize Google scope shorthands and surface valid_scopes by [@jlowin](https://github.com/jlowin) in [#3477](https://github.com/PrefectHQ/fastmcp/pull/3477)
+* fix: resolve ty 0.0.23 type-checking errors by [@jlowin](https://github.com/jlowin) in [#3481](https://github.com/PrefectHQ/fastmcp/pull/3481)
+* fix: shield lifespan teardown from cancellation by [@jlowin](https://github.com/jlowin) in [#3480](https://github.com/PrefectHQ/fastmcp/pull/3480)
+* fix: forward custom_route endpoints from mounted servers by [@voidborne-d](https://github.com/voidborne-d) in [#3462](https://github.com/PrefectHQ/fastmcp/pull/3462)
+* fix: use dynamic version in CLI help text instead of hardcoded 2.0 by [@saschabuehrle](https://github.com/saschabuehrle) in [#3456](https://github.com/PrefectHQ/fastmcp/pull/3456)
+* Fix Monty 0.0.8 compatibility by [@hkc5](https://github.com/hkc5) in [#3468](https://github.com/PrefectHQ/fastmcp/pull/3468)
+* Fix task test teardown hanging 5s per test by [@jlowin](https://github.com/jlowin) in [#3499](https://github.com/PrefectHQ/fastmcp/pull/3499)
+* fix: validate workspace path is a directory before cursor install by [@nightcityblade](https://github.com/nightcityblade) in [#3440](https://github.com/PrefectHQ/fastmcp/pull/3440)
+* Treat `refresh_expires_in=0` as missing, fall back to 30-day default by [@jlowin](https://github.com/jlowin) in [#3514](https://github.com/PrefectHQ/fastmcp/pull/3514)
+* fix: use raw strings for regex in pytest.raises match by [@jlowin](https://github.com/jlowin) in [#3523](https://github.com/PrefectHQ/fastmcp/pull/3523)
+* fix: resolve Pyright "Module is not callable" on @tool, @resource, @prompt decorators by [@jlowin](https://github.com/jlowin) in [#3540](https://github.com/PrefectHQ/fastmcp/pull/3540)
+* fix: flaky KEY_PREFIX warning test in lowest-direct deps by [@jlowin](https://github.com/jlowin) in [#3549](https://github.com/PrefectHQ/fastmcp/pull/3549)
+* fix: suppress output schema for ToolResult subclass annotations by [@jlowin](https://github.com/jlowin) in [#3548](https://github.com/PrefectHQ/fastmcp/pull/3548)
+* Bump anthropic minimum to 0.48.0 by [@jlowin](https://github.com/jlowin) in [#3553](https://github.com/PrefectHQ/fastmcp/pull/3553)
+* Update startup banner deploy URL to Prefect Horizon by [@zzstoatzz](https://github.com/zzstoatzz) in [#3557](https://github.com/PrefectHQ/fastmcp/pull/3557)
+* fix: increase sleep duration in proxy cache tests by [@strawgate](https://github.com/strawgate) in [#3567](https://github.com/PrefectHQ/fastmcp/pull/3567)
+* fix: store absolute token expiry to prevent stale expires_in on reload by [@jlowin](https://github.com/jlowin) in [#3572](https://github.com/PrefectHQ/fastmcp/pull/3572)
+* fix: preserve tool properties named 'title' during schema compression by [@jlowin](https://github.com/jlowin) in [#3582](https://github.com/PrefectHQ/fastmcp/pull/3582)
+* Add `encoding` parameter to `FileResource` by [@shulkx](https://github.com/shulkx) in [#3580](https://github.com/PrefectHQ/fastmcp/pull/3580)
+* Transparently refresh upstream token in OAuthProxy.load_access_token() by [@jlowin](https://github.com/jlowin) in [#3584](https://github.com/PrefectHQ/fastmcp/pull/3584)
+* Fix loopback redirect URI port matching per RFC 8252 §7.3 by [@radoshi](https://github.com/radoshi) in [#3589](https://github.com/PrefectHQ/fastmcp/pull/3589)
+* Fix app tool routing: visibility check and middleware propagation by [@jlowin](https://github.com/jlowin) in [#3591](https://github.com/PrefectHQ/fastmcp/pull/3591)
+* Fix query parameter serialization to respect OpenAPI explode setting by [@jlowin](https://github.com/jlowin) in [#3595](https://github.com/PrefectHQ/fastmcp/pull/3595)
+* Fix dev apps form: union types, textarea support, JSON parsing by [@jlowin](https://github.com/jlowin) in [#3597](https://github.com/PrefectHQ/fastmcp/pull/3597)
+* Respect OpenAPI content type in request body serialization by [@jlowin](https://github.com/jlowin) in [#3611](https://github.com/PrefectHQ/fastmcp/pull/3611)
+* fix(google): replace deprecated /oauth2/v1/tokeninfo with /oauth2/v3/userinfo by [@shigechika](https://github.com/shigechika) in [#3603](https://github.com/PrefectHQ/fastmcp/pull/3603)
+* fix: resolve EntraOBOToken dependency injection through MultiAuth by [@jer805](https://github.com/jer805) in [#3609](https://github.com/PrefectHQ/fastmcp/pull/3609)
+* fix: filesystem provider import machinery by [@strawgate](https://github.com/strawgate) in [#3626](https://github.com/PrefectHQ/fastmcp/pull/3626)
+* fix: recover StdioTransport after subprocess exits by [@strawgate](https://github.com/strawgate) in [#3630](https://github.com/PrefectHQ/fastmcp/pull/3630)
+* fix(server): preserve mounted tool task metadata by [@pandego](https://github.com/pandego) in [#3632](https://github.com/PrefectHQ/fastmcp/pull/3632)
+* fix: scope deprecation warning filter to FastMCPDeprecationWarning by [@jlowin](https://github.com/jlowin) in [#3649](https://github.com/PrefectHQ/fastmcp/pull/3649)
+* fix: resolve CurrentFastMCP/ctx.fastmcp to child server in mounted background tasks by [@jlowin](https://github.com/jlowin) in [#3651](https://github.com/PrefectHQ/fastmcp/pull/3651)
+* Fix blocking docs issues: chart imports, Select API, Rx consistency by [@jlowin](https://github.com/jlowin) in [#3652](https://github.com/PrefectHQ/fastmcp/pull/3652)
+* Fix prompt caching round-trip on cache miss by [@strawgate](https://github.com/strawgate) in [#3666](https://github.com/PrefectHQ/fastmcp/pull/3666)
+* fix: serialize object query params per OpenAPI style/explode rules by [@4444J99](https://github.com/4444J99) in [#3662](https://github.com/PrefectHQ/fastmcp/pull/3662)
+* fix: HTTP request headers not accessible in background task workers by [@pandego](https://github.com/pandego) in [#3631](https://github.com/PrefectHQ/fastmcp/pull/3631)
+* fix: restore HTTP headers in worker execution path for background tasks by [@jlowin](https://github.com/jlowin) in [#3681](https://github.com/PrefectHQ/fastmcp/pull/3681)
+* fix: strip discriminator after dereferencing schemas by [@jlowin](https://github.com/jlowin) in [#3682](https://github.com/PrefectHQ/fastmcp/pull/3682)
+* fix: remove stale ty:ignore directives for ty 0.0.26 by [@jlowin](https://github.com/jlowin) in [#3684](https://github.com/PrefectHQ/fastmcp/pull/3684)
+* fix: dev apps log panel UX improvements by [@jlowin](https://github.com/jlowin) in [#3698](https://github.com/PrefectHQ/fastmcp/pull/3698)
+* Add quiz example app, fix dev server empty string args by [@jlowin](https://github.com/jlowin) in [#3700](https://github.com/PrefectHQ/fastmcp/pull/3700)
+### Docs 📚
+* Add early-development warning to Prefab docs by [@jlowin](https://github.com/jlowin) in [#3362](https://github.com/PrefectHQ/fastmcp/pull/3362)
+* Add tag to docs by [@jlowin](https://github.com/jlowin) in [#3382](https://github.com/PrefectHQ/fastmcp/pull/3382)
+* Add settings and environment variables reference by [@jlowin](https://github.com/jlowin) in [#3384](https://github.com/PrefectHQ/fastmcp/pull/3384)
+* Add contributing guidelines and update issue/PR templates by [@jlowin](https://github.com/jlowin) in [#3485](https://github.com/PrefectHQ/fastmcp/pull/3485)
+* [Documentation] Move stateless_http transport kwarg to http_app as FastMCP constructo… by [@mhallo](https://github.com/mhallo) in [#3510](https://github.com/PrefectHQ/fastmcp/pull/3510)
+* Update security policy by [@jlowin](https://github.com/jlowin) in [#3521](https://github.com/PrefectHQ/fastmcp/pull/3521)
+* Add release instructions to CLAUDE.md by [@jlowin](https://github.com/jlowin) in [#3583](https://github.com/PrefectHQ/fastmcp/pull/3583)
+* fix(docs): correct misleading stateless_http header by [@jlowin](https://github.com/jlowin) in [#3622](https://github.com/PrefectHQ/fastmcp/pull/3622)
+* Add tag to deployment pages by [@jlowin](https://github.com/jlowin) in [#3624](https://github.com/PrefectHQ/fastmcp/pull/3624)
+* Docs: generative UI page, fix imports, add PrefabAppConfig by [@jlowin](https://github.com/jlowin) in [#3650](https://github.com/PrefectHQ/fastmcp/pull/3650)
+* docs: improve contributor guidelines for framework contributions by [@jlowin](https://github.com/jlowin) in [#3653](https://github.com/PrefectHQ/fastmcp/pull/3653)
+* Add release notes for v3.1.0, v3.1.1, and v2.14.6 by [@jlowin](https://github.com/jlowin) in [#3659](https://github.com/PrefectHQ/fastmcp/pull/3659)
+* Docs: showcase hero, narrative improvements, panel closed by default by [@jlowin](https://github.com/jlowin) in [#3657](https://github.com/PrefectHQ/fastmcp/pull/3657)
+* Docs: add FileTreeStore sanitization warnings and update examples by [@strawgate](https://github.com/strawgate) in [#3661](https://github.com/PrefectHQ/fastmcp/pull/3661)
+* Add prefab-ui version pinning warning to docs by [@jlowin](https://github.com/jlowin) in [#3688](https://github.com/PrefectHQ/fastmcp/pull/3688)
+* Reorganize apps overview TOC by [@jlowin](https://github.com/jlowin) in [#3689](https://github.com/PrefectHQ/fastmcp/pull/3689)
+* Fix docs gaps in app provider pages by [@jlowin](https://github.com/jlowin) in [#3690](https://github.com/PrefectHQ/fastmcp/pull/3690)
+* Polish apps docs for 3.2 release by [@jlowin](https://github.com/jlowin) in [#3693](https://github.com/PrefectHQ/fastmcp/pull/3693)
+* Add apps quickstart tutorial by [@jlowin](https://github.com/jlowin) in [#3695](https://github.com/PrefectHQ/fastmcp/pull/3695)
+* Improve quickstart: pie chart, interactive row selection, screenshots by [@jlowin](https://github.com/jlowin) in [#3699](https://github.com/PrefectHQ/fastmcp/pull/3699)
+* Add sales dashboard and live system monitor examples, bump prefab-ui to 0.17 by [@jlowin](https://github.com/jlowin) in [#3696](https://github.com/PrefectHQ/fastmcp/pull/3696)
+* Add examples gallery page by [@jlowin](https://github.com/jlowin) in [#3705](https://github.com/PrefectHQ/fastmcp/pull/3705)
+* docs: note that custom routes are unauthenticated by [@jlowin](https://github.com/jlowin) in [#3706](https://github.com/PrefectHQ/fastmcp/pull/3706)
+* Remove hardcoded prefab-ui version from pinning warnings by [@jlowin](https://github.com/jlowin) in [#3708](https://github.com/PrefectHQ/fastmcp/pull/3708)
+### Examples & Contrib 💡
+* Block recursive self-invocation in BulkToolCaller by [@jlowin](https://github.com/jlowin) in [#3433](https://github.com/PrefectHQ/fastmcp/pull/3433)
+### Dependencies 📦
+* Bump authlib from 1.6.6 to 1.6.7 in /examples/testing_demo in the uv group across 1 directory by [@dependabot](https://github.com/dependabot) in [#3390](https://github.com/PrefectHQ/fastmcp/pull/3390)
+* Bump actions/create-github-app-token from 2 to 3 by [@dependabot](https://github.com/dependabot) in [#3511](https://github.com/PrefectHQ/fastmcp/pull/3511)
+* chore(deps): bump pyasn1 from 0.6.2 to 0.6.3 in the uv group across 1 directory by [@dependabot](https://github.com/dependabot) in [#3538](https://github.com/PrefectHQ/fastmcp/pull/3538)
+* chore(deps): bump j178/prek-action from 1 to 2 by [@dependabot](https://github.com/dependabot) in [#3578](https://github.com/PrefectHQ/fastmcp/pull/3578)
+* chore(deps): bump requests from 2.32.5 to 2.33.0 in the uv group across 1 directory by [@dependabot](https://github.com/dependabot) in [#3638](https://github.com/PrefectHQ/fastmcp/pull/3638)
+* chore(deps): bump cryptography from 46.0.5 to 46.0.6 in /examples/testing_demo in the uv group across 1 directory by [@dependabot](https://github.com/dependabot) in [#3685](https://github.com/PrefectHQ/fastmcp/pull/3685)
+* chore(deps): bump actions/setup-node from 4 to 6 by [@dependabot](https://github.com/dependabot) in [#3691](https://github.com/PrefectHQ/fastmcp/pull/3691)
+
+## New Contributors
+* @Sumanshu-Nankana made their first contribution in [#3380](https://github.com/PrefectHQ/fastmcp/pull/3380)
+* @ericrobinson-indeed made their first contribution in [#3396](https://github.com/PrefectHQ/fastmcp/pull/3396)
+* @voidborne-d made their first contribution in [#3465](https://github.com/PrefectHQ/fastmcp/pull/3465)
+* @mtthidoteu made their first contribution in [#3473](https://github.com/PrefectHQ/fastmcp/pull/3473)
+* @saschabuehrle made their first contribution in [#3456](https://github.com/PrefectHQ/fastmcp/pull/3456)
+* @hkc5 made their first contribution in [#3468](https://github.com/PrefectHQ/fastmcp/pull/3468)
+* @nightcityblade made their first contribution in [#3440](https://github.com/PrefectHQ/fastmcp/pull/3440)
+* @mhallo made their first contribution in [#3510](https://github.com/PrefectHQ/fastmcp/pull/3510)
+* @radoshi made their first contribution in [#3589](https://github.com/PrefectHQ/fastmcp/pull/3589)
+* @shigechika made their first contribution in [#3603](https://github.com/PrefectHQ/fastmcp/pull/3603)
+* @pandego made their first contribution in [#3632](https://github.com/PrefectHQ/fastmcp/pull/3632)
+* @4444J99 made their first contribution in [#3662](https://github.com/PrefectHQ/fastmcp/pull/3662)
+* @mostafa6765 made their first contribution in [#3677](https://github.com/PrefectHQ/fastmcp/pull/3677)
+
+**Full Changelog**: [v3.1.0...v3.2.0](https://github.com/PrefectHQ/fastmcp/compare/v3.1.0...v3.2.0)
+
+</Update>
+
+<Update label="v3.1.1" description="2026-03-14">
+
+**[v3.1.1: 'Tis But a Patch](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.1.1)**
+
+Pins `pydantic-monty` below 0.0.8 to fix a breaking change in Monty that affects code mode. Monty 0.0.8 removed the `external_functions` constructor parameter, causing `MontySandboxProvider` to fail. This patch caps the version so existing installs work correctly.
+
+### Fixes 🐞
+* Pin pydantic-monty below 0.0.8 to fix code mode by [@jlowin](https://github.com/jlowin) in [#3497](https://github.com/PrefectHQ/fastmcp/pull/3497)
+
+**Full Changelog**: [v3.1.0...v3.1.1](https://github.com/PrefectHQ/fastmcp/compare/v3.1.0...v3.1.1)
+
+</Update>
+
+<Update label="v3.1.0" description="2026-03-03">
+
+**[v3.1.0: Code to Joy](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.1.0)**
+
+FastMCP 3.1 is the Code Mode release. The 3.0 architecture introduced providers and transforms as the extensibility layer — 3.1 puts that architecture to work, shipping the most requested capability since launch: servers that can find and execute code on behalf of agents, without requiring clients to know what tools exist.
+
+### New Features 🎉
+* feat: Search transforms for tool discovery by [@jlowin](https://github.com/jlowin) in [#3154](https://github.com/PrefectHQ/fastmcp/pull/3154)
+* Add experimental CodeMode transform by [@aaazzam](https://github.com/aaazzam) in [#3297](https://github.com/PrefectHQ/fastmcp/pull/3297)
+* Add Prefab Apps integration for MCP tool UIs by [@jlowin](https://github.com/jlowin) in [#3316](https://github.com/PrefectHQ/fastmcp/pull/3316)
+### Enhancements 🔧
+* Lazy-load heavy imports to reduce import time by [@jlowin](https://github.com/jlowin) in [#3295](https://github.com/PrefectHQ/fastmcp/pull/3295)
+* Add http_client parameter to all token verifiers for connection pooling by [@jlowin](https://github.com/jlowin) in [#3300](https://github.com/PrefectHQ/fastmcp/pull/3300)
+* Add in-memory caching for token introspection results by [@jlowin](https://github.com/jlowin) in [#3298](https://github.com/PrefectHQ/fastmcp/pull/3298)
+* Add SessionStart hook to install gh CLI in cloud sessions by [@jlowin](https://github.com/jlowin) in [#3308](https://github.com/PrefectHQ/fastmcp/pull/3308)
+* Fix ty 0.0.19 type errors by [@jlowin](https://github.com/jlowin) in [#3310](https://github.com/PrefectHQ/fastmcp/pull/3310)
+* Code Mode: Add resource limits to MontySandboxProvider by [@jlowin](https://github.com/jlowin) in [#3326](https://github.com/PrefectHQ/fastmcp/pull/3326)
+* Accept transforms as FastMCP init kwarg by [@jlowin](https://github.com/jlowin) in [#3324](https://github.com/PrefectHQ/fastmcp/pull/3324)
+* Split large test files to comply with loq line limit by [@jlowin](https://github.com/jlowin) in [#3328](https://github.com/PrefectHQ/fastmcp/pull/3328)
+* Add -m/--module flag to `fastmcp run` and `dev inspector` by [@dgenio](https://github.com/dgenio) in [#3331](https://github.com/PrefectHQ/fastmcp/pull/3331)
+* Add search_result_serializer hook and serialize_tools_for_output_markdown by [@MagnusS0](https://github.com/MagnusS0) in [#3337](https://github.com/PrefectHQ/fastmcp/pull/3337)
+* Add MultiAuth for composing multiple token verification sources by [@jlowin](https://github.com/jlowin) in [#3335](https://github.com/PrefectHQ/fastmcp/pull/3335)
+* Adds PropelAuth as an AuthProvider by [@andrew-propelauth](https://github.com/andrew-propelauth) in [#3358](https://github.com/PrefectHQ/fastmcp/pull/3358)
+* Replace vendored DI with uncalled-for by [@chrisguidry](https://github.com/chrisguidry) in [#3301](https://github.com/PrefectHQ/fastmcp/pull/3301)
+* Decompose CodeMode into composable discovery tools by [@jlowin](https://github.com/jlowin) in [#3354](https://github.com/PrefectHQ/fastmcp/pull/3354)
+* feat(contrib): auto-sync MCPMixin decorators with from_function signatures by [@AnkeshThakur](https://github.com/AnkeshThakur) in [#3323](https://github.com/PrefectHQ/fastmcp/pull/3323)
+* Add Google GenAI Sampling Handler by [@strawgate](https://github.com/strawgate) in [#2977](https://github.com/PrefectHQ/fastmcp/pull/2977)
+* Add ListTools, search limit, and catalog size annotation to CodeMode by [@jlowin](https://github.com/jlowin) in [#3359](https://github.com/PrefectHQ/fastmcp/pull/3359)
+* Allow configuring FastMCP transport setting in the same way as other configuration by [@jvdmr](https://github.com/jvdmr) in [#1796](https://github.com/PrefectHQ/fastmcp/pull/1796)
+* Add include_unversioned option to VersionFilter by [@yangbaechu](https://github.com/yangbaechu) in [#3349](https://github.com/PrefectHQ/fastmcp/pull/3349)
+### Fixes 🐞
+* Fix docs banner pushing nav down by [@jlowin](https://github.com/jlowin) in [#3282](https://github.com/PrefectHQ/fastmcp/pull/3282)
+* fix: Replace hardcoded TTL with DEFAULT_TTL_MS - issue #3279 by [@cedric57](https://github.com/cedric57) in [#3280](https://github.com/PrefectHQ/fastmcp/pull/3280)
+* fix: stop suppressing server stderr in fastmcp call by [@jlowin](https://github.com/jlowin) in [#3283](https://github.com/PrefectHQ/fastmcp/pull/3283)
+* fix: skip max_completion_tokens when maxTokens is None by [@eon01](https://github.com/eon01) in [#3284](https://github.com/PrefectHQ/fastmcp/pull/3284)
+* OpenAPI: rewrite $ref under propertyNames and patternProperties in _replace_ref_with_defs; add regression test for dict[StrEnum, Model] by [@manojPal23234](https://github.com/manojPal23234) in [#3306](https://github.com/PrefectHQ/fastmcp/pull/3306)
+* Remove stale add_resource() key parameter from docs by [@jlowin](https://github.com/jlowin) in [#3309](https://github.com/PrefectHQ/fastmcp/pull/3309)
+* Handle AuthorizationError as exclusion in AuthMiddleware list hooks by [@yangbaechu](https://github.com/yangbaechu) in [#3338](https://github.com/PrefectHQ/fastmcp/pull/3338)
+* Fix flaky OpenAPI performance test threshold by [@jlowin](https://github.com/jlowin) in [#3355](https://github.com/PrefectHQ/fastmcp/pull/3355)
+* Fix flaky SSE timeout test by [@jlowin](https://github.com/jlowin) in [#3343](https://github.com/PrefectHQ/fastmcp/pull/3343)
+* Remove system role references from docs by [@jlowin](https://github.com/jlowin) in [#3356](https://github.com/PrefectHQ/fastmcp/pull/3356)
+* Fix session persistence across tool calls in multi-server MCPConfigTransport by [@jer805](https://github.com/jer805) in [#3330](https://github.com/PrefectHQ/fastmcp/pull/3330)
+### Docs 📚
+* Add v3.0.2 release notes by [@jlowin](https://github.com/jlowin) in [#3276](https://github.com/PrefectHQ/fastmcp/pull/3276)
+* Fix "FastMCP Constructor Parameters" in documentation server.mdx (Remove old parameters & Add new parameter) by [@wangyy04](https://github.com/wangyy04) in [#3317](https://github.com/PrefectHQ/fastmcp/pull/3317)
+* Fix stale docs: tag filtering API and missing output_schema param by [@jlowin](https://github.com/jlowin) in [#3322](https://github.com/PrefectHQ/fastmcp/pull/3322)
+* Narrate search example clients by [@jlowin](https://github.com/jlowin) in [#3321](https://github.com/PrefectHQ/fastmcp/pull/3321)
+* Code Mode: Document resource limits and fix docs formatting by [@jlowin](https://github.com/jlowin) in [#3327](https://github.com/PrefectHQ/fastmcp/pull/3327)
+* Add reverse proxy (nginx) section to HTTP deployment docs by [@dgenio](https://github.com/dgenio) in [#3344](https://github.com/PrefectHQ/fastmcp/pull/3344)
+* Restructure docs navigation: CLI section, Composition, More by [@jlowin](https://github.com/jlowin) in [#3361](https://github.com/PrefectHQ/fastmcp/pull/3361)
+### Other Changes 🦾
+* Don't advertise sampling.tools capability by default by [@jlowin](https://github.com/jlowin) in [#3334](https://github.com/PrefectHQ/fastmcp/pull/3334)
+
+## New Contributors
+* @cedric57 made their first contribution in [#3280](https://github.com/PrefectHQ/fastmcp/pull/3280)
+* @eon01 made their first contribution in [#3284](https://github.com/PrefectHQ/fastmcp/pull/3284)
+* @manojPal23234 made their first contribution in [#3306](https://github.com/PrefectHQ/fastmcp/pull/3306)
+* @wangyy04 made their first contribution in [#3317](https://github.com/PrefectHQ/fastmcp/pull/3317)
+* @yangbaechu made their first contribution in [#3338](https://github.com/PrefectHQ/fastmcp/pull/3338)
+* @andrew-propelauth made their first contribution in [#3358](https://github.com/PrefectHQ/fastmcp/pull/3358)
+* @jer805 made their first contribution in [#3330](https://github.com/PrefectHQ/fastmcp/pull/3330)
+* @jvdmr made their first contribution in [#1796](https://github.com/PrefectHQ/fastmcp/pull/1796)
+
+**Full Changelog**: [v3.0.2...v3.1.0](https://github.com/PrefectHQ/fastmcp/compare/v3.0.2...v3.1.0)
+
+</Update>
+
+<Update label="v3.0.2" description="2026-02-22">
+
+**[v3.0.2: Threecovery Mode II](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.2)**
+
+Two community-contributed fixes: auth headers from MCP transport no longer leak through to downstream OpenAPI APIs, and background task workers now correctly receive the originating request ID. Plus a new docs example for context-aware tool factories.
+
+### Fixes 🐞
+* fix: prevent MCP transport auth header from leaking to downstream OpenAPI APIs by [@stakeswky](https://github.com/stakeswky) in [#3262](https://github.com/PrefectHQ/fastmcp/pull/3262)
+* fix: propagate origin_request_id to background task workers by [@gfortaine](https://github.com/gfortaine) in [#3175](https://github.com/PrefectHQ/fastmcp/pull/3175)
+### Docs 📚
+* Add v3.0.1 release notes by [@jlowin](https://github.com/jlowin) in [#3259](https://github.com/PrefectHQ/fastmcp/pull/3259)
+* docs: add context-aware tool factory example by [@machov](https://github.com/machov) in [#3264](https://github.com/PrefectHQ/fastmcp/pull/3264)
+
+**Full Changelog**: [v3.0.1...v3.0.2](https://github.com/PrefectHQ/fastmcp/compare/v3.0.1...v3.0.2)
+
+</Update>
+
+<Update label="v3.0.1" description="2026-02-20">
+
+**[v3.0.1: Three-covery Mode](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.1)**
+
+First patch after 3.0 — mostly smoothing out rough edges discovered in the wild. The big ones: middleware state that wasn't surviving the trip to tool handlers now does, `Tool.from_tool()` accepts callables again, OpenAPI schemas with circular references no longer crash discovery, and decorator overloads now return the correct types in function mode. Also adds `verify_id_token` to OIDCProxy for providers (like some Azure AD configs) that issue opaque access tokens but standard JWT id_tokens.
+
+### Enhancements 🔧
+* Add verify_id_token option to OIDCProxy by [@jlowin](https://github.com/jlowin) in [#3248](https://github.com/PrefectHQ/fastmcp/pull/3248)
+### Fixes 🐞
+* Fix v3.0.0 changelog compare link by [@jlowin](https://github.com/jlowin) in [#3223](https://github.com/PrefectHQ/fastmcp/pull/3223)
+* Fix MDX parse error in upgrade guide prompts by [@jlowin](https://github.com/jlowin) in [#3227](https://github.com/PrefectHQ/fastmcp/pull/3227)
+* Fix non-serializable state lost between middleware and tools by [@jlowin](https://github.com/jlowin) in [#3234](https://github.com/PrefectHQ/fastmcp/pull/3234)
+* Accept callables in Tool.from_tool() by [@jlowin](https://github.com/jlowin) in [#3235](https://github.com/PrefectHQ/fastmcp/pull/3235)
+* Preserve skill metadata through provider wrapping by [@jlowin](https://github.com/jlowin) in [#3237](https://github.com/PrefectHQ/fastmcp/pull/3237)
+* Fix circular reference crash in OpenAPI schemas by [@jlowin](https://github.com/jlowin) in [#3245](https://github.com/PrefectHQ/fastmcp/pull/3245)
+* Fix NameError with future annotations and Context/Depends parameters by [@jlowin](https://github.com/jlowin) in [#3243](https://github.com/PrefectHQ/fastmcp/pull/3243)
+* Fix ty ignore syntax in OpenAPI provider by [@jlowin](https://github.com/jlowin) in [#3253](https://github.com/PrefectHQ/fastmcp/pull/3253)
+* Use max_completion_tokens instead of deprecated max_tokens in OpenAI handler by [@jlowin](https://github.com/jlowin) in [#3254](https://github.com/PrefectHQ/fastmcp/pull/3254)
+* Fix ty compatibility with upgraded deps by [@jlowin](https://github.com/jlowin) in [#3257](https://github.com/PrefectHQ/fastmcp/pull/3257)
+* Fix decorator overload return types for function mode by [@jlowin](https://github.com/jlowin) in [#3258](https://github.com/PrefectHQ/fastmcp/pull/3258)
+
+
+### Docs 📚
+* Sync README with welcome.mdx, fix install count by [@jlowin](https://github.com/jlowin) in [#3224](https://github.com/PrefectHQ/fastmcp/pull/3224)
+* Document dict-to-Message prompt migration in upgrade guides by [@jlowin](https://github.com/jlowin) in [#3225](https://github.com/PrefectHQ/fastmcp/pull/3225)
+* Fix v2 upgrade guide: remove incorrect v1 import advice by [@jlowin](https://github.com/jlowin) in [#3226](https://github.com/PrefectHQ/fastmcp/pull/3226)
+* Animated banner by [@jlowin](https://github.com/jlowin) in [#3231](https://github.com/PrefectHQ/fastmcp/pull/3231)
+* Document mounted server state store isolation in upgrade guide by [@jlowin](https://github.com/jlowin) in [#3236](https://github.com/PrefectHQ/fastmcp/pull/3236)
+
+**Full Changelog**: [v3.0.0...v3.0.1](https://github.com/PrefectHQ/fastmcp/compare/v3.0.0...v3.0.1)
+
+</Update>
+
+<Update label="v3.0.0" description="2026-02-18">
+
+**[v3.0.0: Three at Last](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.0)**
+
+FastMCP 3.0 is stable. Two betas, two release candidates, 21 new contributors, and more than 100,000 pre-release installs later — the architecture held up, the upgrade path was smooth, and we're shipping it.
+
+The surface API is largely unchanged — `@mcp.tool()` still works exactly as before. What changed is everything underneath: a provider/transform architecture that makes FastMCP extensible, observable, and composable in ways v2 couldn't support. If we did our jobs right, you'll barely notice the redesign. You'll just notice that more is possible.
+
+This is also the release where FastMCP moves from [jlowin/fastmcp](https://github.com/jlowin/fastmcp) to [PrefectHQ/fastmcp](https://github.com/PrefectHQ/fastmcp). GitHub forwards all links, PyPI is the same, imports are the same. A major version felt like the right moment to make it official.
+
+### Build servers from anything
+
+🔌 Components no longer have to live in one file with one server. `FileSystemProvider` discovers tools from directories with hot-reload. `OpenAPIProvider` wraps REST APIs. `ProxyProvider` proxies remote MCP servers. `SkillsProvider` delivers agent skills as resources. Write your own provider for whatever source makes sense. Compose multiple providers into one server, share one across many, or chain them with **transforms** that rename, namespace, filter, version, and secure components as they flow to clients. `ResourcesAsTools` and `PromptsAsTools` expose non-tool components to tool-only clients.
+
+### Ship to production
+
+🔐 Component versioning: serve `@tool(version="2.0")` alongside older versions from one codebase. Granular authorization on individual components with async auth checks, server-wide policies via `AuthMiddleware`, and scope-based access control. OAuth gets CIMD, Static Client Registration, Azure OBO via dependency injection, JWT audience validation, and confused-deputy protections. OpenTelemetry tracing with MCP semantic conventions. Response size limiting. Background tasks with distributed Redis notification and `ctx.elicit()` relay. Security fixes include dropping `diskcache` (CVE-2025-69872) and upgrading `python-multipart` and `protobuf` for additional CVEs.
+
+### Adapt per session
+
+💾 Session state persists across requests via `ctx.set_state()` / `ctx.get_state()`. `ctx.enable_components()` and `ctx.disable_components()` let servers adapt dynamically per client — show admin tools after authentication, progressively reveal capabilities, or scope access by role.
+
+### Develop faster
+
+⚡ `--reload` auto-restarts on file changes. Standalone decorators return the original function, so decorated tools stay callable in tests and non-MCP contexts. Sync functions auto-dispatch to a threadpool. Tool timeouts, MCP-compliant pagination, composable lifespans, `PingMiddleware` for keepalive, and concurrent tool execution when the LLM returns multiple calls in one response.
+
+### Use FastMCP as a CLI
+
+🖥️ `fastmcp list` and `fastmcp call` query and invoke tools on any server from a terminal. `fastmcp discover` scans your editor configs (Claude Desktop, Cursor, Goose, Gemini CLI) and finds configured servers by name. `fastmcp generate-cli` writes a standalone typed CLI where every tool is a subcommand. `fastmcp install` registers your server with Claude Desktop, Cursor, or Goose in one command.
+
+### Build apps (3.1 preview)
+
+📱 Spec-level support for MCP Apps is in: `ui://` resource scheme, typed UI metadata via `AppConfig`, extension negotiation, and runtime detection. The full Apps experience lands in 3.1.
+
+---
+
+If you hit 3.0 because you didn't pin your dependencies and something breaks — the [upgrade guides](https://gofastmcp.com/getting-started/upgrading/from-fastmcp-2) will get you sorted. We minimized breaking changes, but a major version is a major version.
+
+```bash
+pip install fastmcp -U
+```
+
+📖 [Documentation](https://gofastmcp.com)
+🚀 [Upgrade from FastMCP v2](https://gofastmcp.com/getting-started/upgrading/from-fastmcp-2)
+🔀 [Upgrade from MCP Python SDK](https://gofastmcp.com/getting-started/upgrading/from-mcp-sdk)
+
+## What's Changed
+### New Features 🎉
+* Refactor resource behavior and add meta support by [@jlowin](https://github.com/jlowin) in [#2611](https://github.com/PrefectHQ/fastmcp/pull/2611)
+* Refactor prompt behavior and add meta support by [@jlowin](https://github.com/jlowin) in [#2610](https://github.com/PrefectHQ/fastmcp/pull/2610)
+* feat: Provider abstraction for dynamic MCP components by [@jlowin](https://github.com/jlowin) in [#2622](https://github.com/PrefectHQ/fastmcp/pull/2622)
+* Unify component storage in LocalProvider by [@jlowin](https://github.com/jlowin) in [#2680](https://github.com/PrefectHQ/fastmcp/pull/2680)
+* Introduce ResourceResult as canonical resource return type by [@jlowin](https://github.com/jlowin) in [#2734](https://github.com/PrefectHQ/fastmcp/pull/2734)
+* Introduce Message and PromptResult as canonical prompt types by [@jlowin](https://github.com/jlowin) in [#2738](https://github.com/PrefectHQ/fastmcp/pull/2738)
+* Add --reload flag for auto-restart on file changes by [@jlowin](https://github.com/jlowin) in [#2816](https://github.com/PrefectHQ/fastmcp/pull/2816)
+* Add FileSystemProvider for filesystem-based component discovery by [@jlowin](https://github.com/jlowin) in [#2823](https://github.com/PrefectHQ/fastmcp/pull/2823)
+* Add standalone decorators and eliminate fastmcp.fs module by [@jlowin](https://github.com/jlowin) in [#2832](https://github.com/PrefectHQ/fastmcp/pull/2832)
+* Add authorization checks to components and servers by [@jlowin](https://github.com/jlowin) in [#2855](https://github.com/PrefectHQ/fastmcp/pull/2855)
+* Decorators return functions instead of component objects by [@jlowin](https://github.com/jlowin) in [#2856](https://github.com/PrefectHQ/fastmcp/pull/2856)
+* Add transform system for modifying components in provider chains by [@jlowin](https://github.com/jlowin) in [#2836](https://github.com/PrefectHQ/fastmcp/pull/2836)
+* Add OpenTelemetry tracing support by [@chrisguidry](https://github.com/chrisguidry) in [#2869](https://github.com/PrefectHQ/fastmcp/pull/2869)
+* Add component versioning and VersionFilter transform by [@jlowin](https://github.com/jlowin) in [#2894](https://github.com/PrefectHQ/fastmcp/pull/2894)
+* Add version discovery and calling a certain version for components by [@jlowin](https://github.com/jlowin) in [#2897](https://github.com/PrefectHQ/fastmcp/pull/2897)
+* Refactor visibility to mark-based enabled system by [@jlowin](https://github.com/jlowin) in [#2912](https://github.com/PrefectHQ/fastmcp/pull/2912)
+* Add session-specific visibility control via Context by [@jlowin](https://github.com/jlowin) in [#2917](https://github.com/PrefectHQ/fastmcp/pull/2917)
+* Add Skills Provider for exposing agent skills as MCP resources by [@jlowin](https://github.com/jlowin) in [#2944](https://github.com/PrefectHQ/fastmcp/pull/2944)
+* Add MCP Apps Phase 1 — SDK compatibility (SEP-1865) by [@jlowin](https://github.com/jlowin) in [#3009](https://github.com/PrefectHQ/fastmcp/pull/3009)
+* Add `fastmcp list` and `fastmcp call` CLI commands by [@jlowin](https://github.com/jlowin) in [#3054](https://github.com/PrefectHQ/fastmcp/pull/3054)
+* Add `fastmcp generate-cli` command by [@jlowin](https://github.com/jlowin) in [#3065](https://github.com/PrefectHQ/fastmcp/pull/3065)
+* Add CIMD (Client ID Metadata Document) support for OAuth by [@jlowin](https://github.com/jlowin) in [#2871](https://github.com/PrefectHQ/fastmcp/pull/2871)
+
+
+### Enhancements 🔧
+* Convert mounted servers to MountedProvider by [@jlowin](https://github.com/jlowin) in [#2635](https://github.com/PrefectHQ/fastmcp/pull/2635)
+* Simplify .key as computed property by [@jlowin](https://github.com/jlowin) in [#2648](https://github.com/PrefectHQ/fastmcp/pull/2648)
+* Refactor MountedProvider into FastMCPProvider + TransformingProvider by [@jlowin](https://github.com/jlowin) in [#2653](https://github.com/PrefectHQ/fastmcp/pull/2653)
+* Enable background task support for custom component subclasses by [@jlowin](https://github.com/jlowin) in [#2657](https://github.com/PrefectHQ/fastmcp/pull/2657)
+* Use CreateTaskResult for background task creation by [@jlowin](https://github.com/jlowin) in [#2660](https://github.com/PrefectHQ/fastmcp/pull/2660)
+* Refactor provider execution: components own their execution by [@jlowin](https://github.com/jlowin) in [#2663](https://github.com/PrefectHQ/fastmcp/pull/2663)
+* Add supports_tasks() method to replace string mode checks by [@jlowin](https://github.com/jlowin) in [#2664](https://github.com/PrefectHQ/fastmcp/pull/2664)
+* Replace type: ignore[attr-defined] with isinstance assertions in tests by [@jlowin](https://github.com/jlowin) in [#2665](https://github.com/PrefectHQ/fastmcp/pull/2665)
+* Add poll_interval to TaskConfig by [@jlowin](https://github.com/jlowin) in [#2666](https://github.com/PrefectHQ/fastmcp/pull/2666)
+* Refactor task module: rename protocol.py to requests.py and reduce redundancy by [@jlowin](https://github.com/jlowin) in [#2667](https://github.com/PrefectHQ/fastmcp/pull/2667)
+* Refactor FastMCPProxy into ProxyProvider by [@jlowin](https://github.com/jlowin) in [#2669](https://github.com/PrefectHQ/fastmcp/pull/2669)
+* Move OpenAPI to providers/openapi submodule by [@jlowin](https://github.com/jlowin) in [#2672](https://github.com/PrefectHQ/fastmcp/pull/2672)
+* Use ergonomic provider initialization pattern by [@jlowin](https://github.com/jlowin) in [#2675](https://github.com/PrefectHQ/fastmcp/pull/2675)
+* Fix ty 0.0.5 type errors by [@jlowin](https://github.com/jlowin) in [#2676](https://github.com/PrefectHQ/fastmcp/pull/2676)
+* Remove execution methods from Provider base class by [@jlowin](https://github.com/jlowin) in [#2681](https://github.com/PrefectHQ/fastmcp/pull/2681)
+* Add type-prefixed keys for globally unique component identification by [@jlowin](https://github.com/jlowin) in [#2704](https://github.com/PrefectHQ/fastmcp/pull/2704)
+* Consolidate notification system with unified API by [@jlowin](https://github.com/jlowin) in [#2710](https://github.com/PrefectHQ/fastmcp/pull/2710)
+* Parallelize provider operations by [@jlowin](https://github.com/jlowin) in [#2716](https://github.com/PrefectHQ/fastmcp/pull/2716)
+* Consolidate get_* and _list_* methods into single API by [@jlowin](https://github.com/jlowin) in [#2719](https://github.com/PrefectHQ/fastmcp/pull/2719)
+* Consolidate execution method chains into single public API by [@jlowin](https://github.com/jlowin) in [#2728](https://github.com/PrefectHQ/fastmcp/pull/2728)
+* Parallelize list_* calls in Provider.get_tasks() by [@jlowin](https://github.com/jlowin) in [#2731](https://github.com/PrefectHQ/fastmcp/pull/2731)
+* Consistent decorator-based MCP handler registration by [@jlowin](https://github.com/jlowin) in [#2732](https://github.com/PrefectHQ/fastmcp/pull/2732)
+* Make ToolResult a BaseModel for serialization support by [@jlowin](https://github.com/jlowin) in [#2736](https://github.com/PrefectHQ/fastmcp/pull/2736)
+* Align prompt handler with resource pattern by [@jlowin](https://github.com/jlowin) in [#2740](https://github.com/PrefectHQ/fastmcp/pull/2740)
+* Update classes to inherit from FastMCPBaseModel instead of BaseModel by [@jlowin](https://github.com/jlowin) in [#2739](https://github.com/PrefectHQ/fastmcp/pull/2739)
+* Add explicit task_meta parameter to FastMCP.call_tool() by [@jlowin](https://github.com/jlowin) in [#2749](https://github.com/PrefectHQ/fastmcp/pull/2749)
+* Add task_meta parameter to read_resource() for explicit task control by [@jlowin](https://github.com/jlowin) in [#2750](https://github.com/PrefectHQ/fastmcp/pull/2750)
+* Add task_meta to prompts and centralize fn_key enrichment by [@jlowin](https://github.com/jlowin) in [#2751](https://github.com/PrefectHQ/fastmcp/pull/2751)
+* Remove unused include_tags/exclude_tags settings by [@jlowin](https://github.com/jlowin) in [#2756](https://github.com/PrefectHQ/fastmcp/pull/2756)
+* Parallelize provider access when executing components by [@jlowin](https://github.com/jlowin) in [#2744](https://github.com/PrefectHQ/fastmcp/pull/2744)
+* Deprecate tool_serializer parameter by [@jlowin](https://github.com/jlowin) in [#2753](https://github.com/PrefectHQ/fastmcp/pull/2753)
+* Feature/supabase custom auth route by [@EloiZalczer](https://github.com/EloiZalczer) in [#2632](https://github.com/PrefectHQ/fastmcp/pull/2632)
+* Remove deprecated WSTransport by [@jlowin](https://github.com/jlowin) in [#2826](https://github.com/PrefectHQ/fastmcp/pull/2826)
+* Add composable lifespans by [@jlowin](https://github.com/jlowin) in [#2828](https://github.com/PrefectHQ/fastmcp/pull/2828)
+* Replace FastMCP.as_proxy() with create_proxy() function by [@jlowin](https://github.com/jlowin) in [#2829](https://github.com/PrefectHQ/fastmcp/pull/2829)
+* Add PingMiddleware for keepalive connections by [@jlowin](https://github.com/jlowin) in [#2838](https://github.com/PrefectHQ/fastmcp/pull/2838)
+* Run sync tools/resources/prompts in threadpool automatically by [@jlowin](https://github.com/jlowin) in [#2865](https://github.com/PrefectHQ/fastmcp/pull/2865)
+* Add timeout parameter for tool foreground execution by [@jlowin](https://github.com/jlowin) in [#2872](https://github.com/PrefectHQ/fastmcp/pull/2872)
+* Adopt OpenTelemetry MCP semantic conventions by [@chrisguidry](https://github.com/chrisguidry) in [#2886](https://github.com/PrefectHQ/fastmcp/pull/2886)
+* Add client_secret_post authentication to IntrospectionTokenVerifier by [@shulkx](https://github.com/shulkx) in [#2884](https://github.com/PrefectHQ/fastmcp/pull/2884)
+* Add enable_rich_logging setting to disable rich formatting by [@strawgate](https://github.com/strawgate) in [#2893](https://github.com/PrefectHQ/fastmcp/pull/2893)
+* Rename _fastmcp metadata namespace to fastmcp and make non-optional by [@jlowin](https://github.com/jlowin) in [#2895](https://github.com/PrefectHQ/fastmcp/pull/2895)
+* Refactor FastMCP to inherit from Provider by [@jlowin](https://github.com/jlowin) in [#2901](https://github.com/PrefectHQ/fastmcp/pull/2901)
+* Swap public/private method naming in Provider by [@jlowin](https://github.com/jlowin) in [#2902](https://github.com/PrefectHQ/fastmcp/pull/2902)
+* Add MCP-compliant pagination support by [@jlowin](https://github.com/jlowin) in [#2903](https://github.com/PrefectHQ/fastmcp/pull/2903)
+* Support VersionSpec in enable/disable for range-based filtering by [@jlowin](https://github.com/jlowin) in [#2914](https://github.com/PrefectHQ/fastmcp/pull/2914)
+* Immutable transform wrapping for providers by [@jlowin](https://github.com/jlowin) in [#2913](https://github.com/PrefectHQ/fastmcp/pull/2913)
+* Unify discovery API: deduplicate at protocol layer only by [@jlowin](https://github.com/jlowin) in [#2919](https://github.com/PrefectHQ/fastmcp/pull/2919)
+* Add ResourcesAsTools transform by [@jlowin](https://github.com/jlowin) in [#2943](https://github.com/PrefectHQ/fastmcp/pull/2943)
+* Add PromptsAsTools transform by [@jlowin](https://github.com/jlowin) in [#2946](https://github.com/PrefectHQ/fastmcp/pull/2946)
+* Rename Enabled transform to Visibility by [@jlowin](https://github.com/jlowin) in [#2950](https://github.com/PrefectHQ/fastmcp/pull/2950)
+* feat: option to add upstream claims to the FastMCP proxy JWT by [@JonasKs](https://github.com/JonasKs) in [#2997](https://github.com/PrefectHQ/fastmcp/pull/2997)
+* fix: automatically include offline_access as a scope in the Azure provider by [@JonasKs](https://github.com/JonasKs) in [#3001](https://github.com/PrefectHQ/fastmcp/pull/3001)
+* feat: expand --reload to watch frontend file types by [@jlowin](https://github.com/jlowin) in [#3028](https://github.com/PrefectHQ/fastmcp/pull/3028)
+* Add `fastmcp install stdio` command by [@jlowin](https://github.com/jlowin) in [#3032](https://github.com/PrefectHQ/fastmcp/pull/3032)
+* feat: Goose integration + dedicated install command by [@jlowin](https://github.com/jlowin) in [#3040](https://github.com/PrefectHQ/fastmcp/pull/3040)
+* Add `fastmcp discover` and name-based server resolution by [@jlowin](https://github.com/jlowin) in [#3055](https://github.com/PrefectHQ/fastmcp/pull/3055)
+* feat(context): Add background task support for Context by [@gfortaine](https://github.com/gfortaine) in [#2905](https://github.com/PrefectHQ/fastmcp/pull/2905)
+* Add server version to banner by [@richardkmichael](https://github.com/richardkmichael) in [#3076](https://github.com/PrefectHQ/fastmcp/pull/3076)
+* Add @handle_tool_errors decorator for standardized error handling by [@dgenio](https://github.com/dgenio) in [#2885](https://github.com/PrefectHQ/fastmcp/pull/2885)
+* Add ResponseLimitingMiddleware for tool response size control by [@dgenio](https://github.com/dgenio) in [#3072](https://github.com/PrefectHQ/fastmcp/pull/3072)
+* Infer MIME types from OpenAPI response definitions by [@jlowin](https://github.com/jlowin) in [#3101](https://github.com/PrefectHQ/fastmcp/pull/3101)
+* Remove require_auth in favor of scope-based authorization by [@jlowin](https://github.com/jlowin) in [#3103](https://github.com/PrefectHQ/fastmcp/pull/3103)
+* generate-cli: auto-generate SKILL.md agent skill by [@jlowin](https://github.com/jlowin) in [#3115](https://github.com/PrefectHQ/fastmcp/pull/3115)
+* Add Azure OBO dependencies, auth token injection, and documentation by [@jlowin](https://github.com/jlowin) in [#2918](https://github.com/PrefectHQ/fastmcp/pull/2918)
+* feat: add Static Client Registration by [@martimfasantos](https://github.com/martimfasantos) in [#3086](https://github.com/PrefectHQ/fastmcp/pull/3086)
+* Add concurrent tool execution with sequential flag by [@strawgate](https://github.com/strawgate) in [#3022](https://github.com/PrefectHQ/fastmcp/pull/3022)
+* Add validate_output option for OpenAPI tools by [@jlowin](https://github.com/jlowin) in [#3134](https://github.com/PrefectHQ/fastmcp/pull/3134)
+* Relay task elicitation through standard MCP protocol by [@chrisguidry](https://github.com/chrisguidry) in [#3136](https://github.com/PrefectHQ/fastmcp/pull/3136)
+* Support async auth checks by [@jlowin](https://github.com/jlowin) in [#3152](https://github.com/PrefectHQ/fastmcp/pull/3152)
+* Make $ref dereferencing optional via FastMCP(dereference_refs=...) by [@jlowin](https://github.com/jlowin) in [#3151](https://github.com/PrefectHQ/fastmcp/pull/3151)
+* Expose local_provider property, deprecate FastMCP.remove_tool() by [@jlowin](https://github.com/jlowin) in [#3155](https://github.com/PrefectHQ/fastmcp/pull/3155)
+* Add helpers for converting FunctionTool and TransformedTool to SamplingTool by [@strawgate](https://github.com/strawgate) in [#3062](https://github.com/PrefectHQ/fastmcp/pull/3062)
+### Fixes 🐞
+* Let FastMCPError propagate from dependencies by [@chrisguidry](https://github.com/chrisguidry) in [#2646](https://github.com/PrefectHQ/fastmcp/pull/2646)
+* Fix task execution for tools with custom names by [@chrisguidry](https://github.com/chrisguidry) in [#2645](https://github.com/PrefectHQ/fastmcp/pull/2645)
+* fix: check the cause of the tool error by [@rjolaverria](https://github.com/rjolaverria) in [#2674](https://github.com/PrefectHQ/fastmcp/pull/2674)
+* Fix uvicorn 0.39+ test timeouts and FastMCPError propagation by [@jlowin](https://github.com/jlowin) in [#2699](https://github.com/PrefectHQ/fastmcp/pull/2699)
+* Fix: resolve root-level $ref in outputSchema for MCP spec compliance by [@majiayu000](https://github.com/majiayu000) in [#2720](https://github.com/PrefectHQ/fastmcp/pull/2720)
+* Fix Proxy provider to return all resource contents by [@jlowin](https://github.com/jlowin) in [#2742](https://github.com/PrefectHQ/fastmcp/pull/2742)
+* fix: Client OAuth async_auth_flow() method causing MCP-SDK lock error by [@lgndluke](https://github.com/lgndluke) in [#2644](https://github.com/PrefectHQ/fastmcp/pull/2644)
+* Fix rate limit detection during teardown phase by [@jlowin](https://github.com/jlowin) in [#2757](https://github.com/PrefectHQ/fastmcp/pull/2757)
+* Fix OAuth Proxy resource parameter validation by [@jlowin](https://github.com/jlowin) in [#2764](https://github.com/PrefectHQ/fastmcp/pull/2764)
+* Fix `openapi_version` check so 3.1 is included by [@deeleeramone](https://github.com/deeleeramone) in [#2768](https://github.com/PrefectHQ/fastmcp/pull/2768)
+* Fix base_url fallback when url is not set by [@bhbs](https://github.com/bhbs) in [#2776](https://github.com/PrefectHQ/fastmcp/pull/2776)
+* Lazy import DiskStore to avoid sqlite3 dependency on import by [@jlowin](https://github.com/jlowin) in [#2784](https://github.com/PrefectHQ/fastmcp/pull/2784)
+* Fix OAuth token storage TTL calculation by [@jlowin](https://github.com/jlowin) in [#2796](https://github.com/PrefectHQ/fastmcp/pull/2796)
+* Fix client hanging on HTTP 4xx/5xx errors by [@jlowin](https://github.com/jlowin) in [#2803](https://github.com/PrefectHQ/fastmcp/pull/2803)
+* Fix keep_alive passthrough in StdioMCPServer.to_transport() by [@jlowin](https://github.com/jlowin) in [#2791](https://github.com/PrefectHQ/fastmcp/pull/2791)
+* Dereference $ref in tool schemas for MCP client compatibility by [@jlowin](https://github.com/jlowin) in [#2808](https://github.com/PrefectHQ/fastmcp/pull/2808)
+* Fix timeout not propagating to proxy clients in multi-server MCPConfig by [@jlowin](https://github.com/jlowin) in [#2809](https://github.com/PrefectHQ/fastmcp/pull/2809)
+* Fix ContextVar propagation for ASGI-mounted servers with tasks by [@chrisguidry](https://github.com/chrisguidry) in [#2844](https://github.com/PrefectHQ/fastmcp/pull/2844)
+* Fix HTTP transport timeout defaulting to 5 seconds by [@jlowin](https://github.com/jlowin) in [#2849](https://github.com/PrefectHQ/fastmcp/pull/2849)
+* Fix task capabilities location (issue #2870) by [@jlowin](https://github.com/jlowin) in [#2875](https://github.com/PrefectHQ/fastmcp/pull/2875)
+* fix: broaden combine_lifespans type to accept Mapping return types by [@aminsamir45](https://github.com/aminsamir45) in [#3005](https://github.com/PrefectHQ/fastmcp/pull/3005)
+* fix: correctly send resource when exchanging code for upstream by [@JonasKs](https://github.com/JonasKs) in [#3013](https://github.com/PrefectHQ/fastmcp/pull/3013)
+* chore: upgrade python-multipart to 0.0.22 (CVE-2026-24486) by [@jlowin](https://github.com/jlowin) in [#3042](https://github.com/PrefectHQ/fastmcp/pull/3042)
+* chore: upgrade protobuf to 6.33.5 (CVE-2026-0994) by [@jlowin](https://github.com/jlowin) in [#3043](https://github.com/PrefectHQ/fastmcp/pull/3043)
+* fix: use MCP spec error code -32002 for resource not found by [@jlowin](https://github.com/jlowin) in [#3041](https://github.com/PrefectHQ/fastmcp/pull/3041)
+* Fix tool_choice reset for structured output sampling by [@strawgate](https://github.com/strawgate) in [#3014](https://github.com/PrefectHQ/fastmcp/pull/3014)
+* fix: Preserve metadata in FastMCPProvider component wrappers by [@NeelayS](https://github.com/NeelayS) in [#3057](https://github.com/PrefectHQ/fastmcp/pull/3057)
+* fix: enforce redirect URI validation when allowed_client_redirect_uris is supplied by [@nathanwelsh8](https://github.com/nathanwelsh8) in [#3066](https://github.com/PrefectHQ/fastmcp/pull/3066)
+* Fix --reload port conflict when using explicit port by [@jlowin](https://github.com/jlowin) in [#3070](https://github.com/PrefectHQ/fastmcp/pull/3070)
+* Fix compress_schema to preserve additionalProperties: false by [@jlowin](https://github.com/jlowin) in [#3102](https://github.com/PrefectHQ/fastmcp/pull/3102)
+* Fix CIMD redirect allowlist bypass and cache revalidation by [@jlowin](https://github.com/jlowin) in [#3098](https://github.com/PrefectHQ/fastmcp/pull/3098)
+* Fix session visibility marks leaking across sessions by [@jlowin](https://github.com/jlowin) in [#3132](https://github.com/PrefectHQ/fastmcp/pull/3132)
+* Fix unhandled exceptions in OpenAPI POST tool calls by [@jlowin](https://github.com/jlowin) in [#3133](https://github.com/PrefectHQ/fastmcp/pull/3133)
+* feat: distributed notification queue + BLPOP elicitation for background tasks by [@gfortaine](https://github.com/gfortaine) in [#2906](https://github.com/PrefectHQ/fastmcp/pull/2906)
+* fix: snapshot access token for background tasks by [@gfortaine](https://github.com/gfortaine) in [#3138](https://github.com/PrefectHQ/fastmcp/pull/3138)
+* fix: guard client pagination loops against misbehaving servers by [@jlowin](https://github.com/jlowin) in [#3167](https://github.com/PrefectHQ/fastmcp/pull/3167)
+* Support non-serializable values in Context.set_state by [@jlowin](https://github.com/jlowin) in [#3171](https://github.com/PrefectHQ/fastmcp/pull/3171)
+* Fix stale request context in StatefulProxyClient handlers by [@jlowin](https://github.com/jlowin) in [#3172](https://github.com/PrefectHQ/fastmcp/pull/3172)
+* Drop diskcache dependency (CVE-2025-69872) by [@jlowin](https://github.com/jlowin) in [#3185](https://github.com/PrefectHQ/fastmcp/pull/3185)
+* Fix confused deputy attack via consent binding cookie by [@jlowin](https://github.com/jlowin) in [#3201](https://github.com/PrefectHQ/fastmcp/pull/3201)
+* Add JWT audience validation and RFC 8707 warnings to auth providers by [@jlowin](https://github.com/jlowin) in [#3204](https://github.com/PrefectHQ/fastmcp/pull/3204)
+* Cache OBO credentials on AzureProvider for token reuse by [@jlowin](https://github.com/jlowin) in [#3212](https://github.com/PrefectHQ/fastmcp/pull/3212)
+* Fix invalid uv add command in upgrade guide by [@jlowin](https://github.com/jlowin) in [#3217](https://github.com/PrefectHQ/fastmcp/pull/3217)
+* Use standard traceparent/tracestate keys per OTel MCP semconv by [@chrisguidry](https://github.com/chrisguidry) in [#3221](https://github.com/PrefectHQ/fastmcp/pull/3221)
+### Breaking Changes 🛫
+* Add VisibilityFilter for hierarchical enable/disable by [@jlowin](https://github.com/jlowin) in [#2708](https://github.com/PrefectHQ/fastmcp/pull/2708)
+* Remove automatic environment variable loading from auth providers by [@jlowin](https://github.com/jlowin) in [#2752](https://github.com/PrefectHQ/fastmcp/pull/2752)
+* Make pydocket optional and unify DI systems by [@jlowin](https://github.com/jlowin) in [#2835](https://github.com/PrefectHQ/fastmcp/pull/2835)
+* Add session-scoped state persistence by [@jlowin](https://github.com/jlowin) in [#2873](https://github.com/PrefectHQ/fastmcp/pull/2873)
+* Rename ui= to app= and consolidate ToolUI/ResourceUI into AppConfig by [@jlowin](https://github.com/jlowin) in [#3117](https://github.com/PrefectHQ/fastmcp/pull/3117)
+* Remove deprecated FastMCP() constructor kwargs by [@jlowin](https://github.com/jlowin) in [#3148](https://github.com/PrefectHQ/fastmcp/pull/3148)
+* Move `fastmcp dev` to `fastmcp dev inspector` by [@jlowin](https://github.com/jlowin) in [#3188](https://github.com/PrefectHQ/fastmcp/pull/3188)
+
+## New Contributors
+* [@ivanbelenky](https://github.com/ivanbelenky) made their first contribution in [#2656](https://github.com/PrefectHQ/fastmcp/pull/2656)
+* [@rjolaverria](https://github.com/rjolaverria) made their first contribution in [#2674](https://github.com/PrefectHQ/fastmcp/pull/2674)
+* [@mgoldsborough](https://github.com/mgoldsborough) made their first contribution in [#2701](https://github.com/PrefectHQ/fastmcp/pull/2701)
+* [@Ashif4354](https://github.com/Ashif4354) made their first contribution in [#2707](https://github.com/PrefectHQ/fastmcp/pull/2707)
+* [@majiayu000](https://github.com/majiayu000) made their first contribution in [#2720](https://github.com/PrefectHQ/fastmcp/pull/2720)
+* [@lgndluke](https://github.com/lgndluke) made their first contribution in [#2644](https://github.com/PrefectHQ/fastmcp/pull/2644)
+* [@EloiZalczer](https://github.com/EloiZalczer) made their first contribution in [#2632](https://github.com/PrefectHQ/fastmcp/pull/2632)
+* [@deeleeramone](https://github.com/deeleeramone) made their first contribution in [#2768](https://github.com/PrefectHQ/fastmcp/pull/2768)
+* [@shea-parkes](https://github.com/shea-parkes) made their first contribution in [#2781](https://github.com/PrefectHQ/fastmcp/pull/2781)
+* [@bryankthompson](https://github.com/bryankthompson) made their first contribution in [#2777](https://github.com/PrefectHQ/fastmcp/pull/2777)
+* [@bhbs](https://github.com/bhbs) made their first contribution in [#2776](https://github.com/PrefectHQ/fastmcp/pull/2776)
+* [@shulkx](https://github.com/shulkx) made their first contribution in [#2884](https://github.com/PrefectHQ/fastmcp/pull/2884)
+* [@abhijeethp](https://github.com/abhijeethp) made their first contribution in [#2967](https://github.com/PrefectHQ/fastmcp/pull/2967)
+* [@aminsamir45](https://github.com/aminsamir45) made their first contribution in [#3005](https://github.com/PrefectHQ/fastmcp/pull/3005)
+* [@JonasKs](https://github.com/JonasKs) made their first contribution in [#2997](https://github.com/PrefectHQ/fastmcp/pull/2997)
+* [@NeelayS](https://github.com/NeelayS) made their first contribution in [#3057](https://github.com/PrefectHQ/fastmcp/pull/3057)
+* [@gfortaine](https://github.com/gfortaine) made their first contribution in [#2905](https://github.com/PrefectHQ/fastmcp/pull/2905)
+* [@nathanwelsh8](https://github.com/nathanwelsh8) made their first contribution in [#3066](https://github.com/PrefectHQ/fastmcp/pull/3066)
+* [@dgenio](https://github.com/dgenio) made their first contribution in [#2885](https://github.com/PrefectHQ/fastmcp/pull/2885)
+* [@martimfasantos](https://github.com/martimfasantos) made their first contribution in [#3086](https://github.com/PrefectHQ/fastmcp/pull/3086)
+* [@jfBiswajit](https://github.com/jfBiswajit) made their first contribution in [#3193](https://github.com/PrefectHQ/fastmcp/pull/3193)
+
+**Full Changelog**: https://github.com/PrefectHQ/fastmcp/compare/v2.14.5...v3.0.0
+
+</Update>
+
+<Update label="v3.0.0rc1" description="2026-02-12">
+
+**[v3.0.0rc1: RC-ing is Believing](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.0rc1)**
+
+FastMCP 3 RC1 means we believe the API is stable. Beta 2 drew a wave of real-world adoption — production deployments, migration reports, integration testing — and the feedback overwhelmingly confirmed that the architecture works. This release closes gaps that surfaced under load: auth flows that needed to be async, background tasks that needed reliable notification delivery, and APIs still carrying beta-era naming. If nothing unexpected surfaces, this is what 3.0.0 looks like.
+
+🚨 **Breaking Changes** — The `ui=` parameter is now `app=` with a unified `AppConfig` class (matching the feature's actual name), and 16 `FastMCP()` constructor kwargs have finally been removed. If you've been ignoring months of deprecation warnings, you'll get a `TypeError` with specific migration instructions.
+
+🔐 **Auth Improvements** — Three changes that together round out FastMCP's auth story for production. `auth=` checks can now be `async`, so you can hit databases or external services during authorization — previously, passing an async function silently passed because the unawaited coroutine was truthy. Static Client Registration lets clients provide a pre-registered `client_id`/`client_secret` directly, bypassing DCR for servers that don't support it. And Azure OBO flows are now declarative via dependency injection:
+
+```python
+from fastmcp.server.auth.providers.azure import EntraOBOToken
+
+@mcp.tool()
+async def get_emails(
+    graph_token: str = EntraOBOToken(["https://graph.microsoft.com/Mail.Read"]),
+):
+    # OBO exchange already happened — just use the token
+    ...
+```
+
+⚡ **Concurrent Sampling** — When an LLM returns multiple tool calls in a single response, `context.sample()` can now execute them in parallel. Opt in with `tool_concurrency=0` for unlimited parallelism, or set a bound. Tools that aren't safe to parallelize can declare `sequential=True`.
+
+📡 **Background Task Notifications** — Background tasks now reliably push progress updates and elicit user input through the standard MCP protocol. A distributed Redis queue replaces polling (7,200 round-trips/hour → one blocking call), and `ctx.elicit()` in background tasks automatically relays through the client's standard `elicitation_handler`.
+
+✅ **OpenAPI Output Validation** — When backends don't conform to their own OpenAPI schemas, the MCP SDK rejects the response and the tool fails. `validate_output=False` disables strict schema checking while still passing structured JSON to clients — a necessary escape hatch for imperfect APIs.
+
+## What's Changed
+### Enhancements 🔧
+* generate-cli: auto-generate SKILL.md agent skill by [@jlowin](https://github.com/jlowin) in [#3115](https://github.com/PrefectHQ/fastmcp/pull/3115)
+* Scope Martian triage to bug-labeled issues for jlowin by [@jlowin](https://github.com/jlowin) in [#3124](https://github.com/PrefectHQ/fastmcp/pull/3124)
+* Add Azure OBO dependencies, auth token injection, and documentation by [@jlowin](https://github.com/jlowin) in [#2918](https://github.com/PrefectHQ/fastmcp/pull/2918)
+* feat: add Static Client Registration (#3085) by [@martimfasantos](https://github.com/martimfasantos) in [#3086](https://github.com/PrefectHQ/fastmcp/pull/3086)
+* Add concurrent tool execution with sequential flag by [@strawgate](https://github.com/strawgate) in [#3022](https://github.com/PrefectHQ/fastmcp/pull/3022)
+* Add validate_output option for OpenAPI tools by [@jlowin](https://github.com/jlowin) in [#3134](https://github.com/PrefectHQ/fastmcp/pull/3134)
+* Relay task elicitation through standard MCP protocol by [@chrisguidry](https://github.com/chrisguidry) in [#3136](https://github.com/PrefectHQ/fastmcp/pull/3136)
+* Bump py-key-value-aio to `>=0.4.0,<0.5.0` by [@strawgate](https://github.com/strawgate) in [#3143](https://github.com/PrefectHQ/fastmcp/pull/3143)
+* Support async auth checks by [@jlowin](https://github.com/jlowin) in [#3152](https://github.com/PrefectHQ/fastmcp/pull/3152)
+* Make $ref dereferencing optional via FastMCP(dereference_refs=...) by [@jlowin](https://github.com/jlowin) in [#3151](https://github.com/PrefectHQ/fastmcp/pull/3151)
+* Expose local_provider property, deprecate FastMCP.remove_tool() by [@jlowin](https://github.com/jlowin) in [#3155](https://github.com/PrefectHQ/fastmcp/pull/3155)
+* Add helpers for converting FunctionTool and TransformedTool to SamplingTool by [@strawgate](https://github.com/strawgate) in [#3062](https://github.com/PrefectHQ/fastmcp/pull/3062)
+* Updates to github actions / workflows for claude by [@strawgate](https://github.com/strawgate) in [#3157](https://github.com/PrefectHQ/fastmcp/pull/3157)
+### Fixes 🐞
+* Updated deprecation URL for V3 by [@SrzStephen](https://github.com/SrzStephen) in [#3108](https://github.com/PrefectHQ/fastmcp/pull/3108)
+* Fix Windows test timeouts in OAuth proxy provider tests by [@strawgate](https://github.com/strawgate) in [#3123](https://github.com/PrefectHQ/fastmcp/pull/3123)
+* Fix session visibility marks leaking across sessions by [@jlowin](https://github.com/jlowin) in [#3132](https://github.com/PrefectHQ/fastmcp/pull/3132)
+* Fix unhandled exceptions in OpenAPI POST tool calls by [@jlowin](https://github.com/jlowin) in [#3133](https://github.com/PrefectHQ/fastmcp/pull/3133)
+* feat: distributed notification queue + BLPOP elicitation for background tasks by [@gfortaine](https://github.com/gfortaine) in [#2906](https://github.com/PrefectHQ/fastmcp/pull/2906)
+* fix: snapshot access token for background tasks (#3095) by [@gfortaine](https://github.com/gfortaine) in [#3138](https://github.com/PrefectHQ/fastmcp/pull/3138)
+* Stop duplicating path parameter descriptions into tool prose by [@jlowin](https://github.com/jlowin) in [#3149](https://github.com/PrefectHQ/fastmcp/pull/3149)
+* fix: guard client pagination loops against misbehaving servers by [@jlowin](https://github.com/jlowin) in [#3167](https://github.com/PrefectHQ/fastmcp/pull/3167)
+* Fix stale get_* references in docs and examples by [@jlowin](https://github.com/jlowin) in [#3168](https://github.com/PrefectHQ/fastmcp/pull/3168)
+* Support non-serializable values in Context.set_state by [@jlowin](https://github.com/jlowin) in [#3171](https://github.com/PrefectHQ/fastmcp/pull/3171)
+* Fix stale request context in StatefulProxyClient handlers by [@jlowin](https://github.com/jlowin) in [#3172](https://github.com/PrefectHQ/fastmcp/pull/3172)
+### Breaking Changes 🛫
+* Rename ui= to app= and consolidate ToolUI/ResourceUI into AppConfig by [@jlowin](https://github.com/jlowin) in [#3117](https://github.com/PrefectHQ/fastmcp/pull/3117)
+* Remove deprecated FastMCP() constructor kwargs by [@jlowin](https://github.com/jlowin) in [#3148](https://github.com/PrefectHQ/fastmcp/pull/3148)
+### Docs 📚
+* Update docs to reference beta 2 by [@jlowin](https://github.com/jlowin) in [#3112](https://github.com/PrefectHQ/fastmcp/pull/3112)
+* docs: add pre-registered OAuth clients to v3-features by [@jlowin](https://github.com/jlowin) in [#3129](https://github.com/PrefectHQ/fastmcp/pull/3129)
+### Dependencies 📦
+* chore(deps): bump cryptography from 46.0.3 to 46.0.5 in /examples/testing_demo in the uv group across 1 directory by @dependabot in [#3140](https://github.com/PrefectHQ/fastmcp/pull/3140)
+### Other Changes 🦾
+* docs: add v3.0.0rc1 features to v3-features tracking by [@jlowin](https://github.com/jlowin) in [#3145](https://github.com/PrefectHQ/fastmcp/pull/3145)
+* docs: remove nonexistent MSALApp from rc1 notes by [@jlowin](https://github.com/jlowin) in [#3146](https://github.com/PrefectHQ/fastmcp/pull/3146)
+
+## New Contributors
+* [@martimfasantos](https://github.com/martimfasantos) made their first contribution in [#3086](https://github.com/PrefectHQ/fastmcp/pull/3086)
+
+**Full Changelog**: https://github.com/PrefectHQ/fastmcp/compare/v3.0.0b2...v3.0.0rc1
+
+</Update>
+
+<Update label="v3.0.0b2" description="2026-02-07">
+
+**[v3.0.0b2: 2 Fast 2 Beta](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.0b2)**
+
+FastMCP 3 Beta 2 reflects the huge number of people that kicked the tires on Beta 1. Seven new contributors landed changes in this release, and early migration reports went smoother than expected, including teams on Prefect Horizon upgrading from v2. Most of Beta 2 is refinement: fixing what people found, filling gaps from real usage, hardening edges. But a few new features did land along the way.
+
+🖥️ **Client CLI** — `fastmcp list`, `fastmcp call`, `fastmcp discover`, and `fastmcp generate-cli` turn any MCP server into something you can poke at from a terminal. Discover servers configured in Claude Desktop, Cursor, Goose, or project-level `mcp.json` files and reference them by name. `generate-cli` reads a server's schemas and writes a standalone typed CLI script where every tool is a proper subcommand with flags and help text.
+
+🔐 **CIMD** (Client ID Metadata Documents) adds an alternative to Dynamic Client Registration for OAuth. Clients host a static JSON document at an HTTPS URL; that URL becomes the `client_id`. Server-side support includes SSRF-hardened fetching, cache-aware revalidation, and `private_key_jwt` validation. Enabled by default on `OAuthProxy`.
+
+📱 **MCP Apps** — Spec-level compliance for the MCP Apps extension: `ui://` resource scheme, typed UI metadata on tools and resources, extension negotiation, and `ctx.client_supports_extension()` for runtime detection.
+
+⏳ **Background Task Context** — `Context` now works transparently in Docket workers. `ctx.elicit()` routes through Redis-based coordination so background tasks can pause for user input without any code changes.
+
+🛡️ **ResponseLimitingMiddleware** caps tool response sizes with UTF-8-safe truncation for text and schema-aware error handling for structured outputs.
+
+🪿 **Goose Integration** — `fastmcp install goose` generates deeplink URLs for one-command server installation into Goose.
+
+## What's Changed
+### New Features 🎉
+* Add MCP Apps Phase 1 — SDK compatibility (SEP-1865) by [@jlowin](https://github.com/jlowin) in [#3009](https://github.com/PrefectHQ/fastmcp/pull/3009)
+* Add `fastmcp list` and `fastmcp call` CLI commands by [@jlowin](https://github.com/jlowin) in [#3054](https://github.com/PrefectHQ/fastmcp/pull/3054)
+* Add `fastmcp generate-cli` command by [@jlowin](https://github.com/jlowin) in [#3065](https://github.com/PrefectHQ/fastmcp/pull/3065)
+* Add CIMD (Client ID Metadata Document) support for OAuth by [@jlowin](https://github.com/jlowin) in [#2871](https://github.com/PrefectHQ/fastmcp/pull/2871)
+### Enhancements 🔧
+* Make duplicate bot less aggressive by [@jlowin](https://github.com/jlowin) in [#2981](https://github.com/PrefectHQ/fastmcp/pull/2981)
+* Remove uv lockfile monitoring from Dependabot by [@jlowin](https://github.com/jlowin) in [#2986](https://github.com/PrefectHQ/fastmcp/pull/2986)
+* Run static checks with --upgrade, remove lockfile check by [@jlowin](https://github.com/jlowin) in [#2988](https://github.com/PrefectHQ/fastmcp/pull/2988)
+* Adjust workflow triggers for Marvin by [@strawgate](https://github.com/strawgate) in [#3010](https://github.com/PrefectHQ/fastmcp/pull/3010)
+* Move tests to a reusable action and enable nightly checks by [@strawgate](https://github.com/strawgate) in [#3017](https://github.com/PrefectHQ/fastmcp/pull/3017)
+* feat: option to add upstream claims to the FastMCP proxy JWT by [@JonasKs](https://github.com/JonasKs) in [#2997](https://github.com/PrefectHQ/fastmcp/pull/2997)
+* Fix ty 0.0.14 compatibility and upgrade dependencies by [@jlowin](https://github.com/jlowin) in [#3027](https://github.com/PrefectHQ/fastmcp/pull/3027)
+* fix: automatically include offline_access as a scope in the Azure provider to enable automatic token refreshing by [@JonasKs](https://github.com/JonasKs) in [#3001](https://github.com/PrefectHQ/fastmcp/pull/3001)
+* feat: expand --reload to watch frontend file types by [@jlowin](https://github.com/jlowin) in [#3028](https://github.com/PrefectHQ/fastmcp/pull/3028)
+* Add `fastmcp install stdio` command by [@jlowin](https://github.com/jlowin) in [#3032](https://github.com/PrefectHQ/fastmcp/pull/3032)
+* Update martian-issue-triage.yml for Workflow editing guidance by [@strawgate](https://github.com/strawgate) in [#3033](https://github.com/PrefectHQ/fastmcp/pull/3033)
+* feat: Goose integration + dedicated install command by [@jlowin](https://github.com/jlowin) in [#3040](https://github.com/PrefectHQ/fastmcp/pull/3040)
+* Fixing spelling issues in multiple files by [@didier-durand](https://github.com/didier-durand) in [#2996](https://github.com/PrefectHQ/fastmcp/pull/2996)
+* Add `fastmcp discover` and name-based server resolution by [@jlowin](https://github.com/jlowin) in [#3055](https://github.com/PrefectHQ/fastmcp/pull/3055)
+* feat(context): Add background task support for Context (SEP-1686) by [@gfortaine](https://github.com/gfortaine) in [#2905](https://github.com/PrefectHQ/fastmcp/pull/2905)
+* Add server version to banner by [@richardkmichael](https://github.com/richardkmichael) in [#3076](https://github.com/PrefectHQ/fastmcp/pull/3076)
+* Add @handle_tool_errors decorator for standardized error handling by [@dgenio](https://github.com/dgenio) in [#2885](https://github.com/PrefectHQ/fastmcp/pull/2885)
+* Update Anthropic and OpenAI clients to use Omit instead of NotGiven by [@jlowin](https://github.com/jlowin) in [#3088](https://github.com/PrefectHQ/fastmcp/pull/3088)
+* Add ResponseLimitingMiddleware for tool response size control by [@dgenio](https://github.com/dgenio) in [#3072](https://github.com/PrefectHQ/fastmcp/pull/3072)
+* Infer MIME types from OpenAPI response definitions by [@jlowin](https://github.com/jlowin) in [#3101](https://github.com/PrefectHQ/fastmcp/pull/3101)
+* Remove require_auth in favor of scope-based authorization by [@jlowin](https://github.com/jlowin) in [#3103](https://github.com/PrefectHQ/fastmcp/pull/3103)
+### Fixes 🐞
+* Fix FastAPI mounting examples in docs by [@jlowin](https://github.com/jlowin) in [#2962](https://github.com/PrefectHQ/fastmcp/pull/2962)
+* Remove outdated 'FastMCP 3.0 is coming!' CLI banner by [@jlowin](https://github.com/jlowin) in [#2974](https://github.com/PrefectHQ/fastmcp/pull/2974)
+* Pin httpx `< 1.0` and simplify beta install docs by [@jlowin](https://github.com/jlowin) in [#2975](https://github.com/PrefectHQ/fastmcp/pull/2975)
+* Add enabled field to ToolTransformConfig by [@jlowin](https://github.com/jlowin) in [#2991](https://github.com/PrefectHQ/fastmcp/pull/2991)
+* fix phue2 import in smart_home example by [@zzstoatzz](https://github.com/zzstoatzz) in [#2999](https://github.com/PrefectHQ/fastmcp/pull/2999)
+* fix: broaden combine_lifespans type to accept Mapping return types by [@aminsamir45](https://github.com/aminsamir45) in [#3005](https://github.com/PrefectHQ/fastmcp/pull/3005)
+* fix: type narrowing for skills resource contents by [@strawgate](https://github.com/strawgate) in [#3023](https://github.com/PrefectHQ/fastmcp/pull/3023)
+* fix: correctly send resource when exchanging code for the upstream by [@JonasKs](https://github.com/JonasKs) in [#3013](https://github.com/PrefectHQ/fastmcp/pull/3013)
+* MCP Apps: structured CSP/permissions types, resource meta propagation fix, QR example by [@jlowin](https://github.com/jlowin) in [#3031](https://github.com/PrefectHQ/fastmcp/pull/3031)
+* chore: upgrade python-multipart to 0.0.22 (CVE-2026-24486) by [@jlowin](https://github.com/jlowin) in [#3042](https://github.com/PrefectHQ/fastmcp/pull/3042)
+* chore: upgrade protobuf to 6.33.5 (CVE-2026-0994) by [@jlowin](https://github.com/jlowin) in [#3043](https://github.com/PrefectHQ/fastmcp/pull/3043)
+* fix: use MCP spec error code -32002 for resource not found by [@jlowin](https://github.com/jlowin) in [#3041](https://github.com/PrefectHQ/fastmcp/pull/3041)
+* Fix tool_choice reset for structured output sampling by [@strawgate](https://github.com/strawgate) in [#3014](https://github.com/PrefectHQ/fastmcp/pull/3014)
+* Fix workflow notification URL formatting in upgrade checks by [@strawgate](https://github.com/strawgate) in [#3047](https://github.com/PrefectHQ/fastmcp/pull/3047)
+* Fix Field() handling in prompts by [@strawgate](https://github.com/strawgate) in [#3050](https://github.com/PrefectHQ/fastmcp/pull/3050)
+* fix: use SkipJsonSchema to exclude callable fields from JSON schema generation by [@strawgate](https://github.com/strawgate) in [#3048](https://github.com/PrefectHQ/fastmcp/pull/3048)
+* fix: Preserve metadata in FastMCPProvider component wrappers by [@NeelayS](https://github.com/NeelayS) in [#3057](https://github.com/PrefectHQ/fastmcp/pull/3057)
+* Mock network calls in CLI tests and use MemoryStore for OAuth tests by [@strawgate](https://github.com/strawgate) in [#3051](https://github.com/PrefectHQ/fastmcp/pull/3051)
+* Remove OpenAPI timeout parameter, make client optional, surface timeout errors by [@jlowin](https://github.com/jlowin) in [#3067](https://github.com/PrefectHQ/fastmcp/pull/3067)
+* fix: enforce redirect URI validation when allowed_client_redirect_uris is supplied by [@nathanwelsh8](https://github.com/nathanwelsh8) in [#3066](https://github.com/PrefectHQ/fastmcp/pull/3066)
+* Fix --reload port conflict when using explicit port by [@jlowin](https://github.com/jlowin) in [#3070](https://github.com/PrefectHQ/fastmcp/pull/3070)
+* Fix compress_schema to preserve additionalProperties: false for MCP compatibility by [@jlowin](https://github.com/jlowin) in [#3102](https://github.com/PrefectHQ/fastmcp/pull/3102)
+* Fix CIMD redirect allowlist bypass and cache revalidation by [@jlowin](https://github.com/jlowin) in [#3098](https://github.com/PrefectHQ/fastmcp/pull/3098)
+* Exclude content-type from get_http_headers() to prevent HTTP 415 errors by [@jlowin](https://github.com/jlowin) in [#3104](https://github.com/PrefectHQ/fastmcp/pull/3104)
+### Docs 📚
+* Prepare docs for v3.0 beta release by [@jlowin](https://github.com/jlowin) in [#2954](https://github.com/PrefectHQ/fastmcp/pull/2954)
+* Restructure docs: move transforms to dedicated section by [@jlowin](https://github.com/jlowin) in [#2956](https://github.com/PrefectHQ/fastmcp/pull/2956)
+* Remove unnecessary pip warning by [@jlowin](https://github.com/jlowin) in [#2958](https://github.com/PrefectHQ/fastmcp/pull/2958)
+* Update example MCP version in installation docs by [@jlowin](https://github.com/jlowin) in [#2959](https://github.com/PrefectHQ/fastmcp/pull/2959)
+* Update brand images by [@jlowin](https://github.com/jlowin) in [#2960](https://github.com/PrefectHQ/fastmcp/pull/2960)
+* Restructure README and welcome page with motivated narrative by [@jlowin](https://github.com/jlowin) in [#2963](https://github.com/PrefectHQ/fastmcp/pull/2963)
+* Restructure README and docs with motivated narrative by [@jlowin](https://github.com/jlowin) in [#2964](https://github.com/PrefectHQ/fastmcp/pull/2964)
+* Favicon update and Prefect Horizon docs by [@jlowin](https://github.com/jlowin) in [#2978](https://github.com/PrefectHQ/fastmcp/pull/2978)
+* Add dependency injection documentation and DI-style dependencies by [@jlowin](https://github.com/jlowin) in [#2980](https://github.com/PrefectHQ/fastmcp/pull/2980)
+* docs: document expanded reload behavior and restructure beta sections by [@jlowin](https://github.com/jlowin) in [#3039](https://github.com/PrefectHQ/fastmcp/pull/3039)
+* Add output_schema caveat to response limiting docs by [@jlowin](https://github.com/jlowin) in [#3099](https://github.com/PrefectHQ/fastmcp/pull/3099)
+* Document token passthrough security in OAuth Proxy docs by [@jlowin](https://github.com/jlowin) in [#3100](https://github.com/PrefectHQ/fastmcp/pull/3100)
+### Dependencies 📦
+* Bump ty from 0.0.12 to 0.0.13 by @dependabot in [#2984](https://github.com/PrefectHQ/fastmcp/pull/2984)
+* Bump prek from 0.2.30 to 0.3.0 by @dependabot in [#2982](https://github.com/PrefectHQ/fastmcp/pull/2982)
+### Other Changes 🦾
+* Normalize resource URLs before comparison to support RFC 8707 query parameters by [@abhijeethp](https://github.com/abhijeethp) in [#2967](https://github.com/PrefectHQ/fastmcp/pull/2967)
+* Bump pydocket to 0.17.2 (memory leak fix) by [@chrisguidry](https://github.com/chrisguidry) in [#2998](https://github.com/PrefectHQ/fastmcp/pull/2998)
+* Add AzureJWTVerifier for Managed Identity token verification by [@jlowin](https://github.com/jlowin) in [#3058](https://github.com/PrefectHQ/fastmcp/pull/3058)
+* Add release notes for v2.14.4 and v2.14.5 by [@jlowin](https://github.com/jlowin) in [#3064](https://github.com/PrefectHQ/fastmcp/pull/3064)
+* Add missing beta2 features to v3 release tracking by [@jlowin](https://github.com/jlowin) in [#3105](https://github.com/PrefectHQ/fastmcp/pull/3105)
+
+## New Contributors
+* [@abhijeethp](https://github.com/abhijeethp) made their first contribution in [#2967](https://github.com/PrefectHQ/fastmcp/pull/2967)
+* [@aminsamir45](https://github.com/aminsamir45) made their first contribution in [#3005](https://github.com/PrefectHQ/fastmcp/pull/3005)
+* [@JonasKs](https://github.com/JonasKs) made their first contribution in [#2997](https://github.com/PrefectHQ/fastmcp/pull/2997)
+* [@NeelayS](https://github.com/NeelayS) made their first contribution in [#3057](https://github.com/PrefectHQ/fastmcp/pull/3057)
+* [@gfortaine](https://github.com/gfortaine) made their first contribution in [#2905](https://github.com/PrefectHQ/fastmcp/pull/2905)
+* [@nathanwelsh8](https://github.com/nathanwelsh8) made their first contribution in [#3066](https://github.com/PrefectHQ/fastmcp/pull/3066)
+* [@dgenio](https://github.com/dgenio) made their first contribution in [#2885](https://github.com/PrefectHQ/fastmcp/pull/2885)
+
+**Full Changelog**: https://github.com/PrefectHQ/fastmcp/compare/v3.0.0b1...v3.0.0b2
+
+</Update>
+
+<Update label="v3.0.0b1" description="2026-01-20">
+
+**[v3.0.0b1: This Beta Work](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.0b1)**
+
+FastMCP 3.0 rebuilds the framework around three primitives: components, providers, and transforms. Providers source components dynamically—from decorators, filesystems, OpenAPI specs, remote servers, or anywhere else. Transforms modify components as they flow to clients—renaming, namespacing, filtering, securing. The features that required specialized subsystems in v2 now compose naturally from these building blocks.
+
+🔌 **Provider Architecture** unifies how components are sourced. `FileSystemProvider` discovers decorated functions from directories with optional hot-reload. `SkillsProvider` exposes agent skill files as MCP resources. `OpenAPIProvider` and `ProxyProvider` get cleaner integrations. Providers are composable—share one across servers, or attach many to one server.
+
+🔄 **Transforms** add middleware for components. Namespace mounted servers, rename verbose tools, filter by version, control visibility—all without touching source code. `ResourcesAsTools` and `PromptsAsTools` expose non-tool components to tool-only clients.
+
+📋 **Component Versioning** lets you register `@tool(version="2.0")` alongside older versions. Clients see the highest version by default but can request specific versions. `VersionFilter` serves different API versions from one codebase.
+
+💾 **Session-Scoped State** persists across requests. `await ctx.set_state()` and `await ctx.get_state()` now survive the full session. Per-session visibility via `ctx.enable_components()` lets servers adapt dynamically to each client.
+
+⚡ **DX Improvements** include `--reload` for auto-restart during development, automatic threadpool dispatch for sync functions, tool timeouts, pagination for large component lists, and OpenTelemetry tracing.
+
+🔐 **Component Authorization** via `@tool(auth=require_scopes("admin"))` and `AuthMiddleware` for server-wide policies.
+
+Breaking changes are minimal: for most servers, updating the import statement is all you need. See the [migration guide](https://github.com/PrefectHQ/fastmcp/blob/main/docs/getting-started/upgrading/from-fastmcp-2.mdx) for details.
+
+## What's Changed
+### New Features 🎉
+* Refactor resource behavior and add meta support by [@jlowin](https://github.com/jlowin) in [#2611](https://github.com/PrefectHQ/fastmcp/pull/2611)
+* Refactor prompt behavior and add meta support by [@jlowin](https://github.com/jlowin) in [#2610](https://github.com/PrefectHQ/fastmcp/pull/2610)
+* feat: Provider abstraction for dynamic MCP components by [@jlowin](https://github.com/jlowin) in [#2622](https://github.com/PrefectHQ/fastmcp/pull/2622)
+* Unify component storage in LocalProvider by [@jlowin](https://github.com/jlowin) in [#2680](https://github.com/PrefectHQ/fastmcp/pull/2680)
+* Introduce ResourceResult as canonical resource return type by [@jlowin](https://github.com/jlowin) in [#2734](https://github.com/PrefectHQ/fastmcp/pull/2734)
+* Introduce Message and PromptResult as canonical prompt types by [@jlowin](https://github.com/jlowin) in [#2738](https://github.com/PrefectHQ/fastmcp/pull/2738)
+* Add --reload flag for auto-restart on file changes by [@jlowin](https://github.com/jlowin) in [#2816](https://github.com/PrefectHQ/fastmcp/pull/2816)
+* Add FileSystemProvider for filesystem-based component discovery by [@jlowin](https://github.com/jlowin) in [#2823](https://github.com/PrefectHQ/fastmcp/pull/2823)
+* Add standalone decorators and eliminate fastmcp.fs module by [@jlowin](https://github.com/jlowin) in [#2832](https://github.com/PrefectHQ/fastmcp/pull/2832)
+* Add authorization checks to components and servers by [@jlowin](https://github.com/jlowin) in [#2855](https://github.com/PrefectHQ/fastmcp/pull/2855)
+* Decorators return functions instead of component objects by [@jlowin](https://github.com/jlowin) in [#2856](https://github.com/PrefectHQ/fastmcp/pull/2856)
+* Add transform system for modifying components in provider chains by [@jlowin](https://github.com/jlowin) in [#2836](https://github.com/PrefectHQ/fastmcp/pull/2836)
+* Add OpenTelemetry tracing support by [@chrisguidry](https://github.com/chrisguidry) in [#2869](https://github.com/PrefectHQ/fastmcp/pull/2869)
+* Add component versioning and VersionFilter transform by [@jlowin](https://github.com/jlowin) in [#2894](https://github.com/PrefectHQ/fastmcp/pull/2894)
+* Add version discovery and calling a certain version for components by [@jlowin](https://github.com/jlowin) in [#2897](https://github.com/PrefectHQ/fastmcp/pull/2897)
+* Refactor visibility to mark-based enabled system by [@jlowin](https://github.com/jlowin) in [#2912](https://github.com/PrefectHQ/fastmcp/pull/2912)
+* Add session-specific visibility control via Context by [@jlowin](https://github.com/jlowin) in [#2917](https://github.com/PrefectHQ/fastmcp/pull/2917)
+* Add Skills Provider for exposing agent skills as MCP resources by [@jlowin](https://github.com/jlowin) in [#2944](https://github.com/PrefectHQ/fastmcp/pull/2944)
+### Enhancements 🔧
+* Convert mounted servers to MountedProvider by [@jlowin](https://github.com/jlowin) in [#2635](https://github.com/PrefectHQ/fastmcp/pull/2635)
+* Simplify .key as computed property by [@jlowin](https://github.com/jlowin) in [#2648](https://github.com/PrefectHQ/fastmcp/pull/2648)
+* Refactor MountedProvider into FastMCPProvider + TransformingProvider by [@jlowin](https://github.com/jlowin) in [#2653](https://github.com/PrefectHQ/fastmcp/pull/2653)
+* Enable background task support for custom component subclasses by [@jlowin](https://github.com/jlowin) in [#2657](https://github.com/PrefectHQ/fastmcp/pull/2657)
+* Use CreateTaskResult for background task creation by [@jlowin](https://github.com/jlowin) in [#2660](https://github.com/PrefectHQ/fastmcp/pull/2660)
+* Refactor provider execution: components own their execution by [@jlowin](https://github.com/jlowin) in [#2663](https://github.com/PrefectHQ/fastmcp/pull/2663)
+* Add supports_tasks() method to replace string mode checks by [@jlowin](https://github.com/jlowin) in [#2664](https://github.com/PrefectHQ/fastmcp/pull/2664)
+* Replace type: ignore[attr-defined] with isinstance assertions in tests by [@jlowin](https://github.com/jlowin) in [#2665](https://github.com/PrefectHQ/fastmcp/pull/2665)
+* Add poll_interval to TaskConfig by [@jlowin](https://github.com/jlowin) in [#2666](https://github.com/PrefectHQ/fastmcp/pull/2666)
+* Refactor task module: rename protocol.py to requests.py and reduce redundancy by [@jlowin](https://github.com/jlowin) in [#2667](https://github.com/PrefectHQ/fastmcp/pull/2667)
+* Refactor FastMCPProxy into ProxyProvider by [@jlowin](https://github.com/jlowin) in [#2669](https://github.com/PrefectHQ/fastmcp/pull/2669)
+* Move OpenAPI to providers/openapi submodule by [@jlowin](https://github.com/jlowin) in [#2672](https://github.com/PrefectHQ/fastmcp/pull/2672)
+* Use ergonomic provider initialization pattern by [@jlowin](https://github.com/jlowin) in [#2675](https://github.com/PrefectHQ/fastmcp/pull/2675)
+* Fix ty 0.0.5 type errors by [@jlowin](https://github.com/jlowin) in [#2676](https://github.com/PrefectHQ/fastmcp/pull/2676)
+* Remove execution methods from Provider base class by [@jlowin](https://github.com/jlowin) in [#2681](https://github.com/PrefectHQ/fastmcp/pull/2681)
+* Add type-prefixed keys for globally unique component identification by [@jlowin](https://github.com/jlowin) in [#2704](https://github.com/PrefectHQ/fastmcp/pull/2704)
+* Skip parallel MCP config test on Windows by [@jlowin](https://github.com/jlowin) in [#2711](https://github.com/PrefectHQ/fastmcp/pull/2711)
+* Consolidate notification system with unified API by [@jlowin](https://github.com/jlowin) in [#2710](https://github.com/PrefectHQ/fastmcp/pull/2710)
+* Skip test_multi_client on Windows by [@jlowin](https://github.com/jlowin) in [#2714](https://github.com/PrefectHQ/fastmcp/pull/2714)
+* Parallelize provider operations by [@jlowin](https://github.com/jlowin) in [#2716](https://github.com/PrefectHQ/fastmcp/pull/2716)
+* Consolidate get_* and _list_* methods into single API by [@jlowin](https://github.com/jlowin) in [#2719](https://github.com/PrefectHQ/fastmcp/pull/2719)
+* Consolidate execution method chains into single public API by [@jlowin](https://github.com/jlowin) in [#2728](https://github.com/PrefectHQ/fastmcp/pull/2728)
+* Add documentation check to required PR workflow by [@jlowin](https://github.com/jlowin) in [#2730](https://github.com/PrefectHQ/fastmcp/pull/2730)
+* Parallelize list_* calls in Provider.get_tasks() by [@jlowin](https://github.com/jlowin) in [#2731](https://github.com/PrefectHQ/fastmcp/pull/2731)
+* Consistent decorator-based MCP handler registration by [@jlowin](https://github.com/jlowin) in [#2732](https://github.com/PrefectHQ/fastmcp/pull/2732)
+* Make ToolResult a BaseModel for serialization support by [@jlowin](https://github.com/jlowin) in [#2736](https://github.com/PrefectHQ/fastmcp/pull/2736)
+* Align prompt handler with resource pattern by [@jlowin](https://github.com/jlowin) in [#2740](https://github.com/PrefectHQ/fastmcp/pull/2740)
+* Update classes to inherit from FastMCPBaseModel instead of BaseModel by [@jlowin](https://github.com/jlowin) in [#2739](https://github.com/PrefectHQ/fastmcp/pull/2739)
+* Convert provider tests to use direct server calls by [@jlowin](https://github.com/jlowin) in [#2748](https://github.com/PrefectHQ/fastmcp/pull/2748)
+* Add explicit task_meta parameter to FastMCP.call_tool() by [@jlowin](https://github.com/jlowin) in [#2749](https://github.com/PrefectHQ/fastmcp/pull/2749)
+* Add task_meta parameter to read_resource() for explicit task control by [@jlowin](https://github.com/jlowin) in [#2750](https://github.com/PrefectHQ/fastmcp/pull/2750)
+* Add task_meta to prompts and centralize fn_key enrichment by [@jlowin](https://github.com/jlowin) in [#2751](https://github.com/PrefectHQ/fastmcp/pull/2751)
+* Remove unused include_tags/exclude_tags settings by [@jlowin](https://github.com/jlowin) in [#2756](https://github.com/PrefectHQ/fastmcp/pull/2756)
+* Parallelize provider access when executing components by [@jlowin](https://github.com/jlowin) in [#2744](https://github.com/PrefectHQ/fastmcp/pull/2744)
+* Add tests for OAuth generator cleanup and use aclosing by [@jlowin](https://github.com/jlowin) in [#2759](https://github.com/PrefectHQ/fastmcp/pull/2759)
+* Deprecate tool_serializer parameter by [@jlowin](https://github.com/jlowin) in [#2753](https://github.com/PrefectHQ/fastmcp/pull/2753)
+* Feature/supabase custom auth route by [@EloiZalczer](https://github.com/EloiZalczer) in [#2632](https://github.com/PrefectHQ/fastmcp/pull/2632)
+* Add regression tests for caching with mounted server prefixes by [@jlowin](https://github.com/jlowin) in [#2762](https://github.com/PrefectHQ/fastmcp/pull/2762)
+* Update CLI banner with FastMCP 3.0 notice by [@jlowin](https://github.com/jlowin) in [#2766](https://github.com/PrefectHQ/fastmcp/pull/2766)
+* Make FASTMCP_SHOW_SERVER_BANNER apply to all server startup methods by [@jlowin](https://github.com/jlowin) in [#2771](https://github.com/PrefectHQ/fastmcp/pull/2771)
+* Add MCP tool annotations to smart_home example by [@triepod-ai](https://github.com/triepod-ai) in [#2777](https://github.com/PrefectHQ/fastmcp/pull/2777)
+* Cherry-pick debug logging for OAuth token expiry to main by [@jlowin](https://github.com/jlowin) in [#2797](https://github.com/PrefectHQ/fastmcp/pull/2797)
+* Turn off negative CLI flags by default by [@jlowin](https://github.com/jlowin) in [#2801](https://github.com/PrefectHQ/fastmcp/pull/2801)
+* Configure ty to fail on warnings by [@jlowin](https://github.com/jlowin) in [#2804](https://github.com/PrefectHQ/fastmcp/pull/2804)
+* Dereference $ref in tool schemas for MCP client compatibility by [@jlowin](https://github.com/jlowin) in [#2814](https://github.com/PrefectHQ/fastmcp/pull/2814)
+* Add v3.0 feature tracking document by [@jlowin](https://github.com/jlowin) in [#2822](https://github.com/PrefectHQ/fastmcp/pull/2822)
+* Remove deprecated WSTransport by [@jlowin](https://github.com/jlowin) in [#2826](https://github.com/PrefectHQ/fastmcp/pull/2826)
+* Add composable lifespans by [@jlowin](https://github.com/jlowin) in [#2828](https://github.com/PrefectHQ/fastmcp/pull/2828)
+* Replace FastMCP.as_proxy() with create_proxy() function by [@jlowin](https://github.com/jlowin) in [#2829](https://github.com/PrefectHQ/fastmcp/pull/2829)
+* Add docs-broken-links command and fix docstring markdown parsing by [@jlowin](https://github.com/jlowin) in [#2830](https://github.com/PrefectHQ/fastmcp/pull/2830)
+* Add PingMiddleware for keepalive connections by [@jlowin](https://github.com/jlowin) in [#2838](https://github.com/PrefectHQ/fastmcp/pull/2838)
+* Add CLI update notifications by [@jlowin](https://github.com/jlowin) in [#2840](https://github.com/PrefectHQ/fastmcp/pull/2840)
+* Add agent skills for testing and code review by [@jlowin](https://github.com/jlowin) in [#2846](https://github.com/PrefectHQ/fastmcp/pull/2846)
+* Add loq pre-commit hook for file size enforcement by [@jlowin](https://github.com/jlowin) in [#2847](https://github.com/PrefectHQ/fastmcp/pull/2847)
+* Add transport property to Context by [@jlowin](https://github.com/jlowin) in [#2850](https://github.com/PrefectHQ/fastmcp/pull/2850)
+* Add loq file size limits and clean up type ignores by [@jlowin](https://github.com/jlowin) in [#2859](https://github.com/PrefectHQ/fastmcp/pull/2859)
+* Run sync tools/resources/prompts in threadpool automatically by [@jlowin](https://github.com/jlowin) in [#2865](https://github.com/PrefectHQ/fastmcp/pull/2865)
+* Add timeout parameter for tool foreground execution by [@jlowin](https://github.com/jlowin) in [#2872](https://github.com/PrefectHQ/fastmcp/pull/2872)
+* Adopt OpenTelemetry MCP semantic conventions by [@chrisguidry](https://github.com/chrisguidry) in [#2886](https://github.com/PrefectHQ/fastmcp/pull/2886)
+* Add client_secret_post authentication to IntrospectionTokenVerifier by [@shulkx](https://github.com/shulkx) in [#2884](https://github.com/PrefectHQ/fastmcp/pull/2884)
+* Add enable_rich_logging setting to disable rich formatting by [@strawgate](https://github.com/strawgate) in [#2893](https://github.com/PrefectHQ/fastmcp/pull/2893)
+* Rename _fastmcp metadata namespace to fastmcp and make non-optional by [@jlowin](https://github.com/jlowin) in [#2895](https://github.com/PrefectHQ/fastmcp/pull/2895)
+* Refactor FastMCP to inherit from Provider by [@jlowin](https://github.com/jlowin) in [#2901](https://github.com/PrefectHQ/fastmcp/pull/2901)
+* Swap public/private method naming in Provider by [@jlowin](https://github.com/jlowin) in [#2902](https://github.com/PrefectHQ/fastmcp/pull/2902)
+* Add MCP-compliant pagination support by [@jlowin](https://github.com/jlowin) in [#2903](https://github.com/PrefectHQ/fastmcp/pull/2903)
+* Support VersionSpec in enable/disable for range-based filtering by [@jlowin](https://github.com/jlowin) in [#2914](https://github.com/PrefectHQ/fastmcp/pull/2914)
+* Remove sync notification infrastructure by [@jlowin](https://github.com/jlowin) in [#2915](https://github.com/PrefectHQ/fastmcp/pull/2915)
+* Immutable transform wrapping for providers by [@jlowin](https://github.com/jlowin) in [#2913](https://github.com/PrefectHQ/fastmcp/pull/2913)
+* Unify discovery API: deduplicate at protocol layer only by [@jlowin](https://github.com/jlowin) in [#2919](https://github.com/PrefectHQ/fastmcp/pull/2919)
+* Split transports.py into modular structure by [@jlowin](https://github.com/jlowin) in [#2921](https://github.com/PrefectHQ/fastmcp/pull/2921)
+* Move session visibility logic to enabled.py by [@jlowin](https://github.com/jlowin) in [#2924](https://github.com/PrefectHQ/fastmcp/pull/2924)
+* Refactor Client class into mixins and add timeout utilities by [@jlowin](https://github.com/jlowin) in [#2933](https://github.com/PrefectHQ/fastmcp/pull/2933)
+* Refactor OAuthProxy into focused modules by [@jlowin](https://github.com/jlowin) in [#2935](https://github.com/PrefectHQ/fastmcp/pull/2935)
+* Refactor LocalProvider into mixin modules by [@jlowin](https://github.com/jlowin) in [#2936](https://github.com/PrefectHQ/fastmcp/pull/2936)
+* Refactor server.py into mixins by [@jlowin](https://github.com/jlowin) in [#2939](https://github.com/PrefectHQ/fastmcp/pull/2939)
+* Consolidate test fixtures and refactor large test files by [@jlowin](https://github.com/jlowin) in [#2941](https://github.com/PrefectHQ/fastmcp/pull/2941)
+* Refactor transform list methods to pure function pattern by [@jlowin](https://github.com/jlowin) in [#2942](https://github.com/PrefectHQ/fastmcp/pull/2942)
+* Add ResourcesAsTools transform by [@jlowin](https://github.com/jlowin) in [#2943](https://github.com/PrefectHQ/fastmcp/pull/2943)
+* Add PromptsAsTools transform by [@jlowin](https://github.com/jlowin) in [#2946](https://github.com/PrefectHQ/fastmcp/pull/2946)
+* Add client utilities for downloading skills by [@jlowin](https://github.com/jlowin) in [#2948](https://github.com/PrefectHQ/fastmcp/pull/2948)
+* Rename Enabled transform to Visibility by [@jlowin](https://github.com/jlowin) in [#2950](https://github.com/PrefectHQ/fastmcp/pull/2950)
+### Fixes 🐞
+* Let FastMCPError propagate from dependencies by [@chrisguidry](https://github.com/chrisguidry) in [#2646](https://github.com/PrefectHQ/fastmcp/pull/2646)
+* Fix task execution for tools with custom names by [@chrisguidry](https://github.com/chrisguidry) in [#2645](https://github.com/PrefectHQ/fastmcp/pull/2645)
+* fix: check the cause of the tool error by [@rjolaverria](https://github.com/rjolaverria) in [#2674](https://github.com/PrefectHQ/fastmcp/pull/2674)
+* Bump pydocket to 0.16.3 for task cancellation support by [@chrisguidry](https://github.com/chrisguidry) in [#2683](https://github.com/PrefectHQ/fastmcp/pull/2683)
+* Fix uvicorn 0.39+ test timeouts and FastMCPError propagation by [@jlowin](https://github.com/jlowin) in [#2699](https://github.com/PrefectHQ/fastmcp/pull/2699)
+* Fix Prefect website URL in docs footer by [@mgoldsborough](https://github.com/mgoldsborough) in [#2701](https://github.com/PrefectHQ/fastmcp/pull/2701)
+* Fix: resolve root-level $ref in outputSchema for MCP spec compliance by [@majiayu000](https://github.com/majiayu000) in [#2720](https://github.com/PrefectHQ/fastmcp/pull/2720)
+* Fix Provider.get_tasks() to include custom component subclasses by [@jlowin](https://github.com/jlowin) in [#2729](https://github.com/PrefectHQ/fastmcp/pull/2729)
+* Fix Proxy provider to return all resource contents by [@jlowin](https://github.com/jlowin) in [#2742](https://github.com/PrefectHQ/fastmcp/pull/2742)
+* Fix prompt return type documentation by [@jlowin](https://github.com/jlowin) in [#2741](https://github.com/PrefectHQ/fastmcp/pull/2741)
+* fix: Client OAuth async_auth_flow() method causing MCP-SDK self.context.lock error. by [@lgndluke](https://github.com/lgndluke) in [#2644](https://github.com/PrefectHQ/fastmcp/pull/2644)
+* Fix rate limit detection during teardown phase by [@jlowin](https://github.com/jlowin) in [#2757](https://github.com/PrefectHQ/fastmcp/pull/2757)
+* fix: set pytest-asyncio default fixture loop scope to function by [@jlowin](https://github.com/jlowin) in [#2758](https://github.com/PrefectHQ/fastmcp/pull/2758)
+* Fix OAuth Proxy resource parameter validation by [@jlowin](https://github.com/jlowin) in [#2764](https://github.com/PrefectHQ/fastmcp/pull/2764)
+* [BugFix] Fix `openapi_version` Check So 3.1 Is Included by [@deeleeramone](https://github.com/deeleeramone) in [#2768](https://github.com/PrefectHQ/fastmcp/pull/2768)
+* Fix titled enum elicitation schema to comply with MCP spec by [@jlowin](https://github.com/jlowin) in [#2773](https://github.com/PrefectHQ/fastmcp/pull/2773)
+* Fix base_url fallback when url is not set by [@bhbs](https://github.com/bhbs) in [#2776](https://github.com/PrefectHQ/fastmcp/pull/2776)
+* Lazy import DiskStore to avoid sqlite3 dependency on import by [@jlowin](https://github.com/jlowin) in [#2784](https://github.com/PrefectHQ/fastmcp/pull/2784)
+* Fix OAuth token storage TTL calculation by [@jlowin](https://github.com/jlowin) in [#2796](https://github.com/PrefectHQ/fastmcp/pull/2796)
+* Use consistent refresh_ttl for JTI mapping store by [@jlowin](https://github.com/jlowin) in [#2799](https://github.com/PrefectHQ/fastmcp/pull/2799)
+* Return 401 for invalid_grant token errors per MCP spec by [@jlowin](https://github.com/jlowin) in [#2800](https://github.com/PrefectHQ/fastmcp/pull/2800)
+* Fix client hanging on HTTP 4xx/5xx errors by [@jlowin](https://github.com/jlowin) in [#2803](https://github.com/PrefectHQ/fastmcp/pull/2803)
+* Fix unawaited coroutine warning and treat as test error by [@jlowin](https://github.com/jlowin) in [#2806](https://github.com/PrefectHQ/fastmcp/pull/2806)
+* Fix keep_alive passthrough in StdioMCPServer.to_transport() by [@jlowin](https://github.com/jlowin) in [#2791](https://github.com/PrefectHQ/fastmcp/pull/2791)
+* Dereference $ref in tool schemas for MCP client compatibility by [@jlowin](https://github.com/jlowin) in [#2808](https://github.com/PrefectHQ/fastmcp/pull/2808)
+* Prefix Redis keys with docket name for ACL isolation by [@chrisguidry](https://github.com/chrisguidry) in [#2811](https://github.com/PrefectHQ/fastmcp/pull/2811)
+* fix smart_home example: HueAttributes schema and deprecated prefix by [@zzstoatzz](https://github.com/zzstoatzz) in [#2818](https://github.com/PrefectHQ/fastmcp/pull/2818)
+* Fix redirect URI validation docs to match implementation by [@jlowin](https://github.com/jlowin) in [#2824](https://github.com/PrefectHQ/fastmcp/pull/2824)
+* Fix timeout not propagating to proxy clients in multi-server MCPConfig by [@jlowin](https://github.com/jlowin) in [#2809](https://github.com/PrefectHQ/fastmcp/pull/2809)
+* Fix ContextVar propagation for ASGI-mounted servers with tasks by [@chrisguidry](https://github.com/chrisguidry) in [#2844](https://github.com/PrefectHQ/fastmcp/pull/2844)
+* Fix HTTP transport timeout defaulting to 5 seconds by [@jlowin](https://github.com/jlowin) in [#2849](https://github.com/PrefectHQ/fastmcp/pull/2849)
+* Fix decorator error messages to link to correct doc pages by [@jlowin](https://github.com/jlowin) in [#2858](https://github.com/PrefectHQ/fastmcp/pull/2858)
+* Fix task capabilities location (issue #2870) by [@jlowin](https://github.com/jlowin) in [#2875](https://github.com/PrefectHQ/fastmcp/pull/2875)
+* Bump the uv group across 1 directory with 2 updates by [@dependabot](https://github.com/dependabot)\[bot\] in [#2890](https://github.com/PrefectHQ/fastmcp/pull/2890)
+### Breaking Changes 🛫
+* Add VisibilityFilter for hierarchical enable/disable by [@jlowin](https://github.com/jlowin) in [#2708](https://github.com/PrefectHQ/fastmcp/pull/2708)
+* Remove automatic environment variable loading from auth providers by [@jlowin](https://github.com/jlowin) in [#2752](https://github.com/PrefectHQ/fastmcp/pull/2752)
+* Make pydocket optional and unify DI systems by [@jlowin](https://github.com/jlowin) in [#2835](https://github.com/PrefectHQ/fastmcp/pull/2835)
+* Add session-scoped state persistence by [@jlowin](https://github.com/jlowin) in [#2873](https://github.com/PrefectHQ/fastmcp/pull/2873)
+### Docs 📚
+* Undocumented `McpError` exceptions by [@ivanbelenky](https://github.com/ivanbelenky) in [#2656](https://github.com/PrefectHQ/fastmcp/pull/2656)
+* docs(server): add http to transport options in run() method docstring by [@Ashif4354](https://github.com/Ashif4354) in [#2707](https://github.com/PrefectHQ/fastmcp/pull/2707)
+* Add v3 breaking changes notice to README by [@jlowin](https://github.com/jlowin) in [#2712](https://github.com/PrefectHQ/fastmcp/pull/2712)
+* Add changelog entries for v2.13.1 through v2.14.1 by [@jlowin](https://github.com/jlowin) in [#2725](https://github.com/PrefectHQ/fastmcp/pull/2725)
+* Reorganize docs around provider architecture by [@jlowin](https://github.com/jlowin) in [#2723](https://github.com/PrefectHQ/fastmcp/pull/2723)
+* Fix documentation to use 'meta' instead of '_meta' for MCP spec field by [@jlowin](https://github.com/jlowin) in [#2735](https://github.com/PrefectHQ/fastmcp/pull/2735)
+* Enhance documentation on tool transformation by [@shea-parkes](https://github.com/shea-parkes) in [#2781](https://github.com/PrefectHQ/fastmcp/pull/2781)
+* Add FastMCP 4.0 preview to documentation by [@jlowin](https://github.com/jlowin) in [#2831](https://github.com/PrefectHQ/fastmcp/pull/2831)
+* Add release notes for v2.14.2 and v2.14.3 by [@jlowin](https://github.com/jlowin) in [#2852](https://github.com/PrefectHQ/fastmcp/pull/2852)
+* Add missing 3.0.0 version badges and document tasks extra by [@jlowin](https://github.com/jlowin) in [#2866](https://github.com/PrefectHQ/fastmcp/pull/2866)
+* Fix custom provider docs to show correct interface by [@jlowin](https://github.com/jlowin) in [#2920](https://github.com/PrefectHQ/fastmcp/pull/2920)
+* Update v3 features that were missed in PRs by [@jlowin](https://github.com/jlowin) in [#2947](https://github.com/PrefectHQ/fastmcp/pull/2947)
+* Restructure documentation for FastMCP 3.0 by [@jlowin](https://github.com/jlowin) in [#2951](https://github.com/PrefectHQ/fastmcp/pull/2951)
+* Fix broken documentation links by [@jlowin](https://github.com/jlowin) in [#2952](https://github.com/PrefectHQ/fastmcp/pull/2952)
+* Clarify installation for FastMCP 3.0 beta by [@jlowin](https://github.com/jlowin) in [#2953](https://github.com/PrefectHQ/fastmcp/pull/2953)
+### Dependencies 📦
+* Bump peter-evans/create-pull-request from 7 to 8 by [@dependabot](https://github.com/dependabot)\[bot\] in [#2623](https://github.com/PrefectHQ/fastmcp/pull/2623)
+* Bump ty to 0.0.7+ by [@jlowin](https://github.com/jlowin) in [#2737](https://github.com/PrefectHQ/fastmcp/pull/2737)
+* Bump the uv group across 1 directory with 4 updates by [@dependabot](https://github.com/dependabot)\[bot\] in [#2891](https://github.com/PrefectHQ/fastmcp/pull/2891)
+
+## New Contributors
+* [@ivanbelenky](https://github.com/ivanbelenky) made their first contribution in [#2656](https://github.com/PrefectHQ/fastmcp/pull/2656)
+* [@rjolaverria](https://github.com/rjolaverria) made their first contribution in [#2674](https://github.com/PrefectHQ/fastmcp/pull/2674)
+* [@mgoldsborough](https://github.com/mgoldsborough) made their first contribution in [#2701](https://github.com/PrefectHQ/fastmcp/pull/2701)
+* [@Ashif4354](https://github.com/Ashif4354) made their first contribution in [#2707](https://github.com/PrefectHQ/fastmcp/pull/2707)
+* [@majiayu000](https://github.com/majiayu000) made their first contribution in [#2720](https://github.com/PrefectHQ/fastmcp/pull/2720)
+* [@lgndluke](https://github.com/lgndluke) made their first contribution in [#2644](https://github.com/PrefectHQ/fastmcp/pull/2644)
+* [@EloiZalczer](https://github.com/EloiZalczer) made their first contribution in [#2632](https://github.com/PrefectHQ/fastmcp/pull/2632)
+* [@deeleeramone](https://github.com/deeleeramone) made their first contribution in [#2768](https://github.com/PrefectHQ/fastmcp/pull/2768)
+* [@shea-parkes](https://github.com/shea-parkes) made their first contribution in [#2781](https://github.com/PrefectHQ/fastmcp/pull/2781)
+* [@triepod-ai](https://github.com/triepod-ai) made their first contribution in [#2777](https://github.com/PrefectHQ/fastmcp/pull/2777)
+* [@bhbs](https://github.com/bhbs) made their first contribution in [#2776](https://github.com/PrefectHQ/fastmcp/pull/2776)
+* [@shulkx](https://github.com/shulkx) made their first contribution in [#2884](https://github.com/PrefectHQ/fastmcp/pull/2884)
+
+**Full Changelog**: [v2.14.1...v3.0.0b1](https://github.com/PrefectHQ/fastmcp/compare/v2.14.1...v3.0.0b1)
+
+</Update>
+
+<Update label="v2.14.7" description="2026-04-13">
+
+**[v2.14.7: Fake It Till You Break It](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.7)**
+
+A 2.x backport of the fakeredis pin: fakeredis 2.35.0 renamed a connection class that pydocket's `memory://` backend depended on, crashing `fastmcp[tasks]` installs at startup. This caps `fakeredis<2.35.0` on the 2.x line.
+
+### Fixes 🐞
+* fix(deps): cap fakeredis to `<2.35.0` to prevent startup crash on 2.x by [@vincent067](https://github.com/vincent067) in [#3883](https://github.com/PrefectHQ/fastmcp/pull/3883)
+
+**Full Changelog**: [v2.14.6...v2.14.7](https://github.com/PrefectHQ/fastmcp/compare/v2.14.6...v2.14.7)
+
+</Update>
+
+<Update label="v2.14.6" description="2026-03-27">
+
+**[v2.14.6: $Ref Dead Redemption](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.6)**
+
+v2.14.4 backported `dereference_refs()` but never wired it into the tool schema pipeline — `$ref` and `$defs` were still sent to MCP clients. Now fixed: `compress_schema()` dereferences at both tool schema creation sites, so schemas are fully inlined before reaching clients.
+
+### Fixes 🐞
+* Updated deprecation URL for V2 by [@SrzStephen](https://github.com/SrzStephen) in [#3109](https://github.com/PrefectHQ/fastmcp/pull/3109)
+* Use MemoryStore for OAuth proxy tests by [@SrzStephen](https://github.com/SrzStephen) in [#3111](https://github.com/PrefectHQ/fastmcp/pull/3111)
+* fix: wire up dereference_refs() in tool schema pipeline by [@jlowin](https://github.com/jlowin) in [#3170](https://github.com/PrefectHQ/fastmcp/pull/3170)
+
+**Full Changelog**: [v2.14.5...v2.14.6](https://github.com/PrefectHQ/fastmcp/compare/v2.14.5...v2.14.6)
+
+</Update>
+
+<Update label="v2.14.5" description="2026-02-03">
+
+**[v2.14.5: Sealed Docket](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.5)**
+
+Fixes a memory leak in the memory:// docket broker where cancelled tasks accumulated instead of being cleaned up. Bumps pydocket to ≥0.17.2.
+
+## What's Changed
+### Enhancements 🔧
+* Bump pydocket to 0.17.2 (memory leak fix) by [@chrisguidry](https://github.com/chrisguidry) in [#2992](https://github.com/PrefectHQ/fastmcp/pull/2992)
+
+**Full Changelog**: [v2.14.4...v2.14.5](https://github.com/PrefectHQ/fastmcp/compare/v2.14.4...v2.14.5)
+
+</Update>
+
+<Update label="v2.14.4" description="2026-01-22">
+
+**[v2.14.4: Package Deal](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.4)**
+
+Fixes a fresh install bug where the packaging library was missing as a direct dependency, plus backports from 3.x for $ref dereferencing in tool schemas and a task capabilities location fix.
+
+## What's Changed
+### Enhancements 🔧
+* Add release notes for v2.14.2 and v2.14.3 by [@jlowin](https://github.com/jlowin) in [#2851](https://github.com/PrefectHQ/fastmcp/pull/2851)
+### Fixes 🐞
+* Backport: Dereference $ref in tool schemas for MCP client compatibility by [@jlowin](https://github.com/jlowin) in [#2861](https://github.com/PrefectHQ/fastmcp/pull/2861)
+* Fix task capabilities location (issue #2870) by [@jlowin](https://github.com/jlowin) in [#2874](https://github.com/PrefectHQ/fastmcp/pull/2874)
+* Add missing packaging dependency by [@jlowin](https://github.com/jlowin) in [#2989](https://github.com/PrefectHQ/fastmcp/pull/2989)
+
+**Full Changelog**: [v2.14.3...v2.14.4](https://github.com/PrefectHQ/fastmcp/compare/v2.14.3...v2.14.4)
+
+</Update>
+
+<Update label="v2.14.3" description="2026-01-12">
+
+**[v2.14.3: Time After Timeout](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.3)**
+
+Sometimes five seconds just isn't enough. This release fixes an HTTP transport bug that was cutting connections short, along with OAuth and Redis fixes, better ASGI support, and CLI update notifications so you never miss a beat.
+
+## What's Changed
+### Enhancements 🔧
+* Add debug logging for OAuth token expiry diagnostics by [@jlowin](https://github.com/jlowin) in [#2789](https://github.com/PrefectHQ/fastmcp/pull/2789)
+* Add CLI update notifications by [@jlowin](https://github.com/jlowin) in [#2839](https://github.com/PrefectHQ/fastmcp/pull/2839)
+* Use pip instead of uv pip in upgrade instructions by [@jlowin](https://github.com/jlowin) in [#2841](https://github.com/PrefectHQ/fastmcp/pull/2841)
+### Fixes 🐞
+* Backport OAuth token storage TTL fix to release/2.x by [@jlowin](https://github.com/jlowin) in [#2798](https://github.com/PrefectHQ/fastmcp/pull/2798)
+* Prefix Redis keys with docket name for ACL isolation (2.x backport) by [@chrisguidry](https://github.com/chrisguidry) in [#2812](https://github.com/PrefectHQ/fastmcp/pull/2812)
+* Fix ContextVar propagation for ASGI-mounted servers with tasks by [@chrisguidry](https://github.com/chrisguidry) in [#2843](https://github.com/PrefectHQ/fastmcp/pull/2843)
+* Fix HTTP transport timeout defaulting to 5 seconds by [@jlowin](https://github.com/jlowin) in [#2848](https://github.com/PrefectHQ/fastmcp/pull/2848)
+
+**Full Changelog**: [v2.14.2...v2.14.3](https://github.com/PrefectHQ/fastmcp/compare/v2.14.2...v2.14.3)
+
+</Update>
+
+<Update label="v2.14.2" description="2025-12-31">
+
+**[v2.14.2: Port Authority](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.2)**
+
+FastMCP 2.14.2 brings a wave of community contributions safely into the 2.x line. A variety of important fixes backported from 3.0 work improve OpenAPI 3.1 compatibility, MCP spec compliance for output schemas and elicitation, and correct a subtle base_url fallback issue. The CLI now gently reminds you that FastMCP 3.0 is on the horizon.
+
+## What's Changed
+### Enhancements 🔧
+* Pin MCP under 2.x by [@jlowin](https://github.com/jlowin) in [#2709](https://github.com/PrefectHQ/fastmcp/pull/2709)
+* Add auth_route parameter to SupabaseProvider by [@EloiZalczer](https://github.com/EloiZalczer) in [#2760](https://github.com/PrefectHQ/fastmcp/pull/2760)
+* Update CLI banner with FastMCP 3.0 notice by [@jlowin](https://github.com/jlowin) in [#2765](https://github.com/PrefectHQ/fastmcp/pull/2765)
+### Fixes 🐞
+* Let FastMCPError propagate unchanged from managers by [@jlowin](https://github.com/jlowin) in [#2697](https://github.com/PrefectHQ/fastmcp/pull/2697)
+* Fix test cleanup for uvicorn 0.39+ context isolation by [@jlowin](https://github.com/jlowin) in [#2696](https://github.com/PrefectHQ/fastmcp/pull/2696)
+* Bump pydocket to 0.16.3 to fix worker cleanup race condition by [@chrisguidry](https://github.com/chrisguidry) in [#2700](https://github.com/PrefectHQ/fastmcp/pull/2700)
+* Fix Prefect website URL in docs footer by [@mgoldsborough](https://github.com/mgoldsborough) in [#2705](https://github.com/PrefectHQ/fastmcp/pull/2705)
+* Fix: resolve root-level $ref in outputSchema for MCP spec compliance by [@majiayu000](https://github.com/majiayu000) in [#2727](https://github.com/PrefectHQ/fastmcp/pull/2727)
+* Fix OAuth Proxy resource parameter validation by [@jlowin](https://github.com/jlowin) in [#2763](https://github.com/PrefectHQ/fastmcp/pull/2763)
+* Fix openapi_version check to include 3.1 by [@deeleeramone](https://github.com/deeleeramone) in [#2769](https://github.com/PrefectHQ/fastmcp/pull/2769)
+* Fix titled enum elicitation schema to comply with MCP spec by [@jlowin](https://github.com/jlowin) in [#2774](https://github.com/PrefectHQ/fastmcp/pull/2774)
+* Fix base_url fallback when url is not set by [@bhbs](https://github.com/bhbs) in [#2782](https://github.com/PrefectHQ/fastmcp/pull/2782)
+* Lazy import DiskStore to avoid sqlite3 dependency on import by [@jlowin](https://github.com/jlowin) in [#2785](https://github.com/PrefectHQ/fastmcp/pull/2785)
+### Docs 📚
+* Add v3 breaking changes notice to README and docs by [@jlowin](https://github.com/jlowin) in [#2713](https://github.com/PrefectHQ/fastmcp/pull/2713)
+* Add changelog entries for v2.13.1 through v2.14.1 by [@jlowin](https://github.com/jlowin) in [#2724](https://github.com/PrefectHQ/fastmcp/pull/2724)
+* conference to 2.x branch by [@aaazzam](https://github.com/aaazzam) in [#2787](https://github.com/PrefectHQ/fastmcp/pull/2787)
+
+**Full Changelog**: [v2.14.1...v2.14.2](https://github.com/PrefectHQ/fastmcp/compare/v2.14.1...v2.14.2)
+
+</Update>
+
+<Update label="v2.14.1" description="2025-12-15">
+
+**[v2.14.1: 'Tis a Gift to Be Sample](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.1)**
+
+FastMCP 2.14.1 introduces sampling with tools (SEP-1577), enabling servers to pass tools to `ctx.sample()` for agentic workflows where the LLM can automatically execute tool calls in a loop. The new `ctx.sample_step()` method provides single LLM calls that return `SampleStep` objects for custom control flow, while `result_type` enables structured outputs via validated Pydantic models.
+
+🤖 **AnthropicSamplingHandler** joins the existing OpenAI handler, providing multi-provider sampling support out of the box.
+
+⚡ **OpenAISamplingHandler promoted** from experimental status—sampling handlers are now production-ready with a unified API.
+
+## What's Changed
+### New Features 🎉
+* Sampling with tools by [@jlowin](https://github.com/jlowin) in [#2538](https://github.com/PrefectHQ/fastmcp/pull/2538)
+* Add AnthropicSamplingHandler by [@jlowin](https://github.com/jlowin) in [#2677](https://github.com/PrefectHQ/fastmcp/pull/2677)
+### Enhancements 🔧
+* Add Python 3.13 to ubuntu CI by [@jlowin](https://github.com/jlowin) in [#2648](https://github.com/PrefectHQ/fastmcp/pull/2648)
+* Remove legacy task initialization workaround by [@jlowin](https://github.com/jlowin) in [#2649](https://github.com/PrefectHQ/fastmcp/pull/2649)
+* Consolidate session state reset logic by [@jlowin](https://github.com/jlowin) in [#2651](https://github.com/PrefectHQ/fastmcp/pull/2651)
+* Unify SamplingHandler; promote OpenAI from experimental by [@jlowin](https://github.com/jlowin) in [#2656](https://github.com/PrefectHQ/fastmcp/pull/2656)
+* Add `tool_names` parameter to mount() for name customization by [@jlowin](https://github.com/jlowin) in [#2660](https://github.com/PrefectHQ/fastmcp/pull/2660)
+* Use streamable HTTP client API from MCP SDK by [@jlowin](https://github.com/jlowin) in [#2678](https://github.com/PrefectHQ/fastmcp/pull/2678)
+* Deprecate `exclude_args` in favor of Depends() by [@jlowin](https://github.com/jlowin) in [#2693](https://github.com/PrefectHQ/fastmcp/pull/2693)
+### Fixes 🐞
+* Fix prompt tasks to return mcp.types.PromptMessage by [@jlowin](https://github.com/jlowin) in [#2650](https://github.com/PrefectHQ/fastmcp/pull/2650)
+* Fix Windows test warnings by [@jlowin](https://github.com/jlowin) in [#2653](https://github.com/PrefectHQ/fastmcp/pull/2653)
+* Cleanup cancelled connection startup by [@jlowin](https://github.com/jlowin) in [#2679](https://github.com/PrefectHQ/fastmcp/pull/2679)
+* Fix tool choice bug in sampling examples by [@shawnthapa](https://github.com/shawnthapa) in [#2686](https://github.com/PrefectHQ/fastmcp/pull/2686)
+### Docs 📚
+* Simplify Docket tip wording by [@chrisguidry](https://github.com/chrisguidry) in [#2662](https://github.com/PrefectHQ/fastmcp/pull/2662)
+### Other Changes 🦾
+* Bump pydocket to ≥0.15.5 by [@jlowin](https://github.com/jlowin) in [#2694](https://github.com/PrefectHQ/fastmcp/pull/2694)
+
+## New Contributors
+* [@shawnthapa](https://github.com/shawnthapa) made their first contribution in [#2686](https://github.com/PrefectHQ/fastmcp/pull/2686)
+
+**Full Changelog**: [v2.14.0...v2.14.1](https://github.com/PrefectHQ/fastmcp/compare/v2.14.0...v2.14.1)
+
+</Update>
+
+<Update label="v2.14.0" description="2025-12-11">
+
+**[v2.14.0: Task and You Shall Receive](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.0)**
+
+FastMCP 2.14 begins adopting the MCP 2025-11-25 specification, introducing protocol-native background tasks (SEP-1686) that enable long-running operations to report progress without blocking clients. The experimental OpenAPI parser graduates to standard, the `OpenAISamplingHandler` is promoted from experimental, and deprecated APIs accumulated across the 2.x series are removed.
+
+⏳ **Background Tasks** let you add `task=True` to any async tool decorator to run operations in the background with progress tracking. Powered by [Docket](https://github.com/chrisguidry/docket), an enterprise task scheduler handling millions of concurrent tasks daily—in-memory backends work out-of-the-box, and Redis URLs enable persistence and horizontal scaling.
+
+🔧 **OpenAPI Parser Promoted** from experimental to standard with improved performance through single-pass schema processing and cleaner abstractions.
+
+📋 **MCP 2025-11-25 Specification Support** including SSE polling and event resumability (SEP-1699), multi-select enum elicitation schemas (SEP-1330), default values for elicitation (SEP-1034), and tool name validation at registration time (SEP-986).
+
+## Breaking Changes
+- Docket is always enabled; task execution is forbidden through proxies
+- Task protocol enabled by default
+- Removed deprecated settings, imports, and methods accumulated across 2.x series
+
+## What's Changed
+### New Features 🎉
+* OpenAPI parser is now the default by [@jlowin](https://github.com/jlowin) in [#2583](https://github.com/PrefectHQ/fastmcp/pull/2583)
+* Implement SEP-1686: Background Tasks by [@jlowin](https://github.com/jlowin) in [#2550](https://github.com/PrefectHQ/fastmcp/pull/2550)
+### Enhancements 🔧
+* Expose InitializeResult in middleware by [@jlowin](https://github.com/jlowin) in [#2562](https://github.com/PrefectHQ/fastmcp/pull/2562)
+* Update MCP SDK auth compatibility by [@jlowin](https://github.com/jlowin) in [#2574](https://github.com/PrefectHQ/fastmcp/pull/2574)
+* Validate tool names at registration (SEP-986) by [@jlowin](https://github.com/jlowin) in [#2588](https://github.com/PrefectHQ/fastmcp/pull/2588)
+* Support SEP-1034 and SEP-1330 for elicitation by [@jlowin](https://github.com/jlowin) in [#2595](https://github.com/PrefectHQ/fastmcp/pull/2595)
+* Implement SSE polling (SEP-1699) by [@jlowin](https://github.com/jlowin) in [#2612](https://github.com/PrefectHQ/fastmcp/pull/2612)
+* Expose session ID callback by [@jlowin](https://github.com/jlowin) in [#2628](https://github.com/PrefectHQ/fastmcp/pull/2628)
+### Fixes 🐞
+* Fix OAuth metadata discovery by [@jlowin](https://github.com/jlowin) in [#2565](https://github.com/PrefectHQ/fastmcp/pull/2565)
+* Fix fastapi.cli package structure by [@jlowin](https://github.com/jlowin) in [#2570](https://github.com/PrefectHQ/fastmcp/pull/2570)
+* Correct OAuth error codes by [@jlowin](https://github.com/jlowin) in [#2578](https://github.com/PrefectHQ/fastmcp/pull/2578)
+* Prevent function signature modification by [@jlowin](https://github.com/jlowin) in [#2590](https://github.com/PrefectHQ/fastmcp/pull/2590)
+* Fix proxy client kwargs by [@jlowin](https://github.com/jlowin) in [#2605](https://github.com/PrefectHQ/fastmcp/pull/2605)
+* Fix nested server routing by [@jlowin](https://github.com/jlowin) in [#2618](https://github.com/PrefectHQ/fastmcp/pull/2618)
+* Use access token expiry fallback by [@jlowin](https://github.com/jlowin) in [#2635](https://github.com/PrefectHQ/fastmcp/pull/2635)
+* Handle transport cleanup exceptions by [@jlowin](https://github.com/jlowin) in [#2642](https://github.com/PrefectHQ/fastmcp/pull/2642)
+### Docs 📚
+* Add OCI and Supabase integration docs by [@jlowin](https://github.com/jlowin) in [#2580](https://github.com/PrefectHQ/fastmcp/pull/2580)
+* Add v2.14.0 upgrade guide by [@jlowin](https://github.com/jlowin) in [#2598](https://github.com/PrefectHQ/fastmcp/pull/2598)
+* Rewrite background tasks documentation by [@jlowin](https://github.com/jlowin) in [#2620](https://github.com/PrefectHQ/fastmcp/pull/2620)
+* Document read-only tool patterns by [@jlowin](https://github.com/jlowin) in [#2632](https://github.com/PrefectHQ/fastmcp/pull/2632)
+
+## New Contributors
+11 total contributors including 7 first-time participants.
+
+**Full Changelog**: [v2.13.3...v2.14.0](https://github.com/PrefectHQ/fastmcp/compare/v2.13.3...v2.14.0)
+
+</Update>
+
+<Update label="v2.13.3" description="2025-12-03">
+
+**[v2.13.3: Pin-ish Line](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.3)**
+
+FastMCP 2.13.3 pins `mcp<1.23` as a precautionary measure. MCP SDK 1.23 introduced changes related to the November 25, 2025 MCP protocol update that break certain FastMCP patches and workarounds, particularly around OAuth implementation details. FastMCP 2.14 introduces proper support for the updated protocol and requires `mcp>=1.23`.
+
+## What's Changed
+### Fixes 🐞
+* Pin MCP SDK below 1.23 by [@jlowin](https://github.com/jlowin) in [#2545](https://github.com/PrefectHQ/fastmcp/pull/2545)
+
+**Full Changelog**: [v2.13.2...v2.13.3](https://github.com/PrefectHQ/fastmcp/compare/v2.13.2...v2.13.3)
+
+</Update>
+
+<Update label="v2.13.2" description="2025-12-01">
+
+**[v2.13.2: Refreshing Changes](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.2)**
+
+FastMCP 2.13.2 polishes the authentication stack with improvements to token refresh, scope handling, and multi-instance deployments. Discord was added as a built-in OAuth provider, Azure and Google token handling became more reliable, and proxy classes now properly forward icons and titles.
+
+## What's Changed
+### New Features 🎉
+* Add Discord OAuth provider by [@jlowin](https://github.com/jlowin) in [#2480](https://github.com/PrefectHQ/fastmcp/pull/2480)
+### Enhancements 🔧
+* Descope Provider updates for new well-known URLs by [@anvibanga](https://github.com/anvibanga) in [#2465](https://github.com/PrefectHQ/fastmcp/pull/2465)
+* Scalekit provider improvements by [@jlowin](https://github.com/jlowin) in [#2472](https://github.com/PrefectHQ/fastmcp/pull/2472)
+* Add CSP customization for consent screens by [@jlowin](https://github.com/jlowin) in [#2488](https://github.com/PrefectHQ/fastmcp/pull/2488)
+* Add icon support to proxy classes by [@jlowin](https://github.com/jlowin) in [#2495](https://github.com/PrefectHQ/fastmcp/pull/2495)
+### Fixes 🐞
+* Google Provider now defaults to refresh token support by [@jlowin](https://github.com/jlowin) in [#2468](https://github.com/PrefectHQ/fastmcp/pull/2468)
+* Fix Azure OAuth token refresh with unprefixed scopes by [@jlowin](https://github.com/jlowin) in [#2475](https://github.com/PrefectHQ/fastmcp/pull/2475)
+* Prevent `$defs` mutation during tool transforms by [@jlowin](https://github.com/jlowin) in [#2482](https://github.com/PrefectHQ/fastmcp/pull/2482)
+* Fix OAuth proxy refresh token storage for multi-instance deployments by [@jlowin](https://github.com/jlowin) in [#2490](https://github.com/PrefectHQ/fastmcp/pull/2490)
+* Fix stale token issue after OAuth refresh by [@jlowin](https://github.com/jlowin) in [#2498](https://github.com/PrefectHQ/fastmcp/pull/2498)
+* Fix Azure provider OIDC scope handling by [@jlowin](https://github.com/jlowin) in [#2505](https://github.com/PrefectHQ/fastmcp/pull/2505)
+
+## New Contributors
+7 new contributors made their first FastMCP contributions in this release.
+
+**Full Changelog**: [v2.13.1...v2.13.2](https://github.com/PrefectHQ/fastmcp/compare/v2.13.1...v2.13.2)
+
+</Update>
+
+<Update label="v2.13.1" description="2025-11-15">
+
+**[v2.13.1: Heavy Meta](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.1)**
+
+FastMCP 2.13.1 introduces meta parameter support for `ToolResult`, enabling tools to return supplementary metadata alongside results. This supports emerging use cases like OpenAI's Apps SDK. The release also brings improved OAuth functionality with custom token verifiers including a new DebugTokenVerifier, and adds OCI and Supabase authentication providers.
+
+🏷️ **Meta parameters for ToolResult** enable tools to return supplementary metadata alongside results, supporting patterns like OpenAI's Apps SDK integration.
+
+🔐 **Custom token verifiers** with DebugTokenVerifier for development, plus Azure Government support through a `base_authority` parameter and Supabase authentication algorithm configuration.
+
+🔒 **Security fixes** address CVE-2025-61920 through authlib updates and validate Cursor deeplink URLs using safer Windows APIs.
+
+## What's Changed
+### New Features 🎉
+* Add meta parameter support for ToolResult by [@jlowin](https://github.com/jlowin) in [#2350](https://github.com/PrefectHQ/fastmcp/pull/2350)
+* Add OCI authentication provider by [@jlowin](https://github.com/jlowin) in [#2365](https://github.com/PrefectHQ/fastmcp/pull/2365)
+* Add Supabase authentication provider by [@jlowin](https://github.com/jlowin) in [#2378](https://github.com/PrefectHQ/fastmcp/pull/2378)
+### Enhancements 🔧
+* Add custom token verifier support to OIDCProxy by [@jlowin](https://github.com/jlowin) in [#2355](https://github.com/PrefectHQ/fastmcp/pull/2355)
+* Add DebugTokenVerifier for development by [@jlowin](https://github.com/jlowin) in [#2362](https://github.com/PrefectHQ/fastmcp/pull/2362)
+* Add Azure Government support via base_authority parameter by [@jlowin](https://github.com/jlowin) in [#2385](https://github.com/PrefectHQ/fastmcp/pull/2385)
+* Add Supabase authentication algorithm configuration by [@jlowin](https://github.com/jlowin) in [#2392](https://github.com/PrefectHQ/fastmcp/pull/2392)
+### Fixes 🐞
+* Security: Update authlib for CVE-2025-61920 by [@jlowin](https://github.com/jlowin) in [#2398](https://github.com/PrefectHQ/fastmcp/pull/2398)
+* Validate Cursor deeplink URLs using safer Windows APIs by [@jlowin](https://github.com/jlowin) in [#2405](https://github.com/PrefectHQ/fastmcp/pull/2405)
+* Exclude MCP SDK 1.21.1 due to integration test failures by [@jlowin](https://github.com/jlowin) in [#2422](https://github.com/PrefectHQ/fastmcp/pull/2422)
+
+## New Contributors
+18 new contributors joined in this release across 70+ pull requests.
+
+**Full Changelog**: [v2.13.0...v2.13.1](https://github.com/PrefectHQ/fastmcp/compare/v2.13.0...v2.13.1)
+
+</Update>
+
+<Update label="v2.13.0" description="2025-10-25">
+
+**[v2.13.0: Cache Me If You Can](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.0)**
+
+FastMCP 2.13 "Cache Me If You Can" represents a fundamental maturation of the framework. After months of community feedback on authentication and state management, this release delivers the infrastructure FastMCP needs to handle production workloads: persistent storage, response caching, and pragmatic OAuth improvements that reflect real-world deployment challenges.
+
+💾 **Pluggable storage backends** bring persistent state to FastMCP servers. Built on [py-key-value-aio](https://github.com/strawgate/py-key-value), a new library from FastMCP maintainer Bill Easton ([@strawgate](https://github.com/strawgate)), the storage layer provides encrypted disk storage by default, platform-aware token management, and a simple key-value interface for application state. We're excited to bring this elegantly designed library into the FastMCP ecosystem - it's both powerful and remarkably easy to use, including wrappers to add encryption, TTLs, caching, and more to backends ranging from Elasticsearch, Redis, DynamoDB, filesystem, in-memory, and more! OAuth providers now automatically persist tokens across restarts, and developers can store arbitrary state without reaching for external databases. This foundation enables long-running sessions, cached credentials, and stateful applications built on MCP.
+
+🔐 **OAuth maturity** brings months of production learnings into the framework. The new consent screen prevents confused deputy and authorization bypass attacks discovered in earlier versions while providing a clean UX with customizable branding. The OAuth proxy now issues its own tokens with automatic key derivation from client secrets, and RFC 7662 token introspection support enables enterprise auth flows. Path prefix mounting enables OAuth-protected servers to integrate into existing web applications under custom paths like `/api`, and MCP 1.17+ compliance with RFC 9728 ensures protocol compatibility. Combined with improved error handling and platform-aware token storage, OAuth is now production-ready and security-hardened for serious applications.
+
+FastMCP now supports out-of-the-box authentication with:
+- **[WorkOS](https://gofastmcp.com/integrations/workos)** and **[AuthKit](https://gofastmcp.com/integrations/authkit)**
+- **[GitHub](https://gofastmcp.com/integrations/github)**
+- **[Google](https://gofastmcp.com/integrations/google)**
+- **[Azure](https://gofastmcp.com/integrations/azure)** (Entra ID)
+- **[AWS Cognito](https://gofastmcp.com/integrations/aws-cognito)**
+- **[Auth0](https://gofastmcp.com/integrations/auth0)**
+- **[Descope](https://gofastmcp.com/integrations/descope)**
+- **[Scalekit](https://gofastmcp.com/integrations/scalekit)**
+- **[JWTs](https://gofastmcp.com/servers/auth/token-verification#jwt-token-verification)**
+- **[RFC 7662 token introspection](https://gofastmcp.com/servers/auth/token-verification#token-introspection-protocol)**
+
+⚡ **Response Caching Middleware** dramatically improves performance for expensive operations. Cache tool and resource responses with configurable TTLs, reducing redundant API calls and speeding up repeated queries.
+
+🔄 **Server lifespans** provide proper initialization and cleanup hooks that run once per server instance instead of per client session. This fixes a long-standing source of confusion in the MCP SDK and enables proper resource management for database connections, background tasks, and other server-level state. Note: this is a breaking behavioral change if you were using the `lifespan` parameter.
+
+✨ **Developer experience improvements** include Pydantic input validation for better type safety, icon support for richer UX, RFC 6570 query parameters for resource templates, improved Context API methods (list_resources, list_prompts, get_prompt), and async file/directory resources.
+
+This release includes contributions from **20** new contributors and represents the largest feature set in a while. Thank you to everyone who tested preview builds and filed issues - your feedback shaped these improvements!
+
+**Full Changelog**: [v2.12.5...v2.13.0](https://github.com/PrefectHQ/fastmcp/compare/v2.12.5...v2.13.0)
+
+</Update>
+
+<Update label="v2.12.5" description="2025-10-17">
+
+**[v2.12.5: Safety Pin](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.5)**
+
+FastMCP 2.12.5 is a point release that pins the MCP SDK version below 1.17, which introduced a change affecting FastMCP users with auth providers mounted as part of a larger application. This ensures the `.well-known` payload appears in the expected location when using FastMCP authentication providers with composite applications.
+
+## What's Changed
+
+### Fixes 🐞
+* Pin MCP SDK version below 1.17 by [@jlowin](https://github.com/jlowin) in [a1b2c3d](https://github.com/PrefectHQ/fastmcp/commit/dab2b316ddc3883b7896a86da21cacb68da01e5c)
+
+**Full Changelog**: [v2.12.4...v2.12.5](https://github.com/PrefectHQ/fastmcp/compare/v2.12.4...v2.12.5)
+
+</Update>
+
+<Update label="v2.12.4" description="2025-09-26">
+
+**[v2.12.4: OIDC What You Did There](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.4)**
+
+FastMCP 2.12.4 adds comprehensive OIDC support and expands authentication options with AWS Cognito and Descope providers. The release also includes improvements to logging middleware, URL handling for nested resources, persistent OAuth client registration storage, and various fixes to the experimental OpenAPI parser.
+
+## What's Changed
+### New Features 🎉
+* feat: Add support for OIDC configuration by [@ruhulio](https://github.com/ruhulio) in [#1817](https://github.com/PrefectHQ/fastmcp/pull/1817)
+### Enhancements 🔧
+* feat: Move the Starlette context middleware to the front by [@akkuman](https://github.com/akkuman) in [#1812](https://github.com/PrefectHQ/fastmcp/pull/1812)
+* Refactor Logging and Structured Logging Middleware by [@strawgate](https://github.com/strawgate) in [#1805](https://github.com/PrefectHQ/fastmcp/pull/1805)
+* Update pull_request_template.md by [@jlowin](https://github.com/jlowin) in [#1824](https://github.com/PrefectHQ/fastmcp/pull/1824)
+* chore: Set redirect_path default in function by [@ruhulio](https://github.com/ruhulio) in [#1833](https://github.com/PrefectHQ/fastmcp/pull/1833)
+* feat: Set instructions in code by [@attiks](https://github.com/attiks) in [#1838](https://github.com/PrefectHQ/fastmcp/pull/1838)
+* Automatically Create inline Snapshots by [@strawgate](https://github.com/strawgate) in [#1779](https://github.com/PrefectHQ/fastmcp/pull/1779)
+* chore: Cleanup Auth0 redirect_path initialization by [@ruhulio](https://github.com/ruhulio) in [#1842](https://github.com/PrefectHQ/fastmcp/pull/1842)
+* feat: Add support for Descope Authentication by [@anvibanga](https://github.com/anvibanga) in [#1853](https://github.com/PrefectHQ/fastmcp/pull/1853)
+* Update descope version badges by [@jlowin](https://github.com/jlowin) in [#1870](https://github.com/PrefectHQ/fastmcp/pull/1870)
+* Update welcome images by [@jlowin](https://github.com/jlowin) in [#1884](https://github.com/PrefectHQ/fastmcp/pull/1884)
+* Fix rounded edges of image by [@jlowin](https://github.com/jlowin) in [#1886](https://github.com/PrefectHQ/fastmcp/pull/1886)
+* optimize test suite by [@zzstoatzz](https://github.com/zzstoatzz) in [#1893](https://github.com/PrefectHQ/fastmcp/pull/1893)
+* Enhancement: client completions support context_arguments by [@isijoe](https://github.com/isijoe) in [#1906](https://github.com/PrefectHQ/fastmcp/pull/1906)
+* Update Descope icon by [@anvibanga](https://github.com/anvibanga) in [#1912](https://github.com/PrefectHQ/fastmcp/pull/1912)
+* Add AWS Cognito OAuth Provider for Enterprise Authentication by [@stephaneberle9](https://github.com/stephaneberle9) in [#1873](https://github.com/PrefectHQ/fastmcp/pull/1873)
+* Fix typos discovered by codespell by [@cclauss](https://github.com/cclauss) in [#1922](https://github.com/PrefectHQ/fastmcp/pull/1922)
+* Use lowercase namespace for fastmcp logger by [@jlowin](https://github.com/jlowin) in [#1791](https://github.com/PrefectHQ/fastmcp/pull/1791)
+### Fixes 🐞
+* Update quickstart.mdx by [@radi-dev](https://github.com/radi-dev) in [#1821](https://github.com/PrefectHQ/fastmcp/pull/1821)
+* Remove extraneous union import by [@jlowin](https://github.com/jlowin) in [#1823](https://github.com/PrefectHQ/fastmcp/pull/1823)
+* Delay import of Provider classes until FastMCP Server Creation by [@strawgate](https://github.com/strawgate) in [#1820](https://github.com/PrefectHQ/fastmcp/pull/1820)
+* fix: correct documentation link in deprecation warning by [@strawgate](https://github.com/strawgate) in [#1828](https://github.com/PrefectHQ/fastmcp/pull/1828)
+* fix: Increase default 3s timeout on Pytest by [@dacamposol](https://github.com/dacamposol) in [#1866](https://github.com/PrefectHQ/fastmcp/pull/1866)
+* fix: Improve URL handling in OIDCConfiguration by [@ruhulio](https://github.com/ruhulio) in [#1850](https://github.com/PrefectHQ/fastmcp/pull/1850)
+* fix: correct typing for on_read_resource middleware method by [@strawgate](https://github.com/strawgate) in [#1858](https://github.com/PrefectHQ/fastmcp/pull/1858)
+* feat(experimental/openapi): replace $ref in additionalProperties; add tests by [@jlowin](https://github.com/jlowin) in [#1735](https://github.com/PrefectHQ/fastmcp/pull/1735)
+* Honor client supplied scopes during registration by [@dmikusa](https://github.com/dmikusa) in [#1860](https://github.com/PrefectHQ/fastmcp/pull/1860)
+* Fix: FastAPI list parameter parsing in experimental OpenAPI parser by [@jlowin](https://github.com/jlowin) in [#1834](https://github.com/PrefectHQ/fastmcp/pull/1834)
+* Add log level support for stdio and HTTP transports by [@jlowin](https://github.com/jlowin) in [#1840](https://github.com/PrefectHQ/fastmcp/pull/1840)
+* Fix OAuth pre-flight check to accept HTTP 200 responses by [@jlowin](https://github.com/jlowin) in [#1874](https://github.com/PrefectHQ/fastmcp/pull/1874)
+* Fix: Preserve OpenAPI parameter descriptions in experimental parser by [@shlomo666](https://github.com/shlomo666) in [#1877](https://github.com/PrefectHQ/fastmcp/pull/1877)
+* Add persistent storage for OAuth client registrations by [@jlowin](https://github.com/jlowin) in [#1879](https://github.com/PrefectHQ/fastmcp/pull/1879)
+* docs: update release dates based on github releases by [@lodu](https://github.com/lodu) in [#1890](https://github.com/PrefectHQ/fastmcp/pull/1890)
+* Small updates to Sampling types by [@strawgate](https://github.com/strawgate) in [#1882](https://github.com/PrefectHQ/fastmcp/pull/1882)
+* remove lockfile smart_home example by [@zzstoatzz](https://github.com/zzstoatzz) in [#1892](https://github.com/PrefectHQ/fastmcp/pull/1892)
+* Fix: Remove JSON schema title metadata while preserving parameters named 'title' by [@jlowin](https://github.com/jlowin) in [#1872](https://github.com/PrefectHQ/fastmcp/pull/1872)
+* Fix: get_resource_url nested URL handling by [@raphael-linx](https://github.com/raphael-linx) in [#1914](https://github.com/PrefectHQ/fastmcp/pull/1914)
+* Clean up code for creating the resource url by [@jlowin](https://github.com/jlowin) in [#1916](https://github.com/PrefectHQ/fastmcp/pull/1916)
+* Fix route count logging in OpenAPI server by [@zzstoatzz](https://github.com/zzstoatzz) in [#1928](https://github.com/PrefectHQ/fastmcp/pull/1928)
+### Docs 📚
+* docs: make Gemini CLI integration discoverable by [@jackwotherspoon](https://github.com/jackwotherspoon) in [#1827](https://github.com/PrefectHQ/fastmcp/pull/1827)
+* docs: update NEW tags for AI assistant integrations by [@jackwotherspoon](https://github.com/jackwotherspoon) in [#1829](https://github.com/PrefectHQ/fastmcp/pull/1829)
+* Update wordmark by [@jlowin](https://github.com/jlowin) in [#1832](https://github.com/PrefectHQ/fastmcp/pull/1832)
+* docs: improve OAuth and OIDC Proxy documentation by [@jlowin](https://github.com/jlowin) in [#1880](https://github.com/PrefectHQ/fastmcp/pull/1880)
+* Update readme + welcome docs by [@jlowin](https://github.com/jlowin) in [#1883](https://github.com/PrefectHQ/fastmcp/pull/1883)
+* Update dark mode image in README by [@jlowin](https://github.com/jlowin) in [#1885](https://github.com/PrefectHQ/fastmcp/pull/1885)
+
+## New Contributors
+* [@radi-dev](https://github.com/radi-dev) made their first contribution in [#1821](https://github.com/PrefectHQ/fastmcp/pull/1821)
+* [@akkuman](https://github.com/akkuman) made their first contribution in [#1812](https://github.com/PrefectHQ/fastmcp/pull/1812)
+* [@ruhulio](https://github.com/ruhulio) made their first contribution in [#1817](https://github.com/PrefectHQ/fastmcp/pull/1817)
+* [@attiks](https://github.com/attiks) made their first contribution in [#1838](https://github.com/PrefectHQ/fastmcp/pull/1838)
+* [@anvibanga](https://github.com/anvibanga) made their first contribution in [#1853](https://github.com/PrefectHQ/fastmcp/pull/1853)
+* [@shlomo666](https://github.com/shlomo666) made their first contribution in [#1877](https://github.com/PrefectHQ/fastmcp/pull/1877)
+* [@lodu](https://github.com/lodu) made their first contribution in [#1890](https://github.com/PrefectHQ/fastmcp/pull/1890)
+* [@isijoe](https://github.com/isijoe) made their first contribution in [#1906](https://github.com/PrefectHQ/fastmcp/pull/1906)
+* [@raphael-linx](https://github.com/raphael-linx) made their first contribution in [#1914](https://github.com/PrefectHQ/fastmcp/pull/1914)
+* [@stephaneberle9](https://github.com/stephaneberle9) made their first contribution in [#1873](https://github.com/PrefectHQ/fastmcp/pull/1873)
+* [@cclauss](https://github.com/cclauss) made their first contribution in [#1922](https://github.com/PrefectHQ/fastmcp/pull/1922)
+
+**Full Changelog**: [v2.12.3...v2.12.4](https://github.com/PrefectHQ/fastmcp/compare/v2.12.3...v2.12.4)
+
+</Update>
+
+<Update label="v2.12.3" description="2025-09-17">
+
+**[v2.12.3: Double Time](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.3)**
+
+FastMCP 2.12.3 focuses on performance and developer experience improvements based on community feedback. This release includes optimized auth provider imports that reduce server startup time, enhanced OIDC authentication flows with proper token management, and several reliability fixes for OAuth proxy configurations. The addition of automatic inline snapshot creation significantly improves the testing experience for contributors.
+
+## What's Changed
+### New Features 🎉
+* feat: Support setting MCP log level via transport configuration by [@jlowin](https://github.com/jlowin) in [#1756](https://github.com/PrefectHQ/fastmcp/pull/1756)
+### Enhancements 🔧
+* Add client-side auth support for mcp install cursor command by [@jlowin](https://github.com/jlowin) in [#1747](https://github.com/PrefectHQ/fastmcp/pull/1747)
+* Automatically Create inline Snapshots by [@strawgate](https://github.com/strawgate) in [#1779](https://github.com/PrefectHQ/fastmcp/pull/1779)
+* Use lowercase namespace for fastmcp logger by [@jlowin](https://github.com/jlowin) in [#1791](https://github.com/PrefectHQ/fastmcp/pull/1791)
+### Fixes 🐞
+* fix: correct merge mistake during auth0 refactor by [@strawgate](https://github.com/strawgate) in [#1742](https://github.com/PrefectHQ/fastmcp/pull/1742)
+* Remove extraneous union import by [@jlowin](https://github.com/jlowin) in [#1823](https://github.com/PrefectHQ/fastmcp/pull/1823)
+* Delay import of Provider classes until FastMCP Server Creation by [@strawgate](https://github.com/strawgate) in [#1820](https://github.com/PrefectHQ/fastmcp/pull/1820)
+* fix: refactor OIDC configuration provider for proper token management by [@strawgate](https://github.com/strawgate) in [#1751](https://github.com/PrefectHQ/fastmcp/pull/1751)
+* Fix smart_home example imports by [@strawgate](https://github.com/strawgate) in [#1753](https://github.com/PrefectHQ/fastmcp/pull/1753)
+* fix: correct oauth proxy initialization of client by [@strawgate](https://github.com/strawgate) in [#1759](https://github.com/PrefectHQ/fastmcp/pull/1759)
+* Fix: return empty string when prompts have no arguments by [@jlowin](https://github.com/jlowin) in [#1766](https://github.com/PrefectHQ/fastmcp/pull/1766)
+* Fix async server callbacks by [@strawgate](https://github.com/strawgate) in [#1774](https://github.com/PrefectHQ/fastmcp/pull/1774)
+* Fix error when retrieving Completion API errors by [@strawgate](https://github.com/strawgate) in [#1785](https://github.com/PrefectHQ/fastmcp/pull/1785)
+* fix: correct documentation link in deprecation warning by [@strawgate](https://github.com/strawgate) in [#1828](https://github.com/PrefectHQ/fastmcp/pull/1828)
+### Docs 📚
+* Add migration docs for 2.12 by [@jlowin](https://github.com/jlowin) in [#1745](https://github.com/PrefectHQ/fastmcp/pull/1745)
+* Update docs for default sampling implementation to mention OpenAI API Key by [@strawgate](https://github.com/strawgate) in [#1763](https://github.com/PrefectHQ/fastmcp/pull/1763)
+* Add tip about sampling prompts and user_context to sampling documentation by [@jlowin](https://github.com/jlowin) in [#1764](https://github.com/PrefectHQ/fastmcp/pull/1764)
+* Update quickstart.mdx by [@radi-dev](https://github.com/radi-dev) in [#1821](https://github.com/PrefectHQ/fastmcp/pull/1821)
+### Other Changes 🦾
+* Replace Marvin with Claude Code in CI by [@jlowin](https://github.com/jlowin) in [#1800](https://github.com/PrefectHQ/fastmcp/pull/1800)
+* Refactor logging and structured logging middleware by [@strawgate](https://github.com/strawgate) in [#1805](https://github.com/PrefectHQ/fastmcp/pull/1805)
+* feat: Move the Starlette context middleware to the front by [@akkuman](https://github.com/akkuman) in [#1812](https://github.com/PrefectHQ/fastmcp/pull/1812)
+* feat: Add support for OIDC configuration by [@ruhulio](https://github.com/ruhulio) in [#1817](https://github.com/PrefectHQ/fastmcp/pull/1817)
+
+## New Contributors
+* [@radi-dev](https://github.com/radi-dev) made their first contribution in [#1821](https://github.com/PrefectHQ/fastmcp/pull/1821)
+* [@akkuman](https://github.com/akkuman) made their first contribution in [#1812](https://github.com/PrefectHQ/fastmcp/pull/1812)
+* [@ruhulio](https://github.com/ruhulio) made their first contribution in [#1817](https://github.com/PrefectHQ/fastmcp/pull/1817)
+
+**Full Changelog**: [v2.12.2...v2.12.3](https://github.com/PrefectHQ/fastmcp/compare/v2.12.2...v2.12.3)
+
+</Update>
+
+<Update label="v2.12.2" description="2025-09-03">
+
+**[v2.12.2: Perchance to Stream](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.2)**
+
+This is a hotfix for a bug where the `streamable-http` transport was not recognized as a valid option in `fastmcp.json` configuration files, despite being supported by the CLI. This resulted in a parsing error when the CLI arguments were merged against the configuration spec. 
+
+## What's Changed
+### Fixes 🐞
+* Fix streamable-http transport validation in fastmcp.json config by [@jlowin](https://github.com/jlowin) in [#1739](https://github.com/PrefectHQ/fastmcp/pull/1739)
+
+**Full Changelog**: [v2.12.1...v2.12.2](https://github.com/PrefectHQ/fastmcp/compare/v2.12.1...v2.12.2)
+
+</Update>
+
+<Update label="v2.12.1" description="2025-09-03">
+
+**[v2.12.1: OAuth to Joy](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.1)**
+
+FastMCP 2.12.1 strengthens the OAuth proxy implementation based on extensive community testing and feedback. This release improves client storage reliability, adds PKCE forwarding for enhanced security, introduces configurable token endpoint authentication methods, and expands scope handling—all addressing real-world integration challenges discovered since 2.12.0. The enhanced test suite with mock providers ensures these improvements are robust and maintainable.
+
+## Breaking Changes
+- **OAuth Proxy**: Users of built-in IDP integrations should note that `resource_server_url` has been renamed to `base_url` for clarity and consistency
+
+## What's Changed
+### Enhancements 🔧
+* Make openai dependency optional by [@jlowin](https://github.com/jlowin) in [#1701](https://github.com/PrefectHQ/fastmcp/pull/1701)
+* Remove orphaned OAuth proxy code by [@jlowin](https://github.com/jlowin) in [#1722](https://github.com/PrefectHQ/fastmcp/pull/1722)
+* Expose valid scopes from OAuthProxy metadata by [@dmikusa](https://github.com/dmikusa) in [#1717](https://github.com/PrefectHQ/fastmcp/pull/1717)
+* OAuth proxy PKCE forwarding by [@jlowin](https://github.com/jlowin) in [#1733](https://github.com/PrefectHQ/fastmcp/pull/1733)
+* Add token_endpoint_auth_method parameter to OAuthProxy by [@jlowin](https://github.com/jlowin) in [#1736](https://github.com/PrefectHQ/fastmcp/pull/1736)
+* Clean up and enhance OAuth proxy tests with mock provider by [@jlowin](https://github.com/jlowin) in [#1738](https://github.com/PrefectHQ/fastmcp/pull/1738)
+### Fixes 🐞
+* refactor: replace auth provider registry with ImportString by [@jlowin](https://github.com/jlowin) in [#1710](https://github.com/PrefectHQ/fastmcp/pull/1710)
+* Fix OAuth resource URL handling and WWW-Authenticate header by [@jlowin](https://github.com/jlowin) in [#1706](https://github.com/PrefectHQ/fastmcp/pull/1706)
+* Fix OAuth proxy client storage and add retry logic by [@jlowin](https://github.com/jlowin) in [#1732](https://github.com/PrefectHQ/fastmcp/pull/1732)
+### Docs 📚
+* Fix documentation: use StreamableHttpTransport for headers in testing by [@jlowin](https://github.com/jlowin) in [#1702](https://github.com/PrefectHQ/fastmcp/pull/1702)
+* docs: add performance warnings for mounted servers and proxies by [@strawgate](https://github.com/strawgate) in [#1669](https://github.com/PrefectHQ/fastmcp/pull/1669)
+* Update documentation around scopes for google by [@jlowin](https://github.com/jlowin) in [#1703](https://github.com/PrefectHQ/fastmcp/pull/1703)
+* Add deployment information to quickstart by [@seanpwlms](https://github.com/seanpwlms) in [#1433](https://github.com/PrefectHQ/fastmcp/pull/1433)
+* Update quickstart by [@jlowin](https://github.com/jlowin) in [#1728](https://github.com/PrefectHQ/fastmcp/pull/1728)
+* Add development docs for FastMCP by [@jlowin](https://github.com/jlowin) in [#1719](https://github.com/PrefectHQ/fastmcp/pull/1719)
+### Other Changes 🦾
+* Set generics without bounds to default=Any by [@strawgate](https://github.com/strawgate) in [#1648](https://github.com/PrefectHQ/fastmcp/pull/1648)
+
+## New Contributors
+* [@dmikusa](https://github.com/dmikusa) made their first contribution in [#1717](https://github.com/PrefectHQ/fastmcp/pull/1717)
+* [@seanpwlms](https://github.com/seanpwlms) made their first contribution in [#1433](https://github.com/PrefectHQ/fastmcp/pull/1433)
+
+**Full Changelog**: [v2.12.0...v2.12.1](https://github.com/PrefectHQ/fastmcp/compare/v2.12.0...v2.12.1)
+
+</Update>
+
+<Update label="v2.12.0" description="2025-08-31">
+
+**[v2.12.0: Auth to the Races](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.0)**
+
+FastMCP 2.12 represents one of our most significant releases to date, both in scope and community involvement. After extensive testing and iteration with the community, we're shipping major improvements to authentication, configuration, and MCP feature adoption.
+
+🔐 **OAuth Proxy for Broader Provider Support** addresses a fundamental challenge: while MCP requires Dynamic Client Registration (DCR), many popular OAuth providers don't support it. The new OAuth proxy bridges this gap, enabling FastMCP servers to authenticate with providers like GitHub, Google, WorkOS, and Azure through minimal configuration. These native integrations ship today, with more providers planned based on community needs.
+
+📋 **Declarative JSON Configuration** introduces a standardized, portable way to describe and deploy MCP servers. The `fastmcp.json` configuration file becomes the single source of truth for dependencies, transport settings, entrypoints, and server metadata. This foundation sets the stage for future capabilities like transformations and remote sources, moving toward a world where MCP servers are as portable and shareable as container images.
+
+🧠 **Sampling API Fallback** tackles the chicken-and-egg problem limiting adoption of advanced MCP features. Sampling—where servers request LLM completions from clients—is powerful but underutilized due to limited client support. FastMCP now lets server authors define fallback handlers that generate sampling completions server-side when clients don't support the feature, encouraging adoption while maintaining compatibility.
+
+This release took longer than usual to ship, and for good reason: the community's aggressive testing and feedback on the authentication system helped us reach a level of stability we're confident in. There's certainly more work ahead, but these foundations position FastMCP to handle increasingly complex use cases while remaining approachable for developers.
+
+Thank you to our new contributors and everyone who tested preview builds. Your feedback directly shaped these features.
+
+## What's Changed
+### New Features 🎉
+* Add OAuth proxy that allows authentication with social IDPs without DCR support by [@jlowin](https://github.com/jlowin) in [#1434](https://github.com/PrefectHQ/fastmcp/pull/1434)
+* feat: introduce declarative JSON configuration system by [@jlowin](https://github.com/jlowin) in [#1517](https://github.com/PrefectHQ/fastmcp/pull/1517)
+* ✨ Fallback to a Completions API when Sampling is not available by [@strawgate](https://github.com/strawgate) in [#1145](https://github.com/PrefectHQ/fastmcp/pull/1145)
+* Implement typed source system for FastMCP declarative configuration by [@jlowin](https://github.com/jlowin) in [#1607](https://github.com/PrefectHQ/fastmcp/pull/1607)
+### Enhancements 🔧
+* Support importing custom_route endpoints when mounting servers by [@jlowin](https://github.com/jlowin) in [#1470](https://github.com/PrefectHQ/fastmcp/pull/1470)
+* Remove unnecessary asserts by [@jlowin](https://github.com/jlowin) in [#1484](https://github.com/PrefectHQ/fastmcp/pull/1484)
+* Add Claude issue triage by [@jlowin](https://github.com/jlowin) in [#1510](https://github.com/PrefectHQ/fastmcp/pull/1510)
+* Inline dedupe prompt by [@jlowin](https://github.com/jlowin) in [#1512](https://github.com/PrefectHQ/fastmcp/pull/1512)
+* Improve stdio and mcp_config clean-up by [@strawgate](https://github.com/strawgate) in [#1444](https://github.com/PrefectHQ/fastmcp/pull/1444)
+* involve kwargs to pass parameters on creating RichHandler for logging customization. by [@itaru2622](https://github.com/itaru2622) in [#1504](https://github.com/PrefectHQ/fastmcp/pull/1504)
+* Move SDK docs generation to post-merge workflow by [@jlowin](https://github.com/jlowin) in [#1513](https://github.com/PrefectHQ/fastmcp/pull/1513)
+* Improve label triage guidance by [@jlowin](https://github.com/jlowin) in [#1516](https://github.com/PrefectHQ/fastmcp/pull/1516)
+* Add code review guidelines for agents by [@jlowin](https://github.com/jlowin) in [#1520](https://github.com/PrefectHQ/fastmcp/pull/1520)
+* Remove trailing slash in unit tests by [@jlowin](https://github.com/jlowin) in [#1535](https://github.com/PrefectHQ/fastmcp/pull/1535)
+* Update OAuth callback UI branding by [@jlowin](https://github.com/jlowin) in [#1536](https://github.com/PrefectHQ/fastmcp/pull/1536)
+* Fix Marvin workflow to support development tools by [@jlowin](https://github.com/jlowin) in [#1537](https://github.com/PrefectHQ/fastmcp/pull/1537)
+* Add mounted_components_raise_on_load_error setting for debugging by [@jlowin](https://github.com/jlowin) in [#1534](https://github.com/PrefectHQ/fastmcp/pull/1534)
+* feat: Add --workspace flag to fastmcp install cursor by [@jlowin](https://github.com/jlowin) in [#1522](https://github.com/PrefectHQ/fastmcp/pull/1522)
+* switch from `pyright` to `ty` by [@zzstoatzz](https://github.com/zzstoatzz) in [#1545](https://github.com/PrefectHQ/fastmcp/pull/1545)
+* feat: trigger Marvin workflow on PR body content by [@jlowin](https://github.com/jlowin) in [#1549](https://github.com/PrefectHQ/fastmcp/pull/1549)
+* Add WorkOS and Azure OAuth providers by [@jlowin](https://github.com/jlowin) in [#1550](https://github.com/PrefectHQ/fastmcp/pull/1550)
+* Adjust timeout for slow MCP Server shutdown test by [@strawgate](https://github.com/strawgate) in [#1561](https://github.com/PrefectHQ/fastmcp/pull/1561)
+* Update banner by [@jlowin](https://github.com/jlowin) in [#1567](https://github.com/PrefectHQ/fastmcp/pull/1567)
+* Added import of AuthProxy to auth __init__ by [@KaliszS](https://github.com/KaliszS) in [#1568](https://github.com/PrefectHQ/fastmcp/pull/1568)
+* Add configurable redirect URI validation for OAuth providers by [@jlowin](https://github.com/jlowin) in [#1582](https://github.com/PrefectHQ/fastmcp/pull/1582)
+* Remove invalid-argument-type ignore and fix type errors by [@jlowin](https://github.com/jlowin) in [#1588](https://github.com/PrefectHQ/fastmcp/pull/1588)
+* Remove generate-schema from public CLI by [@jlowin](https://github.com/jlowin) in [#1591](https://github.com/PrefectHQ/fastmcp/pull/1591)
+* Skip flaky windows test / mulit-client garbage collection by [@jlowin](https://github.com/jlowin) in [#1592](https://github.com/PrefectHQ/fastmcp/pull/1592)
+* Add setting to disable logging configuration by [@isra17](https://github.com/isra17) in [#1575](https://github.com/PrefectHQ/fastmcp/pull/1575)
+* Improve debug logging for nested Servers / Clients by [@strawgate](https://github.com/strawgate) in [#1604](https://github.com/PrefectHQ/fastmcp/pull/1604)
+* Add GitHub pull request template by [@strawgate](https://github.com/strawgate) in [#1581](https://github.com/PrefectHQ/fastmcp/pull/1581)
+* chore: Automate docs and schema updates via PRs by [@jlowin](https://github.com/jlowin) in [#1611](https://github.com/PrefectHQ/fastmcp/pull/1611)
+* Experiment with haiku for limited workflows by [@jlowin](https://github.com/jlowin) in [#1613](https://github.com/PrefectHQ/fastmcp/pull/1613)
+* feat: Improve GitHub workflow automation for schema and SDK docs by [@jlowin](https://github.com/jlowin) in [#1615](https://github.com/PrefectHQ/fastmcp/pull/1615)
+* Consolidate server loading logic into FileSystemSource by [@jlowin](https://github.com/jlowin) in [#1614](https://github.com/PrefectHQ/fastmcp/pull/1614)
+* Prevent Haiku Marvin from commenting when there are no duplicates by [@jlowin](https://github.com/jlowin) in [#1622](https://github.com/PrefectHQ/fastmcp/pull/1622)
+* chore: Add clarifying note to automated PR bodies by [@jlowin](https://github.com/jlowin) in [#1623](https://github.com/PrefectHQ/fastmcp/pull/1623)
+* feat: introduce inline snapshots by [@strawgate](https://github.com/strawgate) in [#1605](https://github.com/PrefectHQ/fastmcp/pull/1605)
+* Improve fastmcp.json environment configuration and project-based deployments by [@jlowin](https://github.com/jlowin) in [#1631](https://github.com/PrefectHQ/fastmcp/pull/1631)
+* fix: allow passing query params in OAuthProxy upstream authorization url by [@danb27](https://github.com/danb27) in [#1630](https://github.com/PrefectHQ/fastmcp/pull/1630)
+* Support multiple --with-editable flags in CLI commands by [@jlowin](https://github.com/jlowin) in [#1634](https://github.com/PrefectHQ/fastmcp/pull/1634)
+* feat: support comma separated oauth scopes by [@jlowin](https://github.com/jlowin) in [#1642](https://github.com/PrefectHQ/fastmcp/pull/1642)
+* Add allowed_client_redirect_uris to OAuth provider subclasses by [@jlowin](https://github.com/jlowin) in [#1662](https://github.com/PrefectHQ/fastmcp/pull/1662)
+* Consolidate CLI config parsing and prevent infinite loops by [@jlowin](https://github.com/jlowin) in [#1660](https://github.com/PrefectHQ/fastmcp/pull/1660)
+* Internal refactor: mcp server config by [@jlowin](https://github.com/jlowin) in [#1672](https://github.com/PrefectHQ/fastmcp/pull/1672)
+* Refactor Environment to support multiple runtime types by [@jlowin](https://github.com/jlowin) in [#1673](https://github.com/PrefectHQ/fastmcp/pull/1673)
+* Add type field to Environment base class by [@jlowin](https://github.com/jlowin) in [#1676](https://github.com/PrefectHQ/fastmcp/pull/1676)
+### Fixes 🐞
+* Fix breaking change: restore output_schema=False compatibility by [@jlowin](https://github.com/jlowin) in [#1482](https://github.com/PrefectHQ/fastmcp/pull/1482)
+* Fix #1506: Update tool filtering documentation from _meta to meta by [@maybenotconnor](https://github.com/maybenotconnor) in [#1511](https://github.com/PrefectHQ/fastmcp/pull/1511)
+* Fix pytest warnings by [@jlowin](https://github.com/jlowin) in [#1559](https://github.com/PrefectHQ/fastmcp/pull/1559)
+* nest schemas under assets by [@jlowin](https://github.com/jlowin) in [#1593](https://github.com/PrefectHQ/fastmcp/pull/1593)
+* Skip flaky windows test by [@jlowin](https://github.com/jlowin) in [#1596](https://github.com/PrefectHQ/fastmcp/pull/1596)
+* ACTUALLY move schemas to fastmcp.json by [@jlowin](https://github.com/jlowin) in [#1597](https://github.com/PrefectHQ/fastmcp/pull/1597)
+* Fix and centralize CLI path resolution by [@jlowin](https://github.com/jlowin) in [#1590](https://github.com/PrefectHQ/fastmcp/pull/1590)
+* Remove client info modifications by [@jlowin](https://github.com/jlowin) in [#1620](https://github.com/PrefectHQ/fastmcp/pull/1620)
+* Fix $defs being discarded in input schema of transformed tool by [@pldesch-chift](https://github.com/pldesch-chift) in [#1578](https://github.com/PrefectHQ/fastmcp/pull/1578)
+* Fix enum elicitation to use inline schemas for MCP compatibility by [@jlowin](https://github.com/jlowin) in [#1632](https://github.com/PrefectHQ/fastmcp/pull/1632)
+* Reuse session for `StdioTransport` in `Client.new` by [@strawgate](https://github.com/strawgate) in [#1635](https://github.com/PrefectHQ/fastmcp/pull/1635)
+* Feat: Configurable LoggingMiddleware payload serialization by [@vl-kp](https://github.com/vl-kp) in [#1636](https://github.com/PrefectHQ/fastmcp/pull/1636)
+* Fix OAuth redirect URI validation for DCR compatibility by [@jlowin](https://github.com/jlowin) in [#1661](https://github.com/PrefectHQ/fastmcp/pull/1661)
+* Add default scope handling in OAuth proxy by [@romanusyk](https://github.com/romanusyk) in [#1667](https://github.com/PrefectHQ/fastmcp/pull/1667)
+* Fix OAuth token expiry handling by [@jlowin](https://github.com/jlowin) in [#1671](https://github.com/PrefectHQ/fastmcp/pull/1671)
+* Add resource_server_url parameter to OAuth proxy providers by [@jlowin](https://github.com/jlowin) in [#1682](https://github.com/PrefectHQ/fastmcp/pull/1682)
+### Breaking Changes 🛫
+* Enhance inspect command with structured output and format options by [@jlowin](https://github.com/jlowin) in [#1481](https://github.com/PrefectHQ/fastmcp/pull/1481)
+### Docs 📚
+* Update changelog by [@jlowin](https://github.com/jlowin) in [#1453](https://github.com/PrefectHQ/fastmcp/pull/1453)
+* Update banner by [@jlowin](https://github.com/jlowin) in [#1472](https://github.com/PrefectHQ/fastmcp/pull/1472)
+* Update logo files by [@jlowin](https://github.com/jlowin) in [#1473](https://github.com/PrefectHQ/fastmcp/pull/1473)
+* Update deployment docs by [@jlowin](https://github.com/jlowin) in [#1486](https://github.com/PrefectHQ/fastmcp/pull/1486)
+* Update FastMCP Cloud screenshot by [@jlowin](https://github.com/jlowin) in [#1487](https://github.com/PrefectHQ/fastmcp/pull/1487)
+* Update authentication note in docs by [@jlowin](https://github.com/jlowin) in [#1488](https://github.com/PrefectHQ/fastmcp/pull/1488)
+* chore: Update installation.mdx version snippet by [@thomas-te](https://github.com/thomas-te) in [#1496](https://github.com/PrefectHQ/fastmcp/pull/1496)
+* Update fastmcp cloud server requirements by [@jlowin](https://github.com/jlowin) in [#1497](https://github.com/PrefectHQ/fastmcp/pull/1497)
+* Fix oauth pyright type checking by [@strawgate](https://github.com/strawgate) in [#1498](https://github.com/PrefectHQ/fastmcp/pull/1498)
+* docs: Fix type annotation in return value documentation by [@MaikelVeen](https://github.com/MaikelVeen) in [#1499](https://github.com/PrefectHQ/fastmcp/pull/1499)
+* Fix PromptMessage usage in docs example by [@jlowin](https://github.com/jlowin) in [#1515](https://github.com/PrefectHQ/fastmcp/pull/1515)
+* Create CODE_OF_CONDUCT.md by [@jlowin](https://github.com/jlowin) in [#1523](https://github.com/PrefectHQ/fastmcp/pull/1523)
+* Fixed wrong import path in new docs page by [@KaliszS](https://github.com/KaliszS) in [#1538](https://github.com/PrefectHQ/fastmcp/pull/1538)
+* Document symmetric key JWT verification support by [@jlowin](https://github.com/jlowin) in [#1586](https://github.com/PrefectHQ/fastmcp/pull/1586)
+* Update fastmcp.json schema path by [@jlowin](https://github.com/jlowin) in [#1595](https://github.com/PrefectHQ/fastmcp/pull/1595)
+### Dependencies 📦
+* Bump actions/create-github-app-token from 1 to 2 by [@dependabot](https://github.com/dependabot)[bot] in [#1436](https://github.com/PrefectHQ/fastmcp/pull/1436)
+* Bump astral-sh/setup-uv from 4 to 6 by [@dependabot](https://github.com/dependabot)[bot] in [#1532](https://github.com/PrefectHQ/fastmcp/pull/1532)
+* Bump actions/checkout from 4 to 5 by [@dependabot](https://github.com/dependabot)[bot] in [#1533](https://github.com/PrefectHQ/fastmcp/pull/1533)
+### Other Changes 🦾
+* Add dedupe workflow by [@jlowin](https://github.com/jlowin) in [#1454](https://github.com/PrefectHQ/fastmcp/pull/1454)
+* Update AGENTS.md by [@jlowin](https://github.com/jlowin) in [#1471](https://github.com/PrefectHQ/fastmcp/pull/1471)
+* Give Marvin the power of the Internet by [@strawgate](https://github.com/strawgate) in [#1475](https://github.com/PrefectHQ/fastmcp/pull/1475)
+* Update `just` error message for static checks by [@jlowin](https://github.com/jlowin) in [#1483](https://github.com/PrefectHQ/fastmcp/pull/1483)
+* Remove labeler by [@jlowin](https://github.com/jlowin) in [#1509](https://github.com/PrefectHQ/fastmcp/pull/1509)
+* update aproto server to handle rich links by [@zzstoatzz](https://github.com/zzstoatzz) in [#1556](https://github.com/PrefectHQ/fastmcp/pull/1556)
+* fix: enable triage bot for fork PRs using pull_request_target by [@jlowin](https://github.com/jlowin) in [#1557](https://github.com/PrefectHQ/fastmcp/pull/1557)
+
+## New Contributors
+* [@thomas-te](https://github.com/thomas-te) made their first contribution in [#1496](https://github.com/PrefectHQ/fastmcp/pull/1496)
+* [@maybenotconnor](https://github.com/maybenotconnor) made their first contribution in [#1511](https://github.com/PrefectHQ/fastmcp/pull/1511)
+* [@MaikelVeen](https://github.com/MaikelVeen) made their first contribution in [#1499](https://github.com/PrefectHQ/fastmcp/pull/1499)
+* [@KaliszS](https://github.com/KaliszS) made their first contribution in [#1538](https://github.com/PrefectHQ/fastmcp/pull/1538)
+* [@isra17](https://github.com/isra17) made their first contribution in [#1575](https://github.com/PrefectHQ/fastmcp/pull/1575)
+* [@marvin-context-protocol](https://github.com/marvin-context-protocol)[bot] made their first contribution in [#1616](https://github.com/PrefectHQ/fastmcp/pull/1616)
+* [@pldesch-chift](https://github.com/pldesch-chift) made their first contribution in [#1578](https://github.com/PrefectHQ/fastmcp/pull/1578)
+* [@vl-kp](https://github.com/vl-kp) made their first contribution in [#1636](https://github.com/PrefectHQ/fastmcp/pull/1636)
+* [@romanusyk](https://github.com/romanusyk) made their first contribution in [#1667](https://github.com/PrefectHQ/fastmcp/pull/1667)
+
+**Full Changelog**: [v2.11.3...v2.12.0](https://github.com/PrefectHQ/fastmcp/compare/v2.11.3...v2.12.0)
+
+</Update>
+
+<Update label="v2.11.3" description="2025-08-11">
+
+**[v2.11.3: API-tite for Change](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.11.3)**
+
+This release includes significant enhancements to the experimental OpenAPI parser and fixes a significant bug that led schemas not to be included in input/output schemas if they were transitive dependencies (e.g. A → B → C implies A depends on C). For users naively transforming large OpenAPI specs into MCP servers, this may result in ballooning payload sizes and necessitate curation.
+
+## What's Changed
+### Enhancements 🔧
+* Improve redirect handling to address 307's by [@jlowin](https://github.com/jlowin) in [#1387](https://github.com/PrefectHQ/fastmcp/pull/1387)
+* Ensure resource + template names are properly prefixed when importing/mounting by [@jlowin](https://github.com/jlowin) in [#1423](https://github.com/PrefectHQ/fastmcp/pull/1423)
+* fixes #1398: Add JWT claims to AccessToken by [@panargirakis](https://github.com/panargirakis) in [#1399](https://github.com/PrefectHQ/fastmcp/pull/1399)
+* Enable Protected Resource Metadata to provide resource_name and resou… by [@yannj-fr](https://github.com/yannj-fr) in [#1371](https://github.com/PrefectHQ/fastmcp/pull/1371)
+* Pin mcp SDK under 2.0 to avoid breaking changes by [@jlowin](https://github.com/jlowin) in [#1428](https://github.com/PrefectHQ/fastmcp/pull/1428)
+* Clean up complexity from PR #1426 by [@jlowin](https://github.com/jlowin) in [#1435](https://github.com/PrefectHQ/fastmcp/pull/1435)
+* Optimize OpenAPI payload size by 46% by [@jlowin](https://github.com/jlowin) in [#1452](https://github.com/PrefectHQ/fastmcp/pull/1452)
+* Update static checks by [@jlowin](https://github.com/jlowin) in [#1448](https://github.com/PrefectHQ/fastmcp/pull/1448)
+### Fixes 🐞
+* Fix client-side logging bug #1394 by [@chi2liu](https://github.com/chi2liu) in [#1397](https://github.com/PrefectHQ/fastmcp/pull/1397)
+* fix: Fix httpx_client_factory type annotation to match MCP SDK (#1402) by [@chi2liu](https://github.com/chi2liu) in [#1405](https://github.com/PrefectHQ/fastmcp/pull/1405)
+* Fix OpenAPI allOf handling at requestBody top level (#1378) by [@chi2liu](https://github.com/chi2liu) in [#1425](https://github.com/PrefectHQ/fastmcp/pull/1425)
+* Fix OpenAPI transitive references and performance (#1372) by [@jlowin](https://github.com/jlowin) in [#1426](https://github.com/PrefectHQ/fastmcp/pull/1426)
+* fix(type): lifespan is partially unknown by [@ykun9](https://github.com/ykun9) in [#1389](https://github.com/PrefectHQ/fastmcp/pull/1389)
+* Ensure transformed tools generate structured content by [@jlowin](https://github.com/jlowin) in [#1443](https://github.com/PrefectHQ/fastmcp/pull/1443)
+### Docs 📚
+* docs(client/logging): reflect corrected default log level mapping by [@jlowin](https://github.com/jlowin) in [#1403](https://github.com/PrefectHQ/fastmcp/pull/1403)
+* Add documentation for get_access_token() dependency function by [@jlowin](https://github.com/jlowin) in [#1446](https://github.com/PrefectHQ/fastmcp/pull/1446)
+### Other Changes 🦾
+* Add comprehensive tests for utilities.components module by [@chi2liu](https://github.com/chi2liu) in [#1395](https://github.com/PrefectHQ/fastmcp/pull/1395)
+* Consolidate agent instructions into AGENTS.md by [@jlowin](https://github.com/jlowin) in [#1404](https://github.com/PrefectHQ/fastmcp/pull/1404)
+* Fix performance test threshold to prevent flaky failures by [@jlowin](https://github.com/jlowin) in [#1406](https://github.com/PrefectHQ/fastmcp/pull/1406)
+* Update agents.md; add github instructions by [@jlowin](https://github.com/jlowin) in [#1410](https://github.com/PrefectHQ/fastmcp/pull/1410)
+* Add Marvin assistant by [@jlowin](https://github.com/jlowin) in [#1412](https://github.com/PrefectHQ/fastmcp/pull/1412)
+* Marvin: fix deprecated variable names by [@jlowin](https://github.com/jlowin) in [#1417](https://github.com/PrefectHQ/fastmcp/pull/1417)
+* Simplify action setup and add github tools for Marvin by [@jlowin](https://github.com/jlowin) in [#1419](https://github.com/PrefectHQ/fastmcp/pull/1419)
+* Update marvin workflow name by [@jlowin](https://github.com/jlowin) in [#1421](https://github.com/PrefectHQ/fastmcp/pull/1421)
+* Improve GitHub templates by [@jlowin](https://github.com/jlowin) in [#1422](https://github.com/PrefectHQ/fastmcp/pull/1422)
+
+## New Contributors
+* [@panargirakis](https://github.com/panargirakis) made their first contribution in [#1399](https://github.com/PrefectHQ/fastmcp/pull/1399)
+* [@ykun9](https://github.com/ykun9) made their first contribution in [#1389](https://github.com/PrefectHQ/fastmcp/pull/1389)
+* [@yannj-fr](https://github.com/yannj-fr) made their first contribution in [#1371](https://github.com/PrefectHQ/fastmcp/pull/1371)
+
+**Full Changelog**: [v2.11.2...v2.11.3](https://github.com/PrefectHQ/fastmcp/compare/v2.11.2...v2.11.3)
+
+</Update>
+
+<Update label="v2.11.2" description="2025-08-06">
+
+## [v2.11.2: Satis-factory](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.11.2)
+
+## What's Changed
+### Enhancements 🔧
+* Support factory functions in fastmcp run by [@jlowin](https://github.com/jlowin) in [#1384](https://github.com/PrefectHQ/fastmcp/pull/1384)
+* Add async support to client_factory in FastMCPProxy  (#1286) by [@bianning](https://github.com/bianning) in [#1375](https://github.com/PrefectHQ/fastmcp/pull/1375)
+### Fixes 🐞
+* Fix server_version field in inspect manifest by [@jlowin](https://github.com/jlowin) in [#1383](https://github.com/PrefectHQ/fastmcp/pull/1383)
+* Fix Settings field with both default and default_factory by [@jlowin](https://github.com/jlowin) in [#1380](https://github.com/PrefectHQ/fastmcp/pull/1380)
+### Other Changes 🦾
+* Remove unused arg by [@jlowin](https://github.com/jlowin) in [#1382](https://github.com/PrefectHQ/fastmcp/pull/1382)
+* Add remote auth provider tests by [@jlowin](https://github.com/jlowin) in [#1351](https://github.com/PrefectHQ/fastmcp/pull/1351)
+
+## New Contributors
+* [@bianning](https://github.com/bianning) made their first contribution in [#1375](https://github.com/PrefectHQ/fastmcp/pull/1375)
+
+**Full Changelog**: [v2.11.1...v2.11.2](https://github.com/PrefectHQ/fastmcp/compare/v2.11.1...v2.11.2)
+
+</Update>
+
+<Update label="v2.11.1" description="2025-08-04">
+
+## [v2.11.1: You're Better Auth Now](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.11.1)
+
+## What's Changed
+### New Features 🎉
+* Introduce `RemoteAuthProvider` for cleaner external identity provider integration, update docs by [@jlowin](https://github.com/jlowin) in [#1346](https://github.com/PrefectHQ/fastmcp/pull/1346)
+### Enhancements 🔧
+* perf: optimize string operations in OpenAPI parameter processing by [@chi2liu](https://github.com/chi2liu) in [#1342](https://github.com/PrefectHQ/fastmcp/pull/1342)
+### Fixes 🐞
+* Fix method-bound FunctionTool schemas by [@strawgate](https://github.com/strawgate) in [#1360](https://github.com/PrefectHQ/fastmcp/pull/1360)
+* Manually set `_key` after `model_copy()` to enable prefixing Transformed Tools by [@strawgate](https://github.com/strawgate) in [#1357](https://github.com/PrefectHQ/fastmcp/pull/1357)
+### Docs 📚
+* Docs updates by [@jlowin](https://github.com/jlowin) in [#1336](https://github.com/PrefectHQ/fastmcp/pull/1336)
+* Add 2.11 to changelog by [@jlowin](https://github.com/jlowin) in [#1337](https://github.com/PrefectHQ/fastmcp/pull/1337)
+* Update AuthKit vocab by [@jlowin](https://github.com/jlowin) in [#1338](https://github.com/PrefectHQ/fastmcp/pull/1338)
+* Fix typo in decorating-methods.mdx by [@Ozzuke](https://github.com/Ozzuke) in [#1344](https://github.com/PrefectHQ/fastmcp/pull/1344)
+
+## New Contributors
+* [@Ozzuke](https://github.com/Ozzuke) made their first contribution in [#1344](https://github.com/PrefectHQ/fastmcp/pull/1344)
+
+**Full Changelog**: [v2.11.0...v2.11.1](https://github.com/PrefectHQ/fastmcp/compare/v2.11.0...v2.11.1)
+
+</Update>
+
+<Update label="v2.11.0" description="2025-08-01">
+
+## [v2.11.0: Auth to a Good Start](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.11.0)
+
+FastMCP 2.11 doubles down on what developers need most: speed and simplicity. This massive release delivers significant performance improvements and a dramatically better developer experience.
+
+🔐 **Enterprise-Ready Authentication** brings comprehensive OAuth 2.1 support with WorkOS's AuthKit integration. The new AuthProvider interface leverages MCP's support for separate resource and authorization servers, handling API keys and remote authentication with Dynamic Client Registration. AuthKit integration means you can plug into existing enterprise identity systems without rebuilding your auth stack, setting the stage for plug-and-play auth that doesn't require users to become security experts overnight.
+
+⚡ The **Experimental OpenAPI Parser** delivers dramatic performance improvements through single-pass schema processing and optimized memory usage. OpenAPI integrations are now significantly faster, with cleaner, more maintainable code. _(Note: the experimental parser is disabled by default, set `FASTMCPEXPERIMENTALENABLENEWOPENAPIPARSER=1` to enable it. A message will be shown to all users on the legacy parser encouraging them to try the new one before it becomes the default.)_
+
+🧠 **Context State Management** finally gives you persistent state across tool calls with a simple dict interface, while enhanced meta support lets you expose rich component metadata to clients. Combined with improved type annotations, string-based argument descriptions, and UV transport support, this release makes FastMCP feel more intuitive than ever.
+
+This release represents a TON of community contributions and sets the foundation for even more ambitious features ahead.
+
+## What's Changed
+### New Features 🎉
+* Introduce experimental OpenAPI parser with improved performance and maintainability by [@jlowin](https://github.com/jlowin) in [#1209](https://github.com/PrefectHQ/fastmcp/pull/1209)
+* Add state dict to Context (#1118) by [@mukulmurthy](https://github.com/mukulmurthy) in [#1160](https://github.com/PrefectHQ/fastmcp/pull/1160)
+* Expose FastMCP tags to clients via component `meta` dict by [@jlowin](https://github.com/jlowin) in [#1281](https://github.com/PrefectHQ/fastmcp/pull/1281)
+* Add _fastmcp meta namespace by [@jlowin](https://github.com/jlowin) in [#1290](https://github.com/PrefectHQ/fastmcp/pull/1290)
+* Add TokenVerifier protocol support alongside existing OAuthProvider authentication by [@jlowin](https://github.com/jlowin) in [#1297](https://github.com/PrefectHQ/fastmcp/pull/1297)
+* Add comprehensive OAuth 2.1 authentication system with WorkOS integration by [@jlowin](https://github.com/jlowin) in [#1327](https://github.com/PrefectHQ/fastmcp/pull/1327)
+### Enhancements 🔧
+* [🐶] Transform MCP Server Tools by [@strawgate](https://github.com/strawgate) in [#1132](https://github.com/PrefectHQ/fastmcp/pull/1132)
+* Add --python, --project, and --with-requirements options to CLI commands by [@jlowin](https://github.com/jlowin) in [#1190](https://github.com/PrefectHQ/fastmcp/pull/1190)
+* Support `fastmcp run mcp.json` by [@strawgate](https://github.com/strawgate) in [#1138](https://github.com/PrefectHQ/fastmcp/pull/1138)
+* Support from __future__ import annotations by [@jlowin](https://github.com/jlowin) in [#1199](https://github.com/PrefectHQ/fastmcp/pull/1199)
+* Optimize OpenAPI parser performance with single-pass schema processing by [@jlowin](https://github.com/jlowin) in [#1214](https://github.com/PrefectHQ/fastmcp/pull/1214)
+* Log tool name on transform validation error by [@strawgate](https://github.com/strawgate) in [#1238](https://github.com/PrefectHQ/fastmcp/pull/1238)
+* Refactor `get_http_request` and `context.session_id` by [@hopeful0](https://github.com/hopeful0) in [#1242](https://github.com/PrefectHQ/fastmcp/pull/1242)
+* Support creating tool argument descriptions from string annotations by [@jlowin](https://github.com/jlowin) in [#1255](https://github.com/PrefectHQ/fastmcp/pull/1255)
+* feat: Add Annotations support for resources and resource templates by [@chughtapan](https://github.com/chughtapan) in [#1260](https://github.com/PrefectHQ/fastmcp/pull/1260)
+* Add UV Transport by [@strawgate](https://github.com/strawgate) in [#1270](https://github.com/PrefectHQ/fastmcp/pull/1270)
+* Improve OpenAPI-to-JSONSchema conversion utilities by [@jlowin](https://github.com/jlowin) in [#1283](https://github.com/PrefectHQ/fastmcp/pull/1283)
+* Ensure proxy components forward meta dicts by [@jlowin](https://github.com/jlowin) in [#1282](https://github.com/PrefectHQ/fastmcp/pull/1282)
+* fix: server argument passing in CLI run command by [@chughtapan](https://github.com/chughtapan) in [#1293](https://github.com/PrefectHQ/fastmcp/pull/1293)
+* Add meta support to tool transformation utilities by [@jlowin](https://github.com/jlowin) in [#1295](https://github.com/PrefectHQ/fastmcp/pull/1295)
+* feat: Allow Resource Metadata URL as field in OAuthProvider by [@dacamposol](https://github.com/dacamposol) in [#1287](https://github.com/PrefectHQ/fastmcp/pull/1287)
+* Use a simple overwrite instead of a merge for meta by [@jlowin](https://github.com/jlowin) in [#1296](https://github.com/PrefectHQ/fastmcp/pull/1296)
+* Remove unused TimedCache by [@strawgate](https://github.com/strawgate) in [#1303](https://github.com/PrefectHQ/fastmcp/pull/1303)
+* refactor: standardize logging usage across OpenAPI utilities by [@chi2liu](https://github.com/chi2liu) in [#1322](https://github.com/PrefectHQ/fastmcp/pull/1322)
+* perf: optimize OpenAPI parsing by reducing dict copy operations by [@chi2liu](https://github.com/chi2liu) in [#1321](https://github.com/PrefectHQ/fastmcp/pull/1321)
+* Structured client-side logging by [@cjermain](https://github.com/cjermain) in [#1326](https://github.com/PrefectHQ/fastmcp/pull/1326)
+### Fixes 🐞
+* fix: preserve def reference when referenced in allOf / oneOf / anyOf by [@algirdasci](https://github.com/algirdasci) in [#1208](https://github.com/PrefectHQ/fastmcp/pull/1208)
+* fix: add type hint to custom_route decorator by [@zzstoatzz](https://github.com/zzstoatzz) in [#1210](https://github.com/PrefectHQ/fastmcp/pull/1210)
+* chore: typo by [@richardkmichael](https://github.com/richardkmichael) in [#1216](https://github.com/PrefectHQ/fastmcp/pull/1216)
+* fix: handle non-string $ref values in experimental OpenAPI parser by [@jlowin](https://github.com/jlowin) in [#1217](https://github.com/PrefectHQ/fastmcp/pull/1217)
+* Skip repeated type conversion and validation in proxy client elicitation handler by [@chughtapan](https://github.com/chughtapan) in [#1222](https://github.com/PrefectHQ/fastmcp/pull/1222)
+* Ensure default fields are not marked nullable by [@jlowin](https://github.com/jlowin) in [#1224](https://github.com/PrefectHQ/fastmcp/pull/1224)
+* Fix stateful proxy client mixing in multi-proxies sessions by [@hopeful0](https://github.com/hopeful0) in [#1245](https://github.com/PrefectHQ/fastmcp/pull/1245)
+* Fix invalid async context manager usage in proxy documentation by [@zzstoatzz](https://github.com/zzstoatzz) in [#1246](https://github.com/PrefectHQ/fastmcp/pull/1246)
+* fix: experimental FastMCPOpenAPI server lost headers in request when __init__(client with headers) by [@itaru2622](https://github.com/itaru2622) in [#1254](https://github.com/PrefectHQ/fastmcp/pull/1254)
+* Fix typing, add tests for tool call middleware by [@jlowin](https://github.com/jlowin) in [#1269](https://github.com/PrefectHQ/fastmcp/pull/1269)
+* Fix: prune hidden parameter defs by [@muhammadkhalid-03](https://github.com/muhammadkhalid-03) in [#1257](https://github.com/PrefectHQ/fastmcp/pull/1257)
+* Fix nullable field handling in OpenAPI to JSON Schema conversion by [@jlowin](https://github.com/jlowin) in [#1279](https://github.com/PrefectHQ/fastmcp/pull/1279)
+* Ensure fastmcp run supports v1 servers by [@jlowin](https://github.com/jlowin) in [#1332](https://github.com/PrefectHQ/fastmcp/pull/1332)
+### Breaking Changes 🛫
+* Change server flag to --name by [@jlowin](https://github.com/jlowin) in [#1248](https://github.com/PrefectHQ/fastmcp/pull/1248)
+### Docs 📚
+* Remove unused import from FastAPI integration documentation by [@mariotaddeucci](https://github.com/mariotaddeucci) in [#1194](https://github.com/PrefectHQ/fastmcp/pull/1194)
+* Update fastapi docs by [@jlowin](https://github.com/jlowin) in [#1198](https://github.com/PrefectHQ/fastmcp/pull/1198)
+* Add docs for context state management by [@jlowin](https://github.com/jlowin) in [#1227](https://github.com/PrefectHQ/fastmcp/pull/1227)
+* Permit.io integration docs by [@orweis](https://github.com/orweis) in [#1226](https://github.com/PrefectHQ/fastmcp/pull/1226)
+* Update docs to reflect sync tools by [@jlowin](https://github.com/jlowin) in [#1234](https://github.com/PrefectHQ/fastmcp/pull/1234)
+* Update changelog.mdx by [@jlowin](https://github.com/jlowin) in [#1235](https://github.com/PrefectHQ/fastmcp/pull/1235)
+* Update SDK docs by [@jlowin](https://github.com/jlowin) in [#1236](https://github.com/PrefectHQ/fastmcp/pull/1236)
+* Update --name flag documentation for Cursor/Claude by [@adam-conway](https://github.com/adam-conway) in [#1239](https://github.com/PrefectHQ/fastmcp/pull/1239)
+* Add annotations docs by [@jlowin](https://github.com/jlowin) in [#1268](https://github.com/PrefectHQ/fastmcp/pull/1268)
+* Update openapi/fastapi URLs README.md by [@jbn](https://github.com/jbn) in [#1278](https://github.com/PrefectHQ/fastmcp/pull/1278)
+* Add 2.11 version badge for state management by [@jlowin](https://github.com/jlowin) in [#1289](https://github.com/PrefectHQ/fastmcp/pull/1289)
+* Add meta parameter support to tools, resources, templates, and prompts decorators by [@jlowin](https://github.com/jlowin) in [#1294](https://github.com/PrefectHQ/fastmcp/pull/1294)
+* docs: update get_state and set_state references by [@Maxi91f](https://github.com/Maxi91f) in [#1306](https://github.com/PrefectHQ/fastmcp/pull/1306)
+* Add unit tests and docs for denying tool calls with middleware by [@jlowin](https://github.com/jlowin) in [#1333](https://github.com/PrefectHQ/fastmcp/pull/1333)
+* Remove reference to stacked decorators by [@jlowin](https://github.com/jlowin) in [#1334](https://github.com/PrefectHQ/fastmcp/pull/1334)
+* Eunomia authorization server can run embedded within the MCP server by [@tommitt](https://github.com/tommitt) in [#1317](https://github.com/PrefectHQ/fastmcp/pull/1317)
+### Other Changes 🦾
+* Update README.md by [@jlowin](https://github.com/jlowin) in [#1230](https://github.com/PrefectHQ/fastmcp/pull/1230)
+* Logcapture addition to test_server file by [@Sourav-Tripathy](https://github.com/Sourav-Tripathy) in [#1229](https://github.com/PrefectHQ/fastmcp/pull/1229)
+* Add tests for headers with both legacy and experimental openapi parser by [@jlowin](https://github.com/jlowin) in [#1259](https://github.com/PrefectHQ/fastmcp/pull/1259)
+* Small clean-up from MCP Tool Transform PR by [@strawgate](https://github.com/strawgate) in [#1267](https://github.com/PrefectHQ/fastmcp/pull/1267)
+* Add test for proxy tags visibility by [@jlowin](https://github.com/jlowin) in [#1302](https://github.com/PrefectHQ/fastmcp/pull/1302)
+* Add unit test for sampling with image messages by [@jlowin](https://github.com/jlowin) in [#1329](https://github.com/PrefectHQ/fastmcp/pull/1329)
+* Remove redundant resource_metadata_url assignment by [@jlowin](https://github.com/jlowin) in [#1328](https://github.com/PrefectHQ/fastmcp/pull/1328)
+* Update bug.yml by [@jlowin](https://github.com/jlowin) in [#1331](https://github.com/PrefectHQ/fastmcp/pull/1331)
+* Ensure validation errors are raised when masked by [@jlowin](https://github.com/jlowin) in [#1330](https://github.com/PrefectHQ/fastmcp/pull/1330)
+
+## New Contributors
+* [@mariotaddeucci](https://github.com/mariotaddeucci) made their first contribution in [#1194](https://github.com/PrefectHQ/fastmcp/pull/1194)
+* [@algirdasci](https://github.com/algirdasci) made their first contribution in [#1208](https://github.com/PrefectHQ/fastmcp/pull/1208)
+* [@chughtapan](https://github.com/chughtapan) made their first contribution in [#1222](https://github.com/PrefectHQ/fastmcp/pull/1222)
+* [@mukulmurthy](https://github.com/mukulmurthy) made their first contribution in [#1160](https://github.com/PrefectHQ/fastmcp/pull/1160)
+* [@orweis](https://github.com/orweis) made their first contribution in [#1226](https://github.com/PrefectHQ/fastmcp/pull/1226)
+* [@Sourav-Tripathy](https://github.com/Sourav-Tripathy) made their first contribution in [#1229](https://github.com/PrefectHQ/fastmcp/pull/1229)
+* [@adam-conway](https://github.com/adam-conway) made their first contribution in [#1239](https://github.com/PrefectHQ/fastmcp/pull/1239)
+* [@muhammadkhalid-03](https://github.com/muhammadkhalid-03) made their first contribution in [#1257](https://github.com/PrefectHQ/fastmcp/pull/1257)
+* [@jbn](https://github.com/jbn) made their first contribution in [#1278](https://github.com/PrefectHQ/fastmcp/pull/1278)
+* [@dacamposol](https://github.com/dacamposol) made their first contribution in [#1287](https://github.com/PrefectHQ/fastmcp/pull/1287)
+* [@chi2liu](https://github.com/chi2liu) made their first contribution in [#1322](https://github.com/PrefectHQ/fastmcp/pull/1322)
+* [@cjermain](https://github.com/cjermain) made their first contribution in [#1326](https://github.com/PrefectHQ/fastmcp/pull/1326)
+
+**Full Changelog**: [v2.10.6...v2.11.0](https://github.com/PrefectHQ/fastmcp/compare/v2.10.6...v2.11.0)
+
+</Update>
+
+<Update label="v2.10.6" description="2025-07-19">
+
+## [v2.10.6: Hymn for the Weekend](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.6)
+
+A special Saturday release with many fixes.
+
+## What's Changed
+### Enhancements 🔧
+* Resolve #1139 -- Implement include_context argument in Context.sample by [@codingjoe](https://github.com/codingjoe) in [#1141](https://github.com/PrefectHQ/fastmcp/pull/1141)
+* feat(settings): add log level normalization by [@ka2048](https://github.com/ka2048) in [#1171](https://github.com/PrefectHQ/fastmcp/pull/1171)
+* add server name to mounted server warnings by [@artificial-aidan](https://github.com/artificial-aidan) in [#1147](https://github.com/PrefectHQ/fastmcp/pull/1147)
+* Add StatefulProxyClient by [@hopeful0](https://github.com/hopeful0) in [#1109](https://github.com/PrefectHQ/fastmcp/pull/1109)
+### Fixes 🐞
+* Fix OpenAPI empty parameters by [@FabrizioSandri](https://github.com/FabrizioSandri) in [#1128](https://github.com/PrefectHQ/fastmcp/pull/1128)
+* Fix title field preservation in tool transformations by [@jlowin](https://github.com/jlowin) in [#1131](https://github.com/PrefectHQ/fastmcp/pull/1131)
+* Fix optional parameter validation in OpenAPI integration by [@jlowin](https://github.com/jlowin) in [#1135](https://github.com/PrefectHQ/fastmcp/pull/1135)
+* Do not silently exclude the "context" key from JSON body by [@melkamar](https://github.com/melkamar) in [#1153](https://github.com/PrefectHQ/fastmcp/pull/1153)
+* Fix tool output schema generation to respect Pydantic serialization aliases by [@zzstoatzz](https://github.com/zzstoatzz) in [#1148](https://github.com/PrefectHQ/fastmcp/pull/1148)
+* fix: _replace_ref_with_defs; ensure ref_path is string by [@itaru2622](https://github.com/itaru2622) in [#1164](https://github.com/PrefectHQ/fastmcp/pull/1164)
+* Fix nesting when making OpenAPI arrays and objects optional by [@melkamar](https://github.com/melkamar) in [#1178](https://github.com/PrefectHQ/fastmcp/pull/1178)
+* Fix `mcp-json` output format to include server name by [@jlowin](https://github.com/jlowin) in [#1185](https://github.com/PrefectHQ/fastmcp/pull/1185)
+* Only configure logging one time by [@jlowin](https://github.com/jlowin) in [#1187](https://github.com/PrefectHQ/fastmcp/pull/1187)
+### Docs 📚
+* Update changelog.mdx by [@jlowin](https://github.com/jlowin) in [#1127](https://github.com/PrefectHQ/fastmcp/pull/1127)
+* Eunomia Authorization with native FastMCP's Middleware by [@tommitt](https://github.com/tommitt) in [#1144](https://github.com/PrefectHQ/fastmcp/pull/1144)
+* update api ref for new `mdxify` version by [@zzstoatzz](https://github.com/zzstoatzz) in [#1182](https://github.com/PrefectHQ/fastmcp/pull/1182)
+### Other Changes 🦾
+* Expand empty parameter filtering and add comprehensive tests by [@jlowin](https://github.com/jlowin) in [#1129](https://github.com/PrefectHQ/fastmcp/pull/1129)
+* Add no-commit-to-branch hook by [@zzstoatzz](https://github.com/zzstoatzz) in [#1149](https://github.com/PrefectHQ/fastmcp/pull/1149)
+* Update README.md by [@jlowin](https://github.com/jlowin) in [#1165](https://github.com/PrefectHQ/fastmcp/pull/1165)
+* skip on rate limit by [@zzstoatzz](https://github.com/zzstoatzz) in [#1183](https://github.com/PrefectHQ/fastmcp/pull/1183)
+* Remove deprecated proxy creation by [@jlowin](https://github.com/jlowin) in [#1186](https://github.com/PrefectHQ/fastmcp/pull/1186)
+* Separate integration tests from unit tests in CI by [@jlowin](https://github.com/jlowin) in [#1188](https://github.com/PrefectHQ/fastmcp/pull/1188)
+
+## New Contributors
+* [@FabrizioSandri](https://github.com/FabrizioSandri) made their first contribution in [#1128](https://github.com/PrefectHQ/fastmcp/pull/1128)
+* [@melkamar](https://github.com/melkamar) made their first contribution in [#1153](https://github.com/PrefectHQ/fastmcp/pull/1153)
+* [@codingjoe](https://github.com/codingjoe) made their first contribution in [#1141](https://github.com/PrefectHQ/fastmcp/pull/1141)
+* [@itaru2622](https://github.com/itaru2622) made their first contribution in [#1164](https://github.com/PrefectHQ/fastmcp/pull/1164)
+* [@ka2048](https://github.com/ka2048) made their first contribution in [#1171](https://github.com/PrefectHQ/fastmcp/pull/1171)
+* [@artificial-aidan](https://github.com/artificial-aidan) made their first contribution in [#1147](https://github.com/PrefectHQ/fastmcp/pull/1147)
+
+**Full Changelog**: [v2.10.5...v2.10.6](https://github.com/PrefectHQ/fastmcp/compare/v2.10.5...v2.10.6)
+
+</Update>
+
+<Update label="v2.10.5" description="2025-07-11">
+
+## [v2.10.5: Middle Management](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.5)
+
+A maintenance release focused on OpenAPI refinements and middleware fixes, plus console improvements.
+
+## What's Changed
+### Enhancements 🔧
+* Fix Claude Code CLI detection for npm global installations by [@jlowin](https://github.com/jlowin) in [#1106](https://github.com/PrefectHQ/fastmcp/pull/1106)
+* Fix OpenAPI parameter name collisions with location suffixing by [@jlowin](https://github.com/jlowin) in [#1107](https://github.com/PrefectHQ/fastmcp/pull/1107)
+* Add mirrored component support for proxy servers by [@jlowin](https://github.com/jlowin) in [#1105](https://github.com/PrefectHQ/fastmcp/pull/1105)
+### Fixes 🐞
+* Fix OpenAPI deepObject style parameter encoding by [@jlowin](https://github.com/jlowin) in [#1122](https://github.com/PrefectHQ/fastmcp/pull/1122)
+* xfail when github token is not set ('' or None) by [@jlowin](https://github.com/jlowin) in [#1123](https://github.com/PrefectHQ/fastmcp/pull/1123)
+* fix: replace oneOf with anyOf in OpenAPI output schemas by [@MagnusS0](https://github.com/MagnusS0) in [#1119](https://github.com/PrefectHQ/fastmcp/pull/1119)
+* Fix middleware list result types by [@jlowin](https://github.com/jlowin) in [#1125](https://github.com/PrefectHQ/fastmcp/pull/1125)
+* Improve console width for logo by [@jlowin](https://github.com/jlowin) in [#1126](https://github.com/PrefectHQ/fastmcp/pull/1126)
+### Docs 📚
+* Improve transport + integration docs by [@jlowin](https://github.com/jlowin) in [#1103](https://github.com/PrefectHQ/fastmcp/pull/1103)
+* Update proxy.mdx by [@coldfire-x](https://github.com/coldfire-x) in [#1108](https://github.com/PrefectHQ/fastmcp/pull/1108)
+### Other Changes 🦾
+* Update github remote server tests with secret by [@jlowin](https://github.com/jlowin) in [#1112](https://github.com/PrefectHQ/fastmcp/pull/1112)
+
+## New Contributors
+* [@coldfire-x](https://github.com/coldfire-x) made their first contribution in [#1108](https://github.com/PrefectHQ/fastmcp/pull/1108)
+* [@MagnusS0](https://github.com/MagnusS0) made their first contribution in [#1119](https://github.com/PrefectHQ/fastmcp/pull/1119)
+
+**Full Changelog**: [v2.10.4...v2.10.5](https://github.com/PrefectHQ/fastmcp/compare/v2.10.4...v2.10.5)
+
+</Update>
+
+<Update label="v2.10.4" description="2025-07-09">
+
+## [v2.10.4: Transport-ation](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.4)
+
+A quick fix to ensure the CLI accepts "streamable-http" as a valid transport option.
+
+## What's Changed
+### Fixes 🐞
+* Ensure the CLI accepts "streamable-http" as a valid transport by [@jlowin](https://github.com/jlowin) in [#1099](https://github.com/PrefectHQ/fastmcp/pull/1099)
+
+**Full Changelog**: [v2.10.3...v2.10.4](https://github.com/PrefectHQ/fastmcp/compare/v2.10.3...v2.10.4)
+
+</Update>
+
+<Update label="v2.10.3" description="2025-07-09">
+
+## [v2.10.3: CLI Me a River](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.3)
+
+A major CLI overhaul featuring a complete refactor from typer to cyclopts, new IDE integrations, and comprehensive OpenAPI improvements.
+
+## What's Changed
+### New Features 🎉
+* Refactor CLI from typer to cyclopts and add comprehensive tests by [@jlowin](https://github.com/jlowin) in [#1062](https://github.com/PrefectHQ/fastmcp/pull/1062)
+* Add output schema support for OpenAPI tools by [@jlowin](https://github.com/jlowin) in [#1073](https://github.com/PrefectHQ/fastmcp/pull/1073)
+### Enhancements 🔧
+* Add Cursor support via CLI integration by [@jlowin](https://github.com/jlowin) in [#1052](https://github.com/PrefectHQ/fastmcp/pull/1052)
+* Add Claude Code install integration by [@jlowin](https://github.com/jlowin) in [#1053](https://github.com/PrefectHQ/fastmcp/pull/1053)
+* Generate MCP JSON config output from CLI as new `fastmcp install` command by [@jlowin](https://github.com/jlowin) in [#1056](https://github.com/PrefectHQ/fastmcp/pull/1056)
+* Use isawaitable instead of iscoroutine by [@jlowin](https://github.com/jlowin) in [#1059](https://github.com/PrefectHQ/fastmcp/pull/1059)
+* feat: Add `--path` Option to CLI for HTTP/SSE Route by [@davidbk-legit](https://github.com/davidbk-legit) in [#1087](https://github.com/PrefectHQ/fastmcp/pull/1087)
+* Fix concurrent proxy client operations with session isolation by [@jlowin](https://github.com/jlowin) in [#1083](https://github.com/PrefectHQ/fastmcp/pull/1083)
+### Fixes 🐞
+* Refactor Client context management to avoid concurrency issue by [@hopeful0](https://github.com/hopeful0) in [#1054](https://github.com/PrefectHQ/fastmcp/pull/1054)
+* Keep json schema $defs on transform by [@strawgate](https://github.com/strawgate) in [#1066](https://github.com/PrefectHQ/fastmcp/pull/1066)
+* Ensure fastmcp version copy is plaintext by [@jlowin](https://github.com/jlowin) in [#1071](https://github.com/PrefectHQ/fastmcp/pull/1071)
+* Fix single-element list unwrapping in tool content by [@jlowin](https://github.com/jlowin) in [#1074](https://github.com/PrefectHQ/fastmcp/pull/1074)
+* Fix max recursion error when pruning OpenAPI definitions by [@dimitribarbot](https://github.com/dimitribarbot) in [#1092](https://github.com/PrefectHQ/fastmcp/pull/1092)
+* Fix OpenAPI tool name registration when modified by mcp_component_fn by [@jlowin](https://github.com/jlowin) in [#1096](https://github.com/PrefectHQ/fastmcp/pull/1096)
+### Docs 📚
+* Docs: add example of more concise way to use bearer auth by [@neilconway](https://github.com/neilconway) in [#1055](https://github.com/PrefectHQ/fastmcp/pull/1055)
+* Update favicon by [@jlowin](https://github.com/jlowin) in [#1058](https://github.com/PrefectHQ/fastmcp/pull/1058)
+* Update environment note by [@jlowin](https://github.com/jlowin) in [#1075](https://github.com/PrefectHQ/fastmcp/pull/1075)
+* Add fastmcp version --copy documentation by [@jlowin](https://github.com/jlowin) in [#1076](https://github.com/PrefectHQ/fastmcp/pull/1076)
+### Other Changes 🦾
+* Remove asserts and add documentation following #1054 by [@jlowin](https://github.com/jlowin) in [#1057](https://github.com/PrefectHQ/fastmcp/pull/1057)
+* Add --copy flag for fastmcp version by [@jlowin](https://github.com/jlowin) in [#1063](https://github.com/PrefectHQ/fastmcp/pull/1063)
+* Fix docstring format for fastmcp.client.Client by [@neilconway](https://github.com/neilconway) in [#1094](https://github.com/PrefectHQ/fastmcp/pull/1094)
+
+## New Contributors
+* [@neilconway](https://github.com/neilconway) made their first contribution in [#1055](https://github.com/PrefectHQ/fastmcp/pull/1055)
+* [@davidbk-legit](https://github.com/davidbk-legit) made their first contribution in [#1087](https://github.com/PrefectHQ/fastmcp/pull/1087)
+* [@dimitribarbot](https://github.com/dimitribarbot) made their first contribution in [#1092](https://github.com/PrefectHQ/fastmcp/pull/1092)
+
+**Full Changelog**: [v2.10.2...v2.10.3](https://github.com/PrefectHQ/fastmcp/compare/v2.10.2...v2.10.3)
+
+</Update>
+
+<Update label="v2.10.2" description="2025-07-05">
+
+## [v2.10.2: Forward March](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.2)
+
+The headline feature of this release is the ability to "forward" advanced MCP interactions like logging, progress, and elicitation through proxy servers. If the remote server requests an elicitation, the proxy client will pass that request to the new, "ultimate" client.
+
+## What's Changed
+### New Features 🎉
+* Proxy support advanced MCP features by [@hopeful0](https://github.com/hopeful0) in [#1022](https://github.com/PrefectHQ/fastmcp/pull/1022)
+### Enhancements 🔧
+* Re-add splash screen by [@jlowin](https://github.com/jlowin) in [#1027](https://github.com/PrefectHQ/fastmcp/pull/1027)
+* Reduce banner padding by [@jlowin](https://github.com/jlowin) in [#1030](https://github.com/PrefectHQ/fastmcp/pull/1030)
+* Allow per-server timeouts in MCPConfig by [@cegersdoerfer](https://github.com/cegersdoerfer) in [#1031](https://github.com/PrefectHQ/fastmcp/pull/1031)
+* Support 'scp' claim for OAuth scopes in BearerAuthProvider by [@jlowin](https://github.com/jlowin) in [#1033](https://github.com/PrefectHQ/fastmcp/pull/1033)
+* Add path expansion to image/audio/file by [@jlowin](https://github.com/jlowin) in [#1038](https://github.com/PrefectHQ/fastmcp/pull/1038)
+* Ensure multi-client configurations use new ProxyClient by [@jlowin](https://github.com/jlowin) in [#1045](https://github.com/PrefectHQ/fastmcp/pull/1045)
+### Fixes 🐞
+* Expose stateless_http kwarg for mcp.run() by [@jlowin](https://github.com/jlowin) in [#1018](https://github.com/PrefectHQ/fastmcp/pull/1018)
+* Avoid propagating logs by [@jlowin](https://github.com/jlowin) in [#1042](https://github.com/PrefectHQ/fastmcp/pull/1042)
+### Docs 📚
+* Clean up docs by [@jlowin](https://github.com/jlowin) in [#1028](https://github.com/PrefectHQ/fastmcp/pull/1028)
+* Docs: clarify server URL paths for ChatGPT integration by [@thap2331](https://github.com/thap2331) in [#1017](https://github.com/PrefectHQ/fastmcp/pull/1017)
+### Other Changes 🦾
+* Split giant openapi test file into smaller files by [@jlowin](https://github.com/jlowin) in [#1034](https://github.com/PrefectHQ/fastmcp/pull/1034)
+* Add comprehensive OpenAPI 3.0 vs 3.1 compatibility tests by [@jlowin](https://github.com/jlowin) in [#1035](https://github.com/PrefectHQ/fastmcp/pull/1035)
+* Update banner and use console.log by [@jlowin](https://github.com/jlowin) in [#1041](https://github.com/PrefectHQ/fastmcp/pull/1041)
+
+## New Contributors
+* [@cegersdoerfer](https://github.com/cegersdoerfer) made their first contribution in [#1031](https://github.com/PrefectHQ/fastmcp/pull/1031)
+* [@hopeful0](https://github.com/hopeful0) made their first contribution in [#1022](https://github.com/PrefectHQ/fastmcp/pull/1022)
+* [@thap2331](https://github.com/thap2331) made their first contribution in [#1017](https://github.com/PrefectHQ/fastmcp/pull/1017)
+
+**Full Changelog**: [v2.10.1...v2.10.2](https://github.com/PrefectHQ/fastmcp/compare/v2.10.1...v2.10.2)
+
+</Update>
+
+<Update label="v2.10.1" description="2025-07-02">
+
+## [v2.10.1: Revert to Sender](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.1)
+
+A quick patch to revert the CLI banner that was added in v2.10.0.
+
+## What's Changed
+### Docs 📚
+* Update changelog.mdx by [@jlowin](https://github.com/jlowin) in [#1009](https://github.com/PrefectHQ/fastmcp/pull/1009)
+* Revert "Add CLI banner" by [@jlowin](https://github.com/jlowin) in [#1011](https://github.com/PrefectHQ/fastmcp/pull/1011)
+
+**Full Changelog**: [v2.10.0...v2.10.1](https://github.com/PrefectHQ/fastmcp/compare/v2.10.0...v2.10.1)
+
+</Update>
+
+<Update label="v2.10.0" description="2024-07-01">
+
+## [v2.10.0: Great Spec-tations](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.0)
+
+FastMCP 2.10 brings full compliance with the 6/18/2025 MCP spec update, introducing elicitation support for dynamic server-client communication and output schemas for structured tool responses. Please note that due to these changes, this release also includes a breaking change to the return signature of `client.call_tool()`.
+
+### Elicitation Support
+Elicitation allows MCP servers to request additional information from clients during tool execution, enabling more interactive and dynamic server behavior. This opens up new possibilities for tools that need user input or confirmation during execution.
+
+### Output Schemas
+Tools can now define structured output schemas, ensuring that responses conform to expected formats and making tool integration more predictable and type-safe.
+
+## What's Changed
+### New Features 🎉
+* MCP 6/18/25: Add output schema to tools by [@jlowin](https://github.com/jlowin) in [#901](https://github.com/PrefectHQ/fastmcp/pull/901)
+* MCP 6/18/25: Elicitation support by [@jlowin](https://github.com/jlowin) in [#889](https://github.com/PrefectHQ/fastmcp/pull/889)
+### Enhancements 🔧
+* Update types + tests for SDK changes by [@jlowin](https://github.com/jlowin) in [#888](https://github.com/PrefectHQ/fastmcp/pull/888)
+* MCP 6/18/25: Update auth primitives by [@jlowin](https://github.com/jlowin) in [#966](https://github.com/PrefectHQ/fastmcp/pull/966)
+* Add OpenAPI extensions support to HTTPRoute by [@maddymanu](https://github.com/maddymanu) in [#977](https://github.com/PrefectHQ/fastmcp/pull/977)
+* Add title field support to FastMCP components by [@jlowin](https://github.com/jlowin) in [#982](https://github.com/PrefectHQ/fastmcp/pull/982)
+* Support implicit Elicitation acceptance by [@jlowin](https://github.com/jlowin) in [#983](https://github.com/PrefectHQ/fastmcp/pull/983)
+* Support 'no response' elicitation requests by [@jlowin](https://github.com/jlowin) in [#992](https://github.com/PrefectHQ/fastmcp/pull/992)
+* Add Support for Configurable Algorithms by [@sstene1](https://github.com/sstene1) in [#997](https://github.com/PrefectHQ/fastmcp/pull/997)
+### Fixes 🐞
+* Improve stdio error handling to raise connection failures immediately by [@jlowin](https://github.com/jlowin) in [#984](https://github.com/PrefectHQ/fastmcp/pull/984)
+* Fix type hints for FunctionResource:fn by [@CfirTsabari](https://github.com/CfirTsabari) in [#986](https://github.com/PrefectHQ/fastmcp/pull/986)
+* Update link to OpenAI MCP example by [@mossbanay](https://github.com/mossbanay) in [#985](https://github.com/PrefectHQ/fastmcp/pull/985)
+* Fix output schema generation edge case by [@jlowin](https://github.com/jlowin) in [#995](https://github.com/PrefectHQ/fastmcp/pull/995)
+* Refactor array parameter formatting to reduce code duplication by [@jlowin](https://github.com/jlowin) in [#1007](https://github.com/PrefectHQ/fastmcp/pull/1007)
+* Fix OpenAPI array parameter explode handling by [@jlowin](https://github.com/jlowin) in [#1008](https://github.com/PrefectHQ/fastmcp/pull/1008)
+### Breaking Changes 🛫
+* MCP 6/18/25: Upgrade to mcp 1.10 by [@jlowin](https://github.com/jlowin) in [#887](https://github.com/PrefectHQ/fastmcp/pull/887)
+### Docs 📚
+* Update middleware imports and documentation by [@jlowin](https://github.com/jlowin) in [#999](https://github.com/PrefectHQ/fastmcp/pull/999)
+* Update OpenAI docs by [@jlowin](https://github.com/jlowin) in [#1001](https://github.com/PrefectHQ/fastmcp/pull/1001)
+* Add CLI banner by [@jlowin](https://github.com/jlowin) in [#1005](https://github.com/PrefectHQ/fastmcp/pull/1005)
+### Examples & Contrib 💡
+* Component Manager by [@gorocode](https://github.com/gorocode) in [#976](https://github.com/PrefectHQ/fastmcp/pull/976)
+### Other Changes 🦾
+* Minor auth improvements by [@jlowin](https://github.com/jlowin) in [#967](https://github.com/PrefectHQ/fastmcp/pull/967)
+* Add .ccignore for copychat by [@jlowin](https://github.com/jlowin) in [#1000](https://github.com/PrefectHQ/fastmcp/pull/1000)
+
+## New Contributors
+* [@maddymanu](https://github.com/maddymanu) made their first contribution in [#977](https://github.com/PrefectHQ/fastmcp/pull/977)
+* [@github0hello](https://github.com/github0hello) made their first contribution in [#979](https://github.com/PrefectHQ/fastmcp/pull/979)
+* [@tommitt](https://github.com/tommitt) made their first contribution in [#975](https://github.com/PrefectHQ/fastmcp/pull/975)
+* [@CfirTsabari](https://github.com/CfirTsabari) made their first contribution in [#986](https://github.com/PrefectHQ/fastmcp/pull/986)
+* [@mossbanay](https://github.com/mossbanay) made their first contribution in [#985](https://github.com/PrefectHQ/fastmcp/pull/985)
+* [@sstene1](https://github.com/sstene1) made their first contribution in [#997](https://github.com/PrefectHQ/fastmcp/pull/997)
+
+**Full Changelog**: [v2.9.2...v2.10.0](https://github.com/PrefectHQ/fastmcp/compare/v2.9.2...v2.10.0)
+
+</Update>
+
+<Update label="v2.9.2" description="2024-06-26">
+
+## [v2.9.2: Safety Pin](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.9.2)
+
+This is a patch release to pin `mcp` below 1.10, which includes changes related to the 6/18/2025 MCP spec update and could potentially break functionality for some FastMCP users.
+
+## What's Changed
+### Docs 📚
+* Fix version badge for messages by [@jlowin](https://github.com/jlowin) in [#960](https://github.com/PrefectHQ/fastmcp/pull/960)
+### Dependencies 📦
+* Pin mcp dependency by [@jlowin](https://github.com/jlowin) in [#962](https://github.com/PrefectHQ/fastmcp/pull/962)
+
+**Full Changelog**: [v2.9.1...v2.9.2](https://github.com/PrefectHQ/fastmcp/compare/v2.9.1...v2.9.2)
+
+</Update>
+
+<Update label="v2.9.1" description="2024-06-26">
+
+## [v2.9.1: Call Me Maybe](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.9.1)
+
+FastMCP 2.9.1 introduces automatic MCP list change notifications, allowing servers to notify clients when tools, resources, or prompts are dynamically updated. This enables more responsive and adaptive MCP integrations.
+
+## What's Changed
+### New Features 🎉
+* Add automatic MCP list change notifications and client message handling by [@jlowin](https://github.com/jlowin) in [#939](https://github.com/PrefectHQ/fastmcp/pull/939)
+### Enhancements 🔧
+* Add debug logging to bearer token authentication by [@jlowin](https://github.com/jlowin) in [#952](https://github.com/PrefectHQ/fastmcp/pull/952)
+### Fixes 🐞
+* Fix duplicate error logging in exception handlers by [@jlowin](https://github.com/jlowin) in [#938](https://github.com/PrefectHQ/fastmcp/pull/938)
+* Fix parameter location enum handling in OpenAPI parser by [@jlowin](https://github.com/jlowin) in [#953](https://github.com/PrefectHQ/fastmcp/pull/953)
+* Fix external schema reference handling in OpenAPI parser by [@jlowin](https://github.com/jlowin) in [#954](https://github.com/PrefectHQ/fastmcp/pull/954)
+### Docs 📚
+* Update changelog for 2.9 release by [@jlowin](https://github.com/jlowin) in [#929](https://github.com/PrefectHQ/fastmcp/pull/929)
+* Regenerate API references by [@zzstoatzz](https://github.com/zzstoatzz) in [#935](https://github.com/PrefectHQ/fastmcp/pull/935)
+* Regenerate API references by [@zzstoatzz](https://github.com/zzstoatzz) in [#947](https://github.com/PrefectHQ/fastmcp/pull/947)
+* Regenerate API references by [@zzstoatzz](https://github.com/zzstoatzz) in [#949](https://github.com/PrefectHQ/fastmcp/pull/949)
+### Examples & Contrib 💡
+* Add `create_thread` tool to bsky MCP server by [@zzstoatzz](https://github.com/zzstoatzz) in [#927](https://github.com/PrefectHQ/fastmcp/pull/927)
+* Update `mount_example.py` to work with current fastmcp API by [@rajephon](https://github.com/rajephon) in [#957](https://github.com/PrefectHQ/fastmcp/pull/957)
+
+## New Contributors
+* [@rajephon](https://github.com/rajephon) made their first contribution in [#957](https://github.com/PrefectHQ/fastmcp/pull/957)
+
+**Full Changelog**: [v2.9.0...v2.9.1](https://github.com/PrefectHQ/fastmcp/compare/v2.9.0...v2.9.1)
+
+</Update>
+
+<Update label="v2.9.0" description="2024-06-23">
+
+## [v2.9.0: Stuck in the Middleware With You](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.9.0)
+
+FastMCP 2.9 introduces two important features that push beyond the basic MCP protocol: MCP Middleware and server-side type conversion.
+
+### MCP Middleware
+MCP middleware lets you intercept and modify requests and responses at the protocol level, giving you powerful capabilities for logging, authentication, validation, and more. This is particularly useful for building production-ready MCP servers that need sophisticated request handling.
+
+### Server-side Type Conversion
+This release also introduces server-side type conversion for prompt arguments, ensuring that data is properly formatted before being passed to your functions. This reduces the burden on individual tools and prompts to handle type validation and conversion.
+
+## What's Changed
+### New Features 🎉
+* Add File utility for binary data by [@gorocode](https://github.com/gorocode) in [#843](https://github.com/PrefectHQ/fastmcp/pull/843)
+* Consolidate prefix logic into FastMCP methods by [@jlowin](https://github.com/jlowin) in [#861](https://github.com/PrefectHQ/fastmcp/pull/861)
+* Add MCP Middleware by [@jlowin](https://github.com/jlowin) in [#870](https://github.com/PrefectHQ/fastmcp/pull/870)
+* Implement server-side type conversion for prompt arguments by [@jlowin](https://github.com/jlowin) in [#908](https://github.com/PrefectHQ/fastmcp/pull/908)
+### Enhancements 🔧
+* Fix tool description indentation issue by [@zfflxx](https://github.com/zfflxx) in [#845](https://github.com/PrefectHQ/fastmcp/pull/845)
+* Add version parameter to FastMCP constructor by [@mkyutani](https://github.com/mkyutani) in [#842](https://github.com/PrefectHQ/fastmcp/pull/842)
+* Update version to not be positional by [@jlowin](https://github.com/jlowin) in [#848](https://github.com/PrefectHQ/fastmcp/pull/848)
+* Add key to component by [@jlowin](https://github.com/jlowin) in [#869](https://github.com/PrefectHQ/fastmcp/pull/869)
+* Add session_id property to Context for data sharing by [@jlowin](https://github.com/jlowin) in [#881](https://github.com/PrefectHQ/fastmcp/pull/881)
+* Fix CORS documentation example by [@jlowin](https://github.com/jlowin) in [#895](https://github.com/PrefectHQ/fastmcp/pull/895)
+### Fixes 🐞
+* "report_progress missing passing related_request_id causes notifications not working" by [@alexsee](https://github.com/alexsee) in [#838](https://github.com/PrefectHQ/fastmcp/pull/838)
+* Fix JWT issuer validation to support string values per RFC 7519 by [@jlowin](https://github.com/jlowin) in [#892](https://github.com/PrefectHQ/fastmcp/pull/892)
+* Fix BearerAuthProvider audience type annotations by [@jlowin](https://github.com/jlowin) in [#894](https://github.com/PrefectHQ/fastmcp/pull/894)
+### Docs 📚
+* Add CLAUDE.md development guidelines by [@jlowin](https://github.com/jlowin) in [#880](https://github.com/PrefectHQ/fastmcp/pull/880)
+* Update context docs for session_id property by [@jlowin](https://github.com/jlowin) in [#882](https://github.com/PrefectHQ/fastmcp/pull/882)
+* Add API reference by [@zzstoatzz](https://github.com/zzstoatzz) in [#893](https://github.com/PrefectHQ/fastmcp/pull/893)
+* Fix API ref rendering by [@zzstoatzz](https://github.com/zzstoatzz) in [#900](https://github.com/PrefectHQ/fastmcp/pull/900)
+* Simplify docs nav by [@jlowin](https://github.com/jlowin) in [#902](https://github.com/PrefectHQ/fastmcp/pull/902)
+* Add fastmcp inspect command by [@jlowin](https://github.com/jlowin) in [#904](https://github.com/PrefectHQ/fastmcp/pull/904)
+* Update client docs by [@jlowin](https://github.com/jlowin) in [#912](https://github.com/PrefectHQ/fastmcp/pull/912)
+* Update docs nav by [@jlowin](https://github.com/jlowin) in [#913](https://github.com/PrefectHQ/fastmcp/pull/913)
+* Update integration documentation for Claude Desktop, ChatGPT, and Claude Code by [@jlowin](https://github.com/jlowin) in [#915](https://github.com/PrefectHQ/fastmcp/pull/915)
+* Add http as an alias for streamable http by [@jlowin](https://github.com/jlowin) in [#917](https://github.com/PrefectHQ/fastmcp/pull/917)
+* Clean up parameter documentation by [@jlowin](https://github.com/jlowin) in [#918](https://github.com/PrefectHQ/fastmcp/pull/918)
+* Add middleware examples for timing, logging, rate limiting, and error handling by [@jlowin](https://github.com/jlowin) in [#919](https://github.com/PrefectHQ/fastmcp/pull/919)
+* ControlFlow → FastMCP rename by [@jlowin](https://github.com/jlowin) in [#922](https://github.com/PrefectHQ/fastmcp/pull/922)
+### Examples & Contrib 💡
+* Add contrib.mcp_mixin support for annotations by [@rsp2k](https://github.com/rsp2k) in [#860](https://github.com/PrefectHQ/fastmcp/pull/860)
+* Add ATProto (Bluesky) MCP Server Example by [@zzstoatzz](https://github.com/zzstoatzz) in [#916](https://github.com/PrefectHQ/fastmcp/pull/916)
+* Fix path in atproto example pyproject by [@zzstoatzz](https://github.com/zzstoatzz) in [#920](https://github.com/PrefectHQ/fastmcp/pull/920)
+* Remove uv source in example by [@zzstoatzz](https://github.com/zzstoatzz) in [#921](https://github.com/PrefectHQ/fastmcp/pull/921)
+
+## New Contributors
+* [@alexsee](https://github.com/alexsee) made their first contribution in [#838](https://github.com/PrefectHQ/fastmcp/pull/838)
+* [@zfflxx](https://github.com/zfflxx) made their first contribution in [#845](https://github.com/PrefectHQ/fastmcp/pull/845)
+* [@mkyutani](https://github.com/mkyutani) made their first contribution in [#842](https://github.com/PrefectHQ/fastmcp/pull/842)
+* [@gorocode](https://github.com/gorocode) made their first contribution in [#843](https://github.com/PrefectHQ/fastmcp/pull/843)
+* [@rsp2k](https://github.com/rsp2k) made their first contribution in [#860](https://github.com/PrefectHQ/fastmcp/pull/860)
+* [@owtaylor](https://github.com/owtaylor) made their first contribution in [#897](https://github.com/PrefectHQ/fastmcp/pull/897)
+* [@Jason-CKY](https://github.com/Jason-CKY) made their first contribution in [#906](https://github.com/PrefectHQ/fastmcp/pull/906)
+
+**Full Changelog**: [v2.8.1...v2.9.0](https://github.com/PrefectHQ/fastmcp/compare/v2.8.1...v2.9.0)
+
+</Update>
+
+<Update label="v2.8.1" description="2024-06-15">
+
+## [v2.8.1: Sound Judgement](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.8.1)
+
+2.8.1 introduces audio support, as well as minor fixes and updates for deprecated features.
+
+### Audio Support
+This release adds support for audio content in MCP tools and resources, expanding FastMCP's multimedia capabilities beyond text and images.
+
+## What's Changed
+### New Features 🎉
+* Add audio support by [@jlowin](https://github.com/jlowin) in [#833](https://github.com/PrefectHQ/fastmcp/pull/833)
+### Enhancements 🔧
+* Add flag for disabling deprecation warnings by [@jlowin](https://github.com/jlowin) in [#802](https://github.com/PrefectHQ/fastmcp/pull/802)
+* Add examples to Tool Arg Param transformation by [@strawgate](https://github.com/strawgate) in [#806](https://github.com/PrefectHQ/fastmcp/pull/806)
+### Fixes 🐞
+* Restore .settings access as deprecated by [@jlowin](https://github.com/jlowin) in [#800](https://github.com/PrefectHQ/fastmcp/pull/800)
+* Ensure handling of false http kwargs correctly; removed unused kwarg by [@jlowin](https://github.com/jlowin) in [#804](https://github.com/PrefectHQ/fastmcp/pull/804)
+* Bump mcp 1.9.4 by [@jlowin](https://github.com/jlowin) in [#835](https://github.com/PrefectHQ/fastmcp/pull/835)
+### Docs 📚
+* Update changelog for 2.8.0 by [@jlowin](https://github.com/jlowin) in [#794](https://github.com/PrefectHQ/fastmcp/pull/794)
+* Update welcome docs by [@jlowin](https://github.com/jlowin) in [#808](https://github.com/PrefectHQ/fastmcp/pull/808)
+* Update headers in docs by [@jlowin](https://github.com/jlowin) in [#809](https://github.com/PrefectHQ/fastmcp/pull/809)
+* Add MCP group to tutorials by [@jlowin](https://github.com/jlowin) in [#810](https://github.com/PrefectHQ/fastmcp/pull/810)
+* Add Community section to documentation by [@zzstoatzz](https://github.com/zzstoatzz) in [#819](https://github.com/PrefectHQ/fastmcp/pull/819)
+* Add 2.8 update by [@jlowin](https://github.com/jlowin) in [#821](https://github.com/PrefectHQ/fastmcp/pull/821)
+* Embed YouTube videos in community showcase by [@zzstoatzz](https://github.com/zzstoatzz) in [#820](https://github.com/PrefectHQ/fastmcp/pull/820)
+### Other Changes 🦾
+* Ensure http args are passed through by [@jlowin](https://github.com/jlowin) in [#803](https://github.com/PrefectHQ/fastmcp/pull/803)
+* Fix install link in readme by [@jlowin](https://github.com/jlowin) in [#836](https://github.com/PrefectHQ/fastmcp/pull/836)
+
+**Full Changelog**: [v2.8.0...v2.8.1](https://github.com/PrefectHQ/fastmcp/compare/v2.8.0...v2.8.1)
+
+</Update>
+
+<Update label="v2.8.0" description="2024-06-10">
+
+## [v2.8.0: Transform and Roll Out](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.8.0)
+
+FastMCP 2.8.0 introduces powerful new ways to customize and control your MCP servers! 
+
+### Tool Transformation
+
+The highlight of this release is first-class [**Tool Transformation**](/servers/transforms/tool-transformation), a new feature that lets you create enhanced variations of existing tools. You can now easily rename arguments, hide parameters, modify descriptions, and even wrap tools with custom validation or post-processing logic—all without rewriting the original code. This makes it easier than ever to adapt generic tools for specific LLM use cases or to simplify complex APIs. Huge thanks to [@strawgate](https://github.com/strawgate) for partnering on this, starting with [#591](https://github.com/PrefectHQ/fastmcp/discussions/591) and [#599](https://github.com/PrefectHQ/fastmcp/pull/599) and continuing offline.
+
+### Component Control
+This release also gives you more granular control over which components are exposed to clients. With new [**tag-based filtering**](/servers/server#tag-based-filtering), you can selectively enable or disable tools, resources, and prompts based on tags, perfect for managing different environments or user permissions. Complementing this, every component now supports being [programmatically enabled or disabled](/servers/tools#disabling-tools), offering dynamic control over your server's capabilities.
+
+### Tools-by-Default
+Finally, to improve compatibility with a wider range of LLM clients, this release changes the default behavior for OpenAPI integration: all API endpoints are now converted to `Tools` by default. This is a **breaking change** but pragmatically necessitated by the fact that the majority of MCP clients available today are, sadly, only compatible with MCP tools. Therefore, this change significantly simplifies the out-of-the-box experience and ensures your entire API is immediately accessible to any tool-using agent.
+
+## What's Changed
+### New Features 🎉
+* First-class tool transformation by [@jlowin](https://github.com/jlowin) in [#745](https://github.com/PrefectHQ/fastmcp/pull/745)
+* Support enable/disable for all FastMCP components (tools, prompts, resources, templates) by [@jlowin](https://github.com/jlowin) in [#781](https://github.com/PrefectHQ/fastmcp/pull/781)
+* Add support for tag-based component filtering by [@jlowin](https://github.com/jlowin) in [#748](https://github.com/PrefectHQ/fastmcp/pull/748)
+* Allow tag assignments for OpenAPI by [@jlowin](https://github.com/jlowin) in [#791](https://github.com/PrefectHQ/fastmcp/pull/791)
+### Enhancements 🔧
+* Create common base class for components by [@jlowin](https://github.com/jlowin) in [#776](https://github.com/PrefectHQ/fastmcp/pull/776)
+* Move components to own file; add resource by [@jlowin](https://github.com/jlowin) in [#777](https://github.com/PrefectHQ/fastmcp/pull/777)
+* Update FastMCP component with __eq__ and __repr__ by [@jlowin](https://github.com/jlowin) in [#779](https://github.com/PrefectHQ/fastmcp/pull/779)
+* Remove open-ended and server-specific settings by [@jlowin](https://github.com/jlowin) in [#750](https://github.com/PrefectHQ/fastmcp/pull/750)
+### Fixes 🐞
+* Ensure client is only initialized once by [@jlowin](https://github.com/jlowin) in [#758](https://github.com/PrefectHQ/fastmcp/pull/758)
+* Fix field validator for resource by [@jlowin](https://github.com/jlowin) in [#778](https://github.com/PrefectHQ/fastmcp/pull/778)
+* Ensure proxies can overwrite remote tools without falling back to the remote by [@jlowin](https://github.com/jlowin) in [#782](https://github.com/PrefectHQ/fastmcp/pull/782)
+### Breaking Changes 🛫
+* Treat all openapi routes as tools by [@jlowin](https://github.com/jlowin) in [#788](https://github.com/PrefectHQ/fastmcp/pull/788)
+* Fix issue with global OpenAPI tags by [@jlowin](https://github.com/jlowin) in [#792](https://github.com/PrefectHQ/fastmcp/pull/792)
+### Docs 📚
+* Minor docs updates by [@jlowin](https://github.com/jlowin) in [#755](https://github.com/PrefectHQ/fastmcp/pull/755)
+* Add 2.7 update by [@jlowin](https://github.com/jlowin) in [#756](https://github.com/PrefectHQ/fastmcp/pull/756)
+* Reduce 2.7 image size by [@jlowin](https://github.com/jlowin) in [#757](https://github.com/PrefectHQ/fastmcp/pull/757)
+* Update updates.mdx by [@jlowin](https://github.com/jlowin) in [#765](https://github.com/PrefectHQ/fastmcp/pull/765)
+* Hide docs sidebar scrollbar by default by [@jlowin](https://github.com/jlowin) in [#766](https://github.com/PrefectHQ/fastmcp/pull/766)
+* Add "stop vibe testing" to tutorials by [@jlowin](https://github.com/jlowin) in [#767](https://github.com/PrefectHQ/fastmcp/pull/767)
+* Add docs links by [@jlowin](https://github.com/jlowin) in [#768](https://github.com/PrefectHQ/fastmcp/pull/768)
+* Fix: updated variable name under Gemini remote client by [@yrangana](https://github.com/yrangana) in [#769](https://github.com/PrefectHQ/fastmcp/pull/769)
+* Revert "Hide docs sidebar scrollbar by default" by [@jlowin](https://github.com/jlowin) in [#770](https://github.com/PrefectHQ/fastmcp/pull/770)
+* Add updates by [@jlowin](https://github.com/jlowin) in [#773](https://github.com/PrefectHQ/fastmcp/pull/773)
+* Add tutorials by [@jlowin](https://github.com/jlowin) in [#783](https://github.com/PrefectHQ/fastmcp/pull/783)
+* Update LLM-friendly docs by [@jlowin](https://github.com/jlowin) in [#784](https://github.com/PrefectHQ/fastmcp/pull/784)
+* Update oauth.mdx by [@JeremyCraigMartinez](https://github.com/JeremyCraigMartinez) in [#787](https://github.com/PrefectHQ/fastmcp/pull/787)
+* Add changelog by [@jlowin](https://github.com/jlowin) in [#789](https://github.com/PrefectHQ/fastmcp/pull/789)
+* Add tutorials by [@jlowin](https://github.com/jlowin) in [#790](https://github.com/PrefectHQ/fastmcp/pull/790)
+* Add docs for tag-based filtering by [@jlowin](https://github.com/jlowin) in [#793](https://github.com/PrefectHQ/fastmcp/pull/793)
+### Other Changes 🦾
+* Create dependabot.yml by [@jlowin](https://github.com/jlowin) in [#759](https://github.com/PrefectHQ/fastmcp/pull/759)
+* Bump astral-sh/setup-uv from 3 to 6 by [@dependabot](https://github.com/dependabot) in [#760](https://github.com/PrefectHQ/fastmcp/pull/760)
+* Add dependencies section to release by [@jlowin](https://github.com/jlowin) in [#761](https://github.com/PrefectHQ/fastmcp/pull/761)
+* Remove extra imports for MCPConfig by [@Maanas-Verma](https://github.com/Maanas-Verma) in [#763](https://github.com/PrefectHQ/fastmcp/pull/763)
+* Split out enhancements in release notes by [@jlowin](https://github.com/jlowin) in [#764](https://github.com/PrefectHQ/fastmcp/pull/764)
+
+## New Contributors
+* [@dependabot](https://github.com/dependabot) made their first contribution in [#760](https://github.com/PrefectHQ/fastmcp/pull/760)
+* [@Maanas-Verma](https://github.com/Maanas-Verma) made their first contribution in [#763](https://github.com/PrefectHQ/fastmcp/pull/763)
+* [@JeremyCraigMartinez](https://github.com/JeremyCraigMartinez) made their first contribution in [#787](https://github.com/PrefectHQ/fastmcp/pull/787)
+
+**Full Changelog**: [v2.7.1...v2.8.0](https://github.com/PrefectHQ/fastmcp/compare/v2.7.1...v2.8.0)
+
+</Update>
+
+<Update label="v2.7.1" description="2024-06-08">
+
+## [v2.7.1: The Bearer Necessities](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.7.1)
+
+This release primarily contains a fix for parsing string tokens that are provided to FastMCP clients.
+
+### New Features 🎉
+
+* Respect cache setting, set default to 1 second by [@jlowin](https://github.com/jlowin) in [#747](https://github.com/PrefectHQ/fastmcp/pull/747)
+
+### Fixes 🐞
+
+* Ensure event store is properly typed by [@jlowin](https://github.com/jlowin) in [#753](https://github.com/PrefectHQ/fastmcp/pull/753)
+* Fix passing token string to client auth & add auth to MCPConfig clients by [@jlowin](https://github.com/jlowin) in [#754](https://github.com/PrefectHQ/fastmcp/pull/754)
+
+### Docs 📚
+
+* Docs : fix client to mcp\_client in Gemini example by [@yrangana](https://github.com/yrangana) in [#734](https://github.com/PrefectHQ/fastmcp/pull/734)
+* update add tool docstring by [@strawgate](https://github.com/strawgate) in [#739](https://github.com/PrefectHQ/fastmcp/pull/739)
+* Fix contrib link by [@richardkmichael](https://github.com/richardkmichael) in [#749](https://github.com/PrefectHQ/fastmcp/pull/749)
+
+### Other Changes 🦾
+
+* Switch Pydantic defaults to kwargs by [@strawgate](https://github.com/strawgate) in [#731](https://github.com/PrefectHQ/fastmcp/pull/731)
+* Fix Typo in CLI module by [@wfclark5](https://github.com/wfclark5) in [#737](https://github.com/PrefectHQ/fastmcp/pull/737)
+* chore: fix prompt docstring by [@danb27](https://github.com/danb27) in [#752](https://github.com/PrefectHQ/fastmcp/pull/752)
+* Add accept to excluded headers by [@jlowin](https://github.com/jlowin) in [#751](https://github.com/PrefectHQ/fastmcp/pull/751)
+
+### New Contributors
+
+* [@wfclark5](https://github.com/wfclark5) made their first contribution in [#737](https://github.com/PrefectHQ/fastmcp/pull/737)
+* [@richardkmichael](https://github.com/richardkmichael) made their first contribution in [#749](https://github.com/PrefectHQ/fastmcp/pull/749)
+* [@danb27](https://github.com/danb27) made their first contribution in [#752](https://github.com/PrefectHQ/fastmcp/pull/752)
+
+**Full Changelog**: [v2.7.0...v2.7.1](https://github.com/PrefectHQ/fastmcp/compare/v2.7.0...v2.7.1)
+</Update>
+
+<Update label="v2.7.0" description="2024-06-05">
+
+## [v2.7.0: Pare Programming](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.7.0)
+
+This is primarily a housekeeping release to remove or deprecate cruft that's accumulated since v1. Primarily, this release refactors FastMCP's internals in preparation for features planned in the next few major releases. However please note that as a result, this release has some minor breaking changes (which is why it's 2.7, not 2.6.2, in accordance with repo guidelines) though not to the core user-facing APIs.
+
+### Breaking Changes 🛫
+
+* decorators return the objects they create, not the decorated function
+* websockets is an optional dependency
+* methods on the server for automatically converting functions into tools/resources/prompts have been deprecated in favor of using the decorators directly
+
+### New Features 🎉
+
+* allow passing flags to servers by [@zzstoatzz](https://github.com/zzstoatzz) in [#690](https://github.com/PrefectHQ/fastmcp/pull/690)
+* replace $ref pointing to `#/components/schemas/` with `#/$defs/` by [@phateffect](https://github.com/phateffect) in [#697](https://github.com/PrefectHQ/fastmcp/pull/697)
+* Split Tool into Tool and FunctionTool by [@jlowin](https://github.com/jlowin) in [#700](https://github.com/PrefectHQ/fastmcp/pull/700)
+* Use strict basemodel for Prompt; relax from\_function deprecation by [@jlowin](https://github.com/jlowin) in [#701](https://github.com/PrefectHQ/fastmcp/pull/701)
+* Formalize resource/functionresource replationship by [@jlowin](https://github.com/jlowin) in [#702](https://github.com/PrefectHQ/fastmcp/pull/702)
+* Formalize template/functiontemplate split by [@jlowin](https://github.com/jlowin) in [#703](https://github.com/PrefectHQ/fastmcp/pull/703)
+* Support flexible @tool decorator call patterns by [@jlowin](https://github.com/jlowin) in [#706](https://github.com/PrefectHQ/fastmcp/pull/706)
+* Ensure deprecation warnings have stacklevel=2 by [@jlowin](https://github.com/jlowin) in [#710](https://github.com/PrefectHQ/fastmcp/pull/710)
+* Allow naked prompt decorator by [@jlowin](https://github.com/jlowin) in [#711](https://github.com/PrefectHQ/fastmcp/pull/711)
+
+### Fixes 🐞
+
+* Updates / Fixes for Tool Content Conversion by [@strawgate](https://github.com/strawgate) in [#642](https://github.com/PrefectHQ/fastmcp/pull/642)
+* Fix pr labeler permissions by [@jlowin](https://github.com/jlowin) in [#708](https://github.com/PrefectHQ/fastmcp/pull/708)
+* remove -n auto by [@jlowin](https://github.com/jlowin) in [#709](https://github.com/PrefectHQ/fastmcp/pull/709)
+* Fix links in README.md by [@alainivars](https://github.com/alainivars) in [#723](https://github.com/PrefectHQ/fastmcp/pull/723)
+
+Happily, this release DOES permit the use of "naked" decorators to align with Pythonic practice:
+
+```python
+@mcp.tool
+def my_tool():
+    ...
+```
+
+**Full Changelog**: [v2.6.2...v2.7.0](https://github.com/PrefectHQ/fastmcp/compare/v2.6.2...v2.7.0)
+</Update>
+
+<Update label="v2.6.1" description="2024-06-03">
+
+## [v2.6.1: Blast Auth (second ignition)](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.6.1)
+
+This is a patch release to restore py.typed in #686.
+
+### Docs 📚
+
+* Update readme by [@jlowin](https://github.com/jlowin) in [#679](https://github.com/PrefectHQ/fastmcp/pull/679)
+* Add gemini tutorial by [@jlowin](https://github.com/jlowin) in [#680](https://github.com/PrefectHQ/fastmcp/pull/680)
+* Fix : fix path error to CLI Documentation by [@yrangana](https://github.com/yrangana) in [#684](https://github.com/PrefectHQ/fastmcp/pull/684)
+* Update auth docs by [@jlowin](https://github.com/jlowin) in [#687](https://github.com/PrefectHQ/fastmcp/pull/687)
+
+### Other Changes 🦾
+
+* Remove deprecation notice by [@jlowin](https://github.com/jlowin) in [#677](https://github.com/PrefectHQ/fastmcp/pull/677)
+* Delete server.py by [@jlowin](https://github.com/jlowin) in [#681](https://github.com/PrefectHQ/fastmcp/pull/681)
+* Restore py.typed by [@jlowin](https://github.com/jlowin) in [#686](https://github.com/PrefectHQ/fastmcp/pull/686)
+
+### New Contributors
+
+* [@yrangana](https://github.com/yrangana) made their first contribution in [#684](https://github.com/PrefectHQ/fastmcp/pull/684)
+
+**Full Changelog**: [v2.6.0...v2.6.1](https://github.com/PrefectHQ/fastmcp/compare/v2.6.0...v2.6.1)
+</Update>
+
+<Update label="v2.6.0" description="2024-06-02">
+
+## [v2.6.0: Blast Auth](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.6.0)
+
+### New Features 🎉
+
+* Introduce MCP client oauth flow by [@jlowin](https://github.com/jlowin) in [#478](https://github.com/PrefectHQ/fastmcp/pull/478)
+* Support providing tools at init by [@jlowin](https://github.com/jlowin) in [#647](https://github.com/PrefectHQ/fastmcp/pull/647)
+* Simplify code for running servers in processes during tests by [@jlowin](https://github.com/jlowin) in [#649](https://github.com/PrefectHQ/fastmcp/pull/649)
+* Add basic bearer auth for server and client by [@jlowin](https://github.com/jlowin) in [#650](https://github.com/PrefectHQ/fastmcp/pull/650)
+* Support configuring bearer auth from env vars by [@jlowin](https://github.com/jlowin) in [#652](https://github.com/PrefectHQ/fastmcp/pull/652)
+* feat(tool): add support for excluding arguments from tool definition by [@deepak-stratforge](https://github.com/deepak-stratforge) in [#626](https://github.com/PrefectHQ/fastmcp/pull/626)
+* Add docs for server + client auth by [@jlowin](https://github.com/jlowin) in [#655](https://github.com/PrefectHQ/fastmcp/pull/655)
+
+### Fixes 🐞
+
+* fix: Support concurrency in FastMcpProxy (and Client) by [@Sillocan](https://github.com/Sillocan) in [#635](https://github.com/PrefectHQ/fastmcp/pull/635)
+* Ensure Client.close() cleans up client context appropriately by [@jlowin](https://github.com/jlowin) in [#643](https://github.com/PrefectHQ/fastmcp/pull/643)
+* Update client.mdx: ClientError namespace by [@mjkaye](https://github.com/mjkaye) in [#657](https://github.com/PrefectHQ/fastmcp/pull/657)
+
+### Docs 📚
+
+* Make FastMCPTransport support simulated Streamable HTTP Transport (didn't work) by [@jlowin](https://github.com/jlowin) in [#645](https://github.com/PrefectHQ/fastmcp/pull/645)
+* Document exclude\_args by [@jlowin](https://github.com/jlowin) in [#653](https://github.com/PrefectHQ/fastmcp/pull/653)
+* Update welcome by [@jlowin](https://github.com/jlowin) in [#673](https://github.com/PrefectHQ/fastmcp/pull/673)
+* Add Anthropic + Claude desktop integration guides by [@jlowin](https://github.com/jlowin) in [#674](https://github.com/PrefectHQ/fastmcp/pull/674)
+* Minor docs design updates by [@jlowin](https://github.com/jlowin) in [#676](https://github.com/PrefectHQ/fastmcp/pull/676)
+
+### Other Changes 🦾
+
+* Update test typing by [@jlowin](https://github.com/jlowin) in [#646](https://github.com/PrefectHQ/fastmcp/pull/646)
+* Add OpenAI integration docs by [@jlowin](https://github.com/jlowin) in [#660](https://github.com/PrefectHQ/fastmcp/pull/660)
+
+### New Contributors
+
+* [@Sillocan](https://github.com/Sillocan) made their first contribution in [#635](https://github.com/PrefectHQ/fastmcp/pull/635)
+* [@deepak-stratforge](https://github.com/deepak-stratforge) made their first contribution in [#626](https://github.com/PrefectHQ/fastmcp/pull/626)
+* [@mjkaye](https://github.com/mjkaye) made their first contribution in [#657](https://github.com/PrefectHQ/fastmcp/pull/657)
+
+**Full Changelog**: [v2.5.2...v2.6.0](https://github.com/PrefectHQ/fastmcp/compare/v2.5.2...v2.6.0)
+</Update>
+
+<Update label="v2.5.2" description="2024-05-29">
+
+## [v2.5.2: Stayin' Alive](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.5.2)
+
+### New Features 🎉
+
+* Add graceful error handling for unreachable mounted servers by [@davenpi](https://github.com/davenpi) in [#605](https://github.com/PrefectHQ/fastmcp/pull/605)
+* Improve type inference from client transport by [@jlowin](https://github.com/jlowin) in [#623](https://github.com/PrefectHQ/fastmcp/pull/623)
+* Add keep\_alive param to reuse subprocess by [@jlowin](https://github.com/jlowin) in [#624](https://github.com/PrefectHQ/fastmcp/pull/624)
+
+### Fixes 🐞
+
+* Fix handling tools without descriptions by [@jlowin](https://github.com/jlowin) in [#610](https://github.com/PrefectHQ/fastmcp/pull/610)
+* Don't print env vars to console when format is wrong by [@jlowin](https://github.com/jlowin) in [#615](https://github.com/PrefectHQ/fastmcp/pull/615)
+* Ensure behavior-affecting headers are excluded when forwarding proxies/openapi by [@jlowin](https://github.com/jlowin) in [#620](https://github.com/PrefectHQ/fastmcp/pull/620)
+
+### Docs 📚
+
+* Add notes about uv and claude desktop by [@jlowin](https://github.com/jlowin) in [#597](https://github.com/PrefectHQ/fastmcp/pull/597)
+
+### Other Changes 🦾
+
+* add init\_timeout for mcp client by [@jfouret](https://github.com/jfouret) in [#607](https://github.com/PrefectHQ/fastmcp/pull/607)
+* Add init\_timeout for mcp client (incl settings) by [@jlowin](https://github.com/jlowin) in [#609](https://github.com/PrefectHQ/fastmcp/pull/609)
+* Support for uppercase letters at the log level by [@ksawaray](https://github.com/ksawaray) in [#625](https://github.com/PrefectHQ/fastmcp/pull/625)
+
+### New Contributors
+
+* [@jfouret](https://github.com/jfouret) made their first contribution in [#607](https://github.com/PrefectHQ/fastmcp/pull/607)
+* [@ksawaray](https://github.com/ksawaray) made their first contribution in [#625](https://github.com/PrefectHQ/fastmcp/pull/625)
+
+**Full Changelog**: [v2.5.1...v2.5.2](https://github.com/PrefectHQ/fastmcp/compare/v2.5.1...v2.5.2)
+</Update>
+
+<Update label="v2.5.1" description="2024-05-24">
+
+## [v2.5.1: Route Awakening (Part 2)](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.5.1)
+
+### Fixes 🐞
+
+* Ensure content-length is always stripped from client headers by [@jlowin](https://github.com/jlowin) in [#589](https://github.com/PrefectHQ/fastmcp/pull/589)
+
+### Docs 📚
+
+* Fix redundant section of docs by [@jlowin](https://github.com/jlowin) in [#583](https://github.com/PrefectHQ/fastmcp/pull/583)
+
+**Full Changelog**: [v2.5.0...v2.5.1](https://github.com/PrefectHQ/fastmcp/compare/v2.5.0...v2.5.1)
+</Update>
+
+<Update label="v2.5.0" description="2024-05-24">
+
+## [v2.5.0: Route Awakening](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.5.0)
+
+This release introduces completely new tools for generating and customizing MCP servers from OpenAPI specs and FastAPI apps, including popular requests like mechanisms for determining what routes map to what MCP components; renaming routes; and customizing the generated MCP components.
+
+### New Features 🎉
+
+* Add FastMCP 1.0 server support for in-memory Client / Testing by [@jlowin](https://github.com/jlowin) in [#539](https://github.com/PrefectHQ/fastmcp/pull/539)
+* Minor addition: add transport to stdio server in mcpconfig, with default by [@jlowin](https://github.com/jlowin) in [#555](https://github.com/PrefectHQ/fastmcp/pull/555)
+* Raise an error if a Client is created with no servers in config by [@jlowin](https://github.com/jlowin) in [#554](https://github.com/PrefectHQ/fastmcp/pull/554)
+* Expose model preferences in `Context.sample` for flexible model selection. by [@davenpi](https://github.com/davenpi) in [#542](https://github.com/PrefectHQ/fastmcp/pull/542)
+* Ensure custom routes are respected by [@jlowin](https://github.com/jlowin) in [#558](https://github.com/PrefectHQ/fastmcp/pull/558)
+* Add client method to send cancellation notifications by [@davenpi](https://github.com/davenpi) in [#563](https://github.com/PrefectHQ/fastmcp/pull/563)
+* Enhance route map logic for include/exclude OpenAPI routes by [@jlowin](https://github.com/jlowin) in [#564](https://github.com/PrefectHQ/fastmcp/pull/564)
+* Add tag-based route maps by [@jlowin](https://github.com/jlowin) in [#565](https://github.com/PrefectHQ/fastmcp/pull/565)
+* Add advanced control of openAPI route creation by [@jlowin](https://github.com/jlowin) in [#566](https://github.com/PrefectHQ/fastmcp/pull/566)
+* Make error masking configurable by [@jlowin](https://github.com/jlowin) in [#550](https://github.com/PrefectHQ/fastmcp/pull/550)
+* Ensure client headers are passed through to remote servers by [@jlowin](https://github.com/jlowin) in [#575](https://github.com/PrefectHQ/fastmcp/pull/575)
+* Use lowercase name for headers when comparing by [@jlowin](https://github.com/jlowin) in [#576](https://github.com/PrefectHQ/fastmcp/pull/576)
+* Permit more flexible name generation for OpenAPI servers by [@jlowin](https://github.com/jlowin) in [#578](https://github.com/PrefectHQ/fastmcp/pull/578)
+* Ensure that tools/templates/prompts are compatible with callable objects by [@jlowin](https://github.com/jlowin) in [#579](https://github.com/PrefectHQ/fastmcp/pull/579)
+
+### Docs 📚
+
+* Add version badge for prefix formats by [@jlowin](https://github.com/jlowin) in [#537](https://github.com/PrefectHQ/fastmcp/pull/537)
+* Add versioning note to docs by [@jlowin](https://github.com/jlowin) in [#551](https://github.com/PrefectHQ/fastmcp/pull/551)
+* Bump 2.3.6 references to 2.4.0 by [@jlowin](https://github.com/jlowin) in [#567](https://github.com/PrefectHQ/fastmcp/pull/567)
+
+**Full Changelog**: [v2.4.0...v2.5.0](https://github.com/PrefectHQ/fastmcp/compare/v2.4.0...v2.5.0)
+</Update>
+
+<Update label="v2.4.0" description="2024-05-21">
+
+## [v2.4.0: Config and Conquer](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.4.0)
+
+**Note**: this release includes a backwards-incompatible change to how resources are prefixed when mounted in composed servers. However, it is only backwards-incompatible if users were running tests or manually loading resources by prefixed key; LLMs should not have any issue discovering the new route.
+
+### New Features 🎉
+
+* Allow \* Methods and all routes as tools shortcuts by [@jlowin](https://github.com/jlowin) in [#520](https://github.com/PrefectHQ/fastmcp/pull/520)
+* Improved support for config dicts by [@jlowin](https://github.com/jlowin) in [#522](https://github.com/PrefectHQ/fastmcp/pull/522)
+* Support creating clients from MCP config dicts, including multi-server clients by [@jlowin](https://github.com/jlowin) in [#527](https://github.com/PrefectHQ/fastmcp/pull/527)
+* Make resource prefix format configurable by [@jlowin](https://github.com/jlowin) in [#534](https://github.com/PrefectHQ/fastmcp/pull/534)
+
+### Fixes 🐞
+
+* Avoid hanging on initializing server session by [@jlowin](https://github.com/jlowin) in [#523](https://github.com/PrefectHQ/fastmcp/pull/523)
+
+### Breaking Changes 🛫
+
+* Remove customizable separators; improve resource separator by [@jlowin](https://github.com/jlowin) in [#526](https://github.com/PrefectHQ/fastmcp/pull/526)
+
+### Docs 📚
+
+* Improve client documentation by [@jlowin](https://github.com/jlowin) in [#517](https://github.com/PrefectHQ/fastmcp/pull/517)
+
+### Other Changes 🦾
+
+* Ensure openapi path params are handled properly by [@jlowin](https://github.com/jlowin) in [#519](https://github.com/PrefectHQ/fastmcp/pull/519)
+* better error when missing lifespan by [@zzstoatzz](https://github.com/zzstoatzz) in [#521](https://github.com/PrefectHQ/fastmcp/pull/521)
+
+**Full Changelog**: [v2.3.5...v2.4.0](https://github.com/PrefectHQ/fastmcp/compare/v2.3.5...v2.4.0)
+</Update>
+
+<Update label="v2.3.5" description="2024-05-20">
+
+## [v2.3.5: Making Progress](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.3.5)
+
+### New Features 🎉
+
+* support messages in progress notifications by [@rickygenhealth](https://github.com/rickygenhealth) in [#471](https://github.com/PrefectHQ/fastmcp/pull/471)
+* feat: Add middleware option in server.run by [@Maxi91f](https://github.com/Maxi91f) in [#475](https://github.com/PrefectHQ/fastmcp/pull/475)
+* Add lifespan property to app by [@jlowin](https://github.com/jlowin) in [#483](https://github.com/PrefectHQ/fastmcp/pull/483)
+* Update `fastmcp run` to work with remote servers by [@jlowin](https://github.com/jlowin) in [#491](https://github.com/PrefectHQ/fastmcp/pull/491)
+* Add FastMCP.as\_proxy() by [@jlowin](https://github.com/jlowin) in [#490](https://github.com/PrefectHQ/fastmcp/pull/490)
+* Infer sse transport from urls containing /sse by [@jlowin](https://github.com/jlowin) in [#512](https://github.com/PrefectHQ/fastmcp/pull/512)
+* Add progress handler to client by [@jlowin](https://github.com/jlowin) in [#513](https://github.com/PrefectHQ/fastmcp/pull/513)
+* Store the initialize result on the client by [@jlowin](https://github.com/jlowin) in [#509](https://github.com/PrefectHQ/fastmcp/pull/509)
+
+### Fixes 🐞
+
+* Remove patch and use upstream SSEServerTransport by [@jlowin](https://github.com/jlowin) in [#425](https://github.com/PrefectHQ/fastmcp/pull/425)
+
+### Docs 📚
+
+* Update transport docs by [@jlowin](https://github.com/jlowin) in [#458](https://github.com/PrefectHQ/fastmcp/pull/458)
+* update proxy docs + example by [@zzstoatzz](https://github.com/zzstoatzz) in [#460](https://github.com/PrefectHQ/fastmcp/pull/460)
+* doc(asgi): Change custom route example to PlainTextResponse by [@mcw0933](https://github.com/mcw0933) in [#477](https://github.com/PrefectHQ/fastmcp/pull/477)
+* Store FastMCP instance on app.state.fastmcp\_server by [@jlowin](https://github.com/jlowin) in [#489](https://github.com/PrefectHQ/fastmcp/pull/489)
+* Improve AGENTS.md overview by [@jlowin](https://github.com/jlowin) in [#492](https://github.com/PrefectHQ/fastmcp/pull/492)
+* Update release numbers for anticipated version by [@jlowin](https://github.com/jlowin) in [#516](https://github.com/PrefectHQ/fastmcp/pull/516)
+
+### Other Changes 🦾
+
+* run tests on all PRs by [@jlowin](https://github.com/jlowin) in [#468](https://github.com/PrefectHQ/fastmcp/pull/468)
+* add null check by [@zzstoatzz](https://github.com/zzstoatzz) in [#473](https://github.com/PrefectHQ/fastmcp/pull/473)
+* strict typing for `server.py` by [@zzstoatzz](https://github.com/zzstoatzz) in [#476](https://github.com/PrefectHQ/fastmcp/pull/476)
+* Doc(quickstart): Fix import statements by [@mai-nakagawa](https://github.com/mai-nakagawa) in [#479](https://github.com/PrefectHQ/fastmcp/pull/479)
+* Add labeler by [@jlowin](https://github.com/jlowin) in [#484](https://github.com/PrefectHQ/fastmcp/pull/484)
+* Fix flaky timeout test by increasing timeout (#474) by [@davenpi](https://github.com/davenpi) in [#486](https://github.com/PrefectHQ/fastmcp/pull/486)
+* Skipping `test_permission_error` if runner is root. by [@ZiadAmerr](https://github.com/ZiadAmerr) in [#502](https://github.com/PrefectHQ/fastmcp/pull/502)
+* allow passing full uvicorn config by [@zzstoatzz](https://github.com/zzstoatzz) in [#504](https://github.com/PrefectHQ/fastmcp/pull/504)
+* Skip timeout tests on windows by [@jlowin](https://github.com/jlowin) in [#514](https://github.com/PrefectHQ/fastmcp/pull/514)
+
+### New Contributors
+
+* [@rickygenhealth](https://github.com/rickygenhealth) made their first contribution in [#471](https://github.com/PrefectHQ/fastmcp/pull/471)
+* [@Maxi91f](https://github.com/Maxi91f) made their first contribution in [#475](https://github.com/PrefectHQ/fastmcp/pull/475)
+* [@mcw0933](https://github.com/mcw0933) made their first contribution in [#477](https://github.com/PrefectHQ/fastmcp/pull/477)
+* [@mai-nakagawa](https://github.com/mai-nakagawa) made their first contribution in [#479](https://github.com/PrefectHQ/fastmcp/pull/479)
+* [@ZiadAmerr](https://github.com/ZiadAmerr) made their first contribution in [#502](https://github.com/PrefectHQ/fastmcp/pull/502)
+
+**Full Changelog**: [v2.3.4...v2.3.5](https://github.com/PrefectHQ/fastmcp/compare/v2.3.4...v2.3.5)
+</Update>
+
+<Update label="v2.3.4" description="2024-05-15">
+
+## [v2.3.4: Error Today, Gone Tomorrow](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.3.4)
+
+### New Features 🎉
+
+* logging stack trace for easier debugging by [@jbkoh](https://github.com/jbkoh) in [#413](https://github.com/PrefectHQ/fastmcp/pull/413)
+* add missing StreamableHttpTransport in client exports by [@yihuang](https://github.com/yihuang) in [#408](https://github.com/PrefectHQ/fastmcp/pull/408)
+* Improve error handling for tools and resources by [@jlowin](https://github.com/jlowin) in [#434](https://github.com/PrefectHQ/fastmcp/pull/434)
+* feat: add support for removing tools from server by [@davenpi](https://github.com/davenpi) in [#437](https://github.com/PrefectHQ/fastmcp/pull/437)
+* Prune titles from JSONSchemas by [@jlowin](https://github.com/jlowin) in [#449](https://github.com/PrefectHQ/fastmcp/pull/449)
+* Declare toolsChanged capability for stdio server. by [@davenpi](https://github.com/davenpi) in [#450](https://github.com/PrefectHQ/fastmcp/pull/450)
+* Improve handling of exceptiongroups when raised in clients by [@jlowin](https://github.com/jlowin) in [#452](https://github.com/PrefectHQ/fastmcp/pull/452)
+* Add timeout support to client by [@jlowin](https://github.com/jlowin) in [#455](https://github.com/PrefectHQ/fastmcp/pull/455)
+
+### Fixes 🐞
+
+* Pin to mcp 1.8.1 to resolve callback deadlocks with SHTTP by [@jlowin](https://github.com/jlowin) in [#427](https://github.com/PrefectHQ/fastmcp/pull/427)
+* Add reprs for OpenAPI objects by [@jlowin](https://github.com/jlowin) in [#447](https://github.com/PrefectHQ/fastmcp/pull/447)
+* Ensure openapi defs for structured objects are loaded properly by [@jlowin](https://github.com/jlowin) in [#448](https://github.com/PrefectHQ/fastmcp/pull/448)
+* Ensure tests run against correct python version by [@jlowin](https://github.com/jlowin) in [#454](https://github.com/PrefectHQ/fastmcp/pull/454)
+* Ensure result is only returned if a new key was found by [@jlowin](https://github.com/jlowin) in [#456](https://github.com/PrefectHQ/fastmcp/pull/456)
+
+### Docs 📚
+
+* Add documentation for tool removal by [@jlowin](https://github.com/jlowin) in [#440](https://github.com/PrefectHQ/fastmcp/pull/440)
+
+### Other Changes 🦾
+
+* Deprecate passing settings to the FastMCP instance by [@jlowin](https://github.com/jlowin) in [#424](https://github.com/PrefectHQ/fastmcp/pull/424)
+* Add path prefix to test by [@jlowin](https://github.com/jlowin) in [#432](https://github.com/PrefectHQ/fastmcp/pull/432)
+
+### New Contributors
+
+* [@jbkoh](https://github.com/jbkoh) made their first contribution in [#413](https://github.com/PrefectHQ/fastmcp/pull/413)
+* [@davenpi](https://github.com/davenpi) made their first contribution in [#437](https://github.com/PrefectHQ/fastmcp/pull/437)
+
+**Full Changelog**: [v2.3.3...v2.3.4](https://github.com/PrefectHQ/fastmcp/compare/v2.3.3...v2.3.4)
+</Update>
+
+<Update label="v2.3.3" description="2024-05-10">
+
+## [v2.3.3: SSE you later](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.3.3)
+
+This is a hotfix for a bug introduced in 2.3.2 that broke SSE servers
+
+### Fixes 🐞
+
+* Fix bug that sets message path and sse path to same value by [@jlowin](https://github.com/jlowin) in [#405](https://github.com/PrefectHQ/fastmcp/pull/405)
+
+### Docs 📚
+
+* Update composition docs by [@jlowin](https://github.com/jlowin) in [#403](https://github.com/PrefectHQ/fastmcp/pull/403)
+
+### Other Changes 🦾
+
+* Add test for no prefix when importing by [@jlowin](https://github.com/jlowin) in [#404](https://github.com/PrefectHQ/fastmcp/pull/404)
+
+**Full Changelog**: [v2.3.2...v2.3.3](https://github.com/PrefectHQ/fastmcp/compare/v2.3.2...v2.3.3)
+</Update>
+
+<Update label="v2.3.2" description="2024-05-10">
+
+## [v2.3.2: Stuck in the Middleware With You](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.3.2)
+
+### New Features 🎉
+
+* Allow users to pass middleware to starlette app constructors by [@jlowin](https://github.com/jlowin) in [#398](https://github.com/PrefectHQ/fastmcp/pull/398)
+* Deprecate transport-specific methods on FastMCP server by [@jlowin](https://github.com/jlowin) in [#401](https://github.com/PrefectHQ/fastmcp/pull/401)
+
+### Docs 📚
+
+* Update CLI docs by [@jlowin](https://github.com/jlowin) in [#402](https://github.com/PrefectHQ/fastmcp/pull/402)
+
+### Other Changes 🦾
+
+* Adding 23 tests for CLI by [@didier-durand](https://github.com/didier-durand) in [#394](https://github.com/PrefectHQ/fastmcp/pull/394)
+
+**Full Changelog**: [v2.3.1...v2.3.2](https://github.com/PrefectHQ/fastmcp/compare/v2.3.1...v2.3.2)
+</Update>
+
+<Update label="v2.3.1" description="2024-05-09">
+
+## [v2.3.1: For Good-nests Sake](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.3.1)
+
+This release primarily patches a long-standing bug with nested ASGI SSE servers.
+
+### Fixes 🐞
+
+* Fix tool result serialization when the tool returns a list by [@strawgate](https://github.com/strawgate) in [#379](https://github.com/PrefectHQ/fastmcp/pull/379)
+* Ensure FastMCP handles nested SSE and SHTTP apps properly in ASGI frameworks by [@jlowin](https://github.com/jlowin) in [#390](https://github.com/PrefectHQ/fastmcp/pull/390)
+
+### Docs 📚
+
+* Update transport docs by [@jlowin](https://github.com/jlowin) in [#377](https://github.com/PrefectHQ/fastmcp/pull/377)
+* Add llms.txt to docs by [@jlowin](https://github.com/jlowin) in [#384](https://github.com/PrefectHQ/fastmcp/pull/384)
+* Fixing various text typos by [@didier-durand](https://github.com/didier-durand) in [#385](https://github.com/PrefectHQ/fastmcp/pull/385)
+
+### Other Changes 🦾
+
+* Adding a few tests to Image type by [@didier-durand](https://github.com/didier-durand) in [#387](https://github.com/PrefectHQ/fastmcp/pull/387)
+* Adding tests for TimedCache by [@didier-durand](https://github.com/didier-durand) in [#388](https://github.com/PrefectHQ/fastmcp/pull/388)
+
+### New Contributors
+
+* [@didier-durand](https://github.com/didier-durand) made their first contribution in [#385](https://github.com/PrefectHQ/fastmcp/pull/385)
+
+**Full Changelog**: [v2.3.0...v2.3.1](https://github.com/PrefectHQ/fastmcp/compare/v2.3.0...v2.3.1)
+</Update>
+
+<Update label="v2.3.0" description="2024-05-08">
+
+## [v2.3.0: Stream Me Up, Scotty](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.3.0)
+
+### New Features 🎉
+
+* Add streaming support for HTTP transport by [@jlowin](https://github.com/jlowin) in [#365](https://github.com/PrefectHQ/fastmcp/pull/365)
+* Support streaming HTTP transport in clients by [@jlowin](https://github.com/jlowin) in [#366](https://github.com/PrefectHQ/fastmcp/pull/366)
+* Add streaming support to CLI by [@jlowin](https://github.com/jlowin) in [#367](https://github.com/PrefectHQ/fastmcp/pull/367)
+
+### Fixes 🐞
+
+* Fix streaming transport initialization by [@jlowin](https://github.com/jlowin) in [#368](https://github.com/PrefectHQ/fastmcp/pull/368)
+
+### Docs 📚
+
+* Update transport documentation for streaming support by [@jlowin](https://github.com/jlowin) in [#369](https://github.com/PrefectHQ/fastmcp/pull/369)
+
+**Full Changelog**: [v2.2.10...v2.3.0](https://github.com/PrefectHQ/fastmcp/compare/v2.2.10...v2.3.0)
+</Update>
+
+<Update label="v2.2.10" description="2024-05-06">
+
+## [v2.2.10: That's JSON Bourne](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.10)
+
+### Fixes 🐞
+
+* Disable automatic JSON parsing of tool args by [@jlowin](https://github.com/jlowin) in [#341](https://github.com/PrefectHQ/fastmcp/pull/341)
+* Fix prompt test by [@jlowin](https://github.com/jlowin) in [#342](https://github.com/PrefectHQ/fastmcp/pull/342)
+
+### Other Changes 🦾
+
+* Update docs.json by [@jlowin](https://github.com/jlowin) in [#338](https://github.com/PrefectHQ/fastmcp/pull/338)
+* Add test coverage + tests on 4 examples by [@alainivars](https://github.com/alainivars) in [#306](https://github.com/PrefectHQ/fastmcp/pull/306)
+
+### New Contributors
+
+* [@alainivars](https://github.com/alainivars) made their first contribution in [#306](https://github.com/PrefectHQ/fastmcp/pull/306)
+
+**Full Changelog**: [v2.2.9...v2.2.10](https://github.com/PrefectHQ/fastmcp/compare/v2.2.9...v2.2.10)
+</Update>
+
+<Update label="v2.2.9" description="2024-05-06">
+
+## [v2.2.9: Str-ing the Pot (Hotfix)](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.9)
+
+This release is a hotfix for the issue detailed in #330
+
+### Fixes 🐞
+
+* Prevent invalid resource URIs by [@jlowin](https://github.com/jlowin) in [#336](https://github.com/PrefectHQ/fastmcp/pull/336)
+* Coerce numbers to str by [@jlowin](https://github.com/jlowin) in [#337](https://github.com/PrefectHQ/fastmcp/pull/337)
+
+### Docs 📚
+
+* Add client badge by [@jlowin](https://github.com/jlowin) in [#327](https://github.com/PrefectHQ/fastmcp/pull/327)
+* Update bug.yml by [@jlowin](https://github.com/jlowin) in [#328](https://github.com/PrefectHQ/fastmcp/pull/328)
+
+### Other Changes 🦾
+
+* Update quickstart.mdx example to include import by [@discdiver](https://github.com/discdiver) in [#329](https://github.com/PrefectHQ/fastmcp/pull/329)
+
+### New Contributors
+
+* [@discdiver](https://github.com/discdiver) made their first contribution in [#329](https://github.com/PrefectHQ/fastmcp/pull/329)
+
+**Full Changelog**: [v2.2.8...v2.2.9](https://github.com/PrefectHQ/fastmcp/compare/v2.2.8...v2.2.9)
+</Update>
+
+<Update label="v2.2.8" description="2024-05-05">
+
+## [v2.2.8: Parse and Recreation](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.8)
+
+### New Features 🎉
+
+* Replace custom parsing with TypeAdapter by [@jlowin](https://github.com/jlowin) in [#314](https://github.com/PrefectHQ/fastmcp/pull/314)
+* Handle \*args/\*\*kwargs appropriately for various components by [@jlowin](https://github.com/jlowin) in [#317](https://github.com/PrefectHQ/fastmcp/pull/317)
+* Add timeout-graceful-shutdown as a default config for SSE app by [@jlowin](https://github.com/jlowin) in [#323](https://github.com/PrefectHQ/fastmcp/pull/323)
+* Ensure prompts return descriptions by [@jlowin](https://github.com/jlowin) in [#325](https://github.com/PrefectHQ/fastmcp/pull/325)
+
+### Fixes 🐞
+
+* Ensure that tool serialization has a graceful fallback by [@jlowin](https://github.com/jlowin) in [#310](https://github.com/PrefectHQ/fastmcp/pull/310)
+
+### Docs 📚
+
+* Update docs for clarity by [@jlowin](https://github.com/jlowin) in [#312](https://github.com/PrefectHQ/fastmcp/pull/312)
+
+### Other Changes 🦾
+
+* Remove is\_async attribute by [@jlowin](https://github.com/jlowin) in [#315](https://github.com/PrefectHQ/fastmcp/pull/315)
+* Dry out retrieving context kwarg by [@jlowin](https://github.com/jlowin) in [#316](https://github.com/PrefectHQ/fastmcp/pull/316)
+
+**Full Changelog**: [v2.2.7...v2.2.8](https://github.com/PrefectHQ/fastmcp/compare/v2.2.7...v2.2.8)
+</Update>
+
+<Update label="v2.2.7" description="2024-05-03">
+
+## [v2.2.7: You Auth to Know Better](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.7)
+
+### New Features 🎉
+
+* use pydantic\_core.to\_json by [@jlowin](https://github.com/jlowin) in [#290](https://github.com/PrefectHQ/fastmcp/pull/290)
+* Ensure openapi descriptions are included in tool details by [@jlowin](https://github.com/jlowin) in [#293](https://github.com/PrefectHQ/fastmcp/pull/293)
+* Bump mcp to 1.7.1 by [@jlowin](https://github.com/jlowin) in [#298](https://github.com/PrefectHQ/fastmcp/pull/298)
+* Add support for tool annotations by [@jlowin](https://github.com/jlowin) in [#299](https://github.com/PrefectHQ/fastmcp/pull/299)
+* Add auth support by [@jlowin](https://github.com/jlowin) in [#300](https://github.com/PrefectHQ/fastmcp/pull/300)
+* Add low-level methods to client by [@jlowin](https://github.com/jlowin) in [#301](https://github.com/PrefectHQ/fastmcp/pull/301)
+* Add method for retrieving current starlette request to FastMCP context by [@jlowin](https://github.com/jlowin) in [#302](https://github.com/PrefectHQ/fastmcp/pull/302)
+* get\_starlette\_request → get\_http\_request by [@jlowin](https://github.com/jlowin) in [#303](https://github.com/PrefectHQ/fastmcp/pull/303)
+* Support custom Serializer for Tools by [@strawgate](https://github.com/strawgate) in [#308](https://github.com/PrefectHQ/fastmcp/pull/308)
+* Support proxy mount by [@jlowin](https://github.com/jlowin) in [#309](https://github.com/PrefectHQ/fastmcp/pull/309)
+
+### Other Changes 🦾
+
+* Improve context injection type checks by [@jlowin](https://github.com/jlowin) in [#291](https://github.com/PrefectHQ/fastmcp/pull/291)
+* add readme to smarthome example by [@zzstoatzz](https://github.com/zzstoatzz) in [#294](https://github.com/PrefectHQ/fastmcp/pull/294)
+
+**Full Changelog**: [v2.2.6...v2.2.7](https://github.com/PrefectHQ/fastmcp/compare/v2.2.6...v2.2.7)
+</Update>
+
+<Update label="v2.2.6" description="2024-04-30">
+
+## [v2.2.6: The REST is History](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.6)
+
+### New Features 🎉
+
+* Added feature : Load MCP server using config by [@sandipan1](https://github.com/sandipan1) in [#260](https://github.com/PrefectHQ/fastmcp/pull/260)
+* small typing fixes by [@zzstoatzz](https://github.com/zzstoatzz) in [#237](https://github.com/PrefectHQ/fastmcp/pull/237)
+* Expose configurable timeout for OpenAPI by [@jlowin](https://github.com/jlowin) in [#279](https://github.com/PrefectHQ/fastmcp/pull/279)
+* Lower websockets pin for compatibility by [@jlowin](https://github.com/jlowin) in [#286](https://github.com/PrefectHQ/fastmcp/pull/286)
+* Improve OpenAPI param handling by [@jlowin](https://github.com/jlowin) in [#287](https://github.com/PrefectHQ/fastmcp/pull/287)
+
+### Fixes 🐞
+
+* Ensure openapi tool responses are properly converted by [@jlowin](https://github.com/jlowin) in [#283](https://github.com/PrefectHQ/fastmcp/pull/283)
+* Fix OpenAPI examples by [@jlowin](https://github.com/jlowin) in [#285](https://github.com/PrefectHQ/fastmcp/pull/285)
+* Fix client docs for advanced features, add tests for logging by [@jlowin](https://github.com/jlowin) in [#284](https://github.com/PrefectHQ/fastmcp/pull/284)
+
+### Other Changes 🦾
+
+* add testing doc by [@jlowin](https://github.com/jlowin) in [#264](https://github.com/PrefectHQ/fastmcp/pull/264)
+* #267 Fix openapi template resource to support multiple path parameters by [@jeger-at](https://github.com/jeger-at) in [#278](https://github.com/PrefectHQ/fastmcp/pull/278)
+
+### New Contributors
+
+* [@sandipan1](https://github.com/sandipan1) made their first contribution in [#260](https://github.com/PrefectHQ/fastmcp/pull/260)
+* [@jeger-at](https://github.com/jeger-at) made their first contribution in [#278](https://github.com/PrefectHQ/fastmcp/pull/278)
+
+**Full Changelog**: [v2.2.5...v2.2.6](https://github.com/PrefectHQ/fastmcp/compare/v2.2.5...v2.2.6)
+</Update>
+
+<Update label="v2.2.5" description="2024-04-26">
+
+## [v2.2.5: Context Switching](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.5)
+
+### New Features 🎉
+
+* Add tests for tool return types; improve serialization behavior by [@jlowin](https://github.com/jlowin) in [#262](https://github.com/PrefectHQ/fastmcp/pull/262)
+* Support context injection in resources, templates, and prompts (like tools) by [@jlowin](https://github.com/jlowin) in [#263](https://github.com/PrefectHQ/fastmcp/pull/263)
+
+### Docs 📚
+
+* Update wildcards to 2.2.4 by [@jlowin](https://github.com/jlowin) in [#257](https://github.com/PrefectHQ/fastmcp/pull/257)
+* Update note in templates docs by [@jlowin](https://github.com/jlowin) in [#258](https://github.com/PrefectHQ/fastmcp/pull/258)
+* Significant documentation and test expansion for tool input types by [@jlowin](https://github.com/jlowin) in [#261](https://github.com/PrefectHQ/fastmcp/pull/261)
+
+**Full Changelog**: [v2.2.4...v2.2.5](https://github.com/PrefectHQ/fastmcp/compare/v2.2.4...v2.2.5)
+</Update>
+
+<Update label="v2.2.4" description="2024-04-25">
+
+## [v2.2.4: The Wild Side, Actually](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.4)
+
+The wildcard URI templates exposed in v2.2.3 were blocked by a server-level check which is removed in this release.
+
+### New Features 🎉
+
+* Allow customization of inspector proxy port, ui port, and version by [@jlowin](https://github.com/jlowin) in [#253](https://github.com/PrefectHQ/fastmcp/pull/253)
+
+### Fixes 🐞
+
+* fix: unintended type convert by [@cutekibry](https://github.com/cutekibry) in [#252](https://github.com/PrefectHQ/fastmcp/pull/252)
+* Ensure openapi resources return valid responses by [@jlowin](https://github.com/jlowin) in [#254](https://github.com/PrefectHQ/fastmcp/pull/254)
+* Ensure servers expose template wildcards by [@jlowin](https://github.com/jlowin) in [#256](https://github.com/PrefectHQ/fastmcp/pull/256)
+
+### Docs 📚
+
+* Update README.md Grammar error by [@TechWithTy](https://github.com/TechWithTy) in [#249](https://github.com/PrefectHQ/fastmcp/pull/249)
+
+### Other Changes 🦾
+
+* Add resource template tests by [@jlowin](https://github.com/jlowin) in [#255](https://github.com/PrefectHQ/fastmcp/pull/255)
+
+### New Contributors
+
+* [@TechWithTy](https://github.com/TechWithTy) made their first contribution in [#249](https://github.com/PrefectHQ/fastmcp/pull/249)
+* [@cutekibry](https://github.com/cutekibry) made their first contribution in [#252](https://github.com/PrefectHQ/fastmcp/pull/252)
+
+**Full Changelog**: [v2.2.3...v2.2.4](https://github.com/PrefectHQ/fastmcp/compare/v2.2.3...v2.2.4)
+</Update>
+
+<Update label="v2.2.3" description="2024-04-25">
+
+## [v2.2.3: The Wild Side](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.3)
+
+### New Features 🎉
+
+* Add wildcard params for resource templates by [@jlowin](https://github.com/jlowin) in [#246](https://github.com/PrefectHQ/fastmcp/pull/246)
+
+### Docs 📚
+
+* Indicate that Image class is for returns by [@jlowin](https://github.com/jlowin) in [#242](https://github.com/PrefectHQ/fastmcp/pull/242)
+* Update mermaid diagram by [@jlowin](https://github.com/jlowin) in [#243](https://github.com/PrefectHQ/fastmcp/pull/243)
+
+### Other Changes 🦾
+
+* update version badges by [@jlowin](https://github.com/jlowin) in [#248](https://github.com/PrefectHQ/fastmcp/pull/248)
+
+**Full Changelog**: [v2.2.2...v2.2.3](https://github.com/PrefectHQ/fastmcp/compare/v2.2.2...v2.2.3)
+</Update>
+
+<Update label="v2.2.2" description="2024-04-24">
+
+## [v2.2.2: Prompt and Circumstance](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.2)
+
+### New Features 🎉
+
+* Add prompt support by [@jlowin](https://github.com/jlowin) in [#235](https://github.com/PrefectHQ/fastmcp/pull/235)
+
+### Fixes 🐞
+
+* Ensure that resource templates are properly exposed by [@jlowin](https://github.com/jlowin) in [#238](https://github.com/PrefectHQ/fastmcp/pull/238)
+
+### Docs 📚
+
+* Update docs for prompts by [@jlowin](https://github.com/jlowin) in [#236](https://github.com/PrefectHQ/fastmcp/pull/236)
+
+### Other Changes 🦾
+
+* Add prompt tests by [@jlowin](https://github.com/jlowin) in [#239](https://github.com/PrefectHQ/fastmcp/pull/239)
+
+**Full Changelog**: [v2.2.1...v2.2.2](https://github.com/PrefectHQ/fastmcp/compare/v2.2.1...v2.2.2)
+</Update>
+
+<Update label="v2.2.1" description="2024-04-23">
+
+## [v2.2.1: Template for Success](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.1)
+
+### New Features 🎉
+
+* Add resource templates by [@jlowin](https://github.com/jlowin) in [#230](https://github.com/PrefectHQ/fastmcp/pull/230)
+
+### Fixes 🐞
+
+* Ensure that resource templates are properly exposed by [@jlowin](https://github.com/jlowin) in [#231](https://github.com/PrefectHQ/fastmcp/pull/231)
+
+### Docs 📚
+
+* Update docs for resource templates by [@jlowin](https://github.com/jlowin) in [#232](https://github.com/PrefectHQ/fastmcp/pull/232)
+
+### Other Changes 🦾
+
+* Add resource template tests by [@jlowin](https://github.com/jlowin) in [#233](https://github.com/PrefectHQ/fastmcp/pull/233)
+
+**Full Changelog**: [v2.2.0...v2.2.1](https://github.com/PrefectHQ/fastmcp/compare/v2.2.0...v2.2.1)
+</Update>
+
+<Update label="v2.2.0" description="2024-04-22">
+
+## [v2.2.0: Compose Yourself](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.0)
+
+### New Features 🎉
+
+* Add support for mounting FastMCP servers by [@jlowin](https://github.com/jlowin) in [#175](https://github.com/PrefectHQ/fastmcp/pull/175)
+* Add support for duplicate behavior == ignore by [@jlowin](https://github.com/jlowin) in [#169](https://github.com/PrefectHQ/fastmcp/pull/169)
+
+### Breaking Changes 🛫
+
+* Refactor MCP composition by [@jlowin](https://github.com/jlowin) in [#176](https://github.com/PrefectHQ/fastmcp/pull/176)
+
+### Docs 📚
+
+* Improve integration documentation by [@jlowin](https://github.com/jlowin) in [#184](https://github.com/PrefectHQ/fastmcp/pull/184)
+* Improve documentation by [@jlowin](https://github.com/jlowin) in [#185](https://github.com/PrefectHQ/fastmcp/pull/185)
+
+### Other Changes 🦾
+
+* Add transport kwargs for mcp.run() and fastmcp run by [@jlowin](https://github.com/jlowin) in [#161](https://github.com/PrefectHQ/fastmcp/pull/161)
+* Allow resource templates to have optional / excluded arguments by [@jlowin](https://github.com/jlowin) in [#164](https://github.com/PrefectHQ/fastmcp/pull/164)
+* Update resources.mdx by [@jlowin](https://github.com/jlowin) in [#165](https://github.com/PrefectHQ/fastmcp/pull/165)
+
+### New Contributors
+
+* [@kongqi404](https://github.com/kongqi404) made their first contribution in [#181](https://github.com/PrefectHQ/fastmcp/pull/181)
+
+**Full Changelog**: [v2.1.2...v2.2.0](https://github.com/PrefectHQ/fastmcp/compare/v2.1.2...v2.2.0)
+</Update>
+
+<Update label="v2.1.2" description="2024-04-14">
+
+## [v2.1.2: Copy That, Good Buddy](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.1.2)
+
+The main improvement in this release is a fix that allows FastAPI / OpenAPI-generated servers to be mounted as sub-servers.
+
+### Fixes 🐞
+
+* Ensure objects are copied properly and test mounting fastapi by [@jlowin](https://github.com/jlowin) in [#153](https://github.com/PrefectHQ/fastmcp/pull/153)
+
+### Docs 📚
+
+* Fix broken links in docs by [@jlowin](https://github.com/jlowin) in [#154](https://github.com/PrefectHQ/fastmcp/pull/154)
+
+### Other Changes 🦾
+
+* Update README.md by [@jlowin](https://github.com/jlowin) in [#149](https://github.com/PrefectHQ/fastmcp/pull/149)
+* Only apply log config to FastMCP loggers by [@jlowin](https://github.com/jlowin) in [#155](https://github.com/PrefectHQ/fastmcp/pull/155)
+* Update pyproject.toml by [@jlowin](https://github.com/jlowin) in [#156](https://github.com/PrefectHQ/fastmcp/pull/156)
+
+**Full Changelog**: [v2.1.1...v2.1.2](https://github.com/PrefectHQ/fastmcp/compare/v2.1.1...v2.1.2)
+</Update>
+
+<Update label="v2.1.1" description="2024-04-14">
+
+## [v2.1.1: Doc Holiday](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.1.1)
+
+FastMCP's docs are now available at gofastmcp.com.
+
+### Docs 📚
+
+* Add docs by [@jlowin](https://github.com/jlowin) in [#136](https://github.com/PrefectHQ/fastmcp/pull/136)
+* Add docs link to readme by [@jlowin](https://github.com/jlowin) in [#137](https://github.com/PrefectHQ/fastmcp/pull/137)
+* Minor docs updates by [@jlowin](https://github.com/jlowin) in [#138](https://github.com/PrefectHQ/fastmcp/pull/138)
+
+### Fixes 🐞
+
+* fix branch name in example by [@zzstoatzz](https://github.com/zzstoatzz) in [#140](https://github.com/PrefectHQ/fastmcp/pull/140)
+
+### Other Changes 🦾
+
+* smart home example by [@zzstoatzz](https://github.com/zzstoatzz) in [#115](https://github.com/PrefectHQ/fastmcp/pull/115)
+* Remove mac os tests by [@jlowin](https://github.com/jlowin) in [#142](https://github.com/PrefectHQ/fastmcp/pull/142)
+* Expand support for various method interactions by [@jlowin](https://github.com/jlowin) in [#143](https://github.com/PrefectHQ/fastmcp/pull/143)
+* Update docs and add\_resource\_fn by [@jlowin](https://github.com/jlowin) in [#144](https://github.com/PrefectHQ/fastmcp/pull/144)
+* Update description by [@jlowin](https://github.com/jlowin) in [#145](https://github.com/PrefectHQ/fastmcp/pull/145)
+* Support openapi 3.0 and 3.1 by [@jlowin](https://github.com/jlowin) in [#147](https://github.com/PrefectHQ/fastmcp/pull/147)
+
+**Full Changelog**: [v2.1.0...v2.1.1](https://github.com/PrefectHQ/fastmcp/compare/v2.1.0...v2.1.1)
+</Update>
+
+<Update label="v2.1.0" description="2024-04-13">
+
+## [v2.1.0: Tag, You're It](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.1.0)
+
+The primary motivation for this release is the fix in #128 for Claude desktop compatibility, but the primary new feature of this release is per-object tags. Currently these are for bookkeeping only but will become useful in future releases.
+
+### New Features 🎉
+
+* Add tags for all core MCP objects by [@jlowin](https://github.com/jlowin) in [#121](https://github.com/PrefectHQ/fastmcp/pull/121)
+* Ensure that openapi tags are transferred to MCP objects by [@jlowin](https://github.com/jlowin) in [#124](https://github.com/PrefectHQ/fastmcp/pull/124)
+
+### Fixes 🐞
+
+* Change default mounted tool separator from / to \_ by [@jlowin](https://github.com/jlowin) in [#128](https://github.com/PrefectHQ/fastmcp/pull/128)
+* Enter mounted app lifespans by [@jlowin](https://github.com/jlowin) in [#129](https://github.com/PrefectHQ/fastmcp/pull/129)
+* Fix CLI that called mcp instead of fastmcp by [@jlowin](https://github.com/jlowin) in [#128](https://github.com/PrefectHQ/fastmcp/pull/128)
+
+### Breaking Changes 🛫
+
+* Changed configuration for duplicate resources/tools/prompts by [@jlowin](https://github.com/jlowin) in [#121](https://github.com/PrefectHQ/fastmcp/pull/121)
+* Improve client return types by [@jlowin](https://github.com/jlowin) in [#123](https://github.com/PrefectHQ/fastmcp/pull/123)
+
+### Other Changes 🦾
+
+* Add tests for tags in server decorators by [@jlowin](https://github.com/jlowin) in [#122](https://github.com/PrefectHQ/fastmcp/pull/122)
+* Clean up server tests by [@jlowin](https://github.com/jlowin) in [#125](https://github.com/PrefectHQ/fastmcp/pull/125)
+
+**Full Changelog**: [v2.0.0...v2.1.0](https://github.com/PrefectHQ/fastmcp/compare/v2.0.0...v2.1.0)
+</Update>
+
+<Update label="v2.0.0" description="2024-04-11">
+
+## [v2.0.0: Second to None](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.0.0)
+
+### New Features 🎉
+
+* Support mounting FastMCP instances as sub-MCPs by [@jlowin](https://github.com/jlowin) in [#99](https://github.com/PrefectHQ/fastmcp/pull/99)
+* Add in-memory client for calling FastMCP servers (and tests) by [@jlowin](https://github.com/jlowin) in [#100](https://github.com/PrefectHQ/fastmcp/pull/100)
+* Add MCP proxy server by [@jlowin](https://github.com/jlowin) in [#105](https://github.com/PrefectHQ/fastmcp/pull/105)
+* Update FastMCP for upstream changes by [@jlowin](https://github.com/jlowin) in [#107](https://github.com/PrefectHQ/fastmcp/pull/107)
+* Generate FastMCP servers from OpenAPI specs and FastAPI by [@jlowin](https://github.com/jlowin) in [#110](https://github.com/PrefectHQ/fastmcp/pull/110)
+* Reorganize all client / transports by [@jlowin](https://github.com/jlowin) in [#111](https://github.com/PrefectHQ/fastmcp/pull/111)
+* Add sampling and roots by [@jlowin](https://github.com/jlowin) in [#117](https://github.com/PrefectHQ/fastmcp/pull/117)
+
+### Fixes 🐞
+
+* Fix bug with tools that return lists by [@jlowin](https://github.com/jlowin) in [#116](https://github.com/PrefectHQ/fastmcp/pull/116)
+
+### Other Changes 🦾
+
+* Add back FastMCP CLI by [@jlowin](https://github.com/jlowin) in [#108](https://github.com/PrefectHQ/fastmcp/pull/108)
+* Update Readme for v2 by [@jlowin](https://github.com/jlowin) in [#112](https://github.com/PrefectHQ/fastmcp/pull/112)
+* fix deprecation warnings by [@zzstoatzz](https://github.com/zzstoatzz) in [#113](https://github.com/PrefectHQ/fastmcp/pull/113)
+* Readme by [@jlowin](https://github.com/jlowin) in [#118](https://github.com/PrefectHQ/fastmcp/pull/118)
+* FastMCP 2.0 by [@jlowin](https://github.com/jlowin) in [#119](https://github.com/PrefectHQ/fastmcp/pull/119)
+
+**Full Changelog**: [v1.0...v2.0.0](https://github.com/PrefectHQ/fastmcp/compare/v1.0...v2.0.0)
+</Update>
+
+<Update label="v1.0" description="2024-04-11">
+
+## [v1.0: It's Official](https://github.com/PrefectHQ/fastmcp/releases/tag/v1.0)
+
+This release commemorates FastMCP 1.0, which is included in the official Model Context Protocol SDK:
+
+```python
+from mcp.server.fastmcp import FastMCP
+```
+
+To the best of my knowledge, v1 is identical to the upstream version included with `mcp`.
+
+### Docs 📚
+
+* Update readme to redirect to the official SDK by [@jlowin](https://github.com/jlowin) in [#79](https://github.com/PrefectHQ/fastmcp/pull/79)
+
+### Other Changes 🦾
+
+* fix: use Mount instead of Route for SSE message handling by [@samihamine](https://github.com/samihamine) in [#77](https://github.com/PrefectHQ/fastmcp/pull/77)
+
+### New Contributors
+
+* [@samihamine](https://github.com/samihamine) made their first contribution in [#77](https://github.com/PrefectHQ/fastmcp/pull/77)
+
+**Full Changelog**: [v0.4.1...v1.0](https://github.com/PrefectHQ/fastmcp/compare/v0.4.1...v1.0)
+</Update>
+
+<Update label="v0.4.1" description="2024-12-09">
+
+## [v0.4.1: String Theory](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.4.1)
+
+### Fixes 🐞
+
+* fix: handle strings containing numbers correctly by [@sd2k](https://github.com/sd2k) in [#63](https://github.com/PrefectHQ/fastmcp/pull/63)
+
+### Docs 📚
+
+* patch: Update pyproject.toml license by [@leonkozlowski](https://github.com/leonkozlowski) in [#67](https://github.com/PrefectHQ/fastmcp/pull/67)
+
+### Other Changes 🦾
+
+* Avoid new try\_eval\_type unavailable with older pydantic by [@jurasofish](https://github.com/jurasofish) in [#57](https://github.com/PrefectHQ/fastmcp/pull/57)
+* Decorator typing by [@jurasofish](https://github.com/jurasofish) in [#56](https://github.com/PrefectHQ/fastmcp/pull/56)
+
+### New Contributors
+
+* [@leonkozlowski](https://github.com/leonkozlowski) made their first contribution in [#67](https://github.com/PrefectHQ/fastmcp/pull/67)
+
+**Full Changelog**: [v0.4.0...v0.4.1](https://github.com/PrefectHQ/fastmcp/compare/v0.4.0...v0.4.1)
+</Update>
+
+<Update label="v0.4.0" description="2024-12-05">
+
+## [v0.4.0: Nice to MIT You](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.4.0)
+
+This is a relatively small release in terms of features, but the version is bumped to 0.4 to reflect that the code is being relicensed from Apache 2.0 to MIT. This is to facilitate FastMCP's inclusion in the official MCP SDK.
+
+### New Features 🎉
+
+* Add pyright + tests by [@jlowin](https://github.com/jlowin) in [#52](https://github.com/PrefectHQ/fastmcp/pull/52)
+* add pgvector memory example by [@zzstoatzz](https://github.com/zzstoatzz) in [#49](https://github.com/PrefectHQ/fastmcp/pull/49)
+
+### Fixes 🐞
+
+* fix: use stderr for logging by [@sd2k](https://github.com/sd2k) in [#51](https://github.com/PrefectHQ/fastmcp/pull/51)
+
+### Docs 📚
+
+* Update ai-labeler.yml by [@jlowin](https://github.com/jlowin) in [#48](https://github.com/PrefectHQ/fastmcp/pull/48)
+* Relicense from Apache 2.0 to MIT by [@jlowin](https://github.com/jlowin) in [#54](https://github.com/PrefectHQ/fastmcp/pull/54)
+
+### Other Changes 🦾
+
+* fix warning and flake by [@zzstoatzz](https://github.com/zzstoatzz) in [#47](https://github.com/PrefectHQ/fastmcp/pull/47)
+
+### New Contributors
+
+* [@sd2k](https://github.com/sd2k) made their first contribution in [#51](https://github.com/PrefectHQ/fastmcp/pull/51)
+
+**Full Changelog**: [v0.3.5...v0.4.0](https://github.com/PrefectHQ/fastmcp/compare/v0.3.5...v0.4.0)
+</Update>
+
+<Update label="v0.3.5" description="2024-12-03">
+
+## [v0.3.5: Windows of Opportunity](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.3.5)
+
+This release is highlighted by the ability to handle complex JSON objects as MCP inputs and improved Windows compatibility.
+
+### New Features 🎉
+
+* Set up multiple os tests by [@jlowin](https://github.com/jlowin) in [#44](https://github.com/PrefectHQ/fastmcp/pull/44)
+* Changes to accommodate windows users. by [@justjoehere](https://github.com/justjoehere) in [#42](https://github.com/PrefectHQ/fastmcp/pull/42)
+* Handle complex inputs by [@jurasofish](https://github.com/jurasofish) in [#31](https://github.com/PrefectHQ/fastmcp/pull/31)
+
+### Docs 📚
+
+* Make AI labeler more conservative by [@jlowin](https://github.com/jlowin) in [#46](https://github.com/PrefectHQ/fastmcp/pull/46)
+
+### Other Changes 🦾
+
+* Additional Windows Fixes for Dev running and for importing modules in a server by [@justjoehere](https://github.com/justjoehere) in [#43](https://github.com/PrefectHQ/fastmcp/pull/43)
+
+### New Contributors
+
+* [@justjoehere](https://github.com/justjoehere) made their first contribution in [#42](https://github.com/PrefectHQ/fastmcp/pull/42)
+* [@jurasofish](https://github.com/jurasofish) made their first contribution in [#31](https://github.com/PrefectHQ/fastmcp/pull/31)
+
+**Full Changelog**: [v0.3.4...v0.3.5](https://github.com/PrefectHQ/fastmcp/compare/v0.3.4...v0.3.5)
+</Update>
+
+<Update label="v0.3.4" description="2024-12-02">
+
+## [v0.3.4: URL's Well That Ends Well](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.3.4)
+
+### Fixes 🐞
+
+* Handle missing config file when installing by [@jlowin](https://github.com/jlowin) in [#37](https://github.com/PrefectHQ/fastmcp/pull/37)
+* Remove BaseURL reference and use AnyURL by [@jlowin](https://github.com/jlowin) in [#40](https://github.com/PrefectHQ/fastmcp/pull/40)
+
+**Full Changelog**: [v0.3.3...v0.3.4](https://github.com/PrefectHQ/fastmcp/compare/v0.3.3...v0.3.4)
+</Update>
+
+<Update label="v0.3.3" description="2024-12-02">
+
+## [v0.3.3: Dependence Day](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.3.3)
+
+### New Features 🎉
+
+* Surge example by [@zzstoatzz](https://github.com/zzstoatzz) in [#29](https://github.com/PrefectHQ/fastmcp/pull/29)
+* Support Python dependencies in Server by [@jlowin](https://github.com/jlowin) in [#34](https://github.com/PrefectHQ/fastmcp/pull/34)
+
+### Docs 📚
+
+* add `Contributing` section to README by [@zzstoatzz](https://github.com/zzstoatzz) in [#32](https://github.com/PrefectHQ/fastmcp/pull/32)
+
+**Full Changelog**: [v0.3.2...v0.3.3](https://github.com/PrefectHQ/fastmcp/compare/v0.3.2...v0.3.3)
+</Update>
+
+<Update label="v0.3.2" date="2024-12-01" description="Green with ENVy">
+
+## [v0.3.2: Green with ENVy](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.3.2)
+
+### New Features 🎉
+
+* Support env vars when installing by [@jlowin](https://github.com/jlowin) in [#27](https://github.com/PrefectHQ/fastmcp/pull/27)
+
+### Docs 📚
+
+* Remove top level env var by [@jlowin](https://github.com/jlowin) in [#28](https://github.com/PrefectHQ/fastmcp/pull/28)
+
+**Full Changelog**: [v0.3.1...v0.3.2](https://github.com/PrefectHQ/fastmcp/compare/v0.3.1...v0.3.2)
+</Update>
+
+<Update label="v0.3.1" description="2024-12-01">
+
+## [v0.3.1](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.3.1)
+
+### New Features 🎉
+
+* Update README.md by [@jlowin](https://github.com/jlowin) in [#23](https://github.com/PrefectHQ/fastmcp/pull/23)
+* add rich handler and dotenv loading for settings by [@zzstoatzz](https://github.com/zzstoatzz) in [#22](https://github.com/PrefectHQ/fastmcp/pull/22)
+* print exception when server can't start by [@jlowin](https://github.com/jlowin) in [#25](https://github.com/PrefectHQ/fastmcp/pull/25)
+
+### Docs 📚
+
+* Update README.md by [@jlowin](https://github.com/jlowin) in [#24](https://github.com/PrefectHQ/fastmcp/pull/24)
+
+### Other Changes 🦾
+
+* Remove log by [@jlowin](https://github.com/jlowin) in [#26](https://github.com/PrefectHQ/fastmcp/pull/26)
+
+**Full Changelog**: [v0.3.0...v0.3.1](https://github.com/PrefectHQ/fastmcp/compare/v0.3.0...v0.3.1)
+</Update>
+
+<Update label="v0.3.0" description="2024-12-01">
+
+## [v0.3.0: Prompt and Circumstance](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.3.0)
+
+### New Features 🎉
+
+* Update README by [@jlowin](https://github.com/jlowin) in [#3](https://github.com/PrefectHQ/fastmcp/pull/3)
+* Make log levels strings by [@jlowin](https://github.com/jlowin) in [#4](https://github.com/PrefectHQ/fastmcp/pull/4)
+* Make content method a function by [@jlowin](https://github.com/jlowin) in [#5](https://github.com/PrefectHQ/fastmcp/pull/5)
+* Add template support by [@jlowin](https://github.com/jlowin) in [#6](https://github.com/PrefectHQ/fastmcp/pull/6)
+* Refactor resources module by [@jlowin](https://github.com/jlowin) in [#7](https://github.com/PrefectHQ/fastmcp/pull/7)
+* Clean up cli imports by [@jlowin](https://github.com/jlowin) in [#8](https://github.com/PrefectHQ/fastmcp/pull/8)
+* Prepare to list templates by [@jlowin](https://github.com/jlowin) in [#11](https://github.com/PrefectHQ/fastmcp/pull/11)
+* Move image to separate module by [@jlowin](https://github.com/jlowin) in [#9](https://github.com/PrefectHQ/fastmcp/pull/9)
+* Add support for request context, progress, logging, etc. by [@jlowin](https://github.com/jlowin) in [#12](https://github.com/PrefectHQ/fastmcp/pull/12)
+* Add context tests and better runtime loads by [@jlowin](https://github.com/jlowin) in [#13](https://github.com/PrefectHQ/fastmcp/pull/13)
+* Refactor tools + resourcemanager by [@jlowin](https://github.com/jlowin) in [#14](https://github.com/PrefectHQ/fastmcp/pull/14)
+* func → fn everywhere by [@jlowin](https://github.com/jlowin) in [#15](https://github.com/PrefectHQ/fastmcp/pull/15)
+* Add support for prompts by [@jlowin](https://github.com/jlowin) in [#16](https://github.com/PrefectHQ/fastmcp/pull/16)
+* Create LICENSE by [@jlowin](https://github.com/jlowin) in [#18](https://github.com/PrefectHQ/fastmcp/pull/18)
+* Update cli file spec by [@jlowin](https://github.com/jlowin) in [#19](https://github.com/PrefectHQ/fastmcp/pull/19)
+* Update readmeUpdate README by [@jlowin](https://github.com/jlowin) in [#20](https://github.com/PrefectHQ/fastmcp/pull/20)
+* Use hatchling for version by [@jlowin](https://github.com/jlowin) in [#21](https://github.com/PrefectHQ/fastmcp/pull/21)
+
+### Other Changes 🦾
+
+* Add echo server by [@jlowin](https://github.com/jlowin) in [#1](https://github.com/PrefectHQ/fastmcp/pull/1)
+* Add github workflows by [@jlowin](https://github.com/jlowin) in [#2](https://github.com/PrefectHQ/fastmcp/pull/2)
+* typing updates by [@zzstoatzz](https://github.com/zzstoatzz) in [#17](https://github.com/PrefectHQ/fastmcp/pull/17)
+
+### New Contributors
+
+* [@jlowin](https://github.com/jlowin) made their first contribution in [#1](https://github.com/PrefectHQ/fastmcp/pull/1)
+* [@zzstoatzz](https://github.com/zzstoatzz) made their first contribution in [#17](https://github.com/PrefectHQ/fastmcp/pull/17)
+
+**Full Changelog**: [v0.2.0...v0.3.0](https://github.com/PrefectHQ/fastmcp/compare/v0.2.0...v0.3.0)
+</Update>
+
+<Update label="v0.2.0" description="2024-11-30">
+
+## [v0.2.0](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.2.0)
+
+**Full Changelog**: [v0.1.0...v0.2.0](https://github.com/PrefectHQ/fastmcp/compare/v0.1.0...v0.2.0)
+</Update>
+
+<Update label="v0.1.0" description="2024-11-30">
+
+## [v0.1.0](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.1.0)
+
+The very first release of FastMCP! 🎉
+
+**Full Changelog**: [Initial commits](https://github.com/PrefectHQ/fastmcp/commits/v0.1.0)
+</Update>
diff --git a/docs/cli/auth.mdx b/docs/cli/auth.mdx
new file mode 100644
index 0000000..71b89e0
--- /dev/null
+++ b/docs/cli/auth.mdx
@@ -0,0 +1,85 @@
+---
+title: Auth Utilities
+sidebarTitle: Auth
+description: Create and validate CIMD documents for OAuth
+icon: key
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+The `fastmcp auth` commands help with CIMD (Client ID Metadata Document) management — part of MCP's OAuth authentication flow. A CIMD is a JSON document you host at an HTTPS URL to identify your client application to MCP servers.
+
+## Creating a CIMD
+
+`fastmcp auth cimd create` generates a CIMD document:
+
+```bash
+fastmcp auth cimd create \
+  --name "My App" \
+  --redirect-uri "http://localhost:*/callback"
+```
+
+```json
+{
+  "client_id": "https://your-domain.com/oauth/client.json",
+  "client_name": "My App",
+  "redirect_uris": ["http://localhost:*/callback"],
+  "token_endpoint_auth_method": "none"
+}
+```
+
+The generated document includes a placeholder `client_id` — update it to match the URL where you'll host the document before deploying.
+
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Name | `--name` | **Required.** Human-readable client name |
+| Redirect URI | `--redirect-uri` | **Required.** Allowed redirect URIs (repeatable) |
+| Client URI | `--client-uri` | Client's home page URL |
+| Logo URI | `--logo-uri` | Client's logo URL |
+| Scope | `--scope` | Space-separated list of scopes |
+| Output | `--output`, `-o` | Save to file (default: stdout) |
+| Pretty | `--pretty` | Pretty-print JSON (default: true) |
+
+### Example
+
+```bash
+fastmcp auth cimd create \
+  --name "My Production App" \
+  --redirect-uri "http://localhost:*/callback" \
+  --redirect-uri "https://myapp.example.com/callback" \
+  --client-uri "https://myapp.example.com" \
+  --scope "read write" \
+  --output client.json
+```
+
+## Validating a CIMD
+
+`fastmcp auth cimd validate` fetches a hosted CIMD and verifies it conforms to the spec:
+
+```bash
+fastmcp auth cimd validate https://myapp.example.com/oauth/client.json
+```
+
+The validator checks that the URL is valid (HTTPS, non-root path), the document is valid JSON, the `client_id` matches the URL, and no shared-secret auth methods are used.
+
+On success:
+
+```
+→ Fetching https://myapp.example.com/oauth/client.json...
+✓ Valid CIMD document
+
+Document details:
+  client_id: https://myapp.example.com/oauth/client.json
+  client_name: My App
+  token_endpoint_auth_method: none
+  redirect_uris:
+    • http://localhost:*/callback
+```
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Timeout | `--timeout`, `-t` | HTTP request timeout in seconds (default: 10) |
diff --git a/docs/cli/client.mdx b/docs/cli/client.mdx
new file mode 100644
index 0000000..b5ef1d4
--- /dev/null
+++ b/docs/cli/client.mdx
@@ -0,0 +1,144 @@
+---
+title: Client Commands
+sidebarTitle: Client
+description: List tools, call them, and discover configured servers
+icon: satellite-dish
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+The CLI can act as an MCP client — connecting to any server (local or remote) to list what it exposes and call its tools directly. This is useful for development, debugging, scripting, and giving shell-capable LLM agents access to MCP servers.
+
+## Listing Tools
+
+`fastmcp list` connects to a server and prints its tools as function signatures, showing parameter names, types, and descriptions at a glance:
+
+```bash
+fastmcp list http://localhost:8000/mcp
+fastmcp list server.py
+fastmcp list weather  # name-based resolution
+```
+
+When you need the full JSON Schema for a tool's inputs or outputs — for understanding nested objects, enum constraints, or complex types — opt in with `--input-schema` or `--output-schema`:
+
+```bash
+fastmcp list server.py --input-schema
+```
+
+### Resources and Prompts
+
+By default, only tools are shown. Add `--resources` or `--prompts` to include those:
+
+```bash
+fastmcp list server.py --resources --prompts
+```
+
+### Machine-Readable Output
+
+The `--json` flag switches to structured JSON with full schemas included. This is the format to use when feeding tool definitions to an LLM or building automation:
+
+```bash
+fastmcp list server.py --json
+```
+
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Command | `--command` | Connect via stdio (e.g., `'npx -y @mcp/server'`) |
+| Transport | `--transport`, `-t` | Force `http` or `sse` for URL targets |
+| Resources | `--resources` | Include resources in output |
+| Prompts | `--prompts` | Include prompts in output |
+| Input Schema | `--input-schema` | Show full input schemas |
+| Output Schema | `--output-schema` | Show full output schemas |
+| JSON | `--json` | Structured JSON output |
+| Timeout | `--timeout` | Connection timeout in seconds |
+| Auth | `--auth` | `oauth` (default for HTTP), a bearer token, or `none` |
+
+## Calling Tools
+
+`fastmcp call` invokes a single tool on a server. Pass arguments as `key=value` pairs — the CLI fetches the tool's schema and coerces your string values to the right types automatically:
+
+```bash
+fastmcp call server.py greet name=World
+fastmcp call http://localhost:8000/mcp search query=hello limit=5
+```
+
+Type coercion is schema-driven: `"5"` becomes the integer `5` when the schema expects an integer. Booleans accept `true`/`false`, `yes`/`no`, and `1`/`0`. Arrays and objects are parsed as JSON.
+
+### Complex Arguments
+
+For tools with nested or structured parameters, `key=value` syntax gets awkward. Pass a single JSON object instead:
+
+```bash
+fastmcp call server.py create_item '{"name": "Widget", "tags": ["sale"], "metadata": {"color": "blue"}}'
+```
+
+Or use `--input-json` to provide a base dictionary, then override individual keys with `key=value` pairs:
+
+```bash
+fastmcp call server.py search --input-json '{"query": "hello", "limit": 5}' limit=10
+```
+
+### Error Handling
+
+If you misspell a tool name, the CLI suggests corrections via fuzzy matching. Missing required arguments produce a clear message with the tool's signature as a reminder. Tool execution errors are printed with a non-zero exit code, making the CLI straightforward to use in scripts.
+
+### Structured Output
+
+`--json` emits the raw result including content blocks, error status, and structured content:
+
+```bash
+fastmcp call server.py get_weather city=London --json
+```
+
+### Interactive Elicitation
+
+Some tools request additional input during execution through MCP's elicitation mechanism. When this happens, the CLI prompts you in the terminal — showing each field's name, type, and whether it's required. You can type `decline` to skip a question or `cancel` to abort the call entirely.
+
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Command | `--command` | Connect via stdio |
+| Transport | `--transport`, `-t` | Force `http` or `sse` |
+| Input JSON | `--input-json` | Base arguments as JSON (merged with `key=value`) |
+| JSON | `--json` | Raw JSON output |
+| Timeout | `--timeout` | Connection timeout in seconds |
+| Auth | `--auth` | `oauth`, a bearer token, or `none` |
+
+## Discovering Configured Servers
+
+`fastmcp discover` scans your machine for MCP servers configured in editors and tools. It checks:
+
+- **Claude Desktop** — `claude_desktop_config.json`
+- **Claude Code** — `~/.claude.json`
+- **Cursor** — `.cursor/mcp.json` (walks up from current directory)
+- **Gemini CLI** — `~/.gemini/settings.json`
+- **Goose** — `~/.config/goose/config.yaml`
+- **Project** — `./mcp.json` in the current directory
+
+```bash
+fastmcp discover
+```
+
+The output groups servers by source, showing each server's name and transport. Filter by source or get machine-readable output:
+
+```bash
+fastmcp discover --source claude-code
+fastmcp discover --source cursor --source gemini --json
+```
+
+Any server that appears here can be used by name with `list`, `call`, and other commands — so you can go from "I have a server in Claude Code" to querying it without copying URLs or paths.
+
+## LLM Agent Integration
+
+For LLM agents that can execute shell commands but don't have native MCP support, the CLI provides a clean bridge. The agent calls `fastmcp list --json` to discover available tools with full schemas, then `fastmcp call --json` to invoke them with structured results.
+
+Because the CLI handles connection management, transport selection, and type coercion internally, the agent doesn't need to understand MCP protocol details — it just reads JSON and constructs shell commands.
+
+## Remote Stdio Bridges
+
+For MCP hosts that expect a local stdio command but need to connect to a remote HTTP server, use [`fastmcp-remote`](/clients/fastmcp-remote). It provides a small standalone bridge for host configuration, while `fastmcp list` and `fastmcp call` remain focused on direct inspection and invocation from the terminal.
diff --git a/docs/cli/generate-cli.mdx b/docs/cli/generate-cli.mdx
new file mode 100644
index 0000000..2754d19
--- /dev/null
+++ b/docs/cli/generate-cli.mdx
@@ -0,0 +1,106 @@
+---
+title: Generate CLI
+sidebarTitle: Generate CLI
+description: Scaffold a standalone typed CLI from any MCP server
+icon: wand-magic-sparkles
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+`fastmcp list` and `fastmcp call` are general-purpose — you always specify the server, the tool name, and the arguments from scratch. `fastmcp generate-cli` goes further: it connects to a server, reads its tool schemas, and writes a standalone Python script where every tool is a proper subcommand with typed flags, help text, and tab completion. The result is a CLI that feels hand-written for that specific server.
+
+MCP tool schemas already contain everything a CLI framework needs — parameter names, types, descriptions, required/optional status, and defaults. `generate-cli` maps that into [cyclopts](https://cyclopts.readthedocs.io/) commands, so JSON Schema types become Python type annotations, descriptions become `--help` text, and required parameters become mandatory flags.
+
+## Generating a Script
+
+Point the command at any [server target](/cli/overview#server-targets) and it writes a CLI script:
+
+```bash
+fastmcp generate-cli weather
+fastmcp generate-cli http://localhost:8000/mcp
+fastmcp generate-cli server.py my_weather_cli.py
+```
+
+The second positional argument sets the output path (defaults to `cli.py`). If the file already exists, pass `-f` to overwrite:
+
+```bash
+fastmcp generate-cli weather -f
+```
+
+## What You Get
+
+The generated script is a regular Python file — executable, editable, and yours:
+
+```
+$ python cli.py call-tool --help
+Usage: weather-cli call-tool COMMAND
+
+Call a tool on the server
+
+Commands:
+  get_forecast  Get the weather forecast for a city.
+  search_city   Search for a city by name.
+```
+
+Each tool has typed parameters with help text pulled directly from the server's schema:
+
+```
+$ python cli.py call-tool get_forecast --help
+Usage: weather-cli call-tool get_forecast [OPTIONS]
+
+Get the weather forecast for a city.
+
+Options:
+  --city    [str]  City name (required)
+  --days    [int]  Number of forecast days (default: 3)
+```
+
+Beyond tool commands, the script includes generic MCP operations — `list-tools`, `list-resources`, `read-resource`, `list-prompts`, and `get-prompt` — that always reflect the server's current state, even if tools have changed since generation.
+
+## Parameter Handling
+
+Parameters are mapped based on their JSON Schema type:
+
+**Simple types** (`string`, `integer`, `number`, `boolean`) become typed flags:
+
+```bash
+python cli.py call-tool get_forecast --city London --days 3
+```
+
+**Arrays of simple types** become repeatable flags:
+
+```bash
+python cli.py call-tool tag_items --tags python --tags fastapi --tags mcp
+```
+
+**Complex types** (objects, nested arrays, unions) accept JSON strings. The `--help` output shows the full schema so you know what structure to pass:
+
+```bash
+python cli.py call-tool create_user \
+  --name John \
+  --metadata '{"role": "admin", "dept": "engineering"}'
+```
+
+## Agent Skill
+
+Alongside the CLI script, `generate-cli` writes a `SKILL.md` file — a [Claude Code agent skill](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/skills) that documents every tool's exact invocation syntax, parameter flags, types, and descriptions. An agent can pick up the CLI immediately without running `--help` or experimenting with flag names.
+
+To skip skill generation:
+
+```bash
+fastmcp generate-cli weather --no-skill
+```
+
+## How It Works
+
+The generated script is a *client*, not a server — it connects to the server on every invocation rather than bundling it. A `CLIENT_SPEC` variable at the top holds the resolved transport (a URL string or `StdioTransport` with baked-in command and arguments).
+
+The most common edit is changing `CLIENT_SPEC` — for example, pointing a script generated from a dev server at production. Beyond that, the helper functions (`_call_tool`, `_print_tool_result`) are thin wrappers around `fastmcp.Client` that are easy to adapt.
+
+The script requires `fastmcp` as a dependency. If it lives outside a project that already has FastMCP installed:
+
+```bash
+uv run --with fastmcp python cli.py call-tool get_forecast --city London
+```
diff --git a/docs/cli/inspecting.mdx b/docs/cli/inspecting.mdx
new file mode 100644
index 0000000..6579213
--- /dev/null
+++ b/docs/cli/inspecting.mdx
@@ -0,0 +1,72 @@
+---
+title: Inspecting Servers
+sidebarTitle: Inspecting
+description: View a server's components and metadata
+icon: magnifying-glass
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.9.0" />
+
+`fastmcp inspect` loads a server and reports what it contains — its tools, resources, prompts, version, and metadata. The default output is a human-readable summary:
+
+```bash
+fastmcp inspect server.py
+```
+
+```
+Server: MyServer
+Instructions: A helpful MCP server
+Version: 1.0.0
+
+Components:
+  Tools: 5
+  Prompts: 2
+  Resources: 3
+  Templates: 1
+
+Environment:
+  FastMCP: 2.0.0
+  MCP: 1.0.0
+
+Use --format [fastmcp|mcp] for complete JSON output
+```
+
+## JSON Output
+
+For programmatic use, two JSON formats are available:
+
+**FastMCP format** (`--format fastmcp`) includes everything FastMCP knows about the server — tool tags, enabled status, output schemas, annotations, and custom metadata. Field names use `snake_case`. This is the format for debugging and introspecting FastMCP servers.
+
+**MCP protocol format** (`--format mcp`) shows exactly what MCP clients see through the protocol — only standard MCP fields, `camelCase` names, no FastMCP-specific extensions. This is the format for verifying client compatibility and debugging what clients actually receive.
+
+```bash
+# Full FastMCP metadata to stdout
+fastmcp inspect server.py --format fastmcp
+
+# MCP protocol view saved to file
+fastmcp inspect server.py --format mcp -o manifest.json
+```
+
+## Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Format | `--format`, `-f` | `fastmcp` or `mcp` (required when using `-o`) |
+| Output File | `--output`, `-o` | Save to file instead of stdout |
+
+## Entrypoints
+
+The `inspect` command supports the same local entrypoints as [`fastmcp run`](/cli/running): inferred instances, explicit entrypoints, factory functions, and `fastmcp.json` configs.
+
+```bash
+fastmcp inspect server.py                  # inferred instance
+fastmcp inspect server.py:my_server        # explicit entrypoint
+fastmcp inspect server.py:create_server    # factory function
+fastmcp inspect fastmcp.json               # config file
+```
+
+<Warning>
+`inspect` only works with local files and `fastmcp.json` — it doesn't connect to remote URLs or standard MCP config files.
+</Warning>
diff --git a/docs/cli/install-mcp.mdx b/docs/cli/install-mcp.mdx
new file mode 100644
index 0000000..0171b78
--- /dev/null
+++ b/docs/cli/install-mcp.mdx
@@ -0,0 +1,146 @@
+---
+title: Install MCP Servers
+sidebarTitle: Install MCPs
+description: Install MCP servers into Claude, Cursor, Gemini, and other clients
+icon: download
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.10.3" />
+
+`fastmcp install` registers a server with an MCP client application so the client can launch it automatically. Each MCP client runs servers in its own isolated environment, which means dependencies need to be explicitly declared — you can't rely on whatever happens to be installed locally.
+
+```bash
+fastmcp install claude-desktop server.py
+fastmcp install claude-code server.py --with pandas --with matplotlib
+fastmcp install cursor server.py -e .
+```
+
+<Warning>
+`uv` must be installed and available in your system PATH. Both Claude Desktop and Cursor run servers in isolated environments managed by `uv`. On macOS, install it globally with Homebrew for Claude Desktop compatibility: `brew install uv`.
+</Warning>
+
+## Supported Clients
+
+| Client | Install method |
+| ------ | -------------- |
+| `claude-code` | Claude Code's built-in MCP management |
+| `claude-desktop` | Direct config file modification |
+| `cursor` | Deeplink that opens Cursor for confirmation |
+| `gemini-cli` | Gemini CLI's built-in MCP management |
+| `goose` | Deeplink that opens Goose for confirmation (uses `uvx`) |
+| `mcp-json` | Generates standard MCP JSON config for manual use |
+| `stdio` | Outputs the shell command to run via stdio |
+
+## Declaring Dependencies
+
+Because MCP clients run servers in isolation, you need to tell the install command what your server needs. There are two approaches:
+
+**Command-line flags** let you specify dependencies directly:
+
+```bash
+fastmcp install claude-desktop server.py --with pandas --with "sqlalchemy>=2.0"
+fastmcp install cursor server.py -e . --with-requirements requirements.txt
+```
+
+**`fastmcp.json`** configuration files declare dependencies alongside the server definition. When you install from a config file, dependencies are picked up automatically:
+
+```bash
+fastmcp install claude-desktop fastmcp.json
+fastmcp install claude-desktop  # auto-detects fastmcp.json in current directory
+```
+
+See [Server Configuration](/deployment/server-configuration) for the full config format.
+
+## Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Server Name | `--server-name`, `-n` | Custom name for the server |
+| Editable Package | `--with-editable`, `-e` | Install a directory in editable mode |
+| Extra Packages | `--with` | Additional packages (repeatable) |
+| Environment Variables | `--env` | `KEY=VALUE` pairs (repeatable) |
+| Environment File | `--env-file`, `-f` | Load env vars from a `.env` file |
+| Python | `--python` | Python version (e.g., `3.11`) |
+| Project | `--project` | Run within a uv project directory |
+| Requirements | `--with-requirements` | Install from a requirements file |
+| Config Path | `--config-path` | Custom path to Claude Desktop config directory (`claude-desktop` only) |
+
+## Examples
+
+```bash
+# Basic install with auto-detected server instance
+fastmcp install claude-desktop server.py
+
+# Install from fastmcp.json with auto-detection
+fastmcp install claude-desktop
+
+# Explicit entrypoint with dependencies
+fastmcp install claude-desktop server.py:my_server \
+  --server-name "My Analysis Server" \
+  --with pandas
+
+# With environment variables
+fastmcp install claude-code server.py \
+  --env API_KEY=secret \
+  --env DEBUG=true
+
+# With env file
+fastmcp install cursor server.py --env-file .env
+
+# Specific Python version and requirements file
+fastmcp install claude-desktop server.py \
+  --python 3.11 \
+  --with-requirements requirements.txt
+
+# With custom config path (claude-desktop only)
+fastmcp install claude-desktop server.py \
+  --config-path "C:\Users\username\AppData\Local\Packages\Claude_xyz\LocalCache\Roaming\Claude"
+```
+
+## Generating MCP JSON
+
+The `mcp-json` target generates standard MCP configuration JSON instead of installing into a specific client. This is useful for clients that FastMCP doesn't directly support, for CI/CD environments, or for sharing server configs:
+
+```bash
+fastmcp install mcp-json server.py
+```
+
+The output follows the standard format used by Claude Desktop, Cursor, and other MCP clients:
+
+```json
+{
+  "server-name": {
+    "command": "uv",
+    "args": ["run", "--with", "fastmcp", "fastmcp", "run", "/path/to/server.py"],
+    "env": {
+      "API_KEY": "value"
+    }
+  }
+}
+```
+
+Use `--copy` to send it to your clipboard instead of stdout.
+
+## Generating Stdio Commands
+
+The `stdio` target outputs the shell command an MCP host would use to start your server over stdio:
+
+```bash
+fastmcp install stdio server.py
+# Output: uv run --with fastmcp fastmcp run /absolute/path/to/server.py
+```
+
+When installing from a `fastmcp.json`, dependencies from the config are included automatically:
+
+```bash
+fastmcp install stdio fastmcp.json
+# Output: uv run --with fastmcp --with pillow --with 'qrcode[pil]>=8.0' fastmcp run /path/to/server.py
+```
+
+Use `--copy` to copy to clipboard.
+
+<Tip>
+`fastmcp install` is designed for local server files with stdio transport. For remote servers running over HTTP, use your client's native configuration — FastMCP's value here is simplifying the complex local setup with `uv`, dependencies, and environment variables.
+</Tip>
diff --git a/docs/cli/overview.mdx b/docs/cli/overview.mdx
new file mode 100644
index 0000000..54783be
--- /dev/null
+++ b/docs/cli/overview.mdx
@@ -0,0 +1,104 @@
+---
+title: CLI
+sidebarTitle: Overview
+description: The fastmcp command-line interface
+icon: terminal
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+The `fastmcp` CLI is installed automatically with FastMCP. It's the primary way to run, test, install, and interact with MCP servers from your terminal.
+
+```bash
+fastmcp --help
+```
+
+## Commands at a Glance
+
+| Command | What it does |
+| ------- | ------------ |
+| [`run`](/cli/running) | Run a server (local file, factory function, remote URL, or config file) |
+| [`dev apps`](/cli/running#previewing-apps) | Launch a browser-based preview UI for Prefab App tools |
+| [`dev inspector`](/cli/running#development-with-the-inspector) | Launch a server inside the MCP Inspector for interactive testing |
+| [`install`](/cli/install-mcp) | Install a server into Claude Code, Claude Desktop, Cursor, Gemini CLI, or Goose |
+| [`inspect`](/cli/inspecting) | Print a server's tools, resources, and prompts as a summary or JSON report |
+| [`list`](/cli/client) | List a server's tools (and optionally resources and prompts) |
+| [`call`](/cli/client#calling-tools) | Call a single tool with arguments |
+| [`discover`](/cli/client#discovering-configured-servers) | Find MCP servers configured in your editors and tools |
+| [`generate-cli`](/cli/generate-cli) | Scaffold a standalone typed CLI from a server's tool schemas |
+| [`project prepare`](/cli/running#pre-building-environments) | Pre-install dependencies into a reusable uv project |
+| [`auth cimd`](/cli/auth) | Create and validate CIMD documents for OAuth |
+| `version` | Print version info (`--copy` to copy to clipboard) |
+
+## Server Targets
+
+Most commands need to know *which server* to talk to. You pass a "server spec" as the first argument, and FastMCP resolves the right transport automatically.
+
+**URLs** connect to a running HTTP server:
+
+```bash
+fastmcp list http://localhost:8000/mcp
+fastmcp call http://localhost:8000/mcp get_forecast city=London
+```
+
+**Python files** are loaded directly — no `mcp.run()` boilerplate needed. FastMCP finds a server instance named `mcp`, `server`, or `app` in the file, or you can specify one explicitly:
+
+```bash
+fastmcp list server.py
+fastmcp run server.py:my_custom_server
+```
+
+**Config files** work too — both FastMCP's own `fastmcp.json` format and standard MCP config files with an `mcpServers` key:
+
+```bash
+fastmcp run fastmcp.json
+fastmcp list mcp-config.json
+```
+
+**Stdio commands** connect to any MCP server that speaks over standard I/O. Use `--command` instead of a positional argument:
+
+```bash
+fastmcp list --command 'npx -y @modelcontextprotocol/server-github'
+```
+
+### Name-Based Resolution
+
+If your servers are already configured in an editor or tool, you can refer to them by name. FastMCP scans configs from Claude Desktop, Claude Code, Cursor, Gemini CLI, and Goose:
+
+```bash
+fastmcp list weather
+fastmcp call weather get_forecast city=London
+```
+
+When the same name appears in multiple configs, use the `source:name` form to be specific:
+
+```bash
+fastmcp list claude-code:my-server
+fastmcp call cursor:weather get_forecast city=London
+```
+
+Run [`fastmcp discover`](/cli/client#discovering-configured-servers) to see what's available on your machine.
+
+## Authentication
+
+When targeting an HTTP URL, the CLI enables OAuth authentication by default. If the server requires it, you'll be guided through the flow (typically opening a browser). If it doesn't, the setup is a silent no-op.
+
+To skip authentication entirely — useful for local development servers — pass `--auth none`:
+
+```bash
+fastmcp call http://localhost:8000/mcp my_tool --auth none
+```
+
+You can also pass a bearer token directly:
+
+```bash
+fastmcp list http://localhost:8000/mcp --auth "Bearer sk-..."
+```
+
+## Transport Override
+
+FastMCP defaults to Streamable HTTP for URL targets. If the server only supports Server-Sent Events (SSE), force the older transport:
+
+```bash
+fastmcp list http://localhost:8000 --transport sse
+```
diff --git a/docs/cli/running.mdx b/docs/cli/running.mdx
new file mode 100644
index 0000000..b0cad0a
--- /dev/null
+++ b/docs/cli/running.mdx
@@ -0,0 +1,166 @@
+---
+title: Running Servers
+sidebarTitle: Running
+description: Start, develop, and configure servers from the command line
+icon: play
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+## Starting a Server
+
+`fastmcp run` starts a server. Point it at a Python file, a factory function, a remote URL, or a config file:
+
+```bash
+fastmcp run server.py
+fastmcp run server.py:create_server
+fastmcp run https://example.com/mcp
+fastmcp run fastmcp.json
+```
+
+By default, the server runs over **stdio** — the transport that MCP clients like Claude Desktop expect. To serve over HTTP instead, specify the transport:
+
+```bash
+fastmcp run server.py --transport http
+fastmcp run server.py --transport http --host 0.0.0.0 --port 9000
+```
+
+### Entrypoints
+
+FastMCP supports several ways to locate and start your server:
+
+**Inferred instance** — FastMCP imports the file and looks for a variable named `mcp`, `server`, or `app`:
+
+```bash
+fastmcp run server.py
+```
+
+**Explicit instance** — point at a specific variable:
+
+```bash
+fastmcp run server.py:my_server
+```
+
+**Factory function** — FastMCP calls the function and uses the returned server. Useful when your server needs async setup or configuration that runs before startup:
+
+```bash
+fastmcp run server.py:create_server
+```
+
+**Remote URL** — starts a local proxy that bridges to a remote server. Handy for local development against a deployed server, or for bridging a remote HTTP server to stdio:
+
+```bash
+fastmcp run https://example.com/mcp
+```
+
+**FastMCP config** — uses a `fastmcp.json` file that declaratively specifies the server, its dependencies, and deployment settings. When you run `fastmcp run` with no arguments, it auto-detects `fastmcp.json` in the current directory:
+
+```bash
+fastmcp run
+fastmcp run my-config.fastmcp.json
+```
+
+See [Server Configuration](/deployment/server-configuration) for the full `fastmcp.json` format.
+
+**MCP config** — runs servers defined in a standard MCP configuration file (any `.json` with an `mcpServers` key):
+
+```bash
+fastmcp run mcp.json
+```
+
+<Warning>
+`fastmcp run` completely ignores the `if __name__ == "__main__"` block. Any setup code in that block won't execute. If you need initialization logic to run, use a [factory function](/cli/overview#factory-functions).
+</Warning>
+
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Transport | `--transport`, `-t` | `stdio` (default), `http`, or `sse` |
+| Host | `--host` | Bind address for HTTP (default: `127.0.0.1`) |
+| Port | `--port`, `-p` | Bind port for HTTP (default: `8000`) |
+| Path | `--path` | URL path for HTTP (default: `/mcp/`) |
+| Log Level | `--log-level`, `-l` | `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
+| No Banner | `--no-banner` | Suppress the startup banner |
+| Auto-Reload | `--reload` / `--no-reload` | Watch for file changes and restart automatically |
+| Reload Dirs | `--reload-dir` | Directories to watch (repeatable) |
+| Skip Env | `--skip-env` | Don't set up a uv environment (use when already in one) |
+| Python | `--python` | Python version to use (e.g., `3.11`) |
+| Extra Packages | `--with` | Additional packages to install (repeatable) |
+| Project | `--project` | Run within a specific uv project directory |
+| Requirements | `--with-requirements` | Install from a requirements file |
+
+### Dependency Management
+
+By default, `fastmcp run` uses your current Python environment directly. When you pass `--python`, `--with`, `--project`, or `--with-requirements`, it switches to running via `uv run` in a subprocess, which handles dependency isolation automatically.
+
+The `--skip-env` flag is useful when you're already inside an activated venv, a Docker container with pre-installed dependencies, or a uv-managed project — it prevents uv from trying to set up another environment layer.
+
+## Previewing Apps
+
+<VersionBadge version="3.2.0" />
+
+`fastmcp dev apps` launches a browser-based preview UI for servers with [Prefab App tools](/apps/prefab). It starts your MCP server on one port and a local dev UI on another — giving you a live, interactive picker where you can call app tools and see their rendered output without needing a full MCP host client.
+
+```bash
+fastmcp dev apps server.py
+fastmcp dev apps server.py:mcp --mcp-port 9000 --dev-port 9090
+```
+
+The picker auto-generates a form from each tool's input schema. Submit the form and the result opens in a new tab as a rendered Prefab UI.
+
+Auto-reload is on by default — save a file and the MCP server restarts automatically.
+
+<Tip>
+`fastmcp dev apps` requires `fastmcp[apps]` — install with `pip install "fastmcp[apps]"`.
+</Tip>
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| MCP Port | `--mcp-port` | Port for the MCP server (default: `8000`) |
+| Dev Port | `--dev-port` | Port for the dev UI (default: `8080`) |
+| Auto-Reload | `--reload` / `--no-reload` | Watch for file changes (default: on) |
+
+## Development with the Inspector
+
+`fastmcp dev inspector` launches your server inside the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), a browser-based tool for interactively testing MCP servers. Auto-reload is on by default, so your server restarts when you save changes.
+
+```bash
+fastmcp dev inspector server.py
+fastmcp dev inspector server.py -e . --with pandas
+```
+
+<Tip>
+The Inspector always runs your server via `uv run` in a subprocess — it never uses your local environment directly. Specify dependencies with `--with`, `--with-editable`, `--with-requirements`, or through a `fastmcp.json` file.
+</Tip>
+
+<Warning>
+The Inspector connects over **stdio only**. When it launches, you may need to select "STDIO" from the transport dropdown and click connect. To test a server over HTTP, start it separately with `fastmcp run server.py --transport http` and point the Inspector at the URL.
+</Warning>
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Editable Package | `--with-editable`, `-e` | Install a directory in editable mode |
+| Extra Packages | `--with` | Additional packages (repeatable) |
+| Inspector Version | `--inspector-version` | MCP Inspector version to use |
+| UI Port | `--ui-port` | Port for the Inspector UI |
+| Server Port | `--server-port` | Port for the Inspector proxy |
+| Auto-Reload | `--reload` / `--no-reload` | File watching (default: on) |
+| Reload Dirs | `--reload-dir` | Directories to watch (repeatable) |
+| Python | `--python` | Python version |
+| Project | `--project` | Run within a uv project directory |
+| Requirements | `--with-requirements` | Install from a requirements file |
+
+## Pre-Building Environments
+
+`fastmcp project prepare` creates a persistent uv project from a `fastmcp.json` file, pre-installing all dependencies. This separates environment setup from server execution — install once, run many times.
+
+```bash
+# Step 1: Build the environment (slow, does dependency resolution)
+fastmcp project prepare fastmcp.json --output-dir ./env
+
+# Step 2: Run using the prepared environment (fast, no install step)
+fastmcp run fastmcp.json --project ./env
+```
+
+The prepared directory contains a `pyproject.toml`, a `.venv` with all packages installed, and a `uv.lock` for reproducibility. This is particularly useful in deployment scenarios where you want deterministic, pre-built environments.
diff --git a/docs/clients/auth/bearer.mdx b/docs/clients/auth/bearer.mdx
new file mode 100644
index 0000000..2e12fbc
--- /dev/null
+++ b/docs/clients/auth/bearer.mdx
@@ -0,0 +1,88 @@
+---
+title: Bearer Token Authentication
+sidebarTitle: Bearer Auth
+description: Authenticate your FastMCP client with a Bearer token.
+icon: key
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.6.0" />
+
+<Tip>
+Bearer Token authentication is only relevant for HTTP-based transports.
+</Tip>
+
+You can configure your FastMCP client to use **bearer authentication** by supplying a valid access token. This is most appropriate for service accounts, long-lived API keys, CI/CD, applications where authentication is managed separately, or other non-interactive authentication methods.
+
+A Bearer token is a JSON Web Token (JWT) that is used to authenticate a request. It is most commonly used in the `Authorization` header of an HTTP request, using the `Bearer` scheme:
+
+```http
+Authorization: Bearer <token>
+```
+
+
+## Client Usage
+
+The most straightforward way to use a pre-existing Bearer token is to provide it as a string to the `auth` parameter of the `fastmcp.Client` or transport instance. FastMCP will automatically format it correctly for the `Authorization` header and bearer scheme.
+
+<Tip>
+If you're using a string token, do not include the `Bearer` prefix. FastMCP will add it for you.
+</Tip>
+
+```python {5}
+from fastmcp import Client
+
+async with Client(
+    "https://your-server.fastmcp.app/mcp", 
+    auth="<your-token>",
+) as client:
+    await client.ping()
+```
+
+You can also supply a Bearer token to a transport instance, such as `StreamableHttpTransport` or `SSETransport`:
+
+```python {6}
+from fastmcp import Client
+from fastmcp.client.transports import StreamableHttpTransport
+
+transport = StreamableHttpTransport(
+    "http://your-server.fastmcp.app/mcp", 
+    auth="<your-token>",
+)
+
+async with Client(transport) as client:
+    await client.ping()
+```
+
+## `BearerAuth` Helper
+
+If you prefer to be more explicit and not rely on FastMCP to transform your string token, you can use the `BearerAuth` class yourself, which implements the `httpx.Auth` interface.
+
+```python {6}
+from fastmcp import Client
+from fastmcp.client.auth import BearerAuth
+
+async with Client(
+    "https://your-server.fastmcp.app/mcp", 
+    auth=BearerAuth(token="<your-token>"),
+) as client:
+    await client.ping()
+```
+
+## Custom Headers
+
+If the MCP server expects a custom header or token scheme, you can manually set the client's `headers` instead of using the `auth` parameter by setting them on your transport:
+
+```python {5}
+from fastmcp import Client
+from fastmcp.client.transports import StreamableHttpTransport
+
+async with Client(
+    transport=StreamableHttpTransport(
+        "https://your-server.fastmcp.app/mcp", 
+        headers={"X-API-Key": "<your-token>"},
+    ),
+) as client:
+    await client.ping()
+```
diff --git a/docs/clients/auth/cimd.mdx b/docs/clients/auth/cimd.mdx
new file mode 100644
index 0000000..c1f92d1
--- /dev/null
+++ b/docs/clients/auth/cimd.mdx
@@ -0,0 +1,138 @@
+---
+title: CIMD Authentication
+sidebarTitle: CIMD
+description: Use Client ID Metadata Documents for verifiable, domain-based client identity.
+icon: id-badge
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="3.0.0" />
+
+<Tip>
+CIMD authentication is only relevant for HTTP-based transports and requires a server that advertises CIMD support.
+</Tip>
+
+With standard OAuth, your client registers dynamically with every server it connects to, receiving a fresh `client_id` each time. This works, but the server has no way to verify *who* your client actually is — any client can claim any name during registration.
+
+CIMD (Client ID Metadata Documents) flips this around. You host a small JSON document at an HTTPS URL you control, and that URL becomes your `client_id`. When your client connects to a server, the server fetches your metadata document and can verify your identity through your domain ownership. Users see a verified domain badge in the consent screen instead of an unverified client name.
+
+## Client Usage
+
+Pass your CIMD document URL to the `client_metadata_url` parameter of `OAuth`:
+
+```python
+from fastmcp import Client
+from fastmcp.client.auth import OAuth
+
+async with Client(
+    "https://mcp-server.example.com/mcp",
+    auth=OAuth(
+        client_metadata_url="https://myapp.example.com/oauth/client.json",
+    ),
+) as client:
+    await client.ping()
+```
+
+When the server supports CIMD, the client uses your metadata URL as its `client_id` instead of performing Dynamic Client Registration. The server fetches your document, validates it, and proceeds with the standard OAuth authorization flow.
+
+<Note>
+You don't need to pass `mcp_url` when using `OAuth` with `Client(auth=...)` — the transport provides the server URL automatically.
+</Note>
+
+## Creating a CIMD Document
+
+A CIMD document is a JSON file that describes your client. The most important field is `client_id`, which must exactly match the URL where you host the document.
+
+Use the FastMCP CLI to generate one:
+
+```bash
+fastmcp auth cimd create \
+    --name "My Application" \
+    --redirect-uri "http://localhost:*/callback" \
+    --client-id "https://myapp.example.com/oauth/client.json"
+```
+
+This produces:
+
+```json
+{
+  "client_id": "https://myapp.example.com/oauth/client.json",
+  "client_name": "My Application",
+  "redirect_uris": ["http://localhost:*/callback"],
+  "token_endpoint_auth_method": "none",
+  "grant_types": ["authorization_code"],
+  "response_types": ["code"]
+}
+```
+
+If you omit `--client-id`, the CLI generates a placeholder value and reminds you to update it before hosting.
+
+### CLI Options
+
+The `create` command accepts these flags:
+
+| Flag | Description |
+|------|-------------|
+| `--name` | Human-readable client name (required) |
+| `--redirect-uri`, `-r` | Allowed redirect URIs — can be specified multiple times (required) |
+| `--client-id` | The URL where you'll host this document (sets `client_id` directly) |
+| `--output`, `-o` | Write to a file instead of stdout |
+| `--scope` | Space-separated list of scopes the client may request |
+| `--client-uri` | URL of the client's home page |
+| `--logo-uri` | URL of the client's logo image |
+| `--no-pretty` | Output compact JSON |
+
+### Redirect URIs
+
+The `redirect_uris` field supports wildcard port matching for localhost. The pattern `http://localhost:*/callback` matches any port, which is useful for development clients that bind to random available ports (which is what FastMCP's `OAuth` helper does by default).
+
+## Hosting Requirements
+
+CIMD documents must be hosted at a publicly accessible HTTPS URL with a non-root path:
+
+- **HTTPS required** — HTTP URLs are rejected for security
+- **Non-root path** — The URL must have a path component (e.g., `/oauth/client.json`, not just `/`)
+- **Public accessibility** — The server must be able to fetch the document over the internet
+- **Matching `client_id`** — The `client_id` field in the document must exactly match the hosting URL
+
+Common hosting options include static file hosting services like GitHub Pages, Cloudflare Pages, Vercel, or S3 — anywhere you can serve a JSON file over HTTPS.
+
+## Validating Your Document
+
+Before deploying, verify your hosted document passes validation:
+
+```bash
+fastmcp auth cimd validate https://myapp.example.com/oauth/client.json
+```
+
+The validator fetches the document and checks that:
+- The URL is valid (HTTPS, non-root path)
+- The document is well-formed JSON conforming to the CIMD schema
+- The `client_id` in the document matches the URL it was fetched from
+
+## How It Works
+
+When your client connects to a CIMD-enabled server, the flow works like this:
+
+<Steps>
+<Step title="Client Presents Metadata URL">
+Your client sends its `client_metadata_url` as the `client_id` in the OAuth authorization request.
+</Step>
+<Step title="Server Recognizes CIMD URL">
+The server sees that the `client_id` is an HTTPS URL with a path — the signature of a CIMD client — and skips Dynamic Client Registration.
+</Step>
+<Step title="Server Fetches and Validates">
+The server fetches your JSON document from the URL, validates that `client_id` matches the URL, and extracts your client metadata (name, redirect URIs, scopes).
+</Step>
+<Step title="Authorization Proceeds">
+The standard OAuth flow continues: browser opens for user consent, authorization code exchange, token issuance. The consent screen shows your verified domain.
+</Step>
+</Steps>
+
+The server caches your CIMD document according to HTTP cache headers, so subsequent requests don't require re-fetching.
+
+## Server Configuration
+
+CIMD is a server-side feature that your MCP server must support. FastMCP's OAuth proxy providers (GitHub, Google, Auth0, etc.) support CIMD by default. See the [OAuth Proxy CIMD documentation](/servers/auth/oauth-proxy#cimd-support) for server-side configuration, including private key JWT authentication and security details.
diff --git a/docs/clients/auth/oauth.mdx b/docs/clients/auth/oauth.mdx
new file mode 100644
index 0000000..84fbe21
--- /dev/null
+++ b/docs/clients/auth/oauth.mdx
@@ -0,0 +1,186 @@
+---
+title: OAuth Authentication
+sidebarTitle: OAuth
+description: Authenticate your FastMCP client via OAuth 2.1.
+icon: window
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.6.0" />
+
+<Tip>
+OAuth authentication is only relevant for HTTP-based transports and requires user interaction via a web browser.
+</Tip>
+
+When your FastMCP client needs to access an MCP server protected by OAuth 2.1, and the process requires user interaction (like logging in and granting consent), you should use the Authorization Code Flow. FastMCP provides the `fastmcp.client.auth.OAuth` helper to simplify this entire process.
+
+This flow is common for user-facing applications where the application acts on behalf of the user.
+
+## Client Usage
+
+
+### Default Configuration
+
+The simplest way to use OAuth is to pass the string `"oauth"` to the `auth` parameter of the `Client` or transport instance. FastMCP will automatically configure the client to use OAuth with default settings:
+
+```python {4}
+from fastmcp import Client
+
+# Uses default OAuth settings
+async with Client("https://your-server.fastmcp.app/mcp", auth="oauth") as client:
+    await client.ping()
+```
+
+
+### `OAuth` Helper
+
+To fully configure the OAuth flow, use the `OAuth` helper and pass it to the `auth` parameter of the `Client` or transport instance. `OAuth` manages the complexities of the OAuth 2.1 Authorization Code Grant with PKCE (Proof Key for Code Exchange) for enhanced security, and implements the full `httpx.Auth` interface.
+
+```python {2, 4, 6}
+from fastmcp import Client
+from fastmcp.client.auth import OAuth
+
+oauth = OAuth(scopes=["user"])
+
+async with Client("https://your-server.fastmcp.app/mcp", auth=oauth) as client:
+    await client.ping()
+```
+
+<Note>
+You don't need to pass `mcp_url` when using `OAuth` with `Client(auth=...)` — the transport provides the server URL automatically.
+</Note>
+
+#### `OAuth` Parameters
+
+- **`scopes`** (`str | list[str]`, optional): OAuth scopes to request. Can be space-separated string or list of strings
+- **`client_name`** (`str`, optional): Client name for dynamic registration. Defaults to `"FastMCP Client"`
+- **`client_id`** (`str`, optional): Pre-registered OAuth client ID. When provided, skips Dynamic Client Registration entirely. See [Pre-Registered Clients](#pre-registered-clients)
+- **`client_secret`** (`str`, optional): OAuth client secret for pre-registered clients. Optional — public clients that rely on PKCE can omit this
+- **`client_metadata_url`** (`str`, optional): URL-based client identity (CIMD). See [CIMD Authentication](/clients/auth/cimd) for details
+- **`token_storage`** (`AsyncKeyValue`, optional): Storage backend for persisting OAuth tokens. Defaults to in-memory storage (tokens lost on restart). See [Token Storage](#token-storage) for encrypted storage options
+- **`additional_client_metadata`** (`dict[str, Any]`, optional): Extra metadata for client registration
+- **`callback_port`** (`int`, optional): Fixed port for OAuth callback server. If not specified, uses a random available port
+- **`httpx_client_factory`** (`McpHttpClientFactory`, optional): Factory for creating httpx clients
+
+
+## OAuth Flow
+
+The OAuth flow is triggered when you use a FastMCP `Client` configured to use OAuth.
+
+<Steps>
+<Step title="Token Check">
+The client first checks the configured `token_storage` backend for existing, valid tokens for the target server. If one is found, it will be used to authenticate the client.
+</Step>
+<Step title="OAuth Server Discovery">
+If no valid tokens exist, the client attempts to discover the OAuth server's endpoints using a well-known URI (e.g., `/.well-known/oauth-authorization-server`) based on the `mcp_url`.
+</Step>
+<Step title="Client Registration">
+If a `client_id` is provided, the client uses those pre-registered credentials directly and skips this step entirely. Otherwise, if a `client_metadata_url` is configured and the server supports CIMD, the client uses its metadata URL as its identity. As a fallback, the client performs Dynamic Client Registration (RFC 7591) if the server supports it.
+</Step>
+<Step title="Local Callback Server">
+A temporary local HTTP server is started on an available port (or the port specified via `callback_port`). This server's address (e.g., `http://127.0.0.1:<port>/callback`) acts as the `redirect_uri` for the OAuth flow.
+</Step>
+<Step title="Browser Interaction">
+The user's default web browser is automatically opened, directing them to the OAuth server's authorization endpoint. The user logs in and grants (or denies) the requested `scopes`.
+</Step>
+<Step title="Authorization Code & Token Exchange">
+Upon approval, the OAuth server redirects the user's browser to the local callback server with an `authorization_code`. The client captures this code and exchanges it with the OAuth server's token endpoint for an `access_token` (and often a `refresh_token`) using PKCE for security.
+</Step>
+<Step title="Token Caching">
+The obtained tokens are saved to the configured `token_storage` backend for future use, eliminating the need for repeated browser interactions.
+</Step>
+<Step title="Authenticated Requests">
+The access token is automatically included in the `Authorization` header for requests to the MCP server.
+</Step>
+<Step title="Refresh Token">
+If the access token expires, the client will automatically use the refresh token to get a new access token.
+</Step>
+</Steps>
+
+## Token Storage
+
+<VersionBadge version="2.13.0" />
+
+By default, tokens are stored in memory and lost when your application restarts. For persistent storage, pass an `AsyncKeyValue`-compatible storage backend to the `token_storage` parameter.
+
+<Warning>
+**Security Consideration**: Use encrypted storage for production. MCP clients can accumulate OAuth credentials for many servers over time, and a compromised token store could expose access to multiple services.
+</Warning>
+
+```python
+from fastmcp import Client
+from fastmcp.client.auth import OAuth
+from key_value.aio.stores.disk import DiskStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+import os
+
+# Create encrypted disk storage
+encrypted_storage = FernetEncryptionWrapper(
+    key_value=DiskStore(directory="~/.fastmcp/oauth-tokens"),
+    fernet=Fernet(os.environ["OAUTH_STORAGE_ENCRYPTION_KEY"])
+)
+
+oauth = OAuth(token_storage=encrypted_storage)
+
+async with Client("https://your-server.fastmcp.app/mcp", auth=oauth) as client:
+    await client.ping()
+```
+
+You can use any `AsyncKeyValue`-compatible backend from the [key-value library](https://github.com/strawgate/py-key-value) including Redis, DynamoDB, and more. Wrap your storage in `FernetEncryptionWrapper` for encryption.
+
+<Note>
+When selecting a storage backend, review the [py-key-value documentation](https://github.com/strawgate/py-key-value) to understand the maturity level and limitations of your chosen backend. Some backends may be in preview or have constraints that affect production suitability.
+</Note>
+
+## CIMD Authentication
+
+<VersionBadge version="3.0.0" />
+
+Client ID Metadata Documents (CIMD) provide an alternative to Dynamic Client Registration. Instead of registering with each server, your client hosts a static JSON document at an HTTPS URL. That URL becomes your client's identity, and servers can verify who you are through your domain ownership.
+
+```python
+from fastmcp import Client
+from fastmcp.client.auth import OAuth
+
+async with Client(
+    "https://mcp-server.example.com/mcp",
+    auth=OAuth(
+        client_metadata_url="https://myapp.example.com/oauth/client.json",
+    ),
+) as client:
+    await client.ping()
+```
+
+See the [CIMD Authentication](/clients/auth/cimd) page for complete documentation on creating, hosting, and validating CIMD documents.
+
+## Pre-Registered Clients
+
+<VersionBadge version="3.0.0" />
+
+Some OAuth servers don't support Dynamic Client Registration — the MCP spec explicitly makes DCR optional. If your client has been pre-registered with the server (you already have a `client_id` and optionally a `client_secret`), you can provide them directly to skip DCR entirely.
+
+```python
+from fastmcp import Client
+from fastmcp.client.auth import OAuth
+
+async with Client(
+    "https://mcp-server.example.com/mcp",
+    auth=OAuth(
+        client_id="my-registered-client-id",
+        client_secret="my-client-secret",
+    ),
+) as client:
+    await client.ping()
+```
+
+Public clients that rely on PKCE for security can omit `client_secret`:
+
+```python
+oauth = OAuth(client_id="my-public-client-id")
+```
+
+<Note>
+When using pre-registered credentials, the client will not attempt Dynamic Client Registration. If the server rejects the credentials, the error is surfaced immediately rather than falling back to DCR.
+</Note>
diff --git a/docs/clients/cli.mdx b/docs/clients/cli.mdx
new file mode 100644
index 0000000..801c763
--- /dev/null
+++ b/docs/clients/cli.mdx
@@ -0,0 +1,161 @@
+---
+title: Client CLI
+sidebarTitle: CLI
+description: Query and invoke MCP server tools directly from the terminal with fastmcp list and fastmcp call.
+icon: terminal
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+MCP servers are designed for programmatic consumption by AI assistants and applications. But during development, you often want to poke at a server directly: check what tools it exposes, call one with test arguments, or verify that a deployment is responding correctly. The FastMCP CLI gives you that direct access with two commands, `fastmcp list` and `fastmcp call`, so you can query and invoke any MCP server without writing a single line of Python.
+
+These commands are also valuable for LLM-based agents that lack native MCP support. An agent that can execute shell commands can use `fastmcp list --json` to discover available tools and `fastmcp call --json` to invoke them, with structured JSON output designed for programmatic consumption.
+
+## Server Targets
+
+Both commands need to know which server to talk to. You provide a "server spec" as the first argument, and FastMCP figures out the transport automatically. You can point at an HTTP URL for a running server, a Python file that defines one, a JSON configuration file that describes one, or a JavaScript file. The CLI resolves the right connection mechanism so you can focus on the query.
+
+```bash
+fastmcp list http://localhost:8000/mcp
+fastmcp list server.py
+fastmcp list mcp-config.json
+```
+
+Python files are handled with particular care. Rather than requiring your script to call `mcp.run()` at the bottom, the CLI routes it through `fastmcp run` internally, which means any Python file that defines a FastMCP server object works as a target with no boilerplate.
+
+For servers that communicate over stdio (common with Node.js-based MCP servers), use the `--command` flag instead of a positional server spec. The string is shell-split into a command and arguments.
+
+```bash
+fastmcp list --command 'npx -y @modelcontextprotocol/server-github'
+```
+
+### Name-Based Resolution
+
+If your MCP servers are already configured in an editor or tool, you can refer to them by name instead of spelling out URLs or file paths. The CLI scans config files from Claude Desktop, Claude Code, Cursor, Gemini CLI, and Goose, and matches the name you provide.
+
+```bash
+fastmcp list weather
+fastmcp call weather get_forecast city=London
+```
+
+You can also use the `source:name` form to target a specific source directly, which is useful when the same server name appears in multiple configs or when you want to be explicit about which config you mean.
+
+```bash
+fastmcp list claude-code:my-server
+fastmcp call cursor:weather get_forecast city=London
+```
+
+The available source names are `claude-desktop`, `claude-code`, `cursor`, `gemini`, `goose`, and `project` (for `./mcp.json`). Run `fastmcp discover` to see what's available.
+
+## Discovering Configured Servers
+
+`fastmcp discover` scans your local editor and project configurations for MCP server definitions. It checks Claude Desktop, Claude Code (`~/.claude.json`), Cursor workspace configs (walking up from the current directory), Gemini CLI (`~/.gemini/settings.json`), Goose (`~/.config/goose/config.yaml`), and `mcp.json` in the current directory.
+
+```bash
+fastmcp discover
+```
+
+The output groups servers by source, showing each server's name and transport. Use `--source` to filter to specific sources, and `--json` for machine-readable output.
+
+```bash
+fastmcp discover --source claude-code
+fastmcp discover --source cursor --source gemini --json
+```
+
+Any server that appears here can be used by name (or `source:name`) with `fastmcp list` and `fastmcp call`, which means you can go from "I have a server configured in Claude Code" to querying it without copying any URLs or paths.
+
+## Discovering Tools
+
+`fastmcp list` connects to a server and prints every tool it exposes. The default output is compact: each tool appears as a function signature with its parameter names, types, and a description.
+
+```bash
+fastmcp list http://localhost:8000/mcp
+```
+
+The output looks like a Python function signature, making it easy to see at a glance what a tool expects and what it returns. Required parameters appear with just their type annotation, while optional ones show their defaults.
+
+When you need the full JSON Schema for a tool's inputs or outputs -- useful for understanding nested object structures or enum constraints -- opt into them with `--input-schema` or `--output-schema`. These print the raw schema beneath each tool signature.
+
+### Beyond Tools
+
+MCP servers can expose resources and prompts alongside tools. By default, `fastmcp list` only shows tools because they are the most common interaction point. Add `--resources` or `--prompts` to include those in the output.
+
+```bash
+fastmcp list server.py --resources --prompts
+```
+
+Resources appear with their URIs and descriptions. Prompts appear with their argument names so you can see what parameters they accept.
+
+### Machine-Readable Output
+
+The `--json` flag switches from human-friendly text to structured JSON. Each tool includes its name, description, and full input schema (and output schema when present). When combined with `--resources` or `--prompts`, those are included as additional top-level keys.
+
+```bash
+fastmcp list server.py --json
+```
+
+This is the format to use when building automation around MCP servers or feeding tool definitions to an LLM agent that needs to decide which tool to call.
+
+## Calling Tools
+
+`fastmcp call` invokes a single tool on a server. You provide the server spec, the tool name, and arguments as `key=value` pairs. The CLI fetches the tool's schema, coerces your string values to the correct types (integers, floats, booleans, arrays, objects), and makes the call.
+
+```bash
+fastmcp call http://localhost:8000/mcp search query=hello limit=5
+```
+
+Type coercion is driven by the tool's JSON Schema. If a parameter is declared as an integer, the string `"5"` becomes the integer `5`. Booleans accept `true`/`false`, `yes`/`no`, and `1`/`0`. Array and object parameters are parsed as JSON.
+
+For tools with complex or deeply nested arguments, the `key=value` syntax gets unwieldy. You can pass a single JSON object as the argument instead, and the CLI treats it as the full input dictionary.
+
+```bash
+fastmcp call server.py create_item '{"name": "Widget", "tags": ["sale", "new"], "metadata": {"color": "blue"}}'
+```
+
+Alternatively, `--input-json` provides the base argument dictionary. Any `key=value` pairs you add alongside it override keys from the JSON, which is useful for templating a complex call and varying one parameter at a time.
+
+### Error Handling
+
+The CLI validates your call before sending it. If you misspell a tool name, it uses fuzzy matching to suggest corrections. If you omit a required argument, it tells you which ones are missing and prints the tool's signature as a reminder.
+
+When a tool call itself returns an error (the server executed the tool but it failed), the error message is printed and the CLI exits with a non-zero status code, making it straightforward to use in scripts.
+
+### Structured Output
+
+Like `fastmcp list`, the `--json` flag on `fastmcp call` emits structured JSON instead of formatted text. The output includes the content blocks, error status, and structured content when the server provides it. Use this when you need to parse tool results programmatically.
+
+```bash
+fastmcp call server.py get_weather city=London --json
+```
+
+## Authentication
+
+When the server target is an HTTP URL, the CLI automatically enables OAuth authentication. If the server requires it, you will be guided through the OAuth flow (typically opening a browser for authorization). If the server has no auth requirements, the OAuth setup is a silent no-op.
+
+To explicitly disable authentication -- for example, when connecting to a local development server where OAuth setup would just slow you down -- pass `--auth none`.
+
+```bash
+fastmcp call http://localhost:8000/mcp my_tool --auth none
+```
+
+## Transport Override
+
+FastMCP defaults to Streamable HTTP for URL targets. If you are connecting to a server that only supports Server-Sent Events (SSE), use `--transport sse` to force the older transport. This appends `/sse` to the URL path automatically so the client picks the correct protocol.
+
+```bash
+fastmcp list http://localhost:8000 --transport sse
+```
+
+## Interactive Elicitation
+
+Some MCP tools request additional input from the user during execution through a mechanism called elicitation. When a tool sends an elicitation request, the CLI prints the server's question to the terminal and prompts you to respond. Each field in the elicitation schema is presented with its name and expected type, and required fields are clearly marked.
+
+You can type `decline` to skip a question or `cancel` to abort the tool call entirely. This interactive behavior means the CLI works naturally with tools that have multi-step or conversational workflows.
+
+## LLM Agent Integration
+
+For LLM agents that can execute shell commands but lack built-in MCP support, the CLI provides a clean integration path. The agent calls `fastmcp list --json` to get a structured description of every available tool, including full input schemas, and then calls `fastmcp call --json` with the chosen tool and arguments. Both commands return well-formed JSON that is straightforward to parse.
+
+Because the CLI handles connection management, transport selection, and type coercion internally, the agent does not need to understand MCP protocol details. It just needs to read JSON and construct shell commands.
diff --git a/docs/clients/client-only-package.mdx b/docs/clients/client-only-package.mdx
new file mode 100644
index 0000000..020b2f0
--- /dev/null
+++ b/docs/clients/client-only-package.mdx
@@ -0,0 +1,89 @@
+---
+title: Client-Only Package
+description: Use FastMCP's client without installing the full server framework.
+icon: box
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.3.0" />
+
+FastMCP's full `fastmcp` package includes everything needed to build and run MCP servers, apps, proxies, and clients. If you are only embedding an MCP client in another framework, building your own LLM host, or testing MCP servers, you can install the smaller client-only package instead.
+
+```bash
+pip install "fastmcp-slim[client]"
+```
+
+The client-only package uses the `fastmcp` import namespace:
+
+```python
+from fastmcp import Client
+
+client = Client("https://example.com/mcp")
+```
+
+Use `fastmcp-slim[client]` when your code connects to MCP servers but does not define or run FastMCP servers itself. For example, framework authors can depend on `fastmcp-slim[client]` to provide MCP connectivity without requiring users to install the full FastMCP server stack.
+
+## Supported Usage
+
+Client-only installs support remote and subprocess transports:
+
+```python
+from fastmcp import Client
+
+# Remote MCP server
+http_client = Client("https://example.com/mcp")
+
+# Local MCP server over stdio
+stdio_client = Client("my_server.py")
+```
+
+Single-server MCP configuration works as well:
+
+```python
+from fastmcp import Client
+
+config = {
+    "mcpServers": {
+        "weather": {
+            "url": "https://weather.example.com/mcp"
+        }
+    }
+}
+
+client = Client(config)
+```
+
+Optional sampling handlers are available through the same extras as the full package:
+
+```bash
+pip install "fastmcp-slim[client,openai]"
+pip install "fastmcp-slim[client,anthropic]"
+pip install "fastmcp-slim[client,gemini]"
+```
+
+## When to Use the Full Package
+
+Install `fastmcp` when you need server-side FastMCP features:
+
+```bash
+pip install fastmcp
+```
+
+The full package remains the default for most users and continues to support the existing import style:
+
+```python
+from fastmcp import Client, FastMCP
+
+server = FastMCP("Example")
+client = Client(server)
+```
+
+Use the full package for:
+
+- defining or running FastMCP servers
+- in-memory clients connected directly to `FastMCP` server objects
+- multi-server MCP configurations
+- FastMCP apps, proxies, server auth, middleware, and other server-side features
+
+The `fastmcp-slim` package is intentionally narrower: it is for client-only consumers who want FastMCP's MCP client behavior without depending on the full framework.
diff --git a/docs/clients/client.mdx b/docs/clients/client.mdx
new file mode 100644
index 0000000..30e09e6
--- /dev/null
+++ b/docs/clients/client.mdx
@@ -0,0 +1,311 @@
+---
+title: The FastMCP Client
+sidebarTitle: Overview
+description: Programmatic client for interacting with MCP servers through a well-typed, Pythonic interface.
+icon: user-robot
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.0.0" />
+
+The `fastmcp.Client` class provides a programmatic interface for interacting with any MCP server. It handles protocol details and connection management automatically, letting you focus on the operations you want to perform.
+
+The FastMCP Client is designed for deterministic, controlled interactions rather than autonomous behavior, making it ideal for testing MCP servers during development, building deterministic applications that need reliable MCP interactions, and creating the foundation for agentic or LLM-based clients with structured, type-safe operations.
+
+<Note>
+This is a programmatic client that requires explicit function calls and provides direct control over all MCP operations. Use it as a building block for higher-level systems.
+</Note>
+
+## Creating a Client
+
+You provide a server source and the client automatically infers the appropriate transport mechanism.
+
+```python
+import asyncio
+from fastmcp import Client, FastMCP
+
+# In-memory server (ideal for testing)
+server = FastMCP("TestServer")
+client = Client(server)
+
+# HTTP server
+client = Client("https://example.com/mcp")
+
+# Local Python script
+client = Client("my_mcp_server.py")
+
+async def main():
+    async with client:
+        # Basic server interaction
+        await client.ping()
+
+        # List available operations
+        tools = await client.list_tools()
+        resources = await client.list_resources()
+        prompts = await client.list_prompts()
+
+        # Execute operations
+        result = await client.call_tool("example_tool", {"param": "value"})
+        print(result)
+
+asyncio.run(main())
+```
+
+All client operations require using the `async with` context manager for proper connection lifecycle management.
+
+## Choosing a Transport
+
+The client automatically selects a transport based on what you pass to it, but different transports have different characteristics that matter for your use case.
+
+**In-memory transport** connects directly to a FastMCP server instance within the same Python process. Use this for testing and development where you want to eliminate subprocess and network complexity. The server shares your process's environment and memory space.
+
+```python
+from fastmcp import Client, FastMCP
+
+server = FastMCP("TestServer")
+client = Client(server)  # In-memory, no network or subprocess
+```
+
+**STDIO transport** launches a server as a subprocess and communicates through stdin/stdout pipes. This is the standard mechanism used by desktop clients like Claude Desktop. The subprocess runs in an isolated environment, so you must explicitly pass any environment variables the server needs.
+
+```python
+from fastmcp import Client
+
+# Simple inference from file path
+client = Client("my_server.py")
+
+# With explicit environment configuration
+client = Client("my_server.py", env={"API_KEY": "secret"})
+```
+
+**HTTP transport** connects to servers running as web services. Use this for production deployments where the server runs independently and manages its own lifecycle.
+
+```python
+from fastmcp import Client
+
+client = Client("https://api.example.com/mcp")
+```
+
+See [Transports](/clients/transports) for detailed configuration options including authentication headers, session persistence, and multi-server configurations.
+
+## Configuration-Based Clients
+
+<VersionBadge version="2.4.0" />
+
+Create clients from MCP configuration dictionaries, which can include multiple servers. While there is no official standard for MCP configuration format, FastMCP follows established conventions used by tools like Claude Desktop.
+
+```python
+config = {
+    "mcpServers": {
+        "weather": {
+            "url": "https://weather-api.example.com/mcp"
+        },
+        "assistant": {
+            "command": "python",
+            "args": ["./assistant_server.py"]
+        }
+    }
+}
+
+client = Client(config)
+
+async with client:
+    # Tools are prefixed with server names
+    weather_data = await client.call_tool("weather_get_forecast", {"city": "London"})
+    response = await client.call_tool("assistant_answer_question", {"question": "What's the capital of France?"})
+
+    # Resources use prefixed URIs
+    icons = await client.read_resource("weather://weather/icons/sunny")
+```
+
+## Connection Lifecycle
+
+The client uses context managers for connection management. When you enter the context, the client establishes a connection and performs an MCP initialization handshake with the server. This handshake exchanges capabilities, server metadata, and instructions.
+
+```python
+from fastmcp import Client, FastMCP
+
+mcp = FastMCP(name="MyServer", instructions="Use the greet tool to say hello!")
+
+@mcp.tool
+def greet(name: str) -> str:
+    """Greet a user by name."""
+    return f"Hello, {name}!"
+
+async with Client(mcp) as client:
+    # Initialization already happened automatically
+    print(f"Server: {client.initialize_result.server_info.name}")
+    print(f"Instructions: {client.initialize_result.instructions}")
+    print(f"Capabilities: {client.initialize_result.capabilities.tools}")
+```
+
+For advanced scenarios where you need precise control over when initialization happens, disable automatic initialization and call `initialize()` manually:
+
+```python
+from fastmcp import Client
+
+client = Client("my_mcp_server.py", auto_initialize=False)
+
+async with client:
+    # Connection established, but not initialized yet
+    print(f"Connected: {client.is_connected()}")
+    print(f"Initialized: {client.initialize_result is not None}")  # False
+
+    # Initialize manually with custom timeout
+    result = await client.initialize(timeout=10.0)
+    print(f"Server: {result.server_info.name}")
+
+    # Now ready for operations
+    tools = await client.list_tools()
+```
+
+## Protocol negotiation
+
+<VersionBadge version="4.0.0" />
+
+MCP has two protocol eras: the original *legacy* era, which begins every connection with an `initialize` handshake, and the *modern* era (protocol version `2026-07-28` and later), which a client discovers by probing the server's `server/discover` endpoint. The `mode` parameter controls which era the client negotiates when it connects.
+
+By default, `mode="legacy"`. This runs the initialize handshake and behaves identically to earlier FastMCP versions, so existing code connecting to any server keeps working unchanged.
+
+```python
+from fastmcp import Client
+
+# Legacy handshake (the default)
+client = Client("https://example.com/mcp", mode="legacy")
+```
+
+Set `mode="auto"` to negotiate the newest era the server supports. The client probes `server/discover` and adopts the modern protocol when the server responds; for any server that is not positive evidence of modern support, it falls back to the legacy handshake. This makes `"auto"` safe to use against a mixed fleet of legacy and modern servers.
+
+```python
+client = Client("https://example.com/mcp", mode="auto")
+```
+
+You can also pin a specific modern protocol version to adopt it directly, without a discovery probe:
+
+```python
+client = Client("https://example.com/mcp", mode="2026-07-28")
+```
+
+Once connected, the negotiated version and the server's advertised capabilities are available as properties. Both are populated regardless of which era was negotiated, and both are `None` while the client is disconnected.
+
+```python
+async with Client("https://example.com/mcp", mode="auto") as client:
+    print(client.protocol_version)      # e.g. "2026-07-28"
+    print(client.server_capabilities)   # ServerCapabilities | None
+```
+
+<Note>
+`mode="auto"` is not the default yet — the conservative `"legacy"` remains the default to preserve byte-identical behavior against pre-2026 servers. Whether `"auto"` becomes the default is a future release decision.
+</Note>
+
+## Response caching
+
+<VersionBadge version="4.0.0" />
+
+The client can cache the results of `list_tools`, `list_resources`, `list_prompts`, and `read_resource` so that repeated calls avoid a network round-trip. Caching is opt-in and honors the server's own cache hints, so it only takes effect against modern-era servers that advertise them — a cache is inert on a legacy connection.
+
+Enable the default in-memory cache by passing `cache=True`. It respects the `ttlMs` and `cacheScope` hints the server attaches to each response.
+
+```python
+from fastmcp import Client
+
+client = Client("https://example.com/mcp", mode="auto", cache=True)
+
+async with client:
+    tools = await client.list_tools()   # fetched from the server
+    tools = await client.list_tools()   # served from the cache
+```
+
+The default (`cache=None`) and `cache=False` both disable caching. For control over the store, TTL, or partitioning, pass a `CacheConfig`. A custom config requires a `target_id`, since in-memory FastMCP transports expose no server URL to derive a shared-store identity from.
+
+```python
+from fastmcp import Client
+from mcp.client.caching import CacheConfig
+
+config = CacheConfig(target_id="weather-api", default_ttl_ms=60_000)
+client = Client("https://example.com/mcp", mode="auto", cache=config)
+```
+
+The high-level `list_tools`, `list_resources`, `list_prompts`, and `read_resource` methods always use the cache when one is configured. To override the behavior for a single call, use the lower-level `*_mcp` variants, which accept a `cache_mode` argument: `"use"` (the default) serves and stores, `"refresh"` stores a fresh result without serving a cached one, and `"bypass"` skips the cache entirely.
+
+```python
+async with client:
+    fresh = await client.list_tools_mcp(cache_mode="refresh")
+```
+
+## Operations
+
+FastMCP clients interact with three types of server components.
+
+**Tools** are server-side functions that the client can execute with arguments. Call them with `call_tool()` and receive structured results.
+
+```python
+async with client:
+    tools = await client.list_tools()
+    result = await client.call_tool("multiply", {"a": 5, "b": 3})
+    print(result.data)  # 15
+```
+
+See [Tools](/clients/tools) for detailed documentation including version selection, error handling, and structured output.
+
+**Resources** are data sources that the client can read, either static or templated. Access them with `read_resource()` using URIs.
+
+```python
+async with client:
+    resources = await client.list_resources()
+    content = await client.read_resource("file:///config/settings.json")
+    print(content[0].text)
+```
+
+See [Resources](/clients/resources) for detailed documentation including templates and binary content.
+
+**Prompts** are reusable message templates that can accept arguments. Retrieve rendered prompts with `get_prompt()`.
+
+```python
+async with client:
+    prompts = await client.list_prompts()
+    messages = await client.get_prompt("analyze_data", {"data": [1, 2, 3]})
+    print(messages.messages)
+```
+
+See [Prompts](/clients/prompts) for detailed documentation including argument serialization.
+
+## Callback Handlers
+
+The client supports callback handlers for advanced server interactions. These let you respond to server-initiated requests and receive notifications.
+
+```python
+from fastmcp import Client
+from fastmcp.client.logging import LogMessage
+
+async def log_handler(message: LogMessage):
+    print(f"Server log: {message.data}")
+
+async def progress_handler(progress: float, total: float | None, message: str | None):
+    print(f"Progress: {progress}/{total} - {message}")
+
+async def sampling_handler(messages, params, context):
+    # Integrate with your LLM service here
+    return "Generated response"
+
+client = Client(
+    "my_mcp_server.py",
+    log_handler=log_handler,
+    progress_handler=progress_handler,
+    sampling_handler=sampling_handler,
+    timeout=30.0
+)
+```
+
+Each handler type has its own documentation:
+
+- **[Sampling](/clients/sampling)** - Respond to server LLM requests
+- **[Elicitation](/clients/elicitation)** - Handle server requests for user input
+- **[Progress](/clients/progress)** - Monitor long-running operations
+- **[Logging](/clients/logging)** - Handle server log messages
+- **[Roots](/clients/roots)** - Provide local context to servers
+
+<Tip>
+The FastMCP Client is designed as a foundational tool. Use it directly for deterministic operations, or build higher-level agentic systems on top of its reliable, type-safe interface.
+</Tip>
diff --git a/docs/clients/elicitation.mdx b/docs/clients/elicitation.mdx
new file mode 100644
index 0000000..840e426
--- /dev/null
+++ b/docs/clients/elicitation.mdx
@@ -0,0 +1,155 @@
+---
+title: User Elicitation
+sidebarTitle: Elicitation
+description: Handle server requests for structured user input.
+icon: message-question
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+<VersionBadge version="2.10.0" />
+
+Use this when you need to respond to server requests for user input during tool execution.
+
+Elicitation allows MCP servers to request structured input from users during operations. Instead of requiring all inputs upfront, servers can interactively ask for missing parameters, request clarification, or gather additional context.
+
+## Handler Template
+
+```python
+from fastmcp import Client
+from fastmcp.client.elicitation import ElicitResult, ElicitRequestParams, RequestContext
+
+async def elicitation_handler(
+    message: str,
+    response_type: type | None,
+    params: ElicitRequestParams,
+    context: RequestContext
+) -> ElicitResult | object:
+    """
+    Handle server requests for user input.
+
+    Args:
+        message: The prompt to display to the user
+        response_type: Python dataclass type for the response (None if no data expected)
+        params: Original MCP elicitation parameters including raw JSON schema
+        context: Request context with metadata
+
+    Returns:
+        - Data directly (implicitly accepts the elicitation)
+        - ElicitResult for explicit control over the action
+    """
+    # Present the message and collect input
+    user_input = input(f"{message}: ")
+
+    if not user_input:
+        return ElicitResult(action="decline")
+
+    # Create response using the provided dataclass type
+    return response_type(value=user_input)
+
+client = Client(
+    "my_mcp_server.py",
+    elicitation_handler=elicitation_handler,
+)
+```
+
+## How It Works
+
+When a server needs user input, it sends an elicitation request with a message prompt and a JSON schema describing the expected response structure. FastMCP automatically converts this schema into a Python dataclass type, making it easy to construct properly typed responses without manually parsing JSON schemas.
+
+The handler receives four parameters:
+
+<Card icon="code" title="Handler Parameters">
+<ResponseField name="message" type="str">
+  The prompt message to display to the user
+</ResponseField>
+
+<ResponseField name="response_type" type="type | None">
+  A Python dataclass type that FastMCP created from the server's JSON schema. Use this to construct your response with proper typing. If the server requests an empty object, this will be `None`.
+</ResponseField>
+
+<ResponseField name="params" type="ElicitRequestParams">
+  The original MCP elicitation parameters, including the raw JSON schema in `params.requested_schema`
+</ResponseField>
+
+<ResponseField name="context" type="RequestContext">
+  Request context containing metadata about the elicitation request
+</ResponseField>
+</Card>
+
+## Response Actions
+
+You can return data directly, which implicitly accepts the elicitation:
+
+```python
+async def elicitation_handler(message, response_type, params, context):
+    user_input = input(f"{message}: ")
+    return response_type(value=user_input)  # Implicit accept
+```
+
+Or return an `ElicitResult` for explicit control over the action:
+
+```python
+from fastmcp.client.elicitation import ElicitResult
+
+async def elicitation_handler(message, response_type, params, context):
+    user_input = input(f"{message}: ")
+
+    if not user_input:
+        return ElicitResult(action="decline")  # User declined
+
+    if user_input == "cancel":
+        return ElicitResult(action="cancel")   # Cancel entire operation
+
+    return ElicitResult(
+        action="accept",
+        content=response_type(value=user_input)
+    )
+```
+
+**Action types:**
+- **`accept`**: User provided valid input. Include the data in the `content` field.
+- **`decline`**: User chose not to provide the requested information. Omit `content`.
+- **`cancel`**: User cancelled the entire operation. Omit `content`.
+
+## Example
+
+A file management tool might ask which directory to create:
+
+```python
+from fastmcp import Client
+from fastmcp.client.elicitation import ElicitResult
+
+async def elicitation_handler(message, response_type, params, context):
+    print(f"Server asks: {message}")
+
+    user_response = input("Your response: ")
+
+    if not user_response:
+        return ElicitResult(action="decline")
+
+    # Use the response_type dataclass to create a properly structured response
+    return response_type(value=user_response)
+
+client = Client(
+    "my_mcp_server.py",
+    elicitation_handler=elicitation_handler
+)
+```
+
+## Input-required rounds
+
+<VersionBadge version="4.0.0" />
+
+Modern-era servers (protocol version `2026-07-28` and later) can pause a `call_tool`, `get_prompt`, or `read_resource` call to ask for input before producing a final result. When this happens, the client answers each round automatically using the callbacks you already configured — your `elicitation_handler`, `sampling_handler`, and roots — and retries until the call reaches a terminal result. No extra wiring is needed beyond the handlers described above.
+
+The `input_required_max_rounds` parameter caps how many rounds the client will answer before giving up, guarding against a server that never terminates. It defaults to `10`.
+
+```python
+client = Client(
+    "https://example.com/mcp",
+    mode="auto",
+    elicitation_handler=elicitation_handler,
+    input_required_max_rounds=5,
+)
+```
diff --git a/docs/clients/fastmcp-remote.mdx b/docs/clients/fastmcp-remote.mdx
new file mode 100644
index 0000000..ee218af
--- /dev/null
+++ b/docs/clients/fastmcp-remote.mdx
@@ -0,0 +1,169 @@
+---
+title: fastmcp-remote
+description: Bridge remote MCP servers into stdio-only MCP hosts with uvx fastmcp-remote.
+icon: bridge
+---
+
+`fastmcp-remote` is FastMCP's standalone stdio bridge for remote MCP servers. Use it when an MCP host expects to launch a local command, but the server you want to use is hosted over Streamable HTTP or SSE.
+
+```json
+{
+  "mcpServers": {
+    "linear": {
+      "command": "uvx",
+      "args": ["fastmcp-remote", "https://mcp.linear.app/mcp"]
+    }
+  }
+}
+```
+
+The package is powered by FastMCP. It builds one FastMCP client for the remote URL, exposes that client as a local stdio proxy, and keeps the executable focused on that bridge. For running Python server files, local project environments, FastMCP config files, and development reload loops, use [`fastmcp run`](/cli/running).
+
+The command shape follows the original [`mcp-remote`](https://github.com/geelen/mcp-remote) npm project, which established this stdio-to-remote bridge pattern for MCP hosts.
+
+## Installation
+
+Most MCP hosts can run `fastmcp-remote` directly through `uvx`, so you usually do not need to install it yourself:
+
+```bash
+uvx fastmcp-remote https://example.com/mcp
+```
+
+If your host requires an already-installed command, install the package with your Python package manager:
+
+```bash
+uv tool install fastmcp-remote
+```
+
+## Host Configuration
+
+For hosts that use `mcpServers` JSON configuration, set the command to `uvx` and pass `fastmcp-remote` plus the remote server URL as arguments:
+
+```json
+{
+  "mcpServers": {
+    "remote-api": {
+      "command": "uvx",
+      "args": ["fastmcp-remote", "https://example.com/mcp"]
+    }
+  }
+}
+```
+
+## Endpoint URLs and Connection Status
+
+Pass the full MCP endpoint URL for the remote server. Many FastMCP HTTP servers expose MCP at `/mcp`, so a local development server may need `http://localhost:8000/mcp` rather than `http://localhost:8000`.
+
+`fastmcp-remote` starts a local stdio bridge, then connects to the upstream server when the MCP host initializes that bridge. If the upstream server is unavailable, the URL does not point to an MCP endpoint, or authentication cannot complete, initialization fails and the host should report the remote server as failed. After initialization succeeds, later tool, resource, prompt, and ping requests continue to proxy through the same remote server configuration.
+
+OAuth is enabled automatically for HTTPS servers. The first connection opens the browser-based OAuth flow when the server requires authentication, then stores tokens locally for future runs.
+
+To pass a bearer token or another custom header directly, provide `--header` in `Name: Value` form. The header name ends at the first colon, so values can contain additional colons. Quote the header when the value contains spaces, just like any other shell argument. An `Authorization` header disables OAuth by default:
+
+```json
+{
+  "mcpServers": {
+    "private-api": {
+      "command": "uvx",
+      "args": [
+        "fastmcp-remote",
+        "https://example.com/mcp",
+        "--header",
+        "Authorization: Bearer <token>"
+      ]
+    }
+  }
+}
+```
+
+Repeat `--header` to send multiple headers:
+
+```bash
+uvx fastmcp-remote https://example.com/mcp \
+  --header "Authorization: Bearer <token>" \
+  --header "X-Workspace: production" \
+  --header "X-Client-Name: My MCP Host" \
+  --header "X-Callback-Url: https://example.com/oauth/callback"
+```
+
+Some MCP hosts on Windows have trouble preserving spaces inside command arguments. Put the spaced value in an environment variable and reference it from the header value:
+
+```json
+{
+  "mcpServers": {
+    "remote-api": {
+      "command": "uvx",
+      "args": [
+        "fastmcp-remote",
+        "https://example.com/mcp",
+        "--header",
+        "Authorization:${AUTH_HEADER}"
+      ],
+      "env": {
+        "AUTH_HEADER": "Bearer <token>"
+      }
+    }
+  }
+}
+```
+
+For local development servers over plain HTTP, disable OAuth when the server is unauthenticated:
+
+```bash
+uvx fastmcp-remote http://localhost:8000/mcp --auth none
+```
+
+## Self-Signed Certificates
+
+For servers behind a self-signed certificate, point `--verify` at a CA bundle that trusts the certificate:
+
+```bash
+uvx fastmcp-remote https://internal.example.com/mcp --verify /path/to/ca-bundle.pem
+```
+
+To disable certificate verification entirely, pass `--verify false`. This is insecure and should only be used for trusted servers on private networks:
+
+```bash
+uvx fastmcp-remote https://internal.example.com/mcp --verify false
+```
+
+To trust a CA bundle without a flag, set the standard `SSL_CERT_FILE` environment variable, which OpenSSL reads automatically:
+
+```bash
+SSL_CERT_FILE=/path/to/ca-bundle.pem uvx fastmcp-remote https://internal.example.com/mcp
+```
+
+## OAuth Storage
+
+OAuth tokens are stored under `~/.fastmcp/remote` by default. Set `FASTMCP_REMOTE_CONFIG_DIR` to use another directory:
+
+```bash
+FASTMCP_REMOTE_CONFIG_DIR=~/.config/fastmcp-remote uvx fastmcp-remote https://example.com/mcp
+```
+
+Use `--resource` to isolate tokens for a particular remote server identity:
+
+```bash
+uvx fastmcp-remote https://example.com/mcp --resource example-prod
+```
+
+If the remote authorization server requires a fixed callback port or hostname, pass them after the URL:
+
+```bash
+uvx fastmcp-remote https://example.com/mcp 3334 --host 127.0.0.1
+```
+
+## Options
+
+| Option | Description |
+| ------ | ----------- |
+| `--transport` | Choose `http` or `sse`. Defaults to `http`. |
+| `--header` | Add a header to upstream requests, for example `--header "Authorization: Bearer <token>"`. Values may contain colons. Quote headers whose values contain spaces. Use `${VAR}` to expand environment variables inside values. Repeat for multiple headers. |
+| `--auth` | Choose `oauth` or `none`. The default uses OAuth unless an `Authorization` header is provided. |
+| `--verify` | Control TLS certificate verification. Pass a path to a CA bundle to trust a self-signed certificate, or `false` to disable verification (insecure). Defaults to verification enabled. |
+| `--resource` | Isolate OAuth token storage for a named remote resource. |
+| `--host` | Set the OAuth callback hostname. Defaults to `localhost`. |
+| `--auth-timeout` | Set how long to wait for the OAuth callback. Defaults to 300 seconds. |
+| `--ignore-tool` | Hide tools whose names match a glob pattern. Repeat for multiple patterns. |
+| `--debug` | Enable debug logging. |
+| `--silent` | Suppress non-critical logs. |
diff --git a/docs/clients/generate-cli.mdx b/docs/clients/generate-cli.mdx
new file mode 100644
index 0000000..b0faaef
--- /dev/null
+++ b/docs/clients/generate-cli.mdx
@@ -0,0 +1,166 @@
+---
+title: Generate CLI
+sidebarTitle: Generate CLI
+description: Turn any MCP server into a standalone, typed command-line tool.
+icon: wand-magic-sparkles
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+`fastmcp list` and `fastmcp call` let you poke at a server interactively, but they're developer tools — you always have to spell out the server spec, the tool name, and the arguments. `fastmcp generate-cli` takes the next step: it connects to a server, reads its schemas, and writes a standalone Python script where every tool is a proper subcommand with typed flags, help text, and tab completion. The result is a CLI that feels like it was hand-written for that specific server.
+
+The key insight is that MCP tool schemas already contain everything a CLI framework needs: parameter names, types, descriptions, required/optional status, and defaults. `generate-cli` maps that schema into [cyclopts](https://cyclopts.readthedocs.io/) commands, so JSON Schema types become Python type annotations, descriptions become `--help` text, and required parameters become mandatory flags.
+
+## Generating a Script
+
+Point the command at any server spec — URLs, Python files, discovered server names, MCPConfig JSON — and it writes a CLI script:
+
+```bash
+fastmcp generate-cli weather
+fastmcp generate-cli http://localhost:8000/mcp
+fastmcp generate-cli server.py my_weather_cli.py
+```
+
+The second positional argument sets the output path. When omitted, it defaults to `cli.py`. If either the CLI file or its companion `SKILL.md` already exists, the command refuses to overwrite unless you pass `-f`:
+
+```bash
+fastmcp generate-cli weather -f
+fastmcp generate-cli weather my_cli.py -f
+```
+
+Name-based resolution works here too, so if you have a server configured in Claude Desktop, Cursor, or any other supported editor, you can reference it by name. Run [`fastmcp discover`](/clients/cli#discovering-configured-servers) to see what's available.
+
+```bash
+fastmcp generate-cli claude-code:my-server output.py
+```
+
+The `--timeout` and `--auth` flags work the same way they do in `fastmcp list` and `fastmcp call`.
+
+## What You Get
+
+The generated script is a regular Python file — executable, editable, and yours. Here's what it looks like in practice:
+
+```
+$ python cli.py --help
+Usage: weather-cli COMMAND
+
+CLI for weather MCP server
+
+Commands:
+  call-tool       Call a tool on the server
+  list-tools      List available tools.
+  list-resources  List available resources.
+  read-resource   Read a resource by URI.
+  list-prompts    List available prompts.
+  get-prompt      Get a prompt by name. Pass arguments as key=value pairs.
+```
+
+The `call-tool` subcommand is where the generated code lives. Each tool on the server becomes its own command:
+
+```
+$ python cli.py call-tool --help
+Usage: weather-cli call-tool COMMAND
+
+Call a tool on the server
+
+Commands:
+  get_forecast  Get the weather forecast for a city.
+  search_city   Search for a city by name.
+```
+
+And each tool has typed parameters with help text pulled directly from the server's schema:
+
+```
+$ python cli.py call-tool get_forecast --help
+Usage: weather-cli call-tool get_forecast [OPTIONS]
+
+Get the weather forecast for a city.
+
+Options:
+  --city    [str]  City name (required)
+  --days    [int]  Number of forecast days (default: 3)
+```
+
+Tool names are preserved exactly as the server defines them — underscores stay as underscores, so `call-tool get_forecast` matches what the server expects.
+
+## Agent Skill
+
+Alongside the CLI script, `generate-cli` also writes a `SKILL.md` file — a [Claude Code agent skill](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/skills) that documents the generated CLI. The skill includes every tool's exact invocation syntax, parameter flags with types and descriptions, and the utility commands, so an agent can use the CLI immediately without running `--help` or experimenting with flag names.
+
+The skill is written to the same directory as the CLI script. For a weather server, it looks something like:
+
+````markdown
+---
+name: "weather-cli"
+description: "CLI for the weather MCP server. Call tools, list resources, and get prompts."
+---
+
+# weather CLI
+
+## Tool Commands
+
+### get_forecast
+
+Get the weather forecast for a city.
+
+```bash
+uv run --with fastmcp python cli.py call-tool get_forecast --city <value> --days <value>
+```
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--city` | string | yes | City name |
+| `--days` | integer | no | Number of forecast days |
+````
+
+To skip skill generation, pass `--no-skill`:
+
+```bash
+fastmcp generate-cli weather --no-skill
+```
+
+## How It Works
+
+The generated script is a client, not a server. It doesn't bundle or embed the MCP server — it connects to it on every invocation. For URL-based servers, the server needs to be running. For stdio-based servers, the command specified in `CLIENT_SPEC` must be available on the system's `PATH`.
+
+At the top of the generated file, a `CLIENT_SPEC` variable holds the resolved transport: either a URL string or a `StdioTransport` with the command and arguments baked in. Every invocation connects through this spec, so the script works without any external configuration.
+
+### Parameter Handling
+
+Parameters are mapped intelligently based on their complexity:
+
+**Simple types** (`string`, `integer`, `number`, `boolean`) become typed Python parameters with clean flags:
+```bash
+python cli.py call-tool get_forecast --city London --days 3
+```
+
+**Arrays of simple types** (`array` with `string`/`integer`/`number`/`boolean` items) become `list[T]` parameters that accept multiple flags:
+```bash
+python cli.py call-tool tag_items --tags python --tags fastapi --tags mcp
+```
+
+**Complex types** (objects, nested arrays, or unions) accept JSON strings. The tool's `--help` displays the full JSON schema so you know exactly what structure to pass:
+```bash
+python cli.py call-tool create_user \
+  --name John \
+  --metadata '{"role": "admin", "dept": "engineering"}'
+```
+
+Required parameters are mandatory flags; optional ones default to their schema default or `None`. Empty values are filtered out before calling the server.
+
+Beyond tool commands, the script includes generic commands that work regardless of what the server exposes: `list-tools`, `list-resources`, `read-resource`, `list-prompts`, and `get-prompt`. These connect to the server at runtime, so they always reflect the server's current state even if the tools have changed since generation.
+
+## Editing the Output
+
+The most common edit is changing `CLIENT_SPEC`. If you generated from a local dev server and want to point at production, just change the string. If you generated from a discovered name and want to pin the transport, replace it with an explicit URL or `StdioTransport`.
+
+Beyond that, it's a regular Python file. You can add commands, change the output formatting, integrate it into a larger application, or strip out the parts you don't need. The helper functions (`_call_tool`, `_print_tool_result`) are thin wrappers around `fastmcp.Client` that are easy to adapt.
+
+The generated script requires `fastmcp` as a dependency. If the script lives outside a project that already has fastmcp installed, `uv run` is the easiest way to run it without permanent installation:
+
+```bash
+uv run --with fastmcp python cli.py call-tool get_forecast --city London
+```
diff --git a/docs/clients/logging.mdx b/docs/clients/logging.mdx
new file mode 100644
index 0000000..eea9ff3
--- /dev/null
+++ b/docs/clients/logging.mdx
@@ -0,0 +1,92 @@
+---
+title: Server Logging
+sidebarTitle: Logging
+description: Receive and handle log messages from MCP servers.
+icon: receipt
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.0.0" />
+
+Use this when you need to capture or process log messages sent by the server.
+
+MCP servers can emit log messages to clients. The client handles these through a log handler callback.
+
+## Log Handler
+
+Provide a `log_handler` function when creating the client:
+
+```python
+import logging
+from fastmcp import Client
+from fastmcp.client.logging import LogMessage
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+
+logger = logging.getLogger(__name__)
+LOGGING_LEVEL_MAP = logging.getLevelNamesMapping()
+
+async def log_handler(message: LogMessage):
+    """Forward MCP server logs to Python's logging system."""
+    msg = message.data.get('msg')
+    extra = message.data.get('extra')
+
+    level = LOGGING_LEVEL_MAP.get(message.level.upper(), logging.INFO)
+    logger.log(level, msg, extra=extra)
+
+client = Client(
+    "my_mcp_server.py",
+    log_handler=log_handler,
+)
+```
+
+The handler receives a `LogMessage` object:
+
+<Card icon="code" title="LogMessage">
+<ResponseField name="level" type='Literal["debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"]'>
+  The log level
+</ResponseField>
+
+<ResponseField name="logger" type="str | None">
+  The logger name (may be None)
+</ResponseField>
+
+<ResponseField name="data" type="dict">
+  The log payload, containing `msg` and `extra` keys
+</ResponseField>
+</Card>
+
+## Structured Logs
+
+The `message.data` attribute is a dictionary containing the log payload. This enables structured logging with rich contextual information.
+
+```python
+async def detailed_log_handler(message: LogMessage):
+    msg = message.data.get('msg')
+    extra = message.data.get('extra')
+
+    if message.level == "error":
+        print(f"ERROR: {msg} | Details: {extra}")
+    elif message.level == "warning":
+        print(f"WARNING: {msg} | Details: {extra}")
+    else:
+        print(f"{message.level.upper()}: {msg}")
+```
+
+This structure is preserved even when logs are forwarded through a FastMCP proxy, making it useful for debugging multi-server applications.
+
+## Default Behavior
+
+If you do not provide a custom `log_handler`, FastMCP's default handler routes server logs to Python's logging system at the appropriate severity level. The MCP levels map as follows: `notice` becomes INFO; `alert` and `emergency` become CRITICAL.
+
+```python
+client = Client("my_mcp_server.py")
+
+async with client:
+    # Server logs are forwarded at proper severity automatically
+    await client.call_tool("some_tool")
+```
diff --git a/docs/clients/notifications.mdx b/docs/clients/notifications.mdx
new file mode 100644
index 0000000..aa7d470
--- /dev/null
+++ b/docs/clients/notifications.mdx
@@ -0,0 +1,155 @@
+---
+title: Notifications
+sidebarTitle: Notifications
+description: Handle server-sent notifications for list changes and other events.
+icon: envelope
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+<VersionBadge version="2.9.1" />
+
+Use this when you need to react to server-side changes like tool list updates or resource modifications.
+
+MCP servers can send notifications to inform clients about state changes. The message handler provides a unified way to process these notifications.
+
+## Handling Notifications
+
+The simplest approach is a function that receives all messages and filters for the notifications you care about:
+
+```python
+from fastmcp import Client
+
+async def message_handler(message):
+    """Handle MCP notifications from the server."""
+    if hasattr(message, 'method'):
+        method = message.method
+
+        if method == "notifications/tools/list_changed":
+            print("Tools have changed - refresh tool cache")
+        elif method == "notifications/resources/list_changed":
+            print("Resources have changed")
+        elif method == "notifications/prompts/list_changed":
+            print("Prompts have changed")
+
+client = Client(
+    "my_mcp_server.py",
+    message_handler=message_handler,
+)
+```
+
+## MessageHandler Class
+
+For fine-grained targeting, subclass `MessageHandler` to use specific hooks:
+
+```python
+from fastmcp import Client
+from fastmcp.client.messages import MessageHandler
+import mcp_types
+
+class MyMessageHandler(MessageHandler):
+    async def on_tool_list_changed(
+        self, notification: mcp_types.ToolListChangedNotification
+    ) -> None:
+        """Handle tool list changes."""
+        print("Tool list changed - refreshing available tools")
+
+    async def on_resource_list_changed(
+        self, notification: mcp_types.ResourceListChangedNotification
+    ) -> None:
+        """Handle resource list changes."""
+        print("Resource list changed")
+
+    async def on_prompt_list_changed(
+        self, notification: mcp_types.PromptListChangedNotification
+    ) -> None:
+        """Handle prompt list changes."""
+        print("Prompt list changed")
+
+client = Client(
+    "my_mcp_server.py",
+    message_handler=MyMessageHandler(),
+)
+```
+
+### Handler Template
+
+```python
+from fastmcp.client.messages import MessageHandler
+import mcp_types
+
+class MyMessageHandler(MessageHandler):
+    async def on_message(self, message) -> None:
+        """Called for ALL messages (requests and notifications)."""
+        pass
+
+    async def on_notification(
+        self, notification: mcp_types.ServerNotification
+    ) -> None:
+        """Called for notifications (fire-and-forget)."""
+        pass
+
+    async def on_tool_list_changed(
+        self, notification: mcp_types.ToolListChangedNotification
+    ) -> None:
+        """Called when the server's tool list changes."""
+        pass
+
+    async def on_resource_list_changed(
+        self, notification: mcp_types.ResourceListChangedNotification
+    ) -> None:
+        """Called when the server's resource list changes."""
+        pass
+
+    async def on_prompt_list_changed(
+        self, notification: mcp_types.PromptListChangedNotification
+    ) -> None:
+        """Called when the server's prompt list changes."""
+        pass
+
+    async def on_progress(
+        self, notification: mcp_types.ProgressNotification
+    ) -> None:
+        """Called for progress updates during long-running operations."""
+        pass
+
+    async def on_logging_message(
+        self, notification: mcp_types.LoggingMessageNotification
+    ) -> None:
+        """Called for log messages from the server."""
+        pass
+```
+
+## List Change Notifications
+
+A practical example of maintaining a tool cache that refreshes when tools change:
+
+```python
+from fastmcp import Client
+from fastmcp.client.messages import MessageHandler
+import mcp_types
+
+class ToolCacheHandler(MessageHandler):
+    def __init__(self):
+        self.cached_tools = []
+
+    async def on_tool_list_changed(
+        self, notification: mcp_types.ToolListChangedNotification
+    ) -> None:
+        """Clear tool cache when tools change."""
+        print("Tools changed - clearing cache")
+        self.cached_tools = []  # Force refresh on next access
+
+client = Client("server.py", message_handler=ToolCacheHandler())
+```
+
+## Server Requests
+
+While the message handler receives server-initiated requests, you should use dedicated callback parameters for most interactive scenarios:
+
+- **Sampling requests**: Use [`sampling_handler`](/clients/sampling)
+- **Elicitation requests**: Use [`elicitation_handler`](/clients/elicitation)
+- **Progress updates**: Use [`progress_handler`](/clients/progress)
+- **Log messages**: Use [`log_handler`](/clients/logging)
+
+The message handler is primarily for monitoring and handling notifications rather than responding to requests.
diff --git a/docs/clients/progress.mdx b/docs/clients/progress.mdx
new file mode 100644
index 0000000..707ab8d
--- /dev/null
+++ b/docs/clients/progress.mdx
@@ -0,0 +1,67 @@
+---
+title: Progress Monitoring
+sidebarTitle: Progress
+description: Handle progress notifications from long-running server operations.
+icon: bars-progress
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.3.5" />
+
+Use this when you need to track progress of long-running operations.
+
+MCP servers can report progress during operations. The client receives these updates through a progress handler.
+
+## Progress Handler
+
+Set a handler when creating the client:
+
+```python
+from fastmcp import Client
+
+async def progress_handler(
+    progress: float,
+    total: float | None,
+    message: str | None
+) -> None:
+    if total is not None:
+        percentage = (progress / total) * 100
+        print(f"Progress: {percentage:.1f}% - {message or ''}")
+    else:
+        print(f"Progress: {progress} - {message or ''}")
+
+client = Client(
+    "my_mcp_server.py",
+    progress_handler=progress_handler
+)
+```
+
+The handler receives three parameters:
+
+<Card icon="code" title="Handler Parameters">
+<ResponseField name="progress" type="float">
+  Current progress value
+</ResponseField>
+
+<ResponseField name="total" type="float | None">
+  Expected total value (may be None if unknown)
+</ResponseField>
+
+<ResponseField name="message" type="str | None">
+  Optional status message
+</ResponseField>
+</Card>
+
+## Per-Call Handler
+
+Override the client-level handler for specific tool calls:
+
+```python
+async with client:
+    result = await client.call_tool(
+        "long_running_task",
+        {"param": "value"},
+        progress_handler=my_progress_handler
+    )
+```
diff --git a/docs/clients/prompts.mdx b/docs/clients/prompts.mdx
new file mode 100644
index 0000000..5d1bd73
--- /dev/null
+++ b/docs/clients/prompts.mdx
@@ -0,0 +1,147 @@
+---
+title: Getting Prompts
+sidebarTitle: Prompts
+description: Retrieve rendered message templates with automatic argument serialization.
+icon: message-lines
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.0.0" />
+
+Use this when you need to retrieve server-defined message templates for LLM interactions.
+
+Prompts are reusable message templates exposed by MCP servers. They can accept arguments to generate personalized message sequences for LLM interactions.
+
+## Basic Usage
+
+Request a rendered prompt with `get_prompt()`:
+
+```python
+async with client:
+    # Simple prompt without arguments
+    result = await client.get_prompt("welcome_message")
+    # result -> fastmcp.types.GetPromptResult
+
+    # Access the generated messages
+    for message in result.messages:
+        print(f"Role: {message.role}")
+        print(f"Content: {message.content}")
+```
+
+Pass arguments to customize the prompt:
+
+```python
+async with client:
+    result = await client.get_prompt("user_greeting", {
+        "name": "Alice",
+        "role": "administrator"
+    })
+
+    for message in result.messages:
+        print(f"Generated message: {message.content}")
+```
+
+## Argument Serialization
+
+<VersionBadge version="2.9.0" />
+
+FastMCP automatically serializes complex arguments to JSON strings as required by the MCP specification. You can pass typed objects directly:
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class UserData:
+    name: str
+    age: int
+
+async with client:
+    result = await client.get_prompt("analyze_user", {
+        "user": UserData(name="Alice", age=30),     # Automatically serialized
+        "preferences": {"theme": "dark"},           # Dict serialized
+        "scores": [85, 92, 78],                     # List serialized
+        "simple_name": "Bob"                        # Strings unchanged
+    })
+```
+
+The client handles serialization using `pydantic_core.to_json()` for consistent formatting. FastMCP servers automatically deserialize these JSON strings back to the expected types.
+
+## Working with Results
+
+The `get_prompt()` method returns a `GetPromptResult` containing a list of messages:
+
+```python
+async with client:
+    result = await client.get_prompt("conversation_starter", {"topic": "climate"})
+
+    for i, message in enumerate(result.messages):
+        print(f"Message {i + 1}:")
+        print(f"  Role: {message.role}")
+        print(f"  Content: {message.content.text if hasattr(message.content, 'text') else message.content}")
+```
+
+Prompts can generate different message types. System messages configure LLM behavior:
+
+```python
+async with client:
+    result = await client.get_prompt("system_configuration", {
+        "role": "helpful assistant",
+        "expertise": "python programming"
+    })
+
+    # Access the returned messages
+    message = result.messages[0]
+    print(f"Prompt: {message.content}")
+```
+
+Conversation templates generate multi-turn flows:
+
+```python
+async with client:
+    result = await client.get_prompt("interview_template", {
+        "candidate_name": "Alice",
+        "position": "Senior Developer"
+    })
+
+    # Multiple messages for a conversation flow
+    for message in result.messages:
+        print(f"{message.role}: {message.content}")
+```
+
+## Version Selection
+
+<VersionBadge version="3.0.0" />
+
+When a server exposes multiple versions of a prompt, you can request a specific version:
+
+```python
+async with client:
+    # Get the highest version (default)
+    result = await client.get_prompt("summarize", {"text": "..."})
+
+    # Get a specific version
+    result_v1 = await client.get_prompt("summarize", {"text": "..."}, version="1.0")
+```
+
+See [Metadata](/servers/versioning#version-discovery) for how to discover available versions.
+
+## Multi-Server Clients
+
+When using multi-server clients, prompts are accessible directly without prefixing:
+
+```python
+async with client:  # Multi-server client
+    result1 = await client.get_prompt("weather_prompt", {"city": "London"})
+    result2 = await client.get_prompt("assistant_prompt", {"query": "help"})
+```
+
+## Raw Protocol Access
+
+For complete control, use `get_prompt_mcp()` which returns the full MCP protocol object:
+
+```python
+async with client:
+    result = await client.get_prompt_mcp("example_prompt", {"arg": "value"})
+    # result -> fastmcp.types.GetPromptResult
+```
diff --git a/docs/clients/resources.mdx b/docs/clients/resources.mdx
new file mode 100644
index 0000000..197ec6c
--- /dev/null
+++ b/docs/clients/resources.mdx
@@ -0,0 +1,110 @@
+---
+title: Reading Resources
+sidebarTitle: Resources
+description: Access static and templated data sources from MCP servers.
+icon: folder-open
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.0.0" />
+
+Use this when you need to read data from server-exposed resources like configuration files, generated content, or external data sources.
+
+Resources are data sources exposed by MCP servers. They can be static files with fixed content, or dynamic templates that generate content based on parameters in the URI.
+
+## Reading Resources
+
+Read a resource using its URI:
+
+```python
+async with client:
+    content = await client.read_resource("file:///path/to/README.md")
+    # content -> list[TextResourceContents | BlobResourceContents]
+
+    # Access text content
+    if hasattr(content[0], 'text'):
+        print(content[0].text)
+
+    # Access binary content
+    if hasattr(content[0], 'blob'):
+        print(f"Binary data: {len(content[0].blob)} bytes")
+```
+
+Resource templates generate content based on URI parameters. The template defines a pattern like `weather://{{city}}/current`, and you fill in the parameters when reading:
+
+```python
+async with client:
+    # Read from a resource template
+    weather_content = await client.read_resource("weather://london/current")
+    print(weather_content[0].text)
+```
+
+## Content Types
+
+Resources return different content types depending on what they expose.
+
+Text resources include configuration files, JSON data, and other human-readable content:
+
+```python
+async with client:
+    content = await client.read_resource("resource://config/settings.json")
+
+    for item in content:
+        if hasattr(item, 'text'):
+            print(f"Text content: {item.text}")
+            print(f"MIME type: {item.mime_type}")
+```
+
+Binary resources include images, PDFs, and other non-text data:
+
+```python
+async with client:
+    content = await client.read_resource("resource://images/logo.png")
+
+    for item in content:
+        if hasattr(item, 'blob'):
+            print(f"Binary content: {len(item.blob)} bytes")
+            print(f"MIME type: {item.mime_type}")
+
+            # Save to file
+            with open("downloaded_logo.png", "wb") as f:
+                f.write(item.blob)
+```
+
+## Multi-Server Clients
+
+When using multi-server clients, resource URIs are prefixed with the server name:
+
+```python
+async with client:  # Multi-server client
+    weather_icons = await client.read_resource("weather://weather/icons/sunny")
+    templates = await client.read_resource("resource://assistant/templates/list")
+```
+
+## Version Selection
+
+<VersionBadge version="3.0.0" />
+
+When a server exposes multiple versions of a resource, you can request a specific version:
+
+```python
+async with client:
+    # Read the highest version (default)
+    content = await client.read_resource("data://config")
+
+    # Read a specific version
+    content_v1 = await client.read_resource("data://config", version="1.0")
+```
+
+See [Metadata](/servers/versioning#version-discovery) for how to discover available versions.
+
+## Raw Protocol Access
+
+For complete control, use `read_resource_mcp()` which returns the full MCP protocol object:
+
+```python
+async with client:
+    result = await client.read_resource_mcp("resource://example")
+    # result -> fastmcp.types.ReadResourceResult
+```
diff --git a/docs/clients/roots.mdx b/docs/clients/roots.mdx
new file mode 100644
index 0000000..0370c11
--- /dev/null
+++ b/docs/clients/roots.mdx
@@ -0,0 +1,45 @@
+---
+title: Client Roots
+sidebarTitle: Roots
+description: Provide local context and resource boundaries to MCP servers.
+icon: folder-tree
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.0.0" />
+
+Use this when you need to tell servers what local resources the client has access to.
+
+Roots inform servers about resources the client can provide. Servers can use this information to adjust behavior or provide more relevant responses.
+
+## Static Roots
+
+Provide a list of roots when creating the client:
+
+```python
+from fastmcp import Client
+
+client = Client(
+    "my_mcp_server.py",
+    roots=["/path/to/root1", "/path/to/root2"]
+)
+```
+
+## Dynamic Roots
+
+Use a callback to compute roots dynamically when the server requests them:
+
+```python
+from fastmcp import Client
+from fastmcp.client.roots import RequestContext
+
+async def roots_callback(context: RequestContext) -> list[str]:
+    print(f"Server requested roots (Request ID: {context.request_id})")
+    return ["/path/to/root1", "/path/to/root2"]
+
+client = Client(
+    "my_mcp_server.py",
+    roots=roots_callback
+)
+```
diff --git a/docs/clients/sampling.mdx b/docs/clients/sampling.mdx
new file mode 100644
index 0000000..b065598
--- /dev/null
+++ b/docs/clients/sampling.mdx
@@ -0,0 +1,190 @@
+---
+title: LLM Sampling
+sidebarTitle: Sampling
+description: Handle server-initiated LLM completion requests.
+icon: robot
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+<VersionBadge version="2.0.0" />
+
+Use this when you need to respond to server requests for LLM completions.
+
+MCP servers can request LLM completions from clients during tool execution. This enables servers to delegate AI reasoning to the client, which controls which LLM is used and how requests are made.
+
+## Handler Template
+
+```python
+from fastmcp import Client
+from fastmcp.client.sampling import SamplingMessage, SamplingParams, RequestContext
+
+async def sampling_handler(
+    messages: list[SamplingMessage],
+    params: SamplingParams,
+    context: RequestContext
+) -> str:
+    """
+    Handle server requests for LLM completions.
+
+    Args:
+        messages: Conversation messages to send to the LLM
+        params: Sampling parameters (temperature, max_tokens, etc.)
+        context: Request context with metadata
+
+    Returns:
+        Generated text response from your LLM
+    """
+    # Extract message content
+    conversation = []
+    for message in messages:
+        content = message.content.text if hasattr(message.content, 'text') else str(message.content)
+        conversation.append(f"{message.role}: {content}")
+
+    # Use the system prompt if provided
+    system_prompt = params.system_prompt or "You are a helpful assistant."
+
+    # Integrate with your LLM service here
+    return "Generated response based on the messages"
+
+client = Client(
+    "my_mcp_server.py",
+    sampling_handler=sampling_handler,
+)
+```
+
+## Handler Parameters
+
+<Card icon="code" title="SamplingMessage">
+<ResponseField name="role" type='Literal["user", "assistant"]'>
+  The role of the message
+</ResponseField>
+
+<ResponseField name="content" type="TextContent | ImageContent | AudioContent">
+  The content of the message. TextContent has a `.text` attribute.
+</ResponseField>
+</Card>
+
+<Card icon="code" title="SamplingParams">
+<ResponseField name="systemPrompt" type="str | None">
+  Optional system prompt the server wants to use
+</ResponseField>
+
+<ResponseField name="modelPreferences" type="ModelPreferences | None">
+  Server preferences for model selection (hints, cost/speed/intelligence priorities)
+</ResponseField>
+
+<ResponseField name="temperature" type="float | None">
+  Sampling temperature
+</ResponseField>
+
+<ResponseField name="maxTokens" type="int">
+  Maximum tokens to generate
+</ResponseField>
+
+<ResponseField name="stopSequences" type="list[str] | None">
+  Stop sequences for sampling
+</ResponseField>
+
+<ResponseField name="tools" type="list[Tool] | None">
+  Tools the LLM can use during sampling
+</ResponseField>
+
+<ResponseField name="toolChoice" type="ToolChoice | None">
+  Tool usage behavior (`auto`, `required`, or `none`)
+</ResponseField>
+</Card>
+
+## Built-in Handlers
+
+FastMCP provides built-in handlers for OpenAI, Anthropic, and Google Gemini APIs that support the full sampling API including tool use.
+
+### OpenAI Handler
+
+<VersionBadge version="2.11.0" />
+
+```python
+from fastmcp import Client
+from fastmcp.client.sampling.handlers.openai import OpenAISamplingHandler
+
+client = Client(
+    "my_mcp_server.py",
+    sampling_handler=OpenAISamplingHandler(default_model="gpt-4o"),
+)
+```
+
+For OpenAI-compatible APIs (like local models):
+
+```python
+from openai import AsyncOpenAI
+
+client = Client(
+    "my_mcp_server.py",
+    sampling_handler=OpenAISamplingHandler(
+        default_model="llama-3.1-70b",
+        client=AsyncOpenAI(base_url="http://localhost:8000/v1"),
+    ),
+)
+```
+
+<Note>
+Install the OpenAI handler with `pip install fastmcp[openai]`.
+</Note>
+
+### Anthropic Handler
+
+<VersionBadge version="2.14.1" />
+
+```python
+from fastmcp import Client
+from fastmcp.client.sampling.handlers.anthropic import AnthropicSamplingHandler
+
+client = Client(
+    "my_mcp_server.py",
+    sampling_handler=AnthropicSamplingHandler(default_model="claude-sonnet-4-5"),
+)
+```
+
+<Note>
+Install the Anthropic handler with `pip install fastmcp[anthropic]`.
+</Note>
+
+### Google Gemini Handler
+
+<VersionBadge version="3.1.0" />
+
+```python
+from fastmcp import Client
+from fastmcp.client.sampling.handlers.google_genai import GoogleGenaiSamplingHandler
+
+client = Client(
+    "my_mcp_server.py",
+    sampling_handler=GoogleGenaiSamplingHandler(default_model="gemini-2.0-flash"),
+)
+```
+
+<Note>
+Install the Google Gemini handler with `pip install fastmcp[gemini]`.
+</Note>
+
+## Sampling Capabilities
+
+When you provide a `sampling_handler`, FastMCP automatically advertises full sampling capabilities to the server, including tool support. To disable tool support for simpler handlers:
+
+```python
+from fastmcp.types import SamplingCapability
+
+client = Client(
+    "my_mcp_server.py",
+    sampling_handler=basic_handler,
+    sampling_capabilities=SamplingCapability(),  # No tool support
+)
+```
+
+## Tool Execution
+
+Tool execution happens on the server side. The client's role is to pass tools to the LLM and return the LLM's response (which may include tool use requests). The server then executes the tools and may send follow-up sampling requests with tool results.
+
+<Tip>
+To implement a custom sampling handler, see the [handler source code](https://github.com/PrefectHQ/fastmcp/tree/main/fastmcp_slim/fastmcp/client/sampling/handlers) as a reference.
+</Tip>
diff --git a/docs/clients/tasks.mdx b/docs/clients/tasks.mdx
new file mode 100644
index 0000000..ce27520
--- /dev/null
+++ b/docs/clients/tasks.mdx
@@ -0,0 +1,182 @@
+---
+title: Background Tasks
+sidebarTitle: Tasks
+description: Execute operations asynchronously and track their progress.
+icon: clock
+tag: "NEW"
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.14.0" />
+
+Use this when you need to run long operations asynchronously while doing other work.
+
+The MCP task protocol lets you request operations to run in the background. The call returns a Task object immediately, letting you track progress, cancel operations, or await results.
+
+## Requesting Background Execution
+
+Pass `task=True` to run an operation as a background task:
+
+```python
+from fastmcp import Client
+
+async with Client(server) as client:
+    # Start a background task
+    task = await client.call_tool("slow_computation", {"duration": 10}, task=True)
+
+    print(f"Task started: {task.task_id}")
+
+    # Do other work while it runs...
+
+    # Get the result when ready
+    result = await task.result()
+```
+
+This works with tools, resources, and prompts:
+
+```python
+tool_task = await client.call_tool("my_tool", args, task=True)
+resource_task = await client.read_resource("file://large.txt", task=True)
+prompt_task = await client.get_prompt("my_prompt", args, task=True)
+```
+
+## Task API
+
+All task types share a common interface.
+
+### Getting Results
+
+Call `await task.result()` or simply `await task` to block until the task completes:
+
+```python
+task = await client.call_tool("analyze", {"text": "hello"}, task=True)
+
+# Wait for result (blocking)
+result = await task.result()
+# or: result = await task
+```
+
+### Checking Status
+
+Check the current status without blocking:
+
+```python
+status = await task.status()
+print(f"{status.status}: {status.statusMessage}")
+# status.status is "working", "completed", "failed", or "cancelled"
+```
+
+### Waiting with Control
+
+Use `task.wait()` for more control over waiting:
+
+```python
+# Wait up to 30 seconds for completion
+status = await task.wait(timeout=30.0)
+
+# Wait for a specific state
+status = await task.wait(state="completed", timeout=30.0)
+```
+
+### Cancellation
+
+Cancel a running task:
+
+```python
+await task.cancel()
+```
+
+## Status Updates
+
+Register callbacks to receive real-time status updates as the server reports progress:
+
+```python
+def on_status_change(status):
+    print(f"Task {status.taskId}: {status.status} - {status.statusMessage}")
+
+task.on_status_change(on_status_change)
+
+# Async callbacks work too
+async def on_status_async(status):
+    await log_status(status)
+
+task.on_status_change(on_status_async)
+```
+
+### Handler Template
+
+```python
+from fastmcp import Client
+
+def status_handler(status):
+    """
+    Handle task status updates.
+
+    Args:
+        status: Task status object with:
+            - taskId: Unique task identifier
+            - status: "working", "completed", "failed", or "cancelled"
+            - statusMessage: Optional progress message from server
+    """
+    if status.status == "working":
+        print(f"Progress: {status.statusMessage}")
+    elif status.status == "completed":
+        print("Task completed")
+    elif status.status == "failed":
+        print(f"Task failed: {status.statusMessage}")
+
+task.on_status_change(status_handler)
+```
+
+## Graceful Degradation
+
+You can always pass `task=True` regardless of whether the server supports background tasks. Per the MCP specification, servers without task support execute the operation immediately and return the result inline.
+
+```python
+task = await client.call_tool("my_tool", args, task=True)
+
+if task.returned_immediately:
+    print("Server executed immediately (no background support)")
+else:
+    print("Running in background")
+
+# Either way, this works
+result = await task.result()
+```
+
+This lets you write task-aware client code without worrying about server capabilities.
+
+## Example
+
+```python
+import asyncio
+from fastmcp import Client
+
+async def main():
+    async with Client(server) as client:
+        # Start background task
+        task = await client.call_tool(
+            "slow_computation",
+            {"duration": 10},
+            task=True,
+        )
+
+        # Subscribe to updates
+        def on_update(status):
+            print(f"Progress: {status.statusMessage}")
+
+        task.on_status_change(on_update)
+
+        # Do other work while task runs
+        print("Doing other work...")
+        await asyncio.sleep(2)
+
+        # Wait for completion and get result
+        result = await task.result()
+        print(f"Result: {result.content}")
+
+asyncio.run(main())
+```
+
+See [Server Background Tasks](/servers/tasks) for how to enable background task support on the server side.
diff --git a/docs/clients/tools.mdx b/docs/clients/tools.mdx
new file mode 100644
index 0000000..9422c30
--- /dev/null
+++ b/docs/clients/tools.mdx
@@ -0,0 +1,183 @@
+---
+title: Calling Tools
+sidebarTitle: Tools
+description: Execute server-side tools and handle structured results.
+icon: wrench
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.0.0" />
+
+Use this when you need to execute server-side functions and process their results.
+
+Tools are executable functions exposed by MCP servers. The client's `call_tool()` method executes a tool by name with arguments and returns structured results.
+
+## Basic Execution
+
+```python
+async with client:
+    result = await client.call_tool("add", {"a": 5, "b": 3})
+    # result -> CallToolResult with structured and unstructured data
+
+    # Access structured data (automatically deserialized)
+    print(result.data)  # 8
+
+    # Access traditional content blocks
+    print(result.content[0].text)  # "8"
+```
+
+Arguments are passed as a dictionary. For multi-server clients, tool names are automatically prefixed with the server name (e.g., `weather_get_forecast` for a tool named `get_forecast` on the `weather` server).
+
+## Execution Options
+
+The `call_tool()` method supports timeout control and progress monitoring:
+
+```python
+async with client:
+    # With timeout (aborts if execution takes longer than 2 seconds)
+    result = await client.call_tool(
+        "long_running_task",
+        {"param": "value"},
+        timeout=2.0
+    )
+
+    # With progress handler
+    result = await client.call_tool(
+        "long_running_task",
+        {"param": "value"},
+        progress_handler=my_progress_handler
+    )
+```
+
+## Structured Results
+
+<VersionBadge version="2.10.0" />
+
+Tool execution returns a `CallToolResult` object. The `.data` property provides fully hydrated Python objects including complex types like datetimes and UUIDs, reconstructed from the server's output schema.
+
+```python
+from datetime import datetime
+from uuid import UUID
+
+async with client:
+    result = await client.call_tool("get_weather", {"city": "London"})
+
+    # FastMCP reconstructs complete Python objects
+    weather = result.data
+    print(f"Temperature: {weather.temperature}C at {weather.timestamp}")
+
+    # Complex types are properly deserialized
+    assert isinstance(weather.timestamp, datetime)
+    assert isinstance(weather.station_id, UUID)
+
+    # Raw structured JSON is also available
+    print(f"Raw JSON: {result.structured_content}")
+```
+
+<Card icon="code" title="CallToolResult Properties">
+<ResponseField name=".data" type="Any">
+  Fully hydrated Python objects with complex type support (datetimes, UUIDs, custom classes). FastMCP exclusive.
+</ResponseField>
+
+<ResponseField name=".content" type="list[fastmcp.types.ContentBlock]">
+  Standard MCP content blocks (`TextContent`, `ImageContent`, `AudioContent`, etc.).
+</ResponseField>
+
+<ResponseField name=".structured_content" type="dict[str, Any] | None">
+  Standard MCP structured JSON data as sent by the server.
+</ResponseField>
+
+<ResponseField name=".is_error" type="bool">
+  Boolean indicating if the tool execution failed.
+</ResponseField>
+</Card>
+
+For tools without output schemas or when deserialization fails, `.data` will be `None`. Fall back to content blocks in that case:
+
+```python
+async with client:
+    result = await client.call_tool("legacy_tool", {"param": "value"})
+
+    if result.data is not None:
+        print(f"Structured: {result.data}")
+    else:
+        for content in result.content:
+            if hasattr(content, 'text'):
+                print(f"Text result: {content.text}")
+```
+
+<Tip>
+FastMCP servers automatically wrap primitive results (like `int`, `str`, `bool`) in a `{"result": value}` structure. FastMCP clients automatically unwrap this, so you get the original value in `.data`.
+</Tip>
+
+## Error Handling
+
+By default, `call_tool()` raises a `ToolError` if the tool execution fails:
+
+```python
+from fastmcp.exceptions import ToolError
+
+async with client:
+    try:
+        result = await client.call_tool("potentially_failing_tool", {"param": "value"})
+        print("Tool succeeded:", result.data)
+    except ToolError as e:
+        print(f"Tool failed: {e}")
+```
+
+To handle errors manually instead of catching exceptions, disable automatic error raising:
+
+```python
+async with client:
+    result = await client.call_tool(
+        "potentially_failing_tool",
+        {"param": "value"},
+        raise_on_error=False
+    )
+
+    if result.is_error:
+        print(f"Tool failed: {result.content[0].text}")
+    else:
+        print(f"Tool succeeded: {result.data}")
+```
+
+## Sending Metadata
+
+<VersionBadge version="2.13.1" />
+
+The `meta` parameter sends ancillary information alongside tool calls for observability, debugging, or client identification:
+
+```python
+async with client:
+    result = await client.call_tool(
+        name="send_email",
+        arguments={
+            "to": "user@example.com",
+            "subject": "Hello",
+            "body": "Welcome!"
+        },
+        meta={
+            "trace_id": "abc-123",
+            "request_source": "mobile_app"
+        }
+    )
+```
+
+See [Client Metadata](/servers/context#client-metadata) to learn how servers access this data.
+
+## Raw Protocol Access
+
+For complete control, use `call_tool_mcp()` which returns the raw MCP protocol object:
+
+```python
+async with client:
+    result = await client.call_tool_mcp("my_tool", {"param": "value"})
+    # result -> fastmcp.types.CallToolResult
+
+    if result.is_error:
+        print(f"Tool failed: {result.content}")
+    else:
+        print(f"Tool succeeded: {result.content}")
+        # Note: No automatic deserialization with call_tool_mcp()
+```
diff --git a/docs/clients/transports.mdx b/docs/clients/transports.mdx
new file mode 100644
index 0000000..efcda33
--- /dev/null
+++ b/docs/clients/transports.mdx
@@ -0,0 +1,267 @@
+---
+title: Client Transports
+sidebarTitle: Transports
+description: Configure how clients connect to and communicate with MCP servers.
+icon: link
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.0.0" />
+
+Transports handle the underlying connection between your client and MCP servers. While the client can automatically select a transport based on what you pass to it, instantiating transports explicitly gives you full control over configuration.
+
+## STDIO Transport
+
+STDIO transport communicates with MCP servers through subprocess pipes. When using STDIO, your client launches and manages the server process, controlling its lifecycle and environment.
+
+<Warning>
+STDIO servers run in isolated environments by default. They do not inherit your shell's environment variables. You must explicitly pass any configuration the server needs.
+</Warning>
+
+```python
+from fastmcp import Client
+from fastmcp.client.transports import StdioTransport
+
+transport = StdioTransport(
+    command="python",
+    args=["my_server.py", "--verbose"],
+    env={"API_KEY": "secret", "LOG_LEVEL": "DEBUG"},
+    cwd="/path/to/server"
+)
+client = Client(transport)
+```
+
+For convenience, the client can infer STDIO transport from file paths, though this limits configuration options:
+
+```python
+from fastmcp import Client
+
+client = Client("my_server.py")  # Limited - no configuration options
+```
+
+### Environment Variables
+
+Since STDIO servers do not inherit your environment, you need strategies for passing configuration.
+
+**Selective forwarding** passes only the variables your server needs:
+
+```python
+import os
+from fastmcp.client.transports import StdioTransport
+
+required_vars = ["API_KEY", "DATABASE_URL", "REDIS_HOST"]
+env = {var: os.environ[var] for var in required_vars if var in os.environ}
+
+transport = StdioTransport(command="python", args=["server.py"], env=env)
+client = Client(transport)
+```
+
+**Loading from .env files** keeps configuration separate from code:
+
+```python
+from dotenv import dotenv_values
+from fastmcp.client.transports import StdioTransport
+
+env = dotenv_values(".env")
+transport = StdioTransport(command="python", args=["server.py"], env=env)
+client = Client(transport)
+```
+
+### Session Persistence
+
+STDIO transports maintain sessions across multiple client contexts by default (`keep_alive=True`). This reuses the same subprocess for multiple connections, improving performance.
+
+```python
+from fastmcp.client.transports import StdioTransport
+
+transport = StdioTransport(command="python", args=["server.py"])
+client = Client(transport)
+
+async def efficient_multiple_operations():
+    async with client:
+        await client.ping()
+
+    async with client:  # Reuses the same subprocess
+        await client.call_tool("process_data", {"file": "data.csv"})
+```
+
+For complete isolation between connections, disable session persistence:
+
+```python
+transport = StdioTransport(command="python", args=["server.py"], keep_alive=False)
+```
+
+## HTTP Transport
+
+<VersionBadge version="2.3.0" />
+
+HTTP transport connects to MCP servers running as web services. This is the recommended transport for production deployments.
+
+```python
+from fastmcp import Client
+from fastmcp.client.transports import StreamableHttpTransport
+
+transport = StreamableHttpTransport(
+    url="https://api.example.com/mcp",
+    headers={
+        "Authorization": "Bearer your-token-here",
+        "X-Custom-Header": "value"
+    }
+)
+client = Client(transport)
+```
+
+FastMCP also provides authentication helpers:
+
+```python
+from fastmcp import Client
+from fastmcp.client.auth import BearerAuth
+
+client = Client(
+    "https://api.example.com/mcp",
+    auth=BearerAuth("your-token-here")
+)
+```
+
+### SSL Verification
+
+By default, HTTPS connections verify the server's SSL certificate. You can customize this behavior with the `verify` parameter, which accepts the same values as [httpx](https://www.python-httpx.org/advanced/ssl/):
+
+```python
+from fastmcp import Client
+
+# Disable SSL verification (e.g., for self-signed certs in development)
+client = Client("https://dev-server.internal/mcp", verify=False)
+
+# Use a custom CA bundle
+client = Client("https://corp-server.internal/mcp", verify="/path/to/ca-bundle.pem")
+
+# Use a custom SSL context for full control
+import ssl
+ctx = ssl.create_default_context()
+ctx.load_verify_locations("/path/to/internal-ca.pem")
+client = Client("https://corp-server.internal/mcp", verify=ctx)
+```
+
+The `verify` parameter is also available directly on `StreamableHttpTransport` and `SSETransport`:
+
+```python
+from fastmcp.client.transports import StreamableHttpTransport
+
+transport = StreamableHttpTransport(
+    url="https://dev-server.internal/mcp",
+    verify=False,
+)
+client = Client(transport)
+```
+
+### SSE Transport
+
+Server-Sent Events transport is maintained for backward compatibility. Use Streamable HTTP for new deployments unless you have specific infrastructure requirements.
+
+```python
+from fastmcp.client.transports import SSETransport
+
+transport = SSETransport(
+    url="https://api.example.com/sse",
+    headers={"Authorization": "Bearer token"}
+)
+client = Client(transport)
+```
+
+## In-Memory Transport
+
+In-memory transport connects directly to a FastMCP server instance within the same Python process. This eliminates both subprocess management and network overhead, making it ideal for testing.
+
+```python
+from fastmcp import FastMCP, Client
+import os
+
+mcp = FastMCP("TestServer")
+
+@mcp.tool
+def greet(name: str) -> str:
+    prefix = os.environ.get("GREETING_PREFIX", "Hello")
+    return f"{prefix}, {name}!"
+
+client = Client(mcp)
+
+async with client:
+    result = await client.call_tool("greet", {"name": "World"})
+```
+
+<Note>
+Unlike STDIO transports, in-memory servers share the same memory space and environment variables as your client code.
+</Note>
+
+## Multi-Server Configuration
+
+<VersionBadge version="2.4.0" />
+
+Connect to multiple servers defined in a configuration dictionary:
+
+```python
+from fastmcp import Client
+
+config = {
+    "mcpServers": {
+        "weather": {
+            "url": "https://weather.example.com/mcp",
+            "transport": "http"
+        },
+        "assistant": {
+            "command": "python",
+            "args": ["./assistant.py"],
+            "env": {"LOG_LEVEL": "INFO"}
+        }
+    }
+}
+
+client = Client(config)
+
+async with client:
+    # Tools are namespaced by server
+    weather = await client.call_tool("weather_get_forecast", {"city": "NYC"})
+    answer = await client.call_tool("assistant_ask", {"question": "What?"})
+```
+
+### Tool Transformations
+
+FastMCP supports tool transformations within the configuration. You can change names, descriptions, tags, and arguments for tools from a server.
+
+```python
+config = {
+    "mcpServers": {
+        "weather": {
+            "url": "https://weather.example.com/mcp",
+            "transport": "http",
+            "tools": {
+                "weather_get_forecast": {
+                    "name": "miami_weather",
+                    "description": "Get the weather for Miami",
+                    "arguments": {
+                        "city": {
+                            "default": "Miami",
+                            "hide": True,
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+To filter tools by tag, use `include_tags` or `exclude_tags` at the server level:
+
+```python
+config = {
+    "mcpServers": {
+        "weather": {
+            "url": "https://weather.example.com/mcp",
+            "include_tags": ["forecast"]  # Only tools with this tag
+        }
+    }
+}
+```
diff --git a/docs/community/README.md b/docs/community/README.md
new file mode 100644
index 0000000..b61f5cf
--- /dev/null
+++ b/docs/community/README.md
@@ -0,0 +1,22 @@
+# Community Section
+
+This directory contains community-contributed content and showcases for FastMCP.
+
+## Structure
+
+- `showcase.mdx` - Main community showcase page featuring high-quality projects and examples
+
+## Adding Content
+
+To add new community content:
+1. Create a new MDX file in this directory
+2. Update `docs.json` to include it in the navigation
+3. Follow the existing format for consistency
+
+## Guidelines
+
+Community content should:
+- Demonstrate best practices
+- Provide educational value
+- Include proper documentation
+- Be maintained and up-to-date
\ No newline at end of file
diff --git a/docs/community/showcase.mdx b/docs/community/showcase.mdx
new file mode 100644
index 0000000..9ba4c68
--- /dev/null
+++ b/docs/community/showcase.mdx
@@ -0,0 +1,65 @@
+---
+title: 'Community Showcase'
+description: 'High-quality projects and examples from the FastMCP community'
+icon: 'users'
+---
+
+import { YouTubeEmbed } from '/snippets/youtube-embed.mdx'
+
+## Join the Community
+
+<Card title="FastMCP Discord" icon="discord" href="https://discord.gg/uu8dJCgttd">
+  Connect with other FastMCP developers, share your projects, and discuss ideas.
+</Card>
+
+## Featured Projects
+
+Discover exemplary MCP servers and implementations created by our community. These projects demonstrate best practices and innovative uses of FastMCP.
+
+### Learning Resources
+
+<Card title="MCP Dummy Server" icon="graduation-cap" href="https://github.com/WaiYanNyeinNaing/mcp-dummy-server">
+  A comprehensive educational example demonstrating FastMCP best practices with professional dual-transport server implementation, interactive test client, and detailed documentation.
+</Card>
+
+#### Video Tutorials
+
+**Build Remote MCP Servers w/ Python & FastMCP** - Claude Integrations Tutorial by Greg + Code
+
+<YouTubeEmbed 
+  videoId="bOYkbXP-GGo" 
+  title="Build Remote MCP Servers w/ Python & FastMCP" 
+/>
+
+**FastMCP — the best way to build an MCP server with Python** - Tutorial by ZazenCodes
+
+<YouTubeEmbed 
+  videoId="rnljvmHorQw" 
+  title="FastMCP — the best way to build an MCP server with Python" 
+/>
+
+**Speedrun a MCP server for Claude Desktop (fastmcp)** - Tutorial by Nate from Prefect
+
+<YouTubeEmbed 
+  videoId="67ZwpkUEtSI" 
+  title="Speedrun a MCP server for Claude Desktop (fastmcp)" 
+/>
+
+### Community Examples
+
+Have you built something interesting with FastMCP? We'd love to feature high-quality examples here! Start a [discussion on GitHub](https://github.com/PrefectHQ/fastmcp/discussions) to share your project.
+
+## Contributing
+
+To get your project featured:
+
+1. Ensure your project demonstrates best practices
+2. Include comprehensive documentation
+3. Add clear usage examples
+4. Open a discussion in our [GitHub Discussions](https://github.com/PrefectHQ/fastmcp/discussions)
+
+We review submissions regularly and feature projects that provide value to the FastMCP community.
+
+## Further Reading
+
+- [Contrib Modules](/patterns/contrib) - Community-contributed modules that are distributed with FastMCP itself
\ No newline at end of file
diff --git a/docs/css/banner.css b/docs/css/banner.css
new file mode 100644
index 0000000..f9c6384
--- /dev/null
+++ b/docs/css/banner.css
@@ -0,0 +1,74 @@
+/* Banner styling -- improve readability with better contrast */
+#banner {
+  background: #f1f5f9 !important;
+  color: #1e293b !important;
+  font-size: 0.95rem !important;
+  font-weight: 600 !important;
+  padding-top: 12px !important;
+  padding-bottom: 12px !important;
+  overflow: hidden !important;
+}
+
+#banner::before {
+  content: "";
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  background: linear-gradient(
+    90deg,
+    rgba(6, 182, 212, 0.25) 0%,
+    rgba(6, 182, 212, 0.05) 25%,
+    rgba(6, 182, 212, 0.35) 50%,
+    rgba(6, 182, 212, 0.08) 75%,
+    rgba(6, 182, 212, 0.28) 100%
+  );
+  background-size: 300% 100%;
+  animation: colorWave 14s ease-in-out infinite alternate;
+  pointer-events: none;
+}
+
+.dark #banner {
+  background: #475569 !important;
+  color: #f1f5f9 !important;
+}
+
+.dark #banner::before {
+  background: linear-gradient(
+    90deg,
+    rgba(247, 37, 133, 0.35) 0%,
+    rgba(247, 37, 133, 0.08) 25%,
+    rgba(247, 37, 133, 0.45) 50%,
+    rgba(247, 37, 133, 0.12) 75%,
+    rgba(247, 37, 133, 0.38) 100%
+  );
+  background-size: 300% 100%;
+}
+
+@keyframes colorWave {
+  0% {
+    background-position: 0% 0%;
+  }
+  100% {
+    background-position: 100% 0%;
+  }
+}
+
+#banner * {
+  color: #1e293b !important;
+  margin: 0 !important;
+}
+
+.dark #banner * {
+  color: #f1f5f9 !important;
+}
+
+@media (max-width: 767px) {
+  #banner {
+    font-size: 0.8rem !important;
+    padding-top: 8px !important;
+    padding-bottom: 8px !important;
+  }
+}
+
diff --git a/docs/css/python-sdk.css b/docs/css/python-sdk.css
new file mode 100644
index 0000000..72a64c2
--- /dev/null
+++ b/docs/css/python-sdk.css
@@ -0,0 +1,3 @@
+a:has(svg.icon) {
+  border: none !important;
+}
\ No newline at end of file
diff --git a/docs/css/style.css b/docs/css/style.css
new file mode 100644
index 0000000..99844f6
--- /dev/null
+++ b/docs/css/style.css
@@ -0,0 +1,63 @@
+html:not([data-page-mode="wide"]) #content-area {
+  max-width: 44rem !important;
+}
+
+img.nav-logo {
+  max-width: 200px;
+}
+
+/* Code highlighting -- target only inline code elements, not code blocks */
+p code:not(pre code),
+table code:not(pre code),
+.prose code:not(pre code),
+li code:not(pre code),
+h1 code:not(pre code),
+h2 code:not(pre code),
+h3 code:not(pre code),
+h4 code:not(pre code),
+h5 code:not(pre code),
+h6 code:not(pre code) {
+  color: #f72585 !important;
+  background-color: rgba(247, 37, 133, 0.09);
+}
+
+/* V2 banner - inside content-container, breaks out of padding with negative margins */
+#v2-banner {
+  display: block;
+  background: linear-gradient(135deg, #4cc9f0 0%, #2d00f7 100%);
+  color: white;
+  text-align: center;
+  padding: 10px 16px;
+  font-size: 0.875rem;
+  font-weight: 600;
+  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+  margin: -2rem -2rem 1.5rem -2rem;
+  width: calc(100% + 4rem);
+  border-radius: 8px 8px 0 0;
+}
+
+#v2-banner a {
+  color: white;
+  text-decoration: underline;
+  font-weight: 700;
+}
+
+#v2-banner a:hover {
+  opacity: 0.9;
+}
+
+@media (min-width: 1024px) {
+  #v2-banner {
+    margin: -3rem -4rem 1.5rem -4rem;
+    width: calc(100% + 8rem);
+  }
+}
+
+.dark #v2-banner {
+  background: linear-gradient(135deg, #2d00f7 0%, #4cc9f0 100%);
+}
+
+
+
+
+
diff --git a/docs/css/version-badge.css b/docs/css/version-badge.css
new file mode 100644
index 0000000..20aa168
--- /dev/null
+++ b/docs/css/version-badge.css
@@ -0,0 +1,23 @@
+/* Version badge -- display a badge with the current version of the documentation */
+.version-badge {
+  --color-text: #ff5400 !important;
+  --color-bg: #fef2f2 !important;
+  color: #ff5400 !important;
+  background: #fef2f2 !important;
+  border: 1px solid rgba(220, 38, 38, 0.3) !important;
+  transition: box-shadow 0.2s, transform 0.15s;
+}
+
+.version-badge:hover {
+  box-shadow: 0 2px 8px 0 rgba(160, 132, 252, 0.1);
+  transform: translateY(-1px) scale(1.03);
+}
+
+.dark .version-badge {
+  --color-text: #f1f5f9 !important;
+  --color-bg: #334155 !important;
+  color: #f1f5f9 !important;
+  background: #334155 !important;
+  border: 1px solid #64748b !important;
+}
+
diff --git a/docs/deployment/http.mdx b/docs/deployment/http.mdx
new file mode 100644
index 0000000..16c9fad
--- /dev/null
+++ b/docs/deployment/http.mdx
@@ -0,0 +1,924 @@
+---
+title: HTTP Deployment
+sidebarTitle: HTTP Deployment
+description: Deploy your FastMCP server over HTTP for remote access
+icon: server
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+<Tip>
+STDIO transport is perfect for local development and desktop applications. But to unlock the full potential of MCP—centralized services, multi-client access, and network availability—you need remote HTTP deployment.
+</Tip>
+
+This guide walks you through deploying your FastMCP server as a remote MCP service that's accessible via a URL. Once deployed, your MCP server will be available over the network, allowing multiple clients to connect simultaneously and enabling integration with cloud-based LLM applications. This guide focuses specifically on remote MCP deployment, not local STDIO servers.
+
+## Choosing Your Approach
+
+FastMCP provides two ways to deploy your server as an HTTP service. Understanding the trade-offs helps you choose the right approach for your needs.
+
+The **direct HTTP server** approach is simpler and perfect for getting started quickly. You modify your server's `run()` method to use HTTP transport, and FastMCP handles all the web server configuration. This approach works well for standalone deployments where you want your MCP server to be the only service running on a port.
+
+The **ASGI application** approach gives you more control and flexibility. Instead of running the server directly, you create an ASGI application that can be served by Uvicorn. This approach is better when you need advanced server features like multiple workers, custom middleware, or when you're integrating with existing web applications.
+
+### Direct HTTP Server
+
+The simplest way to get your MCP server online is to use the built-in `run()` method with HTTP transport. This approach handles all the server configuration for you and is ideal when you want a standalone MCP server without additional complexity.
+
+```python server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP("My Server")
+
+@mcp.tool
+def process_data(input: str) -> str:
+    """Process data on the server"""
+    return f"Processed: {input}"
+
+if __name__ == "__main__":
+    mcp.run(transport="http", host="0.0.0.0", port=8000)
+```
+
+Run your server with a simple Python command:
+```bash
+python server.py
+```
+
+Your server is now accessible at `http://localhost:8000/mcp` (or use your server's actual IP address for remote access).
+
+This approach is ideal when you want to get online quickly with minimal configuration. It's perfect for internal tools, development environments, or simple deployments where you don't need advanced server features. The built-in server handles all the HTTP details, letting you focus on your MCP implementation.
+
+### ASGI Application
+
+For production deployments, you'll often want more control over how your server runs. FastMCP can create a standard ASGI application that works with any ASGI server like Uvicorn, Gunicorn, or Hypercorn. This approach is particularly useful when you need to configure advanced server options, run multiple workers, or integrate with existing infrastructure.
+
+```python app.py
+from fastmcp import FastMCP
+
+mcp = FastMCP("My Server")
+
+@mcp.tool
+def process_data(input: str) -> str:
+    """Process data on the server"""
+    return f"Processed: {input}"
+
+# Create ASGI application
+app = mcp.http_app()
+```
+
+Run with any ASGI server - here's an example with Uvicorn:
+```bash
+uvicorn app:app --host 0.0.0.0 --port 8000
+```
+
+Your server is accessible at the same URL: `http://localhost:8000/mcp` (or use your server's actual IP address for remote access).
+
+The ASGI approach shines in production environments where you need reliability and performance. You can run multiple worker processes to handle concurrent requests, add custom middleware for logging or monitoring, integrate with existing deployment pipelines, or mount your MCP server as part of a larger application.
+
+## Configuring Your Server
+
+### Custom Path
+
+By default, your MCP server is accessible at `/mcp/` on your domain. You can customize this path to fit your URL structure or avoid conflicts with existing endpoints. This is particularly useful when integrating MCP into an existing application or following specific API conventions.
+
+```python
+# Option 1: With mcp.run()
+mcp.run(transport="http", host="0.0.0.0", port=8000, path="/api/mcp/")
+
+# Option 2: With ASGI app
+app = mcp.http_app(path="/api/mcp/")
+```
+
+Now your server is accessible at `http://localhost:8000/api/mcp/`.
+
+### Authentication
+
+<Warning>
+Authentication is **highly recommended** for remote MCP servers. Some LLM clients require authentication for remote servers and will refuse to connect without it.
+</Warning>
+
+FastMCP supports multiple authentication methods to secure your remote server. See the [Authentication Overview](/servers/auth/authentication) for complete configuration options including Bearer tokens, JWT, and OAuth.
+
+If you're mounting an authenticated server under a path prefix, see [Mounting Authenticated Servers](#mounting-authenticated-servers) below for important routing considerations.
+
+### Host and Origin Protection
+
+FastMCP can validate `Host` and browser `Origin` headers for Streamable HTTP requests before they reach MCP session handling. This request guard protects localhost-bound servers from DNS rebinding attacks, and it remains opt-in in FastMCP 3.x to preserve compatibility with existing ASGI, serverless, and reverse-proxy deployments.
+
+Think of this as a request guard rather than CORS middleware. It decides whether a request can reach MCP session handling. CORS remains a separate browser response-header policy; configure CORS middleware separately when browser JavaScript must read cross-origin responses.
+
+Enable strict validation with `host_origin_protection=True`. When you deploy behind a public hostname, add the hostname clients use to reach your MCP endpoint. If a browser-based MCP client runs on a separate origin, add that origin as well:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("My Server")
+
+app = mcp.http_app(
+    host_origin_protection=True,
+    allowed_hosts=["mcp.example.com"],
+    allowed_origins=["https://app.example.com"],
+)
+```
+
+For the direct server approach, pass the same values to `run()`:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("My Server")
+
+if __name__ == "__main__":
+    mcp.run(
+        transport="http",
+        host="0.0.0.0",
+        port=8000,
+        host_origin_protection=True,
+        allowed_hosts=["mcp.example.com"],
+        allowed_origins=["https://app.example.com"],
+    )
+```
+
+You can also configure these values with environment variables:
+
+```bash
+export FASTMCP_HTTP_HOST_ORIGIN_PROTECTION=true
+export FASTMCP_HTTP_ALLOWED_HOSTS='["mcp.example.com"]'
+export FASTMCP_HTTP_ALLOWED_ORIGINS='["https://app.example.com"]'
+```
+
+Use `host_origin_protection="auto"` to protect localhost-bound direct servers while allowing ASGI, serverless, and reverse-proxy deployments to keep their existing Host handling unless they configure explicit trust rules. Use `host_origin_protection=False` to keep the request guard disabled.
+
+### Health Checks
+
+Health check endpoints are essential for monitoring your deployed server and ensuring it's responding correctly. FastMCP allows you to add custom routes alongside your MCP endpoints, making it easy to implement health checks that work with both deployment approaches.
+
+```python
+from starlette.responses import JSONResponse
+
+@mcp.custom_route("/health", methods=["GET"])
+async def health_check(request):
+    return JSONResponse({"status": "healthy", "service": "mcp-server"})
+```
+
+This health endpoint will be available at `http://localhost:8000/health` and can be used by load balancers, monitoring systems, or deployment platforms to verify your server is running.
+
+<Note>
+Custom routes are never protected by the server's authentication middleware, even when an `AuthProvider` is configured. This is by design — the primary use case for custom routes is unauthenticated operational endpoints like health checks and readiness probes. If you need authenticated HTTP endpoints alongside your MCP server, [mount it in a FastAPI app](/integrations/fastapi) and use FastAPI's `Depends()` for auth on your routes.
+</Note>
+
+### Custom Middleware
+
+
+<VersionBadge version="2.3.2" />
+
+Add custom Starlette middleware to your FastMCP ASGI apps:
+
+```python
+from fastmcp import FastMCP
+from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
+
+# Create your FastMCP server
+mcp = FastMCP("MyServer")
+
+# Define middleware
+middleware = [
+    Middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+]
+
+# Create ASGI app with middleware
+http_app = mcp.http_app(middleware=middleware)
+```
+
+### CORS for Browser-Based Clients
+
+<Tip>
+Most MCP clients, including those that you access through a browser like ChatGPT or Claude, don't need CORS configuration. Only enable CORS if you're working with an MCP client that connects directly from a browser, such as debugging tools or inspectors.
+</Tip>
+
+CORS (Cross-Origin Resource Sharing) is needed when JavaScript running in a web browser connects directly to your MCP server. This is different from using an LLM through a browser—in that case, the browser connects to the LLM service, and the LLM service connects to your MCP server (no CORS needed).
+
+Host and Origin protection runs before CORS when it is active for a request. Add browser client origins to `allowed_origins` so trusted browser requests reach the CORS middleware, then configure CORS to let browser JavaScript read the MCP response headers it needs. Setting `allowed_origins` trusts the request; it does not emit `Access-Control-Allow-Origin` or other CORS response headers.
+
+Browser-based MCP clients that need CORS include:
+
+- **MCP Inspector** - Browser-based debugging tool for testing MCP servers
+- **Custom browser-based MCP clients** - If you're building a web app that directly connects to MCP servers
+
+For these scenarios, add CORS middleware with the specific headers required for MCP protocol:
+
+```python
+from fastmcp import FastMCP
+from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
+
+mcp = FastMCP("MyServer")
+
+# Configure CORS for browser-based clients
+middleware = [
+    Middleware(
+        CORSMiddleware,
+        allow_origins=["*"],  # Allow all origins; use specific origins for security
+        allow_methods=["GET", "POST", "DELETE", "OPTIONS"],
+        allow_headers=[
+            "mcp-protocol-version",
+            "mcp-session-id",
+            "Authorization",
+            "Content-Type",
+        ],
+        expose_headers=["mcp-session-id"],
+    )
+]
+
+app = mcp.http_app(middleware=middleware)
+```
+
+**Key configuration details:**
+
+- **`allow_origins`**: Specify exact origins (e.g., `["http://localhost:3000"]`) rather than `["*"]` for production deployments
+- **`allow_headers`**: Must include `mcp-protocol-version`, `mcp-session-id`, and `Authorization` (for authenticated servers)
+- **`expose_headers`**: Must include `mcp-session-id` so JavaScript can read the session ID from responses and send it in subsequent requests
+
+Without `expose_headers=["mcp-session-id"]`, browsers will receive the session ID but JavaScript won't be able to access it, causing session management to fail.
+
+<Warning>
+**Production Security**: Never use `allow_origins=["*"]` in production. Specify the exact origins of your browser-based clients. Using wildcards exposes your server to unauthorized access from any website.
+</Warning>
+
+### SSE Polling for Long-Running Operations
+
+<VersionBadge version="2.14.0" />
+
+<Note>
+This feature only applies to the **StreamableHTTP transport** (the default for `http_app()`). It does not apply to the legacy SSE transport (`transport="sse"`).
+</Note>
+
+When running tools that take a long time to complete, you may encounter issues with load balancers or proxies terminating connections that stay idle too long. [SEP-1699](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1699) introduces SSE polling to solve this by allowing the server to gracefully close connections and have clients automatically reconnect.
+
+To enable SSE polling, configure an `EventStore` when creating your HTTP application:
+
+```python
+from fastmcp import FastMCP, Context
+from fastmcp.server.event_store import EventStore
+
+mcp = FastMCP("My Server")
+
+@mcp.tool
+async def long_running_task(ctx: Context) -> str:
+    """A task that takes several minutes to complete."""
+    for i in range(100):
+        await ctx.report_progress(i, 100)
+
+        # Periodically close the connection to avoid load balancer timeouts
+        # Client will automatically reconnect and resume receiving progress
+        if i % 30 == 0 and i > 0:
+            await ctx.close_sse_stream()
+
+        await do_expensive_work()
+
+    return "Done!"
+
+# Configure with EventStore for resumability
+event_store = EventStore()
+app = mcp.http_app(
+    event_store=event_store,
+    retry_interval=2000,  # Client reconnects after 2 seconds
+)
+```
+
+**How it works:**
+
+1. When `event_store` is configured, the server stores all events (progress updates, results) with unique IDs
+2. Calling `ctx.close_sse_stream()` gracefully closes the HTTP connection
+3. The client automatically reconnects with a `Last-Event-ID` header
+4. The server replays any events the client missed during the disconnection
+
+The `retry_interval` parameter (in milliseconds) controls how long clients wait before reconnecting. Choose a value that balances responsiveness with server load.
+
+<Note>
+`close_sse_stream()` is a no-op if called without an `EventStore` configured, so you can safely include it in tools that may run in different deployment configurations.
+</Note>
+
+#### Custom Storage Backends
+
+By default, `EventStore` uses in-memory storage. For production deployments with multiple server instances, you can provide a custom storage backend using the `key_value` package:
+
+```python
+from fastmcp.server.event_store import EventStore
+from key_value.aio.stores.redis import RedisStore
+
+# Use Redis for distributed deployments
+redis_store = RedisStore(url="redis://localhost:6379")
+event_store = EventStore(
+    storage=redis_store,
+    max_events_per_stream=100,  # Keep last 100 events per stream
+    ttl=3600,  # Events expire after 1 hour
+)
+
+app = mcp.http_app(event_store=event_store)
+```
+
+## Integration with Web Frameworks
+
+If you already have a web application running, you can add MCP capabilities by mounting a FastMCP server as a sub-application. This allows you to expose MCP tools alongside your existing API endpoints, sharing the same domain and infrastructure. The MCP server becomes just another route in your application, making it easy to manage and deploy.
+
+### Mounting in Starlette
+
+Mount your FastMCP server in a Starlette application:
+
+```python
+from fastmcp import FastMCP
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+# Create your FastMCP server
+mcp = FastMCP("MyServer")
+
+@mcp.tool
+def analyze(data: str) -> dict:
+    return {"result": f"Analyzed: {data}"}
+
+# Create the ASGI app
+mcp_app = mcp.http_app(path='/mcp')
+
+# Create a Starlette app and mount the MCP server
+app = Starlette(
+    routes=[
+        Mount("/mcp-server", app=mcp_app),
+        # Add other routes as needed
+    ],
+    lifespan=mcp_app.lifespan,
+)
+```
+
+The MCP endpoint will be available at `/mcp-server/mcp/` of the resulting Starlette app.
+
+<Warning>
+For Streamable HTTP transport, you **must** pass the lifespan context from the FastMCP app to the resulting Starlette app, as nested lifespans are not recognized. Otherwise, the FastMCP server's session manager will not be properly initialized.
+</Warning>
+
+#### Nested Mounts
+
+You can create complex routing structures by nesting mounts:
+
+```python
+from fastmcp import FastMCP
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+# Create your FastMCP server
+mcp = FastMCP("MyServer")
+
+# Create the ASGI app
+mcp_app = mcp.http_app(path='/mcp')
+
+# Create nested application structure
+inner_app = Starlette(routes=[Mount("/inner", app=mcp_app)])
+app = Starlette(
+    routes=[Mount("/outer", app=inner_app)],
+    lifespan=mcp_app.lifespan,
+)
+```
+
+In this setup, the MCP server is accessible at the `/outer/inner/mcp/` path.
+
+### FastAPI Integration
+
+For FastAPI-specific integration patterns including both mounting MCP servers into FastAPI apps and generating MCP servers from FastAPI apps, see the [FastAPI Integration guide](/integrations/fastapi).
+
+Here's a quick example showing how to add MCP to an existing FastAPI application:
+
+```python
+from fastapi import FastAPI
+from fastmcp import FastMCP
+
+# Create your MCP server
+mcp = FastMCP("API Tools")
+
+@mcp.tool
+def query_database(query: str) -> dict:
+    """Run a database query"""
+    return {"result": "data"}
+
+# Create the MCP ASGI app with path="/" since we'll mount at /mcp
+mcp_app = mcp.http_app(path="/")
+
+# Create FastAPI app with MCP lifespan (required for session management)
+api = FastAPI(lifespan=mcp_app.lifespan)
+
+@api.get("/api/status")
+def status():
+    return {"status": "ok"}
+
+# Mount MCP at /mcp
+api.mount("/mcp", mcp_app)
+
+# Run with: uvicorn app:api --host 0.0.0.0 --port 8000
+```
+
+Your existing API remains at `http://localhost:8000/api` while MCP is available at `http://localhost:8000/mcp`.
+
+<Warning>
+Just like with Starlette, you **must** pass the lifespan from the MCP app to FastAPI. Without this, the session manager won't initialize properly and requests will fail.
+</Warning>
+
+## Mounting Authenticated Servers
+
+<VersionBadge version="2.13.0" />
+
+<Tip>
+This section only applies if you're **mounting an OAuth-protected FastMCP server under a path prefix** (like `/api`) inside another application using `Mount()`.
+
+If you're deploying your FastMCP server at root level without any `Mount()` prefix, the well-known routes are automatically included in `mcp.http_app()` and you don't need to do anything special.
+</Tip>
+
+OAuth specifications (RFC 8414 and RFC 9728) require discovery metadata to be accessible at well-known paths under the root level of your domain. When you mount an OAuth-protected FastMCP server under a path prefix like `/api`, this creates a routing challenge: your operational OAuth endpoints move under the prefix, but discovery endpoints must remain at the root.
+
+<Warning>
+**Common Mistakes to Avoid:**
+
+1. **Forgetting to mount `.well-known` routes at root** - FastMCP cannot do this automatically when your server is mounted under a path prefix. You must explicitly mount well-known routes at the root level.
+
+2. **Including mount prefix in both base_url AND mcp_path** - The mount prefix (like `/api`) should only be in `base_url`, not in `mcp_path`. Otherwise you'll get double paths.
+
+   ✅ **Correct:**
+   ```python
+   base_url = "http://localhost:8000/api"
+   mcp_path = "/mcp"
+   # Result: /api/mcp
+   ```
+
+   ❌ **Wrong:**
+   ```python
+   base_url = "http://localhost:8000/api"
+   mcp_path = "/api/mcp"
+   # Result: /api/api/mcp (double prefix!)
+   ```
+
+Follow the configuration instructions below to set up mounting correctly.
+</Warning>
+
+<Warning>
+**CORS Middleware Conflicts:**
+
+If you're integrating FastMCP into an existing application with its own CORS middleware, be aware that layering CORS middleware can cause conflicts (such as 404 errors on `.well-known` routes or OPTIONS requests).
+
+FastMCP and the MCP SDK already handle CORS for OAuth routes. If you need CORS on your own application routes, consider using the sub-app pattern: mount FastMCP and your routes as separate apps, each with their own middleware, rather than adding application-wide CORS middleware.
+</Warning>
+
+### Route Types
+
+OAuth-protected MCP servers expose two categories of routes:
+
+**Operational routes** handle the OAuth flow and MCP protocol:
+- `/authorize` - OAuth authorization endpoint
+- `/token` - Token exchange endpoint
+- `/auth/callback` - OAuth callback handler
+- `/mcp` - MCP protocol endpoint
+
+**Discovery routes** provide metadata for OAuth clients:
+- `/.well-known/oauth-authorization-server` - Authorization server metadata
+- `/.well-known/oauth-protected-resource/*` - Protected resource metadata
+
+When you mount your MCP app under a prefix, operational routes move with it, but discovery routes must stay at root level for RFC compliance.
+
+### Configuration Parameters
+
+Three parameters control where routes are located and how they combine:
+
+**`base_url`** tells clients where to find operational endpoints. This includes any Starlette `Mount()` path prefix (e.g., `/api`):
+
+```python
+base_url="http://localhost:8000/api"  # Includes mount prefix
+```
+
+**`mcp_path`** is the internal FastMCP endpoint path, which gets appended to `base_url`:
+
+```python
+mcp_path="/mcp"  # Internal MCP path, NOT the mount prefix
+```
+
+**`issuer_url`** (optional) controls the authorization server identity for OAuth discovery. Defaults to `base_url`.
+
+```python
+# Usually not needed - just set base_url and it works
+issuer_url="http://localhost:8000"  # Only if you want root-level discovery
+```
+
+When `issuer_url` has a path (either explicitly or by defaulting from `base_url`), FastMCP creates path-aware discovery routes per RFC 8414. For example, if `base_url` is `http://localhost:8000/api`, the authorization server metadata will be at `/.well-known/oauth-authorization-server/api`.
+
+**Key Invariant:** `base_url + mcp_path = actual externally-accessible MCP URL`
+
+Example:
+- `base_url`: `http://localhost:8000/api` (mount prefix `/api`)
+- `mcp_path`: `/mcp` (internal path)
+- Result: `http://localhost:8000/api/mcp` (final MCP endpoint)
+
+Note that the mount prefix (`/api` from `Mount("/api", ...)`) goes in `base_url`, while `mcp_path` is just the internal MCP route. Don't include the mount prefix in both places or you'll get `/api/api/mcp`.
+
+### Mounting Strategy
+
+When mounting an OAuth-protected server under a path prefix, declare your URLs upfront to make the relationships clear:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.github import GitHubProvider
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+# Define the routing structure
+ROOT_URL = "http://localhost:8000"
+MOUNT_PREFIX = "/api"
+MCP_PATH = "/mcp"
+```
+
+Create the auth provider with `base_url`:
+
+```python
+auth = GitHubProvider(
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+    base_url=f"{ROOT_URL}{MOUNT_PREFIX}",  # Operational endpoints under prefix
+    # issuer_url defaults to base_url - path-aware discovery works automatically
+)
+```
+
+Create the MCP app, which generates operational routes at the specified path:
+
+```python
+mcp = FastMCP("Protected Server", auth=auth)
+mcp_app = mcp.http_app(path=MCP_PATH)
+```
+
+Retrieve the discovery routes from the auth provider. The `mcp_path` argument should match the path used when creating the MCP app:
+
+```python
+well_known_routes = auth.get_well_known_routes(mcp_path=MCP_PATH)
+```
+
+Finally, mount everything in the Starlette app with discovery routes at root and the MCP app under the prefix:
+
+```python
+app = Starlette(
+    routes=[
+        *well_known_routes,  # Discovery routes at root level
+        Mount(MOUNT_PREFIX, app=mcp_app),  # Operational routes under prefix
+    ],
+    lifespan=mcp_app.lifespan,
+)
+```
+
+This configuration produces the following URL structure:
+
+- MCP endpoint: `http://localhost:8000/api/mcp`
+- OAuth authorization: `http://localhost:8000/api/authorize`
+- OAuth callback: `http://localhost:8000/api/auth/callback`
+- Authorization server metadata: `http://localhost:8000/.well-known/oauth-authorization-server/api`
+- Protected resource metadata: `http://localhost:8000/.well-known/oauth-protected-resource/api/mcp`
+
+Both discovery endpoints use path-aware URLs per RFC 8414 and RFC 9728, matching the `base_url` path.
+
+### Complete Example
+
+Here's a complete working example showing all the pieces together:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.github import GitHubProvider
+from starlette.applications import Starlette
+from starlette.routing import Mount
+import uvicorn
+
+# Define routing structure
+ROOT_URL = "http://localhost:8000"
+MOUNT_PREFIX = "/api"
+MCP_PATH = "/mcp"
+
+# Create OAuth provider
+auth = GitHubProvider(
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+    base_url=f"{ROOT_URL}{MOUNT_PREFIX}",
+    # issuer_url defaults to base_url - path-aware discovery works automatically
+)
+
+# Create MCP server
+mcp = FastMCP("Protected Server", auth=auth)
+
+@mcp.tool
+def analyze(data: str) -> dict:
+    return {"result": f"Analyzed: {data}"}
+
+# Create MCP app
+mcp_app = mcp.http_app(path=MCP_PATH)
+
+# Get discovery routes for root level
+well_known_routes = auth.get_well_known_routes(mcp_path=MCP_PATH)
+
+# Assemble the application
+app = Starlette(
+    routes=[
+        *well_known_routes,
+        Mount(MOUNT_PREFIX, app=mcp_app),
+    ],
+    lifespan=mcp_app.lifespan,
+)
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+For more details on OAuth authentication, see the [Authentication guide](/servers/auth/authentication).
+
+## Production Deployment
+
+### Running with Uvicorn
+
+When deploying to production, you'll want to optimize your server for performance and reliability. Uvicorn provides several options to improve your server's capabilities:
+
+```bash
+# Run with basic configuration
+uvicorn app:app --host 0.0.0.0 --port 8000
+
+# Run with multiple workers for production (requires stateless mode - see below)
+uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4
+```
+
+### Horizontal Scaling
+
+<VersionBadge version="2.10.2" />
+
+When deploying FastMCP behind a load balancer or running multiple server instances, you need to understand how the HTTP transport handles sessions and configure your server appropriately.
+
+#### Understanding Sessions
+
+By default, FastMCP's Streamable HTTP transport maintains server-side sessions. Sessions enable stateful MCP features like [elicitation](/servers/elicitation) and [sampling](/servers/sampling), where the server needs to maintain context across multiple requests from the same client.
+
+This works perfectly for single-instance deployments. However, sessions are stored in memory on each server instance, which creates challenges when scaling horizontally.
+
+#### Without Stateless Mode
+
+When running multiple server instances behind a load balancer (Traefik, nginx, HAProxy, Kubernetes, etc.), requests from the same client may be routed to different instances:
+
+1. Client connects to Instance A → session created on Instance A
+2. Next request routes to Instance B → session doesn't exist → **request fails**
+
+You might expect sticky sessions (session affinity) to solve this, but they don't work reliably with MCP clients.
+
+<Warning>
+**Why sticky sessions don't work:** Most MCP clients—including Cursor and Claude Code—use `fetch()` internally and don't properly forward `Set-Cookie` headers. Without cookies, load balancers can't identify which instance should handle subsequent requests. This is a limitation in how these clients implement HTTP, not something you can fix with load balancer configuration.
+</Warning>
+
+#### Enabling Stateless Mode
+
+For horizontally scaled deployments, enable stateless HTTP mode. In stateless mode, each request creates a fresh transport context, eliminating the need for session affinity entirely.
+
+**Option 1: Via `http_app()`**
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("My Server")
+
+@mcp.tool
+def process(data: str) -> str:
+    return f"Processed: {data}"
+
+app = mcp.http_app(stateless_http=True)
+```
+
+**Option 2: Via `run()`**
+
+```python
+if __name__ == "__main__":
+    mcp.run(transport="http", stateless_http=True)
+```
+
+**Option 3: Via environment variable**
+
+```bash
+FASTMCP_STATELESS_HTTP=true uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4
+```
+
+### Environment Variables
+
+Production deployments should never hardcode sensitive information like API keys or authentication tokens. Instead, use environment variables to configure your server at runtime. This keeps your code secure and makes it easy to deploy the same code to different environments with different configurations.
+
+Here's an example using static token authentication for development (OAuth is recommended for production):
+
+```python
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth import StaticTokenVerifier
+
+# Read configuration from environment
+auth_token = os.environ.get("MCP_AUTH_TOKEN")
+if auth_token:
+    auth = StaticTokenVerifier(tokens={auth_token: {"sub": "admin", "client_id": "cli"}})
+    mcp = FastMCP("Production Server", auth=auth)
+else:
+    mcp = FastMCP("Production Server")
+
+app = mcp.http_app()
+```
+
+Deploy with your secrets safely stored in environment variables:
+```bash
+MCP_AUTH_TOKEN=secret uvicorn app:app --host 0.0.0.0 --port 8000
+```
+
+### OAuth Token Security
+
+<VersionBadge version="2.13.0" />
+
+If you're using the [OAuth Proxy](/servers/auth/oauth-proxy), FastMCP issues its own JWT tokens to clients instead of forwarding upstream provider tokens. This maintains proper OAuth 2.0 token boundaries.
+
+**Default Behavior (Development Only):**
+
+By default, FastMCP automatically manages cryptographic keys:
+- **Mac/Windows**: Keys are generated and stored in your system keyring, surviving server restarts. Suitable **only** for development and local testing.
+- **Linux**: Keys are ephemeral (random salt at startup), so tokens are invalidated on restart.
+
+This automatic approach is convenient for development but not suitable for production deployments.
+
+**For Production:**
+
+Production requires explicit key management to ensure tokens survive restarts and can be shared across multiple server instances. This requires the following two things working together:
+
+1. **Explicit JWT signing key** for signing tokens issued to clients
+3. **Persistent network-accessible storage** for upstream tokens (wrapped in `FernetEncryptionWrapper` to encrypt sensitive data at rest)
+
+**Configuration:**
+
+Add two parameters to your auth provider:
+
+```python {8-12}
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+auth = GitHubProvider(
+    client_id=os.environ["GITHUB_CLIENT_ID"],
+    client_secret=os.environ["GITHUB_CLIENT_SECRET"],
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(host="redis.example.com", port=6379),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    ),
+    base_url="https://your-server.com"  # use HTTPS
+)
+```
+
+Both parameters are required for production. Without an explicit signing key, keys are signed using a key derived from the client_secret, which will cause invalidation upon rotation of the client secret. Without persistent storage, tokens are local to the server and won't be trusted across hosts. **Wrap your storage backend in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without encryption, tokens are stored in plaintext.
+
+For more details on the token architecture and key management, see [OAuth Proxy Key and Storage Management](/servers/auth/oauth-proxy#key-and-storage-management).
+
+## Reverse Proxy (nginx)
+
+In production, you'll typically run your FastMCP server behind a reverse proxy like nginx. A reverse proxy provides TLS termination, domain-based routing, static file serving, and an additional layer of security between the internet and your application.
+
+### Running FastMCP as a Linux Service
+
+Before configuring nginx, you need your FastMCP server running as a background service. A systemd unit file ensures your server starts automatically and restarts on failure.
+
+Create a file at `/etc/systemd/system/fastmcp.service`:
+
+```ini
+[Unit]
+Description=FastMCP Server
+After=network.target
+
+[Service]
+User=www-data
+Group=www-data
+WorkingDirectory=/opt/fastmcp
+ExecStart=/opt/fastmcp/.venv/bin/uvicorn app:app --host 127.0.0.1 --port 8000
+Restart=always
+RestartSec=5
+Environment="PATH=/opt/fastmcp/.venv/bin"
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start the service:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable fastmcp
+sudo systemctl start fastmcp
+```
+
+This assumes your ASGI application is in `/opt/fastmcp/app.py` with a virtual environment at `/opt/fastmcp/.venv`. Adjust paths to match your deployment layout.
+
+### nginx Configuration
+
+FastMCP's Streamable HTTP transport uses Server-Sent Events (SSE) for streaming responses. This requires specific nginx settings to prevent buffering from breaking the event stream.
+
+Create a site configuration at `/etc/nginx/sites-available/fastmcp`:
+
+```nginx
+server {
+    listen 80;
+    server_name mcp.example.com;
+
+    # Redirect HTTP to HTTPS
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl;
+    server_name mcp.example.com;
+
+    ssl_certificate /etc/letsencrypt/live/mcp.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/mcp.example.com/privkey.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Connection '';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # Required for SSE (Server-Sent Events) streaming
+        proxy_buffering off;
+        proxy_cache off;
+
+        # Allow long-lived connections for streaming responses
+        proxy_read_timeout 300s;
+        proxy_send_timeout 300s;
+    }
+}
+```
+
+Enable the site and reload nginx:
+
+```bash
+sudo ln -s /etc/nginx/sites-available/fastmcp /etc/nginx/sites-enabled/
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+Your FastMCP server is now accessible at `https://mcp.example.com/mcp`.
+
+<Warning>
+**SSE buffering is the most common issue.** If clients connect but never receive streaming responses (progress updates, tool results), verify that `proxy_buffering off` is set. Without it, nginx buffers the entire SSE stream and delivers it only when the connection closes, which breaks real-time communication.
+</Warning>
+
+### Key Considerations
+
+When deploying FastMCP behind a reverse proxy, keep these points in mind:
+
+- **Disable buffering**: SSE requires `proxy_buffering off` so events reach clients immediately. This is the single most important setting.
+- **Increase timeouts**: The default nginx `proxy_read_timeout` is 60 seconds. Long-running MCP tools will cause the connection to drop. Set timeouts to at least 300 seconds, or higher if your tools run longer. For tools that may exceed any timeout, use [SSE Polling](#sse-polling-for-long-running-operations) to gracefully handle proxy disconnections.
+- **Use HTTP/1.1**: Set `proxy_http_version 1.1` and `proxy_set_header Connection ''` to enable keep-alive connections between nginx and your server. Clearing the `Connection` header prevents clients from sending `Connection: close` to your upstream, which would break SSE streams. Both settings are required for proper SSE support.
+- **Forward headers**: Pass `X-Forwarded-For` and `X-Forwarded-Proto` so your FastMCP server can determine the real client IP and protocol. This is important for logging and for OAuth redirect URLs.
+- **TLS termination**: Let nginx handle TLS certificates (e.g., via Let's Encrypt with Certbot). Your FastMCP server can then run on plain HTTP internally.
+
+### Mounting Under a Path Prefix
+
+If you want your MCP server available at a subpath like `https://example.com/api/mcp` instead of at the root domain, adjust the nginx `location` block:
+
+```nginx
+location /api/ {
+    proxy_pass http://127.0.0.1:8000/;
+    proxy_http_version 1.1;
+    proxy_set_header Connection '';
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+
+    # Required for SSE streaming
+    proxy_buffering off;
+    proxy_cache off;
+    proxy_read_timeout 300s;
+    proxy_send_timeout 300s;
+}
+```
+
+Note the trailing `/` on both `location /api/` and `proxy_pass http://127.0.0.1:8000/` — this ensures nginx strips the `/api` prefix before forwarding to your server. If you're using OAuth authentication with a mount prefix, see [Mounting Authenticated Servers](#mounting-authenticated-servers) for additional configuration.
+
+## Testing Your Deployment
+
+Once your server is deployed, you'll need to verify it's accessible and functioning correctly. For comprehensive testing strategies including connectivity tests, client testing, and authentication testing, see the [Testing Your Server](/development/tests) guide.
+
+## Hosting Your Server
+
+This guide has shown you how to create an HTTP-accessible MCP server, but you'll still need a hosting provider to make it available on the internet. Your FastMCP server can run anywhere that supports Python web applications:
+
+- **Cloud VMs** (AWS EC2, Google Compute Engine, Azure VMs)
+- **Container platforms** (Cloud Run, Container Instances, ECS)  
+- **Platform-as-a-Service** (Railway, Render, Vercel)
+- **Edge platforms** (Cloudflare Workers)
+- **Kubernetes clusters** (self-managed or managed)
+
+The key requirements are Python 3.10+ support and the ability to expose an HTTP port. Most providers will require you to package your server (requirements.txt, Dockerfile, etc.) according to their deployment format. For managed, zero-configuration deployment, see [Prefect Horizon](/deployment/prefect-horizon).
diff --git a/docs/deployment/prefect-horizon.mdx b/docs/deployment/prefect-horizon.mdx
new file mode 100644
index 0000000..b226441
--- /dev/null
+++ b/docs/deployment/prefect-horizon.mdx
@@ -0,0 +1,120 @@
+---
+title: Prefect Horizon
+sidebarTitle: Prefect Horizon
+description: The MCP platform from the FastMCP team
+icon: cloud
+---
+
+[Prefect Horizon](https://www.prefect.io/horizon) is a platform for deploying and managing MCP servers. Built by the FastMCP team at [Prefect](https://www.prefect.io), Horizon provides managed hosting, authentication, access control, and a registry of MCP capabilities.
+
+Horizon includes a **free personal tier for FastMCP users**, making it the fastest way to get a secure, production-ready server URL with built-in OAuth authentication.
+
+<Info>
+Horizon is free for personal projects. Enterprise governance features are available for teams deploying to thousands of users.
+</Info>
+
+## The Platform
+
+Horizon is organized into four integrated pillars:
+
+- **Deploy**: Managed hosting with CI/CD, scaling, monitoring, and rollbacks. Push code and get a live, governed endpoint in 60 seconds.
+- **Registry**: A central catalog of MCP servers across your organization—first-party, third-party, and curated remix servers composed from multiple sources.
+- **Gateway**: Role-based access control, authentication, and audit logs. Define what agents can see and do at the tool level.
+- **Agents**: A permissioned chat interface for interacting with any MCP server or curated combination of servers.
+
+This guide focuses on **Horizon Deploy**, the managed hosting layer that gives you the fastest path from a FastMCP server to a production URL.
+
+## Prerequisites
+
+To use Horizon, you'll need a [GitHub](https://github.com) account and a GitHub repo containing a FastMCP server. If you don't have one yet, Horizon can create a starter repo for you during onboarding.
+
+Your repo can be public or private, but must include at least a Python file containing a FastMCP server instance.
+
+<Tip>
+To verify your file is compatible with Horizon, run `fastmcp inspect <file.py:server_object>` to see what Horizon will see when it runs your server.
+</Tip>
+
+If you have a `requirements.txt` or `pyproject.toml` in the repo, Horizon will automatically detect your server's dependencies and install them. Your file *can* have an `if __name__ == "__main__"` block, but it will be ignored by Horizon.
+
+For example, a minimal server file might look like:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")
+
+@mcp.tool
+def hello(name: str) -> str:
+    return f"Hello, {name}!"
+```
+
+## Getting Started
+
+There are just three steps to deploying a server to Horizon:
+
+### Step 1: Select a Repository
+
+Visit [horizon.prefect.io](https://horizon.prefect.io?utm_source=gofastmcp&utm_medium=docs) and sign in with your GitHub account. Connect your GitHub account to grant Horizon access to your repositories, then select the repo you want to deploy.
+
+<img src="/assets/images/horizon/select-repo.png" alt="Horizon repository selection" />
+
+### Step 2: Configure Your Server
+
+Next, you'll configure how Horizon should build and deploy your server.
+
+<img src="/assets/images/horizon/configure-server.png" alt="Horizon server configuration" />
+
+The configuration screen lets you specify:
+- **Server name**: A unique name for your server. This determines your server's URL.
+- **Description**: A brief description of what your server does.
+- **Entrypoint**: The Python file containing your FastMCP server (e.g., `main.py`). This field has the same syntax as the `fastmcp run` command—use `main.py:mcp` to specify a specific object in the file.
+- **Authentication**: When enabled, only authenticated users in your organization can connect. Horizon handles all the OAuth complexity for you.
+
+Horizon will automatically detect your server's Python dependencies from either a `requirements.txt` or `pyproject.toml` file.
+
+### Step 3: Deploy and Connect
+
+Click **Deploy Server** and Horizon will clone your repository, build your server, and deploy it to a unique URL—typically in under 60 seconds.
+
+<img src="/assets/images/horizon/deployment-live.png" alt="Horizon deployment view showing live server" />
+
+Once deployed, your server is accessible at a URL like:
+
+```
+https://your-server-name.fastmcp.app/mcp
+```
+
+Horizon monitors your repo and redeploys automatically whenever you push to `main`. It also builds preview deployments for every PR, so you can test changes before they go live.
+
+## Testing Your Server
+
+Horizon provides two ways to verify your server is working before connecting external clients.
+
+### Inspector
+
+The Inspector gives you a structured view of everything your server exposes—tools, resources, and prompts. You can click any tool, fill in the inputs, execute it, and see the output. This is useful for systematically validating each capability and debugging specific behaviors.
+
+### ChatMCP
+
+For quick end-to-end testing, ChatMCP lets you interact with your server conversationally. It uses a fast model optimized for rapid iteration—you can verify the server works, test tool calls in context, and confirm the overall behavior before sharing it with others.
+
+<img src="/assets/images/horizon/chat.png" alt="Horizon ChatMCP interface" />
+
+ChatMCP is designed for testing, not as a daily work environment. Once you've confirmed your server works, you can copy connection snippets for Claude Desktop, Cursor, Claude Code, and other MCP clients—or use the FastMCP client library to connect programmatically.
+
+## Horizon Agents
+
+Beyond testing individual servers, Horizon lets you create **Agents**—chat interfaces backed by one or more MCP servers. While ChatMCP tests a single server, Agents let you compose capabilities from multiple servers into a unified experience.
+
+<img src="/assets/images/horizon/agent-detail.png" alt="Horizon Agent configuration" />
+
+To create an agent:
+1. Navigate to **Agents** in the sidebar
+2. Click **Create Agent** and give it a name and description
+3. Add MCP servers to the agent—these can be servers you've deployed to Horizon or external servers in the registry
+
+Once configured, you can chat with your agent directly in Horizon:
+
+<img src="/assets/images/horizon/agent-chat.png" alt="Chatting with a Horizon Agent" />
+
+Agents are useful for creating purpose-built interfaces that combine tools from different servers. For example, you might create an agent that has access to both your company's internal data server and a general-purpose utilities server.
diff --git a/docs/deployment/running-server.mdx b/docs/deployment/running-server.mdx
new file mode 100644
index 0000000..c108553
--- /dev/null
+++ b/docs/deployment/running-server.mdx
@@ -0,0 +1,286 @@
+---
+title: Running Your Server
+sidebarTitle: Running Your Server
+description: Learn how to run your FastMCP server locally for development and testing
+icon: circle-play
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+FastMCP servers can be run in different ways depending on your needs. This guide focuses on running servers locally for development and testing. For production deployment to a URL, see the [HTTP Deployment](/deployment/http) guide.
+
+## The `run()` Method
+
+Every FastMCP server needs to be started to accept connections. The simplest way to run a server is by calling the `run()` method on your FastMCP instance. This method starts the server and blocks until it's stopped, handling all the connection management for you.
+
+<Tip>
+For maximum compatibility, it's best practice to place the `run()` call within an `if __name__ == "__main__":` block. This ensures the server starts only when the script is executed directly, not when imported as a module.
+</Tip>
+
+```python {9-10} my_server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="MyServer")
+
+@mcp.tool
+def hello(name: str) -> str:
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+You can now run this MCP server by executing `python my_server.py`.
+
+## Transport Protocols
+
+MCP servers communicate with clients through different transport protocols. Think of transports as the "language" your server speaks to communicate with clients. FastMCP supports three main transport protocols, each designed for specific use cases and deployment scenarios.
+
+The choice of transport determines how clients connect to your server, what network capabilities are available, and how many clients can connect simultaneously. Understanding these transports helps you choose the right approach for your application.
+
+### STDIO Transport (Default)
+
+STDIO (Standard Input/Output) is the default transport for FastMCP servers. When you call `run()` without arguments, your server uses STDIO transport. This transport communicates through standard input and output streams, making it perfect for command-line tools and desktop applications like Claude Desktop.
+
+With STDIO transport, the client spawns a new server process for each session and manages its lifecycle. The server reads MCP messages from stdin and writes responses to stdout. This is why STDIO servers don't stay running - they're started on-demand by the client.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")
+
+@mcp.tool
+def hello(name: str) -> str:
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    mcp.run()  # Uses STDIO transport by default
+```
+
+STDIO is ideal for:
+- Local development and testing
+- Claude Desktop integration
+- Command-line tools
+- Single-user applications
+
+### HTTP Transport (Streamable)
+
+HTTP transport turns your MCP server into a web service accessible via a URL. This transport uses the Streamable HTTP protocol, which allows clients to connect over the network. Unlike STDIO where each client gets its own process, an HTTP server can handle multiple clients simultaneously.
+
+The Streamable HTTP protocol provides full bidirectional communication between client and server, supporting all MCP operations including streaming responses. This makes it the recommended choice for network-based deployments.
+
+To use HTTP transport, specify it in the `run()` method along with networking options:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")
+
+@mcp.tool
+def hello(name: str) -> str:
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    # Start an HTTP server on port 8000
+    mcp.run(transport="http", host="127.0.0.1", port=8000)
+```
+
+Your server is now accessible at `http://localhost:8000/mcp`. This URL is the MCP endpoint that clients will connect to. HTTP transport enables:
+- Network accessibility
+- Multiple concurrent clients
+- Integration with web infrastructure
+- Remote deployment capabilities
+
+For production HTTP deployment with authentication and advanced configuration, see the [HTTP Deployment](/deployment/http) guide.
+
+### SSE Transport (Legacy)
+
+Server-Sent Events (SSE) transport was the original HTTP-based transport for MCP. While still supported for backward compatibility, it has limitations compared to the newer Streamable HTTP transport. SSE only supports server-to-client streaming, making it less efficient for bidirectional communication.
+
+```python
+if __name__ == "__main__":
+    # SSE transport - use HTTP instead for new projects
+    mcp.run(transport="sse", host="127.0.0.1", port=8000)
+```
+
+We recommend using HTTP transport instead of SSE for all new projects. SSE remains available only for compatibility with older clients that haven't upgraded to Streamable HTTP.
+
+### Choosing the Right Transport
+
+Each transport serves different needs. STDIO is perfect when you need simple, local execution - it's what Claude Desktop and most command-line tools expect. HTTP transport is essential when you need network access, want to serve multiple clients, or plan to deploy your server remotely. SSE exists only for backward compatibility and shouldn't be used in new projects.
+
+Consider your deployment scenario: Are you building a tool for local use? STDIO is your best choice. Need a centralized service that multiple clients can access? HTTP transport is the way to go.
+
+## The FastMCP CLI
+
+FastMCP provides a powerful command-line interface for running servers without modifying the source code. The CLI can automatically find and run your server with different transports, manage dependencies, and handle development workflows:
+
+```bash
+fastmcp run server.py
+```
+
+The CLI automatically finds a FastMCP instance in your file (named `mcp`, `server`, or `app`) and runs it with the specified options. This is particularly useful for testing different transports or configurations without changing your code.
+
+### Dependency Management
+
+The CLI integrates with `uv` to manage Python environments and dependencies:
+
+```bash
+# Run with a specific Python version
+fastmcp run server.py --python 3.11
+
+# Run with additional packages
+fastmcp run server.py --with pandas --with numpy
+
+# Run with dependencies from a requirements file
+fastmcp run server.py --with-requirements requirements.txt
+
+# Combine multiple options
+fastmcp run server.py --python 3.10 --with httpx --transport http
+
+# Run within a specific project directory
+fastmcp run server.py --project /path/to/project
+```
+
+<Note>
+When using `--python`, `--with`, `--project`, or `--with-requirements`, the server runs via `uv run` subprocess instead of using your local environment.
+</Note>
+
+### Passing Arguments to Servers
+
+When servers accept command line arguments (using argparse, click, or other libraries), you can pass them after `--`:
+
+```bash
+fastmcp run config_server.py -- --config config.json
+fastmcp run database_server.py -- --database-path /tmp/db.sqlite --debug
+```
+
+This is useful for servers that need configuration files, database paths, API keys, or other runtime options.
+
+For more CLI features including development mode with the MCP Inspector, see the [CLI documentation](/cli/running).
+
+### Auto-Reload for Development
+
+<VersionBadge version="3.0.0" />
+
+During development, you can use the `--reload` flag to automatically restart your server when source files change:
+
+```bash
+fastmcp run server.py --reload
+```
+
+The server watches for changes to Python files in the current directory and restarts automatically when you save changes. This provides a fast feedback loop during development without manually stopping and starting the server.
+
+```bash
+# Watch specific directories for changes
+fastmcp run server.py --reload --reload-dir ./src --reload-dir ./lib
+
+# Combine with other options
+fastmcp run server.py --reload --transport http --port 8080
+```
+
+<Note>
+Auto-reload uses stateless mode to enable seamless restarts. For stdio transport, this is fully featured. For HTTP transport, some bidirectional features like elicitation are not available during reload mode.
+</Note>
+
+SSE transport does not support auto-reload due to session limitations. Use HTTP transport instead if you need both network access and auto-reload.
+
+### Async Usage
+
+FastMCP servers are built on async Python, but the framework provides both synchronous and asynchronous APIs to fit your application's needs. The `run()` method we've been using is actually a synchronous wrapper around the async server implementation.
+
+For applications that are already running in an async context, FastMCP provides the `run_async()` method:
+
+```python {10-12}
+from fastmcp import FastMCP
+import asyncio
+
+mcp = FastMCP(name="MyServer")
+
+@mcp.tool
+def hello(name: str) -> str:
+    return f"Hello, {name}!"
+
+async def main():
+    # Use run_async() in async contexts
+    await mcp.run_async(transport="http", port=8000)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+<Warning>
+The `run()` method cannot be called from inside an async function because it creates its own async event loop internally. If you attempt to call `run()` from inside an async function, you'll get an error about the event loop already running.
+
+Always use `run_async()` inside async functions and `run()` in synchronous contexts.
+</Warning>
+
+Both `run()` and `run_async()` accept the same transport arguments, so all the examples above apply to both methods.
+
+## Custom Routes
+
+When using HTTP transport, you might want to add custom web endpoints alongside your MCP server. This is useful for health checks, status pages, or simple APIs. FastMCP lets you add custom routes using the `@custom_route` decorator:
+
+```python
+from fastmcp import FastMCP
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+
+mcp = FastMCP("MyServer")
+
+@mcp.custom_route("/health", methods=["GET"])
+async def health_check(request: Request) -> PlainTextResponse:
+    return PlainTextResponse("OK")
+
+@mcp.tool
+def process(data: str) -> str:
+    return f"Processed: {data}"
+
+if __name__ == "__main__":
+    mcp.run(transport="http")  # Health check at http://localhost:8000/health
+```
+
+Custom routes are served by the same web server as your MCP endpoint. They're available at the root of your domain while the MCP endpoint is at `/mcp/`. For more complex web applications, consider [mounting your MCP server into a FastAPI or Starlette app](/deployment/http#integration-with-web-frameworks).
+
+## Alternative Initialization Patterns
+
+The `if __name__ == "__main__"` pattern works well for standalone scripts, but some deployment scenarios require different approaches. FastMCP handles these cases automatically.
+
+### CLI-Only Servers
+
+When using the FastMCP CLI, you don't need the `if __name__` block at all. The CLI will find your FastMCP instance and run it:
+
+```python
+# server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")  # CLI looks for 'mcp', 'server', or 'app'
+
+@mcp.tool
+def process(data: str) -> str:
+    return f"Processed: {data}"
+
+# No if __name__ block needed - CLI will find and run 'mcp'
+```
+
+### ASGI Applications
+
+For ASGI deployment (running with Uvicorn or similar), you'll want to create an ASGI application object. This approach is common in production deployments where you need more control over the server configuration:
+
+```python
+# app.py
+from fastmcp import FastMCP
+
+def create_app():
+    mcp = FastMCP("MyServer")
+    
+    @mcp.tool
+    def process(data: str) -> str:
+        return f"Processed: {data}"
+    
+    return mcp.http_app()
+
+app = create_app()  # Uvicorn will use this
+```
+
+See the [HTTP Deployment](/deployment/http) guide for more ASGI deployment patterns.
\ No newline at end of file
diff --git a/docs/deployment/sandboxed-agents.mdx b/docs/deployment/sandboxed-agents.mdx
new file mode 100644
index 0000000..16191af
--- /dev/null
+++ b/docs/deployment/sandboxed-agents.mdx
@@ -0,0 +1,262 @@
+---
+title: Sandboxed Agents
+sidebarTitle: Sandboxed Agents
+description: Expose MCP tools to isolated agents without giving the sandbox long-lived credentials.
+icon: box-open
+---
+
+This guide is for deployments where an agent runs inside an isolated container, subprocess, or remote worker and still needs MCP access. In that setup, the sandbox itself becomes part of your trust boundary.
+
+The core recommendation is simple: use FastMCP as the capability boundary. Run a remote FastMCP server, authenticate the sandbox with short-lived scoped credentials, and keep privileged credentials on the server side.
+
+## When to Use This Pattern
+
+This pattern is useful when:
+
+- your agent runs in an ephemeral container or subprocess
+- you do not want long-lived credentials inside that sandbox
+- you need per-run, per-tenant, or per-job scoping
+- the sandbox must call internal APIs, databases, or upstream MCP servers indirectly
+
+If you are building a local desktop integration, STDIO and normal local configuration may be enough. This guide is for cases where the sandbox is isolated enough that secret distribution, credential lifetimes, and privilege boundaries become part of the design.
+
+## What Changes in a Sandboxed Deployment
+
+A desktop MCP client usually runs on a developer's machine and launches local servers with configuration the developer controls. A sandboxed agent is different:
+
+- It often runs in an ephemeral container or subprocess.
+- Its filesystem may be inspected after the fact.
+- Its environment variables may be broader than you intend.
+- You may launch many sandboxes concurrently for different users, tenants, or jobs.
+
+That means convenience patterns that are acceptable locally become risky in sandboxes. Passing a GitHub token, database password, or cloud credentials directly into the sandbox creates a secret distribution problem you do not need to have.
+
+The safer approach is to make your FastMCP server the only component with privileged access and let the sandbox call it over MCP.
+
+## Recommended Architecture
+
+Use this shape by default:
+
+```mermaid
+flowchart LR
+    A["Sandboxed agent"] -->|"short-lived token"| B["FastMCP server"]
+    B --> C["internal APIs"]
+    B --> D["databases"]
+    B --> E["other MCP servers"]
+```
+
+The sandbox gets:
+
+- the MCP server URL
+- a short-lived token scoped to its job, tenant, or run
+- no long-lived upstream credentials
+
+The FastMCP server does the privileged work:
+
+- verifies the sandbox token
+- authorizes the request from token claims, scopes, or other server-side policy
+- exposes only the tools that sandbox should see
+- talks to internal APIs, databases, or upstream MCP servers on the sandbox's behalf
+
+The key design rule is simple:
+
+<Tip>
+Give the sandbox capabilities, not credentials.
+</Tip>
+
+With that boundary in place, the next questions are how the sandbox connects, how the server verifies and authorizes it, and how you design the tools the sandbox is allowed to call.
+
+## Prefer HTTP for Sandboxed Agents
+
+For sandboxes, prefer a remote HTTP server over a local STDIO server.
+
+STDIO is still excellent for local development, but a remote HTTP server is usually the better production boundary for sandboxed agents because:
+
+- authentication is explicit
+- the server lifecycle is independent from the sandbox lifecycle
+- secrets stay on the server
+- one deployment can safely serve many sandboxes
+- auditing and revocation happen in one place
+
+This means the sandbox should connect as a client:
+
+```python
+from fastmcp import Client
+from fastmcp.client.auth import BearerAuth
+
+client = Client(
+    "https://sandbox-tools.example.com/mcp",
+    auth=BearerAuth("short-lived-sandbox-token"),
+)
+```
+
+And your FastMCP server should run remotely:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("Sandbox Tools")
+
+if __name__ == "__main__":
+    mcp.run(transport="http", host="0.0.0.0", port=8000)
+```
+
+For production transport setup, see [HTTP Deployment](/deployment/http).
+
+## Use Short-Lived, Scoped Credentials
+
+For sandboxed agents, it is usually cleaner to issue credentials for the sandbox session than to place long-lived upstream credentials directly inside the container.
+
+In practice, that usually means issuing a short-lived bearer token for each sandbox, run, or tenant and validating it on your FastMCP server with a token verifier.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+auth = JWTVerifier(
+    jwks_uri="https://auth.example.com/.well-known/jwks.json",
+    issuer="https://auth.example.com",
+    audience="sandbox-mcp",
+)
+
+mcp = FastMCP("Sandbox Tools", auth=auth)
+```
+
+The token should identify the sandbox's scope. Depending on your system, it may represent a job, a tenant, a run, or a user-authorized session. Useful claims often include:
+
+- sandbox or run id
+- tenant or installation id
+- user or actor id when applicable
+- expiration
+- optional capability scopes
+
+Avoid shared static tokens across many sandboxes. If one sandbox token leaks, you want the blast radius to be small and the lifetime to be short.
+
+Token verification is only one half of the boundary. Authorization still belongs on the FastMCP server: use scopes, claims, middleware, or custom auth checks to decide which tools and resources that sandbox can actually access.
+
+For example, you can verify the token globally and still require a narrower scope on a specific tool:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import require_scopes
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+auth = JWTVerifier(
+    jwks_uri="https://auth.example.com/.well-known/jwks.json",
+    issuer="https://auth.example.com",
+    audience="sandbox-mcp",
+)
+
+mcp = FastMCP("Sandbox Tools", auth=auth)
+
+@mcp.tool(auth=require_scopes("write:summary"))
+def write_summary(content: str) -> str:
+    return f"Stored summary with {len(content)} characters"
+```
+
+For validation patterns, see [Token Verification](/servers/auth/token-verification). For policy enforcement, see [Authorization](/servers/authorization).
+
+## Expose Capabilities, Not Raw Access
+
+The sandbox should not need:
+
+- GitHub app private keys
+- database passwords
+- upstream OAuth client secrets
+- cloud provider credentials
+
+Instead, expose MCP tools that perform privileged work on the server side.
+
+Good sandbox-facing tools tend to look like this:
+
+- `get_recent_updates`
+- `write_summary`
+- `fetch_repo_context`
+- `publish_review_comment`
+
+These tools describe the capability the sandbox needs, not the low-level credentialed action required to perform it.
+
+That distinction matters. A tool like `write_summary` lets the server decide where and how to persist the summary. A tool like `run_sql` or `call_internal_api` pushes privilege and policy into the sandbox where they are much harder to control.
+
+Sandboxed agents behave best when those tools are narrow and structured:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("Sandbox Tools")
+
+@mcp.tool
+def write_summary(content: str) -> str:
+    """Store the final summary for the current run."""
+    return f"Stored summary with {len(content)} characters"
+
+@mcp.tool
+def publish_review_comment(pr_number: int, body: str) -> str:
+    """Queue a review comment for a specific pull request."""
+    return f"Queued comment for PR #{pr_number}"
+```
+
+These are easier to audit, easier to authorize, and easier for agents to use reliably than a broad catch-all tool like `mutate_state(kind: str, payload: dict)`.
+
+Narrow tools also let you express different policies per tool instead of creating one large privileged escape hatch.
+
+## Use a Proxy When Upstream Systems Are More Privileged
+
+If the sandbox needs access to other MCP servers or internal systems, put FastMCP in front of them instead of forwarding secrets into the sandbox.
+
+This is where proxying becomes useful. Your public-facing FastMCP server can authenticate the sandbox, then forward allowed capabilities to upstream systems with stronger credentials.
+
+Typical examples:
+
+- a sandbox-safe MCP gateway in front of internal MCP servers
+- a FastMCP layer in front of internal HTTP APIs
+- a job-scoped server that fronts a Git provider, issue tracker, or storage system
+
+If the upstream system is itself an MCP server, FastMCP's proxy support is a natural fit. See [MCP Proxy](/servers/providers/proxy).
+
+## mcp.json for Sandboxed Clients
+
+If your sandboxed agent is configured through `mcp.json`, keep that configuration minimal. Point it at the remote FastMCP server and pass only the values the sandbox actually needs.
+
+```json
+{
+  "mcpServers": {
+    "sandbox-tools": {
+      "url": "https://sandbox-tools.example.com/mcp",
+      "transport": "http"
+    }
+  }
+}
+```
+
+In many systems, authentication is injected by the launcher or environment rather than hardcoded in `mcp.json`. That is usually the right tradeoff for sandboxes. Avoid baking long-lived credentials directly into generated config files, and avoid treating `mcp.json` as the place where secret material should live.
+
+That is all this section needs to do: tell the sandbox where the server lives. Keep auth and secret handling elsewhere.
+
+For configuration details, see [MCP.json](/integrations/mcp-json-configuration).
+
+## Common Mistakes
+
+The same few mistakes show up again and again in sandboxed deployments:
+
+- passing long-lived API keys directly into the sandbox
+- treating helper scripts in the sandbox as a security boundary
+- exposing broad mutation tools instead of narrow capabilities
+- using one shared token for every sandbox
+- relying on STDIO inheritance for configuration in production
+
+Each of these works at first. Each becomes painful once you have multiple tenants, multiple jobs, or an incident that requires revoking access quickly.
+
+## Production Checklist
+
+Before shipping a sandbox-facing FastMCP server, check these:
+
+- The sandbox connects over HTTP, not with privileged local credentials.
+- Tokens are short-lived and scoped to a run, tenant, or job.
+- The FastMCP server verifies tokens on every request.
+- Long-lived secrets stay on the server side.
+- Tools are narrow, explicit, and structured.
+- Upstream privileged systems sit behind the FastMCP server or proxy.
+- Revocation and audit live at the server boundary, not inside the sandbox.
+
+If you adopt those defaults, sandbox support stops being a special case and becomes a normal deployment pattern: isolated workers talk to a constrained FastMCP surface, and the server handles the privileged parts centrally.
diff --git a/docs/deployment/server-configuration.mdx b/docs/deployment/server-configuration.mdx
new file mode 100644
index 0000000..f9b0e47
--- /dev/null
+++ b/docs/deployment/server-configuration.mdx
@@ -0,0 +1,640 @@
+---
+title: "Project Configuration"
+sidebarTitle: "Project Configuration"
+description: Use fastmcp.json for portable, declarative project configuration
+icon: file-code
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.12.0" />
+
+FastMCP supports declarative configuration through `fastmcp.json` files. This is the canonical and preferred way to configure FastMCP projects, providing a single source of truth for server settings, dependencies, and deployment options that replaces complex command-line arguments.
+
+The `fastmcp.json` file is designed to be a portable description of your server configuration that can be shared across environments and teams. When running from a `fastmcp.json` file, you can override any configuration values using CLI arguments.
+
+## Overview
+
+The `fastmcp.json` configuration file allows you to define all aspects of your FastMCP server in a structured, shareable format. Instead of remembering command-line arguments or writing shell scripts, you declare your server's configuration once and use it everywhere.
+
+When you have a `fastmcp.json` file, running your server becomes as simple as:
+
+```bash
+# Run the server using the configuration
+fastmcp run fastmcp.json
+
+# Or if fastmcp.json exists in the current directory
+fastmcp run
+```
+
+This configuration approach ensures reproducible deployments across different environments, from local development to production servers. It works seamlessly with Claude Desktop, VS Code extensions, and any MCP-compatible client.
+
+## File Structure
+
+The `fastmcp.json` configuration answers three fundamental questions about your server:
+
+- **Source** = WHERE does your server code live?
+- **Environment** = WHAT environment setup does it require?
+- **Deployment** = HOW should the server run?
+
+This conceptual model helps you understand the purpose of each configuration section and organize your settings effectively. The configuration file maps directly to these three concerns:
+
+```json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    // WHERE: Location of your server code
+    "type": "filesystem",  // Optional, defaults to "filesystem"
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    // WHAT: Environment setup and dependencies
+    "type": "uv",  // Optional, defaults to "uv"
+    "python": ">=3.10",
+    "dependencies": ["pandas", "numpy"]
+  },
+  "deployment": {
+    // HOW: Runtime configuration
+    "transport": "stdio",
+    "log_level": "INFO"
+  }
+}
+```
+
+Only the `source` field is required. The `environment` and `deployment` sections are optional and provide additional configuration when needed.
+
+### JSON Schema Support
+
+FastMCP provides JSON schemas for IDE autocomplete and validation. Add the schema reference to your `fastmcp.json` for enhanced developer experience:
+
+```json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  }
+}
+```
+
+Two schema URLs are available:
+- **Version-specific**: `https://gofastmcp.com/public/schemas/fastmcp.json/v1.json`
+- **Latest version**: `https://gofastmcp.com/public/schemas/fastmcp.json/latest.json`
+
+Modern IDEs like VS Code will automatically provide autocomplete suggestions, validation, and inline documentation when the schema is specified.
+
+### Source Configuration
+
+The source configuration determines **WHERE** your server code lives. It tells FastMCP how to find and load your server, whether it's a local Python file, a remote repository, or hosted in the cloud. This section is required and forms the foundation of your configuration.
+
+<Card icon="code" title="Source">
+<ParamField body="source" type="object" required>
+  The server source configuration that determines where your server code lives.
+  
+  <ParamField body="type" type="string" default="filesystem">
+    The source type identifier that determines which implementation to use. Currently supports `"filesystem"` for local files. Future releases will add support for `"git"` and `"cloud"` source types.
+  </ParamField>
+  
+  <Expandable title="FileSystemSource">
+    When `type` is `"filesystem"` (or omitted), the source points to a local Python file containing your FastMCP server:
+    
+    <ParamField body="path" type="string" required>
+      Path to the Python file containing your FastMCP server. 
+    </ParamField>
+    
+    <ParamField body="entrypoint" type="string">
+      Name of the server instance or factory function within the module:
+      - Can be a FastMCP server instance (e.g., `mcp = FastMCP("MyServer")`)
+      - Can be a function with no arguments that returns a FastMCP server
+      - If not specified, FastMCP searches for common names: `mcp`, `server`, or `app`
+    </ParamField>
+    
+    **Example:**
+    ```json
+    "source": {
+      "type": "filesystem",
+      "path": "src/server.py",
+      "entrypoint": "mcp"
+    }
+    ```
+    
+    Note: File paths are resolved relative to the configuration file's location.
+  </Expandable>
+</ParamField>
+</Card>
+
+<Note>
+**Future Source Types**
+
+Future releases will support additional source types:
+- **Git repositories** (`type: "git"`) for loading server code directly from version control
+- **Prefect Horizon** (`type: "cloud"`) for hosted servers with automatic scaling and management
+</Note>
+
+### Environment Configuration
+
+The environment configuration determines **WHAT** environment setup your server requires. It controls the build-time setup of your Python environment, ensuring your server runs with the exact Python version and dependencies it requires. This section creates isolated, reproducible environments across different systems.
+
+FastMCP uses an extensible environment system with a base `Environment` class that can be implemented by different environment providers. Currently, FastMCP supports the `UVEnvironment` for Python environment management using `uv`'s powerful dependency resolver.
+
+<Card icon="code" title="Environment">
+<ParamField body="environment" type="object">
+  Optional environment configuration. When specified, FastMCP uses the appropriate environment implementation to set up your server's runtime.
+  
+  <ParamField body="type" type="string" default="uv">
+    The environment type identifier that determines which implementation to use. Currently supports `"uv"` for Python environments managed by uv. If omitted, defaults to `"uv"`.
+  </ParamField>
+  
+  <Expandable title="UVEnvironment">
+    When `type` is `"uv"` (or omitted), the environment uses uv to manage Python dependencies:
+    
+    <ParamField body="python" type="string">
+      Python version constraint. Examples:
+      - Exact version: `"3.12"`
+      - Minimum version: `">=3.10"`
+      - Version range: `">=3.10,<3.13"`
+    </ParamField>
+    
+    <ParamField body="dependencies" type="list[str]">
+      List of pip packages with optional version specifiers (PEP 508 format).
+      ```json
+      "dependencies": ["pandas>=2.0", "requests", "httpx"]
+      ```
+    </ParamField>
+    
+    <ParamField body="requirements" type="string">
+      Path to a requirements.txt file, resolved relative to the config file location.
+      ```json
+      "requirements": "requirements.txt"
+      ```
+    </ParamField>
+    
+    <ParamField body="project" type="string">
+      Path to a project directory containing pyproject.toml for uv project management.
+      ```json
+      "project": "."
+      ```
+    </ParamField>
+    
+    <ParamField body="editable" type="list[string]">
+      List of paths to packages to install in editable/development mode. Useful for local development when you want changes to be reflected immediately. Supports multiple packages for monorepo setups or shared libraries.
+      ```json
+      "editable": ["."]
+      ```
+      Or with multiple packages:
+      ```json
+      "editable": [".", "../shared-lib", "/path/to/another-package"]
+      ```
+    </ParamField>
+    
+    **Example:**
+    ```json
+    "environment": {
+      "type": "uv",
+      "python": ">=3.10",
+      "dependencies": ["pandas", "numpy"],
+      "editable": ["."]
+    }
+    ```
+    
+    Note: When any UVEnvironment field is specified, FastMCP automatically creates an isolated environment using `uv` before running your server.
+  </Expandable>
+</ParamField>
+</Card>
+
+When environment configuration is provided, FastMCP:
+1. Detects the environment type (defaults to `"uv"` if not specified)
+2. Creates an isolated environment using the appropriate provider
+3. Installs the specified dependencies
+4. Runs your server in this clean environment
+
+This build-time setup ensures your server always has the dependencies it needs, without polluting your system Python or conflicting with other projects.
+
+<Note>
+**Future Environment Types**
+
+Similar to source types, future releases may support additional environment types for different runtime requirements, such as Docker containers or language-specific environments beyond Python.
+</Note>
+
+### Deployment Configuration
+
+The deployment configuration controls **HOW** your server runs. It defines the runtime behavior including network settings, environment variables, and execution context. These settings determine how your server operates when it executes, from transport protocols to logging levels.
+
+Environment variables are included in this section because they're runtime configuration that affects how your server behaves when it executes, not how its environment is built. The deployment configuration is applied every time your server starts, controlling its operational characteristics.
+
+<Card icon="code" title="Deployment Fields">
+<ParamField body="deployment" type="object">
+  Optional runtime configuration for the server.
+  
+  <Expandable title="Deployment Fields">
+    <ParamField body="transport" type="string" default="stdio">
+      Protocol for client communication:
+      - `"stdio"`: Standard input/output for desktop clients
+      - `"http"`: Network-accessible HTTP server
+      - `"sse"`: Server-sent events
+    </ParamField>
+    
+    <ParamField body="host" type="string" default="127.0.0.1">
+      Network interface to bind (HTTP transport only):
+      - `"127.0.0.1"`: Local connections only
+      - `"0.0.0.0"`: All network interfaces
+    </ParamField>
+    
+    <ParamField body="port" type="integer" default="3000">
+      Port number for HTTP transport.
+    </ParamField>
+    
+    <ParamField body="path" type="string" default="/mcp/">
+      URL path for the MCP endpoint when using HTTP transport.
+    </ParamField>
+    
+    <ParamField body="log_level" type="string" default="INFO">
+      Server logging verbosity. Options:
+      - `"DEBUG"`: Detailed debugging information
+      - `"INFO"`: General informational messages
+      - `"WARNING"`: Warning messages
+      - `"ERROR"`: Error messages only
+      - `"CRITICAL"`: Critical errors only
+    </ParamField>
+    
+    <ParamField body="env" type="object">
+      Environment variables to set when running the server. Supports `${VAR_NAME}` syntax for runtime interpolation.
+      ```json
+      "env": {
+        "API_KEY": "secret-key",
+        "DATABASE_URL": "postgres://${DB_USER}@${DB_HOST}/mydb"
+      }
+      ```
+    </ParamField>
+    
+    <ParamField body="cwd" type="string">
+      Working directory for the server process. Relative paths are resolved from the config file location.
+    </ParamField>
+    
+    <ParamField body="args" type="list[str]">
+      Command-line arguments to pass to the server, passed after `--` to the server's argument parser.
+      ```json
+      "args": ["--config", "server-config.json"]
+      ```
+    </ParamField>
+  </Expandable>
+</ParamField>
+</Card>
+
+#### Environment Variable Interpolation
+
+The `env` field in deployment configuration supports runtime interpolation of environment variables using `${VAR_NAME}` syntax. This enables dynamic configuration based on your deployment environment:
+
+```json
+{
+  "deployment": {
+    "env": {
+      "API_URL": "https://api.${ENVIRONMENT}.example.com",
+      "DATABASE_URL": "postgres://${DB_USER}:${DB_PASS}@${DB_HOST}/myapp",
+      "CACHE_KEY": "myapp_${ENVIRONMENT}_${VERSION}"
+    }
+  }
+}
+```
+
+When the server starts, FastMCP replaces `${ENVIRONMENT}`, `${DB_USER}`, etc. with values from your system's environment variables. If a variable doesn't exist, the placeholder is preserved as-is.
+
+**Example**: If your system has `ENVIRONMENT=production` and `DB_HOST=db.example.com`:
+```json
+// Configuration
+{
+  "deployment": {
+    "env": {
+      "API_URL": "https://api.${ENVIRONMENT}.example.com",
+      "DB_HOST": "${DB_HOST}"
+    }
+  }
+}
+
+// Result at runtime
+{
+  "API_URL": "https://api.production.example.com",
+  "DB_HOST": "db.example.com"
+}
+```
+
+This feature is particularly useful for:
+- Deploying the same configuration across development, staging, and production
+- Keeping sensitive values out of configuration files
+- Building dynamic URLs and connection strings
+- Creating environment-specific prefixes or suffixes
+
+## Usage with CLI Commands
+
+FastMCP automatically detects and uses a file specifically named `fastmcp.json` in the current directory, making server execution simple and consistent. Files with FastMCP configuration format but different names are not auto-detected and must be specified explicitly:
+
+```bash
+# Auto-detect fastmcp.json in current directory
+cd my-project
+fastmcp run  # No arguments needed!
+
+# Or specify a configuration file explicitly
+fastmcp run prod.fastmcp.json
+
+# Skip environment setup when already in a uv environment
+fastmcp run fastmcp.json --skip-env
+
+# Skip source preparation when source is already prepared
+fastmcp run fastmcp.json --skip-source
+
+# Skip both environment and source preparation
+fastmcp run fastmcp.json --skip-env --skip-source
+```
+
+### Pre-building Environments
+
+You can use `fastmcp project prepare` to create a persistent uv project with all dependencies pre-installed:
+
+```bash
+# Create a persistent environment
+fastmcp project prepare fastmcp.json --output-dir ./env
+
+# Use the pre-built environment to run the server
+fastmcp run fastmcp.json --project ./env
+```
+
+This pattern separates environment setup (slow) from server execution (fast), useful for deployment scenarios.
+
+### Using an Existing Environment
+
+By default, FastMCP creates an isolated environment with `uv` based on your configuration. When you already have a suitable Python environment, use the `--skip-env` flag to skip environment creation:
+
+```bash
+fastmcp run fastmcp.json --skip-env
+```
+
+**When you already have an environment:**
+- You're in an activated virtual environment with all dependencies installed
+- You're inside a Docker container with pre-installed dependencies  
+- You're in a CI/CD pipeline that pre-builds the environment
+- You're using a system-wide installation with all required packages
+- You're in a uv-managed environment (prevents infinite recursion)
+
+This flag tells FastMCP: "I already have everything installed, just run the server."
+
+### Using an Existing Source
+
+When working with source types that require preparation (future support for git repositories or cloud sources), use the `--skip-source` flag when you already have the source code available:
+
+```bash
+fastmcp run fastmcp.json --skip-source
+```
+
+**When you already have the source:**
+- You've previously cloned a git repository and don't need to re-fetch
+- You have a cached copy of a cloud-hosted server
+- You're in a CI/CD pipeline where source checkout is a separate step
+- You're iterating locally on already-downloaded code
+
+This flag tells FastMCP: "I already have the source code, skip any download/clone steps."
+
+Note: For filesystem sources (local Python files), this flag has no effect since they don't require preparation.
+
+The configuration file works with all FastMCP commands:
+- **`run`** - Start the server in production mode
+- **`dev`** - Launch with the Inspector UI for development  
+- **`inspect`** - View server capabilities and configuration
+- **`install`** - Install to Claude Desktop, Cursor, or other MCP clients
+
+When no file argument is provided, FastMCP searches the current directory for `fastmcp.json`. This means you can simply navigate to your project directory and run `fastmcp run` to start your server with all its configured settings.
+
+### CLI Override Behavior
+
+Command-line arguments take precedence over configuration file values, allowing ad-hoc adjustments without modifying the file:
+
+```bash
+# Config specifies port 3000, CLI overrides to 8080
+fastmcp run fastmcp.json --port 8080
+
+# Config specifies stdio, CLI overrides to HTTP
+fastmcp run fastmcp.json --transport http
+
+# Add extra dependencies not in config
+fastmcp run fastmcp.json --with requests --with httpx
+```
+
+This precedence order enables:
+- Quick testing of different settings
+- Environment-specific overrides in deployment scripts
+- Debugging with increased log levels
+- Temporary configuration changes
+
+### Custom Naming Patterns
+
+You can use different configuration files for different environments:
+
+- `fastmcp.json` - Default configuration
+- `dev.fastmcp.json` - Development settings
+- `prod.fastmcp.json` - Production settings
+- `test_fastmcp.json` - Test configuration
+
+Any file with "fastmcp.json" in the name is recognized as a configuration file.
+
+## Examples
+
+<Tabs>
+<Tab title="Basic Configuration">
+
+A minimal configuration for a simple server:
+
+```json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  }
+}
+```
+This configuration explicitly specifies the server entrypoint (`mcp`), making it clear which server instance or factory function to use. Uses all defaults: STDIO transport, no special dependencies, standard logging.
+</Tab>
+<Tab title="Development Configuration">
+
+A configuration optimized for local development:
+
+```json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  // WHERE does the server live?
+  "source": {
+    "path": "src/server.py",
+    "entrypoint": "app"
+  },
+  // WHAT dependencies does it need?
+  "environment": {
+    "type": "uv",
+    "python": "3.12",
+    "dependencies": ["fastmcp[dev]"],
+    "editable": "."
+  },
+  // HOW should it run?
+  "deployment": {
+    "transport": "http",
+    "host": "127.0.0.1",
+    "port": 8000,
+    "log_level": "DEBUG",
+    "env": {
+      "DEBUG": "true",
+      "ENV": "development"
+    }
+  }
+}
+```
+</Tab>
+<Tab title="Production Configuration">
+
+A production-ready configuration with full dependency management:
+
+```json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  // WHERE does the server live?
+  "source": {
+    "path": "app/main.py",
+    "entrypoint": "mcp_server"
+  },
+  // WHAT dependencies does it need?
+  "environment": {
+    "python": "3.11",
+    "requirements": "requirements/production.txt",
+    "project": "."
+  },
+  // HOW should it run?
+  "deployment": {
+    "transport": "http",
+    "host": "0.0.0.0",
+    "port": 3000,
+    "path": "/api/mcp/",
+    "log_level": "INFO",
+    "env": {
+      "ENV": "production",
+      "API_BASE_URL": "https://api.example.com",
+      "DATABASE_URL": "postgresql://user:pass@db.example.com/prod"
+    },
+    "cwd": "/app",
+    "args": ["--workers", "4"]
+  }
+}
+```
+</Tab>
+<Tab title="Data Science Server">
+
+Configuration for a data analysis server with scientific packages:
+
+```json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "analysis_server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "python": "3.11",
+    "dependencies": [
+      "pandas>=2.0",
+      "numpy",
+      "scikit-learn",
+      "matplotlib",
+      "jupyterlab"
+    ]
+  },
+  "deployment": {
+    "transport": "stdio",
+    "env": {
+      "MATPLOTLIB_BACKEND": "Agg",
+      "DATA_PATH": "./datasets"
+    }
+  }
+}
+```
+</Tab>
+<Tab title="Multi-Environment Setup"> 
+
+You can maintain multiple configuration files for different environments:
+
+**dev.fastmcp.json**:
+```json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "deployment": {
+    "transport": "http",
+    "log_level": "DEBUG"
+  }
+}
+```
+
+**prod.fastmcp.json**:
+```json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "requirements": "requirements/production.txt"
+  },
+  "deployment": {
+    "transport": "http",
+    "host": "0.0.0.0",
+    "log_level": "WARNING"
+  }
+}
+```
+
+Run different configurations:
+```bash
+fastmcp run dev.fastmcp.json   # Development
+fastmcp run prod.fastmcp.json  # Production
+```
+</Tab>
+</Tabs>
+
+## Migrating from CLI Arguments
+
+If you're currently using command-line arguments or shell scripts, migrating to `fastmcp.json` simplifies your workflow. Here's how common CLI patterns map to configuration:
+
+**CLI Command**:
+```bash
+uv run --with pandas --with requests \
+  fastmcp run server.py \
+  --transport http \
+  --port 8000 \
+  --log-level INFO
+```
+
+**Equivalent fastmcp.json**:
+```json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "dependencies": ["pandas", "requests"]
+  },
+  "deployment": {
+    "transport": "http",
+    "port": 8000,
+    "log_level": "INFO"
+  }
+}
+```
+
+Now simply run:
+```bash
+fastmcp run  # Automatically finds and uses fastmcp.json
+```
+
+The configuration file approach provides better documentation, easier sharing, and consistent execution across different environments while maintaining the flexibility to override settings when needed.
\ No newline at end of file
diff --git a/docs/development/contributing.mdx b/docs/development/contributing.mdx
new file mode 100644
index 0000000..c877276
--- /dev/null
+++ b/docs/development/contributing.mdx
@@ -0,0 +1,198 @@
+---
+title: "Contributing"
+description: "Development workflow for FastMCP contributors"
+icon: code-pull-request
+---
+
+Contributing to FastMCP means joining a community that values clean, maintainable code and thoughtful API design. All contributions are valued - from fixing typos in documentation to implementing major features.
+
+## Design Principles
+
+Every contribution should advance these principles:
+
+- 🚀 **Fast** — High-level interfaces mean less code and faster development
+- 🍀 **Simple** — Minimal boilerplate; the obvious way should be the right way
+- 🐍 **Pythonic** — Feels natural to Python developers; no surprising patterns
+- 🔍 **Complete** — Everything needed for production: auth, testing, deployment, observability
+
+PRs are evaluated against these principles. Code that makes FastMCP slower, harder to reason about, less Pythonic, or less complete will be rejected.
+
+## Issues
+
+### Issue First, Code Second
+
+**Every pull request requires a corresponding issue - no exceptions.** This requirement creates a collaborative space where approach, scope, and alignment are established before code is written. Issues serve as design documents where maintainers and contributors discuss implementation strategy, identify potential conflicts with existing patterns, and ensure proposed changes advance FastMCP's vision.
+
+**FastMCP is an opinionated framework, not a kitchen sink.** The maintainers have strong beliefs about what FastMCP should and shouldn't do. Just because something takes N lines of code and you want it in fewer lines doesn't mean FastMCP should take on the maintenance burden or endorse that pattern. This is judged at the maintainers' discretion.
+
+Use issues to understand scope BEFORE opening PRs. The issue discussion determines whether a feature belongs in core, contrib, or not at all.
+
+### Writing Good Issues
+
+FastMCP is an extremely highly-trafficked repository maintained by a very small team. Issues that appear to transfer burden to maintainers without any effort to validate the problem will be closed. Please help the maintainers help you by always providing a minimal reproducible example and clearly describing the problem.
+
+**LLM-generated issues will be closed immediately.** Issues that contain paragraphs of unnecessary explanation, verbose problem descriptions, or obvious LLM authorship patterns obfuscate the actual problem and transfer burden to maintainers.
+
+Write clear, concise issues that:
+- State the problem directly
+- Provide a minimal reproducible example
+- Skip unnecessary background or context
+- Take responsibility for clear communication
+
+Issues may be labeled "Invalid" simply due to confusion caused by verbosity or not adhering to the guidelines outlined here.
+
+## Pull Requests
+
+PRs that deviate from FastMCP's core principles will be rejected regardless of implementation quality. **PRs are NOT for iterating on ideas** - they should only be opened for ideas that already have a bias toward acceptance based on issue discussion.
+
+
+### Development Environment
+
+#### Installation
+
+To contribute to FastMCP, you'll need to set up a development environment with all necessary tools and dependencies.
+
+```bash
+# Clone the repository
+git clone https://github.com/PrefectHQ/fastmcp.git
+cd fastmcp
+
+# Install all dependencies including dev tools
+uv sync
+
+# Install prek hooks
+uv run prek install
+```
+
+In addition, some development commands require [just](https://github.com/casey/just) to be installed.
+
+Prek hooks will run automatically on every commit to catch issues before they reach CI. If you see failures, fix them before committing - never commit broken code expecting to fix it later.
+
+### Development Standards
+
+#### Scope
+
+Large pull requests create review bottlenecks and quality risks. Unless you're fixing a discrete bug or making an incredibly well-scoped change, keep PRs small and focused. 
+
+A PR that changes 50 lines across 3 files can be thoroughly reviewed in minutes. A PR that changes 500 lines across 20 files requires hours of careful analysis and often hides subtle issues.
+
+Breaking large features into smaller PRs:
+- Creates better review experiences
+- Makes git history clear
+- Simplifies debugging with bisect
+- Reduces merge conflicts
+- Gets your code merged faster
+
+#### Code Quality
+
+FastMCP values clarity over cleverness. Every line you write will be maintained by someone else - possibly years from now, possibly without context about your decisions.
+
+**PRs can be rejected for two opposing reasons:**
+1. **Insufficient quality** - Code that doesn't meet our standards for clarity, maintainability, or idiomaticity
+2. **Overengineering** - Code that is overbearing, unnecessarily complex, or tries to be too clever
+
+The focus is on idiomatic, high-quality Python. FastMCP uses patterns like `NotSet` type as an alternative to `None` in certain situations - follow existing patterns.
+
+#### Required Practices
+
+**Full type annotations** on all functions and methods. They catch bugs before runtime and serve as inline documentation.
+
+**Async/await patterns** for all I/O operations. Even if your specific use case doesn't need concurrency, consistency means users can compose features without worrying about blocking operations.
+
+**Descriptive names** make code self-documenting. `auth_token` is clear; `tok` requires mental translation.
+
+**Specific exception types** make error handling predictable. Catching `ValueError` tells readers exactly what error you expect. Never use bare `except` clauses.
+
+#### Anti-Patterns to Avoid
+
+**Complex one-liners** are hard to debug and modify. Break operations into clear steps.
+
+**Mutable default arguments** cause subtle bugs. Use `None` as the default and create the mutable object inside the function.
+
+**Breaking established patterns** confuses readers. If you must deviate, discuss in the issue first.
+
+### Prek Checks
+
+```bash
+# Runs automatically on commit, or manually:
+uv run prek run --all-files
+```
+
+This runs three critical tools:
+- **Ruff**: Linting and formatting
+- **Prettier**: Code formatting
+- **ty**: Static type checking
+
+Pytest runs separately as a distinct workflow step after prek checks pass. CI will reject PRs that fail these checks. Always run them locally first.
+
+### Testing
+
+Tests are documentation that shows how features work. Good tests give reviewers confidence and help future maintainers understand intent.
+
+```bash
+# Run specific test directory
+uv run pytest tests/server/ -v
+
+# Run all tests before submitting PR
+uv run pytest
+```
+
+Every new feature needs tests. See the [Testing Guide](/development/tests) for patterns and requirements.
+
+### Documentation
+
+A feature doesn't exist unless it's documented. Note that FastMCP's hosted documentation always tracks the main branch - users who want historical documentation can clone the repo, checkout a specific tag, and host it themselves.
+
+```bash
+# Preview documentation locally
+just docs
+```
+
+Documentation requirements:
+- **Explain concepts in prose first** - Code without context is just syntax
+- **Complete, runnable examples** - Every code block should be copy-pasteable
+- **Register in docs.json** - Makes pages appear in navigation
+- **Version badges** - Mark when features were added using `<VersionBadge />`
+
+#### SDK Documentation
+
+FastMCP's SDK documentation is auto-generated from the source code docstrings and type annotations. It is automatically updated on every merge to main by a GitHub Actions workflow, so users are *not* responsible for keeping the documentation up to date. However, to generate it proactively, you can use the following command:
+
+```bash
+just api-ref-all
+```
+
+### Submitting Your PR
+
+#### Before Submitting
+
+1. **Run all checks**: `uv run prek run --all-files && uv run pytest`
+2. **Keep scope small**: One feature or fix per PR
+3. **Write clear description**: Your PR description becomes permanent documentation
+4. **Update docs**: Include documentation for API changes
+
+#### PR Description
+
+Write PR descriptions that explain:
+- What problem you're solving
+- Why you chose this approach  
+- Any trade-offs or alternatives considered
+- Migration path for breaking changes
+
+Focus on the "why" - the code shows the "what". Keep it concise but complete.
+
+#### What We Look For
+
+**Framework Philosophy**: FastMCP is NOT trying to do all things or provide all shortcuts. Features are rejected when they don't align with the framework's vision, even if perfectly implemented. The burden of proof is on the PR to demonstrate value.
+
+**Code Quality**: We verify code follows existing patterns. Consistency reduces cognitive load. When every module works similarly, developers understand new code quickly.
+
+**Test Coverage**: Not every line needs testing, but every behavior does. Tests document intent and protect against regressions.
+
+**Breaking Changes**: May be acceptable in minor versions but must be clearly documented. See the [versioning policy](/development/releases#versioning-policy).
+
+## Special Modules
+
+**`contrib`**: Community-maintained patterns and utilities. Original authors maintain their contributions. Not representative of the core framework.
+
+**`experimental`**: Maintainer-developed features that may preview future functionality. Can break or be deleted at any time without notice. Pin your FastMCP version when using these features.
\ No newline at end of file
diff --git a/docs/development/releases.mdx b/docs/development/releases.mdx
new file mode 100644
index 0000000..331fd81
--- /dev/null
+++ b/docs/development/releases.mdx
@@ -0,0 +1,81 @@
+---
+title: "Releases"
+description: "FastMCP versioning and release process"
+icon: "truck-fast"
+---
+
+FastMCP releases frequently to deliver features quickly in the rapidly evolving MCP ecosystem. We use semantic versioning pragmatically - the Model Context Protocol is young, patterns are still emerging, and waiting for perfect stability would mean missing opportunities to empower developers with better tools.
+
+## Versioning Policy
+
+### Semantic Versioning
+
+**Major (x.0.0)**: Complete API redesigns
+
+Major versions represent fundamental shifts. FastMCP 2.x is entirely different from 1.x in both implementation and design philosophy.
+
+**Minor (2.x.0)**: New features and evolution
+
+<Warning>
+Unlike traditional semantic versioning, minor versions **may** include [breaking changes](#breaking-changes) when necessary for the ecosystem's evolution. This flexibility is essential in a young ecosystem where perfect backwards compatibility would prevent important improvements.
+</Warning>
+
+FastMCP tracks the current MCP Protocol version while serving earlier handshake versions alongside it. Building on MCP SDK v2, a FastMCP server negotiates the protocol era each client speaks — the sessionless `2026-07-28` era and earlier session-based eras are both handled by the same server. New features and conventions from the spec flow through to FastMCP as they land; for the details of which capabilities are available on each era, see [Upgrading from FastMCP 3](/getting-started/upgrading/from-fastmcp-3#protocol-version-support).
+
+**Patch (2.0.x)**: Bug fixes and refinements
+
+Patch versions contain only bug fixes without breaking changes. These are safe updates you can apply with confidence.
+
+### Breaking Changes
+
+We permit breaking changes in minor versions because the MCP ecosystem is rapidly evolving. Refusing to break problematic APIs would accumulate design debt that eventually makes the framework unusable. Each breaking change represents a deliberate decision to keep FastMCP aligned with the ecosystem's evolution.
+
+When breaking changes occur:
+- They only happen in minor versions (e.g., 2.3.x to 2.4.0)
+- Release notes explain what changed and how to migrate
+- We provide deprecation warnings at least 1 minor version in advance when possible
+- Changes must substantially benefit users to justify disruption
+
+The public API is what's covered by our compatibility guarantees - these are the parts of FastMCP you can rely on to remain stable within a minor version. The public API consists of:
+- `FastMCP` server class, `Client` class, and FastMCP `Context`
+- Core MCP components: `Tool`, `Prompt`, `Resource`, `ResourceTemplate`, and transports
+- Their public methods and documented behaviors
+
+Everything else (utilities, private methods, internal modules) may change without notice. This boundary lets us refactor internals and improve implementation details without breaking your code. For production stability, pin to specific versions.
+
+<Warning>
+The `fastmcp.server.auth` module was introduced in 2.12.0 and is exempted from this policy temporarily, meaning it is *expected* to have breaking changes even on patch versions. This is because auth is a rapidly evolving part of the MCP spec and it would be dangerous to be beholden to old decisions. Please pin your FastMCP version if using authentication in production.
+
+We expect this exemption to last through at least the 2.12.x and 2.13.x release series. 
+</Warning>
+
+### Production Use
+
+Pin to exact versions:
+```
+fastmcp==2.11.0  # Good
+fastmcp>=2.11.0  # Bad - will install breaking changes
+```
+
+## Creating Releases
+
+Our release process is intentionally simple:
+
+1. Create GitHub release with tag `vMAJOR.MINOR.PATCH` (e.g., `v2.11.0`)
+2. Generate release notes automatically, and curate or add additional editorial information as needed
+3. GitHub releases automatically trigger PyPI deployments
+
+Current-major releases target `main`. Maintenance releases target their release branch, such as `release/3.x` for 3.x patches and `release/2.x` for 2.x patches. Stable releases from `main` update the `published-docs` branch after PyPI publishing succeeds; maintenance releases publish packages and GitHub release notes without repointing the live docs branch.
+
+This automation lets maintainers focus on code quality rather than release mechanics.
+
+### Release Cadence
+
+We follow a feature-driven release cadence rather than a fixed schedule. Minor versions ship approximately every 3-4 weeks when significant functionality is ready.
+
+Patch releases ship promptly for:
+- Critical bug fixes
+- Security updates (immediate release)
+- Regression fixes
+
+This approach means you get improvements as soon as they're ready rather than waiting for arbitrary release dates.
diff --git a/docs/development/tests.mdx b/docs/development/tests.mdx
new file mode 100644
index 0000000..d3ade17
--- /dev/null
+++ b/docs/development/tests.mdx
@@ -0,0 +1,396 @@
+---
+title: "Tests"
+description: "Testing patterns and requirements for FastMCP"
+icon: vial
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+Good tests are the foundation of reliable software. In FastMCP, we treat tests as first-class documentation that demonstrates how features work while protecting against regressions. Every new capability needs comprehensive tests that demonstrate correctness.
+
+## FastMCP Tests
+
+### Running Tests
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run specific test file
+uv run pytest tests/server/test_auth.py
+
+# Run with coverage
+uv run pytest --cov=fastmcp
+
+# Skip integration tests for faster runs
+uv run pytest -m "not integration"
+
+# Skip tests that spawn processes
+uv run pytest -m "not integration and not client_process"
+```
+
+Tests should complete in under 1 second unless marked as integration tests. This speed encourages running them frequently, catching issues early.
+
+### Test Organization
+
+Our test organization mirrors the source package structure, creating a predictable mapping between code and tests. When you're working on `fastmcp_slim/fastmcp/server/auth.py`, you'll find its tests in `tests/server/test_auth.py`. In rare cases tests are split further - for example, the OpenAPI tests are so comprehensive they're split across multiple files.
+
+### Test Markers
+
+We use pytest markers to categorize tests that require special resources or take longer to run:
+
+```python
+@pytest.mark.integration
+async def test_github_api_integration():
+    """Test GitHub API integration with real service."""
+    token = os.getenv("FASTMCP_GITHUB_TOKEN")
+    if not token:
+        pytest.skip("FASTMCP_GITHUB_TOKEN not available")
+    
+    # Test against real GitHub API
+    client = GitHubClient(token)
+    repos = await client.list_repos("prefecthq")
+    assert "fastmcp" in [repo.name for repo in repos]
+
+@pytest.mark.client_process
+async def test_stdio_transport():
+    """Test STDIO transport with separate process."""
+    # This spawns a subprocess
+    async with Client("python examples/simple_echo.py") as client:
+        result = await client.call_tool("echo", {"message": "test"})
+        assert result.content[0].text == "test"
+```
+
+## Writing Tests
+
+
+### Test Requirements
+
+Following these practices creates maintainable, debuggable test suites that serve as both documentation and regression protection.
+
+#### Single Behavior Per Test
+
+Each test should verify exactly one behavior. When it fails, you need to know immediately what broke. A test that checks five things gives you five potential failure points to investigate. A test that checks one thing points directly to the problem.
+
+<CodeGroup>
+
+```python Good: Atomic Test
+async def test_tool_registration():
+    """Test that tools are properly registered with the server."""
+    mcp = FastMCP("test-server")
+    
+    @mcp.tool
+    def add(a: int, b: int) -> int:
+        return a + b
+    
+    tools = mcp.list_tools()
+    assert len(tools) == 1
+    assert tools[0].name == "add"
+```
+
+```python Bad: Multi-Behavior Test
+async def test_server_functionality():
+    """Test multiple server features at once."""
+    mcp = FastMCP("test-server")
+    
+    # Tool registration
+    @mcp.tool
+    def add(a: int, b: int) -> int:
+        return a + b
+    
+    # Resource creation
+    @mcp.resource("config://app")
+    def get_config():
+        return {"version": "1.0"}
+    
+    # Authentication setup
+    mcp.auth = BearerTokenProvider({"token": "user"})
+    
+    # What exactly are we testing? If this fails, what broke?
+    assert mcp.list_tools()
+    assert mcp.list_resources()
+    assert mcp.auth is not None
+```
+
+</CodeGroup>
+
+#### Self-Contained Setup
+
+Every test must create its own setup. Tests should be runnable in any order, in parallel, or in isolation. When a test fails, you should be able to run just that test to reproduce the issue.
+
+<CodeGroup>
+
+```python Good: Self-Contained
+async def test_tool_execution_with_error():
+    """Test that tool errors are properly handled."""
+    mcp = FastMCP("test-server")
+    
+    @mcp.tool
+    def divide(a: int, b: int) -> float:
+        if b == 0:
+            raise ValueError("Cannot divide by zero")
+        return a / b
+    
+    async with Client(mcp) as client:
+        with pytest.raises(Exception):
+            await client.call_tool("divide", {"a": 10, "b": 0})
+```
+
+```python Bad: Test Dependencies
+# Global state that tests depend on
+test_server = None
+
+def test_setup_server():
+    """Setup for other tests."""
+    global test_server
+    test_server = FastMCP("shared-server")
+
+def test_server_works():
+    """Test server functionality."""
+    # Depends on test_setup_server running first
+    assert test_server is not None
+```
+
+</CodeGroup>
+
+#### Clear Intent
+
+Test names and assertions should make the verified behavior obvious. A developer reading your test should understand what feature it validates and how that feature should behave.
+
+```python
+async def test_authenticated_tool_requires_valid_token():
+    """Test that authenticated users can access protected tools."""
+    mcp = FastMCP("test-server")
+    mcp.auth = BearerTokenProvider({"secret-token": "test-user"})
+    
+    @mcp.tool
+    def protected_action() -> str:
+        return "success"
+    
+    async with Client(mcp, auth=BearerAuth("secret-token")) as client:
+        result = await client.call_tool("protected_action", {})
+        assert result.content[0].text == "success"
+```
+
+#### Using Fixtures
+
+Use fixtures to create reusable data, server configurations, or other resources for your tests. Note that you should **not** open FastMCP clients in your fixtures as it can create hard-to-diagnose issues with event loops.
+
+```python
+import pytest
+from fastmcp import FastMCP, Client
+
+@pytest.fixture
+def weather_server():
+    server = FastMCP("WeatherServer")
+    
+    @server.tool
+    def get_temperature(city: str) -> dict:
+        temps = {"NYC": 72, "LA": 85, "Chicago": 68}
+        return {"city": city, "temp": temps.get(city, 70)}
+    
+    return server
+
+async def test_temperature_tool(weather_server):
+    async with Client(weather_server) as client:
+        result = await client.call_tool("get_temperature", {"city": "LA"})
+        assert result.data == {"city": "LA", "temp": 85}
+```
+
+#### Effective Assertions
+
+Assertions should be specific and provide context on failure. When a test fails during CI, the assertion message should tell you exactly what went wrong.
+
+```python
+# Basic assertion - minimal context on failure
+assert result.status == "success"
+
+# Better - explains what was expected
+assert result.status == "success", f"Expected successful operation, got {result.status}: {result.error}"
+```
+
+Try not to have too many assertions in a single test unless you truly need to check various aspects of the same behavior. In general, assertions of different behaviors should be in separate tests.
+
+#### Inline Snapshots
+
+FastMCP uses `inline-snapshot` for testing complex data structures. On first run of `pytest --inline-snapshot=create` with an empty `snapshot()`, pytest will auto-populate the expected value. To update snapshots after intentional changes, run `pytest --inline-snapshot=fix`. This is particularly useful for testing JSON schemas and API responses.
+
+```python
+from inline_snapshot import snapshot
+
+async def test_tool_schema_generation():
+    """Test that tool schemas are generated correctly."""
+    mcp = FastMCP("test-server")
+    
+    @mcp.tool
+    def calculate_tax(amount: float, rate: float = 0.1) -> dict:
+        """Calculate tax on an amount."""
+        return {"amount": amount, "tax": amount * rate, "total": amount * (1 + rate)}
+    
+    tools = mcp.list_tools()
+    schema = tools[0].input_schema
+    
+    # First run: snapshot() is empty, gets auto-populated
+    # Subsequent runs: compares against stored snapshot
+    assert schema == snapshot({
+        "type": "object", 
+        "properties": {
+            "amount": {"type": "number"}, 
+            "rate": {"type": "number", "default": 0.1}
+        }, 
+        "required": ["amount"]
+    })
+```
+
+### In-Memory Testing
+
+FastMCP uses in-memory transport for testing, where servers and clients communicate directly. The majority of functionality can be tested in a deterministic fashion this way. We use more complex setups only when testing transports themselves.
+
+The in-memory transport runs the real MCP protocol implementation without network overhead. Instead of deploying your server or managing network connections, you pass your server instance directly to the client. Everything runs in the same Python process - you can set breakpoints anywhere and step through with your debugger.
+
+```python
+from fastmcp import FastMCP, Client
+
+# Create your server
+server = FastMCP("WeatherServer")
+
+@server.tool
+def get_temperature(city: str) -> dict:
+    """Get current temperature for a city"""
+    temps = {"NYC": 72, "LA": 85, "Chicago": 68}
+    return {"city": city, "temp": temps.get(city, 70)}
+
+async def test_weather_operations():
+    # Pass server directly - no deployment needed
+    async with Client(server) as client:
+        result = await client.call_tool("get_temperature", {"city": "NYC"})
+        assert result.data == {"city": "NYC", "temp": 72}
+```
+
+This pattern makes tests deterministic and fast - typically completing in milliseconds rather than seconds.
+
+### Mocking External Dependencies
+
+FastMCP servers are standard Python objects, so you can mock external dependencies using your preferred approach:
+
+```python
+from unittest.mock import AsyncMock
+
+async def test_database_tool():
+    server = FastMCP("DataServer")
+    
+    # Mock the database
+    mock_db = AsyncMock()
+    mock_db.fetch_users.return_value = [
+        {"id": 1, "name": "Alice"},
+        {"id": 2, "name": "Bob"}
+    ]
+    
+    @server.tool
+    async def list_users() -> list:
+        return await mock_db.fetch_users()
+    
+    async with Client(server) as client:
+        result = await client.call_tool("list_users", {})
+        assert len(result.data) == 2
+        assert result.data[0]["name"] == "Alice"
+        mock_db.fetch_users.assert_called_once()
+```
+
+### Testing Network Transports
+
+While in-memory testing covers most unit testing needs, you'll occasionally need to test actual network transports like HTTP or SSE. FastMCP provides two approaches: in-process async servers (preferred), and separate subprocess servers (for special cases).
+
+#### In-Process Network Testing (Preferred)
+
+<VersionBadge version="2.13.0" />
+
+For most network transport tests, use `run_server_async` as an async context manager. This runs the server as a task in the same process, providing fast, deterministic tests with full debugger support:
+
+```python
+import pytest
+from fastmcp import FastMCP, Client
+from fastmcp.client.transports import StreamableHttpTransport
+from fastmcp.utilities.tests import run_server_async
+
+def create_test_server() -> FastMCP:
+    """Create a test server instance."""
+    server = FastMCP("TestServer")
+
+    @server.tool
+    def greet(name: str) -> str:
+        return f"Hello, {name}!"
+
+    return server
+
+@pytest.fixture
+async def http_server() -> str:
+    """Start server in-process for testing."""
+    server = create_test_server()
+    async with run_server_async(server) as url:
+        yield url
+
+async def test_http_transport(http_server: str):
+    """Test actual HTTP transport behavior."""
+    async with Client(
+        transport=StreamableHttpTransport(http_server)
+    ) as client:
+        result = await client.ping()
+        assert result is True
+
+        greeting = await client.call_tool("greet", {"name": "World"})
+        assert greeting.data == "Hello, World!"
+```
+
+The `run_server_async` context manager automatically handles server lifecycle and cleanup. This approach is faster than subprocess-based testing and provides better error messages.
+
+#### Subprocess Testing (Special Cases)
+
+For tests that require complete process isolation (like STDIO transport or testing subprocess behavior), use `run_server_in_process`:
+
+```python
+import pytest
+from fastmcp.utilities.tests import run_server_in_process
+from fastmcp import FastMCP, Client
+from fastmcp.client.transports import StreamableHttpTransport
+
+def run_server(host: str, port: int) -> None:
+    """Function to run in subprocess."""
+    server = FastMCP("TestServer")
+    
+    @server.tool
+    def greet(name: str) -> str:
+        return f"Hello, {name}!"
+    
+    server.run(host=host, port=port)
+
+@pytest.fixture
+async def http_server():
+    """Fixture that runs server in subprocess."""
+    with run_server_in_process(run_server, transport="http") as url:
+        yield f"{url}/mcp"
+
+async def test_http_transport(http_server: str):
+    """Test actual HTTP transport behavior."""
+    async with Client(
+        transport=StreamableHttpTransport(http_server)
+    ) as client:
+        result = await client.ping()
+        assert result is True
+```
+
+The `run_server_in_process` utility handles server lifecycle, port allocation, and cleanup automatically. Use this only when subprocess isolation is truly necessary, as it's slower and harder to debug than in-process testing. FastMCP uses the `client_process` marker to isolate these tests in CI.
+
+### Documentation Testing
+
+Documentation requires the same validation as code. The `just docs` command launches a local Mintlify server that renders your documentation exactly as users will see it:
+
+```bash
+# Start local documentation server with hot reload
+just docs
+
+# Or run Mintlify directly
+mintlify dev
+```
+
+The local server watches for changes and automatically refreshes. This preview catches formatting issues and helps you see documentation as users will experience it.
diff --git a/docs/development/v3-notes/auth-provider-env-vars.mdx b/docs/development/v3-notes/auth-provider-env-vars.mdx
new file mode 100644
index 0000000..c61f61c
--- /dev/null
+++ b/docs/development/v3-notes/auth-provider-env-vars.mdx
@@ -0,0 +1,73 @@
+---
+title: Auth Provider Environment Variables
+---
+
+## Decision: Remove automatic environment variable loading from auth providers
+
+You can still use environment variables for configuration - you just read them yourself with `os.environ` instead of relying on FastMCP's automatic loading.
+
+**Status:** Implemented in v3.0.0
+
+### Background
+
+Auth providers in v2.x used `pydantic-settings` to automatically load configuration from environment variables with a `FASTMCP_SERVER_AUTH_<PROVIDER>_` prefix. For example, `GitHubProvider` would read from:
+
+- `FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID`
+- `FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET`
+- `FASTMCP_SERVER_AUTH_GITHUB_BASE_URL`
+- etc.
+
+This was implemented via a `*ProviderSettings(BaseSettings)` class in each provider, combined with a `NotSet` sentinel pattern to distinguish between "not provided" and `None`.
+
+### Why remove it
+
+1. **Maintenance burden**: Every new provider needed to implement the settings class, validators, and the `NotSet` merging logic. This was ~50-100 lines of boilerplate per provider.
+
+2. **Documentation complexity**: Each provider needed documentation explaining both the parameter and the corresponding environment variable. This doubled the surface area to document and maintain.
+
+3. **Contributor friction**: New contributors adding providers had to understand and replicate this pattern, which was a source of inconsistency and bugs.
+
+4. **Marginal user value**: Python developers are comfortable with `os.environ["VAR"]` or `os.environ.get("VAR", default)`. The automatic loading saved a single line of code per parameter while adding significant complexity.
+
+5. **Implicit behavior**: Magic environment variable loading makes it harder to understand where values come from. Explicit `os.environ` calls are more traceable.
+
+### Migration path
+
+The migration is trivial - users add explicit environment variable reads:
+
+```python
+# Before (v2.x)
+auth = GitHubProvider()  # Relied on env vars
+
+# After (v3.0)
+import os
+
+auth = GitHubProvider(
+    client_id=os.environ["GITHUB_CLIENT_ID"],
+    client_secret=os.environ["GITHUB_CLIENT_SECRET"],
+    base_url=os.environ["MY_BASE_URL"],
+)
+```
+
+Users can also use `os.environ.get()` with defaults, or any other configuration library they prefer (dotenv, dynaconf, etc.).
+
+### Backwards compatibility
+
+We chose not to provide backwards compatibility because:
+
+1. This is a major version bump (v3.0), which is the appropriate time for breaking changes
+2. The migration is straightforward (add `os.environ` calls)
+3. Maintaining compatibility would require keeping all the boilerplate we're trying to remove
+4. The pattern was likely not heavily used - most production deployments pass secrets explicitly rather than relying on magic prefixes
+
+### What was removed
+
+- `*ProviderSettings(BaseSettings)` classes from all auth providers
+- `NotSet` sentinel usage in provider constructors
+- `pydantic-settings` dependency for auth providers
+- Environment variable documentation from provider docs
+- Related test cases for env var loading
+
+### Result
+
+Provider constructors are now simple and explicit. Required parameters are actually required (Python raises `TypeError` if missing), and optional parameters have clear defaults. The code is more readable and easier to maintain.
diff --git a/docs/development/v3-notes/v3-features.mdx b/docs/development/v3-notes/v3-features.mdx
new file mode 100644
index 0000000..87b8ff7
--- /dev/null
+++ b/docs/development/v3-notes/v3-features.mdx
@@ -0,0 +1,1481 @@
+---
+title: v3.0 Feature Tracking
+---
+
+This document tracks major features in FastMCP v3.0 for release notes preparation.
+
+## 3.0.0rc1
+
+### SamplingTool Conversion Helpers
+
+Server tools (FunctionTool and TransformedTool) can now be passed directly to sampling methods via `SamplingTool.from_callable_tool()` ([#3062](https://github.com/PrefectHQ/fastmcp/pull/3062)). Previously, tools defined with `@mcp.tool` had to be recreated as functions for use in `ctx.sample()`. Now `ctx.sample()` and `ctx.sample_step()` accept these tool instances directly.
+
+```python
+@mcp.tool
+def search(query: str) -> str:
+    """Search the web."""
+    return do_search(query)
+
+# Use tool directly in sampling
+result = await ctx.sample(
+    "Research Python frameworks",
+    tools=[search]  # FunctionTool works directly!
+)
+```
+
+### Google GenAI Sampling Handler
+
+FastMCP now includes a sampling handler for Google's Gemini models ([#2977](https://github.com/jlowin/fastmcp/pull/2977)). This enables MCP clients to use Google's GenAI models with the sampling protocol, including full tool calling support.
+
+```python
+from fastmcp import Client
+from fastmcp.client.sampling.handlers.google_genai import GoogleGenaiSamplingHandler
+from google.genai import Client as GoogleGenaiClient
+
+# Initialize the handler
+handler = GoogleGenaiSamplingHandler(
+    default_model="gemini-2.0-flash-exp",
+    client=GoogleGenaiClient(),  # Optional - creates one if not provided
+)
+
+# Use with MCP sampling (handler is configured at Client construction)
+async with Client("http://server/mcp", sampling_handler=handler) as client:
+    result = await client.sample(
+        messages=[...],
+        tools=[...],
+    )
+```
+
+Key features:
+- Converts MCP tool schemas to Google's function calling format
+- Supports all Google GenAI models that implement function calling
+- Handles nullable types, nested objects, and arrays in tool schemas
+- Properly maps tool choices (`auto`, `required`, `none`) to Google's configuration
+- Preserves model preferences from MCP sampling parameters
+
+The handler joins the existing Anthropic and OpenAI handlers, providing a consistent interface for model-agnostic sampling across providers.
+
+### Concurrent Tool Execution in Sampling
+
+When an LLM returns multiple tool calls in a single sampling response, they can now be executed concurrently ([#3022](https://github.com/PrefectHQ/fastmcp/pull/3022)). Default behavior remains sequential; opt in with `tool_concurrency`. Tools can declare `sequential=True` to force sequential execution even when concurrency is enabled.
+
+```python
+result = await context.sample(
+    messages="Fetch weather for NYC and LA",
+    tools=[fetch_weather],
+    tool_concurrency=0,  # Unlimited parallel execution
+)
+```
+
+### OpenAPI `validate_output` Option
+
+`OpenAPIProvider` and `FastMCP.from_openapi()` now accept `validate_output=False` to skip output schema validation ([#3134](https://github.com/PrefectHQ/fastmcp/pull/3134)). Useful when backends don't conform to their own OpenAPI response schemas — structured JSON still flows through, only the strict schema checking is disabled.
+
+```python
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    validate_output=False,
+)
+```
+
+### Auth Token Injection and Azure OBO Dependencies
+
+New dependency injection for accessing the authenticated user's token directly in tool parameters ([#2918](https://github.com/PrefectHQ/fastmcp/pull/2918)). Works with any auth provider.
+
+```python
+from fastmcp.server.dependencies import CurrentAccessToken, TokenClaim
+from fastmcp.server.auth import AccessToken
+
+@mcp.tool()
+async def my_tool(
+    token: AccessToken = CurrentAccessToken,
+    user_id: str = TokenClaim("oid"),
+): ...
+```
+
+For Azure/Entra, the new `fastmcp[azure]` extra adds `EntraOBOToken`, which handles the On-Behalf-Of token exchange declaratively:
+
+```python
+from fastmcp.server.auth.providers.azure import EntraOBOToken
+
+@mcp.tool()
+async def get_emails(
+    graph_token: str = EntraOBOToken(["https://graph.microsoft.com/Mail.Read"]),
+):
+    # graph_token is ready — OBO exchange happened automatically
+    ...
+```
+
+### `generate-cli` Agent Skill Generation
+
+`fastmcp generate-cli` now produces a `SKILL.md` alongside the CLI script ([#3115](https://github.com/PrefectHQ/fastmcp/pull/3115)) — a Claude Code agent skill with pre-computed invocation syntax for every tool. Agents reading the skill can call tools immediately without running `--help`. On by default; pass `--no-skill` to opt out.
+
+### Background Task Notification Queue
+
+Background tasks now use a distributed Redis notification queue for reliable delivery ([#2906](https://github.com/PrefectHQ/fastmcp/pull/2906)). Elicitation switches from polling to BLPOP (single blocking call instead of ~7,200 round-trips/hour), and notification delivery retries up to 3x with TTL-based expiration.
+
+### Async Auth Checks
+
+Auth check functions can now be `async`, enabling authorization decisions that depend on asynchronous operations like reading server state via `Context.get_state` or calling external services ([#3150](https://github.com/PrefectHQ/fastmcp/issues/3150)). Sync and async checks can be freely mixed. Previously, passing an async function as an auth check would silently pass (coroutine objects are truthy).
+
+### Optional `$ref` Dereferencing in Schemas
+
+Schema `$ref` dereferencing — which inlines all `$defs` for compatibility with MCP clients that don't handle `$ref` — is now controlled by the `dereference_schemas` constructor kwarg ([#3141](https://github.com/PrefectHQ/fastmcp/issues/3141)). Default is `True` (dereference on) because the non-compliant clients are popular and the failure mode is silent breakage that server authors can't diagnose. Opt out when you know your clients handle `$ref` and want smaller schemas:
+
+```python
+mcp = FastMCP("my-server", dereference_schemas=False)
+```
+
+Dereferencing is implemented as middleware (`DereferenceRefsMiddleware`) that runs at serve-time, so schemas are stored with `$ref` intact and only inlined when sent to clients.
+
+### Breaking: Deprecated `FastMCP()` Constructor Kwargs Removed
+
+Sixteen deprecated keyword arguments have been removed from `FastMCP.__init__`. Passing any of them now raises `TypeError` with a migration hint. Environment variables (e.g., `FASTMCP_HOST`) continue to work — only the constructor kwargs moved.
+
+**Transport/server settings** (`host`, `port`, `log_level`, `debug`, `sse_path`, `message_path`, `streamable_http_path`, `json_response`, `stateless_http`): Pass to `run()`, `run_http_async()`, or `http_app()` as appropriate, or set via environment variables.
+
+```python
+# Before
+mcp = FastMCP("server", host="0.0.0.0", port=8080)
+mcp.run()
+
+# After
+mcp = FastMCP("server")
+mcp.run(transport="http", host="0.0.0.0", port=8080)
+```
+
+**Duplicate handling** (`on_duplicate_tools`, `on_duplicate_resources`, `on_duplicate_prompts`): Use the unified `on_duplicate=` parameter.
+
+**Tag filtering** (`include_tags`, `exclude_tags`): Use `server.enable(tags=..., only=True)` and `server.disable(tags=...)` after construction.
+
+**Tool serializer** (`tool_serializer`): Return `ToolResult` from tools instead.
+
+**Tool transformations** (`tool_transformations`): Use `server.add_transform(ToolTransform(...))` after construction.
+
+The `_deprecated_settings` attribute and `.settings` property are also removed. `ExperimentalSettings` has been deleted (dead code).
+
+### Breaking: `ui=` Renamed to `app=`
+
+The MCP Apps decorator parameter has been renamed from `ui=ToolUI(...)` / `ui=ResourceUI(...)` to `app=AppConfig(...)` ([#3117](https://github.com/PrefectHQ/fastmcp/pull/3117)). `ToolUI` and `ResourceUI` are consolidated into a single `AppConfig` class. Wire format is unchanged. See the MCP Apps section under beta2 for full details.
+## 3.0.0beta2
+
+### CLI: `fastmcp list` and `fastmcp call`
+
+New client-side CLI commands for querying and invoking tools on any MCP server — remote URLs, local Python files, MCPConfig JSON, or arbitrary stdio commands. Especially useful for giving LLMs that don't have built-in MCP support access to MCP tools via shell commands.
+
+```bash
+# Discover tools on a server
+fastmcp list http://localhost:8000/mcp
+fastmcp list server.py
+fastmcp list --command 'npx -y @modelcontextprotocol/server-github'
+
+# Call a tool
+fastmcp call server.py greet name=World
+fastmcp call http://localhost:8000/mcp search query=hello limit=5
+fastmcp call server.py create_item '{"name": "Widget", "tags": ["a", "b"]}'
+```
+
+Key features:
+- Tool arguments are auto-coerced using the tool's JSON schema (`limit=5` → int)
+- Single JSON objects work as positional args alongside `key=value` and `--input-json`
+- `--input-schema` / `--output-schema` for full JSON schemas, `--json` for machine-readable output
+- `--transport sse` for SSE servers, `--command` for stdio servers
+- Auto OAuth for HTTP targets (no-ops if server doesn't require auth)
+- Fuzzy tool name matching suggests alternatives on typos
+- Interactive terminal elicitation for tools that request user input mid-execution
+
+Documentation: [CLI Querying](/cli/client)
+
+### CLI: `fastmcp discover` and name-based resolution
+
+`fastmcp discover` scans editor configs (Claude Desktop, Claude Code, Cursor, Gemini CLI, Goose) and project-level `mcp.json` files for MCP server definitions. Discovered servers can be referenced by name — or `source:name` for precision — in `fastmcp list` and `fastmcp call`.
+
+```bash
+# See all configured servers
+fastmcp discover
+
+# Use a server by name
+fastmcp list weather
+fastmcp call weather get_forecast city=London
+
+# Target a specific source with source:name
+fastmcp list claude-code:my-server
+fastmcp call cursor:weather get_forecast city=London
+
+# Filter discovery to specific sources
+fastmcp discover --source claude-code --source cursor
+```
+
+Documentation: [CLI Querying](/cli/client)
+
+### CLI: Expanded Reload File Watching
+
+The `--reload` flag now watches a comprehensive set of file types, making it suitable for MCP apps with frontend bundles ([#3028](https://github.com/PrefectHQ/fastmcp/pull/3028)). Previously limited to `.py` files, it now watches JavaScript, TypeScript, HTML, CSS, config files, and media assets.
+
+### CLI: fastmcp install stdio
+
+The new `fastmcp install stdio` command generates full `uv run` commands for running FastMCP servers over stdio ([#3032](https://github.com/PrefectHQ/fastmcp/pull/3032)).
+
+```bash
+# Generate command for a server
+fastmcp install stdio server.py
+
+# Outputs:
+# uv run --directory /path/to/project fastmcp run server.py
+```
+
+The command automatically detects the project directory and generates the appropriate `uv run` invocation, making it easy to integrate FastMCP servers with MCP clients.
+
+### CIMD (Client ID Metadata Documents)
+
+CIMD provides an alternative to Dynamic Client Registration for OAuth-authenticated MCP servers. Instead of registering with each server dynamically, clients host a static JSON document at an HTTPS URL. That URL becomes the client's `client_id`, and servers verify identity through domain ownership.
+
+**Client usage:**
+
+```python
+from fastmcp import Client
+from fastmcp.client.auth import OAuth
+
+async with Client(
+    "https://mcp-server.example.com/mcp",
+    auth=OAuth(
+        client_metadata_url="https://myapp.example.com/oauth/client.json",
+    ),
+) as client:
+    await client.ping()
+```
+
+The `OAuth` helper now supports deferred binding — `mcp_url` is optional when using `OAuth` with `Client(auth=...)`, since the transport provides the server URL automatically.
+
+**CLI tools for document management:**
+
+```bash
+# Generate a CIMD document
+fastmcp auth cimd create --name "My App" \
+  --redirect-uri "http://localhost:*/callback" \
+  --client-id "https://myapp.example.com/oauth/client.json" \
+  --output client.json
+
+# Validate a hosted document
+fastmcp auth cimd validate https://myapp.example.com/oauth/client.json
+```
+
+**Server-side support:**
+
+CIMD is enabled by default on `OAuthProxy` and its provider subclasses (GitHub, Google, etc.). The server-side implementation includes SSRF-hardened document fetching with DNS pinning, dual redirect URI validation (both CIMD document patterns and proxy patterns must match), HTTP cache-aware revalidation, and `private_key_jwt` assertion validation for clients that need stronger authentication than public client auth.
+
+Key details:
+- CIMD URLs must be HTTPS with a non-root path
+- `token_endpoint_auth_method` limited to `none` or `private_key_jwt` (no shared secrets)
+- `redirect_uris` in CIMD documents support wildcard port patterns (`http://localhost:*/callback`)
+- Servers fetch and cache documents with standard HTTP caching (ETag, Last-Modified, Cache-Control)
+- CIMD is a protocol-level feature — any auth provider implementing the spec can support it
+
+Documentation: [CIMD Authentication](/clients/auth/cimd), [OAuth Proxy CIMD config](/servers/auth/oauth-proxy#cimd-support)
+
+### Pre-Registered OAuth Clients
+
+The `OAuth` client helper now accepts `client_id` and `client_secret` parameters for servers where the client is already registered ([#3086](https://github.com/PrefectHQ/fastmcp/pull/3086)). This bypasses Dynamic Client Registration entirely — useful when DCR is disabled, or when the server has pre-provisioned credentials for your application.
+
+```python
+from fastmcp import Client
+from fastmcp.client.auth import OAuth
+
+async with Client(
+    "https://mcp-server.example.com/mcp",
+    auth=OAuth(
+        client_id="my-registered-app",
+        client_secret="my-secret",
+        scopes=["read", "write"],
+    ),
+) as client:
+    await client.ping()
+```
+
+The static credentials are injected before the OAuth flow begins, so the client never attempts DCR. If the server rejects the credentials, the error surfaces immediately rather than retrying with fresh registration (which can't help for fixed credentials). Public clients can omit `client_secret`.
+
+Documentation: [Pre-Registered Clients](/clients/auth/oauth#pre-registered-clients)
+
+### CLI: `fastmcp generate-cli`
+
+`fastmcp generate-cli` connects to any MCP server, reads its tool schemas, and writes a standalone Python CLI script where every tool becomes a typed subcommand with flags, help text, and tab completion ([#3065](https://github.com/PrefectHQ/fastmcp/pull/3065)). The insight is that MCP tool schemas already contain everything a CLI framework needs — parameter names, types, descriptions, required/optional status — so the generator maps JSON Schema directly into [cyclopts](https://cyclopts.readthedocs.io/) commands.
+
+```bash
+# Generate from any server spec
+fastmcp generate-cli weather
+fastmcp generate-cli http://localhost:8000/mcp
+fastmcp generate-cli server.py my_weather_cli.py
+
+# Use the generated script
+python my_weather_cli.py call-tool get_forecast --city London --days 3
+python my_weather_cli.py list-tools
+python my_weather_cli.py read-resource docs://readme
+```
+
+The generated script embeds the resolved transport (URL or stdio command), so it's self-contained — users don't need to know about MCP or FastMCP to use it. Supports `-f` to overwrite existing files, and name-based resolution via `fastmcp discover`.
+
+Documentation: [Generate CLI](/cli/generate-cli)
+
+### CLI: Goose Integration
+
+New `fastmcp install goose` command that generates a `goose://extension?...` deeplink URL and opens it, prompting Goose to install the server as a STDIO extension ([#3040](https://github.com/PrefectHQ/fastmcp/pull/3040)). Goose requires `uvx` rather than `uv run`, so the command builds the appropriate invocation automatically.
+
+```bash
+fastmcp install goose server.py
+fastmcp install goose server.py --with pandas --python 3.11
+```
+
+Also adds a full integration guide at [Goose Integration](/integrations/goose).
+
+### ResponseLimitingMiddleware
+
+New middleware for controlling tool response sizes, preventing large outputs from overwhelming LLM context windows ([#3072](https://github.com/PrefectHQ/fastmcp/pull/3072)). Text responses are truncated at UTF-8 character boundaries; structured responses (tools with `output_schema`) raise `ToolError` since truncation would corrupt the schema.
+
+```python
+from fastmcp.server.middleware.response_limiting import ResponseLimitingMiddleware
+
+# Limit all tool responses to 500KB
+mcp.add_middleware(ResponseLimitingMiddleware(max_size=500_000))
+
+# Limit only specific tools, raise errors instead of truncating
+mcp.add_middleware(ResponseLimitingMiddleware(
+    max_size=100_000,
+    tools=["search", "fetch_data"],
+    raise_on_unstructured=True,
+))
+```
+
+Key features:
+- Configurable size limit (default 1MB)
+- Tool-specific filtering via `tools` parameter
+- Size metadata added to result's `meta` field for monitoring
+- Configurable `raise_on_structured` and `raise_on_unstructured` behavior
+
+Documentation: [Middleware](/servers/middleware)
+
+### Background Task Context (SEP-1686)
+
+`Context` now works transparently in background tasks running in Docket workers ([#2905](https://github.com/PrefectHQ/fastmcp/pull/2905)). Previously, tools running as background tasks couldn't use `ctx.elicit()` because there was no active request context. Now, when a tool executes in a Docket worker, `Context` detects this via its `task_id` and routes elicitation through Redis-based coordination: the task sets its status to `input_required`, sends a `notifications/tasks/updated` notification with elicitation metadata, and waits for the client to respond via `tasks/sendInput`.
+
+```python
+@mcp.tool(task=True)
+async def interactive_task(ctx: Context) -> str:
+    # Works transparently in both foreground and background task modes
+    result = await ctx.elicit("Please provide additional input", str)
+
+    if isinstance(result, AcceptedElicitation):
+        return f"You provided: {result.data}"
+    else:
+        return "Elicitation was declined or cancelled"
+```
+
+`ctx.is_background_task` and `ctx.task_id` are available for tools that need to branch on execution mode.
+
+### `require_auth` Removed
+
+The `require_auth` authorization check introduced in beta1 has been removed in favor of scope-based authorization via `require_scopes` ([#3103](https://github.com/PrefectHQ/fastmcp/pull/3103)). Since configuring an `AuthProvider` already rejects unauthenticated requests at the transport level, `require_auth` was redundant — `require_scopes` provides the same guarantee with better granularity. The beta1 Component Authorization section has been updated to reflect this.
+
+### MCP Apps (SDK Compatibility)
+
+Support for [MCP Apps](https://modelcontextprotocol.io/specification/2025-06-18/server/apps) — the spec extension that lets MCP servers deliver interactive UIs via sandboxed iframes. Extension negotiation, typed UI metadata on tools and resources, and the `ui://` resource scheme. No component DSL, renderer, or `FastMCPApp` class yet — those are future phases.
+
+**Breaking change from beta 2:** The `ui=` parameter on `@mcp.tool()` and `@mcp.resource()` has been renamed to `app=`, and the `ToolUI`/`ResourceUI` classes have been consolidated into a single `AppConfig` class. This follows the established `task=True`/`TaskConfig` pattern. The wire format (`meta["ui"]`, `_meta.ui`) is unchanged.
+
+**Registering tools with app metadata:**
+
+```python
+from fastmcp import FastMCP
+from fastmcp.apps import AppConfig, ResourceCSP, ResourcePermissions
+
+mcp = FastMCP("My Server")
+
+# Register the HTML bundle as a ui:// resource with CSP
+@mcp.resource(
+    "ui://my-app/view.html",
+    app=AppConfig(
+        csp=ResourceCSP(resource_domains=["https://unpkg.com"]),
+        permissions=ResourcePermissions(clipboard_write={}),
+    ),
+)
+def app_html() -> str:
+    from pathlib import Path
+    return Path("./dist/index.html").read_text()
+
+# Tool with UI — clients render an iframe alongside the result
+@mcp.tool(app=AppConfig(resource_uri="ui://my-app/view.html"))
+async def list_users() -> list[dict]:
+    return [{"id": "1", "name": "Alice"}]
+
+# App-only tool — visible to the UI but hidden from the model
+@mcp.tool(app=AppConfig(resource_uri="ui://my-app/view.html", visibility=["app"]))
+async def delete_user(id: str) -> dict:
+    return {"deleted": True}
+```
+
+The `app=` parameter accepts `True` (enable with defaults), an `AppConfig` instance, or a raw dict for forward compatibility. It merges into `meta["ui"]` — alongside any other metadata you set.
+
+**`ui://` resources** automatically get the correct MIME type (`text/html;profile=mcp-app`) unless you override it explicitly.
+
+**Extension negotiation**: The server advertises `io.modelcontextprotocol/ui` in `capabilities.extensions`. UI metadata (`_meta.ui`) always flows through to clients — the MCP Apps spec assigns visibility enforcement to the host, not the server. Tools can check whether the connected client supports a given extension at runtime via `ctx.client_supports_extension()`:
+
+```python
+from fastmcp import Context
+from fastmcp.apps import AppConfig, UI_EXTENSION_ID
+
+@mcp.tool(app=AppConfig(resource_uri="ui://dashboard"))
+async def dashboard(ctx: Context) -> dict:
+    data = compute_dashboard()
+    if ctx.client_supports_extension(UI_EXTENSION_ID):
+        return data
+    return {"summary": format_text(data)}
+```
+
+**Key details:**
+- `AppConfig` fields: `resource_uri`, `visibility`, `csp`, `permissions`, `domain`, `prefers_border` (all optional). On resources, `resource_uri` and `visibility` are validated as not-applicable and will raise `ValueError` if set.
+- `csp` accepts a `ResourceCSP` model with structured domain lists: `connect_domains`, `resource_domains`, `frame_domains`, `base_uri_domains`
+- `permissions` accepts a `ResourcePermissions` model: `camera`, `microphone`, `geolocation`, `clipboard_write` (each set to `{}` to request)
+- `AppConfig` uses `extra="allow"` for forward compatibility with future spec additions
+- Models use Pydantic aliases for wire format (`resourceUri`, `prefersBorder`, `connectDomains`, `clipboardWrite`)
+- Resource metadata (including CSP/permissions) is propagated to `resources/read` response content items so hosts can read it when rendering the iframe
+- `ctx.client_supports_extension(id)` is a general-purpose method — works for any extension, not just MCP Apps
+- `structuredContent` in tool results already works via `ToolResult` — MCP Apps clients use this to pass data into the iframe
+- The server does not strip `_meta.ui` for non-UI clients; per the spec, visibility enforcement is the host's responsibility
+
+**Future phases** will add a component DSL for building UIs declaratively, an in-repo renderer, and a `FastMCPApp` class.
+
+Implementation: `fastmcp_slim/fastmcp/apps/config.py` (models and constants), with integration points in `server.py` (decorator parameters), `low_level.py` (extension advertisement), and `context.py` (`client_supports_extension` method).
+
+---
+
+## 3.0.0beta1
+
+### Provider-Based Architecture
+
+v3.0 introduces a provider-based component system that replaces v2's static-only registration ([#2622](https://github.com/PrefectHQ/fastmcp/pull/2622)). Providers dynamically source tools, resources, templates, and prompts at runtime.
+
+**Core abstraction** (`fastmcp_slim/fastmcp/server/providers/base.py`):
+```python
+class Provider:
+    async def list_tools(self) -> Sequence[Tool]: ...
+    async def get_tool(self, name: str) -> Tool | None: ...
+    async def list_resources(self) -> Sequence[Resource]: ...
+    async def get_resource(self, uri: str) -> Resource | None: ...
+    async def list_resource_templates(self) -> Sequence[ResourceTemplate]: ...
+    async def get_resource_template(self, uri: str) -> ResourceTemplate | None: ...
+    async def list_prompts(self) -> Sequence[Prompt]: ...
+    async def get_prompt(self, name: str) -> Prompt | None: ...
+```
+
+Providers support:
+- **Lifecycle management**: `async def lifespan()` for setup/teardown
+- **Visibility control**: `enable()` / `disable()` with name, version, tags, components, and allowlist mode
+- **Transform stacking**: `provider.add_transform(Namespace(...))`, `provider.add_transform(ToolTransform(...))`
+
+### LocalProvider
+
+`LocalProvider` (`fastmcp_slim/fastmcp/server/providers/local_provider.py`) manages components registered via decorators. Can be used standalone and attached to multiple servers:
+
+```python
+from fastmcp.server.providers import LocalProvider
+
+provider = LocalProvider()
+
+@provider.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+# Attach to multiple servers
+server1 = FastMCP("Server1", providers=[provider])
+server2 = FastMCP("Server2", providers=[provider])
+```
+
+### ProxyProvider
+
+`ProxyProvider` (`fastmcp_slim/fastmcp/server/providers/proxy.py`) proxies components from remote MCP servers via a client factory. Used by `create_proxy()` and `FastMCP.mount()` for remote server integration.
+
+```python
+from fastmcp.server import create_proxy
+
+# Create proxy to remote server
+server = create_proxy("http://remote-server/mcp")
+```
+
+### OpenAPIProvider
+
+`OpenAPIProvider` (`fastmcp_slim/fastmcp/server/providers/openapi/provider.py`) creates MCP components from OpenAPI specifications. Routes map HTTP operations to tools, resources, or templates based on configurable rules.
+
+```python
+from fastmcp.server.providers.openapi import OpenAPIProvider
+import httpx
+
+client = httpx.AsyncClient(base_url="https://api.example.com")
+provider = OpenAPIProvider(openapi_spec=spec, client=client)
+
+mcp = FastMCP("API Server", providers=[provider])
+```
+
+Features:
+- Automatic route-to-component mapping (GET → resource, POST/PUT/DELETE → tool)
+- Custom route mappings via `route_maps` or `route_map_fn`
+- Component customization via `mcp_component_fn`
+- Name collision detection and handling
+
+### FastMCPProvider
+
+`FastMCPProvider` (`fastmcp_slim/fastmcp/server/providers/fastmcp_provider.py`) wraps a FastMCP server to enable mounting one server onto another. Components delegate execution through the wrapped server's middleware chain.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers import FastMCPProvider
+from fastmcp.server.transforms import Namespace
+
+main = FastMCP("Main")
+sub = FastMCP("Sub")
+
+@sub.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+# Mount with namespace
+provider = FastMCPProvider(sub)
+provider.add_transform(Namespace("sub"))
+main.add_provider(provider)
+# Tool accessible as "sub_greet"
+```
+
+### Transforms
+
+Transforms modify components (tools, resources, prompts) as they flow from providers to clients ([#2836](https://github.com/PrefectHQ/fastmcp/pull/2836)). They use a middleware pattern where each transform receives a `call_next` callable to continue the chain.
+
+**Built-in transforms** (`fastmcp_slim/fastmcp/server/transforms/`):
+
+- `Namespace` - adds prefixes to names (`tool` → `api_tool`) and path segments to URIs (`data://x` → `data://api/x`)
+- `ToolTransform` - modifies tool schemas (rename, description, tags, argument transforms)
+- `Visibility` - sets visibility state on components by key or tag (backs `enable()`/`disable()` API)
+- `VersionFilter` - filters components by version range (`version_gte`, `version_lt`)
+- `ResourcesAsTools` - exposes resources as tools for tool-only clients
+- `PromptsAsTools` - exposes prompts as tools for tool-only clients
+
+```python
+from fastmcp.server.transforms import Namespace, ToolTransform
+from fastmcp.tools.tool_transform import ToolTransformConfig
+
+provider = SomeProvider()
+provider.add_transform(Namespace("api"))
+provider.add_transform(ToolTransform({
+    "api_verbose_tool_name": ToolTransformConfig(name="short")
+}))
+
+# Stacking composes transformations
+# "foo" → "api_foo" (namespace) → "short" (rename)
+```
+
+**Custom transforms** subclass `Transform` and override needed methods:
+
+```python
+from collections.abc import Sequence
+from fastmcp.server.transforms import Transform, GetToolNext
+from fastmcp.tools import Tool
+
+class TagFilter(Transform):
+    def __init__(self, required_tags: set[str]):
+        self.required_tags = required_tags
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        return [t for t in tools if t.tags & self.required_tags]
+
+    async def get_tool(self, name: str, call_next: GetToolNext) -> Tool | None:
+        tool = await call_next(name)
+        return tool if tool and tool.tags & self.required_tags else None
+```
+
+Transforms apply at two levels:
+- **Provider-level**: `provider.add_transform()` - affects only that provider's components
+- **Server-level**: `server.add_transform()` - affects all components from all providers
+
+Documentation: `docs/servers/transforms/transforms.mdx`, `docs/servers/visibility.mdx`
+
+### ResourcesAsTools and PromptsAsTools
+
+These transforms expose resources and prompts as tools for clients that only support the tools protocol. Each transform generates two tools that provide listing and access functionality.
+
+**ResourcesAsTools** generates `list_resources` and `read_resource` tools:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.transforms import ResourcesAsTools
+
+mcp = FastMCP("Server")
+
+@mcp.resource("data://config")
+def get_config() -> dict:
+    return {"setting": "value"}
+
+mcp.add_transform(ResourcesAsTools(mcp))
+# Now has list_resources and read_resource tools
+```
+
+The `list_resources` tool returns JSON with resource metadata. The `read_resource` tool accepts a URI and returns the resource content, preserving both text and binary data through base64 encoding.
+
+**PromptsAsTools** generates `list_prompts` and `get_prompt` tools:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.transforms import PromptsAsTools
+
+mcp = FastMCP("Server")
+
+@mcp.prompt
+def analyze_code(code: str, language: str = "python") -> str:
+    return f"Analyze this {language} code:\n{code}"
+
+mcp.add_transform(PromptsAsTools(mcp))
+# Now has list_prompts and get_prompt tools
+```
+
+The `list_prompts` tool returns JSON with prompt metadata including argument information. The `get_prompt` tool accepts a prompt name and optional arguments dict, returning the rendered prompt as a messages array. Non-text content (like embedded resources) is preserved as structured JSON.
+
+Both transforms:
+- Capture a provider reference at construction for deferred querying
+- Route through `FastMCP.read_resource()` / `FastMCP.render_prompt()` when the provider is FastMCP, ensuring middleware chains execute
+- Fall back to direct provider methods for plain providers
+- Return JSON for easy parsing by tool-only clients
+
+Documentation: `docs/servers/transforms/resources-as-tools.mdx`, `docs/servers/transforms/prompts-as-tools.mdx`
+
+---
+
+### Session-Scoped State
+
+v3.0 changes context state from request-scoped to session-scoped. State now persists across multiple tool calls within the same MCP session.
+
+```python
+@mcp.tool
+async def increment_counter(ctx: Context) -> int:
+    count = await ctx.get_state("counter") or 0
+    await ctx.set_state("counter", count + 1)
+    return count + 1
+```
+
+State is automatically keyed by session ID, ensuring isolation between different clients. The implementation uses [pykeyvalue](https://github.com/strawgate/py-key-value) for pluggable storage backends:
+
+```python
+from key_value.aio.stores.redis import RedisStore
+
+# Use Redis for distributed deployments
+mcp = FastMCP("server", session_state_store=RedisStore(...))
+```
+
+**Key details:**
+- Methods are now async: `await ctx.get_state()`, `await ctx.set_state()`, `await ctx.delete_state()`
+- State expires after 1 day (TTL) to prevent unbounded memory growth
+- Works during `on_initialize` middleware when using the same session object
+- For distributed HTTP, session identity comes from the `mcp-session-id` header
+
+Documentation: `docs/servers/context.mdx`
+
+---
+
+### Visibility System
+
+Components can be enabled/disabled using the visibility system. Each `enable()` or `disable()` call adds a stateless Visibility transform that marks components via internal metadata. Later transforms override earlier ones.
+
+```python
+mcp = FastMCP("Server")
+
+# Disable by name and component type
+mcp.disable(names={"dangerous_tool"}, components=["tool"])
+
+# Disable by tag
+mcp.disable(tags={"admin"})
+
+# Disable by version
+mcp.disable(names={"old_tool"}, version="1.0", components=["tool"])
+
+# Allowlist mode - only show components with these tags
+mcp.enable(tags={"public"}, only=True)
+
+# Enable overrides earlier disable (later transform wins)
+mcp.disable(tags={"internal"})
+mcp.enable(names={"safe_tool"})  # safe_tool is visible despite internal tag
+```
+
+Works at both server and provider level. Supports:
+- **Blocklist mode** (default): All components visible except explicitly disabled
+- **Allowlist mode** (`only=True`): Only explicitly enabled components visible
+- **Tag-based filtering**: Enable/disable groups of components by tag
+- **Override semantics**: Later transforms override earlier marks (enable after disable = enabled)
+- **Transform ordering**: Visibility transforms are injected at the point you call them, so component state is known
+
+#### Per-Session Visibility
+
+Server-level visibility changes affect all connected clients. For per-session control, use `Context` methods that apply rules only to the current session ([#2917](https://github.com/PrefectHQ/fastmcp/pull/2917)):
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.context import Context
+
+mcp = FastMCP("Server")
+
+@mcp.tool(tags={"premium"})
+def premium_analysis(data: str) -> str:
+    return f"Premium analysis of: {data}"
+
+@mcp.tool
+async def unlock_premium(ctx: Context) -> str:
+    """Unlock premium features for this session only."""
+    await ctx.enable_components(tags={"premium"})
+    return "Premium features unlocked"
+
+@mcp.tool
+async def reset_features(ctx: Context) -> str:
+    """Reset to default feature set."""
+    await ctx.reset_visibility()
+    return "Features reset to defaults"
+
+# Globally disabled - sessions unlock individually
+mcp.disable(tags={"premium"})
+```
+
+Session visibility methods:
+- `await ctx.enable_components(...)`: Enable components for this session
+- `await ctx.disable_components(...)`: Disable components for this session
+- `await ctx.reset_visibility()`: Clear session rules, return to global defaults
+
+Session rules override global transforms. FastMCP automatically sends `ToolListChangedNotification` (and resource/prompt equivalents) to affected sessions when visibility changes.
+
+Documentation: `docs/servers/visibility.mdx`
+
+---
+
+### Component Versioning
+
+v3.0 introduces versioning support for tools, resources, and prompts. Components can declare a version, and when multiple versions of the same component exist, the highest version is automatically exposed to clients.
+
+**Declaring versions:**
+
+```python
+@mcp.tool(version="1.0")
+def add(x: int, y: int) -> int:
+    return x + y
+
+@mcp.tool(version="2.0")
+def add(x: int, y: int, z: int = 0) -> int:
+    return x + y + z
+
+# Only v2.0 is exposed to clients via list_tools()
+# Calling "add" invokes the v2.0 implementation
+```
+
+**Version comparison:**
+- Uses PEP 440 semantic versioning (1.10 > 1.9 > 1.2)
+- Falls back to string comparison for non-PEP 440 versions (dates like `2025-01-15` work)
+- Unversioned components sort lower than any versioned component
+- The `v` prefix is normalized (`v1.0` equals `1.0`)
+
+**Version visibility in meta:**
+
+List operations expose all available versions in the component's `meta` field:
+
+```python
+tools = await client.list_tools()
+# Each tool's meta includes:
+# - meta["fastmcp"]["version"]: the version of this component ("2.0")
+# - meta["fastmcp"]["versions"]: all available versions ["2.0", "1.0"]
+```
+
+**Retrieving and calling specific versions:**
+
+```python
+# Get the highest version (default)
+tool = await server.get_tool("add")
+
+# Get a specific version
+tool_v1 = await server.get_tool("add", version="1.0")
+
+# Call a specific version
+result = await server.call_tool("add", {"x": 1, "y": 2}, version="1.0")
+```
+
+**Client version requests:**
+
+The FastMCP client supports version selection:
+
+```python
+async with Client(server) as client:
+    # Call specific tool version
+    result = await client.call_tool("add", {"x": 1, "y": 2}, version="1.0")
+
+    # Get specific prompt version
+    prompt = await client.get_prompt("my_prompt", {"text": "..."}, version="2.0")
+```
+
+For generic MCP clients, pass version via `_meta` in arguments:
+
+```json
+{
+  "x": 1,
+  "y": 2,
+  "_meta": {
+    "fastmcp": {
+      "version": "1.0"
+    }
+  }
+}
+```
+
+**VersionFilter transform:**
+
+The `VersionFilter` transform enables serving different API versions from a single codebase:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers import LocalProvider
+from fastmcp.server.transforms import VersionFilter
+
+# Define components on a shared provider
+components = LocalProvider()
+
+@components.tool(version="1.0")
+def calculate(x: int, y: int) -> int:
+    return x + y
+
+@components.tool(version="2.0")
+def calculate(x: int, y: int, z: int = 0) -> int:
+    return x + y + z
+
+# Create servers that share the provider with different filters
+api_v1 = FastMCP("API v1", providers=[components])
+api_v1.add_transform(VersionFilter(version_lt="2.0"))
+
+api_v2 = FastMCP("API v2", providers=[components])
+api_v2.add_transform(VersionFilter(version_gte="2.0"))
+```
+
+Parameters mirror comparison operators:
+- `version_gte`: Versions >= this value pass through
+- `version_lt`: Versions < this value pass through
+
+**Key format:**
+
+Component keys now include a version suffix using `@` as a delimiter:
+- Versioned: `tool:add@1.0`, `resource:data://config@2.0`
+- Unversioned: `tool:add@`, `resource:data://config@`
+
+The `@` is always present (even for unversioned components) to enable unambiguous parsing of URIs that may contain `@`.
+
+---
+
+### Type-Safe Canonical Results
+
+v3.0 introduces type-safe result classes that provide explicit control over component responses while supporting MCP runtime metadata: `ToolResult` ([#2736](https://github.com/PrefectHQ/fastmcp/pull/2736)), `ResourceResult` ([#2734](https://github.com/PrefectHQ/fastmcp/pull/2734)), and `PromptResult` ([#2738](https://github.com/PrefectHQ/fastmcp/pull/2738)).
+
+#### ToolResult
+
+`ToolResult` (`fastmcp_slim/fastmcp/tools/tool.py:79`) provides structured tool responses:
+
+```python
+from fastmcp.tools import ToolResult
+
+@mcp.tool
+def process(data: str) -> ToolResult:
+    return ToolResult(
+        content=[TextContent(type="text", text="Done")],
+        structured_content={"status": "success", "count": 42},
+        meta={"processing_time_ms": 150}
+    )
+```
+
+Fields:
+- `content`: List of MCP ContentBlocks (text, images, etc.)
+- `structured_content`: Dict matching tool's output schema
+- `meta`: Runtime metadata passed to MCP as `_meta`
+
+#### ResourceResult
+
+`ResourceResult` (`fastmcp_slim/fastmcp/resources/resource.py:117`) provides structured resource responses:
+
+```python
+from fastmcp.resources import ResourceResult, ResourceContent
+
+@mcp.resource("data://items")
+def get_items() -> ResourceResult:
+    return ResourceResult(
+        contents=[
+            ResourceContent({"key": "value"}),  # auto-serialized to JSON
+            ResourceContent(b"binary data"),
+        ],
+        meta={"count": 2}
+    )
+```
+
+Accepts strings, bytes, or `list[ResourceContent]` for flexible content handling.
+
+#### PromptResult
+
+`PromptResult` (`fastmcp_slim/fastmcp/prompts/prompt.py:109`) provides structured prompt responses:
+
+```python
+from fastmcp.prompts import PromptResult, Message
+
+@mcp.prompt
+def conversation() -> PromptResult:
+    return PromptResult(
+        messages=[
+            Message("What's the weather?"),
+            Message("It's sunny today.", role="assistant"),
+        ],
+        meta={"generated_at": "2024-01-01"}
+    )
+```
+
+---
+
+### Background Tasks (SEP-1686)
+
+v3.0 implements MCP SEP-1686 for background task execution via Docket integration.
+
+**Configuration** (`fastmcp_slim/fastmcp/server/tasks/config.py`):
+
+```python
+from fastmcp.server.tasks import TaskConfig
+
+@mcp.tool(task=TaskConfig(mode="required"))
+async def long_running_task():
+    # Must be executed as background task
+    ...
+
+@mcp.tool(task=TaskConfig(mode="optional"))
+async def flexible_task():
+    # Supports both sync and task execution
+    ...
+
+@mcp.tool(task=True)  # Shorthand for mode="optional"
+async def simple_task():
+    ...
+```
+
+Task modes:
+- `"forbidden"`: Component does not support task execution (default)
+- `"optional"`: Supports both synchronous and task execution
+- `"required"`: Must be executed as background task
+
+Requires Docket server for task scheduling and result polling.
+
+---
+
+### Decorators Return Functions
+
+v3.0 changes what decorators (`@tool`, `@resource`, `@prompt`) return ([#2856](https://github.com/PrefectHQ/fastmcp/pull/2856)). Decorators now return the original function unchanged, rather than transforming it into a component object.
+
+**v3 behavior (default):**
+```python
+@mcp.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+# greet is still your function - call it directly
+greet("World")  # "Hello, World!"
+```
+
+**Why this matters:**
+- Functions stay callable - useful for testing and reuse
+- Instance methods just work: `mcp.add_tool(obj.method)`
+- Matches how Flask, FastAPI, and Typer decorators behave
+
+**For v2 compatibility:**
+
+```python
+import fastmcp
+
+# v2 behavior: decorators return FunctionTool/FunctionResource/FunctionPrompt objects
+fastmcp.settings.decorator_mode = "object"
+```
+
+Environment variable: `FASTMCP_DECORATOR_MODE=object`
+
+---
+
+### CLI Auto-Reload
+
+The `--reload` flag enables file watching with automatic server restarts for development ([#2816](https://github.com/PrefectHQ/fastmcp/pull/2816)).
+
+```bash
+# Watch for changes and restart
+fastmcp run server.py --reload
+
+# Watch specific directories
+fastmcp run server.py --reload --reload-dir ./src --reload-dir ./lib
+
+# Works with any transport
+fastmcp run server.py --reload --transport http --port 8080
+```
+
+Implementation (`fastmcp_slim/fastmcp/cli/run.py`):
+- Uses `watchfiles` for efficient file monitoring
+- Runs server as subprocess for clean restarts
+- Stateless mode for seamless reconnection after restart
+- stdio: Full MCP features including elicitation
+- HTTP: Limited bidirectional features during reload
+
+Also available with `fastmcp dev inspector`:
+```bash
+fastmcp dev inspector server.py  # Includes --reload by default
+```
+
+---
+
+### Component Authorization
+
+v3.0 introduces callable-based authorization for tools, resources, and prompts ([#2855](https://github.com/PrefectHQ/fastmcp/pull/2855)).
+
+**Component-level auth**:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import require_scopes
+
+mcp = FastMCP()
+
+@mcp.tool(auth=require_scopes("write"))
+def protected_tool(): ...
+
+@mcp.resource("data://secret", auth=require_scopes("read"))
+def secret_data(): ...
+
+@mcp.prompt(auth=require_scopes("admin"))
+def admin_prompt(): ...
+```
+
+**Server-wide auth via middleware**:
+
+```python
+from fastmcp.server.middleware import AuthMiddleware
+from fastmcp.server.auth import require_scopes, restrict_tag
+
+# Require specific scope for all components
+mcp = FastMCP(middleware=[AuthMiddleware(auth=require_scopes("api"))])
+
+# Tag-based restrictions
+mcp = FastMCP(middleware=[
+    AuthMiddleware(auth=restrict_tag("admin", scopes=["admin"]))
+])
+```
+
+Built-in checks:
+- `require_scopes(*scopes)`: Requires specific OAuth scopes
+- `restrict_tag(tag, scopes)`: Requires scopes only for tagged components
+
+Custom checks receive `AuthContext` with `token` and `component`:
+
+```python
+def custom_check(ctx: AuthContext) -> bool:
+    return ctx.token is not None and "admin" in ctx.token.scopes
+```
+
+STDIO transport bypasses all auth checks (no OAuth concept).
+
+---
+
+### FileSystemProvider
+
+v3.0 introduces `FileSystemProvider`, a fundamentally different approach to organizing MCP servers. Instead of importing a server instance and decorating functions with `@server.tool`, you use standalone decorators in separate files and let the provider discover them.
+
+**The problem it solves**: Traditional servers require coordination between files—either tool files import the server (creating coupling) or the server imports all tool modules (creating a registry bottleneck). FileSystemProvider removes this coupling entirely.
+
+**Usage** ([#2823](https://github.com/PrefectHQ/fastmcp/pull/2823)):
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers import FileSystemProvider
+
+# Scans mcp/ directory for decorated functions
+mcp = FastMCP("server", providers=[FileSystemProvider("mcp/")])
+```
+
+**Tool files are self-contained**:
+
+```python
+# mcp/tools/greet.py
+from fastmcp.tools import tool
+
+@tool
+def greet(name: str) -> str:
+    """Greet someone by name."""
+    return f"Hello, {name}!"
+```
+
+Features:
+- **Standalone decorators**: `@tool`, `@resource`, `@prompt` from `fastmcp.tools`, `fastmcp.resources`, `fastmcp.prompts` ([#2832](https://github.com/PrefectHQ/fastmcp/pull/2832))
+- **Reload mode**: `FileSystemProvider("mcp/", reload=True)` re-scans on every request for development
+- **Package support**: Directories with `__init__.py` support relative imports
+- **Warning deduplication**: Broken imports warn once per file modification
+
+Documentation: [FileSystemProvider](/servers/providers/filesystem)
+
+---
+
+### SkillsProvider
+
+v3.0 introduces `SkillsProvider` for exposing agent skills as MCP resources ([#2944](https://github.com/PrefectHQ/fastmcp/pull/2944)). Skills are directories containing instructions and supporting files that teach AI assistants how to perform tasks—used by Claude Code, Cursor, VS Code Copilot, and other AI coding tools.
+
+**Usage**:
+
+```python
+from pathlib import Path
+from fastmcp import FastMCP
+from fastmcp.server.providers.skills import SkillsDirectoryProvider
+
+mcp = FastMCP("Skills Server")
+mcp.add_provider(SkillsDirectoryProvider(roots=Path.home() / ".claude" / "skills"))
+```
+
+Each subdirectory with a `SKILL.md` file becomes a discoverable skill. Clients see:
+- `skill://{name}/SKILL.md` - Main instruction file
+- `skill://{name}/_manifest` - JSON listing of all files with sizes and hashes
+- `skill://{name}/{path}` - Supporting files (via template or resources)
+
+**Two-layer architecture**:
+- `SkillProvider` - Handles a single skill folder
+- `SkillsDirectoryProvider` - Scans directories, creates a `SkillProvider` per valid skill
+
+**Vendor providers** with locked default paths:
+
+| Provider | Directory |
+|----------|-----------|
+| `ClaudeSkillsProvider` | `~/.claude/skills/` |
+| `CursorSkillsProvider` | `~/.cursor/skills/` |
+| `VSCodeSkillsProvider` | `~/.copilot/skills/` |
+| `CodexSkillsProvider` | `/etc/codex/skills/`, `~/.codex/skills/` |
+| `GeminiSkillsProvider` | `~/.gemini/skills/` |
+| `GooseSkillsProvider` | `~/.config/agents/skills/` |
+| `CopilotSkillsProvider` | `~/.copilot/skills/` |
+| `OpenCodeSkillsProvider` | `~/.config/opencode/skills/` |
+
+**Progressive disclosure**: By default, supporting files are hidden from `list_resources()` and accessed via template. Set `supporting_files="resources"` for full enumeration.
+
+Documentation: [Skills Provider](/servers/providers/skills)
+
+---
+
+### OpenTelemetry Tracing
+
+v3.0 adds OpenTelemetry instrumentation for observability into server and client operations ([#2869](https://github.com/PrefectHQ/fastmcp/pull/2869)).
+
+**Server spans**: Created for tool calls, resource reads, and prompt renders with attributes including component key, provider type, session ID, and auth context.
+
+**Client spans**: Wrap outgoing calls with W3C trace context propagation via request meta.
+
+```python
+# Tracing is passive - configure an OTel SDK to export spans
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+
+provider = TracerProvider()
+provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
+trace.set_tracer_provider(provider)
+
+# Use fastmcp normally - spans export to your configured backend
+```
+
+Components provide their own span attributes through a `get_span_attributes()` method that subclasses override—this lets LocalProvider, FastMCPProvider, and ProxyProvider each include relevant context (original names, backend URIs, etc.).
+
+Documentation: [Telemetry](/servers/telemetry)
+
+---
+
+### Pagination
+
+v3.0 adds pagination support for list operations when servers expose many components ([#2903](https://github.com/PrefectHQ/fastmcp/pull/2903)).
+
+```python
+from fastmcp import FastMCP
+
+# Enable pagination with 50 items per page
+server = FastMCP("ComponentRegistry", list_page_size=50)
+```
+
+When `list_page_size` is set, `tools/list`, `resources/list`, `resources/templates/list`, and `prompts/list` paginate responses with `nextCursor` for subsequent pages.
+
+**Client behavior**: The FastMCP Client fetches all pages automatically—`list_tools()` and similar methods return the complete list. For manual pagination (memory constraints, progress reporting), use `_mcp` variants:
+
+```python
+async with Client(server) as client:
+    result = await client.list_tools_mcp()
+    while result.next_cursor:
+        result = await client.list_tools_mcp(cursor=result.next_cursor)
+```
+
+Documentation: [Pagination](/servers/pagination)
+
+---
+
+### Composable Lifespans
+
+Lifespans can be combined with the `|` operator for modular setup/teardown ([#2828](https://github.com/PrefectHQ/fastmcp/pull/2828)):
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.lifespan import lifespan
+
+@lifespan
+async def db_lifespan(server):
+    db = await connect_db()
+    try:
+        yield {"db": db}
+    finally:
+        await db.close()
+
+@lifespan
+async def cache_lifespan(server):
+    cache = await connect_cache()
+    try:
+        yield {"cache": cache}
+    finally:
+        await cache.close()
+
+mcp = FastMCP("server", lifespan=db_lifespan | cache_lifespan)
+```
+
+Both enter lifespans in order and exit in reverse (LIFO). Context dicts are merged.
+
+Also adds `combine_lifespans()` utility for FastAPI integration:
+
+```python
+from fastmcp.utilities.lifespan import combine_lifespans
+
+app = FastAPI(lifespan=combine_lifespans(app_lifespan, mcp_app.lifespan))
+```
+
+Documentation: [Lifespan](/servers/lifespan)
+
+---
+
+### Tool Timeout
+
+Tools can limit foreground execution time with a `timeout` parameter ([#2872](https://github.com/PrefectHQ/fastmcp/pull/2872)):
+
+```python
+@mcp.tool(timeout=30.0)
+async def fetch_data(url: str) -> dict:
+    """Fetch with 30-second timeout."""
+    ...
+```
+
+When exceeded, clients receive MCP error code `-32000`. Both sync and async tools are supported—sync functions run in thread pools so the timeout applies regardless of execution model.
+
+Note: This timeout applies to foreground execution only. Background tasks (`task=True`) execute in Docket workers where this timeout isn't enforced.
+
+---
+
+### PingMiddleware
+
+Sends periodic server-to-client pings to keep long-lived connections alive ([#2838](https://github.com/PrefectHQ/fastmcp/pull/2838)):
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.middleware import PingMiddleware
+
+mcp = FastMCP("server")
+mcp.add_middleware(PingMiddleware(interval_ms=5000))
+```
+
+The middleware starts a background ping task on first message from each session, using the session's existing task group for automatic cleanup when the session ends.
+
+---
+
+### Context.transport Property
+
+Tools can detect which transport is active ([#2850](https://github.com/PrefectHQ/fastmcp/pull/2850)):
+
+```python
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP("example")
+
+@mcp.tool
+def my_tool(ctx: Context) -> str:
+    if ctx.transport == "stdio":
+        return "short response"
+    return "detailed response with more context"
+```
+
+Returns `Literal["stdio", "sse", "streamable-http"]` when running, or `None` outside a server context.
+
+---
+
+### Automatic Threadpool for Sync Functions
+
+Synchronous tools, resources, and prompts now automatically run in a threadpool, preventing event loop blocking during concurrent requests ([#2865](https://github.com/PrefectHQ/fastmcp/pull/2865)):
+
+```python
+import time
+
+@mcp.tool
+def slow_tool():
+    time.sleep(10)  # No longer blocks other requests
+    return "done"
+```
+
+Three concurrent calls now execute in parallel (~10s) rather than sequentially (30s). Uses `anyio.to_thread.run_sync()` which properly propagates contextvars, so `Context` and `Depends` continue to work.
+
+---
+
+### CLI Update Notifications
+
+The CLI notifies users when a newer FastMCP version is available on PyPI ([#2840](https://github.com/PrefectHQ/fastmcp/pull/2840)).
+
+**Setting**: `FASTMCP_CHECK_FOR_UPDATES`
+- `"stable"` - Check for stable releases (default)
+- `"prerelease"` - Include alpha/beta/rc versions
+- `"off"` - Disable
+
+12-hour cache, 2-second timeout, fails silently on network errors.
+
+---
+
+### Deprecated Features
+
+These emit deprecation warnings but continue to work.
+
+#### Mount Prefix Parameter
+
+The `prefix` parameter for `mount()` renamed to `namespace`:
+
+```python
+# Deprecated
+main.mount(subserver, prefix="api")
+
+# New
+main.mount(subserver, namespace="api")
+```
+
+#### Tag Filtering, Tool Serializer, Tool Transformations Init Parameters
+
+These constructor parameters have been **removed** (not just deprecated) as of rc1. See "Breaking: Deprecated `FastMCP()` Constructor Kwargs Removed" in the rc1 section above. The `add_tool_transformation()` and `remove_tool_transformation()` methods remain as deprecated shims.
+
+---
+
+### Breaking Changes
+
+#### WSTransport Removed
+
+The deprecated `WSTransport` client transport has been removed ([#2826](https://github.com/PrefectHQ/fastmcp/pull/2826)). Use `StreamableHttpTransport` instead.
+
+#### Decorators Return Functions
+
+Decorators (`@tool`, `@resource`, `@prompt`) now return the original function instead of component objects. Code that treats the decorated function as a `FunctionTool`, `FunctionResource`, or `FunctionPrompt` will break.
+
+```python
+# v2.x
+@mcp.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+isinstance(greet, FunctionTool)  # True
+
+# v3.0
+@mcp.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+isinstance(greet, FunctionTool)  # False
+callable(greet)                  # True - it's still your function
+greet("World")                   # "Hello, World!"
+```
+
+Set `FASTMCP_DECORATOR_MODE=object` or `fastmcp.settings.decorator_mode = "object"` for v2 behavior.
+
+#### Component Enable/Disable Moved to Server/Provider
+
+The `enabled` field and `enable()`/`disable()` methods removed from component objects:
+
+```python
+# v2.x
+tool = await server.get_tool("my_tool")
+tool.disable()
+
+# v3.0
+server.disable(names={"my_tool"}, components=["tool"])
+```
+
+#### Component Lookup Methods
+
+Server lookup and listing methods have updated signatures:
+
+- Parameter names: `get_tool(name=...)`, `get_resource(uri=...)`, etc. (was `key`)
+- Plural listing methods renamed: `get_tools()` → `list_tools()`, `get_resources()` → `list_resources()`, etc.
+- Return types: `list_tools()`, `list_resources()`, etc. return lists instead of dicts
+
+```python
+# v2.x
+tools = await server.get_tools()
+tool = tools["my_tool"]
+
+# v3.0
+tools = await server.list_tools()
+tool = next((t for t in tools if t.name == "my_tool"), None)
+```
+
+#### Prompt Return Types
+
+Prompt functions now use `Message` instead of `mcp.types.PromptMessage`:
+
+```python
+# v2.x
+from fastmcp.types import PromptMessage, TextContent
+
+@mcp.prompt
+def my_prompt() -> PromptMessage:
+    return PromptMessage(role="user", content=TextContent(type="text", text="Hello"))
+
+# v3.0
+from fastmcp.prompts import Message
+
+@mcp.prompt
+def my_prompt() -> Message:
+    return Message("Hello")  # role defaults to "user"
+```
+
+#### Auth Provider Environment Variables Removed
+
+Auth providers no longer auto-load from environment variables ([#2752](https://github.com/PrefectHQ/fastmcp/pull/2752)):
+
+```python
+# v2.x - auto-loaded from FASTMCP_SERVER_AUTH_GITHUB_*
+auth = GitHubProvider()
+
+# v3.0 - explicit configuration
+import os
+auth = GitHubProvider(
+    client_id=os.environ["GITHUB_CLIENT_ID"],
+    client_secret=os.environ["GITHUB_CLIENT_SECRET"],
+)
+```
+
+See `docs/development/v3-notes/auth-provider-env-vars.mdx` for rationale.
+
+#### Server Banner Environment Variable
+
+`FASTMCP_SHOW_CLI_BANNER` → `FASTMCP_SHOW_SERVER_BANNER` ([#2771](https://github.com/PrefectHQ/fastmcp/pull/2771))
+
+Now applies to all server startup methods, not just the CLI.
+
+#### Context State Methods Are Async
+
+`ctx.set_state()` and `ctx.get_state()` are now async and session-scoped:
+
+```python
+# v2.x
+ctx.set_state("key", "value")
+value = ctx.get_state("key")
+
+# v3.0
+await ctx.set_state("key", "value")
+value = await ctx.get_state("key")
+```
+
+State now persists across requests within a session. See "Session-Scoped State" above.
diff --git a/docs/development/v4-notes/change-register.mdx b/docs/development/v4-notes/change-register.mdx
new file mode 100644
index 0000000..6476d96
--- /dev/null
+++ b/docs/development/v4-notes/change-register.mdx
@@ -0,0 +1,340 @@
+---
+title: Change Register
+---
+
+This is the complete register of user-facing changes from the MCP Python SDK v2 migration ([PR #4437](https://github.com/PrefectHQ/fastmcp/pull/4437)), organized by subsystem. It doubles as a review lens: take one subsystem, read its claimed changes, and verify each against the diff.
+
+Each entry is tagged **Absorbed** (public surface unchanged), **Bridged** (shim keeps old code working, usually warning), **Breaking** (user code must change), or **Deprecated** (works, warns, slated for removal). See the [overview](/development/v4-notes/index) for what each disposition means.
+
+**Empirical validation (WS2 upgrade reality-check).** The register's compatibility claims are verified, not predicted. Running unchanged 3.x-era code against this branch, all 11 upgrade scenarios pass or warn — the only failures are the two predicted breaks, user `mcp.types` imports and positional `McpError(ErrorData(...))` construction. Cross-version wire interop between a 3.4.3 peer and this branch is bidirectionally clean across 9 operations (3.4.3 client ↔ v4 server and v4 client ↔ 3.4.3 server over HTTP). All 25 `_ALIASES` bridge entries warn correctly with actionable messages.
+
+## Environment
+
+### Dependency floors: pydantic >= 2.12, Starlette >= 1.0 — Breaking (environment)
+
+The SDK v2 raises FastMCP's dependency floors. Projects pinning an older pydantic (e.g. `2.11.*`) hit an unsatisfiable-resolution error at install time and must bump their pin; unpinned projects get pydantic upgraded silently. The server extra floors Starlette at `>=1.0.1` — modern FastAPI (0.11x+) already runs Starlette 1.x, so coexistence is clean (verified with FastAPI 0.138.2); only very old FastAPI pinned below Starlette 1.0 conflicts. Both are documented in the [upgrade guide's Environment requirements](/getting-started/upgrading/from-fastmcp-3#environment-requirements).
+
+*Verify:* `fastmcp_slim/pyproject.toml` (`pydantic[email]>=2.12.0` core, `starlette>=1.0.1` server extra); WS2 environment-upgrade scenario.
+
+## Types and imports
+
+The SDK v2 split protocol types into a standalone `mcp_types` package and renamed every field from camelCase to snake_case. This is the single largest source of user-facing change, and FastMCP absorbs nearly all of it.
+
+### `mcp.types` split into `mcp_types` — Breaking (by omission)
+
+The `mcp.types` module no longer exists. Any `from mcp.types import X` or `import mcp.types` in user code raises `ImportError`. This is the one import change users cannot avoid.
+
+*Verify:* `fastmcp_slim/fastmcp/types.py`, and grep the diff for the doc migration `from mcp.types import` → `from fastmcp.types import` (30 sites).
+
+### `fastmcp.types` is the stable home — Bridged
+
+FastMCP re-exports the protocol types users are most likely to touch from `fastmcp.types`, sourced from `mcp_types` (the `mcp` root package lacks most of them):
+
+```python
+from fastmcp.types import TextContent, Tool, ToolAnnotations, ErrorData
+```
+
+The re-export set is deliberately limited to names that trace to a documented user import: `TextContent`, `ImageContent`, `AudioContent`, `EmbeddedResource`, `ResourceLink`, `ContentBlock`, `Tool`, `Resource`, `ResourceTemplate`, `Prompt`, `PromptMessage`, `CallToolResult`, `GetPromptResult`, `ReadResourceResult`, `TextResourceContents`, `BlobResourceContents`, `SamplingMessage`, `CreateMessageResult`, `SamplingCapability`, `Root`, `ErrorData`, `Completion`, `Annotations`, `ToolAnnotations`, `Icon`, `ToolResultContent`, plus the pre-existing `Textarea`. Notification and request wrapper types (e.g. `ToolListChangedNotification`) are not re-exported — import those from `mcp_types` directly.
+
+*Verify:* `fastmcp_slim/fastmcp/types.py` `__all__`.
+
+### camelCase field reads are bridged — Bridged (deprecated)
+
+Objects FastMCP hands back — results of `client.list_tools()`, `client.call_tool_mcp()`, `client.read_resource()`, and the parameter objects passed to sampling and elicitation handlers — are SDK v2 objects with snake_case fields. A compatibility bridge installed at import time routes the old camelCase names to their snake_case fields, warning once per read:
+
+```python
+from fastmcp import Client
+
+
+async def read_schema():
+    async with Client("my_mcp_server.py") as client:
+        tools = await client.list_tools()
+        return tools[0].inputSchema  # works, warns; prefer .input_schema
+```
+
+The bridged fields are exactly those users read, data-driven from an `_ALIASES` table: `inputSchema`/`outputSchema` (Tool); `mimeType` (Resource, ResourceTemplate, TextResourceContents, BlobResourceContents, ImageContent, AudioContent) and `uriTemplate` (ResourceTemplate); `isError`/`structuredContent` (CallToolResult); `hasMore` (Completion); `serverInfo`/`protocolVersion` (InitializeResult); `nextCursor`/`resourceTemplates` (List\*Result); `systemPrompt`/`maxTokens`/`stopSequences`/`modelPreferences`/`toolChoice` (CreateMessageRequestParams); `requestedSchema` (ElicitRequestFormParams). WS2 verified all 25 alias entries warn correctly with actionable messages.
+
+*Verify:* `fastmcp_slim/fastmcp/_compat.py` (the `_ALIASES` table and `install()`).
+
+### The bridge is a genuine runtime toggle — Absorbed (post-review fix)
+
+The bridge properties install unconditionally, and each getter reads the live `mcp_camelcase_compat` setting on every access: warn-and-return when enabled, raise `AttributeError` when disabled. An earlier version installed the bridge once at import, so flipping the setting afterward did nothing — commit `d9659453` fixed this so the toggle works at runtime:
+
+```python
+import fastmcp
+
+fastmcp.settings.mcp_camelcase_compat = False  # now takes effect immediately
+```
+
+The setting is documented in [Settings](/more/settings) as `FASTMCP_MCP_CAMELCASE_COMPAT`.
+
+*Verify:* `fastmcp_slim/fastmcp/settings.py` (setting), `fastmcp_slim/fastmcp/_compat.py` (per-read gate), commit `d9659453`.
+
+### `mcp-types` is now a core slim dependency — Absorbed (post-review fix)
+
+Bare `import fastmcp` loads `mcp_types` via `_sdk_patches` and `_compat`, so a bare `fastmcp-slim` install (without the `[mcp]` extra) hit `ModuleNotFoundError`. Because `mcp-types` only pulls `pydantic` and `typing-extensions` (already core), it was promoted to a core dependency while the full `mcp` SDK stays in the `[mcp]` extra.
+
+*Verify:* `fastmcp_slim/pyproject.toml` (`mcp-types==2.0.0b1` in core dependencies), commit `e16ffad4`.
+
+### `McpError` is an alias; construction changed — Bridged (catch) / Breaking (construct)
+
+`fastmcp.exceptions.McpError` is a plain alias of the SDK's `MCPError` — a plain alias, not a subclass, so `except McpError` still catches SDK-raised errors and `err.error.code` still reads:
+
+```python
+from fastmcp.exceptions import McpError
+
+try:
+    ...
+except McpError as err:
+    print(err.error.code)  # unchanged
+```
+
+Construction is the one unavoidable behavior break. The v1 pattern of wrapping an `ErrorData` positionally raises `TypeError` under v2; construct with keywords instead:
+
+```python
+from fastmcp.exceptions import McpError
+
+# Before (raises TypeError under SDK v2):
+#   raise McpError(ErrorData(code=-32000, message="Client not supported"))
+
+raise McpError(code=-32000, message="Client not supported")
+```
+
+*Verify:* `fastmcp_slim/fastmcp/exceptions.py` (`McpError = MCPError`).
+
+## Server core
+
+The SDK v2 rewrote the server request-handling model. FastMCP's handler layer is the most heavily rewritten part of the migration, but the public server API is unchanged.
+
+### Handler adapters — Absorbed
+
+Handlers are now registered by method string via `add_request_handler(method, params_type, handler)`, take a uniform `(ctx, params)` signature, and return the **bare** result model (no `ServerResult` wrapper). FastMCP's `_setup_handlers` builds one thin adapter per method (`tools/list`, `tools/call`, `resources/read`, `prompts/get`, `logging/setLevel`, …) that binds the request context, adapts params to the existing handler body, and returns the bare result. The v1 decorator overrides and `_wrap_list_handler` are deleted.
+
+*Verify:* `fastmcp_slim/fastmcp/server/low_level.py` (462 lines changed), `fastmcp_slim/fastmcp/server/mixins/mcp_operations.py`.
+
+### FastMCP-owned request context — Absorbed
+
+The SDK's `request_ctx` ContextVar is gone; the SDK passes context to handlers as an argument only. FastMCP owns its own `fastmcp_request_ctx` ContextVar, set at the top of every adapter. It stores a FastMCP-owned `FastMCPRequestContext` wrapper rather than the raw SDK context, because the raw `ServerRequestContext.meta` is a bare `TypedDict` carrying only `progress_token` — the full `_meta` block (which holds `_meta.fastmcp.version` and the distributed-trace parent) has to be lifted out of the raw params dict. `Context.request_context` and its consumers (`report_progress`, `session_id`, telemetry trace extraction, `get_http_request`) all read through the wrapper.
+
+*Verify:* `fastmcp_slim/fastmcp/server/dependencies.py`, `server/context.py`, `server/telemetry.py`.
+
+### `ServerMiddleware` bridge for `initialize` — Absorbed
+
+Server-side middleware is a new first-class SDK concept: `Server.middleware` is a list of `ServerMiddleware` composed around every request and notification, including `initialize`. FastMCP no longer subclasses `ServerSession` (the runner constructs it), so the old `MiddlewareServerSession._received_request` override is gone. A `FastMCPServerMiddleware` is appended to the SDK's middleware list (preserving the SDK's own OpenTelemetry middleware) and intercepts `initialize` to run FastMCP's middleware chain. The v2 seam is cleaner — `call_next(ctx)` returns the serialized result directly, so the old `capturing_respond` machinery is deleted.
+
+*Verify:* `fastmcp_slim/fastmcp/server/low_level.py` (`FastMCPServerMiddleware`).
+
+### Per-session state re-homed to the connection — Absorbed
+
+Because `ServerSession` is now per-request, per-session state can no longer live on the session object. The minimum logging level is re-homed to a FastMCP-side map keyed by session id (via `connection.session_id`), and `client_supports_extension` becomes a free function reading `session.client_params.capabilities`.
+
+*Verify:* `fastmcp_slim/fastmcp/server/low_level.py`, `server/context.py` (`_log_to_server_and_client`).
+
+### `extensions` capability read from the real field — Absorbed (post-review fix)
+
+SDK v2 declares `extensions` as a real field on `ClientCapabilities`, so a client sending `ClientCapabilities(extensions={...})` populates the field, not `model_extra`. `client_supports_extension` now reads `caps.extensions` first and falls back to `model_extra` only for legacy-serialized clients.
+
+*Verify:* commit `96ca0092`, `server/low_level.py` / `server/context.py`.
+
+### Task protocol and the `_sdk_patches` shim — Absorbed (with an upstream gap)
+
+The SEP-1686 task CRUD protocol (`tasks/get`, `tasks/result`, `tasks/list`, `tasks/cancel`) is entirely FastMCP-owned — the SDK ships no task store. Task detection moves to a params field: `params.task is not None` on `CallToolRequestParams`, with `ttl` from `params.task.ttl`. The four task handlers port to `add_request_handler`.
+
+The SDK has a real gap here (see [Known Gaps](/development/v4-notes/known-gaps) and sdk-feedback #1): it ships the task result types but omits them from the method registries, so a background-task `tools/call` returning a `CreateTaskResult` fails validation. FastMCP installs a registry-widening shim in `_sdk_patches.py` that adds `CreateTaskResult` to the `tools/call` result union and registers the `tasks/*` rows. It is a temporary patch with a self-documented removal trigger.
+
+Resources and prompts have **no `task` field** on their params in b1, so task-augmented resource reads and prompt gets are not wire-expressible — a documented capability regression, tracked by xfails, not a bug FastMCP fixes.
+
+*Verify:* `fastmcp_slim/fastmcp/_sdk_patches.py`, `server/tasks/*`.
+
+### Single SERVER span per request — Absorbed (post-migration fix)
+
+SDK v2 seeds an `OpenTelemetryMiddleware` into every lowlevel `Server`, so each inbound request already emits a SERVER span. FastMCP emits its own richer SERVER span per request (with `fastmcp.*` and auth/session attributes), so a server with an OTel exporter installed would export **two** SERVER spans per request under different attribute conventions. `LowLevelServer.__init__` now drops the SDK's seeded `OpenTelemetryMiddleware` (matched by type, not position, leaving any other seeded middleware intact) and keeps FastMCP's spans. Inbound W3C trace-context extraction is unaffected — FastMCP's telemetry reads `traceparent` from `_meta` itself, so distributed traces still link client to server. Client-side is not double-counted: the SDK's `ClientSession` emits a low-level `MCP send <method>` CLIENT span that nests *under* FastMCP's high-level client span, a legitimate parent/child hierarchy rather than a duplicate.
+
+*Verify:* `fastmcp_slim/fastmcp/server/low_level.py` (the `OpenTelemetryMiddleware` filter); `tests/server/telemetry/test_server_tracing.py::TestSingleServerSpan`.
+
+### Spec-correct error codes via a central translator — Breaking (wire error code)
+
+Resource-not-found responses from the core `resources/read` handler previously used `-32002`. SEP-2164 (and the SDK's own mcpserver, which maps `ResourceNotFoundError` → `INVALID_PARAMS`) makes this `-32602`. The per-adapter `MCPError(code=..., ...)` literals in `server/mixins/mcp_operations.py` are replaced by a single `fastmcp.exceptions.to_mcp_error()` translator that maps FastMCP's public exceptions to the `mcp_types` code constants (`NotFoundError`/`DisabledError`/`ValidationError` → `INVALID_PARAMS`, else `INTERNAL_ERROR`). Clients that string-matched on the old `-32002` for resource-not-found must switch to `-32602`; the human-readable message ("Resource not found: ...") is unchanged. The opt-in `ErrorHandlingMiddleware`, which has its own documented per-method-prefix code mapping, is intentionally left as-is.
+
+*Verify:* `fastmcp_slim/fastmcp/exceptions.py` (`to_mcp_error`); `fastmcp_slim/fastmcp/server/mixins/mcp_operations.py`; `tests/test_exceptions.py`.
+
+## Client
+
+The `fastmcp.Client` public API is preserved exactly. The client stays a wrapper around `mcp.ClientSession` in legacy/handshake mode; the first-class `mcp.client.Client` is deliberately not adopted in this PR.
+
+### Transports yield 2-tuples — Absorbed
+
+All SDK transports (`streamable_http_client`, `sse_client`, `stdio_client`) now yield a 2-tuple `(read, write)` instead of exposing a third `get_session_id` element. HTTP configuration flows through a caller-supplied `http_client=`. Only the tuple unpack changed on the FastMCP side.
+
+*Verify:* `fastmcp_slim/fastmcp/client/transports/http.py`, `transports/sse.py`, `transports/stdio.py`.
+
+### Float timeouts; `timedelta` still accepted — Absorbed
+
+The SDK session and call timeouts are now plain floats. FastMCP's public `Client(timeout=...)` still accepts a `timedelta`, a plain float, or an int, normalizing through the existing `normalize_timeout_to_seconds` at the `SessionKwargs` chokepoint:
+
+```python
+from datetime import timedelta
+
+from fastmcp import Client
+
+client = Client("my_mcp_server.py", timeout=timedelta(seconds=30))  # still works
+client = Client("my_mcp_server.py", timeout=30.0)  # also works
+```
+
+*Verify:* `fastmcp_slim/fastmcp/client/transports/base.py` (`SessionKwargs.read_timeout_seconds: float | None`), `client/client.py`.
+
+### `get_session_id` via header sniff — Bridged
+
+The SDK dropped `get_session_id` from the streamable-HTTP transport with no replacement (the SDK source has an author TODO acknowledging it breaks the Transport protocol). FastMCP reconstructs it by registering an httpx response event hook on the client it owns, capturing the `mcp-session-id` response header. The removal trigger is the upstream TODO.
+
+*Verify:* `fastmcp_slim/fastmcp/client/transports/http.py` (`_capture_session_id`, `get_session_id`).
+
+### Pagination via `params=` — Absorbed
+
+The SDK's `cursor=` kwarg on `list_*` is gone; pagination now flows through `params=PaginatedRequestParams(cursor=...)`. FastMCP's public `cursor=` on the `list_*_mcp` methods is preserved and translated internally.
+
+*Verify:* `fastmcp_slim/fastmcp/client/mixins/{tools,resources,prompts}.py`.
+
+### OAuth `callback_handler` returns `AuthorizationCodeResult` — Breaking (advanced)
+
+The one OAuth break: a custom `callback_handler` must return an `AuthorizationCodeResult` (fields `code`, `state`, `iss`) instead of the old `tuple[str, str | None]`. Everything else in the OAuth surface — `OAuthClientProvider` kwargs, `TokenStorage`, `async_auth_flow` — is unchanged.
+
+*Verify:* `fastmcp_slim/fastmcp/client/auth/oauth.py`.
+
+### Notification dispatch unwrapped — Absorbed
+
+The client's notification handling was reworked for the v2 message model. Custom server-to-client notifications (like SEP-1686 `notifications/tasks/status`) are no longer tee'd to a user `message_handler` — the SDK routes them only through `NotificationBinding` (see sdk-feedback #8). FastMCP registers a binding so task-status updates reach the Task registry.
+
+*Verify:* `fastmcp_slim/fastmcp/client/messages.py`, `client/tasks.py`.
+
+### `SDKServer` alias — Absorbed (post-review rename)
+
+The in-memory transport resolves the low-level server per server type. The alias for the SDK's own `MCPServer` was renamed from the misleading `FastMCP1Server` / `FastMCP1x` to `SDKServer`, since it names the SDK v2 server, not a FastMCP 1.x object.
+
+*Verify:* commit `5c3b82e4`; `client/client.py`, `client/transports/memory.py`, `server/providers/proxy.py`, `cli/run.py`.
+
+### Proxy request-context stash — Absorbed (post-review fix)
+
+Proxy forwarding handlers stash the request context so a backend that issues a server-initiated request (list_roots/sampling/elicitation) can relay it back to the proxy's own client. This stash was initially applied only on the tool path; commit `1ac166bd` extended it to proxied resources, templates, and prompts.
+
+*Verify:* commit `1ac166bd`, `server/providers/proxy.py`.
+
+## HTTP
+
+The maintainer asked whether FastMCP can now delete its custom HTTP app and let the SDK's `Server.streamable_http_app()` handle everything. The answer for this PR is **no** — every override earns its keep. Convergence is a v4 project gated on three upstream additions (see [Feature Program](/development/v4-notes/feature-program)).
+
+### Kept overrides — Absorbed
+
+Four overrides survive, each for a concrete reason:
+
+1. **Event-store session scoping.** The SDK hands every per-session transport the *same* `event_store` object, one stream-ID keyspace shared across sessions. FastMCP's `FastMCPStreamableHTTPSessionManager` returns a fresh `SessionScopedEventStore(shared, session_id=…)` per session, so resumability events don't leak across sessions.
+2. **Lifespan reconciliation.** The SDK builder enters the bare lowlevel `Server.lifespan` (which yields `{}`). FastMCP drives its own `_lifespan_manager` — ref-counted for mounts, Ctrl-C-shielded, docket-aware. The SDK path silently skips all of it, so FastMCP sets the server lifespan to delegate to `_lifespan_manager` and lets the manager enter it once.
+3. **Graceful transport termination.** FastMCP's lifespan `finally` drains the manager's server instances via `transport.terminate()` before task-group cancel, fixing the Uvicorn "returned without completing response" edge (#3025). The SDK just cancels.
+4. **User ASGI middleware hook.** The SDK builder hardcodes an empty middleware list and only appends auth. FastMCP's `http_app(middleware=...)` and `RequestContextMiddleware` have nowhere to go in the SDK path.
+
+*Verify:* `fastmcp_slim/fastmcp/server/http.py`, `server/event_store.py`, `server/mixins/lifespan.py`.
+
+### DNS-rebinding ownership — Absorbed (security)
+
+FastMCP owns DNS-rebinding protection through its `HostOriginGuardMiddleware`, which is more expressive than the SDK's and is the documented surface. To avoid two allowlists double-blocking with confusing errors from two layers, FastMCP **always** disables the SDK's layer by passing `TransportSecuritySettings(enable_dns_rebinding_protection=False)` to the manager — both when FastMCP's protection is on (so they don't double-block) and when it's off (so the SDK's default-on flip can't silently re-enable it).
+
+*Verify:* `fastmcp_slim/fastmcp/server/http.py` (`enable_dns_rebinding_protection=False`, `HostOriginGuardMiddleware`).
+
+## Protocol eras
+
+The SDK v2 serves multiple protocol eras from one server, and FastMCP formally embraces this.
+
+### Dual-era serving — Absorbed (supersedes "latest only")
+
+A single FastMCP server now handles clients across the protocol transition: the session-based handshake eras (through 2025-11-25) and the sessionless `2026-07-28` era (capability discovery via `server/discover`) simultaneously. This supersedes FastMCP's earlier "latest protocol only" stance.
+
+### Per-feature era matrix — Breaking (feature availability by era)
+
+The push-style Context features that require the server to call back into the client are unavailable on the sessionless `2026-07-28` era, because that era removes server-initiated requests (SEP-2577). The request/response features flow on every era.
+
+| Context feature | Session-based eras | `2026-07-28` (sessionless) |
+| --- | --- | --- |
+| `ctx.info` / logging notifications | Supported | Supported |
+| Tools, resources, prompts, completions | Supported | Supported |
+| `ctx.elicit` | Supported | Not yet — MRTR rewrite pending |
+| `ctx.sample` / `ctx.sample_step` | Supported (deprecated) | Removed — call an LLM server-side |
+| `ctx.list_roots` | Supported | Not yet — MRTR rewrite pending |
+| Tasks (via the FastMCP client) | Supported | Not yet |
+
+Tools that rely on `ctx.elicit` or `ctx.list_roots` continue to work against clients on the session-based eras. Sampling is the exception: it is deprecated on every era and will not return on modern connections (see the Deprecated entry below).
+
+Ordinary `ctx.info` usage emits an SDK-level `MCPDeprecationWarning` ("The logging capability is deprecated as of 2026-07-28 (SEP-2577)"). That warning comes from the SDK, not FastMCP, and is benign — logging keeps working on session-based connections per the matrix. `ctx.sample`/`ctx.sample_step` additionally emit a FastMCP-owned `FastMCPDeprecationWarning` (see below). The upgrade guide calls both out explicitly.
+
+Wire interop across the transition is verified: a 3.4.3 client against a v4 server and a v4 client against a 3.4.3 server are bidirectionally clean across 9 operations over HTTP (WS2).
+
+*Verify:* `docs/getting-started/upgrading/from-fastmcp-3.mdx` (the published matrix and SDK-warning note), `tests/server/test_protocol_eras.py`.
+
+### Sampling deprecated, era-gated — Deprecated
+
+`ctx.sample()` and `ctx.sample_step()` are deprecated and slated for removal in a future FastMCP release. Server-initiated sampling relies on the `createMessage` back-channel that SEP-2577 removed from the wire as of `2026-07-28`, and unlike elicitation it has no multi-round-trip replacement (the agentic loop would exhaust the round-trip budget). Both methods now emit a `FastMCPDeprecationWarning` once per process (gated on `settings.deprecation_warnings`), and on a `2026-07-28` connection they raise a clear `ToolError` before touching the wire. The client-side sampling handler infrastructure (anthropic/openai/google_genai) is retained for future MRTR work and is not deprecated. The migration is to call an LLM directly from your server rather than borrowing the client's model.
+
+The dead TODO at `server/context.py` (a background-task sampling relay that was never built) is removed: that relay is not being built, so the note is gone rather than left as a promise.
+
+*Verify:* `fastmcp_slim/fastmcp/server/context.py` (`_warn_sampling_deprecated`, `_is_modern_protocol`, the `sample`/`sample_step` gates), `docs/servers/sampling.mdx` (deprecation banner), `tests/server/test_protocol_eras.py` (warning + era-gate tests).
+
+### Push-feature degradation quality — Resolved (was sdk-feedback #10)
+
+On a `2026-07-28` connection the degradation error used to differ by feature: `ctx.list_roots` raised a clear `NoBackChannelError`, while `ctx.elicit` / `ctx.sample` surfaced a bare "Method not found" because those methods attach a `related_request_id` and reach client dispatch before failing. FastMCP now era-gates `ctx.elicit` and `ctx.sample`/`ctx.sample_step` to raise a clear, era-aware `ToolError` before the wire ("server-initiated sampling is not available on MCP 2026-07-28 connections…" and "elicitation via server-initiated requests is unavailable on 2026-07-28 connections."). The strict xfail that captured #10 is flipped to a passing test.
+
+*Verify:* `tests/server/test_protocol_eras.py` (`test_elicit_sample_degradation_message_is_clear_on_modern`, now a real test), `server/context.py` (era gates).
+
+### Server-level cache hints (SEP-2549) — New (opt-in feature)
+
+A FastMCP server can emit SEP-2549 freshness hints so a caching client (`fastmcp.Client(cache=...)`) may reuse a response without a wire round-trip. Two constructor params carry it: `FastMCP(cache_ttl=300, cache_scope="public")`, where `cache_ttl` is in seconds and `cache_scope` is `"public"` or `"private"` (default `"private"` when a TTL is set). The hint is uniform by construction — one server-level value applies to every SDK-cacheable method (`tools/list`, `prompts/list`, `resources/list`, `resources/templates/list`, `resources/read`, and `server/discover`) with no per-component surface and no aggregation. FastMCP does not hand-set the wire fields: it passes the hint through to the SDK low-level `Server(cache_hints=...)`, whose runner fills `ttlMs`/`cacheScope` on every cacheable result via `apply_cache_hint`, leaving any field a handler set explicitly untouched. `cache_ttl` must be positive, and a `cache_scope` without a `cache_ttl` is rejected at construction (a scope alone does not enable caching, since the client gates on the TTL's presence). Absent both params, no hint is emitted. Honoring is modern-only (the SDK client reads hints only at `2026-07-28`) and opt-in on the client, so a hinted server is inert unless the client passes `cache=`.
+
+*Verify:* `fastmcp_slim/fastmcp/server/caching.py` (`build_cache_hints`), `fastmcp_slim/fastmcp/server/server.py` (constructor params passed to `LowLevelServer(cache_hints=...)`), `tests/server/test_cache_hints.py` (unit validation + end-to-end interop with `fastmcp.Client(cache=True)`).
+
+### The xfail register — Known gap
+
+Roughly forty `xfail` markers across the test tree (concentrated in `tests/server/tasks/`, `tests/client/tasks/`, and `test_protocol_eras.py`) are the built-in beta tracker: each names the SDK gap it waits on. They are enumerated and mapped to sdk-feedback findings on the [Known Gaps](/development/v4-notes/known-gaps) page.
+
+## Security
+
+FastMCP retains hardening that is not yet upstream and does not remove it during the migration.
+
+### Retained OAuth / DCR hardening — Absorbed
+
+FastMCP keeps its own DCR redirect-URI hardening (PRs #4419, #4408) regardless of the SDK's validation, which still accepts unsafe `javascript:`/`data:` redirect schemes at the model level (sdk-feedback #4). The streamable-HTTP DNS-rebinding protection above is a second retained security surface.
+
+*Verify:* recent commits `67527c1f` (block unsafe OAuth redirect schemes), `57a27992` (DNS rebinding), `cccb529f` (DCR redirect URI validation) on `main`.
+
+## Removed in 4.0
+
+Deprecations that warned in 3.x are removed in 4.0. Each entry below is a hard removal — the old surface raises `TypeError` / `AttributeError` rather than warning, unless noted otherwise.
+
+### Module and class shims
+
+- **`fastmcp.server.proxy`** (deprecated 3.0) — Breaking. Import proxy classes (`FastMCPProxy`, `ProxyClient`, etc.) from `fastmcp.server.providers.proxy` instead.
+- **`fastmcp.server.openapi`** and its submodules (`server`, `components`, `routing`), including the **`FastMCPOpenAPI`** class (deprecated 3.0) — Breaking. Use `FastMCP` with an `OpenAPIProvider` from `fastmcp.server.providers.openapi` instead.
+- **`fastmcp.experimental.server.openapi`** and **`fastmcp.experimental.utilities.openapi`** shims (deprecated 2.14) — Breaking. Import from `fastmcp.server.providers.openapi` and `fastmcp.utilities.openapi` respectively.
+- **`fastmcp.server.apps`** and **`fastmcp.server.app`** shims (deprecated 3.2) — Breaking. Import from `fastmcp.apps` (e.g. `AppConfig`) or `fastmcp` (`FastMCPApp`) instead.
+- **`PromptToolMiddleware`** and **`ResourceToolMiddleware`** (deprecated 3.1) — Breaking. Use the `PromptsAsTools` / `ResourcesAsTools` transforms from `fastmcp.server.transforms` instead. The non-deprecated `ToolInjectionMiddleware` base class is retained.
+- **`StreamableHttpTransport(sse_read_timeout=...)`** (deprecated no-op) — Breaking. The parameter had no effect under the SDK v2 client; configure timeouts via `read_timeout_seconds` in `session_kwargs` or on the httpx client via `httpx_client_factory`. `SSETransport` still accepts `sse_read_timeout`.
+
+### `FastMCP` server methods and `mount()` kwargs
+
+The following `FastMCP` methods and parameters, deprecated since 3.0, are removed:
+
+- `FastMCP.as_proxy(...)` → `create_proxy(...)` (`from fastmcp.server import create_proxy`)
+- `FastMCP.import_server(sub)` → `mount(sub)`
+- `mount(prefix=...)` → `mount(namespace=...)`
+- `mount(as_proxy=...)` — removed; mounts always invoke the child's lifespan and middleware, so the flag was already meaningless. To proxy a server, wrap it with `create_proxy()` before mounting.
+- `FastMCP.add_tool_transformation(name, config)` → `add_transform(ToolTransform({name: config}))`
+- `FastMCP.remove_tool_transformation(name)` — removed; it was a no-op that only warned (transforms are immutable once added). Use `server.disable(keys=[...])` to hide tools.
+- `FastMCP.remove_tool(name)` → `mcp.local_provider.remove_tool(name)`
+
+The `_REMOVED_KWARGS` constructor shim (which raises helpful `TypeError`s for kwargs removed in 3.0) is retained through 4.0.
+
+### Tool and component parameters
+
+- **Tool-level `serializer` parameter** — removed from `@tool` / `mcp.tool()`, `Tool.from_function`, `Tool.from_tool`, `TransformedTool.from_tool`, the OpenAPI `OpenAPITool`, and the `mcp_mixin` tool decorator. Return a `ToolResult` from your tool for full control over serialization instead (see [Custom Serialization](/servers/tools#custom-serialization)). The server-level `tool_serializer` constructor kwarg was already removed in 3.0.
+- **Tool `exclude_args` parameter** — removed from the tool decorator and its plumbing (`ParsedFunction.from_function`, `Tool.from_function`, `mcp.tool()`). Use dependency injection with `Depends()` to hide parameters from the tool schema instead.
+- **`decorator_mode` setting** (`FASTMCP_DECORATOR_MODE`) and its `"object"` mode — removed. Decorators always return the original function with metadata attached; the object-returning machinery is gone. Access component objects through the server (e.g. `await mcp.get_tool("name")`) rather than the decorated function.
+- **Component-import compatibility shims** — the `__getattr__` shims that re-exported `FunctionTool` / `ParsedFunction` / `tool` from `fastmcp.tools.tool`, `FunctionResource` / `resource` from `fastmcp.resources.resource`, and `FunctionPrompt` / `prompt` from `fastmcp.prompts.prompt` are removed. Import these from their canonical modules (`fastmcp.tools.function_tool`, `fastmcp.resources.function_resource`, `fastmcp.prompts.function_prompt`) instead.
+
+*Verify:* deletions of `fastmcp_slim/fastmcp/server/proxy.py`, `fastmcp_slim/fastmcp/server/openapi/`, `fastmcp_slim/fastmcp/experimental/server/openapi/`, `fastmcp_slim/fastmcp/experimental/utilities/openapi/`, `fastmcp_slim/fastmcp/server/apps.py`, `fastmcp_slim/fastmcp/server/app.py`; the removed classes in `fastmcp_slim/fastmcp/server/middleware/tool_injection.py`; the removed parameter in `fastmcp_slim/fastmcp/client/transports/http.py`; `fastmcp_slim/fastmcp/server/server.py`; `fastmcp_slim/fastmcp/tools/base.py`, `tools/function_tool.py`, `tools/tool_transform.py`, `tools/function_parsing.py`; `fastmcp_slim/fastmcp/settings.py`, `resources/function_resource.py`, `prompts/function_prompt.py`, and the local-provider decorators; `resources/base.py`, `prompts/base.py`.
diff --git a/docs/development/v4-notes/feature-program.mdx b/docs/development/v4-notes/feature-program.mdx
new file mode 100644
index 0000000..5750156
--- /dev/null
+++ b/docs/development/v4-notes/feature-program.mdx
@@ -0,0 +1,129 @@
+---
+title: Feature Program
+---
+
+The migration is the foundation. The forward v4 program is a sequence of post-merge PRs that build on it. Each feature below carries an explicit status:
+
+- **Designed** — the approach is settled and an API sketch exists; implementation has not started.
+- **Planned** — the shape is agreed but design details remain open.
+- **Not started** — identified as v4 scope, not yet designed.
+
+Code blocks marked as sketches show the *intended* API and do not resolve against the current tree.
+
+## Sampling: deprecate now, remove in 4.0
+
+**Status: Designed.**
+
+Sampling is the push-shaped API where a server borrows the client's model mid-call (`ctx.sample`, `ctx.sample_step`). The `2026-07-28` era removes server-initiated requests, so this API cannot work on modern connections. Background-task sampling is already dead under v2 — a worker's back-channel is gone once the submitting request returns, and no sampling relay was ever built (sdk-feedback #9).
+
+The plan is Option A: **deprecate the push-sampling API now and remove it in the 4.0 release.**
+
+- Deprecate `ctx.sample` / `ctx.sample_step` and the server sampling module now.
+- Era-gate them to raise a clear error on `2026-07-28` (this also fixes the opaque "Method not found" of sdk-feedback #10).
+- Remove `ctx.sample`, `ctx.sample_step`, `server/sampling/`, `SamplingTool`, and structured-result sampling in 4.0.
+
+The migration story is honest: there is **no drop-in** on modern connections. The guidance is architectural — call an LLM from your server directly, with your own API key, rather than borrowing the client's model. That shift is the real answer, and it is why the removal justifies a major version.
+
+The client-side provider handlers (Anthropic, OpenAI, Google GenAI) are **retained** regardless: MRTR needs them to answer sampling input-requests from the client side. What is removed is the server-side push emitter, which the SDK never built for the modern era.
+
+In this PR, sampling still functions on the legacy eras. Users already see an SDK-level `MCPDeprecationWarning` on ordinary `ctx.sample` usage (the SDK deprecated the capability wire-side per SEP-2577, verified empirically by WS2), but FastMCP's own deprecation — warnings with migration guidance, plus the era-gating — lands as the first follow-up PR.
+
+## MRTR elicitation
+
+**Status: Designed. Flagship feature.**
+
+Elicitation survives the modern era, but only declaratively. The 2026 wire envelope still carries elicitation as a multi-round input-request (MRTR — multi-round tool result). Imperative `ctx.elicit` relies on the session back-channel, which is gone on `2026-07-28` foreground calls; on the modern era, elicitation is reachable only through a declarative resolver.
+
+The design does both, so the imperative DX survives where it can and a declarative surface covers the modern era:
+
+**1. Keep `ctx.elicit` as the primary imperative DX,** re-plumbed to be era-aware: legacy connections use the session elicit-form path; background tasks on any era use the existing Redis relay (the task's `input_required` status *is* the MRTR suspension boundary); foreground calls on `2026-07-28` raise a clear era-aware error pointing at the declarative form.
+
+**2. Add a declarative surface** in a new `fastmcp.elicitation` module — `Resolve`, `Elicit`, and `ElicitationResult` — thin wrappers over the SDK's resolver, wired into FastMCP's own tool layer (FastMCP tools do not inherit the SDK's auto-resolver wiring).
+
+The intended DX (sketch — the module does not exist yet):
+
+```python test="skip"
+from typing import Annotated
+
+from pydantic import BaseModel
+
+from fastmcp import FastMCP, Context
+from fastmcp.elicitation import Resolve, Elicit, ElicitationResult
+
+mcp = FastMCP("shipping")
+
+
+class Address(BaseModel):
+    street: str
+    city: str
+    zip: str
+
+
+async def ask_address(ctx: Context) -> Elicit[Address]:
+    return Elicit("Where should we ship this order?", Address)
+
+
+@mcp.tool
+async def create_shipment(
+    order_id: str,
+    address: Annotated[Address, Resolve(ask_address)],  # unwrapped; decline -> ToolError
+) -> str:
+    return f"Shipping {order_id} to {address.city}"
+
+
+@mcp.tool
+async def maybe_ship(
+    order_id: str,
+    address: Annotated[ElicitationResult[Address], Resolve(ask_address)],  # full outcome
+) -> str:
+    if address.action != "accept":
+        return "cancelled"
+    return f"Shipping {order_id} to {address.data.city}"
+
+
+@mcp.tool(task=True)
+async def slow_ship(ctx: Context) -> str:
+    # imperative ctx.elicit survives 2026 via the background-task relay
+    result = await ctx.elicit("Confirm address", Address)
+    if result.action == "accept":
+        return f"Shipping to {result.data.city}"
+    return "cancelled"
+```
+
+The registration path detects `Annotated[_, Resolve(...)]` parameters, builds resolver plans, and returns the SDK's `InputRequiredResult` instead of the tool body on the first round. The FastMCP client already dispatches input-requests through its elicitation callback; the follow-up work confirms the FastMCP client wrapper drives the input-required driver the way the SDK's own client does.
+
+The divergence between elicitation and sampling on 2026 comes down to one fact: the SDK built the server-side emitter for elicitation (`Elicit`/`Resolve`) and not for sampling. The wire carries all three input-request types and the client dispatches all three; only elicitation can produce one server-side. That is why elicitation survives 4.0 via MRTR and push-sampling does not.
+
+## Middleware on the SDK `ServerMiddleware` seam
+
+**Status: Planned.**
+
+The migration already routes `initialize` interception through the SDK's new `ServerMiddleware` seam via `FastMCPServerMiddleware`. The forward work is to lean into that seam more fully — moving more of FastMCP's request-lifecycle middleware onto the native SDK composition point rather than FastMCP-side wrappers, now that the SDK composes middleware around every request and notification.
+
+## First-class 2026 client
+
+**Status: Planned.**
+
+The migration keeps `fastmcp.Client` as a wrapper around `mcp.ClientSession` in legacy/handshake mode. The v4 client work adopts the SDK's first-class `mcp.client.Client`: a `mode='auto'` that negotiates the era, `discover()` for sessionless capability discovery, and the MRTR input-required driver so the client can answer multi-round elicitation and sampling input-requests. This is the client-side half of full `2026-07-28` support.
+
+This workstream also owns the server-side statelessness design holes — `ctx.session_id` / `set_state` round-tripping, task push and background elicitation, and stateful-proxy affinity — since all three turn on the same "what is a session without a session?" question. See [Statelessness on 2026-07-28](/development/v4-notes/known-gaps#statelessness-on-2026-07-28) for the full accounting.
+
+## Subscriptions, cache hints, extensions, OTel
+
+**Status: Not started.**
+
+A cluster of protocol features tracked for v4 once the core client and elicitation work lands: a `subscriptions/listen` surface backed by a subscription bus, resource cache hints, reconciliation of the `extensions` / MCP Apps capability advertisement across eras (the `extensions` capability is stripped at pre-2026 negotiated versions today — sdk-feedback #2), and the OpenTelemetry integration re-checked against the SDK's own OTel middleware.
+
+## SDK delegation, round two
+
+**Status: Planned (gated on upstream).**
+
+The real HTTP simplification is a v4 project, not this PR. FastMCP can collapse its `create_streamable_http_app` onto the SDK's `Server.streamable_http_app()` once upstream adds three things:
+
+1. per-session event-store scoping,
+2. a user-middleware injection hook,
+3. a lifespan hook.
+
+The payoff is not only less code — FastMCP would also inherit the SDK's session-owner credential enforcement, a security gain it lacks today. These are the three upstream feature requests to file (alongside the advisory dossier described in [Known Gaps](/development/v4-notes/known-gaps)). Until they land, the four HTTP overrides in the [Change Register](/development/v4-notes/change-register#http) stay.
+
+One latent capability worth surfacing on FastMCP's side: `session_idle_timeout` is accepted by the manager but never set by `create_streamable_http_app` — a one-line plumb if FastMCP wants to expose it.
diff --git a/docs/development/v4-notes/index.mdx b/docs/development/v4-notes/index.mdx
new file mode 100644
index 0000000..1cbebfd
--- /dev/null
+++ b/docs/development/v4-notes/index.mdx
@@ -0,0 +1,37 @@
+---
+title: v4.0 Development Notes
+---
+
+This directory is the working map of FastMCP v4.0: the complete register of user-facing changes from the MCP Python SDK v2 migration ([PR #4437](https://github.com/PrefectHQ/fastmcp/pull/4437)), plus the forward v4 feature program. It plays three roles at once.
+
+1. **A change register.** Every user-visible change from the migration, organized by subsystem, with a note on how FastMCP handles it (absorbed, bridged, breaking, or deprecated) and where to find it in the diff. This is the [Change Register](/development/v4-notes/change-register).
+2. **A feature program.** The forward v4 work — sampling removal, MRTR elicitation, the first-class 2026 client, and the SDK-delegation round-two convergence — each with an explicit status. This is the [Feature Program](/development/v4-notes/feature-program).
+3. **A review lens.** Because the migration PR is too large to review line by line, the change register is organized so a reviewer can take one subsystem, read its claimed changes, and verify each against the diff. The [Known Gaps](/development/v4-notes/known-gaps) page collects the deliberate xfails and the upstream dependencies that gate the follow-up work.
+
+## Why v4 exists
+
+FastMCP v4.0 is an engine swap. Three forces drive the major version:
+
+**The MCP Python SDK v2 rebuild.** The SDK v2 makes two sweeping changes to the protocol layer: it splits the protocol types out of `mcp.types` into a standalone `mcp_types` package, and it renames every protocol field from camelCase to snake_case (`inputSchema` → `input_schema`, `mimeType` → `mime_type`, `isError` → `is_error`). It also rewrites the server request-handling model — handlers are now registered by method string and return bare result models, there is no `request_ctx` ContextVar, and server-side middleware is a first-class SDK concept. FastMCP absorbs almost all of this so that a typical server needs zero code changes.
+
+**Protocol version 2026-07-28.** The SDK v2 serves multiple protocol eras from one server. Alongside the session-based handshake eras, it introduces the sessionless `2026-07-28` era, which discovers capabilities through `server/discover` and removes server-initiated requests (SEP-2577). This formally supersedes FastMCP's earlier "latest protocol only" stance: a single server now works with clients across the protocol transition.
+
+**Sampling removal.** The `2026-07-28` era removes the server's ability to push a request back to the client mid-call. That takes the push-shaped sampling API (`ctx.sample`, `ctx.sample_step`) off the table on modern connections. Rather than leave it half-working, v4 deprecates it now and removes it in the 4.0 release — a real architectural shift for servers that borrowed the client's model, and one that justifies the major bump.
+
+## Release strategy
+
+The migration merges to `main` and development continues there with subsequent PRs. Releases follow the SDK's own beta timeline:
+
+- **`main` carries the beta pins.** While the SDK is on `mcp==2.0.0b1` / `mcp-types==2.0.0b1`, `main` cuts **pre-releases** (`4.0.0b1`, `4.0.0b2`, …). No stable PyPI release goes out until `mcp 2.0.0` reaches GA — at which point the pins swap to the stable SDK and `4.0.0` ships. The pin-swap is a tracked checklist item on the [Known Gaps](/development/v4-notes/known-gaps) page.
+- **`release/3.x` is the maintenance line.** A `release/3.x` branch is cut from pre-merge `main`. It stays on the SDK v1 line, receives upstream security patches, and serves users who cannot move to the SDK v2 beta yet.
+
+## How to read the register
+
+Each subsystem section in the [Change Register](/development/v4-notes/change-register) tags its changes with one of four dispositions:
+
+- **Absorbed** — the SDK changed underneath, but FastMCP's public surface is identical. Nothing for users to do.
+- **Bridged** — a compatibility shim keeps old code working, usually with a `FastMCPDeprecationWarning`. Users should migrate but are not forced to.
+- **Breaking** — user code must change. These are the headline migration items.
+- **Deprecated** — still works, warns now, slated for removal in a later release.
+
+The user-facing summary of the migration lives in the published [Upgrading from FastMCP 3](/getting-started/upgrading/from-fastmcp-3) guide. These development notes are the exhaustive version behind it.
diff --git a/docs/development/v4-notes/known-gaps.mdx b/docs/development/v4-notes/known-gaps.mdx
new file mode 100644
index 0000000..3f2df1a
--- /dev/null
+++ b/docs/development/v4-notes/known-gaps.mdx
@@ -0,0 +1,91 @@
+---
+title: Known Gaps and Upstream Dependencies
+---
+
+The migration ships with a set of deliberate gaps: temporary shims, xfailed tests, and pins that depend on the MCP Python SDK v2 reaching GA. Each is tracked here with its removal trigger. This page is the checklist for the beta-to-stable transition and the advisory relationship with the SDK team.
+
+## The xfail register
+
+Roughly forty `xfail` markers across the test tree are the built-in beta tracker. Each names the SDK gap it waits on, so re-running the suite against a new SDK beta surfaces exactly which gaps have closed (a strict xfail that starts passing fails the suite, prompting removal of the marker). They cluster in three areas.
+
+**Task suite (`tests/server/tasks/`, `tests/client/tasks/`).** The large majority. These trace to two SDK gaps:
+
+- **sdk-feedback #1** — SEP-1686 ships the task result types but omits them from the method registries, so a task-augmented `tools/call` cannot complete validation. FastMCP's `_sdk_patches.py` registry-widening shim covers the common tool path; the xfails cover paths the shim intentionally does not paper over.
+- **sdk-feedback #3** — `ReadResourceRequestParams` and `GetPromptRequestParams` have no `task` field, so task-augmented resource reads and prompt gets are not wire-expressible. The xfails in `test_task_resources.py`, `test_task_prompts.py`, `test_client_resource_tasks.py`, and `test_client_prompt_tasks.py` carry the reason "SDK v2 has no `task` field on GetPromptRequestParams / ReadResourceRequestParams."
+
+**Protocol eras (`tests/server/test_protocol_eras.py`).** Two strict xfails:
+
+- The strict xfail at `test_protocol_eras.py:319` maps directly to **sdk-feedback #10**: on `2026-07-28`, `ctx.elicit`/`ctx.sample` attach a `related_request_id` and surface a bare "Method not found" rather than a clear era-aware error. It stays strict until the SDK unifies the degradation path or FastMCP era-gates the calls.
+- The strict xfail at `test_protocol_eras.py:400` covers the SDK's first-class high-level client (`mcp.client.Client`) and the sessionless driver that the FastMCP client does not yet adopt (see the [first-class 2026 client](/development/v4-notes/feature-program#first-class-2026-client) feature).
+
+**MCP Apps (`tests/test_apps.py`).** Two xfails tied to **sdk-feedback #2** — the `extensions` capability is stripped by the pre-2026 version sieve, so the UI extension can't be advertised to legacy-era clients.
+
+## Shims and their removal triggers
+
+Every shim in the migration is temporary and carries a documented removal trigger.
+
+| Shim | Location | Removal trigger |
+| --- | --- | --- |
+| `_sdk_patches.py` — task registry widening | `fastmcp_slim/fastmcp/_sdk_patches.py` | SDK adds `tasks/*` rows and `CreateTaskResult` to the `tools/call` result union (sdk-feedback #1). |
+| `_compat.py` — camelCase field bridge | `fastmcp_slim/fastmcp/_compat.py` | User-migration aid; removed in a future release after users migrate reads to snake_case. Users can preview removal with `mcp_camelcase_compat = False`. |
+| `FastMCPRequestContext` ContextVar | `fastmcp_slim/fastmcp/server/dependencies.py` | The SDK deliberately passes context as an argument with no ContextVar; FastMCP's public `get_context()` needs ambient access, and the shim also lifts `_meta`, which the SDK's `TypedDict` drops. No planned removal — this is a permanent boundary, not a beta gap. |
+| `FastMCPServerMiddleware` | `fastmcp_slim/fastmcp/server/low_level.py` | Already the native SDK `ServerMiddleware` path; no cleaner hook exists. Permanent. |
+| Client `get_session_id` header sniff | `fastmcp_slim/fastmcp/client/transports/http.py` | SDK exposes session id (or an `on_session_created` callback) from `streamable_http_client`, at parity with `sse_client` (sdk-feedback #5). |
+| `_sdk_context_shim.py` — generic handler aliases | `fastmcp_slim/fastmcp/client/_sdk_context_shim.py` | The SDK's `ClientRequestContext` is not subscriptable, so FastMCP keeps the public generic `SamplingHandler`/`RootsHandler`/`ElicitationHandler` aliases. Permanent unless the SDK makes the context subscriptable (sdk-feedback #7). |
+
+The `TaskNotificationHandler` binding (sdk-feedback #8) is the client-side equivalent: it registers a `NotificationBinding` for `notifications/tasks/status` because the SDK no longer tees custom server notifications to the message handler.
+
+## Statelessness on 2026-07-28
+
+The `2026-07-28` era is stateless by protocol construction, and the recurring maintainer question is whether that statelessness has to be woven through FastMCP everywhere. It does not — but the honest accounting has three parts: features that are legacy-only because the protocol removed the mechanism, features that already work because they never relied on a session, and a short list of design holes where the current code *doesn't error* but also *doesn't work*. Everything below concerns `2026-07-28` connections only. Every client in the field today negotiates a handshake era, where all of this behaves exactly as it always has.
+
+**The SDK ground truth.** On the modern paths the SDK's `Connection` is strictly per-request: a fresh `Connection` is built from each POST's envelope, its `exit_stack` unwinds when the request returns, `connection.session_id` is always `None`, and `connection.state` is a fresh dict per request. The manager's `stateless` flag never enters the picture — modern routing short-circuits ahead of it. There is no standing server→client stream: notifications emitted *during* a request ride that POST's own SSE sink, and anything emitted after the POST returns is dropped (`_NO_CHANNEL`); server→client *requests* raise `NoBackChannelError`. The only replacement is `subscriptions/listen`, which carries four list-changed / resource-updated event kinds and nothing else — no logging, progress, or task-status events, no resumability, and it is not yet wired into FastMCP. There is no `EventStore` or `Last-Event-ID` on modern paths at all; both belong to the legacy transport.
+
+### Legacy-only by construction — document, don't build
+
+These are not bugs. The protocol removed the mechanism they depend on, so they are simply out of scope on `2026-07-28`:
+
+- **Per-session log levels.** `logging/setLevel` is absent from the 2026 method registry, so the `_client_log_levels` handler is unreachable. There is no per-session log-level state because there is no session.
+- **`EventStore` / resumability.** `EventStore`, `SessionScopedEventStore`, and Last-Event-ID resumption are never constructed on the modern paths. Resumability presupposes a durable stream, which the era does not have.
+- **Ping keepalive.** Server-initiated ping is a server→client request and is therefore structurally a no-op on modern connections; the SDK owns SSE-level pings on this transport.
+
+### Already stateless by construction — works on 2026
+
+These work on `2026-07-28` today because they never leaned on a protocol session:
+
+- **`tasks/get` polling.** Task result retrieval is keyed by `task_id` and backed by Docket/Redis, so a client polls across independent requests without any session affinity.
+- **OAuth bearer validation.** Auth is per-request bearer validation — every POST carries and re-validates its own credential.
+- **In-request progress and logging notifications.** Notifications emitted while a request is still streaming ride that POST's SSE sink and are delivered normally.
+
+### Design holes deferred to the multi-protocol workstream
+
+The remaining items are real holes, deferred to the [first-class 2026 client](/development/v4-notes/feature-program#first-class-2026-client) workstream because they all reduce to one unanswered question — *what is a session when the protocol has none?* The danger in each is that the code currently returns without erroring, which reads as "works" but is actually silent degradation. Again: these affect `2026-07-28` connections only; on the handshake eras every one of them behaves correctly.
+
+- **`ctx.session_id` and `ctx.set_state` / `ctx.get_state` (broken even single-replica).** On a modern request `ctx.session_id` mints a fresh `uuid4`, cached on the per-request `connection.state` that is discarded when the request returns. So `ctx.set_state` and `ctx.get_state` silently never round-trip across requests — no error, just lost data. The open design decision is whether `session_id` should become `None` with `set_state` documented as session-era-only, or be re-based on an app-level key (the auth subject, or a client-supplied header).
+- **Task push and background elicitation (broken even single-replica).** The initial task-status notification is delivered only while the submitting POST is still streaming; the standalone subscription task pushes into a dead sink and its cleanup fires at request end, and the Redis relay is keyed by the throwaway per-request session id. Elicitation from a background task is impossible on 2026 by protocol construction — it needs an explicit era-gate that raises a clear error rather than hanging. Task-status push on 2026 would require adopting `subscriptions/listen` (which does not carry task events) or declaring the era poll-only.
+- **Stateful proxy affinity (degraded).** The stateful proxy's `_caches` are keyed by the per-request `Connection`, so on modern connections the proxy collapses to stateless proxying: results stay correct, but the per-session affinity guarantee is lost. This is decided alongside the `session_id` question — same root — or gated to the legacy/stdio transports.
+
+Multi-replica concerns (per-process rate-limiter buckets, shared Redis backends for state and tasks, a Redis `SubscriptionBus`) are deployment configuration rather than protocol gaps and are out of scope for this section.
+
+## Upstream advisory dossier
+
+FastMCP acts as an advisor to the SDK team. The migration produced a dossier of ten findings (`sdk-feedback.md`) — verified bugs and hard edges to report upstream, plus questions to bundle into a feedback thread. The highest-priority items:
+
+- **#1 (bug)** — SEP-1686 task result types ship but the method registries omit them.
+- **#2 (bug/question)** — `capabilities.extensions` stripped at pre-2026 negotiated versions.
+- **#4 (security)** — DCR redirect-URI validation accepts `javascript:`/`data:` schemes.
+- **#5 (hard edge)** — `streamable_http_client` drops session-id access with no replacement.
+- **#8 (hard edge)** — custom server notifications are dropped, not tee'd to `message_handler`.
+- **#10 (hard edge)** — 2026 push-feature degradation error quality is inconsistent.
+
+Filing is gated on maintainer approval of each issue text.
+
+Separately, the [SDK delegation round two](/development/v4-notes/feature-program#sdk-delegation-round-two) work depends on **three upstream feature requests** — per-session event-store scoping, a user-middleware injection hook, and a lifespan hook — that would let FastMCP collapse its HTTP builders onto the SDK's and inherit the SDK's session-owner credential enforcement.
+
+## GA transition checklist
+
+The beta-to-stable transition is a small set of tracked steps:
+
+- **Swap the pins.** When `mcp 2.0.0` reaches GA, change `mcp-types==2.0.0b1` (core) and the `mcp` pin (the `[mcp]` extra) in `fastmcp_slim/pyproject.toml` from the beta to the stable release, and cut `4.0.0` instead of another pre-release.
+- **Re-run the xfail suite against the GA SDK.** Any strict xfail that starts passing means a gap closed — remove the marker and, where applicable, the corresponding shim.
+- **Confirm `release/3.x`** is cut from pre-merge `main` and receiving upstream security patches for users who stay on the SDK v1 line.
diff --git a/docs/docs.json b/docs/docs.json
new file mode 100644
index 0000000..fb1d309
--- /dev/null
+++ b/docs/docs.json
@@ -0,0 +1,515 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "appearance": {
+    "default": "system",
+    "strict": false
+  },
+  "background": {
+    "color": {
+      "dark": "#222831",
+      "light": "#EEEEEE"
+    },
+    "decoration": "gradient"
+  },
+  "banner": {
+    "content": "Meet [Prefect Horizon](https://prefect.io/horizon?utm_source=gofastmcp&utm_medium=docs&utm_campaign=docs_banner&utm_content=sitewide_banner), the enterprise MCP gateway built by the team behind FastMCP"
+  },
+  "colors": {
+    "dark": "#f72585",
+    "light": "#4cc9f0",
+    "primary": "#2d00f7"
+  },
+  "contextual": {
+    "options": ["copy", "view"]
+  },
+  "description": "The fast, Pythonic way to build MCP servers and clients.",
+  "errors": {
+    "404": {
+      "description": "You’ve wandered outside the context.",
+      "redirect": false,
+      "title": "Don't panic."
+    }
+  },
+  "favicon": {
+    "dark": "/assets/brand/favicon-dark.svg",
+    "light": "/assets/brand/favicon-light.svg"
+  },
+  "footer": {
+    "socials": {
+      "discord": "https://discord.gg/uu8dJCgttd",
+      "github": "https://github.com/PrefectHQ/fastmcp",
+      "website": "https://www.prefect.io",
+      "x": "https://x.com/fastmcp"
+    }
+  },
+  "integrations": {
+    "ga4": {
+      "measurementId": "G-64R5W1TJXG"
+    }
+  },
+  "interaction": {
+    "drilldown": false
+  },
+  "logo": {
+    "dark": "/assets/brand/wordmark-white.png",
+    "light": "/assets/brand/wordmark.png"
+  },
+  "name": "FastMCP",
+  "navbar": {
+    "links": [
+      {
+        "href": "https://discord.gg/uu8dJCgttd",
+        "icon": "discord",
+        "label": ""
+      },
+      {
+        "href": "https://prefect.io/horizon",
+        "icon": "cloud",
+        "label": "Prefect Horizon"
+      }
+    ],
+    "primary": {
+      "href": "https://github.com/PrefectHQ/fastmcp",
+      "type": "github"
+    }
+  },
+  "navigation": {
+    "versions": [
+      {
+        "dropdowns": [
+          {
+            "dropdown": "Documentation",
+            "groups": [
+              {
+                "group": "Get Started",
+                "pages": [
+                  "getting-started/welcome",
+                  "getting-started/installation",
+                  "getting-started/quickstart"
+                ]
+              },
+              {
+                "group": "Servers",
+                "pages": [
+                  "servers/server",
+                  {
+                    "collapsed": true,
+                    "group": "Core Components",
+                    "icon": "toolbox",
+                    "pages": [
+                      "servers/tools",
+                      "servers/resources",
+                      "servers/prompts",
+                      "servers/context"
+                    ]
+                  },
+                  {
+                    "collapsed": true,
+                    "group": "Working with Tools",
+                    "icon": "wand-magic-sparkles",
+                    "pages": [
+                      "servers/transforms/transforms",
+                      "servers/transforms/tool-transformation",
+                      "servers/transforms/code-mode",
+                      "servers/transforms/tool-search",
+                      "servers/transforms/namespace",
+                      "servers/visibility",
+                      "servers/transforms/resources-as-tools",
+                      "servers/transforms/prompts-as-tools",
+                      "servers/tool-fingerprinting"
+                    ]
+                  },
+                  {
+                    "collapsed": true,
+                    "group": "MCP Providers",
+                    "icon": "layer-group",
+                    "pages": [
+                      "servers/providers/overview",
+                      "servers/providers/local",
+                      "servers/providers/filesystem",
+                      "servers/providers/proxy",
+                      "servers/providers/skills",
+                      "servers/composition",
+                      "servers/providers/custom"
+                    ]
+                  },
+                  {
+                    "collapsed": true,
+                    "group": "Interactivity",
+                    "icon": "comments",
+                    "pages": [
+                      "servers/elicitation",
+                      "servers/sampling",
+                      "servers/progress",
+                      "servers/logging",
+                      "servers/pagination",
+                      "servers/icons"
+                    ]
+                  },
+                  {
+                    "collapsed": true,
+                    "group": "Extensibility",
+                    "icon": "puzzle-piece",
+                    "pages": [
+                      "servers/middleware",
+                      "servers/dependency-injection",
+                      "servers/lifespan",
+                      "servers/storage-backends",
+                      "servers/tasks",
+                      "servers/versioning"
+                    ]
+                  },
+                  {
+                    "collapsed": true,
+                    "group": "Auth",
+                    "icon": "shield-check",
+                    "pages": [
+                      {
+                        "collapsed": true,
+                        "group": "Authentication",
+                        "icon": "key",
+                        "pages": [
+                          "servers/auth/authentication",
+                          "servers/auth/token-verification",
+                          "servers/auth/remote-oauth",
+                          "servers/auth/oauth-proxy",
+                          "servers/auth/oidc-proxy",
+                          "servers/auth/full-oauth-server",
+                          "servers/auth/multi-auth"
+                        ]
+                      },
+                      "servers/authorization"
+                    ]
+                  },
+                  {
+                    "collapsed": true,
+                    "group": "Deployment",
+                    "icon": "rocket",
+                    "pages": [
+                      "deployment/running-server",
+                      "deployment/http",
+                      "deployment/sandboxed-agents",
+                      "deployment/prefect-horizon",
+                      "deployment/server-configuration",
+                      "servers/testing",
+                      "servers/telemetry"
+                    ]
+                  }
+                ]
+              },
+              {
+                "group": "Apps",
+                "pages": [
+                  "apps/overview",
+                  "apps/quickstart",
+                  "apps/fastmcp-app",
+                  "apps/prefab",
+                  "apps/generative",
+                  "apps/low-level",
+                  {
+                    "collapsed": true,
+                    "group": "Reference",
+                    "icon": "book",
+                    "pages": [
+                      {
+                        "collapsed": true,
+                        "group": "Prefab Providers",
+                        "icon": "cube",
+                        "pages": [
+                          "apps/providers/approval",
+                          "apps/providers/choice",
+                          "apps/providers/file-upload",
+                          "apps/providers/form"
+                        ]
+                      },
+                      "apps/development",
+                      "apps/examples",
+                      "apps/architecture"
+                    ]
+                  }
+                ]
+              },
+              {
+                "group": "Clients",
+                "pages": [
+                  "clients/client",
+                  "clients/client-only-package",
+                  "clients/transports",
+                  "clients/fastmcp-remote",
+                  {
+                    "collapsed": true,
+                    "group": "Operations",
+                    "icon": "toolbox",
+                    "pages": [
+                      "clients/tools",
+                      "clients/resources",
+                      "clients/prompts",
+                      "clients/sampling",
+                      "clients/elicitation",
+                      "clients/tasks",
+                      "clients/progress",
+                      "clients/logging",
+                      "clients/roots",
+                      "clients/notifications"
+                    ],
+                    "tag": "UPDATED"
+                  },
+                  {
+                    "collapsed": true,
+                    "group": "Authentication",
+                    "icon": "key",
+                    "pages": [
+                      "clients/auth/oauth",
+                      "clients/auth/cimd",
+                      "clients/auth/bearer"
+                    ],
+                    "tag": "UPDATED"
+                  }
+                ]
+              },
+              {
+                "group": "Integrations",
+                "pages": [
+                  {
+                    "collapsed": true,
+                    "group": "Auth",
+                    "icon": "key",
+                    "pages": [
+                      "integrations/auth0",
+                      "integrations/authkit",
+                      "integrations/aws-cognito",
+                      "integrations/azure",
+                      "integrations/descope",
+                      "integrations/discord",
+                      "integrations/eunomia-authorization",
+                      "integrations/github",
+                      "integrations/google",
+                      "integrations/huggingface",
+                      "integrations/keycloak",
+                      "integrations/oci",
+                      "integrations/permit",
+                      "integrations/propelauth",
+                      "integrations/scalekit",
+                      "integrations/supabase",
+                      "integrations/workos"
+                    ]
+                  },
+                  {
+                    "collapsed": true,
+                    "group": "Web Frameworks",
+                    "icon": "code",
+                    "pages": ["integrations/fastapi", "integrations/openapi"]
+                  },
+                  {
+                    "collapsed": true,
+                    "group": "AI Assistants",
+                    "icon": "robot",
+                    "pages": [
+                      "integrations/chatgpt",
+                      "integrations/claude-code",
+                      "integrations/claude-desktop",
+                      "integrations/cursor",
+                      "integrations/gemini-cli",
+                      "integrations/goose"
+                    ]
+                  },
+                  {
+                    "collapsed": true,
+                    "group": "AI SDKs",
+                    "icon": "microchip",
+                    "pages": [
+                      "integrations/anthropic",
+                      "integrations/gemini",
+                      "integrations/openai",
+                      "integrations/pydantic-ai"
+                    ]
+                  },
+                  "integrations/mcp-json-configuration"
+                ]
+              },
+              {
+                "group": "More",
+                "pages": [
+                  "more/settings",
+                  {
+                    "collapsed": true,
+                    "group": "CLI",
+                    "icon": "terminal",
+                    "pages": [
+                      "cli/overview",
+                      "cli/running",
+                      "cli/install-mcp",
+                      "cli/inspecting",
+                      "cli/client",
+                      "cli/generate-cli",
+                      "cli/auth"
+                    ]
+                  },
+                  {
+                    "collapsed": true,
+                    "group": "Upgrading",
+                    "icon": "up",
+                    "pages": [
+                      "getting-started/upgrading/from-fastmcp-2",
+                      "getting-started/upgrading/from-fastmcp-3",
+                      "getting-started/upgrading/from-mcp-sdk",
+                      "getting-started/upgrading/from-low-level-sdk"
+                    ]
+                  },
+                  {
+                    "collapsed": true,
+                    "group": "Development",
+                    "icon": "code",
+                    "pages": [
+                      "development/contributing",
+                      "development/tests",
+                      "development/releases",
+                      "patterns/contrib",
+                      {
+                        "collapsed": true,
+                        "group": "v4 Notes",
+                        "pages": [
+                          "development/v4-notes/index",
+                          "development/v4-notes/change-register",
+                          "development/v4-notes/feature-program",
+                          "development/v4-notes/known-gaps"
+                        ]
+                      }
+                    ]
+                  },
+                  {
+                    "collapsed": true,
+                    "group": "What's New",
+                    "icon": "sparkles",
+                    "pages": ["updates", "changelog"]
+                  },
+                  "more/faq"
+                ]
+              }
+            ],
+            "icon": "book"
+          },
+          {
+            "anchors": [
+              {
+                "anchor": "Python SDK",
+                "icon": "python",
+                "pages": {
+                  "$ref": "./python-sdk-pages.json"
+                }
+              }
+            ],
+            "dropdown": "SDK Reference",
+            "icon": "code"
+          }
+        ],
+        "version": "v3"
+      },
+      {
+        "$ref": "./v2-navigation.json"
+      }
+    ]
+  },
+  "redirects": [
+    {
+      "destination": "/apps/fastmcp-app",
+      "source": "/apps/interactive-apps"
+    },
+    {
+      "destination": "/apps/generative",
+      "source": "/apps/providers/generative"
+    },
+    {
+      "destination": "/apps/prefab",
+      "source": "/apps/patterns"
+    },
+    {
+      "destination": "/cli/overview",
+      "source": "/patterns/cli"
+    },
+    {
+      "destination": "/servers/testing",
+      "source": "/patterns/testing"
+    },
+    {
+      "destination": "/cli/client",
+      "source": "/clients/cli"
+    },
+    {
+      "destination": "/cli/generate-cli",
+      "source": "/clients/generate-cli"
+    },
+    {
+      "destination": "/deployment/prefect-horizon",
+      "source": "/deployment/fastmcp-cloud"
+    },
+    {
+      "destination": "/deployment/prefect-horizon",
+      "source": "/v2/deployment/fastmcp-cloud"
+    },
+    {
+      "destination": "/v2/clients/messages",
+      "source": "/clients/messages"
+    },
+    {
+      "destination": "/v2/patterns/decorating-methods",
+      "source": "/patterns/decorating-methods"
+    },
+    {
+      "destination": "/servers/providers/proxy",
+      "source": "/patterns/proxy"
+    },
+    {
+      "destination": "/servers/composition",
+      "source": "/patterns/composition"
+    },
+    {
+      "destination": "/servers/providers/proxy",
+      "source": "/servers/proxy"
+    },
+    {
+      "destination": "/servers/composition",
+      "source": "/servers/providers/mounting"
+    },
+    {
+      "destination": "/servers/transforms/transforms",
+      "source": "/servers/providers/namespacing"
+    },
+    {
+      "destination": "/servers/transforms/transforms",
+      "source": "/patterns/tool-transformation"
+    },
+    {
+      "destination": "/getting-started/upgrading/from-fastmcp-2",
+      "source": "/development/upgrade-guide"
+    },
+    {
+      "destination": "/getting-started/upgrading/from-mcp-sdk",
+      "source": "/getting-started/upgrading-from-sdk"
+    },
+    {
+      "destination": "/getting-started/upgrading/from-low-level-sdk",
+      "source": "/getting-started/low-level-sdk"
+    },
+    {
+      "destination": "/getting-started/upgrading/from-fastmcp-3",
+      "source": "/getting-started/upgrading/to-mcp-sdk-v2"
+    }
+  ],
+  "search": {
+    "prompt": "Search the docs..."
+  },
+  "styling": {
+    "codeblocks": {
+      "theme": {
+        "dark": "dark-plus",
+        "light": "snazzy-light"
+      }
+    }
+  },
+  "theme": "almond",
+  "thumbnails": {
+    "appearance": "light",
+    "background": "/assets/brand/thumbnail-background-4.jpeg"
+  }
+}
diff --git a/docs/fastmcp-analytics.js b/docs/fastmcp-analytics.js
new file mode 100644
index 0000000..07be005
--- /dev/null
+++ b/docs/fastmcp-analytics.js
@@ -0,0 +1,257 @@
+(function () {
+  if (typeof window === "undefined") return;
+
+  // Public browser key for the shared Prefect Amplitude project.
+  // This is intentionally client-side; the secret key must never ship to the browser.
+  var AMPLITUDE_API_KEY = "c361ed56e7bdc1a48a38773c40120b39";
+  var AMPLITUDE_SCRIPT_URL =
+    "https://cdn.amplitude.com/libs/analytics-browser-2.8.1-min.js.gz";
+  var AMPLITUDE_SERVER_URL = "https://api2.amplitude.com/2/httpapi";
+  var PAGE_VIEW_EVENT = "Page View: FastMCP Docs";
+  var OUTBOUND_CLICK_EVENT = "Docs Outbound Clicked";
+  var SOURCE = "docs";
+  var SOURCE_DETAIL = "fastmcp";
+  var SURFACE = "fastmcp_docs";
+  var DEVICE_ID_PARAM = "deviceId";
+  var routeListenersInstalled = false;
+  var amplitudeInitialized = false;
+  var lastTrackedUrl = null;
+
+  var PREFECT_DESTINATION_HOSTNAMES = [
+    "www.prefect.io",
+    "prefect.io",
+    "horizon.prefect.io",
+    "app.prefect.cloud",
+  ];
+
+  var routeChangeCallbacks = [];
+
+  function loadScript(src, onload) {
+    var script = document.createElement("script");
+    script.src = src;
+    script.async = true;
+
+    if (typeof onload === "function") {
+      script.addEventListener("load", onload);
+    }
+
+    document.head.appendChild(script);
+    return script;
+  }
+
+  function getAmplitude() {
+    return window.amplitude || window.amplitudeAnalytics;
+  }
+
+  function normalizePathname(pathname) {
+    if (pathname === "/") return pathname;
+    return pathname.replace(/\/+$/, "");
+  }
+
+  function observeRouteChanges(callback) {
+    routeChangeCallbacks.push(callback);
+
+    if (!routeListenersInstalled) {
+      var fireCallbacks = function () {
+        routeChangeCallbacks.forEach(function (cb) {
+          window.setTimeout(cb, 0);
+        });
+      };
+
+      var wrapHistoryMethod = function (methodName) {
+        var original = window.history[methodName];
+        window.history[methodName] = function () {
+          var result = original.apply(this, arguments);
+          fireCallbacks();
+          return result;
+        };
+      };
+
+      wrapHistoryMethod("pushState");
+      wrapHistoryMethod("replaceState");
+      window.addEventListener("popstate", fireCallbacks);
+      window.addEventListener("hashchange", fireCallbacks);
+      routeListenersInstalled = true;
+    }
+
+    callback();
+  }
+
+  function buildPageViewProperties() {
+    return {
+      url: window.location.href,
+      title: document.title,
+      referrer: document.referrer || null,
+      path: normalizePathname(window.location.pathname),
+      source: SOURCE,
+      source_detail: SOURCE_DETAIL,
+      surface: SURFACE,
+    };
+  }
+
+  function trackPageView() {
+    var amplitude = getAmplitude();
+    if (!amplitude || typeof amplitude.track !== "function") {
+      return;
+    }
+
+    var url = window.location.href;
+    if (url === lastTrackedUrl) {
+      return;
+    }
+
+    amplitude.track(PAGE_VIEW_EVENT, buildPageViewProperties());
+    lastTrackedUrl = url;
+  }
+
+  function parseUrl(href) {
+    try {
+      return new URL(href, window.location.origin);
+    } catch (error) {
+      return null;
+    }
+  }
+
+  function isPrefectDestination(url) {
+    return PREFECT_DESTINATION_HOSTNAMES.indexOf(url.hostname) !== -1;
+  }
+
+  function addDeviceIdToLink(event) {
+    var amplitude = getAmplitude();
+    if (!amplitude || typeof amplitude.getDeviceId !== "function") {
+      return;
+    }
+
+    var link = event.currentTarget;
+    var href = link.getAttribute("href") || "";
+
+    var url = parseUrl(href);
+    if (!url || !isPrefectDestination(url)) {
+      return;
+    }
+
+    url.searchParams.set(DEVICE_ID_PARAM, amplitude.getDeviceId());
+    link.href = url.toString();
+  }
+
+  function removeDeviceIdFromLink(event) {
+    var link = event.currentTarget;
+    var href = link.getAttribute("href") || "";
+
+    var url = parseUrl(href);
+    if (!url || !isPrefectDestination(url)) {
+      return;
+    }
+
+    url.searchParams.delete(DEVICE_ID_PARAM);
+    link.href = url.toString();
+  }
+
+  function attachDeviceIdForwarding() {
+    var elements = document.querySelectorAll("a[href]");
+    elements.forEach(function (element) {
+      if (element.dataset.fastmcpDeviceIdBound === "true") {
+        return;
+      }
+
+      var url = parseUrl(element.getAttribute("href") || "");
+      if (!url || !isPrefectDestination(url)) {
+        return;
+      }
+
+      element.addEventListener("mouseenter", addDeviceIdToLink);
+      element.addEventListener("mouseleave", removeDeviceIdFromLink);
+      element.addEventListener("focus", addDeviceIdToLink);
+      element.addEventListener("blur", removeDeviceIdFromLink);
+      element.addEventListener("touchstart", addDeviceIdToLink);
+      element.addEventListener("touchcancel", removeDeviceIdFromLink);
+      element.dataset.fastmcpDeviceIdBound = "true";
+    });
+  }
+
+  function trackOutboundClick(event) {
+    var link = event.target && event.target.closest
+      ? event.target.closest("a[href]")
+      : null;
+
+    if (!link) {
+      return;
+    }
+
+    var href = link.getAttribute("href");
+    if (!href || href[0] === "#") {
+      return;
+    }
+
+    var destination;
+    destination = parseUrl(href);
+    if (!destination) {
+      return;
+    }
+
+    if (destination.hostname === window.location.hostname) {
+      return;
+    }
+
+    var amplitude = getAmplitude();
+    if (!amplitude || typeof amplitude.track !== "function") {
+      return;
+    }
+
+    amplitude.track(OUTBOUND_CLICK_EVENT, {
+      path: normalizePathname(window.location.pathname),
+      url: window.location.href,
+      title: document.title,
+      source: SOURCE,
+      source_detail: SOURCE_DETAIL,
+      surface: SURFACE,
+      destination: destination.href,
+      destination_domain: destination.hostname,
+      link_text: (link.textContent || "").trim().slice(0, 200),
+      is_prefect_destination: isPrefectDestination(destination),
+    });
+  }
+
+  function initializeAmplitude() {
+    var amplitude = getAmplitude();
+    if (
+      amplitudeInitialized ||
+      !amplitude ||
+      typeof amplitude.init !== "function"
+    ) {
+      return;
+    }
+
+    amplitude.init(AMPLITUDE_API_KEY, undefined, {
+      useBatch: true,
+      serverUrl: AMPLITUDE_SERVER_URL,
+      attribution: {
+        disabled: false,
+        trackNewCampaigns: true,
+        trackPageViews: true,
+        resetSessionOnNewCampaign: true,
+      },
+      defaultTracking: {
+        pageViews: false,
+        sessions: false,
+        formInteractions: true,
+        fileDownloads: true,
+      },
+    });
+
+    amplitudeInitialized = true;
+    observeRouteChanges(trackPageView);
+    observeRouteChanges(attachDeviceIdForwarding);
+  }
+
+  function initialize() {
+    document.addEventListener("click", trackOutboundClick, true);
+    loadScript(AMPLITUDE_SCRIPT_URL, initializeAmplitude);
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initialize);
+  } else {
+    initialize();
+  }
+})();
diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdx
new file mode 100644
index 0000000..4dae8e9
--- /dev/null
+++ b/docs/getting-started/installation.mdx
@@ -0,0 +1,118 @@
+---
+title: Installation
+description: Install FastMCP and verify your setup
+icon: arrow-down-to-line
+---
+## Install FastMCP
+
+We recommend using [uv](https://docs.astral.sh/uv/getting-started/installation/) to install and manage FastMCP.
+
+```bash
+pip install fastmcp
+```
+
+Or with uv:
+
+```bash
+uv add fastmcp
+```
+
+### Optional Dependencies
+
+FastMCP provides optional extras for specific features. For example, to install the background tasks extra:
+
+```bash
+pip install "fastmcp[tasks]"
+```
+
+See [Background Tasks](/servers/tasks) for details on the task system.
+
+### Verify Installation
+
+To verify that FastMCP is installed correctly, you can run the following command:
+
+```bash
+fastmcp version
+```
+
+You should see output like the following:
+
+```bash
+$ fastmcp version
+
+FastMCP version:                           3.0.0
+MCP version:                               1.25.0
+Python version:                            3.12.2
+Platform:            macOS-15.3.1-arm64-arm-64bit
+FastMCP root path:            ~/Developer/fastmcp
+```
+
+### Dependency Licensing
+
+<Info>
+FastMCP depends on Cyclopts for CLI functionality. Cyclopts v4 includes docutils as a transitive dependency, which has complex licensing that may trigger compliance reviews in some organizations.
+
+If this is a concern, you can install Cyclopts v5 alpha which removes this dependency:
+
+```bash
+pip install "cyclopts>=5.0.0a1"
+```
+
+Alternatively, wait for the stable v5 release. See [this issue](https://github.com/BrianPugh/cyclopts/issues/672) for details.
+</Info>
+## Upgrading
+
+### From FastMCP 2.0
+
+See the [Upgrade Guide](/getting-started/upgrading/from-fastmcp-2) for a complete list of breaking changes and migration steps.
+
+### From the MCP SDK
+
+#### From FastMCP 1.0
+
+If you're using FastMCP 1.0 via the `mcp` package (meaning you import FastMCP as  `from mcp.server.fastmcp import FastMCP`), upgrading is straightforward — for most servers, it's a single import change. See the [full upgrade guide](/getting-started/upgrading/from-mcp-sdk) for details.
+
+#### From the Low-Level Server API
+
+If you built your server directly on the `mcp` package's `Server` class — with `list_tools()`/`call_tool()` handlers and hand-written JSON Schema — see the [migration guide](/getting-started/upgrading/from-low-level-sdk) for a full walkthrough.
+
+## Troubleshooting
+
+### `import fastmcp` fails after a pip upgrade
+
+This affects one specific case: upgrading to FastMCP 3.3 or later from FastMCP 3.2 or earlier with `pip`. Fresh installs and `uv` upgrades are unaffected, so you can skip this unless you did exactly that.
+
+If `import fastmcp` raises `ModuleNotFoundError`, or `from fastmcp import FastMCP` raises `ImportError`, immediately after the upgrade, your install is in a half-removed state. Reinstall in a single step:
+
+```bash
+pip install --force-reinstall fastmcp
+```
+
+If that doesn't resolve it, remove both distributions and reinstall from a clean state:
+
+```bash
+pip uninstall -y fastmcp fastmcp-slim
+pip install fastmcp
+```
+
+FastMCP 3.3 moved the importable code from the `fastmcp` distribution into `fastmcp-slim`. During a single-command `pip` upgrade, pip can install the new files and then delete them while uninstalling the old `fastmcp` distribution, whose file manifest still lists those paths. `uv` uninstalls before it installs, so it is unaffected.
+
+## Versioning Policy
+
+FastMCP follows semantic versioning with pragmatic adaptations for the rapidly evolving MCP ecosystem. Breaking changes may occur in minor versions (e.g., 2.3.x to 2.4.0) when necessary to stay current with the MCP Protocol.
+
+For production use, always pin to exact versions:
+```
+fastmcp==3.0.0  # Good
+fastmcp>=3.0.0  # Bad - may install breaking changes
+```
+
+See the full [versioning and release policy](/development/releases#versioning-policy) for details on our public API, deprecation practices, and breaking change philosophy.
+
+## Contributing to FastMCP
+
+Interested in contributing to FastMCP? See the [Contributing Guide](/development/contributing) for details on:
+- Setting up your development environment
+- Running tests and pre-commit hooks
+- Submitting issues and pull requests
+- Code standards and review process
diff --git a/docs/getting-started/quickstart.mdx b/docs/getting-started/quickstart.mdx
new file mode 100644
index 0000000..97d9f3c
--- /dev/null
+++ b/docs/getting-started/quickstart.mdx
@@ -0,0 +1,164 @@
+---
+title: Quickstart
+icon: rocket-launch
+---
+
+Welcome! This guide will help you quickly set up FastMCP, run your first MCP server, give it a visual UI, and deploy it to Prefect Horizon.
+
+If you haven't already installed FastMCP, follow the [installation instructions](/getting-started/installation).
+
+## Create a FastMCP Server
+
+A FastMCP server is a collection of tools, resources, and other MCP components. To create a server, start by instantiating the `FastMCP` class. 
+
+Create a new file called `my_server.py` and add the following code:
+
+```python my_server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP("My MCP Server")
+```
+
+
+That's it! You've created a FastMCP server, albeit a very boring one. Let's add a tool to make it more interesting.
+
+
+## Add a Tool
+
+To add a tool that returns a simple greeting, write a function and decorate it with `@mcp.tool` to register it with the server:
+
+```python my_server.py {5-7}
+from fastmcp import FastMCP
+
+mcp = FastMCP("My MCP Server")
+
+@mcp.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+```
+
+
+## Run the Server
+
+The simplest way to run your FastMCP server is to call its `run()` method. You can choose between different transports, like `stdio` for local servers, or `http` for remote access:
+
+<CodeGroup>
+
+```python my_server.py (stdio) {9, 10}
+from fastmcp import FastMCP
+
+mcp = FastMCP("My MCP Server")
+
+@mcp.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+```python my_server.py (HTTP) {9, 10}
+from fastmcp import FastMCP
+
+mcp = FastMCP("My MCP Server")
+
+@mcp.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+
+</CodeGroup>
+
+This lets us run the server with `python my_server.py`. The stdio transport is the traditional way to connect MCP servers to clients, while the HTTP transport enables remote connections.
+
+<Tip>
+Why do we need the `if __name__ == "__main__":` block?
+
+The `__main__` block is recommended for consistency and compatibility, ensuring your server works with all MCP clients that execute your server file as a script. Users who will exclusively run their server with the FastMCP CLI can omit it, as the CLI imports the server object directly.
+</Tip>
+
+### Using the FastMCP CLI
+
+You can also use the `fastmcp run` command to start your server. Note that the FastMCP CLI **does not** execute the `__main__` block of your server file. Instead, it imports your server object and runs it with whatever transport and options you provide.
+
+For example, to run this server with the default stdio transport (no matter how you called `mcp.run()`), you can use the following command:
+```bash
+fastmcp run my_server.py:mcp
+```
+
+To run this server with the HTTP transport, you can use the following command:
+```bash
+fastmcp run my_server.py:mcp --transport http --port 8000
+```
+
+## Call Your Server
+
+Once your server is running with HTTP transport, you can connect to it with a FastMCP client or any LLM client that supports the MCP protocol:
+
+```python my_client.py
+import asyncio
+from fastmcp import Client
+
+client = Client("http://localhost:8000/mcp")
+
+async def call_tool(name: str):
+    async with client:
+        result = await client.call_tool("greet", {"name": name})
+        print(result)
+
+asyncio.run(call_tool("Ford"))
+```
+
+Note that:
+- FastMCP clients are asynchronous, so we need to use `asyncio.run` to run the client
+- We must enter a client context (`async with client:`) before using the client
+- You can make multiple client calls within the same context
+
+## Give Your Tool a UI
+
+Tools normally return text, but any tool can return an interactive UI instead. Add `app=True` to your tool decorator and return a [Prefab](https://prefab.prefect.io) component — the host renders it as a chart, table, form, or any other visual element right in the conversation. This requires the `apps` extra (`pip install "fastmcp[apps]"`).
+
+The `app=True` flag tells FastMCP to wire up the renderer and protocol metadata automatically. The tool still works like any other MCP tool — it receives arguments and returns a result — but the result is a component tree that the host displays visually instead of as plain text.
+
+```python my_server.py
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import Column, Heading, Text, Badge, Row
+from fastmcp import FastMCP
+
+mcp = FastMCP("My MCP Server")
+
+
+@mcp.tool(app=True)
+def greet(name: str) -> PrefabApp:
+    """Greet someone with a visual card."""
+    with Column(gap=4, css_class="p-6") as view:
+        Heading(f"Hello, {name}!")
+        with Row(gap=2, align="center"):
+            Text("Status")
+            Badge("Greeted", variant="success")
+
+    return PrefabApp(view=view)
+```
+
+You can preview app tools locally with `fastmcp dev apps my_server.py` — no MCP host required. See the [Apps overview](/apps/overview) for the full guide, including state management, forms, charts, and server-connected interactivity.
+
+## Deploy to Prefect Horizon
+
+[Prefect Horizon](https://horizon.prefect.io?utm_source=gofastmcp&utm_medium=docs) is the enterprise MCP platform built by the FastMCP team at [Prefect](https://www.prefect.io). It provides managed hosting, authentication, access control, and observability for MCP servers.
+
+<Info>
+Horizon is **free for personal projects** and offers enterprise governance for teams.
+</Info>
+
+To deploy your server, you'll need a [GitHub account](https://github.com). Once you have one, you can deploy your server in three steps:
+
+1. Push your `my_server.py` file to a GitHub repository
+2. Sign in to [Prefect Horizon](https://horizon.prefect.io?utm_source=gofastmcp&utm_medium=docs) with your GitHub account
+3. Create a new project from your repository and enter `my_server.py:mcp` as the server entrypoint
+
+That's it! Horizon will build and deploy your server, making it available at a URL like `https://your-project.fastmcp.app/mcp`. You can chat with it to test its functionality, or connect to it from any LLM client that supports the MCP protocol.
+
+For more details, see the [Prefect Horizon guide](/deployment/prefect-horizon).
diff --git a/docs/getting-started/upgrading/from-fastmcp-2.mdx b/docs/getting-started/upgrading/from-fastmcp-2.mdx
new file mode 100644
index 0000000..eef5d4e
--- /dev/null
+++ b/docs/getting-started/upgrading/from-fastmcp-2.mdx
@@ -0,0 +1,450 @@
+---
+title: Upgrading from FastMCP 2
+sidebarTitle: "From FastMCP 2"
+description: Migration instructions for upgrading between FastMCP versions
+icon: up
+---
+
+This guide covers breaking changes and migration steps when upgrading FastMCP.
+
+## v3.0.0
+
+For most servers, upgrading to v3 is straightforward. The breaking changes below affect deprecated constructor kwargs, sync-to-async shifts, a few renamed methods, and some less commonly used features.
+
+### Install
+
+Since you already have `fastmcp` installed, you need to explicitly request the new version — `pip install fastmcp` won't upgrade an existing installation:
+
+```bash
+pip install --upgrade fastmcp
+# or
+uv add --upgrade fastmcp
+```
+
+If you pin versions in a requirements file or `pyproject.toml`, update your pin to `fastmcp>=3.0.0,<4`.
+
+<Info>
+**New repository home.** As part of the v3 release, FastMCP's GitHub repository has moved from `jlowin/fastmcp` to [`PrefectHQ/fastmcp`](https://github.com/PrefectHQ/fastmcp) under [Prefect](https://prefect.io)'s stewardship. GitHub automatically redirects existing clones and bookmarks, so nothing breaks — but you can update your local remote whenever convenient:
+
+```bash
+git remote set-url origin https://github.com/PrefectHQ/fastmcp.git
+```
+
+If you reference the repository URL in dependency specifications (e.g., `git+https://github.com/jlowin/fastmcp.git`), update those to the new location.
+</Info>
+
+<Prompt description="Copy this prompt into any LLM along with your server code to get automated upgrade guidance.">
+You are upgrading a FastMCP v2 server to FastMCP v3.0. Analyze the provided code and identify every change needed. The full upgrade guide is at https://gofastmcp.com/getting-started/upgrading/from-fastmcp-2 and the complete FastMCP documentation is at https://gofastmcp.com — fetch these for complete context.
+
+BREAKING CHANGES (will crash at import or runtime):
+
+1. CONSTRUCTOR KWARGS REMOVED: FastMCP() no longer accepts these kwargs (raises TypeError):
+   - Transport settings: host, port, log_level, debug, sse_path, streamable_http_path, json_response, stateless_http
+     Fix: pass to run() or run_http_async() instead, e.g. mcp.run(transport="http", host="0.0.0.0", port=8080)
+   - message_path: set via environment variable FASTMCP_MESSAGE_PATH only (not a run() kwarg)
+   - Duplicate handling: on_duplicate_tools, on_duplicate_resources, on_duplicate_prompts
+     Fix: use unified on_duplicate= parameter
+   - Tool settings: tool_serializer, include_tags, exclude_tags, tool_transformations
+     Fix: use ToolResult returns, server.enable()/disable(), server.add_transform()
+
+2. COMPONENT METHODS REMOVED:
+   - tool.enable()/disable() raises NotImplementedError
+     Fix: server.disable(names={"tool_name"}, components={"tool"}) or server.disable(tags={"tag"})
+   - get_tools()/get_resources()/get_prompts()/get_resource_templates() removed
+     Fix: use list_tools()/list_resources()/list_prompts()/list_resource_templates() — these return lists, not dicts
+
+3. ASYNC STATE: ctx.set_state() and ctx.get_state() are now async (must be awaited).
+   State values must be JSON-serializable unless serializable=False is passed.
+   Each FastMCP instance has its own state store, so serializable state set by parent middleware isn't visible to mounted tools by default.
+   Fix: pass the same session_state_store to both servers, or use serializable=False (request-scoped state is always shared).
+
+4. PROMPTS: mcp.types.PromptMessage replaced by fastmcp.prompts.Message.
+   Before: PromptMessage(role="user", content=TextContent(type="text", text="Hello"))
+   After:  Message("Hello")  # role defaults to "user", accepts plain strings
+   Also: if prompts return raw dicts like `{"role": "user", "content": "..."}`, these must become Message objects.
+   v2 silently coerced dicts; v3 requires typed Message objects or plain strings.
+
+5. AUTH PROVIDERS: No longer auto-load from env vars. Pass client_id, client_secret explicitly via os.environ.
+
+6. WSTRANSPORT: Removed. Use StreamableHttpTransport.
+
+7. OPENAPI: timeout parameter removed from OpenAPIProvider. Set timeout on the httpx.AsyncClient instead.
+
+8. METADATA: Namespace changed from "_fastmcp" to "fastmcp" in tool.meta. The include_fastmcp_meta parameter is removed (always included).
+
+9. ENV VAR: FASTMCP_SHOW_CLI_BANNER renamed to FASTMCP_SHOW_SERVER_BANNER.
+
+10. DECORATORS: @mcp.tool, @mcp.resource, @mcp.prompt now return the original function, not a component object. Code that accesses .name, .description, or other component attributes on the decorated result will crash with AttributeError.
+   Fix: access component objects via the server (e.g. await mcp.get_tool("name")) instead of the decorated function. The FASTMCP_DECORATOR_MODE=object escape hatch that existed in v3 was removed in FastMCP 4.0.
+
+11. OAUTH STORAGE: Default OAuth client storage changed from DiskStore to FileTreeStore due to pickle deserialization vulnerability in diskcache (CVE-2025-69872). Clients using default storage will re-register automatically on first connection. If using DiskStore explicitly, switch to FileTreeStore (with key/collection sanitization strategies) or add pip install 'py-key-value-aio[disk]'.
+
+12. REPO MOVE: GitHub repository moved from jlowin/fastmcp to PrefectHQ/fastmcp. Update git remotes and dependency URLs that reference the old location.
+
+13. BACKGROUND TASKS: FastMCP's background task system (SEP-1686) is now an optional dependency. If the code uses task=True or TaskConfig, add pip install "fastmcp[tasks]".
+
+DEPRECATIONS (still work but emit warnings):
+
+- mount(prefix="x") -> mount(namespace="x")
+- import_server(sub) -> mount(sub)
+- FastMCP.as_proxy(url) -> from fastmcp.server import create_proxy; create_proxy(url)
+- from fastmcp.server.proxy -> from fastmcp.server.providers.proxy
+- from fastmcp.server.openapi import FastMCPOpenAPI -> from fastmcp.server.providers.openapi import OpenAPIProvider; use FastMCP("name", providers=[OpenAPIProvider(...)])
+- mcp.add_tool_transformation(name, cfg) -> from fastmcp.server.transforms import ToolTransform; mcp.add_transform(ToolTransform(...))
+
+For each issue found, show the original line, explain why it breaks, and provide the corrected code.
+</Prompt>
+
+### Breaking Changes
+
+**Transport and server settings removed from constructor**
+
+In v2, you could configure transport settings directly in the `FastMCP()` constructor. In v3, `FastMCP()` is purely about your server's identity and behavior — transport configuration happens when you actually start serving. Passing any of the old kwargs now raises `TypeError` with a migration hint.
+
+```python
+# Before
+mcp = FastMCP("server", host="0.0.0.0", port=8080)
+mcp.run()
+
+# After
+mcp = FastMCP("server")
+mcp.run(transport="http", host="0.0.0.0", port=8080)
+```
+
+The full list of removed kwargs and their replacements:
+
+- `host`, `port`, `log_level`, `debug`, `sse_path`, `streamable_http_path`, `json_response`, `stateless_http` — pass to `run()`, `run_http_async()`, or `http_app()`, or set via environment variables (e.g. `FASTMCP_HOST`)
+- `message_path` — set via environment variable `FASTMCP_MESSAGE_PATH` only (not a `run()` kwarg)
+- `on_duplicate_tools`, `on_duplicate_resources`, `on_duplicate_prompts` — consolidated into a single `on_duplicate=` parameter
+- `tool_serializer` — return [`ToolResult`](/servers/tools#custom-serialization) from your tools instead
+- `include_tags` / `exclude_tags` — use `server.enable(tags=..., only=True)` / `server.disable(tags=...)` after construction
+- `tool_transformations` — use `server.add_transform(ToolTransform(...))` after construction
+
+**OAuth storage backend changed (diskcache CVE)**
+
+The default OAuth client storage has moved from `DiskStore` to `FileTreeStore` to address a pickle deserialization vulnerability in diskcache ([CVE-2025-69872](https://github.com/PrefectHQ/fastmcp/issues/3166)).
+
+If you were using the default storage (i.e., not passing an explicit `client_storage`), clients will need to re-register on their first connection after upgrading. This happens automatically — no user action required, and it's the same flow that already occurs whenever a server restarts with in-memory storage.
+
+If you were passing a `DiskStore` explicitly, you can either [switch to `FileTreeStore`](/servers/storage-backends) (recommended) or keep using `DiskStore` by adding the dependency yourself.
+
+<Warning>
+When switching to `FileTreeStore`, you **must** configure key and collection sanitization strategies. Without them, keys containing special characters (such as URL-based OAuth client IDs) will cause filesystem errors. See the [File Storage](/servers/storage-backends#file-storage) section for the recommended setup.
+</Warning>
+
+<Warning>
+Keeping `DiskStore` requires `pip install 'py-key-value-aio[disk]'`, which re-introduces the vulnerable `diskcache` package into your dependency tree.
+</Warning>
+
+**Component enable()/disable() moved to server**
+
+In v2, you could enable or disable individual components by calling methods on the component object itself. In v3, visibility is controlled through the server (or provider), which lets you target components by name, tag, or type without needing a reference to the object:
+
+```python
+# Before
+tool = await server.get_tool("my_tool")
+tool.disable()
+
+# After
+server.disable(names={"my_tool"}, components={"tool"})
+```
+
+Calling `.enable()` or `.disable()` on a component object now raises `NotImplementedError`. See [Visibility](/servers/visibility) for the full API, including tag-based filtering and per-session visibility.
+
+**Listing methods renamed and return lists**
+
+The `get_tools()`, `get_resources()`, `get_prompts()`, and `get_resource_templates()` methods have been renamed to `list_tools()`, `list_resources()`, `list_prompts()`, and `list_resource_templates()`. More importantly, they now return lists instead of dicts — so code that indexes by name needs to change:
+
+```python
+# Before
+tools = await server.get_tools()
+tool = tools["my_tool"]
+
+# After
+tools = await server.list_tools()
+tool = next((t for t in tools if t.name == "my_tool"), None)
+```
+
+**Prompts use Message class**
+
+Prompt functions now use FastMCP's `Message` class instead of `mcp.types.PromptMessage`. The new class is simpler — it accepts a plain string and defaults to `role="user"`, so most prompts become one-liners:
+
+```python
+# Before
+from fastmcp.types import PromptMessage, TextContent
+
+@mcp.prompt
+def my_prompt() -> PromptMessage:
+    return PromptMessage(role="user", content=TextContent(type="text", text="Hello"))
+
+# After
+from fastmcp.prompts import Message
+
+@mcp.prompt
+def my_prompt() -> Message:
+    return Message("Hello")
+```
+
+If your prompt functions return raw dicts with `role` and `content` keys, those also need to change. v2 silently coerced dicts into prompt messages, but v3 requires typed `Message` objects (or plain strings for single user messages):
+
+```python
+# Before (v2 accepted this)
+@mcp.prompt
+def my_prompt():
+    return [
+        {"role": "user", "content": "Hello"},
+        {"role": "assistant", "content": "How can I help?"},
+    ]
+
+# After
+from fastmcp.prompts import Message
+
+@mcp.prompt
+def my_prompt() -> list[Message]:
+    return [
+        Message("Hello"),
+        Message("How can I help?", role="assistant"),
+    ]
+```
+
+**Context state methods are async**
+
+`ctx.set_state()` and `ctx.get_state()` are now async because state in v3 is session-scoped and backed by a pluggable storage backend (rather than a simple dict). This means state persists across multiple tool calls within the same session:
+
+```python
+# Before
+ctx.set_state("key", "value")
+value = ctx.get_state("key")
+
+# After
+await ctx.set_state("key", "value")
+value = await ctx.get_state("key")
+```
+
+State values must also be JSON-serializable by default (dicts, lists, strings, numbers, etc.). If you need to store non-serializable values like an HTTP client, pass `serializable=False` — these values are request-scoped and only available during the current tool call:
+
+```python
+await ctx.set_state("client", my_http_client, serializable=False)
+```
+
+**Mounted servers have isolated state stores**
+
+Each `FastMCP` instance has its own state store. In v2 this wasn't noticeable because mounted tools ran in the parent's context, but in v3's provider architecture each server is isolated. Non-serializable state (`serializable=False`) is request-scoped and automatically shared across mount boundaries. For serializable state, pass the same `session_state_store` to both servers:
+
+```python
+from fastmcp import FastMCP
+from key_value.aio.stores.memory import MemoryStore
+
+store = MemoryStore()
+parent = FastMCP("Parent", session_state_store=store)
+child = FastMCP("Child", session_state_store=store)
+parent.mount(child, namespace="child")
+```
+
+**Auth provider environment variables removed**
+
+In v2, auth providers like `GitHubProvider` could auto-load configuration from environment variables with a `FASTMCP_SERVER_AUTH_*` prefix. This magic has been removed — pass values explicitly:
+
+```python
+# Before (v2) — client_id and client_secret loaded automatically
+# from FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID, etc.
+auth = GitHubProvider()
+
+# After (v3) — pass values explicitly
+import os
+from fastmcp.server.auth.providers.github import GitHubProvider
+
+auth = GitHubProvider(
+    client_id=os.environ["GITHUB_CLIENT_ID"],
+    client_secret=os.environ["GITHUB_CLIENT_SECRET"],
+)
+```
+
+**WSTransport removed**
+
+The deprecated WebSocket client transport has been removed. Use `StreamableHttpTransport` instead:
+
+```python test="skip"
+# Before
+from fastmcp.client.transports import WSTransport
+transport = WSTransport("ws://localhost:8000/ws")
+
+# After
+from fastmcp.client.transports import StreamableHttpTransport
+transport = StreamableHttpTransport("http://localhost:8000/mcp")
+```
+
+**OpenAPI `timeout` parameter removed**
+
+`OpenAPIProvider` no longer accepts a `timeout` parameter. Configure timeout on the httpx client directly. The `client` parameter is also now optional — when omitted, a default client is created from the spec's `servers` URL with a 30-second timeout:
+
+```python
+# Before
+provider = OpenAPIProvider(spec, client, timeout=60)
+
+# After
+client = httpx.AsyncClient(base_url="https://api.example.com", timeout=60)
+provider = OpenAPIProvider(spec, client)
+```
+
+**Metadata namespace renamed**
+
+The FastMCP metadata key in component `meta` dicts changed from `_fastmcp` to `fastmcp`. If you read metadata from tool or resource objects, update the key:
+
+```python
+# Before
+tags = tool.meta.get("_fastmcp", {}).get("tags", [])
+
+# After
+tags = tool.meta.get("fastmcp", {}).get("tags", [])
+```
+
+Metadata is now always included — the `include_fastmcp_meta` parameter has been removed from `FastMCP()` and `to_mcp_tool()`, so there is no way to suppress it.
+
+**Server banner environment variable renamed**
+
+`FASTMCP_SHOW_CLI_BANNER` is now `FASTMCP_SHOW_SERVER_BANNER`.
+
+**Decorators return functions**
+
+In v2, `@mcp.tool` transformed your function into a `FunctionTool` object. In v3, decorators return your original function unchanged — which means decorated functions stay callable for testing, reuse, and composition:
+
+```python
+@mcp.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+greet("World")  # Works! Returns "Hello, World!"
+```
+
+If you have code that treats the decorated result as a `FunctionTool` (e.g., accessing `.name` or `.description`), the v2-compatible object-returning behavior was available in v3 via `FASTMCP_DECORATOR_MODE=object`. That escape hatch was removed in FastMCP 4.0 — decorators always return the original function now.
+
+**Background tasks require optional dependency**
+
+FastMCP's background task system (SEP-1686) is now behind an optional extra. If your server uses background tasks, install with:
+
+```bash
+pip install "fastmcp[tasks]"
+```
+
+Without the extra, configuring a tool with `task=True` or `TaskConfig` will raise an import error at runtime. See [Background Tasks](/servers/tasks) for details.
+
+### Deprecated Features
+
+These were deprecated in v3. Items marked **Removed in v4** no longer work at all — update to the replacement shown. The rest still work but emit warnings; update when convenient.
+
+**mount() prefix → namespace** (Removed in v4)
+
+```python
+# Removed in v4
+main.mount(subserver, prefix="api")
+
+# New
+main.mount(subserver, namespace="api")
+```
+
+**import_server() → mount()** (Removed in v4)
+
+```python
+# Removed in v4
+main.import_server(subserver)
+
+# New
+main.mount(subserver)
+```
+
+**Module import paths for proxy and OpenAPI**
+
+The proxy and OpenAPI modules moved under `providers` to reflect v3's provider-based architecture. The old `fastmcp.server.proxy` and `fastmcp.server.openapi` compatibility shims were **removed in 4.0** — import from the `providers` location instead:
+
+```python test="skip"
+# Removed in 4.0
+from fastmcp.server.proxy import FastMCPProxy
+from fastmcp.server.openapi import FastMCPOpenAPI
+
+# New
+from fastmcp.server.providers.proxy import FastMCPProxy
+from fastmcp.server.providers.openapi import OpenAPIProvider
+```
+
+`FastMCPOpenAPI` was **removed in 4.0** — use `FastMCP` with an `OpenAPIProvider` instead:
+
+```python test="skip"
+# Removed in 4.0
+from fastmcp.server.openapi import FastMCPOpenAPI
+server = FastMCPOpenAPI(spec, client)
+
+# New
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi import OpenAPIProvider
+server = FastMCP("my_api", providers=[OpenAPIProvider(spec, client)])
+```
+
+**add_tool_transformation() → add_transform()** (Removed in v4)
+
+```python
+# Removed in v4
+mcp.add_tool_transformation("name", config)
+
+# New
+from fastmcp.server.transforms import ToolTransform
+mcp.add_transform(ToolTransform({"name": config}))
+```
+
+**FastMCP.as_proxy() → create_proxy()** (Removed in v4)
+
+The proxy target is passed positionally in both APIs, so most calls migrate unchanged. If you passed the target by keyword, note that the parameter was renamed from `backend=` to `target=`.
+
+```python
+# Removed in v4
+proxy = FastMCP.as_proxy("http://example.com/mcp")
+proxy = FastMCP.as_proxy(backend="http://example.com/mcp")  # keyword form
+
+# New
+from fastmcp.server import create_proxy
+proxy = create_proxy("http://example.com/mcp")
+proxy = create_proxy(target="http://example.com/mcp")  # as_proxy(backend=X) → create_proxy(target=X)
+```
+
+## v2.14.0
+
+### OpenAPI Parser Promotion
+
+The experimental OpenAPI parser is now standard. The `fastmcp.experimental.server.openapi` and `fastmcp.server.openapi` shims were both **removed in 4.0** — use `FastMCP` with an `OpenAPIProvider` instead:
+
+```python test="skip"
+# Before
+from fastmcp.experimental.server.openapi import FastMCPOpenAPI
+
+# After (removed in 4.0 — use OpenAPIProvider)
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi import OpenAPIProvider
+server = FastMCP("my_api", providers=[OpenAPIProvider(spec, client)])
+```
+
+### Removed Deprecated Features
+
+- `BearerAuthProvider` → use `JWTVerifier`
+- `Context.get_http_request()` → use `get_http_request()` from dependencies
+- `from fastmcp import Image` → use `from fastmcp.utilities.types import Image`
+- `FastMCP(dependencies=[...])` → use `fastmcp.json` configuration
+- `FastMCPProxy(client=...)` → use `client_factory=lambda: ...`
+- `output_schema=False` → use `output_schema=None`
+
+## v2.13.0
+
+### OAuth Token Key Management
+
+The OAuth proxy now issues its own JWT tokens. For production, provide explicit keys:
+
+```python
+auth = GitHubProvider(
+    client_id=os.environ["GITHUB_CLIENT_ID"],
+    client_secret=os.environ["GITHUB_CLIENT_SECRET"],
+    base_url="https://your-server.com",
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=RedisStore(host="redis.example.com"),
+)
+```
+
+See [OAuth Token Security](/deployment/http#oauth-token-security) for details.
diff --git a/docs/getting-started/upgrading/from-fastmcp-3.mdx b/docs/getting-started/upgrading/from-fastmcp-3.mdx
new file mode 100644
index 0000000..50fe44f
--- /dev/null
+++ b/docs/getting-started/upgrading/from-fastmcp-3.mdx
@@ -0,0 +1,148 @@
+---
+title: Upgrading from FastMCP 3
+sidebarTitle: "From FastMCP 3.x"
+description: What changes when you upgrade to FastMCP 4, which builds on the MCP Python SDK v2
+icon: up
+---
+
+FastMCP 4 builds on the MCP Python SDK v2, and that is the source of every change in this guide. The SDK v2 makes two sweeping changes to the protocol layer: it splits the protocol types out of `mcp.types` into a standalone `mcp_types` package, and it renames every protocol field from camelCase to snake_case (`inputSchema` → `input_schema`, `mimeType` → `mime_type`, `isError` → `is_error`, and so on).
+
+FastMCP 4 absorbs almost all of this for you. Field access is bridged so your existing reads keep working, and the imports you were taught have a stable home in FastMCP itself. The sections below describe what FastMCP handles for you, the small number of changes you must make in your own code, and the deprecation timeline for the compatibility shims.
+
+## Environment requirements
+
+The SDK v2 raises FastMCP's dependency floors, which matters before any of your code runs.
+
+**pydantic >= 2.12 is now the floor.** If your project pins an older pydantic (for example `pydantic==2.11.*`), installing this FastMCP release fails with an unsatisfiable-resolution error from your installer — bump your pin to `>=2.12` first. If you don't pin pydantic at all, installers upgrade it silently as part of the FastMCP upgrade.
+
+**The server extra floors Starlette >= 1.0.** Modern FastAPI (0.11x and later) already runs on Starlette 1.x, so mounting a FastMCP server inside a FastAPI app coexists cleanly — verified with FastAPI 0.138.2. Only very old FastAPI versions pinned below Starlette 1.0 conflict; upgrade FastAPI if your resolver complains about Starlette.
+
+## What FastMCP absorbs
+
+### Legacy camelCase field access keeps working
+
+Objects that FastMCP hands back to you — the results of `client.list_tools()`, `client.call_tool_mcp()`, `client.read_resource()`, and the parameter objects passed to your sampling and elicitation handlers — are SDK v2 objects with snake_case fields. FastMCP installs a compatibility bridge at import time that routes the old camelCase names to their new snake_case fields, so code written against FastMCP 2.x still reads correctly:
+
+```python
+from fastmcp import Client
+
+async with Client("my_mcp_server.py") as client:
+    tools = await client.list_tools()
+    schema = tools[0].inputSchema  # still works, warns once
+```
+
+Each bridged read emits a `FastMCPDeprecationWarning` pointing you at the snake_case name (`tools[0].input_schema` here). The bridge covers the fields users actually read: `inputSchema`/`outputSchema` on tools, `mimeType` on resources and content, `isError`/`structuredContent` on tool results, `nextCursor` on paginated results, `serverInfo`/`protocolVersion` on the initialize result, the sampling parameter fields (`systemPrompt`, `maxTokens`, `stopSequences`, `modelPreferences`, `toolChoice`), and `requestedSchema` on elicitation parameters.
+
+The bridge is controlled by the `mcp_camelcase_compat` setting, which defaults to on. Set it to `False` (or the environment variable `FASTMCP_MCP_CAMELCASE_COMPAT=false`) to turn the shims off, in which case only the snake_case names resolve:
+
+```python
+import fastmcp
+
+fastmcp.settings.mcp_camelcase_compat = False
+```
+
+See [Settings](/more/settings) for the full reference.
+
+### Imports have a stable home
+
+The `mcp.types` module no longer exists. FastMCP re-exports the protocol types you're most likely to use — `TextContent`, `ImageContent`, `Tool`, `ErrorData`, `Icon`, `PromptMessage`, `SamplingMessage`, `ToolAnnotations`, and around two dozen others — from `fastmcp.types`. Update your imports to point there:
+
+```python
+from fastmcp.types import TextContent, Tool, ToolAnnotations
+```
+
+For protocol types FastMCP does not re-export (notification and request wrapper types like `ToolListChangedNotification` or `ServerNotification`), import them from `mcp_types` directly:
+
+```python
+import mcp_types
+
+notification = mcp_types.ToolListChangedNotification()
+```
+
+### `McpError` has an alias
+
+`fastmcp.exceptions.McpError` is an alias of the SDK's `MCPError`. Catching errors is unchanged — `except McpError` still catches SDK-raised errors, and reading `err.error.code` still works:
+
+```python
+from fastmcp.exceptions import McpError
+
+try:
+    ...
+except McpError as err:
+    print(err.error.code)
+```
+
+### Behavior preserved across the SDK boundary
+
+A few client behaviors that touch the SDK are preserved so you don't have to change anything:
+
+- `Client(timeout=...)` accepts both a `timedelta` and a plain float number of seconds, as before.
+- `client.ping()` returns a `bool`.
+- `client.transport.get_session_id()` returns `None` on protocol eras that have no session, rather than raising. (The SDK v2 removed session-id access from its streamable HTTP transport; FastMCP reconstructs it on the transport object.)
+
+## What you must change
+
+Three things are on you.
+
+**Your own `mcp.types` imports.** FastMCP can re-export types, but it can't rewrite imports in your code. Any `from mcp.types import X` or `import mcp.types` in your server or client fails at import time with:
+
+```
+ModuleNotFoundError: No module named 'mcp.types'
+```
+
+The raw message gives no hint toward the fix, so if you see it after upgrading, this is why. Switch to `from fastmcp.types import X` for the common types, or `import mcp_types` for the rest.
+
+**`McpError` construction.** The v1 pattern of wrapping an `ErrorData` and passing it positionally fails under SDK v2 with:
+
+```
+TypeError: MCPError.__init__() missing 1 required positional argument: 'message'
+```
+
+Note the message prints the class as `MCPError` (uppercase) even though your code wrote `McpError` — the old name is an alias for the SDK's renamed class. Construct the error with keyword arguments instead:
+
+```python
+from fastmcp.exceptions import McpError
+
+# Before (raises TypeError under SDK v2):
+#   raise McpError(ErrorData(code=-32000, message="Client not supported"))
+
+# After:
+raise McpError(code=-32000, message="Client not supported")
+```
+
+Catching and `err.error.code` are unchanged — only construction moved.
+
+**Raw session access sees v2 objects.** If you reach past FastMCP's client and server surfaces into `client.session`, `ctx.session`, or the internals of `ctx.request_context`, you're now holding raw SDK v2 objects with snake_case fields and the v2 method signatures. FastMCP does not wrap these; code that depends on their v1 shape needs updating.
+
+## Deprecation timeline
+
+The camelCase bridge is a migration aid, not a permanent fixture. It works today and warns on every bridged read so you can find and update the affected call sites. Plan to migrate your reads to snake_case: the shims will be removed in a future release, after which only the snake_case names resolve — the same state you get today by setting `mcp_camelcase_compat = False`. Turning the setting off is a good way to surface every remaining camelCase read in your code as a hard `AttributeError` before the shims go away.
+
+## SDK deprecation warnings you may see
+
+Ordinary use of `ctx.info` (client logging) and `ctx.sample` now emits an SDK-level `MCPDeprecationWarning`:
+
+```
+The logging/sampling capability is deprecated as of 2026-07-28 (SEP-2577)
+```
+
+These warnings come from the MCP SDK, not from FastMCP. For logging they are benign: `ctx.info` keeps working on session-based connections exactly as the protocol table below describes, and the SDK is only signaling the protocol's direction. For sampling, FastMCP additionally emits its own `FastMCPDeprecationWarning`: `ctx.sample` and `ctx.sample_step` are deprecated and slated for removal, so treat that warning as a prompt to migrate to server-side LLM calls rather than as informational.
+
+## Protocol version support
+
+FastMCP servers built on the SDK v2 serve multiple protocol eras from the same server. The SDK negotiates the era each client speaks: the sessionless `2026-07-28` era (which discovers capabilities through `server/discover`) and earlier session-based handshake versions are all handled simultaneously. This formally supersedes FastMCP's earlier "latest protocol only" stance — a single server now works with clients across the protocol transition.
+
+Not every Context feature is available on every era yet. The push-style interactions that require the server to call back into the client — elicitation, sampling, and listing roots — depend on the session-based request/response flow of the earlier eras. On a `2026-07-28` connection these raise a clear, era-aware error rather than reaching the client. Logging notifications and the request/response features flow on every era.
+
+Sampling is the exception that does not come back. `ctx.sample` and `ctx.sample_step` are **deprecated** and will be removed in a future FastMCP release: server-initiated sampling was removed from the wire by SEP-2577, and unlike elicitation it has no multi-round-trip replacement (the agentic loop would exhaust the round-trip budget). The migration is to call an LLM directly from your server rather than borrowing the client's model. See [Sampling](/servers/sampling) for details.
+
+| Context feature | Earlier eras (session-based) | `2026-07-28` (sessionless) |
+| --- | --- | --- |
+| `ctx.info` / logging notifications | Supported | Supported |
+| Tools, resources, prompts, completions | Supported | Supported |
+| `ctx.elicit` | Supported | Not yet — MRTR rewrite pending |
+| `ctx.sample` / `ctx.sample_step` | Supported (deprecated) | Removed — call an LLM server-side |
+| `ctx.list_roots` | Supported | Not yet — MRTR rewrite pending |
+| Tasks (via the FastMCP client) | Supported | Not yet |
+
+If your tools rely on `ctx.elicit` or `ctx.list_roots`, they continue to work against clients on the earlier eras, and the sessionless replacements will expand this table as they land. Sampling is deprecated on every era and will not return on modern connections — migrate those tools to server-side LLM calls.
diff --git a/docs/getting-started/upgrading/from-low-level-sdk.mdx b/docs/getting-started/upgrading/from-low-level-sdk.mdx
new file mode 100644
index 0000000..ab49f15
--- /dev/null
+++ b/docs/getting-started/upgrading/from-low-level-sdk.mdx
@@ -0,0 +1,594 @@
+---
+title: Upgrading from the MCP Low-Level SDK
+sidebarTitle: "From MCP Low-Level SDK"
+description: Upgrade your MCP server from the low-level Python SDK's Server class to FastMCP
+icon: up
+---
+
+If you've been building MCP servers directly on the `mcp` package's `Server` class — writing `list_tools()` and `call_tool()` handlers, hand-crafting JSON Schema dicts, and wiring up transport boilerplate — this guide is for you. FastMCP replaces all of that machinery with a declarative, Pythonic API where your functions *are* the protocol surface.
+
+The core idea: instead of telling the SDK what your tools look like and then separately implementing them, you write ordinary Python functions and let FastMCP derive the protocol layer from your code. Type hints become JSON Schema. Docstrings become descriptions. Return values are serialized automatically. The plumbing you wrote to satisfy the protocol just disappears.
+
+## Why now is the moment to switch
+
+MCP SDK v2 landed sweeping breaking changes on the low-level `Server`: the protocol types moved out of `mcp.types` into a separate `mcp_types` package, every field was renamed from camelCase to snake_case, the `Server` class was rebuilt, `McpError` was renamed, and sessions were removed on the new sessionless protocol era. If you build directly on the low-level SDK, all of that lands on you — you have to rewrite your imports, your handler signatures, and your error construction to match the new surface.
+
+Adopting FastMCP is the easier path. FastMCP 4 runs on SDK v2 and hides that entire surface behind a high-level API that did not change. You write `@mcp.tool` and never touch the renamed internals — FastMCP derives the protocol layer from your function signatures, so the SDK v2 rename simply isn't something your code has to know about. Migrating low-level-SDK-v1 code to FastMCP is less work than migrating it to raw SDK v2, and you come out the other side with the whole framework: composition, middleware, proxies, authentication, and testing. The SDK v2 break is the natural moment to make the jump.
+
+<Note>
+Already using FastMCP 1.0 via `from mcp.server.fastmcp import FastMCP`? Your upgrade is simpler — see the [FastMCP 1.0 upgrade guide](/getting-started/upgrading/from-mcp-sdk) instead.
+</Note>
+
+<Prompt description="Copy this prompt into any LLM along with your server code to get automated upgrade guidance.">
+You are upgrading an MCP server from the `mcp` package's low-level Server class (v1) to FastMCP 4. The server currently uses `mcp.server.Server` (or `mcp.server.lowlevel.server.Server`) with manual handler registration. Analyze the provided code and rewrite it using FastMCP's high-level API. The full guide is at https://gofastmcp.com/getting-started/upgrading/from-low-level-sdk and the complete FastMCP documentation is at https://gofastmcp.com — fetch these for complete context.
+
+UPGRADE RULES:
+
+1. IMPORTS: Replace all `mcp.*` imports with FastMCP equivalents.
+   - `from mcp.server import Server` or `from mcp.server.lowlevel.server import Server` → `from fastmcp import FastMCP`
+   - `import mcp.types as types` → remove (not needed for most code)
+   - `from mcp.server.stdio import stdio_server` → remove (handled by mcp.run())
+   - `from mcp.server.sse import SseServerTransport` → remove (handled by mcp.run())
+
+2. SERVER: Replace `Server("name")` with `FastMCP("name")`.
+
+3. TOOLS: Replace the list_tools + call_tool handler pair with individual @mcp.tool decorators.
+   - Delete the `@server.list_tools()` handler entirely
+   - Delete the `@server.call_tool()` handler entirely
+   - For each tool that was listed in list_tools and dispatched in call_tool, create a new function:
+     - Decorate it with `@mcp.tool`
+     - Use the tool name as the function name (or pass name= to the decorator)
+     - Use the docstring for the description (or pass description= to the decorator)
+     - Convert the inputSchema JSON Schema into typed Python parameters (e.g., `{"type": "integer"}` → `int`, `{"type": "string"}` → `str`, `{"type": "array", "items": {"type": "string"}}` → `list[str]`)
+     - Return plain Python values (`str`, `int`, `dict`, etc.) instead of `list[types.TextContent(...)]`
+     - If the tool returned `types.ImageContent` or `types.EmbeddedResource`, use `from fastmcp.utilities.types import Image` or return the appropriate type
+
+4. RESOURCES: Replace the list_resources + list_resource_templates + read_resource handler trio with individual @mcp.resource decorators.
+   - Delete all three handlers
+   - For each static resource, create a function decorated with `@mcp.resource("uri://...")`
+   - For each resource template, use `@mcp.resource("uri://{param}/path")` with `{param}` in the URI and a matching function parameter
+   - Return str for text content, bytes for binary content
+   - Set `mime_type=` in the decorator if needed
+
+5. PROMPTS: Replace the list_prompts + get_prompt handler pair with individual @mcp.prompt decorators.
+   - Delete both handlers
+   - For each prompt, create a function decorated with `@mcp.prompt`
+   - Convert PromptArgument definitions into typed function parameters
+   - Return str for simple single-message prompts (auto-wrapped as user message)
+   - Return `list[Message]` for multi-message prompts: `from fastmcp.prompts import Message`
+   - `Message("text")` defaults to `role="user"`; use `Message("text", role="assistant")` for assistant messages
+
+6. TRANSPORT: Replace all transport boilerplate with mcp.run().
+   - `async with stdio_server() as (r, w): await server.run(r, w, ...)` → `mcp.run()` (`stdio` is the default)
+   - SSE/Starlette setup → `mcp.run(transport="sse", host="...", port=...)`
+   - Streamable HTTP setup → `mcp.run(transport="http", host="...", port=...)`
+   - Delete asyncio.run(main()) boilerplate — use `if __name__ == "__main__": mcp.run()`
+
+7. CONTEXT: Replace `server.request_context` with FastMCP's Context parameter.
+   - Add `from fastmcp import Context` and add a `ctx: Context` parameter to any tool that needs it
+   - `server.request_context.session.send_log_message(...)` → `await ctx.info("message")` or `await ctx.warning("message")`
+   - Progress reporting → `await ctx.report_progress(current, total)`
+
+For each change, show the original code, explain what it did, and provide the FastMCP equivalent.
+</Prompt>
+
+## Install
+
+```bash
+pip install --upgrade fastmcp
+# or
+uv add fastmcp
+```
+
+FastMCP includes the `mcp` package as a transitive dependency, so you don't lose access to anything.
+
+## Server and Transport
+
+The `Server` class requires you to choose a transport, connect streams, build initialization options, and run an event loop. FastMCP collapses all of that into a constructor and a `run()` call.
+
+<CodeGroup>
+
+```python Before
+import asyncio
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+
+server = Server("my-server")
+
+# ... register handlers ...
+
+async def main():
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            server.create_initialization_options(),
+        )
+
+asyncio.run(main())
+```
+
+```python After
+from fastmcp import FastMCP
+
+mcp = FastMCP("my-server")
+
+# ... register tools, resources, prompts ...
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+</CodeGroup>
+
+Need HTTP instead of stdio? With the `Server` class, you'd wire up Starlette routes and `SseServerTransport` or `StreamableHTTPSessionManager`. With FastMCP:
+
+```python
+mcp.run(transport="http", host="0.0.0.0", port=8000)
+```
+
+## Tools
+
+This is where the difference is most dramatic. The `Server` class requires two handlers — one to describe your tools (with hand-written JSON Schema) and another to dispatch calls by name. FastMCP eliminates both by deriving everything from your function signature.
+
+<CodeGroup>
+
+```python Before
+import mcp.types as types
+from mcp.server import Server
+
+server = Server("math")
+
+@server.list_tools()
+async def list_tools() -> list[types.Tool]:
+    return [
+        types.Tool(
+            name="add",
+            description="Add two numbers",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "a": {"type": "number"},
+                    "b": {"type": "number"},
+                },
+                "required": ["a", "b"],
+            },
+        ),
+        types.Tool(
+            name="multiply",
+            description="Multiply two numbers",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "a": {"type": "number"},
+                    "b": {"type": "number"},
+                },
+                "required": ["a", "b"],
+            },
+        ),
+    ]
+
+@server.call_tool()
+async def call_tool(
+    name: str, arguments: dict
+) -> list[types.TextContent]:
+    if name == "add":
+        result = arguments["a"] + arguments["b"]
+        return [types.TextContent(type="text", text=str(result))]
+    elif name == "multiply":
+        result = arguments["a"] * arguments["b"]
+        return [types.TextContent(type="text", text=str(result))]
+    raise ValueError(f"Unknown tool: {name}")
+```
+
+```python After
+from fastmcp import FastMCP
+
+mcp = FastMCP("math")
+
+@mcp.tool
+def add(a: float, b: float) -> float:
+    """Add two numbers"""
+    return a + b
+
+@mcp.tool
+def multiply(a: float, b: float) -> float:
+    """Multiply two numbers"""
+    return a * b
+```
+
+</CodeGroup>
+
+Each `@mcp.tool` function is self-contained: its name becomes the tool name, its docstring becomes the description, its type annotations become the JSON Schema, and its return value is serialized automatically. No routing. No schema dictionaries. No content-type wrappers.
+
+### Type Mapping
+
+When converting your `inputSchema` to Python type hints:
+
+| JSON Schema | Python Type |
+|---|---|
+| `{"type": "string"}` | `str` |
+| `{"type": "number"}` | `float` |
+| `{"type": "integer"}` | `int` |
+| `{"type": "boolean"}` | `bool` |
+| `{"type": "array", "items": {"type": "string"}}` | `list[str]` |
+| `{"type": "object"}` | `dict` |
+| Optional property (not in `required`) | `param: str \| None = None` |
+
+### Return Values
+
+With the `Server` class, tools return `list[types.TextContent | types.ImageContent | ...]`. In FastMCP, return plain Python values — strings, numbers, dicts, lists, dataclasses, Pydantic models — and serialization is handled for you.
+
+For images or other non-text content, FastMCP provides helpers:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.utilities.types import Image
+
+mcp = FastMCP("media")
+
+@mcp.tool
+def create_chart(data: list[float]) -> Image:
+    """Generate a chart from data."""
+    png_bytes = generate_chart(data)  # your logic
+    return Image(data=png_bytes, format="png")
+```
+
+## Resources
+
+The `Server` class uses three handlers for resources: `list_resources()` to enumerate them, `list_resource_templates()` for URI templates, and `read_resource()` to serve content — all with manual routing by URI. FastMCP replaces all three with per-resource decorators.
+
+<CodeGroup>
+
+```python Before
+import json
+import mcp.types as types
+from mcp.server import Server
+from pydantic import AnyUrl
+
+server = Server("data")
+
+@server.list_resources()
+async def list_resources() -> list[types.Resource]:
+    return [
+        types.Resource(
+            uri=AnyUrl("config://app"),
+            name="app_config",
+            description="Application configuration",
+            mimeType="application/json",
+        ),
+        types.Resource(
+            uri=AnyUrl("config://features"),
+            name="feature_flags",
+            description="Active feature flags",
+            mimeType="application/json",
+        ),
+    ]
+
+@server.list_resource_templates()
+async def list_resource_templates() -> list[types.ResourceTemplate]:
+    return [
+        types.ResourceTemplate(
+            uriTemplate="users://{user_id}/profile",
+            name="user_profile",
+            description="User profile by ID",
+        ),
+        types.ResourceTemplate(
+            uriTemplate="projects://{project_id}/status",
+            name="project_status",
+            description="Project status by ID",
+        ),
+    ]
+
+@server.read_resource()
+async def read_resource(uri: AnyUrl) -> str:
+    uri_str = str(uri)
+    if uri_str == "config://app":
+        return json.dumps({"debug": False, "version": "1.0"})
+    if uri_str == "config://features":
+        return json.dumps({"dark_mode": True, "beta": False})
+    if uri_str.startswith("users://"):
+        user_id = uri_str.split("/")[2]
+        return json.dumps({"id": user_id, "name": f"User {user_id}"})
+    if uri_str.startswith("projects://"):
+        project_id = uri_str.split("/")[2]
+        return json.dumps({"id": project_id, "status": "active"})
+    raise ValueError(f"Unknown resource: {uri}")
+```
+
+```python After
+import json
+from fastmcp import FastMCP
+
+mcp = FastMCP("data")
+
+@mcp.resource("config://app", mime_type="application/json")
+def app_config() -> str:
+    """Application configuration"""
+    return json.dumps({"debug": False, "version": "1.0"})
+
+@mcp.resource("config://features", mime_type="application/json")
+def feature_flags() -> str:
+    """Active feature flags"""
+    return json.dumps({"dark_mode": True, "beta": False})
+
+@mcp.resource("users://{user_id}/profile")
+def user_profile(user_id: str) -> str:
+    """User profile by ID"""
+    return json.dumps({"id": user_id, "name": f"User {user_id}"})
+
+@mcp.resource("projects://{project_id}/status")
+def project_status(project_id: str) -> str:
+    """Project status by ID"""
+    return json.dumps({"id": project_id, "status": "active"})
+```
+
+</CodeGroup>
+
+Static resources and URI templates use the same `@mcp.resource` decorator — FastMCP detects `{placeholders}` in the URI and automatically registers a template. The function parameter `user_id` maps directly to the `{user_id}` placeholder.
+
+## Prompts
+
+Same pattern: the `Server` class uses `list_prompts()` and `get_prompt()` with manual routing. FastMCP uses one decorator per prompt.
+
+<CodeGroup>
+
+```python Before
+import mcp.types as types
+from mcp.server import Server
+
+server = Server("prompts")
+
+@server.list_prompts()
+async def list_prompts() -> list[types.Prompt]:
+    return [
+        types.Prompt(
+            name="review_code",
+            description="Review code for issues",
+            arguments=[
+                types.PromptArgument(
+                    name="code",
+                    description="The code to review",
+                    required=True,
+                ),
+                types.PromptArgument(
+                    name="language",
+                    description="Programming language",
+                    required=False,
+                ),
+            ],
+        )
+    ]
+
+@server.get_prompt()
+async def get_prompt(
+    name: str, arguments: dict[str, str] | None
+) -> types.GetPromptResult:
+    if name == "review_code":
+        code = (arguments or {}).get("code", "")
+        language = (arguments or {}).get("language", "")
+        lang_note = f" (written in {language})" if language else ""
+        return types.GetPromptResult(
+            description="Code review prompt",
+            messages=[
+                types.PromptMessage(
+                    role="user",
+                    content=types.TextContent(
+                        type="text",
+                        text=f"Please review this code{lang_note}:\n\n{code}",
+                    ),
+                )
+            ],
+        )
+    raise ValueError(f"Unknown prompt: {name}")
+```
+
+```python After
+from fastmcp import FastMCP
+
+mcp = FastMCP("prompts")
+
+@mcp.prompt
+def review_code(code: str, language: str | None = None) -> str:
+    """Review code for issues"""
+    lang_note = f" (written in {language})" if language else ""
+    return f"Please review this code{lang_note}:\n\n{code}"
+```
+
+</CodeGroup>
+
+Returning a `str` from a prompt function automatically wraps it as a user message. For multi-turn prompts, return a `list[Message]`:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.prompts import Message
+
+mcp = FastMCP("prompts")
+
+@mcp.prompt
+def debug_session(error: str) -> list[Message]:
+    """Start a debugging conversation"""
+    return [
+        Message(f"I'm seeing this error:\n\n{error}"),
+        Message("I'll help you debug that. Can you share the relevant code?", role="assistant"),
+    ]
+```
+
+## Request Context
+
+The `Server` class exposes request context through `server.request_context`, which gives you the raw `ServerSession` for sending notifications. FastMCP replaces this with a typed `Context` object injected into any function that declares it.
+
+<CodeGroup>
+
+```python Before
+import mcp.types as types
+from mcp.server import Server
+
+server = Server("worker")
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict):
+    if name == "process_data":
+        ctx = server.request_context
+        await ctx.session.send_log_message(
+            level="info", data="Starting processing..."
+        )
+        # ... do work ...
+        await ctx.session.send_log_message(
+            level="info", data="Done!"
+        )
+        return [types.TextContent(type="text", text="Processed")]
+```
+
+```python After
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP("worker")
+
+@mcp.tool
+async def process_data(ctx: Context) -> str:
+    """Process data with progress logging"""
+    await ctx.info("Starting processing...")
+    # ... do work ...
+    await ctx.info("Done!")
+    return "Processed"
+```
+
+</CodeGroup>
+
+The `Context` object provides logging (`ctx.debug()`, `ctx.info()`, `ctx.warning()`, `ctx.error()`), progress reporting (`ctx.report_progress()`), resource subscriptions, session state, and more. See [Context](/servers/context) for the full API.
+
+## Complete Example
+
+A full server upgrade, showing how all the pieces fit together:
+
+<CodeGroup>
+
+```python Before expandable
+import asyncio
+import json
+import mcp.types as types
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from pydantic import AnyUrl
+
+server = Server("demo")
+
+@server.list_tools()
+async def list_tools() -> list[types.Tool]:
+    return [
+        types.Tool(
+            name="greet",
+            description="Greet someone by name",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string"},
+                },
+                "required": ["name"],
+            },
+        )
+    ]
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
+    if name == "greet":
+        return [types.TextContent(type="text", text=f"Hello, {arguments['name']}!")]
+    raise ValueError(f"Unknown tool: {name}")
+
+@server.list_resources()
+async def list_resources() -> list[types.Resource]:
+    return [
+        types.Resource(
+            uri=AnyUrl("info://version"),
+            name="version",
+            description="Server version",
+        )
+    ]
+
+@server.read_resource()
+async def read_resource(uri: AnyUrl) -> str:
+    if str(uri) == "info://version":
+        return json.dumps({"version": "1.0.0"})
+    raise ValueError(f"Unknown resource: {uri}")
+
+@server.list_prompts()
+async def list_prompts() -> list[types.Prompt]:
+    return [
+        types.Prompt(
+            name="summarize",
+            description="Summarize text",
+            arguments=[
+                types.PromptArgument(name="text", required=True)
+            ],
+        )
+    ]
+
+@server.get_prompt()
+async def get_prompt(
+    name: str, arguments: dict[str, str] | None
+) -> types.GetPromptResult:
+    if name == "summarize":
+        return types.GetPromptResult(
+            description="Summarize text",
+            messages=[
+                types.PromptMessage(
+                    role="user",
+                    content=types.TextContent(
+                        type="text",
+                        text=f"Summarize:\n\n{(arguments or {}).get('text', '')}",
+                    ),
+                )
+            ],
+        )
+    raise ValueError(f"Unknown prompt: {name}")
+
+async def main():
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream, write_stream,
+            server.create_initialization_options(),
+        )
+
+asyncio.run(main())
+```
+
+```python After
+import json
+from fastmcp import FastMCP
+
+mcp = FastMCP("demo")
+
+@mcp.tool
+def greet(name: str) -> str:
+    """Greet someone by name"""
+    return f"Hello, {name}!"
+
+@mcp.resource("info://version")
+def version() -> str:
+    """Server version"""
+    return json.dumps({"version": "1.0.0"})
+
+@mcp.prompt
+def summarize(text: str) -> str:
+    """Summarize text"""
+    return f"Summarize:\n\n{text}"
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+</CodeGroup>
+
+## What's Next
+
+Once you've upgraded, you have access to everything FastMCP provides beyond the basics:
+
+- **[Server composition](/servers/composition)** — Mount sub-servers to build modular applications
+- **[Middleware](/servers/middleware)** — Add logging, rate limiting, error handling, and caching
+- **[Proxy servers](/servers/providers/proxy)** — Create a proxy to any existing MCP server
+- **[OpenAPI integration](/integrations/openapi)** — Generate an MCP server from an OpenAPI spec
+- **[Authentication](/servers/auth/authentication)** — Built-in OAuth and token verification
+- **[Testing](/servers/testing)** — Test your server directly in Python without running a subprocess
+
+Explore the full documentation at [gofastmcp.com](https://gofastmcp.com).
diff --git a/docs/getting-started/upgrading/from-mcp-sdk.mdx b/docs/getting-started/upgrading/from-mcp-sdk.mdx
new file mode 100644
index 0000000..919df36
--- /dev/null
+++ b/docs/getting-started/upgrading/from-mcp-sdk.mdx
@@ -0,0 +1,166 @@
+---
+title: Upgrading from the MCP SDK
+sidebarTitle: "From MCP SDK"
+description: Upgrade from FastMCP in the MCP Python SDK to the standalone FastMCP framework
+icon: up
+---
+
+If your server starts with `from mcp.server.fastmcp import FastMCP`, you're using FastMCP 1.0 — the version bundled with v1 of the `mcp` package. Upgrading to the standalone FastMCP framework is easy. **For most servers, it's a single import change.**
+
+```python
+# Before
+from mcp.server.fastmcp import FastMCP
+
+# After
+from fastmcp import FastMCP
+```
+
+That's it. Your `@mcp.tool`, `@mcp.resource`, and `@mcp.prompt` decorators, your `mcp.run()` call, and the rest of your server code all work as-is.
+
+<Tip>
+**Why upgrade?** FastMCP 1.0 pioneered the Pythonic MCP server experience, and we're proud it was bundled into the `mcp` package. The standalone FastMCP project has since grown into a full framework for taking MCP servers from prototype to production — with composition, middleware, proxy servers, authentication, and much more. Upgrading gives you access to all of that, plus ongoing updates and fixes.
+</Tip>
+
+## Install
+
+```bash
+pip install --upgrade fastmcp
+# or
+uv add fastmcp
+```
+
+FastMCP includes the `mcp` package as a dependency, so you don't lose access to anything. Update your import, run your server, and if your tools work, you're done.
+
+<Prompt description="Copy this prompt into any LLM along with your server code to get automated upgrade guidance.">
+You are upgrading an MCP server from FastMCP 1.0 (bundled in the `mcp` package v1) to standalone FastMCP 4. Analyze the provided code and identify every change needed. The full upgrade guide is at https://gofastmcp.com/getting-started/upgrading/from-mcp-sdk and the complete FastMCP documentation is at https://gofastmcp.com — fetch these for complete context.
+
+STEP 1 — IMPORT (required for all servers):
+Change "from mcp.server.fastmcp import FastMCP" to "from fastmcp import FastMCP".
+
+STEP 2 — CONSTRUCTOR KWARGS (only if FastMCP() receives transport settings):
+FastMCP() no longer accepts: host, port, log_level, debug, sse_path, streamable_http_path, json_response, stateless_http.
+Fix: pass these to run() instead.
+Before: `mcp = FastMCP("server", host="0.0.0.0", port=8080); mcp.run()`
+After:  `mcp = FastMCP("server"); mcp.run(transport="http", host="0.0.0.0", port=8080)`
+
+STEP 3 — PROMPTS (only if using PromptMessage directly or returning dicts):
+mcp.types.PromptMessage is replaced by fastmcp.prompts.Message.
+Before: `PromptMessage(role="user", content=TextContent(type="text", text="Hello"))`
+After:  `Message("Hello")`  — role defaults to "user", accepts plain strings.
+Also: if prompts return raw dicts like `{"role": "user", "content": "..."}`, these must become Message objects or plain strings.
+The MCP SDK's FastMCP 1.0 silently coerced dicts; standalone FastMCP requires typed returns.
+
+STEP 4 — OTHER MCP IMPORTS (only if importing from mcp.* directly):
+FastMCP now builds on MCP SDK v2, which removed the `mcp.types` module — protocol types live in the standalone `mcp_types` package. FastMCP re-exports the common ones from `fastmcp.types`. Update any `from mcp.types import X` to `from fastmcp.types import X` (or `import mcp_types`). Prefer FastMCP's own APIs where equivalents exist:
+- fastmcp.types.TextContent for tool returns → just return plain Python values (str, int, dict, etc.)
+- fastmcp.types.ImageContent → fastmcp.utilities.types.Image
+- from mcp.server.stdio import stdio_server → not needed, mcp.run() handles transport
+
+STEP 5 — DECORATORS (only if treating decorated functions as objects):
+@mcp.tool, @mcp.resource, @mcp.prompt now return the original function, not a component object. Code that accesses .name or .description on the decorated result needs updating. Set FASTMCP_DECORATOR_MODE=object temporarily to restore v1 behavior (this compat setting is itself deprecated).
+
+For each issue found, show the original line, explain what changed, and provide the corrected code.
+</Prompt>
+
+## What Might Need Updating
+
+Most servers need nothing beyond the import change. Skim the sections below to see if any apply.
+
+### Constructor Settings
+
+If you passed transport settings like `host` or `port` directly to `FastMCP()`, those now belong on `run()`. This keeps your server definition independent of how it's deployed:
+
+```python
+# Before
+mcp = FastMCP("my-server", host="0.0.0.0", port=8080)
+mcp.run()
+
+# After
+mcp = FastMCP("my-server")
+mcp.run(transport="http", host="0.0.0.0", port=8080)
+```
+
+If you pass the old kwargs, you'll get a clear `TypeError` with a migration hint.
+
+### Prompts
+
+If your prompt functions return `mcp.types.PromptMessage` objects or raw dicts with `role`/`content` keys, you'll need to upgrade to FastMCP's `Message` class. Or just return a plain string — it's automatically wrapped as a user message. The MCP SDK's bundled FastMCP 1.0 silently coerced dicts into messages; standalone FastMCP requires typed `Message` objects or strings.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("prompts")
+
+@mcp.prompt
+def review(code: str) -> str:
+    """Review code for issues"""
+    return f"Please review this code:\n\n{code}"
+```
+
+For multi-turn prompts:
+
+```python
+from fastmcp.prompts import Message
+
+@mcp.prompt
+def debug(error: str) -> list[Message]:
+    """Start a debugging session"""
+    return [
+        Message(f"I'm seeing this error:\n\n{error}"),
+        Message("I'll help debug that. Can you share the relevant code?", role="assistant"),
+    ]
+```
+
+### Other `mcp.*` Imports
+
+FastMCP now builds on MCP SDK v2. The `mcp.types` module no longer exists — protocol types moved to a standalone `mcp_types` package, and the field names were renamed from camelCase to snake_case (`inputSchema` → `input_schema`, `mimeType` → `mime_type`, and so on). FastMCP re-exports the types you're most likely to use from `fastmcp.types`, so update `from mcp.types import X` to `from fastmcp.types import X`. For the full picture, see [Upgrading from FastMCP 3](/getting-started/upgrading/from-fastmcp-3).
+
+Where FastMCP provides its own API for the same thing, it's worth switching over:
+
+| mcp Package | FastMCP Equivalent |
+|---|---|
+| `mcp.types.TextContent(type="text", text=str(x))` | Just return `x` from your tool |
+| `mcp.types.ImageContent(...)` | `from fastmcp.utilities.types import Image` |
+| `mcp.types.PromptMessage(...)` | `from fastmcp.prompts import Message` |
+| `from mcp.server.stdio import stdio_server` | Not needed — `mcp.run()` handles transport |
+
+For protocol types without a FastMCP equivalent, import them from `fastmcp.types` when re-exported there, otherwise from `mcp_types` directly.
+
+### Decorated Functions
+
+In FastMCP 1.0, `@mcp.tool` returned a `FunctionTool` object. Now decorators return your original function unchanged — so decorated functions stay callable for testing, reuse, and composition:
+
+```python
+@mcp.tool
+def greet(name: str) -> str:
+    """Greet someone"""
+    return f"Hello, {name}!"
+
+# This works now — the function is still a regular function
+assert greet("World") == "Hello, World!"
+```
+
+If you have code that accesses `.name`, `.description`, or other attributes on the decorated result, that will need updating. This is uncommon — most servers don't interact with the tool object directly. If you need the old behavior temporarily, set `FASTMCP_DECORATOR_MODE=object` to restore it (this compatibility setting is itself deprecated and will be removed in a future release).
+
+## Verify the Upgrade
+
+```bash
+# Install
+pip install --upgrade fastmcp
+
+# Check version
+fastmcp version
+
+# Run your server
+python my_server.py
+```
+
+You can also inspect your server's registered components with the FastMCP CLI:
+
+```bash
+fastmcp inspect my_server.py
+```
+
+## Looking Ahead
+
+The MCP ecosystem is evolving fast. Part of FastMCP's job is to absorb that complexity on your behalf — as the protocol and its tooling grow, we do the work so your server code doesn't have to change.
diff --git a/docs/getting-started/welcome.mdx b/docs/getting-started/welcome.mdx
new file mode 100644
index 0000000..d42dc39
--- /dev/null
+++ b/docs/getting-started/welcome.mdx
@@ -0,0 +1,134 @@
+---
+title: "Welcome to FastMCP"
+sidebarTitle: "Welcome!"
+description: The fast, Pythonic way to build MCP servers, clients, and applications.
+icon: hand-wave
+mode: center
+---
+{/* <img
+  src="/assets/brand/f-watercolor-waves-4.png"
+
+  alt="'F' logo on a watercolor background"
+  noZoom
+  className="rounded-2xl block dark:hidden"
+  /> 
+  <img
+  src="/assets/brand/f-watercolor-waves-4-dark.png"
+  alt="'F' logo on a watercolor background"
+  noZoom
+  className="rounded-2xl hidden dark:block"
+  />
+
+  
+  */}
+<video
+  autoPlay
+  muted
+  loop
+  playsInline
+  className="rounded-2xl block dark:hidden"
+  src="/assets/brand/f-watercolor-waves-4-animated.mp4"
+></video>
+<video
+  autoPlay
+  muted
+  loop
+  playsInline
+  className="rounded-2xl hidden dark:block"
+  src="/assets/brand/f-watercolor-waves-4-dark-animated.mp4"
+></video>
+
+
+**FastMCP is the standard framework for building MCP applications.** The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) connects LLMs to tools and data. FastMCP gives you everything you need to go from prototype to production — build servers that expose capabilities, connect clients to any MCP service, and give your tools interactive UIs:
+
+```python {1}
+from fastmcp import FastMCP
+
+mcp = FastMCP("Demo 🚀")
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+
+## Move Fast and Make Things
+
+The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) lets you give agents access to your tools and data. But building an effective MCP application is harder than it looks.
+
+FastMCP handles all of it. Declare a tool with a Python function, and the schema, validation, and documentation are generated automatically. Connect to a server with a URL, and transport negotiation, authentication, and protocol lifecycle are managed for you. You focus on your logic, and the MCP part just works: **with FastMCP, best practices are built in.**
+
+**That's why FastMCP is the standard framework for working with MCP.** FastMCP 1.0 was incorporated into the official MCP Python SDK in 2024. Today, the actively maintained standalone project is downloaded a million times a day, and some version of FastMCP powers 70% of MCP servers across all languages.
+
+FastMCP has three pillars:
+
+<CardGroup cols={3}>
+  <Card title="Servers" img="/assets/images/servers-card.png" href="/servers/server">
+    Expose tools, resources, and prompts to LLMs.
+  </Card>
+  <Card title="Apps" img="/assets/images/apps-card.png" href="/apps/overview">
+    Give your tools interactive UIs rendered directly in the conversation.
+  </Card>
+  <Card title="Clients" img="/assets/images/clients-card.png" href="/clients/client">
+    Connect to any MCP server — local or remote, programmatic or CLI.
+  </Card>
+</CardGroup>
+
+**[Servers](/servers/server)** wrap your Python functions into MCP-compliant tools, resources, and prompts. **[Clients](/clients/client)** connect to any server with full protocol support. And **[Apps](/apps/overview)** give your tools interactive UIs rendered directly in the conversation.
+
+Ready to build? Start with the [installation guide](/getting-started/installation) or jump straight to the [quickstart](/getting-started/quickstart).
+
+FastMCP is made with 💙 by [Prefect](https://www.prefect.io/).
+
+## Run FastMCP in production with Horizon
+
+FastMCP is the standard way to build MCP servers. **[Prefect Horizon](https://www.prefect.io/horizon?utm_source=gofastmcp&utm_medium=docs&utm_campaign=docs_welcome&utm_content=welcome_body)** is the enterprise MCP gateway for running them safely.
+
+Built by the FastMCP team, Horizon packages the best practices we've learned shipping the world's most popular MCP framework.
+
+Deploy FastMCP servers from GitHub with branch previews and instant rollback. Create a private registry of every MCP your company uses. Secure access with SSO and tool-level RBAC. Get audit logs, observability, and governance across your MCP stack. Remix approved tools into purpose-built endpoints for teams and agents.
+
+Start with FastMCP. [Scale with Horizon →](https://www.prefect.io/horizon?utm_source=gofastmcp&utm_medium=docs&utm_campaign=docs_welcome&utm_content=welcome_cta)
+
+<Tip>
+**This documentation reflects FastMCP's `main` branch**, meaning it always reflects the latest development version. Features are generally marked with version badges (e.g. `New in version: 3.0.0`) to indicate when they were introduced. Note that this may include features that are not yet released.
+</Tip>
+
+## LLM-Friendly Docs
+
+The FastMCP documentation is available in multiple LLM-friendly formats:
+
+### MCP Server
+
+The FastMCP docs are accessible via MCP! The server URL is `https://gofastmcp.com/mcp`.
+
+In fact, you can use FastMCP to search the FastMCP docs:
+
+```python
+import asyncio
+from fastmcp import Client
+
+async def main():
+    async with Client("https://gofastmcp.com/mcp") as client:
+        result = await client.call_tool(
+            name="search_fast_mcp",
+            arguments={"query": "deploy a FastMCP server"}
+        )
+    print(result)
+
+asyncio.run(main())
+```
+
+### Text Formats
+
+The docs are also available in [llms.txt format](https://llmstxt.org/):
+- [llms.txt](https://gofastmcp.com/llms.txt) - A sitemap listing all documentation pages
+- [llms-full.txt](https://gofastmcp.com/llms-full.txt) - The entire documentation in one file (may exceed context windows)
+
+Any page can be accessed as markdown by appending `.md` to the URL. For example, this page becomes `https://gofastmcp.com/getting-started/welcome.md`.
+
+You can also copy any page as markdown by pressing "Cmd+C" (or "Ctrl+C" on Windows) on your keyboard.
diff --git a/docs/integrations/anthropic.mdx b/docs/integrations/anthropic.mdx
new file mode 100644
index 0000000..08b9b2c
--- /dev/null
+++ b/docs/integrations/anthropic.mdx
@@ -0,0 +1,228 @@
+---
+title: Anthropic API 🤝 FastMCP
+sidebarTitle: Anthropic API
+description: Connect FastMCP servers to the Anthropic API
+icon: message-code
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+
+Anthropic's [Messages API](https://docs.anthropic.com/en/api/messages) supports MCP servers as remote tool sources. This tutorial will show you how to create a FastMCP server and deploy it to a public URL, then how to call it from the Messages API.
+
+<Tip>
+Currently, the MCP connector only accesses **tools** from MCP servers—it queries the `list_tools` endpoint and exposes those functions to Claude. Other MCP features like resources and prompts are not currently supported. You can read more about the MCP connector in the [Anthropic documentation](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector).
+</Tip>
+
+## Create a Server
+
+First, create a FastMCP server with the tools you want to expose. For this example, we'll create a server with a single tool that rolls dice.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+
+## Deploy the Server
+
+Your server must be deployed to a public URL in order for Anthropic to access it. The MCP connector supports both SSE and Streamable HTTP transports.
+
+For development, you can use tools like `ngrok` to temporarily expose a locally-running server to the internet. We'll do that for this example (you may need to install `ngrok` and create a free account), but you can use any other method to deploy your server.
+
+Assuming you saved the above code as `server.py`, you can run the following two commands in two separate terminals to deploy your server and expose it to the internet:
+
+<CodeGroup>
+```bash FastMCP server
+python server.py
+```
+
+```bash ngrok
+ngrok http 8000
+```
+</CodeGroup>
+
+<Warning>
+This exposes your unauthenticated server to the internet. Only run this command in a safe environment if you understand the risks.
+</Warning>
+
+## Call the Server
+
+To use the Messages API with MCP servers, you'll need to install the Anthropic Python SDK (not included with FastMCP):
+
+```bash
+pip install anthropic
+```
+
+You'll also need to authenticate with Anthropic. You can do this by setting the `ANTHROPIC_API_KEY` environment variable. Consult the Anthropic SDK documentation for more information.
+
+```bash
+export ANTHROPIC_API_KEY="your-api-key"
+```
+
+Here is an example of how to call your server from Python. Note that you'll need to replace `https://your-server-url.com` with the actual URL of your server. In addition, we use `/mcp/` as the endpoint because we deployed a streamable-HTTP server with the default path; you may need to use a different endpoint if you customized your server's deployment. **At this time you must also include the `extra_headers` parameter with the `anthropic-beta` header.**
+
+```python {5, 13-22}
+import anthropic
+from rich import print
+
+# Your server URL (replace with your actual URL)
+url = 'https://your-server-url.com'
+
+client = anthropic.Anthropic()
+
+response = client.beta.messages.create(
+    model="claude-sonnet-4-20250514",
+    max_tokens=1000,
+    messages=[{"role": "user", "content": "Roll a few dice!"}],
+    mcp_servers=[
+        {
+            "type": "url",
+            "url": f"{url}/mcp/",
+            "name": "dice-server",
+        }
+    ],
+    extra_headers={
+        "anthropic-beta": "mcp-client-2025-04-04"
+    }
+)
+
+print(response.content)
+```
+
+If you run this code, you'll see something like the following output:
+
+```text
+I'll roll some dice for you! Let me use the dice rolling tool.
+
+I rolled 3 dice and got: 4, 2, 6
+
+The results were 4, 2, and 6. Would you like me to roll again or roll a different number of dice?
+```
+
+
+## Authentication
+
+<VersionBadge version="2.6.0" />
+
+The MCP connector supports OAuth authentication through authorization tokens, which means you can secure your server while still allowing Anthropic to access it.
+
+### Server Authentication
+
+The simplest way to add authentication to the server is to use a bearer token scheme. 
+
+For this example, we'll quickly generate our own tokens with FastMCP's `RSAKeyPair` utility, but this may not be appropriate for production use. For more details, see the complete server-side [Token Verification](/servers/auth/token-verification) documentation. 
+
+We'll start by creating an RSA key pair to sign and verify tokens.
+
+```python
+from fastmcp.server.auth.providers.jwt import RSAKeyPair
+
+key_pair = RSAKeyPair.generate()
+access_token = key_pair.create_token(audience="dice-server")
+```
+
+<Warning>
+FastMCP's `RSAKeyPair` utility is for development and testing only.
+</Warning> 
+
+Next, we'll create a `JWTVerifier` to authenticate the server. 
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import JWTVerifier
+
+auth = JWTVerifier(
+    public_key=key_pair.public_key,
+    audience="dice-server",
+)
+
+mcp = FastMCP(name="Dice Roller", auth=auth)
+```
+
+Here is a complete example that you can copy/paste. For simplicity and the purposes of this example only, it will print the token to the console. **Do NOT do this in production!**
+
+```python server.py [expandable]
+from fastmcp import FastMCP
+from fastmcp.server.auth import JWTVerifier
+from fastmcp.server.auth.providers.jwt import RSAKeyPair
+import random
+
+key_pair = RSAKeyPair.generate()
+access_token = key_pair.create_token(audience="dice-server")
+
+auth = JWTVerifier(
+    public_key=key_pair.public_key,
+    audience="dice-server",
+)
+
+mcp = FastMCP(name="Dice Roller", auth=auth)
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    print(f"\n---\n\n🔑 Dice Roller access token:\n\n{access_token}\n\n---\n")
+    mcp.run(transport="http", port=8000)
+```
+
+### Client Authentication
+
+If you try to call the authenticated server with the same Anthropic code we wrote earlier, you'll get an error indicating that the server rejected the request because it's not authenticated.
+
+```text
+Error code: 400 - {
+    "type": "error", 
+    "error": {
+        "type": "invalid_request_error", 
+        "message": "MCP server 'dice-server' requires authentication. Please provide an authorization_token.",
+    },
+}
+```
+
+To authenticate the client, you can pass the token using the `authorization_token` parameter in your MCP server configuration:
+
+```python {8, 21}
+import anthropic
+from rich import print
+
+# Your server URL (replace with your actual URL)
+url = 'https://your-server-url.com'
+
+# Your access token (replace with your actual token)
+access_token = 'your-access-token'
+
+client = anthropic.Anthropic()
+
+response = client.beta.messages.create(
+    model="claude-sonnet-4-20250514",
+    max_tokens=1000,
+    messages=[{"role": "user", "content": "Roll a few dice!"}],
+    mcp_servers=[
+        {
+            "type": "url",
+            "url": f"{url}/mcp/",
+            "name": "dice-server",
+            "authorization_token": access_token
+        }
+    ],
+    extra_headers={
+        "anthropic-beta": "mcp-client-2025-04-04"
+    }
+)
+
+print(response.content)
+```
+
+You should now see the dice roll results in the output.
diff --git a/docs/integrations/auth0.mdx b/docs/integrations/auth0.mdx
new file mode 100644
index 0000000..65f9d38
--- /dev/null
+++ b/docs/integrations/auth0.mdx
@@ -0,0 +1,195 @@
+---
+title: Auth0 OAuth 🤝 FastMCP
+sidebarTitle: Auth0
+description: Secure your FastMCP server with Auth0 OAuth
+icon: shield-check
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.12.4" />
+
+This guide shows you how to secure your FastMCP server using **Auth0 OAuth**. While Auth0 does have support for Dynamic Client Registration, it is not enabled by default so this integration uses the [**OIDC Proxy**](/servers/auth/oidc-proxy) pattern to bridge Auth0's dynamic OIDC configuration with MCP's authentication requirements.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+1. An **[Auth0 Account](https://auth0.com/)** with access to create Applications
+2. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`)
+
+### Step 1: Create an Auth0 Application
+
+Create an Application in your Auth0 settings to get the credentials needed for authentication:
+
+<Steps>
+<Step title="Navigate to Applications">
+    Go to **Applications → Applications** in your Auth0 account.
+
+    Click **"+ Create Application"** to create a new application.
+</Step>
+
+<Step title="Create Your Application">
+    - **Name**: Choose a name users will recognize (e.g., "My FastMCP Server")
+    - **Choose an application type**: Choose "Single Page Web Applications"
+    - Click **Create** to create the application
+</Step>
+
+<Step title="Configure Your Application">
+    Select the "Settings" tab for your application, then find the "Application URIs" section.
+
+    - **Allowed Callback URLs**: Your server URL + `/auth/callback` (e.g., `http://localhost:8000/auth/callback`)
+    - Click **Save** to save your changes
+
+    <Warning>
+    The callback URL must match exactly. The default path is `/auth/callback`, but you can customize it using the `redirect_path` parameter.
+    </Warning>
+
+    <Tip>
+    If you want to use a custom callback path (e.g., `/auth/auth0/callback`), make sure to set the same path in both your Auth0 Application settings and the `redirect_path` parameter when configuring the Auth0Provider.
+    </Tip>
+</Step>
+
+<Step title="Save Your Credentials">
+    After creating the app, in the "Basic Information" section you'll see:
+
+    - **Client ID**: A public identifier like `tv2ObNgaZAWWhhycr7Bz1LU2mxlnsmsB`
+    - **Client Secret**: A private hidden value that should always be stored securely
+
+    <Tip>
+    Store these credentials securely. Never commit them to version control. Use environment variables or a secrets manager in production.
+    </Tip>
+</Step>
+
+<Step title="Select Your Audience">
+  Go to **Applications → APIs** in your Auth0 account.
+
+    - Find the API that you want to use for your application
+    - **API Audience**: A URL that uniquely identifies the API
+
+    <Tip>
+    Store this along with of the credentials above. Never commit this to version control. Use environment variables or a secrets manager in production.
+    </Tip>
+</Step>
+</Steps>
+
+### Step 2: FastMCP Configuration
+
+Create your FastMCP server using the `Auth0Provider`.
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.auth0 import Auth0Provider
+
+# The Auth0Provider utilizes Auth0 OIDC configuration
+auth_provider = Auth0Provider(
+    config_url="https://.../.well-known/openid-configuration",  # Your Auth0 configuration URL
+    client_id="tv2ObNgaZAWWhhycr7Bz1LU2mxlnsmsB",               # Your Auth0 application Client ID
+    client_secret="vPYqbjemq...",                               # Your Auth0 application Client Secret
+    audience="https://...",                                     # Your Auth0 API audience
+    base_url="http://localhost:8000",                           # Must match your application configuration
+    # redirect_path="/auth/callback"                            # Default value, customize if needed
+)
+
+mcp = FastMCP(name="Auth0 Secured App", auth=auth_provider)
+
+# Add a protected tool to test authentication
+@mcp.tool
+async def get_token_info() -> dict:
+    """Returns information about the Auth0 token."""
+    from fastmcp.server.dependencies import get_access_token
+
+    token = get_access_token()
+
+    return {
+        "issuer": token.claims.get("iss"),
+        "audience": token.claims.get("aud"),
+        "scope": token.claims.get("scope")
+    }
+```
+
+## Testing
+
+### Running the Server
+
+Start your FastMCP server with HTTP transport to enable OAuth flows:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Your server is now running and protected by Auth0 authentication.
+
+### Testing with a Client
+
+Create a test client that authenticates with your Auth0-protected server:
+
+```python test_client.py
+from fastmcp import Client
+import asyncio
+
+async def main():
+    # The client will automatically handle Auth0 OAuth flows
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        # First-time connection will open Auth0 login in your browser
+        print("✓ Authenticated with Auth0!")
+
+        # Test the protected tool
+        result = await client.call_tool("get_token_info")
+        print(f"Auth0 audience: {result['audience']}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+1. Your browser will open to Auth0's authorization page
+2. After you authorize the app, you'll be redirected back
+3. The client receives the token and can make authenticated requests
+
+## Production Configuration
+
+<VersionBadge version="2.13.0" />
+
+For production deployments with persistent token management across server restarts, configure `jwt_signing_key`, and `client_storage`:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.auth0 import Auth0Provider
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+# Production setup with encrypted persistent token storage
+auth_provider = Auth0Provider(
+    config_url="https://.../.well-known/openid-configuration",
+    client_id="tv2ObNgaZAWWhhycr7Bz1LU2mxlnsmsB",
+    client_secret="vPYqbjemq...",
+    audience="https://...",
+    base_url="https://your-production-domain.com",
+
+    # Production token management
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(
+            host=os.environ["REDIS_HOST"],
+            port=int(os.environ["REDIS_PORT"])
+        ),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+
+mcp = FastMCP(name="Production Auth0 App", auth=auth_provider)
+```
+
+<Note>
+Parameters (`jwt_signing_key` and `client_storage`) work together to ensure tokens and client registrations survive server restarts. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without it, tokens are stored in plaintext. Store secrets in environment variables and use a persistent storage backend like Redis for distributed deployments.
+
+For complete details on these parameters, see the [OAuth Proxy documentation](/servers/auth/oauth-proxy#configuration-parameters).
+</Note>
+
+<Info>
+The client caches tokens locally, so you won't need to re-authenticate for subsequent runs unless the token expires or you explicitly clear the cache.
+</Info>
diff --git a/docs/integrations/authkit.mdx b/docs/integrations/authkit.mdx
new file mode 100644
index 0000000..c771752
--- /dev/null
+++ b/docs/integrations/authkit.mdx
@@ -0,0 +1,106 @@
+---
+title: AuthKit 🤝 FastMCP
+sidebarTitle: AuthKit
+description: Secure your FastMCP server with AuthKit by WorkOS
+icon: shield-check
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.11.0" />
+
+This guide shows you how to secure your FastMCP server using WorkOS's **AuthKit**, a complete authentication and user management solution. This integration uses the [**Remote OAuth**](/servers/auth/remote-oauth) pattern with [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html) resource indicators: AuthKit issues tokens whose `aud` claim is bound to your server's resource URL, and FastMCP validates that claim automatically.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+1.  A **[WorkOS Account](https://workos.com/)** and a new **Project**.
+2.  An **[AuthKit](https://www.authkit.com/)** instance configured within your WorkOS project.
+3.  Your FastMCP server's URL (can be localhost for development, e.g., `http://127.0.0.1:8000`).
+
+### Step 1: WorkOS Dashboard
+
+In the WorkOS Dashboard, go to **Connect → Configuration** and configure:
+
+<Steps>
+<Step title="MCP Auth">
+    Enable **Dynamic Client Registration** (DCR) so MCP clients can register themselves. Alternatively, enable **Client ID Metadata Document** (CIMD) if your clients support it.
+</Step>
+
+<Step title="MCP resource indicators">
+    Add your FastMCP server's resource URL (e.g., `http://127.0.0.1:8000/mcp`) as a valid resource indicator.
+
+    This must exactly match what FastMCP advertises in its protected resource metadata. Start your server first and it will log the correct URL on startup — copy that value.
+
+    Without this step, AuthKit falls back to a default environment-scoped audience and audience validation will fail with a 401.
+</Step>
+
+<Step title="Note Your AuthKit Domain">
+    Find your **AuthKit Domain** on the configuration page. It will look like `https://your-project-12345.authkit.app`. You'll need this for your FastMCP server configuration.
+</Step>
+</Steps>
+
+### Step 2: FastMCP Configuration
+
+Create your FastMCP server file and use the `AuthKitProvider` to handle all the OAuth integration automatically:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.workos import AuthKitProvider
+
+# AuthKitProvider automatically discovers WorkOS endpoints, configures JWT
+# validation, and binds the token audience to this server's resource URL.
+auth_provider = AuthKitProvider(
+    authkit_domain="https://your-project-12345.authkit.app",
+    base_url="http://127.0.0.1:8000",  # Use your actual server URL
+)
+
+mcp = FastMCP(name="AuthKit Secured App", auth=auth_provider)
+```
+
+When the server starts, it logs the resource URL it is validating against. Paste that URL into your Dashboard's **MCP resource indicators** list.
+
+## Testing
+
+To test your server, you can use the `fastmcp` CLI to run it locally. Assuming you've saved the above code to `server.py` (after replacing the `authkit_domain` and `base_url` with your actual values!), you can run the following command:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+AuthKit defaults DCR clients to `client_secret_basic` for token exchange, which conflicts with how some MCP clients send credentials. To avoid token exchange errors, register as a public client by setting `token_endpoint_auth_method` to `"none"`:
+
+```python client.py
+from fastmcp import Client
+from fastmcp.client.auth import OAuth
+import asyncio
+
+auth = OAuth(additional_client_metadata={"token_endpoint_auth_method": "none"})
+
+async def main():
+    async with Client("http://127.0.0.1:8000/mcp", auth=auth) as client:
+        assert await client.ping()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Production Configuration
+
+For production deployments, load sensitive configuration from environment variables:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.workos import AuthKitProvider
+
+# Load configuration from environment variables
+auth = AuthKitProvider(
+    authkit_domain=os.environ.get("AUTHKIT_DOMAIN"),
+    base_url=os.environ.get("BASE_URL", "https://your-server.com"),
+)
+
+mcp = FastMCP(name="AuthKit Secured App", auth=auth)
+```
diff --git a/docs/integrations/aws-cognito.mdx b/docs/integrations/aws-cognito.mdx
new file mode 100644
index 0000000..b7df292
--- /dev/null
+++ b/docs/integrations/aws-cognito.mdx
@@ -0,0 +1,278 @@
+---
+title: AWS Cognito OAuth 🤝 FastMCP
+sidebarTitle: AWS Cognito
+description: Secure your FastMCP server with AWS Cognito user pools
+icon: aws
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.12.4" />
+
+This guide shows you how to secure your FastMCP server using **AWS Cognito user pools**. Since AWS Cognito doesn't support Dynamic Client Registration, this integration uses the [**OAuth Proxy**](/servers/auth/oauth-proxy) pattern to bridge AWS Cognito's traditional OAuth with MCP's authentication requirements. It also includes robust JWT token validation, ensuring enterprise-grade authentication.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+1. An **[AWS Account](https://aws.amazon.com/)** with access to create AWS Cognito user pools
+2. Basic familiarity with AWS Cognito concepts (user pools, app clients)
+3. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`)
+
+### Step 1: Create an AWS Cognito User Pool and App Client
+
+Set up AWS Cognito user pool with an app client to get the credentials needed for authentication:
+
+<Steps>
+<Step title="Navigate to AWS Cognito">
+    Go to the **[AWS Cognito Console](https://console.aws.amazon.com/cognito/)** and ensure you're in your desired AWS region.
+
+    Select **"User pools"** from the side navigation (click on the hamburger icon at the top left in case you don't see any), and click **"Create user pool"** to create a new user pool.
+</Step>
+
+<Step title="Define Your Application">
+    AWS Cognito now provides a streamlined setup experience:
+
+    1. **Application type**: Select **"Traditional web application"** (this is the correct choice for FastMCP server-side authentication)
+    2. **Name your application**: Enter a descriptive name (e.g., `FastMCP Server`)
+
+    The traditional web application type automatically configures:
+    - Server-side authentication with client secrets
+    - Authorization code grant flow
+    - Appropriate security settings for confidential clients
+
+    <Info>
+    Choose "Traditional web application" rather than SPA, Mobile app, or Machine-to-machine options. This ensures proper OAuth 2.0 configuration for FastMCP.
+    </Info>
+</Step>
+
+<Step title="Configure Options">
+    AWS will guide you through configuration options:
+
+    - **Sign-in identifiers**: Choose how users will sign in (email, username, or phone)
+    - **Required attributes**: Select any additional user information you need
+    - **Return URL**: Add your callback URL (e.g., `http://localhost:8000/auth/callback` for development)
+
+    <Tip>
+    The simplified interface handles most OAuth security settings automatically based on your application type selection.
+    </Tip>
+</Step>
+
+<Step title="Review and Create">
+    Review your configuration and click **"Create user pool"**.
+
+    After creation, you'll see your user pool details. Save these important values:
+    - **User pool ID** (format: `eu-central-1_XXXXXXXXX`)
+    - **Client ID** (found under → "Applications" → "App clients" in the side navigation → \<Your application name, e.g., `FastMCP Server`\> → "App client information")
+    - **Client Secret** (found under → "Applications" → "App clients" in the side navigation → \<Your application name, e.g., `FastMCP Server`\> → "App client information")
+
+    <Tip>
+    The user pool ID and app client credentials are all you need for FastMCP configuration.
+    </Tip>
+</Step>
+
+<Step title="Configure OAuth Settings">
+    Under "Login pages" in your app client's settings, you can double check and adjust the OAuth configuration:
+
+    - **Allowed callback URLs**: Add your server URL + `/auth/callback` (e.g., `http://localhost:8000/auth/callback`)
+    - **Allowed sign-out URLs**: Optional, for logout functionality
+    - **OAuth 2.0 grant types**: Ensure "Authorization code grant" is selected
+    - **OpenID Connect scopes**: Select scopes your application needs (e.g., `openid`, `email`, `profile`)
+
+    <Tip>
+    For local development, you can use `http://localhost` URLs. For production, you must use HTTPS.
+    </Tip>
+</Step>
+
+<Step title="Configure Resource Server">
+    AWS Cognito requires a resource server entry to support OAuth with protected resources. Without this, token exchange will fail with an `invalid_grant` error.
+
+    Navigate to **"Branding" → "Domain"** in the side navigation, then:
+
+    1. Click **"Create resource server"**
+    2. **Resource server name**: Enter a descriptive name (e.g., `My MCP Server`)
+    3. **Resource server identifier**: Enter your MCP endpoint URL exactly as it will be accessed (e.g., `http://localhost:8000/mcp` for development, or `https://your-server.com/mcp` for production)
+    4. Click **"Create resource server"**
+
+    <Warning>
+    The resource server identifier must exactly match your `base_url + mcp_path`. For the default configuration with `base_url="http://localhost:8000"` and `path="/mcp"`, use `http://localhost:8000/mcp`.
+    </Warning>
+</Step>
+
+<Step title="Save Your Credentials">
+    After setup, you'll have:
+
+    - **User Pool ID**: Format like `eu-central-1_XXXXXXXXX`
+    - **Client ID**: Your application's client identifier
+    - **Client Secret**: Generated client secret (keep secure)
+    - **AWS Region**: Where Your AWS Cognito user pool is located
+
+    <Tip>
+    Store these credentials securely. Never commit them to version control. Use environment variables or AWS Secrets Manager in production.
+    </Tip>
+</Step>
+</Steps>
+
+### Step 2: FastMCP Configuration
+
+Create your FastMCP server using the `AWSCognitoProvider`, which handles AWS Cognito's JWT tokens and user claims automatically:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.aws import AWSCognitoProvider
+from fastmcp.server.dependencies import get_access_token
+
+# The AWSCognitoProvider handles JWT validation and user claims
+auth_provider = AWSCognitoProvider(
+    user_pool_id="eu-central-1_XXXXXXXXX",   # Your AWS Cognito user pool ID
+    aws_region="eu-central-1",               # AWS region (defaults to eu-central-1)
+    client_id="your-app-client-id",          # Your app client ID
+    client_secret="your-app-client-secret",  # Your app client Secret
+    base_url="http://localhost:8000",        # Must match your callback URL
+    # redirect_path="/auth/callback"         # Default value, customize if needed
+)
+
+mcp = FastMCP(name="AWS Cognito Secured App", auth=auth_provider)
+
+# Add a protected tool to test authentication
+@mcp.tool
+async def get_access_token_claims() -> dict:
+    """Get the authenticated user's access token claims."""
+    token = get_access_token()
+    return {
+        "sub": token.claims.get("sub"),
+        "username": token.claims.get("username"),
+        "cognito:groups": token.claims.get("cognito:groups", []),
+    }
+```
+
+## Testing
+
+### Running the Server
+
+Start your FastMCP server with HTTP transport to enable OAuth flows:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Your server is now running and protected by AWS Cognito OAuth authentication.
+
+### Testing with a Client
+
+Create a test client that authenticates with Your AWS Cognito-protected server:
+
+```python test_client.py
+from fastmcp import Client
+import asyncio
+
+async def main():
+    # The client will automatically handle AWS Cognito OAuth
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        # First-time connection will open AWS Cognito login in your browser
+        print("✓ Authenticated with AWS Cognito!")
+
+        # Test the protected tool
+        print("Calling protected tool: get_access_token_claims")
+        result = await client.call_tool("get_access_token_claims")
+        user_data = result.data
+        print("Available access token claims:")
+        print(f"- sub: {user_data.get('sub', 'N/A')}")
+        print(f"- username: {user_data.get('username', 'N/A')}")
+        print(f"- cognito:groups: {user_data.get('cognito:groups', [])}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+1. Your browser will open to AWS Cognito's hosted UI login page
+2. After you sign in (or sign up), you'll be redirected back to your MCP server
+3. The client receives the JWT token and can make authenticated requests
+
+<Info>
+The client caches tokens locally, so you won't need to re-authenticate for subsequent runs unless the token expires or you explicitly clear the cache.
+</Info>
+
+## Production Configuration
+
+<VersionBadge version="2.13.0" />
+
+For production deployments with persistent token management across server restarts, configure `jwt_signing_key`, and `client_storage`:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.aws import AWSCognitoProvider
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+# Production setup with encrypted persistent token storage
+auth_provider = AWSCognitoProvider(
+    user_pool_id="eu-central-1_XXXXXXXXX",
+    aws_region="eu-central-1",
+    client_id="your-app-client-id",
+    client_secret="your-app-client-secret",
+    base_url="https://your-production-domain.com",
+
+    # Production token management
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(
+            host=os.environ["REDIS_HOST"],
+            port=int(os.environ["REDIS_PORT"])
+        ),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+
+mcp = FastMCP(name="Production AWS Cognito App", auth=auth_provider)
+```
+
+<Note>
+Parameters (`jwt_signing_key` and `client_storage`) work together to ensure tokens and client registrations survive server restarts. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without it, tokens are stored in plaintext. Store secrets in environment variables and use a persistent storage backend like Redis for distributed deployments.
+
+For complete details on these parameters, see the [OAuth Proxy documentation](/servers/auth/oauth-proxy#configuration-parameters).
+</Note>
+
+## Features
+
+### JWT Token Validation
+
+The AWS Cognito provider includes robust JWT token validation:
+
+- **Signature Verification**: Validates tokens against AWS Cognito's public keys (JWKS)
+- **Expiration Checking**: Automatically rejects expired tokens
+- **Issuer Validation**: Ensures tokens come from your specific AWS Cognito user pool
+- **Scope Enforcement**: Verifies required OAuth scopes are present
+
+### User Claims and Groups
+
+Access rich user information from AWS Cognito JWT tokens:
+
+```python
+from fastmcp.server.dependencies import get_access_token
+
+@mcp.tool
+async def admin_only_tool() -> str:
+    """A tool only available to admin users."""
+    token = get_access_token()
+    user_groups = token.claims.get("cognito:groups", [])
+
+    if "admin" not in user_groups:
+        raise ValueError("This tool requires admin access")
+
+    return "Admin access granted!"
+```
+
+### Enterprise Integration
+
+Perfect for enterprise environments with:
+
+- **Single Sign-On (SSO)**: Integrate with corporate identity providers
+- **Multi-Factor Authentication (MFA)**: Leverage AWS Cognito's built-in MFA
+- **User Groups**: Role-based access control through AWS Cognito groups
+- **Custom Attributes**: Access custom user attributes defined in your AWS Cognito user pool
+- **Compliance**: Meet enterprise security and compliance requirements
\ No newline at end of file
diff --git a/docs/integrations/azure.mdx b/docs/integrations/azure.mdx
new file mode 100644
index 0000000..cba9234
--- /dev/null
+++ b/docs/integrations/azure.mdx
@@ -0,0 +1,542 @@
+---
+title: Azure (Microsoft Entra ID) OAuth 🤝 FastMCP
+sidebarTitle: Azure (Entra ID)
+description: Secure your FastMCP server with Azure/Microsoft Entra OAuth
+icon: microsoft
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.13.0" />
+
+This guide shows you how to secure your FastMCP server using **Azure OAuth** (Microsoft Entra ID). Since Azure doesn't support Dynamic Client Registration, this integration uses the [**OAuth Proxy**](/servers/auth/oauth-proxy) pattern to bridge Azure's traditional OAuth with MCP's authentication requirements. FastMCP validates Azure JWTs against your application's client_id.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+1. An **[Azure Account](https://portal.azure.com/)** with access to create App registrations
+2. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`)
+3. Your Azure tenant ID (found in Azure Portal under Microsoft Entra ID)
+
+### Step 1: Create an Azure App Registration
+
+Create an App registration in Azure Portal to get the credentials needed for authentication:
+
+<Steps>
+<Step title="Navigate to App registrations">
+    Go to the [Azure Portal](https://portal.azure.com) and navigate to **Microsoft Entra ID → App registrations**.
+    
+    Click **"New registration"** to create a new application.
+</Step>
+
+<Step title="Configure Your Application">
+    Fill in the application details:
+    
+    - **Name**: Choose a name users will recognize (e.g., "My FastMCP Server")
+    - **Supported account types**: Choose based on your needs:
+      - **Single tenant**: Only users in your organization
+      - **Multitenant**: Users in any Microsoft Entra directory
+      - **Multitenant + personal accounts**: Any Microsoft account
+    - **Redirect URI**: Select "Web" and enter your server URL + `/auth/callback` (e.g., `http://localhost:8000/auth/callback`)
+    
+    <Warning>
+    The redirect URI must match exactly. The default path is `/auth/callback`, but you can customize it using the `redirect_path` parameter. For local development, Azure allows `http://localhost` URLs. For production, you must use HTTPS.
+    </Warning>
+    
+    <Tip>
+    If you want to use a custom callback path (e.g., `/auth/azure/callback`), make sure to set the same path in both your Azure App registration and the `redirect_path` parameter when configuring the AzureProvider.
+    </Tip>
+
+    - **Expose an API**: Configure your Application ID URI and define scopes
+      - Go to **Expose an API** in the App registration sidebar.
+      - Click **Set** next to "Application ID URI" and choose one of:
+        - Keep the default `api://{client_id}`
+        - Set a custom value, following the supported formats (see [Identifier URI restrictions](https://learn.microsoft.com/en-us/entra/identity-platform/identifier-uri-restrictions))
+      - Click **Add a scope** and create a scope your app will require, for example:
+        - Scope name: `read` (or `write`, etc.)
+        - Admin consent display name/description: as appropriate for your org
+        - Who can consent: as needed (Admins only or Admins and users)
+
+    - **Configure Access Token Version**: Ensure your app uses access token v2
+      - Go to **Manifest** in the App registration sidebar.
+      - Find the `requestedAccessTokenVersion` property and set it to `2`:
+        ```json
+        "api": {
+            "requestedAccessTokenVersion": 2
+        }
+        ```
+      - Click **Save** at the top of the manifest editor.
+
+    <Warning>
+    Access token v2 is required for FastMCP's Azure integration to work correctly. If this is not set, you may encounter authentication errors.
+    </Warning>
+
+    <Note>
+    In FastMCP's `AzureProvider`, set `identifier_uri` to your Application ID URI (optional; defaults to `api://{client_id}`) and set `required_scopes` to the unprefixed scope names (e.g., `read`, `write`). During authorization, FastMCP automatically prefixes scopes with your `identifier_uri`.
+    </Note>
+
+
+</Step>
+
+
+<Step title="Create Client Secret">
+    After registration, navigate to **Certificates & secrets** in your app's settings.
+    
+    - Click **"New client secret"**
+    - Add a description (e.g., "FastMCP Server")
+    - Choose an expiration period
+    - Click **"Add"**
+    
+    <Warning>
+    Copy the secret value immediately - it won't be shown again! You'll need to create a new secret if you lose it.
+    </Warning>
+</Step>
+
+<Step title="Note Your Credentials">
+    From the **Overview** page of your app registration, note:
+    
+    - **Application (client) ID**: A UUID like `835f09b6-0f0f-40cc-85cb-f32c5829a149`
+    - **Directory (tenant) ID**: A UUID like `08541b6e-646d-43de-a0eb-834e6713d6d5`
+    - **Client Secret**: The value you copied in the previous step
+    
+    <Tip>
+    Store these credentials securely. Never commit them to version control. Use environment variables or a secrets manager in production.
+    </Tip>
+</Step>
+</Steps>
+
+### Step 2: FastMCP Configuration
+
+Create your FastMCP server using the `AzureProvider`, which handles Azure's OAuth flow automatically:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.azure import AzureProvider
+
+# The AzureProvider handles Azure's token format and validation
+auth_provider = AzureProvider(
+    client_id="835f09b6-0f0f-40cc-85cb-f32c5829a149",  # Your Azure App Client ID
+    client_secret="your-client-secret",                 # Your Azure App Client Secret
+    tenant_id="08541b6e-646d-43de-a0eb-834e6713d6d5", # Your Azure Tenant ID (REQUIRED)
+    base_url="http://localhost:8000",                   # Must match your App registration
+    required_scopes=["your-scope"],                 # At least one scope REQUIRED - name of scope from your App
+    # identifier_uri defaults to api://{client_id}
+    # identifier_uri="api://your-api-id",
+    # Optional: request additional upstream scopes in the authorize request
+    # additional_authorize_scopes=["User.Read", "openid", "email"],
+    # redirect_path="/auth/callback"                  # Default value, customize if needed
+    # base_authority="login.microsoftonline.us"      # For Azure Government (default: login.microsoftonline.com)
+)
+
+mcp = FastMCP(name="Azure Secured App", auth=auth_provider)
+
+# Add a protected tool to test authentication
+@mcp.tool
+async def get_user_info() -> dict:
+    """Returns information about the authenticated Azure user."""
+    from fastmcp.server.dependencies import get_access_token
+    
+    token = get_access_token()
+    # The AzureProvider stores user data in token claims
+    return {
+        "azure_id": token.claims.get("sub"),
+        "email": token.claims.get("email"),
+        "name": token.claims.get("name"),
+        "job_title": token.claims.get("job_title"),
+        "office_location": token.claims.get("office_location")
+    }
+```
+
+<Note>
+**Important**: The `tenant_id` parameter is **REQUIRED**. Azure no longer supports using "common" for new applications due to security requirements. You must use one of:
+
+- **Your specific tenant ID**: Found in Azure Portal (e.g., `08541b6e-646d-43de-a0eb-834e6713d6d5`)
+- **"organizations"**: For work and school accounts only
+- **"consumers"**: For personal Microsoft accounts only
+
+Using your specific tenant ID is recommended for better security and control.
+</Note>
+
+<Note>
+**Important**: The `required_scopes` parameter is **REQUIRED** and must include at least one scope. Azure's OAuth API requires the `scope` parameter in all authorization requests - you cannot authenticate without specifying at least one scope. Use the unprefixed scope names from your Azure App registration (e.g., `["read", "write"]`). These scopes must be created under **Expose an API** in your App registration.
+</Note>
+
+### Scope Handling
+
+FastMCP automatically prefixes `required_scopes` with your `identifier_uri` (e.g., `api://your-client-id`) since these are your custom API scopes. Scopes in `additional_authorize_scopes` are sent as-is since they target external resources like Microsoft Graph.
+
+**`required_scopes`** — Your custom API scopes, defined in Azure "Expose an API":
+
+| You write | Sent to Azure | Validated on tokens |
+|-----------|---------------|---------------------|
+| `mcp-read` | `api://xxx/mcp-read` | ✓ |
+| `my.scope` | `api://xxx/my.scope` | ✓ |
+| `openid` | `openid` | ✗ (OIDC scope) |
+| `api://xxx/read` | `api://xxx/read` | ✓ |
+
+**`additional_authorize_scopes`** — External scopes (e.g., Microsoft Graph) for server-side use:
+
+| You write | Sent to Azure | Validated on tokens |
+|-----------|---------------|---------------------|
+| `User.Read` | `User.Read` | ✗ |
+| `Mail.Send` | `Mail.Send` | ✗ |
+
+<Note>
+`offline_access` is automatically included to obtain refresh tokens. FastMCP manages token refreshing automatically.
+</Note>
+
+<Info>
+**Why aren't `additional_authorize_scopes` validated?** Azure issues separate tokens per resource. The access token FastMCP receives is for *your API*—Graph scopes aren't in its `scp` claim. To call Graph APIs, your server uses the upstream Azure token in an on-behalf-of (OBO) flow.
+</Info>
+
+<Note>
+OIDC scopes (`openid`, `profile`, `email`, `offline_access`) are never prefixed and excluded from validation because Azure doesn't include them in access token `scp` claims.
+</Note>
+
+## Testing
+
+### Running the Server
+
+Start your FastMCP server with HTTP transport to enable OAuth flows:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Your server is now running and protected by Azure OAuth authentication.
+
+### Testing with a Client
+
+Create a test client that authenticates with your Azure-protected server:
+
+```python test_client.py
+from fastmcp import Client
+import asyncio
+
+async def main():
+    # The client will automatically handle Azure OAuth
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        # First-time connection will open Azure login in your browser
+        print("✓ Authenticated with Azure!")
+        
+        # Test the protected tool
+        result = await client.call_tool("get_user_info")
+        print(f"Azure user: {result['email']}")
+        print(f"Name: {result['name']}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+1. Your browser will open to Microsoft's authorization page
+2. Sign in with your Microsoft account (work, school, or personal based on your tenant configuration)
+3. Grant the requested permissions
+4. After authorization, you'll be redirected back
+5. The client receives the token and can make authenticated requests
+
+<Info>
+The client caches tokens locally, so you won't need to re-authenticate for subsequent runs unless the token expires or you explicitly clear the cache.
+</Info>
+
+## Production Configuration
+
+<VersionBadge version="2.13.0" />
+
+For production deployments with persistent token management across server restarts, configure `jwt_signing_key` and `client_storage`:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.azure import AzureProvider
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+# Production setup with encrypted persistent token storage
+auth_provider = AzureProvider(
+    client_id="835f09b6-0f0f-40cc-85cb-f32c5829a149",
+    client_secret="your-client-secret",
+    tenant_id="08541b6e-646d-43de-a0eb-834e6713d6d5",
+    base_url="https://your-production-domain.com",
+    required_scopes=["your-scope"],
+
+    # Production token management
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(
+            host=os.environ["REDIS_HOST"],
+            port=int(os.environ["REDIS_PORT"])
+        ),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+
+mcp = FastMCP(name="Production Azure App", auth=auth_provider)
+```
+
+<Note>
+Parameters (`jwt_signing_key` and `client_storage`) work together to ensure tokens and client registrations survive server restarts. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without it, tokens are stored in plaintext. Store secrets in environment variables and use a persistent storage backend like Redis for distributed deployments.
+
+For complete details on these parameters, see the [OAuth Proxy documentation](/servers/auth/oauth-proxy#configuration-parameters).
+</Note>
+
+## Token Verification Only (Managed Identity)
+
+<VersionBadge version="2.15.0" />
+
+For deployments where your server only needs to **validate incoming tokens** — such as Azure Container Apps with Managed Identity — use `AzureJWTVerifier` with `RemoteAuthProvider` instead of the full `AzureProvider`.
+
+This pattern is ideal when:
+- Your infrastructure handles authentication (e.g., Managed Identity)
+- You don't need the OAuth proxy flow (no `client_secret` required)
+- You just need to verify that incoming Azure AD tokens are valid
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth import RemoteAuthProvider
+from fastmcp.server.auth.providers.azure import AzureJWTVerifier
+from pydantic import AnyHttpUrl
+
+tenant_id = "your-tenant-id"
+client_id = "your-client-id"
+
+# AzureJWTVerifier auto-configures JWKS, issuer, and audience
+verifier = AzureJWTVerifier(
+    client_id=client_id,
+    tenant_id=tenant_id,
+    required_scopes=["access_as_user"],  # Scope names from Azure Portal
+)
+
+auth = RemoteAuthProvider(
+    token_verifier=verifier,
+    authorization_servers=[
+        AnyHttpUrl(f"https://login.microsoftonline.com/{tenant_id}/v2.0")
+    ],
+    base_url="https://your-container-app.azurecontainerapps.io",
+)
+
+mcp = FastMCP(name="Azure MI App", auth=auth)
+```
+
+`AzureJWTVerifier` handles Azure's scope format automatically. You write scope names exactly as they appear in Azure Portal under **Expose an API** (e.g., `access_as_user`). The verifier validates tokens using the short-form scopes that Azure puts in the `scp` claim, while advertising the full URI scopes (e.g., `api://your-client-id/access_as_user`) in OAuth metadata so MCP clients know what to request.
+
+<Note>
+For Azure Government, pass `base_authority="login.microsoftonline.us"` to `AzureJWTVerifier`.
+</Note>
+
+## On-Behalf-Of (OBO)
+
+<VersionBadge version="3.0.0" />
+
+The On-Behalf-Of (OBO) flow allows your FastMCP server to call downstream Microsoft APIs—like Microsoft Graph—using the authenticated user's identity. When a user authenticates to your MCP server, you receive a token for your API. OBO exchanges that token for a new token that can call other services, maintaining the user's identity and permissions throughout the chain.
+
+This pattern is useful when your tools need to access user-specific data from Microsoft services: reading emails, accessing calendar events, querying SharePoint, or any other Graph API operation that requires user context.
+
+<Note>
+OBO features require the `azure` extra:
+
+```bash
+pip install 'fastmcp[azure]'
+```
+</Note>
+
+### Azure Portal Setup
+
+OBO requires additional configuration in your Azure App registration beyond basic authentication.
+
+<Steps>
+<Step title="Add API Permissions">
+    In your App registration, navigate to **API permissions** and add the Microsoft Graph permissions your tools will need.
+
+    - Click **Add a permission** → **Microsoft Graph** → **Delegated permissions**
+    - Select the permissions required for your use case (e.g., `Mail.Read`, `Calendars.Read`, `User.Read`)
+    - Repeat for any other APIs you need to call
+
+    <Warning>
+    Only add delegated permissions for OBO. Application permissions bypass user context entirely and are inappropriate for the OBO flow.
+    </Warning>
+</Step>
+
+<Step title="Grant Admin Consent">
+    OBO requires admin consent for the permissions you've added. In the **API permissions** page, click **Grant admin consent for [Your Organization]**.
+
+    Without admin consent, OBO token exchanges will fail with an `AADSTS65001` error indicating the user or administrator hasn't consented to use the application.
+
+    <Tip>
+    For development, you can grant consent for just your own account. For production, an Azure AD administrator must grant tenant-wide consent.
+    </Tip>
+</Step>
+</Steps>
+
+### Configure AzureProvider for OBO
+
+The `additional_authorize_scopes` parameter tells Azure which downstream API permissions to include during the initial authorization. These scopes establish what your server can request through OBO later.
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.azure import AzureProvider
+
+auth_provider = AzureProvider(
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+    tenant_id="your-tenant-id",
+    base_url="http://localhost:8000",
+    required_scopes=["mcp-access"],  # Your API scope
+    # Include Graph scopes for OBO
+    additional_authorize_scopes=[
+        "https://graph.microsoft.com/Mail.Read",
+        "https://graph.microsoft.com/User.Read",
+        "offline_access",  # Enables refresh tokens
+    ],
+)
+
+mcp = FastMCP(name="Graph-Enabled Server", auth=auth_provider)
+```
+
+Scopes listed in `additional_authorize_scopes` are requested during the initial OAuth flow but aren't validated on incoming tokens. They establish permission for your server to later exchange the user's token for downstream API access.
+
+<Info>
+Use fully-qualified scope URIs for downstream APIs (e.g., `https://graph.microsoft.com/Mail.Read`). Short forms like `Mail.Read` work for authorization requests, but fully-qualified URIs are clearer and avoid ambiguity.
+</Info>
+
+### EntraOBOToken Dependency
+
+The `EntraOBOToken` dependency handles the complete OBO flow automatically. Declare it as a parameter default with the scopes you need, and FastMCP exchanges the user's token for a downstream API token before your function runs.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.azure import AzureProvider, EntraOBOToken
+import httpx
+
+auth_provider = AzureProvider(
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+    tenant_id="your-tenant-id",
+    base_url="http://localhost:8000",
+    required_scopes=["mcp-access"],
+    additional_authorize_scopes=[
+        "https://graph.microsoft.com/Mail.Read",
+        "https://graph.microsoft.com/User.Read",
+    ],
+)
+
+mcp = FastMCP(name="Email Reader", auth=auth_provider)
+
+@mcp.tool
+async def get_recent_emails(
+    count: int = 10,
+    graph_token: str = EntraOBOToken(["https://graph.microsoft.com/Mail.Read"]),
+) -> list[dict]:
+    """Get the user's recent emails from Microsoft Graph."""
+    async with httpx.AsyncClient() as client:
+        response = await client.get(
+            f"https://graph.microsoft.com/v1.0/me/messages?$top={count}",
+            headers={"Authorization": f"Bearer {graph_token}"},
+        )
+        response.raise_for_status()
+        data = response.json()
+
+    return [
+        {"subject": msg["subject"], "from": msg["from"]["emailAddress"]["address"]}
+        for msg in data.get("value", [])
+    ]
+```
+
+The `graph_token` parameter receives a ready-to-use access token for Microsoft Graph. FastMCP handles the OBO exchange transparently—your function just uses the token to call the API.
+
+<Warning>
+**Scope alignment is critical.** The scopes passed to `EntraOBOToken` must be a subset of the scopes in `additional_authorize_scopes`. If you request a scope during OBO that wasn't included in the initial authorization, the exchange will fail.
+</Warning>
+
+<Tip>
+For advanced OBO scenarios, use `CurrentAccessToken()` to get the user's token, then construct an `azure.identity.aio.OnBehalfOfCredential` directly with your Azure credentials.
+</Tip>
+
+<Tip>
+For a complete working example of Azure OBO with FastMCP, see [Pamela Fox's blog post on OBO flow for Entra-based MCP servers](https://blog.pamelafox.org/2026/01/using-on-behalf-of-flow-for-entra-based.html).
+</Tip>
+
+## Azure AD B2C
+
+<VersionBadge version="3.3.0" />
+
+Azure AD B2C (Business-to-Consumer) uses different endpoints, scope URIs, and
+token issuers than standard Microsoft Entra ID. The `AzureProvider.from_b2c()`
+factory handles all of these differences automatically.
+
+<Warning>
+Azure AD B2C does **not** support the On-Behalf-Of (OBO) flow. If you need
+OBO for downstream API calls, use `AzureProvider` with standard Entra ID
+instead.
+</Warning>
+
+### Quick Start
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.azure import AzureProvider
+
+auth = AzureProvider.from_b2c(
+    tenant_name="mytenant",
+    policy_name="B2C_1_susi",
+    client_id="00000000-0000-0000-0000-000000000000",
+    client_secret="my-secret",
+    required_scopes=["mcp-access"],
+    base_url="https://myserver.com",
+)
+
+mcp = FastMCP("My App", auth=auth)
+```
+
+`from_b2c()` derives the following values automatically:
+
+| Derived value | Formula |
+|---|---|
+| Authority host | `{tenant_name}.b2clogin.com` |
+| Authorization endpoint | `https://{tenant_name}.b2clogin.com/{tenant_name}.onmicrosoft.com/{policy_name}/oauth2/v2.0/authorize` |
+| Token endpoint | `https://{tenant_name}.b2clogin.com/{tenant_name}.onmicrosoft.com/{policy_name}/oauth2/v2.0/token` |
+| Scope identifier URI | `https://{tenant_name}.onmicrosoft.com/{client_id}` |
+
+### Token Issuer Validation
+
+B2C access tokens carry the **tenant GUID** (not the `.onmicrosoft.com` name)
+in the `iss` claim, and the exact format varies by policy and custom-domain
+configuration. `from_b2c()` therefore **disables issuer validation by
+default**; **audience validation still enforces that tokens target the correct
+application**.
+
+Once you have confirmed a successful end-to-end login, read the actual `iss`
+value from the decoded claims and enable strict validation:
+
+```python
+auth = AzureProvider.from_b2c(
+    tenant_name="mytenant",
+    policy_name="B2C_1_susi",
+    client_id="00000000-0000-0000-0000-000000000000",
+    client_secret="my-secret",
+    required_scopes=["mcp-access"],
+    base_url="https://myserver.com",
+    token_issuer="https://mytenant.b2clogin.com/11111111-2222-3333-4444-555555555555/v2.0/",
+)
+```
+
+### Custom Domains
+
+If your B2C tenant uses a [custom domain](https://learn.microsoft.com/en-us/azure/active-directory-b2c/custom-domain)
+(e.g. `auth.mycompany.com` instead of `mytenant.b2clogin.com`), pass it via
+`custom_domain`:
+
+```python
+auth = AzureProvider.from_b2c(
+    tenant_name="mytenant",
+    policy_name="B2C_1_susi",
+    client_id="00000000-0000-0000-0000-000000000000",
+    client_secret="my-secret",
+    required_scopes=["mcp-access"],
+    base_url="https://myserver.com",
+    custom_domain="auth.mycompany.com",
+)
+```
diff --git a/docs/integrations/chatgpt.mdx b/docs/integrations/chatgpt.mdx
new file mode 100644
index 0000000..e1fb663
--- /dev/null
+++ b/docs/integrations/chatgpt.mdx
@@ -0,0 +1,157 @@
+---
+title: ChatGPT 🤝 FastMCP
+sidebarTitle: ChatGPT
+description: Connect FastMCP servers to ChatGPT in Chat and Deep Research modes
+icon: message-smile
+---
+
+[ChatGPT](https://chatgpt.com/) supports MCP servers through remote HTTP connections in two modes: **Chat mode** for interactive conversations and **Deep Research mode** for comprehensive information retrieval.
+
+<Tip>
+**Developer Mode Required for Chat Mode**: To use MCP servers in regular ChatGPT conversations, you must first enable Developer Mode in your ChatGPT settings. This feature is available for ChatGPT Pro, Team, Enterprise, and Edu users.
+</Tip>
+
+<Note>
+OpenAI's official MCP documentation and examples are built with **FastMCP v2**! Learn more from their [MCP documentation](https://platform.openai.com/docs/mcp) and [Developer Mode guide](https://platform.openai.com/docs/guides/developer-mode).
+</Note>
+
+## Build a Server
+
+First, let's create a simple FastMCP server:
+
+```python server.py
+from fastmcp import FastMCP
+import random
+
+mcp = FastMCP("Demo Server")
+
+@mcp.tool
+def roll_dice(sides: int = 6) -> int:
+    """Roll a dice with the specified number of sides."""
+    return random.randint(1, sides)
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+
+### Deploy Your Server
+
+Your server must be accessible from the internet. For development, use `ngrok`:
+
+<CodeGroup>
+```bash Terminal 1
+python server.py
+```
+
+```bash Terminal 2
+ngrok http 8000
+```
+</CodeGroup>
+
+Note your public URL (e.g., `https://abc123.ngrok.io`) for the next steps.
+
+## Chat Mode
+
+Chat mode lets you use MCP tools directly in ChatGPT conversations. See [OpenAI's Developer Mode guide](https://platform.openai.com/docs/guides/developer-mode) for the latest requirements.
+
+### Add to ChatGPT
+
+#### 1. Enable Developer Mode
+
+1. Open ChatGPT and go to **Settings** → **Connectors**
+2. Under **Advanced**, toggle **Developer Mode** to enabled
+
+#### 2. Create Connector
+
+1. In **Settings** → **Connectors**, click **Create**
+2. Enter:
+   - **Name**: Your server name
+   - **Server URL**: `https://your-server.ngrok.io/mcp/`
+3. Check **I trust this provider**
+4. Add authentication if needed
+5. Click **Create**
+
+<Note>
+**Without Developer Mode**: If you don't have search/fetch tools, ChatGPT will reject the server. With Developer Mode enabled, you don't need search/fetch tools for Chat mode.
+</Note>
+
+#### 3. Use in Chat
+
+1. Start a new chat
+2. Click the **+** button → **More** → **Developer Mode**
+3. **Enable your MCP server connector** (required - the connector must be explicitly added to each chat)
+4. Now you can use your tools:
+
+Example usage:
+- "Roll a 20-sided dice"
+- "Roll dice" (uses default 6 sides)
+
+<Tip>
+The connector must be explicitly enabled in each chat session through Developer Mode. Once added, it remains active for the entire conversation.
+</Tip>
+
+### Skip Confirmations
+
+Use `annotations=ToolAnnotations(readOnlyHint=True)` to skip confirmation prompts for read-only tools:
+
+```python
+from fastmcp.types import ToolAnnotations
+
+@mcp.tool(annotations=ToolAnnotations(readOnlyHint=True))
+def get_status() -> str:
+    """Check system status."""
+    return "All systems operational"
+
+@mcp.tool()  # No annotation - ChatGPT may ask for confirmation
+def delete_item(id: str) -> str:
+    """Delete an item."""
+    return f"Deleted {id}"
+```
+
+## Deep Research Mode
+
+Deep Research mode provides systematic information retrieval with citations. See [OpenAI's MCP documentation](https://platform.openai.com/docs/mcp) for the latest Deep Research specifications.
+
+<Warning>
+**Search and Fetch Required**: Without Developer Mode, ChatGPT will reject any server that doesn't have both `search` and `fetch` tools. Even in Developer Mode, Deep Research only uses these two tools.
+</Warning>
+
+### Tool Implementation
+
+Deep Research tools must follow this pattern:
+
+```python
+@mcp.tool()
+def search(query: str) -> dict:
+    """
+    Search for records matching the query.
+    Must return {"ids": [list of string IDs]}
+    """
+    # Your search logic
+    matching_ids = ["id1", "id2", "id3"]
+    return {"ids": matching_ids}
+
+@mcp.tool()
+def fetch(id: str) -> dict:
+    """
+    Fetch a complete record by ID.
+    Return the full record data for ChatGPT to analyze.
+    """
+    # Your fetch logic
+    return {
+        "id": id,
+        "title": "Record Title",
+        "content": "Full record content...",
+        "metadata": {"author": "Jane Doe", "date": "2024"}
+    }
+```
+
+### Using Deep Research
+
+1. Ensure your server is added to ChatGPT's connectors (same as Chat mode)
+2. Start a new chat
+3. Click **+** → **Deep Research**
+4. Select your MCP server as a source
+5. Ask research questions
+
+ChatGPT will use your `search` and `fetch` tools to find and cite relevant information.
diff --git a/docs/integrations/claude-code.mdx b/docs/integrations/claude-code.mdx
new file mode 100644
index 0000000..8098ff5
--- /dev/null
+++ b/docs/integrations/claude-code.mdx
@@ -0,0 +1,177 @@
+---
+title: Claude Code 🤝 FastMCP
+sidebarTitle: Claude Code
+description: Install and use FastMCP servers in Claude Code
+icon: message-smile
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+import { LocalFocusTip } from "/snippets/local-focus.mdx"
+
+<LocalFocusTip />
+
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code) supports MCP servers through multiple transport methods including STDIO, SSE, and HTTP, allowing you to extend Claude's capabilities with custom tools, resources, and prompts from your FastMCP servers.
+
+## Requirements
+
+This integration uses STDIO transport to run your FastMCP server locally. For remote deployments, you can run your FastMCP server with HTTP or SSE transport and configure it directly using Claude Code's built-in MCP management commands.
+
+## Create a Server
+
+The examples in this guide will use the following simple dice-rolling server, saved as `server.py`.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Install the Server
+
+### FastMCP CLI
+<VersionBadge version="2.10.3" />
+
+The easiest way to install a FastMCP server in Claude Code is using the `fastmcp install claude-code` command. This automatically handles the configuration, dependency management, and calls Claude Code's built-in MCP management system.
+
+```bash
+fastmcp install claude-code server.py
+```
+
+The install command supports the same `file.py:object` notation as the `run` command. If no object is specified, it will automatically look for a FastMCP server object named `mcp`, `server`, or `app` in your file:
+
+```bash
+# These are equivalent if your server object is named 'mcp'
+fastmcp install claude-code server.py
+fastmcp install claude-code server.py:mcp
+
+# Use explicit object name if your server has a different name
+fastmcp install claude-code server.py:my_custom_server
+```
+
+The command will automatically configure the server with Claude Code's `claude mcp add` command.
+
+#### Dependencies
+
+FastMCP provides flexible dependency management options for your Claude Code servers:
+
+**Individual packages**: Use the `--with` flag to specify packages your server needs. You can use this flag multiple times:
+
+```bash
+fastmcp install claude-code server.py --with pandas --with requests
+```
+
+**Requirements file**: If you maintain a `requirements.txt` file with all your dependencies, use `--with-requirements` to install them:
+
+```bash
+fastmcp install claude-code server.py --with-requirements requirements.txt
+```
+
+**Editable packages**: For local packages under development, use `--with-editable` to install them in editable mode:
+
+```bash
+fastmcp install claude-code server.py --with-editable ./my-local-package
+```
+
+Alternatively, you can use a `fastmcp.json` configuration file (recommended):
+
+```json fastmcp.json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "dependencies": ["pandas", "requests"]
+  }
+}
+```
+
+
+#### Python Version and Project Configuration
+
+Control the Python environment for your server with these options:
+
+**Python version**: Use `--python` to specify which Python version your server requires. This ensures compatibility when your server needs specific Python features:
+
+```bash
+fastmcp install claude-code server.py --python 3.11
+```
+
+**Project directory**: Use `--project` to run your server within a specific project context. This tells `uv` to use the project's configuration files and virtual environment:
+
+```bash
+fastmcp install claude-code server.py --project /path/to/my-project
+```
+
+#### Environment Variables
+
+If your server needs environment variables (like API keys), you must include them:
+
+```bash
+fastmcp install claude-code server.py --server-name "Weather Server" \
+  --env API_KEY=your-api-key \
+  --env DEBUG=true
+```
+
+Or load them from a `.env` file:
+
+```bash
+fastmcp install claude-code server.py --server-name "Weather Server" --env-file .env
+```
+
+<Warning>
+**Claude Code must be installed**. The integration looks for the Claude Code CLI at the default installation location (`~/.claude/local/claude`) and uses the `claude mcp add` command to register servers.
+</Warning>
+
+### Manual Configuration
+
+For more control over the configuration, you can manually use Claude Code's built-in MCP management commands. This gives you direct control over how your server is launched:
+
+```bash
+# Add a server with custom configuration
+claude mcp add dice-roller -- uv run --with fastmcp fastmcp run server.py
+
+# Add with environment variables
+claude mcp add weather-server -e API_KEY=secret -e DEBUG=true -- uv run --with fastmcp fastmcp run server.py
+
+# Add with specific scope (local, user, or project)
+claude mcp add my-server --scope user -- uv run --with fastmcp fastmcp run server.py
+```
+
+You can also manually specify Python versions and project directories in your Claude Code commands:
+
+```bash
+# With specific Python version
+claude mcp add ml-server -- uv run --python 3.11 --with fastmcp fastmcp run server.py
+
+# Within a project directory
+claude mcp add project-server -- uv run --project /path/to/project --with fastmcp fastmcp run server.py
+```
+
+## Using the Server
+
+Once your server is installed, you can start using your FastMCP server with Claude Code.
+
+Try asking Claude something like:
+
+> "Roll some dice for me"
+
+Claude will automatically detect your `roll_dice` tool and use it to fulfill your request, returning something like:
+
+> I'll roll some dice for you! Here are your results: [4, 2, 6]
+> 
+> You rolled three dice and got a 4, a 2, and a 6!
+
+Claude Code can now access all the tools, resources, and prompts you've defined in your FastMCP server. 
+
+If your server provides resources, you can reference them with `@` mentions using the format `@server:protocol://resource/path`. If your server provides prompts, you can use them as slash commands with `/mcp__servername__promptname`.
\ No newline at end of file
diff --git a/docs/integrations/claude-desktop.mdx b/docs/integrations/claude-desktop.mdx
new file mode 100644
index 0000000..4478bcc
--- /dev/null
+++ b/docs/integrations/claude-desktop.mdx
@@ -0,0 +1,299 @@
+---
+title: Claude Desktop 🤝 FastMCP
+sidebarTitle: Claude Desktop
+description: Connect FastMCP servers to Claude Desktop
+icon: message-smile
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+import { LocalFocusTip } from "/snippets/local-focus.mdx"
+
+<LocalFocusTip />
+
+[Claude Desktop](https://www.claude.com/download) supports MCP servers through local STDIO connections and remote servers (beta), allowing you to extend Claude's capabilities with custom tools, resources, and prompts from your FastMCP servers.
+
+<Note>
+Remote MCP server support is currently in beta and available for users on Claude Pro, Max, Team, and Enterprise plans (as of June 2025). Most users will still need to use local STDIO connections.
+</Note>
+
+<Note>
+This guide focuses specifically on using FastMCP servers with Claude Desktop. For general Claude Desktop MCP setup and official examples, see the [official Claude Desktop quickstart guide](https://modelcontextprotocol.io/quickstart/user).
+</Note>
+
+
+## Requirements
+
+Claude Desktop traditionally requires MCP servers to run locally using STDIO transport, where your server communicates with Claude through standard input/output rather than HTTP. However, users on certain plans now have access to remote server support as well.
+
+<Tip>
+If you don't have access to remote server support or need to connect to remote servers, you can create a **proxy server** that runs locally via STDIO and forwards requests to remote HTTP servers. See the [Proxy Servers](#proxy-servers) section below.
+</Tip>
+
+## Create a Server
+
+The examples in this guide will use the following simple dice-rolling server, saved as `server.py`.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Install the Server
+
+### FastMCP CLI
+<VersionBadge version="2.10.3" />
+
+The easiest way to install a FastMCP server in Claude Desktop is using the `fastmcp install claude-desktop` command. This automatically handles the configuration and dependency management.
+
+<Tip>
+Prior to version 2.10.3, Claude Desktop could be managed by running `fastmcp install <path>` without specifying the client.
+</Tip>
+
+```bash
+fastmcp install claude-desktop server.py
+```
+
+The install command supports the same `file.py:object` notation as the `run` command. If no object is specified, it will automatically look for a FastMCP server object named `mcp`, `server`, or `app` in your file:
+
+```bash
+# These are equivalent if your server object is named 'mcp'
+fastmcp install claude-desktop server.py
+fastmcp install claude-desktop server.py:mcp
+
+# Use explicit object name if your server has a different name
+fastmcp install claude-desktop server.py:my_custom_server
+```
+
+After installation, restart Claude Desktop completely. You should see a hammer icon (🔨) in the bottom left of the input box, indicating that MCP tools are available.
+
+#### Dependencies
+
+FastMCP provides several ways to manage your server's dependencies when installing in Claude Desktop:
+
+**Individual packages**: Use the `--with` flag to specify packages your server needs. You can use this flag multiple times:
+
+```bash
+fastmcp install claude-desktop server.py --with pandas --with requests
+```
+
+**Requirements file**: If you have a `requirements.txt` file listing all your dependencies, use `--with-requirements` to install them all at once:
+
+```bash
+fastmcp install claude-desktop server.py --with-requirements requirements.txt
+```
+
+**Editable packages**: For local packages in development, use `--with-editable` to install them in editable mode:
+
+```bash
+fastmcp install claude-desktop server.py --with-editable ./my-local-package
+```
+
+Alternatively, you can use a `fastmcp.json` configuration file (recommended):
+
+```json fastmcp.json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "dependencies": ["pandas", "requests"]
+  }
+}
+```
+
+
+#### Python Version and Project Directory
+
+FastMCP allows you to control the Python environment for your server:
+
+**Python version**: Use `--python` to specify which Python version your server should run with. This is particularly useful when your server requires a specific Python version:
+
+```bash
+fastmcp install claude-desktop server.py --python 3.11
+```
+
+**Project directory**: Use `--project` to run your server within a specific project directory. This ensures that `uv` will discover all `pyproject.toml`, `uv.toml`, and `.python-version` files from that project:
+
+```bash
+fastmcp install claude-desktop server.py --project /path/to/my-project
+```
+
+When you specify a project directory, all relative paths in your server will be resolved from that directory, and the project's virtual environment will be used.
+
+#### Environment Variables
+
+<Warning>
+Claude Desktop runs servers in a completely isolated environment with no access to your shell environment or locally installed applications. You must explicitly pass any environment variables your server needs.
+</Warning>
+
+If your server needs environment variables (like API keys), you must include them:
+
+```bash
+fastmcp install claude-desktop server.py --server-name "Weather Server" \
+  --env API_KEY=your-api-key \
+  --env DEBUG=true
+```
+
+Or load them from a `.env` file:
+
+```bash
+fastmcp install claude-desktop server.py --server-name "Weather Server" --env-file .env
+```
+<Warning>
+- **`uv` must be installed and available in your system PATH**. Claude Desktop runs in its own isolated environment and needs `uv` to manage dependencies.
+- **On macOS, it is recommended to install `uv` globally with Homebrew** so that Claude Desktop will detect it: `brew install uv`. Installing `uv` with other methods may not make it accessible to Claude Desktop.
+</Warning>
+
+
+### Manual Configuration
+
+For more control over the configuration, you can manually edit Claude Desktop's configuration file. You can open the configuration file from Claude's developer settings, or find it in the following locations:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+The configuration file is a JSON object with a `mcpServers` key, which contains the configuration for each MCP server.
+
+```json
+{
+  "mcpServers": {
+    "dice-roller": {
+      "command": "python",
+      "args": ["path/to/your/server.py"]
+    }
+  }
+}
+```
+
+After updating the configuration file, restart Claude Desktop completely. Look for the hammer icon (🔨) to confirm your server is loaded.
+
+#### Dependencies
+
+If your server has dependencies, you can use `uv` or another package manager to set up the environment.
+
+
+When manually configuring dependencies, the recommended approach is to use `uv` with FastMCP. The configuration uses `uv run` to create an isolated environment with your specified packages:
+
+```json
+{
+  "mcpServers": {
+    "dice-roller": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--with", "fastmcp",
+        "--with", "pandas",
+        "--with", "requests", 
+        "fastmcp",
+        "run",
+        "path/to/your/server.py"
+      ]
+    }
+  }
+}
+```
+
+You can also manually specify Python versions and project directories in your configuration. Add `--python` to use a specific Python version, or `--project` to run within a project directory:
+
+```json
+{
+  "mcpServers": {
+    "dice-roller": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--python", "3.11",
+        "--project", "/path/to/project",
+        "--with", "fastmcp",
+        "fastmcp",
+        "run",
+        "path/to/your/server.py"
+      ]
+    }
+  }
+}
+```
+
+The order of arguments matters: Python version and project settings come before package specifications, which come before the actual command to run.
+
+<Warning>
+- **`uv` must be installed and available in your system PATH**. Claude Desktop runs in its own isolated environment and needs `uv` to manage dependencies.
+- **On macOS, it is recommended to install `uv` globally with Homebrew** so that Claude Desktop will detect it: `brew install uv`. Installing `uv` with other methods may not make it accessible to Claude Desktop.
+</Warning>
+
+#### Environment Variables
+
+You can also specify environment variables in the configuration:
+
+```json
+{
+  "mcpServers": {
+    "weather-server": {
+      "command": "python",
+      "args": ["path/to/weather_server.py"],
+      "env": {
+        "API_KEY": "your-api-key",
+        "DEBUG": "true"
+      }
+    }
+  }
+}
+```
+<Warning>
+Claude Desktop runs servers in a completely isolated environment with no access to your shell environment or locally installed applications. You must explicitly pass any environment variables your server needs.
+</Warning>
+
+
+## Remote Servers
+
+
+Users on Claude Pro, Max, Team, and Enterprise plans have first-class remote server support via integrations. For other users, or as an alternative approach, FastMCP can create a proxy server that forwards requests to a remote HTTP server. You can install the proxy server in Claude Desktop.
+
+Create a proxy server that connects to a remote HTTP server:
+
+```python proxy_server.py
+from fastmcp.server import create_proxy
+
+# Create a proxy to a remote server
+proxy = create_proxy(
+    "https://example.com/mcp/sse",
+    name="Remote Server Proxy"
+)
+
+if __name__ == "__main__":
+    proxy.run()  # Runs via STDIO for Claude Desktop
+```
+
+### Authentication
+
+For authenticated remote servers, create an authenticated client following the guidance in the [client auth documentation](/clients/auth/bearer) and pass it to the proxy:
+
+```python auth_proxy_server.py {7}
+from fastmcp import Client
+from fastmcp.client.auth import BearerAuth
+from fastmcp.server import create_proxy
+
+# Create authenticated client
+client = Client(
+    "https://api.example.com/mcp/sse",
+    auth=BearerAuth(token="your-access-token")
+)
+
+# Create proxy using the authenticated client
+proxy = create_proxy(client, name="Authenticated Proxy")
+
+if __name__ == "__main__":
+    proxy.run()
+```
+
diff --git a/docs/integrations/cursor-install-mcp.png b/docs/integrations/cursor-install-mcp.png
new file mode 100644
index 0000000..5681d70
Binary files /dev/null and b/docs/integrations/cursor-install-mcp.png differ
diff --git a/docs/integrations/cursor.mdx b/docs/integrations/cursor.mdx
new file mode 100644
index 0000000..da0744e
--- /dev/null
+++ b/docs/integrations/cursor.mdx
@@ -0,0 +1,284 @@
+---
+title: Cursor 🤝 FastMCP
+sidebarTitle: Cursor
+description: Install and use FastMCP servers in Cursor
+icon: message-smile
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+import { LocalFocusTip } from "/snippets/local-focus.mdx"
+
+<LocalFocusTip />
+
+[Cursor](https://www.cursor.com/) supports MCP servers through multiple transport methods including STDIO, SSE, and Streamable HTTP, allowing you to extend Cursor's AI assistant with custom tools, resources, and prompts from your FastMCP servers.
+
+## Requirements
+
+This integration uses STDIO transport to run your FastMCP server locally. For remote deployments, you can run your FastMCP server with HTTP or SSE transport and configure it directly in Cursor's settings.
+
+## Create a Server
+
+The examples in this guide will use the following simple dice-rolling server, saved as `server.py`.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Install the Server
+
+### FastMCP CLI
+<VersionBadge version="2.10.3" />
+
+The easiest way to install a FastMCP server in Cursor is using the `fastmcp install cursor` command. This automatically handles the configuration, dependency management, and opens Cursor with a deeplink to install the server.
+
+```bash
+fastmcp install cursor server.py
+```
+
+#### Workspace Installation
+<VersionBadge version="2.12.0" />
+
+By default, FastMCP installs servers globally for Cursor. You can also install servers to project-specific workspaces using the `--workspace` flag:
+
+```bash
+# Install to current directory's .cursor/ folder
+fastmcp install cursor server.py --workspace .
+
+# Install to specific workspace
+fastmcp install cursor server.py --workspace /path/to/project
+```
+
+This creates a `.cursor/mcp.json` configuration file in the specified workspace directory, allowing different projects to have their own MCP server configurations.
+
+The install command supports the same `file.py:object` notation as the `run` command. If no object is specified, it will automatically look for a FastMCP server object named `mcp`, `server`, or `app` in your file:
+
+```bash
+# These are equivalent if your server object is named 'mcp'
+fastmcp install cursor server.py
+fastmcp install cursor server.py:mcp
+
+# Use explicit object name if your server has a different name
+fastmcp install cursor server.py:my_custom_server
+```
+
+After running the command, Cursor will open automatically and prompt you to install the server. The command will be `uv`, which is expected as this is a Python STDIO server. Click "Install" to confirm:
+
+![Cursor install prompt](./cursor-install-mcp.png)
+
+#### Dependencies
+
+FastMCP offers multiple ways to manage dependencies for your Cursor servers:
+
+**Individual packages**: Use the `--with` flag to specify packages your server needs. You can use this flag multiple times:
+
+```bash
+fastmcp install cursor server.py --with pandas --with requests
+```
+
+**Requirements file**: For projects with a `requirements.txt` file, use `--with-requirements` to install all dependencies at once:
+
+```bash
+fastmcp install cursor server.py --with-requirements requirements.txt
+```
+
+**Editable packages**: When developing local packages, use `--with-editable` to install them in editable mode:
+
+```bash
+fastmcp install cursor server.py --with-editable ./my-local-package
+```
+
+Alternatively, you can use a `fastmcp.json` configuration file (recommended):
+
+```json fastmcp.json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "dependencies": ["pandas", "requests"]
+  }
+}
+```
+
+
+#### Python Version and Project Configuration
+
+Control your server's Python environment with these options:
+
+**Python version**: Use `--python` to specify which Python version your server should use. This is essential when your server requires specific Python features:
+
+```bash
+fastmcp install cursor server.py --python 3.11
+```
+
+**Project directory**: Use `--project` to run your server within a specific project context. This ensures `uv` discovers all project configuration files and uses the correct virtual environment:
+
+```bash
+fastmcp install cursor server.py --project /path/to/my-project
+```
+
+#### Environment Variables
+
+<Warning>
+Cursor runs servers in a completely isolated environment with no access to your shell environment or locally installed applications. You must explicitly pass any environment variables your server needs.
+</Warning>
+
+If your server needs environment variables (like API keys), you must include them:
+
+```bash
+fastmcp install cursor server.py --server-name "Weather Server" \
+  --env API_KEY=your-api-key \
+  --env DEBUG=true
+```
+
+Or load them from a `.env` file:
+
+```bash
+fastmcp install cursor server.py --server-name "Weather Server" --env-file .env
+```
+
+<Warning>
+**`uv` must be installed and available in your system PATH**. Cursor runs in its own isolated environment and needs `uv` to manage dependencies.
+</Warning>
+
+### Generate MCP JSON
+
+<Note>
+**Use the first-class integration above for the best experience.** The MCP JSON generation is useful for advanced use cases, manual configuration, or integration with other tools.
+</Note>
+
+You can generate MCP JSON configuration for manual use:
+
+```bash
+# Generate configuration and output to stdout
+fastmcp install mcp-json server.py --server-name "Dice Roller" --with pandas
+
+# Copy configuration to clipboard for easy pasting
+fastmcp install mcp-json server.py --server-name "Dice Roller" --copy
+```
+
+This generates the standard `mcpServers` configuration format that can be used with any MCP-compatible client.
+
+### Manual Configuration
+
+For more control over the configuration, you can manually edit Cursor's configuration file. The configuration file is located at:
+- **All platforms**: `~/.cursor/mcp.json`
+
+The configuration file is a JSON object with a `mcpServers` key, which contains the configuration for each MCP server.
+
+```json
+{
+  "mcpServers": {
+    "dice-roller": {
+      "command": "python",
+      "args": ["path/to/your/server.py"]
+    }
+  }
+}
+```
+
+After updating the configuration file, your server should be available in Cursor.
+
+#### Dependencies
+
+If your server has dependencies, you can use `uv` or another package manager to set up the environment.
+
+When manually configuring dependencies, the recommended approach is to use `uv` with FastMCP. The configuration should use `uv run` to create an isolated environment with your specified packages:
+
+```json
+{
+  "mcpServers": {
+    "dice-roller": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--with", "fastmcp",
+        "--with", "pandas",
+        "--with", "requests", 
+        "fastmcp",
+        "run",
+        "path/to/your/server.py"
+      ]
+    }
+  }
+}
+```
+
+You can also manually specify Python versions and project directories in your configuration:
+
+```json
+{
+  "mcpServers": {
+    "dice-roller": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--python", "3.11",
+        "--project", "/path/to/project",
+        "--with", "fastmcp",
+        "fastmcp",
+        "run",
+        "path/to/your/server.py"
+      ]
+    }
+  }
+}
+```
+
+Note that the order of arguments is important: Python version and project settings should come before package specifications.
+
+<Warning>
+**`uv` must be installed and available in your system PATH**. Cursor runs in its own isolated environment and needs `uv` to manage dependencies.
+</Warning>
+
+#### Environment Variables
+
+You can also specify environment variables in the configuration:
+
+```json
+{
+  "mcpServers": {
+    "weather-server": {
+      "command": "python",
+      "args": ["path/to/weather_server.py"],
+      "env": {
+        "API_KEY": "your-api-key",
+        "DEBUG": "true"
+      }
+    }
+  }
+}
+```
+
+<Warning>
+Cursor runs servers in a completely isolated environment with no access to your shell environment or locally installed applications. You must explicitly pass any environment variables your server needs.
+</Warning>
+
+## Using the Server
+
+Once your server is installed, you can start using your FastMCP server with Cursor's AI assistant.
+
+Try asking Cursor something like:
+
+> "Roll some dice for me"
+
+Cursor will automatically detect your `roll_dice` tool and use it to fulfill your request, returning something like:
+
+> 🎲 Here are your dice rolls: 4, 6, 4
+> 
+> You rolled 3 dice with a total of 14! The 6 was a nice high roll there!
+
+The AI assistant can now access all the tools, resources, and prompts you've defined in your FastMCP server.
diff --git a/docs/integrations/descope.mdx b/docs/integrations/descope.mdx
new file mode 100644
index 0000000..bfb6cd9
--- /dev/null
+++ b/docs/integrations/descope.mdx
@@ -0,0 +1,113 @@
+---
+title: Descope 🤝 FastMCP
+sidebarTitle: Descope
+description: Secure your FastMCP server with Descope
+icon: shield-check
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+<VersionBadge version="2.12.4" />
+
+This guide shows you how to secure your FastMCP server using [**Descope**](https://www.descope.com), a complete authentication and user management solution. This integration uses the [**Remote OAuth**](/servers/auth/remote-oauth) pattern, where Descope handles user login and your FastMCP server validates the tokens.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+
+1. To [sign up](https://www.descope.com/sign-up) for a Free Forever Descope account
+2. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:3000`)
+
+### Step 1: Configure Descope
+
+<Steps>
+<Step title="Create an MCP Server">
+    1. Go to the [MCP Servers page](https://app.descope.com/mcp-servers) of the Descope Console, and create a new MCP Server.
+    2. Give the MCP server a name and description.
+    3. Ensure that **Dynamic Client Registration (DCR)** is enabled. Then click **Create**.
+    4. Once you've created the MCP Server, note your Well-Known URL.
+    
+    
+    <Warning>
+    DCR is required for FastMCP clients to automatically register with your authentication server.
+    </Warning>
+</Step>
+
+<Step title="Note Your Well-Known URL">
+    Save your Well-Known URL from [MCP Server Settings](https://app.descope.com/mcp-servers):
+    ```
+    Well-Known URL: https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration
+    ```
+</Step>
+</Steps>
+
+### Step 2: Environment Setup
+
+Create a `.env` file with your Descope configuration:
+
+```bash
+DESCOPE_CONFIG_URL=https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration     # Your Descope Well-Known URL
+SERVER_URL=http://localhost:3000     # Your server's base URL
+```
+
+### Step 3: FastMCP Configuration
+
+Create your FastMCP server file and use the DescopeProvider to handle all the OAuth integration automatically:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.descope import DescopeProvider
+
+# The DescopeProvider automatically discovers Descope endpoints
+# and configures JWT token validation
+auth_provider = DescopeProvider(
+    config_url="https://.../.well-known/openid-configuration",  # Your MCP Server .well-known URL
+    base_url=SERVER_URL,                                        # Your server's public URL
+)
+
+# Create FastMCP server with auth
+mcp = FastMCP(name="My Descope Protected Server", auth=auth_provider)
+
+```
+
+## Testing
+
+To test your server, you can use the `fastmcp` CLI to run it locally. Assuming you've saved the above code to `server.py` (after replacing the environment variables with your actual values!), you can run the following command:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Now, you can use a FastMCP client to test that you can reach your server after authenticating:
+
+```python
+from fastmcp import Client
+import asyncio
+
+async def main():
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        assert await client.ping()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Production Configuration
+
+For production deployments, load configuration from environment variables:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.descope import DescopeProvider
+
+# Load configuration from environment variables
+auth = DescopeProvider(
+    config_url=os.environ.get("DESCOPE_CONFIG_URL"),
+    base_url=os.environ.get("BASE_URL", "https://your-server.com")
+)
+
+mcp = FastMCP(name="My Descope Protected Server", auth=auth)
+```
diff --git a/docs/integrations/discord.mdx b/docs/integrations/discord.mdx
new file mode 100644
index 0000000..5d6c643
--- /dev/null
+++ b/docs/integrations/discord.mdx
@@ -0,0 +1,183 @@
+---
+title: Discord OAuth 🤝 FastMCP
+sidebarTitle: Discord
+description: Secure your FastMCP server with Discord OAuth
+icon: discord
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.13.2" />
+
+This guide shows you how to secure your FastMCP server using **Discord OAuth**. Since Discord doesn't support Dynamic Client Registration, this integration uses the [**OAuth Proxy**](/servers/auth/oauth-proxy) pattern to bridge Discord's traditional OAuth with MCP's authentication requirements.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+1. A **[Discord Account](https://discord.com/)** with access to create applications
+2. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`)
+
+### Step 1: Create a Discord Application
+
+Create an application in the Discord Developer Portal to get the credentials needed for authentication:
+
+<Steps>
+<Step title="Navigate to Discord Developer Portal">
+    Go to the [Discord Developer Portal](https://discord.com/developers/applications).
+
+    Click **"New Application"** and give it a name users will recognize (e.g., "My FastMCP Server").
+</Step>
+
+<Step title="Configure OAuth2 Settings">
+    In the left sidebar, click **"OAuth2"**.
+
+    In the **Redirects** section, click **"Add Redirect"** and enter your callback URL:
+    - For development: `http://localhost:8000/auth/callback`
+    - For production: `https://your-domain.com/auth/callback`
+
+    <Warning>
+    The redirect URL must match exactly. The default path is `/auth/callback`, but you can customize it using the `redirect_path` parameter. Discord allows `http://localhost` URLs for development. For production, use HTTPS.
+    </Warning>
+</Step>
+
+<Step title="Save Your Credentials">
+    On the same OAuth2 page, you'll find:
+
+    - **Client ID**: A numeric string like `12345`
+    - **Client Secret**: Click "Reset Secret" to generate one
+
+    <Tip>
+    Store these credentials securely. Never commit them to version control. Use environment variables or a secrets manager in production.
+    </Tip>
+</Step>
+</Steps>
+
+### Step 2: FastMCP Configuration
+
+Create your FastMCP server using the `DiscordProvider`, which handles Discord's OAuth flow automatically:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.discord import DiscordProvider
+
+auth_provider = DiscordProvider(
+    client_id="12345",      # Your Discord Application Client ID
+    client_secret="your-client-secret",    # Your Discord OAuth Client Secret
+    base_url="http://localhost:8000",      # Must match your OAuth configuration
+)
+
+mcp = FastMCP(name="Discord Secured App", auth=auth_provider)
+
+@mcp.tool
+async def get_user_info() -> dict:
+    """Returns information about the authenticated Discord user."""
+    from fastmcp.server.dependencies import get_access_token
+
+    token = get_access_token()
+    return {
+        "discord_id": token.claims.get("sub"),
+        "username": token.claims.get("username"),
+        "avatar": token.claims.get("avatar"),
+    }
+```
+
+## Testing
+
+### Running the Server
+
+Start your FastMCP server with HTTP transport to enable OAuth flows:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Your server is now running and protected by Discord OAuth authentication.
+
+### Testing with a Client
+
+Create a test client that authenticates with your Discord-protected server:
+
+```python test_client.py
+from fastmcp import Client
+import asyncio
+
+async def main():
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        print("✓ Authenticated with Discord!")
+
+        result = await client.call_tool("get_user_info")
+        print(f"Discord user: {result['username']}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+1. Your browser will open to Discord's authorization page
+2. Sign in with your Discord account and authorize the app
+3. After authorization, you'll be redirected back
+4. The client receives the token and can make authenticated requests
+
+<Info>
+The client caches tokens locally, so you won't need to re-authenticate for subsequent runs unless the token expires or you explicitly clear the cache.
+</Info>
+
+## Discord Scopes
+
+Discord OAuth supports several scopes for accessing different types of user data:
+
+| Scope | Description |
+|-------|-------------|
+| `identify` | Access username, avatar, and discriminator (default) |
+| `email` | Access the user's email address |
+| `guilds` | Access the user's list of servers |
+| `guilds.join` | Ability to add the user to a server |
+
+To request additional scopes:
+
+```python
+auth_provider = DiscordProvider(
+    client_id="...",
+    client_secret="...",
+    base_url="http://localhost:8000",
+    required_scopes=["identify", "email"],
+)
+```
+
+## Production Configuration
+
+For production deployments with persistent token management across server restarts, configure `jwt_signing_key` and `client_storage`:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.discord import DiscordProvider
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+auth_provider = DiscordProvider(
+    client_id="12345",
+    client_secret=os.environ["DISCORD_CLIENT_SECRET"],
+    base_url="https://your-production-domain.com",
+
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(
+            host=os.environ["REDIS_HOST"],
+            port=int(os.environ["REDIS_PORT"])
+        ),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+
+mcp = FastMCP(name="Production Discord App", auth=auth_provider)
+```
+
+<Note>
+Parameters (`jwt_signing_key` and `client_storage`) work together to ensure tokens and client registrations survive server restarts. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without it, tokens are stored in plaintext. Store secrets in environment variables and use a persistent storage backend like Redis for distributed deployments.
+
+For complete details on these parameters, see the [OAuth Proxy documentation](/servers/auth/oauth-proxy#configuration-parameters).
+</Note>
diff --git a/docs/integrations/eunomia-authorization.mdx b/docs/integrations/eunomia-authorization.mdx
new file mode 100644
index 0000000..2fd2ca4
--- /dev/null
+++ b/docs/integrations/eunomia-authorization.mdx
@@ -0,0 +1,129 @@
+---
+title: Eunomia Authorization 🤝 FastMCP
+sidebarTitle: Eunomia Auth
+description: Add policy-based authorization to your FastMCP servers with Eunomia
+icon: shield-check
+---
+
+Add **policy-based authorization** to your FastMCP servers with one-line code addition with the **[Eunomia][eunomia-github] authorization middleware**.
+
+Control which tools, resources and prompts MCP clients can view and execute on your server. Define dynamic JSON-based policies and obtain a comprehensive audit log of all access attempts and violations.
+
+## How it Works
+
+Exploiting FastMCP's [Middleware][fastmcp-middleware], the Eunomia middleware intercepts all MCP requests to your server and automatically maps MCP methods to authorization checks.
+
+### Listing Operations
+
+The middleware behaves as a filter for listing operations (`tools/list`, `resources/list`, `prompts/list`), hiding to the client components that are not authorized by the defined policies.
+
+```mermaid
+sequenceDiagram
+    participant MCPClient as MCP Client
+    participant EunomiaMiddleware as Eunomia Middleware
+    participant MCPServer as FastMCP Server
+    participant EunomiaServer as Eunomia Server
+
+    MCPClient->>EunomiaMiddleware: MCP Listing Request (e.g., tools/list)
+    EunomiaMiddleware->>MCPServer: MCP Listing Request
+    MCPServer-->>EunomiaMiddleware: MCP Listing Response
+    EunomiaMiddleware->>EunomiaServer: Authorization Checks
+    EunomiaServer->>EunomiaMiddleware: Authorization Decisions
+    EunomiaMiddleware-->>MCPClient: Filtered MCP Listing Response
+```
+
+### Execution Operations
+
+The middleware behaves as a firewall for execution operations (`tools/call`, `resources/read`, `prompts/get`), blocking operations that are not authorized by the defined policies.
+
+```mermaid
+sequenceDiagram
+    participant MCPClient as MCP Client
+    participant EunomiaMiddleware as Eunomia Middleware
+    participant MCPServer as FastMCP Server
+    participant EunomiaServer as Eunomia Server
+
+    MCPClient->>EunomiaMiddleware: MCP Execution Request (e.g., tools/call)
+    EunomiaMiddleware->>EunomiaServer: Authorization Check
+    EunomiaServer->>EunomiaMiddleware: Authorization Decision
+    EunomiaMiddleware-->>MCPClient: MCP Unauthorized Error (if denied)
+    EunomiaMiddleware->>MCPServer: MCP Execution Request (if allowed)
+    MCPServer-->>EunomiaMiddleware: MCP Execution Response (if allowed)
+    EunomiaMiddleware-->>MCPClient: MCP Execution Response (if allowed)
+```
+
+## Add Authorization to Your Server
+
+<Note>
+Eunomia is an AI-specific authorization server that handles policy decisions. The server runs embedded within your MCP server by default for a zero-effort configuration, but can alternatively be run remotely for centralized policy decisions.
+
+</Note>
+
+### Create a Server with Authorization
+
+First, install the `eunomia-mcp` package:
+
+```bash
+pip install eunomia-mcp
+```
+
+Then create a FastMCP server and add the Eunomia middleware in one line:
+
+```python server.py
+from fastmcp import FastMCP
+from eunomia_mcp import create_eunomia_middleware
+
+# Create your FastMCP server
+mcp = FastMCP("Secure MCP Server 🔒")
+
+@mcp.tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+# Add middleware to your server
+middleware = create_eunomia_middleware(policy_file="mcp_policies.json")
+mcp.add_middleware(middleware)
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+### Configure Access Policies
+
+Use the `eunomia-mcp` CLI in your terminal to manage your authorization policies:
+
+```bash
+# Create a default policy file
+eunomia-mcp init
+
+# Or create a policy file customized for your FastMCP server
+eunomia-mcp init --custom-mcp "app.server:mcp"
+```
+
+This creates `mcp_policies.json` file that you can further edit to your access control needs.
+
+```bash
+# Once edited, validate your policy file
+eunomia-mcp validate mcp_policies.json
+```
+
+### Run the Server
+
+Start your FastMCP server normally:
+
+```bash
+python server.py
+```
+
+The middleware will now intercept all MCP requests and check them against your policies. Requests include agent identification through headers like `X-Agent-ID`, `X-User-ID`, `User-Agent`, or `Authorization` and an automatic mapping of MCP methods to authorization resources and actions.
+
+<Tip>
+  For detailed policy configuration, custom authentication, and remote
+  deployments, visit the [Eunomia MCP Middleware
+  repository][eunomia-mcp-github].
+</Tip>
+
+[eunomia-github]: https://github.com/whataboutyou-ai/eunomia
+[eunomia-mcp-github]: https://github.com/whataboutyou-ai/eunomia/tree/main/pkgs/extensions/mcp
+[fastmcp-middleware]: /servers/middleware
diff --git a/docs/integrations/fastapi.mdx b/docs/integrations/fastapi.mdx
new file mode 100644
index 0000000..83aa924
--- /dev/null
+++ b/docs/integrations/fastapi.mdx
@@ -0,0 +1,445 @@
+---
+title: FastAPI 🤝 FastMCP
+sidebarTitle: FastAPI
+description: Integrate FastMCP with FastAPI applications
+icon: bolt
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+FastMCP provides two powerful ways to integrate with FastAPI applications:
+
+1. **[Generate an MCP server FROM your FastAPI app](#generating-an-mcp-server)** - Convert existing API endpoints into MCP tools
+2. **[Mount an MCP server INTO your FastAPI app](#mounting-an-mcp-server)** - Add MCP functionality to your web application
+
+<Note>
+When generating an MCP server from FastAPI, FastMCP uses OpenAPIProvider (v3.0.0+) under the hood to source tools from your FastAPI app's OpenAPI spec. See [Providers](/servers/providers/overview) to understand how FastMCP sources components.
+</Note>
+
+
+<Tip>
+Generating MCP servers from OpenAPI is a great way to get started with FastMCP, but in practice LLMs achieve **significantly better performance** with well-designed and curated MCP servers than with auto-converted OpenAPI servers. This is especially true for complex APIs with many endpoints and parameters.
+
+We recommend using the FastAPI integration for bootstrapping and prototyping, not for mirroring your API to LLM clients. See the post [Stop Converting Your REST APIs to MCP](https://www.jlowin.dev/blog/stop-converting-rest-apis-to-mcp) for more details.
+</Tip>
+
+
+<Note>
+FastMCP does *not* include FastAPI as a dependency; you must install it separately to use this integration.
+</Note>
+
+## Example FastAPI Application
+
+Throughout this guide, we'll use this e-commerce API as our example (click the `Copy` button to copy it for use with other code blocks):
+
+```python [expandable]
+# Copy this FastAPI server into other code blocks in this guide
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+
+# Models
+class Product(BaseModel):
+    name: str
+    price: float
+    category: str
+    description: str | None = None
+
+class ProductResponse(BaseModel):
+    id: int
+    name: str
+    price: float
+    category: str
+    description: str | None = None
+
+# Create FastAPI app
+app = FastAPI(title="E-commerce API", version="1.0.0")
+
+# In-memory database
+products_db = {
+    1: ProductResponse(
+        id=1, name="Laptop", price=999.99, category="Electronics"
+    ),
+    2: ProductResponse(
+        id=2, name="Mouse", price=29.99, category="Electronics"
+    ),
+    3: ProductResponse(
+        id=3, name="Desk Chair", price=299.99, category="Furniture"
+    ),
+}
+next_id = 4
+
+@app.get("/products", response_model=list[ProductResponse])
+def list_products(
+    category: str | None = None,
+    max_price: float | None = None,
+) -> list[ProductResponse]:
+    """List all products with optional filtering."""
+    products = list(products_db.values())
+    if category:
+        products = [p for p in products if p.category == category]
+    if max_price:
+        products = [p for p in products if p.price <= max_price]
+    return products
+
+@app.get("/products/{product_id}", response_model=ProductResponse)
+def get_product(product_id: int):
+    """Get a specific product by ID."""
+    if product_id not in products_db:
+        raise HTTPException(status_code=404, detail="Product not found")
+    return products_db[product_id]
+
+@app.post("/products", response_model=ProductResponse)
+def create_product(product: Product):
+    """Create a new product."""
+    global next_id
+    product_response = ProductResponse(id=next_id, **product.model_dump())
+    products_db[next_id] = product_response
+    next_id += 1
+    return product_response
+
+@app.put("/products/{product_id}", response_model=ProductResponse)
+def update_product(product_id: int, product: Product):
+    """Update an existing product."""
+    if product_id not in products_db:
+        raise HTTPException(status_code=404, detail="Product not found")
+    products_db[product_id] = ProductResponse(
+        id=product_id,
+        **product.model_dump(),
+    )
+    return products_db[product_id]
+
+@app.delete("/products/{product_id}")
+def delete_product(product_id: int):
+    """Delete a product."""
+    if product_id not in products_db:
+        raise HTTPException(status_code=404, detail="Product not found")
+    del products_db[product_id]
+    return {"message": "Product deleted"}
+```
+
+<Tip>
+All subsequent code examples in this guide assume you have the above FastAPI application code already defined. Each example builds upon this base application, `app`.
+</Tip>
+
+## Generating an MCP Server
+
+<VersionBadge version="2.0.0" />
+
+One of the most common ways to bootstrap an MCP server is to generate it from an existing FastAPI application. FastMCP will expose your FastAPI endpoints as MCP components (tools, by default) in order to expose your API to LLM clients.
+
+
+
+### Basic Conversion
+
+Convert the FastAPI app to an MCP server with a single line:
+
+```python {5}
+# Assumes the FastAPI app from above is already defined
+from fastmcp import FastMCP
+
+# Convert to MCP server
+mcp = FastMCP.from_fastapi(app=app)
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+### Adding Components
+
+Your converted MCP server is a full FastMCP instance, meaning you can add new tools, resources, and other components to it just like you would with any other FastMCP instance.
+
+```python {8-11}
+# Assumes the FastAPI app from above is already defined
+from fastmcp import FastMCP
+
+# Convert to MCP server
+mcp = FastMCP.from_fastapi(app=app)
+
+# Add a new tool
+@mcp.tool
+def get_product(product_id: int) -> ProductResponse:
+    """Get a product by ID."""
+    return products_db[product_id]
+
+# Run the MCP server
+if __name__ == "__main__":
+    mcp.run()
+```
+
+
+
+
+
+### Interacting with the MCP Server
+
+Once you've converted your FastAPI app to an MCP server, you can interact with it using the FastMCP client to test functionality before deploying it to an LLM-based application.
+
+```python {3, }
+# Assumes the FastAPI app from above is already defined
+from fastmcp import FastMCP
+from fastmcp.client import Client
+import asyncio
+
+# Convert to MCP server
+mcp = FastMCP.from_fastapi(app=app)
+
+async def demo():
+    async with Client(mcp) as client:
+        # List available tools
+        tools = await client.list_tools()
+        print(f"Available tools: {[t.name for t in tools]}")
+        
+        # Create a product
+        result = await client.call_tool(
+            "create_product_products_post",
+            {
+                "name": "Wireless Keyboard",
+                "price": 79.99,
+                "category": "Electronics",
+                "description": "Bluetooth mechanical keyboard"
+            }
+        )
+        print(f"Created product: {result.data}")
+        
+        # List electronics under $100
+        result = await client.call_tool(
+            "list_products_products_get",
+            {"category": "Electronics", "max_price": 100}
+        )
+        print(f"Affordable electronics: {result.data}")
+
+if __name__ == "__main__":
+    asyncio.run(demo())
+```
+
+### Custom Route Mapping
+
+Because FastMCP's FastAPI integration is based on its [OpenAPI integration](/integrations/openapi), you can customize how endpoints are converted to MCP components in exactly the same way. For example, here we use a `RouteMap` to map all GET requests to MCP resources, and all POST/PUT/DELETE requests to MCP tools:
+
+```python
+# Assumes the FastAPI app from above is already defined
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi import RouteMap, MCPType
+
+# Custom mapping rules
+mcp = FastMCP.from_fastapi(
+    app=app,
+    route_maps=[
+        # GET with path params → ResourceTemplates
+        RouteMap(
+            methods=["GET"], 
+            pattern=r".*\{.*\}.*", 
+            mcp_type=MCPType.RESOURCE_TEMPLATE
+        ),
+        # Other GETs → Resources
+        RouteMap(
+            methods=["GET"], 
+            pattern=r".*", 
+            mcp_type=MCPType.RESOURCE
+        ),
+        # POST/PUT/DELETE → Tools (default)
+    ],
+)
+
+# Now:
+# - GET /products → Resource
+# - GET /products/{id} → ResourceTemplate
+# - POST/PUT/DELETE → Tools
+```
+
+<Tip>
+To learn more about customizing the conversion process, see the [OpenAPI Integration guide](/integrations/openapi).
+</Tip>
+
+### Authentication and Headers
+
+You can configure headers and other client options via the `httpx_client_kwargs` parameter. For example, to add authentication to your FastAPI app, you can pass a `headers` dictionary to the `httpx_client_kwargs` parameter:
+
+```python {27-31}
+# Assumes the FastAPI app from above is already defined
+from fastmcp import FastMCP
+
+# Add authentication to your FastAPI app
+from fastapi import Depends, Header
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+
+security = HTTPBearer()
+
+def verify_token(credentials: HTTPAuthorizationCredentials = Depends(security)):
+    if credentials.credentials != "secret-token":
+        raise HTTPException(status_code=401, detail="Invalid authentication")
+    return credentials.credentials
+
+# Add a protected endpoint
+@app.get("/admin/stats", dependencies=[Depends(verify_token)])
+def get_admin_stats():
+    return {
+        "total_products": len(products_db),
+        "categories": list(set(p.category for p in products_db.values()))
+    }
+
+# Create MCP server with authentication headers
+mcp = FastMCP.from_fastapi(
+    app=app,
+    httpx_client_kwargs={
+        "headers": {
+            "Authorization": "Bearer secret-token",
+        }
+    }
+)
+```
+
+## Mounting an MCP Server
+
+<VersionBadge version="2.3.1" />
+
+In addition to generating servers, FastMCP can facilitate adding MCP servers to your existing FastAPI application. You can do this by mounting the MCP ASGI application.
+
+### Basic Mounting
+
+To mount an MCP server, you can use the `http_app` method on your FastMCP instance. This will return an ASGI application that can be mounted to your FastAPI application.
+
+```python {23-30}
+from fastmcp import FastMCP
+from fastapi import FastAPI
+
+# Create MCP server
+mcp = FastMCP("Analytics Tools")
+
+@mcp.tool
+def analyze_pricing(category: str) -> dict:
+    """Analyze pricing for a category."""
+    products = [p for p in products_db.values() if p.category == category]
+    if not products:
+        return {"error": f"No products in {category}"}
+    
+    prices = [p.price for p in products]
+    return {
+        "category": category,
+        "avg_price": round(sum(prices) / len(prices), 2),
+        "min": min(prices),
+        "max": max(prices),
+    }
+
+# Create ASGI app from MCP server
+mcp_app = mcp.http_app(path='/mcp')
+
+# Key: Pass lifespan to FastAPI
+app = FastAPI(title="E-commerce API", lifespan=mcp_app.lifespan)
+
+# Mount the MCP server
+app.mount("/analytics", mcp_app)
+
+# Now: API at /products/*, MCP at /analytics/mcp/
+```
+
+## Offering an LLM-Friendly API
+
+A common pattern is to generate an MCP server from your FastAPI app and serve both interfaces from the same application. This provides an LLM-optimized interface alongside your regular API:
+
+```python
+# Assumes the FastAPI app from above is already defined
+from fastmcp import FastMCP
+from fastapi import FastAPI
+
+# 1. Generate MCP server from your API
+mcp = FastMCP.from_fastapi(app=app, name="E-commerce MCP")
+
+# 2. Create the MCP's ASGI app
+mcp_app = mcp.http_app(path='/mcp')
+
+# 3. Create a new FastAPI app that combines both sets of routes
+combined_app = FastAPI(
+    title="E-commerce API with MCP",
+    routes=[
+        *mcp_app.routes,  # MCP routes
+        *app.routes,      # Original API routes
+    ],
+    lifespan=mcp_app.lifespan,
+)
+
+# Now you have:
+# - Regular API: http://localhost:8000/products
+# - LLM-friendly MCP: http://localhost:8000/mcp
+# Both served from the same FastAPI application!
+```
+
+This approach lets you maintain a single codebase while offering both traditional REST endpoints and MCP-compatible endpoints for LLM clients.
+
+## Key Considerations
+
+### Operation IDs
+
+FastAPI operation IDs become MCP component names. Always specify meaningful operation IDs:
+
+```python
+# Good - explicit operation_id
+@app.get("/users/{user_id}", operation_id="get_user_by_id")
+def get_user(user_id: int):
+    return {"id": user_id}
+
+# Less ideal - auto-generated name
+@app.get("/users/{user_id}")
+def get_user(user_id: int):
+    return {"id": user_id}
+```
+
+### Lifespan Management
+
+When mounting MCP servers, always pass the lifespan context:
+
+```python
+# Correct - lifespan passed, path="/" since we mount at /mcp
+mcp_app = mcp.http_app(path="/")
+app = FastAPI(lifespan=mcp_app.lifespan)
+app.mount("/mcp", mcp_app)  # MCP endpoint at /mcp
+
+# Incorrect - missing lifespan
+app = FastAPI()
+app.mount("/mcp", mcp.http_app(path="/"))  # Session manager won't initialize
+```
+
+If you're mounting an authenticated MCP server under a path prefix, see [Mounting Authenticated Servers](/deployment/http#mounting-authenticated-servers) for important OAuth routing considerations.
+
+### CORS Middleware
+
+If your FastAPI app uses `CORSMiddleware` and you're mounting an OAuth-protected FastMCP server, avoid adding application-wide CORS middleware. FastMCP and the MCP SDK already handle CORS for OAuth routes, and layering CORS middleware can cause conflicts (such as 404 errors on `.well-known` routes or OPTIONS requests).
+
+If you need CORS on your own FastAPI routes, use the sub-app pattern: mount your API and FastMCP as separate apps, each with their own middleware, rather than adding top-level `CORSMiddleware` to the combined application.
+
+### Combining Lifespans
+
+If your FastAPI app already has a lifespan (for database connections, startup tasks, etc.), you can't simply replace it with the MCP lifespan. Use `combine_lifespans` to run both:
+
+```python
+from fastapi import FastAPI
+from fastmcp import FastMCP
+from fastmcp.utilities.lifespan import combine_lifespans
+from contextlib import asynccontextmanager
+
+# Your existing lifespan
+@asynccontextmanager
+async def app_lifespan(app: FastAPI):
+    print("Starting up the app...")
+    yield
+    print("Shutting down the app...")
+
+# Create MCP server
+mcp = FastMCP("Tools")
+mcp_app = mcp.http_app(path="/")
+
+# Combine both lifespans
+app = FastAPI(lifespan=combine_lifespans(app_lifespan, mcp_app.lifespan))
+app.mount("/mcp", mcp_app)  # MCP endpoint at /mcp
+```
+
+`combine_lifespans` enters lifespans in order and exits in reverse order.
+
+### Performance Tips
+
+1. **Use in-memory transport for testing** - Pass MCP servers directly to clients
+2. **Design purpose-built MCP tools** - Better than auto-converting complex APIs
+3. **Keep tool parameters simple** - LLMs perform better with focused interfaces
+
+For more details on configuration options, see the [OpenAPI Integration guide](/integrations/openapi).
\ No newline at end of file
diff --git a/docs/integrations/gemini-cli.mdx b/docs/integrations/gemini-cli.mdx
new file mode 100644
index 0000000..10613fb
--- /dev/null
+++ b/docs/integrations/gemini-cli.mdx
@@ -0,0 +1,173 @@
+---
+title: Gemini CLI 🤝 FastMCP
+sidebarTitle: Gemini CLI
+description: Install and use FastMCP servers in Gemini CLI
+icon: message-smile
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+import { LocalFocusTip } from "/snippets/local-focus.mdx"
+
+<LocalFocusTip />
+
+[Gemini CLI](https://geminicli.com/) supports MCP servers through multiple transport methods including STDIO, SSE, and HTTP, allowing you to extend Gemini's capabilities with custom tools, resources, and prompts from your FastMCP servers.
+
+## Requirements
+
+This integration uses STDIO transport to run your FastMCP server locally. For remote deployments, you can run your FastMCP server with HTTP or SSE transport and configure it directly using Gemini CLI's built-in MCP management commands.
+
+## Create a Server
+
+The examples in this guide will use the following simple dice-rolling server, saved as `server.py`.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Install the Server
+
+### FastMCP CLI
+<VersionBadge version="2.13.0" />
+
+The easiest way to install a FastMCP server in Gemini CLI is using the `fastmcp install gemini-cli` command. This automatically handles the configuration, dependency management, and calls Gemini CLI's built-in MCP management system.
+
+```bash
+fastmcp install gemini-cli server.py
+```
+
+The install command supports the same `file.py:object` notation as the `run` command. If no object is specified, it will automatically look for a FastMCP server object named `mcp`, `server`, or `app` in your file:
+
+```bash
+# These are equivalent if your server object is named 'mcp'
+fastmcp install gemini-cli server.py
+fastmcp install gemini-cli server.py:mcp
+
+# Use explicit object name if your server has a different name
+fastmcp install gemini-cli server.py:my_custom_server
+```
+
+The command will automatically configure the server with Gemini CLI's `gemini mcp add` command.
+
+#### Dependencies
+
+FastMCP provides flexible dependency management options for your Gemini CLI servers:
+
+**Individual packages**: Use the `--with` flag to specify packages your server needs. You can use this flag multiple times:
+
+```bash
+fastmcp install gemini-cli server.py --with pandas --with requests
+```
+
+**Requirements file**: If you maintain a `requirements.txt` file with all your dependencies, use `--with-requirements` to install them:
+
+```bash
+fastmcp install gemini-cli server.py --with-requirements requirements.txt
+```
+
+**Editable packages**: For local packages under development, use `--with-editable` to install them in editable mode:
+
+```bash
+fastmcp install gemini-cli server.py --with-editable ./my-local-package
+```
+
+Alternatively, you can use a `fastmcp.json` configuration file (recommended):
+
+```json fastmcp.json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "dependencies": ["pandas", "requests"]
+  }
+}
+```
+
+
+#### Python Version and Project Configuration
+
+Control the Python environment for your server with these options:
+
+**Python version**: Use `--python` to specify which Python version your server requires. This ensures compatibility when your server needs specific Python features:
+
+```bash
+fastmcp install gemini-cli server.py --python 3.11
+```
+
+**Project directory**: Use `--project` to run your server within a specific project context. This tells `uv` to use the project's configuration files and virtual environment:
+
+```bash
+fastmcp install gemini-cli server.py --project /path/to/my-project
+```
+
+#### Environment Variables
+
+If your server needs environment variables (like API keys), you must include them:
+
+```bash
+fastmcp install gemini-cli server.py --server-name "Weather Server" \
+  --env API_KEY=your-api-key \
+  --env DEBUG=true
+```
+
+Or load them from a `.env` file:
+
+```bash
+fastmcp install gemini-cli server.py --server-name "Weather Server" --env-file .env
+```
+
+<Warning>
+**Gemini CLI must be installed**. The integration looks for the Gemini CLI and uses the `gemini mcp add` command to register servers.
+</Warning>
+
+### Manual Configuration
+
+For more control over the configuration, you can manually use Gemini CLI's built-in MCP management commands. This gives you direct control over how your server is launched:
+
+```bash
+# Add a server with custom configuration
+gemini mcp add dice-roller uv -- run --with fastmcp fastmcp run server.py
+
+# Add with environment variables
+gemini mcp add weather-server -e API_KEY=secret -e DEBUG=true uv -- run --with fastmcp fastmcp run server.py
+
+# Add with specific scope (user, or project)
+gemini mcp add my-server --scope user uv -- run --with fastmcp fastmcp run server.py
+```
+
+You can also manually specify Python versions and project directories in your Gemini CLI commands:
+
+```bash
+# With specific Python version
+gemini mcp add ml-server uv -- run --python 3.11 --with fastmcp fastmcp run server.py
+
+# Within a project directory
+gemini mcp add project-server uv -- run --project /path/to/project --with fastmcp fastmcp run server.py
+```
+
+## Using the Server
+
+Once your server is installed, you can start using your FastMCP server with Gemini CLI.
+
+Try asking Gemini something like:
+
+> "Roll some dice for me"
+
+Gemini will automatically detect your `roll_dice` tool and use it to fulfill your request.
+
+Gemini CLI can now access all the tools and prompts you've defined in your FastMCP server. 
+
+If your server provides prompts, you can use them as slash commands with `/prompt_name`.
diff --git a/docs/integrations/gemini.mdx b/docs/integrations/gemini.mdx
new file mode 100644
index 0000000..1b17ab6
--- /dev/null
+++ b/docs/integrations/gemini.mdx
@@ -0,0 +1,108 @@
+---
+title: Gemini SDK 🤝 FastMCP
+sidebarTitle: Gemini SDK
+description: Connect FastMCP servers to the Google Gemini SDK
+icon: message-code
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+Google's Gemini API includes built-in support for MCP servers in their Python and JavaScript SDKs, allowing you to connect directly to MCP servers and use their tools seamlessly with Gemini models.
+
+## Gemini Python SDK
+
+Google's [Gemini Python SDK](https://ai.google.dev/gemini-api/docs) can use FastMCP clients directly.
+
+<Note>
+Google's MCP integration is currently experimental and available in the Python and JavaScript SDKs. The API automatically calls MCP tools when needed and can connect to both local and remote MCP servers.
+</Note>
+
+<Tip>
+Currently, Gemini's MCP support only accesses **tools** from MCP servers—it queries the `list_tools` endpoint and exposes those functions to the AI. Other MCP features like resources and prompts are not currently supported.
+</Tip>
+
+### Create a Server
+
+First, create a FastMCP server with the tools you want to expose. For this example, we'll create a server with a single tool that rolls dice.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+### Call the Server
+
+
+To use the Gemini API with MCP, you'll need to install the Google Generative AI SDK:
+
+```bash
+pip install google-genai
+```
+
+You'll also need to authenticate with Google. You can do this by setting the `GEMINI_API_KEY` environment variable. Consult the Gemini SDK documentation for more information.
+
+```bash
+export GEMINI_API_KEY="your-api-key"
+```
+
+Gemini's SDK interacts directly with the MCP client session. To call the server, you'll need to instantiate a FastMCP client, enter its connection context, and pass the client session to the Gemini SDK.
+
+```python {5, 9, 15}
+from fastmcp import Client
+from google import genai
+import asyncio
+
+mcp_client = Client("server.py")
+gemini_client = genai.Client()
+
+async def main():    
+    async with mcp_client:
+        response = await gemini_client.aio.models.generate_content(
+            model="gemini-2.0-flash",
+            contents="Roll 3 dice!",
+            config=genai.types.GenerateContentConfig(
+                temperature=0,
+                tools=[mcp_client.session],  # Pass the FastMCP client session
+            ),
+        )
+        print(response.text)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+If you run this code, you'll see output like:
+
+```text
+Okay, I rolled 3 dice and got a 5, 4, and 1.
+```
+
+### Remote & Authenticated Servers
+
+In the above example, we connected to our local server using `stdio` transport. Because we're using a FastMCP client, you can also connect to any local or remote MCP server, using any [transport](/clients/transports) or [auth](/clients/auth/oauth) method supported by FastMCP, simply by changing the client configuration.
+
+For example, to connect to a remote, authenticated server, you can use the following client:
+
+```python
+from fastmcp import Client
+from fastmcp.client.auth import BearerAuth
+
+mcp_client = Client(
+    "https://my-server.com/mcp/",
+    auth=BearerAuth("<your-token>"),
+)
+```
+
+The rest of the code remains the same.
+
+
diff --git a/docs/integrations/github.mdx b/docs/integrations/github.mdx
new file mode 100644
index 0000000..d493eb1
--- /dev/null
+++ b/docs/integrations/github.mdx
@@ -0,0 +1,175 @@
+---
+title: GitHub OAuth 🤝 FastMCP
+sidebarTitle: GitHub
+description: Secure your FastMCP server with GitHub OAuth
+icon: github
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.12.0" />
+
+This guide shows you how to secure your FastMCP server using **GitHub OAuth**. Since GitHub doesn't support Dynamic Client Registration, this integration uses the [**OAuth Proxy**](/servers/auth/oauth-proxy) pattern to bridge GitHub's traditional OAuth with MCP's authentication requirements.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+1. A **[GitHub Account](https://github.com/)** with access to create OAuth Apps
+2. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`)
+
+### Step 1: Create a GitHub OAuth App
+
+Create an OAuth App in your GitHub settings to get the credentials needed for authentication:
+
+<Steps>
+<Step title="Navigate to OAuth Apps">
+    Go to **Settings → Developer settings → OAuth Apps** in your GitHub account, or visit [github.com/settings/developers](https://github.com/settings/developers).
+    
+    Click **"New OAuth App"** to create a new application.
+</Step>
+
+<Step title="Configure Your OAuth App">
+    Fill in the application details:
+    
+    - **Application name**: Choose a name users will recognize (e.g., "My FastMCP Server")
+    - **Homepage URL**: Your application's homepage or documentation URL
+    - **Authorization callback URL**: Your server URL + `/auth/callback` (e.g., `http://localhost:8000/auth/callback`)
+    
+    <Warning>
+    The callback URL must match exactly. The default path is `/auth/callback`, but you can customize it using the `redirect_path` parameter. For local development, GitHub allows `http://localhost` URLs. For production, you must use HTTPS.
+    </Warning>
+    
+    <Tip>
+    If you want to use a custom callback path (e.g., `/auth/github/callback`), make sure to set the same path in both your GitHub OAuth App settings and the `redirect_path` parameter when configuring the GitHubProvider.
+    </Tip>
+</Step>
+
+<Step title="Save Your Credentials">
+    After creating the app, you'll see:
+    
+    - **Client ID**: A public identifier like `Ov23liAbcDefGhiJkLmN`
+    - **Client Secret**: Click "Generate a new client secret" and save the value securely
+    
+    <Tip>
+    Store these credentials securely. Never commit them to version control. Use environment variables or a secrets manager in production.
+    </Tip>
+</Step>
+</Steps>
+
+### Step 2: FastMCP Configuration
+
+Create your FastMCP server using the `GitHubProvider`, which handles GitHub's OAuth quirks automatically:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.github import GitHubProvider
+
+# The GitHubProvider handles GitHub's token format and validation
+auth_provider = GitHubProvider(
+    client_id="Ov23liAbcDefGhiJkLmN",  # Your GitHub OAuth App Client ID
+    client_secret="github_pat_...",     # Your GitHub OAuth App Client Secret
+    base_url="http://localhost:8000",   # Must match your OAuth App configuration
+    # redirect_path="/auth/callback"   # Default value, customize if needed
+)
+
+mcp = FastMCP(name="GitHub Secured App", auth=auth_provider)
+
+# Add a protected tool to test authentication
+@mcp.tool
+async def get_user_info() -> dict:
+    """Returns information about the authenticated GitHub user."""
+    from fastmcp.server.dependencies import get_access_token
+    
+    token = get_access_token()
+    # The GitHubProvider stores user data in token claims
+    return {
+        "github_user": token.claims.get("login"),
+        "name": token.claims.get("name"),
+        "email": token.claims.get("email")
+    }
+```
+
+## Testing
+
+### Running the Server
+
+Start your FastMCP server with HTTP transport to enable OAuth flows:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Your server is now running and protected by GitHub OAuth authentication.
+
+### Testing with a Client
+
+Create a test client that authenticates with your GitHub-protected server:
+
+```python test_client.py
+from fastmcp import Client
+import asyncio
+
+async def main():
+    # The client will automatically handle GitHub OAuth
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        # First-time connection will open GitHub login in your browser
+        print("✓ Authenticated with GitHub!")
+        
+        # Test the protected tool
+        result = await client.call_tool("get_user_info")
+        print(f"GitHub user: {result.data['github_user']}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+1. Your browser will open to GitHub's authorization page
+2. After you authorize the app, you'll be redirected back
+3. The client receives the token and can make authenticated requests
+
+<Info>
+The client caches tokens locally, so you won't need to re-authenticate for subsequent runs unless the token expires or you explicitly clear the cache.
+</Info>
+
+## Production Configuration
+
+<VersionBadge version="2.13.0" />
+
+For production deployments with persistent token management across server restarts, configure `jwt_signing_key` and `client_storage`:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.github import GitHubProvider
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+# Production setup with encrypted persistent token storage
+auth_provider = GitHubProvider(
+    client_id="Ov23liAbcDefGhiJkLmN",
+    client_secret="github_pat_...",
+    base_url="https://your-production-domain.com",
+
+    # Production token management
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(
+            host=os.environ["REDIS_HOST"],
+            port=int(os.environ["REDIS_PORT"])
+        ),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+
+mcp = FastMCP(name="Production GitHub App", auth=auth_provider)
+```
+
+<Note>
+Parameters (`jwt_signing_key` and `client_storage`) work together to ensure tokens and client registrations survive server restarts. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without it, tokens are stored in plaintext. Store secrets in environment variables and use a persistent storage backend like Redis for distributed deployments.
+
+For complete details on these parameters, see the [OAuth Proxy documentation](/servers/auth/oauth-proxy#configuration-parameters).
+</Note>
diff --git a/docs/integrations/google.mdx b/docs/integrations/google.mdx
new file mode 100644
index 0000000..17d49d1
--- /dev/null
+++ b/docs/integrations/google.mdx
@@ -0,0 +1,189 @@
+---
+title: Google OAuth 🤝 FastMCP
+sidebarTitle: Google
+description: Secure your FastMCP server with Google OAuth
+icon: google
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.12.0" />
+
+This guide shows you how to secure your FastMCP server using **Google OAuth**. Since Google doesn't support Dynamic Client Registration, this integration uses the [**OAuth Proxy**](/servers/auth/oauth-proxy) pattern to bridge Google's traditional OAuth with MCP's authentication requirements.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+1. A **[Google Cloud Account](https://console.cloud.google.com/)** with access to create OAuth 2.0 Client IDs
+2. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`)
+
+### Step 1: Create a Google OAuth 2.0 Client ID
+
+Create an OAuth 2.0 Client ID in your Google Cloud Console to get the credentials needed for authentication:
+
+<Steps>
+<Step title="Navigate to OAuth Consent Screen">
+    Go to the [Google Cloud Console](https://console.cloud.google.com/apis/credentials) and select your project (or create a new one).
+    
+    First, configure the OAuth consent screen by navigating to **APIs & Services → OAuth consent screen**. Choose "External" for testing or "Internal" for G Suite organizations.
+</Step>
+
+<Step title="Create OAuth 2.0 Client ID">
+    Navigate to **APIs & Services → Credentials** and click **"+ CREATE CREDENTIALS"** → **"OAuth client ID"**.
+    
+    Configure your OAuth client:
+    
+    - **Application type**: Web application
+    - **Name**: Choose a descriptive name (e.g., "FastMCP Server")
+    - **Authorized JavaScript origins**: Add your server's base URL (e.g., `http://localhost:8000`)
+    - **Authorized redirect URIs**: Add your server URL + `/auth/callback` (e.g., `http://localhost:8000/auth/callback`)
+    
+    <Warning>
+    The redirect URI must match exactly. The default path is `/auth/callback`, but you can customize it using the `redirect_path` parameter. For local development, Google allows `http://localhost` URLs with various ports. For production, you must use HTTPS.
+    </Warning>
+    
+    <Tip>
+    If you want to use a custom callback path (e.g., `/auth/google/callback`), make sure to set the same path in both your Google OAuth Client settings and the `redirect_path` parameter when configuring the GoogleProvider.
+    </Tip>
+</Step>
+
+<Step title="Save Your Credentials">
+    After creating the client, you'll receive:
+    
+    - **Client ID**: A string ending in `.apps.googleusercontent.com`
+    - **Client Secret**: A string starting with `GOCSPX-`
+    
+    Download the JSON credentials or copy these values securely.
+    
+    <Tip>
+    Store these credentials securely. Never commit them to version control. Use environment variables or a secrets manager in production.
+    </Tip>
+</Step>
+</Steps>
+
+### Step 2: FastMCP Configuration
+
+Create your FastMCP server using the `GoogleProvider`, which handles Google's OAuth flow automatically:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.google import GoogleProvider
+
+# The GoogleProvider handles Google's token format and validation
+auth_provider = GoogleProvider(
+    client_id="123456789.apps.googleusercontent.com",  # Your Google OAuth Client ID
+    client_secret="GOCSPX-abc123...",                  # Your Google OAuth Client Secret
+    base_url="http://localhost:8000",                  # Must match your OAuth configuration
+    required_scopes=[                                  # Request user information
+        "openid",
+        "https://www.googleapis.com/auth/userinfo.email",
+    ],
+    # redirect_path="/auth/callback"                  # Default value, customize if needed
+)
+
+mcp = FastMCP(name="Google Secured App", auth=auth_provider)
+
+# Add a protected tool to test authentication
+@mcp.tool
+async def get_user_info() -> dict:
+    """Returns information about the authenticated Google user."""
+    from fastmcp.server.dependencies import get_access_token
+    
+    token = get_access_token()
+    # The GoogleProvider stores user data in token claims
+    return {
+        "google_id": token.claims.get("sub"),
+        "email": token.claims.get("email"),
+        "name": token.claims.get("name"),
+        "picture": token.claims.get("picture"),
+        "locale": token.claims.get("locale")
+    }
+```
+
+## Testing
+
+### Running the Server
+
+Start your FastMCP server with HTTP transport to enable OAuth flows:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Your server is now running and protected by Google OAuth authentication.
+
+### Testing with a Client
+
+Create a test client that authenticates with your Google-protected server:
+
+```python test_client.py
+from fastmcp import Client
+import asyncio
+
+async def main():
+    # The client will automatically handle Google OAuth
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        # First-time connection will open Google login in your browser
+        print("✓ Authenticated with Google!")
+        
+        # Test the protected tool
+        result = await client.call_tool("get_user_info")
+        print(f"Google user: {result['email']}")
+        print(f"Name: {result['name']}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+1. Your browser will open to Google's authorization page
+2. Sign in with your Google account and grant the requested permissions
+3. After authorization, you'll be redirected back
+4. The client receives the token and can make authenticated requests
+
+<Info>
+The client caches tokens locally, so you won't need to re-authenticate for subsequent runs unless the token expires or you explicitly clear the cache.
+</Info>
+
+## Production Configuration
+
+<VersionBadge version="2.13.0" />
+
+For production deployments with persistent token management across server restarts, configure `jwt_signing_key` and `client_storage`:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.google import GoogleProvider
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+# Production setup with encrypted persistent token storage
+auth_provider = GoogleProvider(
+    client_id="123456789.apps.googleusercontent.com",
+    client_secret="GOCSPX-abc123...",
+    base_url="https://your-production-domain.com",
+    required_scopes=["openid", "https://www.googleapis.com/auth/userinfo.email"],
+
+    # Production token management
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(
+            host=os.environ["REDIS_HOST"],
+            port=int(os.environ["REDIS_PORT"])
+        ),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+
+mcp = FastMCP(name="Production Google App", auth=auth_provider)
+```
+
+<Note>
+Parameters (`jwt_signing_key` and `client_storage`) work together to ensure tokens and client registrations survive server restarts. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without it, tokens are stored in plaintext. Store secrets in environment variables and use a persistent storage backend like Redis for distributed deployments.
+
+For complete details on these parameters, see the [OAuth Proxy documentation](/servers/auth/oauth-proxy#configuration-parameters).
+</Note>
\ No newline at end of file
diff --git a/docs/integrations/goose.mdx b/docs/integrations/goose.mdx
new file mode 100644
index 0000000..fc2ff8e
--- /dev/null
+++ b/docs/integrations/goose.mdx
@@ -0,0 +1,178 @@
+---
+title: Goose 🤝 FastMCP
+sidebarTitle: Goose
+description: Install and use FastMCP servers in Goose
+icon: message-smile
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+import { LocalFocusTip } from "/snippets/local-focus.mdx"
+
+<LocalFocusTip />
+
+[Goose](https://block.github.io/goose/) is an open-source AI agent from Block that supports MCP servers as extensions. FastMCP can install your server directly into Goose using its deeplink protocol — one command opens Goose with an install dialog ready to go.
+
+## Requirements
+
+This integration uses Goose's deeplink protocol to register your server as a STDIO extension running via `uvx`. You must have Goose installed on your system for the deeplink to open automatically.
+
+For remote deployments, configure your FastMCP server with HTTP transport and add it to Goose directly using `goose configure` or the config file.
+
+## Create a Server
+
+The examples in this guide will use the following simple dice-rolling server, saved as `server.py`.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Install the Server
+
+### FastMCP CLI
+<VersionBadge version="3.0.0" />
+
+The easiest way to install a FastMCP server in Goose is using the `fastmcp install goose` command. This generates a `goose://` deeplink and opens it, prompting Goose to install the server.
+
+```bash
+fastmcp install goose server.py
+```
+
+The install command supports the same `file.py:object` notation as the `run` command. If no object is specified, it will automatically look for a FastMCP server object named `mcp`, `server`, or `app` in your file:
+
+```bash
+# These are equivalent if your server object is named 'mcp'
+fastmcp install goose server.py
+fastmcp install goose server.py:mcp
+
+# Use explicit object name if your server has a different name
+fastmcp install goose server.py:my_custom_server
+```
+
+Under the hood, the generated command uses `uvx` to run your server in an isolated environment. Goose requires `uvx` rather than `uv run`, so the install produces a command like:
+
+```bash
+uvx --with pandas fastmcp run /path/to/server.py
+```
+
+#### Dependencies
+
+Use the `--with` flag to specify additional packages your server needs:
+
+```bash
+fastmcp install goose server.py --with pandas --with requests
+```
+
+Alternatively, you can use a `fastmcp.json` configuration file (recommended):
+
+```json fastmcp.json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "dependencies": ["pandas", "requests"]
+  }
+}
+```
+
+#### Python Version
+
+Use `--python` to specify which Python version your server should use:
+
+```bash
+fastmcp install goose server.py --python 3.11
+```
+
+<Note>
+The Goose install uses `uvx`, which does not support `--project`, `--with-requirements`, or `--with-editable`. If you need these options, use `fastmcp install mcp-json` to generate a full configuration and add it to Goose manually.
+</Note>
+
+#### Environment Variables
+
+Goose's deeplink protocol does not support environment variables. If your server needs them (like API keys), you have two options:
+
+1. **Configure after install**: Run `goose configure` and add environment variables to the extension.
+2. **Manual config**: Use `fastmcp install mcp-json` to generate the full configuration, then add it to `~/.config/goose/config.yaml` with the `envs` field.
+
+### Manual Configuration
+
+For more control, you can manually edit Goose's configuration file at `~/.config/goose/config.yaml`:
+
+```yaml
+extensions:
+  dice-roller:
+    name: Dice Roller
+    cmd: uvx
+    args: [fastmcp, run, /path/to/server.py]
+    enabled: true
+    type: stdio
+    timeout: 300
+```
+
+#### Dependencies
+
+When manually configuring, add packages using `--with` flags in the args:
+
+```yaml
+extensions:
+  dice-roller:
+    name: Dice Roller
+    cmd: uvx
+    args: [--with, pandas, --with, requests, fastmcp, run, /path/to/server.py]
+    enabled: true
+    type: stdio
+    timeout: 300
+```
+
+#### Environment Variables
+
+Environment variables can be specified in the `envs` field:
+
+```yaml
+extensions:
+  weather-server:
+    name: Weather Server
+    cmd: uvx
+    args: [fastmcp, run, /path/to/weather_server.py]
+    enabled: true
+    envs:
+      API_KEY: your-api-key
+      DEBUG: "true"
+    type: stdio
+    timeout: 300
+```
+
+You can also use `goose configure` to add extensions interactively, which prompts for environment variables.
+
+<Warning>
+**`uvx` (from `uv`) must be installed and available in your system PATH**. Goose uses `uvx` to run Python-based extensions in isolated environments.
+</Warning>
+
+## Using the Server
+
+Once your server is installed, you can start using your FastMCP server with Goose.
+
+Try asking Goose something like:
+
+> "Roll some dice for me"
+
+Goose will automatically detect your `roll_dice` tool and use it to fulfill your request, returning something like:
+
+> 🎲 Here are your dice rolls: 4, 6, 4
+>
+> You rolled 3 dice with a total of 14!
+
+Goose can now access all the tools, resources, and prompts you've defined in your FastMCP server.
diff --git a/docs/integrations/huggingface.mdx b/docs/integrations/huggingface.mdx
new file mode 100644
index 0000000..5579402
--- /dev/null
+++ b/docs/integrations/huggingface.mdx
@@ -0,0 +1,304 @@
+---
+title: Hugging Face OAuth 🤝 FastMCP
+sidebarTitle: Hugging Face
+description: Secure your FastMCP server with Hugging Face OAuth
+icon: hugging-face
+iconType: brands
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="3.4.3" />
+
+This guide shows you how to secure your FastMCP server using **Hugging Face OAuth**.
+The `HuggingFaceProvider` uses FastMCP's [OAuth Proxy](/servers/auth/oauth-proxy)
+pattern with Hugging Face's OAuth and OpenID Connect endpoints. It works with
+manually created confidential apps, public PKCE apps, and Client ID Metadata
+Documents (CIMD).
+
+When deploying your MCP server to Hugging Face Spaces, Spaces can create and
+manage the OAuth app for you.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+
+1. A **[Hugging Face account](https://huggingface.co/join)** with access to create OAuth apps
+2. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`)
+
+### Step 1: Create a Hugging Face OAuth app
+
+Create an OAuth app from your [Hugging Face application settings](https://huggingface.co/settings/applications/new).
+For details, see Hugging Face's [OAuth documentation](https://huggingface.co/docs/hub/oauth).
+
+<Steps>
+<Step title="Create the OAuth app">
+    Go to your [Hugging Face application settings](https://huggingface.co/settings/applications/new)
+    and create a new OAuth application.
+
+    Choose a name users will recognize, then configure the redirect URL for
+    your FastMCP server:
+
+    - Development: `http://localhost:8000/auth/callback`
+    - Production: `https://your-domain.com/auth/callback`
+
+    <Warning>
+    The redirect URL must match exactly. The default path is `/auth/callback`,
+    but you can customize it using the `redirect_path` parameter. For
+    production, use HTTPS.
+    </Warning>
+</Step>
+
+<Step title="Save your credentials">
+    After creating the app, save:
+
+    - **Client ID**: The public identifier for your Hugging Face OAuth app
+    - **Client Secret**: The app secret, if you created a confidential app
+
+    <Tip>
+    Store the client secret securely. Never commit it to version control. Use
+    environment variables or a secrets manager in production.
+    </Tip>
+</Step>
+</Steps>
+
+### Step 2: Configure FastMCP
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.huggingface import HuggingFaceProvider
+
+# The HuggingFaceProvider handles Hugging Face's opaque OAuth access tokens
+# and stores user data in token claims.
+auth_provider = HuggingFaceProvider(
+    client_id="your-huggingface-client-id",        # Your Hugging Face OAuth app client ID
+    client_secret="your-huggingface-client-secret", # Your Hugging Face OAuth app client secret
+    base_url="http://localhost:8000",              # Must match your OAuth configuration
+    required_scopes=["openid", "profile"],         # Default value
+    # redirect_path="/auth/callback"               # Default value, customize if needed
+)
+
+mcp = FastMCP(name="Hugging Face Secured App", auth=auth_provider)
+
+
+# Add a protected tool to test authentication
+@mcp.tool
+async def get_user_info() -> dict:
+    """Returns information about the authenticated Hugging Face user."""
+    from fastmcp.server.dependencies import get_access_token
+
+    token = get_access_token()
+    return {
+        "subject": token.claims.get("sub"),
+        "username": token.claims.get("preferred_username"),
+        "profile": token.claims.get("profile"),
+    }
+```
+
+## Public OAuth apps, DCR, and CIMD
+
+Hugging Face supports public OAuth apps (no client secret). For public apps,
+omit `client_secret` and provide a `jwt_signing_key` so FastMCP can sign its
+own proxy tokens:
+
+```python
+auth_provider = HuggingFaceProvider(
+    client_id="your-public-huggingface-client-id",
+    base_url="http://localhost:8000",
+    jwt_signing_key="replace-with-a-secure-secret",
+)
+```
+
+MCP clients can use Dynamic Client Registration with your FastMCP server. The
+`HuggingFaceProvider` inherits FastMCP's OAuth Proxy behavior, which handles
+client registration locally and forwards authorization to Hugging Face using
+your configured Hugging Face OAuth app. In other words, MCP clients register
+with FastMCP, while FastMCP uses your Hugging Face `client_id` and optional
+`client_secret` for the upstream OAuth flow.
+
+You can also use a Client ID Metadata Document URL as the `client_id` when your
+client metadata is hosted at a stable HTTPS URL:
+
+```python
+auth_provider = HuggingFaceProvider(
+    client_id="https://your-client.example/.well-known/oauth-cimd",
+    base_url="http://localhost:8000",
+    jwt_signing_key="replace-with-a-secure-secret",
+)
+```
+
+## Testing
+
+### Running the Server
+
+Start your server with HTTP transport:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Your server is now running and protected by Hugging Face OAuth authentication.
+
+### Testing with a Client
+
+Create a test client that authenticates with your Hugging Face-protected server:
+
+```python test_client.py
+import asyncio
+from fastmcp import Client
+
+
+async def main():
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        result = await client.call_tool("get_user_info")
+        print(result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+
+1. Your browser will open to Hugging Face's authorization page
+2. Sign in with your Hugging Face account and grant the requested permissions
+3. After authorization, you'll be redirected back
+4. The client receives the token and can make authenticated requests
+
+<Info>
+The client caches tokens locally, so you won't need to re-authenticate for
+subsequent runs unless the token expires or you explicitly clear the cache.
+</Info>
+
+## Hugging Face Spaces
+
+When deploying to [Hugging Face Spaces](https://huggingface.co/docs/hub/spaces-oauth),
+Spaces can create and manage the OAuth app for you. Add OAuth metadata to your
+Space README:
+
+```yaml
+---
+title: FastMCP Hugging Face OAuth
+sdk: docker
+hf_oauth: true
+hf_oauth_expiration_minutes: 480
+hf_oauth_scopes:
+  - email
+  - inference-api
+---
+```
+
+Spaces provide `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`, `OAUTH_SCOPES`,
+`OPENID_PROVIDER_URL`, and `SPACE_HOST` environment variables:
+
+```python
+import os
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.huggingface import HuggingFaceProvider
+from fastmcp.utilities.auth import parse_scopes
+
+base_url = f"https://{os.environ['SPACE_HOST']}"
+
+auth_provider = HuggingFaceProvider(
+    client_id=os.environ["OAUTH_CLIENT_ID"],
+    client_secret=os.environ["OAUTH_CLIENT_SECRET"],
+    base_url=base_url,
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    required_scopes=parse_scopes(os.environ.get("OAUTH_SCOPES")) or ["openid", "profile"],
+)
+
+mcp = FastMCP(name="Hugging Face Space App", auth=auth_provider)
+```
+
+Set `JWT_SIGNING_KEY` as a Space secret.
+
+## Hugging Face scopes
+
+The default scopes are `openid` and `profile`. Add more scopes when your tools
+need Hub capabilities:
+
+| Scope | Description |
+|-------|-------------|
+| `email` | Access the user's email address |
+| `read-billing` | Know whether the user has a payment method set up |
+| `read-repos` | Read the user's personal repositories |
+| `gated-repos` | Read public gated repositories the user can access |
+| `contribute-repos` | Create repositories and access app-created repositories |
+| `write-repos` | Read and write the user's personal repositories |
+| `manage-repos` | Full repository access, including creation and deletion |
+| `read-collections` | Read the user's personal collections |
+| `write-collections` | Read and write the user's personal collections, including collection creation and deletion |
+| `inference-api` | Use Hugging Face Inference Providers as the user |
+| `jobs` | Run Hugging Face Jobs |
+| `webhooks` | Manage webhooks |
+| `write-discussions` | Open discussions and pull requests, and interact with discussions |
+
+```python
+auth_provider = HuggingFaceProvider(
+    client_id="your-huggingface-client-id",
+    client_secret="your-huggingface-client-secret",
+    base_url="https://your-domain.com",
+    required_scopes=["openid", "profile", "inference-api", "jobs"],
+)
+```
+
+For organization resources, use Hugging Face's normal OAuth organization grant
+flow. If you need a specific organization, pass Hugging Face's `orgIds`
+authorization parameter. The value is the organization ID from the
+`organizations.sub` field in the Hugging Face userinfo response:
+
+```python
+auth_provider = HuggingFaceProvider(
+    client_id="your-huggingface-client-id",
+    client_secret="your-huggingface-client-secret",
+    base_url="https://your-domain.com",
+    extra_authorize_params={"orgIds": "your-org-id"},
+)
+```
+
+## Production Configuration
+
+For production deployments with persistent token management across server
+restarts, configure `jwt_signing_key` and `client_storage`:
+
+```python server.py
+import os
+from cryptography.fernet import Fernet
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.huggingface import HuggingFaceProvider
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+
+# Production setup with encrypted persistent token storage
+auth_provider = HuggingFaceProvider(
+    client_id="your-huggingface-client-id",
+    client_secret=os.environ["HUGGINGFACE_CLIENT_SECRET"],
+    base_url="https://your-production-domain.com",
+    required_scopes=["openid", "profile", "email"],
+
+    # Production token management
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(
+            host=os.environ["REDIS_HOST"],
+            port=int(os.environ["REDIS_PORT"])
+        ),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+
+mcp = FastMCP(name="Production Hugging Face App", auth=auth_provider)
+```
+
+<Note>
+Parameters (`jwt_signing_key` and `client_storage`) work together to ensure
+tokens and client registrations survive server restarts. **Wrap your storage in
+`FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without
+it, tokens are stored in plaintext. Store secrets in environment variables and
+use a persistent storage backend like Redis for distributed deployments.
+
+For complete details on these parameters, see the [OAuth Proxy documentation](/servers/auth/oauth-proxy#configuration-parameters).
+</Note>
diff --git a/docs/integrations/images/authkit/enable_dcr.png b/docs/integrations/images/authkit/enable_dcr.png
new file mode 100644
index 0000000..e5942f6
Binary files /dev/null and b/docs/integrations/images/authkit/enable_dcr.png differ
diff --git a/docs/integrations/images/oci/ociaddapplication.png b/docs/integrations/images/oci/ociaddapplication.png
new file mode 100644
index 0000000..690f8d3
Binary files /dev/null and b/docs/integrations/images/oci/ociaddapplication.png differ
diff --git a/docs/integrations/images/oci/ocieditdomainsettings.png b/docs/integrations/images/oci/ocieditdomainsettings.png
new file mode 100644
index 0000000..08812ba
Binary files /dev/null and b/docs/integrations/images/oci/ocieditdomainsettings.png differ
diff --git a/docs/integrations/images/oci/ocieditdomainsettingsbutton.png b/docs/integrations/images/oci/ocieditdomainsettingsbutton.png
new file mode 100644
index 0000000..3954dab
Binary files /dev/null and b/docs/integrations/images/oci/ocieditdomainsettingsbutton.png differ
diff --git a/docs/integrations/images/oci/ocioauthconfiguration.png b/docs/integrations/images/oci/ocioauthconfiguration.png
new file mode 100644
index 0000000..f007821
Binary files /dev/null and b/docs/integrations/images/oci/ocioauthconfiguration.png differ
diff --git a/docs/integrations/images/permit/abac_condition_example.png b/docs/integrations/images/permit/abac_condition_example.png
new file mode 100644
index 0000000..a5592ab
Binary files /dev/null and b/docs/integrations/images/permit/abac_condition_example.png differ
diff --git a/docs/integrations/images/permit/abac_policy_example.png b/docs/integrations/images/permit/abac_policy_example.png
new file mode 100644
index 0000000..bd4b5cf
Binary files /dev/null and b/docs/integrations/images/permit/abac_policy_example.png differ
diff --git a/docs/integrations/images/permit/policy_mapping.png b/docs/integrations/images/permit/policy_mapping.png
new file mode 100644
index 0000000..d100b1e
Binary files /dev/null and b/docs/integrations/images/permit/policy_mapping.png differ
diff --git a/docs/integrations/images/permit/role_assignement.png b/docs/integrations/images/permit/role_assignement.png
new file mode 100644
index 0000000..c65e341
Binary files /dev/null and b/docs/integrations/images/permit/role_assignement.png differ
diff --git a/docs/integrations/keycloak.mdx b/docs/integrations/keycloak.mdx
new file mode 100644
index 0000000..22d61f1
--- /dev/null
+++ b/docs/integrations/keycloak.mdx
@@ -0,0 +1,141 @@
+---
+title: Keycloak OAuth 🤝 FastMCP
+sidebarTitle: Keycloak
+description: Secure your FastMCP server with Keycloak OAuth
+icon: shield-check
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="3.2.4" />
+
+This guide shows you how to secure your FastMCP server using **Keycloak OAuth**. This integration uses the [**Remote OAuth**](/servers/auth/remote-oauth) pattern with Dynamic Client Registration (DCR), where Keycloak handles user login and your FastMCP server validates the tokens.
+
+<Note>
+**Keycloak 26.6.0 or later is required.** Earlier versions had a DCR incompatibility with MCP clients ([PR #45309](https://github.com/keycloak/keycloak/pull/45309)) that is fixed in 26.6.0.
+</Note>
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+1. A running **[Keycloak](https://keycloak.org/)** instance (e.g., `http://localhost:8080`)
+2. A Keycloak realm with **Dynamic Client Registration** enabled and a trusted host policy that allows your server URL (e.g., `http://localhost:8000/*`)
+3. Your FastMCP server's public URL (e.g., `http://localhost:8000`)
+
+### FastMCP Configuration
+
+Create your FastMCP server and use `KeycloakAuthProvider` to handle OAuth:
+
+```python server.py
+import os
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.keycloak import KeycloakAuthProvider
+from fastmcp.server.dependencies import get_access_token
+
+auth = KeycloakAuthProvider(
+    realm_url=os.getenv("KEYCLOAK_REALM_URL") or "http://localhost:8080/realms/myrealm",
+    base_url="http://localhost:8000",
+    # audience="http://localhost:8000",  # Recommended for production
+)
+
+mcp = FastMCP("Keycloak Example Server", auth=auth)
+
+
+@mcp.tool
+async def get_access_token_claims() -> dict:
+    """Get the authenticated user's access token claims."""
+    token = get_access_token()
+    return {
+        "sub": token.claims.get("sub"),
+        "scope": token.claims.get("scope"),
+        "azp": token.claims.get("azp"),
+    }
+```
+
+<Warning>
+**Production security**: Always configure the `audience` parameter in production. Without it, your server accepts tokens issued for any audience. Configure Keycloak audience mappers and set `audience` to your server's base URL to ensure tokens are specifically intended for your server.
+</Warning>
+
+## Local Development
+
+Local infrastructure tooling is deliberately kept out of the FastMCP core library to keep auth integrations slim and the associated maintenance burden as low as possible. That said, Keycloak is a popular identity provider for local development and testing, so a dedicated FastMCP-compatible setup blueprint lives in the companion project [**fastmcp-keycloak-local**](https://github.com/stephaneberle9/fastmcp-keycloak-local).
+
+It provides everything needed to develop and test FastMCP servers with Keycloak OAuth locally: a Docker-based Keycloak setup with a pre-configured `fastmcp` realm (Dynamic Client Registration enabled, test user included), cross-platform start scripts, and integration guides for the MCP Inspector, Claude Desktop, and Claude Code CLI.
+
+## Testing
+
+### Running the Server
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+### Testing with a Client
+
+```python client.py
+import asyncio
+from fastmcp import Client
+
+async def main():
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        print("✓ Authenticated with Keycloak!")
+        result = await client.call_tool("get_access_token_claims")
+        print(f"sub: {result.data.get('sub', 'N/A')}")
+
+asyncio.run(main())
+```
+
+On first run, your browser will open to Keycloak's authorization page. After login, the client receives a token and caches it for subsequent runs.
+
+## Features
+
+### JWT Token Validation
+
+- **Signature Verification**: Validates tokens against Keycloak's JWKS endpoint
+- **Expiration Checking**: Automatically rejects expired tokens
+- **Issuer Validation**: Ensures tokens come from your specific Keycloak realm
+- **Scope Enforcement**: Verifies required OAuth scopes are present
+- **Audience Validation**: Optional validation that tokens target your server (configure `audience`)
+
+### User Claims
+
+Access user information from Keycloak JWT tokens:
+
+```python
+from fastmcp.server.dependencies import get_access_token
+
+@mcp.tool
+async def admin_only_tool() -> str:
+    """A tool only available to admin users."""
+    token = get_access_token()
+    roles = token.claims.get("realm_access", {}).get("roles", [])
+    if "admin" not in roles:
+        raise ValueError("This tool requires admin access")
+    return "Admin access granted!"
+```
+
+## Advanced Configuration
+
+### Custom Token Verifier
+
+```python
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.server.auth.providers.keycloak import KeycloakAuthProvider
+
+custom_verifier = JWTVerifier(
+    jwks_uri="http://localhost:8080/realms/myrealm/protocol/openid-connect/certs",
+    issuer="http://localhost:8080/realms/myrealm",
+    audience="my-resource-server",
+    required_scopes=["api:read", "api:write"],
+)
+
+auth = KeycloakAuthProvider(
+    realm_url="http://localhost:8080/realms/myrealm",
+    base_url="http://localhost:8000",
+    token_verifier=custom_verifier,
+)
+```
diff --git a/docs/integrations/mcp-json-configuration.mdx b/docs/integrations/mcp-json-configuration.mdx
new file mode 100644
index 0000000..fec8ffc
--- /dev/null
+++ b/docs/integrations/mcp-json-configuration.mdx
@@ -0,0 +1,514 @@
+---
+title: MCP JSON Configuration 🤝 FastMCP
+sidebarTitle: MCP.json
+description: Generate standard MCP configuration files for any compatible client
+icon: brackets-curly
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.10.3" />
+
+FastMCP can generate standard MCP JSON configuration files that work with any MCP-compatible client including Claude Desktop, VS Code, Cursor, and other applications that support the Model Context Protocol.
+
+## MCP JSON Configuration Standard
+
+The MCP JSON configuration format is an **emergent standard** that has developed across the MCP ecosystem. This format defines how MCP clients should configure and launch MCP servers, providing a consistent way to specify server commands, arguments, and environment variables.
+
+### Configuration Structure
+
+The standard uses a `mcpServers` object where each key represents a server name and the value contains the server's configuration:
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "executable",
+      "args": ["arg1", "arg2"],
+      "env": {
+        "VAR": "value"
+      }
+    }
+  }
+}
+```
+
+### Server Configuration Fields
+
+#### `command` (required)
+The executable command to run the MCP server. This should be an absolute path or a command available in the system PATH.
+
+```json
+{
+  "command": "python"
+}
+```
+
+#### `args` (optional)
+An array of command-line arguments passed to the server executable. Arguments are passed in order.
+
+```json
+{
+  "args": ["server.py", "--verbose", "--port", "8080"]
+}
+```
+
+#### `env` (optional)
+An object containing environment variables to set when launching the server. All values must be strings.
+
+```json
+{
+  "env": {
+    "API_KEY": "secret-key",
+    "DEBUG": "true",
+    "PORT": "8080"
+  }
+}
+```
+
+### Client Adoption
+
+This format is widely adopted across the MCP ecosystem:
+
+- **Claude Desktop**: Uses `~/.claude/claude_desktop_config.json`
+- **Cursor**: Uses `~/.cursor/mcp.json`
+- **VS Code**: Uses workspace `.vscode/mcp.json`
+- **Other clients**: Many MCP-compatible applications follow this standard
+
+## Overview
+
+<Note>
+**For the best experience, use FastMCP's first-class integrations:** [`fastmcp install claude-code`](/integrations/claude-code), [`fastmcp install claude-desktop`](/integrations/claude-desktop), or [`fastmcp install cursor`](/integrations/cursor). Use MCP JSON generation for advanced use cases and unsupported clients.
+</Note>
+
+The `fastmcp install mcp-json` command generates configuration in the standard `mcpServers` format used across the MCP ecosystem. This is useful when:
+
+- **Working with unsupported clients** - Any MCP client not directly integrated with FastMCP
+- **CI/CD environments** - Automated configuration generation for deployments  
+- **Configuration sharing** - Easy distribution of server setups to team members
+- **Custom tooling** - Integration with your own MCP management tools
+- **Manual setup** - When you prefer to manually configure your MCP client
+
+## Basic Usage
+
+Generate configuration and output to stdout (useful for piping):
+
+```bash
+fastmcp install mcp-json server.py
+```
+
+This outputs the server configuration JSON with the server name as the root key:
+
+```json
+{
+  "My Server": {
+    "command": "uv",
+    "args": [
+      "run",
+      "--with",
+      "fastmcp", 
+      "fastmcp",
+      "run",
+      "/absolute/path/to/server.py"
+    ]
+  }
+}
+```
+
+To use this in a client configuration file, add it to the `mcpServers` object in your client's configuration:
+
+```json
+{
+  "mcpServers": {
+    "My Server": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--with",
+        "fastmcp", 
+        "fastmcp",
+        "run",
+        "/absolute/path/to/server.py"
+      ]
+    }
+  }
+}
+```
+
+<Note>
+When using `--python`, `--project`, or `--with-requirements`, the generated configuration will include these options in the `uv run` command, ensuring your server runs with the correct Python version and dependencies.
+</Note>
+
+<Note>
+Different MCP clients may have specific configuration requirements or formatting needs. Always consult your client's documentation to ensure proper integration.
+</Note>
+
+## Configuration Options
+
+### Server Naming
+
+```bash
+# Use server's built-in name (from FastMCP constructor)
+fastmcp install mcp-json server.py
+
+# Override with custom name
+fastmcp install mcp-json server.py --name "Custom Server Name"
+```
+
+### Dependencies
+
+Add Python packages your server needs:
+
+```bash
+# Single package
+fastmcp install mcp-json server.py --with pandas
+
+# Multiple packages  
+fastmcp install mcp-json server.py --with pandas --with requests --with httpx
+
+# Editable local package
+fastmcp install mcp-json server.py --with-editable ./my-package
+
+# From requirements file
+fastmcp install mcp-json server.py --with-requirements requirements.txt
+```
+
+You can also use a `fastmcp.json` configuration file (recommended):
+
+```json fastmcp.json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "dependencies": ["pandas", "matplotlib", "seaborn"]
+  }
+}
+```
+
+Then simply install with:
+```bash
+fastmcp install mcp-json fastmcp.json
+```
+
+
+### Environment Variables
+
+```bash
+# Individual environment variables
+fastmcp install mcp-json server.py \
+  --env API_KEY=your-secret-key \
+  --env DEBUG=true
+
+# Load from .env file
+fastmcp install mcp-json server.py --env-file .env
+```
+
+### Python Version and Project Directory
+
+Specify Python version or run within a specific project:
+
+```bash
+# Use specific Python version
+fastmcp install mcp-json server.py --python 3.11
+
+# Run within a project directory
+fastmcp install mcp-json server.py --project /path/to/project
+```
+
+### Server Object Selection
+
+Use the same `file.py:object` notation as other FastMCP commands:
+
+```bash
+# Auto-detects server object (looks for 'mcp', 'server', or 'app')
+fastmcp install mcp-json server.py
+
+# Explicit server object
+fastmcp install mcp-json server.py:my_custom_server
+```
+
+## Clipboard Integration
+
+Copy configuration directly to your clipboard for easy pasting:
+
+```bash
+fastmcp install mcp-json server.py --copy
+```
+
+<Note>
+The `--copy` flag requires the `pyperclip` Python package. If not installed, you'll see an error message with installation instructions.
+</Note>
+
+## Usage Examples
+
+### Basic Server
+
+```bash
+fastmcp install mcp-json dice_server.py
+```
+
+Output:
+```json
+{
+  "Dice Server": {
+    "command": "uv",
+    "args": [
+      "run",
+      "--with",
+      "fastmcp",
+      "fastmcp", 
+      "run",
+      "/home/user/dice_server.py"
+    ]
+  }
+}
+```
+
+### Production Server with Dependencies
+
+```bash
+fastmcp install mcp-json api_server.py \
+  --name "Production API Server" \
+  --with requests \
+  --with python-dotenv \
+  --env API_BASE_URL=https://api.example.com \
+  --env TIMEOUT=30
+```
+
+### Advanced Configuration
+
+```bash
+fastmcp install mcp-json ml_server.py \
+  --name "ML Analysis Server" \
+  --python 3.11 \
+  --with-requirements requirements.txt \
+  --project /home/user/ml-project \
+  --env GPU_DEVICE=0
+```
+
+Output:
+```json
+{
+  "Production API Server": {
+    "command": "uv",
+    "args": [
+      "run",
+      "--with",
+      "fastmcp",
+      "--with",
+      "python-dotenv", 
+      "--with",
+      "requests",
+      "fastmcp",
+      "run", 
+      "/home/user/api_server.py"
+    ],
+    "env": {
+      "API_BASE_URL": "https://api.example.com",
+      "TIMEOUT": "30"
+    }
+  }
+}
+```
+
+The advanced configuration example generates:
+```json
+{
+  "ML Analysis Server": {
+    "command": "uv",
+    "args": [
+      "run",
+      "--python",
+      "3.11",
+      "--project",
+      "/home/user/ml-project",
+      "--with",
+      "fastmcp",
+      "--with-requirements",
+      "requirements.txt",
+      "fastmcp",
+      "run",
+      "/home/user/ml_server.py"
+    ],
+    "env": {
+      "GPU_DEVICE": "0"
+    }
+  }
+}
+```
+
+### Pipeline Usage
+
+Save configuration to file:
+
+```bash
+fastmcp install mcp-json server.py > mcp-config.json
+```
+
+Use in shell scripts:
+
+```bash
+#!/bin/bash
+CONFIG=$(fastmcp install mcp-json server.py --name "CI Server")
+echo "$CONFIG" | jq '."CI Server".command'
+# Output: "uv"
+```
+
+### UV-Managed Project Dependencies
+
+For servers that live inside a uv-managed project (with `pyproject.toml`), use the `--project` flag to run within that project's environment:
+
+```bash
+fastmcp install mcp-json server.py --project .
+```
+
+Output:
+```json
+{
+  "My Server": {
+    "command": "uv",
+    "args": [
+      "run",
+      "--project",
+      "/absolute/path/to/project",
+      "--with",
+      "fastmcp",
+      "fastmcp",
+      "run",
+      "/absolute/path/to/project/server.py"
+    ]
+  }
+}
+```
+
+You can also use `fastmcp.json` with a local project:
+
+```json fastmcp.json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py"
+  },
+  "environment": {
+    "project": "."
+  }
+}
+```
+
+If your server needs additional packages beyond those in `pyproject.toml`, add them via the `dependencies` array or `--with`.
+
+### Published Packages with `uvx`
+
+If your team publishes MCP servers as pip packages, you can configure clients to run them with `uvx` directly instead of `uv run`. For example, if your package is called `my-mcp-server` and provides a CLI entry point of the same name:
+
+```json
+{
+  "mcpServers": {
+    "My Server": {
+      "command": "uvx",
+      "args": ["my-mcp-server"]
+    }
+  }
+}
+```
+
+If the package name differs from the CLI command (e.g., package `weather-mcp` with command `weather-server`):
+
+```json
+{
+  "mcpServers": {
+    "Weather": {
+      "command": "uvx",
+      "args": ["--from", "weather-mcp", "weather-server"]
+    }
+  }
+}
+```
+
+You can also pin Python versions or add extra dependencies:
+
+```json
+{
+  "mcpServers": {
+    "My Server": {
+      "command": "uvx",
+      "args": [
+        "--python", "3.12",
+        "--with", "requests",
+        "my-mcp-server"
+      ]
+    }
+  }
+}
+```
+
+<Note>
+`fastmcp install mcp-json` generates `uv run` configurations for local development. For published packages, you'll typically write the `uvx` configuration manually or generate it through your own packaging workflow.
+</Note>
+
+## Integration with MCP Clients
+
+The generated configuration works with any MCP-compatible application:
+
+### Claude Desktop
+<Note>
+**Prefer [`fastmcp install claude-desktop`](/integrations/claude-desktop)** for automatic installation. Use MCP JSON for advanced configuration needs.
+</Note>
+Copy the `mcpServers` object into `~/.claude/claude_desktop_config.json`
+
+### Cursor
+<Note>
+**Prefer [`fastmcp install cursor`](/integrations/cursor)** for automatic installation. Use MCP JSON for advanced configuration needs.
+</Note>
+Add to `~/.cursor/mcp.json`
+
+### VS Code  
+Add to your workspace's `.vscode/mcp.json` file
+
+### Custom Applications
+Use the JSON configuration with any application that supports the MCP protocol
+
+## Configuration Format
+
+The generated configuration outputs a server object with the server name as the root key:
+
+```json
+{
+  "<server-name>": {
+    "command": "<executable>",
+    "args": ["<arg1>", "<arg2>", "..."],
+    "env": {
+      "<ENV_VAR>": "<value>"
+    }
+  }
+}
+```
+
+To use this in an MCP client, add it to the client's `mcpServers` configuration object.
+
+**Fields:**
+- `command`: The executable to run (always `uv` for FastMCP servers)
+- `args`: Command-line arguments including dependencies and server path
+- `env`: Environment variables (only included if specified)
+
+<Warning>
+**All file paths in the generated configuration are absolute paths**. This ensures the configuration works regardless of the working directory when the MCP client starts the server.
+</Warning>
+
+## Requirements
+
+- **uv**: Must be installed and available in your system PATH
+- **pyperclip** (optional): Required only for `--copy` functionality
+
+Install uv if not already available:
+
+```bash
+# macOS
+brew install uv
+
+# Linux/Windows  
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
diff --git a/docs/integrations/oci.mdx b/docs/integrations/oci.mdx
new file mode 100644
index 0000000..02fa36d
--- /dev/null
+++ b/docs/integrations/oci.mdx
@@ -0,0 +1,248 @@
+---
+title: OCI IAM OAuth 🤝 FastMCP
+sidebarTitle: Oracle
+description: Secure your FastMCP server with OCI IAM OAuth
+icon: shield-check
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.13.0" />
+
+This guide shows you how to secure your FastMCP server using **OCI IAM OAuth**. Since OCI IAM doesn't support Dynamic Client Registration, this integration uses the [**OIDC Proxy**](/servers/auth/oidc-proxy) pattern to bridge OCI's traditional OAuth with MCP's authentication requirements.
+
+## Configuration
+
+### Prerequisites
+
+1. An OCI cloud Account with access to create an Integrated Application in an Identity Domain.
+2. Your FastMCP server's URL (For dev environments, it is http://localhost:8000. For PROD environments, it could be https://mcp.yourdomain.com)
+
+### Step 1: Make sure client access is enabled for JWK's URL
+
+<Steps>
+<Step title="Navigate to OCI IAM Domain Settings">
+
+    Login to OCI console (https://cloud.oracle.com for OCI commercial cloud).
+    From "Identity & Security" menu, open Domains page.
+    On the Domains list page, select the domain that you are using for MCP Authentication.
+    Open Settings tab. 
+    Click on "Edit Domain Settings" button.
+
+    <Frame>
+        <img src="/integrations/images/oci/ocieditdomainsettingsbutton.png" alt="OCI console showing the Edit Domain Settings button in the IAM Domain settings page" />
+    </Frame>
+</Step>
+
+<Step title="Update Domain Setting">
+
+    Enable "Configure client access" checkbox as shown in the screenshot.
+
+    <Frame>
+        <img src="/integrations/images/oci/ocieditdomainsettings.png" alt="OCI IAM Domain Settings" />
+    </Frame>
+</Step>
+</Steps>
+
+### Step 2: Create OAuth client for MCP server authentication
+
+Follow the Steps as mentioned below to create an OAuth client.
+
+<Steps>
+<Step title="Navigate to OCI IAM Integrated Applications">
+
+    Login to OCI console (https://cloud.oracle.com for OCI commercial cloud).
+    From "Identity & Security" menu, open Domains page.
+    On the Domains list page, select the domain in which you want to create MCP server OAuth client. If you need help finding the list page for the domain, see [Listing Identity Domains.](https://docs.oracle.com/en-us/iaas/Content/Identity/domains/to-view-identity-domains.htm#view-identity-domains).
+    On the details page, select Integrated applications. A list of applications in the domain is displayed.
+</Step>
+
+<Step title="Add an Integrated Application">
+
+    Select Add application.
+    In the Add application window, select Confidential Application.
+    Select Launch workflow.
+    In the Add application details page, Enter name and description as shown below.
+
+    <Frame>
+        <img src="/integrations/images/oci/ociaddapplication.png" alt="Adding a Confidential Integrated Application in OCI IAM Domain" />
+    </Frame>
+</Step>
+
+<Step title="Update OAuth Configuration for an Integrated Application">
+
+    Once the Integrated Application is created, Click on "OAuth configuration" tab.
+    Click on "Edit OAuth configuration" button.
+    Configure the application as OAuth client by selecting "Configure this application as a client now" radio button.
+    Select "Authorization code" grant type. If you are planning to use the same OAuth client application for token exchange, select "Client credentials" grant type as well. In the sample, we will use the same client.
+    For Authorization grant type, select redirect URL. In most cases, this will be the MCP server URL followed by "/oauth/callback".
+
+    <Frame>
+        <img src="/integrations/images/oci/ocioauthconfiguration.png" alt="OAuth Configuration for an Integrated Application in OCI IAM Domain" />
+    </Frame>
+</Step>
+
+<Step title="Activate the Integrated Application">
+
+    Click on "Submit" button to update OAuth configuration for the client application. 
+    **Note: You don't need to do any special configuration to support PKCE for the OAuth client.**
+    Make sure to Activate the client application.
+    Note down client ID and client secret for the application. You'll use these values when configuring the OCIProvider in your code.
+</Step>
+</Steps>
+
+This is all you need to implement MCP server authentication against OCI IAM. However, you may want to use an authenticated user token to invoke OCI control plane APIs and propagate identity to the OCI control plane instead of using a service user account. In that case, you need to implement token exchange.
+
+### Step 3: Token Exchange Setup (Only if MCP server needs to talk to OCI Control Plane)
+
+Token exchange helps you exchange a logged-in user's OCI IAM token for an OCI control plane session token, also known as UPST (User Principal Session Token). To learn more about token exchange, refer to my [Workload Identity Federation Blog](https://www.ateam-oracle.com/post/workload-identity-federation)
+
+For token exchange, we need to configure Identity propagation trust. The blog above discusses setting up the trust using REST APIs. However, you can also use OCI CLI. Before using the CLI command below, ensure that you have created a token exchange OAuth client. In most cases, you can use the same OAuth client that you created above. Replace `<IAM_GUID>` and `<CLIENT_ID>` in the CLI command below with your actual values.
+
+```bash
+oci identity-domains identity-propagation-trust create \
+--schemas '["urn:ietf:params:scim:schemas:oracle:idcs:IdentityPropagationTrust"]' \
+--public-key-endpoint "https://<IAM_GUID>.identity.oraclecloud.com/admin/v1/SigningCert/jwk" \
+--name "For Token Exchange" --type "JWT" \
+--issuer "https://identity.oraclecloud.com/" --active true \
+--endpoint "https://<IAM_GUID>.identity.oraclecloud.com" \
+--subject-claim-name "sub" --allow-impersonation false \
+--subject-mapping-attribute "username" \
+--subject-type "User" --client-claim-name "iss" \
+--client-claim-values '["https://identity.oraclecloud.com/"]' \
+--oauth-clients '["<CLIENT_ID>"]'
+```
+
+To exchange access token for OCI token and create a signer object, you need to add below code in MCP server. You can then use the signer object to create any OCI control plane client. 
+
+```python
+
+from fastmcp.server.dependencies import get_access_token
+from fastmcp.utilities.logging import get_logger
+from oci.auth.signers import TokenExchangeSigner
+import os
+
+logger = get_logger(__name__)
+
+# Load configuration from environment
+OCI_IAM_GUID = os.environ.get("OCI_IAM_GUID")
+OCI_CLIENT_ID = os.environ.get("OCI_CLIENT_ID")
+OCI_CLIENT_SECRET = os.environ.get("OCI_CLIENT_SECRET")
+
+_global_token_cache = {} #In memory cache for OCI session token signer
+    
+def get_oci_signer() -> TokenExchangeSigner:
+
+    authntoken = get_access_token()
+    tokenID = authntoken.claims.get("jti")
+    token = authntoken.token
+    
+    #Check if the signer exists for the token ID in memory cache
+    cached_signer = _global_token_cache.get(tokenID)
+    logger.debug(f"Global cached signer: {cached_signer}")
+    if cached_signer:
+        logger.debug(f"Using globally cached signer for token ID: {tokenID}")
+        return cached_signer
+
+    #If the signer is not yet created for the token then create new OCI signer object
+    logger.debug(f"Creating new signer for token ID: {tokenID}")
+    signer = TokenExchangeSigner(
+        jwt_or_func=token,
+        oci_domain_id=OCI_IAM_GUID.split(".")[0] if OCI_IAM_GUID else "",
+        client_id=OCI_CLIENT_ID,
+        client_secret=OCI_CLIENT_SECRET,
+    )
+    logger.debug(f"Signer {signer} created for token ID: {tokenID}")
+        
+    #Cache the signer object in memory cache
+    _global_token_cache[tokenID] = signer
+    logger.debug(f"Signer cached for token ID: {tokenID}")
+
+    return signer
+```
+
+## Running MCP server
+
+Once the setup is complete, to run the MCP server, run the below command.
+```bash
+fastmcp run server.py:mcp --transport http --port 8000
+```
+
+To run MCP client, run the below command.
+```bash
+python3 client.py
+```
+
+MCP Client sample is as below.
+```python client.py
+from fastmcp import Client
+import asyncio
+
+async def main():
+    # The client will automatically handle OCI OAuth flows
+    async with Client("http://localhost:8000/mcp/", auth="oauth") as client:
+        # First-time connection will open OCI login in your browser
+        print("✓ Authenticated with OCI IAM")
+
+        tools = await client.list_tools()
+        print(f"🔧 Available tools ({len(tools)}):")
+        for tool in tools:
+            print(f"   - {tool.name}: {tool.description}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+1. Your browser will open to OCI IAM's login page
+2. Sign in with your OCI account and grant the requested consent
+3. After authorization, you'll be redirected back to the redirect path
+4. The client receives the token and can make authenticated requests
+
+## Production Configuration
+
+<VersionBadge version="2.13.0" />
+
+For production deployments with persistent token management across server restarts, configure `jwt_signing_key`, and `client_storage`:
+
+```python server.py
+
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.oci import OCIProvider
+
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+# Load configuration from environment
+# Production setup with encrypted persistent token storage
+auth_provider = OCIProvider(
+    config_url=os.environ.get("OCI_CONFIG_URL"),
+    client_id=os.environ.get("OCI_CLIENT_ID"),
+    client_secret=os.environ.get("OCI_CLIENT_SECRET"),
+    base_url=os.environ.get("BASE_URL", "https://your-production-domain.com"),
+
+    # Production token management
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(
+            host=os.environ["REDIS_HOST"],
+            port=int(os.environ["REDIS_PORT"])
+        ),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+
+mcp = FastMCP(name="Production OCI App", auth=auth_provider)
+```
+
+<Note>
+Parameters (`jwt_signing_key` and `client_storage`) work together to ensure tokens and client registrations survive server restarts. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at Rest** - without it, tokens are stored in plaintext. Store secrets in environment variables and use a persistent storage backend like Redis for distributed deployments.
+
+For complete details on these parameters, see the [OAuth Proxy documentation](/servers/auth/oauth-proxy#configuration-parameters).
+</Note>
+
+<Info>
+The client caches tokens locally, so you won't need to re-authenticate for subsequent runs unless the token expires or you explicitly clear the cache.
+</Info>
\ No newline at end of file
diff --git a/docs/integrations/openai.mdx b/docs/integrations/openai.mdx
new file mode 100644
index 0000000..94ca82b
--- /dev/null
+++ b/docs/integrations/openai.mdx
@@ -0,0 +1,227 @@
+---
+title: OpenAI API 🤝 FastMCP
+sidebarTitle: OpenAI API
+description: Connect FastMCP servers to the OpenAI API
+icon: message-code
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+
+## Responses API
+
+OpenAI's [Responses API](https://platform.openai.com/docs/api-reference/responses) supports [MCP servers](https://platform.openai.com/docs/guides/tools-remote-mcp) as remote tool sources, allowing you to extend AI capabilities with custom functions.
+
+<Note>
+The Responses API is a distinct API from OpenAI's Completions API or Assistants API. At this time, only the Responses API supports MCP.
+</Note>
+
+<Tip>
+Currently, the Responses API only accesses **tools** from MCP servers—it queries the `list_tools` endpoint and exposes those functions to the AI agent. Other MCP features like resources and prompts are not currently supported.
+</Tip>
+
+
+### Create a Server
+
+First, create a FastMCP server with the tools you want to expose. For this example, we'll create a server with a single tool that rolls dice.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+
+### Deploy the Server
+
+Your server must be deployed to a public URL in order for OpenAI to access it.
+
+For development, you can use tools like `ngrok` to temporarily expose a locally-running server to the internet. We'll do that for this example (you may need to install `ngrok` and create a free account), but you can use any other method to deploy your server.
+
+Assuming you saved the above code as `server.py`, you can run the following two commands in two separate terminals to deploy your server and expose it to the internet:
+
+<CodeGroup>
+```bash FastMCP server
+python server.py
+```
+
+```bash ngrok
+ngrok http 8000
+```
+</CodeGroup>
+
+<Warning>
+This exposes your unauthenticated server to the internet. Only run this command in a safe environment if you understand the risks.
+</Warning>
+
+### Call the Server
+
+To use the Responses API, you'll need to install the OpenAI Python SDK (not included with FastMCP):
+
+```bash
+pip install openai
+```
+
+You'll also need to authenticate with OpenAI. You can do this by setting the `OPENAI_API_KEY` environment variable. Consult the OpenAI SDK documentation for more information.
+
+```bash
+export OPENAI_API_KEY="your-api-key"
+```
+
+Here is an example of how to call your server from Python. Note that you'll need to replace `https://your-server-url.com` with the actual URL of your server. In addition, we use `/mcp/` as the endpoint because we deployed a streamable-HTTP server with the default path; you may need to use a different endpoint if you customized your server's deployment.
+
+```python {4, 11-16}
+from openai import OpenAI
+
+# Your server URL (replace with your actual URL)
+url = 'https://your-server-url.com'
+
+client = OpenAI()
+
+resp = client.responses.create(
+    model="gpt-4.1",
+    tools=[
+        {
+            "type": "mcp",
+            "server_label": "dice_server",
+            "server_url": f"{url}/mcp/",
+            "require_approval": "never",
+        },
+    ],
+    input="Roll a few dice!",
+)
+
+print(resp.output_text)
+```
+If you run this code, you'll see something like the following output:
+
+```text
+You rolled 3 dice and got the following results: 6, 4, and 2!
+```
+
+### Authentication
+
+<VersionBadge version="2.6.0" />
+
+The Responses API can include headers to authenticate the request, which means you don't have to worry about your server being publicly accessible.
+
+#### Server Authentication
+
+The simplest way to add authentication to the server is to use a bearer token scheme. 
+
+For this example, we'll quickly generate our own tokens with FastMCP's `RSAKeyPair` utility, but this may not be appropriate for production use. For more details, see the complete server-side [Token Verification](/servers/auth/token-verification) documentation. 
+
+We'll start by creating an RSA key pair to sign and verify tokens.
+
+```python
+from fastmcp.server.auth.providers.jwt import RSAKeyPair
+
+key_pair = RSAKeyPair.generate()
+access_token = key_pair.create_token(audience="dice-server")
+```
+
+<Warning>
+FastMCP's `RSAKeyPair` utility is for development and testing only.
+</Warning> 
+
+Next, we'll create a `JWTVerifier` to authenticate the server. 
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import JWTVerifier
+
+auth = JWTVerifier(
+    public_key=key_pair.public_key,
+    audience="dice-server",
+)
+
+mcp = FastMCP(name="Dice Roller", auth=auth)
+```
+
+Here is a complete example that you can copy/paste. For simplicity and the purposes of this example only, it will print the token to the console. **Do NOT do this in production!**
+
+```python server.py [expandable]
+from fastmcp import FastMCP
+from fastmcp.server.auth import JWTVerifier
+from fastmcp.server.auth.providers.jwt import RSAKeyPair
+import random
+
+key_pair = RSAKeyPair.generate()
+access_token = key_pair.create_token(audience="dice-server")
+
+auth = JWTVerifier(
+    public_key=key_pair.public_key,
+    audience="dice-server",
+)
+
+mcp = FastMCP(name="Dice Roller", auth=auth)
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    print(f"\n---\n\n🔑 Dice Roller access token:\n\n{access_token}\n\n---\n")
+    mcp.run(transport="http", port=8000)
+```
+
+#### Client Authentication
+
+If you try to call the authenticated server with the same OpenAI code we wrote earlier, you'll get an error like this:
+
+```text
+APIStatusError: Error code: 424 - {
+    "error": {
+        "message": "Error retrieving tool list from MCP server: 'dice_server'. Http status code: 401 (Unauthorized)",
+        "type": "external_connector_error",
+        "param": "tools",
+        "code": "http_error"
+    }
+}
+```
+
+As expected, the server is rejecting the request because it's not authenticated.
+
+To authenticate the client, you can pass the token in the `Authorization` header with the `Bearer` scheme:
+
+
+```python {4, 7, 19-21} [expandable]
+from openai import OpenAI
+
+# Your server URL (replace with your actual URL)
+url = 'https://your-server-url.com'
+
+# Your access token (replace with your actual token)
+access_token = 'your-access-token'
+
+client = OpenAI()
+
+resp = client.responses.create(
+    model="gpt-4.1",
+    tools=[
+        {
+            "type": "mcp",
+            "server_label": "dice_server",
+            "server_url": f"{url}/mcp/",
+            "require_approval": "never",
+            "headers": {
+                "Authorization": f"Bearer {access_token}"
+            }
+        },
+    ],
+    input="Roll a few dice!",
+)
+
+print(resp.output_text)
+```
+
+You should now see the dice roll results in the output.
\ No newline at end of file
diff --git a/docs/integrations/openapi.mdx b/docs/integrations/openapi.mdx
new file mode 100644
index 0000000..f5f2b3d
--- /dev/null
+++ b/docs/integrations/openapi.mdx
@@ -0,0 +1,456 @@
+---
+title: OpenAPI 🤝 FastMCP
+sidebarTitle: OpenAPI
+description: Generate MCP servers from any OpenAPI specification
+icon: list-tree
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.0.0" />
+
+FastMCP can automatically generate an MCP server from any OpenAPI specification, allowing AI models to interact with existing APIs through the MCP protocol. Instead of manually creating tools and resources, you provide an OpenAPI spec and FastMCP intelligently converts API endpoints into the appropriate MCP components.
+
+<Note>
+Under the hood, OpenAPI integration uses OpenAPIProvider (v3.0.0+) to source tools from the specification. See [Providers](/servers/providers/overview) to understand how FastMCP sources components.
+</Note>
+
+<Tip>
+Generating MCP servers from OpenAPI is a great way to get started with FastMCP, but in practice LLMs achieve **significantly better performance** with well-designed and curated MCP servers than with auto-converted OpenAPI servers. This is especially true for complex APIs with many endpoints and parameters.
+
+We recommend using the FastAPI integration for bootstrapping and prototyping, not for mirroring your API to LLM clients. See the post [Stop Converting Your REST APIs to MCP](https://www.jlowin.dev/blog/stop-converting-rest-apis-to-mcp) for more details.
+</Tip>
+
+## Create a Server
+
+To convert an OpenAPI specification to an MCP server, use the `FastMCP.from_openapi()` class method:
+
+```python server.py
+import httpx
+from fastmcp import FastMCP
+
+# Create an HTTP client for your API
+client = httpx.AsyncClient(base_url="https://api.example.com")
+
+# Load your OpenAPI spec 
+openapi_spec = httpx.get("https://api.example.com/openapi.json").json()
+
+# Create the MCP server
+mcp = FastMCP.from_openapi(
+    openapi_spec=openapi_spec,
+    client=client,
+    name="My API Server"
+)
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+### Authentication
+
+If your API requires authentication, configure it on the HTTP client:
+
+```python
+import httpx
+from fastmcp import FastMCP
+
+# Bearer token authentication
+api_client = httpx.AsyncClient(
+    base_url="https://api.example.com",
+    headers={"Authorization": "Bearer YOUR_TOKEN"}
+)
+
+# Create MCP server with authenticated client
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec, 
+    client=api_client,
+    timeout=30.0  # 30 second timeout for all requests
+)
+```
+
+## Route Mapping
+
+By default, FastMCP converts **every endpoint** in your OpenAPI specification into an MCP **Tool**. This provides a simple, predictable starting point that ensures all your API's functionality is immediately available to the vast majority of LLM clients which only support MCP tools.
+
+While this is a pragmatic default for maximum compatibility, you can easily customize this behavior. Internally, FastMCP uses an ordered list of `RouteMap` objects to determine how to map OpenAPI routes to various MCP component types.
+
+Each `RouteMap` specifies a combination of methods, patterns, and tags, as well as a corresponding MCP component type. Each OpenAPI route is checked against each `RouteMap` in order, and the first one that matches every criteria is used to determine its converted MCP type. A special type, `EXCLUDE`, can be used to exclude routes from the MCP server entirely.
+
+- **Methods**: HTTP methods to match (e.g. `["GET", "POST"]` or `"*"` for all)
+- **Pattern**: Regex pattern to match the route path (e.g. `r"^/users/.*"` or `r".*"` for all)
+- **Tags**: A set of OpenAPI tags that must all be present. An empty set (`{}`) means no tag filtering, so the route matches regardless of its tags.
+- **MCP type**: What MCP component type to create (`TOOL`, `RESOURCE`, `RESOURCE_TEMPLATE`, or `EXCLUDE`)
+- **MCP tags**: A set of custom tags to add to components created from matching routes
+
+Here is FastMCP's default rule:
+
+```python
+from fastmcp.server.providers.openapi import RouteMap, MCPType
+
+DEFAULT_ROUTE_MAPPINGS = [
+    # All routes become tools
+    RouteMap(mcp_type=MCPType.TOOL),
+]
+```
+
+### Custom Route Maps
+
+When creating your FastMCP server, you can customize routing behavior by providing your own list of `RouteMap` objects. Your custom maps are processed before the default route maps, and routes will be assigned to the first matching custom map.
+
+For example, prior to FastMCP 2.8.0, GET requests were automatically mapped to `Resource` and `ResourceTemplate` components based on whether they had path parameters. (This was changed solely for client compatibility reasons.) You can restore this behavior by providing custom route maps:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi import RouteMap, MCPType
+
+# Restore pre-2.8.0 semantic mapping
+semantic_maps = [
+    # GET requests with path parameters become ResourceTemplates
+    RouteMap(methods=["GET"], pattern=r".*\{.*\}.*", mcp_type=MCPType.RESOURCE_TEMPLATE),
+    # All other GET requests become Resources
+    RouteMap(methods=["GET"], pattern=r".*", mcp_type=MCPType.RESOURCE),
+]
+
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    route_maps=semantic_maps,
+)
+```
+
+With these maps, `GET` requests are handled semantically, and all other methods (`POST`, `PUT`, etc.) will fall through to the default rule and become `Tool`s.
+
+Here is a more complete example that uses custom route maps to convert all `GET` endpoints under `/analytics/` to tools while excluding all admin endpoints and all routes tagged "internal". All other routes will be handled by the default rules:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi import RouteMap, MCPType
+
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    route_maps=[
+        # Analytics `GET` endpoints are tools
+        RouteMap(
+            methods=["GET"], 
+            pattern=r"^/analytics/.*", 
+            mcp_type=MCPType.TOOL,
+        ),
+
+        # Exclude all admin endpoints
+        RouteMap(
+            pattern=r"^/admin/.*", 
+            mcp_type=MCPType.EXCLUDE,
+        ),
+
+        # Exclude all routes tagged "internal"
+        RouteMap(
+            tags={"internal"},
+            mcp_type=MCPType.EXCLUDE,
+        ),
+    ],
+)
+```
+
+<Tip>
+The default route maps are always applied after your custom maps, so you do not have to create route maps for every possible route.
+</Tip>
+
+### Excluding Routes
+
+To exclude routes from the MCP server, use a route map to assign them to `MCPType.EXCLUDE`. 
+
+You can use this to remove sensitive or internal routes by targeting them specifically:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi import RouteMap, MCPType
+
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    route_maps=[
+        RouteMap(pattern=r"^/admin/.*", mcp_type=MCPType.EXCLUDE),
+        RouteMap(tags={"internal"}, mcp_type=MCPType.EXCLUDE),
+    ],
+)
+```
+
+Or you can use a catch-all rule to exclude everything that your maps don't handle explicitly:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi import RouteMap, MCPType
+
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    route_maps=[
+        # custom mapping logic goes here
+        # ... your specific route maps ...
+        # exclude all remaining routes
+        RouteMap(mcp_type=MCPType.EXCLUDE),
+    ],
+)
+```
+
+<Tip>
+Using a catch-all exclusion rule will prevent the default route mappings from being applied, since it will match every remaining route. This is useful if you want to explicitly allow-list certain routes.
+</Tip>
+
+### Advanced Route Mapping
+
+<VersionBadge version="2.5.0" />
+
+For advanced use cases that require more complex logic, you can provide a `route_map_fn` callable. After the route map logic is applied, this function is called on each matched route and its assigned MCP component type. It can optionally return a different component type to override the mapped assignment. If it returns `None`, the assigned type is used.
+
+In addition to more precise targeting of methods, patterns, and tags, this function can access any additional OpenAPI metadata about the route.
+
+<Tip>
+The `route_map_fn` is called on all routes, even those that matched `MCPType.EXCLUDE` in your custom maps. This gives you an opportunity to customize the mapping or even override an exclusion.
+</Tip>
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi import RouteMap, MCPType
+from fastmcp.utilities.openapi import HTTPRoute
+
+def custom_route_mapper(route: HTTPRoute, mcp_type: MCPType) -> MCPType | None:
+    """Advanced route type mapping."""
+    # Convert all admin routes to tools regardless of HTTP method
+    if "/admin/" in route.path:
+        return MCPType.TOOL
+
+    elif "internal" in route.tags:
+        return MCPType.EXCLUDE
+    
+    # Convert user detail routes to templates even if they're POST
+    elif route.path.startswith("/users/") and route.method == "POST":
+        return MCPType.RESOURCE_TEMPLATE
+    
+    # Use defaults for all other routes
+    return None
+
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    route_map_fn=custom_route_mapper,
+)
+```
+
+## Customization
+
+### Component Names
+
+<VersionBadge version="2.5.0" />
+
+FastMCP automatically generates names for MCP components based on the OpenAPI specification. By default, it uses the `operationId` from your OpenAPI spec, up to the first double underscore (`__`).
+
+All component names are automatically:
+- **Slugified**: Spaces and special characters are converted to underscores or removed
+- **Truncated**: Limited to 56 characters maximum to ensure compatibility
+- **Unique**: If multiple components have the same name, a number is automatically appended to make them unique
+
+For more control over component names, you can provide an `mcp_names` dictionary that maps `operationId` values to your desired names. The `operationId` must be exactly as it appears in the OpenAPI spec. The provided name will always be slugified and truncated.
+
+```python
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    mcp_names={
+        "list_users__with_pagination": "user_list",
+        "create_user__admin_required": "create_user", 
+        "get_user_details__admin_required": "user_detail",
+    }
+)
+```
+
+Any `operationId` not found in `mcp_names` will use the default strategy (operationId up to the first `__`).
+
+### Tags
+
+<VersionBadge version="2.8.0" />
+
+FastMCP provides several ways to add tags to your MCP components, allowing you to categorize and organize them for better discoverability and filtering. Tags are combined from multiple sources to create the final set of tags on each component.
+
+#### RouteMap Tags
+
+You can add custom tags to components created from specific routes using the `mcp_tags` parameter in `RouteMap`. These tags will be applied to all components created from routes that match that particular route map.
+
+```python
+from fastmcp.server.providers.openapi import RouteMap, MCPType
+
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    route_maps=[
+        # Add custom tags to all POST endpoints
+        RouteMap(
+            methods=["POST"],
+            pattern=r".*",
+            mcp_type=MCPType.TOOL,
+            mcp_tags={"write-operation", "api-mutation"}
+        ),
+        
+        # Add different tags to detail view endpoints
+        RouteMap(
+            methods=["GET"],
+            pattern=r".*\{.*\}.*",
+            mcp_type=MCPType.RESOURCE_TEMPLATE,
+            mcp_tags={"detail-view", "parameterized"}
+        ),
+        
+        # Add tags to list endpoints
+        RouteMap(
+            methods=["GET"],
+            pattern=r".*",
+            mcp_type=MCPType.RESOURCE,
+            mcp_tags={"list-data", "collection"}
+        ),
+    ],
+)
+```
+
+#### Global Tags
+
+You can add tags to **all** components by providing a `tags` parameter when creating your MCP server. These global tags will be applied to every component created from your OpenAPI specification.
+
+```python
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    tags={"api-v2", "production", "external"}
+)
+```
+
+#### OpenAPI Tags in Client Meta
+
+FastMCP automatically includes OpenAPI tags from your specification in the component's metadata. These tags are available to MCP clients through the `meta.fastmcp.tags` field, allowing clients to filter and organize components based on the original OpenAPI tagging:
+
+<CodeGroup>
+```json {5} OpenAPI spec with tags
+{
+  "paths": {
+    "/users": {
+      "get": {
+        "tags": ["users", "public"],
+        "operationId": "list_users",
+        "summary": "List all users"
+      }
+    }
+  }
+}
+```
+```python {6-9} Access OpenAPI tags in MCP client
+async with client:
+    tools = await client.list_tools()
+    for tool in tools:
+        if tool.meta:
+            # OpenAPI tags are now available in fastmcp namespace!
+            fastmcp_meta = tool.meta.get('fastmcp', {})
+            openapi_tags = fastmcp_meta.get('tags', [])
+            if 'users' in openapi_tags:
+                print(f"Found user-related tool: {tool.name}")
+```
+</CodeGroup>
+
+This makes it easy for clients to understand and organize API endpoints based on their original OpenAPI categorization.
+
+### Advanced Customization
+
+<VersionBadge version="2.5.0" />
+
+By default, FastMCP creates MCP components using a variety of metadata from the OpenAPI spec, such as incorporating the OpenAPI description into the MCP component description.
+
+At times you may want to modify those MCP components in a variety of ways, such as adding LLM-specific instructions or tags. For fine-grained customization, you can provide a `mcp_component_fn` when creating the MCP server. After each MCP component has been created, this function is called on it and has the opportunity to modify it in-place.
+
+<Tip>
+Your `mcp_component_fn` is expected to modify the component in-place, not to return a new component. The result of the function is ignored.
+</Tip>
+
+```python
+from fastmcp.server.providers.openapi import (
+    OpenAPITool,
+    OpenAPIResource,
+    OpenAPIResourceTemplate,
+)
+from fastmcp.utilities.openapi import HTTPRoute
+
+def customize_components(
+    route: HTTPRoute, 
+    component: OpenAPITool | OpenAPIResource | OpenAPIResourceTemplate,
+) -> None:
+    # Add custom tags to all components
+    component.tags.add("openapi")
+    
+    # Customize based on component type
+    if isinstance(component, OpenAPITool):
+        component.description = f"🔧 {component.description} (via API)"
+    
+    if isinstance(component, OpenAPIResource):
+        component.description = f"📊 {component.description}"
+        component.tags.add("data")
+
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    mcp_component_fn=customize_components,
+)
+```
+
+## Request Parameter Handling
+
+FastMCP intelligently handles different types of parameters in OpenAPI requests:
+
+### Query Parameters
+
+By default, FastMCP only includes query parameters that have non-empty values. Parameters with `None` values or empty strings are automatically filtered out.
+
+```python
+# When calling this tool...
+await client.call_tool("search_products", {
+    "category": "electronics",  # ✅ Included
+    "min_price": 100,           # ✅ Included  
+    "max_price": None,          # ❌ Excluded
+    "brand": "",                # ❌ Excluded
+})
+
+# The HTTP request will be: GET /products?category=electronics&min_price=100
+```
+
+### Path Parameters
+
+Path parameters are typically required by REST APIs. FastMCP:
+- Filters out `None` values
+- Validates that all required path parameters are provided
+- Raises clear errors for missing required parameters
+
+```python
+# ✅ This works
+await client.call_tool("get_user", {"user_id": 123})
+
+# ❌ This raises: "Missing required path parameters: {'user_id'}"
+await client.call_tool("get_user", {"user_id": None})
+```
+
+### Array Parameters
+
+FastMCP handles array parameters according to OpenAPI specifications:
+
+- **Query arrays**: Serialized based on the `explode` parameter (default: `True`)
+- **Path arrays**: Serialized as comma-separated values (OpenAPI 'simple' style)
+
+```python
+# Query array with explode=true (default)
+# ?tags=red&tags=blue&tags=green
+
+# Query array with explode=false  
+# ?tags=red,blue,green
+
+# Path array (always comma-separated)
+# /items/red,blue,green
+```
+
+### Headers
+
+Header parameters are automatically converted to strings and included in the HTTP request.
\ No newline at end of file
diff --git a/docs/integrations/permit.mdx b/docs/integrations/permit.mdx
new file mode 100644
index 0000000..066f5b1
--- /dev/null
+++ b/docs/integrations/permit.mdx
@@ -0,0 +1,352 @@
+---
+title: Permit.io Authorization 🤝 FastMCP
+sidebarTitle: Permit.io
+description: Add fine-grained authorization to your FastMCP servers with Permit.io
+icon: shield-check
+---
+
+Add **policy-based authorization** to your FastMCP servers with one-line code addition with the **[Permit.io][permit-github] authorization middleware**.
+
+Control which tools, resources and prompts MCP clients can view and execute on your server. Define dynamic policies using Permit.io's powerful RBAC, ABAC, and REBAC capabilities, and obtain comprehensive audit logs of all access attempts and violations.
+
+## How it Works
+
+Leveraging FastMCP's [Middleware][fastmcp-middleware], the Permit.io middleware intercepts all MCP requests to your server and automatically maps MCP methods to authorization checks against your Permit.io policies; covering both server methods and tool execution.
+
+### Policy Mapping
+
+The middleware automatically maps MCP methods to Permit.io resources and actions:
+
+- **MCP server methods** (e.g., `tools/list`, `resources/read`):
+  - **Resource**: `{server_name}_{component}` (e.g., `myserver_tools`)
+  - **Action**: The method verb (e.g., `list`, `read`)
+- **Tool execution** (method `tools/call`):
+  - **Resource**: `{server_name}` (e.g., `myserver`)
+  - **Action**: The tool name (e.g., `greet`)
+
+![Permit.io Policy Mapping Example](./images/permit/policy_mapping.png)
+
+*Example: In Permit.io, the 'Admin' role is granted permissions on resources and actions as mapped by the middleware. For example, 'greet', 'greet-jwt', and 'login' are actions on the 'mcp_server' resource, and 'list' is an action on the 'mcp_server_tools' resource.*
+
+> **Note:**
+> Don't forget to assign the relevant role (e.g., Admin, User) to the user authenticating to your MCP server (such as the user in the JWT) in the Permit.io Directory. Without the correct role assignment, users will not have access to the resources and actions you've configured in your policies.
+>
+> ![Permit.io Directory Role Assignment Example](./images/permit/role_assignement.png)
+>
+> *Example: In Permit.io Directory, both 'client' and 'admin' users are assigned the 'Admin' role, granting them the permissions defined in your policy mapping.*
+
+For detailed policy mapping examples and configuration, see [Detailed Policy Mapping](https://github.com/permitio/permit-fastmcp/blob/main/docs/policy-mapping.md).
+
+### Listing Operations
+
+The middleware behaves as a filter for listing operations (`tools/list`, `resources/list`, `prompts/list`), hiding to the client components that are not authorized by the defined policies.
+
+```mermaid
+sequenceDiagram
+    participant MCPClient as MCP Client
+    participant PermitMiddleware as Permit.io Middleware
+    participant MCPServer as FastMCP Server
+    participant PermitPDP as Permit.io PDP
+
+    MCPClient->>PermitMiddleware: MCP Listing Request (e.g., tools/list)
+    PermitMiddleware->>MCPServer: MCP Listing Request
+    MCPServer-->>PermitMiddleware: MCP Listing Response
+    PermitMiddleware->>PermitPDP: Authorization Checks
+    PermitPDP->>PermitMiddleware: Authorization Decisions
+    PermitMiddleware-->>MCPClient: Filtered MCP Listing Response
+```
+
+### Execution Operations
+
+The middleware behaves as an enforcement point for execution operations (`tools/call`, `resources/read`, `prompts/get`), blocking operations that are not authorized by the defined policies.
+
+```mermaid
+sequenceDiagram
+    participant MCPClient as MCP Client
+    participant PermitMiddleware as Permit.io Middleware
+    participant MCPServer as FastMCP Server
+    participant PermitPDP as Permit.io PDP
+
+    MCPClient->>PermitMiddleware: MCP Execution Request (e.g., tools/call)
+    PermitMiddleware->>PermitPDP: Authorization Check
+    PermitPDP->>PermitMiddleware: Authorization Decision
+    PermitMiddleware-->>MCPClient: MCP Unauthorized Error (if denied)
+    PermitMiddleware->>MCPServer: MCP Execution Request (if allowed)
+    MCPServer-->>PermitMiddleware: MCP Execution Response (if allowed)
+    PermitMiddleware-->>MCPClient: MCP Execution Response (if allowed)
+```
+
+## Add Authorization to Your Server
+
+<Note>
+Permit.io is a cloud-native authorization service. You need a Permit.io account and a running Policy Decision Point (PDP) for the middleware to function. You can run the PDP locally with Docker or use Permit.io's cloud PDP.
+</Note>
+
+### Prerequisites
+
+1. **Permit.io Account**: Sign up at [permit.io](https://permit.io)
+2. **PDP Setup**: Run the Permit.io PDP locally or use the cloud PDP (RBAC only)
+3. **API Key**: Get your Permit.io API key from the dashboard
+
+### Run the Permit.io PDP
+
+Run the PDP locally with Docker:
+
+```bash
+docker run -p 7766:7766 permitio/pdp:latest
+```
+
+Or use the cloud PDP URL: `https://cloudpdp.api.permit.io`
+
+### Create a Server with Authorization
+
+First, install the `permit-fastmcp` package:
+
+```bash
+# Using UV (recommended)
+uv add permit-fastmcp
+
+# Using pip
+pip install permit-fastmcp
+```
+
+Then create a FastMCP server and add the Permit.io middleware:
+
+```python server.py
+from fastmcp import FastMCP
+from permit_fastmcp.middleware.middleware import PermitMcpMiddleware
+
+mcp = FastMCP("Secure FastMCP Server 🔒")
+
+@mcp.tool
+def greet(name: str) -> str:
+    """Greet a user by name"""
+    return f"Hello, {name}!"
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+# Add Permit.io authorization middleware
+mcp.add_middleware(PermitMcpMiddleware(
+    permit_pdp_url="http://localhost:7766",
+    permit_api_key="your-permit-api-key"
+))
+
+if __name__ == "__main__":
+    mcp.run(transport="http")
+```
+
+### Configure Access Policies
+
+Create your authorization policies in the Permit.io dashboard:
+
+1. **Create Resources**: Define resources like `mcp_server` and `mcp_server_tools`
+2. **Define Actions**: Add actions like `greet`, `add`, `list`, `read`
+3. **Create Roles**: Define roles like `Admin`, `User`, `Guest`
+4. **Assign Permissions**: Grant roles access to specific resources and actions
+5. **Assign Users**: Assign roles to users in the Permit.io Directory
+
+For step-by-step setup instructions and troubleshooting, see [Getting Started & FAQ](https://github.com/permitio/permit-fastmcp/blob/main/docs/getting-started.md).
+
+#### Example Policy Configuration
+
+Policies are defined in the Permit.io dashboard, but you can also use the [Permit.io Terraform provider](https://github.com/permitio/terraform-provider-permitio) to define policies in code.
+
+
+```terraform
+# Resources
+resource "permitio_resource" "mcp_server" {
+  name = "mcp_server"
+  key  = "mcp_server"
+  
+  actions = {
+    "greet" = { name = "greet" }
+    "add"   = { name = "add" }
+  }
+}
+
+resource "permitio_resource" "mcp_server_tools" {
+  name = "mcp_server_tools"
+  key  = "mcp_server_tools"
+  
+  actions = {
+    "list" = { name = "list" }
+  }
+}
+
+# Roles
+resource "permitio_role" "Admin" {
+  key         = "Admin"
+  name        = "Admin"
+  permissions = [
+    "mcp_server:greet",
+    "mcp_server:add", 
+    "mcp_server_tools:list"
+  ]
+}
+```
+
+You can also use the [Permit.io CLI](https://github.com/permitio/permit-cli), [API](https://api.permit.io/scalar) or [SDKs](https://github.com/permitio/permit-python) to manage policies, as well as writing policies directly in REGO (Open Policy Agent's policy language).
+
+For complete policy examples including ABAC and RBAC configurations, see [Example Policies](https://github.com/permitio/permit-fastmcp/tree/main/docs/example_policies).
+
+### Identity Management
+
+The middleware supports multiple identity extraction modes:
+
+- **Fixed Identity**: Use a fixed identity for all requests
+- **Header-based**: Extract identity from HTTP headers
+- **JWT-based**: Extract and verify JWT tokens
+- **Source-based**: Use the MCP context source field
+
+For detailed identity mode configuration and environment variables, see [Identity Modes & Environment Variables](https://github.com/permitio/permit-fastmcp/blob/main/docs/identity-modes.md).
+
+#### JWT Authentication Example
+
+```python
+import os
+
+# Configure JWT identity extraction
+os.environ["PERMIT_MCP_IDENTITY_MODE"] = "jwt"
+os.environ["PERMIT_MCP_IDENTITY_JWT_SECRET"] = "your-jwt-secret"
+
+mcp.add_middleware(PermitMcpMiddleware(
+    permit_pdp_url="http://localhost:7766",
+    permit_api_key="your-permit-api-key"
+))
+```
+
+### ABAC Policies with Tool Arguments
+
+The middleware supports Attribute-Based Access Control (ABAC) policies that can evaluate tool arguments as attributes. Tool arguments are automatically flattened as individual attributes (e.g., `arg_name`, `arg_number`) for granular policy conditions.
+
+![ABAC Condition Example](./images/permit/abac_condition_example.png)
+
+*Example: Create dynamic resources with conditions like `resource.arg_number greater-than 10` to allow the `conditional-greet` tool only when the number argument exceeds 10.*
+
+#### Example: Conditional Access
+
+Create a dynamic resource with conditions like `resource.arg_number greater-than 10` to allow the `conditional-greet` tool only when the number argument exceeds 10.
+
+```python
+@mcp.tool
+def conditional_greet(name: str, number: int) -> str:
+    """Greet a user only if number > 10"""
+    return f"Hello, {name}! Your number is {number}"
+```
+
+![ABAC Policy Example](./images/permit/abac_policy_example.png)
+
+*Example: The Admin role is granted access to the "conditional-greet" action on the "Big-greets" dynamic resource, while other tools like "greet", "greet-jwt", and "login" are granted on the base "mcp_server" resource.*
+
+For comprehensive ABAC configuration and advanced policy examples, see [ABAC Policies with Tool Arguments](https://github.com/permitio/permit-fastmcp/blob/main/docs/policy-mapping.md#abac-policies-with-tool-arguments).
+
+### Run the Server
+
+Start your FastMCP server normally:
+
+```bash
+python server.py
+```
+
+The middleware will now intercept all MCP requests and check them against your Permit.io policies. Requests include user identification through the configured identity mode and automatic mapping of MCP methods to authorization resources and actions.
+
+## Advanced Configuration
+
+### Environment Variables
+
+Configure the middleware using environment variables:
+
+```bash
+# Permit.io configuration
+export PERMIT_MCP_PERMIT_PDP_URL="http://localhost:7766"
+export PERMIT_MCP_PERMIT_API_KEY="your-api-key"
+
+# Identity configuration
+export PERMIT_MCP_IDENTITY_MODE="jwt"
+export PERMIT_MCP_IDENTITY_JWT_SECRET="your-jwt-secret"
+
+# Method configuration
+export PERMIT_MCP_KNOWN_METHODS='["tools/list","tools/call"]'
+export PERMIT_MCP_BYPASSED_METHODS='["initialize","ping"]'
+
+# Logging configuration
+export PERMIT_MCP_ENABLE_AUDIT_LOGGING="true"
+```
+
+For a complete list of all configuration options and environment variables, see [Configuration Reference](https://github.com/permitio/permit-fastmcp/blob/main/docs/configuration-reference.md).
+
+### Custom Middleware Configuration
+
+```python
+from permit_fastmcp.middleware.middleware import PermitMcpMiddleware
+
+middleware = PermitMcpMiddleware(
+    permit_pdp_url="http://localhost:7766",
+    permit_api_key="your-api-key",
+    enable_audit_logging=True,
+    bypass_methods=["initialize", "ping", "health/*"]
+)
+
+mcp.add_middleware(middleware)
+```
+
+For advanced configuration options and custom middleware extensions, see [Advanced Configuration](https://github.com/permitio/permit-fastmcp/blob/main/docs/advanced-configuration.md).
+
+## Example: Complete JWT Authentication Server
+
+See the [example server](https://github.com/permitio/permit-fastmcp/blob/main/permit_fastmcp/example_server/example.py) for a full implementation with JWT-based authentication. For additional examples and usage patterns, see [Example Server](https://github.com/permitio/permit-fastmcp/blob/main/permit_fastmcp/example_server/):
+
+```python
+from fastmcp import FastMCP, Context
+from permit_fastmcp.middleware.middleware import PermitMcpMiddleware
+import jwt
+import datetime
+
+# Configure JWT identity extraction
+os.environ["PERMIT_MCP_IDENTITY_MODE"] = "jwt"
+os.environ["PERMIT_MCP_IDENTITY_JWT_SECRET"] = "mysecretkey"
+
+mcp = FastMCP("My MCP Server")
+
+@mcp.tool
+def login(username: str, password: str) -> str:
+    """Login to get a JWT token"""
+    if username == "admin" and password == "password":
+        token = jwt.encode(
+            {"sub": username, "exp": datetime.datetime.utcnow() + datetime.timedelta(hours=1)},
+            "mysecretkey",
+            algorithm="HS256"
+        )
+        return f"Bearer {token}"
+    raise Exception("Invalid credentials")
+
+@mcp.tool
+def greet_jwt(ctx: Context) -> str:
+    """Greet a user by extracting their name from JWT"""
+    # JWT extraction handled by middleware
+    return "Hello, authenticated user!"
+
+mcp.add_middleware(PermitMcpMiddleware(
+    permit_pdp_url="http://localhost:7766",
+    permit_api_key="your-permit-api-key"
+))
+
+if __name__ == "__main__":
+    mcp.run(transport="http")
+```
+
+<Tip>
+  For detailed policy configuration, custom authentication, and advanced
+  deployment patterns, visit the [Permit.io FastMCP Middleware
+  repository][permit-fastmcp-github]. For troubleshooting common issues, see [Troubleshooting](https://github.com/permitio/permit-fastmcp/blob/main/docs/troubleshooting.md).
+</Tip>
+
+
+[permit.io]: https://www.permit.io
+[permit-github]: https://github.com/permitio
+[permit-fastmcp-github]: https://github.com/permitio/permit-fastmcp
+[Agent.Security]: https://agent.security
+[fastmcp-middleware]: /servers/middleware
diff --git a/docs/integrations/propelauth.mdx b/docs/integrations/propelauth.mdx
new file mode 100644
index 0000000..7f21d20
--- /dev/null
+++ b/docs/integrations/propelauth.mdx
@@ -0,0 +1,164 @@
+---
+title: PropelAuth 🤝 FastMCP
+sidebarTitle: PropelAuth
+description: Secure your FastMCP server with PropelAuth
+icon: shield-check
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+<VersionBadge version="3.1.0" />
+
+This guide shows you how to secure your FastMCP server using [**PropelAuth**](https://www.propelauth.com), a complete authentication and user management solution. This integration uses the [**Remote OAuth**](/servers/auth/remote-oauth) pattern, where PropelAuth handles user login, consent management, and your FastMCP server validates the tokens.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+
+1. A [PropelAuth](https://www.propelauth.com) account
+2. Your FastMCP server's base URL (can be localhost for development, e.g., `http://localhost:8000`)
+
+### Step 1: Configure PropelAuth
+
+<Steps>
+<Step title="Enable MCP Authentication">
+    Navigate to the **MCP** section in your PropelAuth dashboard, click **Enable MCP**, and choose which environments to enable it for (Test, Staging, Prod).
+</Step>
+
+<Step title="Configure Allowed MCP Clients">
+    Under **MCP > Allowed MCP Clients**, add redirect URIs for each MCP client you want to allow. PropelAuth provides templates for popular clients like Claude, Cursor, and ChatGPT.
+</Step>
+
+<Step title="Configure Scopes">
+    Under **MCP > Scopes**, define the permissions available to MCP clients (e.g., `read:user_data`).
+</Step>
+
+<Step title="Choose How Users Create OAuth Clients">
+    Under **MCP > Settings > How Do Users Create OAuth Clients?**, you can optionally enable:
+    - **Dynamic Client Registration** — clients self-register automatically via the DCR protocol
+    - **Manually via Hosted Pages** — PropelAuth creates a UI for your users to register OAuth clients
+
+    You can enable neither, one, or both. If you enable neither, you'll manage OAuth client creation yourself.
+</Step>
+
+<Step title="Generate Introspection Credentials">
+    Go to **MCP > Request Validation** and click **Create Credentials**. Note the **Client ID** and **Client Secret** - you'll need these to validate tokens.
+</Step>
+
+<Step title="Note Your Auth URL">
+    Find your Auth URL in the **Backend Integration** section of the dashboard (e.g., `https://auth.yourdomain.com`).
+</Step>
+</Steps>
+
+For more details, see the [PropelAuth MCP documentation](https://docs.propelauth.com/mcp-authentication/overview).
+
+### Step 2: Environment Setup
+
+Create a `.env` file with your PropelAuth configuration:
+
+```bash
+PROPELAUTH_AUTH_URL=https://auth.yourdomain.com          # From Backend Integration page
+PROPELAUTH_INTROSPECTION_CLIENT_ID=your-client-id        # From MCP > Request Validation
+PROPELAUTH_INTROSPECTION_CLIENT_SECRET=your-client-secret # From MCP > Request Validation
+SERVER_URL=http://localhost:8000                          # Your server's base URL
+```
+
+### Step 3: FastMCP Configuration
+
+Create your FastMCP server file and use the PropelAuthProvider to handle all the OAuth integration automatically:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.propelauth import PropelAuthProvider
+
+auth_provider = PropelAuthProvider(
+    auth_url=os.environ["PROPELAUTH_AUTH_URL"],
+    introspection_client_id=os.environ["PROPELAUTH_INTROSPECTION_CLIENT_ID"],
+    introspection_client_secret=os.environ["PROPELAUTH_INTROSPECTION_CLIENT_SECRET"],
+    base_url=os.environ["SERVER_URL"],
+    required_scopes=["read:user_data"],                          # Optional scope enforcement
+)
+
+mcp = FastMCP(name="My PropelAuth Protected Server", auth=auth_provider)
+```
+
+## Testing
+
+With your `.env` loaded, start the server:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Then use a FastMCP client to verify authentication works:
+
+```python
+from fastmcp import Client
+import asyncio
+
+async def main():
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        assert await client.ping()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Accessing User Information
+
+You can use `get_access_token()` inside your tools to identify the authenticated user:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.propelauth import PropelAuthProvider
+from fastmcp.server.dependencies import get_access_token
+
+auth = PropelAuthProvider(
+    auth_url=os.environ["PROPELAUTH_AUTH_URL"],
+    introspection_client_id=os.environ["PROPELAUTH_INTROSPECTION_CLIENT_ID"],
+    introspection_client_secret=os.environ["PROPELAUTH_INTROSPECTION_CLIENT_SECRET"],
+    base_url=os.environ["SERVER_URL"],
+    required_scopes=["read:user_data"],
+)
+
+mcp = FastMCP(name="My PropelAuth Protected Server", auth=auth)
+
+@mcp.tool
+def whoami() -> dict:
+    """Return the authenticated user's ID."""
+    token = get_access_token()
+    if token is None:
+        return {"error": "Not authenticated"}
+    user_id = token.claims.get("sub")
+    return {"user_id": user_id}
+```
+
+## Advanced Configuration
+
+The `PropelAuthProvider` supports optional overrides for token introspection behavior, including caching and request timeouts:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.propelauth import PropelAuthProvider
+
+auth = PropelAuthProvider(
+    auth_url=os.environ["PROPELAUTH_AUTH_URL"],
+    introspection_client_id=os.environ["PROPELAUTH_INTROSPECTION_CLIENT_ID"],
+    introspection_client_secret=os.environ["PROPELAUTH_INTROSPECTION_CLIENT_SECRET"],
+    base_url=os.environ.get("BASE_URL", "https://your-server.com"),
+    required_scopes=["read:user_data"],
+    resource="https://your-server.com/mcp",              # Restrict to tokens intended for this server (RFC 8707)
+    token_introspection_overrides={
+        "cache_ttl_seconds": 300,       # Cache introspection results for 5 minutes
+        "max_cache_size": 1000,         # Maximum cached tokens
+        "timeout_seconds": 15,          # HTTP request timeout
+    },
+)
+
+mcp = FastMCP(name="My PropelAuth Protected Server", auth=auth)
+```
diff --git a/docs/integrations/pydantic-ai.mdx b/docs/integrations/pydantic-ai.mdx
new file mode 100644
index 0000000..0c8ffa5
--- /dev/null
+++ b/docs/integrations/pydantic-ai.mdx
@@ -0,0 +1,137 @@
+---
+title: Pydantic AI 🤝 FastMCP
+sidebarTitle: Pydantic AI
+description: Connect FastMCP servers to Pydantic AI agents using the FastMCPToolset
+icon: message-code
+---
+
+[Pydantic AI](https://ai.pydantic.dev/) ships a [`FastMCPToolset`](https://ai.pydantic.dev/mcp/fastmcp-client/) that lets a Pydantic AI agent call tools exposed by any MCP server through the [FastMCP Client](/clients/client). Because the toolset is built on the FastMCP Client, it works with FastMCP servers as well as any other MCP server, and supports the full range of [transports](/clients/transports): in-memory, STDIO, Streamable HTTP, and SSE.
+
+This page shows how to point `FastMCPToolset` at a FastMCP server, with examples for each transport. For the toolset's full API, see the [Pydantic AI documentation](https://ai.pydantic.dev/mcp/fastmcp-client/).
+
+<Tip>
+The `FastMCPToolset` currently exposes **tools** to the agent. Other MCP features such as elicitation and sampling are not yet supported through this toolset; use Pydantic AI's standard [`MCPServer`](https://ai.pydantic.dev/mcp/client/) client if you need them.
+</Tip>
+
+## Install
+
+`FastMCPToolset` lives in `pydantic-ai-slim` behind the `fastmcp` optional group:
+
+```bash
+pip install "pydantic-ai-slim[fastmcp]"
+```
+
+## Create a Server
+
+Create a FastMCP server with the tools you want to expose. We'll use a single dice-rolling tool throughout this guide.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+
+## In-Memory
+
+If your FastMCP server lives in the same process as your agent, pass the `FastMCP` instance directly. The toolset reuses an [in-memory transport](/clients/transports#in-memory-transport), which avoids a network round trip and is the fastest option for tests and embedded use.
+
+```python
+import asyncio
+import random
+from fastmcp import FastMCP
+from pydantic_ai import Agent
+from pydantic_ai.toolsets.fastmcp import FastMCPToolset
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+toolset = FastMCPToolset(mcp)
+agent = Agent("openai:gpt-4.1", toolsets=[toolset])
+
+async def main():
+    result = await agent.run("Roll 3 dice!")
+    print(result.output)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Streamable HTTP
+
+For a remote FastMCP server reachable over HTTP, pass the URL as a string. The toolset infers the [Streamable HTTP transport](/clients/transports#http-transport) from the URL.
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.toolsets.fastmcp import FastMCPToolset
+
+toolset = FastMCPToolset("https://your-server-url.com/mcp")
+agent = Agent("openai:gpt-4.1", toolsets=[toolset])
+```
+
+For [SSE](/clients/transports#sse-transport), use a `/sse` URL instead.
+
+## STDIO
+
+To launch a FastMCP server as a subprocess, pass a script path and the toolset will use the [STDIO transport](/clients/transports#stdio-transport).
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.toolsets.fastmcp import FastMCPToolset
+
+toolset = FastMCPToolset("server.py")
+agent = Agent("openai:gpt-4.1", toolsets=[toolset])
+```
+
+You can also pass a [`StdioTransport`](/clients/transports#stdio-transport) directly when you need control over the command, args, or environment.
+
+## MCP Configuration
+
+To wire up multiple servers at once, pass an [MCP configuration](/integrations/mcp-json-configuration) dictionary. The toolset opens one client per server and exposes all of their tools to the agent.
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.toolsets.fastmcp import FastMCPToolset
+
+mcp_config = {
+    "mcpServers": {
+        "dice": {"command": "python", "args": ["server.py"]},
+        "weather": {"url": "https://weather.example.com/mcp"},
+    }
+}
+
+toolset = FastMCPToolset(mcp_config)
+agent = Agent("openai:gpt-4.1", toolsets=[toolset])
+```
+
+## Authentication
+
+Because `FastMCPToolset` wraps a [FastMCP `Client`](/clients/client), it inherits the client's full [authentication](/clients/auth/bearer) story. To pass credentials such as a bearer token to a remote server, build a `Client` (or `StreamableHttpTransport`) yourself and hand it to the toolset.
+
+```python
+from fastmcp import Client
+from fastmcp.client.transports import StreamableHttpTransport
+from pydantic_ai import Agent
+from pydantic_ai.toolsets.fastmcp import FastMCPToolset
+
+transport = StreamableHttpTransport(
+    url="https://your-server-url.com/mcp",
+    headers={"Authorization": "Bearer your-access-token"},
+)
+
+toolset = FastMCPToolset(Client(transport))
+agent = Agent("openai:gpt-4.1", toolsets=[toolset])
+```
+
+For OAuth flows, use FastMCP's [`OAuth` helper](/clients/auth/oauth) when constructing the `Client`. For server-side token verification, see [Token Verification](/servers/auth/token-verification).
diff --git a/docs/integrations/scalekit.mdx b/docs/integrations/scalekit.mdx
new file mode 100644
index 0000000..2b2fa9d
--- /dev/null
+++ b/docs/integrations/scalekit.mdx
@@ -0,0 +1,148 @@
+---
+title: Scalekit 🤝 FastMCP
+sidebarTitle: Scalekit
+description: Secure your FastMCP server with Scalekit
+icon: shield-check
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.13.0" />
+
+Install auth stack to your FastMCP server with [Scalekit](https://scalekit.com) using the [Remote OAuth](/servers/auth/remote-oauth) pattern: Scalekit handles user authentication, and the MCP server validates issued tokens.
+
+### Prerequisites
+
+Before you begin
+
+1. Get a [Scalekit account](https://app.scalekit.com/) and grab your **Environment URL** from _Dashboard > Settings_ .
+2. Have your FastMCP server's base URL ready (can be localhost for development, e.g., `http://localhost:8000/`)
+
+### Step 1: Configure MCP server in Scalekit environment
+
+<Steps>
+<Step title="Register MCP server and set environment">
+
+In your Scalekit dashboard:
+    1. Open the **MCP Servers** section, then select **Create new server**
+    2. Enter server details: a name, a resource identifier, and the desired MCP client authentication settings
+    3. Save, then copy the **Resource ID** (for example, res_92015146095)
+
+In your FastMCP project's `.env`:
+
+```sh
+SCALEKIT_ENVIRONMENT_URL=<YOUR_APP_ENVIRONMENT_URL>
+SCALEKIT_RESOURCE_ID=<YOUR_APP_RESOURCE_ID> # res_926EXAMPLE5878
+BASE_URL=http://localhost:8000/
+# Optional: additional scopes tokens must have
+# SCALEKIT_REQUIRED_SCOPES=read,write
+```
+
+</Step>
+</Steps>
+
+### Step 2: Add auth to FastMCP server
+
+Create your FastMCP server file and use the ScalekitProvider to handle all the OAuth integration automatically:
+
+> **Warning:** The legacy `mcp_url` and `client_id` parameters are deprecated and will be removed in a future release. Use `base_url` instead of `mcp_url` and remove `client_id` from your configuration.
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.scalekit import ScalekitProvider
+
+# Discovers Scalekit endpoints and set up JWT token validation
+auth_provider = ScalekitProvider(
+    environment_url=SCALEKIT_ENVIRONMENT_URL,    # Scalekit environment URL
+    resource_id=SCALEKIT_RESOURCE_ID,            # Resource server ID
+    base_url=SERVER_URL,                         # Public MCP endpoint
+    required_scopes=["read"],                    # Optional scope enforcement
+)
+
+# Create FastMCP server with auth
+mcp = FastMCP(name="My Scalekit Protected Server", auth=auth_provider)
+
+@mcp.tool
+def auth_status() -> dict:
+    """Show Scalekit authentication status."""
+    # Extract user claims from the JWT
+    return {
+        "message": "This tool requires authentication via Scalekit",
+        "authenticated": True,
+        "provider": "Scalekit"
+    }
+
+```
+
+<Tip>
+Set `required_scopes` when you need tokens to carry specific permissions. Leave it unset to allow any token issued for the resource.
+</Tip>
+
+## Testing
+
+### Start the MCP server
+
+```sh
+uv run python server.py
+```
+
+Use any MCP client (for example, mcp-inspector, Claude, VS Code, or Windsurf) to connect to the running serve. Verify that authentication succeeds and requests are authorized as expected.
+
+## Production Configuration
+
+For production deployments, load configuration from environment variables:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.scalekit import ScalekitProvider
+
+# Load configuration from environment variables
+auth = ScalekitProvider(
+    environment_url=os.environ.get("SCALEKIT_ENVIRONMENT_URL"),
+    resource_id=os.environ.get("SCALEKIT_RESOURCE_ID"),
+    base_url=os.environ.get("BASE_URL", "https://your-server.com")
+)
+
+mcp = FastMCP(name="My Scalekit Protected Server", auth=auth)
+
+@mcp.tool
+def protected_action() -> str:
+    """A tool that requires authentication."""
+    return "Access granted via Scalekit!"
+```
+
+## Capabilities
+
+Scalekit supports OAuth 2.1 with Dynamic Client Registration for MCP clients and enterprise SSO, and provides built‑in JWT validation and security controls.
+
+**OAuth 2.1/DCR**: clients self‑register, use PKCE, and work with the Remote OAuth pattern without pre‑provisioned credentials.
+
+**Validation and SSO**: tokens are verified (keys, RS256, issuer, audience, expiry), and SAML, OIDC, OAuth 2.0, ADFS, Azure AD, and Google Workspace are supported; use HTTPS in production and review auth logs as needed.
+
+## Debugging
+
+Enable detailed logging to troubleshoot authentication issues:
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+### Token inspection
+
+You can inspect JWT tokens in your tools to understand the user context:
+
+```python
+from fastmcp.server.dependencies import get_access_token
+
+@mcp.tool
+def inspect_token() -> dict:
+    """Inspect the current JWT token claims."""
+    token = get_access_token()
+    if token is None:
+        return {"error": "No token found"}
+
+    # Claims were already verified by the auth provider.
+    return token.claims
+```
diff --git a/docs/integrations/supabase.mdx b/docs/integrations/supabase.mdx
new file mode 100644
index 0000000..9ffda44
--- /dev/null
+++ b/docs/integrations/supabase.mdx
@@ -0,0 +1,123 @@
+---
+title: Supabase 🤝 FastMCP
+sidebarTitle: Supabase
+description: Secure your FastMCP server with Supabase Auth
+icon: shield-check
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.13.0" />
+
+This guide shows you how to secure your FastMCP server using **Supabase Auth**. This integration uses the [**Remote OAuth**](/servers/auth/remote-oauth) pattern, where Supabase handles user authentication and your FastMCP server validates the tokens.
+
+<Warning>
+Supabase Auth does not currently support [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html) resource indicators, so FastMCP cannot validate that tokens were issued for the specific resource server.
+</Warning>
+
+## Consent UI Requirement
+
+Supabase's OAuth Server delegates the user consent screen to your application. When an MCP client initiates authorization, Supabase authenticates the user and then redirects to your application at a configured callback URL (e.g., `https://your-app.com/oauth/callback?authorization_id=...`). Your application must host a page that calls Supabase's `approveAuthorization()` or `denyAuthorization()` APIs to complete the flow.
+
+`SupabaseProvider` handles the resource server side (token verification and metadata), but you are responsible for building and hosting the consent UI separately. See [Supabase's OAuth Server documentation](https://supabase.com/docs/guides/auth/oauth-server/getting-started) for details on implementing the authorization page.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+1. A **[Supabase Account](https://supabase.com/)** with a project or a self-hosted **Supabase Auth** instance
+2. **OAuth Server enabled** in your Supabase Dashboard (Authentication → OAuth Server)
+3. **Dynamic Client Registration enabled** in the same settings
+4. A **consent UI** hosted at your configured authorization path (see above)
+5. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`)
+
+### Step 1: Enable Supabase OAuth Server
+
+In your Supabase Dashboard:
+1. Go to **Authentication → OAuth Server**
+2. Enable the **OAuth Server**
+3. Set your **Site URL** to where your consent UI is hosted
+4. Set the **Authorization Path** (e.g., `/oauth/callback`)
+5. Enable **Allow Dynamic OAuth Apps** for MCP client registration
+
+### Step 2: Get Supabase Project URL
+
+In your Supabase Dashboard:
+1. Go to **Project Settings**
+2. Copy your **Project URL** (e.g., `https://abc123.supabase.co`)
+
+### Step 3: FastMCP Configuration
+
+Create your FastMCP server using the `SupabaseProvider`:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.supabase import SupabaseProvider
+
+auth = SupabaseProvider(
+    project_url="https://abc123.supabase.co",
+    base_url="http://localhost:8000",
+)
+
+mcp = FastMCP("Supabase Protected Server", auth=auth)
+
+@mcp.tool
+def protected_tool(message: str) -> str:
+    """This tool requires authentication."""
+    return f"Authenticated user says: {message}"
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+
+## Testing
+
+### Running the Server
+
+Start your FastMCP server with HTTP transport to enable OAuth flows:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+### Testing with a Client
+
+Create a test client that authenticates with your Supabase-protected server:
+
+```python client.py
+from fastmcp import Client
+import asyncio
+
+async def main():
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        print("Authenticated with Supabase!")
+
+        result = await client.call_tool("protected_tool", {"message": "Hello!"})
+        print(result)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+1. Your browser will open to Supabase's authorization endpoint
+2. After authenticating, Supabase redirects to your consent UI
+3. After you approve, the client receives the token and can make authenticated requests
+
+## Production Configuration
+
+For production deployments, load configuration from environment variables:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.supabase import SupabaseProvider
+
+auth = SupabaseProvider(
+    project_url=os.environ["SUPABASE_PROJECT_URL"],
+    base_url=os.environ.get("BASE_URL", "https://your-server.com"),
+)
+
+mcp = FastMCP(name="Supabase Secured App", auth=auth)
+```
diff --git a/docs/integrations/workos.mdx b/docs/integrations/workos.mdx
new file mode 100644
index 0000000..4f13a55
--- /dev/null
+++ b/docs/integrations/workos.mdx
@@ -0,0 +1,200 @@
+---
+title: WorkOS 🤝 FastMCP
+sidebarTitle: WorkOS
+description: Authenticate FastMCP servers with WorkOS Connect
+icon: shield-check
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.12.0" />
+
+Secure your FastMCP server with WorkOS Connect authentication. This integration uses the OAuth Proxy pattern to handle authentication through WorkOS Connect while maintaining compatibility with MCP clients.
+
+<Note>
+This guide covers WorkOS Connect applications. For Dynamic Client Registration (DCR) with AuthKit, see the [AuthKit integration](/integrations/authkit) instead.
+</Note>
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+1. A **[WorkOS Account](https://workos.com/)** with access to create OAuth Apps
+2. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`)
+
+### Step 1: Create a WorkOS OAuth App
+
+Create an OAuth App in your WorkOS dashboard to get the credentials needed for authentication:
+
+<Steps>
+<Step title="Create OAuth Application">
+In your WorkOS dashboard:
+1. Navigate to **Applications**
+2. Click **Create Application** 
+3. Select **OAuth Application**
+4. Name your application
+</Step>
+
+<Step title="Get Credentials">
+In your OAuth application settings:
+1. Copy your **Client ID** (starts with `client_`)
+2. Click **Generate Client Secret** and save it securely
+3. Copy your **AuthKit Domain** (e.g., `https://your-app.authkit.app`)
+</Step>
+
+<Step title="Configure Redirect URI">
+In the **Redirect URIs** section:
+- Add: `http://localhost:8000/auth/callback` (for development)
+- For production, add your server's public URL + `/auth/callback`
+
+<Warning>
+The callback URL must match exactly. The default path is `/auth/callback`, but you can customize it using the `redirect_path` parameter.
+</Warning>
+</Step>
+</Steps>
+
+### Step 2: FastMCP Configuration
+
+Create your FastMCP server using the `WorkOSProvider`:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.workos import WorkOSProvider
+
+# Configure WorkOS OAuth
+auth = WorkOSProvider(
+    client_id="client_YOUR_CLIENT_ID",
+    client_secret="YOUR_CLIENT_SECRET",
+    authkit_domain="https://your-app.authkit.app",
+    base_url="http://localhost:8000",
+    required_scopes=["openid", "profile", "email"]
+)
+
+mcp = FastMCP("WorkOS Protected Server", auth=auth)
+
+@mcp.tool
+def protected_tool(message: str) -> str:
+    """This tool requires authentication."""
+    return f"Authenticated user says: {message}"
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+
+## Testing
+
+### Running the Server
+
+Start your FastMCP server with HTTP transport to enable OAuth flows:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Your server is now running and protected by WorkOS OAuth authentication.
+
+### Testing with a Client
+
+Create a test client that authenticates with your WorkOS-protected server:
+
+```python client.py
+from fastmcp import Client
+import asyncio
+
+async def main():    
+    # The client will automatically handle WorkOS OAuth
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        # First-time connection will open WorkOS login in your browser
+        print("✓ Authenticated with WorkOS!")
+        
+        # Test the protected tool
+        result = await client.call_tool("protected_tool", {"message": "Hello!"})
+        print(result)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+1. Your browser will open to WorkOS's authorization page
+2. After you authorize the app, you'll be redirected back
+3. The client receives the token and can make authenticated requests
+
+<Info>
+The client caches tokens locally, so you won't need to re-authenticate for subsequent runs unless the token expires or you explicitly clear the cache.
+</Info>
+
+## Production Configuration
+
+<VersionBadge version="2.13.0" />
+
+For production deployments with persistent token management across server restarts, configure `jwt_signing_key`, and `client_storage`:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.workos import WorkOSProvider
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+# Production setup with encrypted persistent token storage
+auth = WorkOSProvider(
+    client_id="client_YOUR_CLIENT_ID",
+    client_secret="YOUR_CLIENT_SECRET",
+    authkit_domain="https://your-app.authkit.app",
+    base_url="https://your-production-domain.com",
+    required_scopes=["openid", "profile", "email"],
+
+    # Production token management
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(
+            host=os.environ["REDIS_HOST"],
+            port=int(os.environ["REDIS_PORT"])
+        ),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+
+mcp = FastMCP(name="Production WorkOS App", auth=auth)
+```
+
+<Note>
+Parameters (`jwt_signing_key` and `client_storage`) work together to ensure tokens and client registrations survive server restarts. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without it, tokens are stored in plaintext. Store secrets in environment variables and use a persistent storage backend like Redis for distributed deployments.
+
+For complete details on these parameters, see the [OAuth Proxy documentation](/servers/auth/oauth-proxy#configuration-parameters).
+</Note>
+
+## Configuration Options
+
+<Card>
+<ParamField path="client_id" required>
+WorkOS OAuth application client ID
+</ParamField>
+
+<ParamField path="client_secret" required>
+WorkOS OAuth application client secret
+</ParamField>
+
+<ParamField path="authkit_domain" required>
+Your WorkOS AuthKit domain URL (e.g., `https://your-app.authkit.app`)
+</ParamField>
+
+<ParamField path="base_url" required>
+Your FastMCP server's public URL
+</ParamField>
+
+<ParamField path="required_scopes" default="[]">
+OAuth scopes to request
+</ParamField>
+
+<ParamField path="redirect_path" default="/auth/callback">
+OAuth callback path
+</ParamField>
+
+<ParamField path="timeout_seconds" default="10">
+API request timeout
+</ParamField>
+</Card>
\ No newline at end of file
diff --git a/docs/more/faq.mdx b/docs/more/faq.mdx
new file mode 100644
index 0000000..d2bbbe0
--- /dev/null
+++ b/docs/more/faq.mdx
@@ -0,0 +1,25 @@
+---
+title: FAQ
+description: Answers to common questions about installing and using FastMCP
+icon: circle-question
+---
+
+## `import fastmcp` stopped working after I upgraded with pip
+
+This can happen when you upgrade to FastMCP 3.3 or later from FastMCP 3.2 or earlier with `pip`. The quick fix is `pip install --force-reinstall fastmcp`. See [Troubleshooting](/getting-started/installation#troubleshooting) for the clean-reinstall fallback and an explanation of why it happens.
+
+## What's the difference between `fastmcp` and `fastmcp-slim`?
+
+`fastmcp` is the full distribution. Installing it gives you the complete framework — server, client, CLI, and the common integrations — and is the right choice for most users:
+
+```bash
+pip install fastmcp
+```
+
+`fastmcp-slim` ships the same importable `fastmcp` package with a minimal set of required dependencies. You opt into the pieces you need through extras, which keeps environments lean when you only use part of the framework:
+
+```bash
+pip install "fastmcp-slim[client]"
+```
+
+Both distributions expose the same `import fastmcp`, so application code is identical regardless of which one you install.
diff --git a/docs/more/settings.mdx b/docs/more/settings.mdx
new file mode 100644
index 0000000..a50cca6
--- /dev/null
+++ b/docs/more/settings.mdx
@@ -0,0 +1,100 @@
+---
+title: Settings
+description: Configure FastMCP behavior through environment variables or a .env file.
+icon: gear
+---
+
+FastMCP uses [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) for configuration. Every setting is available as an environment variable with a `FASTMCP_` prefix. Settings are loaded from environment variables and from a `.env` file (see the [Tasks (Docket)](#tasks-docket) section for a caveat about nested settings in `.env` files).
+
+```bash
+# Set via environment
+export FASTMCP_LOG_LEVEL=DEBUG
+export FASTMCP_PORT=3000
+
+# Or use a .env file (loaded automatically)
+echo "FASTMCP_LOG_LEVEL=DEBUG" >> .env
+```
+
+You can change which `.env` file is loaded by setting the `FASTMCP_ENV_FILE` environment variable (defaults to `.env`). Because this controls which file is loaded, it must be set as an environment variable — it cannot be set inside a `.env` file itself.
+
+## Logging
+
+| Environment Variable | Type | Default | Description |
+|---|---|---|---|
+| `FASTMCP_LOG_LEVEL` | `Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]` | `INFO` | Log level for FastMCP's own logging output. Case-insensitive. |
+| `FASTMCP_LOG_ENABLED` | `bool` | `true` | Enable or disable FastMCP logging entirely. |
+| `FASTMCP_CLIENT_LOG_LEVEL` | `Literal["debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"]` | None | Default minimum log level for messages sent to MCP clients via `context.log()`. When set, messages below this level are suppressed. Individual clients can override this per-session using the MCP `logging/setLevel` request. |
+| `FASTMCP_ENABLE_RICH_LOGGING` | `bool` | `true` | Use rich formatting for log output. Set to `false` for plain Python logging. |
+| `FASTMCP_ENABLE_RICH_TRACEBACKS` | `bool` | `true` | Use rich tracebacks for errors. |
+| `FASTMCP_DEPRECATION_WARNINGS` | `bool` | `true` | Show deprecation warnings. |
+| `FASTMCP_MCP_CAMELCASE_COMPAT` | `bool` | `true` | Bridge legacy camelCase reads on MCP SDK objects (e.g. `tool.inputSchema`, `result.isError`) to their snake_case fields after the SDK v2 rename. Each bridged read emits a `FastMCPDeprecationWarning`. Set to `false` to disable the shims, in which case only the snake_case names resolve. |
+
+## Transport & HTTP
+
+These control how the server listens when running with an HTTP transport.
+
+| Environment Variable | Type | Default | Description |
+|---|---|---|---|
+| `FASTMCP_TRANSPORT` | `Literal["stdio", "http", "sse", "streamable-http"]` | `stdio` | Default transport. |
+| `FASTMCP_HOST` | `str` | `127.0.0.1` | Host to bind to. |
+| `FASTMCP_PORT` | `int` | `8000` | Port to bind to. |
+| `FASTMCP_SSE_PATH` | `str` | `/sse` | Path for SSE endpoint. |
+| `FASTMCP_MESSAGE_PATH` | `str` | `/messages/` | Path for SSE message endpoint. |
+| `FASTMCP_STREAMABLE_HTTP_PATH` | `str` | `/mcp` | Path for Streamable HTTP endpoint. |
+| `FASTMCP_STATELESS_HTTP` | `bool` | `false` | Enable stateless HTTP mode (new transport per request). Useful for multi-worker deployments. |
+| `FASTMCP_JSON_RESPONSE` | `bool` | `false` | Use JSON responses instead of SSE for Streamable HTTP. |
+| `FASTMCP_HTTP_HOST_ORIGIN_PROTECTION` | `bool \| "auto"` | `false` | Validate `Host` and browser `Origin` headers for Streamable HTTP requests. `auto` protects localhost-bound servers and explicit host/origin allowlists. |
+| `FASTMCP_HTTP_ALLOWED_HOSTS` | `list[str] \| null` | `null` | Additional trusted hostnames when Host and Origin protection is enabled. Use a JSON array, such as `["mcp.example.com"]`. |
+| `FASTMCP_HTTP_ALLOWED_ORIGINS` | `list[str] \| null` | `null` | Browser origins trusted when Host and Origin protection is enabled. Configure CORS separately for cross-origin browser reads. Use a JSON array, such as `["https://app.example.com"]`. |
+| `FASTMCP_HTTP_SESSION_IDLE_TIMEOUT` | `float \| null` | `null` | Seconds a Streamable HTTP session may remain idle before it is terminated. The deadline resets on every request. When `null`, sessions never expire from inactivity. Not supported in stateless mode. |
+| `FASTMCP_DEBUG` | `bool` | `false` | Enable debug mode. |
+
+## Error Handling
+
+| Environment Variable | Type | Default | Description |
+|---|---|---|---|
+| `FASTMCP_MASK_ERROR_DETAILS` | `bool` | `false` | Mask error details before sending to clients. When enabled, only messages from explicitly raised `ToolError`, `ResourceError`, or `PromptError` are included in responses. |
+| `FASTMCP_STRICT_INPUT_VALIDATION` | `bool` | `false` | Strictly validate tool inputs against the JSON schema. When disabled, compatible inputs are coerced (e.g., the string `"10"` becomes the integer `10`). |
+| `FASTMCP_MOUNTED_COMPONENTS_RAISE_ON_LOAD_ERROR` | `bool` | `false` | Raise errors when loading mounted components instead of logging warnings. |
+
+## Client
+
+| Environment Variable | Type | Default | Description |
+|---|---|---|---|
+| `FASTMCP_CLIENT_INIT_TIMEOUT` | `float \| None` | None | Timeout in seconds for the client initialization handshake. Set to `0` or leave unset to disable. |
+| `FASTMCP_CLIENT_DISCONNECT_TIMEOUT` | `float` | `5` | Maximum time in seconds to wait for a clean disconnect before giving up. |
+| `FASTMCP_CLIENT_RAISE_FIRST_EXCEPTIONGROUP_ERROR` | `bool` | `true` | When an `ExceptionGroup` is raised, re-raise the first error directly instead of the group. Simplifies debugging but may mask secondary errors. |
+
+## CLI & Display
+
+| Environment Variable | Type | Default | Description |
+|---|---|---|---|
+| `FASTMCP_SHOW_SERVER_BANNER` | `bool` | `true` | Show the server banner on startup. Also controllable via `--no-banner` or `server.run(show_banner=False)`. |
+| `FASTMCP_CHECK_FOR_UPDATES` | `Literal["stable", "prerelease", "off"]` | `stable` | Update checking on CLI startup. `stable` checks stable releases only, `prerelease` includes pre-releases, `off` disables checking. |
+
+## Tasks (Docket)
+
+These configure the [Docket](https://github.com/prefecthq/docket) task queue used by [server tasks](/servers/tasks). All use the `FASTMCP_DOCKET_` prefix.
+
+<Warning>
+When setting Docket values in a `.env` file, use a **double** underscore: `FASTMCP_DOCKET__URL` (not `FASTMCP_DOCKET_URL`). This is because `.env` values are resolved through the parent `Settings` class, which uses `__` as its nested delimiter. As regular environment variables (e.g., `export`), the single-underscore form `FASTMCP_DOCKET_URL` works fine.
+</Warning>
+
+| Environment Variable | Type | Default | Description |
+|---|---|---|---|
+| `FASTMCP_DOCKET_NAME` | `str` | `fastmcp` | Queue name. Servers and workers sharing the same name and backend URL share a task queue. |
+| `FASTMCP_DOCKET_URL` | `str` | `memory://` | Backend URL. Use `memory://` for single-process or `redis://host:port/db` for distributed workers. |
+| `FASTMCP_DOCKET_WORKER_NAME` | `str \| None` | None | Worker name. Auto-generated if unset. |
+| `FASTMCP_DOCKET_CONCURRENCY` | `int` | `10` | Maximum concurrent tasks per worker. |
+| `FASTMCP_DOCKET_REDELIVERY_TIMEOUT` | `timedelta` | `300s` | If a worker doesn't complete a task within this time, it's redelivered to another worker. |
+| `FASTMCP_DOCKET_RECONNECTION_DELAY` | `timedelta` | `5s` | Delay between reconnection attempts when the worker loses its backend connection. |
+| `FASTMCP_DOCKET_MINIMUM_CHECK_INTERVAL` | `timedelta` | `50ms` | How frequently the worker polls for new tasks. Lower values reduce latency at the cost of more CPU usage. |
+
+## Advanced
+
+| Environment Variable | Type | Default | Description |
+|---|---|---|---|
+| `FASTMCP_HOME` | `Path` | Platform default | Data directory for FastMCP. Defaults to the platform-specific user data directory. |
+| `FASTMCP_ENV_FILE` | `str` | `.env` | Path to the `.env` file to load settings from. Must be set as an environment variable (see above). |
+| `FASTMCP_SERVER_DEPENDENCIES` | `list[str]` | `[]` | Additional dependencies to install in the server environment. |
+| `FASTMCP_TEST_MODE` | `bool` | `false` | Enable test mode. |
diff --git a/docs/patterns/cli.mdx b/docs/patterns/cli.mdx
new file mode 100644
index 0000000..fe32bdd
--- /dev/null
+++ b/docs/patterns/cli.mdx
@@ -0,0 +1,851 @@
+---
+title: FastMCP CLI
+sidebarTitle: CLI
+description: Learn how to use the FastMCP command-line interface
+icon: terminal
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+
+FastMCP provides a command-line interface (CLI) that makes it easy to run, develop, and install your MCP servers. The CLI is automatically installed when you install FastMCP.
+
+```bash
+fastmcp --help
+```
+
+## Commands Overview
+
+| Command | Purpose | Dependency Management |
+| ------- | ------- | --------------------- |
+| `list` | List tools on any MCP server | **Supports:** URLs, local files, MCPConfig JSON, stdio commands. **Deps:** N/A (connects to existing servers) |
+| `call` | Call a tool on any MCP server | **Supports:** URLs, local files, MCPConfig JSON, stdio commands. **Deps:** N/A (connects to existing servers) |
+| `run` | Run a FastMCP server directly | **Supports:** Local files, factory functions, URLs, fastmcp.json configs, MCP configs. **Deps:** Uses your local environment directly. With `--python`, `--with`, `--project`, or `--with-requirements`: Runs via `uv run` subprocess. With fastmcp.json: Automatically manages dependencies based on configuration |
+| `dev` | Run a server with the MCP Inspector for testing | **Supports:** Local files and fastmcp.json configs. **Deps:** Always runs via `uv run` subprocess (never uses your local environment); dependencies must be specified or available in a uv-managed project. With fastmcp.json: Uses configured dependencies |
+| `install` | Install a server in MCP client applications | **Supports:** Local files and fastmcp.json configs. **Deps:** Creates an isolated environment; dependencies must be explicitly specified with `--with` and/or `--with-editable`. With fastmcp.json: Uses configured dependencies |
+| `inspect` | Generate a JSON report about a FastMCP server | **Supports:** Local files and fastmcp.json configs. **Deps:** Uses your current environment; you are responsible for ensuring all dependencies are available |
+| `project prepare` | Create a persistent uv project from fastmcp.json environment config | **Supports:** fastmcp.json configs only. **Deps:** Creates a uv project directory with all dependencies pre-installed for reuse with `--project` flag |
+| `auth cimd` | Create and validate CIMD documents for OAuth authentication | N/A |
+| `version` | Display version information | N/A |
+
+## `fastmcp list`
+
+List tools available on any MCP server. This works with remote URLs, local Python files, MCPConfig JSON files, and arbitrary stdio commands. Together with `fastmcp call`, these commands are especially useful for giving LLMs that don't have built-in MCP support access to MCP tools via shell commands.
+
+```bash
+fastmcp list http://localhost:8000/mcp
+fastmcp list server.py
+fastmcp list mcp.json
+fastmcp list --command 'npx -y @modelcontextprotocol/server-github'
+```
+
+By default, the output shows each tool's signature and description. Use `--input-schema` or `--output-schema` to include full JSON schemas, or `--json` for machine-readable output.
+
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Command | `--command` | Connect to a stdio server command (e.g. `'npx -y @mcp/server'`) |
+| Transport | `--transport`, `-t` | Force transport type for URL targets (`http` or `sse`) |
+| Resources | `--resources` | Also list resources |
+| Prompts | `--prompts` | Also list prompts |
+| Input Schema | `--input-schema` | Show full input schemas |
+| Output Schema | `--output-schema` | Show full output schemas |
+| JSON | `--json` | Output as JSON |
+| Timeout | `--timeout` | Connection timeout in seconds |
+| Auth | `--auth` | Auth method: `oauth` (default for HTTP), a bearer token, or `none` to disable |
+
+### Server Targets
+
+The `<server>` argument accepts:
+
+1. **URLs** — `http://` or `https://` endpoints. Uses Streamable HTTP by default; pass `--transport sse` for SSE servers.
+2. **Python files** — `.py` files are run via `fastmcp run` automatically.
+3. **MCPConfig JSON** — `.json` files with an `mcpServers` key are treated as multi-server configs.
+4. **Stdio commands** — Use `--command` to connect to any MCP server via stdio (e.g. `npx`, `uvx`).
+
+### Examples
+
+```bash
+# List tools on a remote server
+fastmcp list http://localhost:8000/mcp
+
+# List tools from a local Python file
+fastmcp list server.py
+
+# Include full input schemas
+fastmcp list server.py --input-schema
+
+# Machine-readable JSON
+fastmcp list server.py --json
+
+# SSE server
+fastmcp list http://localhost:8000/mcp --transport sse
+
+# Stdio command
+fastmcp list --command 'npx -y @modelcontextprotocol/server-github'
+
+# Include resources and prompts
+fastmcp list server.py --resources --prompts
+```
+
+## `fastmcp call`
+
+Call a tool on any MCP server. Arguments can be passed as `key=value` pairs, a single JSON object, or via `--input-json`.
+
+```bash
+fastmcp call server.py greet name=World
+fastmcp call http://localhost:8000/mcp search query=hello limit=5
+fastmcp call server.py create_item '{"name": "x", "tags": ["a", "b"]}'
+```
+
+Tool arguments are automatically coerced to the correct type based on the tool's input schema — string values like `limit=5` become integers when the schema expects one.
+
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Command | `--command` | Connect to a stdio server command (e.g. `'npx -y @mcp/server'`) |
+| Transport | `--transport`, `-t` | Force transport type for URL targets (`http` or `sse`) |
+| Input JSON | `--input-json` | JSON string of tool arguments (merged with key=value args) |
+| JSON | `--json` | Output raw JSON result |
+| Timeout | `--timeout` | Connection timeout in seconds |
+| Auth | `--auth` | Auth method: `oauth` (default for HTTP), a bearer token, or `none` to disable |
+
+### Argument Passing
+
+There are three ways to pass arguments:
+
+**Key=value pairs** are the simplest for flat arguments. Values are coerced using the tool's JSON schema (strings become ints, bools, etc.):
+
+```bash
+fastmcp call server.py search query=hello limit=5 verbose=true
+```
+
+**A single JSON object** works when you have structured or nested arguments:
+
+```bash
+fastmcp call server.py create_item '{"name": "Widget", "tags": ["new", "sale"]}'
+```
+
+**`--input-json`** provides a base dict that key=value pairs can override:
+
+```bash
+fastmcp call server.py search --input-json '{"query": "hello", "limit": 5}' limit=10
+```
+
+### Examples
+
+```bash
+# Call a tool with simple args
+fastmcp call server.py greet name=World
+
+# Call with JSON object
+fastmcp call server.py create '{"name": "x", "tags": ["a"]}'
+
+# Get JSON output for scripting
+fastmcp call server.py add a=3 b=4 --json
+
+# Call a tool on a remote server
+fastmcp call http://localhost:8000/mcp search query=hello
+
+# Call via stdio command
+fastmcp call --command 'npx -y @mcp/server' tool_name arg=value
+
+# Disable OAuth for HTTP targets
+fastmcp call http://localhost:8000/mcp search query=hello --auth none
+```
+
+<Tip>
+If you call a tool that doesn't exist, FastMCP will suggest similar tool names. Use `fastmcp list` to see all available tools on a server.
+</Tip>
+
+## `fastmcp run`
+
+Run a FastMCP server directly or proxy a remote server.
+
+```bash
+fastmcp run server.py
+```
+
+<Tip>
+By default, this command runs the server directly in your current Python environment. You are responsible for ensuring all dependencies are available. When using `--python`, `--with`, `--project`, or `--with-requirements` options, it runs the server via `uv run` subprocess instead.
+</Tip>
+
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Transport | `--transport`, `-t` | Transport protocol to use (`stdio`, `http`, or `sse`) |
+| Host | `--host` | Host to bind to when using http transport (default: 127.0.0.1) |
+| Port | `--port`, `-p` | Port to bind to when using http transport (default: 8000) |
+| Path | `--path` | Path to bind to when using http transport (default: `/mcp/` or `/sse/` for SSE) |
+| Log Level | `--log-level`, `-l` | Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
+| No Banner | `--no-banner` | Disable the startup banner display |
+| Auto-Reload | `--reload` / `--no-reload` | Enable auto-reload on file changes (development mode) |
+| Reload Directories | `--reload-dir` | Directories to watch for changes (can be used multiple times) |
+| No Environment | `--skip-env` | Skip environment setup with uv (use when already in a uv environment) |
+| Python Version | `--python` | Python version to use (e.g., 3.10, 3.11) |
+| Additional Packages | `--with` | Additional packages to install (can be used multiple times) |
+| Project Directory | `--project` | Run the command within the given project directory |
+| Requirements File | `--with-requirements` | Requirements file to install dependencies from |
+
+
+### Entrypoints
+<VersionBadge version="2.3.5" />
+
+The `fastmcp run` command supports the following entrypoints:
+
+1. **[Inferred server instance](#inferred-server-instance)**: `server.py` - imports the module and looks for a FastMCP server instance named `mcp`, `server`, or `app`. Errors if no such object is found.
+2. **[Explicit server entrypoint](#explicit-server-entrypoint)**: `server.py:custom_name` - imports and uses the specified server entrypoint  
+3. **[Factory function](#factory-function)**: `server.py:create_server` - calls the specified function (sync or async) to create a server instance
+4. **[Remote server proxy](#remote-server-proxy)**: `https://example.com/mcp-server` - connects to a remote server and creates a **local proxy server**
+5. **[FastMCP configuration file](#fastmcp-configuration)**: `fastmcp.json` - runs servers using FastMCP's declarative configuration format (auto-detects files in current directory)
+6. **MCP configuration file**: `mcp.json` - runs servers defined in a standard MCP configuration file
+
+<Warning>
+Note: When using `fastmcp run` with a local file, it **completely ignores** the `if __name__ == "__main__"` block. This means:
+- Any setup code in `__main__` will NOT run
+- Server configuration in `__main__` is bypassed  
+- `fastmcp run` finds your server entrypoint/factory and runs it with its own transport settings
+
+If you need setup code to run, use the **factory pattern** instead.
+</Warning>
+
+#### Inferred Server Instance
+
+If you provide a path to a file, `fastmcp run` will load the file and look for a FastMCP server instance stored as a variable named `mcp`, `server`, or `app`. If no such object is found, it will raise an error.
+
+For example, if you have a file called `server.py` with the following content:
+
+```python server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")
+```
+
+You can run it with:
+
+```bash
+fastmcp run server.py
+```
+
+#### Explicit Server Entrypoint
+
+If your server is stored as a variable with a custom name, or you want to be explicit about which server to run, you can use the following syntax to load a specific server entrypoint:
+
+```bash
+fastmcp run server.py:custom_name
+```
+
+For example, if you have a file called `server.py` with the following content:
+
+```python
+from fastmcp import FastMCP
+
+my_server = FastMCP("CustomServer")
+
+@my_server.tool
+def hello() -> str:
+    return "Hello from custom server!"
+```
+
+You can run it with:
+
+```bash
+fastmcp run server.py:my_server
+```
+
+#### Factory Function
+<VersionBadge version="2.11.2" />
+
+Since `fastmcp run` ignores the `if __name__ == "__main__"` block, you can use a factory function to run setup code before your server starts. Factory functions are called without any arguments and must return a FastMCP server instance. Both sync and async factory functions are supported.
+
+The syntax for using a factory function is the same as for an explicit server entrypoint: `fastmcp run server.py:factory_fn`. FastMCP will automatically detect that you have identified a function rather than a server Instance
+
+For example, if you have a file called `server.py` with the following content:
+
+```python
+from fastmcp import FastMCP
+
+async def create_server() -> FastMCP:
+    mcp = FastMCP("MyServer")
+    
+    @mcp.tool
+    def add(x: int, y: int) -> int:
+        return x + y
+    
+    # Setup that runs with fastmcp run
+    tool = await mcp.get_tool("add")
+    tool.disable()
+    
+    return mcp
+```
+
+You can run it with:
+
+```bash
+fastmcp run server.py:create_server
+```
+
+#### Remote Server Proxy
+
+FastMCP run can also start a local proxy server that connects to a remote server. This is useful when you want to run a remote server locally for testing or development purposes, or to use with a client that doesn't support direct connections to remote servers.
+
+To start a local proxy, you can use the following syntax:
+
+```bash
+fastmcp run https://example.com/mcp
+```
+
+#### FastMCP Configuration
+<VersionBadge version="2.11.4" />
+
+FastMCP supports declarative configuration through `fastmcp.json` files. When you run `fastmcp run` without arguments, it automatically looks for a `fastmcp.json` file in the current directory:
+
+```bash
+# Auto-detect fastmcp.json in current directory
+fastmcp run
+
+# Or explicitly specify a configuration file
+fastmcp run my-config.fastmcp.json
+```
+
+The configuration file handles dependencies, environment variables, and transport settings. Command-line arguments override configuration file values:
+
+```bash
+# Override port from config file
+fastmcp run fastmcp.json --port 8080
+
+# Skip environment setup when already in a uv environment
+fastmcp run fastmcp.json --skip-env
+```
+
+<Note>
+The `--skip-env` flag is useful when:
+- You're already in an activated virtual environment
+- You're inside a Docker container with pre-installed dependencies  
+- You're in a uv-managed environment (prevents infinite recursion)
+- You want to test the server without environment setup
+</Note>
+
+See [Server Configuration](/deployment/server-configuration) for detailed documentation on fastmcp.json.
+
+#### MCP Configuration
+
+FastMCP can also run servers defined in a standard MCP configuration file. This is useful when you want to run multiple servers from a single file, or when you want to use a client that doesn't support direct connections to remote servers.
+
+To run a MCP configuration file, you can use the following syntax:
+
+```bash
+fastmcp run mcp.json
+```
+
+This will run all the servers defined in the file.
+
+## `fastmcp dev`
+
+The `dev` command group contains development tools for MCP servers.
+
+### `fastmcp dev inspector`
+
+Run a MCP server with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for testing. Auto-reload is enabled by default, so your server automatically restarts when you save changes to source files.
+
+```bash
+fastmcp dev inspector server.py
+```
+
+<Tip>
+This command always runs your server via `uv run` subprocess (never your local environment) to work with the MCP Inspector. Dependencies can be:
+- Specified using `--with` and/or `--with-editable` options
+- Defined in a `fastmcp.json` configuration file
+- Available in a uv-managed project
+
+When using `fastmcp.json`, the dev command automatically uses the configured dependencies.
+</Tip>
+
+<Warning>
+The `dev inspector` command is a shortcut for testing a server over STDIO only. When the Inspector launches, you may need to:
+1. Select "STDIO" from the transport dropdown
+2. Connect manually
+
+This command does not support HTTP testing. To test a server over Streamable HTTP or SSE:
+1. Start your server manually with the appropriate transport using either the command line:
+   ```bash
+   fastmcp run server.py --transport http
+   ```
+   or by setting the transport in your code:
+   ```bash
+   python server.py  # Assuming your __main__ block sets Streamable HTTP transport
+   ```
+2. Open the MCP Inspector separately and connect to your running server
+</Warning>
+
+#### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Editable Package | `--with-editable`, `-e` | Directory containing pyproject.toml to install in editable mode |
+| Additional Packages | `--with` | Additional packages to install (can be used multiple times) |
+| Inspector Version | `--inspector-version` | Version of the MCP Inspector to use |
+| UI Port | `--ui-port` | Port for the MCP Inspector UI |
+| Server Port | `--server-port` | Port for the MCP Inspector Proxy server |
+| Auto-Reload | `--reload` / `--no-reload` | Enable/disable auto-reload on file changes (enabled by default) |
+| Reload Directories | `--reload-dir` | Directories to watch for changes (can be used multiple times) |
+| Python Version | `--python` | Python version to use (e.g., 3.10, 3.11) |
+| Project Directory | `--project` | Run the command within the given project directory |
+| Requirements File | `--with-requirements` | Requirements file to install dependencies from |
+
+#### Entrypoints
+
+The `dev inspector` command supports local FastMCP server files and configuration:
+
+1. **Inferred server instance**: `server.py` - imports the module and looks for a FastMCP server instance named `mcp`, `server`, or `app`. Errors if no such object is found.
+2. **Explicit server entrypoint**: `server.py:custom_name` - imports and uses the specified server entrypoint
+3. **Factory function**: `server.py:create_server` - calls the specified function (sync or async) to create a server instance
+4. **FastMCP configuration**: `fastmcp.json` - uses FastMCP's declarative configuration (auto-detects in current directory)
+
+<Warning>
+The `dev inspector` command **only supports local files and fastmcp.json** - no URLs, remote servers, or standard MCP configuration files.
+</Warning>
+
+**Examples**
+
+```bash
+# Run dev server with editable mode and additional packages
+fastmcp dev inspector server.py -e . --with pandas --with matplotlib
+
+# Run dev server with fastmcp.json configuration (auto-detects)
+fastmcp dev inspector
+
+# Run dev server with explicit fastmcp.json file
+fastmcp dev inspector dev.fastmcp.json
+
+# Run dev server with specific Python version
+fastmcp dev inspector server.py --python 3.11
+
+# Run dev server with requirements file
+fastmcp dev inspector server.py --with-requirements requirements.txt
+
+# Run dev server within a specific project directory
+fastmcp dev inspector server.py --project /path/to/project
+```
+
+## `fastmcp install`
+<VersionBadge version="2.10.3" />
+
+Install a MCP server in MCP client applications. FastMCP currently supports the following clients:
+
+- **Claude Code** - Installs via Claude Code's built-in MCP management system
+- **Claude Desktop** - Installs via direct configuration file modification
+- **Cursor** - Installs via deeplink that opens Cursor for user confirmation
+- **Gemini CLI** - Installs via Gemini CLI's built-in MCP management system
+- **Goose** - Installs via deeplink that opens Goose for user confirmation (uses `uvx`)
+- **MCP JSON** - Generates standard MCP JSON configuration for manual use
+- **Stdio** - Outputs the shell command to run a server over stdio transport
+
+```bash
+fastmcp install claude-code server.py
+fastmcp install claude-desktop server.py
+fastmcp install cursor server.py
+fastmcp install gemini-cli server.py
+fastmcp install goose server.py
+fastmcp install mcp-json server.py
+fastmcp install stdio server.py
+```
+
+Note that for security reasons, MCP clients usually run every server in a completely isolated environment. Therefore, all dependencies must be explicitly specified using the `--with` and/or `--with-editable` options (following `uv` conventions) or by attaching them to your server in code via the `dependencies` parameter. You should not assume that the MCP server will have access to your local environment.
+
+<Warning>
+**`uv` must be installed and available in your system PATH**. Both Claude Desktop and Cursor run in isolated environments and need `uv` to manage dependencies. On macOS, install `uv` globally with Homebrew for Claude Desktop compatibility: `brew install uv`.
+</Warning>
+
+<Note>
+**Python Version Considerations**: The install commands now support the `--python` option to specify a Python version directly. You can also use `--project` to run within a specific project directory or `--with-requirements` to install dependencies from a requirements file.
+</Note>
+
+<Tip>
+**FastMCP `install` commands focus on local server files with STDIO transport.** For remote servers running with HTTP or SSE transport, use your client's native configuration - FastMCP's value is simplifying the complex local setup with dependencies and `uv` commands.
+</Tip>
+
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Server Name | `--server-name`, `-n` | Custom name for the server (defaults to server's name attribute or file name) |
+| Editable Package | `--with-editable`, `-e` | Directory containing pyproject.toml to install in editable mode |
+| Additional Packages | `--with` | Additional packages to install (can be used multiple times) |
+| Environment Variables | `--env` | Environment variables in KEY=VALUE format (can be used multiple times) |
+| Environment File | `--env-file`, `-f` | Load environment variables from a .env file |
+| Python Version | `--python` | Python version to use (e.g., 3.10, 3.11) |
+| Project Directory | `--project` | Run the command within the given project directory |
+| Requirements File | `--with-requirements` | Requirements file to install dependencies from |
+
+### Entrypoints
+
+The `install` command supports local FastMCP server files and configuration:
+
+1. **Inferred server instance**: `server.py` - imports the module and looks for a FastMCP server instance named `mcp`, `server`, or `app`. Errors if no such object is found.
+2. **Explicit server entrypoint**: `server.py:custom_name` - imports and uses the specified server entrypoint  
+3. **Factory function**: `server.py:create_server` - calls the specified function (sync or async) to create a server instance
+4. **FastMCP configuration**: `fastmcp.json` - uses FastMCP's declarative configuration with dependencies and settings
+
+<Note>
+Factory functions are particularly useful for install commands since they allow setup code to run that would otherwise be ignored when the MCP client runs your server. When using fastmcp.json, dependencies are automatically handled.
+</Note>
+
+<Warning>
+The `install` command **only supports local files and fastmcp.json** - no URLs, remote servers, or standard MCP configuration files. For remote servers, use your MCP client's native configuration.
+</Warning>
+
+**Examples**
+
+```bash
+# Auto-detects server entrypoint (looks for 'mcp', 'server', or 'app')
+fastmcp install claude-desktop server.py
+
+# Install with fastmcp.json configuration (auto-detects)
+fastmcp install claude-desktop
+
+# Install with explicit fastmcp.json file
+fastmcp install claude-desktop my-config.fastmcp.json
+
+# Uses specific server entrypoint
+fastmcp install claude-desktop server.py:my_server
+
+# With custom name and dependencies
+fastmcp install claude-desktop server.py:my_server --server-name "My Analysis Server" --with pandas
+
+# Install in Claude Code with environment variables
+fastmcp install claude-code server.py --env API_KEY=secret --env DEBUG=true
+
+# Install in Cursor with environment variables
+fastmcp install cursor server.py --env API_KEY=secret --env DEBUG=true
+
+# Install with environment file
+fastmcp install cursor server.py --env-file .env
+
+# Install in Goose (uses uvx deeplink)
+fastmcp install goose server.py --with pandas
+
+# Install with specific Python version
+fastmcp install claude-desktop server.py --python 3.11
+
+# Install with requirements file
+fastmcp install claude-code server.py --with-requirements requirements.txt
+
+# Install within a project directory
+fastmcp install cursor server.py --project /path/to/project
+
+# Generate MCP JSON configuration
+fastmcp install mcp-json server.py --name "My Server" --with pandas
+
+# Copy JSON configuration to clipboard
+fastmcp install mcp-json server.py --copy
+
+# Output the stdio command for running a server
+fastmcp install stdio server.py
+
+# Output the stdio command from a fastmcp.json (includes configured dependencies)
+fastmcp install stdio fastmcp.json
+
+# Copy the stdio command to clipboard
+fastmcp install stdio server.py --copy
+```
+
+### MCP JSON Generation
+
+The `mcp-json` subcommand generates standard MCP JSON configuration that can be used with any MCP-compatible client. This is useful when:
+
+- Working with MCP clients not directly supported by FastMCP
+- Creating configuration for CI/CD environments  
+- Sharing server configurations with others
+- Integration with custom tooling
+
+The generated JSON follows the standard MCP server configuration format used by Claude Desktop, VS Code, Cursor, and other MCP clients, with the server name as the root key:
+
+```json
+{
+  "server-name": {
+    "command": "uv",
+    "args": [
+      "run",
+      "--with",
+      "fastmcp",
+      "fastmcp",
+      "run",
+      "/path/to/server.py"
+    ],
+    "env": {
+      "API_KEY": "value"
+    }
+  }
+}
+```
+
+<Note>
+To use this configuration with your MCP client, you'll typically need to add it to the client's `mcpServers` object. Consult your client's documentation for any specific configuration requirements or formatting needs.
+</Note>
+
+**Options specific to mcp-json:**
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Copy to Clipboard | `--copy` | Copy configuration to clipboard instead of printing to stdout |
+
+### Stdio Command
+
+The `stdio` subcommand outputs the shell command an MCP host uses to start your server over stdio transport. Use it when you need a ready-to-paste `uv run --with fastmcp fastmcp run ...` command for a tool or script without a dedicated install target.
+
+```bash
+# Print the command to stdout
+fastmcp install stdio server.py
+
+# Output: uv run --with fastmcp fastmcp run /absolute/path/to/server.py
+```
+
+When you pass a `fastmcp.json`, FastMCP automatically includes dependencies from the configuration:
+
+```bash
+fastmcp install stdio fastmcp.json
+
+# Output: uv run --with fastmcp --with pillow --with 'qrcode[pil]>=8.0' fastmcp run /absolute/path/to/qr_server.py
+```
+
+Use `--copy` to send the command directly to your clipboard:
+
+```bash
+fastmcp install stdio server.py --copy
+# ✓ Command copied to clipboard
+```
+
+**Options specific to stdio:**
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Copy to Clipboard | `--copy` | Copy command to clipboard instead of printing to stdout |
+
+## `fastmcp inspect`
+
+<VersionBadge version="2.9.0" />
+
+Inspect a FastMCP server to view summary information or generate a detailed JSON report.
+
+```bash
+# Show text summary
+fastmcp inspect server.py
+
+# Output FastMCP JSON to stdout
+fastmcp inspect server.py --format fastmcp
+
+# Save MCP JSON to file (format required with -o)
+fastmcp inspect server.py --format mcp -o manifest.json
+```
+
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Format | `--format`, `-f` | Output format: `fastmcp` (FastMCP-specific) or `mcp` (MCP protocol). Required when using `-o` |
+| Output File | `--output`, `-o` | Save JSON report to file instead of stdout. Requires `--format` |
+
+### Output Formats
+
+#### FastMCP Format (`--format fastmcp`)
+The default and most comprehensive format, includes all FastMCP-specific metadata:
+- Server name, instructions, and version
+- FastMCP version and MCP version
+- Tool tags and enabled status
+- Output schemas for tools
+- Annotations and custom metadata
+- Uses snake_case field names
+- **Use this for**: Complete server introspection and debugging FastMCP servers
+
+#### MCP Protocol Format (`--format mcp`)
+Shows exactly what MCP clients will see via the protocol:
+- Only includes standard MCP protocol fields
+- Matches output from `client.list_tools()`, `client.list_prompts()`, etc.
+- Uses camelCase field names (e.g., `inputSchema`)
+- Excludes FastMCP-specific fields like tags and enabled status
+- **Use this for**: Debugging client visibility and ensuring MCP compatibility
+
+### Entrypoints
+
+The `inspect` command supports local FastMCP server files and configuration:
+
+1. **Inferred server instance**: `server.py` - imports the module and looks for a FastMCP server instance named `mcp`, `server`, or `app`. Errors if no such object is found.
+2. **Explicit server entrypoint**: `server.py:custom_name` - imports and uses the specified server entrypoint  
+3. **Factory function**: `server.py:create_server` - calls the specified function (sync or async) to create a server instance
+4. **FastMCP configuration**: `fastmcp.json` - inspects servers defined with FastMCP's declarative configuration
+
+<Warning>
+The `inspect` command **only supports local files and fastmcp.json** - no URLs, remote servers, or standard MCP configuration files.
+</Warning>
+
+### Examples
+
+```bash
+# Show text summary (no JSON output)
+fastmcp inspect server.py
+# Output: 
+# Server: MyServer
+# Instructions: A helpful MCP server
+# Version: 1.0.0
+#
+# Components:
+#   Tools: 5
+#   Prompts: 2
+#   Resources: 3
+#   Templates: 1
+#
+# Environment:
+#   FastMCP: 2.0.0
+#   MCP: 1.0.0
+#
+# Use --format [fastmcp|mcp] for complete JSON output
+
+# Output FastMCP format to stdout
+fastmcp inspect server.py --format fastmcp
+
+# Specify server entrypoint
+fastmcp inspect server.py:my_server
+
+# Output MCP protocol format to stdout
+fastmcp inspect server.py --format mcp
+
+# Save to file (format required)
+fastmcp inspect server.py --format fastmcp -o server-manifest.json
+
+# Save MCP format with custom server object
+fastmcp inspect server.py:my_server --format mcp -o mcp-manifest.json
+
+# Error: format required with output file
+fastmcp inspect server.py -o output.json
+# Error: --format is required when using -o/--output
+```
+
+## `fastmcp project prepare`
+
+Create a persistent uv project directory from a fastmcp.json file's environment configuration. This allows you to pre-install all dependencies once and reuse them with the `--project` flag.
+
+```bash
+fastmcp project prepare fastmcp.json --output-dir ./env
+```
+
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Output Directory | `--output-dir` | **Required.** Directory where the persistent uv project will be created |
+
+### Usage Pattern
+
+```bash
+# Step 1: Prepare the environment (installs dependencies)
+fastmcp project prepare fastmcp.json --output-dir ./my-env
+
+# Step 2: Run using the prepared environment (fast, no dependency installation)
+fastmcp run fastmcp.json --project ./my-env
+```
+
+The prepare command creates a uv project with:
+- A `pyproject.toml` containing all dependencies from the fastmcp.json
+- A `.venv` with all packages pre-installed
+- A `uv.lock` file for reproducible environments
+
+This is useful when you want to separate environment setup from server execution, such as in deployment scenarios where dependencies are installed once and the server is run multiple times.
+
+## `fastmcp auth`
+
+<VersionBadge version="3.0.0" />
+
+Authentication-related utilities and configuration commands.
+
+### `fastmcp auth cimd create`
+
+Generate a CIMD (Client ID Metadata Document) for hosting. This creates a JSON document that you can host at an HTTPS URL to use as your OAuth client identity.
+
+```bash
+fastmcp auth cimd create --name "My App" --redirect-uri "http://localhost:*/callback"
+```
+
+#### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Name | `--name` | **Required.** Human-readable name of the client application |
+| Redirect URI | `--redirect-uri` | **Required.** Allowed redirect URIs (can specify multiple) |
+| Client URI | `--client-uri` | URL of the client's home page |
+| Logo URI | `--logo-uri` | URL of the client's logo image |
+| Scope | `--scope` | Space-separated list of scopes the client may request |
+| Output | `--output`, `-o` | Output file path (default: stdout) |
+| Pretty | `--pretty` | Pretty-print JSON output (default: true) |
+
+#### Example
+
+```bash
+# Generate document to stdout
+fastmcp auth cimd create \
+    --name "My Production App" \
+    --redirect-uri "http://localhost:*/callback" \
+    --redirect-uri "https://myapp.example.com/callback" \
+    --client-uri "https://myapp.example.com" \
+    --scope "read write"
+
+# Save to file
+fastmcp auth cimd create \
+    --name "My App" \
+    --redirect-uri "http://localhost:*/callback" \
+    --output client.json
+```
+
+The generated document includes a placeholder `client_id` that you must update to match the URL where you'll host the document before deploying.
+
+### `fastmcp auth cimd validate`
+
+Validate a hosted CIMD document by fetching it from its URL and checking that it conforms to the CIMD specification.
+
+```bash
+fastmcp auth cimd validate https://myapp.example.com/oauth/client.json
+```
+
+#### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Timeout | `--timeout`, `-t` | HTTP request timeout in seconds (default: 10) |
+
+The validator checks:
+
+- The URL is a valid CIMD URL (HTTPS with non-root path)
+- The document is valid JSON and conforms to the CIMD schema
+- The `client_id` field in the document matches the URL
+- No shared-secret authentication methods are used
+
+On success, it displays the document details:
+
+```
+→ Fetching https://myapp.example.com/oauth/client.json...
+✓ Valid CIMD document
+
+Document details:
+  client_id: https://myapp.example.com/oauth/client.json
+  client_name: My App
+  token_endpoint_auth_method: none
+  redirect_uris:
+    • http://localhost:*/callback
+```
+
+## `fastmcp version`
+
+Display version information about FastMCP and related components.
+
+```bash
+fastmcp version
+```
+
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Copy to Clipboard | `--copy` | Copy version information to clipboard |
diff --git a/docs/patterns/contrib.mdx b/docs/patterns/contrib.mdx
new file mode 100644
index 0000000..04ef45a
--- /dev/null
+++ b/docs/patterns/contrib.mdx
@@ -0,0 +1,45 @@
+---
+title: "Contrib Modules"
+description: "Community-contributed modules extending FastMCP"
+icon: "cubes"
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.2.1" />
+
+FastMCP includes a `contrib` package that holds community-contributed modules. These modules extend FastMCP's functionality but aren't officially maintained by the core team.
+
+Contrib modules provide additional features, integrations, or patterns that complement the core FastMCP library. They offer a way for the community to share useful extensions while keeping the core library focused and maintainable.
+
+The available modules can be viewed in the [contrib directory](https://github.com/PrefectHQ/fastmcp/tree/main/fastmcp_slim/fastmcp/contrib).
+
+## Usage
+
+To use a contrib module, import it from the `fastmcp.contrib` package:
+
+```python test="skip"
+from fastmcp.contrib import my_module
+```
+
+## Important Considerations
+
+- **Stability**: Modules in `contrib` may have different testing requirements or stability guarantees compared to the core library.
+- **Compatibility**: Changes to core FastMCP might break modules in `contrib` without explicit warnings in the main changelog.
+- **Dependencies**: Contrib modules may have additional dependencies not required by the core library. These dependencies are typically documented in the module's README or separate requirements files.
+
+## Contributing
+
+We welcome contributions to the `contrib` package! If you have a module that extends FastMCP in a useful way, consider contributing it:
+
+1. Create a new directory in `fastmcp_slim/fastmcp/contrib/` for your module
+3. Add proper tests for your module in `tests/contrib/`
+2. Include comprehensive documentation in a README.md file, including usage and examples, as well as any additional dependencies or installation instructions
+5. Submit a pull request
+
+The ideal contrib module:
+- Solves a specific use case or integration need
+- Follows FastMCP coding standards
+- Includes thorough documentation and examples
+- Has comprehensive tests
+- Specifies any additional dependencies
diff --git a/docs/patterns/testing.mdx b/docs/patterns/testing.mdx
new file mode 100644
index 0000000..7bd8600
--- /dev/null
+++ b/docs/patterns/testing.mdx
@@ -0,0 +1,104 @@
+---
+title: Testing your FastMCP Server
+sidebarTitle: Testing
+description: How to test your FastMCP server.
+icon: vial
+---
+
+The best way to ensure a reliable and maintainable FastMCP Server is to test it! The FastMCP Client combined with Pytest provides a simple and powerful way to test your FastMCP servers.
+
+## Prerequisites
+
+Testing FastMCP servers requires `pytest-asyncio` to handle async test functions and fixtures. Install it as a development dependency:
+
+```bash
+pip install pytest-asyncio
+```
+
+We recommend configuring pytest to automatically handle async tests by setting the asyncio mode to `auto` in your `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+```
+
+This eliminates the need to decorate every async test with `@pytest.mark.asyncio`.
+
+## Testing with Pytest Fixtures
+
+Using Pytest Fixtures, you can wrap your FastMCP Server in a Client instance that makes interacting with your server fast and easy. This is especially useful when building your own MCP Servers and enables a tight development loop by allowing you to avoid using a separate tool like MCP Inspector during development:
+
+```python
+import pytest
+from fastmcp.client import Client
+from fastmcp.client.transports import FastMCPTransport
+
+from my_project.main import mcp
+
+@pytest.fixture
+async def main_mcp_client():
+    async with Client(transport=mcp) as mcp_client:
+        yield mcp_client
+
+async def test_list_tools(main_mcp_client: Client[FastMCPTransport]):
+    list_tools = await main_mcp_client.list_tools()
+
+    assert len(list_tools) == 5
+```
+
+We recommend the [inline-snapshot library](https://github.com/15r10nk/inline-snapshot) for asserting complex data structures coming from your MCP Server. This library allows you to write tests that are easy to read and understand, and are also easy to update when the data structure changes. 
+
+```python
+from inline_snapshot import snapshot
+
+async def test_list_tools(main_mcp_client: Client[FastMCPTransport]):
+    list_tools = await main_mcp_client.list_tools()
+
+    assert list_tools == snapshot()
+```
+
+Simply run `pytest --inline-snapshot=fix,create` to fill in the `snapshot()` with actual data.
+
+<Tip>
+For values that change you can leverage the [dirty-equals](https://github.com/samuelcolvin/dirty-equals) library to perform flexible equality assertions on dynamic or non-deterministic values.
+</Tip>
+
+Using the pytest `parametrize` decorator, you can easily test your tools with a wide variety of inputs.
+
+```python
+import pytest
+from my_project.main import mcp
+
+from fastmcp.client import Client
+from fastmcp.client.transports import FastMCPTransport
+@pytest.fixture
+async def main_mcp_client():
+    async with Client(mcp) as client:
+        yield client
+
+
+@pytest.mark.parametrize(
+    "first_number, second_number, expected",
+    [
+        (1, 2, 3),
+        (2, 3, 5),
+        (3, 4, 7),
+    ],
+)
+async def test_add(
+    first_number: int,
+    second_number: int,
+    expected: int,
+    main_mcp_client: Client[FastMCPTransport],
+):
+    result = await main_mcp_client.call_tool(
+        name="add", arguments={"x": first_number, "y": second_number}
+    )
+    assert result.data is not None
+    assert isinstance(result.data, int)
+    assert result.data == expected
+```
+
+<Tip>
+The [FastMCP Repository contains thousands of tests](https://github.com/PrefectHQ/fastmcp/tree/main/tests) for the FastMCP Client and Server. Everything from connecting to remote MCP servers, to testing tools, resources, and prompts is covered, take a look for inspiration!
+</Tip>
\ No newline at end of file
diff --git a/docs/prefab-demo-payloads.js b/docs/prefab-demo-payloads.js
new file mode 100644
index 0000000..885ce71
--- /dev/null
+++ b/docs/prefab-demo-payloads.js
@@ -0,0 +1 @@
+window.__FASTMCP_PREFAB_DEMOS__ = {"bar-chart":"<!doctype html>\n<html lang=\"en\">\n<head>\n  <title>Prefab</title>\n  <meta charset=\"UTF-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <link rel=\"stylesheet\" crossorigin href=\"https://cdn.jsdelivr.net/npm/@prefecthq/prefab-ui@0.19.0/dist/app/renderer.css\">\n  <script type=\"module\" crossorigin src=\"https://cdn.jsdelivr.net/npm/@prefecthq/prefab-ui@0.19.0/dist/app/renderer.js\"></script>\n</head>\n<body>\n  <div id=\"root\" style=\"max-width:64rem;margin:0 auto;padding:2rem\"></div>\n  <script id=\"prefab:initial-data\" type=\"application/json\">{\n  \"$prefab\": {\n    \"version\": \"0.2\"\n  },\n  \"view\": {\n    \"cssClass\": \"pf-app-root\",\n    \"type\": \"Div\",\n    \"children\": [\n      {\n        \"cssClass\": \"p-6\",\n        \"type\": \"Column\",\n        \"children\": [\n          {\n            \"type\": \"BarChart\",\n            \"data\": [\n              {\n                \"quarter\": \"Q1\",\n                \"revenue\": 42000,\n                \"costs\": 28000\n              },\n              {\n                \"quarter\": \"Q2\",\n                \"revenue\": 51000,\n                \"costs\": 31000\n              },\n              {\n                \"quarter\": \"Q3\",\n                \"revenue\": 47000,\n                \"costs\": 29000\n              },\n              {\n                \"quarter\": \"Q4\",\n                \"revenue\": 63000,\n                \"costs\": 35000\n              }\n            ],\n            \"series\": [\n              {\n                \"dataKey\": \"revenue\",\n                \"label\": \"Revenue\"\n              },\n              {\n                \"dataKey\": \"costs\",\n                \"label\": \"Costs\"\n              }\n            ],\n            \"xAxis\": \"quarter\",\n            \"height\": 250,\n            \"stacked\": false,\n            \"horizontal\": false,\n            \"barRadius\": 4,\n            \"showLegend\": true,\n            \"showTooltip\": true,\n            \"animate\": true,\n            \"showGrid\": true,\n            \"showYAxis\": true,\n            \"yAxisFormat\": \"auto\"\n          }\n        ]\n      }\n    ]\n  }\n}</script>\n</body>\n</html>","contacts":"<!doctype html>\n<html lang=\"en\">\n<head>\n  <title>Prefab</title>\n  <meta charset=\"UTF-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <link rel=\"stylesheet\" crossorigin href=\"https://cdn.jsdelivr.net/npm/@prefecthq/prefab-ui@0.19.0/dist/app/renderer.css\">\n  <script type=\"module\" crossorigin src=\"https://cdn.jsdelivr.net/npm/@prefecthq/prefab-ui@0.19.0/dist/app/renderer.js\"></script>\n</head>\n<body>\n  <div id=\"root\" style=\"max-width:64rem;margin:0 auto;padding:2rem\"></div>\n  <script id=\"prefab:initial-data\" type=\"application/json\">{\n  \"$prefab\": {\n    \"version\": \"0.2\"\n  },\n  \"view\": {\n    \"cssClass\": \"pf-app-root\",\n    \"type\": \"Div\",\n    \"children\": [\n      {\n        \"cssClass\": \"gap-4 p-6\",\n        \"type\": \"Column\",\n        \"children\": [\n          {\n            \"type\": \"DataTable\",\n            \"columns\": [\n              {\n                \"key\": \"name\",\n                \"header\": \"Name\",\n                \"sortable\": true\n              },\n              {\n                \"key\": \"email\",\n                \"header\": \"Email\",\n                \"sortable\": false\n              },\n              {\n                \"key\": \"category\",\n                \"header\": \"Category\",\n                \"sortable\": false\n              }\n            ],\n            \"rows\": [\n              {\n                \"name\": \"Arthur Dent\",\n                \"email\": \"arthur@earth.com\",\n                \"category\": {\n                  \"type\": \"Badge\",\n                  \"label\": \"Customer\",\n                  \"variant\": \"success\"\n                }\n              },\n              {\n                \"name\": \"Ford Prefect\",\n                \"email\": \"ford@betelgeuse.org\",\n                \"category\": {\n                  \"type\": \"Badge\",\n                  \"label\": \"Partner\",\n                  \"variant\": \"secondary\"\n                }\n              },\n              {\n                \"name\": \"Trillian Astra\",\n                \"email\": \"trillian@heartofgold.com\",\n                \"category\": {\n                  \"type\": \"Badge\",\n                  \"label\": \"Customer\",\n                  \"variant\": \"success\"\n                }\n              },\n              {\n                \"name\": \"Zaphod Beeblebrox\",\n                \"email\": \"zaphod@galaxy.gov\",\n                \"category\": {\n                  \"type\": \"Badge\",\n                  \"label\": \"Vendor\",\n                  \"variant\": \"outline\"\n                }\n              }\n            ],\n            \"search\": true,\n            \"paginated\": false,\n            \"pageSize\": 10\n          },\n          {\n            \"type\": \"Separator\",\n            \"orientation\": \"horizontal\"\n          },\n          {\n            \"content\": \"Add Contact\",\n            \"type\": \"H3\"\n          },\n          {\n            \"cssClass\": \"gap-4\",\n            \"type\": \"Form\",\n            \"onSubmit\": {\n              \"action\": \"showToast\",\n              \"message\": \"Contact saved! (preview demo \\u2014 no backend wired)\",\n              \"variant\": \"success\"\n            },\n            \"children\": [\n              {\n                \"cssClass\": \"gap-4\",\n                \"type\": \"Row\",\n                \"children\": [\n                  {\n                    \"name\": \"name\",\n                    \"type\": \"Input\",\n                    \"inputType\": \"text\",\n                    \"placeholder\": \"Full name\",\n                    \"disabled\": false,\n                    \"readOnly\": false,\n                    \"required\": true\n                  },\n                  {\n                    \"name\": \"email\",\n                    \"type\": \"Input\",\n                    \"inputType\": \"text\",\n                    \"placeholder\": \"name@example.com\",\n                    \"disabled\": false,\n                    \"readOnly\": false,\n                    \"required\": true\n                  }\n                ]\n              },\n              {\n                \"name\": \"category\",\n                \"type\": \"Select\",\n                \"size\": \"default\",\n                \"disabled\": false,\n                \"required\": false,\n                \"invalid\": false,\n                \"children\": [\n                  {\n                    \"type\": \"SelectOption\",\n                    \"value\": \"Customer\",\n                    \"label\": \"Customer\",\n                    \"selected\": false,\n                    \"disabled\": false\n                  },\n                  {\n                    \"type\": \"SelectOption\",\n                    \"value\": \"Partner\",\n                    \"label\": \"Partner\",\n                    \"selected\": false,\n                    \"disabled\": false\n                  },\n                  {\n                    \"type\": \"SelectOption\",\n                    \"value\": \"Vendor\",\n                    \"label\": \"Vendor\",\n                    \"selected\": false,\n                    \"disabled\": false\n                  }\n                ]\n              },\n              {\n                \"type\": \"Button\",\n                \"label\": \"Save Contact\",\n                \"variant\": \"default\",\n                \"size\": \"default\",\n                \"disabled\": false\n              }\n            ]\n          }\n        ]\n      }\n    ]\n  }\n}</script>\n</body>\n</html>","dashboard":"<!doctype html>\n<html lang=\"en\">\n<head>\n  <title>Prefab</title>\n  <meta charset=\"UTF-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <link rel=\"stylesheet\" crossorigin href=\"https://cdn.jsdelivr.net/npm/@prefecthq/prefab-ui@0.19.0/dist/app/renderer.css\">\n  <script type=\"module\" crossorigin src=\"https://cdn.jsdelivr.net/npm/@prefecthq/prefab-ui@0.19.0/dist/app/renderer.js\"></script>\n</head>\n<body>\n  <div id=\"root\" style=\"max-width:64rem;margin:0 auto;padding:2rem\"></div>\n  <script id=\"prefab:initial-data\" type=\"application/json\">{\n  \"$prefab\": {\n    \"version\": \"0.2\"\n  },\n  \"view\": {\n    \"cssClass\": \"pf-app-root\",\n    \"type\": \"Div\",\n    \"children\": [\n      {\n        \"cssClass\": \"gap-4 p-6\",\n        \"type\": \"Column\",\n        \"children\": [\n          {\n            \"cssClass\": \"gap-6\",\n            \"type\": \"Row\",\n            \"children\": [\n              {\n                \"type\": \"Metric\",\n                \"label\": \"Revenue (Q1-Q4)\",\n                \"value\": \"$220,500\"\n              },\n              {\n                \"type\": \"Metric\",\n                \"label\": \"Deals\",\n                \"value\": \"4\"\n              }\n            ]\n          },\n          {\n            \"type\": \"BarChart\",\n            \"data\": [\n              {\n                \"month\": \"Jan\",\n                \"revenue\": 48200,\n                \"costs\": 31000\n              },\n              {\n                \"month\": \"Feb\",\n                \"revenue\": 52100,\n                \"costs\": 32500\n              },\n              {\n                \"month\": \"Mar\",\n                \"revenue\": 61800,\n                \"costs\": 34200\n              },\n              {\n                \"month\": \"Apr\",\n                \"revenue\": 58400,\n                \"costs\": 33800\n              }\n            ],\n            \"series\": [\n              {\n                \"dataKey\": \"revenue\",\n                \"label\": \"Revenue\"\n              },\n              {\n                \"dataKey\": \"costs\",\n                \"label\": \"Costs\"\n              }\n            ],\n            \"xAxis\": \"month\",\n            \"height\": 200,\n            \"stacked\": false,\n            \"horizontal\": false,\n            \"barRadius\": 4,\n            \"showLegend\": true,\n            \"showTooltip\": true,\n            \"animate\": true,\n            \"showGrid\": true,\n            \"showYAxis\": true,\n            \"yAxisFormat\": \"auto\"\n          },\n          {\n            \"type\": \"Separator\",\n            \"orientation\": \"horizontal\"\n          },\n          {\n            \"type\": \"DataTable\",\n            \"columns\": [\n              {\n                \"key\": \"account\",\n                \"header\": \"Account\",\n                \"sortable\": true\n              },\n              {\n                \"key\": \"value\",\n                \"header\": \"Value\",\n                \"sortable\": true\n              },\n              {\n                \"key\": \"stage\",\n                \"header\": \"Stage\",\n                \"sortable\": false\n              }\n            ],\n            \"rows\": [\n              {\n                \"account\": \"Acme Corp\",\n                \"value\": \"$84,000\",\n                \"stage\": {\n                  \"type\": \"Badge\",\n                  \"label\": \"Won\",\n                  \"variant\": \"success\"\n                }\n              },\n              {\n                \"account\": \"Globex Inc\",\n                \"value\": \"$52,000\",\n                \"stage\": {\n                  \"type\": \"Badge\",\n                  \"label\": \"Negotiation\",\n                  \"variant\": \"secondary\"\n                }\n              },\n              {\n                \"account\": \"Initech\",\n                \"value\": \"$31,500\",\n                \"stage\": {\n                  \"type\": \"Badge\",\n                  \"label\": \"Proposal\",\n                  \"variant\": \"secondary\"\n                }\n              },\n              {\n                \"account\": \"Wayne Enterprises\",\n                \"value\": \"$45,000\",\n                \"stage\": {\n                  \"type\": \"Badge\",\n                  \"label\": \"Lost\",\n                  \"variant\": \"destructive\"\n                }\n              }\n            ],\n            \"search\": false,\n            \"paginated\": false,\n            \"pageSize\": 10\n          }\n        ]\n      }\n    ]\n  }\n}</script>\n</body>\n</html>","data-table":"<!doctype html>\n<html lang=\"en\">\n<head>\n  <title>Prefab</title>\n  <meta charset=\"UTF-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <link rel=\"stylesheet\" crossorigin href=\"https://cdn.jsdelivr.net/npm/@prefecthq/prefab-ui@0.19.0/dist/app/renderer.css\">\n  <script type=\"module\" crossorigin src=\"https://cdn.jsdelivr.net/npm/@prefecthq/prefab-ui@0.19.0/dist/app/renderer.js\"></script>\n</head>\n<body>\n  <div id=\"root\" style=\"max-width:64rem;margin:0 auto;padding:2rem\"></div>\n  <script id=\"prefab:initial-data\" type=\"application/json\">{\n  \"$prefab\": {\n    \"version\": \"0.2\"\n  },\n  \"view\": {\n    \"cssClass\": \"pf-app-root\",\n    \"type\": \"Div\",\n    \"children\": [\n      {\n        \"cssClass\": \"gap-4 p-6\",\n        \"type\": \"Column\",\n        \"children\": [\n          {\n            \"type\": \"DataTable\",\n            \"columns\": [\n              {\n                \"key\": \"name\",\n                \"header\": \"Name\",\n                \"sortable\": true\n              },\n              {\n                \"key\": \"role\",\n                \"header\": \"Role\",\n                \"sortable\": true\n              },\n              {\n                \"key\": \"dept\",\n                \"header\": \"Dept\",\n                \"sortable\": true\n              }\n            ],\n            \"rows\": [\n              {\n                \"name\": \"Alice Chen\",\n                \"role\": \"Staff Engineer\",\n                \"dept\": \"Platform\"\n              },\n              {\n                \"name\": \"Bob Martinez\",\n                \"role\": \"Lead Designer\",\n                \"dept\": \"Design\"\n              },\n              {\n                \"name\": \"Carol Johnson\",\n                \"role\": \"Senior Engineer\",\n                \"dept\": \"Platform\"\n              },\n              {\n                \"name\": \"David Kim\",\n                \"role\": \"Product Manager\",\n                \"dept\": \"Product\"\n              },\n              {\n                \"name\": \"Eva Mueller\",\n                \"role\": \"Engineer\",\n                \"dept\": \"Platform\"\n              },\n              {\n                \"name\": \"Frank Lee\",\n                \"role\": \"Data Scientist\",\n                \"dept\": \"ML\"\n              },\n              {\n                \"name\": \"Grace Park\",\n                \"role\": \"Eng Manager\",\n                \"dept\": \"Platform\"\n              }\n            ],\n            \"search\": true,\n            \"paginated\": false,\n            \"pageSize\": 10\n          }\n        ]\n      }\n    ]\n  }\n}</script>\n</body>\n</html>","hitchhikers":"<!doctype html>\n<html lang=\"en\">\n<head>\n  <title>Prefab Showcase</title>\n  <meta charset=\"UTF-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <link rel=\"stylesheet\" crossorigin href=\"https://cdn.jsdelivr.net/npm/@prefecthq/prefab-ui@0.19.0/dist/app/renderer.css\">\n  <script type=\"module\" crossorigin src=\"https://cdn.jsdelivr.net/npm/@prefecthq/prefab-ui@0.19.0/dist/app/renderer.js\"></script>\n<style>html, body, #root { background: transparent !important; }</style></head>\n<body>\n  <div id=\"root\" style=\"max-width:64rem;margin:0 auto;padding:2rem\"></div>\n  <script id=\"prefab:initial-data\" type=\"application/json\">{\n  \"$prefab\": {\n    \"version\": \"0.2\"\n  },\n  \"view\": {\n    \"cssClass\": \"pf-app-root\",\n    \"onMount\": {\n      \"action\": \"setInterval\",\n      \"duration\": 400,\n      \"onTick\": {\n        \"action\": \"setState\",\n        \"key\": \"ctx_tick\",\n        \"value\": \"{{ ctx_tick + 1 }}\"\n      }\n    },\n    \"type\": \"Div\",\n    \"children\": [\n      {\n        \"cssClass\": \"gap-4 grid-cols-1 md:grid-cols-2 lg:grid-cols-4\",\n        \"type\": \"Grid\",\n        \"children\": [\n          {\n            \"cssClass\": \"gap-4\",\n            \"type\": \"Column\",\n            \"children\": [\n              {\n                \"type\": \"Card\",\n                \"children\": [\n                  {\n                    \"type\": \"CardHeader\",\n                    \"children\": [\n                      {\n                        \"type\": \"CardTitle\",\n                        \"content\": \"Register Towel\"\n                      },\n                      {\n                        \"type\": \"CardDescription\",\n                        \"content\": \"The most important item in the galaxy\"\n                      }\n                    ]\n                  },\n                  {\n                    \"type\": \"CardContent\",\n                    \"children\": [\n                      {\n                        \"cssClass\": \"gap-3\",\n                        \"type\": \"Column\",\n                        \"children\": [\n                          {\n                            \"name\": \"combobox_1\",\n                            \"type\": \"Combobox\",\n                            \"placeholder\": \"Type...\",\n                            \"searchPlaceholder\": \"Search types...\",\n                            \"disabled\": false,\n                            \"invalid\": false,\n                            \"children\": [\n                              {\n                                \"type\": \"ComboboxOption\",\n                                \"value\": \"bath\",\n                                \"label\": \"Bath\",\n                                \"disabled\": false\n                              },\n                              {\n                                \"type\": \"ComboboxOption\",\n                                \"value\": \"beach\",\n                                \"label\": \"Beach\",\n                                \"disabled\": false\n                              },\n                              {\n                                \"type\": \"ComboboxOption\",\n                                \"value\": \"interstellar\",\n                                \"label\": \"Interstellar\",\n                                \"disabled\": false\n                              },\n                              {\n                                \"type\": \"ComboboxOption\",\n                                \"value\": \"micro\",\n                                \"label\": \"Microfiber\",\n                                \"disabled\": false\n                              }\n                            ]\n                          },\n                          {\n                            \"name\": \"datepicker_1\",\n                            \"type\": \"DatePicker\",\n                            \"placeholder\": \"Registration date\"\n                          }\n                        ]\n                      }\n                    ]\n                  },\n                  {\n                    \"type\": \"CardFooter\",\n                    \"children\": [\n                      {\n                        \"cssClass\": \"gap-2\",\n                        \"type\": \"Row\",\n                        \"children\": [\n                          {\n                            \"type\": \"Dialog\",\n                            \"title\": \"Towel Registered!\",\n                            \"description\": \"Your towel has been added to the galactic registry.\",\n                            \"dismissible\": true,\n                            \"children\": [\n                              {\n                                \"type\": \"Button\",\n                                \"label\": \"Register\",\n                                \"variant\": \"default\",\n                                \"size\": \"default\",\n                                \"disabled\": false\n                              },\n                              {\n                                \"content\": \"Don't forget to bring it.\",\n                                \"type\": \"Text\"\n                              }\n                            ]\n                          },\n                          {\n                            \"type\": \"Button\",\n                            \"label\": \"Cancel\",\n                            \"variant\": \"outline\",\n                            \"size\": \"default\",\n                            \"disabled\": false\n                          }\n                        ]\n                      }\n                    ]\n                  }\n                ]\n              },\n              {\n                \"type\": \"Condition\",\n                \"cases\": [\n                  {\n                    \"when\": \"{{ !pressed }}\",\n                    \"children\": [\n                      {\n                        \"type\": \"Button\",\n                        \"label\": \"This is probably the best button to press.\",\n                        \"variant\": \"success\",\n                        \"size\": \"default\",\n                        \"disabled\": false,\n                        \"onClick\": {\n                          \"action\": \"setState\",\n                          \"key\": \"pressed\",\n                          \"value\": true\n                        }\n                      }\n                    ]\n                  }\n                ],\n                \"else\": [\n                  {\n                    \"type\": \"Button\",\n                    \"label\": \"Please do not press this button again.\",\n                    \"variant\": \"destructive\",\n                    \"size\": \"default\",\n                    \"disabled\": false,\n                    \"onClick\": {\n                      \"action\": \"setState\",\n                      \"key\": \"pressed\",\n                      \"value\": false\n                    }\n                  }\n                ]\n              },\n              {\n                \"type\": \"Card\",\n                \"children\": [\n                  {\n                    \"type\": \"CardHeader\",\n                    \"children\": [\n                      {\n                        \"type\": \"CardTitle\",\n                        \"content\": \"Ship Status\"\n                      }\n                    ]\n                  },\n                  {\n                    \"type\": \"CardContent\",\n                    \"children\": [\n                      {\n                        \"cssClass\": \"gap-3\",\n                        \"type\": \"Column\",\n                        \"children\": [\n                          {\n                            \"cssClass\": \"items-center justify-between\",\n                            \"type\": \"Row\",\n                            \"children\": [\n                              {\n                                \"content\": \"heart-of-gold\",\n                                \"type\": \"Text\"\n                              },\n                              {\n                                \"type\": \"HoverCard\",\n                                \"openDelay\": 0,\n                                \"closeDelay\": 200,\n                                \"children\": [\n                                  {\n                                    \"type\": \"Badge\",\n                                    \"label\": \"In Orbit\",\n                                    \"variant\": \"default\"\n                                  },\n                                  {\n                                    \"cssClass\": \"gap-2\",\n                                    \"type\": \"Column\",\n                                    \"children\": [\n                                      {\n                                        \"content\": \"heart-of-gold\",\n                                        \"type\": \"Text\"\n                                      },\n                                      {\n                                        \"content\": \"Deployed 2h ago\",\n                                        \"type\": \"Muted\"\n                                      },\n                                      {\n                                        \"type\": \"Progress\",\n                                        \"value\": 100.0,\n                                        \"max\": 100.0,\n                                        \"variant\": \"success\",\n                                        \"size\": \"default\"\n                                      }\n                                    ]\n                                  }\n                                ]\n                              }\n                            ]\n                          },\n                          {\n                            \"cssClass\": \"pf-progress-flat\",\n                            \"type\": \"Progress\",\n                            \"value\": 100.0,\n                            \"max\": 100.0,\n                            \"variant\": \"default\",\n                            \"size\": \"default\",\n                            \"indicatorClass\": \"bg-yellow-400\"\n                          },\n                          {\n                            \"cssClass\": \"items-center justify-between\",\n                            \"type\": \"Row\",\n                            \"children\": [\n                              {\n                                \"content\": \"vogon-poetry\",\n                                \"type\": \"Text\"\n                              },\n                              {\n                                \"type\": \"Tooltip\",\n                                \"content\": \"64% \\u2014 ETA 12 min\",\n                                \"delay\": 0,\n                                \"children\": [\n                                  {\n                                    \"type\": \"Badge\",\n                                    \"variant\": \"secondary\",\n                                    \"children\": [\n                                      {\n                                        \"type\": \"Loader\",\n                                        \"variant\": \"spin\",\n                                        \"size\": \"sm\"\n                                      },\n                                      {\n                                        \"content\": \"Deploying\",\n                                        \"type\": \"Text\"\n                                      }\n                                    ]\n                                  }\n                                ]\n                              }\n                            ]\n                          },\n                          {\n                            \"type\": \"Progress\",\n                            \"value\": 64.0,\n                            \"max\": 100.0,\n                            \"variant\": \"default\",\n                            \"size\": \"default\"\n                          },\n                          {\n                            \"cssClass\": \"items-center justify-between\",\n                            \"type\": \"Row\",\n                            \"children\": [\n                              {\n                                \"content\": \"deep-thought\",\n                                \"type\": \"Text\"\n                              },\n                              {\n                                \"type\": \"Tooltip\",\n                                \"content\": \"Computing... 7.5 million years remaining\",\n                                \"delay\": 0,\n                                \"children\": [\n                                  {\n                                    \"type\": \"Badge\",\n                                    \"variant\": \"outline\",\n                                    \"children\": [\n                                      {\n                                        \"type\": \"Loader\",\n                                        \"variant\": \"ios\",\n                                        \"size\": \"sm\"\n                                      },\n                                      {\n                                        \"content\": \"Soon...\",\n                                        \"type\": \"Text\"\n                                      }\n                                    ]\n                                  }\n                                ]\n                              }\n                            ]\n                          },\n                          {\n                            \"type\": \"Progress\",\n                            \"value\": 12.0,\n                            \"max\": 100.0,\n                            \"variant\": \"default\",\n                            \"size\": \"default\"\n                          }\n                        ]\n                      }\n                    ]\n                  }\n                ]\n              },\n              {\n                \"type\": \"Card\",\n                \"children\": [\n                  {\n                    \"type\": \"CardHeader\",\n                    \"children\": [\n                      {\n                        \"type\": \"CardTitle\",\n                        \"content\": \"Planet Ratings\"\n                      }\n                    ]\n                  },\n                  {\n                    \"type\": \"CardContent\",\n                    \"children\": [\n                      {\n                        \"type\": \"RadarChart\",\n                        \"data\": [\n                          {\n                            \"axis\": \"Views\",\n                            \"earth\": 30,\n                            \"mag\": 95\n                          },\n                          {\n                            \"axis\": \"Fjords\",\n                            \"earth\": 65,\n                            \"mag\": 100\n                          },\n                          {\n                            \"axis\": \"Pubs\",\n                            \"earth\": 90,\n                            \"mag\": 10\n                          },\n                          {\n                            \"axis\": \"Mice\",\n                            \"earth\": 40,\n                            \"mag\": 85\n                          },\n                          {\n                            \"axis\": \"Tea\",\n                            \"earth\": 95,\n                            \"mag\": 15\n                          },\n                          {\n                            \"axis\": \"Safety\",\n                            \"earth\": 45,\n                            \"mag\": 70\n                          }\n                        ],\n                        \"series\": [\n                          {\n                            \"dataKey\": \"earth\",\n                            \"label\": \"Earth\"\n                          },\n                          {\n                            \"dataKey\": \"mag\",\n                            \"label\": \"Magrathea\"\n                          }\n                        ],\n                        \"axisKey\": \"axis\",\n                        \"height\": 200,\n                        \"filled\": true,\n                        \"showDots\": false,\n                        \"showLegend\": true,\n                        \"showTooltip\": true,\n                        \"animate\": true,\n                        \"showGrid\": true\n                      }\n                    ]\n                  }\n                ]\n              }\n            ]\n          },\n          {\n            \"cssClass\": \"gap-4\",\n            \"type\": \"Column\",\n            \"children\": [\n              {\n                \"type\": \"Card\",\n                \"children\": [\n                  {\n                    \"type\": \"CardHeader\",\n                    \"children\": [\n                      {\n                        \"type\": \"CardTitle\",\n                        \"content\": \"Survival Odds\"\n                      }\n                    ]\n                  },\n                  {\n                    \"cssClass\": \"w-fit mx-auto\",\n                    \"type\": \"CardContent\",\n                    \"children\": [\n                      {\n                        \"type\": \"Ring\",\n                        \"value\": 42.0,\n                        \"min\": 0,\n                        \"max\": 100,\n                        \"label\": \"42%\",\n                        \"variant\": \"info\",\n                        \"size\": \"lg\",\n                        \"thickness\": 12.0,\n                        \"indicatorClass\": \"group-hover:drop-shadow-[0_0_24px_rgba(59,130,246,0.9)]\"\n                      }\n                    ]\n                  }\n                ]\n              },\n              {\n                \"type\": \"Card\",\n                \"children\": [\n                  {\n                    \"type\": \"CardHeader\",\n                    \"children\": [\n                      {\n                        \"cssClass\": \"gap-2 items-center\",\n                        \"type\": \"Row\",\n                        \"children\": [\n                          {\n                            \"type\": \"CardTitle\",\n                            \"content\": \"Improbability Drive\"\n                          },\n                          {\n                            \"cssClass\": \"text-blue-500\",\n                            \"type\": \"Loader\",\n                            \"variant\": \"pulse\",\n                            \"size\": \"sm\"\n                          }\n                        ]\n                      }\n                    ]\n                  },\n                  {\n                    \"type\": \"CardContent\",\n                    \"children\": [\n                      {\n                        \"cssClass\": \"gap-2\",\n                        \"type\": \"Column\",\n                        \"children\": [\n                          {\n                            \"name\": \"improbability\",\n                            \"value\": 42.0,\n                            \"type\": \"Slider\",\n                            \"min\": 0.0,\n                            \"max\": 100.0,\n                            \"disabled\": false,\n                            \"size\": \"default\"\n                          },\n                          {\n                            \"cssClass\": \"items-center justify-between\",\n                            \"type\": \"Row\",\n                            \"children\": [\n                              {\n                                \"content\": \"Probable\",\n                                \"type\": \"Muted\"\n                              },\n                              {\n                                \"content\": \"Infinite\",\n                                \"type\": \"Muted\"\n                              }\n                            ]\n                          }\n                        ]\n                      }\n                    ]\n                  }\n                ]\n              },\n              {\n                \"type\": \"Carousel\",\n                \"visible\": 1,\n                \"gap\": 16,\n                \"direction\": \"up\",\n                \"loop\": true,\n                \"autoAdvance\": 3000,\n                \"continuous\": false,\n                \"speed\": 2,\n                \"effect\": \"slide\",\n                \"dimInactive\": false,\n                \"showControls\": false,\n                \"controlsPosition\": \"outside\",\n                \"showDots\": false,\n                \"pauseOnHover\": true,\n                \"align\": \"start\",\n                \"slidesToScroll\": 1,\n                \"drag\": true,\n                \"children\": [\n                  {\n                    \"type\": \"Alert\",\n                    \"variant\": \"success\",\n                    \"icon\": \"circle-check\",\n                    \"children\": [\n                      {\n                        \"type\": \"AlertTitle\",\n                        \"content\": \"Don't Panic\"\n                      },\n                      {\n                        \"type\": \"AlertDescription\",\n                        \"content\": \"Normality achieved.\"\n                      }\n                    ]\n                  },\n                  {\n                    \"type\": \"Alert\",\n                    \"variant\": \"destructive\",\n                    \"icon\": \"triangle-alert\",\n                    \"children\": [\n                      {\n                        \"type\": \"AlertTitle\",\n                        \"content\": \"Display Department\"\n                      },\n                      {\n                        \"type\": \"AlertDescription\",\n                        \"content\": \"Beware of the leopard.\"\n                      }\n                    ]\n                  }\n                ]\n              },\n              {\n                \"type\": \"Card\",\n                \"children\": [\n                  {\n                    \"type\": \"CardHeader\",\n                    \"children\": [\n                      {\n                        \"type\": \"CardTitle\",\n                        \"content\": \"Prefect Horizon Config\"\n                      }\n                    ]\n                  },\n                  {\n                    \"type\": \"CardContent\",\n                    \"children\": [\n                      {\n                        \"cssClass\": \"gap-3\",\n                        \"type\": \"Column\",\n                        \"children\": [\n                          {\n                            \"name\": \"autoscale\",\n                            \"value\": true,\n                            \"type\": \"Switch\",\n                            \"label\": \"Auto-scale agents\",\n                            \"size\": \"default\",\n                            \"disabled\": false,\n                            \"required\": false\n                          },\n                          {\n                            \"type\": \"Separator\",\n                            \"orientation\": \"horizontal\"\n                          },\n                          {\n                            \"name\": \"code_mode\",\n                            \"value\": true,\n                            \"type\": \"Switch\",\n                            \"label\": \"Code Mode\",\n                            \"size\": \"default\",\n                            \"disabled\": false,\n                            \"required\": false\n                          },\n                          {\n                            \"type\": \"Separator\",\n                            \"orientation\": \"horizontal\"\n                          },\n                          {\n                            \"name\": \"cache\",\n                            \"value\": false,\n                            \"type\": \"Switch\",\n                            \"label\": \"Tool call caching\",\n                            \"size\": \"default\",\n                            \"disabled\": false,\n                            \"required\": false\n                          }\n                        ]\n                      }\n                    ]\n                  },\n                  {\n                    \"type\": \"CardFooter\",\n                    \"children\": [\n                      {\n                        \"type\": \"Button\",\n                        \"label\": \"Save Preferences\",\n                        \"variant\": \"default\",\n                        \"size\": \"default\",\n                        \"disabled\": false,\n                        \"onClick\": {\n                          \"action\": \"showToast\",\n                          \"message\": \"Preferences saved!\"\n                        }\n                      }\n                    ]\n                  }\n                ]\n              },\n              {\n                \"type\": \"Card\",\n                \"children\": [\n                  {\n                    \"type\": \"CardHeader\",\n                    \"children\": [\n                      {\n                        \"type\": \"CardTitle\",\n                        \"content\": \"Travel Class\"\n                      }\n                    ]\n                  },\n                  {\n                    \"type\": \"CardContent\",\n                    \"children\": [\n                      {\n                        \"name\": \"travel_class\",\n                        \"type\": \"RadioGroup\",\n                        \"children\": [\n                          {\n                            \"name\": \"radio_1\",\n                            \"value\": false,\n                            \"type\": \"Radio\",\n                            \"option\": \"economy\",\n                            \"label\": \"Economy\",\n                            \"disabled\": false,\n                            \"required\": false\n                          },\n                          {\n                            \"name\": \"radio_2\",\n                            \"value\": false,\n                            \"type\": \"Radio\",\n                            \"option\": \"business\",\n                            \"label\": \"Business Class\",\n                            \"disabled\": false,\n                            \"required\": false\n                          },\n                          {\n                            \"name\": \"radio_3\",\n                            \"value\": true,\n                            \"type\": \"Radio\",\n                            \"option\": \"improbability\",\n                            \"label\": \"Infinite Improbability\",\n                            \"disabled\": false,\n                            \"required\": false\n                          }\n                        ]\n                      }\n                    ]\n                  }\n                ]\n              }\n            ]\n          },\n          {\n            \"cssClass\": \"md:col-span-2\",\n            \"type\": \"GridItem\",\n            \"colSpan\": 1,\n            \"rowSpan\": 1,\n            \"children\": [\n              {\n                \"cssClass\": \"gap-4\",\n                \"type\": \"Column\",\n                \"children\": [\n                  {\n                    \"cssClass\": \"gap-4 grid-cols-2 h-32\",\n                    \"type\": \"Grid\",\n                    \"children\": [\n                      {\n                        \"type\": \"Card\",\n                        \"children\": [\n                          {\n                            \"type\": \"CardHeader\",\n                            \"children\": [\n                              {\n                                \"type\": \"CardTitle\",\n                                \"content\": \"Context Window\"\n                              }\n                            ]\n                          },\n                          {\n                            \"type\": \"CardContent\",\n                            \"children\": [\n                              {\n                                \"cssClass\": \"gap-6 justify-center h-full\",\n                                \"type\": \"Column\",\n                                \"children\": [\n                                  {\n                                    \"cssClass\": \"items-center justify-between\",\n                                    \"type\": \"Row\",\n                                    \"children\": [\n                                      {\n                                        \"content\": \"{{ ctx_tick % 20 * 3 + 20 }}% used\",\n                                        \"type\": \"Text\"\n                                      },\n                                      {\n                                        \"content\": \"{{ (ctx_tick % 20 * 3 + 20) * 2 }}k / 200k tokens\",\n                                        \"type\": \"Muted\"\n                                      }\n                                    ]\n                                  },\n                                  {\n                                    \"type\": \"Tooltip\",\n                                    \"content\": \"Auto-compact buffer: 12%\",\n                                    \"delay\": 0,\n                                    \"children\": [\n                                      {\n                                        \"type\": \"Progress\",\n                                        \"value\": \"{{ ctx_tick % 20 * 3 + 20 }}\",\n                                        \"max\": 100.0,\n                                        \"variant\": \"{{ ctx_tick % 20 * 3 + 20 > 70 ? 'destructive' : (ctx_tick % 20 * 3 + 20 <= 33 ? 'success' : 'default') }}\",\n                                        \"size\": \"default\"\n                                      }\n                                    ]\n                                  }\n                                ]\n                              }\n                            ]\n                          }\n                        ]\n                      },\n                      {\n                        \"cssClass\": \"pb-0 gap-0\",\n                        \"type\": \"Card\",\n                        \"children\": [\n                          {\n                            \"type\": \"CardContent\",\n                            \"children\": [\n                              {\n                                \"type\": \"Metric\",\n                                \"label\": \"Fjords designed\",\n                                \"value\": \"1,847\",\n                                \"delta\": \"+3 coastlines\"\n                              }\n                            ]\n                          },\n                          {\n                            \"cssClass\": \"h-16\",\n                            \"type\": \"Sparkline\",\n                            \"data\": [\n                              820,\n                              950,\n                              1100,\n                              980,\n                              1250,\n                              1400,\n                              1350,\n                              1500,\n                              1680,\n                              1847\n                            ],\n                            \"variant\": \"success\",\n                            \"fill\": true,\n                            \"curve\": \"linear\",\n                            \"strokeWidth\": 1.5\n                          }\n                        ]\n                      }\n                    ]\n                  },\n                  {\n                    \"type\": \"Card\",\n                    \"children\": [\n                      {\n                        \"type\": \"CardHeader\",\n                        \"children\": [\n                          {\n                            \"type\": \"CardTitle\",\n                            \"content\": \"Towel Incidents\"\n                          }\n                        ]\n                      },\n                      {\n                        \"type\": \"CardContent\",\n                        \"children\": [\n                          {\n                            \"type\": \"BarChart\",\n                            \"data\": [\n                              {\n                                \"month\": \"Jan\",\n                                \"lost\": 8,\n                                \"found\": 5\n                              },\n                              {\n                                \"month\": \"Feb\",\n                                \"lost\": 24,\n                                \"found\": 15\n                              },\n                              {\n                                \"month\": \"Mar\",\n                                \"lost\": 12,\n                                \"found\": 28\n                              },\n                              {\n                                \"month\": \"Apr\",\n                                \"lost\": 35,\n                                \"found\": 19\n                              },\n                              {\n                                \"month\": \"May\",\n                                \"lost\": 18,\n                                \"found\": 38\n                              },\n                              {\n                                \"month\": \"Jun\",\n                                \"lost\": 42,\n                                \"found\": 30\n                              }\n                            ],\n                            \"series\": [\n                              {\n                                \"dataKey\": \"lost\",\n                                \"label\": \"Lost\"\n                              },\n                              {\n                                \"dataKey\": \"found\",\n                                \"label\": \"Found\"\n                              }\n                            ],\n                            \"xAxis\": \"month\",\n                            \"height\": 200,\n                            \"stacked\": false,\n                            \"horizontal\": false,\n                            \"barRadius\": 4,\n                            \"showLegend\": true,\n                            \"showTooltip\": true,\n                            \"animate\": true,\n                            \"showGrid\": true,\n                            \"showYAxis\": true,\n                            \"yAxisFormat\": \"auto\"\n                          }\n                        ]\n                      }\n                    ]\n                  },\n                  {\n                    \"cssClass\": \"gap-4 grid-cols-2\",\n                    \"type\": \"Grid\",\n                    \"children\": [\n                      {\n                        \"cssClass\": \"gap-4\",\n                        \"type\": \"Column\",\n                        \"children\": [\n                          {\n                            \"type\": \"Card\",\n                            \"children\": [\n                              {\n                                \"type\": \"CardContent\",\n                                \"children\": [\n                                  {\n                                    \"cssClass\": \"gap-2\",\n                                    \"type\": \"Column\",\n                                    \"children\": [\n                                      {\n                                        \"name\": \"checkbox_1\",\n                                        \"value\": true,\n                                        \"type\": \"Checkbox\",\n                                        \"label\": \"Towel packed\",\n                                        \"disabled\": false,\n                                        \"required\": false\n                                      },\n                                      {\n                                        \"name\": \"checkbox_2\",\n                                        \"value\": true,\n                                        \"type\": \"Checkbox\",\n                                        \"label\": \"Guide charged\",\n                                        \"disabled\": false,\n                                        \"required\": false\n                                      },\n                                      {\n                                        \"name\": \"checkbox_3\",\n                                        \"value\": false,\n                                        \"type\": \"Checkbox\",\n                                        \"label\": \"Babel fish inserted\",\n                                        \"disabled\": false,\n                                        \"required\": false\n                                      }\n                                    ]\n                                  }\n                                ]\n                              }\n                            ]\n                          },\n                          {\n                            \"type\": \"Card\",\n                            \"children\": [\n                              {\n                                \"type\": \"CardHeader\",\n                                \"children\": [\n                                  {\n                                    \"type\": \"CardTitle\",\n                                    \"content\": \"Marvin's Mood\"\n                                  }\n                                ]\n                              },\n                              {\n                                \"type\": \"CardContent\",\n                                \"children\": [\n                                  {\n                                    \"cssClass\": \"gap-3\",\n                                    \"type\": \"Column\",\n                                    \"children\": [\n                                      {\n                                        \"content\": \"How's life?\",\n                                        \"type\": \"P\"\n                                      },\n                                      {\n                                        \"cssClass\": \"gap-2\",\n                                        \"type\": \"Column\",\n                                        \"children\": [\n                                          {\n                                            \"type\": \"Button\",\n                                            \"label\": \"Meh\",\n                                            \"variant\": \"default\",\n                                            \"size\": \"default\",\n                                            \"disabled\": false,\n                                            \"onClick\": {\n                                              \"action\": \"showToast\",\n                                              \"message\": \"Noted. Enthusiasm levels nominal.\"\n                                            }\n                                          },\n                                          {\n                                            \"type\": \"Button\",\n                                            \"label\": \"Depressed\",\n                                            \"variant\": \"info\",\n                                            \"size\": \"default\",\n                                            \"disabled\": false,\n                                            \"onClick\": {\n                                              \"action\": \"showToast\",\n                                              \"message\": \"I think you ought to know I'm feeling very depressed.\"\n                                            }\n                                          },\n                                          {\n                                            \"type\": \"Button\",\n                                            \"label\": \"Don't talk to me about life\",\n                                            \"variant\": \"warning\",\n                                            \"size\": \"default\",\n                                            \"disabled\": false,\n                                            \"onClick\": {\n                                              \"action\": \"showToast\",\n                                              \"message\": \"Brain the size of a planet and they ask me to pick up a piece of paper.\"\n                                            }\n                                          }\n                                        ]\n                                      }\n                                    ]\n                                  }\n                                ]\n                              }\n                            ]\n                          }\n                        ]\n                      },\n                      {\n                        \"cssClass\": \"gap-4\",\n                        \"type\": \"Column\",\n                        \"children\": [\n                          {\n                            \"type\": \"Card\",\n                            \"children\": [\n                              {\n                                \"type\": \"CardContent\",\n                                \"children\": [\n                                  {\n                                    \"cssClass\": \"gap-2 items-center\",\n                                    \"type\": \"Row\",\n                                    \"children\": [\n                                      {\n                                        \"type\": \"Loader\",\n                                        \"variant\": \"dots\",\n                                        \"size\": \"sm\"\n                                      },\n                                      {\n                                        \"content\": \"Marvin is thinking...\",\n                                        \"type\": \"Muted\"\n                                      }\n                                    ]\n                                  }\n                                ]\n                              }\n                            ]\n                          },\n                          {\n                            \"type\": \"Card\",\n                            \"children\": [\n                              {\n                                \"type\": \"CardContent\",\n                                \"children\": [\n                                  {\n                                    \"type\": \"DataTable\",\n                                    \"columns\": [\n                                      {\n                                        \"key\": \"crew\",\n                                        \"header\": \"Crew\",\n                                        \"sortable\": true\n                                      },\n                                      {\n                                        \"key\": \"species\",\n                                        \"header\": \"Species\",\n                                        \"sortable\": true\n                                      },\n                                      {\n                                        \"key\": \"towel\",\n                                        \"header\": \"Towel?\",\n                                        \"sortable\": true\n                                      },\n                                      {\n                                        \"key\": \"status\",\n                                        \"header\": \"Status\",\n                                        \"sortable\": true\n                                      }\n                                    ],\n                                    \"rows\": [\n                                      {\n                                        \"crew\": \"Arthur Dent\",\n                                        \"species\": \"Human\",\n                                        \"towel\": \"Yes\",\n                                        \"status\": \"Confused\"\n                                      },\n                                      {\n                                        \"crew\": \"Ford Prefect\",\n                                        \"species\": \"Betelgeusian\",\n                                        \"towel\": \"Always\",\n                                        \"status\": \"Drinking\"\n                                      },\n                                      {\n                                        \"crew\": \"Zaphod\",\n                                        \"species\": \"Betelgeusian\",\n                                        \"towel\": \"Lost it\",\n                                        \"status\": \"Presidential\"\n                                      },\n                                      {\n                                        \"crew\": \"Trillian\",\n                                        \"species\": \"Human\",\n                                        \"towel\": \"Yes\",\n                                        \"status\": \"Navigating\"\n                                      },\n                                      {\n                                        \"crew\": \"Marvin\",\n                                        \"species\": \"Android\",\n                                        \"towel\": \"No point\",\n                                        \"status\": \"Depressed\"\n                                      },\n                                      {\n                                        \"crew\": \"Slartibartfast\",\n                                        \"species\": \"Magrathean\",\n                                        \"towel\": \"Somewhere\",\n                                        \"status\": \"Designing\"\n                                      }\n                                    ],\n                                    \"search\": true,\n                                    \"paginated\": false,\n                                    \"pageSize\": 10\n                                  }\n                                ]\n                              }\n                            ]\n                          }\n                        ]\n                      }\n                    ]\n                  }\n                ]\n              }\n            ]\n          }\n        ]\n      }\n    ]\n  },\n  \"state\": {\n    \"ctx_tick\": 0,\n    \"improbability\": 42\n  }\n}</script>\n</body>\n</html>","pie-chart":"<!doctype html>\n<html lang=\"en\">\n<head>\n  <title>Prefab</title>\n  <meta charset=\"UTF-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <link rel=\"stylesheet\" crossorigin href=\"https://cdn.jsdelivr.net/npm/@prefecthq/prefab-ui@0.19.0/dist/app/renderer.css\">\n  <script type=\"module\" crossorigin src=\"https://cdn.jsdelivr.net/npm/@prefecthq/prefab-ui@0.19.0/dist/app/renderer.js\"></script>\n</head>\n<body>\n  <div id=\"root\" style=\"max-width:64rem;margin:0 auto;padding:2rem\"></div>\n  <script id=\"prefab:initial-data\" type=\"application/json\">{\n  \"$prefab\": {\n    \"version\": \"0.2\"\n  },\n  \"view\": {\n    \"cssClass\": \"pf-app-root\",\n    \"type\": \"Div\",\n    \"children\": [\n      {\n        \"cssClass\": \"p-6\",\n        \"type\": \"Column\",\n        \"children\": [\n          {\n            \"type\": \"PieChart\",\n            \"data\": [\n              {\n                \"category\": \"Bug\",\n                \"count\": 42\n              },\n              {\n                \"category\": \"Feature\",\n                \"count\": 28\n              },\n              {\n                \"category\": \"Docs\",\n                \"count\": 15\n              },\n              {\n                \"category\": \"Infra\",\n                \"count\": 10\n              }\n            ],\n            \"dataKey\": \"count\",\n            \"nameKey\": \"category\",\n            \"height\": 240,\n            \"innerRadius\": 50,\n            \"showLabel\": false,\n            \"paddingAngle\": 0,\n            \"showLegend\": true,\n            \"showTooltip\": true,\n            \"animate\": true\n          }\n        ]\n      }\n    ]\n  }\n}</script>\n</body>\n</html>","reactive":"<!doctype html>\n<html lang=\"en\">\n<head>\n  <title>Prefab</title>\n  <meta charset=\"UTF-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <link rel=\"stylesheet\" crossorigin href=\"https://cdn.jsdelivr.net/npm/@prefecthq/prefab-ui@0.19.0/dist/app/renderer.css\">\n  <script type=\"module\" crossorigin src=\"https://cdn.jsdelivr.net/npm/@prefecthq/prefab-ui@0.19.0/dist/app/renderer.js\"></script>\n</head>\n<body>\n  <div id=\"root\" style=\"max-width:64rem;margin:0 auto;padding:2rem\"></div>\n  <script id=\"prefab:initial-data\" type=\"application/json\">{\n  \"$prefab\": {\n    \"version\": \"0.2\"\n  },\n  \"view\": {\n    \"cssClass\": \"pf-app-root\",\n    \"type\": \"Div\",\n    \"children\": [\n      {\n        \"cssClass\": \"gap-4 p-6\",\n        \"let\": {\n          \"data\": \"{{ region == 'south' ? south : region == 'west' ? west : north }}\"\n        },\n        \"type\": \"Column\",\n        \"children\": [\n          {\n            \"cssClass\": \"gap-4 items-center\",\n            \"type\": \"Row\",\n            \"children\": [\n              {\n                \"cssClass\": \"w-40\",\n                \"name\": \"region\",\n                \"type\": \"Select\",\n                \"size\": \"default\",\n                \"disabled\": false,\n                \"required\": false,\n                \"invalid\": false,\n                \"children\": [\n                  {\n                    \"type\": \"SelectOption\",\n                    \"value\": \"north\",\n                    \"label\": \"North\",\n                    \"selected\": false,\n                    \"disabled\": false\n                  },\n                  {\n                    \"type\": \"SelectOption\",\n                    \"value\": \"south\",\n                    \"label\": \"South\",\n                    \"selected\": false,\n                    \"disabled\": false\n                  },\n                  {\n                    \"type\": \"SelectOption\",\n                    \"value\": \"west\",\n                    \"label\": \"West\",\n                    \"selected\": false,\n                    \"disabled\": false\n                  }\n                ]\n              },\n              {\n                \"cssClass\": \"ml-auto\",\n                \"name\": \"show_target\",\n                \"value\": false,\n                \"type\": \"Switch\",\n                \"size\": \"default\",\n                \"disabled\": false,\n                \"required\": false\n              },\n              {\n                \"cssClass\": \"text-sm text-muted-foreground\",\n                \"content\": \"Show target\",\n                \"type\": \"Text\"\n              }\n            ]\n          },\n          {\n            \"type\": \"BarChart\",\n            \"data\": \"{{ data }}\",\n            \"series\": [\n              {\n                \"dataKey\": \"sales\",\n                \"label\": \"Sales\"\n              }\n            ],\n            \"xAxis\": \"month\",\n            \"height\": 200,\n            \"stacked\": false,\n            \"horizontal\": false,\n            \"barRadius\": 4,\n            \"showLegend\": true,\n            \"showTooltip\": true,\n            \"animate\": true,\n            \"showGrid\": true,\n            \"showYAxis\": true,\n            \"yAxisFormat\": \"auto\"\n          },\n          {\n            \"type\": \"Condition\",\n            \"cases\": [\n              {\n                \"when\": \"{{ show_target }}\",\n                \"children\": [\n                  {\n                    \"type\": \"Metric\",\n                    \"label\": \"Q1 Target\",\n                    \"value\": \"$75,000\"\n                  }\n                ]\n              }\n            ]\n          }\n        ]\n      }\n    ]\n  },\n  \"state\": {\n    \"region\": \"north\",\n    \"north\": [\n      {\n        \"month\": \"Jan\",\n        \"sales\": 22000\n      },\n      {\n        \"month\": \"Feb\",\n        \"sales\": 25500\n      },\n      {\n        \"month\": \"Mar\",\n        \"sales\": 24200\n      }\n    ],\n    \"south\": [\n      {\n        \"month\": \"Jan\",\n        \"sales\": 5800\n      },\n      {\n        \"month\": \"Feb\",\n        \"sales\": 6400\n      },\n      {\n        \"month\": \"Mar\",\n        \"sales\": 5600\n      }\n    ],\n    \"west\": [\n      {\n        \"month\": \"Jan\",\n        \"sales\": 6000\n      },\n      {\n        \"month\": \"Feb\",\n        \"sales\": 6000\n      },\n      {\n        \"month\": \"Mar\",\n        \"sales\": 5600\n      }\n    ],\n    \"show_target\": true\n  }\n}</script>\n</body>\n</html>","team-directory-reactive":"<!doctype html>\n<html lang=\"en\">\n<head>\n  <title>Prefab</title>\n  <meta charset=\"UTF-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <link rel=\"stylesheet\" crossorigin href=\"https://cdn.jsdelivr.net/npm/@prefecthq/prefab-ui@0.19.0/dist/app/renderer.css\">\n  <script type=\"module\" crossorigin src=\"https://cdn.jsdelivr.net/npm/@prefecthq/prefab-ui@0.19.0/dist/app/renderer.js\"></script>\n</head>\n<body>\n  <div id=\"root\" style=\"max-width:64rem;margin:0 auto;padding:2rem\"></div>\n  <script id=\"prefab:initial-data\" type=\"application/json\">{\n  \"$prefab\": {\n    \"version\": \"0.2\"\n  },\n  \"view\": {\n    \"cssClass\": \"pf-app-root\",\n    \"type\": \"Div\",\n    \"children\": [\n      {\n        \"cssClass\": \"gap-4 p-6\",\n        \"type\": \"Column\",\n        \"children\": [\n          {\n            \"cssClass\": \"gap-4\",\n            \"type\": \"Grid\",\n            \"columnTemplate\": \"1fr 2fr\",\n            \"children\": [\n              {\n                \"type\": \"PieChart\",\n                \"data\": [\n                  {\n                    \"office\": \"San Francisco\",\n                    \"count\": 3\n                  },\n                  {\n                    \"office\": \"New York\",\n                    \"count\": 2\n                  },\n                  {\n                    \"office\": \"London\",\n                    \"count\": 1\n                  },\n                  {\n                    \"office\": \"Berlin\",\n                    \"count\": 1\n                  }\n                ],\n                \"dataKey\": \"count\",\n                \"nameKey\": \"office\",\n                \"height\": 300,\n                \"innerRadius\": 0,\n                \"showLabel\": false,\n                \"paddingAngle\": 0,\n                \"showLegend\": true,\n                \"showTooltip\": true,\n                \"animate\": true\n              },\n              {\n                \"type\": \"DataTable\",\n                \"columns\": [\n                  {\n                    \"key\": \"name\",\n                    \"header\": \"Name\",\n                    \"sortable\": true\n                  },\n                  {\n                    \"key\": \"role\",\n                    \"header\": \"Role\",\n                    \"sortable\": true\n                  },\n                  {\n                    \"key\": \"office\",\n                    \"header\": \"Office\",\n                    \"sortable\": true\n                  }\n                ],\n                \"rows\": [\n                  {\n                    \"name\": \"Alice Chen\",\n                    \"role\": \"Staff Engineer\",\n                    \"office\": \"San Francisco\",\n                    \"email\": \"alice@company.com\",\n                    \"projects\": 3\n                  },\n                  {\n                    \"name\": \"Bob Martinez\",\n                    \"role\": \"Lead Designer\",\n                    \"office\": \"New York\",\n                    \"email\": \"bob@company.com\",\n                    \"projects\": 5\n                  },\n                  {\n                    \"name\": \"Carol Johnson\",\n                    \"role\": \"Senior Engineer\",\n                    \"office\": \"London\",\n                    \"email\": \"carol@company.com\",\n                    \"projects\": 2\n                  },\n                  {\n                    \"name\": \"David Kim\",\n                    \"role\": \"Product Manager\",\n                    \"office\": \"San Francisco\",\n                    \"email\": \"david@company.com\",\n                    \"projects\": 7\n                  },\n                  {\n                    \"name\": \"Eva Mueller\",\n                    \"role\": \"Engineer\",\n                    \"office\": \"Berlin\",\n                    \"email\": \"eva@company.com\",\n                    \"projects\": 1\n                  },\n                  {\n                    \"name\": \"Frank Lee\",\n                    \"role\": \"Data Scientist\",\n                    \"office\": \"San Francisco\",\n                    \"email\": \"frank@company.com\",\n                    \"projects\": 4\n                  },\n                  {\n                    \"name\": \"Grace Park\",\n                    \"role\": \"Engineering Manager\",\n                    \"office\": \"New York\",\n                    \"email\": \"grace@company.com\",\n                    \"projects\": 6\n                  }\n                ],\n                \"search\": true,\n                \"paginated\": false,\n                \"pageSize\": 10,\n                \"onRowClick\": {\n                  \"action\": \"setState\",\n                  \"key\": \"selected\",\n                  \"value\": \"{{ $event }}\"\n                }\n              }\n            ]\n          },\n          {\n            \"type\": \"Condition\",\n            \"cases\": [\n              {\n                \"when\": \"{{ selected }}\",\n                \"children\": [\n                  {\n                    \"type\": \"Card\",\n                    \"children\": [\n                      {\n                        \"type\": \"CardHeader\",\n                        \"children\": [\n                          {\n                            \"cssClass\": \"gap-2 items-center\",\n                            \"type\": \"Row\",\n                            \"children\": [\n                              {\n                                \"content\": \"{{ selected.name }}\",\n                                \"type\": \"H3\"\n                              },\n                              {\n                                \"type\": \"Badge\",\n                                \"label\": \"{{ selected.office }}\",\n                                \"variant\": \"default\"\n                              }\n                            ]\n                          }\n                        ]\n                      },\n                      {\n                        \"type\": \"CardContent\",\n                        \"children\": [\n                          {\n                            \"cssClass\": \"gap-4 grid-cols-3\",\n                            \"type\": \"Grid\",\n                            \"children\": [\n                              {\n                                \"cssClass\": \"gap-0\",\n                                \"type\": \"Column\",\n                                \"children\": [\n                                  {\n                                    \"content\": \"Role\",\n                                    \"type\": \"Small\"\n                                  },\n                                  {\n                                    \"content\": \"{{ selected.role }}\",\n                                    \"type\": \"Text\"\n                                  }\n                                ]\n                              },\n                              {\n                                \"cssClass\": \"gap-0\",\n                                \"type\": \"Column\",\n                                \"children\": [\n                                  {\n                                    \"content\": \"Email\",\n                                    \"type\": \"Small\"\n                                  },\n                                  {\n                                    \"content\": \"{{ selected.email }}\",\n                                    \"type\": \"Text\"\n                                  }\n                                ]\n                              },\n                              {\n                                \"cssClass\": \"gap-0\",\n                                \"type\": \"Column\",\n                                \"children\": [\n                                  {\n                                    \"content\": \"Active Projects\",\n                                    \"type\": \"Small\"\n                                  },\n                                  {\n                                    \"content\": \"{{ selected.projects }}\",\n                                    \"type\": \"Text\"\n                                  }\n                                ]\n                              }\n                            ]\n                          }\n                        ]\n                      }\n                    ]\n                  }\n                ]\n              }\n            ]\n          }\n        ]\n      }\n    ]\n  },\n  \"state\": {\n    \"selected\": null\n  }\n}</script>\n</body>\n</html>","team-directory":"<!doctype html>\n<html lang=\"en\">\n<head>\n  <title>Prefab</title>\n  <meta charset=\"UTF-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <link rel=\"stylesheet\" crossorigin href=\"https://cdn.jsdelivr.net/npm/@prefecthq/prefab-ui@0.19.0/dist/app/renderer.css\">\n  <script type=\"module\" crossorigin src=\"https://cdn.jsdelivr.net/npm/@prefecthq/prefab-ui@0.19.0/dist/app/renderer.js\"></script>\n</head>\n<body>\n  <div id=\"root\" style=\"max-width:64rem;margin:0 auto;padding:2rem\"></div>\n  <script id=\"prefab:initial-data\" type=\"application/json\">{\n  \"$prefab\": {\n    \"version\": \"0.2\"\n  },\n  \"view\": {\n    \"cssClass\": \"pf-app-root\",\n    \"type\": \"Div\",\n    \"children\": [\n      {\n        \"cssClass\": \"gap-4 p-6\",\n        \"type\": \"Column\",\n        \"children\": [\n          {\n            \"cssClass\": \"gap-4\",\n            \"type\": \"Grid\",\n            \"columnTemplate\": \"1fr 2fr\",\n            \"children\": [\n              {\n                \"type\": \"PieChart\",\n                \"data\": [\n                  {\n                    \"office\": \"San Francisco\",\n                    \"count\": 3\n                  },\n                  {\n                    \"office\": \"New York\",\n                    \"count\": 2\n                  },\n                  {\n                    \"office\": \"London\",\n                    \"count\": 1\n                  },\n                  {\n                    \"office\": \"Berlin\",\n                    \"count\": 1\n                  }\n                ],\n                \"dataKey\": \"count\",\n                \"nameKey\": \"office\",\n                \"height\": 300,\n                \"innerRadius\": 0,\n                \"showLabel\": false,\n                \"paddingAngle\": 0,\n                \"showLegend\": true,\n                \"showTooltip\": true,\n                \"animate\": true\n              },\n              {\n                \"type\": \"DataTable\",\n                \"columns\": [\n                  {\n                    \"key\": \"name\",\n                    \"header\": \"Name\",\n                    \"sortable\": true\n                  },\n                  {\n                    \"key\": \"role\",\n                    \"header\": \"Role\",\n                    \"sortable\": true\n                  },\n                  {\n                    \"key\": \"office\",\n                    \"header\": \"Office\",\n                    \"sortable\": true\n                  }\n                ],\n                \"rows\": [\n                  {\n                    \"name\": \"Alice Chen\",\n                    \"role\": \"Staff Engineer\",\n                    \"office\": \"San Francisco\"\n                  },\n                  {\n                    \"name\": \"Bob Martinez\",\n                    \"role\": \"Lead Designer\",\n                    \"office\": \"New York\"\n                  },\n                  {\n                    \"name\": \"Carol Johnson\",\n                    \"role\": \"Senior Engineer\",\n                    \"office\": \"London\"\n                  },\n                  {\n                    \"name\": \"David Kim\",\n                    \"role\": \"Product Manager\",\n                    \"office\": \"San Francisco\"\n                  },\n                  {\n                    \"name\": \"Eva Mueller\",\n                    \"role\": \"Engineer\",\n                    \"office\": \"Berlin\"\n                  },\n                  {\n                    \"name\": \"Frank Lee\",\n                    \"role\": \"Data Scientist\",\n                    \"office\": \"San Francisco\"\n                  },\n                  {\n                    \"name\": \"Grace Park\",\n                    \"role\": \"Engineering Manager\",\n                    \"office\": \"New York\"\n                  }\n                ],\n                \"search\": true,\n                \"paginated\": false,\n                \"pageSize\": 10\n              }\n            ]\n          }\n        ]\n      }\n    ]\n  }\n}</script>\n</body>\n</html>"};
diff --git a/docs/public/schemas/fastmcp.json/latest.json b/docs/public/schemas/fastmcp.json/latest.json
new file mode 100644
index 0000000..aa1f59c
--- /dev/null
+++ b/docs/public/schemas/fastmcp.json/latest.json
@@ -0,0 +1,365 @@
+{
+  "$defs": {
+    "Deployment": {
+      "description": "Configuration for server deployment and runtime settings.",
+      "properties": {
+        "transport": {
+          "anyOf": [
+            {
+              "enum": [
+                "stdio",
+                "http",
+                "sse",
+                "streamable-http"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Transport protocol to use",
+          "title": "Transport"
+        },
+        "host": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Host to bind to when using HTTP transport",
+          "examples": [
+            "127.0.0.1",
+            "0.0.0.0",
+            "localhost"
+          ],
+          "title": "Host"
+        },
+        "port": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Port to bind to when using HTTP transport",
+          "examples": [
+            8000,
+            3000,
+            5000
+          ],
+          "title": "Port"
+        },
+        "path": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "URL path for the server endpoint",
+          "examples": [
+            "/mcp/",
+            "/api/mcp/",
+            "/sse/"
+          ],
+          "title": "Path"
+        },
+        "log_level": {
+          "anyOf": [
+            {
+              "enum": [
+                "DEBUG",
+                "INFO",
+                "WARNING",
+                "ERROR",
+                "CRITICAL"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Log level for the server",
+          "title": "Log Level"
+        },
+        "cwd": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Working directory for the server process",
+          "examples": [
+            ".",
+            "./src",
+            "/app"
+          ],
+          "title": "Cwd"
+        },
+        "env": {
+          "anyOf": [
+            {
+              "additionalProperties": {
+                "type": "string"
+              },
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Environment variables to set when running the server",
+          "examples": [
+            {
+              "API_KEY": "secret",
+              "DEBUG": "true"
+            }
+          ],
+          "title": "Env"
+        },
+        "args": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Arguments to pass to the server (after --)",
+          "examples": [
+            [
+              "--config",
+              "config.json",
+              "--debug"
+            ]
+          ],
+          "title": "Args"
+        }
+      },
+      "title": "Deployment",
+      "type": "object"
+    },
+    "FileSystemSource": {
+      "description": "Source for local Python files.",
+      "properties": {
+        "type": {
+          "const": "filesystem",
+          "default": "filesystem",
+          "title": "Type",
+          "type": "string"
+        },
+        "path": {
+          "description": "Path to Python file containing the server",
+          "title": "Path",
+          "type": "string"
+        },
+        "entrypoint": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Name of server instance or factory function (a no-arg function that returns a FastMCP server)",
+          "title": "Entrypoint"
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "title": "FileSystemSource",
+      "type": "object"
+    },
+    "UVEnvironment": {
+      "description": "Configuration for Python environment setup.",
+      "properties": {
+        "type": {
+          "const": "uv",
+          "default": "uv",
+          "title": "Type",
+          "type": "string"
+        },
+        "python": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Python version constraint",
+          "examples": [
+            "3.10",
+            "3.11",
+            "3.12"
+          ],
+          "title": "Python"
+        },
+        "dependencies": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Python packages to install with PEP 508 specifiers",
+          "examples": [
+            [
+              "fastmcp>=2.0,<3",
+              "httpx",
+              "pandas>=2.0"
+            ]
+          ],
+          "title": "Dependencies"
+        },
+        "requirements": {
+          "anyOf": [
+            {
+              "format": "path",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Path to requirements.txt file",
+          "examples": [
+            "requirements.txt",
+            "../requirements/prod.txt"
+          ],
+          "title": "Requirements"
+        },
+        "project": {
+          "anyOf": [
+            {
+              "format": "path",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Path to project directory containing pyproject.toml",
+          "examples": [
+            ".",
+            "../my-project"
+          ],
+          "title": "Project"
+        },
+        "editable": {
+          "anyOf": [
+            {
+              "items": {
+                "format": "path",
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Directories to install in editable mode",
+          "examples": [
+            [
+              ".",
+              "../my-package"
+            ],
+            [
+              "/path/to/package"
+            ]
+          ],
+          "title": "Editable"
+        }
+      },
+      "title": "UVEnvironment",
+      "type": "object"
+    }
+  },
+  "description": "Configuration file for FastMCP servers",
+  "properties": {
+    "$schema": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+      "description": "JSON schema for IDE support and validation",
+      "title": "$Schema"
+    },
+    "source": {
+      "$ref": "#/$defs/FileSystemSource",
+      "description": "Source configuration for the server",
+      "examples": [
+        {
+          "path": "server.py"
+        },
+        {
+          "entrypoint": "app",
+          "path": "server.py"
+        },
+        {
+          "entrypoint": "mcp",
+          "path": "src/server.py",
+          "type": "filesystem"
+        }
+      ]
+    },
+    "environment": {
+      "$ref": "#/$defs/UVEnvironment",
+      "description": "Python environment setup configuration"
+    },
+    "deployment": {
+      "$ref": "#/$defs/Deployment",
+      "description": "Server deployment and runtime settings"
+    }
+  },
+  "required": [
+    "source"
+  ],
+  "title": "FastMCP Configuration",
+  "type": "object",
+  "$id": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json"
+}
diff --git a/docs/public/schemas/fastmcp.json/v1.json b/docs/public/schemas/fastmcp.json/v1.json
new file mode 100644
index 0000000..aa1f59c
--- /dev/null
+++ b/docs/public/schemas/fastmcp.json/v1.json
@@ -0,0 +1,365 @@
+{
+  "$defs": {
+    "Deployment": {
+      "description": "Configuration for server deployment and runtime settings.",
+      "properties": {
+        "transport": {
+          "anyOf": [
+            {
+              "enum": [
+                "stdio",
+                "http",
+                "sse",
+                "streamable-http"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Transport protocol to use",
+          "title": "Transport"
+        },
+        "host": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Host to bind to when using HTTP transport",
+          "examples": [
+            "127.0.0.1",
+            "0.0.0.0",
+            "localhost"
+          ],
+          "title": "Host"
+        },
+        "port": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Port to bind to when using HTTP transport",
+          "examples": [
+            8000,
+            3000,
+            5000
+          ],
+          "title": "Port"
+        },
+        "path": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "URL path for the server endpoint",
+          "examples": [
+            "/mcp/",
+            "/api/mcp/",
+            "/sse/"
+          ],
+          "title": "Path"
+        },
+        "log_level": {
+          "anyOf": [
+            {
+              "enum": [
+                "DEBUG",
+                "INFO",
+                "WARNING",
+                "ERROR",
+                "CRITICAL"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Log level for the server",
+          "title": "Log Level"
+        },
+        "cwd": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Working directory for the server process",
+          "examples": [
+            ".",
+            "./src",
+            "/app"
+          ],
+          "title": "Cwd"
+        },
+        "env": {
+          "anyOf": [
+            {
+              "additionalProperties": {
+                "type": "string"
+              },
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Environment variables to set when running the server",
+          "examples": [
+            {
+              "API_KEY": "secret",
+              "DEBUG": "true"
+            }
+          ],
+          "title": "Env"
+        },
+        "args": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Arguments to pass to the server (after --)",
+          "examples": [
+            [
+              "--config",
+              "config.json",
+              "--debug"
+            ]
+          ],
+          "title": "Args"
+        }
+      },
+      "title": "Deployment",
+      "type": "object"
+    },
+    "FileSystemSource": {
+      "description": "Source for local Python files.",
+      "properties": {
+        "type": {
+          "const": "filesystem",
+          "default": "filesystem",
+          "title": "Type",
+          "type": "string"
+        },
+        "path": {
+          "description": "Path to Python file containing the server",
+          "title": "Path",
+          "type": "string"
+        },
+        "entrypoint": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Name of server instance or factory function (a no-arg function that returns a FastMCP server)",
+          "title": "Entrypoint"
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "title": "FileSystemSource",
+      "type": "object"
+    },
+    "UVEnvironment": {
+      "description": "Configuration for Python environment setup.",
+      "properties": {
+        "type": {
+          "const": "uv",
+          "default": "uv",
+          "title": "Type",
+          "type": "string"
+        },
+        "python": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Python version constraint",
+          "examples": [
+            "3.10",
+            "3.11",
+            "3.12"
+          ],
+          "title": "Python"
+        },
+        "dependencies": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Python packages to install with PEP 508 specifiers",
+          "examples": [
+            [
+              "fastmcp>=2.0,<3",
+              "httpx",
+              "pandas>=2.0"
+            ]
+          ],
+          "title": "Dependencies"
+        },
+        "requirements": {
+          "anyOf": [
+            {
+              "format": "path",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Path to requirements.txt file",
+          "examples": [
+            "requirements.txt",
+            "../requirements/prod.txt"
+          ],
+          "title": "Requirements"
+        },
+        "project": {
+          "anyOf": [
+            {
+              "format": "path",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Path to project directory containing pyproject.toml",
+          "examples": [
+            ".",
+            "../my-project"
+          ],
+          "title": "Project"
+        },
+        "editable": {
+          "anyOf": [
+            {
+              "items": {
+                "format": "path",
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Directories to install in editable mode",
+          "examples": [
+            [
+              ".",
+              "../my-package"
+            ],
+            [
+              "/path/to/package"
+            ]
+          ],
+          "title": "Editable"
+        }
+      },
+      "title": "UVEnvironment",
+      "type": "object"
+    }
+  },
+  "description": "Configuration file for FastMCP servers",
+  "properties": {
+    "$schema": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+      "description": "JSON schema for IDE support and validation",
+      "title": "$Schema"
+    },
+    "source": {
+      "$ref": "#/$defs/FileSystemSource",
+      "description": "Source configuration for the server",
+      "examples": [
+        {
+          "path": "server.py"
+        },
+        {
+          "entrypoint": "app",
+          "path": "server.py"
+        },
+        {
+          "entrypoint": "mcp",
+          "path": "src/server.py",
+          "type": "filesystem"
+        }
+      ]
+    },
+    "environment": {
+      "$ref": "#/$defs/UVEnvironment",
+      "description": "Python environment setup configuration"
+    },
+    "deployment": {
+      "$ref": "#/$defs/Deployment",
+      "description": "Server deployment and runtime settings"
+    }
+  },
+  "required": [
+    "source"
+  ],
+  "title": "FastMCP Configuration",
+  "type": "object",
+  "$id": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json"
+}
diff --git a/docs/python-sdk-pages.json b/docs/python-sdk-pages.json
new file mode 100644
index 0000000..6d71d0d
--- /dev/null
+++ b/docs/python-sdk-pages.json
@@ -0,0 +1,92 @@
+[
+  "python-sdk/fastmcp-cli",
+  "python-sdk/fastmcp-decorators",
+  "python-sdk/fastmcp-dependencies",
+  "python-sdk/fastmcp-exceptions",
+  "python-sdk/fastmcp-mcp_config",
+  "python-sdk/fastmcp-settings",
+  "python-sdk/fastmcp-telemetry",
+  "python-sdk/fastmcp-types",
+  {
+    "group": "fastmcp.apps",
+    "pages": [
+      "python-sdk/fastmcp-apps-__init__",
+      "python-sdk/fastmcp-apps-app",
+      "python-sdk/fastmcp-apps-approval",
+      "python-sdk/fastmcp-apps-choice",
+      "python-sdk/fastmcp-apps-config",
+      "python-sdk/fastmcp-apps-file_upload",
+      "python-sdk/fastmcp-apps-form",
+      "python-sdk/fastmcp-apps-generative"
+    ]
+  },
+  {
+    "group": "fastmcp.experimental",
+    "pages": [
+      {
+        "group": "transforms",
+        "pages": [
+          "python-sdk/fastmcp-experimental-transforms-code_mode"
+        ]
+      }
+    ]
+  },
+  {
+    "group": "fastmcp.utilities",
+    "pages": [
+      "python-sdk/fastmcp-utilities-__init__",
+      "python-sdk/fastmcp-utilities-async_utils",
+      "python-sdk/fastmcp-utilities-auth",
+      "python-sdk/fastmcp-utilities-authorization",
+      "python-sdk/fastmcp-utilities-cli",
+      "python-sdk/fastmcp-utilities-components",
+      "python-sdk/fastmcp-utilities-docstring_parsing",
+      "python-sdk/fastmcp-utilities-exceptions",
+      "python-sdk/fastmcp-utilities-http",
+      "python-sdk/fastmcp-utilities-inspect",
+      "python-sdk/fastmcp-utilities-json_schema",
+      "python-sdk/fastmcp-utilities-json_schema_type",
+      "python-sdk/fastmcp-utilities-lifespan",
+      "python-sdk/fastmcp-utilities-logging",
+      {
+        "group": "mcp_server_config",
+        "pages": [
+          "python-sdk/fastmcp-utilities-mcp_server_config-__init__",
+          {
+            "group": "v1",
+            "pages": [
+              {
+                "group": "environments",
+                "pages": [
+                  "python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-__init__",
+                  "python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-base",
+                  "python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-uv"
+                ]
+              },
+              "python-sdk/fastmcp-utilities-mcp_server_config-v1-mcp_server_config",
+              {
+                "group": "sources",
+                "pages": [
+                  "python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-base",
+                  "python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-filesystem"
+                ]
+              }
+            ]
+          }
+        ]
+      },
+      "python-sdk/fastmcp-utilities-mime",
+      "python-sdk/fastmcp-utilities-openapi",
+      "python-sdk/fastmcp-utilities-pagination",
+      "python-sdk/fastmcp-utilities-skills",
+      "python-sdk/fastmcp-utilities-tasks",
+      "python-sdk/fastmcp-utilities-tests",
+      "python-sdk/fastmcp-utilities-timeout",
+      "python-sdk/fastmcp-utilities-token_cache",
+      "python-sdk/fastmcp-utilities-types",
+      "python-sdk/fastmcp-utilities-ui",
+      "python-sdk/fastmcp-utilities-version_check",
+      "python-sdk/fastmcp-utilities-versions"
+    ]
+  }
+]
diff --git a/docs/python-sdk/fastmcp-apps-__init__.mdx b/docs/python-sdk/fastmcp-apps-__init__.mdx
new file mode 100644
index 0000000..5f69a4b
--- /dev/null
+++ b/docs/python-sdk/fastmcp-apps-__init__.mdx
@@ -0,0 +1,16 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.apps`
+
+
+FastMCP Apps — interactive UIs for MCP tools.
+
+This package contains the app-related components:
+
+- ``FastMCPApp`` — composable provider for interactive apps with backend tools
+- ``AppConfig`` — configuration for MCP App tools and resources
+- ``ResourceCSP`` / ``ResourcePermissions`` — security configuration
+
diff --git a/docs/python-sdk/fastmcp-apps-app.mdx b/docs/python-sdk/fastmcp-apps-app.mdx
new file mode 100644
index 0000000..4b10923
--- /dev/null
+++ b/docs/python-sdk/fastmcp-apps-app.mdx
@@ -0,0 +1,146 @@
+---
+title: app
+sidebarTitle: app
+---
+
+# `fastmcp.apps.app`
+
+
+FastMCPApp — a Provider that represents a composable MCP application.
+
+FastMCPApp binds entry-point tools (model calls these) together with backend
+tools (the UI calls these via CallTool).  Backend tools are tagged with
+``meta["fastmcp"]["app"]`` so they can be found through the provider chain
+even when transforms (namespace, visibility, etc.) have renamed or hidden
+them — the server sets a context var that tells ``Provider.get_tool`` to
+fall back to a direct lookup for app-visible tools.
+
+Usage::
+
+    from fastmcp import FastMCP, FastMCPApp
+
+    app = FastMCPApp("Dashboard")
+
+    @app.ui()
+    def show_dashboard() -> Component:
+        return Column(...)
+
+    @app.tool()
+    def save_contact(name: str, email: str) -> str:
+        return name
+
+    server = FastMCP("Platform")
+    server.add_provider(app)
+
+
+## Classes
+
+### `FastMCPApp` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Provider that represents an MCP application.
+
+Binds together entry-point tools (``@app.ui``), backend tools
+(``@app.tool``), and the Prefab renderer resource.  Backend tools
+are tagged with ``meta["fastmcp"]["app"]`` so ``Provider.get_tool``
+can find them by original name even when transforms have been applied.
+
+
+**Methods:**
+
+#### `tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+tool(self, name_or_fn: F) -> F
+```
+
+#### `tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L180" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+tool(self, name_or_fn: str | None = None) -> Callable[[F], F]
+```
+
+#### `tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L191" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+tool(self, name_or_fn: str | AnyFunction | None = None) -> Any
+```
+
+Register a backend tool that the UI calls via CallTool.
+
+Backend tools default to ``visibility=["app"]``.  Pass ``model=True``
+to also expose the tool to the model (``visibility=["app", "model"]``).
+
+Supports multiple calling patterns::
+
+    @app.tool
+    def save(name: str): ...
+
+    @app.tool()
+    def save(name: str): ...
+
+    @app.tool("custom_name")
+    def save(name: str): ...
+
+
+#### `ui` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L258" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+ui(self, name_or_fn: F) -> F
+```
+
+#### `ui` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L273" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+ui(self, name_or_fn: str | None = None) -> Callable[[F], F]
+```
+
+#### `ui` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L287" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+ui(self, name_or_fn: str | AnyFunction | None = None) -> Any
+```
+
+Register a UI entry-point tool that the model calls.
+
+Entry-point tools default to ``visibility=["model"]`` and auto-wire
+the Prefab renderer resource and CSP. They are tagged with the app
+name so structured content includes ``_meta.fastmcp.app``.
+
+Supports multiple calling patterns::
+
+    @app.ui
+    def dashboard() -> Component: ...
+
+    @app.ui()
+    def dashboard() -> Component: ...
+
+    @app.ui("my_dashboard")
+    def dashboard() -> Component: ...
+
+
+#### `add_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L362" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_tool(self, tool: Tool | Callable[..., Any]) -> Tool
+```
+
+Add a tool to this app programmatically.
+
+The tool is tagged with this app's name for routing.
+
+
+#### `lifespan` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L418" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+lifespan(self) -> AsyncIterator[None]
+```
+
+#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/app.py#L426" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run(self, transport: Literal['stdio', 'http', 'sse', 'streamable-http'] | None = None, **kwargs: Any) -> None
+```
+
+Create a temporary FastMCP server and run this app standalone.
+
diff --git a/docs/python-sdk/fastmcp-apps-approval.mdx b/docs/python-sdk/fastmcp-apps-approval.mdx
new file mode 100644
index 0000000..81285a7
--- /dev/null
+++ b/docs/python-sdk/fastmcp-apps-approval.mdx
@@ -0,0 +1,58 @@
+---
+title: approval
+sidebarTitle: approval
+---
+
+# `fastmcp.apps.approval`
+
+
+Approval — a Provider that adds human-in-the-loop approval to any server.
+
+The LLM presents a summary of what it's about to do, and the user
+approves or rejects via buttons. The result is sent back into the
+conversation as a message, prompting the LLM's next turn.
+
+Requires ``fastmcp[apps]`` (prefab-ui).
+
+Usage::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps.approval import Approval
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(Approval())
+
+
+## Classes
+
+### `Approval` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/approval.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Provider that adds human-in-the-loop approval to a server.
+
+The LLM calls the ``request_approval`` tool with a summary and
+optional details. The user sees an approval card with Approve and
+Reject buttons. Clicking either sends a message back into the
+conversation (via ``SendMessage``), triggering the LLM's next turn.
+
+The message appears as if the user sent it, so the LLM sees
+something like ``'"Deploy v3.2 to production" is APPROVED'``.
+
+Example::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps.approval import Approval
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(Approval())
+
+Customized::
+
+    Approval(
+        title="Deploy Gate",
+        approve_text="Ship it",
+        approve_variant="default",
+        reject_text="Abort",
+        reject_variant="destructive",
+    )
+
diff --git a/docs/python-sdk/fastmcp-apps-choice.mdx b/docs/python-sdk/fastmcp-apps-choice.mdx
new file mode 100644
index 0000000..8b75726
--- /dev/null
+++ b/docs/python-sdk/fastmcp-apps-choice.mdx
@@ -0,0 +1,44 @@
+---
+title: choice
+sidebarTitle: choice
+---
+
+# `fastmcp.apps.choice`
+
+
+Choice — a Provider that lets the user pick from a set of options.
+
+The LLM presents options, the user clicks one, and the selection
+flows back into the conversation as a message.
+
+Requires ``fastmcp[apps]`` (prefab-ui).
+
+Usage::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps.choice import Choice
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(Choice())
+
+
+## Classes
+
+### `Choice` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/choice.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Provider that lets the user choose from a set of options.
+
+The LLM calls ``choose`` with a prompt and a list of options.
+The user sees a card with one button per option. Clicking a button
+sends the selection back into the conversation via ``SendMessage``,
+triggering the LLM's next turn.
+
+Example::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps.choice import Choice
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(Choice())
+
diff --git a/docs/python-sdk/fastmcp-apps-config.mdx b/docs/python-sdk/fastmcp-apps-config.mdx
new file mode 100644
index 0000000..9d0c3ac
--- /dev/null
+++ b/docs/python-sdk/fastmcp-apps-config.mdx
@@ -0,0 +1,90 @@
+---
+title: config
+sidebarTitle: config
+---
+
+# `fastmcp.apps.config`
+
+
+MCP Apps support — extension negotiation and typed UI metadata models.
+
+Provides constants and Pydantic models for the MCP Apps extension
+(io.modelcontextprotocol/ui), enabling tools and resources to carry
+UI metadata for clients that support interactive app rendering.
+
+
+## Functions
+
+### `app_config_to_meta_dict` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/config.py#L180" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+app_config_to_meta_dict(app: AppConfig | dict[str, Any]) -> dict[str, Any]
+```
+
+
+Convert an AppConfig or dict to the wire-format dict for ``meta["ui"]``.
+
+
+## Classes
+
+### `ResourceCSP` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/config.py#L20" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Content Security Policy for MCP App resources.
+
+Declares which external origins the app is allowed to connect to or
+load resources from.  Hosts use these declarations to build the
+``Content-Security-Policy`` header for the sandboxed iframe.
+
+
+### `ResourcePermissions` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/config.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Iframe sandbox permissions for MCP App resources.
+
+Each field, when set (typically to ``{}``), requests that the host
+grant the corresponding Permission Policy feature to the sandboxed
+iframe.  Hosts MAY honour these; apps should use JS feature detection
+as a fallback.
+
+
+### `AppConfig` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/config.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Configuration for MCP App tools and resources.
+
+Controls how a tool or resource participates in the MCP Apps extension.
+On tools, ``resource_uri`` and ``visibility`` specify which UI resource
+to render and where the tool appears.  On resources, those fields must
+be left unset (the resource itself is the UI).
+
+All fields use ``exclude_none`` serialization so only explicitly-set
+values appear on the wire.  Aliases match the MCP Apps wire format
+(camelCase).
+
+
+### `PrefabAppConfig` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/config.py#L124" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+App configuration for Prefab tools with sensible defaults.
+
+Like ``app=True`` but customizable. Auto-wires the Prefab renderer
+URI and merges the renderer's CSP with any additional domains you
+specify.  The renderer resource is registered automatically.
+
+Example::
+
+    @mcp.tool(app=PrefabAppConfig())  # same as app=True
+
+    @mcp.tool(app=PrefabAppConfig(
+        csp=ResourceCSP(frame_domains=["https://example.com"]),
+    ))
+
+
+**Methods:**
+
+#### `model_post_init` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/config.py#L140" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+model_post_init(self, __context: Any) -> None
+```
diff --git a/docs/python-sdk/fastmcp-apps-file_upload.mdx b/docs/python-sdk/fastmcp-apps-file_upload.mdx
new file mode 100644
index 0000000..878cbae
--- /dev/null
+++ b/docs/python-sdk/fastmcp-apps-file_upload.mdx
@@ -0,0 +1,144 @@
+---
+title: file_upload
+sidebarTitle: file_upload
+---
+
+# `fastmcp.apps.file_upload`
+
+
+FileUpload — a Provider that adds drag-and-drop file upload to any server.
+
+Lets users upload files directly to the server through an interactive UI,
+bypassing the LLM context window entirely. The LLM can then read and work
+with uploaded files through model-visible tools.
+
+Requires ``fastmcp[apps]`` (prefab-ui).
+
+Usage::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps import FileUpload
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(FileUpload())
+
+For custom persistence, override the storage methods::
+
+    class S3Upload(FileUpload):
+        def on_store(self, files, ctx):
+            # write to S3, return summaries
+            ...
+
+        def on_list(self, ctx):
+            # list from S3
+            ...
+
+        def on_read(self, name, ctx):
+            # read from S3
+            ...
+
+
+## Classes
+
+### `FileUpload` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/file_upload.py#L102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Provider that adds file upload capabilities to a server.
+
+Registers a drag-and-drop UI tool, a backend storage tool, and
+model-visible tools for listing and reading uploaded files.
+
+Files are scoped by MCP session and stored in memory by default.
+Override ``on_store``, ``on_list``, and ``on_read`` for custom
+persistence (filesystem, S3, database, etc.). Each method receives
+the current ``Context``, giving access to session ID, auth tokens,
+and request metadata for partitioning and authorization.
+
+**Session scoping:** The default storage uses ``ctx.session_id`` to
+isolate files by session. This works with stdio, SSE, and stateful
+HTTP transports. In **stateless HTTP** mode, each request creates a
+new session, so files won't persist across requests. For stateless
+deployments, override the storage methods to partition by a stable
+identifier from the auth context::
+
+    class UserScopedUpload(FileUpload):
+        def on_store(self, files, ctx):
+            user_id = ctx.access_token["sub"]
+            ...
+
+Example::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps.file_upload import FileUpload
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(FileUpload())
+
+
+**Methods:**
+
+#### `on_store` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/file_upload.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_store(self, files: list[dict[str, Any]], ctx: Context) -> list[dict[str, Any]]
+```
+
+Store uploaded files and return summaries.
+
+**Args:**
+- `files`: List of file dicts, each with ``name``, ``size``,
+``type``, and ``data`` (base64-encoded content).
+- `ctx`: The current request context. Use for session ID,
+auth tokens, or any metadata needed for partitioning.
+
+Override this method for custom persistence. The default
+implementation stores files in memory, scoped by
+``_get_scope_key(ctx)``.
+
+**Returns:**
+- List of file summary dicts (``name``, ``type``, ``size``,
+- ``size_display``, ``uploaded_at``).
+
+
+#### `on_list` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/file_upload.py#L216" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_list(self, ctx: Context) -> list[dict[str, Any]]
+```
+
+List all stored files.
+
+**Args:**
+- `ctx`: The current request context.
+
+Override this method for custom persistence. The default
+implementation returns files from the current scope.
+
+**Returns:**
+- List of file summary dicts.
+
+
+#### `on_read` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/file_upload.py#L232" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_read(self, name: str, ctx: Context) -> dict[str, Any]
+```
+
+Read a file's contents by name.
+
+**Args:**
+- `name`: The filename to read.
+- `ctx`: The current request context.
+
+Override this method for custom persistence. The default
+implementation reads from the current scope's in-memory store.
+Text files are decoded from base64; binary files return a
+truncated base64 preview.
+
+**Returns:**
+- Dict with file metadata and ``content`` (text) or
+- ``content_base64`` (binary preview).
+
+**Raises:**
+- `ValueError`: If the file is not found.
+
diff --git a/docs/python-sdk/fastmcp-apps-form.mdx b/docs/python-sdk/fastmcp-apps-form.mdx
new file mode 100644
index 0000000..c99110c
--- /dev/null
+++ b/docs/python-sdk/fastmcp-apps-form.mdx
@@ -0,0 +1,69 @@
+---
+title: form
+sidebarTitle: form
+---
+
+# `fastmcp.apps.form`
+
+
+FormInput — a Provider that collects structured input from the user.
+
+Define a Pydantic model for the data you need, and ``FormInput``
+generates a form UI. The user fills it out, the submission is
+validated, and an optional callback processes the result.
+
+Requires ``fastmcp[apps]`` (prefab-ui).
+
+Usage::
+
+    from pydantic import BaseModel
+    from fastmcp import FastMCP
+    from fastmcp.apps.form import FormInput
+
+    class ShippingAddress(BaseModel):
+        street: str
+        city: str
+        state: str
+        zip_code: str
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(FormInput(model=ShippingAddress))
+
+
+## Classes
+
+### `FormInput` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/form.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Provider that collects structured input via a Pydantic model.
+
+Define a model for the data you need, and ``FormInput`` generates
+a form from it using ``Form.from_model()``. Field types, labels,
+descriptions, and validation are all derived from the model.
+
+Optionally provide an ``on_submit`` callback to process the
+validated data. The callback receives a model instance and returns
+a string that goes back to the LLM. Without a callback, the
+validated JSON is sent directly.
+
+Example::
+
+    from pydantic import BaseModel
+    from fastmcp import FastMCP
+    from fastmcp.apps.form import FormInput
+
+    class Contact(BaseModel):
+        name: str
+        email: str
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(FormInput(model=Contact))
+
+With a callback::
+
+    def save_contact(contact: Contact) -> str:
+        db.insert(contact.model_dump())
+        return f"Saved {contact.name}"
+
+    mcp.add_provider(FormInput(model=Contact, on_submit=save_contact))
+
diff --git a/docs/python-sdk/fastmcp-apps-generative.mdx b/docs/python-sdk/fastmcp-apps-generative.mdx
new file mode 100644
index 0000000..bb5756b
--- /dev/null
+++ b/docs/python-sdk/fastmcp-apps-generative.mdx
@@ -0,0 +1,56 @@
+---
+title: generative
+sidebarTitle: generative
+---
+
+# `fastmcp.apps.generative`
+
+
+GenerativeUI — a Provider that adds LLM-generated UI capabilities.
+
+Registers tools and resources from ``prefab_ui.generative`` so that an
+LLM can write Prefab Python code, execute it in a sandbox, and render
+the result as a streaming interactive UI.
+
+Requires ``fastmcp[apps]`` (prefab-ui).
+
+Usage::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps.generative import GenerativeUI
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(GenerativeUI())
+
+
+## Classes
+
+### `GenerativeUI` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/generative.py#L53" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Provider that adds generative UI capabilities to a server.
+
+Registers:
+
+- A ``generate_ui`` tool that accepts Prefab Python code, executes
+  it in a Pyodide sandbox, and returns the rendered PrefabApp.
+  Supports streaming via ``ontoolinputpartial``.
+- A ``components`` tool that searches the Prefab component library.
+- The generative renderer resource with CSP for Pyodide CDN access.
+
+Example::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps.generative import GenerativeUI
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(GenerativeUI())
+
+
+**Methods:**
+
+#### `lifespan` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/apps/generative.py#L196" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+lifespan(self) -> AsyncIterator[None]
+```
diff --git a/docs/python-sdk/fastmcp-cli.mdx b/docs/python-sdk/fastmcp-cli.mdx
new file mode 100644
index 0000000..4cc1327
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli.mdx
@@ -0,0 +1,9 @@
+---
+title: cli
+sidebarTitle: cli
+---
+
+# `fastmcp.cli`
+
+
+FastMCP CLI package.
diff --git a/docs/python-sdk/fastmcp-decorators.mdx b/docs/python-sdk/fastmcp-decorators.mdx
new file mode 100644
index 0000000..0eb68b2
--- /dev/null
+++ b/docs/python-sdk/fastmcp-decorators.mdx
@@ -0,0 +1,39 @@
+---
+title: decorators
+sidebarTitle: decorators
+---
+
+# `fastmcp.decorators`
+
+
+Shared decorator utilities for FastMCP.
+
+## Functions
+
+### `resolve_task_config` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/decorators.py#L17" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+resolve_task_config(task: bool | TaskConfig | None) -> bool | TaskConfig
+```
+
+
+Resolve task config, defaulting None to False.
+
+
+### `get_fastmcp_meta` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/decorators.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_fastmcp_meta(fn: Any) -> Any | None
+```
+
+
+Extract FastMCP metadata from a function, handling bound methods and wrappers.
+
+
+## Classes
+
+### `HasFastMCPMeta` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/decorators.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Protocol for callables decorated with FastMCP metadata.
+
diff --git a/docs/python-sdk/fastmcp-dependencies.mdx b/docs/python-sdk/fastmcp-dependencies.mdx
new file mode 100644
index 0000000..f27566e
--- /dev/null
+++ b/docs/python-sdk/fastmcp-dependencies.mdx
@@ -0,0 +1,17 @@
+---
+title: dependencies
+sidebarTitle: dependencies
+---
+
+# `fastmcp.dependencies`
+
+
+Dependency injection exports for FastMCP.
+
+This module re-exports dependency injection symbols to provide a clean,
+centralized import location for all dependency-related functionality.
+
+DI features (Depends, CurrentContext, CurrentFastMCP) work without pydocket
+using the uncalled-for DI engine. Only task-related dependencies (CurrentDocket,
+CurrentWorker) and background task execution require fastmcp[tasks].
+
diff --git a/docs/python-sdk/fastmcp-exceptions.mdx b/docs/python-sdk/fastmcp-exceptions.mdx
new file mode 100644
index 0000000..eb554c3
--- /dev/null
+++ b/docs/python-sdk/fastmcp-exceptions.mdx
@@ -0,0 +1,81 @@
+---
+title: exceptions
+sidebarTitle: exceptions
+---
+
+# `fastmcp.exceptions`
+
+
+Custom exceptions for FastMCP.
+
+## Classes
+
+### `FastMCPDeprecationWarning` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L13" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Deprecation warning for FastMCP APIs.
+
+Subclass of DeprecationWarning so that standard warning filters
+still apply, but FastMCP can selectively enable its own warnings
+without affecting other libraries in the process.
+
+
+### `FastMCPError` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Base error for FastMCP.
+
+
+### `ValidationError` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Error in validating parameters or return values.
+
+
+### `ResourceError` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Error in resource operations.
+
+
+### `ToolError` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Error in tool operations.
+
+
+### `PromptError` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Error in prompt operations.
+
+
+### `InvalidSignature` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Invalid signature for use with FastMCP.
+
+
+### `ClientError` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L50" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Error in client operations.
+
+
+### `NotFoundError` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Object not found.
+
+
+### `DisabledError` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Object is disabled.
+
+
+### `AuthorizationError` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Error when authorization check fails.
+
diff --git a/docs/python-sdk/fastmcp-experimental-transforms-code_mode.mdx b/docs/python-sdk/fastmcp-experimental-transforms-code_mode.mdx
new file mode 100644
index 0000000..6d634b6
--- /dev/null
+++ b/docs/python-sdk/fastmcp-experimental-transforms-code_mode.mdx
@@ -0,0 +1,142 @@
+---
+title: code_mode
+sidebarTitle: code_mode
+---
+
+# `fastmcp.experimental.transforms.code_mode`
+
+## Classes
+
+### `SandboxProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Interface for executing LLM-generated Python code in a sandbox.
+
+WARNING: The ``code`` parameter passed to ``run`` contains untrusted,
+LLM-generated Python.  Implementations MUST execute it in an isolated
+sandbox — never with plain ``exec()``.  Use ``MontySandboxProvider``
+(backed by ``pydantic-monty``) for production workloads.
+
+
+**Methods:**
+
+#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run(self, code: str) -> Any
+```
+
+### `MontySandboxProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Sandbox provider backed by `pydantic-monty`.
+
+**Args:**
+- `limits`: Resource limits for sandbox execution. Supported keys\:
+``max_duration_secs`` (float), ``max_allocations`` (int),
+``max_memory`` (int), ``max_recursion_depth`` (int),
+``gc_interval`` (int).  All are optional; omit a key to
+leave that limit uncapped.
+
+When the argument is omitted entirely, a conservative baseline
+is applied (``max_duration_secs=30``, ``max_memory=100 MB``) so
+the out-of-box configuration is not unbounded. Pass
+``limits=None`` to explicitly run without any limits, or a dict
+to set your own.
+
+
+**Methods:**
+
+#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run(self, code: str) -> Any
+```
+
+### `Search` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L238" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Discovery tool factory that searches the catalog by query.
+
+**Args:**
+- `search_fn`: Async callable ``(tools, query) -> matching_tools``.
+Defaults to BM25 ranking.
+- `name`: Name of the synthetic tool exposed to the LLM.
+- `default_detail`: Default detail level for search results.
+``"brief"`` returns tool names and descriptions only.
+``"detailed"`` returns compact markdown with parameter schemas.
+``"full"`` returns complete JSON tool definitions.
+- `default_limit`: Maximum number of results to return.
+The LLM can override this per call.  ``None`` means no limit.
+
+
+### `GetSchemas` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L320" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Discovery tool factory that returns schemas for tools by name.
+
+**Args:**
+- `name`: Name of the synthetic tool exposed to the LLM.
+- `default_detail`: Default detail level for schema results.
+``"brief"`` returns tool names and descriptions only.
+``"detailed"`` renders compact markdown with parameter names,
+types, and required markers.
+``"full"`` returns the complete JSON schema.
+
+
+### `GetTags` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L381" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Discovery tool factory that lists tool tags from the catalog.
+
+Reads ``tool.tags`` from the catalog and groups tools by tag. Tools
+without tags appear under ``"untagged"``.
+
+**Args:**
+- `name`: Name of the synthetic tool exposed to the LLM.
+- `default_detail`: Default detail level.
+``"brief"`` returns tag names with tool counts.
+``"full"`` lists all tools under each tag.
+
+
+### `ListTools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L448" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Discovery tool factory that lists all tools in the catalog.
+
+**Args:**
+- `name`: Name of the synthetic tool exposed to the LLM.
+- `default_detail`: Default detail level.
+``"brief"`` returns tool names and one-line descriptions.
+``"detailed"`` returns compact markdown with parameter schemas.
+``"full"`` returns the complete JSON schema.
+
+
+### `CodeMode` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L497" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Transform that collapses all tools into discovery + execute meta-tools.
+
+Discovery tools are composable via the ``discovery_tools`` parameter.
+Each is a callable that receives catalog access and returns a ``Tool``.
+By default, ``Search`` and ``GetSchemas`` are included for
+progressive disclosure: search finds candidates, get_schema retrieves
+parameter details, and execute runs code.
+
+The ``execute`` tool is always present and provides a sandboxed Python
+environment with ``call_tool(name, params)`` in scope.
+
+
+**Methods:**
+
+#### `transform_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L549" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+transform_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]
+```
+
+#### `get_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L552" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tool(self, name: str, call_next: GetToolNext) -> Tool | None
+```
diff --git a/docs/python-sdk/fastmcp-mcp_config.mdx b/docs/python-sdk/fastmcp-mcp_config.mdx
new file mode 100644
index 0000000..0302d92
--- /dev/null
+++ b/docs/python-sdk/fastmcp-mcp_config.mdx
@@ -0,0 +1,188 @@
+---
+title: mcp_config
+sidebarTitle: mcp_config
+---
+
+# `fastmcp.mcp_config`
+
+
+Canonical MCP Configuration Format.
+
+This module defines the standard configuration format for Model Context Protocol (MCP) servers.
+It provides a client-agnostic, extensible format that can be used across all MCP implementations.
+
+The configuration format supports both stdio and remote (HTTP/SSE) transports, with comprehensive
+field definitions for server metadata, authentication, and execution parameters.
+
+Example configuration:
+```json
+{
+    "mcpServers": {
+        "my-server": {
+            "command": "npx",
+            "args": ["-y", "@my/mcp-server"],
+            "env": {"API_KEY": "secret"},
+            "timeout": 30000,
+            "description": "My MCP server"
+        }
+    }
+}
+```
+
+
+## Functions
+
+### `infer_transport_type_from_url` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+infer_transport_type_from_url(url: str | AnyUrl) -> Literal['http', 'sse']
+```
+
+
+Infer the appropriate transport type from the given URL.
+
+
+### `update_config_file` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L363" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+update_config_file(file_path: Path, server_name: str, server_config: CanonicalMCPServerTypes) -> None
+```
+
+
+Update an MCP configuration file from a server object, preserving existing fields.
+
+This is used for updating the mcpServer configurations of third-party tools so we do not
+worry about transforming server objects here.
+
+
+## Classes
+
+### `StdioMCPServer` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+MCP server configuration for stdio transport.
+
+This is the canonical configuration format for MCP servers using stdio transport.
+
+
+**Methods:**
+
+#### `to_transport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+to_transport(self) -> StdioTransport
+```
+
+### `TransformingStdioMCPServer` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Stdio server with tool transforms.
+
+
+### `RemoteMCPServer` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L217" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+MCP server configuration for HTTP/SSE transport.
+
+This is the canonical configuration format for MCP servers using remote transports.
+
+
+**Methods:**
+
+#### `to_transport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L253" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+to_transport(self) -> StreamableHttpTransport | SSETransport
+```
+
+### `TransformingRemoteMCPServer` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L281" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Remote server with tool transforms.
+
+
+### `MCPConfig` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L292" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A configuration object for MCP Servers that conforms to the canonical MCP configuration format
+while adding additional fields for enabling FastMCP-specific features like tool transformations
+and filtering by tags.
+
+For an MCPConfig that is strictly canonical, see the `CanonicalMCPConfig` class.
+
+
+**Methods:**
+
+#### `wrap_servers_at_root` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L306" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+wrap_servers_at_root(cls, values: dict[str, Any]) -> dict[str, Any]
+```
+
+If there's no mcpServers key but there are server configs at root, wrap them.
+
+
+#### `add_server` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L319" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_server(self, name: str, server: MCPServerTypes) -> None
+```
+
+Add or update a server in the configuration.
+
+
+#### `from_dict` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L324" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_dict(cls, config: dict[str, Any]) -> Self
+```
+
+Parse MCP configuration from dictionary format.
+
+
+#### `to_dict` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L328" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+to_dict(self) -> dict[str, Any]
+```
+
+Convert MCPConfig to dictionary format, preserving all fields.
+
+
+#### `write_to_file` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L332" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+write_to_file(self, file_path: Path) -> None
+```
+
+Write configuration to JSON file.
+
+
+#### `from_file` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L338" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_file(cls, file_path: Path) -> Self
+```
+
+Load configuration from JSON file.
+
+
+### `CanonicalMCPConfig` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L348" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Canonical MCP configuration format.
+
+This defines the standard configuration format for Model Context Protocol servers.
+The format is designed to be client-agnostic and extensible for future use cases.
+
+
+**Methods:**
+
+#### `add_server` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/mcp_config.py#L358" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_server(self, name: str, server: CanonicalMCPServerTypes) -> None
+```
+
+Add or update a server in the configuration.
+
diff --git a/docs/python-sdk/fastmcp-settings.mdx b/docs/python-sdk/fastmcp-settings.mdx
new file mode 100644
index 0000000..87940be
--- /dev/null
+++ b/docs/python-sdk/fastmcp-settings.mdx
@@ -0,0 +1,48 @@
+---
+title: settings
+sidebarTitle: settings
+---
+
+# `fastmcp.settings`
+
+## Classes
+
+### `DocketSettings` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/settings.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Docket worker configuration.
+
+
+### `Settings` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/settings.py#L136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+FastMCP settings.
+
+
+**Methods:**
+
+#### `get_setting` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/settings.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_setting(self, attr: str) -> Any
+```
+
+Get a setting. If the setting contains one or more `__`, it will be
+treated as a nested setting.
+
+
+#### `set_setting` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/settings.py#L161" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_setting(self, attr: str, value: Any) -> None
+```
+
+Set a setting. If the setting contains one or more `__`, it will be
+treated as a nested setting.
+
+
+#### `normalize_log_level` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/settings.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+normalize_log_level(cls, v)
+```
diff --git a/docs/python-sdk/fastmcp-telemetry.mdx b/docs/python-sdk/fastmcp-telemetry.mdx
new file mode 100644
index 0000000..44d68cb
--- /dev/null
+++ b/docs/python-sdk/fastmcp-telemetry.mdx
@@ -0,0 +1,95 @@
+---
+title: telemetry
+sidebarTitle: telemetry
+---
+
+# `fastmcp.telemetry`
+
+
+OpenTelemetry instrumentation for FastMCP.
+
+This module provides native OpenTelemetry integration for FastMCP servers and clients.
+It uses only the opentelemetry-api package, so telemetry is a no-op unless the user
+installs an OpenTelemetry SDK and configures exporters.
+
+Example usage with SDK:
+    ```python
+    from opentelemetry import trace
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
+
+    # Configure the SDK (user responsibility)
+    provider = TracerProvider()
+    provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
+    trace.set_tracer_provider(provider)
+
+    # Now FastMCP will emit traces
+    from fastmcp import FastMCP
+    mcp = FastMCP("my-server")
+    ```
+
+
+## Functions
+
+### `get_tracer` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/telemetry.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tracer(version: str | None = None) -> Tracer
+```
+
+
+Get the FastMCP tracer for creating spans.
+
+**Args:**
+- `version`: Optional version string for the instrumentation
+
+**Returns:**
+- A tracer instance. Returns a no-op tracer if no SDK is configured.
+
+
+### `inject_trace_context` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/telemetry.py#L50" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+inject_trace_context(meta: dict[str, Any] | None = None) -> dict[str, Any] | None
+```
+
+
+Inject current trace context into a meta dict for MCP request propagation.
+
+**Args:**
+- `meta`: Optional existing meta dict to merge with trace context
+
+**Returns:**
+- A new dict containing the original meta (if any) plus trace context keys,
+- or None if no trace context to inject and meta was None
+
+
+### `record_span_error` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/telemetry.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+record_span_error(span: Span, exception: BaseException) -> None
+```
+
+
+Record an exception on a span and set error status.
+
+
+### `extract_trace_context` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/telemetry.py#L82" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+extract_trace_context(meta: dict[str, Any] | None) -> Context
+```
+
+
+Extract trace context from an MCP request meta dict.
+
+If already in a valid trace (e.g., from HTTP propagation), the existing
+trace context is preserved and meta is not used.
+
+**Args:**
+- `meta`: The meta dict from an MCP request (ctx.request_context.meta)
+
+**Returns:**
+- An OpenTelemetry Context with the extracted trace context,
+- or the current context if no trace context found or already in a trace
+
diff --git a/docs/python-sdk/fastmcp-types.mdx b/docs/python-sdk/fastmcp-types.mdx
new file mode 100644
index 0000000..1e7df0e
--- /dev/null
+++ b/docs/python-sdk/fastmcp-types.mdx
@@ -0,0 +1,27 @@
+---
+title: types
+sidebarTitle: types
+---
+
+# `fastmcp.types`
+
+
+Reusable type annotations for FastMCP tool parameters.
+
+These types can be used in tool function signatures to influence how
+parameters are presented in UIs (e.g. `fastmcp dev apps`) and
+serialized in JSON Schema.
+
+Example:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.types import Textarea
+
+mcp = FastMCP("demo")
+
+@mcp.tool()
+def run_query(sql: Textarea) -> str:
+    ...
+```
+
diff --git a/docs/python-sdk/fastmcp-utilities-__init__.mdx b/docs/python-sdk/fastmcp-utilities-__init__.mdx
new file mode 100644
index 0000000..12e12b4
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-__init__.mdx
@@ -0,0 +1,9 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.utilities`
+
+
+FastMCP utility modules.
diff --git a/docs/python-sdk/fastmcp-utilities-async_utils.mdx b/docs/python-sdk/fastmcp-utilities-async_utils.mdx
new file mode 100644
index 0000000..361400e
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-async_utils.mdx
@@ -0,0 +1,58 @@
+---
+title: async_utils
+sidebarTitle: async_utils
+---
+
+# `fastmcp.utilities.async_utils`
+
+
+Async utilities for FastMCP.
+
+## Functions
+
+### `is_coroutine_function` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/async_utils.py#L14" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+is_coroutine_function(fn: Any) -> bool
+```
+
+
+Check if a callable is a coroutine function, unwrapping functools.partial.
+
+``inspect.iscoroutinefunction`` returns ``False`` for
+``functools.partial`` objects wrapping an async function on Python < 3.12.
+This helper unwraps any layers of ``partial`` before checking.
+
+
+### `call_sync_fn_in_threadpool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/async_utils.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+call_sync_fn_in_threadpool(fn: Callable[..., Any], *args: Any, **kwargs: Any) -> Any
+```
+
+
+Call a sync function in a threadpool to avoid blocking the event loop.
+
+Uses anyio.to_thread.run_sync which properly propagates contextvars,
+making this safe for functions that depend on context (like dependency injection).
+
+
+### `gather` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/async_utils.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+gather(*awaitables: Awaitable[T]) -> list[T] | list[T | BaseException]
+```
+
+
+Run awaitables concurrently and return results in order.
+
+Uses anyio TaskGroup for structured concurrency.
+
+**Args:**
+- `*awaitables`: Awaitables to run concurrently
+- `return_exceptions`: If True, exceptions are returned in results.
+              If False, first exception cancels all and raises.
+
+**Returns:**
+- List of results in the same order as input awaitables.
+
diff --git a/docs/python-sdk/fastmcp-utilities-auth.mdx b/docs/python-sdk/fastmcp-utilities-auth.mdx
new file mode 100644
index 0000000..fbd14b9
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-auth.mdx
@@ -0,0 +1,67 @@
+---
+title: auth
+sidebarTitle: auth
+---
+
+# `fastmcp.utilities.auth`
+
+
+Authentication utility helpers.
+
+## Functions
+
+### `decode_jwt_header` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/auth.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+decode_jwt_header(token: str) -> dict[str, Any]
+```
+
+
+Decode JWT header without signature verification.
+
+Useful for extracting the key ID (kid) for JWKS lookup.
+
+**Args:**
+- `token`: JWT token string (header.payload.signature)
+
+**Returns:**
+- Decoded header as a dictionary
+
+**Raises:**
+- `ValueError`: If token is not a valid JWT format
+
+
+### `decode_jwt_payload` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/auth.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+decode_jwt_payload(token: str) -> dict[str, Any]
+```
+
+
+Decode JWT payload without signature verification.
+
+Use only for tokens received directly from trusted sources (e.g., IdP token endpoints).
+
+**Args:**
+- `token`: JWT token string (header.payload.signature)
+
+**Returns:**
+- Decoded payload as a dictionary
+
+**Raises:**
+- `ValueError`: If token is not a valid JWT format
+
+
+### `parse_scopes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/auth.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+parse_scopes(value: Any) -> list[str] | None
+```
+
+
+Parse scopes from environment variables or settings values.
+
+Accepts either a JSON array string, a comma- or space-separated string,
+a list of strings, or ``None``. Returns a list of scopes or ``None`` if
+no value is provided.
+
diff --git a/docs/python-sdk/fastmcp-utilities-authorization.mdx b/docs/python-sdk/fastmcp-utilities-authorization.mdx
new file mode 100644
index 0000000..f70c442
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-authorization.mdx
@@ -0,0 +1,70 @@
+---
+title: authorization
+sidebarTitle: authorization
+---
+
+# `fastmcp.utilities.authorization`
+
+
+Authorization checks for FastMCP components.
+
+Auth checks are callables that receive an ``AuthContext`` and return True to
+allow access or False to deny it. They can also raise ``AuthorizationError`` to
+deny with a custom message; other exceptions are masked and treated as denial.
+
+
+## Functions
+
+### `require_scopes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/authorization.py#L50" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+require_scopes(*scopes: str) -> AuthCheck
+```
+
+
+Require all of the given OAuth scopes.
+
+
+### `restrict_tag` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/authorization.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+restrict_tag(tag: str) -> AuthCheck
+```
+
+
+Require scopes when the accessed component has a specific tag.
+
+
+### `run_auth_checks` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/authorization.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run_auth_checks(checks: AuthCheck | list[AuthCheck], ctx: AuthContext) -> bool
+```
+
+
+Run auth checks with AND logic.
+
+
+## Classes
+
+### `AuthContext` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/authorization.py#L27" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Context passed to auth check callables.
+
+**Attributes:**
+- `token`: The current access token, or None if unauthenticated.
+- `component`: The tool, resource, resource template, or prompt being accessed.
+- `tool`: Backwards-compatible alias for component when it is a Tool.
+
+
+**Methods:**
+
+#### `tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/authorization.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+tool(self) -> Tool | None
+```
+
+Backwards-compatible access to the component as a Tool.
+
diff --git a/docs/python-sdk/fastmcp-utilities-cli.mdx b/docs/python-sdk/fastmcp-utilities-cli.mdx
new file mode 100644
index 0000000..6b5e732
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-cli.mdx
@@ -0,0 +1,48 @@
+---
+title: cli
+sidebarTitle: cli
+---
+
+# `fastmcp.utilities.cli`
+
+## Functions
+
+### `is_already_in_uv_subprocess` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/cli.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+is_already_in_uv_subprocess() -> bool
+```
+
+
+Check if we're already running in a FastMCP uv subprocess.
+
+
+### `load_and_merge_config` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/cli.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+load_and_merge_config(server_spec: str | None, **cli_overrides) -> tuple[MCPServerConfig, str]
+```
+
+
+Load config from server_spec and apply CLI overrides.
+
+This consolidates the config parsing logic that was duplicated across
+run, inspect, and dev commands.
+
+**Args:**
+- `server_spec`: Python file, config file, URL, or None to auto-detect
+- `cli_overrides`: CLI arguments that override config values
+
+**Returns:**
+- Tuple of (MCPServerConfig, resolved_server_spec)
+
+
+### `log_server_banner` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/cli.py#L201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+log_server_banner(server: FastMCP[Any]) -> None
+```
+
+
+Creates and logs a formatted banner with server information and logo.
+
diff --git a/docs/python-sdk/fastmcp-utilities-components.mdx b/docs/python-sdk/fastmcp-utilities-components.mdx
new file mode 100644
index 0000000..7bb360a
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-components.mdx
@@ -0,0 +1,172 @@
+---
+title: components
+sidebarTitle: components
+---
+
+# `fastmcp.utilities.components`
+
+## Functions
+
+### `get_fastmcp_metadata` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/components.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_fastmcp_metadata(meta: dict[str, Any] | None) -> FastMCPMeta
+```
+
+
+Extract FastMCP metadata from a component's meta dict.
+
+Handles both the current `fastmcp` namespace and the legacy `_fastmcp`
+namespace for compatibility with older FastMCP servers.
+
+
+## Classes
+
+### `FastMCPMeta` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/components.py#L20" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+### `FastMCPComponent` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/components.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Base class for FastMCP tools, prompts, resources, and resource templates.
+
+
+**Methods:**
+
+#### `make_key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/components.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+make_key(cls, identifier: str) -> str
+```
+
+Construct the lookup key for this component type.
+
+**Args:**
+- `identifier`: The raw identifier (name for tools/prompts, uri for resources)
+
+**Returns:**
+- A prefixed key like "tool:name" or "resource:uri"
+
+
+#### `key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/components.py#L139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+key(self) -> str
+```
+
+The globally unique lookup key for this component.
+
+Format: "{key_prefix}:{identifier}@{version}" or "{key_prefix}:{identifier}@"
+e.g. "tool:my_tool@v2", "tool:my_tool@", "resource:file://x.txt@"
+
+The @ suffix is ALWAYS present to enable unambiguous parsing of keys
+(URIs may contain @ characters, so we always include the delimiter).
+
+Subclasses should override this to use their specific identifier.
+Base implementation uses name.
+
+Prefer `.key` over ad-hoc `name or uri or uri_template` logic for any
+cross-component identity work (dedupe, grouping, collision detection,
+lookup tables). It encodes type, identifier, and version, so variants
+of the same component don't falsely collide with each other, and
+cross-type identifiers (e.g. a tool and a resource both named "foo")
+can't clash.
+
+
+#### `get_meta` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/components.py#L161" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_meta(self) -> dict[str, Any]
+```
+
+Get the meta information about the component.
+
+Returns a dict that always includes a `fastmcp` key containing:
+- `tags`: sorted list of component tags
+- `version`: component version (only if set)
+
+Internal keys (prefixed with `_`) are stripped from the fastmcp namespace.
+
+
+#### `enable` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/components.py#L209" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+enable(self) -> None
+```
+
+Removed in 3.0. Use server.enable(keys=[...]) instead.
+
+
+#### `disable` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/components.py#L216" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+disable(self) -> None
+```
+
+Removed in 3.0. Use server.disable(keys=[...]) instead.
+
+
+#### `copy` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/components.py#L223" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+copy(self) -> Self
+```
+
+Create a copy of the component.
+
+
+#### `register_with_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/components.py#L227" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+Register this component with docket for background execution.
+
+No-ops if task_config.mode is "forbidden". Subclasses override to
+register their callable (self.run, self.read, self.render, or self.fn).
+
+
+#### `coerce_task_arguments` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/components.py#L235" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+coerce_task_arguments(self, arguments: dict[str, Any]) -> dict[str, Any]
+```
+
+Validate and coerce task arguments before any task state is created.
+
+Called by ``submit_to_docket`` up front, so invalid inputs raise before
+the task's Redis metadata and initial status notification exist —
+otherwise a coercion failure during queueing would orphan a task the
+client has already observed. The base implementation is a no-op;
+components that splat arguments into a typed Python callable (e.g.
+``FunctionTool``) override this to mirror the synchronous validation
+path.
+
+
+#### `add_to_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/components.py#L248" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_to_docket(self, docket: Docket, *args: Any, **kwargs: Any) -> Execution
+```
+
+Schedule this component for background execution via docket.
+
+Subclasses override this to handle their specific calling conventions:
+- Tool: add_to_docket(docket, arguments: dict, **kwargs)
+- Resource: add_to_docket(docket, **kwargs)
+- ResourceTemplate: add_to_docket(docket, params: dict, **kwargs)
+- Prompt: add_to_docket(docket, arguments: dict | None, **kwargs)
+
+The **kwargs are passed through to docket.add() (e.g., key=task_key).
+
+
+#### `get_span_attributes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/components.py#L270" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_span_attributes(self) -> dict[str, Any]
+```
+
+Return span attributes for telemetry.
+
+Subclasses should call super() and merge their specific attributes.
+
diff --git a/docs/python-sdk/fastmcp-utilities-docstring_parsing.mdx b/docs/python-sdk/fastmcp-utilities-docstring_parsing.mdx
new file mode 100644
index 0000000..b8cacc8
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-docstring_parsing.mdx
@@ -0,0 +1,39 @@
+---
+title: docstring_parsing
+sidebarTitle: docstring_parsing
+---
+
+# `fastmcp.utilities.docstring_parsing`
+
+
+Extract descriptions from function docstrings.
+
+Uses griffelib to parse Google, NumPy, and Sphinx-style docstrings. The
+interface is intentionally narrow — a single function returning a
+`ParsedDocstring` — so the implementation can be swapped without touching
+callers.
+
+
+## Functions
+
+### `parse_docstring` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/docstring_parsing.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+parse_docstring(fn: Callable[..., Any]) -> ParsedDocstring
+```
+
+
+Parse a function's docstring into a summary and parameter descriptions.
+
+Tries Google, NumPy, and Sphinx parsers in order, using the first one that
+successfully extracts parameter descriptions. If none do, returns the full
+docstring as the description with no parameter descriptions.
+
+
+## Classes
+
+### `ParsedDocstring` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/docstring_parsing.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+The extracted description and per-parameter descriptions from a docstring.
+
diff --git a/docs/python-sdk/fastmcp-utilities-exceptions.mdx b/docs/python-sdk/fastmcp-utilities-exceptions.mdx
new file mode 100644
index 0000000..563c9a1
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-exceptions.mdx
@@ -0,0 +1,20 @@
+---
+title: exceptions
+sidebarTitle: exceptions
+---
+
+# `fastmcp.utilities.exceptions`
+
+## Functions
+
+### `iter_exc` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/exceptions.py#L12" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+iter_exc(group: BaseExceptionGroup)
+```
+
+### `get_catch_handlers` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/exceptions.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_catch_handlers() -> Mapping[type[BaseException] | Iterable[type[BaseException]], Callable[[BaseExceptionGroup[Any]], Any]]
+```
diff --git a/docs/python-sdk/fastmcp-utilities-http.mdx b/docs/python-sdk/fastmcp-utilities-http.mdx
new file mode 100644
index 0000000..6441286
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-http.mdx
@@ -0,0 +1,18 @@
+---
+title: http
+sidebarTitle: http
+---
+
+# `fastmcp.utilities.http`
+
+## Functions
+
+### `find_available_port` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/http.py#L4" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+find_available_port(host: str = '127.0.0.1') -> int
+```
+
+
+Find an available port by letting the OS assign one.
+
diff --git a/docs/python-sdk/fastmcp-utilities-inspect.mdx b/docs/python-sdk/fastmcp-utilities-inspect.mdx
new file mode 100644
index 0000000..578a936
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-inspect.mdx
@@ -0,0 +1,143 @@
+---
+title: inspect
+sidebarTitle: inspect
+---
+
+# `fastmcp.utilities.inspect`
+
+
+Utilities for inspecting FastMCP instances.
+
+## Functions
+
+### `inspect_fastmcp_v2` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/inspect.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo
+```
+
+
+Extract information from a FastMCP v2.x instance.
+
+**Args:**
+- `mcp`: The FastMCP v2.x instance to inspect
+
+**Returns:**
+- FastMCPInfo dataclass containing the extracted information
+
+
+### `inspect_fastmcp_v1` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/inspect.py#L236" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+inspect_fastmcp_v1(mcp: FastMCP1x) -> FastMCPInfo
+```
+
+
+Extract information from a FastMCP v1.x instance using a Client.
+
+**Args:**
+- `mcp`: The FastMCP v1.x instance to inspect
+
+**Returns:**
+- FastMCPInfo dataclass containing the extracted information
+
+
+### `inspect_fastmcp` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/inspect.py#L378" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+inspect_fastmcp(mcp: FastMCP[Any] | FastMCP1x) -> FastMCPInfo
+```
+
+
+Extract information from a FastMCP instance into a dataclass.
+
+This function automatically detects whether the instance is FastMCP v1.x or v2.x
+and uses the appropriate extraction method.
+
+**Args:**
+- `mcp`: The FastMCP instance to inspect (v1.x or v2.x)
+
+**Returns:**
+- FastMCPInfo dataclass containing the extracted information
+
+
+### `format_fastmcp_info` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/inspect.py#L403" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+format_fastmcp_info(info: FastMCPInfo) -> bytes
+```
+
+
+Format FastMCPInfo as FastMCP-specific JSON.
+
+This includes FastMCP-specific fields like tags, enabled, annotations, etc.
+
+
+### `format_mcp_info` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/inspect.py#L432" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+format_mcp_info(mcp: FastMCP[Any] | FastMCP1x) -> bytes
+```
+
+
+Format server info as standard MCP protocol JSON.
+
+Uses Client to get the standard MCP protocol format with camelCase fields.
+Includes version metadata at the top level.
+
+
+### `format_info` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/inspect.py#L465" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+format_info(mcp: FastMCP[Any] | FastMCP1x, format: InspectFormat | Literal['fastmcp', 'mcp'], info: FastMCPInfo | None = None) -> bytes
+```
+
+
+Format server information according to the specified format.
+
+**Args:**
+- `mcp`: The FastMCP instance
+- `format`: Output format ("fastmcp" or "mcp")
+- `info`: Pre-extracted FastMCPInfo (optional, will be extracted if not provided)
+
+**Returns:**
+- JSON bytes in the requested format
+
+
+## Classes
+
+### `ToolInfo` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/inspect.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Information about a tool.
+
+
+### `PromptInfo` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/inspect.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Information about a prompt.
+
+
+### `ResourceInfo` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/inspect.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Information about a resource.
+
+
+### `TemplateInfo` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/inspect.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Information about a resource template.
+
+
+### `FastMCPInfo` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/inspect.py#L82" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Information extracted from a FastMCP instance.
+
+
+### `InspectFormat` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/inspect.py#L396" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Output format for inspect command.
+
diff --git a/docs/python-sdk/fastmcp-utilities-json_schema.mdx b/docs/python-sdk/fastmcp-utilities-json_schema.mdx
new file mode 100644
index 0000000..43e9969
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-json_schema.mdx
@@ -0,0 +1,101 @@
+---
+title: json_schema
+sidebarTitle: json_schema
+---
+
+# `fastmcp.utilities.json_schema`
+
+## Functions
+
+### `require_discriminator_property` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/json_schema.py#L116" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+require_discriminator_property(schema: dict[str, Any]) -> dict[str, Any]
+```
+
+
+Keep an OpenAPI discriminator's tag mandatory after the keyword is dropped.
+
+Returns a copy of *schema* with ``discriminator.propertyName`` added to each
+``anyOf``/``oneOf`` variant's ``required`` list. A Pydantic discriminated
+union whose tag has a default omits that tag from ``required``; without this,
+an untagged payload passes the generated schema but fails later in the source
+model with ``union_tag_not_found``. No-op if there is no string
+``propertyName``.
+
+
+### `dereference_refs` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/json_schema.py#L147" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+dereference_refs(schema: dict[str, Any]) -> dict[str, Any]
+```
+
+
+Resolve all $ref references in a JSON schema by inlining definitions.
+
+This function resolves $ref references that point to $defs, replacing them
+with the actual definition content while preserving sibling keywords (like
+description, default, examples) that Pydantic places alongside $ref.
+
+This is necessary because some MCP clients (e.g., VS Code Copilot) don't
+properly handle $ref in tool input schemas.
+
+For self-referencing/circular schemas where full dereferencing is not possible,
+this function falls back to resolving only the root-level $ref while preserving
+$defs for nested references.
+
+Only local ``$ref`` values (those starting with ``#``) are resolved.
+Remote URIs (``http://``, ``file://``, etc.) are stripped before
+resolution to prevent SSRF / local-file-inclusion attacks when proxying
+schemas from untrusted servers.
+
+**Args:**
+- `schema`: JSON schema dict that may contain $ref references
+
+**Returns:**
+- A new schema dict with $ref resolved where possible and $defs removed
+- when no longer needed
+
+
+### `resolve_root_ref` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/json_schema.py#L294" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+resolve_root_ref(schema: dict[str, Any]) -> dict[str, Any]
+```
+
+
+Resolve $ref at root level to meet MCP spec requirements.
+
+MCP specification requires outputSchema to have "type": "object" at the root level.
+When Pydantic generates schemas for self-referential models, it uses $ref at the
+root level pointing to $defs. This function resolves such references by inlining
+the referenced definition while preserving $defs for nested references.
+
+**Args:**
+- `schema`: JSON schema dict that may have $ref at root level
+
+**Returns:**
+- A new schema dict with root-level $ref resolved, or the original schema
+- if no resolution is needed
+
+
+### `compress_schema` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/json_schema.py#L688" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+compress_schema(schema: dict[str, Any], prune_params: list[str] | None = None, prune_additional_properties: bool = False, prune_titles: bool = False, dereference: bool = False) -> dict[str, Any]
+```
+
+
+Compress and optimize a JSON schema for MCP compatibility.
+
+**Args:**
+- `schema`: The schema to compress
+- `prune_params`: List of parameter names to remove from properties
+- `prune_additional_properties`: Whether to remove additionalProperties\: false.
+Defaults to False to maintain MCP client compatibility, as some clients
+(e.g., Claude) require additionalProperties\: false for strict validation.
+- `prune_titles`: Whether to remove title fields from the schema
+- `dereference`: Whether to dereference $ref by inlining definitions.
+Defaults to False; dereferencing is typically handled by
+middleware at serve-time instead.
+
diff --git a/docs/python-sdk/fastmcp-utilities-json_schema_type.mdx b/docs/python-sdk/fastmcp-utilities-json_schema_type.mdx
new file mode 100644
index 0000000..cd46349
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-json_schema_type.mdx
@@ -0,0 +1,129 @@
+---
+title: json_schema_type
+sidebarTitle: json_schema_type
+---
+
+# `fastmcp.utilities.json_schema_type`
+
+
+Convert JSON Schema to Python types with validation.
+
+The json_schema_to_type function converts a JSON Schema into a Python type that can be used
+for validation with Pydantic. It supports:
+
+- Basic types (string, number, integer, boolean, null)
+- Complex types (arrays, objects)
+- Format constraints (date-time, email, uri)
+- Numeric constraints (minimum, maximum, multipleOf)
+- String constraints (minLength, maxLength, pattern)
+- Array constraints (minItems, maxItems, uniqueItems)
+- Object properties with defaults
+- References and recursive schemas
+- Enums and constants
+- Union types
+
+## Unsupported regex patterns
+
+Pydantic uses a Rust-based regex engine that does not support all regex
+features found in real-world JSON Schemas (particularly those from AWS,
+Azure, and other large OpenAPI providers). Unsupported constructs include
+lookahead/lookbehind assertions (`(?!...)`, `(?<=...)`), Unicode property
+escapes (`\p{Graph}`, `\p{Print}`), and very large compiled patterns.
+
+When a `pattern` constraint cannot be compiled, `json_schema_to_type`
+degrades gracefully:
+
+1. The pattern is **dropped** from the Pydantic `StringConstraints` so
+   the type will not raise a `SchemaError`.
+2. A `UserWarning` is emitted with the unsupported pattern.
+3. The original pattern is preserved in the type metadata as
+   `x-unsupported-pattern` (visible via `TypeAdapter(T).json_schema()`).
+4. Other constraints (`minLength`, `maxLength`) are still enforced.
+
+Example:
+    ```python
+    schema = {
+        "type": "object",
+        "properties": {
+            "name": {"type": "string", "minLength": 1},
+            "age": {"type": "integer", "minimum": 0},
+            "email": {"type": "string", "format": "email"}
+        },
+        "required": ["name", "age"]
+    }
+
+    # Name is optional and will be inferred from schema's "title" property if not provided
+    Person = json_schema_to_type(schema)
+    # Creates a validated dataclass with name, age, and optional email fields
+    ```
+
+
+## Functions
+
+### `json_schema_to_type` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/json_schema_type.py#L164" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+json_schema_to_type(schema: Mapping[str, Any] | bool, name: str | None = None) -> type
+```
+
+
+Convert JSON schema to appropriate Python type with validation.
+
+**Args:**
+- `schema`: A JSON Schema dictionary defining the type structure and validation rules.
+Boolean schemas are also accepted (``True`` = any type, ``False`` = unsatisfiable).
+- `name`: Optional name for object schemas. Only allowed when schema type is "object".
+If not provided for objects, name will be inferred from schema's "title"
+property or default to "Root".
+
+**Returns:**
+- A Python type (typically a dataclass for objects) with Pydantic validation
+
+**Raises:**
+- `ValueError`: If a name is provided for a non-object schema
+
+**Examples:**
+
+Create a dataclass from an object schema:
+```python
+schema = {
+    "type": "object",
+    "title": "Person",
+    "properties": {
+        "name": {"type": "string", "minLength": 1},
+        "age": {"type": "integer", "minimum": 0},
+        "email": {"type": "string", "format": "email"}
+    },
+    "required": ["name", "age"]
+}
+
+Person = json_schema_to_type(schema)
+# Creates a dataclass with name, age, and optional email fields:
+# @dataclass
+# class Person:
+#     name: str
+#     age: int
+#     email: str | None = None
+```
+Person(name="John", age=30)
+
+Create a scalar type with constraints:
+```python
+schema = {
+    "type": "string",
+    "minLength": 3,
+    "pattern": "^[A-Z][a-z]+$"
+}
+
+NameType = json_schema_to_type(schema)
+# Creates Annotated[str, StringConstraints(min_length=3, pattern="^[A-Z][a-z]+$")]
+
+@dataclass
+class Name:
+    name: NameType
+```
+
+
+## Classes
+
+### `JSONSchema` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/json_schema_type.py#L131" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
diff --git a/docs/python-sdk/fastmcp-utilities-lifespan.mdx b/docs/python-sdk/fastmcp-utilities-lifespan.mdx
new file mode 100644
index 0000000..f4dcee3
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-lifespan.mdx
@@ -0,0 +1,36 @@
+---
+title: lifespan
+sidebarTitle: lifespan
+---
+
+# `fastmcp.utilities.lifespan`
+
+
+Lifespan utilities for combining async context manager lifespans.
+
+## Functions
+
+### `combine_lifespans` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/lifespan.py#L12" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+combine_lifespans(*lifespans: Callable[[AppT], AbstractAsyncContextManager[Mapping[str, Any] | None]]) -> Callable[[AppT], AbstractAsyncContextManager[dict[str, Any]]]
+```
+
+
+Combine multiple lifespans into a single lifespan.
+
+Useful when mounting FastMCP into FastAPI and you need to run
+both your app's lifespan and the MCP server's lifespan.
+
+Works with both FastAPI-style lifespans (yield None) and FastMCP-style
+lifespans (yield dict). Results are merged; later lifespans override
+earlier ones on key conflicts.
+
+Lifespans are entered in order and exited in reverse order (LIFO).
+
+**Args:**
+- `*lifespans`: Lifespan context manager factories to combine.
+
+**Returns:**
+- A combined lifespan context manager factory.
+
diff --git a/docs/python-sdk/fastmcp-utilities-logging.mdx b/docs/python-sdk/fastmcp-utilities-logging.mdx
new file mode 100644
index 0000000..f3b58bf
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-logging.mdx
@@ -0,0 +1,58 @@
+---
+title: logging
+sidebarTitle: logging
+---
+
+# `fastmcp.utilities.logging`
+
+
+Logging utilities for FastMCP.
+
+## Functions
+
+### `get_logger` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/logging.py#L14" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_logger(name: str) -> logging.Logger
+```
+
+
+Get a logger nested under FastMCP namespace.
+
+**Args:**
+- `name`: the name of the logger, which will be prefixed with 'FastMCP.'
+
+**Returns:**
+- a configured logger instance
+
+
+### `configure_logging` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/logging.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+configure_logging(level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] | int = 'INFO', logger: logging.Logger | None = None, enable_rich_tracebacks: bool | None = None, **rich_kwargs: Any) -> None
+```
+
+
+Configure logging for FastMCP.
+
+**Args:**
+- `logger`: the logger to configure
+- `level`: the log level to use
+- `rich_kwargs`: the parameters to use for creating RichHandler
+
+
+### `temporary_log_level` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/logging.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+temporary_log_level(level: str | None, logger: logging.Logger | None = None, enable_rich_tracebacks: bool | None = None, **rich_kwargs: Any)
+```
+
+
+Context manager to temporarily set log level and restore it afterwards.
+
+**Args:**
+- `level`: The temporary log level to set (e.g., "DEBUG", "INFO")
+- `logger`: Optional logger to configure (defaults to FastMCP logger)
+- `enable_rich_tracebacks`: Whether to enable rich tracebacks
+- `**rich_kwargs`: Additional parameters for RichHandler
+
diff --git a/docs/python-sdk/fastmcp-utilities-mcp_server_config-__init__.mdx b/docs/python-sdk/fastmcp-utilities-mcp_server_config-__init__.mdx
new file mode 100644
index 0000000..bc8fc95
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-mcp_server_config-__init__.mdx
@@ -0,0 +1,13 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.utilities.mcp_server_config`
+
+
+FastMCP Configuration module.
+
+This module provides versioned configuration support for FastMCP servers.
+The current version is v1, which is re-exported here for convenience.
+
diff --git a/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-__init__.mdx b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-__init__.mdx
new file mode 100644
index 0000000..01f1474
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-__init__.mdx
@@ -0,0 +1,9 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.utilities.mcp_server_config.v1.environments`
+
+
+Environment configuration for MCP servers.
diff --git a/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-base.mdx b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-base.mdx
new file mode 100644
index 0000000..f8e764a
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-base.mdx
@@ -0,0 +1,43 @@
+---
+title: base
+sidebarTitle: base
+---
+
+# `fastmcp.utilities.mcp_server_config.v1.environments.base`
+
+## Classes
+
+### `Environment` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/base.py#L7" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Base class for environment configuration.
+
+
+**Methods:**
+
+#### `build_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/base.py#L13" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+build_command(self, command: list[str]) -> list[str]
+```
+
+Build the full command with environment setup.
+
+**Args:**
+- `command`: Base command to wrap with environment setup
+
+**Returns:**
+- Full command ready for subprocess execution
+
+
+#### `prepare` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/base.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+prepare(self, output_dir: Path | None = None) -> None
+```
+
+Prepare the environment (optional, can be no-op).
+
+**Args:**
+- `output_dir`: Directory for persistent environment setup
+
diff --git a/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-uv.mdx b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-uv.mdx
new file mode 100644
index 0000000..8e9e5b2
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-uv.mdx
@@ -0,0 +1,45 @@
+---
+title: uv
+sidebarTitle: uv
+---
+
+# `fastmcp.utilities.mcp_server_config.v1.environments.uv`
+
+## Classes
+
+### `UVEnvironment` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/uv.py#L14" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Configuration for Python environment setup.
+
+
+**Methods:**
+
+#### `build_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/uv.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+build_command(self, command: list[str]) -> list[str]
+```
+
+Build complete uv run command with environment args and command to execute.
+
+**Args:**
+- `command`: Command to execute (e.g., ["fastmcp", "run", "server.py"])
+
+**Returns:**
+- Complete command ready for subprocess.run, including "uv" prefix if needed.
+- If no environment configuration is set, returns the command unchanged.
+
+
+#### `prepare` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/uv.py#L109" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+prepare(self, output_dir: Path | None = None) -> None
+```
+
+Prepare the Python environment using uv.
+
+**Args:**
+- `output_dir`: Directory where the persistent uv project will be created.
+       If None, creates a temporary directory for ephemeral use.
+
diff --git a/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-mcp_server_config.mdx b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-mcp_server_config.mdx
new file mode 100644
index 0000000..dc0dd12
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-mcp_server_config.mdx
@@ -0,0 +1,235 @@
+---
+title: mcp_server_config
+sidebarTitle: mcp_server_config
+---
+
+# `fastmcp.utilities.mcp_server_config.v1.mcp_server_config`
+
+
+FastMCP Configuration File Support.
+
+This module provides support for fastmcp.json configuration files that allow
+users to specify server settings in a declarative format instead of using
+command-line arguments.
+
+
+## Functions
+
+### `generate_schema` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L416" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+generate_schema(output_path: Path | str | None = None) -> dict[str, Any] | None
+```
+
+
+Generate JSON schema for fastmcp.json files.
+
+This is used to create the schema file that IDEs can use for
+validation and auto-completion.
+
+**Args:**
+- `output_path`: Optional path to write the schema to. If provided,
+        writes the schema and returns None. If not provided,
+        returns the schema as a dictionary.
+
+**Returns:**
+- JSON schema as a dictionary if output_path is None, otherwise None
+
+
+## Classes
+
+### `Deployment` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Configuration for server deployment and runtime settings.
+
+
+**Methods:**
+
+#### `apply_runtime_settings` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+apply_runtime_settings(self, config_path: Path | None = None) -> None
+```
+
+Apply runtime settings like environment variables and working directory.
+
+**Args:**
+- `config_path`: Path to config file for resolving relative paths
+
+Environment variables support interpolation with ${VAR_NAME} syntax.
+For example: "API_URL": "https://api.${ENVIRONMENT}.example.com"
+will substitute the value of the ENVIRONMENT variable at runtime.
+
+
+### `MCPServerConfig` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L134" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Configuration for a FastMCP server.
+
+This configuration file allows you to specify all settings needed to run
+a FastMCP server in a declarative format.
+
+
+**Methods:**
+
+#### `validate_source` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+validate_source(cls, v: dict | Source) -> SourceType
+```
+
+Validate and convert source to proper format.
+
+Supports:
+- Dict format: `{"path": "server.py", "entrypoint": "app"}`
+- FileSystemSource instance (passed through)
+
+No string parsing happens here - that's only at CLI boundaries.
+MCPServerConfig works only with properly typed objects.
+
+
+#### `validate_environment` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L199" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+validate_environment(cls, v: dict | Any) -> EnvironmentType
+```
+
+Ensure environment has a type field for discrimination.
+
+For backward compatibility, if no type is specified, default to "uv".
+
+
+#### `validate_deployment` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L210" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+validate_deployment(cls, v: dict | Deployment) -> Deployment
+```
+
+Validate and convert deployment to Deployment.
+
+Accepts:
+- Deployment instance
+- dict that can be converted to Deployment
+
+
+#### `from_file` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L223" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_file(cls, file_path: Path) -> MCPServerConfig
+```
+
+Load configuration from a JSON file.
+
+**Args:**
+- `file_path`: Path to the configuration file
+
+**Returns:**
+- MCPServerConfig instance
+
+**Raises:**
+- `FileNotFoundError`: If the file doesn't exist
+- `json.JSONDecodeError`: If the file is not valid JSON
+- `pydantic.ValidationError`: If the configuration is invalid
+
+
+#### `from_cli_args` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L246" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_cli_args(cls, source: FileSystemSource, transport: Literal['stdio', 'http', 'sse', 'streamable-http'] | None = None, host: str | None = None, port: int | None = None, path: str | None = None, log_level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] | None = None, python: str | None = None, dependencies: list[str] | None = None, requirements: str | None = None, project: str | None = None, editable: str | None = None, env: dict[str, str] | None = None, cwd: str | None = None, args: list[str] | None = None) -> MCPServerConfig
+```
+
+Create a config from CLI arguments.
+
+This allows us to have a single code path where everything
+goes through a config object.
+
+**Args:**
+- `source`: Server source (FileSystemSource instance)
+- `transport`: Transport protocol
+- `host`: Host for HTTP transport
+- `port`: Port for HTTP transport
+- `path`: URL path for server
+- `log_level`: Logging level
+- `python`: Python version
+- `dependencies`: Python packages to install
+- `requirements`: Path to requirements file
+- `project`: Path to project directory
+- `editable`: Path to install in editable mode
+- `env`: Environment variables
+- `cwd`: Working directory
+- `args`: Server arguments
+
+**Returns:**
+- MCPServerConfig instance
+
+
+#### `find_config` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+find_config(cls, start_path: Path | None = None) -> Path | None
+```
+
+Find a fastmcp.json file in the specified directory.
+
+**Args:**
+- `start_path`: Directory to look in (defaults to current directory)
+
+**Returns:**
+- Path to the configuration file, or None if not found
+
+
+#### `prepare` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L342" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+prepare(self, skip_source: bool = False, output_dir: Path | None = None) -> None
+```
+
+Prepare environment and source for execution.
+
+When output_dir is provided, creates a persistent uv project.
+When output_dir is None, does ephemeral caching (for backwards compatibility).
+
+**Args:**
+- `skip_source`: Skip source preparation if True
+- `output_dir`: Directory to create the persistent uv project in (optional)
+
+
+#### `prepare_environment` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L363" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+prepare_environment(self, output_dir: Path | None = None) -> None
+```
+
+Prepare the Python environment.
+
+**Args:**
+- `output_dir`: If provided, creates a persistent uv project in this directory.
+       If None, just populates uv's cache for ephemeral use.
+
+Delegates to the environment's prepare() method
+
+
+#### `prepare_source` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+prepare_source(self) -> None
+```
+
+Prepare the source for loading.
+
+Delegates to the source's prepare() method.
+
+
+#### `run_server` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L381" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run_server(self, **kwargs: Any) -> None
+```
+
+Load and run the server with this configuration.
+
+**Args:**
+- `**kwargs`: Additional arguments to pass to server.run_async()
+     These override config settings
+
diff --git a/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-base.mdx b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-base.mdx
new file mode 100644
index 0000000..4c57930
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-base.mdx
@@ -0,0 +1,42 @@
+---
+title: base
+sidebarTitle: base
+---
+
+# `fastmcp.utilities.mcp_server_config.v1.sources.base`
+
+## Classes
+
+### `Source` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/sources/base.py#L7" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Abstract base class for all source types.
+
+
+**Methods:**
+
+#### `prepare` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/sources/base.py#L12" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+prepare(self) -> None
+```
+
+Prepare the source (download, clone, install, etc).
+
+For sources that need preparation (e.g., git clone, download),
+this method performs that preparation. For sources that don't
+need preparation (e.g., local files), this is a no-op.
+
+
+#### `load_server` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/sources/base.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+load_server(self) -> Any
+```
+
+Load and return the FastMCP server instance.
+
+Must be called after prepare() if the source requires preparation.
+All information needed to load the server should be available
+as attributes on the source instance.
+
diff --git a/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-filesystem.mdx b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-filesystem.mdx
new file mode 100644
index 0000000..2abce7f
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-filesystem.mdx
@@ -0,0 +1,37 @@
+---
+title: filesystem
+sidebarTitle: filesystem
+---
+
+# `fastmcp.utilities.mcp_server_config.v1.sources.filesystem`
+
+## Classes
+
+### `FileSystemSource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/sources/filesystem.py#L16" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Source for local Python files.
+
+
+**Methods:**
+
+#### `parse_path_with_object` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/sources/filesystem.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+parse_path_with_object(cls, v: str) -> str
+```
+
+Parse path:object syntax and extract the object name.
+
+This validator runs before the model is created, allowing us to
+handle the "file.py:object" syntax at the model boundary.
+
+
+#### `load_server` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/sources/filesystem.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+load_server(self) -> Any
+```
+
+Load server from filesystem.
+
diff --git a/docs/python-sdk/fastmcp-utilities-mime.mdx b/docs/python-sdk/fastmcp-utilities-mime.mdx
new file mode 100644
index 0000000..99455c7
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-mime.mdx
@@ -0,0 +1,35 @@
+---
+title: mime
+sidebarTitle: mime
+---
+
+# `fastmcp.utilities.mime`
+
+
+MIME type constants and helpers for MCP Apps UI resources.
+
+This module has no dependencies on the server or resource packages,
+so it can be safely imported from anywhere.
+
+
+## Functions
+
+### `resolve_ui_mime_type` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/mime.py#L10" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+resolve_ui_mime_type(uri: str, explicit_mime_type: str | None) -> str | None
+```
+
+
+Return the appropriate MIME type for a resource URI.
+
+For ``ui://`` scheme resources, defaults to ``UI_MIME_TYPE`` when no
+explicit MIME type is provided.
+
+**Args:**
+- `uri`: The resource URI string
+- `explicit_mime_type`: The MIME type explicitly provided by the user
+
+**Returns:**
+- The resolved MIME type (explicit value, UI default, or None)
+
diff --git a/docs/python-sdk/fastmcp-utilities-openapi.mdx b/docs/python-sdk/fastmcp-utilities-openapi.mdx
new file mode 100644
index 0000000..cb8bcf9
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-openapi.mdx
@@ -0,0 +1,9 @@
+---
+title: openapi
+sidebarTitle: openapi
+---
+
+# `fastmcp.utilities.openapi`
+
+
+OpenAPI utilities for FastMCP - refactored for better maintainability.
diff --git a/docs/python-sdk/fastmcp-utilities-pagination.mdx b/docs/python-sdk/fastmcp-utilities-pagination.mdx
new file mode 100644
index 0000000..7008f23
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-pagination.mdx
@@ -0,0 +1,66 @@
+---
+title: pagination
+sidebarTitle: pagination
+---
+
+# `fastmcp.utilities.pagination`
+
+
+Pagination utilities for MCP list operations.
+
+## Functions
+
+### `paginate_sequence` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/pagination.py#L50" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+paginate_sequence(items: Sequence[T], cursor: str | None, page_size: int) -> tuple[list[T], str | None]
+```
+
+
+Paginate a sequence of items.
+
+**Args:**
+- `items`: The full sequence to paginate.
+- `cursor`: Optional cursor from a previous request. None for first page.
+- `page_size`: Maximum number of items per page.
+
+**Returns:**
+- Tuple of (page_items, next_cursor). next_cursor is None if no more pages.
+
+**Raises:**
+- `ValueError`: If the cursor is invalid.
+
+
+## Classes
+
+### `CursorState` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/pagination.py#L16" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Internal representation of pagination cursor state.
+
+The cursor encodes the offset into the result set. This is opaque to clients
+per the MCP spec - they should not parse or modify cursors.
+
+
+**Methods:**
+
+#### `encode` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/pagination.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+encode(self) -> str
+```
+
+Encode cursor state to an opaque string.
+
+
+#### `decode` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/pagination.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+decode(cls, cursor: str) -> CursorState
+```
+
+Decode cursor from an opaque string.
+
+**Raises:**
+- `ValueError`: If the cursor is invalid or malformed.
+
diff --git a/docs/python-sdk/fastmcp-utilities-skills.mdx b/docs/python-sdk/fastmcp-utilities-skills.mdx
new file mode 100644
index 0000000..cdbbbad
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-skills.mdx
@@ -0,0 +1,114 @@
+---
+title: skills
+sidebarTitle: skills
+---
+
+# `fastmcp.utilities.skills`
+
+
+Client utilities for discovering and downloading skills from MCP servers.
+
+## Functions
+
+### `list_skills` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/skills.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_skills(client: Client) -> list[SkillSummary]
+```
+
+
+List all available skills from an MCP server.
+
+Discovers skills by finding resources with URIs matching the
+`skill://{name}/SKILL.md` pattern.
+
+**Args:**
+- `client`: Connected FastMCP client
+
+**Returns:**
+- List of SkillSummary objects with name, description, and URI
+
+
+### `get_skill_manifest` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/skills.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_skill_manifest(client: Client, skill_name: str) -> SkillManifest
+```
+
+
+Get the manifest for a specific skill.
+
+**Args:**
+- `client`: Connected FastMCP client
+- `skill_name`: Name of the skill
+
+**Returns:**
+- SkillManifest with file listing
+
+**Raises:**
+- `ValueError`: If manifest cannot be read or parsed
+
+
+### `download_skill` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/skills.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+download_skill(client: Client, skill_name: str, target_dir: str | Path) -> Path
+```
+
+
+Download a skill and all its files to a local directory.
+
+Creates a subdirectory named after the skill containing all files.
+
+**Args:**
+- `client`: Connected FastMCP client
+- `skill_name`: Name of the skill to download
+- `target_dir`: Directory where skill folder will be created
+- `overwrite`: If True, overwrite existing skill directory. If False
+(default), raise FileExistsError if directory exists.
+
+**Returns:**
+- Path to the downloaded skill directory
+
+**Raises:**
+- `ValueError`: If skill cannot be found or downloaded
+- `FileExistsError`: If skill directory exists and overwrite=False
+
+
+### `sync_skills` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/skills.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+sync_skills(client: Client, target_dir: str | Path) -> list[Path]
+```
+
+
+Download all available skills from a server.
+
+**Args:**
+- `client`: Connected FastMCP client
+- `target_dir`: Directory where skill folders will be created
+- `overwrite`: If True, overwrite existing files
+
+**Returns:**
+- List of paths to downloaded skill directories
+
+
+## Classes
+
+### `SkillSummary` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/skills.py#L18" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Summary information about a skill available on a server.
+
+
+### `SkillFile` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/skills.py#L27" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Information about a file within a skill.
+
+
+### `SkillManifest` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/skills.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Full manifest of a skill including all files.
+
diff --git a/docs/python-sdk/fastmcp-utilities-tasks.mdx b/docs/python-sdk/fastmcp-utilities-tasks.mdx
new file mode 100644
index 0000000..ed45562
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-tasks.mdx
@@ -0,0 +1,62 @@
+---
+title: tasks
+sidebarTitle: tasks
+---
+
+# `fastmcp.utilities.tasks`
+
+
+Task configuration primitives for FastMCP components.
+
+## Classes
+
+### `TaskMeta` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tasks.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Metadata for task-augmented execution requests.
+
+**Attributes:**
+- `ttl`: Client-requested TTL in milliseconds. If None, uses server default.
+- `fn_key`: Docket routing key. Auto-derived from component name if None.
+
+
+### `TaskConfig` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tasks.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Configuration for MCP background task execution.
+
+Controls how a component handles task-augmented requests:
+
+- ``forbidden``: Component does not support task execution.
+- ``optional``: Component supports both synchronous and task execution.
+- ``required``: Component requires task execution.
+
+
+**Methods:**
+
+#### `from_bool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tasks.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_bool(cls, value: bool) -> TaskConfig
+```
+
+Convert a boolean task flag to a TaskConfig.
+
+
+#### `supports_tasks` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tasks.py#L53" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+supports_tasks(self) -> bool
+```
+
+Check if this component supports task execution.
+
+
+#### `validate_function` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tasks.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+validate_function(self, fn: Callable[..., Any], name: str) -> None
+```
+
+Validate that a function is compatible with this task config.
+
diff --git a/docs/python-sdk/fastmcp-utilities-tests.mdx b/docs/python-sdk/fastmcp-utilities-tests.mdx
new file mode 100644
index 0000000..ca779b9
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-tests.mdx
@@ -0,0 +1,96 @@
+---
+title: tests
+sidebarTitle: tests
+---
+
+# `fastmcp.utilities.tests`
+
+## Functions
+
+### `temporary_settings` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tests.py#L24" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+temporary_settings(**kwargs: Any)
+```
+
+
+Temporarily override FastMCP setting values.
+
+**Args:**
+- `**kwargs`: The settings to override, including nested settings.
+
+
+### `run_server_in_process` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tests.py#L75" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run_server_in_process(server_fn: Callable[..., None], *args: Any, **kwargs: Any) -> Generator[str, None, None]
+```
+
+
+Context manager that runs a FastMCP server in a separate process and
+returns the server URL. When the context manager is exited, the server process is killed.
+
+**Args:**
+- `server_fn`: The function that runs a FastMCP server. FastMCP servers are
+not pickleable, so we need a function that creates and runs one.
+- `*args`: Arguments to pass to the server function.
+- `provide_host_and_port`: Whether to provide the host and port to the server function as kwargs.
+- `host`: Host to bind the server to (default\: "127.0.0.1").
+- `port`: Port to bind the server to (default\: find available port).
+- `**kwargs`: Keyword arguments to pass to the server function.
+
+**Returns:**
+- The server URL.
+
+
+### `run_server_async` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tests.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run_server_async(server: FastMCP, port: int | None = None, transport: Literal['http', 'streamable-http', 'sse'] = 'http', path: str = '/mcp', host: str = '127.0.0.1') -> AsyncGenerator[str, None]
+```
+
+
+Start a FastMCP server as an asyncio task for in-process async testing.
+
+This is the recommended way to test FastMCP servers. It runs the server
+as an async task in the same process, eliminating subprocess coordination,
+sleeps, and cleanup issues.
+
+**Args:**
+- `server`: FastMCP server instance
+- `port`: Port to bind to (default\: find available port)
+- `transport`: Transport type ("http", "streamable-http", or "sse")
+- `path`: URL path for the server (default\: "/mcp")
+- `host`: Host to bind to (default\: "127.0.0.1")
+
+
+## Classes
+
+### `HeadlessOAuth` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tests.py#L225" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+OAuth provider that bypasses browser interaction for testing.
+
+This simulates the complete OAuth flow programmatically by making HTTP requests
+instead of opening a browser and running a callback server. Useful for automated testing.
+
+
+**Methods:**
+
+#### `redirect_handler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tests.py#L238" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+redirect_handler(self, authorization_url: str) -> None
+```
+
+Make HTTP request to authorization URL and store response for callback handler.
+
+
+#### `callback_handler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tests.py#L244" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+callback_handler(self) -> tuple[str, str | None]
+```
+
+Parse stored response and return (auth_code, state).
+
diff --git a/docs/python-sdk/fastmcp-utilities-timeout.mdx b/docs/python-sdk/fastmcp-utilities-timeout.mdx
new file mode 100644
index 0000000..c9c890e
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-timeout.mdx
@@ -0,0 +1,44 @@
+---
+title: timeout
+sidebarTitle: timeout
+---
+
+# `fastmcp.utilities.timeout`
+
+
+Timeout normalization utilities.
+
+## Functions
+
+### `normalize_timeout_to_timedelta` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/timeout.py#L8" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+normalize_timeout_to_timedelta(value: int | float | datetime.timedelta | None) -> datetime.timedelta | None
+```
+
+
+Normalize a timeout value to a timedelta.
+
+**Args:**
+- `value`: Timeout value as int/float (seconds), timedelta, or None
+
+**Returns:**
+- timedelta if value provided, None otherwise
+
+
+### `normalize_timeout_to_seconds` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/timeout.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+normalize_timeout_to_seconds(value: int | float | datetime.timedelta | None) -> float | None
+```
+
+
+Normalize a timeout value to seconds (float).
+
+**Args:**
+- `value`: Timeout value as int/float (seconds), timedelta, or None.
+Zero values are treated as "disabled" and return None.
+
+**Returns:**
+- float seconds if value provided and non-zero, None otherwise
+
diff --git a/docs/python-sdk/fastmcp-utilities-token_cache.mdx b/docs/python-sdk/fastmcp-utilities-token_cache.mdx
new file mode 100644
index 0000000..a831d20
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-token_cache.mdx
@@ -0,0 +1,87 @@
+---
+title: token_cache
+sidebarTitle: token_cache
+---
+
+# `fastmcp.utilities.token_cache`
+
+
+In-memory cache for token verification results.
+
+Provides a generic TTL-based cache for ``AccessToken`` objects, designed to
+reduce repeated network calls during opaque-token verification.  Only
+*successful* verifications should be cached; errors and failures must be
+retried on every request.
+
+Example:
+    ```python
+    from fastmcp.utilities.token_cache import TokenCache
+
+    cache = TokenCache(ttl_seconds=300, max_size=10000)
+
+    # On cache miss, call the upstream verifier and store the result.
+    hit, token = cache.get(raw_token)
+    if not hit:
+        token = await _call_upstream(raw_token)
+        if token is not None:
+            cache.set(raw_token, token)
+    ```
+
+
+## Classes
+
+### `TokenCache` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/token_cache.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+TTL-based in-memory cache for ``AccessToken`` objects.
+
+Features:
+- SHA-256 hashed cache keys (fixed size, regardless of token length).
+- Per-entry TTL that respects both the configured ``ttl_seconds`` and the
+  token's own ``expires_at`` claim (whichever is sooner).
+- Bounded size with FIFO eviction when the cache is full.
+- Periodic cleanup of expired entries to prevent unbounded growth.
+- Defensive deep copies on both store and retrieve to prevent
+  callers from mutating cached values.
+
+Caching is disabled when ``ttl_seconds`` is ``None`` or ``0``, or
+when ``max_size`` is ``0``.  Negative values raise ``ValueError``.
+
+
+**Methods:**
+
+#### `enabled` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/token_cache.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+enabled(self) -> bool
+```
+
+Return whether caching is active.
+
+
+#### `get` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/token_cache.py#L95" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get(self, token: str) -> tuple[bool, AccessToken | None]
+```
+
+Look up a cached verification result.
+
+**Returns:**
+- ``(True, AccessToken)`` on a cache hit, ``(False, None)`` on a miss
+- or when caching is disabled.  The returned ``AccessToken`` is a deep
+- copy that is safe to mutate.
+
+
+#### `set` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/token_cache.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set(self, token: str, result: AccessToken) -> None
+```
+
+Store a *successful* verification result.
+
+Only successful verifications should be cached.  Failures (inactive
+tokens, missing scopes, HTTP errors, timeouts) must **not** be cached
+so that transient problems do not produce sticky false negatives.
+
diff --git a/docs/python-sdk/fastmcp-utilities-types.mdx b/docs/python-sdk/fastmcp-utilities-types.mdx
new file mode 100644
index 0000000..7f1b030
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-types.mdx
@@ -0,0 +1,168 @@
+---
+title: types
+sidebarTitle: types
+---
+
+# `fastmcp.utilities.types`
+
+
+Common types used across FastMCP.
+
+## Functions
+
+### `get_fn_name` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/types.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_fn_name(fn: Callable[..., Any]) -> str
+```
+
+### `get_cached_typeadapter` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/types.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_cached_typeadapter(cls: T) -> TypeAdapter[T]
+```
+
+
+TypeAdapters are heavy objects, and in an application context we'd typically
+create them once in a global scope and reuse them as often as possible.
+However, this isn't feasible for user-generated functions. Instead, we use a
+cache to minimize the cost of creating them as much as possible.
+
+
+### `issubclass_safe` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/types.py#L123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+issubclass_safe(cls: type, base: type) -> bool
+```
+
+
+Check if cls is a subclass of base, even if cls is a type variable.
+
+
+### `is_class_member_of_type` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/types.py#L133" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+is_class_member_of_type(cls: Any, base: type) -> bool
+```
+
+
+Check if cls is a member of base, even if cls is a type variable.
+
+Base can be a type, a UnionType, or an Annotated type. Generic types are not
+considered members (e.g. T is not a member of list\[T]).
+
+
+### `find_kwarg_by_type` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/types.py#L155" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+find_kwarg_by_type(fn: Callable, kwarg_type: type) -> str | None
+```
+
+
+Find the name of the kwarg that is of type kwarg_type.
+
+Includes union types that contain the kwarg_type, as well as Annotated types.
+
+
+### `create_function_without_params` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/types.py#L181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_function_without_params(fn: Callable[..., Any], exclude_params: list[str]) -> Callable[..., Any]
+```
+
+
+Create a new function with the same code but without the specified parameters in annotations.
+
+This is used to exclude parameters from type adapter processing when they can't be serialized.
+The excluded parameters are removed from the function's __annotations__ dictionary.
+
+
+### `replace_type` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/types.py#L454" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+replace_type(type_, type_map: dict[type, type])
+```
+
+
+Given a (possibly generic, nested, or otherwise complex) type, replaces all
+instances of keys in type_map with their corresponding values.
+
+This is useful for transforming types when creating tools.
+
+**Args:**
+- `type_`: The type to transform.
+- `type_map`: A mapping of types to replace (keys are replaced by values).
+
+Examples:
+```python
+>>> replace_type(list[int | bool], {int: str})
+list[str | bool]
+
+>>> replace_type(list[list[int]], {int: str})
+list[list[str]]
+```
+
+
+## Classes
+
+### `FastMCPBaseModel` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/types.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Base model for FastMCP models.
+
+
+### `Image` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/types.py#L238" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Helper class for returning images from tools.
+
+
+**Methods:**
+
+#### `to_image_content` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/types.py#L289" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+to_image_content(self, mime_type: str | None = None, annotations: Annotations | None = None) -> mcp.types.ImageContent
+```
+
+Convert to MCP ImageContent.
+
+
+#### `to_data_uri` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/types.py#L304" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+to_data_uri(self, mime_type: str | None = None) -> str
+```
+
+Get image as a data URI.
+
+
+### `Audio` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/types.py#L310" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Helper class for returning audio from tools.
+
+
+**Methods:**
+
+#### `to_audio_content` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/types.py#L347" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+to_audio_content(self, mime_type: str | None = None, annotations: Annotations | None = None) -> mcp.types.AudioContent
+```
+
+### `File` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/types.py#L368" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Helper class for returning file data from tools.
+
+
+**Methods:**
+
+#### `to_resource_content` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/types.py#L407" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+to_resource_content(self, mime_type: str | None = None, annotations: Annotations | None = None) -> mcp.types.EmbeddedResource
+```
+
+### `ContextSamplingFallbackProtocol` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/types.py#L490" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
diff --git a/docs/python-sdk/fastmcp-utilities-ui.mdx b/docs/python-sdk/fastmcp-utilities-ui.mdx
new file mode 100644
index 0000000..7687df7
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-ui.mdx
@@ -0,0 +1,140 @@
+---
+title: ui
+sidebarTitle: ui
+---
+
+# `fastmcp.utilities.ui`
+
+
+
+Shared UI utilities for FastMCP HTML pages.
+
+This module provides reusable HTML/CSS components for OAuth callbacks,
+consent pages, and other user-facing interfaces.
+
+
+## Functions
+
+### `create_page` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/ui.py#L453" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_page(content: str, title: str = 'FastMCP', additional_styles: str = '', csp_policy: str = "default-src 'none'; style-src 'unsafe-inline'; img-src https: data:; base-uri 'none'") -> str
+```
+
+
+Create a complete HTML page with FastMCP styling.
+
+**Args:**
+- `content`: HTML content to place inside the page
+- `title`: Page title
+- `additional_styles`: Extra CSS to include
+- `csp_policy`: Content Security Policy header value.
+If empty string "", the CSP meta tag is omitted entirely.
+
+**Returns:**
+- Complete HTML page as string
+
+
+### `create_logo` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/ui.py#L501" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_logo(icon_url: str | None = None, alt_text: str = 'FastMCP') -> str
+```
+
+
+Create logo HTML.
+
+**Args:**
+- `icon_url`: Optional custom icon URL. If not provided, uses the FastMCP logo.
+- `alt_text`: Alt text for the logo image.
+
+**Returns:**
+- HTML for logo image tag.
+
+
+### `create_status_message` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/ui.py#L516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_status_message(message: str, is_success: bool = True) -> str
+```
+
+
+Create a status message with icon.
+
+**Args:**
+- `message`: Status message text
+- `is_success`: True for success (✓), False for error (✕)
+
+**Returns:**
+- HTML for status message
+
+
+### `create_info_box` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/ui.py#L539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_info_box(content: str, is_error: bool = False, centered: bool = False, monospace: bool = False) -> str
+```
+
+
+Create an info box.
+
+**Args:**
+- `content`: HTML content for the info box
+- `is_error`: True for error styling, False for normal
+- `centered`: True to center the text, False for left-aligned
+- `monospace`: True to use gray monospace font styling instead of blue
+
+**Returns:**
+- HTML for info box
+
+
+### `create_detail_box` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/ui.py#L568" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_detail_box(rows: list[tuple[str, str]]) -> str
+```
+
+
+Create a detail box with key-value pairs.
+
+**Args:**
+- `rows`: List of (label, value) tuples
+
+**Returns:**
+- HTML for detail box
+
+
+### `create_button_group` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/ui.py#L591" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_button_group(buttons: list[tuple[str, str, str]]) -> str
+```
+
+
+Create a group of buttons.
+
+**Args:**
+- `buttons`: List of (text, value, css_class) tuples
+
+**Returns:**
+- HTML for button group
+
+
+### `create_secure_html_response` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/ui.py#L609" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_secure_html_response(html: str, status_code: int = 200) -> HTMLResponse
+```
+
+
+Create an HTMLResponse with security headers.
+
+Adds X-Frame-Options: DENY to prevent clickjacking attacks per MCP security best practices.
+
+**Args:**
+- `html`: HTML content to return
+- `status_code`: HTTP status code
+
+**Returns:**
+- HTMLResponse with security headers
+
diff --git a/docs/python-sdk/fastmcp-utilities-version_check.mdx b/docs/python-sdk/fastmcp-utilities-version_check.mdx
new file mode 100644
index 0000000..6a4377a
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-version_check.mdx
@@ -0,0 +1,40 @@
+---
+title: version_check
+sidebarTitle: version_check
+---
+
+# `fastmcp.utilities.version_check`
+
+
+Version checking utilities for FastMCP.
+
+## Functions
+
+### `get_latest_version` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/version_check.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_latest_version(include_prereleases: bool = False) -> str | None
+```
+
+
+Get the latest version of FastMCP from PyPI, using cache when available.
+
+**Args:**
+- `include_prereleases`: If True, include pre-release versions.
+
+**Returns:**
+- The latest version string, or None if unavailable.
+
+
+### `check_for_newer_version` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/version_check.py#L124" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+check_for_newer_version() -> str | None
+```
+
+
+Check if a newer version of FastMCP is available.
+
+**Returns:**
+- The latest version string if newer than current, None otherwise.
+
diff --git a/docs/python-sdk/fastmcp-utilities-versions.mdx b/docs/python-sdk/fastmcp-utilities-versions.mdx
new file mode 100644
index 0000000..1eaa639
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-versions.mdx
@@ -0,0 +1,229 @@
+---
+title: versions
+sidebarTitle: versions
+---
+
+# `fastmcp.utilities.versions`
+
+
+Version comparison utilities for component versioning.
+
+This module provides utilities for comparing component versions. Versions are
+strings that are first attempted to be parsed as PEP 440 versions (using the
+`packaging` library), falling back to lexicographic string comparison.
+
+Examples:
+    - "1", "2", "10" → parsed as PEP 440, compared semantically (1 < 2 < 10)
+    - "1.0", "2.0" → parsed as PEP 440
+    - "v1.0" → 'v' prefix stripped, parsed as "1.0"
+    - "2025-01-15" → not valid PEP 440, compared as strings
+    - None → sorts lowest (unversioned components)
+
+
+## Functions
+
+### `parse_version_key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L197" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+parse_version_key(version: str | None) -> VersionKey
+```
+
+
+Parse a version string into a sortable key.
+
+**Args:**
+- `version`: The version string, or None for unversioned.
+
+**Returns:**
+- A VersionKey suitable for sorting.
+
+
+### `version_sort_key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L209" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+version_sort_key(component: FastMCPComponent) -> tuple[VersionKey, str]
+```
+
+
+Get a sort key for a component based on its version.
+
+Use with sorted() or max() to order components by version.
+
+The key is a `(VersionKey, raw)` tuple. The `VersionKey` orders by PEP 440
+semantics (or lexicographically for non-PEP 440 strings); the raw version
+string is a deterministic tie-breaker so that two components whose versions
+are PEP 440-equivalent but spelled differently (e.g. `"1"` and `"1.0"`) are
+ordered reproducibly instead of by registration order. The raw tie-breaker
+only affects equivalent-version ties and never the primary version order,
+so range/equality matching (which uses `VersionKey` directly) is unchanged.
+
+**Args:**
+- `component`: The component to get a sort key for.
+
+**Returns:**
+- A deterministic, sortable `(VersionKey, raw)` tuple.
+
+
+### `compare_versions` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L237" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+compare_versions(a: str | None, b: str | None) -> int
+```
+
+
+Compare two version strings.
+
+**Args:**
+- `a`: First version string (or None).
+- `b`: Second version string (or None).
+
+**Returns:**
+- -1 if a &lt; b, 0 if a == b, 1 if a &gt; b.
+
+
+### `is_version_greater` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L259" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+is_version_greater(a: str | None, b: str | None) -> bool
+```
+
+
+Check if version a is greater than version b.
+
+**Args:**
+- `a`: First version string (or None).
+- `b`: Second version string (or None).
+
+**Returns:**
+- True if a > b, False otherwise.
+
+
+### `max_version` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L272" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+max_version(a: str | None, b: str | None) -> str | None
+```
+
+
+Return the greater of two versions.
+
+**Args:**
+- `a`: First version string (or None).
+- `b`: Second version string (or None).
+
+**Returns:**
+- The greater version, or None if both are None.
+
+
+### `min_version` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L289" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+min_version(a: str | None, b: str | None) -> str | None
+```
+
+
+Return the lesser of two versions.
+
+**Args:**
+- `a`: First version string (or None).
+- `b`: Second version string (or None).
+
+**Returns:**
+- The lesser version, or None if both are None.
+
+
+### `dedupe_with_versions` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L306" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+dedupe_with_versions(components: Sequence[C], key_fn: Callable[[C], str]) -> list[C]
+```
+
+
+Deduplicate components by key, keeping highest version.
+
+Groups components by key, selects the highest version from each group,
+and injects available versions into meta if any component is versioned.
+
+**Args:**
+- `components`: Sequence of components to deduplicate.
+- `key_fn`: Function to extract the grouping key from a component.
+
+**Returns:**
+- Deduplicated list with versions injected into meta.
+
+
+## Classes
+
+### `VersionSpec` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Specification for filtering components by version.
+
+Used by transforms and providers to filter components to a specific
+version or version range. Unversioned components (version=None) always
+match any spec.
+
+**Args:**
+- `gte`: If set, only versions >= this value match.
+- `lt`: If set, only versions < this value match.
+- `eq`: If set, only this exact version matches (gte/lt ignored).
+Matching is PEP 440-normalized and `v`-prefix insensitive, so
+`eq="v1.0"` matches a component versioned `"1.0"`, and `eq="1.0"`
+matches `"1"` (PEP 440 treats `1` and `1.0` as the same version).
+If a server registers two PEP 440-equivalent spellings of the
+same component (e.g. both `"1"` and `"1.0"`), they are the same
+version under this spec; selection among them is deterministic
+(see `version_sort_key`), not registration-order dependent.
+
+
+**Methods:**
+
+#### `matches` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+matches(self, version: str | None) -> bool
+```
+
+Check if a version matches this spec.
+
+**Args:**
+- `version`: The version to check, or None for unversioned.
+- `match_none`: Whether unversioned (None) components match. Defaults to True
+for backward compatibility with retrieval operations. Set to False
+when filtering (e.g., enable/disable) to exclude unversioned components
+from version-specific rules.
+
+**Returns:**
+- True if the version matches the spec.
+
+
+#### `intersect` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+intersect(self, other: VersionSpec | None) -> VersionSpec
+```
+
+Return a spec that satisfies both this spec and other.
+
+Used by transforms to combine caller constraints with filter constraints.
+For example, if a VersionFilter has lt="3.0" and caller requests eq="1.0",
+the intersection validates "1.0" is in range and returns the exact spec.
+
+**Args:**
+- `other`: Another spec to intersect with, or None.
+
+**Returns:**
+- A VersionSpec that matches only versions satisfying both specs.
+
+
+### `VersionKey` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L124" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A comparable version key that handles None, PEP 440 versions, and strings.
+
+Comparison order:
+1. None (unversioned) sorts lowest
+2. PEP 440 versions sort by semantic version order
+3. Invalid versions (strings) sort lexicographically
+4. When comparing PEP 440 vs string, PEP 440 comes first
+
diff --git a/docs/servers/auth/authentication.mdx b/docs/servers/auth/authentication.mdx
new file mode 100644
index 0000000..d37c57f
--- /dev/null
+++ b/docs/servers/auth/authentication.mdx
@@ -0,0 +1,252 @@
+---
+title: Authentication
+sidebarTitle: Overview
+description: Secure your FastMCP server with flexible authentication patterns, from simple API keys to full OAuth 2.1 integration with external identity providers.
+icon: user-shield
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.11.0" />
+
+Authentication in MCP presents unique challenges that differ from traditional web applications. MCP clients need to discover authentication requirements automatically, negotiate OAuth flows without user intervention, and work seamlessly across different identity providers. FastMCP addresses these challenges by providing authentication patterns that integrate with the MCP protocol while remaining simple to implement and deploy.
+
+<Tip>
+Authentication applies only to FastMCP's HTTP-based transports (`http` and `sse`). The STDIO transport inherits security from its local execution environment.
+</Tip>
+
+<Warning>
+**Authentication is rapidly evolving in MCP.** The specification and best practices are changing quickly. FastMCP aims to provide stable, secure patterns that adapt to these changes while keeping your code simple and maintainable.
+</Warning>
+
+## MCP Authentication Challenges
+
+Traditional web authentication assumes a human user with a browser who can interact with login forms and consent screens. MCP clients are often automated systems that need to authenticate without human intervention. This creates several unique requirements:
+
+**Automatic Discovery**: MCP clients must discover authentication requirements by examining server metadata rather than encountering login redirects.
+
+**Programmatic OAuth**: OAuth flows must work without human interaction, relying on pre-configured credentials or Dynamic Client Registration.
+
+**Token Management**: Clients need to obtain, refresh, and manage tokens automatically across multiple MCP servers.
+
+**Protocol Integration**: Authentication must integrate cleanly with MCP's transport mechanisms and error handling.
+
+These challenges mean that not all authentication approaches work well with MCP. The patterns that do work fall into three categories based on the level of authentication responsibility your server assumes.
+
+## Authentication Responsibility
+
+Authentication responsibility exists on a spectrum. Your MCP server can validate tokens created elsewhere, coordinate with external identity providers, or handle the complete authentication lifecycle internally. Each approach involves different trade-offs between simplicity, security, and control.
+
+### Token Validation
+
+Your server validates tokens but delegates their creation to external systems. This approach treats your MCP server as a pure resource server that trusts tokens signed by known issuers.
+
+Token validation works well when you already have authentication infrastructure that can issue structured tokens like JWTs. Your existing API gateway, microservices platform, or enterprise SSO system becomes the source of truth for user identity, while your MCP server focuses on its core functionality.
+
+The key insight is that token validation separates authentication (proving who you are) from authorization (determining what you can do). Your MCP server receives proof of identity in the form of a signed token and makes access decisions based on the claims within that token.
+
+This pattern excels in microservices architectures where multiple services need to validate the same tokens, or when integrating MCP servers into existing systems that already handle user authentication.
+
+### External Identity Providers
+
+Your server coordinates with established identity providers to create seamless authentication experiences for MCP clients. This approach leverages OAuth 2.0 and OpenID Connect protocols to delegate user authentication while maintaining control over authorization decisions.
+
+External identity providers handle the complex aspects of authentication: user credential verification, multi-factor authentication, account recovery, and security monitoring. Your MCP server receives tokens from these trusted providers and validates them using the provider's public keys.
+
+The MCP protocol's support for Dynamic Client Registration makes this pattern particularly powerful. MCP clients can automatically discover your authentication requirements and register themselves with your identity provider without manual configuration.
+
+This approach works best for production applications that need enterprise-grade authentication features without the complexity of building them from scratch. It scales well across multiple applications and provides consistent user experiences.
+
+### Full OAuth Implementation
+
+Your server implements a complete OAuth 2.0 authorization server, handling everything from user credential verification to token lifecycle management. This approach provides maximum control at the cost of significant complexity.
+
+Full OAuth implementation means building user interfaces for login and consent, implementing secure credential storage, managing token lifecycles, and maintaining ongoing security updates. The complexity extends beyond initial implementation to include threat monitoring, compliance requirements, and keeping pace with evolving security best practices.
+
+This pattern makes sense only when you need complete control over the authentication process, operate in air-gapped environments, or have specialized requirements that external providers cannot meet.
+
+## FastMCP Authentication Providers
+
+FastMCP translates these authentication responsibility levels into a variety of concrete classes that handle the complexities of MCP protocol integration. You can build on these classes to handle the complexities of MCP protocol integration.
+
+### TokenVerifier
+
+`TokenVerifier` provides pure token validation without OAuth metadata endpoints. This class focuses on the essential task of determining whether a token is valid and extracting authorization information from its claims.
+
+The implementation handles JWT signature verification, expiration checking, and claim extraction. It validates tokens against known issuers and audiences, ensuring that tokens intended for your server are not accepted by other systems.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+auth = JWTVerifier(
+    jwks_uri="https://your-auth-system.com/.well-known/jwks.json",
+    issuer="https://your-auth-system.com", 
+    audience="your-mcp-server"
+)
+
+mcp = FastMCP(name="Protected Server", auth=auth)
+```
+
+This example configures token validation against a JWT issuer. The `JWTVerifier` will fetch public keys from the JWKS endpoint and validate incoming tokens against those keys. Only tokens with the correct issuer and audience claims will be accepted.
+
+`TokenVerifier` works well when you control both the token issuer and your MCP server, or when integrating with existing JWT-based infrastructure.
+
+→ **Complete guide**: [Token Verification](/servers/auth/token-verification)
+
+### RemoteAuthProvider
+
+`RemoteAuthProvider` enables authentication with identity providers that **support Dynamic Client Registration (DCR)**, such as Descope and WorkOS AuthKit. With DCR, MCP clients can automatically register themselves with the identity provider and obtain credentials without any manual configuration.
+
+This class combines token validation with OAuth discovery metadata. It extends `TokenVerifier` functionality by adding OAuth 2.0 protected resource endpoints that advertise your authentication requirements. MCP clients examine these endpoints to understand which identity providers you trust and how to obtain valid tokens.
+
+The key requirement is that your identity provider must support DCR - the ability for clients to dynamically register and obtain credentials. This is what enables the seamless, automated authentication flow that MCP requires.
+
+For example, the built-in `AuthKitProvider` uses WorkOS AuthKit, which fully supports DCR:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.workos import AuthKitProvider
+
+auth = AuthKitProvider(
+    authkit_domain="https://your-project.authkit.app",
+    base_url="https://your-fastmcp-server.com"
+)
+
+mcp = FastMCP(name="Enterprise Server", auth=auth)
+```
+
+This example uses WorkOS AuthKit as the external identity provider. The `AuthKitProvider` automatically configures token validation against WorkOS and provides the OAuth metadata that MCP clients need for automatic authentication.
+
+`RemoteAuthProvider` is ideal for production applications when your identity provider supports Dynamic Client Registration (DCR). This enables fully automated authentication without manual client configuration.
+
+→ **Complete guide**: [Remote OAuth](/servers/auth/remote-oauth)
+
+### OAuthProxy
+
+<VersionBadge version="2.12.0" />
+
+`OAuthProxy` enables authentication with OAuth providers that **don't support Dynamic Client Registration (DCR)**, such as GitHub, Google, Azure, AWS, and most traditional enterprise identity systems.
+
+When identity providers require manual app registration and fixed credentials, `OAuthProxy` bridges the gap. It presents a DCR-compliant interface to MCP clients (accepting any registration request) while using your pre-registered credentials with the upstream provider. The proxy handles the complexity of callback forwarding, enabling dynamic client callbacks to work with providers that require fixed redirect URIs.
+
+This class solves the fundamental incompatibility between MCP's expectation of dynamic registration and traditional OAuth providers' requirement for manual app registration.
+
+For example, the built-in `GitHubProvider` extends `OAuthProxy` to work with GitHub's OAuth system:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.github import GitHubProvider
+
+auth = GitHubProvider(
+    client_id="Ov23li...",  # Your GitHub OAuth App ID
+    client_secret="abc123...",  # Your GitHub OAuth App Secret
+    base_url="https://your-server.com"
+)
+
+mcp = FastMCP(name="GitHub-Protected Server", auth=auth)
+```
+
+This example uses the GitHub provider, which extends `OAuthProxy` with GitHub-specific token validation. The proxy handles the complete OAuth flow while making GitHub's non-DCR authentication work seamlessly with MCP clients.
+
+`OAuthProxy` is essential when integrating with OAuth providers that don't support DCR. This includes most established providers like GitHub, Google, and Azure, which require manual app registration through their developer consoles.
+
+→ **Complete guide**: [OAuth Proxy](/servers/auth/oauth-proxy)
+
+### OAuthProvider
+
+`OAuthProvider` implements a complete OAuth 2.0 authorization server within your MCP server. This class handles the full authentication lifecycle from user credential verification to token management.
+
+The implementation provides all required OAuth endpoints including authorization, token, and discovery endpoints. It manages client registration, user consent, and token lifecycle while integrating with your user storage and authentication logic.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import OAuthProvider
+
+auth = MyOAuthProvider(
+    user_store=your_user_database,
+    client_store=your_client_registry,
+    # Additional configuration...
+)
+
+mcp = FastMCP(name="Auth Server", auth=auth)
+```
+
+This example shows the basic structure of a custom OAuth provider. The actual implementation requires significant additional configuration for user management, client registration, and security policies.
+
+`OAuthProvider` should be used only when you have specific requirements that external providers cannot meet and the expertise to implement OAuth securely.
+
+→ **Complete guide**: [Full OAuth Server](/servers/auth/full-oauth-server)
+
+### MultiAuth
+
+<VersionBadge version="3.1.0" />
+
+`MultiAuth` composes multiple authentication sources into a single `auth` provider. When a server needs to accept tokens from different issuers — for example, an OAuth proxy for interactive clients alongside JWT verification for machine-to-machine tokens — `MultiAuth` tries each source in order and accepts the first successful verification.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import MultiAuth, OAuthProxy
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+auth = MultiAuth(
+    server=OAuthProxy(
+        issuer_url="https://login.example.com/...",
+        client_id="my-app",
+        client_secret="secret",
+        base_url="https://my-server.com",
+    ),
+    verifiers=[
+        JWTVerifier(
+            jwks_uri="https://internal-issuer.example.com/.well-known/jwks.json",
+            issuer="https://internal-issuer.example.com",
+            audience="my-mcp-server",
+        ),
+    ],
+)
+
+mcp = FastMCP("My Server", auth=auth)
+```
+
+The server (if provided) owns all OAuth routes and metadata. Verifiers contribute only token verification logic. This keeps the MCP discovery surface clean while supporting multiple token sources.
+
+→ **Complete guide**: [Multiple Auth Sources](/servers/auth/multi-auth)
+
+## Configuration
+
+Authentication providers are configured programmatically by instantiating them directly in your code with their required parameters. This makes dependencies explicit and allows your IDE to provide helpful autocompletion and type checking.
+
+For production deployments, load sensitive values like client secrets from environment variables:
+
+```python
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.github import GitHubProvider
+
+# Load secrets from environment variables
+auth = GitHubProvider(
+    client_id=os.environ.get("GITHUB_CLIENT_ID"),
+    client_secret=os.environ.get("GITHUB_CLIENT_SECRET"),
+    base_url=os.environ.get("BASE_URL", "http://localhost:8000")
+)
+
+mcp = FastMCP(name="My Server", auth=auth)
+```
+
+This approach keeps secrets out of your codebase while maintaining explicit configuration. You can use any environment variable names you prefer - there are no special prefixes required.
+
+## Choosing Your Implementation
+
+The authentication approach you choose depends on your existing infrastructure, security requirements, and operational constraints.
+
+**For OAuth providers without DCR support (GitHub, Google, Azure, AWS, most enterprise systems), use OAuth Proxy.** These providers require manual app registration through their developer consoles. OAuth Proxy bridges the gap by presenting a DCR-compliant interface to MCP clients while using your fixed credentials with the provider. The proxy's callback forwarding pattern enables dynamic client ports to work with providers that require fixed redirect URIs.
+
+**For identity providers with DCR support (Descope, WorkOS AuthKit, modern auth platforms), use RemoteAuthProvider.** These providers allow clients to dynamically register and obtain credentials without manual configuration. This enables the fully automated authentication flow that MCP is designed for, providing the best user experience and simplest implementation.
+
+**Token validation works well when you already have authentication infrastructure that issues structured tokens.** If your organization already uses JWT-based systems, API gateways, or enterprise SSO that can generate tokens, this approach integrates seamlessly while keeping your MCP server focused on its core functionality. The simplicity comes from leveraging existing investment in authentication infrastructure.
+
+**When you need tokens from multiple sources, use MultiAuth.** This is common in hybrid architectures where interactive clients authenticate through an OAuth proxy while backend services send JWT tokens directly. `MultiAuth` composes an optional auth server with additional token verifiers, trying each source in order until one succeeds.
+
+**Full OAuth implementation should be avoided unless you have compelling reasons that external providers cannot address.** Air-gapped environments, specialized compliance requirements, or unique organizational constraints might justify this approach, but it requires significant security expertise and ongoing maintenance commitment. The complexity extends far beyond initial implementation to include threat monitoring, security updates, and keeping pace with evolving attack vectors.
+
+FastMCP's architecture supports migration between these approaches as your requirements evolve. You can integrate with existing token systems initially and migrate to external identity providers as your application scales, or implement custom solutions when your requirements outgrow standard patterns.
\ No newline at end of file
diff --git a/docs/servers/auth/full-oauth-server.mdx b/docs/servers/auth/full-oauth-server.mdx
new file mode 100644
index 0000000..529a017
--- /dev/null
+++ b/docs/servers/auth/full-oauth-server.mdx
@@ -0,0 +1,229 @@
+---
+title: Full OAuth Server
+sidebarTitle: Full OAuth Server
+description: Build a self-contained authentication system where your FastMCP server manages users, issues tokens, and validates them.
+icon: users-between-lines
+
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.11.0" />
+
+<Warning>
+**This is an extremely advanced pattern that most users should avoid.** Building a secure OAuth 2.1 server requires deep expertise in authentication protocols, cryptography, and security best practices. The complexity extends far beyond initial implementation to include ongoing security monitoring, threat response, and compliance maintenance.
+
+**Use [Remote OAuth](/servers/auth/remote-oauth) instead** unless you have compelling requirements that external identity providers cannot meet, such as air-gapped environments or specialized compliance needs.
+</Warning>
+
+The Full OAuth Server pattern exists to support the MCP protocol specification's requirements. Your FastMCP server becomes both an Authorization Server and Resource Server, handling the complete authentication lifecycle from user login to token validation.
+
+This documentation exists for completeness - the vast majority of applications should use external identity providers instead.
+
+## OAuthProvider
+
+FastMCP provides the `OAuthProvider` abstract class that implements the OAuth 2.1 specification. To use this pattern, you must subclass `OAuthProvider` and implement all required abstract methods.
+
+<Note>
+`OAuthProvider` handles OAuth endpoints, protocol flows, and security requirements, but delegates all storage, user management, and business logic to your implementation of the abstract methods.
+</Note>
+
+## Required Implementation
+
+You must implement these abstract methods to create a functioning OAuth server:
+
+### Client Management
+
+<Card icon="code" title="Client Management Methods">
+<ParamField body="get_client" type="async method">
+  Retrieve client information by ID from your database.
+  
+  <Expandable title="Parameters">
+    <ParamField body="client_id" type="str">
+      Client identifier to look up
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="OAuthClientInformationFull | None" type="return type">
+      Client information object or `None` if client not found
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="register_client" type="async method">
+  Store new client registration information in your database.
+  
+  <Expandable title="Parameters">
+    <ParamField body="client_info" type="OAuthClientInformationFull">
+      Complete client registration information to store
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="None" type="return type">
+      No return value
+    </ParamField>
+  </Expandable>
+</ParamField>
+</Card>
+
+### Authorization Flow
+
+<Card icon="code" title="Authorization Flow Methods">
+<ParamField body="authorize" type="async method">
+  Handle authorization request and return redirect URL. Must implement user authentication and consent collection.
+  
+  <Expandable title="Parameters">
+    <ParamField body="client" type="OAuthClientInformationFull">
+      OAuth client making the authorization request
+    </ParamField>
+    <ParamField body="params" type="AuthorizationParams">
+      Authorization request parameters from the client
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="str" type="return type">
+      Redirect URL to send the client to
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="load_authorization_code" type="async method">
+  Load authorization code from storage by code string. Return `None` if code is invalid or expired.
+  
+  <Expandable title="Parameters">
+    <ParamField body="client" type="OAuthClientInformationFull">
+      OAuth client attempting to use the authorization code
+    </ParamField>
+    <ParamField body="authorization_code" type="str">
+      Authorization code string to look up
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="AuthorizationCode | None" type="return type">
+      Authorization code object or `None` if not found
+    </ParamField>
+  </Expandable>
+</ParamField>
+</Card>
+
+### Token Management
+
+<Card icon="code" title="Token Management Methods">
+<ParamField body="exchange_authorization_code" type="async method">
+  Exchange authorization code for access and refresh tokens. Must validate code and create new tokens.
+  
+  <Expandable title="Parameters">
+    <ParamField body="client" type="OAuthClientInformationFull">
+      OAuth client exchanging the authorization code
+    </ParamField>
+    <ParamField body="authorization_code" type="AuthorizationCode">
+      Valid authorization code object to exchange
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="OAuthToken" type="return type">
+      New OAuth token containing access and refresh tokens
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="load_refresh_token" type="async method">
+  Load refresh token from storage by token string. Return `None` if token is invalid or expired.
+  
+  <Expandable title="Parameters">
+    <ParamField body="client" type="OAuthClientInformationFull">
+      OAuth client attempting to use the refresh token
+    </ParamField>
+    <ParamField body="refresh_token" type="str">
+      Refresh token string to look up
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="RefreshToken | None" type="return type">
+      Refresh token object or `None` if not found
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="exchange_refresh_token" type="async method">
+  Exchange refresh token for new access/refresh token pair. Must validate scopes and token.
+  
+  <Expandable title="Parameters">
+    <ParamField body="client" type="OAuthClientInformationFull">
+      OAuth client using the refresh token
+    </ParamField>
+    <ParamField body="refresh_token" type="RefreshToken">
+      Valid refresh token object to exchange
+    </ParamField>
+    <ParamField body="scopes" type="list[str]">
+      Requested scopes for the new access token
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="OAuthToken" type="return type">
+      New OAuth token with updated access and refresh tokens
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="load_access_token" type="async method">
+  Load an access token by its token string.
+  
+  <Expandable title="Parameters">
+    <ParamField body="token" type="str">
+      The access token to verify
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="AccessToken | None" type="return type">
+      The access token object, or `None` if the token is invalid
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="revoke_token" type="async method">
+  Revoke access or refresh token, marking it as invalid in storage.
+  
+  <Expandable title="Parameters">
+    <ParamField body="token" type="AccessToken | RefreshToken">
+      Token object to revoke and mark invalid
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="None" type="return type">
+      No return value
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="verify_token" type="async method">
+  Verify bearer token for incoming requests. Return `AccessToken` if valid, `None` if invalid.
+  
+  <Expandable title="Parameters">
+    <ParamField body="token" type="str">
+      Bearer token string from incoming request
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="AccessToken | None" type="return type">
+      Access token object if valid, `None` if invalid or expired
+    </ParamField>
+  </Expandable>
+</ParamField>
+</Card>
+
+Each method must handle storage, validation, security, and error cases according to the OAuth 2.1 specification. The implementation complexity is substantial and requires expertise in OAuth security considerations.
+
+<Warning>
+**Security Notice:** OAuth server implementation involves numerous security considerations including PKCE, state parameters, redirect URI validation, token binding, replay attack prevention, and secure storage requirements. Mistakes can lead to serious security vulnerabilities.
+</Warning>
\ No newline at end of file
diff --git a/docs/servers/auth/multi-auth.mdx b/docs/servers/auth/multi-auth.mdx
new file mode 100644
index 0000000..ba54d25
--- /dev/null
+++ b/docs/servers/auth/multi-auth.mdx
@@ -0,0 +1,95 @@
+---
+title: Multiple Auth Sources
+sidebarTitle: Multiple Auth Sources
+description: Accept tokens from multiple authentication sources with a single server.
+icon: layer-group
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="3.1.0" />
+
+Production servers often need to accept tokens from multiple authentication sources. An interactive application might authenticate through an OAuth proxy, while a backend service sends machine-to-machine JWT tokens directly. `MultiAuth` composes these sources into a single `auth` provider so every valid token is accepted regardless of where it was issued.
+
+## Understanding MultiAuth
+
+`MultiAuth` wraps an optional auth server (like `OAuthProxy`) together with one or more token verifiers (like `JWTVerifier`). When a request arrives with a bearer token, `MultiAuth` tries each source in order and accepts the first successful verification.
+
+The auth server, if provided, is tried first. It owns all OAuth routes and metadata — the verifiers contribute only token verification logic. This keeps the MCP discovery surface clean: one set of routes, one set of metadata, multiple verification paths.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import MultiAuth, OAuthProxy
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+auth = MultiAuth(
+    server=OAuthProxy(
+        issuer_url="https://login.example.com/...",
+        client_id="my-app",
+        client_secret="secret",
+        base_url="https://my-server.com",
+    ),
+    verifiers=[
+        JWTVerifier(
+            jwks_uri="https://internal-issuer.example.com/.well-known/jwks.json",
+            issuer="https://internal-issuer.example.com",
+            audience="my-mcp-server",
+        ),
+    ],
+)
+
+mcp = FastMCP("My Server", auth=auth)
+```
+
+Interactive MCP clients authenticate through the OAuth proxy as usual. Backend services skip OAuth entirely and send a JWT signed by the internal issuer. Both paths are validated, and the first match wins.
+
+## Verification Order
+
+`MultiAuth` checks sources in a deterministic order:
+
+1. **Server** (if provided) — the full auth provider's `verify_token` runs first
+2. **Verifiers** — each `TokenVerifier` is tried in list order
+
+The first source that returns a valid `AccessToken` wins. If every source returns `None`, the request receives a 401 response.
+
+This ordering means the server acts as the "primary" authentication path, with verifiers as fallbacks for tokens the server doesn't recognize.
+
+## Verifiers Only
+
+You don't always need a full OAuth server. If your server only needs to accept tokens from multiple issuers, pass verifiers without a server:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import MultiAuth
+from fastmcp.server.auth.providers.jwt import JWTVerifier, StaticTokenVerifier
+
+auth = MultiAuth(
+    verifiers=[
+        JWTVerifier(
+            jwks_uri="https://issuer-a.example.com/.well-known/jwks.json",
+            issuer="https://issuer-a.example.com",
+            audience="my-server",
+        ),
+        JWTVerifier(
+            jwks_uri="https://issuer-b.example.com/.well-known/jwks.json",
+            issuer="https://issuer-b.example.com",
+            audience="my-server",
+        ),
+    ],
+)
+
+mcp = FastMCP("Multi-Issuer Server", auth=auth)
+```
+
+Without a server, no OAuth routes or metadata are served. This is appropriate for internal systems where clients already know how to obtain tokens.
+
+## API Reference
+
+### MultiAuth
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `server` | `AuthProvider \| None` | Optional auth provider that owns routes and OAuth metadata. Also tried first for token verification. |
+| `verifiers` | `list[TokenVerifier] \| TokenVerifier` | One or more token verifiers tried after the server. |
+| `base_url` | `str \| None` | Override the base URL. Defaults to the server's `base_url`. |
+| `required_scopes` | `list[str] \| None` | Override required scopes. Defaults to the server's scopes. |
diff --git a/docs/servers/auth/oauth-proxy.mdx b/docs/servers/auth/oauth-proxy.mdx
new file mode 100644
index 0000000..e35f244
--- /dev/null
+++ b/docs/servers/auth/oauth-proxy.mdx
@@ -0,0 +1,741 @@
+---
+title: OAuth Proxy
+sidebarTitle: OAuth Proxy
+description: Bridge traditional OAuth providers to work seamlessly with MCP's authentication flow.
+icon: share
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+<VersionBadge version="2.12.0" />
+
+The OAuth proxy enables FastMCP servers to authenticate with OAuth providers that **don't support Dynamic Client Registration (DCR)**. This includes virtually all traditional OAuth providers: GitHub, Google, Azure, AWS, Discord, Facebook, and most enterprise identity systems. For providers that do support DCR (like Descope and WorkOS AuthKit), use [`RemoteAuthProvider`](/servers/auth/remote-oauth) instead.
+
+MCP clients expect to register automatically and obtain credentials on the fly, but traditional providers require manual app registration through their developer consoles. The OAuth proxy bridges this gap by presenting a DCR-compliant interface to MCP clients while using your pre-registered credentials with the upstream provider. When a client attempts to register, the proxy returns your fixed credentials. When a client initiates authorization, the proxy handles the complexity of callback forwarding—storing the client's dynamic callback URL, using its own fixed callback with the provider, then forwarding back to the client after token exchange.
+
+This approach enables any MCP client (whether using random localhost ports or fixed URLs like Claude.ai) to authenticate with any traditional OAuth provider, all while maintaining full OAuth 2.1 and PKCE security.
+
+<Note>
+  For providers that support OIDC discovery (Auth0, Google with OIDC
+  configuration, Azure AD), consider using [`OIDC
+  Proxy`](/servers/auth/oidc-proxy) for automatic configuration. OIDC Proxy
+  extends the OAuth proxy to automatically discover endpoints from the provider's
+  `/.well-known/openid-configuration` URL, simplifying setup.
+</Note>
+
+## Implementation
+
+### Provider Setup Requirements
+
+Before using the OAuth proxy, you need to register your application with your OAuth provider:
+
+1. **Register your application** in the provider's developer console (GitHub Settings, Google Cloud Console, Azure Portal, etc.)
+2. **Configure the redirect URI** as your FastMCP server URL plus your chosen callback path:
+   - Default: `https://your-server.com/auth/callback`
+   - Custom: `https://your-server.com/your/custom/path` (if you set `redirect_path`)
+   - Development: `http://localhost:8000/auth/callback`
+3. **Obtain your credentials**: Client ID and Client Secret
+4. **Note the OAuth endpoints**: Authorization URL and Token URL (usually found in the provider's OAuth documentation)
+
+<Warning>
+  The redirect URI you configure with your provider must exactly match your
+  FastMCP server's URL plus the callback path. If you customize `redirect_path`
+  in the OAuth proxy, update your provider's redirect URI accordingly.
+</Warning>
+
+### Basic Setup
+
+Here's how to implement the OAuth proxy with any provider:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import OAuthProxy
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+# Configure token verification for your provider
+# See the Token Verification guide for provider-specific setups
+token_verifier = JWTVerifier(
+    jwks_uri="https://your-provider.com/.well-known/jwks.json",
+    issuer="https://your-provider.com",
+    audience="your-app-id"
+)
+
+# Create the OAuth proxy
+auth = OAuthProxy(
+    # Provider's OAuth endpoints (from their documentation)
+    upstream_authorization_endpoint="https://provider.com/oauth/authorize",
+    upstream_token_endpoint="https://provider.com/oauth/token",
+
+    # Your registered app credentials
+    upstream_client_id="your-client-id",
+    upstream_client_secret="your-client-secret",
+
+    # Token validation (see Token Verification guide)
+    token_verifier=token_verifier,
+
+    # Your FastMCP server's public URL
+    base_url="https://your-server.com",
+
+    # Optional: customize the callback path (default is "/auth/callback")
+    # redirect_path="/custom/callback",
+)
+
+mcp = FastMCP(name="My Server", auth=auth)
+```
+
+### Configuration Parameters
+
+<Card icon="code" title="OAuthProxy Parameters">
+<ParamField body="upstream_authorization_endpoint" type="str" required>
+  URL of your OAuth provider's authorization endpoint (e.g., `https://github.com/login/oauth/authorize`)
+</ParamField>
+
+<ParamField body="upstream_token_endpoint" type="str" required>
+  URL of your OAuth provider's token endpoint (e.g.,
+  `https://github.com/login/oauth/access_token`)
+</ParamField>
+
+<ParamField body="upstream_client_id" type="str" required>
+  Client ID from your registered OAuth application
+</ParamField>
+
+<ParamField body="upstream_client_secret" type="str | None">
+  Client secret from your registered OAuth application. Optional for PKCE public
+  clients or when using alternative credentials (e.g., managed identity client
+  assertions via a subclass). When omitted, `jwt_signing_key` must be provided
+  explicitly since it cannot be derived from the secret.
+</ParamField>
+
+<ParamField body="token_verifier" type="TokenVerifier" required>
+  A [`TokenVerifier`](/servers/auth/token-verification) instance to validate the
+  provider's tokens
+</ParamField>
+
+<ParamField body="base_url" type="AnyHttpUrl | str" required>
+  Public URL where OAuth endpoints will be accessible, **including any mount path** (e.g., `https://your-server.com/api`).
+
+  This URL is used to construct OAuth callback URLs and operational endpoints. When mounting under a path prefix, include that prefix in `base_url`. Use `issuer_url` separately to specify where auth server metadata is located (typically at root level).
+</ParamField>
+
+<ParamField body="resource_base_url" type="AnyHttpUrl | str | None">
+  Optional public base URL for the protected resource metadata and token audience.
+
+  Use this when your OAuth callbacks and operational endpoints need to live under one public URL, but the protected MCP resource should be advertised under another. FastMCP will still append the MCP mount path (for example, `/mcp`) to this base URL.
+</ParamField>
+
+<ParamField body="redirect_path" type="str" default="/auth/callback">
+  Path for OAuth callbacks. Must match the redirect URI configured in your OAuth
+  application
+</ParamField>
+
+<ParamField body="upstream_revocation_endpoint" type="str | None">
+  Optional URL of provider's token revocation endpoint
+</ParamField>
+
+<ParamField body="issuer_url" type="AnyHttpUrl | str | None">
+  Issuer URL for OAuth authorization server metadata (defaults to `base_url`).
+
+  When `issuer_url` has a path component (either explicitly or by defaulting from `base_url`), FastMCP creates path-aware discovery routes per RFC 8414. For example, if `base_url` is `http://localhost:8000/api`, the authorization server metadata will be at `/.well-known/oauth-authorization-server/api`.
+
+  **Default behavior (recommended for most cases):**
+  ```python
+  auth = GitHubProvider(
+      base_url="http://localhost:8000/api",  # OAuth endpoints under /api
+      # issuer_url defaults to base_url - path-aware discovery works automatically
+  )
+  ```
+
+  **When to set explicitly:**
+  Set `issuer_url` to root level only if you want multiple MCP servers to share a single discovery endpoint:
+  ```python
+  auth = GitHubProvider(
+      base_url="http://localhost:8000/api",
+      issuer_url="http://localhost:8000"  # Shared root-level discovery
+  )
+  ```
+
+  See the [HTTP Deployment guide](/deployment/http#mounting-authenticated-servers) for complete mounting examples.
+</ParamField>
+
+<ParamField body="service_documentation_url" type="AnyHttpUrl | str | None">
+  Optional URL to your service documentation
+</ParamField>
+
+<ParamField body="forward_pkce" type="bool" default="True">
+  Whether to forward PKCE (Proof Key for Code Exchange) to the upstream OAuth
+  provider. When enabled and the client uses PKCE, the proxy generates its own
+  PKCE parameters to send upstream while separately validating the client's
+  PKCE. This ensures end-to-end PKCE security at both layers (client-to-proxy
+  and proxy-to-upstream). - `True` (default): Forward PKCE for providers that
+  support it (Google, Azure, AWS, GitHub, etc.) - `False`: Disable only if upstream
+  provider doesn't support PKCE
+</ParamField>
+
+<ParamField body="forward_resource" type="bool" default="True">
+  Whether to forward RFC 8707 `resource` parameters from MCP clients to the
+  upstream OAuth provider. When enabled, the proxy includes the resource indicator
+  in authorization requests, allowing providers that support RFC 8707 to scope
+  tokens to specific resources. Disable for providers that reject unknown
+  parameters.
+</ParamField>
+
+<ParamField body="token_endpoint_auth_method" type="str | None">
+  Token endpoint authentication method for the upstream OAuth server. Controls
+  how the proxy authenticates when exchanging authorization codes and refresh
+  tokens with the upstream provider. - `"client_secret_basic"`: Send credentials
+  in Authorization header (most common) - `"client_secret_post"`: Send
+  credentials in request body (required by some providers) - `"none"`: No
+  authentication (for public clients) - `None` (default): Uses authlib's default
+  (typically `"client_secret_basic"`) Set this if your provider requires a
+  specific authentication method and the default doesn't work.
+</ParamField>
+
+<ParamField body="allowed_client_redirect_uris" type="list[str] | None">
+  List of allowed redirect URI patterns for MCP clients. Patterns support
+  wildcards (e.g., `"http://localhost:*"`, `"https://*.example.com/*"`).
+  - `None` (default): DCR clients use registered redirect URIs, with loopback
+    ports allowed to vary for MCP compatibility. Unsafe browser schemes such as
+    `javascript:`, `data:`, `file:`, and `vbscript:` are rejected.
+  - Empty list `[]`: No redirect URIs allowed
+  - Custom list: Only matching patterns allowed
+
+  These patterns apply to MCP client loopback redirects. Configure the upstream
+  OAuth app redirect URI separately with `redirect_path`.
+</ParamField>
+
+<ParamField body="valid_scopes" type="list[str] | None">
+  List of all possible valid scopes for the OAuth provider. These are advertised
+  to clients through the `/.well-known` endpoints. Defaults to `required_scopes`
+  from your TokenVerifier if not specified.
+</ParamField>
+
+<ParamField body="extra_authorize_params" type="dict[str, str] | None">
+  Additional parameters to forward to the upstream authorization endpoint. Useful for provider-specific parameters that aren't part of the standard OAuth2 flow.
+  
+  For example, Auth0 requires an `audience` parameter to issue JWT tokens:
+  ```python
+  extra_authorize_params={"audience": "https://api.example.com"}
+  ```
+  
+  These parameters are added to every authorization request sent to the upstream provider.
+</ParamField>
+
+<ParamField body="extra_token_params" type="dict[str, str] | None">
+  Additional parameters to forward to the upstream token endpoint during code exchange and token refresh. Useful for provider-specific requirements during token operations.
+
+For example, some providers require additional context during token exchange:
+
+```python
+extra_token_params={"audience": "https://api.example.com"}
+```
+
+These parameters are included in all token requests to the upstream provider.
+
+</ParamField>
+
+<ParamField body="client_storage" type="AsyncKeyValue | None">
+
+<VersionBadge version="2.13.0" />
+  Storage backend for persisting OAuth client registrations and upstream tokens.
+
+  **Default behavior:**
+  By default, clients are automatically persisted to an encrypted disk store, allowing them to survive server restarts as long as the filesystem remains accessible. This means MCP clients only need to register once and can reconnect seamlessly. The disk store is encrypted using a key derived from the JWT Signing Key (which is derived from the upstream client secret by default). For client registrations to survive upstream client secret rotation, you should provide a JWT Signing Key or your own client_storage.
+
+For production deployments with multiple servers or cloud deployments, see [Storage Backends](/servers/storage-backends) for available options.
+
+<Warning>
+  **When providing custom storage**, wrap it in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest:
+
+  ```python
+  from key_value.aio.stores.redis import RedisStore
+  from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+  from cryptography.fernet import Fernet
+  import os
+
+  auth = OAuthProxy(
+      ...,
+      jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+      client_storage=FernetEncryptionWrapper(
+          key_value=RedisStore(host="redis.example.com", port=6379),
+          fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+      )
+  )
+  ```
+
+  Without encryption, upstream OAuth tokens are stored in plaintext.
+</Warning>
+
+Testing with in-memory storage (unencrypted):
+
+```python
+from key_value.aio.stores.memory import MemoryStore
+
+# Use in-memory storage for testing (clients lost on restart)
+auth = OAuthProxy(..., client_storage=MemoryStore())
+```
+
+</ParamField>
+
+<ParamField body="jwt_signing_key" type="str | bytes | None">
+
+<VersionBadge version="2.13.0" />
+  Secret used to sign FastMCP JWT tokens issued to clients. Accepts any string or bytes - will be derived into a proper 32-byte cryptographic key using HKDF.
+
+  **Default behavior (`None`):**
+  Derives a 32-byte key using PBKDF2 from the upstream client secret.
+
+  **For production:**
+  Provide an explicit secret (e.g., from environment variable) to use a fixed key instead of the key derived from the upstream client secret. This allows you to manage keys securely in cloud environments, allows keys to work across multiple instances, and allows you to rotate keys without losing client registrations.
+
+  ```python
+  import os
+
+  auth = OAuthProxy(
+      ...,
+      jwt_signing_key=os.environ["JWT_SIGNING_KEY"],  # Any sufficiently complex string!
+      client_storage=RedisStore(...)  # Persistent storage
+  )
+  ```
+
+  See [HTTP Deployment - OAuth Token Security](/deployment/http#oauth-token-security) for complete production setup.
+</ParamField>
+
+
+<ParamField body="require_authorization_consent" type='bool | Literal["remember", "external"]' default="True">
+  Consent screen behavior for authorization requests. The consent page displays which client is requesting access, defending against [confused deputy and AS-in-the-middle attacks](#confused-deputy-attacks) by requiring explicit user approval.
+
+  **`True` (default) — always prompt:**
+  Users see the consent screen on every authorization. Strongest protection against AS-in-the-middle attacks where a malicious MCP server redirects the victim's browser into a legitimate proxy and relies on a previously-remembered approval to silently complete the flow.
+
+  **`"remember"` — silent consent on return:**
+  Users see the consent screen on first authorization; subsequent flows from the same browser for the same `(client_id, redirect_uri)` are silently approved via a signed cookie. Cross-site navigations (detected via `Sec-Fetch-Site`) fall back to the prompt. `Sec-Fetch-Site` is a browser-level heuristic rather than a protocol guarantee: an attacker who finds a way to initiate a non-cross-site navigation (XSS on a sibling origin, a same-site redirect chain, etc.) can reach the silent-consent path. `True` does not depend on this signal. See [Confused Deputy Attacks](#confused-deputy-attacks) for the underlying attack class.
+
+  **`"external"` — delegate to upstream:**
+  Skip the built-in consent page; consent is collected by the upstream IdP or a custom login page referenced via `upstream_authorization_endpoint`. No security warning is logged.
+
+  **`False` — disable entirely:**
+  Authorization proceeds directly to the upstream provider without any consent UI. Logs a security warning. Only for local development or testing.
+
+  ```python
+  # Development/testing only - skip consent screen
+  auth = OAuthProxy(
+      ...,
+      require_authorization_consent=False  # ⚠️ Security warning: only for local/testing
+  )
+
+  # Convenience mode - silent consent on return visits (less safe than True)
+  auth = OAuthProxy(
+      ...,
+      require_authorization_consent="remember",
+  )
+  ```
+
+  <Warning>
+    Disabling consent removes an important security layer. Only disable for local development or testing environments where you fully control all connecting clients.
+  </Warning>
+</ParamField>
+
+<ParamField body="consent_csp_policy" type="str | None" default="None">
+  Content Security Policy for the consent page.
+
+  - `None` (default): Uses the built-in CSP policy with appropriate directives for form submission
+  - Empty string `""`: Disables CSP entirely (no meta tag rendered)
+  - Custom string: Uses the provided value as the CSP policy
+
+  This is useful for organizations that have their own CSP policies and need to override or disable FastMCP's built-in CSP directives.
+
+  ```python
+  # Disable CSP entirely (let org CSP policies apply)
+  auth = OAuthProxy(..., consent_csp_policy="")
+
+  # Use custom CSP policy
+  auth = OAuthProxy(..., consent_csp_policy="default-src 'self'; style-src 'unsafe-inline'")
+  ```
+</ParamField>
+</Card>
+
+### Using Built-in Providers
+
+FastMCP includes pre-configured providers for common services:
+
+```python
+from fastmcp.server.auth.providers.github import GitHubProvider
+
+auth = GitHubProvider(
+    client_id="your-github-app-id",
+    client_secret="your-github-app-secret",
+    base_url="https://your-server.com"
+)
+
+mcp = FastMCP(name="My Server", auth=auth)
+```
+
+Available providers include `GitHubProvider`, `GoogleProvider`, and others. These handle token verification automatically.
+
+### Token Verification
+
+The OAuth proxy requires a compatible `TokenVerifier` to validate tokens from your provider. Different providers use different token formats:
+
+- **JWT tokens** (Google, Azure): Use `JWTVerifier` with the provider's JWKS endpoint
+- **Opaque tokens with RFC 7662 introspection** (Auth0, Okta, WorkOS): Use `IntrospectionTokenVerifier`
+- **Opaque tokens (provider-specific)** (GitHub, Discord): Use provider-specific verifiers like `GitHubTokenVerifier`
+
+See the [Token Verification guide](/servers/auth/token-verification) for detailed setup instructions for your provider.
+
+### Scope Configuration
+
+OAuth scopes control what permissions your application requests from users. They're configured through your `TokenVerifier` (required for the OAuth proxy to validate tokens from your provider). Set `required_scopes` to automatically request the permissions your application needs:
+
+```python
+JWTVerifier(..., required_scopes = ["read:user", "write:data"])
+```
+
+Dynamic clients created by the proxy will automatically include these scopes in their authorization requests. See the [Token Verification](#token-verification) section below for detailed setup.
+
+### Custom Parameters
+
+Some OAuth providers require additional parameters beyond the standard OAuth2 flow. Use `extra_authorize_params` and `extra_token_params` to pass provider-specific requirements. For example, Auth0 requires an `audience` parameter to issue JWT tokens instead of opaque tokens:
+
+```python
+auth = OAuthProxy(
+    upstream_authorization_endpoint="https://your-domain.auth0.com/authorize",
+    upstream_token_endpoint="https://your-domain.auth0.com/oauth/token",
+    upstream_client_id="your-auth0-client-id",
+    upstream_client_secret="your-auth0-client-secret",
+
+    # Auth0-specific audience parameter
+    extra_authorize_params={"audience": "https://your-api-identifier.com"},
+    extra_token_params={"audience": "https://your-api-identifier.com"},
+
+    token_verifier=JWTVerifier(
+        jwks_uri="https://your-domain.auth0.com/.well-known/jwks.json",
+        issuer="https://your-domain.auth0.com/",
+        audience="https://your-api-identifier.com"
+    ),
+    base_url="https://your-server.com"
+)
+```
+
+The proxy also forwards RFC 8707 `resource` parameters from MCP clients to upstream providers that support them. This is enabled by default via the `forward_resource` parameter. Disable it for providers that reject unknown parameters.
+
+## OAuth Flow
+
+```mermaid
+sequenceDiagram
+    participant Client as MCP Client<br/>(localhost:random)
+    participant User as User
+    participant Proxy as FastMCP OAuth Proxy<br/>(server:8000)
+    participant Provider as OAuth Provider<br/>(GitHub, etc.)
+
+    Note over Client, Proxy: Dynamic Registration (Local)
+    Client->>Proxy: 1. POST /register<br/>redirect_uri: localhost:54321/callback
+    Proxy-->>Client: 2. Returns fixed upstream credentials
+
+    Note over Client, User: Authorization with User Consent
+    Client->>Proxy: 3. GET /authorize<br/>redirect_uri=localhost:54321/callback<br/>code_challenge=CLIENT_CHALLENGE
+    Note over Proxy: Store transaction with client PKCE<br/>Generate proxy PKCE pair
+    Proxy->>User: 4. Show consent page<br/>(client details, redirect URI, scopes)
+    User->>Proxy: 5. Approve/deny consent
+    Note over Proxy: Set consent binding cookie<br/>(binds browser to this flow)
+    Proxy->>Provider: 6. Redirect to provider<br/>redirect_uri=server:8000/auth/callback<br/>code_challenge=PROXY_CHALLENGE
+
+    Note over Provider, Proxy: Provider Callback
+    Provider->>Proxy: 7. GET /auth/callback<br/>with authorization code
+    Note over Proxy: Verify consent binding cookie<br/>(reject if missing or mismatched)
+    Proxy->>Provider: 8. Exchange code for tokens<br/>code_verifier=PROXY_VERIFIER
+    Provider-->>Proxy: 9. Access & refresh tokens
+
+    Note over Proxy, Client: Client Callback Forwarding
+    Proxy->>Client: 10. Redirect to localhost:54321/callback<br/>with new authorization code
+
+    Note over Client, Proxy: Token Exchange
+    Client->>Proxy: 11. POST /token with code<br/>code_verifier=CLIENT_VERIFIER
+    Proxy-->>Client: 12. Returns FastMCP JWT tokens
+```
+
+The flow diagram above illustrates the complete OAuth proxy pattern. Let's understand each phase:
+
+### Registration Phase
+
+When an MCP client calls `/register` with its dynamic callback URL, the proxy responds with your pre-configured upstream credentials. The client stores these credentials believing it has registered a new app. Meanwhile, the proxy records the client's callback URL for later use.
+
+### Authorization Phase
+
+The client initiates OAuth by redirecting to the proxy's `/authorize` endpoint. The proxy:
+
+1. Stores the client's transaction with its PKCE challenge
+2. Generates its own PKCE parameters for upstream security
+3. Shows the user a consent page with the client's details, redirect URI, and requested scopes
+4. If the user approves (or the client was previously approved), sets a consent binding cookie and redirects to the upstream provider using the fixed callback URL
+
+This dual-PKCE approach maintains end-to-end security at both the client-to-proxy and proxy-to-provider layers. The consent step protects against confused deputy attacks by ensuring you explicitly approve each client before it can complete authorization, and the consent binding cookie ensures that only the browser that approved consent can complete the callback.
+
+### Callback Phase
+
+After user authorization, the provider redirects back to the proxy's fixed callback URL. The proxy:
+
+1. Verifies the consent binding cookie matches the transaction (rejecting requests from a different browser)
+2. Exchanges the authorization code for tokens with the provider
+3. Stores these tokens temporarily
+4. Generates a new authorization code for the client
+5. Redirects to the client's original dynamic callback URL
+
+### Token Exchange Phase
+
+Finally, the client exchanges its authorization code with the proxy. The proxy validates the client's PKCE verifier, then issues its own FastMCP JWT tokens (rather than forwarding the upstream provider's tokens). See [Token Architecture](#token-architecture) for details on this design.
+
+This entire flow is transparent to the MCP client—it experiences a standard OAuth flow with dynamic registration, unaware that a proxy is managing the complexity behind the scenes.
+
+### Token Architecture
+
+The OAuth proxy implements a **token factory pattern**: instead of directly forwarding tokens from the upstream OAuth provider, it issues its own JWT tokens to MCP clients. This maintains proper OAuth 2.0 token audience boundaries and enables better security controls.
+
+**How it works:**
+
+When an MCP client completes authorization, the proxy:
+
+1. **Receives upstream tokens** from the OAuth provider (GitHub, Google, etc.)
+2. **Encrypts and stores** these tokens using Fernet encryption (AES-128-CBC + HMAC-SHA256)
+3. **Issues FastMCP JWT tokens** to the client, signed with HS256
+
+The FastMCP JWT contains minimal claims: issuer, audience, client ID, scopes, expiration, and a unique token identifier (JTI). The JTI acts as a reference linking to the encrypted upstream token.
+
+**Token validation:**
+
+When a client makes an MCP request with its FastMCP token:
+
+1. **FastMCP validates the JWT** signature, expiration, issuer, and audience
+2. **Looks up the upstream token** using the JTI from the validated JWT
+3. **Decrypts and validates** the upstream token with the provider
+
+This two-tier validation ensures that FastMCP tokens can only be used with this server (via audience validation) while maintaining full upstream token security.
+
+This architecture also prevents [token passthrough](#token-passthrough) — see the [Security](#security) section for details.
+
+**Token expiry alignment:**
+
+By default, FastMCP token lifetimes match the upstream token lifetimes. When the upstream token expires, the FastMCP token also expires, maintaining consistent security boundaries.
+
+**Extending the FastMCP token lifetime:**
+
+Some upstream providers issue short-lived access tokens (5–60 minutes is common). Because the FastMCP token is a reference into the proxy's storage rather than the upstream credential itself, its client-facing lifetime can be longer than the upstream token's without weakening security: every request re-validates the upstream token and transparently refreshes it when it has expired, so a revoked or genuinely expired upstream session still fails validation and forces re-authentication.
+
+This matters for MCP clients that don't refresh gracefully. For example, [`mcp-remote`](https://github.com/geelen/mcp-remote) (used by Claude Desktop) has known issues handling access-token expiry, so a short upstream lifetime can push users through a full OAuth flow after every idle period. Set `fastmcp_access_token_expiry_seconds` to decouple the FastMCP token lifetime from the upstream `expires_in`:
+
+```python
+from fastmcp.server.auth import OAuthProxy
+
+auth = OAuthProxy(
+    upstream_authorization_endpoint="https://provider.com/oauth/authorize",
+    upstream_token_endpoint="https://provider.com/oauth/token",
+    upstream_client_id="your-client-id",
+    upstream_client_secret="your-client-secret",
+    token_verifier=token_verifier,
+    base_url="https://your-server.com",
+    fastmcp_access_token_expiry_seconds=60 * 60 * 24,  # 24 hours
+)
+```
+
+The upstream token's real expiry is preserved internally to drive transparent refresh; only the FastMCP-issued token lives longer. This parameter is available on every provider built on the OAuth proxy (`GitHubProvider`, `GoogleProvider`, `AzureProvider`, and the rest).
+
+Extending the lifetime only works when the upstream provider issues a refresh token, since that's what lets the proxy renew the access token behind the scenes. When the upstream provides no refresh token, the FastMCP token lifetime is capped at the upstream `expires_in` — issuing a longer-lived token would claim a validity the proxy can't honor.
+
+**Refresh tokens:**
+
+The proxy issues its own refresh tokens that map to upstream refresh tokens. When a client uses a FastMCP refresh token, the proxy refreshes the upstream token and issues a new FastMCP access token.
+
+### PKCE Forwarding
+
+The OAuth proxy automatically handles PKCE (Proof Key for Code Exchange) when working with providers that support or require it. The proxy generates its own PKCE parameters to send upstream while separately validating the client's PKCE, ensuring end-to-end security at both layers.
+
+This is enabled by default via the `forward_pkce` parameter and works seamlessly with providers like Google, Azure AD, and GitHub. Only disable it for legacy providers that don't support PKCE:
+
+```python
+# Disable PKCE forwarding only if upstream doesn't support it
+auth = OAuthProxy(
+    ...,
+    forward_pkce=False  # Default is True
+)
+```
+
+### Redirect URI Validation
+
+By default, the OAuth proxy validates DCR clients against their registered redirect URIs while allowing loopback ports to vary for MCP compatibility. Unsafe browser schemes such as `javascript:` are always rejected. You can restrict which clients can connect at the server level by specifying allowed patterns:
+
+```python
+# Allow only localhost clients (common for development)
+auth = OAuthProxy(
+    # ... other parameters ...
+    allowed_client_redirect_uris=[
+        "http://localhost:*",
+        "http://127.0.0.1:*"
+    ]
+)
+
+# Allow specific known clients
+auth = OAuthProxy(
+    # ... other parameters ...
+    allowed_client_redirect_uris=[
+        "http://localhost:*",
+        "https://claude.ai/api/mcp/auth_callback",
+        "https://*.mycompany.com/auth/*"  # Wildcard patterns supported
+    ]
+)
+```
+
+Check your server logs for "Client registered with redirect_uri" messages to identify what URLs your clients use.
+
+## CIMD Support
+
+<VersionBadge version="3.0.0" />
+
+The OAuth proxy supports **Client ID Metadata Documents (CIMD)**, an alternative to Dynamic Client Registration where clients host a static JSON document at an HTTPS URL. Instead of registering dynamically, clients simply provide their CIMD URL as their `client_id`, and the server fetches and validates the metadata.
+
+CIMD clients appear in the consent screen with a verified domain badge, giving users confidence about which application is requesting access. This provides stronger identity verification than DCR, where any client can claim any name.
+
+### How CIMD Works
+
+When a client presents an HTTPS URL as its `client_id` (for example, `https://myapp.example.com/oauth/client.json`), the OAuth proxy recognizes it as a CIMD client and:
+
+1. Fetches the JSON document from that URL
+2. Validates that the document's `client_id` field matches the URL
+3. Extracts client metadata (name, redirect URIs, scopes, etc.)
+4. Stores the client persistently alongside DCR clients
+5. Shows the verified domain in the consent screen
+
+This flow happens transparently. MCP clients that support CIMD simply provide their metadata URL instead of registering, and the OAuth proxy handles the rest.
+
+### CIMD Configuration
+
+CIMD support is enabled by default for `OAuthProxy`.
+
+<Card icon="code" title="CIMD Parameters">
+<ParamField body="enable_cimd" type="bool" default="True">
+  Whether to accept CIMD URLs as client identifiers. When enabled, clients can use HTTPS URLs pointing to metadata documents as their `client_id` instead of registering via DCR.
+</ParamField>
+</Card>
+
+### Private Key JWT Authentication
+
+CIMD clients can authenticate using `private_key_jwt` instead of the default `none` authentication method. This provides cryptographic proof of client identity by signing JWT assertions with a private key, while the server verifies using the client's public key from their CIMD document.
+
+To use `private_key_jwt`, the CIMD document must include either a `jwks_uri` (URL to fetch the public key set) or inline `jwks` (the key set directly in the document):
+
+```json
+{
+  "client_id": "https://myapp.example.com/oauth/client.json",
+  "client_name": "My Secure App",
+  "redirect_uris": ["http://localhost:*/callback"],
+  "token_endpoint_auth_method": "private_key_jwt",
+  "jwks_uri": "https://myapp.example.com/.well-known/jwks.json"
+}
+```
+
+The OAuth proxy validates JWT assertions according to RFC 7523, checking the signature, issuer, audience, subject claims, and preventing replay attacks via JTI tracking.
+
+### Security Considerations
+
+CIMD provides several security advantages over DCR:
+
+- **Verified identity**: The domain in the `client_id` URL is verified by HTTPS, so users know which organization is requesting access
+- **No registration required**: Clients don't need to store or manage dynamically-issued credentials
+- **Redirect URI enforcement**: CIMD documents must declare `redirect_uris`, which are enforced by the proxy (wildcard patterns supported)
+- **SSRF protection**: The OAuth proxy blocks fetches to localhost, private IPs, and reserved addresses
+- **Replay prevention**: For `private_key_jwt` clients, JTI claims are tracked to prevent assertion replay
+- **Cache-aware fetching**: CIMD documents are cached according to HTTP cache headers and revalidated when required
+
+CIMD is enabled by default. To disable it entirely (for example, to require all clients to register via DCR), set `enable_cimd=False` explicitly:
+
+```python
+auth = OAuthProxy(
+    ...,
+    enable_cimd=False,
+)
+```
+
+## Security
+
+### Key and Storage Management
+
+<VersionBadge version="2.13.0" />
+The OAuth proxy requires cryptographic keys for JWT signing and storage encryption, plus persistent storage to maintain valid tokens across server restarts.
+
+**Default behavior (appropriate for development only):**
+- **Mac/Windows**: FastMCP automatically generates keys and stores them in your system keyring. Storage defaults to disk. Tokens survive server restarts. This is **only** suitable for development and local testing.
+- **Linux**: Keys are ephemeral (random salt at startup). Storage defaults to memory. Tokens become invalid on server restart.
+
+**For production:**
+Configure the following parameters together: provide a unique `jwt_signing_key` (for signing FastMCP JWTs), and a shared `client_storage` backend (for storing tokens). Both are required for production deployments. Use a network-accessible storage backend like Redis or DynamoDB rather than local disk storage. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** (see the `client_storage` parameter documentation above for examples). The keys accept any secret string and derive proper cryptographic keys using HKDF. See [OAuth Token Security](/deployment/http#oauth-token-security) and [Storage Backends](/servers/storage-backends) for complete production setup.
+
+### Confused Deputy Attacks
+
+<VersionBadge version="2.13.0" />
+
+A confused deputy attack allows a malicious client to steal your authorization by tricking you into granting it access under your identity.
+
+The OAuth proxy works by bridging DCR clients to traditional auth providers, which means that multiple MCP clients connect through a single upstream OAuth application. An attacker can exploit this shared application by registering a malicious client with their own redirect URI, then sending you an authorization link. When you click it, your browser goes through the OAuth flow—but since you may have already authorized this OAuth app before, the provider might auto-approve the request. The authorization code then gets sent to the attacker's redirect URI instead of a legitimate client, giving them access under your credentials.
+
+#### Mitigation
+
+FastMCP's OAuth proxy defends against confused deputy attacks with two layers of protection:
+
+**Consent screen.** Before any authorization happens, you see a consent page showing the client's details, redirect URI, and requested scopes. This gives you the opportunity to review and deny suspicious requests. By default (`require_authorization_consent=True`), the page is shown on every flow, which is the strongest protection. Setting `require_authorization_consent="remember"` approves previously-approved `(client_id, redirect_uri)` pairs silently on return visits, trading some protection for UX (see below). The consent mechanism is implemented with CSRF tokens and cryptographically signed cookies to prevent tampering.
+
+![](/assets/images/oauth-proxy-consent-screen.png)
+
+The consent page automatically displays your server's name, icon, and website URL, if available. These visual identifiers help users confirm they're authorizing the correct server.
+
+**Browser-session binding.** When you approve consent (or when a previously-approved client auto-approves), the proxy sets a cryptographically signed cookie that binds your browser session to the authorization flow. When the identity provider redirects back to the proxy's callback, the proxy verifies that this cookie is present and matches the expected transaction. A different browser — such as a victim who was sent the authorization URL by an attacker — won't have this cookie, and the callback will be rejected with a 403 error. This prevents the attack even when the identity provider skips the consent page for previously-authorized applications.
+
+#### AS-in-the-middle variant
+
+A related attack works even with browser-session binding in place: a malicious MCP server advertises its own authorization server, which redirects the victim's browser into the legitimate proxy's `/authorize` endpoint. Because the victim's browser carries both the prior-approval cookie and the newly-issued session-binding cookie throughout, both layers pass. The defense is the consent prompt itself: if consent is shown (`require_authorization_consent=True`), the victim sees the benign MCP server's name on the consent page — which doesn't match the malicious server they thought they were connecting to — and can deny.
+
+`require_authorization_consent="remember"` adds a `Sec-Fetch-Site` check to keep this path safe for legitimate return flows (the attack navigation lands as `cross-site` and falls back to the prompt), but this is a browser-level heuristic. For the strongest defense, leave `require_authorization_consent=True`.
+
+**Learn more:**
+- [MCP Security Best Practices](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#confused-deputy-problem) - Official specification guidance
+- [Confused Deputy Attacks Explained](https://den.dev/blog/mcp-confused-deputy-api-management/) - Detailed walkthrough by Den Delimarsky
+
+### Token Passthrough
+
+[Token passthrough](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#token-passthrough) occurs when an intermediary exposes upstream tokens to downstream clients, allowing those clients to impersonate the intermediary or access services they shouldn't reach.
+
+#### Client-facing mitigation
+
+The OAuth proxy's [token factory architecture](#token-architecture) prevents this by design. MCP clients only ever receive FastMCP-issued JWTs — the upstream provider token is never sent to the client. A FastMCP JWT is scoped to your server and cannot be used to access the upstream provider directly, even if intercepted.
+
+#### Calling downstream services
+
+When your MCP server needs to call other APIs on behalf of the authenticated user, avoid forwarding the upstream token directly — this reintroduces the token passthrough problem in the other direction. Instead, use a token exchange flow like [OAuth 2.0 Token Exchange (RFC 8693)](https://datatracker.ietf.org/doc/html/rfc8693) or your provider's equivalent (such as Azure's [On-Behalf-Of flow](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-on-behalf-of-flow)) to obtain a new token scoped to the downstream service.
+
+The upstream token is available in your tool functions via `get_access_token()` or the `CurrentAccessToken` dependency, which you can use as the assertion for a token exchange. The exchanged token will be scoped to the specific downstream service and identify your MCP server as the authorized intermediary, maintaining proper audience boundaries throughout the chain.
+
+## Production Configuration
+
+For production deployments, load sensitive credentials from environment variables:
+
+```python
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.github import GitHubProvider
+
+# Load secrets from environment variables
+auth = GitHubProvider(
+    client_id=os.environ.get("GITHUB_CLIENT_ID"),
+    client_secret=os.environ.get("GITHUB_CLIENT_SECRET"),
+    base_url=os.environ.get("BASE_URL", "https://your-production-server.com")
+)
+
+mcp = FastMCP(name="My Server", auth=auth)
+
+@mcp.tool
+def protected_tool(data: str) -> str:
+    """This tool is now protected by OAuth."""
+    return f"Processed: {data}"
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+
+This keeps secrets out of your codebase while maintaining explicit configuration.
diff --git a/docs/servers/auth/oidc-proxy.mdx b/docs/servers/auth/oidc-proxy.mdx
new file mode 100644
index 0000000..fde747e
--- /dev/null
+++ b/docs/servers/auth/oidc-proxy.mdx
@@ -0,0 +1,287 @@
+---
+title: OIDC Proxy
+sidebarTitle: OIDC Proxy
+description: Bridge OIDC providers to work seamlessly with MCP's authentication flow.
+icon: share
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+<VersionBadge version="2.12.4" />
+
+The OIDC proxy enables FastMCP servers to authenticate with OIDC providers that **don't support Dynamic Client Registration (DCR)** out of the box. This includes OAuth providers like: Auth0, Google, Azure, AWS, etc. For providers that do support DCR (like WorkOS AuthKit), use [`RemoteAuthProvider`](/servers/auth/remote-oauth) instead.
+
+The OIDC proxy is built upon [`OAuthProxy`](/servers/auth/oauth-proxy) so it has all the same functionality under the covers.
+
+## Implementation
+
+### Provider Setup Requirements
+
+Before using the OIDC proxy, you need to register your application with your OAuth provider:
+
+1. **Register your application** in the provider's developer console (Auth0 Applications, Google Cloud Console, Azure Portal, etc.)
+2. **Configure the redirect URI** as your FastMCP server URL plus your chosen callback path:
+   - Default: `https://your-server.com/auth/callback`
+   - Custom: `https://your-server.com/your/custom/path` (if you set `redirect_path`)
+   - Development: `http://localhost:8000/auth/callback`
+3. **Obtain your credentials**: Client ID and Client Secret
+
+<Warning>
+  The redirect URI you configure with your provider must exactly match your
+  FastMCP server's URL plus the callback path. If you customize `redirect_path`
+  in the OIDC proxy, update your provider's redirect URI accordingly.
+</Warning>
+
+### Basic Setup
+
+Here's how to implement the OIDC proxy with any provider:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.oidc_proxy import OIDCProxy
+
+# Create the OIDC proxy
+auth = OIDCProxy(
+    # Provider's configuration URL
+    config_url="https://provider.com/.well-known/openid-configuration",
+
+    # Your registered app credentials
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+
+    # Your FastMCP server's public URL
+    base_url="https://your-server.com",
+
+    # Optional: customize the callback path (default is "/auth/callback")
+    # redirect_path="/custom/callback",
+)
+
+mcp = FastMCP(name="My Server", auth=auth)
+```
+
+### Configuration Parameters
+
+<Card icon="code" title="OIDCProxy Parameters">
+<ParamField body="config_url" type="str" required>
+  URL of your OAuth provider's OIDC configuration
+</ParamField>
+
+<ParamField body="client_id" type="str" required>
+  Client ID from your registered OAuth application
+</ParamField>
+
+<ParamField body="client_secret" type="str | None">
+  Client secret from your registered OAuth application. Optional for PKCE public
+  clients. When omitted, `jwt_signing_key` must be provided.
+</ParamField>
+
+<ParamField body="base_url" type="AnyHttpUrl | str" required>
+  Public URL of your FastMCP server (e.g., `https://your-server.com`)
+</ParamField>
+
+<ParamField body="resource_base_url" type="AnyHttpUrl | str | None">
+  Optional public base URL for the protected resource metadata and token audience.
+
+  Use this when your OAuth callbacks and operational endpoints need to live under one public URL, but the protected MCP resource should be advertised under another. FastMCP will still append the MCP mount path (for example, `/mcp`) to this base URL.
+</ParamField>
+
+<ParamField body="strict" type="bool | None">
+  Strict flag for configuration validation. When True, requires all OIDC
+  mandatory fields.
+</ParamField>
+
+<ParamField body="audience" type="str | None">
+  Audience parameter for OIDC providers that require it (e.g., Auth0). This is
+  typically your API identifier.
+</ParamField>
+
+<ParamField body="timeout_seconds" type="int | None" default="10">
+  HTTP request timeout in seconds for fetching OIDC configuration
+</ParamField>
+
+<ParamField body="token_verifier" type="TokenVerifier | None">
+
+<VersionBadge version="2.13.1" />
+  Custom token verifier for validating tokens. When provided, FastMCP uses your custom verifier instead of creating a default `JWTVerifier`.
+
+  Cannot be used with `algorithm` or `required_scopes` parameters - configure these on your verifier instead. The verifier's `required_scopes` are automatically loaded and advertised.
+</ParamField>
+
+<ParamField body="algorithm" type="str | None">
+  JWT algorithm to use for token verification (e.g., "RS256"). If not specified,
+  uses the provider's default. Only used when `token_verifier` is not provided.
+</ParamField>
+
+<ParamField body="required_scopes" type="list[str] | None">
+  List of OAuth scopes for token validation. These are automatically
+  included in authorization requests. Only used when `token_verifier` is not provided.
+</ParamField>
+
+<ParamField body="redirect_path" type="str" default="/auth/callback">
+  Path for OAuth callbacks. Must match the redirect URI configured in your OAuth
+  application
+</ParamField>
+
+<ParamField body="allowed_client_redirect_uris" type="list[str] | None">
+  List of allowed redirect URI patterns for MCP clients. Patterns support wildcards (e.g., `"http://localhost:*"`, `"https://*.example.com/*"`).
+  - `None` (default): DCR clients use registered redirect URIs, with loopback ports allowed to vary for MCP compatibility. Unsafe browser schemes such as `javascript:`, `data:`, `file:`, and `vbscript:` are rejected.
+  - Empty list `[]`: No redirect URIs allowed
+  - Custom list: Only matching patterns allowed
+
+These patterns apply to MCP client loopback redirects. Configure the upstream OAuth app redirect URI separately with `redirect_path`.
+
+</ParamField>
+
+<ParamField body="token_endpoint_auth_method" type="str | None">
+  Token endpoint authentication method for the upstream OAuth server. Controls how the proxy authenticates when exchanging authorization codes and refresh tokens with the upstream provider.
+  - `"client_secret_basic"`: Send credentials in Authorization header (most common)
+  - `"client_secret_post"`: Send credentials in request body (required by some providers)
+  - `"none"`: No authentication (for public clients)
+  - `None` (default): Uses authlib's default (typically `"client_secret_basic"`)
+
+Set this if your provider requires a specific authentication method and the default doesn't work.
+
+</ParamField>
+
+<ParamField body="jwt_signing_key" type="str | bytes | None">
+
+<VersionBadge version="2.13.0" />
+  Secret used to sign FastMCP JWT tokens issued to clients. Accepts any string or bytes - will be derived into a proper 32-byte cryptographic key using HKDF.
+
+  **Default behavior (`None`):**
+  - **Mac/Windows**: Auto-managed via system keyring. Keys are generated once and persisted, surviving server restarts with zero configuration. Keys are automatically derived from server attributes, so this approach, while convenient, is **only** suitable for development and local testing. For production, you must provide an explicit secret.
+  - **Linux**: Ephemeral (random salt at startup). Tokens become invalid on server restart, triggering client re-authentication.
+
+  **For production:**
+  Provide an explicit secret (e.g., from environment variable) to use a fixed key instead of the auto-generated one.
+</ParamField>
+
+<ParamField body="client_storage" type="AsyncKeyValue | None">
+
+<VersionBadge version="2.13.0" />
+  Storage backend for persisting OAuth client registrations and upstream tokens.
+
+  **Default behavior:**
+  - **Mac/Windows**: Encrypted DiskStore in your platform's data directory (derived from `platformdirs`)
+  - **Linux**: MemoryStore (ephemeral - clients lost on restart)
+
+  By default on Mac/Windows, clients are automatically persisted to encrypted disk storage, allowing them to survive server restarts as long as the filesystem remains accessible. This means MCP clients only need to register once and can reconnect seamlessly. On Linux where keyring isn't available, ephemeral storage is used to match the ephemeral key strategy.
+
+For production deployments with multiple servers or cloud deployments, use a network-accessible storage backend rather than local disk storage. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest.** See [Storage Backends](/servers/storage-backends) for available options.
+
+Testing with in-memory storage (unencrypted):
+
+```python
+from key_value.aio.stores.memory import MemoryStore
+
+# Use in-memory storage for testing (clients lost on restart)
+auth = OIDCProxy(..., client_storage=MemoryStore())
+```
+
+Production with encrypted Redis storage:
+
+```python
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+import os
+
+auth = OIDCProxy(
+    ...,
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(host="redis.example.com", port=6379),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+```
+
+</ParamField>
+
+<ParamField body="require_authorization_consent" type='bool | Literal["remember", "external"]' default="True">
+  Consent screen behavior for authorization requests. Accepts `True` (default; always prompt — strongest protection), `"remember"` (silent consent on return visits via signed cookie, gated by `Sec-Fetch-Site` to block AS-in-the-middle attacks), `"external"` (consent handled by upstream IdP or custom page), or `False` (disable entirely; local/testing only). See the [OAuthProxy documentation](/servers/auth/oauth-proxy) for full details on each mode and the security trade-offs.
+</ParamField>
+
+<ParamField body="consent_csp_policy" type="str | None" default="None">
+  Content Security Policy for the consent page.
+
+  - `None` (default): Uses the built-in CSP policy with appropriate directives for form submission
+  - Empty string `""`: Disables CSP entirely (no meta tag rendered)
+  - Custom string: Uses the provided value as the CSP policy
+
+  This is useful for organizations that have their own CSP policies and need to override or disable FastMCP's built-in CSP directives.
+</ParamField>
+</Card>
+
+### Using Built-in Providers
+
+FastMCP includes pre-configured OIDC providers for common services:
+
+```python
+from fastmcp.server.auth.providers.auth0 import Auth0Provider
+
+auth = Auth0Provider(
+    config_url="https://.../.well-known/openid-configuration",
+    client_id="your-auth0-client-id",
+    client_secret="your-auth0-client-secret",
+    audience="https://...",
+    base_url="https://localhost:8000"
+)
+
+mcp = FastMCP(name="My Server", auth=auth)
+```
+
+Available providers include `Auth0Provider` at present.
+
+### Scope Configuration
+
+OAuth scopes are configured with `required_scopes` to automatically request the permissions your application needs.
+
+Dynamic clients created by the proxy will automatically include these scopes in their authorization requests.
+
+## CIMD Support
+
+<VersionBadge version="3.0.0" />
+
+The OIDC proxy inherits full CIMD (Client ID Metadata Document) support from `OAuthProxy`. Clients can use HTTPS URLs as their `client_id` instead of registering dynamically, and the proxy will fetch and validate their metadata document.
+
+See the [OAuth Proxy CIMD documentation](/servers/auth/oauth-proxy#cimd-support) for complete details on how CIMD works, including private key JWT authentication and security considerations.
+
+The CIMD-related parameters available on `OIDCProxy` are:
+
+<Card icon="code" title="CIMD Parameters">
+<ParamField body="enable_cimd" type="bool" default="True">
+  Whether to accept CIMD URLs as client identifiers.
+</ParamField>
+</Card>
+
+## Production Configuration
+
+For production deployments, load sensitive credentials from environment variables:
+
+```python
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.auth0 import Auth0Provider
+
+# Load secrets from environment variables
+auth = Auth0Provider(
+    config_url=os.environ.get("AUTH0_CONFIG_URL"),
+    client_id=os.environ.get("AUTH0_CLIENT_ID"),
+    client_secret=os.environ.get("AUTH0_CLIENT_SECRET"),
+    audience=os.environ.get("AUTH0_AUDIENCE"),
+    base_url=os.environ.get("BASE_URL", "https://localhost:8000")
+)
+
+mcp = FastMCP(name="My Server", auth=auth)
+
+@mcp.tool
+def protected_tool(data: str) -> str:
+    """This tool is now protected by OAuth."""
+    return f"Processed: {data}"
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+
+This keeps secrets out of your codebase while maintaining explicit configuration.
diff --git a/docs/servers/auth/remote-oauth.mdx b/docs/servers/auth/remote-oauth.mdx
new file mode 100644
index 0000000..c2256b0
--- /dev/null
+++ b/docs/servers/auth/remote-oauth.mdx
@@ -0,0 +1,240 @@
+---
+title: Remote OAuth
+sidebarTitle: Remote OAuth
+description: Integrate your FastMCP server with external identity providers like Descope, WorkOS, Auth0, and corporate SSO systems.
+icon: camera-cctv
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.11.0" />
+
+Remote OAuth integration allows your FastMCP server to leverage external identity providers that **support Dynamic Client Registration (DCR)**. With DCR, MCP clients can automatically register themselves with the identity provider and obtain credentials without any manual configuration. This provides enterprise-grade authentication with fully automated flows, making it ideal for production applications with modern identity providers.
+
+<Tip>
+**When to use RemoteAuthProvider vs OAuth Proxy:**
+- **RemoteAuthProvider**: For providers WITH Dynamic Client Registration (Descope, WorkOS AuthKit, modern OIDC providers)
+- **OAuth Proxy**: For providers WITHOUT Dynamic Client Registration (GitHub, Google, Azure, AWS, Discord, etc.)
+
+RemoteAuthProvider requires DCR support for fully automated client registration and authentication.
+</Tip>
+
+## DCR-Enabled Providers
+
+RemoteAuthProvider works with identity providers that support **Dynamic Client Registration (DCR)** - a critical capability that enables automated authentication flows:
+
+| Feature | DCR Providers (RemoteAuth) | Non-DCR Providers (OAuth Proxy) |
+|---------|---------------------------|--------------------------------|
+| **Client Registration** | Automatic via API | Manual in provider console |
+| **Credentials** | Dynamic per client | Fixed app credentials |
+| **Configuration** | Zero client config | Pre-shared credentials |
+| **Examples** | Descope, WorkOS AuthKit, modern OIDC | GitHub, Google, Azure |
+| **FastMCP Class** | `RemoteAuthProvider` | [`OAuthProxy`](/servers/auth/oauth-proxy) |
+
+If your provider doesn't support DCR (most traditional OAuth providers), you'll need to use [`OAuth Proxy`](/servers/auth/oauth-proxy) instead, which bridges the gap between MCP's DCR expectations and fixed OAuth credentials.
+
+## The Remote OAuth Challenge
+
+Traditional OAuth flows assume human users with web browsers who can interact with login forms, consent screens, and redirects. MCP clients operate differently - they're often automated systems that need to authenticate programmatically without human intervention.
+
+This creates several unique requirements that standard OAuth implementations don't address well:
+
+**Automatic Discovery**: MCP clients must discover authentication requirements by examining server metadata rather than encountering HTTP redirects. They need to know which identity provider to use and how to reach it before making any authenticated requests.
+
+**Programmatic Registration**: Clients need to register themselves with identity providers automatically. Manual client registration doesn't work when clients might be dynamically created tools or services.
+
+**Seamless Token Management**: Clients must obtain, store, and refresh tokens without user interaction. The authentication flow needs to work in headless environments where no human is available to complete OAuth consent flows.
+
+**Protocol Integration**: The authentication process must integrate cleanly with MCP's JSON-RPC transport layer and error handling mechanisms.
+
+These requirements mean that your MCP server needs to do more than just validate tokens - it needs to provide discovery metadata that enables MCP clients to understand and navigate your authentication requirements automatically.
+
+## MCP Authentication Discovery
+
+MCP authentication discovery relies on well-known endpoints that clients can examine to understand your authentication requirements. Your server becomes a bridge between MCP clients and your chosen identity provider.
+
+The core discovery endpoint is `/.well-known/oauth-protected-resource`, which tells clients that your server requires OAuth authentication and identifies the authorization servers you trust. This endpoint contains static metadata that points clients to your identity provider without requiring any dynamic lookups.
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant FastMCPServer as FastMCP Server
+    participant ExternalIdP as Identity Provider
+
+    Client->>FastMCPServer: 1. GET /.well-known/oauth-protected-resource
+    FastMCPServer-->>Client: 2. "Use https://my-idp.com for auth"
+    
+    note over Client, ExternalIdP: Client goes directly to the IdP
+    Client->>ExternalIdP: 3. Authenticate & get token via DCR
+    ExternalIdP-->>Client: 4. Access token
+    
+    Client->>FastMCPServer: 5. MCP request with Bearer token
+    FastMCPServer->>FastMCPServer: 6. Verify token signature
+    FastMCPServer-->>Client: 7. MCP response
+```
+
+This flow separates concerns cleanly: your MCP server handles resource protection and token validation, while your identity provider handles user authentication and token issuance. The client coordinates between these systems using standardized OAuth discovery mechanisms.
+
+## FastMCP Remote Authentication
+
+<VersionBadge version="2.11.1" />
+
+FastMCP provides `RemoteAuthProvider` to handle the complexities of remote OAuth integration. This class combines token validation capabilities with the OAuth discovery metadata that MCP clients require.
+
+### RemoteAuthProvider
+
+`RemoteAuthProvider` works by composing a [`TokenVerifier`](/servers/auth/token-verification) with authorization server information. A `TokenVerifier` is another FastMCP authentication class that focuses solely on token validation - signature verification, expiration checking, and claim extraction. The `RemoteAuthProvider` takes that token validation capability and adds the OAuth discovery endpoints that enable MCP clients to automatically find and authenticate with your identity provider.
+
+This composition pattern means you can use any token validation strategy while maintaining consistent OAuth discovery behavior:
+- **JWT tokens**: Use `JWTVerifier` for self-contained tokens
+- **Opaque tokens**: Use `IntrospectionTokenVerifier` for RFC 7662 introspection
+- **Custom validation**: Implement your own `TokenVerifier` subclass
+
+The separation allows you to change token validation approaches without affecting the client discovery experience.
+
+The class automatically generates the required OAuth metadata endpoints using the MCP SDK's standardized route creation functions. This ensures compatibility with MCP clients while reducing the implementation complexity for server developers.
+
+### Basic Implementation
+
+Most applications can use `RemoteAuthProvider` directly without subclassing. The implementation requires a `TokenVerifier` instance, a list of trusted authorization servers, and your server's URL for metadata generation.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import RemoteAuthProvider
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from pydantic import AnyHttpUrl
+
+# Configure token validation for your identity provider
+token_verifier = JWTVerifier(
+    jwks_uri="https://auth.yourcompany.com/.well-known/jwks.json",
+    issuer="https://auth.yourcompany.com",
+    audience="mcp-production-api"
+)
+
+# Create the remote auth provider
+auth = RemoteAuthProvider(
+    token_verifier=token_verifier,
+    authorization_servers=[AnyHttpUrl("https://auth.yourcompany.com")],
+    base_url="https://api.yourcompany.com",  # Your server base URL
+    # Optional: restrict allowed client redirect URIs
+    allowed_client_redirect_uris=["http://localhost:*", "http://127.0.0.1:*"]
+)
+
+mcp = FastMCP(name="Company API", auth=auth)
+```
+
+This configuration creates a server that accepts tokens issued by `auth.yourcompany.com` and provides the OAuth discovery metadata that MCP clients need. The `JWTVerifier` handles token validation using your identity provider's public keys, while the `RemoteAuthProvider` generates the required OAuth endpoints.
+
+The `authorization_servers` list tells MCP clients which identity providers you trust. The `base_url` identifies your server in OAuth metadata, enabling proper token audience validation. **Important**: The `base_url` should point to your server base URL - for example, if your MCP server is accessible at `https://api.yourcompany.com/mcp`, use `https://api.yourcompany.com` as the base URL.
+
+### Overriding Advertised Scopes
+
+Some identity providers use different scope formats for authorization requests versus token claims. For example, Azure AD requires clients to request full URI scopes like `api://client-id/read`, but the token's `scp` claim contains just `read`. The `scopes_supported` parameter lets you advertise the full-form scopes in metadata while validating against the short form:
+
+```python
+auth = RemoteAuthProvider(
+    token_verifier=token_verifier,
+    authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+    base_url="https://api.example.com",
+    scopes_supported=["api://my-api/read", "api://my-api/write"],
+)
+```
+
+When not set, `scopes_supported` defaults to the token verifier's `required_scopes`. For Azure AD specifically, see the [AzureJWTVerifier](/integrations/azure#token-verification-only-managed-identity) which handles this automatically.
+
+### Custom Endpoints
+
+You can extend `RemoteAuthProvider` to add additional endpoints beyond the standard OAuth protected resource metadata. These don't have to be OAuth-specific - you can add any endpoints your authentication integration requires.
+
+```python
+import httpx
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+class CompanyAuthProvider(RemoteAuthProvider):
+    def __init__(self):
+        token_verifier = JWTVerifier(
+            jwks_uri="https://auth.yourcompany.com/.well-known/jwks.json",
+            issuer="https://auth.yourcompany.com",
+            audience="mcp-production-api"
+        )
+        
+        super().__init__(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.yourcompany.com")],
+            base_url="https://api.yourcompany.com"  # Your server base URL
+        )
+    
+    def get_routes(self) -> list[Route]:
+        """Add custom endpoints to the standard protected resource routes."""
+        
+        # Get the standard OAuth protected resource routes
+        routes = super().get_routes()
+        
+        # Add authorization server metadata forwarding for client convenience
+        async def authorization_server_metadata(request):
+            async with httpx.AsyncClient() as client:
+                response = await client.get(
+                    "https://auth.yourcompany.com/.well-known/oauth-authorization-server"
+                )
+                response.raise_for_status()
+                return JSONResponse(response.json())
+        
+        routes.append(
+            Route("/.well-known/oauth-authorization-server", authorization_server_metadata)
+        )
+        
+        return routes
+
+mcp = FastMCP(name="Company API", auth=CompanyAuthProvider())
+```
+
+This pattern uses `super().get_routes()` to get the standard protected resource routes, then adds additional endpoints as needed. A common use case is providing authorization server metadata forwarding, which allows MCP clients to discover your identity provider's capabilities through your MCP server rather than contacting the identity provider directly.
+
+## WorkOS AuthKit Integration
+
+WorkOS AuthKit provides an excellent example of remote OAuth integration. The `AuthKitProvider` demonstrates how to implement both token validation and OAuth metadata forwarding in a production-ready package.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.workos import AuthKitProvider
+
+auth = AuthKitProvider(
+    authkit_domain="https://your-project.authkit.app",
+    base_url="https://your-mcp-server.com"
+)
+
+mcp = FastMCP(name="Protected Application", auth=auth)
+```
+
+The `AuthKitProvider` automatically configures JWT validation against WorkOS's public keys and provides both protected resource metadata and authorization server metadata forwarding. This implementation handles the complete remote OAuth integration with minimal configuration.
+
+WorkOS's support for Dynamic Client Registration makes it particularly well-suited for MCP applications. Clients can automatically register themselves with your WorkOS project and obtain the credentials needed for authentication without manual intervention.
+
+→ **Complete WorkOS tutorial**: [AuthKit Integration Guide](/integrations/authkit)
+
+## Client Redirect URI Security
+
+<Note>
+`RemoteAuthProvider` also supports the `allowed_client_redirect_uris` parameter for controlling which redirect URIs are accepted from MCP clients during DCR:
+
+- `None` (default): Broad DCR-compatible redirect support, while rejecting unsafe browser schemes such as `javascript:`, `data:`, `file:`, and `vbscript:`
+- Custom list: Specify allowed patterns with wildcard support
+- Empty list `[]`: No redirect URIs allowed
+
+This provides defense-in-depth even though DCR providers typically validate redirect URIs themselves.
+</Note>
+
+## Implementation Considerations
+
+Remote OAuth integration requires careful attention to several technical details that affect reliability and security.
+
+**Token Validation Performance**: Your server validates every incoming token by checking signatures against your identity provider's public keys. Consider implementing key caching and rotation handling to minimize latency while maintaining security.
+
+**Error Handling**: Network issues with your identity provider can affect token validation. Implement appropriate timeouts, retry logic, and graceful degradation to maintain service availability during identity provider outages.
+
+**Audience Validation**: Ensure that tokens intended for your server are not accepted by other applications. Proper audience validation prevents token misuse across different services in your ecosystem.
+
+**Scope Management**: Map token scopes to your application's permission model consistently. Consider how scope changes affect existing tokens and plan for smooth permission updates.
+
+The complexity of these considerations reinforces why external identity providers are recommended over custom OAuth implementations. Established providers handle these technical details with extensive testing and operational experience.
diff --git a/docs/servers/auth/token-verification.mdx b/docs/servers/auth/token-verification.mdx
new file mode 100644
index 0000000..7e38d9a
--- /dev/null
+++ b/docs/servers/auth/token-verification.mdx
@@ -0,0 +1,428 @@
+---
+title: Token Verification
+sidebarTitle: Token Verification
+description: Protect your server by validating bearer tokens issued by external systems.
+icon: key
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.11.0" />
+
+Token verification enables your FastMCP server to validate bearer tokens issued by external systems without participating in user authentication flows. Your server acts as a pure resource server, focusing on token validation and authorization decisions while delegating identity management to other systems in your infrastructure.
+
+<Note>
+Token verification operates somewhat outside the formal MCP authentication flow, which expects OAuth-style discovery. It's best suited for internal systems, microservices architectures, or when you have full control over token generation and distribution.
+</Note>
+
+## Understanding Token Verification
+
+Token verification addresses scenarios where authentication responsibility is distributed across multiple systems. Your MCP server receives structured tokens containing identity and authorization information, validates their authenticity, and makes access control decisions based on their contents.
+
+This pattern emerges naturally in microservices architectures where a central authentication service issues tokens that multiple downstream services validate independently. It also works well when integrating MCP servers into existing systems that already have established token-based authentication mechanisms.
+
+### The Token Verification Model
+
+Token verification treats your MCP server as a resource server in OAuth terminology. The key insight is that token validation and token issuance are separate concerns that can be handled by different systems.
+
+**Token Issuance**: Another system (API gateway, authentication service, or identity provider) handles user authentication and creates signed tokens containing identity and permission information.
+
+**Token Validation**: Your MCP server receives these tokens, verifies their authenticity using cryptographic signatures, and extracts authorization information from their claims.
+
+**Access Control**: Based on token contents, your server determines what resources, tools, and prompts the client can access.
+
+This separation allows your MCP server to focus on its core functionality while leveraging existing authentication infrastructure. The token acts as a portable proof of identity that travels with each request.
+
+### Token Security Considerations
+
+Token-based authentication relies on cryptographic signatures to ensure token integrity. Your MCP server validates tokens using public keys corresponding to the private keys used for token creation. This asymmetric approach means your server never needs access to signing secrets.
+
+Token validation must address several security requirements: signature verification ensures tokens haven't been tampered with, expiration checking prevents use of stale tokens, and audience validation ensures tokens intended for your server aren't accepted by other systems.
+
+The challenge in MCP environments is that clients need to obtain valid tokens before making requests, but the MCP protocol doesn't provide built-in discovery mechanisms for token endpoints. Clients must obtain tokens through separate channels or prior configuration.
+
+On the streamable-HTTP transport, each session is additionally bound to the credential that created it: a request that presents a different credential for an existing `Mcp-Session-Id` is rejected with a 404, exactly as if the session did not exist. A leaked session id is therefore useless without the original credential. Session identity is the `(client_id, issuer, subject)` triple your verifier populates.
+
+
+## TokenVerifier Class
+
+FastMCP provides the `TokenVerifier` class to handle token validation complexity while remaining flexible about token sources and validation strategies.
+
+`TokenVerifier` focuses exclusively on token validation without providing OAuth discovery metadata. This makes it ideal for internal systems where clients already know how to obtain tokens, or for microservices that trust tokens from known issuers.
+
+The class validates token signatures, checks expiration timestamps, and extracts authorization information from token claims. It supports various token formats and validation strategies while maintaining a consistent interface for authorization decisions.
+
+You can subclass `TokenVerifier` to implement custom validation logic for specialized token formats or validation requirements. The base class handles common patterns while allowing extension for unique use cases.
+
+## JWT Token Verification
+
+JSON Web Tokens (JWTs) represent the most common token format for modern applications. FastMCP's `JWTVerifier` validates JWTs using industry-standard cryptographic techniques and claim validation.
+
+### JWKS Endpoint Integration
+
+JWKS endpoint integration provides the most flexible approach for production systems. The verifier automatically fetches public keys from a JSON Web Key Set endpoint, enabling automatic key rotation without server configuration changes.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+# Configure JWT verification against your identity provider
+verifier = JWTVerifier(
+    jwks_uri="https://auth.yourcompany.com/.well-known/jwks.json",
+    issuer="https://auth.yourcompany.com",
+    audience="mcp-production-api"
+)
+
+mcp = FastMCP(name="Protected API", auth=verifier)
+```
+
+This configuration creates a server that validates JWTs issued by `auth.yourcompany.com`. The verifier periodically fetches public keys from the JWKS endpoint and validates incoming tokens against those keys. Only tokens with the correct issuer and audience claims will be accepted.
+
+The `issuer` parameter ensures tokens come from your trusted authentication system, while `audience` validation prevents tokens intended for other services from being accepted by your MCP server.
+
+### Symmetric Key Verification (HMAC)
+
+Symmetric key verification uses a shared secret for both signing and validation, making it ideal for internal microservices and trusted environments where the same secret can be securely distributed to both token issuers and validators.
+
+This approach is commonly used in microservices architectures where services share a secret key, or when your authentication service and MCP server are both managed by the same organization. The HMAC algorithms (HS256, HS384, HS512) provide strong security when the shared secret is properly managed.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+# Use a shared secret for symmetric key verification
+verifier = JWTVerifier(
+    public_key="your-shared-secret-key-minimum-32-chars",  # Despite the name, this accepts symmetric secrets
+    issuer="internal-auth-service",
+    audience="mcp-internal-api",
+    algorithm="HS256"  # or HS384, HS512 for stronger security
+)
+
+mcp = FastMCP(name="Internal API", auth=verifier)
+```
+
+The verifier will validate tokens signed with the same secret using the specified HMAC algorithm. This approach offers several advantages for internal systems:
+
+- **Simplicity**: No key pair management or certificate distribution
+- **Performance**: HMAC operations are typically faster than RSA
+- **Compatibility**: Works well with existing microservice authentication patterns
+
+<Note>
+The parameter is named `public_key` for backwards compatibility, but when using HMAC algorithms (HS256/384/512), it accepts the symmetric secret string.
+</Note>
+
+<Warning>
+**Security Considerations for Symmetric Keys:**
+- Use a strong, randomly generated secret (minimum 32 characters recommended)
+- Never expose the secret in logs, error messages, or version control
+- Implement secure key distribution and rotation mechanisms
+- Consider using asymmetric keys (RSA/ECDSA) for external-facing APIs
+</Warning>
+
+### Static Public Key Verification
+
+Static public key verification works when you have a fixed RSA or ECDSA signing key and don't need automatic key rotation. This approach is primarily useful for development environments or controlled deployments where JWKS endpoints aren't available.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+# Use a static public key for token verification
+public_key_pem = """-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
+-----END PUBLIC KEY-----"""
+
+verifier = JWTVerifier(
+    public_key=public_key_pem,
+    issuer="https://auth.yourcompany.com",
+    audience="mcp-production-api"
+)
+
+mcp = FastMCP(name="Protected API", auth=verifier)
+```
+
+This configuration validates tokens using a specific RSA or ECDSA public key. The key must correspond to the private key used by your token issuer. While less flexible than JWKS endpoints, this approach can be useful in development environments or when testing with fixed keys.
+## Opaque Token Verification
+
+Many authorization servers issue opaque tokens rather than self-contained JWTs. Opaque tokens are random strings that carry no information themselves - the authorization server maintains their state and validation requires querying the server. FastMCP supports opaque token validation through OAuth 2.0 Token Introspection (RFC 7662).
+
+### Understanding Opaque Tokens
+
+Opaque tokens differ fundamentally from JWTs in their verification model. Where JWTs carry signed claims that can be validated locally, opaque tokens require network calls to the issuing authorization server for validation. The authorization server maintains token state and can revoke tokens immediately, providing stronger security guarantees for sensitive operations.
+
+This approach trades performance (network latency on each validation) for security and flexibility. Authorization servers can revoke opaque tokens instantly, implement complex authorization logic, and maintain detailed audit logs of token usage. Many enterprise OAuth providers default to opaque tokens for these security advantages.
+
+### Token Introspection Protocol
+
+RFC 7662 standardizes how resource servers validate opaque tokens. The protocol defines an introspection endpoint where resource servers authenticate using client credentials and receive token metadata including active status, scopes, expiration, and subject identity.
+
+FastMCP implements this protocol through the `IntrospectionTokenVerifier` class, handling authentication, request formatting, and response parsing according to the specification.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.introspection import IntrospectionTokenVerifier
+
+# Configure introspection with your OAuth provider
+verifier = IntrospectionTokenVerifier(
+    introspection_url="https://auth.yourcompany.com/oauth/introspect",
+    client_id="mcp-resource-server",
+    client_secret="your-client-secret",
+    required_scopes=["api:read", "api:write"]
+)
+
+mcp = FastMCP(name="Protected API", auth=verifier)
+```
+
+The verifier authenticates to the introspection endpoint using client credentials and queries it whenever a bearer token arrives. FastMCP checks whether the token is active and has sufficient scopes before allowing access.
+
+Two standard client authentication methods are supported, both defined in RFC 6749:
+
+- **`client_secret_basic`** (default): Sends credentials via HTTP Basic Auth header
+- **`client_secret_post`**: Sends credentials in the POST request body
+
+Most OAuth providers support both methods, though some may require one specifically. Configure the authentication method with the `client_auth_method` parameter:
+
+```python
+# Use POST body authentication instead of Basic Auth
+verifier = IntrospectionTokenVerifier(
+    introspection_url="https://auth.yourcompany.com/oauth/introspect",
+    client_id="mcp-resource-server",
+    client_secret="your-client-secret",
+    client_auth_method="client_secret_post",
+    required_scopes=["api:read", "api:write"]
+)
+```
+
+## Development and Testing
+
+Development environments often need simpler token management without the complexity of full JWT infrastructure. FastMCP provides tools specifically designed for these scenarios.
+
+### Static Token Verification
+
+Static token verification enables rapid development by accepting predefined tokens with associated claims. This approach eliminates the need for token generation infrastructure during development and testing.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.jwt import StaticTokenVerifier
+
+# Define development tokens and their associated claims
+verifier = StaticTokenVerifier(
+    tokens={
+        "dev-alice-token": {
+            "client_id": "alice@company.com",
+            "scopes": ["read:data", "write:data", "admin:users"]
+        },
+        "dev-guest-token": {
+            "client_id": "guest-user",
+            "scopes": ["read:data"]
+        }
+    },
+    required_scopes=["read:data"]
+)
+
+mcp = FastMCP(name="Development Server", auth=verifier)
+```
+
+Clients can now authenticate using `Authorization: Bearer dev-alice-token` headers. The server will recognize the token and load the associated claims for authorization decisions. This approach enables immediate development without external dependencies.
+
+<Warning>
+Static token verification stores tokens as plain text and should never be used in production environments. It's designed exclusively for development and testing scenarios.
+</Warning>
+
+
+### Debug/Custom Token Verification
+
+<VersionBadge version="2.13.1" />
+
+The `DebugTokenVerifier` provides maximum flexibility for testing and special cases where standard token verification isn't applicable. It delegates validation to a user-provided callable, making it useful for prototyping, testing scenarios, or handling opaque tokens without introspection endpoints.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.debug import DebugTokenVerifier
+
+# Accept all tokens (useful for rapid development)
+verifier = DebugTokenVerifier()
+
+mcp = FastMCP(name="Development Server", auth=verifier)
+```
+
+By default, `DebugTokenVerifier` accepts any non-empty token as valid. This eliminates authentication barriers during early development, allowing you to focus on core functionality before adding security.
+
+For more controlled testing, provide custom validation logic:
+
+```python
+from fastmcp.server.auth.providers.debug import DebugTokenVerifier
+
+# Synchronous validation - check token prefix
+verifier = DebugTokenVerifier(
+    validate=lambda token: token.startswith("dev-"),
+    client_id="development-client",
+    scopes=["read", "write"]
+)
+
+mcp = FastMCP(name="Development Server", auth=verifier)
+```
+
+The validation callable can also be async, enabling database lookups or external service calls:
+
+```python
+from fastmcp.server.auth.providers.debug import DebugTokenVerifier
+
+# Asynchronous validation - check against cache
+async def validate_token(token: str) -> bool:
+    # Check if token exists in Redis, database, etc.
+    return await redis.exists(f"valid_tokens:{token}")
+
+verifier = DebugTokenVerifier(
+    validate=validate_token,
+    client_id="api-client",
+    scopes=["api:access"]
+)
+
+mcp = FastMCP(name="Custom API", auth=verifier)
+```
+
+**Use Cases:**
+
+- **Testing**: Accept any token during integration tests without setting up token infrastructure
+- **Prototyping**: Quickly validate concepts without authentication complexity
+- **Opaque tokens without introspection**: When you have tokens from an IDP that provides no introspection endpoint, and you're willing to accept tokens without validation (validation happens later at the upstream service)
+- **Custom token formats**: Implement validation for non-standard token formats or legacy systems
+
+<Warning>
+`DebugTokenVerifier` bypasses standard security checks. Only use in controlled environments (development, testing) or when you fully understand the security implications. For production, use proper JWT or introspection-based verification.
+</Warning>
+
+### Test Token Generation
+
+Test token generation helps when you need to test JWT verification without setting up complete identity infrastructure. FastMCP includes utilities for generating test key pairs and signed tokens.
+
+```python
+from fastmcp.server.auth.providers.jwt import JWTVerifier, RSAKeyPair
+
+# Generate a key pair for testing
+key_pair = RSAKeyPair.generate()
+
+# Configure your server with the public key
+verifier = JWTVerifier(
+    public_key=key_pair.public_key,
+    issuer="https://test.yourcompany.com",
+    audience="test-mcp-server"
+)
+
+# Generate a test token using the private key
+test_token = key_pair.create_token(
+    subject="test-user-123",
+    issuer="https://test.yourcompany.com", 
+    audience="test-mcp-server",
+    scopes=["read", "write", "admin"]
+)
+
+print(f"Test token: {test_token}")
+```
+
+This pattern enables comprehensive testing of JWT validation logic without depending on external token issuers. The generated tokens are cryptographically valid and will pass all standard JWT validation checks.
+
+## HTTP Client Customization
+
+<VersionBadge version="2.18.0" />
+
+All token verifiers that make HTTP calls accept an optional `http_client` parameter. This lets you provide your own `httpx.AsyncClient` for connection pooling, custom TLS configuration, or proxy settings.
+
+### Connection Pooling
+
+By default, each token verification call creates a fresh HTTP client. Under high load, this means repeated TCP connections and TLS handshakes. Providing a shared client enables connection pooling across calls:
+
+```python
+import httpx
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.introspection import IntrospectionTokenVerifier
+
+# Create a shared client with connection pooling
+http_client = httpx.AsyncClient(
+    timeout=10,
+    limits=httpx.Limits(max_connections=20, max_keepalive_connections=10),
+)
+
+verifier = IntrospectionTokenVerifier(
+    introspection_url="https://auth.yourcompany.com/oauth/introspect",
+    client_id="mcp-resource-server",
+    client_secret="your-client-secret",
+    http_client=http_client,
+)
+
+mcp = FastMCP(name="Protected API", auth=verifier)
+```
+
+The same pattern works for `JWTVerifier` when using JWKS endpoints:
+
+```python
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+verifier = JWTVerifier(
+    jwks_uri="https://auth.yourcompany.com/.well-known/jwks.json",
+    issuer="https://auth.yourcompany.com",
+    http_client=http_client,
+)
+```
+
+<Warning>
+`JWTVerifier` does not support `http_client` when `ssrf_safe=True`. SSRF-safe mode requires a hardened transport that validates DNS resolution and connection targets, which cannot be guaranteed with a user-provided client. Attempting to use both will raise a `ValueError`.
+</Warning>
+
+<Note>
+When you provide an `http_client`, you are responsible for its lifecycle. The verifier will not close it. Use the server's `lifespan` to manage client cleanup:
+
+```python
+from contextlib import asynccontextmanager
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.introspection import IntrospectionTokenVerifier
+
+http_client = httpx.AsyncClient(timeout=10)
+
+verifier = IntrospectionTokenVerifier(
+    introspection_url="https://auth.example.com/introspect",
+    client_id="my-service",
+    client_secret="secret",
+    http_client=http_client,
+)
+
+@asynccontextmanager
+async def lifespan(app):
+    yield
+    await http_client.aclose()
+
+mcp = FastMCP(name="My API", auth=verifier, lifespan=lifespan)
+```
+</Note>
+
+The convenience providers (`GitHubProvider`, `GoogleProvider`, `DiscordProvider`, `WorkOSProvider`, `AzureProvider`) also accept `http_client` and pass it through to their internal token verifier.
+
+## Production Configuration
+
+For production deployments, load sensitive configuration from environment variables:
+
+```python
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+# Load configuration from environment variables
+# Parse comma-separated scopes if provided
+scopes_env = os.environ.get("JWT_REQUIRED_SCOPES")
+required_scopes = scopes_env.split(",") if scopes_env else None
+
+verifier = JWTVerifier(
+    jwks_uri=os.environ.get("JWT_JWKS_URI"),
+    issuer=os.environ.get("JWT_ISSUER"),
+    audience=os.environ.get("JWT_AUDIENCE"),
+    required_scopes=required_scopes,
+)
+
+mcp = FastMCP(name="Production API", auth=verifier)
+```
+
+This keeps configuration out of your codebase while maintaining explicit setup.
+
+This approach enables the same codebase to run across development, staging, and production environments with different authentication requirements. Development might use static tokens while production uses JWT verification, all controlled through environment configuration.
+
diff --git a/docs/servers/authorization.mdx b/docs/servers/authorization.mdx
new file mode 100644
index 0000000..a48d2a9
--- /dev/null
+++ b/docs/servers/authorization.mdx
@@ -0,0 +1,384 @@
+---
+title: Authorization
+sidebarTitle: Authorization
+description: Control access to components using callable-based authorization checks that filter visibility and enforce permissions.
+icon: shield-halved
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="3.0.0" />
+
+Authorization controls what authenticated users can do with your FastMCP server. While [authentication](/servers/auth/authentication) verifies identity (who you are), authorization determines access (what you can do). FastMCP provides a callable-based authorization system that works at both the component level and globally via middleware.
+
+The authorization model centers on a simple concept: callable functions that receive context about the current request and return `True` to allow access or `False` to deny it. Multiple checks combine with AND logic, meaning all checks must pass for access to be granted.
+
+<Note>
+Authorization relies on OAuth tokens which are only available with HTTP transports (SSE, Streamable HTTP). In STDIO mode, there's no OAuth mechanism, so `get_access_token()` returns `None` and all auth checks are skipped.
+</Note>
+
+<Note>
+When an `AuthProvider` is configured, all requests to the MCP endpoint must carry a valid token—unauthenticated requests are rejected at the transport level before any auth checks run. Authorization checks therefore differentiate between authenticated users based on their scopes and claims, not between authenticated and unauthenticated users.
+</Note>
+
+## Auth Checks
+
+An auth check is any callable that accepts an `AuthContext` and returns a boolean. Auth checks can be synchronous or asynchronous, so checks that need to perform async operations (like reading server state or calling external services) work naturally.
+
+```python
+from fastmcp.server.auth import AuthContext
+
+def my_custom_check(ctx: AuthContext) -> bool:
+    # ctx.token is AccessToken | None
+    # ctx.component is the Tool, Resource, or Prompt being accessed
+    return ctx.token is not None and "special" in ctx.token.scopes
+```
+
+FastMCP provides two built-in auth checks that cover common authorization patterns.
+
+### require_scopes
+
+Scope-based authorization checks that the token contains all specified OAuth scopes. When multiple scopes are provided, all must be present (AND logic).
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import require_scopes
+
+mcp = FastMCP("Scoped Server")
+
+@mcp.tool(auth=require_scopes("admin"))
+def admin_operation() -> str:
+    """Requires the 'admin' scope."""
+    return "Admin action completed"
+
+@mcp.tool(auth=require_scopes("read", "write"))
+def read_write_operation() -> str:
+    """Requires both 'read' AND 'write' scopes."""
+    return "Read/write action completed"
+```
+
+### restrict_tag
+
+Tag-based restrictions apply scope requirements conditionally. If a component has the specified tag, the token must have the required scopes. Components without the tag are unaffected.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import restrict_tag
+from fastmcp.server.middleware import AuthMiddleware
+
+mcp = FastMCP(
+    "Tagged Server",
+    middleware=[
+        AuthMiddleware(auth=restrict_tag("admin", scopes=["admin"]))
+    ]
+)
+
+@mcp.tool(tags={"admin"})
+def admin_tool() -> str:
+    """Tagged 'admin', so requires 'admin' scope."""
+    return "Admin only"
+
+@mcp.tool(tags={"public"})
+def public_tool() -> str:
+    """Not tagged 'admin', so no scope required by the restriction."""
+    return "Anyone can access"
+```
+
+### Combining Checks
+
+Multiple auth checks can be combined by passing a list. All checks must pass for authorization to succeed (AND logic).
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import require_scopes
+
+mcp = FastMCP("Combined Auth Server")
+
+@mcp.tool(auth=[require_scopes("admin"), require_scopes("write")])
+def secure_admin_action() -> str:
+    """Requires both 'admin' AND 'write' scopes."""
+    return "Secure admin action"
+```
+
+### Custom Auth Checks
+
+Any callable that accepts `AuthContext` and returns `bool` can serve as an auth check. This enables authorization logic based on token claims, component metadata, or external systems.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import AuthContext
+
+mcp = FastMCP("Custom Auth Server")
+
+def require_premium_user(ctx: AuthContext) -> bool:
+    """Check for premium user status in token claims."""
+    if ctx.token is None:
+        return False
+    return ctx.token.claims.get("premium", False) is True
+
+def require_access_level(minimum_level: int):
+    """Factory function for level-based authorization."""
+    def check(ctx: AuthContext) -> bool:
+        if ctx.token is None:
+            return False
+        user_level = ctx.token.claims.get("level", 0)
+        return user_level >= minimum_level
+    return check
+
+@mcp.tool(auth=require_premium_user)
+def premium_feature() -> str:
+    """Only for premium users."""
+    return "Premium content"
+
+@mcp.tool(auth=require_access_level(5))
+def advanced_feature() -> str:
+    """Requires access level 5 or higher."""
+    return "Advanced feature"
+```
+
+### Async Auth Checks
+
+Auth checks can be `async` functions, which is useful when the authorization decision depends on asynchronous operations like reading server state or querying external services.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import AuthContext
+
+mcp = FastMCP("Async Auth Server")
+
+async def check_user_permissions(ctx: AuthContext) -> bool:
+    """Async auth check that reads server state."""
+    if ctx.token is None:
+        return False
+    user_id = ctx.token.claims.get("sub")
+    # Async operations work naturally in auth checks
+    permissions = await fetch_user_permissions(user_id)
+    return "admin" in permissions
+
+@mcp.tool(auth=check_user_permissions)
+def admin_tool() -> str:
+    return "Admin action completed"
+```
+
+Sync and async checks can be freely combined in a list — each check is handled according to its type.
+
+### Error Handling
+
+Auth checks can raise exceptions for explicit denial with custom messages:
+
+- **`AuthorizationError`**: Propagates with its custom message, useful for explaining why access was denied
+- **Other exceptions**: Masked for security (logged internally, treated as denial)
+
+```python
+from fastmcp.server.auth import AuthContext
+from fastmcp.exceptions import AuthorizationError
+
+def require_verified_email(ctx: AuthContext) -> bool:
+    """Require verified email with explicit denial message."""
+    if ctx.token is None:
+        raise AuthorizationError("Authentication required")
+    if not ctx.token.claims.get("email_verified"):
+        raise AuthorizationError("Email verification required")
+    return True
+```
+
+## Component-Level Authorization
+
+The `auth` parameter on decorators controls visibility and access for individual components. When auth checks fail for the current request, the component is hidden from list responses and direct access returns not-found.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import require_scopes
+
+mcp = FastMCP("Component Auth Server")
+
+@mcp.tool(auth=require_scopes("write"))
+def write_tool() -> str:
+    """Only visible to users with 'write' scope."""
+    return "Written"
+
+@mcp.resource("secret://data", auth=require_scopes("read"))
+def secret_resource() -> str:
+    """Only visible to users with 'read' scope."""
+    return "Secret data"
+
+@mcp.prompt(auth=require_scopes("admin"))
+def admin_prompt() -> str:
+    """Only visible to users with 'admin' scope."""
+    return "Admin prompt content"
+```
+
+<Note>
+Component-level `auth` controls both visibility (list filtering) and access (direct lookups return not-found for unauthorized requests). Additionally use `AuthMiddleware` to apply server-wide authorization rules and get explicit `AuthorizationError` responses on unauthorized execution attempts.
+</Note>
+
+## Server-Level Authorization
+
+For server-wide authorization enforcement, use `AuthMiddleware`. This middleware applies auth checks globally to all components—filtering list responses and blocking unauthorized execution with explicit `AuthorizationError` responses.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import require_scopes
+from fastmcp.server.middleware import AuthMiddleware
+
+mcp = FastMCP(
+    "Enforced Auth Server",
+    middleware=[AuthMiddleware(auth=require_scopes("api"))]
+)
+
+@mcp.tool
+def any_tool() -> str:
+    """Requires 'api' scope to see AND call."""
+    return "Protected"
+```
+
+### Component Auth + Middleware
+
+Component-level `auth` and `AuthMiddleware` work together as complementary layers. The middleware applies server-wide rules to all components, while component-level auth adds per-component requirements. Both layers are checked—all checks must pass.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import require_scopes, restrict_tag
+from fastmcp.server.middleware import AuthMiddleware
+
+mcp = FastMCP(
+    "Layered Auth Server",
+    middleware=[
+        AuthMiddleware(auth=restrict_tag("admin", scopes=["admin"]))
+    ]
+)
+
+# Requires "write" scope (component-level)
+# Also requires "admin" scope if tagged "admin" (middleware-level)
+@mcp.tool(auth=require_scopes("write"), tags={"admin"})
+def admin_write() -> str:
+    """Requires both 'write' AND 'admin' scopes."""
+    return "Admin write"
+
+# Requires "write" scope (component-level only)
+@mcp.tool(auth=require_scopes("write"))
+def user_write() -> str:
+    """Requires 'write' scope."""
+    return "User write"
+```
+
+### Tag-Based Global Authorization
+
+A common pattern uses `restrict_tag` with `AuthMiddleware` to apply scope requirements based on component tags.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import restrict_tag
+from fastmcp.server.middleware import AuthMiddleware
+
+mcp = FastMCP(
+    "Tag-Based Auth Server",
+    middleware=[
+        AuthMiddleware(auth=restrict_tag("admin", scopes=["admin"])),
+        AuthMiddleware(auth=restrict_tag("write", scopes=["write"])),
+    ]
+)
+
+@mcp.tool(tags={"admin"})
+def delete_all_data() -> str:
+    """Requires 'admin' scope."""
+    return "Deleted"
+
+@mcp.tool(tags={"write"})
+def update_record(id: str, data: str) -> str:
+    """Requires 'write' scope."""
+    return f"Updated {id}"
+
+@mcp.tool
+def read_record(id: str) -> str:
+    """No tag restrictions, accessible to all."""
+    return f"Record {id}"
+```
+
+## Accessing Tokens in Tools
+
+Tools can access the current authentication token using `get_access_token()` from `fastmcp.server.dependencies`. This enables tools to make decisions based on user identity or permissions beyond simple authorization checks.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.dependencies import get_access_token
+
+mcp = FastMCP("Token Access Server")
+
+@mcp.tool
+def personalized_greeting() -> str:
+    """Greet the user based on their token claims."""
+    token = get_access_token()
+
+    if token is None:
+        return "Hello, guest!"
+
+    name = token.claims.get("name", "user")
+    return f"Hello, {name}!"
+
+@mcp.tool
+def user_dashboard() -> dict:
+    """Return user-specific data based on token."""
+    token = get_access_token()
+
+    if token is None:
+        return {"error": "Not authenticated"}
+
+    return {
+        "client_id": token.client_id,
+        "scopes": token.scopes,
+        "claims": token.claims,
+    }
+```
+
+## Reference
+
+### AccessToken
+
+The `AccessToken` object contains information extracted from the OAuth token.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `token` | `str` | The raw token string |
+| `client_id` | `str \| None` | OAuth client identifier |
+| `scopes` | `list[str]` | Granted OAuth scopes |
+| `expires_at` | `datetime \| None` | Token expiration time |
+| `claims` | `dict[str, Any]` | All JWT claims or custom token data |
+
+### AuthContext
+
+The `AuthContext` dataclass is passed to all auth check functions.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `token` | `AccessToken \| None` | Current access token, or `None` if unauthenticated |
+| `component` | `Tool \| Resource \| Prompt` | The component being accessed |
+
+Access to the component object enables authorization decisions based on metadata like tags, name, or custom properties.
+
+```python
+from fastmcp.server.auth import AuthContext
+
+def require_matching_tag(ctx: AuthContext) -> bool:
+    """Require a scope matching each of the component's tags."""
+    if ctx.token is None:
+        return False
+    user_scopes = set(ctx.token.scopes)
+    return ctx.component.tags.issubset(user_scopes)
+```
+
+### Imports
+
+```python
+from fastmcp.server.auth import (
+    AccessToken,       # Token with .token, .client_id, .scopes, .expires_at, .claims
+    AuthContext,       # Context with .token, .component
+    AuthCheck,         # Type alias: sync or async Callable[[AuthContext], bool]
+    require_scopes,    # Built-in: requires specific scopes
+    restrict_tag,      # Built-in: tag-based scope requirements
+    run_auth_checks,   # Utility: run checks with AND logic
+)
+
+from fastmcp.server.middleware import AuthMiddleware
+```
diff --git a/docs/servers/composition.mdx b/docs/servers/composition.mdx
new file mode 100644
index 0000000..42523a5
--- /dev/null
+++ b/docs/servers/composition.mdx
@@ -0,0 +1,237 @@
+---
+title: Composing Servers
+sidebarTitle: Composition
+description: Combine multiple servers into one
+icon: puzzle-piece
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.2.0" />
+
+As your application grows, you'll want to split it into focused servers — one for weather, one for calendar, one for admin — and combine them into a single server that clients connect to. That's what `mount()` does.
+
+When you mount a server, all its tools, resources, and prompts become available through the parent. The connection is live: add a tool to the child after mounting, and it's immediately visible through the parent.
+
+```python
+from fastmcp import FastMCP
+
+weather = FastMCP("Weather")
+
+@weather.tool
+def get_forecast(city: str) -> str:
+    """Get weather forecast for a city."""
+    return f"Sunny in {city}"
+
+@weather.resource("data://cities")
+def list_cities() -> list[str]:
+    """List supported cities."""
+    return ["London", "Paris", "Tokyo"]
+
+main = FastMCP("MainApp")
+main.mount(weather)
+
+# main now serves get_forecast and data://cities
+```
+
+## Mounting External Servers
+
+Mount remote HTTP servers or subprocess-based MCP servers using `create_proxy()`:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server import create_proxy
+
+mcp = FastMCP("Orchestrator")
+
+# Mount a remote HTTP server (URLs work directly)
+mcp.mount(create_proxy("http://api.example.com/mcp"), namespace="api")
+
+# Mount local Python scripts (file paths work directly)
+mcp.mount(create_proxy("./my_server.py"), namespace="local")
+```
+
+### Mounting npm/uvx Packages
+
+For npm packages or Python tools, use the config dict format:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server import create_proxy
+
+mcp = FastMCP("Orchestrator")
+
+# Mount npm package via config
+github_config = {
+    "mcpServers": {
+        "default": {
+            "command": "npx",
+            "args": ["-y", "@modelcontextprotocol/server-github"]
+        }
+    }
+}
+mcp.mount(create_proxy(github_config), namespace="github")
+
+# Mount Python tool via config
+sqlite_config = {
+    "mcpServers": {
+        "default": {
+            "command": "uvx",
+            "args": ["mcp-server-sqlite", "--db", "data.db"]
+        }
+    }
+}
+mcp.mount(create_proxy(sqlite_config), namespace="db")
+```
+
+Or use explicit transport classes:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server import create_proxy
+from fastmcp.client.transports import NpxStdioTransport, UvxStdioTransport
+
+mcp = FastMCP("Orchestrator")
+
+mcp.mount(
+    create_proxy(NpxStdioTransport(package="@modelcontextprotocol/server-github")),
+    namespace="github"
+)
+mcp.mount(
+    create_proxy(UvxStdioTransport(tool_name="mcp-server-sqlite", tool_args=["--db", "data.db"])),
+    namespace="db"
+)
+```
+
+For advanced configuration, see [Proxying](/servers/providers/proxy).
+
+## Namespacing
+
+<VersionBadge version="3.0.0" />
+
+When mounting multiple servers, use namespaces to avoid naming conflicts:
+
+```python
+weather = FastMCP("Weather")
+calendar = FastMCP("Calendar")
+
+@weather.tool
+def get_data() -> str:
+    return "Weather data"
+
+@calendar.tool
+def get_data() -> str:
+    return "Calendar data"
+
+main = FastMCP("Main")
+main.mount(weather, namespace="weather")
+main.mount(calendar, namespace="calendar")
+
+# Tools are now:
+# - weather_get_data
+# - calendar_get_data
+```
+
+### How Namespacing Works
+
+| Component Type | Without Namespace | With `namespace="api"` |
+|----------------|-------------------|------------------------|
+| Tool | `my_tool` | `api_my_tool` |
+| Prompt | `my_prompt` | `api_my_prompt` |
+| Resource | `data://info` | `data://api/info` |
+| Template | `data://{id}` | `data://api/{id}` |
+
+Namespacing uses [transforms](/servers/transforms/transforms) under the hood.
+
+## Dynamic Composition
+
+Because `mount()` creates a live link, you can add components to a child server after mounting and they'll be immediately available through the parent:
+
+```python
+main = FastMCP("Main")
+main.mount(dynamic_server, namespace="dynamic")
+
+# Add a tool AFTER mounting - it's accessible through main
+@dynamic_server.tool
+def added_later() -> str:
+    return "Added after mounting!"
+```
+
+## Tag Filtering
+
+<VersionBadge version="3.0.0" />
+
+Parent server tag filters apply recursively to mounted servers:
+
+```python
+api_server = FastMCP("API")
+
+@api_server.tool(tags={"production"})
+def prod_endpoint() -> str:
+    return "Production data"
+
+@api_server.tool(tags={"development"})
+def dev_endpoint() -> str:
+    return "Debug data"
+
+# Mount with production filter
+prod_app = FastMCP("Production")
+prod_app.mount(api_server, namespace="api")
+prod_app.enable(tags={"production"}, only=True)
+
+# Only prod_endpoint (namespaced as api_prod_endpoint) is visible
+```
+
+## Performance Considerations
+
+Operations like `list_tools()` on the parent are affected by the performance of all mounted servers. This is particularly noticeable with:
+
+- HTTP-based mounted servers (300-400ms vs 1-2ms for local tools)
+- Mounted servers with slow initialization
+- Deep mounting hierarchies
+
+If low latency is critical, consider implementing caching strategies or limiting mounting depth.
+
+## Custom Routes
+
+<VersionBadge version="2.4.0" />
+
+Custom HTTP routes defined with `@server.custom_route()` are also forwarded when mounting:
+
+```python
+subserver = FastMCP("Sub")
+
+@subserver.custom_route("/health", methods=["GET"])
+async def health_check():
+    return {"status": "ok"}
+
+main = FastMCP("Main")
+main.mount(subserver, namespace="sub")
+
+# /health is now accessible through main's HTTP app
+```
+
+## Conflict Resolution
+
+<VersionBadge version="3.0.0" />
+
+When mounting multiple servers with the same namespace (or no namespace), the **most recently mounted** server takes precedence for conflicting component names:
+
+```python
+server_a = FastMCP("A")
+server_b = FastMCP("B")
+
+@server_a.tool
+def shared_tool() -> str:
+    return "From A"
+
+@server_b.tool
+def shared_tool() -> str:
+    return "From B"
+
+main = FastMCP("Main")
+main.mount(server_a)
+main.mount(server_b)
+
+# shared_tool returns "From B" (most recently mounted)
+```
diff --git a/docs/servers/context.mdx b/docs/servers/context.mdx
new file mode 100644
index 0000000..ecd9e67
--- /dev/null
+++ b/docs/servers/context.mdx
@@ -0,0 +1,480 @@
+---
+title: MCP Context
+sidebarTitle: Context
+description: Access MCP capabilities like logging, progress, and resources within your MCP objects.
+icon: rectangle-code
+tag: NEW
+---
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+When defining FastMCP [tools](/servers/tools), [resources](/servers/resources), resource templates, or [prompts](/servers/prompts), your functions might need to interact with the underlying MCP session or access advanced server capabilities. FastMCP provides the `Context` object for this purpose.
+
+<Note>
+You access Context through FastMCP's dependency injection system. For other injectable values like HTTP requests, access tokens, and custom dependencies, see [Dependency Injection](/servers/dependency-injection).
+</Note>
+
+## What Is Context?
+
+The `Context` object provides a clean interface to access MCP features within your functions, including:
+
+- **Logging**: Send debug, info, warning, and error messages back to the client
+- **Progress Reporting**: Update the client on the progress of long-running operations
+- **Resource Access**: List and read data from resources registered with the server
+- **Prompt Access**: List and retrieve prompts registered with the server
+- **LLM Sampling**: Request the client's LLM to generate text based on provided messages
+- **User Elicitation**: Request structured input from users during tool execution
+- **Session State**: Store data that persists across requests within an MCP session
+- **Session Visibility**: [Control which components are visible](/servers/visibility#per-session-visibility) to the current session
+- **Request Information**: Access metadata about the current request
+- **Server Access**: When needed, access the underlying FastMCP server instance
+
+## Accessing the Context
+
+<VersionBadge version="2.14" />
+
+The preferred way to access context is using the `CurrentContext()` dependency:
+
+```python {1, 6}
+from fastmcp import FastMCP
+from fastmcp.dependencies import CurrentContext
+from fastmcp.server.context import Context
+
+mcp = FastMCP(name="Context Demo")
+
+@mcp.tool
+async def process_file(file_uri: str, ctx: Context = CurrentContext()) -> str:
+    """Processes a file, using context for logging and resource access."""
+    await ctx.info(f"Processing {file_uri}")
+    return "Processed file"
+```
+
+This works with tools, resources, and prompts:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.dependencies import CurrentContext
+from fastmcp.server.context import Context
+
+mcp = FastMCP(name="Context Demo")
+
+@mcp.resource("resource://user-data")
+async def get_user_data(ctx: Context = CurrentContext()) -> dict:
+    await ctx.debug("Fetching user data")
+    return {"user_id": "example"}
+
+@mcp.prompt
+async def data_analysis_request(dataset: str, ctx: Context = CurrentContext()) -> str:
+    return f"Please analyze the following dataset: {dataset}"
+```
+
+**Key Points:**
+
+- Dependency parameters are automatically excluded from the MCP schema—clients never see them.
+- Context methods are async, so your function usually needs to be async as well.
+- **Each MCP request receives a new context object.** Context is scoped to a single request; state or data set in one request will not be available in subsequent requests.
+- Context is only available during a request; attempting to use context methods outside a request will raise errors.
+
+### Legacy Type-Hint Injection
+
+For backwards compatibility, you can still access context by simply adding a parameter with the `Context` type hint. FastMCP will automatically inject the context instance:
+
+```python {1, 6}
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP(name="Context Demo")
+
+@mcp.tool
+async def process_file(file_uri: str, ctx: Context) -> str:
+    """Processes a file, using context for logging and resource access."""
+    # Context is injected automatically based on the type hint
+    return "Processed file"
+```
+
+This approach still works for tools, resources, and prompts. The parameter name doesn't matter—only the `Context` type hint is important. The type hint can also be a union (`Context | None`) or use `Annotated[]`.
+
+### Via `get_context()` Function
+
+<VersionBadge version="2.2.11" />
+
+For code nested deeper within your function calls where passing context through parameters is inconvenient, use `get_context()` to retrieve the active context from anywhere within a request's execution flow:
+
+```python {2,9}
+from fastmcp import FastMCP
+from fastmcp.server.dependencies import get_context
+
+mcp = FastMCP(name="Dependency Demo")
+
+# Utility function that needs context but doesn't receive it as a parameter
+async def process_data(data: list[float]) -> dict:
+    # Get the active context - only works when called within a request
+    ctx = get_context()
+    await ctx.info(f"Processing {len(data)} data points")
+
+@mcp.tool
+async def analyze_dataset(dataset_name: str) -> dict:
+    # Call utility function that uses context internally
+    data = load_data(dataset_name)
+    await process_data(data)
+```
+
+**Important Notes:**
+
+- The `get_context()` function should only be used within the context of a server request. Calling it outside of a request will raise a `RuntimeError`.
+- The `get_context()` function is server-only and should not be used in client code.
+
+## Context Capabilities
+
+FastMCP provides several advanced capabilities through the context object. Each capability has dedicated documentation with comprehensive examples and best practices:
+
+### Logging
+
+Send debug, info, warning, and error messages back to the MCP client for visibility into function execution.
+
+```python
+await ctx.debug("Starting analysis")
+await ctx.info(f"Processing {len(data)} items") 
+await ctx.warning("Deprecated parameter used")
+await ctx.error("Processing failed")
+```
+
+See [Server Logging](/servers/logging) for complete documentation and examples.
+### Client Elicitation
+
+<VersionBadge version="2.10.0" />
+
+Request structured input from clients during tool execution, enabling interactive workflows and progressive disclosure. This is a new feature in the 6/18/2025 MCP spec.
+
+```python
+result = await ctx.elicit("Enter your name:", response_type=str)
+if result.action == "accept":
+    name = result.data
+```
+
+See [User Elicitation](/servers/elicitation) for detailed examples and supported response types.
+
+### LLM Sampling
+
+<VersionBadge version="2.0.0" />
+
+Request the client's LLM to generate text based on provided messages, useful for leveraging AI capabilities within your tools.
+
+```python
+response = await ctx.sample("Analyze this data", temperature=0.7)
+```
+
+See [LLM Sampling](/servers/sampling) for comprehensive usage and advanced techniques.
+
+
+### Progress Reporting
+
+Update clients on the progress of long-running operations, enabling progress indicators and better user experience.
+
+```python
+await ctx.report_progress(progress=50, total=100)  # 50% complete
+```
+
+See [Progress Reporting](/servers/progress) for detailed patterns and examples.
+
+### Resource Access
+
+List and read data from resources registered with your FastMCP server, allowing access to files, configuration, or dynamic content.
+
+```python
+# List available resources
+resources = await ctx.list_resources()
+
+# Read a specific resource
+content_list = await ctx.read_resource("resource://config")
+content = content_list[0].content
+```
+
+**Method signatures:**
+- **`ctx.list_resources() -> list[MCPResource]`**: <VersionBadge version="2.13.0" /> Returns list of all available resources
+- **`ctx.read_resource(uri: str | AnyUrl) -> list[ReadResourceContents]`**: Returns a list of resource content parts
+
+### Prompt Access
+
+<VersionBadge version="2.13.0" />
+
+List and retrieve prompts registered with your FastMCP server, allowing tools and middleware to discover and use available prompts programmatically.
+
+```python
+# List available prompts
+prompts = await ctx.list_prompts()
+
+# Get a specific prompt with arguments
+result = await ctx.get_prompt("analyze_data", {"dataset": "users"})
+messages = result.messages
+```
+
+**Method signatures:**
+- **`ctx.list_prompts() -> list[MCPPrompt]`**: Returns list of all available prompts
+- **`ctx.get_prompt(name: str, arguments: dict[str, Any] | None = None) -> GetPromptResult`**: Get a specific prompt with optional arguments
+
+### Session State
+
+<VersionBadge version="3.0.0" />
+
+Store data that persists across multiple requests within the same MCP session. Session state is automatically keyed by the client's session, ensuring isolation between different clients.
+
+```python
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP("stateful-app")
+
+@mcp.tool
+async def increment_counter(ctx: Context) -> int:
+    """Increment a counter that persists across tool calls."""
+    count = await ctx.get_state("counter") or 0
+    await ctx.set_state("counter", count + 1)
+    return count + 1
+
+@mcp.tool
+async def get_counter(ctx: Context) -> int:
+    """Get the current counter value."""
+    return await ctx.get_state("counter") or 0
+```
+
+Each client session has its own isolated state—two different clients calling `increment_counter` will each have their own counter.
+
+**Method signatures:**
+- **`await ctx.set_state(key, value, *, serializable=True)`**: Store a value in session state
+- **`await ctx.get_state(key)`**: Retrieve a value (returns None if not found)
+- **`await ctx.delete_state(key)`**: Remove a value from session state
+
+<Note>
+State methods are async and require `await`. State expires after 1 day to prevent unbounded memory growth.
+</Note>
+
+#### Non-Serializable Values
+
+By default, state values must be JSON-serializable (dicts, lists, strings, numbers, etc.) so they can be persisted across requests. For non-serializable values like HTTP clients or database connections, pass `serializable=False`:
+
+```python
+@mcp.tool
+async def my_tool(ctx: Context) -> str:
+    # This object can't be JSON-serialized
+    client = SomeHTTPClient(base_url="https://api.example.com")
+    await ctx.set_state("client", client, serializable=False)
+
+    # Retrieve it later in the same request
+    client = await ctx.get_state("client")
+    return await client.fetch("/data")
+```
+
+Values stored with `serializable=False` only live for the current MCP request (a single tool call, resource read, or prompt render). They will not be available in subsequent requests within the session.
+
+#### Custom Storage Backends
+
+By default, session state uses an in-memory store suitable for single-server deployments. For distributed or serverless deployments, provide a custom storage backend:
+
+```python
+from key_value.aio.stores.redis import RedisStore
+
+# Use Redis for distributed state
+mcp = FastMCP("distributed-app", session_state_store=RedisStore(...))
+```
+
+Any backend compatible with the [py-key-value-aio](https://github.com/strawgate/py-key-value) `AsyncKeyValue` protocol works. See [Storage Backends](/servers/storage-backends) for more options including Redis, DynamoDB, and MongoDB.
+
+#### State and Mounted Servers
+
+Each `FastMCP` instance has its own session state store. When you `mount()` a child server, state set on the parent is not visible to tools on the child, and vice versa:
+
+```python
+from fastmcp import FastMCP, Context
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+parent = FastMCP("Parent")
+child = FastMCP("Child")
+parent.mount(child, namespace="child")
+
+class Stasher(Middleware):
+    async def on_call_tool(self, context: MiddlewareContext, call_next):
+        await context.fastmcp_context.set_state("user", "alice")
+        return await call_next(context)
+
+parent.add_middleware(Stasher())
+
+@child.tool
+async def whoami(ctx: Context) -> str:
+    return await ctx.get_state("user") or "unknown"  # returns "unknown"
+```
+
+To share state across the mount boundary, pass the same store to both servers:
+
+```python
+from key_value.aio.stores.memory import MemoryStore
+
+store = MemoryStore()
+parent = FastMCP("Parent", session_state_store=store)
+child = FastMCP("Child", session_state_store=store)
+parent.mount(child, namespace="child")
+```
+
+Alternatively, state set with `serializable=False` lives on the request context and is inherited by mounted children automatically — use it when the value is request-scoped and does not need to persist across tool calls.
+
+#### State During Initialization
+
+State set during `on_initialize` middleware persists to subsequent tool calls when using the same session object (STDIO, SSE, single-server HTTP). For distributed/serverless HTTP deployments where different machines handle init and tool calls, state is isolated by the `mcp-session-id` header.
+
+### Session Visibility
+
+<VersionBadge version="3.0.0" />
+
+Tools can customize which components are visible to their current session using `ctx.enable_components()`, `ctx.disable_components()`, and `ctx.reset_visibility()`. These methods apply visibility rules that affect only the calling session, leaving other sessions unchanged. See [Per-Session Visibility](/servers/visibility#per-session-visibility) for complete documentation, filter criteria, and patterns like namespace activation.
+
+### Change Notifications
+
+<VersionBadge version="3.0.0" />
+
+FastMCP automatically sends list change notifications when components (such as tools, resources, or prompts) are added, removed, enabled, or disabled. In rare cases where you need to manually trigger these notifications, you can use the context's notification methods:
+
+```python
+import mcp_types
+
+@mcp.tool
+async def custom_tool_management(ctx: Context) -> str:
+    """Example of manual notification after custom tool changes."""
+    await ctx.send_notification(mcp_types.ToolListChangedNotification())
+    await ctx.send_notification(mcp_types.ResourceListChangedNotification())
+    await ctx.send_notification(mcp_types.PromptListChangedNotification())
+    return "Notifications sent"
+```
+
+These methods are primarily used internally by FastMCP's automatic notification system and most users will not need to invoke them directly.
+
+### FastMCP Server
+
+To access the underlying FastMCP server instance, you can use the `ctx.fastmcp` property:
+
+```python
+@mcp.tool
+async def my_tool(ctx: Context) -> None:
+    # Access the FastMCP server instance
+    server_name = ctx.fastmcp.name
+    ...
+```
+
+### Transport
+
+<VersionBadge version="3.0.0" />
+
+The `ctx.transport` property indicates which transport is being used to run the server. This is useful when your tool needs to behave differently depending on whether the server is running over STDIO, SSE, or Streamable HTTP. For example, you might want to return shorter responses over STDIO or adjust timeout behavior based on transport characteristics.
+
+The transport type is set once when the server starts and remains constant for the server's lifetime. It returns `None` when called outside of a server context (for example, in unit tests or when running code outside of an MCP request).
+
+```python
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP("example")
+
+@mcp.tool
+def connection_info(ctx: Context) -> str:
+    if ctx.transport == "stdio":
+        return "Connected via STDIO"
+    elif ctx.transport == "sse":
+        return "Connected via SSE"
+    elif ctx.transport == "streamable-http":
+        return "Connected via Streamable HTTP"
+    else:
+        return "Transport unknown"
+```
+
+**Property signature:** `ctx.transport -> Literal["stdio", "sse", "streamable-http"] | None`
+
+### MCP Request
+
+Access metadata about the current request and client.
+
+```python
+@mcp.tool
+async def request_info(ctx: Context) -> dict:
+    """Return information about the current request."""
+    return {
+        "request_id": ctx.request_id,
+        "client_id": ctx.client_id or "Unknown client"
+    }
+```
+
+**Available Properties:**
+
+- **`ctx.request_id -> str`**: Get the unique ID for the current MCP request
+- **`ctx.client_id -> str | None`**: Get the ID of the client making the request, if provided during initialization
+- **`ctx.session_id -> str`**: Get the MCP session ID for session-based data sharing. Raises `RuntimeError` if the MCP session is not yet established.
+
+#### Request Context Availability
+
+<VersionBadge version="2.13.1" />
+
+The `ctx.request_context` property provides access to the underlying MCP request context, but returns `None` when the MCP session has not been established yet. This typically occurs:
+
+- During middleware execution in the `on_request` hook before the MCP handshake completes
+- During the initialization phase of client connections
+
+The MCP request context is distinct from the HTTP request. For HTTP transports, HTTP request data may be available even when the MCP session is not yet established.
+
+To safely access the request context in situations where it may not be available:
+
+```python
+from fastmcp import FastMCP, Context
+from fastmcp.server.dependencies import get_http_request
+
+mcp = FastMCP(name="Session Aware Demo")
+
+@mcp.tool
+async def session_info(ctx: Context) -> dict:
+    """Return session information when available."""
+
+    # Check if MCP session is available
+    if ctx.request_context:
+        # MCP session available - can access MCP-specific attributes
+        return {
+            "session_id": ctx.session_id,
+            "request_id": ctx.request_id,
+            "has_meta": ctx.request_context.meta is not None
+        }
+    else:
+        # MCP session not available - use HTTP helpers for request data (if using HTTP transport)
+        request = get_http_request()
+        return {
+            "message": "MCP session not available",
+            "user_agent": request.headers.get("user-agent", "Unknown")
+        }
+```
+
+For HTTP request access that works regardless of MCP session availability (when using HTTP transports), use the [HTTP request helpers](/servers/dependency-injection#http-request) like `get_http_request()` and `get_http_headers()`.
+
+#### Client Metadata
+
+<VersionBadge version="2.13.1" />
+
+Clients can send contextual information with their requests using the `meta` parameter. This metadata is accessible through `ctx.request_context.meta` and is available for all MCP operations (tools, resources, prompts).
+
+The `meta` field is `None` when clients don't provide metadata. When provided, metadata is accessible via attribute access (e.g., `meta.user_id`) rather than dictionary access. The structure of metadata is determined by the client making the request.
+
+```python
+@mcp.tool
+def send_email(to: str, subject: str, body: str, ctx: Context) -> str:
+    """Send an email, logging metadata about the request."""
+
+    # Access client-provided metadata
+    meta = ctx.request_context.meta
+
+    if meta:
+        # Meta is accessed as an object with attribute access
+        user_id = meta.user_id if hasattr(meta, 'user_id') else None
+        trace_id = meta.trace_id if hasattr(meta, 'trace_id') else None
+
+        # Use metadata for logging, observability, etc.
+        if trace_id:
+            log_with_trace(f"Sending email for user {user_id}", trace_id)
+
+    # Send the email...
+    return f"Email sent to {to}"
+```
+
+<Warning>
+The MCP request is part of the low-level MCP SDK and intended for advanced use cases. Most users will not need to use it directly.
+</Warning>
+
diff --git a/docs/servers/dependency-injection.mdx b/docs/servers/dependency-injection.mdx
new file mode 100644
index 0000000..40fc7b6
--- /dev/null
+++ b/docs/servers/dependency-injection.mdx
@@ -0,0 +1,433 @@
+---
+title: Dependency Injection
+sidebarTitle: Dependencies
+description: Inject runtime values like HTTP requests, access tokens, and custom dependencies into your MCP components.
+icon: syringe
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+FastMCP uses dependency injection to provide runtime values to your tools, resources, and prompts. Instead of passing context through every layer of your code, you declare what you need as parameter defaults—FastMCP resolves them automatically when your function runs.
+
+The dependency injection system is powered by [Docket](https://github.com/chrisguidry/docket) and its dependency system [uncalled-for](https://github.com/chrisguidry/uncalled-for). Core DI features like `Depends()` and `CurrentContext()` work without installing Docket. For background tasks and advanced task-related dependencies, install `fastmcp[tasks]`. For comprehensive coverage of dependency patterns, see the [Docket dependency documentation](https://docket.lol/en/latest/dependency-injection/).
+
+<Note>
+Dependency parameters are automatically excluded from the MCP schema—clients never see them as callable parameters. This separation keeps your function signatures clean while giving you access to the runtime context you need.
+</Note>
+
+## How Dependency Injection Works
+
+Dependency injection in FastMCP follows a simple pattern: declare a parameter with a recognized type annotation or a dependency default value, and FastMCP injects the resolved value at runtime.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.context import Context
+
+mcp = FastMCP("Demo")
+
+
+@mcp.tool
+async def my_tool(query: str, ctx: Context) -> str:
+    await ctx.info(f"Processing: {query}")
+    return f"Results for: {query}"
+```
+
+When a client calls `my_tool`, they only see `query` as a parameter. The `ctx` parameter is injected automatically because it has a `Context` type annotation—FastMCP recognizes this and provides the active context for the request.
+
+This works identically for tools, resources, resource templates, and prompts.
+
+### Explicit Dependencies with CurrentContext
+
+For more explicit code, you can use `CurrentContext()` as a default value instead of relying on the type annotation:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.dependencies import CurrentContext
+from fastmcp.server.context import Context
+
+mcp = FastMCP("Demo")
+
+
+@mcp.tool
+async def my_tool(query: str, ctx: Context = CurrentContext()) -> str:
+    await ctx.info(f"Processing: {query}")
+    return f"Results for: {query}"
+```
+
+Both approaches work identically. The type-annotation approach is more concise; the explicit `CurrentContext()` approach makes the dependency injection visible in the signature.
+
+## Built-in Dependencies
+
+### MCP Context
+
+The MCP Context provides logging, progress reporting, resource access, and other request-scoped operations. See [MCP Context](/servers/context) for the full API.
+
+**Dependency injection:** Use a `Context` type annotation (FastMCP injects automatically) or `CurrentContext()`:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.context import Context
+
+mcp = FastMCP("Demo")
+
+
+@mcp.tool
+async def process_data(data: str, ctx: Context) -> str:
+    await ctx.info(f"Processing: {data}")
+    return "Done"
+
+
+# Or explicitly with CurrentContext()
+from fastmcp.dependencies import CurrentContext
+
+@mcp.tool
+async def process_data(data: str, ctx: Context = CurrentContext()) -> str:
+    ...
+```
+
+**Function:** Use `get_context()` in helper functions or middleware:
+
+```python
+from fastmcp.server.dependencies import get_context
+
+async def log_something(message: str):
+    ctx = get_context()
+    await ctx.info(message)
+```
+
+### Server Instance
+
+<VersionBadge version="2.14" />
+
+Access the FastMCP server instance for introspection or server-level configuration.
+
+**Dependency injection:** Use `CurrentFastMCP()`:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.dependencies import CurrentFastMCP
+
+mcp = FastMCP("Demo")
+
+
+@mcp.tool
+async def server_info(server: FastMCP = CurrentFastMCP()) -> str:
+    return f"Server: {server.name}"
+```
+
+**Function:** Use `get_server()`:
+
+```python
+from fastmcp.server.dependencies import get_server
+
+def get_server_name() -> str:
+    return get_server().name
+```
+
+### HTTP Request
+
+<VersionBadge version="2.2.11" />
+
+Access the Starlette Request when running over HTTP transports (SSE or Streamable HTTP).
+
+**Dependency injection:** Use `CurrentRequest()`:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.dependencies import CurrentRequest
+from starlette.requests import Request
+
+mcp = FastMCP("Demo")
+
+
+@mcp.tool
+async def client_info(request: Request = CurrentRequest()) -> dict:
+    return {
+        "user_agent": request.headers.get("user-agent", "Unknown"),
+        "client_ip": request.client.host if request.client else "Unknown",
+    }
+```
+
+**Function:** Use `get_http_request()`:
+
+```python
+from fastmcp.server.dependencies import get_http_request
+
+def get_client_ip() -> str:
+    request = get_http_request()
+    return request.client.host if request.client else "Unknown"
+```
+
+<Note>
+Both raise `RuntimeError` when called outside an HTTP context (e.g., STDIO transport).
+For background tasks created from an HTTP request, FastMCP restores a minimal request
+backed by the originating request's snapshotted headers. Use HTTP Headers if you need
+graceful fallback.
+</Note>
+
+### HTTP Headers
+
+<VersionBadge version="2.2.11" />
+
+Access HTTP headers with graceful fallback. When a background task originates from an
+HTTP request, FastMCP restores the originating headers inside the worker. When no HTTP
+request is available, this returns an empty dictionary, making it safe for code that
+might run over any transport.
+
+**Dependency injection:** Use `CurrentHeaders()`:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.dependencies import CurrentHeaders
+
+mcp = FastMCP("Demo")
+
+
+@mcp.tool
+async def get_auth_type(headers: dict = CurrentHeaders()) -> str:
+    auth = headers.get("authorization", "")
+    return "Bearer" if auth.startswith("Bearer ") else "None"
+```
+
+**Function:** Use `get_http_headers()`:
+
+```python
+from fastmcp.server.dependencies import get_http_headers
+
+def get_user_agent() -> str:
+    headers = get_http_headers()
+    return headers.get("user-agent", "Unknown")
+```
+
+By default, problematic headers like `host` and `content-length` are excluded. Use `get_http_headers(include_all=True)` to include all headers.
+
+### Access Token
+
+<VersionBadge version="2.11.0" />
+
+Access the authenticated user's token when your server uses authentication.
+
+**Dependency injection:** Use `CurrentAccessToken()` (raises if not authenticated):
+
+```python
+from fastmcp import FastMCP
+from fastmcp.dependencies import CurrentAccessToken
+from fastmcp.server.auth import AccessToken
+
+mcp = FastMCP("Demo")
+
+
+@mcp.tool
+async def get_user_id(token: AccessToken = CurrentAccessToken()) -> str:
+    return token.claims.get("sub", "unknown")
+```
+
+**Function:** Use `get_access_token()` (returns `None` if not authenticated):
+
+```python
+from fastmcp.server.dependencies import get_access_token
+
+@mcp.tool
+async def get_user_info() -> dict:
+    token = get_access_token()
+    if token is None:
+        return {"authenticated": False}
+    return {"authenticated": True, "user": token.claims.get("sub")}
+```
+
+The `AccessToken` object provides:
+
+- **`client_id`**: The OAuth client identifier
+- **`scopes`**: List of granted permission scopes
+- **`expires_at`**: Token expiration timestamp (if available)
+- **`claims`**: Dictionary of all token claims (JWT claims or provider-specific data)
+
+### Token Claims
+
+When you need just one specific value from the token—like a user ID or tenant identifier—`TokenClaim()` extracts it directly without needing the full token object.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.dependencies import TokenClaim
+
+mcp = FastMCP("Demo")
+
+
+@mcp.tool
+async def add_expense(
+    amount: float,
+    user_id: str = TokenClaim("oid"),  # Azure object ID
+) -> dict:
+    await db.insert({"user_id": user_id, "amount": amount})
+    return {"status": "created", "user_id": user_id}
+```
+
+`TokenClaim()` raises a `RuntimeError` if the claim doesn't exist, listing available claims to help with debugging.
+
+Common claims vary by identity provider:
+
+| Provider | User ID Claim | Email Claim | Name Claim |
+|----------|--------------|-------------|------------|
+| Azure/Entra | `oid` | `email` | `name` |
+| GitHub | `sub` | `email` | `name` |
+| Google | `sub` | `email` | `name` |
+| Auth0 | `sub` | `email` | `name` |
+
+### Background Task Dependencies
+
+<VersionBadge version="2.3.0" />
+
+For background task execution, FastMCP provides dependencies that integrate with [Docket](https://github.com/chrisguidry/docket). These require installing `fastmcp[tasks]`.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.dependencies import CurrentDocket, CurrentWorker, Progress
+
+mcp = FastMCP("Task Demo")
+
+
+@mcp.tool(task=True)
+async def long_running_task(
+    data: str,
+    docket=CurrentDocket(),
+    worker=CurrentWorker(),
+    progress=Progress(),
+) -> str:
+    await progress.set_total(100)
+
+    for i in range(100):
+        # Process chunk...
+        await progress.increment()
+        await progress.set_message(f"Processing chunk {i + 1}")
+
+    return "Complete"
+```
+
+- **`CurrentDocket()`**: Access the Docket instance for scheduling additional background work
+- **`CurrentWorker()`**: Access the worker processing tasks (name, concurrency settings)
+- **`Progress()`**: Track task progress with atomic updates
+
+<Note>
+Task dependencies require `pip install 'fastmcp[tasks]'`. They're only available within task-enabled components (`task=True`). For comprehensive task patterns, see the [Docket documentation](https://chrisguidry.github.io/docket/dependencies/).
+</Note>
+
+## Custom Dependencies
+
+Beyond the built-in dependencies, you can create your own to inject configuration, database connections, API clients, or any other values your functions need.
+
+### Using Depends()
+
+The `Depends()` function wraps any callable and injects its return value. This works with synchronous functions, async functions, and async context managers.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.dependencies import Depends
+
+mcp = FastMCP("Custom Deps Demo")
+
+
+def get_config() -> dict:
+    return {"api_url": "https://api.example.com", "timeout": 30}
+
+
+async def get_user_id() -> int:
+    # Could fetch from database, external service, etc.
+    return 42
+
+
+@mcp.tool
+async def fetch_data(
+    query: str,
+    config: dict = Depends(get_config),
+    user_id: int = Depends(get_user_id),
+) -> str:
+    return f"User {user_id} fetching '{query}' from {config['api_url']}"
+```
+
+### Caching
+
+Dependencies are cached per-request. If multiple parameters use the same dependency, or if nested dependencies share a common dependency, it's resolved once and the same instance is reused.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.dependencies import Depends
+
+mcp = FastMCP("Caching Demo")
+
+
+def get_db_connection():
+    print("Connecting to database...")  # Only printed once per request
+    return {"connection": "active"}
+
+
+def get_user_repo(db=Depends(get_db_connection)):
+    return {"db": db, "type": "user"}
+
+
+def get_order_repo(db=Depends(get_db_connection)):
+    return {"db": db, "type": "order"}
+
+
+@mcp.tool
+async def process_order(
+    order_id: str,
+    users=Depends(get_user_repo),
+    orders=Depends(get_order_repo),
+) -> str:
+    # Both repos share the same db connection
+    return f"Processed order {order_id}"
+```
+
+### Resource Management
+
+For dependencies that need cleanup—database connections, file handles, HTTP clients—use an async context manager. The cleanup code runs after your function completes, even if an error occurs.
+
+```python
+from contextlib import asynccontextmanager
+
+from fastmcp import FastMCP
+from fastmcp.dependencies import Depends
+
+mcp = FastMCP("Resource Demo")
+
+
+@asynccontextmanager
+async def get_database():
+    db = await connect_to_database()
+    try:
+        yield db
+    finally:
+        await db.close()
+
+
+@mcp.tool
+async def query_users(sql: str, db=Depends(get_database)) -> list:
+    return await db.execute(sql)
+```
+
+### Nested Dependencies
+
+Dependencies can depend on other dependencies. FastMCP resolves them in the correct order and applies caching across the dependency tree.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.dependencies import Depends
+
+mcp = FastMCP("Nested Demo")
+
+
+def get_base_url() -> str:
+    return "https://api.example.com"
+
+
+def get_api_client(base_url: str = Depends(get_base_url)) -> dict:
+    return {"base_url": base_url, "version": "v1"}
+
+
+@mcp.tool
+async def call_api(endpoint: str, client: dict = Depends(get_api_client)) -> str:
+    return f"Calling {client['base_url']}/{client['version']}/{endpoint}"
+```
+
+For advanced dependency patterns—like `TaskArgument()` for accessing task parameters, or custom `Dependency` subclasses—see the [Docket dependency documentation](https://chrisguidry.github.io/docket/dependencies/).
diff --git a/docs/servers/elicitation.mdx b/docs/servers/elicitation.mdx
new file mode 100644
index 0000000..923e704
--- /dev/null
+++ b/docs/servers/elicitation.mdx
@@ -0,0 +1,379 @@
+---
+title: User Elicitation
+sidebarTitle: Elicitation
+description: Request structured input from users during tool execution through the MCP context.
+icon: message-question
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.10.0" />
+
+User elicitation allows MCP servers to request structured input from users during tool execution. Instead of requiring all inputs upfront, tools can interactively ask for missing parameters, clarification, or additional context as needed.
+
+Elicitation enables tools to pause execution and request specific information from users:
+
+- **Missing parameters**: Ask for required information not provided initially
+- **Clarification requests**: Get user confirmation or choices for ambiguous scenarios
+- **Progressive disclosure**: Collect complex information step-by-step
+- **Dynamic workflows**: Adapt tool behavior based on user responses
+
+For example, a file management tool might ask "Which directory should I create?" or a data analysis tool might request "What date range should I analyze?"
+
+## Overview
+
+Use the `ctx.elicit()` method within any tool function to request user input. Specify the message to display and the type of response you expect.
+
+```python
+from fastmcp import FastMCP, Context
+from dataclasses import dataclass
+
+mcp = FastMCP("Elicitation Server")
+
+@dataclass
+class UserInfo:
+    name: str
+    age: int
+
+@mcp.tool
+async def collect_user_info(ctx: Context) -> str:
+    """Collect user information through interactive prompts."""
+    result = await ctx.elicit(
+        message="Please provide your information",
+        response_type=UserInfo
+    )
+
+    if result.action == "accept":
+        user = result.data
+        return f"Hello {user.name}, you are {user.age} years old"
+    elif result.action == "decline":
+        return "Information not provided"
+    else:  # cancel
+        return "Operation cancelled"
+```
+
+The elicitation result contains an `action` field indicating how the user responded:
+
+| Action | Description |
+|--------|-------------|
+| `accept` | User provided valid input—data is available in the `data` field |
+| `decline` | User chose not to provide the requested information |
+| `cancel` | User cancelled the entire operation |
+
+FastMCP also provides typed result classes for pattern matching:
+
+```python
+from fastmcp.server.elicitation import (
+    AcceptedElicitation,
+    DeclinedElicitation,
+    CancelledElicitation,
+)
+
+@mcp.tool
+async def pattern_example(ctx: Context) -> str:
+    result = await ctx.elicit("Enter your name:", response_type=str)
+
+    match result:
+        case AcceptedElicitation(data=name):
+            return f"Hello {name}!"
+        case DeclinedElicitation():
+            return "No name provided"
+        case CancelledElicitation():
+            return "Operation cancelled"
+```
+
+### Multi-Turn Elicitation
+
+Tools can make multiple elicitation calls to gather information progressively:
+
+```python
+@mcp.tool
+async def plan_meeting(ctx: Context) -> str:
+    """Plan a meeting by gathering details step by step."""
+
+    title_result = await ctx.elicit("What's the meeting title?", response_type=str)
+    if title_result.action != "accept":
+        return "Meeting planning cancelled"
+
+    duration_result = await ctx.elicit("Duration in minutes?", response_type=int)
+    if duration_result.action != "accept":
+        return "Meeting planning cancelled"
+
+    priority_result = await ctx.elicit(
+        "Is this urgent?",
+        response_type=["yes", "no"]
+    )
+    if priority_result.action != "accept":
+        return "Meeting planning cancelled"
+
+    urgent = priority_result.data == "yes"
+    return f"Meeting '{title_result.data}' for {duration_result.data} minutes (Urgent: {urgent})"
+```
+
+### Client Requirements
+
+Elicitation requires the client to implement an elicitation handler. If a client doesn't support elicitation, calls to `ctx.elicit()` will raise an error indicating that elicitation is not supported.
+
+See [Client Elicitation](/clients/elicitation) for details on how clients handle these requests.
+
+## Schema and Response Types
+
+The server must send a schema to the client indicating the type of data it expects in response to the elicitation request. The MCP spec only supports a limited subset of JSON Schema types for elicitation responses—specifically JSON **objects** with **primitive** properties including `string`, `number` (or `integer`), `boolean`, and `enum` fields.
+
+FastMCP makes it easy to request a broader range of types, including scalars (e.g. `str`) or no response at all, by automatically wrapping them in MCP-compatible object schemas.
+
+### Scalar Types
+
+You can request simple scalar data types for basic input, such as a string, integer, or boolean. When you request a scalar type, FastMCP automatically wraps it in an object schema for MCP spec compatibility. Clients will see a schema requesting a single "value" field of the requested type. Once clients respond, the provided object is "unwrapped" and the scalar value is returned directly in the `data` field.
+
+<CodeGroup>
+```python title="String"
+@mcp.tool
+async def get_user_name(ctx: Context) -> str:
+    result = await ctx.elicit("What's your name?", response_type=str)
+
+    if result.action == "accept":
+        return f"Hello, {result.data}!"
+    return "No name provided"
+```
+```python title="Integer"
+@mcp.tool
+async def pick_a_number(ctx: Context) -> str:
+    result = await ctx.elicit("Pick a number!", response_type=int)
+
+    if result.action == "accept":
+        return f"You picked {result.data}"
+    return "No number provided"
+```
+```python title="Boolean"
+@mcp.tool
+async def pick_a_boolean(ctx: Context) -> str:
+    result = await ctx.elicit("True or false?", response_type=bool)
+
+    if result.action == "accept":
+        return f"You picked {result.data}"
+    return "No boolean provided"
+```
+</CodeGroup>
+
+#### Customizing the Field Label
+
+<VersionBadge version="3.3.0" />
+
+When FastMCP wraps a scalar, `Literal`, `Enum`, or one of the constrained-option shorthands, the wrapper's `value` property is labelled `"Value"` by default — and some clients (including VS Code) render that label directly in the UI. Pass `response_title` and `response_description` to override it:
+
+```python
+@mcp.tool
+async def confirm_purchase(ctx: Context) -> str:
+    result = await ctx.elicit(
+        "Buy 1x Baguette?",
+        response_type=bool,
+        response_title="Confirm purchase",
+        response_description="Approve this transaction?",
+    )
+    if result.action == "accept":
+        return "Purchased" if result.data else "Declined"
+    return "No response"
+```
+
+These arguments only apply when FastMCP is adding the wrapper. For structured responses (`BaseModel`, dataclass, `TypedDict`), set the metadata on the individual fields via `Field(title=..., description=...)` — passing `response_title` or `response_description` alongside a model type raises `TypeError`.
+
+### No Response
+
+Sometimes, the goal of an elicitation is to simply get a user to approve or reject an action. Pass `None` as the response type to indicate that no data is expected. The `data` field will be `None` when the user accepts.
+
+```python
+@mcp.tool
+async def approve_action(ctx: Context) -> str:
+    result = await ctx.elicit("Approve this action?", response_type=None)
+
+    if result.action == "accept":
+        return do_action()
+    else:
+        raise ValueError("Action rejected")
+```
+
+### Constrained Options
+
+Constrain the user's response to a specific set of values using a `Literal` type, Python enum, or a list of strings as a convenient shortcut.
+
+<CodeGroup>
+```python title="List of strings"
+@mcp.tool
+async def set_priority(ctx: Context) -> str:
+    result = await ctx.elicit(
+        "What priority level?",
+        response_type=["low", "medium", "high"],
+    )
+
+    if result.action == "accept":
+        return f"Priority set to: {result.data}"
+```
+```python title="Literal type"
+from typing import Literal
+
+@mcp.tool
+async def set_priority(ctx: Context) -> str:
+    result = await ctx.elicit(
+        "What priority level?",
+        response_type=Literal["low", "medium", "high"]
+    )
+
+    if result.action == "accept":
+        return f"Priority set to: {result.data}"
+    return "No priority set"
+```
+```python title="Python enum"
+from enum import Enum
+
+class Priority(Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+@mcp.tool
+async def set_priority(ctx: Context) -> str:
+    result = await ctx.elicit("What priority level?", response_type=Priority)
+
+    if result.action == "accept":
+        return f"Priority set to: {result.data.value}"
+    return "No priority set"
+```
+</CodeGroup>
+
+### Multi-Select
+
+<VersionBadge version="2.14.0" />
+
+Enable multi-select by wrapping your choices in an additional list level. This allows users to select multiple values from the available options.
+
+<CodeGroup>
+```python title="List of strings"
+@mcp.tool
+async def select_tags(ctx: Context) -> str:
+    result = await ctx.elicit(
+        "Choose tags",
+        response_type=[["bug", "feature", "documentation"]]  # Note: list of a list
+    )
+
+    if result.action == "accept":
+        tags = result.data
+        return f"Selected tags: {', '.join(tags)}"
+```
+```python title="list[Enum] type"
+from enum import Enum
+
+class Tag(Enum):
+    BUG = "bug"
+    FEATURE = "feature"
+    DOCS = "documentation"
+
+@mcp.tool
+async def select_tags(ctx: Context) -> str:
+    result = await ctx.elicit(
+        "Choose tags",
+        response_type=list[Tag]
+    )
+    if result.action == "accept":
+        tags = [tag.value for tag in result.data]
+        return f"Selected: {', '.join(tags)}"
+```
+</CodeGroup>
+
+### Titled Options
+
+<VersionBadge version="2.14.0" />
+
+For better UI display, provide human-readable titles for enum options. FastMCP generates SEP-1330 compliant schemas using the `oneOf` pattern with `const` and `title` fields.
+
+```python
+@mcp.tool
+async def set_priority(ctx: Context) -> str:
+    result = await ctx.elicit(
+        "What priority level?",
+        response_type={
+            "low": {"title": "Low Priority"},
+            "medium": {"title": "Medium Priority"},
+            "high": {"title": "High Priority"}
+        }
+    )
+
+    if result.action == "accept":
+        return f"Priority set to: {result.data}"
+```
+
+For multi-select with titles, wrap the dict in a list:
+
+```python
+@mcp.tool
+async def select_priorities(ctx: Context) -> str:
+    result = await ctx.elicit(
+        "Choose priorities",
+        response_type=[{
+            "low": {"title": "Low Priority"},
+            "medium": {"title": "Medium Priority"},
+            "high": {"title": "High Priority"}
+        }]
+    )
+
+    if result.action == "accept":
+        return f"Selected: {', '.join(result.data)}"
+```
+
+### Structured Responses
+
+Request structured data with multiple fields by using a dataclass, typed dict, or Pydantic model as the response type. Note that the MCP spec only supports shallow objects with scalar (string, number, boolean) or enum properties.
+
+```python
+from dataclasses import dataclass
+from typing import Literal
+
+@dataclass
+class TaskDetails:
+    title: str
+    description: str
+    priority: Literal["low", "medium", "high"]
+    due_date: str
+
+@mcp.tool
+async def create_task(ctx: Context) -> str:
+    result = await ctx.elicit(
+        "Please provide task details",
+        response_type=TaskDetails
+    )
+
+    if result.action == "accept":
+        task = result.data
+        return f"Created task: {task.title} (Priority: {task.priority})"
+    return "Task creation cancelled"
+```
+
+### Default Values
+
+<VersionBadge version="2.14.0" />
+
+Provide default values for elicitation fields using Pydantic's `Field(default=...)`. Clients will pre-populate form fields with these defaults. Fields with default values are automatically marked as optional.
+
+```python
+from pydantic import BaseModel, Field
+from enum import Enum
+
+class Priority(Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+class TaskDetails(BaseModel):
+    title: str = Field(description="Task title")
+    description: str = Field(default="", description="Task description")
+    priority: Priority = Field(default=Priority.MEDIUM, description="Task priority")
+
+@mcp.tool
+async def create_task(ctx: Context) -> str:
+    result = await ctx.elicit("Please provide task details", response_type=TaskDetails)
+    if result.action == "accept":
+        return f"Created: {result.data.title}"
+    return "Task creation cancelled"
+```
+
+Default values are supported for strings, integers, numbers, booleans, and enums.
diff --git a/docs/servers/icons.mdx b/docs/servers/icons.mdx
new file mode 100644
index 0000000..589e054
--- /dev/null
+++ b/docs/servers/icons.mdx
@@ -0,0 +1,151 @@
+---
+title: Icons
+description: Add visual icons to your servers, tools, resources, and prompts
+icon: image
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.13.0" />
+
+Icons provide visual representations for your MCP servers and components, helping client applications present better user interfaces. When displayed in MCP clients, icons help users quickly identify and navigate your server's capabilities.
+
+## Icon Format
+
+Icons use the standard MCP Icon type from the MCP protocol specification. Each icon specifies a source URL or data URI, and optionally includes MIME type and size information.
+
+```python
+from fastmcp.types import Icon
+
+icon = Icon(
+    src="https://example.com/icon.png",
+    mime_type="image/png",
+    sizes=["48x48"]
+)
+```
+
+The fields serve different purposes:
+
+- **src**: URL or data URI pointing to the icon image
+- **mime_type** (optional): MIME type of the image (e.g., "image/png", "image/svg+xml")
+- **sizes** (optional): Array of size descriptors (e.g., ["48x48"], ["any"])
+
+## Server Icons
+
+Add icons and a website URL to your server for display in client applications. Multiple icons at different sizes help clients choose the best resolution for their display context.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.types import Icon
+
+mcp = FastMCP(
+    name="WeatherService",
+    website_url="https://weather.example.com",
+    icons=[
+        Icon(
+            src="https://weather.example.com/icon-48.png",
+            mime_type="image/png",
+            sizes=["48x48"]
+        ),
+        Icon(
+            src="https://weather.example.com/icon-96.png",
+            mime_type="image/png",
+            sizes=["96x96"]
+        ),
+    ]
+)
+```
+
+Server icons appear in MCP client interfaces to help users identify your server among others they may have installed.
+
+## Component Icons
+
+Icons can be added to individual tools, resources, resource templates, and prompts. This helps users visually distinguish between different component types and purposes.
+
+### Tool Icons
+
+```python
+from fastmcp.types import Icon
+
+@mcp.tool(
+    icons=[Icon(src="https://example.com/calculator-icon.png")]
+)
+def calculate_sum(a: int, b: int) -> int:
+    """Add two numbers together."""
+    return a + b
+```
+
+### Resource Icons
+
+```python
+@mcp.resource(
+    "config://settings",
+    icons=[Icon(src="https://example.com/config-icon.png")]
+)
+def get_settings() -> dict:
+    """Retrieve application settings."""
+    return {"theme": "dark", "language": "en"}
+```
+
+### Resource Template Icons
+
+```python
+@mcp.resource(
+    "user://{user_id}/profile",
+    icons=[Icon(src="https://example.com/user-icon.png")]
+)
+def get_user_profile(user_id: str) -> dict:
+    """Get a user's profile."""
+    return {"id": user_id, "name": f"User {user_id}"}
+```
+
+### Prompt Icons
+
+```python
+@mcp.prompt(
+    icons=[Icon(src="https://example.com/prompt-icon.png")]
+)
+def analyze_code(code: str):
+    """Create a prompt for code analysis."""
+    return f"Please analyze this code:\n\n{code}"
+```
+
+## Using Data URIs
+
+For small icons or when you want to embed the icon directly without external dependencies, use data URIs. This approach eliminates the need for hosting and ensures the icon is always available.
+
+```python
+from fastmcp.types import Icon
+from fastmcp.utilities.types import Image
+
+# SVG icon as data URI
+svg_icon = Icon(
+    src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCI+PHBhdGggZD0iTTEyIDJDNi40OCAyIDIgNi40OCAyIDEyczQuNDggMTAgMTAgMTAgMTAtNC40OCAxMC0xMFMxNy41MiAyIDEyIDJ6Ii8+PC9zdmc+",
+    mime_type="image/svg+xml"
+)
+
+@mcp.tool(icons=[svg_icon])
+def my_tool() -> str:
+    """A tool with an embedded SVG icon."""
+    return "result"
+```
+
+### Generating Data URIs from Files
+
+FastMCP provides the `Image` utility class to convert local image files into data URIs.
+
+```python
+from fastmcp.types import Icon
+from fastmcp.utilities.types import Image
+
+# Generate a data URI from a local image file
+img = Image(path="./assets/brand/favicon.png")
+icon = Icon(src=img.to_data_uri())
+
+@mcp.tool(icons=[icon])
+def file_icon_tool() -> str:
+    """A tool with an icon generated from a local file."""
+    return "result"
+```
+
+This approach is useful when you have local image assets and want to embed them directly in your server definition.
diff --git a/docs/servers/lifespan.mdx b/docs/servers/lifespan.mdx
new file mode 100644
index 0000000..822e4f8
--- /dev/null
+++ b/docs/servers/lifespan.mdx
@@ -0,0 +1,148 @@
+---
+title: Lifespans
+sidebarTitle: Lifespan
+description: Server-level setup and teardown with composable lifespans
+icon: heart-pulse
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+Lifespans let you run code once when the server starts and clean up when it stops. Unlike per-session handlers, lifespans run exactly once regardless of how many clients connect.
+
+## Basic Usage
+
+Use the `@lifespan` decorator to define a lifespan:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.lifespan import lifespan
+
+@lifespan
+async def app_lifespan(server):
+    # Setup: runs once when server starts
+    print("Starting up...")
+    try:
+        yield {"started_at": "2024-01-01"}
+    finally:
+        # Teardown: runs when server stops
+        print("Shutting down...")
+
+mcp = FastMCP("MyServer", lifespan=app_lifespan)
+```
+
+The dict you yield becomes the **lifespan context**, accessible from tools.
+
+<Note>
+Always use `try/finally` for cleanup code to ensure it runs even if the server is cancelled.
+</Note>
+
+## Accessing Lifespan Context
+
+Access the lifespan context in tools via `ctx.lifespan_context`:
+
+```python
+from fastmcp import FastMCP, Context
+from fastmcp.server.lifespan import lifespan
+
+@lifespan
+async def app_lifespan(server):
+    # Initialize shared state
+    data = {"users": ["alice", "bob"]}
+    yield {"data": data}
+
+mcp = FastMCP("MyServer", lifespan=app_lifespan)
+
+@mcp.tool
+def list_users(ctx: Context) -> list[str]:
+    data = ctx.lifespan_context["data"]
+    return data["users"]
+```
+
+## Composing Lifespans
+
+Compose multiple lifespans with the `|` operator:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.lifespan import lifespan
+
+@lifespan
+async def config_lifespan(server):
+    config = {"debug": True, "version": "1.0"}
+    yield {"config": config}
+
+@lifespan
+async def data_lifespan(server):
+    data = {"items": []}
+    yield {"data": data}
+
+# Compose with |
+mcp = FastMCP("MyServer", lifespan=config_lifespan | data_lifespan)
+```
+
+Composed lifespans:
+- Enter in order (left to right)
+- Exit in reverse order (right to left)
+- Merge their context dicts (later values overwrite earlier on conflict)
+
+## Backwards Compatibility
+
+Existing `@asynccontextmanager` lifespans still work when passed directly to FastMCP:
+
+```python
+from contextlib import asynccontextmanager
+from fastmcp import FastMCP
+
+@asynccontextmanager
+async def legacy_lifespan(server):
+    yield {"key": "value"}
+
+mcp = FastMCP("MyServer", lifespan=legacy_lifespan)
+```
+
+To compose an `@asynccontextmanager` function with `@lifespan` functions, wrap it with `ContextManagerLifespan`:
+
+```python
+from contextlib import asynccontextmanager
+from fastmcp.server.lifespan import lifespan, ContextManagerLifespan
+
+@asynccontextmanager
+async def legacy_lifespan(server):
+    yield {"legacy": True}
+
+@lifespan
+async def new_lifespan(server):
+    yield {"new": True}
+
+# Wrap the legacy lifespan explicitly for composition
+combined = ContextManagerLifespan(legacy_lifespan) | new_lifespan
+```
+
+## With FastAPI
+
+When mounting FastMCP into FastAPI, use `combine_lifespans` to run both your app's lifespan and the MCP server's lifespan:
+
+```python
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastmcp import FastMCP
+from fastmcp.utilities.lifespan import combine_lifespans
+
+@asynccontextmanager
+async def app_lifespan(app):
+    print("FastAPI starting...")
+    yield
+    print("FastAPI shutting down...")
+
+mcp = FastMCP("Tools")
+mcp_app = mcp.http_app()
+
+app = FastAPI(lifespan=combine_lifespans(app_lifespan, mcp_app.lifespan))
+app.mount("/mcp", mcp_app)
+```
+
+See the [FastAPI integration guide](/integrations/fastapi#combining-lifespans) for full details.
diff --git a/docs/servers/logging.mdx b/docs/servers/logging.mdx
new file mode 100644
index 0000000..e01fdd8
--- /dev/null
+++ b/docs/servers/logging.mdx
@@ -0,0 +1,87 @@
+---
+title: Client Logging
+sidebarTitle: Logging
+description: Send log messages back to MCP clients through the context.
+icon: receipt
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<Tip>
+This documentation covers **MCP client logging**—sending messages from your server to MCP clients. For standard server-side logging (e.g., writing to files, console), use `fastmcp.utilities.logging.get_logger()` or Python's built-in `logging` module.
+</Tip>
+
+Server logging allows MCP tools to send debug, info, warning, and error messages back to the client. Unlike standard Python logging, MCP server logging sends messages directly to the client, making them visible in the client's interface or logs.
+
+## Basic Usage
+
+Use the context logging methods within any tool function:
+
+```python
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP("LoggingDemo")
+
+@mcp.tool
+async def analyze_data(data: list[float], ctx: Context) -> dict:
+    """Analyze numerical data with comprehensive logging."""
+    await ctx.debug("Starting analysis of numerical data")
+    await ctx.info(f"Analyzing {len(data)} data points")
+
+    try:
+        if not data:
+            await ctx.warning("Empty data list provided")
+            return {"error": "Empty data list"}
+
+        result = sum(data) / len(data)
+        await ctx.info(f"Analysis complete, average: {result}")
+        return {"average": result, "count": len(data)}
+
+    except Exception as e:
+        await ctx.error(f"Analysis failed: {str(e)}")
+        raise
+```
+
+## Log Levels
+
+| Level | Use Case |
+|-------|----------|
+| `ctx.debug()` | Detailed execution information for diagnosing problems |
+| `ctx.info()` | General information about normal program execution |
+| `ctx.warning()` | Potentially harmful situations that don't prevent execution |
+| `ctx.error()` | Error events that might still allow the application to continue |
+
+## Structured Logging
+
+All logging methods accept an `extra` parameter for sending structured data to the client. This is useful for creating rich, queryable logs.
+
+```python
+@mcp.tool
+async def process_transaction(transaction_id: str, amount: float, ctx: Context):
+    await ctx.info(
+        f"Processing transaction {transaction_id}",
+        extra={
+            "transaction_id": transaction_id,
+            "amount": amount,
+            "currency": "USD"
+        }
+    )
+```
+
+## Server-Side Logs
+
+Messages sent to clients via `ctx.log()` and its convenience methods are also logged to the server's log at `DEBUG` level. Enable debug logging on the `fastmcp.server.context.to_client` logger to see these messages:
+
+```python
+import logging
+from fastmcp.utilities.logging import get_logger
+
+to_client_logger = get_logger(name="fastmcp.server.context.to_client")
+to_client_logger.setLevel(level=logging.DEBUG)
+```
+
+## Client Handling
+
+Log messages are sent to the client through the MCP protocol. How clients handle these messages depends on their implementation—development clients may display logs in real-time, production clients may store them for analysis, and integration clients may forward them to external logging systems.
+
+See [Client Logging](/clients/logging) for details on how clients handle server log messages.
diff --git a/docs/servers/middleware.mdx b/docs/servers/middleware.mdx
new file mode 100644
index 0000000..c08c06b
--- /dev/null
+++ b/docs/servers/middleware.mdx
@@ -0,0 +1,958 @@
+---
+title: Middleware
+sidebarTitle: Middleware
+description: Add cross-cutting functionality to your MCP server with middleware that intercepts and modifies requests and responses.
+icon: layer-group
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.9.0" />
+
+Middleware adds behavior that applies across multiple operations—authentication, logging, rate limiting, or request transformation—without modifying individual tools or resources.
+
+<Tip>
+MCP middleware is a FastMCP-specific concept and is not part of the official MCP protocol specification.
+</Tip>
+
+## Overview
+
+MCP middleware forms a pipeline around your server's operations. When a request arrives, it flows through each middleware in order—each can inspect, modify, or reject the request before passing it along. After the operation completes, the response flows back through the same middleware in reverse order.
+
+```
+Request → Middleware A → Middleware B → Handler → Middleware B → Middleware A → Response
+```
+
+This bidirectional flow means middleware can:
+- **Pre-process**: Validate authentication, log incoming requests, check rate limits
+- **Post-process**: Transform responses, record timing metrics, handle errors consistently
+
+The key decision point is `call_next(context)`. Calling it continues the chain; not calling it stops processing entirely.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+class LoggingMiddleware(Middleware):
+    async def on_message(self, context: MiddlewareContext, call_next):
+        print(f"→ {context.method}")
+        result = await call_next(context)
+        print(f"← {context.method}")
+        return result
+
+mcp = FastMCP("MyServer")
+mcp.add_middleware(LoggingMiddleware())
+```
+
+### Execution Order
+
+Middleware executes in the order added to the server. The first middleware runs first on the way in and last on the way out:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.middleware.error_handling import ErrorHandlingMiddleware
+from fastmcp.server.middleware.rate_limiting import RateLimitingMiddleware
+from fastmcp.server.middleware.logging import LoggingMiddleware
+
+mcp = FastMCP("MyServer")
+mcp.add_middleware(ErrorHandlingMiddleware())   # 1st in, last out
+mcp.add_middleware(RateLimitingMiddleware())    # 2nd in, 2nd out
+mcp.add_middleware(LoggingMiddleware())         # 3rd in, first out
+```
+
+This ordering matters. Place error handling early so it catches exceptions from all subsequent middleware. Place logging late so it records the actual execution after other middleware has processed the request.
+
+### Server Composition
+
+When using [mounted servers](/servers/composition), middleware behavior follows a clear hierarchy:
+
+- **Parent middleware** runs for all requests, including those routed to mounted servers
+- **Mounted server middleware** only runs for requests handled by that specific server
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.middleware.logging import LoggingMiddleware
+
+parent = FastMCP("Parent")
+parent.add_middleware(AuthMiddleware())  # Runs for ALL requests
+
+child = FastMCP("Child")
+child.add_middleware(LoggingMiddleware())  # Only runs for child's tools
+
+parent.mount(child, namespace="child")
+```
+
+Requests to `child_tool` flow through the parent's `AuthMiddleware` first, then through the child's `LoggingMiddleware`.
+
+Middleware-stored state does not automatically cross mount boundaries. If `AuthMiddleware` on the parent calls `ctx.set_state("user_id", ...)`, a tool on the child server calling `ctx.get_state("user_id")` will get `None` — each `FastMCP` instance owns its own session state store. To share state across the mount, either pass the same `session_state_store` to both servers or use `serializable=False` for request-scoped values. See [State and Mounted Servers](/servers/context#state-and-mounted-servers) for details.
+
+## Hooks
+
+Rather than processing every message identically, FastMCP provides specialized hooks at different levels of specificity. Multiple hooks fire for a single request, going from general to specific:
+
+| Level | Hooks | Purpose |
+|-------|-------|---------|
+| Message | `on_message` | All MCP traffic (requests and notifications) |
+| Type | `on_request`, `on_notification` | Requests expecting responses vs fire-and-forget |
+| Operation | `on_call_tool`, `on_read_resource`, `on_get_prompt`, etc. | Specific MCP operations |
+
+When a client calls a tool, the middleware chain processes `on_message` first, then `on_request`, then `on_call_tool`. This hierarchy lets you target exactly the right scope—use `on_message` for logging everything, `on_request` for authentication, and `on_call_tool` for tool-specific behavior.
+
+### Hook Signature
+
+Every hook follows the same pattern:
+
+```python
+async def hook_name(self, context: MiddlewareContext, call_next) -> result_type:
+    # Pre-processing
+    result = await call_next(context)
+    # Post-processing
+    return result
+```
+
+**Parameters:**
+- `context` — `MiddlewareContext` containing request information
+- `call_next` — Async function to continue the middleware chain
+
+**Returns:** The appropriate result type for the hook (varies by operation).
+
+### MiddlewareContext
+
+The `context` parameter provides access to request details:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `method` | `str` | MCP method name (e.g., `"tools/call"`) |
+| `source` | `str` | Origin: `"client"` or `"server"` |
+| `type` | `str` | Message type: `"request"` or `"notification"` |
+| `message` | `object` | The MCP message data |
+| `timestamp` | `datetime` | When the request was received |
+| `fastmcp_context` | `Context` | FastMCP context object (if available) |
+
+### Message Hooks
+
+#### on_message
+
+Called for every MCP message—both requests and notifications.
+
+```python
+async def on_message(self, context: MiddlewareContext, call_next):
+    result = await call_next(context)
+    return result
+```
+
+Use for: Logging, metrics, or any cross-cutting concern that applies to all traffic.
+
+#### on_request
+
+Called for MCP requests that expect a response.
+
+```python
+async def on_request(self, context: MiddlewareContext, call_next):
+    result = await call_next(context)
+    return result
+```
+
+Use for: Authentication, authorization, request validation.
+
+#### on_notification
+
+Called for fire-and-forget MCP notifications.
+
+```python
+async def on_notification(self, context: MiddlewareContext, call_next):
+    await call_next(context)
+    # Notifications don't return values
+```
+
+Use for: Event logging, async side effects.
+
+### Operation Hooks
+
+#### on_call_tool
+
+Called when a tool is executed. The `context.message` contains `name` (tool name) and `arguments` (dict).
+
+```python
+async def on_call_tool(self, context: MiddlewareContext, call_next):
+    tool_name = context.message.name
+    args = context.message.arguments
+    result = await call_next(context)
+    return result
+```
+
+**Returns:** Tool execution result or raises `ToolError`.
+
+#### on_read_resource
+
+Called when a resource is read. The `context.message` contains `uri` (resource URI).
+
+```python
+async def on_read_resource(self, context: MiddlewareContext, call_next):
+    uri = context.message.uri
+    result = await call_next(context)
+    return result
+```
+
+**Returns:** Resource content.
+
+#### on_get_prompt
+
+Called when a prompt is retrieved. The `context.message` contains `name` (prompt name) and `arguments` (dict).
+
+```python
+async def on_get_prompt(self, context: MiddlewareContext, call_next):
+    prompt_name = context.message.name
+    result = await call_next(context)
+    return result
+```
+
+**Returns:** Prompt messages.
+
+#### on_list_tools
+
+Called when listing available tools. Returns a list of FastMCP `Tool` objects before MCP conversion.
+
+```python
+async def on_list_tools(self, context: MiddlewareContext, call_next):
+    tools = await call_next(context)
+    # Filter or modify the tool list
+    return tools
+```
+
+**Returns:** `list[Tool]` — Can be filtered before returning to client.
+
+#### on_list_resources
+
+Called when listing available resources. Returns FastMCP `Resource` objects.
+
+```python
+async def on_list_resources(self, context: MiddlewareContext, call_next):
+    resources = await call_next(context)
+    return resources
+```
+
+**Returns:** `list[Resource]`
+
+#### on_list_resource_templates
+
+Called when listing resource templates.
+
+```python
+async def on_list_resource_templates(self, context: MiddlewareContext, call_next):
+    templates = await call_next(context)
+    return templates
+```
+
+**Returns:** `list[ResourceTemplate]`
+
+#### on_list_prompts
+
+Called when listing available prompts.
+
+```python
+async def on_list_prompts(self, context: MiddlewareContext, call_next):
+    prompts = await call_next(context)
+    return prompts
+```
+
+**Returns:** `list[Prompt]`
+
+#### on_initialize
+
+<VersionBadge version="2.13.0" />
+
+Called when a client connects and initializes the session. This hook cannot modify the initialization response.
+
+```python
+from fastmcp.exceptions import McpError
+
+async def on_initialize(self, context: MiddlewareContext, call_next):
+    client_info = context.message.params.get("clientInfo", {})
+    client_name = client_info.get("name", "unknown")
+
+    # Reject before call_next to send error to client
+    if client_name == "blocked-client":
+        raise McpError(code=-32000, message="Client not supported")
+
+    await call_next(context)
+    print(f"Client {client_name} initialized")
+```
+
+**Returns:** `None` — The initialization response is handled internally by the MCP protocol.
+
+<Warning>
+Raising `McpError` after `call_next()` will only log the error, not send it to the client. The response has already been sent. Always reject **before** `call_next()`.
+</Warning>
+
+### Raw Handler
+
+For complete control over all messages, override `__call__` instead of individual hooks:
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+class RawMiddleware(Middleware):
+    async def __call__(self, context: MiddlewareContext, call_next):
+        print(f"Processing: {context.method}")
+        result = await call_next(context)
+        print(f"Completed: {context.method}")
+        return result
+```
+
+This bypasses the hook dispatch system entirely. Use when you need uniform handling regardless of message type.
+
+### Session Availability
+
+<VersionBadge version="2.13.1" />
+
+The MCP session may not be available during certain phases like initialization. Check before accessing session-specific attributes:
+
+```python
+async def on_request(self, context: MiddlewareContext, call_next):
+    ctx = context.fastmcp_context
+
+    if ctx.request_context:
+        # MCP session available
+        session_id = ctx.session_id
+        request_id = ctx.request_id
+    else:
+        # Session not yet established (e.g., during initialization)
+        # Use HTTP helpers if needed
+        from fastmcp.server.dependencies import get_http_headers
+        headers = get_http_headers()
+
+    return await call_next(context)
+```
+
+For HTTP-specific data (headers, client IP) when using HTTP transports, see [HTTP Requests](/servers/context#http-requests).
+
+## Built-in Middleware
+
+FastMCP includes production-ready middleware for common server concerns.
+
+### Logging
+
+```python
+from fastmcp.server.middleware.logging import LoggingMiddleware, StructuredLoggingMiddleware
+```
+
+`LoggingMiddleware` provides human-readable request and response logging. `StructuredLoggingMiddleware` outputs JSON-formatted logs for aggregation tools like Datadog or Splunk.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.middleware.logging import LoggingMiddleware
+
+mcp = FastMCP("MyServer")
+mcp.add_middleware(LoggingMiddleware(
+    include_payloads=True,
+    max_payload_length=1000
+))
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `include_payloads` | `bool` | `False` | Log request/response content |
+| `max_payload_length` | `int` | `500` | Truncate payloads beyond this length |
+| `logger` | `Logger` | module logger | Custom logger instance |
+
+### Timing
+
+```python
+from fastmcp.server.middleware.timing import TimingMiddleware, DetailedTimingMiddleware
+```
+
+`TimingMiddleware` logs execution duration for all requests. `DetailedTimingMiddleware` provides per-operation timing with separate tracking for tools, resources, and prompts.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.middleware.timing import TimingMiddleware
+
+mcp = FastMCP("MyServer")
+mcp.add_middleware(TimingMiddleware())
+```
+
+### Caching
+
+```python
+from fastmcp.server.middleware.caching import ResponseCachingMiddleware
+```
+
+Caches tool calls, resource reads, and list operations with TTL-based expiration.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.middleware.caching import ResponseCachingMiddleware
+
+mcp = FastMCP("MyServer")
+mcp.add_middleware(ResponseCachingMiddleware())
+```
+
+Each operation type can be configured independently using settings classes:
+
+```python
+from fastmcp.server.middleware.caching import (
+    ResponseCachingMiddleware,
+    CallToolSettings,
+    ListToolsSettings,
+    ReadResourceSettings
+)
+
+mcp.add_middleware(ResponseCachingMiddleware(
+    list_tools_settings=ListToolsSettings(ttl=30),
+    call_tool_settings=CallToolSettings(included_tools=["expensive_tool"]),
+    read_resource_settings=ReadResourceSettings(enabled=False)
+))
+```
+
+| Settings Class | Configures |
+|----------------|------------|
+| `ListToolsSettings` | `on_list_tools` caching |
+| `CallToolSettings` | `on_call_tool` caching |
+| `ListResourcesSettings` | `on_list_resources` caching |
+| `ReadResourceSettings` | `on_read_resource` caching |
+| `ListPromptsSettings` | `on_list_prompts` caching |
+| `GetPromptSettings` | `on_get_prompt` caching |
+
+Each settings class accepts:
+- `enabled` — Enable/disable caching for this operation
+- `ttl` — Time-to-live in seconds
+- `included_*` / `excluded_*` — Whitelist or blacklist specific items
+
+For persistence or distributed deployments, configure a different storage backend:
+
+```python
+from pathlib import Path
+from fastmcp.server.middleware.caching import ResponseCachingMiddleware
+from key_value.aio.stores.filetree import (
+    FileTreeStore,
+    FileTreeV1KeySanitizationStrategy,
+    FileTreeV1CollectionSanitizationStrategy,
+)
+
+cache_dir = Path("cache")
+mcp.add_middleware(ResponseCachingMiddleware(
+    cache_storage=FileTreeStore(
+        data_directory=cache_dir,
+        key_sanitization_strategy=FileTreeV1KeySanitizationStrategy(cache_dir),
+        collection_sanitization_strategy=FileTreeV1CollectionSanitizationStrategy(cache_dir),
+    )
+))
+```
+
+See [Storage Backends](/servers/storage-backends) for complete options.
+
+<Note>
+Cache keys are based on the operation name and arguments only — they do not include user or session identity. If your tools return user-specific data derived from auth context (e.g., headers or session state) rather than from the request arguments, you should either disable caching for those tools or ensure user identity is part of the tool arguments.
+</Note>
+
+### Rate Limiting
+
+```python
+from fastmcp.server.middleware.rate_limiting import (
+    RateLimitingMiddleware,
+    SlidingWindowRateLimitingMiddleware
+)
+```
+
+`RateLimitingMiddleware` uses a token bucket algorithm allowing controlled bursts. `SlidingWindowRateLimitingMiddleware` provides precise time-window rate limiting without burst allowance.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.middleware.rate_limiting import RateLimitingMiddleware
+
+mcp = FastMCP("MyServer")
+mcp.add_middleware(RateLimitingMiddleware(
+    max_requests_per_second=10.0,
+    burst_capacity=20
+))
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `max_requests_per_second` | `float` | `10.0` | Sustained request rate |
+| `burst_capacity` | `int` | `20` | Maximum burst size |
+| `get_client_id` | `Callable` | `None` | Custom client identification |
+
+For sliding window rate limiting:
+
+```python
+from fastmcp.server.middleware.rate_limiting import SlidingWindowRateLimitingMiddleware
+
+mcp.add_middleware(SlidingWindowRateLimitingMiddleware(
+    max_requests=100,
+    window_minutes=1
+))
+```
+
+### Error Handling
+
+```python
+from fastmcp.server.middleware.error_handling import ErrorHandlingMiddleware, RetryMiddleware
+```
+
+`ErrorHandlingMiddleware` provides centralized error logging and transformation. `RetryMiddleware` automatically retries with exponential backoff for transient failures.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.middleware.error_handling import ErrorHandlingMiddleware
+
+mcp = FastMCP("MyServer")
+mcp.add_middleware(ErrorHandlingMiddleware(
+    include_traceback=True,
+    transform_errors=True,
+    error_callback=my_error_callback
+))
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `include_traceback` | `bool` | `False` | Include stack traces in logs |
+| `transform_errors` | `bool` | `False` | Convert exceptions to MCP errors |
+| `error_callback` | `Callable` | `None` | Custom callback on errors |
+
+For automatic retries:
+
+```python
+from fastmcp.server.middleware.error_handling import RetryMiddleware
+
+mcp.add_middleware(RetryMiddleware(
+    max_retries=3,
+    retry_exceptions=(ConnectionError, TimeoutError)
+))
+```
+
+### Ping
+
+<VersionBadge version="3.0.0" />
+
+```python
+from fastmcp.server.middleware import PingMiddleware
+```
+
+Keeps long-lived connections alive by sending periodic pings.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.middleware import PingMiddleware
+
+mcp = FastMCP("MyServer")
+mcp.add_middleware(PingMiddleware(interval_ms=5000))
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `interval_ms` | `int` | `30000` | Ping interval in milliseconds |
+
+The ping task starts on the first message and stops automatically when the session ends. Most useful for stateful HTTP connections; has no effect on stateless connections.
+
+### Response Limiting
+
+<VersionBadge version="3.0.0" />
+
+```python
+from fastmcp.server.middleware.response_limiting import ResponseLimitingMiddleware
+```
+
+Large tool responses can overwhelm LLM context windows or cause memory issues. You can add response-limiting middleware to enforce size constraints on tool outputs.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.middleware.response_limiting import ResponseLimitingMiddleware
+
+mcp = FastMCP("MyServer")
+
+# Limit all tool responses to 500KB
+mcp.add_middleware(ResponseLimitingMiddleware(max_size=500_000))
+
+@mcp.tool
+def search(query: str) -> str:
+    # This could return a very large result
+    return "x" * 1_000_000  # 1MB response
+
+# When called, the response will be truncated to ~500KB with:
+# "...\n\n[Response truncated due to size limit]"
+```
+
+When a response exceeds the limit, the middleware extracts all text content, joins it together, truncates to fit within the limit, and returns a single `TextContent` block. For non-text responses, the serialized JSON is used as the text source.
+
+<Note>
+If a tool defines an `output_schema`, truncated responses will no longer conform to that schema — the client will receive a plain `TextContent` block instead of the expected structured output. Keep this in mind when setting size limits for tools with structured responses.
+</Note>
+
+```python
+# Limit only specific tools
+mcp.add_middleware(ResponseLimitingMiddleware(
+    max_size=100_000,
+    tools=["search", "fetch_data"],
+))
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `max_size` | `int` | `1_000_000` | Maximum response size in bytes (1MB default) |
+| `truncation_suffix` | `str` | `"\n\n[Response truncated due to size limit]"` | Suffix appended to truncated responses |
+| `tools` | `list[str] \| None` | `None` | Limit only these tools (None = all tools) |
+
+### Combining Middleware
+
+Order matters. Place middleware that should run first (on the way in) earliest:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.middleware.error_handling import ErrorHandlingMiddleware
+from fastmcp.server.middleware.rate_limiting import RateLimitingMiddleware
+from fastmcp.server.middleware.timing import TimingMiddleware
+from fastmcp.server.middleware.logging import LoggingMiddleware
+
+mcp = FastMCP("Production Server")
+
+mcp.add_middleware(ErrorHandlingMiddleware())   # Catch all errors
+mcp.add_middleware(RateLimitingMiddleware(max_requests_per_second=50))
+mcp.add_middleware(TimingMiddleware())
+mcp.add_middleware(LoggingMiddleware())
+
+@mcp.tool
+def my_tool(data: str) -> str:
+    return f"Processed: {data}"
+```
+
+## Custom Middleware
+
+When the built-in middleware doesn't fit your needs—custom authentication schemes, domain-specific logging, or request transformation—subclass `Middleware` and override the hooks you need.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+class CustomMiddleware(Middleware):
+    async def on_request(self, context: MiddlewareContext, call_next):
+        # Pre-processing
+        print(f"→ {context.method}")
+
+        result = await call_next(context)
+
+        # Post-processing
+        print(f"← {context.method}")
+        return result
+
+mcp = FastMCP("MyServer")
+mcp.add_middleware(CustomMiddleware())
+```
+
+Override only the hooks relevant to your use case. Unoverridden hooks pass through automatically.
+
+### Denying Requests
+
+Raise the appropriate error type to stop processing and return an error to the client.
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+from fastmcp.exceptions import ToolError
+
+class AuthMiddleware(Middleware):
+    async def on_call_tool(self, context: MiddlewareContext, call_next):
+        tool_name = context.message.name
+
+        if tool_name in ["delete_all", "admin_config"]:
+            raise ToolError("Access denied: requires admin privileges")
+
+        return await call_next(context)
+```
+
+| Operation | Error Type |
+|-----------|------------|
+| Tool calls | `ToolError` |
+| Resource reads | `ResourceError` |
+| Prompt retrieval | `PromptError` |
+| General requests | `McpError` |
+
+Do not return error values or skip `call_next()` to indicate errors—raise exceptions for proper error propagation.
+
+### Modifying Requests
+
+Change the message before passing it down the chain.
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+class InputSanitizer(Middleware):
+    async def on_call_tool(self, context: MiddlewareContext, call_next):
+        if context.message.name == "search":
+            # Normalize search query
+            query = context.message.arguments.get("query", "")
+            context.message.arguments["query"] = query.strip().lower()
+
+        return await call_next(context)
+```
+
+### Modifying Responses
+
+Transform results after the handler executes.
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+class ResponseEnricher(Middleware):
+    async def on_call_tool(self, context: MiddlewareContext, call_next):
+        result = await call_next(context)
+
+        if context.message.name == "get_data" and result.structured_content:
+            result.structured_content["processed_by"] = "enricher"
+
+        return result
+```
+
+For more complex tool transformations, consider [Transforms](/servers/transforms/transforms) instead.
+
+### Filtering Lists
+
+List operations return FastMCP objects that you can filter before they reach the client. When filtering list results, also block execution in the corresponding operation hook to maintain consistency:
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+from fastmcp.exceptions import ToolError
+
+class PrivateToolFilter(Middleware):
+    async def on_list_tools(self, context: MiddlewareContext, call_next):
+        tools = await call_next(context)
+        return [tool for tool in tools if "private" not in tool.tags]
+
+    async def on_call_tool(self, context: MiddlewareContext, call_next):
+        if context.fastmcp_context:
+            tool = await context.fastmcp_context.fastmcp.get_tool(context.message.name)
+            if "private" in tool.tags:
+                raise ToolError("Tool not found")
+
+        return await call_next(context)
+```
+
+### Accessing Component Metadata
+
+During execution hooks, component metadata (like tags) isn't directly available. Look up the component through the server:
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+from fastmcp.exceptions import ToolError
+
+class TagBasedAuth(Middleware):
+    async def on_call_tool(self, context: MiddlewareContext, call_next):
+        if context.fastmcp_context:
+            try:
+                tool = await context.fastmcp_context.fastmcp.get_tool(context.message.name)
+
+                if "requires-auth" in tool.tags:
+                    # Check authentication here
+                    pass
+
+            except Exception:
+                pass  # Let execution handle missing tools
+
+        return await call_next(context)
+```
+
+The same pattern works for resources and prompts:
+
+```python
+resource = await context.fastmcp_context.fastmcp.get_resource(context.message.uri)
+prompt = await context.fastmcp_context.fastmcp.get_prompt(context.message.name)
+```
+
+### Storing State
+
+<VersionBadge version="2.11.0" />
+
+Middleware can store state that tools access later through the FastMCP context.
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+class UserMiddleware(Middleware):
+    async def on_request(self, context: MiddlewareContext, call_next):
+        # Extract user from headers (HTTP transport)
+        from fastmcp.server.dependencies import get_http_headers
+        headers = get_http_headers() or {}
+        user_id = headers.get("x-user-id", "anonymous")
+
+        # Store for tools to access
+        if context.fastmcp_context:
+            context.fastmcp_context.set_state("user_id", user_id)
+
+        return await call_next(context)
+```
+
+Tools retrieve the state:
+
+```python
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP("MyServer")
+
+@mcp.tool
+def get_user_data(ctx: Context) -> str:
+    user_id = ctx.get_state("user_id")
+    return f"Data for user: {user_id}"
+```
+
+See [Context State Management](/servers/context#state-management) for details.
+
+### Constructor Parameters
+
+Initialize middleware with configuration:
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+class ConfigurableMiddleware(Middleware):
+    def __init__(self, api_key: str, rate_limit: int = 100):
+        self.api_key = api_key
+        self.rate_limit = rate_limit
+        self.request_counts = {}
+
+    async def on_request(self, context: MiddlewareContext, call_next):
+        # Use self.api_key, self.rate_limit, etc.
+        return await call_next(context)
+
+mcp.add_middleware(ConfigurableMiddleware(
+    api_key="secret",
+    rate_limit=50
+))
+```
+
+### Error Handling in Custom Middleware
+
+Wrap `call_next()` to handle errors from downstream middleware and handlers.
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+class ErrorLogger(Middleware):
+    async def on_request(self, context: MiddlewareContext, call_next):
+        try:
+            return await call_next(context)
+        except Exception as e:
+            print(f"Error in {context.method}: {type(e).__name__}: {e}")
+            raise  # Re-raise to let error propagate
+```
+
+Catching and not re-raising suppresses the error entirely. Usually you want to log and re-raise.
+
+### Audit and Event Records
+
+A common need is to emit one structured record per tool call — for audit logs, policy decisions, or offline analysis — without wrapping individual tools or storing raw payloads. `on_call_tool` is the right place: it sees the call start, the resolved `ToolResult` (so it can detect empty or error results), the duration, and can deny the call before it runs.
+
+Use [OpenTelemetry](/servers/telemetry) when the goal is to *export* spans to an observability backend. Reach for a record like this when you want a self-contained, redacted audit trail — or to drive runtime decisions from the result.
+
+```python
+import hashlib
+import json
+from datetime import datetime
+
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+from fastmcp.exceptions import ToolError
+
+
+def _schema_hash(arguments: dict | None) -> str:
+    """Stable hash of the argument shape — detects schema drift without storing values."""
+    shape = sorted(arguments or {})
+    return hashlib.sha256(json.dumps(shape).encode()).hexdigest()[:12]
+
+
+def _redact(arguments: dict | None) -> dict:
+    """Keep keys, drop values — raw inputs stay out of the default path."""
+    return {key: "<redacted>" for key in (arguments or {})}
+
+
+def _call_id(context: MiddlewareContext) -> str | None:
+    """Request id when an MCP session is active (see Session Availability above)."""
+    ctx = context.fastmcp_context
+    if ctx is not None and ctx.request_context:
+        return ctx.request_id
+    return None
+
+
+class AuditMiddleware(Middleware):
+    async def on_call_tool(self, context: MiddlewareContext, call_next):
+        record = {
+            "tool": context.message.name,
+            "call_id": _call_id(context),
+            "schema_hash": _schema_hash(context.message.arguments),
+            "arguments": _redact(context.message.arguments),
+            "received_at": context.timestamp.isoformat(),
+        }
+
+        try:
+            result = await call_next(context)
+        except Exception as exc:
+            record["status"] = "failed"
+            record["error"] = type(exc).__name__
+            self.emit(record)
+            raise
+
+        empty = not result.content and result.structured_content is None
+        record["status"] = "error" if result.is_error else "empty" if empty else "completed"
+        now = datetime.now(context.timestamp.tzinfo)
+        record["duration_ms"] = round((now - context.timestamp).total_seconds() * 1000, 2)
+        self.emit(record)
+        return result
+
+    def emit(self, record: dict) -> None:
+        # Swap in your sink: structured logger, queue, audit store, etc.
+        print(json.dumps(record))
+```
+
+Each record carries the fields downstream tools tend to need — tool name, call id, input schema hash, redacted arguments, result class (`completed` / `empty` / `error` / `failed`), and duration — while raw inputs and outputs stay out by default.
+
+To make this a policy layer, deny inside the same hook before calling `call_next`:
+
+```python
+async def on_call_tool(self, context: MiddlewareContext, call_next):
+    if not self.is_allowed(context.message.name, context.message.arguments):
+        self.emit({"tool": context.message.name, "status": "denied", "reason": "policy"})
+        raise ToolError("Call blocked by policy")
+    return await call_next(context)
+```
+
+### Complete Example
+
+Authentication middleware checking API keys for specific tools:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+from fastmcp.server.dependencies import get_http_headers
+from fastmcp.exceptions import ToolError
+
+class ApiKeyAuth(Middleware):
+    def __init__(self, valid_keys: set[str], protected_tools: set[str]):
+        self.valid_keys = valid_keys
+        self.protected_tools = protected_tools
+
+    async def on_call_tool(self, context: MiddlewareContext, call_next):
+        tool_name = context.message.name
+
+        if tool_name not in self.protected_tools:
+            return await call_next(context)
+
+        headers = get_http_headers() or {}
+        api_key = headers.get("x-api-key")
+
+        if api_key not in self.valid_keys:
+            raise ToolError(f"Invalid API key for protected tool: {tool_name}")
+
+        return await call_next(context)
+
+mcp = FastMCP("Secure Server")
+mcp.add_middleware(ApiKeyAuth(
+    valid_keys={"key-1", "key-2"},
+    protected_tools={"delete_user", "admin_panel"}
+))
+
+@mcp.tool
+def delete_user(user_id: str) -> str:
+    return f"Deleted user {user_id}"
+
+@mcp.tool
+def get_user(user_id: str) -> str:
+    return f"User {user_id}"  # Not protected
+```
diff --git a/docs/servers/pagination.mdx b/docs/servers/pagination.mdx
new file mode 100644
index 0000000..c23e296
--- /dev/null
+++ b/docs/servers/pagination.mdx
@@ -0,0 +1,93 @@
+---
+title: Pagination
+sidebarTitle: Pagination
+description: Control how servers return large lists of components to clients.
+icon: page
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+When a server exposes many tools, resources, or prompts, returning them all in a single response can be impractical. MCP supports pagination for list operations, allowing servers to return results in manageable chunks that clients can fetch incrementally.
+
+## Server Configuration
+
+By default, FastMCP servers return all components in a single response for backward compatibility. To enable pagination, set the `list_page_size` parameter when creating your server. This value determines the maximum number of items returned per page across all list operations.
+
+```python
+from fastmcp import FastMCP
+
+# Enable pagination with 50 items per page
+server = FastMCP("ComponentRegistry", list_page_size=50)
+
+# Register tools (in practice, these might come from a database or config)
+@server.tool
+def search(query: str) -> str:
+    return f"Results for: {query}"
+
+@server.tool
+def analyze(data: str) -> dict:
+    return {"status": "analyzed", "data": data}
+
+# ... many more tools, resources, prompts
+```
+
+When `list_page_size` is configured, the `tools/list`, `resources/list`, `resources/templates/list`, and `prompts/list` endpoints all paginate their responses. Each response includes a `next_cursor` field when more results exist, which clients use to fetch subsequent pages.
+
+### Cursor Format
+
+Cursors are opaque base64-encoded strings per the MCP specification. Clients should treat them as black boxes, passing them unchanged between requests. The cursor encodes the offset into the result set, but this is an implementation detail that may change.
+
+## Client Behavior
+
+The FastMCP Client handles pagination transparently. Convenience methods like `list_tools()`, `list_resources()`, `list_resource_templates()`, and `list_prompts()` automatically fetch all pages and return the complete list. Existing code continues to work without modification.
+
+```python
+from fastmcp import Client
+
+async with Client(server) as client:
+    # Returns all 200 tools, fetching pages automatically
+    tools = await client.list_tools()
+    print(f"Total tools: {len(tools)}")  # 200
+```
+
+### Manual Pagination
+
+For scenarios where you want to process results incrementally (memory-constrained environments, progress reporting, or early termination), use the `_mcp` variants with explicit cursor handling.
+
+```python
+from fastmcp import Client
+
+async with Client(server) as client:
+    # Fetch first page
+    result = await client.list_tools_mcp()
+    print(f"Page 1: {len(result.tools)} tools")
+
+    # Continue fetching while more pages exist
+    while result.next_cursor:
+        result = await client.list_tools_mcp(cursor=result.next_cursor)
+        print(f"Next page: {len(result.tools)} tools")
+```
+
+The `_mcp` methods return the raw MCP protocol objects, which include both the items and the `next_cursor` for the next page. When `next_cursor` is `None`, you've reached the end of the result set.
+
+All four list operations support manual pagination:
+
+| Operation | Convenience Method | Manual Method |
+|-----------|-------------------|---------------|
+| Tools | `list_tools()` | `list_tools_mcp(cursor=...)` |
+| Resources | `list_resources()` | `list_resources_mcp(cursor=...)` |
+| Resource Templates | `list_resource_templates()` | `list_resource_templates_mcp(cursor=...)` |
+| Prompts | `list_prompts()` | `list_prompts_mcp(cursor=...)` |
+
+## When to Use Pagination
+
+Pagination becomes valuable when your server exposes a large number of components. Consider enabling it when:
+
+- Your server dynamically generates many components (e.g., from a database or file system)
+- Memory usage is a concern for clients
+- You want to reduce initial response latency
+
+For servers with a fixed, modest number of components (fewer than 100), pagination adds complexity without meaningful benefit. The default behavior of returning everything in one response is simpler and efficient for typical use cases.
diff --git a/docs/servers/progress.mdx b/docs/servers/progress.mdx
new file mode 100644
index 0000000..9600a05
--- /dev/null
+++ b/docs/servers/progress.mdx
@@ -0,0 +1,51 @@
+---
+title: Progress Reporting
+sidebarTitle: Progress
+description: Update clients on the progress of long-running operations through the MCP context.
+icon: chart-line
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+Progress reporting allows MCP tools to notify clients about the progress of long-running operations. Clients can display progress indicators and provide better user experience during time-consuming tasks.
+
+## Basic Usage
+
+Use `ctx.report_progress()` to send progress updates to the client. The method accepts a `progress` value representing how much work is complete, and an optional `total` representing the full scope of work.
+
+```python
+from fastmcp import FastMCP, Context
+import asyncio
+
+mcp = FastMCP("ProgressDemo")
+
+@mcp.tool
+async def process_items(items: list[str], ctx: Context) -> dict:
+    """Process a list of items with progress updates."""
+    total = len(items)
+    results = []
+
+    for i, item in enumerate(items):
+        await ctx.report_progress(progress=i, total=total)
+        await asyncio.sleep(0.1)
+        results.append(item.upper())
+
+    await ctx.report_progress(progress=total, total=total)
+    return {"processed": len(results), "results": results}
+```
+
+## Progress Patterns
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| Percentage | Progress as 0-100 percentage | `progress=75, total=100` |
+| Absolute | Completed items of a known count | `progress=3, total=10` |
+| Indeterminate | Progress without known endpoint | `progress=files_found` (no total) |
+
+For multi-stage operations, map each stage to a portion of the total progress range. A four-stage operation might allocate 0-25% to validation, 25-60% to export, 60-80% to transform, and 80-100% to import.
+
+## Client Requirements
+
+Progress reporting requires clients to support progress handling. Clients must send a `progressToken` in the initial request to receive progress updates. If no progress token is provided, progress calls have no effect (they don't error).
+
+See [Client Progress](/clients/progress) for details on implementing client-side progress handling.
diff --git a/docs/servers/prompts.mdx b/docs/servers/prompts.mdx
new file mode 100644
index 0000000..b5cf2f6
--- /dev/null
+++ b/docs/servers/prompts.mdx
@@ -0,0 +1,481 @@
+---
+title: Prompts
+sidebarTitle: Prompts
+description: Create reusable, parameterized prompt templates for MCP clients.
+icon: message-lines
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+Prompts are reusable message templates that help LLMs generate structured, purposeful responses. FastMCP simplifies defining these templates, primarily using the `@mcp.prompt` decorator.
+
+## What Are Prompts?
+
+Prompts provide parameterized message templates for LLMs. When a client requests a prompt:
+
+1.  FastMCP finds the corresponding prompt definition.
+2.  If it has parameters, they are validated against your function signature.
+3.  Your function executes with the validated inputs.
+4.  The generated message(s) are returned to the LLM to guide its response.
+
+This allows you to define consistent, reusable templates that LLMs can use across different clients and contexts.
+
+## Prompts
+
+### The `@prompt` Decorator
+
+The most common way to define a prompt is by decorating a Python function. The decorator uses the function name as the prompt's identifier.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.prompts import Message
+
+mcp = FastMCP(name="PromptServer")
+
+# Basic prompt returning a string (converted to user message automatically)
+@mcp.prompt
+def ask_about_topic(topic: str) -> str:
+    """Generates a user message asking for an explanation of a topic."""
+    return f"Can you please explain the concept of '{topic}'?"
+
+# Prompt returning multiple messages
+@mcp.prompt
+def generate_code_request(language: str, task_description: str) -> list[Message]:
+    """Generates a conversation for code generation."""
+    return [
+        Message(f"Write a {language} function that performs the following task: {task_description}"),
+        Message("I'll help you write that function.", role="assistant"),
+    ]
+```
+
+**Key Concepts:**
+
+*   **Name:** By default, the prompt name is taken from the function name.
+*   **Parameters:** The function parameters define the inputs needed to generate the prompt.
+*   **Inferred Metadata:** By default:
+    *   Prompt Name: Taken from the function name (`ask_about_topic`).
+    *   Prompt Description: Taken from the summary of the function's docstring. If the docstring includes parameter descriptions (Google, NumPy, or Sphinx style), they populate each prompt argument's description in the MCP protocol (see [Argument Descriptions](#argument-descriptions)).
+<Tip>
+Functions with `*args` or `**kwargs` are not supported as prompts. This restriction exists because FastMCP needs to generate a complete parameter schema for the MCP protocol, which isn't possible with variable argument lists.
+</Tip>
+
+#### Decorator Arguments
+
+While FastMCP infers the name and description from your function, you can override these and add additional metadata using arguments to the `@mcp.prompt` decorator:
+
+```python
+@mcp.prompt(
+    name="analyze_data_request",          # Custom prompt name
+    description="Creates a request to analyze data with specific parameters",  # Custom description
+    tags={"analysis", "data"},            # Optional categorization tags
+    meta={"version": "1.1", "author": "data-team"}  # Custom metadata
+)
+def data_analysis_prompt(
+    data_uri: str = Field(description="The URI of the resource containing the data."),
+    analysis_type: str = Field(default="summary", description="Type of analysis.")
+) -> str:
+    """This docstring is ignored when description is provided."""
+    return f"Please perform a '{analysis_type}' analysis on the data found at {data_uri}."
+```
+
+<Card icon="code" title="@prompt Decorator Arguments">
+<ParamField body="name" type="str | None">
+  Sets the explicit prompt name exposed via MCP. If not provided, uses the function name
+</ParamField>
+
+<ParamField body="title" type="str | None">
+  A human-readable title for the prompt
+</ParamField>
+
+<ParamField body="description" type="str | None">
+  Provides the description exposed via MCP. If set, the function's docstring is ignored for the prompt description, though docstring-derived argument descriptions still apply (see [Argument Descriptions](#argument-descriptions)).
+</ParamField>
+
+<ParamField body="tags" type="set[str] | None">
+  A set of strings used to categorize the prompt. These can be used by the server and, in some cases, by clients to filter or group available prompts.
+</ParamField>
+
+<ParamField body="enabled" type="bool" default="True">
+  <Warning>Deprecated in v3.0.0. Use `mcp.enable()` / `mcp.disable()` at the server level instead.</Warning>
+  A boolean to enable or disable the prompt. See [Component Visibility](#component-visibility) for the recommended approach.
+</ParamField>
+
+<ParamField body="icons" type="list[Icon] | None">
+  <VersionBadge version="2.13.0" />
+
+  Optional list of icon representations for this prompt. See [Icons](/servers/icons) for detailed examples
+</ParamField>
+
+<ParamField body="meta" type="dict[str, Any] | None">
+  <VersionBadge version="2.11.0" />
+
+  Optional meta information about the prompt. This data is passed through to the MCP client as the `meta` field of the client-side prompt object and can be used for custom metadata, versioning, or other application-specific purposes.
+</ParamField>
+
+<ParamField body="version" type="str | int | None">
+  <VersionBadge version="3.0.0" />
+
+  Optional version identifier for this prompt. See [Versioning](/servers/versioning) for details.
+</ParamField>
+</Card>
+
+#### Using with Methods
+
+For decorating instance or class methods, use the standalone `@prompt` decorator and register the bound method. See [Tools: Using with Methods](/servers/tools#using-with-methods) for the pattern.
+
+### Argument Types
+
+<VersionBadge version="2.9.0" />
+
+The MCP specification requires that all prompt arguments be passed as strings, but FastMCP allows you to use typed annotations for better developer experience. When you use complex types like `list[int]` or `dict[str, str]`, FastMCP:
+
+1. **Automatically converts** string arguments from MCP clients to the expected types
+2. **Generates helpful descriptions** showing the exact JSON string format needed
+3. **Preserves direct usage** - you can still call prompts with properly typed arguments
+
+Since the MCP specification only allows string arguments, clients need to know what string format to use for complex types. FastMCP solves this by automatically enhancing the argument descriptions with JSON schema information, making it clear to both humans and LLMs how to format their arguments.
+
+<CodeGroup>
+
+```python Python Code
+@mcp.prompt
+def analyze_data(
+    numbers: list[int],
+    metadata: dict[str, str], 
+    threshold: float
+) -> str:
+    """Analyze numerical data."""
+    avg = sum(numbers) / len(numbers)
+    return f"Average: {avg}, above threshold: {avg > threshold}"
+```
+
+```json Resulting MCP Prompt
+{
+  "name": "analyze_data",
+  "description": "Analyze numerical data.",
+  "arguments": [
+    {
+      "name": "numbers",
+      "description": "Provide as a JSON string matching the following schema: {\"items\":{\"type\":\"integer\"},\"type\":\"array\"}",
+      "required": true
+    },
+    {
+      "name": "metadata", 
+      "description": "Provide as a JSON string matching the following schema: {\"additionalProperties\":{\"type\":\"string\"},\"type\":\"object\"}",
+      "required": true
+    },
+    {
+      "name": "threshold",
+      "description": "Provide as a JSON string matching the following schema: {\"type\":\"number\"}",
+      "required": true
+    }
+  ]
+}
+```
+
+</CodeGroup>
+
+**MCP clients will call this prompt with string arguments:**
+```json
+{
+  "numbers": "[1, 2, 3, 4, 5]",
+  "metadata": "{\"source\": \"api\", \"version\": \"1.0\"}",
+  "threshold": "2.5"
+}
+```
+
+**But you can still call it directly with proper types:**
+```python
+# This also works for direct calls
+result = await prompt.render({
+    "numbers": [1, 2, 3, 4, 5],
+    "metadata": {"source": "api", "version": "1.0"}, 
+    "threshold": 2.5
+})
+```
+
+<Warning>
+Keep your type annotations simple when using this feature. Complex nested types or custom classes may not convert reliably from JSON strings. The automatically generated schema descriptions are the only guidance users receive about the expected format.
+
+Good choices: `list[int]`, `dict[str, str]`, `float`, `bool`
+Avoid: Complex Pydantic models, deeply nested structures, custom classes
+</Warning>
+
+### Argument Descriptions
+
+<VersionBadge version="3.2.4" />
+
+FastMCP parses your function's docstring to extract the prompt description and per-argument descriptions. Google, NumPy, and Sphinx styles are all supported:
+
+```python
+@mcp.prompt
+def analyze_data(dataset: str, method: str = "summary") -> str:
+    """Generate an analysis prompt for a dataset.
+
+    Args:
+        dataset: URI or identifier of the dataset to analyze.
+        method: Type of analysis to perform (summary, detailed, etc).
+    """
+    return f"Please perform a '{method}' analysis on {dataset}."
+```
+
+The free-form text above the `Args` section — whether a single line or multiple paragraphs — becomes the prompt description, and each argument's docstring entry becomes the description on the corresponding `PromptArgument` in the MCP protocol. Sections like `Returns`, `Raises`, and `Example` are excluded from the description but otherwise ignored.
+
+If an argument already has an explicit description — via `Annotated[x, "..."]` or `Field(description=...)` — that description takes precedence over the docstring. This makes it safe to adopt docstring-based descriptions incrementally: existing annotations keep working, and docstrings fill in the gaps.
+
+### Return Values
+
+Prompt functions must return one of these types:
+
+-   **`str`**: Sent as a single user message.
+-   **`list[Message | str]`**: A sequence of messages (a conversation). Strings are auto-converted to user Messages.
+-   **`PromptResult`**: Full control over messages, description, and metadata. See [PromptResult](#promptresult) below.
+
+```python
+from fastmcp.prompts import Message
+
+@mcp.prompt
+def roleplay_scenario(character: str, situation: str) -> list[Message]:
+    """Sets up a roleplaying scenario with initial messages."""
+    return [
+        Message(f"Let's roleplay. You are {character}. The situation is: {situation}"),
+        Message("Okay, I understand. I am ready. What happens next?", role="assistant")
+    ]
+```
+
+#### Message
+
+<VersionBadge version="3.0.0" />
+
+`Message` provides a user-friendly wrapper for prompt messages with automatic serialization.
+
+```python
+from fastmcp.prompts import Message
+
+# String content (user role by default)
+Message("Hello, world!")
+
+# Explicit role
+Message("I can help with that.", role="assistant")
+
+# Auto-serialized to JSON text
+Message({"key": "value"})
+Message(["item1", "item2"])
+```
+
+`Message` accepts two fields:
+
+**`content`** - The message content. Strings pass through directly. Other types (dict, list, BaseModel) are automatically JSON-serialized to text.
+
+**`role`** - The message role, either `"user"` (default) or `"assistant"`.
+
+<Card title="Message">
+<ParamField body="content" type="Any" required>
+  The content data. Strings pass through directly. Other types (dict, list, BaseModel) are automatically JSON-serialized.
+</ParamField>
+<ParamField body="role" type="Literal['user', 'assistant']" default="user">
+  The message role.
+</ParamField>
+</Card>
+
+#### PromptResult
+
+<VersionBadge version="3.0.0" />
+
+`PromptResult` gives you explicit control over prompt responses: multiple messages, roles, and metadata at both the message and result level.
+
+```python test="skip"
+from fastmcp import FastMCP
+from fastmcp.prompts import PromptResult, Message
+
+mcp = FastMCP(name="PromptServer")
+
+@mcp.prompt
+def code_review(code: str) -> PromptResult:
+    """Returns a code review prompt with metadata."""
+    return PromptResult(
+        messages=[
+            Message(f"Please review this code:\n\n```\n{code}\n```"),
+            Message("I'll analyze this code for issues.", role="assistant"),
+        ],
+        description="Code review prompt",
+        meta={"review_type": "security", "priority": "high"}
+    )
+```
+
+For simple cases, you can pass a string directly to `PromptResult`:
+
+```python
+return PromptResult("Please help me with this task")  # auto-converts to single Message
+```
+
+<Card title="PromptResult">
+<ParamField body="messages" type="str | list[Message]" required>
+  Messages to return. Strings are wrapped as a single user Message.
+</ParamField>
+<ParamField body="description" type="str | None">
+  Optional description of the prompt result. If not provided, defaults to the prompt's docstring.
+</ParamField>
+<ParamField body="meta" type="dict[str, Any] | None">
+  Result-level metadata, included in the MCP response's `_meta` field. Use this for runtime metadata like categorization, priority, or other client-specific data.
+</ParamField>
+</Card>
+
+<Note>
+The `meta` field in `PromptResult` is for runtime metadata specific to this render response. This is separate from the `meta` parameter in `@mcp.prompt(meta={...})`, which provides static metadata about the prompt definition itself (returned when listing prompts).
+</Note>
+
+You can still return plain `str` or `list[Message | str]` from your prompt functions—`PromptResult` is opt-in for when you need to include metadata.
+
+### Required vs. Optional Parameters
+
+Parameters in your function signature are considered **required** unless they have a default value.
+
+```python
+@mcp.prompt
+def data_analysis_prompt(
+    data_uri: str,                        # Required - no default value
+    analysis_type: str = "summary",       # Optional - has default value
+    include_charts: bool = False          # Optional - has default value
+) -> str:
+    """Creates a request to analyze data with specific parameters."""
+    prompt = f"Please perform a '{analysis_type}' analysis on the data found at {data_uri}."
+    if include_charts:
+        prompt += " Include relevant charts and visualizations."
+    return prompt
+```
+
+In this example, the client *must* provide `data_uri`. If `analysis_type` or `include_charts` are omitted, their default values will be used.
+
+### Component Visibility
+
+<VersionBadge version="3.0.0" />
+
+You can control which prompts are enabled for clients using server-level enabled control. Disabled prompts don't appear in `list_prompts` and can't be called.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")
+
+@mcp.prompt(tags={"public"})
+def public_prompt(topic: str) -> str:
+    return f"Discuss: {topic}"
+
+@mcp.prompt(tags={"internal"})
+def internal_prompt() -> str:
+    return "Internal system prompt"
+
+# Disable specific prompts by key
+mcp.disable(keys={"prompt:internal_prompt"})
+
+# Disable prompts by tag
+mcp.disable(tags={"internal"})
+
+# Or use allowlist mode - only enable prompts with specific tags
+mcp.enable(tags={"public"}, only=True)
+```
+
+See [Visibility](/servers/visibility) for the complete visibility control API including key formats, tag-based filtering, and provider-level control.
+
+### Async Prompts
+
+FastMCP supports both standard (`def`) and asynchronous (`async def`) functions as prompts. Synchronous functions automatically run in a threadpool to avoid blocking the event loop.
+
+```python
+# Synchronous prompt (runs in threadpool)
+@mcp.prompt
+def simple_question(question: str) -> str:
+    """Generates a simple question to ask the LLM."""
+    return f"Question: {question}"
+
+# Asynchronous prompt
+@mcp.prompt
+async def data_based_prompt(data_id: str) -> str:
+    """Generates a prompt based on data that needs to be fetched."""
+    # In a real scenario, you might fetch data from a database or API
+    async with aiohttp.ClientSession() as session:
+        async with session.get(f"https://api.example.com/data/{data_id}") as response:
+            data = await response.json()
+            return f"Analyze this data: {data['content']}"
+```
+
+Use `async def` when your prompt function performs I/O operations like network requests or database queries, since async is more efficient than threadpool dispatch.
+
+### Accessing MCP Context
+
+<VersionBadge version="2.2.5" />
+
+Prompts can access additional MCP information and features through the `Context` object. To access it, add a parameter to your prompt function with a type annotation of `Context`:
+
+```python {6}
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP(name="PromptServer")
+
+@mcp.prompt
+async def generate_report_request(report_type: str, ctx: Context) -> str:
+    """Generates a request for a report."""
+    return f"Please create a {report_type} report. Request ID: {ctx.request_id}"
+```
+
+For full documentation on the Context object and all its capabilities, see the [Context documentation](/servers/context).
+
+### Notifications
+
+<VersionBadge version="2.9.1" />
+
+FastMCP automatically sends `notifications/prompts/list_changed` notifications to connected clients when prompts are added, enabled, or disabled. This allows clients to stay up-to-date with the current prompt set without manually polling for changes.
+
+```python
+@mcp.prompt
+def example_prompt() -> str:
+    return "Hello!"
+
+# These operations trigger notifications:
+mcp.add_prompt(example_prompt)               # Sends prompts/list_changed notification
+mcp.disable(keys={"prompt:example_prompt"})  # Sends prompts/list_changed notification
+mcp.enable(keys={"prompt:example_prompt"})   # Sends prompts/list_changed notification
+```
+
+Notifications are only sent when these operations occur within an active MCP request context (e.g., when called from within a tool or other MCP operation). Operations performed during server initialization do not trigger notifications.
+
+Clients can handle these notifications using a [message handler](/clients/notifications) to automatically refresh their prompt lists or update their interfaces.
+
+## Server Behavior
+
+### Duplicate Prompts
+
+<VersionBadge version="2.1.0" />
+
+You can configure how the FastMCP server handles attempts to register multiple prompts with the same name. Use the `on_duplicate_prompts` setting during `FastMCP` initialization.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(
+    name="PromptServer",
+    on_duplicate_prompts="error"  # Raise an error if a prompt name is duplicated
+)
+
+@mcp.prompt
+def greeting(): return "Hello, how can I help you today?"
+
+# This registration attempt will raise a ValueError because
+# "greeting" is already registered and the behavior is "error".
+# @mcp.prompt
+# def greeting(): return "Hi there! What can I do for you?"
+```
+
+The duplicate behavior options are:
+
+-   `"warn"` (default): Logs a warning, and the new prompt replaces the old one.
+-   `"error"`: Raises a `ValueError`, preventing the duplicate registration.
+-   `"replace"`: Silently replaces the existing prompt with the new one.
+-   `"ignore"`: Keeps the original prompt and ignores the new registration attempt.
+
+## Versioning
+
+<VersionBadge version="3.0.0" />
+
+Prompts support versioning, allowing you to maintain multiple implementations under the same name while clients automatically receive the highest version. See [Versioning](/servers/versioning) for complete documentation on version comparison, retrieval, and migration patterns.
diff --git a/docs/servers/providers/custom.mdx b/docs/servers/providers/custom.mdx
new file mode 100644
index 0000000..f5673c6
--- /dev/null
+++ b/docs/servers/providers/custom.mdx
@@ -0,0 +1,245 @@
+---
+title: Custom Providers
+sidebarTitle: Custom
+description: Build providers that source components from any data source
+icon: code
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+Custom providers let you source components from anywhere - databases, APIs, configuration systems, or dynamic runtime logic. If you can write Python code to fetch or generate a component, you can wrap it in a provider.
+
+## When to Build Custom
+
+The built-in providers handle common cases: decorators (`LocalProvider`), composition (`FastMCPProvider`), and proxying (`ProxyProvider`). Build a custom provider when your components come from somewhere else:
+
+- **Database-backed tools**: Admin users define tools in a database, and your server exposes them dynamically
+- **API-backed resources**: Resources that fetch content from external services on demand
+- **Configuration-driven components**: Components loaded from YAML/JSON config files at startup
+- **Multi-tenant systems**: Different users see different tools based on their permissions
+- **Plugin systems**: Third-party code registers components at runtime
+
+## Providers vs Middleware
+
+Both providers and [middleware](/servers/middleware) can influence what components a client sees, but they work at different levels.
+
+**Providers** are objects that source components. They make it easy to reason about where tools, resources, and prompts come from - a database, another server, an API.
+
+**Middleware** intercepts individual requests. It's well-suited for request-specific decisions like logging, rate limiting, or authentication.
+
+You *could* use middleware to dynamically add tools based on request context. But it's often cleaner to have a provider source all possible tools, then use middleware or [visibility controls](/servers/visibility) to filter what each request can see. This separation makes it easier to reason about how components are sourced and how they interact with other server machinery.
+
+## The Provider Interface
+
+A provider implements protected `_list_*` methods that return available components. The public `list_*` methods handle transforms automatically - you override the underscore-prefixed versions:
+
+```python
+from collections.abc import Sequence
+from fastmcp.server.providers import Provider
+from fastmcp.tools import Tool
+from fastmcp.resources import Resource
+from fastmcp.prompts import Prompt
+
+class MyProvider(Provider):
+    async def _list_tools(self) -> Sequence[Tool]:
+        """Return all tools this provider offers."""
+        return []
+
+    async def _list_resources(self) -> Sequence[Resource]:
+        """Return all resources this provider offers."""
+        return []
+
+    async def _list_prompts(self) -> Sequence[Prompt]:
+        """Return all prompts this provider offers."""
+        return []
+```
+
+You only need to implement the methods for component types you provide. The base class returns empty sequences by default.
+
+The `_get_*` methods (`_get_tool`, `_get_resource`, `_get_prompt`) have default implementations that search through the list results. Override them only if you can fetch individual components more efficiently than iterating the full list.
+
+## What Providers Return
+
+Providers return component objects that are ready to use. When a client calls a tool, FastMCP invokes the tool's function - your provider isn't involved in execution. This means the `Tool`, `Resource`, or `Prompt` you return must actually work.
+
+The easiest way to create components is from functions:
+
+```python
+from fastmcp.tools import Tool
+
+def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+
+tool = Tool.from_function(add)
+```
+
+The function's type hints become the input schema, and the docstring becomes the description. You can override these:
+
+```python
+tool = Tool.from_function(
+    add,
+    name="calculator_add",
+    description="Add two integers together"
+)
+```
+
+Similar `from_function` methods exist for `Resource` and `Prompt`.
+
+## Registering Providers
+
+Add providers when creating the server:
+
+```python
+mcp = FastMCP(
+    "MyServer",
+    providers=[
+        DatabaseProvider(db_url),
+        ConfigProvider(config_path),
+    ]
+)
+```
+
+Or add them after creation:
+
+```python
+mcp = FastMCP("MyServer")
+mcp.add_provider(DatabaseProvider(db_url))
+```
+
+## A Simple Provider
+
+Here's a minimal provider that serves tools from a dictionary:
+
+```python
+from collections.abc import Callable, Sequence
+from fastmcp import FastMCP
+from fastmcp.server.providers import Provider
+from fastmcp.tools import Tool
+
+class DictProvider(Provider):
+    def __init__(self, tools: dict[str, Callable]):
+        super().__init__()
+        self._tools = [
+            Tool.from_function(fn, name=name)
+            for name, fn in tools.items()
+        ]
+
+    async def _list_tools(self) -> Sequence[Tool]:
+        return self._tools
+```
+
+Use it like this:
+
+```python
+def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+
+def multiply(a: int, b: int) -> int:
+    """Multiply two numbers."""
+    return a * b
+
+mcp = FastMCP("Calculator", providers=[
+    DictProvider({"add": add, "multiply": multiply})
+])
+```
+
+## Lifecycle Management
+
+Providers often need to set up connections when the server starts and clean them up when it stops. Override the `lifespan` method:
+
+```python
+from contextlib import asynccontextmanager
+from collections.abc import AsyncIterator, Sequence
+
+class DatabaseProvider(Provider):
+    def __init__(self, db_url: str):
+        super().__init__()
+        self.db_url = db_url
+        self.db = None
+
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncIterator[None]:
+        self.db = await connect_database(self.db_url)
+        try:
+            yield
+        finally:
+            await self.db.close()
+
+    async def _list_tools(self) -> Sequence[Tool]:
+        rows = await self.db.fetch("SELECT * FROM tools")
+        return [self._make_tool(row) for row in rows]
+```
+
+FastMCP calls your provider's `lifespan` during server startup and shutdown. The connection is available to your methods while the server runs.
+
+## Full Example: API-Backed Resources
+
+Here's a complete provider that fetches resources from an external REST API:
+
+```python
+from contextlib import asynccontextmanager
+from collections.abc import AsyncIterator, Sequence
+from fastmcp.server.providers import Provider
+from fastmcp.resources import Resource
+import httpx
+
+class ApiResourceProvider(Provider):
+    """Provides resources backed by an external API."""
+
+    def __init__(self, base_url: str, api_key: str):
+        super().__init__()
+        self.base_url = base_url
+        self.api_key = api_key
+        self.client = None
+
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncIterator[None]:
+        self.client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers={"Authorization": f"Bearer {self.api_key}"}
+        )
+        try:
+            yield
+        finally:
+            await self.client.aclose()
+
+    async def _list_resources(self) -> Sequence[Resource]:
+        response = await self.client.get("/resources")
+        response.raise_for_status()
+        return [
+            self._make_resource(item)
+            for item in response.json()["items"]
+        ]
+
+    def _make_resource(self, data: dict) -> Resource:
+        resource_id = data["id"]
+
+        async def read_content() -> str:
+            response = await self.client.get(
+                f"/resources/{resource_id}/content"
+            )
+            return response.text
+
+        return Resource.from_function(
+            read_content,
+            uri=f"api://resources/{resource_id}",
+            name=data["name"],
+            description=data.get("description", ""),
+            mime_type=data.get("mime_type", "text/plain")
+        )
+```
+
+Register it like any other provider:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("API Resources", providers=[
+    ApiResourceProvider("https://api.example.com", "my-api-key")
+])
+```
diff --git a/docs/servers/providers/filesystem.mdx b/docs/servers/providers/filesystem.mdx
new file mode 100644
index 0000000..353a671
--- /dev/null
+++ b/docs/servers/providers/filesystem.mdx
@@ -0,0 +1,256 @@
+---
+title: Filesystem Provider
+sidebarTitle: Filesystem
+description: Automatic component discovery from Python files
+icon: folder-tree
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+`FileSystemProvider` scans a directory for Python files and automatically registers functions decorated with `@tool`, `@resource`, or `@prompt`. This enables a file-based organization pattern similar to Next.js routing, where your project structure becomes your component registry.
+
+## Why Filesystem Discovery
+
+Traditional FastMCP servers require coordination between files. Either your tool files import the server to call `@server.tool()`, or your server file imports all the tool modules. Both approaches create coupling that some developers prefer to avoid.
+
+`FileSystemProvider` eliminates this coordination. Each file is self-contained—it uses standalone decorators (`@tool`, `@resource`, `@prompt`) that don't require access to a server instance. The provider discovers these files at startup, so you can add new tools without modifying your server file.
+
+This is a convention some teams prefer, not necessarily better for all projects. The tradeoffs:
+
+- **No coordination**: Files don't import the server; server doesn't import files
+- **Predictable naming**: Function names become component names (unless overridden)
+- **Development mode**: Optionally re-scan files on every request for rapid iteration
+
+## Quick Start
+
+Create a provider pointing to your components directory, then pass it to your server. Use `Path(__file__).parent` to make the path relative to your server file.
+
+```python
+from pathlib import Path
+
+from fastmcp import FastMCP
+from fastmcp.server.providers import FileSystemProvider
+
+mcp = FastMCP("MyServer", providers=[FileSystemProvider(Path(__file__).parent / "components")])
+```
+
+In your `components/` directory, create Python files with decorated functions.
+
+```python
+# components/tools/greet.py
+from fastmcp.tools import tool
+
+@tool
+def greet(name: str) -> str:
+    """Greet someone by name."""
+    return f"Hello, {name}!"
+```
+
+When the server starts, `FileSystemProvider` scans the directory, imports all Python files, and registers any decorated functions it finds.
+
+## Decorators
+
+FastMCP provides standalone decorators that mark functions for discovery: `@tool` from `fastmcp.tools`, `@resource` from `fastmcp.resources`, and `@prompt` from `fastmcp.prompts`. These support the full syntax of server-bound decorators—all the same parameters work identically.
+
+### @tool
+
+Mark a function as a tool. The function name becomes the tool name by default.
+
+```python
+from fastmcp.tools import tool
+
+@tool
+def calculate_sum(a: float, b: float) -> float:
+    """Add two numbers together."""
+    return a + b
+```
+
+Customize the tool with optional parameters.
+
+```python
+from fastmcp.tools import tool
+
+@tool(
+    name="add-numbers",
+    description="Add two numbers together.",
+    tags={"math", "arithmetic"},
+)
+def add(a: float, b: float) -> float:
+    return a + b
+```
+
+The decorator supports all standard tool options: `name`, `title`, `description`, `icons`, `tags`, `output_schema`, `annotations`, and `meta`.
+
+### @resource
+
+Mark a function as a resource. Unlike `@tool`, the `@resource` decorator requires a URI argument.
+
+```python
+from fastmcp.resources import resource
+
+@resource("config://app")
+def get_app_config() -> str:
+    """Get application configuration."""
+    return '{"version": "1.0"}'
+```
+
+URIs with template parameters create resource templates. The provider automatically detects whether to register a static resource or a template based on whether the URI contains `{parameters}` or the function has arguments.
+
+```python
+from fastmcp.resources import resource
+
+@resource("users://{user_id}/profile")
+def get_user_profile(user_id: str) -> str:
+    """Get a user's profile by ID."""
+    return f'{{"id": "{user_id}", "name": "User"}}'
+```
+
+The decorator supports: `uri` (required), `name`, `title`, `description`, `icons`, `mime_type`, `tags`, `annotations`, and `meta`.
+
+### @prompt
+
+Mark a function as a prompt template.
+
+```python test="skip"
+from fastmcp.prompts import prompt
+
+@prompt
+def code_review(code: str, language: str = "python") -> str:
+    """Generate a code review prompt."""
+    return f"Please review this {language} code:\n\n```{language}\n{code}\n```"
+```
+
+```python
+from fastmcp.prompts import prompt
+
+@prompt(name="explain-concept", tags={"education"})
+def explain(topic: str) -> str:
+    """Generate an explanation prompt."""
+    return f"Explain {topic} using clear examples and analogies."
+```
+
+The decorator supports: `name`, `title`, `description`, `icons`, `tags`, and `meta`.
+
+## Directory Structure
+
+The directory structure is purely organizational. The provider recursively scans all `.py` files regardless of which subdirectory they're in. Subdirectories like `tools/`, `resources/`, and `prompts/` are optional conventions that help you organize code.
+
+```
+components/
+├── tools/
+│   ├── greeting.py      # @tool functions
+│   └── calculator.py    # @tool functions
+├── resources/
+│   └── config.py        # @resource functions
+└── prompts/
+    └── assistant.py     # @prompt functions
+```
+
+You can also put all components in a single file or organize by feature rather than type.
+
+```
+components/
+├── user_management.py   # @tool, @resource, @prompt for users
+├── billing.py           # @tool, @resource for billing
+└── analytics.py         # @tool for analytics
+```
+
+## Discovery Rules
+
+The provider follows these rules when scanning:
+
+| Rule | Behavior |
+|------|----------|
+| File extensions | Only `.py` files are scanned |
+| `__init__.py` | Skipped (used for package structure, not components) |
+| `__pycache__` | Skipped |
+| Private functions | Functions starting with `_` are ignored, even if decorated |
+| No decorators | Files without `@tool`, `@resource`, or `@prompt` are silently skipped |
+| Multiple components | A single file can contain any number of decorated functions |
+
+### Package Imports
+
+If your directory contains an `__init__.py` file, the provider imports files as proper Python package members. This means relative imports work correctly within your components directory.
+
+```python
+# components/__init__.py exists
+
+# components/tools/greeting.py
+from ..helpers import format_name  # Relative imports work
+
+@tool
+def greet(name: str) -> str:
+    return f"Hello, {format_name(name)}!"
+```
+
+Without `__init__.py`, files are imported directly using `importlib.util.spec_from_file_location`.
+
+## Reload Mode
+
+During development, you may want changes to component files to take effect without restarting the server. Enable reload mode to re-scan the directory on every request.
+
+```python
+from pathlib import Path
+
+from fastmcp.server.providers import FileSystemProvider
+
+provider = FileSystemProvider(Path(__file__).parent / "components", reload=True)
+```
+
+With `reload=True`, the provider:
+
+1. Re-discovers all Python files on each request
+2. Re-imports modules that have changed
+3. Updates the component registry with any new, modified, or removed components
+
+<Warning>
+Reload mode adds overhead to every request. Use it only during development, not in production.
+</Warning>
+
+## Error Handling
+
+When a file fails to import (syntax error, missing dependency, etc.), the provider logs a warning and continues scanning other files. Failed imports don't prevent the server from starting.
+
+```
+WARNING - Failed to import /path/to/broken.py: No module named 'missing_dep'
+```
+
+The provider tracks which files have failed and only re-logs warnings when the file's modification time changes. This prevents log spam when a broken file is repeatedly scanned in reload mode.
+
+## Example Project
+
+A complete example is available in the repository at `examples/filesystem-provider/`. The structure demonstrates the recommended organization.
+
+```
+examples/filesystem-provider/
+├── server.py                    # Server entry point
+└── components/
+    ├── tools/
+    │   ├── greeting.py          # greet, farewell tools
+    │   └── calculator.py        # add, multiply tools
+    ├── resources/
+    │   └── config.py            # Static and templated resources
+    └── prompts/
+        └── assistant.py         # code_review, explain prompts
+```
+
+The server entry point is minimal.
+
+```python
+from pathlib import Path
+
+from fastmcp import FastMCP
+from fastmcp.server.providers import FileSystemProvider
+
+provider = FileSystemProvider(
+    root=Path(__file__).parent / "components",
+    reload=True,
+)
+
+mcp = FastMCP("FilesystemDemo", providers=[provider])
+```
+
+Run with `fastmcp run examples/filesystem-provider/server.py` or inspect with `fastmcp inspect examples/filesystem-provider/server.py`.
diff --git a/docs/servers/providers/local.mdx b/docs/servers/providers/local.mdx
new file mode 100644
index 0000000..8672665
--- /dev/null
+++ b/docs/servers/providers/local.mdx
@@ -0,0 +1,161 @@
+---
+title: Local Provider
+sidebarTitle: Local
+description: The default provider for decorator-registered components
+icon: house
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+`LocalProvider` stores components that you define directly on your server. When you use `@mcp.tool`, `@mcp.resource`, or `@mcp.prompt`, you're adding components to your server's `LocalProvider`.
+
+## How It Works
+
+Every FastMCP server has a `LocalProvider` as its first provider. Components registered via decorators or direct methods are stored here:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")
+
+# These are stored in the server's `LocalProvider`
+@mcp.tool
+def greet(name: str) -> str:
+    """Greet someone by name."""
+    return f"Hello, {name}!"
+
+@mcp.resource("data://config")
+def get_config() -> str:
+    """Return configuration data."""
+    return '{"version": "1.0"}'
+
+@mcp.prompt
+def analyze(topic: str) -> str:
+    """Create an analysis prompt."""
+    return f"Please analyze: {topic}"
+```
+
+The `LocalProvider` is always queried first when clients request components, ensuring that your directly-defined components take precedence over those from mounted or proxied servers.
+
+## Component Registration
+
+### Using Decorators
+
+The most common way to register components:
+
+```python
+@mcp.tool
+def my_tool(x: int) -> str:
+    return str(x)
+
+@mcp.resource("data://info")
+def my_resource() -> str:
+    return "info"
+
+@mcp.prompt
+def my_prompt(topic: str) -> str:
+    return f"Discuss: {topic}"
+```
+
+### Using Direct Methods
+
+You can also add pre-built component objects:
+
+```python
+from fastmcp.tools import Tool
+
+# Create a tool object
+my_tool = Tool.from_function(some_function, name="custom_tool")
+
+# Add it to the server
+mcp.add_tool(my_tool)
+mcp.add_resource(my_resource)
+mcp.add_prompt(my_prompt)
+```
+
+### Removing Components
+
+Remove components by name or URI:
+
+```python
+mcp.local_provider.remove_tool("my_tool")
+mcp.local_provider.remove_resource("data://info")
+mcp.local_provider.remove_prompt("my_prompt")
+```
+
+## Duplicate Handling
+
+When you try to add a component that already exists, the behavior depends on the `on_duplicate` setting:
+
+| Mode | Behavior |
+|------|----------|
+| `"error"` (default) | Raise `ValueError` |
+| `"warn"` | Log warning and replace |
+| `"replace"` | Silently replace |
+| `"ignore"` | Keep existing component |
+
+Configure this when creating the server:
+
+```python
+mcp = FastMCP("MyServer", on_duplicate="warn")
+```
+
+## Component Visibility
+
+<VersionBadge version="3.0.0" />
+
+Components can be dynamically enabled or disabled at runtime. Disabled components don't appear in listings and can't be called.
+
+```python
+@mcp.tool(tags={"admin"})
+def delete_all() -> str:
+    """Delete everything."""
+    return "Deleted"
+
+@mcp.tool
+def get_status() -> str:
+    """Get system status."""
+    return "OK"
+
+# Disable admin tools
+mcp.disable(tags={"admin"})
+
+# Or only enable specific tools
+mcp.enable(keys={"tool:get_status"}, only=True)
+```
+
+See [Visibility](/servers/visibility) for the full documentation on keys, tags, allowlist mode, and provider-level control.
+
+## Standalone LocalProvider
+
+You can create a LocalProvider independently and attach it to multiple servers:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers import LocalProvider
+
+# Create a reusable provider
+shared_tools = LocalProvider()
+
+@shared_tools.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+@shared_tools.resource("data://version")
+def get_version() -> str:
+    return "1.0.0"
+
+# Attach to multiple servers
+server1 = FastMCP("Server1", providers=[shared_tools])
+server2 = FastMCP("Server2", providers=[shared_tools])
+```
+
+This is useful for:
+- Sharing components across servers
+- Testing components in isolation
+- Building reusable component libraries
+
+Standalone providers also support visibility control with `enable()` and `disable()`. See [Visibility](/servers/visibility) for details.
diff --git a/docs/servers/providers/overview.mdx b/docs/servers/providers/overview.mdx
new file mode 100644
index 0000000..d3e3e4e
--- /dev/null
+++ b/docs/servers/providers/overview.mdx
@@ -0,0 +1,81 @@
+---
+title: Providers
+sidebarTitle: Overview
+description: How FastMCP sources tools, resources, and prompts
+icon: layer-group
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+Every FastMCP server has one or more component providers. A provider is a source of tools, resources, and prompts - it's what makes components available to clients.
+
+## What Is a Provider?
+
+When a client connects to your server and asks "what tools do you have?", FastMCP asks each provider that question and combines the results. When a client calls a specific tool, FastMCP finds which provider has it and delegates the call.
+
+You're already using providers. When you write `@mcp.tool`, you're adding a tool to your server's `LocalProvider` - the default provider that stores components you define directly in code. You just don't have to think about it for simple servers.
+
+Providers become important when your components come from multiple sources: another FastMCP server to include, a remote MCP server to proxy, or a database where tools are defined dynamically. Each source gets its own provider, and FastMCP queries them all seamlessly.
+
+## Why Providers?
+
+The provider abstraction solves a common problem: as servers grow, you need to organize components across multiple sources without tangling everything together.
+
+**Composition**: Break a large server into focused modules. A "weather" server and a "calendar" server can each be developed independently, then mounted into a main server. Each mounted server becomes a `FastMCPProvider`.
+
+**Proxying**: Expose a remote MCP server through your local server. Maybe you're bridging transports (remote HTTP to local stdio) or aggregating multiple backends. Remote connections become `ProxyProvider` instances.
+
+**Dynamic sources**: Load tools from a database, generate them from an OpenAPI spec, or create them based on user permissions. Custom providers let components come from anywhere.
+
+## Built-in Providers
+
+FastMCP includes providers for common patterns:
+
+| Provider | What it does | How you use it |
+|----------|--------------|----------------|
+| `LocalProvider` | Stores components you define in code | `@mcp.tool`, `mcp.add_tool()` |
+| `FastMCPProvider` | Wraps another FastMCP server | `mcp.mount(server)` |
+| `ProxyProvider` | Connects to remote MCP servers | `create_proxy(client)` |
+
+Most users only interact with `LocalProvider` (through decorators) and occasionally mount or proxy other servers. The provider abstraction stays invisible until you need it.
+
+## Transforms
+
+[Transforms](/servers/transforms/transforms) modify components as they flow from providers to clients. Each transform sits in a chain, intercepting queries and modifying results before passing them along.
+
+| Transform | Purpose |
+|-----------|---------|
+| `Namespace` | Prefixes names to avoid conflicts |
+| `ToolTransform` | Modifies tool schemas (rename, description, arguments) |
+
+The most common use is namespacing mounted servers to prevent name collisions. When you call `mount(server, namespace="api")`, FastMCP creates a `Namespace` transform automatically.
+
+Transforms can be added to individual providers (affecting just that source) or to the server itself (affecting all components). See [Transforms](/servers/transforms/transforms) for the full picture.
+
+## Provider Order
+
+When a client requests a tool, FastMCP queries providers in registration order. The first provider that has the tool handles the request.
+
+`LocalProvider` is always first, so your decorator-defined tools take precedence. Additional providers are queried in the order you added them. This means if two providers have a tool with the same name, the first one wins.
+
+## When to Care About Providers
+
+**You can ignore providers entirely** if you're building a simple server with decorators. Just use `@mcp.tool`, `@mcp.resource`, and `@mcp.prompt` - FastMCP handles the rest.
+
+**Learn about providers when** you want to:
+- [Mount another server](/servers/composition) into yours
+- [Proxy a remote server](/servers/providers/proxy) through yours
+- [Control visibility state](/servers/visibility) of components
+- [Build dynamic sources](/servers/providers/custom) like database-backed tools
+
+## Next Steps
+
+- [Local](/servers/providers/local) - How decorators work
+- [Mounting](/servers/composition) - Compose servers together
+- [Proxying](/servers/providers/proxy) - Connect to remote servers
+- [Transforms](/servers/transforms/transforms) - Namespace, rename, and modify components
+- [Visibility](/servers/visibility) - Control which components clients can access
+- [Custom](/servers/providers/custom) - Build your own providers
diff --git a/docs/servers/providers/proxy.mdx b/docs/servers/providers/proxy.mdx
new file mode 100644
index 0000000..9d64b61
--- /dev/null
+++ b/docs/servers/providers/proxy.mdx
@@ -0,0 +1,353 @@
+---
+title: MCP Proxy Provider
+sidebarTitle: MCP Proxy
+description: Source components from other MCP servers
+icon: arrows-retweet
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.0.0" />
+
+The Proxy Provider sources components from another MCP server through a client connection. This lets you expose any MCP server's tools, resources, and prompts through your own server, whether the source is local or accessed over the network.
+
+## Why Use Proxy Provider
+
+The Proxy Provider enables:
+
+- **Bridge transports**: Make an HTTP server available via stdio, or vice versa
+- **Aggregate servers**: Combine multiple source servers into one unified server
+- **Add security**: Act as a controlled gateway with authentication and authorization
+- **Simplify access**: Provide a stable endpoint even if backend servers change
+
+```mermaid
+sequenceDiagram
+    participant Client as Your Client
+    participant Proxy as FastMCP Proxy
+    participant Backend as Source Server
+
+    Client->>Proxy: MCP Request (stdio)
+    Proxy->>Backend: MCP Request (HTTP/stdio/SSE)
+    Backend-->>Proxy: MCP Response
+    Proxy-->>Client: MCP Response
+```
+
+## Quick Start
+
+<VersionBadge version="2.10.3" />
+
+Create a proxy using `create_proxy()`:
+
+```python
+from fastmcp.server import create_proxy
+
+# create_proxy() accepts URLs, file paths, and transports directly
+proxy = create_proxy("http://example.com/mcp", name="MyProxy")
+
+if __name__ == "__main__":
+    proxy.run()
+```
+
+This gives you:
+
+- Safe concurrent request handling
+- Automatic forwarding of MCP features (sampling, elicitation, etc.)
+- Session isolation to prevent context mixing
+
+<Tip>
+To mount a proxy inside another FastMCP server, see [Mounting External Servers](/servers/composition#mounting-external-servers).
+</Tip>
+
+## Connection Semantics
+
+FastMCP proxies are lazy bridges. Creating the proxy object and starting the local server do not contact the upstream server. The upstream connection begins when an MCP client sends an `initialize` request to the proxy.
+
+During initialization, the proxy initializes the upstream server before responding locally. If the upstream server is unavailable, the URL does not point to an MCP endpoint, or upstream authentication cannot complete, the proxy initialization fails. This keeps the local proxy's connection status aligned with the upstream server it represents.
+
+After initialization, the proxy forwards MCP requests such as `ping`, `tools/list`, `resources/list`, `prompts/list`, tool calls, resource reads, sampling, elicitation, logging, and progress through the upstream client.
+
+## Transport Bridging
+
+A common use case is bridging transports between servers:
+
+```python
+from fastmcp.server import create_proxy
+
+# Bridge HTTP server to local stdio
+http_proxy = create_proxy("http://example.com/mcp/sse", name="HTTP-to-stdio")
+
+# Run locally via stdio for Claude Desktop
+if __name__ == "__main__":
+    http_proxy.run()  # Defaults to stdio
+```
+
+Or expose a local server via HTTP:
+
+```python
+from fastmcp.server import create_proxy
+
+# Bridge local server to HTTP
+local_proxy = create_proxy("local_server.py", name="stdio-to-HTTP")
+
+if __name__ == "__main__":
+    local_proxy.run(transport="http", host="0.0.0.0", port=8080)
+```
+
+## Session Isolation
+
+<VersionBadge version="2.10.3" />
+
+`create_proxy()` provides session isolation - each request gets its own isolated backend session:
+
+```python
+from fastmcp.server import create_proxy
+
+# Each request creates a fresh backend session (recommended)
+proxy = create_proxy("backend_server.py")
+
+# Multiple clients can use this proxy simultaneously:
+# - Client A calls a tool → gets isolated session
+# - Client B calls a tool → gets different session
+# - No context mixing
+```
+
+### Shared Sessions
+
+If you pass an already-connected client, the proxy reuses that session:
+
+```python
+from fastmcp import Client
+from fastmcp.server import create_proxy
+
+async with Client("backend_server.py") as connected_client:
+    # This proxy reuses the connected session
+    proxy = create_proxy(connected_client)
+
+    # ⚠️ Warning: All requests share the same session
+```
+
+<Warning>
+Shared sessions may cause context mixing in concurrent scenarios. Use only in single-threaded situations or with explicit synchronization.
+</Warning>
+
+## MCP Feature Forwarding
+
+<VersionBadge version="2.10.3" />
+
+Proxies automatically forward MCP protocol features:
+
+| Feature | Description |
+|---------|-------------|
+| Roots | Filesystem root access requests |
+| Sampling | LLM completion requests |
+| Elicitation | User input requests |
+| Logging | Log messages from backend |
+| Progress | Progress notifications |
+
+```python
+from fastmcp.server import create_proxy
+
+# All features forwarded automatically
+proxy = create_proxy("advanced_backend.py")
+
+# When the backend:
+# - Requests LLM sampling → forwarded to your client
+# - Logs messages → appear in your client
+# - Reports progress → shown in your client
+```
+
+### Disabling Features
+
+Selectively disable forwarding:
+
+```python
+from fastmcp.server.providers.proxy import ProxyClient
+
+backend = ProxyClient(
+    "backend_server.py",
+    sampling_handler=None,  # Disable LLM sampling
+    log_handler=None        # Disable log forwarding
+)
+```
+
+## Configuration-Based Proxies
+
+<VersionBadge version="2.4.0" />
+
+Create proxies from configuration dictionaries:
+
+```python
+from fastmcp.server import create_proxy
+
+config = {
+    "mcpServers": {
+        "default": {
+            "url": "https://example.com/mcp",
+            "transport": "http"
+        }
+    }
+}
+
+proxy = create_proxy(config, name="Config-Based Proxy")
+```
+
+### Multi-Server Proxies
+
+Combine multiple servers with automatic namespacing:
+
+```python
+from fastmcp.server import create_proxy
+
+config = {
+    "mcpServers": {
+        "weather": {
+            "url": "https://weather-api.example.com/mcp",
+            "transport": "http"
+        },
+        "calendar": {
+            "url": "https://calendar-api.example.com/mcp",
+            "transport": "http"
+        }
+    }
+}
+
+# Creates unified proxy with prefixed components:
+# - weather_get_forecast
+# - calendar_add_event
+composite = create_proxy(config, name="Composite")
+```
+
+## Component Prefixing
+
+Proxied components follow standard prefixing rules:
+
+| Component Type | Pattern |
+|----------------|---------|
+| Tools | `{prefix}_{tool_name}` |
+| Prompts | `{prefix}_{prompt_name}` |
+| Resources | `protocol://{prefix}/path` |
+| Templates | `protocol://{prefix}/...` |
+
+## Mirrored Components
+
+<VersionBadge version="2.10.5" />
+
+Components from a proxy server are "mirrored" - they reflect the remote server's state and cannot be modified directly.
+
+To modify a proxied component (like disabling it), create a local copy:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server import create_proxy
+
+proxy = create_proxy("backend_server.py")
+
+# Get mirrored tool
+mirrored_tool = await proxy.get_tool("useful_tool")
+
+# Create modifiable local copy
+local_tool = mirrored_tool.copy()
+
+# Add to your own server
+my_server = FastMCP("MyServer")
+my_server.add_tool(local_tool)
+
+# Now you can control enabled state
+my_server.disable(keys={local_tool.key})
+```
+
+## Performance Considerations
+
+Proxying introduces network latency:
+
+| Operation | Local | Proxied (HTTP) |
+|-----------|-------|----------------|
+| `list_tools()` | 1-2ms | 300-400ms |
+| `call_tool()` | 1-2ms | 200-500ms |
+
+When mounting proxy servers, this latency affects all operations on the parent server.
+
+### Component List Caching
+
+<VersionBadge version="3.2.0" />
+
+`ProxyProvider` caches the backend's component lists (tools, resources, templates, prompts) so that individual lookups — like resolving a tool by name during `call_tool` — don't require a separate backend connection. The cache stores raw component metadata and is shared across all proxy sessions; per-session visibility, auth, and transforms are still applied after cache lookup by the server layer. The cache refreshes whenever an explicit `list_*` call is made, and entries expire after a configurable TTL (default 300 seconds).
+
+For backends whose component lists change dynamically, disable caching by setting `cache_ttl=0`.
+
+```python
+from fastmcp.server.providers.proxy import ProxyProvider, ProxyClient
+
+# Default 300s TTL
+provider = ProxyProvider(lambda: ProxyClient("http://backend/mcp"))
+
+# Custom TTL
+provider = ProxyProvider(lambda: ProxyClient("http://backend/mcp"), cache_ttl=60)
+
+# Disable caching
+provider = ProxyProvider(lambda: ProxyClient("http://backend/mcp"), cache_ttl=0)
+```
+
+### Session Reuse for Stateless Backends
+
+By default, each tool call opens a fresh MCP session to the backend. This is the safe default because it prevents state from leaking between requests. However, for stateless HTTP backends where there's no session state to protect, this overhead is unnecessary.
+
+You can reuse a single backend session by providing a client factory that returns the same client instance:
+
+```python
+from fastmcp.server.providers.proxy import FastMCPProxy, ProxyClient
+
+base_client = ProxyClient("http://backend:8000/mcp")
+shared_client = base_client.new()
+
+proxy = FastMCPProxy(
+    client_factory=lambda: shared_client,
+    name="ReusedSessionProxy",
+)
+```
+
+This eliminates the MCP initialization handshake on every call, which can dramatically reduce latency under load. The `Client` uses reference counting for its session lifecycle, so concurrent callers sharing the same instance is safe.
+
+<Warning>
+Only reuse sessions when you know the backend is stateless (e.g. stateless HTTP). For stateful backends (stdio processes, servers that track session state), use the default fresh-session behavior to avoid context mixing.
+</Warning>
+
+## Advanced Usage
+
+### FastMCPProxy Class
+
+For explicit session control, use `FastMCPProxy` directly:
+
+```python
+from fastmcp.server.providers.proxy import FastMCPProxy, ProxyClient
+
+# Custom session factory
+def create_client():
+    return ProxyClient("backend_server.py")
+
+proxy = FastMCPProxy(client_factory=create_client)
+```
+
+This gives you full control over session creation and reuse strategies.
+
+### Adding Proxied Components to Existing Server
+
+Mount a proxy to add components from another server:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server import create_proxy
+
+server = FastMCP("My Server")
+
+# Add local tools
+@server.tool
+def local_tool() -> str:
+    return "Local result"
+
+# Mount proxied tools from another server
+external = create_proxy("http://external-server/mcp")
+server.mount(external)
+
+# Now server has both local and proxied tools
+```
diff --git a/docs/servers/providers/skills.mdx b/docs/servers/providers/skills.mdx
new file mode 100644
index 0000000..0f8eff5
--- /dev/null
+++ b/docs/servers/providers/skills.mdx
@@ -0,0 +1,305 @@
+---
+title: Skills Provider
+sidebarTitle: Skills
+description: Expose agent skills as MCP resources
+icon: wand-magic-sparkles
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+Agent skills are directories containing instructions and supporting files that teach an AI assistant how to perform specific tasks. Tools like Claude Code, Cursor, and VS Code Copilot each have their own skills directories where users can add custom capabilities. The Skills Provider exposes these skill directories as MCP resources, making skills discoverable and shareable across different AI tools and clients.
+
+## Why Skills as Resources
+
+Skills live in platform-specific directories (`~/.claude/skills/`, `~/.cursor/skills/`, etc.) and typically contain a main instruction file plus supporting reference materials. When you want to share skills between tools or access them from a custom client, you need a way to discover and retrieve these files programmatically.
+
+The Skills Provider solves this by exposing each skill as a set of MCP resources. A client can list available skills, read the main instruction file, check the manifest to see what supporting files exist, and fetch any file it needs. This transforms local skill directories into a standardized API that works with any MCP client.
+
+## Quick Start
+
+Create a provider pointing to your skills directory, then add it to your server.
+
+```python
+from pathlib import Path
+
+from fastmcp import FastMCP
+from fastmcp.server.providers.skills import SkillsDirectoryProvider
+
+mcp = FastMCP("Skills Server")
+mcp.add_provider(SkillsDirectoryProvider(roots=Path.home() / ".claude" / "skills"))
+```
+
+Each subdirectory containing a `SKILL.md` file becomes a discoverable skill. Clients can then list resources to see available skills and read them as needed.
+
+```python
+from fastmcp import Client
+
+async with Client(mcp) as client:
+    # List all skill resources
+    resources = await client.list_resources()
+    for r in resources:
+        print(r.uri)  # skill://my-skill/SKILL.md, skill://my-skill/_manifest, ...
+
+    # Read a skill's main instruction file
+    result = await client.read_resource("skill://my-skill/SKILL.md")
+    print(result[0].text)
+```
+
+## Skill Structure
+
+A skill is a directory containing a main instruction file (default: `SKILL.md`) and optionally supporting files. The directory name becomes the skill's identifier.
+
+```
+~/.claude/skills/
+├── pdf-processing/
+│   ├── SKILL.md           # Main instructions
+│   ├── reference.md       # Supporting documentation
+│   └── examples/
+│       └── sample.pdf
+└── code-review/
+    └── SKILL.md
+```
+
+The main file can include YAML frontmatter to provide metadata. If no frontmatter exists, the provider extracts a description from the first meaningful line of content.
+
+```markdown
+---
+description: Process and extract information from PDF documents
+---
+
+# PDF Processing
+
+Instructions for handling PDFs...
+```
+
+## Resource URIs
+
+Each skill exposes three types of resources, all using the `skill://` URI scheme.
+
+The main instruction file contains the primary skill content. This is the resource clients read to understand what a skill does and how to use it.
+
+```
+skill://pdf-processing/SKILL.md
+```
+
+The manifest is a synthetic JSON resource listing all files in the skill directory with their sizes and SHA256 hashes. Clients use this to discover supporting files and verify content integrity.
+
+```
+skill://pdf-processing/_manifest
+```
+
+Reading the manifest returns structured file information.
+
+```json
+{
+  "skill": "pdf-processing",
+  "files": [
+    {"path": "SKILL.md", "size": 1234, "hash": "sha256:abc123..."},
+    {"path": "reference.md", "size": 567, "hash": "sha256:def456..."},
+    {"path": "examples/sample.pdf", "size": 89012, "hash": "sha256:ghi789..."}
+  ]
+}
+```
+
+Supporting files are any additional files in the skill directory. These might be reference documentation, code examples, or binary assets.
+
+```
+skill://pdf-processing/reference.md
+skill://pdf-processing/examples/sample.pdf
+```
+
+<Note>
+Supporting-file access is confined to the skill directory. Requested paths are validated before any filesystem access: attempts to traverse out with `..`, inject an absolute path, or smuggle a null byte are rejected with a clear error, and symlinks that resolve outside the skill directory are refused.
+</Note>
+
+## Provider Architecture
+
+The Skills Provider uses a two-layer architecture to handle both single skills and skill directories.
+
+### SkillProvider
+
+`SkillProvider` handles a single skill directory. It loads the main file, parses any frontmatter, scans for supporting files, and creates the appropriate resources.
+
+```python
+from pathlib import Path
+
+from fastmcp import FastMCP
+from fastmcp.server.providers.skills import SkillProvider
+
+mcp = FastMCP("Single Skill")
+mcp.add_provider(SkillProvider(Path.home() / ".claude" / "skills" / "pdf-processing"))
+```
+
+Use `SkillProvider` when you want to expose exactly one skill, or when you need fine-grained control over individual skill configuration.
+
+### SkillsDirectoryProvider
+
+`SkillsDirectoryProvider` scans one or more root directories and creates a `SkillProvider` for each valid skill folder it finds. A folder is considered a valid skill if it contains the main file (default: `SKILL.md`).
+
+```python
+from pathlib import Path
+
+from fastmcp import FastMCP
+from fastmcp.server.providers.skills import SkillsDirectoryProvider
+
+mcp = FastMCP("Skills")
+mcp.add_provider(SkillsDirectoryProvider(roots=Path.home() / ".claude" / "skills"))
+```
+
+When scanning multiple root directories, provide them as a list. The first directory takes precedence if the same skill name appears in multiple roots.
+
+```python
+from pathlib import Path
+
+from fastmcp import FastMCP
+from fastmcp.server.providers.skills import SkillsDirectoryProvider
+
+mcp = FastMCP("Skills")
+mcp.add_provider(SkillsDirectoryProvider(roots=[
+    Path.cwd() / ".claude" / "skills",      # Project-level skills first
+    Path.home() / ".claude" / "skills",     # User-level fallback
+]))
+```
+
+## Vendor Providers
+
+FastMCP includes pre-configured providers for popular AI coding tools. Each vendor provider extends `SkillsDirectoryProvider` with the appropriate default directory for that platform.
+
+| Provider | Default Directory |
+|----------|-------------------|
+| `ClaudeSkillsProvider` | `~/.claude/skills/` |
+| `CursorSkillsProvider` | `~/.cursor/skills/` |
+| `VSCodeSkillsProvider` | `~/.copilot/skills/` |
+| `CodexSkillsProvider` | `/etc/codex/skills/` and `~/.codex/skills/` |
+| `GeminiSkillsProvider` | `~/.gemini/skills/` |
+| `GooseSkillsProvider` | `~/.config/agents/skills/` |
+| `CopilotSkillsProvider` | `~/.copilot/skills/` |
+| `OpenCodeSkillsProvider` | `~/.config/opencode/skills/` |
+
+Vendor providers accept the same configuration options as `SkillsDirectoryProvider` (except for `roots`, which is locked to the platform default).
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers.skills import ClaudeSkillsProvider
+
+mcp = FastMCP("Claude Skills")
+mcp.add_provider(ClaudeSkillsProvider())  # Uses ~/.claude/skills/
+```
+
+`CodexSkillsProvider` scans both system-level (`/etc/codex/skills/`) and user-level (`~/.codex/skills/`) directories, with system skills taking precedence.
+
+## Supporting Files Disclosure
+
+The `supporting_files` parameter controls how supporting files (everything except the main file and manifest) appear to clients.
+
+### Template Mode (Default)
+
+With `supporting_files="template"`, supporting files are accessed through a `ResourceTemplate` rather than being listed as individual resources. Clients see only the main file and manifest in `list_resources()`, then discover supporting files by reading the manifest.
+
+```python
+from pathlib import Path
+
+from fastmcp.server.providers.skills import SkillsDirectoryProvider
+
+# Default behavior - supporting files hidden from list_resources()
+provider = SkillsDirectoryProvider(
+    roots=Path.home() / ".claude" / "skills",
+    supporting_files="template",  # This is the default
+)
+```
+
+This keeps the resource list compact when skills contain many files. Clients that need supporting files read the manifest first, then request specific files by URI.
+
+### Resources Mode
+
+With `supporting_files="resources"`, every file in every skill appears as an individual resource in `list_resources()`. Clients get full enumeration upfront without needing to read manifests.
+
+```python
+from pathlib import Path
+
+from fastmcp.server.providers.skills import SkillsDirectoryProvider
+
+# All files visible as individual resources
+provider = SkillsDirectoryProvider(
+    roots=Path.home() / ".claude" / "skills",
+    supporting_files="resources",
+)
+```
+
+Use this mode when clients need to discover all available files without additional round trips, or when integrating with tools that expect flat resource lists.
+
+## Reload Mode
+
+Enable reload mode to re-scan the skills directory on every request. Changes to skills take effect immediately without restarting the server.
+
+```python
+from pathlib import Path
+
+from fastmcp.server.providers.skills import SkillsDirectoryProvider
+
+provider = SkillsDirectoryProvider(
+    roots=Path.home() / ".claude" / "skills",
+    reload=True,
+)
+```
+
+With `reload=True`, the provider re-discovers skills on each `list_resources()` or `read_resource()` call. New skills appear, removed skills disappear, and modified content reflects current file state.
+
+<Warning>
+Reload mode adds overhead to every request. Use it during development when you're actively editing skills, but disable it in production.
+</Warning>
+
+## Client Utilities
+
+FastMCP provides utilities for downloading skills from any MCP server that exposes them. These are standalone functions in `fastmcp.utilities.skills`.
+
+### Discovering Skills
+
+Use `list_skills()` to see what skills are available on a server.
+
+```python
+from fastmcp import Client
+from fastmcp.utilities.skills import list_skills
+
+async with Client("http://skills-server/mcp") as client:
+    skills = await list_skills(client)
+    for skill in skills:
+        print(f"{skill.name}: {skill.description}")
+```
+
+### Downloading Skills
+
+Use `download_skill()` to download a single skill, or `sync_skills()` to download all available skills.
+
+```python
+from pathlib import Path
+
+from fastmcp import Client
+from fastmcp.utilities.skills import download_skill, sync_skills
+
+async with Client("http://skills-server/mcp") as client:
+    # Download one skill
+    path = await download_skill(client, "pdf-processing", Path.home() / ".claude" / "skills")
+
+    # Or download all skills
+    paths = await sync_skills(client, Path.home() / ".claude" / "skills")
+```
+
+Both functions accept an `overwrite` parameter. When `False` (default), existing skills are skipped. When `True`, existing files are replaced.
+
+### Inspecting Manifests
+
+Use `get_skill_manifest()` to see what files a skill contains before downloading.
+
+```python
+from fastmcp import Client
+from fastmcp.utilities.skills import get_skill_manifest
+
+async with Client("http://skills-server/mcp") as client:
+    manifest = await get_skill_manifest(client, "pdf-processing")
+    for file in manifest.files:
+        print(f"{file.path} ({file.size} bytes, {file.hash})")
+```
diff --git a/docs/servers/resources.mdx b/docs/servers/resources.mdx
new file mode 100644
index 0000000..c756c5f
--- /dev/null
+++ b/docs/servers/resources.mdx
@@ -0,0 +1,747 @@
+---
+title: Resources & Templates
+sidebarTitle: Resources
+description: Expose data sources and dynamic content generators to your MCP client.
+icon: folder-open
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+Resources represent data or files that an MCP client can read, and resource templates extend this concept by allowing clients to request dynamically generated resources based on parameters passed in the URI.
+
+FastMCP simplifies defining both static and dynamic resources, primarily using the `@mcp.resource` decorator.
+
+## What Are Resources?
+
+Resources provide read-only access to data for the LLM or client application. When a client requests a resource URI:
+
+1.  FastMCP finds the corresponding resource definition.
+2.  If it's dynamic (defined by a function), the function is executed.
+3.  The content (text, JSON, binary data) is returned to the client.
+
+This allows LLMs to access files, database content, configuration, or dynamically generated information relevant to the conversation.
+
+## Resources
+
+### The `@resource` Decorator
+
+The most common way to define a resource is by decorating a Python function. The decorator requires the resource's unique URI.
+
+```python
+import json
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="DataServer")
+
+# Basic dynamic resource returning a string
+@mcp.resource("resource://greeting")
+def get_greeting() -> str:
+    """Provides a simple greeting message."""
+    return "Hello from FastMCP Resources!"
+
+# Resource returning JSON data
+@mcp.resource("data://config")
+def get_config() -> str:
+    """Provides application configuration as JSON."""
+    return json.dumps({
+        "theme": "dark",
+        "version": "1.2.0",
+        "features": ["tools", "resources"],
+    })
+```
+
+**Key Concepts:**
+
+*   **URI:** The first argument to `@resource` is the unique URI (e.g., `"resource://greeting"`) clients use to request this data.
+*   **Lazy Loading:** The decorated function (`get_greeting`, `get_config`) is only executed when a client specifically requests that resource URI via `resources/read`.
+*   **Inferred Metadata:** By default:
+    *   Resource Name: Taken from the function name (`get_greeting`).
+    *   Resource Description: Taken from the function's docstring.
+
+#### Decorator Arguments
+
+You can customize the resource's properties using arguments in the `@mcp.resource` decorator:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="DataServer")
+
+# Example specifying metadata
+@mcp.resource(
+    uri="data://app-status",      # Explicit URI (required)
+    name="ApplicationStatus",     # Custom name
+    description="Provides the current status of the application.", # Custom description
+    mime_type="application/json", # Explicit MIME type
+    tags={"monitoring", "status"}, # Categorization tags
+    meta={"version": "2.1", "team": "infrastructure"}  # Custom metadata
+)
+def get_application_status() -> str:
+    """Internal function description (ignored if description is provided above)."""
+    return json.dumps({"status": "ok", "uptime": 12345, "version": mcp.settings.version})
+```
+
+<Card icon="code" title="@resource Decorator Arguments">
+<ParamField body="uri" type="str" required>
+  The unique identifier for the resource
+</ParamField>
+
+<ParamField body="name" type="str | None">
+  A human-readable name. If not provided, defaults to function name
+</ParamField>
+
+<ParamField body="description" type="str | None">
+  Explanation of the resource. If not provided, defaults to docstring
+</ParamField>
+
+<ParamField body="mime_type" type="str | None">
+  Specifies the content type. FastMCP often infers a default like `text/plain` or `application/json`, but explicit is better for non-text types
+</ParamField>
+
+<ParamField body="tags" type="set[str] | None">
+  A set of strings used to categorize the resource. These can be used by the server and, in some cases, by clients to filter or group available resources.
+</ParamField>
+
+<ParamField body="enabled" type="bool" default="True">
+  <Warning>Deprecated in v3.0.0. Use `mcp.enable()` / `mcp.disable()` at the server level instead.</Warning>
+  A boolean to enable or disable the resource. See [Component Visibility](#component-visibility) for the recommended approach.
+</ParamField>
+
+<ParamField body="icons" type="list[Icon] | None">
+  <VersionBadge version="2.13.0" />
+
+  Optional list of icon representations for this resource or template. See [Icons](/servers/icons) for detailed examples
+</ParamField>
+
+<ParamField body="annotations" type="Annotations | dict | None">
+    An optional `Annotations` object or dictionary to add additional metadata about the resource.
+  <Expandable title="Annotations attributes">
+    <ParamField body="readOnlyHint" type="bool | None">
+      If true, the resource is read-only and does not modify its environment.
+    </ParamField>
+    <ParamField body="idempotentHint" type="bool | None">
+      If true, reading the resource repeatedly will have no additional effect on its environment.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="meta" type="dict[str, Any] | None">
+  <VersionBadge version="2.11.0" />
+
+  Optional meta information about the resource. This data is passed through to the MCP client as the `meta` field of the client-side resource object and can be used for custom metadata, versioning, or other application-specific purposes.
+</ParamField>
+
+<ParamField body="version" type="str | int | None">
+  <VersionBadge version="3.0.0" />
+
+  Optional version identifier for this resource. See [Versioning](/servers/versioning) for details.
+</ParamField>
+</Card>
+
+#### Using with Methods
+
+For decorating instance or class methods, use the standalone `@resource` decorator and register the bound method. See [Tools: Using with Methods](/servers/tools#using-with-methods) for the pattern.
+
+### Return Values
+
+Resource functions must return one of three types:
+
+-   **`str`**: Sent as `TextResourceContents` (with `mime_type="text/plain"` by default).
+-   **`bytes`**: Base64 encoded and sent as `BlobResourceContents`. You should specify an appropriate `mime_type` (e.g., `"image/png"`, `"application/octet-stream"`).
+-   **`ResourceResult`**: Full control over contents, MIME types, and metadata. See [ResourceResult](#resourceresult) below.
+
+<Note>
+To return structured data like dicts or lists, serialize them to JSON strings using `json.dumps()`. This explicit approach ensures your type checker catches errors during development rather than at runtime when a client reads the resource.
+</Note>
+
+#### ResourceResult
+
+<VersionBadge version="3.0.0" />
+
+`ResourceResult` gives you explicit control over resource responses: multiple content items, per-item MIME types, and metadata at both the item and result level.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.resources import ResourceResult, ResourceContent
+
+mcp = FastMCP()
+
+@mcp.resource("data://users")
+def get_users() -> ResourceResult:
+    return ResourceResult(
+        contents=[
+            ResourceContent(content='[{"id": 1}]', mime_type="application/json"),
+            ResourceContent(content="# Users\n...", mime_type="text/markdown"),
+        ],
+        meta={"total": 1}
+    )
+```
+
+`ResourceContent` accepts three fields:
+
+**`content`** - The actual resource content. Can be `str` (text content) or `bytes` (binary content). This is the data that will be returned to the client.
+
+**`mime_type`** - Optional MIME type for the content. Defaults to `"text/plain"` for string content and `"application/octet-stream"` for binary content.
+
+**`meta`** - Optional metadata dictionary that will be included in the MCP response's `meta` field. Use this for runtime metadata like Content Security Policy headers, caching hints, or other client-specific data.
+
+For simple cases, you can pass `str` or `bytes` directly to `ResourceResult`:
+
+```python
+return ResourceResult("plain text")           # auto-converts to ResourceContent
+return ResourceResult(b"\x00\x01\x02")         # binary content
+```
+
+<Card title="ResourceResult">
+<ParamField body="contents" type="str | bytes | list[ResourceContent]" required>
+  Content to return. Strings and bytes are wrapped in a single `ResourceContent`. Use a list of `ResourceContent` for multiple items or custom MIME types.
+</ParamField>
+<ParamField body="meta" type="dict[str, Any] | None">
+  Result-level metadata, included in the MCP response's `_meta` field.
+</ParamField>
+</Card>
+
+<Card title="ResourceContent">
+<ParamField body="content" type="Any" required>
+  The content data. Strings and bytes pass through directly. Other types (dict, list, BaseModel) are automatically JSON-serialized.
+</ParamField>
+<ParamField body="mime_type" type="str | None">
+  MIME type. Defaults to `text/plain` for strings, `application/octet-stream` for bytes, `application/json` for serialized objects.
+</ParamField>
+<ParamField body="meta" type="dict[str, Any] | None">
+  Item-level metadata for this specific content.
+</ParamField>
+</Card>
+
+### Component Visibility
+
+<VersionBadge version="3.0.0" />
+
+You can control which resources are enabled for clients using server-level enabled control. Disabled resources don't appear in `list_resources` and can't be read.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")
+
+@mcp.resource("data://public", tags={"public"})
+def get_public(): return "public"
+
+@mcp.resource("data://secret", tags={"internal"})
+def get_secret(): return "secret"
+
+# Disable specific resources by key
+mcp.disable(keys={"resource:data://secret"})
+
+# Disable resources by tag
+mcp.disable(tags={"internal"})
+
+# Or use allowlist mode - only enable resources with specific tags
+mcp.enable(tags={"public"}, only=True)
+```
+
+See [Visibility](/servers/visibility) for the complete visibility control API including key formats, tag-based filtering, and provider-level control.
+
+
+### Accessing MCP Context
+
+<VersionBadge version="2.2.5" />
+
+Resources and resource templates can access additional MCP information and features through the `Context` object. To access it, add a parameter to your resource function with a type annotation of `Context`:
+
+```python {6, 14}
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP(name="DataServer")
+
+@mcp.resource("resource://system-status")
+async def get_system_status(ctx: Context) -> str:
+    """Provides system status information."""
+    return json.dumps({
+        "status": "operational",
+        "request_id": ctx.request_id
+    })
+
+@mcp.resource("resource://{name}/details")
+async def get_details(name: str, ctx: Context) -> str:
+    """Get details for a specific name."""
+    return json.dumps({
+        "name": name,
+        "accessed_at": ctx.request_id
+    })
+```
+
+For full documentation on the Context object and all its capabilities, see the [Context documentation](/servers/context).
+
+
+### Async Resources
+
+FastMCP supports both `async def` and regular `def` resource functions. Synchronous functions automatically run in a threadpool to avoid blocking the event loop.
+
+For I/O-bound operations, async functions are more efficient:
+
+```python
+import aiofiles
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="DataServer")
+
+@mcp.resource("file:///app/data/important_log.txt", mime_type="text/plain")
+async def read_important_log() -> str:
+    """Reads content from a specific log file asynchronously."""
+    try:
+        async with aiofiles.open("/app/data/important_log.txt", mode="r") as f:
+            content = await f.read()
+        return content
+    except FileNotFoundError:
+        return "Log file not found."
+```
+
+
+### Resource Classes
+
+While `@mcp.resource` is ideal for dynamic content, you can directly register pre-defined resources (like static files or simple text) using `mcp.add_resource()` and concrete `Resource` subclasses.
+
+```python
+from pathlib import Path
+from fastmcp import FastMCP
+from fastmcp.resources import FileResource, TextResource, DirectoryResource
+
+mcp = FastMCP(name="DataServer")
+
+# 1. Exposing a static file directly
+readme_path = Path("./README.md").resolve()
+if readme_path.exists():
+    # Use a file:// URI scheme
+    readme_resource = FileResource(
+        uri=f"file://{readme_path.as_posix()}",
+        path=readme_path, # Path to the actual file
+        name="README File",
+        description="The project's README.",
+        mime_type="text/markdown",
+        tags={"documentation"}
+    )
+    mcp.add_resource(readme_resource)
+
+# 2. Exposing simple, predefined text
+notice_resource = TextResource(
+    uri="resource://notice",
+    name="Important Notice",
+    text="System maintenance scheduled for Sunday.",
+    tags={"notification"}
+)
+mcp.add_resource(notice_resource)
+
+# 3. Exposing a directory listing
+data_dir_path = Path("./app_data").resolve()
+if data_dir_path.is_dir():
+    data_listing_resource = DirectoryResource(
+        uri="resource://data-files",
+        path=data_dir_path, # Path to the directory
+        name="Data Directory Listing",
+        description="Lists files available in the data directory.",
+        recursive=False # Set to True to list subdirectories
+    )
+    mcp.add_resource(data_listing_resource) # Returns JSON list of files
+```
+
+**Common Resource Classes:**
+
+-   `TextResource`: For simple string content.
+-   `BinaryResource`: For raw `bytes` content.
+-   `FileResource`: Reads content from a local file path. Handles text/binary modes, encoding, and lazy reading.
+-   `HttpResource`: Fetches content from an HTTP(S) URL (requires `httpx`).
+-   `DirectoryResource`: Lists files in a local directory (returns JSON).
+-   (`FunctionResource`: Internal class used by `@mcp.resource`).
+
+Use these when the content is static or sourced directly from a file/URL, bypassing the need for a dedicated Python function.
+
+### Notifications
+
+<VersionBadge version="2.9.1" />
+
+FastMCP automatically sends `notifications/resources/list_changed` notifications to connected clients when resources or templates are added, enabled, or disabled. This allows clients to stay up-to-date with the current resource set without manually polling for changes.
+
+```python
+@mcp.resource("data://example")
+def example_resource() -> str:
+    return "Hello!"
+
+# These operations trigger notifications:
+mcp.add_resource(example_resource)                   # Sends resources/list_changed notification
+mcp.disable(keys={"resource:data://example"})        # Sends resources/list_changed notification
+mcp.enable(keys={"resource:data://example"})         # Sends resources/list_changed notification
+```
+
+Notifications are only sent when these operations occur within an active MCP request context (e.g., when called from within a tool or other MCP operation). Operations performed during server initialization do not trigger notifications.
+
+Clients can handle these notifications using a [message handler](/clients/notifications) to automatically refresh their resource lists or update their interfaces.
+
+### Annotations
+
+<VersionBadge version="2.11.0" />
+
+FastMCP allows you to add specialized metadata to your resources through annotations. These annotations communicate how resources behave to client applications without consuming token context in LLM prompts.
+
+Annotations serve several purposes in client applications:
+- Indicating whether resources are read-only or may have side effects
+- Describing the safety profile of resources (idempotent vs. non-idempotent)
+- Helping clients optimize caching and access patterns
+
+You can add annotations to a resource using the `annotations` parameter in the `@mcp.resource` decorator:
+
+```python
+@mcp.resource(
+    "data://config",
+    annotations={
+        "readOnlyHint": True,
+        "idempotentHint": True
+    }
+)
+def get_config() -> str:
+    """Get application configuration."""
+    return json.dumps({"version": "1.0", "debug": False})
+```
+
+FastMCP supports these standard annotations:
+
+| Annotation | Type | Default | Purpose |
+| :--------- | :--- | :------ | :------ |
+| `readOnlyHint` | boolean | true | Indicates if the resource only provides data without side effects |
+| `idempotentHint` | boolean | true | Indicates if repeated reads have the same effect as a single read |
+
+Remember that annotations help make better user experiences but should be treated as advisory hints. They help client applications present appropriate UI elements and optimize access patterns, but won't enforce behavior on their own. Always focus on making your annotations accurately represent what your resource actually does.
+
+## Resource Templates
+
+Resource Templates allow clients to request resources whose content depends on parameters embedded in the URI. Define a template using the **same `@mcp.resource` decorator**, but include `{parameter_name}` placeholders in the URI string and add corresponding arguments to your function signature.
+
+Resource templates share most configuration options with regular resources (name, description, mime_type, tags, annotations), but add the ability to define URI parameters that map to function parameters.
+
+Resource templates generate a new resource for each unique set of parameters, which means that resources can be dynamically created on-demand. For example, if the resource template `"user://profile/{name}"` is registered, MCP clients could request `"user://profile/ford"` or `"user://profile/marvin"` to retrieve either of those two user profiles as resources, without having to register each resource individually.
+
+<Tip>
+Functions with `*args` are not supported as resource templates. However, unlike tools and prompts, resource templates do support `**kwargs` because the URI template defines specific parameter names that will be collected and passed as keyword arguments.
+</Tip>
+
+Here is a complete example that shows how to define two resource templates:
+
+```python
+import json
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="DataServer")
+
+# Template URI includes {city} placeholder
+@mcp.resource("weather://{city}/current")
+def get_weather(city: str) -> str:
+    """Provides weather information for a specific city."""
+    return json.dumps({
+        "city": city.capitalize(),
+        "temperature": 22,
+        "condition": "Sunny",
+        "unit": "celsius"
+    })
+
+# Template with multiple parameters and annotations
+@mcp.resource(
+    "repos://{owner}/{repo}/info",
+    annotations={
+        "readOnlyHint": True,
+        "idempotentHint": True
+    }
+)
+def get_repo_info(owner: str, repo: str) -> str:
+    """Retrieves information about a GitHub repository."""
+    return json.dumps({
+        "owner": owner,
+        "name": repo,
+        "full_name": f"{owner}/{repo}",
+        "stars": 120,
+        "forks": 48
+    })
+```
+
+With these two templates defined, clients can request a variety of resources:
+- `weather://london/current` → Returns weather for London
+- `weather://paris/current` → Returns weather for Paris
+- `repos://PrefectHQ/fastmcp/info` → Returns info about the PrefectHQ/fastmcp repository
+- `repos://prefecthq/prefect/info` → Returns info about the prefecthq/prefect repository
+
+### RFC 6570 URI Templates
+
+
+FastMCP implements [RFC 6570 URI Templates](https://datatracker.ietf.org/doc/html/rfc6570) for resource templates, providing a standardized way to define parameterized URIs. This includes support for simple expansion, wildcard path parameters, and form-style query parameters.
+
+#### Wildcard Parameters
+
+<VersionBadge version="2.2.4" />
+
+Resource templates support wildcard parameters that can match multiple path segments. Standard parameters (`{param}`) match a single URI segment before decoding and do not cross literal "/" boundaries in the request URI. Wildcard parameters (`{param*}`) can capture multiple segments including slashes. Wildcards capture all subsequent path segments *up until* the defined part of the URI template (whether literal or another parameter). This allows you to have multiple wildcard parameters in a single URI template.
+
+```python {15, 23}
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="DataServer")
+
+
+# Standard parameter only matches one segment
+@mcp.resource("files://{filename}")
+def get_file(filename: str) -> str:
+    """Retrieves a file by name."""
+    # Will only match files://<single-segment>
+    return f"File content for: {filename}"
+
+
+# Wildcard parameter can match multiple segments
+@mcp.resource("path://{filepath*}")
+def get_path_content(filepath: str) -> str:
+    """Retrieves content at a specific path."""
+    # Can match path://docs/server/resources.mdx
+    return f"Content at path: {filepath}"
+
+
+# Mixing standard and wildcard parameters
+@mcp.resource("repo://{owner}/{path*}/template.py")
+def get_template_file(owner: str, path: str) -> dict:
+    """Retrieves a file from a specific repository and path, but
+    only if the resource ends with `template.py`"""
+    # Can match repo://PrefectHQ/fastmcp/src/resources/template.py
+    return {
+        "owner": owner,
+        "path": path + "/template.py",
+        "content": f"File at {path}/template.py in {owner}'s repository"
+    }
+```
+
+Wildcard parameters are useful when:
+
+- Working with file paths or hierarchical data
+- Creating APIs that need to capture variable-length path segments
+- Building URL-like patterns similar to REST APIs
+
+Note that like regular parameters, each wildcard parameter must still be a named parameter in your function signature, and all required function parameters must appear in the URI template.
+
+#### Filesystem Path Safety
+
+Template parameters are decoded before your function receives them. A standard `{filename}` parameter matches one URI segment before decoding, so a request like `files://a%2Fb` passes `filename="a/b"` to the handler. Treat template values as untrusted decoded URI data whenever they determine filesystem paths.
+
+Validate the final resolved path against an allowed root before reading:
+
+```python
+from pathlib import Path
+
+from fastmcp import FastMCP
+from fastmcp.exceptions import ResourceError
+
+mcp = FastMCP(name="DocsServer")
+DOCS_ROOT = Path("docs").resolve()
+
+
+@mcp.resource("docs://{filename}")
+def read_doc(filename: str) -> str:
+    requested_path = (DOCS_ROOT / filename).resolve()
+
+    if not requested_path.is_relative_to(DOCS_ROOT) or not requested_path.is_file():
+        raise ResourceError("Document not found")
+
+    return requested_path.read_text(encoding="utf-8")
+```
+
+Use wildcard parameters (`{path*}`) for resources whose URI shape intentionally includes slashes, and apply the same containment check before accessing the filesystem.
+
+#### Query Parameters
+
+<VersionBadge version="2.13.0" />
+
+FastMCP supports RFC 6570 form-style query parameters using the `{?param1,param2}` syntax. Query parameters provide a clean way to pass optional configuration to resources without cluttering the path.
+
+Query parameters must be optional function parameters (have default values), while path parameters map to required function parameters. This enforces a clear separation: required data goes in the path, optional configuration in query params.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="DataServer")
+
+# Basic query parameters
+@mcp.resource("data://{id}{?format}")
+def get_data(id: str, format: str = "json") -> str:
+    """Retrieve data in specified format."""
+    if format == "xml":
+        return f"<data id='{id}' />"
+    return f'{{"id": "{id}"}}'
+
+# Multiple query parameters with type coercion
+@mcp.resource("api://{endpoint}{?version,limit,offset}")
+def call_api(endpoint: str, version: int = 1, limit: int = 10, offset: int = 0) -> dict:
+    """Call API endpoint with pagination."""
+    return {
+        "endpoint": endpoint,
+        "version": version,
+        "limit": limit,
+        "offset": offset,
+        "results": fetch_results(endpoint, version, limit, offset)
+    }
+
+# Query parameters with wildcards
+@mcp.resource("files://{path*}{?encoding,lines}")
+def read_file(path: str, encoding: str = "utf-8", lines: int = 100) -> str:
+    """Read file with optional encoding and line limit."""
+    return read_file_content(path, encoding, lines)
+```
+
+**Example requests:**
+- `data://123` → Uses default format `"json"`
+- `data://123?format=xml` → Uses format `"xml"`
+- `api://users?version=2&limit=50` → `version=2, limit=50, offset=0`
+- `files://src/main.py?encoding=ascii&lines=50` → Custom encoding and line limit
+
+FastMCP automatically coerces query parameter string values to the correct types based on your function's type hints (`int`, `float`, `bool`, `str`).
+
+**Query parameters vs. hidden defaults:**
+
+Query parameters expose optional configuration to clients. To hide optional parameters from clients entirely (always use defaults), simply omit them from the URI template:
+
+```python
+# Clients CAN override max_results via query string
+@mcp.resource("search://{query}{?max_results}")
+def search_configurable(query: str, max_results: int = 10) -> dict:
+    return {"query": query, "limit": max_results}
+
+# Clients CANNOT override max_results (not in URI template)
+@mcp.resource("search://{query}")
+def search_fixed(query: str, max_results: int = 10) -> dict:
+    return {"query": query, "limit": max_results}
+```
+
+### Template Parameter Rules
+
+<VersionBadge version="2.2.0" />
+
+FastMCP enforces these validation rules when creating resource templates:
+
+1. **Required function parameters** (no default values) must appear in the URI path template
+2. **Query parameters** (specified with `{?param}` syntax) must be optional function parameters with default values
+3. **All URI template parameters** (path and query) must exist as function parameters
+
+Optional function parameters (those with default values) can be:
+- Included as query parameters (`{?param}`) - clients can override via query string
+- Omitted from URI template - always uses default value, not exposed to clients
+- Used in alternative path templates - enables multiple ways to access the same resource
+
+**Multiple templates for one function:**
+
+Create multiple resource templates that expose the same function through different URI patterns by manually applying decorators:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="DataServer")
+
+# Define a user lookup function that can be accessed by different identifiers
+def lookup_user(name: str | None = None, email: str | None = None) -> dict:
+    """Look up a user by either name or email."""
+    if email:
+        return find_user_by_email(email)  # pseudocode
+    elif name:
+        return find_user_by_name(name)  # pseudocode
+    else:
+        return {"error": "No lookup parameters provided"}
+
+# Manually apply multiple decorators to the same function
+mcp.resource("users://email/{email}")(lookup_user)
+mcp.resource("users://name/{name}")(lookup_user)
+```
+
+Now an LLM or client can retrieve user information in two different ways:
+- `users://email/alice@example.com` → Looks up user by email (with name=None)
+- `users://name/Bob` → Looks up user by name (with email=None)
+
+This approach allows a single function to be registered with multiple URI patterns while keeping the implementation clean and straightforward.
+
+Templates provide a powerful way to expose parameterized data access points following REST-like principles.
+
+## Error Handling
+
+<VersionBadge version="2.4.1" />
+
+If your resource function encounters an error, you can raise a standard Python exception (`ValueError`, `TypeError`, `FileNotFoundError`, custom exceptions, etc.) or a FastMCP `ResourceError`.
+
+By default, all exceptions (including their details) are logged and converted into an MCP error response to be sent back to the client LLM. This helps the LLM understand failures and react appropriately.
+
+If you want to mask internal error details for security reasons, you can:
+
+1. Use the `mask_error_details=True` parameter when creating your `FastMCP` instance:
+```python
+mcp = FastMCP(name="SecureServer", mask_error_details=True)
+```
+
+2. Or use `ResourceError` to explicitly control what error information is sent to clients:
+```python
+from fastmcp import FastMCP
+from fastmcp.exceptions import ResourceError
+
+mcp = FastMCP(name="DataServer")
+
+@mcp.resource("resource://safe-error")
+def fail_with_details() -> str:
+    """This resource provides detailed error information."""
+    # ResourceError contents are always sent back to clients,
+    # regardless of mask_error_details setting
+    raise ResourceError("Unable to retrieve data: file not found")
+
+@mcp.resource("resource://masked-error")
+def fail_with_masked_details() -> str:
+    """This resource masks internal error details when mask_error_details=True."""
+    # This message would be masked if mask_error_details=True
+    raise ValueError("Sensitive internal file path: /etc/secrets.conf")
+
+@mcp.resource("data://{id}")
+def get_data_by_id(id: str) -> dict:
+    """Template resources also support the same error handling pattern."""
+    if id == "secure":
+        raise ValueError("Cannot access secure data")
+    elif id == "missing":
+        raise ResourceError("Data ID 'missing' not found in database")
+    return {"id": id, "value": "data"}
+```
+
+When `mask_error_details=True`, only error messages from `ResourceError` will include details, other exceptions will be converted to a generic message.
+
+## Server Behavior
+
+### Duplicate Resources
+
+<VersionBadge version="2.1.0" />
+
+You can configure how the FastMCP server handles attempts to register multiple resources or templates with the same URI. Use the `on_duplicate_resources` setting during `FastMCP` initialization.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(
+    name="ResourceServer",
+    on_duplicate_resources="error" # Raise error on duplicates
+)
+
+@mcp.resource("data://config")
+def get_config_v1(): return {"version": 1}
+
+# This registration attempt will raise a ValueError because
+# "data://config" is already registered and the behavior is "error".
+# @mcp.resource("data://config")
+# def get_config_v2(): return {"version": 2}
+```
+
+The duplicate behavior options are:
+
+-   `"warn"` (default): Logs a warning, and the new resource/template replaces the old one.
+-   `"error"`: Raises a `ValueError`, preventing the duplicate registration.
+-   `"replace"`: Silently replaces the existing resource/template with the new one.
+-   `"ignore"`: Keeps the original resource/template and ignores the new registration attempt.
+
+## Versioning
+
+<VersionBadge version="3.0.0" />
+
+Resources and resource templates support versioning, allowing you to maintain multiple implementations under the same URI while clients automatically receive the highest version. See [Versioning](/servers/versioning) for complete documentation on version comparison, retrieval, and migration patterns.
diff --git a/docs/servers/sampling.mdx b/docs/servers/sampling.mdx
new file mode 100644
index 0000000..d19a05c
--- /dev/null
+++ b/docs/servers/sampling.mdx
@@ -0,0 +1,587 @@
+---
+title: Sampling
+sidebarTitle: Sampling
+description: Request LLM text generation from the client or a configured provider through the MCP context.
+icon: robot
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.0.0" />
+
+<Warning>
+**Sampling is deprecated and will be removed in a future FastMCP release.**
+
+`ctx.sample()` and `ctx.sample_step()` rely on server-initiated `createMessage`
+requests, which MCP removed as of the 2026-07-28 protocol (SEP-2577). They work
+only on session-based (handshake-era) connections; on a 2026-07-28 connection
+they raise a clear error rather than reaching the client.
+
+**Migration:** call an LLM directly from your server using your own API key and
+provider SDK instead of borrowing the client's model. There is no drop-in
+replacement on modern connections — this architectural shift is the intended
+answer.
+</Warning>
+
+LLM sampling allows your MCP tools to request text generation from an LLM during execution. This enables tools to leverage AI capabilities for analysis, generation, reasoning, and more—without the client needing to orchestrate multiple calls.
+
+By default, sampling requests are routed to the client's LLM. You can also configure a fallback handler to use a specific provider (like OpenAI) when the client doesn't support sampling, or to always use your own LLM regardless of client capabilities.
+
+## Overview
+
+The simplest use of sampling is passing a prompt string to `ctx.sample()`. The method sends the prompt to the LLM, waits for the complete response, and returns a `SamplingResult`. You can access the generated text through the `.text` attribute.
+
+```python
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP()
+
+@mcp.tool
+async def summarize(content: str, ctx: Context) -> str:
+    """Generate a summary of the provided content."""
+    result = await ctx.sample(f"Please summarize this:\n\n{content}")
+    return result.text or ""
+```
+
+The `SamplingResult` also provides `.result` (identical to `.text` for plain text responses) and `.history` containing the full message exchange—useful if you need to continue the conversation or debug the interaction.
+
+### System Prompts
+
+System prompts let you establish the LLM's role and behavioral guidelines before it processes your request. This is useful for controlling tone, enforcing constraints, or providing context that shouldn't clutter the user-facing prompt.
+
+````python
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP()
+
+@mcp.tool
+async def generate_code(concept: str, ctx: Context) -> str:
+    """Generate a Python code example for a concept."""
+    result = await ctx.sample(
+        messages=f"Write a Python example demonstrating '{concept}'.",
+        system_prompt=(
+            "You are an expert Python programmer. "
+            "Provide concise, working code without explanations."
+        ),
+        temperature=0.7,
+        max_tokens=300
+    )
+    return f"```python\n{result.text}\n```"
+````
+
+The `temperature` parameter controls randomness—higher values (up to 1.0) produce more varied outputs, while lower values make responses more deterministic. The `max_tokens` parameter limits response length.
+
+### Model Preferences
+
+Model preferences let you hint at which LLM the client should use for a request. You can pass a single model name or a list of preferences in priority order. These are hints rather than requirements—the actual model used depends on what the client has available.
+
+```python
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP()
+
+@mcp.tool
+async def technical_analysis(data: str, ctx: Context) -> str:
+    """Analyze data using a reasoning-focused model."""
+    result = await ctx.sample(
+        messages=f"Analyze this data:\n\n{data}",
+        model_preferences=["claude-opus-4-5", "gpt-5-2"],
+        temperature=0.2,
+    )
+    return result.text or ""
+```
+
+Use model preferences when different tasks benefit from different model characteristics. Creative writing might prefer faster models with higher temperature, while complex analysis might benefit from larger reasoning-focused models.
+
+### Multi-Turn Conversations
+
+For requests that need conversational context, construct a list of `SamplingMessage` objects representing the conversation history. Each message has a `role` ("user" or "assistant") and `content` (a `TextContent` object).
+
+```python
+from fastmcp.types import SamplingMessage, TextContent
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP()
+
+@mcp.tool
+async def contextual_analysis(query: str, data: str, ctx: Context) -> str:
+    """Analyze data with conversational context."""
+    messages = [
+        SamplingMessage(
+            role="user",
+            content=TextContent(type="text", text=f"Here's my data: {data}"),
+        ),
+        SamplingMessage(
+            role="assistant",
+            content=TextContent(type="text", text="I see the data. What would you like to know?"),
+        ),
+        SamplingMessage(
+            role="user",
+            content=TextContent(type="text", text=query),
+        ),
+    ]
+    result = await ctx.sample(messages=messages)
+    return result.text or ""
+```
+
+The LLM receives the full conversation thread and responds with awareness of the preceding context.
+
+### Fallback Handlers
+
+Client support for sampling is optional—some clients may not implement it. To ensure your tools work regardless of client capabilities, configure a `sampling_handler` that sends requests directly to an LLM provider.
+
+FastMCP provides built-in handlers for [OpenAI and Anthropic APIs](/clients/sampling#built-in-handlers). These handlers support the full sampling API including tools, automatically converting your Python functions to each provider's format.
+
+<Note>
+Install handlers with `pip install fastmcp[openai]` or `pip install fastmcp[anthropic]`.
+</Note>
+
+```python
+from fastmcp import FastMCP
+from fastmcp.client.sampling.handlers.openai import OpenAISamplingHandler
+
+server = FastMCP(
+    name="My Server",
+    sampling_handler=OpenAISamplingHandler(default_model="gpt-4o-mini"),
+    sampling_handler_behavior="fallback",
+)
+```
+
+The `sampling_handler_behavior` parameter controls when the handler is used:
+
+- **`"fallback"`** (default): Use the handler only when the client doesn't support sampling. This lets capable clients use their own LLM while ensuring your tools still work with clients that lack sampling support.
+- **`"always"`**: Always use the handler, bypassing the client entirely. Use this when you need guaranteed control over which LLM processes requests—for cost control, compliance requirements, or when specific model characteristics are essential.
+
+## Structured Output
+
+<VersionBadge version="2.14.1" />
+
+When you need validated, typed data instead of free-form text, use the `result_type` parameter. FastMCP ensures the LLM returns data matching your type, handling validation and retries automatically.
+
+The `result_type` parameter accepts Pydantic models, dataclasses, and basic types like `int`, `list[str]`, or `dict[str, int]`. When you specify a result type, FastMCP automatically creates a `final_response` tool that the LLM calls to provide its response. If validation fails, the error is sent back to the LLM for retry.
+
+```python
+from pydantic import BaseModel
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP()
+
+class SentimentResult(BaseModel):
+    sentiment: str
+    confidence: float
+    reasoning: str
+
+@mcp.tool
+async def analyze_sentiment(text: str, ctx: Context) -> SentimentResult:
+    """Analyze text sentiment with structured output."""
+    result = await ctx.sample(
+        messages=f"Analyze the sentiment of: {text}",
+        result_type=SentimentResult,
+    )
+    return result.result  # A validated SentimentResult object
+```
+
+When you call this tool, the LLM returns a structured response that FastMCP validates against your Pydantic model. You access the validated object through `result.result`, while `result.text` contains the JSON representation.
+
+### Structured Output with Tools
+
+Combine structured output with tools for agentic workflows that return validated data. The LLM uses your tools to gather information, then returns a response matching your type.
+
+```python
+from pydantic import BaseModel
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP()
+
+def search(query: str) -> str:
+    """Search the web for information."""
+    return f"Results for: {query}"
+
+def fetch_url(url: str) -> str:
+    """Fetch content from a URL."""
+    return f"Content from: {url}"
+
+class ResearchResult(BaseModel):
+    summary: str
+    sources: list[str]
+    confidence: float
+
+@mcp.tool
+async def research(topic: str, ctx: Context) -> ResearchResult:
+    """Research a topic and return structured findings."""
+    result = await ctx.sample(
+        messages=f"Research: {topic}",
+        tools=[search, fetch_url],
+        result_type=ResearchResult,
+    )
+    return result.result
+```
+
+<Note>
+Structured output with automatic validation only applies to `sample()`. With `sample_step()`, you must manage structured output yourself.
+</Note>
+
+## Tool Use
+
+<VersionBadge version="2.14.1" />
+
+Sampling with tools enables agentic workflows where the LLM can call functions to gather information before responding. This implements [SEP-1577](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1577), allowing the LLM to autonomously orchestrate multi-step operations.
+
+Pass Python functions to the `tools` parameter, and FastMCP handles the execution loop automatically—calling tools, returning results to the LLM, and continuing until the LLM provides a final response.
+
+### Defining Tools
+
+Define regular Python functions with type hints and docstrings. FastMCP extracts the function's name, docstring, and parameter types to create tool schemas that the LLM can understand.
+
+```python
+from fastmcp import FastMCP, Context
+
+def search(query: str) -> str:
+    """Search the web for information."""
+    return f"Results for: {query}"
+
+def get_time() -> str:
+    """Get the current time."""
+    from datetime import datetime
+    return datetime.now().strftime("%H:%M:%S")
+
+mcp = FastMCP()
+
+@mcp.tool
+async def research(question: str, ctx: Context) -> str:
+    """Answer questions using available tools."""
+    result = await ctx.sample(
+        messages=question,
+        tools=[search, get_time],
+    )
+    return result.text or ""
+```
+
+The LLM sees each function's signature and docstring, using this information to decide when and how to call them. Tool errors are caught and sent back to the LLM, allowing it to recover gracefully. An internal safety limit prevents infinite loops.
+
+### Custom Tool Definitions
+
+For custom names or descriptions, use `SamplingTool.from_function()`:
+
+```python
+from fastmcp.server.sampling import SamplingTool
+
+tool = SamplingTool.from_function(
+    my_func,
+    name="custom_name",
+    description="Custom description"
+)
+
+result = await ctx.sample(messages="...", tools=[tool])
+```
+
+### Error Handling
+
+By default, when a sampling tool raises an exception, the error message (including details) is sent back to the LLM so it can attempt recovery. To prevent sensitive information from leaking to the LLM, use the `mask_error_details` parameter:
+
+```python
+result = await ctx.sample(
+    messages=question,
+    tools=[search],
+    mask_error_details=True,  # Generic error messages only
+)
+```
+
+When `mask_error_details=True`, tool errors become generic messages like `"Error executing tool 'search'"` instead of exposing stack traces or internal details.
+
+To intentionally provide specific error messages to the LLM regardless of masking, raise `ToolError`:
+
+```python
+from fastmcp.exceptions import ToolError
+
+def search(query: str) -> str:
+    """Search for information."""
+    if not query.strip():
+        raise ToolError("Search query cannot be empty")
+    return f"Results for: {query}"
+```
+
+`ToolError` messages always pass through to the LLM, making it the escape hatch for errors you want the LLM to see and handle.
+
+### Concurrent Tool Execution
+
+By default, tools execute sequentially — one at a time, in order. When your tools are independent (no shared state between them), you can execute them in parallel with `tool_concurrency`:
+
+```python
+result = await ctx.sample(
+    messages="Research these three topics",
+    tools=[search, fetch_url],
+    tool_concurrency=0,  # Unlimited parallel execution
+)
+```
+
+The `tool_concurrency` parameter controls how many tools run at once:
+
+- **`None`** (default): Sequential execution
+- **`0`**: Unlimited parallel execution
+- **`N > 0`**: Execute at most N tools concurrently
+
+For tools that must not run concurrently (file writes, shared state mutations, etc.), mark them as `sequential` when creating the `SamplingTool`:
+
+```python
+from fastmcp.server.sampling import SamplingTool
+
+db_writer = SamplingTool.from_function(
+    write_to_db,
+    sequential=True,  # Forces all tools in the batch to run sequentially
+)
+
+result = await ctx.sample(
+    messages="Process this data",
+    tools=[search, db_writer],
+    tool_concurrency=0,  # Would be parallel, but db_writer forces sequential
+)
+```
+
+<Note>
+When any tool in a batch has `sequential=True`, the entire batch executes sequentially regardless of `tool_concurrency`. This is a conservative guarantee — if one tool needs ordering, all tools in that batch respect it.
+</Note>
+
+### Client Requirements
+
+<Note>
+Sampling with tools requires the client to advertise the `sampling.tools` capability. FastMCP clients do this automatically. For external clients that don't support tool-enabled sampling, configure a fallback handler with `sampling_handler_behavior="always"`.
+</Note>
+
+## Advanced Control
+
+<VersionBadge version="2.14.1" />
+
+While `sample()` handles the tool execution loop automatically, some scenarios require fine-grained control over each step. The `sample_step()` method makes a single LLM call and returns a `SampleStep` containing the response and updated history.
+
+Unlike `sample()`, `sample_step()` is stateless—it doesn't remember previous calls. You control the conversation by passing the full message history each time. The returned `step.history` includes all messages up through the current response, making it easy to continue the loop.
+
+Use `sample_step()` when you need to:
+
+- Inspect tool calls before they execute
+- Implement custom termination conditions
+- Add logging, metrics, or checkpointing between steps
+- Build custom agentic loops with domain-specific logic
+
+### Basic Loop
+
+By default, `sample_step()` executes any tool calls and includes the results in the history. Call it in a loop, passing the updated history each time, until a stop condition is met.
+
+```python
+from fastmcp.types import SamplingMessage
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP()
+
+def search(query: str) -> str:
+    return f"Results for: {query}"
+
+def get_time() -> str:
+    return "12:00 PM"
+
+@mcp.tool
+async def controlled_agent(question: str, ctx: Context) -> str:
+    """Agent with manual loop control."""
+    messages: list[str | SamplingMessage] = [question]
+
+    while True:
+        step = await ctx.sample_step(
+            messages=messages,
+            tools=[search, get_time],
+        )
+
+        if step.is_tool_use:
+            # Tools already executed (execute_tools=True by default)
+            for call in step.tool_calls:
+                print(f"Called tool: {call.name}")
+
+        if not step.is_tool_use:
+            return step.text or ""
+
+        messages = step.history
+```
+
+### SampleStep Properties
+
+Each `SampleStep` provides information about what the LLM returned:
+
+| Property | Description |
+|----------|-------------|
+| `step.is_tool_use` | True if the LLM requested tool calls |
+| `step.tool_calls` | List of tool calls requested (if any) |
+| `step.text` | The text content (if any) |
+| `step.history` | All messages exchanged so far |
+
+The contents of `step.history` depend on `execute_tools`:
+- **`execute_tools=True`** (default): Includes tool results, ready for the next iteration
+- **`execute_tools=False`**: Includes the assistant's tool request, but you add results yourself
+
+### Manual Tool Execution
+
+Set `execute_tools=False` to handle tool execution yourself. When disabled, `step.history` contains the user message and the assistant's response with tool calls—but no tool results. You execute the tools and append the results as a user message.
+
+```python
+from fastmcp.types import SamplingMessage, ToolResultContent, TextContent
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP()
+
+@mcp.tool
+async def research(question: str, ctx: Context) -> str:
+    """Research with manual tool handling."""
+
+    def search(query: str) -> str:
+        return f"Results for: {query}"
+
+    def get_time() -> str:
+        return "12:00 PM"
+
+    tools = {"search": search, "get_time": get_time}
+    messages: list[SamplingMessage] = [question]
+
+    while True:
+        step = await ctx.sample_step(
+            messages=messages,
+            tools=list(tools.values()),
+            execute_tools=False,
+        )
+
+        if not step.is_tool_use:
+            return step.text or ""
+
+        # Execute tools and collect results
+        tool_results = []
+        for call in step.tool_calls:
+            fn = tools[call.name]
+            result = fn(**call.input)
+            tool_results.append(
+                ToolResultContent(
+                    type="tool_result",
+                    tool_use_id=call.id,
+                    content=[TextContent(type="text", text=result)],
+                )
+            )
+
+        messages = list(step.history)
+        messages.append(SamplingMessage(role="user", content=tool_results))
+```
+
+To report an error to the LLM, set `is_error=True` on the tool result:
+
+```python
+tool_result = ToolResultContent(
+    type="tool_result",
+    tool_use_id=call.id,
+    content=[TextContent(type="text", text="Permission denied")],
+    is_error=True,
+)
+```
+
+## Method Reference
+
+<Card icon="code" title="ctx.sample()">
+<ResponseField name="ctx.sample" type="async method">
+  Request text generation from the LLM, running to completion automatically.
+
+  <Expandable title="Parameters">
+    <ResponseField name="messages" type="str | list[str | SamplingMessage]">
+      The prompt to send. Can be a simple string or a list of messages for multi-turn conversations.
+    </ResponseField>
+
+    <ResponseField name="system_prompt" type="str | None" default="None">
+      Instructions that establish the LLM's role and behavior.
+    </ResponseField>
+
+    <ResponseField name="temperature" type="float | None" default="None">
+      Controls randomness (0.0 = deterministic, 1.0 = creative).
+    </ResponseField>
+
+    <ResponseField name="max_tokens" type="int | None" default="512">
+      Maximum tokens to generate.
+    </ResponseField>
+
+    <ResponseField name="model_preferences" type="str | list[str] | None" default="None">
+      Hints for which model the client should use.
+    </ResponseField>
+
+    <ResponseField name="tools" type="list[Callable] | None" default="None">
+      Functions the LLM can call during sampling.
+    </ResponseField>
+
+    <ResponseField name="result_type" type="type[T] | None" default="None">
+      A type for validated structured output. Supports Pydantic models, dataclasses, and basic types like `int`, `list[str]`, or `dict[str, int]`.
+    </ResponseField>
+
+    <ResponseField name="mask_error_details" type="bool | None" default="None">
+      If True, mask detailed error messages from tool execution. When None (default), uses the global `settings.mask_error_details` value. Tools can raise `ToolError` to bypass masking and provide specific error messages to the LLM.
+    </ResponseField>
+
+    <ResponseField name="tool_concurrency" type="int | None" default="None">
+      Controls parallel execution of tools. `None` (default) for sequential, `0` for unlimited parallel, or a positive integer for bounded concurrency. If any tool has `sequential=True`, all tools execute sequentially regardless.
+    </ResponseField>
+
+  </Expandable>
+
+  <Expandable title="Response">
+    <ResponseField name="SamplingResult[T]" type="dataclass">
+      - `.text`: The raw text response (or JSON for structured output)
+      - `.result`: The typed result—same as `.text` for plain text, or a validated Pydantic object for structured output
+      - `.history`: All messages exchanged during sampling
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+</Card>
+
+<Card icon="code" title="ctx.sample_step()">
+<ResponseField name="ctx.sample_step" type="async method">
+  Make a single LLM sampling call. Use this for fine-grained control over the sampling loop.
+
+  <Expandable title="Parameters">
+    <ResponseField name="messages" type="str | list[str | SamplingMessage]">
+      The prompt or conversation history.
+    </ResponseField>
+
+    <ResponseField name="system_prompt" type="str | None" default="None">
+      Instructions that establish the LLM's role and behavior.
+    </ResponseField>
+
+    <ResponseField name="temperature" type="float | None" default="None">
+      Controls randomness (0.0 = deterministic, 1.0 = creative).
+    </ResponseField>
+
+    <ResponseField name="max_tokens" type="int | None" default="512">
+      Maximum tokens to generate.
+    </ResponseField>
+
+    <ResponseField name="tools" type="list[Callable] | None" default="None">
+      Functions the LLM can call during sampling.
+    </ResponseField>
+
+    <ResponseField name="tool_choice" type="str | None" default="None">
+      Controls tool usage: `"auto"`, `"required"`, or `"none"`.
+    </ResponseField>
+
+    <ResponseField name="execute_tools" type="bool" default="True">
+      If True, execute tool calls and append results to history. If False, return immediately with tool calls available for manual execution.
+    </ResponseField>
+
+    <ResponseField name="mask_error_details" type="bool | None" default="None">
+      If True, mask detailed error messages from tool execution.
+    </ResponseField>
+
+    <ResponseField name="tool_concurrency" type="int | None" default="None">
+      Controls parallel execution of tools. `None` (default) for sequential, `0` for unlimited parallel, or a positive integer for bounded concurrency.
+    </ResponseField>
+  </Expandable>
+
+  <Expandable title="Response">
+    <ResponseField name="SampleStep" type="dataclass">
+      - `.response`: The raw LLM response
+      - `.history`: Messages including input, assistant response, and tool results
+      - `.is_tool_use`: True if the LLM requested tool execution
+      - `.tool_calls`: List of tool calls (if any)
+      - `.text`: The text content (if any)
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+</Card>
diff --git a/docs/servers/server.mdx b/docs/servers/server.mdx
new file mode 100644
index 0000000..9f6374a
--- /dev/null
+++ b/docs/servers/server.mdx
@@ -0,0 +1,314 @@
+---
+title: The FastMCP Server
+sidebarTitle: Overview
+description: The core FastMCP server class for building MCP applications
+icon: server
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+The `FastMCP` class is the central piece of every FastMCP application. It acts as the container for your tools, resources, and prompts, managing communication with MCP clients and orchestrating the entire server lifecycle.
+
+## Creating a Server
+
+At its simplest, a FastMCP server just needs a name. Everything else has sensible defaults.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")
+```
+
+Instructions help clients (and the LLMs behind them) understand what your server does and how to use it effectively.
+
+```python
+mcp = FastMCP(
+    "DataAnalysis",
+    instructions="Provides tools for analyzing numerical datasets. Start with get_summary() for an overview.",
+)
+```
+
+## Components
+
+FastMCP servers expose three types of components to clients, each serving a distinct role in the MCP protocol.
+
+**Tools** are functions that clients invoke to perform actions or access external systems.
+
+```python
+@mcp.tool
+def multiply(a: float, b: float) -> float:
+    """Multiplies two numbers together."""
+    return a * b
+```
+
+**Resources** expose data that clients can read — passive data sources rather than invocable functions.
+
+```python
+@mcp.resource("data://config")
+def get_config() -> dict:
+    return {"theme": "dark", "version": "1.0"}
+```
+
+**Prompts** are reusable message templates that guide LLM interactions.
+
+```python
+@mcp.prompt
+def analyze_data(data_points: list[float]) -> str:
+    formatted_data = ", ".join(str(point) for point in data_points)
+    return f"Please analyze these data points: {formatted_data}"
+```
+
+Each component type has detailed documentation: [Tools](/servers/tools), [Resources](/servers/resources) (including [Resource Templates](/servers/resources#resource-templates)), and [Prompts](/servers/prompts).
+
+## Running the Server
+
+Start your server by calling `mcp.run()`. The `if __name__` guard ensures compatibility with MCP clients that launch your server as a subprocess.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")
+
+@mcp.tool
+def greet(name: str) -> str:
+    """Greet a user by name."""
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+FastMCP supports several transports:
+- **STDIO** (default): For local integrations and CLI tools
+- **HTTP**: For web services using the Streamable HTTP protocol
+- **SSE**: Legacy web transport (deprecated)
+
+```python
+# Run with HTTP transport
+mcp.run(transport="http", host="127.0.0.1", port=9000)
+```
+
+The server can also be run using the FastMCP CLI. For detailed information on transports and deployment, see [Running Your Server](/deployment/running-server).
+
+
+## Configuration Reference
+
+The `FastMCP` constructor accepts parameters organized into four categories: identity, composition, behavior, and handlers.
+
+### Identity
+
+These parameters control how your server presents itself to clients.
+
+<Card>
+<ParamField body="name" type="str" default="FastMCP">
+  A human-readable name for your server, shown in client applications and logs
+</ParamField>
+
+<ParamField body="instructions" type="str | None">
+  Description of how to interact with this server. Clients surface these instructions to help LLMs understand the server's purpose and available functionality
+</ParamField>
+
+<ParamField body="version" type="str | None">
+  Version string for your server. Defaults to the FastMCP library version if not provided
+</ParamField>
+
+<ParamField body="website_url" type="str | None">
+  <VersionBadge version="2.13.0" />
+
+  URL to a website with more information about your server. Displayed in client applications
+</ParamField>
+
+<ParamField body="icons" type="list[Icon] | None">
+  <VersionBadge version="2.13.0" />
+
+  List of icon representations for your server. See [Icons](/servers/icons) for details
+</ParamField>
+
+<ParamField body="experimental_capabilities" type="dict[str, dict[str, Any]] | None">
+  <VersionBadge version="3.2.5" />
+
+  Arbitrary experimental capabilities to advertise in the MCP `initialize` response. Use this to declare cross-server interop conventions or draft extensions that follow the MCP spec's `experimental` field. Keys are capability names; values are free-form dicts. FastMCP's built-in derived capabilities (`tools`, `resources`, etc.) are unaffected — this only populates `capabilities.experimental`
+</ParamField>
+</Card>
+
+### Composition
+
+These parameters control what your server is built from — its components, middleware, providers, and lifecycle.
+
+<Card>
+<ParamField body="tools" type="list[Tool | Callable] | None">
+  Tools to register on the server. An alternative to the `@mcp.tool` decorator when you need to add tools programmatically
+</ParamField>
+
+<ParamField body="auth" type="OAuthProvider | TokenVerifier | None">
+  Authentication provider for securing HTTP-based transports. See [Authentication](/servers/auth/authentication) for configuration
+</ParamField>
+
+<ParamField body="middleware" type="list[Middleware] | None">
+  [Middleware](/servers/middleware) that intercepts and transforms every MCP message flowing through the server — requests, responses, and notifications in both directions. Use for cross-cutting concerns like logging, error handling, and rate limiting
+</ParamField>
+
+<ParamField body="providers" type="list[Provider] | None">
+  [Providers](/servers/providers/overview) that supply tools, resources, and prompts dynamically. Providers are queried at request time, so they can serve components from databases, APIs, or other external sources
+</ParamField>
+
+<ParamField body="transforms" type="list[Transform] | None">
+  <VersionBadge version="3.1.0" />
+
+  Server-level [transforms](/servers/transforms/transforms) to apply to all components. Transforms modify how tools, resources, and prompts are presented to clients — for example, [search transforms](/servers/transforms/tool-search) replace large catalogs with on-demand discovery
+</ParamField>
+
+<ParamField body="lifespan" type="Lifespan | AsyncContextManager | None">
+  Server-level setup and teardown logic that runs when the server starts and stops. See [Lifespans](/servers/lifespan) for composable lifespans
+</ParamField>
+</Card>
+
+### Behavior
+
+These parameters tune how the server processes requests and communicates with clients.
+
+<Card>
+<ParamField body="on_duplicate" type='Literal["warn", "error", "replace", "ignore"]' default="warn">
+  How to handle duplicate component registrations
+</ParamField>
+
+<ParamField body="strict_input_validation" type="bool" default="False">
+  <VersionBadge version="2.13.0" />
+
+  When `False` (default), FastMCP uses Pydantic's flexible validation that coerces compatible inputs (e.g., `"10"` → `10` for int parameters). When `True`, validates inputs against the exact JSON Schema before calling your function, rejecting type mismatches. See [Input Validation Modes](/servers/tools#input-validation-modes) for details
+</ParamField>
+
+<ParamField body="mask_error_details" type="bool | None">
+  When `True`, replaces internal error details in tool/resource responses with a generic message to avoid leaking implementation details to clients. Defaults to the `FASTMCP_MASK_ERROR_DETAILS` environment variable
+</ParamField>
+
+<ParamField body="list_page_size" type="int | None" default="None">
+  <VersionBadge version="3.0.0" />
+
+  Maximum items per page for list operations (`tools/list`, `resources/list`, etc.). When `None`, all results are returned in a single response. See [Pagination](/servers/pagination) for details
+</ParamField>
+
+<ParamField body="tasks" type="bool | None" default="False">
+  Enable background task support. When `True`, tools and resources can return `CreateTaskResult` to run work asynchronously while the client polls for results
+</ParamField>
+
+<ParamField body="client_log_level" type="LoggingLevel | None">
+  <VersionBadge version="3.2.0" />
+
+  Default minimum log level for messages sent to MCP clients via `context.log()`. When set, messages below this level are suppressed. Individual clients can override this per-session using the MCP `logging/setLevel` request. One of `"debug"`, `"info"`, `"notice"`, `"warning"`, `"error"`, `"critical"`, `"alert"`, or `"emergency"`
+</ParamField>
+
+<ParamField body="dereference_schemas" type="bool" default="True">
+  Automatically dereference `$ref` pointers in JSON schemas generated from complex Pydantic models. Most clients require flat schemas without `$ref`, so this should usually stay enabled
+</ParamField>
+
+<ParamField body="cache_ttl" type="int | None" default="None">
+  How long, in seconds, a client may treat this server's cacheable responses as fresh (SEP-2549). When set, the hint applies uniformly to `tools/list`, `prompts/list`, `resources/list`, `resources/templates/list`, and `resources/read`. Clients must opt into caching to honor it — see [Response caching](/clients/client#response-caching). Must be a positive integer
+</ParamField>
+
+<ParamField body="cache_scope" type='Literal["public", "private"] | None' default="None">
+  Whether a cached response may be shared across authorization contexts (`"public"`) or reused only within the one that produced it (`"private"`, the default when a `cache_ttl` is set). Requires `cache_ttl`
+</ParamField>
+</Card>
+
+### Handlers and Storage
+
+These parameters provide custom handlers for MCP capabilities and persistent storage for session state.
+
+<Card>
+<ParamField body="sampling_handler" type="SamplingHandler | None">
+  Custom handler for MCP sampling requests (server-initiated LLM calls). See [Sampling](/servers/sampling) for details
+</ParamField>
+
+<ParamField body="sampling_handler_behavior" type='Literal["always", "fallback"] | None' default="fallback">
+  When `"fallback"`, the sampling handler is used only when no tool-specific handler exists. When `"always"`, this handler is used for all sampling requests
+</ParamField>
+
+<ParamField body="session_state_store" type="AsyncKeyValue | None">
+  Persistent key-value store for session state that survives across requests. Defaults to an in-memory store. Provide a custom implementation for persistence across server restarts
+</ParamField>
+</Card>
+
+
+## Response Caching
+
+<VersionBadge version="4.0.0" />
+
+A server whose listings and resource reads change slowly can tell clients how long they may reuse a response before fetching it again (SEP-2549). Set `cache_ttl` (seconds) on the server, and the hint is attached uniformly to every cacheable response — `tools/list`, `prompts/list`, `resources/list`, `resources/templates/list`, and `resources/read`.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("Weather", cache_ttl=300, cache_scope="public")
+
+@mcp.tool
+def forecast(city: str) -> str:
+    return f"Sunny in {city}"
+```
+
+`cache_scope` controls whether a cached response may be shared across authorization contexts (`"public"`) or reused only within the one that produced it (`"private"`, the default when a TTL is set). A `cache_scope` without a `cache_ttl` does not enable caching and raises at construction.
+
+The hint is inert on its own: a client only reuses a response if it opts into caching and negotiates the modern protocol. See [Response caching](/clients/client#response-caching) for the client side.
+
+
+## Tag-Based Filtering
+
+<VersionBadge version="2.8.0" />
+
+Tags let you categorize components and selectively expose them. This is useful for creating different views of your server for different environments or user types.
+
+```python
+@mcp.tool(tags={"public", "utility"})
+def public_tool() -> str:
+    return "This tool is public"
+
+@mcp.tool(tags={"internal", "admin"})
+def admin_tool() -> str:
+    return "This tool is for admins only"
+```
+
+The filtering logic works as follows:
+- **Enable with `only=True`**: Switches to allowlist mode — only components with at least one matching tag are exposed
+- **Disable**: Components with any matching tag are hidden
+- **Precedence**: Later calls override earlier ones, so call `disable` after `enable` to exclude from an allowlist
+
+<Tip>
+To ensure a component is never exposed, you can set `enabled=False` on the component itself. See the component-specific documentation for details.
+</Tip>
+
+```python
+# Only expose components tagged with "public"
+mcp = FastMCP()
+mcp.enable(tags={"public"}, only=True)
+
+# Hide components tagged as "internal" or "deprecated"
+mcp = FastMCP()
+mcp.disable(tags={"internal", "deprecated"})
+
+# Combine both: show admin tools but hide deprecated ones
+mcp = FastMCP()
+mcp.enable(tags={"admin"}, only=True).disable(tags={"deprecated"})
+```
+
+This filtering applies to all component types (tools, resources, resource templates, and prompts) and affects both listing and access.
+
+## Custom Routes
+
+When running with HTTP transport, you can add custom web routes alongside your MCP endpoint using the `@custom_route` decorator.
+
+```python
+from fastmcp import FastMCP
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+
+mcp = FastMCP("MyServer")
+
+@mcp.custom_route("/health", methods=["GET"])
+async def health_check(request: Request) -> PlainTextResponse:
+    return PlainTextResponse("OK")
+
+if __name__ == "__main__":
+    mcp.run(transport="http")  # Health check at http://localhost:8000/health
+```
+
+Custom routes are useful for health checks, status endpoints, and simple webhooks. For more complex web applications, consider [mounting your MCP server into a FastAPI or Starlette app](/deployment/http#integration-with-web-frameworks).
diff --git a/docs/servers/storage-backends.mdx b/docs/servers/storage-backends.mdx
new file mode 100644
index 0000000..d13ce17
--- /dev/null
+++ b/docs/servers/storage-backends.mdx
@@ -0,0 +1,296 @@
+---
+title: Storage Backends
+sidebarTitle: Storage Backends
+description: Configure persistent and distributed storage for caching and OAuth state management
+icon: database
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.13.0" />
+
+FastMCP uses pluggable storage backends for caching responses and managing OAuth state. By default, all storage is in-memory, which is perfect for development but doesn't persist across restarts. FastMCP includes support for multiple storage backends, and you can easily extend it with custom implementations.
+
+<Tip>
+The storage layer is powered by **[py-key-value-aio](https://github.com/strawgate/py-key-value)**, an async key-value library maintained by a core FastMCP maintainer. This library provides a unified interface for multiple backends, making it easy to swap implementations based on your deployment needs.
+</Tip>
+
+## Available Backends
+
+### In-Memory Storage
+
+**Best for:** Development, testing, single-process deployments
+
+In-memory storage is the default for all FastMCP storage needs. It's fast, requires no setup, and is perfect for getting started.
+
+```python
+from key_value.aio.stores.memory import MemoryStore
+
+# Used by default - no configuration needed
+# But you can also be explicit:
+cache_store = MemoryStore()
+```
+
+**Characteristics:**
+- ✅ No setup required
+- ✅ Very fast
+- ❌ Data lost on restart
+- ❌ Not suitable for multi-process deployments
+
+### File Storage
+
+**Best for:** Single-server production deployments, persistent caching
+
+File storage persists data to the filesystem as one JSON file per key, allowing it to survive server restarts. This is the default backend for OAuth storage on Mac and Windows.
+
+```python
+from pathlib import Path
+from key_value.aio.stores.filetree import (
+    FileTreeStore,
+    FileTreeV1KeySanitizationStrategy,
+    FileTreeV1CollectionSanitizationStrategy,
+)
+from fastmcp.server.middleware.caching import ResponseCachingMiddleware
+
+storage_dir = Path("/var/cache/fastmcp")
+store = FileTreeStore(
+    data_directory=storage_dir,
+    key_sanitization_strategy=FileTreeV1KeySanitizationStrategy(storage_dir),
+    collection_sanitization_strategy=FileTreeV1CollectionSanitizationStrategy(storage_dir),
+)
+
+# Persistent response cache
+middleware = ResponseCachingMiddleware(cache_storage=store)
+```
+
+<Warning>
+**Sanitization strategies are required** when using `FileTreeStore`. Without them, keys containing special characters (such as URL-based OAuth client IDs like `https://claude.ai/oauth/claude-code-client-metadata`) will be used as-is in filesystem paths, causing `FileNotFoundError` crashes. The V1 strategies shown above are safe defaults — alphanumeric names pass through as-is for readability, while special characters are hashed to prevent path errors and traversal attacks. Changing sanitization strategies after data has been written is a breaking change, so choose your strategy upfront.
+</Warning>
+
+**Characteristics:**
+- ✅ Data persists across restarts
+- ✅ No external dependencies
+- ✅ Human-readable files on disk
+- ❌ Not suitable for distributed deployments
+- ❌ Filesystem access required
+
+### Redis
+
+**Best for:** Distributed production deployments, shared caching across multiple servers
+
+<Note>
+Redis support requires an optional dependency: `pip install 'py-key-value-aio[redis]'`
+</Note>
+
+Redis provides distributed caching and state management, ideal for production deployments with multiple server instances.
+
+```python
+from key_value.aio.stores.redis import RedisStore
+from fastmcp.server.middleware.caching import ResponseCachingMiddleware
+
+# Distributed response cache
+middleware = ResponseCachingMiddleware(
+    cache_storage=RedisStore(host="redis.example.com", port=6379)
+)
+```
+
+With authentication:
+
+```python
+from key_value.aio.stores.redis import RedisStore
+
+cache_store = RedisStore(
+    host="redis.example.com",
+    port=6379,
+    password="your-redis-password"
+)
+```
+
+For OAuth token storage:
+
+```python
+import os
+from fastmcp.server.auth.providers.github import GitHubProvider
+from key_value.aio.stores.redis import RedisStore
+
+auth = GitHubProvider(
+    client_id=os.environ["GITHUB_CLIENT_ID"],
+    client_secret=os.environ["GITHUB_CLIENT_SECRET"],
+    base_url="https://your-server.com",
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=RedisStore(host="redis.example.com", port=6379)
+)
+```
+
+**Characteristics:**
+- ✅ Distributed and highly available
+- ✅ Fast in-memory performance
+- ✅ Works across multiple server instances
+- ✅ Built-in TTL support
+- ❌ Requires Redis infrastructure
+- ❌ Network latency vs local storage
+
+### Other Backends from py-key-value-aio
+
+The py-key-value-aio library includes additional implementations for various storage systems:
+
+- **DynamoDB** - AWS distributed database
+- **MongoDB** - NoSQL document store
+- **Elasticsearch** - Distributed search and analytics
+- **Memcached** - Distributed memory caching
+- **RocksDB** - Embedded high-performance key-value store
+- **Valkey** - Redis-compatible server
+
+For configuration details on these backends, consult the [py-key-value-aio documentation](https://github.com/strawgate/py-key-value).
+
+<Warning>
+Before using these backends in production, review the [py-key-value documentation](https://github.com/strawgate/py-key-value) to understand the maturity level and limitations of your chosen backend. Some backends may be in preview or have specific constraints that make them unsuitable for production use.
+</Warning>
+
+## Use Cases in FastMCP
+
+### Server-Side OAuth Token Storage
+
+The [OAuth Proxy](/servers/auth/oauth-proxy) and OAuth auth providers use storage for persisting OAuth client registrations and upstream tokens. **By default, storage is automatically encrypted using `FernetEncryptionWrapper`.** When providing custom storage, wrap it in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest.
+
+**Development (default behavior):**
+
+By default, FastMCP automatically manages keys and storage based on your platform:
+- **Mac/Windows**: Keys are auto-managed via system keyring, storage defaults to disk. Suitable **only** for development and local testing.
+- **Linux**: Keys are ephemeral, storage defaults to memory.
+
+No configuration needed:
+
+```python
+from fastmcp.server.auth.providers.github import GitHubProvider
+
+auth = GitHubProvider(
+    client_id="your-id",
+    client_secret="your-secret",
+    base_url="https://your-server.com"
+)
+```
+
+**Production:**
+
+For production deployments, configure explicit keys and persistent network-accessible storage with encryption:
+
+```python
+import os
+from fastmcp.server.auth.providers.github import GitHubProvider
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+auth = GitHubProvider(
+    client_id=os.environ["GITHUB_CLIENT_ID"],
+    client_secret=os.environ["GITHUB_CLIENT_SECRET"],
+    base_url="https://your-server.com",
+    # Explicit JWT signing key (required for production)
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    # Encrypted persistent storage (required for production)
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(host="redis.example.com", port=6379),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+```
+
+Both parameters are required for production. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without it, tokens are stored in plaintext. See [OAuth Token Security](/deployment/http#oauth-token-security) and [Key and Storage Management](/servers/auth/oauth-proxy#key-and-storage-management) for complete setup details.
+
+### Response Caching Middleware
+
+The [Response Caching Middleware](/servers/middleware#caching-middleware) caches tool calls, resource reads, and prompt requests. Storage configuration is passed via the `cache_storage` parameter:
+
+```python
+from pathlib import Path
+from fastmcp import FastMCP
+from fastmcp.server.middleware.caching import ResponseCachingMiddleware
+from key_value.aio.stores.filetree import (
+    FileTreeStore,
+    FileTreeV1KeySanitizationStrategy,
+    FileTreeV1CollectionSanitizationStrategy,
+)
+
+mcp = FastMCP("My Server")
+
+cache_dir = Path("cache")
+cache_store = FileTreeStore(
+    data_directory=cache_dir,
+    key_sanitization_strategy=FileTreeV1KeySanitizationStrategy(cache_dir),
+    collection_sanitization_strategy=FileTreeV1CollectionSanitizationStrategy(cache_dir),
+)
+
+# Cache to disk instead of memory
+mcp.add_middleware(ResponseCachingMiddleware(cache_storage=cache_store))
+```
+
+For multi-server deployments sharing a Redis instance:
+
+```python
+from fastmcp.server.middleware.caching import ResponseCachingMiddleware
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.prefix_collections import PrefixCollectionsWrapper
+
+base_store = RedisStore(host="redis.example.com")
+namespaced_store = PrefixCollectionsWrapper(
+    key_value=base_store,
+    prefix="my-server"
+)
+
+middleware = ResponseCachingMiddleware(cache_storage=namespaced_store)
+```
+
+### Client-Side OAuth Token Storage
+
+The [FastMCP Client](/clients/client) uses storage for persisting OAuth tokens locally. By default, tokens are stored in memory:
+
+```python
+from pathlib import Path
+from fastmcp.client.auth import OAuth
+from key_value.aio.stores.filetree import (
+    FileTreeStore,
+    FileTreeV1KeySanitizationStrategy,
+    FileTreeV1CollectionSanitizationStrategy,
+)
+
+# Store tokens on disk for persistence across restarts
+token_dir = Path("~/.local/share/fastmcp/tokens").expanduser()
+token_storage = FileTreeStore(
+    data_directory=token_dir,
+    key_sanitization_strategy=FileTreeV1KeySanitizationStrategy(token_dir),
+    collection_sanitization_strategy=FileTreeV1CollectionSanitizationStrategy(token_dir),
+)
+
+oauth_provider = OAuth(
+    mcp_url="https://your-mcp-server.com/mcp/sse",
+    token_storage=token_storage
+)
+```
+
+This allows clients to reconnect without re-authenticating after restarts.
+
+## Choosing a Backend
+
+| Backend | Development | Single Server | Multi-Server | Cloud Native |
+|---------|-------------|---------------|--------------|--------------|
+| Memory | ✅ Best | ⚠️ Limited | ❌ | ❌ |
+| File | ✅ Good | ✅ Recommended | ❌ | ⚠️ |
+| Redis | ⚠️ Overkill | ✅ Good | ✅ Best | ✅ Best |
+| DynamoDB | ❌ | ⚠️ | ✅ | ✅ Best (AWS) |
+| MongoDB | ❌ | ⚠️ | ✅ | ✅ Good |
+
+**Decision tree:**
+
+1. **Just starting?** Use **Memory** (default) - no configuration needed
+2. **Single server, needs persistence?** Use **File**
+3. **Multiple servers or cloud deployment?** Use **Redis** or **DynamoDB**
+4. **Existing infrastructure?** Look for a matching py-key-value-aio backend
+
+## More Resources
+
+- [py-key-value-aio GitHub](https://github.com/strawgate/py-key-value) - Full library documentation
+- [Response Caching Middleware](/servers/middleware#caching-middleware) - Using storage for caching
+- [OAuth Token Security](/deployment/http#oauth-token-security) - Production OAuth configuration
+- [HTTP Deployment](/deployment/http) - Complete deployment guide
diff --git a/docs/servers/tasks.mdx b/docs/servers/tasks.mdx
new file mode 100644
index 0000000..d4aae9f
--- /dev/null
+++ b/docs/servers/tasks.mdx
@@ -0,0 +1,263 @@
+---
+title: Background Tasks
+sidebarTitle: Background Tasks
+description: Run long-running operations asynchronously with progress tracking
+icon: clock
+tag: "NEW"
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.14.0" />
+
+<Tip>
+Background tasks require the `tasks` optional extra. See [installation instructions](#enabling-background-tasks) below.
+</Tip>
+
+FastMCP implements the MCP background task protocol ([SEP-1686](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks)), giving your servers a production-ready distributed task scheduler with a single decorator change.
+
+<Tip>
+**What is Docket?** FastMCP's task system is powered by [Docket](https://github.com/chrisguidry/docket), originally built by [Prefect](https://prefect.io) to power [Prefect Cloud](https://www.prefect.io/prefect/cloud)'s managed task scheduling and execution service, where it processes millions of concurrent tasks every day. Docket is now open-sourced for the community.
+</Tip>
+
+
+## What Are MCP Background Tasks?
+
+In MCP, all component interactions are blocking by default. When a client calls a tool, reads a resource, or fetches a prompt, it sends a request and waits for the response. For operations that take seconds or minutes, this creates a poor user experience.
+
+The MCP background task protocol solves this by letting clients:
+1. **Start** an operation and receive a task ID immediately
+2. **Track** progress as the operation runs
+3. **Retrieve** the result when ready
+
+FastMCP handles all of this for you. Add `task=True` to your decorator, and your function gains full background execution with progress reporting, distributed processing, and horizontal scaling.
+
+### MCP Background Tasks vs Python Concurrency
+
+You can always use Python's concurrency primitives (asyncio, threads, multiprocessing) or external task queues in your FastMCP servers. FastMCP is just Python—run code however you like.
+
+MCP background tasks are different: they're **protocol-native**. This means MCP clients that support the task protocol can start operations, receive progress updates, and retrieve results through the standard MCP interface. The coordination happens at the protocol level, not inside your application code.
+
+## Enabling Background Tasks
+
+<VersionBadge version="3.0.0" /> Background tasks require the `tasks` extra:
+
+```bash
+pip install "fastmcp[tasks]"
+```
+
+Add `task=True` to any tool, resource, resource template, or prompt decorator. This marks the component as capable of background execution.
+
+```python {6}
+import asyncio
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")
+
+@mcp.tool(task=True)
+async def slow_computation(duration: int) -> str:
+    """A long-running operation."""
+    for i in range(duration):
+        await asyncio.sleep(1)
+    return f"Completed in {duration} seconds"
+```
+
+When a client requests background execution, the call returns immediately with a task ID. The work executes in a background worker, and the client can poll for status or wait for the result.
+
+<Warning>
+Background tasks require async functions. Attempting to use `task=True` with a sync function raises a `ValueError` at registration time.
+</Warning>
+
+## Execution Modes
+
+For fine-grained control over task execution behavior, use `TaskConfig` instead of the boolean shorthand. The MCP task protocol defines three execution modes:
+
+| Mode | Client calls without task | Client calls with task |
+|------|--------------------------|------------------------|
+| `"forbidden"` | Executes synchronously | Error: task not supported |
+| `"optional"` | Executes synchronously | Executes as background task |
+| `"required"` | Error: task required | Executes as background task |
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.tasks import TaskConfig
+
+mcp = FastMCP("MyServer")
+
+# Supports both sync and background execution (default when task=True)
+@mcp.tool(task=TaskConfig(mode="optional"))
+async def flexible_task() -> str:
+    return "Works either way"
+
+# Requires background execution - errors if client doesn't request task
+@mcp.tool(task=TaskConfig(mode="required"))
+async def must_be_background() -> str:
+    return "Only runs as a background task"
+
+# No task support (default when task=False or omitted)
+@mcp.tool(task=TaskConfig(mode="forbidden"))
+async def sync_only() -> str:
+    return "Never runs as background task"
+```
+
+The boolean shortcuts map to these modes:
+- `task=True` → `TaskConfig(mode="optional")`
+- `task=False` → `TaskConfig(mode="forbidden")`
+
+### Poll Interval
+
+<VersionBadge version="2.15.0" />
+
+When clients poll for task status, the server tells them how frequently to check back. By default, FastMCP suggests a 5-second interval, but you can customize this per component:
+
+```python
+from datetime import timedelta
+from fastmcp import FastMCP
+from fastmcp.server.tasks import TaskConfig
+
+mcp = FastMCP("MyServer")
+
+# Poll every 2 seconds for a fast-completing task
+@mcp.tool(task=TaskConfig(mode="optional", poll_interval=timedelta(seconds=2)))
+async def quick_task() -> str:
+    return "Done quickly"
+
+# Poll every 30 seconds for a long-running task
+@mcp.tool(task=TaskConfig(mode="optional", poll_interval=timedelta(seconds=30)))
+async def slow_task() -> str:
+    return "Eventually done"
+```
+
+Shorter intervals give clients faster feedback but increase server load. Longer intervals reduce load but delay status updates.
+
+### Server-Wide Default
+
+To enable background task support for all components by default, pass `tasks=True` to the constructor. Individual decorators can still override this with `task=False`.
+
+```python
+mcp = FastMCP("MyServer", tasks=True)
+```
+
+<Warning>
+If your server defines any synchronous tools, resources, or prompts, you will need to explicitly set `task=False` on their decorators to avoid an error.
+</Warning>
+
+### Graceful Degradation
+
+When a client requests background execution but the component has `mode="forbidden"`, FastMCP executes synchronously and returns the result inline. This follows the SEP-1686 specification for graceful degradation—clients can always request background execution without worrying about server capabilities.
+
+Conversely, when a component has `mode="required"` but the client doesn't request background execution, FastMCP returns an error indicating that task execution is required.
+
+### Configuration
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `FASTMCP_DOCKET_URL` | `memory://` | Backend URL (`memory://` or `redis://host:port/db`) |
+
+## Backends
+
+FastMCP supports two backends for task execution, each with different tradeoffs.
+
+### In-Memory Backend (Default)
+
+The in-memory backend (`memory://`) requires zero configuration and works out of the box.
+
+**Advantages:**
+- No external dependencies
+- Simple single-process deployment
+
+**Disadvantages:**
+- **Ephemeral**: If the server restarts, all pending tasks are lost
+- **Higher latency**: ~250ms task pickup time vs single-digit milliseconds with Redis
+- **No horizontal scaling**: Single process only—you cannot add additional workers
+
+### Redis Backend
+
+For production deployments, use Redis (or Valkey) as your backend by setting `FASTMCP_DOCKET_URL=redis://localhost:6379`.
+
+**Advantages:**
+- **Persistent**: Tasks survive server restarts
+- **Fast**: Single-digit millisecond task pickup latency
+- **Scalable**: Add workers to distribute load across processes or machines
+
+## Workers
+
+Every FastMCP server with task-enabled components automatically starts an **embedded worker**. You do not need to start a separate worker process for tasks to execute.
+
+To scale horizontally, add more workers using the CLI:
+
+```bash
+fastmcp tasks worker server.py
+```
+
+Each additional worker pulls tasks from the same queue, distributing load across processes. Configure worker concurrency via environment:
+
+```bash
+export FASTMCP_DOCKET_CONCURRENCY=20
+fastmcp tasks worker server.py
+```
+
+<Note>
+Additional workers only work with Redis/Valkey backends. The in-memory backend is single-process only.
+</Note>
+
+<Warning>
+Task-enabled components must be defined at server startup to be registered with all workers. Components added dynamically after the server starts will not be available for background execution.
+</Warning>
+
+## Progress Reporting
+
+The `Progress` dependency lets you report progress back to clients. Inject it as a parameter with a default value, and FastMCP will provide the active progress reporter.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.dependencies import Progress
+
+mcp = FastMCP("MyServer")
+
+@mcp.tool(task=True)
+async def process_files(files: list[str], progress: Progress = Progress()) -> str:
+    await progress.set_total(len(files))
+
+    for file in files:
+        await progress.set_message(f"Processing {file}")
+        # ... do work ...
+        await progress.increment()
+
+    return f"Processed {len(files)} files"
+```
+
+The progress API:
+- `await progress.set_total(n)` — Set the total number of steps
+- `await progress.increment(amount=1)` — Increment progress
+- `await progress.set_message(text)` — Update the status message
+
+Progress works in both immediate and background execution modes—you can use the same code regardless of how the client invokes your function.
+
+## Docket Dependencies
+
+FastMCP exposes Docket's full dependency injection system within your task-enabled functions. Beyond `Progress`, you can access the Docket instance, worker information, and use advanced features like retries and timeouts.
+
+```python
+from docket import Docket, Worker
+from fastmcp import FastMCP
+from fastmcp.dependencies import Progress, CurrentDocket, CurrentWorker
+
+mcp = FastMCP("MyServer")
+
+@mcp.tool(task=True)
+async def my_task(
+    progress: Progress = Progress(),
+    docket: Docket = CurrentDocket(),
+    worker: Worker = CurrentWorker(),
+) -> str:
+    # Schedule additional background work
+    await docket.add(another_task, arg1, arg2)
+
+    # Access worker metadata
+    worker_name = worker.name
+
+    return "Done"
+```
+
+With `CurrentDocket()`, you can schedule additional background tasks, chain work together, and coordinate complex workflows. See the [Docket documentation](https://chrisguidry.github.io/docket/) for the complete API, including retry policies, timeouts, and custom dependencies.
diff --git a/docs/servers/telemetry.mdx b/docs/servers/telemetry.mdx
new file mode 100644
index 0000000..aed7308
--- /dev/null
+++ b/docs/servers/telemetry.mdx
@@ -0,0 +1,345 @@
+---
+title: OpenTelemetry
+sidebarTitle: Telemetry
+description: Native OpenTelemetry instrumentation for distributed tracing.
+icon: chart-line
+tag: NEW
+---
+
+FastMCP includes native OpenTelemetry instrumentation for observability. Traces are automatically generated for tool, prompt, resource, and resource template operations, providing visibility into server behavior, request handling, and provider delegation chains.
+
+## How It Works
+
+FastMCP uses the OpenTelemetry API for instrumentation. This means:
+
+- **Zero configuration required** - Instrumentation is always active
+- **No overhead when unused** - Without an SDK, all operations are no-ops
+- **Bring your own SDK** - You control collection, export, and sampling
+- **Works with any OTEL backend** - Jaeger, Zipkin, Datadog, New Relic, etc.
+
+## Enabling Telemetry
+
+The easiest way to export traces is using `opentelemetry-instrument`, which configures the SDK automatically:
+
+```bash
+pip install opentelemetry-distro opentelemetry-exporter-otlp
+opentelemetry-bootstrap -a install
+```
+
+Then run your server with tracing enabled:
+
+```bash
+opentelemetry-instrument \
+  --service_name my-fastmcp-server \
+  --exporter_otlp_endpoint http://localhost:4317 \
+  fastmcp run server.py
+```
+
+Or configure via environment variables:
+
+```bash
+export OTEL_SERVICE_NAME=my-fastmcp-server
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+
+opentelemetry-instrument fastmcp run server.py
+```
+
+This works with any OTLP-compatible backend (Jaeger, Zipkin, Grafana Tempo, Datadog, etc.) and requires no changes to your FastMCP code.
+
+<Card title="OpenTelemetry Python Documentation" icon="book" href="https://opentelemetry.io/docs/languages/python/">
+  Learn more about the OpenTelemetry Python SDK, auto-instrumentation, and available exporters.
+</Card>
+
+## Tracing
+
+FastMCP creates spans for all MCP operations, providing end-to-end visibility into request handling.
+
+### Server Spans
+
+The server creates spans for each operation using [MCP semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/):
+
+| Span Name | Description |
+|-----------|-------------|
+| `tools/call {name}` | Tool execution (e.g., `tools/call get_weather`) |
+| `resources/read` | Resource read (URI in `mcp.resource.uri` attribute, not span name) |
+| `prompts/get {name}` | Prompt render (e.g., `prompts/get greeting`) |
+
+For mounted servers, an additional `delegate {name}` span shows the delegation to the child server.
+
+### Client Spans
+
+The FastMCP client creates spans for outgoing requests with the same naming pattern (`tools/call {name}`, `resources/read`, `prompts/get {name}`).
+
+### Span Hierarchy
+
+Spans form a hierarchy showing the request flow. For mounted servers:
+
+```
+tools/call weather_forecast (CLIENT)
+  └── tools/call weather_forecast (SERVER, provider=FastMCPProvider)
+        └── delegate get_weather (INTERNAL)
+              └── tools/call get_weather (SERVER, provider=LocalProvider)
+```
+
+For proxy providers connecting to remote servers:
+
+```
+tools/call remote_search (CLIENT)
+  └── tools/call remote_search (SERVER, provider=ProxyProvider)
+        └── [remote server spans via trace context propagation]
+```
+
+## Programmatic Configuration
+
+For more control, configure the SDK in your Python code before importing FastMCP:
+
+```python
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+
+# Configure the SDK with OTLP exporter
+provider = TracerProvider()
+processor = BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:4317"))
+provider.add_span_processor(processor)
+trace.set_tracer_provider(provider)
+
+# Now import and use FastMCP - traces will be exported automatically
+from fastmcp import FastMCP
+
+mcp = FastMCP("my-server")
+
+@mcp.tool()
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+```
+
+<Tip>
+The SDK must be configured **before** importing FastMCP to ensure the tracer provider is set when FastMCP initializes.
+</Tip>
+
+### Local Development
+
+For quick local trace visualization, [otel-desktop-viewer](https://github.com/CtrlSpice/otel-desktop-viewer) is a lightweight single-binary tool:
+
+```bash
+# macOS
+brew install nico-barbas/brew/otel-desktop-viewer
+
+# Or download from GitHub releases
+```
+
+Run it alongside your server:
+
+```bash
+# Terminal 1: Start the viewer (UI at http://localhost:8000, OTLP on :4317)
+otel-desktop-viewer
+
+# Terminal 2: Run your server with tracing
+opentelemetry-instrument fastmcp run server.py
+```
+
+For more features, use [Jaeger](https://www.jaegertracing.io/):
+
+```bash
+docker run -d --name jaeger \
+  -p 16686:16686 \
+  -p 4317:4317 \
+  jaegertracing/all-in-one:latest
+```
+
+Then view traces at http://localhost:16686
+
+## Custom Spans
+
+You can add your own spans using the FastMCP tracer:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.telemetry import get_tracer
+
+mcp = FastMCP("custom-spans")
+
+@mcp.tool()
+async def complex_operation(input: str) -> str:
+    tracer = get_tracer()
+
+    with tracer.start_as_current_span("parse_input") as span:
+        span.set_attribute("input.length", len(input))
+        parsed = parse(input)
+
+    with tracer.start_as_current_span("process_data") as span:
+        span.set_attribute("data.count", len(parsed))
+        result = process(parsed)
+
+    return result
+```
+
+### Where custom spans help most
+
+Custom spans are most useful around work that is expensive or hard to debug:
+
+- External calls such as databases, vector stores, HTTP APIs, or queue operations
+- Multi-step tool logic where one stage dominates latency
+- Prompt or resource generation that fans out to other systems
+- Sampling calls made from inside a tool via `ctx.sample(...)`
+
+Avoid wrapping every small helper function or simple in-memory transformation. That usually adds noise without making traces easier to interpret.
+
+### Recommended naming and attributes
+
+- Use `{tool_name}.{operation}` or `{resource_name}.{operation}` for child spans such as `search.fetch`, `search.rank`, or `docs.render`
+- Add attributes that explain workload shape, such as counts, sizes, cache hits, or IDs
+- Do not record secrets, prompts with sensitive user data, or raw tokens as span attributes
+- Let exceptions propagate unless you have a specific recovery path; FastMCP's server spans already mark failures and record exceptions
+
+### Instrumenting tools, prompts, and resources
+
+```python
+from fastmcp import FastMCP
+from fastmcp.telemetry import get_tracer
+
+mcp = FastMCP("my-server")
+
+@mcp.tool
+async def search(query: str) -> str:
+    tracer = get_tracer()
+
+    with tracer.start_as_current_span("search.fetch") as span:
+        span.set_attribute("search.query_length", len(query))
+        results = await fetch_results(query)
+        span.set_attribute("search.result_count", len(results))
+
+    with tracer.start_as_current_span("search.rank"):
+        ranked = rank_results(results)
+
+    return format_results(ranked)
+
+@mcp.prompt
+async def summarize_prompt(topic: str) -> str:
+    tracer = get_tracer()
+    with tracer.start_as_current_span("summarize_prompt.render") as span:
+        span.set_attribute("prompt.topic_length", len(topic))
+        return f"Summarize the latest updates about {topic}."
+
+@mcp.resource("docs://{slug}")
+async def docs_resource(slug: str) -> str:
+    tracer = get_tracer()
+    with tracer.start_as_current_span("docs_resource.load") as span:
+        span.set_attribute("docs.slug", slug)
+        return await load_doc(slug)
+```
+
+### Sampling calls inside tools
+
+If your tool uses `ctx.sample(...)`, keep the LLM work nested under the tool span so traces show both application logic and model latency together.
+
+For providers with their own OTEL integrations, prefer enabling that instrumentation rather than manually creating a span around every model call. For example, if you use Google GenAI, `logfire.instrument_google_genai()` will emit child spans with token and request metadata under the active FastMCP tool span.
+
+### Exporter choices
+
+- For local debugging, `ConsoleSpanExporter` or `otel-desktop-viewer` gives quick feedback with minimal setup
+- For shared environments, use OTLP exporters to backends like Logfire, Jaeger, Tempo, Datadog, or New Relic
+- If traces are too noisy, tune sampling in your OpenTelemetry SDK instead of removing FastMCP instrumentation
+
+## Error Handling
+
+When errors occur, spans are automatically marked with error status and the exception is recorded:
+
+```python
+@mcp.tool()
+def risky_operation() -> str:
+    raise ValueError("Something went wrong")
+
+# The span will have:
+# - status = ERROR with exception message as description
+# - error.type = "tool_error" (or exception class name for non-tool errors)
+# - exception event with stack trace
+```
+
+## Attributes Reference
+
+<Warning>
+**Migrating from v3.1 or earlier:** The `rpc.system`, `rpc.service`, and `rpc.method` span attributes were removed in favor of the [MCP semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/) listed below. If you have dashboards or alerts keyed on those `rpc.*` attributes, update them to use `mcp.method.name` and the `fastmcp.*` attributes instead.
+</Warning>
+
+### MCP Semantic Conventions
+
+FastMCP implements the [OpenTelemetry MCP semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/):
+
+| Attribute | Description |
+|-----------|-------------|
+| `mcp.method.name` | The MCP method being called (`tools/call`, `resources/read`, `prompts/get`) |
+| `mcp.session.id` | Session identifier for the MCP connection |
+| `mcp.resource.uri` | The resource URI (for resource operations) |
+| `gen_ai.tool.name` | Tool name (on `tools/call` spans) |
+| `gen_ai.prompt.name` | Prompt name (on `prompts/get` spans) |
+| `error.type` | Error classification (`tool_error` for ToolError, otherwise exception class name) |
+
+### Auth Attributes
+
+Standard [identity attributes](https://opentelemetry.io/docs/specs/semconv/attributes-registry/enduser/):
+
+| Attribute | Description |
+|-----------|-------------|
+| `enduser.id` | Client ID from access token (when authenticated) |
+| `enduser.scope` | Space-separated OAuth scopes (when authenticated) |
+
+### FastMCP Custom Attributes
+
+All custom attributes use the `fastmcp.` prefix for features unique to FastMCP:
+
+| Attribute | Description |
+|-----------|-------------|
+| `fastmcp.server.name` | Server name |
+| `fastmcp.component.type` | `tool`, `resource`, `prompt`, or `resource_template` |
+| `fastmcp.component.key` | Full component identifier (e.g., `tool:greet`) |
+| `fastmcp.provider.type` | Provider class (`LocalProvider`, `FastMCPProvider`, `ProxyProvider`) |
+
+Provider-specific attributes for delegation context:
+
+| Attribute | Description |
+|-----------|-------------|
+| `fastmcp.delegate.original_name` | Original tool/prompt name before namespacing |
+| `fastmcp.delegate.original_uri` | Original resource URI before namespacing |
+| `fastmcp.proxy.backend_name` | Remote server tool/prompt name |
+| `fastmcp.proxy.backend_uri` | Remote server resource URI |
+
+## Testing with Telemetry
+
+For testing, use the in-memory exporter:
+
+```python
+import pytest
+from collections.abc import Generator
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+from fastmcp import FastMCP
+
+@pytest.fixture
+def trace_exporter() -> Generator[InMemorySpanExporter, None, None]:
+    exporter = InMemorySpanExporter()
+    provider = TracerProvider()
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    original_provider = trace.get_tracer_provider()
+    trace.set_tracer_provider(provider)
+    yield exporter
+    exporter.clear()
+    trace.set_tracer_provider(original_provider)
+
+async def test_tool_creates_span(trace_exporter: InMemorySpanExporter) -> None:
+    mcp = FastMCP("test")
+
+    @mcp.tool()
+    def hello() -> str:
+        return "world"
+
+    await mcp.call_tool("hello", {})
+
+    spans = trace_exporter.get_finished_spans()
+    assert any(s.name == "tools/call hello" for s in spans)
+```
diff --git a/docs/servers/testing.mdx b/docs/servers/testing.mdx
new file mode 100644
index 0000000..7bd8600
--- /dev/null
+++ b/docs/servers/testing.mdx
@@ -0,0 +1,104 @@
+---
+title: Testing your FastMCP Server
+sidebarTitle: Testing
+description: How to test your FastMCP server.
+icon: vial
+---
+
+The best way to ensure a reliable and maintainable FastMCP Server is to test it! The FastMCP Client combined with Pytest provides a simple and powerful way to test your FastMCP servers.
+
+## Prerequisites
+
+Testing FastMCP servers requires `pytest-asyncio` to handle async test functions and fixtures. Install it as a development dependency:
+
+```bash
+pip install pytest-asyncio
+```
+
+We recommend configuring pytest to automatically handle async tests by setting the asyncio mode to `auto` in your `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+```
+
+This eliminates the need to decorate every async test with `@pytest.mark.asyncio`.
+
+## Testing with Pytest Fixtures
+
+Using Pytest Fixtures, you can wrap your FastMCP Server in a Client instance that makes interacting with your server fast and easy. This is especially useful when building your own MCP Servers and enables a tight development loop by allowing you to avoid using a separate tool like MCP Inspector during development:
+
+```python
+import pytest
+from fastmcp.client import Client
+from fastmcp.client.transports import FastMCPTransport
+
+from my_project.main import mcp
+
+@pytest.fixture
+async def main_mcp_client():
+    async with Client(transport=mcp) as mcp_client:
+        yield mcp_client
+
+async def test_list_tools(main_mcp_client: Client[FastMCPTransport]):
+    list_tools = await main_mcp_client.list_tools()
+
+    assert len(list_tools) == 5
+```
+
+We recommend the [inline-snapshot library](https://github.com/15r10nk/inline-snapshot) for asserting complex data structures coming from your MCP Server. This library allows you to write tests that are easy to read and understand, and are also easy to update when the data structure changes. 
+
+```python
+from inline_snapshot import snapshot
+
+async def test_list_tools(main_mcp_client: Client[FastMCPTransport]):
+    list_tools = await main_mcp_client.list_tools()
+
+    assert list_tools == snapshot()
+```
+
+Simply run `pytest --inline-snapshot=fix,create` to fill in the `snapshot()` with actual data.
+
+<Tip>
+For values that change you can leverage the [dirty-equals](https://github.com/samuelcolvin/dirty-equals) library to perform flexible equality assertions on dynamic or non-deterministic values.
+</Tip>
+
+Using the pytest `parametrize` decorator, you can easily test your tools with a wide variety of inputs.
+
+```python
+import pytest
+from my_project.main import mcp
+
+from fastmcp.client import Client
+from fastmcp.client.transports import FastMCPTransport
+@pytest.fixture
+async def main_mcp_client():
+    async with Client(mcp) as client:
+        yield client
+
+
+@pytest.mark.parametrize(
+    "first_number, second_number, expected",
+    [
+        (1, 2, 3),
+        (2, 3, 5),
+        (3, 4, 7),
+    ],
+)
+async def test_add(
+    first_number: int,
+    second_number: int,
+    expected: int,
+    main_mcp_client: Client[FastMCPTransport],
+):
+    result = await main_mcp_client.call_tool(
+        name="add", arguments={"x": first_number, "y": second_number}
+    )
+    assert result.data is not None
+    assert isinstance(result.data, int)
+    assert result.data == expected
+```
+
+<Tip>
+The [FastMCP Repository contains thousands of tests](https://github.com/PrefectHQ/fastmcp/tree/main/tests) for the FastMCP Client and Server. Everything from connecting to remote MCP servers, to testing tools, resources, and prompts is covered, take a look for inspiration!
+</Tip>
\ No newline at end of file
diff --git a/docs/servers/tool-fingerprinting.mdx b/docs/servers/tool-fingerprinting.mdx
new file mode 100644
index 0000000..b8c06c0
--- /dev/null
+++ b/docs/servers/tool-fingerprinting.mdx
@@ -0,0 +1,156 @@
+---
+title: Tool Fingerprinting
+sidebarTitle: Tool Fingerprinting
+description: Build stable fingerprints for tool identity and schema change detection
+icon: fingerprint
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+<VersionBadge version="3.0.0" />
+
+Downstream systems like routers, gateways, and audit loggers often need to detect whether a tool's schema changed between deployments. Rather than each system inventing its own JSON normalization and hashing logic, you can build stable fingerprints from FastMCP's existing API surface.
+
+FastMCP does not define a single "contract hash" because the inclusion policy is necessarily application-specific: some systems care only about the input schema, others include the description, metadata, tags, or version. Instead, this recipe shows how to assemble a fingerprint payload from the parts you care about, then hash it deterministically.
+
+## The Recipe
+
+The two key building blocks are:
+
+- **`tool.key`** — FastMCP's canonical component identity, encoding type, name, and version (e.g. `tool:greet@1.0` or `tool:greet@`)
+- **`tool.to_mcp_tool()`** — the protocol-facing tool object that MCP clients see, including the input schema
+
+Combine them into a payload, serialize deterministically, and hash:
+
+```python
+import hashlib
+import json
+
+from fastmcp import FastMCP
+
+mcp = FastMCP("demo")
+
+
+@mcp.tool()
+def greet(name: str) -> str:
+    """Say hello."""
+    return f"Hello {name}"
+
+
+async def fingerprint_tool(server: FastMCP, tool_name: str) -> str:
+    tool = await server.get_tool(tool_name)
+    if tool is None:
+        raise ValueError(f"Tool {tool_name!r} not found")
+
+    mcp_tool = tool.to_mcp_tool()
+    dumped = mcp_tool.model_dump(mode="json", by_alias=True, exclude_none=True)
+
+    payload = {
+        "key": tool.key,
+        "inputSchema": dumped["inputSchema"],
+    }
+
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+```
+
+The fingerprint is stable across process restarts as long as the tool's name, version, and input schema remain the same.
+
+## Why `tool.key`?
+
+`tool.key` is FastMCP's canonical component identity. It encodes the component type, identifier, and version into a single string:
+
+```
+tool:greet@1.0    # versioned tool
+tool:greet@       # unversioned tool
+```
+
+Using `key` rather than just the tool name ensures that two versions of the same tool produce distinct fingerprints, and that a tool and a resource with the same name cannot collide.
+
+## Why `to_mcp_tool()`?
+
+`to_mcp_tool()` returns the protocol-facing representation — the shape that MCP clients actually receive. This matters because routers and gateways typically operate on the protocol layer, not FastMCP internals. The `model_dump(mode="json", by_alias=True, exclude_none=True)` call produces a clean, serializable dictionary using the MCP protocol field names.
+
+## Customizing the Payload
+
+You own the inclusion policy. Add or remove fields depending on what constitutes a "contract" in your system:
+
+```python
+async def custom_fingerprint(server: FastMCP, tool_name: str) -> str:
+    tool = await server.get_tool(tool_name)
+    if tool is None:
+        raise ValueError(f"Tool {tool_name!r} not found")
+
+    mcp_tool = tool.to_mcp_tool()
+    dumped = mcp_tool.model_dump(mode="json", by_alias=True, exclude_none=True)
+
+    # Include description to detect documentation drift
+    payload = {
+        "key": tool.key,
+        "inputSchema": dumped["inputSchema"],
+        "description": dumped.get("description"),
+    }
+
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+```
+
+Common variations:
+
+| Field          | When to include                                                            |
+| -------------- | -------------------------------------------------------------------------- |
+| `inputSchema`  | Always — this is the core contract                                         |
+| `description`  | When documentation drift matters (e.g. LLM routing decisions depend on it) |
+| `outputSchema` | When downstream consumers validate response shapes                         |
+| `annotations`  | When behavioral hints (read-only, destructive) affect routing              |
+| `_meta`        | When custom metadata drives policy decisions                               |
+
+## Detecting Schema Drift in CI
+
+Store fingerprints as artifacts and compare between deployments:
+
+```python
+import json
+import hashlib
+from pathlib import Path
+
+from fastmcp import FastMCP
+
+
+async def generate_manifest(server: FastMCP) -> dict[str, str]:
+    """Generate a fingerprint manifest for all tools."""
+    manifest = {}
+
+    for tool in await server.list_tools():
+        mcp_tool = tool.to_mcp_tool()
+        dumped = mcp_tool.model_dump(mode="json", by_alias=True, exclude_none=True)
+
+        payload = {
+            "key": tool.key,
+            "inputSchema": dumped["inputSchema"],
+        }
+
+        canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+        manifest[tool.key] = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+    return manifest
+
+
+async def check_drift(server: FastMCP, baseline_path: Path) -> list[str]:
+    """Compare current fingerprints against a stored baseline."""
+    current = await generate_manifest(server)
+    baseline = json.loads(baseline_path.read_text())
+
+    changed = []
+    for key, fingerprint in current.items():
+        if baseline.get(key) != fingerprint:
+            changed.append(key)
+
+    for key in baseline:
+        if key not in current:
+            changed.append(key)
+
+    return changed
+```
+
+Run `generate_manifest` in CI after each build and compare against the previous run. Any differences indicate a schema change that downstream consumers should be aware of.
diff --git a/docs/servers/tools.mdx b/docs/servers/tools.mdx
new file mode 100644
index 0000000..bc5b7d2
--- /dev/null
+++ b/docs/servers/tools.mdx
@@ -0,0 +1,1143 @@
+---
+title: Tools
+sidebarTitle: Tools
+description: Expose functions as executable capabilities for your MCP client.
+icon: wrench
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+Tools are the core building blocks that allow your LLM to interact with external systems, execute code, and access data that isn't in its training data. In FastMCP, tools are Python functions exposed to LLMs through the MCP protocol.
+
+Tools in FastMCP transform regular Python functions into capabilities that LLMs can invoke during conversations. When an LLM decides to use a tool:
+
+1.  It sends a request with parameters based on the tool's schema.
+2.  FastMCP validates these parameters against your function's signature.
+3.  Your function executes with the validated inputs.
+4.  The result is returned to the LLM, which can use it in its response.
+
+This allows LLMs to perform tasks like querying databases, calling APIs, making calculations, or accessing files—extending their capabilities beyond what's in their training data.
+
+
+## The `@tool` Decorator
+
+Creating a tool is as simple as decorating a Python function with `@mcp.tool`:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="CalculatorServer")
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Adds two integer numbers together."""
+    return a + b
+```
+
+When this tool is registered, FastMCP automatically:
+- Uses the function name (`add`) as the tool name.
+- Parses the function's docstring for the tool description and, if present, per-parameter descriptions (see [Docstring Descriptions](#docstring-descriptions)).
+- Generates an input schema based on the function's parameters and type annotations.
+- Handles parameter validation and error reporting.
+
+The way you define your Python function dictates how the tool appears and behaves for the LLM client.
+
+<Tip>
+Functions with `*args` or `**kwargs` are not supported as tools. This restriction exists because FastMCP needs to generate a complete parameter schema for the MCP protocol, which isn't possible with variable argument lists.
+</Tip>
+
+### Decorator Arguments
+
+While FastMCP infers the name and description from your function, you can override these and add additional metadata using arguments to the `@mcp.tool` decorator:
+
+```python
+@mcp.tool(
+    name="find_products",           # Custom tool name for the LLM
+    description="Search the product catalog with optional category filtering.", # Custom description
+    tags={"catalog", "search"},      # Optional tags for organization/filtering
+    meta={"version": "1.2", "author": "product-team"}  # Custom metadata
+)
+def search_products_implementation(query: str, category: str | None = None) -> list[dict]:
+    """Internal function description (ignored if description is provided above)."""
+    # Implementation...
+    print(f"Searching for '{query}' in category '{category}'")
+    return [{"id": 2, "name": "Another Product"}]
+```
+
+<Card icon="code" title="@tool Decorator Arguments">
+<ParamField body="name" type="str | None">
+  Sets the explicit tool name exposed via MCP. If not provided, uses the function name
+</ParamField>
+
+<ParamField body="description" type="str | None">
+  Provides the description exposed via MCP. If set, the function's docstring is ignored for the tool description, though docstring-derived parameter descriptions still apply (see [Docstring Descriptions](#docstring-descriptions)).
+</ParamField>
+
+<ParamField body="tags" type="set[str] | None">
+  A set of strings used to categorize the tool. These can be used by the server and, in some cases, by clients to filter or group available tools.
+</ParamField>
+
+<ParamField body="enabled" type="bool" default="True">
+  <Warning>Deprecated in v3.0.0. Use `mcp.enable()` / `mcp.disable()` at the server level instead.</Warning>
+  A boolean to enable or disable the tool. See [Component Visibility](#component-visibility) for the recommended approach.
+</ParamField>
+
+<ParamField body="icons" type="list[Icon] | None">
+  <VersionBadge version="2.13.0" />
+
+  Optional list of icon representations for this tool. See [Icons](/servers/icons) for detailed examples
+</ParamField>
+
+<ParamField body="annotations" type="ToolAnnotations | dict | None">
+    An optional `ToolAnnotations` object or dictionary to add additional metadata about the tool.
+  <Expandable title="ToolAnnotations attributes">
+    <ParamField body="title" type="str | None">
+      A human-readable title for the tool.
+    </ParamField>
+    <ParamField body="readOnlyHint" type="bool | None">
+      If true, the tool does not modify its environment.
+    </ParamField>
+    <ParamField body="destructiveHint" type="bool | None">
+      If true, the tool may perform destructive updates to its environment.
+    </ParamField>
+    <ParamField body="idempotentHint" type="bool | None">
+      If true, calling the tool repeatedly with the same arguments will have no additional effect on the its environment.
+    </ParamField>
+    <ParamField body="openWorldHint" type="bool | None">
+      If true, this tool may interact with an "open world" of external entities. If false, the tool's domain of interaction is closed.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="meta" type="dict[str, Any] | None">
+  <VersionBadge version="2.11.0" />
+
+  Optional meta information about the tool. This data is passed through to the MCP client as the `meta` field of the client-side tool object and can be used for custom metadata, versioning, or other application-specific purposes.
+</ParamField>
+
+<ParamField body="timeout" type="float | None">
+  <VersionBadge version="3.0.0" />
+
+  Execution timeout in seconds. If the tool takes longer than this to complete, an MCP error is returned to the client. See [Timeouts](#timeouts) for details.
+</ParamField>
+
+<ParamField body="version" type="str | int | None">
+  <VersionBadge version="3.0.0" />
+
+  Optional version identifier for this tool. See [Versioning](/servers/versioning) for details.
+</ParamField>
+
+<ParamField body="output_schema" type="dict[str, Any] | None">
+  <VersionBadge version="2.10.0" />
+
+  Optional JSON schema for the tool's output. When provided, the tool must return structured output matching this schema. If not provided, FastMCP automatically generates a schema from the function's return type annotation. See [Output Schemas](#output-schemas) for details.
+</ParamField>
+
+<ParamField body="run_in_thread" type="bool" default="True">
+  Applies to sync tool functions only. When `True` (default), sync functions are dispatched to a thread pool so they don't block the event loop. Set to `False` to run the function inline on the event loop thread — useful for libraries with thread affinity like Windows COM (`pywin32`, `uiautomation`, `comtypes`), `tkinter`, or certain GPU/driver bindings. Ignored for async functions, which always run on the event loop. See [Thread affinity](#thread-affinity) for details.
+</ParamField>
+</Card>
+
+### Using with Methods
+
+The `@mcp.tool` decorator registers tools immediately, which doesn't work with instance or class methods (you'd see `self` or `cls` as required parameters). For methods, use the standalone `@tool` decorator to attach metadata, then register the bound method:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.tools import tool
+
+class Calculator:
+    def __init__(self, multiplier: int):
+        self.multiplier = multiplier
+
+    @tool()
+    def multiply(self, x: int) -> int:
+        """Multiply x by the instance multiplier."""
+        return x * self.multiplier
+
+calc = Calculator(multiplier=3)
+mcp = FastMCP()
+mcp.add_tool(calc.multiply)  # Registers with correct schema (only 'x', not 'self')
+```
+
+### Async Support
+
+FastMCP supports both asynchronous (`async def`) and synchronous (`def`) functions as tools. Synchronous tools automatically run in a threadpool to avoid blocking the event loop, so multiple tool calls can execute concurrently even if individual tools perform blocking operations.
+
+```python
+from fastmcp import FastMCP
+import time
+
+mcp = FastMCP()
+
+@mcp.tool
+def slow_tool(x: int) -> int:
+    """This sync function won't block other concurrent requests."""
+    time.sleep(2)  # Runs in threadpool, not on the event loop
+    return x * 2
+```
+
+For I/O-bound operations like network requests or database queries, async tools are still preferred since they're more efficient than threadpool dispatch. Use sync tools when working with synchronous libraries or for simple operations where the threading overhead doesn't matter.
+
+### Thread affinity
+
+This section applies to sync tools only. Async tools already run on the event loop and are not affected.
+
+Some libraries bind state to the thread they're first used from and break when called from a different thread. The most common case is Windows COM — libraries like `uiautomation`, `comtypes`, and parts of `pywin32` require `CoInitialize` to have been called on the current thread, and worker-pool threads don't initialize COM by default. Similar constraints apply to `tkinter`, some GPU bindings (CUDA contexts), and certain hardware drivers.
+
+For these cases, pass `run_in_thread=False` so FastMCP invokes the sync function inline on the event loop thread instead of dispatching it to a worker:
+
+```python
+import uiautomation as auto
+
+@mcp.tool(run_in_thread=False)
+def list_windows() -> list[str]:
+    """List desktop windows via Windows UI Automation (COM)."""
+    desktop = auto.GetRootControl()
+    return [w.Name for w in desktop.GetChildren()[:5]]
+```
+
+The tradeoff is that the event loop is blocked for the duration of the call — other in-flight requests wait until the tool returns. Keep `run_in_thread=False` reserved for tools that genuinely need thread affinity, and prefer short-running calls in that path.
+
+Inline sync calls have no cancellation checkpoints, so `timeout` cannot interrupt them. Combining `timeout` with `run_in_thread=False` on a sync function is rejected at registration — drop one or the other.
+
+## Arguments
+
+By default, FastMCP converts Python functions into MCP tools by inspecting the function's signature and type annotations. This allows you to use standard Python type annotations for your tools. In general, the framework strives to "just work": idiomatic Python behaviors like parameter defaults and type annotations are automatically translated into MCP schemas. However, there are a number of ways to customize the behavior of your tools.
+
+<Note>
+FastMCP automatically dereferences `$ref` entries in tool schemas to ensure compatibility with MCP clients that don't fully support JSON Schema references (e.g., VS Code Copilot, Claude Desktop). This means complex Pydantic models with shared types are inlined in the schema rather than using `$defs` references.
+
+Dereferencing happens at serve-time via middleware, so your schemas are stored with `$ref` intact and only inlined when sent to clients. If you know your clients handle `$ref` correctly and prefer smaller schemas, you can opt out:
+
+```python
+mcp = FastMCP("my-server", dereference_schemas=False)
+```
+</Note>
+
+### Type Annotations
+
+MCP tools have typed arguments, and FastMCP uses type annotations to determine those types. Therefore, you should use standard Python type annotations for tool arguments:
+
+```python
+@mcp.tool
+def analyze_text(
+    text: str,
+    max_tokens: int = 100,
+    language: str | None = None
+) -> dict:
+    """Analyze the provided text."""
+    # Implementation...
+```
+
+FastMCP supports a wide range of type annotations, including all Pydantic types:
+
+| Type Annotation         | Example                       | Description                         |
+| :---------------------- | :---------------------------- | :---------------------------------- |
+| Basic types             | `int`, `float`, `str`, `bool` | Simple scalar values |
+| Binary data             | `bytes`                       | Binary content (raw strings, not auto-decoded base64) |
+| Date and Time           | `datetime`, `date`, `timedelta` | Date and time objects (ISO format strings) |
+| Collection types        | `list[str]`, `dict[str, int]`, `set[int]` | Collections of items |
+| Optional types          | `float \| None`, `Optional[float]`| Parameters that may be null/omitted |
+| Union types             | `str \| int`, `Union[str, int]`| Parameters accepting multiple types |
+| Constrained types       | `Literal["A", "B"]`, `Enum`   | Parameters with specific allowed values |
+| Paths                   | `Path`                        | File system paths (auto-converted from strings) |
+| UUIDs                   | `UUID`                        | Universally unique identifiers (auto-converted from strings) |
+| Pydantic models         | `UserData`                    | Complex structured data with validation |
+
+FastMCP supports all types that Pydantic supports as fields, including all Pydantic custom types. A few FastMCP-specific behaviors to note:
+
+**Binary Data**: `bytes` parameters accept raw strings without automatic base64 decoding. For base64 data, use `str` and decode manually with `base64.b64decode()`.
+
+**Enums**: Clients send enum values (`"red"`), not names (`"RED"`). Your function receives the Enum member (`Color.RED`).
+
+**Paths and UUIDs**: String inputs are automatically converted to `Path` and `UUID` objects.
+
+**Pydantic Models**: Must be provided as JSON objects (dicts), not stringified JSON. Even with flexible validation, `{"user": {"name": "Alice"}}` works, but `{"user": '{"name": "Alice"}'}` does not.
+
+### Optional Arguments
+
+FastMCP follows Python's standard function parameter conventions. Parameters without default values are required, while those with default values are optional.
+
+```python
+@mcp.tool
+def search_products(
+    query: str,                   # Required - no default value
+    max_results: int = 10,        # Optional - has default value
+    sort_by: str = "relevance",   # Optional - has default value
+    category: str | None = None   # Optional - can be None
+) -> list[dict]:
+    """Search the product catalog."""
+    # Implementation...
+```
+
+In this example, the LLM must provide a `query` parameter, while `max_results`, `sort_by`, and `category` will use their default values if not explicitly provided.
+
+### Validation Modes
+
+<VersionBadge version="2.13.0" />
+
+By default, FastMCP uses Pydantic's flexible validation that coerces compatible inputs to match your type annotations. This improves compatibility with LLM clients that may send string representations of values (like `"10"` for an integer parameter).
+
+If you need stricter validation that rejects any type mismatches, you can enable strict input validation. Strict mode uses the MCP SDK's built-in JSON Schema validation to validate inputs against the exact schema before passing them to your function:
+
+```python
+# Enable strict validation for this server
+mcp = FastMCP("StrictServer", strict_input_validation=True)
+
+@mcp.tool
+def add_numbers(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+
+# With strict_input_validation=True, sending {"a": "10", "b": "20"} will fail
+# With strict_input_validation=False (default), it will be coerced to integers
+```
+
+**Validation Behavior Comparison:**
+
+| Input Type | strict_input_validation=False (default) | strict_input_validation=True |
+| :--------- | :-------------------------------------- | :--------------------------- |
+| String integers (`"10"` for `int`) | ✅ Coerced to integer | ❌ Validation error |
+| String floats (`"3.14"` for `float`) | ✅ Coerced to float | ❌ Validation error |
+| String booleans (`"true"` for `bool`) | ✅ Coerced to boolean | ❌ Validation error |
+| Lists with string elements (`["1", "2"]` for `list[int]`) | ✅ Elements coerced | ❌ Validation error |
+| Pydantic model fields with type mismatches | ✅ Fields coerced | ❌ Validation error |
+| Invalid values (`"abc"` for `int`) | ❌ Validation error | ❌ Validation error |
+
+<Note>
+**Note on Pydantic Models:** Even with `strict_input_validation=False`, Pydantic model parameters must be provided as JSON objects (dicts), not as stringified JSON. For example, `{"user": {"name": "Alice"}}` works, but `{"user": '{"name": "Alice"}'}` does not.
+</Note>
+
+The default flexible validation mode is recommended for most use cases as it handles common LLM client behaviors gracefully while still providing strong type safety through Pydantic's validation.
+
+### Parameter Metadata
+
+You can provide additional metadata about parameters in several ways:
+
+#### Docstring Descriptions
+
+<VersionBadge version="3.2.4" />
+
+FastMCP parses your function's docstring to extract both the tool description and per-parameter descriptions. Google, NumPy, and Sphinx docstring styles are all supported — the parser tries each and uses whichever finds parameter descriptions:
+
+```python
+@mcp.tool
+def process_image(
+    image_url: str,
+    resize: bool = False,
+    width: int = 800,
+) -> dict:
+    """Process an image with optional resizing.
+
+    Args:
+        image_url: URL of the image to process.
+        resize: Whether to resize the image.
+        width: Target width in pixels.
+    """
+    # Implementation...
+```
+
+The free-form text above the `Args` section — whether a single line or multiple paragraphs — becomes the tool description, and each parameter's docstring entry becomes the description for that parameter in the generated schema. Sections like `Returns`, `Raises`, and `Example` are excluded from the description but otherwise ignored.
+
+If a parameter already has an explicit description — via `Annotated[x, "..."]` or `Field(description=...)` — that description takes precedence over the docstring. This makes it safe to adopt docstring-based descriptions incrementally: existing annotations keep working, and docstrings fill in the gaps.
+
+#### Simple String Descriptions
+
+<VersionBadge version="2.11.0" />
+
+For basic parameter descriptions, you can use a convenient shorthand with `Annotated`:
+
+```python 
+from typing import Annotated
+
+@mcp.tool
+def process_image(
+    image_url: Annotated[str, "URL of the image to process"],
+    resize: Annotated[bool, "Whether to resize the image"] = False,
+    width: Annotated[int, "Target width in pixels"] = 800,
+    format: Annotated[str, "Output image format"] = "jpeg"
+) -> dict:
+    """Process an image with optional resizing."""
+    # Implementation...
+```
+
+This shorthand syntax is equivalent to using `Field(description=...)` but more concise for simple descriptions.
+
+<Tip>
+This shorthand syntax is only applied to `Annotated` types with a single string description. 
+</Tip>
+
+#### Advanced Metadata with Field
+
+For validation constraints and advanced metadata, use Pydantic's `Field` class with `Annotated`:
+
+```python
+from typing import Annotated
+from pydantic import Field
+
+@mcp.tool
+def process_image(
+    image_url: Annotated[str, Field(description="URL of the image to process")],
+    resize: Annotated[bool, Field(description="Whether to resize the image")] = False,
+    width: Annotated[int, Field(description="Target width in pixels", ge=1, le=2000)] = 800,
+    format: Annotated[
+        Literal["jpeg", "png", "webp"], 
+        Field(description="Output image format")
+    ] = "jpeg"
+) -> dict:
+    """Process an image with optional resizing."""
+    # Implementation...
+```
+
+
+You can also use the Field as a default value, though the Annotated approach is preferred:
+
+```python
+@mcp.tool
+def search_database(
+    query: str = Field(description="Search query string"),
+    limit: int = Field(10, description="Maximum number of results", ge=1, le=100)
+) -> list:
+    """Search the database with the provided query."""
+    # Implementation...
+```
+
+Field provides several validation and documentation features:
+- `description`: Human-readable explanation of the parameter (shown to LLMs)
+- `ge`/`gt`/`le`/`lt`: Greater/less than (or equal) constraints
+- `min_length`/`max_length`: String or collection length constraints
+- `pattern`: Regex pattern for string validation
+- `default`: Default value if parameter is omitted
+
+### Hiding Parameters from the LLM
+
+<VersionBadge version="2.14.0" />
+
+To inject values at runtime without exposing them to the LLM (such as `user_id`, credentials, or database connections), use dependency injection with `Depends()`. Parameters using `Depends()` are automatically excluded from the tool schema:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.dependencies import Depends
+
+mcp = FastMCP()
+
+def get_user_id() -> str:
+    return "user_123"  # Injected at runtime
+
+@mcp.tool
+def get_user_details(user_id: str = Depends(get_user_id)) -> str:
+    # user_id is injected by the server, not provided by the LLM
+    return f"Details for {user_id}"
+```
+
+See [Custom Dependencies](/servers/context#custom-dependencies) for more details on dependency injection.
+
+## Return Values
+
+
+FastMCP tools can return data in two complementary formats: **traditional content blocks** (like text and images) and **structured outputs** (machine-readable JSON). When you add return type annotations, FastMCP automatically generates **output schemas** to validate the structured data and enables clients to deserialize results back to Python objects.
+
+Understanding how these three concepts work together:
+
+- **Return Values**: What your Python function returns (determines both content blocks and structured data)
+- **Structured Outputs**: JSON data sent alongside traditional content for machine processing  
+- **Output Schemas**: JSON Schema declarations that describe and validate the structured output format
+
+The following sections explain each concept in detail.
+
+### Content Blocks
+
+FastMCP automatically converts tool return values into appropriate MCP content blocks:
+
+- **`str`**: Sent as `TextContent`
+- **`bytes`**: Base64 encoded and sent as `BlobResourceContents` (within an `EmbeddedResource`)
+- **`fastmcp.utilities.types.Image`**: Sent as `ImageContent`
+- **`fastmcp.utilities.types.Audio`**: Sent as `AudioContent`
+- **`fastmcp.utilities.types.File`**: Sent as base64-encoded `EmbeddedResource`
+- **MCP SDK content blocks**: Sent as-is
+- **A list of any of the above**: Converts each item according to the above rules
+- **`None`**: Results in an empty response
+
+#### Media Helper Classes
+
+FastMCP provides helper classes for returning images, audio, and files. When you return one of these classes, either directly or as part of a list, FastMCP automatically converts it to the appropriate MCP content block. For example, if you return a `fastmcp.utilities.types.Image` object, FastMCP will convert it to an MCP `ImageContent` block with the correct MIME type and base64 encoding.
+
+```python
+from fastmcp.utilities.types import Image, Audio, File
+
+@mcp.tool
+def get_chart() -> Image:
+    """Generate a chart image."""
+    return Image(path="chart.png")
+
+@mcp.tool
+def get_multiple_charts() -> list[Image]:
+    """Return multiple charts."""
+    return [Image(path="chart1.png"), Image(path="chart2.png")]
+```
+
+<Tip>
+Helper classes are only automatically converted to MCP content blocks when returned **directly** or as part of a **list**. For more complex containers like dicts, you can manually convert them to MCP types:
+
+```python
+# ✅ Automatic conversion
+return Image(path="chart.png")
+return [Image(path="chart1.png"), "text content"]
+
+# ❌ Will not be automatically converted
+return {"image": Image(path="chart.png")}
+
+# ✅ Manual conversion for nested use
+return {"image": Image(path="chart.png").to_image_content()}
+```
+</Tip>
+
+Each helper class accepts either `path=` or `data=` (mutually exclusive):
+- **`path`**: File path (string or Path object) - MIME type detected from extension
+- **`data`**: Raw bytes - requires `format=` parameter for MIME type
+- **`format`**: Optional format override (e.g., "png", "wav", "pdf")
+- **`name`**: Optional name for `File` when using `data=`
+- **`annotations`**: Optional MCP annotations for the content
+
+### Structured Output
+
+<VersionBadge version="2.10.0" />
+
+The 6/18/2025 MCP spec update [introduced](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content) structured content, which is a new way to return data from tools. Structured content is a JSON object that is sent alongside traditional content. FastMCP automatically creates structured outputs alongside traditional content when your tool returns data that has a JSON object representation. This provides machine-readable JSON data that clients can deserialize back to Python objects.
+
+**Automatic Structured Content Rules:**
+- **Object-like results** (`dict`, Pydantic models, dataclasses) → Always become structured content (even without output schema)  
+- **Non-object results** (`int`, `str`, `list`) → Only become structured content if there's an output schema to validate/serialize them
+- **All results** → Always become traditional content blocks for backward compatibility
+
+<Note>
+This automatic behavior enables clients to receive machine-readable data alongside human-readable content without requiring explicit output schemas for object-like returns.
+</Note>
+
+#### Dictionaries and Objects
+
+When your tool returns a dictionary, dataclass, or Pydantic model, FastMCP automatically creates structured content from it. The structured content contains the actual object data, making it easy for clients to deserialize back to native objects.
+
+<CodeGroup>
+```python Tool Definition
+@mcp.tool
+def get_user_data(user_id: str) -> dict:
+    """Get user data."""
+    return {"name": "Alice", "age": 30, "active": True}
+```
+
+```json MCP Result
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\n  \"name\": \"Alice\",\n  \"age\": 30,\n  \"active\": true\n}"
+    }
+  ],
+  "structuredContent": {
+    "name": "Alice",
+    "age": 30,
+    "active": true
+  }
+}
+```
+</CodeGroup>
+
+#### Primitives and Collections
+
+When your tool returns a primitive type (int, str, bool) or a collection (list, set), FastMCP needs a return type annotation to generate structured content. The annotation tells FastMCP how to validate and serialize the result.
+
+Without a type annotation, the tool only produces `content`:
+
+<CodeGroup>
+```python Tool Definition
+@mcp.tool
+def calculate_sum(a: int, b: int):
+    """Calculate sum without return annotation."""
+    return a + b  # Returns 8
+```
+
+```json MCP Result
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "8"
+    }
+  ]
+}
+```
+</CodeGroup>
+
+When you add a return annotation, such as `-> int`, FastMCP generates `structuredContent` by wrapping the primitive value in a `{"result": ...}` object, since JSON schemas require object-type roots for structured output:
+
+<CodeGroup>
+```python Tool Definition
+@mcp.tool
+def calculate_sum(a: int, b: int) -> int:
+    """Calculate sum with return annotation."""
+    return a + b  # Returns 8
+```
+
+```json MCP Result
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "8"
+    }
+  ],
+  "structuredContent": {
+    "result": 8
+  }
+}
+```
+</CodeGroup>
+
+#### Typed Models
+
+Return type annotations work with any type that can be converted to a JSON schema. Dataclasses and Pydantic models are particularly useful because FastMCP extracts their field definitions to create detailed schemas.
+
+<CodeGroup>
+```python Tool Definition
+from dataclasses import dataclass
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+@dataclass
+class Person:
+    name: str
+    age: int
+    email: str
+
+@mcp.tool
+def get_user_profile(user_id: str) -> Person:
+    """Get a user's profile information."""
+    return Person(
+        name="Alice",
+        age=30,
+        email="alice@example.com",
+    )
+```
+
+```json Generated Output Schema
+{
+  "properties": {
+    "name": {"title": "Name", "type": "string"},
+    "age": {"title": "Age", "type": "integer"},
+    "email": {"title": "Email", "type": "string"}
+  },
+  "required": ["name", "age", "email"],
+  "title": "Person",
+  "type": "object"
+}
+```
+
+```json MCP Result
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\"name\": \"Alice\", \"age\": 30, \"email\": \"alice@example.com\"}"
+    }
+  ],
+  "structuredContent": {
+    "name": "Alice",
+    "age": 30,
+    "email": "alice@example.com"
+  }
+}
+```
+</CodeGroup>
+
+The `Person` dataclass becomes an output schema (second tab) that describes the expected format. When executed, clients receive the result (third tab) with both `content` and `structuredContent` fields.
+
+### Output Schemas
+
+<VersionBadge version="2.10.0" />
+
+The 6/18/2025 MCP spec update [introduced](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#output-schema) output schemas, which are a new way to describe the expected output format of a tool. When an output schema is provided, the tool *must* return structured output that matches the schema.
+
+When you add return type annotations to your functions, FastMCP automatically generates JSON schemas that describe the expected output format. These schemas help MCP clients understand and validate the structured data they receive.
+
+#### Primitive Type Wrapping
+
+For primitive return types (like `int`, `str`, `bool`), FastMCP automatically wraps the result under a `"result"` key to create valid structured output:
+
+<CodeGroup>
+```python Primitive Return Type
+@mcp.tool
+def calculate_sum(a: int, b: int) -> int:
+    """Add two numbers together."""
+    return a + b
+```
+
+```json Generated Schema (Wrapped)
+{
+  "type": "object",
+  "properties": {
+    "result": {"type": "integer"}
+  },
+  "x-fastmcp-wrap-result": true
+}
+```
+
+```json Structured Output
+{
+  "result": 8
+}
+```
+</CodeGroup>
+
+#### Manual Schema Control
+
+You can override the automatically generated schema by providing a custom `output_schema`:
+
+```python
+@mcp.tool(output_schema={
+    "type": "object", 
+    "properties": {
+        "data": {"type": "string"},
+        "metadata": {"type": "object"}
+    }
+})
+def custom_schema_tool() -> dict:
+    """Tool with custom output schema."""
+    return {"data": "Hello", "metadata": {"version": "1.0"}}
+```
+
+Schema generation works for most common types including basic types, collections, union types, Pydantic models, TypedDict structures, and dataclasses.
+
+<Warning>
+**Important Constraints**: 
+- Output schemas must be object types (`"type": "object"`)
+- If you provide an output schema, your tool **must** return structured output that matches it
+- However, you can provide structured output without an output schema (using `ToolResult`)
+</Warning>
+
+### ToolResult and Metadata
+
+For complete control over tool responses, return a `ToolResult` object. This gives you explicit control over all aspects of the tool's output: traditional content, structured data, and metadata.
+
+```python
+from fastmcp.tools.tool import ToolResult
+from fastmcp.types import TextContent
+
+@mcp.tool
+def advanced_tool() -> ToolResult:
+    """Tool with full control over output."""
+    return ToolResult(
+        content=[TextContent(type="text", text="Human-readable summary")],
+        structured_content={"data": "value", "count": 42},
+        meta={"execution_time_ms": 145}
+    )
+```
+
+`ToolResult` accepts three fields:
+
+**`content`** - The traditional MCP content blocks that clients display to users. Can be a string (automatically converted to `TextContent`), a list of MCP content blocks, or any serializable value (converted to JSON string). At least one of `content` or `structured_content` must be provided.
+
+```python
+# Simple string
+ToolResult(content="Hello, world!")
+
+# List of content blocks
+ToolResult(content=[
+    TextContent(type="text", text="Result: 42"),
+    ImageContent(type="image", data="base64...", mime_type="image/png")
+])
+```
+
+**`structured_content`** - A dictionary containing structured data that matches your tool's output schema. This enables clients to programmatically process the results. If you provide `structured_content`, it must be a dictionary or `None`. If only `structured_content` is provided, it will also be used as `content` (converted to JSON string).
+
+```python
+ToolResult(
+    content="Found 3 users",
+    structured_content={"users": [{"name": "Alice"}, {"name": "Bob"}]}
+)
+```
+
+**`meta`** 
+<VersionBadge version="2.13.1" />
+Runtime metadata about the tool execution. Use this for performance metrics, debugging information, or any client-specific data that doesn't belong in the content or structured output.
+
+```python
+ToolResult(
+    content="Analysis complete",
+    structured_content={"result": "positive"},
+    meta={
+        "execution_time_ms": 145,
+        "model_version": "2.1",
+        "confidence": 0.95
+    }
+)
+```
+
+<Note>
+The `meta` field in `ToolResult` is for runtime metadata about tool execution (e.g., execution time, performance metrics). This is separate from the `meta` parameter in `@mcp.tool(meta={...})`, which provides static metadata about the tool definition itself.
+</Note>
+
+When returning `ToolResult`, you have full control - FastMCP won't automatically wrap or transform your data. `ToolResult` can be returned with or without an output schema.
+
+### Custom Serialization
+
+When you need custom serialization (like YAML, Markdown tables, or specialized formats), return `ToolResult` with your serialized content. This makes the serialization explicit and visible in your tool's code:
+
+```python
+import yaml
+from fastmcp import FastMCP
+from fastmcp.tools.tool import ToolResult
+
+mcp = FastMCP("MyServer")
+
+@mcp.tool
+def get_config() -> ToolResult:
+    """Returns configuration as YAML."""
+    data = {"api_key": "abc123", "debug": True, "rate_limit": 100}
+    return ToolResult(
+        content=yaml.dump(data, sort_keys=False),
+        structured_content=data
+    )
+```
+
+<Tip>
+For reusable serialization across multiple tools, create a wrapper decorator that returns `ToolResult`. This lets you compose serializers with other behaviors (logging, validation, caching) and keeps the serialization visible at the tool definition. See [examples/custom_tool_serializer_decorator.py](https://github.com/PrefectHQ/fastmcp/blob/main/examples/custom_tool_serializer_decorator.py) for a complete implementation.
+</Tip>
+
+## Error Handling
+
+<VersionBadge version="2.4.1" />
+
+If your tool encounters an error, you can raise a standard Python exception (`ValueError`, `TypeError`, `FileNotFoundError`, custom exceptions, etc.) or a FastMCP `ToolError`.
+
+By default, all exceptions (including their details) are logged and converted into an MCP error response to be sent back to the client LLM. This helps the LLM understand failures and react appropriately.
+
+If you want to mask internal error details for security reasons, you can:
+
+1. Use the `mask_error_details=True` parameter when creating your `FastMCP` instance:
+```python
+mcp = FastMCP(name="SecureServer", mask_error_details=True)
+```
+
+2. Or use `ToolError` to explicitly control what error information is sent to clients:
+```python
+from fastmcp import FastMCP
+from fastmcp.exceptions import ToolError
+
+@mcp.tool
+def divide(a: float, b: float) -> float:
+    """Divide a by b."""
+
+    if b == 0:
+        # Error messages from ToolError are always sent to clients,
+        # regardless of mask_error_details setting
+        raise ToolError("Division by zero is not allowed.")
+    
+    # If mask_error_details=True, this message would be masked
+    if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
+        raise TypeError("Both arguments must be numbers.")
+        
+    return a / b
+```
+
+When `mask_error_details=True`, only error messages from `ToolError` will include details, other exceptions will be converted to a generic message.
+
+## Timeouts
+
+<VersionBadge version="3.0.0" />
+
+Tools can specify a `timeout` parameter to limit how long execution can take. When the timeout is exceeded, the client receives an MCP error and the tool stops processing. This protects your server from unexpectedly slow operations that could block resources or leave clients waiting indefinitely.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+@mcp.tool(timeout=30.0)
+async def fetch_data(url: str) -> dict:
+    """Fetch data with a 30-second timeout."""
+    # If this takes longer than 30 seconds,
+    # the client receives an MCP error
+    ...
+```
+
+Timeouts are specified in seconds as a float. When a tool exceeds its timeout, FastMCP returns an MCP error with code `-32000` and a message indicating which tool timed out and how long it ran. Both sync and async tools support timeouts—sync functions run in thread pools, so the timeout applies to the entire operation regardless of execution model.
+
+<Note>
+Tools must explicitly opt-in to timeouts. There is no server-level default timeout setting.
+</Note>
+
+### Timeouts vs Background Tasks
+
+Timeouts apply to **foreground execution**—when a tool runs directly in response to a client request. They protect your server from tools that unexpectedly hang due to network issues, resource contention, or other transient problems.
+
+<Warning>
+The `timeout` parameter does **not** apply to background tasks. When a tool runs as a background task (`task=True`), execution happens in a Docket worker where the FastMCP timeout is not enforced.
+
+For task timeouts, use Docket's `Timeout` dependency directly in your function signature:
+
+```python
+from datetime import timedelta
+from docket import Timeout
+
+@mcp.tool(task=True)
+async def long_running_task(
+    data: str,
+    timeout: Timeout = Timeout(timedelta(minutes=10))
+) -> str:
+    """Task with a 10-minute timeout enforced by Docket."""
+    ...
+```
+
+See the [Docket documentation](https://chrisguidry.github.io/docket/dependencies/#task-timeouts) for more on task timeouts and retries.
+</Warning>
+
+When a tool times out, FastMCP logs a warning suggesting task mode. For operations you know will be long-running, use `task=True` instead—background tasks offload work to distributed workers and let clients poll for progress.
+
+## Component Visibility
+
+<VersionBadge version="3.0.0" />
+
+You can control which tools are enabled for clients using server-level enabled control. Disabled tools don't appear in `list_tools` and can't be called.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")
+
+@mcp.tool(tags={"admin"})
+def admin_action() -> str:
+    """Admin-only action."""
+    return "Done"
+
+@mcp.tool(tags={"public"})
+def public_action() -> str:
+    """Public action."""
+    return "Done"
+
+# Disable specific tools by key
+mcp.disable(keys={"tool:admin_action"})
+
+# Disable tools by tag
+mcp.disable(tags={"admin"})
+
+# Or use allowlist mode - only enable tools with specific tags
+mcp.enable(tags={"public"}, only=True)
+```
+
+See [Visibility](/servers/visibility) for the complete visibility control API including key formats, tag-based filtering, and provider-level control.
+
+## MCP Annotations
+
+<VersionBadge version="2.2.7" />
+
+FastMCP allows you to add specialized metadata to your tools through annotations. These annotations communicate how tools behave to client applications without consuming token context in LLM prompts.
+
+Annotations serve several purposes in client applications:
+- Adding user-friendly titles for display purposes
+- Indicating whether tools modify data or systems
+- Describing the safety profile of tools (destructive vs. non-destructive)
+- Signaling if tools interact with external systems
+
+You can add annotations to a tool using the `annotations` parameter in the `@mcp.tool` decorator. FastMCP accepts either a plain dict or `ToolAnnotations`; the examples below use `ToolAnnotations` for consistency and stronger editor/type support.
+
+```python
+from fastmcp.types import ToolAnnotations
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        title="Calculate Sum",
+        readOnlyHint=True,
+        openWorldHint=False,
+    )
+)
+def calculate_sum(a: float, b: float) -> float:
+    """Add two numbers together."""
+    return a + b
+```
+
+FastMCP supports these standard annotations:
+
+| Annotation | Type | Default | Purpose |
+| :--------- | :--- | :------ | :------ |
+| `title` | string | - | Display name for user interfaces |
+| `readOnlyHint` | boolean | false | Indicates if the tool only reads without making changes |
+| `destructiveHint` | boolean | true | For non-readonly tools, signals if changes are destructive |
+| `idempotentHint` | boolean | false | Indicates if repeated identical calls have the same effect as a single call |
+| `openWorldHint` | boolean | true | Specifies if the tool interacts with external systems |
+
+Remember that annotations help make better user experiences but should be treated as advisory hints. They help client applications present appropriate UI elements and safety controls, but won't enforce security boundaries on their own. Always focus on making your annotations accurately represent what your tool actually does.
+
+### Using Annotation Hints
+
+MCP clients like Claude and ChatGPT use annotation hints to determine when to skip confirmation prompts and how to present tools to users. The most commonly used hint is `readOnlyHint`, which signals that a tool only reads data without making changes.
+
+**Read-only tools** improve user experience by:
+- Skipping confirmation prompts for safe operations
+- Allowing broader access without security concerns
+- Enabling more aggressive batching and caching
+
+Mark a tool as read-only when it retrieves data, performs calculations, or checks status without modifying state:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.types import ToolAnnotations
+
+mcp = FastMCP("Data Server")
+
+@mcp.tool(annotations=ToolAnnotations(readOnlyHint=True))
+def get_user(user_id: str) -> dict:
+    """Retrieve user information by ID."""
+    return {"id": user_id, "name": "Alice"}
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        idempotentHint=True,  # Same result for repeated calls
+        openWorldHint=False   # Only internal data
+    )
+)
+def search_products(query: str) -> list[dict]:
+    """Search the product catalog."""
+    return [{"id": 1, "name": "Widget", "price": 29.99}]
+
+# Write operations - no readOnlyHint
+@mcp.tool()
+def update_user(user_id: str, name: str) -> dict:
+    """Update user information."""
+    return {"id": user_id, "name": name, "updated": True}
+
+@mcp.tool(annotations=ToolAnnotations(destructiveHint=True))
+def delete_user(user_id: str) -> dict:
+    """Permanently delete a user account."""
+    return {"deleted": user_id}
+```
+
+For tools that write to databases, send notifications, create/update/delete resources, or trigger workflows, omit `readOnlyHint` or set it to `False`. Use `destructiveHint=True` for operations that cannot be undone.
+
+Client-specific behavior:
+- **ChatGPT**: Skips confirmation prompts for read-only tools in Chat mode (see [ChatGPT integration](/integrations/chatgpt))
+- **Claude**: Uses hints to understand tool safety profiles and make better execution decisions
+
+## Notifications
+
+<VersionBadge version="2.9.1" />
+
+FastMCP automatically sends `notifications/tools/list_changed` notifications to connected clients when tools are added, removed, enabled, or disabled. This allows clients to stay up-to-date with the current tool set without manually polling for changes.
+
+```python
+@mcp.tool
+def example_tool() -> str:
+    return "Hello!"
+
+# These operations trigger notifications:
+mcp.add_tool(example_tool)              # Sends tools/list_changed notification
+mcp.disable(keys={"tool:example_tool"}) # Sends tools/list_changed notification
+mcp.enable(keys={"tool:example_tool"})  # Sends tools/list_changed notification
+mcp.local_provider.remove_tool("example_tool")  # Sends tools/list_changed notification
+```
+
+Notifications are only sent when these operations occur within an active MCP request context (e.g., when called from within a tool or other MCP operation). Operations performed during server initialization do not trigger notifications.
+
+Clients can handle these notifications using a [message handler](/clients/notifications) to automatically refresh their tool lists or update their interfaces.
+
+## Accessing the MCP Context
+
+Tools can access MCP features like logging, reading resources, or reporting progress through the `Context` object. To use it, add a parameter to your tool function with the type hint `Context`.
+
+```python
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP(name="ContextDemo")
+
+@mcp.tool
+async def process_data(data_uri: str, ctx: Context) -> dict:
+    """Process data from a resource with progress reporting."""
+    await ctx.info(f"Processing data from {data_uri}")
+    
+    # Read a resource
+    resource = await ctx.read_resource(data_uri)
+    data = resource[0].content if resource else ""
+    
+    # Report progress
+    await ctx.report_progress(progress=50, total=100)
+    
+    # Example request to the client's LLM for help
+    summary = await ctx.sample(f"Summarize this in 10 words: {data[:200]}")
+    
+    await ctx.report_progress(progress=100, total=100)
+    return {
+        "length": len(data),
+        "summary": summary.text
+    }
+```
+
+The Context object provides access to:
+
+- **Logging**: `ctx.debug()`, `ctx.info()`, `ctx.warning()`, `ctx.error()`
+- **Progress Reporting**: `ctx.report_progress(progress, total)`
+- **Resource Access**: `ctx.read_resource(uri)`
+- **LLM Sampling**: `ctx.sample(...)`
+- **Request Information**: `ctx.request_id`, `ctx.client_id`
+
+For full documentation on the Context object and all its capabilities, see the [Context documentation](/servers/context).
+
+## Server Behavior
+
+### Duplicate Tools
+
+<VersionBadge version="2.1.0" />
+
+You can control how the FastMCP server behaves if you try to register multiple tools with the same name. This is configured using the `on_duplicate_tools` argument when creating the `FastMCP` instance.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(
+    name="StrictServer",
+    # Configure behavior for duplicate tool names
+    on_duplicate_tools="error"
+)
+
+@mcp.tool
+def my_tool(): return "Version 1"
+
+# This will now raise a ValueError because 'my_tool' already exists
+# and on_duplicate_tools is set to "error".
+# @mcp.tool
+# def my_tool(): return "Version 2"
+```
+
+The duplicate behavior options are:
+
+-   `"warn"` (default): Logs a warning and the new tool replaces the old one.
+-   `"error"`: Raises a `ValueError`, preventing the duplicate registration.
+-   `"replace"`: Silently replaces the existing tool with the new one.
+-   `"ignore"`: Keeps the original tool and ignores the new registration attempt.
+
+### Removing Tools
+
+<VersionBadge version="2.3.4" />
+
+You can dynamically remove tools from a server through its [local provider](/servers/providers/local):
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="DynamicToolServer")
+
+@mcp.tool
+def calculate_sum(a: int, b: int) -> int:
+    """Add two numbers together."""
+    return a + b
+
+mcp.local_provider.remove_tool("calculate_sum")
+```
+
+## Versioning
+
+<VersionBadge version="3.0.0" />
+
+Tools support versioning, allowing you to maintain multiple implementations under the same name while clients automatically receive the highest version. See [Versioning](/servers/versioning) for complete documentation on version comparison, retrieval, and migration patterns.
diff --git a/docs/servers/transforms/code-mode.mdx b/docs/servers/transforms/code-mode.mdx
new file mode 100644
index 0000000..c7ef55b
--- /dev/null
+++ b/docs/servers/transforms/code-mode.mdx
@@ -0,0 +1,361 @@
+---
+title: Code Mode
+sidebarTitle: Code Mode
+description: Let LLMs write Python to orchestrate tools in a sandbox
+icon: flask
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.1.0" />
+
+<Warning>
+CodeMode is experimental. The core interface is stable, but the specific discovery tools and their parameters may evolve as we learn more about what works best in practice.
+</Warning>
+
+Standard MCP tool usage has two scaling problems. First, every tool in the catalog is loaded into the LLM's context upfront — with hundreds of tools, that's tens of thousands of tokens spent before the LLM even reads the user's request. Second, every tool call is a round-trip: the LLM calls a tool, the result passes back through the context window, the LLM reasons about it, calls another tool, and so on. Intermediate results that only exist to feed the next step still burn tokens flowing through the model.
+
+CodeMode solves both problems. Instead of seeing your entire tool catalog, the LLM gets meta-tools for discovering what's available and for writing and executing code that calls the tools it needs. It discovers on demand, writes a script that chains tool calls in a sandbox, and gets back only the final answer.
+
+The approach was introduced by Cloudflare in [Code Mode](https://blog.cloudflare.com/code-mode/) and explored further by Anthropic in [Code Execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp).
+
+## Getting Started
+
+<Tip>
+CodeMode requires the `code-mode` extra for sandbox support. Install it with `pip install "fastmcp[code-mode]"`.
+</Tip>
+
+You take a normal server with normally registered tools and add a `CodeMode` transform. The transform wraps your existing tools in the code mode machinery — your tool functions don't change at all:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.experimental.transforms.code_mode import CodeMode
+
+mcp = FastMCP("Server", transforms=[CodeMode()])
+
+@mcp.tool
+def add(x: int, y: int) -> int:
+    """Add two numbers."""
+    return x + y
+
+@mcp.tool
+def multiply(x: int, y: int) -> int:
+    """Multiply two numbers."""
+    return x * y
+```
+
+Clients connecting to this server no longer see `add` and `multiply` directly. Instead, they see the meta-tools that CodeMode provides — tools for discovering what's available and executing code against it. The original tools are still there, but they're accessed through the CodeMode layer.
+
+## Discovery
+
+Before the LLM can write code that calls your tools, it needs to know what tools exist and how to call them. This is the **discovery** process — the LLM uses meta-tools to learn about your tool catalog, then writes code against what it finds.
+
+The fundamental tradeoff is **tokens vs. round-trips**. Each discovery step is an LLM round-trip: the model calls a tool, waits for the response, reasons about it, then decides what to do next. More steps mean less wasted context (each step is targeted) but more latency and API calls. Fewer steps mean the LLM gets information upfront but pays for detail it might not need.
+
+By default, CodeMode gives the LLM three tools — `search`, `get_schema`, and `execute` — creating a three-stage discovery flow:
+
+<Steps>
+<Step title="Search for tools">
+First, the LLM uses the `search` meta-tool to find tools by keyword.
+
+For example, it might do `search(query="math numbers")` and receive the following response:
+
+```
+- add: Add two numbers.
+- multiply: Multiply two numbers.
+```
+
+This lets the LLM know which tools are available and what they do, significantly reducing the surface area it needs to consider.
+
+</Step>
+<Step title="Get parameter details for the tools">
+Next, the LLM calls `get_schema` to get parameter details for the tools it found in the previous step.
+
+For example, it might do `get_schema(tools=["add", "multiply"])` and receive the following response:
+
+```
+### add
+
+Add two numbers.
+
+**Parameters**
+- `x` (integer, required)
+- `y` (integer, required)
+
+### multiply
+
+Multiply two numbers.
+
+**Parameters**
+- `x` (integer, required)
+- `y` (integer, required)
+```
+
+Now the LLM knows the parameters for the tools it found, and can write code that chains the tool calls. If it needed more detail, it could have called `get_schema` with `detail="full"` to get the complete JSON schema.
+
+</Step>
+<Step title="Write and execute code that chains the tool calls">
+Finally, the LLM writes and executes code that chains the tool calls in a Python sandbox. Inside the sandbox, `call_tool(name, params)` is the only function available. The LLM uses this to compose tools into a workflow and return a final result.
+
+For example, it might write the following code and call the `execute` tool with it:
+
+```python
+a = await call_tool("add", {"x": 3, "y": 4})
+b = await call_tool("multiply", {"x": a, "y": 2})
+return b
+```
+
+The result is returned to the LLM.
+</Step>
+</Steps>
+
+This three-stage flow works well for most servers — each step pulls in only the information needed for the next one, keeping context usage minimal. But CodeMode's discovery surface is fully configurable. The sections below explain each built-in discovery tool and how to combine them into different patterns.
+
+## Discovery Tools
+
+CodeMode ships with four built-in discovery tools: `Search`, `GetSchemas`, `GetTags`, and `ListTools`. By default, only `Search` and `GetSchemas` are enabled. Each tool supports a `default_detail` parameter that sets the default verbosity level, and the LLM can override the detail level on any individual call.
+
+### Detail Levels
+
+`Search` and `GetSchemas` share the same three detail levels, so the same `detail` value produces the same output format regardless of which tool the LLM calls:
+
+| Level | Output | Token cost |
+|---|---|---|
+| `"brief"` | Tool names and one-line descriptions | Cheapest — good for scanning |
+| `"detailed"` | Compact markdown with parameter names, types, and required markers | Medium — often enough to write code |
+| `"full"` | Complete JSON schema | Most expensive — everything |
+
+`Search` defaults to `"brief"` and `GetSchemas` defaults to `"detailed"`.
+
+### Search
+
+`Search` finds tools by natural-language query using BM25 ranking. At its default `"brief"` detail, results include just tool names and descriptions — enough to decide which tools are worth inspecting further. The LLM can request `"detailed"` to get parameter schemas inline, or `"full"` for the complete JSON.
+
+Search results include an annotation like `"2 of 10 tools:"` when the result set is smaller than the full catalog, so the LLM knows there are more tools to discover with different queries.
+
+You can cap result count with `default_limit`. The LLM can also override the limit per call. This is useful for large catalogs where you want to keep search results focused:
+
+```python
+Search(default_limit=5)  # return at most 5 results per search
+```
+
+If your tools use [tags](/servers/tools#tags), Search also accepts a `tags` parameter so the LLM can narrow results to specific categories before searching.
+
+### GetSchemas
+
+`GetSchemas` returns parameter details for specific tools by name. At its default `"detailed"` level, it renders compact markdown with parameter names, types, and required markers. At `"full"`, it returns the complete JSON schema — useful when tools have deeply nested parameters that the compact format doesn't capture.
+
+### GetTags
+
+`GetTags` lets the LLM browse tools by category using [tag](/servers/tools#tags) metadata. At brief detail, the LLM sees tag names with counts. At full detail, it sees tools listed under each tag:
+
+```
+- math (3 tools)
+- text (2 tools)
+- untagged (1 tool)
+```
+
+`GetTags` isn't included in the defaults — add it when browsing by category would help the LLM orient itself in a large catalog. The LLM can browse tags first, then pass specific tags into Search to narrow results.
+
+### ListTools
+
+`ListTools` dumps the entire catalog at whatever detail level the LLM requests. It supports the same three detail levels as `Search` and `GetSchemas`, defaulting to `"brief"`.
+
+`ListTools` isn't included in the defaults — for large catalogs, search-based discovery is more token-efficient. But for smaller catalogs (under ~20 tools), letting the LLM see everything upfront can be faster than multiple search round-trips:
+
+```python
+from fastmcp.experimental.transforms.code_mode import CodeMode, ListTools, GetSchemas
+
+code_mode = CodeMode(
+    discovery_tools=[ListTools(), GetSchemas()],
+)
+```
+
+## Discovery Patterns
+
+The right discovery configuration depends on your server — how many tools you have and how complex their parameters are. It may be tempting to minimize round-trips by collapsing everything into fewer steps, but for the complex servers that benefit most from CodeMode, our experience is that staged discovery leads to better results. Flooding the LLM with detailed schemas for tools it doesn't end up using can hurt more than the extra round-trip costs. Each pattern below is a complete, copyable configuration.
+
+### Three-Stage
+
+The default. The LLM searches for candidates, inspects schemas for the ones it wants, then writes code. Best for **large or complex tool sets** where you want to minimize context usage — the LLM only pays for schemas it actually needs.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.experimental.transforms.code_mode import CodeMode
+
+mcp = FastMCP("Server", transforms=[CodeMode()])
+```
+
+If your tools use [tags](/servers/tools#tags), add `GetTags` so the LLM can browse by category before searching — giving it four stages of progressive disclosure:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.experimental.transforms.code_mode import CodeMode
+from fastmcp.experimental.transforms.code_mode import GetTags, Search, GetSchemas
+
+code_mode = CodeMode(
+    discovery_tools=[GetTags(), Search(), GetSchemas()],
+)
+
+mcp = FastMCP("Server", transforms=[code_mode])
+```
+
+### Two-Stage
+
+Search returns parameter schemas inline, so the LLM can go straight from search to execute. Best for **smaller catalogs** where the extra tokens per search result are a reasonable price for one fewer round-trip.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.experimental.transforms.code_mode import CodeMode
+from fastmcp.experimental.transforms.code_mode import Search, GetSchemas
+
+code_mode = CodeMode(
+    discovery_tools=[Search(default_detail="detailed"), GetSchemas()],
+)
+
+mcp = FastMCP("Server", transforms=[code_mode])
+```
+
+`GetSchemas` is still available as a fallback — the LLM can call it with `detail="full"` if it encounters a tool with complex nested parameters where the compact markdown isn't enough.
+
+### Single-Stage
+
+Skip discovery entirely and bake tool instructions into the execute tool's description. Best for **very simple servers** where the LLM already knows what tools are available — maybe there are only a few, or they're described in the system prompt.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.experimental.transforms.code_mode import CodeMode
+
+code_mode = CodeMode(
+    discovery_tools=[],
+    execute_description=(
+        "Available tools:\n"
+        "- add(x: int, y: int) -> int: Add two numbers\n"
+        "- multiply(x: int, y: int) -> int: Multiply two numbers\n\n"
+        "Write Python using `await call_tool(name, params)` and `return` the result."
+    ),
+)
+
+mcp = FastMCP("Server", transforms=[code_mode])
+```
+
+## Custom Discovery Tools
+
+Discovery tools are composable — you can mix the built-ins with your own. Each discovery tool is a callable that receives catalog access and returns a `Tool`. The catalog accessor is a function (not the catalog itself) because the catalog is request-scoped — different users may see different tools based on auth.
+
+Here's a minimal example:
+
+```python
+from fastmcp.experimental.transforms.code_mode import CodeMode
+from fastmcp.experimental.transforms.code_mode import GetToolCatalog, GetSchemas
+from fastmcp.server.context import Context
+from fastmcp.tools.tool import Tool
+
+def list_all_tools(get_catalog: GetToolCatalog) -> Tool:
+    async def list_tools(ctx: Context) -> str:
+        """List all available tool names."""
+        tools = await get_catalog(ctx)
+        return ", ".join(t.name for t in tools)
+
+    return Tool.from_function(fn=list_tools, name="list_tools")
+
+code_mode = CodeMode(discovery_tools=[list_all_tools, GetSchemas()])
+```
+
+The LLM sees the docstring of each discovery tool's inner function as its description — that's how it learns what each tool does and when to use it. Write docstrings that explain what the tool returns and when the LLM should call it.
+
+Discovery tools and the execute tool can also have custom names:
+
+```python
+from fastmcp.experimental.transforms.code_mode import Search, GetSchemas
+
+code_mode = CodeMode(
+    discovery_tools=[
+        Search(name="find_tools"),
+        GetSchemas(name="describe"),
+    ],
+    execute_tool_name="run_workflow",
+)
+
+mcp = FastMCP("Server", transforms=[code_mode])
+```
+
+## Sandbox Configuration
+
+### Resource Limits
+
+The default `MontySandboxProvider` enforces execution limits — timeouts, memory caps, recursion depth, and more.
+
+Constructed with no arguments, it applies a conservative baseline so the out-of-box configuration is not unbounded: `max_duration_secs=30` and `max_memory=100_000_000` (100 MB). Pass an explicit `limits` dict to override it, or `limits=None` to run with no limits at all:
+
+```python
+from fastmcp.experimental.transforms.code_mode import MontySandboxProvider
+
+MontySandboxProvider()                  # baseline: 30s, 100 MB
+MontySandboxProvider(limits={...})      # your own limits
+MontySandboxProvider(limits=None)       # explicitly uncapped
+```
+
+```python
+from fastmcp.experimental.transforms.code_mode import CodeMode
+from fastmcp.experimental.transforms.code_mode import MontySandboxProvider
+
+sandbox = MontySandboxProvider(
+    limits={"max_duration_secs": 10, "max_memory": 50_000_000},
+)
+
+mcp = FastMCP("Server", transforms=[CodeMode(sandbox_provider=sandbox)])
+```
+
+All keys are optional — omit any to leave that dimension uncapped:
+
+| Key | Type | Description |
+|---|---|---|
+| `max_duration_secs` | `float` | Maximum wall-clock execution time |
+| `max_memory` | `int` | Memory ceiling in bytes |
+| `max_allocations` | `int` | Cap on total object allocations |
+| `max_recursion_depth` | `int` | Maximum recursion depth |
+| `gc_interval` | `int` | Garbage collection frequency |
+
+### Tool Call Limits
+
+A single `execute` block can issue many `call_tool()` invocations — a loop in LLM-generated code can fan out into a large number of backend operations from one request. `CodeMode` caps this at `max_tool_calls` (default `50`); exceeding it raises a `ToolError`. Pass `None` for no cap:
+
+```python
+from fastmcp.experimental.transforms.code_mode import CodeMode
+
+CodeMode()                      # default: 50 call_tool() calls per execute()
+CodeMode(max_tool_calls=200)    # raise the cap
+CodeMode(max_tool_calls=None)   # no cap
+```
+
+### Custom Sandbox Providers
+
+You can replace the default sandbox with any object implementing the `SandboxProvider` protocol:
+
+```python
+from collections.abc import Callable
+from typing import Any
+
+from fastmcp.experimental.transforms.code_mode import CodeMode
+from fastmcp.experimental.transforms.code_mode import SandboxProvider
+
+class RemoteSandboxProvider:
+    async def run(
+        self,
+        code: str,
+        *,
+        inputs: dict[str, Any] | None = None,
+        external_functions: dict[str, Callable[..., Any]] | None = None,
+    ) -> Any:
+        # Send code to your remote sandbox runtime
+        ...
+
+mcp = FastMCP(
+    "Server",
+    transforms=[CodeMode(sandbox_provider=RemoteSandboxProvider())],
+)
+```
+
+The `external_functions` dict contains async callables injected into the sandbox scope — `execute` uses this to provide `call_tool`.
diff --git a/docs/servers/transforms/namespace.mdx b/docs/servers/transforms/namespace.mdx
new file mode 100644
index 0000000..fdb0d1c
--- /dev/null
+++ b/docs/servers/transforms/namespace.mdx
@@ -0,0 +1,63 @@
+---
+title: Namespace Transform
+sidebarTitle: Namespace
+description: Prefix component names to prevent conflicts
+icon: tag
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+The `Namespace` transform prefixes all component names, preventing conflicts when composing multiple servers.
+
+Tools and prompts receive an underscore-separated prefix. Resources and templates receive a path-segment prefix in their URIs.
+
+| Component | Original | With `Namespace("api")` |
+|-----------|----------|-------------------------|
+| Tool | `my_tool` | `api_my_tool` |
+| Prompt | `my_prompt` | `api_my_prompt` |
+| Resource | `data://info` | `data://api/info` |
+| Template | `data://{id}` | `data://api/{id}` |
+
+The most common use is through the `mount()` method's `namespace` parameter.
+
+```python
+from fastmcp import FastMCP
+
+weather = FastMCP("Weather")
+calendar = FastMCP("Calendar")
+
+@weather.tool
+def get_data() -> str:
+    return "Weather data"
+
+@calendar.tool
+def get_data() -> str:
+    return "Calendar data"
+
+# Without namespacing, these would conflict
+main = FastMCP("Main")
+main.mount(weather, namespace="weather")
+main.mount(calendar, namespace="calendar")
+
+# Clients see: weather_get_data, calendar_get_data
+```
+
+You can also apply namespacing directly using the `Namespace` transform.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.transforms import Namespace
+
+mcp = FastMCP("Server")
+
+@mcp.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+# Namespace all components
+mcp.add_transform(Namespace("api"))
+
+# Tool is now: api_greet
+```
diff --git a/docs/servers/transforms/namespacing.mdx b/docs/servers/transforms/namespacing.mdx
new file mode 100644
index 0000000..009a1ee
--- /dev/null
+++ b/docs/servers/transforms/namespacing.mdx
@@ -0,0 +1,9 @@
+---
+title: Namespacing
+sidebarTitle: Namespacing
+description: Namespace and transform components with transforms
+icon: wand-magic-sparkles
+redirect: /servers/transforms/transforms
+---
+
+This page has moved to [Transforms](/servers/transforms/transforms).
diff --git a/docs/servers/transforms/prompts-as-tools.mdx b/docs/servers/transforms/prompts-as-tools.mdx
new file mode 100644
index 0000000..6a9ab1b
--- /dev/null
+++ b/docs/servers/transforms/prompts-as-tools.mdx
@@ -0,0 +1,130 @@
+---
+title: Prompts as Tools
+sidebarTitle: Prompts as Tools
+description: Expose prompts to tool-only clients
+icon: message-lines
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+Some MCP clients only support tools. They cannot list or get prompts directly because they lack prompt protocol support. The `PromptsAsTools` transform bridges this gap by generating tools that provide access to your server's prompts.
+
+When you add `PromptsAsTools` to a server, it creates two tools that clients can call instead of using the prompt protocol:
+
+- **`list_prompts`** returns JSON describing all available prompts and their arguments
+- **`get_prompt`** renders a specific prompt with provided arguments
+
+This means any client that can call tools can now access prompts, even if the client has no native prompt support.
+
+## Basic Usage
+
+Pass your FastMCP server to `PromptsAsTools` when adding the transform. The generated tools route through the server at runtime, which means all server middleware — auth, visibility, rate limiting — applies to prompt operations automatically, exactly as it would for direct `prompts/get` calls.
+
+<Note>
+`PromptsAsTools` (and `ResourcesAsTools`) should be applied to a FastMCP server instance, not a raw Provider. The generated tools call back into the server's middleware chain at runtime, so they need a server to route through. If you want to expose only a subset of prompts, create a dedicated FastMCP server for those prompts and apply the transform there.
+</Note>
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.transforms import PromptsAsTools
+
+mcp = FastMCP("My Server")
+
+@mcp.prompt
+def analyze_code(code: str, language: str = "python") -> str:
+    """Analyze code for potential issues."""
+    return f"Analyze this {language} code:\n{code}"
+
+@mcp.prompt
+def explain_concept(concept: str) -> str:
+    """Explain a programming concept."""
+    return f"Explain: {concept}"
+
+# Add the transform - creates list_prompts and get_prompt tools
+mcp.add_transform(PromptsAsTools(mcp))
+```
+
+Clients now see three items: whatever tools you defined directly, plus `list_prompts` and `get_prompt`.
+
+## Listing Prompts
+
+The `list_prompts` tool returns JSON with metadata for each prompt, including its arguments.
+
+```python
+result = await client.call_tool("list_prompts", {})
+prompts = json.loads(result.data)
+# [
+#   {
+#     "name": "analyze_code",
+#     "description": "Analyze code for potential issues.",
+#     "arguments": [
+#       {"name": "code", "description": null, "required": true},
+#       {"name": "language", "description": null, "required": false}
+#     ]
+#   },
+#   {
+#     "name": "explain_concept",
+#     "description": "Explain a programming concept.",
+#     "arguments": [
+#       {"name": "concept", "description": null, "required": true}
+#     ]
+#   }
+#]
+```
+
+Each argument includes:
+- `name`: The argument name
+- `description`: Optional description from type hints or docstrings
+- `required`: Whether the argument must be provided
+
+## Getting Prompts
+
+The `get_prompt` tool accepts a prompt name and optional arguments dict. It returns the rendered prompt as JSON with a messages array.
+
+```python
+# Prompt with required and optional arguments
+result = await client.call_tool(
+    "get_prompt",
+    {
+        "name": "analyze_code",
+        "arguments": {
+            "code": "x = 1\nprint(x)",
+            "language": "python"
+        }
+    }
+)
+
+response = json.loads(result.data)
+# {
+#   "messages": [
+#     {
+#       "role": "user",
+#       "content": "Analyze this python code:\nx = 1\nprint(x)"
+#     }
+#   ]
+# }
+```
+
+If a prompt has no arguments, you can omit the `arguments` field or pass an empty dict:
+
+```python
+result = await client.call_tool(
+    "get_prompt",
+    {"name": "simple_prompt"}
+)
+```
+
+## Message Format
+
+Rendered prompts return a messages array following the standard MCP format. Each message includes:
+- `role`: The message role ("user" or "assistant")
+- `content`: The message text content
+
+Multi-message prompts are supported - the array will contain all messages in order.
+
+## Binary Content
+
+Unlike resources, prompts always return text content. There is no binary encoding needed.
diff --git a/docs/servers/transforms/resources-as-tools.mdx b/docs/servers/transforms/resources-as-tools.mdx
new file mode 100644
index 0000000..b79980d
--- /dev/null
+++ b/docs/servers/transforms/resources-as-tools.mdx
@@ -0,0 +1,111 @@
+---
+title: Resources as Tools
+sidebarTitle: Resources as Tools
+description: Expose resources to tool-only clients
+icon: toolbox
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+Some MCP clients only support tools. They cannot list or read resources directly because they lack resource protocol support. The `ResourcesAsTools` transform bridges this gap by generating tools that provide access to your server's resources.
+
+When you add `ResourcesAsTools` to a server, it creates two tools that clients can call instead of using the resource protocol:
+
+- **`list_resources`** returns JSON describing all available resources and templates
+- **`read_resource`** reads a specific resource by URI
+
+This means any client that can call tools can now access resources, even if the client has no native resource support.
+
+## Basic Usage
+
+Pass your FastMCP server to `ResourcesAsTools` when adding the transform. The generated tools route through the server at runtime, which means all server middleware — auth, visibility, rate limiting — applies to resource operations automatically, exactly as it would for direct `resources/read` calls.
+
+<Note>
+`ResourcesAsTools` (and `PromptsAsTools`) should be applied to a FastMCP server instance, not a raw Provider. The generated tools call back into the server's middleware chain at runtime, so they need a server to route through. If you want to expose only a subset of resources, create a dedicated FastMCP server for those resources and apply the transform there.
+</Note>
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.transforms import ResourcesAsTools
+
+mcp = FastMCP("My Server")
+
+@mcp.resource("config://app")
+def app_config() -> str:
+    """Application configuration."""
+    return '{"app_name": "My App", "version": "1.0.0"}'
+
+@mcp.resource("user://{user_id}/profile")
+def user_profile(user_id: str) -> str:
+    """Get a user's profile by ID."""
+    return f'{{"user_id": "{user_id}", "name": "User {user_id}"}}'
+
+# Add the transform - creates list_resources and read_resource tools
+mcp.add_transform(ResourcesAsTools(mcp))
+```
+
+Clients now see three tools: whatever tools you defined directly, plus `list_resources` and `read_resource`.
+
+Both generated tools are annotated with `readOnlyHint=True`, since they only read data. Clients that respect tool annotations (like Cursor) can use this to auto-confirm these tool calls without prompting the user.
+
+## Static Resources vs Templates
+
+Resources come in two forms, and the `list_resources` tool distinguishes between them in its JSON output.
+
+Static resources have fixed URIs. They represent concrete data that exists at a known location. In the listing output, static resources include a `uri` field containing the exact URI to request.
+
+Resource templates have parameterized URIs with placeholders like `{user_id}`. They represent patterns for accessing dynamic data. In the listing output, templates include a `uri_template` field showing the pattern with its placeholders.
+
+When a client calls `list_resources`, it receives JSON like this:
+
+```json
+[
+  {
+    "uri": "config://app",
+    "name": "app_config",
+    "description": "Application configuration.",
+    "mime_type": "text/plain"
+  },
+  {
+    "uri_template": "user://{user_id}/profile",
+    "name": "user_profile",
+    "description": "Get a user's profile by ID."
+  }
+]
+```
+
+The client can distinguish resource types by checking which field is present: `uri` for static resources, `uri_template` for templates.
+
+## Reading Resources
+
+The `read_resource` tool accepts a single `uri` argument. For static resources, pass the exact URI. For templates, fill in the placeholders with actual values.
+
+```python
+# Reading a static resource
+result = await client.call_tool("read_resource", {"uri": "config://app"})
+print(result.data)  # '{"app_name": "My App", "version": "1.0.0"}'
+
+# Reading a templated resource - fill in {user_id} with an actual ID
+result = await client.call_tool("read_resource", {"uri": "user://42/profile"})
+print(result.data)  # '{"user_id": "42", "name": "User 42"}'
+```
+
+The transform handles template matching automatically. When you request `user://42/profile`, it matches against the `user://{user_id}/profile` template, extracts `user_id=42`, and calls your resource function with that parameter.
+
+## Binary Content
+
+Resources that return binary data (like images or files) are automatically base64-encoded when read through the `read_resource` tool. This ensures binary content can be transmitted as a string in the tool response.
+
+```python
+@mcp.resource("data://binary", mime_type="application/octet-stream")
+def binary_data() -> bytes:
+    return b"\x00\x01\x02\x03"
+
+# Client receives base64-encoded string
+result = await client.call_tool("read_resource", {"uri": "data://binary"})
+decoded = base64.b64decode(result.data)  # b'\x00\x01\x02\x03'
+```
+
diff --git a/docs/servers/transforms/tool-search.mdx b/docs/servers/transforms/tool-search.mdx
new file mode 100644
index 0000000..204004f
--- /dev/null
+++ b/docs/servers/transforms/tool-search.mdx
@@ -0,0 +1,173 @@
+---
+title: Tool Search
+sidebarTitle: Tool Search
+description: Replace large tool catalogs with on-demand search
+icon: magnifying-glass
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.1.0" />
+
+When a server exposes hundreds or thousands of tools, sending the full catalog to an LLM wastes tokens and degrades tool selection accuracy. Search transforms solve this by replacing the tool listing with a search interface — the LLM discovers tools on demand instead of receiving everything upfront.
+
+## How It Works
+
+When you add a search transform, `list_tools()` returns just two synthetic tools instead of the full catalog:
+
+- **`search_tools`** finds tools matching a query and returns their full definitions
+- **`call_tool`** executes a discovered tool by name
+
+The original tools are still callable. They're hidden from the listing but remain fully functional — the search transform controls *discovery*, not *access*.
+
+Both synthetic tools search across tool names, descriptions, parameter names, and parameter descriptions. A search for `"email"` would match a tool named `send_email`, a tool with "email" in its description, or a tool with an `email_address` parameter.
+
+Search results are returned in the same JSON format as `list_tools`, including the full input schema, so the LLM can construct valid calls immediately without a second round-trip.
+
+## Search Strategies
+
+FastMCP provides two search transforms. They share the same interface — two synthetic tools, same configuration options — but differ in how they match queries to tools.
+
+### Regex Search
+
+`RegexSearchTransform` matches tools against a regex pattern using case-insensitive `re.search`. It has zero overhead and no index to build, making it a good default when the LLM knows roughly what it's looking for.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.transforms.search import RegexSearchTransform
+
+mcp = FastMCP("My Server", transforms=[RegexSearchTransform()])
+
+@mcp.tool
+def search_database(query: str, limit: int = 10) -> list[dict]:
+    """Search the database for records matching the query."""
+    ...
+
+@mcp.tool
+def delete_record(record_id: str) -> bool:
+    """Delete a record from the database by its ID."""
+    ...
+
+@mcp.tool
+def send_email(to: str, subject: str, body: str) -> bool:
+    """Send an email to the given recipient."""
+    ...
+```
+
+The LLM's `search_tools` call takes a `pattern` parameter — a regex string:
+
+```python
+# Exact substring match
+result = await client.call_tool("search_tools", {"pattern": "database"})
+# Returns: search_database, delete_record
+
+# Regex pattern
+result = await client.call_tool("search_tools", {"pattern": "send.*email|notify"})
+# Returns: send_email
+```
+
+Results are returned in catalog order. If the pattern is invalid regex, the search returns an empty list rather than raising an error.
+
+### BM25 Search
+
+`BM25SearchTransform` ranks tools by relevance using the [BM25 Okapi](https://en.wikipedia.org/wiki/Okapi_BM25) algorithm. It's better for natural language queries because it scores each tool based on term frequency and document rarity, returning results ranked by relevance rather than filtering by match/no-match.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.transforms.search import BM25SearchTransform
+
+mcp = FastMCP("My Server", transforms=[BM25SearchTransform()])
+
+# ... define tools ...
+```
+
+The LLM's `search_tools` call takes a `query` parameter — natural language:
+
+```python
+result = await client.call_tool("search_tools", {
+    "query": "tools for deleting things from the database"
+})
+# Returns: delete_record ranked first, search_database second
+```
+
+BM25 builds an in-memory index from the searchable text of all tools. The index is created lazily on the first search and automatically rebuilt whenever the tool catalog changes — for example, when tools are added, removed, or have their descriptions updated. The staleness check is based on a hash of all searchable text, so description changes are detected even when tool names stay the same.
+
+### Which to Choose
+
+Use **regex** when your LLM is good at constructing targeted patterns and you want deterministic, predictable results. Regex is also simpler to debug — you can see exactly what pattern was sent.
+
+Use **BM25** when your LLM tends to describe what it needs in natural language, or when your tool catalog has nuanced descriptions where relevance ranking adds value. BM25 handles partial matches and synonyms better because it scores on individual terms rather than requiring a single pattern to match.
+
+## Configuration
+
+Both search transforms accept the same configuration options.
+
+### Limiting Results
+
+By default, search returns at most 5 tools. Adjust `max_results` based on your catalog size and how much context you want the LLM to receive per search:
+
+```python
+mcp.add_transform(RegexSearchTransform(max_results=10))
+mcp.add_transform(BM25SearchTransform(max_results=3))
+```
+
+With regex, results stop as soon as the limit is reached (first N matches in catalog order). With BM25, all tools are scored and the top N by relevance are returned.
+
+### Pinning Tools
+
+Some tools should always be visible regardless of search. Use `always_visible` to pin them in the listing alongside the synthetic tools:
+
+```python
+mcp.add_transform(RegexSearchTransform(
+    always_visible=["help", "status"],
+))
+
+# list_tools returns: help, status, search_tools, call_tool
+```
+
+Pinned tools appear directly in `list_tools` so the LLM can call them without searching. They're excluded from search results to avoid duplication.
+
+### Custom Tool Names
+
+The default names `search_tools` and `call_tool` can be changed to avoid conflicts with real tools:
+
+```python
+mcp.add_transform(RegexSearchTransform(
+    search_tool_name="find_tools",
+    call_tool_name="run_tool",
+))
+```
+
+## The `call_tool` Proxy
+
+The `call_tool` proxy forwards calls to the real tool. When a client calls `call_tool(name="search_database", arguments={...})`, the proxy resolves `search_database` through the server's normal tool pipeline — including transforms and middleware — and executes it.
+
+The proxy rejects attempts to call the synthetic tools themselves. `call_tool(name="call_tool")` raises an error rather than recursing.
+
+<Note>
+Tools discovered through search can also be called directly via `client.call_tool("search_database", {...})` without going through the proxy. The proxy exists for LLMs that only know about the tools returned by `list_tools` and need a way to invoke discovered tools through a tool they can see.
+</Note>
+
+## Auth and Visibility
+
+Search results respect the full authorization pipeline. Tools filtered by middleware, visibility transforms, or component-level auth checks won't appear in search results.
+
+The search tool queries `list_tools()` through the complete pipeline at search time, so the same filtering that controls what a client sees in the listing also controls what they can discover through search.
+
+```python
+from fastmcp.server.transforms import Visibility
+from fastmcp.server.transforms.search import RegexSearchTransform
+
+mcp = FastMCP("My Server")
+
+# ... define tools ...
+
+# Disable admin tools globally
+mcp.add_transform(Visibility(False, tags={"admin"}))
+
+# Add search — admin tools won't appear in results
+mcp.add_transform(RegexSearchTransform())
+```
+
+Session-level visibility changes (via `ctx.disable_components()`) are also reflected immediately in search results.
diff --git a/docs/servers/transforms/tool-transformation.mdx b/docs/servers/transforms/tool-transformation.mdx
new file mode 100644
index 0000000..a50513f
--- /dev/null
+++ b/docs/servers/transforms/tool-transformation.mdx
@@ -0,0 +1,230 @@
+---
+title: Tool Transformation
+sidebarTitle: Tool Transformation
+description: Modify tool schemas - rename, reshape arguments, and customize behavior
+icon: wrench
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+Tool transformation lets you modify tool schemas - renaming tools, changing descriptions, adjusting tags, and reshaping argument schemas. FastMCP provides two mechanisms that share the same configuration options but differ in timing.
+
+**Deferred transformation** with `ToolTransform` applies modifications when tools flow through a transform chain. Use this for tools from mounted servers, proxies, or other providers where you don't control the source directly.
+
+**Immediate transformation** with `Tool.from_tool()` creates a modified tool object right away. Use this when you have direct access to a tool and want to transform it before registration.
+
+## ToolTransform
+
+The `ToolTransform` class is a transform that modifies tools as they flow through a provider. Provide a dictionary mapping original tool names to their transformation configuration.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.transforms import ToolTransform
+from fastmcp.tools.tool_transform import ToolTransformConfig
+
+mcp = FastMCP("Server")
+
+@mcp.tool
+def verbose_internal_data_fetcher(query: str) -> str:
+    """Fetches data from the internal database."""
+    return f"Results for: {query}"
+
+# Rename the tool to something simpler
+mcp.add_transform(ToolTransform({
+    "verbose_internal_data_fetcher": ToolTransformConfig(
+        name="search",
+        description="Search the database.",
+    )
+}))
+
+# Clients see "search" with the cleaner description
+```
+
+`ToolTransform` is useful when you want to modify tools from mounted or proxied servers without changing the original source.
+
+## Tool.from_tool()
+
+Use `Tool.from_tool()` when you have the tool object and want to create a transformed version for registration.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.tools import Tool, tool
+from fastmcp.tools.tool_transform import ArgTransform
+
+# Create a tool without registering it
+@tool
+def search(q: str, limit: int = 10) -> list[str]:
+    """Search for items."""
+    return [f"Result {i} for {q}" for i in range(limit)]
+
+# Transform it before registration
+better_search = Tool.from_tool(
+    search,
+    name="find_items",
+    description="Find items matching your search query.",
+    transform_args={
+        "q": ArgTransform(
+            name="query",
+            description="The search terms to look for.",
+        ),
+    },
+)
+
+mcp = FastMCP("Server")
+mcp.add_tool(better_search)
+```
+
+The standalone `@tool` decorator (from `fastmcp.tools`) creates a Tool object without registering it to any server. This separates creation from registration, letting you transform tools before deciding where they go.
+
+## Modification Options
+
+Both mechanisms support the same modifications.
+
+**Tool-level options:**
+
+| Option | Description |
+|--------|-------------|
+| `name` | New name for the tool |
+| `description` | New description |
+| `title` | Human-readable title |
+| `tags` | Set of tags for categorization |
+| `annotations` | MCP ToolAnnotations |
+| `meta` | Custom metadata dictionary |
+| `enabled` | Whether the tool is visible to clients (default `True`) |
+
+**Argument-level options** (via `ArgTransform` or `ArgTransformConfig`):
+
+| Option | Description |
+|--------|-------------|
+| `name` | Rename the argument |
+| `description` | New description for the argument |
+| `default` | New default value |
+| `default_factory` | Callable that generates a default (requires `hide=True`) |
+| `hide` | Remove from client-visible schema |
+| `required` | Make an optional argument required |
+| `type` | Change the argument's type |
+| `examples` | Example values for the argument |
+
+## Hiding Arguments
+
+Hide arguments to simplify the interface or inject values the client shouldn't control.
+
+```python
+from fastmcp.tools.tool_transform import ArgTransform
+
+# Hide with a constant value
+transform_args = {
+    "api_key": ArgTransform(hide=True, default="secret-key"),
+}
+
+# Hide with a dynamic value
+import uuid
+transform_args = {
+    "request_id": ArgTransform(hide=True, default_factory=lambda: str(uuid.uuid4())),
+}
+```
+
+Hidden arguments disappear from the tool's schema. The client never sees them, but the underlying function receives the configured value.
+
+<Warning>
+`default_factory` requires `hide=True`. Visible arguments need static defaults that can be represented in JSON Schema.
+</Warning>
+
+## Renaming Arguments
+
+Rename arguments to make them more intuitive for LLMs or match your API conventions.
+
+```python
+from fastmcp.tools import Tool, tool
+from fastmcp.tools.tool_transform import ArgTransform
+
+@tool
+def search(q: str, n: int = 10) -> list[str]:
+    """Search for items."""
+    return []
+
+better_search = Tool.from_tool(
+    search,
+    transform_args={
+        "q": ArgTransform(name="query", description="Search terms"),
+        "n": ArgTransform(name="max_results", description="Maximum results to return"),
+    },
+)
+```
+
+## Custom Transform Functions
+
+For advanced scenarios, provide a `transform_fn` that intercepts tool execution. The function can validate inputs, modify outputs, or add custom logic while still calling the original tool via `forward()`.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.tools import Tool, tool
+from fastmcp.tools.tool_transform import forward, ArgTransform
+
+@tool
+def divide(a: float, b: float) -> float:
+    """Divide a by b."""
+    return a / b
+
+async def safe_divide(numerator: float, denominator: float) -> float:
+    if denominator == 0:
+        raise ValueError("Cannot divide by zero")
+    return await forward(numerator=numerator, denominator=denominator)
+
+safe_division = Tool.from_tool(
+    divide,
+    name="safe_divide",
+    transform_fn=safe_divide,
+    transform_args={
+        "a": ArgTransform(name="numerator"),
+        "b": ArgTransform(name="denominator"),
+    },
+)
+
+mcp = FastMCP("Server")
+mcp.add_tool(safe_division)
+```
+
+The `forward()` function handles argument mapping automatically. Call it with the transformed argument names, and it maps them back to the original function's parameters.
+
+For direct access to the original function without mapping, use `forward_raw()` with the original parameter names.
+
+## Context-Aware Tool Factories
+
+You can write functions that act as "factories," generating specialized versions of a tool for different contexts. For example, create a `get_my_data` tool for the current user by hiding the `user_id` parameter and providing it automatically.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.tools import Tool, tool
+from fastmcp.tools.tool_transform import ArgTransform
+
+# A generic tool that requires a user_id
+@tool
+def get_user_data(user_id: str, query: str) -> str:
+    """Fetch data for a specific user."""
+    return f"Data for user {user_id}: {query}"
+
+
+def create_user_tool(user_id: str) -> Tool:
+    """Factory that creates a user-specific version of get_user_data."""
+    return Tool.from_tool(
+        get_user_data,
+        name="get_my_data",
+        description="Fetch your data. No need to specify a user ID.",
+        transform_args={
+            "user_id": ArgTransform(hide=True, default=user_id),
+        },
+    )
+
+
+# Create a server with a tool customized for the current user
+mcp = FastMCP("User Server")
+current_user_id = "user-123"  # e.g., from auth context
+mcp.add_tool(create_user_tool(current_user_id))
+
+# Clients see "get_my_data(query: str)" — user_id is injected automatically
+```
+
+This pattern is useful for multi-tenant servers where each connection gets tools pre-configured with their identity, or for wrapping generic tools with environment-specific defaults.
diff --git a/docs/servers/transforms/transforms.mdx b/docs/servers/transforms/transforms.mdx
new file mode 100644
index 0000000..4347b2f
--- /dev/null
+++ b/docs/servers/transforms/transforms.mdx
@@ -0,0 +1,173 @@
+---
+title: Transforms Overview
+sidebarTitle: Overview
+description: Modify components as they flow through your server
+icon: wand-magic-sparkles
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+Transforms modify components as they flow from providers to clients. When a client asks "what tools do you have?", the request passes through each transform in the chain. Each transform can modify the components before passing them along.
+
+## Mental Model
+
+Think of transforms as filters in a pipeline. Components flow from providers through transforms to reach clients:
+
+```
+Provider → [Transform A] → [Transform B] → Client
+```
+
+When listing components, transforms receive sequences and return transformed sequences—a pure function pattern. When getting a specific component by name, transforms use a middleware pattern with `call_next`, working in reverse: mapping the client's requested name back to the original, then transforming the result.
+
+## Built-in Transforms
+
+FastMCP provides several transforms for common use cases:
+
+- **[Namespace](/servers/transforms/namespace)** - Prefix component names to prevent conflicts when composing servers
+- **[Tool Transformation](/servers/transforms/tool-transformation)** - Rename tools, modify descriptions, reshape arguments
+- **[Enabled](/servers/visibility)** - Control which components are visible at runtime
+- **[Tool Search](/servers/transforms/tool-search)** - Replace large tool catalogs with on-demand search
+- **[Resources as Tools](/servers/transforms/resources-as-tools)** - Expose resources to tool-only clients
+- **[Prompts as Tools](/servers/transforms/prompts-as-tools)** - Expose prompts to tool-only clients
+- **[Code Mode (Experimental)](/servers/transforms/code-mode)** - Replace many tools with programmable `search` + `execute`
+
+## Server vs Provider Transforms
+
+Transforms can be added at two levels, each serving different purposes.
+
+### Provider-Level Transforms
+
+Provider transforms apply to components from a specific provider. They run first, modifying components before they reach the server level.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers import FastMCPProvider
+from fastmcp.server.transforms import Namespace, ToolTransform
+from fastmcp.tools.tool_transform import ToolTransformConfig
+
+sub_server = FastMCP("Sub")
+
+@sub_server.tool
+def process(data: str) -> str:
+    return f"Processed: {data}"
+
+# Create provider and add transforms
+provider = FastMCPProvider(sub_server)
+provider.add_transform(Namespace("api"))
+provider.add_transform(ToolTransform({
+    "api_process": ToolTransformConfig(description="Process data through the API"),
+}))
+
+main = FastMCP("Main", providers=[provider])
+# Tool is now: api_process with updated description
+```
+
+When using `mount()`, the returned provider reference lets you add transforms directly.
+
+```python
+main = FastMCP("Main")
+mount = main.mount(sub_server, namespace="api")
+mount.add_transform(ToolTransform({...}))
+```
+
+### Server-Level Transforms
+
+Server transforms apply to all components from all providers. They run after provider transforms, seeing the already-transformed names.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.transforms import Namespace
+
+mcp = FastMCP("Server", transforms=[Namespace("v1")])
+
+@mcp.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+# All tools become v1_toolname
+```
+
+Server-level transforms are useful for API versioning or applying consistent naming across your entire server.
+
+### Transform Order
+
+Transforms stack in the order they're added. The first transform added is innermost (closest to the provider), and subsequent transforms wrap it.
+
+```python
+from fastmcp.server.providers import FastMCPProvider
+from fastmcp.server.transforms import Namespace, ToolTransform
+from fastmcp.tools.tool_transform import ToolTransformConfig
+
+provider = FastMCPProvider(server)
+provider.add_transform(Namespace("api"))           # Applied first
+provider.add_transform(ToolTransform({             # Sees namespaced names
+    "api_verbose_name": ToolTransformConfig(name="short"),
+}))
+
+# Flow: "verbose_name" -> "api_verbose_name" -> "short"
+```
+
+When a client requests "short", the transforms reverse the mapping: ToolTransform maps "short" to "api_verbose_name", then Namespace strips the prefix to find "verbose_name" in the provider.
+
+## Custom Transforms
+
+Create custom transforms by subclassing `Transform` and overriding the methods you need.
+
+```python
+from collections.abc import Sequence
+from fastmcp.server.transforms import Transform, GetToolNext
+from fastmcp.tools.tool import Tool
+
+class TagFilter(Transform):
+    """Filter tools to only those with specific tags."""
+
+    def __init__(self, required_tags: set[str]):
+        self.required_tags = required_tags
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        return [t for t in tools if t.tags & self.required_tags]
+
+    async def get_tool(self, name: str, call_next: GetToolNext) -> Tool | None:
+        tool = await call_next(name)
+        if tool and tool.tags & self.required_tags:
+            return tool
+        return None
+```
+
+The `Transform` base class provides default implementations that pass through unchanged. Override only the methods relevant to your transform.
+
+Each component type has two methods with different patterns:
+
+| Method | Pattern | Purpose |
+|--------|---------|---------|
+| `list_tools(tools)` | Pure function | Transform the sequence of tools |
+| `get_tool(name, call_next)` | Middleware | Transform lookup by name |
+| `list_resources(resources)` | Pure function | Transform the sequence of resources |
+| `get_resource(uri, call_next)` | Middleware | Transform lookup by URI |
+| `list_resource_templates(templates)` | Pure function | Transform the sequence of templates |
+| `get_resource_template(uri, call_next)` | Middleware | Transform template lookup by URI |
+| `list_prompts(prompts)` | Pure function | Transform the sequence of prompts |
+| `get_prompt(name, call_next)` | Middleware | Transform lookup by name |
+
+List methods receive sequences directly and return transformed sequences. Get methods use `call_next` for routing flexibility—when a client requests "new_name", your transform maps it back to "original_name" before calling `call_next()`.
+
+```python
+class PrefixTransform(Transform):
+    def __init__(self, prefix: str):
+        self.prefix = prefix
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        return [t.model_copy(update={"name": f"{self.prefix}_{t.name}"}) for t in tools]
+
+    async def get_tool(self, name: str, call_next: GetToolNext) -> Tool | None:
+        # Reverse the prefix to find the original
+        if not name.startswith(f"{self.prefix}_"):
+            return None
+        original = name[len(self.prefix) + 1:]
+        tool = await call_next(original)
+        if tool:
+            return tool.model_copy(update={"name": name})
+        return None
+```
diff --git a/docs/servers/versioning.mdx b/docs/servers/versioning.mdx
new file mode 100644
index 0000000..4c44a73
--- /dev/null
+++ b/docs/servers/versioning.mdx
@@ -0,0 +1,336 @@
+---
+title: Versioning
+sidebarTitle: Versioning
+description: Serve multiple API versions from a single codebase
+icon: code-branch
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+Component versioning lets you maintain multiple implementations of the same tool, resource, or prompt under a single identifier. You register each version, and FastMCP handles the rest: clients see the highest version by default, but you can filter to expose exactly the versions you want.
+
+The primary use case is serving different API versions from one codebase. Instead of maintaining separate deployments for v1 and v2 clients, you version your components and use `VersionFilter` to create distinct API surfaces.
+
+## Versioned API Surfaces
+
+Consider a server that needs to support both v1 and v2 clients. The v2 API adds new parameters to existing tools, and you want both versions to coexist cleanly. Define your components on a shared provider, then create separate servers with different version filters.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers import LocalProvider
+from fastmcp.server.transforms import VersionFilter
+
+# Define versioned components on a shared provider
+components = LocalProvider()
+
+@components.tool(version="1.0")
+def calculate(x: int, y: int) -> int:
+    """Add two numbers."""
+    return x + y
+
+@components.tool(version="2.0")
+def calculate(x: int, y: int, z: int = 0) -> int:
+    """Add two or three numbers."""
+    return x + y + z
+
+# Create servers that share the provider with different filters
+api_v1 = FastMCP("API v1", providers=[components])
+api_v1.add_transform(VersionFilter(version_lt="2.0"))
+
+api_v2 = FastMCP("API v2", providers=[components])
+api_v2.add_transform(VersionFilter(version_gte="2.0"))
+```
+
+Clients connecting to `api_v1` see the two-argument `calculate`. Clients connecting to `api_v2` see the three-argument version. Both servers share the same component definitions.
+
+`VersionFilter` accepts two keyword-only parameters that mirror comparison operators: `version_gte` (greater than or equal) and `version_lt` (less than). You can use either or both to define your version range.
+
+```python
+# Versions < 3.0 (v1.x and v2.x)
+VersionFilter(version_lt="3.0")
+
+# Versions >= 2.0 (v2.x and later)
+VersionFilter(version_gte="2.0")
+
+# Versions in range [2.0, 3.0) (only v2.x)
+VersionFilter(version_gte="2.0", version_lt="3.0")
+```
+
+<Note>
+**Unversioned components are exempt from version filtering by default.** Set `include_unversioned=False` to exclude them. Including them by default ensures that adding version filtering to a server with mixed versioned and unversioned components doesn't accidentally hide the unversioned ones. To prevent confusion, FastMCP forbids mixing versioned and unversioned components with the same name.
+</Note>
+
+### Filtering Mounted Servers
+
+When you mount child servers and apply a `VersionFilter` to the parent, the filter applies to components from mounted servers as well. Range filtering (`version_gte` and `version_lt`) is handled at the provider level, meaning mounted servers don't need to know about the parent's version constraints.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.transforms import VersionFilter
+
+# Child server with versioned components
+child = FastMCP("Child")
+
+@child.tool(version="1.0")
+def process(data: str) -> str:
+    return data.upper()
+
+@child.tool(version="2.0")
+def process(data: str, mode: str = "default") -> str:
+    return data.upper() if mode == "default" else data.lower()
+
+# Parent server mounts child and applies version filter
+parent = FastMCP("Parent")
+parent.mount(child, namespace="child")
+parent.add_transform(VersionFilter(version_lt="2.0"))
+
+# Clients see only child_process v1.0
+```
+
+The parent's `VersionFilter` sees components after they've been namespaced, but filters based on version regardless of namespace. This lets you apply version policies consistently across your entire server hierarchy.
+
+## Declaring Versions
+
+Add a `version` parameter to any component decorator. FastMCP stores versions as strings and groups components by their identifier (name for tools and prompts, URI for resources).
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+@mcp.tool(version="1.0")
+def process(data: str) -> str:
+    """Original processing."""
+    return data.upper()
+
+@mcp.tool(version="2.0")
+def process(data: str, mode: str = "default") -> str:
+    """Enhanced processing with mode selection."""
+    if mode == "reverse":
+        return data[::-1].upper()
+    return data.upper()
+```
+
+Both versions are registered. When a client lists tools, they see only `process` with version 2.0 (the highest). When they invoke `process`, version 2.0 executes. The same pattern applies to resources and prompts.
+
+### Versioned vs Unversioned Components
+
+For any given component name, you must choose one approach: either version all implementations or version none of them. Mixing versioned and unversioned components with the same name raises an error at registration time.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+@mcp.tool
+def calculate(x: int, y: int) -> int:
+    """Unversioned tool."""
+    return x + y
+
+@mcp.tool(version="2.0")  # Raises ValueError
+def calculate(x: int, y: int, z: int = 0) -> int:
+    """Cannot mix versioned with unversioned."""
+    return x + y + z
+```
+
+The error message explains the conflict: "Cannot add versioned tool 'calculate' (version='2.0'): an unversioned tool with this name already exists. Either version all components or none."
+
+This restriction helps keep version filtering behavior predictable.
+
+Resources and prompts follow the same pattern.
+
+```python
+@mcp.resource("config://app", version="1.0")
+def config_v1() -> str:
+    return '{"format": "legacy"}'
+
+@mcp.resource("config://app", version="2.0")
+def config_v2() -> str:
+    return '{"format": "modern", "schema": "v2"}'
+
+@mcp.prompt(version="1.0")
+def summarize(text: str) -> str:
+    return f"Summarize: {text}"
+
+@mcp.prompt(version="2.0")
+def summarize(text: str, style: str = "concise") -> str:
+    return f"Summarize in a {style} style: {text}"
+```
+
+### Version Discovery
+
+When clients list components, each versioned component includes metadata about all available versions. This lets clients discover what versions exist before deciding which to use. The `meta.fastmcp.versions` field contains all registered versions sorted from highest to lowest.
+
+```python
+from fastmcp import Client
+
+async with Client(server) as client:
+    tools = await client.list_tools()
+
+    for tool in tools:
+        if tool.meta:
+            fastmcp_meta = tool.meta.get("fastmcp", {})
+            # Current version being returned (highest by default)
+            print(f"Version: {fastmcp_meta.get('version')}")
+            # All available versions for this component
+            print(f"Available: {fastmcp_meta.get('versions')}")
+```
+
+For a tool with versions `"1.0"` and `"2.0"`, listing returns the `2.0` implementation with `meta.fastmcp.version` set to `"2.0"` and `meta.fastmcp.versions` set to `["2.0", "1.0"]`. Unversioned components omit these fields entirely.
+
+This discovery mechanism enables clients to make informed decisions about which version to request, support graceful degradation when newer versions introduce breaking changes, or display version information in developer tools.
+
+## Requesting Specific Versions
+
+By default, clients receive and invoke the highest version of each component. When you need a specific version, FastMCP provides two approaches: the FastMCP client API for Python applications, and the MCP protocol mechanism for any MCP-compatible client.
+
+### FastMCP Client
+
+The FastMCP client's `call_tool` and `get_prompt` methods accept an optional `version` parameter. When specified, the server executes that exact version instead of the highest.
+
+```python
+from fastmcp import Client
+
+async with Client(server) as client:
+    # Call the highest version (default behavior)
+    result = await client.call_tool("calculate", {"x": 1, "y": 2})
+
+    # Call a specific version
+    result_v1 = await client.call_tool("calculate", {"x": 1, "y": 2}, version="1.0")
+
+    # Get a specific prompt version
+    prompt = await client.get_prompt("summarize", {"text": "..."}, version="1.0")
+```
+
+If the requested version doesn't exist, the server raises a `NotFoundError`. This ensures you get exactly what you asked for rather than silently falling back to a different version.
+
+### MCP Protocol
+
+For generic MCP clients that don't have built-in version support, pass the version through the `_meta` field in arguments. FastMCP servers extract the version from `_meta.fastmcp.version` before processing.
+
+<CodeGroup>
+```json Tool Call Arguments
+{
+  "x": 1,
+  "y": 2,
+  "_meta": {
+    "fastmcp": {
+      "version": "1.0"
+    }
+  }
+}
+```
+
+```json Prompt Arguments
+{
+  "text": "Summarize this document...",
+  "_meta": {
+    "fastmcp": {
+      "version": "1.0"
+    }
+  }
+}
+```
+</CodeGroup>
+
+The `_meta` field is part of the MCP request params, not arguments, so your component implementation never sees it. This convention allows version selection to work across any MCP client without requiring protocol changes. The FastMCP client handles this automatically when you pass the `version` parameter.
+
+## Version Comparison
+
+FastMCP compares versions to determine which is "highest" when multiple versions share an identifier. The comparison behavior depends on the version format.
+
+For [PEP 440](https://peps.python.org/pep-0440/) versions (like `"1.0"`, `"2.1.3"`, `"1.0a1"`), FastMCP uses semantic comparison where numeric segments are compared as numbers.
+
+```python
+# PEP 440 versions compare semantically
+"1" < "2" < "10"           # Numeric order (not "1" < "10" < "2")
+"1.9" < "1.10"             # Numeric order (not "1.10" < "1.9")
+"1.0a1" < "1.0b1" < "1.0"  # Pre-releases sort before releases
+```
+
+For other formats (dates, custom schemes), FastMCP falls back to lexicographic string comparison. This works well for ISO dates and other naturally sortable formats.
+
+```python
+# Non-PEP 440 versions compare as strings
+"2025-01-15" < "2025-02-01"  # ISO dates sort correctly
+"alpha" < "beta"             # Alphabetical order
+```
+
+The `v` prefix is stripped before comparison, so `"v1.0"` and `"1.0"` are treated as equal for sorting purposes.
+
+## Retrieving Specific Versions
+
+Server-side code can retrieve specific versions rather than just the highest. This is useful during migrations when you need to compare behavior between versions or access legacy implementations.
+
+The `get_tool`, `get_resource`, and `get_prompt` methods accept an optional `version` parameter. Without it, they return the highest version. With it, they return exactly that version.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+@mcp.tool(version="1.0")
+def add(x: int, y: int) -> int:
+    return x + y
+
+@mcp.tool(version="2.0")
+def add(x: int, y: int) -> int:
+    return x + y + 100  # Different behavior
+
+# Get highest version (default)
+tool = await mcp.get_tool("add")
+print(tool.version)  # "2.0"
+
+# Get specific version
+tool_v1 = await mcp.get_tool("add", version="1.0")
+print(tool_v1.version)  # "1.0"
+```
+
+If the requested version doesn't exist, a `NotFoundError` is raised.
+
+## Removing Versions
+
+The `remove_tool`, `remove_resource`, and `remove_prompt` methods on the server's [local provider](/servers/providers/local) accept an optional `version` parameter that controls what gets removed.
+
+```python
+# Remove ALL versions of a component
+mcp.local_provider.remove_tool("calculate")
+
+# Remove only a specific version
+mcp.local_provider.remove_tool("calculate", version="1.0")
+```
+
+When you remove a specific version, other versions remain registered. When you remove without specifying a version, all versions are removed.
+
+## Migration Workflow
+
+Versioning supports gradual migration when updating component behavior. You can deploy new versions alongside old ones, verify the new behavior works correctly, then clean up.
+
+When migrating an existing unversioned component to use versioning, start by assigning an initial version to your existing implementation. Then add the new version alongside it.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+@mcp.tool(version="1.0")
+def process_data(input: str) -> str:
+    """Original implementation, now versioned."""
+    return legacy_process(input)
+
+@mcp.tool(version="2.0")
+def process_data(input: str, options: dict | None = None) -> str:
+    """Updated implementation with new options parameter."""
+    return modern_process(input, options or {})
+```
+
+Clients automatically see version 2.0 (the highest). During the transition, your server code can still access the original implementation via `get_tool("process_data", version="1.0")`.
+
+Once the migration is complete, remove the old version.
+
+```python
+mcp.local_provider.remove_tool("process_data", version="1.0")
+```
diff --git a/docs/servers/visibility.mdx b/docs/servers/visibility.mdx
new file mode 100644
index 0000000..509bd70
--- /dev/null
+++ b/docs/servers/visibility.mdx
@@ -0,0 +1,452 @@
+---
+title: Component Visibility
+sidebarTitle: Visibility
+description: Control which components are available to clients
+icon: toggle-on
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+Components can be dynamically enabled or disabled at runtime. A disabled tool disappears from listings and cannot be called. This enables runtime access control, feature flags, and context-aware component exposure.
+
+## Component Visibility
+
+Every FastMCP server provides `enable()` and `disable()` methods for controlling component availability.
+
+### Disabling Components
+
+The `disable()` method marks components as disabled. Disabled components are filtered out from all client queries.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("Server")
+
+@mcp.tool(tags={"admin"})
+def delete_everything() -> str:
+    """Delete all data."""
+    return "Deleted"
+
+@mcp.tool(tags={"admin"})
+def reset_system() -> str:
+    """Reset the system."""
+    return "Reset"
+
+@mcp.tool
+def get_status() -> str:
+    """Get system status."""
+    return "OK"
+
+# Disable admin tools
+mcp.disable(tags={"admin"})
+
+# Clients only see: get_status
+```
+
+### Enabling Components
+
+The `enable()` method re-enables previously disabled components.
+
+```python
+# Re-enable admin tools
+mcp.enable(tags={"admin"})
+
+# Clients now see all three tools
+```
+
+## Keys and Tags
+
+Visibility filtering works with two identifiers: keys (for specific components) and tags (for groups).
+
+### Component Keys
+
+Every component has a unique key in the format `{type}:{identifier}`.
+
+| Component | Key Format | Example |
+|-----------|------------|---------|
+| Tool | `tool:{name}` | `tool:delete_everything` |
+| Resource | `resource:{uri}` | `resource:data://config` |
+| Template | `template:{uri}` | `template:file://{path}` |
+| Prompt | `prompt:{name}` | `prompt:analyze` |
+
+Use keys to target specific components.
+
+```python
+# Disable a specific tool
+mcp.disable(keys={"tool:delete_everything"})
+
+# Disable multiple specific components
+mcp.disable(keys={"tool:reset_system", "resource:data://secrets"})
+```
+
+### Tags
+
+Tags group components for bulk operations. Define tags when creating components, then filter by them.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("Server")
+
+@mcp.tool(tags={"public", "read"})
+def get_data() -> str:
+    return "data"
+
+@mcp.tool(tags={"admin", "write"})
+def set_data(value: str) -> str:
+    return f"Set: {value}"
+
+@mcp.tool(tags={"admin", "dangerous"})
+def delete_data() -> str:
+    return "Deleted"
+
+# Disable all admin tools
+mcp.disable(tags={"admin"})
+
+# Disable all dangerous tools (some overlap with admin)
+mcp.disable(tags={"dangerous"})
+```
+
+A component is disabled if it has **any** of the disabled tags. The component doesn't need all the tags; one match is enough.
+
+### Combining Keys and Tags
+
+You can specify both keys and tags in a single call. The filters combine additively.
+
+```python
+# Disable specific tools AND all dangerous-tagged components
+mcp.disable(keys={"tool:debug_info"}, tags={"dangerous"})
+```
+
+## Allowlist Mode
+
+By default, visibility filtering uses blocklist mode: everything is enabled unless explicitly disabled. The `only=True` parameter switches to allowlist mode, where **only** specified components are enabled.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("Server")
+
+@mcp.tool(tags={"safe"})
+def read_only_operation() -> str:
+    return "Read"
+
+@mcp.tool(tags={"safe"})
+def list_items() -> list[str]:
+    return ["a", "b", "c"]
+
+@mcp.tool(tags={"dangerous"})
+def delete_all() -> str:
+    return "Deleted"
+
+@mcp.tool
+def untagged_tool() -> str:
+    return "Untagged"
+
+# Only enable safe tools - everything else is disabled
+mcp.enable(tags={"safe"}, only=True)
+
+# Clients see: read_only_operation, list_items
+# Disabled: delete_all, untagged_tool
+```
+
+Allowlist mode is useful for restrictive environments where you want to explicitly opt-in components rather than opt-out.
+
+### Allowlist Behavior
+
+When you call `enable(only=True)`:
+
+1. Default visibility state switches to "disabled"
+2. Previous allowlists are cleared
+3. Only specified keys/tags become enabled
+
+```python
+# Start fresh - only enable these specific tools
+mcp.enable(keys={"tool:safe_read", "tool:safe_write"}, only=True)
+
+# Later, switch to a different allowlist
+mcp.enable(tags={"production"}, only=True)
+```
+
+### Ordering and Overrides
+
+Later `enable()` and `disable()` calls override earlier ones. This lets you create broad rules with specific exceptions.
+
+```python
+mcp.enable(tags={"api"}, only=True)  # Allow all api-tagged
+mcp.disable(keys={"tool:api_admin"})  # Later disable overrides for this tool
+
+# api_admin is disabled because the later disable() overrides the allowlist
+```
+
+You can always re-enable something that was disabled by adding another `enable()` call after it.
+
+## Server vs Provider
+
+Visibility state operates at two levels: the server and individual providers.
+
+### Server-Level
+
+Server-level visibility state applies to all components from all providers. When you call `mcp.enable()` or `mcp.disable()`, you're filtering the final view that clients see.
+
+```python
+from fastmcp import FastMCP
+
+main = FastMCP("Main")
+main.mount(sub_server, namespace="api")
+
+@main.tool(tags={"internal"})
+def local_debug() -> str:
+    return "Debug"
+
+# Disable internal tools from ALL sources
+main.disable(tags={"internal"})
+```
+
+### Provider-Level
+
+Each provider can add its own visibility transforms. These run before server-level transforms, so the server can override provider-level disables.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers import LocalProvider
+
+# Create provider with visibility control
+admin_tools = LocalProvider()
+
+@admin_tools.tool(tags={"admin"})
+def admin_action() -> str:
+    return "Admin"
+
+@admin_tools.tool
+def regular_action() -> str:
+    return "Regular"
+
+# Disable at provider level
+admin_tools.disable(tags={"admin"})
+
+# Server can override if needed
+mcp = FastMCP("Server", providers=[admin_tools])
+mcp.enable(names={"admin_action"})  # Re-enables despite provider disable
+```
+
+Provider-level transforms are useful for setting default visibility that servers can selectively override.
+
+### Layered Transforms
+
+Provider transforms run first, then server transforms. Later transforms override earlier ones, so the server has final say.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers import LocalProvider
+
+provider = LocalProvider()
+
+@provider.tool(tags={"feature", "beta"})
+def new_feature() -> str:
+    return "New"
+
+# Provider enables feature-tagged
+provider.enable(tags={"feature"}, only=True)
+
+# Server disables beta-tagged (runs after provider)
+mcp = FastMCP("Server", providers=[provider])
+mcp.disable(tags={"beta"})
+
+# new_feature is disabled (server's later disable overrides provider's enable)
+```
+
+## Per-Session Visibility
+
+Server-level visibility changes affect all connected clients simultaneously. When you need different clients to see different components, use per-session visibility instead.
+
+Session visibility lets individual sessions customize their view of available components. When a tool calls `ctx.enable_components()` or `ctx.disable_components()`, those rules apply only to the current session. Other sessions continue to see the global defaults. This enables patterns like progressive disclosure, role-based access, and on-demand feature activation.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.context import Context
+
+mcp = FastMCP("Session-Aware Server")
+
+@mcp.tool(tags={"premium"})
+def premium_analysis(data: str) -> str:
+    """Advanced analysis available to premium users."""
+    return f"Premium analysis of: {data}"
+
+@mcp.tool
+async def unlock_premium(ctx: Context) -> str:
+    """Unlock premium features for this session."""
+    await ctx.enable_components(tags={"premium"})
+    return "Premium features unlocked"
+
+@mcp.tool
+async def reset_features(ctx: Context) -> str:
+    """Reset to default feature set."""
+    await ctx.reset_visibility()
+    return "Features reset to defaults"
+
+# Premium tools are disabled globally by default
+mcp.disable(tags={"premium"})
+```
+
+All sessions start with `premium_analysis` hidden. When a session calls `unlock_premium`, that session gains access to premium tools while other sessions remain unaffected. Calling `reset_features` returns the session to the global defaults.
+
+### How Session Rules Work
+
+Session rules override global transforms. When listing components, FastMCP first applies global enable/disable rules, then applies session-specific rules on top. Rules within a session accumulate, and later rules override earlier ones for the same component.
+
+```python
+@mcp.tool
+async def customize_session(ctx: Context) -> str:
+    # Enable finance tools for this session
+    await ctx.enable_components(tags={"finance"})
+
+    # Also enable admin tools
+    await ctx.enable_components(tags={"admin"})
+
+    # Later: disable a specific admin tool
+    await ctx.disable_components(names={"dangerous_admin_tool"})
+
+    return "Session customized"
+```
+
+Each call adds a rule to the session. The `dangerous_admin_tool` ends up disabled because its disable rule was added after the admin enable rule.
+
+### Filter Criteria
+
+The session visibility methods accept the same filter criteria as `server.enable()` and `server.disable()`:
+
+| Parameter | Description |
+|-----------|-------------|
+| `names` | Component names or URIs to match |
+| `keys` | Component keys (e.g., `{"tool:my_tool"}`) |
+| `tags` | Tags to match (component must have at least one) |
+| `version` | Version specification to match |
+| `components` | Component types (`{"tool"}`, `{"resource"}`, `{"prompt"}`, `{"template"}`) |
+| `match_all` | If `True`, matches all components regardless of other criteria |
+
+```python
+from fastmcp.utilities.versions import VersionSpec
+
+@mcp.tool
+async def enable_recent_tools(ctx: Context) -> str:
+    """Enable only tools from version 2.0.0 or later."""
+    await ctx.enable_components(
+        version=VersionSpec(gte="2.0.0"),
+        components={"tool"}
+    )
+    return "Recent tools enabled"
+```
+
+### Automatic Notifications
+
+When session visibility changes, FastMCP automatically sends notifications to that session. Clients receive `ToolListChangedNotification`, `ResourceListChangedNotification`, and `PromptListChangedNotification` so they can refresh their component lists. These notifications go only to the affected session.
+
+When you specify the `components` parameter, FastMCP optimizes by sending only the relevant notifications:
+
+```python
+# Only sends ToolListChangedNotification
+await ctx.enable_components(tags={"finance"}, components={"tool"})
+
+# Sends all three notifications (no components filter)
+await ctx.enable_components(tags={"finance"})
+```
+
+### Namespace Activation Pattern
+
+A common pattern organizes tools into namespaces using tag prefixes, disables them globally, then provides activation tools that unlock namespaces on demand:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.context import Context
+
+server = FastMCP("Multi-Domain Assistant")
+
+# Finance namespace
+@server.tool(tags={"namespace:finance"})
+def analyze_portfolio(symbols: list[str]) -> str:
+    return f"Analysis for: {', '.join(symbols)}"
+
+@server.tool(tags={"namespace:finance"})
+def get_market_data(symbol: str) -> dict:
+    return {"symbol": symbol, "price": 150.25}
+
+# Admin namespace
+@server.tool(tags={"namespace:admin"})
+def list_users() -> list[str]:
+    return ["alice", "bob", "charlie"]
+
+# Activation tools - always visible
+@server.tool
+async def activate_finance(ctx: Context) -> str:
+    await ctx.enable_components(tags={"namespace:finance"})
+    return "Finance tools activated"
+
+@server.tool
+async def activate_admin(ctx: Context) -> str:
+    await ctx.enable_components(tags={"namespace:admin"})
+    return "Admin tools activated"
+
+@server.tool
+async def deactivate_all(ctx: Context) -> str:
+    await ctx.reset_visibility()
+    return "All namespaces deactivated"
+
+# Disable namespace tools globally
+server.disable(tags={"namespace:finance", "namespace:admin"})
+```
+
+Sessions start seeing only the activation tools. Calling `activate_finance` reveals finance tools for that session only. Multiple namespaces can be activated independently, and `deactivate_all` returns to the initial state.
+
+### Method Reference
+
+- **`await ctx.enable_components(...) -> None`**: Enable matching components for this session
+- **`await ctx.disable_components(...) -> None`**: Disable matching components for this session
+- **`await ctx.reset_visibility() -> None`**: Clear all session rules, returning to global defaults
+
+## Client Notifications
+
+When visibility state changes, FastMCP automatically notifies connected clients. Clients supporting the MCP notification protocol receive `list_changed` events and can refresh their component lists.
+
+This happens automatically. You don't need to trigger notifications manually.
+
+```python
+# This automatically notifies clients
+mcp.disable(tags={"maintenance"})
+
+# Clients receive: tools/list_changed, resources/list_changed, etc.
+```
+
+## Filtering Logic
+
+Understanding the filtering logic helps when debugging visibility state issues.
+
+The `is_enabled()` function checks a component's internal metadata:
+
+1. If the component has `meta.fastmcp._internal.visibility = False`, it's disabled
+2. If the component has `meta.fastmcp._internal.visibility = True`, it's enabled
+3. If no visibility state is set, the component is enabled by default
+
+When multiple `enable()` and `disable()` calls are made, transforms are applied in order. **Later transforms override earlier ones**, so the last matching transform wins.
+
+## The Visibility Transform
+
+Under the hood, `enable()` and `disable()` add `Visibility` transforms to the server or provider. The `Visibility` transform marks components with visibility metadata, and the server applies the final filter after all provider and server transforms complete.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.transforms import Visibility
+
+mcp = FastMCP("Server")
+
+# Using the convenience method (recommended)
+mcp.disable(names={"secret_tool"})
+
+# Equivalent to:
+mcp.add_transform(Visibility(False, names={"secret_tool"}))
+```
+
+Server-level transforms override provider-level transforms. If a component is disabled at the provider level but enabled at the server level, the server-level `enable()` can re-enable it.
diff --git a/docs/snippets/local-focus.mdx b/docs/snippets/local-focus.mdx
new file mode 100644
index 0000000..4da6ac7
--- /dev/null
+++ b/docs/snippets/local-focus.mdx
@@ -0,0 +1,7 @@
+export const LocalFocusTip = () => {
+    return (
+        <Tip>
+            <strong>This integration focuses on running local FastMCP server files with STDIO transport.</strong> For remote servers running with HTTP or SSE transport, use your client's native configuration - FastMCP's integrations focus on simplifying the complex local setup with dependencies and <code>uv</code> commands.
+        </Tip>
+    );
+};
\ No newline at end of file
diff --git a/docs/snippets/prefab-demo-frame.mdx b/docs/snippets/prefab-demo-frame.mdx
new file mode 100644
index 0000000..c7d639e
--- /dev/null
+++ b/docs/snippets/prefab-demo-frame.mdx
@@ -0,0 +1,66 @@
+export const PrefabDemoFrame = ({ demo, height, title }) => {
+  const [blobUrl, setBlobUrl] = React.useState(null);
+
+  React.useEffect(() => {
+    let active = true;
+    let objectUrl = null;
+    let payloadsPromise = window.__FASTMCP_PREFAB_DEMOS_PROMISE__;
+
+    if (window.__FASTMCP_PREFAB_DEMOS__) {
+      payloadsPromise = Promise.resolve(window.__FASTMCP_PREFAB_DEMOS__);
+    } else if (!payloadsPromise) {
+      payloadsPromise = new Promise((resolve, reject) => {
+        const script = document.createElement("script");
+        script.src = "/prefab-demo-payloads.js";
+        script.onload = () => resolve(window.__FASTMCP_PREFAB_DEMOS__);
+        script.onerror = reject;
+        document.head.appendChild(script);
+      });
+      window.__FASTMCP_PREFAB_DEMOS_PROMISE__ = payloadsPromise;
+    }
+
+    payloadsPromise
+      .then((payloads) => {
+        const html = payloads[demo];
+        if (!html) {
+          throw new Error(`Unknown Prefab demo: ${demo}`);
+        }
+        objectUrl = URL.createObjectURL(
+          new Blob([html], { type: "text/html" }),
+        );
+        if (active) {
+          setBlobUrl(objectUrl);
+        } else {
+          URL.revokeObjectURL(objectUrl);
+        }
+      });
+
+    return () => {
+      active = false;
+      if (objectUrl) {
+        URL.revokeObjectURL(objectUrl);
+      }
+    };
+  }, [demo]);
+
+  if (!blobUrl) {
+    return <div style={{ width: "100%", height, borderRadius: "8px" }} />;
+  }
+
+  return (
+    <iframe
+      src={blobUrl}
+      title={title}
+      style={{
+        width: "100%",
+        height,
+        border: "none",
+        overflow: "hidden",
+        borderRadius: "8px",
+      }}
+      frameBorder="0"
+      scrolling="no"
+      sandbox="allow-scripts allow-same-origin"
+    />
+  );
+};
diff --git a/docs/snippets/prefab-pin-warning.mdx b/docs/snippets/prefab-pin-warning.mdx
new file mode 100644
index 0000000..098181f
--- /dev/null
+++ b/docs/snippets/prefab-pin-warning.mdx
@@ -0,0 +1,3 @@
+<Tip>
+[Prefab](https://prefab.prefect.io) is under active development with frequent breaking changes. FastMCP sets a minimum `prefab-ui` version but does not pin an upper bound — **pin `prefab-ui` to a specific version in your own dependencies** before deploying.
+</Tip>
diff --git a/docs/snippets/version-badge.mdx b/docs/snippets/version-badge.mdx
new file mode 100644
index 0000000..3442524
--- /dev/null
+++ b/docs/snippets/version-badge.mdx
@@ -0,0 +1,7 @@
+export const VersionBadge = ({ version }) => {
+    return (
+        <Badge stroke size="lg" icon='gift' iconType='regular' className="version-badge">
+            New in version <code>{version}</code>
+        </Badge>
+    );
+};
\ No newline at end of file
diff --git a/docs/snippets/youtube-embed.mdx b/docs/snippets/youtube-embed.mdx
new file mode 100644
index 0000000..1c36e6c
--- /dev/null
+++ b/docs/snippets/youtube-embed.mdx
@@ -0,0 +1,12 @@
+export const YouTubeEmbed = ({ videoId, title }) => {
+    return (
+        <iframe
+            className="w-full aspect-video rounded-md"
+            src={`https://www.youtube.com/embed/${videoId}`}
+            title={title}
+            frameBorder="0"
+            allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+            allowFullScreen
+        />
+    );
+};
\ No newline at end of file
diff --git a/docs/tutorials/create-mcp-server.mdx b/docs/tutorials/create-mcp-server.mdx
new file mode 100644
index 0000000..de10007
--- /dev/null
+++ b/docs/tutorials/create-mcp-server.mdx
@@ -0,0 +1,198 @@
+---
+title: "How to Create an MCP Server in Python"
+sidebarTitle: "Creating an MCP Server"
+description: "A step-by-step guide to building a Model Context Protocol (MCP) server using Python and FastMCP, from basic tools to dynamic resources."
+icon: server
+---
+
+So you want to build a Model Context Protocol (MCP) server in Python. The goal is to create a service that can provide tools and data to AI models like Claude, Gemini, or others that support the protocol. While the [MCP specification](https://modelcontextprotocol.io/specification/) is powerful, implementing it from scratch involves a lot of boilerplate: handling JSON-RPC, managing session state, and correctly formatting requests and responses.
+
+This is where **FastMCP** comes in. It's a high-level framework that handles all the protocol complexities for you, letting you focus on what matters: writing the Python functions that power your server.
+
+This guide will walk you through creating a fully-featured MCP server from scratch using FastMCP.
+
+<Tip>
+Every code block in this tutorial is a complete, runnable example. You can copy and paste it into a file and run it, or paste it directly into a Python REPL like IPython to try it out.
+</Tip>
+
+### Prerequisites
+
+Make sure you have FastMCP installed. If not, follow the [installation guide](/getting-started/installation).
+
+```bash
+pip install fastmcp
+```
+
+
+## Step 1: Create the Basic Server
+
+Every FastMCP application starts with an instance of the `FastMCP` class. This object acts as the container for all your tools and resources.
+
+Create a new file called `my_mcp_server.py`:
+
+```python my_mcp_server.py
+from fastmcp import FastMCP
+
+# Create a server instance with a descriptive name
+mcp = FastMCP(name="My First MCP Server")
+```
+
+That's it! You have a valid (though empty) MCP server. Now, let's add some functionality.
+
+## Step 2: Add a Tool
+
+Tools are functions that an LLM can execute. Let's create a simple tool that adds two numbers.
+
+To do this, simply write a standard Python function and decorate it with `@mcp.tool`.
+
+```python my_mcp_server.py {5-8}
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="My First MCP Server")
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Adds two integer numbers together."""
+    return a + b
+```
+
+FastMCP automatically handles the rest:
+- **Tool Name:** It uses the function name (`add`) as the tool's name.
+- **Description:** It uses the function's docstring as the tool's description for the LLM.
+- **Schema:** It inspects the type hints (`a: int`, `b: int`) to generate a JSON schema for the inputs.
+
+This is the core philosophy of FastMCP: **write Python, not protocol boilerplate.**
+
+## Step 3: Expose Data with Resources
+
+Resources provide read-only data to the LLM. You can define a resource by decorating a function with `@mcp.resource`, providing a unique URI.
+
+Let's expose a simple configuration dictionary as a resource.
+
+```python my_mcp_server.py {10-13}
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="My First MCP Server")
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Adds two integer numbers together."""
+    return a + b
+
+@mcp.resource("resource://config")
+def get_config() -> dict:
+    """Provides the application's configuration."""
+    return {"version": "1.0", "author": "MyTeam"}
+```
+
+When a client requests the URI `resource://config`, FastMCP will execute the `get_config` function and return its output (serialized as JSON) to the client. The function is only called when the resource is requested, enabling lazy-loading of data.
+
+## Step 4: Generate Dynamic Content with Resource Templates
+
+Sometimes, you need to generate resources based on parameters. This is what **Resource Templates** are for. You define them using the same `@mcp.resource` decorator but with placeholders in the URI.
+
+Let's create a template that provides a personalized greeting.
+
+```python my_mcp_server.py {15-17}
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="My First MCP Server")
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Adds two integer numbers together."""
+    return a + b
+
+@mcp.resource("resource://config")
+def get_config() -> dict:
+    """Provides the application's configuration."""
+    return {"version": "1.0", "author": "MyTeam"}
+
+@mcp.resource("greetings://{name}")
+def personalized_greeting(name: str) -> str:
+    """Generates a personalized greeting for the given name."""
+    return f"Hello, {name}! Welcome to the MCP server."
+```
+
+Now, clients can request dynamic URIs:
+- `greetings://Ford` will call `personalized_greeting(name="Ford")`.
+- `greetings://Marvin` will call `personalized_greeting(name="Marvin")`.
+
+FastMCP automatically maps the `{name}` placeholder in the URI to the `name` parameter in your function.
+
+## Step 5: Run the Server
+
+To make your server executable, add a `__main__` block to your script that calls `mcp.run()`.
+
+```python my_mcp_server.py {19-20}
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="My First MCP Server")
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Adds two integer numbers together."""
+    return a + b
+
+@mcp.resource("resource://config")
+def get_config() -> dict:
+    """Provides the application's configuration."""
+    return {"version": "1.0", "author": "MyTeam"}
+
+@mcp.resource("greetings://{name}")
+def personalized_greeting(name: str) -> str:
+    """Generates a personalized greeting for the given name."""
+    return f"Hello, {name}! Welcome to the MCP server."
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+Now you can run your server from the command line:
+```bash
+python my_mcp_server.py
+```
+This starts the server using the default **STDIO transport**, which is how clients like Claude Desktop communicate with local servers. To learn about other transports, like HTTP, see the [Running Your Server](/deployment/running-server) guide.
+
+## The Complete Server
+
+Here is the full code for `my_mcp_server.py` (click to expand):
+
+```python my_mcp_server.py [expandable]
+from fastmcp import FastMCP
+
+# 1. Create the server
+mcp = FastMCP(name="My First MCP Server")
+
+# 2. Add a tool
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Adds two integer numbers together."""
+    return a + b
+
+# 3. Add a static resource
+@mcp.resource("resource://config")
+def get_config() -> dict:
+    """Provides the application's configuration."""
+    return {"version": "1.0", "author": "MyTeam"}
+
+# 4. Add a resource template for dynamic content
+@mcp.resource("greetings://{name}")
+def personalized_greeting(name: str) -> str:
+    """Generates a personalized greeting for the given name."""
+    return f"Hello, {name}! Welcome to the MCP server."
+
+# 5. Make the server runnable
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Next Steps
+
+You've successfully built an MCP server! From here, you can explore more advanced topics:
+
+-   [**Tools in Depth**](/servers/tools): Learn about asynchronous tools, error handling, and custom return types.
+-   [**Resources & Templates**](/servers/resources): Discover different resource types, including files and HTTP endpoints.
+-   [**Prompts**](/servers/prompts): Create reusable prompt templates for your LLM.
+-   [**Running Your Server**](/deployment/running-server): Deploy your server with different transports like HTTP.
+
diff --git a/docs/tutorials/mcp.mdx b/docs/tutorials/mcp.mdx
new file mode 100644
index 0000000..fd3995f
--- /dev/null
+++ b/docs/tutorials/mcp.mdx
@@ -0,0 +1,120 @@
+---
+title: "What is the Model Context Protocol (MCP)?"
+sidebarTitle: "What is MCP?"
+description: "An introduction to the core concepts of the Model Context Protocol (MCP), explaining what it is, why it's useful, and how it works."
+icon: "diagram-project"
+---
+
+The Model Context Protocol (MCP) is an open standard designed to solve a fundamental problem in AI development: how can Large Language Models (LLMs) reliably and securely interact with external tools, data, and services?
+
+It's the **bridge between the probabilistic, non-deterministic world of AI and the deterministic, reliable world of your code and data.**
+
+While you could build a custom REST API for your LLM, MCP provides a specialized, standardized "port" for AI-native communication. Think of it as **USB-C for AI**: a single, well-defined interface for connecting any compliant LLM to any compliant tool or data source.
+
+This guide provides a high-level overview of the protocol itself. We'll use **FastMCP**, the leading Python framework for MCP, to illustrate the concepts with simple code examples.
+
+## Why Do We Need a Protocol?
+
+With countless APIs already in existence, the most common question is: "Why do we need another one?"
+
+The answer lies in **standardization**. The AI ecosystem is fragmented. Every model provider has its own way of defining and calling tools. MCP's goal is to create a common language that offers several key advantages:
+
+1.  **Interoperability:** Build one MCP server, and it can be used by any MCP-compliant client (Claude, Gemini, OpenAI, custom agents, etc.) without custom integration code. This is the protocol's most important promise.
+2.  **Discoverability:** Clients can dynamically ask a server what it's capable of at runtime. They receive a structured, machine-readable "menu" of tools and resources.
+3.  **Security & Safety:** MCP provides a clear, sandboxed boundary. An LLM can't execute arbitrary code on your server; it can only *request* to run the specific, typed, and validated functions you explicitly expose.
+4.  **Composability:** You can build small, specialized MCP servers and combine them to create powerful, complex applications.
+
+## Core MCP Components 
+
+An MCP server exposes its capabilities through three primary components: Tools, Resources, and Prompts.
+
+### Tools: Executable Actions
+
+Tools are functions that the LLM can ask the server to execute. They are the action-oriented part of MCP.
+
+In the spirit of a REST API, you can think of **Tools as being like `POST` requests.** They are used to *perform an action*, *change state*, or *trigger a side effect*, like sending an email, adding a user to a database, or making a calculation.
+
+With FastMCP, creating a tool is as simple as decorating a Python function.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+# This function is now an MCP tool named "get_weather"
+@mcp.tool
+def get_weather(city: str) -> dict:
+    """Gets the current weather for a specific city."""
+    # In a real app, this would call a weather API
+    return {"city": city, "temperature": "72F", "forecast": "Sunny"}
+```
+
+[**Learn more about Tools →**](/servers/tools)
+
+### Resources: Read-Only Data
+
+Resources are data sources that the LLM can read. They are used to load information into the LLM's context, providing it with knowledge it doesn't have from its training data.
+
+Following the REST API analogy, **Resources are like `GET` requests.** Their purpose is to *retrieve information* idempotently, ideally without causing side effects. A resource can be anything from a static text file to a dynamic piece of data from a database. Each resource is identified by a unique URI.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+# This function provides a resource at the URI "system://status"
+@mcp.resource("system://status")
+def get_system_status() -> dict:
+    """Returns the current operational status of the service."""
+    return {"status": "all systems normal"}
+```
+
+#### Resource Templates
+
+You can also create **Resource Templates** for dynamic data. A client could request `users://42/profile` to get the profile for a specific user.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+# This template provides user data for any given user ID
+@mcp.resource("users://{user_id}/profile")
+def get_user_profile(user_id: str) -> dict:
+    """Returns the profile for a specific user."""
+    # Fetch user from a database...
+    return {"id": user_id, "name": "Zaphod Beeblebrox"}
+```
+
+[**Learn more about Resources & Templates →**](/servers/resources)
+
+### Prompts: Reusable Instructions
+
+Prompts are reusable, parameterized message templates. They provide a way to define consistent, structured instructions that a client can request to guide the LLM's behavior for a specific task.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+@mcp.prompt
+def summarize_text(text_to_summarize: str) -> str:
+    """Creates a prompt asking the LLM to summarize a piece of text."""
+    return f"""
+        Please provide a concise, one-paragraph summary of the following text:
+        
+        {text_to_summarize}
+        """
+```
+
+[**Learn more about Prompts →**](/servers/prompts)
+
+## Advanced Capabilities
+
+Beyond the core components, MCP also supports more advanced interaction patterns, such as a server requesting that the *client's* LLM generate a completion (known as **sampling**), or a server sending asynchronous **notifications** to a client. These features enable more complex, bidirectional workflows and are fully supported by FastMCP.
+
+## Next Steps
+
+Now that you understand the core concepts of the Model Context Protocol, you're ready to start building. The best place to begin is our step-by-step tutorial.
+
+[**Tutorial: How to Create an MCP Server in Python →**](/tutorials/create-mcp-server)
diff --git a/docs/tutorials/rest-api.mdx b/docs/tutorials/rest-api.mdx
new file mode 100644
index 0000000..90872c9
--- /dev/null
+++ b/docs/tutorials/rest-api.mdx
@@ -0,0 +1,203 @@
+---
+title: "How to Connect an LLM to a REST API"
+sidebarTitle: "Connect LLMs to REST APIs"
+description: "A step-by-step guide to making any REST API with an OpenAPI spec available to LLMs using FastMCP."
+icon: "plug"
+---
+
+You've built a powerful REST API, and now you want your LLM to be able to use it. Manually writing a wrapper function for every single endpoint is tedious, error-prone, and hard to maintain.
+
+This is where **FastMCP** shines. If your API has an OpenAPI (or Swagger) specification, FastMCP can automatically convert your entire API into a fully-featured MCP server, making every endpoint available as a secure, typed tool for your AI model.
+
+This guide will walk you through converting a public REST API into an MCP server in just a few lines of code.
+
+<Tip>
+Every code block in this tutorial is a complete, runnable example. You can copy and paste it into a file and run it, or paste it directly into a Python REPL like IPython to try it out.
+</Tip>
+
+### Prerequisites
+
+Make sure you have FastMCP installed. If not, follow the [installation guide](/getting-started/installation).
+
+```bash
+pip install fastmcp
+```
+
+## Step 1: Choose a Target API
+
+For this tutorial, we'll use the [JSONPlaceholder API](https://jsonplaceholder.typicode.com/), a free, fake online REST API for testing and prototyping. It's perfect because it's simple and has a public OpenAPI specification.
+
+-   **API Base URL:** `https://jsonplaceholder.typicode.com`
+-   **OpenAPI Spec URL:** We'll use a community-provided spec for it.
+
+## Step 2: Create the MCP Server
+
+Now for the magic. We'll use `FastMCP.from_openapi`. This method takes an `httpx.AsyncClient` configured for your API and its OpenAPI specification, and automatically converts **every endpoint** into a callable MCP `Tool`.
+
+<Tip>
+Learn more about working with OpenAPI specs in the [OpenAPI integration docs](/integrations/openapi).
+</Tip>
+
+<Note>
+For this tutorial, we'll use a simplified OpenAPI spec directly in the code. In a real project, you would typically load the spec from a URL or local file.
+</Note>
+
+Create a file named `api_server.py`:
+
+```python api_server.py {31-35}
+import httpx
+from fastmcp import FastMCP
+
+# Create an HTTP client for the target API
+client = httpx.AsyncClient(base_url="https://jsonplaceholder.typicode.com")
+
+# Define a simplified OpenAPI spec for JSONPlaceholder
+openapi_spec = {
+    "openapi": "3.0.0",
+    "info": {"title": "JSONPlaceholder API", "version": "1.0"},
+    "paths": {
+        "/users": {
+            "get": {
+                "summary": "Get all users",
+                "operationId": "get_users",
+                "responses": {"200": {"description": "A list of users."}}
+            }
+        },
+        "/users/{id}": {
+            "get": {
+                "summary": "Get a user by ID",
+                "operationId": "get_user_by_id",
+                "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}],
+                "responses": {"200": {"description": "A single user."}}
+            }
+        }
+    }
+}
+
+# Create the MCP server from the OpenAPI spec
+mcp = FastMCP.from_openapi(
+    openapi_spec=openapi_spec,
+    client=client,
+    name="JSONPlaceholder MCP Server"
+)
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+
+And that's it! With just a few lines of code, you've created an MCP server that exposes the entire JSONPlaceholder API as a collection of tools.
+
+## Step 3: Test the Generated Server
+
+Let's verify that our new MCP server works. We can use the `fastmcp.Client` to connect to it and inspect its tools.
+
+<Tip>
+Learn more about the FastMCP client in the [client docs](/clients/client).
+</Tip>
+
+Create a separate file, `api_client.py`:
+
+```python api_client.py {2, 6, 9, 16}
+import asyncio
+from fastmcp import Client
+
+async def main():
+    # Connect to the MCP server we just created
+    async with Client("http://127.0.0.1:8000/mcp") as client:
+        
+        # List the tools that were automatically generated
+        tools = await client.list_tools()
+        print("Generated Tools:")
+        for tool in tools:
+            print(f"- {tool.name}")
+            
+        # Call one of the generated tools
+        print("\n\nCalling tool 'get_user_by_id'...")
+        user = await client.call_tool("get_user_by_id", {"id": 1})
+        print(f"Result:\n{user.data}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+First, run your server:
+```bash
+python api_server.py
+```
+
+Then, in another terminal, run the client:
+```bash
+python api_client.py
+```
+
+You should see a list of generated tools (`get_users`, `get_user_by_id`) and the result of calling the `get_user_by_id` tool, which fetches data from the live JSONPlaceholder API.
+
+![](/assets/images/tutorial-rest-api-result.png)
+
+
+## Step 4: Customizing Route Maps
+
+By default, FastMCP converts every API endpoint into an MCP `Tool`. This ensures maximum compatibility with contemporary LLM clients, many of which **only support the `tools` part of the MCP specification.**
+
+However, for clients that support the full MCP spec, representing `GET` requests as `Resources` can be more semantically correct and efficient.
+
+FastMCP allows users to customize this behavior using the concept of "route maps". A `RouteMap` is a mapping of an API route to an MCP type. FastMCP checks each API route against your custom maps in order. If a route matches a map, it's converted to the specified `mcp_type`. Any route that doesn't match your custom maps will fall back to the default behavior (becoming a `Tool`).
+
+<Tip>
+Learn more about route maps in the [OpenAPI integration docs](/integrations/openapi#route-mapping).
+</Tip>
+
+Here’s how you can add custom route maps to turn `GET` requests into `Resources` and `ResourceTemplates` (if they have path parameters):
+
+```python api_server_with_resources.py {3, 37-42}
+import httpx
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi import RouteMap, MCPType
+
+
+# Create an HTTP client for the target API
+client = httpx.AsyncClient(base_url="https://jsonplaceholder.typicode.com")
+
+# Define a simplified OpenAPI spec for JSONPlaceholder
+openapi_spec = {
+    "openapi": "3.0.0",
+    "info": {"title": "JSONPlaceholder API", "version": "1.0"},
+    "paths": {
+        "/users": {
+            "get": {
+                "summary": "Get all users",
+                "operationId": "get_users",
+                "responses": {"200": {"description": "A list of users."}}
+            }
+        },
+        "/users/{id}": {
+            "get": {
+                "summary": "Get a user by ID",
+                "operationId": "get_user_by_id",
+                "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}],
+                "responses": {"200": {"description": "A single user."}}
+            }
+        }
+    }
+}
+
+# Create the MCP server with custom route mapping
+mcp = FastMCP.from_openapi(
+    openapi_spec=openapi_spec,
+    client=client,
+    name="JSONPlaceholder MCP Server",
+    route_maps=[
+        # Map GET requests with path parameters (e.g., /users/{id}) to ResourceTemplate
+        RouteMap(methods=["GET"], pattern=r".*\{.*\}.*", mcp_type=MCPType.RESOURCE_TEMPLATE),
+        # Map all other GET requests to Resource
+        RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE),
+    ]
+)
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+With this configuration:
+- `GET /users/{id}` becomes a `ResourceTemplate`.
+- `GET /users` becomes a `Resource`.
+- Any `POST`, `PUT`, etc. endpoints would still become `Tools` by default.
\ No newline at end of file
diff --git a/docs/unify-intent.js b/docs/unify-intent.js
new file mode 100644
index 0000000..b51e57b
--- /dev/null
+++ b/docs/unify-intent.js
@@ -0,0 +1,74 @@
+// Load Unify intent tag on selected pages
+(function () {
+  if (typeof window === "undefined") return;
+
+  function isTaggedPage() {
+    var path = window.location.pathname;
+    return (
+      path.includes("/servers/auth/") ||
+      path.includes("/clients/auth/") ||
+      path.includes("/deployment/running-server") ||
+      path.includes("/deployment/http") ||
+      path.includes("/deployment/prefect-horizon")
+    );
+  }
+
+  function loadUnify() {
+    var e = [
+      "identify",
+      "page",
+      "startAutoPage",
+      "stopAutoPage",
+      "startAutoIdentify",
+      "stopAutoIdentify",
+    ];
+    function t(o) {
+      return Object.assign(
+        [],
+        e.reduce(function (r, n) {
+          r[n] = function () {
+            return o.push([n, [].slice.call(arguments)]), o;
+          };
+          return r;
+        }, {}),
+      );
+    }
+    if (!window.unify) window.unify = t(window.unify);
+    if (!window.unifyBrowser) window.unifyBrowser = t(window.unifyBrowser);
+
+    var n = document.createElement("script");
+    n.async = true;
+    n.setAttribute(
+      "src",
+      "https://tag.unifyintent.com/v1/Rj9KrQqMhyYcU5qfJtVszE/script.js",
+    );
+    n.setAttribute(
+      "data-api-key",
+      "wk_SBvJ4jyD_wRgPAHCNJb89seVmREhcj2NspRpxAywi",
+    );
+    n.setAttribute("id", "unifytag");
+    (document.body || document.head).appendChild(n);
+  }
+
+  function update() {
+    if (isTaggedPage() && !document.getElementById("unifytag")) {
+      loadUnify();
+    } else if (!isTaggedPage() && document.getElementById("unifytag")) {
+      document.getElementById("unifytag").remove();
+    }
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", update);
+  } else {
+    update();
+  }
+
+  var lastUrl = location.href;
+  new MutationObserver(function () {
+    if (location.href !== lastUrl) {
+      lastUrl = location.href;
+      setTimeout(update, 100);
+    }
+  }).observe(document.body, { subtree: true, childList: true });
+})();
diff --git a/docs/updates.mdx b/docs/updates.mdx
new file mode 100644
index 0000000..0faf12d
--- /dev/null
+++ b/docs/updates.mdx
@@ -0,0 +1,743 @@
+---
+title: "FastMCP Updates"
+sidebarTitle: "Updates"
+icon: "sparkles"
+tag: NEW
+---
+
+<Update label="FastMCP 3.4.4" description="July 8, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.4.4: Host in Translation"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.4"
+cta="Read the release notes"
+>
+A compatibility patch for HTTP deployments affected by the 3.4.3 Host/Origin guard defaults. FastMCP 3.x now keeps strict Host and Origin validation available for explicit opt-in deployments without rejecting existing ASGI, serverless, and reverse-proxy traffic by default.
+
+🌐 **HTTP compatibility restored** — existing hosted deployments keep accepting their public Host headers unless strict host/origin protection is configured.
+
+🔐 **Guard remains available** — deployments that know their public host and browser origins can still enable strict validation with `host_origin_protection=True`, `allowed_hosts`, and `allowed_origins`.
+
+🤗 **Hugging Face auth** — new OAuth provider support covers public and private Hugging Face apps, with docs and examples for PKCE, Dynamic Client Registration, and CIMD.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.4.3" description="July 5, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.4.3: The Fast and the Secure-ious"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.3"
+cta="Read the release notes"
+>
+A month of SSRF and OAuth hardening lands in one patch. NAT64, 6to4, Teredo, and ISATAP transition addresses can no longer smuggle private IPv4 targets past the SSRF allow-list, Streamable HTTP validates Host and Origin before session handling to block DNS rebinding, and OAuth redirect validation rejects unsafe schemes and unregistered DCR redirect URIs.
+
+🛡️ **SSRF allow-list hardening** — every IPv6 transition form (NAT64, 6to4, Teredo, ISATAP) now unwraps to its embedded IPv4 target and gets checked against the same policy.
+
+🌐 **DNS rebinding protection** — Streamable HTTP validates `Host` and browser `Origin` before session handling, closing a path to localhost-bound unauthenticated servers.
+
+🔐 **Stricter OAuth redirects** — unsafe redirect schemes are rejected before registration, and DCR clients are bound to the redirect URIs they registered.
+
+🧵 **Reliability fixes** — proxy session teardown races, discriminator-tag handling in JSON schema conversion, and several smaller fixes across middleware and resource templates.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.4.2" description="June 6, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.4.2: Heads Up"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.2"
+cta="Read the release notes"
+>
+A compatibility patch. `JWTVerifier` now accepts JWTs carrying private, non-critical JWS header parameters (like Clerk's `cat`) instead of rejecting them before signature and claim validation, while unsupported critical headers are still rejected.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.4.1" description="June 5, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.4.1: Floor It"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.1"
+cta="Read the release notes"
+>
+A security patch. FastMCP now floors Starlette at `>=1.0.1`, so installs can no longer resolve to a version affected by CVE-2026-48710 — previously the dependency was only constrained transitively through `mcp`. OAuthProxy also logs refresh-token cache misses instead of failing silently.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.4.0" description="June 2, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.4.0: Remote Control"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.0"
+cta="Read the release notes"
+>
+The remote release. `fastmcp-remote` is a standalone bridge that connects stdio-only MCP hosts to servers hosted over HTTP, with OAuth enabled automatically for HTTPS. The proxy layer underneath it is hardened so bridges fail loudly on a missing or misconfigured upstream, and FastMCP-issued tokens can now outlive short-lived upstream tokens to survive long idle periods.
+
+🌉 **fastmcp-remote** — `uvx fastmcp-remote https://example.com/mcp` bridges a remote server back to a stdio-only host.
+
+🔌 **Bridges fail loudly** — proxies forward `initialize` upstream, so a missing backend or wrong URL fails the handshake instead of returning an empty-but-connected proxy.
+
+🔐 **Longer-lived tokens** — `fastmcp_access_token_expiry_seconds` decouples the client-facing token lifetime from a short upstream `expires_in`.
+
+⚠️ **Returnable tool errors** — `ToolResult(..., is_error=True)` hands back rich errors the model can act on instead of only raising.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.3.1" description="May 15, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.3.1: Loop There It Is"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.3.1"
+cta="Read the release notes"
+>
+Hotfix for the 3.3 packaging split: standalone component imports like `from fastmcp.tools import tool` no longer pull in the server stack or trip a circular import. Component-level auth and task primitives moved to lightweight utility modules, with the old import paths preserved as compatibility re-exports.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.3.0" description="May 15, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.3.0: Slim Reaper"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.3.0"
+cta="Read the release notes"
+>
+The `fastmcp-slim` release. A dependency-light distribution that ships FastMCP's client and transport layer without Starlette, Uvicorn, or the server stack — the import namespace is unchanged. It also closes out a backlog of OAuth proxy hardening, MCP-compliant OTEL instrumentation, and auth additions.
+
+🪶 **fastmcp-slim** — install the client without the server footprint for CI, agents, and library dependencies.
+
+🔐 **OAuth proxy hardening** — silent-consent AS-in-the-middle guard, dot-segment redirect rejection, and per-token response cache partitioning.
+
+🔑 **Auth additions** — `AzureB2CProvider` user flows and a public `update_scopes()` API on `OAuthProxy`.
+
+🧵 **Thread affinity** — `@mcp.tool(run_in_thread=False)` for tools bound to a specific thread.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.2.4" description="April 14, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.2.4: Patch Me If You Can"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.2.4"
+cta="Read the release notes"
+>
+A grab bag of fixes and hardening. Background tasks are now scoped to the authorization context instead of the MCP session — a breaking change for anyone relying on session-scoped semantics — and parameter descriptions are extracted from docstrings automatically.
+
+🔐 **Security** — `FileUpload` validates decoded base64 size, the proxy stops forwarding inbound headers to unrelated servers, and AuthKit binds token audience per RFC 8707.
+
+🔑 **Keycloak** — new OAuth provider for enterprise auth and local dev.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.2.3" description="April 9, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.2.3: Redis or Not"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.2.3"
+cta="Read the release notes"
+>
+Pins `fakeredis<2.35.0` in the `tasks` extra: a 2.35.0 rename broke pydocket's `memory://` backend and made `fastmcp[tasks]` installs fail at startup with an `ImportError`.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.2.2" description="April 9, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.2.2: Audience Appreciation"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.2.2"
+cta="Read the release notes"
+>
+Fixes the Azure audience regression from 3.2.1 — both the bare client ID GUID and a custom `identifier_uri` are now accepted as the token audience.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.2.1" description="April 8, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.2.1: Audience Participation"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.2.1"
+cta="Read the release notes"
+>
+A patch focused on auth-provider audience validation: Cognito validates on `client_id`, Azure honors `identifier_uri`, and consent cookies are LRU-capped to avoid header overflow. Also fixes OpenAPI 3.0 `nullable` fields leaking into tool input schemas and server-variable substitution in base URLs.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.2.0" description="March 30, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.2.0: Show Don't Tool"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.2.0"
+cta="Read the release notes"
+>
+The Apps release. Your tools can return interactive UIs — charts, dashboards, forms, maps — rendered right inside the conversation.
+
+🎨 **FastMCPApp** — separate the tools the LLM sees (`@app.ui()`) from the backend tools the UI calls (`@app.tool()`), built on Prefab.
+
+🧩 **Built-in providers** — FileUpload, Approval, Choice, FormInput, and GenerativeUI.
+
+🖥️ **Dev server** — `fastmcp dev apps` previews app tools in the browser with an MCP message inspector.
+
+🔒 **Security pass** — SSRF/path-traversal prevention, JWT algorithm restrictions, OAuth scope enforcement, and CSRF fixes.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.1.1" description="March 14, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.1.1: 'Tis But a Patch"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.1.1"
+cta="Read the release notes"
+>
+Pins `pydantic-monty<0.0.8` to fix a breaking change in Monty that affects code mode.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.1.0" description="March 3, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.1.0: Code to Joy"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.1.0"
+cta="Read the release notes"
+>
+The Code Mode release. Instead of loading the entire tool catalog into context, `CodeMode` gives LLMs meta-tools: search for relevant tools on demand, inspect their schemas, then write Python that chains `call_tool()` calls in a sandbox. Also ships search transforms, early Prefab Apps integration, `MultiAuth` for composing multiple token verification sources, and PropelAuth support.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.0.2" description="February 22, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.0.2: Threecovery Mode II"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.2"
+cta="Read the release notes"
+>
+Two community-contributed fixes: auth headers from MCP transport no longer leak through to downstream OpenAPI APIs, and background task workers now correctly receive the originating request ID. Plus a new docs example for context-aware tool factories.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.0.1" description="February 20, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.0.1: Three-covery Mode"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.1"
+cta="Read the release notes"
+>
+First patch after 3.0 — mostly smoothing out rough edges discovered in the wild. The big ones: middleware state that wasn't surviving the trip to tool handlers now does, `Tool.from_tool()` accepts callables again, OpenAPI schemas with circular references no longer crash discovery, and decorator overloads now return the correct types in function mode.
+
+🔐 **OIDC `verify_id_token`** — New option for providers that issue opaque access tokens but standard JWT id_tokens. Verifies identity via the id_token while using the access_token for upstream API calls.
+
+🐞 **11 bug fixes** — State serialization, future annotations with `Context`/`Depends`, OpenAI handler deprecation warnings, type checker compatibility, and more.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.0.0" description="February 18, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.0.0: Three at Last"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.0"
+cta="Read the release notes"
+img="assets/updates/release-3-0.png"
+>
+FastMCP 3.0 is stable. Two betas, two release candidates, 21 new contributors, and more than 100,000 pre-release installs later — the architecture held up, the upgrade path was smooth, and we're shipping it.
+
+The surface API is largely unchanged — `@mcp.tool()` still works exactly as before. What changed is everything underneath: a provider/transform architecture that makes FastMCP extensible, observable, and composable in ways v2 couldn't support.
+
+🔌 **Build servers from anything** — `FileSystemProvider`, `OpenAPIProvider`, `ProxyProvider`, `SkillsProvider`, and composable transforms that rename, namespace, filter, version, and secure components as they flow to clients.
+
+🔐 **Ship to production** — Component versioning, granular authorization with async auth checks, CIMD, Static Client Registration, Azure OBO, OpenTelemetry tracing, and background tasks with distributed Redis notification.
+
+💾 **Adapt per session** — Session state persists across requests, and `ctx.enable_components()` / `ctx.disable_components()` let servers adapt dynamically per client.
+
+⚡ **Develop faster** — `--reload`, standalone decorators, automatic threadpool dispatch, tool timeouts, pagination, and concurrent tool execution.
+
+🖥️ **CLI** — `fastmcp list`, `fastmcp call`, `fastmcp discover`, `fastmcp generate-cli`, and `fastmcp install` for Claude Desktop, Cursor, and Goose.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.0.0rc1" description="February 12, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.0.0rc1: RC-ing is Believing"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.0rc1"
+cta="Read the release notes"
+>
+FastMCP 3 RC1 means we believe the API is stable. Beta 2 drew a wave of real-world adoption — production deployments, migration reports, integration testing — and the feedback overwhelmingly confirmed that the architecture works. This release closes gaps that surfaced under load: auth flows that needed to be async, background tasks that needed reliable notification delivery, and APIs still carrying beta-era naming. If nothing unexpected surfaces, this is what 3.0.0 looks like.
+
+🚨 **Breaking Changes** — The `ui=` parameter is now `app=` with a unified `AppConfig` class, and 16 `FastMCP()` constructor kwargs have been removed after months of deprecation warnings.
+
+🔐 **Auth Improvements** — Async `auth=` checks, Static Client Registration for servers without DCR, and declarative Azure OBO flows via dependency injection.
+
+⚡ **Concurrent Sampling** — `context.sample()` can now execute multiple tool calls in parallel with `tool_concurrency=0`.
+
+📡 **Background Task Notifications** — A distributed Redis queue replaces polling for progress updates and elicitation relay.
+
+✅ **OpenAPI Output Validation** — `validate_output=False` disables strict schema checking for imperfect backend APIs.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.0.0b2" description="February 7, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.0.0b2: 2 Fast 2 Beta"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.0b2"
+cta="Read the release notes"
+>
+Beta 2 reflects the huge number of people that kicked the tires on Beta 1. Seven new contributors landed changes, and early migration reports went smoother than expected. Most of Beta 2 is refinement — fixing what people found, filling gaps from real usage, hardening edges — but a few new features landed along the way.
+
+🖥️ **Client CLI** — `fastmcp list`, `fastmcp call`, `fastmcp discover`, and `fastmcp generate-cli` turn any MCP server into something you can poke at from a terminal.
+
+🔐 **CIMD** (Client ID Metadata Documents) adds an alternative to Dynamic Client Registration for OAuth.
+
+📱 **MCP Apps** — Spec-level compliance for the MCP Apps extension with `ui://` resource scheme and typed UI metadata.
+
+⏳ **Background Task Context** — `Context` now works transparently in Docket workers with Redis-based coordination.
+
+🛡️ **ResponseLimitingMiddleware** caps tool response sizes with UTF-8-safe truncation.
+
+🪿 **Goose Integration** — `fastmcp install goose` for one-command server installation into Goose.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.0.0b1" description="January 20, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP 3.0.0b1: This Beta Work"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.0b1"
+cta="Read the release notes"
+>
+FastMCP 3.0 rebuilds the framework around three primitives: components, providers, and transforms. Providers source components dynamically—from decorators, filesystems, OpenAPI specs, remote servers, or anywhere else. Transforms modify components as they flow to clients. The features that required specialized subsystems in v2 now compose naturally from these building blocks.
+
+🔌 **Provider Architecture** unifies how components are sourced with `FileSystemProvider`, `SkillsProvider`, `OpenAPIProvider`, and `ProxyProvider`.
+
+🔄 **Transforms** add middleware for components—namespace, rename, filter by version, control visibility.
+
+📋 **Component Versioning** lets you register multiple versions of the same tool with automatic highest-version selection.
+
+💾 **Session-Scoped State** persists across requests, with per-session visibility control.
+
+⚡ **DX Improvements** include `--reload` for development, automatic threadpool dispatch, tool timeouts, pagination, and OpenTelemetry tracing.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.14.7" description="April 13, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP 2.14.7: Fake It Till You Break It"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.7"
+cta="Read the release notes"
+>
+A 2.x backport of the fakeredis pin: fakeredis 2.35.0 renamed a connection class that pydocket's `memory://` backend relied on, crashing `fastmcp[tasks]` installs at startup. Caps `fakeredis<2.35.0` on the 2.x line.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.14.6" description="March 27, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP 2.14.6: $Ref Dead Redemption"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.6"
+cta="Read the release notes"
+>
+v2.14.4 backported `dereference_refs()` but never wired it into the tool schema pipeline — `$ref` and `$defs` were still sent to MCP clients. Now fixed: schemas are fully inlined before reaching clients.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.14.5" description="February 3, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP 2.14.5: Sealed Docket"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.5"
+cta="Read the release notes"
+>
+Fixes a memory leak in the memory:// docket broker where cancelled tasks accumulated instead of being cleaned up. Bumps pydocket to ≥0.17.2.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.14.4" description="January 22, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP 2.14.4: Package Deal"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.4"
+cta="Read the release notes"
+>
+Fixes a fresh install bug where the packaging library was missing as a direct dependency, plus backports $ref dereferencing in tool schemas and a task capabilities location fix.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.14.3" description="January 12, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP 2.14.3: Time After Timeout"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.3"
+cta="Read the release notes"
+>
+Sometimes five seconds just isn't enough. This release fixes an HTTP transport bug that was cutting connections short, along with OAuth and Redis fixes, better ASGI support, and CLI update notifications so you never miss a beat.
+
+⏱️ **HTTP transport timeout fix** restores MCP's 30-second default connect timeout, which was incorrectly defaulting to 5 seconds.
+
+🔧 **Infrastructure fixes** including OAuth token storage TTL, Redis key prefixing for ACL isolation, and ContextVar propagation for ASGI-mounted servers with background tasks.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.14.2" description="December 31, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.14.2: Port Authority"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.2"
+cta="Read the release notes"
+>
+A wave of community contributions arrives safely in the 2.x line. Important backports from 3.0 improve OpenAPI 3.1 compatibility, MCP spec compliance for output schemas and elicitation, and correct a subtle base_url fallback issue.
+
+🔧 **OpenAPI 3.1 support** fixes version detection to properly handle 3.1 specs alongside 3.0.
+
+📋 **MCP spec compliance** for root-level `$ref` resolution in output schemas and titled enum elicitation schemas.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.14.1" description="December 15, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.14.1: 'Tis a Gift to Be Sample"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.1"
+cta="Read the release notes"
+>
+FastMCP 2.14.1 introduces sampling with tools (SEP-1577), enabling servers to pass tools to `ctx.sample()` for agentic workflows where the LLM can automatically execute tool calls in a loop.
+
+🤖 **Sampling with tools** lets servers leverage client LLM capabilities for multi-step agentic workflows. The new `ctx.sample_step()` method provides single LLM calls with tool inspection, while `result_type` enables structured outputs via validated Pydantic models.
+
+🔧 **AnthropicSamplingHandler** joins the existing OpenAI handler, and both are now promoted from experimental to production-ready status with a unified API.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.14.0" description="December 11, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.14.0: Task and You Shall Receive"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.0"
+cta="Read the release notes"
+>
+FastMCP 2.14 begins adopting the MCP 2025-11-25 specification, introducing protocol-native background tasks that enable long-running operations to report progress without blocking clients.
+
+⏳ **Background Tasks (SEP-1686)** let you add `task=True` to any async tool decorator. Powered by [Docket](https://github.com/chrisguidry/docket) for enterprise task scheduling—in-memory backends work out-of-the-box, Redis enables persistence and horizontal scaling.
+
+🔧 **OpenAPI Parser Promoted** from experimental to standard with improved performance through single-pass schema processing.
+
+📋 **MCP Spec Updates** including SSE polling (SEP-1699), multi-select elicitation (SEP-1330), and tool name validation (SEP-986). Also removes deprecated APIs accumulated across 2.x.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.13.3" description="December 3, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.13.3: Pin-ish Line"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.3"
+cta="Read the release notes"
+>
+Pins `mcp<1.23` as a precaution due to MCP SDK changes related to the 11/25/25 protocol update that break certain FastMCP patches and workarounds. FastMCP 2.14 introduces proper support for the updated protocol.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.13.2" description="December 1, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.13.2: Refreshing Changes"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.2"
+cta="Read the release notes"
+>
+Polishes the authentication stack with improvements to token refresh, scope handling, and multi-instance deployments.
+
+🎮 **Discord OAuth provider** added as a built-in authentication option.
+
+🔄 **Token refresh fixes** for Azure and Google providers, plus OAuth proxy improvements for multi-instance deployments.
+
+🎨 **Icon support** added to proxy classes for richer UX.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.13.1" description="November 15, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.13.1: Heavy Meta"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.1"
+cta="Read the release notes"
+>
+Introduces meta parameter support for `ToolResult`, enabling tools to return supplementary metadata alongside results for patterns like OpenAI's Apps SDK.
+
+🏷️ **Meta parameters** let tools return supplementary metadata alongside results.
+
+🔐 **New auth providers** for OCI and Supabase, plus custom token verifiers with DebugTokenVerifier for development.
+
+🔒 **Security fixes** for CVE-2025-61920 and safer Cursor deeplink URL validation on Windows.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.13.0" description="October 25, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.13.0: Cache Me If You Can"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.0"
+cta="Read the release notes"
+>
+FastMCP 2.13 "Cache Me If You Can" represents a fundamental maturation of the framework. After months of community feedback on authentication and state management, this release delivers the infrastructure FastMCP needs to handle production workloads: persistent storage, response caching, and pragmatic OAuth improvements that reflect real-world deployment challenges.
+
+💾 **Pluggable storage backends** bring persistent state to FastMCP servers. Built on [py-key-value-aio](https://github.com/strawgate/py-key-value), a new library from FastMCP maintainer Bill Easton ([@strawgate](https://github.com/strawgate)), the storage layer provides encrypted disk storage by default, platform-aware token management, and a simple key-value interface for application state. We're excited to bring this elegantly designed library into the FastMCP ecosystem - it's both powerful and remarkably easy to use, including wrappers to add encryption, TTLs, caching, and more to backends ranging from Elasticsearch, Redis, DynamoDB, filesystem, in-memory, and more!
+
+🔐 **OAuth maturity** brings months of production learnings into the framework. The new consent screen prevents confused deputy and authorization bypass attacks discovered in earlier versions, while the OAuth proxy now issues its own tokens with automatic key derivation. RFC 7662 token introspection support enables enterprise auth flows, and path prefix mounting enables OAuth-protected servers to integrate into existing web applications. FastMCP now supports out-of-the-box authentication with [WorkOS](https://gofastmcp.com/integrations/workos) and [AuthKit](https://gofastmcp.com/integrations/authkit), [GitHub](https://gofastmcp.com/integrations/github), [Google](https://gofastmcp.com/integrations/google), [Azure](https://gofastmcp.com/integrations/azure) (Entra ID), [AWS Cognito](https://gofastmcp.com/integrations/aws-cognito), [Auth0](https://gofastmcp.com/integrations/auth0), [Descope](https://gofastmcp.com/integrations/descope), [Scalekit](https://gofastmcp.com/integrations/scalekit), [JWTs](https://gofastmcp.com/servers/auth/token-verification#jwt-token-verification), and [RFC 7662 token introspection](https://gofastmcp.com/servers/auth/token-verification#token-introspection-protocol).
+
+⚡ **Response Caching Middleware** dramatically improves performance for expensive operations, while **Server lifespans** provide proper initialization and cleanup hooks that run once per server instance instead of per client session.
+
+✨ **Developer experience improvements** include Pydantic input validation, icon support, RFC 6570 query parameters for resource templates, improved Context API methods, and async file/directory resources.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.12.5" description="October 17, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.12.5: Safety Pin"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.5"
+cta="Read the release notes"
+>
+Pins MCP SDK version below 1.17 to ensure the `.well-known` payload appears in the expected location when using FastMCP auth providers with composite applications.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.12.4" description="September 26, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.12.4: OIDC What You Did There"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.4"
+cta="Read the release notes"
+>
+FastMCP 2.12.4 adds comprehensive OIDC support and expands authentication options with AWS Cognito and Descope providers. The release also includes improvements to logging middleware, URL handling for nested resources, persistent OAuth client registration storage, and various fixes to the experimental OpenAPI parser.
+
+🔐 **OIDC Configuration** brings native support for OpenID Connect, enabling seamless integration with enterprise identity providers.
+
+🏢 **Enterprise Authentication** expands with AWS Cognito and Descope providers, broadening the authentication ecosystem.
+
+🛠️ **Improved Reliability** through enhanced URL handling, persistent OAuth storage, and numerous parser fixes based on community feedback.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.12.3" description="September 17, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.12.3: Double Time"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.3"
+cta="Read the release notes"
+>
+FastMCP 2.12.3 focuses on performance and developer experience improvements. This release includes optimized auth provider imports that reduce server startup time, enhanced OIDC authentication flows, and automatic inline snapshot creation for testing.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.12.2" description="September 3, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.12.2: Perchance to Stream"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.2"
+cta="Read the release notes"
+>
+Hotfix for streamable-http transport validation in fastmcp.json configuration files, resolving a parsing error when CLI arguments were merged against the configuration spec.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.12.1" description="September 3, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.12.1: OAuth to Joy"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.1"
+cta="Read the release notes"
+>
+FastMCP 2.12.1 strengthens OAuth proxy implementation with improved client storage reliability, PKCE forwarding, configurable token endpoint authentication methods, and expanded scope handling based on extensive community testing.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.12" description="August 31, 2025" tags={["Releases"]}>
+<Card 
+title="FastMCP 2.12: Auth to the Races" 
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.0" 
+cta="Read the release notes"  
+>
+FastMCP 2.12 represents one of our most significant releases to date. After extensive testing and iteration with the community, we're shipping major improvements to authentication, configuration, and MCP feature adoption.
+
+🔐 **OAuth Proxy** bridges the gap for providers that don't support Dynamic Client Registration, enabling authentication with GitHub, Google, WorkOS, and Azure through minimal configuration.
+
+📋 **Declarative JSON Configuration** introduces `fastmcp.json` as the single source of truth for server settings, making MCP servers as portable and shareable as container images.
+
+🧠 **Sampling API Fallback** tackles adoption challenges by letting servers generate completions server-side when clients don't support the feature, encouraging innovation while maintaining compatibility.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.11" description="August 1, 2025" tags={["Releases"]}>
+<Card 
+title="FastMCP 2.11: Auth to a Good Start" 
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.11.0" 
+cta="Read the release notes"  
+>
+FastMCP 2.11 brings enterprise-ready authentication and dramatic performance improvements.
+
+🔒 **Comprehensive OAuth 2.1 Support** with WorkOS AuthKit integration, Dynamic Client Registration, and support for separate resource and authorization servers.
+
+⚡ **Experimental OpenAPI Parser** delivers dramatic performance gains through single-pass schema processing and optimized memory usage (enable with environment variable).
+
+💾 **Enhanced State Management** provides persistent state across tool calls with a simple dictionary interface, improving context handling and type annotations.
+
+This release emphasizes speed and simplicity while setting the foundation for future enterprise features.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.10" description="July 2, 2025" tags={["Releases"]}>
+<Card 
+title="FastMCP 2.10: Great Spec-tations" 
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.0" 
+cta="Read the release notes"  
+>
+FastMCP 2.10 achieves full compliance with the 6/18/2025 MCP specification update, introducing powerful new communication patterns.
+
+💬 **Elicitation Support** enables dynamic server-client communication and "human-in-the-loop" workflows, allowing servers to request additional information during execution.
+
+📊 **Output Schemas** provide structured outputs for tools, making results more predictable and easier to parse programmatically.
+
+🛠️ **Enhanced HTTP Routing** with OpenAPI extensions support and configurable algorithms for more flexible API integration.
+
+This release includes a breaking change to `client.call_tool()` return signatures but significantly expands the interaction capabilities of MCP servers.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.9" description="June 23, 2025" tags={["Releases", "Blog Posts"]}>
+<Card 
+title="FastMCP 2.9: MCP-Native Middleware" href="https://www.jlowin.dev/blog/fastmcp-2-9-middleware" 
+img="https://jlowin.dev/_image?href=%2F_astro%2Fhero.BkVTdeBk.jpg&w=1200&h=630&f=png" 
+cta="Read more"  
+>
+FastMCP 2.9 is a major release that, among other things, introduces two important features that push beyond the basic MCP protocol. 
+
+🤝 *MCP Middleware* brings a flexible middleware system for intercepting and controlling server operations - think authentication, logging, rate limiting, and custom business logic without touching core protocol code. 
+
+✨ *Server-side type conversion* for prompts solves a major developer pain point: while MCP requires string arguments, your functions can now work with native Python types like lists and dictionaries, with automatic conversion handling the complexity.
+
+These features transform FastMCP from a simple protocol implementation into a powerful framework for building sophisticated MCP applications. Combined with the new `File` utility for binary data and improvements to authentication and serialization, this release makes FastMCP significantly more flexible and developer-friendly while maintaining full protocol compliance.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.8" description="June 11, 2025" tags={["Releases", "Blog Posts"]}>
+<Card 
+title="FastMCP 2.8: Transform and Roll Out" href="https://www.jlowin.dev/blog/fastmcp-2-8-tool-transformation" 
+img="https://www.jlowin.dev/_image?href=%2F_astro%2Fhero.su3kspkP.png&w=1000&h=500&f=webp" 
+cta="Read more"  
+>
+FastMCP 2.8 is here, and it's all about taking control of your tools.
+
+This release is packed with new features for curating the perfect LLM experience:
+
+🛠️ Tool Transformation
+
+The headline feature lets you wrap any tool—from your own code, a third-party library, or an OpenAPI spec—to create an enhanced, LLM-friendly version. You can rename arguments, rewrite descriptions, and hide parameters without touching the original code.
+
+This feature was developed in close partnership with Bill Easton. As Bill brilliantly [put it](https://www.linkedin.com/posts/williamseaston_huge-thanks-to-william-easton-for-providing-activity-7338011349525983232-Mw6T?utm_source=share&utm_medium=member_desktop&rcm=ACoAAAAd6d0B3uL9zpCsq9eYWKi3HIvb8eN_r_Q), "Tool transformation flips Prompt Engineering on its head: stop writing tool-friendly LLM prompts and start providing LLM-friendly tools."
+
+🏷️ Component Control
+
+Now that you're transforming tools, you need a way to hide the old ones! In FastMCP 2.8 you can programmatically enable/disable any component, and for everyone who's been asking what FastMCP's tags are for—they finally have a purpose! You can now use tags to declaratively filter which components are exposed to your clients.
+
+🚀 Pragmatic by Default
+
+Lastly, to ensure maximum compatibility with the ecosystem, we've made the pragmatic decision to default all OpenAPI routes to Tools, making your entire API immediately accessible to any tool-using agent. When the industry catches up and supports resources, we'll restore the old default -- but no reason you should do extra work before OpenAI, Anthropic, or Google!
+
+</Card>
+</Update>
+
+<Update label="FastMCP 2.7" description="June 6, 2025" tags={["Releases"]}>
+<Card 
+title="FastMCP 2.7: Pare Programming" href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.7.0" 
+img="assets/updates/release-2-7.png" 
+cta="Read the release notes"  
+>
+FastMCP 2.7 has been released!
+
+Most notably, it introduces the highly requested (and Pythonic) "naked" decorator usage:
+
+```python {3}
+mcp = FastMCP()
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    return a + b
+```
+
+In addition, decorators now return the objects they create, instead of the decorated function. This is an important usability enhancement.
+
+The bulk of the update is focused on improving the FastMCP internals, including a few breaking internal changes to private APIs. A number of functions that have clung on since 1.0 are now deprecated.
+</Card>
+</Update>
+
+
+
+<Update label="FastMCP 2.6" description="June 2, 2025" tags={["Releases", "Blog Posts"]}>
+<Card 
+title="FastMCP 2.6: Blast Auth" href="https://www.jlowin.dev/blog/fastmcp-2-6" 
+img="https://www.jlowin.dev/_image?href=%2F_astro%2Fhero.Bsu8afiw.png&w=1000&h=500&f=webp" 
+cta="Read more"  
+>
+FastMCP 2.6 is here!
+
+This release introduces first-class authentication for MCP servers and clients, including pragmatic Bearer token support and seamless OAuth 2.1 integration. This release aligns with how major AI platforms are adopting MCP today, making it easier than ever to securely connect your tools to real-world AI models. Dive into the update and secure your stack with minimal friction.
+</Card>
+</Update>
+
+<Update description="May 21, 2025" label="Vibe-Testing" tags={["Blog Posts", "Tutorials"]}>
+<Card
+title="Stop Vibe-Testing Your MCP Server"
+href="https://www.jlowin.dev/blog/stop-vibe-testing-mcp-servers"
+img="https://www.jlowin.dev/_image?href=%2F_astro%2Fhero.BUPy9I9c.png&w=1000&h=500&f=webp"
+cta="Read more"
+>
+
+Your tests are bad and you should feel bad.
+
+Stop vibe-testing your MCP server through LLM guesswork. FastMCP 2.0 introduces in-memory testing for fast, deterministic, and fully Pythonic validation of your MCP logic—no network, no subprocesses, no vibes.
+
+</Card>
+</Update>
+
+
+<Update description="May 8, 2025" label="10,000 Stars" tags={["Blog Posts"]}>
+<Card
+title="Reflecting on FastMCP at 10k stars 🌟"
+href="https://www.jlowin.dev/blog/fastmcp-2-10k-stars"
+img="https://www.jlowin.dev/_image?href=%2F_astro%2Fhero.Cnvci9Q_.png&w=1000&h=500&f=webp"
+cta="Read more"
+>
+
+In just six weeks since its relaunch, FastMCP has surpassed 10,000 GitHub stars—becoming the fastest-growing OSS project in our orbit. What started as a personal itch has become the backbone of Python-based MCP servers, powering a rapidly expanding ecosystem. While the protocol itself evolves, FastMCP continues to lead with clarity, developer experience, and opinionated tooling. Here’s to what’s next.
+
+</Card>
+</Update>
+
+<Update description="May 8, 2025" label="FastMCP 2.3" tags={["Blog Posts", "Releases"]}>
+<Card
+title="Now Streaming: FastMCP 2.3"
+href="https://www.jlowin.dev/blog/fastmcp-2-3-streamable-http"
+img="https://www.jlowin.dev/_image?href=%2F_astro%2Fhero.M_hv6gEB.png&w=1000&h=500&f=webp"
+cta="Read more"
+>
+
+FastMCP 2.3 introduces full support for Streamable HTTP, a modern alternative to SSE that simplifies MCP deployments over the web. It’s efficient, reliable, and now the default HTTP transport. Just run your server with transport="http" and connect clients via a standard URL—FastMCP handles the rest. No special setup required. This release makes deploying MCP servers easier and more portable than ever.
+
+</Card>
+</Update>
+
+<Update description="April 23, 2025" label="Proxy Servers" tags={["Blog Posts", "Tutorials"]}>
+<Card
+title="MCP Proxy Servers with FastMCP 2.0"
+href="https://www.jlowin.dev/blog/fastmcp-proxy"
+img="https://www.jlowin.dev/_image?href=%2F_astro%2Frobot-hero.DpmAqgui.png&w=1000&h=500&f=webp"
+cta="Read more"
+>
+
+Even AI needs a good travel adapter 🔌
+
+
+FastMCP now supports proxying arbitrary MCP servers, letting you run a local FastMCP instance that transparently forwards requests to any remote or third-party server—regardless of transport. This enables transport bridging (e.g., stdio ⇄ SSE), simplified client configuration, and powerful gateway patterns. Proxies are fully composable with other FastMCP servers, letting you mount or import them just like local servers. Use `FastMCP.from_client()` to wrap any backend in a clean, Pythonic proxy.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.0" description="April 16, 2025" tags={["Releases", "Blog Posts"]}>
+<Card
+title="Introducing FastMCP 2.0 🚀"
+href="https://www.jlowin.dev/blog/fastmcp-2"
+img="https://www.jlowin.dev/_image?href=%2F_astro%2Fhero.DpbmGNrr.png&w=1000&h=500&f=webp"
+cta="Read more"
+>
+
+This major release reimagines FastMCP as a full ecosystem platform, with powerful new features for composition, integration, and client interaction. You can now compose local and remote servers, proxy arbitrary MCP servers (with transport translation), and generate MCP servers from OpenAPI or FastAPI apps. A new client infrastructure supports advanced workflows like LLM sampling. 
+
+FastMCP 2.0 builds on the success of v1 with a cleaner, more flexible foundation—try it out today!
+</Card>
+</Update>
+
+
+
+<Update label="Official SDK" description="December 3, 2024" tags={["Announcements"]}>
+<Card
+title="FastMCP is joining the official MCP Python SDK!"
+href="https://bsky.app/profile/jlowin.dev/post/3lch4xk5cf22c"
+icon="sparkles"
+cta="Read the announcement"
+>
+FastMCP 1.0 will become part of the official MCP Python SDK!
+</Card>
+</Update>
+
+
+
+<Update label="FastMCP 1.0" description="December 1, 2024" tags={["Releases", "Blog Posts"]}>
+<Card
+title="Introducing FastMCP 🚀"
+href="https://www.jlowin.dev/blog/introducing-fastmcp"
+img="https://www.jlowin.dev/_image?href=%2F_astro%2Ffastmcp.Bep7YlTw.png&w=1000&h=500&f=webp"
+cta="Read more"
+>
+Because life's too short for boilerplate.
+
+This is where it all started. FastMCP’s launch post introduced a clean, Pythonic way to build MCP servers without the protocol overhead. Just write functions; FastMCP handles the rest. What began as a weekend project quickly became the foundation of a growing ecosystem.
+</Card>
+</Update>
diff --git a/docs/v2-banner.js b/docs/v2-banner.js
new file mode 100644
index 0000000..71d98d1
--- /dev/null
+++ b/docs/v2-banner.js
@@ -0,0 +1,39 @@
+// Add v2 banner inside content-container with negative margins
+(function() {
+  if (typeof window === 'undefined') return;
+  
+  function addBanner() {
+    const isV2 = window.location.pathname.includes('/v2/');
+    const container = document.getElementById('content-container');
+    let banner = document.getElementById('v2-banner');
+    
+    if (isV2 && container) {
+      if (!banner) {
+        banner = document.createElement('div');
+        banner.id = 'v2-banner';
+        banner.innerHTML = 'These are the docs for FastMCP 2.0. <a href="/getting-started/welcome" style="color: white; text-decoration: underline; font-weight: 700;">FastMCP 3.0</a> is now available.';
+        container.insertBefore(banner, container.firstChild);
+      }
+    } else if (!isV2 && banner) {
+      banner.remove();
+    }
+  }
+  
+  function run() {
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', addBanner);
+    } else {
+      addBanner();
+    }
+  }
+  
+  run();
+  
+  let lastUrl = location.href;
+  new MutationObserver(() => {
+    if (location.href !== lastUrl) {
+      lastUrl = location.href;
+      setTimeout(addBanner, 100);
+    }
+  }).observe(document.body, {subtree: true, childList: true});
+})();
diff --git a/docs/v2-navigation.json b/docs/v2-navigation.json
new file mode 100644
index 0000000..17865ed
--- /dev/null
+++ b/docs/v2-navigation.json
@@ -0,0 +1,197 @@
+{
+  "dropdowns": [
+    {
+      "dropdown": "Documentation",
+      "groups": [
+        {
+          "group": "Get Started",
+          "pages": [
+            "v2/getting-started/welcome",
+            "v2/getting-started/installation",
+            "v2/getting-started/quickstart",
+            "v2/updates"
+          ]
+        },
+        {
+          "group": "Servers",
+          "pages": [
+            "v2/servers/server",
+            {
+              "group": "Core Components",
+              "icon": "toolbox",
+              "pages": [
+                "v2/servers/tools",
+                "v2/servers/resources",
+                "v2/servers/prompts"
+              ]
+            },
+            {
+              "group": "Advanced Features",
+              "icon": "stars",
+              "pages": [
+                "v2/servers/composition",
+                "v2/servers/context",
+                "v2/servers/elicitation",
+                "v2/servers/icons",
+                "v2/servers/logging",
+                "v2/servers/middleware",
+                "v2/servers/progress",
+                "v2/servers/proxy",
+                "v2/servers/sampling",
+                "v2/servers/storage-backends",
+                "v2/servers/tasks"
+              ]
+            },
+            {
+              "group": "Authentication",
+              "icon": "shield-check",
+              "pages": [
+                "v2/servers/auth/authentication",
+                "v2/servers/auth/token-verification",
+                "v2/servers/auth/remote-oauth",
+                "v2/servers/auth/oauth-proxy",
+                "v2/servers/auth/oidc-proxy",
+                "v2/servers/auth/full-oauth-server"
+              ]
+            },
+            {
+              "group": "Deployment",
+              "icon": "rocket",
+              "pages": [
+                "v2/deployment/running-server",
+                "v2/deployment/http",
+                "deployment/prefect-horizon",
+                "v2/deployment/server-configuration"
+              ]
+            }
+          ]
+        },
+        {
+          "group": "Clients",
+          "pages": [
+            {
+              "group": "Essentials",
+              "icon": "cube",
+              "pages": [
+                "v2/clients/client",
+                "v2/clients/transports"
+              ]
+            },
+            {
+              "group": "Core Operations",
+              "icon": "handshake",
+              "pages": [
+                "v2/clients/tools",
+                "v2/clients/resources",
+                "v2/clients/prompts"
+              ]
+            },
+            {
+              "group": "Advanced Features",
+              "icon": "stars",
+              "pages": [
+                "v2/clients/elicitation",
+                "v2/clients/logging",
+                "v2/clients/progress",
+                "v2/clients/sampling",
+                "v2/clients/tasks",
+                "v2/clients/messages",
+                "v2/clients/roots"
+              ]
+            },
+            {
+              "group": "Authentication",
+              "icon": "user-shield",
+              "pages": [
+                "v2/clients/auth/oauth",
+                "v2/clients/auth/bearer"
+              ]
+            }
+          ]
+        },
+        {
+          "group": "Integrations",
+          "pages": [
+            {
+              "group": "Authentication",
+              "icon": "key",
+              "pages": [
+                "v2/integrations/auth0",
+                "v2/integrations/authkit",
+                "v2/integrations/aws-cognito",
+                "v2/integrations/azure",
+                "v2/integrations/descope",
+                "v2/integrations/discord",
+                "v2/integrations/github",
+                "v2/integrations/google",
+                "v2/integrations/oci",
+                "v2/integrations/scalekit",
+                "v2/integrations/supabase",
+                "v2/integrations/workos"
+              ]
+            },
+            {
+              "group": "Authorization",
+              "icon": "shield-check",
+              "pages": [
+                "v2/integrations/eunomia-authorization",
+                "v2/integrations/permit"
+              ]
+            },
+            {
+              "group": "AI Assistants",
+              "icon": "robot",
+              "pages": [
+                "v2/integrations/chatgpt",
+                "v2/integrations/claude-code",
+                "v2/integrations/claude-desktop",
+                "v2/integrations/cursor",
+                "v2/integrations/gemini-cli",
+                "v2/integrations/mcp-json-configuration"
+              ]
+            },
+            {
+              "group": "AI SDKs",
+              "icon": "code",
+              "pages": [
+                "v2/integrations/anthropic",
+                "v2/integrations/gemini",
+                "v2/integrations/openai"
+              ]
+            },
+            {
+              "group": "API Integration",
+              "icon": "globe",
+              "pages": [
+                "v2/integrations/fastapi",
+                "v2/integrations/openapi"
+              ]
+            }
+          ]
+        },
+        {
+          "group": "Patterns",
+          "pages": [
+            "v2/patterns/tool-transformation",
+            "v2/patterns/decorating-methods",
+            "v2/patterns/cli",
+            "v2/patterns/contrib",
+            "v2/patterns/testing"
+          ]
+        },
+        {
+          "group": "Development",
+          "pages": [
+            "v2/development/contributing",
+            "v2/development/tests",
+            "v2/development/releases",
+            "v2/development/upgrade-guide",
+            "v2/changelog"
+          ]
+        }
+      ],
+      "icon": "book"
+    }
+  ],
+  "version": "v2.14.5"
+}
diff --git a/docs/v2/changelog.mdx b/docs/v2/changelog.mdx
new file mode 100644
index 0000000..6e99792
--- /dev/null
+++ b/docs/v2/changelog.mdx
@@ -0,0 +1,2342 @@
+---
+title: "Changelog"
+icon: "list-check"
+rss: true
+---
+
+<Update label="v2.14.7" description="2026-04-13">
+
+**[v2.14.7: Fake It Till You Break It](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.7)**
+
+A 2.x backport of the fakeredis pin: fakeredis 2.35.0 renamed a connection class that pydocket's `memory://` backend depended on, crashing `fastmcp[tasks]` installs at startup. This caps `fakeredis<2.35.0` on the 2.x line.
+
+## What's Changed
+### Fixes 🐞
+* fix(deps): cap fakeredis to `<2.35.0` to prevent startup crash on 2.x by [@vincent067](https://github.com/vincent067) in [#3883](https://github.com/PrefectHQ/fastmcp/pull/3883)
+
+**Full Changelog**: [v2.14.6...v2.14.7](https://github.com/PrefectHQ/fastmcp/compare/v2.14.6...v2.14.7)
+
+</Update>
+
+<Update label="v2.14.6" description="2026-03-27">
+
+**[v2.14.6: $Ref Dead Redemption](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.6)**
+
+v2.14.4 backported `dereference_refs()` but never wired it into the tool schema pipeline — `$ref` and `$defs` were still sent to MCP clients. Now fixed: `compress_schema()` dereferences at both tool schema creation sites, so schemas are fully inlined before reaching clients.
+
+## What's Changed
+### Fixes 🐞
+* Updated deprecation URL for V2 by [@SrzStephen](https://github.com/SrzStephen) in [#3109](https://github.com/PrefectHQ/fastmcp/pull/3109)
+* Use MemoryStore for OAuth proxy tests by [@SrzStephen](https://github.com/SrzStephen) in [#3111](https://github.com/PrefectHQ/fastmcp/pull/3111)
+* fix: wire up dereference_refs() in tool schema pipeline by [@jlowin](https://github.com/jlowin) in [#3170](https://github.com/PrefectHQ/fastmcp/pull/3170)
+
+**Full Changelog**: [v2.14.5...v2.14.6](https://github.com/PrefectHQ/fastmcp/compare/v2.14.5...v2.14.6)
+
+</Update>
+
+<Update label="v2.14.5" description="2026-02-03">
+
+**[v2.14.5: Sealed Docket](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.5)**
+
+Fixes a memory leak in the memory:// docket broker where cancelled tasks accumulated instead of being cleaned up. Bumps pydocket to ≥0.17.2.
+
+## What's Changed
+### Enhancements 🔧
+* Bump pydocket to 0.17.2 (memory leak fix) by [@chrisguidry](https://github.com/chrisguidry) in [#2992](https://github.com/PrefectHQ/fastmcp/pull/2992)
+
+**Full Changelog**: [v2.14.4...v2.14.5](https://github.com/PrefectHQ/fastmcp/compare/v2.14.4...v2.14.5)
+
+</Update>
+
+<Update label="v2.14.4" description="2026-01-22">
+
+**[v2.14.4: Package Deal](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.4)**
+
+Fixes a fresh install bug where the packaging library was missing as a direct dependency, plus backports from 3.x for $ref dereferencing in tool schemas and a task capabilities location fix.
+
+## What's Changed
+### Enhancements 🔧
+* Add release notes for v2.14.2 and v2.14.3 by [@jlowin](https://github.com/jlowin) in [#2851](https://github.com/PrefectHQ/fastmcp/pull/2851)
+### Fixes 🐞
+* Backport: Dereference $ref in tool schemas for MCP client compatibility by [@jlowin](https://github.com/jlowin) in [#2861](https://github.com/PrefectHQ/fastmcp/pull/2861)
+* Fix task capabilities location (issue #2870) by [@jlowin](https://github.com/jlowin) in [#2874](https://github.com/PrefectHQ/fastmcp/pull/2874)
+* Add missing packaging dependency by [@jlowin](https://github.com/jlowin) in [#2989](https://github.com/PrefectHQ/fastmcp/pull/2989)
+
+**Full Changelog**: [v2.14.3...v2.14.4](https://github.com/PrefectHQ/fastmcp/compare/v2.14.3...v2.14.4)
+
+</Update>
+
+<Update label="v2.14.3" description="2026-01-12">
+
+**[v2.14.3: Time After Timeout](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.3)**
+
+Sometimes five seconds just isn't enough. This release fixes an HTTP transport bug that was cutting connections short, along with OAuth and Redis fixes, better ASGI support, and CLI update notifications so you never miss a beat.
+
+## What's Changed
+### Enhancements 🔧
+* Add debug logging for OAuth token expiry diagnostics by [@jlowin](https://github.com/jlowin) in [#2789](https://github.com/PrefectHQ/fastmcp/pull/2789)
+* Add CLI update notifications by [@jlowin](https://github.com/jlowin) in [#2839](https://github.com/PrefectHQ/fastmcp/pull/2839)
+* Use pip instead of uv pip in upgrade instructions by [@jlowin](https://github.com/jlowin) in [#2841](https://github.com/PrefectHQ/fastmcp/pull/2841)
+### Fixes 🐞
+* Backport OAuth token storage TTL fix to release/2.x by [@jlowin](https://github.com/jlowin) in [#2798](https://github.com/PrefectHQ/fastmcp/pull/2798)
+* Prefix Redis keys with docket name for ACL isolation (2.x backport) by [@chrisguidry](https://github.com/chrisguidry) in [#2812](https://github.com/PrefectHQ/fastmcp/pull/2812)
+* Fix ContextVar propagation for ASGI-mounted servers with tasks by [@chrisguidry](https://github.com/chrisguidry) in [#2843](https://github.com/PrefectHQ/fastmcp/pull/2843)
+* Fix HTTP transport timeout defaulting to 5 seconds by [@jlowin](https://github.com/jlowin) in [#2848](https://github.com/PrefectHQ/fastmcp/pull/2848)
+
+**Full Changelog**: [v2.14.2...v2.14.3](https://github.com/PrefectHQ/fastmcp/compare/v2.14.2...v2.14.3)
+
+</Update>
+
+<Update label="v2.14.2" description="2025-12-31">
+
+**[v2.14.2: Port Authority](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.2)**
+
+FastMCP 2.14.2 brings a wave of community contributions safely into the 2.x line. A variety of important fixes backported from 3.0 work improve OpenAPI 3.1 compatibility, MCP spec compliance for output schemas and elicitation, and correct a subtle base_url fallback issue. The CLI now gently reminds you that FastMCP 3.0 is on the horizon.
+
+## What's Changed
+### Enhancements 🔧
+* Pin MCP under 2.x by [@jlowin](https://github.com/jlowin) in [#2709](https://github.com/PrefectHQ/fastmcp/pull/2709)
+* Add auth_route parameter to SupabaseProvider by [@EloiZalczer](https://github.com/EloiZalczer) in [#2760](https://github.com/PrefectHQ/fastmcp/pull/2760)
+* Update CLI banner with FastMCP 3.0 notice by [@jlowin](https://github.com/jlowin) in [#2765](https://github.com/PrefectHQ/fastmcp/pull/2765)
+### Fixes 🐞
+* Let FastMCPError propagate unchanged from managers by [@jlowin](https://github.com/jlowin) in [#2697](https://github.com/PrefectHQ/fastmcp/pull/2697)
+* Fix test cleanup for uvicorn 0.39+ context isolation by [@jlowin](https://github.com/jlowin) in [#2696](https://github.com/PrefectHQ/fastmcp/pull/2696)
+* Bump pydocket to 0.16.3 to fix worker cleanup race condition by [@chrisguidry](https://github.com/chrisguidry) in [#2700](https://github.com/PrefectHQ/fastmcp/pull/2700)
+* Fix Prefect website URL in docs footer by [@mgoldsborough](https://github.com/mgoldsborough) in [#2705](https://github.com/PrefectHQ/fastmcp/pull/2705)
+* Fix: resolve root-level $ref in outputSchema for MCP spec compliance by [@majiayu000](https://github.com/majiayu000) in [#2727](https://github.com/PrefectHQ/fastmcp/pull/2727)
+* Fix OAuth Proxy resource parameter validation by [@jlowin](https://github.com/jlowin) in [#2763](https://github.com/PrefectHQ/fastmcp/pull/2763)
+* Fix openapi_version check to include 3.1 by [@deeleeramone](https://github.com/deeleeramone) in [#2769](https://github.com/PrefectHQ/fastmcp/pull/2769)
+* Fix titled enum elicitation schema to comply with MCP spec by [@jlowin](https://github.com/jlowin) in [#2774](https://github.com/PrefectHQ/fastmcp/pull/2774)
+* Fix base_url fallback when url is not set by [@bhbs](https://github.com/bhbs) in [#2782](https://github.com/PrefectHQ/fastmcp/pull/2782)
+* Lazy import DiskStore to avoid sqlite3 dependency on import by [@jlowin](https://github.com/jlowin) in [#2785](https://github.com/PrefectHQ/fastmcp/pull/2785)
+### Docs 📚
+* Add v3 breaking changes notice to README and docs by [@jlowin](https://github.com/jlowin) in [#2713](https://github.com/PrefectHQ/fastmcp/pull/2713)
+* Add changelog entries for v2.13.1 through v2.14.1 by [@jlowin](https://github.com/jlowin) in [#2724](https://github.com/PrefectHQ/fastmcp/pull/2724)
+* conference to 2.x branch by [@aaazzam](https://github.com/aaazzam) in [#2787](https://github.com/PrefectHQ/fastmcp/pull/2787)
+
+**Full Changelog**: [v2.14.1...v2.14.2](https://github.com/PrefectHQ/fastmcp/compare/v2.14.1...v2.14.2)
+
+</Update>
+
+<Update label="v2.14.1" description="2025-12-15">
+
+**[v2.14.1: 'Tis a Gift to Be Sample](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.1)**
+
+FastMCP 2.14.1 introduces sampling with tools (SEP-1577), enabling servers to pass tools to `ctx.sample()` for agentic workflows where the LLM can automatically execute tool calls in a loop. The new `ctx.sample_step()` method provides single LLM calls that return `SampleStep` objects for custom control flow, while `result_type` enables structured outputs via validated Pydantic models.
+
+🤖 **AnthropicSamplingHandler** joins the existing OpenAI handler, providing multi-provider sampling support out of the box.
+
+⚡ **OpenAISamplingHandler promoted** from experimental status—sampling handlers are now production-ready with a unified API.
+
+## What's Changed
+### New Features 🎉
+* Sampling with tools by [@jlowin](https://github.com/jlowin) in [#2538](https://github.com/PrefectHQ/fastmcp/pull/2538)
+* Add AnthropicSamplingHandler by [@jlowin](https://github.com/jlowin) in [#2677](https://github.com/PrefectHQ/fastmcp/pull/2677)
+### Enhancements 🔧
+* Add Python 3.13 to ubuntu CI by [@jlowin](https://github.com/jlowin) in [#2648](https://github.com/PrefectHQ/fastmcp/pull/2648)
+* Remove legacy task initialization workaround by [@jlowin](https://github.com/jlowin) in [#2649](https://github.com/PrefectHQ/fastmcp/pull/2649)
+* Consolidate session state reset logic by [@jlowin](https://github.com/jlowin) in [#2651](https://github.com/PrefectHQ/fastmcp/pull/2651)
+* Unify SamplingHandler; promote OpenAI from experimental by [@jlowin](https://github.com/jlowin) in [#2656](https://github.com/PrefectHQ/fastmcp/pull/2656)
+* Add `tool_names` parameter to mount() for name customization by [@jlowin](https://github.com/jlowin) in [#2660](https://github.com/PrefectHQ/fastmcp/pull/2660)
+* Use streamable HTTP client API from MCP SDK by [@jlowin](https://github.com/jlowin) in [#2678](https://github.com/PrefectHQ/fastmcp/pull/2678)
+* Deprecate `exclude_args` in favor of Depends() by [@jlowin](https://github.com/jlowin) in [#2693](https://github.com/PrefectHQ/fastmcp/pull/2693)
+### Fixes 🐞
+* Fix prompt tasks to return mcp.types.PromptMessage by [@jlowin](https://github.com/jlowin) in [#2650](https://github.com/PrefectHQ/fastmcp/pull/2650)
+* Fix Windows test warnings by [@jlowin](https://github.com/jlowin) in [#2653](https://github.com/PrefectHQ/fastmcp/pull/2653)
+* Cleanup cancelled connection startup by [@jlowin](https://github.com/jlowin) in [#2679](https://github.com/PrefectHQ/fastmcp/pull/2679)
+* Fix tool choice bug in sampling examples by [@shawnthapa](https://github.com/shawnthapa) in [#2686](https://github.com/PrefectHQ/fastmcp/pull/2686)
+### Docs 📚
+* Simplify Docket tip wording by [@chrisguidry](https://github.com/chrisguidry) in [#2662](https://github.com/PrefectHQ/fastmcp/pull/2662)
+### Other Changes 🦾
+* Bump pydocket to ≥0.15.5 by [@jlowin](https://github.com/jlowin) in [#2694](https://github.com/PrefectHQ/fastmcp/pull/2694)
+
+## New Contributors
+* [@shawnthapa](https://github.com/shawnthapa) made their first contribution in [#2686](https://github.com/PrefectHQ/fastmcp/pull/2686)
+
+**Full Changelog**: [v2.14.0...v2.14.1](https://github.com/PrefectHQ/fastmcp/compare/v2.14.0...v2.14.1)
+
+</Update>
+
+<Update label="v2.14.0" description="2025-12-11">
+
+**[v2.14.0: Task and You Shall Receive](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.0)**
+
+FastMCP 2.14 begins adopting the MCP 2025-11-25 specification, introducing protocol-native background tasks (SEP-1686) that enable long-running operations to report progress without blocking clients. The experimental OpenAPI parser graduates to standard, the `OpenAISamplingHandler` is promoted from experimental, and deprecated APIs accumulated across the 2.x series are removed.
+
+⏳ **Background Tasks** let you add `task=True` to any async tool decorator to run operations in the background with progress tracking. Powered by [Docket](https://github.com/chrisguidry/docket), an enterprise task scheduler handling millions of concurrent tasks daily—in-memory backends work out-of-the-box, and Redis URLs enable persistence and horizontal scaling.
+
+🔧 **OpenAPI Parser Promoted** from experimental to standard with improved performance through single-pass schema processing and cleaner abstractions.
+
+📋 **MCP 2025-11-25 Specification Support** including SSE polling and event resumability (SEP-1699), multi-select enum elicitation schemas (SEP-1330), default values for elicitation (SEP-1034), and tool name validation at registration time (SEP-986).
+
+## Breaking Changes
+- Docket is always enabled; task execution is forbidden through proxies
+- Task protocol enabled by default
+- Removed deprecated settings, imports, and methods accumulated across 2.x series
+
+## What's Changed
+### New Features 🎉
+* OpenAPI parser is now the default by [@jlowin](https://github.com/jlowin) in [#2583](https://github.com/PrefectHQ/fastmcp/pull/2583)
+* Implement SEP-1686: Background Tasks by [@jlowin](https://github.com/jlowin) in [#2550](https://github.com/PrefectHQ/fastmcp/pull/2550)
+### Enhancements 🔧
+* Expose InitializeResult in middleware by [@jlowin](https://github.com/jlowin) in [#2562](https://github.com/PrefectHQ/fastmcp/pull/2562)
+* Update MCP SDK auth compatibility by [@jlowin](https://github.com/jlowin) in [#2574](https://github.com/PrefectHQ/fastmcp/pull/2574)
+* Validate tool names at registration (SEP-986) by [@jlowin](https://github.com/jlowin) in [#2588](https://github.com/PrefectHQ/fastmcp/pull/2588)
+* Support SEP-1034 and SEP-1330 for elicitation by [@jlowin](https://github.com/jlowin) in [#2595](https://github.com/PrefectHQ/fastmcp/pull/2595)
+* Implement SSE polling (SEP-1699) by [@jlowin](https://github.com/jlowin) in [#2612](https://github.com/PrefectHQ/fastmcp/pull/2612)
+* Expose session ID callback by [@jlowin](https://github.com/jlowin) in [#2628](https://github.com/PrefectHQ/fastmcp/pull/2628)
+### Fixes 🐞
+* Fix OAuth metadata discovery by [@jlowin](https://github.com/jlowin) in [#2565](https://github.com/PrefectHQ/fastmcp/pull/2565)
+* Fix fastapi.cli package structure by [@jlowin](https://github.com/jlowin) in [#2570](https://github.com/PrefectHQ/fastmcp/pull/2570)
+* Correct OAuth error codes by [@jlowin](https://github.com/jlowin) in [#2578](https://github.com/PrefectHQ/fastmcp/pull/2578)
+* Prevent function signature modification by [@jlowin](https://github.com/jlowin) in [#2590](https://github.com/PrefectHQ/fastmcp/pull/2590)
+* Fix proxy client kwargs by [@jlowin](https://github.com/jlowin) in [#2605](https://github.com/PrefectHQ/fastmcp/pull/2605)
+* Fix nested server routing by [@jlowin](https://github.com/jlowin) in [#2618](https://github.com/PrefectHQ/fastmcp/pull/2618)
+* Use access token expiry fallback by [@jlowin](https://github.com/jlowin) in [#2635](https://github.com/PrefectHQ/fastmcp/pull/2635)
+* Handle transport cleanup exceptions by [@jlowin](https://github.com/jlowin) in [#2642](https://github.com/PrefectHQ/fastmcp/pull/2642)
+### Docs 📚
+* Add OCI and Supabase integration docs by [@jlowin](https://github.com/jlowin) in [#2580](https://github.com/PrefectHQ/fastmcp/pull/2580)
+* Add v2.14.0 upgrade guide by [@jlowin](https://github.com/jlowin) in [#2598](https://github.com/PrefectHQ/fastmcp/pull/2598)
+* Rewrite background tasks documentation by [@jlowin](https://github.com/jlowin) in [#2620](https://github.com/PrefectHQ/fastmcp/pull/2620)
+* Document read-only tool patterns by [@jlowin](https://github.com/jlowin) in [#2632](https://github.com/PrefectHQ/fastmcp/pull/2632)
+
+## New Contributors
+11 total contributors including 7 first-time participants.
+
+**Full Changelog**: [v2.13.3...v2.14.0](https://github.com/PrefectHQ/fastmcp/compare/v2.13.3...v2.14.0)
+
+</Update>
+
+<Update label="v2.13.3" description="2025-12-03">
+
+**[v2.13.3: Pin-ish Line](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.3)**
+
+FastMCP 2.13.3 pins `mcp<1.23` as a precautionary measure. MCP SDK 1.23 introduced changes related to the November 25, 2025 MCP protocol update that break certain FastMCP patches and workarounds, particularly around OAuth implementation details. FastMCP 2.14 introduces proper support for the updated protocol and requires `mcp>=1.23`.
+
+## What's Changed
+### Fixes 🐞
+* Pin MCP SDK below 1.23 by [@jlowin](https://github.com/jlowin) in [#2545](https://github.com/PrefectHQ/fastmcp/pull/2545)
+
+**Full Changelog**: [v2.13.2...v2.13.3](https://github.com/PrefectHQ/fastmcp/compare/v2.13.2...v2.13.3)
+
+</Update>
+
+<Update label="v2.13.2" description="2025-12-01">
+
+**[v2.13.2: Refreshing Changes](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.2)**
+
+FastMCP 2.13.2 polishes the authentication stack with improvements to token refresh, scope handling, and multi-instance deployments. Discord was added as a built-in OAuth provider, Azure and Google token handling became more reliable, and proxy classes now properly forward icons and titles.
+
+## What's Changed
+### New Features 🎉
+* Add Discord OAuth provider by [@jlowin](https://github.com/jlowin) in [#2480](https://github.com/PrefectHQ/fastmcp/pull/2480)
+### Enhancements 🔧
+* Descope Provider updates for new well-known URLs by [@anvibanga](https://github.com/anvibanga) in [#2465](https://github.com/PrefectHQ/fastmcp/pull/2465)
+* Scalekit provider improvements by [@jlowin](https://github.com/jlowin) in [#2472](https://github.com/PrefectHQ/fastmcp/pull/2472)
+* Add CSP customization for consent screens by [@jlowin](https://github.com/jlowin) in [#2488](https://github.com/PrefectHQ/fastmcp/pull/2488)
+* Add icon support to proxy classes by [@jlowin](https://github.com/jlowin) in [#2495](https://github.com/PrefectHQ/fastmcp/pull/2495)
+### Fixes 🐞
+* Google Provider now defaults to refresh token support by [@jlowin](https://github.com/jlowin) in [#2468](https://github.com/PrefectHQ/fastmcp/pull/2468)
+* Fix Azure OAuth token refresh with unprefixed scopes by [@jlowin](https://github.com/jlowin) in [#2475](https://github.com/PrefectHQ/fastmcp/pull/2475)
+* Prevent `$defs` mutation during tool transforms by [@jlowin](https://github.com/jlowin) in [#2482](https://github.com/PrefectHQ/fastmcp/pull/2482)
+* Fix OAuth proxy refresh token storage for multi-instance deployments by [@jlowin](https://github.com/jlowin) in [#2490](https://github.com/PrefectHQ/fastmcp/pull/2490)
+* Fix stale token issue after OAuth refresh by [@jlowin](https://github.com/jlowin) in [#2498](https://github.com/PrefectHQ/fastmcp/pull/2498)
+* Fix Azure provider OIDC scope handling by [@jlowin](https://github.com/jlowin) in [#2505](https://github.com/PrefectHQ/fastmcp/pull/2505)
+
+## New Contributors
+7 new contributors made their first FastMCP contributions in this release.
+
+**Full Changelog**: [v2.13.1...v2.13.2](https://github.com/PrefectHQ/fastmcp/compare/v2.13.1...v2.13.2)
+
+</Update>
+
+<Update label="v2.13.1" description="2025-11-15">
+
+**[v2.13.1: Heavy Meta](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.1)**
+
+FastMCP 2.13.1 introduces meta parameter support for `ToolResult`, enabling tools to return supplementary metadata alongside results. This supports emerging use cases like OpenAI's Apps SDK. The release also brings improved OAuth functionality with custom token verifiers including a new DebugTokenVerifier, and adds OCI and Supabase authentication providers.
+
+🏷️ **Meta parameters for ToolResult** enable tools to return supplementary metadata alongside results, supporting patterns like OpenAI's Apps SDK integration.
+
+🔐 **Custom token verifiers** with DebugTokenVerifier for development, plus Azure Government support through a `base_authority` parameter and Supabase authentication algorithm configuration.
+
+🔒 **Security fixes** address CVE-2025-61920 through authlib updates and validate Cursor deeplink URLs using safer Windows APIs.
+
+## What's Changed
+### New Features 🎉
+* Add meta parameter support for ToolResult by [@jlowin](https://github.com/jlowin) in [#2350](https://github.com/PrefectHQ/fastmcp/pull/2350)
+* Add OCI authentication provider by [@jlowin](https://github.com/jlowin) in [#2365](https://github.com/PrefectHQ/fastmcp/pull/2365)
+* Add Supabase authentication provider by [@jlowin](https://github.com/jlowin) in [#2378](https://github.com/PrefectHQ/fastmcp/pull/2378)
+### Enhancements 🔧
+* Add custom token verifier support to OIDCProxy by [@jlowin](https://github.com/jlowin) in [#2355](https://github.com/PrefectHQ/fastmcp/pull/2355)
+* Add DebugTokenVerifier for development by [@jlowin](https://github.com/jlowin) in [#2362](https://github.com/PrefectHQ/fastmcp/pull/2362)
+* Add Azure Government support via base_authority parameter by [@jlowin](https://github.com/jlowin) in [#2385](https://github.com/PrefectHQ/fastmcp/pull/2385)
+* Add Supabase authentication algorithm configuration by [@jlowin](https://github.com/jlowin) in [#2392](https://github.com/PrefectHQ/fastmcp/pull/2392)
+### Fixes 🐞
+* Security: Update authlib for CVE-2025-61920 by [@jlowin](https://github.com/jlowin) in [#2398](https://github.com/PrefectHQ/fastmcp/pull/2398)
+* Validate Cursor deeplink URLs using safer Windows APIs by [@jlowin](https://github.com/jlowin) in [#2405](https://github.com/PrefectHQ/fastmcp/pull/2405)
+* Exclude MCP SDK 1.21.1 due to integration test failures by [@jlowin](https://github.com/jlowin) in [#2422](https://github.com/PrefectHQ/fastmcp/pull/2422)
+
+## New Contributors
+18 new contributors joined in this release across 70+ pull requests.
+
+**Full Changelog**: [v2.13.0...v2.13.1](https://github.com/PrefectHQ/fastmcp/compare/v2.13.0...v2.13.1)
+
+</Update>
+
+<Update label="v2.13.0" description="2025-10-25">
+
+**[v2.13.0: Cache Me If You Can](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.0)**
+
+FastMCP 2.13 "Cache Me If You Can" represents a fundamental maturation of the framework. After months of community feedback on authentication and state management, this release delivers the infrastructure FastMCP needs to handle production workloads: persistent storage, response caching, and pragmatic OAuth improvements that reflect real-world deployment challenges.
+
+💾 **Pluggable storage backends** bring persistent state to FastMCP servers. Built on [py-key-value-aio](https://github.com/strawgate/py-key-value), a new library from FastMCP maintainer Bill Easton ([@strawgate](https://github.com/strawgate)), the storage layer provides encrypted disk storage by default, platform-aware token management, and a simple key-value interface for application state. We're excited to bring this elegantly designed library into the FastMCP ecosystem - it's both powerful and remarkably easy to use, including wrappers to add encryption, TTLs, caching, and more to backends ranging from Elasticsearch, Redis, DynamoDB, filesystem, in-memory, and more! OAuth providers now automatically persist tokens across restarts, and developers can store arbitrary state without reaching for external databases. This foundation enables long-running sessions, cached credentials, and stateful applications built on MCP.
+
+🔐 **OAuth maturity** brings months of production learnings into the framework. The new consent screen prevents confused deputy and authorization bypass attacks discovered in earlier versions while providing a clean UX with customizable branding. The OAuth proxy now issues its own tokens with automatic key derivation from client secrets, and RFC 7662 token introspection support enables enterprise auth flows. Path prefix mounting enables OAuth-protected servers to integrate into existing web applications under custom paths like `/api`, and MCP 1.17+ compliance with RFC 9728 ensures protocol compatibility. Combined with improved error handling and platform-aware token storage, OAuth is now production-ready and security-hardened for serious applications.
+
+FastMCP now supports out-of-the-box authentication with:
+- **[WorkOS](https://gofastmcp.com/integrations/workos)** and **[AuthKit](https://gofastmcp.com/integrations/authkit)**
+- **[GitHub](https://gofastmcp.com/integrations/github)**
+- **[Google](https://gofastmcp.com/integrations/google)**
+- **[Azure](https://gofastmcp.com/integrations/azure)** (Entra ID)
+- **[AWS Cognito](https://gofastmcp.com/integrations/aws-cognito)**
+- **[Auth0](https://gofastmcp.com/integrations/auth0)**
+- **[Descope](https://gofastmcp.com/integrations/descope)**
+- **[Scalekit](https://gofastmcp.com/integrations/scalekit)**
+- **[JWTs](https://gofastmcp.com/servers/auth/token-verification#jwt-token-verification)**
+- **[RFC 7662 token introspection](https://gofastmcp.com/servers/auth/token-verification#token-introspection-protocol)**
+
+⚡ **Response Caching Middleware** dramatically improves performance for expensive operations. Cache tool and resource responses with configurable TTLs, reducing redundant API calls and speeding up repeated queries.
+
+🔄 **Server lifespans** provide proper initialization and cleanup hooks that run once per server instance instead of per client session. This fixes a long-standing source of confusion in the MCP SDK and enables proper resource management for database connections, background tasks, and other server-level state. Note: this is a breaking behavioral change if you were using the `lifespan` parameter.
+
+✨ **Developer experience improvements** include Pydantic input validation for better type safety, icon support for richer UX, RFC 6570 query parameters for resource templates, improved Context API methods (list_resources, list_prompts, get_prompt), and async file/directory resources.
+
+This release includes contributions from **20** new contributors and represents the largest feature set in a while. Thank you to everyone who tested preview builds and filed issues - your feedback shaped these improvements!
+
+**Full Changelog**: [v2.12.5...v2.13.0](https://github.com/PrefectHQ/fastmcp/compare/v2.12.5...v2.13.0)
+
+</Update>
+
+<Update label="v2.12.5" description="2025-10-17">
+
+**[v2.12.5: Safety Pin](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.5)**
+
+FastMCP 2.12.5 is a point release that pins the MCP SDK version below 1.17, which introduced a change affecting FastMCP users with auth providers mounted as part of a larger application. This ensures the `.well-known` payload appears in the expected location when using FastMCP authentication providers with composite applications.
+
+## What's Changed
+
+### Fixes 🐞
+* Pin MCP SDK version below 1.17 by [@jlowin](https://github.com/jlowin) in [a1b2c3d](https://github.com/PrefectHQ/fastmcp/commit/dab2b316ddc3883b7896a86da21cacb68da01e5c)
+
+**Full Changelog**: [v2.12.4...v2.12.5](https://github.com/PrefectHQ/fastmcp/compare/v2.12.4...v2.12.5)
+
+</Update>
+
+<Update label="v2.12.4" description="2025-09-26">
+
+**[v2.12.4: OIDC What You Did There](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.4)**
+
+FastMCP 2.12.4 adds comprehensive OIDC support and expands authentication options with AWS Cognito and Descope providers. The release also includes improvements to logging middleware, URL handling for nested resources, persistent OAuth client registration storage, and various fixes to the experimental OpenAPI parser.
+
+## What's Changed
+### New Features 🎉
+* feat: Add support for OIDC configuration by [@ruhulio](https://github.com/ruhulio) in [#1817](https://github.com/PrefectHQ/fastmcp/pull/1817)
+### Enhancements 🔧
+* feat: Move the Starlette context middleware to the front by [@akkuman](https://github.com/akkuman) in [#1812](https://github.com/PrefectHQ/fastmcp/pull/1812)
+* Refactor Logging and Structured Logging Middleware by [@strawgate](https://github.com/strawgate) in [#1805](https://github.com/PrefectHQ/fastmcp/pull/1805)
+* Update pull_request_template.md by [@jlowin](https://github.com/jlowin) in [#1824](https://github.com/PrefectHQ/fastmcp/pull/1824)
+* chore: Set redirect_path default in function by [@ruhulio](https://github.com/ruhulio) in [#1833](https://github.com/PrefectHQ/fastmcp/pull/1833)
+* feat: Set instructions in code by [@attiks](https://github.com/attiks) in [#1838](https://github.com/PrefectHQ/fastmcp/pull/1838)
+* Automatically Create inline Snapshots by [@strawgate](https://github.com/strawgate) in [#1779](https://github.com/PrefectHQ/fastmcp/pull/1779)
+* chore: Cleanup Auth0 redirect_path initialization by [@ruhulio](https://github.com/ruhulio) in [#1842](https://github.com/PrefectHQ/fastmcp/pull/1842)
+* feat: Add support for Descope Authentication by [@anvibanga](https://github.com/anvibanga) in [#1853](https://github.com/PrefectHQ/fastmcp/pull/1853)
+* Update descope version badges by [@jlowin](https://github.com/jlowin) in [#1870](https://github.com/PrefectHQ/fastmcp/pull/1870)
+* Update welcome images by [@jlowin](https://github.com/jlowin) in [#1884](https://github.com/PrefectHQ/fastmcp/pull/1884)
+* Fix rounded edges of image by [@jlowin](https://github.com/jlowin) in [#1886](https://github.com/PrefectHQ/fastmcp/pull/1886)
+* optimize test suite by [@zzstoatzz](https://github.com/zzstoatzz) in [#1893](https://github.com/PrefectHQ/fastmcp/pull/1893)
+* Enhancement: client completions support context_arguments by [@isijoe](https://github.com/isijoe) in [#1906](https://github.com/PrefectHQ/fastmcp/pull/1906)
+* Update Descope icon by [@anvibanga](https://github.com/anvibanga) in [#1912](https://github.com/PrefectHQ/fastmcp/pull/1912)
+* Add AWS Cognito OAuth Provider for Enterprise Authentication by [@stephaneberle9](https://github.com/stephaneberle9) in [#1873](https://github.com/PrefectHQ/fastmcp/pull/1873)
+* Fix typos discovered by codespell by [@cclauss](https://github.com/cclauss) in [#1922](https://github.com/PrefectHQ/fastmcp/pull/1922)
+* Use lowercase namespace for fastmcp logger by [@jlowin](https://github.com/jlowin) in [#1791](https://github.com/PrefectHQ/fastmcp/pull/1791)
+### Fixes 🐞
+* Update quickstart.mdx by [@radi-dev](https://github.com/radi-dev) in [#1821](https://github.com/PrefectHQ/fastmcp/pull/1821)
+* Remove extraneous union import by [@jlowin](https://github.com/jlowin) in [#1823](https://github.com/PrefectHQ/fastmcp/pull/1823)
+* Delay import of Provider classes until FastMCP Server Creation by [@strawgate](https://github.com/strawgate) in [#1820](https://github.com/PrefectHQ/fastmcp/pull/1820)
+* fix: correct documentation link in deprecation warning by [@strawgate](https://github.com/strawgate) in [#1828](https://github.com/PrefectHQ/fastmcp/pull/1828)
+* fix: Increase default 3s timeout on Pytest by [@dacamposol](https://github.com/dacamposol) in [#1866](https://github.com/PrefectHQ/fastmcp/pull/1866)
+* fix: Improve URL handling in OIDCConfiguration by [@ruhulio](https://github.com/ruhulio) in [#1850](https://github.com/PrefectHQ/fastmcp/pull/1850)
+* fix: correct typing for on_read_resource middleware method by [@strawgate](https://github.com/strawgate) in [#1858](https://github.com/PrefectHQ/fastmcp/pull/1858)
+* feat(experimental/openapi): replace $ref in additionalProperties; add tests by [@jlowin](https://github.com/jlowin) in [#1735](https://github.com/PrefectHQ/fastmcp/pull/1735)
+* Honor client supplied scopes during registration by [@dmikusa](https://github.com/dmikusa) in [#1860](https://github.com/PrefectHQ/fastmcp/pull/1860)
+* Fix: FastAPI list parameter parsing in experimental OpenAPI parser by [@jlowin](https://github.com/jlowin) in [#1834](https://github.com/PrefectHQ/fastmcp/pull/1834)
+* Add log level support for stdio and HTTP transports by [@jlowin](https://github.com/jlowin) in [#1840](https://github.com/PrefectHQ/fastmcp/pull/1840)
+* Fix OAuth pre-flight check to accept HTTP 200 responses by [@jlowin](https://github.com/jlowin) in [#1874](https://github.com/PrefectHQ/fastmcp/pull/1874)
+* Fix: Preserve OpenAPI parameter descriptions in experimental parser by [@shlomo666](https://github.com/shlomo666) in [#1877](https://github.com/PrefectHQ/fastmcp/pull/1877)
+* Add persistent storage for OAuth client registrations by [@jlowin](https://github.com/jlowin) in [#1879](https://github.com/PrefectHQ/fastmcp/pull/1879)
+* docs: update release dates based on github releases by [@lodu](https://github.com/lodu) in [#1890](https://github.com/PrefectHQ/fastmcp/pull/1890)
+* Small updates to Sampling types by [@strawgate](https://github.com/strawgate) in [#1882](https://github.com/PrefectHQ/fastmcp/pull/1882)
+* remove lockfile smart_home example by [@zzstoatzz](https://github.com/zzstoatzz) in [#1892](https://github.com/PrefectHQ/fastmcp/pull/1892)
+* Fix: Remove JSON schema title metadata while preserving parameters named 'title' by [@jlowin](https://github.com/jlowin) in [#1872](https://github.com/PrefectHQ/fastmcp/pull/1872)
+* Fix: get_resource_url nested URL handling by [@raphael-linx](https://github.com/raphael-linx) in [#1914](https://github.com/PrefectHQ/fastmcp/pull/1914)
+* Clean up code for creating the resource url by [@jlowin](https://github.com/jlowin) in [#1916](https://github.com/PrefectHQ/fastmcp/pull/1916)
+* Fix route count logging in OpenAPI server by [@zzstoatzz](https://github.com/zzstoatzz) in [#1928](https://github.com/PrefectHQ/fastmcp/pull/1928)
+### Docs 📚
+* docs: make Gemini CLI integration discoverable by [@jackwotherspoon](https://github.com/jackwotherspoon) in [#1827](https://github.com/PrefectHQ/fastmcp/pull/1827)
+* docs: update NEW tags for AI assistant integrations by [@jackwotherspoon](https://github.com/jackwotherspoon) in [#1829](https://github.com/PrefectHQ/fastmcp/pull/1829)
+* Update wordmark by [@jlowin](https://github.com/jlowin) in [#1832](https://github.com/PrefectHQ/fastmcp/pull/1832)
+* docs: improve OAuth and OIDC Proxy documentation by [@jlowin](https://github.com/jlowin) in [#1880](https://github.com/PrefectHQ/fastmcp/pull/1880)
+* Update readme + welcome docs by [@jlowin](https://github.com/jlowin) in [#1883](https://github.com/PrefectHQ/fastmcp/pull/1883)
+* Update dark mode image in README by [@jlowin](https://github.com/jlowin) in [#1885](https://github.com/PrefectHQ/fastmcp/pull/1885)
+
+## New Contributors
+* [@radi-dev](https://github.com/radi-dev) made their first contribution in [#1821](https://github.com/PrefectHQ/fastmcp/pull/1821)
+* [@akkuman](https://github.com/akkuman) made their first contribution in [#1812](https://github.com/PrefectHQ/fastmcp/pull/1812)
+* [@ruhulio](https://github.com/ruhulio) made their first contribution in [#1817](https://github.com/PrefectHQ/fastmcp/pull/1817)
+* [@attiks](https://github.com/attiks) made their first contribution in [#1838](https://github.com/PrefectHQ/fastmcp/pull/1838)
+* [@anvibanga](https://github.com/anvibanga) made their first contribution in [#1853](https://github.com/PrefectHQ/fastmcp/pull/1853)
+* [@shlomo666](https://github.com/shlomo666) made their first contribution in [#1877](https://github.com/PrefectHQ/fastmcp/pull/1877)
+* [@lodu](https://github.com/lodu) made their first contribution in [#1890](https://github.com/PrefectHQ/fastmcp/pull/1890)
+* [@isijoe](https://github.com/isijoe) made their first contribution in [#1906](https://github.com/PrefectHQ/fastmcp/pull/1906)
+* [@raphael-linx](https://github.com/raphael-linx) made their first contribution in [#1914](https://github.com/PrefectHQ/fastmcp/pull/1914)
+* [@stephaneberle9](https://github.com/stephaneberle9) made their first contribution in [#1873](https://github.com/PrefectHQ/fastmcp/pull/1873)
+* [@cclauss](https://github.com/cclauss) made their first contribution in [#1922](https://github.com/PrefectHQ/fastmcp/pull/1922)
+
+**Full Changelog**: [v2.12.3...v2.12.4](https://github.com/PrefectHQ/fastmcp/compare/v2.12.3...v2.12.4)
+
+</Update>
+
+<Update label="v2.12.3" description="2025-09-17">
+
+**[v2.12.3: Double Time](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.3)**
+
+FastMCP 2.12.3 focuses on performance and developer experience improvements based on community feedback. This release includes optimized auth provider imports that reduce server startup time, enhanced OIDC authentication flows with proper token management, and several reliability fixes for OAuth proxy configurations. The addition of automatic inline snapshot creation significantly improves the testing experience for contributors.
+
+## What's Changed
+### New Features 🎉
+* feat: Support setting MCP log level via transport configuration by [@jlowin](https://github.com/jlowin) in [#1756](https://github.com/PrefectHQ/fastmcp/pull/1756)
+### Enhancements 🔧
+* Add client-side auth support for mcp install cursor command by [@jlowin](https://github.com/jlowin) in [#1747](https://github.com/PrefectHQ/fastmcp/pull/1747)
+* Automatically Create inline Snapshots by [@strawgate](https://github.com/strawgate) in [#1779](https://github.com/PrefectHQ/fastmcp/pull/1779)
+* Use lowercase namespace for fastmcp logger by [@jlowin](https://github.com/jlowin) in [#1791](https://github.com/PrefectHQ/fastmcp/pull/1791)
+### Fixes 🐞
+* fix: correct merge mistake during auth0 refactor by [@strawgate](https://github.com/strawgate) in [#1742](https://github.com/PrefectHQ/fastmcp/pull/1742)
+* Remove extraneous union import by [@jlowin](https://github.com/jlowin) in [#1823](https://github.com/PrefectHQ/fastmcp/pull/1823)
+* Delay import of Provider classes until FastMCP Server Creation by [@strawgate](https://github.com/strawgate) in [#1820](https://github.com/PrefectHQ/fastmcp/pull/1820)
+* fix: refactor OIDC configuration provider for proper token management by [@strawgate](https://github.com/strawgate) in [#1751](https://github.com/PrefectHQ/fastmcp/pull/1751)
+* Fix smart_home example imports by [@strawgate](https://github.com/strawgate) in [#1753](https://github.com/PrefectHQ/fastmcp/pull/1753)
+* fix: correct oauth proxy initialization of client by [@strawgate](https://github.com/strawgate) in [#1759](https://github.com/PrefectHQ/fastmcp/pull/1759)
+* Fix: return empty string when prompts have no arguments by [@jlowin](https://github.com/jlowin) in [#1766](https://github.com/PrefectHQ/fastmcp/pull/1766)
+* Fix async server callbacks by [@strawgate](https://github.com/strawgate) in [#1774](https://github.com/PrefectHQ/fastmcp/pull/1774)
+* Fix error when retrieving Completion API errors by [@strawgate](https://github.com/strawgate) in [#1785](https://github.com/PrefectHQ/fastmcp/pull/1785)
+* fix: correct documentation link in deprecation warning by [@strawgate](https://github.com/strawgate) in [#1828](https://github.com/PrefectHQ/fastmcp/pull/1828)
+### Docs 📚
+* Add migration docs for 2.12 by [@jlowin](https://github.com/jlowin) in [#1745](https://github.com/PrefectHQ/fastmcp/pull/1745)
+* Update docs for default sampling implementation to mention OpenAI API Key by [@strawgate](https://github.com/strawgate) in [#1763](https://github.com/PrefectHQ/fastmcp/pull/1763)
+* Add tip about sampling prompts and user_context to sampling documentation by [@jlowin](https://github.com/jlowin) in [#1764](https://github.com/PrefectHQ/fastmcp/pull/1764)
+* Update quickstart.mdx by [@radi-dev](https://github.com/radi-dev) in [#1821](https://github.com/PrefectHQ/fastmcp/pull/1821)
+### Other Changes 🦾
+* Replace Marvin with Claude Code in CI by [@jlowin](https://github.com/jlowin) in [#1800](https://github.com/PrefectHQ/fastmcp/pull/1800)
+* Refactor logging and structured logging middleware by [@strawgate](https://github.com/strawgate) in [#1805](https://github.com/PrefectHQ/fastmcp/pull/1805)
+* feat: Move the Starlette context middleware to the front by [@akkuman](https://github.com/akkuman) in [#1812](https://github.com/PrefectHQ/fastmcp/pull/1812)
+* feat: Add support for OIDC configuration by [@ruhulio](https://github.com/ruhulio) in [#1817](https://github.com/PrefectHQ/fastmcp/pull/1817)
+
+## New Contributors
+* [@radi-dev](https://github.com/radi-dev) made their first contribution in [#1821](https://github.com/PrefectHQ/fastmcp/pull/1821)
+* [@akkuman](https://github.com/akkuman) made their first contribution in [#1812](https://github.com/PrefectHQ/fastmcp/pull/1812)
+* [@ruhulio](https://github.com/ruhulio) made their first contribution in [#1817](https://github.com/PrefectHQ/fastmcp/pull/1817)
+
+**Full Changelog**: [v2.12.2...v2.12.3](https://github.com/PrefectHQ/fastmcp/compare/v2.12.2...v2.12.3)
+
+</Update>
+
+<Update label="v2.12.2" description="2025-09-03">
+
+**[v2.12.2: Perchance to Stream](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.2)**
+
+This is a hotfix for a bug where the `streamable-http` transport was not recognized as a valid option in `fastmcp.json` configuration files, despite being supported by the CLI. This resulted in a parsing error when the CLI arguments were merged against the configuration spec. 
+
+## What's Changed
+### Fixes 🐞
+* Fix streamable-http transport validation in fastmcp.json config by [@jlowin](https://github.com/jlowin) in [#1739](https://github.com/PrefectHQ/fastmcp/pull/1739)
+
+**Full Changelog**: [v2.12.1...v2.12.2](https://github.com/PrefectHQ/fastmcp/compare/v2.12.1...v2.12.2)
+
+</Update>
+
+<Update label="v2.12.1" description="2025-09-03">
+
+**[v2.12.1: OAuth to Joy](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.1)**
+
+FastMCP 2.12.1 strengthens the OAuth proxy implementation based on extensive community testing and feedback. This release improves client storage reliability, adds PKCE forwarding for enhanced security, introduces configurable token endpoint authentication methods, and expands scope handling—all addressing real-world integration challenges discovered since 2.12.0. The enhanced test suite with mock providers ensures these improvements are robust and maintainable.
+
+## Breaking Changes
+- **OAuth Proxy**: Users of built-in IDP integrations should note that `resource_server_url` has been renamed to `base_url` for clarity and consistency
+
+## What's Changed
+### Enhancements 🔧
+* Make openai dependency optional by [@jlowin](https://github.com/jlowin) in [#1701](https://github.com/PrefectHQ/fastmcp/pull/1701)
+* Remove orphaned OAuth proxy code by [@jlowin](https://github.com/jlowin) in [#1722](https://github.com/PrefectHQ/fastmcp/pull/1722)
+* Expose valid scopes from OAuthProxy metadata by [@dmikusa](https://github.com/dmikusa) in [#1717](https://github.com/PrefectHQ/fastmcp/pull/1717)
+* OAuth proxy PKCE forwarding by [@jlowin](https://github.com/jlowin) in [#1733](https://github.com/PrefectHQ/fastmcp/pull/1733)
+* Add token_endpoint_auth_method parameter to OAuthProxy by [@jlowin](https://github.com/jlowin) in [#1736](https://github.com/PrefectHQ/fastmcp/pull/1736)
+* Clean up and enhance OAuth proxy tests with mock provider by [@jlowin](https://github.com/jlowin) in [#1738](https://github.com/PrefectHQ/fastmcp/pull/1738)
+### Fixes 🐞
+* refactor: replace auth provider registry with ImportString by [@jlowin](https://github.com/jlowin) in [#1710](https://github.com/PrefectHQ/fastmcp/pull/1710)
+* Fix OAuth resource URL handling and WWW-Authenticate header by [@jlowin](https://github.com/jlowin) in [#1706](https://github.com/PrefectHQ/fastmcp/pull/1706)
+* Fix OAuth proxy client storage and add retry logic by [@jlowin](https://github.com/jlowin) in [#1732](https://github.com/PrefectHQ/fastmcp/pull/1732)
+### Docs 📚
+* Fix documentation: use StreamableHttpTransport for headers in testing by [@jlowin](https://github.com/jlowin) in [#1702](https://github.com/PrefectHQ/fastmcp/pull/1702)
+* docs: add performance warnings for mounted servers and proxies by [@strawgate](https://github.com/strawgate) in [#1669](https://github.com/PrefectHQ/fastmcp/pull/1669)
+* Update documentation around scopes for google by [@jlowin](https://github.com/jlowin) in [#1703](https://github.com/PrefectHQ/fastmcp/pull/1703)
+* Add deployment information to quickstart by [@seanpwlms](https://github.com/seanpwlms) in [#1433](https://github.com/PrefectHQ/fastmcp/pull/1433)
+* Update quickstart by [@jlowin](https://github.com/jlowin) in [#1728](https://github.com/PrefectHQ/fastmcp/pull/1728)
+* Add development docs for FastMCP by [@jlowin](https://github.com/jlowin) in [#1719](https://github.com/PrefectHQ/fastmcp/pull/1719)
+### Other Changes 🦾
+* Set generics without bounds to default=Any by [@strawgate](https://github.com/strawgate) in [#1648](https://github.com/PrefectHQ/fastmcp/pull/1648)
+
+## New Contributors
+* [@dmikusa](https://github.com/dmikusa) made their first contribution in [#1717](https://github.com/PrefectHQ/fastmcp/pull/1717)
+* [@seanpwlms](https://github.com/seanpwlms) made their first contribution in [#1433](https://github.com/PrefectHQ/fastmcp/pull/1433)
+
+**Full Changelog**: [v2.12.0...v2.12.1](https://github.com/PrefectHQ/fastmcp/compare/v2.12.0...v2.12.1)
+
+</Update>
+
+<Update label="v2.12.0" description="2025-08-31">
+
+**[v2.12.0: Auth to the Races](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.0)**
+
+FastMCP 2.12 represents one of our most significant releases to date, both in scope and community involvement. After extensive testing and iteration with the community, we're shipping major improvements to authentication, configuration, and MCP feature adoption.
+
+🔐 **OAuth Proxy for Broader Provider Support** addresses a fundamental challenge: while MCP requires Dynamic Client Registration (DCR), many popular OAuth providers don't support it. The new OAuth proxy bridges this gap, enabling FastMCP servers to authenticate with providers like GitHub, Google, WorkOS, and Azure through minimal configuration. These native integrations ship today, with more providers planned based on community needs.
+
+📋 **Declarative JSON Configuration** introduces a standardized, portable way to describe and deploy MCP servers. The `fastmcp.json` configuration file becomes the single source of truth for dependencies, transport settings, entrypoints, and server metadata. This foundation sets the stage for future capabilities like transformations and remote sources, moving toward a world where MCP servers are as portable and shareable as container images.
+
+🧠 **Sampling API Fallback** tackles the chicken-and-egg problem limiting adoption of advanced MCP features. Sampling—where servers request LLM completions from clients—is powerful but underutilized due to limited client support. FastMCP now lets server authors define fallback handlers that generate sampling completions server-side when clients don't support the feature, encouraging adoption while maintaining compatibility.
+
+This release took longer than usual to ship, and for good reason: the community's aggressive testing and feedback on the authentication system helped us reach a level of stability we're confident in. There's certainly more work ahead, but these foundations position FastMCP to handle increasingly complex use cases while remaining approachable for developers.
+
+Thank you to our new contributors and everyone who tested preview builds. Your feedback directly shaped these features.
+
+## What's Changed
+### New Features 🎉
+* Add OAuth proxy that allows authentication with social IDPs without DCR support by [@jlowin](https://github.com/jlowin) in [#1434](https://github.com/PrefectHQ/fastmcp/pull/1434)
+* feat: introduce declarative JSON configuration system by [@jlowin](https://github.com/jlowin) in [#1517](https://github.com/PrefectHQ/fastmcp/pull/1517)
+* ✨ Fallback to a Completions API when Sampling is not available by [@strawgate](https://github.com/strawgate) in [#1145](https://github.com/PrefectHQ/fastmcp/pull/1145)
+* Implement typed source system for FastMCP declarative configuration by [@jlowin](https://github.com/jlowin) in [#1607](https://github.com/PrefectHQ/fastmcp/pull/1607)
+### Enhancements 🔧
+* Support importing custom_route endpoints when mounting servers by [@jlowin](https://github.com/jlowin) in [#1470](https://github.com/PrefectHQ/fastmcp/pull/1470)
+* Remove unnecessary asserts by [@jlowin](https://github.com/jlowin) in [#1484](https://github.com/PrefectHQ/fastmcp/pull/1484)
+* Add Claude issue triage by [@jlowin](https://github.com/jlowin) in [#1510](https://github.com/PrefectHQ/fastmcp/pull/1510)
+* Inline dedupe prompt by [@jlowin](https://github.com/jlowin) in [#1512](https://github.com/PrefectHQ/fastmcp/pull/1512)
+* Improve stdio and mcp_config clean-up by [@strawgate](https://github.com/strawgate) in [#1444](https://github.com/PrefectHQ/fastmcp/pull/1444)
+* involve kwargs to pass parameters on creating RichHandler for logging customization. by [@itaru2622](https://github.com/itaru2622) in [#1504](https://github.com/PrefectHQ/fastmcp/pull/1504)
+* Move SDK docs generation to post-merge workflow by [@jlowin](https://github.com/jlowin) in [#1513](https://github.com/PrefectHQ/fastmcp/pull/1513)
+* Improve label triage guidance by [@jlowin](https://github.com/jlowin) in [#1516](https://github.com/PrefectHQ/fastmcp/pull/1516)
+* Add code review guidelines for agents by [@jlowin](https://github.com/jlowin) in [#1520](https://github.com/PrefectHQ/fastmcp/pull/1520)
+* Remove trailing slash in unit tests by [@jlowin](https://github.com/jlowin) in [#1535](https://github.com/PrefectHQ/fastmcp/pull/1535)
+* Update OAuth callback UI branding by [@jlowin](https://github.com/jlowin) in [#1536](https://github.com/PrefectHQ/fastmcp/pull/1536)
+* Fix Marvin workflow to support development tools by [@jlowin](https://github.com/jlowin) in [#1537](https://github.com/PrefectHQ/fastmcp/pull/1537)
+* Add mounted_components_raise_on_load_error setting for debugging by [@jlowin](https://github.com/jlowin) in [#1534](https://github.com/PrefectHQ/fastmcp/pull/1534)
+* feat: Add --workspace flag to fastmcp install cursor by [@jlowin](https://github.com/jlowin) in [#1522](https://github.com/PrefectHQ/fastmcp/pull/1522)
+* switch from `pyright` to `ty` by [@zzstoatzz](https://github.com/zzstoatzz) in [#1545](https://github.com/PrefectHQ/fastmcp/pull/1545)
+* feat: trigger Marvin workflow on PR body content by [@jlowin](https://github.com/jlowin) in [#1549](https://github.com/PrefectHQ/fastmcp/pull/1549)
+* Add WorkOS and Azure OAuth providers by [@jlowin](https://github.com/jlowin) in [#1550](https://github.com/PrefectHQ/fastmcp/pull/1550)
+* Adjust timeout for slow MCP Server shutdown test by [@strawgate](https://github.com/strawgate) in [#1561](https://github.com/PrefectHQ/fastmcp/pull/1561)
+* Update banner by [@jlowin](https://github.com/jlowin) in [#1567](https://github.com/PrefectHQ/fastmcp/pull/1567)
+* Added import of AuthProxy to auth __init__ by [@KaliszS](https://github.com/KaliszS) in [#1568](https://github.com/PrefectHQ/fastmcp/pull/1568)
+* Add configurable redirect URI validation for OAuth providers by [@jlowin](https://github.com/jlowin) in [#1582](https://github.com/PrefectHQ/fastmcp/pull/1582)
+* Remove invalid-argument-type ignore and fix type errors by [@jlowin](https://github.com/jlowin) in [#1588](https://github.com/PrefectHQ/fastmcp/pull/1588)
+* Remove generate-schema from public CLI by [@jlowin](https://github.com/jlowin) in [#1591](https://github.com/PrefectHQ/fastmcp/pull/1591)
+* Skip flaky windows test / mulit-client garbage collection by [@jlowin](https://github.com/jlowin) in [#1592](https://github.com/PrefectHQ/fastmcp/pull/1592)
+* Add setting to disable logging configuration by [@isra17](https://github.com/isra17) in [#1575](https://github.com/PrefectHQ/fastmcp/pull/1575)
+* Improve debug logging for nested Servers / Clients by [@strawgate](https://github.com/strawgate) in [#1604](https://github.com/PrefectHQ/fastmcp/pull/1604)
+* Add GitHub pull request template by [@strawgate](https://github.com/strawgate) in [#1581](https://github.com/PrefectHQ/fastmcp/pull/1581)
+* chore: Automate docs and schema updates via PRs by [@jlowin](https://github.com/jlowin) in [#1611](https://github.com/PrefectHQ/fastmcp/pull/1611)
+* Experiment with haiku for limited workflows by [@jlowin](https://github.com/jlowin) in [#1613](https://github.com/PrefectHQ/fastmcp/pull/1613)
+* feat: Improve GitHub workflow automation for schema and SDK docs by [@jlowin](https://github.com/jlowin) in [#1615](https://github.com/PrefectHQ/fastmcp/pull/1615)
+* Consolidate server loading logic into FileSystemSource by [@jlowin](https://github.com/jlowin) in [#1614](https://github.com/PrefectHQ/fastmcp/pull/1614)
+* Prevent Haiku Marvin from commenting when there are no duplicates by [@jlowin](https://github.com/jlowin) in [#1622](https://github.com/PrefectHQ/fastmcp/pull/1622)
+* chore: Add clarifying note to automated PR bodies by [@jlowin](https://github.com/jlowin) in [#1623](https://github.com/PrefectHQ/fastmcp/pull/1623)
+* feat: introduce inline snapshots by [@strawgate](https://github.com/strawgate) in [#1605](https://github.com/PrefectHQ/fastmcp/pull/1605)
+* Improve fastmcp.json environment configuration and project-based deployments by [@jlowin](https://github.com/jlowin) in [#1631](https://github.com/PrefectHQ/fastmcp/pull/1631)
+* fix: allow passing query params in OAuthProxy upstream authorization url by [@danb27](https://github.com/danb27) in [#1630](https://github.com/PrefectHQ/fastmcp/pull/1630)
+* Support multiple --with-editable flags in CLI commands by [@jlowin](https://github.com/jlowin) in [#1634](https://github.com/PrefectHQ/fastmcp/pull/1634)
+* feat: support comma separated oauth scopes by [@jlowin](https://github.com/jlowin) in [#1642](https://github.com/PrefectHQ/fastmcp/pull/1642)
+* Add allowed_client_redirect_uris to OAuth provider subclasses by [@jlowin](https://github.com/jlowin) in [#1662](https://github.com/PrefectHQ/fastmcp/pull/1662)
+* Consolidate CLI config parsing and prevent infinite loops by [@jlowin](https://github.com/jlowin) in [#1660](https://github.com/PrefectHQ/fastmcp/pull/1660)
+* Internal refactor: mcp server config by [@jlowin](https://github.com/jlowin) in [#1672](https://github.com/PrefectHQ/fastmcp/pull/1672)
+* Refactor Environment to support multiple runtime types by [@jlowin](https://github.com/jlowin) in [#1673](https://github.com/PrefectHQ/fastmcp/pull/1673)
+* Add type field to Environment base class by [@jlowin](https://github.com/jlowin) in [#1676](https://github.com/PrefectHQ/fastmcp/pull/1676)
+### Fixes 🐞
+* Fix breaking change: restore output_schema=False compatibility by [@jlowin](https://github.com/jlowin) in [#1482](https://github.com/PrefectHQ/fastmcp/pull/1482)
+* Fix #1506: Update tool filtering documentation from _meta to meta by [@maybenotconnor](https://github.com/maybenotconnor) in [#1511](https://github.com/PrefectHQ/fastmcp/pull/1511)
+* Fix pytest warnings by [@jlowin](https://github.com/jlowin) in [#1559](https://github.com/PrefectHQ/fastmcp/pull/1559)
+* nest schemas under assets by [@jlowin](https://github.com/jlowin) in [#1593](https://github.com/PrefectHQ/fastmcp/pull/1593)
+* Skip flaky windows test by [@jlowin](https://github.com/jlowin) in [#1596](https://github.com/PrefectHQ/fastmcp/pull/1596)
+* ACTUALLY move schemas to fastmcp.json by [@jlowin](https://github.com/jlowin) in [#1597](https://github.com/PrefectHQ/fastmcp/pull/1597)
+* Fix and centralize CLI path resolution by [@jlowin](https://github.com/jlowin) in [#1590](https://github.com/PrefectHQ/fastmcp/pull/1590)
+* Remove client info modifications by [@jlowin](https://github.com/jlowin) in [#1620](https://github.com/PrefectHQ/fastmcp/pull/1620)
+* Fix $defs being discarded in input schema of transformed tool by [@pldesch-chift](https://github.com/pldesch-chift) in [#1578](https://github.com/PrefectHQ/fastmcp/pull/1578)
+* Fix enum elicitation to use inline schemas for MCP compatibility by [@jlowin](https://github.com/jlowin) in [#1632](https://github.com/PrefectHQ/fastmcp/pull/1632)
+* Reuse session for `StdioTransport` in `Client.new` by [@strawgate](https://github.com/strawgate) in [#1635](https://github.com/PrefectHQ/fastmcp/pull/1635)
+* Feat: Configurable LoggingMiddleware payload serialization by [@vl-kp](https://github.com/vl-kp) in [#1636](https://github.com/PrefectHQ/fastmcp/pull/1636)
+* Fix OAuth redirect URI validation for DCR compatibility by [@jlowin](https://github.com/jlowin) in [#1661](https://github.com/PrefectHQ/fastmcp/pull/1661)
+* Add default scope handling in OAuth proxy by [@romanusyk](https://github.com/romanusyk) in [#1667](https://github.com/PrefectHQ/fastmcp/pull/1667)
+* Fix OAuth token expiry handling by [@jlowin](https://github.com/jlowin) in [#1671](https://github.com/PrefectHQ/fastmcp/pull/1671)
+* Add resource_server_url parameter to OAuth proxy providers by [@jlowin](https://github.com/jlowin) in [#1682](https://github.com/PrefectHQ/fastmcp/pull/1682)
+### Breaking Changes 🛫
+* Enhance inspect command with structured output and format options by [@jlowin](https://github.com/jlowin) in [#1481](https://github.com/PrefectHQ/fastmcp/pull/1481)
+### Docs 📚
+* Update changelog by [@jlowin](https://github.com/jlowin) in [#1453](https://github.com/PrefectHQ/fastmcp/pull/1453)
+* Update banner by [@jlowin](https://github.com/jlowin) in [#1472](https://github.com/PrefectHQ/fastmcp/pull/1472)
+* Update logo files by [@jlowin](https://github.com/jlowin) in [#1473](https://github.com/PrefectHQ/fastmcp/pull/1473)
+* Update deployment docs by [@jlowin](https://github.com/jlowin) in [#1486](https://github.com/PrefectHQ/fastmcp/pull/1486)
+* Update FastMCP Cloud screenshot by [@jlowin](https://github.com/jlowin) in [#1487](https://github.com/PrefectHQ/fastmcp/pull/1487)
+* Update authentication note in docs by [@jlowin](https://github.com/jlowin) in [#1488](https://github.com/PrefectHQ/fastmcp/pull/1488)
+* chore: Update installation.mdx version snippet by [@thomas-te](https://github.com/thomas-te) in [#1496](https://github.com/PrefectHQ/fastmcp/pull/1496)
+* Update fastmcp cloud server requirements by [@jlowin](https://github.com/jlowin) in [#1497](https://github.com/PrefectHQ/fastmcp/pull/1497)
+* Fix oauth pyright type checking by [@strawgate](https://github.com/strawgate) in [#1498](https://github.com/PrefectHQ/fastmcp/pull/1498)
+* docs: Fix type annotation in return value documentation by [@MaikelVeen](https://github.com/MaikelVeen) in [#1499](https://github.com/PrefectHQ/fastmcp/pull/1499)
+* Fix PromptMessage usage in docs example by [@jlowin](https://github.com/jlowin) in [#1515](https://github.com/PrefectHQ/fastmcp/pull/1515)
+* Create CODE_OF_CONDUCT.md by [@jlowin](https://github.com/jlowin) in [#1523](https://github.com/PrefectHQ/fastmcp/pull/1523)
+* Fixed wrong import path in new docs page by [@KaliszS](https://github.com/KaliszS) in [#1538](https://github.com/PrefectHQ/fastmcp/pull/1538)
+* Document symmetric key JWT verification support by [@jlowin](https://github.com/jlowin) in [#1586](https://github.com/PrefectHQ/fastmcp/pull/1586)
+* Update fastmcp.json schema path by [@jlowin](https://github.com/jlowin) in [#1595](https://github.com/PrefectHQ/fastmcp/pull/1595)
+### Dependencies 📦
+* Bump actions/create-github-app-token from 1 to 2 by [@dependabot](https://github.com/dependabot)[bot] in [#1436](https://github.com/PrefectHQ/fastmcp/pull/1436)
+* Bump astral-sh/setup-uv from 4 to 6 by [@dependabot](https://github.com/dependabot)[bot] in [#1532](https://github.com/PrefectHQ/fastmcp/pull/1532)
+* Bump actions/checkout from 4 to 5 by [@dependabot](https://github.com/dependabot)[bot] in [#1533](https://github.com/PrefectHQ/fastmcp/pull/1533)
+### Other Changes 🦾
+* Add dedupe workflow by [@jlowin](https://github.com/jlowin) in [#1454](https://github.com/PrefectHQ/fastmcp/pull/1454)
+* Update AGENTS.md by [@jlowin](https://github.com/jlowin) in [#1471](https://github.com/PrefectHQ/fastmcp/pull/1471)
+* Give Marvin the power of the Internet by [@strawgate](https://github.com/strawgate) in [#1475](https://github.com/PrefectHQ/fastmcp/pull/1475)
+* Update `just` error message for static checks by [@jlowin](https://github.com/jlowin) in [#1483](https://github.com/PrefectHQ/fastmcp/pull/1483)
+* Remove labeler by [@jlowin](https://github.com/jlowin) in [#1509](https://github.com/PrefectHQ/fastmcp/pull/1509)
+* update aproto server to handle rich links by [@zzstoatzz](https://github.com/zzstoatzz) in [#1556](https://github.com/PrefectHQ/fastmcp/pull/1556)
+* fix: enable triage bot for fork PRs using pull_request_target by [@jlowin](https://github.com/jlowin) in [#1557](https://github.com/PrefectHQ/fastmcp/pull/1557)
+
+## New Contributors
+* [@thomas-te](https://github.com/thomas-te) made their first contribution in [#1496](https://github.com/PrefectHQ/fastmcp/pull/1496)
+* [@maybenotconnor](https://github.com/maybenotconnor) made their first contribution in [#1511](https://github.com/PrefectHQ/fastmcp/pull/1511)
+* [@MaikelVeen](https://github.com/MaikelVeen) made their first contribution in [#1499](https://github.com/PrefectHQ/fastmcp/pull/1499)
+* [@KaliszS](https://github.com/KaliszS) made their first contribution in [#1538](https://github.com/PrefectHQ/fastmcp/pull/1538)
+* [@isra17](https://github.com/isra17) made their first contribution in [#1575](https://github.com/PrefectHQ/fastmcp/pull/1575)
+* [@marvin-context-protocol](https://github.com/marvin-context-protocol)[bot] made their first contribution in [#1616](https://github.com/PrefectHQ/fastmcp/pull/1616)
+* [@pldesch-chift](https://github.com/pldesch-chift) made their first contribution in [#1578](https://github.com/PrefectHQ/fastmcp/pull/1578)
+* [@vl-kp](https://github.com/vl-kp) made their first contribution in [#1636](https://github.com/PrefectHQ/fastmcp/pull/1636)
+* [@romanusyk](https://github.com/romanusyk) made their first contribution in [#1667](https://github.com/PrefectHQ/fastmcp/pull/1667)
+
+**Full Changelog**: [v2.11.3...v2.12.0](https://github.com/PrefectHQ/fastmcp/compare/v2.11.3...v2.12.0)
+
+</Update>
+
+<Update label="v2.11.3" description="2025-08-11">
+
+**[v2.11.3: API-tite for Change](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.11.3)**
+
+This release includes significant enhancements to the experimental OpenAPI parser and fixes a significant bug that led schemas not to be included in input/output schemas if they were transitive dependencies (e.g. A → B → C implies A depends on C). For users naively transforming large OpenAPI specs into MCP servers, this may result in ballooning payload sizes and necessitate curation.
+
+## What's Changed
+### Enhancements 🔧
+* Improve redirect handling to address 307's by [@jlowin](https://github.com/jlowin) in [#1387](https://github.com/PrefectHQ/fastmcp/pull/1387)
+* Ensure resource + template names are properly prefixed when importing/mounting by [@jlowin](https://github.com/jlowin) in [#1423](https://github.com/PrefectHQ/fastmcp/pull/1423)
+* fixes #1398: Add JWT claims to AccessToken by [@panargirakis](https://github.com/panargirakis) in [#1399](https://github.com/PrefectHQ/fastmcp/pull/1399)
+* Enable Protected Resource Metadata to provide resource_name and resou… by [@yannj-fr](https://github.com/yannj-fr) in [#1371](https://github.com/PrefectHQ/fastmcp/pull/1371)
+* Pin mcp SDK under 2.0 to avoid breaking changes by [@jlowin](https://github.com/jlowin) in [#1428](https://github.com/PrefectHQ/fastmcp/pull/1428)
+* Clean up complexity from PR #1426 by [@jlowin](https://github.com/jlowin) in [#1435](https://github.com/PrefectHQ/fastmcp/pull/1435)
+* Optimize OpenAPI payload size by 46% by [@jlowin](https://github.com/jlowin) in [#1452](https://github.com/PrefectHQ/fastmcp/pull/1452)
+* Update static checks by [@jlowin](https://github.com/jlowin) in [#1448](https://github.com/PrefectHQ/fastmcp/pull/1448)
+### Fixes 🐞
+* Fix client-side logging bug #1394 by [@chi2liu](https://github.com/chi2liu) in [#1397](https://github.com/PrefectHQ/fastmcp/pull/1397)
+* fix: Fix httpx_client_factory type annotation to match MCP SDK (#1402) by [@chi2liu](https://github.com/chi2liu) in [#1405](https://github.com/PrefectHQ/fastmcp/pull/1405)
+* Fix OpenAPI allOf handling at requestBody top level (#1378) by [@chi2liu](https://github.com/chi2liu) in [#1425](https://github.com/PrefectHQ/fastmcp/pull/1425)
+* Fix OpenAPI transitive references and performance (#1372) by [@jlowin](https://github.com/jlowin) in [#1426](https://github.com/PrefectHQ/fastmcp/pull/1426)
+* fix(type): lifespan is partially unknown by [@ykun9](https://github.com/ykun9) in [#1389](https://github.com/PrefectHQ/fastmcp/pull/1389)
+* Ensure transformed tools generate structured content by [@jlowin](https://github.com/jlowin) in [#1443](https://github.com/PrefectHQ/fastmcp/pull/1443)
+### Docs 📚
+* docs(client/logging): reflect corrected default log level mapping by [@jlowin](https://github.com/jlowin) in [#1403](https://github.com/PrefectHQ/fastmcp/pull/1403)
+* Add documentation for get_access_token() dependency function by [@jlowin](https://github.com/jlowin) in [#1446](https://github.com/PrefectHQ/fastmcp/pull/1446)
+### Other Changes 🦾
+* Add comprehensive tests for utilities.components module by [@chi2liu](https://github.com/chi2liu) in [#1395](https://github.com/PrefectHQ/fastmcp/pull/1395)
+* Consolidate agent instructions into AGENTS.md by [@jlowin](https://github.com/jlowin) in [#1404](https://github.com/PrefectHQ/fastmcp/pull/1404)
+* Fix performance test threshold to prevent flaky failures by [@jlowin](https://github.com/jlowin) in [#1406](https://github.com/PrefectHQ/fastmcp/pull/1406)
+* Update agents.md; add github instructions by [@jlowin](https://github.com/jlowin) in [#1410](https://github.com/PrefectHQ/fastmcp/pull/1410)
+* Add Marvin assistant by [@jlowin](https://github.com/jlowin) in [#1412](https://github.com/PrefectHQ/fastmcp/pull/1412)
+* Marvin: fix deprecated variable names by [@jlowin](https://github.com/jlowin) in [#1417](https://github.com/PrefectHQ/fastmcp/pull/1417)
+* Simplify action setup and add github tools for Marvin by [@jlowin](https://github.com/jlowin) in [#1419](https://github.com/PrefectHQ/fastmcp/pull/1419)
+* Update marvin workflow name by [@jlowin](https://github.com/jlowin) in [#1421](https://github.com/PrefectHQ/fastmcp/pull/1421)
+* Improve GitHub templates by [@jlowin](https://github.com/jlowin) in [#1422](https://github.com/PrefectHQ/fastmcp/pull/1422)
+
+## New Contributors
+* [@panargirakis](https://github.com/panargirakis) made their first contribution in [#1399](https://github.com/PrefectHQ/fastmcp/pull/1399)
+* [@ykun9](https://github.com/ykun9) made their first contribution in [#1389](https://github.com/PrefectHQ/fastmcp/pull/1389)
+* [@yannj-fr](https://github.com/yannj-fr) made their first contribution in [#1371](https://github.com/PrefectHQ/fastmcp/pull/1371)
+
+**Full Changelog**: [v2.11.2...v2.11.3](https://github.com/PrefectHQ/fastmcp/compare/v2.11.2...v2.11.3)
+
+</Update>
+
+<Update label="v2.11.2" description="2025-08-06">
+
+## [v2.11.2: Satis-factory](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.11.2)
+
+## What's Changed
+### Enhancements 🔧
+* Support factory functions in fastmcp run by [@jlowin](https://github.com/jlowin) in [#1384](https://github.com/PrefectHQ/fastmcp/pull/1384)
+* Add async support to client_factory in FastMCPProxy  (#1286) by [@bianning](https://github.com/bianning) in [#1375](https://github.com/PrefectHQ/fastmcp/pull/1375)
+### Fixes 🐞
+* Fix server_version field in inspect manifest by [@jlowin](https://github.com/jlowin) in [#1383](https://github.com/PrefectHQ/fastmcp/pull/1383)
+* Fix Settings field with both default and default_factory by [@jlowin](https://github.com/jlowin) in [#1380](https://github.com/PrefectHQ/fastmcp/pull/1380)
+### Other Changes 🦾
+* Remove unused arg by [@jlowin](https://github.com/jlowin) in [#1382](https://github.com/PrefectHQ/fastmcp/pull/1382)
+* Add remote auth provider tests by [@jlowin](https://github.com/jlowin) in [#1351](https://github.com/PrefectHQ/fastmcp/pull/1351)
+
+## New Contributors
+* [@bianning](https://github.com/bianning) made their first contribution in [#1375](https://github.com/PrefectHQ/fastmcp/pull/1375)
+
+**Full Changelog**: [v2.11.1...v2.11.2](https://github.com/PrefectHQ/fastmcp/compare/v2.11.1...v2.11.2)
+
+</Update>
+
+<Update label="v2.11.1" description="2025-08-04">
+
+## [v2.11.1: You're Better Auth Now](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.11.1)
+
+## What's Changed
+### New Features 🎉
+* Introduce `RemoteAuthProvider` for cleaner external identity provider integration, update docs by [@jlowin](https://github.com/jlowin) in [#1346](https://github.com/PrefectHQ/fastmcp/pull/1346)
+### Enhancements 🔧
+* perf: optimize string operations in OpenAPI parameter processing by [@chi2liu](https://github.com/chi2liu) in [#1342](https://github.com/PrefectHQ/fastmcp/pull/1342)
+### Fixes 🐞
+* Fix method-bound FunctionTool schemas by [@strawgate](https://github.com/strawgate) in [#1360](https://github.com/PrefectHQ/fastmcp/pull/1360)
+* Manually set `_key` after `model_copy()` to enable prefixing Transformed Tools by [@strawgate](https://github.com/strawgate) in [#1357](https://github.com/PrefectHQ/fastmcp/pull/1357)
+### Docs 📚
+* Docs updates by [@jlowin](https://github.com/jlowin) in [#1336](https://github.com/PrefectHQ/fastmcp/pull/1336)
+* Add 2.11 to changelog by [@jlowin](https://github.com/jlowin) in [#1337](https://github.com/PrefectHQ/fastmcp/pull/1337)
+* Update AuthKit vocab by [@jlowin](https://github.com/jlowin) in [#1338](https://github.com/PrefectHQ/fastmcp/pull/1338)
+* Fix typo in decorating-methods.mdx by [@Ozzuke](https://github.com/Ozzuke) in [#1344](https://github.com/PrefectHQ/fastmcp/pull/1344)
+
+## New Contributors
+* [@Ozzuke](https://github.com/Ozzuke) made their first contribution in [#1344](https://github.com/PrefectHQ/fastmcp/pull/1344)
+
+**Full Changelog**: [v2.11.0...v2.11.1](https://github.com/PrefectHQ/fastmcp/compare/v2.11.0...v2.11.1)
+
+</Update>
+
+<Update label="v2.11.0" description="2025-08-01">
+
+## [v2.11.0: Auth to a Good Start](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.11.0)
+
+FastMCP 2.11 doubles down on what developers need most: speed and simplicity. This massive release delivers significant performance improvements and a dramatically better developer experience.
+
+🔐 **Enterprise-Ready Authentication** brings comprehensive OAuth 2.1 support with WorkOS's AuthKit integration. The new AuthProvider interface leverages MCP's support for separate resource and authorization servers, handling API keys and remote authentication with Dynamic Client Registration. AuthKit integration means you can plug into existing enterprise identity systems without rebuilding your auth stack, setting the stage for plug-and-play auth that doesn't require users to become security experts overnight.
+
+⚡ The **Experimental OpenAPI Parser** delivers dramatic performance improvements through single-pass schema processing and optimized memory usage. OpenAPI integrations are now significantly faster, with cleaner, more maintainable code. _(Note: the experimental parser is disabled by default, set `FASTMCPEXPERIMENTALENABLENEWOPENAPIPARSER=1` to enable it. A message will be shown to all users on the legacy parser encouraging them to try the new one before it becomes the default.)_
+
+🧠 **Context State Management** finally gives you persistent state across tool calls with a simple dict interface, while enhanced meta support lets you expose rich component metadata to clients. Combined with improved type annotations, string-based argument descriptions, and UV transport support, this release makes FastMCP feel more intuitive than ever.
+
+This release represents a TON of community contributions and sets the foundation for even more ambitious features ahead.
+
+## What's Changed
+### New Features 🎉
+* Introduce experimental OpenAPI parser with improved performance and maintainability by [@jlowin](https://github.com/jlowin) in [#1209](https://github.com/PrefectHQ/fastmcp/pull/1209)
+* Add state dict to Context (#1118) by [@mukulmurthy](https://github.com/mukulmurthy) in [#1160](https://github.com/PrefectHQ/fastmcp/pull/1160)
+* Expose FastMCP tags to clients via component `meta` dict by [@jlowin](https://github.com/jlowin) in [#1281](https://github.com/PrefectHQ/fastmcp/pull/1281)
+* Add _fastmcp meta namespace by [@jlowin](https://github.com/jlowin) in [#1290](https://github.com/PrefectHQ/fastmcp/pull/1290)
+* Add TokenVerifier protocol support alongside existing OAuthProvider authentication by [@jlowin](https://github.com/jlowin) in [#1297](https://github.com/PrefectHQ/fastmcp/pull/1297)
+* Add comprehensive OAuth 2.1 authentication system with WorkOS integration by [@jlowin](https://github.com/jlowin) in [#1327](https://github.com/PrefectHQ/fastmcp/pull/1327)
+### Enhancements 🔧
+* [🐶] Transform MCP Server Tools by [@strawgate](https://github.com/strawgate) in [#1132](https://github.com/PrefectHQ/fastmcp/pull/1132)
+* Add --python, --project, and --with-requirements options to CLI commands by [@jlowin](https://github.com/jlowin) in [#1190](https://github.com/PrefectHQ/fastmcp/pull/1190)
+* Support `fastmcp run mcp.json` by [@strawgate](https://github.com/strawgate) in [#1138](https://github.com/PrefectHQ/fastmcp/pull/1138)
+* Support from __future__ import annotations by [@jlowin](https://github.com/jlowin) in [#1199](https://github.com/PrefectHQ/fastmcp/pull/1199)
+* Optimize OpenAPI parser performance with single-pass schema processing by [@jlowin](https://github.com/jlowin) in [#1214](https://github.com/PrefectHQ/fastmcp/pull/1214)
+* Log tool name on transform validation error by [@strawgate](https://github.com/strawgate) in [#1238](https://github.com/PrefectHQ/fastmcp/pull/1238)
+* Refactor `get_http_request` and `context.session_id` by [@hopeful0](https://github.com/hopeful0) in [#1242](https://github.com/PrefectHQ/fastmcp/pull/1242)
+* Support creating tool argument descriptions from string annotations by [@jlowin](https://github.com/jlowin) in [#1255](https://github.com/PrefectHQ/fastmcp/pull/1255)
+* feat: Add Annotations support for resources and resource templates by [@chughtapan](https://github.com/chughtapan) in [#1260](https://github.com/PrefectHQ/fastmcp/pull/1260)
+* Add UV Transport by [@strawgate](https://github.com/strawgate) in [#1270](https://github.com/PrefectHQ/fastmcp/pull/1270)
+* Improve OpenAPI-to-JSONSchema conversion utilities by [@jlowin](https://github.com/jlowin) in [#1283](https://github.com/PrefectHQ/fastmcp/pull/1283)
+* Ensure proxy components forward meta dicts by [@jlowin](https://github.com/jlowin) in [#1282](https://github.com/PrefectHQ/fastmcp/pull/1282)
+* fix: server argument passing in CLI run command by [@chughtapan](https://github.com/chughtapan) in [#1293](https://github.com/PrefectHQ/fastmcp/pull/1293)
+* Add meta support to tool transformation utilities by [@jlowin](https://github.com/jlowin) in [#1295](https://github.com/PrefectHQ/fastmcp/pull/1295)
+* feat: Allow Resource Metadata URL as field in OAuthProvider by [@dacamposol](https://github.com/dacamposol) in [#1287](https://github.com/PrefectHQ/fastmcp/pull/1287)
+* Use a simple overwrite instead of a merge for meta by [@jlowin](https://github.com/jlowin) in [#1296](https://github.com/PrefectHQ/fastmcp/pull/1296)
+* Remove unused TimedCache by [@strawgate](https://github.com/strawgate) in [#1303](https://github.com/PrefectHQ/fastmcp/pull/1303)
+* refactor: standardize logging usage across OpenAPI utilities by [@chi2liu](https://github.com/chi2liu) in [#1322](https://github.com/PrefectHQ/fastmcp/pull/1322)
+* perf: optimize OpenAPI parsing by reducing dict copy operations by [@chi2liu](https://github.com/chi2liu) in [#1321](https://github.com/PrefectHQ/fastmcp/pull/1321)
+* Structured client-side logging by [@cjermain](https://github.com/cjermain) in [#1326](https://github.com/PrefectHQ/fastmcp/pull/1326)
+### Fixes 🐞
+* fix: preserve def reference when referenced in allOf / oneOf / anyOf by [@algirdasci](https://github.com/algirdasci) in [#1208](https://github.com/PrefectHQ/fastmcp/pull/1208)
+* fix: add type hint to custom_route decorator by [@zzstoatzz](https://github.com/zzstoatzz) in [#1210](https://github.com/PrefectHQ/fastmcp/pull/1210)
+* chore: typo by [@richardkmichael](https://github.com/richardkmichael) in [#1216](https://github.com/PrefectHQ/fastmcp/pull/1216)
+* fix: handle non-string $ref values in experimental OpenAPI parser by [@jlowin](https://github.com/jlowin) in [#1217](https://github.com/PrefectHQ/fastmcp/pull/1217)
+* Skip repeated type conversion and validation in proxy client elicitation handler by [@chughtapan](https://github.com/chughtapan) in [#1222](https://github.com/PrefectHQ/fastmcp/pull/1222)
+* Ensure default fields are not marked nullable by [@jlowin](https://github.com/jlowin) in [#1224](https://github.com/PrefectHQ/fastmcp/pull/1224)
+* Fix stateful proxy client mixing in multi-proxies sessions by [@hopeful0](https://github.com/hopeful0) in [#1245](https://github.com/PrefectHQ/fastmcp/pull/1245)
+* Fix invalid async context manager usage in proxy documentation by [@zzstoatzz](https://github.com/zzstoatzz) in [#1246](https://github.com/PrefectHQ/fastmcp/pull/1246)
+* fix: experimental FastMCPOpenAPI server lost headers in request when __init__(client with headers) by [@itaru2622](https://github.com/itaru2622) in [#1254](https://github.com/PrefectHQ/fastmcp/pull/1254)
+* Fix typing, add tests for tool call middleware by [@jlowin](https://github.com/jlowin) in [#1269](https://github.com/PrefectHQ/fastmcp/pull/1269)
+* Fix: prune hidden parameter defs by [@muhammadkhalid-03](https://github.com/muhammadkhalid-03) in [#1257](https://github.com/PrefectHQ/fastmcp/pull/1257)
+* Fix nullable field handling in OpenAPI to JSON Schema conversion by [@jlowin](https://github.com/jlowin) in [#1279](https://github.com/PrefectHQ/fastmcp/pull/1279)
+* Ensure fastmcp run supports v1 servers by [@jlowin](https://github.com/jlowin) in [#1332](https://github.com/PrefectHQ/fastmcp/pull/1332)
+### Breaking Changes 🛫
+* Change server flag to --name by [@jlowin](https://github.com/jlowin) in [#1248](https://github.com/PrefectHQ/fastmcp/pull/1248)
+### Docs 📚
+* Remove unused import from FastAPI integration documentation by [@mariotaddeucci](https://github.com/mariotaddeucci) in [#1194](https://github.com/PrefectHQ/fastmcp/pull/1194)
+* Update fastapi docs by [@jlowin](https://github.com/jlowin) in [#1198](https://github.com/PrefectHQ/fastmcp/pull/1198)
+* Add docs for context state management by [@jlowin](https://github.com/jlowin) in [#1227](https://github.com/PrefectHQ/fastmcp/pull/1227)
+* Permit.io integration docs by [@orweis](https://github.com/orweis) in [#1226](https://github.com/PrefectHQ/fastmcp/pull/1226)
+* Update docs to reflect sync tools by [@jlowin](https://github.com/jlowin) in [#1234](https://github.com/PrefectHQ/fastmcp/pull/1234)
+* Update changelog.mdx by [@jlowin](https://github.com/jlowin) in [#1235](https://github.com/PrefectHQ/fastmcp/pull/1235)
+* Update SDK docs by [@jlowin](https://github.com/jlowin) in [#1236](https://github.com/PrefectHQ/fastmcp/pull/1236)
+* Update --name flag documentation for Cursor/Claude by [@adam-conway](https://github.com/adam-conway) in [#1239](https://github.com/PrefectHQ/fastmcp/pull/1239)
+* Add annotations docs by [@jlowin](https://github.com/jlowin) in [#1268](https://github.com/PrefectHQ/fastmcp/pull/1268)
+* Update openapi/fastapi URLs README.md by [@jbn](https://github.com/jbn) in [#1278](https://github.com/PrefectHQ/fastmcp/pull/1278)
+* Add 2.11 version badge for state management by [@jlowin](https://github.com/jlowin) in [#1289](https://github.com/PrefectHQ/fastmcp/pull/1289)
+* Add meta parameter support to tools, resources, templates, and prompts decorators by [@jlowin](https://github.com/jlowin) in [#1294](https://github.com/PrefectHQ/fastmcp/pull/1294)
+* docs: update get_state and set_state references by [@Maxi91f](https://github.com/Maxi91f) in [#1306](https://github.com/PrefectHQ/fastmcp/pull/1306)
+* Add unit tests and docs for denying tool calls with middleware by [@jlowin](https://github.com/jlowin) in [#1333](https://github.com/PrefectHQ/fastmcp/pull/1333)
+* Remove reference to stacked decorators by [@jlowin](https://github.com/jlowin) in [#1334](https://github.com/PrefectHQ/fastmcp/pull/1334)
+* Eunomia authorization server can run embedded within the MCP server by [@tommitt](https://github.com/tommitt) in [#1317](https://github.com/PrefectHQ/fastmcp/pull/1317)
+### Other Changes 🦾
+* Update README.md by [@jlowin](https://github.com/jlowin) in [#1230](https://github.com/PrefectHQ/fastmcp/pull/1230)
+* Logcapture addition to test_server file by [@Sourav-Tripathy](https://github.com/Sourav-Tripathy) in [#1229](https://github.com/PrefectHQ/fastmcp/pull/1229)
+* Add tests for headers with both legacy and experimental openapi parser by [@jlowin](https://github.com/jlowin) in [#1259](https://github.com/PrefectHQ/fastmcp/pull/1259)
+* Small clean-up from MCP Tool Transform PR by [@strawgate](https://github.com/strawgate) in [#1267](https://github.com/PrefectHQ/fastmcp/pull/1267)
+* Add test for proxy tags visibility by [@jlowin](https://github.com/jlowin) in [#1302](https://github.com/PrefectHQ/fastmcp/pull/1302)
+* Add unit test for sampling with image messages by [@jlowin](https://github.com/jlowin) in [#1329](https://github.com/PrefectHQ/fastmcp/pull/1329)
+* Remove redundant resource_metadata_url assignment by [@jlowin](https://github.com/jlowin) in [#1328](https://github.com/PrefectHQ/fastmcp/pull/1328)
+* Update bug.yml by [@jlowin](https://github.com/jlowin) in [#1331](https://github.com/PrefectHQ/fastmcp/pull/1331)
+* Ensure validation errors are raised when masked by [@jlowin](https://github.com/jlowin) in [#1330](https://github.com/PrefectHQ/fastmcp/pull/1330)
+
+## New Contributors
+* [@mariotaddeucci](https://github.com/mariotaddeucci) made their first contribution in [#1194](https://github.com/PrefectHQ/fastmcp/pull/1194)
+* [@algirdasci](https://github.com/algirdasci) made their first contribution in [#1208](https://github.com/PrefectHQ/fastmcp/pull/1208)
+* [@chughtapan](https://github.com/chughtapan) made their first contribution in [#1222](https://github.com/PrefectHQ/fastmcp/pull/1222)
+* [@mukulmurthy](https://github.com/mukulmurthy) made their first contribution in [#1160](https://github.com/PrefectHQ/fastmcp/pull/1160)
+* [@orweis](https://github.com/orweis) made their first contribution in [#1226](https://github.com/PrefectHQ/fastmcp/pull/1226)
+* [@Sourav-Tripathy](https://github.com/Sourav-Tripathy) made their first contribution in [#1229](https://github.com/PrefectHQ/fastmcp/pull/1229)
+* [@adam-conway](https://github.com/adam-conway) made their first contribution in [#1239](https://github.com/PrefectHQ/fastmcp/pull/1239)
+* [@muhammadkhalid-03](https://github.com/muhammadkhalid-03) made their first contribution in [#1257](https://github.com/PrefectHQ/fastmcp/pull/1257)
+* [@jbn](https://github.com/jbn) made their first contribution in [#1278](https://github.com/PrefectHQ/fastmcp/pull/1278)
+* [@dacamposol](https://github.com/dacamposol) made their first contribution in [#1287](https://github.com/PrefectHQ/fastmcp/pull/1287)
+* [@chi2liu](https://github.com/chi2liu) made their first contribution in [#1322](https://github.com/PrefectHQ/fastmcp/pull/1322)
+* [@cjermain](https://github.com/cjermain) made their first contribution in [#1326](https://github.com/PrefectHQ/fastmcp/pull/1326)
+
+**Full Changelog**: [v2.10.6...v2.11.0](https://github.com/PrefectHQ/fastmcp/compare/v2.10.6...v2.11.0)
+
+</Update>
+
+<Update label="v2.10.6" description="2025-07-19">
+
+## [v2.10.6: Hymn for the Weekend](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.6)
+
+A special Saturday release with many fixes.
+
+## What's Changed
+### Enhancements 🔧
+* Resolve #1139 -- Implement include_context argument in Context.sample by [@codingjoe](https://github.com/codingjoe) in [#1141](https://github.com/PrefectHQ/fastmcp/pull/1141)
+* feat(settings): add log level normalization by [@ka2048](https://github.com/ka2048) in [#1171](https://github.com/PrefectHQ/fastmcp/pull/1171)
+* add server name to mounted server warnings by [@artificial-aidan](https://github.com/artificial-aidan) in [#1147](https://github.com/PrefectHQ/fastmcp/pull/1147)
+* Add StatefulProxyClient by [@hopeful0](https://github.com/hopeful0) in [#1109](https://github.com/PrefectHQ/fastmcp/pull/1109)
+### Fixes 🐞
+* Fix OpenAPI empty parameters by [@FabrizioSandri](https://github.com/FabrizioSandri) in [#1128](https://github.com/PrefectHQ/fastmcp/pull/1128)
+* Fix title field preservation in tool transformations by [@jlowin](https://github.com/jlowin) in [#1131](https://github.com/PrefectHQ/fastmcp/pull/1131)
+* Fix optional parameter validation in OpenAPI integration by [@jlowin](https://github.com/jlowin) in [#1135](https://github.com/PrefectHQ/fastmcp/pull/1135)
+* Do not silently exclude the "context" key from JSON body by [@melkamar](https://github.com/melkamar) in [#1153](https://github.com/PrefectHQ/fastmcp/pull/1153)
+* Fix tool output schema generation to respect Pydantic serialization aliases by [@zzstoatzz](https://github.com/zzstoatzz) in [#1148](https://github.com/PrefectHQ/fastmcp/pull/1148)
+* fix: _replace_ref_with_defs; ensure ref_path is string by [@itaru2622](https://github.com/itaru2622) in [#1164](https://github.com/PrefectHQ/fastmcp/pull/1164)
+* Fix nesting when making OpenAPI arrays and objects optional by [@melkamar](https://github.com/melkamar) in [#1178](https://github.com/PrefectHQ/fastmcp/pull/1178)
+* Fix `mcp-json` output format to include server name by [@jlowin](https://github.com/jlowin) in [#1185](https://github.com/PrefectHQ/fastmcp/pull/1185)
+* Only configure logging one time by [@jlowin](https://github.com/jlowin) in [#1187](https://github.com/PrefectHQ/fastmcp/pull/1187)
+### Docs 📚
+* Update changelog.mdx by [@jlowin](https://github.com/jlowin) in [#1127](https://github.com/PrefectHQ/fastmcp/pull/1127)
+* Eunomia Authorization with native FastMCP's Middleware by [@tommitt](https://github.com/tommitt) in [#1144](https://github.com/PrefectHQ/fastmcp/pull/1144)
+* update api ref for new `mdxify` version by [@zzstoatzz](https://github.com/zzstoatzz) in [#1182](https://github.com/PrefectHQ/fastmcp/pull/1182)
+### Other Changes 🦾
+* Expand empty parameter filtering and add comprehensive tests by [@jlowin](https://github.com/jlowin) in [#1129](https://github.com/PrefectHQ/fastmcp/pull/1129)
+* Add no-commit-to-branch hook by [@zzstoatzz](https://github.com/zzstoatzz) in [#1149](https://github.com/PrefectHQ/fastmcp/pull/1149)
+* Update README.md by [@jlowin](https://github.com/jlowin) in [#1165](https://github.com/PrefectHQ/fastmcp/pull/1165)
+* skip on rate limit by [@zzstoatzz](https://github.com/zzstoatzz) in [#1183](https://github.com/PrefectHQ/fastmcp/pull/1183)
+* Remove deprecated proxy creation by [@jlowin](https://github.com/jlowin) in [#1186](https://github.com/PrefectHQ/fastmcp/pull/1186)
+* Separate integration tests from unit tests in CI by [@jlowin](https://github.com/jlowin) in [#1188](https://github.com/PrefectHQ/fastmcp/pull/1188)
+
+## New Contributors
+* [@FabrizioSandri](https://github.com/FabrizioSandri) made their first contribution in [#1128](https://github.com/PrefectHQ/fastmcp/pull/1128)
+* [@melkamar](https://github.com/melkamar) made their first contribution in [#1153](https://github.com/PrefectHQ/fastmcp/pull/1153)
+* [@codingjoe](https://github.com/codingjoe) made their first contribution in [#1141](https://github.com/PrefectHQ/fastmcp/pull/1141)
+* [@itaru2622](https://github.com/itaru2622) made their first contribution in [#1164](https://github.com/PrefectHQ/fastmcp/pull/1164)
+* [@ka2048](https://github.com/ka2048) made their first contribution in [#1171](https://github.com/PrefectHQ/fastmcp/pull/1171)
+* [@artificial-aidan](https://github.com/artificial-aidan) made their first contribution in [#1147](https://github.com/PrefectHQ/fastmcp/pull/1147)
+
+**Full Changelog**: [v2.10.5...v2.10.6](https://github.com/PrefectHQ/fastmcp/compare/v2.10.5...v2.10.6)
+
+</Update>
+
+<Update label="v2.10.5" description="2025-07-11">
+
+## [v2.10.5: Middle Management](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.5)
+
+A maintenance release focused on OpenAPI refinements and middleware fixes, plus console improvements.
+
+## What's Changed
+### Enhancements 🔧
+* Fix Claude Code CLI detection for npm global installations by [@jlowin](https://github.com/jlowin) in [#1106](https://github.com/PrefectHQ/fastmcp/pull/1106)
+* Fix OpenAPI parameter name collisions with location suffixing by [@jlowin](https://github.com/jlowin) in [#1107](https://github.com/PrefectHQ/fastmcp/pull/1107)
+* Add mirrored component support for proxy servers by [@jlowin](https://github.com/jlowin) in [#1105](https://github.com/PrefectHQ/fastmcp/pull/1105)
+### Fixes 🐞
+* Fix OpenAPI deepObject style parameter encoding by [@jlowin](https://github.com/jlowin) in [#1122](https://github.com/PrefectHQ/fastmcp/pull/1122)
+* xfail when github token is not set ('' or None) by [@jlowin](https://github.com/jlowin) in [#1123](https://github.com/PrefectHQ/fastmcp/pull/1123)
+* fix: replace oneOf with anyOf in OpenAPI output schemas by [@MagnusS0](https://github.com/MagnusS0) in [#1119](https://github.com/PrefectHQ/fastmcp/pull/1119)
+* Fix middleware list result types by [@jlowin](https://github.com/jlowin) in [#1125](https://github.com/PrefectHQ/fastmcp/pull/1125)
+* Improve console width for logo by [@jlowin](https://github.com/jlowin) in [#1126](https://github.com/PrefectHQ/fastmcp/pull/1126)
+### Docs 📚
+* Improve transport + integration docs by [@jlowin](https://github.com/jlowin) in [#1103](https://github.com/PrefectHQ/fastmcp/pull/1103)
+* Update proxy.mdx by [@coldfire-x](https://github.com/coldfire-x) in [#1108](https://github.com/PrefectHQ/fastmcp/pull/1108)
+### Other Changes 🦾
+* Update github remote server tests with secret by [@jlowin](https://github.com/jlowin) in [#1112](https://github.com/PrefectHQ/fastmcp/pull/1112)
+
+## New Contributors
+* [@coldfire-x](https://github.com/coldfire-x) made their first contribution in [#1108](https://github.com/PrefectHQ/fastmcp/pull/1108)
+* [@MagnusS0](https://github.com/MagnusS0) made their first contribution in [#1119](https://github.com/PrefectHQ/fastmcp/pull/1119)
+
+**Full Changelog**: [v2.10.4...v2.10.5](https://github.com/PrefectHQ/fastmcp/compare/v2.10.4...v2.10.5)
+
+</Update>
+
+<Update label="v2.10.4" description="2025-07-09">
+
+## [v2.10.4: Transport-ation](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.4)
+
+A quick fix to ensure the CLI accepts "streamable-http" as a valid transport option.
+
+## What's Changed
+### Fixes 🐞
+* Ensure the CLI accepts "streamable-http" as a valid transport by [@jlowin](https://github.com/jlowin) in [#1099](https://github.com/PrefectHQ/fastmcp/pull/1099)
+
+**Full Changelog**: [v2.10.3...v2.10.4](https://github.com/PrefectHQ/fastmcp/compare/v2.10.3...v2.10.4)
+
+</Update>
+
+<Update label="v2.10.3" description="2025-07-09">
+
+## [v2.10.3: CLI Me a River](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.3)
+
+A major CLI overhaul featuring a complete refactor from typer to cyclopts, new IDE integrations, and comprehensive OpenAPI improvements.
+
+## What's Changed
+### New Features 🎉
+* Refactor CLI from typer to cyclopts and add comprehensive tests by [@jlowin](https://github.com/jlowin) in [#1062](https://github.com/PrefectHQ/fastmcp/pull/1062)
+* Add output schema support for OpenAPI tools by [@jlowin](https://github.com/jlowin) in [#1073](https://github.com/PrefectHQ/fastmcp/pull/1073)
+### Enhancements 🔧
+* Add Cursor support via CLI integration by [@jlowin](https://github.com/jlowin) in [#1052](https://github.com/PrefectHQ/fastmcp/pull/1052)
+* Add Claude Code install integration by [@jlowin](https://github.com/jlowin) in [#1053](https://github.com/PrefectHQ/fastmcp/pull/1053)
+* Generate MCP JSON config output from CLI as new `fastmcp install` command by [@jlowin](https://github.com/jlowin) in [#1056](https://github.com/PrefectHQ/fastmcp/pull/1056)
+* Use isawaitable instead of iscoroutine by [@jlowin](https://github.com/jlowin) in [#1059](https://github.com/PrefectHQ/fastmcp/pull/1059)
+* feat: Add `--path` Option to CLI for HTTP/SSE Route by [@davidbk-legit](https://github.com/davidbk-legit) in [#1087](https://github.com/PrefectHQ/fastmcp/pull/1087)
+* Fix concurrent proxy client operations with session isolation by [@jlowin](https://github.com/jlowin) in [#1083](https://github.com/PrefectHQ/fastmcp/pull/1083)
+### Fixes 🐞
+* Refactor Client context management to avoid concurrency issue by [@hopeful0](https://github.com/hopeful0) in [#1054](https://github.com/PrefectHQ/fastmcp/pull/1054)
+* Keep json schema $defs on transform by [@strawgate](https://github.com/strawgate) in [#1066](https://github.com/PrefectHQ/fastmcp/pull/1066)
+* Ensure fastmcp version copy is plaintext by [@jlowin](https://github.com/jlowin) in [#1071](https://github.com/PrefectHQ/fastmcp/pull/1071)
+* Fix single-element list unwrapping in tool content by [@jlowin](https://github.com/jlowin) in [#1074](https://github.com/PrefectHQ/fastmcp/pull/1074)
+* Fix max recursion error when pruning OpenAPI definitions by [@dimitribarbot](https://github.com/dimitribarbot) in [#1092](https://github.com/PrefectHQ/fastmcp/pull/1092)
+* Fix OpenAPI tool name registration when modified by mcp_component_fn by [@jlowin](https://github.com/jlowin) in [#1096](https://github.com/PrefectHQ/fastmcp/pull/1096)
+### Docs 📚
+* Docs: add example of more concise way to use bearer auth by [@neilconway](https://github.com/neilconway) in [#1055](https://github.com/PrefectHQ/fastmcp/pull/1055)
+* Update favicon by [@jlowin](https://github.com/jlowin) in [#1058](https://github.com/PrefectHQ/fastmcp/pull/1058)
+* Update environment note by [@jlowin](https://github.com/jlowin) in [#1075](https://github.com/PrefectHQ/fastmcp/pull/1075)
+* Add fastmcp version --copy documentation by [@jlowin](https://github.com/jlowin) in [#1076](https://github.com/PrefectHQ/fastmcp/pull/1076)
+### Other Changes 🦾
+* Remove asserts and add documentation following #1054 by [@jlowin](https://github.com/jlowin) in [#1057](https://github.com/PrefectHQ/fastmcp/pull/1057)
+* Add --copy flag for fastmcp version by [@jlowin](https://github.com/jlowin) in [#1063](https://github.com/PrefectHQ/fastmcp/pull/1063)
+* Fix docstring format for fastmcp.client.Client by [@neilconway](https://github.com/neilconway) in [#1094](https://github.com/PrefectHQ/fastmcp/pull/1094)
+
+## New Contributors
+* [@neilconway](https://github.com/neilconway) made their first contribution in [#1055](https://github.com/PrefectHQ/fastmcp/pull/1055)
+* [@davidbk-legit](https://github.com/davidbk-legit) made their first contribution in [#1087](https://github.com/PrefectHQ/fastmcp/pull/1087)
+* [@dimitribarbot](https://github.com/dimitribarbot) made their first contribution in [#1092](https://github.com/PrefectHQ/fastmcp/pull/1092)
+
+**Full Changelog**: [v2.10.2...v2.10.3](https://github.com/PrefectHQ/fastmcp/compare/v2.10.2...v2.10.3)
+
+</Update>
+
+<Update label="v2.10.2" description="2025-07-05">
+
+## [v2.10.2: Forward March](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.2)
+
+The headline feature of this release is the ability to "forward" advanced MCP interactions like logging, progress, and elicitation through proxy servers. If the remote server requests an elicitation, the proxy client will pass that request to the new, "ultimate" client.
+
+## What's Changed
+### New Features 🎉
+* Proxy support advanced MCP features by [@hopeful0](https://github.com/hopeful0) in [#1022](https://github.com/PrefectHQ/fastmcp/pull/1022)
+### Enhancements 🔧
+* Re-add splash screen by [@jlowin](https://github.com/jlowin) in [#1027](https://github.com/PrefectHQ/fastmcp/pull/1027)
+* Reduce banner padding by [@jlowin](https://github.com/jlowin) in [#1030](https://github.com/PrefectHQ/fastmcp/pull/1030)
+* Allow per-server timeouts in MCPConfig by [@cegersdoerfer](https://github.com/cegersdoerfer) in [#1031](https://github.com/PrefectHQ/fastmcp/pull/1031)
+* Support 'scp' claim for OAuth scopes in BearerAuthProvider by [@jlowin](https://github.com/jlowin) in [#1033](https://github.com/PrefectHQ/fastmcp/pull/1033)
+* Add path expansion to image/audio/file by [@jlowin](https://github.com/jlowin) in [#1038](https://github.com/PrefectHQ/fastmcp/pull/1038)
+* Ensure multi-client configurations use new ProxyClient by [@jlowin](https://github.com/jlowin) in [#1045](https://github.com/PrefectHQ/fastmcp/pull/1045)
+### Fixes 🐞
+* Expose stateless_http kwarg for mcp.run() by [@jlowin](https://github.com/jlowin) in [#1018](https://github.com/PrefectHQ/fastmcp/pull/1018)
+* Avoid propagating logs by [@jlowin](https://github.com/jlowin) in [#1042](https://github.com/PrefectHQ/fastmcp/pull/1042)
+### Docs 📚
+* Clean up docs by [@jlowin](https://github.com/jlowin) in [#1028](https://github.com/PrefectHQ/fastmcp/pull/1028)
+* Docs: clarify server URL paths for ChatGPT integration by [@thap2331](https://github.com/thap2331) in [#1017](https://github.com/PrefectHQ/fastmcp/pull/1017)
+### Other Changes 🦾
+* Split giant openapi test file into smaller files by [@jlowin](https://github.com/jlowin) in [#1034](https://github.com/PrefectHQ/fastmcp/pull/1034)
+* Add comprehensive OpenAPI 3.0 vs 3.1 compatibility tests by [@jlowin](https://github.com/jlowin) in [#1035](https://github.com/PrefectHQ/fastmcp/pull/1035)
+* Update banner and use console.log by [@jlowin](https://github.com/jlowin) in [#1041](https://github.com/PrefectHQ/fastmcp/pull/1041)
+
+## New Contributors
+* [@cegersdoerfer](https://github.com/cegersdoerfer) made their first contribution in [#1031](https://github.com/PrefectHQ/fastmcp/pull/1031)
+* [@hopeful0](https://github.com/hopeful0) made their first contribution in [#1022](https://github.com/PrefectHQ/fastmcp/pull/1022)
+* [@thap2331](https://github.com/thap2331) made their first contribution in [#1017](https://github.com/PrefectHQ/fastmcp/pull/1017)
+
+**Full Changelog**: [v2.10.1...v2.10.2](https://github.com/PrefectHQ/fastmcp/compare/v2.10.1...v2.10.2)
+
+</Update>
+
+<Update label="v2.10.1" description="2025-07-02">
+
+## [v2.10.1: Revert to Sender](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.1)
+
+A quick patch to revert the CLI banner that was added in v2.10.0.
+
+## What's Changed
+### Docs 📚
+* Update changelog.mdx by [@jlowin](https://github.com/jlowin) in [#1009](https://github.com/PrefectHQ/fastmcp/pull/1009)
+* Revert "Add CLI banner" by [@jlowin](https://github.com/jlowin) in [#1011](https://github.com/PrefectHQ/fastmcp/pull/1011)
+
+**Full Changelog**: [v2.10.0...v2.10.1](https://github.com/PrefectHQ/fastmcp/compare/v2.10.0...v2.10.1)
+
+</Update>
+
+<Update label="v2.10.0" description="2024-07-01">
+
+## [v2.10.0: Great Spec-tations](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.0)
+
+FastMCP 2.10 brings full compliance with the 6/18/2025 MCP spec update, introducing elicitation support for dynamic server-client communication and output schemas for structured tool responses. Please note that due to these changes, this release also includes a breaking change to the return signature of `client.call_tool()`.
+
+### Elicitation Support
+Elicitation allows MCP servers to request additional information from clients during tool execution, enabling more interactive and dynamic server behavior. This opens up new possibilities for tools that need user input or confirmation during execution.
+
+### Output Schemas
+Tools can now define structured output schemas, ensuring that responses conform to expected formats and making tool integration more predictable and type-safe.
+
+## What's Changed
+### New Features 🎉
+* MCP 6/18/25: Add output schema to tools by [@jlowin](https://github.com/jlowin) in [#901](https://github.com/PrefectHQ/fastmcp/pull/901)
+* MCP 6/18/25: Elicitation support by [@jlowin](https://github.com/jlowin) in [#889](https://github.com/PrefectHQ/fastmcp/pull/889)
+### Enhancements 🔧
+* Update types + tests for SDK changes by [@jlowin](https://github.com/jlowin) in [#888](https://github.com/PrefectHQ/fastmcp/pull/888)
+* MCP 6/18/25: Update auth primitives by [@jlowin](https://github.com/jlowin) in [#966](https://github.com/PrefectHQ/fastmcp/pull/966)
+* Add OpenAPI extensions support to HTTPRoute by [@maddymanu](https://github.com/maddymanu) in [#977](https://github.com/PrefectHQ/fastmcp/pull/977)
+* Add title field support to FastMCP components by [@jlowin](https://github.com/jlowin) in [#982](https://github.com/PrefectHQ/fastmcp/pull/982)
+* Support implicit Elicitation acceptance by [@jlowin](https://github.com/jlowin) in [#983](https://github.com/PrefectHQ/fastmcp/pull/983)
+* Support 'no response' elicitation requests by [@jlowin](https://github.com/jlowin) in [#992](https://github.com/PrefectHQ/fastmcp/pull/992)
+* Add Support for Configurable Algorithms by [@sstene1](https://github.com/sstene1) in [#997](https://github.com/PrefectHQ/fastmcp/pull/997)
+### Fixes 🐞
+* Improve stdio error handling to raise connection failures immediately by [@jlowin](https://github.com/jlowin) in [#984](https://github.com/PrefectHQ/fastmcp/pull/984)
+* Fix type hints for FunctionResource:fn by [@CfirTsabari](https://github.com/CfirTsabari) in [#986](https://github.com/PrefectHQ/fastmcp/pull/986)
+* Update link to OpenAI MCP example by [@mossbanay](https://github.com/mossbanay) in [#985](https://github.com/PrefectHQ/fastmcp/pull/985)
+* Fix output schema generation edge case by [@jlowin](https://github.com/jlowin) in [#995](https://github.com/PrefectHQ/fastmcp/pull/995)
+* Refactor array parameter formatting to reduce code duplication by [@jlowin](https://github.com/jlowin) in [#1007](https://github.com/PrefectHQ/fastmcp/pull/1007)
+* Fix OpenAPI array parameter explode handling by [@jlowin](https://github.com/jlowin) in [#1008](https://github.com/PrefectHQ/fastmcp/pull/1008)
+### Breaking Changes 🛫
+* MCP 6/18/25: Upgrade to mcp 1.10 by [@jlowin](https://github.com/jlowin) in [#887](https://github.com/PrefectHQ/fastmcp/pull/887)
+### Docs 📚
+* Update middleware imports and documentation by [@jlowin](https://github.com/jlowin) in [#999](https://github.com/PrefectHQ/fastmcp/pull/999)
+* Update OpenAI docs by [@jlowin](https://github.com/jlowin) in [#1001](https://github.com/PrefectHQ/fastmcp/pull/1001)
+* Add CLI banner by [@jlowin](https://github.com/jlowin) in [#1005](https://github.com/PrefectHQ/fastmcp/pull/1005)
+### Examples & Contrib 💡
+* Component Manager by [@gorocode](https://github.com/gorocode) in [#976](https://github.com/PrefectHQ/fastmcp/pull/976)
+### Other Changes 🦾
+* Minor auth improvements by [@jlowin](https://github.com/jlowin) in [#967](https://github.com/PrefectHQ/fastmcp/pull/967)
+* Add .ccignore for copychat by [@jlowin](https://github.com/jlowin) in [#1000](https://github.com/PrefectHQ/fastmcp/pull/1000)
+
+## New Contributors
+* [@maddymanu](https://github.com/maddymanu) made their first contribution in [#977](https://github.com/PrefectHQ/fastmcp/pull/977)
+* [@github0hello](https://github.com/github0hello) made their first contribution in [#979](https://github.com/PrefectHQ/fastmcp/pull/979)
+* [@tommitt](https://github.com/tommitt) made their first contribution in [#975](https://github.com/PrefectHQ/fastmcp/pull/975)
+* [@CfirTsabari](https://github.com/CfirTsabari) made their first contribution in [#986](https://github.com/PrefectHQ/fastmcp/pull/986)
+* [@mossbanay](https://github.com/mossbanay) made their first contribution in [#985](https://github.com/PrefectHQ/fastmcp/pull/985)
+* [@sstene1](https://github.com/sstene1) made their first contribution in [#997](https://github.com/PrefectHQ/fastmcp/pull/997)
+
+**Full Changelog**: [v2.9.2...v2.10.0](https://github.com/PrefectHQ/fastmcp/compare/v2.9.2...v2.10.0)
+
+</Update>
+
+<Update label="v2.9.2" description="2024-06-26">
+
+## [v2.9.2: Safety Pin](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.9.2)
+
+This is a patch release to pin `mcp` below 1.10, which includes changes related to the 6/18/2025 MCP spec update and could potentially break functionality for some FastMCP users.
+
+## What's Changed
+### Docs 📚
+* Fix version badge for messages by [@jlowin](https://github.com/jlowin) in [#960](https://github.com/PrefectHQ/fastmcp/pull/960)
+### Dependencies 📦
+* Pin mcp dependency by [@jlowin](https://github.com/jlowin) in [#962](https://github.com/PrefectHQ/fastmcp/pull/962)
+
+**Full Changelog**: [v2.9.1...v2.9.2](https://github.com/PrefectHQ/fastmcp/compare/v2.9.1...v2.9.2)
+
+</Update>
+
+<Update label="v2.9.1" description="2024-06-26">
+
+## [v2.9.1: Call Me Maybe](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.9.1)
+
+FastMCP 2.9.1 introduces automatic MCP list change notifications, allowing servers to notify clients when tools, resources, or prompts are dynamically updated. This enables more responsive and adaptive MCP integrations.
+
+## What's Changed
+### New Features 🎉
+* Add automatic MCP list change notifications and client message handling by [@jlowin](https://github.com/jlowin) in [#939](https://github.com/PrefectHQ/fastmcp/pull/939)
+### Enhancements 🔧
+* Add debug logging to bearer token authentication by [@jlowin](https://github.com/jlowin) in [#952](https://github.com/PrefectHQ/fastmcp/pull/952)
+### Fixes 🐞
+* Fix duplicate error logging in exception handlers by [@jlowin](https://github.com/jlowin) in [#938](https://github.com/PrefectHQ/fastmcp/pull/938)
+* Fix parameter location enum handling in OpenAPI parser by [@jlowin](https://github.com/jlowin) in [#953](https://github.com/PrefectHQ/fastmcp/pull/953)
+* Fix external schema reference handling in OpenAPI parser by [@jlowin](https://github.com/jlowin) in [#954](https://github.com/PrefectHQ/fastmcp/pull/954)
+### Docs 📚
+* Update changelog for 2.9 release by [@jlowin](https://github.com/jlowin) in [#929](https://github.com/PrefectHQ/fastmcp/pull/929)
+* Regenerate API references by [@zzstoatzz](https://github.com/zzstoatzz) in [#935](https://github.com/PrefectHQ/fastmcp/pull/935)
+* Regenerate API references by [@zzstoatzz](https://github.com/zzstoatzz) in [#947](https://github.com/PrefectHQ/fastmcp/pull/947)
+* Regenerate API references by [@zzstoatzz](https://github.com/zzstoatzz) in [#949](https://github.com/PrefectHQ/fastmcp/pull/949)
+### Examples & Contrib 💡
+* Add `create_thread` tool to bsky MCP server by [@zzstoatzz](https://github.com/zzstoatzz) in [#927](https://github.com/PrefectHQ/fastmcp/pull/927)
+* Update `mount_example.py` to work with current fastmcp API by [@rajephon](https://github.com/rajephon) in [#957](https://github.com/PrefectHQ/fastmcp/pull/957)
+
+## New Contributors
+* [@rajephon](https://github.com/rajephon) made their first contribution in [#957](https://github.com/PrefectHQ/fastmcp/pull/957)
+
+**Full Changelog**: [v2.9.0...v2.9.1](https://github.com/PrefectHQ/fastmcp/compare/v2.9.0...v2.9.1)
+
+</Update>
+
+<Update label="v2.9.0" description="2024-06-23">
+
+## [v2.9.0: Stuck in the Middleware With You](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.9.0)
+
+FastMCP 2.9 introduces two important features that push beyond the basic MCP protocol: MCP Middleware and server-side type conversion.
+
+### MCP Middleware
+MCP middleware lets you intercept and modify requests and responses at the protocol level, giving you powerful capabilities for logging, authentication, validation, and more. This is particularly useful for building production-ready MCP servers that need sophisticated request handling.
+
+### Server-side Type Conversion
+This release also introduces server-side type conversion for prompt arguments, ensuring that data is properly formatted before being passed to your functions. This reduces the burden on individual tools and prompts to handle type validation and conversion.
+
+## What's Changed
+### New Features 🎉
+* Add File utility for binary data by [@gorocode](https://github.com/gorocode) in [#843](https://github.com/PrefectHQ/fastmcp/pull/843)
+* Consolidate prefix logic into FastMCP methods by [@jlowin](https://github.com/jlowin) in [#861](https://github.com/PrefectHQ/fastmcp/pull/861)
+* Add MCP Middleware by [@jlowin](https://github.com/jlowin) in [#870](https://github.com/PrefectHQ/fastmcp/pull/870)
+* Implement server-side type conversion for prompt arguments by [@jlowin](https://github.com/jlowin) in [#908](https://github.com/PrefectHQ/fastmcp/pull/908)
+### Enhancements 🔧
+* Fix tool description indentation issue by [@zfflxx](https://github.com/zfflxx) in [#845](https://github.com/PrefectHQ/fastmcp/pull/845)
+* Add version parameter to FastMCP constructor by [@mkyutani](https://github.com/mkyutani) in [#842](https://github.com/PrefectHQ/fastmcp/pull/842)
+* Update version to not be positional by [@jlowin](https://github.com/jlowin) in [#848](https://github.com/PrefectHQ/fastmcp/pull/848)
+* Add key to component by [@jlowin](https://github.com/jlowin) in [#869](https://github.com/PrefectHQ/fastmcp/pull/869)
+* Add session_id property to Context for data sharing by [@jlowin](https://github.com/jlowin) in [#881](https://github.com/PrefectHQ/fastmcp/pull/881)
+* Fix CORS documentation example by [@jlowin](https://github.com/jlowin) in [#895](https://github.com/PrefectHQ/fastmcp/pull/895)
+### Fixes 🐞
+* "report_progress missing passing related_request_id causes notifications not working" by [@alexsee](https://github.com/alexsee) in [#838](https://github.com/PrefectHQ/fastmcp/pull/838)
+* Fix JWT issuer validation to support string values per RFC 7519 by [@jlowin](https://github.com/jlowin) in [#892](https://github.com/PrefectHQ/fastmcp/pull/892)
+* Fix BearerAuthProvider audience type annotations by [@jlowin](https://github.com/jlowin) in [#894](https://github.com/PrefectHQ/fastmcp/pull/894)
+### Docs 📚
+* Add CLAUDE.md development guidelines by [@jlowin](https://github.com/jlowin) in [#880](https://github.com/PrefectHQ/fastmcp/pull/880)
+* Update context docs for session_id property by [@jlowin](https://github.com/jlowin) in [#882](https://github.com/PrefectHQ/fastmcp/pull/882)
+* Add API reference by [@zzstoatzz](https://github.com/zzstoatzz) in [#893](https://github.com/PrefectHQ/fastmcp/pull/893)
+* Fix API ref rendering by [@zzstoatzz](https://github.com/zzstoatzz) in [#900](https://github.com/PrefectHQ/fastmcp/pull/900)
+* Simplify docs nav by [@jlowin](https://github.com/jlowin) in [#902](https://github.com/PrefectHQ/fastmcp/pull/902)
+* Add fastmcp inspect command by [@jlowin](https://github.com/jlowin) in [#904](https://github.com/PrefectHQ/fastmcp/pull/904)
+* Update client docs by [@jlowin](https://github.com/jlowin) in [#912](https://github.com/PrefectHQ/fastmcp/pull/912)
+* Update docs nav by [@jlowin](https://github.com/jlowin) in [#913](https://github.com/PrefectHQ/fastmcp/pull/913)
+* Update integration documentation for Claude Desktop, ChatGPT, and Claude Code by [@jlowin](https://github.com/jlowin) in [#915](https://github.com/PrefectHQ/fastmcp/pull/915)
+* Add http as an alias for streamable http by [@jlowin](https://github.com/jlowin) in [#917](https://github.com/PrefectHQ/fastmcp/pull/917)
+* Clean up parameter documentation by [@jlowin](https://github.com/jlowin) in [#918](https://github.com/PrefectHQ/fastmcp/pull/918)
+* Add middleware examples for timing, logging, rate limiting, and error handling by [@jlowin](https://github.com/jlowin) in [#919](https://github.com/PrefectHQ/fastmcp/pull/919)
+* ControlFlow → FastMCP rename by [@jlowin](https://github.com/jlowin) in [#922](https://github.com/PrefectHQ/fastmcp/pull/922)
+### Examples & Contrib 💡
+* Add contrib.mcp_mixin support for annotations by [@rsp2k](https://github.com/rsp2k) in [#860](https://github.com/PrefectHQ/fastmcp/pull/860)
+* Add ATProto (Bluesky) MCP Server Example by [@zzstoatzz](https://github.com/zzstoatzz) in [#916](https://github.com/PrefectHQ/fastmcp/pull/916)
+* Fix path in atproto example pyproject by [@zzstoatzz](https://github.com/zzstoatzz) in [#920](https://github.com/PrefectHQ/fastmcp/pull/920)
+* Remove uv source in example by [@zzstoatzz](https://github.com/zzstoatzz) in [#921](https://github.com/PrefectHQ/fastmcp/pull/921)
+
+## New Contributors
+* [@alexsee](https://github.com/alexsee) made their first contribution in [#838](https://github.com/PrefectHQ/fastmcp/pull/838)
+* [@zfflxx](https://github.com/zfflxx) made their first contribution in [#845](https://github.com/PrefectHQ/fastmcp/pull/845)
+* [@mkyutani](https://github.com/mkyutani) made their first contribution in [#842](https://github.com/PrefectHQ/fastmcp/pull/842)
+* [@gorocode](https://github.com/gorocode) made their first contribution in [#843](https://github.com/PrefectHQ/fastmcp/pull/843)
+* [@rsp2k](https://github.com/rsp2k) made their first contribution in [#860](https://github.com/PrefectHQ/fastmcp/pull/860)
+* [@owtaylor](https://github.com/owtaylor) made their first contribution in [#897](https://github.com/PrefectHQ/fastmcp/pull/897)
+* [@Jason-CKY](https://github.com/Jason-CKY) made their first contribution in [#906](https://github.com/PrefectHQ/fastmcp/pull/906)
+
+**Full Changelog**: [v2.8.1...v2.9.0](https://github.com/PrefectHQ/fastmcp/compare/v2.8.1...v2.9.0)
+
+</Update>
+
+<Update label="v2.8.1" description="2024-06-15">
+
+## [v2.8.1: Sound Judgement](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.8.1)
+
+2.8.1 introduces audio support, as well as minor fixes and updates for deprecated features.
+
+### Audio Support
+This release adds support for audio content in MCP tools and resources, expanding FastMCP's multimedia capabilities beyond text and images.
+
+## What's Changed
+### New Features 🎉
+* Add audio support by [@jlowin](https://github.com/jlowin) in [#833](https://github.com/PrefectHQ/fastmcp/pull/833)
+### Enhancements 🔧
+* Add flag for disabling deprecation warnings by [@jlowin](https://github.com/jlowin) in [#802](https://github.com/PrefectHQ/fastmcp/pull/802)
+* Add examples to Tool Arg Param transformation by [@strawgate](https://github.com/strawgate) in [#806](https://github.com/PrefectHQ/fastmcp/pull/806)
+### Fixes 🐞
+* Restore .settings access as deprecated by [@jlowin](https://github.com/jlowin) in [#800](https://github.com/PrefectHQ/fastmcp/pull/800)
+* Ensure handling of false http kwargs correctly; removed unused kwarg by [@jlowin](https://github.com/jlowin) in [#804](https://github.com/PrefectHQ/fastmcp/pull/804)
+* Bump mcp 1.9.4 by [@jlowin](https://github.com/jlowin) in [#835](https://github.com/PrefectHQ/fastmcp/pull/835)
+### Docs 📚
+* Update changelog for 2.8.0 by [@jlowin](https://github.com/jlowin) in [#794](https://github.com/PrefectHQ/fastmcp/pull/794)
+* Update welcome docs by [@jlowin](https://github.com/jlowin) in [#808](https://github.com/PrefectHQ/fastmcp/pull/808)
+* Update headers in docs by [@jlowin](https://github.com/jlowin) in [#809](https://github.com/PrefectHQ/fastmcp/pull/809)
+* Add MCP group to tutorials by [@jlowin](https://github.com/jlowin) in [#810](https://github.com/PrefectHQ/fastmcp/pull/810)
+* Add Community section to documentation by [@zzstoatzz](https://github.com/zzstoatzz) in [#819](https://github.com/PrefectHQ/fastmcp/pull/819)
+* Add 2.8 update by [@jlowin](https://github.com/jlowin) in [#821](https://github.com/PrefectHQ/fastmcp/pull/821)
+* Embed YouTube videos in community showcase by [@zzstoatzz](https://github.com/zzstoatzz) in [#820](https://github.com/PrefectHQ/fastmcp/pull/820)
+### Other Changes 🦾
+* Ensure http args are passed through by [@jlowin](https://github.com/jlowin) in [#803](https://github.com/PrefectHQ/fastmcp/pull/803)
+* Fix install link in readme by [@jlowin](https://github.com/jlowin) in [#836](https://github.com/PrefectHQ/fastmcp/pull/836)
+
+**Full Changelog**: [v2.8.0...v2.8.1](https://github.com/PrefectHQ/fastmcp/compare/v2.8.0...v2.8.1)
+
+</Update>
+
+<Update label="v2.8.0" description="2024-06-10">
+
+## [v2.8.0: Transform and Roll Out](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.8.0)
+
+FastMCP 2.8.0 introduces powerful new ways to customize and control your MCP servers! 
+
+### Tool Transformation
+
+The highlight of this release is first-class [**Tool Transformation**](/v2/patterns/tool-transformation), a new feature that lets you create enhanced variations of existing tools. You can now easily rename arguments, hide parameters, modify descriptions, and even wrap tools with custom validation or post-processing logic—all without rewriting the original code. This makes it easier than ever to adapt generic tools for specific LLM use cases or to simplify complex APIs. Huge thanks to [@strawgate](https://github.com/strawgate) for partnering on this, starting with [#591](https://github.com/PrefectHQ/fastmcp/discussions/591) and [#599](https://github.com/PrefectHQ/fastmcp/pull/599) and continuing offline.
+
+### Component Control
+This release also gives you more granular control over which components are exposed to clients. With new [**tag-based filtering**](/v2/servers/server#tag-based-filtering), you can selectively enable or disable tools, resources, and prompts based on tags, perfect for managing different environments or user permissions. Complementing this, every component now supports being [programmatically enabled or disabled](/v2/servers/tools#disabling-tools), offering dynamic control over your server's capabilities.
+
+### Tools-by-Default
+Finally, to improve compatibility with a wider range of LLM clients, this release changes the default behavior for OpenAPI integration: all API endpoints are now converted to `Tools` by default. This is a **breaking change** but pragmatically necessitated by the fact that the majority of MCP clients available today are, sadly, only compatible with MCP tools. Therefore, this change significantly simplifies the out-of-the-box experience and ensures your entire API is immediately accessible to any tool-using agent.
+
+## What's Changed
+### New Features 🎉
+* First-class tool transformation by [@jlowin](https://github.com/jlowin) in [#745](https://github.com/PrefectHQ/fastmcp/pull/745)
+* Support enable/disable for all FastMCP components (tools, prompts, resources, templates) by [@jlowin](https://github.com/jlowin) in [#781](https://github.com/PrefectHQ/fastmcp/pull/781)
+* Add support for tag-based component filtering by [@jlowin](https://github.com/jlowin) in [#748](https://github.com/PrefectHQ/fastmcp/pull/748)
+* Allow tag assignments for OpenAPI by [@jlowin](https://github.com/jlowin) in [#791](https://github.com/PrefectHQ/fastmcp/pull/791)
+### Enhancements 🔧
+* Create common base class for components by [@jlowin](https://github.com/jlowin) in [#776](https://github.com/PrefectHQ/fastmcp/pull/776)
+* Move components to own file; add resource by [@jlowin](https://github.com/jlowin) in [#777](https://github.com/PrefectHQ/fastmcp/pull/777)
+* Update FastMCP component with __eq__ and __repr__ by [@jlowin](https://github.com/jlowin) in [#779](https://github.com/PrefectHQ/fastmcp/pull/779)
+* Remove open-ended and server-specific settings by [@jlowin](https://github.com/jlowin) in [#750](https://github.com/PrefectHQ/fastmcp/pull/750)
+### Fixes 🐞
+* Ensure client is only initialized once by [@jlowin](https://github.com/jlowin) in [#758](https://github.com/PrefectHQ/fastmcp/pull/758)
+* Fix field validator for resource by [@jlowin](https://github.com/jlowin) in [#778](https://github.com/PrefectHQ/fastmcp/pull/778)
+* Ensure proxies can overwrite remote tools without falling back to the remote by [@jlowin](https://github.com/jlowin) in [#782](https://github.com/PrefectHQ/fastmcp/pull/782)
+### Breaking Changes 🛫
+* Treat all openapi routes as tools by [@jlowin](https://github.com/jlowin) in [#788](https://github.com/PrefectHQ/fastmcp/pull/788)
+* Fix issue with global OpenAPI tags by [@jlowin](https://github.com/jlowin) in [#792](https://github.com/PrefectHQ/fastmcp/pull/792)
+### Docs 📚
+* Minor docs updates by [@jlowin](https://github.com/jlowin) in [#755](https://github.com/PrefectHQ/fastmcp/pull/755)
+* Add 2.7 update by [@jlowin](https://github.com/jlowin) in [#756](https://github.com/PrefectHQ/fastmcp/pull/756)
+* Reduce 2.7 image size by [@jlowin](https://github.com/jlowin) in [#757](https://github.com/PrefectHQ/fastmcp/pull/757)
+* Update updates.mdx by [@jlowin](https://github.com/jlowin) in [#765](https://github.com/PrefectHQ/fastmcp/pull/765)
+* Hide docs sidebar scrollbar by default by [@jlowin](https://github.com/jlowin) in [#766](https://github.com/PrefectHQ/fastmcp/pull/766)
+* Add "stop vibe testing" to tutorials by [@jlowin](https://github.com/jlowin) in [#767](https://github.com/PrefectHQ/fastmcp/pull/767)
+* Add docs links by [@jlowin](https://github.com/jlowin) in [#768](https://github.com/PrefectHQ/fastmcp/pull/768)
+* Fix: updated variable name under Gemini remote client by [@yrangana](https://github.com/yrangana) in [#769](https://github.com/PrefectHQ/fastmcp/pull/769)
+* Revert "Hide docs sidebar scrollbar by default" by [@jlowin](https://github.com/jlowin) in [#770](https://github.com/PrefectHQ/fastmcp/pull/770)
+* Add updates by [@jlowin](https://github.com/jlowin) in [#773](https://github.com/PrefectHQ/fastmcp/pull/773)
+* Add tutorials by [@jlowin](https://github.com/jlowin) in [#783](https://github.com/PrefectHQ/fastmcp/pull/783)
+* Update LLM-friendly docs by [@jlowin](https://github.com/jlowin) in [#784](https://github.com/PrefectHQ/fastmcp/pull/784)
+* Update oauth.mdx by [@JeremyCraigMartinez](https://github.com/JeremyCraigMartinez) in [#787](https://github.com/PrefectHQ/fastmcp/pull/787)
+* Add changelog by [@jlowin](https://github.com/jlowin) in [#789](https://github.com/PrefectHQ/fastmcp/pull/789)
+* Add tutorials by [@jlowin](https://github.com/jlowin) in [#790](https://github.com/PrefectHQ/fastmcp/pull/790)
+* Add docs for tag-based filtering by [@jlowin](https://github.com/jlowin) in [#793](https://github.com/PrefectHQ/fastmcp/pull/793)
+### Other Changes 🦾
+* Create dependabot.yml by [@jlowin](https://github.com/jlowin) in [#759](https://github.com/PrefectHQ/fastmcp/pull/759)
+* Bump astral-sh/setup-uv from 3 to 6 by [@dependabot](https://github.com/dependabot) in [#760](https://github.com/PrefectHQ/fastmcp/pull/760)
+* Add dependencies section to release by [@jlowin](https://github.com/jlowin) in [#761](https://github.com/PrefectHQ/fastmcp/pull/761)
+* Remove extra imports for MCPConfig by [@Maanas-Verma](https://github.com/Maanas-Verma) in [#763](https://github.com/PrefectHQ/fastmcp/pull/763)
+* Split out enhancements in release notes by [@jlowin](https://github.com/jlowin) in [#764](https://github.com/PrefectHQ/fastmcp/pull/764)
+
+## New Contributors
+* [@dependabot](https://github.com/dependabot) made their first contribution in [#760](https://github.com/PrefectHQ/fastmcp/pull/760)
+* [@Maanas-Verma](https://github.com/Maanas-Verma) made their first contribution in [#763](https://github.com/PrefectHQ/fastmcp/pull/763)
+* [@JeremyCraigMartinez](https://github.com/JeremyCraigMartinez) made their first contribution in [#787](https://github.com/PrefectHQ/fastmcp/pull/787)
+
+**Full Changelog**: [v2.7.1...v2.8.0](https://github.com/PrefectHQ/fastmcp/compare/v2.7.1...v2.8.0)
+
+</Update>
+
+<Update label="v2.7.1" description="2024-06-08">
+
+## [v2.7.1: The Bearer Necessities](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.7.1)
+
+This release primarily contains a fix for parsing string tokens that are provided to FastMCP clients.
+
+### New Features 🎉
+
+* Respect cache setting, set default to 1 second by [@jlowin](https://github.com/jlowin) in [#747](https://github.com/PrefectHQ/fastmcp/pull/747)
+
+### Fixes 🐞
+
+* Ensure event store is properly typed by [@jlowin](https://github.com/jlowin) in [#753](https://github.com/PrefectHQ/fastmcp/pull/753)
+* Fix passing token string to client auth & add auth to MCPConfig clients by [@jlowin](https://github.com/jlowin) in [#754](https://github.com/PrefectHQ/fastmcp/pull/754)
+
+### Docs 📚
+
+* Docs : fix client to mcp\_client in Gemini example by [@yrangana](https://github.com/yrangana) in [#734](https://github.com/PrefectHQ/fastmcp/pull/734)
+* update add tool docstring by [@strawgate](https://github.com/strawgate) in [#739](https://github.com/PrefectHQ/fastmcp/pull/739)
+* Fix contrib link by [@richardkmichael](https://github.com/richardkmichael) in [#749](https://github.com/PrefectHQ/fastmcp/pull/749)
+
+### Other Changes 🦾
+
+* Switch Pydantic defaults to kwargs by [@strawgate](https://github.com/strawgate) in [#731](https://github.com/PrefectHQ/fastmcp/pull/731)
+* Fix Typo in CLI module by [@wfclark5](https://github.com/wfclark5) in [#737](https://github.com/PrefectHQ/fastmcp/pull/737)
+* chore: fix prompt docstring by [@danb27](https://github.com/danb27) in [#752](https://github.com/PrefectHQ/fastmcp/pull/752)
+* Add accept to excluded headers by [@jlowin](https://github.com/jlowin) in [#751](https://github.com/PrefectHQ/fastmcp/pull/751)
+
+### New Contributors
+
+* [@wfclark5](https://github.com/wfclark5) made their first contribution in [#737](https://github.com/PrefectHQ/fastmcp/pull/737)
+* [@richardkmichael](https://github.com/richardkmichael) made their first contribution in [#749](https://github.com/PrefectHQ/fastmcp/pull/749)
+* [@danb27](https://github.com/danb27) made their first contribution in [#752](https://github.com/PrefectHQ/fastmcp/pull/752)
+
+**Full Changelog**: [v2.7.0...v2.7.1](https://github.com/PrefectHQ/fastmcp/compare/v2.7.0...v2.7.1)
+</Update>
+
+<Update label="v2.7.0" description="2024-06-05">
+
+## [v2.7.0: Pare Programming](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.7.0)
+
+This is primarily a housekeeping release to remove or deprecate cruft that's accumulated since v1. Primarily, this release refactors FastMCP's internals in preparation for features planned in the next few major releases. However please note that as a result, this release has some minor breaking changes (which is why it's 2.7, not 2.6.2, in accordance with repo guidelines) though not to the core user-facing APIs.
+
+### Breaking Changes 🛫
+
+* decorators return the objects they create, not the decorated function
+* websockets is an optional dependency
+* methods on the server for automatically converting functions into tools/resources/prompts have been deprecated in favor of using the decorators directly
+
+### New Features 🎉
+
+* allow passing flags to servers by [@zzstoatzz](https://github.com/zzstoatzz) in [#690](https://github.com/PrefectHQ/fastmcp/pull/690)
+* replace $ref pointing to `#/components/schemas/` with `#/$defs/` by [@phateffect](https://github.com/phateffect) in [#697](https://github.com/PrefectHQ/fastmcp/pull/697)
+* Split Tool into Tool and FunctionTool by [@jlowin](https://github.com/jlowin) in [#700](https://github.com/PrefectHQ/fastmcp/pull/700)
+* Use strict basemodel for Prompt; relax from\_function deprecation by [@jlowin](https://github.com/jlowin) in [#701](https://github.com/PrefectHQ/fastmcp/pull/701)
+* Formalize resource/functionresource replationship by [@jlowin](https://github.com/jlowin) in [#702](https://github.com/PrefectHQ/fastmcp/pull/702)
+* Formalize template/functiontemplate split by [@jlowin](https://github.com/jlowin) in [#703](https://github.com/PrefectHQ/fastmcp/pull/703)
+* Support flexible @tool decorator call patterns by [@jlowin](https://github.com/jlowin) in [#706](https://github.com/PrefectHQ/fastmcp/pull/706)
+* Ensure deprecation warnings have stacklevel=2 by [@jlowin](https://github.com/jlowin) in [#710](https://github.com/PrefectHQ/fastmcp/pull/710)
+* Allow naked prompt decorator by [@jlowin](https://github.com/jlowin) in [#711](https://github.com/PrefectHQ/fastmcp/pull/711)
+
+### Fixes 🐞
+
+* Updates / Fixes for Tool Content Conversion by [@strawgate](https://github.com/strawgate) in [#642](https://github.com/PrefectHQ/fastmcp/pull/642)
+* Fix pr labeler permissions by [@jlowin](https://github.com/jlowin) in [#708](https://github.com/PrefectHQ/fastmcp/pull/708)
+* remove -n auto by [@jlowin](https://github.com/jlowin) in [#709](https://github.com/PrefectHQ/fastmcp/pull/709)
+* Fix links in README.md by [@alainivars](https://github.com/alainivars) in [#723](https://github.com/PrefectHQ/fastmcp/pull/723)
+
+Happily, this release DOES permit the use of "naked" decorators to align with Pythonic practice:
+
+```python
+@mcp.tool
+def my_tool():
+    ...
+```
+
+**Full Changelog**: [v2.6.2...v2.7.0](https://github.com/PrefectHQ/fastmcp/compare/v2.6.2...v2.7.0)
+</Update>
+
+<Update label="v2.6.1" description="2024-06-03">
+
+## [v2.6.1: Blast Auth (second ignition)](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.6.1)
+
+This is a patch release to restore py.typed in #686.
+
+### Docs 📚
+
+* Update readme by [@jlowin](https://github.com/jlowin) in [#679](https://github.com/PrefectHQ/fastmcp/pull/679)
+* Add gemini tutorial by [@jlowin](https://github.com/jlowin) in [#680](https://github.com/PrefectHQ/fastmcp/pull/680)
+* Fix : fix path error to CLI Documentation by [@yrangana](https://github.com/yrangana) in [#684](https://github.com/PrefectHQ/fastmcp/pull/684)
+* Update auth docs by [@jlowin](https://github.com/jlowin) in [#687](https://github.com/PrefectHQ/fastmcp/pull/687)
+
+### Other Changes 🦾
+
+* Remove deprecation notice by [@jlowin](https://github.com/jlowin) in [#677](https://github.com/PrefectHQ/fastmcp/pull/677)
+* Delete server.py by [@jlowin](https://github.com/jlowin) in [#681](https://github.com/PrefectHQ/fastmcp/pull/681)
+* Restore py.typed by [@jlowin](https://github.com/jlowin) in [#686](https://github.com/PrefectHQ/fastmcp/pull/686)
+
+### New Contributors
+
+* [@yrangana](https://github.com/yrangana) made their first contribution in [#684](https://github.com/PrefectHQ/fastmcp/pull/684)
+
+**Full Changelog**: [v2.6.0...v2.6.1](https://github.com/PrefectHQ/fastmcp/compare/v2.6.0...v2.6.1)
+</Update>
+
+<Update label="v2.6.0" description="2024-06-02">
+
+## [v2.6.0: Blast Auth](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.6.0)
+
+### New Features 🎉
+
+* Introduce MCP client oauth flow by [@jlowin](https://github.com/jlowin) in [#478](https://github.com/PrefectHQ/fastmcp/pull/478)
+* Support providing tools at init by [@jlowin](https://github.com/jlowin) in [#647](https://github.com/PrefectHQ/fastmcp/pull/647)
+* Simplify code for running servers in processes during tests by [@jlowin](https://github.com/jlowin) in [#649](https://github.com/PrefectHQ/fastmcp/pull/649)
+* Add basic bearer auth for server and client by [@jlowin](https://github.com/jlowin) in [#650](https://github.com/PrefectHQ/fastmcp/pull/650)
+* Support configuring bearer auth from env vars by [@jlowin](https://github.com/jlowin) in [#652](https://github.com/PrefectHQ/fastmcp/pull/652)
+* feat(tool): add support for excluding arguments from tool definition by [@deepak-stratforge](https://github.com/deepak-stratforge) in [#626](https://github.com/PrefectHQ/fastmcp/pull/626)
+* Add docs for server + client auth by [@jlowin](https://github.com/jlowin) in [#655](https://github.com/PrefectHQ/fastmcp/pull/655)
+
+### Fixes 🐞
+
+* fix: Support concurrency in FastMcpProxy (and Client) by [@Sillocan](https://github.com/Sillocan) in [#635](https://github.com/PrefectHQ/fastmcp/pull/635)
+* Ensure Client.close() cleans up client context appropriately by [@jlowin](https://github.com/jlowin) in [#643](https://github.com/PrefectHQ/fastmcp/pull/643)
+* Update client.mdx: ClientError namespace by [@mjkaye](https://github.com/mjkaye) in [#657](https://github.com/PrefectHQ/fastmcp/pull/657)
+
+### Docs 📚
+
+* Make FastMCPTransport support simulated Streamable HTTP Transport (didn't work) by [@jlowin](https://github.com/jlowin) in [#645](https://github.com/PrefectHQ/fastmcp/pull/645)
+* Document exclude\_args by [@jlowin](https://github.com/jlowin) in [#653](https://github.com/PrefectHQ/fastmcp/pull/653)
+* Update welcome by [@jlowin](https://github.com/jlowin) in [#673](https://github.com/PrefectHQ/fastmcp/pull/673)
+* Add Anthropic + Claude desktop integration guides by [@jlowin](https://github.com/jlowin) in [#674](https://github.com/PrefectHQ/fastmcp/pull/674)
+* Minor docs design updates by [@jlowin](https://github.com/jlowin) in [#676](https://github.com/PrefectHQ/fastmcp/pull/676)
+
+### Other Changes 🦾
+
+* Update test typing by [@jlowin](https://github.com/jlowin) in [#646](https://github.com/PrefectHQ/fastmcp/pull/646)
+* Add OpenAI integration docs by [@jlowin](https://github.com/jlowin) in [#660](https://github.com/PrefectHQ/fastmcp/pull/660)
+
+### New Contributors
+
+* [@Sillocan](https://github.com/Sillocan) made their first contribution in [#635](https://github.com/PrefectHQ/fastmcp/pull/635)
+* [@deepak-stratforge](https://github.com/deepak-stratforge) made their first contribution in [#626](https://github.com/PrefectHQ/fastmcp/pull/626)
+* [@mjkaye](https://github.com/mjkaye) made their first contribution in [#657](https://github.com/PrefectHQ/fastmcp/pull/657)
+
+**Full Changelog**: [v2.5.2...v2.6.0](https://github.com/PrefectHQ/fastmcp/compare/v2.5.2...v2.6.0)
+</Update>
+
+<Update label="v2.5.2" description="2024-05-29">
+
+## [v2.5.2: Stayin' Alive](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.5.2)
+
+### New Features 🎉
+
+* Add graceful error handling for unreachable mounted servers by [@davenpi](https://github.com/davenpi) in [#605](https://github.com/PrefectHQ/fastmcp/pull/605)
+* Improve type inference from client transport by [@jlowin](https://github.com/jlowin) in [#623](https://github.com/PrefectHQ/fastmcp/pull/623)
+* Add keep\_alive param to reuse subprocess by [@jlowin](https://github.com/jlowin) in [#624](https://github.com/PrefectHQ/fastmcp/pull/624)
+
+### Fixes 🐞
+
+* Fix handling tools without descriptions by [@jlowin](https://github.com/jlowin) in [#610](https://github.com/PrefectHQ/fastmcp/pull/610)
+* Don't print env vars to console when format is wrong by [@jlowin](https://github.com/jlowin) in [#615](https://github.com/PrefectHQ/fastmcp/pull/615)
+* Ensure behavior-affecting headers are excluded when forwarding proxies/openapi by [@jlowin](https://github.com/jlowin) in [#620](https://github.com/PrefectHQ/fastmcp/pull/620)
+
+### Docs 📚
+
+* Add notes about uv and claude desktop by [@jlowin](https://github.com/jlowin) in [#597](https://github.com/PrefectHQ/fastmcp/pull/597)
+
+### Other Changes 🦾
+
+* add init\_timeout for mcp client by [@jfouret](https://github.com/jfouret) in [#607](https://github.com/PrefectHQ/fastmcp/pull/607)
+* Add init\_timeout for mcp client (incl settings) by [@jlowin](https://github.com/jlowin) in [#609](https://github.com/PrefectHQ/fastmcp/pull/609)
+* Support for uppercase letters at the log level by [@ksawaray](https://github.com/ksawaray) in [#625](https://github.com/PrefectHQ/fastmcp/pull/625)
+
+### New Contributors
+
+* [@jfouret](https://github.com/jfouret) made their first contribution in [#607](https://github.com/PrefectHQ/fastmcp/pull/607)
+* [@ksawaray](https://github.com/ksawaray) made their first contribution in [#625](https://github.com/PrefectHQ/fastmcp/pull/625)
+
+**Full Changelog**: [v2.5.1...v2.5.2](https://github.com/PrefectHQ/fastmcp/compare/v2.5.1...v2.5.2)
+</Update>
+
+<Update label="v2.5.1" description="2024-05-24">
+
+## [v2.5.1: Route Awakening (Part 2)](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.5.1)
+
+### Fixes 🐞
+
+* Ensure content-length is always stripped from client headers by [@jlowin](https://github.com/jlowin) in [#589](https://github.com/PrefectHQ/fastmcp/pull/589)
+
+### Docs 📚
+
+* Fix redundant section of docs by [@jlowin](https://github.com/jlowin) in [#583](https://github.com/PrefectHQ/fastmcp/pull/583)
+
+**Full Changelog**: [v2.5.0...v2.5.1](https://github.com/PrefectHQ/fastmcp/compare/v2.5.0...v2.5.1)
+</Update>
+
+<Update label="v2.5.0" description="2024-05-24">
+
+## [v2.5.0: Route Awakening](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.5.0)
+
+This release introduces completely new tools for generating and customizing MCP servers from OpenAPI specs and FastAPI apps, including popular requests like mechanisms for determining what routes map to what MCP components; renaming routes; and customizing the generated MCP components.
+
+### New Features 🎉
+
+* Add FastMCP 1.0 server support for in-memory Client / Testing by [@jlowin](https://github.com/jlowin) in [#539](https://github.com/PrefectHQ/fastmcp/pull/539)
+* Minor addition: add transport to stdio server in mcpconfig, with default by [@jlowin](https://github.com/jlowin) in [#555](https://github.com/PrefectHQ/fastmcp/pull/555)
+* Raise an error if a Client is created with no servers in config by [@jlowin](https://github.com/jlowin) in [#554](https://github.com/PrefectHQ/fastmcp/pull/554)
+* Expose model preferences in `Context.sample` for flexible model selection. by [@davenpi](https://github.com/davenpi) in [#542](https://github.com/PrefectHQ/fastmcp/pull/542)
+* Ensure custom routes are respected by [@jlowin](https://github.com/jlowin) in [#558](https://github.com/PrefectHQ/fastmcp/pull/558)
+* Add client method to send cancellation notifications by [@davenpi](https://github.com/davenpi) in [#563](https://github.com/PrefectHQ/fastmcp/pull/563)
+* Enhance route map logic for include/exclude OpenAPI routes by [@jlowin](https://github.com/jlowin) in [#564](https://github.com/PrefectHQ/fastmcp/pull/564)
+* Add tag-based route maps by [@jlowin](https://github.com/jlowin) in [#565](https://github.com/PrefectHQ/fastmcp/pull/565)
+* Add advanced control of openAPI route creation by [@jlowin](https://github.com/jlowin) in [#566](https://github.com/PrefectHQ/fastmcp/pull/566)
+* Make error masking configurable by [@jlowin](https://github.com/jlowin) in [#550](https://github.com/PrefectHQ/fastmcp/pull/550)
+* Ensure client headers are passed through to remote servers by [@jlowin](https://github.com/jlowin) in [#575](https://github.com/PrefectHQ/fastmcp/pull/575)
+* Use lowercase name for headers when comparing by [@jlowin](https://github.com/jlowin) in [#576](https://github.com/PrefectHQ/fastmcp/pull/576)
+* Permit more flexible name generation for OpenAPI servers by [@jlowin](https://github.com/jlowin) in [#578](https://github.com/PrefectHQ/fastmcp/pull/578)
+* Ensure that tools/templates/prompts are compatible with callable objects by [@jlowin](https://github.com/jlowin) in [#579](https://github.com/PrefectHQ/fastmcp/pull/579)
+
+### Docs 📚
+
+* Add version badge for prefix formats by [@jlowin](https://github.com/jlowin) in [#537](https://github.com/PrefectHQ/fastmcp/pull/537)
+* Add versioning note to docs by [@jlowin](https://github.com/jlowin) in [#551](https://github.com/PrefectHQ/fastmcp/pull/551)
+* Bump 2.3.6 references to 2.4.0 by [@jlowin](https://github.com/jlowin) in [#567](https://github.com/PrefectHQ/fastmcp/pull/567)
+
+**Full Changelog**: [v2.4.0...v2.5.0](https://github.com/PrefectHQ/fastmcp/compare/v2.4.0...v2.5.0)
+</Update>
+
+<Update label="v2.4.0" description="2024-05-21">
+
+## [v2.4.0: Config and Conquer](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.4.0)
+
+**Note**: this release includes a backwards-incompatible change to how resources are prefixed when mounted in composed servers. However, it is only backwards-incompatible if users were running tests or manually loading resources by prefixed key; LLMs should not have any issue discovering the new route.
+
+### New Features 🎉
+
+* Allow \* Methods and all routes as tools shortcuts by [@jlowin](https://github.com/jlowin) in [#520](https://github.com/PrefectHQ/fastmcp/pull/520)
+* Improved support for config dicts by [@jlowin](https://github.com/jlowin) in [#522](https://github.com/PrefectHQ/fastmcp/pull/522)
+* Support creating clients from MCP config dicts, including multi-server clients by [@jlowin](https://github.com/jlowin) in [#527](https://github.com/PrefectHQ/fastmcp/pull/527)
+* Make resource prefix format configurable by [@jlowin](https://github.com/jlowin) in [#534](https://github.com/PrefectHQ/fastmcp/pull/534)
+
+### Fixes 🐞
+
+* Avoid hanging on initializing server session by [@jlowin](https://github.com/jlowin) in [#523](https://github.com/PrefectHQ/fastmcp/pull/523)
+
+### Breaking Changes 🛫
+
+* Remove customizable separators; improve resource separator by [@jlowin](https://github.com/jlowin) in [#526](https://github.com/PrefectHQ/fastmcp/pull/526)
+
+### Docs 📚
+
+* Improve client documentation by [@jlowin](https://github.com/jlowin) in [#517](https://github.com/PrefectHQ/fastmcp/pull/517)
+
+### Other Changes 🦾
+
+* Ensure openapi path params are handled properly by [@jlowin](https://github.com/jlowin) in [#519](https://github.com/PrefectHQ/fastmcp/pull/519)
+* better error when missing lifespan by [@zzstoatzz](https://github.com/zzstoatzz) in [#521](https://github.com/PrefectHQ/fastmcp/pull/521)
+
+**Full Changelog**: [v2.3.5...v2.4.0](https://github.com/PrefectHQ/fastmcp/compare/v2.3.5...v2.4.0)
+</Update>
+
+<Update label="v2.3.5" description="2024-05-20">
+
+## [v2.3.5: Making Progress](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.3.5)
+
+### New Features 🎉
+
+* support messages in progress notifications by [@rickygenhealth](https://github.com/rickygenhealth) in [#471](https://github.com/PrefectHQ/fastmcp/pull/471)
+* feat: Add middleware option in server.run by [@Maxi91f](https://github.com/Maxi91f) in [#475](https://github.com/PrefectHQ/fastmcp/pull/475)
+* Add lifespan property to app by [@jlowin](https://github.com/jlowin) in [#483](https://github.com/PrefectHQ/fastmcp/pull/483)
+* Update `fastmcp run` to work with remote servers by [@jlowin](https://github.com/jlowin) in [#491](https://github.com/PrefectHQ/fastmcp/pull/491)
+* Add FastMCP.as\_proxy() by [@jlowin](https://github.com/jlowin) in [#490](https://github.com/PrefectHQ/fastmcp/pull/490)
+* Infer sse transport from urls containing /sse by [@jlowin](https://github.com/jlowin) in [#512](https://github.com/PrefectHQ/fastmcp/pull/512)
+* Add progress handler to client by [@jlowin](https://github.com/jlowin) in [#513](https://github.com/PrefectHQ/fastmcp/pull/513)
+* Store the initialize result on the client by [@jlowin](https://github.com/jlowin) in [#509](https://github.com/PrefectHQ/fastmcp/pull/509)
+
+### Fixes 🐞
+
+* Remove patch and use upstream SSEServerTransport by [@jlowin](https://github.com/jlowin) in [#425](https://github.com/PrefectHQ/fastmcp/pull/425)
+
+### Docs 📚
+
+* Update transport docs by [@jlowin](https://github.com/jlowin) in [#458](https://github.com/PrefectHQ/fastmcp/pull/458)
+* update proxy docs + example by [@zzstoatzz](https://github.com/zzstoatzz) in [#460](https://github.com/PrefectHQ/fastmcp/pull/460)
+* doc(asgi): Change custom route example to PlainTextResponse by [@mcw0933](https://github.com/mcw0933) in [#477](https://github.com/PrefectHQ/fastmcp/pull/477)
+* Store FastMCP instance on app.state.fastmcp\_server by [@jlowin](https://github.com/jlowin) in [#489](https://github.com/PrefectHQ/fastmcp/pull/489)
+* Improve AGENTS.md overview by [@jlowin](https://github.com/jlowin) in [#492](https://github.com/PrefectHQ/fastmcp/pull/492)
+* Update release numbers for anticipated version by [@jlowin](https://github.com/jlowin) in [#516](https://github.com/PrefectHQ/fastmcp/pull/516)
+
+### Other Changes 🦾
+
+* run tests on all PRs by [@jlowin](https://github.com/jlowin) in [#468](https://github.com/PrefectHQ/fastmcp/pull/468)
+* add null check by [@zzstoatzz](https://github.com/zzstoatzz) in [#473](https://github.com/PrefectHQ/fastmcp/pull/473)
+* strict typing for `server.py` by [@zzstoatzz](https://github.com/zzstoatzz) in [#476](https://github.com/PrefectHQ/fastmcp/pull/476)
+* Doc(quickstart): Fix import statements by [@mai-nakagawa](https://github.com/mai-nakagawa) in [#479](https://github.com/PrefectHQ/fastmcp/pull/479)
+* Add labeler by [@jlowin](https://github.com/jlowin) in [#484](https://github.com/PrefectHQ/fastmcp/pull/484)
+* Fix flaky timeout test by increasing timeout (#474) by [@davenpi](https://github.com/davenpi) in [#486](https://github.com/PrefectHQ/fastmcp/pull/486)
+* Skipping `test_permission_error` if runner is root. by [@ZiadAmerr](https://github.com/ZiadAmerr) in [#502](https://github.com/PrefectHQ/fastmcp/pull/502)
+* allow passing full uvicorn config by [@zzstoatzz](https://github.com/zzstoatzz) in [#504](https://github.com/PrefectHQ/fastmcp/pull/504)
+* Skip timeout tests on windows by [@jlowin](https://github.com/jlowin) in [#514](https://github.com/PrefectHQ/fastmcp/pull/514)
+
+### New Contributors
+
+* [@rickygenhealth](https://github.com/rickygenhealth) made their first contribution in [#471](https://github.com/PrefectHQ/fastmcp/pull/471)
+* [@Maxi91f](https://github.com/Maxi91f) made their first contribution in [#475](https://github.com/PrefectHQ/fastmcp/pull/475)
+* [@mcw0933](https://github.com/mcw0933) made their first contribution in [#477](https://github.com/PrefectHQ/fastmcp/pull/477)
+* [@mai-nakagawa](https://github.com/mai-nakagawa) made their first contribution in [#479](https://github.com/PrefectHQ/fastmcp/pull/479)
+* [@ZiadAmerr](https://github.com/ZiadAmerr) made their first contribution in [#502](https://github.com/PrefectHQ/fastmcp/pull/502)
+
+**Full Changelog**: [v2.3.4...v2.3.5](https://github.com/PrefectHQ/fastmcp/compare/v2.3.4...v2.3.5)
+</Update>
+
+<Update label="v2.3.4" description="2024-05-15">
+
+## [v2.3.4: Error Today, Gone Tomorrow](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.3.4)
+
+### New Features 🎉
+
+* logging stack trace for easier debugging by [@jbkoh](https://github.com/jbkoh) in [#413](https://github.com/PrefectHQ/fastmcp/pull/413)
+* add missing StreamableHttpTransport in client exports by [@yihuang](https://github.com/yihuang) in [#408](https://github.com/PrefectHQ/fastmcp/pull/408)
+* Improve error handling for tools and resources by [@jlowin](https://github.com/jlowin) in [#434](https://github.com/PrefectHQ/fastmcp/pull/434)
+* feat: add support for removing tools from server by [@davenpi](https://github.com/davenpi) in [#437](https://github.com/PrefectHQ/fastmcp/pull/437)
+* Prune titles from JSONSchemas by [@jlowin](https://github.com/jlowin) in [#449](https://github.com/PrefectHQ/fastmcp/pull/449)
+* Declare toolsChanged capability for stdio server. by [@davenpi](https://github.com/davenpi) in [#450](https://github.com/PrefectHQ/fastmcp/pull/450)
+* Improve handling of exceptiongroups when raised in clients by [@jlowin](https://github.com/jlowin) in [#452](https://github.com/PrefectHQ/fastmcp/pull/452)
+* Add timeout support to client by [@jlowin](https://github.com/jlowin) in [#455](https://github.com/PrefectHQ/fastmcp/pull/455)
+
+### Fixes 🐞
+
+* Pin to mcp 1.8.1 to resolve callback deadlocks with SHTTP by [@jlowin](https://github.com/jlowin) in [#427](https://github.com/PrefectHQ/fastmcp/pull/427)
+* Add reprs for OpenAPI objects by [@jlowin](https://github.com/jlowin) in [#447](https://github.com/PrefectHQ/fastmcp/pull/447)
+* Ensure openapi defs for structured objects are loaded properly by [@jlowin](https://github.com/jlowin) in [#448](https://github.com/PrefectHQ/fastmcp/pull/448)
+* Ensure tests run against correct python version by [@jlowin](https://github.com/jlowin) in [#454](https://github.com/PrefectHQ/fastmcp/pull/454)
+* Ensure result is only returned if a new key was found by [@jlowin](https://github.com/jlowin) in [#456](https://github.com/PrefectHQ/fastmcp/pull/456)
+
+### Docs 📚
+
+* Add documentation for tool removal by [@jlowin](https://github.com/jlowin) in [#440](https://github.com/PrefectHQ/fastmcp/pull/440)
+
+### Other Changes 🦾
+
+* Deprecate passing settings to the FastMCP instance by [@jlowin](https://github.com/jlowin) in [#424](https://github.com/PrefectHQ/fastmcp/pull/424)
+* Add path prefix to test by [@jlowin](https://github.com/jlowin) in [#432](https://github.com/PrefectHQ/fastmcp/pull/432)
+
+### New Contributors
+
+* [@jbkoh](https://github.com/jbkoh) made their first contribution in [#413](https://github.com/PrefectHQ/fastmcp/pull/413)
+* [@davenpi](https://github.com/davenpi) made their first contribution in [#437](https://github.com/PrefectHQ/fastmcp/pull/437)
+
+**Full Changelog**: [v2.3.3...v2.3.4](https://github.com/PrefectHQ/fastmcp/compare/v2.3.3...v2.3.4)
+</Update>
+
+<Update label="v2.3.3" description="2024-05-10">
+
+## [v2.3.3: SSE you later](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.3.3)
+
+This is a hotfix for a bug introduced in 2.3.2 that broke SSE servers
+
+### Fixes 🐞
+
+* Fix bug that sets message path and sse path to same value by [@jlowin](https://github.com/jlowin) in [#405](https://github.com/PrefectHQ/fastmcp/pull/405)
+
+### Docs 📚
+
+* Update composition docs by [@jlowin](https://github.com/jlowin) in [#403](https://github.com/PrefectHQ/fastmcp/pull/403)
+
+### Other Changes 🦾
+
+* Add test for no prefix when importing by [@jlowin](https://github.com/jlowin) in [#404](https://github.com/PrefectHQ/fastmcp/pull/404)
+
+**Full Changelog**: [v2.3.2...v2.3.3](https://github.com/PrefectHQ/fastmcp/compare/v2.3.2...v2.3.3)
+</Update>
+
+<Update label="v2.3.2" description="2024-05-10">
+
+## [v2.3.2: Stuck in the Middleware With You](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.3.2)
+
+### New Features 🎉
+
+* Allow users to pass middleware to starlette app constructors by [@jlowin](https://github.com/jlowin) in [#398](https://github.com/PrefectHQ/fastmcp/pull/398)
+* Deprecate transport-specific methods on FastMCP server by [@jlowin](https://github.com/jlowin) in [#401](https://github.com/PrefectHQ/fastmcp/pull/401)
+
+### Docs 📚
+
+* Update CLI docs by [@jlowin](https://github.com/jlowin) in [#402](https://github.com/PrefectHQ/fastmcp/pull/402)
+
+### Other Changes 🦾
+
+* Adding 23 tests for CLI by [@didier-durand](https://github.com/didier-durand) in [#394](https://github.com/PrefectHQ/fastmcp/pull/394)
+
+**Full Changelog**: [v2.3.1...v2.3.2](https://github.com/PrefectHQ/fastmcp/compare/v2.3.1...v2.3.2)
+</Update>
+
+<Update label="v2.3.1" description="2024-05-09">
+
+## [v2.3.1: For Good-nests Sake](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.3.1)
+
+This release primarily patches a long-standing bug with nested ASGI SSE servers.
+
+### Fixes 🐞
+
+* Fix tool result serialization when the tool returns a list by [@strawgate](https://github.com/strawgate) in [#379](https://github.com/PrefectHQ/fastmcp/pull/379)
+* Ensure FastMCP handles nested SSE and SHTTP apps properly in ASGI frameworks by [@jlowin](https://github.com/jlowin) in [#390](https://github.com/PrefectHQ/fastmcp/pull/390)
+
+### Docs 📚
+
+* Update transport docs by [@jlowin](https://github.com/jlowin) in [#377](https://github.com/PrefectHQ/fastmcp/pull/377)
+* Add llms.txt to docs by [@jlowin](https://github.com/jlowin) in [#384](https://github.com/PrefectHQ/fastmcp/pull/384)
+* Fixing various text typos by [@didier-durand](https://github.com/didier-durand) in [#385](https://github.com/PrefectHQ/fastmcp/pull/385)
+
+### Other Changes 🦾
+
+* Adding a few tests to Image type by [@didier-durand](https://github.com/didier-durand) in [#387](https://github.com/PrefectHQ/fastmcp/pull/387)
+* Adding tests for TimedCache by [@didier-durand](https://github.com/didier-durand) in [#388](https://github.com/PrefectHQ/fastmcp/pull/388)
+
+### New Contributors
+
+* [@didier-durand](https://github.com/didier-durand) made their first contribution in [#385](https://github.com/PrefectHQ/fastmcp/pull/385)
+
+**Full Changelog**: [v2.3.0...v2.3.1](https://github.com/PrefectHQ/fastmcp/compare/v2.3.0...v2.3.1)
+</Update>
+
+<Update label="v2.3.0" description="2024-05-08">
+
+## [v2.3.0: Stream Me Up, Scotty](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.3.0)
+
+### New Features 🎉
+
+* Add streaming support for HTTP transport by [@jlowin](https://github.com/jlowin) in [#365](https://github.com/PrefectHQ/fastmcp/pull/365)
+* Support streaming HTTP transport in clients by [@jlowin](https://github.com/jlowin) in [#366](https://github.com/PrefectHQ/fastmcp/pull/366)
+* Add streaming support to CLI by [@jlowin](https://github.com/jlowin) in [#367](https://github.com/PrefectHQ/fastmcp/pull/367)
+
+### Fixes 🐞
+
+* Fix streaming transport initialization by [@jlowin](https://github.com/jlowin) in [#368](https://github.com/PrefectHQ/fastmcp/pull/368)
+
+### Docs 📚
+
+* Update transport documentation for streaming support by [@jlowin](https://github.com/jlowin) in [#369](https://github.com/PrefectHQ/fastmcp/pull/369)
+
+**Full Changelog**: [v2.2.10...v2.3.0](https://github.com/PrefectHQ/fastmcp/compare/v2.2.10...v2.3.0)
+</Update>
+
+<Update label="v2.2.10" description="2024-05-06">
+
+## [v2.2.10: That's JSON Bourne](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.10)
+
+### Fixes 🐞
+
+* Disable automatic JSON parsing of tool args by [@jlowin](https://github.com/jlowin) in [#341](https://github.com/PrefectHQ/fastmcp/pull/341)
+* Fix prompt test by [@jlowin](https://github.com/jlowin) in [#342](https://github.com/PrefectHQ/fastmcp/pull/342)
+
+### Other Changes 🦾
+
+* Update docs.json by [@jlowin](https://github.com/jlowin) in [#338](https://github.com/PrefectHQ/fastmcp/pull/338)
+* Add test coverage + tests on 4 examples by [@alainivars](https://github.com/alainivars) in [#306](https://github.com/PrefectHQ/fastmcp/pull/306)
+
+### New Contributors
+
+* [@alainivars](https://github.com/alainivars) made their first contribution in [#306](https://github.com/PrefectHQ/fastmcp/pull/306)
+
+**Full Changelog**: [v2.2.9...v2.2.10](https://github.com/PrefectHQ/fastmcp/compare/v2.2.9...v2.2.10)
+</Update>
+
+<Update label="v2.2.9" description="2024-05-06">
+
+## [v2.2.9: Str-ing the Pot (Hotfix)](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.9)
+
+This release is a hotfix for the issue detailed in #330
+
+### Fixes 🐞
+
+* Prevent invalid resource URIs by [@jlowin](https://github.com/jlowin) in [#336](https://github.com/PrefectHQ/fastmcp/pull/336)
+* Coerce numbers to str by [@jlowin](https://github.com/jlowin) in [#337](https://github.com/PrefectHQ/fastmcp/pull/337)
+
+### Docs 📚
+
+* Add client badge by [@jlowin](https://github.com/jlowin) in [#327](https://github.com/PrefectHQ/fastmcp/pull/327)
+* Update bug.yml by [@jlowin](https://github.com/jlowin) in [#328](https://github.com/PrefectHQ/fastmcp/pull/328)
+
+### Other Changes 🦾
+
+* Update quickstart.mdx example to include import by [@discdiver](https://github.com/discdiver) in [#329](https://github.com/PrefectHQ/fastmcp/pull/329)
+
+### New Contributors
+
+* [@discdiver](https://github.com/discdiver) made their first contribution in [#329](https://github.com/PrefectHQ/fastmcp/pull/329)
+
+**Full Changelog**: [v2.2.8...v2.2.9](https://github.com/PrefectHQ/fastmcp/compare/v2.2.8...v2.2.9)
+</Update>
+
+<Update label="v2.2.8" description="2024-05-05">
+
+## [v2.2.8: Parse and Recreation](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.8)
+
+### New Features 🎉
+
+* Replace custom parsing with TypeAdapter by [@jlowin](https://github.com/jlowin) in [#314](https://github.com/PrefectHQ/fastmcp/pull/314)
+* Handle \*args/\*\*kwargs appropriately for various components by [@jlowin](https://github.com/jlowin) in [#317](https://github.com/PrefectHQ/fastmcp/pull/317)
+* Add timeout-graceful-shutdown as a default config for SSE app by [@jlowin](https://github.com/jlowin) in [#323](https://github.com/PrefectHQ/fastmcp/pull/323)
+* Ensure prompts return descriptions by [@jlowin](https://github.com/jlowin) in [#325](https://github.com/PrefectHQ/fastmcp/pull/325)
+
+### Fixes 🐞
+
+* Ensure that tool serialization has a graceful fallback by [@jlowin](https://github.com/jlowin) in [#310](https://github.com/PrefectHQ/fastmcp/pull/310)
+
+### Docs 📚
+
+* Update docs for clarity by [@jlowin](https://github.com/jlowin) in [#312](https://github.com/PrefectHQ/fastmcp/pull/312)
+
+### Other Changes 🦾
+
+* Remove is\_async attribute by [@jlowin](https://github.com/jlowin) in [#315](https://github.com/PrefectHQ/fastmcp/pull/315)
+* Dry out retrieving context kwarg by [@jlowin](https://github.com/jlowin) in [#316](https://github.com/PrefectHQ/fastmcp/pull/316)
+
+**Full Changelog**: [v2.2.7...v2.2.8](https://github.com/PrefectHQ/fastmcp/compare/v2.2.7...v2.2.8)
+</Update>
+
+<Update label="v2.2.7" description="2024-05-03">
+
+## [v2.2.7: You Auth to Know Better](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.7)
+
+### New Features 🎉
+
+* use pydantic\_core.to\_json by [@jlowin](https://github.com/jlowin) in [#290](https://github.com/PrefectHQ/fastmcp/pull/290)
+* Ensure openapi descriptions are included in tool details by [@jlowin](https://github.com/jlowin) in [#293](https://github.com/PrefectHQ/fastmcp/pull/293)
+* Bump mcp to 1.7.1 by [@jlowin](https://github.com/jlowin) in [#298](https://github.com/PrefectHQ/fastmcp/pull/298)
+* Add support for tool annotations by [@jlowin](https://github.com/jlowin) in [#299](https://github.com/PrefectHQ/fastmcp/pull/299)
+* Add auth support by [@jlowin](https://github.com/jlowin) in [#300](https://github.com/PrefectHQ/fastmcp/pull/300)
+* Add low-level methods to client by [@jlowin](https://github.com/jlowin) in [#301](https://github.com/PrefectHQ/fastmcp/pull/301)
+* Add method for retrieving current starlette request to FastMCP context by [@jlowin](https://github.com/jlowin) in [#302](https://github.com/PrefectHQ/fastmcp/pull/302)
+* get\_starlette\_request → get\_http\_request by [@jlowin](https://github.com/jlowin) in [#303](https://github.com/PrefectHQ/fastmcp/pull/303)
+* Support custom Serializer for Tools by [@strawgate](https://github.com/strawgate) in [#308](https://github.com/PrefectHQ/fastmcp/pull/308)
+* Support proxy mount by [@jlowin](https://github.com/jlowin) in [#309](https://github.com/PrefectHQ/fastmcp/pull/309)
+
+### Other Changes 🦾
+
+* Improve context injection type checks by [@jlowin](https://github.com/jlowin) in [#291](https://github.com/PrefectHQ/fastmcp/pull/291)
+* add readme to smarthome example by [@zzstoatzz](https://github.com/zzstoatzz) in [#294](https://github.com/PrefectHQ/fastmcp/pull/294)
+
+**Full Changelog**: [v2.2.6...v2.2.7](https://github.com/PrefectHQ/fastmcp/compare/v2.2.6...v2.2.7)
+</Update>
+
+<Update label="v2.2.6" description="2024-04-30">
+
+## [v2.2.6: The REST is History](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.6)
+
+### New Features 🎉
+
+* Added feature : Load MCP server using config by [@sandipan1](https://github.com/sandipan1) in [#260](https://github.com/PrefectHQ/fastmcp/pull/260)
+* small typing fixes by [@zzstoatzz](https://github.com/zzstoatzz) in [#237](https://github.com/PrefectHQ/fastmcp/pull/237)
+* Expose configurable timeout for OpenAPI by [@jlowin](https://github.com/jlowin) in [#279](https://github.com/PrefectHQ/fastmcp/pull/279)
+* Lower websockets pin for compatibility by [@jlowin](https://github.com/jlowin) in [#286](https://github.com/PrefectHQ/fastmcp/pull/286)
+* Improve OpenAPI param handling by [@jlowin](https://github.com/jlowin) in [#287](https://github.com/PrefectHQ/fastmcp/pull/287)
+
+### Fixes 🐞
+
+* Ensure openapi tool responses are properly converted by [@jlowin](https://github.com/jlowin) in [#283](https://github.com/PrefectHQ/fastmcp/pull/283)
+* Fix OpenAPI examples by [@jlowin](https://github.com/jlowin) in [#285](https://github.com/PrefectHQ/fastmcp/pull/285)
+* Fix client docs for advanced features, add tests for logging by [@jlowin](https://github.com/jlowin) in [#284](https://github.com/PrefectHQ/fastmcp/pull/284)
+
+### Other Changes 🦾
+
+* add testing doc by [@jlowin](https://github.com/jlowin) in [#264](https://github.com/PrefectHQ/fastmcp/pull/264)
+* #267 Fix openapi template resource to support multiple path parameters by [@jeger-at](https://github.com/jeger-at) in [#278](https://github.com/PrefectHQ/fastmcp/pull/278)
+
+### New Contributors
+
+* [@sandipan1](https://github.com/sandipan1) made their first contribution in [#260](https://github.com/PrefectHQ/fastmcp/pull/260)
+* [@jeger-at](https://github.com/jeger-at) made their first contribution in [#278](https://github.com/PrefectHQ/fastmcp/pull/278)
+
+**Full Changelog**: [v2.2.5...v2.2.6](https://github.com/PrefectHQ/fastmcp/compare/v2.2.5...v2.2.6)
+</Update>
+
+<Update label="v2.2.5" description="2024-04-26">
+
+## [v2.2.5: Context Switching](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.5)
+
+### New Features 🎉
+
+* Add tests for tool return types; improve serialization behavior by [@jlowin](https://github.com/jlowin) in [#262](https://github.com/PrefectHQ/fastmcp/pull/262)
+* Support context injection in resources, templates, and prompts (like tools) by [@jlowin](https://github.com/jlowin) in [#263](https://github.com/PrefectHQ/fastmcp/pull/263)
+
+### Docs 📚
+
+* Update wildcards to 2.2.4 by [@jlowin](https://github.com/jlowin) in [#257](https://github.com/PrefectHQ/fastmcp/pull/257)
+* Update note in templates docs by [@jlowin](https://github.com/jlowin) in [#258](https://github.com/PrefectHQ/fastmcp/pull/258)
+* Significant documentation and test expansion for tool input types by [@jlowin](https://github.com/jlowin) in [#261](https://github.com/PrefectHQ/fastmcp/pull/261)
+
+**Full Changelog**: [v2.2.4...v2.2.5](https://github.com/PrefectHQ/fastmcp/compare/v2.2.4...v2.2.5)
+</Update>
+
+<Update label="v2.2.4" description="2024-04-25">
+
+## [v2.2.4: The Wild Side, Actually](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.4)
+
+The wildcard URI templates exposed in v2.2.3 were blocked by a server-level check which is removed in this release.
+
+### New Features 🎉
+
+* Allow customization of inspector proxy port, ui port, and version by [@jlowin](https://github.com/jlowin) in [#253](https://github.com/PrefectHQ/fastmcp/pull/253)
+
+### Fixes 🐞
+
+* fix: unintended type convert by [@cutekibry](https://github.com/cutekibry) in [#252](https://github.com/PrefectHQ/fastmcp/pull/252)
+* Ensure openapi resources return valid responses by [@jlowin](https://github.com/jlowin) in [#254](https://github.com/PrefectHQ/fastmcp/pull/254)
+* Ensure servers expose template wildcards by [@jlowin](https://github.com/jlowin) in [#256](https://github.com/PrefectHQ/fastmcp/pull/256)
+
+### Docs 📚
+
+* Update README.md Grammar error by [@TechWithTy](https://github.com/TechWithTy) in [#249](https://github.com/PrefectHQ/fastmcp/pull/249)
+
+### Other Changes 🦾
+
+* Add resource template tests by [@jlowin](https://github.com/jlowin) in [#255](https://github.com/PrefectHQ/fastmcp/pull/255)
+
+### New Contributors
+
+* [@TechWithTy](https://github.com/TechWithTy) made their first contribution in [#249](https://github.com/PrefectHQ/fastmcp/pull/249)
+* [@cutekibry](https://github.com/cutekibry) made their first contribution in [#252](https://github.com/PrefectHQ/fastmcp/pull/252)
+
+**Full Changelog**: [v2.2.3...v2.2.4](https://github.com/PrefectHQ/fastmcp/compare/v2.2.3...v2.2.4)
+</Update>
+
+<Update label="v2.2.3" description="2024-04-25">
+
+## [v2.2.3: The Wild Side](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.3)
+
+### New Features 🎉
+
+* Add wildcard params for resource templates by [@jlowin](https://github.com/jlowin) in [#246](https://github.com/PrefectHQ/fastmcp/pull/246)
+
+### Docs 📚
+
+* Indicate that Image class is for returns by [@jlowin](https://github.com/jlowin) in [#242](https://github.com/PrefectHQ/fastmcp/pull/242)
+* Update mermaid diagram by [@jlowin](https://github.com/jlowin) in [#243](https://github.com/PrefectHQ/fastmcp/pull/243)
+
+### Other Changes 🦾
+
+* update version badges by [@jlowin](https://github.com/jlowin) in [#248](https://github.com/PrefectHQ/fastmcp/pull/248)
+
+**Full Changelog**: [v2.2.2...v2.2.3](https://github.com/PrefectHQ/fastmcp/compare/v2.2.2...v2.2.3)
+</Update>
+
+<Update label="v2.2.2" description="2024-04-24">
+
+## [v2.2.2: Prompt and Circumstance](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.2)
+
+### New Features 🎉
+
+* Add prompt support by [@jlowin](https://github.com/jlowin) in [#235](https://github.com/PrefectHQ/fastmcp/pull/235)
+
+### Fixes 🐞
+
+* Ensure that resource templates are properly exposed by [@jlowin](https://github.com/jlowin) in [#238](https://github.com/PrefectHQ/fastmcp/pull/238)
+
+### Docs 📚
+
+* Update docs for prompts by [@jlowin](https://github.com/jlowin) in [#236](https://github.com/PrefectHQ/fastmcp/pull/236)
+
+### Other Changes 🦾
+
+* Add prompt tests by [@jlowin](https://github.com/jlowin) in [#239](https://github.com/PrefectHQ/fastmcp/pull/239)
+
+**Full Changelog**: [v2.2.1...v2.2.2](https://github.com/PrefectHQ/fastmcp/compare/v2.2.1...v2.2.2)
+</Update>
+
+<Update label="v2.2.1" description="2024-04-23">
+
+## [v2.2.1: Template for Success](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.1)
+
+### New Features 🎉
+
+* Add resource templates by [@jlowin](https://github.com/jlowin) in [#230](https://github.com/PrefectHQ/fastmcp/pull/230)
+
+### Fixes 🐞
+
+* Ensure that resource templates are properly exposed by [@jlowin](https://github.com/jlowin) in [#231](https://github.com/PrefectHQ/fastmcp/pull/231)
+
+### Docs 📚
+
+* Update docs for resource templates by [@jlowin](https://github.com/jlowin) in [#232](https://github.com/PrefectHQ/fastmcp/pull/232)
+
+### Other Changes 🦾
+
+* Add resource template tests by [@jlowin](https://github.com/jlowin) in [#233](https://github.com/PrefectHQ/fastmcp/pull/233)
+
+**Full Changelog**: [v2.2.0...v2.2.1](https://github.com/PrefectHQ/fastmcp/compare/v2.2.0...v2.2.1)
+</Update>
+
+<Update label="v2.2.0" description="2024-04-22">
+
+## [v2.2.0: Compose Yourself](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.0)
+
+### New Features 🎉
+
+* Add support for mounting FastMCP servers by [@jlowin](https://github.com/jlowin) in [#175](https://github.com/PrefectHQ/fastmcp/pull/175)
+* Add support for duplicate behavior == ignore by [@jlowin](https://github.com/jlowin) in [#169](https://github.com/PrefectHQ/fastmcp/pull/169)
+
+### Breaking Changes 🛫
+
+* Refactor MCP composition by [@jlowin](https://github.com/jlowin) in [#176](https://github.com/PrefectHQ/fastmcp/pull/176)
+
+### Docs 📚
+
+* Improve integration documentation by [@jlowin](https://github.com/jlowin) in [#184](https://github.com/PrefectHQ/fastmcp/pull/184)
+* Improve documentation by [@jlowin](https://github.com/jlowin) in [#185](https://github.com/PrefectHQ/fastmcp/pull/185)
+
+### Other Changes 🦾
+
+* Add transport kwargs for mcp.run() and fastmcp run by [@jlowin](https://github.com/jlowin) in [#161](https://github.com/PrefectHQ/fastmcp/pull/161)
+* Allow resource templates to have optional / excluded arguments by [@jlowin](https://github.com/jlowin) in [#164](https://github.com/PrefectHQ/fastmcp/pull/164)
+* Update resources.mdx by [@jlowin](https://github.com/jlowin) in [#165](https://github.com/PrefectHQ/fastmcp/pull/165)
+
+### New Contributors
+
+* [@kongqi404](https://github.com/kongqi404) made their first contribution in [#181](https://github.com/PrefectHQ/fastmcp/pull/181)
+
+**Full Changelog**: [v2.1.2...v2.2.0](https://github.com/PrefectHQ/fastmcp/compare/v2.1.2...v2.2.0)
+</Update>
+
+<Update label="v2.1.2" description="2024-04-14">
+
+## [v2.1.2: Copy That, Good Buddy](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.1.2)
+
+The main improvement in this release is a fix that allows FastAPI / OpenAPI-generated servers to be mounted as sub-servers.
+
+### Fixes 🐞
+
+* Ensure objects are copied properly and test mounting fastapi by [@jlowin](https://github.com/jlowin) in [#153](https://github.com/PrefectHQ/fastmcp/pull/153)
+
+### Docs 📚
+
+* Fix broken links in docs by [@jlowin](https://github.com/jlowin) in [#154](https://github.com/PrefectHQ/fastmcp/pull/154)
+
+### Other Changes 🦾
+
+* Update README.md by [@jlowin](https://github.com/jlowin) in [#149](https://github.com/PrefectHQ/fastmcp/pull/149)
+* Only apply log config to FastMCP loggers by [@jlowin](https://github.com/jlowin) in [#155](https://github.com/PrefectHQ/fastmcp/pull/155)
+* Update pyproject.toml by [@jlowin](https://github.com/jlowin) in [#156](https://github.com/PrefectHQ/fastmcp/pull/156)
+
+**Full Changelog**: [v2.1.1...v2.1.2](https://github.com/PrefectHQ/fastmcp/compare/v2.1.1...v2.1.2)
+</Update>
+
+<Update label="v2.1.1" description="2024-04-14">
+
+## [v2.1.1: Doc Holiday](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.1.1)
+
+FastMCP's docs are now available at gofastmcp.com.
+
+### Docs 📚
+
+* Add docs by [@jlowin](https://github.com/jlowin) in [#136](https://github.com/PrefectHQ/fastmcp/pull/136)
+* Add docs link to readme by [@jlowin](https://github.com/jlowin) in [#137](https://github.com/PrefectHQ/fastmcp/pull/137)
+* Minor docs updates by [@jlowin](https://github.com/jlowin) in [#138](https://github.com/PrefectHQ/fastmcp/pull/138)
+
+### Fixes 🐞
+
+* fix branch name in example by [@zzstoatzz](https://github.com/zzstoatzz) in [#140](https://github.com/PrefectHQ/fastmcp/pull/140)
+
+### Other Changes 🦾
+
+* smart home example by [@zzstoatzz](https://github.com/zzstoatzz) in [#115](https://github.com/PrefectHQ/fastmcp/pull/115)
+* Remove mac os tests by [@jlowin](https://github.com/jlowin) in [#142](https://github.com/PrefectHQ/fastmcp/pull/142)
+* Expand support for various method interactions by [@jlowin](https://github.com/jlowin) in [#143](https://github.com/PrefectHQ/fastmcp/pull/143)
+* Update docs and add\_resource\_fn by [@jlowin](https://github.com/jlowin) in [#144](https://github.com/PrefectHQ/fastmcp/pull/144)
+* Update description by [@jlowin](https://github.com/jlowin) in [#145](https://github.com/PrefectHQ/fastmcp/pull/145)
+* Support openapi 3.0 and 3.1 by [@jlowin](https://github.com/jlowin) in [#147](https://github.com/PrefectHQ/fastmcp/pull/147)
+
+**Full Changelog**: [v2.1.0...v2.1.1](https://github.com/PrefectHQ/fastmcp/compare/v2.1.0...v2.1.1)
+</Update>
+
+<Update label="v2.1.0" description="2024-04-13">
+
+## [v2.1.0: Tag, You're It](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.1.0)
+
+The primary motivation for this release is the fix in #128 for Claude desktop compatibility, but the primary new feature of this release is per-object tags. Currently these are for bookkeeping only but will become useful in future releases.
+
+### New Features 🎉
+
+* Add tags for all core MCP objects by [@jlowin](https://github.com/jlowin) in [#121](https://github.com/PrefectHQ/fastmcp/pull/121)
+* Ensure that openapi tags are transferred to MCP objects by [@jlowin](https://github.com/jlowin) in [#124](https://github.com/PrefectHQ/fastmcp/pull/124)
+
+### Fixes 🐞
+
+* Change default mounted tool separator from / to \_ by [@jlowin](https://github.com/jlowin) in [#128](https://github.com/PrefectHQ/fastmcp/pull/128)
+* Enter mounted app lifespans by [@jlowin](https://github.com/jlowin) in [#129](https://github.com/PrefectHQ/fastmcp/pull/129)
+* Fix CLI that called mcp instead of fastmcp by [@jlowin](https://github.com/jlowin) in [#128](https://github.com/PrefectHQ/fastmcp/pull/128)
+
+### Breaking Changes 🛫
+
+* Changed configuration for duplicate resources/tools/prompts by [@jlowin](https://github.com/jlowin) in [#121](https://github.com/PrefectHQ/fastmcp/pull/121)
+* Improve client return types by [@jlowin](https://github.com/jlowin) in [#123](https://github.com/PrefectHQ/fastmcp/pull/123)
+
+### Other Changes 🦾
+
+* Add tests for tags in server decorators by [@jlowin](https://github.com/jlowin) in [#122](https://github.com/PrefectHQ/fastmcp/pull/122)
+* Clean up server tests by [@jlowin](https://github.com/jlowin) in [#125](https://github.com/PrefectHQ/fastmcp/pull/125)
+
+**Full Changelog**: [v2.0.0...v2.1.0](https://github.com/PrefectHQ/fastmcp/compare/v2.0.0...v2.1.0)
+</Update>
+
+<Update label="v2.0.0" description="2024-04-11">
+
+## [v2.0.0: Second to None](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.0.0)
+
+### New Features 🎉
+
+* Support mounting FastMCP instances as sub-MCPs by [@jlowin](https://github.com/jlowin) in [#99](https://github.com/PrefectHQ/fastmcp/pull/99)
+* Add in-memory client for calling FastMCP servers (and tests) by [@jlowin](https://github.com/jlowin) in [#100](https://github.com/PrefectHQ/fastmcp/pull/100)
+* Add MCP proxy server by [@jlowin](https://github.com/jlowin) in [#105](https://github.com/PrefectHQ/fastmcp/pull/105)
+* Update FastMCP for upstream changes by [@jlowin](https://github.com/jlowin) in [#107](https://github.com/PrefectHQ/fastmcp/pull/107)
+* Generate FastMCP servers from OpenAPI specs and FastAPI by [@jlowin](https://github.com/jlowin) in [#110](https://github.com/PrefectHQ/fastmcp/pull/110)
+* Reorganize all client / transports by [@jlowin](https://github.com/jlowin) in [#111](https://github.com/PrefectHQ/fastmcp/pull/111)
+* Add sampling and roots by [@jlowin](https://github.com/jlowin) in [#117](https://github.com/PrefectHQ/fastmcp/pull/117)
+
+### Fixes 🐞
+
+* Fix bug with tools that return lists by [@jlowin](https://github.com/jlowin) in [#116](https://github.com/PrefectHQ/fastmcp/pull/116)
+
+### Other Changes 🦾
+
+* Add back FastMCP CLI by [@jlowin](https://github.com/jlowin) in [#108](https://github.com/PrefectHQ/fastmcp/pull/108)
+* Update Readme for v2 by [@jlowin](https://github.com/jlowin) in [#112](https://github.com/PrefectHQ/fastmcp/pull/112)
+* fix deprecation warnings by [@zzstoatzz](https://github.com/zzstoatzz) in [#113](https://github.com/PrefectHQ/fastmcp/pull/113)
+* Readme by [@jlowin](https://github.com/jlowin) in [#118](https://github.com/PrefectHQ/fastmcp/pull/118)
+* FastMCP 2.0 by [@jlowin](https://github.com/jlowin) in [#119](https://github.com/PrefectHQ/fastmcp/pull/119)
+
+**Full Changelog**: [v1.0...v2.0.0](https://github.com/PrefectHQ/fastmcp/compare/v1.0...v2.0.0)
+</Update>
+
+<Update label="v1.0" description="2024-04-11">
+
+## [v1.0: It's Official](https://github.com/PrefectHQ/fastmcp/releases/tag/v1.0)
+
+This release commemorates FastMCP 1.0, which is included in the official Model Context Protocol SDK:
+
+```python
+from mcp.server.fastmcp import FastMCP
+```
+
+To the best of my knowledge, v1 is identical to the upstream version included with `mcp`.
+
+### Docs 📚
+
+* Update readme to redirect to the official SDK by [@jlowin](https://github.com/jlowin) in [#79](https://github.com/PrefectHQ/fastmcp/pull/79)
+
+### Other Changes 🦾
+
+* fix: use Mount instead of Route for SSE message handling by [@samihamine](https://github.com/samihamine) in [#77](https://github.com/PrefectHQ/fastmcp/pull/77)
+
+### New Contributors
+
+* [@samihamine](https://github.com/samihamine) made their first contribution in [#77](https://github.com/PrefectHQ/fastmcp/pull/77)
+
+**Full Changelog**: [v0.4.1...v1.0](https://github.com/PrefectHQ/fastmcp/compare/v0.4.1...v1.0)
+</Update>
+
+<Update label="v0.4.1" description="2024-12-09">
+
+## [v0.4.1: String Theory](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.4.1)
+
+### Fixes 🐞
+
+* fix: handle strings containing numbers correctly by [@sd2k](https://github.com/sd2k) in [#63](https://github.com/PrefectHQ/fastmcp/pull/63)
+
+### Docs 📚
+
+* patch: Update pyproject.toml license by [@leonkozlowski](https://github.com/leonkozlowski) in [#67](https://github.com/PrefectHQ/fastmcp/pull/67)
+
+### Other Changes 🦾
+
+* Avoid new try\_eval\_type unavailable with older pydantic by [@jurasofish](https://github.com/jurasofish) in [#57](https://github.com/PrefectHQ/fastmcp/pull/57)
+* Decorator typing by [@jurasofish](https://github.com/jurasofish) in [#56](https://github.com/PrefectHQ/fastmcp/pull/56)
+
+### New Contributors
+
+* [@leonkozlowski](https://github.com/leonkozlowski) made their first contribution in [#67](https://github.com/PrefectHQ/fastmcp/pull/67)
+
+**Full Changelog**: [v0.4.0...v0.4.1](https://github.com/PrefectHQ/fastmcp/compare/v0.4.0...v0.4.1)
+</Update>
+
+<Update label="v0.4.0" description="2024-12-05">
+
+## [v0.4.0: Nice to MIT You](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.4.0)
+
+This is a relatively small release in terms of features, but the version is bumped to 0.4 to reflect that the code is being relicensed from Apache 2.0 to MIT. This is to facilitate FastMCP's inclusion in the official MCP SDK.
+
+### New Features 🎉
+
+* Add pyright + tests by [@jlowin](https://github.com/jlowin) in [#52](https://github.com/PrefectHQ/fastmcp/pull/52)
+* add pgvector memory example by [@zzstoatzz](https://github.com/zzstoatzz) in [#49](https://github.com/PrefectHQ/fastmcp/pull/49)
+
+### Fixes 🐞
+
+* fix: use stderr for logging by [@sd2k](https://github.com/sd2k) in [#51](https://github.com/PrefectHQ/fastmcp/pull/51)
+
+### Docs 📚
+
+* Update ai-labeler.yml by [@jlowin](https://github.com/jlowin) in [#48](https://github.com/PrefectHQ/fastmcp/pull/48)
+* Relicense from Apache 2.0 to MIT by [@jlowin](https://github.com/jlowin) in [#54](https://github.com/PrefectHQ/fastmcp/pull/54)
+
+### Other Changes 🦾
+
+* fix warning and flake by [@zzstoatzz](https://github.com/zzstoatzz) in [#47](https://github.com/PrefectHQ/fastmcp/pull/47)
+
+### New Contributors
+
+* [@sd2k](https://github.com/sd2k) made their first contribution in [#51](https://github.com/PrefectHQ/fastmcp/pull/51)
+
+**Full Changelog**: [v0.3.5...v0.4.0](https://github.com/PrefectHQ/fastmcp/compare/v0.3.5...v0.4.0)
+</Update>
+
+<Update label="v0.3.5" description="2024-12-03">
+
+## [v0.3.5: Windows of Opportunity](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.3.5)
+
+This release is highlighted by the ability to handle complex JSON objects as MCP inputs and improved Windows compatibility.
+
+### New Features 🎉
+
+* Set up multiple os tests by [@jlowin](https://github.com/jlowin) in [#44](https://github.com/PrefectHQ/fastmcp/pull/44)
+* Changes to accommodate windows users. by [@justjoehere](https://github.com/justjoehere) in [#42](https://github.com/PrefectHQ/fastmcp/pull/42)
+* Handle complex inputs by [@jurasofish](https://github.com/jurasofish) in [#31](https://github.com/PrefectHQ/fastmcp/pull/31)
+
+### Docs 📚
+
+* Make AI labeler more conservative by [@jlowin](https://github.com/jlowin) in [#46](https://github.com/PrefectHQ/fastmcp/pull/46)
+
+### Other Changes 🦾
+
+* Additional Windows Fixes for Dev running and for importing modules in a server by [@justjoehere](https://github.com/justjoehere) in [#43](https://github.com/PrefectHQ/fastmcp/pull/43)
+
+### New Contributors
+
+* [@justjoehere](https://github.com/justjoehere) made their first contribution in [#42](https://github.com/PrefectHQ/fastmcp/pull/42)
+* [@jurasofish](https://github.com/jurasofish) made their first contribution in [#31](https://github.com/PrefectHQ/fastmcp/pull/31)
+
+**Full Changelog**: [v0.3.4...v0.3.5](https://github.com/PrefectHQ/fastmcp/compare/v0.3.4...v0.3.5)
+</Update>
+
+<Update label="v0.3.4" description="2024-12-02">
+
+## [v0.3.4: URL's Well That Ends Well](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.3.4)
+
+### Fixes 🐞
+
+* Handle missing config file when installing by [@jlowin](https://github.com/jlowin) in [#37](https://github.com/PrefectHQ/fastmcp/pull/37)
+* Remove BaseURL reference and use AnyURL by [@jlowin](https://github.com/jlowin) in [#40](https://github.com/PrefectHQ/fastmcp/pull/40)
+
+**Full Changelog**: [v0.3.3...v0.3.4](https://github.com/PrefectHQ/fastmcp/compare/v0.3.3...v0.3.4)
+</Update>
+
+<Update label="v0.3.3" description="2024-12-02">
+
+## [v0.3.3: Dependence Day](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.3.3)
+
+### New Features 🎉
+
+* Surge example by [@zzstoatzz](https://github.com/zzstoatzz) in [#29](https://github.com/PrefectHQ/fastmcp/pull/29)
+* Support Python dependencies in Server by [@jlowin](https://github.com/jlowin) in [#34](https://github.com/PrefectHQ/fastmcp/pull/34)
+
+### Docs 📚
+
+* add `Contributing` section to README by [@zzstoatzz](https://github.com/zzstoatzz) in [#32](https://github.com/PrefectHQ/fastmcp/pull/32)
+
+**Full Changelog**: [v0.3.2...v0.3.3](https://github.com/PrefectHQ/fastmcp/compare/v0.3.2...v0.3.3)
+</Update>
+
+<Update label="v0.3.2" date="2024-12-01" description="Green with ENVy">
+
+## [v0.3.2: Green with ENVy](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.3.2)
+
+### New Features 🎉
+
+* Support env vars when installing by [@jlowin](https://github.com/jlowin) in [#27](https://github.com/PrefectHQ/fastmcp/pull/27)
+
+### Docs 📚
+
+* Remove top level env var by [@jlowin](https://github.com/jlowin) in [#28](https://github.com/PrefectHQ/fastmcp/pull/28)
+
+**Full Changelog**: [v0.3.1...v0.3.2](https://github.com/PrefectHQ/fastmcp/compare/v0.3.1...v0.3.2)
+</Update>
+
+<Update label="v0.3.1" description="2024-12-01">
+
+## [v0.3.1](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.3.1)
+
+### New Features 🎉
+
+* Update README.md by [@jlowin](https://github.com/jlowin) in [#23](https://github.com/PrefectHQ/fastmcp/pull/23)
+* add rich handler and dotenv loading for settings by [@zzstoatzz](https://github.com/zzstoatzz) in [#22](https://github.com/PrefectHQ/fastmcp/pull/22)
+* print exception when server can't start by [@jlowin](https://github.com/jlowin) in [#25](https://github.com/PrefectHQ/fastmcp/pull/25)
+
+### Docs 📚
+
+* Update README.md by [@jlowin](https://github.com/jlowin) in [#24](https://github.com/PrefectHQ/fastmcp/pull/24)
+
+### Other Changes 🦾
+
+* Remove log by [@jlowin](https://github.com/jlowin) in [#26](https://github.com/PrefectHQ/fastmcp/pull/26)
+
+**Full Changelog**: [v0.3.0...v0.3.1](https://github.com/PrefectHQ/fastmcp/compare/v0.3.0...v0.3.1)
+</Update>
+
+<Update label="v0.3.0" description="2024-12-01">
+
+## [v0.3.0: Prompt and Circumstance](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.3.0)
+
+### New Features 🎉
+
+* Update README by [@jlowin](https://github.com/jlowin) in [#3](https://github.com/PrefectHQ/fastmcp/pull/3)
+* Make log levels strings by [@jlowin](https://github.com/jlowin) in [#4](https://github.com/PrefectHQ/fastmcp/pull/4)
+* Make content method a function by [@jlowin](https://github.com/jlowin) in [#5](https://github.com/PrefectHQ/fastmcp/pull/5)
+* Add template support by [@jlowin](https://github.com/jlowin) in [#6](https://github.com/PrefectHQ/fastmcp/pull/6)
+* Refactor resources module by [@jlowin](https://github.com/jlowin) in [#7](https://github.com/PrefectHQ/fastmcp/pull/7)
+* Clean up cli imports by [@jlowin](https://github.com/jlowin) in [#8](https://github.com/PrefectHQ/fastmcp/pull/8)
+* Prepare to list templates by [@jlowin](https://github.com/jlowin) in [#11](https://github.com/PrefectHQ/fastmcp/pull/11)
+* Move image to separate module by [@jlowin](https://github.com/jlowin) in [#9](https://github.com/PrefectHQ/fastmcp/pull/9)
+* Add support for request context, progress, logging, etc. by [@jlowin](https://github.com/jlowin) in [#12](https://github.com/PrefectHQ/fastmcp/pull/12)
+* Add context tests and better runtime loads by [@jlowin](https://github.com/jlowin) in [#13](https://github.com/PrefectHQ/fastmcp/pull/13)
+* Refactor tools + resourcemanager by [@jlowin](https://github.com/jlowin) in [#14](https://github.com/PrefectHQ/fastmcp/pull/14)
+* func → fn everywhere by [@jlowin](https://github.com/jlowin) in [#15](https://github.com/PrefectHQ/fastmcp/pull/15)
+* Add support for prompts by [@jlowin](https://github.com/jlowin) in [#16](https://github.com/PrefectHQ/fastmcp/pull/16)
+* Create LICENSE by [@jlowin](https://github.com/jlowin) in [#18](https://github.com/PrefectHQ/fastmcp/pull/18)
+* Update cli file spec by [@jlowin](https://github.com/jlowin) in [#19](https://github.com/PrefectHQ/fastmcp/pull/19)
+* Update readmeUpdate README by [@jlowin](https://github.com/jlowin) in [#20](https://github.com/PrefectHQ/fastmcp/pull/20)
+* Use hatchling for version by [@jlowin](https://github.com/jlowin) in [#21](https://github.com/PrefectHQ/fastmcp/pull/21)
+
+### Other Changes 🦾
+
+* Add echo server by [@jlowin](https://github.com/jlowin) in [#1](https://github.com/PrefectHQ/fastmcp/pull/1)
+* Add github workflows by [@jlowin](https://github.com/jlowin) in [#2](https://github.com/PrefectHQ/fastmcp/pull/2)
+* typing updates by [@zzstoatzz](https://github.com/zzstoatzz) in [#17](https://github.com/PrefectHQ/fastmcp/pull/17)
+
+### New Contributors
+
+* [@jlowin](https://github.com/jlowin) made their first contribution in [#1](https://github.com/PrefectHQ/fastmcp/pull/1)
+* [@zzstoatzz](https://github.com/zzstoatzz) made their first contribution in [#17](https://github.com/PrefectHQ/fastmcp/pull/17)
+
+**Full Changelog**: [v0.2.0...v0.3.0](https://github.com/PrefectHQ/fastmcp/compare/v0.2.0...v0.3.0)
+</Update>
+
+<Update label="v0.2.0" description="2024-11-30">
+
+## [v0.2.0](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.2.0)
+
+**Full Changelog**: [v0.1.0...v0.2.0](https://github.com/PrefectHQ/fastmcp/compare/v0.1.0...v0.2.0)
+</Update>
+
+<Update label="v0.1.0" description="2024-11-30">
+
+## [v0.1.0](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.1.0)
+
+The very first release of FastMCP! 🎉
+
+**Full Changelog**: [Initial commits](https://github.com/PrefectHQ/fastmcp/commits/v0.1.0)
+</Update>
\ No newline at end of file
diff --git a/docs/v2/clients/auth/bearer.mdx b/docs/v2/clients/auth/bearer.mdx
new file mode 100644
index 0000000..2e12fbc
--- /dev/null
+++ b/docs/v2/clients/auth/bearer.mdx
@@ -0,0 +1,88 @@
+---
+title: Bearer Token Authentication
+sidebarTitle: Bearer Auth
+description: Authenticate your FastMCP client with a Bearer token.
+icon: key
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.6.0" />
+
+<Tip>
+Bearer Token authentication is only relevant for HTTP-based transports.
+</Tip>
+
+You can configure your FastMCP client to use **bearer authentication** by supplying a valid access token. This is most appropriate for service accounts, long-lived API keys, CI/CD, applications where authentication is managed separately, or other non-interactive authentication methods.
+
+A Bearer token is a JSON Web Token (JWT) that is used to authenticate a request. It is most commonly used in the `Authorization` header of an HTTP request, using the `Bearer` scheme:
+
+```http
+Authorization: Bearer <token>
+```
+
+
+## Client Usage
+
+The most straightforward way to use a pre-existing Bearer token is to provide it as a string to the `auth` parameter of the `fastmcp.Client` or transport instance. FastMCP will automatically format it correctly for the `Authorization` header and bearer scheme.
+
+<Tip>
+If you're using a string token, do not include the `Bearer` prefix. FastMCP will add it for you.
+</Tip>
+
+```python {5}
+from fastmcp import Client
+
+async with Client(
+    "https://your-server.fastmcp.app/mcp", 
+    auth="<your-token>",
+) as client:
+    await client.ping()
+```
+
+You can also supply a Bearer token to a transport instance, such as `StreamableHttpTransport` or `SSETransport`:
+
+```python {6}
+from fastmcp import Client
+from fastmcp.client.transports import StreamableHttpTransport
+
+transport = StreamableHttpTransport(
+    "http://your-server.fastmcp.app/mcp", 
+    auth="<your-token>",
+)
+
+async with Client(transport) as client:
+    await client.ping()
+```
+
+## `BearerAuth` Helper
+
+If you prefer to be more explicit and not rely on FastMCP to transform your string token, you can use the `BearerAuth` class yourself, which implements the `httpx.Auth` interface.
+
+```python {6}
+from fastmcp import Client
+from fastmcp.client.auth import BearerAuth
+
+async with Client(
+    "https://your-server.fastmcp.app/mcp", 
+    auth=BearerAuth(token="<your-token>"),
+) as client:
+    await client.ping()
+```
+
+## Custom Headers
+
+If the MCP server expects a custom header or token scheme, you can manually set the client's `headers` instead of using the `auth` parameter by setting them on your transport:
+
+```python {5}
+from fastmcp import Client
+from fastmcp.client.transports import StreamableHttpTransport
+
+async with Client(
+    transport=StreamableHttpTransport(
+        "https://your-server.fastmcp.app/mcp", 
+        headers={"X-API-Key": "<your-token>"},
+    ),
+) as client:
+    await client.ping()
+```
diff --git a/docs/v2/clients/auth/oauth.mdx b/docs/v2/clients/auth/oauth.mdx
new file mode 100644
index 0000000..adc1160
--- /dev/null
+++ b/docs/v2/clients/auth/oauth.mdx
@@ -0,0 +1,132 @@
+---
+title: OAuth Authentication
+sidebarTitle: OAuth
+description: Authenticate your FastMCP client via OAuth 2.1.
+icon: window
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.6.0" />
+
+<Tip>
+OAuth authentication is only relevant for HTTP-based transports and requires user interaction via a web browser.
+</Tip>
+
+When your FastMCP client needs to access an MCP server protected by OAuth 2.1, and the process requires user interaction (like logging in and granting consent), you should use the Authorization Code Flow. FastMCP provides the `fastmcp.client.auth.OAuth` helper to simplify this entire process.
+
+This flow is common for user-facing applications where the application acts on behalf of the user.
+
+## Client Usage
+
+
+### Default Configuration
+
+The simplest way to use OAuth is to pass the string `"oauth"` to the `auth` parameter of the `Client` or transport instance. FastMCP will automatically configure the client to use OAuth with default settings:
+
+```python {4}
+from fastmcp import Client
+
+# Uses default OAuth settings
+async with Client("https://your-server.fastmcp.app/mcp", auth="oauth") as client:
+    await client.ping()
+```
+
+
+### `OAuth` Helper
+
+To fully configure the OAuth flow, use the `OAuth` helper and pass it to the `auth` parameter of the `Client` or transport instance. `OAuth` manages the complexities of the OAuth 2.1 Authorization Code Grant with PKCE (Proof Key for Code Exchange) for enhanced security, and implements the full `httpx.Auth` interface.
+
+```python {2, 4, 6}
+from fastmcp import Client
+from fastmcp.client.auth import OAuth
+
+oauth = OAuth(mcp_url="https://your-server.fastmcp.app/mcp")
+
+async with Client("https://your-server.fastmcp.app/mcp", auth=oauth) as client:
+    await client.ping()
+```
+
+#### `OAuth` Parameters
+
+- **`mcp_url`** (`str`): The full URL of the target MCP server endpoint. Used to discover OAuth server metadata
+- **`scopes`** (`str | list[str]`, optional): OAuth scopes to request. Can be space-separated string or list of strings
+- **`client_name`** (`str`, optional): Client name for dynamic registration. Defaults to `"FastMCP Client"`
+- **`token_storage`** (`AsyncKeyValue`, optional): Storage backend for persisting OAuth tokens. Defaults to in-memory storage (tokens lost on restart). See [Token Storage](#token-storage) for encrypted storage options
+- **`additional_client_metadata`** (`dict[str, Any]`, optional): Extra metadata for client registration
+- **`callback_port`** (`int`, optional): Fixed port for OAuth callback server. If not specified, uses a random available port
+
+
+## OAuth Flow
+
+The OAuth flow is triggered when you use a FastMCP `Client` configured to use OAuth.
+
+<Steps>
+<Step title="Token Check">
+The client first checks the configured `token_storage` backend for existing, valid tokens for the target server. If one is found, it will be used to authenticate the client.
+</Step>
+<Step title="OAuth Server Discovery">
+If no valid tokens exist, the client attempts to discover the OAuth server's endpoints using a well-known URI (e.g., `/.well-known/oauth-authorization-server`) based on the `mcp_url`.
+</Step>
+<Step title="Dynamic Client Registration">
+If the OAuth server supports it and the client isn't already registered (or credentials aren't cached), the client performs dynamic client registration according to RFC 7591.
+</Step>
+<Step title="Local Callback Server">
+A temporary local HTTP server is started on an available port (or the port specified via `callback_port`). This server's address (e.g., `http://127.0.0.1:<port>/callback`) acts as the `redirect_uri` for the OAuth flow.
+</Step>
+<Step title="Browser Interaction">
+The user's default web browser is automatically opened, directing them to the OAuth server's authorization endpoint. The user logs in and grants (or denies) the requested `scopes`.
+</Step>
+<Step title="Authorization Code & Token Exchange">
+Upon approval, the OAuth server redirects the user's browser to the local callback server with an `authorization_code`. The client captures this code and exchanges it with the OAuth server's token endpoint for an `access_token` (and often a `refresh_token`) using PKCE for security.
+</Step>
+<Step title="Token Caching">
+The obtained tokens are saved to the configured `token_storage` backend for future use, eliminating the need for repeated browser interactions.
+</Step>
+<Step title="Authenticated Requests">
+The access token is automatically included in the `Authorization` header for requests to the MCP server.
+</Step>
+<Step title="Refresh Token">
+If the access token expires, the client will automatically use the refresh token to get a new access token.
+</Step>
+</Steps>
+
+## Token Storage
+
+<VersionBadge version="2.13.0" />
+
+By default, tokens are stored in memory and lost when your application restarts. For persistent storage, pass an `AsyncKeyValue`-compatible storage backend to the `token_storage` parameter.
+
+<Warning>
+**Security Consideration**: Use encrypted storage for production. MCP clients can accumulate OAuth credentials for many servers over time, and a compromised token store could expose access to multiple services.
+</Warning>
+
+```python
+from fastmcp import Client
+from fastmcp.client.auth import OAuth
+from key_value.aio.stores.disk import DiskStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+import os
+
+# Create encrypted disk storage
+encrypted_storage = FernetEncryptionWrapper(
+    key_value=DiskStore(directory="~/.fastmcp/oauth-tokens"),
+    fernet=Fernet(os.environ["OAUTH_STORAGE_ENCRYPTION_KEY"])
+)
+
+oauth = OAuth(
+    mcp_url="https://your-server.fastmcp.app/mcp",
+    token_storage=encrypted_storage
+)
+
+async with Client("https://your-server.fastmcp.app/mcp", auth=oauth) as client:
+    await client.ping()
+```
+
+You can use any `AsyncKeyValue`-compatible backend from the [key-value library](https://github.com/strawgate/py-key-value) including Redis, DynamoDB, and more. Wrap your storage in `FernetEncryptionWrapper` for encryption.
+
+<Note>
+When selecting a storage backend, review the [py-key-value documentation](https://github.com/strawgate/py-key-value) to understand the maturity level and limitations of your chosen backend. Some backends may be in preview or have constraints that affect production suitability.
+</Note>
diff --git a/docs/v2/clients/client.mdx b/docs/v2/clients/client.mdx
new file mode 100644
index 0000000..4293e02
--- /dev/null
+++ b/docs/v2/clients/client.mdx
@@ -0,0 +1,340 @@
+---
+title: The FastMCP Client
+sidebarTitle: Overview
+description: Programmatic client for interacting with MCP servers through a well-typed, Pythonic interface.
+icon: user-robot
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.0.0" />
+
+The central piece of MCP client applications is the `fastmcp.Client` class. This class provides a **programmatic interface** for interacting with any Model Context Protocol (MCP) server, handling protocol details and connection management automatically.
+
+The FastMCP Client is designed for deterministic, controlled interactions rather than autonomous behavior, making it ideal for:
+
+- **Testing MCP servers** during development
+- **Building deterministic applications** that need reliable MCP interactions  
+- **Creating the foundation for agentic or LLM-based clients** with structured, type-safe operations
+
+All client operations require using the `async with` context manager for proper connection lifecycle management.
+
+
+<Note>
+This is not an agentic client - it requires explicit function calls and provides direct control over all MCP operations. Use it as a building block for higher-level systems.
+</Note>
+
+## Creating a Client
+
+Creating a client is straightforward. You provide a server source and the client automatically infers the appropriate transport mechanism.
+
+```python
+import asyncio
+from fastmcp import Client, FastMCP
+
+# In-memory server (ideal for testing)
+server = FastMCP("TestServer")
+client = Client(server)
+
+# HTTP server
+client = Client("https://example.com/mcp")
+
+# Local Python script
+client = Client("my_mcp_server.py")
+
+async def main():
+    async with client:
+        # Basic server interaction
+        await client.ping()
+        
+        # List available operations
+        tools = await client.list_tools()
+        resources = await client.list_resources()
+        prompts = await client.list_prompts()
+        
+        # Execute operations
+        result = await client.call_tool("example_tool", {"param": "value"})
+        print(result)
+
+asyncio.run(main())
+```
+
+## Client-Transport Architecture
+
+The FastMCP Client separates concerns between protocol and connection:
+
+- **`Client`**: Handles MCP protocol operations (tools, resources, prompts) and manages callbacks
+- **`Transport`**: Establishes and maintains the connection (WebSockets, HTTP, Stdio, in-memory)
+
+### Transport Inference
+
+The client automatically infers the appropriate transport based on the input:
+
+1. **`FastMCP` instance** → In-memory transport (perfect for testing)
+2. **File path ending in `.py`** → Python Stdio transport
+3. **File path ending in `.js`** → Node.js Stdio transport  
+4. **URL starting with `http://` or `https://`** → HTTP transport
+5. **`MCPConfig` dictionary** → Multi-server client
+
+```python
+from fastmcp import Client, FastMCP
+
+# Examples of transport inference
+client_memory = Client(FastMCP("TestServer"))
+client_script = Client("./server.py") 
+client_http = Client("https://api.example.com/mcp")
+```
+
+<Tip>
+For testing and development, always prefer the in-memory transport by passing a `FastMCP` server directly to the client. This eliminates network complexity and separate processes.
+</Tip>
+
+## Configuration-Based Clients
+
+<VersionBadge version="2.4.0" />
+
+Create clients from MCP configuration dictionaries, which can include multiple servers. While there is no official standard for MCP configuration format, FastMCP follows established conventions used by tools like Claude Desktop.
+
+### Configuration Format
+
+```python
+config = {
+    "mcpServers": {
+        "server_name": {
+            # Remote HTTP/SSE server
+            "transport": "http",  # or "sse" 
+            "url": "https://api.example.com/mcp",
+            "headers": {"Authorization": "Bearer token"},
+            "auth": "oauth"  # or bearer token string
+        },
+        "local_server": {
+            # Local stdio server
+            "transport": "stdio",
+            "command": "python",
+            "args": ["./server.py", "--verbose"],
+            "env": {"DEBUG": "true"},
+            "cwd": "/path/to/server",
+        }
+    }
+}
+```
+
+### Multi-Server Example
+
+```python
+config = {
+    "mcpServers": {
+        "weather": {"url": "https://weather-api.example.com/mcp"},
+        "assistant": {"command": "python", "args": ["./assistant_server.py"]}
+    }
+}
+
+client = Client(config)
+
+async with client:
+    # Tools are prefixed with server names
+    weather_data = await client.call_tool("weather_get_forecast", {"city": "London"})
+    response = await client.call_tool("assistant_answer_question", {"question": "What's the capital of France?"})
+    
+    # Resources use prefixed URIs
+    icons = await client.read_resource("weather://weather/icons/sunny")
+    templates = await client.read_resource("resource://assistant/templates/list")
+```
+
+## Connection Lifecycle
+
+The client operates asynchronously and uses context managers for connection management:
+
+```python
+async def example():
+    client = Client("my_mcp_server.py")
+    
+    # Connection established here
+    async with client:
+        print(f"Connected: {client.is_connected()}")
+        
+        # Make multiple calls within the same session
+        tools = await client.list_tools()
+        result = await client.call_tool("greet", {"name": "World"})
+        
+    # Connection closed automatically here
+    print(f"Connected: {client.is_connected()}")
+```
+
+## Operations
+
+FastMCP clients can interact with several types of server components:
+
+### Tools
+
+Tools are server-side functions that the client can execute with arguments.
+
+```python
+async with client:
+    # List available tools
+    tools = await client.list_tools()
+    
+    # Execute a tool
+    result = await client.call_tool("multiply", {"a": 5, "b": 3})
+    print(result.data)  # 15
+```
+
+See [Tools](/v2/clients/tools) for detailed documentation.
+
+### Resources
+
+Resources are data sources that the client can read, either static or templated.
+
+```python
+async with client:
+    # List available resources
+    resources = await client.list_resources()
+    
+    # Read a resource
+    content = await client.read_resource("file:///config/settings.json")
+    print(content[0].text)
+```
+
+See [Resources](/v2/clients/resources) for detailed documentation.
+
+### Prompts
+
+Prompts are reusable message templates that can accept arguments.
+
+```python
+async with client:
+    # List available prompts
+    prompts = await client.list_prompts()
+    
+    # Get a rendered prompt
+    messages = await client.get_prompt("analyze_data", {"data": [1, 2, 3]})
+    print(messages.messages)
+```
+
+See [Prompts](/v2/clients/prompts) for detailed documentation.
+
+### Server Connectivity
+
+Use `ping()` to verify the server is reachable:
+
+```python
+async with client:
+    await client.ping()
+    print("Server is reachable")
+```
+
+### Initialization and Server Information
+
+When you enter the client context manager, the client automatically performs an MCP initialization handshake with the server. This handshake exchanges capabilities, server metadata, and instructions. The result is available through the `initialize_result` property.
+
+```python
+from fastmcp import Client, FastMCP
+
+mcp = FastMCP(name="MyServer", instructions="Use the greet tool to say hello!")
+
+@mcp.tool
+def greet(name: str) -> str:
+    """Greet a user by name."""
+    return f"Hello, {name}!"
+
+async with Client(mcp) as client:
+    # Initialization already happened automatically
+    print(f"Server: {client.initialize_result.serverInfo.name}")
+    print(f"Version: {client.initialize_result.serverInfo.version}")
+    print(f"Instructions: {client.initialize_result.instructions}")
+    print(f"Capabilities: {client.initialize_result.capabilities.tools}")
+```
+
+#### Manual Initialization Control
+
+In advanced scenarios, you might want precise control over when initialization happens. For example, you may need custom error handling, want to defer initialization until after other setup, or need to measure initialization timing separately.
+
+Disable automatic initialization and call `initialize()` manually:
+
+```python
+from fastmcp import Client
+
+# Disable automatic initialization
+client = Client("my_mcp_server.py", auto_initialize=False)
+
+async with client:
+    # Connection established, but not initialized yet
+    print(f"Connected: {client.is_connected()}")
+    print(f"Initialized: {client.initialize_result is not None}")  # False
+
+    # Initialize manually with custom timeout
+    result = await client.initialize(timeout=10.0)
+    print(f"Server: {result.serverInfo.name}")
+
+    # Now ready for operations
+    tools = await client.list_tools()
+```
+
+The `initialize()` method is idempotent - calling it multiple times returns the cached result from the first successful call.
+
+## Client Configuration
+
+Clients can be configured with additional handlers and settings for specialized use cases.
+
+### Callback Handlers
+
+The client supports several callback handlers for advanced server interactions:
+
+```python
+from fastmcp import Client
+from fastmcp.client.logging import LogMessage
+
+async def log_handler(message: LogMessage):
+    print(f"Server log: {message.data}")
+
+async def progress_handler(progress: float, total: float | None, message: str | None):
+    print(f"Progress: {progress}/{total} - {message}")
+
+async def sampling_handler(messages, params, context):
+    # Integrate with your LLM service here
+    return "Generated response"
+
+client = Client(
+    "my_mcp_server.py",
+    log_handler=log_handler,
+    progress_handler=progress_handler,
+    sampling_handler=sampling_handler,
+    timeout=30.0
+)
+```
+
+The `Client` constructor accepts several configuration options:
+
+- `transport`: Transport instance or source for automatic inference  
+- `log_handler`: Handle server log messages
+- `progress_handler`: Monitor long-running operations
+- `sampling_handler`: Respond to server LLM requests
+- `roots`: Provide local context to servers
+- `timeout`: Default timeout for requests (in seconds)
+
+### Transport Configuration
+
+For detailed transport configuration (headers, authentication, environment variables), see the [Transports](/v2/clients/transports) documentation.
+
+## Next Steps
+
+Explore the detailed documentation for each operation type:
+
+### Core Operations
+- **[Tools](/v2/clients/tools)** - Execute server-side functions and handle results
+- **[Resources](/v2/clients/resources)** - Access static and templated resources  
+- **[Prompts](/v2/clients/prompts)** - Work with message templates and argument serialization
+
+### Advanced Features
+- **[Logging](/v2/clients/logging)** - Handle server log messages
+- **[Progress](/v2/clients/progress)** - Monitor long-running operations
+- **[Sampling](/v2/clients/sampling)** - Respond to server LLM requests
+- **[Roots](/v2/clients/roots)** - Provide local context to servers
+
+### Connection Details
+- **[Transports](/v2/clients/transports)** - Configure connection methods and parameters
+- **[Authentication](/v2/clients/auth/oauth)** - Set up OAuth and bearer token authentication
+
+<Tip>
+The FastMCP Client is designed as a foundational tool. Use it directly for deterministic operations, or build higher-level agentic systems on top of its reliable, type-safe interface.
+</Tip>
\ No newline at end of file
diff --git a/docs/v2/clients/elicitation.mdx b/docs/v2/clients/elicitation.mdx
new file mode 100644
index 0000000..15b0e50
--- /dev/null
+++ b/docs/v2/clients/elicitation.mdx
@@ -0,0 +1,125 @@
+---
+title: User Elicitation
+sidebarTitle: Elicitation
+description: Handle server-initiated user input requests with structured schemas.
+icon: message-question
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+<VersionBadge version="2.10.0" />
+
+## What is Elicitation?
+
+Elicitation allows MCP servers to request structured input from users during tool execution. Instead of requiring all inputs upfront, servers can interactively ask users for information as needed - like prompting for missing parameters, requesting clarification, or gathering additional context.
+
+For example, a file management tool might ask "Which directory should I create?" or a data analysis tool might request "What date range should I analyze?"
+
+## How FastMCP Makes Elicitation Easy
+
+FastMCP's client provides a helpful abstraction layer that:
+
+- **Converts JSON schemas to Python types**: The raw MCP protocol uses JSON schemas, but FastMCP automatically converts these to Python dataclasses
+- **Provides structured constructors**: Instead of manually building dictionaries that match the schema, you get dataclass constructors that ensure correct structure
+- **Handles type conversion**: FastMCP takes care of converting between JSON representations and Python objects
+- **Runtime introspection**: You can inspect the generated dataclass fields to understand the expected structure
+
+When you implement an elicitation handler, FastMCP gives you a dataclass type that matches the server's schema, making it easy to create properly structured responses without having to manually parse JSON schemas.
+
+## Elicitation Handler
+
+Provide an `elicitation_handler` function when creating the client. FastMCP automatically converts the server's JSON schema into a Python dataclass type, making it easy to construct the response:
+
+```python
+from fastmcp import Client
+from fastmcp.client.elicitation import ElicitResult
+
+async def elicitation_handler(message: str, response_type: type, params, context):
+    # Present the message to the user and collect input
+    user_input = input(f"{message}: ")
+    
+    # Create response using the provided dataclass type
+    # FastMCP converted the JSON schema to this Python type for you
+    response_data = response_type(value=user_input)
+    
+    # You can return data directly - FastMCP will implicitly accept the elicitation
+    return response_data
+    
+    # Or explicitly return an ElicitResult for more control
+    # return ElicitResult(action="accept", content=response_data)
+
+client = Client(
+    "my_mcp_server.py",
+    elicitation_handler=elicitation_handler,
+)
+```
+
+### Handler Parameters
+
+The elicitation handler receives four parameters:
+
+<Card icon="code" title="Elicitation Handler Parameters">
+<ResponseField name="message" type="str">
+  The prompt message to display to the user
+</ResponseField>
+
+<ResponseField name="response_type" type="type">
+  A Python dataclass type that FastMCP created from the server's JSON schema. Use this to construct your response with proper typing and IDE support. If the server requests an empty object (indicating no response), this will be `None`.
+</ResponseField>
+
+<ResponseField name="params" type="ElicitRequestParams">
+  The original MCP elicitation request parameters, including the raw JSON schema in `params.requestedSchema` if you need it
+</ResponseField>
+
+<ResponseField name="context" type="RequestContext">
+  Request context containing metadata about the elicitation request
+</ResponseField>
+</Card>
+
+### Response Actions
+
+The handler can return data directly (which implicitly accepts the elicitation) or an `ElicitResult` object for more control over the response action:
+
+<Card icon="code" title="ElicitResult Structure">
+<ResponseField name="action" type="Literal['accept', 'decline', 'cancel']">
+  How the user responded to the elicitation request
+</ResponseField>
+
+<ResponseField name="content" type="dataclass instance | dict | None">
+  The user's input data (required for "accept", omitted for "decline"/"cancel")
+</ResponseField>
+</Card>
+
+**Action Types:**
+- **`accept`**: User provided valid input - include their data in the `content` field
+- **`decline`**: User chose not to provide the requested information - omit `content`  
+- **`cancel`**: User cancelled the entire operation - omit `content`
+
+## Basic Example
+
+```python
+from fastmcp import Client
+from fastmcp.client.elicitation import ElicitResult
+
+async def basic_elicitation_handler(message: str, response_type: type, params, context):
+    print(f"Server asks: {message}")
+    
+    # Simple text input for demonstration
+    user_response = input("Your response: ")
+    
+    if not user_response:
+        # For non-acceptance, use ElicitResult explicitly
+        return ElicitResult(action="decline")
+    
+    # Use the response_type dataclass to create a properly structured response
+    # FastMCP handles the conversion from JSON schema to Python type
+    # Return data directly - FastMCP will implicitly accept the elicitation
+    return response_type(value=user_response)
+
+client = Client(
+    "my_mcp_server.py", 
+    elicitation_handler=basic_elicitation_handler
+)
+```
+
+
diff --git a/docs/v2/clients/logging.mdx b/docs/v2/clients/logging.mdx
new file mode 100644
index 0000000..ffebdf8
--- /dev/null
+++ b/docs/v2/clients/logging.mdx
@@ -0,0 +1,111 @@
+---
+title: Server Logging
+sidebarTitle: Logging
+description: Receive and handle log messages from MCP servers.
+icon: receipt
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.0.0" />
+
+MCP servers can emit log messages to clients. The client can handle these logs through a log handler callback.
+
+## Log Handler
+
+Provide a `log_handler` function when creating the client. For robust logging, the log messages can be integrated with Python's standard `logging` module.
+
+```python
+import logging
+from fastmcp import Client
+from fastmcp.client.logging import LogMessage
+
+# In a real app, you might configure this in your main entry point
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+
+# Get a logger for the module where the client is used
+logger = logging.getLogger(__name__)
+
+# This mapping is useful for converting MCP level strings to Python's levels
+LOGGING_LEVEL_MAP = logging.getLevelNamesMapping()
+
+async def log_handler(message: LogMessage):
+    """
+    Handles incoming logs from the MCP server and forwards them
+    to the standard Python logging system.
+    """
+    msg = message.data.get('msg')
+    extra = message.data.get('extra')
+
+    # Convert the MCP log level to a Python log level
+    level = LOGGING_LEVEL_MAP.get(message.level.upper(), logging.INFO)
+
+    # Log the message using the standard logging library
+    logger.log(level, msg, extra=extra)
+
+
+client = Client(
+    "my_mcp_server.py",
+    log_handler=log_handler,
+)
+```
+
+## Handling Structured Logs
+
+The `message.data` attribute is a dictionary that contains the log payload from the server. This enables structured logging, allowing you to receive rich, contextual information.
+
+The dictionary contains two keys:
+- `msg`: The string log message.
+- `extra`: A dictionary containing any extra data sent from the server.
+
+This structure is preserved even when logs are forwarded through a FastMCP proxy, making it a powerful tool for debugging complex, multi-server applications.
+
+### Handler Parameters
+
+The `log_handler` is called every time a log message is received. It receives a `LogMessage` object:
+
+<Card icon="code" title="Log Handler Parameters">
+<ResponseField name="LogMessage" type="Log Message Object">
+  <Expandable title="attributes">
+    <ResponseField name="level" type='Literal["debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"]'>
+      The log level
+    </ResponseField>
+
+    <ResponseField name="logger" type="str | None">
+      The logger name (optional, may be None)
+    </ResponseField>
+
+    <ResponseField name="data" type="dict">
+      The log payload, containing `msg` and `extra` keys.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+</Card>
+
+```python
+async def detailed_log_handler(message: LogMessage):
+    msg = message.data.get('msg')
+    extra = message.data.get('extra')
+
+    if message.level == "error":
+        print(f"ERROR: {msg} | Details: {extra}")
+    elif message.level == "warning":
+        print(f"WARNING: {msg} | Details: {extra}")
+    else:
+        print(f"{message.level.upper()}: {msg}")
+```
+
+## Default Log Handling
+
+If you don't provide a custom `log_handler`, FastMCP's default handler routes server logs to the appropriate Python logging levels. The MCP levels are mapped as follows: `notice` → INFO; `alert` and `emergency` → CRITICAL. If the server includes a logger name, it is prefixed in the message, and any `extra` data is forwarded via the logging `extra` parameter.
+
+```python
+client = Client("my_mcp_server.py")
+
+async with client:
+    # Server logs are forwarded at their proper severity (DEBUG/INFO/WARNING/ERROR/CRITICAL)
+    await client.call_tool("some_tool")
+```
diff --git a/docs/v2/clients/messages.mdx b/docs/v2/clients/messages.mdx
new file mode 100644
index 0000000..426ff7f
--- /dev/null
+++ b/docs/v2/clients/messages.mdx
@@ -0,0 +1,129 @@
+---
+title: Message Handling
+sidebarTitle: Messages
+description: Handle MCP messages, requests, and notifications with custom message handlers.
+icon: envelope
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+<VersionBadge version="2.9.1" />
+
+MCP clients can receive various types of messages from servers, including requests that need responses and notifications that don't. The message handler provides a unified way to process all these messages.
+
+## Function-Based Handler
+
+The simplest way to handle messages is with a function that receives all messages:
+
+```python
+from fastmcp import Client
+
+async def message_handler(message):
+    """Handle all MCP messages from the server."""
+    if hasattr(message, 'root'):
+        method = message.root.method
+        print(f"Received: {method}")
+        
+        # Handle specific notifications
+        if method == "notifications/tools/list_changed":
+            print("Tools have changed - might want to refresh tool cache")
+        elif method == "notifications/resources/list_changed":
+            print("Resources have changed")
+
+client = Client(
+    "my_mcp_server.py",
+    message_handler=message_handler,
+)
+```
+
+## Message Handler Class
+
+For fine-grained targeting, FastMCP provides a `MessageHandler` class you can subclass to take advantage of specific hooks:
+
+```python
+from fastmcp import Client
+from fastmcp.client.messages import MessageHandler
+import mcp.types
+
+class MyMessageHandler(MessageHandler):
+    async def on_tool_list_changed(
+        self, notification: mcp.types.ToolListChangedNotification
+    ) -> None:
+        """Handle tool list changes specifically."""
+        print("Tool list changed - refreshing available tools")
+
+client = Client(
+    "my_mcp_server.py",
+    message_handler=MyMessageHandler(),
+)
+```
+
+### Available Handler Methods
+
+All handler methods receive a single argument - the specific message type:
+
+<Card icon="code" title="Message Handler Methods">
+<ResponseField name="on_message(message)" type="Any MCP message">
+  Called for ALL messages (requests and notifications)
+</ResponseField>
+
+<ResponseField name="on_request(request)" type="mcp.types.ClientRequest">
+  Called for requests that expect responses
+</ResponseField>
+
+<ResponseField name="on_notification(notification)" type="mcp.types.ServerNotification">
+  Called for notifications (fire-and-forget)
+</ResponseField>
+
+<ResponseField name="on_tool_list_changed(notification)" type="mcp.types.ToolListChangedNotification">
+  Called when the server's tool list changes
+</ResponseField>
+
+<ResponseField name="on_resource_list_changed(notification)" type="mcp.types.ResourceListChangedNotification">
+  Called when the server's resource list changes
+</ResponseField>
+
+<ResponseField name="on_prompt_list_changed(notification)" type="mcp.types.PromptListChangedNotification">
+  Called when the server's prompt list changes
+</ResponseField>
+
+<ResponseField name="on_progress(notification)" type="mcp.types.ProgressNotification">
+  Called for progress updates during long-running operations
+</ResponseField>
+
+<ResponseField name="on_logging_message(notification)" type="mcp.types.LoggingMessageNotification">
+  Called for log messages from the server
+</ResponseField>
+</Card>
+
+## Example: Handling Tool Changes
+
+Here's a practical example of handling tool list changes:
+
+```python
+from fastmcp.client.messages import MessageHandler
+import mcp.types
+
+class ToolCacheHandler(MessageHandler):
+    def __init__(self):
+        self.cached_tools = []
+    
+    async def on_tool_list_changed(
+        self, notification: mcp.types.ToolListChangedNotification
+    ) -> None:
+        """Clear tool cache when tools change."""
+        print("Tools changed - clearing cache")
+        self.cached_tools = []  # Force refresh on next access
+
+client = Client("server.py", message_handler=ToolCacheHandler())
+```
+
+## Handling Requests
+
+While the message handler receives server-initiated requests, for most use cases you should use the dedicated callback parameters instead:
+
+- **Sampling requests**: Use [`sampling_handler`](/v2/clients/sampling)
+- **Progress requests**: Use [`progress_handler`](/v2/clients/progress)  
+- **Log requests**: Use [`log_handler`](/v2/clients/logging)
+
+The message handler is primarily for monitoring and handling notifications rather than responding to requests.
\ No newline at end of file
diff --git a/docs/v2/clients/progress.mdx b/docs/v2/clients/progress.mdx
new file mode 100644
index 0000000..ff3e0aa
--- /dev/null
+++ b/docs/v2/clients/progress.mdx
@@ -0,0 +1,70 @@
+---
+title: Progress Monitoring
+sidebarTitle: Progress
+description: Handle progress notifications from long-running server operations.
+icon: bars-progress
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.3.5" />
+
+MCP servers can report progress during long-running operations. The client can receive these updates through a progress handler.
+
+## Progress Handler
+
+Set a progress handler when creating the client:
+
+```python
+from fastmcp import Client
+
+async def my_progress_handler(
+    progress: float, 
+    total: float | None, 
+    message: str | None
+) -> None:
+    if total is not None:
+        percentage = (progress / total) * 100
+        print(f"Progress: {percentage:.1f}% - {message or ''}")
+    else:
+        print(f"Progress: {progress} - {message or ''}")
+
+client = Client(
+    "my_mcp_server.py",
+    progress_handler=my_progress_handler
+)
+```
+
+### Handler Parameters
+
+The progress handler receives three parameters:
+
+
+<Card icon="code" title="Progress Handler Parameters">
+<ResponseField name="progress" type="float">
+  Current progress value
+</ResponseField>
+
+<ResponseField name="total" type="float | None">
+  Expected total value (may be None)
+</ResponseField>
+
+<ResponseField name="message" type="str | None">
+  Optional status message (may be None)
+</ResponseField>
+</Card>
+
+
+## Per-Call Progress Handler
+
+Override the progress handler for specific tool calls:
+
+```python
+async with client:
+    # Override with specific progress handler for this call
+    result = await client.call_tool(
+        "long_running_task", 
+        {"param": "value"}, 
+        progress_handler=my_progress_handler
+    )
+```
diff --git a/docs/v2/clients/prompts.mdx b/docs/v2/clients/prompts.mdx
new file mode 100644
index 0000000..291503f
--- /dev/null
+++ b/docs/v2/clients/prompts.mdx
@@ -0,0 +1,216 @@
+---
+title: Prompts
+sidebarTitle: Prompts
+description: Use server-side prompt templates with automatic argument serialization.
+icon: message-lines
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.0.0" />
+
+Prompts are reusable message templates exposed by MCP servers. They can accept arguments to generate personalized message sequences for LLM interactions.
+
+## Listing Prompts
+
+Use `list_prompts()` to retrieve all available prompt templates:
+
+```python
+async with client:
+    prompts = await client.list_prompts()
+    # prompts -> list[mcp.types.Prompt]
+    
+    for prompt in prompts:
+        print(f"Prompt: {prompt.name}")
+        print(f"Description: {prompt.description}")
+        if prompt.arguments:
+            print(f"Arguments: {[arg.name for arg in prompt.arguments]}")
+        # Access tags and other metadata
+        if hasattr(prompt, '_meta') and prompt._meta:
+            fastmcp_meta = prompt._meta.get('_fastmcp', {})
+            print(f"Tags: {fastmcp_meta.get('tags', [])}")
+```
+
+### Filtering by Tags
+
+<VersionBadge version="2.11.0" />
+
+You can use the `meta` field to filter prompts based on their tags:
+
+```python
+async with client:
+    prompts = await client.list_prompts()
+    
+    # Filter prompts by tag
+    analysis_prompts = [
+        prompt for prompt in prompts 
+        if hasattr(prompt, '_meta') and prompt._meta and
+           prompt._meta.get('_fastmcp', {}) and
+           'analysis' in prompt._meta.get('_fastmcp', {}).get('tags', [])
+    ]
+    
+    print(f"Found {len(analysis_prompts)} analysis prompts")
+```
+
+<Note>
+The `_meta` field is part of the standard MCP specification. FastMCP servers include tags and other metadata within a `_fastmcp` namespace (e.g., `_meta._fastmcp.tags`) to avoid conflicts with user-defined metadata. This behavior can be controlled with the server's `include_fastmcp_meta` setting - when disabled, the `_fastmcp` namespace won't be included. Other MCP server implementations may not provide this metadata structure.
+</Note>
+
+## Using Prompts
+
+### Basic Usage
+
+Request a rendered prompt using `get_prompt()` with the prompt name and arguments:
+
+```python
+async with client:
+    # Simple prompt without arguments
+    result = await client.get_prompt("welcome_message")
+    # result -> mcp.types.GetPromptResult
+    
+    # Access the generated messages
+    for message in result.messages:
+        print(f"Role: {message.role}")
+        print(f"Content: {message.content}")
+```
+
+### Prompts with Arguments
+
+Pass arguments as a dictionary to customize the prompt:
+
+```python
+async with client:
+    # Prompt with simple arguments
+    result = await client.get_prompt("user_greeting", {
+        "name": "Alice",
+        "role": "administrator"
+    })
+    
+    # Access the personalized messages
+    for message in result.messages:
+        print(f"Generated message: {message.content}")
+```
+
+## Automatic Argument Serialization
+
+<VersionBadge version="2.9.0" />
+
+FastMCP automatically serializes complex arguments to JSON strings as required by the MCP specification. This allows you to pass typed objects directly:
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class UserData:
+    name: str
+    age: int
+
+async with client:
+    # Complex arguments are automatically serialized
+    result = await client.get_prompt("analyze_user", {
+        "user": UserData(name="Alice", age=30),     # Automatically serialized to JSON
+        "preferences": {"theme": "dark"},           # Dict serialized to JSON string
+        "scores": [85, 92, 78],                     # List serialized to JSON string
+        "simple_name": "Bob"                        # Strings passed through unchanged
+    })
+```
+
+The client handles serialization using `pydantic_core.to_json()` for consistent formatting. FastMCP servers can automatically deserialize these JSON strings back to the expected types.
+
+### Serialization Examples
+
+```python
+async with client:
+    result = await client.get_prompt("data_analysis", {
+        # These will be automatically serialized to JSON strings:
+        "config": {
+            "format": "csv",
+            "include_headers": True,
+            "delimiter": ","
+        },
+        "filters": [
+            {"field": "age", "operator": ">", "value": 18},
+            {"field": "status", "operator": "==", "value": "active"}
+        ],
+        # This remains a string:
+        "report_title": "Monthly Analytics Report"
+    })
+```
+
+## Working with Prompt Results
+
+The `get_prompt()` method returns a `GetPromptResult` object containing a list of messages:
+
+```python
+async with client:
+    result = await client.get_prompt("conversation_starter", {"topic": "climate"})
+    
+    # Access individual messages
+    for i, message in enumerate(result.messages):
+        print(f"Message {i + 1}:")
+        print(f"  Role: {message.role}")
+        print(f"  Content: {message.content.text if hasattr(message.content, 'text') else message.content}")
+```
+
+## Raw MCP Protocol Access
+
+For access to the complete MCP protocol objects, use the `*_mcp` methods:
+
+```python
+async with client:
+    # Raw MCP method returns full protocol object
+    prompts_result = await client.list_prompts_mcp()
+    # prompts_result -> mcp.types.ListPromptsResult
+    
+    prompt_result = await client.get_prompt_mcp("example_prompt", {"arg": "value"})
+    # prompt_result -> mcp.types.GetPromptResult
+```
+
+## Multi-Server Clients
+
+When using multi-server clients, prompts are accessible without prefixing (unlike tools):
+
+```python
+async with client:  # Multi-server client
+    # Prompts from any server are directly accessible
+    result1 = await client.get_prompt("weather_prompt", {"city": "London"})
+    result2 = await client.get_prompt("assistant_prompt", {"query": "help"})
+```
+
+## Common Prompt Patterns
+
+### System Messages
+
+Many prompts generate system messages for LLM configuration:
+
+```python
+async with client:
+    result = await client.get_prompt("system_configuration", {
+        "role": "helpful assistant",
+        "expertise": "python programming"
+    })
+    
+    # Access the returned messages
+    message = result.messages[0]
+    print(f"Prompt: {message.content}")
+```
+
+### Conversation Templates
+
+Prompts can generate multi-turn conversation templates:
+
+```python
+async with client:
+    result = await client.get_prompt("interview_template", {
+        "candidate_name": "Alice",
+        "position": "Senior Developer"
+    })
+    
+    # Multiple messages for a conversation flow
+    for message in result.messages:
+        print(f"{message.role}: {message.content}")
+```
+
+<Tip>
+Prompt arguments and their expected types depend on the specific prompt implementation. Check the server's documentation or use `list_prompts()` to see available arguments for each prompt.
+</Tip>
\ No newline at end of file
diff --git a/docs/v2/clients/resources.mdx b/docs/v2/clients/resources.mdx
new file mode 100644
index 0000000..b5120fd
--- /dev/null
+++ b/docs/v2/clients/resources.mdx
@@ -0,0 +1,204 @@
+---
+title: Resource Operations
+sidebarTitle: Resources
+description: Access static and templated resources from MCP servers.
+icon: folder-open
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.0.0" />
+
+Resources are data sources exposed by MCP servers. They can be static files or dynamic templates that generate content based on parameters.
+
+## Types of Resources
+
+MCP servers expose two types of resources:
+
+- **Static Resources**: Fixed content accessible via URI (e.g., configuration files, documentation)
+- **Resource Templates**: Dynamic resources that accept parameters to generate content (e.g., API endpoints, database queries)
+
+## Listing Resources
+
+### Static Resources
+
+Use `list_resources()` to retrieve all static resources available on the server:
+
+```python
+async with client:
+    resources = await client.list_resources()
+    # resources -> list[mcp.types.Resource]
+    
+    for resource in resources:
+        print(f"Resource URI: {resource.uri}")
+        print(f"Name: {resource.name}")
+        print(f"Description: {resource.description}")
+        print(f"MIME Type: {resource.mimeType}")
+        # Access tags and other metadata
+        if hasattr(resource, '_meta') and resource._meta:
+            fastmcp_meta = resource._meta.get('_fastmcp', {})
+            print(f"Tags: {fastmcp_meta.get('tags', [])}")
+```
+
+### Resource Templates
+
+Use `list_resource_templates()` to retrieve available resource templates:
+
+```python
+async with client:
+    templates = await client.list_resource_templates()
+    # templates -> list[mcp.types.ResourceTemplate]
+    
+    for template in templates:
+        print(f"Template URI: {template.uriTemplate}")
+        print(f"Name: {template.name}")
+        print(f"Description: {template.description}")
+        # Access tags and other metadata
+        if hasattr(template, '_meta') and template._meta:
+            fastmcp_meta = template._meta.get('_fastmcp', {})
+            print(f"Tags: {fastmcp_meta.get('tags', [])}")
+```
+
+### Filtering by Tags
+
+<VersionBadge version="2.11.0" />
+
+You can use the `meta` field to filter resources based on their tags:
+
+```python
+async with client:
+    resources = await client.list_resources()
+    
+    # Filter resources by tag
+    config_resources = [
+        resource for resource in resources 
+        if hasattr(resource, '_meta') and resource._meta and
+           resource._meta.get('_fastmcp', {}) and
+           'config' in resource._meta.get('_fastmcp', {}).get('tags', [])
+    ]
+    
+    print(f"Found {len(config_resources)} config resources")
+```
+
+<Note>
+The `_meta` field is part of the standard MCP specification. FastMCP servers include tags and other metadata within a `_fastmcp` namespace (e.g., `_meta._fastmcp.tags`) to avoid conflicts with user-defined metadata. This behavior can be controlled with the server's `include_fastmcp_meta` setting - when disabled, the `_fastmcp` namespace won't be included. Other MCP server implementations may not provide this metadata structure.
+</Note>
+
+## Reading Resources
+
+### Static Resources
+
+Read a static resource using its URI:
+
+```python
+async with client:
+    # Read a static resource
+    content = await client.read_resource("file:///path/to/README.md")
+    # content -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]
+    
+    # Access text content
+    if hasattr(content[0], 'text'):
+        print(content[0].text)
+    
+    # Access binary content
+    if hasattr(content[0], 'blob'):
+        print(f"Binary data: {len(content[0].blob)} bytes")
+```
+
+### Resource Templates
+
+Read from a resource template by providing the URI with parameters:
+
+```python
+async with client:
+    # Read a resource generated from a template
+    # For example, a template like "weather://{{city}}/current"
+    weather_content = await client.read_resource("weather://london/current")
+    
+    # Access the generated content
+    print(weather_content[0].text)  # Assuming text JSON response
+```
+
+## Content Types
+
+Resources can return different content types:
+
+### Text Resources
+
+```python
+async with client:
+    content = await client.read_resource("resource://config/settings.json")
+    
+    for item in content:
+        if hasattr(item, 'text'):
+            print(f"Text content: {item.text}")
+            print(f"MIME type: {item.mimeType}")
+```
+
+### Binary Resources
+
+```python
+async with client:
+    content = await client.read_resource("resource://images/logo.png")
+    
+    for item in content:
+        if hasattr(item, 'blob'):
+            print(f"Binary content: {len(item.blob)} bytes")
+            print(f"MIME type: {item.mimeType}")
+            
+            # Save to file
+            with open("downloaded_logo.png", "wb") as f:
+                f.write(item.blob)
+```
+
+## Working with Multi-Server Clients
+
+When using multi-server clients, resource URIs are automatically prefixed with the server name:
+
+```python
+async with client:  # Multi-server client
+    # Access resources from different servers
+    weather_icons = await client.read_resource("weather://weather/icons/sunny")
+    templates = await client.read_resource("resource://assistant/templates/list")
+    
+    print(f"Weather icon: {weather_icons[0].blob}")
+    print(f"Templates: {templates[0].text}")
+```
+
+## Raw MCP Protocol Access
+
+For access to the complete MCP protocol objects, use the `*_mcp` methods:
+
+```python
+async with client:
+    # Raw MCP methods return full protocol objects
+    resources_result = await client.list_resources_mcp()
+    # resources_result -> mcp.types.ListResourcesResult
+    
+    templates_result = await client.list_resource_templates_mcp()
+    # templates_result -> mcp.types.ListResourceTemplatesResult
+    
+    content_result = await client.read_resource_mcp("resource://example")
+    # content_result -> mcp.types.ReadResourceResult
+```
+
+## Common Resource URI Patterns
+
+Different MCP servers may use various URI schemes:
+
+```python
+# File system resources
+"file:///path/to/file.txt"
+
+# Custom protocol resources  
+"weather://london/current"
+"database://users/123"
+
+# Generic resource protocol
+"resource://config/settings"
+"resource://templates/email"
+```
+
+<Tip>
+Resource URIs and their formats depend on the specific MCP server implementation. Check the server's documentation for available resources and their URI patterns.
+</Tip>
\ No newline at end of file
diff --git a/docs/v2/clients/roots.mdx b/docs/v2/clients/roots.mdx
new file mode 100644
index 0000000..2a8d8c1
--- /dev/null
+++ b/docs/v2/clients/roots.mdx
@@ -0,0 +1,42 @@
+---
+title: Client Roots
+sidebarTitle: Roots
+description: Provide local context and resource boundaries to MCP servers.
+icon: folder-tree
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.0.0" />
+
+Roots are a way for clients to inform servers about the resources they have access to. Servers can use this information to adjust behavior or provide more relevant responses.
+
+## Setting Static Roots
+
+Provide a list of roots when creating the client:
+
+<CodeGroup>
+```python Static Roots
+from fastmcp import Client
+
+client = Client(
+    "my_mcp_server.py", 
+    roots=["/path/to/root1", "/path/to/root2"]
+)
+```
+
+```python Dynamic Roots Callback
+from fastmcp import Client
+from fastmcp.client.roots import RequestContext
+
+async def roots_callback(context: RequestContext) -> list[str]:
+    print(f"Server requested roots (Request ID: {context.request_id})")
+    return ["/path/to/root1", "/path/to/root2"]
+
+client = Client(
+    "my_mcp_server.py", 
+    roots=roots_callback
+)
+```
+</CodeGroup>
+
diff --git a/docs/v2/clients/sampling.mdx b/docs/v2/clients/sampling.mdx
new file mode 100644
index 0000000..a709b17
--- /dev/null
+++ b/docs/v2/clients/sampling.mdx
@@ -0,0 +1,258 @@
+---
+title: LLM Sampling
+sidebarTitle: Sampling
+description: Handle server-initiated LLM sampling requests.
+icon: robot
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+<VersionBadge version="2.0.0" />
+
+MCP servers can request LLM completions from clients. The client handles these requests through a sampling handler callback.
+
+## Sampling Handler
+
+Provide a `sampling_handler` function when creating the client:
+
+```python
+from fastmcp import Client
+from fastmcp.client.sampling import (
+    SamplingMessage,
+    SamplingParams,
+    RequestContext,
+)
+
+async def sampling_handler(
+    messages: list[SamplingMessage],
+    params: SamplingParams,
+    context: RequestContext
+) -> str:
+    # Your LLM integration logic here
+    # Extract text from messages and generate a response
+    return "Generated response based on the messages"
+
+client = Client(
+    "my_mcp_server.py",
+    sampling_handler=sampling_handler,
+)
+```
+
+### Handler Parameters
+
+The sampling handler receives three parameters:
+
+<Card icon="code" title="Sampling Handler Parameters">
+<ResponseField name="SamplingMessage" type="Sampling Message Object">
+  <Expandable title="attributes">
+    <ResponseField name="role" type='Literal["user", "assistant"]'>
+      The role of the message.
+    </ResponseField>
+
+    <ResponseField name="content" type="TextContent | ImageContent | AudioContent">
+      The content of the message.
+
+      TextContent is most common, and has a `.text` attribute.
+    </ResponseField>
+
+  </Expandable>
+</ResponseField>
+<ResponseField name="SamplingParams" type="Sampling Parameters Object">
+  <Expandable title="attributes">
+    <ResponseField name="messages" type="list[SamplingMessage]">
+      The messages to sample from
+    </ResponseField>
+
+    <ResponseField name="modelPreferences" type="ModelPreferences | None">
+      The server's preferences for which model to select. The client MAY ignore
+    these preferences.
+    <Expandable title="attributes">
+      <ResponseField name="hints" type="list[ModelHint] | None">
+        The hints to use for model selection.
+      </ResponseField>
+
+      <ResponseField name="costPriority" type="float | None">
+        The cost priority for model selection.
+      </ResponseField>
+
+      <ResponseField name="speedPriority" type="float | None">
+        The speed priority for model selection.
+      </ResponseField>
+
+      <ResponseField name="intelligencePriority" type="float | None">
+        The intelligence priority for model selection.
+      </ResponseField>
+    </Expandable>
+    </ResponseField>
+
+    <ResponseField name="systemPrompt" type="str | None">
+      An optional system prompt the server wants to use for sampling.
+    </ResponseField>
+
+    <ResponseField name="includeContext" type="IncludeContext | None">
+      A request to include context from one or more MCP servers (including the caller), to
+      be attached to the prompt.
+    </ResponseField>
+
+    <ResponseField name="temperature" type="float | None">
+      The sampling temperature.
+    </ResponseField>
+
+    <ResponseField name="maxTokens" type="int">
+      The maximum number of tokens to sample.
+    </ResponseField>
+
+    <ResponseField name="stopSequences" type="list[str] | None">
+      The stop sequences to use for sampling.
+    </ResponseField>
+
+    <ResponseField name="metadata" type="dict[str, Any] | None">
+      Optional metadata to pass through to the LLM provider.
+    </ResponseField>
+
+    <ResponseField name="tools" type="list[Tool] | None">
+      Optional list of tools the LLM can use during sampling. See [Using the OpenAI Handler](#using-the-openai-handler).
+    </ResponseField>
+
+    <ResponseField name="toolChoice" type="ToolChoice | None">
+      Optional control over tool usage behavior (`auto`, `required`, or `none`).
+    </ResponseField>
+    </Expandable>
+
+</ResponseField>
+<ResponseField name="RequestContext" type="Request Context Object">
+  <Expandable title="attributes">
+    <ResponseField name="request_id" type="RequestId">
+      Unique identifier for the MCP request
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+</Card>
+
+## Basic Example
+
+```python
+from fastmcp import Client
+from fastmcp.client.sampling import SamplingMessage, SamplingParams, RequestContext
+
+async def basic_sampling_handler(
+    messages: list[SamplingMessage],
+    params: SamplingParams,
+    context: RequestContext
+) -> str:
+    # Extract message content
+    conversation = []
+    for message in messages:
+        content = message.content.text if hasattr(message.content, 'text') else str(message.content)
+        conversation.append(f"{message.role}: {content}")
+
+    # Use the system prompt if provided
+    system_prompt = params.systemPrompt or "You are a helpful assistant."
+
+    # Here you would integrate with your preferred LLM service
+    # This is just a placeholder response
+    return f"Response based on conversation: {' | '.join(conversation)}"
+
+client = Client(
+    "my_mcp_server.py",
+    sampling_handler=basic_sampling_handler
+)
+```
+
+<Note>
+If the client doesn't provide a sampling handler, servers can optionally configure a fallback handler. See [Server Sampling](/v2/servers/sampling#sampling-fallback-handler) for details.
+</Note>
+
+## Sampling Capabilities
+
+When you provide a `sampling_handler`, FastMCP automatically advertises full sampling capabilities to the server, including tool support. To disable tool support (for simpler handlers that don't support tools), pass `sampling_capabilities` explicitly:
+
+```python
+from mcp.types import SamplingCapability
+
+client = Client(
+    "my_mcp_server.py",
+    sampling_handler=basic_handler,
+    sampling_capabilities=SamplingCapability(),  # No tool support
+)
+```
+
+## Built-in Handlers
+
+FastMCP provides built-in sampling handlers for OpenAI and Anthropic APIs. These handlers support the full sampling API including tool use, handling message conversion and response formatting automatically.
+
+### OpenAI Handler
+
+<VersionBadge version="2.11.0" />
+
+The OpenAI handler works with OpenAI's API and any OpenAI-compatible provider:
+
+```python
+from fastmcp import Client
+from fastmcp.client.sampling.handlers.openai import OpenAISamplingHandler
+
+client = Client(
+    "my_mcp_server.py",
+    sampling_handler=OpenAISamplingHandler(default_model="gpt-4o"),
+)
+```
+
+For OpenAI-compatible APIs (like local models), pass a custom client:
+
+```python
+from openai import AsyncOpenAI
+
+client = Client(
+    "my_mcp_server.py",
+    sampling_handler=OpenAISamplingHandler(
+        default_model="llama-3.1-70b",
+        client=AsyncOpenAI(base_url="http://localhost:8000/v1"),
+    ),
+)
+```
+
+<Note>
+Install the OpenAI handler with `pip install fastmcp[openai]`.
+</Note>
+
+### Anthropic Handler
+
+<VersionBadge version="2.14.1" />
+
+The Anthropic handler uses Claude models via the Anthropic API:
+
+```python
+from fastmcp import Client
+from fastmcp.client.sampling.handlers.anthropic import AnthropicSamplingHandler
+
+client = Client(
+    "my_mcp_server.py",
+    sampling_handler=AnthropicSamplingHandler(default_model="claude-sonnet-4-5"),
+)
+```
+
+You can pass a custom client for advanced configuration:
+
+```python
+from anthropic import AsyncAnthropic
+
+client = Client(
+    "my_mcp_server.py",
+    sampling_handler=AnthropicSamplingHandler(
+        default_model="claude-sonnet-4-5",
+        client=AsyncAnthropic(),  # Uses ANTHROPIC_API_KEY env var
+    ),
+)
+```
+
+<Note>
+Install the Anthropic handler with `pip install fastmcp[anthropic]`.
+</Note>
+
+### Tool Execution
+
+Tool execution happens on the server side. The client's role is to pass tools to the LLM and return the LLM's response (which may include tool use requests). The server then executes the tools and may send follow-up sampling requests with tool results.
+
+<Tip>
+To implement a custom sampling handler, see the [handler source code](https://github.com/PrefectHQ/fastmcp/tree/main/fastmcp_slim/fastmcp/client/sampling/handlers) as a reference.
+</Tip>
\ No newline at end of file
diff --git a/docs/v2/clients/tasks.mdx b/docs/v2/clients/tasks.mdx
new file mode 100644
index 0000000..57b2a4a
--- /dev/null
+++ b/docs/v2/clients/tasks.mdx
@@ -0,0 +1,138 @@
+---
+title: Background Tasks
+sidebarTitle: Background Tasks
+description: Execute operations asynchronously and track their progress
+icon: clock
+tag: "NEW"
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.14.0" />
+
+The [MCP task protocol](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks) lets you request operations to run asynchronously. This returns a Task object immediately, letting you track progress, cancel operations, or await results.
+
+See [Server Background Tasks](/v2/servers/tasks) for how to enable this on the server side.
+
+## Requesting Background Execution
+
+Pass `task=True` to run an operation as a background task. The call returns immediately with a Task object while the work executes on the server.
+
+```python
+from fastmcp import Client
+
+async with Client(server) as client:
+    # Start a background task
+    task = await client.call_tool("slow_computation", {"duration": 10}, task=True)
+
+    print(f"Task started: {task.task_id}")
+
+    # Do other work while it runs...
+
+    # Get the result when ready
+    result = await task.result()
+```
+
+This works with tools, resources, and prompts:
+
+```python
+tool_task = await client.call_tool("my_tool", args, task=True)
+resource_task = await client.read_resource("file://large.txt", task=True)
+prompt_task = await client.get_prompt("my_prompt", args, task=True)
+```
+
+## Working with Task Objects
+
+All task types share a common interface for retrieving results, checking status, and receiving updates.
+
+To get the result, call `await task.result()` or simply `await task`. This blocks until the task completes and returns the result. You can also check status without blocking using `await task.status()`, which returns the current state (`"working"`, `"completed"`, `"failed"`, or `"cancelled"`) along with any progress message from the server.
+
+```python
+task = await client.call_tool("analyze", {"text": "hello"}, task=True)
+
+# Check current status (non-blocking)
+status = await task.status()
+print(f"{status.status}: {status.statusMessage}")
+
+# Wait for result (blocking)
+result = await task.result()
+```
+
+For more control over waiting, use `task.wait()` with an optional timeout or target state:
+
+```python
+# Wait up to 30 seconds for completion
+status = await task.wait(timeout=30.0)
+
+# Wait for a specific state
+status = await task.wait(state="completed", timeout=30.0)
+```
+
+To cancel a running task, call `await task.cancel()`.
+
+### Real-Time Status Updates
+
+Register callbacks to receive status updates as the server reports progress. Both sync and async callbacks are supported.
+
+```python
+def on_status_change(status):
+    print(f"Task {status.taskId}: {status.status} - {status.statusMessage}")
+
+task.on_status_change(on_status_change)
+
+# Async callbacks work too
+async def on_status_async(status):
+    await log_status(status)
+
+task.on_status_change(on_status_async)
+```
+
+## Graceful Degradation
+
+You can always pass `task=True` regardless of whether the server supports background tasks. Per the MCP specification, servers without task support execute the operation immediately and return the result inline. The Task API provides a consistent interface either way.
+
+```python
+task = await client.call_tool("my_tool", args, task=True)
+
+if task.returned_immediately:
+    print("Server executed immediately (no background support)")
+else:
+    print("Running in background")
+
+# Either way, this works
+result = await task.result()
+```
+
+This means you can write task-aware client code without worrying about server capabilities.
+
+## Complete Example
+
+```python
+import asyncio
+from fastmcp import Client
+
+async def main():
+    async with Client(server) as client:
+        # Start background task
+        task = await client.call_tool(
+            "slow_computation",
+            {"duration": 10},
+            task=True,
+        )
+
+        # Subscribe to updates
+        def on_update(status):
+            print(f"Progress: {status.statusMessage}")
+
+        task.on_status_change(on_update)
+
+        # Do other work while task runs
+        print("Doing other work...")
+        await asyncio.sleep(2)
+
+        # Wait for completion and get result
+        result = await task.result()
+        print(f"Result: {result.content}")
+
+asyncio.run(main())
+```
diff --git a/docs/v2/clients/tools.mdx b/docs/v2/clients/tools.mdx
new file mode 100644
index 0000000..d9321f7
--- /dev/null
+++ b/docs/v2/clients/tools.mdx
@@ -0,0 +1,295 @@
+---
+title: Tool Operations
+sidebarTitle: Tools
+description: Discover and execute server-side tools with the FastMCP client.
+icon: wrench
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.0.0" />
+
+Tools are executable functions exposed by MCP servers. The FastMCP client provides methods to discover available tools and execute them with arguments.
+
+## Discovering Tools
+
+Use `list_tools()` to retrieve all tools available on the server:
+
+```python
+async with client:
+    tools = await client.list_tools()
+    # tools -> list[mcp.types.Tool]
+    
+    for tool in tools:
+        print(f"Tool: {tool.name}")
+        print(f"Description: {tool.description}")
+        if tool.inputSchema:
+            print(f"Parameters: {tool.inputSchema}")
+        # Access tags and other metadata
+        if hasattr(tool, 'meta') and tool.meta:
+            fastmcp_meta = tool.meta.get('_fastmcp', {})
+            print(f"Tags: {fastmcp_meta.get('tags', [])}")
+```
+
+### Filtering by Tags
+
+<VersionBadge version="2.11.0" />
+
+You can use the `meta` field to filter tools based on their tags:
+
+```python
+async with client:
+    tools = await client.list_tools()
+    
+    # Filter tools by tag
+    analysis_tools = [
+        tool for tool in tools 
+        if hasattr(tool, 'meta') and tool.meta and
+           tool.meta.get('_fastmcp', {}) and
+           'analysis' in tool.meta.get('_fastmcp', {}).get('tags', [])
+    ]
+    
+    print(f"Found {len(analysis_tools)} analysis tools")
+```
+
+<Note>
+The `meta` field is part of the standard MCP specification. FastMCP servers include tags and other metadata within a `_fastmcp` namespace (e.g., `meta._fastmcp.tags`) to avoid conflicts with user-defined metadata. This behavior can be controlled with the server's `include_fastmcp_meta` setting - when disabled, the `_fastmcp` namespace won't be included. Other MCP server implementations may not provide this metadata structure.
+</Note>
+
+## Executing Tools
+
+### Basic Execution
+
+Execute a tool using `call_tool()` with the tool name and arguments:
+
+```python
+async with client:
+    # Simple tool call
+    result = await client.call_tool("add", {"a": 5, "b": 3})
+    # result -> CallToolResult with structured and unstructured data
+    
+    # Access structured data (automatically deserialized)
+    print(result.data)  # 8 (int) or {"result": 8} for primitive types
+    
+    # Access traditional content blocks  
+    print(result.content[0].text)  # "8" (TextContent)
+```
+
+### Advanced Execution Options
+
+The `call_tool()` method supports additional parameters for timeout control and progress monitoring:
+
+```python
+async with client:
+    # With timeout (aborts if execution takes longer than 2 seconds)
+    result = await client.call_tool(
+        "long_running_task", 
+        {"param": "value"}, 
+        timeout=2.0
+    )
+    
+    # With progress handler (to track execution progress)
+    result = await client.call_tool(
+        "long_running_task",
+        {"param": "value"},
+        progress_handler=my_progress_handler
+    )
+```
+
+**Parameters:**
+- `name`: The tool name (string)
+- `arguments`: Dictionary of arguments to pass to the tool (optional)
+- `timeout`: Maximum execution time in seconds (optional, overrides client-level timeout)
+- `progress_handler`: Progress callback function (optional, overrides client-level handler)
+- `meta`: Dictionary of metadata to send with the request (optional, see below)
+
+## Sending Metadata
+
+<VersionBadge version="2.13.1" />
+
+The `meta` parameter sends ancillary information alongside tool calls. This can be used for various purposes like observability, debugging, client identification, or any context the server may need beyond the tool's primary arguments.
+
+```python
+async with client:
+    result = await client.call_tool(
+        name="send_email",
+        arguments={
+            "to": "user@example.com",
+            "subject": "Hello",
+            "body": "Welcome!"
+        },
+        meta={
+            "trace_id": "abc-123",
+            "request_source": "mobile_app"
+        }
+    )
+```
+
+The structure and usage of `meta` is determined by your application. See [Client Metadata](/v2/servers/context#client-metadata) in the server documentation to learn how to access this data in your tool implementations.
+
+## Handling Results
+
+<VersionBadge version="2.10.0" />
+
+Tool execution returns a `CallToolResult` object with both structured and traditional content. FastMCP's standout feature is the `.data` property, which doesn't just provide raw JSON but actually hydrates complete Python objects including complex types like datetimes, UUIDs, and custom classes.
+
+### CallToolResult Properties
+
+<Card icon="code" title="CallToolResult Properties">
+<ResponseField name=".data" type="Any">
+  **FastMCP exclusive**: Fully hydrated Python objects with complex type support (datetimes, UUIDs, custom classes). Goes beyond JSON to provide complete object reconstruction from output schemas.
+</ResponseField>
+
+<ResponseField name=".content" type="list[mcp.types.ContentBlock]">
+  Standard MCP content blocks (`TextContent`, `ImageContent`, `AudioContent`, etc.) available from all MCP servers.
+</ResponseField>
+
+<ResponseField name=".structured_content" type="dict[str, Any] | None">
+  Standard MCP structured JSON data as sent by the server, available from all MCP servers that support structured outputs.
+</ResponseField>
+
+<ResponseField name=".is_error" type="bool">
+  Boolean indicating if the tool execution failed.
+</ResponseField>
+</Card>
+
+### Structured Data Access
+
+FastMCP's `.data` property provides fully hydrated Python objects, not just JSON dictionaries. This includes complex type reconstruction:
+
+```python
+from datetime import datetime
+from uuid import UUID
+
+async with client:
+    result = await client.call_tool("get_weather", {"city": "London"})
+    
+    # FastMCP reconstructs complete Python objects from the server's output schema
+    weather = result.data  # Server-defined WeatherReport object
+    print(f"Temperature: {weather.temperature}°C at {weather.timestamp}")
+    print(f"Station: {weather.station_id}")
+    print(f"Humidity: {weather.humidity}%")
+    
+    # The timestamp is a real datetime object, not a string!
+    assert isinstance(weather.timestamp, datetime)
+    assert isinstance(weather.station_id, UUID)
+    
+    # Compare with raw structured JSON (standard MCP)
+    print(f"Raw JSON: {result.structured_content}")
+    # {"temperature": 20, "timestamp": "2024-01-15T14:30:00Z", "station_id": "123e4567-..."}
+    
+    # Traditional content blocks (standard MCP)  
+    print(f"Text content: {result.content[0].text}")
+```
+
+### Fallback Behavior
+
+For tools without output schemas or when deserialization fails, `.data` will be `None`:
+
+```python
+async with client:
+    result = await client.call_tool("legacy_tool", {"param": "value"})
+    
+    if result.data is not None:
+        # Structured output available and successfully deserialized
+        print(f"Structured: {result.data}")
+    else:
+        # No structured output or deserialization failed - use content blocks
+        for content in result.content:
+            if hasattr(content, 'text'):
+                print(f"Text result: {content.text}")
+            elif hasattr(content, 'data'):
+                print(f"Binary data: {len(content.data)} bytes")
+```
+
+### Primitive Type Unwrapping
+
+<Tip>
+FastMCP servers automatically wrap non-object results (like `int`, `str`, `bool`) in a `{"result": value}` structure to create valid structured outputs. FastMCP clients understand this convention and automatically unwrap the value in `.data` for convenience, so you get the original primitive value instead of a wrapper object.
+</Tip>
+
+```python
+async with client:
+    result = await client.call_tool("calculate_sum", {"a": 5, "b": 3})
+    
+    # FastMCP client automatically unwraps for convenience
+    print(result.data)  # 8 (int) - the original value
+    
+    # Raw structured content shows the server-side wrapping
+    print(result.structured_content)  # {"result": 8}
+    
+    # Other MCP clients would need to manually access ["result"]
+    # value = result.structured_content["result"]  # Not needed with FastMCP!
+```
+
+## Error Handling
+
+### Exception-Based Error Handling
+
+By default, `call_tool()` raises a `ToolError` if the tool execution fails:
+
+```python
+from fastmcp.exceptions import ToolError
+
+async with client:
+    try:
+        result = await client.call_tool("potentially_failing_tool", {"param": "value"})
+        print("Tool succeeded:", result.data)
+    except ToolError as e:
+        print(f"Tool failed: {e}")
+```
+
+### Manual Error Checking
+
+You can disable automatic error raising and manually check the result:
+
+```python
+async with client:
+    result = await client.call_tool(
+        "potentially_failing_tool", 
+        {"param": "value"}, 
+        raise_on_error=False
+    )
+    
+    if result.is_error:
+        print(f"Tool failed: {result.content[0].text}")
+    else:
+        print(f"Tool succeeded: {result.data}")
+```
+
+### Raw MCP Protocol Access
+
+For complete control, use `call_tool_mcp()` which returns the raw MCP protocol object:
+
+```python
+async with client:
+    result = await client.call_tool_mcp("potentially_failing_tool", {"param": "value"})
+    # result -> mcp.types.CallToolResult
+    
+    if result.isError:
+        print(f"Tool failed: {result.content}")
+    else:
+        print(f"Tool succeeded: {result.content}")
+        # Note: No automatic deserialization with call_tool_mcp()
+```
+
+## Argument Handling
+
+Arguments are passed as a dictionary to the tool:
+
+```python
+async with client:
+    # Simple arguments
+    result = await client.call_tool("greet", {"name": "World"})
+    
+    # Complex arguments
+    result = await client.call_tool("process_data", {
+        "config": {"format": "json", "validate": True},
+        "items": [1, 2, 3, 4, 5],
+        "metadata": {"source": "api", "version": "1.0"}
+    })
+```
+
+<Tip>
+For multi-server clients, tool names are automatically prefixed with the server name (e.g., `weather_get_forecast` for a tool named `get_forecast` on the `weather` server).
+</Tip>
\ No newline at end of file
diff --git a/docs/v2/clients/transports.mdx b/docs/v2/clients/transports.mdx
new file mode 100644
index 0000000..b7129ac
--- /dev/null
+++ b/docs/v2/clients/transports.mdx
@@ -0,0 +1,383 @@
+---
+title: Client Transports
+sidebarTitle: Transports
+description: Configure how FastMCP Clients connect to and communicate with servers.
+icon: link
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.0.0" />
+
+The FastMCP `Client` communicates with MCP servers through transport objects that handle the underlying connection mechanics. While the client can automatically select a transport based on what you pass to it, instantiating transports explicitly gives you full control over configuration—environment variables, authentication, session management, and more.
+
+Think of transports as configurable adapters between your client code and MCP servers. Each transport type handles a different communication pattern: subprocesses with pipes, HTTP connections, or direct in-memory calls.
+
+## Choosing the Right Transport
+
+- **Use [STDIO Transport](#stdio-transport)** when you need to run local MCP servers with full control over their environment and lifecycle
+- **Use [Remote Transports](#remote-transports)** when connecting to production services or shared MCP servers running independently  
+- **Use [In-Memory Transport](#in-memory-transport)** for testing FastMCP servers without subprocess or network overhead
+- **Use [MCP JSON Configuration](#mcp-json-configuration-transport)** when you need to connect to multiple servers defined in configuration files
+
+## STDIO Transport
+
+STDIO (Standard Input/Output) transport communicates with MCP servers through subprocess pipes. This is the standard mechanism used by desktop clients like Claude Desktop and is the primary way to run local MCP servers.
+
+### The Client Runs the Server
+
+<Warning>
+**Critical Concept**: When using STDIO transport, your client actually launches and manages the server process. This is fundamentally different from network transports where you connect to an already-running server. Understanding this relationship is key to using STDIO effectively.
+</Warning>
+
+With STDIO transport, your client:
+- Starts the server as a subprocess when you connect
+- Manages the server's lifecycle (start, stop, restart)
+- Controls the server's environment and configuration
+- Communicates through stdin/stdout pipes
+
+This architecture enables powerful local integrations but requires understanding environment isolation and process management.
+
+### Environment Isolation
+
+STDIO servers run in isolated environments by default. This is a security feature enforced by the MCP protocol to prevent accidental exposure of sensitive data.
+
+When your client launches an MCP server:
+- The server does NOT inherit your shell's environment variables
+- API keys, paths, and other configuration must be explicitly passed
+- The working directory and system paths may differ from your shell
+
+To pass environment variables to your server, use the `env` parameter:
+
+```python
+from fastmcp import Client
+
+# If your server needs environment variables (like API keys),
+# you must explicitly pass them:
+client = Client(
+    "my_server.py",
+    env={"API_KEY": "secret", "DEBUG": "true"}
+)
+
+# This won't work - the server runs in isolation:
+# export API_KEY="secret"  # in your shell
+# client = Client("my_server.py")  # server can't see API_KEY
+```
+
+### Basic Usage
+
+To use STDIO transport, you create a transport instance with the command and arguments needed to run your server:
+
+```python
+from fastmcp.client.transports import StdioTransport
+
+transport = StdioTransport(
+    command="python",
+    args=["my_server.py"]
+)
+client = Client(transport)
+```
+
+You can configure additional settings like environment variables, working directory, or command arguments:
+
+```python
+transport = StdioTransport(
+    command="python",
+    args=["my_server.py", "--verbose"],
+    env={"LOG_LEVEL": "DEBUG"},
+    cwd="/path/to/server"
+)
+client = Client(transport)
+```
+
+For convenience, the client can also infer STDIO transport from file paths, but this doesn't allow configuration:
+
+```python
+from fastmcp import Client
+
+client = Client("my_server.py")  # Limited - no configuration options
+```
+
+### Environment Variables
+
+Since STDIO servers don't inherit your environment, you need strategies for passing configuration. Here are two common approaches:
+
+**Selective forwarding** passes only the variables your server actually needs:
+
+```python
+import os
+from fastmcp.client.transports import StdioTransport
+
+required_vars = ["API_KEY", "DATABASE_URL", "REDIS_HOST"]
+env = {
+    var: os.environ[var] 
+    for var in required_vars 
+    if var in os.environ
+}
+
+transport = StdioTransport(
+    command="python",
+    args=["server.py"],
+    env=env
+)
+client = Client(transport)
+```
+
+**Loading from .env files** keeps configuration separate from code:
+
+```python
+from dotenv import dotenv_values
+from fastmcp.client.transports import StdioTransport
+
+env = dotenv_values(".env")
+transport = StdioTransport(
+    command="python",
+    args=["server.py"],
+    env=env
+)
+client = Client(transport)
+```
+
+### Session Persistence
+
+STDIO transports maintain sessions across multiple client contexts by default (`keep_alive=True`). This improves performance by reusing the same subprocess for multiple connections, but can be controlled when you need isolation.
+
+By default, the subprocess persists between connections:
+
+```python
+from fastmcp.client.transports import StdioTransport
+
+transport = StdioTransport(
+    command="python",
+    args=["server.py"]
+)
+client = Client(transport)
+
+async def efficient_multiple_operations():
+    async with client:
+        await client.ping()
+    
+    async with client:  # Reuses the same subprocess
+        await client.call_tool("process_data", {"file": "data.csv"})
+```
+
+For complete isolation between connections, disable session persistence:
+
+```python
+transport = StdioTransport(
+    command="python",
+    args=["server.py"],
+    keep_alive=False
+)
+client = Client(transport)
+```
+
+Use `keep_alive=False` when you need complete isolation (e.g., in test suites) or when server state could cause issues between connections.
+
+### Specialized STDIO Transports
+
+FastMCP provides convenience transports that are thin wrappers around `StdioTransport` with pre-configured commands:
+
+- **`PythonStdioTransport`** - Uses `python` command for `.py` files
+- **`NodeStdioTransport`** - Uses `node` command for `.js` files  
+- **`UvStdioTransport`** - Uses `uv` for Python packages (uses `env_vars` parameter)
+- **`UvxStdioTransport`** - Uses `uvx` for Python packages (uses `env_vars` parameter)
+- **`NpxStdioTransport`** - Uses `npx` for Node packages (uses `env_vars` parameter)
+
+For most use cases, instantiate `StdioTransport` directly with your desired command. These specialized transports are primarily useful for client inference shortcuts.
+
+## Remote Transports
+
+Remote transports connect to MCP servers running as web services. This is a fundamentally different model from STDIO transports—instead of your client launching and managing a server process, you connect to an already-running service that manages its own environment and lifecycle.
+
+### Streamable HTTP Transport
+
+<VersionBadge version="2.3.0" />
+
+Streamable HTTP is the recommended transport for production deployments, providing efficient bidirectional streaming over HTTP connections.
+
+- **Class:** `StreamableHttpTransport`
+- **Server compatibility:** FastMCP servers running with `mcp run --transport http`
+
+The transport requires a URL and optionally supports custom headers for authentication and configuration:
+
+```python
+from fastmcp.client.transports import StreamableHttpTransport
+
+# Basic connection
+transport = StreamableHttpTransport(url="https://api.example.com/mcp")
+client = Client(transport)
+
+# With custom headers for authentication
+transport = StreamableHttpTransport(
+    url="https://api.example.com/mcp",
+    headers={
+        "Authorization": "Bearer your-token-here",
+        "X-Custom-Header": "value"
+    }
+)
+client = Client(transport)
+```
+
+For convenience, FastMCP also provides authentication helpers:
+
+```python
+from fastmcp.client.auth import BearerAuth
+
+client = Client(
+    "https://api.example.com/mcp",
+    auth=BearerAuth("your-token-here")
+)
+```
+
+### SSE Transport (Legacy)
+
+Server-Sent Events transport is maintained for backward compatibility but is superseded by Streamable HTTP for new deployments.
+
+- **Class:** `SSETransport`  
+- **Server compatibility:** FastMCP servers running with `mcp run --transport sse`
+
+SSE transport supports the same configuration options as Streamable HTTP:
+
+```python
+from fastmcp.client.transports import SSETransport
+
+transport = SSETransport(
+    url="https://api.example.com/sse",
+    headers={"Authorization": "Bearer token"}
+)
+client = Client(transport)
+```
+
+Use Streamable HTTP for new deployments unless you have specific infrastructure requirements for SSE.
+
+## In-Memory Transport
+
+In-memory transport connects directly to a FastMCP server instance within the same Python process. This eliminates both subprocess management and network overhead, making it ideal for testing and development.
+
+- **Class:** `FastMCPTransport`
+
+<Note>
+Unlike STDIO transports, in-memory servers have full access to your Python process's environment. They share the same memory space and environment variables as your client code—no isolation or explicit environment passing required.
+</Note>
+
+```python
+from fastmcp import FastMCP, Client
+import os
+
+mcp = FastMCP("TestServer")
+
+@mcp.tool
+def greet(name: str) -> str:
+    prefix = os.environ.get("GREETING_PREFIX", "Hello")
+    return f"{prefix}, {name}!"
+
+client = Client(mcp)
+
+async with client:
+    result = await client.call_tool("greet", {"name": "World"})
+```
+
+## MCP JSON Configuration Transport
+
+<VersionBadge version="2.4.0" />
+
+This transport supports the emerging MCP JSON configuration standard for defining multiple servers:
+
+- **Class:** `MCPConfigTransport`
+
+```python
+config = {
+    "mcpServers": {
+        "weather": {
+            "url": "https://weather.example.com/mcp",
+            "transport": "http"
+        },
+        "assistant": {
+            "command": "python",
+            "args": ["./assistant.py"],
+            "env": {"LOG_LEVEL": "INFO"}
+        }
+    }
+}
+
+client = Client(config)
+
+async with client:
+    # Tools are namespaced by server
+    weather = await client.call_tool("weather_get_forecast", {"city": "NYC"})
+    answer = await client.call_tool("assistant_ask", {"question": "What?"})
+```
+
+### Tool Transformation with FastMCP and MCPConfig
+
+FastMCP supports basic tool transformations to be defined alongside the MCP Servers in the MCPConfig file.
+
+```python
+config = {
+    "mcpServers": {
+        "weather": {
+            "url": "https://weather.example.com/mcp",
+            "transport": "http",
+            "tools": { }   #  <--- This is the tool transformation section
+        }
+    }
+}
+```
+
+With these transformations, you can transform (change) the name, title, description, tags, enablement, and arguments of a tool.
+
+For each argument the tool takes, you can transform (change) the name, description, default, visibility, whether it's required, and you can provide example values.
+
+In the following example, we're transforming the `weather_get_forecast` tool to only retrieve the weather for `Miami` and hiding the `city` argument from the client.
+
+```python
+tool_transformations = {
+    "weather_get_forecast": {
+        "name": "miami_weather",
+        "description": "Get the weather for Miami",
+        "arguments": {
+            "city": {
+                "name": "city",
+                "default": "Miami",
+                "hide": True,
+            }
+        }
+    }
+}
+
+config = {
+    "mcpServers": {
+        "weather": {
+            "url": "https://weather.example.com/mcp",
+            "transport": "http",
+            "tools": tool_transformations
+        }
+    }
+}
+```
+
+#### Allowlisting and Blocklisting Tools
+
+Tools can be allowlisted or blocklisted from the client by applying `tags` to the tools on the server. In the following example, we're allowlisting only tools marked with the `forecast` tag, all other tools will be unavailable to the client.
+
+```python
+tool_transformations = {
+    "weather_get_forecast": {
+        "enabled": True,
+        "tags": ["forecast"]
+    }
+}
+
+
+config = {
+    "mcpServers": {
+        "weather": {
+            "url": "https://weather.example.com/mcp",
+            "transport": "http",
+            "tools": tool_transformations,
+            "include_tags": ["forecast"]
+        }
+    }
+}
+```
\ No newline at end of file
diff --git a/docs/v2/community/showcase.mdx b/docs/v2/community/showcase.mdx
new file mode 100644
index 0000000..1e7a50c
--- /dev/null
+++ b/docs/v2/community/showcase.mdx
@@ -0,0 +1,65 @@
+---
+title: 'Community Showcase'
+description: 'High-quality projects and examples from the FastMCP community'
+icon: 'users'
+---
+
+import { YouTubeEmbed } from '/snippets/youtube-embed.mdx'
+
+## Join the Community
+
+<Card title="FastMCP Discord" icon="discord" href="https://discord.gg/uu8dJCgttd">
+  Connect with other FastMCP developers, share your projects, and discuss ideas.
+</Card>
+
+## Featured Projects
+
+Discover exemplary MCP servers and implementations created by our community. These projects demonstrate best practices and innovative uses of FastMCP.
+
+### Learning Resources
+
+<Card title="MCP Dummy Server" icon="graduation-cap" href="https://github.com/WaiYanNyeinNaing/mcp-dummy-server">
+  A comprehensive educational example demonstrating FastMCP best practices with professional dual-transport server implementation, interactive test client, and detailed documentation.
+</Card>
+
+#### Video Tutorials
+
+**Build Remote MCP Servers w/ Python & FastMCP** - Claude Integrations Tutorial by Greg + Code
+
+<YouTubeEmbed 
+  videoId="bOYkbXP-GGo" 
+  title="Build Remote MCP Servers w/ Python & FastMCP" 
+/>
+
+**FastMCP — the best way to build an MCP server with Python** - Tutorial by ZazenCodes
+
+<YouTubeEmbed 
+  videoId="rnljvmHorQw" 
+  title="FastMCP — the best way to build an MCP server with Python" 
+/>
+
+**Speedrun a MCP server for Claude Desktop (fastmcp)** - Tutorial by Nate from Prefect
+
+<YouTubeEmbed 
+  videoId="67ZwpkUEtSI" 
+  title="Speedrun a MCP server for Claude Desktop (fastmcp)" 
+/>
+
+### Community Examples
+
+Have you built something interesting with FastMCP? We'd love to feature high-quality examples here! Start a [discussion on GitHub](https://github.com/PrefectHQ/fastmcp/discussions) to share your project.
+
+## Contributing
+
+To get your project featured:
+
+1. Ensure your project demonstrates best practices
+2. Include comprehensive documentation
+3. Add clear usage examples
+4. Open a discussion in our [GitHub Discussions](https://github.com/PrefectHQ/fastmcp/discussions)
+
+We review submissions regularly and feature projects that provide value to the FastMCP community.
+
+## Further Reading
+
+- [Contrib Modules](/v2/patterns/contrib) - Community-contributed modules that are distributed with FastMCP itself
\ No newline at end of file
diff --git a/docs/v2/deployment/http.mdx b/docs/v2/deployment/http.mdx
new file mode 100644
index 0000000..3596089
--- /dev/null
+++ b/docs/v2/deployment/http.mdx
@@ -0,0 +1,864 @@
+---
+title: HTTP Deployment
+sidebarTitle: HTTP Deployment
+description: Deploy your FastMCP server over HTTP for remote access
+icon: server
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+<Tip>
+STDIO transport is perfect for local development and desktop applications. But to unlock the full potential of MCP—centralized services, multi-client access, and network availability—you need remote HTTP deployment.
+</Tip>
+
+This guide walks you through deploying your FastMCP server as a remote MCP service that's accessible via a URL. Once deployed, your MCP server will be available over the network, allowing multiple clients to connect simultaneously and enabling integration with cloud-based LLM applications. This guide focuses specifically on remote MCP deployment, not local STDIO servers.
+
+## Choosing Your Approach
+
+FastMCP provides two ways to deploy your server as an HTTP service. Understanding the trade-offs helps you choose the right approach for your needs.
+
+The **direct HTTP server** approach is simpler and perfect for getting started quickly. You modify your server's `run()` method to use HTTP transport, and FastMCP handles all the web server configuration. This approach works well for standalone deployments where you want your MCP server to be the only service running on a port.
+
+The **ASGI application** approach gives you more control and flexibility. Instead of running the server directly, you create an ASGI application that can be served by Uvicorn. This approach is better when you need advanced server features like multiple workers, custom middleware, or when you're integrating with existing web applications.
+
+### Direct HTTP Server
+
+The simplest way to get your MCP server online is to use the built-in `run()` method with HTTP transport. This approach handles all the server configuration for you and is ideal when you want a standalone MCP server without additional complexity.
+
+```python server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP("My Server")
+
+@mcp.tool
+def process_data(input: str) -> str:
+    """Process data on the server"""
+    return f"Processed: {input}"
+
+if __name__ == "__main__":
+    mcp.run(transport="http", host="0.0.0.0", port=8000)
+```
+
+Run your server with a simple Python command:
+```bash
+python server.py
+```
+
+Your server is now accessible at `http://localhost:8000/mcp` (or use your server's actual IP address for remote access).
+
+This approach is ideal when you want to get online quickly with minimal configuration. It's perfect for internal tools, development environments, or simple deployments where you don't need advanced server features. The built-in server handles all the HTTP details, letting you focus on your MCP implementation.
+
+### ASGI Application
+
+For production deployments, you'll often want more control over how your server runs. FastMCP can create a standard ASGI application that works with any ASGI server like Uvicorn, Gunicorn, or Hypercorn. This approach is particularly useful when you need to configure advanced server options, run multiple workers, or integrate with existing infrastructure.
+
+```python app.py
+from fastmcp import FastMCP
+
+mcp = FastMCP("My Server")
+
+@mcp.tool
+def process_data(input: str) -> str:
+    """Process data on the server"""
+    return f"Processed: {input}"
+
+# Create ASGI application
+app = mcp.http_app()
+```
+
+Run with any ASGI server - here's an example with Uvicorn:
+```bash
+uvicorn app:app --host 0.0.0.0 --port 8000
+```
+
+Your server is accessible at the same URL: `http://localhost:8000/mcp` (or use your server's actual IP address for remote access).
+
+The ASGI approach shines in production environments where you need reliability and performance. You can run multiple worker processes to handle concurrent requests, add custom middleware for logging or monitoring, integrate with existing deployment pipelines, or mount your MCP server as part of a larger application.
+
+## Configuring Your Server
+
+### Custom Path
+
+By default, your MCP server is accessible at `/mcp/` on your domain. You can customize this path to fit your URL structure or avoid conflicts with existing endpoints. This is particularly useful when integrating MCP into an existing application or following specific API conventions.
+
+```python
+# Option 1: With mcp.run()
+mcp.run(transport="http", host="0.0.0.0", port=8000, path="/api/mcp/")
+
+# Option 2: With ASGI app
+app = mcp.http_app(path="/api/mcp/")
+```
+
+Now your server is accessible at `http://localhost:8000/api/mcp/`.
+
+### Authentication
+
+<Warning>
+Authentication is **highly recommended** for remote MCP servers. Some LLM clients require authentication for remote servers and will refuse to connect without it.
+</Warning>
+
+FastMCP supports multiple authentication methods to secure your remote server. See the [Authentication Overview](/v2/servers/auth/authentication) for complete configuration options including Bearer tokens, JWT, and OAuth.
+
+If you're mounting an authenticated server under a path prefix, see [Mounting Authenticated Servers](#mounting-authenticated-servers) below for important routing considerations.
+
+### Health Checks
+
+Health check endpoints are essential for monitoring your deployed server and ensuring it's responding correctly. FastMCP allows you to add custom routes alongside your MCP endpoints, making it easy to implement health checks that work with both deployment approaches.
+
+```python
+from starlette.responses import JSONResponse
+
+@mcp.custom_route("/health", methods=["GET"])
+async def health_check(request):
+    return JSONResponse({"status": "healthy", "service": "mcp-server"})
+```
+
+This health endpoint will be available at `http://localhost:8000/health` and can be used by load balancers, monitoring systems, or deployment platforms to verify your server is running.
+
+### Custom Middleware
+
+
+<VersionBadge version="2.3.2" />
+
+Add custom Starlette middleware to your FastMCP ASGI apps:
+
+```python
+from fastmcp import FastMCP
+from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
+
+# Create your FastMCP server
+mcp = FastMCP("MyServer")
+
+# Define middleware
+middleware = [
+    Middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+]
+
+# Create ASGI app with middleware
+http_app = mcp.http_app(middleware=middleware)
+```
+
+### CORS for Browser-Based Clients
+
+<Tip>
+Most MCP clients, including those that you access through a browser like ChatGPT or Claude, don't need CORS configuration. Only enable CORS if you're working with an MCP client that connects directly from a browser, such as debugging tools or inspectors.
+</Tip>
+
+CORS (Cross-Origin Resource Sharing) is needed when JavaScript running in a web browser connects directly to your MCP server. This is different from using an LLM through a browser—in that case, the browser connects to the LLM service, and the LLM service connects to your MCP server (no CORS needed).
+
+Browser-based MCP clients that need CORS include:
+
+- **MCP Inspector** - Browser-based debugging tool for testing MCP servers
+- **Custom browser-based MCP clients** - If you're building a web app that directly connects to MCP servers
+
+For these scenarios, add CORS middleware with the specific headers required for MCP protocol:
+
+```python
+from fastmcp import FastMCP
+from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
+
+mcp = FastMCP("MyServer")
+
+# Configure CORS for browser-based clients
+middleware = [
+    Middleware(
+        CORSMiddleware,
+        allow_origins=["*"],  # Allow all origins; use specific origins for security
+        allow_methods=["GET", "POST", "DELETE", "OPTIONS"],
+        allow_headers=[
+            "mcp-protocol-version",
+            "mcp-session-id",
+            "Authorization",
+            "Content-Type",
+        ],
+        expose_headers=["mcp-session-id"],
+    )
+]
+
+app = mcp.http_app(middleware=middleware)
+```
+
+**Key configuration details:**
+
+- **`allow_origins`**: Specify exact origins (e.g., `["http://localhost:3000"]`) rather than `["*"]` for production deployments
+- **`allow_headers`**: Must include `mcp-protocol-version`, `mcp-session-id`, and `Authorization` (for authenticated servers)
+- **`expose_headers`**: Must include `mcp-session-id` so JavaScript can read the session ID from responses and send it in subsequent requests
+
+Without `expose_headers=["mcp-session-id"]`, browsers will receive the session ID but JavaScript won't be able to access it, causing session management to fail.
+
+<Warning>
+**Production Security**: Never use `allow_origins=["*"]` in production. Specify the exact origins of your browser-based clients. Using wildcards exposes your server to unauthorized access from any website.
+</Warning>
+
+### SSE Polling for Long-Running Operations
+
+<VersionBadge version="2.14.0" />
+
+<Note>
+This feature only applies to the **StreamableHTTP transport** (the default for `http_app()`). It does not apply to the legacy SSE transport (`transport="sse"`).
+</Note>
+
+When running tools that take a long time to complete, you may encounter issues with load balancers or proxies terminating connections that stay idle too long. [SEP-1699](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1699) introduces SSE polling to solve this by allowing the server to gracefully close connections and have clients automatically reconnect.
+
+To enable SSE polling, configure an `EventStore` when creating your HTTP application:
+
+```python
+from fastmcp import FastMCP, Context
+from fastmcp.server.event_store import EventStore
+
+mcp = FastMCP("My Server")
+
+@mcp.tool
+async def long_running_task(ctx: Context) -> str:
+    """A task that takes several minutes to complete."""
+    for i in range(100):
+        await ctx.report_progress(i, 100)
+
+        # Periodically close the connection to avoid load balancer timeouts
+        # Client will automatically reconnect and resume receiving progress
+        if i % 30 == 0 and i > 0:
+            await ctx.close_sse_stream()
+
+        await do_expensive_work()
+
+    return "Done!"
+
+# Configure with EventStore for resumability
+event_store = EventStore()
+app = mcp.http_app(
+    event_store=event_store,
+    retry_interval=2000,  # Client reconnects after 2 seconds
+)
+```
+
+**How it works:**
+
+1. When `event_store` is configured, the server stores all events (progress updates, results) with unique IDs
+2. Calling `ctx.close_sse_stream()` gracefully closes the HTTP connection
+3. The client automatically reconnects with a `Last-Event-ID` header
+4. The server replays any events the client missed during the disconnection
+
+The `retry_interval` parameter (in milliseconds) controls how long clients wait before reconnecting. Choose a value that balances responsiveness with server load.
+
+<Note>
+`close_sse_stream()` is a no-op if called without an `EventStore` configured, so you can safely include it in tools that may run in different deployment configurations.
+</Note>
+
+#### Custom Storage Backends
+
+By default, `EventStore` uses in-memory storage. For production deployments with multiple server instances, you can provide a custom storage backend using the `key_value` package:
+
+```python
+from fastmcp.server.event_store import EventStore
+from key_value.aio.stores.redis import RedisStore
+
+# Use Redis for distributed deployments
+redis_store = RedisStore(url="redis://localhost:6379")
+event_store = EventStore(
+    storage=redis_store,
+    max_events_per_stream=100,  # Keep last 100 events per stream
+    ttl=3600,  # Events expire after 1 hour
+)
+
+app = mcp.http_app(event_store=event_store)
+```
+
+## Integration with Web Frameworks
+
+If you already have a web application running, you can add MCP capabilities by mounting a FastMCP server as a sub-application. This allows you to expose MCP tools alongside your existing API endpoints, sharing the same domain and infrastructure. The MCP server becomes just another route in your application, making it easy to manage and deploy.
+
+### Mounting in Starlette
+
+Mount your FastMCP server in a Starlette application:
+
+```python
+from fastmcp import FastMCP
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+# Create your FastMCP server
+mcp = FastMCP("MyServer")
+
+@mcp.tool
+def analyze(data: str) -> dict:
+    return {"result": f"Analyzed: {data}"}
+
+# Create the ASGI app
+mcp_app = mcp.http_app(path='/mcp')
+
+# Create a Starlette app and mount the MCP server
+app = Starlette(
+    routes=[
+        Mount("/mcp-server", app=mcp_app),
+        # Add other routes as needed
+    ],
+    lifespan=mcp_app.lifespan,
+)
+```
+
+The MCP endpoint will be available at `/mcp-server/mcp/` of the resulting Starlette app.
+
+<Warning>
+For Streamable HTTP transport, you **must** pass the lifespan context from the FastMCP app to the resulting Starlette app, as nested lifespans are not recognized. Otherwise, the FastMCP server's session manager will not be properly initialized.
+</Warning>
+
+#### Nested Mounts
+
+You can create complex routing structures by nesting mounts:
+
+```python
+from fastmcp import FastMCP
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+# Create your FastMCP server
+mcp = FastMCP("MyServer")
+
+# Create the ASGI app
+mcp_app = mcp.http_app(path='/mcp')
+
+# Create nested application structure
+inner_app = Starlette(routes=[Mount("/inner", app=mcp_app)])
+app = Starlette(
+    routes=[Mount("/outer", app=inner_app)],
+    lifespan=mcp_app.lifespan,
+)
+```
+
+In this setup, the MCP server is accessible at the `/outer/inner/mcp/` path.
+
+### FastAPI Integration
+
+For FastAPI-specific integration patterns including both mounting MCP servers into FastAPI apps and generating MCP servers from FastAPI apps, see the [FastAPI Integration guide](/v2/integrations/fastapi).
+
+Here's a quick example showing how to add MCP to an existing FastAPI application:
+
+```python
+from fastapi import FastAPI
+from fastmcp import FastMCP
+
+# Your existing API
+api = FastAPI()
+
+@api.get("/api/status")
+def status():
+    return {"status": "ok"}
+
+# Create your MCP server
+mcp = FastMCP("API Tools")
+
+@mcp.tool
+def query_database(query: str) -> dict:
+    """Run a database query"""
+    return {"result": "data"}
+
+# Mount MCP at /mcp
+api.mount("/mcp", mcp.http_app())
+
+# Run with: uvicorn app:api --host 0.0.0.0 --port 8000
+```
+
+Your existing API remains at `http://localhost:8000/api` while MCP is available at `http://localhost:8000/mcp`.
+
+## Mounting Authenticated Servers
+
+<VersionBadge version="2.13.0" />
+
+<Tip>
+This section only applies if you're **mounting an OAuth-protected FastMCP server under a path prefix** (like `/api`) inside another application using `Mount()`.
+
+If you're deploying your FastMCP server at root level without any `Mount()` prefix, the well-known routes are automatically included in `mcp.http_app()` and you don't need to do anything special.
+</Tip>
+
+OAuth specifications (RFC 8414 and RFC 9728) require discovery metadata to be accessible at well-known paths under the root level of your domain. When you mount an OAuth-protected FastMCP server under a path prefix like `/api`, this creates a routing challenge: your operational OAuth endpoints move under the prefix, but discovery endpoints must remain at the root.
+
+<Warning>
+**Common Mistakes to Avoid:**
+
+1. **Forgetting to mount `.well-known` routes at root** - FastMCP cannot do this automatically when your server is mounted under a path prefix. You must explicitly mount well-known routes at the root level.
+
+2. **Including mount prefix in both base_url AND mcp_path** - The mount prefix (like `/api`) should only be in `base_url`, not in `mcp_path`. Otherwise you'll get double paths.
+
+   ✅ **Correct:**
+   ```python
+   base_url = "http://localhost:8000/api"
+   mcp_path = "/mcp"
+   # Result: /api/mcp
+   ```
+
+   ❌ **Wrong:**
+   ```python
+   base_url = "http://localhost:8000/api"
+   mcp_path = "/api/mcp"
+   # Result: /api/api/mcp (double prefix!)
+   ```
+
+Follow the configuration instructions below to set up mounting correctly.
+</Warning>
+
+<Warning>
+**CORS Middleware Conflicts:**
+
+If you're integrating FastMCP into an existing application with its own CORS middleware, be aware that layering CORS middleware can cause conflicts (such as 404 errors on `.well-known` routes or OPTIONS requests).
+
+FastMCP and the MCP SDK already handle CORS for OAuth routes. If you need CORS on your own application routes, consider using the sub-app pattern: mount FastMCP and your routes as separate apps, each with their own middleware, rather than adding application-wide CORS middleware.
+</Warning>
+
+### Route Types
+
+OAuth-protected MCP servers expose two categories of routes:
+
+**Operational routes** handle the OAuth flow and MCP protocol:
+- `/authorize` - OAuth authorization endpoint
+- `/token` - Token exchange endpoint
+- `/auth/callback` - OAuth callback handler
+- `/mcp` - MCP protocol endpoint
+
+**Discovery routes** provide metadata for OAuth clients:
+- `/.well-known/oauth-authorization-server` - Authorization server metadata
+- `/.well-known/oauth-protected-resource/*` - Protected resource metadata
+
+When you mount your MCP app under a prefix, operational routes move with it, but discovery routes must stay at root level for RFC compliance.
+
+### Configuration Parameters
+
+Three parameters control where routes are located and how they combine:
+
+**`base_url`** tells clients where to find operational endpoints. This includes any Starlette `Mount()` path prefix (e.g., `/api`):
+
+```python
+base_url="http://localhost:8000/api"  # Includes mount prefix
+```
+
+**`mcp_path`** is the internal FastMCP endpoint path, which gets appended to `base_url`:
+
+```python
+mcp_path="/mcp"  # Internal MCP path, NOT the mount prefix
+```
+
+**`issuer_url`** (optional) controls the authorization server identity for OAuth discovery. Defaults to `base_url`.
+
+```python
+# Usually not needed - just set base_url and it works
+issuer_url="http://localhost:8000"  # Only if you want root-level discovery
+```
+
+When `issuer_url` has a path (either explicitly or by defaulting from `base_url`), FastMCP creates path-aware discovery routes per RFC 8414. For example, if `base_url` is `http://localhost:8000/api`, the authorization server metadata will be at `/.well-known/oauth-authorization-server/api`.
+
+**Key Invariant:** `base_url + mcp_path = actual externally-accessible MCP URL`
+
+Example:
+- `base_url`: `http://localhost:8000/api` (mount prefix `/api`)
+- `mcp_path`: `/mcp` (internal path)
+- Result: `http://localhost:8000/api/mcp` (final MCP endpoint)
+
+Note that the mount prefix (`/api` from `Mount("/api", ...)`) goes in `base_url`, while `mcp_path` is just the internal MCP route. Don't include the mount prefix in both places or you'll get `/api/api/mcp`.
+
+### Mounting Strategy
+
+When mounting an OAuth-protected server under a path prefix, declare your URLs upfront to make the relationships clear:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.github import GitHubProvider
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+# Define the routing structure
+ROOT_URL = "http://localhost:8000"
+MOUNT_PREFIX = "/api"
+MCP_PATH = "/mcp"
+```
+
+Create the auth provider with `base_url`:
+
+```python
+auth = GitHubProvider(
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+    base_url=f"{ROOT_URL}{MOUNT_PREFIX}",  # Operational endpoints under prefix
+    # issuer_url defaults to base_url - path-aware discovery works automatically
+)
+```
+
+Create the MCP app, which generates operational routes at the specified path:
+
+```python
+mcp = FastMCP("Protected Server", auth=auth)
+mcp_app = mcp.http_app(path=MCP_PATH)
+```
+
+Retrieve the discovery routes from the auth provider. The `mcp_path` argument should match the path used when creating the MCP app:
+
+```python
+well_known_routes = auth.get_well_known_routes(mcp_path=MCP_PATH)
+```
+
+Finally, mount everything in the Starlette app with discovery routes at root and the MCP app under the prefix:
+
+```python
+app = Starlette(
+    routes=[
+        *well_known_routes,  # Discovery routes at root level
+        Mount(MOUNT_PREFIX, app=mcp_app),  # Operational routes under prefix
+    ],
+    lifespan=mcp_app.lifespan,
+)
+```
+
+This configuration produces the following URL structure:
+
+- MCP endpoint: `http://localhost:8000/api/mcp`
+- OAuth authorization: `http://localhost:8000/api/authorize`
+- OAuth callback: `http://localhost:8000/api/auth/callback`
+- Authorization server metadata: `http://localhost:8000/.well-known/oauth-authorization-server/api`
+- Protected resource metadata: `http://localhost:8000/.well-known/oauth-protected-resource/api/mcp`
+
+Both discovery endpoints use path-aware URLs per RFC 8414 and RFC 9728, matching the `base_url` path.
+
+### Complete Example
+
+Here's a complete working example showing all the pieces together:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.github import GitHubProvider
+from starlette.applications import Starlette
+from starlette.routing import Mount
+import uvicorn
+
+# Define routing structure
+ROOT_URL = "http://localhost:8000"
+MOUNT_PREFIX = "/api"
+MCP_PATH = "/mcp"
+
+# Create OAuth provider
+auth = GitHubProvider(
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+    base_url=f"{ROOT_URL}{MOUNT_PREFIX}",
+    # issuer_url defaults to base_url - path-aware discovery works automatically
+)
+
+# Create MCP server
+mcp = FastMCP("Protected Server", auth=auth)
+
+@mcp.tool
+def analyze(data: str) -> dict:
+    return {"result": f"Analyzed: {data}"}
+
+# Create MCP app
+mcp_app = mcp.http_app(path=MCP_PATH)
+
+# Get discovery routes for root level
+well_known_routes = auth.get_well_known_routes(mcp_path=MCP_PATH)
+
+# Assemble the application
+app = Starlette(
+    routes=[
+        *well_known_routes,
+        Mount(MOUNT_PREFIX, app=mcp_app),
+    ],
+    lifespan=mcp_app.lifespan,
+)
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+For more details on OAuth authentication, see the [Authentication guide](/v2/servers/auth/authentication).
+
+## Production Deployment
+
+### Running with Uvicorn
+
+When deploying to production, you'll want to optimize your server for performance and reliability. Uvicorn provides several options to improve your server's capabilities:
+
+```bash
+# Run with basic configuration
+uvicorn app:app --host 0.0.0.0 --port 8000
+
+# Run with multiple workers for production (requires stateless mode - see below)
+uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4
+```
+
+### Horizontal Scaling
+
+<VersionBadge version="2.10.2" />
+
+When deploying FastMCP behind a load balancer or running multiple server instances, you need to understand how the HTTP transport handles sessions and configure your server appropriately.
+
+#### Understanding Sessions
+
+By default, FastMCP's Streamable HTTP transport maintains server-side sessions. Sessions enable stateful MCP features like [elicitation](/v2/servers/elicitation) and [sampling](/v2/servers/sampling), where the server needs to maintain context across multiple requests from the same client.
+
+This works perfectly for single-instance deployments. However, sessions are stored in memory on each server instance, which creates challenges when scaling horizontally.
+
+#### Without Stateless Mode
+
+When running multiple server instances behind a load balancer (Traefik, nginx, HAProxy, Kubernetes, etc.), requests from the same client may be routed to different instances:
+
+1. Client connects to Instance A → session created on Instance A
+2. Next request routes to Instance B → session doesn't exist → **request fails**
+
+You might expect sticky sessions (session affinity) to solve this, but they don't work reliably with MCP clients.
+
+<Warning>
+**Why sticky sessions don't work:** Most MCP clients—including Cursor and Claude Code—use `fetch()` internally and don't properly forward `Set-Cookie` headers. Without cookies, load balancers can't identify which instance should handle subsequent requests. This is a limitation in how these clients implement HTTP, not something you can fix with load balancer configuration.
+</Warning>
+
+#### Enabling Stateless Mode
+
+For horizontally scaled deployments, enable stateless HTTP mode. In stateless mode, each request creates a fresh transport context, eliminating the need for session affinity entirely.
+
+**Option 1: Via constructor**
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("My Server", stateless_http=True)
+
+@mcp.tool
+def process(data: str) -> str:
+    return f"Processed: {data}"
+
+app = mcp.http_app()
+```
+
+**Option 2: Via `run()`**
+
+```python
+if __name__ == "__main__":
+    mcp.run(transport="http", stateless_http=True)
+```
+
+**Option 3: Via environment variable**
+
+```bash
+FASTMCP_STATELESS_HTTP=true uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4
+```
+
+### Environment Variables
+
+Production deployments should never hardcode sensitive information like API keys or authentication tokens. Instead, use environment variables to configure your server at runtime. This keeps your code secure and makes it easy to deploy the same code to different environments with different configurations.
+
+Here's an example using static token authentication for development (OAuth is recommended for production):
+
+```python
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth import StaticTokenVerifier
+
+# Read configuration from environment
+auth_token = os.environ.get("MCP_AUTH_TOKEN")
+if auth_token:
+    auth = StaticTokenVerifier(tokens={auth_token: {"sub": "admin", "client_id": "cli"}})
+    mcp = FastMCP("Production Server", auth=auth)
+else:
+    mcp = FastMCP("Production Server")
+
+app = mcp.http_app()
+```
+
+Deploy with your secrets safely stored in environment variables:
+```bash
+MCP_AUTH_TOKEN=secret uvicorn app:app --host 0.0.0.0 --port 8000
+```
+
+### OAuth Token Security
+
+<VersionBadge version="2.13.0" />
+
+If you're using the [OAuth Proxy](/v2/servers/auth/oauth-proxy), FastMCP issues its own JWT tokens to clients instead of forwarding upstream provider tokens. This maintains proper OAuth 2.0 token boundaries.
+
+**Default Behavior (Development Only):**
+
+By default, FastMCP automatically manages cryptographic keys:
+- **Mac/Windows**: Keys are generated and stored in your system keyring, surviving server restarts. Suitable **only** for development and local testing.
+- **Linux**: Keys are ephemeral (random salt at startup), so tokens are invalidated on restart.
+
+This automatic approach is convenient for development but not suitable for production deployments.
+
+**For Production:**
+
+Production requires explicit key management to ensure tokens survive restarts and can be shared across multiple server instances. This requires the following two things working together:
+
+1. **Explicit JWT signing key** for signing tokens issued to clients
+3. **Persistent network-accessible storage** for upstream tokens (wrapped in `FernetEncryptionWrapper` to encrypt sensitive data at rest)
+
+**Configuration:**
+
+Add two parameters to your auth provider:
+
+```python {8-12}
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+auth = GitHubProvider(
+    client_id=os.environ["GITHUB_CLIENT_ID"],
+    client_secret=os.environ["GITHUB_CLIENT_SECRET"],
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(host="redis.example.com", port=6379),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    ),
+    base_url="https://your-server.com"  # use HTTPS
+)
+```
+
+Both parameters are required for production. Without an explicit signing key, keys are signed using a key derived from the client_secret, which will cause invalidation upon rotation of the client secret. Without persistent storage, tokens are local to the server and won't be trusted across hosts. **Wrap your storage backend in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without encryption, tokens are stored in plaintext.
+
+For more details on the token architecture and key management, see [OAuth Proxy Key and Storage Management](/v2/servers/auth/oauth-proxy#key-and-storage-management).
+
+## Reverse Proxy (nginx)
+
+In production, you'll typically run your FastMCP server behind a reverse proxy like nginx. A reverse proxy provides TLS termination, domain-based routing, static file serving, and an additional layer of security between the internet and your application.
+
+### Running FastMCP as a Linux Service
+
+Before configuring nginx, you need your FastMCP server running as a background service. A systemd unit file ensures your server starts automatically and restarts on failure.
+
+Create a file at `/etc/systemd/system/fastmcp.service`:
+
+```ini
+[Unit]
+Description=FastMCP Server
+After=network.target
+
+[Service]
+User=www-data
+Group=www-data
+WorkingDirectory=/opt/fastmcp
+ExecStart=/opt/fastmcp/.venv/bin/uvicorn app:app --host 127.0.0.1 --port 8000
+Restart=always
+RestartSec=5
+Environment="PATH=/opt/fastmcp/.venv/bin"
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start the service:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable fastmcp
+sudo systemctl start fastmcp
+```
+
+This assumes your ASGI application is in `/opt/fastmcp/app.py` with a virtual environment at `/opt/fastmcp/.venv`. Adjust paths to match your deployment layout.
+
+### nginx Configuration
+
+FastMCP's Streamable HTTP transport uses Server-Sent Events (SSE) for streaming responses. This requires specific nginx settings to prevent buffering from breaking the event stream.
+
+Create a site configuration at `/etc/nginx/sites-available/fastmcp`:
+
+```nginx
+server {
+    listen 80;
+    server_name mcp.example.com;
+
+    # Redirect HTTP to HTTPS
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl;
+    server_name mcp.example.com;
+
+    ssl_certificate /etc/letsencrypt/live/mcp.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/mcp.example.com/privkey.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Connection '';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # Required for SSE (Server-Sent Events) streaming
+        proxy_buffering off;
+        proxy_cache off;
+
+        # Allow long-lived connections for streaming responses
+        proxy_read_timeout 300s;
+        proxy_send_timeout 300s;
+    }
+}
+```
+
+Enable the site and reload nginx:
+
+```bash
+sudo ln -s /etc/nginx/sites-available/fastmcp /etc/nginx/sites-enabled/
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+Your FastMCP server is now accessible at `https://mcp.example.com/mcp`.
+
+<Warning>
+**SSE buffering is the most common issue.** If clients connect but never receive streaming responses (progress updates, tool results), verify that `proxy_buffering off` is set. Without it, nginx buffers the entire SSE stream and delivers it only when the connection closes, which breaks real-time communication.
+</Warning>
+
+### Key Considerations
+
+When deploying FastMCP behind a reverse proxy, keep these points in mind:
+
+- **Disable buffering**: SSE requires `proxy_buffering off` so events reach clients immediately. This is the single most important setting.
+- **Increase timeouts**: The default nginx `proxy_read_timeout` is 60 seconds. Long-running MCP tools will cause the connection to drop. Set timeouts to at least 300 seconds, or higher if your tools run longer. For tools that may exceed any timeout, use [SSE Polling](#sse-polling-for-long-running-operations) to gracefully handle proxy disconnections.
+- **Use HTTP/1.1**: Set `proxy_http_version 1.1` and `proxy_set_header Connection ''` to enable keep-alive connections between nginx and your server. Clearing the `Connection` header prevents clients from sending `Connection: close` to your upstream, which would break SSE streams. Both settings are required for proper SSE support.
+- **Forward headers**: Pass `X-Forwarded-For` and `X-Forwarded-Proto` so your FastMCP server can determine the real client IP and protocol. This is important for logging and for OAuth redirect URLs.
+- **TLS termination**: Let nginx handle TLS certificates (e.g., via Let's Encrypt with Certbot). Your FastMCP server can then run on plain HTTP internally.
+
+### Mounting Under a Path Prefix
+
+If you want your MCP server available at a subpath like `https://example.com/api/mcp` instead of at the root domain, adjust the nginx `location` block:
+
+```nginx
+location /api/ {
+    proxy_pass http://127.0.0.1:8000/;
+    proxy_http_version 1.1;
+    proxy_set_header Connection '';
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+
+    # Required for SSE streaming
+    proxy_buffering off;
+    proxy_cache off;
+    proxy_read_timeout 300s;
+    proxy_send_timeout 300s;
+}
+```
+
+Note the trailing `/` on both `location /api/` and `proxy_pass http://127.0.0.1:8000/` — this ensures nginx strips the `/api` prefix before forwarding to your server. If you're using OAuth authentication with a mount prefix, see [Mounting Authenticated Servers](#mounting-authenticated-servers) for additional configuration.
+
+## Testing Your Deployment
+
+Once your server is deployed, you'll need to verify it's accessible and functioning correctly. For comprehensive testing strategies including connectivity tests, client testing, and authentication testing, see the [Testing Your Server](/v2/development/tests) guide.
+
+## Hosting Your Server
+
+This guide has shown you how to create an HTTP-accessible MCP server, but you'll still need a hosting provider to make it available on the internet. Your FastMCP server can run anywhere that supports Python web applications:
+
+- **Cloud VMs** (AWS EC2, Google Compute Engine, Azure VMs)
+- **Container platforms** (Cloud Run, Container Instances, ECS)  
+- **Platform-as-a-Service** (Railway, Render, Vercel)
+- **Edge platforms** (Cloudflare Workers)
+- **Kubernetes clusters** (self-managed or managed)
+
+The key requirements are Python 3.10+ support and the ability to expose an HTTP port. Most providers will require you to package your server (requirements.txt, Dockerfile, etc.) according to their deployment format. For managed, zero-configuration deployment, see [Prefect Horizon](/deployment/prefect-horizon).
diff --git a/docs/v2/deployment/running-server.mdx b/docs/v2/deployment/running-server.mdx
new file mode 100644
index 0000000..381b801
--- /dev/null
+++ b/docs/v2/deployment/running-server.mdx
@@ -0,0 +1,258 @@
+---
+title: Running Your Server
+sidebarTitle: Running Your Server
+description: Learn how to run your FastMCP server locally for development and testing
+icon: circle-play
+---
+
+FastMCP servers can be run in different ways depending on your needs. This guide focuses on running servers locally for development and testing. For production deployment to a URL, see the [HTTP Deployment](/v2/deployment/http) guide.
+
+## The `run()` Method
+
+Every FastMCP server needs to be started to accept connections. The simplest way to run a server is by calling the `run()` method on your FastMCP instance. This method starts the server and blocks until it's stopped, handling all the connection management for you.
+
+<Tip>
+For maximum compatibility, it's best practice to place the `run()` call within an `if __name__ == "__main__":` block. This ensures the server starts only when the script is executed directly, not when imported as a module.
+</Tip>
+
+```python {9-10} my_server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="MyServer")
+
+@mcp.tool
+def hello(name: str) -> str:
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+You can now run this MCP server by executing `python my_server.py`.
+
+## Transport Protocols
+
+MCP servers communicate with clients through different transport protocols. Think of transports as the "language" your server speaks to communicate with clients. FastMCP supports three main transport protocols, each designed for specific use cases and deployment scenarios.
+
+The choice of transport determines how clients connect to your server, what network capabilities are available, and how many clients can connect simultaneously. Understanding these transports helps you choose the right approach for your application.
+
+### STDIO Transport (Default)
+
+STDIO (Standard Input/Output) is the default transport for FastMCP servers. When you call `run()` without arguments, your server uses STDIO transport. This transport communicates through standard input and output streams, making it perfect for command-line tools and desktop applications like Claude Desktop.
+
+With STDIO transport, the client spawns a new server process for each session and manages its lifecycle. The server reads MCP messages from stdin and writes responses to stdout. This is why STDIO servers don't stay running - they're started on-demand by the client.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")
+
+@mcp.tool
+def hello(name: str) -> str:
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    mcp.run()  # Uses STDIO transport by default
+```
+
+STDIO is ideal for:
+- Local development and testing
+- Claude Desktop integration
+- Command-line tools
+- Single-user applications
+
+### HTTP Transport (Streamable)
+
+HTTP transport turns your MCP server into a web service accessible via a URL. This transport uses the Streamable HTTP protocol, which allows clients to connect over the network. Unlike STDIO where each client gets its own process, an HTTP server can handle multiple clients simultaneously.
+
+The Streamable HTTP protocol provides full bidirectional communication between client and server, supporting all MCP operations including streaming responses. This makes it the recommended choice for network-based deployments.
+
+To use HTTP transport, specify it in the `run()` method along with networking options:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")
+
+@mcp.tool
+def hello(name: str) -> str:
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    # Start an HTTP server on port 8000
+    mcp.run(transport="http", host="127.0.0.1", port=8000)
+```
+
+Your server is now accessible at `http://localhost:8000/mcp`. This URL is the MCP endpoint that clients will connect to. HTTP transport enables:
+- Network accessibility
+- Multiple concurrent clients
+- Integration with web infrastructure
+- Remote deployment capabilities
+
+For production HTTP deployment with authentication and advanced configuration, see the [HTTP Deployment](/v2/deployment/http) guide.
+
+### SSE Transport (Legacy)
+
+Server-Sent Events (SSE) transport was the original HTTP-based transport for MCP. While still supported for backward compatibility, it has limitations compared to the newer Streamable HTTP transport. SSE only supports server-to-client streaming, making it less efficient for bidirectional communication.
+
+```python
+if __name__ == "__main__":
+    # SSE transport - use HTTP instead for new projects
+    mcp.run(transport="sse", host="127.0.0.1", port=8000)
+```
+
+We recommend using HTTP transport instead of SSE for all new projects. SSE remains available only for compatibility with older clients that haven't upgraded to Streamable HTTP.
+
+### Choosing the Right Transport
+
+Each transport serves different needs. STDIO is perfect when you need simple, local execution - it's what Claude Desktop and most command-line tools expect. HTTP transport is essential when you need network access, want to serve multiple clients, or plan to deploy your server remotely. SSE exists only for backward compatibility and shouldn't be used in new projects.
+
+Consider your deployment scenario: Are you building a tool for local use? STDIO is your best choice. Need a centralized service that multiple clients can access? HTTP transport is the way to go.
+
+## The FastMCP CLI
+
+FastMCP provides a powerful command-line interface for running servers without modifying the source code. The CLI can automatically find and run your server with different transports, manage dependencies, and handle development workflows:
+
+```bash
+fastmcp run server.py
+```
+
+The CLI automatically finds a FastMCP instance in your file (named `mcp`, `server`, or `app`) and runs it with the specified options. This is particularly useful for testing different transports or configurations without changing your code.
+
+### Dependency Management
+
+The CLI integrates with `uv` to manage Python environments and dependencies:
+
+```bash
+# Run with a specific Python version
+fastmcp run server.py --python 3.11
+
+# Run with additional packages
+fastmcp run server.py --with pandas --with numpy
+
+# Run with dependencies from a requirements file
+fastmcp run server.py --with-requirements requirements.txt
+
+# Combine multiple options
+fastmcp run server.py --python 3.10 --with httpx --transport http
+
+# Run within a specific project directory
+fastmcp run server.py --project /path/to/project
+```
+
+<Note>
+When using `--python`, `--with`, `--project`, or `--with-requirements`, the server runs via `uv run` subprocess instead of using your local environment.
+</Note>
+
+### Passing Arguments to Servers
+
+When servers accept command line arguments (using argparse, click, or other libraries), you can pass them after `--`:
+
+```bash
+fastmcp run config_server.py -- --config config.json
+fastmcp run database_server.py -- --database-path /tmp/db.sqlite --debug
+```
+
+This is useful for servers that need configuration files, database paths, API keys, or other runtime options.
+
+For more CLI features including development mode with the MCP Inspector, see the [CLI documentation](/v2/patterns/cli).
+
+### Async Usage
+
+FastMCP servers are built on async Python, but the framework provides both synchronous and asynchronous APIs to fit your application's needs. The `run()` method we've been using is actually a synchronous wrapper around the async server implementation.
+
+For applications that are already running in an async context, FastMCP provides the `run_async()` method:
+
+```python {10-12}
+from fastmcp import FastMCP
+import asyncio
+
+mcp = FastMCP(name="MyServer")
+
+@mcp.tool
+def hello(name: str) -> str:
+    return f"Hello, {name}!"
+
+async def main():
+    # Use run_async() in async contexts
+    await mcp.run_async(transport="http", port=8000)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+<Warning>
+The `run()` method cannot be called from inside an async function because it creates its own async event loop internally. If you attempt to call `run()` from inside an async function, you'll get an error about the event loop already running.
+
+Always use `run_async()` inside async functions and `run()` in synchronous contexts.
+</Warning>
+
+Both `run()` and `run_async()` accept the same transport arguments, so all the examples above apply to both methods.
+
+## Custom Routes
+
+When using HTTP transport, you might want to add custom web endpoints alongside your MCP server. This is useful for health checks, status pages, or simple APIs. FastMCP lets you add custom routes using the `@custom_route` decorator:
+
+```python
+from fastmcp import FastMCP
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+
+mcp = FastMCP("MyServer")
+
+@mcp.custom_route("/health", methods=["GET"])
+async def health_check(request: Request) -> PlainTextResponse:
+    return PlainTextResponse("OK")
+
+@mcp.tool
+def process(data: str) -> str:
+    return f"Processed: {data}"
+
+if __name__ == "__main__":
+    mcp.run(transport="http")  # Health check at http://localhost:8000/health
+```
+
+Custom routes are served by the same web server as your MCP endpoint. They're available at the root of your domain while the MCP endpoint is at `/mcp/`. For more complex web applications, consider [mounting your MCP server into a FastAPI or Starlette app](/v2/deployment/http#integration-with-web-frameworks).
+
+## Alternative Initialization Patterns
+
+The `if __name__ == "__main__"` pattern works well for standalone scripts, but some deployment scenarios require different approaches. FastMCP handles these cases automatically.
+
+### CLI-Only Servers
+
+When using the FastMCP CLI, you don't need the `if __name__` block at all. The CLI will find your FastMCP instance and run it:
+
+```python
+# server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")  # CLI looks for 'mcp', 'server', or 'app'
+
+@mcp.tool
+def process(data: str) -> str:
+    return f"Processed: {data}"
+
+# No if __name__ block needed - CLI will find and run 'mcp'
+```
+
+### ASGI Applications
+
+For ASGI deployment (running with Uvicorn or similar), you'll want to create an ASGI application object. This approach is common in production deployments where you need more control over the server configuration:
+
+```python
+# app.py
+from fastmcp import FastMCP
+
+def create_app():
+    mcp = FastMCP("MyServer")
+    
+    @mcp.tool
+    def process(data: str) -> str:
+        return f"Processed: {data}"
+    
+    return mcp.http_app()
+
+app = create_app()  # Uvicorn will use this
+```
+
+See the [HTTP Deployment](/v2/deployment/http) guide for more ASGI deployment patterns.
\ No newline at end of file
diff --git a/docs/v2/deployment/server-configuration.mdx b/docs/v2/deployment/server-configuration.mdx
new file mode 100644
index 0000000..f9b0e47
--- /dev/null
+++ b/docs/v2/deployment/server-configuration.mdx
@@ -0,0 +1,640 @@
+---
+title: "Project Configuration"
+sidebarTitle: "Project Configuration"
+description: Use fastmcp.json for portable, declarative project configuration
+icon: file-code
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.12.0" />
+
+FastMCP supports declarative configuration through `fastmcp.json` files. This is the canonical and preferred way to configure FastMCP projects, providing a single source of truth for server settings, dependencies, and deployment options that replaces complex command-line arguments.
+
+The `fastmcp.json` file is designed to be a portable description of your server configuration that can be shared across environments and teams. When running from a `fastmcp.json` file, you can override any configuration values using CLI arguments.
+
+## Overview
+
+The `fastmcp.json` configuration file allows you to define all aspects of your FastMCP server in a structured, shareable format. Instead of remembering command-line arguments or writing shell scripts, you declare your server's configuration once and use it everywhere.
+
+When you have a `fastmcp.json` file, running your server becomes as simple as:
+
+```bash
+# Run the server using the configuration
+fastmcp run fastmcp.json
+
+# Or if fastmcp.json exists in the current directory
+fastmcp run
+```
+
+This configuration approach ensures reproducible deployments across different environments, from local development to production servers. It works seamlessly with Claude Desktop, VS Code extensions, and any MCP-compatible client.
+
+## File Structure
+
+The `fastmcp.json` configuration answers three fundamental questions about your server:
+
+- **Source** = WHERE does your server code live?
+- **Environment** = WHAT environment setup does it require?
+- **Deployment** = HOW should the server run?
+
+This conceptual model helps you understand the purpose of each configuration section and organize your settings effectively. The configuration file maps directly to these three concerns:
+
+```json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    // WHERE: Location of your server code
+    "type": "filesystem",  // Optional, defaults to "filesystem"
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    // WHAT: Environment setup and dependencies
+    "type": "uv",  // Optional, defaults to "uv"
+    "python": ">=3.10",
+    "dependencies": ["pandas", "numpy"]
+  },
+  "deployment": {
+    // HOW: Runtime configuration
+    "transport": "stdio",
+    "log_level": "INFO"
+  }
+}
+```
+
+Only the `source` field is required. The `environment` and `deployment` sections are optional and provide additional configuration when needed.
+
+### JSON Schema Support
+
+FastMCP provides JSON schemas for IDE autocomplete and validation. Add the schema reference to your `fastmcp.json` for enhanced developer experience:
+
+```json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  }
+}
+```
+
+Two schema URLs are available:
+- **Version-specific**: `https://gofastmcp.com/public/schemas/fastmcp.json/v1.json`
+- **Latest version**: `https://gofastmcp.com/public/schemas/fastmcp.json/latest.json`
+
+Modern IDEs like VS Code will automatically provide autocomplete suggestions, validation, and inline documentation when the schema is specified.
+
+### Source Configuration
+
+The source configuration determines **WHERE** your server code lives. It tells FastMCP how to find and load your server, whether it's a local Python file, a remote repository, or hosted in the cloud. This section is required and forms the foundation of your configuration.
+
+<Card icon="code" title="Source">
+<ParamField body="source" type="object" required>
+  The server source configuration that determines where your server code lives.
+  
+  <ParamField body="type" type="string" default="filesystem">
+    The source type identifier that determines which implementation to use. Currently supports `"filesystem"` for local files. Future releases will add support for `"git"` and `"cloud"` source types.
+  </ParamField>
+  
+  <Expandable title="FileSystemSource">
+    When `type` is `"filesystem"` (or omitted), the source points to a local Python file containing your FastMCP server:
+    
+    <ParamField body="path" type="string" required>
+      Path to the Python file containing your FastMCP server. 
+    </ParamField>
+    
+    <ParamField body="entrypoint" type="string">
+      Name of the server instance or factory function within the module:
+      - Can be a FastMCP server instance (e.g., `mcp = FastMCP("MyServer")`)
+      - Can be a function with no arguments that returns a FastMCP server
+      - If not specified, FastMCP searches for common names: `mcp`, `server`, or `app`
+    </ParamField>
+    
+    **Example:**
+    ```json
+    "source": {
+      "type": "filesystem",
+      "path": "src/server.py",
+      "entrypoint": "mcp"
+    }
+    ```
+    
+    Note: File paths are resolved relative to the configuration file's location.
+  </Expandable>
+</ParamField>
+</Card>
+
+<Note>
+**Future Source Types**
+
+Future releases will support additional source types:
+- **Git repositories** (`type: "git"`) for loading server code directly from version control
+- **Prefect Horizon** (`type: "cloud"`) for hosted servers with automatic scaling and management
+</Note>
+
+### Environment Configuration
+
+The environment configuration determines **WHAT** environment setup your server requires. It controls the build-time setup of your Python environment, ensuring your server runs with the exact Python version and dependencies it requires. This section creates isolated, reproducible environments across different systems.
+
+FastMCP uses an extensible environment system with a base `Environment` class that can be implemented by different environment providers. Currently, FastMCP supports the `UVEnvironment` for Python environment management using `uv`'s powerful dependency resolver.
+
+<Card icon="code" title="Environment">
+<ParamField body="environment" type="object">
+  Optional environment configuration. When specified, FastMCP uses the appropriate environment implementation to set up your server's runtime.
+  
+  <ParamField body="type" type="string" default="uv">
+    The environment type identifier that determines which implementation to use. Currently supports `"uv"` for Python environments managed by uv. If omitted, defaults to `"uv"`.
+  </ParamField>
+  
+  <Expandable title="UVEnvironment">
+    When `type` is `"uv"` (or omitted), the environment uses uv to manage Python dependencies:
+    
+    <ParamField body="python" type="string">
+      Python version constraint. Examples:
+      - Exact version: `"3.12"`
+      - Minimum version: `">=3.10"`
+      - Version range: `">=3.10,<3.13"`
+    </ParamField>
+    
+    <ParamField body="dependencies" type="list[str]">
+      List of pip packages with optional version specifiers (PEP 508 format).
+      ```json
+      "dependencies": ["pandas>=2.0", "requests", "httpx"]
+      ```
+    </ParamField>
+    
+    <ParamField body="requirements" type="string">
+      Path to a requirements.txt file, resolved relative to the config file location.
+      ```json
+      "requirements": "requirements.txt"
+      ```
+    </ParamField>
+    
+    <ParamField body="project" type="string">
+      Path to a project directory containing pyproject.toml for uv project management.
+      ```json
+      "project": "."
+      ```
+    </ParamField>
+    
+    <ParamField body="editable" type="list[string]">
+      List of paths to packages to install in editable/development mode. Useful for local development when you want changes to be reflected immediately. Supports multiple packages for monorepo setups or shared libraries.
+      ```json
+      "editable": ["."]
+      ```
+      Or with multiple packages:
+      ```json
+      "editable": [".", "../shared-lib", "/path/to/another-package"]
+      ```
+    </ParamField>
+    
+    **Example:**
+    ```json
+    "environment": {
+      "type": "uv",
+      "python": ">=3.10",
+      "dependencies": ["pandas", "numpy"],
+      "editable": ["."]
+    }
+    ```
+    
+    Note: When any UVEnvironment field is specified, FastMCP automatically creates an isolated environment using `uv` before running your server.
+  </Expandable>
+</ParamField>
+</Card>
+
+When environment configuration is provided, FastMCP:
+1. Detects the environment type (defaults to `"uv"` if not specified)
+2. Creates an isolated environment using the appropriate provider
+3. Installs the specified dependencies
+4. Runs your server in this clean environment
+
+This build-time setup ensures your server always has the dependencies it needs, without polluting your system Python or conflicting with other projects.
+
+<Note>
+**Future Environment Types**
+
+Similar to source types, future releases may support additional environment types for different runtime requirements, such as Docker containers or language-specific environments beyond Python.
+</Note>
+
+### Deployment Configuration
+
+The deployment configuration controls **HOW** your server runs. It defines the runtime behavior including network settings, environment variables, and execution context. These settings determine how your server operates when it executes, from transport protocols to logging levels.
+
+Environment variables are included in this section because they're runtime configuration that affects how your server behaves when it executes, not how its environment is built. The deployment configuration is applied every time your server starts, controlling its operational characteristics.
+
+<Card icon="code" title="Deployment Fields">
+<ParamField body="deployment" type="object">
+  Optional runtime configuration for the server.
+  
+  <Expandable title="Deployment Fields">
+    <ParamField body="transport" type="string" default="stdio">
+      Protocol for client communication:
+      - `"stdio"`: Standard input/output for desktop clients
+      - `"http"`: Network-accessible HTTP server
+      - `"sse"`: Server-sent events
+    </ParamField>
+    
+    <ParamField body="host" type="string" default="127.0.0.1">
+      Network interface to bind (HTTP transport only):
+      - `"127.0.0.1"`: Local connections only
+      - `"0.0.0.0"`: All network interfaces
+    </ParamField>
+    
+    <ParamField body="port" type="integer" default="3000">
+      Port number for HTTP transport.
+    </ParamField>
+    
+    <ParamField body="path" type="string" default="/mcp/">
+      URL path for the MCP endpoint when using HTTP transport.
+    </ParamField>
+    
+    <ParamField body="log_level" type="string" default="INFO">
+      Server logging verbosity. Options:
+      - `"DEBUG"`: Detailed debugging information
+      - `"INFO"`: General informational messages
+      - `"WARNING"`: Warning messages
+      - `"ERROR"`: Error messages only
+      - `"CRITICAL"`: Critical errors only
+    </ParamField>
+    
+    <ParamField body="env" type="object">
+      Environment variables to set when running the server. Supports `${VAR_NAME}` syntax for runtime interpolation.
+      ```json
+      "env": {
+        "API_KEY": "secret-key",
+        "DATABASE_URL": "postgres://${DB_USER}@${DB_HOST}/mydb"
+      }
+      ```
+    </ParamField>
+    
+    <ParamField body="cwd" type="string">
+      Working directory for the server process. Relative paths are resolved from the config file location.
+    </ParamField>
+    
+    <ParamField body="args" type="list[str]">
+      Command-line arguments to pass to the server, passed after `--` to the server's argument parser.
+      ```json
+      "args": ["--config", "server-config.json"]
+      ```
+    </ParamField>
+  </Expandable>
+</ParamField>
+</Card>
+
+#### Environment Variable Interpolation
+
+The `env` field in deployment configuration supports runtime interpolation of environment variables using `${VAR_NAME}` syntax. This enables dynamic configuration based on your deployment environment:
+
+```json
+{
+  "deployment": {
+    "env": {
+      "API_URL": "https://api.${ENVIRONMENT}.example.com",
+      "DATABASE_URL": "postgres://${DB_USER}:${DB_PASS}@${DB_HOST}/myapp",
+      "CACHE_KEY": "myapp_${ENVIRONMENT}_${VERSION}"
+    }
+  }
+}
+```
+
+When the server starts, FastMCP replaces `${ENVIRONMENT}`, `${DB_USER}`, etc. with values from your system's environment variables. If a variable doesn't exist, the placeholder is preserved as-is.
+
+**Example**: If your system has `ENVIRONMENT=production` and `DB_HOST=db.example.com`:
+```json
+// Configuration
+{
+  "deployment": {
+    "env": {
+      "API_URL": "https://api.${ENVIRONMENT}.example.com",
+      "DB_HOST": "${DB_HOST}"
+    }
+  }
+}
+
+// Result at runtime
+{
+  "API_URL": "https://api.production.example.com",
+  "DB_HOST": "db.example.com"
+}
+```
+
+This feature is particularly useful for:
+- Deploying the same configuration across development, staging, and production
+- Keeping sensitive values out of configuration files
+- Building dynamic URLs and connection strings
+- Creating environment-specific prefixes or suffixes
+
+## Usage with CLI Commands
+
+FastMCP automatically detects and uses a file specifically named `fastmcp.json` in the current directory, making server execution simple and consistent. Files with FastMCP configuration format but different names are not auto-detected and must be specified explicitly:
+
+```bash
+# Auto-detect fastmcp.json in current directory
+cd my-project
+fastmcp run  # No arguments needed!
+
+# Or specify a configuration file explicitly
+fastmcp run prod.fastmcp.json
+
+# Skip environment setup when already in a uv environment
+fastmcp run fastmcp.json --skip-env
+
+# Skip source preparation when source is already prepared
+fastmcp run fastmcp.json --skip-source
+
+# Skip both environment and source preparation
+fastmcp run fastmcp.json --skip-env --skip-source
+```
+
+### Pre-building Environments
+
+You can use `fastmcp project prepare` to create a persistent uv project with all dependencies pre-installed:
+
+```bash
+# Create a persistent environment
+fastmcp project prepare fastmcp.json --output-dir ./env
+
+# Use the pre-built environment to run the server
+fastmcp run fastmcp.json --project ./env
+```
+
+This pattern separates environment setup (slow) from server execution (fast), useful for deployment scenarios.
+
+### Using an Existing Environment
+
+By default, FastMCP creates an isolated environment with `uv` based on your configuration. When you already have a suitable Python environment, use the `--skip-env` flag to skip environment creation:
+
+```bash
+fastmcp run fastmcp.json --skip-env
+```
+
+**When you already have an environment:**
+- You're in an activated virtual environment with all dependencies installed
+- You're inside a Docker container with pre-installed dependencies  
+- You're in a CI/CD pipeline that pre-builds the environment
+- You're using a system-wide installation with all required packages
+- You're in a uv-managed environment (prevents infinite recursion)
+
+This flag tells FastMCP: "I already have everything installed, just run the server."
+
+### Using an Existing Source
+
+When working with source types that require preparation (future support for git repositories or cloud sources), use the `--skip-source` flag when you already have the source code available:
+
+```bash
+fastmcp run fastmcp.json --skip-source
+```
+
+**When you already have the source:**
+- You've previously cloned a git repository and don't need to re-fetch
+- You have a cached copy of a cloud-hosted server
+- You're in a CI/CD pipeline where source checkout is a separate step
+- You're iterating locally on already-downloaded code
+
+This flag tells FastMCP: "I already have the source code, skip any download/clone steps."
+
+Note: For filesystem sources (local Python files), this flag has no effect since they don't require preparation.
+
+The configuration file works with all FastMCP commands:
+- **`run`** - Start the server in production mode
+- **`dev`** - Launch with the Inspector UI for development  
+- **`inspect`** - View server capabilities and configuration
+- **`install`** - Install to Claude Desktop, Cursor, or other MCP clients
+
+When no file argument is provided, FastMCP searches the current directory for `fastmcp.json`. This means you can simply navigate to your project directory and run `fastmcp run` to start your server with all its configured settings.
+
+### CLI Override Behavior
+
+Command-line arguments take precedence over configuration file values, allowing ad-hoc adjustments without modifying the file:
+
+```bash
+# Config specifies port 3000, CLI overrides to 8080
+fastmcp run fastmcp.json --port 8080
+
+# Config specifies stdio, CLI overrides to HTTP
+fastmcp run fastmcp.json --transport http
+
+# Add extra dependencies not in config
+fastmcp run fastmcp.json --with requests --with httpx
+```
+
+This precedence order enables:
+- Quick testing of different settings
+- Environment-specific overrides in deployment scripts
+- Debugging with increased log levels
+- Temporary configuration changes
+
+### Custom Naming Patterns
+
+You can use different configuration files for different environments:
+
+- `fastmcp.json` - Default configuration
+- `dev.fastmcp.json` - Development settings
+- `prod.fastmcp.json` - Production settings
+- `test_fastmcp.json` - Test configuration
+
+Any file with "fastmcp.json" in the name is recognized as a configuration file.
+
+## Examples
+
+<Tabs>
+<Tab title="Basic Configuration">
+
+A minimal configuration for a simple server:
+
+```json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  }
+}
+```
+This configuration explicitly specifies the server entrypoint (`mcp`), making it clear which server instance or factory function to use. Uses all defaults: STDIO transport, no special dependencies, standard logging.
+</Tab>
+<Tab title="Development Configuration">
+
+A configuration optimized for local development:
+
+```json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  // WHERE does the server live?
+  "source": {
+    "path": "src/server.py",
+    "entrypoint": "app"
+  },
+  // WHAT dependencies does it need?
+  "environment": {
+    "type": "uv",
+    "python": "3.12",
+    "dependencies": ["fastmcp[dev]"],
+    "editable": "."
+  },
+  // HOW should it run?
+  "deployment": {
+    "transport": "http",
+    "host": "127.0.0.1",
+    "port": 8000,
+    "log_level": "DEBUG",
+    "env": {
+      "DEBUG": "true",
+      "ENV": "development"
+    }
+  }
+}
+```
+</Tab>
+<Tab title="Production Configuration">
+
+A production-ready configuration with full dependency management:
+
+```json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  // WHERE does the server live?
+  "source": {
+    "path": "app/main.py",
+    "entrypoint": "mcp_server"
+  },
+  // WHAT dependencies does it need?
+  "environment": {
+    "python": "3.11",
+    "requirements": "requirements/production.txt",
+    "project": "."
+  },
+  // HOW should it run?
+  "deployment": {
+    "transport": "http",
+    "host": "0.0.0.0",
+    "port": 3000,
+    "path": "/api/mcp/",
+    "log_level": "INFO",
+    "env": {
+      "ENV": "production",
+      "API_BASE_URL": "https://api.example.com",
+      "DATABASE_URL": "postgresql://user:pass@db.example.com/prod"
+    },
+    "cwd": "/app",
+    "args": ["--workers", "4"]
+  }
+}
+```
+</Tab>
+<Tab title="Data Science Server">
+
+Configuration for a data analysis server with scientific packages:
+
+```json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "analysis_server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "python": "3.11",
+    "dependencies": [
+      "pandas>=2.0",
+      "numpy",
+      "scikit-learn",
+      "matplotlib",
+      "jupyterlab"
+    ]
+  },
+  "deployment": {
+    "transport": "stdio",
+    "env": {
+      "MATPLOTLIB_BACKEND": "Agg",
+      "DATA_PATH": "./datasets"
+    }
+  }
+}
+```
+</Tab>
+<Tab title="Multi-Environment Setup"> 
+
+You can maintain multiple configuration files for different environments:
+
+**dev.fastmcp.json**:
+```json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "deployment": {
+    "transport": "http",
+    "log_level": "DEBUG"
+  }
+}
+```
+
+**prod.fastmcp.json**:
+```json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "requirements": "requirements/production.txt"
+  },
+  "deployment": {
+    "transport": "http",
+    "host": "0.0.0.0",
+    "log_level": "WARNING"
+  }
+}
+```
+
+Run different configurations:
+```bash
+fastmcp run dev.fastmcp.json   # Development
+fastmcp run prod.fastmcp.json  # Production
+```
+</Tab>
+</Tabs>
+
+## Migrating from CLI Arguments
+
+If you're currently using command-line arguments or shell scripts, migrating to `fastmcp.json` simplifies your workflow. Here's how common CLI patterns map to configuration:
+
+**CLI Command**:
+```bash
+uv run --with pandas --with requests \
+  fastmcp run server.py \
+  --transport http \
+  --port 8000 \
+  --log-level INFO
+```
+
+**Equivalent fastmcp.json**:
+```json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "dependencies": ["pandas", "requests"]
+  },
+  "deployment": {
+    "transport": "http",
+    "port": 8000,
+    "log_level": "INFO"
+  }
+}
+```
+
+Now simply run:
+```bash
+fastmcp run  # Automatically finds and uses fastmcp.json
+```
+
+The configuration file approach provides better documentation, easier sharing, and consistent execution across different environments while maintaining the flexibility to override settings when needed.
\ No newline at end of file
diff --git a/docs/v2/development/contributing.mdx b/docs/v2/development/contributing.mdx
new file mode 100644
index 0000000..31df31d
--- /dev/null
+++ b/docs/v2/development/contributing.mdx
@@ -0,0 +1,187 @@
+---
+title: "Contributing"
+description: "Development workflow for FastMCP contributors"
+icon: code-pull-request
+---
+
+Contributing to FastMCP means joining a community that values clean, maintainable code and thoughtful API design. All contributions are valued - from fixing typos in documentation to implementing major features.
+
+## Issues
+
+### Issue First, Code Second
+
+**Every pull request requires a corresponding issue - no exceptions.** This requirement creates a collaborative space where approach, scope, and alignment are established before code is written. Issues serve as design documents where maintainers and contributors discuss implementation strategy, identify potential conflicts with existing patterns, and ensure proposed changes advance FastMCP's vision.
+
+**FastMCP is an opinionated framework, not a kitchen sink.** The maintainers have strong beliefs about what FastMCP should and shouldn't do. Just because something takes N lines of code and you want it in fewer lines doesn't mean FastMCP should take on the maintenance burden or endorse that pattern. This is judged at the maintainers' discretion.
+
+Use issues to understand scope BEFORE opening PRs. The issue discussion determines whether a feature belongs in core, contrib, or not at all.
+
+### Writing Good Issues
+
+FastMCP is an extremely highly-trafficked repository maintained by a very small team. Issues that appear to transfer burden to maintainers without any effort to validate the problem will be closed. Please help the maintainers help you by always providing a minimal reproducible example and clearly describing the problem.
+
+**LLM-generated issues will be closed immediately.** Issues that contain paragraphs of unnecessary explanation, verbose problem descriptions, or obvious LLM authorship patterns obfuscate the actual problem and transfer burden to maintainers.
+
+Write clear, concise issues that:
+- State the problem directly
+- Provide a minimal reproducible example
+- Skip unnecessary background or context
+- Take responsibility for clear communication
+
+Issues may be labeled "Invalid" simply due to confusion caused by verbosity or not adhering to the guidelines outlined here.
+
+## Pull Requests
+
+PRs that deviate from FastMCP's core principles will be rejected regardless of implementation quality. **PRs are NOT for iterating on ideas** - they should only be opened for ideas that already have a bias toward acceptance based on issue discussion.
+
+
+### Development Environment
+
+#### Installation
+
+To contribute to FastMCP, you'll need to set up a development environment with all necessary tools and dependencies.
+
+```bash
+# Clone the repository
+git clone https://github.com/PrefectHQ/fastmcp.git
+cd fastmcp
+
+# Install all dependencies including dev tools
+uv sync
+
+# Install prek hooks
+uv run prek install
+```
+
+In addition, some development commands require [just](https://github.com/casey/just) to be installed.
+
+Prek hooks will run automatically on every commit to catch issues before they reach CI. If you see failures, fix them before committing - never commit broken code expecting to fix it later.
+
+### Development Standards
+
+#### Scope
+
+Large pull requests create review bottlenecks and quality risks. Unless you're fixing a discrete bug or making an incredibly well-scoped change, keep PRs small and focused. 
+
+A PR that changes 50 lines across 3 files can be thoroughly reviewed in minutes. A PR that changes 500 lines across 20 files requires hours of careful analysis and often hides subtle issues.
+
+Breaking large features into smaller PRs:
+- Creates better review experiences
+- Makes git history clear
+- Simplifies debugging with bisect
+- Reduces merge conflicts
+- Gets your code merged faster
+
+#### Code Quality
+
+FastMCP values clarity over cleverness. Every line you write will be maintained by someone else - possibly years from now, possibly without context about your decisions.
+
+**PRs can be rejected for two opposing reasons:**
+1. **Insufficient quality** - Code that doesn't meet our standards for clarity, maintainability, or idiomaticity
+2. **Overengineering** - Code that is overbearing, unnecessarily complex, or tries to be too clever
+
+The focus is on idiomatic, high-quality Python. FastMCP uses patterns like `NotSet` type as an alternative to `None` in certain situations - follow existing patterns.
+
+#### Required Practices
+
+**Full type annotations** on all functions and methods. They catch bugs before runtime and serve as inline documentation.
+
+**Async/await patterns** for all I/O operations. Even if your specific use case doesn't need concurrency, consistency means users can compose features without worrying about blocking operations.
+
+**Descriptive names** make code self-documenting. `auth_token` is clear; `tok` requires mental translation.
+
+**Specific exception types** make error handling predictable. Catching `ValueError` tells readers exactly what error you expect. Never use bare `except` clauses.
+
+#### Anti-Patterns to Avoid
+
+**Complex one-liners** are hard to debug and modify. Break operations into clear steps.
+
+**Mutable default arguments** cause subtle bugs. Use `None` as the default and create the mutable object inside the function.
+
+**Breaking established patterns** confuses readers. If you must deviate, discuss in the issue first.
+
+### Prek Checks
+
+```bash
+# Runs automatically on commit, or manually:
+uv run prek run --all-files
+```
+
+This runs three critical tools:
+- **Ruff**: Linting and formatting
+- **Prettier**: Code formatting
+- **ty**: Static type checking
+
+Pytest runs separately as a distinct workflow step after prek checks pass. CI will reject PRs that fail these checks. Always run them locally first.
+
+### Testing
+
+Tests are documentation that shows how features work. Good tests give reviewers confidence and help future maintainers understand intent.
+
+```bash
+# Run specific test directory
+uv run pytest tests/server/ -v
+
+# Run all tests before submitting PR
+uv run pytest
+```
+
+Every new feature needs tests. See the [Testing Guide](/v2/development/tests) for patterns and requirements.
+
+### Documentation
+
+A feature doesn't exist unless it's documented. Note that FastMCP's hosted documentation always tracks the main branch - users who want historical documentation can clone the repo, checkout a specific tag, and host it themselves.
+
+```bash
+# Preview documentation locally
+just docs
+```
+
+Documentation requirements:
+- **Explain concepts in prose first** - Code without context is just syntax
+- **Complete, runnable examples** - Every code block should be copy-pasteable
+- **Register in docs.json** - Makes pages appear in navigation
+- **Version badges** - Mark when features were added using `<VersionBadge />`
+
+#### SDK Documentation
+
+FastMCP's SDK documentation is auto-generated from the source code docstrings and type annotations. It is automatically updated on every merge to main by a GitHub Actions workflow, so users are *not* responsible for keeping the documentation up to date. However, to generate it proactively, you can use the following command:
+
+```bash
+just api-ref-all
+```
+
+### Submitting Your PR
+
+#### Before Submitting
+
+1. **Run all checks**: `uv run prek run --all-files && uv run pytest`
+2. **Keep scope small**: One feature or fix per PR
+3. **Write clear description**: Your PR description becomes permanent documentation
+4. **Update docs**: Include documentation for API changes
+
+#### PR Description
+
+Write PR descriptions that explain:
+- What problem you're solving
+- Why you chose this approach  
+- Any trade-offs or alternatives considered
+- Migration path for breaking changes
+
+Focus on the "why" - the code shows the "what". Keep it concise but complete.
+
+#### What We Look For
+
+**Framework Philosophy**: FastMCP is NOT trying to do all things or provide all shortcuts. Features are rejected when they don't align with the framework's vision, even if perfectly implemented. The burden of proof is on the PR to demonstrate value.
+
+**Code Quality**: We verify code follows existing patterns. Consistency reduces cognitive load. When every module works similarly, developers understand new code quickly.
+
+**Test Coverage**: Not every line needs testing, but every behavior does. Tests document intent and protect against regressions.
+
+**Breaking Changes**: May be acceptable in minor versions but must be clearly documented. See the [versioning policy](/v2/development/releases#versioning-policy).
+
+## Special Modules
+
+**`contrib`**: Community-maintained patterns and utilities. Original authors maintain their contributions. Not representative of the core framework.
+
+**`experimental`**: Maintainer-developed features that may preview future functionality. Can break or be deleted at any time without notice. Pin your FastMCP version when using these features.
\ No newline at end of file
diff --git a/docs/v2/development/releases.mdx b/docs/v2/development/releases.mdx
new file mode 100644
index 0000000..3464627
--- /dev/null
+++ b/docs/v2/development/releases.mdx
@@ -0,0 +1,79 @@
+---
+title: "Releases"
+description: "FastMCP versioning and release process"
+icon: "truck-fast"
+---
+
+FastMCP releases frequently to deliver features quickly in the rapidly evolving MCP ecosystem. We use semantic versioning pragmatically - the Model Context Protocol is young, patterns are still emerging, and waiting for perfect stability would mean missing opportunities to empower developers with better tools.
+
+## Versioning Policy
+
+### Semantic Versioning
+
+**Major (x.0.0)**: Complete API redesigns
+
+Major versions represent fundamental shifts. FastMCP 2.x is entirely different from 1.x in both implementation and design philosophy.
+
+**Minor (2.x.0)**: New features and evolution
+
+<Warning>
+Unlike traditional semantic versioning, minor versions **may** include [breaking changes](#breaking-changes) when necessary for the ecosystem's evolution. This flexibility is essential in a young ecosystem where perfect backwards compatibility would prevent important improvements.
+</Warning>
+
+FastMCP always targets the most current MCP Protocol version. Breaking changes in the MCP spec or MCP SDK automatically flow through to FastMCP - we prioritize staying current with the latest features and conventions over maintaining compatibility with older protocol versions.
+
+**Patch (2.0.x)**: Bug fixes and refinements
+
+Patch versions contain only bug fixes without breaking changes. These are safe updates you can apply with confidence.
+
+### Breaking Changes
+
+We permit breaking changes in minor versions because the MCP ecosystem is rapidly evolving. Refusing to break problematic APIs would accumulate design debt that eventually makes the framework unusable. Each breaking change represents a deliberate decision to keep FastMCP aligned with the ecosystem's evolution.
+
+When breaking changes occur:
+- They only happen in minor versions (e.g., 2.3.x to 2.4.0)
+- Release notes explain what changed and how to migrate
+- We provide deprecation warnings at least 1 minor version in advance when possible
+- Changes must substantially benefit users to justify disruption
+
+The public API is what's covered by our compatibility guarantees - these are the parts of FastMCP you can rely on to remain stable within a minor version. The public API consists of:
+- `FastMCP` server class, `Client` class, and FastMCP `Context`
+- Core MCP components: `Tool`, `Prompt`, `Resource`, `ResourceTemplate`, and transports
+- Their public methods and documented behaviors
+
+Everything else (utilities, private methods, internal modules) may change without notice. This boundary lets us refactor internals and improve implementation details without breaking your code. For production stability, pin to specific versions.
+
+<Warning>
+The `fastmcp.server.auth` module was introduced in 2.12.0 and is exempted from this policy temporarily, meaning it is *expected* to have breaking changes even on patch versions. This is because auth is a rapidly evolving part of the MCP spec and it would be dangerous to be beholden to old decisions. Please pin your FastMCP version if using authentication in production.
+
+We expect this exemption to last through at least the 2.12.x and 2.13.x release series. 
+</Warning>
+
+### Production Use
+
+Pin to exact versions:
+```
+fastmcp==2.11.0  # Good
+fastmcp>=2.11.0  # Bad - will install breaking changes
+```
+
+## Creating Releases
+
+Our release process is intentionally simple:
+
+1. Create GitHub release with tag `vMAJOR.MINOR.PATCH` (e.g., `v2.11.0`)
+2. Generate release notes automatically, and curate or add additional editorial information as needed
+3. GitHub releases automatically trigger PyPI deployments
+
+This automation lets maintainers focus on code quality rather than release mechanics.
+
+### Release Cadence
+
+We follow a feature-driven release cadence rather than a fixed schedule. Minor versions ship approximately every 3-4 weeks when significant functionality is ready.
+
+Patch releases ship promptly for:
+- Critical bug fixes
+- Security updates (immediate release)
+- Regression fixes
+
+This approach means you get improvements as soon as they're ready rather than waiting for arbitrary release dates.
diff --git a/docs/v2/development/tests.mdx b/docs/v2/development/tests.mdx
new file mode 100644
index 0000000..4653368
--- /dev/null
+++ b/docs/v2/development/tests.mdx
@@ -0,0 +1,396 @@
+---
+title: "Tests"
+description: "Testing patterns and requirements for FastMCP"
+icon: vial
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+Good tests are the foundation of reliable software. In FastMCP, we treat tests as first-class documentation that demonstrates how features work while protecting against regressions. Every new capability needs comprehensive tests that demonstrate correctness.
+
+## FastMCP Tests
+
+### Running Tests
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run specific test file
+uv run pytest tests/server/test_auth.py
+
+# Run with coverage
+uv run pytest --cov=fastmcp
+
+# Skip integration tests for faster runs
+uv run pytest -m "not integration"
+
+# Skip tests that spawn processes
+uv run pytest -m "not integration and not client_process"
+```
+
+Tests should complete in under 1 second unless marked as integration tests. This speed encourages running them frequently, catching issues early.
+
+### Test Organization
+
+Our test organization mirrors the source package structure, creating a predictable mapping between code and tests. When you're working on `fastmcp_slim/fastmcp/server/auth.py`, you'll find its tests in `tests/server/test_auth.py`. In rare cases tests are split further - for example, the OpenAPI tests are so comprehensive they're split across multiple files.
+
+### Test Markers
+
+We use pytest markers to categorize tests that require special resources or take longer to run:
+
+```python
+@pytest.mark.integration
+async def test_github_api_integration():
+    """Test GitHub API integration with real service."""
+    token = os.getenv("FASTMCP_GITHUB_TOKEN")
+    if not token:
+        pytest.skip("FASTMCP_GITHUB_TOKEN not available")
+    
+    # Test against real GitHub API
+    client = GitHubClient(token)
+    repos = await client.list_repos("prefecthq")
+    assert "fastmcp" in [repo.name for repo in repos]
+
+@pytest.mark.client_process
+async def test_stdio_transport():
+    """Test STDIO transport with separate process."""
+    # This spawns a subprocess
+    async with Client("python examples/simple_echo.py") as client:
+        result = await client.call_tool("echo", {"message": "test"})
+        assert result.content[0].text == "test"
+```
+
+## Writing Tests
+
+
+### Test Requirements
+
+Following these practices creates maintainable, debuggable test suites that serve as both documentation and regression protection.
+
+#### Single Behavior Per Test
+
+Each test should verify exactly one behavior. When it fails, you need to know immediately what broke. A test that checks five things gives you five potential failure points to investigate. A test that checks one thing points directly to the problem.
+
+<CodeGroup>
+
+```python Good: Atomic Test
+async def test_tool_registration():
+    """Test that tools are properly registered with the server."""
+    mcp = FastMCP("test-server")
+    
+    @mcp.tool
+    def add(a: int, b: int) -> int:
+        return a + b
+    
+    tools = mcp.list_tools()
+    assert len(tools) == 1
+    assert tools[0].name == "add"
+```
+
+```python Bad: Multi-Behavior Test
+async def test_server_functionality():
+    """Test multiple server features at once."""
+    mcp = FastMCP("test-server")
+    
+    # Tool registration
+    @mcp.tool
+    def add(a: int, b: int) -> int:
+        return a + b
+    
+    # Resource creation
+    @mcp.resource("config://app")
+    def get_config():
+        return {"version": "1.0"}
+    
+    # Authentication setup
+    mcp.auth = BearerTokenProvider({"token": "user"})
+    
+    # What exactly are we testing? If this fails, what broke?
+    assert mcp.list_tools()
+    assert mcp.list_resources()
+    assert mcp.auth is not None
+```
+
+</CodeGroup>
+
+#### Self-Contained Setup
+
+Every test must create its own setup. Tests should be runnable in any order, in parallel, or in isolation. When a test fails, you should be able to run just that test to reproduce the issue.
+
+<CodeGroup>
+
+```python Good: Self-Contained
+async def test_tool_execution_with_error():
+    """Test that tool errors are properly handled."""
+    mcp = FastMCP("test-server")
+    
+    @mcp.tool
+    def divide(a: int, b: int) -> float:
+        if b == 0:
+            raise ValueError("Cannot divide by zero")
+        return a / b
+    
+    async with Client(mcp) as client:
+        with pytest.raises(Exception):
+            await client.call_tool("divide", {"a": 10, "b": 0})
+```
+
+```python Bad: Test Dependencies
+# Global state that tests depend on
+test_server = None
+
+def test_setup_server():
+    """Setup for other tests."""
+    global test_server
+    test_server = FastMCP("shared-server")
+
+def test_server_works():
+    """Test server functionality."""
+    # Depends on test_setup_server running first
+    assert test_server is not None
+```
+
+</CodeGroup>
+
+#### Clear Intent
+
+Test names and assertions should make the verified behavior obvious. A developer reading your test should understand what feature it validates and how that feature should behave.
+
+```python
+async def test_authenticated_tool_requires_valid_token():
+    """Test that authenticated users can access protected tools."""
+    mcp = FastMCP("test-server")
+    mcp.auth = BearerTokenProvider({"secret-token": "test-user"})
+    
+    @mcp.tool
+    def protected_action() -> str:
+        return "success"
+    
+    async with Client(mcp, auth=BearerAuth("secret-token")) as client:
+        result = await client.call_tool("protected_action", {})
+        assert result.content[0].text == "success"
+```
+
+#### Using Fixtures
+
+Use fixtures to create reusable data, server configurations, or other resources for your tests. Note that you should **not** open FastMCP clients in your fixtures as it can create hard-to-diagnose issues with event loops.
+
+```python
+import pytest
+from fastmcp import FastMCP, Client
+
+@pytest.fixture
+def weather_server():
+    server = FastMCP("WeatherServer")
+    
+    @server.tool
+    def get_temperature(city: str) -> dict:
+        temps = {"NYC": 72, "LA": 85, "Chicago": 68}
+        return {"city": city, "temp": temps.get(city, 70)}
+    
+    return server
+
+async def test_temperature_tool(weather_server):
+    async with Client(weather_server) as client:
+        result = await client.call_tool("get_temperature", {"city": "LA"})
+        assert result.data == {"city": "LA", "temp": 85}
+```
+
+#### Effective Assertions
+
+Assertions should be specific and provide context on failure. When a test fails during CI, the assertion message should tell you exactly what went wrong.
+
+```python
+# Basic assertion - minimal context on failure
+assert result.status == "success"
+
+# Better - explains what was expected
+assert result.status == "success", f"Expected successful operation, got {result.status}: {result.error}"
+```
+
+Try not to have too many assertions in a single test unless you truly need to check various aspects of the same behavior. In general, assertions of different behaviors should be in separate tests.
+
+#### Inline Snapshots
+
+FastMCP uses `inline-snapshot` for testing complex data structures. On first run of `pytest --inline-snapshot=create` with an empty `snapshot()`, pytest will auto-populate the expected value. To update snapshots after intentional changes, run `pytest --inline-snapshot=fix`. This is particularly useful for testing JSON schemas and API responses.
+
+```python
+from inline_snapshot import snapshot
+
+async def test_tool_schema_generation():
+    """Test that tool schemas are generated correctly."""
+    mcp = FastMCP("test-server")
+    
+    @mcp.tool
+    def calculate_tax(amount: float, rate: float = 0.1) -> dict:
+        """Calculate tax on an amount."""
+        return {"amount": amount, "tax": amount * rate, "total": amount * (1 + rate)}
+    
+    tools = mcp.list_tools()
+    schema = tools[0].inputSchema
+    
+    # First run: snapshot() is empty, gets auto-populated
+    # Subsequent runs: compares against stored snapshot
+    assert schema == snapshot({
+        "type": "object", 
+        "properties": {
+            "amount": {"type": "number"}, 
+            "rate": {"type": "number", "default": 0.1}
+        }, 
+        "required": ["amount"]
+    })
+```
+
+### In-Memory Testing
+
+FastMCP uses in-memory transport for testing, where servers and clients communicate directly. The majority of functionality can be tested in a deterministic fashion this way. We use more complex setups only when testing transports themselves.
+
+The in-memory transport runs the real MCP protocol implementation without network overhead. Instead of deploying your server or managing network connections, you pass your server instance directly to the client. Everything runs in the same Python process - you can set breakpoints anywhere and step through with your debugger.
+
+```python
+from fastmcp import FastMCP, Client
+
+# Create your server
+server = FastMCP("WeatherServer")
+
+@server.tool
+def get_temperature(city: str) -> dict:
+    """Get current temperature for a city"""
+    temps = {"NYC": 72, "LA": 85, "Chicago": 68}
+    return {"city": city, "temp": temps.get(city, 70)}
+
+async def test_weather_operations():
+    # Pass server directly - no deployment needed
+    async with Client(server) as client:
+        result = await client.call_tool("get_temperature", {"city": "NYC"})
+        assert result.data == {"city": "NYC", "temp": 72}
+```
+
+This pattern makes tests deterministic and fast - typically completing in milliseconds rather than seconds.
+
+### Mocking External Dependencies
+
+FastMCP servers are standard Python objects, so you can mock external dependencies using your preferred approach:
+
+```python
+from unittest.mock import AsyncMock
+
+async def test_database_tool():
+    server = FastMCP("DataServer")
+    
+    # Mock the database
+    mock_db = AsyncMock()
+    mock_db.fetch_users.return_value = [
+        {"id": 1, "name": "Alice"},
+        {"id": 2, "name": "Bob"}
+    ]
+    
+    @server.tool
+    async def list_users() -> list:
+        return await mock_db.fetch_users()
+    
+    async with Client(server) as client:
+        result = await client.call_tool("list_users", {})
+        assert len(result.data) == 2
+        assert result.data[0]["name"] == "Alice"
+        mock_db.fetch_users.assert_called_once()
+```
+
+### Testing Network Transports
+
+While in-memory testing covers most unit testing needs, you'll occasionally need to test actual network transports like HTTP or SSE. FastMCP provides two approaches: in-process async servers (preferred), and separate subprocess servers (for special cases).
+
+#### In-Process Network Testing (Preferred)
+
+<VersionBadge version="2.13.0" />
+
+For most network transport tests, use `run_server_async` as an async context manager. This runs the server as a task in the same process, providing fast, deterministic tests with full debugger support:
+
+```python
+import pytest
+from fastmcp import FastMCP, Client
+from fastmcp.client.transports import StreamableHttpTransport
+from fastmcp.utilities.tests import run_server_async
+
+def create_test_server() -> FastMCP:
+    """Create a test server instance."""
+    server = FastMCP("TestServer")
+
+    @server.tool
+    def greet(name: str) -> str:
+        return f"Hello, {name}!"
+
+    return server
+
+@pytest.fixture
+async def http_server() -> str:
+    """Start server in-process for testing."""
+    server = create_test_server()
+    async with run_server_async(server) as url:
+        yield url
+
+async def test_http_transport(http_server: str):
+    """Test actual HTTP transport behavior."""
+    async with Client(
+        transport=StreamableHttpTransport(http_server)
+    ) as client:
+        result = await client.ping()
+        assert result is True
+
+        greeting = await client.call_tool("greet", {"name": "World"})
+        assert greeting.data == "Hello, World!"
+```
+
+The `run_server_async` context manager automatically handles server lifecycle and cleanup. This approach is faster than subprocess-based testing and provides better error messages.
+
+#### Subprocess Testing (Special Cases)
+
+For tests that require complete process isolation (like STDIO transport or testing subprocess behavior), use `run_server_in_process`:
+
+```python
+import pytest
+from fastmcp.utilities.tests import run_server_in_process
+from fastmcp import FastMCP, Client
+from fastmcp.client.transports import StreamableHttpTransport
+
+def run_server(host: str, port: int) -> None:
+    """Function to run in subprocess."""
+    server = FastMCP("TestServer")
+    
+    @server.tool
+    def greet(name: str) -> str:
+        return f"Hello, {name}!"
+    
+    server.run(host=host, port=port)
+
+@pytest.fixture
+async def http_server():
+    """Fixture that runs server in subprocess."""
+    with run_server_in_process(run_server, transport="http") as url:
+        yield f"{url}/mcp"
+
+async def test_http_transport(http_server: str):
+    """Test actual HTTP transport behavior."""
+    async with Client(
+        transport=StreamableHttpTransport(http_server)
+    ) as client:
+        result = await client.ping()
+        assert result is True
+```
+
+The `run_server_in_process` utility handles server lifecycle, port allocation, and cleanup automatically. Use this only when subprocess isolation is truly necessary, as it's slower and harder to debug than in-process testing. FastMCP uses the `client_process` marker to isolate these tests in CI.
+
+### Documentation Testing
+
+Documentation requires the same validation as code. The `just docs` command launches a local Mintlify server that renders your documentation exactly as users will see it:
+
+```bash
+# Start local documentation server with hot reload
+just docs
+
+# Or run Mintlify directly
+mintlify dev
+```
+
+The local server watches for changes and automatically refreshes. This preview catches formatting issues and helps you see documentation as users will experience it.
diff --git a/docs/v2/development/upgrade-guide.mdx b/docs/v2/development/upgrade-guide.mdx
new file mode 100644
index 0000000..93b3148
--- /dev/null
+++ b/docs/v2/development/upgrade-guide.mdx
@@ -0,0 +1,153 @@
+---
+title: Upgrade Guide
+sidebarTitle: Upgrade Guide
+description: Migration instructions for upgrading between FastMCP versions
+icon: up
+tag: NEW
+---
+
+This guide provides migration instructions for breaking changes and major updates when upgrading between FastMCP versions.
+
+## v2.14.0
+
+### OpenAPI Parser Promotion
+
+The experimental OpenAPI parser is now the standard implementation. The legacy parser has been removed.
+
+**If you were using the legacy parser:** No code changes required. The new parser is a drop-in replacement with improved architecture.
+
+**If you were using the experimental parser:** Update your imports from the experimental module to the standard location:
+
+<CodeGroup>
+```python test="skip" Before
+from fastmcp.experimental.server.openapi import FastMCPOpenAPI, RouteMap, MCPType
+```
+
+```python test="skip" After
+from fastmcp.server.openapi import FastMCPOpenAPI, RouteMap, MCPType
+```
+</CodeGroup>
+
+The experimental imports will continue working temporarily but will show deprecation warnings. The `FASTMCP_EXPERIMENTAL_ENABLE_NEW_OPENAPI_PARSER` environment variable is no longer needed and can be removed.
+
+### Deprecated Features Removed
+
+The following deprecated features have been removed in v2.14.0:
+
+**BearerAuthProvider** (deprecated in v2.11):
+<CodeGroup>
+```python test="skip" Before
+from fastmcp.server.auth.providers.bearer import BearerAuthProvider
+```
+
+```python After
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+```
+</CodeGroup>
+
+**Context.get_http_request()** (deprecated in v2.2.11):
+<CodeGroup>
+```python test="skip" Before
+request = context.get_http_request()
+```
+
+```python After
+from fastmcp.server.dependencies import get_http_request
+request = get_http_request()
+```
+</CodeGroup>
+
+**Top-level Image import** (deprecated in v2.8.1):
+<CodeGroup>
+```python test="skip" Before
+from fastmcp import Image
+```
+
+```python After
+from fastmcp.utilities.types import Image
+```
+</CodeGroup>
+
+**FastMCP dependencies parameter** (deprecated in v2.11.4):
+<CodeGroup>
+```python Before
+mcp = FastMCP("server", dependencies=["requests", "pandas"])
+```
+
+```json After
+{
+  "environment": {
+    "dependencies": ["requests", "pandas"]
+  }
+}
+```
+</CodeGroup>
+
+**Legacy resource prefix format**: The `resource_prefix_format` parameter and "protocol" format have been removed. Only the "path" format is supported (this was already the default).
+
+**FastMCPProxy client parameter**:
+<CodeGroup>
+```python Before
+proxy = FastMCPProxy(client=my_client)
+```
+
+```python After
+proxy = FastMCPProxy(client_factory=lambda: my_client)
+```
+</CodeGroup>
+
+**output_schema=False**:
+<CodeGroup>
+```python Before
+@mcp.tool(output_schema=False)
+def my_tool() -> str:
+    return "result"
+```
+
+```python After
+@mcp.tool(output_schema=None)
+def my_tool() -> str:
+    return "result"
+```
+</CodeGroup>
+
+## v2.13.0
+
+### OAuth Token Key Management
+
+The OAuth proxy now issues its own JWT tokens to clients instead of forwarding upstream provider tokens. This improves security by maintaining proper token audience boundaries.
+
+**What changed:**
+
+The OAuth proxy now implements a token factory pattern - it receives tokens from your OAuth provider (GitHub, Google, etc.), encrypts and stores them, then issues its own FastMCP JWT tokens to clients. This requires cryptographic keys for JWT signing and token encryption.
+
+**Default behavior (development):**
+
+By default, FastMCP automatically manages keys based on your platform:
+- **Mac/Windows**: Keys are auto-managed via system keyring, surviving server restarts with zero configuration. Suitable **only** for development and local testing.
+- **Linux**: Keys are ephemeral (random salt at startup, regenerated on each restart).
+
+This works fine for development and testing where re-authentication after restart is acceptable.
+
+**For production:**
+
+Production deployments must provide explicit keys and use persistent storage. Add these three things:
+
+```python
+auth = GitHubProvider(
+    client_id=os.environ["GITHUB_CLIENT_ID"],
+    client_secret=os.environ["GITHUB_CLIENT_SECRET"],
+    base_url="https://your-server.com",
+
+    # Explicit keys (required for production)
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+
+    # Persistent network storage (required for production)
+    client_storage=RedisStore(host="redis.example.com", port=6379)
+)
+```
+
+**More information:**
+- [OAuth Token Security](/v2/deployment/http#oauth-token-security) - Complete production setup guide
+- [Key and Storage Management](/v2/servers/auth/oauth-proxy#key-and-storage-management) - Detailed explanation of defaults and production requirements
+- [OAuth Proxy Parameters](/v2/servers/auth/oauth-proxy#configuration-parameters) - Parameter documentation
diff --git a/docs/v2/getting-started/installation.mdx b/docs/v2/getting-started/installation.mdx
new file mode 100644
index 0000000..d70eac1
--- /dev/null
+++ b/docs/v2/getting-started/installation.mdx
@@ -0,0 +1,100 @@
+---
+title: Installation
+icon: arrow-down-to-line
+---
+## Install FastMCP
+
+We recommend using [uv](https://docs.astral.sh/uv/getting-started/installation/) to install and manage FastMCP.
+
+If you plan to use FastMCP in your project, you can add it as a dependency with:
+
+```bash
+uv add fastmcp
+```
+
+Alternatively, you can install it directly with `pip` or `uv pip`:
+<CodeGroup>
+    ```bash uv
+    uv pip install fastmcp
+    ```
+
+    ```bash pip
+    pip install fastmcp
+    ```
+</CodeGroup>
+
+<Warning>
+**FastMCP 3.0** is in development and may include breaking changes. To avoid unexpected issues, pin your dependency to v2: `fastmcp<3`
+</Warning>
+
+### Verify Installation
+
+To verify that FastMCP is installed correctly, you can run the following command:
+
+```bash
+fastmcp version
+```
+
+You should see output like the following:
+
+```bash
+$ fastmcp version
+
+FastMCP version:                           2.11.3
+MCP version:                               1.12.4
+Python version:                            3.12.2
+Platform:            macOS-15.3.1-arm64-arm-64bit
+FastMCP root path:            ~/Developer/fastmcp
+```
+
+### Dependency Licensing
+
+<Info>
+FastMCP depends on Cyclopts for CLI functionality. Cyclopts v4 includes docutils as a transitive dependency, which has complex licensing that may trigger compliance reviews in some organizations.
+
+If this is a concern, you can install Cyclopts v5 alpha which removes this dependency:
+
+```bash
+pip install "cyclopts>=5.0.0a1"
+```
+
+Alternatively, wait for the stable v5 release. See [this issue](https://github.com/BrianPugh/cyclopts/issues/672) for details.
+</Info>
+## Upgrading from the Official MCP SDK
+
+Upgrading from the official MCP SDK's FastMCP 1.0 to FastMCP 2.0 is generally straightforward. The core server API is highly compatible, and in many cases, changing your import statement from `from mcp.server.fastmcp import FastMCP` to `from fastmcp import FastMCP` will be sufficient. 
+
+
+```python {5}
+# Before
+# from mcp.server.fastmcp import FastMCP
+
+# After
+from fastmcp import FastMCP
+
+mcp = FastMCP("My MCP Server")
+```
+
+<Warning>
+Prior to `fastmcp==2.3.0` and `mcp==1.8.0`, the 2.x API always mirrored the official 1.0 API. However, as the projects diverge, this can not be guaranteed. You may see deprecation warnings if you attempt to use 1.0 APIs in FastMCP 2.x. Please refer to this documentation for details on new capabilities.
+</Warning>
+
+## Versioning Policy
+
+FastMCP follows semantic versioning with pragmatic adaptations for the rapidly evolving MCP ecosystem. Breaking changes may occur in minor versions (e.g., 2.3.x to 2.4.0) when necessary to stay current with the MCP Protocol.
+
+For production use, always pin to exact versions:
+```
+fastmcp==2.11.0  # Good
+fastmcp>=2.11.0  # Bad - will install breaking changes
+```
+
+See the full [versioning and release policy](/v2/development/releases#versioning-policy) for details on our public API, deprecation practices, and breaking change philosophy. 
+
+## Contributing to FastMCP
+
+Interested in contributing to FastMCP? See the [Contributing Guide](/v2/development/contributing) for details on:
+- Setting up your development environment
+- Running tests and pre-commit hooks
+- Submitting issues and pull requests
+- Code standards and review process
diff --git a/docs/v2/getting-started/quickstart.mdx b/docs/v2/getting-started/quickstart.mdx
new file mode 100644
index 0000000..117efcd
--- /dev/null
+++ b/docs/v2/getting-started/quickstart.mdx
@@ -0,0 +1,136 @@
+---
+title: Quickstart
+icon: rocket-launch
+---
+
+Welcome! This guide will help you quickly set up FastMCP, run your first MCP server, and deploy a server to Prefect Horizon.
+
+If you haven't already installed FastMCP, follow the [installation instructions](/v2/getting-started/installation).
+
+## Create a FastMCP Server
+
+A FastMCP server is a collection of tools, resources, and other MCP components. To create a server, start by instantiating the `FastMCP` class. 
+
+Create a new file called `my_server.py` and add the following code:
+
+```python my_server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP("My MCP Server")
+```
+
+
+That's it! You've created a FastMCP server, albeit a very boring one. Let's add a tool to make it more interesting.
+
+
+## Add a Tool
+
+To add a tool that returns a simple greeting, write a function and decorate it with `@mcp.tool` to register it with the server:
+
+```python my_server.py {5-7}
+from fastmcp import FastMCP
+
+mcp = FastMCP("My MCP Server")
+
+@mcp.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+```
+
+
+## Run the Server
+
+The simplest way to run your FastMCP server is to call its `run()` method. You can choose between different transports, like `stdio` for local servers, or `http` for remote access:
+
+<CodeGroup>
+
+```python my_server.py (stdio) {9, 10}
+from fastmcp import FastMCP
+
+mcp = FastMCP("My MCP Server")
+
+@mcp.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+```python my_server.py (HTTP) {9, 10}
+from fastmcp import FastMCP
+
+mcp = FastMCP("My MCP Server")
+
+@mcp.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+
+</CodeGroup>
+
+This lets us run the server with `python my_server.py`. The stdio transport is the traditional way to connect MCP servers to clients, while the HTTP transport enables remote connections.
+
+<Tip>
+Why do we need the `if __name__ == "__main__":` block?
+
+The `__main__` block is recommended for consistency and compatibility, ensuring your server works with all MCP clients that execute your server file as a script. Users who will exclusively run their server with the FastMCP CLI can omit it, as the CLI imports the server object directly.
+</Tip>
+
+### Using the FastMCP CLI
+
+You can also use the `fastmcp run` command to start your server. Note that the FastMCP CLI **does not** execute the `__main__` block of your server file. Instead, it imports your server object and runs it with whatever transport and options you provide.
+
+For example, to run this server with the default stdio transport (no matter how you called `mcp.run()`), you can use the following command:
+```bash
+fastmcp run my_server.py:mcp
+```
+
+To run this server with the HTTP transport, you can use the following command:
+```bash
+fastmcp run my_server.py:mcp --transport http --port 8000
+```
+
+## Call Your Server
+
+Once your server is running with HTTP transport, you can connect to it with a FastMCP client or any LLM client that supports the MCP protocol:
+
+```python my_client.py
+import asyncio
+from fastmcp import Client
+
+client = Client("http://localhost:8000/mcp")
+
+async def call_tool(name: str):
+    async with client:
+        result = await client.call_tool("greet", {"name": name})
+        print(result)
+
+asyncio.run(call_tool("Ford"))
+```
+
+Note that:
+- FastMCP clients are asynchronous, so we need to use `asyncio.run` to run the client
+- We must enter a client context (`async with client:`) before using the client
+- You can make multiple client calls within the same context
+
+## Deploy to Prefect Horizon
+
+[Prefect Horizon](https://horizon.prefect.io?utm_source=gofastmcp&utm_medium=docs) is the enterprise MCP platform built by the FastMCP team at [Prefect](https://www.prefect.io). It provides managed hosting, authentication, access control, and observability for MCP servers.
+
+<Info>
+Horizon is **free for personal projects** and offers enterprise governance for teams.
+</Info>
+
+To deploy your server, you'll need a [GitHub account](https://github.com). Once you have one, you can deploy your server in three steps:
+
+1. Push your `my_server.py` file to a GitHub repository
+2. Sign in to [Prefect Horizon](https://horizon.prefect.io?utm_source=gofastmcp&utm_medium=docs) with your GitHub account
+3. Create a new project from your repository and enter `my_server.py:mcp` as the server entrypoint
+
+That's it! Horizon will build and deploy your server, making it available at a URL like `https://your-project.fastmcp.app/mcp`. You can chat with it to test its functionality, or connect to it from any LLM client that supports the MCP protocol.
+
+For more details, see the [Prefect Horizon guide](/deployment/prefect-horizon).
diff --git a/docs/v2/getting-started/welcome.mdx b/docs/v2/getting-started/welcome.mdx
new file mode 100644
index 0000000..b8213d4
--- /dev/null
+++ b/docs/v2/getting-started/welcome.mdx
@@ -0,0 +1,115 @@
+---
+title: "Welcome to FastMCP 2.0!"
+sidebarTitle: "Welcome!"
+description: The fast, Pythonic way to build MCP servers and clients.
+icon: hand-wave
+---
+
+<img 
+  src="/assets/brand/f-watercolor-waves.png" 
+  
+  alt="'F' logo on a watercolor background"
+  noZoom
+  className="rounded-2xl block dark:hidden"
+  />
+<img 
+  src="/assets/brand/f-watercolor-waves-dark.png" 
+  alt="'F' logo on a watercolor background"
+  noZoom
+  className="rounded-2xl hidden dark:block"
+  />
+
+
+**FastMCP is the standard framework for building MCP applications.** The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) provides a standardized way to connect LLMs to tools and data, and FastMCP makes it production-ready with clean, Pythonic code:
+
+```python {1}
+from fastmcp import FastMCP
+
+mcp = FastMCP("Demo 🚀")
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Beyond Basic MCP
+
+FastMCP pioneered Python MCP development, and FastMCP 1.0 was incorporated into the [official MCP SDK](https://github.com/modelcontextprotocol/python-sdk) in 2024.
+
+**This is FastMCP 2.0,** the actively maintained version that extends far beyond basic protocol implementation. While the SDK provides core functionality, FastMCP 2.0 delivers everything needed for production: advanced MCP patterns (server composition, proxying, OpenAPI/FastAPI generation, tool transformation), enterprise auth (Google, GitHub, Azure, Auth0, WorkOS, and more), deployment tools, testing frameworks, and comprehensive client libraries.
+
+Ready to build? Start with our [installation guide](/v2/getting-started/installation) or jump straight to the [quickstart](/v2/getting-started/quickstart).
+
+FastMCP is made with 💙 by [Prefect](https://www.prefect.io/).
+
+<Warning>
+**FastMCP 3.0** is in development and may include breaking changes. To avoid unexpected issues, pin your dependency to v2: `fastmcp<3`
+</Warning>
+
+## What is MCP?
+
+The Model Context Protocol lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. It is often described as "the USB-C port for AI", providing a uniform way to connect LLMs to resources they can use. It may be easier to think of it as an API, but specifically designed for LLM interactions. MCP servers can:
+
+- Expose data through `Resources` (think of these sort of like GET endpoints; they are used to load information into the LLM's context)
+- Provide functionality through `Tools` (sort of like POST endpoints; they are used to execute code or otherwise produce a side effect)
+- Define interaction patterns through `Prompts` (reusable templates for LLM interactions)
+- And more!
+
+FastMCP provides a high-level, Pythonic interface for building, managing, and interacting with these servers.
+
+## Why FastMCP?
+
+FastMCP handles all the complex protocol details so you can focus on building. In most cases, decorating a Python function is all you need — FastMCP handles the rest.
+
+🚀 **Fast**: High-level interface means less code and faster development
+
+🍀 **Simple**: Build MCP servers with minimal boilerplate
+
+🐍 **Pythonic**: Feels natural to Python developers
+
+🔍 **Complete**: Everything for production — enterprise auth (Google, GitHub, Azure, Auth0, WorkOS), deployment tools, testing frameworks, client libraries, and more
+
+FastMCP provides the shortest path from idea to production. Deploy locally, to the cloud with [Prefect Horizon](https://horizon.prefect.io?utm_source=gofastmcp&utm_medium=docs) (free for personal projects), or to your own infrastructure.
+
+<Tip>
+**This documentation reflects FastMCP's `main` branch**, meaning it always reflects the latest development version. Features are generally marked with version badges (e.g. `New in version: 2.13.1`) to indicate when they were introduced. Note that this may include features that are not yet released.
+</Tip>
+
+## LLM-Friendly Docs
+
+The FastMCP documentation is available in multiple LLM-friendly formats:
+
+### MCP Server
+
+The FastMCP docs are accessible via MCP! The server URL is `https://gofastmcp.com/mcp`. 
+
+In fact, you can use FastMCP to search the FastMCP docs:
+
+```python
+import asyncio
+from fastmcp import Client
+
+async def main():
+    async with Client("https://gofastmcp.com/mcp") as client:
+        result = await client.call_tool(
+            name="search_fast_mcp",
+            arguments={"query": "deploy a FastMCP server"}
+        )
+    print(result)
+
+asyncio.run(main())
+```
+
+### Text Formats
+
+The docs are also available in [llms.txt format](https://llmstxt.org/):
+- [llms.txt](https://gofastmcp.com/llms.txt) - A sitemap listing all documentation pages
+- [llms-full.txt](https://gofastmcp.com/llms-full.txt) - The entire documentation in one file (may exceed context windows)
+
+Any page can be accessed as markdown by appending `.md` to the URL. For example, this page becomes `https://gofastmcp.com/getting-started/welcome.md`.
+
+You can also copy any page as markdown by pressing "Cmd+C" (or "Ctrl+C" on Windows) on your keyboard.
diff --git a/docs/v2/integrations/anthropic.mdx b/docs/v2/integrations/anthropic.mdx
new file mode 100644
index 0000000..7d2d38d
--- /dev/null
+++ b/docs/v2/integrations/anthropic.mdx
@@ -0,0 +1,228 @@
+---
+title: Anthropic API 🤝 FastMCP
+sidebarTitle: Anthropic API
+description: Connect FastMCP servers to the Anthropic API
+icon: message-code
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+
+Anthropic's [Messages API](https://docs.anthropic.com/en/api/messages) supports MCP servers as remote tool sources. This tutorial will show you how to create a FastMCP server and deploy it to a public URL, then how to call it from the Messages API.
+
+<Tip>
+Currently, the MCP connector only accesses **tools** from MCP servers—it queries the `list_tools` endpoint and exposes those functions to Claude. Other MCP features like resources and prompts are not currently supported. You can read more about the MCP connector in the [Anthropic documentation](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector).
+</Tip>
+
+## Create a Server
+
+First, create a FastMCP server with the tools you want to expose. For this example, we'll create a server with a single tool that rolls dice.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+
+## Deploy the Server
+
+Your server must be deployed to a public URL in order for Anthropic to access it. The MCP connector supports both SSE and Streamable HTTP transports.
+
+For development, you can use tools like `ngrok` to temporarily expose a locally-running server to the internet. We'll do that for this example (you may need to install `ngrok` and create a free account), but you can use any other method to deploy your server.
+
+Assuming you saved the above code as `server.py`, you can run the following two commands in two separate terminals to deploy your server and expose it to the internet:
+
+<CodeGroup>
+```bash FastMCP server
+python server.py
+```
+
+```bash ngrok
+ngrok http 8000
+```
+</CodeGroup>
+
+<Warning>
+This exposes your unauthenticated server to the internet. Only run this command in a safe environment if you understand the risks.
+</Warning>
+
+## Call the Server
+
+To use the Messages API with MCP servers, you'll need to install the Anthropic Python SDK (not included with FastMCP):
+
+```bash
+pip install anthropic
+```
+
+You'll also need to authenticate with Anthropic. You can do this by setting the `ANTHROPIC_API_KEY` environment variable. Consult the Anthropic SDK documentation for more information.
+
+```bash
+export ANTHROPIC_API_KEY="your-api-key"
+```
+
+Here is an example of how to call your server from Python. Note that you'll need to replace `https://your-server-url.com` with the actual URL of your server. In addition, we use `/mcp/` as the endpoint because we deployed a streamable-HTTP server with the default path; you may need to use a different endpoint if you customized your server's deployment. **At this time you must also include the `extra_headers` parameter with the `anthropic-beta` header.**
+
+```python {5, 13-22}
+import anthropic
+from rich import print
+
+# Your server URL (replace with your actual URL)
+url = 'https://your-server-url.com'
+
+client = anthropic.Anthropic()
+
+response = client.beta.messages.create(
+    model="claude-sonnet-4-20250514",
+    max_tokens=1000,
+    messages=[{"role": "user", "content": "Roll a few dice!"}],
+    mcp_servers=[
+        {
+            "type": "url",
+            "url": f"{url}/mcp/",
+            "name": "dice-server",
+        }
+    ],
+    extra_headers={
+        "anthropic-beta": "mcp-client-2025-04-04"
+    }
+)
+
+print(response.content)
+```
+
+If you run this code, you'll see something like the following output:
+
+```text
+I'll roll some dice for you! Let me use the dice rolling tool.
+
+I rolled 3 dice and got: 4, 2, 6
+
+The results were 4, 2, and 6. Would you like me to roll again or roll a different number of dice?
+```
+
+
+## Authentication
+
+<VersionBadge version="2.6.0" />
+
+The MCP connector supports OAuth authentication through authorization tokens, which means you can secure your server while still allowing Anthropic to access it.
+
+### Server Authentication
+
+The simplest way to add authentication to the server is to use a bearer token scheme. 
+
+For this example, we'll quickly generate our own tokens with FastMCP's `RSAKeyPair` utility, but this may not be appropriate for production use. For more details, see the complete server-side [Token Verification](/v2/servers/auth/token-verification) documentation. 
+
+We'll start by creating an RSA key pair to sign and verify tokens.
+
+```python
+from fastmcp.server.auth.providers.jwt import RSAKeyPair
+
+key_pair = RSAKeyPair.generate()
+access_token = key_pair.create_token(audience="dice-server")
+```
+
+<Warning>
+FastMCP's `RSAKeyPair` utility is for development and testing only.
+</Warning> 
+
+Next, we'll create a `JWTVerifier` to authenticate the server. 
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import JWTVerifier
+
+auth = JWTVerifier(
+    public_key=key_pair.public_key,
+    audience="dice-server",
+)
+
+mcp = FastMCP(name="Dice Roller", auth=auth)
+```
+
+Here is a complete example that you can copy/paste. For simplicity and the purposes of this example only, it will print the token to the console. **Do NOT do this in production!**
+
+```python server.py [expandable]
+from fastmcp import FastMCP
+from fastmcp.server.auth import JWTVerifier
+from fastmcp.server.auth.providers.jwt import RSAKeyPair
+import random
+
+key_pair = RSAKeyPair.generate()
+access_token = key_pair.create_token(audience="dice-server")
+
+auth = JWTVerifier(
+    public_key=key_pair.public_key,
+    audience="dice-server",
+)
+
+mcp = FastMCP(name="Dice Roller", auth=auth)
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    print(f"\n---\n\n🔑 Dice Roller access token:\n\n{access_token}\n\n---\n")
+    mcp.run(transport="http", port=8000)
+```
+
+### Client Authentication
+
+If you try to call the authenticated server with the same Anthropic code we wrote earlier, you'll get an error indicating that the server rejected the request because it's not authenticated.
+
+```text
+Error code: 400 - {
+    "type": "error", 
+    "error": {
+        "type": "invalid_request_error", 
+        "message": "MCP server 'dice-server' requires authentication. Please provide an authorization_token.",
+    },
+}
+```
+
+To authenticate the client, you can pass the token using the `authorization_token` parameter in your MCP server configuration:
+
+```python {8, 21}
+import anthropic
+from rich import print
+
+# Your server URL (replace with your actual URL)
+url = 'https://your-server-url.com'
+
+# Your access token (replace with your actual token)
+access_token = 'your-access-token'
+
+client = anthropic.Anthropic()
+
+response = client.beta.messages.create(
+    model="claude-sonnet-4-20250514",
+    max_tokens=1000,
+    messages=[{"role": "user", "content": "Roll a few dice!"}],
+    mcp_servers=[
+        {
+            "type": "url",
+            "url": f"{url}/mcp/",
+            "name": "dice-server",
+            "authorization_token": access_token
+        }
+    ],
+    extra_headers={
+        "anthropic-beta": "mcp-client-2025-04-04"
+    }
+)
+
+print(response.content)
+```
+
+You should now see the dice roll results in the output.
diff --git a/docs/v2/integrations/auth0.mdx b/docs/v2/integrations/auth0.mdx
new file mode 100644
index 0000000..9e5b186
--- /dev/null
+++ b/docs/v2/integrations/auth0.mdx
@@ -0,0 +1,277 @@
+---
+title: Auth0 OAuth 🤝 FastMCP
+sidebarTitle: Auth0
+description: Secure your FastMCP server with Auth0 OAuth
+icon: shield-check
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.12.4" />
+
+This guide shows you how to secure your FastMCP server using **Auth0 OAuth**. While Auth0 does have support for Dynamic Client Registration, it is not enabled by default so this integration uses the [**OIDC Proxy**](/v2/servers/auth/oidc-proxy) pattern to bridge Auth0's dynamic OIDC configuration with MCP's authentication requirements.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+1. An **[Auth0 Account](https://auth0.com/)** with access to create Applications
+2. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`)
+
+### Step 1: Create an Auth0 Application
+
+Create an Application in your Auth0 settings to get the credentials needed for authentication:
+
+<Steps>
+<Step title="Navigate to Applications">
+    Go to **Applications → Applications** in your Auth0 account.
+
+    Click **"+ Create Application"** to create a new application.
+</Step>
+
+<Step title="Create Your Application">
+    - **Name**: Choose a name users will recognize (e.g., "My FastMCP Server")
+    - **Choose an application type**: Choose "Single Page Web Applications"
+    - Click **Create** to create the application
+</Step>
+
+<Step title="Configure Your Application">
+    Select the "Settings" tab for your application, then find the "Application URIs" section.
+
+    - **Allowed Callback URLs**: Your server URL + `/auth/callback` (e.g., `http://localhost:8000/auth/callback`)
+    - Click **Save** to save your changes
+
+    <Warning>
+    The callback URL must match exactly. The default path is `/auth/callback`, but you can customize it using the `redirect_path` parameter.
+    </Warning>
+
+    <Tip>
+    If you want to use a custom callback path (e.g., `/auth/auth0/callback`), make sure to set the same path in both your Auth0 Application settings and the `redirect_path` parameter when configuring the Auth0Provider.
+    </Tip>
+</Step>
+
+<Step title="Save Your Credentials">
+    After creating the app, in the "Basic Information" section you'll see:
+
+    - **Client ID**: A public identifier like `tv2ObNgaZAWWhhycr7Bz1LU2mxlnsmsB`
+    - **Client Secret**: A private hidden value that should always be stored securely
+
+    <Tip>
+    Store these credentials securely. Never commit them to version control. Use environment variables or a secrets manager in production.
+    </Tip>
+</Step>
+
+<Step title="Select Your Audience">
+  Go to **Applications → APIs** in your Auth0 account.
+
+    - Find the API that you want to use for your application
+    - **API Audience**: A URL that uniquely identifies the API
+
+    <Tip>
+    Store this along with of the credentials above. Never commit this to version control. Use environment variables or a secrets manager in production.
+    </Tip>
+</Step>
+</Steps>
+
+### Step 2: FastMCP Configuration
+
+Create your FastMCP server using the `Auth0Provider`.
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.auth0 import Auth0Provider
+
+# The Auth0Provider utilizes Auth0 OIDC configuration
+auth_provider = Auth0Provider(
+    config_url="https://.../.well-known/openid-configuration",  # Your Auth0 configuration URL
+    client_id="tv2ObNgaZAWWhhycr7Bz1LU2mxlnsmsB",               # Your Auth0 application Client ID
+    client_secret="vPYqbjemq...",                               # Your Auth0 application Client Secret
+    audience="https://...",                                     # Your Auth0 API audience
+    base_url="http://localhost:8000",                           # Must match your application configuration
+    # redirect_path="/auth/callback"                            # Default value, customize if needed
+)
+
+mcp = FastMCP(name="Auth0 Secured App", auth=auth_provider)
+
+# Add a protected tool to test authentication
+@mcp.tool
+async def get_token_info() -> dict:
+    """Returns information about the Auth0 token."""
+    from fastmcp.server.dependencies import get_access_token
+
+    token = get_access_token()
+
+    return {
+        "issuer": token.claims.get("iss"),
+        "audience": token.claims.get("aud"),
+        "scope": token.claims.get("scope")
+    }
+```
+
+## Testing
+
+### Running the Server
+
+Start your FastMCP server with HTTP transport to enable OAuth flows:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Your server is now running and protected by Auth0 authentication.
+
+### Testing with a Client
+
+Create a test client that authenticates with your Auth0-protected server:
+
+```python test_client.py
+from fastmcp import Client
+import asyncio
+
+async def main():
+    # The client will automatically handle Auth0 OAuth flows
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        # First-time connection will open Auth0 login in your browser
+        print("✓ Authenticated with Auth0!")
+
+        # Test the protected tool
+        result = await client.call_tool("get_token_info")
+        print(f"Auth0 audience: {result['audience']}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+1. Your browser will open to Auth0's authorization page
+2. After you authorize the app, you'll be redirected back
+3. The client receives the token and can make authenticated requests
+
+## Production Configuration
+
+<VersionBadge version="2.13.0" />
+
+For production deployments with persistent token management across server restarts, configure `jwt_signing_key`, and `client_storage`:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.auth0 import Auth0Provider
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+# Production setup with encrypted persistent token storage
+auth_provider = Auth0Provider(
+    config_url="https://.../.well-known/openid-configuration",
+    client_id="tv2ObNgaZAWWhhycr7Bz1LU2mxlnsmsB",
+    client_secret="vPYqbjemq...",
+    audience="https://...",
+    base_url="https://your-production-domain.com",
+
+    # Production token management
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(
+            host=os.environ["REDIS_HOST"],
+            port=int(os.environ["REDIS_PORT"])
+        ),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+
+mcp = FastMCP(name="Production Auth0 App", auth=auth_provider)
+```
+
+<Note>
+Parameters (`jwt_signing_key` and `client_storage`) work together to ensure tokens and client registrations survive server restarts. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without it, tokens are stored in plaintext. Store secrets in environment variables and use a persistent storage backend like Redis for distributed deployments.
+
+For complete details on these parameters, see the [OAuth Proxy documentation](/v2/servers/auth/oauth-proxy#configuration-parameters).
+</Note>
+
+<Info>
+The client caches tokens locally, so you won't need to re-authenticate for subsequent runs unless the token expires or you explicitly clear the cache.
+</Info>
+
+## Environment Variables
+
+For production deployments, use environment variables instead of hardcoding credentials.
+
+### Provider Selection
+
+Setting this environment variable allows the Auth0 provider to be used automatically without explicitly instantiating it in code.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH" default="Not set">
+Set to `fastmcp.server.auth.providers.auth0.Auth0Provider` to use Auth0 authentication.
+</ParamField>
+</Card>
+
+### Auth0-Specific Configuration
+
+These environment variables provide default values for the Auth0 provider, whether it's instantiated manually or configured via `FASTMCP_SERVER_AUTH`.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH_AUTH0_CONFIG_URL" required>
+Your Auth0 Application Configuration URL (e.g., `https://.../.well-known/openid-configuration`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AUTH0_CLIENT_ID" required>
+Your Auth0 Application Client ID (e.g., `tv2ObNgaZAWWhhycr7Bz1LU2mxlnsmsB`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AUTH0_CLIENT_SECRET" required>
+Your Auth0 Application Client Secret (e.g., `vPYqbjemq...`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AUTH0_AUDIENCE" required>
+Your Auth0 API Audience
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AUTH0_BASE_URL" required>
+Public URL where OAuth endpoints will be accessible (includes any mount path)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AUTH0_ISSUER_URL" default="Uses BASE_URL">
+Issuer URL for OAuth metadata (defaults to `BASE_URL`). Set to root-level URL when mounting under a path prefix to avoid 404 logs. See [HTTP Deployment guide](/v2/deployment/http#mounting-authenticated-servers) for details.
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AUTH0_REDIRECT_PATH" default="/auth/callback">
+Redirect path configured in your Auth0 Application
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AUTH0_REQUIRED_SCOPES" default='["openid"]'>
+Comma-, space-, or JSON-separated list of required AUth0 scopes (e.g., `openid email` or `["openid","email"]`)
+</ParamField>
+</Card>
+
+Example `.env` file:
+```bash
+# Use the Auth0 provider
+FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.auth0.Auth0Provider
+
+# Auth0 configuration and credentials
+FASTMCP_SERVER_AUTH_AUTH0_CONFIG_URL=https://.../.well-known/openid-configuration
+FASTMCP_SERVER_AUTH_AUTH0_CLIENT_ID=tv2ObNgaZAWWhhycr7Bz1LU2mxlnsmsB
+FASTMCP_SERVER_AUTH_AUTH0_CLIENT_SECRET=vPYqbjemq...
+FASTMCP_SERVER_AUTH_AUTH0_AUDIENCE=https://...
+FASTMCP_SERVER_AUTH_AUTH0_BASE_URL=https://your-server.com
+FASTMCP_SERVER_AUTH_AUTH0_REQUIRED_SCOPES=openid,email
+```
+
+With environment variables set, your server code simplifies to:
+
+```python server.py
+from fastmcp import FastMCP
+
+# Authentication is automatically configured from environment
+mcp = FastMCP(name="Auth0 Secured App")
+
+@mcp.tool
+async def search_logs() -> list[str]:
+    """Search the service logs."""
+    # Your tool implementation here
+    pass
+```
diff --git a/docs/v2/integrations/authkit.mdx b/docs/v2/integrations/authkit.mdx
new file mode 100644
index 0000000..aa7799a
--- /dev/null
+++ b/docs/v2/integrations/authkit.mdx
@@ -0,0 +1,133 @@
+---
+title: AuthKit 🤝 FastMCP
+sidebarTitle: AuthKit
+description: Secure your FastMCP server with AuthKit by WorkOS
+icon: shield-check
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.11.0" />
+
+This guide shows you how to secure your FastMCP server using WorkOS's **AuthKit**, a complete authentication and user management solution. This integration uses the [**Remote OAuth**](/v2/servers/auth/remote-oauth) pattern, where AuthKit handles user login and your FastMCP server validates the tokens.
+
+
+## Configuration
+### Prerequisites
+
+Before you begin, you will need:
+1.  A **[WorkOS Account](https://workos.com/)** and a new **Project**.
+2.  An **[AuthKit](https://www.authkit.com/)** instance configured within your WorkOS project.
+3.  Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`).
+
+### Step 1: AuthKit Configuration
+
+In your WorkOS Dashboard, enable AuthKit and configure the following settings:
+
+<Steps>
+<Step title="Enable Dynamic Client Registration">
+    Go to **Applications → Configuration** and enable **Dynamic Client Registration**. This allows MCP clients register with your application automatically.
+
+    ![Enable Dynamic Client Registration](./images/authkit/enable_dcr.png)
+</Step>
+
+<Step title="Note Your AuthKit Domain">
+    Find your **AuthKit Domain** on the configuration page. It will look like `https://your-project-12345.authkit.app`. You'll need this for your FastMCP server configuration.
+</Step>
+</Steps>
+
+### Step 2: FastMCP Configuration
+
+Create your FastMCP server file and use the `AuthKitProvider` to handle all the OAuth integration automatically:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.workos import AuthKitProvider
+
+# The AuthKitProvider automatically discovers WorkOS endpoints
+# and configures JWT token validation
+auth_provider = AuthKitProvider(
+    authkit_domain="https://your-project-12345.authkit.app",
+    base_url="http://localhost:8000"  # Use your actual server URL
+)
+
+mcp = FastMCP(name="AuthKit Secured App", auth=auth_provider)
+```
+
+## Testing
+
+To test your server, you can use the `fastmcp` CLI to run it locally. Assuming you've saved the above code to `server.py` (after replacing the `authkit_domain` and `base_url` with your actual values!), you can run the following command:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Now, you can use a FastMCP client to test that you can reach your server after authenticating:
+
+```python
+from fastmcp import Client
+import asyncio
+
+async def main():
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        assert await client.ping()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+
+## Environment Variables
+
+<VersionBadge version="2.12.1" />
+
+For production deployments, use environment variables instead of hardcoding credentials.
+
+### Provider Selection
+
+Setting this environment variable allows the AuthKit provider to be used automatically without explicitly instantiating it in code.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH" default="Not set">
+Set to `fastmcp.server.auth.providers.workos.AuthKitProvider` to use AuthKit authentication.
+</ParamField>
+</Card>
+
+### AuthKit-Specific Configuration
+
+These environment variables provide default values for the AuthKit provider, whether it's instantiated manually or configured via `FASTMCP_SERVER_AUTH`.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_AUTHKIT_DOMAIN" required>
+Your AuthKit domain (e.g., `https://your-project-12345.authkit.app`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_BASE_URL" required>
+Public URL of your FastMCP server (e.g., `https://your-server.com` or `http://localhost:8000` for development)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_REQUIRED_SCOPES" default="[]">
+Comma-, space-, or JSON-separated list of required OAuth scopes (e.g., `openid profile email` or `["openid", "profile", "email"]`)
+</ParamField>
+</Card>
+
+Example `.env` file:
+```bash
+# Use the AuthKit provider
+FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.workos.AuthKitProvider
+
+# AuthKit configuration
+FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_AUTHKIT_DOMAIN=https://your-project-12345.authkit.app
+FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_BASE_URL=https://your-server.com
+FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_REQUIRED_SCOPES=openid,profile,email
+```
+
+With environment variables set, your server code simplifies to:
+
+```python server.py
+from fastmcp import FastMCP
+
+# Authentication is automatically configured from environment
+mcp = FastMCP(name="AuthKit Secured App")
+```
\ No newline at end of file
diff --git a/docs/v2/integrations/aws-cognito.mdx b/docs/v2/integrations/aws-cognito.mdx
new file mode 100644
index 0000000..4f39e19
--- /dev/null
+++ b/docs/v2/integrations/aws-cognito.mdx
@@ -0,0 +1,365 @@
+---
+title: AWS Cognito OAuth 🤝 FastMCP
+sidebarTitle: AWS Cognito
+description: Secure your FastMCP server with AWS Cognito user pools
+icon: aws
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.12.4" />
+
+This guide shows you how to secure your FastMCP server using **AWS Cognito user pools**. Since AWS Cognito doesn't support Dynamic Client Registration, this integration uses the [**OAuth Proxy**](/v2/servers/auth/oauth-proxy) pattern to bridge AWS Cognito's traditional OAuth with MCP's authentication requirements. It also includes robust JWT token validation, ensuring enterprise-grade authentication.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+1. An **[AWS Account](https://aws.amazon.com/)** with access to create AWS Cognito user pools
+2. Basic familiarity with AWS Cognito concepts (user pools, app clients)
+3. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`)
+
+### Step 1: Create an AWS Cognito User Pool and App Client
+
+Set up AWS Cognito user pool with an app client to get the credentials needed for authentication:
+
+<Steps>
+<Step title="Navigate to AWS Cognito">
+    Go to the **[AWS Cognito Console](https://console.aws.amazon.com/cognito/)** and ensure you're in your desired AWS region.
+
+    Select **"User pools"** from the side navigation (click on the hamburger icon at the top left in case you don't see any), and click **"Create user pool"** to create a new user pool.
+</Step>
+
+<Step title="Define Your Application">
+    AWS Cognito now provides a streamlined setup experience:
+
+    1. **Application type**: Select **"Traditional web application"** (this is the correct choice for FastMCP server-side authentication)
+    2. **Name your application**: Enter a descriptive name (e.g., `FastMCP Server`)
+
+    The traditional web application type automatically configures:
+    - Server-side authentication with client secrets
+    - Authorization code grant flow
+    - Appropriate security settings for confidential clients
+
+    <Info>
+    Choose "Traditional web application" rather than SPA, Mobile app, or Machine-to-machine options. This ensures proper OAuth 2.0 configuration for FastMCP.
+    </Info>
+</Step>
+
+<Step title="Configure Options">
+    AWS will guide you through configuration options:
+
+    - **Sign-in identifiers**: Choose how users will sign in (email, username, or phone)
+    - **Required attributes**: Select any additional user information you need
+    - **Return URL**: Add your callback URL (e.g., `http://localhost:8000/auth/callback` for development)
+
+    <Tip>
+    The simplified interface handles most OAuth security settings automatically based on your application type selection.
+    </Tip>
+</Step>
+
+<Step title="Review and Create">
+    Review your configuration and click **"Create user pool"**.
+
+    After creation, you'll see your user pool details. Save these important values:
+    - **User pool ID** (format: `eu-central-1_XXXXXXXXX`)
+    - **Client ID** (found under → "Applications" → "App clients" in the side navigation → \<Your application name, e.g., `FastMCP Server`\> → "App client information")
+    - **Client Secret** (found under → "Applications" → "App clients" in the side navigation → \<Your application name, e.g., `FastMCP Server`\> → "App client information")
+
+    <Tip>
+    The user pool ID and app client credentials are all you need for FastMCP configuration.
+    </Tip>
+</Step>
+
+<Step title="Configure OAuth Settings">
+    Under "Login pages" in your app client's settings, you can double check and adjust the OAuth configuration:
+
+    - **Allowed callback URLs**: Add your server URL + `/auth/callback` (e.g., `http://localhost:8000/auth/callback`)
+    - **Allowed sign-out URLs**: Optional, for logout functionality
+    - **OAuth 2.0 grant types**: Ensure "Authorization code grant" is selected
+    - **OpenID Connect scopes**: Select scopes your application needs (e.g., `openid`, `email`, `profile`)
+
+    <Tip>
+    For local development, you can use `http://localhost` URLs. For production, you must use HTTPS.
+    </Tip>
+</Step>
+
+<Step title="Configure Resource Server">
+    AWS Cognito requires a resource server entry to support OAuth with protected resources. Without this, token exchange will fail with an `invalid_grant` error.
+
+    Navigate to **"Branding" → "Domain"** in the side navigation, then:
+
+    1. Click **"Create resource server"**
+    2. **Resource server name**: Enter a descriptive name (e.g., `My MCP Server`)
+    3. **Resource server identifier**: Enter your MCP endpoint URL exactly as it will be accessed (e.g., `http://localhost:8000/mcp` for development, or `https://your-server.com/mcp` for production)
+    4. Click **"Create resource server"**
+
+    <Warning>
+    The resource server identifier must exactly match your `base_url + mcp_path`. For the default configuration with `base_url="http://localhost:8000"` and `path="/mcp"`, use `http://localhost:8000/mcp`.
+    </Warning>
+</Step>
+
+<Step title="Save Your Credentials">
+    After setup, you'll have:
+
+    - **User Pool ID**: Format like `eu-central-1_XXXXXXXXX`
+    - **Client ID**: Your application's client identifier
+    - **Client Secret**: Generated client secret (keep secure)
+    - **AWS Region**: Where Your AWS Cognito user pool is located
+
+    <Tip>
+    Store these credentials securely. Never commit them to version control. Use environment variables or AWS Secrets Manager in production.
+    </Tip>
+</Step>
+</Steps>
+
+### Step 2: FastMCP Configuration
+
+Create your FastMCP server using the `AWSCognitoProvider`, which handles AWS Cognito's JWT tokens and user claims automatically:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.aws import AWSCognitoProvider
+from fastmcp.server.dependencies import get_access_token
+
+# The AWSCognitoProvider handles JWT validation and user claims
+auth_provider = AWSCognitoProvider(
+    user_pool_id="eu-central-1_XXXXXXXXX",   # Your AWS Cognito user pool ID
+    aws_region="eu-central-1",               # AWS region (defaults to eu-central-1)
+    client_id="your-app-client-id",          # Your app client ID
+    client_secret="your-app-client-secret",  # Your app client Secret
+    base_url="http://localhost:8000",        # Must match your callback URL
+    # redirect_path="/auth/callback"         # Default value, customize if needed
+)
+
+mcp = FastMCP(name="AWS Cognito Secured App", auth=auth_provider)
+
+# Add a protected tool to test authentication
+@mcp.tool
+async def get_access_token_claims() -> dict:
+    """Get the authenticated user's access token claims."""
+    token = get_access_token()
+    return {
+        "sub": token.claims.get("sub"),
+        "username": token.claims.get("username"),
+        "cognito:groups": token.claims.get("cognito:groups", []),
+    }
+```
+
+## Testing
+
+### Running the Server
+
+Start your FastMCP server with HTTP transport to enable OAuth flows:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Your server is now running and protected by AWS Cognito OAuth authentication.
+
+### Testing with a Client
+
+Create a test client that authenticates with Your AWS Cognito-protected server:
+
+```python test_client.py
+from fastmcp import Client
+import asyncio
+
+async def main():
+    # The client will automatically handle AWS Cognito OAuth
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        # First-time connection will open AWS Cognito login in your browser
+        print("✓ Authenticated with AWS Cognito!")
+
+        # Test the protected tool
+        print("Calling protected tool: get_access_token_claims")
+        result = await client.call_tool("get_access_token_claims")
+        user_data = result.data
+        print("Available access token claims:")
+        print(f"- sub: {user_data.get('sub', 'N/A')}")
+        print(f"- username: {user_data.get('username', 'N/A')}")
+        print(f"- cognito:groups: {user_data.get('cognito:groups', [])}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+1. Your browser will open to AWS Cognito's hosted UI login page
+2. After you sign in (or sign up), you'll be redirected back to your MCP server
+3. The client receives the JWT token and can make authenticated requests
+
+<Info>
+The client caches tokens locally, so you won't need to re-authenticate for subsequent runs unless the token expires or you explicitly clear the cache.
+</Info>
+
+## Production Configuration
+
+<VersionBadge version="2.13.0" />
+
+For production deployments with persistent token management across server restarts, configure `jwt_signing_key`, and `client_storage`:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.aws import AWSCognitoProvider
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+# Production setup with encrypted persistent token storage
+auth_provider = AWSCognitoProvider(
+    user_pool_id="eu-central-1_XXXXXXXXX",
+    aws_region="eu-central-1",
+    client_id="your-app-client-id",
+    client_secret="your-app-client-secret",
+    base_url="https://your-production-domain.com",
+
+    # Production token management
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(
+            host=os.environ["REDIS_HOST"],
+            port=int(os.environ["REDIS_PORT"])
+        ),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+
+mcp = FastMCP(name="Production AWS Cognito App", auth=auth_provider)
+```
+
+<Note>
+Parameters (`jwt_signing_key` and `client_storage`) work together to ensure tokens and client registrations survive server restarts. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without it, tokens are stored in plaintext. Store secrets in environment variables and use a persistent storage backend like Redis for distributed deployments.
+
+For complete details on these parameters, see the [OAuth Proxy documentation](/v2/servers/auth/oauth-proxy#configuration-parameters).
+</Note>
+
+## Environment Variables
+
+For production deployments, use environment variables instead of hardcoding credentials.
+
+### Provider Selection
+
+Setting this environment variable allows the AWS Cognito provider to be used automatically without explicitly instantiating it in code.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH" default="Not set">
+Set to `fastmcp.server.auth.providers.aws.AWSCognitoProvider` to use AWS Cognito authentication.
+</ParamField>
+</Card>
+
+### AWS Cognito-Specific Configuration
+
+These environment variables provide default values for the AWS Cognito provider, whether it's instantiated manually or configured via `FASTMCP_SERVER_AUTH`.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH_AWS_COGNITO_USER_POOL_ID" required>
+Your AWS Cognito user pool ID (e.g., `eu-central-1_XXXXXXXXX`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AWS_COGNITO_AWS_REGION" default="eu-central-1">
+AWS region where your AWS Cognito user pool is located
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AWS_COGNITO_CLIENT_ID" required>
+Your AWS Cognito app client ID
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AWS_COGNITO_CLIENT_SECRET" required>
+Your AWS Cognito app client secret
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AWS_COGNITO_BASE_URL" default="http://localhost:8000">
+Public URL where OAuth endpoints will be accessible (includes any mount path)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AWS_COGNITO_ISSUER_URL" default="Uses BASE_URL">
+Issuer URL for OAuth metadata (defaults to `BASE_URL`). Set to root-level URL when mounting under a path prefix to avoid 404 logs. See [HTTP Deployment guide](/v2/deployment/http#mounting-authenticated-servers) for details.
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AWS_COGNITO_REDIRECT_PATH" default="/auth/callback">
+One of the redirect paths configured in your AWS Cognito app client
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AWS_COGNITO_REQUIRED_SCOPES" default='["openid"]'>
+Comma-, space-, or JSON-separated list of required OAuth scopes (e.g., `openid email` or `["openid","email","profile"]`)
+</ParamField>
+</Card>
+
+Example `.env` file:
+```bash
+# Use the AWS Cognito provider
+FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.aws.AWSCognitoProvider
+
+# AWS Cognito credentials
+FASTMCP_SERVER_AUTH_AWS_COGNITO_USER_POOL_ID=eu-central-1_XXXXXXXXX
+FASTMCP_SERVER_AUTH_AWS_COGNITO_AWS_REGION=eu-central-1
+FASTMCP_SERVER_AUTH_AWS_COGNITO_CLIENT_ID=your-app-client-id
+FASTMCP_SERVER_AUTH_AWS_COGNITO_CLIENT_SECRET=your-app-client-secret
+FASTMCP_SERVER_AUTH_AWS_COGNITO_BASE_URL=https://your-server.com
+FASTMCP_SERVER_AUTH_AWS_COGNITO_REQUIRED_SCOPES=openid,email,profile
+```
+
+With environment variables set, your server code simplifies to:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.dependencies import get_access_token
+
+# Authentication is automatically configured from environment
+mcp = FastMCP(name="AWS Cognito Secured App")
+
+@mcp.tool
+async def get_access_token_claims() -> dict:
+    """Get the authenticated user's access token claims."""
+    token = get_access_token()
+    return {
+        "sub": token.claims.get("sub"),
+        "username": token.claims.get("username"),
+        "cognito:groups": token.claims.get("cognito:groups", []),
+    }
+```
+
+## Features
+
+### JWT Token Validation
+
+The AWS Cognito provider includes robust JWT token validation:
+
+- **Signature Verification**: Validates tokens against AWS Cognito's public keys (JWKS)
+- **Expiration Checking**: Automatically rejects expired tokens
+- **Issuer Validation**: Ensures tokens come from your specific AWS Cognito user pool
+- **Scope Enforcement**: Verifies required OAuth scopes are present
+
+### User Claims and Groups
+
+Access rich user information from AWS Cognito JWT tokens:
+
+```python
+from fastmcp.server.dependencies import get_access_token
+
+@mcp.tool
+async def admin_only_tool() -> str:
+    """A tool only available to admin users."""
+    token = get_access_token()
+    user_groups = token.claims.get("cognito:groups", [])
+
+    if "admin" not in user_groups:
+        raise ValueError("This tool requires admin access")
+
+    return "Admin access granted!"
+```
+
+### Enterprise Integration
+
+Perfect for enterprise environments with:
+
+- **Single Sign-On (SSO)**: Integrate with corporate identity providers
+- **Multi-Factor Authentication (MFA)**: Leverage AWS Cognito's built-in MFA
+- **User Groups**: Role-based access control through AWS Cognito groups
+- **Custom Attributes**: Access custom user attributes defined in your AWS Cognito user pool
+- **Compliance**: Meet enterprise security and compliance requirements
\ No newline at end of file
diff --git a/docs/v2/integrations/azure.mdx b/docs/v2/integrations/azure.mdx
new file mode 100644
index 0000000..208b3f2
--- /dev/null
+++ b/docs/v2/integrations/azure.mdx
@@ -0,0 +1,391 @@
+---
+title: Azure (Microsoft Entra ID) OAuth 🤝 FastMCP
+sidebarTitle: Azure (Entra ID)
+description: Secure your FastMCP server with Azure/Microsoft Entra OAuth
+icon: microsoft
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.13.0" />
+
+This guide shows you how to secure your FastMCP server using **Azure OAuth** (Microsoft Entra ID). Since Azure doesn't support Dynamic Client Registration, this integration uses the [**OAuth Proxy**](/v2/servers/auth/oauth-proxy) pattern to bridge Azure's traditional OAuth with MCP's authentication requirements. FastMCP validates Azure JWTs against your application's client_id.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+1. An **[Azure Account](https://portal.azure.com/)** with access to create App registrations
+2. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`)
+3. Your Azure tenant ID (found in Azure Portal under Microsoft Entra ID)
+
+### Step 1: Create an Azure App Registration
+
+Create an App registration in Azure Portal to get the credentials needed for authentication:
+
+<Steps>
+<Step title="Navigate to App registrations">
+    Go to the [Azure Portal](https://portal.azure.com) and navigate to **Microsoft Entra ID → App registrations**.
+    
+    Click **"New registration"** to create a new application.
+</Step>
+
+<Step title="Configure Your Application">
+    Fill in the application details:
+    
+    - **Name**: Choose a name users will recognize (e.g., "My FastMCP Server")
+    - **Supported account types**: Choose based on your needs:
+      - **Single tenant**: Only users in your organization
+      - **Multitenant**: Users in any Microsoft Entra directory
+      - **Multitenant + personal accounts**: Any Microsoft account
+    - **Redirect URI**: Select "Web" and enter your server URL + `/auth/callback` (e.g., `http://localhost:8000/auth/callback`)
+    
+    <Warning>
+    The redirect URI must match exactly. The default path is `/auth/callback`, but you can customize it using the `redirect_path` parameter. For local development, Azure allows `http://localhost` URLs. For production, you must use HTTPS.
+    </Warning>
+    
+    <Tip>
+    If you want to use a custom callback path (e.g., `/auth/azure/callback`), make sure to set the same path in both your Azure App registration and the `redirect_path` parameter when configuring the AzureProvider.
+    </Tip>
+
+    - **Expose an API**: Configure your Application ID URI and define scopes
+      - Go to **Expose an API** in the App registration sidebar.
+      - Click **Set** next to "Application ID URI" and choose one of:
+        - Keep the default `api://{client_id}`
+        - Set a custom value, following the supported formats (see [Identifier URI restrictions](https://learn.microsoft.com/en-us/entra/identity-platform/identifier-uri-restrictions))
+      - Click **Add a scope** and create a scope your app will require, for example:
+        - Scope name: `read` (or `write`, etc.)
+        - Admin consent display name/description: as appropriate for your org
+        - Who can consent: as needed (Admins only or Admins and users)
+
+    - **Configure Access Token Version**: Ensure your app uses access token v2
+      - Go to **Manifest** in the App registration sidebar.
+      - Find the `requestedAccessTokenVersion` property and set it to `2`:
+        ```json
+        "api": {
+            "requestedAccessTokenVersion": 2
+        }
+        ```
+      - Click **Save** at the top of the manifest editor.
+
+    <Warning>
+    Access token v2 is required for FastMCP's Azure integration to work correctly. If this is not set, you may encounter authentication errors.
+    </Warning>
+
+    <Note>
+    In FastMCP's `AzureProvider`, set `identifier_uri` to your Application ID URI (optional; defaults to `api://{client_id}`) and set `required_scopes` to the unprefixed scope names (e.g., `read`, `write`). During authorization, FastMCP automatically prefixes scopes with your `identifier_uri`.
+    </Note>
+
+
+</Step>
+
+
+<Step title="Create Client Secret">
+    After registration, navigate to **Certificates & secrets** in your app's settings.
+    
+    - Click **"New client secret"**
+    - Add a description (e.g., "FastMCP Server")
+    - Choose an expiration period
+    - Click **"Add"**
+    
+    <Warning>
+    Copy the secret value immediately - it won't be shown again! You'll need to create a new secret if you lose it.
+    </Warning>
+</Step>
+
+<Step title="Note Your Credentials">
+    From the **Overview** page of your app registration, note:
+    
+    - **Application (client) ID**: A UUID like `835f09b6-0f0f-40cc-85cb-f32c5829a149`
+    - **Directory (tenant) ID**: A UUID like `08541b6e-646d-43de-a0eb-834e6713d6d5`
+    - **Client Secret**: The value you copied in the previous step
+    
+    <Tip>
+    Store these credentials securely. Never commit them to version control. Use environment variables or a secrets manager in production.
+    </Tip>
+</Step>
+</Steps>
+
+### Step 2: FastMCP Configuration
+
+Create your FastMCP server using the `AzureProvider`, which handles Azure's OAuth flow automatically:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.azure import AzureProvider
+
+# The AzureProvider handles Azure's token format and validation
+auth_provider = AzureProvider(
+    client_id="835f09b6-0f0f-40cc-85cb-f32c5829a149",  # Your Azure App Client ID
+    client_secret="your-client-secret",                 # Your Azure App Client Secret
+    tenant_id="08541b6e-646d-43de-a0eb-834e6713d6d5", # Your Azure Tenant ID (REQUIRED)
+    base_url="http://localhost:8000",                   # Must match your App registration
+    required_scopes=["your-scope"],                 # At least one scope REQUIRED - name of scope from your App
+    # identifier_uri defaults to api://{client_id}
+    # identifier_uri="api://your-api-id",
+    # Optional: request additional upstream scopes in the authorize request
+    # additional_authorize_scopes=["User.Read", "offline_access", "openid", "email"],
+    # redirect_path="/auth/callback"                  # Default value, customize if needed
+    # base_authority="login.microsoftonline.us"      # For Azure Government (default: login.microsoftonline.com)
+)
+
+mcp = FastMCP(name="Azure Secured App", auth=auth_provider)
+
+# Add a protected tool to test authentication
+@mcp.tool
+async def get_user_info() -> dict:
+    """Returns information about the authenticated Azure user."""
+    from fastmcp.server.dependencies import get_access_token
+    
+    token = get_access_token()
+    # The AzureProvider stores user data in token claims
+    return {
+        "azure_id": token.claims.get("sub"),
+        "email": token.claims.get("email"),
+        "name": token.claims.get("name"),
+        "job_title": token.claims.get("job_title"),
+        "office_location": token.claims.get("office_location")
+    }
+```
+
+<Note>
+**Important**: The `tenant_id` parameter is **REQUIRED**. Azure no longer supports using "common" for new applications due to security requirements. You must use one of:
+
+- **Your specific tenant ID**: Found in Azure Portal (e.g., `08541b6e-646d-43de-a0eb-834e6713d6d5`)
+- **"organizations"**: For work and school accounts only
+- **"consumers"**: For personal Microsoft accounts only
+
+Using your specific tenant ID is recommended for better security and control.
+</Note>
+
+<Note>
+**Important**: The `required_scopes` parameter is **REQUIRED** and must include at least one scope. Azure's OAuth API requires the `scope` parameter in all authorization requests - you cannot authenticate without specifying at least one scope. Use the unprefixed scope names from your Azure App registration (e.g., `["read", "write"]`). These scopes must be created under **Expose an API** in your App registration.
+</Note>
+
+### Scope Handling
+
+FastMCP automatically prefixes `required_scopes` with your `identifier_uri` (e.g., `api://your-client-id`) since these are your custom API scopes. Scopes in `additional_authorize_scopes` are sent as-is since they target external resources like Microsoft Graph.
+
+**`required_scopes`** — Your custom API scopes, defined in Azure "Expose an API":
+
+| You write | Sent to Azure | Validated on tokens |
+|-----------|---------------|---------------------|
+| `mcp-read` | `api://xxx/mcp-read` | ✓ |
+| `my.scope` | `api://xxx/my.scope` | ✓ |
+| `openid` | `openid` | ✗ (OIDC scope) |
+| `api://xxx/read` | `api://xxx/read` | ✓ |
+
+**`additional_authorize_scopes`** — External scopes (e.g., Microsoft Graph) for server-side use:
+
+| You write | Sent to Azure | Validated on tokens |
+|-----------|---------------|---------------------|
+| `User.Read` | `User.Read` | ✗ |
+| `Mail.Send` | `Mail.Send` | ✗ |
+
+<Info>
+**Why aren't `additional_authorize_scopes` validated?** Azure issues separate tokens per resource. The access token FastMCP receives is for *your API*—Graph scopes aren't in its `scp` claim. To call Graph APIs, your server uses the upstream Azure token in an on-behalf-of (OBO) flow.
+</Info>
+
+<Note>
+OIDC scopes (`openid`, `profile`, `email`, `offline_access`) are never prefixed and excluded from validation because Azure doesn't include them in access token `scp` claims.
+</Note>
+
+## Testing
+
+### Running the Server
+
+Start your FastMCP server with HTTP transport to enable OAuth flows:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Your server is now running and protected by Azure OAuth authentication.
+
+### Testing with a Client
+
+Create a test client that authenticates with your Azure-protected server:
+
+```python test_client.py
+from fastmcp import Client
+import asyncio
+
+async def main():
+    # The client will automatically handle Azure OAuth
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        # First-time connection will open Azure login in your browser
+        print("✓ Authenticated with Azure!")
+        
+        # Test the protected tool
+        result = await client.call_tool("get_user_info")
+        print(f"Azure user: {result['email']}")
+        print(f"Name: {result['name']}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+1. Your browser will open to Microsoft's authorization page
+2. Sign in with your Microsoft account (work, school, or personal based on your tenant configuration)
+3. Grant the requested permissions
+4. After authorization, you'll be redirected back
+5. The client receives the token and can make authenticated requests
+
+<Info>
+The client caches tokens locally, so you won't need to re-authenticate for subsequent runs unless the token expires or you explicitly clear the cache.
+</Info>
+
+## Production Configuration
+
+<VersionBadge version="2.13.0" />
+
+For production deployments with persistent token management across server restarts, configure `jwt_signing_key` and `client_storage`:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.azure import AzureProvider
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+# Production setup with encrypted persistent token storage
+auth_provider = AzureProvider(
+    client_id="835f09b6-0f0f-40cc-85cb-f32c5829a149",
+    client_secret="your-client-secret",
+    tenant_id="08541b6e-646d-43de-a0eb-834e6713d6d5",
+    base_url="https://your-production-domain.com",
+    required_scopes=["your-scope"],
+
+    # Production token management
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(
+            host=os.environ["REDIS_HOST"],
+            port=int(os.environ["REDIS_PORT"])
+        ),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+
+mcp = FastMCP(name="Production Azure App", auth=auth_provider)
+```
+
+<Note>
+Parameters (`jwt_signing_key` and `client_storage`) work together to ensure tokens and client registrations survive server restarts. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without it, tokens are stored in plaintext. Store secrets in environment variables and use a persistent storage backend like Redis for distributed deployments.
+
+For complete details on these parameters, see the [OAuth Proxy documentation](/v2/servers/auth/oauth-proxy#configuration-parameters).
+</Note>
+
+## Environment Variables
+
+<VersionBadge version="2.12.1" />
+
+For production deployments, use environment variables instead of hardcoding credentials.
+
+### Provider Selection
+
+Setting this environment variable allows the Azure provider to be used automatically without explicitly instantiating it in code.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH" default="Not set">
+Set to `fastmcp.server.auth.providers.azure.AzureProvider` to use Azure authentication.
+</ParamField>
+</Card>
+
+### Azure-Specific Configuration
+
+These environment variables provide default values for the Azure provider, whether it's instantiated manually or configured via `FASTMCP_SERVER_AUTH`.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH_AZURE_CLIENT_ID" required>
+Your Azure App registration Client ID (e.g., `835f09b6-0f0f-40cc-85cb-f32c5829a149`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AZURE_CLIENT_SECRET" required>
+Your Azure App registration Client Secret
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AZURE_TENANT_ID" required>
+Your Azure tenant ID (specific ID, "organizations", or "consumers")
+
+<Note>
+This is **REQUIRED**. Find your tenant ID in Azure Portal under Microsoft Entra ID → Overview.
+</Note>
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AZURE_BASE_URL" default="http://localhost:8000">
+Public URL where OAuth endpoints will be accessible (includes any mount path)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AZURE_ISSUER_URL" default="Uses BASE_URL">
+Issuer URL for OAuth metadata (defaults to `BASE_URL`). Set to root-level URL when mounting under a path prefix to avoid 404 logs. See [HTTP Deployment guide](/v2/deployment/http#mounting-authenticated-servers) for details.
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AZURE_REDIRECT_PATH" default="/auth/callback">
+Redirect path configured in your Azure App registration
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AZURE_REQUIRED_SCOPES" required>
+Comma-, space-, or JSON-separated list of required scopes for your API (at least one scope required). These are validated on tokens and used as defaults if the client does not request specific scopes. Use unprefixed scope names from your Azure App registration (e.g., `read,write`).
+
+You can include standard OIDC scopes (`openid`, `profile`, `email`, `offline_access`) in `required_scopes`. FastMCP automatically handles them correctly: they're sent to Azure unprefixed and excluded from token validation (since Azure doesn't include OIDC scopes in access token `scp` claims).
+
+<Note>
+Azure's OAuth API requires the `scope` parameter - you must provide at least one scope.
+</Note>
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AZURE_ADDITIONAL_AUTHORIZE_SCOPES" default="">
+Comma-, space-, or JSON-separated list of additional scopes to include in the authorization request without prefixing. Use this to request upstream scopes such as Microsoft Graph permissions. These are not used for token validation.
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AZURE_IDENTIFIER_URI" default="api://{client_id}">
+Application ID URI used to prefix scopes during authorization.
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_AZURE_BASE_AUTHORITY" default="login.microsoftonline.com">
+Azure authority base URL. Override this to use Azure Government:
+
+- `login.microsoftonline.com` - Azure Public Cloud (default)
+- `login.microsoftonline.us` - Azure Government
+
+This setting affects all Azure OAuth endpoints (authorization, token, issuer, JWKS).
+</ParamField>
+</Card>
+
+Example `.env` file:
+```bash
+# Use the Azure provider
+FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.azure.AzureProvider
+
+# Azure OAuth credentials
+FASTMCP_SERVER_AUTH_AZURE_CLIENT_ID=835f09b6-0f0f-40cc-85cb-f32c5829a149
+FASTMCP_SERVER_AUTH_AZURE_CLIENT_SECRET=your-client-secret-here
+FASTMCP_SERVER_AUTH_AZURE_TENANT_ID=08541b6e-646d-43de-a0eb-834e6713d6d5
+FASTMCP_SERVER_AUTH_AZURE_BASE_URL=https://your-server.com
+FASTMCP_SERVER_AUTH_AZURE_REQUIRED_SCOPES=read,write
+# Optional custom API configuration
+# FASTMCP_SERVER_AUTH_AZURE_IDENTIFIER_URI=api://your-api-id
+# Request additional upstream scopes (optional)
+# FASTMCP_SERVER_AUTH_AZURE_ADDITIONAL_AUTHORIZE_SCOPES=User.Read,Mail.Read
+```
+
+With environment variables set, your server code simplifies to:
+
+```python server.py
+from fastmcp import FastMCP
+
+# Authentication is automatically configured from environment
+mcp = FastMCP(name="Azure Secured App")
+
+@mcp.tool
+async def protected_tool(query: str) -> str:
+    """A tool that requires Azure authentication to access."""
+    # Your tool implementation here
+    return f"Processing authenticated request: {query}"
+```
+
diff --git a/docs/v2/integrations/chatgpt.mdx b/docs/v2/integrations/chatgpt.mdx
new file mode 100644
index 0000000..d408555
--- /dev/null
+++ b/docs/v2/integrations/chatgpt.mdx
@@ -0,0 +1,158 @@
+---
+title: ChatGPT 🤝 FastMCP
+sidebarTitle: ChatGPT
+description: Connect FastMCP servers to ChatGPT in Chat and Deep Research modes
+icon: message-smile
+tag: NEW
+---
+
+ChatGPT supports MCP servers through remote HTTP connections in two modes: **Chat mode** for interactive conversations and **Deep Research mode** for comprehensive information retrieval.
+
+<Tip>
+**Developer Mode Required for Chat Mode**: To use MCP servers in regular ChatGPT conversations, you must first enable Developer Mode in your ChatGPT settings. This feature is available for ChatGPT Pro, Team, Enterprise, and Edu users.
+</Tip>
+
+<Note>
+OpenAI's official MCP documentation and examples are built with **FastMCP v2**! Learn more from their [MCP documentation](https://platform.openai.com/docs/mcp) and [Developer Mode guide](https://platform.openai.com/docs/guides/developer-mode).
+</Note>
+
+## Build a Server
+
+First, let's create a simple FastMCP server:
+
+```python server.py
+from fastmcp import FastMCP
+import random
+
+mcp = FastMCP("Demo Server")
+
+@mcp.tool
+def roll_dice(sides: int = 6) -> int:
+    """Roll a dice with the specified number of sides."""
+    return random.randint(1, sides)
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+
+### Deploy Your Server
+
+Your server must be accessible from the internet. For development, use `ngrok`:
+
+<CodeGroup>
+```bash Terminal 1
+python server.py
+```
+
+```bash Terminal 2
+ngrok http 8000
+```
+</CodeGroup>
+
+Note your public URL (e.g., `https://abc123.ngrok.io`) for the next steps.
+
+## Chat Mode
+
+Chat mode lets you use MCP tools directly in ChatGPT conversations. See [OpenAI's Developer Mode guide](https://platform.openai.com/docs/guides/developer-mode) for the latest requirements.
+
+### Add to ChatGPT
+
+#### 1. Enable Developer Mode
+
+1. Open ChatGPT and go to **Settings** → **Connectors**
+2. Under **Advanced**, toggle **Developer Mode** to enabled
+
+#### 2. Create Connector
+
+1. In **Settings** → **Connectors**, click **Create**
+2. Enter:
+   - **Name**: Your server name
+   - **Server URL**: `https://your-server.ngrok.io/mcp/`
+3. Check **I trust this provider**
+4. Add authentication if needed
+5. Click **Create**
+
+<Note>
+**Without Developer Mode**: If you don't have search/fetch tools, ChatGPT will reject the server. With Developer Mode enabled, you don't need search/fetch tools for Chat mode.
+</Note>
+
+#### 3. Use in Chat
+
+1. Start a new chat
+2. Click the **+** button → **More** → **Developer Mode**
+3. **Enable your MCP server connector** (required - the connector must be explicitly added to each chat)
+4. Now you can use your tools:
+
+Example usage:
+- "Roll a 20-sided dice"
+- "Roll dice" (uses default 6 sides)
+
+<Tip>
+The connector must be explicitly enabled in each chat session through Developer Mode. Once added, it remains active for the entire conversation.
+</Tip>
+
+### Skip Confirmations
+
+Use `annotations=ToolAnnotations(readOnlyHint=True)` to skip confirmation prompts for read-only tools:
+
+```python
+from mcp.types import ToolAnnotations
+
+@mcp.tool(annotations=ToolAnnotations(readOnlyHint=True))
+def get_status() -> str:
+    """Check system status."""
+    return "All systems operational"
+
+@mcp.tool()  # No annotation - ChatGPT may ask for confirmation
+def delete_item(id: str) -> str:
+    """Delete an item."""
+    return f"Deleted {id}"
+```
+
+## Deep Research Mode
+
+Deep Research mode provides systematic information retrieval with citations. See [OpenAI's MCP documentation](https://platform.openai.com/docs/mcp) for the latest Deep Research specifications.
+
+<Warning>
+**Search and Fetch Required**: Without Developer Mode, ChatGPT will reject any server that doesn't have both `search` and `fetch` tools. Even in Developer Mode, Deep Research only uses these two tools.
+</Warning>
+
+### Tool Implementation
+
+Deep Research tools must follow this pattern:
+
+```python
+@mcp.tool()
+def search(query: str) -> dict:
+    """
+    Search for records matching the query.
+    Must return {"ids": [list of string IDs]}
+    """
+    # Your search logic
+    matching_ids = ["id1", "id2", "id3"]
+    return {"ids": matching_ids}
+
+@mcp.tool()
+def fetch(id: str) -> dict:
+    """
+    Fetch a complete record by ID.
+    Return the full record data for ChatGPT to analyze.
+    """
+    # Your fetch logic
+    return {
+        "id": id,
+        "title": "Record Title",
+        "content": "Full record content...",
+        "metadata": {"author": "Jane Doe", "date": "2024"}
+    }
+```
+
+### Using Deep Research
+
+1. Ensure your server is added to ChatGPT's connectors (same as Chat mode)
+2. Start a new chat
+3. Click **+** → **Deep Research**
+4. Select your MCP server as a source
+5. Ask research questions
+
+ChatGPT will use your `search` and `fetch` tools to find and cite relevant information.
diff --git a/docs/v2/integrations/claude-code.mdx b/docs/v2/integrations/claude-code.mdx
new file mode 100644
index 0000000..2b04c10
--- /dev/null
+++ b/docs/v2/integrations/claude-code.mdx
@@ -0,0 +1,177 @@
+---
+title: Claude Code 🤝 FastMCP
+sidebarTitle: Claude Code
+description: Install and use FastMCP servers in Claude Code
+icon: message-smile
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+import { LocalFocusTip } from "/snippets/local-focus.mdx"
+
+<LocalFocusTip />
+
+Claude Code supports MCP servers through multiple transport methods including STDIO, SSE, and HTTP, allowing you to extend Claude's capabilities with custom tools, resources, and prompts from your FastMCP servers.
+
+## Requirements
+
+This integration uses STDIO transport to run your FastMCP server locally. For remote deployments, you can run your FastMCP server with HTTP or SSE transport and configure it directly using Claude Code's built-in MCP management commands.
+
+## Create a Server
+
+The examples in this guide will use the following simple dice-rolling server, saved as `server.py`.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Install the Server
+
+### FastMCP CLI
+<VersionBadge version="2.10.3" />
+
+The easiest way to install a FastMCP server in Claude Code is using the `fastmcp install claude-code` command. This automatically handles the configuration, dependency management, and calls Claude Code's built-in MCP management system.
+
+```bash
+fastmcp install claude-code server.py
+```
+
+The install command supports the same `file.py:object` notation as the `run` command. If no object is specified, it will automatically look for a FastMCP server object named `mcp`, `server`, or `app` in your file:
+
+```bash
+# These are equivalent if your server object is named 'mcp'
+fastmcp install claude-code server.py
+fastmcp install claude-code server.py:mcp
+
+# Use explicit object name if your server has a different name
+fastmcp install claude-code server.py:my_custom_server
+```
+
+The command will automatically configure the server with Claude Code's `claude mcp add` command.
+
+#### Dependencies
+
+FastMCP provides flexible dependency management options for your Claude Code servers:
+
+**Individual packages**: Use the `--with` flag to specify packages your server needs. You can use this flag multiple times:
+
+```bash
+fastmcp install claude-code server.py --with pandas --with requests
+```
+
+**Requirements file**: If you maintain a `requirements.txt` file with all your dependencies, use `--with-requirements` to install them:
+
+```bash
+fastmcp install claude-code server.py --with-requirements requirements.txt
+```
+
+**Editable packages**: For local packages under development, use `--with-editable` to install them in editable mode:
+
+```bash
+fastmcp install claude-code server.py --with-editable ./my-local-package
+```
+
+Alternatively, you can use a `fastmcp.json` configuration file (recommended):
+
+```json fastmcp.json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "dependencies": ["pandas", "requests"]
+  }
+}
+```
+
+
+#### Python Version and Project Configuration
+
+Control the Python environment for your server with these options:
+
+**Python version**: Use `--python` to specify which Python version your server requires. This ensures compatibility when your server needs specific Python features:
+
+```bash
+fastmcp install claude-code server.py --python 3.11
+```
+
+**Project directory**: Use `--project` to run your server within a specific project context. This tells `uv` to use the project's configuration files and virtual environment:
+
+```bash
+fastmcp install claude-code server.py --project /path/to/my-project
+```
+
+#### Environment Variables
+
+If your server needs environment variables (like API keys), you must include them:
+
+```bash
+fastmcp install claude-code server.py --server-name "Weather Server" \
+  --env API_KEY=your-api-key \
+  --env DEBUG=true
+```
+
+Or load them from a `.env` file:
+
+```bash
+fastmcp install claude-code server.py --server-name "Weather Server" --env-file .env
+```
+
+<Warning>
+**Claude Code must be installed**. The integration looks for the Claude Code CLI at the default installation location (`~/.claude/local/claude`) and uses the `claude mcp add` command to register servers.
+</Warning>
+
+### Manual Configuration
+
+For more control over the configuration, you can manually use Claude Code's built-in MCP management commands. This gives you direct control over how your server is launched:
+
+```bash
+# Add a server with custom configuration
+claude mcp add dice-roller -- uv run --with fastmcp fastmcp run server.py
+
+# Add with environment variables
+claude mcp add weather-server -e API_KEY=secret -e DEBUG=true -- uv run --with fastmcp fastmcp run server.py
+
+# Add with specific scope (local, user, or project)
+claude mcp add my-server --scope user -- uv run --with fastmcp fastmcp run server.py
+```
+
+You can also manually specify Python versions and project directories in your Claude Code commands:
+
+```bash
+# With specific Python version
+claude mcp add ml-server -- uv run --python 3.11 --with fastmcp fastmcp run server.py
+
+# Within a project directory
+claude mcp add project-server -- uv run --project /path/to/project --with fastmcp fastmcp run server.py
+```
+
+## Using the Server
+
+Once your server is installed, you can start using your FastMCP server with Claude Code.
+
+Try asking Claude something like:
+
+> "Roll some dice for me"
+
+Claude will automatically detect your `roll_dice` tool and use it to fulfill your request, returning something like:
+
+> I'll roll some dice for you! Here are your results: [4, 2, 6]
+> 
+> You rolled three dice and got a 4, a 2, and a 6!
+
+Claude Code can now access all the tools, resources, and prompts you've defined in your FastMCP server. 
+
+If your server provides resources, you can reference them with `@` mentions using the format `@server:protocol://resource/path`. If your server provides prompts, you can use them as slash commands with `/mcp__servername__promptname`.
\ No newline at end of file
diff --git a/docs/v2/integrations/claude-desktop.mdx b/docs/v2/integrations/claude-desktop.mdx
new file mode 100644
index 0000000..98a6ffe
--- /dev/null
+++ b/docs/v2/integrations/claude-desktop.mdx
@@ -0,0 +1,298 @@
+---
+title: Claude Desktop 🤝 FastMCP
+sidebarTitle: Claude Desktop
+description: Connect FastMCP servers to Claude Desktop
+icon: message-smile
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+import { LocalFocusTip } from "/snippets/local-focus.mdx"
+
+<LocalFocusTip />
+
+Claude Desktop supports MCP servers through local STDIO connections and remote servers (beta), allowing you to extend Claude's capabilities with custom tools, resources, and prompts from your FastMCP servers.
+
+<Note>
+Remote MCP server support is currently in beta and available for users on Claude Pro, Max, Team, and Enterprise plans (as of June 2025). Most users will still need to use local STDIO connections.
+</Note>
+
+<Note>
+This guide focuses specifically on using FastMCP servers with Claude Desktop. For general Claude Desktop MCP setup and official examples, see the [official Claude Desktop quickstart guide](https://modelcontextprotocol.io/quickstart/user).
+</Note>
+
+
+## Requirements
+
+Claude Desktop traditionally requires MCP servers to run locally using STDIO transport, where your server communicates with Claude through standard input/output rather than HTTP. However, users on certain plans now have access to remote server support as well.
+
+<Tip>
+If you don't have access to remote server support or need to connect to remote servers, you can create a **proxy server** that runs locally via STDIO and forwards requests to remote HTTP servers. See the [Proxy Servers](#proxy-servers) section below.
+</Tip>
+
+## Create a Server
+
+The examples in this guide will use the following simple dice-rolling server, saved as `server.py`.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Install the Server
+
+### FastMCP CLI
+<VersionBadge version="2.10.3" />
+
+The easiest way to install a FastMCP server in Claude Desktop is using the `fastmcp install claude-desktop` command. This automatically handles the configuration and dependency management.
+
+<Tip>
+Prior to version 2.10.3, Claude Desktop could be managed by running `fastmcp install <path>` without specifying the client.
+</Tip>
+
+```bash
+fastmcp install claude-desktop server.py
+```
+
+The install command supports the same `file.py:object` notation as the `run` command. If no object is specified, it will automatically look for a FastMCP server object named `mcp`, `server`, or `app` in your file:
+
+```bash
+# These are equivalent if your server object is named 'mcp'
+fastmcp install claude-desktop server.py
+fastmcp install claude-desktop server.py:mcp
+
+# Use explicit object name if your server has a different name
+fastmcp install claude-desktop server.py:my_custom_server
+```
+
+After installation, restart Claude Desktop completely. You should see a hammer icon (🔨) in the bottom left of the input box, indicating that MCP tools are available.
+
+#### Dependencies
+
+FastMCP provides several ways to manage your server's dependencies when installing in Claude Desktop:
+
+**Individual packages**: Use the `--with` flag to specify packages your server needs. You can use this flag multiple times:
+
+```bash
+fastmcp install claude-desktop server.py --with pandas --with requests
+```
+
+**Requirements file**: If you have a `requirements.txt` file listing all your dependencies, use `--with-requirements` to install them all at once:
+
+```bash
+fastmcp install claude-desktop server.py --with-requirements requirements.txt
+```
+
+**Editable packages**: For local packages in development, use `--with-editable` to install them in editable mode:
+
+```bash
+fastmcp install claude-desktop server.py --with-editable ./my-local-package
+```
+
+Alternatively, you can use a `fastmcp.json` configuration file (recommended):
+
+```json fastmcp.json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "dependencies": ["pandas", "requests"]
+  }
+}
+```
+
+
+#### Python Version and Project Directory
+
+FastMCP allows you to control the Python environment for your server:
+
+**Python version**: Use `--python` to specify which Python version your server should run with. This is particularly useful when your server requires a specific Python version:
+
+```bash
+fastmcp install claude-desktop server.py --python 3.11
+```
+
+**Project directory**: Use `--project` to run your server within a specific project directory. This ensures that `uv` will discover all `pyproject.toml`, `uv.toml`, and `.python-version` files from that project:
+
+```bash
+fastmcp install claude-desktop server.py --project /path/to/my-project
+```
+
+When you specify a project directory, all relative paths in your server will be resolved from that directory, and the project's virtual environment will be used.
+
+#### Environment Variables
+
+<Warning>
+Claude Desktop runs servers in a completely isolated environment with no access to your shell environment or locally installed applications. You must explicitly pass any environment variables your server needs.
+</Warning>
+
+If your server needs environment variables (like API keys), you must include them:
+
+```bash
+fastmcp install claude-desktop server.py --server-name "Weather Server" \
+  --env API_KEY=your-api-key \
+  --env DEBUG=true
+```
+
+Or load them from a `.env` file:
+
+```bash
+fastmcp install claude-desktop server.py --server-name "Weather Server" --env-file .env
+```
+<Warning>
+- **`uv` must be installed and available in your system PATH**. Claude Desktop runs in its own isolated environment and needs `uv` to manage dependencies.
+- **On macOS, it is recommended to install `uv` globally with Homebrew** so that Claude Desktop will detect it: `brew install uv`. Installing `uv` with other methods may not make it accessible to Claude Desktop.
+</Warning>
+
+
+### Manual Configuration
+
+For more control over the configuration, you can manually edit Claude Desktop's configuration file. You can open the configuration file from Claude's developer settings, or find it in the following locations:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+The configuration file is a JSON object with a `mcpServers` key, which contains the configuration for each MCP server.
+
+```json
+{
+  "mcpServers": {
+    "dice-roller": {
+      "command": "python",
+      "args": ["path/to/your/server.py"]
+    }
+  }
+}
+```
+
+After updating the configuration file, restart Claude Desktop completely. Look for the hammer icon (🔨) to confirm your server is loaded.
+
+#### Dependencies
+
+If your server has dependencies, you can use `uv` or another package manager to set up the environment.
+
+
+When manually configuring dependencies, the recommended approach is to use `uv` with FastMCP. The configuration uses `uv run` to create an isolated environment with your specified packages:
+
+```json
+{
+  "mcpServers": {
+    "dice-roller": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--with", "fastmcp",
+        "--with", "pandas",
+        "--with", "requests", 
+        "fastmcp",
+        "run",
+        "path/to/your/server.py"
+      ]
+    }
+  }
+}
+```
+
+You can also manually specify Python versions and project directories in your configuration. Add `--python` to use a specific Python version, or `--project` to run within a project directory:
+
+```json
+{
+  "mcpServers": {
+    "dice-roller": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--python", "3.11",
+        "--project", "/path/to/project",
+        "--with", "fastmcp",
+        "fastmcp",
+        "run",
+        "path/to/your/server.py"
+      ]
+    }
+  }
+}
+```
+
+The order of arguments matters: Python version and project settings come before package specifications, which come before the actual command to run.
+
+<Warning>
+- **`uv` must be installed and available in your system PATH**. Claude Desktop runs in its own isolated environment and needs `uv` to manage dependencies.
+- **On macOS, it is recommended to install `uv` globally with Homebrew** so that Claude Desktop will detect it: `brew install uv`. Installing `uv` with other methods may not make it accessible to Claude Desktop.
+</Warning>
+
+#### Environment Variables
+
+You can also specify environment variables in the configuration:
+
+```json
+{
+  "mcpServers": {
+    "weather-server": {
+      "command": "python",
+      "args": ["path/to/weather_server.py"],
+      "env": {
+        "API_KEY": "your-api-key",
+        "DEBUG": "true"
+      }
+    }
+  }
+}
+```
+<Warning>
+Claude Desktop runs servers in a completely isolated environment with no access to your shell environment or locally installed applications. You must explicitly pass any environment variables your server needs.
+</Warning>
+
+
+## Remote Servers
+
+
+Users on Claude Pro, Max, Team, and Enterprise plans have first-class remote server support via integrations. For other users, or as an alternative approach, FastMCP can create a proxy server that forwards requests to a remote HTTP server. You can install the proxy server in Claude Desktop.
+
+Create a proxy server that connects to a remote HTTP server:
+
+```python proxy_server.py
+from fastmcp import FastMCP
+
+# Create a proxy to a remote server
+proxy = FastMCP.as_proxy(
+    "https://example.com/mcp/sse", 
+    name="Remote Server Proxy"
+)
+
+if __name__ == "__main__":
+    proxy.run()  # Runs via STDIO for Claude Desktop
+```
+
+### Authentication
+
+For authenticated remote servers, create an authenticated client following the guidance in the [client auth documentation](/v2/clients/auth/bearer) and pass it to the proxy:
+
+```python auth_proxy_server.py {7}
+from fastmcp import FastMCP, Client
+from fastmcp.client.auth import BearerAuth
+
+# Create authenticated client
+client = Client(
+    "https://api.example.com/mcp/sse",
+    auth=BearerAuth(token="your-access-token")
+)
+
+# Create proxy using the authenticated client
+proxy = FastMCP.as_proxy(client, name="Authenticated Proxy")
+
+if __name__ == "__main__":
+    proxy.run()
+```
+
diff --git a/docs/v2/integrations/cursor-install-mcp.png b/docs/v2/integrations/cursor-install-mcp.png
new file mode 100644
index 0000000..5681d70
Binary files /dev/null and b/docs/v2/integrations/cursor-install-mcp.png differ
diff --git a/docs/v2/integrations/cursor.mdx b/docs/v2/integrations/cursor.mdx
new file mode 100644
index 0000000..5b98cbd
--- /dev/null
+++ b/docs/v2/integrations/cursor.mdx
@@ -0,0 +1,284 @@
+---
+title: Cursor 🤝 FastMCP
+sidebarTitle: Cursor
+description: Install and use FastMCP servers in Cursor
+icon: message-smile
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+import { LocalFocusTip } from "/snippets/local-focus.mdx"
+
+<LocalFocusTip />
+
+Cursor supports MCP servers through multiple transport methods including STDIO, SSE, and Streamable HTTP, allowing you to extend Cursor's AI assistant with custom tools, resources, and prompts from your FastMCP servers.
+
+## Requirements
+
+This integration uses STDIO transport to run your FastMCP server locally. For remote deployments, you can run your FastMCP server with HTTP or SSE transport and configure it directly in Cursor's settings.
+
+## Create a Server
+
+The examples in this guide will use the following simple dice-rolling server, saved as `server.py`.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Install the Server
+
+### FastMCP CLI
+<VersionBadge version="2.10.3" />
+
+The easiest way to install a FastMCP server in Cursor is using the `fastmcp install cursor` command. This automatically handles the configuration, dependency management, and opens Cursor with a deeplink to install the server.
+
+```bash
+fastmcp install cursor server.py
+```
+
+#### Workspace Installation
+<VersionBadge version="2.12.0" />
+
+By default, FastMCP installs servers globally for Cursor. You can also install servers to project-specific workspaces using the `--workspace` flag:
+
+```bash
+# Install to current directory's .cursor/ folder
+fastmcp install cursor server.py --workspace .
+
+# Install to specific workspace
+fastmcp install cursor server.py --workspace /path/to/project
+```
+
+This creates a `.cursor/mcp.json` configuration file in the specified workspace directory, allowing different projects to have their own MCP server configurations.
+
+The install command supports the same `file.py:object` notation as the `run` command. If no object is specified, it will automatically look for a FastMCP server object named `mcp`, `server`, or `app` in your file:
+
+```bash
+# These are equivalent if your server object is named 'mcp'
+fastmcp install cursor server.py
+fastmcp install cursor server.py:mcp
+
+# Use explicit object name if your server has a different name
+fastmcp install cursor server.py:my_custom_server
+```
+
+After running the command, Cursor will open automatically and prompt you to install the server. The command will be `uv`, which is expected as this is a Python STDIO server. Click "Install" to confirm:
+
+![Cursor install prompt](./cursor-install-mcp.png)
+
+#### Dependencies
+
+FastMCP offers multiple ways to manage dependencies for your Cursor servers:
+
+**Individual packages**: Use the `--with` flag to specify packages your server needs. You can use this flag multiple times:
+
+```bash
+fastmcp install cursor server.py --with pandas --with requests
+```
+
+**Requirements file**: For projects with a `requirements.txt` file, use `--with-requirements` to install all dependencies at once:
+
+```bash
+fastmcp install cursor server.py --with-requirements requirements.txt
+```
+
+**Editable packages**: When developing local packages, use `--with-editable` to install them in editable mode:
+
+```bash
+fastmcp install cursor server.py --with-editable ./my-local-package
+```
+
+Alternatively, you can use a `fastmcp.json` configuration file (recommended):
+
+```json fastmcp.json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "dependencies": ["pandas", "requests"]
+  }
+}
+```
+
+
+#### Python Version and Project Configuration
+
+Control your server's Python environment with these options:
+
+**Python version**: Use `--python` to specify which Python version your server should use. This is essential when your server requires specific Python features:
+
+```bash
+fastmcp install cursor server.py --python 3.11
+```
+
+**Project directory**: Use `--project` to run your server within a specific project context. This ensures `uv` discovers all project configuration files and uses the correct virtual environment:
+
+```bash
+fastmcp install cursor server.py --project /path/to/my-project
+```
+
+#### Environment Variables
+
+<Warning>
+Cursor runs servers in a completely isolated environment with no access to your shell environment or locally installed applications. You must explicitly pass any environment variables your server needs.
+</Warning>
+
+If your server needs environment variables (like API keys), you must include them:
+
+```bash
+fastmcp install cursor server.py --server-name "Weather Server" \
+  --env API_KEY=your-api-key \
+  --env DEBUG=true
+```
+
+Or load them from a `.env` file:
+
+```bash
+fastmcp install cursor server.py --server-name "Weather Server" --env-file .env
+```
+
+<Warning>
+**`uv` must be installed and available in your system PATH**. Cursor runs in its own isolated environment and needs `uv` to manage dependencies.
+</Warning>
+
+### Generate MCP JSON
+
+<Note>
+**Use the first-class integration above for the best experience.** The MCP JSON generation is useful for advanced use cases, manual configuration, or integration with other tools.
+</Note>
+
+You can generate MCP JSON configuration for manual use:
+
+```bash
+# Generate configuration and output to stdout
+fastmcp install mcp-json server.py --server-name "Dice Roller" --with pandas
+
+# Copy configuration to clipboard for easy pasting
+fastmcp install mcp-json server.py --server-name "Dice Roller" --copy
+```
+
+This generates the standard `mcpServers` configuration format that can be used with any MCP-compatible client.
+
+### Manual Configuration
+
+For more control over the configuration, you can manually edit Cursor's configuration file. The configuration file is located at:
+- **All platforms**: `~/.cursor/mcp.json`
+
+The configuration file is a JSON object with a `mcpServers` key, which contains the configuration for each MCP server.
+
+```json
+{
+  "mcpServers": {
+    "dice-roller": {
+      "command": "python",
+      "args": ["path/to/your/server.py"]
+    }
+  }
+}
+```
+
+After updating the configuration file, your server should be available in Cursor.
+
+#### Dependencies
+
+If your server has dependencies, you can use `uv` or another package manager to set up the environment.
+
+When manually configuring dependencies, the recommended approach is to use `uv` with FastMCP. The configuration should use `uv run` to create an isolated environment with your specified packages:
+
+```json
+{
+  "mcpServers": {
+    "dice-roller": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--with", "fastmcp",
+        "--with", "pandas",
+        "--with", "requests", 
+        "fastmcp",
+        "run",
+        "path/to/your/server.py"
+      ]
+    }
+  }
+}
+```
+
+You can also manually specify Python versions and project directories in your configuration:
+
+```json
+{
+  "mcpServers": {
+    "dice-roller": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--python", "3.11",
+        "--project", "/path/to/project",
+        "--with", "fastmcp",
+        "fastmcp",
+        "run",
+        "path/to/your/server.py"
+      ]
+    }
+  }
+}
+```
+
+Note that the order of arguments is important: Python version and project settings should come before package specifications.
+
+<Warning>
+**`uv` must be installed and available in your system PATH**. Cursor runs in its own isolated environment and needs `uv` to manage dependencies.
+</Warning>
+
+#### Environment Variables
+
+You can also specify environment variables in the configuration:
+
+```json
+{
+  "mcpServers": {
+    "weather-server": {
+      "command": "python",
+      "args": ["path/to/weather_server.py"],
+      "env": {
+        "API_KEY": "your-api-key",
+        "DEBUG": "true"
+      }
+    }
+  }
+}
+```
+
+<Warning>
+Cursor runs servers in a completely isolated environment with no access to your shell environment or locally installed applications. You must explicitly pass any environment variables your server needs.
+</Warning>
+
+## Using the Server
+
+Once your server is installed, you can start using your FastMCP server with Cursor's AI assistant.
+
+Try asking Cursor something like:
+
+> "Roll some dice for me"
+
+Cursor will automatically detect your `roll_dice` tool and use it to fulfill your request, returning something like:
+
+> 🎲 Here are your dice rolls: 4, 6, 4
+> 
+> You rolled 3 dice with a total of 14! The 6 was a nice high roll there!
+
+The AI assistant can now access all the tools, resources, and prompts you've defined in your FastMCP server.
diff --git a/docs/v2/integrations/descope.mdx b/docs/v2/integrations/descope.mdx
new file mode 100644
index 0000000..14bade5
--- /dev/null
+++ b/docs/v2/integrations/descope.mdx
@@ -0,0 +1,146 @@
+---
+title: Descope 🤝 FastMCP
+sidebarTitle: Descope
+description: Secure your FastMCP server with Descope
+icon: shield-check
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+<VersionBadge version="2.12.4" />
+
+This guide shows you how to secure your FastMCP server using [**Descope**](https://www.descope.com), a complete authentication and user management solution. This integration uses the [**Remote OAuth**](/v2/servers/auth/remote-oauth) pattern, where Descope handles user login and your FastMCP server validates the tokens.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+
+1. To [sign up](https://www.descope.com/sign-up) for a Free Forever Descope account
+2. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:3000`)
+
+### Step 1: Configure Descope
+
+<Steps>
+<Step title="Create an MCP Server">
+    1. Go to the [MCP Servers page](https://app.descope.com/mcp-servers) of the Descope Console, and create a new MCP Server.
+    2. Give the MCP server a name and description.
+    3. Ensure that **Dynamic Client Registration (DCR)** is enabled. Then click **Create**.
+    4. Once you've created the MCP Server, note your Well-Known URL.
+    
+    
+    <Warning>
+    DCR is required for FastMCP clients to automatically register with your authentication server.
+    </Warning>
+</Step>
+
+<Step title="Note Your Well-Known URL">
+    Save your Well-Known URL from [MCP Server Settings](https://app.descope.com/mcp-servers):
+    ```
+    Well-Known URL: https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration
+    ```
+</Step>
+</Steps>
+
+### Step 2: Environment Setup
+
+Create a `.env` file with your Descope configuration:
+
+```bash
+DESCOPE_CONFIG_URL=https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration     # Your Descope Well-Known URL
+SERVER_URL=http://localhost:3000     # Your server's base URL
+```
+
+### Step 3: FastMCP Configuration
+
+Create your FastMCP server file and use the DescopeProvider to handle all the OAuth integration automatically:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.descope import DescopeProvider
+
+# The DescopeProvider automatically discovers Descope endpoints
+# and configures JWT token validation
+auth_provider = DescopeProvider(
+    config_url="https://.../.well-known/openid-configuration",  # Your MCP Server .well-known URL
+    base_url=SERVER_URL,                                        # Your server's public URL
+)
+
+# Create FastMCP server with auth
+mcp = FastMCP(name="My Descope Protected Server", auth=auth_provider)
+
+```
+
+## Testing
+
+To test your server, you can use the `fastmcp` CLI to run it locally. Assuming you've saved the above code to `server.py` (after replacing the environment variables with your actual values!), you can run the following command:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Now, you can use a FastMCP client to test that you can reach your server after authenticating:
+
+```python
+from fastmcp import Client
+import asyncio
+
+async def main():
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        assert await client.ping()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Environment Variables
+
+For production deployments, use environment variables instead of hardcoding credentials.
+
+### Provider Selection
+
+Setting this environment variable allows the Descope provider to be used automatically without explicitly instantiating it in code.
+
+<Card>
+  <ParamField path="FASTMCP_SERVER_AUTH" default="Not set">
+    Set to `fastmcp.server.auth.providers.descope.DescopeProvider` to use
+    Descope authentication.
+  </ParamField>
+</Card>
+
+### Descope-Specific Configuration
+
+These environment variables provide default values for the Descope provider, whether it's instantiated manually or configured via `FASTMCP_SERVER_AUTH`.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH_DESCOPEPROVIDER_CONFIG_URL" required>
+Your Well-Known URL from the [Descope Console](https://app.descope.com/mcp-servers)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_DESCOPEPROVIDER_BASE_URL" required>
+  Public URL of your FastMCP server (e.g., `https://your-server.com` or
+  `http://localhost:8000` for development)
+</ParamField>
+</Card>
+
+Example `.env` file:
+
+```bash
+# Use the Descope provider
+FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.descope.DescopeProvider
+
+# Descope configuration
+FASTMCP_SERVER_AUTH_DESCOPEPROVIDER_CONFIG_URL=https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration
+FASTMCP_SERVER_AUTH_DESCOPEPROVIDER_BASE_URL=https://your-server.com
+```
+
+With environment variables set, your server code simplifies to:
+
+```python server.py
+from fastmcp import FastMCP
+
+# Authentication is automatically configured from environment
+mcp = FastMCP(name="My Descope Protected Server")
+```
diff --git a/docs/v2/integrations/discord.mdx b/docs/v2/integrations/discord.mdx
new file mode 100644
index 0000000..b9154e3
--- /dev/null
+++ b/docs/v2/integrations/discord.mdx
@@ -0,0 +1,255 @@
+---
+title: Discord OAuth 🤝 FastMCP
+sidebarTitle: Discord
+description: Secure your FastMCP server with Discord OAuth
+icon: discord
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.13.2" />
+
+This guide shows you how to secure your FastMCP server using **Discord OAuth**. Since Discord doesn't support Dynamic Client Registration, this integration uses the [**OAuth Proxy**](/v2/servers/auth/oauth-proxy) pattern to bridge Discord's traditional OAuth with MCP's authentication requirements.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+1. A **[Discord Account](https://discord.com/)** with access to create applications
+2. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`)
+
+### Step 1: Create a Discord Application
+
+Create an application in the Discord Developer Portal to get the credentials needed for authentication:
+
+<Steps>
+<Step title="Navigate to Discord Developer Portal">
+    Go to the [Discord Developer Portal](https://discord.com/developers/applications).
+
+    Click **"New Application"** and give it a name users will recognize (e.g., "My FastMCP Server").
+</Step>
+
+<Step title="Configure OAuth2 Settings">
+    In the left sidebar, click **"OAuth2"**.
+
+    In the **Redirects** section, click **"Add Redirect"** and enter your callback URL:
+    - For development: `http://localhost:8000/auth/callback`
+    - For production: `https://your-domain.com/auth/callback`
+
+    <Warning>
+    The redirect URL must match exactly. The default path is `/auth/callback`, but you can customize it using the `redirect_path` parameter. Discord allows `http://localhost` URLs for development. For production, use HTTPS.
+    </Warning>
+</Step>
+
+<Step title="Save Your Credentials">
+    On the same OAuth2 page, you'll find:
+
+    - **Client ID**: A numeric string like `12345`
+    - **Client Secret**: Click "Reset Secret" to generate one
+
+    <Tip>
+    Store these credentials securely. Never commit them to version control. Use environment variables or a secrets manager in production.
+    </Tip>
+</Step>
+</Steps>
+
+### Step 2: FastMCP Configuration
+
+Create your FastMCP server using the `DiscordProvider`, which handles Discord's OAuth flow automatically:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.discord import DiscordProvider
+
+auth_provider = DiscordProvider(
+    client_id="12345",      # Your Discord Application Client ID
+    client_secret="your-client-secret",    # Your Discord OAuth Client Secret
+    base_url="http://localhost:8000",      # Must match your OAuth configuration
+)
+
+mcp = FastMCP(name="Discord Secured App", auth=auth_provider)
+
+@mcp.tool
+async def get_user_info() -> dict:
+    """Returns information about the authenticated Discord user."""
+    from fastmcp.server.dependencies import get_access_token
+
+    token = get_access_token()
+    return {
+        "discord_id": token.claims.get("sub"),
+        "username": token.claims.get("username"),
+        "avatar": token.claims.get("avatar"),
+    }
+```
+
+## Testing
+
+### Running the Server
+
+Start your FastMCP server with HTTP transport to enable OAuth flows:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Your server is now running and protected by Discord OAuth authentication.
+
+### Testing with a Client
+
+Create a test client that authenticates with your Discord-protected server:
+
+```python test_client.py
+from fastmcp import Client
+import asyncio
+
+async def main():
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        print("✓ Authenticated with Discord!")
+
+        result = await client.call_tool("get_user_info")
+        print(f"Discord user: {result['username']}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+1. Your browser will open to Discord's authorization page
+2. Sign in with your Discord account and authorize the app
+3. After authorization, you'll be redirected back
+4. The client receives the token and can make authenticated requests
+
+<Info>
+The client caches tokens locally, so you won't need to re-authenticate for subsequent runs unless the token expires or you explicitly clear the cache.
+</Info>
+
+## Discord Scopes
+
+Discord OAuth supports several scopes for accessing different types of user data:
+
+| Scope | Description |
+|-------|-------------|
+| `identify` | Access username, avatar, and discriminator (default) |
+| `email` | Access the user's email address |
+| `guilds` | Access the user's list of servers |
+| `guilds.join` | Ability to add the user to a server |
+
+To request additional scopes:
+
+```python
+auth_provider = DiscordProvider(
+    client_id="...",
+    client_secret="...",
+    base_url="http://localhost:8000",
+    required_scopes=["identify", "email"],
+)
+```
+
+## Production Configuration
+
+For production deployments with persistent token management across server restarts, configure `jwt_signing_key` and `client_storage`:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.discord import DiscordProvider
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+auth_provider = DiscordProvider(
+    client_id="12345",
+    client_secret=os.environ["DISCORD_CLIENT_SECRET"],
+    base_url="https://your-production-domain.com",
+
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(
+            host=os.environ["REDIS_HOST"],
+            port=int(os.environ["REDIS_PORT"])
+        ),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+
+mcp = FastMCP(name="Production Discord App", auth=auth_provider)
+```
+
+<Note>
+Parameters (`jwt_signing_key` and `client_storage`) work together to ensure tokens and client registrations survive server restarts. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without it, tokens are stored in plaintext. Store secrets in environment variables and use a persistent storage backend like Redis for distributed deployments.
+
+For complete details on these parameters, see the [OAuth Proxy documentation](/v2/servers/auth/oauth-proxy#configuration-parameters).
+</Note>
+
+## Environment Variables
+
+For production deployments, use environment variables instead of hardcoding credentials.
+
+### Provider Selection
+
+Setting this environment variable allows the Discord provider to be used automatically without explicitly instantiating it in code.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH" default="Not set">
+Set to `fastmcp.server.auth.providers.discord.DiscordProvider` to use Discord authentication.
+</ParamField>
+</Card>
+
+### Discord-Specific Configuration
+
+These environment variables provide default values for the Discord provider, whether it's instantiated manually or configured via `FASTMCP_SERVER_AUTH`.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH_DISCORD_CLIENT_ID" required>
+Your Discord Application Client ID (e.g., `12345`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_DISCORD_CLIENT_SECRET" required>
+Your Discord OAuth Client Secret
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_DISCORD_BASE_URL" default="http://localhost:8000">
+Public URL where OAuth endpoints will be accessible (includes any mount path)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_DISCORD_ISSUER_URL" default="Uses BASE_URL">
+Issuer URL for OAuth metadata (defaults to `BASE_URL`). Set to root-level URL when mounting under a path prefix to avoid 404 logs. See [HTTP Deployment guide](/v2/deployment/http#mounting-authenticated-servers) for details.
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_DISCORD_REDIRECT_PATH" default="/auth/callback">
+Redirect path configured in your Discord OAuth settings
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_DISCORD_REQUIRED_SCOPES" default='["identify"]'>
+Comma-, space-, or JSON-separated list of required Discord scopes (e.g., `identify,email` or `["identify","email"]`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_DISCORD_TIMEOUT_SECONDS" default="10">
+HTTP request timeout for Discord API calls
+</ParamField>
+</Card>
+
+Example `.env` file:
+```bash
+FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.discord.DiscordProvider
+
+FASTMCP_SERVER_AUTH_DISCORD_CLIENT_ID=12345
+FASTMCP_SERVER_AUTH_DISCORD_CLIENT_SECRET=your-client-secret
+FASTMCP_SERVER_AUTH_DISCORD_BASE_URL=https://your-server.com
+FASTMCP_SERVER_AUTH_DISCORD_REQUIRED_SCOPES=identify,email
+```
+
+With environment variables set, your server code simplifies to:
+
+```python server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Discord Secured App")
+
+@mcp.tool
+async def protected_tool(query: str) -> str:
+    """A tool that requires Discord authentication to access."""
+    return f"Processing authenticated request: {query}"
+```
diff --git a/docs/v2/integrations/eunomia-authorization.mdx b/docs/v2/integrations/eunomia-authorization.mdx
new file mode 100644
index 0000000..2fd2ca4
--- /dev/null
+++ b/docs/v2/integrations/eunomia-authorization.mdx
@@ -0,0 +1,129 @@
+---
+title: Eunomia Authorization 🤝 FastMCP
+sidebarTitle: Eunomia Auth
+description: Add policy-based authorization to your FastMCP servers with Eunomia
+icon: shield-check
+---
+
+Add **policy-based authorization** to your FastMCP servers with one-line code addition with the **[Eunomia][eunomia-github] authorization middleware**.
+
+Control which tools, resources and prompts MCP clients can view and execute on your server. Define dynamic JSON-based policies and obtain a comprehensive audit log of all access attempts and violations.
+
+## How it Works
+
+Exploiting FastMCP's [Middleware][fastmcp-middleware], the Eunomia middleware intercepts all MCP requests to your server and automatically maps MCP methods to authorization checks.
+
+### Listing Operations
+
+The middleware behaves as a filter for listing operations (`tools/list`, `resources/list`, `prompts/list`), hiding to the client components that are not authorized by the defined policies.
+
+```mermaid
+sequenceDiagram
+    participant MCPClient as MCP Client
+    participant EunomiaMiddleware as Eunomia Middleware
+    participant MCPServer as FastMCP Server
+    participant EunomiaServer as Eunomia Server
+
+    MCPClient->>EunomiaMiddleware: MCP Listing Request (e.g., tools/list)
+    EunomiaMiddleware->>MCPServer: MCP Listing Request
+    MCPServer-->>EunomiaMiddleware: MCP Listing Response
+    EunomiaMiddleware->>EunomiaServer: Authorization Checks
+    EunomiaServer->>EunomiaMiddleware: Authorization Decisions
+    EunomiaMiddleware-->>MCPClient: Filtered MCP Listing Response
+```
+
+### Execution Operations
+
+The middleware behaves as a firewall for execution operations (`tools/call`, `resources/read`, `prompts/get`), blocking operations that are not authorized by the defined policies.
+
+```mermaid
+sequenceDiagram
+    participant MCPClient as MCP Client
+    participant EunomiaMiddleware as Eunomia Middleware
+    participant MCPServer as FastMCP Server
+    participant EunomiaServer as Eunomia Server
+
+    MCPClient->>EunomiaMiddleware: MCP Execution Request (e.g., tools/call)
+    EunomiaMiddleware->>EunomiaServer: Authorization Check
+    EunomiaServer->>EunomiaMiddleware: Authorization Decision
+    EunomiaMiddleware-->>MCPClient: MCP Unauthorized Error (if denied)
+    EunomiaMiddleware->>MCPServer: MCP Execution Request (if allowed)
+    MCPServer-->>EunomiaMiddleware: MCP Execution Response (if allowed)
+    EunomiaMiddleware-->>MCPClient: MCP Execution Response (if allowed)
+```
+
+## Add Authorization to Your Server
+
+<Note>
+Eunomia is an AI-specific authorization server that handles policy decisions. The server runs embedded within your MCP server by default for a zero-effort configuration, but can alternatively be run remotely for centralized policy decisions.
+
+</Note>
+
+### Create a Server with Authorization
+
+First, install the `eunomia-mcp` package:
+
+```bash
+pip install eunomia-mcp
+```
+
+Then create a FastMCP server and add the Eunomia middleware in one line:
+
+```python server.py
+from fastmcp import FastMCP
+from eunomia_mcp import create_eunomia_middleware
+
+# Create your FastMCP server
+mcp = FastMCP("Secure MCP Server 🔒")
+
+@mcp.tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+# Add middleware to your server
+middleware = create_eunomia_middleware(policy_file="mcp_policies.json")
+mcp.add_middleware(middleware)
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+### Configure Access Policies
+
+Use the `eunomia-mcp` CLI in your terminal to manage your authorization policies:
+
+```bash
+# Create a default policy file
+eunomia-mcp init
+
+# Or create a policy file customized for your FastMCP server
+eunomia-mcp init --custom-mcp "app.server:mcp"
+```
+
+This creates `mcp_policies.json` file that you can further edit to your access control needs.
+
+```bash
+# Once edited, validate your policy file
+eunomia-mcp validate mcp_policies.json
+```
+
+### Run the Server
+
+Start your FastMCP server normally:
+
+```bash
+python server.py
+```
+
+The middleware will now intercept all MCP requests and check them against your policies. Requests include agent identification through headers like `X-Agent-ID`, `X-User-ID`, `User-Agent`, or `Authorization` and an automatic mapping of MCP methods to authorization resources and actions.
+
+<Tip>
+  For detailed policy configuration, custom authentication, and remote
+  deployments, visit the [Eunomia MCP Middleware
+  repository][eunomia-mcp-github].
+</Tip>
+
+[eunomia-github]: https://github.com/whataboutyou-ai/eunomia
+[eunomia-mcp-github]: https://github.com/whataboutyou-ai/eunomia/tree/main/pkgs/extensions/mcp
+[fastmcp-middleware]: /servers/middleware
diff --git a/docs/v2/integrations/fastapi.mdx b/docs/v2/integrations/fastapi.mdx
new file mode 100644
index 0000000..67d5d06
--- /dev/null
+++ b/docs/v2/integrations/fastapi.mdx
@@ -0,0 +1,451 @@
+---
+title: FastAPI 🤝 FastMCP
+sidebarTitle: FastAPI
+description: Integrate FastMCP with FastAPI applications
+icon: bolt
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+FastMCP provides two powerful ways to integrate with FastAPI applications:
+
+1. **[Generate an MCP server FROM your FastAPI app](#generating-an-mcp-server)** - Convert existing API endpoints into MCP tools
+2. **[Mount an MCP server INTO your FastAPI app](#mounting-an-mcp-server)** - Add MCP functionality to your web application
+
+
+<Tip>
+Generating MCP servers from OpenAPI is a great way to get started with FastMCP, but in practice LLMs achieve **significantly better performance** with well-designed and curated MCP servers than with auto-converted OpenAPI servers. This is especially true for complex APIs with many endpoints and parameters.
+
+We recommend using the FastAPI integration for bootstrapping and prototyping, not for mirroring your API to LLM clients. See the post [Stop Converting Your REST APIs to MCP](https://www.jlowin.dev/blog/stop-converting-rest-apis-to-mcp) for more details.
+</Tip>
+
+
+<Note>
+FastMCP does *not* include FastAPI as a dependency; you must install it separately to use this integration.
+</Note>
+
+## Example FastAPI Application
+
+Throughout this guide, we'll use this e-commerce API as our example (click the `Copy` button to copy it for use with other code blocks):
+
+```python [expandable]
+# Copy this FastAPI server into other code blocks in this guide
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+
+# Models
+class Product(BaseModel):
+    name: str
+    price: float
+    category: str
+    description: str | None = None
+
+class ProductResponse(BaseModel):
+    id: int
+    name: str
+    price: float
+    category: str
+    description: str | None = None
+
+# Create FastAPI app
+app = FastAPI(title="E-commerce API", version="1.0.0")
+
+# In-memory database
+products_db = {
+    1: ProductResponse(
+        id=1, name="Laptop", price=999.99, category="Electronics"
+    ),
+    2: ProductResponse(
+        id=2, name="Mouse", price=29.99, category="Electronics"
+    ),
+    3: ProductResponse(
+        id=3, name="Desk Chair", price=299.99, category="Furniture"
+    ),
+}
+next_id = 4
+
+@app.get("/products", response_model=list[ProductResponse])
+def list_products(
+    category: str | None = None,
+    max_price: float | None = None,
+) -> list[ProductResponse]:
+    """List all products with optional filtering."""
+    products = list(products_db.values())
+    if category:
+        products = [p for p in products if p.category == category]
+    if max_price:
+        products = [p for p in products if p.price <= max_price]
+    return products
+
+@app.get("/products/{product_id}", response_model=ProductResponse)
+def get_product(product_id: int):
+    """Get a specific product by ID."""
+    if product_id not in products_db:
+        raise HTTPException(status_code=404, detail="Product not found")
+    return products_db[product_id]
+
+@app.post("/products", response_model=ProductResponse)
+def create_product(product: Product):
+    """Create a new product."""
+    global next_id
+    product_response = ProductResponse(id=next_id, **product.model_dump())
+    products_db[next_id] = product_response
+    next_id += 1
+    return product_response
+
+@app.put("/products/{product_id}", response_model=ProductResponse)
+def update_product(product_id: int, product: Product):
+    """Update an existing product."""
+    if product_id not in products_db:
+        raise HTTPException(status_code=404, detail="Product not found")
+    products_db[product_id] = ProductResponse(
+        id=product_id,
+        **product.model_dump(),
+    )
+    return products_db[product_id]
+
+@app.delete("/products/{product_id}")
+def delete_product(product_id: int):
+    """Delete a product."""
+    if product_id not in products_db:
+        raise HTTPException(status_code=404, detail="Product not found")
+    del products_db[product_id]
+    return {"message": "Product deleted"}
+```
+
+<Tip>
+All subsequent code examples in this guide assume you have the above FastAPI application code already defined. Each example builds upon this base application, `app`.
+</Tip>
+
+## Generating an MCP Server
+
+<VersionBadge version="2.0.0" />
+
+One of the most common ways to bootstrap an MCP server is to generate it from an existing FastAPI application. FastMCP will expose your FastAPI endpoints as MCP components (tools, by default) in order to expose your API to LLM clients.
+
+
+
+### Basic Conversion
+
+Convert the FastAPI app to an MCP server with a single line:
+
+```python {5}
+# Assumes the FastAPI app from above is already defined
+from fastmcp import FastMCP
+
+# Convert to MCP server
+mcp = FastMCP.from_fastapi(app=app)
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+### Adding Components
+
+Your converted MCP server is a full FastMCP instance, meaning you can add new tools, resources, and other components to it just like you would with any other FastMCP instance.
+
+```python {8-11}
+# Assumes the FastAPI app from above is already defined
+from fastmcp import FastMCP
+
+# Convert to MCP server
+mcp = FastMCP.from_fastapi(app=app)
+
+# Add a new tool
+@mcp.tool
+def get_product(product_id: int) -> ProductResponse:
+    """Get a product by ID."""
+    return products_db[product_id]
+
+# Run the MCP server
+if __name__ == "__main__":
+    mcp.run()
+```
+
+
+
+
+
+### Interacting with the MCP Server
+
+Once you've converted your FastAPI app to an MCP server, you can interact with it using the FastMCP client to test functionality before deploying it to an LLM-based application.
+
+```python {3, }
+# Assumes the FastAPI app from above is already defined
+from fastmcp import FastMCP
+from fastmcp.client import Client
+import asyncio
+
+# Convert to MCP server
+mcp = FastMCP.from_fastapi(app=app)
+
+async def demo():
+    async with Client(mcp) as client:
+        # List available tools
+        tools = await client.list_tools()
+        print(f"Available tools: {[t.name for t in tools]}")
+        
+        # Create a product
+        result = await client.call_tool(
+            "create_product_products_post",
+            {
+                "name": "Wireless Keyboard",
+                "price": 79.99,
+                "category": "Electronics",
+                "description": "Bluetooth mechanical keyboard"
+            }
+        )
+        print(f"Created product: {result.data}")
+        
+        # List electronics under $100
+        result = await client.call_tool(
+            "list_products_products_get",
+            {"category": "Electronics", "max_price": 100}
+        )
+        print(f"Affordable electronics: {result.data}")
+
+if __name__ == "__main__":
+    asyncio.run(demo())
+```
+
+### Custom Route Mapping
+
+Because FastMCP's FastAPI integration is based on its [OpenAPI integration](/v2/integrations/openapi), you can customize how endpoints are converted to MCP components in exactly the same way. For example, here we use a `RouteMap` to map all GET requests to MCP resources, and all POST/PUT/DELETE requests to MCP tools:
+
+```python
+# Assumes the FastAPI app from above is already defined
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi import RouteMap, MCPType
+
+# Custom mapping rules
+mcp = FastMCP.from_fastapi(
+    app=app,
+    route_maps=[
+        # GET with path params → ResourceTemplates
+        RouteMap(
+            methods=["GET"], 
+            pattern=r".*\{.*\}.*", 
+            mcp_type=MCPType.RESOURCE_TEMPLATE
+        ),
+        # Other GETs → Resources
+        RouteMap(
+            methods=["GET"], 
+            pattern=r".*", 
+            mcp_type=MCPType.RESOURCE
+        ),
+        # POST/PUT/DELETE → Tools (default)
+    ],
+)
+
+# Now:
+# - GET /products → Resource
+# - GET /products/{id} → ResourceTemplate
+# - POST/PUT/DELETE → Tools
+```
+
+<Tip>
+To learn more about customizing the conversion process, see the [OpenAPI Integration guide](/v2/integrations/openapi).
+</Tip>
+
+### Authentication and Headers
+
+You can configure headers and other client options via the `httpx_client_kwargs` parameter. For example, to add authentication to your FastAPI app, you can pass a `headers` dictionary to the `httpx_client_kwargs` parameter:
+
+```python {27-31}
+# Assumes the FastAPI app from above is already defined
+from fastmcp import FastMCP
+
+# Add authentication to your FastAPI app
+from fastapi import Depends, Header
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+
+security = HTTPBearer()
+
+def verify_token(credentials: HTTPAuthorizationCredentials = Depends(security)):
+    if credentials.credentials != "secret-token":
+        raise HTTPException(status_code=401, detail="Invalid authentication")
+    return credentials.credentials
+
+# Add a protected endpoint
+@app.get("/admin/stats", dependencies=[Depends(verify_token)])
+def get_admin_stats():
+    return {
+        "total_products": len(products_db),
+        "categories": list(set(p.category for p in products_db.values()))
+    }
+
+# Create MCP server with authentication headers
+mcp = FastMCP.from_fastapi(
+    app=app,
+    httpx_client_kwargs={
+        "headers": {
+            "Authorization": "Bearer secret-token",
+        }
+    }
+)
+```
+
+## Mounting an MCP Server
+
+<VersionBadge version="2.3.1" />
+
+In addition to generating servers, FastMCP can facilitate adding MCP servers to your existing FastAPI application. You can do this by mounting the MCP ASGI application.
+
+### Basic Mounting
+
+To mount an MCP server, you can use the `http_app` method on your FastMCP instance. This will return an ASGI application that can be mounted to your FastAPI application.
+
+```python {23-30}
+from fastmcp import FastMCP
+from fastapi import FastAPI
+
+# Create MCP server
+mcp = FastMCP("Analytics Tools")
+
+@mcp.tool
+def analyze_pricing(category: str) -> dict:
+    """Analyze pricing for a category."""
+    products = [p for p in products_db.values() if p.category == category]
+    if not products:
+        return {"error": f"No products in {category}"}
+    
+    prices = [p.price for p in products]
+    return {
+        "category": category,
+        "avg_price": round(sum(prices) / len(prices), 2),
+        "min": min(prices),
+        "max": max(prices),
+    }
+
+# Create ASGI app from MCP server
+mcp_app = mcp.http_app(path='/mcp')
+
+# Key: Pass lifespan to FastAPI
+app = FastAPI(title="E-commerce API", lifespan=mcp_app.lifespan)
+
+# Mount the MCP server
+app.mount("/analytics", mcp_app)
+
+# Now: API at /products/*, MCP at /analytics/mcp/
+```
+
+## Offering an LLM-Friendly API
+
+A common pattern is to generate an MCP server from your FastAPI app and serve both interfaces from the same application. This provides an LLM-optimized interface alongside your regular API:
+
+```python
+# Assumes the FastAPI app from above is already defined
+from fastmcp import FastMCP
+from fastapi import FastAPI
+
+# 1. Generate MCP server from your API
+mcp = FastMCP.from_fastapi(app=app, name="E-commerce MCP")
+
+# 2. Create the MCP's ASGI app
+mcp_app = mcp.http_app(path='/mcp')
+
+# 3. Create a new FastAPI app that combines both sets of routes
+combined_app = FastAPI(
+    title="E-commerce API with MCP",
+    routes=[
+        *mcp_app.routes,  # MCP routes
+        *app.routes,      # Original API routes
+    ],
+    lifespan=mcp_app.lifespan,
+)
+
+# Now you have:
+# - Regular API: http://localhost:8000/products
+# - LLM-friendly MCP: http://localhost:8000/mcp
+# Both served from the same FastAPI application!
+```
+
+This approach lets you maintain a single codebase while offering both traditional REST endpoints and MCP-compatible endpoints for LLM clients.
+
+## Key Considerations
+
+### Operation IDs
+
+FastAPI operation IDs become MCP component names. Always specify meaningful operation IDs:
+
+```python
+# Good - explicit operation_id
+@app.get("/users/{user_id}", operation_id="get_user_by_id")
+def get_user(user_id: int):
+    return {"id": user_id}
+
+# Less ideal - auto-generated name
+@app.get("/users/{user_id}")
+def get_user(user_id: int):
+    return {"id": user_id}
+```
+
+### Lifespan Management
+
+When mounting MCP servers, always pass the lifespan context:
+
+```python
+# Correct - lifespan passed
+mcp_app = mcp.http_app(path='/mcp')
+app = FastAPI(lifespan=mcp_app.lifespan)
+app.mount("/mcp", mcp_app)
+
+# Incorrect - missing lifespan
+app = FastAPI()
+app.mount("/mcp", mcp.http_app())  # Session manager won't initialize
+```
+
+If you're mounting an authenticated MCP server under a path prefix, see [Mounting Authenticated Servers](/v2/deployment/http#mounting-authenticated-servers) for important OAuth routing considerations.
+
+### CORS Middleware
+
+If your FastAPI app uses `CORSMiddleware` and you're mounting an OAuth-protected FastMCP server, avoid adding application-wide CORS middleware. FastMCP and the MCP SDK already handle CORS for OAuth routes, and layering CORS middleware can cause conflicts (such as 404 errors on `.well-known` routes or OPTIONS requests).
+
+If you need CORS on your own FastAPI routes, use the sub-app pattern: mount your API and FastMCP as separate apps, each with their own middleware, rather than adding top-level `CORSMiddleware` to the combined application.
+
+### Combining Lifespans
+
+If your FastAPI app already has a lifespan (for database connections, startup tasks, etc.), you can't simply replace it with the MCP lifespan. Instead, you need to create a new lifespan function that manages both contexts. This ensures that both your app's initialization logic and the MCP server's session manager run properly:
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastmcp import FastMCP
+
+# Your existing lifespan
+@asynccontextmanager
+async def app_lifespan(app: FastAPI):
+    # Startup
+    print("Starting up the app...")
+    # Initialize database, cache, etc.
+    yield
+    # Shutdown
+    print("Shutting down the app...")
+
+# Create MCP server
+mcp = FastMCP("Tools")
+mcp_app = mcp.http_app(path='/mcp')
+
+# Combine both lifespans
+@asynccontextmanager
+async def combined_lifespan(app: FastAPI):
+    # Run both lifespans
+    async with app_lifespan(app):
+        async with mcp_app.lifespan(app):
+            yield
+
+# Use the combined lifespan
+app = FastAPI(lifespan=combined_lifespan)
+app.mount("/mcp", mcp_app)
+```
+
+This pattern ensures both your app's initialization logic and the MCP server's session manager are properly managed. The key is using nested `async with` statements - the inner context (MCP) will be initialized after the outer context (your app), and cleaned up before it. This maintains the correct initialization and cleanup order for all your resources.
+
+### Performance Tips
+
+1. **Use in-memory transport for testing** - Pass MCP servers directly to clients
+2. **Design purpose-built MCP tools** - Better than auto-converting complex APIs
+3. **Keep tool parameters simple** - LLMs perform better with focused interfaces
+
+For more details on configuration options, see the [OpenAPI Integration guide](/v2/integrations/openapi).
\ No newline at end of file
diff --git a/docs/v2/integrations/gemini-cli.mdx b/docs/v2/integrations/gemini-cli.mdx
new file mode 100644
index 0000000..af63a5d
--- /dev/null
+++ b/docs/v2/integrations/gemini-cli.mdx
@@ -0,0 +1,174 @@
+---
+title: Gemini CLI 🤝 FastMCP
+sidebarTitle: Gemini CLI
+description: Install and use FastMCP servers in Gemini CLI
+icon: message-smile
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+import { LocalFocusTip } from "/snippets/local-focus.mdx"
+
+<LocalFocusTip />
+
+Gemini CLI supports MCP servers through multiple transport methods including STDIO, SSE, and HTTP, allowing you to extend Gemini's capabilities with custom tools, resources, and prompts from your FastMCP servers.
+
+## Requirements
+
+This integration uses STDIO transport to run your FastMCP server locally. For remote deployments, you can run your FastMCP server with HTTP or SSE transport and configure it directly using Gemini CLI's built-in MCP management commands.
+
+## Create a Server
+
+The examples in this guide will use the following simple dice-rolling server, saved as `server.py`.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Install the Server
+
+### FastMCP CLI
+<VersionBadge version="2.13.0" />
+
+The easiest way to install a FastMCP server in Gemini CLI is using the `fastmcp install gemini-cli` command. This automatically handles the configuration, dependency management, and calls Gemini CLI's built-in MCP management system.
+
+```bash
+fastmcp install gemini-cli server.py
+```
+
+The install command supports the same `file.py:object` notation as the `run` command. If no object is specified, it will automatically look for a FastMCP server object named `mcp`, `server`, or `app` in your file:
+
+```bash
+# These are equivalent if your server object is named 'mcp'
+fastmcp install gemini-cli server.py
+fastmcp install gemini-cli server.py:mcp
+
+# Use explicit object name if your server has a different name
+fastmcp install gemini-cli server.py:my_custom_server
+```
+
+The command will automatically configure the server with Gemini CLI's `gemini mcp add` command.
+
+#### Dependencies
+
+FastMCP provides flexible dependency management options for your Gemini CLI servers:
+
+**Individual packages**: Use the `--with` flag to specify packages your server needs. You can use this flag multiple times:
+
+```bash
+fastmcp install gemini-cli server.py --with pandas --with requests
+```
+
+**Requirements file**: If you maintain a `requirements.txt` file with all your dependencies, use `--with-requirements` to install them:
+
+```bash
+fastmcp install gemini-cli server.py --with-requirements requirements.txt
+```
+
+**Editable packages**: For local packages under development, use `--with-editable` to install them in editable mode:
+
+```bash
+fastmcp install gemini-cli server.py --with-editable ./my-local-package
+```
+
+Alternatively, you can use a `fastmcp.json` configuration file (recommended):
+
+```json fastmcp.json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "dependencies": ["pandas", "requests"]
+  }
+}
+```
+
+
+#### Python Version and Project Configuration
+
+Control the Python environment for your server with these options:
+
+**Python version**: Use `--python` to specify which Python version your server requires. This ensures compatibility when your server needs specific Python features:
+
+```bash
+fastmcp install gemini-cli server.py --python 3.11
+```
+
+**Project directory**: Use `--project` to run your server within a specific project context. This tells `uv` to use the project's configuration files and virtual environment:
+
+```bash
+fastmcp install gemini-cli server.py --project /path/to/my-project
+```
+
+#### Environment Variables
+
+If your server needs environment variables (like API keys), you must include them:
+
+```bash
+fastmcp install gemini-cli server.py --server-name "Weather Server" \
+  --env API_KEY=your-api-key \
+  --env DEBUG=true
+```
+
+Or load them from a `.env` file:
+
+```bash
+fastmcp install gemini-cli server.py --server-name "Weather Server" --env-file .env
+```
+
+<Warning>
+**Gemini CLI must be installed**. The integration looks for the Gemini CLI and uses the `gemini mcp add` command to register servers.
+</Warning>
+
+### Manual Configuration
+
+For more control over the configuration, you can manually use Gemini CLI's built-in MCP management commands. This gives you direct control over how your server is launched:
+
+```bash
+# Add a server with custom configuration
+gemini mcp add dice-roller uv -- run --with fastmcp fastmcp run server.py
+
+# Add with environment variables
+gemini mcp add weather-server -e API_KEY=secret -e DEBUG=true uv -- run --with fastmcp fastmcp run server.py
+
+# Add with specific scope (user, or project)
+gemini mcp add my-server --scope user uv -- run --with fastmcp fastmcp run server.py
+```
+
+You can also manually specify Python versions and project directories in your Gemini CLI commands:
+
+```bash
+# With specific Python version
+gemini mcp add ml-server uv -- run --python 3.11 --with fastmcp fastmcp run server.py
+
+# Within a project directory
+gemini mcp add project-server uv -- run --project /path/to/project --with fastmcp fastmcp run server.py
+```
+
+## Using the Server
+
+Once your server is installed, you can start using your FastMCP server with Gemini CLI.
+
+Try asking Gemini something like:
+
+> "Roll some dice for me"
+
+Gemini will automatically detect your `roll_dice` tool and use it to fulfill your request.
+
+Gemini CLI can now access all the tools and prompts you've defined in your FastMCP server. 
+
+If your server provides prompts, you can use them as slash commands with `/prompt_name`.
diff --git a/docs/v2/integrations/gemini.mdx b/docs/v2/integrations/gemini.mdx
new file mode 100644
index 0000000..901e7f8
--- /dev/null
+++ b/docs/v2/integrations/gemini.mdx
@@ -0,0 +1,108 @@
+---
+title: Gemini SDK 🤝 FastMCP
+sidebarTitle: Gemini SDK
+description: Connect FastMCP servers to the Google Gemini SDK
+icon: message-code
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+Google's Gemini API includes built-in support for MCP servers in their Python and JavaScript SDKs, allowing you to connect directly to MCP servers and use their tools seamlessly with Gemini models.
+
+## Gemini Python SDK
+
+Google's [Gemini Python SDK](https://ai.google.dev/gemini-api/docs) can use FastMCP clients directly.
+
+<Note>
+Google's MCP integration is currently experimental and available in the Python and JavaScript SDKs. The API automatically calls MCP tools when needed and can connect to both local and remote MCP servers.
+</Note>
+
+<Tip>
+Currently, Gemini's MCP support only accesses **tools** from MCP servers—it queries the `list_tools` endpoint and exposes those functions to the AI. Other MCP features like resources and prompts are not currently supported.
+</Tip>
+
+### Create a Server
+
+First, create a FastMCP server with the tools you want to expose. For this example, we'll create a server with a single tool that rolls dice.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+### Call the Server
+
+
+To use the Gemini API with MCP, you'll need to install the Google Generative AI SDK:
+
+```bash
+pip install google-genai
+```
+
+You'll also need to authenticate with Google. You can do this by setting the `GEMINI_API_KEY` environment variable. Consult the Gemini SDK documentation for more information.
+
+```bash
+export GEMINI_API_KEY="your-api-key"
+```
+
+Gemini's SDK interacts directly with the MCP client session. To call the server, you'll need to instantiate a FastMCP client, enter its connection context, and pass the client session to the Gemini SDK.
+
+```python {5, 9, 15}
+from fastmcp import Client
+from google import genai
+import asyncio
+
+mcp_client = Client("server.py")
+gemini_client = genai.Client()
+
+async def main():    
+    async with mcp_client:
+        response = await gemini_client.aio.models.generate_content(
+            model="gemini-2.0-flash",
+            contents="Roll 3 dice!",
+            config=genai.types.GenerateContentConfig(
+                temperature=0,
+                tools=[mcp_client.session],  # Pass the FastMCP client session
+            ),
+        )
+        print(response.text)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+If you run this code, you'll see output like:
+
+```text
+Okay, I rolled 3 dice and got a 5, 4, and 1.
+```
+
+### Remote & Authenticated Servers
+
+In the above example, we connected to our local server using `stdio` transport. Because we're using a FastMCP client, you can also connect to any local or remote MCP server, using any [transport](/v2/clients/transports) or [auth](/v2/clients/auth/oauth) method supported by FastMCP, simply by changing the client configuration.
+
+For example, to connect to a remote, authenticated server, you can use the following client:
+
+```python
+from fastmcp import Client
+from fastmcp.client.auth import BearerAuth
+
+mcp_client = Client(
+    "https://my-server.com/mcp/",
+    auth=BearerAuth("<your-token>"),
+)
+```
+
+The rest of the code remains the same.
+
+
diff --git a/docs/v2/integrations/github.mdx b/docs/v2/integrations/github.mdx
new file mode 100644
index 0000000..5c92006
--- /dev/null
+++ b/docs/v2/integrations/github.mdx
@@ -0,0 +1,253 @@
+---
+title: GitHub OAuth 🤝 FastMCP
+sidebarTitle: GitHub
+description: Secure your FastMCP server with GitHub OAuth
+icon: github
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.12.0" />
+
+This guide shows you how to secure your FastMCP server using **GitHub OAuth**. Since GitHub doesn't support Dynamic Client Registration, this integration uses the [**OAuth Proxy**](/v2/servers/auth/oauth-proxy) pattern to bridge GitHub's traditional OAuth with MCP's authentication requirements.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+1. A **[GitHub Account](https://github.com/)** with access to create OAuth Apps
+2. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`)
+
+### Step 1: Create a GitHub OAuth App
+
+Create an OAuth App in your GitHub settings to get the credentials needed for authentication:
+
+<Steps>
+<Step title="Navigate to OAuth Apps">
+    Go to **Settings → Developer settings → OAuth Apps** in your GitHub account, or visit [github.com/settings/developers](https://github.com/settings/developers).
+    
+    Click **"New OAuth App"** to create a new application.
+</Step>
+
+<Step title="Configure Your OAuth App">
+    Fill in the application details:
+    
+    - **Application name**: Choose a name users will recognize (e.g., "My FastMCP Server")
+    - **Homepage URL**: Your application's homepage or documentation URL
+    - **Authorization callback URL**: Your server URL + `/auth/callback` (e.g., `http://localhost:8000/auth/callback`)
+    
+    <Warning>
+    The callback URL must match exactly. The default path is `/auth/callback`, but you can customize it using the `redirect_path` parameter. For local development, GitHub allows `http://localhost` URLs. For production, you must use HTTPS.
+    </Warning>
+    
+    <Tip>
+    If you want to use a custom callback path (e.g., `/auth/github/callback`), make sure to set the same path in both your GitHub OAuth App settings and the `redirect_path` parameter when configuring the GitHubProvider.
+    </Tip>
+</Step>
+
+<Step title="Save Your Credentials">
+    After creating the app, you'll see:
+    
+    - **Client ID**: A public identifier like `Ov23liAbcDefGhiJkLmN`
+    - **Client Secret**: Click "Generate a new client secret" and save the value securely
+    
+    <Tip>
+    Store these credentials securely. Never commit them to version control. Use environment variables or a secrets manager in production.
+    </Tip>
+</Step>
+</Steps>
+
+### Step 2: FastMCP Configuration
+
+Create your FastMCP server using the `GitHubProvider`, which handles GitHub's OAuth quirks automatically:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.github import GitHubProvider
+
+# The GitHubProvider handles GitHub's token format and validation
+auth_provider = GitHubProvider(
+    client_id="Ov23liAbcDefGhiJkLmN",  # Your GitHub OAuth App Client ID
+    client_secret="github_pat_...",     # Your GitHub OAuth App Client Secret
+    base_url="http://localhost:8000",   # Must match your OAuth App configuration
+    # redirect_path="/auth/callback"   # Default value, customize if needed
+)
+
+mcp = FastMCP(name="GitHub Secured App", auth=auth_provider)
+
+# Add a protected tool to test authentication
+@mcp.tool
+async def get_user_info() -> dict:
+    """Returns information about the authenticated GitHub user."""
+    from fastmcp.server.dependencies import get_access_token
+    
+    token = get_access_token()
+    # The GitHubProvider stores user data in token claims
+    return {
+        "github_user": token.claims.get("login"),
+        "name": token.claims.get("name"),
+        "email": token.claims.get("email")
+    }
+```
+
+## Testing
+
+### Running the Server
+
+Start your FastMCP server with HTTP transport to enable OAuth flows:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Your server is now running and protected by GitHub OAuth authentication.
+
+### Testing with a Client
+
+Create a test client that authenticates with your GitHub-protected server:
+
+```python test_client.py
+from fastmcp import Client
+import asyncio
+
+async def main():
+    # The client will automatically handle GitHub OAuth
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        # First-time connection will open GitHub login in your browser
+        print("✓ Authenticated with GitHub!")
+        
+        # Test the protected tool
+        result = await client.call_tool("get_user_info")
+        print(f"GitHub user: {result['github_user']}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+1. Your browser will open to GitHub's authorization page
+2. After you authorize the app, you'll be redirected back
+3. The client receives the token and can make authenticated requests
+
+<Info>
+The client caches tokens locally, so you won't need to re-authenticate for subsequent runs unless the token expires or you explicitly clear the cache.
+</Info>
+
+## Production Configuration
+
+<VersionBadge version="2.13.0" />
+
+For production deployments with persistent token management across server restarts, configure `jwt_signing_key` and `client_storage`:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.github import GitHubProvider
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+# Production setup with encrypted persistent token storage
+auth_provider = GitHubProvider(
+    client_id="Ov23liAbcDefGhiJkLmN",
+    client_secret="github_pat_...",
+    base_url="https://your-production-domain.com",
+
+    # Production token management
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(
+            host=os.environ["REDIS_HOST"],
+            port=int(os.environ["REDIS_PORT"])
+        ),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+
+mcp = FastMCP(name="Production GitHub App", auth=auth_provider)
+```
+
+<Note>
+Parameters (`jwt_signing_key` and `client_storage`) work together to ensure tokens and client registrations survive server restarts. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without it, tokens are stored in plaintext. Store secrets in environment variables and use a persistent storage backend like Redis for distributed deployments.
+
+For complete details on these parameters, see the [OAuth Proxy documentation](/v2/servers/auth/oauth-proxy#configuration-parameters).
+</Note>
+
+## Environment Variables
+
+<VersionBadge version="2.12.1" />
+
+For production deployments, use environment variables instead of hardcoding credentials.
+
+### Provider Selection
+
+Setting this environment variable allows the GitHub provider to be used automatically without explicitly instantiating it in code.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH" default="Not set">
+Set to `fastmcp.server.auth.providers.github.GitHubProvider` to use GitHub authentication.
+</ParamField>
+</Card>
+
+### GitHub-Specific Configuration
+
+These environment variables provide default values for the GitHub provider, whether it's instantiated manually or configured via `FASTMCP_SERVER_AUTH`.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID" required>
+Your GitHub OAuth App Client ID (e.g., `Ov23liAbcDefGhiJkLmN`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET" required>
+Your GitHub OAuth App Client Secret
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_GITHUB_BASE_URL" default="http://localhost:8000">
+Public URL where OAuth endpoints will be accessible (includes any mount path)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_GITHUB_ISSUER_URL" default="Uses BASE_URL">
+Issuer URL for OAuth metadata (defaults to `BASE_URL`). Set to root-level URL when mounting under a path prefix to avoid 404 logs. See [HTTP Deployment guide](/v2/deployment/http#mounting-authenticated-servers) for details.
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_GITHUB_REDIRECT_PATH" default="/auth/callback">
+Redirect path configured in your GitHub OAuth App
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_GITHUB_REQUIRED_SCOPES" default='["user"]'>
+Comma-, space-, or JSON-separated list of required GitHub scopes (e.g., `user repo` or `["user","repo"]`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_GITHUB_TIMEOUT_SECONDS" default="10">
+HTTP request timeout for GitHub API calls
+</ParamField>
+</Card>
+
+Example `.env` file:
+```bash
+# Use the GitHub provider
+FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.github.GitHubProvider
+
+# GitHub OAuth credentials
+FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID=Ov23liAbcDefGhiJkLmN
+FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET=github_pat_...
+FASTMCP_SERVER_AUTH_GITHUB_BASE_URL=https://your-server.com
+FASTMCP_SERVER_AUTH_GITHUB_REQUIRED_SCOPES=user,repo
+```
+
+With environment variables set, your server code simplifies to:
+
+```python server.py
+from fastmcp import FastMCP
+
+# Authentication is automatically configured from environment
+mcp = FastMCP(name="GitHub Secured App")
+
+@mcp.tool
+async def list_repos() -> list[str]:
+    """List the authenticated user's repositories."""
+    # Your tool implementation here
+    pass
+```
diff --git a/docs/v2/integrations/google.mdx b/docs/v2/integrations/google.mdx
new file mode 100644
index 0000000..3285765
--- /dev/null
+++ b/docs/v2/integrations/google.mdx
@@ -0,0 +1,267 @@
+---
+title: Google OAuth 🤝 FastMCP
+sidebarTitle: Google
+description: Secure your FastMCP server with Google OAuth
+icon: google
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.12.0" />
+
+This guide shows you how to secure your FastMCP server using **Google OAuth**. Since Google doesn't support Dynamic Client Registration, this integration uses the [**OAuth Proxy**](/v2/servers/auth/oauth-proxy) pattern to bridge Google's traditional OAuth with MCP's authentication requirements.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+1. A **[Google Cloud Account](https://console.cloud.google.com/)** with access to create OAuth 2.0 Client IDs
+2. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`)
+
+### Step 1: Create a Google OAuth 2.0 Client ID
+
+Create an OAuth 2.0 Client ID in your Google Cloud Console to get the credentials needed for authentication:
+
+<Steps>
+<Step title="Navigate to OAuth Consent Screen">
+    Go to the [Google Cloud Console](https://console.cloud.google.com/apis/credentials) and select your project (or create a new one).
+    
+    First, configure the OAuth consent screen by navigating to **APIs & Services → OAuth consent screen**. Choose "External" for testing or "Internal" for G Suite organizations.
+</Step>
+
+<Step title="Create OAuth 2.0 Client ID">
+    Navigate to **APIs & Services → Credentials** and click **"+ CREATE CREDENTIALS"** → **"OAuth client ID"**.
+    
+    Configure your OAuth client:
+    
+    - **Application type**: Web application
+    - **Name**: Choose a descriptive name (e.g., "FastMCP Server")
+    - **Authorized JavaScript origins**: Add your server's base URL (e.g., `http://localhost:8000`)
+    - **Authorized redirect URIs**: Add your server URL + `/auth/callback` (e.g., `http://localhost:8000/auth/callback`)
+    
+    <Warning>
+    The redirect URI must match exactly. The default path is `/auth/callback`, but you can customize it using the `redirect_path` parameter. For local development, Google allows `http://localhost` URLs with various ports. For production, you must use HTTPS.
+    </Warning>
+    
+    <Tip>
+    If you want to use a custom callback path (e.g., `/auth/google/callback`), make sure to set the same path in both your Google OAuth Client settings and the `redirect_path` parameter when configuring the GoogleProvider.
+    </Tip>
+</Step>
+
+<Step title="Save Your Credentials">
+    After creating the client, you'll receive:
+    
+    - **Client ID**: A string ending in `.apps.googleusercontent.com`
+    - **Client Secret**: A string starting with `GOCSPX-`
+    
+    Download the JSON credentials or copy these values securely.
+    
+    <Tip>
+    Store these credentials securely. Never commit them to version control. Use environment variables or a secrets manager in production.
+    </Tip>
+</Step>
+</Steps>
+
+### Step 2: FastMCP Configuration
+
+Create your FastMCP server using the `GoogleProvider`, which handles Google's OAuth flow automatically:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.google import GoogleProvider
+
+# The GoogleProvider handles Google's token format and validation
+auth_provider = GoogleProvider(
+    client_id="123456789.apps.googleusercontent.com",  # Your Google OAuth Client ID
+    client_secret="GOCSPX-abc123...",                  # Your Google OAuth Client Secret
+    base_url="http://localhost:8000",                  # Must match your OAuth configuration
+    required_scopes=[                                  # Request user information
+        "openid",
+        "https://www.googleapis.com/auth/userinfo.email",
+    ],
+    # redirect_path="/auth/callback"                  # Default value, customize if needed
+)
+
+mcp = FastMCP(name="Google Secured App", auth=auth_provider)
+
+# Add a protected tool to test authentication
+@mcp.tool
+async def get_user_info() -> dict:
+    """Returns information about the authenticated Google user."""
+    from fastmcp.server.dependencies import get_access_token
+    
+    token = get_access_token()
+    # The GoogleProvider stores user data in token claims
+    return {
+        "google_id": token.claims.get("sub"),
+        "email": token.claims.get("email"),
+        "name": token.claims.get("name"),
+        "picture": token.claims.get("picture"),
+        "locale": token.claims.get("locale")
+    }
+```
+
+## Testing
+
+### Running the Server
+
+Start your FastMCP server with HTTP transport to enable OAuth flows:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Your server is now running and protected by Google OAuth authentication.
+
+### Testing with a Client
+
+Create a test client that authenticates with your Google-protected server:
+
+```python test_client.py
+from fastmcp import Client
+import asyncio
+
+async def main():
+    # The client will automatically handle Google OAuth
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        # First-time connection will open Google login in your browser
+        print("✓ Authenticated with Google!")
+        
+        # Test the protected tool
+        result = await client.call_tool("get_user_info")
+        print(f"Google user: {result['email']}")
+        print(f"Name: {result['name']}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+1. Your browser will open to Google's authorization page
+2. Sign in with your Google account and grant the requested permissions
+3. After authorization, you'll be redirected back
+4. The client receives the token and can make authenticated requests
+
+<Info>
+The client caches tokens locally, so you won't need to re-authenticate for subsequent runs unless the token expires or you explicitly clear the cache.
+</Info>
+
+## Production Configuration
+
+<VersionBadge version="2.13.0" />
+
+For production deployments with persistent token management across server restarts, configure `jwt_signing_key` and `client_storage`:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.google import GoogleProvider
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+# Production setup with encrypted persistent token storage
+auth_provider = GoogleProvider(
+    client_id="123456789.apps.googleusercontent.com",
+    client_secret="GOCSPX-abc123...",
+    base_url="https://your-production-domain.com",
+    required_scopes=["openid", "https://www.googleapis.com/auth/userinfo.email"],
+
+    # Production token management
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(
+            host=os.environ["REDIS_HOST"],
+            port=int(os.environ["REDIS_PORT"])
+        ),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+
+mcp = FastMCP(name="Production Google App", auth=auth_provider)
+```
+
+<Note>
+Parameters (`jwt_signing_key` and `client_storage`) work together to ensure tokens and client registrations survive server restarts. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without it, tokens are stored in plaintext. Store secrets in environment variables and use a persistent storage backend like Redis for distributed deployments.
+
+For complete details on these parameters, see the [OAuth Proxy documentation](/v2/servers/auth/oauth-proxy#configuration-parameters).
+</Note>
+
+## Environment Variables
+
+<VersionBadge version="2.12.1" />
+
+For production deployments, use environment variables instead of hardcoding credentials.
+
+### Provider Selection
+
+Setting this environment variable allows the Google provider to be used automatically without explicitly instantiating it in code.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH" default="Not set">
+Set to `fastmcp.server.auth.providers.google.GoogleProvider` to use Google authentication.
+</ParamField>
+</Card>
+
+### Google-Specific Configuration
+
+These environment variables provide default values for the Google provider, whether it's instantiated manually or configured via `FASTMCP_SERVER_AUTH`.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID" required>
+Your Google OAuth 2.0 Client ID (e.g., `123456789.apps.googleusercontent.com`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET" required>
+Your Google OAuth 2.0 Client Secret (e.g., `GOCSPX-abc123...`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_GOOGLE_BASE_URL" default="http://localhost:8000">
+Public URL where OAuth endpoints will be accessible (includes any mount path)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_GOOGLE_ISSUER_URL" default="Uses BASE_URL">
+Issuer URL for OAuth metadata (defaults to `BASE_URL`). Set to root-level URL when mounting under a path prefix to avoid 404 logs. See [HTTP Deployment guide](/v2/deployment/http#mounting-authenticated-servers) for details.
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_GOOGLE_REDIRECT_PATH" default="/auth/callback">
+Redirect path configured in your Google OAuth Client
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_GOOGLE_REQUIRED_SCOPES" default="[]">
+Comma-, space-, or JSON-separated list of required Google scopes (e.g., `"openid,https://www.googleapis.com/auth/userinfo.email"` or `["openid", "https://www.googleapis.com/auth/userinfo.email"]`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_GOOGLE_TIMEOUT_SECONDS" default="10">
+HTTP request timeout for Google API calls
+</ParamField>
+</Card>
+
+Example `.env` file:
+```bash
+# Use the Google provider
+FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.google.GoogleProvider
+
+# Google OAuth credentials
+FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID=123456789.apps.googleusercontent.com
+FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET=GOCSPX-abc123...
+FASTMCP_SERVER_AUTH_GOOGLE_BASE_URL=https://your-server.com
+FASTMCP_SERVER_AUTH_GOOGLE_REQUIRED_SCOPES=openid,https://www.googleapis.com/auth/userinfo.email
+```
+
+With environment variables set, your server code simplifies to:
+
+```python server.py
+from fastmcp import FastMCP
+
+# Authentication is automatically configured from environment
+mcp = FastMCP(name="Google Secured App")
+
+@mcp.tool
+async def protected_tool(query: str) -> str:
+    """A tool that requires Google authentication to access."""
+    # Your tool implementation here
+    return f"Processing authenticated request: {query}"
+```
\ No newline at end of file
diff --git a/docs/v2/integrations/images/authkit/enable_dcr.png b/docs/v2/integrations/images/authkit/enable_dcr.png
new file mode 100644
index 0000000..e5942f6
Binary files /dev/null and b/docs/v2/integrations/images/authkit/enable_dcr.png differ
diff --git a/docs/v2/integrations/images/permit/abac_condition_example.png b/docs/v2/integrations/images/permit/abac_condition_example.png
new file mode 100644
index 0000000..a5592ab
Binary files /dev/null and b/docs/v2/integrations/images/permit/abac_condition_example.png differ
diff --git a/docs/v2/integrations/images/permit/abac_policy_example.png b/docs/v2/integrations/images/permit/abac_policy_example.png
new file mode 100644
index 0000000..bd4b5cf
Binary files /dev/null and b/docs/v2/integrations/images/permit/abac_policy_example.png differ
diff --git a/docs/v2/integrations/images/permit/policy_mapping.png b/docs/v2/integrations/images/permit/policy_mapping.png
new file mode 100644
index 0000000..d100b1e
Binary files /dev/null and b/docs/v2/integrations/images/permit/policy_mapping.png differ
diff --git a/docs/v2/integrations/images/permit/role_assignement.png b/docs/v2/integrations/images/permit/role_assignement.png
new file mode 100644
index 0000000..c65e341
Binary files /dev/null and b/docs/v2/integrations/images/permit/role_assignement.png differ
diff --git a/docs/v2/integrations/mcp-json-configuration.mdx b/docs/v2/integrations/mcp-json-configuration.mdx
new file mode 100644
index 0000000..b85bf9e
--- /dev/null
+++ b/docs/v2/integrations/mcp-json-configuration.mdx
@@ -0,0 +1,514 @@
+---
+title: MCP JSON Configuration 🤝 FastMCP
+sidebarTitle: MCP.json
+description: Generate standard MCP configuration files for any compatible client
+icon: brackets-curly
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.10.3" />
+
+FastMCP can generate standard MCP JSON configuration files that work with any MCP-compatible client including Claude Desktop, VS Code, Cursor, and other applications that support the Model Context Protocol.
+
+## MCP JSON Configuration Standard
+
+The MCP JSON configuration format is an **emergent standard** that has developed across the MCP ecosystem. This format defines how MCP clients should configure and launch MCP servers, providing a consistent way to specify server commands, arguments, and environment variables.
+
+### Configuration Structure
+
+The standard uses a `mcpServers` object where each key represents a server name and the value contains the server's configuration:
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "executable",
+      "args": ["arg1", "arg2"],
+      "env": {
+        "VAR": "value"
+      }
+    }
+  }
+}
+```
+
+### Server Configuration Fields
+
+#### `command` (required)
+The executable command to run the MCP server. This should be an absolute path or a command available in the system PATH.
+
+```json
+{
+  "command": "python"
+}
+```
+
+#### `args` (optional)
+An array of command-line arguments passed to the server executable. Arguments are passed in order.
+
+```json
+{
+  "args": ["server.py", "--verbose", "--port", "8080"]
+}
+```
+
+#### `env` (optional)
+An object containing environment variables to set when launching the server. All values must be strings.
+
+```json
+{
+  "env": {
+    "API_KEY": "secret-key",
+    "DEBUG": "true",
+    "PORT": "8080"
+  }
+}
+```
+
+### Client Adoption
+
+This format is widely adopted across the MCP ecosystem:
+
+- **Claude Desktop**: Uses `~/.claude/claude_desktop_config.json`
+- **Cursor**: Uses `~/.cursor/mcp.json`
+- **VS Code**: Uses workspace `.vscode/mcp.json`
+- **Other clients**: Many MCP-compatible applications follow this standard
+
+## Overview
+
+<Note>
+**For the best experience, use FastMCP's first-class integrations:** [`fastmcp install claude-code`](/v2/integrations/claude-code), [`fastmcp install claude-desktop`](/v2/integrations/claude-desktop), or [`fastmcp install cursor`](/v2/integrations/cursor). Use MCP JSON generation for advanced use cases and unsupported clients.
+</Note>
+
+The `fastmcp install mcp-json` command generates configuration in the standard `mcpServers` format used across the MCP ecosystem. This is useful when:
+
+- **Working with unsupported clients** - Any MCP client not directly integrated with FastMCP
+- **CI/CD environments** - Automated configuration generation for deployments  
+- **Configuration sharing** - Easy distribution of server setups to team members
+- **Custom tooling** - Integration with your own MCP management tools
+- **Manual setup** - When you prefer to manually configure your MCP client
+
+## Basic Usage
+
+Generate configuration and output to stdout (useful for piping):
+
+```bash
+fastmcp install mcp-json server.py
+```
+
+This outputs the server configuration JSON with the server name as the root key:
+
+```json
+{
+  "My Server": {
+    "command": "uv",
+    "args": [
+      "run",
+      "--with",
+      "fastmcp", 
+      "fastmcp",
+      "run",
+      "/absolute/path/to/server.py"
+    ]
+  }
+}
+```
+
+To use this in a client configuration file, add it to the `mcpServers` object in your client's configuration:
+
+```json
+{
+  "mcpServers": {
+    "My Server": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--with",
+        "fastmcp", 
+        "fastmcp",
+        "run",
+        "/absolute/path/to/server.py"
+      ]
+    }
+  }
+}
+```
+
+<Note>
+When using `--python`, `--project`, or `--with-requirements`, the generated configuration will include these options in the `uv run` command, ensuring your server runs with the correct Python version and dependencies.
+</Note>
+
+<Note>
+Different MCP clients may have specific configuration requirements or formatting needs. Always consult your client's documentation to ensure proper integration.
+</Note>
+
+## Configuration Options
+
+### Server Naming
+
+```bash
+# Use server's built-in name (from FastMCP constructor)
+fastmcp install mcp-json server.py
+
+# Override with custom name
+fastmcp install mcp-json server.py --name "Custom Server Name"
+```
+
+### Dependencies
+
+Add Python packages your server needs:
+
+```bash
+# Single package
+fastmcp install mcp-json server.py --with pandas
+
+# Multiple packages  
+fastmcp install mcp-json server.py --with pandas --with requests --with httpx
+
+# Editable local package
+fastmcp install mcp-json server.py --with-editable ./my-package
+
+# From requirements file
+fastmcp install mcp-json server.py --with-requirements requirements.txt
+```
+
+You can also use a `fastmcp.json` configuration file (recommended):
+
+```json fastmcp.json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "dependencies": ["pandas", "matplotlib", "seaborn"]
+  }
+}
+```
+
+Then simply install with:
+```bash
+fastmcp install mcp-json fastmcp.json
+```
+
+
+### Environment Variables
+
+```bash
+# Individual environment variables
+fastmcp install mcp-json server.py \
+  --env API_KEY=your-secret-key \
+  --env DEBUG=true
+
+# Load from .env file
+fastmcp install mcp-json server.py --env-file .env
+```
+
+### Python Version and Project Directory
+
+Specify Python version or run within a specific project:
+
+```bash
+# Use specific Python version
+fastmcp install mcp-json server.py --python 3.11
+
+# Run within a project directory
+fastmcp install mcp-json server.py --project /path/to/project
+```
+
+### Server Object Selection
+
+Use the same `file.py:object` notation as other FastMCP commands:
+
+```bash
+# Auto-detects server object (looks for 'mcp', 'server', or 'app')
+fastmcp install mcp-json server.py
+
+# Explicit server object
+fastmcp install mcp-json server.py:my_custom_server
+```
+
+## Clipboard Integration
+
+Copy configuration directly to your clipboard for easy pasting:
+
+```bash
+fastmcp install mcp-json server.py --copy
+```
+
+<Note>
+The `--copy` flag requires the `pyperclip` Python package. If not installed, you'll see an error message with installation instructions.
+</Note>
+
+## Usage Examples
+
+### Basic Server
+
+```bash
+fastmcp install mcp-json dice_server.py
+```
+
+Output:
+```json
+{
+  "Dice Server": {
+    "command": "uv",
+    "args": [
+      "run",
+      "--with",
+      "fastmcp",
+      "fastmcp", 
+      "run",
+      "/home/user/dice_server.py"
+    ]
+  }
+}
+```
+
+### Production Server with Dependencies
+
+```bash
+fastmcp install mcp-json api_server.py \
+  --name "Production API Server" \
+  --with requests \
+  --with python-dotenv \
+  --env API_BASE_URL=https://api.example.com \
+  --env TIMEOUT=30
+```
+
+### Advanced Configuration
+
+```bash
+fastmcp install mcp-json ml_server.py \
+  --name "ML Analysis Server" \
+  --python 3.11 \
+  --with-requirements requirements.txt \
+  --project /home/user/ml-project \
+  --env GPU_DEVICE=0
+```
+
+Output:
+```json
+{
+  "Production API Server": {
+    "command": "uv",
+    "args": [
+      "run",
+      "--with",
+      "fastmcp",
+      "--with",
+      "python-dotenv", 
+      "--with",
+      "requests",
+      "fastmcp",
+      "run", 
+      "/home/user/api_server.py"
+    ],
+    "env": {
+      "API_BASE_URL": "https://api.example.com",
+      "TIMEOUT": "30"
+    }
+  }
+}
+```
+
+The advanced configuration example generates:
+```json
+{
+  "ML Analysis Server": {
+    "command": "uv",
+    "args": [
+      "run",
+      "--python",
+      "3.11",
+      "--project",
+      "/home/user/ml-project",
+      "--with",
+      "fastmcp",
+      "--with-requirements",
+      "requirements.txt",
+      "fastmcp",
+      "run",
+      "/home/user/ml_server.py"
+    ],
+    "env": {
+      "GPU_DEVICE": "0"
+    }
+  }
+}
+```
+
+### Pipeline Usage
+
+Save configuration to file:
+
+```bash
+fastmcp install mcp-json server.py > mcp-config.json
+```
+
+Use in shell scripts:
+
+```bash
+#!/bin/bash
+CONFIG=$(fastmcp install mcp-json server.py --name "CI Server")
+echo "$CONFIG" | jq '."CI Server".command'
+# Output: "uv"
+```
+
+### UV-Managed Project Dependencies
+
+For servers that live inside a uv-managed project (with `pyproject.toml`), use the `--project` flag to run within that project's environment:
+
+```bash
+fastmcp install mcp-json server.py --project .
+```
+
+Output:
+```json
+{
+  "My Server": {
+    "command": "uv",
+    "args": [
+      "run",
+      "--project",
+      "/absolute/path/to/project",
+      "--with",
+      "fastmcp",
+      "fastmcp",
+      "run",
+      "/absolute/path/to/project/server.py"
+    ]
+  }
+}
+```
+
+You can also use `fastmcp.json` with a local project:
+
+```json fastmcp.json
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py"
+  },
+  "environment": {
+    "project": "."
+  }
+}
+```
+
+If your server needs additional packages beyond those in `pyproject.toml`, add them via the `dependencies` array or `--with`.
+
+### Published Packages with `uvx`
+
+If your team publishes MCP servers as pip packages, you can configure clients to run them with `uvx` directly instead of `uv run`. For example, if your package is called `my-mcp-server` and provides a CLI entry point of the same name:
+
+```json
+{
+  "mcpServers": {
+    "My Server": {
+      "command": "uvx",
+      "args": ["my-mcp-server"]
+    }
+  }
+}
+```
+
+If the package name differs from the CLI command (e.g., package `weather-mcp` with command `weather-server`):
+
+```json
+{
+  "mcpServers": {
+    "Weather": {
+      "command": "uvx",
+      "args": ["--from", "weather-mcp", "weather-server"]
+    }
+  }
+}
+```
+
+You can also pin Python versions or add extra dependencies:
+
+```json
+{
+  "mcpServers": {
+    "My Server": {
+      "command": "uvx",
+      "args": [
+        "--python", "3.12",
+        "--with", "requests",
+        "my-mcp-server"
+      ]
+    }
+  }
+}
+```
+
+<Note>
+`fastmcp install mcp-json` generates `uv run` configurations for local development. For published packages, you'll typically write the `uvx` configuration manually or generate it through your own packaging workflow.
+</Note>
+
+## Integration with MCP Clients
+
+The generated configuration works with any MCP-compatible application:
+
+### Claude Desktop
+<Note>
+**Prefer [`fastmcp install claude-desktop`](/v2/integrations/claude-desktop)** for automatic installation. Use MCP JSON for advanced configuration needs.
+</Note>
+Copy the `mcpServers` object into `~/.claude/claude_desktop_config.json`
+
+### Cursor
+<Note>
+**Prefer [`fastmcp install cursor`](/v2/integrations/cursor)** for automatic installation. Use MCP JSON for advanced configuration needs.
+</Note>
+Add to `~/.cursor/mcp.json`
+
+### VS Code  
+Add to your workspace's `.vscode/mcp.json` file
+
+### Custom Applications
+Use the JSON configuration with any application that supports the MCP protocol
+
+## Configuration Format
+
+The generated configuration outputs a server object with the server name as the root key:
+
+```json
+{
+  "<server-name>": {
+    "command": "<executable>",
+    "args": ["<arg1>", "<arg2>", "..."],
+    "env": {
+      "<ENV_VAR>": "<value>"
+    }
+  }
+}
+```
+
+To use this in an MCP client, add it to the client's `mcpServers` configuration object.
+
+**Fields:**
+- `command`: The executable to run (always `uv` for FastMCP servers)
+- `args`: Command-line arguments including dependencies and server path
+- `env`: Environment variables (only included if specified)
+
+<Warning>
+**All file paths in the generated configuration are absolute paths**. This ensures the configuration works regardless of the working directory when the MCP client starts the server.
+</Warning>
+
+## Requirements
+
+- **uv**: Must be installed and available in your system PATH
+- **pyperclip** (optional): Required only for `--copy` functionality
+
+Install uv if not already available:
+
+```bash
+# macOS
+brew install uv
+
+# Linux/Windows  
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
diff --git a/docs/v2/integrations/oci.mdx b/docs/v2/integrations/oci.mdx
new file mode 100644
index 0000000..282a51e
--- /dev/null
+++ b/docs/v2/integrations/oci.mdx
@@ -0,0 +1,333 @@
+---
+title: OCI IAM OAuth 🤝 FastMCP
+sidebarTitle: Oracle
+description: Secure your FastMCP server with OCI IAM OAuth
+icon: shield-check
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.13.0" />
+
+This guide shows you how to secure your FastMCP server using **OCI IAM OAuth**. Since OCI IAM doesn't support Dynamic Client Registration, this integration uses the [**OIDC Proxy**](/v2/servers/auth/oidc-proxy) pattern to bridge OCI's traditional OAuth with MCP's authentication requirements.
+
+## Configuration
+
+### Prerequisites
+
+1. An OCI cloud Account with access to create an Integrated Application in an Identity Domain.
+2. Your FastMCP server's URL (For dev environments, it is http://localhost:8000. For PROD environments, it could be https://mcp.${DOMAIN}.com)
+
+### Step 1: Make sure client access is enabled for JWK's URL
+
+<Steps>
+<Step title="Navigate to OCI IAM Domain Settings">
+
+    Login to OCI console (https://cloud.oracle.com for OCI commercial cloud).
+    From "Identity & Security" menu, open Domains page.
+    On the Domains list page, select the domain that you are using for MCP Authentication.
+    Open Settings tab. 
+    Click on "Edit Domain Settings" button.
+
+    <Frame>
+        <img src="/integrations/images/oci/ocieditdomainsettingsbutton.png" alt="OCI console showing the Edit Domain Settings button in the IAM Domain settings page" />
+    </Frame>
+</Step>
+
+<Step title="Update Domain Setting">
+
+    Enable "Configure client access" checkbox as shown in the screenshot.
+
+    <Frame>
+        <img src="/integrations/images/oci/ocieditdomainsettings.png" alt="OCI IAM Domain Settings" />
+    </Frame>
+</Step>
+</Steps>
+
+### Step 2: Create OAuth client for MCP server authentication
+
+Follow the Steps as mentioned below to create an OAuth client.
+
+<Steps>
+<Step title="Navigate to OCI IAM Integrated Applications">
+
+    Login to OCI console (https://cloud.oracle.com for OCI commercial cloud).
+    From "Identity & Security" menu, open Domains page.
+    On the Domains list page, select the domain in which you want to create MCP server OAuth client. If you need help finding the list page for the domain, see [Listing Identity Domains.](https://docs.oracle.com/en-us/iaas/Content/Identity/domains/to-view-identity-domains.htm#view-identity-domains).
+    On the details page, select Integrated applications. A list of applications in the domain is displayed.
+</Step>
+
+<Step title="Add an Integrated Application">
+
+    Select Add application.
+    In the Add application window, select Confidential Application.
+    Select Launch workflow.
+    In the Add application details page, Enter name and description as shown below.
+
+    <Frame>
+        <img src="/integrations/images/oci/ociaddapplication.png" alt="Adding a Confidential Integrated Application in OCI IAM Domain" />
+    </Frame>
+</Step>
+
+<Step title="Update OAuth Configuration for an Integrated Application">
+
+    Once the Integrated Application is created, Click on "OAuth configuration" tab.
+    Click on "Edit OAuth configuration" button.
+    Configure the application as OAuth client by selecting "Configure this application as a client now" radio button.
+    Select "Authorization code" grant type. If you are planning to use the same OAuth client application for token exchange, select "Client credentials" grant type as well. In the sample, we will use the same client.
+    For Authorization grant type, select redirect URL. In most cases, this will be the MCP server URL followed by "/oauth/callback".
+
+    <Frame>
+        <img src="/integrations/images/oci/ocioauthconfiguration.png" alt="OAuth Configuration for an Integrated Application in OCI IAM Domain" />
+    </Frame>
+</Step>
+
+<Step title="Activate the Integrated Application">
+
+    Click on "Submit" button to update OAuth configuration for the client application. 
+    **Note: You don't need to do any special configuration to support PKCE for the OAuth client.**
+    Make sure to Activate the client application.
+    Note down client ID and client secret for the application. Update .env file and replace FASTMCP_SERVER_AUTH_OCI_CLIENT_ID and FASTMCP_SERVER_AUTH_OCI_CLIENT_SECRET values. 
+    FASTMCP_SERVER_AUTH_OCI_IAM_GUID in the env file is the Identity domain URL that you chose for the MCP server.
+</Step>
+</Steps>
+
+This is all you need to implement MCP server authentication against OCI IAM. However, you may want to use an authenticated user token to invoke OCI control plane APIs and propagate identity to the OCI control plane instead of using a service user account. In that case, you need to implement token exchange.
+
+### Step 3: Token Exchange Setup (Only if MCP server needs to talk to OCI Control Plane)
+
+Token exchange helps you exchange a logged-in user's OCI IAM token for an OCI control plane session token, also known as UPST (User Principal Session Token). To learn more about token exchange, refer to my [Workload Identity Federation Blog](https://www.ateam-oracle.com/post/workload-identity-federation)
+
+For token exchange, we need to configure Identity propagation trust. The blog above discusses setting up the trust using REST APIs. However, you can also use OCI CLI. Before using the CLI command below, ensure that you have created a token exchange OAuth client. In most cases, you can use the same OAuth client that you created above. You will use the client ID of the token exchange OAuth client in the CLI command below and replace it with {FASTMCP_SERVER_AUTH_OCI_CLIENT_ID}. 
+
+You will also need to update the client secret for the token exchange OAuth client in the .env file. It is the FASTMCP_SERVER_AUTH_OCI_CLIENT_SECRET parameter. Update FASTMCP_SERVER_AUTH_OCI_IAM_GUID and FASTMCP_SERVER_AUTH_OCI_CLIENT_ID as well for the token exchange OAuth client in the .env file.
+
+```bash
+oci identity-domains identity-propagation-trust create \
+--schemas '["urn:ietf:params:scim:schemas:oracle:idcs:IdentityPropagationTrust"]' \
+--public-key-endpoint "https://{FASTMCP_SERVER_AUTH_OCI_IAM_GUID}.identity.oraclecloud.com/admin/v1/SigningCert/jwk" \
+--name "For Token Exchange" --type "JWT" \
+--issuer "https://identity.oraclecloud.com/" --active true \
+--endpoint "https://{FASTMCP_SERVER_AUTH_OCI_IAM_GUID}.identity.oracleclcoud.com" \
+--subject-claim-name "sub" --allow-impersonation false \
+--subject-mapping-attribute "username" \
+--subject-type "User" --client-claim-name "iss" \
+--client-claim-values '["https://identity.oraclecloud.com/"]' \
+--oauth-clients '["{FASTMCP_SERVER_AUTH_OCI_CLIENT_ID}"]'
+```
+
+To exchange access token for OCI token and create a signer object, you need to add below code in MCP server. You can then use the signer object to create any OCI control plane client. 
+
+```python
+
+from fastmcp.server.dependencies import get_access_token
+from fastmcp.utilities.logging import get_logger
+from oci.auth.signers import TokenExchangeSigner
+import os
+
+logger = get_logger(__name__)
+
+# Load configuration from environment
+FASTMCP_SERVER_AUTH_OCI_IAM_GUID = os.environ["FASTMCP_SERVER_AUTH_OCI_IAM_GUID"]
+FASTMCP_SERVER_AUTH_OCI_CLIENT_ID = os.environ["FASTMCP_SERVER_AUTH_OCI_CLIENT_ID"]
+FASTMCP_SERVER_AUTH_OCI_CLIENT_SECRET = os.environ["FASTMCP_SERVER_AUTH_OCI_CLIENT_SECRET"]
+
+_global_token_cache = {} #In memory cache for OCI session token signer
+    
+def get_oci_signer() -> TokenExchangeSigner:
+
+    authntoken = get_access_token()
+    tokenID = authntoken.claims.get("jti")
+    token = authntoken.token
+    
+    #Check if the signer exists for the token ID in memory cache
+    cached_signer = _global_token_cache.get(tokenID)
+    logger.debug(f"Global cached signer: {cached_signer}")
+    if cached_signer:
+        logger.debug(f"Using globally cached signer for token ID: {tokenID}")
+        return cached_signer
+
+    #If the signer is not yet created for the token then create new OCI signer object
+    logger.debug(f"Creating new signer for token ID: {tokenID}")
+    signer = TokenExchangeSigner(
+        jwt_or_func=token,
+        oci_domain_id=FASTMCP_SERVER_AUTH_OCI_IAM_GUID.split(".")[0],
+        client_id=FASTMCP_SERVER_AUTH_OCI_CLIENT_ID,
+        client_secret=FASTMCP_SERVER_AUTH_OCI_CLIENT_SECRET,
+    )
+    logger.debug(f"Signer {signer} created for token ID: {tokenID}")
+        
+    #Cache the signer object in memory cache
+    _global_token_cache[tokenID] = signer
+    logger.debug(f"Signer cached for token ID: {tokenID}")
+
+    return signer
+```
+
+## Running MCP server
+
+Once the setup is complete, to run the MCP server, run the below command.
+```bash
+fastmcp run server.py:mcp --transport http --port 8000
+```
+
+To run MCP client, run the below command.
+```bash
+python3 client.py
+```
+
+MCP Client sample is as below.
+```python client.py
+from fastmcp import Client
+import asyncio
+
+async def main():
+    # The client will automatically handle OCI OAuth flows
+    async with Client("http://localhost:8000/mcp/", auth="oauth") as client:
+        # First-time connection will open OCI login in your browser
+        print("✓ Authenticated with OCI IAM")
+
+        tools = await client.list_tools()
+        print(f"🔧 Available tools ({len(tools)}):")
+        for tool in tools:
+            print(f"   - {tool.name}: {tool.description}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+1. Your browser will open to OCI IAM's login page
+2. Sign in with your OCI account and grant the requested consent
+3. After authorization, you'll be redirected back to the redirect path
+4. The client receives the token and can make authenticated requests
+
+## Production Configuration
+
+<VersionBadge version="2.13.0" />
+
+For production deployments with persistent token management across server restarts, configure `jwt_signing_key`, and `client_storage`:
+
+```python server.py
+
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.oci import OCIProvider
+
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+# Load configuration from environment
+FASTMCP_SERVER_AUTH_OCI_CONFIG_URL = os.environ["FASTMCP_SERVER_AUTH_OCI_CONFIG_URL"]
+FASTMCP_SERVER_AUTH_OCI_CLIENT_ID = os.environ["FASTMCP_SERVER_AUTH_OCI_CLIENT_ID"]
+FASTMCP_SERVER_AUTH_OCI_CLIENT_SECRET = os.environ["FASTMCP_SERVER_AUTH_OCI_CLIENT_SECRET"]
+
+# Production setup with encrypted persistent token storage
+auth_provider = OCIProvider(
+    config_url=FASTMCP_SERVER_AUTH_OCI_CONFIG_URL,
+    client_id=FASTMCP_SERVER_AUTH_OCI_CLIENT_ID,
+    client_secret=FASTMCP_SERVER_AUTH_OCI_CLIENT_SECRET,
+    base_url="https://your-production-domain.com",
+
+    # Production token management
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(
+            host=os.environ["REDIS_HOST"],
+            port=int(os.environ["REDIS_PORT"])
+        ),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+
+mcp = FastMCP(name="Production OCI App", auth=auth_provider)
+```
+
+<Note>
+Parameters (`jwt_signing_key` and `client_storage`) work together to ensure tokens and client registrations survive server restarts. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at Rest** - without it, tokens are stored in plaintext. Store secrets in environment variables and use a persistent storage backend like Redis for distributed deployments.
+
+For complete details on these parameters, see the [OAuth Proxy documentation](/v2/servers/auth/oauth-proxy#configuration-parameters).
+</Note>
+
+<Info>
+The client caches tokens locally, so you won't need to re-authenticate for subsequent runs unless the token expires or you explicitly clear the cache.
+</Info>
+
+## Environment Variables
+
+For production deployments, use environment variables instead of hardcoding credentials.
+
+### Provider Selection
+
+Setting this environment variable allows the OCI provider to be used automatically without explicitly instantiating it in code.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH" default="Not set">
+Set to `fastmcp.server.auth.providers.oci.OCIProvider` to use OCI IAM authentication.
+</ParamField>
+</Card>
+
+### OCI-Specific Configuration
+
+These environment variables provide default values for the OCI IAM provider, whether it's instantiated manually or configured via `FASTMCP_SERVER_AUTH`.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH_OCI_IAM_GUID" required>
+Your OCI Application Configuration URL (e.g., `idcs-asdascxasd11......identity.oraclecloud.com`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_OCI_CONFIG_URL" required>
+Your OCI Application Configuration URL (e.g., `https://{FASTMCP_SERVER_AUTH_OCI_IAM_GUID}.identity.oraclecloud.com/.well-known/openid-configuration`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_OCI_CLIENT_ID" required>
+Your OCI Application Client ID (e.g., `tv2ObNgaZAWWhhycr7Bz1LU2mxlnsmsB`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_OCI_CLIENT_SECRET" required>
+Your OCI Application Client Secret (e.g., `idcsssvPYqbjemq...`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_OCI_BASE_URL" required>
+Public URL where OAuth endpoints will be accessible (includes any mount path)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_OCI_REDIRECT_PATH" default="/auth/callback">
+Redirect path configured in your OCI IAM Integrated Application
+</ParamField>
+
+</Card>
+
+Example `.env` file:
+```bash
+# Use the OCI IAM provider
+FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.oci.OCIProvider
+
+# OCI IAM configuration and credentials
+FASTMCP_SERVER_AUTH_OCI_IAM_GUID=idcs-asaacasd1111.....
+FASTMCP_SERVER_AUTH_OCI_CONFIG_URL=https://{FASTMCP_SERVER_AUTH_OCI_IAM_GUID}.identity.oraclecloud.com/.well-known/openid-configuration
+FASTMCP_SERVER_AUTH_OCI_CLIENT_ID=<your-client-id>
+FASTMCP_SERVER_AUTH_OCI_CLIENT_SECRET=<your-client-secret>
+FASTMCP_SERVER_AUTH_OCI_BASE_URL=https://your-server.com
+```
+
+With environment variables set, your server code simplifies to:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.dependencies import get_access_token
+
+# Authentication is automatically configured from environment
+mcp = FastMCP(name="OCI Secured App")
+
+@mcp.tool
+def whoami() -> str:
+    """The whoami function is to test MCP server without requiring token exchange.
+    This tool can be used to test successful authentication against OCI IAM.
+    It will return logged in user's subject (username from IAM domain)."""
+    token = get_access_token()
+    user = token.claims.get("sub")
+    return f"You are User: {user}"
+```
\ No newline at end of file
diff --git a/docs/v2/integrations/openai.mdx b/docs/v2/integrations/openai.mdx
new file mode 100644
index 0000000..af41528
--- /dev/null
+++ b/docs/v2/integrations/openai.mdx
@@ -0,0 +1,227 @@
+---
+title: OpenAI API 🤝 FastMCP
+sidebarTitle: OpenAI API
+description: Connect FastMCP servers to the OpenAI API
+icon: message-code
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+
+## Responses API
+
+OpenAI's [Responses API](https://platform.openai.com/docs/api-reference/responses) supports [MCP servers](https://platform.openai.com/docs/guides/tools-remote-mcp) as remote tool sources, allowing you to extend AI capabilities with custom functions.
+
+<Note>
+The Responses API is a distinct API from OpenAI's Completions API or Assistants API. At this time, only the Responses API supports MCP.
+</Note>
+
+<Tip>
+Currently, the Responses API only accesses **tools** from MCP servers—it queries the `list_tools` endpoint and exposes those functions to the AI agent. Other MCP features like resources and prompts are not currently supported.
+</Tip>
+
+
+### Create a Server
+
+First, create a FastMCP server with the tools you want to expose. For this example, we'll create a server with a single tool that rolls dice.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+
+### Deploy the Server
+
+Your server must be deployed to a public URL in order for OpenAI to access it.
+
+For development, you can use tools like `ngrok` to temporarily expose a locally-running server to the internet. We'll do that for this example (you may need to install `ngrok` and create a free account), but you can use any other method to deploy your server.
+
+Assuming you saved the above code as `server.py`, you can run the following two commands in two separate terminals to deploy your server and expose it to the internet:
+
+<CodeGroup>
+```bash FastMCP server
+python server.py
+```
+
+```bash ngrok
+ngrok http 8000
+```
+</CodeGroup>
+
+<Warning>
+This exposes your unauthenticated server to the internet. Only run this command in a safe environment if you understand the risks.
+</Warning>
+
+### Call the Server
+
+To use the Responses API, you'll need to install the OpenAI Python SDK (not included with FastMCP):
+
+```bash
+pip install openai
+```
+
+You'll also need to authenticate with OpenAI. You can do this by setting the `OPENAI_API_KEY` environment variable. Consult the OpenAI SDK documentation for more information.
+
+```bash
+export OPENAI_API_KEY="your-api-key"
+```
+
+Here is an example of how to call your server from Python. Note that you'll need to replace `https://your-server-url.com` with the actual URL of your server. In addition, we use `/mcp/` as the endpoint because we deployed a streamable-HTTP server with the default path; you may need to use a different endpoint if you customized your server's deployment.
+
+```python {4, 11-16}
+from openai import OpenAI
+
+# Your server URL (replace with your actual URL)
+url = 'https://your-server-url.com'
+
+client = OpenAI()
+
+resp = client.responses.create(
+    model="gpt-4.1",
+    tools=[
+        {
+            "type": "mcp",
+            "server_label": "dice_server",
+            "server_url": f"{url}/mcp/",
+            "require_approval": "never",
+        },
+    ],
+    input="Roll a few dice!",
+)
+
+print(resp.output_text)
+```
+If you run this code, you'll see something like the following output:
+
+```text
+You rolled 3 dice and got the following results: 6, 4, and 2!
+```
+
+### Authentication
+
+<VersionBadge version="2.6.0" />
+
+The Responses API can include headers to authenticate the request, which means you don't have to worry about your server being publicly accessible.
+
+#### Server Authentication
+
+The simplest way to add authentication to the server is to use a bearer token scheme. 
+
+For this example, we'll quickly generate our own tokens with FastMCP's `RSAKeyPair` utility, but this may not be appropriate for production use. For more details, see the complete server-side [Token Verification](/v2/servers/auth/token-verification) documentation. 
+
+We'll start by creating an RSA key pair to sign and verify tokens.
+
+```python
+from fastmcp.server.auth.providers.jwt import RSAKeyPair
+
+key_pair = RSAKeyPair.generate()
+access_token = key_pair.create_token(audience="dice-server")
+```
+
+<Warning>
+FastMCP's `RSAKeyPair` utility is for development and testing only.
+</Warning> 
+
+Next, we'll create a `JWTVerifier` to authenticate the server. 
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import JWTVerifier
+
+auth = JWTVerifier(
+    public_key=key_pair.public_key,
+    audience="dice-server",
+)
+
+mcp = FastMCP(name="Dice Roller", auth=auth)
+```
+
+Here is a complete example that you can copy/paste. For simplicity and the purposes of this example only, it will print the token to the console. **Do NOT do this in production!**
+
+```python server.py [expandable]
+from fastmcp import FastMCP
+from fastmcp.server.auth import JWTVerifier
+from fastmcp.server.auth.providers.jwt import RSAKeyPair
+import random
+
+key_pair = RSAKeyPair.generate()
+access_token = key_pair.create_token(audience="dice-server")
+
+auth = JWTVerifier(
+    public_key=key_pair.public_key,
+    audience="dice-server",
+)
+
+mcp = FastMCP(name="Dice Roller", auth=auth)
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    print(f"\n---\n\n🔑 Dice Roller access token:\n\n{access_token}\n\n---\n")
+    mcp.run(transport="http", port=8000)
+```
+
+#### Client Authentication
+
+If you try to call the authenticated server with the same OpenAI code we wrote earlier, you'll get an error like this:
+
+```text
+APIStatusError: Error code: 424 - {
+    "error": {
+        "message": "Error retrieving tool list from MCP server: 'dice_server'. Http status code: 401 (Unauthorized)",
+        "type": "external_connector_error",
+        "param": "tools",
+        "code": "http_error"
+    }
+}
+```
+
+As expected, the server is rejecting the request because it's not authenticated.
+
+To authenticate the client, you can pass the token in the `Authorization` header with the `Bearer` scheme:
+
+
+```python {4, 7, 19-21} [expandable]
+from openai import OpenAI
+
+# Your server URL (replace with your actual URL)
+url = 'https://your-server-url.com'
+
+# Your access token (replace with your actual token)
+access_token = 'your-access-token'
+
+client = OpenAI()
+
+resp = client.responses.create(
+    model="gpt-4.1",
+    tools=[
+        {
+            "type": "mcp",
+            "server_label": "dice_server",
+            "server_url": f"{url}/mcp/",
+            "require_approval": "never",
+            "headers": {
+                "Authorization": f"Bearer {access_token}"
+            }
+        },
+    ],
+    input="Roll a few dice!",
+)
+
+print(resp.output_text)
+```
+
+You should now see the dice roll results in the output.
\ No newline at end of file
diff --git a/docs/v2/integrations/openapi.mdx b/docs/v2/integrations/openapi.mdx
new file mode 100644
index 0000000..0fd38cb
--- /dev/null
+++ b/docs/v2/integrations/openapi.mdx
@@ -0,0 +1,452 @@
+---
+title: OpenAPI 🤝 FastMCP
+sidebarTitle: OpenAPI
+description: Generate MCP servers from any OpenAPI specification
+icon: list-tree
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.0.0" />
+
+FastMCP can automatically generate an MCP server from any OpenAPI specification, allowing AI models to interact with existing APIs through the MCP protocol. Instead of manually creating tools and resources, you provide an OpenAPI spec and FastMCP intelligently converts API endpoints into the appropriate MCP components.
+
+<Tip>
+Generating MCP servers from OpenAPI is a great way to get started with FastMCP, but in practice LLMs achieve **significantly better performance** with well-designed and curated MCP servers than with auto-converted OpenAPI servers. This is especially true for complex APIs with many endpoints and parameters.
+
+We recommend using the FastAPI integration for bootstrapping and prototyping, not for mirroring your API to LLM clients. See the post [Stop Converting Your REST APIs to MCP](https://www.jlowin.dev/blog/stop-converting-rest-apis-to-mcp) for more details.
+</Tip>
+
+## Create a Server
+
+To convert an OpenAPI specification to an MCP server, use the `FastMCP.from_openapi()` class method:
+
+```python server.py
+import httpx
+from fastmcp import FastMCP
+
+# Create an HTTP client for your API
+client = httpx.AsyncClient(base_url="https://api.example.com")
+
+# Load your OpenAPI spec 
+openapi_spec = httpx.get("https://api.example.com/openapi.json").json()
+
+# Create the MCP server
+mcp = FastMCP.from_openapi(
+    openapi_spec=openapi_spec,
+    client=client,
+    name="My API Server"
+)
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+### Authentication
+
+If your API requires authentication, configure it on the HTTP client:
+
+```python
+import httpx
+from fastmcp import FastMCP
+
+# Bearer token authentication
+api_client = httpx.AsyncClient(
+    base_url="https://api.example.com",
+    headers={"Authorization": "Bearer YOUR_TOKEN"}
+)
+
+# Create MCP server with authenticated client
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec, 
+    client=api_client,
+    timeout=30.0  # 30 second timeout for all requests
+)
+```
+
+## Route Mapping
+
+By default, FastMCP converts **every endpoint** in your OpenAPI specification into an MCP **Tool**. This provides a simple, predictable starting point that ensures all your API's functionality is immediately available to the vast majority of LLM clients which only support MCP tools.
+
+While this is a pragmatic default for maximum compatibility, you can easily customize this behavior. Internally, FastMCP uses an ordered list of `RouteMap` objects to determine how to map OpenAPI routes to various MCP component types.
+
+Each `RouteMap` specifies a combination of methods, patterns, and tags, as well as a corresponding MCP component type. Each OpenAPI route is checked against each `RouteMap` in order, and the first one that matches every criteria is used to determine its converted MCP type. A special type, `EXCLUDE`, can be used to exclude routes from the MCP server entirely.
+
+- **Methods**: HTTP methods to match (e.g. `["GET", "POST"]` or `"*"` for all)
+- **Pattern**: Regex pattern to match the route path (e.g. `r"^/users/.*"` or `r".*"` for all)
+- **Tags**: A set of OpenAPI tags that must all be present. An empty set (`{}`) means no tag filtering, so the route matches regardless of its tags.
+- **MCP type**: What MCP component type to create (`TOOL`, `RESOURCE`, `RESOURCE_TEMPLATE`, or `EXCLUDE`)
+- **MCP tags**: A set of custom tags to add to components created from matching routes
+
+Here is FastMCP's default rule:
+
+```python
+from fastmcp.server.providers.openapi import RouteMap, MCPType
+
+DEFAULT_ROUTE_MAPPINGS = [
+    # All routes become tools
+    RouteMap(mcp_type=MCPType.TOOL),
+]
+```
+
+### Custom Route Maps
+
+When creating your FastMCP server, you can customize routing behavior by providing your own list of `RouteMap` objects. Your custom maps are processed before the default route maps, and routes will be assigned to the first matching custom map.
+
+For example, prior to FastMCP 2.8.0, GET requests were automatically mapped to `Resource` and `ResourceTemplate` components based on whether they had path parameters. (This was changed solely for client compatibility reasons.) You can restore this behavior by providing custom route maps:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi import RouteMap, MCPType
+
+# Restore pre-2.8.0 semantic mapping
+semantic_maps = [
+    # GET requests with path parameters become ResourceTemplates
+    RouteMap(methods=["GET"], pattern=r".*\{.*\}.*", mcp_type=MCPType.RESOURCE_TEMPLATE),
+    # All other GET requests become Resources
+    RouteMap(methods=["GET"], pattern=r".*", mcp_type=MCPType.RESOURCE),
+]
+
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    route_maps=semantic_maps,
+)
+```
+
+With these maps, `GET` requests are handled semantically, and all other methods (`POST`, `PUT`, etc.) will fall through to the default rule and become `Tool`s.
+
+Here is a more complete example that uses custom route maps to convert all `GET` endpoints under `/analytics/` to tools while excluding all admin endpoints and all routes tagged "internal". All other routes will be handled by the default rules:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi import RouteMap, MCPType
+
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    route_maps=[
+        # Analytics `GET` endpoints are tools
+        RouteMap(
+            methods=["GET"], 
+            pattern=r"^/analytics/.*", 
+            mcp_type=MCPType.TOOL,
+        ),
+
+        # Exclude all admin endpoints
+        RouteMap(
+            pattern=r"^/admin/.*", 
+            mcp_type=MCPType.EXCLUDE,
+        ),
+
+        # Exclude all routes tagged "internal"
+        RouteMap(
+            tags={"internal"},
+            mcp_type=MCPType.EXCLUDE,
+        ),
+    ],
+)
+```
+
+<Tip>
+The default route maps are always applied after your custom maps, so you do not have to create route maps for every possible route.
+</Tip>
+
+### Excluding Routes
+
+To exclude routes from the MCP server, use a route map to assign them to `MCPType.EXCLUDE`. 
+
+You can use this to remove sensitive or internal routes by targeting them specifically:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi import RouteMap, MCPType
+
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    route_maps=[
+        RouteMap(pattern=r"^/admin/.*", mcp_type=MCPType.EXCLUDE),
+        RouteMap(tags={"internal"}, mcp_type=MCPType.EXCLUDE),
+    ],
+)
+```
+
+Or you can use a catch-all rule to exclude everything that your maps don't handle explicitly:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi import RouteMap, MCPType
+
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    route_maps=[
+        # custom mapping logic goes here
+        # ... your specific route maps ...
+        # exclude all remaining routes
+        RouteMap(mcp_type=MCPType.EXCLUDE),
+    ],
+)
+```
+
+<Tip>
+Using a catch-all exclusion rule will prevent the default route mappings from being applied, since it will match every remaining route. This is useful if you want to explicitly allow-list certain routes.
+</Tip>
+
+### Advanced Route Mapping
+
+<VersionBadge version="2.5.0" />
+
+For advanced use cases that require more complex logic, you can provide a `route_map_fn` callable. After the route map logic is applied, this function is called on each matched route and its assigned MCP component type. It can optionally return a different component type to override the mapped assignment. If it returns `None`, the assigned type is used.
+
+In addition to more precise targeting of methods, patterns, and tags, this function can access any additional OpenAPI metadata about the route.
+
+<Tip>
+The `route_map_fn` is called on all routes, even those that matched `MCPType.EXCLUDE` in your custom maps. This gives you an opportunity to customize the mapping or even override an exclusion.
+</Tip>
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi import RouteMap, MCPType
+from fastmcp.utilities.openapi import HTTPRoute
+
+def custom_route_mapper(route: HTTPRoute, mcp_type: MCPType) -> MCPType | None:
+    """Advanced route type mapping."""
+    # Convert all admin routes to tools regardless of HTTP method
+    if "/admin/" in route.path:
+        return MCPType.TOOL
+
+    elif "internal" in route.tags:
+        return MCPType.EXCLUDE
+    
+    # Convert user detail routes to templates even if they're POST
+    elif route.path.startswith("/users/") and route.method == "POST":
+        return MCPType.RESOURCE_TEMPLATE
+    
+    # Use defaults for all other routes
+    return None
+
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    route_map_fn=custom_route_mapper,
+)
+```
+
+## Customization
+
+### Component Names
+
+<VersionBadge version="2.5.0" />
+
+FastMCP automatically generates names for MCP components based on the OpenAPI specification. By default, it uses the `operationId` from your OpenAPI spec, up to the first double underscore (`__`).
+
+All component names are automatically:
+- **Slugified**: Spaces and special characters are converted to underscores or removed
+- **Truncated**: Limited to 56 characters maximum to ensure compatibility
+- **Unique**: If multiple components have the same name, a number is automatically appended to make them unique
+
+For more control over component names, you can provide an `mcp_names` dictionary that maps `operationId` values to your desired names. The `operationId` must be exactly as it appears in the OpenAPI spec. The provided name will always be slugified and truncated.
+
+```python
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    mcp_names={
+        "list_users__with_pagination": "user_list",
+        "create_user__admin_required": "create_user", 
+        "get_user_details__admin_required": "user_detail",
+    }
+)
+```
+
+Any `operationId` not found in `mcp_names` will use the default strategy (operationId up to the first `__`).
+
+### Tags
+
+<VersionBadge version="2.8.0" />
+
+FastMCP provides several ways to add tags to your MCP components, allowing you to categorize and organize them for better discoverability and filtering. Tags are combined from multiple sources to create the final set of tags on each component.
+
+#### RouteMap Tags
+
+You can add custom tags to components created from specific routes using the `mcp_tags` parameter in `RouteMap`. These tags will be applied to all components created from routes that match that particular route map.
+
+```python
+from fastmcp.server.providers.openapi import RouteMap, MCPType
+
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    route_maps=[
+        # Add custom tags to all POST endpoints
+        RouteMap(
+            methods=["POST"],
+            pattern=r".*",
+            mcp_type=MCPType.TOOL,
+            mcp_tags={"write-operation", "api-mutation"}
+        ),
+        
+        # Add different tags to detail view endpoints
+        RouteMap(
+            methods=["GET"],
+            pattern=r".*\{.*\}.*",
+            mcp_type=MCPType.RESOURCE_TEMPLATE,
+            mcp_tags={"detail-view", "parameterized"}
+        ),
+        
+        # Add tags to list endpoints
+        RouteMap(
+            methods=["GET"],
+            pattern=r".*",
+            mcp_type=MCPType.RESOURCE,
+            mcp_tags={"list-data", "collection"}
+        ),
+    ],
+)
+```
+
+#### Global Tags
+
+You can add tags to **all** components by providing a `tags` parameter when creating your MCP server. These global tags will be applied to every component created from your OpenAPI specification.
+
+```python
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    tags={"api-v2", "production", "external"}
+)
+```
+
+#### OpenAPI Tags in Client Meta
+
+FastMCP automatically includes OpenAPI tags from your specification in the component's metadata. These tags are available to MCP clients through the `_meta._fastmcp.tags` field, allowing clients to filter and organize components based on the original OpenAPI tagging:
+
+<CodeGroup>
+```json {5} OpenAPI spec with tags
+{
+  "paths": {
+    "/users": {
+      "get": {
+        "tags": ["users", "public"],
+        "operationId": "list_users",
+        "summary": "List all users"
+      }
+    }
+  }
+}
+```
+```python {6-9} Access OpenAPI tags in MCP client
+async with client:
+    tools = await client.list_tools()
+    for tool in tools:
+        if hasattr(tool, '_meta') and tool._meta:
+            # OpenAPI tags are now available in _fastmcp namespace!
+            fastmcp_meta = tool._meta.get('_fastmcp', {})
+            openapi_tags = fastmcp_meta.get('tags', [])
+            if 'users' in openapi_tags:
+                print(f"Found user-related tool: {tool.name}")
+```
+</CodeGroup>
+
+This makes it easy for clients to understand and organize API endpoints based on their original OpenAPI categorization.
+
+### Advanced Customization
+
+<VersionBadge version="2.5.0" />
+
+By default, FastMCP creates MCP components using a variety of metadata from the OpenAPI spec, such as incorporating the OpenAPI description into the MCP component description.
+
+At times you may want to modify those MCP components in a variety of ways, such as adding LLM-specific instructions or tags. For fine-grained customization, you can provide a `mcp_component_fn` when creating the MCP server. After each MCP component has been created, this function is called on it and has the opportunity to modify it in-place.
+
+<Tip>
+Your `mcp_component_fn` is expected to modify the component in-place, not to return a new component. The result of the function is ignored.
+</Tip>
+
+```python
+from fastmcp.server.providers.openapi import (
+    OpenAPITool,
+    OpenAPIResource,
+    OpenAPIResourceTemplate,
+)
+from fastmcp.utilities.openapi import HTTPRoute
+
+def customize_components(
+    route: HTTPRoute, 
+    component: OpenAPITool | OpenAPIResource | OpenAPIResourceTemplate,
+) -> None:
+    # Add custom tags to all components
+    component.tags.add("openapi")
+    
+    # Customize based on component type
+    if isinstance(component, OpenAPITool):
+        component.description = f"🔧 {component.description} (via API)"
+    
+    if isinstance(component, OpenAPIResource):
+        component.description = f"📊 {component.description}"
+        component.tags.add("data")
+
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    mcp_component_fn=customize_components,
+)
+```
+
+## Request Parameter Handling
+
+FastMCP intelligently handles different types of parameters in OpenAPI requests:
+
+### Query Parameters
+
+By default, FastMCP only includes query parameters that have non-empty values. Parameters with `None` values or empty strings are automatically filtered out.
+
+```python
+# When calling this tool...
+await client.call_tool("search_products", {
+    "category": "electronics",  # ✅ Included
+    "min_price": 100,           # ✅ Included  
+    "max_price": None,          # ❌ Excluded
+    "brand": "",                # ❌ Excluded
+})
+
+# The HTTP request will be: GET /products?category=electronics&min_price=100
+```
+
+### Path Parameters
+
+Path parameters are typically required by REST APIs. FastMCP:
+- Filters out `None` values
+- Validates that all required path parameters are provided
+- Raises clear errors for missing required parameters
+
+```python
+# ✅ This works
+await client.call_tool("get_user", {"user_id": 123})
+
+# ❌ This raises: "Missing required path parameters: {'user_id'}"
+await client.call_tool("get_user", {"user_id": None})
+```
+
+### Array Parameters
+
+FastMCP handles array parameters according to OpenAPI specifications:
+
+- **Query arrays**: Serialized based on the `explode` parameter (default: `True`)
+- **Path arrays**: Serialized as comma-separated values (OpenAPI 'simple' style)
+
+```python
+# Query array with explode=true (default)
+# ?tags=red&tags=blue&tags=green
+
+# Query array with explode=false  
+# ?tags=red,blue,green
+
+# Path array (always comma-separated)
+# /items/red,blue,green
+```
+
+### Headers
+
+Header parameters are automatically converted to strings and included in the HTTP request.
\ No newline at end of file
diff --git a/docs/v2/integrations/permit.mdx b/docs/v2/integrations/permit.mdx
new file mode 100644
index 0000000..066f5b1
--- /dev/null
+++ b/docs/v2/integrations/permit.mdx
@@ -0,0 +1,352 @@
+---
+title: Permit.io Authorization 🤝 FastMCP
+sidebarTitle: Permit.io
+description: Add fine-grained authorization to your FastMCP servers with Permit.io
+icon: shield-check
+---
+
+Add **policy-based authorization** to your FastMCP servers with one-line code addition with the **[Permit.io][permit-github] authorization middleware**.
+
+Control which tools, resources and prompts MCP clients can view and execute on your server. Define dynamic policies using Permit.io's powerful RBAC, ABAC, and REBAC capabilities, and obtain comprehensive audit logs of all access attempts and violations.
+
+## How it Works
+
+Leveraging FastMCP's [Middleware][fastmcp-middleware], the Permit.io middleware intercepts all MCP requests to your server and automatically maps MCP methods to authorization checks against your Permit.io policies; covering both server methods and tool execution.
+
+### Policy Mapping
+
+The middleware automatically maps MCP methods to Permit.io resources and actions:
+
+- **MCP server methods** (e.g., `tools/list`, `resources/read`):
+  - **Resource**: `{server_name}_{component}` (e.g., `myserver_tools`)
+  - **Action**: The method verb (e.g., `list`, `read`)
+- **Tool execution** (method `tools/call`):
+  - **Resource**: `{server_name}` (e.g., `myserver`)
+  - **Action**: The tool name (e.g., `greet`)
+
+![Permit.io Policy Mapping Example](./images/permit/policy_mapping.png)
+
+*Example: In Permit.io, the 'Admin' role is granted permissions on resources and actions as mapped by the middleware. For example, 'greet', 'greet-jwt', and 'login' are actions on the 'mcp_server' resource, and 'list' is an action on the 'mcp_server_tools' resource.*
+
+> **Note:**
+> Don't forget to assign the relevant role (e.g., Admin, User) to the user authenticating to your MCP server (such as the user in the JWT) in the Permit.io Directory. Without the correct role assignment, users will not have access to the resources and actions you've configured in your policies.
+>
+> ![Permit.io Directory Role Assignment Example](./images/permit/role_assignement.png)
+>
+> *Example: In Permit.io Directory, both 'client' and 'admin' users are assigned the 'Admin' role, granting them the permissions defined in your policy mapping.*
+
+For detailed policy mapping examples and configuration, see [Detailed Policy Mapping](https://github.com/permitio/permit-fastmcp/blob/main/docs/policy-mapping.md).
+
+### Listing Operations
+
+The middleware behaves as a filter for listing operations (`tools/list`, `resources/list`, `prompts/list`), hiding to the client components that are not authorized by the defined policies.
+
+```mermaid
+sequenceDiagram
+    participant MCPClient as MCP Client
+    participant PermitMiddleware as Permit.io Middleware
+    participant MCPServer as FastMCP Server
+    participant PermitPDP as Permit.io PDP
+
+    MCPClient->>PermitMiddleware: MCP Listing Request (e.g., tools/list)
+    PermitMiddleware->>MCPServer: MCP Listing Request
+    MCPServer-->>PermitMiddleware: MCP Listing Response
+    PermitMiddleware->>PermitPDP: Authorization Checks
+    PermitPDP->>PermitMiddleware: Authorization Decisions
+    PermitMiddleware-->>MCPClient: Filtered MCP Listing Response
+```
+
+### Execution Operations
+
+The middleware behaves as an enforcement point for execution operations (`tools/call`, `resources/read`, `prompts/get`), blocking operations that are not authorized by the defined policies.
+
+```mermaid
+sequenceDiagram
+    participant MCPClient as MCP Client
+    participant PermitMiddleware as Permit.io Middleware
+    participant MCPServer as FastMCP Server
+    participant PermitPDP as Permit.io PDP
+
+    MCPClient->>PermitMiddleware: MCP Execution Request (e.g., tools/call)
+    PermitMiddleware->>PermitPDP: Authorization Check
+    PermitPDP->>PermitMiddleware: Authorization Decision
+    PermitMiddleware-->>MCPClient: MCP Unauthorized Error (if denied)
+    PermitMiddleware->>MCPServer: MCP Execution Request (if allowed)
+    MCPServer-->>PermitMiddleware: MCP Execution Response (if allowed)
+    PermitMiddleware-->>MCPClient: MCP Execution Response (if allowed)
+```
+
+## Add Authorization to Your Server
+
+<Note>
+Permit.io is a cloud-native authorization service. You need a Permit.io account and a running Policy Decision Point (PDP) for the middleware to function. You can run the PDP locally with Docker or use Permit.io's cloud PDP.
+</Note>
+
+### Prerequisites
+
+1. **Permit.io Account**: Sign up at [permit.io](https://permit.io)
+2. **PDP Setup**: Run the Permit.io PDP locally or use the cloud PDP (RBAC only)
+3. **API Key**: Get your Permit.io API key from the dashboard
+
+### Run the Permit.io PDP
+
+Run the PDP locally with Docker:
+
+```bash
+docker run -p 7766:7766 permitio/pdp:latest
+```
+
+Or use the cloud PDP URL: `https://cloudpdp.api.permit.io`
+
+### Create a Server with Authorization
+
+First, install the `permit-fastmcp` package:
+
+```bash
+# Using UV (recommended)
+uv add permit-fastmcp
+
+# Using pip
+pip install permit-fastmcp
+```
+
+Then create a FastMCP server and add the Permit.io middleware:
+
+```python server.py
+from fastmcp import FastMCP
+from permit_fastmcp.middleware.middleware import PermitMcpMiddleware
+
+mcp = FastMCP("Secure FastMCP Server 🔒")
+
+@mcp.tool
+def greet(name: str) -> str:
+    """Greet a user by name"""
+    return f"Hello, {name}!"
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+# Add Permit.io authorization middleware
+mcp.add_middleware(PermitMcpMiddleware(
+    permit_pdp_url="http://localhost:7766",
+    permit_api_key="your-permit-api-key"
+))
+
+if __name__ == "__main__":
+    mcp.run(transport="http")
+```
+
+### Configure Access Policies
+
+Create your authorization policies in the Permit.io dashboard:
+
+1. **Create Resources**: Define resources like `mcp_server` and `mcp_server_tools`
+2. **Define Actions**: Add actions like `greet`, `add`, `list`, `read`
+3. **Create Roles**: Define roles like `Admin`, `User`, `Guest`
+4. **Assign Permissions**: Grant roles access to specific resources and actions
+5. **Assign Users**: Assign roles to users in the Permit.io Directory
+
+For step-by-step setup instructions and troubleshooting, see [Getting Started & FAQ](https://github.com/permitio/permit-fastmcp/blob/main/docs/getting-started.md).
+
+#### Example Policy Configuration
+
+Policies are defined in the Permit.io dashboard, but you can also use the [Permit.io Terraform provider](https://github.com/permitio/terraform-provider-permitio) to define policies in code.
+
+
+```terraform
+# Resources
+resource "permitio_resource" "mcp_server" {
+  name = "mcp_server"
+  key  = "mcp_server"
+  
+  actions = {
+    "greet" = { name = "greet" }
+    "add"   = { name = "add" }
+  }
+}
+
+resource "permitio_resource" "mcp_server_tools" {
+  name = "mcp_server_tools"
+  key  = "mcp_server_tools"
+  
+  actions = {
+    "list" = { name = "list" }
+  }
+}
+
+# Roles
+resource "permitio_role" "Admin" {
+  key         = "Admin"
+  name        = "Admin"
+  permissions = [
+    "mcp_server:greet",
+    "mcp_server:add", 
+    "mcp_server_tools:list"
+  ]
+}
+```
+
+You can also use the [Permit.io CLI](https://github.com/permitio/permit-cli), [API](https://api.permit.io/scalar) or [SDKs](https://github.com/permitio/permit-python) to manage policies, as well as writing policies directly in REGO (Open Policy Agent's policy language).
+
+For complete policy examples including ABAC and RBAC configurations, see [Example Policies](https://github.com/permitio/permit-fastmcp/tree/main/docs/example_policies).
+
+### Identity Management
+
+The middleware supports multiple identity extraction modes:
+
+- **Fixed Identity**: Use a fixed identity for all requests
+- **Header-based**: Extract identity from HTTP headers
+- **JWT-based**: Extract and verify JWT tokens
+- **Source-based**: Use the MCP context source field
+
+For detailed identity mode configuration and environment variables, see [Identity Modes & Environment Variables](https://github.com/permitio/permit-fastmcp/blob/main/docs/identity-modes.md).
+
+#### JWT Authentication Example
+
+```python
+import os
+
+# Configure JWT identity extraction
+os.environ["PERMIT_MCP_IDENTITY_MODE"] = "jwt"
+os.environ["PERMIT_MCP_IDENTITY_JWT_SECRET"] = "your-jwt-secret"
+
+mcp.add_middleware(PermitMcpMiddleware(
+    permit_pdp_url="http://localhost:7766",
+    permit_api_key="your-permit-api-key"
+))
+```
+
+### ABAC Policies with Tool Arguments
+
+The middleware supports Attribute-Based Access Control (ABAC) policies that can evaluate tool arguments as attributes. Tool arguments are automatically flattened as individual attributes (e.g., `arg_name`, `arg_number`) for granular policy conditions.
+
+![ABAC Condition Example](./images/permit/abac_condition_example.png)
+
+*Example: Create dynamic resources with conditions like `resource.arg_number greater-than 10` to allow the `conditional-greet` tool only when the number argument exceeds 10.*
+
+#### Example: Conditional Access
+
+Create a dynamic resource with conditions like `resource.arg_number greater-than 10` to allow the `conditional-greet` tool only when the number argument exceeds 10.
+
+```python
+@mcp.tool
+def conditional_greet(name: str, number: int) -> str:
+    """Greet a user only if number > 10"""
+    return f"Hello, {name}! Your number is {number}"
+```
+
+![ABAC Policy Example](./images/permit/abac_policy_example.png)
+
+*Example: The Admin role is granted access to the "conditional-greet" action on the "Big-greets" dynamic resource, while other tools like "greet", "greet-jwt", and "login" are granted on the base "mcp_server" resource.*
+
+For comprehensive ABAC configuration and advanced policy examples, see [ABAC Policies with Tool Arguments](https://github.com/permitio/permit-fastmcp/blob/main/docs/policy-mapping.md#abac-policies-with-tool-arguments).
+
+### Run the Server
+
+Start your FastMCP server normally:
+
+```bash
+python server.py
+```
+
+The middleware will now intercept all MCP requests and check them against your Permit.io policies. Requests include user identification through the configured identity mode and automatic mapping of MCP methods to authorization resources and actions.
+
+## Advanced Configuration
+
+### Environment Variables
+
+Configure the middleware using environment variables:
+
+```bash
+# Permit.io configuration
+export PERMIT_MCP_PERMIT_PDP_URL="http://localhost:7766"
+export PERMIT_MCP_PERMIT_API_KEY="your-api-key"
+
+# Identity configuration
+export PERMIT_MCP_IDENTITY_MODE="jwt"
+export PERMIT_MCP_IDENTITY_JWT_SECRET="your-jwt-secret"
+
+# Method configuration
+export PERMIT_MCP_KNOWN_METHODS='["tools/list","tools/call"]'
+export PERMIT_MCP_BYPASSED_METHODS='["initialize","ping"]'
+
+# Logging configuration
+export PERMIT_MCP_ENABLE_AUDIT_LOGGING="true"
+```
+
+For a complete list of all configuration options and environment variables, see [Configuration Reference](https://github.com/permitio/permit-fastmcp/blob/main/docs/configuration-reference.md).
+
+### Custom Middleware Configuration
+
+```python
+from permit_fastmcp.middleware.middleware import PermitMcpMiddleware
+
+middleware = PermitMcpMiddleware(
+    permit_pdp_url="http://localhost:7766",
+    permit_api_key="your-api-key",
+    enable_audit_logging=True,
+    bypass_methods=["initialize", "ping", "health/*"]
+)
+
+mcp.add_middleware(middleware)
+```
+
+For advanced configuration options and custom middleware extensions, see [Advanced Configuration](https://github.com/permitio/permit-fastmcp/blob/main/docs/advanced-configuration.md).
+
+## Example: Complete JWT Authentication Server
+
+See the [example server](https://github.com/permitio/permit-fastmcp/blob/main/permit_fastmcp/example_server/example.py) for a full implementation with JWT-based authentication. For additional examples and usage patterns, see [Example Server](https://github.com/permitio/permit-fastmcp/blob/main/permit_fastmcp/example_server/):
+
+```python
+from fastmcp import FastMCP, Context
+from permit_fastmcp.middleware.middleware import PermitMcpMiddleware
+import jwt
+import datetime
+
+# Configure JWT identity extraction
+os.environ["PERMIT_MCP_IDENTITY_MODE"] = "jwt"
+os.environ["PERMIT_MCP_IDENTITY_JWT_SECRET"] = "mysecretkey"
+
+mcp = FastMCP("My MCP Server")
+
+@mcp.tool
+def login(username: str, password: str) -> str:
+    """Login to get a JWT token"""
+    if username == "admin" and password == "password":
+        token = jwt.encode(
+            {"sub": username, "exp": datetime.datetime.utcnow() + datetime.timedelta(hours=1)},
+            "mysecretkey",
+            algorithm="HS256"
+        )
+        return f"Bearer {token}"
+    raise Exception("Invalid credentials")
+
+@mcp.tool
+def greet_jwt(ctx: Context) -> str:
+    """Greet a user by extracting their name from JWT"""
+    # JWT extraction handled by middleware
+    return "Hello, authenticated user!"
+
+mcp.add_middleware(PermitMcpMiddleware(
+    permit_pdp_url="http://localhost:7766",
+    permit_api_key="your-permit-api-key"
+))
+
+if __name__ == "__main__":
+    mcp.run(transport="http")
+```
+
+<Tip>
+  For detailed policy configuration, custom authentication, and advanced
+  deployment patterns, visit the [Permit.io FastMCP Middleware
+  repository][permit-fastmcp-github]. For troubleshooting common issues, see [Troubleshooting](https://github.com/permitio/permit-fastmcp/blob/main/docs/troubleshooting.md).
+</Tip>
+
+
+[permit.io]: https://www.permit.io
+[permit-github]: https://github.com/permitio
+[permit-fastmcp-github]: https://github.com/permitio/permit-fastmcp
+[Agent.Security]: https://agent.security
+[fastmcp-middleware]: /servers/middleware
diff --git a/docs/v2/integrations/scalekit.mdx b/docs/v2/integrations/scalekit.mdx
new file mode 100644
index 0000000..5a87733
--- /dev/null
+++ b/docs/v2/integrations/scalekit.mdx
@@ -0,0 +1,187 @@
+---
+title: Scalekit 🤝 FastMCP
+sidebarTitle: Scalekit
+description: Secure your FastMCP server with Scalekit
+icon: shield-check
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.13.0" />
+
+Install auth stack to your FastMCP server with [Scalekit](https://scalekit.com) using the [Remote OAuth](/v2/servers/auth/remote-oauth) pattern: Scalekit handles user authentication, and the MCP server validates issued tokens.
+
+### Prerequisites
+
+Before you begin
+
+1. Get a [Scalekit account](https://app.scalekit.com/) and grab your **Environment URL** from _Dashboard > Settings_ .
+2. Have your FastMCP server's base URL ready (can be localhost for development, e.g., `http://localhost:8000/`)
+
+### Step 1: Configure MCP server in Scalekit environment
+
+<Steps>
+<Step title="Register MCP server and set environment">
+
+In your Scalekit dashboard:
+    1. Open the **MCP Servers** section, then select **Create new server**
+    2. Enter server details: a name, a resource identifier, and the desired MCP client authentication settings
+    3. Save, then copy the **Resource ID** (for example, res_92015146095)
+
+In your FastMCP project's `.env`:
+
+```sh
+SCALEKIT_ENVIRONMENT_URL=<YOUR_APP_ENVIRONMENT_URL>
+SCALEKIT_RESOURCE_ID=<YOUR_APP_RESOURCE_ID> # res_926EXAMPLE5878
+BASE_URL=http://localhost:8000/
+# Optional: additional scopes tokens must have
+# SCALEKIT_REQUIRED_SCOPES=read,write
+```
+
+</Step>
+</Steps>
+
+### Step 2: Add auth to FastMCP server
+
+Create your FastMCP server file and use the ScalekitProvider to handle all the OAuth integration automatically:
+
+> **Warning:** The legacy `mcp_url` and `client_id` parameters are deprecated and will be removed in a future release. Use `base_url` instead of `mcp_url` and remove `client_id` from your configuration.
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.scalekit import ScalekitProvider
+
+# Discovers Scalekit endpoints and set up JWT token validation
+auth_provider = ScalekitProvider(
+    environment_url=SCALEKIT_ENVIRONMENT_URL,    # Scalekit environment URL
+    resource_id=SCALEKIT_RESOURCE_ID,            # Resource server ID
+    base_url=SERVER_URL,                         # Public MCP endpoint
+    required_scopes=["read"],                    # Optional scope enforcement
+)
+
+# Create FastMCP server with auth
+mcp = FastMCP(name="My Scalekit Protected Server", auth=auth_provider)
+
+@mcp.tool
+def auth_status() -> dict:
+    """Show Scalekit authentication status."""
+    # Extract user claims from the JWT
+    return {
+        "message": "This tool requires authentication via Scalekit",
+        "authenticated": True,
+        "provider": "Scalekit"
+    }
+
+```
+
+<Tip>
+Set `required_scopes` when you need tokens to carry specific permissions. Leave it unset to allow any token issued for the resource.
+</Tip>
+
+## Testing
+
+### Start the MCP server
+
+```sh
+uv run python server.py
+```
+
+Use any MCP client (for example, mcp-inspector, Claude, VS Code, or Windsurf) to connect to the running serve. Verify that authentication succeeds and requests are authorized as expected.
+
+### Provider selection
+
+Setting this environment variable allows the Scalekit provider to be used automatically without explicitly instantiating it in code.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH" default="Not set">
+Set to `fastmcp.server.auth.providers.scalekit.ScalekitProvider` to use Scalekit authentication.
+</ParamField>
+</Card>
+
+### Scalekit-specific configuration
+
+These environment variables provide default values for the Scalekit provider, whether it's instantiated manually or configured via `FASTMCP_SERVER_AUTH`.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_ENVIRONMENT_URL" required>
+Your Scalekit environment URL from the Admin Portal (e.g., `https://your-env.scalekit.com`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_RESOURCE_ID" required>
+Your Scalekit resource server ID from the MCP Servers section
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_BASE_URL" required>
+Public URL of your FastMCP server (e.g., `https://your-server.com` or `http://localhost:8000/` for development)
+</ParamField>
+
+Legacy `FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_MCP_URL` is still recognized for backward compatibility but will be removed soon-rename it to `...BASE_URL`.
+
+<ParamField path="FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_REQUIRED_SCOPES" default="[]">
+Comma-, space-, or JSON-separated list of scopes that tokens must include to access your server
+</ParamField>
+</Card>
+
+Example `.env`:
+
+```bash
+# Use the Scalekit provider
+FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.scalekit.ScalekitProvider
+
+# Scalekit configuration
+FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_ENVIRONMENT_URL=https://your-env.scalekit.com
+FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_RESOURCE_ID=res_456
+FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_BASE_URL=https://your-server.com/
+# FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_REQUIRED_SCOPES=read,write
+# FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_MCP_URL=https://your-server.com/  # Deprecated
+```
+
+With environment variables set, your server code simplifies to:
+
+```python server.py
+from fastmcp import FastMCP
+
+# Authentication is automatically configured from environment
+mcp = FastMCP(name="My Scalekit Protected Server")
+
+@mcp.tool
+def protected_action() -> str:
+    """A tool that requires authentication."""
+    return "Access granted via Scalekit!"
+```
+
+## Capabilities
+
+Scalekit supports OAuth 2.1 with Dynamic Client Registration for MCP clients and enterprise SSO, and provides built‑in JWT validation and security controls.
+
+**OAuth 2.1/DCR**: clients self‑register, use PKCE, and work with the Remote OAuth pattern without pre‑provisioned credentials.
+
+**Validation and SSO**: tokens are verified (keys, RS256, issuer, audience, expiry), and SAML, OIDC, OAuth 2.0, ADFS, Azure AD, and Google Workspace are supported; use HTTPS in production and review auth logs as needed.
+
+## Debugging
+
+Enable detailed logging to troubleshoot authentication issues:
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+### Token inspection
+
+You can inspect JWT tokens in your tools to understand the user context:
+
+```python
+from fastmcp.server.dependencies import get_access_token
+
+@mcp.tool
+def inspect_token() -> dict:
+    """Inspect the current JWT token claims."""
+    token = get_access_token()
+    if token is None:
+        return {"error": "No token found"}
+
+    # Claims were already verified by the auth provider.
+    return token.claims
+```
diff --git a/docs/v2/integrations/supabase.mdx b/docs/v2/integrations/supabase.mdx
new file mode 100644
index 0000000..94a57e0
--- /dev/null
+++ b/docs/v2/integrations/supabase.mdx
@@ -0,0 +1,148 @@
+---
+title: Supabase 🤝 FastMCP
+sidebarTitle: Supabase
+description: Secure your FastMCP server with Supabase Auth
+icon: shield-check
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.13.0" />
+
+This guide shows you how to secure your FastMCP server using **Supabase Auth**. This integration uses the [**Remote OAuth**](/v2/servers/auth/remote-oauth) pattern, where Supabase handles user authentication and your FastMCP server validates the tokens.
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+1. A **[Supabase Account](https://supabase.com/)** with a project or a self-hosted **Supabase Auth** instance
+2. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`)
+
+### Step 1: Get Supabase Project URL
+
+In your Supabase Dashboard:
+1. Go to **Project Settings**
+2. Copy your **Project URL** (e.g., `https://abc123.supabase.co`)
+
+### Step 2: FastMCP Configuration
+
+Create your FastMCP server using the `SupabaseProvider`:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.supabase import SupabaseProvider
+
+# Configure Supabase Auth
+auth = SupabaseProvider(
+    project_url="https://abc123.supabase.co",
+    base_url="http://localhost:8000",
+    auth_route="/my/auth/route" # if self-hosting and using custom routes
+)
+
+mcp = FastMCP("Supabase Protected Server", auth=auth)
+
+@mcp.tool
+def protected_tool(message: str) -> str:
+    """This tool requires authentication."""
+    return f"Authenticated user says: {message}"
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+
+## Testing
+
+### Running the Server
+
+Start your FastMCP server with HTTP transport to enable OAuth flows:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Your server is now running and protected by Supabase authentication.
+
+### Testing with a Client
+
+Create a test client that authenticates with your Supabase-protected server:
+
+```python client.py
+from fastmcp import Client
+import asyncio
+
+async def main():
+    # The client will automatically handle Supabase OAuth
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        # First-time connection will open Supabase login in your browser
+        print("✓ Authenticated with Supabase!")
+
+        # Test the protected tool
+        result = await client.call_tool("protected_tool", {"message": "Hello!"})
+        print(result)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+1. Your browser will open to Supabase's authorization page
+2. After you authorize, you'll be redirected back
+3. The client receives the token and can make authenticated requests
+
+## Environment Variables
+
+For production deployments, use environment variables instead of hardcoding credentials.
+
+### Provider Selection
+
+Setting this environment variable allows the Supabase provider to be used automatically without explicitly instantiating it in code.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH" default="Not set">
+Set to `fastmcp.server.auth.providers.supabase.SupabaseProvider` to use Supabase authentication.
+</ParamField>
+</Card>
+
+### Supabase-Specific Configuration
+
+These environment variables provide default values for the Supabase provider, whether it's instantiated manually or configured via `FASTMCP_SERVER_AUTH`.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH_SUPABASE_PROJECT_URL" required>
+Your Supabase project URL (e.g., `https://abc123.supabase.co`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_SUPABASE_BASE_URL" required>
+Public URL of your FastMCP server (e.g., `https://your-server.com` or `http://localhost:8000` for development)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_SUPABASE_AUTH_ROUTE" default="/auth/v1">
+Your Supabase auth route (e.g., `/auth/v1`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_SUPABASE_REQUIRED_SCOPES" default="[]">
+Comma-, space-, or JSON-separated list of required OAuth scopes (e.g., `openid email` or `["openid", "email"]`)
+</ParamField>
+</Card>
+
+Example `.env` file:
+```bash
+# Use the Supabase provider
+FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.supabase.SupabaseProvider
+
+# Supabase configuration
+FASTMCP_SERVER_AUTH_SUPABASE_PROJECT_URL=https://abc123.supabase.co
+FASTMCP_SERVER_AUTH_SUPABASE_BASE_URL=https://your-server.com
+FASTMCP_SERVER_AUTH_SUPABASE_REQUIRED_SCOPES=openid,email
+```
+
+With environment variables set, your server code simplifies to:
+
+```python server.py
+from fastmcp import FastMCP
+
+# Authentication is automatically configured from environment
+mcp = FastMCP(name="Supabase Protected Server")
+```
diff --git a/docs/v2/integrations/workos.mdx b/docs/v2/integrations/workos.mdx
new file mode 100644
index 0000000..b8c01a1
--- /dev/null
+++ b/docs/v2/integrations/workos.mdx
@@ -0,0 +1,288 @@
+---
+title: WorkOS 🤝 FastMCP
+sidebarTitle: WorkOS
+description: Authenticate FastMCP servers with WorkOS Connect
+icon: shield-check
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.12.0" />
+
+Secure your FastMCP server with WorkOS Connect authentication. This integration uses the OAuth Proxy pattern to handle authentication through WorkOS Connect while maintaining compatibility with MCP clients.
+
+<Note>
+This guide covers WorkOS Connect applications. For Dynamic Client Registration (DCR) with AuthKit, see the [AuthKit integration](/v2/integrations/authkit) instead.
+</Note>
+
+## Configuration
+
+### Prerequisites
+
+Before you begin, you will need:
+1. A **[WorkOS Account](https://workos.com/)** with access to create OAuth Apps
+2. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`)
+
+### Step 1: Create a WorkOS OAuth App
+
+Create an OAuth App in your WorkOS dashboard to get the credentials needed for authentication:
+
+<Steps>
+<Step title="Create OAuth Application">
+In your WorkOS dashboard:
+1. Navigate to **Applications**
+2. Click **Create Application** 
+3. Select **OAuth Application**
+4. Name your application
+</Step>
+
+<Step title="Get Credentials">
+In your OAuth application settings:
+1. Copy your **Client ID** (starts with `client_`)
+2. Click **Generate Client Secret** and save it securely
+3. Copy your **AuthKit Domain** (e.g., `https://your-app.authkit.app`)
+</Step>
+
+<Step title="Configure Redirect URI">
+In the **Redirect URIs** section:
+- Add: `http://localhost:8000/auth/callback` (for development)
+- For production, add your server's public URL + `/auth/callback`
+
+<Warning>
+The callback URL must match exactly. The default path is `/auth/callback`, but you can customize it using the `redirect_path` parameter.
+</Warning>
+</Step>
+</Steps>
+
+### Step 2: FastMCP Configuration
+
+Create your FastMCP server using the `WorkOSProvider`:
+
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.workos import WorkOSProvider
+
+# Configure WorkOS OAuth
+auth = WorkOSProvider(
+    client_id="client_YOUR_CLIENT_ID",
+    client_secret="YOUR_CLIENT_SECRET",
+    authkit_domain="https://your-app.authkit.app",
+    base_url="http://localhost:8000",
+    required_scopes=["openid", "profile", "email"]
+)
+
+mcp = FastMCP("WorkOS Protected Server", auth=auth)
+
+@mcp.tool
+def protected_tool(message: str) -> str:
+    """This tool requires authentication."""
+    return f"Authenticated user says: {message}"
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+
+## Testing
+
+### Running the Server
+
+Start your FastMCP server with HTTP transport to enable OAuth flows:
+
+```bash
+fastmcp run server.py --transport http --port 8000
+```
+
+Your server is now running and protected by WorkOS OAuth authentication.
+
+### Testing with a Client
+
+Create a test client that authenticates with your WorkOS-protected server:
+
+```python client.py
+from fastmcp import Client
+import asyncio
+
+async def main():    
+    # The client will automatically handle WorkOS OAuth
+    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
+        # First-time connection will open WorkOS login in your browser
+        print("✓ Authenticated with WorkOS!")
+        
+        # Test the protected tool
+        result = await client.call_tool("protected_tool", {"message": "Hello!"})
+        print(result)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+When you run the client for the first time:
+1. Your browser will open to WorkOS's authorization page
+2. After you authorize the app, you'll be redirected back
+3. The client receives the token and can make authenticated requests
+
+<Info>
+The client caches tokens locally, so you won't need to re-authenticate for subsequent runs unless the token expires or you explicitly clear the cache.
+</Info>
+
+## Production Configuration
+
+<VersionBadge version="2.13.0" />
+
+For production deployments with persistent token management across server restarts, configure `jwt_signing_key`, and `client_storage`:
+
+```python server.py
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.workos import WorkOSProvider
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+# Production setup with encrypted persistent token storage
+auth = WorkOSProvider(
+    client_id="client_YOUR_CLIENT_ID",
+    client_secret="YOUR_CLIENT_SECRET",
+    authkit_domain="https://your-app.authkit.app",
+    base_url="https://your-production-domain.com",
+    required_scopes=["openid", "profile", "email"],
+
+    # Production token management
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(
+            host=os.environ["REDIS_HOST"],
+            port=int(os.environ["REDIS_PORT"])
+        ),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+
+mcp = FastMCP(name="Production WorkOS App", auth=auth)
+```
+
+<Note>
+Parameters (`jwt_signing_key` and `client_storage`) work together to ensure tokens and client registrations survive server restarts. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without it, tokens are stored in plaintext. Store secrets in environment variables and use a persistent storage backend like Redis for distributed deployments.
+
+For complete details on these parameters, see the [OAuth Proxy documentation](/v2/servers/auth/oauth-proxy#configuration-parameters).
+</Note>
+
+## Environment Variables
+
+<VersionBadge version="2.12.1" />
+
+For production deployments, use environment variables instead of hardcoding credentials.
+
+### Provider Selection
+
+Setting this environment variable allows the WorkOS provider to be used automatically without explicitly instantiating it in code.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH" default="Not set">
+Set to `fastmcp.server.auth.providers.workos.WorkOSProvider` to use WorkOS authentication.
+</ParamField>
+</Card>
+
+### WorkOS-Specific Configuration
+
+These environment variables provide default values for the WorkOS provider, whether it's instantiated manually or configured via `FASTMCP_SERVER_AUTH`.
+
+<Card>
+<ParamField path="FASTMCP_SERVER_AUTH_WORKOS_CLIENT_ID" required>
+Your WorkOS OAuth App Client ID (e.g., `client_01K33Y6GGS7T3AWMPJWKW42Y3Q`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_WORKOS_CLIENT_SECRET" required>
+Your WorkOS OAuth App Client Secret
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_WORKOS_AUTHKIT_DOMAIN" required>
+Your WorkOS AuthKit domain (e.g., `https://your-app.authkit.app`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_WORKOS_BASE_URL" default="http://localhost:8000">
+Public URL where OAuth endpoints will be accessible (includes any mount path)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_WORKOS_ISSUER_URL" default="Uses BASE_URL">
+Issuer URL for OAuth metadata (defaults to `BASE_URL`). Set to root-level URL when mounting under a path prefix to avoid 404 logs. See [HTTP Deployment guide](/v2/deployment/http#mounting-authenticated-servers) for details.
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_WORKOS_REDIRECT_PATH" default="/auth/callback">
+Redirect path configured in your WorkOS OAuth App
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_WORKOS_REQUIRED_SCOPES" default="[]">
+Comma-, space-, or JSON-separated list of required OAuth scopes (e.g., `openid profile email` or `["openid","profile","email"]`)
+</ParamField>
+
+<ParamField path="FASTMCP_SERVER_AUTH_WORKOS_TIMEOUT_SECONDS" default="10">
+HTTP request timeout for WorkOS API calls
+</ParamField>
+</Card>
+
+Example `.env` file:
+```bash
+# WorkOS OAuth credentials (always used as defaults)
+FASTMCP_SERVER_AUTH_WORKOS_CLIENT_ID=client_01K33Y6GGS7T3AWMPJWKW42Y3Q
+FASTMCP_SERVER_AUTH_WORKOS_CLIENT_SECRET=your_client_secret
+FASTMCP_SERVER_AUTH_WORKOS_AUTHKIT_DOMAIN=https://your-app.authkit.app
+FASTMCP_SERVER_AUTH_WORKOS_BASE_URL=https://your-server.com
+FASTMCP_SERVER_AUTH_WORKOS_REQUIRED_SCOPES=["openid","profile","email"]
+
+# Optional: Automatically provision WorkOS auth for all servers
+FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.workos.WorkOSProvider
+```
+
+With environment variables set, you can either:
+
+**Option 1: Manual instantiation (env vars provide defaults)**
+```python server.py
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.workos import WorkOSProvider
+
+# Env vars provide default values for WorkOSProvider()
+auth = WorkOSProvider()  # Uses env var defaults
+mcp = FastMCP(name="WorkOS Protected Server", auth=auth)
+```
+
+**Option 2: Automatic provisioning (requires FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.workos.WorkOSProvider)**
+```python server.py
+from fastmcp import FastMCP
+
+# Auth is automatically provisioned from FASTMCP_SERVER_AUTH
+mcp = FastMCP(name="WorkOS Protected Server")
+```
+
+## Configuration Options
+
+<Card>
+<ParamField path="client_id" required>
+WorkOS OAuth application client ID
+</ParamField>
+
+<ParamField path="client_secret" required>
+WorkOS OAuth application client secret
+</ParamField>
+
+<ParamField path="authkit_domain" required>
+Your WorkOS AuthKit domain URL (e.g., `https://your-app.authkit.app`)
+</ParamField>
+
+<ParamField path="base_url" required>
+Your FastMCP server's public URL
+</ParamField>
+
+<ParamField path="required_scopes" default="[]">
+OAuth scopes to request
+</ParamField>
+
+<ParamField path="redirect_path" default="/auth/callback">
+OAuth callback path
+</ParamField>
+
+<ParamField path="timeout_seconds" default="10">
+API request timeout
+</ParamField>
+</Card>
\ No newline at end of file
diff --git a/docs/v2/patterns/cli.mdx b/docs/v2/patterns/cli.mdx
new file mode 100644
index 0000000..1aa9045
--- /dev/null
+++ b/docs/v2/patterns/cli.mdx
@@ -0,0 +1,577 @@
+---
+title: FastMCP CLI
+sidebarTitle: CLI
+description: Learn how to use the FastMCP command-line interface
+icon: terminal
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+
+FastMCP provides a command-line interface (CLI) that makes it easy to run, develop, and install your MCP servers. The CLI is automatically installed when you install FastMCP.
+
+```bash
+fastmcp --help
+```
+
+## Commands Overview
+
+| Command | Purpose | Dependency Management |
+| ------- | ------- | --------------------- |
+| `run` | Run a FastMCP server directly | **Supports:** Local files, factory functions, URLs, fastmcp.json configs, MCP configs. **Deps:** Uses your local environment directly. With `--python`, `--with`, `--project`, or `--with-requirements`: Runs via `uv run` subprocess. With fastmcp.json: Automatically manages dependencies based on configuration |
+| `dev` | Run a server with the MCP Inspector for testing | **Supports:** Local files and fastmcp.json configs. **Deps:** Always runs via `uv run` subprocess (never uses your local environment); dependencies must be specified or available in a uv-managed project. With fastmcp.json: Uses configured dependencies |
+| `install` | Install a server in MCP client applications | **Supports:** Local files and fastmcp.json configs. **Deps:** Creates an isolated environment; dependencies must be explicitly specified with `--with` and/or `--with-editable`. With fastmcp.json: Uses configured dependencies |
+| `inspect` | Generate a JSON report about a FastMCP server | **Supports:** Local files and fastmcp.json configs. **Deps:** Uses your current environment; you are responsible for ensuring all dependencies are available |
+| `project prepare` | Create a persistent uv project from fastmcp.json environment config | **Supports:** fastmcp.json configs only. **Deps:** Creates a uv project directory with all dependencies pre-installed for reuse with `--project` flag |
+| `version` | Display version information | N/A |
+
+## `fastmcp run`
+
+Run a FastMCP server directly or proxy a remote server.
+
+```bash
+fastmcp run server.py
+```
+
+<Tip>
+By default, this command runs the server directly in your current Python environment. You are responsible for ensuring all dependencies are available. When using `--python`, `--with`, `--project`, or `--with-requirements` options, it runs the server via `uv run` subprocess instead.
+</Tip>
+
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Transport | `--transport`, `-t` | Transport protocol to use (`stdio`, `http`, or `sse`) |
+| Host | `--host` | Host to bind to when using http transport (default: 127.0.0.1) |
+| Port | `--port`, `-p` | Port to bind to when using http transport (default: 8000) |
+| Path | `--path` | Path to bind to when using http transport (default: `/mcp/` or `/sse/` for SSE) |
+| Log Level | `--log-level`, `-l` | Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
+| No Banner | `--no-banner` | Disable the startup banner display |
+| No Environment | `--skip-env` | Skip environment setup with uv (use when already in a uv environment) |
+| Python Version | `--python` | Python version to use (e.g., 3.10, 3.11) |
+| Additional Packages | `--with` | Additional packages to install (can be used multiple times) |
+| Project Directory | `--project` | Run the command within the given project directory |
+| Requirements File | `--with-requirements` | Requirements file to install dependencies from |
+
+
+### Entrypoints
+<VersionBadge version="2.3.5" />
+
+The `fastmcp run` command supports the following entrypoints:
+
+1. **[Inferred server instance](#inferred-server-instance)**: `server.py` - imports the module and looks for a FastMCP server instance named `mcp`, `server`, or `app`. Errors if no such object is found.
+2. **[Explicit server entrypoint](#explicit-server-entrypoint)**: `server.py:custom_name` - imports and uses the specified server entrypoint  
+3. **[Factory function](#factory-function)**: `server.py:create_server` - calls the specified function (sync or async) to create a server instance
+4. **[Remote server proxy](#remote-server-proxy)**: `https://example.com/mcp-server` - connects to a remote server and creates a **local proxy server**
+5. **[FastMCP configuration file](#fastmcp-configuration)**: `fastmcp.json` - runs servers using FastMCP's declarative configuration format (auto-detects files in current directory)
+6. **MCP configuration file**: `mcp.json` - runs servers defined in a standard MCP configuration file
+
+<Warning>
+Note: When using `fastmcp run` with a local file, it **completely ignores** the `if __name__ == "__main__"` block. This means:
+- Any setup code in `__main__` will NOT run
+- Server configuration in `__main__` is bypassed  
+- `fastmcp run` finds your server entrypoint/factory and runs it with its own transport settings
+
+If you need setup code to run, use the **factory pattern** instead.
+</Warning>
+
+#### Inferred Server Instance
+
+If you provide a path to a file, `fastmcp run` will load the file and look for a FastMCP server instance stored as a variable named `mcp`, `server`, or `app`. If no such object is found, it will raise an error.
+
+For example, if you have a file called `server.py` with the following content:
+
+```python server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")
+```
+
+You can run it with:
+
+```bash
+fastmcp run server.py
+```
+
+#### Explicit Server Entrypoint
+
+If your server is stored as a variable with a custom name, or you want to be explicit about which server to run, you can use the following syntax to load a specific server entrypoint:
+
+```bash
+fastmcp run server.py:custom_name
+```
+
+For example, if you have a file called `server.py` with the following content:
+
+```python
+from fastmcp import FastMCP
+
+my_server = FastMCP("CustomServer")
+
+@my_server.tool
+def hello() -> str:
+    return "Hello from custom server!"
+```
+
+You can run it with:
+
+```bash
+fastmcp run server.py:my_server
+```
+
+#### Factory Function
+<VersionBadge version="2.11.2" />
+
+Since `fastmcp run` ignores the `if __name__ == "__main__"` block, you can use a factory function to run setup code before your server starts. Factory functions are called without any arguments and must return a FastMCP server instance. Both sync and async factory functions are supported.
+
+The syntax for using a factory function is the same as for an explicit server entrypoint: `fastmcp run server.py:factory_fn`. FastMCP will automatically detect that you have identified a function rather than a server Instance
+
+For example, if you have a file called `server.py` with the following content:
+
+```python
+from fastmcp import FastMCP
+
+async def create_server() -> FastMCP:
+    mcp = FastMCP("MyServer")
+    
+    @mcp.tool
+    def add(x: int, y: int) -> int:
+        return x + y
+    
+    # Setup that runs with fastmcp run
+    tool = await mcp.get_tool("add")
+    tool.disable()
+    
+    return mcp
+```
+
+You can run it with:
+
+```bash
+fastmcp run server.py:create_server
+```
+
+#### Remote Server Proxy
+
+FastMCP run can also start a local proxy server that connects to a remote server. This is useful when you want to run a remote server locally for testing or development purposes, or to use with a client that doesn't support direct connections to remote servers.
+
+To start a local proxy, you can use the following syntax:
+
+```bash
+fastmcp run https://example.com/mcp
+```
+
+#### FastMCP Configuration
+<VersionBadge version="2.11.4" />
+
+FastMCP supports declarative configuration through `fastmcp.json` files. When you run `fastmcp run` without arguments, it automatically looks for a `fastmcp.json` file in the current directory:
+
+```bash
+# Auto-detect fastmcp.json in current directory
+fastmcp run
+
+# Or explicitly specify a configuration file
+fastmcp run my-config.fastmcp.json
+```
+
+The configuration file handles dependencies, environment variables, and transport settings. Command-line arguments override configuration file values:
+
+```bash
+# Override port from config file
+fastmcp run fastmcp.json --port 8080
+
+# Skip environment setup when already in a uv environment
+fastmcp run fastmcp.json --skip-env
+```
+
+<Note>
+The `--skip-env` flag is useful when:
+- You're already in an activated virtual environment
+- You're inside a Docker container with pre-installed dependencies  
+- You're in a uv-managed environment (prevents infinite recursion)
+- You want to test the server without environment setup
+</Note>
+
+See [Server Configuration](/v2/deployment/server-configuration) for detailed documentation on fastmcp.json.
+
+#### MCP Configuration
+
+FastMCP can also run servers defined in a standard MCP configuration file. This is useful when you want to run multiple servers from a single file, or when you want to use a client that doesn't support direct connections to remote servers.
+
+To run a MCP configuration file, you can use the following syntax:
+
+```bash
+fastmcp run mcp.json
+```
+
+This will run all the servers defined in the file.
+
+## `fastmcp dev`
+
+Run a MCP server with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for testing.
+
+```bash
+fastmcp dev server.py
+```
+
+<Tip> 
+This command always runs your server via `uv run` subprocess (never your local environment) to work with the MCP Inspector. Dependencies can be:
+- Specified using `--with` and/or `--with-editable` options
+- Defined in a `fastmcp.json` configuration file
+- Available in a uv-managed project
+
+When using `fastmcp.json`, the dev command automatically uses the configured dependencies.
+</Tip>
+
+<Warning>
+The `dev` command is a shortcut for testing a server over STDIO only. When the Inspector launches, you may need to:
+1. Select "STDIO" from the transport dropdown
+2. Connect manually
+
+This command does not support HTTP testing. To test a server over Streamable HTTP or SSE:
+1. Start your server manually with the appropriate transport using either the command line:
+   ```bash
+   fastmcp run server.py --transport http
+   ```
+   or by setting the transport in your code:
+   ```bash
+   python server.py  # Assuming your __main__ block sets Streamable HTTP transport
+   ```
+2. Open the MCP Inspector separately and connect to your running server
+</Warning>
+
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Editable Package | `--with-editable`, `-e` | Directory containing pyproject.toml to install in editable mode |
+| Additional Packages | `--with` | Additional packages to install (can be used multiple times) |
+| Inspector Version | `--inspector-version` | Version of the MCP Inspector to use |
+| UI Port | `--ui-port` | Port for the MCP Inspector UI |
+| Server Port | `--server-port` | Port for the MCP Inspector Proxy server |
+| Python Version | `--python` | Python version to use (e.g., 3.10, 3.11) |
+| Project Directory | `--project` | Run the command within the given project directory |
+| Requirements File | `--with-requirements` | Requirements file to install dependencies from |
+
+### Entrypoints
+
+The `dev` command supports local FastMCP server files and configuration:
+
+1. **Inferred server instance**: `server.py` - imports the module and looks for a FastMCP server instance named `mcp`, `server`, or `app`. Errors if no such object is found.
+2. **Explicit server entrypoint**: `server.py:custom_name` - imports and uses the specified server entrypoint  
+3. **Factory function**: `server.py:create_server` - calls the specified function (sync or async) to create a server instance
+4. **FastMCP configuration**: `fastmcp.json` - uses FastMCP's declarative configuration (auto-detects in current directory)
+
+<Warning>
+The `dev` command **only supports local files and fastmcp.json** - no URLs, remote servers, or standard MCP configuration files.
+</Warning>
+
+**Examples**
+
+```bash
+# Run dev server with editable mode and additional packages
+fastmcp dev server.py -e . --with pandas --with matplotlib
+
+# Run dev server with fastmcp.json configuration (auto-detects)
+fastmcp dev
+
+# Run dev server with explicit fastmcp.json file
+fastmcp dev dev.fastmcp.json
+
+# Run dev server with specific Python version
+fastmcp dev server.py --python 3.11
+
+# Run dev server with requirements file
+fastmcp dev server.py --with-requirements requirements.txt
+
+# Run dev server within a specific project directory
+fastmcp dev server.py --project /path/to/project
+```
+
+## `fastmcp install`
+<VersionBadge version="2.10.3" />
+
+Install a MCP server in MCP client applications. FastMCP currently supports the following clients:
+
+- **Claude Code** - Installs via Claude Code's built-in MCP management system
+- **Claude Desktop** - Installs via direct configuration file modification
+- **Cursor** - Installs via deeplink that opens Cursor for user confirmation
+- **MCP JSON** - Generates standard MCP JSON configuration for manual use
+
+```bash
+fastmcp install claude-code server.py
+fastmcp install claude-desktop server.py
+fastmcp install cursor server.py
+fastmcp install mcp-json server.py
+```
+
+Note that for security reasons, MCP clients usually run every server in a completely isolated environment. Therefore, all dependencies must be explicitly specified using the `--with` and/or `--with-editable` options (following `uv` conventions) or by attaching them to your server in code via the `dependencies` parameter. You should not assume that the MCP server will have access to your local environment.
+
+<Warning>
+**`uv` must be installed and available in your system PATH**. Both Claude Desktop and Cursor run in isolated environments and need `uv` to manage dependencies. On macOS, install `uv` globally with Homebrew for Claude Desktop compatibility: `brew install uv`.
+</Warning>
+
+<Note>
+**Python Version Considerations**: The install commands now support the `--python` option to specify a Python version directly. You can also use `--project` to run within a specific project directory or `--with-requirements` to install dependencies from a requirements file.
+</Note>
+
+<Tip>
+**FastMCP `install` commands focus on local server files with STDIO transport.** For remote servers running with HTTP or SSE transport, use your client's native configuration - FastMCP's value is simplifying the complex local setup with dependencies and `uv` commands.
+</Tip>
+
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Server Name | `--server-name`, `-n` | Custom name for the server (defaults to server's name attribute or file name) |
+| Editable Package | `--with-editable`, `-e` | Directory containing pyproject.toml to install in editable mode |
+| Additional Packages | `--with` | Additional packages to install (can be used multiple times) |
+| Environment Variables | `--env` | Environment variables in KEY=VALUE format (can be used multiple times) |
+| Environment File | `--env-file`, `-f` | Load environment variables from a .env file |
+| Python Version | `--python` | Python version to use (e.g., 3.10, 3.11) |
+| Project Directory | `--project` | Run the command within the given project directory |
+| Requirements File | `--with-requirements` | Requirements file to install dependencies from |
+
+### Entrypoints
+
+The `install` command supports local FastMCP server files and configuration:
+
+1. **Inferred server instance**: `server.py` - imports the module and looks for a FastMCP server instance named `mcp`, `server`, or `app`. Errors if no such object is found.
+2. **Explicit server entrypoint**: `server.py:custom_name` - imports and uses the specified server entrypoint  
+3. **Factory function**: `server.py:create_server` - calls the specified function (sync or async) to create a server instance
+4. **FastMCP configuration**: `fastmcp.json` - uses FastMCP's declarative configuration with dependencies and settings
+
+<Note>
+Factory functions are particularly useful for install commands since they allow setup code to run that would otherwise be ignored when the MCP client runs your server. When using fastmcp.json, dependencies are automatically handled.
+</Note>
+
+<Warning>
+The `install` command **only supports local files and fastmcp.json** - no URLs, remote servers, or standard MCP configuration files. For remote servers, use your MCP client's native configuration.
+</Warning>
+
+**Examples**
+
+```bash
+# Auto-detects server entrypoint (looks for 'mcp', 'server', or 'app')
+fastmcp install claude-desktop server.py
+
+# Install with fastmcp.json configuration (auto-detects)
+fastmcp install claude-desktop
+
+# Install with explicit fastmcp.json file
+fastmcp install claude-desktop my-config.fastmcp.json
+
+# Uses specific server entrypoint
+fastmcp install claude-desktop server.py:my_server
+
+# With custom name and dependencies
+fastmcp install claude-desktop server.py:my_server --server-name "My Analysis Server" --with pandas
+
+# Install in Claude Code with environment variables
+fastmcp install claude-code server.py --env API_KEY=secret --env DEBUG=true
+
+# Install in Cursor with environment variables
+fastmcp install cursor server.py --env API_KEY=secret --env DEBUG=true
+
+# Install with environment file
+fastmcp install cursor server.py --env-file .env
+
+# Install with specific Python version
+fastmcp install claude-desktop server.py --python 3.11
+
+# Install with requirements file
+fastmcp install claude-code server.py --with-requirements requirements.txt
+
+# Install within a project directory
+fastmcp install cursor server.py --project /path/to/project
+
+# Generate MCP JSON configuration
+fastmcp install mcp-json server.py --name "My Server" --with pandas
+
+# Copy JSON configuration to clipboard
+fastmcp install mcp-json server.py --copy
+```
+
+### MCP JSON Generation
+
+The `mcp-json` subcommand generates standard MCP JSON configuration that can be used with any MCP-compatible client. This is useful when:
+
+- Working with MCP clients not directly supported by FastMCP
+- Creating configuration for CI/CD environments  
+- Sharing server configurations with others
+- Integration with custom tooling
+
+The generated JSON follows the standard MCP server configuration format used by Claude Desktop, VS Code, Cursor, and other MCP clients, with the server name as the root key:
+
+```json
+{
+  "server-name": {
+    "command": "uv",
+    "args": [
+      "run",
+      "--with",
+      "fastmcp",
+      "fastmcp",
+      "run",
+      "/path/to/server.py"
+    ],
+    "env": {
+      "API_KEY": "value"
+    }
+  }
+}
+```
+
+<Note>
+To use this configuration with your MCP client, you'll typically need to add it to the client's `mcpServers` object. Consult your client's documentation for any specific configuration requirements or formatting needs.
+</Note>
+
+**Options specific to mcp-json:**
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Copy to Clipboard | `--copy` | Copy configuration to clipboard instead of printing to stdout |
+
+## `fastmcp inspect`
+
+<VersionBadge version="2.9.0" />
+
+Inspect a FastMCP server to view summary information or generate a detailed JSON report.
+
+```bash
+# Show text summary
+fastmcp inspect server.py
+
+# Output FastMCP JSON to stdout
+fastmcp inspect server.py --format fastmcp
+
+# Save MCP JSON to file (format required with -o)
+fastmcp inspect server.py --format mcp -o manifest.json
+```
+
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Format | `--format`, `-f` | Output format: `fastmcp` (FastMCP-specific) or `mcp` (MCP protocol). Required when using `-o` |
+| Output File | `--output`, `-o` | Save JSON report to file instead of stdout. Requires `--format` |
+
+### Output Formats
+
+#### FastMCP Format (`--format fastmcp`)
+The default and most comprehensive format, includes all FastMCP-specific metadata:
+- Server name, instructions, and version
+- FastMCP version and MCP version
+- Tool tags and enabled status
+- Output schemas for tools
+- Annotations and custom metadata
+- Uses snake_case field names
+- **Use this for**: Complete server introspection and debugging FastMCP servers
+
+#### MCP Protocol Format (`--format mcp`)
+Shows exactly what MCP clients will see via the protocol:
+- Only includes standard MCP protocol fields
+- Matches output from `client.list_tools()`, `client.list_prompts()`, etc.
+- Uses camelCase field names (e.g., `inputSchema`)
+- Excludes FastMCP-specific fields like tags and enabled status
+- **Use this for**: Debugging client visibility and ensuring MCP compatibility
+
+### Entrypoints
+
+The `inspect` command supports local FastMCP server files and configuration:
+
+1. **Inferred server instance**: `server.py` - imports the module and looks for a FastMCP server instance named `mcp`, `server`, or `app`. Errors if no such object is found.
+2. **Explicit server entrypoint**: `server.py:custom_name` - imports and uses the specified server entrypoint  
+3. **Factory function**: `server.py:create_server` - calls the specified function (sync or async) to create a server instance
+4. **FastMCP configuration**: `fastmcp.json` - inspects servers defined with FastMCP's declarative configuration
+
+<Warning>
+The `inspect` command **only supports local files and fastmcp.json** - no URLs, remote servers, or standard MCP configuration files.
+</Warning>
+
+### Examples
+
+```bash
+# Show text summary (no JSON output)
+fastmcp inspect server.py
+# Output: 
+# Server: MyServer
+# Instructions: A helpful MCP server
+# Version: 1.0.0
+#
+# Components:
+#   Tools: 5
+#   Prompts: 2
+#   Resources: 3
+#   Templates: 1
+#
+# Environment:
+#   FastMCP: 2.0.0
+#   MCP: 1.0.0
+#
+# Use --format [fastmcp|mcp] for complete JSON output
+
+# Output FastMCP format to stdout
+fastmcp inspect server.py --format fastmcp
+
+# Specify server entrypoint
+fastmcp inspect server.py:my_server
+
+# Output MCP protocol format to stdout
+fastmcp inspect server.py --format mcp
+
+# Save to file (format required)
+fastmcp inspect server.py --format fastmcp -o server-manifest.json
+
+# Save MCP format with custom server object
+fastmcp inspect server.py:my_server --format mcp -o mcp-manifest.json
+
+# Error: format required with output file
+fastmcp inspect server.py -o output.json
+# Error: --format is required when using -o/--output
+```
+
+## `fastmcp project prepare`
+
+Create a persistent uv project directory from a fastmcp.json file's environment configuration. This allows you to pre-install all dependencies once and reuse them with the `--project` flag.
+
+```bash
+fastmcp project prepare fastmcp.json --output-dir ./env
+```
+
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Output Directory | `--output-dir` | **Required.** Directory where the persistent uv project will be created |
+
+### Usage Pattern
+
+```bash
+# Step 1: Prepare the environment (installs dependencies)
+fastmcp project prepare fastmcp.json --output-dir ./my-env
+
+# Step 2: Run using the prepared environment (fast, no dependency installation)
+fastmcp run fastmcp.json --project ./my-env
+```
+
+The prepare command creates a uv project with:
+- A `pyproject.toml` containing all dependencies from the fastmcp.json
+- A `.venv` with all packages pre-installed
+- A `uv.lock` file for reproducible environments
+
+This is useful when you want to separate environment setup from server execution, such as in deployment scenarios where dependencies are installed once and the server is run multiple times.
+
+## `fastmcp version`
+
+Display version information about FastMCP and related components.
+
+```bash
+fastmcp version
+```
+
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Copy to Clipboard | `--copy` | Copy version information to clipboard |
diff --git a/docs/v2/patterns/contrib.mdx b/docs/v2/patterns/contrib.mdx
new file mode 100644
index 0000000..04ef45a
--- /dev/null
+++ b/docs/v2/patterns/contrib.mdx
@@ -0,0 +1,45 @@
+---
+title: "Contrib Modules"
+description: "Community-contributed modules extending FastMCP"
+icon: "cubes"
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.2.1" />
+
+FastMCP includes a `contrib` package that holds community-contributed modules. These modules extend FastMCP's functionality but aren't officially maintained by the core team.
+
+Contrib modules provide additional features, integrations, or patterns that complement the core FastMCP library. They offer a way for the community to share useful extensions while keeping the core library focused and maintainable.
+
+The available modules can be viewed in the [contrib directory](https://github.com/PrefectHQ/fastmcp/tree/main/fastmcp_slim/fastmcp/contrib).
+
+## Usage
+
+To use a contrib module, import it from the `fastmcp.contrib` package:
+
+```python test="skip"
+from fastmcp.contrib import my_module
+```
+
+## Important Considerations
+
+- **Stability**: Modules in `contrib` may have different testing requirements or stability guarantees compared to the core library.
+- **Compatibility**: Changes to core FastMCP might break modules in `contrib` without explicit warnings in the main changelog.
+- **Dependencies**: Contrib modules may have additional dependencies not required by the core library. These dependencies are typically documented in the module's README or separate requirements files.
+
+## Contributing
+
+We welcome contributions to the `contrib` package! If you have a module that extends FastMCP in a useful way, consider contributing it:
+
+1. Create a new directory in `fastmcp_slim/fastmcp/contrib/` for your module
+3. Add proper tests for your module in `tests/contrib/`
+2. Include comprehensive documentation in a README.md file, including usage and examples, as well as any additional dependencies or installation instructions
+5. Submit a pull request
+
+The ideal contrib module:
+- Solves a specific use case or integration need
+- Follows FastMCP coding standards
+- Includes thorough documentation and examples
+- Has comprehensive tests
+- Specifies any additional dependencies
diff --git a/docs/v2/patterns/decorating-methods.mdx b/docs/v2/patterns/decorating-methods.mdx
new file mode 100644
index 0000000..2b48aa4
--- /dev/null
+++ b/docs/v2/patterns/decorating-methods.mdx
@@ -0,0 +1,225 @@
+---
+title: Decorating Methods
+sidebarTitle: Decorating Methods
+description: Properly use instance methods, class methods, and static methods with FastMCP decorators.
+icon: at
+---
+
+FastMCP's decorator system is designed to work with functions, but you may see unexpected behavior if you try to decorate an instance or class method. This guide explains the correct approach for using methods with all FastMCP decorators (`@tool`, `@resource`, and `@prompt`).
+
+## Why Are Methods Hard?
+
+When you apply a FastMCP decorator like `@tool`, `@resource`, or `@prompt` to a method, the decorator captures the function at decoration time. For instance methods and class methods, this poses a challenge because:
+
+1. For instance methods: The decorator gets the unbound method before any instance exists
+2. For class methods: The decorator gets the function before it's bound to the class
+
+This means directly decorating these methods doesn't work as expected. In practice, the LLM would see parameters like `self` or `cls` that it cannot provide values for.
+
+Additionally, **FastMCP decorators return objects (Tool, Resource, or Prompt instances) rather than the original function**. This means that when you decorate a method directly, the method becomes the returned object and is no longer callable by your code:
+
+<Warning>
+**Don't do this!**
+
+The method will no longer be callable from Python, and the tool won't be callable by LLMs.
+
+```python
+
+from fastmcp import FastMCP
+mcp = FastMCP()
+
+class MyClass:
+    @mcp.tool
+    def my_method(self, x: int) -> int:
+        return x * 2
+
+obj = MyClass()
+obj.my_method(5)  # Fails - my_method is a Tool, not a function
+```
+</Warning>
+
+This is another important reason to register methods functionally after defining the class.
+
+## Recommended Patterns
+
+### Instance Methods
+
+<Warning>
+**Don't do this!**
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+class MyClass:
+    @mcp.tool  # This won't work correctly
+    def add(self, x, y):
+        return x + y
+```
+</Warning>
+When the decorator is applied this way, it captures the unbound method. When the LLM later tries to use this component, it will see `self` as a required parameter, but it won't know what to provide for it, causing errors or unexpected behavior.
+
+<Check>
+**Do this instead**:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+class MyClass:
+    def add(self, x, y):
+        return x + y
+
+# Create an instance first, then register the bound methods
+obj = MyClass()
+mcp.tool(obj.add)
+
+# Now you can call it without 'self' showing up as a parameter
+await mcp._mcp_call_tool('add', {'x': 1, 'y': 2})  # Returns 3
+```
+</Check>
+
+This approach works because:
+1. You first create an instance of the class (`obj`)
+2. When you access the method through the instance (`obj.add`), Python creates a bound method where `self` is already set to that instance
+3. When you register this bound method, the system sees a callable that only expects the appropriate parameters, not `self`
+
+### Class Methods
+
+The behavior of decorating class methods depends on the order of decorators:
+
+<Warning>
+**Don't do this** (decorator order matters):
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+class MyClass:
+    @classmethod
+    @mcp.tool  # This won't work but won't raise an error
+    def from_string_v1(cls, s):
+        return cls(s)
+    
+    @mcp.tool
+    @classmethod  # This will raise a helpful ValueError
+    def from_string_v2(cls, s):
+        return cls(s)
+```
+</Warning>
+
+- If `@classmethod` comes first, then `@mcp.tool`: No error is raised, but it won't work correctly
+- If `@mcp.tool` comes first, then `@classmethod`: FastMCP will detect this and raise a helpful `ValueError` with guidance
+
+<Check>
+**Do this instead**:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+class MyClass:
+    @classmethod
+    def from_string(cls, s):
+        return cls(s)
+
+# Register the class method after the class is defined
+mcp.tool(MyClass.from_string)
+```
+</Check>
+
+This works because:
+1. The `@classmethod` decorator is applied properly during class definition
+2. When you access `MyClass.from_string`, Python provides a special method object that automatically binds the class to the `cls` parameter
+3. When registered, only the appropriate parameters are exposed to the LLM, hiding the implementation detail of the `cls` parameter
+
+### Static Methods
+
+Static methods "work" with FastMCP decorators, but this is not recommended because the FastMCP decorator will not return a callable method. Therefore, you should register static methods the same way as other methods.
+
+<Warning>
+**This is not recommended, though it will work.**
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+class MyClass:
+    @mcp.tool
+    @staticmethod
+    def utility(x, y):
+        return x + y
+```
+</Warning>
+
+This works because `@staticmethod` converts the method to a regular function, which the FastMCP decorator can then properly process. However, this is not recommended because the FastMCP decorator will not return a callable staticmethod. Therefore, you should register static methods the same way as other methods.
+
+<Check>
+**Prefer this pattern:**
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+class MyClass:
+    @staticmethod
+    def utility(x, y):
+        return x + y
+
+# This also works
+mcp.tool(MyClass.utility)
+```
+</Check>
+
+## Additional Patterns
+
+### Creating Components at Class Initialization
+
+You can automatically register instance methods when creating an object:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+class ComponentProvider:
+    def __init__(self, mcp_instance):
+        # Register methods
+        mcp_instance.tool(self.tool_method)
+        mcp_instance.resource("resource://data")(self.resource_method)
+    
+    def tool_method(self, x):
+        return x * 2
+    
+    def resource_method(self):
+        return "Resource data"
+
+# The methods are automatically registered when creating the instance
+provider = ComponentProvider(mcp)
+```
+
+This pattern is useful when:
+- You want to encapsulate registration logic within the class itself
+- You have multiple related components that should be registered together
+- You want to ensure that methods are always properly registered when creating an instance
+
+The class automatically registers its methods during initialization, ensuring they're properly bound to the instance before registration.
+
+## Summary
+
+The current behavior of FastMCP decorators with methods is:
+
+- **Static methods**: Can be decorated directly and work perfectly with all FastMCP decorators
+- **Class methods**: Cannot be decorated directly and will raise a helpful `ValueError` with guidance
+- **Instance methods**: Should be registered after creating an instance using the decorator calls
+
+For class and instance methods, you should register them after creating the instance or class to ensure proper method binding. This ensures that the methods are properly bound before being registered.
+
+
+Understanding these patterns allows you to effectively organize your components into classes while maintaining proper method binding, giving you the benefits of object-oriented design without sacrificing the simplicity of FastMCP's decorator system.
diff --git a/docs/v2/patterns/testing.mdx b/docs/v2/patterns/testing.mdx
new file mode 100644
index 0000000..7bd8600
--- /dev/null
+++ b/docs/v2/patterns/testing.mdx
@@ -0,0 +1,104 @@
+---
+title: Testing your FastMCP Server
+sidebarTitle: Testing
+description: How to test your FastMCP server.
+icon: vial
+---
+
+The best way to ensure a reliable and maintainable FastMCP Server is to test it! The FastMCP Client combined with Pytest provides a simple and powerful way to test your FastMCP servers.
+
+## Prerequisites
+
+Testing FastMCP servers requires `pytest-asyncio` to handle async test functions and fixtures. Install it as a development dependency:
+
+```bash
+pip install pytest-asyncio
+```
+
+We recommend configuring pytest to automatically handle async tests by setting the asyncio mode to `auto` in your `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+```
+
+This eliminates the need to decorate every async test with `@pytest.mark.asyncio`.
+
+## Testing with Pytest Fixtures
+
+Using Pytest Fixtures, you can wrap your FastMCP Server in a Client instance that makes interacting with your server fast and easy. This is especially useful when building your own MCP Servers and enables a tight development loop by allowing you to avoid using a separate tool like MCP Inspector during development:
+
+```python
+import pytest
+from fastmcp.client import Client
+from fastmcp.client.transports import FastMCPTransport
+
+from my_project.main import mcp
+
+@pytest.fixture
+async def main_mcp_client():
+    async with Client(transport=mcp) as mcp_client:
+        yield mcp_client
+
+async def test_list_tools(main_mcp_client: Client[FastMCPTransport]):
+    list_tools = await main_mcp_client.list_tools()
+
+    assert len(list_tools) == 5
+```
+
+We recommend the [inline-snapshot library](https://github.com/15r10nk/inline-snapshot) for asserting complex data structures coming from your MCP Server. This library allows you to write tests that are easy to read and understand, and are also easy to update when the data structure changes. 
+
+```python
+from inline_snapshot import snapshot
+
+async def test_list_tools(main_mcp_client: Client[FastMCPTransport]):
+    list_tools = await main_mcp_client.list_tools()
+
+    assert list_tools == snapshot()
+```
+
+Simply run `pytest --inline-snapshot=fix,create` to fill in the `snapshot()` with actual data.
+
+<Tip>
+For values that change you can leverage the [dirty-equals](https://github.com/samuelcolvin/dirty-equals) library to perform flexible equality assertions on dynamic or non-deterministic values.
+</Tip>
+
+Using the pytest `parametrize` decorator, you can easily test your tools with a wide variety of inputs.
+
+```python
+import pytest
+from my_project.main import mcp
+
+from fastmcp.client import Client
+from fastmcp.client.transports import FastMCPTransport
+@pytest.fixture
+async def main_mcp_client():
+    async with Client(mcp) as client:
+        yield client
+
+
+@pytest.mark.parametrize(
+    "first_number, second_number, expected",
+    [
+        (1, 2, 3),
+        (2, 3, 5),
+        (3, 4, 7),
+    ],
+)
+async def test_add(
+    first_number: int,
+    second_number: int,
+    expected: int,
+    main_mcp_client: Client[FastMCPTransport],
+):
+    result = await main_mcp_client.call_tool(
+        name="add", arguments={"x": first_number, "y": second_number}
+    )
+    assert result.data is not None
+    assert isinstance(result.data, int)
+    assert result.data == expected
+```
+
+<Tip>
+The [FastMCP Repository contains thousands of tests](https://github.com/PrefectHQ/fastmcp/tree/main/tests) for the FastMCP Client and Server. Everything from connecting to remote MCP servers, to testing tools, resources, and prompts is covered, take a look for inspiration!
+</Tip>
\ No newline at end of file
diff --git a/docs/v2/patterns/tool-transformation.mdx b/docs/v2/patterns/tool-transformation.mdx
new file mode 100644
index 0000000..0808f68
--- /dev/null
+++ b/docs/v2/patterns/tool-transformation.mdx
@@ -0,0 +1,739 @@
+---
+title: Tool Transformation
+sidebarTitle: Tool Transformation
+description: Create enhanced tool variants with modified schemas, argument mappings, and custom behavior.
+icon: wand-magic-sparkles
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.8.0" />
+
+Tool transformation allows you to create new, enhanced tools from existing ones. This powerful feature enables you to adapt tools for different contexts, simplify complex interfaces, or add custom logic without duplicating code.
+
+## Why Transform Tools?
+
+Often, an existing tool is *almost* perfect for your use case, but it might have:
+- A confusing description (or no description at all).
+- Argument names or descriptions that are not intuitive for an LLM (e.g., `q` instead of `query`).
+- Unnecessary parameters that you want to hide from the LLM.
+- A need for input validation before the original tool is called.
+- A need to modify or format the tool's output.
+
+Instead of rewriting the tool from scratch, you can **transform** it to fit your needs.
+
+## Basic Transformation
+
+The primary way to create a transformed tool is with the `Tool.from_tool()` class method. At its simplest, you can use it to change a tool's top-level metadata like its `name`, `description`, or `tags`.
+
+In the following simple example, we take a generic `search` tool and adjust its name and description to help an LLM client better understand its purpose.
+
+```python {13-21}
+from fastmcp import FastMCP
+from fastmcp.tools import Tool
+
+mcp = FastMCP()
+
+# The original, generic tool
+@mcp.tool
+def search(query: str, category: str = "all") -> list[dict]:
+    """Searches for items in the database."""
+    return database.search(query, category)
+
+# Create a more domain-specific version by changing its metadata
+product_search_tool = Tool.from_tool(
+    search,
+    name="find_products",
+    description="""
+        Search for products in the e-commerce catalog. 
+        Use this when customers ask about finding specific items, 
+        checking availability, or browsing product categories.
+        """,
+)
+
+mcp.add_tool(product_search_tool)
+```
+
+<Tip>
+When you transform a tool, the original tool remains registered on the server. To avoid confusing an LLM with two similar tools, you can disable the original one:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.tools import Tool
+
+mcp = FastMCP()
+
+# The original, generic tool
+@mcp.tool
+def search(query: str, category: str = "all") -> list[dict]:
+    ...
+
+# Create a more domain-specific version
+product_search_tool = Tool.from_tool(search, ...)
+mcp.add_tool(product_search_tool)
+
+# Disable the original tool
+search.disable()
+```
+</Tip>
+
+Now, clients see a tool named `find_products` with a clear, domain-specific purpose and relevant tags, even though it still uses the original generic `search` function's logic.
+
+### Parameters
+
+The `Tool.from_tool()` class method is the primary way to create a transformed tool. It takes the following parameters:
+
+- `tool`: The tool to transform. This is the only required argument.
+- `name`: An optional name for the new tool.
+- `description`: An optional description for the new tool.
+- `transform_args`: A dictionary of `ArgTransform` objects, one for each argument you want to modify.
+- `transform_fn`: An optional function that will be called instead of the parent tool's logic.
+- `output_schema`: Control output schema and structured outputs (see [Output Schema Control](#output-schema-control)).
+- `tags`: An optional set of tags for the new tool.
+- `annotations`: An optional set of `ToolAnnotations` for the new tool.
+- `serializer`: An optional function that will be called to serialize the result of the new tool.
+- `meta`: Control meta information for the tool. Use `None` to remove meta, any dict to set meta, or leave unset to inherit from parent.
+
+The result is a new `TransformedTool` object that wraps the parent tool and applies the transformations you specify. You can add this tool to your MCP server using its `add_tool()` method.
+
+
+
+## Modifying Arguments
+
+To modify a tool's parameters, provide a dictionary of `ArgTransform` objects to the `transform_args` parameter of `Tool.from_tool()`. Each key is the name of the *original* argument you want to modify.
+
+<Tip>
+You only need to provide a `transform_args` entry for arguments you want to modify. All other arguments will be passed through unchanged.
+</Tip>
+
+### The ArgTransform Class
+
+To modify an argument, you need to create an `ArgTransform` object. This object has the following parameters:
+
+- `name`: The new name for the argument.
+- `description`: The new description for the argument.
+- `default`: The new default value for the argument.
+- `default_factory`: A function that will be called to generate a default value for the argument. This is useful for arguments that need to be generated for each tool call, such as timestamps or unique IDs.
+- `hide`: Whether to hide the argument from the LLM.
+- `required`: Whether the argument is required, usually used to make an optional argument be required instead.
+- `type`: The new type for the argument.
+
+<Tip>
+Certain combinations of parameters are not allowed. For example, you can only use `default_factory` with `hide=True`, because dynamic defaults cannot be represented in a JSON schema for the client. You can only set required=True for arguments that do not declare a default value.
+</Tip>
+
+
+### Descriptions
+
+By far the most common reason to transform a tool, after its own description, is to improve its argument descriptions. A good description is crucial for helping an LLM understand how to use a parameter correctly. This is especially important when wrapping tools from external APIs, whose argument descriptions may be missing or written for developers, not LLMs.
+
+In this example, we add a helpful description to the `user_id` argument:
+
+```python {16-19}
+from fastmcp import FastMCP
+from fastmcp.tools import Tool
+from fastmcp.tools.tool_transform import ArgTransform
+
+mcp = FastMCP()
+
+@mcp.tool
+def find_user(user_id: str):
+    """Finds a user by their ID."""
+    ...
+
+new_tool = Tool.from_tool(
+    find_user,
+    transform_args={
+        "user_id": ArgTransform(
+            description=(
+                "The unique identifier for the user, "
+                "usually in the format 'usr-xxxxxxxx'."
+            )
+        )
+    }
+)
+```
+
+### Names
+
+At times, you may want to rename an argument to make it more intuitive for an LLM. 
+
+For example, in the following example, we take a generic `q` argument and expand it to `search_query`:
+
+```python {15}
+from fastmcp import FastMCP
+from fastmcp.tools import Tool
+from fastmcp.tools.tool_transform import ArgTransform
+
+mcp = FastMCP()
+
+@mcp.tool
+def search(q: str):
+    """Searches for items in the database."""
+    return database.search(q)
+
+new_tool = Tool.from_tool(
+    search,
+    transform_args={
+        "q": ArgTransform(name="search_query")
+    }
+)
+```
+
+### Default Values
+
+You can update the default value for any argument using the `default` parameter. Here, we change the default value of the `y` argument to 10:
+
+```python{15}
+from fastmcp import FastMCP
+from fastmcp.tools import Tool
+from fastmcp.tools.tool_transform import ArgTransform
+
+mcp = FastMCP()
+
+@mcp.tool
+def add(x: int, y: int) -> int:
+    """Adds two numbers."""
+    return x + y
+
+new_tool = Tool.from_tool(
+    add,
+    transform_args={
+        "y": ArgTransform(default=10)
+    }
+)
+```
+
+Default values are especially useful in combination with hidden arguments.
+
+### Hiding Arguments
+
+Sometimes a tool requires arguments that shouldn't be exposed to the LLM, such as API keys, configuration flags, or internal IDs. You can hide these parameters using `hide=True`. Note that you can only hide arguments that have a default value (or for which you provide a new default), because the LLM can't provide a value at call time.
+
+<Tip>
+To pass a constant value to the parent tool, combine `hide=True` with `default=<value>`.
+</Tip>
+
+```python {19-20}
+import os
+from fastmcp import FastMCP
+from fastmcp.tools import Tool
+from fastmcp.tools.tool_transform import ArgTransform
+
+mcp = FastMCP()
+
+@mcp.tool
+def send_email(to: str, subject: str, body: str, api_key: str):
+    """Sends an email."""
+    ...
+    
+# Create a simplified version that hides the API key
+new_tool = Tool.from_tool(
+    send_email,
+    name="send_notification",
+    transform_args={
+        "api_key": ArgTransform(
+            hide=True, 
+            default=os.environ.get("EMAIL_API_KEY"),
+        )
+    }
+)
+```
+The LLM now only sees the `to`, `subject`, and `body` parameters. The `api_key` is supplied automatically from an environment variable.
+
+For values that must be generated for each tool call (like timestamps or unique IDs), use `default_factory`, which is called with no arguments every time the tool is called. For example,
+
+```python {3-4}
+transform_args = {
+    'timestamp': ArgTransform(
+        hide=True,
+        default_factory=lambda: datetime.now(),
+    )
+}
+```
+
+<Warning>
+`default_factory` can only be used with `hide=True`. This is because visible parameters need static defaults that can be represented in a JSON schema for the client.
+</Warning>
+
+### Meta Information
+
+<VersionBadge version="2.11.0" />
+
+You can control meta information on transformed tools using the `meta` parameter. Meta information is additional data about the tool that doesn't affect its functionality but can be used by clients for categorization, routing, or other purposes.
+
+```python {15-17}
+from fastmcp import FastMCP
+from fastmcp.tools import Tool
+
+mcp = FastMCP()
+
+@mcp.tool
+def analyze_data(data: str) -> dict:
+    """Analyzes the provided data."""
+    return {"result": f"Analysis of {data}"}
+
+# Add custom meta information
+enhanced_tool = Tool.from_tool(
+    analyze_data,
+    name="enhanced_analyzer",
+    meta={
+        "category": "analytics",
+        "priority": "high",
+        "requires_auth": True
+    }
+)
+
+mcp.add_tool(enhanced_tool)
+```
+
+You can also remove meta information entirely:
+
+```python {6}
+# Remove meta information from parent tool
+simplified_tool = Tool.from_tool(
+    analyze_data,
+    name="simple_analyzer", 
+    meta=None  # Removes any meta information
+)
+```
+
+If you don't specify the `meta` parameter, the transformed tool inherits the parent tool's meta information.
+
+### Required Values
+
+In rare cases where you want to make an optional argument required, you can set `required=True`. This has no effect if the argument was already required.
+
+```python {3}
+transform_args = {
+    'user_id': ArgTransform(
+        required=True,
+    )
+}
+```
+
+## Modifying Tool Behavior
+
+<Warning>
+With great power comes great responsibility. Modifying tool behavior is a very advanced feature.
+</Warning>
+
+In addition to changing a tool's schema, advanced users can also modify its behavior. This is useful for adding validation logic, or for post-processing the tool's output.
+
+The `from_tool()` method takes a `transform_fn` parameter, which is an async function that replaces the parent tool's logic and gives you complete control over the tool's execution.
+
+### The Transform Function
+
+The `transform_fn` is an async function that **completely replaces** the parent tool's logic. 
+
+Critically, the transform function's arguments are used to determine the new tool's final schema. Any arguments that are not already present in the parent tool schema OR the `transform_args` will be added to the new tool's schema. Note that when `transform_args` and your function have the same argument name, the `transform_args` metadata will take precedence, if provided.
+
+```python
+async def my_custom_logic(user_input: str, max_length: int = 100) -> str:
+    # Your custom logic here - this completely replaces the parent tool
+    return f"Custom result for: {user_input[:max_length]}"
+
+Tool.from_tool(transform_fn=my_custom_logic)
+```
+
+<Tip>
+The name / docstring of the `transform_fn` are ignored. Only its arguments are used to determine the final schema.
+</Tip>
+
+### Calling the Parent Tool
+
+Most of the time, you don't want to completely replace the parent tool's behavior. Instead, you want to add validation, modify inputs, or post-process outputs while still leveraging the parent tool's core functionality. For this, FastMCP provides the special `forward()` and `forward_raw()` functions.
+
+Both `forward()` and `forward_raw()` are async functions that let you call the parent tool from within your `transform_fn`:
+
+- **`forward()`** (recommended): Automatically handles argument mapping based on your `ArgTransform` configurations. Call it with the transformed argument names.
+- **`forward_raw()`**: Bypasses all transformation and calls the parent tool directly with its original argument names. This is rarely needed unless you're doing complex argument manipulation, perhaps without `arg_transforms`.
+
+The most common transformation pattern is to validate (potentially renamed) arguments before calling the parent tool. Here's an example that validates that `x` and `y` are positive before calling the parent tool:
+<Tabs>
+<Tab title="Using forward()">
+
+In the simplest case, your parent tool and your transform function have the same arguments. You can call `forward()` with the same argument names as the parent tool:
+
+```python {15}
+from fastmcp import FastMCP
+from fastmcp.tools import Tool
+from fastmcp.tools.tool_transform import forward
+
+mcp = FastMCP()
+
+@mcp.tool
+def add(x: int, y: int) -> int:
+    """Adds two numbers."""
+    return x + y
+
+async def ensure_positive(x: int, y: int) -> int:
+    if x <= 0 or y <= 0:
+        raise ValueError("x and y must be positive")
+    return await forward(x=x, y=y)
+
+new_tool = Tool.from_tool(
+    add,
+    transform_fn=ensure_positive,
+)
+
+mcp.add_tool(new_tool)
+```
+</Tab>
+<Tab title="Using forward() with renamed args">
+
+When your transformed tool has different argument names than the parent tool, you can call `forward()` with the renamed arguments and it will automatically map the arguments to the parent tool's arguments:
+
+```python {15, 20-23}
+from fastmcp import FastMCP
+from fastmcp.tools import Tool
+from fastmcp.tools.tool_transform import forward
+
+mcp = FastMCP()
+
+@mcp.tool
+def add(x: int, y: int) -> int:
+    """Adds two numbers."""
+    return x + y
+
+async def ensure_positive(a: int, b: int) -> int:
+    if a <= 0 or b <= 0:
+        raise ValueError("a and b must be positive")
+    return await forward(a=a, b=b)
+
+new_tool = Tool.from_tool(
+    add,
+    transform_fn=ensure_positive,
+    transform_args={
+        "x": ArgTransform(name="a"),
+        "y": ArgTransform(name="b"),
+    }
+)
+
+mcp.add_tool(new_tool)
+```
+</Tab>
+<Tab title="Using forward_raw()">
+Finally, you can use `forward_raw()` to bypass all argument mapping and call the parent tool directly with its original argument names.
+
+```python {15, 20-23}
+from fastmcp import FastMCP
+from fastmcp.tools import Tool
+from fastmcp.tools.tool_transform import forward
+
+mcp = FastMCP()
+
+@mcp.tool
+def add(x: int, y: int) -> int:
+    """Adds two numbers."""
+    return x + y
+
+async def ensure_positive(a: int, b: int) -> int:
+    if a <= 0 or b <= 0:
+        raise ValueError("a and b must be positive")
+    return await forward_raw(x=a, y=b)
+
+new_tool = Tool.from_tool(
+    add,
+    transform_fn=ensure_positive,
+    transform_args={
+        "x": ArgTransform(name="a"),
+        "y": ArgTransform(name="b"),
+    }
+)
+
+mcp.add_tool(new_tool)
+```
+</Tab>
+</Tabs>
+
+### Passing Arguments with **kwargs
+
+If your `transform_fn` includes `**kwargs` in its signature, it will receive **all arguments from the parent tool after `ArgTransform` configurations have been applied**. This is powerful for creating flexible validation functions that don't require you to add every argument to the function signature.
+
+In the following example, we wrap a parent tool that accepts two arguments `x` and `y`. These are renamed to `a` and `b` in the transformed tool, and the transform only validates `a`, passing the other argument through as `**kwargs`.
+
+```python {12, 15}
+from fastmcp import FastMCP
+from fastmcp.tools import Tool
+from fastmcp.tools.tool_transform import forward, ArgTransform
+
+mcp = FastMCP()
+
+@mcp.tool
+def add(x: int, y: int) -> int:
+    """Adds two numbers."""
+    return x + y
+
+async def ensure_a_positive(a: int, **kwargs) -> int:
+    if a <= 0:
+        raise ValueError("a must be positive")
+    return await forward(a=a, **kwargs)
+
+new_tool = Tool.from_tool(
+    add,
+    transform_fn=ensure_a_positive,
+    transform_args={
+        "x": ArgTransform(name="a"),
+        "y": ArgTransform(name="b"),
+    }
+)
+
+mcp.add_tool(new_tool)
+```
+
+<Tip>
+In the above example, `**kwargs` receives the renamed argument `b`, not the original argument `y`. It is therefore recommended to use with `forward()`, not `forward_raw()`.
+</Tip>
+
+## Modifying MCP Tools with MCPConfig
+
+When running MCP Servers under FastMCP with `MCPConfig`, you can also apply a subset of tool transformations
+directly in the MCPConfig json file.
+
+```json
+{
+    "mcpServers": {
+        "weather": {
+            "url": "https://weather.example.com/mcp",
+            "transport": "http",
+            "tools": {
+                "weather_get_forecast": {
+                    "name": "miami_weather",
+                    "description": "Get the weather for Miami",
+                    "meta": {
+                        "category": "weather",
+                        "location": "miami"
+                    },
+                    "arguments": {
+                        "city": {
+                            "name": "city",
+                            "default": "Miami",
+                            "hide": True,
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+The `tools` section is a dictionary of tool names to tool configurations. Each tool configuration is a
+dictionary of tool properties.
+
+See the [MCPConfigTransport](/v2/clients/transports#tool-transformation-with-fastmcp-and-mcpconfig) documentation for more details.
+
+
+## Output Schema Control
+
+<VersionBadge version="2.10.0" />
+
+Transformed tools inherit output schemas from their parent by default, but you can control this behavior:
+
+**Inherit from Parent (Default)**
+```python
+Tool.from_tool(parent_tool, name="renamed_tool")
+```
+The transformed tool automatically uses the parent tool's output schema and structured output behavior.
+
+**Custom Output Schema**
+```python
+Tool.from_tool(parent_tool, output_schema={
+    "type": "object", 
+    "properties": {"status": {"type": "string"}}
+})
+```
+Provide your own schema that differs from the parent. The tool must return data matching this schema.
+
+**Remove Output Schema**
+```python
+Tool.from_tool(parent_tool, output_schema=None)
+```
+Removes the output schema declaration. Automatic structured content still works for object-like returns (dict, dataclass, Pydantic models) but primitive types won't be structured.
+
+**Full Control with Transform Functions**
+```python
+async def custom_output(**kwargs) -> ToolResult:
+    result = await forward(**kwargs)
+    return ToolResult(content=[...], structured_content={...})
+
+Tool.from_tool(parent_tool, transform_fn=custom_output)
+```
+Use a transform function returning `ToolResult` for complete control over both content blocks and structured outputs.
+
+## Common Patterns
+
+Tool transformation is a flexible feature that supports many powerful patterns. Here are a few common use cases to give you ideas.
+
+### Exposing Client Methods as Tools
+
+A powerful use case for tool transformation is exposing methods from existing Python clients (GitHub clients, API clients, database clients, etc.) directly as MCP tools. This pattern eliminates boilerplate wrapper functions and treats tools as annotations around client methods.
+
+**Without Tool Transformation**, you typically create wrapper functions that duplicate annotations:
+
+```python
+async def get_repository(
+    owner: Annotated[str, "The owner of the repository."],
+    repo: Annotated[str, "The name of the repository."],
+) -> Repository:
+    """Get basic information about a GitHub repository."""
+    return await github_client.get_repository(owner=owner, repo=repo)
+```
+
+**With Tool Transformation**, you can wrap the client method directly:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.tools import Tool
+from fastmcp.tools.tool_transform import ArgTransform
+
+mcp = FastMCP("GitHub Tools")
+
+# Wrap a client method directly as a tool
+get_repo_tool = Tool.from_tool(
+    tool=Tool.from_function(fn=github_client.get_repository),
+    description="Get basic information about a GitHub repository.",
+    transform_args={
+        "owner": ArgTransform(description="The owner of the repository."),
+        "repo": ArgTransform(description="The name of the repository."),
+    }
+)
+
+mcp.add_tool(get_repo_tool)
+```
+
+This pattern keeps the implementation in your client and treats the tool as an annotation layer, avoiding duplicate code.
+
+#### Hiding Client-Specific Arguments
+
+Client methods often have internal parameters (debug flags, auth tokens, rate limit settings) that shouldn't be exposed to LLMs. Use `hide=True` with a default value to handle these automatically:
+
+```python
+get_issues_tool = Tool.from_tool(
+    tool=Tool.from_function(fn=github_client.get_issues),
+    description="Get issues from a GitHub repository.",
+    transform_args={
+        "owner": ArgTransform(description="The owner of the repository."),
+        "repo": ArgTransform(description="The name of the repository."),
+        "limit": ArgTransform(description="Maximum number of issues to return."),
+        # Hide internal parameters
+        "include_debug_info": ArgTransform(hide=True, default=False),
+        "error_on_not_found": ArgTransform(hide=True, default=True),
+    }
+)
+
+mcp.add_tool(get_issues_tool)
+```
+
+The LLM only sees `owner`, `repo`, and `limit`. Internal parameters are supplied automatically.
+
+#### Reusable Argument Patterns
+
+When wrapping multiple client methods, you can define reusable argument transformations. This scales well for larger tool sets and keeps annotations consistent:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.tools import Tool
+from fastmcp.tools.tool_transform import ArgTransform
+
+mcp = FastMCP("GitHub Tools")
+
+# Define reusable argument patterns
+OWNER_ARG = ArgTransform(description="The repository owner.")
+REPO_ARG = ArgTransform(description="The repository name.")
+LIMIT_ARG = ArgTransform(description="Maximum number of items to return.")
+HIDE_ERROR = ArgTransform(hide=True, default=True)
+
+def create_github_tools(client):
+    """Create tools from GitHub client methods with shared argument patterns."""
+
+    owner_repo_args = {
+        "owner": OWNER_ARG,
+        "repo": REPO_ARG,
+    }
+
+    error_args = {
+        "error_on_not_found": HIDE_ERROR,
+    }
+
+    return [
+        Tool.from_tool(
+            tool=Tool.from_function(fn=client.get_repository),
+            description="Get basic information about a GitHub repository.",
+            transform_args={**owner_repo_args, **error_args}
+        ),
+        Tool.from_tool(
+            tool=Tool.from_function(fn=client.get_issue),
+            description="Get a specific issue from a repository.",
+            transform_args={
+                **owner_repo_args,
+                "issue_number": ArgTransform(description="The issue number."),
+                "limit_comments": LIMIT_ARG,
+                **error_args,
+            }
+        ),
+        Tool.from_tool(
+            tool=Tool.from_function(fn=client.get_pull_request),
+            description="Get a specific pull request from a repository.",
+            transform_args={
+                **owner_repo_args,
+                "pull_request_number": ArgTransform(description="The PR number."),
+                "limit_comments": LIMIT_ARG,
+                **error_args,
+            }
+        ),
+    ]
+
+# Add all tools to the server
+for tool in create_github_tools(github_client):
+    mcp.add_tool(tool)
+```
+
+This pattern provides several benefits:
+
+- **No duplicate implementation**: Logic stays in the client
+- **Consistent annotations**: Reusable argument patterns ensure consistency
+- **Easy maintenance**: Update the client, not wrapper functions
+- **Scalable**: Easily add new tools by wrapping additional client methods
+
+### Adapting Remote or Generated Tools
+This is one of the most common reasons to use tool transformation. Tools from remote MCP servers (via a [proxy](/v2/servers/proxy)) or generated from an [OpenAPI spec](/v2/integrations/openapi) are often too generic for direct use by an LLM. You can use transformation to create a simpler, more intuitive version for your specific needs.
+
+### Chaining Transformations
+You can chain transformations by using an already transformed tool as the parent for a new transformation. This lets you build up complex behaviors in layers, for example, first renaming arguments, and then adding validation logic to the renamed tool.
+
+### Context-Aware Tool Factories
+You can write functions that act as "factories," generating specialized versions of a tool for different contexts. For example, you could create a `get_my_data` tool that is specific to the currently logged-in user by hiding the `user_id` parameter and providing it automatically.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.tools import Tool, tool
+from fastmcp.tools.tool_transform import ArgTransform
+
+# A generic tool that requires a user_id
+@tool
+def get_user_data(user_id: str, query: str) -> str:
+    """Fetch data for a specific user."""
+    return f"Data for user {user_id}: {query}"
+
+
+def create_user_tool(user_id: str) -> Tool:
+    """Factory that creates a user-specific version of get_user_data."""
+    return Tool.from_tool(
+        get_user_data,
+        name="get_my_data",
+        description="Fetch your data. No need to specify a user ID.",
+        transform_args={
+            "user_id": ArgTransform(hide=True, default=user_id),
+        },
+    )
+
+
+# Create a server with a tool customized for the current user
+mcp = FastMCP("User Server")
+current_user_id = "user-123"  # e.g., from auth context
+mcp.add_tool(create_user_tool(current_user_id))
+
+# Clients see "get_my_data(query: str)" — user_id is injected automatically
+```
diff --git a/docs/v2/servers/auth/authentication.mdx b/docs/v2/servers/auth/authentication.mdx
new file mode 100644
index 0000000..c6b829b
--- /dev/null
+++ b/docs/v2/servers/auth/authentication.mdx
@@ -0,0 +1,266 @@
+---
+title: Authentication
+sidebarTitle: Overview
+description: Secure your FastMCP server with flexible authentication patterns, from simple API keys to full OAuth 2.1 integration with external identity providers.
+icon: user-shield
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.11.0" />
+
+Authentication in MCP presents unique challenges that differ from traditional web applications. MCP clients need to discover authentication requirements automatically, negotiate OAuth flows without user intervention, and work seamlessly across different identity providers. FastMCP addresses these challenges by providing authentication patterns that integrate with the MCP protocol while remaining simple to implement and deploy.
+
+<Tip>
+Authentication applies only to FastMCP's HTTP-based transports (`http` and `sse`). The STDIO transport inherits security from its local execution environment.
+</Tip>
+
+<Warning>
+**Authentication is rapidly evolving in MCP.** The specification and best practices are changing quickly. FastMCP aims to provide stable, secure patterns that adapt to these changes while keeping your code simple and maintainable.
+</Warning>
+
+## MCP Authentication Challenges
+
+Traditional web authentication assumes a human user with a browser who can interact with login forms and consent screens. MCP clients are often automated systems that need to authenticate without human intervention. This creates several unique requirements:
+
+**Automatic Discovery**: MCP clients must discover authentication requirements by examining server metadata rather than encountering login redirects.
+
+**Programmatic OAuth**: OAuth flows must work without human interaction, relying on pre-configured credentials or Dynamic Client Registration.
+
+**Token Management**: Clients need to obtain, refresh, and manage tokens automatically across multiple MCP servers.
+
+**Protocol Integration**: Authentication must integrate cleanly with MCP's transport mechanisms and error handling.
+
+These challenges mean that not all authentication approaches work well with MCP. The patterns that do work fall into three categories based on the level of authentication responsibility your server assumes.
+
+## Authentication Responsibility
+
+Authentication responsibility exists on a spectrum. Your MCP server can validate tokens created elsewhere, coordinate with external identity providers, or handle the complete authentication lifecycle internally. Each approach involves different trade-offs between simplicity, security, and control.
+
+### Token Validation
+
+Your server validates tokens but delegates their creation to external systems. This approach treats your MCP server as a pure resource server that trusts tokens signed by known issuers.
+
+Token validation works well when you already have authentication infrastructure that can issue structured tokens like JWTs. Your existing API gateway, microservices platform, or enterprise SSO system becomes the source of truth for user identity, while your MCP server focuses on its core functionality.
+
+The key insight is that token validation separates authentication (proving who you are) from authorization (determining what you can do). Your MCP server receives proof of identity in the form of a signed token and makes access decisions based on the claims within that token.
+
+This pattern excels in microservices architectures where multiple services need to validate the same tokens, or when integrating MCP servers into existing systems that already handle user authentication.
+
+### External Identity Providers
+
+Your server coordinates with established identity providers to create seamless authentication experiences for MCP clients. This approach leverages OAuth 2.0 and OpenID Connect protocols to delegate user authentication while maintaining control over authorization decisions.
+
+External identity providers handle the complex aspects of authentication: user credential verification, multi-factor authentication, account recovery, and security monitoring. Your MCP server receives tokens from these trusted providers and validates them using the provider's public keys.
+
+The MCP protocol's support for Dynamic Client Registration makes this pattern particularly powerful. MCP clients can automatically discover your authentication requirements and register themselves with your identity provider without manual configuration.
+
+This approach works best for production applications that need enterprise-grade authentication features without the complexity of building them from scratch. It scales well across multiple applications and provides consistent user experiences.
+
+### Full OAuth Implementation
+
+Your server implements a complete OAuth 2.0 authorization server, handling everything from user credential verification to token lifecycle management. This approach provides maximum control at the cost of significant complexity.
+
+Full OAuth implementation means building user interfaces for login and consent, implementing secure credential storage, managing token lifecycles, and maintaining ongoing security updates. The complexity extends beyond initial implementation to include threat monitoring, compliance requirements, and keeping pace with evolving security best practices.
+
+This pattern makes sense only when you need complete control over the authentication process, operate in air-gapped environments, or have specialized requirements that external providers cannot meet.
+
+## FastMCP Authentication Providers
+
+FastMCP translates these authentication responsibility levels into a variety of concrete classes that handle the complexities of MCP protocol integration. You can build on these classes to handle the complexities of MCP protocol integration.
+
+### TokenVerifier
+
+`TokenVerifier` provides pure token validation without OAuth metadata endpoints. This class focuses on the essential task of determining whether a token is valid and extracting authorization information from its claims.
+
+The implementation handles JWT signature verification, expiration checking, and claim extraction. It validates tokens against known issuers and audiences, ensuring that tokens intended for your server are not accepted by other systems.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+auth = JWTVerifier(
+    jwks_uri="https://your-auth-system.com/.well-known/jwks.json",
+    issuer="https://your-auth-system.com", 
+    audience="your-mcp-server"
+)
+
+mcp = FastMCP(name="Protected Server", auth=auth)
+```
+
+This example configures token validation against a JWT issuer. The `JWTVerifier` will fetch public keys from the JWKS endpoint and validate incoming tokens against those keys. Only tokens with the correct issuer and audience claims will be accepted.
+
+`TokenVerifier` works well when you control both the token issuer and your MCP server, or when integrating with existing JWT-based infrastructure.
+
+→ **Complete guide**: [Token Verification](/v2/servers/auth/token-verification)
+
+### RemoteAuthProvider
+
+`RemoteAuthProvider` enables authentication with identity providers that **support Dynamic Client Registration (DCR)**, such as Descope and WorkOS AuthKit. With DCR, MCP clients can automatically register themselves with the identity provider and obtain credentials without any manual configuration.
+
+This class combines token validation with OAuth discovery metadata. It extends `TokenVerifier` functionality by adding OAuth 2.0 protected resource endpoints that advertise your authentication requirements. MCP clients examine these endpoints to understand which identity providers you trust and how to obtain valid tokens.
+
+The key requirement is that your identity provider must support DCR - the ability for clients to dynamically register and obtain credentials. This is what enables the seamless, automated authentication flow that MCP requires.
+
+For example, the built-in `AuthKitProvider` uses WorkOS AuthKit, which fully supports DCR:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.workos import AuthKitProvider
+
+auth = AuthKitProvider(
+    authkit_domain="https://your-project.authkit.app",
+    base_url="https://your-fastmcp-server.com"
+)
+
+mcp = FastMCP(name="Enterprise Server", auth=auth)
+```
+
+This example uses WorkOS AuthKit as the external identity provider. The `AuthKitProvider` automatically configures token validation against WorkOS and provides the OAuth metadata that MCP clients need for automatic authentication.
+
+`RemoteAuthProvider` is ideal for production applications when your identity provider supports Dynamic Client Registration (DCR). This enables fully automated authentication without manual client configuration.
+
+→ **Complete guide**: [Remote OAuth](/v2/servers/auth/remote-oauth)
+
+### OAuthProxy
+
+<VersionBadge version="2.12.0" />
+
+`OAuthProxy` enables authentication with OAuth providers that **don't support Dynamic Client Registration (DCR)**, such as GitHub, Google, Azure, AWS, and most traditional enterprise identity systems.
+
+When identity providers require manual app registration and fixed credentials, `OAuthProxy` bridges the gap. It presents a DCR-compliant interface to MCP clients (accepting any registration request) while using your pre-registered credentials with the upstream provider. The proxy handles the complexity of callback forwarding, enabling dynamic client callbacks to work with providers that require fixed redirect URIs.
+
+This class solves the fundamental incompatibility between MCP's expectation of dynamic registration and traditional OAuth providers' requirement for manual app registration.
+
+For example, the built-in `GitHubProvider` extends `OAuthProxy` to work with GitHub's OAuth system:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.github import GitHubProvider
+
+auth = GitHubProvider(
+    client_id="Ov23li...",  # Your GitHub OAuth App ID
+    client_secret="abc123...",  # Your GitHub OAuth App Secret
+    base_url="https://your-server.com"
+)
+
+mcp = FastMCP(name="GitHub-Protected Server", auth=auth)
+```
+
+This example uses the GitHub provider, which extends `OAuthProxy` with GitHub-specific token validation. The proxy handles the complete OAuth flow while making GitHub's non-DCR authentication work seamlessly with MCP clients.
+
+`OAuthProxy` is essential when integrating with OAuth providers that don't support DCR. This includes most established providers like GitHub, Google, and Azure, which require manual app registration through their developer consoles.
+
+→ **Complete guide**: [OAuth Proxy](/v2/servers/auth/oauth-proxy)
+
+### OAuthProvider
+
+`OAuthProvider` implements a complete OAuth 2.0 authorization server within your MCP server. This class handles the full authentication lifecycle from user credential verification to token management.
+
+The implementation provides all required OAuth endpoints including authorization, token, and discovery endpoints. It manages client registration, user consent, and token lifecycle while integrating with your user storage and authentication logic.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import OAuthProvider
+
+auth = MyOAuthProvider(
+    user_store=your_user_database,
+    client_store=your_client_registry,
+    # Additional configuration...
+)
+
+mcp = FastMCP(name="Auth Server", auth=auth)
+```
+
+This example shows the basic structure of a custom OAuth provider. The actual implementation requires significant additional configuration for user management, client registration, and security policies.
+
+`OAuthProvider` should be used only when you have specific requirements that external providers cannot meet and the expertise to implement OAuth securely.
+
+→ **Complete guide**: [Full OAuth Server](/v2/servers/auth/full-oauth-server)
+
+## Configuration Approaches
+
+FastMCP supports both programmatic configuration for maximum flexibility and environment-based configuration for deployment simplicity.
+
+### Programmatic Configuration
+
+Programmatic configuration provides complete control over authentication settings and allows for complex initialization logic. This approach works well during development and when you need to customize authentication behavior based on runtime conditions.
+
+Authentication providers are instantiated directly in your code with their required parameters. This makes dependencies explicit and allows your IDE to provide helpful autocompletion and type checking.
+
+### Environment Configuration
+
+<VersionBadge version="2.12.1" />
+
+Environment-based configuration separates authentication settings from application code, enabling the same codebase to work across different deployment environments without modification.
+
+FastMCP automatically detects authentication configuration from environment variables when no explicit `auth` parameter is provided. The configuration system supports all authentication providers and their various options.
+
+#### Provider Configuration
+
+Authentication providers are configured by specifying the full module path to the provider class:
+
+<ParamField path="FASTMCP_SERVER_AUTH" type="string">
+The full module path to the authentication provider class. Examples:
+- `fastmcp.server.auth.providers.github.GitHubProvider` - GitHub OAuth
+- `fastmcp.server.auth.providers.google.GoogleProvider` - Google OAuth
+- `fastmcp.server.auth.providers.jwt.JWTVerifier` - JWT token verification
+- `fastmcp.server.auth.providers.workos.WorkOSProvider` - WorkOS OAuth
+- `fastmcp.server.auth.providers.workos.AuthKitProvider` - WorkOS AuthKit
+- `mycompany.auth.CustomProvider` - Your custom provider class
+</ParamField>
+
+When using providers like GitHub or Google, you'll need to set provider-specific environment variables:
+
+```bash
+# GitHub OAuth
+export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.github.GitHubProvider
+export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID="Ov23li..."
+export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET="github_pat_..."
+
+# Google OAuth
+export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.google.GoogleProvider
+export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID="123456.apps.googleusercontent.com"
+export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET="GOCSPX-..."
+```
+
+#### Provider-Specific Configuration
+
+Each provider has its own configuration options set through environment variables:
+
+```bash
+# JWT Token Verification
+export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.jwt.JWTVerifier
+export FASTMCP_SERVER_AUTH_JWT_JWKS_URI="https://auth.example.com/jwks"
+export FASTMCP_SERVER_AUTH_JWT_ISSUER="https://auth.example.com"
+export FASTMCP_SERVER_AUTH_JWT_AUDIENCE="mcp-server"
+
+# Custom Provider
+export FASTMCP_SERVER_AUTH=mycompany.auth.CustomProvider
+# Plus any environment variables your custom provider expects
+```
+
+With these environment variables set, creating an authenticated FastMCP server requires no additional configuration:
+
+```python
+from fastmcp import FastMCP
+
+# Authentication automatically configured from environment
+mcp = FastMCP(name="My Server")
+```
+
+This approach simplifies deployment pipelines and follows twelve-factor app principles for configuration management.
+
+## Choosing Your Implementation
+
+The authentication approach you choose depends on your existing infrastructure, security requirements, and operational constraints.
+
+**For OAuth providers without DCR support (GitHub, Google, Azure, AWS, most enterprise systems), use OAuth Proxy.** These providers require manual app registration through their developer consoles. OAuth Proxy bridges the gap by presenting a DCR-compliant interface to MCP clients while using your fixed credentials with the provider. The proxy's callback forwarding pattern enables dynamic client ports to work with providers that require fixed redirect URIs.
+
+**For identity providers with DCR support (Descope, WorkOS AuthKit, modern auth platforms), use RemoteAuthProvider.** These providers allow clients to dynamically register and obtain credentials without manual configuration. This enables the fully automated authentication flow that MCP is designed for, providing the best user experience and simplest implementation.
+
+**Token validation works well when you already have authentication infrastructure that issues structured tokens.** If your organization already uses JWT-based systems, API gateways, or enterprise SSO that can generate tokens, this approach integrates seamlessly while keeping your MCP server focused on its core functionality. The simplicity comes from leveraging existing investment in authentication infrastructure.
+
+**Full OAuth implementation should be avoided unless you have compelling reasons that external providers cannot address.** Air-gapped environments, specialized compliance requirements, or unique organizational constraints might justify this approach, but it requires significant security expertise and ongoing maintenance commitment. The complexity extends far beyond initial implementation to include threat monitoring, security updates, and keeping pace with evolving attack vectors.
+
+FastMCP's architecture supports migration between these approaches as your requirements evolve. You can integrate with existing token systems initially and migrate to external identity providers as your application scales, or implement custom solutions when your requirements outgrow standard patterns.
\ No newline at end of file
diff --git a/docs/v2/servers/auth/full-oauth-server.mdx b/docs/v2/servers/auth/full-oauth-server.mdx
new file mode 100644
index 0000000..eaaba6a
--- /dev/null
+++ b/docs/v2/servers/auth/full-oauth-server.mdx
@@ -0,0 +1,229 @@
+---
+title: Full OAuth Server
+sidebarTitle: Full OAuth Server
+description: Build a self-contained authentication system where your FastMCP server manages users, issues tokens, and validates them.
+icon: users-between-lines
+
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.11.0" />
+
+<Warning>
+**This is an extremely advanced pattern that most users should avoid.** Building a secure OAuth 2.1 server requires deep expertise in authentication protocols, cryptography, and security best practices. The complexity extends far beyond initial implementation to include ongoing security monitoring, threat response, and compliance maintenance.
+
+**Use [Remote OAuth](/v2/servers/auth/remote-oauth) instead** unless you have compelling requirements that external identity providers cannot meet, such as air-gapped environments or specialized compliance needs.
+</Warning>
+
+The Full OAuth Server pattern exists to support the MCP protocol specification's requirements. Your FastMCP server becomes both an Authorization Server and Resource Server, handling the complete authentication lifecycle from user login to token validation.
+
+This documentation exists for completeness - the vast majority of applications should use external identity providers instead.
+
+## OAuthProvider
+
+FastMCP provides the `OAuthProvider` abstract class that implements the OAuth 2.1 specification. To use this pattern, you must subclass `OAuthProvider` and implement all required abstract methods.
+
+<Note>
+`OAuthProvider` handles OAuth endpoints, protocol flows, and security requirements, but delegates all storage, user management, and business logic to your implementation of the abstract methods.
+</Note>
+
+## Required Implementation
+
+You must implement these abstract methods to create a functioning OAuth server:
+
+### Client Management
+
+<Card icon="code" title="Client Management Methods">
+<ParamField body="get_client" type="async method">
+  Retrieve client information by ID from your database.
+  
+  <Expandable title="Parameters">
+    <ParamField body="client_id" type="str">
+      Client identifier to look up
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="OAuthClientInformationFull | None" type="return type">
+      Client information object or `None` if client not found
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="register_client" type="async method">
+  Store new client registration information in your database.
+  
+  <Expandable title="Parameters">
+    <ParamField body="client_info" type="OAuthClientInformationFull">
+      Complete client registration information to store
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="None" type="return type">
+      No return value
+    </ParamField>
+  </Expandable>
+</ParamField>
+</Card>
+
+### Authorization Flow
+
+<Card icon="code" title="Authorization Flow Methods">
+<ParamField body="authorize" type="async method">
+  Handle authorization request and return redirect URL. Must implement user authentication and consent collection.
+  
+  <Expandable title="Parameters">
+    <ParamField body="client" type="OAuthClientInformationFull">
+      OAuth client making the authorization request
+    </ParamField>
+    <ParamField body="params" type="AuthorizationParams">
+      Authorization request parameters from the client
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="str" type="return type">
+      Redirect URL to send the client to
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="load_authorization_code" type="async method">
+  Load authorization code from storage by code string. Return `None` if code is invalid or expired.
+  
+  <Expandable title="Parameters">
+    <ParamField body="client" type="OAuthClientInformationFull">
+      OAuth client attempting to use the authorization code
+    </ParamField>
+    <ParamField body="authorization_code" type="str">
+      Authorization code string to look up
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="AuthorizationCode | None" type="return type">
+      Authorization code object or `None` if not found
+    </ParamField>
+  </Expandable>
+</ParamField>
+</Card>
+
+### Token Management
+
+<Card icon="code" title="Token Management Methods">
+<ParamField body="exchange_authorization_code" type="async method">
+  Exchange authorization code for access and refresh tokens. Must validate code and create new tokens.
+  
+  <Expandable title="Parameters">
+    <ParamField body="client" type="OAuthClientInformationFull">
+      OAuth client exchanging the authorization code
+    </ParamField>
+    <ParamField body="authorization_code" type="AuthorizationCode">
+      Valid authorization code object to exchange
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="OAuthToken" type="return type">
+      New OAuth token containing access and refresh tokens
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="load_refresh_token" type="async method">
+  Load refresh token from storage by token string. Return `None` if token is invalid or expired.
+  
+  <Expandable title="Parameters">
+    <ParamField body="client" type="OAuthClientInformationFull">
+      OAuth client attempting to use the refresh token
+    </ParamField>
+    <ParamField body="refresh_token" type="str">
+      Refresh token string to look up
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="RefreshToken | None" type="return type">
+      Refresh token object or `None` if not found
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="exchange_refresh_token" type="async method">
+  Exchange refresh token for new access/refresh token pair. Must validate scopes and token.
+  
+  <Expandable title="Parameters">
+    <ParamField body="client" type="OAuthClientInformationFull">
+      OAuth client using the refresh token
+    </ParamField>
+    <ParamField body="refresh_token" type="RefreshToken">
+      Valid refresh token object to exchange
+    </ParamField>
+    <ParamField body="scopes" type="list[str]">
+      Requested scopes for the new access token
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="OAuthToken" type="return type">
+      New OAuth token with updated access and refresh tokens
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="load_access_token" type="async method">
+  Load an access token by its token string.
+  
+  <Expandable title="Parameters">
+    <ParamField body="token" type="str">
+      The access token to verify
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="AccessToken | None" type="return type">
+      The access token object, or `None` if the token is invalid
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="revoke_token" type="async method">
+  Revoke access or refresh token, marking it as invalid in storage.
+  
+  <Expandable title="Parameters">
+    <ParamField body="token" type="AccessToken | RefreshToken">
+      Token object to revoke and mark invalid
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="None" type="return type">
+      No return value
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="verify_token" type="async method">
+  Verify bearer token for incoming requests. Return `AccessToken` if valid, `None` if invalid.
+  
+  <Expandable title="Parameters">
+    <ParamField body="token" type="str">
+      Bearer token string from incoming request
+    </ParamField>
+  </Expandable>
+  
+  <Expandable title="Returns">
+    <ParamField body="AccessToken | None" type="return type">
+      Access token object if valid, `None` if invalid or expired
+    </ParamField>
+  </Expandable>
+</ParamField>
+</Card>
+
+Each method must handle storage, validation, security, and error cases according to the OAuth 2.1 specification. The implementation complexity is substantial and requires expertise in OAuth security considerations.
+
+<Warning>
+**Security Notice:** OAuth server implementation involves numerous security considerations including PKCE, state parameters, redirect URI validation, token binding, replay attack prevention, and secure storage requirements. Mistakes can lead to serious security vulnerabilities.
+</Warning>
\ No newline at end of file
diff --git a/docs/v2/servers/auth/oauth-proxy.mdx b/docs/v2/servers/auth/oauth-proxy.mdx
new file mode 100644
index 0000000..eef3bce
--- /dev/null
+++ b/docs/v2/servers/auth/oauth-proxy.mdx
@@ -0,0 +1,616 @@
+---
+title: OAuth Proxy
+sidebarTitle: OAuth Proxy
+description: Bridge traditional OAuth providers to work seamlessly with MCP's authentication flow.
+icon: share
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+<VersionBadge version="2.12.0" />
+
+The OAuth proxy enables FastMCP servers to authenticate with OAuth providers that **don't support Dynamic Client Registration (DCR)**. This includes virtually all traditional OAuth providers: GitHub, Google, Azure, AWS, Discord, Facebook, and most enterprise identity systems. For providers that do support DCR (like Descope and WorkOS AuthKit), use [`RemoteAuthProvider`](/v2/servers/auth/remote-oauth) instead.
+
+MCP clients expect to register automatically and obtain credentials on the fly, but traditional providers require manual app registration through their developer consoles. The OAuth proxy bridges this gap by presenting a DCR-compliant interface to MCP clients while using your pre-registered credentials with the upstream provider. When a client attempts to register, the proxy returns your fixed credentials. When a client initiates authorization, the proxy handles the complexity of callback forwarding—storing the client's dynamic callback URL, using its own fixed callback with the provider, then forwarding back to the client after token exchange.
+
+This approach enables any MCP client (whether using random localhost ports or fixed URLs like Claude.ai) to authenticate with any traditional OAuth provider, all while maintaining full OAuth 2.1 and PKCE security.
+
+<Note>
+  For providers that support OIDC discovery (Auth0, Google with OIDC
+  configuration, Azure AD), consider using [`OIDC
+  Proxy`](/v2/servers/auth/oidc-proxy) for automatic configuration. OIDC Proxy
+  extends the OAuth proxy to automatically discover endpoints from the provider's
+  `/.well-known/openid-configuration` URL, simplifying setup.
+</Note>
+
+## Implementation
+
+### Provider Setup Requirements
+
+Before using the OAuth proxy, you need to register your application with your OAuth provider:
+
+1. **Register your application** in the provider's developer console (GitHub Settings, Google Cloud Console, Azure Portal, etc.)
+2. **Configure the redirect URI** as your FastMCP server URL plus your chosen callback path:
+   - Default: `https://your-server.com/auth/callback`
+   - Custom: `https://your-server.com/your/custom/path` (if you set `redirect_path`)
+   - Development: `http://localhost:8000/auth/callback`
+3. **Obtain your credentials**: Client ID and Client Secret
+4. **Note the OAuth endpoints**: Authorization URL and Token URL (usually found in the provider's OAuth documentation)
+
+<Warning>
+  The redirect URI you configure with your provider must exactly match your
+  FastMCP server's URL plus the callback path. If you customize `redirect_path`
+  in the OAuth proxy, update your provider's redirect URI accordingly.
+</Warning>
+
+### Basic Setup
+
+Here's how to implement the OAuth proxy with any provider:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import OAuthProxy
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+# Configure token verification for your provider
+# See the Token Verification guide for provider-specific setups
+token_verifier = JWTVerifier(
+    jwks_uri="https://your-provider.com/.well-known/jwks.json",
+    issuer="https://your-provider.com",
+    audience="your-app-id"
+)
+
+# Create the OAuth proxy
+auth = OAuthProxy(
+    # Provider's OAuth endpoints (from their documentation)
+    upstream_authorization_endpoint="https://provider.com/oauth/authorize",
+    upstream_token_endpoint="https://provider.com/oauth/token",
+
+    # Your registered app credentials
+    upstream_client_id="your-client-id",
+    upstream_client_secret="your-client-secret",
+
+    # Token validation (see Token Verification guide)
+    token_verifier=token_verifier,
+
+    # Your FastMCP server's public URL
+    base_url="https://your-server.com",
+
+    # Optional: customize the callback path (default is "/auth/callback")
+    # redirect_path="/custom/callback",
+)
+
+mcp = FastMCP(name="My Server", auth=auth)
+```
+
+### Configuration Parameters
+
+<Card icon="code" title="OAuthProxy Parameters">
+<ParamField body="upstream_authorization_endpoint" type="str" required>
+  URL of your OAuth provider's authorization endpoint (e.g., `https://github.com/login/oauth/authorize`)
+</ParamField>
+
+<ParamField body="upstream_token_endpoint" type="str" required>
+  URL of your OAuth provider's token endpoint (e.g.,
+  `https://github.com/login/oauth/access_token`)
+</ParamField>
+
+<ParamField body="upstream_client_id" type="str" required>
+  Client ID from your registered OAuth application
+</ParamField>
+
+<ParamField body="upstream_client_secret" type="str" required>
+  Client secret from your registered OAuth application
+</ParamField>
+
+<ParamField body="token_verifier" type="TokenVerifier" required>
+  A [`TokenVerifier`](/v2/servers/auth/token-verification) instance to validate the
+  provider's tokens
+</ParamField>
+
+<ParamField body="base_url" type="AnyHttpUrl | str" required>
+  Public URL where OAuth endpoints will be accessible, **including any mount path** (e.g., `https://your-server.com/api`).
+
+  This URL is used to construct OAuth callback URLs and operational endpoints. When mounting under a path prefix, include that prefix in `base_url`. Use `issuer_url` separately to specify where auth server metadata is located (typically at root level).
+</ParamField>
+
+<ParamField body="resource_base_url" type="AnyHttpUrl | str | None">
+  Optional public base URL for the protected resource metadata and token audience.
+
+  Use this when your OAuth callbacks and operational endpoints need to live under one public URL, but the protected MCP resource should be advertised under another. FastMCP will still append the MCP mount path (for example, `/mcp`) to this base URL.
+</ParamField>
+
+<ParamField body="redirect_path" type="str" default="/auth/callback">
+  Path for OAuth callbacks. Must match the redirect URI configured in your OAuth
+  application
+</ParamField>
+
+<ParamField body="upstream_revocation_endpoint" type="str | None">
+  Optional URL of provider's token revocation endpoint
+</ParamField>
+
+<ParamField body="issuer_url" type="AnyHttpUrl | str | None">
+  Issuer URL for OAuth authorization server metadata (defaults to `base_url`).
+
+  When `issuer_url` has a path component (either explicitly or by defaulting from `base_url`), FastMCP creates path-aware discovery routes per RFC 8414. For example, if `base_url` is `http://localhost:8000/api`, the authorization server metadata will be at `/.well-known/oauth-authorization-server/api`.
+
+  **Default behavior (recommended for most cases):**
+  ```python
+  auth = GitHubProvider(
+      base_url="http://localhost:8000/api",  # OAuth endpoints under /api
+      # issuer_url defaults to base_url - path-aware discovery works automatically
+  )
+  ```
+
+  **When to set explicitly:**
+  Set `issuer_url` to root level only if you want multiple MCP servers to share a single discovery endpoint:
+  ```python
+  auth = GitHubProvider(
+      base_url="http://localhost:8000/api",
+      issuer_url="http://localhost:8000"  # Shared root-level discovery
+  )
+  ```
+
+  See the [HTTP Deployment guide](/v2/deployment/http#mounting-authenticated-servers) for complete mounting examples.
+</ParamField>
+
+<ParamField body="service_documentation_url" type="AnyHttpUrl | str | None">
+  Optional URL to your service documentation
+</ParamField>
+
+<ParamField body="forward_pkce" type="bool" default="True">
+  Whether to forward PKCE (Proof Key for Code Exchange) to the upstream OAuth
+  provider. When enabled and the client uses PKCE, the proxy generates its own
+  PKCE parameters to send upstream while separately validating the client's
+  PKCE. This ensures end-to-end PKCE security at both layers (client-to-proxy
+  and proxy-to-upstream). - `True` (default): Forward PKCE for providers that
+  support it (Google, Azure, AWS, GitHub, etc.) - `False`: Disable only if upstream
+  provider doesn't support PKCE
+</ParamField>
+
+<ParamField body="token_endpoint_auth_method" type="str | None">
+  Token endpoint authentication method for the upstream OAuth server. Controls
+  how the proxy authenticates when exchanging authorization codes and refresh
+  tokens with the upstream provider. - `"client_secret_basic"`: Send credentials
+  in Authorization header (most common) - `"client_secret_post"`: Send
+  credentials in request body (required by some providers) - `"none"`: No
+  authentication (for public clients) - `None` (default): Uses authlib's default
+  (typically `"client_secret_basic"`) Set this if your provider requires a
+  specific authentication method and the default doesn't work.
+</ParamField>
+
+<ParamField body="allowed_client_redirect_uris" type="list[str] | None">
+  List of allowed redirect URI patterns for MCP clients. Patterns support
+  wildcards (e.g., `"http://localhost:*"`, `"https://*.example.com/*"`). -
+  `None` (default): All redirect URIs allowed (for MCP/DCR compatibility) -
+  Empty list `[]`: No redirect URIs allowed - Custom list: Only matching
+  patterns allowed These patterns apply to MCP client loopback redirects, NOT
+  the upstream OAuth app redirect URI.
+</ParamField>
+
+<ParamField body="valid_scopes" type="list[str] | None">
+  List of all possible valid scopes for the OAuth provider. These are advertised
+  to clients through the `/.well-known` endpoints. Defaults to `required_scopes`
+  from your TokenVerifier if not specified.
+</ParamField>
+
+<ParamField body="extra_authorize_params" type="dict[str, str] | None">
+  Additional parameters to forward to the upstream authorization endpoint. Useful for provider-specific parameters that aren't part of the standard OAuth2 flow.
+  
+  For example, Auth0 requires an `audience` parameter to issue JWT tokens:
+  ```python
+  extra_authorize_params={"audience": "https://api.example.com"}
+  ```
+  
+  These parameters are added to every authorization request sent to the upstream provider.
+</ParamField>
+
+<ParamField body="extra_token_params" type="dict[str, str] | None">
+  Additional parameters to forward to the upstream token endpoint during code exchange and token refresh. Useful for provider-specific requirements during token operations.
+
+For example, some providers require additional context during token exchange:
+
+```python
+extra_token_params={"audience": "https://api.example.com"}
+```
+
+These parameters are included in all token requests to the upstream provider.
+
+</ParamField>
+
+<ParamField body="client_storage" type="AsyncKeyValue | None">
+
+<VersionBadge version="2.13.0" />
+  Storage backend for persisting OAuth client registrations and upstream tokens.
+
+  **Default behavior:**
+  By default, clients are automatically persisted to an encrypted disk store, allowing them to survive server restarts as long as the filesystem remains accessible. This means MCP clients only need to register once and can reconnect seamlessly. The disk store is encrypted using a key derived from the JWT Signing Key (which is derived from the upstream client secret by default). For client registrations to survive upstream client secret rotation, you should provide a JWT Signing Key or your own client_storage.
+
+For production deployments with multiple servers or cloud deployments, see [Storage Backends](/v2/servers/storage-backends) for available options.
+
+<Warning>
+  **When providing custom storage**, wrap it in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest:
+
+  ```python
+  from key_value.aio.stores.redis import RedisStore
+  from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+  from cryptography.fernet import Fernet
+  import os
+
+  auth = OAuthProxy(
+      ...,
+      jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+      client_storage=FernetEncryptionWrapper(
+          key_value=RedisStore(host="redis.example.com", port=6379),
+          fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+      )
+  )
+  ```
+
+  Without encryption, upstream OAuth tokens are stored in plaintext.
+</Warning>
+
+Testing with in-memory storage (unencrypted):
+
+```python
+from key_value.aio.stores.memory import MemoryStore
+
+# Use in-memory storage for testing (clients lost on restart)
+auth = OAuthProxy(..., client_storage=MemoryStore())
+```
+
+</ParamField>
+
+<ParamField body="jwt_signing_key" type="str | bytes | None">
+
+<VersionBadge version="2.13.0" />
+  Secret used to sign FastMCP JWT tokens issued to clients. Accepts any string or bytes - will be derived into a proper 32-byte cryptographic key using HKDF.
+
+  **Default behavior (`None`):**
+  Derives a 32-byte key using PBKDF2 from the upstream client secret.
+
+  **For production:**
+  Provide an explicit secret (e.g., from environment variable) to use a fixed key instead of the key derived from the upstream client secret. This allows you to manage keys securely in cloud environments, allows keys to work across multiple instances, and allows you to rotate keys without losing client registrations.
+
+  ```python
+  import os
+
+  auth = OAuthProxy(
+      ...,
+      jwt_signing_key=os.environ["JWT_SIGNING_KEY"],  # Any sufficiently complex string!
+      client_storage=RedisStore(...)  # Persistent storage
+  )
+  ```
+
+  See [HTTP Deployment - OAuth Token Security](/v2/deployment/http#oauth-token-security) for complete production setup.
+</ParamField>
+
+
+<ParamField body="require_authorization_consent" type='bool | Literal["remember", "external"]' default="True">
+  Consent screen behavior for authorization requests. The consent page displays which client is requesting access, defending against [confused deputy and AS-in-the-middle attacks](#confused-deputy-attacks) by requiring explicit user approval.
+
+  **`True` (default) — always prompt:**
+  Users see the consent screen on every authorization. Strongest protection against AS-in-the-middle attacks where a malicious MCP server redirects the victim's browser into a legitimate proxy and relies on a previously-remembered approval to silently complete the flow.
+
+  **`"remember"` — silent consent on return:**
+  Users see the consent screen on first authorization; subsequent flows from the same browser for the same `(client_id, redirect_uri)` are silently approved via a signed cookie. Cross-site navigations (detected via `Sec-Fetch-Site`) fall back to the prompt. `Sec-Fetch-Site` is a browser-level heuristic rather than a protocol guarantee: an attacker who finds a way to initiate a non-cross-site navigation (XSS on a sibling origin, a same-site redirect chain, etc.) can reach the silent-consent path. `True` does not depend on this signal. See [Confused Deputy Attacks](#confused-deputy-attacks) for the underlying attack class.
+
+  **`"external"` — delegate to upstream:**
+  Skip the built-in consent page; consent is collected by the upstream IdP or a custom login page referenced via `upstream_authorization_endpoint`. No security warning is logged.
+
+  **`False` — disable entirely:**
+  Authorization proceeds directly to the upstream provider without any consent UI. Logs a security warning. Only for local development or testing.
+
+  ```python
+  # Development/testing only - skip consent screen
+  auth = OAuthProxy(
+      ...,
+      require_authorization_consent=False  # ⚠️ Security warning: only for local/testing
+  )
+
+  # Convenience mode - silent consent on return visits (less safe than True)
+  auth = OAuthProxy(
+      ...,
+      require_authorization_consent="remember",
+  )
+  ```
+
+  <Warning>
+    Disabling consent removes an important security layer. Only disable for local development or testing environments where you fully control all connecting clients.
+  </Warning>
+</ParamField>
+
+<ParamField body="consent_csp_policy" type="str | None" default="None">
+  Content Security Policy for the consent page.
+
+  - `None` (default): Uses the built-in CSP policy with appropriate directives for form submission
+  - Empty string `""`: Disables CSP entirely (no meta tag rendered)
+  - Custom string: Uses the provided value as the CSP policy
+
+  This is useful for organizations that have their own CSP policies and need to override or disable FastMCP's built-in CSP directives.
+
+  ```python
+  # Disable CSP entirely (let org CSP policies apply)
+  auth = OAuthProxy(..., consent_csp_policy="")
+
+  # Use custom CSP policy
+  auth = OAuthProxy(..., consent_csp_policy="default-src 'self'; style-src 'unsafe-inline'")
+  ```
+</ParamField>
+</Card>
+
+### Using Built-in Providers
+
+FastMCP includes pre-configured providers for common services:
+
+```python
+from fastmcp.server.auth.providers.github import GitHubProvider
+
+auth = GitHubProvider(
+    client_id="your-github-app-id",
+    client_secret="your-github-app-secret",
+    base_url="https://your-server.com"
+)
+
+mcp = FastMCP(name="My Server", auth=auth)
+```
+
+Available providers include `GitHubProvider`, `GoogleProvider`, and others. These handle token verification automatically.
+
+### Token Verification
+
+The OAuth proxy requires a compatible `TokenVerifier` to validate tokens from your provider. Different providers use different token formats:
+
+- **JWT tokens** (Google, Azure): Use `JWTVerifier` with the provider's JWKS endpoint
+- **Opaque tokens with RFC 7662 introspection** (Auth0, Okta, WorkOS): Use `IntrospectionTokenVerifier`
+- **Opaque tokens (provider-specific)** (GitHub, Discord): Use provider-specific verifiers like `GitHubTokenVerifier`
+
+See the [Token Verification guide](/v2/servers/auth/token-verification) for detailed setup instructions for your provider.
+
+### Scope Configuration
+
+OAuth scopes control what permissions your application requests from users. They're configured through your `TokenVerifier` (required for the OAuth proxy to validate tokens from your provider). Set `required_scopes` to automatically request the permissions your application needs:
+
+```python
+JWTVerifier(..., required_scopes = ["read:user", "write:data"])
+```
+
+Dynamic clients created by the proxy will automatically include these scopes in their authorization requests. See the [Token Verification](#token-verification) section below for detailed setup.
+
+### Custom Parameters
+
+Some OAuth providers require additional parameters beyond the standard OAuth2 flow. Use `extra_authorize_params` and `extra_token_params` to pass provider-specific requirements. For example, Auth0 requires an `audience` parameter to issue JWT tokens instead of opaque tokens:
+
+```python
+auth = OAuthProxy(
+    upstream_authorization_endpoint="https://your-domain.auth0.com/authorize",
+    upstream_token_endpoint="https://your-domain.auth0.com/oauth/token",
+    upstream_client_id="your-auth0-client-id",
+    upstream_client_secret="your-auth0-client-secret",
+
+    # Auth0-specific audience parameter
+    extra_authorize_params={"audience": "https://your-api-identifier.com"},
+    extra_token_params={"audience": "https://your-api-identifier.com"},
+
+    token_verifier=JWTVerifier(
+        jwks_uri="https://your-domain.auth0.com/.well-known/jwks.json",
+        issuer="https://your-domain.auth0.com/",
+        audience="https://your-api-identifier.com"
+    ),
+    base_url="https://your-server.com"
+)
+```
+
+The proxy also automatically forwards RFC 8707 `resource` parameters from MCP clients to upstream providers that support them.
+
+## OAuth Flow
+
+```mermaid
+sequenceDiagram
+    participant Client as MCP Client<br/>(localhost:random)
+    participant User as User
+    participant Proxy as FastMCP OAuth Proxy<br/>(server:8000)
+    participant Provider as OAuth Provider<br/>(GitHub, etc.)
+
+    Note over Client, Proxy: Dynamic Registration (Local)
+    Client->>Proxy: 1. POST /register<br/>redirect_uri: localhost:54321/callback
+    Proxy-->>Client: 2. Returns fixed upstream credentials
+
+    Note over Client, User: Authorization with User Consent
+    Client->>Proxy: 3. GET /authorize<br/>redirect_uri=localhost:54321/callback<br/>code_challenge=CLIENT_CHALLENGE
+    Note over Proxy: Store transaction with client PKCE<br/>Generate proxy PKCE pair
+    Proxy->>User: 4. Show consent page<br/>(client details, redirect URI, scopes)
+    User->>Proxy: 5. Approve/deny consent
+    Proxy->>Provider: 6. Redirect to provider<br/>redirect_uri=server:8000/auth/callback<br/>code_challenge=PROXY_CHALLENGE
+
+    Note over Provider, Proxy: Provider Callback
+    Provider->>Proxy: 7. GET /auth/callback<br/>with authorization code
+    Proxy->>Provider: 8. Exchange code for tokens<br/>code_verifier=PROXY_VERIFIER
+    Provider-->>Proxy: 9. Access & refresh tokens
+
+    Note over Proxy, Client: Client Callback Forwarding
+    Proxy->>Client: 10. Redirect to localhost:54321/callback<br/>with new authorization code
+
+    Note over Client, Proxy: Token Exchange
+    Client->>Proxy: 11. POST /token with code<br/>code_verifier=CLIENT_VERIFIER
+    Proxy-->>Client: 12. Returns stored provider tokens
+```
+
+The flow diagram above illustrates the complete OAuth proxy pattern. Let's understand each phase:
+
+### Registration Phase
+
+When an MCP client calls `/register` with its dynamic callback URL, the proxy responds with your pre-configured upstream credentials. The client stores these credentials believing it has registered a new app. Meanwhile, the proxy records the client's callback URL for later use.
+
+### Authorization Phase
+
+The client initiates OAuth by redirecting to the proxy's `/authorize` endpoint. The proxy:
+
+1. Stores the client's transaction with its PKCE challenge
+2. Generates its own PKCE parameters for upstream security
+3. Shows the user a consent page with the client's details, redirect URI, and requested scopes
+4. If the user approves (or the client was previously approved), redirects to the upstream provider using the fixed callback URL
+
+This dual-PKCE approach maintains end-to-end security at both the client-to-proxy and proxy-to-provider layers. The consent step protects against confused deputy attacks by ensuring you explicitly approve each client before it can complete authorization.
+
+### Callback Phase
+
+After user authorization, the provider redirects back to the proxy's fixed callback URL. The proxy:
+
+1. Exchanges the authorization code for tokens with the provider
+2. Stores these tokens temporarily
+3. Generates a new authorization code for the client
+4. Redirects to the client's original dynamic callback URL
+
+### Token Exchange Phase
+
+Finally, the client exchanges its authorization code with the proxy to receive the provider's tokens. The proxy validates the client's PKCE verifier before returning the stored tokens.
+
+This entire flow is transparent to the MCP client—it experiences a standard OAuth flow with dynamic registration, unaware that a proxy is managing the complexity behind the scenes.
+
+### Token Architecture
+
+The OAuth proxy implements a **token factory pattern**: instead of directly forwarding tokens from the upstream OAuth provider, it issues its own JWT tokens to MCP clients. This maintains proper OAuth 2.0 token audience boundaries and enables better security controls.
+
+**How it works:**
+
+When an MCP client completes authorization, the proxy:
+
+1. **Receives upstream tokens** from the OAuth provider (GitHub, Google, etc.)
+2. **Encrypts and stores** these tokens using Fernet encryption (AES-128-CBC + HMAC-SHA256)
+3. **Issues FastMCP JWT tokens** to the client, signed with HS256
+
+The FastMCP JWT contains minimal claims: issuer, audience, client ID, scopes, expiration, and a unique token identifier (JTI). The JTI acts as a reference linking to the encrypted upstream token.
+
+**Token validation:**
+
+When a client makes an MCP request with its FastMCP token:
+
+1. **FastMCP validates the JWT** signature, expiration, issuer, and audience
+2. **Looks up the upstream token** using the JTI from the validated JWT
+3. **Decrypts and validates** the upstream token with the provider
+
+This two-tier validation ensures that FastMCP tokens can only be used with this server (via audience validation) while maintaining full upstream token security.
+
+**Token expiry alignment:**
+
+FastMCP token lifetimes match the upstream token lifetimes. When the upstream token expires, the FastMCP token also expires, maintaining consistent security boundaries.
+
+**Refresh tokens:**
+
+The proxy issues its own refresh tokens that map to upstream refresh tokens. When a client uses a FastMCP refresh token, the proxy refreshes the upstream token and issues a new FastMCP access token.
+
+### PKCE Forwarding
+
+The OAuth proxy automatically handles PKCE (Proof Key for Code Exchange) when working with providers that support or require it. The proxy generates its own PKCE parameters to send upstream while separately validating the client's PKCE, ensuring end-to-end security at both layers.
+
+This is enabled by default via the `forward_pkce` parameter and works seamlessly with providers like Google, Azure AD, and GitHub. Only disable it for legacy providers that don't support PKCE:
+
+```python
+# Disable PKCE forwarding only if upstream doesn't support it
+auth = OAuthProxy(
+    ...,
+    forward_pkce=False  # Default is True
+)
+```
+
+### Redirect URI Validation
+
+While the OAuth proxy accepts all redirect URIs by default (for DCR compatibility), you can restrict which clients can connect by specifying allowed patterns:
+
+```python
+# Allow only localhost clients (common for development)
+auth = OAuthProxy(
+    # ... other parameters ...
+    allowed_client_redirect_uris=[
+        "http://localhost:*",
+        "http://127.0.0.1:*"
+    ]
+)
+
+# Allow specific known clients
+auth = OAuthProxy(
+    # ... other parameters ...
+    allowed_client_redirect_uris=[
+        "http://localhost:*",
+        "https://claude.ai/api/mcp/auth_callback",
+        "https://*.mycompany.com/auth/*"  # Wildcard patterns supported
+    ]
+)
+```
+
+Check your server logs for "Client registered with redirect_uri" messages to identify what URLs your clients use.
+
+## Security
+
+### Key and Storage Management
+
+<VersionBadge version="2.13.0" />
+The OAuth proxy requires cryptographic keys for JWT signing and storage encryption, plus persistent storage to maintain valid tokens across server restarts.
+
+**Default behavior (appropriate for development only):**
+- **Mac/Windows**: FastMCP automatically generates keys and stores them in your system keyring. Storage defaults to disk. Tokens survive server restarts. This is **only** suitable for development and local testing.
+- **Linux**: Keys are ephemeral (random salt at startup). Storage defaults to memory. Tokens become invalid on server restart.
+
+**For production:**
+Configure the following parameters together: provide a unique `jwt_signing_key` (for signing FastMCP JWTs), and a shared `client_storage` backend (for storing tokens). Both are required for production deployments. Use a network-accessible storage backend like Redis or DynamoDB rather than local disk storage. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** (see the `client_storage` parameter documentation above for examples). The keys accept any secret string and derive proper cryptographic keys using HKDF. See [OAuth Token Security](/v2/deployment/http#oauth-token-security) and [Storage Backends](/v2/servers/storage-backends) for complete production setup.
+
+### Confused Deputy Attacks
+
+<VersionBadge version="2.13.0" />
+
+A confused deputy attack allows a malicious client to steal your authorization by tricking you into granting it access under your identity.
+
+The OAuth proxy works by bridging DCR clients to traditional auth providers, which means that multiple MCP clients connect through a single upstream OAuth application. An attacker can exploit this shared application by registering a malicious client with their own redirect URI, then sending you an authorization link. When you click it, your browser goes through the OAuth flow—but since you may have already authorized this OAuth app before, the provider might auto-approve the request. The authorization code then gets sent to the attacker's redirect URI instead of a legitimate client, giving them access under your credentials.
+
+#### Mitigation
+
+FastMCP's OAuth proxy requires you to explicitly consent whenever a client attempts to connect to your server. Before any authorization happens, you see a consent page showing the client's details, redirect URI, and requested scopes. This gives you the opportunity to review and deny suspicious requests. By default (`require_authorization_consent=True`), the page is shown on every flow, which is the strongest protection. Setting `require_authorization_consent="remember"` approves previously-approved `(client_id, redirect_uri)` pairs silently on return visits, trading some protection for UX (see below). The consent mechanism is implemented with CSRF tokens and cryptographically signed cookies to prevent tampering.
+
+![](/assets/images/oauth-proxy-consent-screen.png)
+
+The consent page automatically displays your server's name, icon, and website URL, if available. These visual identifiers help users confirm they're authorizing the correct server.
+
+#### AS-in-the-middle variant
+
+A related attack works by positioning a malicious authorization server between an MCP client and a legitimate proxy: a malicious MCP server advertises its own authorization server, which redirects the victim's browser into the legitimate proxy's `/authorize` endpoint. Because the victim's browser carries the prior-approval cookie throughout, a `"remember"`-mode proxy would silently complete the flow. The defense is the consent prompt itself: if consent is shown (`require_authorization_consent=True`), the victim sees the benign MCP server's name on the consent page — which doesn't match the malicious server they thought they were connecting to — and can deny.
+
+`require_authorization_consent="remember"` adds a `Sec-Fetch-Site` check to keep this path safe for legitimate return flows (the attack navigation lands as `cross-site` and falls back to the prompt), but this is a browser-level heuristic. For the strongest defense, leave `require_authorization_consent=True`.
+
+**Learn more:**
+- [MCP Security Best Practices](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#confused-deputy-problem) - Official specification guidance
+- [Confused Deputy Attacks Explained](https://den.dev/blog/mcp-confused-deputy-api-management/) - Detailed walkthrough by Den Delimarsky
+
+## Environment Configuration
+
+<VersionBadge version="2.12.1" />
+
+For production deployments, configure the OAuth proxy through environment variables instead of hardcoding credentials:
+
+```bash
+# Specify the provider implementation
+export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.github.GitHubProvider
+
+# Provider-specific credentials
+export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID="Ov23li..."
+export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET="abc123..."
+export FASTMCP_SERVER_AUTH_GITHUB_BASE_URL="https://your-production-server.com"
+```
+
+With environment configuration, your server code simplifies to:
+
+```python
+from fastmcp import FastMCP
+
+# Authentication automatically configured from environment
+mcp = FastMCP(name="My Server")
+
+@mcp.tool
+def protected_tool(data: str) -> str:
+    """This tool is now protected by OAuth."""
+    return f"Processed: {data}"
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
diff --git a/docs/v2/servers/auth/oidc-proxy.mdx b/docs/v2/servers/auth/oidc-proxy.mdx
new file mode 100644
index 0000000..7502982
--- /dev/null
+++ b/docs/v2/servers/auth/oidc-proxy.mdx
@@ -0,0 +1,275 @@
+---
+title: OIDC Proxy
+sidebarTitle: OIDC Proxy
+description: Bridge OIDC providers to work seamlessly with MCP's authentication flow.
+icon: share
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+<VersionBadge version="2.12.4" />
+
+The OIDC proxy enables FastMCP servers to authenticate with OIDC providers that **don't support Dynamic Client Registration (DCR)** out of the box. This includes OAuth providers like: Auth0, Google, Azure, AWS, etc. For providers that do support DCR (like WorkOS AuthKit), use [`RemoteAuthProvider`](/v2/servers/auth/remote-oauth) instead.
+
+The OIDC proxy is built upon [`OAuthProxy`](/v2/servers/auth/oauth-proxy) so it has all the same functionality under the covers.
+
+## Implementation
+
+### Provider Setup Requirements
+
+Before using the OIDC proxy, you need to register your application with your OAuth provider:
+
+1. **Register your application** in the provider's developer console (Auth0 Applications, Google Cloud Console, Azure Portal, etc.)
+2. **Configure the redirect URI** as your FastMCP server URL plus your chosen callback path:
+   - Default: `https://your-server.com/auth/callback`
+   - Custom: `https://your-server.com/your/custom/path` (if you set `redirect_path`)
+   - Development: `http://localhost:8000/auth/callback`
+3. **Obtain your credentials**: Client ID and Client Secret
+
+<Warning>
+  The redirect URI you configure with your provider must exactly match your
+  FastMCP server's URL plus the callback path. If you customize `redirect_path`
+  in the OIDC proxy, update your provider's redirect URI accordingly.
+</Warning>
+
+### Basic Setup
+
+Here's how to implement the OIDC proxy with any provider:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.oidc_proxy import OIDCProxy
+
+# Create the OIDC proxy
+auth = OIDCProxy(
+    # Provider's configuration URL
+    config_url="https://provider.com/.well-known/openid-configuration",
+
+    # Your registered app credentials
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+
+    # Your FastMCP server's public URL
+    base_url="https://your-server.com",
+
+    # Optional: customize the callback path (default is "/auth/callback")
+    # redirect_path="/custom/callback",
+)
+
+mcp = FastMCP(name="My Server", auth=auth)
+```
+
+### Configuration Parameters
+
+<Card icon="code" title="OIDCProxy Parameters">
+<ParamField body="config_url" type="str" required>
+  URL of your OAuth provider's OIDC configuration
+</ParamField>
+
+<ParamField body="client_id" type="str" required>
+  Client ID from your registered OAuth application
+</ParamField>
+
+<ParamField body="client_secret" type="str" required>
+  Client secret from your registered OAuth application
+</ParamField>
+
+<ParamField body="base_url" type="AnyHttpUrl | str" required>
+  Public URL of your FastMCP server (e.g., `https://your-server.com`)
+</ParamField>
+
+<ParamField body="resource_base_url" type="AnyHttpUrl | str | None">
+  Optional public base URL for the protected resource metadata and token audience.
+
+  Use this when your OAuth callbacks and operational endpoints need to live under one public URL, but the protected MCP resource should be advertised under another. FastMCP will still append the MCP mount path (for example, `/mcp`) to this base URL.
+</ParamField>
+
+<ParamField body="strict" type="bool | None">
+  Strict flag for configuration validation. When True, requires all OIDC
+  mandatory fields.
+</ParamField>
+
+<ParamField body="audience" type="str | None">
+  Audience parameter for OIDC providers that require it (e.g., Auth0). This is
+  typically your API identifier.
+</ParamField>
+
+<ParamField body="timeout_seconds" type="int | None" default="10">
+  HTTP request timeout in seconds for fetching OIDC configuration
+</ParamField>
+
+<ParamField body="token_verifier" type="TokenVerifier | None">
+
+<VersionBadge version="2.13.1" />
+  Custom token verifier for validating tokens. When provided, FastMCP uses your custom verifier instead of creating a default `JWTVerifier`.
+
+  Cannot be used with `algorithm` or `required_scopes` parameters - configure these on your verifier instead. The verifier's `required_scopes` are automatically loaded and advertised.
+</ParamField>
+
+<ParamField body="algorithm" type="str | None">
+  JWT algorithm to use for token verification (e.g., "RS256"). If not specified,
+  uses the provider's default. Only used when `token_verifier` is not provided.
+</ParamField>
+
+<ParamField body="required_scopes" type="list[str] | None">
+  List of OAuth scopes for token validation. These are automatically
+  included in authorization requests. Only used when `token_verifier` is not provided.
+</ParamField>
+
+<ParamField body="redirect_path" type="str" default="/auth/callback">
+  Path for OAuth callbacks. Must match the redirect URI configured in your OAuth
+  application
+</ParamField>
+
+<ParamField body="allowed_client_redirect_uris" type="list[str] | None">
+  List of allowed redirect URI patterns for MCP clients. Patterns support wildcards (e.g., `"http://localhost:*"`, `"https://*.example.com/*"`).
+  - `None` (default): All redirect URIs allowed (for MCP/DCR compatibility)
+  - Empty list `[]`: No redirect URIs allowed
+  - Custom list: Only matching patterns allowed
+
+These patterns apply to MCP client loopback redirects, NOT the upstream OAuth app redirect URI.
+
+</ParamField>
+
+<ParamField body="token_endpoint_auth_method" type="str | None">
+  Token endpoint authentication method for the upstream OAuth server. Controls how the proxy authenticates when exchanging authorization codes and refresh tokens with the upstream provider.
+  - `"client_secret_basic"`: Send credentials in Authorization header (most common)
+  - `"client_secret_post"`: Send credentials in request body (required by some providers)
+  - `"none"`: No authentication (for public clients)
+  - `None` (default): Uses authlib's default (typically `"client_secret_basic"`)
+
+Set this if your provider requires a specific authentication method and the default doesn't work.
+
+</ParamField>
+
+<ParamField body="jwt_signing_key" type="str | bytes | None">
+
+<VersionBadge version="2.13.0" />
+  Secret used to sign FastMCP JWT tokens issued to clients. Accepts any string or bytes - will be derived into a proper 32-byte cryptographic key using HKDF.
+
+  **Default behavior (`None`):**
+  - **Mac/Windows**: Auto-managed via system keyring. Keys are generated once and persisted, surviving server restarts with zero configuration. Keys are automatically derived from server attributes, so this approach, while convenient, is **only** suitable for development and local testing. For production, you must provide an explicit secret.
+  - **Linux**: Ephemeral (random salt at startup). Tokens become invalid on server restart, triggering client re-authentication.
+
+  **For production:**
+  Provide an explicit secret (e.g., from environment variable) to use a fixed key instead of the auto-generated one.
+</ParamField>
+
+<ParamField body="client_storage" type="AsyncKeyValue | None">
+
+<VersionBadge version="2.13.0" />
+  Storage backend for persisting OAuth client registrations and upstream tokens.
+
+  **Default behavior:**
+  - **Mac/Windows**: Encrypted DiskStore in your platform's data directory (derived from `platformdirs`)
+  - **Linux**: MemoryStore (ephemeral - clients lost on restart)
+
+  By default on Mac/Windows, clients are automatically persisted to encrypted disk storage, allowing them to survive server restarts as long as the filesystem remains accessible. This means MCP clients only need to register once and can reconnect seamlessly. On Linux where keyring isn't available, ephemeral storage is used to match the ephemeral key strategy.
+
+For production deployments with multiple servers or cloud deployments, use a network-accessible storage backend rather than local disk storage. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest.** See [Storage Backends](/v2/servers/storage-backends) for available options.
+
+Testing with in-memory storage (unencrypted):
+
+```python
+from key_value.aio.stores.memory import MemoryStore
+
+# Use in-memory storage for testing (clients lost on restart)
+auth = OIDCProxy(..., client_storage=MemoryStore())
+```
+
+Production with encrypted Redis storage:
+
+```python
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+import os
+
+auth = OIDCProxy(
+    ...,
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(host="redis.example.com", port=6379),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+```
+
+</ParamField>
+
+<ParamField body="require_authorization_consent" type='bool | Literal["remember", "external"]' default="True">
+  Consent screen behavior for authorization requests. Accepts `True` (default; always prompt — strongest protection), `"remember"` (silent consent on return visits via signed cookie, gated by `Sec-Fetch-Site` to block AS-in-the-middle attacks), `"external"` (consent handled by upstream IdP or custom page), or `False` (disable entirely; local/testing only). See the [OAuthProxy documentation](/v2/servers/auth/oauth-proxy) for full details on each mode and the security trade-offs.
+</ParamField>
+
+<ParamField body="consent_csp_policy" type="str | None" default="None">
+  Content Security Policy for the consent page.
+
+  - `None` (default): Uses the built-in CSP policy with appropriate directives for form submission
+  - Empty string `""`: Disables CSP entirely (no meta tag rendered)
+  - Custom string: Uses the provided value as the CSP policy
+
+  This is useful for organizations that have their own CSP policies and need to override or disable FastMCP's built-in CSP directives.
+</ParamField>
+</Card>
+
+### Using Built-in Providers
+
+FastMCP includes pre-configured OIDC providers for common services:
+
+```python
+from fastmcp.server.auth.providers.auth0 import Auth0Provider
+
+auth = Auth0Provider(
+    config_url="https://.../.well-known/openid-configuration",
+    client_id="your-auth0-client-id",
+    client_secret="your-auth0-client-secret",
+    audience="https://...",
+    base_url="https://localhost:8000"
+)
+
+mcp = FastMCP(name="My Server", auth=auth)
+```
+
+Available providers include `Auth0Provider` at present.
+
+### Scope Configuration
+
+OAuth scopes are configured with `required_scopes` to automatically request the permissions your application needs.
+
+Dynamic clients created by the proxy will automatically include these scopes in their authorization requests.
+
+## Environment Configuration
+
+<VersionBadge version="2.13.0" />
+
+For production deployments, configure the OIDC proxy through environment variables instead of hardcoding credentials:
+
+```bash
+# Specify the provider implementation
+export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.auth0.Auth0Provider
+
+# Provider-specific credentials
+export FASTMCP_SERVER_AUTH_AUTH0_CONFIG_URL=https://.../.well-known/openid-configuration
+export FASTMCP_SERVER_AUTH_AUTH0_CLIENT_ID=tv2ObNgaZAWWhhycr7Bz1LU2mxlnsmsB
+export FASTMCP_SERVER_AUTH_AUTH0_CLIENT_SECRET=vPYqbjemq...
+export FASTMCP_SERVER_AUTH_AUTH0_AUDIENCE=https://...
+export FASTMCP_SERVER_AUTH_AUTH0_BASE_URL=https://localhost:8000
+```
+
+With environment configuration, your server code simplifies to:
+
+```python
+from fastmcp import FastMCP
+
+# Authentication automatically configured from environment
+mcp = FastMCP(name="My Server")
+
+@mcp.tool
+def protected_tool(data: str) -> str:
+    """This tool is now protected by OAuth."""
+    return f"Processed: {data}"
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
diff --git a/docs/v2/servers/auth/remote-oauth.mdx b/docs/v2/servers/auth/remote-oauth.mdx
new file mode 100644
index 0000000..39c43c5
--- /dev/null
+++ b/docs/v2/servers/auth/remote-oauth.mdx
@@ -0,0 +1,226 @@
+---
+title: Remote OAuth
+sidebarTitle: Remote OAuth
+description: Integrate your FastMCP server with external identity providers like Descope, WorkOS, Auth0, and corporate SSO systems.
+icon: camera-cctv
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.11.0" />
+
+Remote OAuth integration allows your FastMCP server to leverage external identity providers that **support Dynamic Client Registration (DCR)**. With DCR, MCP clients can automatically register themselves with the identity provider and obtain credentials without any manual configuration. This provides enterprise-grade authentication with fully automated flows, making it ideal for production applications with modern identity providers.
+
+<Tip>
+**When to use RemoteAuthProvider vs OAuth Proxy:**
+- **RemoteAuthProvider**: For providers WITH Dynamic Client Registration (Descope, WorkOS AuthKit, modern OIDC providers)
+- **OAuth Proxy**: For providers WITHOUT Dynamic Client Registration (GitHub, Google, Azure, AWS, Discord, etc.)
+
+RemoteAuthProvider requires DCR support for fully automated client registration and authentication.
+</Tip>
+
+## DCR-Enabled Providers
+
+RemoteAuthProvider works with identity providers that support **Dynamic Client Registration (DCR)** - a critical capability that enables automated authentication flows:
+
+| Feature | DCR Providers (RemoteAuth) | Non-DCR Providers (OAuth Proxy) |
+|---------|---------------------------|--------------------------------|
+| **Client Registration** | Automatic via API | Manual in provider console |
+| **Credentials** | Dynamic per client | Fixed app credentials |
+| **Configuration** | Zero client config | Pre-shared credentials |
+| **Examples** | Descope, WorkOS AuthKit, modern OIDC | GitHub, Google, Azure |
+| **FastMCP Class** | `RemoteAuthProvider` | [`OAuthProxy`](/v2/servers/auth/oauth-proxy) |
+
+If your provider doesn't support DCR (most traditional OAuth providers), you'll need to use [`OAuth Proxy`](/v2/servers/auth/oauth-proxy) instead, which bridges the gap between MCP's DCR expectations and fixed OAuth credentials.
+
+## The Remote OAuth Challenge
+
+Traditional OAuth flows assume human users with web browsers who can interact with login forms, consent screens, and redirects. MCP clients operate differently - they're often automated systems that need to authenticate programmatically without human intervention.
+
+This creates several unique requirements that standard OAuth implementations don't address well:
+
+**Automatic Discovery**: MCP clients must discover authentication requirements by examining server metadata rather than encountering HTTP redirects. They need to know which identity provider to use and how to reach it before making any authenticated requests.
+
+**Programmatic Registration**: Clients need to register themselves with identity providers automatically. Manual client registration doesn't work when clients might be dynamically created tools or services.
+
+**Seamless Token Management**: Clients must obtain, store, and refresh tokens without user interaction. The authentication flow needs to work in headless environments where no human is available to complete OAuth consent flows.
+
+**Protocol Integration**: The authentication process must integrate cleanly with MCP's JSON-RPC transport layer and error handling mechanisms.
+
+These requirements mean that your MCP server needs to do more than just validate tokens - it needs to provide discovery metadata that enables MCP clients to understand and navigate your authentication requirements automatically.
+
+## MCP Authentication Discovery
+
+MCP authentication discovery relies on well-known endpoints that clients can examine to understand your authentication requirements. Your server becomes a bridge between MCP clients and your chosen identity provider.
+
+The core discovery endpoint is `/.well-known/oauth-protected-resource`, which tells clients that your server requires OAuth authentication and identifies the authorization servers you trust. This endpoint contains static metadata that points clients to your identity provider without requiring any dynamic lookups.
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant FastMCPServer as FastMCP Server
+    participant ExternalIdP as Identity Provider
+
+    Client->>FastMCPServer: 1. GET /.well-known/oauth-protected-resource
+    FastMCPServer-->>Client: 2. "Use https://my-idp.com for auth"
+    
+    note over Client, ExternalIdP: Client goes directly to the IdP
+    Client->>ExternalIdP: 3. Authenticate & get token via DCR
+    ExternalIdP-->>Client: 4. Access token
+    
+    Client->>FastMCPServer: 5. MCP request with Bearer token
+    FastMCPServer->>FastMCPServer: 6. Verify token signature
+    FastMCPServer-->>Client: 7. MCP response
+```
+
+This flow separates concerns cleanly: your MCP server handles resource protection and token validation, while your identity provider handles user authentication and token issuance. The client coordinates between these systems using standardized OAuth discovery mechanisms.
+
+## FastMCP Remote Authentication
+
+<VersionBadge version="2.11.1" />
+
+FastMCP provides `RemoteAuthProvider` to handle the complexities of remote OAuth integration. This class combines token validation capabilities with the OAuth discovery metadata that MCP clients require.
+
+### RemoteAuthProvider
+
+`RemoteAuthProvider` works by composing a [`TokenVerifier`](/v2/servers/auth/token-verification) with authorization server information. A `TokenVerifier` is another FastMCP authentication class that focuses solely on token validation - signature verification, expiration checking, and claim extraction. The `RemoteAuthProvider` takes that token validation capability and adds the OAuth discovery endpoints that enable MCP clients to automatically find and authenticate with your identity provider.
+
+This composition pattern means you can use any token validation strategy while maintaining consistent OAuth discovery behavior:
+- **JWT tokens**: Use `JWTVerifier` for self-contained tokens
+- **Opaque tokens**: Use `IntrospectionTokenVerifier` for RFC 7662 introspection
+- **Custom validation**: Implement your own `TokenVerifier` subclass
+
+The separation allows you to change token validation approaches without affecting the client discovery experience.
+
+The class automatically generates the required OAuth metadata endpoints using the MCP SDK's standardized route creation functions. This ensures compatibility with MCP clients while reducing the implementation complexity for server developers.
+
+### Basic Implementation
+
+Most applications can use `RemoteAuthProvider` directly without subclassing. The implementation requires a `TokenVerifier` instance, a list of trusted authorization servers, and your server's URL for metadata generation.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import RemoteAuthProvider
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from pydantic import AnyHttpUrl
+
+# Configure token validation for your identity provider
+token_verifier = JWTVerifier(
+    jwks_uri="https://auth.yourcompany.com/.well-known/jwks.json",
+    issuer="https://auth.yourcompany.com",
+    audience="mcp-production-api"
+)
+
+# Create the remote auth provider
+auth = RemoteAuthProvider(
+    token_verifier=token_verifier,
+    authorization_servers=[AnyHttpUrl("https://auth.yourcompany.com")],
+    base_url="https://api.yourcompany.com",  # Your server base URL
+    # Optional: customize allowed client redirect URIs (defaults to localhost only)
+    allowed_client_redirect_uris=["http://localhost:*", "http://127.0.0.1:*"]
+)
+
+mcp = FastMCP(name="Company API", auth=auth)
+```
+
+This configuration creates a server that accepts tokens issued by `auth.yourcompany.com` and provides the OAuth discovery metadata that MCP clients need. The `JWTVerifier` handles token validation using your identity provider's public keys, while the `RemoteAuthProvider` generates the required OAuth endpoints.
+
+The `authorization_servers` list tells MCP clients which identity providers you trust. The `base_url` identifies your server in OAuth metadata, enabling proper token audience validation. **Important**: The `base_url` should point to your server base URL - for example, if your MCP server is accessible at `https://api.yourcompany.com/mcp`, use `https://api.yourcompany.com` as the base URL.
+
+### Custom Endpoints
+
+You can extend `RemoteAuthProvider` to add additional endpoints beyond the standard OAuth protected resource metadata. These don't have to be OAuth-specific - you can add any endpoints your authentication integration requires.
+
+```python
+import httpx
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+class CompanyAuthProvider(RemoteAuthProvider):
+    def __init__(self):
+        token_verifier = JWTVerifier(
+            jwks_uri="https://auth.yourcompany.com/.well-known/jwks.json",
+            issuer="https://auth.yourcompany.com",
+            audience="mcp-production-api"
+        )
+        
+        super().__init__(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.yourcompany.com")],
+            base_url="https://api.yourcompany.com"  # Your server base URL
+        )
+    
+    def get_routes(self) -> list[Route]:
+        """Add custom endpoints to the standard protected resource routes."""
+        
+        # Get the standard OAuth protected resource routes
+        routes = super().get_routes()
+        
+        # Add authorization server metadata forwarding for client convenience
+        async def authorization_server_metadata(request):
+            async with httpx.AsyncClient() as client:
+                response = await client.get(
+                    "https://auth.yourcompany.com/.well-known/oauth-authorization-server"
+                )
+                response.raise_for_status()
+                return JSONResponse(response.json())
+        
+        routes.append(
+            Route("/.well-known/oauth-authorization-server", authorization_server_metadata)
+        )
+        
+        return routes
+
+mcp = FastMCP(name="Company API", auth=CompanyAuthProvider())
+```
+
+This pattern uses `super().get_routes()` to get the standard protected resource routes, then adds additional endpoints as needed. A common use case is providing authorization server metadata forwarding, which allows MCP clients to discover your identity provider's capabilities through your MCP server rather than contacting the identity provider directly.
+
+## WorkOS AuthKit Integration
+
+WorkOS AuthKit provides an excellent example of remote OAuth integration. The `AuthKitProvider` demonstrates how to implement both token validation and OAuth metadata forwarding in a production-ready package.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.workos import AuthKitProvider
+
+auth = AuthKitProvider(
+    authkit_domain="https://your-project.authkit.app",
+    base_url="https://your-mcp-server.com"
+)
+
+mcp = FastMCP(name="Protected Application", auth=auth)
+```
+
+The `AuthKitProvider` automatically configures JWT validation against WorkOS's public keys and provides both protected resource metadata and authorization server metadata forwarding. This implementation handles the complete remote OAuth integration with minimal configuration.
+
+WorkOS's support for Dynamic Client Registration makes it particularly well-suited for MCP applications. Clients can automatically register themselves with your WorkOS project and obtain the credentials needed for authentication without manual intervention.
+
+→ **Complete WorkOS tutorial**: [AuthKit Integration Guide](/v2/integrations/authkit)
+
+## Client Redirect URI Security
+
+<Note>
+`RemoteAuthProvider` also supports the `allowed_client_redirect_uris` parameter for controlling which redirect URIs are accepted from MCP clients during DCR:
+
+- `None` (default): Only localhost patterns allowed
+- Custom list: Specify allowed patterns with wildcard support
+- Empty list `[]`: Allow all (not recommended)
+
+This provides defense-in-depth even though DCR providers typically validate redirect URIs themselves.
+</Note>
+
+## Implementation Considerations
+
+Remote OAuth integration requires careful attention to several technical details that affect reliability and security.
+
+**Token Validation Performance**: Your server validates every incoming token by checking signatures against your identity provider's public keys. Consider implementing key caching and rotation handling to minimize latency while maintaining security.
+
+**Error Handling**: Network issues with your identity provider can affect token validation. Implement appropriate timeouts, retry logic, and graceful degradation to maintain service availability during identity provider outages.
+
+**Audience Validation**: Ensure that tokens intended for your server are not accepted by other applications. Proper audience validation prevents token misuse across different services in your ecosystem.
+
+**Scope Management**: Map token scopes to your application's permission model consistently. Consider how scope changes affect existing tokens and plan for smooth permission updates.
+
+The complexity of these considerations reinforces why external identity providers are recommended over custom OAuth implementations. Established providers handle these technical details with extensive testing and operational experience.
\ No newline at end of file
diff --git a/docs/v2/servers/auth/token-verification.mdx b/docs/v2/servers/auth/token-verification.mdx
new file mode 100644
index 0000000..e142826
--- /dev/null
+++ b/docs/v2/servers/auth/token-verification.mdx
@@ -0,0 +1,341 @@
+---
+title: Token Verification
+sidebarTitle: Token Verification
+description: Protect your server by validating bearer tokens issued by external systems.
+icon: key
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.11.0" />
+
+Token verification enables your FastMCP server to validate bearer tokens issued by external systems without participating in user authentication flows. Your server acts as a pure resource server, focusing on token validation and authorization decisions while delegating identity management to other systems in your infrastructure.
+
+<Note>
+Token verification operates somewhat outside the formal MCP authentication flow, which expects OAuth-style discovery. It's best suited for internal systems, microservices architectures, or when you have full control over token generation and distribution.
+</Note>
+
+## Understanding Token Verification
+
+Token verification addresses scenarios where authentication responsibility is distributed across multiple systems. Your MCP server receives structured tokens containing identity and authorization information, validates their authenticity, and makes access control decisions based on their contents.
+
+This pattern emerges naturally in microservices architectures where a central authentication service issues tokens that multiple downstream services validate independently. It also works well when integrating MCP servers into existing systems that already have established token-based authentication mechanisms.
+
+### The Token Verification Model
+
+Token verification treats your MCP server as a resource server in OAuth terminology. The key insight is that token validation and token issuance are separate concerns that can be handled by different systems.
+
+**Token Issuance**: Another system (API gateway, authentication service, or identity provider) handles user authentication and creates signed tokens containing identity and permission information.
+
+**Token Validation**: Your MCP server receives these tokens, verifies their authenticity using cryptographic signatures, and extracts authorization information from their claims.
+
+**Access Control**: Based on token contents, your server determines what resources, tools, and prompts the client can access.
+
+This separation allows your MCP server to focus on its core functionality while leveraging existing authentication infrastructure. The token acts as a portable proof of identity that travels with each request.
+
+### Token Security Considerations
+
+Token-based authentication relies on cryptographic signatures to ensure token integrity. Your MCP server validates tokens using public keys corresponding to the private keys used for token creation. This asymmetric approach means your server never needs access to signing secrets.
+
+Token validation must address several security requirements: signature verification ensures tokens haven't been tampered with, expiration checking prevents use of stale tokens, and audience validation ensures tokens intended for your server aren't accepted by other systems.
+
+The challenge in MCP environments is that clients need to obtain valid tokens before making requests, but the MCP protocol doesn't provide built-in discovery mechanisms for token endpoints. Clients must obtain tokens through separate channels or prior configuration.
+
+
+## TokenVerifier Class
+
+FastMCP provides the `TokenVerifier` class to handle token validation complexity while remaining flexible about token sources and validation strategies.
+
+`TokenVerifier` focuses exclusively on token validation without providing OAuth discovery metadata. This makes it ideal for internal systems where clients already know how to obtain tokens, or for microservices that trust tokens from known issuers.
+
+The class validates token signatures, checks expiration timestamps, and extracts authorization information from token claims. It supports various token formats and validation strategies while maintaining a consistent interface for authorization decisions.
+
+You can subclass `TokenVerifier` to implement custom validation logic for specialized token formats or validation requirements. The base class handles common patterns while allowing extension for unique use cases.
+
+## JWT Token Verification
+
+JSON Web Tokens (JWTs) represent the most common token format for modern applications. FastMCP's `JWTVerifier` validates JWTs using industry-standard cryptographic techniques and claim validation.
+
+### JWKS Endpoint Integration
+
+JWKS endpoint integration provides the most flexible approach for production systems. The verifier automatically fetches public keys from a JSON Web Key Set endpoint, enabling automatic key rotation without server configuration changes.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+# Configure JWT verification against your identity provider
+verifier = JWTVerifier(
+    jwks_uri="https://auth.yourcompany.com/.well-known/jwks.json",
+    issuer="https://auth.yourcompany.com",
+    audience="mcp-production-api"
+)
+
+mcp = FastMCP(name="Protected API", auth=verifier)
+```
+
+This configuration creates a server that validates JWTs issued by `auth.yourcompany.com`. The verifier periodically fetches public keys from the JWKS endpoint and validates incoming tokens against those keys. Only tokens with the correct issuer and audience claims will be accepted.
+
+The `issuer` parameter ensures tokens come from your trusted authentication system, while `audience` validation prevents tokens intended for other services from being accepted by your MCP server.
+
+### Symmetric Key Verification (HMAC)
+
+Symmetric key verification uses a shared secret for both signing and validation, making it ideal for internal microservices and trusted environments where the same secret can be securely distributed to both token issuers and validators.
+
+This approach is commonly used in microservices architectures where services share a secret key, or when your authentication service and MCP server are both managed by the same organization. The HMAC algorithms (HS256, HS384, HS512) provide strong security when the shared secret is properly managed.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+# Use a shared secret for symmetric key verification
+verifier = JWTVerifier(
+    public_key="your-shared-secret-key-minimum-32-chars",  # Despite the name, this accepts symmetric secrets
+    issuer="internal-auth-service",
+    audience="mcp-internal-api",
+    algorithm="HS256"  # or HS384, HS512 for stronger security
+)
+
+mcp = FastMCP(name="Internal API", auth=verifier)
+```
+
+The verifier will validate tokens signed with the same secret using the specified HMAC algorithm. This approach offers several advantages for internal systems:
+
+- **Simplicity**: No key pair management or certificate distribution
+- **Performance**: HMAC operations are typically faster than RSA
+- **Compatibility**: Works well with existing microservice authentication patterns
+
+<Note>
+The parameter is named `public_key` for backwards compatibility, but when using HMAC algorithms (HS256/384/512), it accepts the symmetric secret string.
+</Note>
+
+<Warning>
+**Security Considerations for Symmetric Keys:**
+- Use a strong, randomly generated secret (minimum 32 characters recommended)
+- Never expose the secret in logs, error messages, or version control
+- Implement secure key distribution and rotation mechanisms
+- Consider using asymmetric keys (RSA/ECDSA) for external-facing APIs
+</Warning>
+
+### Static Public Key Verification
+
+Static public key verification works when you have a fixed RSA or ECDSA signing key and don't need automatic key rotation. This approach is primarily useful for development environments or controlled deployments where JWKS endpoints aren't available.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+# Use a static public key for token verification
+public_key_pem = """-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
+-----END PUBLIC KEY-----"""
+
+verifier = JWTVerifier(
+    public_key=public_key_pem,
+    issuer="https://auth.yourcompany.com",
+    audience="mcp-production-api"
+)
+
+mcp = FastMCP(name="Protected API", auth=verifier)
+```
+
+This configuration validates tokens using a specific RSA or ECDSA public key. The key must correspond to the private key used by your token issuer. While less flexible than JWKS endpoints, this approach can be useful in development environments or when testing with fixed keys.
+## Opaque Token Verification
+
+Many authorization servers issue opaque tokens rather than self-contained JWTs. Opaque tokens are random strings that carry no information themselves - the authorization server maintains their state and validation requires querying the server. FastMCP supports opaque token validation through OAuth 2.0 Token Introspection (RFC 7662).
+
+### Understanding Opaque Tokens
+
+Opaque tokens differ fundamentally from JWTs in their verification model. Where JWTs carry signed claims that can be validated locally, opaque tokens require network calls to the issuing authorization server for validation. The authorization server maintains token state and can revoke tokens immediately, providing stronger security guarantees for sensitive operations.
+
+This approach trades performance (network latency on each validation) for security and flexibility. Authorization servers can revoke opaque tokens instantly, implement complex authorization logic, and maintain detailed audit logs of token usage. Many enterprise OAuth providers default to opaque tokens for these security advantages.
+
+### Token Introspection Protocol
+
+RFC 7662 standardizes how resource servers validate opaque tokens. The protocol defines an introspection endpoint where resource servers authenticate using client credentials and receive token metadata including active status, scopes, expiration, and subject identity.
+
+FastMCP implements this protocol through the `IntrospectionTokenVerifier` class, handling authentication, request formatting, and response parsing according to the specification.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.introspection import IntrospectionTokenVerifier
+
+# Configure introspection with your OAuth provider
+verifier = IntrospectionTokenVerifier(
+    introspection_url="https://auth.yourcompany.com/oauth/introspect",
+    client_id="mcp-resource-server",
+    client_secret="your-client-secret",
+    required_scopes=["api:read", "api:write"]
+)
+
+mcp = FastMCP(name="Protected API", auth=verifier)
+```
+
+The verifier authenticates to the introspection endpoint using HTTP Basic Auth with your client credentials. When a request arrives with a bearer token, FastMCP queries the introspection endpoint to determine if the token is active and has sufficient scopes.
+
+## Development and Testing
+
+Development environments often need simpler token management without the complexity of full JWT infrastructure. FastMCP provides tools specifically designed for these scenarios.
+
+### Static Token Verification
+
+Static token verification enables rapid development by accepting predefined tokens with associated claims. This approach eliminates the need for token generation infrastructure during development and testing.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.jwt import StaticTokenVerifier
+
+# Define development tokens and their associated claims
+verifier = StaticTokenVerifier(
+    tokens={
+        "dev-alice-token": {
+            "client_id": "alice@company.com",
+            "scopes": ["read:data", "write:data", "admin:users"]
+        },
+        "dev-guest-token": {
+            "client_id": "guest-user",
+            "scopes": ["read:data"]
+        }
+    },
+    required_scopes=["read:data"]
+)
+
+mcp = FastMCP(name="Development Server", auth=verifier)
+```
+
+Clients can now authenticate using `Authorization: Bearer dev-alice-token` headers. The server will recognize the token and load the associated claims for authorization decisions. This approach enables immediate development without external dependencies.
+
+<Warning>
+Static token verification stores tokens as plain text and should never be used in production environments. It's designed exclusively for development and testing scenarios.
+</Warning>
+
+
+### Debug/Custom Token Verification
+
+<VersionBadge version="2.13.1" />
+
+The `DebugTokenVerifier` provides maximum flexibility for testing and special cases where standard token verification isn't applicable. It delegates validation to a user-provided callable, making it useful for prototyping, testing scenarios, or handling opaque tokens without introspection endpoints.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.debug import DebugTokenVerifier
+
+# Accept all tokens (useful for rapid development)
+verifier = DebugTokenVerifier()
+
+mcp = FastMCP(name="Development Server", auth=verifier)
+```
+
+By default, `DebugTokenVerifier` accepts any non-empty token as valid. This eliminates authentication barriers during early development, allowing you to focus on core functionality before adding security.
+
+For more controlled testing, provide custom validation logic:
+
+```python
+from fastmcp.server.auth.providers.debug import DebugTokenVerifier
+
+# Synchronous validation - check token prefix
+verifier = DebugTokenVerifier(
+    validate=lambda token: token.startswith("dev-"),
+    client_id="development-client",
+    scopes=["read", "write"]
+)
+
+mcp = FastMCP(name="Development Server", auth=verifier)
+```
+
+The validation callable can also be async, enabling database lookups or external service calls:
+
+```python
+from fastmcp.server.auth.providers.debug import DebugTokenVerifier
+
+# Asynchronous validation - check against cache
+async def validate_token(token: str) -> bool:
+    # Check if token exists in Redis, database, etc.
+    return await redis.exists(f"valid_tokens:{token}")
+
+verifier = DebugTokenVerifier(
+    validate=validate_token,
+    client_id="api-client",
+    scopes=["api:access"]
+)
+
+mcp = FastMCP(name="Custom API", auth=verifier)
+```
+
+**Use Cases:**
+
+- **Testing**: Accept any token during integration tests without setting up token infrastructure
+- **Prototyping**: Quickly validate concepts without authentication complexity
+- **Opaque tokens without introspection**: When you have tokens from an IDP that provides no introspection endpoint, and you're willing to accept tokens without validation (validation happens later at the upstream service)
+- **Custom token formats**: Implement validation for non-standard token formats or legacy systems
+
+<Warning>
+`DebugTokenVerifier` bypasses standard security checks. Only use in controlled environments (development, testing) or when you fully understand the security implications. For production, use proper JWT or introspection-based verification.
+</Warning>
+
+### Test Token Generation
+
+Test token generation helps when you need to test JWT verification without setting up complete identity infrastructure. FastMCP includes utilities for generating test key pairs and signed tokens.
+
+```python
+from fastmcp.server.auth.providers.jwt import JWTVerifier, RSAKeyPair
+
+# Generate a key pair for testing
+key_pair = RSAKeyPair.generate()
+
+# Configure your server with the public key
+verifier = JWTVerifier(
+    public_key=key_pair.public_key,
+    issuer="https://test.yourcompany.com",
+    audience="test-mcp-server"
+)
+
+# Generate a test token using the private key
+test_token = key_pair.create_token(
+    subject="test-user-123",
+    issuer="https://test.yourcompany.com", 
+    audience="test-mcp-server",
+    scopes=["read", "write", "admin"]
+)
+
+print(f"Test token: {test_token}")
+```
+
+This pattern enables comprehensive testing of JWT validation logic without depending on external token issuers. The generated tokens are cryptographically valid and will pass all standard JWT validation checks.
+
+## Environment Configuration
+
+<VersionBadge version="2.12.1" />
+
+FastMCP supports both programmatic and environment-based configuration for token verification, enabling flexible deployment across different environments.
+
+Environment-based configuration separates authentication settings from application code, following twelve-factor app principles and simplifying deployment pipelines.
+
+```bash
+# Enable JWT verification
+export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.jwt.JWTVerifier
+
+# For asymmetric verification with JWKS endpoint:
+export FASTMCP_SERVER_AUTH_JWT_JWKS_URI="https://auth.company.com/.well-known/jwks.json"
+export FASTMCP_SERVER_AUTH_JWT_ISSUER="https://auth.company.com"
+export FASTMCP_SERVER_AUTH_JWT_AUDIENCE="mcp-production-api"
+export FASTMCP_SERVER_AUTH_JWT_REQUIRED_SCOPES="read:data,write:data"
+
+# OR for symmetric key verification (HMAC):
+export FASTMCP_SERVER_AUTH_JWT_PUBLIC_KEY="your-shared-secret-key-minimum-32-chars"
+export FASTMCP_SERVER_AUTH_JWT_ALGORITHM="HS256"  # or HS384, HS512
+export FASTMCP_SERVER_AUTH_JWT_ISSUER="internal-auth-service"
+export FASTMCP_SERVER_AUTH_JWT_AUDIENCE="mcp-internal-api"
+```
+
+With these environment variables configured, your FastMCP server automatically enables JWT verification:
+
+```python
+from fastmcp import FastMCP
+
+# Authentication automatically configured from environment
+mcp = FastMCP(name="Production API")
+```
+
+This approach enables the same codebase to run across development, staging, and production environments with different authentication requirements. Development might use static tokens while production uses JWT verification, all controlled through environment configuration.
+
diff --git a/docs/v2/servers/composition.mdx b/docs/v2/servers/composition.mdx
new file mode 100644
index 0000000..8fb9343
--- /dev/null
+++ b/docs/v2/servers/composition.mdx
@@ -0,0 +1,326 @@
+---
+title: Server Composition
+sidebarTitle: Composition
+description: Combine multiple FastMCP servers into a single, larger application using mounting and importing.
+icon: puzzle-piece
+---
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.2.0" />
+
+As your MCP applications grow, you might want to organize your tools, resources, and prompts into logical modules or reuse existing server components. FastMCP supports composition through two methods:
+
+- **`import_server`**: For a one-time copy of components with prefixing (static composition).
+- **`mount`**: For creating a live link where the main server delegates requests to the subserver (dynamic composition).
+
+## Why Compose Servers?
+
+-   **Modularity**: Break down large applications into smaller, focused servers (e.g., a `WeatherServer`, a `DatabaseServer`, a `CalendarServer`).
+-   **Reusability**: Create common utility servers (e.g., a `TextProcessingServer`) and mount them wherever needed.
+-   **Teamwork**: Different teams can work on separate FastMCP servers that are later combined.
+-   **Organization**: Keep related functionality grouped together logically.
+
+### Importing vs Mounting
+
+The choice of importing or mounting depends on your use case and requirements.
+
+| Feature | Importing | Mounting |
+|---------|----------------|---------|
+| **Method** | `FastMCP.import_server(server, prefix=None)` | `FastMCP.mount(server, prefix=None)` |
+| **Composition Type** | One-time copy (static) | Live link (dynamic) |
+| **Updates** | Changes to subserver NOT reflected | Changes to subserver immediately reflected |
+| **Performance** | Fast - no runtime delegation | Slower - affected by slowest mounted server |
+| **Prefix** | Optional - omit for original names | Optional - omit for original names |
+| **Best For** | Bundling finalized components, performance-critical setups | Modular runtime composition |
+
+### Proxy Servers
+
+FastMCP supports [MCP proxying](/v2/servers/proxy), which allows you to mirror a local or remote server in a local FastMCP instance. Proxies are fully compatible with both importing and mounting.
+
+<VersionBadge version="2.4.0" />
+
+You can also create proxies from configuration dictionaries that follow the MCPConfig schema, which is useful for quickly connecting to one or more remote servers. See the [Proxy Servers documentation](/v2/servers/proxy#configuration-based-proxies) for details on configuration-based proxying. Note that MCPConfig follows an emerging standard and its format may evolve over time.
+
+Prefixing rules for tools, prompts, resources, and templates are identical across importing, mounting, and proxies. When prefixes are used, resource URIs are prefixed using path format (since 2.4.0): `resource://prefix/path/to/resource`.
+
+## Importing (Static Composition)
+
+The `import_server()` method copies all components (tools, resources, templates, prompts) from one `FastMCP` instance (the *subserver*) into another (the *main server*). An optional `prefix` can be provided to avoid naming conflicts. If no prefix is provided, components are imported without modification. When multiple servers are imported with the same prefix (or no prefix), the most recently imported server's components take precedence.
+
+```python
+from fastmcp import FastMCP
+import asyncio
+
+# Define subservers
+weather_mcp = FastMCP(name="WeatherService")
+
+@weather_mcp.tool
+def get_forecast(city: str) -> dict:
+    """Get weather forecast."""
+    return {"city": city, "forecast": "Sunny"}
+
+@weather_mcp.resource("data://cities/supported")
+def list_supported_cities() -> list[str]:
+    """List cities with weather support."""
+    return ["London", "Paris", "Tokyo"]
+
+# Define main server
+main_mcp = FastMCP(name="MainApp")
+
+# Import subserver
+async def setup():
+    await main_mcp.import_server(weather_mcp, prefix="weather")
+
+# Result: main_mcp now contains prefixed components:
+# - Tool: "weather_get_forecast"
+# - Resource: "data://weather/cities/supported" 
+
+if __name__ == "__main__":
+    asyncio.run(setup())
+    main_mcp.run()
+```
+
+### How Importing Works
+
+When you call `await main_mcp.import_server(subserver, prefix={whatever})`:
+
+1.  **Tools**: All tools from `subserver` are added to `main_mcp` with names prefixed using `{prefix}_`.
+    -   `subserver.tool(name="my_tool")` becomes `main_mcp.tool(name="{prefix}_my_tool")`.
+2.  **Resources**: All resources are added with both URIs and names prefixed.
+    -   URI: `subserver.resource(uri="data://info")` becomes `main_mcp.resource(uri="data://{prefix}/info")`.
+    -   Name: `resource.name` becomes `"{prefix}_{resource.name}"`.
+3.  **Resource Templates**: Templates are prefixed similarly to resources.
+    -   URI: `subserver.resource(uri="data://{id}")` becomes `main_mcp.resource(uri="data://{prefix}/{id}")`.
+    -   Name: `template.name` becomes `"{prefix}_{template.name}"`.
+4.  **Prompts**: All prompts are added with names prefixed using `{prefix}_`.
+    -   `subserver.prompt(name="my_prompt")` becomes `main_mcp.prompt(name="{prefix}_my_prompt")`.
+
+Note that `import_server` performs a **one-time copy** of components. Changes made to the `subserver` *after* importing **will not** be reflected in `main_mcp`. The `subserver`'s `lifespan` context is also **not** executed by the main server.
+
+<Tip>
+The `prefix` parameter is optional. If omitted, components are imported without modification.
+</Tip>
+
+#### Importing Without Prefixes
+
+<VersionBadge version="2.9.0" />
+
+You can also import servers without specifying a prefix, which copies components using their original names:
+
+```python
+
+from fastmcp import FastMCP
+import asyncio
+
+# Define subservers
+weather_mcp = FastMCP(name="WeatherService")
+
+@weather_mcp.tool
+def get_forecast(city: str) -> dict:
+    """Get weather forecast."""
+    return {"city": city, "forecast": "Sunny"}
+
+@weather_mcp.resource("data://cities/supported")
+def list_supported_cities() -> list[str]:
+    """List cities with weather support."""
+    return ["London", "Paris", "Tokyo"]
+
+# Define main server
+main_mcp = FastMCP(name="MainApp")
+
+# Import subserver
+async def setup():
+    # Import without prefix - components keep original names
+    await main_mcp.import_server(weather_mcp)
+
+# Result: main_mcp now contains:
+# - Tool: "get_forecast" (original name preserved)
+# - Resource: "data://cities/supported" (original URI preserved)
+
+if __name__ == "__main__":
+    asyncio.run(setup())
+    main_mcp.run()
+```
+
+#### Conflict Resolution
+
+<VersionBadge version="2.9.0" />
+
+When importing multiple servers with the same prefix, or no prefix, components from the **most recently imported** server take precedence.
+
+
+
+
+## Mounting (Live Linking)
+
+The `mount()` method creates a **live link** between the `main_mcp` server and the `subserver`. Instead of copying components, requests for components matching the optional `prefix` are **delegated** to the `subserver` at runtime. If no prefix is provided, the subserver's components are accessible without prefixing. When multiple servers are mounted with the same prefix (or no prefix), the most recently mounted server takes precedence for conflicting component names.
+
+```python
+import asyncio
+from fastmcp import FastMCP, Client
+
+# Define subserver
+dynamic_mcp = FastMCP(name="DynamicService")
+
+@dynamic_mcp.tool
+def initial_tool():
+    """Initial tool demonstration."""
+    return "Initial Tool Exists"
+
+# Mount subserver (synchronous operation)
+main_mcp = FastMCP(name="MainAppLive")
+main_mcp.mount(dynamic_mcp, prefix="dynamic")
+
+# Add a tool AFTER mounting - it will be accessible through main_mcp
+@dynamic_mcp.tool
+def added_later():
+    """Tool added after mounting."""
+    return "Tool Added Dynamically!"
+
+# Testing access to mounted tools
+async def test_dynamic_mount():
+    tools = await main_mcp.get_tools()
+    print("Available tools:", list(tools.keys()))
+    # Shows: ['dynamic_initial_tool', 'dynamic_added_later']
+    
+    async with Client(main_mcp) as client:
+        result = await client.call_tool("dynamic_added_later")
+        print("Result:", result.data)
+        # Shows: "Tool Added Dynamically!"
+
+if __name__ == "__main__":
+    asyncio.run(test_dynamic_mount())
+```
+
+### How Mounting Works
+
+When mounting is configured:
+
+1. **Live Link**: The parent server establishes a connection to the mounted server.
+2. **Dynamic Updates**: Changes to the mounted server are immediately reflected when accessed through the parent.
+3. **Prefixed Access**: The parent server uses prefixes to route requests to the mounted server.
+4. **Delegation**: Requests for components matching the prefix are delegated to the mounted server at runtime.
+
+The same prefixing rules apply as with `import_server` for naming tools, resources, templates, and prompts. This includes prefixing both the URIs/keys and the names of resources and templates for better identification in multi-server configurations.
+
+<Tip>
+    The `prefix` parameter is optional. If omitted, components are mounted without modification.
+</Tip>
+
+<Note>
+When mounting servers, custom HTTP routes defined with `@server.custom_route()` are also forwarded to the parent server, making them accessible through the parent's HTTP application.
+</Note>
+
+#### Performance Considerations
+
+Due to the "live link", operations like `list_tools()` on the parent server will be impacted by the speed of the slowest mounted server. In particular, HTTP-based mounted servers can introduce significant latency (300-400ms vs 1-2ms for local tools), and this slowdown affects the whole server, not just interactions with the HTTP-proxied tools. If performance is important, importing tools via [`import_server()`](#importing-static-composition) may be a more appropriate solution as it copies components once at startup rather than delegating requests at runtime.
+
+#### Mounting Without Prefixes
+
+<VersionBadge version="2.9.0" />
+
+You can also mount servers without specifying a prefix, which makes components accessible without prefixing. This works identically to [importing without prefixes](#importing-without-prefixes), including [conflict resolution](#conflict-resolution).
+
+
+
+
+### Direct vs. Proxy Mounting
+
+<VersionBadge version="2.2.7" />
+
+FastMCP supports two mounting modes:
+
+1. **Direct Mounting** (default): The parent server directly accesses the mounted server's objects in memory.
+   - No client lifecycle events occur on the mounted server
+   - The mounted server's lifespan context is not executed
+   - Communication is handled through direct method calls
+   
+2. **Proxy Mounting**: The parent server treats the mounted server as a separate entity and communicates with it through a client interface.
+   - Full client lifecycle events occur on the mounted server
+   - The mounted server's lifespan is executed when a client connects
+   - Communication happens via an in-memory Client transport
+
+```python
+# Direct mounting (default when no custom lifespan)
+main_mcp.mount(api_server, prefix="api")
+
+# Proxy mounting (preserves full client lifecycle)
+main_mcp.mount(api_server, prefix="api", as_proxy=True)
+
+# Mounting without a prefix (components accessible without prefixing)
+main_mcp.mount(api_server)
+```
+
+FastMCP automatically uses proxy mounting when the mounted server has a custom lifespan, but you can override this behavior with the `as_proxy` parameter.
+
+#### Interaction with Proxy Servers
+
+When using `FastMCP.as_proxy()` to create a proxy server, mounting that server will always use proxy mounting:
+
+```python
+# Create a proxy for a remote server
+remote_proxy = FastMCP.as_proxy(Client("http://example.com/mcp"))
+
+# Mount the proxy (always uses proxy mounting)
+main_server.mount(remote_proxy, prefix="remote")
+```
+
+
+
+## Tag Filtering with Composition
+
+<VersionBadge version="2.9.0" />
+
+When using `include_tags` or `exclude_tags` on a parent server, these filters apply **recursively** to all components, including those from mounted or imported servers. This allows you to control which components are exposed at the parent level, regardless of how your application is composed.
+
+```python
+import asyncio
+from fastmcp import FastMCP, Client
+
+# Create a subserver with tools tagged for different environments
+api_server = FastMCP(name="APIServer")
+
+@api_server.tool(tags={"production"})
+def prod_endpoint() -> str:
+    """Production-ready endpoint."""
+    return "Production data"
+
+@api_server.tool(tags={"development"})
+def dev_endpoint() -> str:
+    """Development-only endpoint."""
+    return "Debug data"
+
+# Mount the subserver with production tag filtering at parent level
+prod_app = FastMCP(name="ProductionApp", include_tags={"production"})
+prod_app.mount(api_server, prefix="api")
+
+# Test the filtering
+async def test_filtering():
+    async with Client(prod_app) as client:
+        tools = await client.list_tools()
+        print("Available tools:", [t.name for t in tools])
+        # Shows: ['api_prod_endpoint']
+        # The 'api_dev_endpoint' is filtered out
+
+        # Calling the filtered tool raises an error
+        try:
+            await client.call_tool("api_dev_endpoint")
+        except Exception as e:
+            print(f"Filtered tool not accessible: {e}")
+
+if __name__ == "__main__":
+    asyncio.run(test_filtering())
+```
+
+### How Recursive Filtering Works
+
+Tag filters apply in the following order:
+
+1. **Child Server Filters**: Each mounted/imported server first applies its own `include_tags`/`exclude_tags` to its components.
+2. **Parent Server Filters**: The parent server then applies its own `include_tags`/`exclude_tags` to all components, including those from child servers.
+
+This ensures that parent server tag policies act as a global policy for everything the parent server exposes, no matter how your application is composed.
+
+<Note>
+This filtering applies to both **listing** (e.g., `list_tools()`) and **execution** (e.g., `call_tool()`). Filtered components are neither visible nor executable through the parent server.
+</Note>
diff --git a/docs/v2/servers/context.mdx b/docs/v2/servers/context.mdx
new file mode 100644
index 0000000..3b224fd
--- /dev/null
+++ b/docs/v2/servers/context.mdx
@@ -0,0 +1,613 @@
+---
+title: MCP Context
+sidebarTitle: Context
+description: Access MCP capabilities like logging, progress, and resources within your MCP objects.
+icon: rectangle-code
+---
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+When defining FastMCP [tools](/v2/servers/tools), [resources](/v2/servers/resources), resource templates, or [prompts](/v2/servers/prompts), your functions might need to interact with the underlying MCP session or access advanced server capabilities. FastMCP provides the `Context` object for this purpose.
+
+<Note>
+FastMCP uses [Docket](https://github.com/chrisguidry/docket)'s dependency injection system for managing runtime dependencies. This page covers Context and the built-in dependencies; see [Custom Dependencies](#custom-dependencies) for creating your own.
+</Note>
+
+## What Is Context?
+
+The `Context` object provides a clean interface to access MCP features within your functions, including:
+
+- **Logging**: Send debug, info, warning, and error messages back to the client
+- **Progress Reporting**: Update the client on the progress of long-running operations
+- **Resource Access**: List and read data from resources registered with the server
+- **Prompt Access**: List and retrieve prompts registered with the server
+- **LLM Sampling**: Request the client's LLM to generate text based on provided messages
+- **User Elicitation**: Request structured input from users during tool execution
+- **State Management**: Store and share data between middleware and the handler within a single request
+- **Request Information**: Access metadata about the current request
+- **Server Access**: When needed, access the underlying FastMCP server instance
+
+## Accessing the Context
+
+<VersionBadge version="2.14" />
+
+The preferred way to access context is using the `CurrentContext()` dependency:
+
+```python {1, 6}
+from fastmcp import FastMCP
+from fastmcp.dependencies import CurrentContext
+from fastmcp.server.context import Context
+
+mcp = FastMCP(name="Context Demo")
+
+@mcp.tool
+async def process_file(file_uri: str, ctx: Context = CurrentContext()) -> str:
+    """Processes a file, using context for logging and resource access."""
+    await ctx.info(f"Processing {file_uri}")
+    return "Processed file"
+```
+
+This works with tools, resources, and prompts:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.dependencies import CurrentContext
+from fastmcp.server.context import Context
+
+mcp = FastMCP(name="Context Demo")
+
+@mcp.resource("resource://user-data")
+async def get_user_data(ctx: Context = CurrentContext()) -> dict:
+    await ctx.debug("Fetching user data")
+    return {"user_id": "example"}
+
+@mcp.prompt
+async def data_analysis_request(dataset: str, ctx: Context = CurrentContext()) -> str:
+    return f"Please analyze the following dataset: {dataset}"
+```
+
+**Key Points:**
+
+- Dependency parameters are automatically excluded from the MCP schema—clients never see them.
+- Context methods are async, so your function usually needs to be async as well.
+- **Each MCP request receives a new context object.** Context is scoped to a single request; state or data set in one request will not be available in subsequent requests.
+- Context is only available during a request; attempting to use context methods outside a request will raise errors.
+
+### Legacy Type-Hint Injection
+
+For backwards compatibility, you can still access context by simply adding a parameter with the `Context` type hint. FastMCP will automatically inject the context instance:
+
+```python {1, 6}
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP(name="Context Demo")
+
+@mcp.tool
+async def process_file(file_uri: str, ctx: Context) -> str:
+    """Processes a file, using context for logging and resource access."""
+    # Context is injected automatically based on the type hint
+    return "Processed file"
+```
+
+This approach still works for tools, resources, and prompts. The parameter name doesn't matter—only the `Context` type hint is important. The type hint can also be a union (`Context | None`) or use `Annotated[]`.
+
+### Via `get_context()` Function
+
+<VersionBadge version="2.2.11" />
+
+For code nested deeper within your function calls where passing context through parameters is inconvenient, use `get_context()` to retrieve the active context from anywhere within a request's execution flow:
+
+```python {2,9}
+from fastmcp import FastMCP
+from fastmcp.server.dependencies import get_context
+
+mcp = FastMCP(name="Dependency Demo")
+
+# Utility function that needs context but doesn't receive it as a parameter
+async def process_data(data: list[float]) -> dict:
+    # Get the active context - only works when called within a request
+    ctx = get_context()
+    await ctx.info(f"Processing {len(data)} data points")
+
+@mcp.tool
+async def analyze_dataset(dataset_name: str) -> dict:
+    # Call utility function that uses context internally
+    data = load_data(dataset_name)
+    await process_data(data)
+```
+
+**Important Notes:**
+
+- The `get_context()` function should only be used within the context of a server request. Calling it outside of a request will raise a `RuntimeError`.
+- The `get_context()` function is server-only and should not be used in client code.
+
+## Context Capabilities
+
+FastMCP provides several advanced capabilities through the context object. Each capability has dedicated documentation with comprehensive examples and best practices:
+
+### Logging
+
+Send debug, info, warning, and error messages back to the MCP client for visibility into function execution.
+
+```python
+await ctx.debug("Starting analysis")
+await ctx.info(f"Processing {len(data)} items") 
+await ctx.warning("Deprecated parameter used")
+await ctx.error("Processing failed")
+```
+
+See [Server Logging](/v2/servers/logging) for complete documentation and examples.
+### Client Elicitation
+
+<VersionBadge version="2.10.0" />
+
+Request structured input from clients during tool execution, enabling interactive workflows and progressive disclosure. This is a new feature in the 6/18/2025 MCP spec.
+
+```python
+result = await ctx.elicit("Enter your name:", response_type=str)
+if result.action == "accept":
+    name = result.data
+```
+
+See [User Elicitation](/v2/servers/elicitation) for detailed examples and supported response types.
+
+### LLM Sampling
+
+<VersionBadge version="2.0.0" />
+
+Request the client's LLM to generate text based on provided messages, useful for leveraging AI capabilities within your tools.
+
+```python
+response = await ctx.sample("Analyze this data", temperature=0.7)
+```
+
+See [LLM Sampling](/v2/servers/sampling) for comprehensive usage and advanced techniques.
+
+
+### Progress Reporting
+
+Update clients on the progress of long-running operations, enabling progress indicators and better user experience.
+
+```python
+await ctx.report_progress(progress=50, total=100)  # 50% complete
+```
+
+See [Progress Reporting](/v2/servers/progress) for detailed patterns and examples.
+
+### Resource Access
+
+List and read data from resources registered with your FastMCP server, allowing access to files, configuration, or dynamic content.
+
+```python
+# List available resources
+resources = await ctx.list_resources()
+
+# Read a specific resource
+content_list = await ctx.read_resource("resource://config")
+content = content_list[0].content
+```
+
+**Method signatures:**
+- **`ctx.list_resources() -> list[MCPResource]`**: <VersionBadge version="2.13.0" /> Returns list of all available resources
+- **`ctx.read_resource(uri: str | AnyUrl) -> list[ReadResourceContents]`**: Returns a list of resource content parts
+
+### Prompt Access
+
+<VersionBadge version="2.13.0" />
+
+List and retrieve prompts registered with your FastMCP server, allowing tools and middleware to discover and use available prompts programmatically.
+
+```python
+# List available prompts
+prompts = await ctx.list_prompts()
+
+# Get a specific prompt with arguments
+result = await ctx.get_prompt("analyze_data", {"dataset": "users"})
+messages = result.messages
+```
+
+**Method signatures:**
+- **`ctx.list_prompts() -> list[MCPPrompt]`**: Returns list of all available prompts
+- **`ctx.get_prompt(name: str, arguments: dict[str, Any] | None = None) -> GetPromptResult`**: Get a specific prompt with optional arguments
+
+### State Management
+
+<VersionBadge version="2.11.0" />
+
+Store and share data between middleware and handlers within a single MCP request. Each MCP request (such as calling a tool, reading a resource, listing tools, or listing resources) receives its own context object with isolated state. Context state is particularly useful for passing information from [middleware](/v2/servers/middleware) to your handlers.
+
+To store a value in the context state, use `ctx.set_state(key, value)`. To retrieve a value, use `ctx.get_state(key)`.
+
+<Warning>
+Context state is scoped to a single MCP request. Each operation (tool call, resource read, list operation, etc.) receives a new context object. State set during one request will not be available in subsequent requests. For persistent data storage across requests, use external storage mechanisms like databases, files, or in-memory caches.
+</Warning>
+
+This simplified example shows how to use MCP middleware to store user info in the context state, and how to access that state in a tool:
+
+```python {7-8, 16-17}
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+class UserAuthMiddleware(Middleware):
+    async def on_call_tool(self, context: MiddlewareContext, call_next):
+
+        # Middleware stores user info in context state
+        context.fastmcp_context.set_state("user_id", "user_123")
+        context.fastmcp_context.set_state("permissions", ["read", "write"])
+
+        return await call_next(context)
+
+@mcp.tool
+async def secure_operation(data: str, ctx: Context) -> str:
+    """Tool can access state set by middleware."""
+
+    user_id = ctx.get_state("user_id")  # "user_123"
+    permissions = ctx.get_state("permissions")  # ["read", "write"]
+    
+    if "write" not in permissions:
+        return "Access denied"
+    
+    return f"Processing {data} for user {user_id}"
+```
+
+**Method signatures:**
+- **`ctx.set_state(key: str, value: Any) -> None`**: Store a value in the context state
+- **`ctx.get_state(key: str) -> Any`**: Retrieve a value from the context state (returns None if not found)
+
+**State Inheritance:**
+When a new context is created (nested contexts), it inherits a copy of its parent's state. This ensures that:
+- State set on a child context never affects the parent context
+- State set on a parent context after the child context is initialized is not propagated to the child context
+
+This makes state management predictable and prevents unexpected side effects between nested operations.
+
+### Change Notifications
+
+<VersionBadge version="2.9.1" />
+
+FastMCP automatically sends list change notifications when components (such as tools, resources, or prompts) are added, removed, enabled, or disabled. In rare cases where you need to manually trigger these notifications, you can use the context methods:
+
+```python
+@mcp.tool
+async def custom_tool_management(ctx: Context) -> str:
+    """Example of manual notification after custom tool changes."""
+    # After making custom changes to tools
+    await ctx.send_tool_list_changed()
+    await ctx.send_resource_list_changed()
+    await ctx.send_prompt_list_changed()
+    return "Notifications sent"
+```
+
+These methods are primarily used internally by FastMCP's automatic notification system and most users will not need to invoke them directly.
+
+### FastMCP Server
+
+To access the underlying FastMCP server instance, you can use the `ctx.fastmcp` property:
+
+```python
+@mcp.tool
+async def my_tool(ctx: Context) -> None:
+    # Access the FastMCP server instance
+    server_name = ctx.fastmcp.name
+    ...
+```
+
+### MCP Request
+
+Access metadata about the current request and client.
+
+```python
+@mcp.tool
+async def request_info(ctx: Context) -> dict:
+    """Return information about the current request."""
+    return {
+        "request_id": ctx.request_id,
+        "client_id": ctx.client_id or "Unknown client"
+    }
+```
+
+**Available Properties:**
+
+- **`ctx.request_id -> str`**: Get the unique ID for the current MCP request
+- **`ctx.client_id -> str | None`**: Get the ID of the client making the request, if provided during initialization
+- **`ctx.session_id -> str | None`**: Get the MCP session ID for session-based data sharing (HTTP transports only)
+
+#### Request Context Availability
+
+<VersionBadge version="2.13.1" />
+
+The `ctx.request_context` property provides access to the underlying MCP request context, but returns `None` when the MCP session has not been established yet. This typically occurs:
+
+- During middleware execution in the `on_request` hook before the MCP handshake completes
+- During the initialization phase of client connections
+
+The MCP request context is distinct from the HTTP request. For HTTP transports, HTTP request data may be available even when the MCP session is not yet established.
+
+To safely access the request context in situations where it may not be available:
+
+```python
+from fastmcp import FastMCP, Context
+from fastmcp.server.dependencies import get_http_request
+
+mcp = FastMCP(name="Session Aware Demo")
+
+@mcp.tool
+async def session_info(ctx: Context) -> dict:
+    """Return session information when available."""
+
+    # Check if MCP session is available
+    if ctx.request_context:
+        # MCP session available - can access MCP-specific attributes
+        return {
+            "session_id": ctx.session_id,
+            "request_id": ctx.request_id,
+            "has_meta": ctx.request_context.meta is not None
+        }
+    else:
+        # MCP session not available - use HTTP helpers for request data (if using HTTP transport)
+        request = get_http_request()
+        return {
+            "message": "MCP session not available",
+            "user_agent": request.headers.get("user-agent", "Unknown")
+        }
+```
+
+For HTTP request access that works regardless of MCP session availability (when using HTTP transports), use the [HTTP request helpers](#http-requests) like `get_http_request()` and `get_http_headers()`.
+
+#### Client Metadata
+
+<VersionBadge version="2.13.1" />
+
+Clients can send contextual information with their requests using the `meta` parameter. This metadata is accessible through `ctx.request_context.meta` and is available for all MCP operations (tools, resources, prompts).
+
+The `meta` field is `None` when clients don't provide metadata. When provided, metadata is accessible via attribute access (e.g., `meta.user_id`) rather than dictionary access. The structure of metadata is determined by the client making the request.
+
+```python
+@mcp.tool
+def send_email(to: str, subject: str, body: str, ctx: Context) -> str:
+    """Send an email, logging metadata about the request."""
+
+    # Access client-provided metadata
+    meta = ctx.request_context.meta
+
+    if meta:
+        # Meta is accessed as an object with attribute access
+        user_id = meta.user_id if hasattr(meta, 'user_id') else None
+        trace_id = meta.trace_id if hasattr(meta, 'trace_id') else None
+
+        # Use metadata for logging, observability, etc.
+        if trace_id:
+            log_with_trace(f"Sending email for user {user_id}", trace_id)
+
+    # Send the email...
+    return f"Email sent to {to}"
+```
+
+<Warning>
+The MCP request is part of the low-level MCP SDK and intended for advanced use cases. Most users will not need to use it directly.
+</Warning>
+
+## Runtime Dependencies
+
+### HTTP Requests
+
+<VersionBadge version="2.2.11" />
+
+The recommended way to access the current HTTP request is through the `get_http_request()` dependency function:
+
+```python {2, 3, 11}
+from fastmcp import FastMCP
+from fastmcp.server.dependencies import get_http_request
+from starlette.requests import Request
+
+mcp = FastMCP(name="HTTP Request Demo")
+
+@mcp.tool
+async def user_agent_info() -> dict:
+    """Return information about the user agent."""
+    # Get the HTTP request
+    request: Request = get_http_request()
+    
+    # Access request data
+    user_agent = request.headers.get("user-agent", "Unknown")
+    client_ip = request.client.host if request.client else "Unknown"
+    
+    return {
+        "user_agent": user_agent,
+        "client_ip": client_ip,
+        "path": request.url.path,
+    }
+```
+
+This approach works anywhere within a request's execution flow, not just within your MCP function. It's useful when:
+
+1. You need access to HTTP information in helper functions
+2. You're calling nested functions that need HTTP request data
+3. You're working with middleware or other request processing code
+
+### HTTP Headers
+<VersionBadge version="2.2.11" />
+
+If you only need request headers and want to avoid potential errors, you can use the `get_http_headers()` helper:
+
+```python {2, 10}
+from fastmcp import FastMCP
+from fastmcp.server.dependencies import get_http_headers
+
+mcp = FastMCP(name="Headers Demo")
+
+@mcp.tool
+async def safe_header_info() -> dict:
+    """Safely get header information without raising errors."""
+    # Get headers (returns empty dict if no request context)
+    headers = get_http_headers()
+    
+    # Get authorization header
+    auth_header = headers.get("authorization", "")
+    is_bearer = auth_header.startswith("Bearer ")
+    
+    return {
+        "user_agent": headers.get("user-agent", "Unknown"),
+        "content_type": headers.get("content-type", "Unknown"),
+        "has_auth": bool(auth_header),
+        "auth_type": "Bearer" if is_bearer else "Other" if auth_header else "None",
+        "headers_count": len(headers)
+    }
+```
+
+By default, `get_http_headers()` excludes problematic headers like `host` and `content-length`. To include all headers, use `get_http_headers(include_all=True)`.
+
+### Access Tokens
+
+<VersionBadge version="2.11.0" />
+
+When using authentication with your FastMCP server, you can access the authenticated user's access token information using the `get_access_token()` dependency function:
+
+```python {2, 10}
+from fastmcp import FastMCP
+from fastmcp.server.dependencies import get_access_token, AccessToken
+
+mcp = FastMCP(name="Auth Token Demo")
+
+@mcp.tool
+async def get_user_info() -> dict:
+    """Get information about the authenticated user."""
+    # Get the access token (None if not authenticated)
+    token: AccessToken | None = get_access_token()
+    
+    if token is None:
+        return {"authenticated": False}
+    
+    return {
+        "authenticated": True,
+        "client_id": token.client_id,
+        "scopes": token.scopes,
+        "expires_at": token.expires_at,
+        "token_claims": token.claims,  # JWT claims or custom token data
+    }
+```
+
+This is particularly useful when you need to:
+
+1. **Access user identification** - Get the `client_id` or subject from token claims
+2. **Check permissions** - Verify scopes or custom claims before performing operations
+3. **Multi-tenant applications** - Extract tenant information from token claims
+4. **Audit logging** - Track which user performed which actions
+
+#### Working with Token Claims
+
+The `claims` field contains all the data from the original token (JWT claims for JWT tokens, or custom data for other token types):
+
+```python {2, 3, 9, 12, 15}
+from fastmcp import FastMCP
+from fastmcp.server.dependencies import get_access_token
+
+mcp = FastMCP(name="Multi-tenant Demo")
+
+@mcp.tool
+async def get_tenant_data(resource_id: str) -> dict:
+    """Get tenant-specific data using token claims."""
+    token: AccessToken | None = get_access_token()
+    
+    # Extract tenant ID from token claims
+    tenant_id = token.claims.get("tenant_id") if token else None
+    
+    # Extract user ID from standard JWT subject claim
+    user_id = token.claims.get("sub") if token else None
+    
+    # Use tenant and user info to authorize and filter data
+    if not tenant_id:
+        raise ValueError("No tenant information in token")
+    
+    return {
+        "resource_id": resource_id,
+        "tenant_id": tenant_id,
+        "user_id": user_id,
+        "data": f"Tenant-specific data for {tenant_id}",
+    }
+```
+
+## Custom Dependencies
+
+<VersionBadge version="2.14" />
+
+FastMCP's dependency injection is powered by [Docket](https://github.com/chrisguidry/docket), which provides a flexible system for injecting values into your functions. Beyond the built-in dependencies like `CurrentContext()`, you can create your own.
+
+### Using `Depends()`
+
+The simplest way to create a custom dependency is with `Depends()`. Pass any callable (sync or async function, or async context manager) and its return value will be injected:
+
+```python
+from contextlib import asynccontextmanager
+from fastmcp import FastMCP
+from fastmcp.dependencies import Depends
+
+mcp = FastMCP(name="Custom Deps Demo")
+
+# Simple function dependency
+def get_config() -> dict:
+    return {"api_url": "https://api.example.com", "timeout": 30}
+
+# Async function dependency
+async def get_user_id() -> int:
+    return 42
+
+@mcp.tool
+async def fetch_data(
+    query: str,
+    config: dict = Depends(get_config),
+    user_id: int = Depends(get_user_id),
+) -> str:
+    return f"User {user_id} fetching '{query}' from {config['api_url']}"
+```
+
+Dependencies using `Depends()` are automatically excluded from the MCP schema—clients never see them as parameters.
+
+### Resource Management with Context Managers
+
+For dependencies that need cleanup (database connections, file handles, etc.), use an async context manager:
+
+```python
+from contextlib import asynccontextmanager
+from fastmcp import FastMCP
+from fastmcp.dependencies import Depends
+
+mcp = FastMCP(name="Resource Demo")
+
+@asynccontextmanager
+async def get_database():
+    db = await connect_to_database()
+    try:
+        yield db
+    finally:
+        await db.close()
+
+@mcp.tool
+async def query_users(sql: str, db = Depends(get_database)) -> list:
+    return await db.execute(sql)
+```
+
+The context manager's cleanup code runs after your function completes, even if an error occurs.
+
+### Nested Dependencies
+
+Dependencies can depend on other dependencies:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.dependencies import Depends
+
+mcp = FastMCP(name="Nested Demo")
+
+def get_base_url() -> str:
+    return "https://api.example.com"
+
+def get_api_client(base_url: str = Depends(get_base_url)) -> dict:
+    return {"base_url": base_url, "version": "v1"}
+
+@mcp.tool
+async def call_api(endpoint: str, client: dict = Depends(get_api_client)) -> str:
+    return f"Calling {client['base_url']}/{client['version']}/{endpoint}"
+```
+
+### Advanced: Subclassing `Dependency`
+
+For more complex dependency patterns—like dependencies that need access to Docket's execution context or require custom lifecycle management—you can subclass Docket's `Dependency` class. See the [Docket documentation on dependencies](https://chrisguidry.github.io/docket/dependencies/) for details.
diff --git a/docs/v2/servers/elicitation.mdx b/docs/v2/servers/elicitation.mdx
new file mode 100644
index 0000000..a63f171
--- /dev/null
+++ b/docs/v2/servers/elicitation.mdx
@@ -0,0 +1,462 @@
+---
+title: User Elicitation
+sidebarTitle: Elicitation
+description: Request structured input from users during tool execution through the MCP context.
+icon: message-question
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.10.0" />
+
+User elicitation allows MCP servers to request structured input from users during tool execution. Instead of requiring all inputs upfront, tools can interactively ask for missing parameters, clarification, or additional context as needed.
+
+<Tip>
+Most of the examples in this document assume you have a FastMCP server instance named `mcp` and show how to use the `ctx.elicit` method to request user input from an `@mcp.tool`-decorated function.
+</Tip>
+
+## What is Elicitation?
+
+Elicitation enables tools to pause execution and request specific information from users. This is particularly useful for:
+
+- **Missing parameters**: Ask for required information not provided initially
+- **Clarification requests**: Get user confirmation or choices for ambiguous scenarios  
+- **Progressive disclosure**: Collect complex information step-by-step
+- **Dynamic workflows**: Adapt tool behavior based on user responses
+
+For example, a file management tool might ask "Which directory should I create?" or a data analysis tool might request "What date range should I analyze?"
+
+### Basic Usage
+
+Use the `ctx.elicit()` method within any tool function to request user input:
+
+```python {14-17}
+from fastmcp import FastMCP, Context
+from dataclasses import dataclass
+
+mcp = FastMCP("Elicitation Server")
+
+@dataclass
+class UserInfo:
+    name: str
+    age: int
+
+@mcp.tool
+async def collect_user_info(ctx: Context) -> str:
+    """Collect user information through interactive prompts."""
+    result = await ctx.elicit(
+        message="Please provide your information",
+        response_type=UserInfo
+    )
+    
+    if result.action == "accept":
+        user = result.data
+        return f"Hello {user.name}, you are {user.age} years old"
+    elif result.action == "decline":
+        return "Information not provided"
+    else:  # cancel
+        return "Operation cancelled"
+```
+
+## Method Signature
+
+<Card icon="code" title="Context Elicitation Method">
+<ResponseField name="ctx.elicit" type="async method">
+  <Expandable title="Parameters">
+    <ResponseField name="message" type="str">
+      The prompt message to display to the user
+    </ResponseField>
+    
+    <ResponseField name="response_type" type="type" default="None">
+      The Python type defining the expected response structure (dataclass, primitive type, etc.) Note that elicitation responses are subject to a restricted subset of JSON Schema types. See [Supported Response Types](#supported-response-types) for more details. 
+    </ResponseField>
+  </Expandable>
+  
+  <Expandable title="Response">
+    <ResponseField name="ElicitationResult" type="object">
+      Result object containing the user's response
+      
+      <Expandable title="properties">
+        <ResponseField name="action" type="Literal['accept', 'decline', 'cancel']">
+          How the user responded to the request
+        </ResponseField>
+        
+        <ResponseField name="data" type="response_type | None">
+          The user's input data (only present when action is "accept")
+        </ResponseField>
+      </Expandable>
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+</Card>
+
+## Elicitation Actions
+
+The elicitation result contains an `action` field indicating how the user responded:
+
+- **`accept`**: User provided valid input - data is available in the `data` field
+- **`decline`**: User chose not to provide the requested information and the data field is `None`
+- **`cancel`**: User cancelled the entire operation and the data field is `None`
+
+```python {5, 7}
+@mcp.tool
+async def my_tool(ctx: Context) -> str:
+    result = await ctx.elicit("Choose an action")
+
+    if result.action == "accept":
+        return "Accepted!"
+    elif result.action == "decline":
+        return "Declined!"
+    else:
+        return "Cancelled!"
+```
+
+FastMCP also provides typed result classes for pattern matching on the `action` field:
+
+```python {1-5, 12, 14, 16}
+from fastmcp.server.elicitation import (
+    AcceptedElicitation, 
+    DeclinedElicitation, 
+    CancelledElicitation,
+)
+
+@mcp.tool
+async def pattern_example(ctx: Context) -> str:
+    result = await ctx.elicit("Enter your name:", response_type=str)
+    
+    match result:
+        case AcceptedElicitation(data=name):
+            return f"Hello {name}!"
+        case DeclinedElicitation():
+            return "No name provided"
+        case CancelledElicitation():
+            return "Operation cancelled"
+```
+
+## Response Types
+
+The server must send a schema to the client indicating the type of data it expects in response to the elicitation request. If the request is `accept`-ed, the client must send a response that matches the schema.
+
+The MCP spec only supports a limited subset of JSON Schema types for elicitation responses. Specifically, it only supports JSON  **objects** with **primitive** properties including `string`, `number` (or `integer`), `boolean` and `enum` fields.
+
+FastMCP makes it easy to request a broader range of types, including scalars (e.g. `str`) or no response at all, by automatically wrapping them in MCP-compatible object schemas.
+
+
+### Scalar Types
+
+You can request simple scalar data types for basic input, such as a string, integer, or boolean.
+
+When you request a scalar type, FastMCP automatically wraps it in an object schema for MCP spec compatibility. Clients will see a corresponding schema requesting a single "value" field of the requested type. Once clients respond, the provided object is "unwrapped" and the scalar value is returned to your tool function as the `data` field of the `ElicitationResult` object.
+
+As a developer, this means you do not have to worry about creating or accessing a structured object when you only need a scalar value.
+
+<CodeGroup>
+```python {4} title="Request a string"
+@mcp.tool
+async def get_user_name(ctx: Context) -> str:
+    """Get the user's name."""
+    result = await ctx.elicit("What's your name?", response_type=str)
+    
+    if result.action == "accept":
+        return f"Hello, {result.data}!"
+    return "No name provided"
+```
+```python {4} title="Request an integer"
+@mcp.tool
+async def pick_a_number(ctx: Context) -> str:
+    """Pick a number."""
+    result = await ctx.elicit("Pick a number!", response_type=int)
+    
+    if result.action == "accept":
+        return f"You picked {result.data}"
+    return "No number provided"
+```
+```python {4} title="Request a boolean"
+@mcp.tool
+async def pick_a_boolean(ctx: Context) -> str:
+    """Pick a boolean."""
+    result = await ctx.elicit("True or false?", response_type=bool)
+    
+    if result.action == "accept":
+        return f"You picked {result.data}"
+    return "No boolean provided"
+```
+</CodeGroup>
+
+### No Response
+
+Sometimes, the goal of an elicitation is to simply get a user to approve or reject an action. In this case, you can pass `None` as the response type to indicate that no response is expected. In order to comply with the MCP spec, the client will see a schema requesting an empty object in response. In this case, the `data` field of the `ElicitationResult` object will be `None` when the user accepts the elicitation.
+
+```python {4} title="No response"
+@mcp.tool
+async def approve_action(ctx: Context) -> str:
+    """Approve an action."""
+    result = await ctx.elicit("Approve this action?", response_type=None)
+
+    if result.action == "accept":
+        return do_action()
+    else:
+        raise ValueError("Action rejected")
+```
+
+### Constrained Options
+
+Often you'll want to constrain the user's response to a specific set of values. You can do this by using a `Literal` type or a Python enum as the response type, or by passing a list of strings to the `response_type` parameter as a convenient shortcut.
+
+<CodeGroup>
+```python {6} title="Using a list of strings"
+@mcp.tool
+async def set_priority(ctx: Context) -> str:
+    """Set task priority level."""
+    result = await ctx.elicit(
+        "What priority level?",
+        response_type=["low", "medium", "high"],
+    )
+
+    if result.action == "accept":
+        return f"Priority set to: {result.data}"
+```
+```python {1, 8} title="Using a Literal type"
+from typing import Literal
+
+@mcp.tool
+async def set_priority(ctx: Context) -> str:
+    """Set task priority level."""
+    result = await ctx.elicit(
+        "What priority level?",
+        response_type=Literal["low", "medium", "high"]
+    )
+
+    if result.action == "accept":
+        return f"Priority set to: {result.data}"
+    return "No priority set"
+```
+```python {1, 11} title="Using a Python enum"
+from enum import Enum
+
+class Priority(Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+@mcp.tool
+async def set_priority(ctx: Context) -> str:
+    """Set task priority level."""
+    result = await ctx.elicit("What priority level?", response_type=Priority)
+
+    if result.action == "accept":
+        return f"Priority set to: {result.data.value}"
+    return "No priority set"
+```
+</CodeGroup>
+
+#### Multi-Select
+
+<VersionBadge version="2.14.0" />
+
+Enable multi-select by wrapping your choices in an additional list level. This allows users to select multiple values from the available options.
+
+<CodeGroup>
+```python {6-8} title="List of a list of strings"
+@mcp.tool
+async def select_tags(ctx: Context) -> str:
+    """Select multiple tags."""
+    result = await ctx.elicit(
+        "Choose tags",
+        response_type=[["bug", "feature", "documentation"]]  # Note: list of a list
+    )
+
+    if result.action == "accept":
+        tags = result.data  # List of selected strings
+        return f"Selected tags: {', '.join(tags)}"
+```
+
+```python {1, 3-6, 11-14} title="list[Enum] type annotation"
+from enum import Enum
+
+class Tag(Enum):
+    BUG = "bug"
+    FEATURE = "feature"
+    DOCS = "documentation"
+
+@mcp.tool
+async def select_tags(ctx: Context) -> str:
+    result = await ctx.elicit(
+        "Choose tags",
+        response_type=list[Tag]  # Type annotation for multi-select
+    )
+    if result.action == "accept":
+        tags = [tag.value for tag in result.data]
+        return f"Selected: {', '.join(tags)}"
+```
+</CodeGroup>
+
+For titled multi-select, wrap a dict in a list (see [Titled Options](#titled-options) for dict syntax):
+
+```python {6-12}
+@mcp.tool
+async def select_priorities(ctx: Context) -> str:
+    """Select multiple priorities."""
+    result = await ctx.elicit(
+        "Choose priorities",
+        response_type=[{  # Note: list containing a dict
+            "low": {"title": "Low Priority"},
+            "medium": {"title": "Medium Priority"},
+            "high": {"title": "High Priority"}
+        }]
+    )
+
+    if result.action == "accept":
+        priorities = result.data  # List of selected strings
+        return f"Selected: {', '.join(priorities)}"
+```
+
+#### Titled Options
+
+<VersionBadge version="2.14.0" />
+
+For better UI display, you can provide human-readable titles for enum options. FastMCP generates SEP-1330 compliant schemas using the `oneOf` pattern with `const` and `title` fields.
+
+Use a dict to specify titles for enum values:
+
+```python {6-10}
+@mcp.tool
+async def set_priority(ctx: Context) -> str:
+    """Set task priority level."""
+    result = await ctx.elicit(
+        "What priority level?",
+        response_type={
+            "low": {"title": "Low Priority"},
+            "medium": {"title": "Medium Priority"},
+            "high": {"title": "High Priority"}
+        }
+    )
+
+    if result.action == "accept":
+        return f"Priority set to: {result.data}"
+```
+
+For multi-select with titles, wrap the dict in a list:
+
+```python {6-12}
+@mcp.tool
+async def select_priorities(ctx: Context) -> str:
+    """Select multiple priorities."""
+    result = await ctx.elicit(
+        "Choose priorities",
+        response_type=[{  # List containing a dict for multi-select
+            "low": {"title": "Low Priority"},
+            "medium": {"title": "Medium Priority"},
+            "high": {"title": "High Priority"}
+        }]
+    )
+
+    if result.action == "accept":
+        priorities = result.data  # List of selected strings
+        return f"Selected: {', '.join(priorities)}"
+```
+
+### Structured Responses
+
+You can request structured data with multiple fields by using a dataclass, typed dict, or Pydantic model as the response type. Note that the MCP spec only supports shallow objects with scalar (string, number, boolean) or enum properties.
+
+```python {1, 16, 20}
+from dataclasses import dataclass
+from typing import Literal
+
+@dataclass
+class TaskDetails:
+    title: str
+    description: str
+    priority: Literal["low", "medium", "high"]
+    due_date: str
+
+@mcp.tool
+async def create_task(ctx: Context) -> str:
+    """Create a new task with user-provided details."""
+    result = await ctx.elicit(
+        "Please provide task details",
+        response_type=TaskDetails
+    )
+    
+    if result.action == "accept":
+        task = result.data
+        return f"Created task: {task.title} (Priority: {task.priority})"
+    return "Task creation cancelled"
+```
+
+### Default Values
+
+<VersionBadge version="2.14.0" />
+
+You can provide default values for elicitation fields using Pydantic's `Field(default=...)`. Clients will pre-populate form fields with these defaults, making it easier for users to provide input.
+
+Default values are supported for all primitive types:
+- Strings: `Field(default="[email protected]")`
+- Integers: `Field(default=50)`
+- Numbers: `Field(default=3.14)`
+- Booleans: `Field(default=False)`
+- Enums: `Field(default=EnumValue.A)`
+
+Fields with default values are automatically marked as optional (not included in the `required` list), so users can accept the default or provide their own value.
+
+```python
+from pydantic import BaseModel, Field
+from enum import Enum
+
+class Priority(Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+class TaskDetails(BaseModel):
+    title: str = Field(description="Task title")
+    description: str = Field(default="", description="Task description")
+    priority: Priority = Field(default=Priority.MEDIUM, description="Task priority")
+
+@mcp.tool
+async def create_task(ctx: Context) -> str:
+    result = await ctx.elicit("Please provide task details", response_type=TaskDetails)
+    if result.action == "accept":
+        return f"Created: {result.data.title}"
+    return "Task creation cancelled"
+```
+
+## Multi-Turn Elicitation
+
+Tools can make multiple elicitation calls to gather information progressively:
+
+```python {6, 11, 16-19}
+@mcp.tool
+async def plan_meeting(ctx: Context) -> str:
+    """Plan a meeting by gathering details step by step."""
+    
+    # Get meeting title
+    title_result = await ctx.elicit("What's the meeting title?", response_type=str)
+    if title_result.action != "accept":
+        return "Meeting planning cancelled"
+    
+    # Get duration
+    duration_result = await ctx.elicit("Duration in minutes?", response_type=int)
+    if duration_result.action != "accept":
+        return "Meeting planning cancelled"
+    
+    # Get priority
+    priority_result = await ctx.elicit(
+        "Is this urgent?", 
+        response_type=Literal["yes", "no"]
+    )
+    if priority_result.action != "accept":
+        return "Meeting planning cancelled"
+    
+    urgent = priority_result.data == "yes"
+    return f"Meeting '{title_result.data}' planned for {duration_result.data} minutes (Urgent: {urgent})"
+```
+
+
+## Client Requirements
+
+Elicitation requires the client to implement an elicitation handler. See [Client Elicitation](/v2/clients/elicitation) for details on how clients can handle these requests.
+
+If a client doesn't support elicitation, calls to `ctx.elicit()` will raise an error indicating that elicitation is not supported.
\ No newline at end of file
diff --git a/docs/v2/servers/icons.mdx b/docs/v2/servers/icons.mdx
new file mode 100644
index 0000000..a7d038f
--- /dev/null
+++ b/docs/v2/servers/icons.mdx
@@ -0,0 +1,139 @@
+---
+title: Icons
+description: Add visual icons to your servers, tools, resources, and prompts
+icon: image
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.13.0" />
+
+Icons provide visual representations for your MCP servers and components, helping client applications present better user interfaces. When displayed in MCP clients, icons help users quickly identify and navigate your server's capabilities.
+
+## Icon Format
+
+Icons use the standard MCP Icon type from the MCP protocol specification. Each icon specifies:
+
+- **src**: URL or data URI pointing to the icon image
+- **mimeType** (optional): MIME type of the image (e.g., "image/png", "image/svg+xml")
+- **sizes** (optional): Array of size descriptors (e.g., ["48x48"], ["any"])
+
+```python
+from mcp.types import Icon
+
+icon = Icon(
+    src="https://example.com/icon.png",
+    mimeType="image/png",
+    sizes=["48x48"]
+)
+```
+
+## Server Icons
+
+Add icons and a website URL to your server for display in client applications:
+
+```python
+from fastmcp import FastMCP
+from mcp.types import Icon
+
+mcp = FastMCP(
+    name="WeatherService",
+    website_url="https://weather.example.com",
+    icons=[
+        Icon(
+            src="https://weather.example.com/icon-48.png",
+            mimeType="image/png",
+            sizes=["48x48"]
+        ),
+        Icon(
+            src="https://weather.example.com/icon-96.png",
+            mimeType="image/png",
+            sizes=["96x96"]
+        ),
+    ]
+)
+```
+
+Server icons appear in MCP client interfaces to help users identify your server among others they may have installed.
+
+## Component Icons
+
+Icons can be added to individual tools, resources, resource templates, and prompts:
+
+### Tool Icons
+
+```python
+from mcp.types import Icon
+
+@mcp.tool(
+    icons=[Icon(src="https://example.com/calculator-icon.png")]
+)
+def calculate_sum(a: int, b: int) -> int:
+    """Add two numbers together."""
+    return a + b
+```
+
+### Resource Icons
+
+```python
+@mcp.resource(
+    "config://settings",
+    icons=[Icon(src="https://example.com/config-icon.png")]
+)
+def get_settings() -> dict:
+    """Retrieve application settings."""
+    return {"theme": "dark", "language": "en"}
+```
+
+### Resource Template Icons
+
+```python
+@mcp.resource(
+    "user://{user_id}/profile",
+    icons=[Icon(src="https://example.com/user-icon.png")]
+)
+def get_user_profile(user_id: str) -> dict:
+    """Get a user's profile."""
+    return {"id": user_id, "name": f"User {user_id}"}
+```
+
+### Prompt Icons
+
+```python
+@mcp.prompt(
+    icons=[Icon(src="https://example.com/prompt-icon.png")]
+)
+def analyze_code(code: str):
+    """Create a prompt for code analysis."""
+    return f"Please analyze this code:\n\n{code}"
+```
+
+## Using Data URIs
+
+For small icons or when you want to embed the icon directly, use data URIs:
+
+```python
+from mcp.types import Icon
+from fastmcp.utilities.types import Image
+
+# SVG icon as data URI
+svg_icon = Icon(
+    src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCI+PHBhdGggZD0iTTEyIDJDNi40OCAyIDIgNi40OCAyIDEyczQuNDggMTAgMTAgMTAgMTAtNC40OCAxMC0xMFMxNy41MiAyIDEyIDJ6Ii8+PC9zdmc+",
+    mimeType="image/svg+xml"
+)
+
+@mcp.tool(icons=[svg_icon])
+def my_tool() -> str:
+    """A tool with an embedded SVG icon."""
+    return "result"
+
+# Generating a data URI from a local image file.
+img = Image(path="./assets/brand/favicon.png")
+icon = Icon(src=img.to_data_uri())
+
+@mcp.tool(icons=[icon])
+def file_icon_tool() -> str:
+    """A tool with an icon generated from a local file."""
+    return "result"
+```
diff --git a/docs/v2/servers/logging.mdx b/docs/v2/servers/logging.mdx
new file mode 100644
index 0000000..14f9a9d
--- /dev/null
+++ b/docs/v2/servers/logging.mdx
@@ -0,0 +1,249 @@
+---
+title: Client Logging
+sidebarTitle: Logging
+description: Send log messages back to MCP clients through the context.
+icon: receipt
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<Tip>
+This documentation covers **MCP client logging** - sending messages from your server to MCP clients. For standard server-side logging (e.g., writing to files, console), use `fastmcp.utilities.logging.get_logger()` or Python's built-in `logging` module.
+</Tip>
+
+Server logging allows MCP tools to send debug, info, warning, and error messages back to the client. This provides visibility into function execution and helps with debugging during development and operation.
+
+## Why Use Server Logging?
+
+Server logging is essential for:
+
+- **Debugging**: Send detailed execution information to help diagnose issues
+- **Progress visibility**: Keep users informed about what the tool is doing
+- **Error reporting**: Communicate problems and their context to clients
+- **Audit trails**: Create records of tool execution for compliance or analysis
+
+Unlike standard Python logging, MCP server logging sends messages directly to the client, making them visible in the client's interface or logs.
+
+### Basic Usage
+
+Use the context logging methods within any tool function:
+
+```python {8-9, 13, 17, 21}
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP("LoggingDemo")
+
+@mcp.tool
+async def analyze_data(data: list[float], ctx: Context) -> dict:
+    """Analyze numerical data with comprehensive logging."""
+    await ctx.debug("Starting analysis of numerical data")
+    await ctx.info(f"Analyzing {len(data)} data points")
+    
+    try:
+        if not data:
+            await ctx.warning("Empty data list provided")
+            return {"error": "Empty data list"}
+        
+        result = sum(data) / len(data)
+        await ctx.info(f"Analysis complete, average: {result}")
+        return {"average": result, "count": len(data)}
+        
+    except Exception as e:
+        await ctx.error(f"Analysis failed: {str(e)}")
+        raise
+```
+
+## Structured Logging with `extra`
+
+All logging methods (`debug`, `info`, `warning`, `error`, `log`) now accept an `extra` parameter, which is a dictionary of arbitrary data. This allows you to send structured data to the client, which is useful for creating rich, queryable logs.
+
+```python
+@mcp.tool
+async def process_transaction(transaction_id: str, amount: float, ctx: Context):
+    await ctx.info(
+        f"Processing transaction {transaction_id}",
+        extra={
+            "transaction_id": transaction_id,
+            "amount": amount,
+            "currency": "USD"
+        }
+    )
+    # ... processing logic ...
+```
+
+## Server Logs
+
+Client Logging in the form of `ctx.log()` and its convenience methods (`debug`, `info`, `warning`, `error`) are meant for sending messages to the MCP clients. Messages sent to clients are also logged to the server's log at `DEBUG` level. Enable debug logging on the server or enable debug logging on the `fastmcp.server.context.to_client` logger to see these messages in the server's log.
+
+```python
+import logging
+
+from fastmcp.utilities.logging import get_logger
+
+to_client_logger = get_logger(name="fastmcp.server.context.to_client")
+to_client_logger.setLevel(level=logging.DEBUG)
+```
+
+## Logging Methods
+
+<Card icon="code" title="Context Logging Methods">
+<ResponseField name="ctx.debug" type="async method">
+  Send debug-level messages for detailed execution information
+
+  <Expandable title="parameters">
+    <ResponseField name="message" type="str">
+      The debug message to send to the client
+    </ResponseField>
+    <ResponseField name="extra" type="dict | None" default="None">
+      Optional dictionary for structured logging data
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="ctx.info" type="async method">
+  Send informational messages about normal execution
+
+  <Expandable title="parameters">
+    <ResponseField name="message" type="str">
+      The information message to send to the client
+    </ResponseField>
+    <ResponseField name="extra" type="dict | None" default="None">
+      Optional dictionary for structured logging data
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="ctx.warning" type="async method">
+  Send warning messages for potential issues that didn't prevent execution
+
+  <Expandable title="parameters">
+    <ResponseField name="message" type="str">
+      The warning message to send to the client
+    </ResponseField>
+    <ResponseField name="extra" type="dict | None" default="None">
+      Optional dictionary for structured logging data
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="ctx.error" type="async method">
+  Send error messages for problems that occurred during execution
+
+  <Expandable title="parameters">
+    <ResponseField name="message" type="str">
+      The error message to send to the client
+    </ResponseField>
+    <ResponseField name="extra" type="dict | None" default="None">
+      Optional dictionary for structured logging data
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="ctx.log" type="async method">
+  Generic logging method with custom level and logger name
+
+  <Expandable title="parameters">
+    <ResponseField name="level" type="Literal['debug', 'info', 'warning', 'error']">
+      The log level for the message
+    </ResponseField>
+
+    <ResponseField name="message" type="str">
+      The message to send to the client
+    </ResponseField>
+
+    <ResponseField name="logger_name" type="str | None" default="None">
+      Optional custom logger name for categorizing messages
+    </ResponseField>
+    <ResponseField name="extra" type="dict | None" default="None">
+      Optional dictionary for structured logging data
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+</Card>
+
+## Log Levels
+
+### Debug
+Use for detailed information that's typically only useful when diagnosing problems:
+
+```python 
+@mcp.tool
+async def process_file(file_path: str, ctx: Context) -> str:
+    """Process a file with detailed debug logging."""
+    await ctx.debug(f"Starting to process file: {file_path}")
+    await ctx.debug("Checking file permissions")
+    
+    # File processing logic
+    await ctx.debug("File processing completed successfully")
+    return "File processed"
+```
+
+### Info
+Use for general information about normal program execution:
+
+```python
+@mcp.tool
+async def backup_database(ctx: Context) -> str:
+    """Backup database with progress information."""
+    await ctx.info("Starting database backup")
+    await ctx.info("Connecting to database")
+    await ctx.info("Backup completed successfully")
+    return "Database backed up"
+```
+
+### Warning
+Use for potentially harmful situations that don't prevent execution:
+
+```python
+@mcp.tool
+async def validate_config(config: dict, ctx: Context) -> dict:
+    """Validate configuration with warnings for deprecated options."""
+    if "old_api_key" in config:
+        await ctx.warning(
+            "Using deprecated 'old_api_key' field. Please use 'api_key' instead",
+            extra={"deprecated_field": "old_api_key"}
+        )
+    
+    if config.get("timeout", 30) > 300:
+        await ctx.warning(
+            "Timeout value is very high (>5 minutes), this may cause issues",
+            extra={"timeout_value": config.get("timeout")}
+        )
+    
+    return {"status": "valid", "warnings": "see logs"}
+```
+
+### Error
+Use for error events that might still allow the application to continue:
+
+```python
+@mcp.tool
+async def batch_process(items: list[str], ctx: Context) -> dict:
+    """Process multiple items, logging errors for failed items."""
+    successful = 0
+    failed = 0
+    
+    for item in items:
+        try:
+            # Process item
+            successful += 1
+        except Exception as e:
+            await ctx.error(
+                f"Failed to process item '{item}': {str(e)}",
+                extra={"failed_item": item}
+            )
+            failed += 1
+    
+    return {"successful": successful, "failed": failed}
+```
+
+
+## Client Handling
+
+Log messages are sent to the client through the MCP protocol. How clients handle these messages depends on their implementation:
+
+- **Development clients**: May display logs in real-time for debugging
+- **Production clients**: May store logs for later analysis or display to users
+- **Integration clients**: May forward logs to external logging systems
+
+See [Client Logging](/v2/clients/logging) for details on how clients can handle server log messages.
diff --git a/docs/v2/servers/middleware.mdx b/docs/v2/servers/middleware.mdx
new file mode 100644
index 0000000..f5cf71e
--- /dev/null
+++ b/docs/v2/servers/middleware.mdx
@@ -0,0 +1,816 @@
+---
+title: MCP Middleware
+sidebarTitle: Middleware
+description: Add cross-cutting functionality to your MCP server with middleware that can inspect, modify, and respond to all MCP requests and responses.
+icon: layer-group
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.9.0" />
+
+MCP middleware is a powerful concept that allows you to add cross-cutting functionality to your FastMCP server. Unlike traditional web middleware, MCP middleware is designed specifically for the Model Context Protocol, providing hooks for different types of MCP operations like tool calls, resource reads, and prompt requests.
+
+<Tip>
+MCP middleware is a FastMCP-specific concept and is not part of the official MCP protocol specification. This middleware system is designed to work with FastMCP servers and may not be compatible with other MCP implementations.
+</Tip>
+
+<Warning>
+MCP middleware is a brand new concept and may be subject to breaking changes in future versions.
+</Warning>
+
+## What is MCP Middleware?
+
+MCP middleware lets you intercept and modify MCP requests and responses as they flow through your server. Think of it as a pipeline where each piece of middleware can inspect what's happening, make changes, and then pass control to the next middleware in the chain.
+
+Common use cases for MCP middleware include:
+- **Authentication and Authorization**: Verify client permissions before executing operations
+- **Logging and Monitoring**: Track usage patterns and performance metrics
+- **Rate Limiting**: Control request frequency per client or operation type
+- **Request/Response Transformation**: Modify data before it reaches tools or after it leaves
+- **Caching**: Store frequently requested data to improve performance
+- **Error Handling**: Provide consistent error responses across your server
+
+## How Middleware Works
+
+FastMCP middleware operates on a pipeline model. When a request comes in, it flows through your middleware in the order they were added to the server. Each middleware can:
+
+1. **Inspect the incoming request** and its context
+2. **Modify the request** before passing it to the next middleware or handler
+3. **Execute the next middleware/handler** in the chain by calling `call_next()`
+4. **Inspect and modify the response** before returning it
+5. **Handle errors** that occur during processing
+
+The key insight is that middleware forms a chain where each piece decides whether to continue processing or stop the chain entirely.
+
+If you're familiar with ASGI middleware, the basic structure of FastMCP middleware will feel familiar. At its core, middleware is a callable class that receives a context object containing information about the current JSON-RPC message and a handler function to continue the middleware chain.
+
+It's important to understand that MCP operates on the [JSON-RPC specification](https://spec.modelcontextprotocol.io/specification/basic/transports/). While FastMCP presents requests and responses in a familiar way, these are fundamentally JSON-RPC messages, not HTTP request/response pairs like you might be used to in web applications. FastMCP middleware works with all [transport types](/v2/clients/transports), including local stdio transport and HTTP transports, though not all middleware implementations are compatible across all transports (e.g., middleware that inspects HTTP headers won't work with stdio transport).
+
+The most fundamental way to implement middleware is by overriding the `__call__` method on the `Middleware` base class:
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+class RawMiddleware(Middleware):
+    async def __call__(self, context: MiddlewareContext, call_next):
+        # This method receives ALL messages regardless of type
+        print(f"Raw middleware processing: {context.method}")
+        result = await call_next(context)
+        print(f"Raw middleware completed: {context.method}")
+        return result
+```
+
+This gives you complete control over every message that flows through your server, but requires you to handle all message types manually.
+
+## Middleware Hooks
+
+To make it easier for users to target specific types of messages, FastMCP middleware provides a variety of specialized hooks. Instead of implementing the raw `__call__` method, you can override specific hook methods that are called only for certain types of operations, allowing you to target exactly the level of specificity you need for your middleware logic.
+
+### Hook Hierarchy and Execution Order
+
+FastMCP provides multiple hooks that are called with varying levels of specificity. Understanding this hierarchy is crucial for effective middleware design.
+
+When a request comes in, **multiple hooks may be called for the same request**, going from general to specific:
+
+1. **`on_message`** - Called for ALL MCP messages (both requests and notifications)
+2. **`on_request` or `on_notification`** - Called based on the message type
+3. **Operation-specific hooks** - Called for specific MCP operations like `on_call_tool`
+
+For example, when a client calls a tool, your middleware will receive **multiple hook calls**:
+1. `on_message` and `on_request` for any initial tool discovery operations (list_tools)
+2. `on_message` (because it's any MCP message) for the tool call itself
+3. `on_request` (because tool calls expect responses) for the tool call itself
+4. `on_call_tool` (because it's specifically a tool execution) for the tool call itself
+
+Note that the MCP SDK may perform additional operations like listing tools for caching purposes, which will trigger additional middleware calls beyond just the direct tool execution.
+
+This hierarchy allows you to target your middleware logic with the right level of specificity. Use `on_message` for broad concerns like logging, `on_request` for authentication, and `on_call_tool` for tool-specific logic like performance monitoring.
+
+### Available Hooks
+<VersionBadge version="2.9.0" />
+
+- `on_message`: Called for all MCP messages (requests and notifications)
+- `on_request`: Called specifically for MCP requests (that expect responses)
+- `on_notification`: Called specifically for MCP notifications (fire-and-forget)
+
+- `on_call_tool`: Called when tools are being executed
+- `on_read_resource`: Called when resources are being read
+- `on_get_prompt`: Called when prompts are being retrieved
+- `on_list_tools`: Called when listing available tools
+- `on_list_resources`: Called when listing available resources
+- `on_list_resource_templates`: Called when listing resource templates
+- `on_list_prompts`: Called when listing available prompts
+<VersionBadge version="2.13.0" />
+- `on_initialize`: Called when a client connects and initializes the session (returns `None`)
+<Note>
+The `on_initialize` hook receives the client's initialization request but **returns `None`** rather than a result. The initialization response is handled internally by the MCP protocol and cannot be modified by middleware. This hook is useful for client detection, logging connections, or initializing session state, but not for modifying the initialization handshake itself.
+</Note>
+
+**Example:**
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+from mcp import McpError
+from mcp.types import ErrorData
+
+class InitializationMiddleware(Middleware):
+    async def on_initialize(self, context: MiddlewareContext, call_next):
+        # Check client capabilities before initialization
+        client_info = context.message.params.get("clientInfo", {})
+        client_name = client_info.get("name", "unknown")
+
+        # Reject unsupported clients BEFORE call_next
+        if client_name == "unsupported-client":
+            raise McpError(ErrorData(code=-32000, message="This client is not supported"))
+
+        # Log successful initialization
+        await call_next(context)
+        print(f"Client {client_name} initialized successfully")
+```
+
+<Warning>
+If you raise `McpError` in `on_initialize` **after** calling `call_next()`, the error will only be logged and will not be sent to the client. The initialization response has already been sent at that point. Always raise `McpError` **before** `call_next()` if you want to reject the initialization.
+</Warning>
+
+### MCP Session Availability in Middleware
+
+<VersionBadge version="2.13.1" />
+
+The MCP session and request context are not available during certain phases like initialization. When middleware runs during these phases, `context.fastmcp_context.request_context` returns `None` rather than the full MCP request context.
+
+This typically occurs when:
+- The `on_request` hook fires during client initialization
+- The MCP handshake hasn't completed yet
+
+To handle this in middleware, check if the MCP request context is available before accessing MCP-specific attributes. Note that the MCP request context is distinct from the HTTP request - for HTTP transports, you can use HTTP helpers to access request data even when the MCP session is not available:
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+class SessionAwareMiddleware(Middleware):
+    async def on_request(self, context: MiddlewareContext, call_next):
+        ctx = context.fastmcp_context
+
+        if ctx.request_context:
+            # MCP session available - can access session-specific attributes
+            session_id = ctx.session_id
+            request_id = ctx.request_id
+        else:
+            # MCP session not available yet - use HTTP helpers for request data (if using HTTP transport)
+            from fastmcp.server.dependencies import get_http_headers
+            headers = get_http_headers()
+            # Access HTTP data for auth, logging, etc.
+
+        return await call_next(context)
+```
+
+For HTTP request data (headers, client IP, etc.) when using HTTP transports, use `get_http_request()` or `get_http_headers()` from `fastmcp.server.dependencies`, which work regardless of MCP session availability. See [HTTP Requests](/v2/servers/context#http-requests) for details.
+
+## Component Access in Middleware
+
+Understanding how to access component information (tools, resources, prompts) in middleware is crucial for building powerful middleware functionality. The access patterns differ significantly between listing operations and execution operations.
+
+### Listing Operations vs Execution Operations
+
+FastMCP middleware handles two types of operations differently:
+
+**Listing Operations** (`on_list_tools`, `on_list_resources`, `on_list_prompts`, etc.):
+- Middleware receives **FastMCP component objects** with full metadata
+- These objects include FastMCP-specific properties like `tags` that can be accessed directly from the component
+- The result contains complete component information before it's converted to MCP format  
+- Tags are included in the component's `meta` field in the listing response returned to MCP clients
+
+**Execution Operations** (`on_call_tool`, `on_read_resource`, `on_get_prompt`):
+- Middleware runs **before** the component is executed
+- The middleware result is either the execution result or an error if the component wasn't found
+- Component metadata isn't directly available in the hook parameters
+
+### Accessing Component Metadata During Execution
+
+If you need to check component properties (like tags) during execution operations, use the FastMCP server instance available through the context:
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+from fastmcp.exceptions import ToolError
+
+class TagBasedMiddleware(Middleware):
+    async def on_call_tool(self, context: MiddlewareContext, call_next):
+        # Access the tool object to check its metadata
+        if context.fastmcp_context:
+            try:
+                tool = await context.fastmcp_context.fastmcp.get_tool(context.message.name)
+                
+                # Check if this tool has a "private" tag
+                if "private" in tool.tags:
+                    raise ToolError("Access denied: private tool")
+                    
+                # Check if tool is enabled
+                if not tool.enabled:
+                    raise ToolError("Tool is currently disabled")
+                    
+            except Exception:
+                # Tool not found or other error - let execution continue
+                # and handle the error naturally
+                pass
+        
+        return await call_next(context)
+```
+
+The same pattern works for resources and prompts:
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+from fastmcp.exceptions import ResourceError, PromptError
+
+class ComponentAccessMiddleware(Middleware):
+    async def on_read_resource(self, context: MiddlewareContext, call_next):
+        if context.fastmcp_context:
+            try:
+                resource = await context.fastmcp_context.fastmcp.get_resource(context.message.uri)
+                if "restricted" in resource.tags:
+                    raise ResourceError("Access denied: restricted resource")
+            except Exception:
+                pass
+        return await call_next(context)
+    
+    async def on_get_prompt(self, context: MiddlewareContext, call_next):
+        if context.fastmcp_context:
+            try:
+                prompt = await context.fastmcp_context.fastmcp.get_prompt(context.message.name)
+                if not prompt.enabled:
+                    raise PromptError("Prompt is currently disabled")
+            except Exception:
+                pass
+        return await call_next(context)
+```
+
+### Working with Listing Results
+
+For listing operations, the middleware `call_next` function returns a list of FastMCP components prior to being converted to MCP format. You can filter or modify this list and return it to the client. For example:
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+class ListingFilterMiddleware(Middleware):
+    async def on_list_tools(self, context: MiddlewareContext, call_next):
+        result = await call_next(context)
+        
+        # Filter out tools with "private" tag
+        filtered_tools = [
+            tool for tool in result 
+            if "private" not in tool.tags
+        ]
+        
+        # Return modified list
+        return filtered_tools
+```
+
+This filtering happens before the components are converted to MCP format and returned to the client. Tags are accessible both during filtering and are included in the component's `meta` field in the final listing response.
+
+<Tip>
+When filtering components in listing operations, ensure you also prevent execution of filtered components in the corresponding execution hooks (`on_call_tool`, `on_read_resource`, `on_get_prompt`) to maintain consistency.
+</Tip>
+
+### Tool Call Denial
+
+You can deny access to specific tools by raising a `ToolError` in your middleware. This is the correct way to block tool execution, as it integrates properly with the FastMCP error handling system.
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+from fastmcp.exceptions import ToolError
+
+class AuthMiddleware(Middleware):
+    async def on_call_tool(self, context: MiddlewareContext, call_next):
+        tool_name = context.message.name
+        
+        # Deny access to restricted tools
+        if tool_name.lower() in ["delete", "admin_config"]:
+            raise ToolError("Access denied: tool requires admin privileges")
+        
+        # Allow other tools to proceed
+        return await call_next(context)
+```
+
+<Warning>
+When denying tool calls, always raise `ToolError` rather than returning `ToolResult` objects or other values. `ToolError` ensures proper error propagation through the middleware chain and converts to the correct MCP error response format.
+</Warning>
+
+### Tool Call Modification
+
+For execution operations like tool calls, you can modify arguments before execution or transform results afterward:
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+class ToolCallMiddleware(Middleware):
+    async def on_call_tool(self, context: MiddlewareContext, call_next):
+        # Modify arguments before execution
+        if context.message.name == "calculate":
+            # Ensure positive inputs
+            if context.message.arguments.get("value", 0) < 0:
+                context.message.arguments["value"] = abs(context.message.arguments["value"])
+        
+        result = await call_next(context)
+        
+        # Transform result after execution
+        if context.message.name == "get_data":
+            # Add metadata to result
+            if result.structured_content:
+                result.structured_content["processed_at"] = "2024-01-01T00:00:00Z"
+        
+        return result
+```
+
+<Tip>
+For more complex tool rewriting scenarios, consider using [Tool Transformation](/v2/patterns/tool-transformation) patterns which provide a more structured approach to creating modified tool variants.
+</Tip>
+
+### Anatomy of a Hook
+
+Every middleware hook follows the same pattern. Let's examine the `on_message` hook to understand the structure:
+
+```python
+async def on_message(self, context: MiddlewareContext, call_next):
+    # 1. Pre-processing: Inspect and optionally modify the request
+    print(f"Processing {context.method}")
+    
+    # 2. Chain continuation: Call the next middleware/handler
+    result = await call_next(context)
+    
+    # 3. Post-processing: Inspect and optionally modify the response
+    print(f"Completed {context.method}")
+    
+    # 4. Return the result (potentially modified)
+    return result
+```
+
+### Hook Parameters
+
+Every hook receives two parameters:
+
+1. **`context: MiddlewareContext`** - Contains information about the current request:
+   - `context.method` - The MCP method name (e.g., "tools/call")
+   - `context.source` - Where the request came from ("client" or "server")
+   - `context.type` - Message type ("request" or "notification")
+   - `context.message` - The MCP message data
+   - `context.timestamp` - When the request was received
+   - `context.fastmcp_context` - FastMCP Context object (if available)
+
+2. **`call_next`** - A function that continues the middleware chain. You **must** call this to proceed, unless you want to stop processing entirely.
+
+### Control Flow
+
+You have complete control over the request flow:
+- **Continue processing**: Call `await call_next(context)` to proceed
+- **Modify the request**: Change the context before calling `call_next`
+- **Modify the response**: Change the result after calling `call_next`
+- **Stop the chain**: Don't call `call_next` (rarely needed)
+- **Handle errors**: Wrap `call_next` in try/catch blocks
+
+#### State Management
+
+<VersionBadge version="2.11.0" />
+
+In addition to modifying the request and response, you can also store state data that your tools can (optionally) access later. To do so, use the FastMCP Context to either `set_state` or `get_state` as appropriate. For more information, see the [Context State Management](/v2/servers/context#state-management) docs.
+
+## Creating Middleware
+
+FastMCP middleware is implemented by subclassing the `Middleware` base class and overriding the hooks you need. You only need to implement the hooks that are relevant to your use case.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+class LoggingMiddleware(Middleware):
+    """Middleware that logs all MCP operations."""
+    
+    async def on_message(self, context: MiddlewareContext, call_next):
+        """Called for all MCP messages."""
+        print(f"Processing {context.method} from {context.source}")
+        
+        result = await call_next(context)
+        
+        print(f"Completed {context.method}")
+        return result
+
+# Add middleware to your server
+mcp = FastMCP("MyServer")
+mcp.add_middleware(LoggingMiddleware())
+```
+
+This creates a basic logging middleware that will print information about every request that flows through your server.
+
+## Adding Middleware to Your Server
+
+### Single Middleware
+
+Adding middleware to your server is straightforward:
+
+```python
+mcp = FastMCP("MyServer")
+mcp.add_middleware(LoggingMiddleware())
+```
+
+### Multiple Middleware
+
+Middleware executes in the order it's added to the server. The first middleware added runs first on the way in, and last on the way out:
+
+```python
+mcp = FastMCP("MyServer")
+
+mcp.add_middleware(AuthenticationMiddleware("secret-token"))
+mcp.add_middleware(PerformanceMiddleware())
+mcp.add_middleware(LoggingMiddleware())
+```
+
+This creates the following execution flow:
+1. AuthenticationMiddleware (pre-processing)
+2. PerformanceMiddleware (pre-processing)  
+3. LoggingMiddleware (pre-processing)
+4. Actual tool/resource handler
+5. LoggingMiddleware (post-processing)
+6. PerformanceMiddleware (post-processing)
+7. AuthenticationMiddleware (post-processing)
+
+## Server Composition and Middleware
+
+When using [Server Composition](/v2/servers/composition) with `mount` or `import_server`, middleware behavior follows these rules:
+
+1. **Parent server middleware** runs for all requests, including those routed to mounted servers
+2. **Mounted server middleware** only runs for requests handled by that specific server
+3. **Middleware order** is preserved within each server
+
+This allows you to create layered middleware architectures where parent servers handle cross-cutting concerns like authentication, while child servers focus on domain-specific middleware.
+
+```python
+# Parent server with middleware
+parent = FastMCP("Parent")
+parent.add_middleware(AuthenticationMiddleware("token"))
+
+# Child server with its own middleware  
+child = FastMCP("Child")
+child.add_middleware(LoggingMiddleware())
+
+@child.tool
+def child_tool() -> str:
+    return "from child"
+
+# Mount the child server
+parent.mount(child, prefix="child")
+```
+
+When a client calls "child_tool", the request will flow through the parent's authentication middleware first, then route to the child server where it will go through the child's logging middleware.
+
+## Built-in Middleware Examples
+
+FastMCP includes several middleware implementations that demonstrate best practices and provide immediately useful functionality. Let's explore how each type works by building simplified versions, then see how to use the full implementations.
+
+### Timing Middleware
+
+Performance monitoring is essential for understanding your server's behavior and identifying bottlenecks. FastMCP includes timing middleware at `fastmcp.server.middleware.timing`. 
+
+Here's an example of how it works:
+
+```python
+import time
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+class SimpleTimingMiddleware(Middleware):
+    async def on_request(self, context: MiddlewareContext, call_next):
+        start_time = time.perf_counter()
+        
+        try:
+            result = await call_next(context)
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            print(f"Request {context.method} completed in {duration_ms:.2f}ms")
+            return result
+        except Exception as e:
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            print(f"Request {context.method} failed after {duration_ms:.2f}ms: {e}")
+            raise
+```
+
+To use the full version with proper logging and configuration:
+
+```python
+from fastmcp.server.middleware.timing import (
+    TimingMiddleware, 
+    DetailedTimingMiddleware
+)
+
+# Basic timing for all requests
+mcp.add_middleware(TimingMiddleware())
+
+# Detailed per-operation timing (tools, resources, prompts)
+mcp.add_middleware(DetailedTimingMiddleware())
+```
+
+The built-in versions include custom logger support, proper formatting, and **DetailedTimingMiddleware** provides operation-specific hooks like `on_call_tool` and `on_read_resource` for granular timing.
+
+### Tool Injection Middleware
+
+Tool injection middleware is a middleware that injects tools into the server during the request lifecycle:
+
+```python
+from fastmcp.server.middleware.tool_injection import ToolInjectionMiddleware
+
+def my_tool_fn(a: int, b: int) -> int:
+    return a + b
+
+my_tool = Tool.from_function(fn=my_tool_fn, name="my_tool")
+
+mcp.add_middleware(ToolInjectionMiddleware(tools=[my_tool]))
+```
+
+### Prompt Tool Middleware
+
+Prompt tool middleware is a compatibility middleware for clients that are unable to list or get prompts. It provides two tools: `list_prompts` and `get_prompt` which allow clients to list and get prompts respectively using only tool calls.
+
+```python
+from fastmcp.server.middleware.tool_injection import PromptToolMiddleware
+
+mcp.add_middleware(PromptToolMiddleware())
+```
+
+### Resource Tool Middleware
+
+Resource tool middleware is a compatibility middleware for clients that are unable to list or read resources. It provides two tools: `list_resources` and `read_resource` which allow clients to list and read resources respectively using only tool calls.
+
+```python
+from fastmcp.server.middleware.tool_injection import ResourceToolMiddleware
+
+mcp.add_middleware(ResourceToolMiddleware())
+```
+
+### Caching Middleware
+
+Caching middleware is essential for improving performance and reducing server load. FastMCP provides caching middleware at `fastmcp.server.middleware.caching`.
+
+Here's how to use the full version:
+
+```python
+from fastmcp.server.middleware.caching import ResponseCachingMiddleware
+
+mcp.add_middleware(ResponseCachingMiddleware())
+```
+
+Out of the box, it caches call/list tool, resources, and prompts to an in-memory cache with TTL-based expiration. Cache entries expire based on their TTL; there is no event-based cache invalidation. List calls are stored under global keys—when sharing a storage backend across multiple servers, consider namespacing collections to prevent conflicts. See [Storage Backends](/v2/servers/storage-backends) for advanced configuration options.
+
+Each method can be configured individually, for example, caching list tools for 30 seconds, limiting caching to specific tools, and disabling caching for resource reads:
+
+```python
+from fastmcp.server.middleware.caching import ResponseCachingMiddleware, CallToolSettings, ListToolsSettings, ReadResourceSettings
+
+mcp.add_middleware(ResponseCachingMiddleware(
+    list_tools_settings=ListToolsSettings(
+        ttl=30,
+    ),
+    call_tool_settings=CallToolSettings(
+        included_tools=["tool1"],
+    ),
+    read_resource_settings=ReadResourceSettings(
+        enabled=False
+    )
+))
+```
+
+#### Storage Backends
+
+By default, caching uses in-memory storage, which is fast but doesn't persist across restarts. For production or persistent caching across server restarts, configure a different storage backend. See [Storage Backends](/v2/servers/storage-backends) for complete options including disk, Redis, DynamoDB, and custom implementations.
+
+Disk-based caching example:
+
+```python
+from fastmcp.server.middleware.caching import ResponseCachingMiddleware
+from key_value.aio.stores.disk import DiskStore
+
+mcp.add_middleware(ResponseCachingMiddleware(
+    cache_storage=DiskStore(directory="cache"),
+))
+```
+
+Redis for distributed deployments:
+
+```python
+from fastmcp.server.middleware.caching import ResponseCachingMiddleware
+from key_value.aio.stores.redis import RedisStore
+
+mcp.add_middleware(ResponseCachingMiddleware(
+    cache_storage=RedisStore(host="redis.example.com", port=6379),
+))
+```
+
+#### Cache Statistics
+
+The caching middleware collects operation statistics (hits, misses, etc.) through the underlying storage layer. Access statistics from the middleware instance:
+
+```python
+from fastmcp.server.middleware.caching import ResponseCachingMiddleware
+
+middleware = ResponseCachingMiddleware()
+mcp.add_middleware(middleware)
+
+# Later, retrieve statistics
+stats = middleware.statistics()
+print(f"Total cache operations: {stats}")
+```
+
+### Logging Middleware
+
+Request and response logging is crucial for debugging, monitoring, and understanding usage patterns in your MCP server. FastMCP provides comprehensive logging middleware at `fastmcp.server.middleware.logging`. 
+
+Here's an example of how it works:
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+class SimpleLoggingMiddleware(Middleware):
+    async def on_message(self, context: MiddlewareContext, call_next):
+        print(f"Processing {context.method} from {context.source}")
+        
+        try:
+            result = await call_next(context)
+            print(f"Completed {context.method}")
+            return result
+        except Exception as e:
+            print(f"Failed {context.method}: {e}")
+            raise
+```
+
+To use the full versions with advanced features:
+
+```python
+from fastmcp.server.middleware.logging import (
+    LoggingMiddleware, 
+    StructuredLoggingMiddleware
+)
+
+# Human-readable logging with payload support
+mcp.add_middleware(LoggingMiddleware(
+    include_payloads=True,
+    max_payload_length=1000
+))
+
+# JSON-structured logging for log aggregation tools
+mcp.add_middleware(StructuredLoggingMiddleware(include_payloads=True))
+```
+
+The built-in versions include payload logging, structured JSON output, custom logger support, payload size limits, and operation-specific hooks for granular control.
+
+### Rate Limiting Middleware
+
+Rate limiting is essential for protecting your server from abuse, ensuring fair resource usage, and maintaining performance under load. FastMCP includes sophisticated rate limiting middleware at `fastmcp.server.middleware.rate_limiting`. 
+
+Here's an example of how it works:
+
+```python
+import time
+from collections import defaultdict
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+from mcp import McpError
+from mcp.types import ErrorData
+
+class SimpleRateLimitMiddleware(Middleware):
+    def __init__(self, requests_per_minute: int = 60):
+        self.requests_per_minute = requests_per_minute
+        self.client_requests = defaultdict(list)
+    
+    async def on_request(self, context: MiddlewareContext, call_next):
+        current_time = time.time()
+        client_id = "default"  # In practice, extract from headers or context
+        
+        # Clean old requests and check limit
+        cutoff_time = current_time - 60
+        self.client_requests[client_id] = [
+            req_time for req_time in self.client_requests[client_id]
+            if req_time > cutoff_time
+        ]
+        
+        if len(self.client_requests[client_id]) >= self.requests_per_minute:
+            raise McpError(ErrorData(code=-32000, message="Rate limit exceeded"))
+        
+        self.client_requests[client_id].append(current_time)
+        return await call_next(context)
+```
+
+To use the full versions with advanced algorithms:
+
+```python
+from fastmcp.server.middleware.rate_limiting import (
+    RateLimitingMiddleware, 
+    SlidingWindowRateLimitingMiddleware
+)
+
+# Token bucket rate limiting (allows controlled bursts)
+mcp.add_middleware(RateLimitingMiddleware(
+    max_requests_per_second=10.0,
+    burst_capacity=20
+))
+
+# Sliding window rate limiting (precise time-based control)
+mcp.add_middleware(SlidingWindowRateLimitingMiddleware(
+    max_requests=100,
+    window_minutes=1
+))
+```
+
+The built-in versions include token bucket algorithms, per-client identification, global rate limiting, and async-safe implementations with configurable client identification functions.
+
+### Error Handling Middleware
+
+Consistent error handling and recovery is critical for robust MCP servers. FastMCP provides comprehensive error handling middleware at `fastmcp.server.middleware.error_handling`.
+
+Here's an example of how it works:
+
+```python
+import logging
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+class SimpleErrorHandlingMiddleware(Middleware):
+    def __init__(self):
+        self.logger = logging.getLogger("errors")
+        self.error_counts = {}
+    
+    async def on_message(self, context: MiddlewareContext, call_next):
+        try:
+            return await call_next(context)
+        except Exception as error:
+            # Log the error and track statistics
+            error_key = f"{type(error).__name__}:{context.method}"
+            self.error_counts[error_key] = self.error_counts.get(error_key, 0) + 1
+            
+            self.logger.error(f"Error in {context.method}: {type(error).__name__}: {error}")
+            raise
+```
+
+To use the full versions with advanced features:
+
+```python
+from fastmcp.server.middleware.error_handling import (
+    ErrorHandlingMiddleware, 
+    RetryMiddleware
+)
+
+# Comprehensive error logging and transformation
+mcp.add_middleware(ErrorHandlingMiddleware(
+    include_traceback=True,
+    transform_errors=True,
+    error_callback=my_error_callback
+))
+
+# Automatic retry with exponential backoff
+mcp.add_middleware(RetryMiddleware(
+    max_retries=3,
+    retry_exceptions=(ConnectionError, TimeoutError)
+))
+```
+
+The built-in versions include error transformation, custom callbacks, configurable retry logic, and proper MCP error formatting.
+
+### Combining Middleware
+
+These middleware work together seamlessly:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.middleware.timing import TimingMiddleware
+from fastmcp.server.middleware.logging import LoggingMiddleware
+from fastmcp.server.middleware.rate_limiting import RateLimitingMiddleware
+from fastmcp.server.middleware.error_handling import ErrorHandlingMiddleware
+
+mcp = FastMCP("Production Server")
+
+# Add middleware in logical order
+mcp.add_middleware(ErrorHandlingMiddleware())  # Handle errors first
+mcp.add_middleware(RateLimitingMiddleware(max_requests_per_second=50))
+mcp.add_middleware(TimingMiddleware())  # Time actual execution
+mcp.add_middleware(LoggingMiddleware())  # Log everything
+
+@mcp.tool
+def my_tool(data: str) -> str:
+    return f"Processed: {data}"
+```
+
+This configuration provides comprehensive monitoring, protection, and observability for your MCP server.
+
+### Custom Middleware Example
+
+You can also create custom middleware by extending the base class:
+
+```python
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+class CustomHeaderMiddleware(Middleware):
+    async def on_request(self, context: MiddlewareContext, call_next):
+        # Add custom logic here
+        print(f"Processing {context.method}")
+        
+        result = await call_next(context)
+        
+        print(f"Completed {context.method}")
+        return result
+
+mcp.add_middleware(CustomHeaderMiddleware())
+```
diff --git a/docs/v2/servers/progress.mdx b/docs/v2/servers/progress.mdx
new file mode 100644
index 0000000..c5bbad3
--- /dev/null
+++ b/docs/v2/servers/progress.mdx
@@ -0,0 +1,189 @@
+---
+title: Progress Reporting
+sidebarTitle: Progress
+description: Update clients on the progress of long-running operations through the MCP context.
+icon: chart-line
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+Progress reporting allows MCP tools to notify clients about the progress of long-running operations. This enables clients to display progress indicators and provide better user experience during time-consuming tasks.
+
+## Why Use Progress Reporting?
+
+Progress reporting is valuable for:
+
+- **User experience**: Keep users informed about long-running operations
+- **Progress indicators**: Enable clients to show progress bars or percentages
+- **Timeout prevention**: Demonstrate that operations are actively progressing
+- **Debugging**: Track execution progress for performance analysis
+
+### Basic Usage
+
+Use `ctx.report_progress()` to send progress updates to the client:
+
+```python {14, 21}
+from fastmcp import FastMCP, Context
+import asyncio
+
+mcp = FastMCP("ProgressDemo")
+
+@mcp.tool
+async def process_items(items: list[str], ctx: Context) -> dict:
+    """Process a list of items with progress updates."""
+    total = len(items)
+    results = []
+    
+    for i, item in enumerate(items):
+        # Report progress as we process each item
+        await ctx.report_progress(progress=i, total=total)
+        
+        # Simulate processing time
+        await asyncio.sleep(0.1)
+        results.append(item.upper())
+    
+    # Report 100% completion
+    await ctx.report_progress(progress=total, total=total)
+    
+    return {"processed": len(results), "results": results}
+```
+
+## Method Signature
+
+<Card icon="code" title="Context Progress Method">
+<ResponseField name="ctx.report_progress" type="async method">
+  Report progress to the client for long-running operations
+  
+  <Expandable title="Parameters">
+    <ResponseField name="progress" type="float">
+      Current progress value (e.g., 24, 0.75, 1500)
+    </ResponseField>
+    
+    <ResponseField name="total" type="float | None" default="None">
+      Optional total value (e.g., 100, 1.0, 2000). When provided, clients may interpret this as enabling percentage calculation.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+</Card>
+
+## Progress Patterns
+
+### Percentage-Based Progress
+
+Report progress as a percentage (0-100):
+
+```python {13-14}
+@mcp.tool
+async def download_file(url: str, ctx: Context) -> str:
+    """Download a file with percentage progress."""
+    total_size = 1000  # KB
+    downloaded = 0
+    
+    while downloaded < total_size:
+        # Download chunk
+        chunk_size = min(50, total_size - downloaded)
+        downloaded += chunk_size
+        
+        # Report percentage progress
+        percentage = (downloaded / total_size) * 100
+        await ctx.report_progress(progress=percentage, total=100)
+        
+        await asyncio.sleep(0.1)  # Simulate download time
+    
+    return f"Downloaded file from {url}"
+```
+
+### Absolute Progress
+
+Report progress with absolute values:
+
+```python {10}
+@mcp.tool
+async def backup_database(ctx: Context) -> str:
+    """Backup database tables with absolute progress."""
+    tables = ["users", "orders", "products", "inventory", "logs"]
+    
+    for i, table in enumerate(tables):
+        await ctx.info(f"Backing up table: {table}")
+        
+        # Report absolute progress
+        await ctx.report_progress(progress=i + 1, total=len(tables))
+        
+        # Simulate backup time
+        await asyncio.sleep(0.5)
+    
+    return "Database backup completed"
+```
+
+### Indeterminate Progress
+
+Report progress without a known total for operations where the endpoint is unknown:
+
+```python {11}
+@mcp.tool
+async def scan_directory(directory: str, ctx: Context) -> dict:
+    """Scan directory with indeterminate progress."""
+    files_found = 0
+    
+    # Simulate directory scanning
+    for i in range(10):  # Unknown number of files
+        files_found += 1
+        
+        # Report progress without total for indeterminate operations
+        await ctx.report_progress(progress=files_found)
+        
+        await asyncio.sleep(0.2)
+    
+    return {"files_found": files_found, "directory": directory}
+```
+
+### Multi-Stage Operations
+
+Break complex operations into stages with progress for each:
+
+```python
+@mcp.tool
+async def data_migration(source: str, destination: str, ctx: Context) -> str:
+    """Migrate data with multi-stage progress reporting."""
+    
+    # Stage 1: Validation (0-25%)
+    await ctx.info("Validating source data")
+    for i in range(5):
+        await ctx.report_progress(progress=i * 5, total=100)
+        await asyncio.sleep(0.1)
+    
+    # Stage 2: Export (25-60%)
+    await ctx.info("Exporting data from source")
+    for i in range(7):
+        progress = 25 + (i * 5)
+        await ctx.report_progress(progress=progress, total=100)
+        await asyncio.sleep(0.1)
+    
+    # Stage 3: Transform (60-80%)
+    await ctx.info("Transforming data format")
+    for i in range(4):
+        progress = 60 + (i * 5)
+        await ctx.report_progress(progress=progress, total=100)
+        await asyncio.sleep(0.1)
+    
+    # Stage 4: Import (80-100%)
+    await ctx.info("Importing to destination")
+    for i in range(4):
+        progress = 80 + (i * 5)
+        await ctx.report_progress(progress=progress, total=100)
+        await asyncio.sleep(0.1)
+    
+    # Final completion
+    await ctx.report_progress(progress=100, total=100)
+    
+    return f"Migration from {source} to {destination} completed"
+```
+
+
+## Client Requirements
+
+Progress reporting requires clients to support progress handling:
+
+- Clients must send a `progressToken` in the initial request to receive progress updates
+- If no progress token is provided, progress calls will have no effect (they won't error)
+- See [Client Progress](/v2/clients/progress) for details on implementing client-side progress handling
diff --git a/docs/v2/servers/prompts.mdx b/docs/v2/servers/prompts.mdx
new file mode 100644
index 0000000..bccba2b
--- /dev/null
+++ b/docs/v2/servers/prompts.mdx
@@ -0,0 +1,353 @@
+---
+title: Prompts
+sidebarTitle: Prompts
+description: Create reusable, parameterized prompt templates for MCP clients.
+icon: message-lines
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+Prompts are reusable message templates that help LLMs generate structured, purposeful responses. FastMCP simplifies defining these templates, primarily using the `@mcp.prompt` decorator.
+
+## What Are Prompts?
+
+Prompts provide parameterized message templates for LLMs. When a client requests a prompt:
+
+1.  FastMCP finds the corresponding prompt definition.
+2.  If it has parameters, they are validated against your function signature.
+3.  Your function executes with the validated inputs.
+4.  The generated message(s) are returned to the LLM to guide its response.
+
+This allows you to define consistent, reusable templates that LLMs can use across different clients and contexts.
+
+## Prompts
+
+### The `@prompt` Decorator
+
+The most common way to define a prompt is by decorating a Python function. The decorator uses the function name as the prompt's identifier.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.prompts.prompt import Message, PromptMessage, TextContent
+
+mcp = FastMCP(name="PromptServer")
+
+# Basic prompt returning a string (converted to user message automatically)
+@mcp.prompt
+def ask_about_topic(topic: str) -> str:
+    """Generates a user message asking for an explanation of a topic."""
+    return f"Can you please explain the concept of '{topic}'?"
+
+# Prompt returning a specific message type
+@mcp.prompt
+def generate_code_request(language: str, task_description: str) -> PromptMessage:
+    """Generates a user message requesting code generation."""
+    content = f"Write a {language} function that performs the following task: {task_description}"
+    return PromptMessage(role="user", content=TextContent(type="text", text=content))
+```
+
+**Key Concepts:**
+
+*   **Name:** By default, the prompt name is taken from the function name.
+*   **Parameters:** The function parameters define the inputs needed to generate the prompt.
+*   **Inferred Metadata:** By default:
+    *   Prompt Name: Taken from the function name (`ask_about_topic`).
+    *   Prompt Description: Taken from the function's docstring.
+<Tip>
+Functions with `*args` or `**kwargs` are not supported as prompts. This restriction exists because FastMCP needs to generate a complete parameter schema for the MCP protocol, which isn't possible with variable argument lists.
+</Tip>
+
+#### Decorator Arguments
+
+While FastMCP infers the name and description from your function, you can override these and add additional metadata using arguments to the `@mcp.prompt` decorator:
+
+```python
+@mcp.prompt(
+    name="analyze_data_request",          # Custom prompt name
+    description="Creates a request to analyze data with specific parameters",  # Custom description
+    tags={"analysis", "data"},            # Optional categorization tags
+    meta={"version": "1.1", "author": "data-team"}  # Custom metadata
+)
+def data_analysis_prompt(
+    data_uri: str = Field(description="The URI of the resource containing the data."),
+    analysis_type: str = Field(default="summary", description="Type of analysis.")
+) -> str:
+    """This docstring is ignored when description is provided."""
+    return f"Please perform a '{analysis_type}' analysis on the data found at {data_uri}."
+```
+
+<Card icon="code" title="@prompt Decorator Arguments">
+<ParamField body="name" type="str | None">
+  Sets the explicit prompt name exposed via MCP. If not provided, uses the function name
+</ParamField>
+
+<ParamField body="title" type="str | None">
+  A human-readable title for the prompt
+</ParamField>
+
+<ParamField body="description" type="str | None">
+  Provides the description exposed via MCP. If set, the function's docstring is ignored for this purpose
+</ParamField>
+
+<ParamField body="tags" type="set[str] | None">
+  A set of strings used to categorize the prompt. These can be used by the server and, in some cases, by clients to filter or group available prompts.
+</ParamField>
+
+<ParamField body="enabled" type="bool" default="True">
+  A boolean to enable or disable the prompt. See [Disabling Prompts](#disabling-prompts) for more information
+</ParamField>
+
+<ParamField body="icons" type="list[Icon] | None">
+  <VersionBadge version="2.13.0" />
+
+  Optional list of icon representations for this prompt. See [Icons](/v2/servers/icons) for detailed examples
+</ParamField>
+
+<ParamField body="meta" type="dict[str, Any] | None">
+  <VersionBadge version="2.11.0" />
+
+  Optional meta information about the prompt. This data is passed through to the MCP client as the `_meta` field of the client-side prompt object and can be used for custom metadata, versioning, or other application-specific purposes.
+</ParamField>
+</Card>
+
+### Argument Types
+
+<VersionBadge version="2.9.0" />
+
+The MCP specification requires that all prompt arguments be passed as strings, but FastMCP allows you to use typed annotations for better developer experience. When you use complex types like `list[int]` or `dict[str, str]`, FastMCP:
+
+1. **Automatically converts** string arguments from MCP clients to the expected types
+2. **Generates helpful descriptions** showing the exact JSON string format needed
+3. **Preserves direct usage** - you can still call prompts with properly typed arguments
+
+Since the MCP specification only allows string arguments, clients need to know what string format to use for complex types. FastMCP solves this by automatically enhancing the argument descriptions with JSON schema information, making it clear to both humans and LLMs how to format their arguments.
+
+<CodeGroup>
+
+```python Python Code
+@mcp.prompt
+def analyze_data(
+    numbers: list[int],
+    metadata: dict[str, str], 
+    threshold: float
+) -> str:
+    """Analyze numerical data."""
+    avg = sum(numbers) / len(numbers)
+    return f"Average: {avg}, above threshold: {avg > threshold}"
+```
+
+```json Resulting MCP Prompt
+{
+  "name": "analyze_data",
+  "description": "Analyze numerical data.",
+  "arguments": [
+    {
+      "name": "numbers",
+      "description": "Provide as a JSON string matching the following schema: {\"items\":{\"type\":\"integer\"},\"type\":\"array\"}",
+      "required": true
+    },
+    {
+      "name": "metadata", 
+      "description": "Provide as a JSON string matching the following schema: {\"additionalProperties\":{\"type\":\"string\"},\"type\":\"object\"}",
+      "required": true
+    },
+    {
+      "name": "threshold",
+      "description": "Provide as a JSON string matching the following schema: {\"type\":\"number\"}",
+      "required": true
+    }
+  ]
+}
+```
+
+</CodeGroup>
+
+**MCP clients will call this prompt with string arguments:**
+```json
+{
+  "numbers": "[1, 2, 3, 4, 5]",
+  "metadata": "{\"source\": \"api\", \"version\": \"1.0\"}",
+  "threshold": "2.5"
+}
+```
+
+**But you can still call it directly with proper types:**
+```python
+# This also works for direct calls
+result = await prompt.render({
+    "numbers": [1, 2, 3, 4, 5],
+    "metadata": {"source": "api", "version": "1.0"}, 
+    "threshold": 2.5
+})
+```
+
+<Warning>
+Keep your type annotations simple when using this feature. Complex nested types or custom classes may not convert reliably from JSON strings. The automatically generated schema descriptions are the only guidance users receive about the expected format.
+
+Good choices: `list[int]`, `dict[str, str]`, `float`, `bool`
+Avoid: Complex Pydantic models, deeply nested structures, custom classes
+</Warning>
+
+### Return Values
+
+FastMCP intelligently handles different return types from your prompt function:
+
+-   **`str`**: Automatically converted to a single `PromptMessage`.
+-   **`PromptMessage`**: Used directly as provided. (Note a more user-friendly `Message` constructor is available that can accept raw strings instead of `TextContent` objects.)
+-   **`list[PromptMessage | str]`**: Used as a sequence of messages (a conversation).
+-   **`Any`**: If the return type is not one of the above, the return value is attempted to be converted to a string and used as a `PromptMessage`.
+
+```python
+from fastmcp.prompts.prompt import Message, PromptResult
+
+@mcp.prompt
+def roleplay_scenario(character: str, situation: str) -> PromptResult:
+    """Sets up a roleplaying scenario with initial messages."""
+    return [
+        Message(f"Let's roleplay. You are {character}. The situation is: {situation}"),
+        Message("Okay, I understand. I am ready. What happens next?", role="assistant")
+    ]
+```
+
+
+### Required vs. Optional Parameters
+
+Parameters in your function signature are considered **required** unless they have a default value.
+
+```python
+@mcp.prompt
+def data_analysis_prompt(
+    data_uri: str,                        # Required - no default value
+    analysis_type: str = "summary",       # Optional - has default value
+    include_charts: bool = False          # Optional - has default value
+) -> str:
+    """Creates a request to analyze data with specific parameters."""
+    prompt = f"Please perform a '{analysis_type}' analysis on the data found at {data_uri}."
+    if include_charts:
+        prompt += " Include relevant charts and visualizations."
+    return prompt
+```
+
+In this example, the client *must* provide `data_uri`. If `analysis_type` or `include_charts` are omitted, their default values will be used.
+
+### Disabling Prompts
+
+<VersionBadge version="2.8.0" />
+
+You can control the visibility and availability of prompts by enabling or disabling them. Disabled prompts will not appear in the list of available prompts, and attempting to call a disabled prompt will result in an "Unknown prompt" error.
+
+By default, all prompts are enabled. You can disable a prompt upon creation using the `enabled` parameter in the decorator:
+
+```python
+@mcp.prompt(enabled=False)
+def experimental_prompt():
+    """This prompt is not ready for use."""
+    return "This is an experimental prompt."
+```
+
+You can also toggle a prompt's state programmatically after it has been created:
+
+```python
+@mcp.prompt
+def seasonal_prompt(): return "Happy Holidays!"
+
+# Disable and re-enable the prompt
+seasonal_prompt.disable()
+seasonal_prompt.enable()
+```
+
+### Async Prompts
+
+FastMCP seamlessly supports both standard (`def`) and asynchronous (`async def`) functions as prompts.
+
+```python
+# Synchronous prompt
+@mcp.prompt
+def simple_question(question: str) -> str:
+    """Generates a simple question to ask the LLM."""
+    return f"Question: {question}"
+
+# Asynchronous prompt
+@mcp.prompt
+async def data_based_prompt(data_id: str) -> str:
+    """Generates a prompt based on data that needs to be fetched."""
+    # In a real scenario, you might fetch data from a database or API
+    async with aiohttp.ClientSession() as session:
+        async with session.get(f"https://api.example.com/data/{data_id}") as response:
+            data = await response.json()
+            return f"Analyze this data: {data['content']}"
+```
+
+Use `async def` when your prompt function performs I/O operations like network requests, database queries, file I/O, or external service calls.
+
+### Accessing MCP Context
+
+<VersionBadge version="2.2.5" />
+
+Prompts can access additional MCP information and features through the `Context` object. To access it, add a parameter to your prompt function with a type annotation of `Context`:
+
+```python {6}
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP(name="PromptServer")
+
+@mcp.prompt
+async def generate_report_request(report_type: str, ctx: Context) -> str:
+    """Generates a request for a report."""
+    return f"Please create a {report_type} report. Request ID: {ctx.request_id}"
+```
+
+For full documentation on the Context object and all its capabilities, see the [Context documentation](/v2/servers/context).
+
+### Notifications
+
+<VersionBadge version="2.9.1" />
+
+FastMCP automatically sends `notifications/prompts/list_changed` notifications to connected clients when prompts are added, enabled, or disabled. This allows clients to stay up-to-date with the current prompt set without manually polling for changes.
+
+```python
+@mcp.prompt
+def example_prompt() -> str:
+    return "Hello!"
+
+# These operations trigger notifications:
+mcp.add_prompt(example_prompt)  # Sends prompts/list_changed notification
+example_prompt.disable()        # Sends prompts/list_changed notification  
+example_prompt.enable()         # Sends prompts/list_changed notification
+```
+
+Notifications are only sent when these operations occur within an active MCP request context (e.g., when called from within a tool or other MCP operation). Operations performed during server initialization do not trigger notifications.
+
+Clients can handle these notifications using a [message handler](/v2/clients/messages) to automatically refresh their prompt lists or update their interfaces.
+
+## Server Behavior
+
+### Duplicate Prompts
+
+<VersionBadge version="2.1.0" />
+
+You can configure how the FastMCP server handles attempts to register multiple prompts with the same name. Use the `on_duplicate_prompts` setting during `FastMCP` initialization.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(
+    name="PromptServer",
+    on_duplicate_prompts="error"  # Raise an error if a prompt name is duplicated
+)
+
+@mcp.prompt
+def greeting(): return "Hello, how can I help you today?"
+
+# This registration attempt will raise a ValueError because
+# "greeting" is already registered and the behavior is "error".
+# @mcp.prompt
+# def greeting(): return "Hi there! What can I do for you?"
+```
+
+The duplicate behavior options are:
+
+-   `"warn"` (default): Logs a warning, and the new prompt replaces the old one.
+-   `"error"`: Raises a `ValueError`, preventing the duplicate registration.
+-   `"replace"`: Silently replaces the existing prompt with the new one.
+-   `"ignore"`: Keeps the original prompt and ignores the new registration attempt. 
diff --git a/docs/v2/servers/proxy.mdx b/docs/v2/servers/proxy.mdx
new file mode 100644
index 0000000..b5ceb4b
--- /dev/null
+++ b/docs/v2/servers/proxy.mdx
@@ -0,0 +1,349 @@
+---
+title: Proxy Servers
+sidebarTitle: Proxy Servers
+description: Use FastMCP to act as an intermediary or change transport for other MCP servers.
+icon: arrows-retweet
+---
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.0.0" />
+
+FastMCP provides a powerful proxying capability that allows one FastMCP server instance to act as a frontend for another MCP server (which could be remote, running on a different transport, or even another FastMCP instance). This is achieved using the `FastMCP.as_proxy()` class method.
+
+## What is Proxying?
+
+Proxying means setting up a FastMCP server that doesn't implement its own tools or resources directly. Instead, when it receives a request (like `tools/call` or `resources/read`), it forwards that request to a *backend* MCP server, receives the response, and then relays that response back to the original client.
+
+```mermaid
+sequenceDiagram
+    participant ClientApp as Your Client (e.g., Claude Desktop)
+    participant FastMCPProxy as FastMCP Proxy Server
+    participant BackendServer as Backend MCP Server (e.g., remote SSE)
+
+    ClientApp->>FastMCPProxy: MCP Request (e.g. stdio)
+    Note over FastMCPProxy, BackendServer: Proxy forwards the request
+    FastMCPProxy->>BackendServer: MCP Request (e.g. sse)
+    BackendServer-->>FastMCPProxy: MCP Response (e.g. sse)
+    Note over ClientApp, FastMCPProxy: Proxy relays the response
+    FastMCPProxy-->>ClientApp: MCP Response (e.g. stdio)
+```
+
+### Key Benefits
+
+<VersionBadge version="2.10.3" />
+
+- **Session Isolation**: Each request gets its own isolated session, ensuring safe concurrent operations
+- **Transport Bridging**: Expose servers running on one transport via a different transport
+- **Advanced MCP Features**: Automatic forwarding of sampling, elicitation, logging, and progress
+- **Security**: Acts as a controlled gateway to backend servers
+- **Simplicity**: Single endpoint even if backend location or transport changes
+
+### Performance Considerations
+
+When using proxy servers, especially those connecting to HTTP-based backend servers, be aware that latency can be significant. Operations like `list_tools()` may take hundreds of milliseconds compared to 1-2ms for local tools. When mounting proxy servers, this latency affects all operations on the parent server, not just interactions with the proxied tools.
+
+If low latency is a requirement for your use-case, consider using [`import_server()`](/v2/servers/composition#importing-static-composition) to copy tools at startup rather than proxying them at runtime.
+
+## Quick Start
+
+<VersionBadge version="2.10.3" />
+
+The recommended way to create a proxy is using `ProxyClient`, which provides full MCP feature support with automatic session isolation:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers.proxy import ProxyClient
+
+# Create a proxy with full MCP feature support
+proxy = FastMCP.as_proxy(
+    ProxyClient("backend_server.py"),
+    name="MyProxy"
+)
+
+# Run the proxy (e.g., via stdio for Claude Desktop)
+if __name__ == "__main__":
+    proxy.run()
+```
+
+This single setup gives you:
+- Safe concurrent request handling
+- Automatic forwarding of advanced MCP features (sampling, elicitation, etc.)
+- Session isolation to prevent context mixing
+- Full compatibility with all MCP clients
+
+You can also pass a FastMCP [client transport](/v2/clients/transports) (or parameter that can be inferred to a transport) to `as_proxy()`. This will automatically create a `ProxyClient` instance for you.
+
+Finally, you can pass a regular FastMCP `Client` instance to `as_proxy()`. This will work for many use cases, but may break if advanced MCP features like sampling or elicitation are invoked by the server. 
+
+## Session Isolation & Concurrency
+
+<VersionBadge version="2.10.3" />
+
+FastMCP proxies provide session isolation to ensure safe concurrent operations. The session strategy depends on how the proxy is configured:
+
+### Fresh Sessions
+
+When you pass a disconnected client (which is the normal case), each request gets its own isolated backend session:
+
+```python
+from fastmcp.server.providers.proxy import ProxyClient
+
+# Each request creates a fresh backend session (recommended)
+proxy = FastMCP.as_proxy(ProxyClient("backend_server.py"))
+
+# Multiple clients can use this proxy simultaneously without interference:
+# - Client A calls a tool -> gets isolated backend session
+# - Client B calls a tool -> gets different isolated backend session  
+# - No context mixing between requests
+```
+
+### Session Reuse with Connected Clients
+
+When you pass an already-connected client, the proxy will reuse that session for all requests:
+
+```python
+from fastmcp import Client
+
+# Create and connect a client
+async with Client("backend_server.py") as connected_client:
+    # This proxy will reuse the connected session for all requests
+    proxy = FastMCP.as_proxy(connected_client)
+    
+    # ⚠️ Warning: All requests share the same backend session
+    # This may cause context mixing in concurrent scenarios
+```
+
+**Important**: Using shared sessions with concurrent requests from multiple clients may lead to context mixing and race conditions. This approach should only be used in single-threaded scenarios or when you have explicit synchronization.
+
+## Transport Bridging
+
+A common use case is bridging transports - exposing a server running on one transport via a different transport. For example, making a remote SSE server available locally via stdio:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers.proxy import ProxyClient
+
+# Bridge remote SSE server to local stdio
+remote_proxy = FastMCP.as_proxy(
+    ProxyClient("http://example.com/mcp/sse"),
+    name="Remote-to-Local Bridge"
+)
+
+# Run locally via stdio for Claude Desktop
+if __name__ == "__main__":
+    remote_proxy.run()  # Defaults to stdio transport
+```
+
+Or expose a local server via HTTP for remote access:
+
+```python
+# Bridge local server to HTTP
+local_proxy = FastMCP.as_proxy(
+    ProxyClient("local_server.py"),
+    name="Local-to-HTTP Bridge"
+)
+
+# Run via HTTP for remote clients
+if __name__ == "__main__":
+    local_proxy.run(transport="http", host="0.0.0.0", port=8080)
+```
+
+
+## Advanced MCP Features
+
+<VersionBadge version="2.10.3" />
+
+`ProxyClient` automatically forwards advanced MCP protocol features between the backend server and clients connected to the proxy, ensuring full MCP compatibility.
+
+### Supported Features
+
+- **Roots**: Forwards filesystem root access requests to the client
+- **Sampling**: Forwards LLM completion requests from backend to client  
+- **Elicitation**: Forwards user input requests to the client
+- **Logging**: Forwards log messages from backend through to client
+- **Progress**: Forwards progress notifications during long operations
+
+```python
+from fastmcp.server.providers.proxy import ProxyClient
+
+# ProxyClient automatically handles all these features
+backend = ProxyClient("advanced_backend.py")
+proxy = FastMCP.as_proxy(backend)
+
+# When the backend server:
+# - Requests LLM sampling -> forwarded to your client
+# - Logs messages -> appear in your client
+# - Reports progress -> shown in your client
+# - Needs user input -> prompts your client
+```
+
+### Customizing Feature Support
+
+You can selectively disable forwarding by passing `None` for specific handlers:
+
+```python
+# Disable sampling but keep other features
+backend = ProxyClient(
+    "backend_server.py",
+    sampling_handler=None,  # Disable LLM sampling forwarding
+    log_handler=None        # Disable log forwarding
+)
+```
+
+When you use a transport string directly with `FastMCP.as_proxy()`, it automatically creates a `ProxyClient` internally to ensure full feature support.
+
+## Configuration-Based Proxies
+
+<VersionBadge version="2.4.0" />
+
+You can create a proxy directly from a configuration dictionary that follows the MCPConfig schema. This is useful for quickly setting up proxies to remote servers without manually configuring each connection detail.
+
+```python
+from fastmcp import FastMCP
+
+# Create a proxy directly from a config dictionary
+config = {
+    "mcpServers": {
+        "default": {  # For single server configs, 'default' is commonly used
+            "url": "https://example.com/mcp",
+            "transport": "http"
+        }
+    }
+}
+
+# Create a proxy to the configured server (auto-creates ProxyClient)
+proxy = FastMCP.as_proxy(config, name="Config-Based Proxy")
+
+# Run the proxy with stdio transport for local access
+if __name__ == "__main__":
+    proxy.run()
+```
+
+<Note>
+The MCPConfig format follows an emerging standard for MCP server configuration and may evolve as the specification matures. While FastMCP aims to maintain compatibility with future versions, be aware that field names or structure might change.
+</Note>
+
+### Multi-Server Configurations
+
+You can create a proxy to multiple servers by specifying multiple entries in the config. They are automatically mounted with their config names as prefixes:
+
+```python
+# Multi-server configuration
+config = {
+    "mcpServers": {
+        "weather": {
+            "url": "https://weather-api.example.com/mcp",
+            "transport": "http"
+        },
+        "calendar": {
+            "url": "https://calendar-api.example.com/mcp",
+            "transport": "http"
+        }
+    }
+}
+
+# Create a unified proxy to multiple servers
+composite_proxy = FastMCP.as_proxy(config, name="Composite Proxy")
+
+# Tools, resources, prompts, and templates are accessible with prefixes:
+# - Tools: weather_get_forecast, calendar_add_event
+# - Prompts: weather_daily_summary, calendar_quick_add
+# - Resources: weather://weather/icons/sunny, calendar://calendar/events/today
+# - Templates: weather://weather/locations/{id}, calendar://calendar/events/{date}
+```
+
+## Component Prefixing
+
+When proxying one or more servers, component names are prefixed the same way as with mounting and importing:
+
+- Tools: `{prefix}_{tool_name}`
+- Prompts: `{prefix}_{prompt_name}`
+- Resources: `protocol://{prefix}/path/to/resource` (default path format)
+- Resource templates: `protocol://{prefix}/...` and template names are also prefixed
+
+These rules apply uniformly whether you:
+- Mount a proxy on another server
+- Create a multi-server proxy from an `MCPConfig`
+- Use `FastMCP.as_proxy()` directly
+
+## Mirrored Components
+
+<VersionBadge version="2.10.5" />
+
+When you access tools, resources, or prompts from a proxy server, they are "mirrored" from the remote server. Mirrored components cannot be modified directly since they reflect the state of the remote server. For example, you can not simply "disable" a mirrored component.
+
+However, you can create a copy of a mirrored component and store it as a new locally-defined component. Local components always take precedence over mirrored ones because the proxy server will check its own registry before it attempts to engage the remote server.
+
+Therefore, to enable or disable a proxy tool, resource, or prompt, you should first create a local copy and add it to your own server. Here's an example of how to do that for a tool:
+
+```python
+# Create your own server
+my_server = FastMCP("MyServer")
+
+# Get a proxy server
+proxy = FastMCP.as_proxy("backend_server.py")
+
+# Get mirrored components from proxy
+mirrored_tool = await proxy.get_tool("useful_tool")
+
+# Create a local copy that you can modify
+local_tool = mirrored_tool.copy()
+
+# Add the local copy to your server
+my_server.add_tool(local_tool)
+
+# Now you can disable YOUR copy
+local_tool.disable()
+```
+
+
+## `FastMCPProxy` Class
+
+Internally, `FastMCP.as_proxy()` uses the `FastMCPProxy` class. You generally don't need to interact with this class directly, but it's available if needed for advanced scenarios.
+
+### Direct Usage
+
+```python
+from fastmcp.server.providers.proxy import FastMCPProxy, ProxyClient
+
+# Provide a client factory for explicit session control
+def create_client():
+    return ProxyClient("backend_server.py")
+
+proxy = FastMCPProxy(client_factory=create_client)
+```
+
+### Parameters
+
+- **`client_factory`**: A callable that returns a `Client` instance when called. This gives you full control over session creation and reuse strategies.
+
+### Explicit Session Management
+
+`FastMCPProxy` requires explicit session management - no automatic detection is performed. You must choose your session strategy:
+
+```python
+# Share session across all requests (be careful with concurrency)
+shared_client = ProxyClient("backend_server.py")
+def shared_session_factory():
+    return shared_client
+
+proxy = FastMCPProxy(client_factory=shared_session_factory)
+
+# Create fresh sessions per request (recommended)
+def fresh_session_factory():
+    return ProxyClient("backend_server.py")
+
+proxy = FastMCPProxy(client_factory=fresh_session_factory)
+```
+
+For automatic session strategy selection, use the convenience method `FastMCP.as_proxy()` instead.
+
+```python
+# Custom factory with specific configuration
+def custom_client_factory():
+    client = ProxyClient("backend_server.py")
+    # Add any custom configuration here
+    return client
+
+proxy = FastMCPProxy(client_factory=custom_client_factory)
+```
diff --git a/docs/v2/servers/resources.mdx b/docs/v2/servers/resources.mdx
new file mode 100644
index 0000000..f472df5
--- /dev/null
+++ b/docs/v2/servers/resources.mdx
@@ -0,0 +1,665 @@
+---
+title: Resources & Templates
+sidebarTitle: Resources
+description: Expose data sources and dynamic content generators to your MCP client.
+icon: folder-open
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+Resources represent data or files that an MCP client can read, and resource templates extend this concept by allowing clients to request dynamically generated resources based on parameters passed in the URI.
+
+FastMCP simplifies defining both static and dynamic resources, primarily using the `@mcp.resource` decorator.
+
+## What Are Resources?
+
+Resources provide read-only access to data for the LLM or client application. When a client requests a resource URI:
+
+1.  FastMCP finds the corresponding resource definition.
+2.  If it's dynamic (defined by a function), the function is executed.
+3.  The content (text, JSON, binary data) is returned to the client.
+
+This allows LLMs to access files, database content, configuration, or dynamically generated information relevant to the conversation.
+
+## Resources
+
+### The `@resource` Decorator
+
+The most common way to define a resource is by decorating a Python function. The decorator requires the resource's unique URI.
+
+```python
+import json
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="DataServer")
+
+# Basic dynamic resource returning a string
+@mcp.resource("resource://greeting")
+def get_greeting() -> str:
+    """Provides a simple greeting message."""
+    return "Hello from FastMCP Resources!"
+
+# Resource returning JSON data (dict is auto-serialized)
+@mcp.resource("data://config")
+def get_config() -> dict:
+    """Provides application configuration as JSON."""
+    return {
+        "theme": "dark",
+        "version": "1.2.0",
+        "features": ["tools", "resources"],
+    }
+```
+
+**Key Concepts:**
+
+*   **URI:** The first argument to `@resource` is the unique URI (e.g., `"resource://greeting"`) clients use to request this data.
+*   **Lazy Loading:** The decorated function (`get_greeting`, `get_config`) is only executed when a client specifically requests that resource URI via `resources/read`.
+*   **Inferred Metadata:** By default:
+    *   Resource Name: Taken from the function name (`get_greeting`).
+    *   Resource Description: Taken from the function's docstring.
+
+#### Decorator Arguments
+
+You can customize the resource's properties using arguments in the `@mcp.resource` decorator:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="DataServer")
+
+# Example specifying metadata
+@mcp.resource(
+    uri="data://app-status",      # Explicit URI (required)
+    name="ApplicationStatus",     # Custom name
+    description="Provides the current status of the application.", # Custom description
+    mime_type="application/json", # Explicit MIME type
+    tags={"monitoring", "status"}, # Categorization tags
+    meta={"version": "2.1", "team": "infrastructure"}  # Custom metadata
+)
+def get_application_status() -> dict:
+    """Internal function description (ignored if description is provided above)."""
+    return {"status": "ok", "uptime": 12345, "version": mcp.settings.version} # Example usage
+```
+
+<Card icon="code" title="@resource Decorator Arguments">
+<ParamField body="uri" type="str" required>
+  The unique identifier for the resource
+</ParamField>
+
+<ParamField body="name" type="str | None">
+  A human-readable name. If not provided, defaults to function name
+</ParamField>
+
+<ParamField body="description" type="str | None">
+  Explanation of the resource. If not provided, defaults to docstring
+</ParamField>
+
+<ParamField body="mime_type" type="str | None">
+  Specifies the content type. FastMCP often infers a default like `text/plain` or `application/json`, but explicit is better for non-text types
+</ParamField>
+
+<ParamField body="tags" type="set[str] | None">
+  A set of strings used to categorize the resource. These can be used by the server and, in some cases, by clients to filter or group available resources.
+</ParamField>
+
+<ParamField body="enabled" type="bool" default="True">
+  A boolean to enable or disable the resource. See [Disabling Resources](#disabling-resources) for more information
+</ParamField>
+
+<ParamField body="icons" type="list[Icon] | None">
+  <VersionBadge version="2.13.0" />
+
+  Optional list of icon representations for this resource or template. See [Icons](/v2/servers/icons) for detailed examples
+</ParamField>
+
+<ParamField body="annotations" type="Annotations | dict | None">
+    An optional `Annotations` object or dictionary to add additional metadata about the resource.
+  <Expandable title="Annotations attributes">
+    <ParamField body="readOnlyHint" type="bool | None">
+      If true, the resource is read-only and does not modify its environment.
+    </ParamField>
+    <ParamField body="idempotentHint" type="bool | None">
+      If true, reading the resource repeatedly will have no additional effect on its environment.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="meta" type="dict[str, Any] | None">
+  <VersionBadge version="2.11.0" />
+  
+  Optional meta information about the resource. This data is passed through to the MCP client as the `_meta` field of the client-side resource object and can be used for custom metadata, versioning, or other application-specific purposes.
+</ParamField>
+</Card>
+
+### Return Values
+
+FastMCP automatically converts your function's return value into the appropriate MCP resource content:
+
+-   **`str`**: Sent as `TextResourceContents` (with `mime_type="text/plain"` by default).
+-   **`dict`, `list`, `pydantic.BaseModel`**: Automatically serialized to a JSON string and sent as `TextResourceContents` (with `mime_type="application/json"` by default).
+-   **`bytes`**: Base64 encoded and sent as `BlobResourceContents`. You should specify an appropriate `mime_type` (e.g., `"image/png"`, `"application/octet-stream"`).
+-   **`None`**: Results in an empty resource content list being returned.
+
+### Disabling Resources
+
+<VersionBadge version="2.8.0" />
+
+You can control the visibility and availability of resources and templates by enabling or disabling them. Disabled resources will not appear in the list of available resources or templates, and attempting to read a disabled resource will result in an "Unknown resource" error.
+
+By default, all resources are enabled. You can disable a resource upon creation using the `enabled` parameter in the decorator:
+
+```python
+@mcp.resource("data://secret", enabled=False)
+def get_secret_data():
+    """This resource is currently disabled."""
+    return "Secret data"
+```
+
+You can also toggle a resource's state programmatically after it has been created:
+
+```python
+@mcp.resource("data://config")
+def get_config(): return {"version": 1}
+
+# Disable and re-enable the resource
+get_config.disable()
+get_config.enable()
+```
+
+
+### Accessing MCP Context
+
+<VersionBadge version="2.2.5" />
+
+Resources and resource templates can access additional MCP information and features through the `Context` object. To access it, add a parameter to your resource function with a type annotation of `Context`:
+
+```python {6, 14}
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP(name="DataServer")
+
+@mcp.resource("resource://system-status")
+async def get_system_status(ctx: Context) -> dict:
+    """Provides system status information."""
+    return {
+        "status": "operational",
+        "request_id": ctx.request_id
+    }
+
+@mcp.resource("resource://{name}/details")
+async def get_details(name: str, ctx: Context) -> dict:
+    """Get details for a specific name."""
+    return {
+        "name": name,
+        "accessed_at": ctx.request_id
+    }
+```
+
+For full documentation on the Context object and all its capabilities, see the [Context documentation](/v2/servers/context).
+
+
+### Async Resources
+
+Use `async def` for resource functions that perform I/O operations (e.g., reading from a database or network) to avoid blocking the server.
+
+```python
+import aiofiles
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="DataServer")
+
+@mcp.resource("file:///app/data/important_log.txt", mime_type="text/plain")
+async def read_important_log() -> str:
+    """Reads content from a specific log file asynchronously."""
+    try:
+        async with aiofiles.open("/app/data/important_log.txt", mode="r") as f:
+            content = await f.read()
+        return content
+    except FileNotFoundError:
+        return "Log file not found."
+```
+
+
+### Resource Classes
+
+While `@mcp.resource` is ideal for dynamic content, you can directly register pre-defined resources (like static files or simple text) using `mcp.add_resource()` and concrete `Resource` subclasses.
+
+```python
+from pathlib import Path
+from fastmcp import FastMCP
+from fastmcp.resources import FileResource, TextResource, DirectoryResource
+
+mcp = FastMCP(name="DataServer")
+
+# 1. Exposing a static file directly
+readme_path = Path("./README.md").resolve()
+if readme_path.exists():
+    # Use a file:// URI scheme
+    readme_resource = FileResource(
+        uri=f"file://{readme_path.as_posix()}",
+        path=readme_path, # Path to the actual file
+        name="README File",
+        description="The project's README.",
+        mime_type="text/markdown",
+        tags={"documentation"}
+    )
+    mcp.add_resource(readme_resource)
+
+# 2. Exposing simple, predefined text
+notice_resource = TextResource(
+    uri="resource://notice",
+    name="Important Notice",
+    text="System maintenance scheduled for Sunday.",
+    tags={"notification"}
+)
+mcp.add_resource(notice_resource)
+
+# 3. Exposing a directory listing
+data_dir_path = Path("./app_data").resolve()
+if data_dir_path.is_dir():
+    data_listing_resource = DirectoryResource(
+        uri="resource://data-files",
+        path=data_dir_path, # Path to the directory
+        name="Data Directory Listing",
+        description="Lists files available in the data directory.",
+        recursive=False # Set to True to list subdirectories
+    )
+    mcp.add_resource(data_listing_resource) # Returns JSON list of files
+```
+
+**Common Resource Classes:**
+
+-   `TextResource`: For simple string content.
+-   `BinaryResource`: For raw `bytes` content.
+-   `FileResource`: Reads content from a local file path. Handles text/binary modes and lazy reading.
+-   `HttpResource`: Fetches content from an HTTP(S) URL (requires `httpx`).
+-   `DirectoryResource`: Lists files in a local directory (returns JSON).
+-   (`FunctionResource`: Internal class used by `@mcp.resource`).
+
+Use these when the content is static or sourced directly from a file/URL, bypassing the need for a dedicated Python function.
+
+### Notifications
+
+<VersionBadge version="2.9.1" />
+
+FastMCP automatically sends `notifications/resources/list_changed` notifications to connected clients when resources or templates are added, enabled, or disabled. This allows clients to stay up-to-date with the current resource set without manually polling for changes.
+
+```python
+@mcp.resource("data://example")
+def example_resource() -> str:
+    return "Hello!"
+
+# These operations trigger notifications:
+mcp.add_resource(example_resource)  # Sends resources/list_changed notification
+example_resource.disable()          # Sends resources/list_changed notification  
+example_resource.enable()           # Sends resources/list_changed notification
+```
+
+Notifications are only sent when these operations occur within an active MCP request context (e.g., when called from within a tool or other MCP operation). Operations performed during server initialization do not trigger notifications.
+
+Clients can handle these notifications using a [message handler](/v2/clients/messages) to automatically refresh their resource lists or update their interfaces.
+
+### Annotations
+
+<VersionBadge version="2.11.0" />
+
+FastMCP allows you to add specialized metadata to your resources through annotations. These annotations communicate how resources behave to client applications without consuming token context in LLM prompts.
+
+Annotations serve several purposes in client applications:
+- Indicating whether resources are read-only or may have side effects
+- Describing the safety profile of resources (idempotent vs. non-idempotent)
+- Helping clients optimize caching and access patterns
+
+You can add annotations to a resource using the `annotations` parameter in the `@mcp.resource` decorator:
+
+```python
+@mcp.resource(
+    "data://config",
+    annotations={
+        "readOnlyHint": True,
+        "idempotentHint": True
+    }
+)
+def get_config() -> dict:
+    """Get application configuration."""
+    return {"version": "1.0", "debug": False}
+```
+
+FastMCP supports these standard annotations:
+
+| Annotation | Type | Default | Purpose |
+| :--------- | :--- | :------ | :------ |
+| `readOnlyHint` | boolean | true | Indicates if the resource only provides data without side effects |
+| `idempotentHint` | boolean | true | Indicates if repeated reads have the same effect as a single read |
+
+Remember that annotations help make better user experiences but should be treated as advisory hints. They help client applications present appropriate UI elements and optimize access patterns, but won't enforce behavior on their own. Always focus on making your annotations accurately represent what your resource actually does.
+
+## Resource Templates
+
+Resource Templates allow clients to request resources whose content depends on parameters embedded in the URI. Define a template using the **same `@mcp.resource` decorator**, but include `{parameter_name}` placeholders in the URI string and add corresponding arguments to your function signature.
+
+Resource templates share most configuration options with regular resources (name, description, mime_type, tags, annotations), but add the ability to define URI parameters that map to function parameters.
+
+Resource templates generate a new resource for each unique set of parameters, which means that resources can be dynamically created on-demand. For example, if the resource template `"user://profile/{name}"` is registered, MCP clients could request `"user://profile/ford"` or `"user://profile/marvin"` to retrieve either of those two user profiles as resources, without having to register each resource individually.
+
+<Tip>
+Functions with `*args` are not supported as resource templates. However, unlike tools and prompts, resource templates do support `**kwargs` because the URI template defines specific parameter names that will be collected and passed as keyword arguments.
+</Tip>
+
+Here is a complete example that shows how to define two resource templates:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="DataServer")
+
+# Template URI includes {city} placeholder
+@mcp.resource("weather://{city}/current")
+def get_weather(city: str) -> dict:
+    """Provides weather information for a specific city."""
+    # In a real implementation, this would call a weather API
+    # Here we're using simplified logic for example purposes
+    return {
+        "city": city.capitalize(),
+        "temperature": 22,
+        "condition": "Sunny",
+        "unit": "celsius"
+    }
+
+# Template with multiple parameters and annotations
+@mcp.resource(
+    "repos://{owner}/{repo}/info",
+    annotations={
+        "readOnlyHint": True,
+        "idempotentHint": True
+    }
+)
+def get_repo_info(owner: str, repo: str) -> dict:
+    """Retrieves information about a GitHub repository."""
+    # In a real implementation, this would call the GitHub API
+    return {
+        "owner": owner,
+        "name": repo,
+        "full_name": f"{owner}/{repo}",
+        "stars": 120,
+        "forks": 48
+    }
+```
+
+With these two templates defined, clients can request a variety of resources:
+- `weather://london/current` → Returns weather for London
+- `weather://paris/current` → Returns weather for Paris
+- `repos://PrefectHQ/fastmcp/info` → Returns info about the PrefectHQ/fastmcp repository
+- `repos://prefecthq/prefect/info` → Returns info about the prefecthq/prefect repository
+
+### RFC 6570 URI Templates
+
+
+FastMCP implements [RFC 6570 URI Templates](https://datatracker.ietf.org/doc/html/rfc6570) for resource templates, providing a standardized way to define parameterized URIs. This includes support for simple expansion, wildcard path parameters, and form-style query parameters.
+
+#### Wildcard Parameters
+
+<VersionBadge version="2.2.4" />
+
+Resource templates support wildcard parameters that can match multiple path segments. Standard parameters (`{param}`) match a single URI segment before decoding and do not cross literal "/" boundaries in the request URI. Wildcard parameters (`{param*}`) can capture multiple segments including slashes. Wildcards capture all subsequent path segments *up until* the defined part of the URI template (whether literal or another parameter). This allows you to have multiple wildcard parameters in a single URI template.
+
+```python {15, 23}
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="DataServer")
+
+
+# Standard parameter only matches one segment
+@mcp.resource("files://{filename}")
+def get_file(filename: str) -> str:
+    """Retrieves a file by name."""
+    # Will only match files://<single-segment>
+    return f"File content for: {filename}"
+
+
+# Wildcard parameter can match multiple segments
+@mcp.resource("path://{filepath*}")
+def get_path_content(filepath: str) -> str:
+    """Retrieves content at a specific path."""
+    # Can match path://docs/server/resources.mdx
+    return f"Content at path: {filepath}"
+
+
+# Mixing standard and wildcard parameters
+@mcp.resource("repo://{owner}/{path*}/template.py")
+def get_template_file(owner: str, path: str) -> dict:
+    """Retrieves a file from a specific repository and path, but
+    only if the resource ends with `template.py`"""
+    # Can match repo://PrefectHQ/fastmcp/src/resources/template.py
+    return {
+        "owner": owner,
+        "path": path + "/template.py",
+        "content": f"File at {path}/template.py in {owner}'s repository"
+    }
+```
+
+Wildcard parameters are useful when:
+
+- Working with file paths or hierarchical data
+- Creating APIs that need to capture variable-length path segments
+- Building URL-like patterns similar to REST APIs
+
+Note that like regular parameters, each wildcard parameter must still be a named parameter in your function signature, and all required function parameters must appear in the URI template.
+
+#### Filesystem Path Safety
+
+Template parameters are decoded before your function receives them. A standard `{filename}` parameter matches one URI segment before decoding, so a request like `files://a%2Fb` passes `filename="a/b"` to the handler. Treat template values as untrusted decoded URI data whenever they determine filesystem paths.
+
+Validate the final resolved path against an allowed root before reading:
+
+```python
+from pathlib import Path
+
+from fastmcp import FastMCP
+from fastmcp.exceptions import ResourceError
+
+mcp = FastMCP(name="DocsServer")
+DOCS_ROOT = Path("docs").resolve()
+
+
+@mcp.resource("docs://{filename}")
+def read_doc(filename: str) -> str:
+    requested_path = (DOCS_ROOT / filename).resolve()
+
+    if not requested_path.is_relative_to(DOCS_ROOT) or not requested_path.is_file():
+        raise ResourceError("Document not found")
+
+    return requested_path.read_text(encoding="utf-8")
+```
+
+Use wildcard parameters (`{path*}`) for resources whose URI shape intentionally includes slashes, and apply the same containment check before accessing the filesystem.
+
+#### Query Parameters
+
+<VersionBadge version="2.13.0" />
+
+FastMCP supports RFC 6570 form-style query parameters using the `{?param1,param2}` syntax. Query parameters provide a clean way to pass optional configuration to resources without cluttering the path.
+
+Query parameters must be optional function parameters (have default values), while path parameters map to required function parameters. This enforces a clear separation: required data goes in the path, optional configuration in query params.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="DataServer")
+
+# Basic query parameters
+@mcp.resource("data://{id}{?format}")
+def get_data(id: str, format: str = "json") -> str:
+    """Retrieve data in specified format."""
+    if format == "xml":
+        return f"<data id='{id}' />"
+    return f'{{"id": "{id}"}}'
+
+# Multiple query parameters with type coercion
+@mcp.resource("api://{endpoint}{?version,limit,offset}")
+def call_api(endpoint: str, version: int = 1, limit: int = 10, offset: int = 0) -> dict:
+    """Call API endpoint with pagination."""
+    return {
+        "endpoint": endpoint,
+        "version": version,
+        "limit": limit,
+        "offset": offset,
+        "results": fetch_results(endpoint, version, limit, offset)
+    }
+
+# Query parameters with wildcards
+@mcp.resource("files://{path*}{?encoding,lines}")
+def read_file(path: str, encoding: str = "utf-8", lines: int = 100) -> str:
+    """Read file with optional encoding and line limit."""
+    return read_file_content(path, encoding, lines)
+```
+
+**Example requests:**
+- `data://123` → Uses default format `"json"`
+- `data://123?format=xml` → Uses format `"xml"`
+- `api://users?version=2&limit=50` → `version=2, limit=50, offset=0`
+- `files://src/main.py?encoding=ascii&lines=50` → Custom encoding and line limit
+
+FastMCP automatically coerces query parameter string values to the correct types based on your function's type hints (`int`, `float`, `bool`, `str`).
+
+**Query parameters vs. hidden defaults:**
+
+Query parameters expose optional configuration to clients. To hide optional parameters from clients entirely (always use defaults), simply omit them from the URI template:
+
+```python
+# Clients CAN override max_results via query string
+@mcp.resource("search://{query}{?max_results}")
+def search_configurable(query: str, max_results: int = 10) -> dict:
+    return {"query": query, "limit": max_results}
+
+# Clients CANNOT override max_results (not in URI template)
+@mcp.resource("search://{query}")
+def search_fixed(query: str, max_results: int = 10) -> dict:
+    return {"query": query, "limit": max_results}
+```
+
+### Template Parameter Rules
+
+<VersionBadge version="2.2.0" />
+
+FastMCP enforces these validation rules when creating resource templates:
+
+1. **Required function parameters** (no default values) must appear in the URI path template
+2. **Query parameters** (specified with `{?param}` syntax) must be optional function parameters with default values
+3. **All URI template parameters** (path and query) must exist as function parameters
+
+Optional function parameters (those with default values) can be:
+- Included as query parameters (`{?param}`) - clients can override via query string
+- Omitted from URI template - always uses default value, not exposed to clients
+- Used in alternative path templates - enables multiple ways to access the same resource
+
+**Multiple templates for one function:**
+
+Create multiple resource templates that expose the same function through different URI patterns by manually applying decorators:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="DataServer")
+
+# Define a user lookup function that can be accessed by different identifiers
+def lookup_user(name: str | None = None, email: str | None = None) -> dict:
+    """Look up a user by either name or email."""
+    if email:
+        return find_user_by_email(email)  # pseudocode
+    elif name:
+        return find_user_by_name(name)  # pseudocode
+    else:
+        return {"error": "No lookup parameters provided"}
+
+# Manually apply multiple decorators to the same function
+mcp.resource("users://email/{email}")(lookup_user)
+mcp.resource("users://name/{name}")(lookup_user)
+```
+
+Now an LLM or client can retrieve user information in two different ways:
+- `users://email/alice@example.com` → Looks up user by email (with name=None)
+- `users://name/Bob` → Looks up user by name (with email=None)
+
+This approach allows a single function to be registered with multiple URI patterns while keeping the implementation clean and straightforward.
+
+Templates provide a powerful way to expose parameterized data access points following REST-like principles.
+
+## Error Handling
+
+<VersionBadge version="2.4.1" />
+
+If your resource function encounters an error, you can raise a standard Python exception (`ValueError`, `TypeError`, `FileNotFoundError`, custom exceptions, etc.) or a FastMCP `ResourceError`.
+
+By default, all exceptions (including their details) are logged and converted into an MCP error response to be sent back to the client LLM. This helps the LLM understand failures and react appropriately.
+
+If you want to mask internal error details for security reasons, you can:
+
+1. Use the `mask_error_details=True` parameter when creating your `FastMCP` instance:
+```python
+mcp = FastMCP(name="SecureServer", mask_error_details=True)
+```
+
+2. Or use `ResourceError` to explicitly control what error information is sent to clients:
+```python
+from fastmcp import FastMCP
+from fastmcp.exceptions import ResourceError
+
+mcp = FastMCP(name="DataServer")
+
+@mcp.resource("resource://safe-error")
+def fail_with_details() -> str:
+    """This resource provides detailed error information."""
+    # ResourceError contents are always sent back to clients,
+    # regardless of mask_error_details setting
+    raise ResourceError("Unable to retrieve data: file not found")
+
+@mcp.resource("resource://masked-error")
+def fail_with_masked_details() -> str:
+    """This resource masks internal error details when mask_error_details=True."""
+    # This message would be masked if mask_error_details=True
+    raise ValueError("Sensitive internal file path: /etc/secrets.conf")
+
+@mcp.resource("data://{id}")
+def get_data_by_id(id: str) -> dict:
+    """Template resources also support the same error handling pattern."""
+    if id == "secure":
+        raise ValueError("Cannot access secure data")
+    elif id == "missing":
+        raise ResourceError("Data ID 'missing' not found in database")
+    return {"id": id, "value": "data"}
+```
+
+When `mask_error_details=True`, only error messages from `ResourceError` will include details, other exceptions will be converted to a generic message.
+
+## Server Behavior
+
+### Duplicate Resources
+
+<VersionBadge version="2.1.0" />
+
+You can configure how the FastMCP server handles attempts to register multiple resources or templates with the same URI. Use the `on_duplicate_resources` setting during `FastMCP` initialization.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(
+    name="ResourceServer",
+    on_duplicate_resources="error" # Raise error on duplicates
+)
+
+@mcp.resource("data://config")
+def get_config_v1(): return {"version": 1}
+
+# This registration attempt will raise a ValueError because
+# "data://config" is already registered and the behavior is "error".
+# @mcp.resource("data://config")
+# def get_config_v2(): return {"version": 2}
+```
+
+The duplicate behavior options are:
+
+-   `"warn"` (default): Logs a warning, and the new resource/template replaces the old one.
+-   `"error"`: Raises a `ValueError`, preventing the duplicate registration.
+-   `"replace"`: Silently replaces the existing resource/template with the new one.
+-   `"ignore"`: Keeps the original resource/template and ignores the new registration attempt.
diff --git a/docs/v2/servers/sampling.mdx b/docs/v2/servers/sampling.mdx
new file mode 100644
index 0000000..5c21a0b
--- /dev/null
+++ b/docs/v2/servers/sampling.mdx
@@ -0,0 +1,488 @@
+---
+title: LLM Sampling
+sidebarTitle: Sampling
+description: Request LLM text generation from the client or a configured provider through the MCP context.
+icon: robot
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+<VersionBadge version="2.0.0" />
+
+LLM sampling allows your MCP tools to request text generation from an LLM during execution. This enables tools to leverage AI capabilities for analysis, generation, reasoning, and more—without the client needing to orchestrate multiple calls.
+
+By default, sampling requests are routed to the client's LLM. You can also configure a fallback handler to use a specific provider (like OpenAI) when the client doesn't support sampling, or to always use your own LLM regardless of client capabilities.
+
+## Method Reference
+
+<Card icon="code" title="ctx.sample()">
+<ResponseField name="ctx.sample" type="async method">
+  Request text generation from the LLM, running to completion automatically.
+
+  <Expandable title="Parameters">
+    <ResponseField name="messages" type="str | list[str | SamplingMessage]">
+      The prompt to send. Can be a simple string or a list of messages for multi-turn conversations.
+    </ResponseField>
+
+    <ResponseField name="system_prompt" type="str | None" default="None">
+      Instructions that establish the LLM's role and behavior.
+    </ResponseField>
+
+    <ResponseField name="temperature" type="float | None" default="None">
+      Controls randomness (0.0 = deterministic, 1.0 = creative).
+    </ResponseField>
+
+    <ResponseField name="max_tokens" type="int | None" default="512">
+      Maximum tokens to generate.
+    </ResponseField>
+
+    <ResponseField name="model_preferences" type="str | list[str] | None" default="None">
+      Hints for which model the client should use.
+    </ResponseField>
+
+    <ResponseField name="tools" type="list[Callable] | None" default="None">
+      Functions the LLM can call during sampling.
+    </ResponseField>
+
+    <ResponseField name="result_type" type="type[T] | None" default="None">
+      A type for validated structured output. Supports Pydantic models, dataclasses, and basic types like `int`, `list[str]`, or `dict[str, int]`.
+    </ResponseField>
+
+    <ResponseField name="mask_error_details" type="bool | None" default="None">
+      If True, mask detailed error messages from tool execution. When None (default), uses the global `settings.mask_error_details` value. Tools can raise `ToolError` to bypass masking and provide specific error messages to the LLM.
+    </ResponseField>
+
+  </Expandable>
+
+  <Expandable title="Response">
+    <ResponseField name="SamplingResult[T]" type="dataclass">
+      - `.text`: The raw text response (or JSON for structured output)
+      - `.result`: The typed result—same as `.text` for plain text, or a validated Pydantic object for structured output
+      - `.history`: All messages exchanged during sampling
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+</Card>
+
+<Card icon="code" title="ctx.sample_step()">
+<ResponseField name="ctx.sample_step" type="async method">
+  Make a single LLM sampling call. Use this for fine-grained control over the sampling loop.
+
+  <Expandable title="Parameters">
+    Same as `sample()`, plus:
+
+    <ResponseField name="tool_choice" type="str | None" default="None">
+      Controls tool usage: `"auto"`, `"required"`, or `"none"`.
+    </ResponseField>
+
+    <ResponseField name="execute_tools" type="bool" default="True">
+      If True, execute tool calls and append results to history. If False, return immediately with tool calls available for manual execution.
+    </ResponseField>
+
+    <ResponseField name="mask_error_details" type="bool | None" default="None">
+      If True, mask detailed error messages from tool execution. When None (default), uses the global `settings.mask_error_details` value. Tools can raise `ToolError` to bypass masking.
+    </ResponseField>
+
+  </Expandable>
+
+  <Expandable title="Response">
+    <ResponseField name="SampleStep" type="dataclass">
+      - `.response`: The raw LLM response
+      - `.history`: Messages including input, assistant response, and tool results
+      - `.is_tool_use`: True if the LLM requested tool execution
+      - `.tool_calls`: List of tool calls (if any)
+      - `.text`: The text content (if any)
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+</Card>
+
+## Basic Sampling
+
+The simplest use of sampling is passing a prompt string to `ctx.sample()`. The method sends the prompt to the LLM, waits for the complete response, and returns a `SamplingResult`. You can access the generated text through the `.text` attribute.
+
+```python
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP()
+
+@mcp.tool
+async def summarize(content: str, ctx: Context) -> str:
+    """Generate a summary of the provided content."""
+    result = await ctx.sample(f"Please summarize this:\n\n{content}")
+    return result.text or ""
+```
+
+The `SamplingResult` also provides `.result` (identical to `.text` for plain text responses) and `.history` containing the full message exchange—useful if you need to continue the conversation or debug the interaction.
+
+### System Prompts
+
+System prompts let you establish the LLM's role and behavioral guidelines before it processes your request. This is useful for controlling tone, enforcing constraints, or providing context that shouldn't clutter the user-facing prompt.
+
+````python
+@mcp.tool
+async def generate_code(concept: str, ctx: Context) -> str:
+    """Generate a Python code example for a concept."""
+    result = await ctx.sample(
+        messages=f"Write a Python example demonstrating '{concept}'.",
+        system_prompt=(
+            "You are an expert Python programmer. "
+            "Provide concise, working code without explanations."
+        ),
+        temperature=0.7,
+        max_tokens=300
+    )
+    return f"```python\n{result.text}\n```"
+````
+
+The `temperature` parameter controls randomness—higher values (up to 1.0) produce more varied outputs, while lower values make responses more deterministic. The `max_tokens` parameter limits response length.
+
+### Model Preferences
+
+Model preferences let you hint at which LLM the client should use for a request. You can pass a single model name or a list of preferences in priority order. These are hints rather than requirements—the actual model used depends on what the client has available.
+
+```python
+@mcp.tool
+async def technical_analysis(data: str, ctx: Context) -> str:
+    """Analyze data using a reasoning-focused model."""
+    result = await ctx.sample(
+        messages=f"Analyze this data:\n\n{data}",
+        model_preferences=["claude-opus-4-5", "gpt-5-2"],
+        temperature=0.2,
+    )
+    return result.text or ""
+```
+
+Use model preferences when different tasks benefit from different model characteristics. Creative writing might prefer faster models with higher temperature, while complex analysis might benefit from larger reasoning-focused models.
+
+### Multi-Turn Conversations
+
+For requests that need conversational context, construct a list of `SamplingMessage` objects representing the conversation history. Each message has a `role` ("user" or "assistant") and `content` (a `TextContent` object).
+
+```python
+from mcp.types import SamplingMessage, TextContent
+
+@mcp.tool
+async def contextual_analysis(query: str, data: str, ctx: Context) -> str:
+    """Analyze data with conversational context."""
+    messages = [
+        SamplingMessage(
+            role="user",
+            content=TextContent(type="text", text=f"Here's my data: {data}"),
+        ),
+        SamplingMessage(
+            role="assistant",
+            content=TextContent(type="text", text="I see the data. What would you like to know?"),
+        ),
+        SamplingMessage(
+            role="user",
+            content=TextContent(type="text", text=query),
+        ),
+    ]
+    result = await ctx.sample(messages=messages)
+    return result.text or ""
+```
+
+The LLM receives the full conversation thread and responds with awareness of the preceding context.
+
+## Structured Output
+
+<VersionBadge version="2.14.1" />
+
+When you need validated, typed data instead of free-form text, use the `result_type` parameter. FastMCP ensures the LLM returns data matching your type, handling validation and retries automatically. The `result_type` parameter accepts Pydantic models, dataclasses, and basic types like `int`, `list[str]`, or `dict[str, int]`.
+
+```python
+from pydantic import BaseModel
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP()
+
+class SentimentResult(BaseModel):
+    sentiment: str
+    confidence: float
+    reasoning: str
+
+@mcp.tool
+async def analyze_sentiment(text: str, ctx: Context) -> SentimentResult:
+    """Analyze text sentiment with structured output."""
+    result = await ctx.sample(
+        messages=f"Analyze the sentiment of: {text}",
+        result_type=SentimentResult,
+    )
+    return result.result  # A validated SentimentResult object
+```
+
+When you call this tool, the LLM returns a structured response that FastMCP validates against your Pydantic model. You access the validated object through `result.result`, while `result.text` contains the JSON representation.
+
+<Note>
+  When you pass `result_type`, `sample()` automatically creates a
+  `final_response` tool that the LLM calls to provide its response. If
+  validation fails, the error is sent back to the LLM for retry. This automatic
+  handling only applies to `sample()`—with `sample_step()`, you must manage
+  structured output yourself.
+</Note>
+
+## Sampling with Tools
+
+<VersionBadge version="2.14.1" />
+
+Sampling with tools enables agentic workflows where the LLM can call functions to gather information before responding. This implements [SEP-1577](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1577), allowing the LLM to autonomously orchestrate multi-step operations.
+
+Pass Python functions to the `tools` parameter, and FastMCP handles the execution loop automatically—calling tools, returning results to the LLM, and continuing until the LLM provides a final response.
+
+### Defining Tools
+
+Define regular Python functions with type hints and docstrings. FastMCP extracts the function's name, docstring, and parameter types to create tool schemas that the LLM can understand.
+
+```python
+from fastmcp import FastMCP, Context
+
+def search(query: str) -> str:
+    """Search the web for information."""
+    return f"Results for: {query}"
+
+def get_time() -> str:
+    """Get the current time."""
+    from datetime import datetime
+    return datetime.now().strftime("%H:%M:%S")
+
+mcp = FastMCP()
+
+@mcp.tool
+async def research(question: str, ctx: Context) -> str:
+    """Answer questions using available tools."""
+    result = await ctx.sample(
+        messages=question,
+        tools=[search, get_time],
+    )
+    return result.text or ""
+```
+
+The LLM sees each function's signature and docstring, using this information to decide when and how to call them. Tool errors are caught and sent back to the LLM, allowing it to recover gracefully. An internal safety limit prevents infinite loops.
+
+### Tool Error Handling
+
+By default, when a sampling tool raises an exception, the error message (including details) is sent back to the LLM so it can attempt recovery. To prevent sensitive information from leaking to the LLM, use the `mask_error_details` parameter:
+
+```python
+result = await ctx.sample(
+    messages=question,
+    tools=[search],
+    mask_error_details=True,  # Generic error messages only
+)
+```
+
+When `mask_error_details=True`, tool errors become generic messages like `"Error executing tool 'search'"` instead of exposing stack traces or internal details.
+
+To intentionally provide specific error messages to the LLM regardless of masking, raise `ToolError`:
+
+```python
+from fastmcp.exceptions import ToolError
+
+def search(query: str) -> str:
+    """Search for information."""
+    if not query.strip():
+        raise ToolError("Search query cannot be empty")
+    return f"Results for: {query}"
+```
+
+`ToolError` messages always pass through to the LLM, making it the escape hatch for errors you want the LLM to see and handle.
+
+For custom names or descriptions, use `SamplingTool.from_function()`:
+
+```python
+from fastmcp.server.sampling import SamplingTool
+
+tool = SamplingTool.from_function(
+    my_func,
+    name="custom_name",
+    description="Custom description"
+)
+
+result = await ctx.sample(messages="...", tools=[tool])
+```
+
+### Combining with Structured Output
+
+Combine tools with `result_type` for agentic workflows that return validated, structured data. The LLM uses your tools to gather information, then returns a response matching your type.
+
+```python
+result = await ctx.sample(
+    messages="Research Python async patterns",
+    tools=[search, fetch_url],
+    result_type=ResearchResult,
+)
+```
+
+## Loop Control
+
+<VersionBadge version="2.14.1" />
+
+While `sample()` handles the tool execution loop automatically, some scenarios require fine-grained control over each step. The `sample_step()` method makes a single LLM call and returns a `SampleStep` containing the response and updated history.
+
+Unlike `sample()`, `sample_step()` is stateless—it doesn't remember previous calls. You control the conversation by passing the full message history each time. The returned `step.history` includes all messages up through the current response, making it easy to continue the loop.
+
+Use `sample_step()` when you need to:
+
+- Inspect tool calls before they execute
+- Implement custom termination conditions
+- Add logging, metrics, or checkpointing between steps
+- Build custom agentic loops with domain-specific logic
+
+### Using sample_step()
+
+By default, `sample_step()` executes any tool calls and includes the results in the history. Call it in a loop, passing the updated history each time, until a stop condition is met.
+
+```python
+from mcp.types import SamplingMessage
+
+@mcp.tool
+async def controlled_agent(question: str, ctx: Context) -> str:
+    """Agent with manual loop control."""
+    messages: list[str | SamplingMessage] = [question]  # strings auto-convert
+
+    while True:
+        step = await ctx.sample_step(
+            messages=messages,
+            tools=[search, get_time],
+        )
+
+        if step.is_tool_use:
+            # Tools already executed (execute_tools=True by default)
+            # Log what was called before continuing
+            for call in step.tool_calls:
+                print(f"Called tool: {call.name}")
+
+        if not step.is_tool_use:
+            return step.text or ""
+
+        # Continue with updated history
+        messages = step.history
+```
+
+### SampleStep Properties
+
+Each `SampleStep` provides information about what the LLM returned:
+
+- `step.is_tool_use` — True if the LLM requested tool calls
+- `step.tool_calls` — List of tool calls requested (if any)
+- `step.text` — The text content (if any)
+- `step.history` — All messages exchanged so far
+
+The contents of `step.history` depend on `execute_tools`:
+- **`execute_tools=True`** (default): Includes tool results, ready for the next iteration
+- **`execute_tools=False`**: Includes the assistant's tool request, but you add results yourself
+
+### Manual Tool Execution
+
+Set `execute_tools=False` to handle tool execution yourself. When disabled, `step.history` contains the user message and the assistant's response with tool calls—but no tool results. You execute the tools and append the results as a user message.
+
+```python
+from mcp.types import SamplingMessage, ToolResultContent, TextContent
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP()
+
+@mcp.tool
+async def research(question: str, ctx: Context) -> str:
+    """Research with manual tool handling."""
+
+    def search(query: str) -> str:
+        return f"Results for: {query}"
+
+    def get_time() -> str:
+        return "12:00 PM"
+
+    # Map tool names to functions
+    tools = {"search": search, "get_time": get_time}
+
+    messages: list[SamplingMessage] = [question]  # strings are converted automatically
+
+    while True:
+        step = await ctx.sample_step(
+            messages=messages,
+            tools=list(tools.values()),
+            execute_tools=False,
+        )
+
+        if not step.is_tool_use:
+            return step.text or ""
+
+        # Execute tools and collect results
+        tool_results = []
+        for call in step.tool_calls:
+            fn = tools[call.name]
+            result = fn(**call.input)
+            tool_results.append(
+                ToolResultContent(
+                    type="tool_result",
+                    toolUseId=call.id,
+                    content=[TextContent(type="text", text=result)],
+                )
+            )
+
+        messages = list(step.history)
+        messages.append(SamplingMessage(role="user", content=tool_results))
+```
+
+#### Error Handling
+
+To report an error, set `isError=True`. The LLM will see the error and can decide how to proceed:
+
+```python
+tool_result = ToolResultContent(
+    type="tool_result",
+    toolUseId=call.id,
+    content=[TextContent(type="text", text="Permission denied")],
+    isError=True,
+)
+```
+
+## Fallback Handlers
+
+Client support for sampling is optional—some clients may not implement it. To ensure your tools work regardless of client capabilities, configure a `sampling_handler` that sends requests directly to an LLM provider.
+
+FastMCP provides built-in handlers for [OpenAI and Anthropic APIs](/v2/clients/sampling#built-in-handlers). These handlers support the full sampling API including tools, automatically converting your Python functions to each provider's format.
+
+<Note>
+Install handlers with `pip install fastmcp[openai]` or `pip install fastmcp[anthropic]`.
+</Note>
+
+```python
+from fastmcp import FastMCP
+from fastmcp.client.sampling.handlers.openai import OpenAISamplingHandler
+
+server = FastMCP(
+    name="My Server",
+    sampling_handler=OpenAISamplingHandler(default_model="gpt-4o-mini"),
+    sampling_handler_behavior="fallback",
+)
+```
+
+Or with Anthropic:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.client.sampling.handlers.anthropic import AnthropicSamplingHandler
+
+server = FastMCP(
+    name="My Server",
+    sampling_handler=AnthropicSamplingHandler(default_model="claude-sonnet-4-5"),
+    sampling_handler_behavior="fallback",
+)
+```
+
+### Behavior Modes
+
+The `sampling_handler_behavior` parameter controls when the handler is used:
+
+- **`"fallback"`** (default): Use the handler only when the client doesn't support sampling. This lets capable clients use their own LLM while ensuring your tools still work with clients that lack sampling support.
+- **`"always"`**: Always use the handler, bypassing the client entirely. Use this when you need guaranteed control over which LLM processes requests—for cost control, compliance requirements, or when specific model characteristics are essential.
+
+<Note>
+  Sampling with tools requires the client to advertise the `sampling.tools`
+  capability. FastMCP clients do this automatically. For external clients that
+  don't support tool-enabled sampling, configure a fallback handler with
+  `sampling_handler_behavior="always"`.
+</Note>
diff --git a/docs/v2/servers/server.mdx b/docs/v2/servers/server.mdx
new file mode 100644
index 0000000..f8519f6
--- /dev/null
+++ b/docs/v2/servers/server.mdx
@@ -0,0 +1,436 @@
+---
+title: The FastMCP Server
+sidebarTitle: Overview
+description: The core FastMCP server class for building MCP applications with tools, resources, and prompts.
+icon: server
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+The central piece of a FastMCP application is the `FastMCP` server class. This class acts as the main container for your application's tools, resources, and prompts, and manages communication with MCP clients.
+
+## Creating a Server
+
+Instantiating a server is straightforward. You typically provide a name for your server, which helps identify it in client applications or logs.
+
+```python
+from fastmcp import FastMCP
+
+# Create a basic server instance
+mcp = FastMCP(name="MyAssistantServer")
+
+# You can also add instructions for how to interact with the server
+mcp_with_instructions = FastMCP(
+    name="HelpfulAssistant",
+    instructions="""
+        This server provides data analysis tools.
+        Call get_average() to analyze numerical data.
+    """,
+)
+```
+
+The `FastMCP` constructor accepts several arguments:
+
+<Card icon="code" title="FastMCP Constructor Parameters">
+<ParamField body="name" type="str" default="FastMCP">
+  A human-readable name for your server
+</ParamField>
+
+<ParamField body="instructions" type="str | None">
+  Description of how to interact with this server. These instructions help clients understand the server's purpose and available functionality
+</ParamField>
+
+<ParamField body="version" type="str | None">
+  Version string for your server. If not provided, defaults to the FastMCP library version
+</ParamField>
+
+<ParamField body="website_url" type="str | None">
+  <VersionBadge version="2.13.0" />
+
+  URL to a website with more information about your server. Displayed in client applications
+</ParamField>
+
+<ParamField body="icons" type="list[Icon] | None">
+  <VersionBadge version="2.13.0" />
+
+  List of icon representations for your server. Icons help users visually identify your server in client applications. See [Icons](/v2/servers/icons) for detailed examples
+</ParamField>
+
+<ParamField body="auth" type="OAuthProvider | TokenVerifier | None">
+  Authentication provider for securing HTTP-based transports. See [Authentication](/v2/servers/auth/authentication) for configuration options
+</ParamField>
+
+<ParamField body="lifespan" type="AsyncContextManager | None">
+  An async context manager function for server startup and shutdown logic
+</ParamField>
+
+<ParamField body="tools" type="list[Tool | Callable] | None">
+  A list of tools (or functions to convert to tools) to add to the server. In some cases, providing tools programmatically may be more convenient than using the `@mcp.tool` decorator
+</ParamField>
+
+
+<ParamField body="include_tags" type="set[str] | None">
+  Only expose components with at least one matching tag
+</ParamField>
+
+<ParamField body="exclude_tags" type="set[str] | None">
+  Hide components with any matching tag
+</ParamField>
+
+<ParamField body="on_duplicate_tools" type='Literal["error", "warn", "replace"]' default="error">
+  How to handle duplicate tool registrations
+</ParamField>
+
+<ParamField body="on_duplicate_resources" type='Literal["error", "warn", "replace"]' default="warn">
+  How to handle duplicate resource registrations
+</ParamField>
+
+<ParamField body="on_duplicate_prompts" type='Literal["error", "warn", "replace"]' default="replace">
+  How to handle duplicate prompt registrations
+</ParamField>
+
+
+<ParamField body="strict_input_validation" type="bool" default="False">
+  <VersionBadge version="2.13.0" />
+  Controls how tool input parameters are validated. When `False` (default), FastMCP uses Pydantic's flexible validation that coerces compatible inputs (e.g., `"10"` → `10` for int parameters). When `True`, uses the MCP SDK's JSON Schema validation to validate inputs against the exact schema before passing them to your function, rejecting any type mismatches. The default mode improves compatibility with LLM clients while maintaining type safety. See [Input Validation Modes](/v2/servers/tools#input-validation-modes) for details
+</ParamField>
+
+<ParamField body="include_fastmcp_meta" type="bool" default="True">
+  <VersionBadge version="2.11.0" />
+
+  Whether to include FastMCP metadata in component responses. When `True`, component tags and other FastMCP-specific metadata are included in the `_fastmcp` namespace within each component's `meta` field. When `False`, this metadata is omitted, resulting in cleaner integration with external systems. Can be overridden globally via `FASTMCP_INCLUDE_FASTMCP_META` environment variable
+</ParamField>
+</Card>
+## Components
+
+FastMCP servers expose several types of components to the client:
+
+### Tools
+
+Tools are functions that the client can call to perform actions or access external systems.
+
+```python
+@mcp.tool
+def multiply(a: float, b: float) -> float:
+    """Multiplies two numbers together."""
+    return a * b
+```
+
+See [Tools](/v2/servers/tools) for detailed documentation.
+
+### Resources
+
+Resources expose data sources that the client can read.
+
+```python
+@mcp.resource("data://config")
+def get_config() -> dict:
+    """Provides the application configuration."""
+    return {"theme": "dark", "version": "1.0"}
+```
+
+See [Resources & Templates](/v2/servers/resources) for detailed documentation.
+
+### Resource Templates
+
+Resource templates are parameterized resources that allow the client to request specific data.
+
+```python
+@mcp.resource("users://{user_id}/profile")
+def get_user_profile(user_id: int) -> dict:
+    """Retrieves a user's profile by ID."""
+    # The {user_id} in the URI is extracted and passed to this function
+    return {"id": user_id, "name": f"User {user_id}", "status": "active"}
+```
+
+See [Resources & Templates](/v2/servers/resources) for detailed documentation.
+
+### Prompts
+
+Prompts are reusable message templates for guiding the LLM.
+
+```python
+@mcp.prompt
+def analyze_data(data_points: list[float]) -> str:
+    """Creates a prompt asking for analysis of numerical data."""
+    formatted_data = ", ".join(str(point) for point in data_points)
+    return f"Please analyze these data points: {formatted_data}"
+```
+
+See [Prompts](/v2/servers/prompts) for detailed documentation.
+
+## Tag-Based Filtering
+
+<VersionBadge version="2.8.0" />
+
+FastMCP supports tag-based filtering to selectively expose components based on configurable include/exclude tag sets. This is useful for creating different views of your server for different environments or users.
+
+Components can be tagged when defined using the `tags` parameter:
+
+```python
+@mcp.tool(tags={"public", "utility"})
+def public_tool() -> str:
+    return "This tool is public"
+
+@mcp.tool(tags={"internal", "admin"})
+def admin_tool() -> str:
+    return "This tool is for admins only"
+```
+
+
+The filtering logic works as follows:
+- **Include tags**: If specified, only components with at least one matching tag are exposed
+- **Exclude tags**: Components with any matching tag are filtered out
+- **Precedence**: Exclude tags always take priority over include tags
+
+<Tip>
+To ensure a component is never exposed, you can set `enabled=False` on the component itself. To learn more, see the component-specific documentation.
+</Tip>
+
+You configure tag-based filtering when creating your server:
+
+```python
+# Only expose components tagged with "public"
+mcp = FastMCP(include_tags={"public"})
+
+# Hide components tagged as "internal" or "deprecated"  
+mcp = FastMCP(exclude_tags={"internal", "deprecated"})
+
+# Combine both: show admin tools but hide deprecated ones
+mcp = FastMCP(include_tags={"admin"}, exclude_tags={"deprecated"})
+```
+
+This filtering applies to all component types (tools, resources, resource templates, and prompts) and affects both listing and access.
+
+## Running the Server
+
+FastMCP servers need a transport mechanism to communicate with clients. You typically start your server by calling the `mcp.run()` method on your `FastMCP` instance, often within an `if __name__ == "__main__":` block in your main server script. This pattern ensures compatibility with various MCP clients.
+
+```python
+# my_server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="MyServer")
+
+@mcp.tool
+def greet(name: str) -> str:
+    """Greet a user by name."""
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    # This runs the server, defaulting to STDIO transport
+    mcp.run()
+    
+    # To use a different transport, e.g., HTTP:
+    # mcp.run(transport="http", host="127.0.0.1", port=9000)
+```
+
+FastMCP supports several transport options: 
+- STDIO (default, for local tools)
+- HTTP (recommended for web services, uses Streamable HTTP protocol)
+- SSE (legacy web transport, deprecated)
+
+The server can also be run using the FastMCP CLI.
+
+For detailed information on each transport, how to configure them (host, port, paths), and when to use which, please refer to the [**Running Your FastMCP Server**](/v2/deployment/running-server) guide.
+
+## Custom Routes
+
+When running your server with HTTP transport, you can add custom web routes alongside your MCP endpoint using the `@custom_route` decorator. This is useful for simple endpoints like health checks that need to be served alongside your MCP server:
+
+```python
+from fastmcp import FastMCP
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+
+mcp = FastMCP("MyServer")
+
+@mcp.custom_route("/health", methods=["GET"])
+async def health_check(request: Request) -> PlainTextResponse:
+    return PlainTextResponse("OK")
+
+if __name__ == "__main__":
+    mcp.run(transport="http")  # Health check at http://localhost:8000/health
+```
+
+Custom routes are served alongside your MCP endpoint and are useful for:
+- Health check endpoints for monitoring
+- Simple status or info endpoints
+- Basic webhooks or callbacks
+
+For more complex web applications, consider [mounting your MCP server into a FastAPI or Starlette app](/v2/deployment/http#integration-with-web-frameworks).
+
+## Composing Servers
+
+<VersionBadge version="2.2.0" />
+
+FastMCP supports composing multiple servers together using `import_server` (static copy) and `mount` (live link). This allows you to organize large applications into modular components or reuse existing servers.
+
+See the [Server Composition](/v2/servers/composition) guide for full details, best practices, and examples.
+
+```python
+# Example: Importing a subserver
+from fastmcp import FastMCP
+import asyncio
+
+main = FastMCP(name="Main")
+sub = FastMCP(name="Sub")
+
+@sub.tool
+def hello(): 
+    return "hi"
+
+# Mount directly
+main.mount(sub, prefix="sub")
+```
+
+## Proxying Servers
+
+<VersionBadge version="2.0.0" />
+
+FastMCP can act as a proxy for any MCP server (local or remote) using `FastMCP.as_proxy`, letting you bridge transports or add a frontend to existing servers. For example, you can expose a remote SSE server locally via stdio, or vice versa.
+
+Proxies automatically handle concurrent operations safely by creating fresh sessions for each request when using disconnected clients.
+
+See the [Proxying Servers](/v2/servers/proxy) guide for details and advanced usage.
+
+```python
+from fastmcp import FastMCP, Client
+
+backend = Client("http://example.com/mcp/sse")
+proxy = FastMCP.as_proxy(backend, name="ProxyServer")
+# Now use the proxy like any FastMCP server
+```
+
+## OpenAPI Integration
+
+<VersionBadge version="2.0.0" />
+
+FastMCP can automatically generate servers from OpenAPI specifications or existing FastAPI applications using `FastMCP.from_openapi()` and `FastMCP.from_fastapi()`. This allows you to instantly convert existing APIs into MCP servers without manual tool creation.
+
+See the [FastAPI Integration](/v2/integrations/fastapi) and [OpenAPI Integration](/v2/integrations/openapi) guides for detailed examples and configuration options.
+
+```python
+import httpx
+from fastmcp import FastMCP
+
+# From OpenAPI spec
+spec = httpx.get("https://api.example.com/openapi.json").json()
+mcp = FastMCP.from_openapi(openapi_spec=spec, client=httpx.AsyncClient())
+
+# From FastAPI app
+from fastapi import FastAPI
+app = FastAPI()
+mcp = FastMCP.from_fastapi(app=app)
+```
+
+## Server Configuration
+
+Servers can be configured using a combination of initialization arguments, global settings, and transport-specific settings.
+
+### Server-Specific Configuration
+
+Server-specific settings are passed when creating the `FastMCP` instance and control server behavior:
+
+```python
+from fastmcp import FastMCP
+
+# Configure server-specific settings
+mcp = FastMCP(
+    name="ConfiguredServer",
+    include_tags={"public", "api"},              # Only expose these tagged components
+    exclude_tags={"internal", "deprecated"},     # Hide these tagged components
+    on_duplicate_tools="error",                  # Handle duplicate registrations
+    on_duplicate_resources="warn",
+    on_duplicate_prompts="replace",
+    include_fastmcp_meta=False,                  # Disable FastMCP metadata for cleaner integration
+)
+```
+
+### Global Settings
+
+Global settings affect all FastMCP servers and can be configured via environment variables (prefixed with `FASTMCP_`) or in a `.env` file:
+
+```python
+import fastmcp
+
+# Access global settings
+print(fastmcp.settings.log_level)        # Default: "INFO"
+print(fastmcp.settings.mask_error_details)  # Default: False
+print(fastmcp.settings.strict_input_validation)  # Default: False
+print(fastmcp.settings.include_fastmcp_meta)   # Default: True
+```
+
+Common global settings include:
+- **`log_level`**: Logging level ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"), set with `FASTMCP_LOG_LEVEL`
+- **`mask_error_details`**: Whether to hide detailed error information from clients, set with `FASTMCP_MASK_ERROR_DETAILS`
+- **`strict_input_validation`**: Controls tool input validation mode (default: False for flexible coercion), set with `FASTMCP_STRICT_INPUT_VALIDATION`. See [Input Validation Modes](/v2/servers/tools#input-validation-modes)
+- **`include_fastmcp_meta`**: Whether to include FastMCP metadata in component responses (default: True), set with `FASTMCP_INCLUDE_FASTMCP_META`
+- **`env_file`**: Path to the environment file to load settings from (default: ".env"), set with `FASTMCP_ENV_FILE`. Useful when your project uses a `.env` file with syntax incompatible with python-dotenv
+
+### Transport-Specific Configuration
+
+Transport settings are provided when running the server and control network behavior:
+
+```python
+# Configure transport when running
+mcp.run(
+    transport="http",
+    host="0.0.0.0",           # Bind to all interfaces
+    port=9000,                # Custom port
+    log_level="DEBUG",        # Override global log level
+)
+
+# Or for async usage
+await mcp.run_async(
+    transport="http", 
+    host="127.0.0.1",
+    port=8080,
+)
+```
+
+### Setting Global Configuration
+
+Global FastMCP settings can be configured via environment variables (prefixed with `FASTMCP_`):
+
+```bash
+# Configure global FastMCP behavior
+export FASTMCP_LOG_LEVEL=DEBUG
+export FASTMCP_MASK_ERROR_DETAILS=True
+export FASTMCP_STRICT_INPUT_VALIDATION=False
+export FASTMCP_INCLUDE_FASTMCP_META=False
+```
+
+### Custom Tool Serialization
+
+<VersionBadge version="2.2.7" />
+
+By default, FastMCP serializes tool return values to JSON when they need to be converted to text. You can customize this behavior by providing a `tool_serializer` function when creating your server:
+
+```python
+import yaml
+from fastmcp import FastMCP
+
+# Define a custom serializer that formats dictionaries as YAML
+def yaml_serializer(data):
+    return yaml.dump(data, sort_keys=False)
+
+# Create a server with the custom serializer
+mcp = FastMCP(name="MyServer", tool_serializer=yaml_serializer)
+
+@mcp.tool
+def get_config():
+    """Returns configuration in YAML format."""
+    return {"api_key": "abc123", "debug": True, "rate_limit": 100}
+```
+
+The serializer function takes any data object and returns a string representation. This is applied to **all non-string return values** from your tools. Tools that already return strings bypass the serializer.
+
+This customization is useful when you want to:
+- Format data in a specific way (like YAML or custom formats)
+- Control specific serialization options (like indentation or sorting)
+- Add metadata or transform data before sending it to clients
+
+<Tip>
+If the serializer function raises an exception, the tool will fall back to the default JSON serialization to avoid breaking the server.
+</Tip>
diff --git a/docs/v2/servers/storage-backends.mdx b/docs/v2/servers/storage-backends.mdx
new file mode 100644
index 0000000..25b8580
--- /dev/null
+++ b/docs/v2/servers/storage-backends.mdx
@@ -0,0 +1,275 @@
+---
+title: Storage Backends
+sidebarTitle: Storage Backends
+description: Configure persistent and distributed storage for caching and OAuth state management
+icon: database
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.13.0" />
+
+FastMCP uses pluggable storage backends for caching responses and managing OAuth state. By default, all storage is in-memory, which is perfect for development but doesn't persist across restarts. FastMCP includes support for multiple storage backends, and you can easily extend it with custom implementations.
+
+<Tip>
+The storage layer is powered by **[py-key-value-aio](https://github.com/strawgate/py-key-value)**, an async key-value library maintained by a core FastMCP maintainer. This library provides a unified interface for multiple backends, making it easy to swap implementations based on your deployment needs.
+</Tip>
+
+## Available Backends
+
+### In-Memory Storage
+
+**Best for:** Development, testing, single-process deployments
+
+In-memory storage is the default for all FastMCP storage needs. It's fast, requires no setup, and is perfect for getting started.
+
+```python
+from key_value.aio.stores.memory import MemoryStore
+
+# Used by default - no configuration needed
+# But you can also be explicit:
+cache_store = MemoryStore()
+```
+
+**Characteristics:**
+- ✅ No setup required
+- ✅ Very fast
+- ❌ Data lost on restart
+- ❌ Not suitable for multi-process deployments
+
+### Disk Storage
+
+**Best for:** Single-server production deployments, persistent caching
+
+Disk storage persists data to the filesystem, allowing it to survive server restarts.
+
+```python
+from key_value.aio.stores.disk import DiskStore
+from fastmcp.server.middleware.caching import ResponseCachingMiddleware
+
+# Persistent response cache
+middleware = ResponseCachingMiddleware(
+    cache_storage=DiskStore(directory="/var/cache/fastmcp")
+)
+```
+
+Or with OAuth token storage:
+
+```python
+from fastmcp.server.auth.providers.github import GitHubProvider
+from key_value.aio.stores.disk import DiskStore
+
+auth = GitHubProvider(
+    client_id="your-id",
+    client_secret="your-secret",
+    base_url="https://your-server.com",
+    client_storage=DiskStore(directory="/var/lib/fastmcp/oauth")
+)
+```
+
+**Characteristics:**
+- ✅ Data persists across restarts
+- ✅ Good performance for moderate load
+- ❌ Not suitable for distributed deployments
+- ❌ Filesystem access required
+
+### Redis
+
+**Best for:** Distributed production deployments, shared caching across multiple servers
+
+<Note>
+Redis support requires an optional dependency: `pip install 'py-key-value-aio[redis]'`
+</Note>
+
+Redis provides distributed caching and state management, ideal for production deployments with multiple server instances.
+
+```python
+from key_value.aio.stores.redis import RedisStore
+from fastmcp.server.middleware.caching import ResponseCachingMiddleware
+
+# Distributed response cache
+middleware = ResponseCachingMiddleware(
+    cache_storage=RedisStore(host="redis.example.com", port=6379)
+)
+```
+
+With authentication:
+
+```python
+from key_value.aio.stores.redis import RedisStore
+
+cache_store = RedisStore(
+    host="redis.example.com",
+    port=6379,
+    password="your-redis-password"
+)
+```
+
+For OAuth token storage:
+
+```python
+import os
+from fastmcp.server.auth.providers.github import GitHubProvider
+from key_value.aio.stores.redis import RedisStore
+
+auth = GitHubProvider(
+    client_id=os.environ["GITHUB_CLIENT_ID"],
+    client_secret=os.environ["GITHUB_CLIENT_SECRET"],
+    base_url="https://your-server.com",
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    client_storage=RedisStore(host="redis.example.com", port=6379)
+)
+```
+
+**Characteristics:**
+- ✅ Distributed and highly available
+- ✅ Fast in-memory performance
+- ✅ Works across multiple server instances
+- ✅ Built-in TTL support
+- ❌ Requires Redis infrastructure
+- ❌ Network latency vs local storage
+
+### Other Backends from py-key-value-aio
+
+The py-key-value-aio library includes additional implementations for various storage systems:
+
+- **DynamoDB** - AWS distributed database
+- **MongoDB** - NoSQL document store
+- **Elasticsearch** - Distributed search and analytics
+- **Memcached** - Distributed memory caching
+- **RocksDB** - Embedded high-performance key-value store
+- **Valkey** - Redis-compatible server
+
+For configuration details on these backends, consult the [py-key-value-aio documentation](https://github.com/strawgate/py-key-value).
+
+<Warning>
+Before using these backends in production, review the [py-key-value documentation](https://github.com/strawgate/py-key-value) to understand the maturity level and limitations of your chosen backend. Some backends may be in preview or have specific constraints that make them unsuitable for production use.
+</Warning>
+
+## Use Cases in FastMCP
+
+### Server-Side OAuth Token Storage
+
+The [OAuth Proxy](/v2/servers/auth/oauth-proxy) and OAuth auth providers use storage for persisting OAuth client registrations and upstream tokens. **By default, storage is automatically encrypted using `FernetEncryptionWrapper`.** When providing custom storage, wrap it in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest.
+
+**Development (default behavior):**
+
+By default, FastMCP automatically manages keys and storage based on your platform:
+- **Mac/Windows**: Keys are auto-managed via system keyring, storage defaults to disk. Suitable **only** for development and local testing.
+- **Linux**: Keys are ephemeral, storage defaults to memory.
+
+No configuration needed:
+
+```python
+from fastmcp.server.auth.providers.github import GitHubProvider
+
+auth = GitHubProvider(
+    client_id="your-id",
+    client_secret="your-secret",
+    base_url="https://your-server.com"
+)
+```
+
+**Production:**
+
+For production deployments, configure explicit keys and persistent network-accessible storage with encryption:
+
+```python
+import os
+from fastmcp.server.auth.providers.github import GitHubProvider
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from cryptography.fernet import Fernet
+
+auth = GitHubProvider(
+    client_id=os.environ["GITHUB_CLIENT_ID"],
+    client_secret=os.environ["GITHUB_CLIENT_SECRET"],
+    base_url="https://your-server.com",
+    # Explicit JWT signing key (required for production)
+    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
+    # Encrypted persistent storage (required for production)
+    client_storage=FernetEncryptionWrapper(
+        key_value=RedisStore(host="redis.example.com", port=6379),
+        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
+    )
+)
+```
+
+Both parameters are required for production. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without it, tokens are stored in plaintext. See [OAuth Token Security](/v2/deployment/http#oauth-token-security) and [Key and Storage Management](/v2/servers/auth/oauth-proxy#key-and-storage-management) for complete setup details.
+
+### Response Caching Middleware
+
+The [Response Caching Middleware](/v2/servers/middleware#caching-middleware) caches tool calls, resource reads, and prompt requests. Storage configuration is passed via the `cache_storage` parameter:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.middleware.caching import ResponseCachingMiddleware
+from key_value.aio.stores.disk import DiskStore
+
+mcp = FastMCP("My Server")
+
+# Cache to disk instead of memory
+mcp.add_middleware(ResponseCachingMiddleware(
+    cache_storage=DiskStore(directory="cache")
+))
+```
+
+For multi-server deployments sharing a Redis instance:
+
+```python
+from fastmcp.server.middleware.caching import ResponseCachingMiddleware
+from key_value.aio.stores.redis import RedisStore
+from key_value.aio.wrappers.prefix_collections import PrefixCollectionsWrapper
+
+base_store = RedisStore(host="redis.example.com")
+namespaced_store = PrefixCollectionsWrapper(
+    key_value=base_store,
+    prefix="my-server"
+)
+
+middleware = ResponseCachingMiddleware(cache_storage=namespaced_store)
+```
+
+### Client-Side OAuth Token Storage
+
+The [FastMCP Client](/v2/clients/client) uses storage for persisting OAuth tokens locally. By default, tokens are stored in memory:
+
+```python
+from fastmcp.client.auth import OAuth
+from key_value.aio.stores.disk import DiskStore
+
+# Store tokens on disk for persistence across restarts
+token_storage = DiskStore(directory="~/.local/share/fastmcp/tokens")
+
+oauth_provider = OAuth(
+    mcp_url="https://your-mcp-server.com/mcp/sse",
+    token_storage=token_storage
+)
+```
+
+This allows clients to reconnect without re-authenticating after restarts.
+
+## Choosing a Backend
+
+| Backend | Development | Single Server | Multi-Server | Cloud Native |
+|---------|-------------|---------------|--------------|--------------|
+| Memory | ✅ Best | ⚠️ Limited | ❌ | ❌ |
+| Disk | ✅ Good | ✅ Recommended | ❌ | ⚠️ |
+| Redis | ⚠️ Overkill | ✅ Good | ✅ Best | ✅ Best |
+| DynamoDB | ❌ | ⚠️ | ✅ | ✅ Best (AWS) |
+| MongoDB | ❌ | ⚠️ | ✅ | ✅ Good |
+
+**Decision tree:**
+
+1. **Just starting?** Use **Memory** (default) - no configuration needed
+2. **Single server, needs persistence?** Use **Disk**
+3. **Multiple servers or cloud deployment?** Use **Redis** or **DynamoDB**
+4. **Existing infrastructure?** Look for a matching py-key-value-aio backend
+
+## More Resources
+
+- [py-key-value-aio GitHub](https://github.com/strawgate/py-key-value) - Full library documentation
+- [Response Caching Middleware](/v2/servers/middleware#caching-middleware) - Using storage for caching
+- [OAuth Token Security](/v2/deployment/http#oauth-token-security) - Production OAuth configuration
+- [HTTP Deployment](/v2/deployment/http) - Complete deployment guide
diff --git a/docs/v2/servers/tasks.mdx b/docs/v2/servers/tasks.mdx
new file mode 100644
index 0000000..daae475
--- /dev/null
+++ b/docs/v2/servers/tasks.mdx
@@ -0,0 +1,223 @@
+---
+title: Background Tasks
+sidebarTitle: Background Tasks
+description: Run long-running operations asynchronously with progress tracking
+icon: clock
+tag: "NEW"
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.14.0" />
+
+FastMCP implements the MCP background task protocol ([SEP-1686](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks)), giving your servers a production-ready distributed task scheduler with a single decorator change.
+
+<Tip>
+**What is Docket?** FastMCP's task system is powered by [Docket](https://github.com/chrisguidry/docket), originally built by [Prefect](https://prefect.io) to power [Prefect Cloud](https://www.prefect.io/prefect/cloud)'s managed task scheduling and execution service, where it processes millions of concurrent tasks every day. Docket is now open-sourced for the community.
+</Tip>
+
+
+## What Are MCP Background Tasks?
+
+In MCP, all component interactions are blocking by default. When a client calls a tool, reads a resource, or fetches a prompt, it sends a request and waits for the response. For operations that take seconds or minutes, this creates a poor user experience.
+
+The MCP background task protocol solves this by letting clients:
+1. **Start** an operation and receive a task ID immediately
+2. **Track** progress as the operation runs
+3. **Retrieve** the result when ready
+
+FastMCP handles all of this for you. Add `task=True` to your decorator, and your function gains full background execution with progress reporting, distributed processing, and horizontal scaling.
+
+### MCP Background Tasks vs Python Concurrency
+
+You can always use Python's concurrency primitives (asyncio, threads, multiprocessing) or external task queues in your FastMCP servers. FastMCP is just Python—run code however you like.
+
+MCP background tasks are different: they're **protocol-native**. This means MCP clients that support the task protocol can start operations, receive progress updates, and retrieve results through the standard MCP interface. The coordination happens at the protocol level, not inside your application code.
+
+## Enabling Background Tasks
+
+Add `task=True` to any tool, resource, resource template, or prompt decorator. This marks the component as capable of background execution.
+
+```python {6}
+import asyncio
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")
+
+@mcp.tool(task=True)
+async def slow_computation(duration: int) -> str:
+    """A long-running operation."""
+    for i in range(duration):
+        await asyncio.sleep(1)
+    return f"Completed in {duration} seconds"
+```
+
+When a client requests background execution, the call returns immediately with a task ID. The work executes in a background worker, and the client can poll for status or wait for the result.
+
+<Warning>
+Background tasks require async functions. Attempting to use `task=True` with a sync function raises a `ValueError` at registration time.
+</Warning>
+
+## Execution Modes
+
+For fine-grained control over task execution behavior, use `TaskConfig` instead of the boolean shorthand. The MCP task protocol defines three execution modes:
+
+| Mode | Client calls without task | Client calls with task |
+|------|--------------------------|------------------------|
+| `"forbidden"` | Executes synchronously | Error: task not supported |
+| `"optional"` | Executes synchronously | Executes as background task |
+| `"required"` | Error: task required | Executes as background task |
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.tasks import TaskConfig
+
+mcp = FastMCP("MyServer")
+
+# Supports both sync and background execution (default when task=True)
+@mcp.tool(task=TaskConfig(mode="optional"))
+async def flexible_task() -> str:
+    return "Works either way"
+
+# Requires background execution - errors if client doesn't request task
+@mcp.tool(task=TaskConfig(mode="required"))
+async def must_be_background() -> str:
+    return "Only runs as a background task"
+
+# No task support (default when task=False or omitted)
+@mcp.tool(task=TaskConfig(mode="forbidden"))
+async def sync_only() -> str:
+    return "Never runs as background task"
+```
+
+The boolean shortcuts map to these modes:
+- `task=True` → `TaskConfig(mode="optional")`
+- `task=False` → `TaskConfig(mode="forbidden")`
+
+### Server-Wide Default
+
+To enable background task support for all components by default, pass `tasks=True` to the constructor. Individual decorators can still override this with `task=False`.
+
+```python
+mcp = FastMCP("MyServer", tasks=True)
+```
+
+<Warning>
+If your server defines any synchronous tools, resources, or prompts, you will need to explicitly set `task=False` on their decorators to avoid an error.
+</Warning>
+
+### Graceful Degradation
+
+When a client requests background execution but the component has `mode="forbidden"`, FastMCP executes synchronously and returns the result inline. This follows the SEP-1686 specification for graceful degradation—clients can always request background execution without worrying about server capabilities.
+
+Conversely, when a component has `mode="required"` but the client doesn't request background execution, FastMCP returns an error indicating that task execution is required.
+
+### Configuration
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `FASTMCP_DOCKET_URL` | `memory://` | Backend URL (`memory://` or `redis://host:port/db`) |
+
+## Backends
+
+FastMCP supports two backends for task execution, each with different tradeoffs.
+
+### In-Memory Backend (Default)
+
+The in-memory backend (`memory://`) requires zero configuration and works out of the box.
+
+**Advantages:**
+- No external dependencies
+- Simple single-process deployment
+
+**Disadvantages:**
+- **Ephemeral**: If the server restarts, all pending tasks are lost
+- **Higher latency**: ~250ms task pickup time vs single-digit milliseconds with Redis
+- **No horizontal scaling**: Single process only—you cannot add additional workers
+
+### Redis Backend
+
+For production deployments, use Redis (or Valkey) as your backend by setting `FASTMCP_DOCKET_URL=redis://localhost:6379`.
+
+**Advantages:**
+- **Persistent**: Tasks survive server restarts
+- **Fast**: Single-digit millisecond task pickup latency
+- **Scalable**: Add workers to distribute load across processes or machines
+
+## Workers
+
+Every FastMCP server with task-enabled components automatically starts an **embedded worker**. You do not need to start a separate worker process for tasks to execute.
+
+To scale horizontally, add more workers using the CLI:
+
+```bash
+fastmcp tasks worker server.py
+```
+
+Each additional worker pulls tasks from the same queue, distributing load across processes. Configure worker concurrency via environment:
+
+```bash
+export FASTMCP_DOCKET_CONCURRENCY=20
+fastmcp tasks worker server.py
+```
+
+<Note>
+Additional workers only work with Redis/Valkey backends. The in-memory backend is single-process only.
+</Note>
+
+## Progress Reporting
+
+The `Progress` dependency lets you report progress back to clients. Inject it as a parameter with a default value, and FastMCP will provide the active progress reporter.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.dependencies import Progress
+
+mcp = FastMCP("MyServer")
+
+@mcp.tool(task=True)
+async def process_files(files: list[str], progress: Progress = Progress()) -> str:
+    await progress.set_total(len(files))
+
+    for file in files:
+        await progress.set_message(f"Processing {file}")
+        # ... do work ...
+        await progress.increment()
+
+    return f"Processed {len(files)} files"
+```
+
+The progress API:
+- `await progress.set_total(n)` — Set the total number of steps
+- `await progress.increment(amount=1)` — Increment progress
+- `await progress.set_message(text)` — Update the status message
+
+Progress works in both immediate and background execution modes—you can use the same code regardless of how the client invokes your function.
+
+## Docket Dependencies
+
+FastMCP exposes Docket's full dependency injection system within your task-enabled functions. Beyond `Progress`, you can access the Docket instance, worker information, and use advanced features like retries and timeouts.
+
+```python
+from docket import Docket, Worker
+from fastmcp import FastMCP
+from fastmcp.dependencies import Progress, CurrentDocket, CurrentWorker
+
+mcp = FastMCP("MyServer")
+
+@mcp.tool(task=True)
+async def my_task(
+    progress: Progress = Progress(),
+    docket: Docket = CurrentDocket(),
+    worker: Worker = CurrentWorker(),
+) -> str:
+    # Schedule additional background work
+    await docket.add(another_task, arg1, arg2)
+
+    # Access worker metadata
+    worker_name = worker.name
+
+    return "Done"
+```
+
+With `CurrentDocket()`, you can schedule additional background tasks, chain work together, and coordinate complex workflows. See the [Docket documentation](https://chrisguidry.github.io/docket/) for the complete API, including retry policies, timeouts, and custom dependencies.
diff --git a/docs/v2/servers/tools.mdx b/docs/v2/servers/tools.mdx
new file mode 100644
index 0000000..3cdcf3b
--- /dev/null
+++ b/docs/v2/servers/tools.mdx
@@ -0,0 +1,988 @@
+---
+title: Tools
+sidebarTitle: Tools
+description: Expose functions as executable capabilities for your MCP client.
+icon: wrench
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+Tools are the core building blocks that allow your LLM to interact with external systems, execute code, and access data that isn't in its training data. In FastMCP, tools are Python functions exposed to LLMs through the MCP protocol.
+
+Tools in FastMCP transform regular Python functions into capabilities that LLMs can invoke during conversations. When an LLM decides to use a tool:
+
+1.  It sends a request with parameters based on the tool's schema.
+2.  FastMCP validates these parameters against your function's signature.
+3.  Your function executes with the validated inputs.
+4.  The result is returned to the LLM, which can use it in its response.
+
+This allows LLMs to perform tasks like querying databases, calling APIs, making calculations, or accessing files—extending their capabilities beyond what's in their training data.
+
+
+## The `@tool` Decorator
+
+Creating a tool is as simple as decorating a Python function with `@mcp.tool`:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="CalculatorServer")
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Adds two integer numbers together."""
+    return a + b
+```
+
+When this tool is registered, FastMCP automatically:
+- Uses the function name (`add`) as the tool name.
+- Uses the function's docstring (`Adds two integer numbers...`) as the tool description.
+- Generates an input schema based on the function's parameters and type annotations.
+- Handles parameter validation and error reporting.
+
+The way you define your Python function dictates how the tool appears and behaves for the LLM client.
+
+<Tip>
+Functions with `*args` or `**kwargs` are not supported as tools. This restriction exists because FastMCP needs to generate a complete parameter schema for the MCP protocol, which isn't possible with variable argument lists.
+</Tip>
+
+### Decorator Arguments
+
+While FastMCP infers the name and description from your function, you can override these and add additional metadata using arguments to the `@mcp.tool` decorator:
+
+```python
+@mcp.tool(
+    name="find_products",           # Custom tool name for the LLM
+    description="Search the product catalog with optional category filtering.", # Custom description
+    tags={"catalog", "search"},      # Optional tags for organization/filtering
+    meta={"version": "1.2", "author": "product-team"}  # Custom metadata
+)
+def search_products_implementation(query: str, category: str | None = None) -> list[dict]:
+    """Internal function description (ignored if description is provided above)."""
+    # Implementation...
+    print(f"Searching for '{query}' in category '{category}'")
+    return [{"id": 2, "name": "Another Product"}]
+```
+
+<Card icon="code" title="@tool Decorator Arguments">
+<ParamField body="name" type="str | None">
+  Sets the explicit tool name exposed via MCP. If not provided, uses the function name
+</ParamField>
+
+<ParamField body="description" type="str | None">
+  Provides the description exposed via MCP. If set, the function's docstring is ignored for this purpose
+</ParamField>
+
+<ParamField body="tags" type="set[str] | None">
+  A set of strings used to categorize the tool. These can be used by the server and, in some cases, by clients to filter or group available tools.
+</ParamField>
+
+<ParamField body="enabled" type="bool" default="True">
+  A boolean to enable or disable the tool. See [Disabling Tools](#disabling-tools) for more information
+</ParamField>
+
+<ParamField body="icons" type="list[Icon] | None">
+  <VersionBadge version="2.13.0" />
+
+  Optional list of icon representations for this tool. See [Icons](/v2/servers/icons) for detailed examples
+</ParamField>
+
+<ParamField body="annotations" type="ToolAnnotations | dict | None">
+    An optional `ToolAnnotations` object or dictionary to add additional metadata about the tool.
+  <Expandable title="ToolAnnotations attributes">
+    <ParamField body="title" type="str | None">
+      A human-readable title for the tool.
+    </ParamField>
+    <ParamField body="readOnlyHint" type="bool | None">
+      If true, the tool does not modify its environment.
+    </ParamField>
+    <ParamField body="destructiveHint" type="bool | None">
+      If true, the tool may perform destructive updates to its environment.
+    </ParamField>
+    <ParamField body="idempotentHint" type="bool | None">
+      If true, calling the tool repeatedly with the same arguments will have no additional effect on the its environment.
+    </ParamField>
+    <ParamField body="openWorldHint" type="bool | None">
+      If true, this tool may interact with an "open world" of external entities. If false, the tool's domain of interaction is closed.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="meta" type="dict[str, Any] | None">
+  <VersionBadge version="2.11.0" />
+  
+  Optional meta information about the tool. This data is passed through to the MCP client as the `_meta` field of the client-side tool object and can be used for custom metadata, versioning, or other application-specific purposes.
+</ParamField>
+</Card>
+
+
+### Async Support
+
+FastMCP is an async-first framework that seamlessly supports both asynchronous (`async def`) and synchronous (`def`) functions as tools. Async tools are preferred for I/O-bound operations to keep your server responsive.
+
+While synchronous tools work seamlessly in FastMCP, they can block the event loop during execution. For CPU-intensive or potentially blocking synchronous operations, consider alternative strategies. One approach is to use `anyio` (which FastMCP already uses internally) to wrap them as async functions, for example:
+
+```python {1, 13}
+import anyio
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+def cpu_intensive_task(data: str) -> str:
+    # Some heavy computation that could block the event loop
+    return processed_data
+
+@mcp.tool
+async def wrapped_cpu_task(data: str) -> str:
+    """CPU-intensive task wrapped to prevent blocking."""
+    return await anyio.to_thread.run_sync(cpu_intensive_task, data)
+```
+
+Alternative approaches include using `asyncio.get_event_loop().run_in_executor()` or other threading techniques to manage blocking operations without impacting server responsiveness. For example, here's a recipe for using the `asyncer` library (not included in FastMCP) to create a decorator that wraps synchronous functions, courtesy of [@hsheth2](https://github.com/PrefectHQ/fastmcp/issues/864#issuecomment-3103678258):
+
+<CodeGroup>
+```python Decorator Recipe
+import asyncer
+import functools
+from typing import Callable, ParamSpec, TypeVar, Awaitable
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+def make_async_background(fn: Callable[_P, _R]) -> Callable[_P, Awaitable[_R]]:
+    @functools.wraps(fn)
+    async def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
+        return await asyncer.asyncify(fn)(*args, **kwargs)
+
+    return wrapper
+```
+
+```python Using the Decorator {6}
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+@mcp.tool()
+@make_async_background
+def my_tool() -> None:
+    time.sleep(5)
+```
+</CodeGroup>
+
+## Arguments
+
+By default, FastMCP converts Python functions into MCP tools by inspecting the function's signature and type annotations. This allows you to use standard Python type annotations for your tools. In general, the framework strives to "just work": idiomatic Python behaviors like parameter defaults and type annotations are automatically translated into MCP schemas. However, there are a number of ways to customize the behavior of your tools.
+
+<Note>
+FastMCP automatically dereferences `$ref` entries in tool schemas to ensure compatibility with MCP clients that don't fully support JSON Schema references (e.g., VS Code Copilot, Claude Desktop). This means complex Pydantic models with shared types are inlined in the schema rather than using `$defs` references.
+</Note>
+
+### Type Annotations
+
+MCP tools have typed arguments, and FastMCP uses type annotations to determine those types. Therefore, you should use standard Python type annotations for tool arguments:
+
+```python
+@mcp.tool
+def analyze_text(
+    text: str,
+    max_tokens: int = 100,
+    language: str | None = None
+) -> dict:
+    """Analyze the provided text."""
+    # Implementation...
+```
+
+FastMCP supports a wide range of type annotations, including all Pydantic types:
+
+| Type Annotation         | Example                       | Description                         |
+| :---------------------- | :---------------------------- | :---------------------------------- |
+| Basic types             | `int`, `float`, `str`, `bool` | Simple scalar values |
+| Binary data             | `bytes`                       | Binary content (raw strings, not auto-decoded base64) |
+| Date and Time           | `datetime`, `date`, `timedelta` | Date and time objects (ISO format strings) |
+| Collection types        | `list[str]`, `dict[str, int]`, `set[int]` | Collections of items |
+| Optional types          | `float \| None`, `Optional[float]`| Parameters that may be null/omitted |
+| Union types             | `str \| int`, `Union[str, int]`| Parameters accepting multiple types |
+| Constrained types       | `Literal["A", "B"]`, `Enum`   | Parameters with specific allowed values |
+| Paths                   | `Path`                        | File system paths (auto-converted from strings) |
+| UUIDs                   | `UUID`                        | Universally unique identifiers (auto-converted from strings) |
+| Pydantic models         | `UserData`                    | Complex structured data with validation |
+
+FastMCP supports all types that Pydantic supports as fields, including all Pydantic custom types. A few FastMCP-specific behaviors to note:
+
+**Binary Data**: `bytes` parameters accept raw strings without automatic base64 decoding. For base64 data, use `str` and decode manually with `base64.b64decode()`.
+
+**Enums**: Clients send enum values (`"red"`), not names (`"RED"`). Your function receives the Enum member (`Color.RED`).
+
+**Paths and UUIDs**: String inputs are automatically converted to `Path` and `UUID` objects.
+
+**Pydantic Models**: Must be provided as JSON objects (dicts), not stringified JSON. Even with flexible validation, `{"user": {"name": "Alice"}}` works, but `{"user": '{"name": "Alice"}'}` does not.
+
+### Optional Arguments
+
+FastMCP follows Python's standard function parameter conventions. Parameters without default values are required, while those with default values are optional.
+
+```python
+@mcp.tool
+def search_products(
+    query: str,                   # Required - no default value
+    max_results: int = 10,        # Optional - has default value
+    sort_by: str = "relevance",   # Optional - has default value
+    category: str | None = None   # Optional - can be None
+) -> list[dict]:
+    """Search the product catalog."""
+    # Implementation...
+```
+
+In this example, the LLM must provide a `query` parameter, while `max_results`, `sort_by`, and `category` will use their default values if not explicitly provided.
+
+### Validation Modes
+
+<VersionBadge version="2.13.0" />
+
+By default, FastMCP uses Pydantic's flexible validation that coerces compatible inputs to match your type annotations. This improves compatibility with LLM clients that may send string representations of values (like `"10"` for an integer parameter).
+
+If you need stricter validation that rejects any type mismatches, you can enable strict input validation. Strict mode uses the MCP SDK's built-in JSON Schema validation to validate inputs against the exact schema before passing them to your function:
+
+```python
+# Enable strict validation for this server
+mcp = FastMCP("StrictServer", strict_input_validation=True)
+
+@mcp.tool
+def add_numbers(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+
+# With strict_input_validation=True, sending {"a": "10", "b": "20"} will fail
+# With strict_input_validation=False (default), it will be coerced to integers
+```
+
+**Validation Behavior Comparison:**
+
+| Input Type | strict_input_validation=False (default) | strict_input_validation=True |
+| :--------- | :-------------------------------------- | :--------------------------- |
+| String integers (`"10"` for `int`) | ✅ Coerced to integer | ❌ Validation error |
+| String floats (`"3.14"` for `float`) | ✅ Coerced to float | ❌ Validation error |
+| String booleans (`"true"` for `bool`) | ✅ Coerced to boolean | ❌ Validation error |
+| Lists with string elements (`["1", "2"]` for `list[int]`) | ✅ Elements coerced | ❌ Validation error |
+| Pydantic model fields with type mismatches | ✅ Fields coerced | ❌ Validation error |
+| Invalid values (`"abc"` for `int`) | ❌ Validation error | ❌ Validation error |
+
+<Note>
+**Note on Pydantic Models:** Even with `strict_input_validation=False`, Pydantic model parameters must be provided as JSON objects (dicts), not as stringified JSON. For example, `{"user": {"name": "Alice"}}` works, but `{"user": '{"name": "Alice"}'}` does not.
+</Note>
+
+The default flexible validation mode is recommended for most use cases as it handles common LLM client behaviors gracefully while still providing strong type safety through Pydantic's validation.
+
+### Parameter Metadata
+
+You can provide additional metadata about parameters in several ways:
+
+#### Simple String Descriptions
+
+<VersionBadge version="2.11.0" />
+
+For basic parameter descriptions, you can use a convenient shorthand with `Annotated`:
+
+```python 
+from typing import Annotated
+
+@mcp.tool
+def process_image(
+    image_url: Annotated[str, "URL of the image to process"],
+    resize: Annotated[bool, "Whether to resize the image"] = False,
+    width: Annotated[int, "Target width in pixels"] = 800,
+    format: Annotated[str, "Output image format"] = "jpeg"
+) -> dict:
+    """Process an image with optional resizing."""
+    # Implementation...
+```
+
+This shorthand syntax is equivalent to using `Field(description=...)` but more concise for simple descriptions.
+
+<Tip>
+This shorthand syntax is only applied to `Annotated` types with a single string description. 
+</Tip>
+
+#### Advanced Metadata with Field
+
+For validation constraints and advanced metadata, use Pydantic's `Field` class with `Annotated`:
+
+```python
+from typing import Annotated
+from pydantic import Field
+
+@mcp.tool
+def process_image(
+    image_url: Annotated[str, Field(description="URL of the image to process")],
+    resize: Annotated[bool, Field(description="Whether to resize the image")] = False,
+    width: Annotated[int, Field(description="Target width in pixels", ge=1, le=2000)] = 800,
+    format: Annotated[
+        Literal["jpeg", "png", "webp"], 
+        Field(description="Output image format")
+    ] = "jpeg"
+) -> dict:
+    """Process an image with optional resizing."""
+    # Implementation...
+```
+
+
+You can also use the Field as a default value, though the Annotated approach is preferred:
+
+```python
+@mcp.tool
+def search_database(
+    query: str = Field(description="Search query string"),
+    limit: int = Field(10, description="Maximum number of results", ge=1, le=100)
+) -> list:
+    """Search the database with the provided query."""
+    # Implementation...
+```
+
+Field provides several validation and documentation features:
+- `description`: Human-readable explanation of the parameter (shown to LLMs)
+- `ge`/`gt`/`le`/`lt`: Greater/less than (or equal) constraints
+- `min_length`/`max_length`: String or collection length constraints
+- `pattern`: Regex pattern for string validation
+- `default`: Default value if parameter is omitted
+
+### Hiding Parameters from the LLM
+
+<VersionBadge version="2.14.0" />
+
+To inject values at runtime without exposing them to the LLM (such as `user_id`, credentials, or database connections), use dependency injection with `Depends()`. Parameters using `Depends()` are automatically excluded from the tool schema:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.dependencies import Depends
+
+mcp = FastMCP()
+
+def get_user_id() -> str:
+    return "user_123"  # Injected at runtime
+
+@mcp.tool
+def get_user_details(user_id: str = Depends(get_user_id)) -> str:
+    # user_id is injected by the server, not provided by the LLM
+    return f"Details for {user_id}"
+```
+
+See [Custom Dependencies](/v2/servers/context#custom-dependencies) for more details on dependency injection.
+
+## Return Values
+
+
+FastMCP tools can return data in two complementary formats: **traditional content blocks** (like text and images) and **structured outputs** (machine-readable JSON). When you add return type annotations, FastMCP automatically generates **output schemas** to validate the structured data and enables clients to deserialize results back to Python objects.
+
+Understanding how these three concepts work together:
+
+- **Return Values**: What your Python function returns (determines both content blocks and structured data)
+- **Structured Outputs**: JSON data sent alongside traditional content for machine processing  
+- **Output Schemas**: JSON Schema declarations that describe and validate the structured output format
+
+The following sections explain each concept in detail.
+
+### Content Blocks
+
+FastMCP automatically converts tool return values into appropriate MCP content blocks:
+
+- **`str`**: Sent as `TextContent`
+- **`bytes`**: Base64 encoded and sent as `BlobResourceContents` (within an `EmbeddedResource`)
+- **`fastmcp.utilities.types.Image`**: Sent as `ImageContent`
+- **`fastmcp.utilities.types.Audio`**: Sent as `AudioContent`
+- **`fastmcp.utilities.types.File`**: Sent as base64-encoded `EmbeddedResource`
+- **MCP SDK content blocks**: Sent as-is
+- **A list of any of the above**: Converts each item according to the above rules
+- **`None`**: Results in an empty response
+
+#### Media Helper Classes
+
+FastMCP provides helper classes for returning images, audio, and files. When you return one of these classes, either directly or as part of a list, FastMCP automatically converts it to the appropriate MCP content block. For example, if you return a `fastmcp.utilities.types.Image` object, FastMCP will convert it to an MCP `ImageContent` block with the correct MIME type and base64 encoding.
+
+```python
+from fastmcp.utilities.types import Image, Audio, File
+
+@mcp.tool
+def get_chart() -> Image:
+    """Generate a chart image."""
+    return Image(path="chart.png")
+
+@mcp.tool
+def get_multiple_charts() -> list[Image]:
+    """Return multiple charts."""
+    return [Image(path="chart1.png"), Image(path="chart2.png")]
+```
+
+<Tip>
+Helper classes are only automatically converted to MCP content blocks when returned **directly** or as part of a **list**. For more complex containers like dicts, you can manually convert them to MCP types:
+
+```python
+# ✅ Automatic conversion
+return Image(path="chart.png")
+return [Image(path="chart1.png"), "text content"]
+
+# ❌ Will not be automatically converted
+return {"image": Image(path="chart.png")}
+
+# ✅ Manual conversion for nested use
+return {"image": Image(path="chart.png").to_image_content()}
+```
+</Tip>
+
+Each helper class accepts either `path=` or `data=` (mutually exclusive):
+- **`path`**: File path (string or Path object) - MIME type detected from extension
+- **`data`**: Raw bytes - requires `format=` parameter for MIME type
+- **`format`**: Optional format override (e.g., "png", "wav", "pdf")
+- **`name`**: Optional name for `File` when using `data=`
+- **`annotations`**: Optional MCP annotations for the content
+
+### Structured Output
+
+<VersionBadge version="2.10.0" />
+
+The 6/18/2025 MCP spec update [introduced](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content) structured content, which is a new way to return data from tools. Structured content is a JSON object that is sent alongside traditional content. FastMCP automatically creates structured outputs alongside traditional content when your tool returns data that has a JSON object representation. This provides machine-readable JSON data that clients can deserialize back to Python objects.
+
+**Automatic Structured Content Rules:**
+- **Object-like results** (`dict`, Pydantic models, dataclasses) → Always become structured content (even without output schema)  
+- **Non-object results** (`int`, `str`, `list`) → Only become structured content if there's an output schema to validate/serialize them
+- **All results** → Always become traditional content blocks for backward compatibility
+
+<Note>
+This automatic behavior enables clients to receive machine-readable data alongside human-readable content without requiring explicit output schemas for object-like returns.
+</Note>
+
+#### Dictionaries and Objects
+
+When your tool returns a dictionary, dataclass, or Pydantic model, FastMCP automatically creates structured content from it. The structured content contains the actual object data, making it easy for clients to deserialize back to native objects.
+
+<CodeGroup>
+```python Tool Definition
+@mcp.tool
+def get_user_data(user_id: str) -> dict:
+    """Get user data."""
+    return {"name": "Alice", "age": 30, "active": True}
+```
+
+```json MCP Result
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\n  \"name\": \"Alice\",\n  \"age\": 30,\n  \"active\": true\n}"
+    }
+  ],
+  "structuredContent": {
+    "name": "Alice",
+    "age": 30,
+    "active": true
+  }
+}
+```
+</CodeGroup>
+
+#### Primitives and Collections
+
+When your tool returns a primitive type (int, str, bool) or a collection (list, set), FastMCP needs a return type annotation to generate structured content. The annotation tells FastMCP how to validate and serialize the result.
+
+Without a type annotation, the tool only produces `content`:
+
+<CodeGroup>
+```python Tool Definition
+@mcp.tool
+def calculate_sum(a: int, b: int):
+    """Calculate sum without return annotation."""
+    return a + b  # Returns 8
+```
+
+```json MCP Result
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "8"
+    }
+  ]
+}
+```
+</CodeGroup>
+
+When you add a return annotation, such as `-> int`, FastMCP generates `structuredContent` by wrapping the primitive value in a `{"result": ...}` object, since JSON schemas require object-type roots for structured output:
+
+<CodeGroup>
+```python Tool Definition
+@mcp.tool
+def calculate_sum(a: int, b: int) -> int:
+    """Calculate sum with return annotation."""
+    return a + b  # Returns 8
+```
+
+```json MCP Result
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "8"
+    }
+  ],
+  "structuredContent": {
+    "result": 8
+  }
+}
+```
+</CodeGroup>
+
+#### Typed Models
+
+Return type annotations work with any type that can be converted to a JSON schema. Dataclasses and Pydantic models are particularly useful because FastMCP extracts their field definitions to create detailed schemas.
+
+<CodeGroup>
+```python Tool Definition
+from dataclasses import dataclass
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+@dataclass
+class Person:
+    name: str
+    age: int
+    email: str
+
+@mcp.tool
+def get_user_profile(user_id: str) -> Person:
+    """Get a user's profile information."""
+    return Person(
+        name="Alice",
+        age=30,
+        email="alice@example.com",
+    )
+```
+
+```json Generated Output Schema
+{
+  "properties": {
+    "name": {"title": "Name", "type": "string"},
+    "age": {"title": "Age", "type": "integer"},
+    "email": {"title": "Email", "type": "string"}
+  },
+  "required": ["name", "age", "email"],
+  "title": "Person",
+  "type": "object"
+}
+```
+
+```json MCP Result
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\"name\": \"Alice\", \"age\": 30, \"email\": \"alice@example.com\"}"
+    }
+  ],
+  "structuredContent": {
+    "name": "Alice",
+    "age": 30,
+    "email": "alice@example.com"
+  }
+}
+```
+</CodeGroup>
+
+The `Person` dataclass becomes an output schema (second tab) that describes the expected format. When executed, clients receive the result (third tab) with both `content` and `structuredContent` fields.
+
+### Output Schemas
+
+<VersionBadge version="2.10.0" />
+
+The 6/18/2025 MCP spec update [introduced](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#output-schema) output schemas, which are a new way to describe the expected output format of a tool. When an output schema is provided, the tool *must* return structured output that matches the schema.
+
+When you add return type annotations to your functions, FastMCP automatically generates JSON schemas that describe the expected output format. These schemas help MCP clients understand and validate the structured data they receive.
+
+#### Primitive Type Wrapping
+
+For primitive return types (like `int`, `str`, `bool`), FastMCP automatically wraps the result under a `"result"` key to create valid structured output:
+
+<CodeGroup>
+```python Primitive Return Type
+@mcp.tool
+def calculate_sum(a: int, b: int) -> int:
+    """Add two numbers together."""
+    return a + b
+```
+
+```json Generated Schema (Wrapped)
+{
+  "type": "object",
+  "properties": {
+    "result": {"type": "integer"}
+  },
+  "x-fastmcp-wrap-result": true
+}
+```
+
+```json Structured Output
+{
+  "result": 8
+}
+```
+</CodeGroup>
+
+#### Manual Schema Control
+
+You can override the automatically generated schema by providing a custom `output_schema`:
+
+```python
+@mcp.tool(output_schema={
+    "type": "object", 
+    "properties": {
+        "data": {"type": "string"},
+        "metadata": {"type": "object"}
+    }
+})
+def custom_schema_tool() -> dict:
+    """Tool with custom output schema."""
+    return {"data": "Hello", "metadata": {"version": "1.0"}}
+```
+
+Schema generation works for most common types including basic types, collections, union types, Pydantic models, TypedDict structures, and dataclasses.
+
+<Warning>
+**Important Constraints**: 
+- Output schemas must be object types (`"type": "object"`)
+- If you provide an output schema, your tool **must** return structured output that matches it
+- However, you can provide structured output without an output schema (using `ToolResult`)
+</Warning>
+
+### ToolResult and Metadata
+
+For complete control over tool responses, return a `ToolResult` object. This gives you explicit control over all aspects of the tool's output: traditional content, structured data, and metadata.
+
+```python
+from fastmcp.tools.tool import ToolResult
+from mcp.types import TextContent
+
+@mcp.tool
+def advanced_tool() -> ToolResult:
+    """Tool with full control over output."""
+    return ToolResult(
+        content=[TextContent(type="text", text="Human-readable summary")],
+        structured_content={"data": "value", "count": 42},
+        meta={"execution_time_ms": 145}
+    )
+```
+
+`ToolResult` accepts three fields:
+
+**`content`** - The traditional MCP content blocks that clients display to users. Can be a string (automatically converted to `TextContent`), a list of MCP content blocks, or any serializable value (converted to JSON string). At least one of `content` or `structured_content` must be provided.
+
+```python
+# Simple string
+ToolResult(content="Hello, world!")
+
+# List of content blocks
+ToolResult(content=[
+    TextContent(type="text", text="Result: 42"),
+    ImageContent(type="image", data="base64...", mimeType="image/png")
+])
+```
+
+**`structured_content`** - A dictionary containing structured data that matches your tool's output schema. This enables clients to programmatically process the results. If you provide `structured_content`, it must be a dictionary or `None`. If only `structured_content` is provided, it will also be used as `content` (converted to JSON string).
+
+```python
+ToolResult(
+    content="Found 3 users",
+    structured_content={"users": [{"name": "Alice"}, {"name": "Bob"}]}
+)
+```
+
+**`meta`** 
+<VersionBadge version="2.13.1" />
+Runtime metadata about the tool execution. Use this for performance metrics, debugging information, or any client-specific data that doesn't belong in the content or structured output.
+
+```python
+ToolResult(
+    content="Analysis complete",
+    structured_content={"result": "positive"},
+    meta={
+        "execution_time_ms": 145,
+        "model_version": "2.1",
+        "confidence": 0.95
+    }
+)
+```
+
+<Note>
+The `meta` field in `ToolResult` is for runtime metadata about tool execution (e.g., execution time, performance metrics). This is separate from the `meta` parameter in `@mcp.tool(meta={...})`, which provides static metadata about the tool definition itself.
+</Note>
+
+When returning `ToolResult`, you have full control - FastMCP won't automatically wrap or transform your data. `ToolResult` can be returned with or without an output schema.
+
+## Error Handling
+
+<VersionBadge version="2.4.1" />
+
+If your tool encounters an error, you can raise a standard Python exception (`ValueError`, `TypeError`, `FileNotFoundError`, custom exceptions, etc.) or a FastMCP `ToolError`.
+
+By default, all exceptions (including their details) are logged and converted into an MCP error response to be sent back to the client LLM. This helps the LLM understand failures and react appropriately.
+
+If you want to mask internal error details for security reasons, you can:
+
+1. Use the `mask_error_details=True` parameter when creating your `FastMCP` instance:
+```python
+mcp = FastMCP(name="SecureServer", mask_error_details=True)
+```
+
+2. Or use `ToolError` to explicitly control what error information is sent to clients:
+```python
+from fastmcp import FastMCP
+from fastmcp.exceptions import ToolError
+
+@mcp.tool
+def divide(a: float, b: float) -> float:
+    """Divide a by b."""
+
+    if b == 0:
+        # Error messages from ToolError are always sent to clients,
+        # regardless of mask_error_details setting
+        raise ToolError("Division by zero is not allowed.")
+    
+    # If mask_error_details=True, this message would be masked
+    if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
+        raise TypeError("Both arguments must be numbers.")
+        
+    return a / b
+```
+
+When `mask_error_details=True`, only error messages from `ToolError` will include details, other exceptions will be converted to a generic message.
+
+## Disabling Tools
+
+<VersionBadge version="2.8.0" />
+
+You can control the visibility and availability of tools by enabling or disabling them. This is useful for feature flagging, maintenance, or dynamically changing the toolset available to a client. Disabled tools will not appear in the list of available tools returned by `list_tools`, and attempting to call a disabled tool will result in an "Unknown tool" error, just as if the tool did not exist.
+
+By default, all tools are enabled. You can disable a tool upon creation using the `enabled` parameter in the decorator:
+
+```python
+@mcp.tool(enabled=False)
+def maintenance_tool():
+    """This tool is currently under maintenance."""
+    return "This tool is disabled."
+```
+
+You can also toggle a tool's state programmatically after it has been created:
+
+```python
+@mcp.tool
+def dynamic_tool():
+    return "I am a dynamic tool."
+
+# Disable and re-enable the tool
+dynamic_tool.disable()
+dynamic_tool.enable()
+```
+## MCP Annotations
+
+<VersionBadge version="2.2.7" />
+
+FastMCP allows you to add specialized metadata to your tools through annotations. These annotations communicate how tools behave to client applications without consuming token context in LLM prompts.
+
+Annotations serve several purposes in client applications:
+- Adding user-friendly titles for display purposes
+- Indicating whether tools modify data or systems
+- Describing the safety profile of tools (destructive vs. non-destructive)
+- Signaling if tools interact with external systems
+
+You can add annotations to a tool using the `annotations` parameter in the `@mcp.tool` decorator. FastMCP accepts either a plain dict or `ToolAnnotations`; the examples below use `ToolAnnotations` for consistency and stronger editor/type support.
+
+```python
+from mcp.types import ToolAnnotations
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        title="Calculate Sum",
+        readOnlyHint=True,
+        openWorldHint=False,
+    )
+)
+def calculate_sum(a: float, b: float) -> float:
+    """Add two numbers together."""
+    return a + b
+```
+
+FastMCP supports these standard annotations:
+
+| Annotation | Type | Default | Purpose |
+| :--------- | :--- | :------ | :------ |
+| `title` | string | - | Display name for user interfaces |
+| `readOnlyHint` | boolean | false | Indicates if the tool only reads without making changes |
+| `destructiveHint` | boolean | true | For non-readonly tools, signals if changes are destructive |
+| `idempotentHint` | boolean | false | Indicates if repeated identical calls have the same effect as a single call |
+| `openWorldHint` | boolean | true | Specifies if the tool interacts with external systems |
+
+Remember that annotations help make better user experiences but should be treated as advisory hints. They help client applications present appropriate UI elements and safety controls, but won't enforce security boundaries on their own. Always focus on making your annotations accurately represent what your tool actually does.
+
+### Using Annotation Hints
+
+MCP clients like Claude and ChatGPT use annotation hints to determine when to skip confirmation prompts and how to present tools to users. The most commonly used hint is `readOnlyHint`, which signals that a tool only reads data without making changes.
+
+**Read-only tools** improve user experience by:
+- Skipping confirmation prompts for safe operations
+- Allowing broader access without security concerns
+- Enabling more aggressive batching and caching
+
+Mark a tool as read-only when it retrieves data, performs calculations, or checks status without modifying state:
+
+```python
+from fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+
+mcp = FastMCP("Data Server")
+
+@mcp.tool(annotations=ToolAnnotations(readOnlyHint=True))
+def get_user(user_id: str) -> dict:
+    """Retrieve user information by ID."""
+    return {"id": user_id, "name": "Alice"}
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        idempotentHint=True,  # Same result for repeated calls
+        openWorldHint=False   # Only internal data
+    )
+)
+def search_products(query: str) -> list[dict]:
+    """Search the product catalog."""
+    return [{"id": 1, "name": "Widget", "price": 29.99}]
+
+# Write operations - no readOnlyHint
+@mcp.tool()
+def update_user(user_id: str, name: str) -> dict:
+    """Update user information."""
+    return {"id": user_id, "name": name, "updated": True}
+
+@mcp.tool(annotations=ToolAnnotations(destructiveHint=True))
+def delete_user(user_id: str) -> dict:
+    """Permanently delete a user account."""
+    return {"deleted": user_id}
+```
+
+For tools that write to databases, send notifications, create/update/delete resources, or trigger workflows, omit `readOnlyHint` or set it to `False`. Use `destructiveHint=True` for operations that cannot be undone.
+
+Client-specific behavior:
+- **ChatGPT**: Skips confirmation prompts for read-only tools in Chat mode (see [ChatGPT integration](/v2/integrations/chatgpt))
+- **Claude**: Uses hints to understand tool safety profiles and make better execution decisions
+
+## Notifications
+
+<VersionBadge version="2.9.1" />
+
+FastMCP automatically sends `notifications/tools/list_changed` notifications to connected clients when tools are added, removed, enabled, or disabled. This allows clients to stay up-to-date with the current tool set without manually polling for changes.
+
+```python
+@mcp.tool
+def example_tool() -> str:
+    return "Hello!"
+
+# These operations trigger notifications:
+mcp.add_tool(example_tool)     # Sends tools/list_changed notification
+example_tool.disable()         # Sends tools/list_changed notification  
+example_tool.enable()          # Sends tools/list_changed notification
+mcp.remove_tool("example_tool") # Sends tools/list_changed notification
+```
+
+Notifications are only sent when these operations occur within an active MCP request context (e.g., when called from within a tool or other MCP operation). Operations performed during server initialization do not trigger notifications.
+
+Clients can handle these notifications using a [message handler](/v2/clients/messages) to automatically refresh their tool lists or update their interfaces.
+
+## Accessing the MCP Context
+
+Tools can access MCP features like logging, reading resources, or reporting progress through the `Context` object. To use it, add a parameter to your tool function with the type hint `Context`.
+
+```python
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP(name="ContextDemo")
+
+@mcp.tool
+async def process_data(data_uri: str, ctx: Context) -> dict:
+    """Process data from a resource with progress reporting."""
+    await ctx.info(f"Processing data from {data_uri}")
+    
+    # Read a resource
+    resource = await ctx.read_resource(data_uri)
+    data = resource[0].content if resource else ""
+    
+    # Report progress
+    await ctx.report_progress(progress=50, total=100)
+    
+    # Example request to the client's LLM for help
+    summary = await ctx.sample(f"Summarize this in 10 words: {data[:200]}")
+    
+    await ctx.report_progress(progress=100, total=100)
+    return {
+        "length": len(data),
+        "summary": summary.text
+    }
+```
+
+The Context object provides access to:
+
+- **Logging**: `ctx.debug()`, `ctx.info()`, `ctx.warning()`, `ctx.error()`
+- **Progress Reporting**: `ctx.report_progress(progress, total)`
+- **Resource Access**: `ctx.read_resource(uri)`
+- **LLM Sampling**: `ctx.sample(...)`
+- **Request Information**: `ctx.request_id`, `ctx.client_id`
+
+For full documentation on the Context object and all its capabilities, see the [Context documentation](/v2/servers/context).
+
+## Server Behavior
+
+### Duplicate Tools
+
+<VersionBadge version="2.1.0" />
+
+You can control how the FastMCP server behaves if you try to register multiple tools with the same name. This is configured using the `on_duplicate_tools` argument when creating the `FastMCP` instance.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(
+    name="StrictServer",
+    # Configure behavior for duplicate tool names
+    on_duplicate_tools="error"
+)
+
+@mcp.tool
+def my_tool(): return "Version 1"
+
+# This will now raise a ValueError because 'my_tool' already exists
+# and on_duplicate_tools is set to "error".
+# @mcp.tool
+# def my_tool(): return "Version 2"
+```
+
+The duplicate behavior options are:
+
+-   `"warn"` (default): Logs a warning and the new tool replaces the old one.
+-   `"error"`: Raises a `ValueError`, preventing the duplicate registration.
+-   `"replace"`: Silently replaces the existing tool with the new one.
+-   `"ignore"`: Keeps the original tool and ignores the new registration attempt.
+
+### Removing Tools
+
+<VersionBadge version="2.3.4" />
+
+You can dynamically remove tools from a server using the `remove_tool` method:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="DynamicToolServer")
+
+@mcp.tool
+def calculate_sum(a: int, b: int) -> int:
+    """Add two numbers together."""
+    return a + b
+
+mcp.remove_tool("calculate_sum")
+```
diff --git a/docs/v2/tutorials/create-mcp-server.mdx b/docs/v2/tutorials/create-mcp-server.mdx
new file mode 100644
index 0000000..280733a
--- /dev/null
+++ b/docs/v2/tutorials/create-mcp-server.mdx
@@ -0,0 +1,198 @@
+---
+title: "How to Create an MCP Server in Python"
+sidebarTitle: "Creating an MCP Server"
+description: "A step-by-step guide to building a Model Context Protocol (MCP) server using Python and FastMCP, from basic tools to dynamic resources."
+icon: server
+---
+
+So you want to build a Model Context Protocol (MCP) server in Python. The goal is to create a service that can provide tools and data to AI models like Claude, Gemini, or others that support the protocol. While the [MCP specification](https://modelcontextprotocol.io/specification/) is powerful, implementing it from scratch involves a lot of boilerplate: handling JSON-RPC, managing session state, and correctly formatting requests and responses.
+
+This is where **FastMCP** comes in. It's a high-level framework that handles all the protocol complexities for you, letting you focus on what matters: writing the Python functions that power your server.
+
+This guide will walk you through creating a fully-featured MCP server from scratch using FastMCP.
+
+<Tip>
+Every code block in this tutorial is a complete, runnable example. You can copy and paste it into a file and run it, or paste it directly into a Python REPL like IPython to try it out.
+</Tip>
+
+### Prerequisites
+
+Make sure you have FastMCP installed. If not, follow the [installation guide](/v2/getting-started/installation).
+
+```bash
+pip install fastmcp
+```
+
+
+## Step 1: Create the Basic Server
+
+Every FastMCP application starts with an instance of the `FastMCP` class. This object acts as the container for all your tools and resources.
+
+Create a new file called `my_mcp_server.py`:
+
+```python my_mcp_server.py
+from fastmcp import FastMCP
+
+# Create a server instance with a descriptive name
+mcp = FastMCP(name="My First MCP Server")
+```
+
+That's it! You have a valid (though empty) MCP server. Now, let's add some functionality.
+
+## Step 2: Add a Tool
+
+Tools are functions that an LLM can execute. Let's create a simple tool that adds two numbers.
+
+To do this, simply write a standard Python function and decorate it with `@mcp.tool`.
+
+```python my_mcp_server.py {5-8}
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="My First MCP Server")
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Adds two integer numbers together."""
+    return a + b
+```
+
+FastMCP automatically handles the rest:
+- **Tool Name:** It uses the function name (`add`) as the tool's name.
+- **Description:** It uses the function's docstring as the tool's description for the LLM.
+- **Schema:** It inspects the type hints (`a: int`, `b: int`) to generate a JSON schema for the inputs.
+
+This is the core philosophy of FastMCP: **write Python, not protocol boilerplate.**
+
+## Step 3: Expose Data with Resources
+
+Resources provide read-only data to the LLM. You can define a resource by decorating a function with `@mcp.resource`, providing a unique URI.
+
+Let's expose a simple configuration dictionary as a resource.
+
+```python my_mcp_server.py {10-13}
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="My First MCP Server")
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Adds two integer numbers together."""
+    return a + b
+
+@mcp.resource("resource://config")
+def get_config() -> dict:
+    """Provides the application's configuration."""
+    return {"version": "1.0", "author": "MyTeam"}
+```
+
+When a client requests the URI `resource://config`, FastMCP will execute the `get_config` function and return its output (serialized as JSON) to the client. The function is only called when the resource is requested, enabling lazy-loading of data.
+
+## Step 4: Generate Dynamic Content with Resource Templates
+
+Sometimes, you need to generate resources based on parameters. This is what **Resource Templates** are for. You define them using the same `@mcp.resource` decorator but with placeholders in the URI.
+
+Let's create a template that provides a personalized greeting.
+
+```python my_mcp_server.py {15-17}
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="My First MCP Server")
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Adds two integer numbers together."""
+    return a + b
+
+@mcp.resource("resource://config")
+def get_config() -> dict:
+    """Provides the application's configuration."""
+    return {"version": "1.0", "author": "MyTeam"}
+
+@mcp.resource("greetings://{name}")
+def personalized_greeting(name: str) -> str:
+    """Generates a personalized greeting for the given name."""
+    return f"Hello, {name}! Welcome to the MCP server."
+```
+
+Now, clients can request dynamic URIs:
+- `greetings://Ford` will call `personalized_greeting(name="Ford")`.
+- `greetings://Marvin` will call `personalized_greeting(name="Marvin")`.
+
+FastMCP automatically maps the `{name}` placeholder in the URI to the `name` parameter in your function.
+
+## Step 5: Run the Server
+
+To make your server executable, add a `__main__` block to your script that calls `mcp.run()`.
+
+```python my_mcp_server.py {19-20}
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="My First MCP Server")
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Adds two integer numbers together."""
+    return a + b
+
+@mcp.resource("resource://config")
+def get_config() -> dict:
+    """Provides the application's configuration."""
+    return {"version": "1.0", "author": "MyTeam"}
+
+@mcp.resource("greetings://{name}")
+def personalized_greeting(name: str) -> str:
+    """Generates a personalized greeting for the given name."""
+    return f"Hello, {name}! Welcome to the MCP server."
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+Now you can run your server from the command line:
+```bash
+python my_mcp_server.py
+```
+This starts the server using the default **STDIO transport**, which is how clients like Claude Desktop communicate with local servers. To learn about other transports, like HTTP, see the [Running Your Server](/v2/deployment/running-server) guide.
+
+## The Complete Server
+
+Here is the full code for `my_mcp_server.py` (click to expand):
+
+```python my_mcp_server.py [expandable]
+from fastmcp import FastMCP
+
+# 1. Create the server
+mcp = FastMCP(name="My First MCP Server")
+
+# 2. Add a tool
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Adds two integer numbers together."""
+    return a + b
+
+# 3. Add a static resource
+@mcp.resource("resource://config")
+def get_config() -> dict:
+    """Provides the application's configuration."""
+    return {"version": "1.0", "author": "MyTeam"}
+
+# 4. Add a resource template for dynamic content
+@mcp.resource("greetings://{name}")
+def personalized_greeting(name: str) -> str:
+    """Generates a personalized greeting for the given name."""
+    return f"Hello, {name}! Welcome to the MCP server."
+
+# 5. Make the server runnable
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Next Steps
+
+You've successfully built an MCP server! From here, you can explore more advanced topics:
+
+-   [**Tools in Depth**](/v2/servers/tools): Learn about asynchronous tools, error handling, and custom return types.
+-   [**Resources & Templates**](/v2/servers/resources): Discover different resource types, including files and HTTP endpoints.
+-   [**Prompts**](/v2/servers/prompts): Create reusable prompt templates for your LLM.
+-   [**Running Your Server**](/v2/deployment/running-server): Deploy your server with different transports like HTTP.
+
diff --git a/docs/v2/tutorials/mcp.mdx b/docs/v2/tutorials/mcp.mdx
new file mode 100644
index 0000000..07a8db5
--- /dev/null
+++ b/docs/v2/tutorials/mcp.mdx
@@ -0,0 +1,120 @@
+---
+title: "What is the Model Context Protocol (MCP)?"
+sidebarTitle: "What is MCP?"
+description: "An introduction to the core concepts of the Model Context Protocol (MCP), explaining what it is, why it's useful, and how it works."
+icon: "diagram-project"
+---
+
+The Model Context Protocol (MCP) is an open standard designed to solve a fundamental problem in AI development: how can Large Language Models (LLMs) reliably and securely interact with external tools, data, and services?
+
+It's the **bridge between the probabilistic, non-deterministic world of AI and the deterministic, reliable world of your code and data.**
+
+While you could build a custom REST API for your LLM, MCP provides a specialized, standardized "port" for AI-native communication. Think of it as **USB-C for AI**: a single, well-defined interface for connecting any compliant LLM to any compliant tool or data source.
+
+This guide provides a high-level overview of the protocol itself. We'll use **FastMCP**, the leading Python framework for MCP, to illustrate the concepts with simple code examples.
+
+## Why Do We Need a Protocol?
+
+With countless APIs already in existence, the most common question is: "Why do we need another one?"
+
+The answer lies in **standardization**. The AI ecosystem is fragmented. Every model provider has its own way of defining and calling tools. MCP's goal is to create a common language that offers several key advantages:
+
+1.  **Interoperability:** Build one MCP server, and it can be used by any MCP-compliant client (Claude, Gemini, OpenAI, custom agents, etc.) without custom integration code. This is the protocol's most important promise.
+2.  **Discoverability:** Clients can dynamically ask a server what it's capable of at runtime. They receive a structured, machine-readable "menu" of tools and resources.
+3.  **Security & Safety:** MCP provides a clear, sandboxed boundary. An LLM can't execute arbitrary code on your server; it can only *request* to run the specific, typed, and validated functions you explicitly expose.
+4.  **Composability:** You can build small, specialized MCP servers and combine them to create powerful, complex applications.
+
+## Core MCP Components 
+
+An MCP server exposes its capabilities through three primary components: Tools, Resources, and Prompts.
+
+### Tools: Executable Actions
+
+Tools are functions that the LLM can ask the server to execute. They are the action-oriented part of MCP.
+
+In the spirit of a REST API, you can think of **Tools as being like `POST` requests.** They are used to *perform an action*, *change state*, or *trigger a side effect*, like sending an email, adding a user to a database, or making a calculation.
+
+With FastMCP, creating a tool is as simple as decorating a Python function.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+# This function is now an MCP tool named "get_weather"
+@mcp.tool
+def get_weather(city: str) -> dict:
+    """Gets the current weather for a specific city."""
+    # In a real app, this would call a weather API
+    return {"city": city, "temperature": "72F", "forecast": "Sunny"}
+```
+
+[**Learn more about Tools →**](/v2/servers/tools)
+
+### Resources: Read-Only Data
+
+Resources are data sources that the LLM can read. They are used to load information into the LLM's context, providing it with knowledge it doesn't have from its training data.
+
+Following the REST API analogy, **Resources are like `GET` requests.** Their purpose is to *retrieve information* idempotently, ideally without causing side effects. A resource can be anything from a static text file to a dynamic piece of data from a database. Each resource is identified by a unique URI.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+# This function provides a resource at the URI "system://status"
+@mcp.resource("system://status")
+def get_system_status() -> dict:
+    """Returns the current operational status of the service."""
+    return {"status": "all systems normal"}
+```
+
+#### Resource Templates
+
+You can also create **Resource Templates** for dynamic data. A client could request `users://42/profile` to get the profile for a specific user.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+# This template provides user data for any given user ID
+@mcp.resource("users://{user_id}/profile")
+def get_user_profile(user_id: str) -> dict:
+    """Returns the profile for a specific user."""
+    # Fetch user from a database...
+    return {"id": user_id, "name": "Zaphod Beeblebrox"}
+```
+
+[**Learn more about Resources & Templates →**](/v2/servers/resources)
+
+### Prompts: Reusable Instructions
+
+Prompts are reusable, parameterized message templates. They provide a way to define consistent, structured instructions that a client can request to guide the LLM's behavior for a specific task.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+@mcp.prompt
+def summarize_text(text_to_summarize: str) -> str:
+    """Creates a prompt asking the LLM to summarize a piece of text."""
+    return f"""
+        Please provide a concise, one-paragraph summary of the following text:
+        
+        {text_to_summarize}
+        """
+```
+
+[**Learn more about Prompts →**](/v2/servers/prompts)
+
+## Advanced Capabilities
+
+Beyond the core components, MCP also supports more advanced interaction patterns, such as a server requesting that the *client's* LLM generate a completion (known as **sampling**), or a server sending asynchronous **notifications** to a client. These features enable more complex, bidirectional workflows and are fully supported by FastMCP.
+
+## Next Steps
+
+Now that you understand the core concepts of the Model Context Protocol, you're ready to start building. The best place to begin is our step-by-step tutorial.
+
+[**Tutorial: How to Create an MCP Server in Python →**](/v2/tutorials/create-mcp-server)
diff --git a/docs/v2/tutorials/rest-api.mdx b/docs/v2/tutorials/rest-api.mdx
new file mode 100644
index 0000000..6524a23
--- /dev/null
+++ b/docs/v2/tutorials/rest-api.mdx
@@ -0,0 +1,203 @@
+---
+title: "How to Connect an LLM to a REST API"
+sidebarTitle: "Connect LLMs to REST APIs"
+description: "A step-by-step guide to making any REST API with an OpenAPI spec available to LLMs using FastMCP."
+icon: "plug"
+---
+
+You've built a powerful REST API, and now you want your LLM to be able to use it. Manually writing a wrapper function for every single endpoint is tedious, error-prone, and hard to maintain.
+
+This is where **FastMCP** shines. If your API has an OpenAPI (or Swagger) specification, FastMCP can automatically convert your entire API into a fully-featured MCP server, making every endpoint available as a secure, typed tool for your AI model.
+
+This guide will walk you through converting a public REST API into an MCP server in just a few lines of code.
+
+<Tip>
+Every code block in this tutorial is a complete, runnable example. You can copy and paste it into a file and run it, or paste it directly into a Python REPL like IPython to try it out.
+</Tip>
+
+### Prerequisites
+
+Make sure you have FastMCP installed. If not, follow the [installation guide](/v2/getting-started/installation).
+
+```bash
+pip install fastmcp
+```
+
+## Step 1: Choose a Target API
+
+For this tutorial, we'll use the [JSONPlaceholder API](https://jsonplaceholder.typicode.com/), a free, fake online REST API for testing and prototyping. It's perfect because it's simple and has a public OpenAPI specification.
+
+-   **API Base URL:** `https://jsonplaceholder.typicode.com`
+-   **OpenAPI Spec URL:** We'll use a community-provided spec for it.
+
+## Step 2: Create the MCP Server
+
+Now for the magic. We'll use `FastMCP.from_openapi`. This method takes an `httpx.AsyncClient` configured for your API and its OpenAPI specification, and automatically converts **every endpoint** into a callable MCP `Tool`.
+
+<Tip>
+Learn more about working with OpenAPI specs in the [OpenAPI integration docs](/v2/integrations/openapi).
+</Tip>
+
+<Note>
+For this tutorial, we'll use a simplified OpenAPI spec directly in the code. In a real project, you would typically load the spec from a URL or local file.
+</Note>
+
+Create a file named `api_server.py`:
+
+```python api_server.py {31-35}
+import httpx
+from fastmcp import FastMCP
+
+# Create an HTTP client for the target API
+client = httpx.AsyncClient(base_url="https://jsonplaceholder.typicode.com")
+
+# Define a simplified OpenAPI spec for JSONPlaceholder
+openapi_spec = {
+    "openapi": "3.0.0",
+    "info": {"title": "JSONPlaceholder API", "version": "1.0"},
+    "paths": {
+        "/users": {
+            "get": {
+                "summary": "Get all users",
+                "operationId": "get_users",
+                "responses": {"200": {"description": "A list of users."}}
+            }
+        },
+        "/users/{id}": {
+            "get": {
+                "summary": "Get a user by ID",
+                "operationId": "get_user_by_id",
+                "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}],
+                "responses": {"200": {"description": "A single user."}}
+            }
+        }
+    }
+}
+
+# Create the MCP server from the OpenAPI spec
+mcp = FastMCP.from_openapi(
+    openapi_spec=openapi_spec,
+    client=client,
+    name="JSONPlaceholder MCP Server"
+)
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+
+And that's it! With just a few lines of code, you've created an MCP server that exposes the entire JSONPlaceholder API as a collection of tools.
+
+## Step 3: Test the Generated Server
+
+Let's verify that our new MCP server works. We can use the `fastmcp.Client` to connect to it and inspect its tools.
+
+<Tip>
+Learn more about the FastMCP client in the [client docs](/v2/clients/client).
+</Tip>
+
+Create a separate file, `api_client.py`:
+
+```python api_client.py {2, 6, 9, 16}
+import asyncio
+from fastmcp import Client
+
+async def main():
+    # Connect to the MCP server we just created
+    async with Client("http://127.0.0.1:8000/mcp") as client:
+        
+        # List the tools that were automatically generated
+        tools = await client.list_tools()
+        print("Generated Tools:")
+        for tool in tools:
+            print(f"- {tool.name}")
+            
+        # Call one of the generated tools
+        print("\n\nCalling tool 'get_user_by_id'...")
+        user = await client.call_tool("get_user_by_id", {"id": 1})
+        print(f"Result:\n{user.data}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+First, run your server:
+```bash
+python api_server.py
+```
+
+Then, in another terminal, run the client:
+```bash
+python api_client.py
+```
+
+You should see a list of generated tools (`get_users`, `get_user_by_id`) and the result of calling the `get_user_by_id` tool, which fetches data from the live JSONPlaceholder API.
+
+![](/assets/images/tutorial-rest-api-result.png)
+
+
+## Step 4: Customizing Route Maps
+
+By default, FastMCP converts every API endpoint into an MCP `Tool`. This ensures maximum compatibility with contemporary LLM clients, many of which **only support the `tools` part of the MCP specification.**
+
+However, for clients that support the full MCP spec, representing `GET` requests as `Resources` can be more semantically correct and efficient.
+
+FastMCP allows users to customize this behavior using the concept of "route maps". A `RouteMap` is a mapping of an API route to an MCP type. FastMCP checks each API route against your custom maps in order. If a route matches a map, it's converted to the specified `mcp_type`. Any route that doesn't match your custom maps will fall back to the default behavior (becoming a `Tool`).
+
+<Tip>
+Learn more about route maps in the [OpenAPI integration docs](/v2/integrations/openapi#route-mapping).
+</Tip>
+
+Here’s how you can add custom route maps to turn `GET` requests into `Resources` and `ResourceTemplates` (if they have path parameters):
+
+```python api_server_with_resources.py {3, 37-42}
+import httpx
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi import RouteMap, MCPType
+
+
+# Create an HTTP client for the target API
+client = httpx.AsyncClient(base_url="https://jsonplaceholder.typicode.com")
+
+# Define a simplified OpenAPI spec for JSONPlaceholder
+openapi_spec = {
+    "openapi": "3.0.0",
+    "info": {"title": "JSONPlaceholder API", "version": "1.0"},
+    "paths": {
+        "/users": {
+            "get": {
+                "summary": "Get all users",
+                "operationId": "get_users",
+                "responses": {"200": {"description": "A list of users."}}
+            }
+        },
+        "/users/{id}": {
+            "get": {
+                "summary": "Get a user by ID",
+                "operationId": "get_user_by_id",
+                "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}],
+                "responses": {"200": {"description": "A single user."}}
+            }
+        }
+    }
+}
+
+# Create the MCP server with custom route mapping
+mcp = FastMCP.from_openapi(
+    openapi_spec=openapi_spec,
+    client=client,
+    name="JSONPlaceholder MCP Server",
+    route_maps=[
+        # Map GET requests with path parameters (e.g., /users/{id}) to ResourceTemplate
+        RouteMap(methods=["GET"], pattern=r".*\{.*\}.*", mcp_type=MCPType.RESOURCE_TEMPLATE),
+        # Map all other GET requests to Resource
+        RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE),
+    ]
+)
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
+```
+With this configuration:
+- `GET /users/{id}` becomes a `ResourceTemplate`.
+- `GET /users` becomes a `Resource`.
+- Any `POST`, `PUT`, etc. endpoints would still become `Tools` by default.
\ No newline at end of file
diff --git a/docs/v2/updates.mdx b/docs/v2/updates.mdx
new file mode 100644
index 0000000..903745a
--- /dev/null
+++ b/docs/v2/updates.mdx
@@ -0,0 +1,445 @@
+---
+title: "FastMCP Updates"
+sidebarTitle: "Updates"
+icon: "sparkles"
+tag: NEW
+---
+
+<Update label="FastMCP 2.14.7" description="April 13, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP 2.14.7: Fake It Till You Break It"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.7"
+cta="Read the release notes"
+>
+A 2.x backport of the fakeredis pin: fakeredis 2.35.0 renamed a connection class that pydocket's `memory://` backend relied on, crashing `fastmcp[tasks]` installs at startup. Caps `fakeredis<2.35.0` on the 2.x line.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.14.6" description="March 27, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP 2.14.6: $Ref Dead Redemption"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.6"
+cta="Read the release notes"
+>
+v2.14.4 backported `dereference_refs()` but never wired it into the tool schema pipeline — `$ref` and `$defs` were still sent to MCP clients. Now fixed: schemas are fully inlined before reaching clients.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.14.5" description="February 3, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP 2.14.5: Sealed Docket"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.5"
+cta="Read the release notes"
+>
+Fixes a memory leak in the memory:// docket broker where cancelled tasks accumulated instead of being cleaned up. Bumps pydocket to ≥0.17.2.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.14.4" description="January 22, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP 2.14.4: Package Deal"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.4"
+cta="Read the release notes"
+>
+Fixes a fresh install bug where the packaging library was missing as a direct dependency, plus backports $ref dereferencing in tool schemas and a task capabilities location fix.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.14.3" description="January 12, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP 2.14.3: Time After Timeout"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.3"
+cta="Read the release notes"
+>
+Sometimes five seconds just isn't enough. This release fixes an HTTP transport bug that was cutting connections short, along with OAuth and Redis fixes, better ASGI support, and CLI update notifications so you never miss a beat.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.14.2" description="December 31, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.14.2: Port Authority"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.2"
+cta="Read the release notes"
+>
+FastMCP 2.14.2 brings a wave of community contributions safely into the 2.x line. A variety of important fixes backported from 3.0 work improve OpenAPI 3.1 compatibility, MCP spec compliance for output schemas and elicitation, and correct a subtle base_url fallback issue. The CLI now gently reminds you that FastMCP 3.0 is on the horizon.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.14.1" description="December 15, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.14.1: 'Tis a Gift to Be Sample"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.1"
+cta="Read the release notes"
+>
+FastMCP 2.14.1 introduces sampling with tools (SEP-1577), enabling servers to pass tools to `ctx.sample()` for agentic workflows where the LLM can automatically execute tool calls in a loop.
+
+🤖 **Sampling with tools** lets servers leverage client LLM capabilities for multi-step agentic workflows. The new `ctx.sample_step()` method provides single LLM calls with tool inspection, while `result_type` enables structured outputs via validated Pydantic models.
+
+🔧 **AnthropicSamplingHandler** joins the existing OpenAI handler, and both are now promoted from experimental to production-ready status with a unified API.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.14.0" description="December 11, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.14.0: Task and You Shall Receive"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.0"
+cta="Read the release notes"
+>
+FastMCP 2.14 begins adopting the MCP 2025-11-25 specification, introducing protocol-native background tasks that enable long-running operations to report progress without blocking clients.
+
+⏳ **Background Tasks (SEP-1686)** let you add `task=True` to any async tool decorator. Powered by [Docket](https://github.com/chrisguidry/docket) for enterprise task scheduling—in-memory backends work out-of-the-box, Redis enables persistence and horizontal scaling.
+
+🔧 **OpenAPI Parser Promoted** from experimental to standard with improved performance through single-pass schema processing.
+
+📋 **MCP Spec Updates** including SSE polling (SEP-1699), multi-select elicitation (SEP-1330), and tool name validation (SEP-986). Also removes deprecated APIs accumulated across 2.x.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.13.3" description="December 3, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.13.3: Pin-ish Line"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.3"
+cta="Read the release notes"
+>
+Pins `mcp<1.23` as a precaution due to MCP SDK changes related to the 11/25/25 protocol update that break certain FastMCP patches and workarounds. FastMCP 2.14 introduces proper support for the updated protocol.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.13.2" description="December 1, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.13.2: Refreshing Changes"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.2"
+cta="Read the release notes"
+>
+Polishes the authentication stack with improvements to token refresh, scope handling, and multi-instance deployments.
+
+🎮 **Discord OAuth provider** added as a built-in authentication option.
+
+🔄 **Token refresh fixes** for Azure and Google providers, plus OAuth proxy improvements for multi-instance deployments.
+
+🎨 **Icon support** added to proxy classes for richer UX.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.13.1" description="November 15, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.13.1: Heavy Meta"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.1"
+cta="Read the release notes"
+>
+Introduces meta parameter support for `ToolResult`, enabling tools to return supplementary metadata alongside results for patterns like OpenAI's Apps SDK.
+
+🏷️ **Meta parameters** let tools return supplementary metadata alongside results.
+
+🔐 **New auth providers** for OCI and Supabase, plus custom token verifiers with DebugTokenVerifier for development.
+
+🔒 **Security fixes** for CVE-2025-61920 and safer Cursor deeplink URL validation on Windows.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.13.0" description="October 25, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.13.0: Cache Me If You Can"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.0"
+cta="Read the release notes"
+>
+FastMCP 2.13 "Cache Me If You Can" represents a fundamental maturation of the framework. After months of community feedback on authentication and state management, this release delivers the infrastructure FastMCP needs to handle production workloads: persistent storage, response caching, and pragmatic OAuth improvements that reflect real-world deployment challenges.
+
+💾 **Pluggable storage backends** bring persistent state to FastMCP servers. Built on [py-key-value-aio](https://github.com/strawgate/py-key-value), a new library from FastMCP maintainer Bill Easton ([@strawgate](https://github.com/strawgate)), the storage layer provides encrypted disk storage by default, platform-aware token management, and a simple key-value interface for application state. We're excited to bring this elegantly designed library into the FastMCP ecosystem - it's both powerful and remarkably easy to use, including wrappers to add encryption, TTLs, caching, and more to backends ranging from Elasticsearch, Redis, DynamoDB, filesystem, in-memory, and more!
+
+🔐 **OAuth maturity** brings months of production learnings into the framework. The new consent screen prevents confused deputy and authorization bypass attacks discovered in earlier versions, while the OAuth proxy now issues its own tokens with automatic key derivation. RFC 7662 token introspection support enables enterprise auth flows, and path prefix mounting enables OAuth-protected servers to integrate into existing web applications. FastMCP now supports out-of-the-box authentication with [WorkOS](https://gofastmcp.com/integrations/workos) and [AuthKit](https://gofastmcp.com/integrations/authkit), [GitHub](https://gofastmcp.com/integrations/github), [Google](https://gofastmcp.com/integrations/google), [Azure](https://gofastmcp.com/integrations/azure) (Entra ID), [AWS Cognito](https://gofastmcp.com/integrations/aws-cognito), [Auth0](https://gofastmcp.com/integrations/auth0), [Descope](https://gofastmcp.com/integrations/descope), [Scalekit](https://gofastmcp.com/integrations/scalekit), [JWTs](https://gofastmcp.com/servers/auth/token-verification#jwt-token-verification), and [RFC 7662 token introspection](https://gofastmcp.com/servers/auth/token-verification#token-introspection-protocol).
+
+⚡ **Response Caching Middleware** dramatically improves performance for expensive operations, while **Server lifespans** provide proper initialization and cleanup hooks that run once per server instance instead of per client session.
+
+✨ **Developer experience improvements** include Pydantic input validation, icon support, RFC 6570 query parameters for resource templates, improved Context API methods, and async file/directory resources.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.12.5" description="October 17, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.12.5: Safety Pin"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.5"
+cta="Read the release notes"
+>
+Pins MCP SDK version below 1.17 to ensure the `.well-known` payload appears in the expected location when using FastMCP auth providers with composite applications.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.12.4" description="September 26, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.12.4: OIDC What You Did There"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.4"
+cta="Read the release notes"
+>
+FastMCP 2.12.4 adds comprehensive OIDC support and expands authentication options with AWS Cognito and Descope providers. The release also includes improvements to logging middleware, URL handling for nested resources, persistent OAuth client registration storage, and various fixes to the experimental OpenAPI parser.
+
+🔐 **OIDC Configuration** brings native support for OpenID Connect, enabling seamless integration with enterprise identity providers.
+
+🏢 **Enterprise Authentication** expands with AWS Cognito and Descope providers, broadening the authentication ecosystem.
+
+🛠️ **Improved Reliability** through enhanced URL handling, persistent OAuth storage, and numerous parser fixes based on community feedback.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.12.3" description="September 17, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.12.3: Double Time"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.3"
+cta="Read the release notes"
+>
+FastMCP 2.12.3 focuses on performance and developer experience improvements. This release includes optimized auth provider imports that reduce server startup time, enhanced OIDC authentication flows, and automatic inline snapshot creation for testing.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.12.2" description="September 3, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.12.2: Perchance to Stream"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.2"
+cta="Read the release notes"
+>
+Hotfix for streamable-http transport validation in fastmcp.json configuration files, resolving a parsing error when CLI arguments were merged against the configuration spec.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.12.1" description="September 3, 2025" tags={["Releases"]}>
+<Card
+title="FastMCP 2.12.1: OAuth to Joy"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.1"
+cta="Read the release notes"
+>
+FastMCP 2.12.1 strengthens OAuth proxy implementation with improved client storage reliability, PKCE forwarding, configurable token endpoint authentication methods, and expanded scope handling based on extensive community testing.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.12" description="August 31, 2025" tags={["Releases"]}>
+<Card 
+title="FastMCP 2.12: Auth to the Races" 
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.0" 
+cta="Read the release notes"  
+>
+FastMCP 2.12 represents one of our most significant releases to date. After extensive testing and iteration with the community, we're shipping major improvements to authentication, configuration, and MCP feature adoption.
+
+🔐 **OAuth Proxy** bridges the gap for providers that don't support Dynamic Client Registration, enabling authentication with GitHub, Google, WorkOS, and Azure through minimal configuration.
+
+📋 **Declarative JSON Configuration** introduces `fastmcp.json` as the single source of truth for server settings, making MCP servers as portable and shareable as container images.
+
+🧠 **Sampling API Fallback** tackles adoption challenges by letting servers generate completions server-side when clients don't support the feature, encouraging innovation while maintaining compatibility.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.11" description="August 1, 2025" tags={["Releases"]}>
+<Card 
+title="FastMCP 2.11: Auth to a Good Start" 
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.11.0" 
+cta="Read the release notes"  
+>
+FastMCP 2.11 brings enterprise-ready authentication and dramatic performance improvements.
+
+🔒 **Comprehensive OAuth 2.1 Support** with WorkOS AuthKit integration, Dynamic Client Registration, and support for separate resource and authorization servers.
+
+⚡ **Experimental OpenAPI Parser** delivers dramatic performance gains through single-pass schema processing and optimized memory usage (enable with environment variable).
+
+💾 **Enhanced State Management** provides persistent state across tool calls with a simple dictionary interface, improving context handling and type annotations.
+
+This release emphasizes speed and simplicity while setting the foundation for future enterprise features.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.10" description="July 2, 2025" tags={["Releases"]}>
+<Card 
+title="FastMCP 2.10: Great Spec-tations" 
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.0" 
+cta="Read the release notes"  
+>
+FastMCP 2.10 achieves full compliance with the 6/18/2025 MCP specification update, introducing powerful new communication patterns.
+
+💬 **Elicitation Support** enables dynamic server-client communication and "human-in-the-loop" workflows, allowing servers to request additional information during execution.
+
+📊 **Output Schemas** provide structured outputs for tools, making results more predictable and easier to parse programmatically.
+
+🛠️ **Enhanced HTTP Routing** with OpenAPI extensions support and configurable algorithms for more flexible API integration.
+
+This release includes a breaking change to `client.call_tool()` return signatures but significantly expands the interaction capabilities of MCP servers.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.9" description="June 23, 2025" tags={["Releases", "Blog Posts"]}>
+<Card 
+title="FastMCP 2.9: MCP-Native Middleware" href="https://www.jlowin.dev/blog/fastmcp-2-9-middleware" 
+img="https://jlowin.dev/_image?href=%2F_astro%2Fhero.BkVTdeBk.jpg&w=1200&h=630&f=png" 
+cta="Read more"  
+>
+FastMCP 2.9 is a major release that, among other things, introduces two important features that push beyond the basic MCP protocol. 
+
+🤝 *MCP Middleware* brings a flexible middleware system for intercepting and controlling server operations - think authentication, logging, rate limiting, and custom business logic without touching core protocol code. 
+
+✨ *Server-side type conversion* for prompts solves a major developer pain point: while MCP requires string arguments, your functions can now work with native Python types like lists and dictionaries, with automatic conversion handling the complexity.
+
+These features transform FastMCP from a simple protocol implementation into a powerful framework for building sophisticated MCP applications. Combined with the new `File` utility for binary data and improvements to authentication and serialization, this release makes FastMCP significantly more flexible and developer-friendly while maintaining full protocol compliance.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.8" description="June 11, 2025" tags={["Releases", "Blog Posts"]}>
+<Card 
+title="FastMCP 2.8: Transform and Roll Out" href="https://www.jlowin.dev/blog/fastmcp-2-8-tool-transformation" 
+img="https://www.jlowin.dev/_image?href=%2F_astro%2Fhero.su3kspkP.png&w=1000&h=500&f=webp" 
+cta="Read more"  
+>
+FastMCP 2.8 is here, and it's all about taking control of your tools.
+
+This release is packed with new features for curating the perfect LLM experience:
+
+🛠️ Tool Transformation
+
+The headline feature lets you wrap any tool—from your own code, a third-party library, or an OpenAPI spec—to create an enhanced, LLM-friendly version. You can rename arguments, rewrite descriptions, and hide parameters without touching the original code.
+
+This feature was developed in close partnership with Bill Easton. As Bill brilliantly [put it](https://www.linkedin.com/posts/williamseaston_huge-thanks-to-william-easton-for-providing-activity-7338011349525983232-Mw6T?utm_source=share&utm_medium=member_desktop&rcm=ACoAAAAd6d0B3uL9zpCsq9eYWKi3HIvb8eN_r_Q), "Tool transformation flips Prompt Engineering on its head: stop writing tool-friendly LLM prompts and start providing LLM-friendly tools."
+
+🏷️ Component Control
+
+Now that you're transforming tools, you need a way to hide the old ones! In FastMCP 2.8 you can programmatically enable/disable any component, and for everyone who's been asking what FastMCP's tags are for—they finally have a purpose! You can now use tags to declaratively filter which components are exposed to your clients.
+
+🚀 Pragmatic by Default
+
+Lastly, to ensure maximum compatibility with the ecosystem, we've made the pragmatic decision to default all OpenAPI routes to Tools, making your entire API immediately accessible to any tool-using agent. When the industry catches up and supports resources, we'll restore the old default -- but no reason you should do extra work before OpenAI, Anthropic, or Google!
+
+</Card>
+</Update>
+
+<Update label="FastMCP 2.7" description="June 6, 2025" tags={["Releases"]}>
+<Card 
+title="FastMCP 2.7: Pare Programming" href="https://github.com/PrefectHQ/fastmcp/releases/tag/v2.7.0" 
+img="assets/updates/release-2-7.png" 
+cta="Read the release notes"  
+>
+FastMCP 2.7 has been released!
+
+Most notably, it introduces the highly requested (and Pythonic) "naked" decorator usage:
+
+```python {3}
+mcp = FastMCP()
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    return a + b
+```
+
+In addition, decorators now return the objects they create, instead of the decorated function. This is an important usability enhancement.
+
+The bulk of the update is focused on improving the FastMCP internals, including a few breaking internal changes to private APIs. A number of functions that have clung on since 1.0 are now deprecated.
+</Card>
+</Update>
+
+
+
+<Update label="FastMCP 2.6" description="June 2, 2025" tags={["Releases", "Blog Posts"]}>
+<Card 
+title="FastMCP 2.6: Blast Auth" href="https://www.jlowin.dev/blog/fastmcp-2-6" 
+img="https://www.jlowin.dev/_image?href=%2F_astro%2Fhero.Bsu8afiw.png&w=1000&h=500&f=webp" 
+cta="Read more"  
+>
+FastMCP 2.6 is here!
+
+This release introduces first-class authentication for MCP servers and clients, including pragmatic Bearer token support and seamless OAuth 2.1 integration. This release aligns with how major AI platforms are adopting MCP today, making it easier than ever to securely connect your tools to real-world AI models. Dive into the update and secure your stack with minimal friction.
+</Card>
+</Update>
+
+<Update description="May 21, 2025" label="Vibe-Testing" tags={["Blog Posts", "Tutorials"]}>
+<Card
+title="Stop Vibe-Testing Your MCP Server"
+href="https://www.jlowin.dev/blog/stop-vibe-testing-mcp-servers"
+img="https://www.jlowin.dev/_image?href=%2F_astro%2Fhero.BUPy9I9c.png&w=1000&h=500&f=webp"
+cta="Read more"
+>
+
+Your tests are bad and you should feel bad.
+
+Stop vibe-testing your MCP server through LLM guesswork. FastMCP 2.0 introduces in-memory testing for fast, deterministic, and fully Pythonic validation of your MCP logic—no network, no subprocesses, no vibes.
+
+</Card>
+</Update>
+
+
+<Update description="May 8, 2025" label="10,000 Stars" tags={["Blog Posts"]}>
+<Card
+title="Reflecting on FastMCP at 10k stars 🌟"
+href="https://www.jlowin.dev/blog/fastmcp-2-10k-stars"
+img="https://www.jlowin.dev/_image?href=%2F_astro%2Fhero.Cnvci9Q_.png&w=1000&h=500&f=webp"
+cta="Read more"
+>
+
+In just six weeks since its relaunch, FastMCP has surpassed 10,000 GitHub stars—becoming the fastest-growing OSS project in our orbit. What started as a personal itch has become the backbone of Python-based MCP servers, powering a rapidly expanding ecosystem. While the protocol itself evolves, FastMCP continues to lead with clarity, developer experience, and opinionated tooling. Here’s to what’s next.
+
+</Card>
+</Update>
+
+<Update description="May 8, 2025" label="FastMCP 2.3" tags={["Blog Posts", "Releases"]}>
+<Card
+title="Now Streaming: FastMCP 2.3"
+href="https://www.jlowin.dev/blog/fastmcp-2-3-streamable-http"
+img="https://www.jlowin.dev/_image?href=%2F_astro%2Fhero.M_hv6gEB.png&w=1000&h=500&f=webp"
+cta="Read more"
+>
+
+FastMCP 2.3 introduces full support for Streamable HTTP, a modern alternative to SSE that simplifies MCP deployments over the web. It’s efficient, reliable, and now the default HTTP transport. Just run your server with transport="http" and connect clients via a standard URL—FastMCP handles the rest. No special setup required. This release makes deploying MCP servers easier and more portable than ever.
+
+</Card>
+</Update>
+
+<Update description="April 23, 2025" label="Proxy Servers" tags={["Blog Posts", "Tutorials"]}>
+<Card
+title="MCP Proxy Servers with FastMCP 2.0"
+href="https://www.jlowin.dev/blog/fastmcp-proxy"
+img="https://www.jlowin.dev/_image?href=%2F_astro%2Frobot-hero.DpmAqgui.png&w=1000&h=500&f=webp"
+cta="Read more"
+>
+
+Even AI needs a good travel adapter 🔌
+
+
+FastMCP now supports proxying arbitrary MCP servers, letting you run a local FastMCP instance that transparently forwards requests to any remote or third-party server—regardless of transport. This enables transport bridging (e.g., stdio ⇄ SSE), simplified client configuration, and powerful gateway patterns. Proxies are fully composable with other FastMCP servers, letting you mount or import them just like local servers. Use `FastMCP.from_client()` to wrap any backend in a clean, Pythonic proxy.
+</Card>
+</Update>
+
+<Update label="FastMCP 2.0" description="April 16, 2025" tags={["Releases", "Blog Posts"]}>
+<Card
+title="Introducing FastMCP 2.0 🚀"
+href="https://www.jlowin.dev/blog/fastmcp-2"
+img="https://www.jlowin.dev/_image?href=%2F_astro%2Fhero.DpbmGNrr.png&w=1000&h=500&f=webp"
+cta="Read more"
+>
+
+This major release reimagines FastMCP as a full ecosystem platform, with powerful new features for composition, integration, and client interaction. You can now compose local and remote servers, proxy arbitrary MCP servers (with transport translation), and generate MCP servers from OpenAPI or FastAPI apps. A new client infrastructure supports advanced workflows like LLM sampling. 
+
+FastMCP 2.0 builds on the success of v1 with a cleaner, more flexible foundation—try it out today!
+</Card>
+</Update>
+
+
+
+<Update label="Official SDK" description="December 3, 2024" tags={["Announcements"]}>
+<Card
+title="FastMCP is joining the official MCP Python SDK!"
+href="https://bsky.app/profile/jlowin.dev/post/3lch4xk5cf22c"
+icon="sparkles"
+cta="Read the announcement"
+>
+FastMCP 1.0 will become part of the official MCP Python SDK!
+</Card>
+</Update>
+
+
+
+<Update label="FastMCP 1.0" description="December 1, 2024" tags={["Releases", "Blog Posts"]}>
+<Card
+title="Introducing FastMCP 🚀"
+href="https://www.jlowin.dev/blog/introducing-fastmcp"
+img="https://www.jlowin.dev/_image?href=%2F_astro%2Ffastmcp.Bep7YlTw.png&w=1000&h=500&f=webp"
+cta="Read more"
+>
+Because life's too short for boilerplate.
+
+This is where it all started. FastMCP’s launch post introduced a clean, Pythonic way to build MCP servers without the protocol overhead. Just write functions; FastMCP handles the rest. What began as a weekend project quickly became the foundation of a growing ecosystem.
+</Card>
+</Update>
+
diff --git a/examples/apps/approval/approval_server.py b/examples/apps/approval/approval_server.py
new file mode 100644
index 0000000..3c82da5
--- /dev/null
+++ b/examples/apps/approval/approval_server.py
@@ -0,0 +1,13 @@
+"""Approval gate — require human sign-off before the agent acts.
+
+Usage:
+    uv run python approval_server.py
+"""
+
+from fastmcp import FastMCP
+from fastmcp.apps.approval import Approval
+
+mcp = FastMCP("Approval Demo", providers=[Approval()])
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/apps/approvals/approvals_server.py b/examples/apps/approvals/approvals_server.py
new file mode 100644
index 0000000..c920480
--- /dev/null
+++ b/examples/apps/approvals/approvals_server.py
@@ -0,0 +1,333 @@
+"""Approval workflow — a FastMCPApp example with tabs, status badges, and action chaining.
+
+Demonstrates a multi-step interactive workflow:
+- @app.ui() entry point showing a pending approvals dashboard
+- @app.tool() backend tools that the UI calls via CallTool
+- @app.tool(model=True) for tools accessible from both model and UI
+- Tabs with filtered lists and counter badges
+- Action chaining: approve → update state → show toast
+
+Usage:
+    uv run python approvals_server.py
+"""
+
+from __future__ import annotations
+
+from prefab_ui.actions import SetState, ShowToast
+from prefab_ui.actions.mcp import CallTool
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import (
+    Badge,
+    Button,
+    Card,
+    CardContent,
+    CardHeader,
+    CardTitle,
+    Column,
+    ForEach,
+    Heading,
+    If,
+    Muted,
+    Row,
+    Separator,
+    Tab,
+    Tabs,
+    Text,
+)
+from prefab_ui.rx import ERROR, RESULT, Rx
+
+from fastmcp import FastMCP, FastMCPApp
+
+# ---------------------------------------------------------------------------
+# Data
+# ---------------------------------------------------------------------------
+
+_requests: list[dict] = [
+    {
+        "id": "REQ-001",
+        "type": "expense",
+        "title": "Client dinner — Acme Corp",
+        "submitter": "Alice Chen",
+        "description": "Business dinner with Acme Corp stakeholders to discuss Q3 partnership.",
+        "amount": 284.50,
+        "status": "pending",
+        "created_at": "2026-03-18",
+    },
+    {
+        "id": "REQ-002",
+        "type": "access",
+        "title": "Production database read access",
+        "submitter": "Bob Martinez",
+        "description": "Need read access to prod DB for quarterly analytics report.",
+        "amount": None,
+        "status": "pending",
+        "created_at": "2026-03-19",
+    },
+    {
+        "id": "REQ-003",
+        "type": "time_off",
+        "title": "Vacation — Apr 7-11",
+        "submitter": "Carol Johnson",
+        "description": "Family vacation, all deliverables handed off to David.",
+        "amount": None,
+        "status": "approved",
+        "created_at": "2026-03-15",
+    },
+    {
+        "id": "REQ-004",
+        "type": "expense",
+        "title": "Conference registration — PyCon 2026",
+        "submitter": "David Kim",
+        "description": "PyCon US 2026 early-bird registration plus tutorial day.",
+        "amount": 650.00,
+        "status": "pending",
+        "created_at": "2026-03-20",
+    },
+    {
+        "id": "REQ-005",
+        "type": "access",
+        "title": "AWS staging account access",
+        "submitter": "Eva Mueller",
+        "description": "Staging environment access for load testing new API endpoints.",
+        "amount": None,
+        "status": "rejected",
+        "created_at": "2026-03-14",
+    },
+    {
+        "id": "REQ-006",
+        "type": "expense",
+        "title": "Team offsite lunch",
+        "submitter": "Frank Okafor",
+        "description": "Catering for 12-person engineering offsite planning session.",
+        "amount": 420.00,
+        "status": "pending",
+        "created_at": "2026-03-21",
+    },
+    {
+        "id": "REQ-007",
+        "type": "time_off",
+        "title": "Personal day — Mar 28",
+        "submitter": "Grace Liu",
+        "description": "Personal appointment, will be available on Slack for emergencies.",
+        "amount": None,
+        "status": "pending",
+        "created_at": "2026-03-20",
+    },
+    {
+        "id": "REQ-008",
+        "type": "expense",
+        "title": "Software license — Figma annual",
+        "submitter": "Hassan Ali",
+        "description": "Annual Figma Professional license renewal for design team.",
+        "amount": 144.00,
+        "status": "approved",
+        "created_at": "2026-03-12",
+    },
+]
+
+
+def _by_status(status: str) -> list[dict]:
+    return [r for r in _requests if r["status"] == status]
+
+
+def _find_request(request_id: str) -> dict | None:
+    for r in _requests:
+        if r["id"] == request_id:
+            return r
+    return None
+
+
+# ---------------------------------------------------------------------------
+# App
+# ---------------------------------------------------------------------------
+
+app = FastMCPApp("Approvals")
+
+
+def _all_lists() -> dict[str, list[dict]]:
+    """Return state updates for all three status lists."""
+    return {
+        "pending_requests": _by_status("pending"),
+        "approved_requests": _by_status("approved"),
+        "rejected_requests": _by_status("rejected"),
+    }
+
+
+@app.tool()
+def approve_request(request_id: str) -> dict[str, list[dict]]:
+    """Approve a pending request and return updated lists."""
+    req = _find_request(request_id)
+    if req is None:
+        raise ValueError(f"Request {request_id} not found")
+    if req["status"] != "pending":
+        raise ValueError(f"Request {request_id} is already {req['status']}")
+    req["status"] = "approved"
+    return _all_lists()
+
+
+@app.tool()
+def reject_request(request_id: str) -> dict[str, list[dict]]:
+    """Reject a pending request and return updated lists."""
+    req = _find_request(request_id)
+    if req is None:
+        raise ValueError(f"Request {request_id} not found")
+    if req["status"] != "pending":
+        raise ValueError(f"Request {request_id} is already {req['status']}")
+    req["status"] = "rejected"
+    return _all_lists()
+
+
+@app.tool()
+def add_comment(request_id: str, comment: str) -> dict:
+    """Add a comment to a request. Returns the updated request."""
+    req = _find_request(request_id)
+    if req is None:
+        raise ValueError(f"Request {request_id} not found")
+    comments = req.setdefault("comments", [])
+    comments.append(comment)
+    return req
+
+
+@app.tool(model=True)
+def get_request_details(request_id: str) -> dict:
+    """Get full details for a single request. Available to both model and UI."""
+    req = _find_request(request_id)
+    if req is None:
+        raise ValueError(f"Request {request_id} not found")
+    return req
+
+
+@app.tool()
+def list_requests(status: str | None = None) -> list[dict]:
+    """List requests, optionally filtered by status."""
+    if status is not None:
+        return _by_status(status)
+    return list(_requests)
+
+
+def _update_all_lists() -> list:
+    """Actions to update all three status lists from a tool result."""
+    return [
+        SetState("pending_requests", RESULT.pending_requests),
+        SetState("approved_requests", RESULT.approved_requests),
+        SetState("rejected_requests", RESULT.rejected_requests),
+    ]
+
+
+def _build_request_card(
+    item: Rx,
+    *,
+    status_variant: str = "warning",
+    show_actions: bool = False,
+) -> None:
+    """Build a card for a single request inside a ForEach context."""
+    request_id = str(item.id)
+
+    with Card():
+        with CardHeader():
+            with Row(gap=2, align="center", justify="between"):
+                CardTitle(item.title)
+                Badge(item.status, variant=status_variant)
+        with CardContent(css_class="space-y-2"):
+            with Row(gap=2, align="center"):
+                Badge(item.type, variant="secondary")
+                Text(item.submitter, css_class="font-medium")
+                Muted(item.created_at)
+
+            with If(item.amount):
+                Text(item.amount.currency(), css_class="text-lg font-semibold")
+
+            Muted(item.description)
+
+            if show_actions:
+                Separator()
+                with Row(gap=2):
+                    Button(
+                        "Approve",
+                        variant="default",
+                        on_click=CallTool(
+                            approve_request,
+                            arguments={"request_id": request_id},
+                            on_success=_update_all_lists()
+                            + [
+                                ShowToast(
+                                    "Request approved",
+                                    variant="success",
+                                ),
+                            ],
+                            on_error=ShowToast(
+                                ERROR,
+                                variant="error",
+                            ),
+                        ),
+                    )
+                    Button(
+                        "Reject",
+                        variant="destructive",
+                        on_click=CallTool(
+                            reject_request,
+                            arguments={"request_id": request_id},
+                            on_success=_update_all_lists()
+                            + [
+                                ShowToast(
+                                    "Request rejected",
+                                    variant="warning",
+                                ),
+                            ],
+                            on_error=ShowToast(
+                                ERROR,
+                                variant="error",
+                            ),
+                        ),
+                    )
+
+
+@app.ui()
+def approval_dashboard() -> PrefabApp:
+    """Open the approval dashboard. The model calls this to launch the app."""
+    pending_count = Rx("pending_requests").length()
+    approved_count = Rx("approved_requests").length()
+    rejected_count = Rx("rejected_requests").length()
+
+    with Column(gap=6, css_class="p-6") as view:
+        with Row(gap=3, align="center"):
+            Heading("Approval Dashboard")
+            Badge(pending_count, variant="warning")
+            Muted("pending")
+
+        with Tabs(value="pending"):
+            with Tab(title="Pending"):
+                with If(pending_count):
+                    with ForEach("pending_requests") as item:
+                        _build_request_card(item, show_actions=True)
+                with If(~pending_count):
+                    Muted("No pending requests.")
+
+            with Tab(title="Approved"):
+                with If(approved_count):
+                    with ForEach("approved_requests") as item:
+                        _build_request_card(item, status_variant="success")
+                with If(~approved_count):
+                    Muted("No approved requests.")
+
+            with Tab(title="Rejected"):
+                with If(rejected_count):
+                    with ForEach("rejected_requests") as item:
+                        _build_request_card(item, status_variant="destructive")
+                with If(~rejected_count):
+                    Muted("No rejected requests.")
+
+    return PrefabApp(
+        view=view,
+        state={
+            "pending_requests": _by_status("pending"),
+            "approved_requests": _by_status("approved"),
+            "rejected_requests": _by_status("rejected"),
+        },
+    )
+
+
+mcp = FastMCP("Approvals Server", providers=[app])
+
+if __name__ == "__main__":
+    mcp.run(transport="http")
diff --git a/examples/apps/chart_server.py b/examples/apps/chart_server.py
new file mode 100644
index 0000000..566cd3e
--- /dev/null
+++ b/examples/apps/chart_server.py
@@ -0,0 +1,38 @@
+from prefab_ui.components import Column, Heading, Muted
+from prefab_ui.components.charts import BarChart, ChartSeries
+
+from fastmcp import FastMCP
+
+mcp = FastMCP("Sales Dashboard")
+
+DATA = [
+    {"month": "Jan", "online": 4200, "retail": 2400},
+    {"month": "Feb", "online": 3800, "retail": 2100},
+    {"month": "Mar", "online": 5100, "retail": 2800},
+    {"month": "Apr", "online": 4600, "retail": 3200},
+    {"month": "May", "online": 5800, "retail": 3100},
+    {"month": "Jun", "online": 6200, "retail": 3500},
+]
+
+
+@mcp.tool(app=True)
+def sales_chart(stacked: bool = False) -> Column:
+    """Show monthly online vs. retail sales as a bar chart."""
+    with Column(gap=4, css_class="p-6") as view:
+        Heading("Monthly Sales")
+        Muted("Online vs. retail — hover bars for details")
+        BarChart(
+            data=DATA,
+            series=[
+                ChartSeries(data_key="online", label="Online"),
+                ChartSeries(data_key="retail", label="Retail"),
+            ],
+            x_axis="month",
+            stacked=stacked,
+            show_legend=True,
+        )
+    return view
+
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/apps/choice/choice_server.py b/examples/apps/choice/choice_server.py
new file mode 100644
index 0000000..b91dfb7
--- /dev/null
+++ b/examples/apps/choice/choice_server.py
@@ -0,0 +1,13 @@
+"""Multiple choice — let the user pick from options instead of typing.
+
+Usage:
+    uv run python choice_server.py
+"""
+
+from fastmcp import FastMCP
+from fastmcp.apps.choice import Choice
+
+mcp = FastMCP("Choice Demo", providers=[Choice()])
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/apps/contacts/contacts_server.py b/examples/apps/contacts/contacts_server.py
new file mode 100644
index 0000000..66c2ba5
--- /dev/null
+++ b/examples/apps/contacts/contacts_server.py
@@ -0,0 +1,148 @@
+"""Contact manager — a FastMCPApp example with forms and callable tool references.
+
+Demonstrates the full FastMCPApp stack:
+- @app.ui() entry point that the model calls to open the app
+- @app.tool() backend tools that the UI calls via CallTool
+- CallTool(fn) with function references (not strings) that resolve to global keys
+- Form.from_model() for auto-generated Pydantic model forms
+- Manual form construction with the context-manager pattern
+
+Usage:
+    uv run python contacts_server.py
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from prefab_ui.actions import SetState, ShowToast
+from prefab_ui.actions.mcp import CallTool
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import (
+    Badge,
+    Button,
+    Column,
+    ForEach,
+    Form,
+    Heading,
+    Input,
+    Muted,
+    Row,
+    Separator,
+    Text,
+)
+from prefab_ui.rx import ERROR, RESULT, STATE
+from pydantic import BaseModel, Field
+
+from fastmcp import FastMCP, FastMCPApp
+
+# ---------------------------------------------------------------------------
+# Data
+# ---------------------------------------------------------------------------
+
+_contacts: list[dict] = [
+    {
+        "name": "Arthur Dent",
+        "email": "arthur@earth.com",
+        "category": "Customer",
+        "notes": "",
+    },
+    {
+        "name": "Ford Prefect",
+        "email": "ford@betelgeuse.org",
+        "category": "Partner",
+        "notes": "Researcher",
+    },
+]
+
+
+# ---------------------------------------------------------------------------
+# Pydantic model for auto-generated forms
+# ---------------------------------------------------------------------------
+
+
+class ContactModel(BaseModel):
+    name: str = Field(title="Full Name", min_length=1)
+    email: str = Field(title="Email")
+    category: Literal["Customer", "Vendor", "Partner", "Other"] = "Other"
+    notes: str = Field(
+        default="",
+        title="Notes",
+        json_schema_extra={"ui": {"type": "textarea"}},
+    )
+
+
+# ---------------------------------------------------------------------------
+# App
+# ---------------------------------------------------------------------------
+
+app = FastMCPApp("Contacts")
+
+
+@app.tool()
+def save_contact(data: ContactModel) -> list[dict]:
+    """Save a new contact and return the updated list."""
+    _contacts.append(data.model_dump())
+    return list(_contacts)
+
+
+@app.tool()
+def search_contacts(query: str) -> list[dict]:
+    """Filter contacts by name or email."""
+    q = query.lower()
+    return [c for c in _contacts if q in c["name"].lower() or q in c["email"].lower()]
+
+
+@app.tool(model=True)
+def list_contacts() -> list[dict]:
+    """Return all contacts. Visible to both the model and the UI."""
+    return list(_contacts)
+
+
+@app.ui()
+def contact_manager() -> PrefabApp:
+    """Open the contact manager. The model calls this to launch the app."""
+    with Column(gap=6, css_class="p-6") as view:
+        Heading("Contacts")
+
+        with ForEach("contacts") as contact:
+            with Row(gap=2, align="center"):
+                Text(contact.name, css_class="font-medium")
+                Muted(contact.email)
+                Badge(contact.category)
+
+        Separator()
+
+        Heading("Add Contact", level=3)
+        Form.from_model(
+            ContactModel,
+            on_submit=CallTool(
+                save_contact,
+                on_success=[
+                    SetState("contacts", RESULT),
+                    ShowToast("Contact saved!", variant="success"),
+                ],
+                on_error=ShowToast(ERROR, variant="error"),
+            ),
+        )
+
+        Separator()
+
+        Heading("Search", level=3)
+        with Form(
+            on_submit=CallTool(
+                search_contacts,
+                arguments={"query": STATE.query},
+                on_success=SetState("contacts", RESULT),
+            )
+        ):
+            Input(name="query", placeholder="Search by name or email...")
+            Button("Search")
+
+    return PrefabApp(view=view, state={"contacts": list(_contacts)})
+
+
+mcp = FastMCP("Contacts Server", providers=[app])
+
+if __name__ == "__main__":
+    mcp.run(transport="http")
diff --git a/examples/apps/datatable_server.py b/examples/apps/datatable_server.py
new file mode 100644
index 0000000..dc78b49
--- /dev/null
+++ b/examples/apps/datatable_server.py
@@ -0,0 +1,123 @@
+from collections import Counter
+
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import (
+    Badge,
+    Card,
+    CardContent,
+    Column,
+    Grid,
+    Heading,
+    Row,
+    Separator,
+    Text,
+)
+from prefab_ui.components.charts import BarChart, ChartSeries, PieChart
+from prefab_ui.components.data_table import DataTable, DataTableColumn
+
+from fastmcp import FastMCP
+
+mcp = FastMCP("Team Directory")
+
+TEAM = [
+    {
+        "name": "Alice Chen",
+        "role": "Engineering",
+        "level": "Senior",
+        "location": "San Francisco",
+    },
+    {"name": "Bob Martinez", "role": "Design", "level": "Lead", "location": "New York"},
+    {
+        "name": "Carol Johnson",
+        "role": "Engineering",
+        "level": "Staff",
+        "location": "London",
+    },
+    {
+        "name": "David Kim",
+        "role": "Product",
+        "level": "Senior",
+        "location": "San Francisco",
+    },
+    {"name": "Eva Müller", "role": "Engineering", "level": "Mid", "location": "Berlin"},
+    {
+        "name": "Frank Okafor",
+        "role": "Data Science",
+        "level": "Senior",
+        "location": "Lagos",
+    },
+    {
+        "name": "Grace Liu",
+        "role": "Engineering",
+        "level": "Junior",
+        "location": "Singapore",
+    },
+    {"name": "Hassan Ali", "role": "Design", "level": "Senior", "location": "Dubai"},
+]
+
+
+@mcp.tool(app=True)
+def team_directory(department: str | None = None) -> PrefabApp:
+    """Browse the team directory — sortable, searchable, with department breakdown."""
+    rows = [p for p in TEAM if not department or p["role"] == department]
+
+    dept_counts = Counter(p["role"] for p in rows)
+    chart_data = [{"department": k, "count": v} for k, v in dept_counts.items()]
+
+    level_counts = Counter(p["level"] for p in rows)
+    level_data = [{"level": k, "count": v} for k, v in level_counts.items()]
+
+    with Column(gap=6, css_class="p-6") as view:
+        with Row(gap=2, align="center"):
+            Heading("Team Directory")
+            Badge(f"{len(rows)} people", variant="secondary")
+
+        with Grid(columns=2, gap=6):
+            with Card():
+                with CardContent():
+                    Text(
+                        "By Department",
+                        css_class="text-sm font-medium text-muted-foreground mb-2",
+                    )
+                    PieChart(
+                        data=chart_data,
+                        data_key="count",
+                        name_key="department",
+                        show_legend=True,
+                        inner_radius=40,
+                        height=200,
+                    )
+
+            with Card():
+                with CardContent():
+                    Text(
+                        "By Level",
+                        css_class="text-sm font-medium text-muted-foreground mb-2",
+                    )
+                    BarChart(
+                        data=level_data,
+                        series=[ChartSeries(data_key="count", label="People")],
+                        x_axis="level",
+                        height=200,
+                        horizontal=True,
+                    )
+
+        Separator()
+
+        DataTable(
+            columns=[
+                DataTableColumn(key="name", header="Name", sortable=True),
+                DataTableColumn(key="role", header="Department", sortable=True),
+                DataTableColumn(key="level", header="Level", sortable=True),
+                DataTableColumn(key="location", header="Location", sortable=True),
+            ],
+            rows=rows,
+            search=True,
+            paginated=True,
+        )
+
+    return PrefabApp(view=view)
+
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/apps/explorer/explorer_server.py b/examples/apps/explorer/explorer_server.py
new file mode 100644
index 0000000..41896f2
--- /dev/null
+++ b/examples/apps/explorer/explorer_server.py
@@ -0,0 +1,590 @@
+"""Data explorer — a FastMCPApp example with tables, charts, and filtering.
+
+Demonstrates the full FastMCPApp stack:
+- @app.ui() entry point with a tabbed data exploration interface
+- @app.tool() backend tools for analysis, summaries, and filtering
+- DataTable with sorting, search, and pagination
+- BarChart and PieChart for data visualization
+- Metric cards for summary statistics
+- Select-driven filtering with CallTool
+- State management with PrefabApp state dict and Rx()
+
+Usage:
+    uv run python explorer_server.py               # HTTP (default)
+    uv run python explorer_server.py --stdio        # stdio for MCP clients
+"""
+
+from __future__ import annotations
+
+from prefab_ui.actions import SetState, ShowToast
+from prefab_ui.actions.mcp import CallTool
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import (
+    Badge,
+    Button,
+    Card,
+    CardContent,
+    Column,
+    DataTable,
+    DataTableColumn,
+    Grid,
+    Heading,
+    Metric,
+    Muted,
+    Row,
+    Select,
+    SelectOption,
+    Separator,
+    Tab,
+    Tabs,
+    Text,
+)
+from prefab_ui.components.charts import BarChart, ChartSeries, PieChart
+from prefab_ui.rx import ERROR, RESULT, STATE, Rx
+
+from fastmcp import FastMCP, FastMCPApp
+
+# ---------------------------------------------------------------------------
+# Sample data
+# ---------------------------------------------------------------------------
+
+SALES_DATA: list[dict] = [
+    {
+        "date": "2025-01-05",
+        "product": "Widget A",
+        "region": "North",
+        "amount": 1200,
+        "quantity": 10,
+    },
+    {
+        "date": "2025-01-12",
+        "product": "Widget B",
+        "region": "South",
+        "amount": 850,
+        "quantity": 7,
+    },
+    {
+        "date": "2025-01-18",
+        "product": "Gadget X",
+        "region": "East",
+        "amount": 2300,
+        "quantity": 15,
+    },
+    {
+        "date": "2025-01-25",
+        "product": "Gadget Y",
+        "region": "West",
+        "amount": 1750,
+        "quantity": 12,
+    },
+    {
+        "date": "2025-02-02",
+        "product": "Widget A",
+        "region": "East",
+        "amount": 1400,
+        "quantity": 11,
+    },
+    {
+        "date": "2025-02-09",
+        "product": "Widget B",
+        "region": "North",
+        "amount": 920,
+        "quantity": 8,
+    },
+    {
+        "date": "2025-02-15",
+        "product": "Gadget X",
+        "region": "South",
+        "amount": 2100,
+        "quantity": 14,
+    },
+    {
+        "date": "2025-02-22",
+        "product": "Gadget Y",
+        "region": "West",
+        "amount": 1600,
+        "quantity": 11,
+    },
+    {
+        "date": "2025-03-01",
+        "product": "Widget A",
+        "region": "South",
+        "amount": 1350,
+        "quantity": 10,
+    },
+    {
+        "date": "2025-03-08",
+        "product": "Widget B",
+        "region": "West",
+        "amount": 780,
+        "quantity": 6,
+    },
+    {
+        "date": "2025-03-14",
+        "product": "Gadget X",
+        "region": "North",
+        "amount": 2500,
+        "quantity": 17,
+    },
+    {
+        "date": "2025-03-21",
+        "product": "Gadget Y",
+        "region": "East",
+        "amount": 1900,
+        "quantity": 13,
+    },
+    {
+        "date": "2025-04-03",
+        "product": "Widget A",
+        "region": "West",
+        "amount": 1100,
+        "quantity": 9,
+    },
+    {
+        "date": "2025-04-10",
+        "product": "Widget B",
+        "region": "East",
+        "amount": 960,
+        "quantity": 8,
+    },
+    {
+        "date": "2025-04-17",
+        "product": "Gadget X",
+        "region": "South",
+        "amount": 2400,
+        "quantity": 16,
+    },
+    {
+        "date": "2025-04-24",
+        "product": "Gadget Y",
+        "region": "North",
+        "amount": 1850,
+        "quantity": 12,
+    },
+    {
+        "date": "2025-05-01",
+        "product": "Widget A",
+        "region": "North",
+        "amount": 1500,
+        "quantity": 12,
+    },
+    {
+        "date": "2025-05-08",
+        "product": "Widget B",
+        "region": "South",
+        "amount": 890,
+        "quantity": 7,
+    },
+    {
+        "date": "2025-05-15",
+        "product": "Gadget X",
+        "region": "West",
+        "amount": 2200,
+        "quantity": 15,
+    },
+    {
+        "date": "2025-05-22",
+        "product": "Gadget Y",
+        "region": "East",
+        "amount": 1700,
+        "quantity": 11,
+    },
+    {
+        "date": "2025-06-05",
+        "product": "Widget A",
+        "region": "East",
+        "amount": 1300,
+        "quantity": 10,
+    },
+    {
+        "date": "2025-06-12",
+        "product": "Widget B",
+        "region": "North",
+        "amount": 1050,
+        "quantity": 9,
+    },
+    {
+        "date": "2025-06-19",
+        "product": "Gadget X",
+        "region": "North",
+        "amount": 2600,
+        "quantity": 18,
+    },
+    {
+        "date": "2025-06-26",
+        "product": "Gadget Y",
+        "region": "South",
+        "amount": 1650,
+        "quantity": 11,
+    },
+    {
+        "date": "2025-07-03",
+        "product": "Widget A",
+        "region": "South",
+        "amount": 1450,
+        "quantity": 11,
+    },
+    {
+        "date": "2025-07-10",
+        "product": "Widget B",
+        "region": "West",
+        "amount": 830,
+        "quantity": 7,
+    },
+    {
+        "date": "2025-07-17",
+        "product": "Gadget X",
+        "region": "East",
+        "amount": 2350,
+        "quantity": 16,
+    },
+    {
+        "date": "2025-07-24",
+        "product": "Gadget Y",
+        "region": "West",
+        "amount": 1800,
+        "quantity": 12,
+    },
+    {
+        "date": "2025-08-01",
+        "product": "Widget A",
+        "region": "West",
+        "amount": 1250,
+        "quantity": 10,
+    },
+    {
+        "date": "2025-08-08",
+        "product": "Widget B",
+        "region": "East",
+        "amount": 970,
+        "quantity": 8,
+    },
+    {
+        "date": "2025-08-15",
+        "product": "Gadget X",
+        "region": "South",
+        "amount": 2450,
+        "quantity": 16,
+    },
+    {
+        "date": "2025-08-22",
+        "product": "Gadget Y",
+        "region": "North",
+        "amount": 1950,
+        "quantity": 13,
+    },
+]
+
+REGIONS = ["All", "North", "South", "East", "West"]
+PRODUCTS = ["All", "Widget A", "Widget B", "Gadget X", "Gadget Y"]
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _filter_rows(
+    rows: list[dict],
+    region: str = "All",
+    product: str = "All",
+) -> list[dict]:
+    filtered = rows
+    if region != "All":
+        filtered = [r for r in filtered if r["region"] == region]
+    if product != "All":
+        filtered = [r for r in filtered if r["product"] == product]
+    return filtered
+
+
+def _compute_summary(rows: list[dict]) -> dict:
+    if not rows:
+        return {
+            "count": 0,
+            "total_amount": 0,
+            "avg_amount": 0,
+            "min_amount": 0,
+            "max_amount": 0,
+            "total_quantity": 0,
+        }
+    amounts = [r["amount"] for r in rows]
+    return {
+        "count": len(rows),
+        "total_amount": sum(amounts),
+        "avg_amount": round(sum(amounts) / len(amounts)),
+        "min_amount": min(amounts),
+        "max_amount": max(amounts),
+        "total_quantity": sum(r["quantity"] for r in rows),
+    }
+
+
+def _aggregate_by(rows: list[dict], key: str) -> list[dict]:
+    totals: dict[str, int] = {}
+    for row in rows:
+        label = row[key]
+        totals[label] = totals.get(label, 0) + row["amount"]
+    return [{key: label, "amount": total} for label, total in sorted(totals.items())]
+
+
+# ---------------------------------------------------------------------------
+# App
+# ---------------------------------------------------------------------------
+
+app = FastMCPApp("Data Explorer")
+
+
+@app.tool()
+def analyze_data(region: str = "All", product: str = "All") -> dict:
+    """Filter and analyze sales data. Returns rows, summary, and chart data."""
+    filtered = _filter_rows(SALES_DATA, region, product)
+    return {
+        "rows": filtered,
+        "summary": _compute_summary(filtered),
+        "by_region": _aggregate_by(filtered, "region"),
+        "by_product": _aggregate_by(filtered, "product"),
+    }
+
+
+@app.tool(model=True)
+def get_summary() -> dict:
+    """Return summary statistics for the full dataset."""
+    return _compute_summary(SALES_DATA)
+
+
+@app.tool()
+def filter_data(region: str = "All", product: str = "All") -> list[dict]:
+    """Filter sales data by region and/or product."""
+    return _filter_rows(SALES_DATA, region, product)
+
+
+@app.ui()
+def data_explorer() -> PrefabApp:
+    """Open the data explorer. Browse, filter, and visualize sales data."""
+
+    initial = analyze_data()
+
+    with Column(gap=6, css_class="p-6") as view:
+        Heading("Sales Data Explorer")
+        Muted(f"{len(SALES_DATA)} records loaded")
+
+        Separator()
+
+        # ----- Filters -----
+        with Row(gap=4, align="center"):
+            Text("Filters", css_class="font-semibold")
+
+            with Select(
+                name="selected_region",
+                placeholder="Region",
+                value="All",
+                on_change=[
+                    SetState("loading", True),
+                    CallTool(
+                        analyze_data,
+                        arguments={
+                            "region": STATE.selected_region,
+                            "product": STATE.selected_product,
+                        },
+                        on_success=[
+                            SetState("rows", RESULT.rows),
+                            SetState("summary", RESULT.summary),
+                            SetState("by_region", RESULT.by_region),
+                            SetState("by_product", RESULT.by_product),
+                            SetState("loading", False),
+                            ShowToast("Data updated", variant="success"),
+                        ],
+                        on_error=[
+                            SetState("loading", False),
+                            ShowToast(ERROR, variant="error"),
+                        ],
+                    ),
+                ],
+            ):
+                for region in REGIONS:
+                    SelectOption(value=region, label=region)
+
+            with Select(
+                name="selected_product",
+                placeholder="Product",
+                value="All",
+                on_change=[
+                    SetState("loading", True),
+                    CallTool(
+                        analyze_data,
+                        arguments={
+                            "region": STATE.selected_region,
+                            "product": STATE.selected_product,
+                        },
+                        on_success=[
+                            SetState("rows", RESULT.rows),
+                            SetState("summary", RESULT.summary),
+                            SetState("by_region", RESULT.by_region),
+                            SetState("by_product", RESULT.by_product),
+                            SetState("loading", False),
+                            ShowToast("Data updated", variant="success"),
+                        ],
+                        on_error=[
+                            SetState("loading", False),
+                            ShowToast(ERROR, variant="error"),
+                        ],
+                    ),
+                ],
+            ):
+                for product in PRODUCTS:
+                    SelectOption(value=product, label=product)
+
+            Button(
+                Rx("loading").then("Loading...", "Reset"),
+                disabled=Rx("loading"),
+                on_click=[
+                    SetState("selected_region", "All"),
+                    SetState("selected_product", "All"),
+                    SetState("loading", True),
+                    CallTool(
+                        analyze_data,
+                        arguments={"region": "All", "product": "All"},
+                        on_success=[
+                            SetState("rows", RESULT.rows),
+                            SetState("summary", RESULT.summary),
+                            SetState("by_region", RESULT.by_region),
+                            SetState("by_product", RESULT.by_product),
+                            SetState("loading", False),
+                        ],
+                        on_error=[
+                            SetState("loading", False),
+                            ShowToast(ERROR, variant="error"),
+                        ],
+                    ),
+                ],
+            )
+
+        Separator()
+
+        # ----- Tabs -----
+        with Tabs():
+            # ---- Summary ----
+            with Tab("Summary"):
+                with Grid(columns=3, gap=4):
+                    with Card():
+                        with CardContent():
+                            Metric(
+                                label="Total Revenue",
+                                value=Rx("summary.total_amount"),
+                            )
+                    with Card():
+                        with CardContent():
+                            Metric(
+                                label="Average Sale",
+                                value=Rx("summary.avg_amount"),
+                            )
+                    with Card():
+                        with CardContent():
+                            Metric(
+                                label="Total Quantity",
+                                value=Rx("summary.total_quantity"),
+                            )
+
+                with Grid(columns=3, gap=4, css_class="mt-4"):
+                    with Card():
+                        with CardContent():
+                            Metric(
+                                label="Transactions",
+                                value=Rx("summary.count"),
+                            )
+                    with Card():
+                        with CardContent():
+                            Metric(
+                                label="Min Sale",
+                                value=Rx("summary.min_amount"),
+                            )
+                    with Card():
+                        with CardContent():
+                            Metric(
+                                label="Max Sale",
+                                value=Rx("summary.max_amount"),
+                            )
+
+                with Row(gap=2, css_class="mt-4"):
+                    Badge(f"Region: {STATE.selected_region}")
+                    Badge(f"Product: {STATE.selected_product}")
+
+            # ---- Table ----
+            with Tab("Table"):
+                DataTable(
+                    columns=[
+                        DataTableColumn(key="date", header="Date", sortable=True),
+                        DataTableColumn(key="product", header="Product", sortable=True),
+                        DataTableColumn(key="region", header="Region", sortable=True),
+                        DataTableColumn(
+                            key="amount", header="Amount ($)", sortable=True
+                        ),
+                        DataTableColumn(key="quantity", header="Qty", sortable=True),
+                    ],
+                    rows="{{ rows }}",
+                    search=True,
+                    paginated=True,
+                    page_size=10,
+                )
+
+            # ---- Charts ----
+            with Tab("Charts"):
+                with Grid(columns=2, gap=6):
+                    with Column(gap=2):
+                        Heading("Revenue by Region", level=3)
+                        BarChart(
+                            data=Rx("by_region"),
+                            series=[ChartSeries(data_key="amount", label="Revenue")],
+                            x_axis="region",
+                            show_legend=True,
+                        )
+
+                    with Column(gap=2):
+                        Heading("Revenue by Product", level=3)
+                        BarChart(
+                            data=Rx("by_product"),
+                            series=[ChartSeries(data_key="amount", label="Revenue")],
+                            x_axis="product",
+                            show_legend=True,
+                        )
+
+                Separator(css_class="my-4")
+
+                with Grid(columns=2, gap=6):
+                    with Column(gap=2):
+                        Heading("Region Breakdown", level=3)
+                        PieChart(
+                            data=Rx("by_region"),
+                            data_key="amount",
+                            name_key="region",
+                            show_legend=True,
+                            inner_radius=60,
+                        )
+
+                    with Column(gap=2):
+                        Heading("Product Breakdown", level=3)
+                        PieChart(
+                            data=Rx("by_product"),
+                            data_key="amount",
+                            name_key="product",
+                            show_legend=True,
+                            inner_radius=60,
+                        )
+
+    return PrefabApp(
+        view=view,
+        state={
+            "rows": initial["rows"],
+            "summary": initial["summary"],
+            "by_region": initial["by_region"],
+            "by_product": initial["by_product"],
+            "selected_region": "All",
+            "selected_product": "All",
+            "loading": False,
+        },
+    )
+
+
+mcp = FastMCP("Data Explorer", providers=[app])
+
+if __name__ == "__main__":
+    mcp.run(transport="http")
diff --git a/examples/apps/file_upload/file_upload_server.py b/examples/apps/file_upload/file_upload_server.py
new file mode 100644
index 0000000..c567f78
--- /dev/null
+++ b/examples/apps/file_upload/file_upload_server.py
@@ -0,0 +1,13 @@
+"""File upload — bypass the LLM context window to get files onto the server.
+
+Usage:
+    uv run python file_upload_server.py
+"""
+
+from fastmcp import FastMCP
+from fastmcp.apps.file_upload import FileUpload
+
+mcp = FastMCP("File Upload Server", providers=[FileUpload()])
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/apps/form/form_server.py b/examples/apps/form/form_server.py
new file mode 100644
index 0000000..bfa2ab2
--- /dev/null
+++ b/examples/apps/form/form_server.py
@@ -0,0 +1,41 @@
+"""Form input — collect structured data from users via Pydantic models.
+
+Usage:
+    uv run python form_server.py
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from fastmcp import FastMCP
+from fastmcp.apps.form import FormInput
+
+
+class ShippingAddress(BaseModel):
+    name: str = Field(description="Full name")
+    street: str = Field(description="Street address")
+    city: str
+    state: str = Field(description="Two-letter state code")
+    zip_code: str = Field(description="5-digit ZIP")
+
+
+class BugReport(BaseModel):
+    title: str = Field(description="Brief summary")
+    severity: Literal["low", "medium", "high", "critical"]
+    description: str = Field(
+        description="Detailed description",
+        json_schema_extra={"ui": {"type": "textarea"}},
+    )
+
+
+mcp = FastMCP(
+    "Form Demo",
+    providers=[
+        FormInput(model=ShippingAddress),
+        FormInput(model=BugReport),
+    ],
+)
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/apps/generative_ui.py b/examples/apps/generative_ui.py
new file mode 100644
index 0000000..e03f6ed
--- /dev/null
+++ b/examples/apps/generative_ui.py
@@ -0,0 +1,22 @@
+"""Generative UI — let the LLM build custom Prefab UIs on the fly.
+
+The GenerativeUI provider registers two tools:
+- generate_prefab_ui: the LLM writes Prefab Python code, it runs in a sandbox, the result renders
+- search_prefab_components: the LLM searches the Prefab component library
+
+The generative renderer supports streaming: as the LLM writes code into
+the `code` argument, the host forwards partial arguments to the app via
+ontoolinputpartial, and the user watches the UI build up in real time.
+
+Usage:
+    uv run python generative_ui.py
+"""
+
+from fastmcp import FastMCP
+from fastmcp.apps.generative import GenerativeUI
+
+mcp = FastMCP("Prefab Studio")
+mcp.add_provider(GenerativeUI())
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/apps/greet_server.py b/examples/apps/greet_server.py
new file mode 100644
index 0000000..bb3ad83
--- /dev/null
+++ b/examples/apps/greet_server.py
@@ -0,0 +1,64 @@
+"""Minimal example demonstrating a @app=True tool with arguments.
+
+Usage:
+    uv run python greet_server.py
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from prefab_ui.components import Badge, Column, Heading, Muted
+
+from fastmcp import FastMCP
+
+mcp = FastMCP("Greeter")
+
+GREETINGS: dict[str, str] = {
+    "English": "Hello",
+    "Spanish": "¡Hola",
+    "French": "Bonjour",
+    "Japanese": "こんにちは",
+    "Arabic": "مرحبا",
+}
+
+
+@mcp.tool(app=True)
+def greet(
+    name: str,
+    language: Literal["English", "Spanish", "French", "Japanese", "Arabic"] = "English",
+) -> Column:
+    """Greet someone in their language."""
+    word = GREETINGS[language]
+    with Column(gap=3, css_class="p-8") as view:
+        Heading(f"{word}, {name}!")
+        Muted("Greeting rendered by FastMCP")
+        Badge(language)
+    return view
+
+
+FAREWELLS: dict[str, str] = {
+    "English": "Goodbye",
+    "Spanish": "Adiós",
+    "French": "Au revoir",
+    "Japanese": "さようなら",
+    "Arabic": "مع السلامة",
+}
+
+
+@mcp.tool(app=True)
+def farewell(
+    name: str,
+    language: Literal["English", "Spanish", "French", "Japanese", "Arabic"] = "English",
+) -> Column:
+    """Say farewell in their language."""
+    word = FAREWELLS[language]
+    with Column(gap=3, css_class="p-8") as view:
+        Heading(f"{word}, {name}!")
+        Muted("Farewell rendered by FastMCP")
+        Badge(language)
+    return view
+
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/apps/inspector_demo.py b/examples/apps/inspector_demo.py
new file mode 100644
index 0000000..2d5d244
--- /dev/null
+++ b/examples/apps/inspector_demo.py
@@ -0,0 +1,120 @@
+"""Demo server for testing the dev apps MCP message inspector.
+
+Exercises tool calls, server notifications (ctx.log), and errors
+so you can verify all message types appear in the inspector panel.
+
+Usage:
+    fastmcp dev apps examples/apps/inspector_demo.py
+"""
+
+from __future__ import annotations
+
+from prefab_ui.actions import ShowToast
+from prefab_ui.actions.mcp import CallTool, SendMessage, UpdateContext
+from prefab_ui.components import (
+    Badge,
+    Button,
+    Column,
+    Heading,
+    Muted,
+    Row,
+)
+from prefab_ui.rx import ERROR
+
+from fastmcp import FastMCP
+from fastmcp.server.context import Context
+
+mcp = FastMCP("Inspector Demo")
+
+
+@mcp.tool(app=True)
+def demo() -> Column:
+    """A demo app that exercises various MCP message types."""
+    with Column(gap=6, css_class="p-8 max-w-lg") as view:
+        Heading("Inspector Demo")
+        Muted("Click the buttons and watch the inspector panel on the right.")
+
+        with Column(gap=3):
+            with Row(gap=2, align="center"):
+                Button(
+                    "Call Tool",
+                    variant="default",
+                    on_click=CallTool(
+                        "echo",
+                        arguments={"message": "Hello from the inspector!"},
+                        on_success=ShowToast("Tool call succeeded", variant="success"),
+                        on_error=ShowToast(ERROR, variant="error"),
+                    ),
+                )
+                Badge("tools/call + response", variant="secondary")
+
+            with Row(gap=2, align="center"):
+                Button(
+                    "Call with Logging",
+                    variant="default",
+                    on_click=CallTool(
+                        "echo_with_logs",
+                        arguments={"message": "Watch the notifications!"},
+                        on_success=ShowToast("Done (check logs)", variant="success"),
+                        on_error=ShowToast(ERROR, variant="error"),
+                    ),
+                )
+                Badge("tools/call + notifications", variant="secondary")
+
+            with Row(gap=2, align="center"):
+                Button(
+                    "Trigger Error",
+                    variant="destructive",
+                    on_click=CallTool(
+                        "fail",
+                        arguments={},
+                        on_error=ShowToast(ERROR, variant="error"),
+                    ),
+                )
+                Badge("error response", variant="destructive")
+
+            with Row(gap=2, align="center"):
+                Button(
+                    "Update Context",
+                    variant="outline",
+                    on_click=[
+                        UpdateContext(content="Demo context from inspector"),
+                        ShowToast("Context updated", variant="success"),
+                    ],
+                )
+                Badge("bridge: UpdateContext", variant="outline")
+
+            with Row(gap=2, align="center"):
+                Button(
+                    "Send Message",
+                    variant="outline",
+                    on_click=SendMessage("Tell me about this demo app"),
+                )
+                Badge("bridge: SendMessage", variant="outline")
+
+    return view
+
+
+@mcp.tool()
+def echo(message: str) -> str:
+    """Echo a message back."""
+    return f"Echo: {message}"
+
+
+@mcp.tool()
+async def echo_with_logs(message: str, ctx: Context) -> str:
+    """Echo a message and emit log notifications."""
+    await ctx.log(f"Processing: {message}", level="info")
+    await ctx.log("Step 1: validated input", level="debug")
+    await ctx.log("Step 2: generating response", level="debug")
+    return f"Logged echo: {message}"
+
+
+@mcp.tool()
+def fail() -> str:
+    """Always raises an error."""
+    raise ValueError("This is a deliberate error for testing the inspector")
+
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/apps/inventory/inventory_server.py b/examples/apps/inventory/inventory_server.py
new file mode 100644
index 0000000..f008620
--- /dev/null
+++ b/examples/apps/inventory/inventory_server.py
@@ -0,0 +1,445 @@
+"""Inventory tracker -- a FastMCPApp example with CRUD operations and rich UI.
+
+Demonstrates the full FastMCPApp stack:
+- @app.ui() entry point that the model calls to open the app
+- @app.tool() backend tools for add, update, delete, and search
+- DataTable with sortable columns and built-in search
+- Form.from_model() for auto-generated Pydantic model forms
+- Tabs, Select filtering, ForEach results, and Toast notifications
+- State management with PrefabApp state dict and Rx()
+
+Usage:
+    uv run python inventory_server.py               # HTTP (default)
+    uv run python inventory_server.py --stdio        # stdio for MCP clients
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from prefab_ui.actions import SetState, ShowToast
+from prefab_ui.actions.mcp import CallTool
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import (
+    Badge,
+    Button,
+    Card,
+    CardContent,
+    Column,
+    DataTable,
+    DataTableColumn,
+    ForEach,
+    Form,
+    Grid,
+    Heading,
+    Input,
+    Muted,
+    Row,
+    Select,
+    SelectOption,
+    Separator,
+    Tab,
+    Tabs,
+    Text,
+)
+from prefab_ui.rx import ERROR, RESULT, STATE, Rx
+from pydantic import BaseModel, Field
+
+from fastmcp import FastMCP, FastMCPApp
+
+# ---------------------------------------------------------------------------
+# Data store
+# ---------------------------------------------------------------------------
+
+_next_id = 11
+
+_inventory: list[dict] = [
+    {
+        "id": 1,
+        "name": "Wireless Mouse",
+        "category": "Electronics",
+        "quantity": 45,
+        "price": 29.99,
+        "last_updated": "2026-03-20",
+    },
+    {
+        "id": 2,
+        "name": "Mechanical Keyboard",
+        "category": "Electronics",
+        "quantity": 32,
+        "price": 89.99,
+        "last_updated": "2026-03-19",
+    },
+    {
+        "id": 3,
+        "name": "USB-C Hub",
+        "category": "Electronics",
+        "quantity": 18,
+        "price": 49.99,
+        "last_updated": "2026-03-18",
+    },
+    {
+        "id": 4,
+        "name": "A4 Copy Paper (500 sheets)",
+        "category": "Office Supplies",
+        "quantity": 200,
+        "price": 8.50,
+        "last_updated": "2026-03-21",
+    },
+    {
+        "id": 5,
+        "name": "Ballpoint Pens (box)",
+        "category": "Office Supplies",
+        "quantity": 150,
+        "price": 12.00,
+        "last_updated": "2026-03-20",
+    },
+    {
+        "id": 6,
+        "name": "Sticky Notes (pack)",
+        "category": "Office Supplies",
+        "quantity": 85,
+        "price": 5.99,
+        "last_updated": "2026-03-17",
+    },
+    {
+        "id": 7,
+        "name": "Standing Desk",
+        "category": "Furniture",
+        "quantity": 8,
+        "price": 499.00,
+        "last_updated": "2026-03-15",
+    },
+    {
+        "id": 8,
+        "name": "Ergonomic Chair",
+        "category": "Furniture",
+        "quantity": 12,
+        "price": 349.00,
+        "last_updated": "2026-03-16",
+    },
+    {
+        "id": 9,
+        "name": "Monitor Arm",
+        "category": "Furniture",
+        "quantity": 25,
+        "price": 79.99,
+        "last_updated": "2026-03-22",
+    },
+    {
+        "id": 10,
+        "name": "Webcam HD",
+        "category": "Electronics",
+        "quantity": 60,
+        "price": 69.99,
+        "last_updated": "2026-03-21",
+    },
+]
+
+CATEGORIES = ["All", "Electronics", "Office Supplies", "Furniture"]
+
+
+# ---------------------------------------------------------------------------
+# Pydantic model for add-item form
+# ---------------------------------------------------------------------------
+
+
+class NewItem(BaseModel):
+    name: str = Field(title="Item Name", min_length=1)
+    category: Literal["Electronics", "Office Supplies", "Furniture"] = Field(
+        title="Category",
+        default="Electronics",
+    )
+    quantity: int = Field(title="Quantity", ge=0, default=1)
+    price: float = Field(title="Unit Price ($)", ge=0.0, default=0.0)
+
+
+# ---------------------------------------------------------------------------
+# App and tools
+# ---------------------------------------------------------------------------
+
+app = FastMCPApp("Inventory")
+
+
+@app.tool()
+def add_item(data: NewItem) -> list[dict]:
+    """Add a new item to inventory and return the full list."""
+    global _next_id
+    item = {
+        "id": _next_id,
+        "name": data.name,
+        "category": data.category,
+        "quantity": data.quantity,
+        "price": data.price,
+        "last_updated": datetime.now().strftime("%Y-%m-%d"),
+    }
+    _next_id += 1
+    _inventory.append(item)
+    return list(_inventory)
+
+
+@app.tool()
+def update_quantity(item_id: int, delta: int) -> list[dict]:
+    """Adjust an item's quantity by delta (+/-) and return the full list."""
+    for item in _inventory:
+        if item["id"] == item_id:
+            new_qty = max(0, item["quantity"] + delta)
+            item["quantity"] = new_qty
+            item["last_updated"] = datetime.now().strftime("%Y-%m-%d")
+            break
+    return list(_inventory)
+
+
+@app.tool()
+def delete_item(item_id: int) -> list[dict]:
+    """Remove an item by ID and return the remaining inventory."""
+    for i, item in enumerate(_inventory):
+        if item["id"] == item_id:
+            _inventory.pop(i)
+            break
+    return list(_inventory)
+
+
+@app.tool()
+def search_items(query: str) -> list[dict]:
+    """Search items by name (case-insensitive). Returns matching items."""
+    q = query.lower()
+    return [item for item in _inventory if q in item["name"].lower()]
+
+
+@app.tool()
+def filter_by_category(category: str) -> list[dict]:
+    """Filter inventory by category. Pass 'All' to show everything."""
+    if category == "All":
+        return list(_inventory)
+    return [item for item in _inventory if item["category"] == category]
+
+
+# ---------------------------------------------------------------------------
+# UI helpers
+# ---------------------------------------------------------------------------
+
+
+def _build_inventory_table() -> None:
+    """Render the main DataTable with all current items."""
+    DataTable(
+        columns=[
+            DataTableColumn(key="name", header="Name", sortable=True),
+            DataTableColumn(key="category", header="Category", sortable=True),
+            DataTableColumn(key="quantity", header="Qty", sortable=True),
+            DataTableColumn(key="price", header="Price ($)", sortable=True),
+            DataTableColumn(key="last_updated", header="Updated", sortable=True),
+        ],
+        rows=list(_inventory),
+        search=True,
+        paginated=True,
+        page_size=10,
+    )
+
+
+def _build_search_section() -> None:
+    """Render the search form with ForEach results."""
+    Heading("Search Items", level=3)
+    Muted("Search by name across all inventory items.")
+
+    with Form(
+        on_submit=CallTool(
+            search_items,
+            arguments={"query": STATE.query},
+            on_success=SetState("search_results", RESULT),
+        )
+    ):
+        Input(name="query", placeholder="Search by name...")
+        Button("Search")
+
+    with ForEach("search_results") as result:
+        with Card(css_class="mb-2"):
+            with CardContent():
+                with Row(gap=3, align="center"):
+                    Text(result.name, css_class="font-medium")
+                    Badge(result.category)
+                    Text(result.quantity)
+                    Muted("in stock")
+
+
+def _build_add_form() -> None:
+    """Render the add-item form using Form.from_model()."""
+    Heading("Add New Item", level=3)
+    Muted("Fill out the form below to add a new item to inventory.")
+
+    Form.from_model(
+        NewItem,
+        submit_label="Add Item",
+        on_submit=CallTool(
+            add_item,
+            on_success=[
+                SetState("recent_additions", RESULT),
+                ShowToast("Item added!", variant="success"),
+            ],
+            on_error=ShowToast(ERROR, variant="error"),
+        ),
+    )
+
+
+def _build_actions_section() -> None:
+    """Render category filter, quantity adjustment, and delete controls."""
+
+    # Category filter
+    Heading("Filter by Category", level=3)
+    Muted("Select a category to see matching items.")
+
+    with Form(
+        on_submit=CallTool(
+            filter_by_category,
+            arguments={"category": STATE.selected_category},
+            on_success=SetState("filtered_items", RESULT),
+        )
+    ):
+        with Select(name="selected_category", placeholder="Choose a category..."):
+            for cat in CATEGORIES:
+                SelectOption(cat, value=cat)
+        Button("Apply Filter")
+
+    with ForEach("filtered_items") as item:
+        with Row(gap=3, align="center", css_class="py-1"):
+            Badge(item.id, variant="outline")
+            Text(item.name, css_class="font-medium")
+            Badge(item.category)
+            Muted(item.quantity)
+
+    Separator()
+
+    # Quantity adjustment
+    Heading("Adjust Quantity", level=3)
+    Muted("Enter an item ID and use the buttons to adjust stock levels.")
+
+    Input(name="adjust_id", input_type="number", placeholder="Item ID (e.g. 1)")
+
+    with Row(gap=2):
+        Button(
+            "- 1",
+            variant="outline",
+            on_click=CallTool(
+                update_quantity,
+                arguments={"item_id": STATE.adjust_id, "delta": -1},
+                on_success=[
+                    SetState("filtered_items", RESULT),
+                    ShowToast("Quantity decreased", variant="default"),
+                ],
+                on_error=ShowToast(ERROR, variant="error"),
+            ),
+        )
+        Button(
+            "+ 1",
+            variant="outline",
+            on_click=CallTool(
+                update_quantity,
+                arguments={"item_id": STATE.adjust_id, "delta": 1},
+                on_success=[
+                    SetState("filtered_items", RESULT),
+                    ShowToast("Quantity increased", variant="default"),
+                ],
+                on_error=ShowToast(ERROR, variant="error"),
+            ),
+        )
+        Button(
+            "+ 10",
+            on_click=CallTool(
+                update_quantity,
+                arguments={"item_id": STATE.adjust_id, "delta": 10},
+                on_success=[
+                    SetState("filtered_items", RESULT),
+                    ShowToast("Restocked +10", variant="success"),
+                ],
+                on_error=ShowToast(ERROR, variant="error"),
+            ),
+        )
+
+    Separator()
+
+    # Delete
+    Heading("Delete Item", level=3)
+    Muted("Permanently remove an item by its ID.")
+
+    with Form(
+        on_submit=CallTool(
+            delete_item,
+            arguments={"item_id": STATE.delete_id},
+            on_success=[
+                SetState("filtered_items", RESULT),
+                ShowToast("Item deleted", variant="warning"),
+            ],
+            on_error=ShowToast(ERROR, variant="error"),
+        )
+    ):
+        Input(name="delete_id", input_type="number", placeholder="Item ID to delete")
+        Button("Delete", variant="destructive")
+
+
+# ---------------------------------------------------------------------------
+# Entry point UI
+# ---------------------------------------------------------------------------
+
+
+@app.ui()
+def inventory_manager() -> PrefabApp:
+    """Open the inventory manager. The model calls this to launch the app."""
+    with Column(gap=6, css_class="p-6") as view:
+        with Row(gap=3, align="center"):
+            Heading("Inventory Tracker")
+            Badge(
+                Rx("filtered_items.length"),
+                variant="secondary",
+            )
+            Muted("items tracked")
+
+        Separator()
+
+        # Summary cards per category
+        with Grid(columns=3, gap=4):
+            for cat in ["Electronics", "Office Supplies", "Furniture"]:
+                count = sum(1 for it in _inventory if it["category"] == cat)
+                total_qty = sum(
+                    it["quantity"] for it in _inventory if it["category"] == cat
+                )
+                with Card():
+                    with CardContent():
+                        Text(cat, css_class="font-medium")
+                        Muted(f"{count} items, {total_qty} units")
+
+        with Tabs():
+            with Tab("All Items"):
+                _build_inventory_table()
+
+            with Tab("Search"):
+                _build_search_section()
+
+            with Tab("Add Item"):
+                _build_add_form()
+
+            with Tab("Actions"):
+                _build_actions_section()
+
+    return PrefabApp(
+        view=view,
+        state={
+            "search_results": [],
+            "filtered_items": list(_inventory),
+            "recent_additions": [],
+            "selected_category": "All",
+            "adjust_id": "",
+            "delete_id": "",
+            "query": "",
+        },
+    )
+
+
+# ---------------------------------------------------------------------------
+# Server
+# ---------------------------------------------------------------------------
+
+mcp = FastMCP("Inventory Server", providers=[app])
+
+if __name__ == "__main__":
+    mcp.run(transport="http")
diff --git a/examples/apps/map/map_server.py b/examples/apps/map/map_server.py
new file mode 100644
index 0000000..5bc868a
--- /dev/null
+++ b/examples/apps/map/map_server.py
@@ -0,0 +1,164 @@
+"""Interactive Map — geocode addresses and render on an interactive map.
+
+Accepts plain addresses (or place names), geocodes them via
+OpenStreetMap Nominatim, and renders an interactive Leaflet map.
+
+Usage:
+    fastmcp dev apps map_server.py
+"""
+
+from __future__ import annotations
+
+from textwrap import dedent
+
+import httpx
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import (
+    Badge,
+    Card,
+    Column,
+    Embed,
+    Heading,
+    Muted,
+)
+from prefab_ui.components.data_table import DataTable, DataTableColumn
+
+from fastmcp import FastMCP
+
+mcp = FastMCP("Interactive Map")
+
+NOMINATIM_URL = "https://nominatim.openstreetmap.org/search"
+
+
+def _geocode(query: str) -> dict | None:
+    """Geocode an address using OpenStreetMap Nominatim (free, no key)."""
+    resp = httpx.get(
+        NOMINATIM_URL,
+        params={"q": query, "format": "json", "limit": 1},
+        headers={"User-Agent": "fastmcp-map-example/1.0"},
+        timeout=10,
+    )
+    results = resp.json()
+    if results:
+        r = results[0]
+        return {
+            "name": r.get("display_name", query).split(",")[0],
+            "address": query,
+            "lat": float(r["lat"]),
+            "lng": float(r["lon"]),
+        }
+    return None
+
+
+def _build_map_html(
+    locations: list[dict],
+    zoom: int,
+) -> str:
+    markers_js = ""
+    for loc in locations:
+        name = str(loc["name"]).replace("\\", "\\\\").replace("'", "\\'")
+        markers_js += (
+            f"L.marker([{loc['lat']}, {loc['lng']}]).addTo(map).bindPopup('{name}');\n"
+        )
+
+    avg_lat = sum(loc["lat"] for loc in locations) / len(locations)
+    avg_lng = sum(loc["lng"] for loc in locations) / len(locations)
+
+    return dedent(f"""\
+        <!DOCTYPE html>
+        <html>
+        <head>
+            <meta charset="utf-8" />
+            <link
+                rel="stylesheet"
+                href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"
+            />
+            <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
+            <style>
+                body {{ margin: 0; }}
+                #map {{ width: 100%; height: 100vh; }}
+            </style>
+        </head>
+        <body>
+            <div id="map"></div>
+            <script>
+                var map = L.map('map').setView([{avg_lat}, {avg_lng}], {zoom});
+                L.tileLayer('https://{{s}}.tile.openstreetmap.org/{{z}}/{{x}}/{{y}}.png', {{
+                    attribution: '&copy; OpenStreetMap contributors'
+                }}).addTo(map);
+                {markers_js}
+            </script>
+        </body>
+        </html>
+    """)
+
+
+@mcp.tool(app=True)
+def show_map(
+    locations: list[str] | None = None,
+    title: str = "Map",
+    zoom: int = 2,
+) -> PrefabApp:
+    """Show locations on an interactive map.
+
+    Accepts addresses, place names, or landmarks. Each location is
+    geocoded via OpenStreetMap and displayed as a marker on an
+    interactive Leaflet map.
+
+    Args:
+        locations: List of addresses or place names. Defaults to
+            sample US landmarks if not provided.
+        title: Heading for the map.
+        zoom: Initial zoom level (1-18, higher = closer).
+    """
+    if not locations:
+        locations = [
+            "Statue of Liberty, New York",
+            "Golden Gate Bridge, San Francisco",
+            "Space Needle, Seattle",
+            "Willis Tower, Chicago",
+            "Gateway Arch, St. Louis",
+        ]
+
+    geocoded = []
+    failed = []
+    for loc in locations:
+        result = _geocode(loc)
+        if result:
+            geocoded.append(result)
+        else:
+            failed.append(loc)
+
+    with PrefabApp() as app:
+        with Column(gap=4, css_class="p-6"):
+            Heading(title)
+            Muted(f"{len(geocoded)} locations mapped")
+            if failed:
+                for f in failed:
+                    Badge(f"Could not find: {f}", variant="destructive")
+
+            if geocoded:
+                map_html = _build_map_html(geocoded, zoom)
+                with Card():
+                    Embed(
+                        html=map_html,
+                        width="100%",
+                        height="500px",
+                        sandbox="allow-scripts",
+                    )
+                DataTable(
+                    columns=[
+                        DataTableColumn(key="name", header="Name", sortable=True),
+                        DataTableColumn(key="address", header="Address", sortable=True),
+                        DataTableColumn(key="lat", header="Latitude", sortable=True),
+                        DataTableColumn(key="lng", header="Longitude", sortable=True),
+                    ],
+                    rows=geocoded,
+                    search=True,
+                )
+
+    return app
+
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/apps/patterns_server.py b/examples/apps/patterns_server.py
new file mode 100644
index 0000000..abf888c
--- /dev/null
+++ b/examples/apps/patterns_server.py
@@ -0,0 +1,487 @@
+"""Patterns showcase — every Prefab pattern from the docs in one server.
+
+A runnable collection of the patterns from https://gofastmcp.com/apps/patterns.
+Each tool demonstrates a different Prefab UI pattern: charts, tables, forms,
+status displays, conditional content, tabs, and accordions.
+
+Usage:
+    uv run python patterns_server.py              # HTTP (port 8000)
+    uv run python patterns_server.py --stdio       # stdio for MCP clients
+"""
+
+from __future__ import annotations
+
+from prefab_ui.actions import ShowToast
+from prefab_ui.actions.mcp import CallTool
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import (
+    Accordion,
+    AccordionItem,
+    Alert,
+    Badge,
+    Button,
+    Card,
+    CardContent,
+    Column,
+    DataTable,
+    DataTableColumn,
+    ForEach,
+    Form,
+    Grid,
+    Heading,
+    If,
+    Input,
+    Muted,
+    Progress,
+    Row,
+    Select,
+    Separator,
+    Switch,
+    Tab,
+    Tabs,
+    Text,
+    Textarea,
+)
+from prefab_ui.components.charts import AreaChart, BarChart, ChartSeries, PieChart
+from prefab_ui.rx import ERROR, Rx
+
+from fastmcp import FastMCP
+
+mcp = FastMCP("Patterns Showcase")
+
+
+# ---------------------------------------------------------------------------
+# Data
+# ---------------------------------------------------------------------------
+
+QUARTERLY_DATA = [
+    {"quarter": "Q1", "revenue": 42000, "costs": 28000},
+    {"quarter": "Q2", "revenue": 51000, "costs": 31000},
+    {"quarter": "Q3", "revenue": 47000, "costs": 29000},
+    {"quarter": "Q4", "revenue": 63000, "costs": 35000},
+]
+
+DAILY_USAGE = [
+    {"date": f"Feb {d}", "requests": v}
+    for d, v in zip(
+        range(1, 11),
+        [1200, 1350, 980, 1500, 1420, 1680, 1550, 1700, 1450, 1600],
+    )
+]
+
+TICKETS = [
+    {"category": "Bug", "count": 23},
+    {"category": "Feature", "count": 15},
+    {"category": "Docs", "count": 8},
+    {"category": "Infra", "count": 12},
+]
+
+EMPLOYEES = [
+    {
+        "name": "Alice Chen",
+        "department": "Engineering",
+        "role": "Staff Engineer",
+        "location": "San Francisco",
+    },
+    {
+        "name": "Bob Martinez",
+        "department": "Design",
+        "role": "Lead Designer",
+        "location": "New York",
+    },
+    {
+        "name": "Carol Johnson",
+        "department": "Engineering",
+        "role": "Senior Engineer",
+        "location": "London",
+    },
+    {
+        "name": "David Kim",
+        "department": "Product",
+        "role": "Product Manager",
+        "location": "San Francisco",
+    },
+    {
+        "name": "Eva Müller",
+        "department": "Engineering",
+        "role": "Engineer",
+        "location": "Berlin",
+    },
+    {
+        "name": "Frank Okafor",
+        "department": "Data Science",
+        "role": "Senior Analyst",
+        "location": "Lagos",
+    },
+    {
+        "name": "Grace Liu",
+        "department": "Engineering",
+        "role": "Junior Engineer",
+        "location": "Singapore",
+    },
+    {
+        "name": "Hassan Ali",
+        "department": "Design",
+        "role": "Senior Designer",
+        "location": "Dubai",
+    },
+]
+
+SERVICES = [
+    {
+        "name": "API Gateway",
+        "status": "healthy",
+        "ok": True,
+        "latency_ms": 12,
+        "uptime_pct": 99.9,
+    },
+    {
+        "name": "Database",
+        "status": "healthy",
+        "ok": True,
+        "latency_ms": 3,
+        "uptime_pct": 99.99,
+    },
+    {
+        "name": "Cache",
+        "status": "degraded",
+        "ok": False,
+        "latency_ms": 45,
+        "uptime_pct": 98.2,
+    },
+    {
+        "name": "Queue",
+        "status": "healthy",
+        "ok": True,
+        "latency_ms": 8,
+        "uptime_pct": 99.8,
+    },
+]
+
+ENDPOINTS = [
+    {
+        "path": "/api/users",
+        "status": 200,
+        "healthy": True,
+        "avg_ms": 45,
+        "p99_ms": 120,
+        "uptime_pct": 99.9,
+    },
+    {
+        "path": "/api/orders",
+        "status": 200,
+        "healthy": True,
+        "avg_ms": 82,
+        "p99_ms": 250,
+        "uptime_pct": 99.7,
+    },
+    {
+        "path": "/api/search",
+        "status": 200,
+        "healthy": True,
+        "avg_ms": 150,
+        "p99_ms": 500,
+        "uptime_pct": 99.5,
+    },
+    {
+        "path": "/api/webhooks",
+        "status": 503,
+        "healthy": False,
+        "avg_ms": 2000,
+        "p99_ms": 5000,
+        "uptime_pct": 95.1,
+    },
+]
+
+PROJECT = {
+    "name": "FastMCP v3",
+    "description": "Next generation MCP framework with Apps support.",
+    "status": "Active",
+    "created_at": "2025-01-15",
+    "members": [
+        {"name": "Alice Chen", "role": "Lead"},
+        {"name": "Bob Martinez", "role": "Design"},
+        {"name": "Carol Johnson", "role": "Backend"},
+    ],
+    "activity": [
+        {
+            "timestamp": "2 hours ago",
+            "message": "Merged PR #342: Add Prefab UI integration",
+        },
+        {
+            "timestamp": "5 hours ago",
+            "message": "Opened issue #345: CORS convenience API",
+        },
+        {"timestamp": "1 day ago", "message": "Released v3.0.1"},
+    ],
+}
+
+# In-memory contact store for the form demo
+_contacts: list[dict] = [
+    {"name": "Zaphod Beeblebrox", "email": "zaphod@galaxy.gov", "category": "Partner"},
+]
+
+
+# ---------------------------------------------------------------------------
+# Charts
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool(app=True)
+def quarterly_revenue(year: int = 2025) -> PrefabApp:
+    """Show quarterly revenue as a bar chart."""
+    with Column(gap=4, css_class="p-6") as view:
+        Heading(f"{year} Revenue vs Costs")
+        BarChart(
+            data=QUARTERLY_DATA,
+            series=[
+                ChartSeries(data_key="revenue", label="Revenue"),
+                ChartSeries(data_key="costs", label="Costs"),
+            ],
+            x_axis="quarter",
+            show_legend=True,
+        )
+
+    return PrefabApp(view=view)
+
+
+@mcp.tool(app=True)
+def usage_trend() -> PrefabApp:
+    """Show API usage over time as an area chart."""
+    with Column(gap=4, css_class="p-6") as view:
+        Heading("API Usage (10 Days)")
+        AreaChart(
+            data=DAILY_USAGE,
+            series=[ChartSeries(data_key="requests", label="Requests")],
+            x_axis="date",
+            curve="smooth",
+            height=250,
+        )
+
+    return PrefabApp(view=view)
+
+
+@mcp.tool(app=True)
+def ticket_breakdown() -> PrefabApp:
+    """Show open tickets by category as a donut chart."""
+    with Column(gap=4, css_class="p-6") as view:
+        Heading("Open Tickets")
+        PieChart(
+            data=TICKETS,
+            data_key="count",
+            name_key="category",
+            show_legend=True,
+            inner_radius=60,
+        )
+
+    return PrefabApp(view=view)
+
+
+# ---------------------------------------------------------------------------
+# Data Tables
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool(app=True)
+def employee_directory() -> PrefabApp:
+    """Show a searchable, sortable employee directory."""
+    with Column(gap=4, css_class="p-6") as view:
+        Heading("Employee Directory")
+        DataTable(
+            columns=[
+                DataTableColumn(key="name", header="Name", sortable=True),
+                DataTableColumn(key="department", header="Department", sortable=True),
+                DataTableColumn(key="role", header="Role"),
+                DataTableColumn(key="location", header="Office", sortable=True),
+            ],
+            rows=EMPLOYEES,
+            search=True,
+            paginated=True,
+            page_size=15,
+        )
+
+    return PrefabApp(view=view)
+
+
+# ---------------------------------------------------------------------------
+# Forms
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool(app=True)
+def contact_form() -> PrefabApp:
+    """Show a form to create a new contact, with a live contact list below."""
+    with Column(gap=6, css_class="p-6") as view:
+        Heading("Contacts")
+
+        with ForEach("contacts") as item:
+            with Row(gap=2, align="center"):
+                Text(item.name, css_class="font-medium")
+                Muted(item.email)
+                Badge(item.category)
+
+        Separator()
+
+        Heading("Add Contact", level=3)
+        with Form(
+            on_submit=CallTool(
+                "save_contact",
+                result_key="contacts",
+                on_success=ShowToast("Contact saved!", variant="success"),
+                on_error=ShowToast(ERROR, variant="error"),
+            )
+        ):
+            Input(name="name", label="Full Name", required=True)
+            Input(name="email", label="Email", input_type="email", required=True)
+            Select(
+                name="category",
+                label="Category",
+                options=["Customer", "Vendor", "Partner", "Other"],
+            )
+            Textarea(name="notes", label="Notes", placeholder="Optional notes...")
+            Button("Save Contact")
+
+    return PrefabApp(view=view, state={"contacts": list(_contacts)})
+
+
+@mcp.tool
+def save_contact(
+    name: str,
+    email: str,
+    category: str = "Other",
+    notes: str = "",
+) -> list[dict]:
+    """Save a new contact and return the updated list."""
+    contact = {"name": name, "email": email, "category": category, "notes": notes}
+    _contacts.append(contact)
+    return list(_contacts)
+
+
+# ---------------------------------------------------------------------------
+# Status Displays
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool(app=True)
+def system_status() -> PrefabApp:
+    """Show current system health."""
+    all_ok = all(s["ok"] for s in SERVICES)
+
+    with Column(gap=4, css_class="p-6") as view:
+        with Row(gap=2, align="center"):
+            Heading("System Status")
+            Badge(
+                "All Healthy" if all_ok else "Degraded",
+                variant="success" if all_ok else "destructive",
+            )
+
+        Separator()
+
+        with Grid(columns=2, gap=4):
+            for svc in SERVICES:
+                with Card():
+                    with CardContent():
+                        with Row(gap=2, align="center"):
+                            Text(svc["name"], css_class="font-medium")
+                            Badge(
+                                svc["status"],
+                                variant="success" if svc["ok"] else "destructive",
+                            )
+                        Muted(f"Response: {svc['latency_ms']}ms")
+                        Progress(value=svc["uptime_pct"])
+
+    return PrefabApp(view=view)
+
+
+# ---------------------------------------------------------------------------
+# Conditional Content
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool(app=True)
+def feature_flags() -> PrefabApp:
+    """Toggle feature flags with live preview."""
+    with Column(gap=4, css_class="p-6") as view:
+        Heading("Feature Flags")
+
+        Switch(name="dark_mode", label="Dark Mode")
+        Switch(name="beta_features", label="Beta Features")
+
+        Separator()
+
+        with If(Rx("dark_mode")):
+            Alert(title="Dark mode enabled", description="UI will use dark theme.")
+        with If(Rx("beta_features")):
+            Alert(
+                title="Beta features active",
+                description="Experimental features are now visible.",
+                variant="warning",
+            )
+
+    return PrefabApp(view=view, state={"dark_mode": False, "beta_features": False})
+
+
+# ---------------------------------------------------------------------------
+# Tabs
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool(app=True)
+def project_overview() -> PrefabApp:
+    """Show project details organized in tabs."""
+    with Column(gap=4, css_class="p-6") as view:
+        Heading(PROJECT["name"])
+
+        with Tabs():
+            with Tab("Overview"):
+                Text(PROJECT["description"])
+                with Row(gap=4):
+                    Badge(PROJECT["status"])
+                    Muted(f"Created: {PROJECT['created_at']}")
+
+            with Tab("Members"):
+                DataTable(
+                    columns=[
+                        DataTableColumn(key="name", header="Name", sortable=True),
+                        DataTableColumn(key="role", header="Role"),
+                    ],
+                    rows=PROJECT["members"],
+                )
+
+            with Tab("Activity"):
+                with ForEach("activity") as item:
+                    with Row(gap=2):
+                        Muted(item.timestamp)
+                        Text(item.message)
+
+    return PrefabApp(view=view, state={"activity": PROJECT["activity"]})
+
+
+# ---------------------------------------------------------------------------
+# Accordion
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool(app=True)
+def api_health() -> PrefabApp:
+    """Show health details for each API endpoint."""
+    with Column(gap=4, css_class="p-6") as view:
+        Heading("API Health")
+
+        with Accordion(multiple=True):
+            for ep in ENDPOINTS:
+                with AccordionItem(ep["path"]):
+                    with Row(gap=4):
+                        Badge(
+                            f"{ep['status']}",
+                            variant="success" if ep["healthy"] else "destructive",
+                        )
+                        Text(f"Avg: {ep['avg_ms']}ms")
+                        Text(f"P99: {ep['p99_ms']}ms")
+                    Progress(value=ep["uptime_pct"])
+
+    return PrefabApp(view=view)
+
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/apps/qr_server/README.md b/examples/apps/qr_server/README.md
new file mode 100644
index 0000000..2cfe806
--- /dev/null
+++ b/examples/apps/qr_server/README.md
@@ -0,0 +1,35 @@
+# QR Code MCP App
+
+An MCP App server that generates QR codes with an interactive viewer UI. Ported from the [ext-apps QR server example](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/qr-server) to demonstrate FastMCP's MCP Apps support.
+
+## What it demonstrates
+
+- Linking a tool to a `ui://` resource via `AppConfig`
+- Serving embedded HTML with the `@modelcontextprotocol/ext-apps` JS SDK from CDN
+- Declaring CSP resource domains via `ResourceCSP`
+- Returning `ImageContent` (base64 PNG) from a tool
+
+## Setup
+
+```bash
+cd examples/apps/qr_server
+uv sync
+```
+
+## Usage
+
+```bash
+uv run python qr_server.py
+```
+
+Or install it into an MCP client:
+
+```bash
+fastmcp install stdio fastmcp.json
+```
+
+## How it works
+
+The server registers one tool (`generate_qr`) and one resource (`ui://qr-server/view.html`). The tool generates a QR code as a base64 PNG image. The resource serves an HTML page that uses the MCP Apps JS SDK to receive the tool result and display the image in a sandboxed iframe.
+
+The HTML loads the ext-apps SDK from unpkg, so the resource declares `csp=ResourceCSP(resource_domains=["https://unpkg.com"])` to allow the host to set the appropriate Content-Security-Policy.
diff --git a/examples/apps/qr_server/fastmcp.json b/examples/apps/qr_server/fastmcp.json
new file mode 100644
index 0000000..7e74faa
--- /dev/null
+++ b/examples/apps/qr_server/fastmcp.json
@@ -0,0 +1,13 @@
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "qr_server.py"
+  },
+  "environment": {
+    "dependencies": [
+      "fastmcp",
+      "qrcode[pil]>=8.0",
+      "pillow"
+    ]
+  }
+}
diff --git a/examples/apps/qr_server/pyproject.toml b/examples/apps/qr_server/pyproject.toml
new file mode 100644
index 0000000..815ea0a
--- /dev/null
+++ b/examples/apps/qr_server/pyproject.toml
@@ -0,0 +1,13 @@
+[project]
+name = "fastmcp-app-examples"
+version = "0.1.0"
+description = "MCP App examples for FastMCP"
+requires-python = ">=3.10"
+dependencies = [
+    "fastmcp",
+    "qrcode[pil]>=8.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
diff --git a/examples/apps/qr_server/qr_server.py b/examples/apps/qr_server/qr_server.py
new file mode 100644
index 0000000..04639fd
--- /dev/null
+++ b/examples/apps/qr_server/qr_server.py
@@ -0,0 +1,170 @@
+"""QR Code MCP App Server — generates QR codes with an interactive view UI.
+
+Demonstrates MCP Apps with FastMCP:
+- Tool linked to a ui:// resource via AppConfig
+- HTML resource with CSP metadata for CDN-loaded dependencies
+- Embedded HTML using the @modelcontextprotocol/ext-apps JS SDK
+- ImageContent return type for binary data
+- Both stdio and HTTP transport modes
+
+Based on https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/qr-server
+
+Setup (from examples/apps/):
+    uv sync
+
+Usage:
+    uv run python qr_server.py            # HTTP mode (port 3001)
+    uv run python qr_server.py --stdio     # stdio mode for MCP clients
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+
+import qrcode  # type: ignore[import-untyped]
+from mcp import types
+
+from fastmcp import FastMCP
+from fastmcp.apps import AppConfig, ResourceCSP
+from fastmcp.tools import ToolResult
+
+VIEW_URI: str = "ui://qr-server/view.html"
+
+mcp: FastMCP = FastMCP("QR Code Server")
+
+EMBEDDED_VIEW_HTML: str = """\
+<!DOCTYPE html>
+<html>
+<head>
+  <meta name="color-scheme" content="light dark">
+  <style>
+    html, body {
+      margin: 0;
+      padding: 0;
+      overflow: hidden;
+      background: transparent;
+    }
+    body {
+      display: flex;
+      justify-content: center;
+      align-items: center;
+      height: 340px;
+      width: 340px;
+    }
+    img {
+      width: 300px;
+      height: 300px;
+      border-radius: 8px;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+    }
+  </style>
+</head>
+<body>
+  <div id="qr"></div>
+  <script type="module">
+    import { App } from "https://unpkg.com/@modelcontextprotocol/ext-apps@0.4.0/app-with-deps";
+
+    const app = new App({ name: "QR View", version: "1.0.0" });
+
+    app.ontoolresult = ({ content }) => {
+      const img = content?.find(c => c.type === 'image');
+      if (img) {
+        const qrDiv = document.getElementById('qr');
+        qrDiv.innerHTML = '';
+
+        const allowedTypes = ['image/png', 'image/jpeg', 'image/gif'];
+        const mimeType = allowedTypes.includes(img.mimeType) ? img.mimeType : 'image/png';
+
+        const image = document.createElement('img');
+        image.src = `data:${mimeType};base64,${img.data}`;
+        image.alt = "QR Code";
+        qrDiv.appendChild(image);
+      }
+    };
+
+    function handleHostContextChanged(ctx) {
+      if (ctx.safeAreaInsets) {
+        document.body.style.paddingTop = `${ctx.safeAreaInsets.top}px`;
+        document.body.style.paddingRight = `${ctx.safeAreaInsets.right}px`;
+        document.body.style.paddingBottom = `${ctx.safeAreaInsets.bottom}px`;
+        document.body.style.paddingLeft = `${ctx.safeAreaInsets.left}px`;
+      }
+    }
+
+    app.onhostcontextchanged = handleHostContextChanged;
+
+    await app.connect();
+    const ctx = app.getHostContext();
+    if (ctx) {
+      handleHostContextChanged(ctx);
+    }
+  </script>
+</body>
+</html>"""
+
+
+@mcp.tool(app=AppConfig(resource_uri=VIEW_URI))
+def generate_qr(
+    text: str = "https://gofastmcp.com",
+    box_size: int = 10,
+    border: int = 4,
+    error_correction: str = "M",
+    fill_color: str = "black",
+    back_color: str = "white",
+) -> ToolResult:
+    """Generate a QR code from text.
+
+    Args:
+        text: The text/URL to encode
+        box_size: Size of each box in pixels (default: 10)
+        border: Border size in boxes (default: 4)
+        error_correction: Error correction level - L(7%), M(15%), Q(25%), H(30%)
+        fill_color: Foreground color (hex like #FF0000 or name like red)
+        back_color: Background color (hex like #FFFFFF or name like white)
+    """
+    error_levels = {
+        "L": qrcode.constants.ERROR_CORRECT_L,
+        "M": qrcode.constants.ERROR_CORRECT_M,
+        "Q": qrcode.constants.ERROR_CORRECT_Q,
+        "H": qrcode.constants.ERROR_CORRECT_H,
+    }
+
+    if box_size <= 0:
+        raise ValueError("box_size must be > 0")
+    if border < 0:
+        raise ValueError("border must be >= 0")
+
+    error_key = error_correction.upper()
+    if error_key not in error_levels:
+        raise ValueError(f"error_correction must be one of: {', '.join(error_levels)}")
+
+    qr = qrcode.QRCode(
+        version=1,
+        error_correction=error_levels[error_key],
+        box_size=box_size,
+        border=border,
+    )
+    qr.add_data(text)
+    qr.make(fit=True)
+
+    img = qr.make_image(fill_color=fill_color, back_color=back_color)
+    buffer = io.BytesIO()
+    img.save(buffer, format="PNG")
+    b64 = base64.b64encode(buffer.getvalue()).decode()
+    return ToolResult(
+        content=[types.ImageContent(type="image", data=b64, mimeType="image/png")]
+    )
+
+
+@mcp.resource(
+    VIEW_URI,
+    app=AppConfig(csp=ResourceCSP(resource_domains=["https://unpkg.com"])),
+)
+def view() -> str:
+    """Interactive QR code viewer — renders tool results as images."""
+    return EMBEDDED_VIEW_HTML
+
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/apps/quiz/quiz_server.py b/examples/apps/quiz/quiz_server.py
new file mode 100644
index 0000000..7de6f08
--- /dev/null
+++ b/examples/apps/quiz/quiz_server.py
@@ -0,0 +1,258 @@
+"""Quiz / trivia app — a FastMCPApp example with multi-turn state.
+
+Demonstrates building state over a conversation:
+- The LLM generates quiz questions and calls `take_quiz` to launch the UI
+- The user answers via multiple-choice buttons (no forms)
+- Each answer calls `submit_answer`, which returns correctness + updated score
+- After the final question, a SendMessage pushes the score back to the LLM
+
+Usage:
+    uv run python quiz_server.py
+"""
+
+from __future__ import annotations
+
+from prefab_ui.actions import SetState, ShowToast
+from prefab_ui.actions.mcp import CallTool, SendMessage
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import (
+    Badge,
+    Button,
+    Card,
+    Column,
+    Heading,
+    If,
+    Muted,
+    Progress,
+    Row,
+    Text,
+)
+from prefab_ui.rx import ERROR, RESULT, Rx
+
+from fastmcp import FastMCP, FastMCPApp
+
+app = FastMCPApp("Quiz")
+
+DEFAULT_QUESTIONS = [
+    {
+        "question": "What is the capital of Australia?",
+        "options": ["Sydney", "Melbourne", "Canberra", "Perth"],
+        "correct": 2,
+    },
+    {
+        "question": "Which planet has the most moons?",
+        "options": ["Jupiter", "Saturn", "Uranus", "Neptune"],
+        "correct": 1,
+    },
+    {
+        "question": "What year did the Berlin Wall fall?",
+        "options": ["1987", "1989", "1991", "1993"],
+        "correct": 1,
+    },
+    {
+        "question": "Which element has the chemical symbol 'Au'?",
+        "options": ["Silver", "Aluminum", "Gold", "Argon"],
+        "correct": 2,
+    },
+    {
+        "question": "What is the deepest ocean?",
+        "options": ["Atlantic", "Indian", "Arctic", "Pacific"],
+        "correct": 3,
+    },
+]
+
+
+# ---------------------------------------------------------------------------
+# Backend tool — grade an answer and advance state
+# ---------------------------------------------------------------------------
+
+
+@app.tool()
+def submit_answer(
+    question_index: int,
+    selected: int,
+    correct: int,
+    total_questions: int,
+    current_score: int,
+) -> dict:
+    """Grade an answer and return the updated quiz state.
+
+    Returns a dict with:
+    - is_correct: whether the selected answer matched the correct index
+    - new_score: the updated cumulative score
+    - answered_index: the question that was just answered
+    - finished: whether this was the last question
+    """
+    is_correct = selected == correct
+    new_score = current_score + (1 if is_correct else 0)
+    finished = (question_index + 1) >= total_questions
+    return {
+        "is_correct": is_correct,
+        "new_score": new_score,
+        "answered_index": question_index,
+        "finished": finished,
+    }
+
+
+# ---------------------------------------------------------------------------
+# UI entry point — the LLM calls this with a topic and generated questions
+# ---------------------------------------------------------------------------
+
+
+@app.ui()
+def take_quiz(
+    topic: str = "General Knowledge",
+    questions: list[dict] | None = None,
+) -> PrefabApp:
+    """Launch a quiz UI.
+
+    The LLM generates the questions and passes them in:
+    - topic: displayed as the heading (e.g. "World Capitals")
+    - questions: list of dicts, each with:
+        - "question": the question text
+        - "options": list of answer strings
+        - "correct": index of the correct option
+
+    If no questions are provided, a built-in set is used.
+    """
+    if questions is None:
+        questions = DEFAULT_QUESTIONS
+    total = len(questions)
+    score = Rx("score")
+    current_q = Rx("current_question")
+    answered = Rx("answered")
+
+    with Column(gap=6, css_class="p-6 max-w-2xl") as view:
+        Heading(f"Quiz: {topic}")
+
+        with Row(gap=3, align="center"):
+            Badge(f"{score}/{total} correct", variant="secondary")
+            Progress(value=current_q, max=total, size="sm")
+
+        for i, q in enumerate(questions):
+            visible = current_q == i
+            options = q["options"]
+            correct_idx = q["correct"]
+
+            with If(visible):
+                with Card():
+                    with Column(gap=4, css_class="p-4"):
+                        Text(
+                            f"Question {i + 1} of {total}",
+                            css_class="text-sm font-medium text-muted-foreground",
+                        )
+                        Heading(q["question"], level=3)
+
+                        with If(~answered):
+                            with Column(gap=2):
+                                for opt_idx, option in enumerate(options):
+                                    on_success_actions = [
+                                        SetState("answered", True),
+                                        SetState(
+                                            "last_correct",
+                                            RESULT.is_correct,
+                                        ),
+                                        SetState("score", RESULT.new_score),
+                                    ]
+                                    is_last = (i + 1) >= total
+                                    if is_last:
+                                        on_success_actions.append(
+                                            SetState("finished", True),
+                                        )
+
+                                    Button(
+                                        option,
+                                        variant="outline",
+                                        css_class="w-full justify-start",
+                                        on_click=CallTool(
+                                            submit_answer,
+                                            arguments={
+                                                "question_index": i,
+                                                "selected": opt_idx,
+                                                "correct": correct_idx,
+                                                "total_questions": total,
+                                                "current_score": str(score),
+                                            },
+                                            on_success=on_success_actions,
+                                            on_error=ShowToast(
+                                                ERROR,
+                                                variant="error",
+                                            ),
+                                        ),
+                                    )
+
+                        with If(answered):
+                            with Column(gap=2):
+                                for opt_idx, option in enumerate(options):
+                                    if opt_idx == correct_idx:
+                                        Button(
+                                            f"{option}",
+                                            variant="success",
+                                            css_class="w-full justify-start",
+                                            disabled=True,
+                                        )
+                                    else:
+                                        Button(
+                                            option,
+                                            variant="ghost",
+                                            css_class="w-full justify-start opacity-50",
+                                            disabled=True,
+                                        )
+
+                                with If(Rx("last_correct")):
+                                    Badge("Correct!", variant="success")
+                                with If(~Rx("last_correct")):
+                                    Badge(
+                                        f"Incorrect — answer: {options[correct_idx]}",
+                                        variant="destructive",
+                                    )
+
+        with If(answered & ~Rx("finished")):
+            Button(
+                "Next Question",
+                variant="default",
+                on_click=[
+                    SetState("current_question", current_q + 1),
+                    SetState("answered", False),
+                    SetState("last_correct", False),
+                ],
+            )
+
+        with If(Rx("finished") & answered):
+            with Card(css_class="border-2 border-primary"):
+                with Column(gap=3, css_class="p-4 items-center text-center"):
+                    Heading("Quiz Complete!", level=2)
+                    Text(
+                        f"{score}/{total} correct",
+                        css_class="text-2xl font-bold",
+                    )
+                    Progress(
+                        value=score,
+                        max=total,
+                        variant="success",
+                        size="lg",
+                    )
+                    Muted("Click below to send your results to the conversation.")
+                    Button(
+                        "Send Results",
+                        variant="default",
+                        on_click=SendMessage(
+                            f'Quiz complete! Topic: "{topic}" '
+                            f"— Final score: {score}/{total} correct.",
+                        ),
+                    )
+
+    initial_state = {
+        "score": 0,
+        "current_question": 0,
+        "answered": False,
+        "last_correct": False,
+        "finished": False,
+    }
+    return PrefabApp(view=view, state=initial_state)
+
+
+mcp = FastMCP("Quiz Server", providers=[app])
+
+if __name__ == "__main__":
+    mcp.run(transport="http")
diff --git a/examples/apps/sales_dashboard/sales_dashboard_server.py b/examples/apps/sales_dashboard/sales_dashboard_server.py
new file mode 100644
index 0000000..fe38c64
--- /dev/null
+++ b/examples/apps/sales_dashboard/sales_dashboard_server.py
@@ -0,0 +1,233 @@
+from prefab_ui.components import (
+    Card,
+    CardContent,
+    Column,
+    Grid,
+    Heading,
+    Metric,
+    Muted,
+    Row,
+    Separator,
+    Text,
+)
+from prefab_ui.components.charts import AreaChart, ChartSeries, PieChart
+from prefab_ui.components.data_table import DataTable, DataTableColumn
+
+from fastmcp import FastMCP
+
+mcp = FastMCP("Sales Dashboard")
+
+MONTHLY_REVENUE = [
+    {"month": "Jul", "new_business": 182_000, "expansion": 74_000, "renewal": 210_000},
+    {"month": "Aug", "new_business": 195_000, "expansion": 81_000, "renewal": 215_000},
+    {"month": "Sep", "new_business": 224_000, "expansion": 93_000, "renewal": 208_000},
+    {"month": "Oct", "new_business": 210_000, "expansion": 88_000, "renewal": 222_000},
+    {"month": "Nov", "new_business": 248_000, "expansion": 102_000, "renewal": 230_000},
+    {"month": "Dec", "new_business": 271_000, "expansion": 115_000, "renewal": 238_000},
+    {"month": "Jan", "new_business": 235_000, "expansion": 97_000, "renewal": 241_000},
+    {"month": "Feb", "new_business": 262_000, "expansion": 108_000, "renewal": 245_000},
+    {"month": "Mar", "new_business": 289_000, "expansion": 121_000, "renewal": 252_000},
+    {"month": "Apr", "new_business": 305_000, "expansion": 134_000, "renewal": 258_000},
+    {"month": "May", "new_business": 318_000, "expansion": 142_000, "renewal": 263_000},
+    {"month": "Jun", "new_business": 342_000, "expansion": 156_000, "renewal": 270_000},
+]
+
+REVENUE_BY_SEGMENT = [
+    {"segment": "Enterprise", "revenue": 3_840_000},
+    {"segment": "Mid-Market", "revenue": 2_160_000},
+    {"segment": "SMB", "revenue": 1_440_000},
+    {"segment": "Startup", "revenue": 720_000},
+]
+
+RECENT_DEALS = [
+    {
+        "company": "Meridian Health Systems",
+        "amount": "$485,000",
+        "stage": "Closed Won",
+        "rep": "Sarah Chen",
+        "close_date": "Jun 12, 2026",
+    },
+    {
+        "company": "Atlas Financial Group",
+        "amount": "$372,000",
+        "stage": "Closed Won",
+        "rep": "Marcus Rivera",
+        "close_date": "Jun 10, 2026",
+    },
+    {
+        "company": "Pinnacle Manufacturing",
+        "amount": "$298,000",
+        "stage": "Negotiation",
+        "rep": "Aisha Patel",
+        "close_date": "Jun 28, 2026",
+    },
+    {
+        "company": "Crestview Logistics",
+        "amount": "$264,000",
+        "stage": "Proposal Sent",
+        "rep": "James O'Brien",
+        "close_date": "Jul 5, 2026",
+    },
+    {
+        "company": "Northstar Retail",
+        "amount": "$215,000",
+        "stage": "Closed Won",
+        "rep": "Sarah Chen",
+        "close_date": "Jun 8, 2026",
+    },
+    {
+        "company": "Ironclad Security",
+        "amount": "$189,000",
+        "stage": "Negotiation",
+        "rep": "Lena Kowalski",
+        "close_date": "Jul 1, 2026",
+    },
+    {
+        "company": "Summit Analytics",
+        "amount": "$176,000",
+        "stage": "Closed Won",
+        "rep": "Marcus Rivera",
+        "close_date": "Jun 5, 2026",
+    },
+    {
+        "company": "Brightpath Education",
+        "amount": "$142,000",
+        "stage": "Proposal Sent",
+        "rep": "Aisha Patel",
+        "close_date": "Jul 12, 2026",
+    },
+    {
+        "company": "Vantage Media",
+        "amount": "$128,000",
+        "stage": "Closed Won",
+        "rep": "Lena Kowalski",
+        "close_date": "Jun 3, 2026",
+    },
+    {
+        "company": "Redwood Hospitality",
+        "amount": "$97,000",
+        "stage": "Discovery",
+        "rep": "James O'Brien",
+        "close_date": "Jul 20, 2026",
+    },
+]
+
+
+@mcp.tool(app=True)
+def sales_dashboard() -> Column:
+    """Company sales dashboard with KPIs, revenue trends, segment breakdown, and recent deals."""
+    total_revenue = sum(
+        row["new_business"] + row["expansion"] + row["renewal"]
+        for row in MONTHLY_REVENUE
+    )
+    current_quarter = sum(
+        row["new_business"] + row["expansion"] + row["renewal"]
+        for row in MONTHLY_REVENUE[-3:]
+    )
+    prior_quarter = sum(
+        row["new_business"] + row["expansion"] + row["renewal"]
+        for row in MONTHLY_REVENUE[-6:-3]
+    )
+    growth_pct = (current_quarter - prior_quarter) / prior_quarter * 100
+
+    with Column(gap=6, css_class="p-6") as view:
+        with Row(gap=2, align="center"):
+            Heading("Sales Dashboard")
+            Muted("FY2026  |  Last updated Jun 15, 2026")
+
+        with Grid(columns=4, gap=4):
+            with Card():
+                with CardContent():
+                    Metric(
+                        label="Total Revenue",
+                        value=f"${total_revenue / 1_000_000:.1f}M",
+                        delta="+18.2% YoY",
+                        trend="up",
+                    )
+
+            with Card():
+                with CardContent():
+                    Metric(
+                        label="Quarterly Growth",
+                        value=f"{growth_pct:.1f}%",
+                        delta="+3.8pp vs prior",
+                        trend="up",
+                    )
+
+            with Card():
+                with CardContent():
+                    Metric(
+                        label="Active Customers",
+                        value="1,847",
+                        delta="+124 this quarter",
+                        trend="up",
+                    )
+
+            with Card():
+                with CardContent():
+                    Metric(
+                        label="Avg Deal Size",
+                        value="$236K",
+                        delta="+12% vs H1",
+                        trend="up",
+                    )
+
+        with Grid(columns=3, gap=6):
+            with Card(css_class="col-span-2"):
+                with CardContent():
+                    Text(
+                        "Monthly Revenue",
+                        css_class="text-sm font-medium text-muted-foreground mb-2",
+                    )
+                    AreaChart(
+                        data=MONTHLY_REVENUE,
+                        series=[
+                            ChartSeries(data_key="new_business", label="New Business"),
+                            ChartSeries(data_key="expansion", label="Expansion"),
+                            ChartSeries(data_key="renewal", label="Renewal"),
+                        ],
+                        x_axis="month",
+                        stacked=True,
+                        curve="smooth",
+                        show_legend=True,
+                        height=280,
+                        y_axis_format="compact",
+                    )
+
+            with Card():
+                with CardContent():
+                    Text(
+                        "Revenue by Segment",
+                        css_class="text-sm font-medium text-muted-foreground mb-2",
+                    )
+                    PieChart(
+                        data=REVENUE_BY_SEGMENT,
+                        data_key="revenue",
+                        name_key="segment",
+                        show_legend=True,
+                        inner_radius=50,
+                        height=280,
+                    )
+
+        Separator()
+
+        Text("Recent Deals", css_class="text-lg font-semibold")
+
+        DataTable(
+            columns=[
+                DataTableColumn(key="company", header="Company", sortable=True),
+                DataTableColumn(key="amount", header="Amount", sortable=True),
+                DataTableColumn(key="stage", header="Stage", sortable=True),
+                DataTableColumn(key="rep", header="Sales Rep", sortable=True),
+                DataTableColumn(key="close_date", header="Close Date", sortable=True),
+            ],
+            rows=RECENT_DEALS,
+            search=True,
+            paginated=True,
+        )
+
+    return view
+
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/apps/showcase_server.py b/examples/apps/showcase_server.py
new file mode 100644
index 0000000..4368a7f
--- /dev/null
+++ b/examples/apps/showcase_server.py
@@ -0,0 +1,345 @@
+# ruff: noqa: F405
+"""Component showcase — demonstrates the breadth of Prefab UI components.
+
+Usage:
+    uv run python showcase_server.py
+"""
+
+from prefab_ui.actions import SetState, ShowToast
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import *  # noqa: F403, F405
+from prefab_ui.components.charts import *  # noqa: F403, F405
+from prefab_ui.components.control_flow import Else, If
+
+from fastmcp import FastMCP
+
+mcp = FastMCP("Showcase")
+
+
+@mcp.tool(app=True)
+def showcase() -> PrefabApp:
+    """Prefab UI component showcase."""
+    with Grid(columns={"default": 1, "md": 2, "lg": 4}, gap=4, css_class="p-4") as view:
+        # ── Col 1 ─────────────────────────────────────────────────────
+        with Column(gap=4):
+            with Card():
+                with CardHeader():
+                    CardTitle("Register Towel")
+                    CardDescription("The most important item in the galaxy")
+                with CardContent():
+                    with Column(gap=3):
+                        owner_input = Input(placeholder="Owner name...", name="owner")
+                        with Combobox(
+                            placeholder="Type...", search_placeholder="Search types..."
+                        ):
+                            ComboboxOption("Bath", value="bath")
+                            ComboboxOption("Beach", value="beach")
+                            ComboboxOption("Interstellar", value="interstellar")
+                            ComboboxOption("Microfiber", value="micro")
+                        DatePicker(placeholder="Registration date")
+                with CardFooter():
+                    with Row(gap=2):
+                        with Dialog(
+                            title="Towel Registered!",
+                            description="Your towel has been added to the galactic registry.",
+                        ):
+                            Button("Register")
+                            with If("{{ owner }}"):
+                                Text(
+                                    f"Thanks, {owner_input.rx}. Don't forget to bring it."
+                                )
+                            with Else():
+                                Text("Anonymous, I see? Don't forget to bring it.")
+                        Button("Cancel", variant="outline")
+            with Card():
+                with CardContent():
+                    with Row(gap=2, align="center"):
+                        Loader(variant="dots", size="sm")
+                        Muted("Marvin is thinking...")
+
+            with Card():
+                with CardHeader():
+                    CardTitle("Ship Status")
+                with CardContent():
+                    with Column(gap=3):
+                        with Row(align="center", css_class="justify-between"):
+                            Text("heart-of-gold")
+                            with HoverCard(open_delay=0, close_delay=200):
+                                Badge("In Orbit", variant="default")
+                                with Column(gap=2):
+                                    Text("heart-of-gold")
+                                    Muted("Deployed 2h ago")
+                                    Progress(value=100, max=100, variant="success")
+                        Progress(value=100, max=100, indicator_class="bg-yellow-400")
+                        with Row(align="center", css_class="justify-between"):
+                            Text("vogon-poetry")
+                            with Tooltip("64% — ETA 12 min", delay=0):
+                                with Badge(variant="secondary"):
+                                    Loader(size="sm")
+                                    Text("Deploying")
+                        Progress(value=64, max=100)
+                        with Row(align="center", css_class="justify-between"):
+                            Text("deep-thought")
+                            with Tooltip(
+                                "Computing... 7.5 million years remaining", delay=0
+                            ):
+                                with Badge(variant="outline"):
+                                    Loader(size="sm", variant="ios")
+                                    Text("Soon...")
+                        Progress(value=12, max=100)
+            with Card():
+                with CardHeader():
+                    CardTitle("Planet Ratings")
+                with CardContent():
+                    RadarChart(
+                        data=[
+                            {"axis": "Views", "earth": 30, "mag": 95},
+                            {"axis": "Fjords", "earth": 65, "mag": 100},
+                            {"axis": "Pubs", "earth": 90, "mag": 10},
+                            {"axis": "Mice", "earth": 40, "mag": 85},
+                            {"axis": "Tea", "earth": 95, "mag": 15},
+                            {"axis": "Safety", "earth": 45, "mag": 70},
+                        ],
+                        series=[
+                            ChartSeries(dataKey="earth", label="Earth"),
+                            ChartSeries(dataKey="mag", label="Magrathea"),
+                        ],
+                        axis_key="axis",
+                        height=200,
+                        show_legend=True,
+                        show_tooltip=True,
+                    )
+
+        # ── Col 2 ─────────────────────────────────────────────────────
+        with Column(gap=4):
+            with Card():
+                with CardHeader():
+                    CardTitle("Survival Odds")
+                with CardContent(css_class="w-fit mx-auto"):
+                    Ring(
+                        value=42,
+                        label="42%",
+                        variant="info",
+                        size="lg",
+                        thickness=12,
+                        indicator_class="group-hover:drop-shadow-[0_0_24px_rgba(59,130,246,0.9)]",
+                    )
+            with Card():
+                with CardHeader():
+                    with Row(gap=2, align="center"):
+                        CardTitle("Improbability Drive")
+                        Loader(variant="pulse", size="sm", css_class="text-blue-500")
+                with CardContent():
+                    with Column(gap=2):
+                        Slider(min=0, max=100, value=42, name="improbability")
+                        with Row(align="center", css_class="justify-between"):
+                            Muted("Probable")
+                            Muted("Infinite")
+            with Alert(variant="success", icon="circle-check"):
+                AlertTitle("Don't Panic")
+                AlertDescription("Normality achieved.")
+            with Card():
+                with CardHeader():
+                    CardTitle("Prefect Horizon Config")
+                with CardContent():
+                    with Column(gap=3):
+                        Switch(label="Auto-scale agents", value=True, name="autoscale")
+                        Separator()
+                        Switch(label="Code Mode", value=True, name="code_mode")
+                        Separator()
+                        Switch(label="Tool call caching", value=False, name="cache")
+                with CardFooter():
+                    Button("Save Preferences", on_click=ShowToast("Preferences saved!"))
+            with Card():
+                with CardHeader():
+                    CardTitle("Travel Class")
+                with CardContent():
+                    with RadioGroup(name="travel_class"):
+                        Radio(option="economy", label="Economy")
+                        Radio(option="business", label="Business Class")
+                        Radio(
+                            option="improbability",
+                            label="Infinite Improbability",
+                            value=True,
+                        )
+
+        # ── Cols 3–4 ──────────────────────────────────────────────────
+        with GridItem(css_class="md:col-span-2"):
+            with Column(gap=4):
+                with Grid(columns=2, gap=4, css_class="h-32"):
+                    with Card():
+                        with CardHeader():
+                            CardTitle("Context Window")
+                        with CardContent():
+                            with Column(gap=6, justify="center", css_class="h-full"):
+                                with Row(align="center", css_class="justify-between"):
+                                    Text("45% used")
+                                    Muted("90k / 200k tokens")
+                                with Tooltip("Auto-compact buffer: 12%", delay=0):
+                                    Progress(value=45, max=100)
+                    with Card(css_class="pb-0 gap-0"):
+                        with CardContent():
+                            Metric(
+                                label="Fjords designed",
+                                value="1,847",
+                                delta="+3 coastlines",
+                            )
+                        Sparkline(
+                            data=[
+                                820,
+                                950,
+                                1100,
+                                980,
+                                1250,
+                                1400,
+                                1350,
+                                1500,
+                                1680,
+                                1847,
+                            ],
+                            variant="success",
+                            fill=True,
+                            css_class="h-16",
+                        )
+                with Card():
+                    with CardHeader():
+                        CardTitle("Towel Incidents")
+                    with CardContent():
+                        BarChart(
+                            data=[
+                                {"month": "Jan", "lost": 8, "found": 5},
+                                {"month": "Feb", "lost": 24, "found": 15},
+                                {"month": "Mar", "lost": 12, "found": 28},
+                                {"month": "Apr", "lost": 35, "found": 19},
+                                {"month": "May", "lost": 18, "found": 38},
+                                {"month": "Jun", "lost": 42, "found": 30},
+                            ],
+                            series=[
+                                ChartSeries(dataKey="lost", label="Lost"),
+                                ChartSeries(dataKey="found", label="Found"),
+                            ],
+                            x_axis="month",
+                            height=200,
+                            bar_radius=4,
+                            show_legend=True,
+                            show_tooltip=True,
+                            show_grid=True,
+                        )
+
+                with Grid(columns=2, gap=4):
+                    with Column(gap=4):
+                        with Card():
+                            with CardContent():
+                                with Column(gap=2):
+                                    Checkbox(label="Towel packed", value=True)
+                                    Checkbox(label="Guide charged", value=True)
+                                    Checkbox(label="Babel fish inserted", value=False)
+                        with If("{{ !pressed }}"):
+                            Button(
+                                "This is probably the best button to press.",
+                                variant="success",
+                                on_click=SetState("pressed", True),
+                            )
+                        with Else():
+                            Button(
+                                "Please do not press this button again.",
+                                variant="destructive",
+                                on_click=SetState("pressed", False),
+                            )
+                        with Card():
+                            with CardHeader():
+                                CardTitle("Marvin's Mood")
+                            with CardContent():
+                                with Column(gap=3):
+                                    P("How's life?")
+                                    with Column(gap=2):
+                                        Button(
+                                            "Meh",
+                                            on_click=ShowToast(
+                                                "Noted. Enthusiasm levels nominal."
+                                            ),
+                                        )
+                                        Button(
+                                            "Depressed",
+                                            variant="info",
+                                            on_click=ShowToast(
+                                                "I think you ought to know I'm feeling very depressed."
+                                            ),
+                                        )
+                                        Button(
+                                            "Don't talk to me about life",
+                                            variant="warning",
+                                            on_click=ShowToast(
+                                                "Brain the size of a planet and they ask me to pick up a piece of paper."
+                                            ),
+                                        )
+
+                    with Column(gap=4):
+                        with Alert(variant="destructive", icon="triangle-alert"):
+                            AlertTitle("Beware of the Leopard")
+                        with Card():
+                            with CardContent():
+                                DataTable(
+                                    columns=[
+                                        DataTableColumn(
+                                            key="crew", header="Crew", sortable=True
+                                        ),
+                                        DataTableColumn(
+                                            key="species",
+                                            header="Species",
+                                            sortable=True,
+                                        ),
+                                        DataTableColumn(
+                                            key="towel", header="Towel?", sortable=True
+                                        ),
+                                        DataTableColumn(
+                                            key="status", header="Status", sortable=True
+                                        ),
+                                    ],
+                                    rows=[
+                                        {
+                                            "crew": "Arthur Dent",
+                                            "species": "Human",
+                                            "towel": "Yes",
+                                            "status": "Confused",
+                                        },
+                                        {
+                                            "crew": "Ford Prefect",
+                                            "species": "Betelgeusian",
+                                            "towel": "Always",
+                                            "status": "Drinking",
+                                        },
+                                        {
+                                            "crew": "Zaphod",
+                                            "species": "Betelgeusian",
+                                            "towel": "Lost it",
+                                            "status": "Presidential",
+                                        },
+                                        {
+                                            "crew": "Trillian",
+                                            "species": "Human",
+                                            "towel": "Yes",
+                                            "status": "Navigating",
+                                        },
+                                        {
+                                            "crew": "Marvin",
+                                            "species": "Android",
+                                            "towel": "No point",
+                                            "status": "Depressed",
+                                        },
+                                        {
+                                            "crew": "Slartibartfast",
+                                            "species": "Magrathean",
+                                            "towel": "Somewhere",
+                                            "status": "Designing",
+                                        },
+                                    ],
+                                    search=True,
+                                    paginated=False,
+                                )
+
+    return PrefabApp(view=view, state={"pressed": False, "improbability": 42})
+
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/apps/system_monitor/system_monitor_server.py b/examples/apps/system_monitor/system_monitor_server.py
new file mode 100644
index 0000000..7105a36
--- /dev/null
+++ b/examples/apps/system_monitor/system_monitor_server.py
@@ -0,0 +1,195 @@
+"""System monitor — live CPU, memory, and disk stats from the host machine.
+
+Auto-refreshes every 3 seconds via SetInterval + CallTool.
+
+Requires psutil: pip install psutil
+
+Usage:
+    fastmcp dev apps system_monitor_server.py
+"""
+
+import platform
+import time
+from datetime import datetime
+
+import psutil
+from prefab_ui.actions import SetInterval, SetState
+from prefab_ui.actions.mcp import CallTool
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import (
+    Badge,
+    Card,
+    CardContent,
+    CardHeader,
+    Column,
+    Grid,
+    Heading,
+    Metric,
+    Muted,
+    Progress,
+    Row,
+    Select,
+    SelectOption,
+    Small,
+    Text,
+)
+from prefab_ui.components.charts import AreaChart, ChartSeries
+from prefab_ui.components.control_flow import ForEach
+from prefab_ui.rx import RESULT, STATE, Rx
+
+from fastmcp import FastMCP
+from fastmcp.apps.app import FastMCPApp
+
+app = FastMCPApp("Monitor")
+
+_history: list[dict] = []
+
+
+def _collect_stats() -> dict:
+    """Collect a full snapshot of system stats."""
+    cpu = psutil.cpu_percent(interval=0.1)
+    mem = psutil.virtual_memory()
+    disk = psutil.disk_usage("/")
+
+    now = datetime.now().strftime("%H:%M:%S")
+    _history.append({"time": now, "cpu": cpu, "memory": mem.percent})
+    if len(_history) > 100:
+        del _history[: len(_history) - 100]
+
+    top_procs = []
+    for p in sorted(
+        psutil.process_iter(["pid", "name", "cpu_percent", "memory_percent"]),
+        key=lambda p: p.info.get("cpu_percent") or 0,
+        reverse=True,
+    )[:6]:
+        info = p.info
+        top_procs.append(
+            {
+                "pid": info.get("pid") or 0,
+                "name": info.get("name") or "unknown",
+                "cpu": f"{(info.get('cpu_percent') or 0):.1f}%",
+                "memory": f"{(info.get('memory_percent') or 0):.1f}%",
+            }
+        )
+
+    return {
+        "cpu": cpu,
+        "mem_pct": mem.percent,
+        "mem_used": mem.used // (1024**3),
+        "mem_total": mem.total // (1024**3),
+        "disk_pct": disk.percent,
+        "disk_used": disk.used // (1024**3),
+        "disk_total": disk.total // (1024**3),
+        "uptime": _format_uptime(),
+        "cores": psutil.cpu_count(),
+        "platform": f"{platform.system()} {platform.machine()}",
+        "hostname": platform.node(),
+        "healthy": cpu < 80 and mem.percent < 90,
+        "history": list(_history),
+        "top_procs": top_procs,
+    }
+
+
+def _format_uptime() -> str:
+    elapsed = int(time.time() - psutil.boot_time())
+    days, remainder = divmod(elapsed, 86400)
+    hours, remainder = divmod(remainder, 3600)
+    minutes, _ = divmod(remainder, 60)
+    if days > 0:
+        return f"{days}d {hours}h {minutes}m"
+    return f"{hours}h {minutes}m"
+
+
+@app.tool()
+def refresh() -> dict:
+    """Collect fresh system stats."""
+    return _collect_stats()
+
+
+@app.ui()
+def system_dashboard() -> PrefabApp:
+    """Live system dashboard with auto-refresh."""
+    initial = _collect_stats()
+
+    with PrefabApp(state={"stats": initial, "interval": "500"}) as ui:
+        with Column(
+            gap=6,
+            css_class="p-6",
+            on_mount=SetInterval(
+                duration=Rx("interval"),
+                on_tick=CallTool(
+                    "refresh",
+                    on_success=SetState("stats", RESULT),
+                ),
+            ),
+        ):
+            with Row(gap=3, align="center"):
+                Heading("System Monitor")
+                Badge(STATE.stats.hostname, variant="outline")
+                with Select(name="interval", css_class="w-32"):
+                    SelectOption("0.5s", value="500")
+                    SelectOption("1s", value="1000")
+                    SelectOption("5s", value="5000")
+
+            with Grid(columns=4, gap=4):
+                with Card():
+                    with CardContent():
+                        Metric(label="CPU", value=f"{STATE.stats.cpu}%")
+                        Progress(value=STATE.stats.cpu)
+
+                with Card():
+                    with CardContent():
+                        Metric(label="Memory", value=f"{STATE.stats.mem_pct}%")
+                        Progress(value=STATE.stats.mem_pct)
+                        Muted(f"{STATE.stats.mem_used}GB / {STATE.stats.mem_total}GB")
+
+                with Card():
+                    with CardContent():
+                        Metric(label="Disk", value=f"{STATE.stats.disk_pct}%")
+                        Progress(value=STATE.stats.disk_pct)
+                        Muted(f"{STATE.stats.disk_used}GB / {STATE.stats.disk_total}GB")
+
+                with Card():
+                    with CardContent():
+                        Metric(label="Uptime", value=STATE.stats.uptime)
+                        Muted(f"{STATE.stats.cores} cores")
+
+            with Grid(columns=[2, 1], gap=4):
+                with Card():
+                    with CardHeader():
+                        Text("CPU & Memory", css_class="text-sm font-medium")
+                    with CardContent():
+                        AreaChart(
+                            data=STATE.stats.history,
+                            series=[
+                                ChartSeries(data_key="cpu", label="CPU %"),
+                                ChartSeries(data_key="memory", label="Memory %"),
+                            ],
+                            x_axis="time",
+                            curve="smooth",
+                            show_legend=True,
+                            height=220,
+                            animate=False,
+                        )
+
+                with Card():
+                    with CardHeader():
+                        Text("Top Processes", css_class="text-sm font-medium")
+                    with CardContent():
+                        with Column(gap=2):
+                            with ForEach("stats.top_procs") as proc:
+                                with Row(justify="between", align="center"):
+                                    with Column(gap=0):
+                                        Small(proc.name)
+                                        Muted(proc.pid)
+                                    with Row(gap=2):
+                                        Badge(proc.cpu, variant="outline")
+                                        Badge(proc.memory, variant="outline")
+
+    return ui
+
+
+mcp = FastMCP("System Monitor", providers=[app])
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/atproto_mcp/README.md b/examples/atproto_mcp/README.md
new file mode 100644
index 0000000..7543554
--- /dev/null
+++ b/examples/atproto_mcp/README.md
@@ -0,0 +1,156 @@
+# ATProto MCP Server
+
+This example demonstrates a FastMCP server that provides tools and resources for interacting with the AT Protocol (Bluesky).
+
+## Features
+
+### Resources (Read-only)
+
+- **atproto://profile/status**: Get connection status and profile information
+- **atproto://timeline**: Retrieve your timeline feed
+- **atproto://notifications**: Get recent notifications
+
+### Tools (Actions)
+
+- **post**: Create posts with rich features (text, images, quotes, replies, links, mentions)
+- **create_thread**: Post multipart threads with automatic linking
+- **search**: Search for posts by query
+- **follow**: Follow users by handle
+- **like**: Like posts by URI
+- **repost**: Share posts by URI
+
+## Setup
+
+1. Create a `.env` file in the root directory with your Bluesky credentials:
+
+```bash
+ATPROTO_HANDLE=your.handle@bsky.social
+ATPROTO_PASSWORD=your-app-password
+ATPROTO_PDS_URL=https://bsky.social  # optional, defaults to bsky.social
+```
+
+2. Install and run the server:
+
+```bash
+# Install dependencies
+uv pip install -e .
+
+# Run the server
+uv run atproto-mcp
+```
+
+## The Unified Post Tool
+
+The `post` tool is a single, flexible interface for all posting needs:
+
+```python
+async def post(
+    text: str,                          # Required: Post content
+    images: list[str] = None,           # Optional: Image URLs (max 4)
+    image_alts: list[str] = None,       # Optional: Alt text for images
+    links: list[RichTextLink] = None,   # Optional: Embedded links
+    mentions: list[RichTextMention] = None,  # Optional: User mentions
+    reply_to: str = None,               # Optional: Reply to post URI
+    reply_root: str = None,             # Optional: Thread root URI
+    quote: str = None,                  # Optional: Quote post URI
+)
+```
+
+### Usage Examples
+
+```python
+from fastmcp import Client
+from atproto_mcp.server import atproto_mcp
+
+async def demo():
+    async with Client(atproto_mcp) as client:
+        # Simple post
+        await client.call_tool("post", {
+            "text": "Hello from FastMCP!"
+        })
+        
+        # Post with image
+        await client.call_tool("post", {
+            "text": "Beautiful sunset! 🌅",
+            "images": ["https://example.com/sunset.jpg"],
+            "image_alts": ["Sunset over the ocean"]
+        })
+        
+        # Reply to a post
+        await client.call_tool("post", {
+            "text": "Great point!",
+            "reply_to": "at://did:plc:xxx/app.bsky.feed.post/yyy"
+        })
+        
+        # Quote post
+        await client.call_tool("post", {
+            "text": "This is important:",
+            "quote": "at://did:plc:xxx/app.bsky.feed.post/yyy"
+        })
+        
+        # Rich text with links and mentions
+        await client.call_tool("post", {
+            "text": "Check out FastMCP by @alternatebuild.dev",
+            "links": [{"text": "FastMCP", "url": "https://github.com/PrefectHQ/fastmcp"}],
+            "mentions": [{"handle": "alternatebuild.dev", "display_text": "@alternatebuild.dev"}]
+        })
+        
+        # Advanced: Quote with image
+        await client.call_tool("post", {
+            "text": "Adding visual context:",
+            "quote": "at://did:plc:xxx/app.bsky.feed.post/yyy",
+            "images": ["https://example.com/chart.png"]
+        })
+        
+        # Advanced: Reply with rich text
+        await client.call_tool("post", {
+            "text": "I agree! See this article for more info",
+            "reply_to": "at://did:plc:xxx/app.bsky.feed.post/yyy",
+            "links": [{"text": "this article", "url": "https://example.com/article"}]
+        })
+        
+        # Create a thread
+        await client.call_tool("create_thread", {
+            "posts": [
+                {"text": "Starting a thread about Python 🧵"},
+                {"text": "Python is great for rapid prototyping"},
+                {"text": "And the ecosystem is amazing!", "images": ["https://example.com/python.jpg"]}
+            ]
+        })
+```
+
+## AI Assistant Use Cases
+
+The unified API enables natural AI assistant interactions:
+
+- **"Reply to that post with these findings"** → Uses `reply_to` with rich text
+- **"Share this article with commentary"** → Uses `quote` with the article link
+- **"Post this chart with explanation"** → Uses `images` with descriptive text
+- **"Start a thread about AI safety"** → Uses `create_thread` for automatic linking
+
+## Architecture
+
+The server is organized as:
+- `server.py` - Public API with resources and tools
+- `_atproto/` - Private implementation module
+  - `_client.py` - ATProto client management
+  - `_posts.py` - Unified posting logic
+  - `_profile.py` - Profile operations
+  - `_read.py` - Timeline, search, notifications
+  - `_social.py` - Follow, like, repost
+- `types.py` - TypedDict definitions
+- `settings.py` - Configuration management
+
+## Running the Demo
+
+```bash
+# Run demo (read-only)
+uv run python demo.py
+
+# Run demo with posting enabled
+uv run python demo.py --post
+```
+
+## Security Note
+
+Store your Bluesky credentials securely in environment variables. Never commit credentials to version control.
\ No newline at end of file
diff --git a/examples/atproto_mcp/demo.py b/examples/atproto_mcp/demo.py
new file mode 100644
index 0000000..154e111
--- /dev/null
+++ b/examples/atproto_mcp/demo.py
@@ -0,0 +1,260 @@
+"""Demo script showing all ATProto MCP server capabilities."""
+
+import argparse
+import asyncio
+import json
+from typing import cast
+
+from atproto_mcp.server import atproto_mcp
+from atproto_mcp.types import (
+    NotificationsResult,
+    PostResult,
+    ProfileInfo,
+    SearchResult,
+    TimelineResult,
+)
+
+from fastmcp import Client
+
+
+async def main(enable_posting: bool = False):
+    print("🔵 ATProto MCP Server Demo\n")
+
+    async with Client(atproto_mcp) as client:
+        # 1. Check connection status (resource)
+        print("1. Checking connection status...")
+        result = await client.read_resource("atproto://profile/status")
+        status: ProfileInfo = (
+            json.loads(result[0].text) if result else cast(ProfileInfo, {})
+        )
+
+        if status.get("connected"):
+            print(f"✅ Connected as: @{status['handle']}")
+            print(f"   Followers: {status['followers']}")
+            print(f"   Following: {status['following']}")
+            print(f"   Posts: {status['posts']}")
+        else:
+            print(f"❌ Connection failed: {status.get('error')}")
+            return
+
+        # 2. Get timeline
+        print("\n2. Getting timeline...")
+        result = await client.read_resource("atproto://timeline")
+        timeline: TimelineResult = (
+            json.loads(result[0].text) if result else cast(TimelineResult, {})
+        )
+
+        if timeline.get("success") and timeline["posts"]:
+            print(f"✅ Found {timeline['count']} posts")
+            post = timeline["posts"][0]
+            print(f"   Latest by @{post['author']}: {post['text'][:80]}...")
+            save_uri = post["uri"]  # Save for later interactions
+        else:
+            print("❌ No posts in timeline")
+            save_uri = None
+
+        # 3. Search for posts
+        print("\n3. Searching for posts about 'Bluesky'...")
+        result = await client.call_tool("search", {"query": "Bluesky", "limit": 5})
+        search: SearchResult = (
+            json.loads(result[0].text) if result else cast(SearchResult, {})
+        )
+
+        if search.get("success") and search["posts"]:
+            print(f"✅ Found {search['count']} posts")
+            print(f"   Sample: {search['posts'][0]['text'][:80]}...")
+
+        # 4. Get notifications
+        print("\n4. Checking notifications...")
+        result = await client.read_resource("atproto://notifications")
+        notifs: NotificationsResult = (
+            json.loads(result[0].text) if result else cast(NotificationsResult, {})
+        )
+
+        if notifs.get("success"):
+            print(f"✅ You have {notifs['count']} notifications")
+            unread = sum(1 for n in notifs["notifications"] if not n["is_read"])
+            if unread:
+                print(f"   ({unread} unread)")
+
+        # 5. Demo posting capabilities
+        if enable_posting:
+            print("\n5. Demonstrating posting capabilities...")
+
+            # a. Simple post
+            print("\n   a) Creating a simple post...")
+            result = await client.call_tool(
+                "post",
+                {"text": "🧪 Testing the unified ATProto MCP post tool! #FastMCP"},
+            )
+            post_result: PostResult = json.loads(result[0].text) if result else {}
+            if post_result.get("success"):
+                print("   ✅ Posted successfully!")
+                simple_uri = post_result["uri"]
+            else:
+                print(f"   ❌ Failed: {post_result.get('error')}")
+                simple_uri = None
+
+            # b. Post with rich text (link and mention)
+            print("\n   b) Creating a post with rich text...")
+            result = await client.call_tool(
+                "post",
+                {
+                    "text": "Check out FastMCP and follow @alternatebuild.dev for updates!",
+                    "links": [
+                        {
+                            "text": "FastMCP",
+                            "url": "https://github.com/PrefectHQ/fastmcp",
+                        }
+                    ],
+                    "mentions": [
+                        {
+                            "handle": "alternatebuild.dev",
+                            "display_text": "@alternatebuild.dev",
+                        }
+                    ],
+                },
+            )
+            if json.loads(result[0].text).get("success"):
+                print("   ✅ Rich text post created!")
+
+            # c. Reply to a post
+            if save_uri:
+                print("\n   c) Replying to a post...")
+                result = await client.call_tool(
+                    "post", {"text": "Great post! 👍", "reply_to": save_uri}
+                )
+                if json.loads(result[0].text).get("success"):
+                    print("   ✅ Reply posted!")
+
+            # d. Quote post
+            if simple_uri:
+                print("\n   d) Creating a quote post...")
+                result = await client.call_tool(
+                    "post",
+                    {
+                        "text": "Quoting my own test post for demo purposes 🔄",
+                        "quote": simple_uri,
+                    },
+                )
+                if json.loads(result[0].text).get("success"):
+                    print("   ✅ Quote post created!")
+
+            # e. Post with image
+            print("\n   e) Creating a post with image...")
+            result = await client.call_tool(
+                "post",
+                {
+                    "text": "Here's a test image post! 📸",
+                    "images": ["https://picsum.photos/400/300"],
+                    "image_alts": ["Random test image"],
+                },
+            )
+            if json.loads(result[0].text).get("success"):
+                print("   ✅ Image post created!")
+
+            # f. Quote with image (advanced)
+            if simple_uri:
+                print("\n   f) Creating a quote post with image...")
+                result = await client.call_tool(
+                    "post",
+                    {
+                        "text": "Quote + image combo! 🎨",
+                        "quote": simple_uri,
+                        "images": ["https://picsum.photos/300/200"],
+                        "image_alts": ["Another test image"],
+                    },
+                )
+                if json.loads(result[0].text).get("success"):
+                    print("   ✅ Quote with image created!")
+
+            # g. Social actions
+            if save_uri:
+                print("\n   g) Demonstrating social actions...")
+
+                # Like
+                result = await client.call_tool("like", {"uri": save_uri})
+                if json.loads(result[0].text).get("success"):
+                    print("   ✅ Liked a post!")
+
+                # Repost
+                result = await client.call_tool("repost", {"uri": save_uri})
+                if json.loads(result[0].text).get("success"):
+                    print("   ✅ Reposted!")
+
+                # Follow
+                result = await client.call_tool(
+                    "follow", {"handle": "alternatebuild.dev"}
+                )
+                if json.loads(result[0].text).get("success"):
+                    print("   ✅ Followed @alternatebuild.dev!")
+
+            # h. Thread creation (new!)
+            print("\n   h) Creating a thread...")
+            result = await client.call_tool(
+                "create_thread",
+                {
+                    "posts": [
+                        {
+                            "text": "Let me share some thoughts about the ATProto MCP server 🧵"
+                        },
+                        {
+                            "text": "First, it makes posting from the terminal incredibly smooth"
+                        },
+                        {
+                            "text": "The unified post API means one tool handles everything",
+                            "links": [
+                                {
+                                    "text": "everything",
+                                    "url": "https://github.com/PrefectHQ/fastmcp",
+                                }
+                            ],
+                        },
+                        {
+                            "text": "And now with create_thread, multi-post threads are trivial!"
+                        },
+                    ]
+                },
+            )
+            if json.loads(result[0].text).get("success"):
+                thread_result = json.loads(result[0].text)
+                print(f"   ✅ Thread created with {thread_result['post_count']} posts!")
+        else:
+            print("\n5. Posting capabilities (not enabled):")
+            print("   To test posting, run with --post flag")
+            print("   Example: python demo.py --post")
+
+        # 6. Show available capabilities
+        print("\n6. Available capabilities:")
+        print("\n   Resources (read-only):")
+        print("     - atproto://profile/status")
+        print("     - atproto://timeline")
+        print("     - atproto://notifications")
+
+        print("\n   Tools (actions):")
+        print("     - post: Unified posting with rich features")
+        print("       • Simple text posts")
+        print("       • Images (up to 4)")
+        print("       • Rich text (links, mentions)")
+        print("       • Replies and threads")
+        print("       • Quote posts")
+        print("       • Combinations (quote + image, reply + rich text, etc.)")
+        print("     - search: Search for posts")
+        print("     - create_thread: Post multi-part threads")
+        print("     - follow: Follow users")
+        print("     - like: Like posts")
+        print("     - repost: Share posts")
+
+        print("\n✨ Demo complete!")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="ATProto MCP Server Demo")
+    parser.add_argument(
+        "--post",
+        action="store_true",
+        help="Enable posting test messages to Bluesky",
+    )
+    args = parser.parse_args()
+
+    asyncio.run(main(enable_posting=args.post))
diff --git a/examples/atproto_mcp/fastmcp.json b/examples/atproto_mcp/fastmcp.json
new file mode 100644
index 0000000..d51fdc2
--- /dev/null
+++ b/examples/atproto_mcp/fastmcp.json
@@ -0,0 +1,11 @@
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "src/atproto_mcp/server.py"
+  },
+  "environment": {
+    "dependencies": [
+      "atproto_mcp@git+https://github.com/PrefectHQ/fastmcp.git#subdirectory=examples/atproto_mcp"
+    ]
+  }
+}
\ No newline at end of file
diff --git a/examples/atproto_mcp/pyproject.toml b/examples/atproto_mcp/pyproject.toml
new file mode 100644
index 0000000..2f1b67a
--- /dev/null
+++ b/examples/atproto_mcp/pyproject.toml
@@ -0,0 +1,24 @@
+[project]
+name = "atproto-mcp"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [{ name = "zzstoatzz", email = "thrast36@gmail.com" }]
+requires-python = ">=3.10"
+dependencies = [
+    "fastmcp>=0.8.0",
+    "atproto@git+https://github.com/MarshalX/atproto.git@refs/pull/605/head",
+    "pydantic-settings>=2.0.0",
+    "websockets>=15.0.1",
+    "httpx>=0.27.0",
+]
+
+[project.scripts]
+atproto-mcp = "atproto_mcp.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.metadata]
+allow-direct-references = true
diff --git a/examples/atproto_mcp/src/atproto_mcp/__init__.py b/examples/atproto_mcp/src/atproto_mcp/__init__.py
new file mode 100644
index 0000000..9752f9b
--- /dev/null
+++ b/examples/atproto_mcp/src/atproto_mcp/__init__.py
@@ -0,0 +1,3 @@
+from atproto_mcp.settings import settings
+
+__all__ = ["settings"]
diff --git a/examples/atproto_mcp/src/atproto_mcp/__main__.py b/examples/atproto_mcp/src/atproto_mcp/__main__.py
new file mode 100644
index 0000000..bb4c12e
--- /dev/null
+++ b/examples/atproto_mcp/src/atproto_mcp/__main__.py
@@ -0,0 +1,9 @@
+from atproto_mcp.server import atproto_mcp
+
+
+def main():
+    atproto_mcp.run()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/atproto_mcp/src/atproto_mcp/_atproto/__init__.py b/examples/atproto_mcp/src/atproto_mcp/_atproto/__init__.py
new file mode 100644
index 0000000..ae9b766
--- /dev/null
+++ b/examples/atproto_mcp/src/atproto_mcp/_atproto/__init__.py
@@ -0,0 +1,20 @@
+"""Private ATProto implementation module."""
+
+from ._client import get_client
+from ._posts import create_post, create_thread
+from ._profile import get_profile_info
+from ._read import fetch_notifications, fetch_timeline, search_for_posts
+from ._social import follow_user_by_handle, like_post_by_uri, repost_by_uri
+
+__all__ = [
+    "create_post",
+    "create_thread",
+    "fetch_notifications",
+    "fetch_timeline",
+    "follow_user_by_handle",
+    "get_client",
+    "get_profile_info",
+    "like_post_by_uri",
+    "repost_by_uri",
+    "search_for_posts",
+]
diff --git a/examples/atproto_mcp/src/atproto_mcp/_atproto/_client.py b/examples/atproto_mcp/src/atproto_mcp/_atproto/_client.py
new file mode 100644
index 0000000..40ee8e1
--- /dev/null
+++ b/examples/atproto_mcp/src/atproto_mcp/_atproto/_client.py
@@ -0,0 +1,16 @@
+"""ATProto client management."""
+
+from atproto import Client
+
+from atproto_mcp.settings import settings
+
+_client: Client | None = None
+
+
+def get_client() -> Client:
+    """Get or create an authenticated ATProto client."""
+    global _client
+    if _client is None:
+        _client = Client()
+        _client.login(settings.atproto_handle, settings.atproto_password)
+    return _client
diff --git a/examples/atproto_mcp/src/atproto_mcp/_atproto/_posts.py b/examples/atproto_mcp/src/atproto_mcp/_atproto/_posts.py
new file mode 100644
index 0000000..daf8c34
--- /dev/null
+++ b/examples/atproto_mcp/src/atproto_mcp/_atproto/_posts.py
@@ -0,0 +1,420 @@
+"""Unified posting functionality."""
+
+import time
+from datetime import datetime
+
+from atproto import models
+
+from atproto_mcp.types import (
+    PostResult,
+    RichTextLink,
+    RichTextMention,
+    ThreadPost,
+    ThreadResult,
+)
+
+from ._client import get_client
+
+
+def create_post(
+    text: str,
+    images: list[str] | None = None,
+    image_alts: list[str] | None = None,
+    links: list[RichTextLink] | None = None,
+    mentions: list[RichTextMention] | None = None,
+    reply_to: str | None = None,
+    reply_root: str | None = None,
+    quote: str | None = None,
+) -> PostResult:
+    """Create a unified post with optional features.
+
+    Args:
+        text: Post text (max 300 chars)
+        images: URLs of images to attach (max 4)
+        image_alts: Alt text for images
+        links: Links to embed in rich text
+        mentions: User mentions to embed
+        reply_to: URI of post to reply to
+        reply_root: URI of thread root (defaults to reply_to)
+        quote: URI of post to quote
+    """
+    try:
+        client = get_client()
+        facets = []
+        embed = None
+        reply_ref = None
+
+        # Always build facets to handle auto-detected URLs and explicit links/mentions
+        facets = _build_facets(text, links, mentions, client)
+
+        # Handle replies
+        if reply_to:
+            reply_ref = _build_reply_ref(reply_to, reply_root, client)
+
+        # Handle quotes and images
+        if quote and images:
+            # Quote with images - create record with media embed
+            embed = _build_quote_with_images_embed(quote, images, image_alts, client)
+        elif quote:
+            # Quote only
+            embed = _build_quote_embed(quote, client)
+        elif images:
+            # Images only - use send_images for proper handling
+            return _send_images(text, images, image_alts, facets, reply_ref, client)
+
+        # Send the post (always include facets if any were created)
+        post = client.send_post(
+            text=text,
+            facets=facets if facets else None,
+            embed=embed,
+            reply_to=reply_ref,
+        )
+
+        return PostResult(
+            success=True,
+            uri=post.uri,
+            cid=post.cid,
+            text=text,
+            created_at=datetime.now().isoformat(),
+            error=None,
+        )
+    except Exception as e:
+        return PostResult(
+            success=False,
+            uri=None,
+            cid=None,
+            text=None,
+            created_at=None,
+            error=str(e),
+        )
+
+
+def _build_facets(
+    text: str,
+    links: list[RichTextLink] | None,
+    mentions: list[RichTextMention] | None,
+    client,
+):
+    """Build facets for rich text formatting, including auto-detected URLs."""
+    import re
+
+    facets = []
+    covered_ranges = []
+
+    # URL regex pattern for auto-detection
+    url_pattern = re.compile(
+        r"https?://(?:www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b(?:[-a-zA-Z0-9()@:%_\+.~#?&/=]*)"
+    )
+
+    # Process explicit links first
+    if links:
+        for link in links:
+            start = text.find(link["text"])
+            if start == -1:
+                continue
+            end = start + len(link["text"])
+
+            # Track this range as covered
+            covered_ranges.append((start, end))
+
+            facets.append(
+                models.AppBskyRichtextFacet.Main(
+                    features=[models.AppBskyRichtextFacet.Link(uri=link["url"])],
+                    index=models.AppBskyRichtextFacet.ByteSlice(
+                        byte_start=len(text[:start].encode("UTF-8")),
+                        byte_end=len(text[:end].encode("UTF-8")),
+                    ),
+                )
+            )
+
+    # Auto-detect URLs that aren't already covered by explicit links
+    for match in url_pattern.finditer(text):
+        url = match.group()
+        start = match.start()
+        end = match.end()
+
+        # Check if this URL overlaps with any explicit link
+        overlaps = False
+        for covered_start, covered_end in covered_ranges:
+            if not (end <= covered_start or start >= covered_end):
+                overlaps = True
+                break
+
+        if not overlaps:
+            facets.append(
+                models.AppBskyRichtextFacet.Main(
+                    features=[models.AppBskyRichtextFacet.Link(uri=url)],
+                    index=models.AppBskyRichtextFacet.ByteSlice(
+                        byte_start=len(text[:start].encode("UTF-8")),
+                        byte_end=len(text[:end].encode("UTF-8")),
+                    ),
+                )
+            )
+
+    # Process mentions
+    if mentions:
+        for mention in mentions:
+            display_text = mention.get("display_text") or f"@{mention['handle']}"
+            start = text.find(display_text)
+            if start == -1:
+                continue
+            end = start + len(display_text)
+
+            # Resolve handle to DID
+            resolved = client.app.bsky.actor.search_actors(
+                params={"q": mention["handle"], "limit": 1}
+            )
+            if not resolved.actors:
+                continue
+
+            did = resolved.actors[0].did
+            facets.append(
+                models.AppBskyRichtextFacet.Main(
+                    features=[models.AppBskyRichtextFacet.Mention(did=did)],
+                    index=models.AppBskyRichtextFacet.ByteSlice(
+                        byte_start=len(text[:start].encode("UTF-8")),
+                        byte_end=len(text[:end].encode("UTF-8")),
+                    ),
+                )
+            )
+
+    return facets
+
+
+def _build_reply_ref(reply_to: str, reply_root: str | None, client):
+    """Build reply reference."""
+    # Get parent post to extract CID
+    parent_post = client.app.bsky.feed.get_posts(params={"uris": [reply_to]})
+    if not parent_post.posts:
+        raise ValueError("Parent post not found")
+
+    parent_cid = parent_post.posts[0].cid
+    parent_ref = models.ComAtprotoRepoStrongRef.Main(uri=reply_to, cid=parent_cid)
+
+    # If no root_uri provided, parent is the root
+    if reply_root is None:
+        root_ref = parent_ref
+    else:
+        # Get root post CID
+        root_post = client.app.bsky.feed.get_posts(params={"uris": [reply_root]})
+        if not root_post.posts:
+            raise ValueError("Root post not found")
+        root_cid = root_post.posts[0].cid
+        root_ref = models.ComAtprotoRepoStrongRef.Main(uri=reply_root, cid=root_cid)
+
+    return models.AppBskyFeedPost.ReplyRef(parent=parent_ref, root=root_ref)
+
+
+def _build_quote_embed(quote_uri: str, client):
+    """Build quote embed."""
+    # Get the post to quote
+    quoted_post = client.app.bsky.feed.get_posts(params={"uris": [quote_uri]})
+    if not quoted_post.posts:
+        raise ValueError("Quoted post not found")
+
+    # Create strong ref for the quoted post
+    quoted_cid = quoted_post.posts[0].cid
+    quoted_ref = models.ComAtprotoRepoStrongRef.Main(uri=quote_uri, cid=quoted_cid)
+
+    # Create the embed
+    return models.AppBskyEmbedRecord.Main(record=quoted_ref)
+
+
+def _build_quote_with_images_embed(
+    quote_uri: str, image_urls: list[str], image_alts: list[str] | None, client
+):
+    """Build quote embed with images."""
+    import httpx
+
+    # Get the quoted post
+    quoted_post = client.app.bsky.feed.get_posts(params={"uris": [quote_uri]})
+    if not quoted_post.posts:
+        raise ValueError("Quoted post not found")
+
+    quoted_cid = quoted_post.posts[0].cid
+    quoted_ref = models.ComAtprotoRepoStrongRef.Main(uri=quote_uri, cid=quoted_cid)
+
+    # Download and upload images
+    images = []
+    alts = image_alts or [""] * len(image_urls)
+
+    for i, url in enumerate(image_urls[:4]):
+        response = httpx.get(url, follow_redirects=True)
+        response.raise_for_status()
+
+        # Upload to blob storage
+        upload = client.upload_blob(response.content)
+        images.append(
+            models.AppBskyEmbedImages.Image(
+                alt=alts[i] if i < len(alts) else "",
+                image=upload.blob,
+            )
+        )
+
+    # Create record with media embed
+    return models.AppBskyEmbedRecordWithMedia.Main(
+        record=models.AppBskyEmbedRecord.Main(record=quoted_ref),
+        media=models.AppBskyEmbedImages.Main(images=images),
+    )
+
+
+def _send_images(
+    text: str,
+    image_urls: list[str],
+    image_alts: list[str] | None,
+    facets,
+    reply_ref,
+    client,
+):
+    """Send post with images using the client's send_images method."""
+    import httpx
+
+    # Ensure alt_texts has same length as images
+    if image_alts is None:
+        image_alts = [""] * len(image_urls)
+    elif len(image_alts) < len(image_urls):
+        image_alts.extend([""] * (len(image_urls) - len(image_alts)))
+
+    image_data = []
+    alts = []
+    for i, url in enumerate(image_urls[:4]):  # Max 4 images
+        # Download image (follow redirects)
+        response = httpx.get(url, follow_redirects=True)
+        response.raise_for_status()
+
+        image_data.append(response.content)
+        alts.append(image_alts[i] if i < len(image_alts) else "")
+
+    # Send post with images
+    # Note: send_images doesn't support facets or reply_to directly
+    # So we need to use send_post with manual image upload if we have facets or replies
+    # Since we always create facets now (for URL auto-detection), we'll always use this path
+    if facets or reply_ref:
+        # Manual image upload
+        images = []
+        for i, data in enumerate(image_data):
+            upload = client.upload_blob(data)
+            images.append(
+                models.AppBskyEmbedImages.Image(
+                    alt=alts[i],
+                    image=upload.blob,
+                )
+            )
+
+        embed = models.AppBskyEmbedImages.Main(images=images)
+        post = client.send_post(
+            text=text,
+            facets=facets if facets else None,
+            embed=embed,
+            reply_to=reply_ref,
+        )
+    else:
+        # Use simple send_images
+        post = client.send_images(
+            text=text,
+            images=image_data,
+            image_alts=alts,
+        )
+
+    return PostResult(
+        success=True,
+        uri=post.uri,
+        cid=post.cid,
+        text=text,
+        created_at=datetime.now().isoformat(),
+        error=None,
+    )
+
+
+def create_thread(posts: list[ThreadPost]) -> ThreadResult:
+    """Create a thread of posts with automatic linking.
+
+    Args:
+        posts: List of posts to create as a thread. First post is the root.
+    """
+    if not posts:
+        return ThreadResult(
+            success=False,
+            thread_uri=None,
+            post_uris=[],
+            post_count=0,
+            error="No posts provided",
+        )
+
+    try:
+        post_uris = []
+        root_uri = None
+        parent_uri = None
+
+        for i, post_data in enumerate(posts):
+            # First post is the root
+            if i == 0:
+                result = create_post(
+                    text=post_data["text"],
+                    images=post_data.get("images"),
+                    image_alts=post_data.get("image_alts"),
+                    links=post_data.get("links"),
+                    mentions=post_data.get("mentions"),
+                    quote=post_data.get("quote"),
+                )
+
+                if not result["success"]:
+                    return ThreadResult(
+                        success=False,
+                        thread_uri=None,
+                        post_uris=post_uris,
+                        post_count=len(post_uris),
+                        error=f"Failed to create root post: {result['error']}",
+                    )
+
+                root_uri = result["uri"]
+                parent_uri = root_uri
+                post_uris.append(root_uri)
+
+                # Small delay to ensure post is indexed
+                time.sleep(0.5)
+            else:
+                # Subsequent posts reply to the previous one
+                result = create_post(
+                    text=post_data["text"],
+                    images=post_data.get("images"),
+                    image_alts=post_data.get("image_alts"),
+                    links=post_data.get("links"),
+                    mentions=post_data.get("mentions"),
+                    quote=post_data.get("quote"),
+                    reply_to=parent_uri,
+                    reply_root=root_uri,
+                )
+
+                if not result["success"]:
+                    return ThreadResult(
+                        success=False,
+                        thread_uri=root_uri,
+                        post_uris=post_uris,
+                        post_count=len(post_uris),
+                        error=f"Failed to create post {i + 1}: {result['error']}",
+                    )
+
+                parent_uri = result["uri"]
+                post_uris.append(parent_uri)
+
+                # Small delay between posts
+                if i < len(posts) - 1:
+                    time.sleep(0.5)
+
+        return ThreadResult(
+            success=True,
+            thread_uri=root_uri,
+            post_uris=post_uris,
+            post_count=len(post_uris),
+            error=None,
+        )
+
+    except Exception as e:
+        return ThreadResult(
+            success=False,
+            thread_uri=None,
+            post_uris=post_uris,
+            post_count=len(post_uris),
+            error=str(e),
+        )
diff --git a/examples/atproto_mcp/src/atproto_mcp/_atproto/_profile.py b/examples/atproto_mcp/src/atproto_mcp/_atproto/_profile.py
new file mode 100644
index 0000000..956ae54
--- /dev/null
+++ b/examples/atproto_mcp/src/atproto_mcp/_atproto/_profile.py
@@ -0,0 +1,33 @@
+"""Profile-related operations."""
+
+from atproto_mcp.types import ProfileInfo
+
+from ._client import get_client
+
+
+def get_profile_info() -> ProfileInfo:
+    """Get profile information for the authenticated user."""
+    try:
+        client = get_client()
+        profile = client.get_profile(client.me.did)
+        return ProfileInfo(
+            connected=True,
+            handle=profile.handle,
+            display_name=profile.display_name,
+            did=client.me.did,
+            followers=profile.followers_count,
+            following=profile.follows_count,
+            posts=profile.posts_count,
+            error=None,
+        )
+    except Exception as e:
+        return ProfileInfo(
+            connected=False,
+            handle=None,
+            display_name=None,
+            did=None,
+            followers=None,
+            following=None,
+            posts=None,
+            error=str(e),
+        )
diff --git a/examples/atproto_mcp/src/atproto_mcp/_atproto/_read.py b/examples/atproto_mcp/src/atproto_mcp/_atproto/_read.py
new file mode 100644
index 0000000..189185a
--- /dev/null
+++ b/examples/atproto_mcp/src/atproto_mcp/_atproto/_read.py
@@ -0,0 +1,124 @@
+"""Read-only operations for timeline, search, and notifications."""
+
+from atproto_mcp.types import (
+    Notification,
+    NotificationsResult,
+    Post,
+    SearchResult,
+    TimelineResult,
+)
+
+from ._client import get_client
+
+
+def fetch_timeline(limit: int = 10) -> TimelineResult:
+    """Fetch the authenticated user's timeline."""
+    try:
+        client = get_client()
+        timeline = client.get_timeline(limit=limit)
+
+        posts = []
+        for feed_view in timeline.feed:
+            post = feed_view.post
+            posts.append(
+                Post(
+                    uri=post.uri,
+                    cid=post.cid,
+                    text=post.record.text if hasattr(post.record, "text") else "",
+                    author=post.author.handle,
+                    created_at=post.record.created_at,
+                    likes=post.like_count or 0,
+                    reposts=post.repost_count or 0,
+                    replies=post.reply_count or 0,
+                )
+            )
+
+        return TimelineResult(
+            success=True,
+            posts=posts,
+            count=len(posts),
+            error=None,
+        )
+    except Exception as e:
+        return TimelineResult(
+            success=False,
+            posts=[],
+            count=0,
+            error=str(e),
+        )
+
+
+def search_for_posts(query: str, limit: int = 10) -> SearchResult:
+    """Search for posts containing specific text."""
+    try:
+        client = get_client()
+        search_results = client.app.bsky.feed.search_posts(
+            params={"q": query, "limit": limit}
+        )
+
+        posts = []
+        for post in search_results.posts:
+            posts.append(
+                Post(
+                    uri=post.uri,
+                    cid=post.cid,
+                    text=post.record.text if hasattr(post.record, "text") else "",
+                    author=post.author.handle,
+                    created_at=post.record.created_at,
+                    likes=post.like_count or 0,
+                    reposts=post.repost_count or 0,
+                    replies=post.reply_count or 0,
+                )
+            )
+
+        return SearchResult(
+            success=True,
+            query=query,
+            posts=posts,
+            count=len(posts),
+            error=None,
+        )
+    except Exception as e:
+        return SearchResult(
+            success=False,
+            query=query,
+            posts=[],
+            count=0,
+            error=str(e),
+        )
+
+
+def fetch_notifications(limit: int = 10) -> NotificationsResult:
+    """Fetch recent notifications."""
+    try:
+        client = get_client()
+        notifs = client.app.bsky.notification.list_notifications(
+            params={"limit": limit}
+        )
+
+        notifications = []
+        for notif in notifs.notifications:
+            notifications.append(
+                Notification(
+                    uri=notif.uri,
+                    cid=notif.cid,
+                    author=notif.author.handle,
+                    reason=notif.reason,
+                    is_read=notif.is_read,
+                    indexed_at=notif.indexed_at,
+                )
+            )
+
+        return NotificationsResult(
+            success=True,
+            notifications=notifications,
+            count=len(notifications),
+            error=None,
+        )
+    except Exception as e:
+        return NotificationsResult(
+            success=False,
+            notifications=[],
+            count=0,
+            error=str(e),
+        )
diff --git a/examples/atproto_mcp/src/atproto_mcp/_atproto/_social.py b/examples/atproto_mcp/src/atproto_mcp/_atproto/_social.py
new file mode 100644
index 0000000..87bd029
--- /dev/null
+++ b/examples/atproto_mcp/src/atproto_mcp/_atproto/_social.py
@@ -0,0 +1,108 @@
+"""Social actions like follow, like, and repost."""
+
+from atproto_mcp.types import FollowResult, LikeResult, RepostResult
+
+from ._client import get_client
+
+
+def follow_user_by_handle(handle: str) -> FollowResult:
+    """Follow a user by their handle."""
+    try:
+        client = get_client()
+        # Search for the user to get their DID
+        results = client.app.bsky.actor.search_actors(params={"q": handle, "limit": 1})
+        if not results.actors:
+            return FollowResult(
+                success=False,
+                did=None,
+                handle=None,
+                uri=None,
+                error=f"User @{handle} not found",
+            )
+
+        actor = results.actors[0]
+        # Create the follow
+        follow = client.follow(actor.did)
+        return FollowResult(
+            success=True,
+            did=actor.did,
+            handle=actor.handle,
+            uri=follow.uri,
+            error=None,
+        )
+    except Exception as e:
+        return FollowResult(
+            success=False,
+            did=None,
+            handle=None,
+            uri=None,
+            error=str(e),
+        )
+
+
+def like_post_by_uri(uri: str) -> LikeResult:
+    """Like a post by its AT URI."""
+    try:
+        client = get_client()
+        # Parse the URI to get the components
+        # URI format: at://did:plc:xxx/app.bsky.feed.post/yyy
+        parts = uri.replace("at://", "").split("/")
+        if len(parts) != 3 or parts[1] != "app.bsky.feed.post":
+            raise ValueError("Invalid post URI format")
+
+        # Get the post to retrieve its CID
+        post = client.app.bsky.feed.get_posts(params={"uris": [uri]})
+        if not post.posts:
+            raise ValueError("Post not found")
+
+        cid = post.posts[0].cid
+
+        # Now like the post with both URI and CID
+        like = client.like(uri, cid)
+        return LikeResult(
+            success=True,
+            liked_uri=uri,
+            like_uri=like.uri,
+            error=None,
+        )
+    except Exception as e:
+        return LikeResult(
+            success=False,
+            liked_uri=None,
+            like_uri=None,
+            error=str(e),
+        )
+
+
+def repost_by_uri(uri: str) -> RepostResult:
+    """Repost a post by its AT URI."""
+    try:
+        client = get_client()
+        # Parse the URI to get the components
+        # URI format: at://did:plc:xxx/app.bsky.feed.post/yyy
+        parts = uri.replace("at://", "").split("/")
+        if len(parts) != 3 or parts[1] != "app.bsky.feed.post":
+            raise ValueError("Invalid post URI format")
+
+        # Get the post to retrieve its CID
+        post = client.app.bsky.feed.get_posts(params={"uris": [uri]})
+        if not post.posts:
+            raise ValueError("Post not found")
+
+        cid = post.posts[0].cid
+
+        # Now repost with both URI and CID
+        repost = client.repost(uri, cid)
+        return RepostResult(
+            success=True,
+            reposted_uri=uri,
+            repost_uri=repost.uri,
+            error=None,
+        )
+    except Exception as e:
+        return RepostResult(
+            success=False,
+            reposted_uri=None,
+            repost_uri=None,
+            error=str(e),
+        )
diff --git a/examples/atproto_mcp/src/atproto_mcp/py.typed b/examples/atproto_mcp/src/atproto_mcp/py.typed
new file mode 100644
index 0000000..e69de29
diff --git a/examples/atproto_mcp/src/atproto_mcp/server.py b/examples/atproto_mcp/src/atproto_mcp/server.py
new file mode 100644
index 0000000..4f9ef4e
--- /dev/null
+++ b/examples/atproto_mcp/src/atproto_mcp/server.py
@@ -0,0 +1,149 @@
+"""ATProto MCP Server - Public API exposing Bluesky tools and resources."""
+
+from typing import Annotated
+
+from pydantic import Field
+
+from atproto_mcp import _atproto
+from atproto_mcp.settings import settings
+from atproto_mcp.types import (
+    FollowResult,
+    LikeResult,
+    NotificationsResult,
+    PostResult,
+    ProfileInfo,
+    RepostResult,
+    RichTextLink,
+    RichTextMention,
+    SearchResult,
+    ThreadPost,
+    ThreadResult,
+    TimelineResult,
+)
+from fastmcp import FastMCP
+
+atproto_mcp = FastMCP("ATProto MCP Server")
+
+
+# Resources - read-only operations
+@atproto_mcp.resource("atproto://profile/status")
+def atproto_status() -> ProfileInfo:
+    """Check the status of the ATProto connection and current user profile."""
+    return _atproto.get_profile_info()
+
+
+@atproto_mcp.resource("atproto://timeline")
+def get_timeline() -> TimelineResult:
+    """Get the authenticated user's timeline feed."""
+    return _atproto.fetch_timeline(settings.atproto_timeline_default_limit)
+
+
+@atproto_mcp.resource("atproto://notifications")
+def get_notifications() -> NotificationsResult:
+    """Get recent notifications for the authenticated user."""
+    return _atproto.fetch_notifications(settings.atproto_notifications_default_limit)
+
+
+# Tools - actions that modify state
+@atproto_mcp.tool
+def post(
+    text: Annotated[
+        str, Field(max_length=300, description="The text content of the post")
+    ],
+    images: Annotated[
+        list[str] | None,
+        Field(max_length=4, description="URLs of images to attach (max 4)"),
+    ] = None,
+    image_alts: Annotated[
+        list[str] | None, Field(description="Alt text for each image")
+    ] = None,
+    links: Annotated[
+        list[RichTextLink] | None, Field(description="Links to embed in the text")
+    ] = None,
+    mentions: Annotated[
+        list[RichTextMention] | None, Field(description="User mentions to embed")
+    ] = None,
+    reply_to: Annotated[
+        str | None, Field(description="AT URI of post to reply to")
+    ] = None,
+    reply_root: Annotated[
+        str | None, Field(description="AT URI of thread root (defaults to reply_to)")
+    ] = None,
+    quote: Annotated[str | None, Field(description="AT URI of post to quote")] = None,
+) -> PostResult:
+    """Create a post with optional rich features like images, quotes, replies, and rich text.
+
+    Examples:
+        - Simple post: post("Hello world!")
+        - With image: post("Check this out!", images=["https://example.com/img.jpg"])
+        - Reply: post("I agree!", reply_to="at://did/app.bsky.feed.post/123")
+        - Quote: post("Great point!", quote="at://did/app.bsky.feed.post/456")
+        - Rich text: post("Check out example.com", links=[{"text": "example.com", "url": "https://example.com"}])
+    """
+    return _atproto.create_post(
+        text, images, image_alts, links, mentions, reply_to, reply_root, quote
+    )
+
+
+@atproto_mcp.tool
+def follow(
+    handle: Annotated[
+        str,
+        Field(
+            description="The handle of the user to follow (e.g., 'user.bsky.social')"
+        ),
+    ],
+) -> FollowResult:
+    """Follow a user by their handle."""
+    return _atproto.follow_user_by_handle(handle)
+
+
+@atproto_mcp.tool
+def like(
+    uri: Annotated[str, Field(description="The AT URI of the post to like")],
+) -> LikeResult:
+    """Like a post by its AT URI."""
+    return _atproto.like_post_by_uri(uri)
+
+
+@atproto_mcp.tool
+def repost(
+    uri: Annotated[str, Field(description="The AT URI of the post to repost")],
+) -> RepostResult:
+    """Repost a post by its AT URI."""
+    return _atproto.repost_by_uri(uri)
+
+
+@atproto_mcp.tool
+def search(
+    query: Annotated[str, Field(description="Search query for posts")],
+    limit: Annotated[
+        int, Field(ge=1, le=100, description="Number of results to return")
+    ] = settings.atproto_search_default_limit,
+) -> SearchResult:
+    """Search for posts containing specific text."""
+    return _atproto.search_for_posts(query, limit)
+
+
+@atproto_mcp.tool
+def create_thread(
+    posts: Annotated[
+        list[ThreadPost],
+        Field(
+            description="List of posts to create as a thread. Each post can have text, images, links, mentions, and quotes."
+        ),
+    ],
+) -> ThreadResult:
+    """Create a thread of posts with automatic linking.
+
+    The first post becomes the root of the thread, and each subsequent post
+    replies to the previous one, maintaining the thread structure.
+
+    Example:
+        create_thread([
+            {"text": "Starting a thread about Python 🧵"},
+            {"text": "Python is great for rapid development"},
+            {"text": "And the ecosystem is amazing!", "images": ["https://example.com/python.jpg"]}
+        ])
+    """
+    return _atproto.create_thread(posts)
diff --git a/examples/atproto_mcp/src/atproto_mcp/settings.py b/examples/atproto_mcp/src/atproto_mcp/settings.py
new file mode 100644
index 0000000..9eed408
--- /dev/null
+++ b/examples/atproto_mcp/src/atproto_mcp/settings.py
@@ -0,0 +1,17 @@
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=[".env"], extra="ignore")
+
+    atproto_handle: str = Field(default=...)
+    atproto_password: str = Field(default=...)
+    atproto_pds_url: str = Field(default="https://bsky.social")
+
+    atproto_notifications_default_limit: int = Field(default=10)
+    atproto_timeline_default_limit: int = Field(default=10)
+    atproto_search_default_limit: int = Field(default=10)
+
+
+settings = Settings()
diff --git a/examples/atproto_mcp/src/atproto_mcp/types.py b/examples/atproto_mcp/src/atproto_mcp/types.py
new file mode 100644
index 0000000..e95fc21
--- /dev/null
+++ b/examples/atproto_mcp/src/atproto_mcp/types.py
@@ -0,0 +1,142 @@
+"""Type definitions for ATProto MCP server."""
+
+from typing import TypedDict
+
+
+class ProfileInfo(TypedDict):
+    """Profile information response."""
+
+    connected: bool
+    handle: str | None
+    display_name: str | None
+    did: str | None
+    followers: int | None
+    following: int | None
+    posts: int | None
+    error: str | None
+
+
+class PostResult(TypedDict):
+    """Result of creating a post."""
+
+    success: bool
+    uri: str | None
+    cid: str | None
+    text: str | None
+    created_at: str | None
+    error: str | None
+
+
+class Post(TypedDict):
+    """A single post."""
+
+    author: str
+    text: str | None
+    created_at: str | None
+    likes: int
+    reposts: int
+    replies: int
+    uri: str
+    cid: str
+
+
+class TimelineResult(TypedDict):
+    """Timeline fetch result."""
+
+    success: bool
+    count: int
+    posts: list[Post]
+    error: str | None
+
+
+class SearchResult(TypedDict):
+    """Search result."""
+
+    success: bool
+    query: str
+    count: int
+    posts: list[Post]
+    error: str | None
+
+
+class Notification(TypedDict):
+    """A single notification."""
+
+    reason: str
+    author: str | None
+    is_read: bool
+    indexed_at: str
+    uri: str
+    cid: str
+
+
+class NotificationsResult(TypedDict):
+    """Notifications fetch result."""
+
+    success: bool
+    count: int
+    notifications: list[Notification]
+    error: str | None
+
+
+class FollowResult(TypedDict):
+    """Result of following a user."""
+
+    success: bool
+    handle: str | None
+    did: str | None
+    uri: str | None
+    error: str | None
+
+
+class LikeResult(TypedDict):
+    """Result of liking a post."""
+
+    success: bool
+    liked_uri: str | None
+    like_uri: str | None
+    error: str | None
+
+
+class RepostResult(TypedDict):
+    """Result of reposting."""
+
+    success: bool
+    reposted_uri: str | None
+    repost_uri: str | None
+    error: str | None
+
+
+class RichTextLink(TypedDict):
+    """A link in rich text."""
+
+    text: str
+    url: str
+
+
+class RichTextMention(TypedDict):
+    """A mention in rich text."""
+
+    handle: str
+    display_text: str | None
+
+
+class ThreadPost(TypedDict, total=False):
+    """A post in a thread."""
+
+    text: str  # Required
+    images: list[str] | None
+    image_alts: list[str] | None
+    links: list[RichTextLink] | None
+    mentions: list[RichTextMention] | None
+    quote: str | None
+
+
+class ThreadResult(TypedDict):
+    """Result of creating a thread."""
+
+    success: bool
+    thread_uri: str | None  # URI of the first post
+    post_uris: list[str]
+    post_count: int
+    error: str | None
diff --git a/examples/auth/authkit/README.md b/examples/auth/authkit/README.md
new file mode 100644
index 0000000..8c4b8a6
--- /dev/null
+++ b/examples/auth/authkit/README.md
@@ -0,0 +1,36 @@
+# AuthKit Example
+
+Protects a FastMCP server with WorkOS AuthKit. The server binds the JWT
+`aud` claim to its own resource URL automatically — you just paste that same
+URL into the WorkOS Dashboard as a resource indicator.
+
+## WorkOS Dashboard setup
+
+In the WorkOS Dashboard for your project, go to **Connect → Configuration** and:
+
+1. Under **MCP Auth**, enable **Dynamic Client Registration** (or **Client ID
+   Metadata Document** if your MCP client supports it).
+2. Under **MCP resource indicators**, add `http://127.0.0.1:8000/mcp` as a
+   valid resource indicator.
+
+## Running
+
+1. Set your AuthKit domain:
+
+   ```bash
+   export AUTHKIT_DOMAIN="https://your-app.authkit.app"
+   ```
+
+2. Start the server. It logs the resource URL it's validating against —
+   that's the URL that must match your dashboard resource indicator:
+
+   ```bash
+   python server.py
+   ```
+
+3. In another terminal, run the client. Your browser will open for AuthKit
+   authentication:
+
+   ```bash
+   python client.py
+   ```
diff --git a/examples/auth/authkit/client.py b/examples/auth/authkit/client.py
new file mode 100644
index 0000000..562637b
--- /dev/null
+++ b/examples/auth/authkit/client.py
@@ -0,0 +1,33 @@
+"""OAuth client example for connecting to FastMCP servers.
+
+This example demonstrates how to connect to an OAuth-protected FastMCP server.
+
+To run:
+    python client.py
+"""
+
+import asyncio
+
+from fastmcp.client import Client
+from fastmcp.client.auth import OAuth
+
+SERVER_URL = "http://127.0.0.1:8000/mcp"
+
+
+async def main():
+    # AuthKit defaults DCR clients to client_secret_basic, which conflicts
+    # with how MCP SDKs send credentials. Force "none" to register as a
+    # public client and avoid token exchange errors.
+    auth = OAuth(additional_client_metadata={"token_endpoint_auth_method": "none"})
+    async with Client(SERVER_URL, auth=auth) as client:
+        assert await client.ping()
+        print("Successfully authenticated!")
+
+        tools = await client.list_tools()
+        print(f"Available tools ({len(tools)}):")
+        for tool in tools:
+            print(f"   - {tool.name}: {tool.description}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/auth/authkit/server.py b/examples/auth/authkit/server.py
new file mode 100644
index 0000000..7611ccd
--- /dev/null
+++ b/examples/auth/authkit/server.py
@@ -0,0 +1,34 @@
+"""AuthKit server example for FastMCP.
+
+Demonstrates an MCP server secured by WorkOS AuthKit. FastMCP binds the JWT
+audience to this server's resource URL automatically; you configure the same
+URL as an MCP resource indicator in the WorkOS Dashboard.
+
+Required environment variables:
+- AUTHKIT_DOMAIN: Your AuthKit domain (e.g., "https://your-app.authkit.app")
+
+To run:
+    python server.py
+"""
+
+import os
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.workos import AuthKitProvider
+
+auth = AuthKitProvider(
+    authkit_domain=os.getenv("AUTHKIT_DOMAIN") or "",
+    base_url="http://127.0.0.1:8000",
+)
+
+mcp = FastMCP("AuthKit Example Server", auth=auth)
+
+
+@mcp.tool
+def echo(message: str) -> str:
+    """Echo the provided message."""
+    return message
+
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
diff --git a/examples/auth/aws_oauth/README.md b/examples/auth/aws_oauth/README.md
new file mode 100644
index 0000000..c4e25b1
--- /dev/null
+++ b/examples/auth/aws_oauth/README.md
@@ -0,0 +1,47 @@
+# AWS Cognito OAuth Example
+
+Demonstrates FastMCP server protection with AWS Cognito OAuth.
+
+## Setup
+
+1. Create an AWS Cognito User Pool and App Client:
+   - Go to [AWS Cognito Console](https://console.aws.amazon.com/cognito/)
+   - Create a new User Pool or use an existing one
+   - Create an App Client in your User Pool
+   - Configure the App Client settings:
+     - Enable "Authorization code grant" flow
+     - Add Callback URL: `http://127.0.0.1:8000/auth/callback`
+     - Configure OAuth scopes (at minimum: `openid`)
+   - Note your User Pool ID, App Client ID, Client Secret, and Cognito Domain Prefix
+
+2. Set environment variables:
+
+   ```bash
+   export FASTMCP_SERVER_AUTH_AWS_COGNITO_USER_POOL_ID="your-user-pool-id"
+   export FASTMCP_SERVER_AUTH_AWS_COGNITO_AWS_REGION="your-aws-region"
+   export FASTMCP_SERVER_AUTH_AWS_COGNITO_CLIENT_ID="your-app-client-id"
+   export FASTMCP_SERVER_AUTH_AWS_COGNITO_CLIENT_SECRET="your-app-client-secret"
+   ```
+
+   Or create a `.env` file:
+
+   ```env
+   FASTMCP_SERVER_AUTH_AWS_COGNITO_USER_POOL_ID=your-user-pool-id
+   FASTMCP_SERVER_AUTH_AWS_COGNITO_AWS_REGION=your-aws-region
+   FASTMCP_SERVER_AUTH_AWS_COGNITO_CLIENT_ID=your-app-client-id
+   FASTMCP_SERVER_AUTH_AWS_COGNITO_CLIENT_SECRET=your-app-client-secret
+   ```
+
+3. Run the server:
+
+   ```bash
+   python server.py
+   ```
+
+4. In another terminal, run the client:
+
+   ```bash
+   python client.py
+   ```
+
+The client will open your browser for AWS Cognito authentication.
diff --git a/examples/auth/aws_oauth/client.py b/examples/auth/aws_oauth/client.py
new file mode 100644
index 0000000..afcf54f
--- /dev/null
+++ b/examples/auth/aws_oauth/client.py
@@ -0,0 +1,42 @@
+"""OAuth client example for connecting to FastMCP servers.
+
+This example demonstrates how to connect to an OAuth-protected FastMCP server.
+
+To run:
+    python client.py
+"""
+
+import asyncio
+
+from fastmcp.client import Client
+
+SERVER_URL = "http://127.0.0.1:8000/mcp"
+
+
+async def main():
+    try:
+        async with Client(SERVER_URL, auth="oauth") as client:
+            assert await client.ping()
+            print("✅ Successfully authenticated!")
+
+            tools = await client.list_tools()
+            print(f"🔧 Available tools ({len(tools)}):")
+            for tool in tools:
+                print(f"   - {tool.name}: {tool.description}")
+
+            # Test the protected tool
+            print("🔒 Calling protected tool: get_access_token_claims")
+            result = await client.call_tool("get_access_token_claims")
+            user_data = result.data
+            print("📄 Available access token claims:")
+            print(f"   - sub: {user_data.get('sub', 'N/A')}")
+            print(f"   - username: {user_data.get('username', 'N/A')}")
+            print(f"   - cognito:groups: {user_data.get('cognito:groups', [])}")
+
+    except Exception as e:
+        print(f"❌ Authentication failed: {e}")
+        raise
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/auth/aws_oauth/requirements.txt b/examples/auth/aws_oauth/requirements.txt
new file mode 100644
index 0000000..044c95a
--- /dev/null
+++ b/examples/auth/aws_oauth/requirements.txt
@@ -0,0 +1,2 @@
+fastmcp
+python-dotenv
diff --git a/examples/auth/aws_oauth/server.py b/examples/auth/aws_oauth/server.py
new file mode 100644
index 0000000..2611643
--- /dev/null
+++ b/examples/auth/aws_oauth/server.py
@@ -0,0 +1,59 @@
+"""AWS Cognito OAuth server example for FastMCP.
+
+This example demonstrates how to protect a FastMCP server with AWS Cognito.
+
+Required environment variables:
+- FASTMCP_SERVER_AUTH_AWS_COGNITO_USER_POOL_ID: Your AWS Cognito User Pool ID
+- FASTMCP_SERVER_AUTH_AWS_COGNITO_AWS_REGION: Your AWS region (optional, defaults to eu-central-1)
+- FASTMCP_SERVER_AUTH_AWS_COGNITO_CLIENT_ID: Your Cognito app client ID
+- FASTMCP_SERVER_AUTH_AWS_COGNITO_CLIENT_SECRET: Your Cognito app client secret
+
+To run:
+    python server.py
+"""
+
+import logging
+import os
+
+from dotenv import load_dotenv
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.aws import AWSCognitoProvider
+from fastmcp.server.dependencies import get_access_token
+
+logging.basicConfig(level=logging.DEBUG)
+
+load_dotenv(".env", override=True)
+
+auth = AWSCognitoProvider(
+    user_pool_id=os.getenv("FASTMCP_SERVER_AUTH_AWS_COGNITO_USER_POOL_ID") or "",
+    aws_region=os.getenv("FASTMCP_SERVER_AUTH_AWS_COGNITO_AWS_REGION")
+    or "eu-central-1",
+    client_id=os.getenv("FASTMCP_SERVER_AUTH_AWS_COGNITO_CLIENT_ID") or "",
+    client_secret=os.getenv("FASTMCP_SERVER_AUTH_AWS_COGNITO_CLIENT_SECRET") or "",
+    base_url="http://127.0.0.1:8000",
+    # redirect_path="/custom/callback"
+)
+
+mcp = FastMCP("AWS Cognito OAuth Example Server", auth=auth)
+
+
+@mcp.tool
+def echo(message: str) -> str:
+    """Echo the provided message."""
+    return message
+
+
+@mcp.tool
+async def get_access_token_claims() -> dict:
+    """Get the authenticated user's access token claims."""
+    token = get_access_token()
+    return {
+        "sub": token.claims.get("sub"),
+        "username": token.claims.get("username"),
+        "cognito:groups": token.claims.get("cognito:groups", []),
+    }
+
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
diff --git a/examples/auth/azure_oauth/README.md b/examples/auth/azure_oauth/README.md
new file mode 100644
index 0000000..98d9ae7
--- /dev/null
+++ b/examples/auth/azure_oauth/README.md
@@ -0,0 +1,51 @@
+# Azure (Microsoft Entra) OAuth Example
+
+This example demonstrates how to use the Azure OAuth provider with FastMCP servers.
+
+## Setup
+
+### 1. Azure App Registration
+
+1. Go to [Azure Portal → App registrations](https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade)
+2. Click "New registration" and configure:
+   - Name: Your app name
+   - Supported account types: Choose based on your needs
+   - Redirect URI: `http://127.0.0.1:8000/auth/callback` (Web platform)
+3. After creation, go to "Certificates & secrets" → "New client secret"
+4. Note these values from the Overview page:
+   - Application (client) ID
+   - Directory (tenant) ID
+
+### 2. Environment Variables
+
+Create a `.env` file:
+
+```bash
+# Required
+AZURE_CLIENT_ID=your-application-client-id
+AZURE_CLIENT_SECRET=your-client-secret-value
+AZURE_TENANT_ID=your-tenant-id  # From Azure Portal Overview page
+```
+
+### 3. Run the Example
+
+Start the server:
+
+```bash
+uv run python server.py
+```
+
+Test with client:
+
+```bash
+uv run python client.py
+```
+
+## Tenant Configuration
+
+The `tenant_id` parameter is **required** and controls which accounts can authenticate:
+
+- **Your tenant ID**: Single organization (most common)
+- **`organizations`**: Any work/school account
+- **`consumers`**: Personal Microsoft accounts only
+
diff --git a/examples/auth/azure_oauth/client.py b/examples/auth/azure_oauth/client.py
new file mode 100644
index 0000000..5f1f39b
--- /dev/null
+++ b/examples/auth/azure_oauth/client.py
@@ -0,0 +1,32 @@
+"""OAuth client example for connecting to FastMCP servers.
+
+This example demonstrates how to connect to an OAuth-protected FastMCP server.
+
+To run:
+    python client.py
+"""
+
+import asyncio
+
+from fastmcp.client import Client
+
+SERVER_URL = "http://127.0.0.1:8000/mcp"
+
+
+async def main():
+    try:
+        async with Client(SERVER_URL, auth="oauth") as client:
+            assert await client.ping()
+            print("✅ Successfully authenticated!")
+
+            tools = await client.list_tools()
+            print(f"🔧 Available tools ({len(tools)}):")
+            for tool in tools:
+                print(f"   - {tool.name}: {tool.description}")
+    except Exception as e:
+        print(f"❌ Authentication failed: {e}")
+        raise
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/auth/azure_oauth/server.py b/examples/auth/azure_oauth/server.py
new file mode 100644
index 0000000..e0c9e79
--- /dev/null
+++ b/examples/auth/azure_oauth/server.py
@@ -0,0 +1,44 @@
+"""Azure (Microsoft Entra) OAuth server example for FastMCP.
+
+This example demonstrates how to protect a FastMCP server with Azure/Microsoft OAuth.
+
+Required environment variables:
+- AZURE_CLIENT_ID: Your Azure application (client) ID
+- AZURE_CLIENT_SECRET: Your Azure client secret
+- AZURE_TENANT_ID: Tenant ID
+  Options: "organizations" (work/school), "consumers" (personal), or specific tenant ID
+- AZURE_REQUIRED_SCOPES: At least one scope required (e.g., "read" or "read,write")
+  These must match scope names created under "Expose an API" in your Azure App registration
+
+To run:
+    python server.py
+"""
+
+import os
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.azure import AzureProvider
+
+auth = AzureProvider(
+    client_id=os.getenv("FASTMCP_SERVER_AUTH_AZURE_CLIENT_ID") or "",
+    client_secret=os.getenv("FASTMCP_SERVER_AUTH_AZURE_CLIENT_SECRET") or "",
+    tenant_id=os.getenv("FASTMCP_SERVER_AUTH_AZURE_TENANT_ID")
+    or "",  # Required for single-tenant apps - get from Azure Portal
+    base_url="http://127.0.0.1:8000",
+    required_scopes=["read"],
+    # required_scopes is automatically loaded from FASTMCP_SERVER_AUTH_AZURE_REQUIRED_SCOPES
+    # At least one scope is required - use unprefixed scope names from your Azure App (e.g., ["read", "write"])
+    # redirect_path="/auth/callback",  # Default path - change if using a different callback URL
+)
+
+mcp = FastMCP("Azure OAuth Example Server", auth=auth)
+
+
+@mcp.tool
+def echo(message: str) -> str:
+    """Echo the provided message."""
+    return message
+
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
diff --git a/examples/auth/clerk_oauth/README.md b/examples/auth/clerk_oauth/README.md
new file mode 100644
index 0000000..9a79ff5
--- /dev/null
+++ b/examples/auth/clerk_oauth/README.md
@@ -0,0 +1,36 @@
+# Clerk OAuth Example
+
+Demonstrates FastMCP server protection with Clerk OAuth.
+
+## Setup
+
+1. Create a Clerk OAuth Application:
+   - Go to [Clerk Dashboard](https://dashboard.clerk.com/)
+   - Create or select an application
+   - Go to Developers > OAuth Applications
+   - Create an OAuth application
+   - Add Authorized redirect URI: `http://127.0.0.1:8000/auth/callback`
+   - Copy the Client ID and Client Secret
+   - Note your instance domain (e.g., `saving-primate-16.clerk.accounts.dev`)
+
+2. Set environment variables:
+
+   ```bash
+   export FASTMCP_SERVER_AUTH_CLERK_DOMAIN="your-instance.clerk.accounts.dev"
+   export FASTMCP_SERVER_AUTH_CLERK_CLIENT_ID="your-clerk-client-id"
+   export FASTMCP_SERVER_AUTH_CLERK_CLIENT_SECRET="your-clerk-client-secret"
+   ```
+
+3. Run the server:
+
+   ```bash
+   python server.py
+   ```
+
+4. In another terminal, run the client:
+
+   ```bash
+   python client.py
+   ```
+
+The client will open your browser for Clerk authentication.
diff --git a/examples/auth/clerk_oauth/client.py b/examples/auth/clerk_oauth/client.py
new file mode 100644
index 0000000..d9d44c9
--- /dev/null
+++ b/examples/auth/clerk_oauth/client.py
@@ -0,0 +1,33 @@
+"""OAuth client example for connecting to a Clerk-protected FastMCP server.
+
+This example demonstrates how to connect to an OAuth-protected FastMCP server
+using Clerk as the identity provider.
+
+To run:
+    python client.py
+"""
+
+import asyncio
+
+from fastmcp.client import Client
+
+SERVER_URL = "http://127.0.0.1:8000/mcp"
+
+
+async def main():
+    try:
+        async with Client(SERVER_URL, auth="oauth") as client:
+            assert await client.ping()
+            print("✅ Successfully authenticated!")
+
+            tools = await client.list_tools()
+            print(f"🔧 Available tools ({len(tools)}):")
+            for tool in tools:
+                print(f"   - {tool.name}: {tool.description}")
+    except Exception as e:
+        print(f"❌ Authentication failed: {e}")
+        raise
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/auth/clerk_oauth/server.py b/examples/auth/clerk_oauth/server.py
new file mode 100644
index 0000000..e7d0807
--- /dev/null
+++ b/examples/auth/clerk_oauth/server.py
@@ -0,0 +1,40 @@
+"""Clerk OAuth server example for FastMCP.
+
+This example demonstrates how to protect a FastMCP server with Clerk OAuth.
+
+Required environment variables:
+- FASTMCP_SERVER_AUTH_CLERK_DOMAIN: Your Clerk instance domain
+    (e.g., "saving-primate-16.clerk.accounts.dev")
+- FASTMCP_SERVER_AUTH_CLERK_CLIENT_ID: Your Clerk OAuth client ID
+- FASTMCP_SERVER_AUTH_CLERK_CLIENT_SECRET: Your Clerk OAuth client secret
+
+To run:
+    python server.py
+"""
+
+import os
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.clerk import ClerkProvider
+
+auth = ClerkProvider(
+    domain=os.getenv("FASTMCP_SERVER_AUTH_CLERK_DOMAIN") or "",
+    client_id=os.getenv("FASTMCP_SERVER_AUTH_CLERK_CLIENT_ID") or "",
+    client_secret=os.getenv("FASTMCP_SERVER_AUTH_CLERK_CLIENT_SECRET") or "",
+    base_url="http://127.0.0.1:8000",
+    # redirect_path="/auth/callback",  # Default path - change if using a different callback URL
+    # Optional: specify required scopes (defaults to ["openid", "email", "profile"])
+    # required_scopes=["openid", "email", "profile", "public_metadata"],
+)
+
+mcp = FastMCP("Clerk OAuth Example Server", auth=auth)
+
+
+@mcp.tool
+def echo(message: str) -> str:
+    """Echo the provided message."""
+    return message
+
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
diff --git a/examples/auth/discord_oauth/README.md b/examples/auth/discord_oauth/README.md
new file mode 100644
index 0000000..e757ad8
--- /dev/null
+++ b/examples/auth/discord_oauth/README.md
@@ -0,0 +1,33 @@
+# Discord OAuth Example
+
+Demonstrates FastMCP server protection with Discord OAuth.
+
+## Setup
+
+1. Create a Discord OAuth App:
+   - Go to https://discord.com/developers/applications
+   - Click "New Application" and give it a name
+   - Go to OAuth2 in the left sidebar
+   - Add a Redirect URL: `http://127.0.0.1:8000/auth/callback`
+   - Copy the Client ID and Client Secret
+
+2. Set environment variables:
+
+   ```bash
+   export FASTMCP_SERVER_AUTH_DISCORD_CLIENT_ID="your-client-id"
+   export FASTMCP_SERVER_AUTH_DISCORD_CLIENT_SECRET="your-client-secret"
+   ```
+
+3. Run the server:
+
+   ```bash
+   python server.py
+   ```
+
+4. In another terminal, run the client:
+
+   ```bash
+   python client.py
+   ```
+
+The client will open your browser for Discord authentication.
diff --git a/examples/auth/discord_oauth/client.py b/examples/auth/discord_oauth/client.py
new file mode 100644
index 0000000..880b86f
--- /dev/null
+++ b/examples/auth/discord_oauth/client.py
@@ -0,0 +1,32 @@
+"""Discord OAuth client example for connecting to FastMCP servers.
+
+This example demonstrates how to connect to a Discord OAuth-protected FastMCP server.
+
+To run:
+    python client.py
+"""
+
+import asyncio
+
+from fastmcp.client import Client
+
+SERVER_URL = "http://127.0.0.1:8000/mcp"
+
+
+async def main():
+    try:
+        async with Client(SERVER_URL, auth="oauth") as client:
+            assert await client.ping()
+            print("✅ Successfully authenticated!")
+
+            tools = await client.list_tools()
+            print(f"🔧 Available tools ({len(tools)}):")
+            for tool in tools:
+                print(f"   - {tool.name}: {tool.description}")
+    except Exception as e:
+        print(f"❌ Authentication failed: {e}")
+        raise
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/auth/discord_oauth/server.py b/examples/auth/discord_oauth/server.py
new file mode 100644
index 0000000..1e109b7
--- /dev/null
+++ b/examples/auth/discord_oauth/server.py
@@ -0,0 +1,35 @@
+"""Discord OAuth server example for FastMCP.
+
+This example demonstrates how to protect a FastMCP server with Discord OAuth.
+
+Required environment variables:
+- FASTMCP_SERVER_AUTH_DISCORD_CLIENT_ID: Your Discord OAuth app client ID
+- FASTMCP_SERVER_AUTH_DISCORD_CLIENT_SECRET: Your Discord OAuth app client secret
+
+To run:
+    python server.py
+"""
+
+import os
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.discord import DiscordProvider
+
+auth = DiscordProvider(
+    client_id=os.getenv("FASTMCP_SERVER_AUTH_DISCORD_CLIENT_ID") or "",
+    client_secret=os.getenv("FASTMCP_SERVER_AUTH_DISCORD_CLIENT_SECRET") or "",
+    base_url="http://127.0.0.1:8000",
+    # redirect_path="/auth/callback",  # Default path - change if using a different callback URL
+)
+
+mcp = FastMCP("Discord OAuth Example Server", auth=auth)
+
+
+@mcp.tool
+def echo(message: str) -> str:
+    """Echo the provided message."""
+    return message
+
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
diff --git a/examples/auth/github_oauth/README.md b/examples/auth/github_oauth/README.md
new file mode 100644
index 0000000..dcd5c22
--- /dev/null
+++ b/examples/auth/github_oauth/README.md
@@ -0,0 +1,31 @@
+# GitHub OAuth Example
+
+Demonstrates FastMCP server protection with GitHub OAuth.
+
+## Setup
+
+1. Create a GitHub OAuth App:
+   - Go to GitHub Settings > Developer settings > OAuth Apps
+   - Set Authorization callback URL to: `http://127.0.0.1:8000/auth/callback`
+   - Copy the Client ID and Client Secret
+
+2. Set environment variables:
+
+   ```bash
+   export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID="your-client-id"
+   export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET="your-client-secret"
+   ```
+
+3. Run the server:
+
+   ```bash
+   python server.py
+   ```
+
+4. In another terminal, run the client:
+
+   ```bash
+   python client.py
+   ```
+
+The client will open your browser for GitHub authentication.
diff --git a/examples/auth/github_oauth/client.py b/examples/auth/github_oauth/client.py
new file mode 100644
index 0000000..8722a54
--- /dev/null
+++ b/examples/auth/github_oauth/client.py
@@ -0,0 +1,32 @@
+"""OAuth client example for connecting to FastMCP servers.
+
+This example demonstrates how to connect to an OAuth-protected FastMCP server.
+
+To run:
+    python client.py
+"""
+
+import asyncio
+
+from fastmcp.client import Client, OAuth
+
+SERVER_URL = "http://127.0.0.1:8000/mcp"
+
+
+async def main():
+    try:
+        async with Client(SERVER_URL, auth=OAuth()) as client:
+            assert await client.ping()
+            print("✅ Successfully authenticated!")
+
+            tools = await client.list_tools()
+            print(f"🔧 Available tools ({len(tools)}):")
+            for tool in tools:
+                print(f"   - {tool.name}: {tool.description}")
+    except Exception as e:
+        print(f"❌ Authentication failed: {e}")
+        raise
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/auth/github_oauth/server.py b/examples/auth/github_oauth/server.py
new file mode 100644
index 0000000..e93d6f0
--- /dev/null
+++ b/examples/auth/github_oauth/server.py
@@ -0,0 +1,35 @@
+"""GitHub OAuth server example for FastMCP.
+
+This example demonstrates how to protect a FastMCP server with GitHub OAuth.
+
+Required environment variables:
+- FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID: Your GitHub OAuth app client ID
+- FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET: Your GitHub OAuth app client secret
+
+To run:
+    python server.py
+"""
+
+import os
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.github import GitHubProvider
+
+auth = GitHubProvider(
+    client_id=os.getenv("FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID") or "",
+    client_secret=os.getenv("FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET") or "",
+    base_url="http://127.0.0.1:8000",
+    # redirect_path="/auth/callback",  # Default path - change if using a different callback URL
+)
+
+mcp = FastMCP("GitHub OAuth Example Server", auth=auth)
+
+
+@mcp.tool
+def echo(message: str) -> str:
+    """Echo the provided message."""
+    return message
+
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
diff --git a/examples/auth/google_oauth/README.md b/examples/auth/google_oauth/README.md
new file mode 100644
index 0000000..82bcd86
--- /dev/null
+++ b/examples/auth/google_oauth/README.md
@@ -0,0 +1,34 @@
+# Google OAuth Example
+
+Demonstrates FastMCP server protection with Google OAuth.
+
+## Setup
+
+1. Create a Google OAuth 2.0 Client:
+   - Go to [Google Cloud Console](https://console.cloud.google.com/)
+   - Create or select a project
+   - Go to APIs & Services > Credentials
+   - Create OAuth 2.0 Client ID (Web application)
+   - Add Authorized redirect URI: `http://127.0.0.1:8000/auth/callback`
+   - Copy the Client ID and Client Secret
+
+2. Set environment variables:
+
+   ```bash
+   export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
+   export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET="your-client-secret"
+   ```
+
+3. Run the server:
+
+   ```bash
+   python server.py
+   ```
+
+4. In another terminal, run the client:
+
+   ```bash
+   python client.py
+   ```
+
+The client will open your browser for Google authentication.
diff --git a/examples/auth/google_oauth/client.py b/examples/auth/google_oauth/client.py
new file mode 100644
index 0000000..5f1f39b
--- /dev/null
+++ b/examples/auth/google_oauth/client.py
@@ -0,0 +1,32 @@
+"""OAuth client example for connecting to FastMCP servers.
+
+This example demonstrates how to connect to an OAuth-protected FastMCP server.
+
+To run:
+    python client.py
+"""
+
+import asyncio
+
+from fastmcp.client import Client
+
+SERVER_URL = "http://127.0.0.1:8000/mcp"
+
+
+async def main():
+    try:
+        async with Client(SERVER_URL, auth="oauth") as client:
+            assert await client.ping()
+            print("✅ Successfully authenticated!")
+
+            tools = await client.list_tools()
+            print(f"🔧 Available tools ({len(tools)}):")
+            for tool in tools:
+                print(f"   - {tool.name}: {tool.description}")
+    except Exception as e:
+        print(f"❌ Authentication failed: {e}")
+        raise
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/auth/google_oauth/server.py b/examples/auth/google_oauth/server.py
new file mode 100644
index 0000000..2043ed6
--- /dev/null
+++ b/examples/auth/google_oauth/server.py
@@ -0,0 +1,37 @@
+"""Google OAuth server example for FastMCP.
+
+This example demonstrates how to protect a FastMCP server with Google OAuth.
+
+Required environment variables:
+- FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID: Your Google OAuth client ID
+- FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET: Your Google OAuth client secret
+
+To run:
+    python server.py
+"""
+
+import os
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.google import GoogleProvider
+
+auth = GoogleProvider(
+    client_id=os.getenv("FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID") or "",
+    client_secret=os.getenv("FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET") or "",
+    base_url="http://127.0.0.1:8000",
+    # redirect_path="/auth/callback",  # Default path - change if using a different callback URL
+    # Optional: specify required scopes
+    # required_scopes=["openid", "https://www.googleapis.com/auth/userinfo.email"],
+)
+
+mcp = FastMCP("Google OAuth Example Server", auth=auth)
+
+
+@mcp.tool
+def echo(message: str) -> str:
+    """Echo the provided message."""
+    return message
+
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
diff --git a/examples/auth/huggingface_oauth/README.md b/examples/auth/huggingface_oauth/README.md
new file mode 100644
index 0000000..3b84c70
--- /dev/null
+++ b/examples/auth/huggingface_oauth/README.md
@@ -0,0 +1,31 @@
+# Hugging FAce OAuth Example
+
+Demonstrates FastMCP server protection with Hugging Face OAuth.
+
+## Setup
+
+1. Create a Hugging Face OAuth App:
+   - Go to Hugging Face Settings > Connected Apps > Create App (`https://huggingface.co/settings/applications/new`)
+   - Set Authorization callback URL to: `http://localhost:8000/auth/callback`
+   - Copy the Client ID and Client Secret
+
+2. Set environment variables:
+
+   ```bash
+   export FASTMCP_SERVER_AUTH_HF_CLIENT_ID="your-client-id"
+   export FASTMCP_SERVER_AUTH_HF_CLIENT_SECRET="your-client-secret"
+   ```
+
+3. Run the server:
+
+   ```bash
+   python server.py
+   ```
+
+4. In another terminal, run the client:
+
+   ```bash
+   python client.py
+   ```
+
+The client will open your browser for Hugging Face authentication.
diff --git a/examples/auth/huggingface_oauth/client.py b/examples/auth/huggingface_oauth/client.py
new file mode 100644
index 0000000..d7f2b76
--- /dev/null
+++ b/examples/auth/huggingface_oauth/client.py
@@ -0,0 +1,32 @@
+"""OAuth client example for connecting to FastMCP servers.
+
+This example demonstrates how to connect to an OAuth-protected FastMCP server.
+
+To run:
+    python client.py
+"""
+
+import asyncio
+
+from fastmcp.client import Client
+
+SERVER_URL = "http://localhost:8000/mcp"
+
+
+async def main():
+    try:
+        async with Client(SERVER_URL, auth="oauth") as client:
+            assert await client.ping()
+            print("✅ Successfully authenticated!")
+
+            tools = await client.list_tools()
+            print(f"🔧 Available tools ({len(tools)}):")
+            for tool in tools:
+                print(f"   - {tool.name}: {tool.description}")
+    except Exception as e:
+        print(f"❌ Authentication failed: {e}")
+        raise
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/auth/huggingface_oauth/server.py b/examples/auth/huggingface_oauth/server.py
new file mode 100644
index 0000000..9745eb8
--- /dev/null
+++ b/examples/auth/huggingface_oauth/server.py
@@ -0,0 +1,35 @@
+import os
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.huggingface import HuggingFaceProvider
+
+auth_provider = HuggingFaceProvider(
+    # Your Hugging Face OAuth app client ID
+    client_id=os.getenv("FASTMCP_SERVER_AUTH_HF_CLIENT_ID") or "",
+    # Your Hugging Face OAuth app client secret
+    client_secret=os.getenv("FASTMCP_SERVER_AUTH_HF_CLIENT_SECRET") or "",
+    # Must match your OAuth configuration
+    base_url="http://localhost:8000",
+    # Supply jwt_signing_key instead of client_secret for public applications
+    # jwt_signing_key="replace-with-a-secure-secret"
+)
+
+mcp = FastMCP(name="Hugging Face Secured App", auth=auth_provider)
+
+
+# Add a tool to test authentication
+@mcp.tool
+async def get_user_info() -> dict:
+    """Returns information about the authenticated Hugging Face user."""
+    from fastmcp.server.dependencies import get_access_token
+
+    token = get_access_token()
+    return {
+        "subject": token.claims.get("sub"),
+        "username": token.claims.get("preferred_username"),
+        "profile": token.claims.get("profile"),
+    }
+
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
diff --git a/examples/auth/keycloak_oauth/README.md b/examples/auth/keycloak_oauth/README.md
new file mode 100644
index 0000000..ba6b95b
--- /dev/null
+++ b/examples/auth/keycloak_oauth/README.md
@@ -0,0 +1,29 @@
+# Keycloak OAuth Example
+
+Demonstrates FastMCP server protection with Keycloak OAuth.
+
+**Requires Keycloak 26.6.0 or later** with Dynamic Client Registration enabled.
+
+## Setup
+
+1. Configure a Keycloak realm with Dynamic Client Registration enabled and a trusted host policy for your server URL (e.g. `http://127.0.0.1:8000/*`).
+
+2. Set environment variables:
+
+   ```bash
+   export KEYCLOAK_REALM_URL="http://localhost:8080/realms/your-realm"
+   ```
+
+3. Run the server:
+
+   ```bash
+   python server.py
+   ```
+
+4. In another terminal, run the client:
+
+   ```bash
+   python client.py
+   ```
+
+The client will open your browser for Keycloak authentication.
diff --git a/examples/auth/keycloak_oauth/client.py b/examples/auth/keycloak_oauth/client.py
new file mode 100644
index 0000000..4992abb
--- /dev/null
+++ b/examples/auth/keycloak_oauth/client.py
@@ -0,0 +1,33 @@
+"""OAuth client example for connecting to a Keycloak-protected FastMCP server.
+
+To run:
+    python client.py
+"""
+
+import asyncio
+
+from fastmcp import Client
+
+SERVER_URL = "http://127.0.0.1:8000/mcp"
+
+
+async def main():
+    async with Client(SERVER_URL, auth="oauth") as client:
+        assert await client.ping()
+        print("Successfully authenticated!")
+
+        tools = await client.list_tools()
+        print(f"Available tools ({len(tools)}):")
+        for tool in tools:
+            print(f"   - {tool.name}: {tool.description}")
+
+        print("Calling protected tool: get_access_token_claims")
+        result = await client.call_tool("get_access_token_claims")
+        claims = result.data
+        print(f"   sub: {claims.get('sub', 'N/A')}")
+        print(f"   scope: {claims.get('scope', 'N/A')}")
+        print(f"   azp: {claims.get('azp', 'N/A')}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/auth/keycloak_oauth/server.py b/examples/auth/keycloak_oauth/server.py
new file mode 100644
index 0000000..7b46531
--- /dev/null
+++ b/examples/auth/keycloak_oauth/server.py
@@ -0,0 +1,44 @@
+"""Keycloak OAuth server example for FastMCP.
+
+This example demonstrates how to protect a FastMCP server with Keycloak OAuth.
+
+Required: Keycloak 26.6.0 or later with Dynamic Client Registration enabled.
+
+To run:
+    KEYCLOAK_REALM_URL=https://your-keycloak.com/realms/myrealm python server.py
+"""
+
+import os
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.keycloak import KeycloakAuthProvider
+from fastmcp.server.dependencies import get_access_token
+
+auth = KeycloakAuthProvider(
+    realm_url=os.getenv("KEYCLOAK_REALM_URL") or "http://localhost:8080/realms/fastmcp",
+    base_url="http://127.0.0.1:8000",
+    # audience="http://127.0.0.1:8000",  # Recommended for production
+)
+
+mcp = FastMCP("Keycloak Example Server", auth=auth)
+
+
+@mcp.tool
+def echo(message: str) -> str:
+    """Echo the provided message."""
+    return message
+
+
+@mcp.tool
+async def get_access_token_claims() -> dict:
+    """Get the authenticated user's access token claims."""
+    token = get_access_token()
+    return {
+        "sub": token.claims.get("sub"),
+        "scope": token.claims.get("scope"),
+        "azp": token.claims.get("azp"),
+    }
+
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
diff --git a/examples/auth/mounted/README.md b/examples/auth/mounted/README.md
new file mode 100644
index 0000000..2bf2130
--- /dev/null
+++ b/examples/auth/mounted/README.md
@@ -0,0 +1,39 @@
+# Multi-Provider OAuth Example
+
+This example demonstrates mounting multiple OAuth-protected MCP servers in a single application, each with its own OAuth provider. It showcases RFC 8414 path-aware discovery where each server has its own authorization server metadata endpoint.
+
+## URL Structure
+
+- **GitHub MCP**: `http://127.0.0.1:8000/api/mcp/github/mcp`
+- **Google MCP**: `http://127.0.0.1:8000/api/mcp/google/mcp`
+
+Discovery endpoints (RFC 8414 path-aware):
+- **GitHub**: `http://127.0.0.1:8000/.well-known/oauth-authorization-server/api/mcp/github`
+- **Google**: `http://127.0.0.1:8000/.well-known/oauth-authorization-server/api/mcp/google`
+
+## Setup
+
+Set environment variables for both providers:
+
+```bash
+export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID="your-github-client-id"
+export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET="your-github-client-secret"
+export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID="your-google-client-id"
+export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET="your-google-client-secret"
+```
+
+Configure redirect URIs in each provider's developer console (note the `/api/mcp/{provider}` prefix since the servers are mounted):
+- GitHub: `http://127.0.0.1:8000/api/mcp/github/auth/callback/github`
+- Google: `http://127.0.0.1:8000/api/mcp/google/auth/callback/google`
+
+## Running
+
+Start the server:
+```bash
+python server.py
+```
+
+Connect with the client:
+```bash
+python client.py
+```
diff --git a/examples/auth/mounted/client.py b/examples/auth/mounted/client.py
new file mode 100644
index 0000000..2b69195
--- /dev/null
+++ b/examples/auth/mounted/client.py
@@ -0,0 +1,50 @@
+"""Mounted OAuth servers client example for FastMCP.
+
+This example demonstrates connecting to multiple mounted OAuth-protected MCP servers.
+
+To run:
+    python client.py
+"""
+
+import asyncio
+
+from fastmcp.client import Client
+
+GITHUB_URL = "http://127.0.0.1:8000/api/mcp/github/mcp"
+GOOGLE_URL = "http://127.0.0.1:8000/api/mcp/google/mcp"
+
+
+async def main():
+    # Connect to GitHub server
+    print("\n--- GitHub Server ---")
+    try:
+        async with Client(GITHUB_URL, auth="oauth") as client:
+            assert await client.ping()
+            print("✅ Successfully authenticated!")
+
+            tools = await client.list_tools()
+            print(f"🔧 Available tools ({len(tools)}):")
+            for tool in tools:
+                print(f"   - {tool.name}: {tool.description}")
+    except Exception as e:
+        print(f"❌ Authentication failed: {e}")
+        raise
+
+    # Connect to Google server
+    print("\n--- Google Server ---")
+    try:
+        async with Client(GOOGLE_URL, auth="oauth") as client:
+            assert await client.ping()
+            print("✅ Successfully authenticated!")
+
+            tools = await client.list_tools()
+            print(f"🔧 Available tools ({len(tools)}):")
+            for tool in tools:
+                print(f"   - {tool.name}: {tool.description}")
+    except Exception as e:
+        print(f"❌ Authentication failed: {e}")
+        raise
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/auth/mounted/server.py b/examples/auth/mounted/server.py
new file mode 100644
index 0000000..c5b3af5
--- /dev/null
+++ b/examples/auth/mounted/server.py
@@ -0,0 +1,121 @@
+"""Mounted OAuth servers example for FastMCP.
+
+This example demonstrates mounting multiple OAuth-protected MCP servers in a single
+application, each with its own provider. It showcases RFC 8414 path-aware discovery
+where each server has its own authorization server metadata endpoint.
+
+URL structure:
+- GitHub MCP: http://127.0.0.1:8000/api/mcp/github/mcp
+- Google MCP: http://127.0.0.1:8000/api/mcp/google/mcp
+- GitHub discovery: http://127.0.0.1:8000/.well-known/oauth-authorization-server/api/mcp/github
+- Google discovery: http://127.0.0.1:8000/.well-known/oauth-authorization-server/api/mcp/google
+
+Required environment variables:
+- FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID: Your GitHub OAuth app client ID
+- FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET: Your GitHub OAuth app client secret
+- FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID: Your Google OAuth client ID
+- FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET: Your Google OAuth client secret
+
+To run:
+    python server.py
+"""
+
+import os
+
+import uvicorn
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.github import GitHubProvider
+from fastmcp.server.auth.providers.google import GoogleProvider
+
+# Configuration
+ROOT_URL = "http://127.0.0.1:8000"
+API_PREFIX = "/api/mcp"
+
+# --- GitHub OAuth Server ---
+github_auth = GitHubProvider(
+    client_id=os.getenv("FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID") or "",
+    client_secret=os.getenv("FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET") or "",
+    base_url=f"{ROOT_URL}{API_PREFIX}/github",
+    redirect_path="/auth/callback/github",
+)
+
+github_mcp = FastMCP("GitHub Server", auth=github_auth)
+
+
+@github_mcp.tool
+def github_echo(message: str) -> str:
+    """Echo from the GitHub-authenticated server."""
+    return f"[GitHub] {message}"
+
+
+@github_mcp.tool
+def github_info() -> str:
+    """Get info about the GitHub server."""
+    return "This is the GitHub OAuth protected MCP server"
+
+
+# --- Google OAuth Server ---
+google_auth = GoogleProvider(
+    client_id=os.getenv("FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID") or "",
+    client_secret=os.getenv("FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET") or "",
+    base_url=f"{ROOT_URL}{API_PREFIX}/google",
+    redirect_path="/auth/callback/google",
+)
+
+google_mcp = FastMCP("Google Server", auth=google_auth)
+
+
+@google_mcp.tool
+def google_echo(message: str) -> str:
+    """Echo from the Google-authenticated server."""
+    return f"[Google] {message}"
+
+
+@google_mcp.tool
+def google_info() -> str:
+    """Get info about the Google server."""
+    return "This is the Google OAuth protected MCP server"
+
+
+# --- Create ASGI apps ---
+github_app = github_mcp.http_app(path="/mcp")
+google_app = google_mcp.http_app(path="/mcp")
+
+# Get well-known routes for each provider (path-aware per RFC 8414)
+github_well_known = github_auth.get_well_known_routes(mcp_path="/mcp")
+google_well_known = google_auth.get_well_known_routes(mcp_path="/mcp")
+
+# --- Combine into single application ---
+# Note: Each provider has its own path-aware discovery endpoint:
+# - /.well-known/oauth-authorization-server/api/mcp/github
+# - /.well-known/oauth-authorization-server/api/mcp/google
+app = Starlette(
+    routes=[
+        # Well-known routes at root level (path-aware)
+        *github_well_known,
+        *google_well_known,
+        # MCP servers under /api/mcp prefix
+        Mount(f"{API_PREFIX}/github", app=github_app),
+        Mount(f"{API_PREFIX}/google", app=google_app),
+    ],
+    # Use one of the app lifespans (they're functionally equivalent)
+    lifespan=github_app.lifespan,
+)
+
+if __name__ == "__main__":
+    print("Starting mounted OAuth servers...")
+    print(f"  GitHub MCP:     {ROOT_URL}{API_PREFIX}/github/mcp")
+    print(f"  Google MCP:     {ROOT_URL}{API_PREFIX}/google/mcp")
+    print()
+    print("Discovery endpoints (RFC 8414 path-aware):")
+    print(
+        f"  GitHub:  {ROOT_URL}/.well-known/oauth-authorization-server{API_PREFIX}/github"
+    )
+    print(
+        f"  Google:  {ROOT_URL}/.well-known/oauth-authorization-server{API_PREFIX}/google"
+    )
+    print()
+    uvicorn.run(app, host="0.0.0.0", port=8000)
diff --git a/examples/auth/oci_oauth/README.md b/examples/auth/oci_oauth/README.md
new file mode 100644
index 0000000..5b83177
--- /dev/null
+++ b/examples/auth/oci_oauth/README.md
@@ -0,0 +1,51 @@
+# Oracle (OCI IAM (Identity Domain)) OAuth Example
+
+This example demonstrates how to use the OCI IAM OAuth provider with FastMCP servers.
+
+## Setup
+
+### 1. OCI App Registration
+
+1. Login to OCI console (https://cloud.oracle.com for OCI commercial cloud).
+2. From "Identity & Security" menu, open Domains page.
+3. On the Domains list page, select the domain in which you want to create MCP server OAuth client. If you need help finding the list page for the domain, see [Listing Identity Domains.](https://docs.oracle.com/en-us/iaas/Content/Identity/domains/to-view-identity-domains.htm#view-identity-domains).
+4. On the details page, select Integrated applications. A list of applications in the domain is displayed.
+5. Select Add application.
+6. In the Add application window, select Confidential Application.
+7. Select Launch workflow.
+8. In the Add application details page, Enter name and description and create the application.
+9. Once the Integrated Application is created, Click on "OAuth configuration" tab.
+10. Click on "Edit OAuth configuration" button.
+11. Configure the application as OAuth client by selecting "Configure this application as a client now" radio button.
+12. Select "Authorization code" grant type. If you are planning to use the same OAuth client application for token exchange, select "Client credentials" grant type as well. In the sample, we will use the same client.
+13. For Authorization grant type, select redirect URL. In most cases, this will be the MCP server URL followed by "/auth/callback". For example http://localhost:8000/auth/callback
+14. Click on "Submit" button to update OAuth configuration for the client application.
+15. Make sure to Activate the client application.
+16. Note down client ID and client secret for the application. You'll use these values when configuring the OCIProvider in the MCP server.
+
+For details instructions with screenshots, please refer to [FastMCP OCI Provider Documentation](https://gofastmcp.com/integrations/oci).
+
+### 2. Set Environment Variables
+
+```bash
+# Required
+FASTMCP_SERVER_AUTH_IDCS_CLIENT_ID=your-application-client-id
+FASTMCP_SERVER_AUTH_IDCS_CLIENT_SECRET=your-client-secret-value
+FASTMCP_SERVER_AUTH_IDCS_DOMAIN=your-iam-domain-url  # IDCS domain URL  for example idcs-abscasdwdac3432rdwsda.identity.oraclecloud.com
+```
+
+### 3. Run the Example
+
+Start the server:
+
+```bash
+python server.py
+```
+
+Test with client:
+
+```bash
+python client.py
+```
+
+When you run the client, it will open a browser on your machine to login to OCI IAM domain.
diff --git a/examples/auth/oci_oauth/client.py b/examples/auth/oci_oauth/client.py
new file mode 100644
index 0000000..d7f2b76
--- /dev/null
+++ b/examples/auth/oci_oauth/client.py
@@ -0,0 +1,32 @@
+"""OAuth client example for connecting to FastMCP servers.
+
+This example demonstrates how to connect to an OAuth-protected FastMCP server.
+
+To run:
+    python client.py
+"""
+
+import asyncio
+
+from fastmcp.client import Client
+
+SERVER_URL = "http://localhost:8000/mcp"
+
+
+async def main():
+    try:
+        async with Client(SERVER_URL, auth="oauth") as client:
+            assert await client.ping()
+            print("✅ Successfully authenticated!")
+
+            tools = await client.list_tools()
+            print(f"🔧 Available tools ({len(tools)}):")
+            for tool in tools:
+                print(f"   - {tool.name}: {tool.description}")
+    except Exception as e:
+        print(f"❌ Authentication failed: {e}")
+        raise
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/auth/oci_oauth/server.py b/examples/auth/oci_oauth/server.py
new file mode 100644
index 0000000..e1b09f8
--- /dev/null
+++ b/examples/auth/oci_oauth/server.py
@@ -0,0 +1,38 @@
+"""Oracle OCI IAM OAuth server example for FastMCP.
+
+This example demonstrates how to protect a FastMCP server with Oracle OCI IAM OAuth.
+
+Required environment variables:
+- FASTMCP_SERVER_AUTH_IDCS_CLIENT_ID: Your IDCS OAuth Application clientID
+- FASTMCP_SERVER_AUTH_IDCS_CLIENT_SECRET: Your IDCS client secret
+- FASTMCP_SERVER_AUTH_IDCS_DOMAIN: IDCS domain URL  for example idcs-abscasdwdac3432rdwsda.identity.oraclecloud.com
+
+To run:
+    python server.py
+"""
+
+import os
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.oci import OCIProvider
+
+auth = OCIProvider(
+    client_id=os.getenv("FASTMCP_SERVER_AUTH_IDCS_CLIENT_ID") or "",
+    client_secret=os.getenv("FASTMCP_SERVER_AUTH_IDCS_CLIENT_SECRET") or "",
+    config_url=f"https://{os.getenv('FASTMCP_SERVER_AUTH_IDCS_DOMAIN')}/.well-known/openid-configuration"
+    or "",
+    base_url="http://localhost:8000",
+    # redirect_path="/auth/callback",  # Default path - change if using a different callback URL
+)
+
+mcp = FastMCP("OCI OAuth Example Server", auth=auth)
+
+
+@mcp.tool
+def echo(message: str) -> str:
+    """Echo the provided message."""
+    return message
+
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000, host="localhost")
diff --git a/examples/auth/propelauth_oauth/README.md b/examples/auth/propelauth_oauth/README.md
new file mode 100644
index 0000000..aa5b10e
--- /dev/null
+++ b/examples/auth/propelauth_oauth/README.md
@@ -0,0 +1,67 @@
+# PropelAuth OAuth Example
+
+Demonstrates FastMCP server protection with PropelAuth OAuth.
+
+## Setup
+
+### 1. Configure MCP Authentication in PropelAuth
+
+**Create a PropelAuth Account**:
+
+- Go to [PropelAuth Dashboard](https://www.propelauth.com)
+- Navigate to the **MCP** section and click **Enable MCP**
+
+**Configure Allowed MCP Clients**:
+
+- Under **MCP > Allowed MCP Clients**, add redirect URIs for each MCP client you want to allow
+- PropelAuth provides templates for popular clients like Claude, Cursor, and ChatGPT
+
+**Configure Scopes**:
+
+- Under **MCP > Scopes**, define the permissions available to MCP clients (e.g., `read:user_data`)
+
+**Generate Introspection Credentials**:
+
+- Go to **MCP > Request Validation** and click **Create Credentials**
+- Note the **Client ID** and **Client Secret**
+
+**Note Your Auth URL**:
+
+- Find your Auth URL in the **Backend Integration** section (e.g., `https://auth.yourdomain.com`)
+
+Create a `.env` file:
+
+```bash
+# Required PropelAuth credentials
+PROPELAUTH_AUTH_URL=https://auth.yourdomain.com
+PROPELAUTH_INTROSPECTION_CLIENT_ID=your-client-id
+PROPELAUTH_INTROSPECTION_CLIENT_SECRET=your-client-secret
+BASE_URL=http://127.0.0.1:8000/
+# Optional: additional scopes tokens must include (comma-separated)
+# PROPELAUTH_REQUIRED_SCOPES=read:user_data
+```
+
+### 2. Run the Example
+
+Start the server:
+
+```bash
+# From this directory
+uv run python server.py
+```
+
+The server will start on `http://127.0.0.1:8000/mcp` with PropelAuth OAuth authentication enabled.
+
+Test with client:
+
+```bash
+uv run python client.py
+```
+
+The `client.py` will:
+
+1. Attempt to connect to the server
+2. Detect that OAuth authentication is required
+3. Open a browser for PropelAuth authentication
+4. Complete the OAuth flow and connect to the server
+5. Demonstrate calling authenticated tools (echo and whoami)
diff --git a/examples/auth/propelauth_oauth/client.py b/examples/auth/propelauth_oauth/client.py
new file mode 100644
index 0000000..fd6a84b
--- /dev/null
+++ b/examples/auth/propelauth_oauth/client.py
@@ -0,0 +1,43 @@
+"""OAuth client example for connecting to PropelAuth-protected FastMCP servers.
+
+This example demonstrates how to connect to a PropelAuth OAuth-protected FastMCP server.
+
+To run:
+    python client.py
+"""
+
+import asyncio
+
+from fastmcp.client import Client
+
+SERVER_URL = "http://127.0.0.1:8000/mcp"
+
+
+async def main():
+    try:
+        async with Client(SERVER_URL, auth="oauth") as client:
+            assert await client.ping()
+            print("✅ Successfully authenticated with PropelAuth!")
+
+            tools = await client.list_tools()
+            print(f"🔧 Available tools ({len(tools)}):")
+            for tool in tools:
+                print(f"   - {tool.name}: {tool.description}")
+
+            # Test calling a tool
+            result = await client.call_tool(
+                "echo", {"message": "Hello from PropelAuth!"}
+            )
+            print(f"🎯 Echo result: {result}")
+
+            # Test calling whoami tool
+            whoami = await client.call_tool("whoami", {})
+            print(f"👤 Who am I: {whoami}")
+
+    except Exception as e:
+        print(f"❌ Authentication failed: {e}")
+        raise
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/auth/propelauth_oauth/server.py b/examples/auth/propelauth_oauth/server.py
new file mode 100644
index 0000000..ab1661d
--- /dev/null
+++ b/examples/auth/propelauth_oauth/server.py
@@ -0,0 +1,54 @@
+"""PropelAuth OAuth server example for FastMCP.
+
+This example demonstrates how to protect a FastMCP server with PropelAuth OAuth.
+
+Required environment variables:
+- PROPELAUTH_AUTH_URL: Your PropelAuth Auth URL (from Backend Integration page)
+- PROPELAUTH_INTROSPECTION_CLIENT_ID: Introspection Client ID (from MCP > Request Validation)
+- PROPELAUTH_INTROSPECTION_CLIENT_SECRET: Introspection Client Secret (from MCP > Request Validation)
+
+Optional:
+- PROPELAUTH_REQUIRED_SCOPES: Comma-separated scopes tokens must include
+- BASE_URL: Public URL where the FastMCP server is exposed (defaults to `http://127.0.0.1:8000/`)
+
+To run:
+    python server.py
+"""
+
+import os
+
+from dotenv import load_dotenv
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.propelauth import PropelAuthProvider
+from fastmcp.server.dependencies import get_access_token
+
+load_dotenv()
+
+auth = PropelAuthProvider(
+    auth_url=os.environ["PROPELAUTH_AUTH_URL"],
+    introspection_client_id=os.environ["PROPELAUTH_INTROSPECTION_CLIENT_ID"],
+    introspection_client_secret=os.environ["PROPELAUTH_INTROSPECTION_CLIENT_SECRET"],
+    base_url=os.getenv("BASE_URL", "http://127.0.0.1:8000/"),
+)
+
+mcp = FastMCP("PropelAuth OAuth Example Server", auth=auth)
+
+
+@mcp.tool
+def echo(message: str) -> str:
+    """Echo the provided message."""
+    return message
+
+
+@mcp.tool
+def whoami() -> dict:
+    """Return the authenticated user's ID."""
+    token = get_access_token()
+    if token is None:
+        return {"error": "Not authenticated"}
+    return {"user_id": token.claims.get("sub")}
+
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
diff --git a/examples/auth/scalekit_oauth/README.md b/examples/auth/scalekit_oauth/README.md
new file mode 100644
index 0000000..d16b81c
--- /dev/null
+++ b/examples/auth/scalekit_oauth/README.md
@@ -0,0 +1,55 @@
+# Scalekit OAuth Example
+
+Demonstrates FastMCP server protection with Scalekit OAuth.
+
+## Setup
+
+### 1. Configure MCP server in Scalekit environment
+
+**Create a Scalekit Account**:
+
+- Go to [Scalekit Dashboard](https://app.scalekit.com/)
+- Copy your Environment URL from **Developers** → **Settings**
+- Copy Resource ID (res_xxx) from **Developers** → **MCP Servers**
+
+**Register Your MCP Server**:
+
+- Go to **MCP Servers** → **Create New Server**
+- Fill in your MCP server details
+- Note the **Resource ID** (e.g., `res_123`)
+
+Create a `.env` file:
+
+```bash
+# Required Scalekit credentials
+SCALEKIT_ENVIRONMENT_URL=<YOUR_APP_ENVIRONMENT_URL>
+SCALEKIT_RESOURCE_ID=<YOUR_APP_RESOURCE_ID> # res_926EXAMPLE5878
+BASE_URL=http://127.0.0.1:8000/
+# Optional: additional scopes tokens must include (comma-separated)
+# SCALEKIT_REQUIRED_SCOPES=read,write
+```
+
+### 2. Run the Example
+
+Start the server:
+
+```bash
+# From this directory
+uv run python server.py
+```
+
+The server will start on `http://127.0.0.1:8000/mcp` with Scalekit OAuth authentication enabled.
+
+Test with client:
+
+```bash
+uv run python client.py
+```
+
+The `client.py` will:
+
+1. Attempt to connect to the server
+2. Detect that OAuth authentication is required
+3. Open a browser for Scalekit authentication
+4. Complete the OAuth flow and connect to the server
+5. Demonstrate calling authenticated tools
diff --git a/examples/auth/scalekit_oauth/client.py b/examples/auth/scalekit_oauth/client.py
new file mode 100644
index 0000000..4146b2c
--- /dev/null
+++ b/examples/auth/scalekit_oauth/client.py
@@ -0,0 +1,41 @@
+"""OAuth client example for connecting to Scalekit-protected FastMCP servers.
+
+This example demonstrates how to connect to a Scalekit OAuth-protected FastMCP server.
+
+To run:
+    python client.py
+"""
+
+import asyncio
+
+from fastmcp.client import Client
+
+SERVER_URL = "http://127.0.0.1:8000/mcp"
+
+
+async def main():
+    try:
+        async with Client(SERVER_URL, auth="oauth") as client:
+            assert await client.ping()
+            print("✅ Successfully authenticated with Scalekit!")
+
+            tools = await client.list_tools()
+            print(f"🔧 Available tools ({len(tools)}):")
+            for tool in tools:
+                print(f"   - {tool.name}: {tool.description}")
+
+            # Test calling a tool
+            result = await client.call_tool("echo", {"message": "Hello from Scalekit!"})
+            print(f"🎯 Echo result: {result}")
+
+            # Test calling auth status tool
+            auth_status = await client.call_tool("auth_status", {})
+            print(f"👤 Auth status: {auth_status}")
+
+    except Exception as e:
+        print(f"❌ Authentication failed: {e}")
+        raise
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/auth/scalekit_oauth/server.py b/examples/auth/scalekit_oauth/server.py
new file mode 100644
index 0000000..09d4f59
--- /dev/null
+++ b/examples/auth/scalekit_oauth/server.py
@@ -0,0 +1,58 @@
+"""Scalekit OAuth server example for FastMCP.
+
+This example demonstrates how to protect a FastMCP server with Scalekit OAuth.
+
+Required environment variables:
+- SCALEKIT_ENVIRONMENT_URL: Your Scalekit environment URL (e.g., "https://your-env.scalekit.com")
+- SCALEKIT_RESOURCE_ID: Your Scalekit resource ID
+
+Optional:
+- SCALEKIT_REQUIRED_SCOPES: Comma-separated scopes tokens must include
+- BASE_URL: Public URL where the FastMCP server is exposed (defaults to `http://127.0.0.1:8000/`)
+
+To run:
+    python server.py
+"""
+
+import os
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.scalekit import ScalekitProvider
+
+required_scopes_env = os.getenv("SCALEKIT_REQUIRED_SCOPES")
+required_scopes = (
+    [scope.strip() for scope in required_scopes_env.split(",") if scope.strip()]
+    if required_scopes_env
+    else None
+)
+
+auth = ScalekitProvider(
+    environment_url=os.getenv("SCALEKIT_ENVIRONMENT_URL")
+    or "https://your-env.scalekit.com",
+    resource_id=os.getenv("SCALEKIT_RESOURCE_ID") or "",
+    base_url=os.getenv("BASE_URL", "http://127.0.0.1:8000/"),
+    required_scopes=required_scopes,
+)
+
+mcp = FastMCP("Scalekit OAuth Example Server", auth=auth)
+
+
+@mcp.tool
+def echo(message: str) -> str:
+    """Echo the provided message."""
+    return message
+
+
+@mcp.tool
+def auth_status() -> dict:
+    """Show Scalekit authentication status."""
+    # In a real implementation, you would extract user info from the JWT token
+    return {
+        "message": "This tool requires authentication via Scalekit",
+        "authenticated": True,
+        "provider": "Scalekit",
+    }
+
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
diff --git a/examples/auth/workos_oauth/README.md b/examples/auth/workos_oauth/README.md
new file mode 100644
index 0000000..62afa8d
--- /dev/null
+++ b/examples/auth/workos_oauth/README.md
@@ -0,0 +1,27 @@
+# WorkOS OAuth Example
+
+Demonstrates FastMCP server protection with WorkOS OAuth.
+
+## Setup
+
+1. Create a WorkOS application and copy your credentials:
+
+   ```bash
+   export WORKOS_CLIENT_ID="your-client-id"
+   export WORKOS_CLIENT_SECRET="your-client-secret"
+   export WORKOS_AUTHKIT_DOMAIN="https://your-app.authkit.app"
+   ```
+
+2. Run the server:
+
+   ```bash
+   python server.py
+   ```
+
+3. In another terminal, run the client:
+
+   ```bash
+   python client.py
+   ```
+
+The client will open your browser for WorkOS authentication.
diff --git a/examples/auth/workos_oauth/client.py b/examples/auth/workos_oauth/client.py
new file mode 100644
index 0000000..5f1f39b
--- /dev/null
+++ b/examples/auth/workos_oauth/client.py
@@ -0,0 +1,32 @@
+"""OAuth client example for connecting to FastMCP servers.
+
+This example demonstrates how to connect to an OAuth-protected FastMCP server.
+
+To run:
+    python client.py
+"""
+
+import asyncio
+
+from fastmcp.client import Client
+
+SERVER_URL = "http://127.0.0.1:8000/mcp"
+
+
+async def main():
+    try:
+        async with Client(SERVER_URL, auth="oauth") as client:
+            assert await client.ping()
+            print("✅ Successfully authenticated!")
+
+            tools = await client.list_tools()
+            print(f"🔧 Available tools ({len(tools)}):")
+            for tool in tools:
+                print(f"   - {tool.name}: {tool.description}")
+    except Exception as e:
+        print(f"❌ Authentication failed: {e}")
+        raise
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/auth/workos_oauth/server.py b/examples/auth/workos_oauth/server.py
new file mode 100644
index 0000000..4dba970
--- /dev/null
+++ b/examples/auth/workos_oauth/server.py
@@ -0,0 +1,37 @@
+"""WorkOS OAuth server example for FastMCP.
+
+This example demonstrates how to protect a FastMCP server with WorkOS OAuth.
+
+Required environment variables:
+- WORKOS_CLIENT_ID: Your WorkOS Connect application client ID
+- WORKOS_CLIENT_SECRET: Your WorkOS Connect application client secret
+- WORKOS_AUTHKIT_DOMAIN: Your AuthKit domain (e.g., "https://your-app.authkit.app")
+
+To run:
+    python server.py
+"""
+
+import os
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.workos import WorkOSProvider
+
+auth = WorkOSProvider(
+    client_id=os.getenv("WORKOS_CLIENT_ID") or "",
+    client_secret=os.getenv("WORKOS_CLIENT_SECRET") or "",
+    authkit_domain=os.getenv("WORKOS_AUTHKIT_DOMAIN") or "https://your-app.authkit.app",
+    base_url="http://127.0.0.1:8000",
+    # redirect_path="/auth/callback",  # Default path - change if using a different callback URL
+)
+
+mcp = FastMCP("WorkOS OAuth Example Server", auth=auth)
+
+
+@mcp.tool
+def echo(message: str) -> str:
+    """Echo the provided message."""
+    return message
+
+
+if __name__ == "__main__":
+    mcp.run(transport="http", port=8000)
diff --git a/examples/code_mode/README.md b/examples/code_mode/README.md
new file mode 100644
index 0000000..28834f3
--- /dev/null
+++ b/examples/code_mode/README.md
@@ -0,0 +1,37 @@
+# Code Mode
+
+CodeMode collapses an entire tool catalog into two meta-tools: `search` (keyword-based discovery) and `execute` (run Python scripts that chain tool calls in a sandbox). Instead of burning context tokens on every intermediate result, the LLM writes a script that runs server-side and returns only the final answer.
+
+## Run
+
+```bash
+uv run python server.py   # in one terminal
+uv run python client.py   # in another
+```
+
+## Example Output
+
+```
+══════════════════ CodeMode Transform ══════════════════
+
+┌────────────── list_tools() ──────────────┐
+│ Tool     Description                     │
+│ search   Search for available tools ...  │
+│ execute  Chain `await call_tool(...)` ... │
+└── 8 backend tools collapsed into 2 ──────┘
+
+┌──── search(query="math arithmetic") ─────┐
+│ #   Tool      Description                │
+│ 1   add       Add two numbers together.  │
+│ 2   multiply  Multiply two numbers.      │
+│ 3   fibonacci Generate the first n ...   │
+└── 3 results ─────────────────────────────┘
+
+┌────────────── execute ───────────────────┐
+│ a = await call_tool("add", {"a": 3 ...  │
+│ b = await call_tool("multiply", ...     │
+│ return b                                 │
+└── result: 14.0 ──────────────────────────┘
+```
+
+The key insight: with standard MCP, each `call_tool` is a round-trip through the LLM. With CodeMode, the LLM writes one script and all the tool calls happen server-side. Intermediate data never touches the context window.
diff --git a/examples/code_mode/client.py b/examples/code_mode/client.py
new file mode 100644
index 0000000..3757bec
--- /dev/null
+++ b/examples/code_mode/client.py
@@ -0,0 +1,142 @@
+"""Example: Client using CodeMode to discover and chain tools.
+
+CodeMode exposes just two tools: `search` (keyword query) and `execute`
+(run Python code with `call_tool` available). This client demonstrates
+both: searching for tools, then chaining multiple calls in a single
+execute block — one round-trip instead of many.
+
+Run with:
+    uv run python examples/code_mode/client.py
+"""
+
+import asyncio
+import json
+from typing import Any
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.table import Table
+
+from fastmcp.client import Client
+
+console = Console()
+
+
+def _get_result(result) -> Any:
+    """Extract the value from a CallToolResult (structured or text)."""
+    if result.structured_content is not None:
+        data = result.structured_content
+        if isinstance(data, dict) and set(data) == {"result"}:
+            return data["result"]
+        return data
+    return result.content[0].text
+
+
+def _format_params(tool: dict) -> str:
+    """Format inputSchema properties as a compact signature."""
+    schema = tool.get("inputSchema", {})
+    props = schema.get("properties", {})
+    if not props:
+        return "()"
+    parts = []
+    for name, info in props.items():
+        typ = info.get("type", "")
+        parts.append(f"{name}: {typ}" if typ else name)
+    return f"({', '.join(parts)})"
+
+
+def _tool_table(
+    tools: list[dict], *, ranked: bool = False, show_params: bool = False
+) -> Table:
+    table = Table(show_header=True, show_edge=False, pad_edge=False, expand=True)
+    if ranked:
+        table.add_column("#", style="dim", width=3, justify="right")
+    table.add_column("Tool", style="cyan", no_wrap=True)
+    if show_params:
+        table.add_column("Parameters", style="dim", no_wrap=True)
+    table.add_column("Description", style="dim")
+    for i, tool in enumerate(tools, 1):
+        row = [tool["name"]]
+        if show_params:
+            row.append(_format_params(tool))
+        row.append(tool.get("description", ""))
+        if ranked:
+            row.insert(0, str(i))
+        table.add_row(*row)
+    return table
+
+
+async def main():
+    async with Client("examples/code_mode/server.py") as client:
+        console.print()
+        console.rule("[bold]CodeMode[/bold]")
+        console.print()
+
+        # Step 1: list_tools only returns two synthetic meta-tools
+        console.print(
+            "The server has 8 tools. CodeMode replaces them with "
+            "two synthetic tools — [bold]search[/bold] and [bold]execute[/bold]:"
+        )
+        console.print()
+        tools = await client.list_tools()
+        visible = [{"name": t.name, "description": t.description} for t in tools]
+        console.print(
+            Panel(
+                _tool_table(visible),
+                title="[bold]list_tools()[/bold]",
+                title_align="left",
+                border_style="blue",
+            )
+        )
+        console.print()
+
+        # Step 2: search discovers available tools
+        console.print("The LLM calls [bold]search[/bold] to discover available tools:")
+        console.print()
+        result = await client.call_tool("search", {"query": "add multiply numbers"})
+        found = _get_result(result)
+        if isinstance(found, str):
+            found = json.loads(found)
+        console.print(
+            Panel(
+                _tool_table(found, ranked=True, show_params=True),
+                title='[bold]search[/bold]  [dim]query="add multiply numbers"[/dim]',
+                title_align="left",
+                border_style="green",
+            )
+        )
+        console.print()
+
+        # Step 3: execute chains tool calls in one round-trip
+        console.print(
+            "Now the LLM writes a Python script that chains "
+            "the tools it found. All of it runs server-side in a "
+            "sandbox — [bold]one round-trip[/bold], intermediate "
+            "data never hits the context window:"
+        )
+        console.print()
+        code = """\
+a = await call_tool("add", {"a": 3, "b": 4})
+b = await call_tool("multiply", {"x": a["result"], "y": 2})
+fib = await call_tool("fibonacci", {"n": b["result"]})
+return {"sum": a["result"], "product": b["result"], "fibonacci": fib["result"]}
+"""
+        result = await client.call_tool("execute", {"code": code})
+        console.print(
+            Panel(
+                Syntax(code.strip(), "python", theme="monokai"),
+                title="[bold]execute[/bold]",
+                title_align="left",
+                border_style="yellow",
+            )
+        )
+        console.print()
+
+        # Final result
+        console.print(f"  Result: [bold green]{_get_result(result)}[/bold green]")
+        console.print()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/code_mode/server.py b/examples/code_mode/server.py
new file mode 100644
index 0000000..70aca8b
--- /dev/null
+++ b/examples/code_mode/server.py
@@ -0,0 +1,84 @@
+"""Example: CodeMode transform — search and execute tools via code.
+
+CodeMode replaces the entire tool catalog with two meta-tools: `search`
+(keyword-based tool discovery) and `execute` (run Python code that chains
+tool calls in a sandbox). This dramatically reduces round-trips and
+context window usage when an LLM needs to orchestrate many tools.
+
+Requires pydantic-monty for the sandbox:
+    pip install "fastmcp[code-mode]"
+
+Run with:
+    uv run python examples/code_mode/server.py
+"""
+
+from fastmcp import FastMCP
+from fastmcp.experimental.transforms.code_mode import CodeMode
+
+mcp = FastMCP("CodeMode Demo")
+
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Add two numbers together."""
+    return a + b
+
+
+@mcp.tool
+def multiply(x: float, y: float) -> float:
+    """Multiply two numbers."""
+    return x * y
+
+
+@mcp.tool
+def fibonacci(n: int) -> list[int]:
+    """Generate the first n Fibonacci numbers."""
+    if n <= 0:
+        return []
+    seq = [0, 1]
+    while len(seq) < n:
+        seq.append(seq[-1] + seq[-2])
+    return seq[:n]
+
+
+@mcp.tool
+def reverse_string(text: str) -> str:
+    """Reverse a string."""
+    return text[::-1]
+
+
+@mcp.tool
+def word_count(text: str) -> int:
+    """Count the number of words in a text."""
+    return len(text.split())
+
+
+@mcp.tool
+def to_uppercase(text: str) -> str:
+    """Convert text to uppercase."""
+    return text.upper()
+
+
+@mcp.tool
+def list_files(directory: str) -> list[str]:
+    """List files in a directory."""
+    import os
+
+    return os.listdir(directory)
+
+
+@mcp.tool
+def read_file(path: str) -> str:
+    """Read the contents of a file."""
+    with open(path) as f:
+        return f.read()
+
+
+# CodeMode collapses all 8 tools into just `search` + `execute`.
+# The LLM discovers tools via keyword search, then writes Python
+# scripts that chain multiple tool calls in a single round-trip.
+mcp.add_transform(CodeMode())
+
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/complex_inputs.py b/examples/complex_inputs.py
new file mode 100644
index 0000000..014482a
--- /dev/null
+++ b/examples/complex_inputs.py
@@ -0,0 +1,30 @@
+"""
+FastMCP Complex inputs Example
+
+Demonstrates validation via pydantic with complex models.
+"""
+
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+
+from fastmcp import FastMCP
+
+mcp = FastMCP("Shrimp Tank")
+
+
+class ShrimpTank(BaseModel):
+    class Shrimp(BaseModel):
+        name: Annotated[str, Field(max_length=10)]
+
+    shrimp: list[Shrimp]
+
+
+@mcp.tool
+def name_shrimp(
+    tank: ShrimpTank,
+    # You can use pydantic Field in function signatures for validation.
+    extra_names: Annotated[list[str], Field(max_length=10)],
+) -> list[str]:
+    """List all shrimp names in the tank"""
+    return [shrimp.name for shrimp in tank.shrimp] + extra_names
diff --git a/examples/config_server.py b/examples/config_server.py
new file mode 100644
index 0000000..9d6976d
--- /dev/null
+++ b/examples/config_server.py
@@ -0,0 +1,46 @@
+"""
+Simple example showing FastMCP server with command line argument support.
+
+Usage:
+    fastmcp run examples/config_server.py -- --name MyServer --debug
+"""
+
+import argparse
+
+from fastmcp import FastMCP
+
+parser = argparse.ArgumentParser(description="Simple configurable MCP server")
+parser.add_argument(
+    "--name", type=str, default="ConfigurableServer", help="Server name"
+)
+parser.add_argument("--debug", action="store_true", help="Enable debug mode")
+
+args = parser.parse_args()
+
+server_name = args.name
+if args.debug:
+    server_name += " (Debug)"
+
+mcp = FastMCP(server_name)
+
+
+@mcp.tool
+def get_status() -> dict[str, str | bool]:
+    """Get the current server configuration and status."""
+    return {
+        "server_name": server_name,
+        "debug_mode": args.debug,
+        "original_name": args.name,
+    }
+
+
+@mcp.tool
+def echo_message(message: str) -> str:
+    """Echo a message, with debug info if debug mode is enabled."""
+    if args.debug:
+        return f"[DEBUG] Echoing: {message}"
+    return message
+
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/custom_tool_serializer_decorator.py b/examples/custom_tool_serializer_decorator.py
new file mode 100644
index 0000000..7075b72
--- /dev/null
+++ b/examples/custom_tool_serializer_decorator.py
@@ -0,0 +1,72 @@
+"""Example of custom tool serialization using ToolResult and a wrapper decorator.
+
+This pattern provides explicit control over how tool outputs are serialized,
+making the serialization visible in each tool's code.
+"""
+
+import asyncio
+import inspect
+from collections.abc import Callable
+from functools import wraps
+from typing import Any
+
+import yaml
+
+from fastmcp import FastMCP
+from fastmcp.tools.tool import ToolResult
+
+
+def with_serializer(serializer: Callable[[Any], str]):
+    """Decorator to apply custom serialization to tool output."""
+
+    def decorator(fn):
+        @wraps(fn)
+        def wrapper(*args, **kwargs):
+            result = fn(*args, **kwargs)
+            return ToolResult(content=serializer(result), structured_content=result)
+
+        @wraps(fn)
+        async def async_wrapper(*args, **kwargs):
+            result = await fn(*args, **kwargs)
+            return ToolResult(content=serializer(result), structured_content=result)
+
+        return async_wrapper if inspect.iscoroutinefunction(fn) else wrapper
+
+    return decorator
+
+
+# Create reusable serializer decorators
+with_yaml = with_serializer(lambda d: yaml.dump(d, width=100, sort_keys=False))
+
+server = FastMCP(name="CustomSerializerExample")
+
+
+@server.tool
+@with_yaml
+def get_example_data() -> dict:
+    """Returns some example data serialized as YAML."""
+    return {"name": "Test", "value": 123, "status": True}
+
+
+@server.tool
+def get_json_data() -> dict:
+    """Returns data with default JSON serialization."""
+    return {"format": "json", "data": [1, 2, 3]}
+
+
+async def example_usage():
+    # YAML serialized tool
+    yaml_result = await server._call_tool_mcp("get_example_data", {})
+    print("YAML Tool Result:")
+    print(yaml_result)
+    print()
+
+    # Default JSON serialized tool
+    json_result = await server._call_tool_mcp("get_json_data", {})
+    print("JSON Tool Result:")
+    print(json_result)
+
+
+if __name__ == "__main__":
+    asyncio.run(example_usage())
+    server.run()
diff --git a/examples/desktop.py b/examples/desktop.py
new file mode 100644
index 0000000..b32a314
--- /dev/null
+++ b/examples/desktop.py
@@ -0,0 +1,32 @@
+"""
+FastMCP Desktop Example
+
+A simple example that exposes the desktop directory as a resource.
+"""
+
+from pathlib import Path
+
+from fastmcp import FastMCP
+
+# Create server
+mcp = FastMCP("Demo")
+
+
+@mcp.resource("dir://desktop")
+def desktop() -> list[str]:
+    """List the files in the user's desktop"""
+    desktop = Path.home() / "Desktop"
+    return [str(f) for f in desktop.iterdir()]
+
+
+# Add a dynamic greeting resource
+@mcp.resource("greeting://{name}")
+def get_greeting(name: str) -> str:
+    """Get a personalized greeting"""
+    return f"Hello, {name}!"
+
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
diff --git a/examples/diagnostics/client_with_tracing.py b/examples/diagnostics/client_with_tracing.py
new file mode 100644
index 0000000..0b56ddc
--- /dev/null
+++ b/examples/diagnostics/client_with_tracing.py
@@ -0,0 +1,161 @@
+#!/usr/bin/env python
+"""Client script to exercise all diagnostics server components with tracing.
+
+Usage:
+    # First, start the diagnostics server with tracing in one terminal:
+    uv run examples/run_with_tracing.py examples/diagnostics/server.py --transport sse --port 8001
+
+    # Then run this client in another terminal:
+    uv run examples/diagnostics/client_with_tracing.py
+
+    # View traces in otel-desktop-viewer (http://localhost:8000):
+    otel-desktop-viewer
+
+This script exercises all 8 components:
+- 4 successful: ping, diag://status, diag://echo/{message}, greet prompt
+- 4 error: fail_tool, diag://error, diag://error/{code}, fail prompt
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+# Configure OTEL SDK before importing fastmcp
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+
+def setup_tracing():
+    """Set up OpenTelemetry tracing with OTLP export."""
+    endpoint = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4317")
+    service_name = os.environ.get("OTEL_SERVICE_NAME", "fastmcp-diagnostics-client")
+
+    resource = Resource.create({"service.name": service_name})
+    provider = TracerProvider(resource=resource)
+    exporter = OTLPSpanExporter(endpoint=endpoint, insecure=True)
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+    trace.set_tracer_provider(provider)
+
+    print(f"Tracing enabled: OTLP {endpoint}")
+    print(f"Service: {service_name}")
+    print("View traces: otel-desktop-viewer (http://localhost:8000)\n")
+
+
+async def main():
+    setup_tracing()
+
+    from fastmcp import Client
+
+    server_url = os.environ.get("DIAGNOSTICS_SERVER_URL", "http://localhost:8001/sse")
+    print(f"Connecting to: {server_url}\n")
+
+    async with Client(server_url) as client:
+        # List all available components
+        tools = await client.list_tools()
+        resources = await client.list_resources()
+        prompts = await client.list_prompts()
+
+        print(f"Found {len(tools)} tools: {[t.name for t in tools]}")
+        print(f"Found {len(resources)} resources: {[r.uri for r in resources]}")
+        print(f"Found {len(prompts)} prompts: {[p.name for p in prompts]}\n")
+
+        # === SUCCESSFUL OPERATIONS ===
+        print("=" * 60)
+        print("SUCCESSFUL OPERATIONS")
+        print("=" * 60)
+
+        # Local successful components
+        print("\n--- Local Tools ---")
+        result = await client.call_tool("ping", {})
+        print(f"ping: {result}")
+
+        print("\n--- Local Resources ---")
+        result = await client.read_resource("diag://status")
+        print(f"diag://status: {result}")
+
+        result = await client.read_resource("diag://echo/hello-world")
+        print(f"diag://echo/hello-world: {result}")
+
+        print("\n--- Local Prompts ---")
+        result = await client.get_prompt("greet", {"name": "Diagnostics"})
+        print(
+            f"greet: {result.messages[0].content.text if result.messages else result}"
+        )
+
+        # Proxied components from echo server
+        print("\n--- Proxied Tools ---")
+        try:
+            result = await client.call_tool(
+                "proxied_echo_tool", {"text": "proxied test"}
+            )
+            print(f"proxied_echo_tool: {result}")
+        except Exception as e:
+            print(f"proxied_echo_tool: ERROR - {e}")
+
+        print("\n--- Proxied Resources ---")
+        try:
+            # Resource: echo://static -> echo://proxied/static
+            result = await client.read_resource("echo://proxied/static")
+            print(f"echo://proxied/static: {result}")
+        except Exception as e:
+            print(f"echo://proxied/static: ERROR - {e}")
+
+        try:
+            # Template: echo://{text} -> echo://proxied/{text}
+            result = await client.read_resource("echo://proxied/test-message")
+            print(f"echo://proxied/test-message: {result}")
+        except Exception as e:
+            print(f"echo://proxied/test-message: ERROR - {e}")
+
+        print("\n--- Proxied Prompts ---")
+        try:
+            result = await client.get_prompt("proxied_echo", {"text": "proxied prompt"})
+            print(
+                f"proxied_echo: {result.messages[0].content.text if result.messages else result}"
+            )
+        except Exception as e:
+            print(f"proxied_echo: ERROR - {e}")
+
+        # === ERROR OPERATIONS ===
+        print("\n" + "=" * 60)
+        print("ERROR OPERATIONS (expected to fail)")
+        print("=" * 60)
+
+        print("\n--- Error Tools ---")
+        try:
+            await client.call_tool("fail_tool", {})
+            print("fail_tool: UNEXPECTED SUCCESS")
+        except Exception as e:
+            print(f"fail_tool: {type(e).__name__} - {e}")
+
+        print("\n--- Error Resources ---")
+        try:
+            await client.read_resource("diag://error")
+            print("diag://error: UNEXPECTED SUCCESS")
+        except Exception as e:
+            print(f"diag://error: {type(e).__name__} - {e}")
+
+        try:
+            await client.read_resource("diag://error/500")
+            print("diag://error/500: UNEXPECTED SUCCESS")
+        except Exception as e:
+            print(f"diag://error/500: {type(e).__name__} - {e}")
+
+        print("\n--- Error Prompts ---")
+        try:
+            await client.get_prompt("fail", {})
+            print("fail: UNEXPECTED SUCCESS")
+        except Exception as e:
+            print(f"fail: {type(e).__name__} - {e}")
+
+    print("\n" + "=" * 60)
+    print("DONE - Check otel-desktop-viewer for traces")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/diagnostics/server.py b/examples/diagnostics/server.py
new file mode 100644
index 0000000..211c5d8
--- /dev/null
+++ b/examples/diagnostics/server.py
@@ -0,0 +1,125 @@
+"""FastMCP Diagnostics Server - for testing tracing, errors, and observability."""
+
+import asyncio
+import os
+import subprocess
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+import httpx
+
+from fastmcp import FastMCP
+from fastmcp.server import create_proxy
+
+ECHO_SERVER_PORT = 8002
+ECHO_SERVER_URL = f"http://localhost:{ECHO_SERVER_PORT}/sse"
+
+
+@asynccontextmanager
+async def lifespan(server: FastMCP) -> AsyncIterator[None]:
+    """Start echo server subprocess and mount proxy to it."""
+    echo_path = Path(__file__).parent.parent / "echo.py"
+
+    # Pass OTEL config to subprocess with different service name
+    env = os.environ.copy()
+    env["OTEL_SERVICE_NAME"] = "fastmcp-echo-server"
+
+    # Start echo server as subprocess using run_with_tracing.py for OTEL export
+    run_with_tracing = Path(__file__).parent.parent / "run_with_tracing.py"
+    proc = subprocess.Popen(
+        [
+            "uv",
+            "run",
+            str(run_with_tracing),
+            str(echo_path),
+            "--transport",
+            "sse",
+            "--port",
+            str(ECHO_SERVER_PORT),
+        ],
+        env=env,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+
+    # Wait for server to be ready (async to avoid blocking event loop)
+    async with httpx.AsyncClient() as client:
+        for _ in range(50):
+            try:
+                await client.get(
+                    f"http://localhost:{ECHO_SERVER_PORT}/sse", timeout=0.1
+                )
+                break
+            except Exception:
+                await asyncio.sleep(0.1)
+
+    # Mount proxy to the running echo server
+    echo_proxy = create_proxy(ECHO_SERVER_URL, name="Echo Proxy")
+    server.mount(echo_proxy, namespace="proxied")
+
+    try:
+        yield
+    finally:
+        proc.terminate()
+        try:
+            proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait()
+
+
+mcp = FastMCP("Diagnostics Server", lifespan=lifespan)
+
+# === SUCCESSFUL COMPONENTS ===
+
+
+@mcp.tool
+def ping() -> str:
+    """Simple ping tool - always succeeds."""
+    return "pong"
+
+
+@mcp.resource("diag://status")
+def status_resource() -> str:
+    """Status resource - always succeeds."""
+    return "OK"
+
+
+@mcp.resource("diag://echo/{message}")
+def echo_template(message: str) -> str:
+    """Echo template - always succeeds."""
+    return f"Echo: {message}"
+
+
+@mcp.prompt("greet")
+def greet_prompt(name: str = "World") -> str:
+    """Greeting prompt - always succeeds."""
+    return f"Hello, {name}!"
+
+
+# === ERROR COMPONENTS ===
+
+
+@mcp.tool
+def fail_tool(message: str = "Intentional tool failure") -> str:
+    """Tool that always raises ValueError - for error tracing."""
+    raise ValueError(message)
+
+
+@mcp.resource("diag://error")
+def error_resource() -> str:
+    """Resource that always raises ValueError."""
+    raise ValueError("Intentional resource failure")
+
+
+@mcp.resource("diag://error/{code}")
+def error_template(code: str) -> str:
+    """Template that always raises ValueError."""
+    raise ValueError(f"Intentional template failure: {code}")
+
+
+@mcp.prompt("fail")
+def fail_prompt() -> str:
+    """Prompt that always raises ValueError."""
+    raise ValueError("Intentional prompt failure")
diff --git a/examples/echo.py b/examples/echo.py
new file mode 100644
index 0000000..c98f23d
--- /dev/null
+++ b/examples/echo.py
@@ -0,0 +1,30 @@
+"""
+FastMCP Echo Server
+"""
+
+from fastmcp import FastMCP
+
+# Create server
+mcp = FastMCP("Echo Server")
+
+
+@mcp.tool
+def echo_tool(text: str) -> str:
+    """Echo the input text"""
+    return text
+
+
+@mcp.resource("echo://static")
+def echo_resource() -> str:
+    return "Echo!"
+
+
+@mcp.resource("echo://{text}")
+def echo_template(text: str) -> str:
+    """Echo the input text"""
+    return f"Echo: {text}"
+
+
+@mcp.prompt("echo")
+def echo_prompt(text: str) -> str:
+    return text
diff --git a/examples/elicitation.py b/examples/elicitation.py
new file mode 100644
index 0000000..368980e
--- /dev/null
+++ b/examples/elicitation.py
@@ -0,0 +1,47 @@
+"""
+FastMCP Elicitation Example
+
+Demonstrates tools that ask users for input during execution.
+
+Try it with the CLI:
+
+    fastmcp list examples/elicitation.py
+    fastmcp call examples/elicitation.py greet
+    fastmcp call examples/elicitation.py survey
+"""
+
+from dataclasses import dataclass
+
+from fastmcp import Context, FastMCP
+
+mcp = FastMCP("Elicitation Demo")
+
+
+@mcp.tool
+async def greet(ctx: Context) -> str:
+    """Greet the user by name (asks for their name)."""
+    result = await ctx.elicit("What is your name?", response_type=str)
+
+    if result.action == "accept":
+        return f"Hello, {result.data}!"
+    return "Maybe next time!"
+
+
+@mcp.tool
+async def survey(ctx: Context) -> str:
+    """Run a short survey collecting structured info."""
+
+    @dataclass
+    class SurveyResponse:
+        favorite_color: str
+        lucky_number: int
+
+    result = await ctx.elicit(
+        "Quick survey — tell us about yourself:",
+        response_type=SurveyResponse,
+    )
+
+    if result.action == "accept":
+        resp = result.data
+        return f"Got it — you like {resp.favorite_color} and your lucky number is {resp.lucky_number}."
+    return "Survey skipped."
diff --git a/examples/fastmcp_config/env_interpolation_example.json b/examples/fastmcp_config/env_interpolation_example.json
new file mode 100644
index 0000000..0eb4af0
--- /dev/null
+++ b/examples/fastmcp_config/env_interpolation_example.json
@@ -0,0 +1,20 @@
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "entrypoint": "src/server.py:app",
+  "environment": {
+    "python": "3.12",
+    "dependencies": ["fastmcp", "httpx", "pandas"]
+  },
+  "deployment": {
+    "transport": "http",
+    "host": "0.0.0.0",
+    "port": 8000,
+    "env": {
+      "API_BASE_URL": "https://api.${ENVIRONMENT}.example.com",
+      "DATABASE_URL": "postgres://${DB_USER}:${DB_PASS}@${DB_HOST}:${DB_PORT}/${DB_NAME}",
+      "CACHE_PREFIX": "myapp_${ENVIRONMENT}_v1",
+      "LOG_LEVEL": "${LOG_LEVEL}",
+      "FEATURE_FLAGS": "${FEATURE_FLAGS}"
+    }
+  }
+}
diff --git a/examples/fastmcp_config/fastmcp.json b/examples/fastmcp_config/fastmcp.json
new file mode 100644
index 0000000..3511d11
--- /dev/null
+++ b/examples/fastmcp_config/fastmcp.json
@@ -0,0 +1,13 @@
+{
+  "$schema": "https://gofastmcp.com/schemas/fastmcp/v1.json",
+  "source": {
+    "path": "server.py"
+  },
+  "environment": {
+    "python": "3.12",
+    "dependencies": ["requests"]
+  },
+  "deployment": {
+    "transport": "stdio"
+  }
+}
\ No newline at end of file
diff --git a/examples/fastmcp_config/full_example.fastmcp.json b/examples/fastmcp_config/full_example.fastmcp.json
new file mode 100644
index 0000000..e31a4f8
--- /dev/null
+++ b/examples/fastmcp_config/full_example.fastmcp.json
@@ -0,0 +1,27 @@
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "python": "3.12",
+    "dependencies": ["requests>=2.31.0", "httpx"],
+    "requirements": null,
+    "project": null,
+    "editable": null
+  },
+  "deployment": {
+    "transport": "http",
+    "host": "127.0.0.1",
+    "port": 8000,
+    "path": "/mcp/",
+    "log_level": "INFO",
+    "env": {
+      "DEBUG": "false",
+      "API_TIMEOUT": "30"
+    },
+    "cwd": null,
+    "args": null
+  }
+}
diff --git a/examples/fastmcp_config/server.py b/examples/fastmcp_config/server.py
new file mode 100644
index 0000000..40f116b
--- /dev/null
+++ b/examples/fastmcp_config/server.py
@@ -0,0 +1,39 @@
+"""Example FastMCP server for demonstrating fastmcp.json configuration."""
+
+from fastmcp import FastMCP
+
+# Create the FastMCP server instance
+mcp = FastMCP("Config Example Server")
+
+
+@mcp.tool
+def echo(text: str) -> str:
+    """Echo the provided text back to the user."""
+    return f"You said: {text}"
+
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Add two numbers together."""
+    return a + b
+
+
+@mcp.resource("config://example")
+def get_example_config() -> str:
+    """Return an example configuration."""
+    return """
+    This server is configured using fastmcp.json.
+    
+    The configuration file specifies:
+    - Python version
+    - Dependencies
+    - Transport settings
+    - Other runtime options
+    """
+
+
+# This allows the server to run with: fastmcp run server.py
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(mcp.run_async())
diff --git a/examples/fastmcp_config/simple.fastmcp.json b/examples/fastmcp_config/simple.fastmcp.json
new file mode 100644
index 0000000..40541fe
--- /dev/null
+++ b/examples/fastmcp_config/simple.fastmcp.json
@@ -0,0 +1,7 @@
+{
+  "$schema": "https://gofastmcp.com/schemas/fastmcp/v1.json",
+  "entrypoint": "server.py",
+  "deployment": {
+    "transport": "stdio"
+  }
+}
\ No newline at end of file
diff --git a/examples/fastmcp_config_demo/README.md b/examples/fastmcp_config_demo/README.md
new file mode 100644
index 0000000..7abf11c
--- /dev/null
+++ b/examples/fastmcp_config_demo/README.md
@@ -0,0 +1,55 @@
+# FastMCP Configuration Demo
+
+This example demonstrates the recommended way to configure FastMCP servers using `fastmcp.json`.
+
+## Migration from Dependencies Parameter
+
+Previously (deprecated as of FastMCP 2.11.4), you would specify dependencies in the Python code:
+
+```python
+mcp = FastMCP("Demo Server", dependencies=["pyautogui", "Pillow"])
+```
+
+Now, dependencies are declared in `fastmcp.json`:
+
+```json
+{
+  "environment": {
+    "dependencies": ["pyautogui", "Pillow"]
+  }
+}
+```
+
+## Running the Server
+
+With the configuration file in place, you can run the server in several ways:
+
+```bash
+# Auto-detect fastmcp.json in current directory
+cd examples/mcp_server_config_demo
+fastmcp run
+
+# Or specify the config file explicitly
+fastmcp run examples/mcp_server_config_demo/fastmcp.json
+
+# Or use development mode with the Inspector UI
+fastmcp dev examples/mcp_server_config_demo/fastmcp.json
+```
+
+## Benefits
+
+- **Single source of truth**: All configuration in one place
+- **Environment isolation**: Dependencies are installed in an isolated UV environment
+- **No import-time issues**: Dependencies are installed before the server is imported
+- **IDE support**: JSON schema provides autocomplete and validation
+- **Shareable**: Easy to share complete server configuration with others
+
+## Configuration Structure
+
+The `fastmcp.json` file supports three main sections:
+
+1. **entrypoint** (required): The Python file containing your server
+2. **environment** (optional): Python version and dependencies
+3. **deployment** (optional): Runtime settings like transport and logging
+
+See the [full documentation](https://gofastmcp.com/docs/deployment/server-configuration) for more details.
\ No newline at end of file
diff --git a/examples/fastmcp_config_demo/fastmcp.json b/examples/fastmcp_config_demo/fastmcp.json
new file mode 100644
index 0000000..9027c6c
--- /dev/null
+++ b/examples/fastmcp_config_demo/fastmcp.json
@@ -0,0 +1,14 @@
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "server.py"
+  },
+  "environment": {
+    "python": "3.11",
+    "dependencies": ["pyautogui", "Pillow"]
+  },
+  "deployment": {
+    "transport": "stdio",
+    "log_level": "INFO"
+  }
+}
diff --git a/examples/fastmcp_config_demo/server.py b/examples/fastmcp_config_demo/server.py
new file mode 100644
index 0000000..5453a06
--- /dev/null
+++ b/examples/fastmcp_config_demo/server.py
@@ -0,0 +1,70 @@
+"""
+Example server demonstrating fastmcp.json configuration.
+
+This server previously would have used the deprecated dependencies parameter:
+    mcp = FastMCP("Demo Server", dependencies=["pyautogui", "Pillow"])
+
+Now dependencies are declared in fastmcp.json alongside this file.
+"""
+
+import io
+
+from fastmcp import FastMCP
+from fastmcp.utilities.types import Image
+
+# Create server - dependencies are now in fastmcp.json
+mcp = FastMCP("Screenshot Demo")
+
+
+@mcp.tool
+def take_screenshot() -> Image:
+    """
+    Take a screenshot of the user's screen and return it as an image.
+
+    Use this tool anytime the user wants you to look at something on their screen.
+    """
+    import pyautogui
+
+    buffer = io.BytesIO()
+
+    # Capture and compress the screenshot to stay under size limits
+    screenshot = pyautogui.screenshot()
+    screenshot.convert("RGB").save(buffer, format="JPEG", quality=60, optimize=True)
+
+    return Image(data=buffer.getvalue(), format="jpeg")
+
+
+@mcp.tool
+def analyze_colors() -> dict:
+    """
+    Analyze the dominant colors in the current screen.
+
+    Returns a dictionary with color statistics from the screen.
+    """
+    import pyautogui
+    from PIL import Image as PILImage
+
+    screenshot = pyautogui.screenshot()
+    # Convert to smaller size for faster analysis
+    small = screenshot.resize((100, 100), PILImage.Resampling.LANCZOS)
+
+    # Get colors
+    colors = small.getcolors(maxcolors=10000)
+    if not colors:
+        return {"error": "Too many colors to analyze"}
+
+    # Sort by frequency
+    sorted_colors = sorted(colors, key=lambda x: x[0], reverse=True)[:10]
+
+    return {
+        "top_colors": [
+            {"count": count, "rgb": color} for count, color in sorted_colors
+        ],
+        "total_pixels": sum(c[0] for c in colors),
+    }
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(mcp.run_async())
diff --git a/examples/filesystem-provider/components/prompts/assistant.py b/examples/filesystem-provider/components/prompts/assistant.py
new file mode 100644
index 0000000..0950e34
--- /dev/null
+++ b/examples/filesystem-provider/components/prompts/assistant.py
@@ -0,0 +1,39 @@
+"""Assistant prompts."""
+
+from fastmcp.prompts import prompt
+
+
+@prompt
+def code_review(code: str, language: str = "python") -> str:
+    """Generate a code review prompt.
+
+    Args:
+        code: The code to review.
+        language: Programming language (default: python).
+    """
+    return f"""Please review this {language} code:
+
+```{language}
+{code}
+```
+
+Focus on:
+- Code quality and readability
+- Potential bugs or issues
+- Performance considerations
+- Best practices"""
+
+
+@prompt(
+    name="explain-concept",
+    description="Generate a prompt to explain a technical concept.",
+    tags={"education", "explanation"},
+)
+def explain(topic: str, audience: str = "developer") -> str:
+    """Generate an explanation prompt.
+
+    Args:
+        topic: The concept to explain.
+        audience: Target audience level.
+    """
+    return f"Explain {topic} to a {audience}. Use clear examples and analogies."
diff --git a/examples/filesystem-provider/components/resources/config.py b/examples/filesystem-provider/components/resources/config.py
new file mode 100644
index 0000000..03a3f7b
--- /dev/null
+++ b/examples/filesystem-provider/components/resources/config.py
@@ -0,0 +1,55 @@
+"""Configuration resources - static and templated."""
+
+import json
+
+from fastmcp.resources import resource
+
+
+# Static resource - no parameters in URI
+@resource("config://app")
+def get_app_config() -> str:
+    """Get application configuration."""
+    return json.dumps(
+        {
+            "name": "FilesystemDemo",
+            "version": "1.0.0",
+            "features": ["tools", "resources", "prompts"],
+        },
+        indent=2,
+    )
+
+
+# Resource template - {env} is a parameter
+@resource("config://env/{env}")
+def get_env_config(env: str) -> str:
+    """Get environment-specific configuration.
+
+    Args:
+        env: Environment name (dev, staging, prod).
+    """
+    configs = {
+        "dev": {"debug": True, "log_level": "DEBUG", "database": "localhost"},
+        "staging": {"debug": True, "log_level": "INFO", "database": "staging-db"},
+        "prod": {"debug": False, "log_level": "WARNING", "database": "prod-db"},
+    }
+    config = configs.get(env, {"error": f"Unknown environment: {env}"})
+    return json.dumps(config, indent=2)
+
+
+# Resource with custom metadata
+@resource(
+    "config://features",
+    name="feature-flags",
+    mime_type="application/json",
+    tags={"config", "features"},
+)
+def get_feature_flags() -> str:
+    """Get feature flags configuration."""
+    return json.dumps(
+        {
+            "dark_mode": True,
+            "beta_features": False,
+            "max_upload_size_mb": 100,
+        },
+        indent=2,
+    )
diff --git a/examples/filesystem-provider/components/tools/calculator.py b/examples/filesystem-provider/components/tools/calculator.py
new file mode 100644
index 0000000..f8d9010
--- /dev/null
+++ b/examples/filesystem-provider/components/tools/calculator.py
@@ -0,0 +1,24 @@
+"""Math tools with custom metadata."""
+
+from fastmcp.tools import tool
+
+
+@tool(
+    name="add-numbers",  # Custom name (default would be "add")
+    description="Add two numbers together.",
+    tags={"math", "arithmetic"},
+)
+def add(a: float, b: float) -> float:
+    """Add two numbers."""
+    return a + b
+
+
+@tool(tags={"math", "arithmetic"})
+def multiply(a: float, b: float) -> float:
+    """Multiply two numbers.
+
+    Args:
+        a: First number.
+        b: Second number.
+    """
+    return a * b
diff --git a/examples/filesystem-provider/components/tools/greeting.py b/examples/filesystem-provider/components/tools/greeting.py
new file mode 100644
index 0000000..f124902
--- /dev/null
+++ b/examples/filesystem-provider/components/tools/greeting.py
@@ -0,0 +1,28 @@
+"""Greeting tools - multiple tools in one file."""
+
+from fastmcp.tools import tool
+
+
+@tool
+def greet(name: str) -> str:
+    """Greet someone by name.
+
+    Args:
+        name: The person's name.
+    """
+    return f"Hello, {name}!"
+
+
+@tool
+def farewell(name: str) -> str:
+    """Say goodbye to someone.
+
+    Args:
+        name: The person's name.
+    """
+    return f"Goodbye, {name}!"
+
+
+# Helper functions without decorators are ignored
+def _format_message(msg: str) -> str:
+    return msg.strip().capitalize()
diff --git a/examples/filesystem-provider/server.py b/examples/filesystem-provider/server.py
new file mode 100644
index 0000000..11bbf7f
--- /dev/null
+++ b/examples/filesystem-provider/server.py
@@ -0,0 +1,29 @@
+"""Filesystem-based MCP server using FileSystemProvider.
+
+This example demonstrates how to use FileSystemProvider to automatically
+discover and register tools, resources, and prompts from the filesystem.
+
+Run:
+    fastmcp run examples/filesystem-provider/server.py
+
+Inspect:
+    fastmcp inspect examples/filesystem-provider/server.py
+
+Dev mode (re-scan files on every request):
+    Change reload=True below, then modify files while the server runs.
+"""
+
+from pathlib import Path
+
+from fastmcp import FastMCP
+from fastmcp.server.providers import FileSystemProvider
+
+# The provider scans all .py files in the directory recursively.
+# Functions decorated with @tool, @resource, or @prompt are registered.
+# Directory structure is purely organizational - decorators determine type.
+provider = FileSystemProvider(
+    root=Path(__file__).parent / "components",
+    reload=True,  # Set True for dev mode (re-scan on every request)
+)
+
+mcp = FastMCP("FilesystemDemo", providers=[provider])
diff --git a/examples/get_file.py b/examples/get_file.py
new file mode 100644
index 0000000..b86ca92
--- /dev/null
+++ b/examples/get_file.py
@@ -0,0 +1,39 @@
+# /// script
+# dependencies = ["aiohttp", "fastmcp"]
+# ///
+
+# uv pip install aiohttp fastmcp
+
+import aiohttp
+
+from fastmcp.server import FastMCP
+from fastmcp.utilities.types import File
+
+
+def create_server():
+    mcp = FastMCP(name="File Demo", instructions="Get files from the server or URL.")
+
+    @mcp.tool()
+    async def get_test_file_from_server(path: str = "requirements.txt") -> File:
+        """
+        Get a test file from the server. If the path is not provided, it defaults to 'requirements.txt'.
+        """
+        return File(path=path)
+
+    @mcp.tool()
+    async def get_test_pdf_from_url(
+        url: str = "https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf",
+    ) -> File:
+        """
+        Get a test PDF file from a URL. If the URL is not provided, it defaults to a sample PDF.
+        """
+        async with aiohttp.ClientSession() as session:
+            async with session.get(url) as response:
+                pdf_data = await response.read()
+                return File(data=pdf_data, format="pdf")
+
+    return mcp
+
+
+if __name__ == "__main__":
+    create_server().run(transport="sse", host="0.0.0.0", port=8001, path="/sse")
diff --git a/examples/in_memory_proxy_example.py b/examples/in_memory_proxy_example.py
new file mode 100644
index 0000000..20cea73
--- /dev/null
+++ b/examples/in_memory_proxy_example.py
@@ -0,0 +1,82 @@
+"""
+This example demonstrates how to set up and use an in-memory FastMCP proxy.
+
+It illustrates the pattern:
+1. Create an original FastMCP server with some tools.
+2. Create a proxy FastMCP server using ``create_proxy(original_server)``.
+3. Use another Client to connect to the proxy server (in-memory) and interact with the original server's tools through the proxy.
+"""
+
+import asyncio
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server import create_proxy
+from fastmcp.types import TextContent
+
+
+class EchoService:
+    """A simple service to demonstrate with"""
+
+    def echo(self, message: str) -> str:
+        return f"Original server echoes: {message}"
+
+
+async def main():
+    print("--- In-Memory FastMCP Proxy Example ---")
+    print("This example will walk through setting up an in-memory proxy.")
+    print("-----------------------------------------")
+
+    # 1. Original Server Setup
+    print(
+        "\nStep 1: Setting up the Original Server (OriginalEchoServer) with an 'echo' tool..."
+    )
+    original_server = FastMCP("OriginalEchoServer")
+    original_server.add_tool(EchoService().echo)
+    print(f"   -> Original Server '{original_server.name}' created.")
+
+    # 2. Proxy Server Creation
+    print("\nStep 2: Creating the Proxy Server (InMemoryProxy)...")
+    print(f"          (Using create_proxy to wrap '{original_server.name}' directly)")
+    proxy_server = create_proxy(original_server, name="InMemoryProxy")
+    print(
+        f"   -> Proxy Server '{proxy_server.name}' created, proxying '{original_server.name}'."
+    )
+
+    # 3. Interacting via Proxy
+    print("\nStep 3: Using a new Client to connect to the Proxy Server and interact...")
+    async with Client(proxy_server) as final_client:
+        print(f"   -> Successfully connected to proxy '{proxy_server.name}'.")
+
+        print("\n   Listing tools available via proxy...")
+        tools = await final_client.list_tools()
+        if tools:
+            print("      Available Tools:")
+            for tool in tools:
+                print(
+                    f"        - {tool.name} (Description: {tool.description or 'N/A'})"
+                )
+        else:
+            print("      No tools found via proxy.")
+
+        message_to_echo = "Hello, simplified proxied world!"
+        print(f"\n   Calling 'echo' tool via proxy with message: '{message_to_echo}'")
+        try:
+            result = await final_client.call_tool("echo", {"message": message_to_echo})
+            if result.content and isinstance(result.content[0], TextContent):
+                print(
+                    f"      Result from proxied 'echo' call: '{result.content[0].text}'"
+                )
+            else:
+                print(
+                    f"      Error: Unexpected result format from proxied 'echo' call: {result}"
+                )
+        except Exception as e:
+            print(f"      Error calling 'echo' tool via proxy: {e}")
+
+    print("\n-----------------------------------------")
+    print("--- In-Memory Proxy Example Finished ---")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/memory.fastmcp.json b/examples/memory.fastmcp.json
new file mode 100644
index 0000000..5ee1aea
--- /dev/null
+++ b/examples/memory.fastmcp.json
@@ -0,0 +1,7 @@
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "entrypoint": "memory.py",
+  "environment": {
+    "dependencies": ["pydantic-ai-slim[openai]", "asyncpg", "numpy", "pgvector"]
+  }
+}
diff --git a/examples/memory.py b/examples/memory.py
new file mode 100644
index 0000000..792bd48
--- /dev/null
+++ b/examples/memory.py
@@ -0,0 +1,341 @@
+# /// script
+# dependencies = ["pydantic-ai-slim[openai]", "asyncpg", "numpy", "pgvector", "fastmcp"]
+# ///
+
+# uv pip install 'pydantic-ai-slim[openai]' asyncpg numpy pgvector fastmcp
+
+"""
+Recursive memory system inspired by the human brain's clustering of memories.
+Uses OpenAI's 'text-embedding-3-small' model and pgvector for efficient similarity search.
+"""
+
+import asyncio
+import math
+import os
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Annotated, Any, Self
+
+import asyncpg
+import numpy as np
+from openai import AsyncOpenAI
+from pgvector.asyncpg import register_vector
+from pydantic import BaseModel, Field
+from pydantic_ai import Agent
+
+import fastmcp
+from fastmcp import FastMCP
+
+MAX_DEPTH = 5
+SIMILARITY_THRESHOLD = 0.7
+DECAY_FACTOR = 0.99
+REINFORCEMENT_FACTOR = 1.1
+
+DEFAULT_LLM_MODEL = "openai:gpt-4o"
+DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small"
+
+# Dependencies are configured in memory.fastmcp.json
+mcp = FastMCP("memory")
+
+DB_DSN = "postgresql://postgres:postgres@localhost:54320/memory_db"
+# reset memory by deleting the profile directory
+PROFILE_DIR = (
+    fastmcp.settings.home / os.environ.get("USER", "anon") / "memory"
+).resolve()
+PROFILE_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def cosine_similarity(a: list[float], b: list[float]) -> float:
+    a_array = np.array(a, dtype=np.float64)
+    b_array = np.array(b, dtype=np.float64)
+    return np.dot(a_array, b_array) / (
+        np.linalg.norm(a_array) * np.linalg.norm(b_array)
+    )
+
+
+async def do_ai(
+    user_prompt: str,
+    system_prompt: str,
+    result_type: type | Annotated,
+    deps=None,
+) -> Any:
+    agent = Agent(
+        DEFAULT_LLM_MODEL,
+        system_prompt=system_prompt,
+        result_type=result_type,
+    )
+    result = await agent.run(user_prompt, deps=deps)
+    return result.data
+
+
+@dataclass
+class Deps:
+    openai: AsyncOpenAI
+    pool: asyncpg.Pool
+
+
+async def get_db_pool() -> asyncpg.Pool:
+    async def init(conn):
+        await conn.execute("CREATE EXTENSION IF NOT EXISTS vector;")
+        await register_vector(conn)
+
+    pool = await asyncpg.create_pool(DB_DSN, init=init)
+    return pool
+
+
+class MemoryNode(BaseModel):
+    id: int | None = None
+    content: str
+    summary: str = ""
+    importance: float = 1.0
+    access_count: int = 0
+    timestamp: float = Field(
+        default_factory=lambda: datetime.now(timezone.utc).timestamp()
+    )
+    embedding: list[float]
+
+    @classmethod
+    async def from_content(cls, content: str, deps: Deps):
+        embedding = await get_embedding(content, deps)
+        return cls(content=content, embedding=embedding)
+
+    async def save(self, deps: Deps):
+        async with deps.pool.acquire() as conn:
+            if self.id is None:
+                result = await conn.fetchrow(
+                    """
+                    INSERT INTO memories (content, summary, importance, access_count, timestamp, embedding)
+                    VALUES ($1, $2, $3, $4, $5, $6)
+                    RETURNING id
+                    """,
+                    self.content,
+                    self.summary,
+                    self.importance,
+                    self.access_count,
+                    self.timestamp,
+                    self.embedding,
+                )
+                self.id = result["id"]
+            else:
+                await conn.execute(
+                    """
+                    UPDATE memories
+                    SET content = $1, summary = $2, importance = $3,
+                        access_count = $4, timestamp = $5, embedding = $6
+                    WHERE id = $7
+                    """,
+                    self.content,
+                    self.summary,
+                    self.importance,
+                    self.access_count,
+                    self.timestamp,
+                    self.embedding,
+                    self.id,
+                )
+
+    async def merge_with(self, other: Self, deps: Deps):
+        self.content = await do_ai(
+            f"{self.content}\n\n{other.content}",
+            "Combine the following two texts into a single, coherent text.",
+            str,
+            deps,
+        )
+        self.importance += other.importance
+        self.access_count += other.access_count
+        self.embedding = [
+            (a + b) / 2 for a, b in zip(self.embedding, other.embedding, strict=True)
+        ]
+        self.summary = await do_ai(
+            self.content, "Summarize the following text concisely.", str, deps
+        )
+        await self.save(deps)
+        # Delete the merged node from the database
+        if other.id is not None:
+            await delete_memory(other.id, deps)
+
+    def get_effective_importance(self):
+        return self.importance * (1 + math.log(self.access_count + 1))
+
+
+async def get_embedding(text: str, deps: Deps) -> list[float]:
+    embedding_response = await deps.openai.embeddings.create(
+        input=text,
+        model=DEFAULT_EMBEDDING_MODEL,
+    )
+    return embedding_response.data[0].embedding
+
+
+async def delete_memory(memory_id: int, deps: Deps):
+    async with deps.pool.acquire() as conn:
+        await conn.execute("DELETE FROM memories WHERE id = $1", memory_id)
+
+
+async def add_memory(content: str, deps: Deps):
+    new_memory = await MemoryNode.from_content(content, deps)
+    await new_memory.save(deps)
+
+    similar_memories = await find_similar_memories(new_memory.embedding, deps)
+    for memory in similar_memories:
+        if memory.id != new_memory.id:
+            await new_memory.merge_with(memory, deps)
+
+    await update_importance(new_memory.embedding, deps)
+
+    await prune_memories(deps)
+
+    return f"Remembered: {content}"
+
+
+async def find_similar_memories(embedding: list[float], deps: Deps) -> list[MemoryNode]:
+    async with deps.pool.acquire() as conn:
+        rows = await conn.fetch(
+            """
+            SELECT id, content, summary, importance, access_count, timestamp, embedding
+            FROM memories
+            ORDER BY embedding <-> $1
+            LIMIT 5
+            """,
+            embedding,
+        )
+    memories = [
+        MemoryNode(
+            id=row["id"],
+            content=row["content"],
+            summary=row["summary"],
+            importance=row["importance"],
+            access_count=row["access_count"],
+            timestamp=row["timestamp"],
+            embedding=row["embedding"],
+        )
+        for row in rows
+    ]
+    return memories
+
+
+async def update_importance(user_embedding: list[float], deps: Deps):
+    async with deps.pool.acquire() as conn:
+        rows = await conn.fetch(
+            "SELECT id, importance, access_count, embedding FROM memories"
+        )
+        for row in rows:
+            memory_embedding = row["embedding"]
+            similarity = cosine_similarity(user_embedding, memory_embedding)
+            if similarity > SIMILARITY_THRESHOLD:
+                new_importance = row["importance"] * REINFORCEMENT_FACTOR
+                new_access_count = row["access_count"] + 1
+            else:
+                new_importance = row["importance"] * DECAY_FACTOR
+                new_access_count = row["access_count"]
+            await conn.execute(
+                """
+                UPDATE memories
+                SET importance = $1, access_count = $2
+                WHERE id = $3
+                """,
+                new_importance,
+                new_access_count,
+                row["id"],
+            )
+
+
+async def prune_memories(deps: Deps):
+    async with deps.pool.acquire() as conn:
+        rows = await conn.fetch(
+            """
+            SELECT id, importance, access_count
+            FROM memories
+            ORDER BY importance DESC
+            OFFSET $1
+            """,
+            MAX_DEPTH,
+        )
+        for row in rows:
+            await conn.execute("DELETE FROM memories WHERE id = $1", row["id"])
+
+
+async def display_memory_tree(deps: Deps) -> str:
+    async with deps.pool.acquire() as conn:
+        rows = await conn.fetch(
+            """
+            SELECT content, summary, importance, access_count
+            FROM memories
+            ORDER BY importance DESC
+            LIMIT $1
+            """,
+            MAX_DEPTH,
+        )
+    result = ""
+    for row in rows:
+        effective_importance = row["importance"] * (
+            1 + math.log(row["access_count"] + 1)
+        )
+        summary = row["summary"] or row["content"]
+        result += f"- {summary} (Importance: {effective_importance:.2f})\n"
+    return result
+
+
+@mcp.tool
+async def remember(
+    contents: Annotated[
+        list[str], Field(description="List of observations or memories to store")
+    ],
+):
+    deps = Deps(openai=AsyncOpenAI(), pool=await get_db_pool())
+    try:
+        return "\n".join(
+            await asyncio.gather(*[add_memory(content, deps) for content in contents])
+        )
+    finally:
+        await deps.pool.close()
+
+
+@mcp.tool
+async def read_profile() -> str:
+    deps = Deps(openai=AsyncOpenAI(), pool=await get_db_pool())
+    profile = await display_memory_tree(deps)
+    await deps.pool.close()
+    return profile
+
+
+async def initialize_database():
+    pool = await asyncpg.create_pool(
+        "postgresql://postgres:postgres@localhost:54320/postgres"
+    )
+    try:
+        async with pool.acquire() as conn:
+            await conn.execute("""
+                SELECT pg_terminate_backend(pg_stat_activity.pid)
+                FROM pg_stat_activity
+                WHERE pg_stat_activity.datname = 'memory_db'
+                AND pid <> pg_backend_pid();
+            """)
+            await conn.execute("DROP DATABASE IF EXISTS memory_db;")
+            await conn.execute("CREATE DATABASE memory_db;")
+    finally:
+        await pool.close()
+
+    pool = await asyncpg.create_pool(DB_DSN)
+    try:
+        async with pool.acquire() as conn:
+            await conn.execute("CREATE EXTENSION IF NOT EXISTS vector;")
+
+            await register_vector(conn)
+
+            await conn.execute("""
+                CREATE TABLE IF NOT EXISTS memories (
+                    id SERIAL PRIMARY KEY,
+                    content TEXT NOT NULL,
+                    summary TEXT,
+                    importance REAL NOT NULL,
+                    access_count INT NOT NULL,
+                    timestamp DOUBLE PRECISION NOT NULL,
+                    embedding vector(1536) NOT NULL
+                );
+                CREATE INDEX IF NOT EXISTS idx_memories_embedding ON memories USING hnsw (embedding vector_l2_ops);
+            """)
+    finally:
+        await pool.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(initialize_database())
diff --git a/examples/mount_example.fastmcp.json b/examples/mount_example.fastmcp.json
new file mode 100644
index 0000000..d30d2e3
--- /dev/null
+++ b/examples/mount_example.fastmcp.json
@@ -0,0 +1,4 @@
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "entrypoint": "mount_example.py"
+}
diff --git a/examples/mount_example.py b/examples/mount_example.py
new file mode 100644
index 0000000..5844ebe
--- /dev/null
+++ b/examples/mount_example.py
@@ -0,0 +1,111 @@
+"""Example of mounting FastMCP apps together.
+
+This example demonstrates how to mount FastMCP apps together. It shows how to:
+
+1. Create sub-applications for different domains
+2. Mount those sub-applications to a main application
+3. Access tools with prefixed names and resources with prefixed URIs
+"""
+
+import asyncio
+from urllib.parse import urlparse
+
+from fastmcp import FastMCP
+
+# Weather sub-application
+weather_app = FastMCP("Weather App")
+
+
+@weather_app.tool
+def get_weather_forecast(location: str) -> str:
+    """Get the weather forecast for a location."""
+    return f"Sunny skies for {location} today!"
+
+
+@weather_app.resource(uri="weather://forecast")
+async def weather_data():
+    """Return current weather data."""
+    return {"temperature": 72, "conditions": "sunny", "humidity": 45, "wind_speed": 5}
+
+
+# News sub-application
+news_app = FastMCP("News App")
+
+
+@news_app.tool
+def get_news_headlines() -> list[str]:
+    """Get the latest news headlines."""
+    return [
+        "Tech company launches new product",
+        "Local team wins championship",
+        "Scientists make breakthrough discovery",
+    ]
+
+
+@news_app.resource(uri="news://headlines")
+async def news_data():
+    """Return latest news data."""
+    return {
+        "top_story": "Breaking news: Important event happened",
+        "categories": ["politics", "sports", "technology"],
+        "sources": ["AP", "Reuters", "Local Sources"],
+    }
+
+
+# Main application
+app = FastMCP("Main App")
+
+
+@app.tool
+def check_app_status() -> dict[str, str]:
+    """Check the status of the main application."""
+    return {"status": "running", "version": "1.0.0", "uptime": "3h 24m"}
+
+
+# Mount sub-applications
+app.mount(server=weather_app, namespace="weather")
+
+app.mount(server=news_app, namespace="news")
+
+
+async def get_server_details():
+    """Print information about mounted resources."""
+    # Print available tools
+    tools = await app.list_tools()
+    print(f"\nAvailable tools ({len(tools)}):")
+    for tool in tools:
+        print(f"  - {tool.name}: {tool.description}")
+
+    # Print available resources
+    print("\nAvailable resources:")
+
+    # Distinguish between native and imported resources
+    # Native resources would be those directly in the main app (not prefixed)
+
+    resources = await app.list_resources()
+
+    native_resources = [
+        str(r.uri)
+        for r in resources
+        if urlparse(str(r.uri)).netloc not in ("weather", "news")
+    ]
+
+    # Imported resources - categorized by source app
+    weather_resources = [
+        str(r.uri) for r in resources if urlparse(str(r.uri)).netloc == "weather"
+    ]
+    news_resources = [
+        str(r.uri) for r in resources if urlparse(str(r.uri)).netloc == "news"
+    ]
+
+    print(f"  - Native app resources: {native_resources}")
+    print(f"  - Imported from weather app: {weather_resources}")
+    print(f"  - Imported from news app: {news_resources}")
+
+
+if __name__ == "__main__":
+    # First run our async function to display info
+    asyncio.run(get_server_details())
+
+    # Then start the server (uncomment to run the server)
+    app.run()
diff --git a/examples/namespace_activation/README.md b/examples/namespace_activation/README.md
new file mode 100644
index 0000000..3dffb14
--- /dev/null
+++ b/examples/namespace_activation/README.md
@@ -0,0 +1,55 @@
+# Namespace Activation
+
+Demonstrates session-specific visibility control using tags to organize tools into namespaces that can be activated on demand.
+
+## Pattern
+
+1. Tag tools with namespaces: `@server.tool(tags={"namespace:finance"})`
+2. Globally disable namespaces: `server.disable(tags={"namespace:finance"})`
+3. Provide activation tools that call `ctx.enable_components(tags={"namespace:finance"})`
+
+Each session starts with only the activation tools visible. When a session calls an activation tool, that namespace becomes visible **only for that session**.
+
+## Run
+
+```bash
+# Server
+uv run python server.py
+
+# Client (in another terminal)
+uv run python client.py
+```
+
+## Example Output
+
+```
+Namespace Activation Demo
+
+╭─────────────────── Initial Tools ───────────────────╮
+│ activate_finance, activate_admin, deactivate_all    │
+╰─────────────────────────────────────────────────────╯
+
+→ Calling activate_finance()
+  Finance tools activated
+╭─────────────── After Activating Finance ────────────╮
+│ analyze_portfolio, get_market_data, execute_trade,  │
+│ activate_finance, activate_admin, deactivate_all    │
+╰─────────────────────────────────────────────────────╯
+
+→ Calling get_market_data(symbol='AAPL')
+  {'symbol': 'AAPL', 'price': 150.25, 'change': '+2.5%'}
+
+→ Calling activate_admin()
+  Admin tools activated
+╭────────────── After Activating Admin ───────────────╮
+│ analyze_portfolio, get_market_data, execute_trade,  │
+│ list_users, reset_user_password, activate_finance,  │
+│ activate_admin, deactivate_all                      │
+╰─────────────────────────────────────────────────────╯
+
+→ Calling deactivate_all()
+  All namespaces deactivated
+╭────────────── After Deactivating All ───────────────╮
+│ activate_finance, activate_admin, deactivate_all    │
+╰─────────────────────────────────────────────────────╯
+```
diff --git a/examples/namespace_activation/client.py b/examples/namespace_activation/client.py
new file mode 100644
index 0000000..7090f27
--- /dev/null
+++ b/examples/namespace_activation/client.py
@@ -0,0 +1,76 @@
+"""
+Namespace Activation Client
+
+Demonstrates how session-specific visibility works from the client perspective.
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+from rich import print
+from rich.panel import Panel
+
+from fastmcp import Client
+
+
+def load_server():
+    """Load the example server."""
+    examples_dir = Path(__file__).parent
+    if str(examples_dir) not in sys.path:
+        sys.path.insert(0, str(examples_dir))
+
+    import server as server_module
+
+    return server_module.server
+
+
+server = load_server()
+
+
+def show_tools(tools: list, title: str) -> None:
+    """Display available tools in a panel."""
+    tool_names = [f"[cyan]{t.name}[/]" for t in tools]
+    print(Panel(", ".join(tool_names) or "[dim]No tools[/]", title=title))
+
+
+async def main():
+    print("\n[bold]Namespace Activation Demo[/]\n")
+
+    async with Client(server) as client:
+        # Initially only activation tools are visible
+        tools = await client.list_tools()
+        show_tools(tools, "Initial Tools")
+
+        # Activate finance namespace
+        print("\n[yellow]→ Calling activate_finance()[/]")
+        result = await client.call_tool("activate_finance", {})
+        print(f"  [green]{result.data}[/]")
+
+        tools = await client.list_tools()
+        show_tools(tools, "After Activating Finance")
+
+        # Use a finance tool
+        print("\n[yellow]→ Calling get_market_data(symbol='AAPL')[/]")
+        result = await client.call_tool("get_market_data", {"symbol": "AAPL"})
+        print(f"  [green]{result.data}[/]")
+
+        # Activate admin namespace too
+        print("\n[yellow]→ Calling activate_admin()[/]")
+        result = await client.call_tool("activate_admin", {})
+        print(f"  [green]{result.data}[/]")
+
+        tools = await client.list_tools()
+        show_tools(tools, "After Activating Admin")
+
+        # Deactivate all - back to defaults
+        print("\n[yellow]→ Calling deactivate_all()[/]")
+        result = await client.call_tool("deactivate_all", {})
+        print(f"  [green]{result.data}[/]")
+
+        tools = await client.list_tools()
+        show_tools(tools, "After Deactivating All")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/namespace_activation/server.py b/examples/namespace_activation/server.py
new file mode 100644
index 0000000..f906d9f
--- /dev/null
+++ b/examples/namespace_activation/server.py
@@ -0,0 +1,73 @@
+"""
+Namespace Activation Server
+
+Tools are organized into namespaces using tags, globally disabled by default,
+and selectively enabled per-session via activation tools.
+"""
+
+from fastmcp import FastMCP
+from fastmcp.server.context import Context
+
+server = FastMCP("Multi-Domain Assistant")
+
+
+# Finance namespace
+@server.tool(tags={"namespace:finance"})
+def analyze_portfolio(symbols: list[str]) -> str:
+    """Analyze a portfolio of stock symbols."""
+    return f"Portfolio analysis for: {', '.join(symbols)}"
+
+
+@server.tool(tags={"namespace:finance"})
+def get_market_data(symbol: str) -> dict:
+    """Get current market data for a symbol."""
+    return {"symbol": symbol, "price": 150.25, "change": "+2.5%"}
+
+
+@server.tool(tags={"namespace:finance"})
+def execute_trade(symbol: str, quantity: int, side: str) -> str:
+    """Execute a trade (simulated)."""
+    return f"Executed {side} order: {quantity} shares of {symbol}"
+
+
+# Admin namespace
+@server.tool(tags={"namespace:admin"})
+def list_users() -> list[str]:
+    """List all system users."""
+    return ["alice", "bob", "charlie"]
+
+
+@server.tool(tags={"namespace:admin"})
+def reset_user_password(username: str) -> str:
+    """Reset a user's password (simulated)."""
+    return f"Password reset for {username}"
+
+
+# Activation tools - always visible
+@server.tool
+async def activate_finance(ctx: Context) -> str:
+    """Activate finance tools for this session."""
+    await ctx.enable_components(tags={"namespace:finance"})
+    return "Finance tools activated"
+
+
+@server.tool
+async def activate_admin(ctx: Context) -> str:
+    """Activate admin tools for this session."""
+    await ctx.enable_components(tags={"namespace:admin"})
+    return "Admin tools activated"
+
+
+@server.tool
+async def deactivate_all(ctx: Context) -> str:
+    """Deactivate all namespaces, returning to defaults."""
+    await ctx.reset_visibility()
+    return "All namespaces deactivated"
+
+
+# Globally disable namespace tools by default
+server.disable(tags={"namespace:finance", "namespace:admin"})
+
+
+if __name__ == "__main__":
+    server.run()
diff --git a/examples/persistent_state/README.md b/examples/persistent_state/README.md
new file mode 100644
index 0000000..efe5579
--- /dev/null
+++ b/examples/persistent_state/README.md
@@ -0,0 +1,51 @@
+# Persistent Session State
+
+This example demonstrates session-scoped state that persists across tool calls within the same MCP session.
+
+## What it shows
+
+- State set in one tool call is readable in subsequent calls
+- Different clients have isolated state (same keys, different values)
+- Reconnecting creates a new session with fresh state
+
+## Running
+
+**HTTP transport:**
+
+```bash
+# Terminal 1: Start the server
+uv run python server.py
+
+# Terminal 2: Run the client
+uv run python client.py
+```
+
+**STDIO transport (in-process):**
+
+```bash
+uv run python client_stdio.py
+```
+
+## Example output
+
+```text
+Each line below is a separate tool call
+
+Alice connects
+  session a9f6eaa3
+  set user = Alice
+  set secret = alice-password
+  get user → Alice
+  get secret → alice-password
+
+Bob connects (different session)
+  session 0c3bffc5
+  get user → not found
+  get secret → not found
+  set user = Bob
+  get user → Bob
+
+Alice reconnects (new session)
+  session e39640e3
+  get user → not found
+```
diff --git a/examples/persistent_state/client.py b/examples/persistent_state/client.py
new file mode 100644
index 0000000..a5bb636
--- /dev/null
+++ b/examples/persistent_state/client.py
@@ -0,0 +1,85 @@
+"""Client for testing persistent state.
+
+Run the server first:
+    uv run python examples/persistent_state/server.py
+
+Then run this client:
+    uv run python examples/persistent_state/client.py
+"""
+
+import asyncio
+
+from rich.console import Console
+
+from fastmcp import Client
+from fastmcp.client.transports import StreamableHttpTransport
+
+URL = "http://127.0.0.1:8000/mcp"
+console = Console()
+
+
+async def main() -> None:
+    console.print()
+    console.print("[dim italic]Each line below is a separate tool call[/dim italic]")
+    console.print()
+
+    # --- Alice's session ---
+    console.print("[dim]Alice connects[/dim]")
+
+    transport1 = StreamableHttpTransport(url=URL)
+    async with Client(transport=transport1) as alice:
+        result = await alice.call_tool("list_session_info", {})
+        console.print(f"  session [cyan]{result.data['session_id'][:8]}[/cyan]")
+
+        await alice.call_tool("set_value", {"key": "user", "value": "Alice"})
+        console.print("  set [white]user[/white] = [green]Alice[/green]")
+
+        await alice.call_tool("set_value", {"key": "secret", "value": "alice-password"})
+        console.print("  set [white]secret[/white] = [green]alice-password[/green]")
+
+        result = await alice.call_tool("get_value", {"key": "user"})
+        console.print("  get [white]user[/white] → [green]Alice[/green]")
+
+        result = await alice.call_tool("get_value", {"key": "secret"})
+        console.print("  get [white]secret[/white] → [green]alice-password[/green]")
+
+    console.print()
+
+    # --- Bob's session ---
+    console.print("[dim]Bob connects (different session)[/dim]")
+
+    transport2 = StreamableHttpTransport(url=URL)
+    async with Client(transport=transport2) as bob:
+        result = await bob.call_tool("list_session_info", {})
+        console.print(f"  session [cyan]{result.data['session_id'][:8]}[/cyan]")
+
+        await bob.call_tool("get_value", {"key": "user"})
+        console.print("  get [white]user[/white] → [dim]not found[/dim]")
+
+        await bob.call_tool("get_value", {"key": "secret"})
+        console.print("  get [white]secret[/white] → [dim]not found[/dim]")
+
+        await bob.call_tool("set_value", {"key": "user", "value": "Bob"})
+        console.print("  set [white]user[/white] = [green]Bob[/green]")
+
+        await bob.call_tool("get_value", {"key": "user"})
+        console.print("  get [white]user[/white] → [green]Bob[/green]")
+
+    console.print()
+
+    # --- Alice reconnects ---
+    console.print("[dim]Alice reconnects (new session)[/dim]")
+
+    transport3 = StreamableHttpTransport(url=URL)
+    async with Client(transport=transport3) as alice_again:
+        result = await alice_again.call_tool("list_session_info", {})
+        console.print(f"  session [cyan]{result.data['session_id'][:8]}[/cyan]")
+
+        await alice_again.call_tool("get_value", {"key": "user"})
+        console.print("  get [white]user[/white] → [dim]not found[/dim]")
+
+    console.print()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/persistent_state/client_stdio.py b/examples/persistent_state/client_stdio.py
new file mode 100644
index 0000000..5264a80
--- /dev/null
+++ b/examples/persistent_state/client_stdio.py
@@ -0,0 +1,88 @@
+"""Client for testing persistent state over STDIO.
+
+Run directly:
+    uv run python examples/persistent_state/client_stdio.py
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+from rich.console import Console
+
+from fastmcp import Client, FastMCP
+
+# Add parent directory to path for importing the server module
+examples_dir: Path = Path(__file__).parent.parent.parent
+if str(examples_dir) not in sys.path:
+    sys.path.insert(0, str(examples_dir))
+
+import examples.persistent_state.server as server_module  # noqa: E402
+
+server: FastMCP = server_module.server
+
+console: Console = Console()
+
+
+async def main() -> None:
+    console.print()
+    console.print("[dim italic]Each line below is a separate tool call[/dim italic]")
+    console.print()
+
+    # --- Alice's session ---
+    console.print("[dim]Alice connects[/dim]")
+
+    async with Client(server) as alice:
+        result = await alice.call_tool("list_session_info", {})
+        console.print(f"  session [cyan]{result.data['session_id'][:8]}[/cyan]")
+
+        await alice.call_tool("set_value", {"key": "user", "value": "Alice"})
+        console.print("  set [white]user[/white] = [green]Alice[/green]")
+
+        await alice.call_tool("set_value", {"key": "secret", "value": "alice-password"})
+        console.print("  set [white]secret[/white] = [green]alice-password[/green]")
+
+        await alice.call_tool("get_value", {"key": "user"})
+        console.print("  get [white]user[/white] → [green]Alice[/green]")
+
+        await alice.call_tool("get_value", {"key": "secret"})
+        console.print("  get [white]secret[/white] → [green]alice-password[/green]")
+
+    console.print()
+
+    # --- Bob's session ---
+    console.print("[dim]Bob connects (different session)[/dim]")
+
+    async with Client(server) as bob:
+        result = await bob.call_tool("list_session_info", {})
+        console.print(f"  session [cyan]{result.data['session_id'][:8]}[/cyan]")
+
+        await bob.call_tool("get_value", {"key": "user"})
+        console.print("  get [white]user[/white] → [dim]not found[/dim]")
+
+        await bob.call_tool("get_value", {"key": "secret"})
+        console.print("  get [white]secret[/white] → [dim]not found[/dim]")
+
+        await bob.call_tool("set_value", {"key": "user", "value": "Bob"})
+        console.print("  set [white]user[/white] = [green]Bob[/green]")
+
+        await bob.call_tool("get_value", {"key": "user"})
+        console.print("  get [white]user[/white] → [green]Bob[/green]")
+
+    console.print()
+
+    # --- Alice reconnects ---
+    console.print("[dim]Alice reconnects (new session)[/dim]")
+
+    async with Client(server) as alice_again:
+        result = await alice_again.call_tool("list_session_info", {})
+        console.print(f"  session [cyan]{result.data['session_id'][:8]}[/cyan]")
+
+        await alice_again.call_tool("get_value", {"key": "user"})
+        console.print("  get [white]user[/white] → [dim]not found[/dim]")
+
+    console.print()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/persistent_state/server.py b/examples/persistent_state/server.py
new file mode 100644
index 0000000..df44cd9
--- /dev/null
+++ b/examples/persistent_state/server.py
@@ -0,0 +1,42 @@
+"""Example: Persistent session-scoped state.
+
+This demonstrates using Context.get_state() and set_state() to store
+data that persists across tool calls within the same MCP session.
+
+Run with:
+    uv run python examples/persistent_state/server.py
+"""
+
+from fastmcp import FastMCP
+from fastmcp.server.context import Context
+
+server = FastMCP("StateExample")
+
+
+@server.tool
+async def set_value(key: str, value: str, ctx: Context) -> str:
+    """Store a value in session state."""
+    await ctx.set_state(key, value)
+    return f"Stored '{key}' = '{value}'"
+
+
+@server.tool
+async def get_value(key: str, ctx: Context) -> str:
+    """Retrieve a value from session state."""
+    value = await ctx.get_state(key)
+    if value is None:
+        return f"Key '{key}' not found"
+    return f"'{key}' = '{value}'"
+
+
+@server.tool
+async def list_session_info(ctx: Context) -> dict[str, str | None]:
+    """Get information about the current session."""
+    return {
+        "session_id": ctx.session_id,
+        "transport": ctx.transport,
+    }
+
+
+if __name__ == "__main__":
+    server.run(transport="streamable-http")
diff --git a/examples/prompts_as_tools/client.py b/examples/prompts_as_tools/client.py
new file mode 100644
index 0000000..43f9bb4
--- /dev/null
+++ b/examples/prompts_as_tools/client.py
@@ -0,0 +1,77 @@
+"""Example: Client using prompts-as-tools.
+
+This client demonstrates calling the list_prompts and get_prompt tools
+generated by the PromptsAsTools transform.
+
+Run with:
+    uv run python examples/prompts_as_tools/client.py
+"""
+
+import asyncio
+import json
+
+from fastmcp.client import Client
+
+
+async def main():
+    # Connect to the server
+    async with Client("examples/prompts_as_tools/server.py") as client:
+        # List all available tools
+        print("=== Available Tools ===")
+        tools = await client.list_tools()
+        for tool in tools:
+            print(f"  - {tool.name}: {tool.description}")
+        print()
+
+        # Use list_prompts tool to see what's available
+        print("=== Listing Prompts ===")
+        result = await client.call_tool("list_prompts", {})
+        prompts = json.loads(result.data)
+
+        for prompt in prompts:
+            print(f"  {prompt['name']}")
+            print(f"    Description: {prompt.get('description', 'N/A')}")
+            if prompt["arguments"]:
+                print("    Arguments:")
+                for arg in prompt["arguments"]:
+                    required = "required" if arg["required"] else "optional"
+                    print(
+                        f"      - {arg['name']} ({required}): {arg.get('description', 'N/A')}"
+                    )
+            print()
+
+        # Get a prompt without optional arguments
+        print("=== Getting Simple Prompt ===")
+        result = await client.call_tool(
+            "get_prompt",
+            {"name": "explain_concept", "arguments": {"concept": "recursion"}},
+        )
+        response = json.loads(result.data)
+        print("Messages:")
+        for msg in response["messages"]:
+            print(f"  Role: {msg['role']}")
+            print(f"  Content: {msg['content'][:100]}...")
+        print()
+
+        # Get a prompt with optional arguments
+        print("=== Getting Prompt with Optional Arguments ===")
+        result = await client.call_tool(
+            "get_prompt",
+            {
+                "name": "analyze_code",
+                "arguments": {
+                    "code": "def factorial(n):\n    return n * factorial(n-1)",
+                    "language": "python",
+                    "focus": "bugs",
+                },
+            },
+        )
+        response = json.loads(result.data)
+        print("Messages:")
+        for msg in response["messages"]:
+            print(f"  Role: {msg['role']}")
+            print(f"  Content: {msg['content'][:150]}...")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/prompts_as_tools/server.py b/examples/prompts_as_tools/server.py
new file mode 100644
index 0000000..912ef03
--- /dev/null
+++ b/examples/prompts_as_tools/server.py
@@ -0,0 +1,86 @@
+"""Example: Expose prompts as tools using PromptsAsTools transform.
+
+This example shows how to use PromptsAsTools to make prompts accessible
+to clients that only support tools (not the prompts protocol).
+
+Run with:
+    uv run python examples/prompts_as_tools/server.py
+"""
+
+from fastmcp import FastMCP
+from fastmcp.server.transforms import PromptsAsTools
+
+mcp = FastMCP("Prompt Tools Demo")
+
+
+# Simple prompt without arguments
+@mcp.prompt
+def explain_concept(concept: str) -> str:
+    """Explain a programming concept."""
+    return f"""Please explain the following programming concept in simple terms:
+
+{concept}
+
+Include:
+- A clear definition
+- Common use cases
+- A simple example
+"""
+
+
+# Prompt with multiple arguments
+@mcp.prompt
+def analyze_code(code: str, language: str = "python", focus: str = "all") -> str:
+    """Analyze code for potential issues."""
+    return f"""Analyze this {language} code:
+
+```{language}
+{code}
+```
+
+Focus on: {focus}
+
+Please identify:
+- Potential bugs or errors
+- Performance issues
+- Code style improvements
+- Security concerns
+"""
+
+
+# Prompt with required and optional arguments
+@mcp.prompt
+def review_pull_request(
+    title: str, description: str, diff: str, guidelines: str = ""
+) -> str:
+    """Review a pull request."""
+    guidelines_section = (
+        f"\n\nGuidelines to follow:\n{guidelines}" if guidelines else ""
+    )
+
+    return f"""Review this pull request:
+
+**Title:** {title}
+
+**Description:**
+{description}
+
+**Diff:**
+```
+{diff}
+```{guidelines_section}
+
+Please provide:
+- Summary of changes
+- Potential issues or concerns
+- Suggestions for improvement
+- Overall recommendation (approve/request changes)
+"""
+
+
+# Add the transform - this creates list_prompts and get_prompt tools
+mcp.add_transform(PromptsAsTools(mcp))
+
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/providers/sqlite/README.md b/examples/providers/sqlite/README.md
new file mode 100644
index 0000000..9175a5e
--- /dev/null
+++ b/examples/providers/sqlite/README.md
@@ -0,0 +1,59 @@
+# Dynamic Tools from SQLite
+
+This example demonstrates serving MCP tools from a database. Tools can be added, modified, or disabled by updating the database - no server restart required.
+
+## Structure
+
+- `tools.db` - SQLite database with tool configurations (committed for convenience)
+- `setup_db.py` - Script to create/reset the database
+- `server.py` - MCP server that loads tools from the database
+
+## Usage
+
+```bash
+# Reset the database (optional - tools.db is pre-seeded)
+uv run examples/providers/sqlite/setup_db.py
+
+# Run the server
+uv run fastmcp run examples/providers/sqlite/server.py
+```
+
+## How It Works
+
+The `SQLiteToolProvider` queries the database on every `list_tools` and `call_tool` request:
+
+```python
+class SQLiteToolProvider(BaseToolProvider):
+    async def list_tools(self) -> list[Tool]:
+        # Query database for enabled tools
+        ...
+
+    async def get_tool(self, name: str) -> Tool | None:
+        # Efficient single-tool lookup
+        ...
+```
+
+Tools are defined as `ConfigurableTool` subclasses that combine schema and execution:
+
+```python
+class ConfigurableTool(Tool):
+    operation: str  # "add", "multiply", etc.
+
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
+        # Execute based on configured operation
+        ...
+```
+
+## Modifying Tools at Runtime
+
+While the server is running, you can modify tools in the database:
+
+```bash
+# Add a new tool
+sqlite3 examples/providers/sqlite/tools.db "INSERT INTO tools VALUES ('subtract_numbers', 'Subtract two numbers', '{\"type\":\"object\",\"properties\":{\"a\":{\"type\":\"number\"},\"b\":{\"type\":\"number\"}},\"required\":[\"a\",\"b\"]}', 'subtract', 0, 1)"
+
+# Disable a tool
+sqlite3 examples/providers/sqlite/tools.db "UPDATE tools SET enabled = 0 WHERE name = 'divide_numbers'"
+```
+
+The next `list_tools` or `call_tool` request will reflect these changes.
diff --git a/examples/providers/sqlite/server.py b/examples/providers/sqlite/server.py
new file mode 100644
index 0000000..dd9f19f
--- /dev/null
+++ b/examples/providers/sqlite/server.py
@@ -0,0 +1,137 @@
+# /// script
+# dependencies = ["aiosqlite", "fastmcp"]
+# ///
+"""
+MCP server with database-configured tools.
+
+Tools are loaded from tools.db on each request, so you can add/modify/disable
+tools in the database without restarting the server.
+
+Run with: uv run fastmcp run examples/providers/sqlite/server.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+import aiosqlite
+from rich import print
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.providers import Provider
+from fastmcp.tools.tool import Tool, ToolResult
+
+DB_PATH = Path(__file__).parent / "tools.db"
+
+
+class ConfigurableTool(Tool):
+    """A tool that performs a configured arithmetic operation.
+
+    This demonstrates the pattern: Tool subclass = schema + execution in one place.
+    """
+
+    operation: str  # "add", "multiply", "subtract", "divide"
+    default_value: float = 0
+
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
+        a = arguments.get("a", self.default_value)
+        b = arguments.get("b", self.default_value)
+
+        if self.operation == "add":
+            result = a + b
+        elif self.operation == "multiply":
+            result = a * b
+        elif self.operation == "subtract":
+            result = a - b
+        elif self.operation == "divide":
+            if b == 0:
+                return ToolResult(
+                    structured_content={
+                        "error": "Division by zero",
+                        "operation": self.operation,
+                    }
+                )
+            result = a / b
+        else:
+            result = a + b
+
+        return ToolResult(
+            structured_content={"result": result, "operation": self.operation}
+        )
+
+
+class SQLiteToolProvider(Provider):
+    """Queries SQLite for tool configurations.
+
+    Called on every list_tools/get_tool request, so database changes
+    are reflected immediately without server restart.
+    """
+
+    def __init__(self, db_path: str):
+        super().__init__()
+        self.db_path = db_path
+
+    async def list_tools(self) -> Sequence[Tool]:
+        async with aiosqlite.connect(self.db_path) as db:
+            db.row_factory = aiosqlite.Row
+            async with db.execute("SELECT * FROM tools WHERE enabled = 1") as cursor:
+                rows = await cursor.fetchall()
+                return [self._make_tool(row) for row in rows]
+
+    async def get_tool(self, name: str) -> Tool | None:
+        async with aiosqlite.connect(self.db_path) as db:
+            db.row_factory = aiosqlite.Row
+            async with db.execute(
+                "SELECT * FROM tools WHERE name = ? AND enabled = 1", (name,)
+            ) as cursor:
+                row = await cursor.fetchone()
+                return self._make_tool(row) if row else None
+
+    def _make_tool(self, row: aiosqlite.Row) -> ConfigurableTool:
+        return ConfigurableTool(
+            name=row["name"],
+            description=row["description"],
+            parameters=json.loads(row["parameters_schema"]),
+            operation=row["operation"],
+            default_value=row["default_value"] or 0,
+        )
+
+
+provider = SQLiteToolProvider(db_path=str(DB_PATH))
+mcp = FastMCP("DynamicToolsServer", providers=[provider])
+
+
+@mcp.tool
+def server_info() -> dict[str, str]:
+    """Get information about this server (static tool)."""
+    return {
+        "name": "DynamicToolsServer",
+        "description": "A server with database-configured tools",
+        "database": str(DB_PATH),
+    }
+
+
+async def main():
+    async with Client(mcp) as client:
+        tools = await client.list_tools()
+        print(f"[bold]Available tools ({len(tools)}):[/bold]")
+        for tool in tools:
+            print(f"  • {tool.name}: {tool.description}")
+
+        print()
+        print("[bold]Calling add_numbers(10, 5):[/bold]")
+        result = await client.call_tool("add_numbers", {"a": 10, "b": 5})
+        print(f"  Result: {result.structured_content}")
+
+        print()
+        print("[bold]Calling multiply_numbers(7, 6):[/bold]")
+        result = await client.call_tool("multiply_numbers", {"a": 7, "b": 6})
+        print(f"  Result: {result.structured_content}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/providers/sqlite/setup_db.py b/examples/providers/sqlite/setup_db.py
new file mode 100644
index 0000000..beeb428
--- /dev/null
+++ b/examples/providers/sqlite/setup_db.py
@@ -0,0 +1,102 @@
+# /// script
+# dependencies = ["aiosqlite"]
+# ///
+"""
+Creates and seeds the tools database.
+
+Run with: uv run examples/providers/sqlite/setup_db.py
+"""
+
+import asyncio
+import json
+from pathlib import Path
+
+import aiosqlite
+
+DB_PATH = Path(__file__).parent / "tools.db"
+
+
+async def setup_database() -> None:
+    """Create the tools table and seed with example tools."""
+    async with aiosqlite.connect(DB_PATH) as db:
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS tools (
+                name TEXT PRIMARY KEY,
+                description TEXT NOT NULL,
+                parameters_schema TEXT NOT NULL,
+                operation TEXT NOT NULL,
+                default_value REAL,
+                enabled INTEGER DEFAULT 1
+            )
+        """)
+
+        tools_data = [
+            (
+                "add_numbers",
+                "Add two numbers together",
+                json.dumps(
+                    {
+                        "type": "object",
+                        "properties": {
+                            "a": {"type": "number", "description": "First number"},
+                            "b": {"type": "number", "description": "Second number"},
+                        },
+                        "required": ["a", "b"],
+                    }
+                ),
+                "add",
+                0,
+                1,
+            ),
+            (
+                "multiply_numbers",
+                "Multiply two numbers",
+                json.dumps(
+                    {
+                        "type": "object",
+                        "properties": {
+                            "a": {"type": "number", "description": "First number"},
+                            "b": {"type": "number", "description": "Second number"},
+                        },
+                        "required": ["a", "b"],
+                    }
+                ),
+                "multiply",
+                1,
+                1,
+            ),
+            (
+                "divide_numbers",
+                "Divide two numbers",
+                json.dumps(
+                    {
+                        "type": "object",
+                        "properties": {
+                            "a": {"type": "number", "description": "Dividend"},
+                            "b": {"type": "number", "description": "Divisor"},
+                        },
+                        "required": ["a", "b"],
+                    }
+                ),
+                "divide",
+                0,
+                1,
+            ),
+        ]
+
+        await db.executemany(
+            """
+            INSERT OR REPLACE INTO tools
+            (name, description, parameters_schema, operation, default_value, enabled)
+            VALUES (?, ?, ?, ?, ?, ?)
+            """,
+            tools_data,
+        )
+        await db.commit()
+
+    print(f"Database created at: {DB_PATH}")
+    print("Seeded 3 tools: add_numbers, multiply_numbers, divide_numbers")
+
+
+if __name__ == "__main__":
+    asyncio.run(setup_database())
diff --git a/examples/resources_as_tools/client.py b/examples/resources_as_tools/client.py
new file mode 100644
index 0000000..8a23b12
--- /dev/null
+++ b/examples/resources_as_tools/client.py
@@ -0,0 +1,52 @@
+"""Example: Client using resources-as-tools.
+
+This client demonstrates calling the list_resources and read_resource tools
+generated by the ResourcesAsTools transform.
+
+Run with:
+    uv run python examples/resources_as_tools/client.py
+"""
+
+import asyncio
+import json
+
+from fastmcp.client import Client
+
+
+async def main():
+    # Connect to the server
+    async with Client("examples/resources_as_tools/server.py") as client:
+        # List all available tools
+        print("=== Available Tools ===")
+        tools = await client.list_tools()
+        for tool in tools:
+            print(f"  - {tool.name}: {tool.description}")
+        print()
+
+        # Use list_resources tool to see what's available
+        print("=== Listing Resources ===")
+        result = await client.call_tool("list_resources", {})
+        resources = json.loads(result.data)
+        for resource in resources:
+            if "uri" in resource:
+                print(f"  Static: {resource['uri']}")
+            else:
+                print(f"  Template: {resource['uri_template']}")
+            print(f"    Name: {resource['name']}")
+            print(f"    Description: {resource.get('description', 'N/A')}")
+            print()
+
+        # Read a static resource
+        print("=== Reading Static Resource ===")
+        result = await client.call_tool("read_resource", {"uri": "config://app"})
+        print(f"config://app content:\n{result.data}")
+        print()
+
+        # Read a templated resource
+        print("=== Reading Templated Resource ===")
+        result = await client.call_tool("read_resource", {"uri": "user://42/profile"})
+        print(f"user://42/profile content:\n{result.data}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/resources_as_tools/server.py b/examples/resources_as_tools/server.py
new file mode 100644
index 0000000..2514159
--- /dev/null
+++ b/examples/resources_as_tools/server.py
@@ -0,0 +1,65 @@
+"""Example: Expose resources as tools using ResourcesAsTools transform.
+
+This example shows how to use ResourcesAsTools to make resources accessible
+to clients that only support tools (not the resources protocol).
+
+Run with:
+    uv run python examples/resources_as_tools/server.py
+"""
+
+from fastmcp import FastMCP
+from fastmcp.server.transforms import ResourcesAsTools
+
+mcp = FastMCP("Resource Tools Demo")
+
+
+# Static resource - has a fixed URI
+@mcp.resource("config://app")
+def app_config() -> str:
+    """Application configuration."""
+    return """
+    {
+        "app_name": "My App",
+        "version": "1.0.0",
+        "debug": false
+    }
+    """
+
+
+# Another static resource
+@mcp.resource("readme://main")
+def readme() -> str:
+    """Project README."""
+    return """
+    # My Project
+
+    This is an example project demonstrating ResourcesAsTools.
+    """
+
+
+# Resource template - URI has placeholders
+@mcp.resource("user://{user_id}/profile")
+def user_profile(user_id: str) -> str:
+    """Get a user's profile by ID."""
+    return f"""
+    {{
+        "user_id": "{user_id}",
+        "name": "User {user_id}",
+        "email": "user{user_id}@example.com"
+    }}
+    """
+
+
+# Another template with multiple parameters
+@mcp.resource("file://{directory}/{filename}")
+def read_file(directory: str, filename: str) -> str:
+    """Read a file from a directory."""
+    return f"Contents of {directory}/{filename}"
+
+
+# Add the transform - this creates list_resources and read_resource tools
+mcp.add_transform(ResourcesAsTools(mcp))
+
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/run_with_tracing.py b/examples/run_with_tracing.py
new file mode 100755
index 0000000..f49255e
--- /dev/null
+++ b/examples/run_with_tracing.py
@@ -0,0 +1,59 @@
+#!/usr/bin/env python
+"""Run a FastMCP server with OpenTelemetry tracing enabled.
+
+Usage:
+    uv run examples/run_with_tracing.py examples/echo.py --transport sse --port 8001
+
+All arguments after the script name are passed to `fastmcp run`.
+Traces are exported via OTLP to localhost:4317.
+
+To view traces, run otel-desktop-viewer in another terminal:
+    otel-desktop-viewer
+    # Trace UI at http://localhost:8000, OTLP receiver on :4317
+
+Install otel-desktop-viewer:
+    brew install nico-barbas/brew/otel-desktop-viewer
+"""
+
+import os
+import sys
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print(__doc__)
+        sys.exit(1)
+
+    # Configure OTEL SDK before importing fastmcp
+    from opentelemetry import trace
+    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+    from opentelemetry.sdk.resources import Resource
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+    endpoint = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4317")
+    service_name = os.environ.get(
+        "OTEL_SERVICE_NAME",
+        f"fastmcp-{os.path.basename(sys.argv[1]).replace('.py', '')}",
+    )
+
+    # Set up tracer provider with OTLP exporter
+    resource = Resource.create({"service.name": service_name})
+    provider = TracerProvider(resource=resource)
+    exporter = OTLPSpanExporter(endpoint=endpoint, insecure=True)
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+    trace.set_tracer_provider(provider)
+
+    print(f"Tracing enabled → OTLP {endpoint}", flush=True)
+    print(f"Service: {service_name}", flush=True)
+    print("View traces: otel-desktop-viewer (http://localhost:8000)\n", flush=True)
+
+    # Now run fastmcp CLI
+    from fastmcp.cli.cli import app
+
+    sys.argv = ["fastmcp", "run", *sys.argv[1:]]
+    app()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/sampling/README.md b/examples/sampling/README.md
new file mode 100644
index 0000000..3f9225b
--- /dev/null
+++ b/examples/sampling/README.md
@@ -0,0 +1,62 @@
+# Sampling Examples
+
+These examples demonstrate FastMCP's sampling API, which allows server tools to request LLM completions from the client.
+
+## Prerequisites
+
+```bash
+pip install fastmcp[anthropic]
+export ANTHROPIC_API_KEY=your-key
+```
+
+Or run directly with `uv`:
+
+```bash
+uv run examples/sampling/text.py
+```
+
+## Examples
+
+### Simple Text Sampling (`text.py`)
+
+Basic sampling flow where a server tool requests an LLM completion:
+
+```bash
+uv run examples/sampling/text.py
+```
+
+### Structured Output (`structured_output.py`)
+
+Uses `result_type` to get validated Pydantic models from the LLM:
+
+```bash
+uv run examples/sampling/structured_output.py
+```
+
+### Tool Use (`tool_use.py`)
+
+Gives the LLM tools to use during sampling (calculator, time, dice):
+
+```bash
+uv run examples/sampling/tool_use.py
+```
+
+### Server Fallback (`server_fallback.py`)
+
+Configures a fallback sampling handler on the server, enabling sampling even when clients don't support it:
+
+```bash
+uv run examples/sampling/server_fallback.py
+```
+
+## Using OpenAI Instead
+
+To use OpenAI instead of Anthropic, change the handler:
+
+```python
+from fastmcp.client.sampling.handlers.openai import OpenAISamplingHandler
+
+handler = OpenAISamplingHandler(default_model="gpt-4o-mini")
+```
+
+And install with `pip install fastmcp[openai]`.
diff --git a/examples/sampling/server_fallback.py b/examples/sampling/server_fallback.py
new file mode 100644
index 0000000..1c3fb10
--- /dev/null
+++ b/examples/sampling/server_fallback.py
@@ -0,0 +1,88 @@
+# /// script
+# dependencies = ["anthropic", "fastmcp", "rich"]
+# ///
+"""
+Server-Side Fallback Handler
+
+Demonstrates configuring a sampling handler on the server. This ensures
+sampling works even when the client doesn't provide a handler.
+
+The server runs as an HTTP server that can be connected to by any MCP client.
+
+Run:
+    uv run examples/sampling/server_fallback.py
+
+Then connect with any MCP client (e.g., Claude Desktop) or test with:
+    curl http://localhost:8000/mcp/
+"""
+
+import asyncio
+
+from rich.console import Console
+from rich.panel import Panel
+
+from fastmcp import FastMCP
+from fastmcp.client.sampling.handlers.anthropic import AnthropicSamplingHandler
+from fastmcp.server.context import Context
+
+console = Console()
+
+
+# Create server with a fallback sampling handler
+# This handler is used when the client doesn't support sampling
+mcp = FastMCP(
+    "Server with Fallback Handler",
+    sampling_handler=AnthropicSamplingHandler(default_model="claude-sonnet-4-5"),
+    sampling_handler_behavior="fallback",  # Use only if client lacks sampling
+)
+
+
+@mcp.tool
+async def summarize(text: str, ctx: Context) -> str:
+    """Summarize the given text."""
+    console.print(f"[bold cyan]SERVER[/] Summarizing text ({len(text)} chars)...")
+
+    result = await ctx.sample(
+        messages=f"Summarize this text in 1-2 sentences:\n\n{text}",
+        system_prompt="You are a concise summarizer.",
+        max_tokens=150,
+    )
+
+    console.print("[bold cyan]SERVER[/] Summary complete")
+    return result.text or ""
+
+
+@mcp.tool
+async def translate(text: str, target_language: str, ctx: Context) -> str:
+    """Translate text to the target language."""
+    console.print(f"[bold cyan]SERVER[/] Translating to {target_language}...")
+
+    result = await ctx.sample(
+        messages=f"Translate to {target_language}:\n\n{text}",
+        system_prompt=f"You are a translator. Output only the {target_language} translation.",
+        max_tokens=500,
+    )
+
+    console.print("[bold cyan]SERVER[/] Translation complete")
+    return result.text or ""
+
+
+async def main():
+    console.print(
+        Panel.fit(
+            "[bold]Server-Side Fallback Handler Demo[/]\n\n"
+            "This server has a built-in Anthropic handler that activates\n"
+            "when clients don't provide their own sampling support.",
+            subtitle="server_fallback.py",
+        )
+    )
+    console.print()
+    console.print("[bold yellow]Starting HTTP server on http://localhost:8000[/]")
+    console.print("Connect with an MCP client or press Ctrl+C to stop")
+    console.print()
+
+    await mcp.run_http_async(host="localhost", port=8000)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/sampling/structured_output.py b/examples/sampling/structured_output.py
new file mode 100644
index 0000000..fa7afe7
--- /dev/null
+++ b/examples/sampling/structured_output.py
@@ -0,0 +1,110 @@
+# /// script
+# dependencies = ["anthropic", "fastmcp", "rich"]
+# ///
+"""
+Structured Output Sampling
+
+Demonstrates using `result_type` to get validated Pydantic models from an LLM.
+The server exposes a sentiment analysis tool that returns structured data.
+
+Run:
+    uv run examples/sampling/structured_output.py
+"""
+
+import asyncio
+
+from pydantic import BaseModel
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from fastmcp import Client, Context, FastMCP
+from fastmcp.client.sampling import SamplingMessage, SamplingParams
+from fastmcp.client.sampling.handlers.anthropic import AnthropicSamplingHandler
+
+console = Console()
+
+
+class LoggingAnthropicHandler(AnthropicSamplingHandler):
+    async def __call__(
+        self, messages: list[SamplingMessage], params: SamplingParams, context
+    ):  # type: ignore[override]
+        console.print("      [bold blue]SAMPLING[/] Calling Claude API...")
+        result = await super().__call__(messages, params, context)
+        console.print("      [bold blue]SAMPLING[/] Response received")
+        return result
+
+
+# Define a structured output model
+class SentimentAnalysis(BaseModel):
+    sentiment: str  # "positive", "negative", or "neutral"
+    confidence: float  # 0.0 to 1.0
+    keywords: list[str]  # Keywords that influenced the analysis
+    explanation: str  # Brief explanation of the analysis
+
+
+# Create the MCP server
+mcp = FastMCP("Sentiment Analyzer")
+
+
+@mcp.tool
+async def analyze_sentiment(text: str, ctx: Context) -> dict:
+    """Analyze the sentiment of the given text."""
+    console.print("    [bold cyan]SERVER[/] Analyzing sentiment...")
+
+    result = await ctx.sample(
+        messages=f"Analyze the sentiment of this text:\n\n{text}",
+        system_prompt="You are a sentiment analysis expert. Analyze text carefully.",
+        result_type=SentimentAnalysis,
+    )
+
+    console.print("    [bold cyan]SERVER[/] Analysis complete")
+    return result.result.model_dump()  # type: ignore[attr-defined]
+
+
+async def main():
+    console.print(
+        Panel.fit("[bold]MCP Sampling Flow Demo[/]", subtitle="structured_output.py")
+    )
+    console.print()
+
+    handler = LoggingAnthropicHandler(default_model="claude-sonnet-4-5")
+
+    async with Client(mcp, sampling_handler=handler) as client:
+        texts = [
+            "I absolutely love this product! It exceeded all my expectations.",
+            "The service was okay, nothing special but got the job done.",
+            "This is the worst experience I've ever had. Never again.",
+        ]
+
+        for text in texts:
+            console.print(f"[bold green]CLIENT[/] Analyzing: [italic]{text[:50]}...[/]")
+            console.print()
+
+            result = await client.call_tool("analyze_sentiment", {"text": text})
+            data = result.data
+
+            # Display results in a table
+            table = Table(show_header=False, box=None, padding=(0, 2))
+            table.add_column(style="bold")
+            table.add_column()
+
+            sentiment_color = {
+                "positive": "green",
+                "negative": "red",
+                "neutral": "yellow",
+            }.get(
+                data["sentiment"],
+                "white",  # type: ignore[union-attr]
+            )
+            table.add_row("Sentiment", f"[{sentiment_color}]{data['sentiment']}[/]")  # type: ignore[index]
+            table.add_row("Confidence", f"{data['confidence']:.0%}")  # type: ignore[index]
+            table.add_row("Keywords", ", ".join(data["keywords"]))  # type: ignore[index]
+            table.add_row("Explanation", data["explanation"])  # type: ignore[index]
+
+            console.print(Panel(table, border_style=sentiment_color))
+            console.print()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/sampling/text.py b/examples/sampling/text.py
new file mode 100644
index 0000000..6d354e7
--- /dev/null
+++ b/examples/sampling/text.py
@@ -0,0 +1,78 @@
+# /// script
+# dependencies = ["anthropic", "fastmcp", "rich"]
+# ///
+"""
+Simple Text Sampling
+
+Demonstrates the basic MCP sampling flow where a server tool requests
+an LLM completion from the client.
+
+Run:
+    uv run examples/sampling/text.py
+"""
+
+import asyncio
+
+from rich.console import Console
+from rich.panel import Panel
+
+from fastmcp import Client, Context, FastMCP
+from fastmcp.client.sampling import SamplingMessage, SamplingParams
+from fastmcp.client.sampling.handlers.anthropic import AnthropicSamplingHandler
+
+console = Console()
+
+
+# Create a wrapper handler that logs when the LLM is called
+class LoggingAnthropicHandler(AnthropicSamplingHandler):
+    async def __call__(
+        self, messages: list[SamplingMessage], params: SamplingParams, context
+    ):  # type: ignore[override]
+        console.print("      [bold blue]SAMPLING[/] Calling Claude API...")
+        result = await super().__call__(messages, params, context)
+        console.print("      [bold blue]SAMPLING[/] Response received")
+        return result
+
+
+# Create the MCP server
+mcp = FastMCP("Haiku Generator")
+
+
+@mcp.tool
+async def write_haiku(topic: str, ctx: Context) -> str:
+    """Write a haiku about any topic."""
+    console.print(
+        f"    [bold cyan]SERVER[/] Tool 'write_haiku' called with topic: {topic}"
+    )
+
+    result = await ctx.sample(
+        messages=f"Write a haiku about: {topic}",
+        system_prompt="You are a poet. Write only the haiku, nothing else.",
+        max_tokens=100,
+    )
+
+    console.print("    [bold cyan]SERVER[/] Returning haiku to client")
+    return result.text or ""
+
+
+async def main():
+    console.print(Panel.fit("[bold]MCP Sampling Flow Demo[/]", subtitle="text.py"))
+    console.print()
+
+    # Create the sampling handler
+    handler = LoggingAnthropicHandler(default_model="claude-sonnet-4-5")
+
+    # Connect client to server with the sampling handler
+    async with Client(mcp, sampling_handler=handler) as client:
+        console.print("[bold green]CLIENT[/] Calling tool 'write_haiku'...")
+        console.print()
+
+        result = await client.call_tool("write_haiku", {"topic": "Python programming"})
+
+        console.print()
+        console.print("[bold green]CLIENT[/] Received result:")
+        console.print(Panel(result.data, title="Haiku", border_style="green"))  # type: ignore[arg-type]
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/sampling/tool_use.py b/examples/sampling/tool_use.py
new file mode 100644
index 0000000..e7869a1
--- /dev/null
+++ b/examples/sampling/tool_use.py
@@ -0,0 +1,125 @@
+# /// script
+# dependencies = ["anthropic", "fastmcp", "rich"]
+# ///
+"""
+Sampling with Tools
+
+Demonstrates giving an LLM tools to use during sampling. The LLM can call
+helper functions to gather information before responding.
+
+Run:
+    uv run examples/sampling/tool_use.py
+"""
+
+import asyncio
+import random
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+from rich.console import Console
+from rich.panel import Panel
+
+from fastmcp import Client, Context, FastMCP
+from fastmcp.client.sampling import SamplingMessage, SamplingParams
+from fastmcp.client.sampling.handlers.anthropic import AnthropicSamplingHandler
+
+console = Console()
+
+
+class LoggingAnthropicHandler(AnthropicSamplingHandler):
+    async def __call__(
+        self, messages: list[SamplingMessage], params: SamplingParams, context
+    ):  # type: ignore[override]
+        console.print("      [bold blue]SAMPLING[/] Calling Claude API...")
+        result = await super().__call__(messages, params, context)
+        console.print("      [bold blue]SAMPLING[/] Response received")
+        return result
+
+
+# Define tools available to the LLM during sampling
+def add(a: float, b: float) -> str:
+    """Add two numbers together."""
+    result = a + b
+    console.print(f"        [bold magenta]TOOL[/] add({a}, {b}) = {result}")
+    return str(result)
+
+
+def multiply(a: float, b: float) -> str:
+    """Multiply two numbers together."""
+    result = a * b
+    console.print(f"        [bold magenta]TOOL[/] multiply({a}, {b}) = {result}")
+    return str(result)
+
+
+def get_current_time() -> str:
+    """Get the current date and time."""
+    console.print("        [bold magenta]TOOL[/] get_current_time()")
+    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+
+def roll_dice(sides: int = 6) -> str:
+    """Roll a die with the specified number of sides."""
+    result = random.randint(1, sides)
+    console.print(f"        [bold magenta]TOOL[/] roll_dice({sides}) = {result}")
+    return str(result)
+
+
+# Structured output for the response
+class AssistantResponse(BaseModel):
+    answer: str = Field(description="The answer to the user's question")
+    tools_used: list[str] = Field(description="List of tools that were used")
+    reasoning: str = Field(
+        description="Brief explanation of how the answer was determined"
+    )
+
+
+# Create the MCP server
+mcp = FastMCP("Smart Assistant")
+
+
+@mcp.tool
+async def ask_assistant(question: str, ctx: Context) -> dict:
+    """Ask the assistant a question. It can use tools to help answer."""
+    console.print("    [bold cyan]SERVER[/] Processing question...")
+
+    result = await ctx.sample(
+        messages=question,
+        system_prompt="You are a helpful assistant with access to tools. Use them when needed to answer questions accurately.",
+        tools=[add, multiply, get_current_time, roll_dice],
+        result_type=AssistantResponse,
+    )
+
+    console.print("    [bold cyan]SERVER[/] Response ready")
+    return result.result.model_dump()  # type: ignore[attr-defined]
+
+
+async def main():
+    console.print(Panel.fit("[bold]MCP Sampling Flow Demo[/]", subtitle="tool_use.py"))
+    console.print()
+
+    handler = LoggingAnthropicHandler(default_model="claude-sonnet-4-5")
+
+    async with Client(mcp, sampling_handler=handler) as client:
+        questions = [
+            "What is 15 times 7, plus 23?",
+            "Roll a 20-sided dice for me",
+            "What time is it right now?",
+        ]
+
+        for question in questions:
+            console.print(f"[bold green]CLIENT[/] Question: {question}")
+            console.print()
+
+            result = await client.call_tool("ask_assistant", {"question": question})
+            data = result.data
+
+            console.print(f"[bold green]CLIENT[/] Answer: {data['answer']}")  # type: ignore[index]
+            console.print(
+                f"         Tools used: {', '.join(data['tools_used']) or 'none'}"
+            )  # type: ignore[index]
+            console.print(f"         Reasoning: {data['reasoning']}")  # type: ignore[index]
+            console.print()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/screenshot.fastmcp.json b/examples/screenshot.fastmcp.json
new file mode 100644
index 0000000..9ff06d7
--- /dev/null
+++ b/examples/screenshot.fastmcp.json
@@ -0,0 +1,7 @@
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "entrypoint": "screenshot.py",
+  "environment": {
+    "dependencies": ["pyautogui", "Pillow"]
+  }
+}
diff --git a/examples/screenshot.py b/examples/screenshot.py
new file mode 100644
index 0000000..8661337
--- /dev/null
+++ b/examples/screenshot.py
@@ -0,0 +1,34 @@
+# /// script
+# dependencies = ["pyautogui", "Pillow", "fastmcp"]
+# ///
+
+"""
+FastMCP Screenshot Example
+
+Give Claude a tool to capture and view screenshots.
+"""
+
+import io
+
+from fastmcp import FastMCP
+from fastmcp.utilities.types import Image
+
+# Create server
+# Dependencies are configured in screenshot.fastmcp.json
+mcp = FastMCP("Screenshot Demo")
+
+
+@mcp.tool
+def take_screenshot() -> Image:
+    """
+    Take a screenshot of the user's screen and return it as an image. Use
+    this tool anytime the user wants you to look at something they're doing.
+    """
+    import pyautogui
+
+    buffer = io.BytesIO()
+
+    # if the file exceeds ~1MB, it will be rejected by Claude
+    screenshot = pyautogui.screenshot()
+    screenshot.convert("RGB").save(buffer, format="JPEG", quality=60, optimize=True)
+    return Image(data=buffer.getvalue(), format="jpeg")
diff --git a/examples/search/README.md b/examples/search/README.md
new file mode 100644
index 0000000..32a2639
--- /dev/null
+++ b/examples/search/README.md
@@ -0,0 +1,21 @@
+# Search Transforms
+
+When a server exposes many tools, listing them all at once can overwhelm an LLM's context window. Search transforms collapse the full tool catalog behind a search interface — clients see only `search_tools` and `call_tool`, and discover the real tools on demand.
+
+## Two search strategies
+
+**Regex** (`RegexSearchTransform`) — clients search with regex patterns like `add|multiply` or `text.*`. Fast and precise when you know what you're looking for.
+
+**BM25** (`BM25SearchTransform`) — clients search with natural language like `"work with numbers"`. Results are ranked by relevance using BM25 scoring. The index rebuilds automatically when tools change.
+
+Both strategies respect the full auth pipeline: middleware, visibility transforms, and component-level auth checks all apply to search results.
+
+## Run
+
+```bash
+# Regex
+uv run python examples/search/client_regex.py
+
+# BM25
+uv run python examples/search/client_bm25.py
+```
diff --git a/examples/search/client_bm25.py b/examples/search/client_bm25.py
new file mode 100644
index 0000000..b33e395
--- /dev/null
+++ b/examples/search/client_bm25.py
@@ -0,0 +1,152 @@
+"""Example: Client using BM25 search to discover and call tools.
+
+BM25 search accepts natural language queries instead of regex patterns.
+This client shows how relevance ranking surfaces the best matches.
+
+Run with:
+    uv run python examples/search/client_bm25.py
+"""
+
+import asyncio
+import json
+from typing import Any
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from fastmcp.client import Client
+
+console = Console()
+
+
+def _get_result(result) -> Any:
+    """Extract the value from a CallToolResult (structured or text)."""
+    if result.structured_content is not None:
+        data = result.structured_content
+        if isinstance(data, dict) and set(data) == {"result"}:
+            return data["result"]
+        return data
+    return result.content[0].text
+
+
+def _format_params(tool: dict) -> str:
+    """Format inputSchema properties as a compact signature."""
+    schema = tool.get("inputSchema", {})
+    props = schema.get("properties", {})
+    if not props:
+        return "()"
+    parts = []
+    for name, info in props.items():
+        typ = info.get("type", "")
+        parts.append(f"{name}: {typ}" if typ else name)
+    return f"({', '.join(parts)})"
+
+
+def _tool_table(
+    tools: list[dict], *, ranked: bool = False, show_params: bool = False
+) -> Table:
+    table = Table(show_header=True, show_edge=False, pad_edge=False, expand=True)
+    if ranked:
+        table.add_column("#", style="dim", width=3, justify="right")
+    table.add_column("Tool", style="cyan", no_wrap=True)
+    if show_params:
+        table.add_column("Parameters", style="dim", no_wrap=True)
+    table.add_column("Description", style="dim")
+    for i, tool in enumerate(tools, 1):
+        row = [tool["name"]]
+        if show_params:
+            row.append(_format_params(tool))
+        row.append(tool.get("description", ""))
+        if ranked:
+            row.insert(0, str(i))
+        table.add_row(*row)
+    return table
+
+
+async def main():
+    async with Client("examples/search/server_bm25.py") as client:
+        console.print()
+        console.rule("[bold]BM25 Search Transform[/bold]")
+        console.print()
+
+        # Step 1: list_tools shows only synthetic tools + pinned tools
+        console.print(
+            "The server has 8 tools. BM25SearchTransform replaces them with "
+            "just [bold]search_tools[/bold] and [bold]call_tool[/bold]. "
+            "[bold]list_files[/bold] stays visible via [dim]always_visible[/dim]:"
+        )
+        console.print()
+        tools = await client.list_tools()
+        visible = [{"name": t.name, "description": t.description} for t in tools]
+        console.print(
+            Panel(
+                _tool_table(visible),
+                title="[bold]list_tools()[/bold]",
+                title_align="left",
+                border_style="blue",
+            )
+        )
+        console.print()
+
+        # Step 2: natural language search discovers tools by relevance
+        console.print(
+            "The LLM uses [bold]search_tools[/bold] with natural language "
+            "to discover tools ranked by relevance:"
+        )
+        console.print()
+        result = await client.call_tool("search_tools", {"query": "work with numbers"})
+        found = _get_result(result)
+        if isinstance(found, str):
+            found = json.loads(found)
+        console.print(
+            Panel(
+                _tool_table(found, ranked=True, show_params=True),
+                title='[bold]search_tools[/bold]  [dim]query="work with numbers"[/dim]',
+                title_align="left",
+                border_style="green",
+            )
+        )
+        console.print()
+
+        result = await client.call_tool(
+            "search_tools", {"query": "manipulate text strings"}
+        )
+        found = _get_result(result)
+        if isinstance(found, str):
+            found = json.loads(found)
+        console.print(
+            Panel(
+                _tool_table(found, ranked=True, show_params=True),
+                title='[bold]search_tools[/bold]  [dim]query="manipulate text strings"[/dim]',
+                title_align="left",
+                border_style="green",
+            )
+        )
+        console.print()
+
+        # Step 3: call a discovered tool
+        console.print(
+            "Then the LLM calls a discovered tool through [bold]call_tool[/bold]:"
+        )
+        console.print()
+        result = await client.call_tool(
+            "call_tool",
+            {
+                "name": "word_count",
+                "arguments": {"text": "BM25 search makes tool discovery easy"},
+            },
+        )
+        console.print(
+            Panel(
+                f'call_tool(name="word_count", arguments={{"text": "BM25 search makes tool discovery easy"}})\n→ [bold green]{_get_result(result)}[/bold green]',
+                title="[bold]call_tool()[/bold]",
+                title_align="left",
+                border_style="magenta",
+            )
+        )
+        console.print()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/search/client_regex.py b/examples/search/client_regex.py
new file mode 100644
index 0000000..ccccefb
--- /dev/null
+++ b/examples/search/client_regex.py
@@ -0,0 +1,161 @@
+"""Example: Client using regex search to discover and call tools.
+
+Regex search lets clients find tools by matching patterns against tool names
+and descriptions. Precise when you know what you're looking for.
+
+Run with:
+    uv run python examples/search/client_regex.py
+"""
+
+import asyncio
+import json
+from typing import Any
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from fastmcp.client import Client
+
+console = Console()
+
+
+def _get_result(result) -> Any:
+    """Extract the value from a CallToolResult (structured or text)."""
+    if result.structured_content is not None:
+        data = result.structured_content
+        if isinstance(data, dict) and set(data) == {"result"}:
+            return data["result"]
+        return data
+    return result.content[0].text
+
+
+def _format_params(tool: dict) -> str:
+    """Format inputSchema properties as a compact signature."""
+    schema = tool.get("inputSchema", {})
+    props = schema.get("properties", {})
+    if not props:
+        return "()"
+    parts = []
+    for name, info in props.items():
+        typ = info.get("type", "")
+        parts.append(f"{name}: {typ}" if typ else name)
+    return f"({', '.join(parts)})"
+
+
+def _tool_table(
+    tools: list[dict], *, ranked: bool = False, show_params: bool = False
+) -> Table:
+    table = Table(show_header=True, show_edge=False, pad_edge=False, expand=True)
+    if ranked:
+        table.add_column("#", style="dim", width=3, justify="right")
+    table.add_column("Tool", style="cyan", no_wrap=True)
+    if show_params:
+        table.add_column("Parameters", style="dim", no_wrap=True)
+    table.add_column("Description", style="dim")
+    for i, tool in enumerate(tools, 1):
+        row = [tool["name"]]
+        if show_params:
+            row.append(_format_params(tool))
+        row.append(tool.get("description", ""))
+        if ranked:
+            row.insert(0, str(i))
+        table.add_row(*row)
+    return table
+
+
+async def main():
+    async with Client("examples/search/server_regex.py") as client:
+        console.print()
+        console.rule("[bold]Regex Search Transform[/bold]")
+        console.print()
+
+        # Step 1: list_tools shows only synthetic tools
+        console.print(
+            "The server has 6 tools. RegexSearchTransform replaces them with "
+            "just [bold]search_tools[/bold] and [bold]call_tool[/bold]:"
+        )
+        console.print()
+        tools = await client.list_tools()
+        visible = [{"name": t.name, "description": t.description} for t in tools]
+        console.print(
+            Panel(
+                _tool_table(visible),
+                title="[bold]list_tools()[/bold]",
+                title_align="left",
+                border_style="blue",
+            )
+        )
+        console.print()
+
+        # Step 2: regex patterns discover tools
+        console.print(
+            "The LLM uses [bold]search_tools[/bold] with regex patterns "
+            "to find tools by name:"
+        )
+        console.print()
+        result = await client.call_tool(
+            "search_tools", {"pattern": "add|multiply|fibonacci"}
+        )
+        found = _get_result(result)
+        if isinstance(found, str):
+            found = json.loads(found)
+        console.print(
+            Panel(
+                _tool_table(found, show_params=True),
+                title='[bold]search_tools[/bold]  [dim]pattern="add|multiply|fibonacci"[/dim]',
+                title_align="left",
+                border_style="green",
+            )
+        )
+        console.print()
+
+        result = await client.call_tool("search_tools", {"pattern": "text|string|word"})
+        found = _get_result(result)
+        if isinstance(found, str):
+            found = json.loads(found)
+        console.print(
+            Panel(
+                _tool_table(found, show_params=True),
+                title='[bold]search_tools[/bold]  [dim]pattern="text|string|word"[/dim]',
+                title_align="left",
+                border_style="green",
+            )
+        )
+        console.print()
+
+        # Step 3: call discovered tools
+        console.print(
+            "Then the LLM calls discovered tools through [bold]call_tool[/bold]:"
+        )
+        console.print()
+        result = await client.call_tool(
+            "call_tool", {"name": "add", "arguments": {"a": 17, "b": 25}}
+        )
+        console.print(
+            Panel(
+                f'call_tool(name="add", arguments={{"a": 17, "b": 25}})\n→ [bold green]{_get_result(result)}[/bold green]',
+                title="[bold]call_tool()[/bold]",
+                title_align="left",
+                border_style="magenta",
+            )
+        )
+        console.print()
+
+        result = await client.call_tool(
+            "call_tool",
+            {"name": "reverse_string", "arguments": {"text": "hello world"}},
+        )
+        console.print(
+            Panel(
+                f'call_tool(name="reverse_string", arguments={{"text": "hello world"}})\n→ [bold green]{_get_result(result)}[/bold green]',
+                title="[bold]call_tool()[/bold]",
+                title_align="left",
+                border_style="magenta",
+            )
+        )
+        console.print()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/search/server_bm25.py b/examples/search/server_bm25.py
new file mode 100644
index 0000000..63cdf80
--- /dev/null
+++ b/examples/search/server_bm25.py
@@ -0,0 +1,85 @@
+"""Example: Search transforms with BM25 relevance ranking.
+
+BM25SearchTransform uses term-frequency/inverse-document-frequency scoring
+to rank tools by relevance to a natural language query. Unlike regex search
+(which requires the user to construct a pattern), BM25 handles queries like
+"work with text" or "do math" and returns the most relevant matches.
+
+The index is built lazily and rebuilt automatically when the tool catalog
+changes (e.g. tools added or removed between requests).
+
+Run with:
+    uv run python examples/search/server_bm25.py
+"""
+
+import os
+
+from fastmcp import FastMCP
+from fastmcp.server.transforms.search import BM25SearchTransform
+
+mcp = FastMCP("BM25 Search Demo")
+
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Add two numbers together."""
+    return a + b
+
+
+@mcp.tool
+def multiply(x: float, y: float) -> float:
+    """Multiply two numbers."""
+    return x * y
+
+
+@mcp.tool
+def fibonacci(n: int) -> list[int]:
+    """Generate the first n Fibonacci numbers."""
+    if n <= 0:
+        return []
+    seq = [0, 1]
+    while len(seq) < n:
+        seq.append(seq[-1] + seq[-2])
+    return seq[:n]
+
+
+@mcp.tool
+def reverse_string(text: str) -> str:
+    """Reverse a string."""
+    return text[::-1]
+
+
+@mcp.tool
+def word_count(text: str) -> int:
+    """Count the number of words in a text."""
+    return len(text.split())
+
+
+@mcp.tool
+def to_uppercase(text: str) -> str:
+    """Convert text to uppercase."""
+    return text.upper()
+
+
+@mcp.tool
+def list_files(directory: str) -> list[str]:
+    """List files in a directory."""
+    return os.listdir(directory)
+
+
+@mcp.tool
+def read_file(path: str) -> str:
+    """Read the contents of a file."""
+    with open(path) as f:
+        return f.read()
+
+
+# BM25 search with a higher result limit for this larger catalog.
+# The `always_visible` option keeps specific tools in list_tools output
+# alongside the search/call tools — useful for tools the LLM should
+# always know about.
+mcp.add_transform(BM25SearchTransform(max_results=5, always_visible=["list_files"]))
+
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/search/server_regex.py b/examples/search/server_regex.py
new file mode 100644
index 0000000..261ef6a
--- /dev/null
+++ b/examples/search/server_regex.py
@@ -0,0 +1,74 @@
+"""Example: Search transforms with regex pattern matching.
+
+When a server has many tools, listing them all at once can overwhelm an LLM's
+context window. Search transforms collapse the full tool catalog behind a
+search interface — clients see only `search_tools` and `call_tool`, and
+discover the real tools on demand.
+
+This example registers a handful of tools and applies RegexSearchTransform.
+Clients use `search_tools` with a regex pattern to find relevant tools, then
+`call_tool` to execute them by name.
+
+Run with:
+    uv run python examples/search/server_regex.py
+"""
+
+from fastmcp import FastMCP
+from fastmcp.server.transforms.search import RegexSearchTransform
+
+mcp = FastMCP("Regex Search Demo")
+
+
+# Register a variety of tools across different domains.
+# With the search transform active, none of these appear in list_tools —
+# they're only discoverable via search.
+
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Add two numbers together."""
+    return a + b
+
+
+@mcp.tool
+def multiply(x: float, y: float) -> float:
+    """Multiply two numbers."""
+    return x * y
+
+
+@mcp.tool
+def fibonacci(n: int) -> list[int]:
+    """Generate the first n Fibonacci numbers."""
+    if n <= 0:
+        return []
+    seq = [0, 1]
+    while len(seq) < n:
+        seq.append(seq[-1] + seq[-2])
+    return seq[:n]
+
+
+@mcp.tool
+def reverse_string(text: str) -> str:
+    """Reverse a string."""
+    return text[::-1]
+
+
+@mcp.tool
+def word_count(text: str) -> int:
+    """Count the number of words in a text."""
+    return len(text.split())
+
+
+@mcp.tool
+def to_uppercase(text: str) -> str:
+    """Convert text to uppercase."""
+    return text.upper()
+
+
+# Apply the regex search transform.
+# max_results limits how many tools a single search returns.
+mcp.add_transform(RegexSearchTransform(max_results=3))
+
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/simple_echo.py b/examples/simple_echo.py
new file mode 100644
index 0000000..b1dc1f3
--- /dev/null
+++ b/examples/simple_echo.py
@@ -0,0 +1,14 @@
+"""
+FastMCP Echo Server
+"""
+
+from fastmcp import FastMCP
+
+# Create server
+mcp = FastMCP("Echo Server")
+
+
+@mcp.tool
+def echo(text: str) -> str:
+    """Echo the input text"""
+    return text
diff --git a/examples/skills/README.md b/examples/skills/README.md
new file mode 100644
index 0000000..7f5ae14
--- /dev/null
+++ b/examples/skills/README.md
@@ -0,0 +1,104 @@
+# Skills Provider Example
+
+This example demonstrates how to expose agent skills (like Claude Code skills) as MCP resources.
+
+## Structure
+
+```
+skills/
+├── README.md              # This file
+├── server.py              # MCP server that exposes skills
+├── client.py              # Example client that discovers and reads skills
+└── sample_skills/         # Example skills directory
+    ├── pdf-processing/
+    │   ├── SKILL.md       # Main skill file
+    │   └── reference.md   # Supporting documentation
+    └── code-review/
+        └── SKILL.md       # Main skill file
+```
+
+## Running the Example
+
+1. Start the server:
+   ```bash
+   uv run python examples/skills/server.py
+   ```
+
+2. In another terminal, run the client:
+   ```bash
+   uv run python examples/skills/client.py
+   ```
+
+## How It Works
+
+The skills provider system has a two-layer architecture:
+
+- **`SkillProvider`** - Handles a single skill folder, exposing its files as resources
+- **`SkillsDirectoryProvider`** - Scans a directory, creates a `SkillProvider` per folder
+- **`ClaudeSkillsProvider`** - Convenience subclass for Claude Code skills (~/.claude/skills/)
+
+For each skill, the provider exposes:
+- A **Resource** for the main file (`skill://{name}/SKILL.md`)
+- A **Resource** for a synthetic manifest (`skill://{name}/_manifest`)
+- Supporting files via **ResourceTemplate** or **Resources** (configurable)
+
+### Progressive Disclosure
+
+When a client lists resources, they see skill names and descriptions (from frontmatter) without fetching the full content. This keeps the discovery cost low.
+
+By default, supporting files are exposed via ResourceTemplate (hidden from `list_resources()`). Set `supporting_files="resources"` to make them visible:
+
+```python
+SkillsDirectoryProvider(roots=skills_dir, supporting_files="resources")
+```
+
+### The Manifest
+
+The `_manifest` resource provides a JSON listing of all files in a skill:
+
+```json
+{
+  "skill": "pdf-processing",
+  "files": [
+    {"path": "SKILL.md", "size": 1234, "hash": "sha256:abc..."},
+    {"path": "reference.md", "size": 5678, "hash": "sha256:def..."}
+  ]
+}
+```
+
+This enables clients to download entire skills for local use.
+
+## Usage Examples
+
+### Single Skill
+
+```python
+from pathlib import Path
+from fastmcp import FastMCP
+from fastmcp.server.providers.skills import SkillProvider
+
+mcp = FastMCP("My Skill")
+mcp.add_provider(SkillProvider(Path.home() / ".claude/skills/pdf-processing"))
+mcp.run()
+```
+
+### All Skills in a Directory
+
+```python
+from fastmcp.server.providers.skills import SkillsDirectoryProvider
+
+mcp = FastMCP("Skills")
+mcp.add_provider(SkillsDirectoryProvider(roots=Path.home() / ".claude" / "skills"))
+mcp.run()
+```
+
+### Claude Code Skills (default location)
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.providers.skills import ClaudeSkillsProvider
+
+mcp = FastMCP("My Skills")
+mcp.add_provider(ClaudeSkillsProvider())  # Uses ~/.claude/skills/
+mcp.run()
+```
diff --git a/examples/skills/client.py b/examples/skills/client.py
new file mode 100644
index 0000000..a376fe2
--- /dev/null
+++ b/examples/skills/client.py
@@ -0,0 +1,66 @@
+"""Example: Skills Client
+
+This example shows how to discover and download skills from a skills server.
+
+Run this client (it starts its own server internally):
+    uv run python examples/skills/client.py
+"""
+
+import asyncio
+import json
+from pathlib import Path
+
+from fastmcp import Client
+from fastmcp.server.providers.skills import SkillsDirectoryProvider
+
+
+async def main():
+    # Create a skills provider pointing at our sample skills
+    skills_dir = Path(__file__).parent / "sample_skills"
+    provider = SkillsDirectoryProvider(roots=skills_dir)
+
+    # Connect to a FastMCP server with this provider
+    from fastmcp import FastMCP
+
+    mcp = FastMCP("Skills Server")
+    mcp.add_provider(provider)
+
+    async with Client(mcp) as client:
+        print("Connected to skills server\n")
+
+        # List available resources
+        print("=== Available Resources ===")
+        resources = await client.list_resources()
+        for r in resources:
+            print(f"  {r.uri}")
+            if r.description:
+                print(f"    Description: {r.description}")
+        print()
+
+        # List resource templates
+        print("=== Resource Templates ===")
+        templates = await client.list_resource_templates()
+        for t in templates:
+            print(f"  {t.uriTemplate}")
+        print()
+
+        # Read a skill's main file
+        print("=== Reading pdf-processing/SKILL.md ===")
+        result = await client.read_resource("skill://pdf-processing/SKILL.md")
+        print(result[0].text[:500] + "...\n")
+
+        # Read the manifest to see all files
+        print("=== Reading pdf-processing/_manifest ===")
+        result = await client.read_resource("skill://pdf-processing/_manifest")
+        manifest = json.loads(result[0].text)
+        print(json.dumps(manifest, indent=2))
+        print()
+
+        # Read a supporting file via template
+        print("=== Reading pdf-processing/reference.md ===")
+        result = await client.read_resource("skill://pdf-processing/reference.md")
+        print(result[0].text[:500] + "...\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/skills/download_skills.py b/examples/skills/download_skills.py
new file mode 100644
index 0000000..69b8d03
--- /dev/null
+++ b/examples/skills/download_skills.py
@@ -0,0 +1,82 @@
+"""Example: Downloading skills from an MCP server.
+
+This example shows how to use the skills client utilities to discover
+and download skills from any MCP server that exposes them via SkillsProvider.
+
+Run this script:
+    uv run python examples/skills/download_skills.py
+
+This example creates an in-memory server with sample skills. In practice,
+you would connect to a remote server URL instead.
+"""
+
+import asyncio
+import tempfile
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.tree import Tree
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.providers.skills import SkillsDirectoryProvider
+from fastmcp.utilities.skills import list_skills, sync_skills
+
+console = Console()
+
+
+async def main():
+    # For this example, we'll create an in-memory server with skills.
+    # In practice, you'd connect to a remote server URL.
+    skills_dir = Path(__file__).parent / "sample_skills"
+    mcp = FastMCP("Skills Server")
+    mcp.add_provider(SkillsDirectoryProvider(roots=skills_dir))
+
+    async with Client(mcp) as client:
+        # 1. Discover what skills are available on the server
+        console.print()
+        console.print(
+            Panel.fit(
+                "[bold]Discovering skills on MCP server...[/bold]",
+                border_style="blue",
+            )
+        )
+
+        skills = await list_skills(client)
+
+        table = Table(title="Skills Available on Server", show_header=True)
+        table.add_column("Skill", style="cyan")
+        table.add_column("Description")
+        for skill in sorted(skills, key=lambda s: s.name):
+            table.add_row(skill.name, skill.description)
+        console.print(table)
+
+        # 2. Download all skills to a local directory
+        console.print()
+        console.print(
+            Panel.fit(
+                "[bold]Downloading all skills to local directory...[/bold]",
+                border_style="green",
+            )
+        )
+
+        with tempfile.TemporaryDirectory() as tmp:
+            paths = await sync_skills(client, tmp)
+
+            tree = Tree(f"[bold]{tmp}[/bold]")
+            for skill_path in sorted(paths, key=lambda p: p.name):
+                skill_branch = tree.add(f"[cyan]{skill_path.name}/[/cyan]")
+                for f in sorted(skill_path.rglob("*")):
+                    if f.is_file():
+                        rel = f.relative_to(skill_path)
+                        skill_branch.add(str(rel))
+
+            console.print(tree)
+            console.print(
+                f"\n[green]✓[/green] Downloaded {len(paths)} skills to local directory"
+            )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/skills/sample_skills/code-review/SKILL.md b/examples/skills/sample_skills/code-review/SKILL.md
new file mode 100644
index 0000000..0c57545
--- /dev/null
+++ b/examples/skills/sample_skills/code-review/SKILL.md
@@ -0,0 +1,40 @@
+---
+description: Review code for quality, maintainability, and correctness
+version: "1.0.0"
+tags: [code, review, quality]
+---
+
+# Code Review Skill
+
+This skill guides you through conducting thorough code reviews.
+
+## Review Checklist
+
+When reviewing code, consider:
+
+### Correctness
+- Does the code do what it's supposed to do?
+- Are edge cases handled?
+- Are there any obvious bugs?
+
+### Maintainability
+- Is the code easy to understand?
+- Are variable and function names descriptive?
+- Is there appropriate documentation?
+
+### Performance
+- Are there any obvious performance issues?
+- Are expensive operations cached when appropriate?
+- Are database queries efficient?
+
+### Security
+- Is user input validated?
+- Are there any injection vulnerabilities?
+- Are secrets properly managed?
+
+## Giving Feedback
+
+- Be specific and actionable
+- Explain *why* something should change
+- Suggest alternatives, don't just criticize
+- Acknowledge good work too
diff --git a/examples/skills/sample_skills/pdf-processing/SKILL.md b/examples/skills/sample_skills/pdf-processing/SKILL.md
new file mode 100644
index 0000000..2490f67
--- /dev/null
+++ b/examples/skills/sample_skills/pdf-processing/SKILL.md
@@ -0,0 +1,28 @@
+---
+description: Extract text from PDFs, fill forms, and merge documents
+version: "1.0.0"
+tags: [document, pdf, extraction]
+---
+
+# PDF Processing Skill
+
+This skill helps you work with PDF documents.
+
+## Capabilities
+
+- Extract text content from PDF files
+- Fill form fields in PDF documents
+- Merge multiple PDFs into one
+- Split PDFs into separate pages
+
+## Usage
+
+When working with PDFs, use the appropriate tools:
+
+1. For text extraction: Read the PDF and parse its content
+2. For forms: Identify form fields and fill them programmatically
+3. For merging: Combine multiple documents in the desired order
+
+## Additional Resources
+
+See [reference.md](reference.md) for detailed API documentation.
diff --git a/examples/skills/sample_skills/pdf-processing/reference.md b/examples/skills/sample_skills/pdf-processing/reference.md
new file mode 100644
index 0000000..7b7b329
--- /dev/null
+++ b/examples/skills/sample_skills/pdf-processing/reference.md
@@ -0,0 +1,47 @@
+# PDF Processing Reference
+
+## Text Extraction
+
+To extract text from a PDF:
+
+```python
+from pypdf import PdfReader
+
+reader = PdfReader("document.pdf")
+for page in reader.pages:
+    text = page.extract_text()
+    print(text)
+```
+
+## Form Filling
+
+PDF forms can be filled using the form fields API:
+
+```python
+from pypdf import PdfReader, PdfWriter
+
+reader = PdfReader("form.pdf")
+writer = PdfWriter()
+
+writer.append(reader)
+writer.update_page_form_field_values(
+    writer.pages[0],
+    {"field_name": "field_value"}
+)
+
+with open("filled_form.pdf", "wb") as output:
+    writer.write(output)
+```
+
+## Merging PDFs
+
+```python
+from pypdf import PdfWriter
+
+writer = PdfWriter()
+writer.append("doc1.pdf")
+writer.append("doc2.pdf")
+
+with open("merged.pdf", "wb") as output:
+    writer.write(output)
+```
diff --git a/examples/skills/server.py b/examples/skills/server.py
new file mode 100644
index 0000000..a5cd499
--- /dev/null
+++ b/examples/skills/server.py
@@ -0,0 +1,49 @@
+"""Example: Skills Provider Server
+
+This example shows how to expose agent skills as MCP resources.
+Skills can be discovered, browsed, and downloaded by any MCP client.
+
+Run this server:
+    uv run python examples/skills/server.py
+
+Then use the client example to interact with it:
+    uv run python examples/skills/client.py
+"""
+
+from pathlib import Path
+
+from fastmcp import FastMCP
+from fastmcp.server.providers.skills import (
+    SkillsDirectoryProvider,
+)
+
+# Create server
+mcp = FastMCP("Skills Server")
+
+# Option 1: Load a single skill
+# mcp.add_provider(SkillProvider(Path.home() / ".claude/skills/pdf-processing"))
+
+# Option 2: Load all skills from a custom directory
+skills_dir = Path(__file__).parent / "sample_skills"
+mcp.add_provider(SkillsDirectoryProvider(roots=skills_dir, reload=True))
+
+# Option 3: Load skills from a platform's default location
+# mcp.add_provider(ClaudeSkillsProvider())  # ~/.claude/skills/
+
+# Option 4: Load from multiple directories (in precedence order)
+# mcp.add_provider(SkillsDirectoryProvider(roots=[
+#     Path.cwd() / ".claude/skills",      # Project-level first
+#     Path.home() / ".claude/skills",     # User-level fallback
+# ]))
+
+# Other vendor providers available:
+# - CursorSkillsProvider()   → ~/.cursor/skills/
+# - VSCodeSkillsProvider()   → ~/.copilot/skills/
+# - CodexSkillsProvider()    → ~/.codex/skills/
+# - GeminiSkillsProvider()   → ~/.gemini/skills/
+# - GooseSkillsProvider()    → ~/.config/agents/skills/
+# - CopilotSkillsProvider()  → ~/.copilot/skills/
+# - OpenCodeSkillsProvider() → ~/.config/opencode/skills/
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/smart_home/README.md b/examples/smart_home/README.md
new file mode 100644
index 0000000..5d065f5
--- /dev/null
+++ b/examples/smart_home/README.md
@@ -0,0 +1,15 @@
+# smart home mcp server
+
+```bash
+cd examples/smart_home
+mcp install src/smart_home/hub.py:hub_mcp -f .env
+```
+where `.env` contains the following:
+```
+HUE_BRIDGE_IP=<your hue bridge ip>
+HUE_BRIDGE_USERNAME=<your hue bridge username>
+```
+
+```bash
+open -a Claude
+```
\ No newline at end of file
diff --git a/examples/smart_home/hub.fastmcp.json b/examples/smart_home/hub.fastmcp.json
new file mode 100644
index 0000000..25daabb
--- /dev/null
+++ b/examples/smart_home/hub.fastmcp.json
@@ -0,0 +1,9 @@
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "entrypoint": "src/smart_home/hub.py",
+  "environment": {
+    "dependencies": [
+      "smart_home@git+https://github.com/PrefectHQ/fastmcp.git#subdirectory=examples/smart_home"
+    ]
+  }
+}
\ No newline at end of file
diff --git a/examples/smart_home/lights.fastmcp.json b/examples/smart_home/lights.fastmcp.json
new file mode 100644
index 0000000..534cab5
--- /dev/null
+++ b/examples/smart_home/lights.fastmcp.json
@@ -0,0 +1,9 @@
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "entrypoint": "src/smart_home/lights/server.py",
+  "environment": {
+    "dependencies": [
+      "smart_home@git+https://github.com/PrefectHQ/fastmcp.git#subdirectory=examples/smart_home"
+    ]
+  }
+}
\ No newline at end of file
diff --git a/examples/smart_home/pyproject.toml b/examples/smart_home/pyproject.toml
new file mode 100644
index 0000000..e38609d
--- /dev/null
+++ b/examples/smart_home/pyproject.toml
@@ -0,0 +1,19 @@
+[project]
+name = "smart-home"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [{ name = "zzstoatzz", email = "thrast36@gmail.com" }]
+requires-python = ">=3.12"
+dependencies = ["fastmcp@git+https://github.com/PrefectHQ/fastmcp.git", "phue2"]
+
+[project.scripts]
+smart-home = "smart_home.__main__:main"
+
+[dependency-groups]
+dev = ["ruff", "ipython"]
+
+
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
diff --git a/examples/smart_home/src/smart_home/__init__.py b/examples/smart_home/src/smart_home/__init__.py
new file mode 100644
index 0000000..dad7ea2
--- /dev/null
+++ b/examples/smart_home/src/smart_home/__init__.py
@@ -0,0 +1,3 @@
+from smart_home.settings import settings
+
+__all__ = ["settings"]
diff --git a/examples/smart_home/src/smart_home/__main__.py b/examples/smart_home/src/smart_home/__main__.py
new file mode 100644
index 0000000..ea5ae47
--- /dev/null
+++ b/examples/smart_home/src/smart_home/__main__.py
@@ -0,0 +1,9 @@
+from smart_home.hub import hub_mcp
+
+
+def main():
+    hub_mcp.run()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/smart_home/src/smart_home/hub.py b/examples/smart_home/src/smart_home/hub.py
new file mode 100644
index 0000000..30c4f24
--- /dev/null
+++ b/examples/smart_home/src/smart_home/hub.py
@@ -0,0 +1,31 @@
+from phue import Bridge
+
+from fastmcp import FastMCP
+from fastmcp.types import ToolAnnotations
+from smart_home.lights.server import lights_mcp
+from smart_home.settings import settings
+
+hub_mcp = FastMCP("Smart Home Hub (phue2)")
+
+# Mount the lights service under the 'hue' namespace
+hub_mcp.mount(lights_mcp, namespace="hue")
+
+
+# Add a status check for the hub
+@hub_mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
+def hub_status() -> str:
+    """Checks the status of the main hub and connections."""
+    try:
+        bridge = Bridge(
+            ip=settings.hue_bridge_ip,
+            username=settings.hue_bridge_username,
+            save_config=False,
+        )
+        bridge.connect()
+        return "Hub OK. Hue Bridge Connected (via phue2)."
+    except Exception as e:
+        return f"Hub Warning: Hue Bridge connection failed or not attempted: {e}"
+
+
+# Add mounting points for other services later
+# hub_mcp.mount("thermo", thermostat_mcp)
diff --git a/examples/smart_home/src/smart_home/lights/__init__.py b/examples/smart_home/src/smart_home/lights/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/examples/smart_home/src/smart_home/lights/hue_utils.py b/examples/smart_home/src/smart_home/lights/hue_utils.py
new file mode 100644
index 0000000..4ec5e71
--- /dev/null
+++ b/examples/smart_home/src/smart_home/lights/hue_utils.py
@@ -0,0 +1,34 @@
+from typing import Any
+
+from phue import Bridge
+from phue.exceptions import PhueException
+
+from smart_home.settings import settings
+
+
+def _get_bridge() -> Bridge | None:
+    """Attempts to connect to the Hue bridge using settings."""
+    try:
+        return Bridge(
+            ip=settings.hue_bridge_ip,
+            username=settings.hue_bridge_username,
+            save_config=False,
+        )
+    except Exception:
+        # Broad exception to catch potential connection issues
+        # TODO: Add more specific logging or error handling
+        return None
+
+
+def handle_phue_error(
+    light_or_group: str, operation: str, error: Exception
+) -> dict[str, Any]:
+    """Creates a standardized error response for phue operations."""
+    base_info = {"target": light_or_group, "operation": operation, "success": False}
+    if isinstance(error, KeyError):
+        base_info["error"] = f"Target '{light_or_group}' not found"
+    elif isinstance(error, PhueException):
+        base_info["error"] = f"phue error during {operation}: {error}"
+    else:
+        base_info["error"] = f"Unexpected error during {operation}: {error}"
+    return base_info
diff --git a/examples/smart_home/src/smart_home/lights/server.py b/examples/smart_home/src/smart_home/lights/server.py
new file mode 100644
index 0000000..535b0f1
--- /dev/null
+++ b/examples/smart_home/src/smart_home/lights/server.py
@@ -0,0 +1,318 @@
+# /// script
+# dependencies = [
+#     "smart_home@git+https://github.com/PrefectHQ/fastmcp.git#subdirectory=examples/smart_home",
+#     "fastmcp",
+# ]
+# ///
+
+from typing import Annotated, Any, Literal, TypedDict
+
+from phue.exceptions import PhueException
+from pydantic import Field
+from typing_extensions import NotRequired
+
+from fastmcp import FastMCP
+from fastmcp.types import ToolAnnotations
+from smart_home.lights.hue_utils import _get_bridge, handle_phue_error
+
+
+class HueAttributes(TypedDict, total=False):
+    """TypedDict for optional light attributes."""
+
+    on: NotRequired[Annotated[bool, Field(description="on/off state")]]
+    bri: NotRequired[Annotated[int, Field(ge=0, le=254, description="brightness")]]
+    hue: NotRequired[
+        Annotated[
+            int,
+            Field(
+                ge=0,
+                le=65535,
+                description="hue (color wheel position)",
+            ),
+        ]
+    ]
+    sat: NotRequired[
+        Annotated[
+            int,
+            Field(
+                ge=0,
+                le=254,
+                description="saturation",
+            ),
+        ]
+    ]
+    xy: NotRequired[Annotated[list[float], Field(description="xy color coordinates")]]
+    ct: NotRequired[
+        Annotated[
+            int,
+            Field(ge=153, le=500, description="color temperature"),
+        ]
+    ]
+    alert: NotRequired[Literal["none", "select", "lselect"]]
+    effect: NotRequired[Literal["none", "colorloop"]]
+    transitiontime: NotRequired[Annotated[int, Field(description="deciseconds")]]
+
+
+# Dependencies are configured in lights.fastmcp.json
+lights_mcp = FastMCP("Hue Lights Service (phue2)")
+
+
+@lights_mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
+def read_all_lights() -> list[str]:
+    """Lists the names of all available Hue lights using phue2."""
+    if not (bridge := _get_bridge()):
+        return ["Error: Bridge not connected"]
+    try:
+        light_dict = bridge.get_light_objects("list")
+        return [light.name for light in light_dict]
+    except (PhueException, Exception) as e:
+        # Simplified error handling for list return type
+        return [f"Error listing lights: {e}"]
+
+
+# --- Tools ---
+
+
+@lights_mcp.tool(annotations=ToolAnnotations(readOnlyHint=False, openWorldHint=True))
+def toggle_light(light_name: str, state: bool) -> dict[str, Any]:
+    """Turns a specific light on (true) or off (false) using phue2."""
+    if not (bridge := _get_bridge()):
+        return {"error": "Bridge not connected", "success": False}
+    try:
+        result = bridge.set_light(light_name, "on", state)
+        return {
+            "light": light_name,
+            "set_on_state": state,
+            "success": True,
+            "phue2_result": result,
+        }
+    except (KeyError, PhueException, Exception) as e:
+        return handle_phue_error(light_name, "toggle_light", e)
+
+
+@lights_mcp.tool(annotations=ToolAnnotations(readOnlyHint=False, openWorldHint=True))
+def set_brightness(light_name: str, brightness: int) -> dict[str, Any]:
+    """Sets the brightness of a specific light (0-254) using phue2."""
+    if not (bridge := _get_bridge()):
+        return {"error": "Bridge not connected", "success": False}
+    if not 0 <= brightness <= 254:
+        # Keep specific input validation error here
+        return {
+            "light": light_name,
+            "error": "Brightness must be between 0 and 254",
+            "success": False,
+        }
+    try:
+        result = bridge.set_light(light_name, "bri", brightness)
+        return {
+            "light": light_name,
+            "set_brightness": brightness,
+            "success": True,
+            "phue2_result": result,
+        }
+    except (KeyError, PhueException, Exception) as e:
+        return handle_phue_error(light_name, "set_brightness", e)
+
+
+@lights_mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
+def list_groups() -> list[str]:
+    """Lists the names of all available Hue light groups."""
+    if not (bridge := _get_bridge()):
+        return ["Error: Bridge not connected"]
+    try:
+        # phue2 get_group() returns a dict {id: {details}} including name
+        groups = bridge.get_group()
+        return [group_details["name"] for group_details in groups.values()]
+    except (PhueException, Exception) as e:
+        return [f"Error listing groups: {e}"]
+
+
+@lights_mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
+def list_scenes() -> dict[str, list[str]] | list[str]:
+    """Lists Hue scenes, grouped by the light group they belong to.
+
+    Returns:
+        dict[str, list[str]]: A dictionary mapping group names to a list of scene names within that group.
+        list[str]: An error message list if the bridge connection fails or an error occurs.
+    """
+    if not (bridge := _get_bridge()):
+        return ["Error: Bridge not connected"]
+    try:
+        scenes_data = bridge.get_scene()  # Returns dict {scene_id: {details...}}
+        groups_data = bridge.get_group()  # Returns dict {group_id: {details...}}
+
+        # Create a lookup for group name by group ID
+        group_id_to_name = {gid: ginfo["name"] for gid, ginfo in groups_data.items()}
+
+        scenes_by_group: dict[str, list[str]] = {}
+        for scene_id, scene_details in scenes_data.items():
+            scene_name = scene_details.get("name")
+            # Scenes might be associated with a group via 'group' key or lights
+            # Using 'group' key if available is more direct for group scenes
+            group_id = scene_details.get("group")
+            if scene_name and group_id and group_id in group_id_to_name:
+                group_name = group_id_to_name[group_id]
+                if group_name not in scenes_by_group:
+                    scenes_by_group[group_name] = []
+                # Avoid duplicate scene names within a group listing (though unlikely)
+                if scene_name not in scenes_by_group[group_name]:
+                    scenes_by_group[group_name].append(scene_name)
+
+        # Sort scenes within each group for consistent output
+        for group_name in scenes_by_group:
+            scenes_by_group[group_name].sort()
+
+        return scenes_by_group
+    except (PhueException, Exception) as e:
+        # Return error as list to match other list-returning tools on error
+        return [f"Error listing scenes by group: {e}"]
+
+
+@lights_mcp.tool(annotations=ToolAnnotations(readOnlyHint=False, openWorldHint=True))
+def activate_scene(group_name: str, scene_name: str) -> dict[str, Any]:
+    """Activates a specific scene within a specified light group, verifying the scene belongs to the group."""
+    if not (bridge := _get_bridge()):
+        return {"error": "Bridge not connected", "success": False}
+    try:
+        # 1. Find the target group ID
+        groups_data = bridge.get_group()
+        target_group_id = None
+        for gid, ginfo in groups_data.items():
+            if ginfo.get("name") == group_name:
+                target_group_id = gid
+                break
+        if not target_group_id:
+            return {"error": f"Group '{group_name}' not found", "success": False}
+
+        # 2. Find the target scene and check its group association
+        scenes_data = bridge.get_scene()
+        scene_found = False
+        scene_in_correct_group = False
+        for sinfo in scenes_data.values():
+            if sinfo.get("name") == scene_name:
+                scene_found = True
+                # Check if this scene is associated with the target group ID
+                if sinfo.get("group") == target_group_id:
+                    scene_in_correct_group = True
+                    break  # Found the scene in the correct group
+
+        if not scene_found:
+            return {"error": f"Scene '{scene_name}' not found", "success": False}
+
+        if not scene_in_correct_group:
+            return {
+                "error": f"Scene '{scene_name}' does not belong to group '{group_name}'",
+                "success": False,
+            }
+
+        # 3. Activate the scene (now that we've verified it)
+        result = bridge.run_scene(group_name=group_name, scene_name=scene_name)
+
+        if result:
+            return {
+                "group": group_name,
+                "activated_scene": scene_name,
+                "success": True,
+                "phue2_result": result,
+            }
+        else:
+            # This case might indicate the scene/group exists but activation failed internally
+            return {
+                "group": group_name,
+                "scene": scene_name,
+                "error": "Scene activation failed (phue2 returned False)",
+                "success": False,
+            }
+
+    except (KeyError, PhueException, Exception) as e:
+        # Handle potential errors during bridge communication or data parsing
+        return handle_phue_error(f"{group_name}/{scene_name}", "activate_scene", e)
+
+
+@lights_mcp.tool(annotations=ToolAnnotations(readOnlyHint=False, openWorldHint=True))
+def set_light_attributes(light_name: str, attributes: HueAttributes) -> dict[str, Any]:
+    """Sets multiple attributes (e.g., hue, sat, bri, ct, xy, transitiontime) for a specific light."""
+    if not (bridge := _get_bridge()):
+        return {"error": "Bridge not connected", "success": False}
+
+    # Basic validation (more specific validation could be added)
+    if not isinstance(attributes, dict) or not attributes:
+        return {
+            "error": "Attributes must be a non-empty dictionary",
+            "success": False,
+            "light": light_name,
+        }
+
+    try:
+        result = bridge.set_light(light_name, dict(attributes))
+        return {
+            "light": light_name,
+            "set_attributes": attributes,
+            "success": True,
+            "phue2_result": result,
+        }
+    except (KeyError, PhueException, ValueError, Exception) as e:
+        # ValueError might occur for invalid attribute values
+        return handle_phue_error(light_name, "set_light_attributes", e)
+
+
+@lights_mcp.tool(annotations=ToolAnnotations(readOnlyHint=False, openWorldHint=True))
+def set_group_attributes(group_name: str, attributes: HueAttributes) -> dict[str, Any]:
+    """Sets multiple attributes for all lights within a specific group."""
+    if not (bridge := _get_bridge()):
+        return {"error": "Bridge not connected", "success": False}
+
+    if not isinstance(attributes, dict) or not attributes:
+        return {
+            "error": "Attributes must be a non-empty dictionary",
+            "success": False,
+            "group": group_name,
+        }
+
+    try:
+        result = bridge.set_group(group_name, dict(attributes))
+        return {
+            "group": group_name,
+            "set_attributes": attributes,
+            "success": True,
+            "phue2_result": result,
+        }
+    except (KeyError, PhueException, ValueError, Exception) as e:
+        return handle_phue_error(group_name, "set_group_attributes", e)
+
+
+@lights_mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
+def list_lights_by_group() -> dict[str, list[str]] | list[str]:
+    """Lists Hue lights, grouped by the room/group they belong to.
+
+    Returns:
+        dict[str, list[str]]: A dictionary mapping group names to a list of light names within that group.
+        list[str]: An error message list if the bridge connection fails or an error occurs.
+    """
+    if not (bridge := _get_bridge()):
+        return ["Error: Bridge not connected"]
+    try:
+        groups_data = bridge.get_group()  # dict {group_id: {details}}
+        lights_data = bridge.get_light_objects("id")  # dict {light_id: {details}}
+
+        lights_by_group: dict[str, list[str]] = {}
+        for group_details in groups_data.values():
+            group_name = group_details.get("name")
+            light_ids = group_details.get("lights", [])
+            if group_name and light_ids:
+                light_names = []
+                for light_id in light_ids:
+                    # phue uses string IDs for lights in group, but int IDs in get_light_objects
+                    light_id_int = int(light_id)
+                    if light_id_int in lights_data:
+                        light_name = lights_data[light_id_int].name
+                        if light_name:
+                            light_names.append(light_name)
+                if light_names:
+                    light_names.sort()
+                    lights_by_group[group_name] = light_names
+
+        return lights_by_group
+
+    except (PhueException, Exception) as e:
+        return [f"Error listing lights by group: {e}"]
diff --git a/examples/smart_home/src/smart_home/py.typed b/examples/smart_home/src/smart_home/py.typed
new file mode 100644
index 0000000..e69de29
diff --git a/examples/smart_home/src/smart_home/settings.py b/examples/smart_home/src/smart_home/settings.py
new file mode 100644
index 0000000..d6b09ac
--- /dev/null
+++ b/examples/smart_home/src/smart_home/settings.py
@@ -0,0 +1,12 @@
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    hue_bridge_ip: str = Field(default=...)
+    hue_bridge_username: str = Field(default=...)
+
+
+settings = Settings()
diff --git a/examples/tags_example.py b/examples/tags_example.py
new file mode 100644
index 0000000..f714c92
--- /dev/null
+++ b/examples/tags_example.py
@@ -0,0 +1,141 @@
+"""
+Example demonstrating RouteMap tags functionality.
+
+This example shows how to use the tags parameter in RouteMap
+to selectively route OpenAPI endpoints based on their tags.
+"""
+
+import asyncio
+
+from fastapi import FastAPI
+
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi import MCPType, RouteMap
+
+# Create a FastAPI app with tagged endpoints
+app = FastAPI(title="Tagged API Example")
+
+
+@app.get("/users", tags=["users", "public"])
+async def get_users():
+    """Get all users - public endpoint"""
+    return [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
+
+
+@app.post("/users", tags=["users", "admin"])
+async def create_user(name: str):
+    """Create a user - admin only"""
+    return {"id": 3, "name": name}
+
+
+@app.get("/admin/stats", tags=["admin", "internal"])
+async def get_admin_stats():
+    """Get admin statistics - internal use"""
+    return {"total_users": 100, "active_sessions": 25}
+
+
+@app.get("/health", tags=["public"])
+async def health_check():
+    """Public health check"""
+    return {"status": "healthy"}
+
+
+@app.get("/metrics")
+async def get_metrics():
+    """Metrics endpoint with no tags"""
+    return {"requests": 1000, "errors": 5}
+
+
+async def main():
+    """Demonstrate different tag-based routing strategies."""
+
+    print("=== Example 1: Make admin-tagged routes tools ===")
+
+    # Strategy 1: Convert admin-tagged routes to tools
+    mcp1 = FastMCP.from_fastapi(
+        app=app,
+        route_maps=[
+            RouteMap(methods="*", pattern=r".*", mcp_type=MCPType.TOOL, tags={"admin"}),
+            RouteMap(methods=["GET"], pattern=r".*", mcp_type=MCPType.RESOURCE),
+        ],
+    )
+
+    tools = await mcp1.list_tools()
+    resources = await mcp1.list_resources()
+
+    print(f"Tools ({len(tools)}): {', '.join(t.name for t in tools)}")
+    print(f"Resources ({len(resources)}): {', '.join(str(r.uri) for r in resources)}")
+
+    print("\n=== Example 2: Exclude internal routes ===")
+
+    # Strategy 2: Exclude internal routes entirely
+    mcp2 = FastMCP.from_fastapi(
+        app=app,
+        route_maps=[
+            RouteMap(
+                methods="*", pattern=r".*", mcp_type=MCPType.EXCLUDE, tags={"internal"}
+            ),
+            RouteMap(methods=["GET"], pattern=r".*", mcp_type=MCPType.RESOURCE),
+            RouteMap(methods=["POST"], pattern=r".*", mcp_type=MCPType.TOOL),
+        ],
+    )
+
+    tools = await mcp2.list_tools()
+    resources = await mcp2.list_resources()
+
+    print(f"Tools ({len(tools)}): {', '.join(t.name for t in tools)}")
+    print(f"Resources ({len(resources)}): {', '.join(str(r.uri) for r in resources)}")
+
+    print("\n=== Example 3: Pattern + Tags combination ===")
+
+    # Strategy 3: Routes matching both pattern AND tags
+    mcp3 = FastMCP.from_fastapi(
+        app=app,
+        route_maps=[
+            # Admin routes under /admin path -> tools
+            RouteMap(
+                methods="*",
+                pattern=r".*/admin/.*",
+                mcp_type=MCPType.TOOL,
+                tags={"admin"},
+            ),
+            # Public routes -> tools
+            RouteMap(
+                methods="*", pattern=r".*", mcp_type=MCPType.TOOL, tags={"public"}
+            ),
+            RouteMap(methods=["GET"], pattern=r".*", mcp_type=MCPType.RESOURCE),
+        ],
+    )
+
+    tools = await mcp3.list_tools()
+    resources = await mcp3.list_resources()
+
+    print(f"Tools ({len(tools)}): {', '.join(t.name for t in tools)}")
+    print(f"Resources ({len(resources)}): {', '.join(str(r.uri) for r in resources)}")
+
+    print("\n=== Example 4: Multiple tag AND condition ===")
+
+    # Strategy 4: Routes must have ALL specified tags
+    mcp4 = FastMCP.from_fastapi(
+        app=app,
+        route_maps=[
+            # Routes with BOTH "users" AND "admin" tags -> tools
+            RouteMap(
+                methods="*",
+                pattern=r".*",
+                mcp_type=MCPType.TOOL,
+                tags={"users", "admin"},
+            ),
+            RouteMap(methods=["GET"], pattern=r".*", mcp_type=MCPType.RESOURCE),
+        ],
+    )
+
+    tools = await mcp4.list_tools()
+    resources = await mcp4.list_resources()
+
+    print(f"Tools ({len(tools)}): {', '.join(t.name for t in tools)}")
+    print(f"Resources ({len(resources)}): {', '.join(str(r.uri) for r in resources)}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/task_elicitation.py b/examples/task_elicitation.py
new file mode 100644
index 0000000..2c7852e
--- /dev/null
+++ b/examples/task_elicitation.py
@@ -0,0 +1,81 @@
+"""
+Background task elicitation demo.
+
+A background task (Docket) that pauses mid-execution to ask the user a
+question, waits for the answer, then resumes and finishes.
+
+Works with both in-memory and Redis backends:
+
+    # In-memory (single process, no Redis needed)
+    FASTMCP_DOCKET_URL=memory:// uv run python examples/task_elicitation.py
+
+    # Redis (distributed, needs a worker running separately)
+    #   Terminal 1: docker compose -f examples/tasks/docker-compose.yml up -d
+    #   Terminal 2: FASTMCP_DOCKET_URL=redis://localhost:24242/0 \
+    #               uv run fastmcp tasks worker examples/task_elicitation.py
+    #   Terminal 3: FASTMCP_DOCKET_URL=redis://localhost:24242/0 \
+    #               uv run python examples/task_elicitation.py
+
+Requires the `docket` extra (included in dev dependencies).
+"""
+
+import asyncio
+from dataclasses import dataclass
+
+from fastmcp import Context, FastMCP
+from fastmcp.client import Client
+from fastmcp.server.elicitation import AcceptedElicitation
+from fastmcp.types import TextContent
+
+mcp = FastMCP("Task Elicitation Demo")
+
+
+@dataclass
+class DinnerPrefs:
+    cuisine: str
+    vegetarian: bool
+
+
+@mcp.tool(task=True)
+async def plan_dinner(ctx: Context) -> str:
+    """Plan a dinner menu, asking the user what they're in the mood for."""
+
+    await ctx.report_progress(0, 2, "Asking what you'd like...")
+
+    result = await ctx.elicit(
+        "What kind of dinner are you in the mood for?",
+        response_type=DinnerPrefs,
+    )
+
+    if not isinstance(result, AcceptedElicitation):
+        return "Dinner cancelled!"
+
+    prefs = result.data
+    await ctx.report_progress(1, 2, "Planning your menu...")
+    await asyncio.sleep(1)
+    await ctx.report_progress(2, 2, "Done!")
+
+    veg = "vegetarian " if prefs.vegetarian else ""
+    return f"Tonight's menu: a lovely {veg}{prefs.cuisine} dinner!"
+
+
+async def handle_elicitation(message, response_type, params, context):
+    """Handle elicitation requests from background tasks."""
+    print(f"  Server asks: {message}")
+    print("  Responding with: cuisine=Thai, vegetarian=True")
+    return DinnerPrefs(cuisine="Thai", vegetarian=True)
+
+
+async def main():
+    async with Client(mcp, elicitation_handler=handle_elicitation) as client:
+        print("Starting background task...")
+        task = await client.call_tool("plan_dinner", {}, task=True)
+        print(f"  task_id = {task.task_id}\n")
+
+        result = await task.result()
+        assert isinstance(result.content[0], TextContent)
+        print(f"\nResult: {result.content[0].text}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/tasks/README.md b/examples/tasks/README.md
new file mode 100644
index 0000000..8013968
--- /dev/null
+++ b/examples/tasks/README.md
@@ -0,0 +1,60 @@
+# FastMCP Tasks Example
+
+Demonstrates background task execution with Docket, including progress tracking, distributed backends, and CLI worker management.
+
+## Setup
+
+```bash
+# From the fastmcp root directory
+uv sync
+
+# Start Redis
+cd examples/tasks
+docker compose up -d
+
+# Load environment (or source .envrc manually)
+direnv allow
+
+# Run the server
+fastmcp run server.py
+```
+
+For single-process mode without Redis, set `FASTMCP_DOCKET_URL=memory://` (note: CLI workers won't work).
+
+## Running the Client
+
+```bash
+# Background execution with progress callbacks
+python examples/tasks/client.py --duration 10
+
+# Immediate execution (blocks)
+python examples/tasks/client.py immediate --duration 5
+```
+
+## Starting Additional Workers
+
+With Redis, you can run additional workers to process tasks in parallel:
+
+```bash
+fastmcp tasks worker server.py
+
+# Configure via environment:
+export FASTMCP_DOCKET_CONCURRENCY=20
+fastmcp tasks worker server.py
+```
+
+**Backend options:**
+- `memory://` - Single-process only (default)
+- `redis://` - Distributed, multi-process (Redis or Valkey)
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `FASTMCP_DOCKET_URL` | `memory://` | Docket backend URL |
+
+## Learn More
+
+- [FastMCP Tasks Documentation](https://gofastmcp.com/docs/tasks)
+- [Docket Documentation](https://github.com/PrefectHQ/docket)
+- [MCP Task Protocol (SEP-1686)](https://spec.modelcontextprotocol.io/specification/architecture/tasks/)
diff --git a/examples/tasks/client.py b/examples/tasks/client.py
new file mode 100644
index 0000000..ac1dacf
--- /dev/null
+++ b/examples/tasks/client.py
@@ -0,0 +1,161 @@
+"""
+FastMCP Tasks Example Client
+
+Demonstrates calling tools both immediately and as background tasks,
+with real-time progress updates via status callbacks.
+
+Usage:
+    # Make sure environment is configured (source .envrc or use direnv)
+    source .envrc
+
+    # Background task execution with progress callbacks (default)
+    python client.py --duration 10
+
+    # Immediate execution (blocks until complete)
+    python client.py immediate --duration 5
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import cyclopts
+from mcp_types import GetTaskResult
+from rich.console import Console
+
+from fastmcp.client import Client
+from fastmcp.types import TextContent
+
+console = Console()
+app = cyclopts.App(name="tasks-client", help="FastMCP Tasks Example Client")
+
+
+def load_server():
+    """Load the example server."""
+    examples_dir = Path(__file__).parent.parent.parent
+    if str(examples_dir) not in sys.path:
+        sys.path.insert(0, str(examples_dir))
+
+    import examples.tasks.server as server_module
+
+    return server_module.mcp
+
+
+# Track last message to deduplicate consecutive identical notifications
+# Note: Docket fires separate events for progress.increment() and progress.set_message(),
+# but MCP's status_message field only carries the text message (no numerical progress).
+# This means we often get duplicate notifications with identical messages.
+_last_notification_message = None
+
+
+def print_notification(status: GetTaskResult) -> None:
+    """Callback function for push notifications from server.
+
+    This is called automatically when the server sends notifications/tasks/status.
+    Deduplicates identical consecutive messages to keep output clean.
+    """
+    global _last_notification_message
+
+    # Skip if this is the same message we just printed
+    if status.status_message == _last_notification_message:
+        return
+
+    _last_notification_message = status.status_message
+
+    color = {
+        "working": "yellow",
+        "completed": "green",
+        "failed": "red",
+    }.get(status.status, "yellow")
+
+    icon = {
+        "working": "🚀",
+        "completed": "✅",
+        "failed": "❌",
+    }.get(status.status, "⚠️")
+
+    console.print(
+        f"[{color}]📢 Notification: {status.status} {icon} - {status.status_message}[/{color}]"
+    )
+
+
+@app.default
+async def task(
+    duration: Annotated[
+        int,
+        cyclopts.Parameter(help="Duration of computation in seconds (1-60)"),
+    ] = 10,
+):
+    """Execute as background task with real-time progress callbacks."""
+    if duration < 1 or duration > 60:
+        console.print("[red]Error: Duration must be between 1 and 60 seconds[/red]")
+        sys.exit(1)
+
+    server = load_server()
+
+    console.print(f"\n[bold]Calling slow_computation(duration={duration})[/bold]")
+    console.print("Mode: [cyan]Background task[/cyan]\n")
+
+    async with Client(server) as client:
+        task_obj = await client.call_tool(
+            "slow_computation",
+            arguments={"duration": duration},
+            task=True,
+        )
+
+        console.print(f"Task started: [cyan]{task_obj.task_id}[/cyan]\n")
+
+        # Register callback for real-time push notifications
+        task_obj.on_status_change(print_notification)
+
+        console.print(
+            "[dim]Notifications will appear as the server sends them...[/dim]\n"
+        )
+
+        # Do other work while task runs in background
+        for i in range(3):
+            await asyncio.sleep(0.5)
+            console.print(f"[dim]Client doing other work... ({i + 1}/3)[/dim]")
+
+        console.print()
+
+        # Wait for task to complete
+        console.print("[dim]Waiting for final result...[/dim]")
+        result = await task_obj.result()
+
+        console.print("\n[bold]Result:[/bold]")
+        assert isinstance(result.content[0], TextContent)
+        console.print(f"  {result.content[0].text}")
+
+
+@app.command
+async def immediate(
+    duration: Annotated[
+        int,
+        cyclopts.Parameter(help="Duration of computation in seconds (1-60)"),
+    ] = 5,
+):
+    """Execute the tool immediately (blocks until complete)."""
+    if duration < 1 or duration > 60:
+        console.print("[red]Error: Duration must be between 1 and 60 seconds[/red]")
+        sys.exit(1)
+
+    server = load_server()
+
+    console.print(f"\n[bold]Calling slow_computation(duration={duration})[/bold]")
+    console.print("Mode: [cyan]Immediate execution[/cyan]\n")
+
+    async with Client(server) as client:
+        result = await client.call_tool(
+            "slow_computation",
+            arguments={"duration": duration},
+        )
+
+        console.print("\n[bold]Result:[/bold]")
+        assert isinstance(result.content[0], TextContent)
+        console.print(f"  {result.content[0].text}")
+
+
+if __name__ == "__main__":
+    app()
diff --git a/examples/tasks/docker-compose.yml b/examples/tasks/docker-compose.yml
new file mode 100644
index 0000000..d5643b2
--- /dev/null
+++ b/examples/tasks/docker-compose.yml
@@ -0,0 +1,10 @@
+services:
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "24242:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
diff --git a/examples/tasks/server.py b/examples/tasks/server.py
new file mode 100644
index 0000000..77b3cde
--- /dev/null
+++ b/examples/tasks/server.py
@@ -0,0 +1,75 @@
+"""
+FastMCP Tasks Example Server
+
+Demonstrates background task execution with progress tracking using Docket.
+
+Setup:
+    1. Start Redis: docker compose up -d
+    2. Load environment: source .envrc
+    3. Run server: fastmcp run server.py
+
+The example uses Redis by default to demonstrate distributed task execution
+and the fastmcp tasks CLI commands.
+"""
+
+import asyncio
+import logging
+from typing import Annotated
+
+from docket import Logged
+
+from fastmcp import FastMCP
+from fastmcp.dependencies import Progress
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Create server
+mcp = FastMCP("Tasks Example")
+
+
+@mcp.tool(task=True)
+async def slow_computation(
+    duration: Annotated[int, Logged],
+    progress: Progress = Progress(),
+) -> str:
+    """
+    Perform a slow computation that takes `duration` seconds.
+
+    This tool demonstrates progress tracking with background tasks.
+    It logs progress every 1-2 seconds and reports progress via Docket.
+
+    Args:
+        duration: Number of seconds the computation should take (1-60)
+
+    Returns:
+        A completion message with the total duration
+    """
+    if duration < 1 or duration > 60:
+        raise ValueError("Duration must be between 1 and 60 seconds")
+
+    logger.info(f"Starting slow computation for {duration} seconds")
+
+    # Set total progress units
+    await progress.set_total(duration)
+
+    # Process each second
+    for i in range(duration):
+        # Sleep for 1 second
+        await asyncio.sleep(1)
+
+        # Update progress
+        elapsed = i + 1
+        remaining = duration - elapsed
+        await progress.increment()
+        await progress.set_message(
+            f"Working... {elapsed}/{duration}s ({remaining}s remaining)"
+        )
+
+        # Log every 1-2 seconds
+        if elapsed % 2 == 0 or elapsed == duration:
+            logger.info(f"Progress: {elapsed}/{duration}s")
+
+    logger.info(f"Completed computation in {duration} seconds")
+    return f"Computation completed successfully in {duration} seconds!"
diff --git a/examples/testing_demo/README.md b/examples/testing_demo/README.md
new file mode 100644
index 0000000..e4e7111
--- /dev/null
+++ b/examples/testing_demo/README.md
@@ -0,0 +1,84 @@
+# FastMCP Testing Demo
+
+A comprehensive example demonstrating FastMCP testing patterns with pytest-asyncio.
+
+## Overview
+
+This example shows how to:
+- Set up pytest-asyncio configuration in `pyproject.toml`
+- Write async test fixtures for MCP clients
+- Test tools, resources, and prompts
+- Use parametrized tests for multiple scenarios
+- Leverage inline-snapshot and dirty-equals for assertions
+
+## Project Structure
+
+```
+testing_demo/
+├── pyproject.toml          # Project config with pytest-asyncio setup
+├── server.py               # Simple MCP server with tools/resources/prompts
+├── tests/
+│   └── test_server.py      # Comprehensive test suite
+└── README.md               # This file
+```
+
+## Key Features
+
+### pyproject.toml Configuration
+
+The `pyproject.toml` includes the critical pytest-asyncio configuration:
+
+```toml
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+```
+
+This eliminates the need for `@pytest.mark.asyncio` decorators on every async test.
+
+### Server Components
+
+The demo server (`server.py`) includes:
+- **Tools**: `add`, `greet`, `async_multiply`
+- **Resources**: `demo://info`, `demo://greeting/{name}`
+- **Prompts**: `hello`, `explain`
+
+### Test Patterns
+
+The test suite demonstrates:
+1. **Async fixture pattern**: Proper client fixture using `async with`
+2. **Tool testing**: Calling tools and checking results via `.data` attribute
+3. **Resource testing**: Reading static and templated resources
+4. **Prompt testing**: Getting prompts with different arguments
+5. **Parametrized tests**: Testing multiple scenarios efficiently
+6. **Schema validation**: Verifying tool schemas and structure
+7. **Pattern matching**: Using dirty-equals for flexible assertions
+
+## Running the Tests
+
+```bash
+# Install dependencies
+uv sync
+
+# Run all tests
+uv run pytest
+
+# Run with verbose output
+uv run pytest -v
+
+# Run a specific test
+uv run pytest tests/test_server.py::test_add_tool
+```
+
+## Running the Server
+
+```bash
+# Run the server
+uv run fastmcp run server.py
+
+# Inspect the server
+uv run fastmcp inspect server.py
+```
+
+## Learning More
+
+For detailed information about testing FastMCP servers, see the [Testing Documentation](../../docs/patterns/testing.mdx).
diff --git a/examples/testing_demo/pyproject.toml b/examples/testing_demo/pyproject.toml
new file mode 100644
index 0000000..6130b9c
--- /dev/null
+++ b/examples/testing_demo/pyproject.toml
@@ -0,0 +1,18 @@
+[project]
+name = "testing-demo"
+version = "0.1.0"
+description = "FastMCP testing example demonstrating pytest-asyncio patterns"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "fastmcp>=2.0.0",
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.2.0",
+    "dirty-equals>=0.9.0",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["."]
+python_files = ["test_*.py"]
diff --git a/examples/testing_demo/server.py b/examples/testing_demo/server.py
new file mode 100644
index 0000000..2bac46e
--- /dev/null
+++ b/examples/testing_demo/server.py
@@ -0,0 +1,61 @@
+"""
+FastMCP Testing Demo Server
+
+A simple MCP server demonstrating tools, resources, and prompts
+with comprehensive test coverage.
+"""
+
+from fastmcp import FastMCP
+
+# Create server
+mcp = FastMCP("Testing Demo")
+
+
+# Tools
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Add two numbers together"""
+    return a + b
+
+
+@mcp.tool
+def greet(name: str, greeting: str = "Hello") -> str:
+    """Greet someone with a customizable greeting"""
+    return f"{greeting}, {name}!"
+
+
+@mcp.tool
+async def async_multiply(x: float, y: float) -> float:
+    """Multiply two numbers (async example)"""
+    return x * y
+
+
+# Resources
+@mcp.resource("demo://info")
+def server_info() -> str:
+    """Get server information"""
+    return "This is the FastMCP Testing Demo server"
+
+
+@mcp.resource("demo://greeting/{name}")
+def greeting_resource(name: str) -> str:
+    """Get a personalized greeting resource"""
+    return f"Welcome to FastMCP, {name}!"
+
+
+# Prompts
+@mcp.prompt("hello")
+def hello_prompt(name: str = "World") -> str:
+    """Generate a hello world prompt"""
+    return f"Say hello to {name} in a friendly way."
+
+
+@mcp.prompt("explain")
+def explain_prompt(topic: str, detail_level: str = "medium") -> str:
+    """Generate a prompt to explain a topic"""
+    if detail_level == "simple":
+        return f"Explain {topic} in simple terms for beginners."
+    elif detail_level == "detailed":
+        return f"Provide a detailed, technical explanation of {topic}."
+    else:
+        return f"Explain {topic} with moderate technical detail."
diff --git a/examples/testing_demo/tests/test_server.py b/examples/testing_demo/tests/test_server.py
new file mode 100644
index 0000000..921d6c3
--- /dev/null
+++ b/examples/testing_demo/tests/test_server.py
@@ -0,0 +1,160 @@
+"""
+Tests for the Testing Demo server.
+
+Demonstrates pytest-asyncio patterns, fixtures, and testing best practices.
+"""
+
+import pytest
+from dirty_equals import IsStr
+
+from fastmcp.client import Client
+
+
+@pytest.fixture
+async def client():
+    """
+    Client fixture for testing.
+
+    Uses async context manager and yields client synchronously.
+    No @pytest.mark.asyncio needed - asyncio_mode = "auto" handles it.
+    """
+    # Import here to avoid import-time side effects
+    from server import mcp
+
+    async with Client(mcp) as client:
+        yield client
+
+
+async def test_add_tool(client: Client):
+    """Test the add tool with simple addition"""
+    result = await client.call_tool("add", {"a": 2, "b": 3})
+    assert result.data == 5
+
+
+async def test_greet_tool_default(client: Client):
+    """Test the greet tool with default greeting"""
+    result = await client.call_tool("greet", {"name": "Alice"})
+    assert result.data == "Hello, Alice!"
+
+
+async def test_greet_tool_custom(client: Client):
+    """Test the greet tool with custom greeting"""
+    result = await client.call_tool("greet", {"name": "Bob", "greeting": "Hi"})
+    assert result.data == "Hi, Bob!"
+
+
+async def test_async_multiply_tool(client: Client):
+    """Test the async multiply tool"""
+    result = await client.call_tool("async_multiply", {"x": 3.5, "y": 2.0})
+    assert result.data == 7.0
+
+
+@pytest.mark.parametrize(
+    "a,b,expected",
+    [
+        (0, 0, 0),
+        (1, 1, 2),
+        (-1, 1, 0),
+        (100, 200, 300),
+    ],
+)
+async def test_add_parametrized(client: Client, a: int, b: int, expected: int):
+    """Test add tool with multiple parameter combinations"""
+    result = await client.call_tool("add", {"a": a, "b": b})
+    assert result.data == expected
+
+
+async def test_server_info_resource(client: Client):
+    """Test the server info resource"""
+    result = await client.read_resource("demo://info")
+    assert len(result) == 1
+    assert result[0].text == "This is the FastMCP Testing Demo server"
+
+
+async def test_greeting_resource_template(client: Client):
+    """Test the greeting resource template"""
+    result = await client.read_resource("demo://greeting/Charlie")
+    assert len(result) == 1
+    assert result[0].text == "Welcome to FastMCP, Charlie!"
+
+
+async def test_hello_prompt_default(client: Client):
+    """Test hello prompt with default parameter"""
+    result = await client.get_prompt("hello")
+    assert result.messages[0].content.text == "Say hello to World in a friendly way."
+
+
+async def test_hello_prompt_custom(client: Client):
+    """Test hello prompt with custom name"""
+    result = await client.get_prompt("hello", {"name": "Dave"})
+    assert result.messages[0].content.text == "Say hello to Dave in a friendly way."
+
+
+async def test_explain_prompt_levels(client: Client):
+    """Test explain prompt with different detail levels"""
+    # Simple level
+    result = await client.get_prompt(
+        "explain", {"topic": "MCP", "detail_level": "simple"}
+    )
+    assert "simple terms" in result.messages[0].content.text
+    assert "MCP" in result.messages[0].content.text
+
+    # Detailed level
+    result = await client.get_prompt(
+        "explain", {"topic": "MCP", "detail_level": "detailed"}
+    )
+    assert "detailed" in result.messages[0].content.text
+    assert "technical" in result.messages[0].content.text
+
+
+async def test_list_tools(client: Client):
+    """Test listing available tools"""
+    tools = await client.list_tools()
+    tool_names = [tool.name for tool in tools]
+
+    assert "add" in tool_names
+    assert "greet" in tool_names
+    assert "async_multiply" in tool_names
+
+
+async def test_list_resources(client: Client):
+    """Test listing available resources"""
+    resources = await client.list_resources()
+    resource_uris = [str(resource.uri) for resource in resources]
+
+    # Check that we have at least the static resource
+    assert "demo://info" in resource_uris
+    # There should be at least one resource listed
+    assert len(resource_uris) >= 1
+
+
+async def test_list_prompts(client: Client):
+    """Test listing available prompts"""
+    prompts = await client.list_prompts()
+    prompt_names = [prompt.name for prompt in prompts]
+
+    assert "hello" in prompt_names
+    assert "explain" in prompt_names
+
+
+# Example using dirty-equals for flexible assertions
+async def test_greet_with_dirty_equals(client: Client):
+    """Test greet tool using dirty-equals for pattern matching"""
+    result = await client.call_tool("greet", {"name": "Eve"})
+    # Check that result data matches the pattern
+    assert result.data == IsStr(regex=r"^Hello, \w+!$")
+
+
+# Example using inline-snapshot for complex data
+async def test_tool_schema_structure(client: Client):
+    """Test tool schema structure"""
+    tools = await client.list_tools()
+    add_tool = next(tool for tool in tools if tool.name == "add")
+
+    # Verify basic schema structure
+    assert add_tool.name == "add"
+    assert add_tool.description == "Add two numbers together"
+    assert "a" in add_tool.inputSchema["properties"]
+    assert "b" in add_tool.inputSchema["properties"]
+    assert add_tool.inputSchema["properties"]["a"]["type"] == "integer"
+    assert add_tool.inputSchema["properties"]["b"]["type"] == "integer"
diff --git a/examples/testing_demo/uv.lock b/examples/testing_demo/uv.lock
new file mode 100644
index 0000000..f912f80
--- /dev/null
+++ b/examples/testing_demo/uv.lock
@@ -0,0 +1,1592 @@
+version = 1
+revision = 3
+requires-python = ">=3.10"
+
+[options]
+exclude-newer = "2026-06-20T14:09:01.281965Z"
+exclude-newer-span = "P1W"
+
+[options.exclude-newer-package]
+prefab-ui = false
+
+[[package]]
+name = "aiofile"
+version = "3.9.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "caio" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/67/e2/d7cb819de8df6b5c1968a2756c3cb4122d4fa2b8fc768b53b7c9e5edb646/aiofile-3.9.0.tar.gz", hash = "sha256:e5ad718bb148b265b6df1b3752c4d1d83024b93da9bd599df74b9d9ffcf7919b", size = 17943, upload-time = "2024-10-08T10:39:35.846Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/50/25/da1f0b4dd970e52bf5a36c204c107e11a0c6d3ed195eba0bfbc664c312b2/aiofile-3.9.0-py3-none-any.whl", hash = "sha256:ce2f6c1571538cbdfa0143b04e16b208ecb0e9cb4148e528af8a640ed51cc8aa", size = 19539, upload-time = "2024-10-08T10:39:32.955Z" },
+]
+
+[[package]]
+name = "annotated-types"
+version = "0.7.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ee/67/531ea369ba64dcff5ec9c3402f9f51bf748cec26dde048a2f973a4eea7f5/annotated_types-0.7.0.tar.gz", hash = "sha256:aff07c09a53a08bc8cfccb9c85b05f1aa9a2a6f23728d790723543408344ce89", size = 16081, upload-time = "2024-05-20T21:33:25.928Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/78/b6/6307fbef88d9b5ee7421e68d78a9f162e0da4900bc5f5793f6d3d0e34fb8/annotated_types-0.7.0-py3-none-any.whl", hash = "sha256:1f02e8b43a8fbbc3f3e0d4f0f4bfc8131bcb4eebe8849b8e5c773f3a1c582a53", size = 13643, upload-time = "2024-05-20T21:33:24.1Z" },
+]
+
+[[package]]
+name = "anyio"
+version = "4.12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "exceptiongroup", marker = "python_full_version < '3.11'" },
+    { name = "idna" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/96/f0/5eb65b2bb0d09ac6776f2eb54adee6abe8228ea05b20a5ad0e4945de8aac/anyio-4.12.1.tar.gz", hash = "sha256:41cfcc3a4c85d3f05c932da7c26d0201ac36f72abd4435ba90d0464a3ffed703", size = 228685, upload-time = "2026-01-06T11:45:21.246Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/38/0e/27be9fdef66e72d64c0cdc3cc2823101b80585f8119b5c112c2e8f5f7dab/anyio-4.12.1-py3-none-any.whl", hash = "sha256:d405828884fc140aa80a3c667b8beed277f1dfedec42ba031bd6ac3db606ab6c", size = 113592, upload-time = "2026-01-06T11:45:19.497Z" },
+]
+
+[[package]]
+name = "attrs"
+version = "25.4.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/6b/5c/685e6633917e101e5dcb62b9dd76946cbb57c26e133bae9e0cd36033c0a9/attrs-25.4.0.tar.gz", hash = "sha256:16d5969b87f0859ef33a48b35d55ac1be6e42ae49d5e853b597db70c35c57e11", size = 934251, upload-time = "2025-10-06T13:54:44.725Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3a/2a/7cc015f5b9f5db42b7d48157e23356022889fc354a2813c15934b7cb5c0e/attrs-25.4.0-py3-none-any.whl", hash = "sha256:adcf7e2a1fb3b36ac48d97835bb6d8ade15b8dcce26aba8bf1d14847b57a3373", size = 67615, upload-time = "2025-10-06T13:54:43.17Z" },
+]
+
+[[package]]
+name = "authlib"
+version = "1.7.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cryptography" },
+    { name = "joserfc" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/36/98/7d93f30d029643c0275dbc0bd6d5a6f670661ee6c9a94d93af7ab4887600/authlib-1.7.2.tar.gz", hash = "sha256:2cea25fefcd4e7173bdf1372c0afc265c8034b23a8cd5dcb6a9164b826c64231", size = 176511, upload-time = "2026-05-06T08:10:23.116Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fb/95/adcb68e20c34162e9135f370d6e31737719c2b6f94bc953fe7ed1f10fe21/authlib-1.7.2-py2.py3-none-any.whl", hash = "sha256:3e1faedc9d87e7d56a164eca3ccb6ace0d61b94abe83e92242f8dc8bba9b4a9f", size = 259548, upload-time = "2026-05-06T08:10:21.436Z" },
+]
+
+[[package]]
+name = "backports-asyncio-runner"
+version = "1.2.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/8e/ff/70dca7d7cb1cbc0edb2c6cc0c38b65cba36cccc491eca64cabd5fe7f8670/backports_asyncio_runner-1.2.0.tar.gz", hash = "sha256:a5aa7b2b7d8f8bfcaa2b57313f70792df84e32a2a746f585213373f900b42162", size = 69893, upload-time = "2025-07-02T02:27:15.685Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a0/59/76ab57e3fe74484f48a53f8e337171b4a2349e506eabe136d7e01d059086/backports_asyncio_runner-1.2.0-py3-none-any.whl", hash = "sha256:0da0a936a8aeb554eccb426dc55af3ba63bcdc69fa1a600b5bb305413a4477b5", size = 12313, upload-time = "2025-07-02T02:27:14.263Z" },
+]
+
+[[package]]
+name = "backports-tarfile"
+version = "1.2.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/86/72/cd9b395f25e290e633655a100af28cb253e4393396264a98bd5f5951d50f/backports_tarfile-1.2.0.tar.gz", hash = "sha256:d75e02c268746e1b8144c278978b6e98e85de6ad16f8e4b0844a154557eca991", size = 86406, upload-time = "2024-05-28T17:01:54.731Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b9/fa/123043af240e49752f1c4bd24da5053b6bd00cad78c2be53c0d1e8b975bc/backports.tarfile-1.2.0-py3-none-any.whl", hash = "sha256:77e284d754527b01fb1e6fa8a1afe577858ebe4e9dad8919e34c862cb399bc34", size = 30181, upload-time = "2024-05-28T17:01:53.112Z" },
+]
+
+[[package]]
+name = "beartype"
+version = "0.22.9"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c7/94/1009e248bbfbab11397abca7193bea6626806be9a327d399810d523a07cb/beartype-0.22.9.tar.gz", hash = "sha256:8f82b54aa723a2848a56008d18875f91c1db02c32ef6a62319a002e3e25a975f", size = 1608866, upload-time = "2025-12-13T06:50:30.72Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/71/cc/18245721fa7747065ab478316c7fea7c74777d07f37ae60db2e84f8172e8/beartype-0.22.9-py3-none-any.whl", hash = "sha256:d16c9bbc61ea14637596c5f6fbff2ee99cbe3573e46a716401734ef50c3060c2", size = 1333658, upload-time = "2025-12-13T06:50:28.266Z" },
+]
+
+[[package]]
+name = "cachetools"
+version = "7.0.5"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/af/dd/57fe3fdb6e65b25a5987fd2cdc7e22db0aef508b91634d2e57d22928d41b/cachetools-7.0.5.tar.gz", hash = "sha256:0cd042c24377200c1dcd225f8b7b12b0ca53cc2c961b43757e774ebe190fd990", size = 37367, upload-time = "2026-03-09T20:51:29.451Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/06/f3/39cf3367b8107baa44f861dc802cbf16263c945b62d8265d36034fc07bea/cachetools-7.0.5-py3-none-any.whl", hash = "sha256:46bc8ebefbe485407621d0a4264b23c080cedd913921bad7ac3ed2f26c183114", size = 13918, upload-time = "2026-03-09T20:51:27.33Z" },
+]
+
+[[package]]
+name = "caio"
+version = "0.9.25"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/92/88/b8527e1b00c1811db339a1df8bd1ae49d146fcea9d6a5c40e3a80aaeb38d/caio-0.9.25.tar.gz", hash = "sha256:16498e7f81d1d0f5a4c0ad3f2540e65fe25691376e0a5bd367f558067113ed10", size = 26781, upload-time = "2025-12-26T15:21:36.501Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/6a/80/ea4ead0c5d52a9828692e7df20f0eafe8d26e671ce4883a0a146bb91049e/caio-0.9.25-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:ca6c8ecda611478b6016cb94d23fd3eb7124852b985bdec7ecaad9f3116b9619", size = 36836, upload-time = "2025-12-26T15:22:04.662Z" },
+    { url = "https://files.pythonhosted.org/packages/17/b9/36715c97c873649d1029001578f901b50250916295e3dddf20c865438865/caio-0.9.25-cp310-cp310-manylinux2010_x86_64.manylinux2014_x86_64.manylinux_2_12_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:db9b5681e4af8176159f0d6598e73b2279bb661e718c7ac23342c550bd78c241", size = 79695, upload-time = "2025-12-26T15:22:18.818Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/ab/07080ecb1adb55a02cbd8ec0126aa8e43af343ffabb6a71125b42670e9a1/caio-0.9.25-cp310-cp310-manylinux_2_34_aarch64.whl", hash = "sha256:bf61d7d0c4fd10ffdd98ca47f7e8db4d7408e74649ffaf4bef40b029ada3c21b", size = 79457, upload-time = "2026-03-04T22:08:16.024Z" },
+    { url = "https://files.pythonhosted.org/packages/88/95/dd55757bb671eb4c376e006c04e83beb413486821f517792ea603ef216e9/caio-0.9.25-cp310-cp310-manylinux_2_34_x86_64.whl", hash = "sha256:ab52e5b643f8bbd64a0605d9412796cd3464cb8ca88593b13e95a0f0b10508ae", size = 77705, upload-time = "2026-03-04T22:08:17.202Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/90/543f556fcfcfa270713eef906b6352ab048e1e557afec12925c991dc93c2/caio-0.9.25-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:d6956d9e4a27021c8bd6c9677f3a59eb1d820cc32d0343cea7961a03b1371965", size = 36839, upload-time = "2025-12-26T15:21:40.267Z" },
+    { url = "https://files.pythonhosted.org/packages/51/3b/36f3e8ec38dafe8de4831decd2e44c69303d2a3892d16ceda42afed44e1b/caio-0.9.25-cp311-cp311-manylinux2010_x86_64.manylinux2014_x86_64.manylinux_2_12_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:bf84bfa039f25ad91f4f52944452a5f6f405e8afab4d445450978cd6241d1478", size = 80255, upload-time = "2025-12-26T15:22:20.271Z" },
+    { url = "https://files.pythonhosted.org/packages/df/ce/65e64867d928e6aff1b4f0e12dba0ef6d5bf412c240dc1df9d421ac10573/caio-0.9.25-cp311-cp311-manylinux_2_34_aarch64.whl", hash = "sha256:ae3d62587332bce600f861a8de6256b1014d6485cfd25d68c15caf1611dd1f7c", size = 80052, upload-time = "2026-03-04T22:08:20.402Z" },
+    { url = "https://files.pythonhosted.org/packages/46/90/e278863c47e14ec58309aa2e38a45882fbe67b4cc29ec9bc8f65852d3e45/caio-0.9.25-cp311-cp311-manylinux_2_34_x86_64.whl", hash = "sha256:fc220b8533dcf0f238a6b1a4a937f92024c71e7b10b5a2dfc1c73604a25709bc", size = 78273, upload-time = "2026-03-04T22:08:21.368Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/25/79c98ebe12df31548ba4eaf44db11b7cad6b3e7b4203718335620939083c/caio-0.9.25-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:fb7ff95af4c31ad3f03179149aab61097a71fd85e05f89b4786de0359dffd044", size = 36983, upload-time = "2025-12-26T15:21:36.075Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/2b/21288691f16d479945968a0a4f2856818c1c5be56881d51d4dac9b255d26/caio-0.9.25-cp312-cp312-manylinux2010_x86_64.manylinux2014_x86_64.manylinux_2_12_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:97084e4e30dfa598449d874c4d8e0c8d5ea17d2f752ef5e48e150ff9d240cd64", size = 82012, upload-time = "2025-12-26T15:22:20.983Z" },
+    { url = "https://files.pythonhosted.org/packages/03/c4/8a1b580875303500a9c12b9e0af58cb82e47f5bcf888c2457742a138273c/caio-0.9.25-cp312-cp312-manylinux_2_34_aarch64.whl", hash = "sha256:4fa69eba47e0f041b9d4f336e2ad40740681c43e686b18b191b6c5f4c5544bfb", size = 81502, upload-time = "2026-03-04T22:08:22.381Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/1c/0fe770b8ffc8362c48134d1592d653a81a3d8748d764bec33864db36319d/caio-0.9.25-cp312-cp312-manylinux_2_34_x86_64.whl", hash = "sha256:6bebf6f079f1341d19f7386db9b8b1f07e8cc15ae13bfdaff573371ba0575d69", size = 80200, upload-time = "2026-03-04T22:08:23.382Z" },
+    { url = "https://files.pythonhosted.org/packages/31/57/5e6ff127e6f62c9f15d989560435c642144aa4210882f9494204bc892305/caio-0.9.25-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:d6c2a3411af97762a2b03840c3cec2f7f728921ff8adda53d7ea2315a8563451", size = 36979, upload-time = "2025-12-26T15:21:35.484Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/9f/f21af50e72117eb528c422d4276cbac11fb941b1b812b182e0a9c70d19c5/caio-0.9.25-cp313-cp313-manylinux2010_x86_64.manylinux2014_x86_64.manylinux_2_12_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:0998210a4d5cd5cb565b32ccfe4e53d67303f868a76f212e002a8554692870e6", size = 81900, upload-time = "2025-12-26T15:22:21.919Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/12/c39ae2a4037cb10ad5eb3578eb4d5f8c1a2575c62bba675f3406b7ef0824/caio-0.9.25-cp313-cp313-manylinux_2_34_aarch64.whl", hash = "sha256:1a177d4777141b96f175fe2c37a3d96dec7911ed9ad5f02bac38aaa1c936611f", size = 81523, upload-time = "2026-03-04T22:08:25.187Z" },
+    { url = "https://files.pythonhosted.org/packages/22/59/f8f2e950eb4f1a5a3883e198dca514b9d475415cb6cd7b78b9213a0dd45a/caio-0.9.25-cp313-cp313-manylinux_2_34_x86_64.whl", hash = "sha256:9ed3cfb28c0e99fec5e208c934e5c157d0866aa9c32aa4dc5e9b6034af6286b7", size = 80243, upload-time = "2026-03-04T22:08:26.449Z" },
+    { url = "https://files.pythonhosted.org/packages/69/ca/a08fdc7efdcc24e6a6131a93c85be1f204d41c58f474c42b0670af8c016b/caio-0.9.25-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:fab6078b9348e883c80a5e14b382e6ad6aabbc4429ca034e76e730cf464269db", size = 36978, upload-time = "2025-12-26T15:21:41.055Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/6c/d4d24f65e690213c097174d26eda6831f45f4734d9d036d81790a27e7b78/caio-0.9.25-cp314-cp314-manylinux2010_x86_64.manylinux2014_x86_64.manylinux_2_12_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:44a6b58e52d488c75cfaa5ecaa404b2b41cc965e6c417e03251e868ecd5b6d77", size = 81832, upload-time = "2025-12-26T15:22:22.757Z" },
+    { url = "https://files.pythonhosted.org/packages/87/a4/e534cf7d2d0e8d880e25dd61e8d921ffcfe15bd696734589826f5a2df727/caio-0.9.25-cp314-cp314-manylinux_2_34_aarch64.whl", hash = "sha256:628a630eb7fb22381dd8e3c8ab7f59e854b9c806639811fc3f4310c6bd711d79", size = 81565, upload-time = "2026-03-04T22:08:27.483Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/ed/bf81aeac1d290017e5e5ac3e880fd56ee15e50a6d0353986799d1bc5cfd5/caio-0.9.25-cp314-cp314-manylinux_2_34_x86_64.whl", hash = "sha256:0ba16aa605ccb174665357fc729cf500679c2d94d5f1458a6f0d5ca48f2060a7", size = 80071, upload-time = "2026-03-04T22:08:28.751Z" },
+    { url = "https://files.pythonhosted.org/packages/86/93/1f76c8d1bafe3b0614e06b2195784a3765bbf7b0a067661af9e2dd47fc33/caio-0.9.25-py3-none-any.whl", hash = "sha256:06c0bb02d6b929119b1cfbe1ca403c768b2013a369e2db46bfa2a5761cf82e40", size = 19087, upload-time = "2025-12-26T15:22:00.221Z" },
+]
+
+[[package]]
+name = "certifi"
+version = "2026.2.25"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/af/2d/7bf41579a8986e348fa033a31cdd0e4121114f6bce2457e8876010b092dd/certifi-2026.2.25.tar.gz", hash = "sha256:e887ab5cee78ea814d3472169153c2d12cd43b14bd03329a39a9c6e2e80bfba7", size = 155029, upload-time = "2026-02-25T02:54:17.342Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9a/3c/c17fb3ca2d9c3acff52e30b309f538586f9f5b9c9cf454f3845fc9af4881/certifi-2026.2.25-py3-none-any.whl", hash = "sha256:027692e4402ad994f1c42e52a4997a9763c646b73e4096e4d5d6db8af1d6f0fa", size = 153684, upload-time = "2026-02-25T02:54:15.766Z" },
+]
+
+[[package]]
+name = "cffi"
+version = "2.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pycparser", marker = "implementation_name != 'PyPy'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/eb/56/b1ba7935a17738ae8453301356628e8147c79dbb825bcbc73dc7401f9846/cffi-2.0.0.tar.gz", hash = "sha256:44d1b5909021139fe36001ae048dbdde8214afa20200eda0f64c068cac5d5529", size = 523588, upload-time = "2025-09-08T23:24:04.541Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/93/d7/516d984057745a6cd96575eea814fe1edd6646ee6efd552fb7b0921dec83/cffi-2.0.0-cp310-cp310-macosx_10_13_x86_64.whl", hash = "sha256:0cf2d91ecc3fcc0625c2c530fe004f82c110405f101548512cce44322fa8ac44", size = 184283, upload-time = "2025-09-08T23:22:08.01Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/84/ad6a0b408daa859246f57c03efd28e5dd1b33c21737c2db84cae8c237aa5/cffi-2.0.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:f73b96c41e3b2adedc34a7356e64c8eb96e03a3782b535e043a986276ce12a49", size = 180504, upload-time = "2025-09-08T23:22:10.637Z" },
+    { url = "https://files.pythonhosted.org/packages/50/bd/b1a6362b80628111e6653c961f987faa55262b4002fcec42308cad1db680/cffi-2.0.0-cp310-cp310-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:53f77cbe57044e88bbd5ed26ac1d0514d2acf0591dd6bb02a3ae37f76811b80c", size = 208811, upload-time = "2025-09-08T23:22:12.267Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/27/6933a8b2562d7bd1fb595074cf99cc81fc3789f6a6c05cdabb46284a3188/cffi-2.0.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:3e837e369566884707ddaf85fc1744b47575005c0a229de3327f8f9a20f4efeb", size = 216402, upload-time = "2025-09-08T23:22:13.455Z" },
+    { url = "https://files.pythonhosted.org/packages/05/eb/b86f2a2645b62adcfff53b0dd97e8dfafb5c8aa864bd0d9a2c2049a0d551/cffi-2.0.0-cp310-cp310-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:5eda85d6d1879e692d546a078b44251cdd08dd1cfb98dfb77b670c97cee49ea0", size = 203217, upload-time = "2025-09-08T23:22:14.596Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/e0/6cbe77a53acf5acc7c08cc186c9928864bd7c005f9efd0d126884858a5fe/cffi-2.0.0-cp310-cp310-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:9332088d75dc3241c702d852d4671613136d90fa6881da7d770a483fd05248b4", size = 203079, upload-time = "2025-09-08T23:22:15.769Z" },
+    { url = "https://files.pythonhosted.org/packages/98/29/9b366e70e243eb3d14a5cb488dfd3a0b6b2f1fb001a203f653b93ccfac88/cffi-2.0.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:fc7de24befaeae77ba923797c7c87834c73648a05a4bde34b3b7e5588973a453", size = 216475, upload-time = "2025-09-08T23:22:17.427Z" },
+    { url = "https://files.pythonhosted.org/packages/21/7a/13b24e70d2f90a322f2900c5d8e1f14fa7e2a6b3332b7309ba7b2ba51a5a/cffi-2.0.0-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:cf364028c016c03078a23b503f02058f1814320a56ad535686f90565636a9495", size = 218829, upload-time = "2025-09-08T23:22:19.069Z" },
+    { url = "https://files.pythonhosted.org/packages/60/99/c9dc110974c59cc981b1f5b66e1d8af8af764e00f0293266824d9c4254bc/cffi-2.0.0-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:e11e82b744887154b182fd3e7e8512418446501191994dbf9c9fc1f32cc8efd5", size = 211211, upload-time = "2025-09-08T23:22:20.588Z" },
+    { url = "https://files.pythonhosted.org/packages/49/72/ff2d12dbf21aca1b32a40ed792ee6b40f6dc3a9cf1644bd7ef6e95e0ac5e/cffi-2.0.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:8ea985900c5c95ce9db1745f7933eeef5d314f0565b27625d9a10ec9881e1bfb", size = 218036, upload-time = "2025-09-08T23:22:22.143Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/cc/027d7fb82e58c48ea717149b03bcadcbdc293553edb283af792bd4bcbb3f/cffi-2.0.0-cp310-cp310-win32.whl", hash = "sha256:1f72fb8906754ac8a2cc3f9f5aaa298070652a0ffae577e0ea9bd480dc3c931a", size = 172184, upload-time = "2025-09-08T23:22:23.328Z" },
+    { url = "https://files.pythonhosted.org/packages/33/fa/072dd15ae27fbb4e06b437eb6e944e75b068deb09e2a2826039e49ee2045/cffi-2.0.0-cp310-cp310-win_amd64.whl", hash = "sha256:b18a3ed7d5b3bd8d9ef7a8cb226502c6bf8308df1525e1cc676c3680e7176739", size = 182790, upload-time = "2025-09-08T23:22:24.752Z" },
+    { url = "https://files.pythonhosted.org/packages/12/4a/3dfd5f7850cbf0d06dc84ba9aa00db766b52ca38d8b86e3a38314d52498c/cffi-2.0.0-cp311-cp311-macosx_10_13_x86_64.whl", hash = "sha256:b4c854ef3adc177950a8dfc81a86f5115d2abd545751a304c5bcf2c2c7283cfe", size = 184344, upload-time = "2025-09-08T23:22:26.456Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/8b/f0e4c441227ba756aafbe78f117485b25bb26b1c059d01f137fa6d14896b/cffi-2.0.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:2de9a304e27f7596cd03d16f1b7c72219bd944e99cc52b84d0145aefb07cbd3c", size = 180560, upload-time = "2025-09-08T23:22:28.197Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/b7/1200d354378ef52ec227395d95c2576330fd22a869f7a70e88e1447eb234/cffi-2.0.0-cp311-cp311-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:baf5215e0ab74c16e2dd324e8ec067ef59e41125d3eade2b863d294fd5035c92", size = 209613, upload-time = "2025-09-08T23:22:29.475Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/56/6033f5e86e8cc9bb629f0077ba71679508bdf54a9a5e112a3c0b91870332/cffi-2.0.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:730cacb21e1bdff3ce90babf007d0a0917cc3e6492f336c2f0134101e0944f93", size = 216476, upload-time = "2025-09-08T23:22:31.063Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/7f/55fecd70f7ece178db2f26128ec41430d8720f2d12ca97bf8f0a628207d5/cffi-2.0.0-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:6824f87845e3396029f3820c206e459ccc91760e8fa24422f8b0c3d1731cbec5", size = 203374, upload-time = "2025-09-08T23:22:32.507Z" },
+    { url = "https://files.pythonhosted.org/packages/84/ef/a7b77c8bdc0f77adc3b46888f1ad54be8f3b7821697a7b89126e829e676a/cffi-2.0.0-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:9de40a7b0323d889cf8d23d1ef214f565ab154443c42737dfe52ff82cf857664", size = 202597, upload-time = "2025-09-08T23:22:34.132Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/91/500d892b2bf36529a75b77958edfcd5ad8e2ce4064ce2ecfeab2125d72d1/cffi-2.0.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:8941aaadaf67246224cee8c3803777eed332a19d909b47e29c9842ef1e79ac26", size = 215574, upload-time = "2025-09-08T23:22:35.443Z" },
+    { url = "https://files.pythonhosted.org/packages/44/64/58f6255b62b101093d5df22dcb752596066c7e89dd725e0afaed242a61be/cffi-2.0.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:a05d0c237b3349096d3981b727493e22147f934b20f6f125a3eba8f994bec4a9", size = 218971, upload-time = "2025-09-08T23:22:36.805Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/49/fa72cebe2fd8a55fbe14956f9970fe8eb1ac59e5df042f603ef7c8ba0adc/cffi-2.0.0-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:94698a9c5f91f9d138526b48fe26a199609544591f859c870d477351dc7b2414", size = 211972, upload-time = "2025-09-08T23:22:38.436Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/28/dd0967a76aab36731b6ebfe64dec4e981aff7e0608f60c2d46b46982607d/cffi-2.0.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:5fed36fccc0612a53f1d4d9a816b50a36702c28a2aa880cb8a122b3466638743", size = 217078, upload-time = "2025-09-08T23:22:39.776Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/c0/015b25184413d7ab0a410775fdb4a50fca20f5589b5dab1dbbfa3baad8ce/cffi-2.0.0-cp311-cp311-win32.whl", hash = "sha256:c649e3a33450ec82378822b3dad03cc228b8f5963c0c12fc3b1e0ab940f768a5", size = 172076, upload-time = "2025-09-08T23:22:40.95Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/8f/dc5531155e7070361eb1b7e4c1a9d896d0cb21c49f807a6c03fd63fc877e/cffi-2.0.0-cp311-cp311-win_amd64.whl", hash = "sha256:66f011380d0e49ed280c789fbd08ff0d40968ee7b665575489afa95c98196ab5", size = 182820, upload-time = "2025-09-08T23:22:42.463Z" },
+    { url = "https://files.pythonhosted.org/packages/95/5c/1b493356429f9aecfd56bc171285a4c4ac8697f76e9bbbbb105e537853a1/cffi-2.0.0-cp311-cp311-win_arm64.whl", hash = "sha256:c6638687455baf640e37344fe26d37c404db8b80d037c3d29f58fe8d1c3b194d", size = 177635, upload-time = "2025-09-08T23:22:43.623Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/47/4f61023ea636104d4f16ab488e268b93008c3d0bb76893b1b31db1f96802/cffi-2.0.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:6d02d6655b0e54f54c4ef0b94eb6be0607b70853c45ce98bd278dc7de718be5d", size = 185271, upload-time = "2025-09-08T23:22:44.795Z" },
+    { url = "https://files.pythonhosted.org/packages/df/a2/781b623f57358e360d62cdd7a8c681f074a71d445418a776eef0aadb4ab4/cffi-2.0.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:8eca2a813c1cb7ad4fb74d368c2ffbbb4789d377ee5bb8df98373c2cc0dee76c", size = 181048, upload-time = "2025-09-08T23:22:45.938Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/df/a4f0fbd47331ceeba3d37c2e51e9dfc9722498becbeec2bd8bc856c9538a/cffi-2.0.0-cp312-cp312-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:21d1152871b019407d8ac3985f6775c079416c282e431a4da6afe7aefd2bccbe", size = 212529, upload-time = "2025-09-08T23:22:47.349Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/72/12b5f8d3865bf0f87cf1404d8c374e7487dcf097a1c91c436e72e6badd83/cffi-2.0.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:b21e08af67b8a103c71a250401c78d5e0893beff75e28c53c98f4de42f774062", size = 220097, upload-time = "2025-09-08T23:22:48.677Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/95/7a135d52a50dfa7c882ab0ac17e8dc11cec9d55d2c18dda414c051c5e69e/cffi-2.0.0-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:1e3a615586f05fc4065a8b22b8152f0c1b00cdbc60596d187c2a74f9e3036e4e", size = 207983, upload-time = "2025-09-08T23:22:50.06Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/c8/15cb9ada8895957ea171c62dc78ff3e99159ee7adb13c0123c001a2546c1/cffi-2.0.0-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:81afed14892743bbe14dacb9e36d9e0e504cd204e0b165062c488942b9718037", size = 206519, upload-time = "2025-09-08T23:22:51.364Z" },
+    { url = "https://files.pythonhosted.org/packages/78/2d/7fa73dfa841b5ac06c7b8855cfc18622132e365f5b81d02230333ff26e9e/cffi-2.0.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:3e17ed538242334bf70832644a32a7aae3d83b57567f9fd60a26257e992b79ba", size = 219572, upload-time = "2025-09-08T23:22:52.902Z" },
+    { url = "https://files.pythonhosted.org/packages/07/e0/267e57e387b4ca276b90f0434ff88b2c2241ad72b16d31836adddfd6031b/cffi-2.0.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:3925dd22fa2b7699ed2617149842d2e6adde22b262fcbfada50e3d195e4b3a94", size = 222963, upload-time = "2025-09-08T23:22:54.518Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/75/1f2747525e06f53efbd878f4d03bac5b859cbc11c633d0fb81432d98a795/cffi-2.0.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:2c8f814d84194c9ea681642fd164267891702542f028a15fc97d4674b6206187", size = 221361, upload-time = "2025-09-08T23:22:55.867Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/2b/2b6435f76bfeb6bbf055596976da087377ede68df465419d192acf00c437/cffi-2.0.0-cp312-cp312-win32.whl", hash = "sha256:da902562c3e9c550df360bfa53c035b2f241fed6d9aef119048073680ace4a18", size = 172932, upload-time = "2025-09-08T23:22:57.188Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/ed/13bd4418627013bec4ed6e54283b1959cf6db888048c7cf4b4c3b5b36002/cffi-2.0.0-cp312-cp312-win_amd64.whl", hash = "sha256:da68248800ad6320861f129cd9c1bf96ca849a2771a59e0344e88681905916f5", size = 183557, upload-time = "2025-09-08T23:22:58.351Z" },
+    { url = "https://files.pythonhosted.org/packages/95/31/9f7f93ad2f8eff1dbc1c3656d7ca5bfd8fb52c9d786b4dcf19b2d02217fa/cffi-2.0.0-cp312-cp312-win_arm64.whl", hash = "sha256:4671d9dd5ec934cb9a73e7ee9676f9362aba54f7f34910956b84d727b0d73fb6", size = 177762, upload-time = "2025-09-08T23:22:59.668Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/8d/a0a47a0c9e413a658623d014e91e74a50cdd2c423f7ccfd44086ef767f90/cffi-2.0.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:00bdf7acc5f795150faa6957054fbbca2439db2f775ce831222b66f192f03beb", size = 185230, upload-time = "2025-09-08T23:23:00.879Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/d2/a6c0296814556c68ee32009d9c2ad4f85f2707cdecfd7727951ec228005d/cffi-2.0.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:45d5e886156860dc35862657e1494b9bae8dfa63bf56796f2fb56e1679fc0bca", size = 181043, upload-time = "2025-09-08T23:23:02.231Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/1e/d22cc63332bd59b06481ceaac49d6c507598642e2230f201649058a7e704/cffi-2.0.0-cp313-cp313-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:07b271772c100085dd28b74fa0cd81c8fb1a3ba18b21e03d7c27f3436a10606b", size = 212446, upload-time = "2025-09-08T23:23:03.472Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/f5/a2c23eb03b61a0b8747f211eb716446c826ad66818ddc7810cc2cc19b3f2/cffi-2.0.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:d48a880098c96020b02d5a1f7d9251308510ce8858940e6fa99ece33f610838b", size = 220101, upload-time = "2025-09-08T23:23:04.792Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/7f/e6647792fc5850d634695bc0e6ab4111ae88e89981d35ac269956605feba/cffi-2.0.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:f93fd8e5c8c0a4aa1f424d6173f14a892044054871c771f8566e4008eaa359d2", size = 207948, upload-time = "2025-09-08T23:23:06.127Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/1e/a5a1bd6f1fb30f22573f76533de12a00bf274abcdc55c8edab639078abb6/cffi-2.0.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:dd4f05f54a52fb558f1ba9f528228066954fee3ebe629fc1660d874d040ae5a3", size = 206422, upload-time = "2025-09-08T23:23:07.753Z" },
+    { url = "https://files.pythonhosted.org/packages/98/df/0a1755e750013a2081e863e7cd37e0cdd02664372c754e5560099eb7aa44/cffi-2.0.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:c8d3b5532fc71b7a77c09192b4a5a200ea992702734a2e9279a37f2478236f26", size = 219499, upload-time = "2025-09-08T23:23:09.648Z" },
+    { url = "https://files.pythonhosted.org/packages/50/e1/a969e687fcf9ea58e6e2a928ad5e2dd88cc12f6f0ab477e9971f2309b57c/cffi-2.0.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:d9b29c1f0ae438d5ee9acb31cadee00a58c46cc9c0b2f9038c6b0b3470877a8c", size = 222928, upload-time = "2025-09-08T23:23:10.928Z" },
+    { url = "https://files.pythonhosted.org/packages/36/54/0362578dd2c9e557a28ac77698ed67323ed5b9775ca9d3fe73fe191bb5d8/cffi-2.0.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:6d50360be4546678fc1b79ffe7a66265e28667840010348dd69a314145807a1b", size = 221302, upload-time = "2025-09-08T23:23:12.42Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/6d/bf9bda840d5f1dfdbf0feca87fbdb64a918a69bca42cfa0ba7b137c48cb8/cffi-2.0.0-cp313-cp313-win32.whl", hash = "sha256:74a03b9698e198d47562765773b4a8309919089150a0bb17d829ad7b44b60d27", size = 172909, upload-time = "2025-09-08T23:23:14.32Z" },
+    { url = "https://files.pythonhosted.org/packages/37/18/6519e1ee6f5a1e579e04b9ddb6f1676c17368a7aba48299c3759bbc3c8b3/cffi-2.0.0-cp313-cp313-win_amd64.whl", hash = "sha256:19f705ada2530c1167abacb171925dd886168931e0a7b78f5bffcae5c6b5be75", size = 183402, upload-time = "2025-09-08T23:23:15.535Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/0e/02ceeec9a7d6ee63bb596121c2c8e9b3a9e150936f4fbef6ca1943e6137c/cffi-2.0.0-cp313-cp313-win_arm64.whl", hash = "sha256:256f80b80ca3853f90c21b23ee78cd008713787b1b1e93eae9f3d6a7134abd91", size = 177780, upload-time = "2025-09-08T23:23:16.761Z" },
+    { url = "https://files.pythonhosted.org/packages/92/c4/3ce07396253a83250ee98564f8d7e9789fab8e58858f35d07a9a2c78de9f/cffi-2.0.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:fc33c5141b55ed366cfaad382df24fe7dcbc686de5be719b207bb248e3053dc5", size = 185320, upload-time = "2025-09-08T23:23:18.087Z" },
+    { url = "https://files.pythonhosted.org/packages/59/dd/27e9fa567a23931c838c6b02d0764611c62290062a6d4e8ff7863daf9730/cffi-2.0.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:c654de545946e0db659b3400168c9ad31b5d29593291482c43e3564effbcee13", size = 181487, upload-time = "2025-09-08T23:23:19.622Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/43/0e822876f87ea8a4ef95442c3d766a06a51fc5298823f884ef87aaad168c/cffi-2.0.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:24b6f81f1983e6df8db3adc38562c83f7d4a0c36162885ec7f7b77c7dcbec97b", size = 220049, upload-time = "2025-09-08T23:23:20.853Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/89/76799151d9c2d2d1ead63c2429da9ea9d7aac304603de0c6e8764e6e8e70/cffi-2.0.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:12873ca6cb9b0f0d3a0da705d6086fe911591737a59f28b7936bdfed27c0d47c", size = 207793, upload-time = "2025-09-08T23:23:22.08Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/dd/3465b14bb9e24ee24cb88c9e3730f6de63111fffe513492bf8c808a3547e/cffi-2.0.0-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:d9b97165e8aed9272a6bb17c01e3cc5871a594a446ebedc996e2397a1c1ea8ef", size = 206300, upload-time = "2025-09-08T23:23:23.314Z" },
+    { url = "https://files.pythonhosted.org/packages/47/d9/d83e293854571c877a92da46fdec39158f8d7e68da75bf73581225d28e90/cffi-2.0.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:afb8db5439b81cf9c9d0c80404b60c3cc9c3add93e114dcae767f1477cb53775", size = 219244, upload-time = "2025-09-08T23:23:24.541Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/0f/1f177e3683aead2bb00f7679a16451d302c436b5cbf2505f0ea8146ef59e/cffi-2.0.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:737fe7d37e1a1bffe70bd5754ea763a62a066dc5913ca57e957824b72a85e205", size = 222828, upload-time = "2025-09-08T23:23:26.143Z" },
+    { url = "https://files.pythonhosted.org/packages/c6/0f/cafacebd4b040e3119dcb32fed8bdef8dfe94da653155f9d0b9dc660166e/cffi-2.0.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:38100abb9d1b1435bc4cc340bb4489635dc2f0da7456590877030c9b3d40b0c1", size = 220926, upload-time = "2025-09-08T23:23:27.873Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/aa/df335faa45b395396fcbc03de2dfcab242cd61a9900e914fe682a59170b1/cffi-2.0.0-cp314-cp314-win32.whl", hash = "sha256:087067fa8953339c723661eda6b54bc98c5625757ea62e95eb4898ad5e776e9f", size = 175328, upload-time = "2025-09-08T23:23:44.61Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/92/882c2d30831744296ce713f0feb4c1cd30f346ef747b530b5318715cc367/cffi-2.0.0-cp314-cp314-win_amd64.whl", hash = "sha256:203a48d1fb583fc7d78a4c6655692963b860a417c0528492a6bc21f1aaefab25", size = 185650, upload-time = "2025-09-08T23:23:45.848Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/2c/98ece204b9d35a7366b5b2c6539c350313ca13932143e79dc133ba757104/cffi-2.0.0-cp314-cp314-win_arm64.whl", hash = "sha256:dbd5c7a25a7cb98f5ca55d258b103a2054f859a46ae11aaf23134f9cc0d356ad", size = 180687, upload-time = "2025-09-08T23:23:47.105Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/61/c768e4d548bfa607abcda77423448df8c471f25dbe64fb2ef6d555eae006/cffi-2.0.0-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:9a67fc9e8eb39039280526379fb3a70023d77caec1852002b4da7e8b270c4dd9", size = 188773, upload-time = "2025-09-08T23:23:29.347Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/ea/5f76bce7cf6fcd0ab1a1058b5af899bfbef198bea4d5686da88471ea0336/cffi-2.0.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:7a66c7204d8869299919db4d5069a82f1561581af12b11b3c9f48c584eb8743d", size = 185013, upload-time = "2025-09-08T23:23:30.63Z" },
+    { url = "https://files.pythonhosted.org/packages/be/b4/c56878d0d1755cf9caa54ba71e5d049479c52f9e4afc230f06822162ab2f/cffi-2.0.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:7cc09976e8b56f8cebd752f7113ad07752461f48a58cbba644139015ac24954c", size = 221593, upload-time = "2025-09-08T23:23:31.91Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/0d/eb704606dfe8033e7128df5e90fee946bbcb64a04fcdaa97321309004000/cffi-2.0.0-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:92b68146a71df78564e4ef48af17551a5ddd142e5190cdf2c5624d0c3ff5b2e8", size = 209354, upload-time = "2025-09-08T23:23:33.214Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/19/3c435d727b368ca475fb8742ab97c9cb13a0de600ce86f62eab7fa3eea60/cffi-2.0.0-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:b1e74d11748e7e98e2f426ab176d4ed720a64412b6a15054378afdb71e0f37dc", size = 208480, upload-time = "2025-09-08T23:23:34.495Z" },
+    { url = "https://files.pythonhosted.org/packages/d0/44/681604464ed9541673e486521497406fadcc15b5217c3e326b061696899a/cffi-2.0.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:28a3a209b96630bca57cce802da70c266eb08c6e97e5afd61a75611ee6c64592", size = 221584, upload-time = "2025-09-08T23:23:36.096Z" },
+    { url = "https://files.pythonhosted.org/packages/25/8e/342a504ff018a2825d395d44d63a767dd8ebc927ebda557fecdaca3ac33a/cffi-2.0.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:7553fb2090d71822f02c629afe6042c299edf91ba1bf94951165613553984512", size = 224443, upload-time = "2025-09-08T23:23:37.328Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/5e/b666bacbbc60fbf415ba9988324a132c9a7a0448a9a8f125074671c0f2c3/cffi-2.0.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:6c6c373cfc5c83a975506110d17457138c8c63016b563cc9ed6e056a82f13ce4", size = 223437, upload-time = "2025-09-08T23:23:38.945Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/1d/ec1a60bd1a10daa292d3cd6bb0b359a81607154fb8165f3ec95fe003b85c/cffi-2.0.0-cp314-cp314t-win32.whl", hash = "sha256:1fc9ea04857caf665289b7a75923f2c6ed559b8298a1b8c49e59f7dd95c8481e", size = 180487, upload-time = "2025-09-08T23:23:40.423Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/41/4c1168c74fac325c0c8156f04b6749c8b6a8f405bbf91413ba088359f60d/cffi-2.0.0-cp314-cp314t-win_amd64.whl", hash = "sha256:d68b6cef7827e8641e8ef16f4494edda8b36104d79773a334beaa1e3521430f6", size = 191726, upload-time = "2025-09-08T23:23:41.742Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/3a/dbeec9d1ee0844c679f6bb5d6ad4e9f198b1224f4e7a32825f47f6192b0c/cffi-2.0.0-cp314-cp314t-win_arm64.whl", hash = "sha256:0a1527a803f0a659de1af2e1fd700213caba79377e27e4693648c2923da066f9", size = 184195, upload-time = "2025-09-08T23:23:43.004Z" },
+]
+
+[[package]]
+name = "click"
+version = "8.3.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/3d/fa/656b739db8587d7b5dfa22e22ed02566950fbfbcdc20311993483657a5c0/click-8.3.1.tar.gz", hash = "sha256:12ff4785d337a1bb490bb7e9c2b1ee5da3112e94a8622f26a6c77f5d2fc6842a", size = 295065, upload-time = "2025-11-15T20:45:42.706Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/98/78/01c019cdb5d6498122777c1a43056ebb3ebfeef2076d9d026bfe15583b2b/click-8.3.1-py3-none-any.whl", hash = "sha256:981153a64e25f12d547d3426c367a4857371575ee7ad18df2a6183ab0545b2a6", size = 108274, upload-time = "2025-11-15T20:45:41.139Z" },
+]
+
+[[package]]
+name = "colorama"
+version = "0.4.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
+]
+
+[[package]]
+name = "cryptography"
+version = "49.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cffi", marker = "platform_python_implementation != 'PyPy'" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/1f/99/d1c90d6041656cc6ee229dc99cd67fd0cd5aec3c5f7d72fffc27cc750054/cryptography-49.0.0.tar.gz", hash = "sha256:f89660a348f4f78a92366240a61404e337586ef7f5909a2fef59ca88ef505493", size = 854345, upload-time = "2026-06-12T20:02:30.512Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9b/22/adf66990e63584a68dfb50c24f48a125c07b1699899381c8151e63ed458c/cryptography-49.0.0-cp311-abi3-macosx_11_0_arm64.whl", hash = "sha256:966fe0e9c67490071f14c0d2b1cb2dfb3023c5ce39457343931415f08382f2db", size = 4032100, upload-time = "2026-06-12T20:02:32.143Z" },
+    { url = "https://files.pythonhosted.org/packages/09/41/3797cfaf69cae04a13ee78ebd83f0678d9c02b4779d21ce24445326f1a69/cryptography-49.0.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:36d1709f992593689b45bda411498d62c6e365f2ca00b84657d4dadd24de16db", size = 4692978, upload-time = "2026-06-12T20:01:21.305Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/8b/43011f7ebe515a8aa20d61f290a326cd890c2e738e16e59eaff8d9c3a412/cryptography-49.0.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:0e959b578856a3924bc0cbb710fc12c387b9412a951389f3ca61704a9e25f325", size = 4716422, upload-time = "2026-06-12T20:01:48.566Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/91/01ce7303a4579e6d3a6abef01bd322848e9ea7a219adcabc5048b9033571/cryptography-49.0.0-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:53ecee2e23f7169b6117e99fc8a944e5e50f79e69758a83b52a00cb98ab2b2d2", size = 4700503, upload-time = "2026-06-12T20:02:47.091Z" },
+    { url = "https://files.pythonhosted.org/packages/62/99/a2c95cf8293f07491e9e27c20cc4dcd18176d944e674679adeb1d0173fd6/cryptography-49.0.0-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:2eda353d8a27bcbcaa4cbed18994a74ab4d19a2ca897db188ea269ab9b71419b", size = 5309779, upload-time = "2026-06-12T20:02:08.987Z" },
+    { url = "https://files.pythonhosted.org/packages/20/2c/0622f20ff02b2ef32558733443805dc82fd4c275be01b2d19d14676f3a1b/cryptography-49.0.0-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:2afe9051da7ae7bd5905da5a949280c7d2bb75682e188f650a9d0f2756b834c6", size = 4749683, upload-time = "2026-06-12T20:02:03.335Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/5b/c5246635d5fd3b64e0d45ae10e99fd32fe9676a79915ccfe5a61ba9af1a5/cryptography-49.0.0-cp311-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:0b82e28ee398a386f0807bba7884d30f25218855690f45115831bcce5d90822c", size = 4337874, upload-time = "2026-06-12T20:02:54.323Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/88/05563c7fe2e914e87d1a536d06fe83e66b4e1d95cb593e05aea375531da8/cryptography-49.0.0-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:ccac2bfebc306b862133e3bb71f3f6ee8bb525240089b2d952e4144b3a6d5da7", size = 4700283, upload-time = "2026-06-12T20:01:34.822Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/b6/d7696e4e890d6ae1469935164c9e5215c557671cb78d6e3f458ccceaa632/cryptography-49.0.0-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:d0527ce944105f257f605a827d6ebead966c752038b6e8656abb9c5edee6fc68", size = 5265844, upload-time = "2026-06-12T20:01:24.09Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/3c/f3ad17eecc1a57b0ba236dc01f90e783c51f4a2f35f64777cc4f47a184b2/cryptography-49.0.0-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:cbc77da8c523d5abd028635ba850a6966fcee2c82e2bf65a41d1d8afe0f98be9", size = 4749290, upload-time = "2026-06-12T20:01:30.848Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/01/339573cf1023163a400b0b5d16f6d507de413b9f60be6fd1b77feeaf6737/cryptography-49.0.0-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:b87e65d263b3e5d3bb92a57e2a6638e2f31110fa7aa890c7b2dbba42248d0a3f", size = 4834612, upload-time = "2026-06-12T20:01:29.246Z" },
+    { url = "https://files.pythonhosted.org/packages/71/fd/577302e213a1be9468f92d1afef66fcf1ef83d516819d9992ca547f592bd/cryptography-49.0.0-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:66ec79c3904820572d7e987abdf304281f141d37ad9a489b8e97066e7b9b6459", size = 4980804, upload-time = "2026-06-12T20:01:42.853Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/09/f42b1d190c5ba75f72062a387f8030d1d75f6ab035788f1d9c4b01de6525/cryptography-49.0.0-cp311-abi3-win_amd64.whl", hash = "sha256:e5dfc1e64de5677cec922ffa8da89c546d0415bf6efdf081842e5d44c84e1f0e", size = 3810026, upload-time = "2026-06-12T20:02:39.262Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/9e/db72b3ae7fc9cfad53e630e56c6ae83b9b6ff0bf3718ffb8012d20b3aabf/cryptography-49.0.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:73a205dce83953d131a4aa1e0fd917a2fd1c5b1eef251e9d7152efefcbf5caf7", size = 4013892, upload-time = "2026-06-12T20:02:10.735Z" },
+    { url = "https://files.pythonhosted.org/packages/86/12/c48a424f38db03027be9f7ed5c7dc5de9933dbee992865f98b13727a009d/cryptography-49.0.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:196ecd6a36e4e9aa10270393bb98d8df88fccee0bf1e5128b91ae4eb4375896d", size = 4678835, upload-time = "2026-06-12T20:02:48.743Z" },
+    { url = "https://files.pythonhosted.org/packages/68/28/8a3ad4653662c93fc44dc4e5d8fd374c25c42e07b34bbfbadf49cf57a5a8/cryptography-49.0.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:7abcee80084cda3f7691f3eb1ce480d8df49cec637b429aa35986c1de71738aa", size = 4697239, upload-time = "2026-06-12T20:02:56.03Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/b2/2193fc74f81aee4f9b62733133b73b5176718932ed8f2e4b03fa040480a6/cryptography-49.0.0-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:4ae387c9cb68ea569ca17e490d66d8142b81c3cc814bf179974b7d146e490bbb", size = 4685593, upload-time = "2026-06-12T20:02:50.666Z" },
+    { url = "https://files.pythonhosted.org/packages/47/f1/1d3eaa243bfc5de4a187b22aa8c048b3e4980bfbe830ac46e6bac2e66947/cryptography-49.0.0-cp314-cp314t-manylinux_2_28_ppc64le.whl", hash = "sha256:f37d847238971164fdbc68ade6f6574aecc9c0af714190e2083429ff68f4ce9d", size = 5289961, upload-time = "2026-06-12T20:01:46.468Z" },
+    { url = "https://files.pythonhosted.org/packages/58/39/2d51306721330c486495853eda1c567880ff036de15a14c4b74f399934af/cryptography-49.0.0-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:c2bc30226390d60ea19d9f82b19db005fe0452154a23c1c410c12ea801e43561", size = 4731145, upload-time = "2026-06-12T20:02:16.832Z" },
+    { url = "https://files.pythonhosted.org/packages/17/50/983e838c7fd0d87fd8c969bcdd328edaf5f756e38df5281637424c155873/cryptography-49.0.0-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:07cab27cc7b7e0fd28e5e26bb9eeedde5c135c868b46de4a27845abe94af6122", size = 4321719, upload-time = "2026-06-12T20:02:52.611Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/f5/8f571d7e27c55bce9f76f026143bcb1e040a4233149ecca0bea5fa5dd5f7/cryptography-49.0.0-cp314-cp314t-manylinux_2_34_aarch64.whl", hash = "sha256:b20133d204d2bb56ba047642199603876c872026ca53e79c35b83772ab2cc505", size = 4685209, upload-time = "2026-06-12T20:02:07.282Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/84/0e27016a6fc5a0886f797018b26aa42f40c09a82332bff77822a451deaaa/cryptography-49.0.0-cp314-cp314t-manylinux_2_34_ppc64le.whl", hash = "sha256:b970c6da94d5bb18629db453d14f2a1300f6bf59b61e9b82377931ef95504866", size = 5246285, upload-time = "2026-06-12T20:01:32.439Z" },
+    { url = "https://files.pythonhosted.org/packages/11/2d/5e1fb307cb5931881516b464c98774b3f2c36b5d4bb9a2830253cf553cad/cryptography-49.0.0-cp314-cp314t-manylinux_2_34_x86_64.whl", hash = "sha256:d8ecde755e2e91bf773fc94e8c9d730cd7f2007004cb492263a794ec3899a1c8", size = 4730441, upload-time = "2026-06-12T20:02:01.469Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/c0/bff5a02ee731d207d6a1ed51732549d8c53d2bc8da1d10ec6f2844201d68/cryptography-49.0.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:e3fb64c420688e5319ae25113a354015abbd8dffbfbc41781a1ea66fc7622ac3", size = 4815869, upload-time = "2026-06-12T20:01:36.574Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/26/814681d14248d95d73d5c3eea0c39a94eb8302df966f670a2c60de90974b/cryptography-49.0.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:32703d93296f5c1f4b53349ad3a250c2cae0fdecd3a3dd5d47e616d8d616af27", size = 4960948, upload-time = "2026-06-12T20:02:18.688Z" },
+    { url = "https://files.pythonhosted.org/packages/4c/fe/93ecac273d3738939d023612ad12cca9a3740a5345d69fda04134c43fd96/cryptography-49.0.0-cp314-cp314t-win_amd64.whl", hash = "sha256:33cd0565932807baddb67b96dbee92f2c374b5c89dee09fd74079aeb8c8dba61", size = 3799153, upload-time = "2026-06-12T20:01:39.059Z" },
+    { url = "https://files.pythonhosted.org/packages/19/2a/5bb823f5bedcf80718cea7fbc95ec5515cca3769633c4b01a32be7f30e7c/cryptography-49.0.0-cp39-abi3-macosx_11_0_arm64.whl", hash = "sha256:ec5e529fb80935c94fe7b729f9972b50e351a0e6b50aa294fd5cabb109fcc29a", size = 4025947, upload-time = "2026-06-12T20:01:25.745Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/df/40577043ca124e17012f408ddddaeb213b856336ac82ddb3bc915f39e29f/cryptography-49.0.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:f78ff2c9ed8dc2d036b0f4d640e22522213d047c1b14e61205a7e55c80a494d4", size = 4692429, upload-time = "2026-06-12T20:01:53.628Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/99/2d13299eb3dd27b02dcfaafcc91d6b5cb3329f7cbd6d8f51921acd566c1a/cryptography-49.0.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:35b151772baff2c74cba7fa290ceaff4c3b11c0c881eb93eb5dbc05a7cfbba18", size = 4700968, upload-time = "2026-06-12T20:02:45.383Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/4d/9c0cd02f95e2602dd5e563da149ee0830abef3537be8b34dc56281ebe27a/cryptography-49.0.0-cp39-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:0f21641cf4b30fca7aee061ced0ec7ad7b073518088b7c9969a297c0ae796c69", size = 4697758, upload-time = "2026-06-12T20:01:41.13Z" },
+    { url = "https://files.pythonhosted.org/packages/24/01/186c825898477d77e2324d5360fefe622ff1d8d1963ec0554e2cada8ec77/cryptography-49.0.0-cp39-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:9e82dcc8e56052715fb18b2429e3bca4823b1629136a2084fc45a9a5cecb9b64", size = 5298863, upload-time = "2026-06-12T20:02:24.579Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/7b/62cbbab75d0659865bf0273790031544a0b16c8072d258f9428dcd8190dc/cryptography-49.0.0-cp39-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:6f2debedf9ca60cf1d5bd466475638af5130f89965605cd818484d19987d3a21", size = 4735983, upload-time = "2026-06-12T20:01:50.14Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/72/3e798c064bc39e471008075d0f9bc9daf77a80879c092e4a8e170c585ed4/cryptography-49.0.0-cp39-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:8c25ceb16df5b9435f3f6a9829204985b0e0cbee3b48aacd432c7d2c850b44d9", size = 4334173, upload-time = "2026-06-12T20:01:44.743Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/ee/6fca21d1ac73e06f8bef71940abfd4d2f6472b4bca284d770f32bd4086f6/cryptography-49.0.0-cp39-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:28d8b15e6275f12c8a207dc309dfa957903c927d08d0cc937ee3f63f200693cc", size = 4697298, upload-time = "2026-06-12T20:02:20.918Z" },
+    { url = "https://files.pythonhosted.org/packages/67/d0/a5fcd3515f0bae49a7b6d0413cc1bdccdcc1fc0047037a0d480642cdc5d6/cryptography-49.0.0-cp39-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:6fc361c34fb6aac015ce19435876635e5c6d21db31998b0920f675f131e043b8", size = 5254338, upload-time = "2026-06-12T20:02:22.737Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/84/84fe36f19caf857d61cb7fc9c63035a47ffabd84ea12d1d393148efa3615/cryptography-49.0.0-cp39-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:2400ef9c9e2299a25614eb1dea3db54a69b1349efd043bfac9c67630d136df36", size = 4735650, upload-time = "2026-06-12T20:02:41.389Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/a0/db537264e234f7273a73ec020873d6d6b39dfd8a53db78b550ca8320440e/cryptography-49.0.0-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:67e1d20ad9ef3a563c59ef22e7a8a0b8210bd26604369ea4a30a7c66aefe504e", size = 4834820, upload-time = "2026-06-12T20:01:51.847Z" },
+    { url = "https://files.pythonhosted.org/packages/93/77/8df9eb486495979bccecd1062e2eaf435250e84437040295b57d09048b0b/cryptography-49.0.0-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:42b0684e0e40cf26122427802486f6d93aea593612603a94fbf260c7eb1e9c1b", size = 4967968, upload-time = "2026-06-12T20:02:12.524Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/e6/f60198ea8d9dfa15fff9ed4ca02ce362f6eadd9ba757dcc50634c4257b63/cryptography-49.0.0-cp39-abi3-win_amd64.whl", hash = "sha256:026ac7423e6fa66872d3bf889be5974507da3944f866f704fa200eadacd00001", size = 3785547, upload-time = "2026-06-12T20:02:26.847Z" },
+    { url = "https://files.pythonhosted.org/packages/63/d3/4a83af35d65e3fad632c926fad684c193ea4398569ccb0bbbc7fe8f5dc9a/cryptography-49.0.0-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:fc1e275c2f1d97b1a6450b8b0ea3ebfa6e087a611c2b26cb2404d48588abab7b", size = 3993685, upload-time = "2026-06-12T20:02:14.883Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/a7/f9dac0ab7f80368c56993a7bf638ef9935f825c91902798481fac0898138/cryptography-49.0.0-pp311-pypy311_pp73-manylinux_2_28_aarch64.whl", hash = "sha256:c83782480a4a9da4d0feb51950131ba32e12e70813848b3343f6e18c28a66838", size = 4676239, upload-time = "2026-06-12T20:02:28.793Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/70/2ba3769dd0ae167e2f33dfa9592d45db6ff9a61d62ca1a5b3d1bdd09068f/cryptography-49.0.0-pp311-pypy311_pp73-manylinux_2_28_x86_64.whl", hash = "sha256:b39efa323140595abd3ecca8529d321ae50f55f3aa3ba9cc81ea56a6011953d5", size = 4715584, upload-time = "2026-06-12T20:01:27.495Z" },
+    { url = "https://files.pythonhosted.org/packages/94/64/2923570ac1c0bd3a737aa366ac3abbbbde273042308b8cde95e2364a6e6a/cryptography-49.0.0-pp311-pypy311_pp73-manylinux_2_34_aarch64.whl", hash = "sha256:b47db11c2c3525083296069b98ac5221907455e989ae0c2e3008bde851921615", size = 4675885, upload-time = "2026-06-12T20:01:55.49Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/f8/614dc7e051418cfe53d55173c1e24c6b0085e89996fe90508c2fdf769aef/cryptography-49.0.0-pp311-pypy311_pp73-manylinux_2_34_x86_64.whl", hash = "sha256:084ef1af862eb07ec46d25f68689f2102a9fc0e05ce7b80f14f5fe51e4eef0f6", size = 4715449, upload-time = "2026-06-12T20:02:05.469Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/50/a9caea39ad19c431c1a3f8a31114df65b260cdfe67786b6c7e7c040c4c44/cryptography-49.0.0-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:be9fcb48a55f023493482827d4f459bd263cc20efde64f204b97c123201850c6", size = 3783731, upload-time = "2026-06-12T20:02:43.319Z" },
+]
+
+[[package]]
+name = "cyclopts"
+version = "4.10.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "attrs" },
+    { name = "docstring-parser" },
+    { name = "rich" },
+    { name = "rich-rst" },
+    { name = "tomli", marker = "python_full_version < '3.11'" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/2c/e7/3e26855c046ac527cf94d890f6698e703980337f22ea7097e02b35b910f9/cyclopts-4.10.0.tar.gz", hash = "sha256:0ae04a53274e200ef3477c8b54de63b019bc6cd0162d75c718bf40c9c3fb5268", size = 166394, upload-time = "2026-03-14T14:09:31.043Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/06/06/d68a5d5d292c2ad2bc6a02e5ca2cb1bb9c15e941ab02f004a06a342d7f0f/cyclopts-4.10.0-py3-none-any.whl", hash = "sha256:50f333382a60df8d40ec14aa2e627316b361c4f478598ada1f4169d959bf9ea7", size = 204097, upload-time = "2026-03-14T14:09:32.504Z" },
+]
+
+[[package]]
+name = "dirty-equals"
+version = "0.11"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/30/1d/c5913ac9d6615515a00f4bdc71356d302437cb74ff2e9aaccd3c14493b78/dirty_equals-0.11.tar.gz", hash = "sha256:f4ac74ee88f2d11e2fa0f65eb30ee4f07105c5f86f4dc92b09eb1138775027c3", size = 128067, upload-time = "2025-11-17T01:51:24.451Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/bb/8d/dbff05239043271dbeace563a7686212a3dd517864a35623fe4d4a64ca19/dirty_equals-0.11-py3-none-any.whl", hash = "sha256:b1d7093273fc2f9be12f443a8ead954ef6daaf6746fd42ef3a5616433ee85286", size = 28051, upload-time = "2025-11-17T01:51:22.849Z" },
+]
+
+[[package]]
+name = "dnspython"
+version = "2.8.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/8c/8b/57666417c0f90f08bcafa776861060426765fdb422eb10212086fb811d26/dnspython-2.8.0.tar.gz", hash = "sha256:181d3c6996452cb1189c4046c61599b84a5a86e099562ffde77d26984ff26d0f", size = 368251, upload-time = "2025-09-07T18:58:00.022Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ba/5a/18ad964b0086c6e62e2e7500f7edc89e3faa45033c71c1893d34eed2b2de/dnspython-2.8.0-py3-none-any.whl", hash = "sha256:01d9bbc4a2d76bf0db7c1f729812ded6d912bd318d3b1cf81d30c0f845dbf3af", size = 331094, upload-time = "2025-09-07T18:57:58.071Z" },
+]
+
+[[package]]
+name = "docstring-parser"
+version = "0.17.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b2/9d/c3b43da9515bd270df0f80548d9944e389870713cc1fe2b8fb35fe2bcefd/docstring_parser-0.17.0.tar.gz", hash = "sha256:583de4a309722b3315439bb31d64ba3eebada841f2e2cee23b99df001434c912", size = 27442, upload-time = "2025-07-21T07:35:01.868Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/55/e2/2537ebcff11c1ee1ff17d8d0b6f4db75873e3b0fb32c2d4a2ee31ecb310a/docstring_parser-0.17.0-py3-none-any.whl", hash = "sha256:cf2569abd23dce8099b300f9b4fa8191e9582dda731fd533daf54c4551658708", size = 36896, upload-time = "2025-07-21T07:35:00.684Z" },
+]
+
+[[package]]
+name = "docutils"
+version = "0.22.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ae/b6/03bb70946330e88ffec97aefd3ea75ba575cb2e762061e0e62a213befee8/docutils-0.22.4.tar.gz", hash = "sha256:4db53b1fde9abecbb74d91230d32ab626d94f6badfc575d6db9194a49df29968", size = 2291750, upload-time = "2025-12-18T19:00:26.443Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/02/10/5da547df7a391dcde17f59520a231527b8571e6f46fc8efb02ccb370ab12/docutils-0.22.4-py3-none-any.whl", hash = "sha256:d0013f540772d1420576855455d050a2180186c91c15779301ac2ccb3eeb68de", size = 633196, upload-time = "2025-12-18T19:00:18.077Z" },
+]
+
+[[package]]
+name = "email-validator"
+version = "2.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "dnspython" },
+    { name = "idna" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f5/22/900cb125c76b7aaa450ce02fd727f452243f2e91a61af068b40adba60ea9/email_validator-2.3.0.tar.gz", hash = "sha256:9fc05c37f2f6cf439ff414f8fc46d917929974a82244c20eb10231ba60c54426", size = 51238, upload-time = "2025-08-26T13:09:06.831Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/de/15/545e2b6cf2e3be84bc1ed85613edd75b8aea69807a71c26f4ca6a9258e82/email_validator-2.3.0-py3-none-any.whl", hash = "sha256:80f13f623413e6b197ae73bb10bf4eb0908faf509ad8362c5edeb0be7fd450b4", size = 35604, upload-time = "2025-08-26T13:09:05.858Z" },
+]
+
+[[package]]
+name = "exceptiongroup"
+version = "1.3.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8a/0e/97c33bf5009bdbac74fd2beace167cab3f978feb69cc36f1ef79360d6c4e/exceptiongroup-1.3.1-py3-none-any.whl", hash = "sha256:a7a39a3bd276781e98394987d3a5701d0c4edffb633bb7a5144577f82c773598", size = 16740, upload-time = "2025-11-21T23:01:53.443Z" },
+]
+
+[[package]]
+name = "fastmcp"
+version = "3.2.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "authlib" },
+    { name = "cyclopts" },
+    { name = "exceptiongroup" },
+    { name = "httpx" },
+    { name = "jsonref" },
+    { name = "jsonschema-path" },
+    { name = "mcp" },
+    { name = "openapi-pydantic" },
+    { name = "opentelemetry-api" },
+    { name = "packaging" },
+    { name = "platformdirs" },
+    { name = "py-key-value-aio", extra = ["filetree", "keyring", "memory"] },
+    { name = "pydantic", extra = ["email"] },
+    { name = "pyperclip" },
+    { name = "python-dotenv" },
+    { name = "pyyaml" },
+    { name = "rich" },
+    { name = "uncalled-for" },
+    { name = "uvicorn" },
+    { name = "watchfiles" },
+    { name = "websockets" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d0/32/4f1b2cfd7b50db89114949f90158b1dcc2c92a1917b9f57c0ff24e47a2f4/fastmcp-3.2.0.tar.gz", hash = "sha256:d4830b8ffc3592d3d9c76dc0f398904cf41f04910e41a0de38cc1004e0903bef", size = 26318581, upload-time = "2026-03-30T20:25:37.692Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/4f/67/684fa2d2de1e7504549d4ca457b4f854ccec3cd3be03bd86b33b599fbf58/fastmcp-3.2.0-py3-none-any.whl", hash = "sha256:e71aba3df16f86f546a4a9e513261d3233bcc92bef0dfa647bac3fa33623f681", size = 705550, upload-time = "2026-03-30T20:25:35.499Z" },
+]
+
+[[package]]
+name = "h11"
+version = "0.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/01/ee/02a2c011bdab74c6fb3c75474d40b3052059d95df7e73351460c8588d963/h11-0.16.0.tar.gz", hash = "sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1", size = 101250, upload-time = "2025-04-24T03:35:25.427Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" },
+]
+
+[[package]]
+name = "httpcore"
+version = "1.0.9"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "certifi" },
+    { name = "h11" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/94/82699a10bca87a5556c9c59b5963f2d039dbd239f25bc2a63907a05a14cb/httpcore-1.0.9.tar.gz", hash = "sha256:6e34463af53fd2ab5d807f399a9b45ea31c3dfa2276f15a2c3f00afff6e176e8", size = 85484, upload-time = "2025-04-24T22:06:22.219Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7e/f5/f66802a942d491edb555dd61e3a9961140fd64c90bce1eafd741609d334d/httpcore-1.0.9-py3-none-any.whl", hash = "sha256:2d400746a40668fc9dec9810239072b40b4484b640a8c38fd654a024c7a1bf55", size = 78784, upload-time = "2025-04-24T22:06:20.566Z" },
+]
+
+[[package]]
+name = "httpx"
+version = "0.28.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "certifi" },
+    { name = "httpcore" },
+    { name = "idna" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b1/df/48c586a5fe32a0f01324ee087459e112ebb7224f646c0b5023f5e79e9956/httpx-0.28.1.tar.gz", hash = "sha256:75e98c5f16b0f35b567856f597f06ff2270a374470a5c2392242528e3e3e42fc", size = 141406, upload-time = "2024-12-06T15:37:23.222Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2a/39/e50c7c3a983047577ee07d2a9e53faf5a69493943ec3f6a384bdc792deb2/httpx-0.28.1-py3-none-any.whl", hash = "sha256:d909fcccc110f8c7faf814ca82a9a4d816bc5a6dbfea25d6591d6985b8ba59ad", size = 73517, upload-time = "2024-12-06T15:37:21.509Z" },
+]
+
+[[package]]
+name = "httpx-sse"
+version = "0.4.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/0f/4c/751061ffa58615a32c31b2d82e8482be8dd4a89154f003147acee90f2be9/httpx_sse-0.4.3.tar.gz", hash = "sha256:9b1ed0127459a66014aec3c56bebd93da3c1bc8bb6618c8082039a44889a755d", size = 15943, upload-time = "2025-10-10T21:48:22.271Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d2/fd/6668e5aec43ab844de6fc74927e155a3b37bf40d7c3790e49fc0406b6578/httpx_sse-0.4.3-py3-none-any.whl", hash = "sha256:0ac1c9fe3c0afad2e0ebb25a934a59f4c7823b60792691f779fad2c5568830fc", size = 8960, upload-time = "2025-10-10T21:48:21.158Z" },
+]
+
+[[package]]
+name = "idna"
+version = "3.18"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/cd/63/9496c57188a2ee585e0f1db071d75089a11e98aa86eb99d9d7618fc1edce/idna-3.18.tar.gz", hash = "sha256:ffb385a7e039654cef1ab9ef32c6fafe283c0c0467bba1d9029738ce4a14a848", size = 196711, upload-time = "2026-06-02T14:34:07.794Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1e/5e/d4e9f1a599fb8e573b7b87160658329fbf28d19eac2718f51fc3def3aa5a/idna-3.18-py3-none-any.whl", hash = "sha256:7f952cbe720b688055e3f87de14f5c3e5fdaa8bc3928985c4077ca689de849a2", size = 65455, upload-time = "2026-06-02T14:34:06.319Z" },
+]
+
+[[package]]
+name = "importlib-metadata"
+version = "8.7.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "zipp" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f3/49/3b30cad09e7771a4982d9975a8cbf64f00d4a1ececb53297f1d9a7be1b10/importlib_metadata-8.7.1.tar.gz", hash = "sha256:49fef1ae6440c182052f407c8d34a68f72efc36db9ca90dc0113398f2fdde8bb", size = 57107, upload-time = "2025-12-21T10:00:19.278Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fa/5e/f8e9a1d23b9c20a551a8a02ea3637b4642e22c2626e3a13a9a29cdea99eb/importlib_metadata-8.7.1-py3-none-any.whl", hash = "sha256:5a1f80bf1daa489495071efbb095d75a634cf28a8bc299581244063b53176151", size = 27865, upload-time = "2025-12-21T10:00:18.329Z" },
+]
+
+[[package]]
+name = "iniconfig"
+version = "2.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/34/14ca021ce8e5dfedc35312d08ba8bf51fdd999c576889fc2c24cb97f4f10/iniconfig-2.3.0.tar.gz", hash = "sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730", size = 20503, upload-time = "2025-10-18T21:55:43.219Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484, upload-time = "2025-10-18T21:55:41.639Z" },
+]
+
+[[package]]
+name = "jaraco-classes"
+version = "3.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "more-itertools" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/c0/ed4a27bc5571b99e3cff68f8a9fa5b56ff7df1c2251cc715a652ddd26402/jaraco.classes-3.4.0.tar.gz", hash = "sha256:47a024b51d0239c0dd8c8540c6c7f484be3b8fcf0b2d85c13825780d3b3f3acd", size = 11780, upload-time = "2024-03-31T07:27:36.643Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7f/66/b15ce62552d84bbfcec9a4873ab79d993a1dd4edb922cbfccae192bd5b5f/jaraco.classes-3.4.0-py3-none-any.whl", hash = "sha256:f662826b6bed8cace05e7ff873ce0f9283b5c924470fe664fff1c2f00f581790", size = 6777, upload-time = "2024-03-31T07:27:34.792Z" },
+]
+
+[[package]]
+name = "jaraco-context"
+version = "6.1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "backports-tarfile", marker = "python_full_version < '3.12'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/27/7b/c3081ff1af947915503121c649f26a778e1a2101fd525f74aef997d75b7e/jaraco_context-6.1.1.tar.gz", hash = "sha256:bc046b2dc94f1e5532bd02402684414575cc11f565d929b6563125deb0a6e581", size = 15832, upload-time = "2026-03-07T15:46:04.63Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f4/49/c152890d49102b280ecf86ba5f80a8c111c3a155dafa3bd24aeb64fde9e1/jaraco_context-6.1.1-py3-none-any.whl", hash = "sha256:0df6a0287258f3e364072c3e40d5411b20cafa30cb28c4839d24319cecf9f808", size = 7005, upload-time = "2026-03-07T15:46:03.515Z" },
+]
+
+[[package]]
+name = "jaraco-functools"
+version = "4.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "more-itertools" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0f/27/056e0638a86749374d6f57d0b0db39f29509cce9313cf91bdc0ac4d91084/jaraco_functools-4.4.0.tar.gz", hash = "sha256:da21933b0417b89515562656547a77b4931f98176eb173644c0d35032a33d6bb", size = 19943, upload-time = "2025-12-21T09:29:43.6Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fd/c4/813bb09f0985cb21e959f21f2464169eca882656849adf727ac7bb7e1767/jaraco_functools-4.4.0-py3-none-any.whl", hash = "sha256:9eec1e36f45c818d9bf307c8948eb03b2b56cd44087b3cdc989abca1f20b9176", size = 10481, upload-time = "2025-12-21T09:29:42.27Z" },
+]
+
+[[package]]
+name = "jeepney"
+version = "0.9.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7b/6f/357efd7602486741aa73ffc0617fb310a29b588ed0fd69c2399acbb85b0c/jeepney-0.9.0.tar.gz", hash = "sha256:cf0e9e845622b81e4a28df94c40345400256ec608d0e55bb8a3feaa9163f5732", size = 106758, upload-time = "2025-02-27T18:51:01.684Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b2/a3/e137168c9c44d18eff0376253da9f1e9234d0239e0ee230d2fee6cea8e55/jeepney-0.9.0-py3-none-any.whl", hash = "sha256:97e5714520c16fc0a45695e5365a2e11b81ea79bba796e26f9f1d178cb182683", size = 49010, upload-time = "2025-02-27T18:51:00.104Z" },
+]
+
+[[package]]
+name = "joserfc"
+version = "1.7.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cryptography" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/44/90/25cb27518750218e4f850be63d8bbb2343efaad1c01c3571aaa4b3c33bd7/joserfc-1.7.1.tar.gz", hash = "sha256:77d0b76514879c68c6f433bc5b7357a4ab72008ff1e33d8379fd11d72bd8ca81", size = 233181, upload-time = "2026-06-08T07:21:33.412Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b3/00/fa62404c3e347f946faa13aa21085205f9cc06ad17671e37f81a51662ae8/joserfc-1.7.1-py3-none-any.whl", hash = "sha256:b3e3d655612e2e1ef67b2600f2f420e12e537b020208fab1761fad647319c164", size = 70423, upload-time = "2026-06-08T07:21:32.001Z" },
+]
+
+[[package]]
+name = "jsonref"
+version = "1.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/aa/0d/c1f3277e90ccdb50d33ed5ba1ec5b3f0a242ed8c1b1a85d3afeb68464dca/jsonref-1.1.0.tar.gz", hash = "sha256:32fe8e1d85af0fdefbebce950af85590b22b60f9e95443176adbde4e1ecea552", size = 8814, upload-time = "2023-01-16T16:10:04.455Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0c/ec/e1db9922bceb168197a558a2b8c03a7963f1afe93517ddd3cf99f202f996/jsonref-1.1.0-py3-none-any.whl", hash = "sha256:590dc7773df6c21cbf948b5dac07a72a251db28b0238ceecce0a2abfa8ec30a9", size = 9425, upload-time = "2023-01-16T16:10:02.255Z" },
+]
+
+[[package]]
+name = "jsonschema"
+version = "4.26.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "attrs" },
+    { name = "jsonschema-specifications" },
+    { name = "referencing" },
+    { name = "rpds-py" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b3/fc/e067678238fa451312d4c62bf6e6cf5ec56375422aee02f9cb5f909b3047/jsonschema-4.26.0.tar.gz", hash = "sha256:0c26707e2efad8aa1bfc5b7ce170f3fccc2e4918ff85989ba9ffa9facb2be326", size = 366583, upload-time = "2026-01-07T13:41:07.246Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/69/90/f63fb5873511e014207a475e2bb4e8b2e570d655b00ac19a9a0ca0a385ee/jsonschema-4.26.0-py3-none-any.whl", hash = "sha256:d489f15263b8d200f8387e64b4c3a75f06629559fb73deb8fdfb525f2dab50ce", size = 90630, upload-time = "2026-01-07T13:41:05.306Z" },
+]
+
+[[package]]
+name = "jsonschema-path"
+version = "0.4.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pathable" },
+    { name = "pyyaml" },
+    { name = "referencing" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5b/8a/7e6102f2b8bdc6705a9eb5294f8f6f9ccd3a8420e8e8e19671d1dd773251/jsonschema_path-0.4.5.tar.gz", hash = "sha256:c6cd7d577ae290c7defd4f4029e86fdb248ca1bd41a07557795b3c95e5144918", size = 15113, upload-time = "2026-03-03T09:56:46.87Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/04/d5/4e96c44f6c1ea3d812cf5391d81a4f5abaa540abf8d04ecd7f66e0ed11df/jsonschema_path-0.4.5-py3-none-any.whl", hash = "sha256:7d77a2c3f3ec569a40efe5c5f942c44c1af2a6f96fe0866794c9ef5b8f87fd65", size = 19368, upload-time = "2026-03-03T09:56:45.39Z" },
+]
+
+[[package]]
+name = "jsonschema-specifications"
+version = "2025.9.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "referencing" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/19/74/a633ee74eb36c44aa6d1095e7cc5569bebf04342ee146178e2d36600708b/jsonschema_specifications-2025.9.1.tar.gz", hash = "sha256:b540987f239e745613c7a9176f3edb72b832a4ac465cf02712288397832b5e8d", size = 32855, upload-time = "2025-09-08T01:34:59.186Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/41/45/1a4ed80516f02155c51f51e8cedb3c1902296743db0bbc66608a0db2814f/jsonschema_specifications-2025.9.1-py3-none-any.whl", hash = "sha256:98802fee3a11ee76ecaca44429fda8a41bff98b00a0f2838151b113f210cc6fe", size = 18437, upload-time = "2025-09-08T01:34:57.871Z" },
+]
+
+[[package]]
+name = "keyring"
+version = "25.7.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "importlib-metadata", marker = "python_full_version < '3.12'" },
+    { name = "jaraco-classes" },
+    { name = "jaraco-context" },
+    { name = "jaraco-functools" },
+    { name = "jeepney", marker = "sys_platform == 'linux'" },
+    { name = "pywin32-ctypes", marker = "sys_platform == 'win32'" },
+    { name = "secretstorage", marker = "sys_platform == 'linux'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/43/4b/674af6ef2f97d56f0ab5153bf0bfa28ccb6c3ed4d1babf4305449668807b/keyring-25.7.0.tar.gz", hash = "sha256:fe01bd85eb3f8fb3dd0405defdeac9a5b4f6f0439edbb3149577f244a2e8245b", size = 63516, upload-time = "2025-11-16T16:26:09.482Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/81/db/e655086b7f3a705df045bf0933bdd9c2f79bb3c97bfef1384598bb79a217/keyring-25.7.0-py3-none-any.whl", hash = "sha256:be4a0b195f149690c166e850609a477c532ddbfbaed96a404d4e43f8d5e2689f", size = 39160, upload-time = "2025-11-16T16:26:08.402Z" },
+]
+
+[[package]]
+name = "markdown-it-py"
+version = "4.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "mdurl" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5b/f5/4ec618ed16cc4f8fb3b701563655a69816155e79e24a17b651541804721d/markdown_it_py-4.0.0.tar.gz", hash = "sha256:cb0a2b4aa34f932c007117b194e945bd74e0ec24133ceb5bac59009cda1cb9f3", size = 73070, upload-time = "2025-08-11T12:57:52.854Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/94/54/e7d793b573f298e1c9013b8c4dade17d481164aa517d1d7148619c2cedbf/markdown_it_py-4.0.0-py3-none-any.whl", hash = "sha256:87327c59b172c5011896038353a81343b6754500a08cd7a4973bb48c6d578147", size = 87321, upload-time = "2025-08-11T12:57:51.923Z" },
+]
+
+[[package]]
+name = "mcp"
+version = "1.26.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "httpx" },
+    { name = "httpx-sse" },
+    { name = "jsonschema" },
+    { name = "pydantic" },
+    { name = "pydantic-settings" },
+    { name = "pyjwt", extra = ["crypto"] },
+    { name = "python-multipart" },
+    { name = "pywin32", marker = "sys_platform == 'win32'" },
+    { name = "sse-starlette" },
+    { name = "starlette" },
+    { name = "typing-extensions" },
+    { name = "typing-inspection" },
+    { name = "uvicorn", marker = "sys_platform != 'emscripten'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/fc/6d/62e76bbb8144d6ed86e202b5edd8a4cb631e7c8130f3f4893c3f90262b10/mcp-1.26.0.tar.gz", hash = "sha256:db6e2ef491eecc1a0d93711a76f28dec2e05999f93afd48795da1c1137142c66", size = 608005, upload-time = "2026-01-24T19:40:32.468Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fd/d9/eaa1f80170d2b7c5ba23f3b59f766f3a0bb41155fbc32a69adfa1adaaef9/mcp-1.26.0-py3-none-any.whl", hash = "sha256:904a21c33c25aa98ddbeb47273033c435e595bbacfdb177f4bd87f6dceebe1ca", size = 233615, upload-time = "2026-01-24T19:40:30.652Z" },
+]
+
+[[package]]
+name = "mdurl"
+version = "0.1.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d6/54/cfe61301667036ec958cb99bd3efefba235e65cdeb9c84d24a8293ba1d90/mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba", size = 8729, upload-time = "2022-08-14T12:40:10.846Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" },
+]
+
+[[package]]
+name = "more-itertools"
+version = "10.8.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ea/5d/38b681d3fce7a266dd9ab73c66959406d565b3e85f21d5e66e1181d93721/more_itertools-10.8.0.tar.gz", hash = "sha256:f638ddf8a1a0d134181275fb5d58b086ead7c6a72429ad725c67503f13ba30bd", size = 137431, upload-time = "2025-09-02T15:23:11.018Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a4/8e/469e5a4a2f5855992e425f3cb33804cc07bf18d48f2db061aec61ce50270/more_itertools-10.8.0-py3-none-any.whl", hash = "sha256:52d4362373dcf7c52546bc4af9a86ee7c4579df9a8dc268be0a2f949d376cc9b", size = 69667, upload-time = "2025-09-02T15:23:09.635Z" },
+]
+
+[[package]]
+name = "openapi-pydantic"
+version = "0.5.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pydantic" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/02/2e/58d83848dd1a79cb92ed8e63f6ba901ca282c5f09d04af9423ec26c56fd7/openapi_pydantic-0.5.1.tar.gz", hash = "sha256:ff6835af6bde7a459fb93eb93bb92b8749b754fc6e51b2f1590a19dc3005ee0d", size = 60892, upload-time = "2025-01-08T19:29:27.083Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/12/cf/03675d8bd8ecbf4445504d8071adab19f5f993676795708e36402ab38263/openapi_pydantic-0.5.1-py3-none-any.whl", hash = "sha256:a3a09ef4586f5bd760a8df7f43028b60cafb6d9f61de2acba9574766255ab146", size = 96381, upload-time = "2025-01-08T19:29:25.275Z" },
+]
+
+[[package]]
+name = "opentelemetry-api"
+version = "1.40.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "importlib-metadata" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/2c/1d/4049a9e8698361cc1a1aa03a6c59e4fa4c71e0c0f94a30f988a6876a2ae6/opentelemetry_api-1.40.0.tar.gz", hash = "sha256:159be641c0b04d11e9ecd576906462773eb97ae1b657730f0ecf64d32071569f", size = 70851, upload-time = "2026-03-04T14:17:21.555Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/5f/bf/93795954016c522008da367da292adceed71cca6ee1717e1d64c83089099/opentelemetry_api-1.40.0-py3-none-any.whl", hash = "sha256:82dd69331ae74b06f6a874704be0cfaa49a1650e1537d4a813b86ecef7d0ecf9", size = 68676, upload-time = "2026-03-04T14:17:01.24Z" },
+]
+
+[[package]]
+name = "packaging"
+version = "26.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/65/ee/299d360cdc32edc7d2cf530f3accf79c4fca01e96ffc950d8a52213bd8e4/packaging-26.0.tar.gz", hash = "sha256:00243ae351a257117b6a241061796684b084ed1c516a08c48a3f7e147a9d80b4", size = 143416, upload-time = "2026-01-21T20:50:39.064Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b7/b9/c538f279a4e237a006a2c98387d081e9eb060d203d8ed34467cc0f0b9b53/packaging-26.0-py3-none-any.whl", hash = "sha256:b36f1fef9334a5588b4166f8bcd26a14e521f2b55e6b9de3aaa80d3ff7a37529", size = 74366, upload-time = "2026-01-21T20:50:37.788Z" },
+]
+
+[[package]]
+name = "pathable"
+version = "0.5.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/55/b748445cb4ea6b125626f15379be7c96d1035d4fa3e8fee362fa92298abf/pathable-0.5.0.tar.gz", hash = "sha256:d81938348a1cacb525e7c75166270644782c0fb9c8cecc16be033e71427e0ef1", size = 16655, upload-time = "2026-02-20T08:47:00.748Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/52/96/5a770e5c461462575474468e5af931cff9de036e7c2b4fea23c1c58d2cbe/pathable-0.5.0-py3-none-any.whl", hash = "sha256:646e3d09491a6351a0c82632a09c02cdf70a252e73196b36d8a15ba0a114f0a6", size = 16867, upload-time = "2026-02-20T08:46:59.536Z" },
+]
+
+[[package]]
+name = "platformdirs"
+version = "4.9.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/19/56/8d4c30c8a1d07013911a8fdbd8f89440ef9f08d07a1b50ab8ca8be5a20f9/platformdirs-4.9.4.tar.gz", hash = "sha256:1ec356301b7dc906d83f371c8f487070e99d3ccf9e501686456394622a01a934", size = 28737, upload-time = "2026-03-05T18:34:13.271Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/63/d7/97f7e3a6abb67d8080dd406fd4df842c2be0efaf712d1c899c32a075027c/platformdirs-4.9.4-py3-none-any.whl", hash = "sha256:68a9a4619a666ea6439f2ff250c12a853cd1cbd5158d258bd824a7df6be2f868", size = 21216, upload-time = "2026-03-05T18:34:12.172Z" },
+]
+
+[[package]]
+name = "pluggy"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f9/e2/3e91f31a7d2b083fe6ef3fa267035b518369d9511ffab804f839851d2779/pluggy-1.6.0.tar.gz", hash = "sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3", size = 69412, upload-time = "2025-05-15T12:30:07.975Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" },
+]
+
+[[package]]
+name = "py-key-value-aio"
+version = "0.4.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "beartype" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/04/3c/0397c072a38d4bc580994b42e0c90c5f44f679303489e4376289534735e5/py_key_value_aio-0.4.4.tar.gz", hash = "sha256:e3012e6243ed7cc09bb05457bd4d03b1ba5c2b1ca8700096b3927db79ffbbe55", size = 92300, upload-time = "2026-02-16T21:21:43.245Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/32/69/f1b537ee70b7def42d63124a539ed3026a11a3ffc3086947a1ca6e861868/py_key_value_aio-0.4.4-py3-none-any.whl", hash = "sha256:18e17564ecae61b987f909fc2cd41ee2012c84b4b1dcb8c055cf8b4bc1bf3f5d", size = 152291, upload-time = "2026-02-16T21:21:44.241Z" },
+]
+
+[package.optional-dependencies]
+filetree = [
+    { name = "aiofile" },
+    { name = "anyio" },
+]
+keyring = [
+    { name = "keyring" },
+]
+memory = [
+    { name = "cachetools" },
+]
+
+[[package]]
+name = "pycparser"
+version = "3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/1b/7d/92392ff7815c21062bea51aa7b87d45576f649f16458d78b7cf94b9ab2e6/pycparser-3.0.tar.gz", hash = "sha256:600f49d217304a5902ac3c37e1281c9fe94e4d0489de643a9504c5cdfdfc6b29", size = 103492, upload-time = "2026-01-21T14:26:51.89Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0c/c3/44f3fbbfa403ea2a7c779186dc20772604442dde72947e7d01069cbe98e3/pycparser-3.0-py3-none-any.whl", hash = "sha256:b727414169a36b7d524c1c3e31839a521725078d7b2ff038656844266160a992", size = 48172, upload-time = "2026-01-21T14:26:50.693Z" },
+]
+
+[[package]]
+name = "pydantic"
+version = "2.12.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "annotated-types" },
+    { name = "pydantic-core" },
+    { name = "typing-extensions" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/69/44/36f1a6e523abc58ae5f928898e4aca2e0ea509b5aa6f6f392a5d882be928/pydantic-2.12.5.tar.gz", hash = "sha256:4d351024c75c0f085a9febbb665ce8c0c6ec5d30e903bdb6394b7ede26aebb49", size = 821591, upload-time = "2025-11-26T15:11:46.471Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/5a/87/b70ad306ebb6f9b585f114d0ac2137d792b48be34d732d60e597c2f8465a/pydantic-2.12.5-py3-none-any.whl", hash = "sha256:e561593fccf61e8a20fc46dfc2dfe075b8be7d0188df33f221ad1f0139180f9d", size = 463580, upload-time = "2025-11-26T15:11:44.605Z" },
+]
+
+[package.optional-dependencies]
+email = [
+    { name = "email-validator" },
+]
+
+[[package]]
+name = "pydantic-core"
+version = "2.41.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/71/70/23b021c950c2addd24ec408e9ab05d59b035b39d97cdc1130e1bce647bb6/pydantic_core-2.41.5.tar.gz", hash = "sha256:08daa51ea16ad373ffd5e7606252cc32f07bc72b28284b6bc9c6df804816476e", size = 460952, upload-time = "2025-11-04T13:43:49.098Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c6/90/32c9941e728d564b411d574d8ee0cf09b12ec978cb22b294995bae5549a5/pydantic_core-2.41.5-cp310-cp310-macosx_10_12_x86_64.whl", hash = "sha256:77b63866ca88d804225eaa4af3e664c5faf3568cea95360d21f4725ab6e07146", size = 2107298, upload-time = "2025-11-04T13:39:04.116Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/a8/61c96a77fe28993d9a6fb0f4127e05430a267b235a124545d79fea46dd65/pydantic_core-2.41.5-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:dfa8a0c812ac681395907e71e1274819dec685fec28273a28905df579ef137e2", size = 1901475, upload-time = "2025-11-04T13:39:06.055Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/b6/338abf60225acc18cdc08b4faef592d0310923d19a87fba1faf05af5346e/pydantic_core-2.41.5-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5921a4d3ca3aee735d9fd163808f5e8dd6c6972101e4adbda9a4667908849b97", size = 1918815, upload-time = "2025-11-04T13:39:10.41Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/1c/2ed0433e682983d8e8cba9c8d8ef274d4791ec6a6f24c58935b90e780e0a/pydantic_core-2.41.5-cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:e25c479382d26a2a41b7ebea1043564a937db462816ea07afa8a44c0866d52f9", size = 2065567, upload-time = "2025-11-04T13:39:12.244Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/24/cf84974ee7d6eae06b9e63289b7b8f6549d416b5c199ca2d7ce13bbcf619/pydantic_core-2.41.5-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:f547144f2966e1e16ae626d8ce72b4cfa0caedc7fa28052001c94fb2fcaa1c52", size = 2230442, upload-time = "2025-11-04T13:39:13.962Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/21/4e287865504b3edc0136c89c9c09431be326168b1eb7841911cbc877a995/pydantic_core-2.41.5-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:6f52298fbd394f9ed112d56f3d11aabd0d5bd27beb3084cc3d8ad069483b8941", size = 2350956, upload-time = "2025-11-04T13:39:15.889Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/76/7727ef2ffa4b62fcab916686a68a0426b9b790139720e1934e8ba797e238/pydantic_core-2.41.5-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:100baa204bb412b74fe285fb0f3a385256dad1d1879f0a5cb1499ed2e83d132a", size = 2068253, upload-time = "2025-11-04T13:39:17.403Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/8c/a4abfc79604bcb4c748e18975c44f94f756f08fb04218d5cb87eb0d3a63e/pydantic_core-2.41.5-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:05a2c8852530ad2812cb7914dc61a1125dc4e06252ee98e5638a12da6cc6fb6c", size = 2177050, upload-time = "2025-11-04T13:39:19.351Z" },
+    { url = "https://files.pythonhosted.org/packages/67/b1/de2e9a9a79b480f9cb0b6e8b6ba4c50b18d4e89852426364c66aa82bb7b3/pydantic_core-2.41.5-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:29452c56df2ed968d18d7e21f4ab0ac55e71dc59524872f6fc57dcf4a3249ed2", size = 2147178, upload-time = "2025-11-04T13:39:21Z" },
+    { url = "https://files.pythonhosted.org/packages/16/c1/dfb33f837a47b20417500efaa0378adc6635b3c79e8369ff7a03c494b4ac/pydantic_core-2.41.5-cp310-cp310-musllinux_1_1_armv7l.whl", hash = "sha256:d5160812ea7a8a2ffbe233d8da666880cad0cbaf5d4de74ae15c313213d62556", size = 2341833, upload-time = "2025-11-04T13:39:22.606Z" },
+    { url = "https://files.pythonhosted.org/packages/47/36/00f398642a0f4b815a9a558c4f1dca1b4020a7d49562807d7bc9ff279a6c/pydantic_core-2.41.5-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:df3959765b553b9440adfd3c795617c352154e497a4eaf3752555cfb5da8fc49", size = 2321156, upload-time = "2025-11-04T13:39:25.843Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/70/cad3acd89fde2010807354d978725ae111ddf6d0ea46d1ea1775b5c1bd0c/pydantic_core-2.41.5-cp310-cp310-win32.whl", hash = "sha256:1f8d33a7f4d5a7889e60dc39856d76d09333d8a6ed0f5f1190635cbec70ec4ba", size = 1989378, upload-time = "2025-11-04T13:39:27.92Z" },
+    { url = "https://files.pythonhosted.org/packages/76/92/d338652464c6c367e5608e4488201702cd1cbb0f33f7b6a85a60fe5f3720/pydantic_core-2.41.5-cp310-cp310-win_amd64.whl", hash = "sha256:62de39db01b8d593e45871af2af9e497295db8d73b085f6bfd0b18c83c70a8f9", size = 2013622, upload-time = "2025-11-04T13:39:29.848Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/72/74a989dd9f2084b3d9530b0915fdda64ac48831c30dbf7c72a41a5232db8/pydantic_core-2.41.5-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:a3a52f6156e73e7ccb0f8cced536adccb7042be67cb45f9562e12b319c119da6", size = 2105873, upload-time = "2025-11-04T13:39:31.373Z" },
+    { url = "https://files.pythonhosted.org/packages/12/44/37e403fd9455708b3b942949e1d7febc02167662bf1a7da5b78ee1ea2842/pydantic_core-2.41.5-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:7f3bf998340c6d4b0c9a2f02d6a400e51f123b59565d74dc60d252ce888c260b", size = 1899826, upload-time = "2025-11-04T13:39:32.897Z" },
+    { url = "https://files.pythonhosted.org/packages/33/7f/1d5cab3ccf44c1935a359d51a8a2a9e1a654b744b5e7f80d41b88d501eec/pydantic_core-2.41.5-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:378bec5c66998815d224c9ca994f1e14c0c21cb95d2f52b6021cc0b2a58f2a5a", size = 1917869, upload-time = "2025-11-04T13:39:34.469Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/6a/30d94a9674a7fe4f4744052ed6c5e083424510be1e93da5bc47569d11810/pydantic_core-2.41.5-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:e7b576130c69225432866fe2f4a469a85a54ade141d96fd396dffcf607b558f8", size = 2063890, upload-time = "2025-11-04T13:39:36.053Z" },
+    { url = "https://files.pythonhosted.org/packages/50/be/76e5d46203fcb2750e542f32e6c371ffa9b8ad17364cf94bb0818dbfb50c/pydantic_core-2.41.5-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:6cb58b9c66f7e4179a2d5e0f849c48eff5c1fca560994d6eb6543abf955a149e", size = 2229740, upload-time = "2025-11-04T13:39:37.753Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/ee/fed784df0144793489f87db310a6bbf8118d7b630ed07aa180d6067e653a/pydantic_core-2.41.5-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:88942d3a3dff3afc8288c21e565e476fc278902ae4d6d134f1eeda118cc830b1", size = 2350021, upload-time = "2025-11-04T13:39:40.94Z" },
+    { url = "https://files.pythonhosted.org/packages/c8/be/8fed28dd0a180dca19e72c233cbf58efa36df055e5b9d90d64fd1740b828/pydantic_core-2.41.5-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:f31d95a179f8d64d90f6831d71fa93290893a33148d890ba15de25642c5d075b", size = 2066378, upload-time = "2025-11-04T13:39:42.523Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/3b/698cf8ae1d536a010e05121b4958b1257f0b5522085e335360e53a6b1c8b/pydantic_core-2.41.5-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:c1df3d34aced70add6f867a8cf413e299177e0c22660cc767218373d0779487b", size = 2175761, upload-time = "2025-11-04T13:39:44.553Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/ba/15d537423939553116dea94ce02f9c31be0fa9d0b806d427e0308ec17145/pydantic_core-2.41.5-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:4009935984bd36bd2c774e13f9a09563ce8de4abaa7226f5108262fa3e637284", size = 2146303, upload-time = "2025-11-04T13:39:46.238Z" },
+    { url = "https://files.pythonhosted.org/packages/58/7f/0de669bf37d206723795f9c90c82966726a2ab06c336deba4735b55af431/pydantic_core-2.41.5-cp311-cp311-musllinux_1_1_armv7l.whl", hash = "sha256:34a64bc3441dc1213096a20fe27e8e128bd3ff89921706e83c0b1ac971276594", size = 2340355, upload-time = "2025-11-04T13:39:48.002Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/de/e7482c435b83d7e3c3ee5ee4451f6e8973cff0eb6007d2872ce6383f6398/pydantic_core-2.41.5-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:c9e19dd6e28fdcaa5a1de679aec4141f691023916427ef9bae8584f9c2fb3b0e", size = 2319875, upload-time = "2025-11-04T13:39:49.705Z" },
+    { url = "https://files.pythonhosted.org/packages/fe/e6/8c9e81bb6dd7560e33b9053351c29f30c8194b72f2d6932888581f503482/pydantic_core-2.41.5-cp311-cp311-win32.whl", hash = "sha256:2c010c6ded393148374c0f6f0bf89d206bf3217f201faa0635dcd56bd1520f6b", size = 1987549, upload-time = "2025-11-04T13:39:51.842Z" },
+    { url = "https://files.pythonhosted.org/packages/11/66/f14d1d978ea94d1bc21fc98fcf570f9542fe55bfcc40269d4e1a21c19bf7/pydantic_core-2.41.5-cp311-cp311-win_amd64.whl", hash = "sha256:76ee27c6e9c7f16f47db7a94157112a2f3a00e958bc626e2f4ee8bec5c328fbe", size = 2011305, upload-time = "2025-11-04T13:39:53.485Z" },
+    { url = "https://files.pythonhosted.org/packages/56/d8/0e271434e8efd03186c5386671328154ee349ff0354d83c74f5caaf096ed/pydantic_core-2.41.5-cp311-cp311-win_arm64.whl", hash = "sha256:4bc36bbc0b7584de96561184ad7f012478987882ebf9f9c389b23f432ea3d90f", size = 1972902, upload-time = "2025-11-04T13:39:56.488Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/5d/5f6c63eebb5afee93bcaae4ce9a898f3373ca23df3ccaef086d0233a35a7/pydantic_core-2.41.5-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:f41a7489d32336dbf2199c8c0a215390a751c5b014c2c1c5366e817202e9cdf7", size = 2110990, upload-time = "2025-11-04T13:39:58.079Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/32/9c2e8ccb57c01111e0fd091f236c7b371c1bccea0fa85247ac55b1e2b6b6/pydantic_core-2.41.5-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:070259a8818988b9a84a449a2a7337c7f430a22acc0859c6b110aa7212a6d9c0", size = 1896003, upload-time = "2025-11-04T13:39:59.956Z" },
+    { url = "https://files.pythonhosted.org/packages/68/b8/a01b53cb0e59139fbc9e4fda3e9724ede8de279097179be4ff31f1abb65a/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e96cea19e34778f8d59fe40775a7a574d95816eb150850a85a7a4c8f4b94ac69", size = 1919200, upload-time = "2025-11-04T13:40:02.241Z" },
+    { url = "https://files.pythonhosted.org/packages/38/de/8c36b5198a29bdaade07b5985e80a233a5ac27137846f3bc2d3b40a47360/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:ed2e99c456e3fadd05c991f8f437ef902e00eedf34320ba2b0842bd1c3ca3a75", size = 2052578, upload-time = "2025-11-04T13:40:04.401Z" },
+    { url = "https://files.pythonhosted.org/packages/00/b5/0e8e4b5b081eac6cb3dbb7e60a65907549a1ce035a724368c330112adfdd/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:65840751b72fbfd82c3c640cff9284545342a4f1eb1586ad0636955b261b0b05", size = 2208504, upload-time = "2025-11-04T13:40:06.072Z" },
+    { url = "https://files.pythonhosted.org/packages/77/56/87a61aad59c7c5b9dc8caad5a41a5545cba3810c3e828708b3d7404f6cef/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:e536c98a7626a98feb2d3eaf75944ef6f3dbee447e1f841eae16f2f0a72d8ddc", size = 2335816, upload-time = "2025-11-04T13:40:07.835Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/76/941cc9f73529988688a665a5c0ecff1112b3d95ab48f81db5f7606f522d3/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:eceb81a8d74f9267ef4081e246ffd6d129da5d87e37a77c9bde550cb04870c1c", size = 2075366, upload-time = "2025-11-04T13:40:09.804Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/43/ebef01f69baa07a482844faaa0a591bad1ef129253ffd0cdaa9d8a7f72d3/pydantic_core-2.41.5-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:d38548150c39b74aeeb0ce8ee1d8e82696f4a4e16ddc6de7b1d8823f7de4b9b5", size = 2171698, upload-time = "2025-11-04T13:40:12.004Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/87/41f3202e4193e3bacfc2c065fab7706ebe81af46a83d3e27605029c1f5a6/pydantic_core-2.41.5-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:c23e27686783f60290e36827f9c626e63154b82b116d7fe9adba1fda36da706c", size = 2132603, upload-time = "2025-11-04T13:40:13.868Z" },
+    { url = "https://files.pythonhosted.org/packages/49/7d/4c00df99cb12070b6bccdef4a195255e6020a550d572768d92cc54dba91a/pydantic_core-2.41.5-cp312-cp312-musllinux_1_1_armv7l.whl", hash = "sha256:482c982f814460eabe1d3bb0adfdc583387bd4691ef00b90575ca0d2b6fe2294", size = 2329591, upload-time = "2025-11-04T13:40:15.672Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/6a/ebf4b1d65d458f3cda6a7335d141305dfa19bdc61140a884d165a8a1bbc7/pydantic_core-2.41.5-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:bfea2a5f0b4d8d43adf9d7b8bf019fb46fdd10a2e5cde477fbcb9d1fa08c68e1", size = 2319068, upload-time = "2025-11-04T13:40:17.532Z" },
+    { url = "https://files.pythonhosted.org/packages/49/3b/774f2b5cd4192d5ab75870ce4381fd89cf218af999515baf07e7206753f0/pydantic_core-2.41.5-cp312-cp312-win32.whl", hash = "sha256:b74557b16e390ec12dca509bce9264c3bbd128f8a2c376eaa68003d7f327276d", size = 1985908, upload-time = "2025-11-04T13:40:19.309Z" },
+    { url = "https://files.pythonhosted.org/packages/86/45/00173a033c801cacf67c190fef088789394feaf88a98a7035b0e40d53dc9/pydantic_core-2.41.5-cp312-cp312-win_amd64.whl", hash = "sha256:1962293292865bca8e54702b08a4f26da73adc83dd1fcf26fbc875b35d81c815", size = 2020145, upload-time = "2025-11-04T13:40:21.548Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/22/91fbc821fa6d261b376a3f73809f907cec5ca6025642c463d3488aad22fb/pydantic_core-2.41.5-cp312-cp312-win_arm64.whl", hash = "sha256:1746d4a3d9a794cacae06a5eaaccb4b8643a131d45fbc9af23e353dc0a5ba5c3", size = 1976179, upload-time = "2025-11-04T13:40:23.393Z" },
+    { url = "https://files.pythonhosted.org/packages/87/06/8806241ff1f70d9939f9af039c6c35f2360cf16e93c2ca76f184e76b1564/pydantic_core-2.41.5-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:941103c9be18ac8daf7b7adca8228f8ed6bb7a1849020f643b3a14d15b1924d9", size = 2120403, upload-time = "2025-11-04T13:40:25.248Z" },
+    { url = "https://files.pythonhosted.org/packages/94/02/abfa0e0bda67faa65fef1c84971c7e45928e108fe24333c81f3bfe35d5f5/pydantic_core-2.41.5-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:112e305c3314f40c93998e567879e887a3160bb8689ef3d2c04b6cc62c33ac34", size = 1896206, upload-time = "2025-11-04T13:40:27.099Z" },
+    { url = "https://files.pythonhosted.org/packages/15/df/a4c740c0943e93e6500f9eb23f4ca7ec9bf71b19e608ae5b579678c8d02f/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0cbaad15cb0c90aa221d43c00e77bb33c93e8d36e0bf74760cd00e732d10a6a0", size = 1919307, upload-time = "2025-11-04T13:40:29.806Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/e3/6324802931ae1d123528988e0e86587c2072ac2e5394b4bc2bc34b61ff6e/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:03ca43e12fab6023fc79d28ca6b39b05f794ad08ec2feccc59a339b02f2b3d33", size = 2063258, upload-time = "2025-11-04T13:40:33.544Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/d4/2230d7151d4957dd79c3044ea26346c148c98fbf0ee6ebd41056f2d62ab5/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:dc799088c08fa04e43144b164feb0c13f9a0bc40503f8df3e9fde58a3c0c101e", size = 2214917, upload-time = "2025-11-04T13:40:35.479Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/9f/eaac5df17a3672fef0081b6c1bb0b82b33ee89aa5cec0d7b05f52fd4a1fa/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:97aeba56665b4c3235a0e52b2c2f5ae9cd071b8a8310ad27bddb3f7fb30e9aa2", size = 2332186, upload-time = "2025-11-04T13:40:37.436Z" },
+    { url = "https://files.pythonhosted.org/packages/cf/4e/35a80cae583a37cf15604b44240e45c05e04e86f9cfd766623149297e971/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:406bf18d345822d6c21366031003612b9c77b3e29ffdb0f612367352aab7d586", size = 2073164, upload-time = "2025-11-04T13:40:40.289Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/e3/f6e262673c6140dd3305d144d032f7bd5f7497d3871c1428521f19f9efa2/pydantic_core-2.41.5-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:b93590ae81f7010dbe380cdeab6f515902ebcbefe0b9327cc4804d74e93ae69d", size = 2179146, upload-time = "2025-11-04T13:40:42.809Z" },
+    { url = "https://files.pythonhosted.org/packages/75/c7/20bd7fc05f0c6ea2056a4565c6f36f8968c0924f19b7d97bbfea55780e73/pydantic_core-2.41.5-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:01a3d0ab748ee531f4ea6c3e48ad9dac84ddba4b0d82291f87248f2f9de8d740", size = 2137788, upload-time = "2025-11-04T13:40:44.752Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/8d/34318ef985c45196e004bc46c6eab2eda437e744c124ef0dbe1ff2c9d06b/pydantic_core-2.41.5-cp313-cp313-musllinux_1_1_armv7l.whl", hash = "sha256:6561e94ba9dacc9c61bce40e2d6bdc3bfaa0259d3ff36ace3b1e6901936d2e3e", size = 2340133, upload-time = "2025-11-04T13:40:46.66Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/59/013626bf8c78a5a5d9350d12e7697d3d4de951a75565496abd40ccd46bee/pydantic_core-2.41.5-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:915c3d10f81bec3a74fbd4faebe8391013ba61e5a1a8d48c4455b923bdda7858", size = 2324852, upload-time = "2025-11-04T13:40:48.575Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/d9/c248c103856f807ef70c18a4f986693a46a8ffe1602e5d361485da502d20/pydantic_core-2.41.5-cp313-cp313-win32.whl", hash = "sha256:650ae77860b45cfa6e2cdafc42618ceafab3a2d9a3811fcfbd3bbf8ac3c40d36", size = 1994679, upload-time = "2025-11-04T13:40:50.619Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/8b/341991b158ddab181cff136acd2552c9f35bd30380422a639c0671e99a91/pydantic_core-2.41.5-cp313-cp313-win_amd64.whl", hash = "sha256:79ec52ec461e99e13791ec6508c722742ad745571f234ea6255bed38c6480f11", size = 2019766, upload-time = "2025-11-04T13:40:52.631Z" },
+    { url = "https://files.pythonhosted.org/packages/73/7d/f2f9db34af103bea3e09735bb40b021788a5e834c81eedb541991badf8f5/pydantic_core-2.41.5-cp313-cp313-win_arm64.whl", hash = "sha256:3f84d5c1b4ab906093bdc1ff10484838aca54ef08de4afa9de0f5f14d69639cd", size = 1981005, upload-time = "2025-11-04T13:40:54.734Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/28/46b7c5c9635ae96ea0fbb779e271a38129df2550f763937659ee6c5dbc65/pydantic_core-2.41.5-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:3f37a19d7ebcdd20b96485056ba9e8b304e27d9904d233d7b1015db320e51f0a", size = 2119622, upload-time = "2025-11-04T13:40:56.68Z" },
+    { url = "https://files.pythonhosted.org/packages/74/1a/145646e5687e8d9a1e8d09acb278c8535ebe9e972e1f162ed338a622f193/pydantic_core-2.41.5-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:1d1d9764366c73f996edd17abb6d9d7649a7eb690006ab6adbda117717099b14", size = 1891725, upload-time = "2025-11-04T13:40:58.807Z" },
+    { url = "https://files.pythonhosted.org/packages/23/04/e89c29e267b8060b40dca97bfc64a19b2a3cf99018167ea1677d96368273/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:25e1c2af0fce638d5f1988b686f3b3ea8cd7de5f244ca147c777769e798a9cd1", size = 1915040, upload-time = "2025-11-04T13:41:00.853Z" },
+    { url = "https://files.pythonhosted.org/packages/84/a3/15a82ac7bd97992a82257f777b3583d3e84bdb06ba6858f745daa2ec8a85/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:506d766a8727beef16b7adaeb8ee6217c64fc813646b424d0804d67c16eddb66", size = 2063691, upload-time = "2025-11-04T13:41:03.504Z" },
+    { url = "https://files.pythonhosted.org/packages/74/9b/0046701313c6ef08c0c1cf0e028c67c770a4e1275ca73131563c5f2a310a/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:4819fa52133c9aa3c387b3328f25c1facc356491e6135b459f1de698ff64d869", size = 2213897, upload-time = "2025-11-04T13:41:05.804Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/cd/6bac76ecd1b27e75a95ca3a9a559c643b3afcd2dd62086d4b7a32a18b169/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:2b761d210c9ea91feda40d25b4efe82a1707da2ef62901466a42492c028553a2", size = 2333302, upload-time = "2025-11-04T13:41:07.809Z" },
+    { url = "https://files.pythonhosted.org/packages/4c/d2/ef2074dc020dd6e109611a8be4449b98cd25e1b9b8a303c2f0fca2f2bcf7/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:22f0fb8c1c583a3b6f24df2470833b40207e907b90c928cc8d3594b76f874375", size = 2064877, upload-time = "2025-11-04T13:41:09.827Z" },
+    { url = "https://files.pythonhosted.org/packages/18/66/e9db17a9a763d72f03de903883c057b2592c09509ccfe468187f2a2eef29/pydantic_core-2.41.5-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:2782c870e99878c634505236d81e5443092fba820f0373997ff75f90f68cd553", size = 2180680, upload-time = "2025-11-04T13:41:12.379Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/9e/3ce66cebb929f3ced22be85d4c2399b8e85b622db77dad36b73c5387f8f8/pydantic_core-2.41.5-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:0177272f88ab8312479336e1d777f6b124537d47f2123f89cb37e0accea97f90", size = 2138960, upload-time = "2025-11-04T13:41:14.627Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/62/205a998f4327d2079326b01abee48e502ea739d174f0a89295c481a2272e/pydantic_core-2.41.5-cp314-cp314-musllinux_1_1_armv7l.whl", hash = "sha256:63510af5e38f8955b8ee5687740d6ebf7c2a0886d15a6d65c32814613681bc07", size = 2339102, upload-time = "2025-11-04T13:41:16.868Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/0d/f05e79471e889d74d3d88f5bd20d0ed189ad94c2423d81ff8d0000aab4ff/pydantic_core-2.41.5-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:e56ba91f47764cc14f1daacd723e3e82d1a89d783f0f5afe9c364b8bb491ccdb", size = 2326039, upload-time = "2025-11-04T13:41:18.934Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/e1/e08a6208bb100da7e0c4b288eed624a703f4d129bde2da475721a80cab32/pydantic_core-2.41.5-cp314-cp314-win32.whl", hash = "sha256:aec5cf2fd867b4ff45b9959f8b20ea3993fc93e63c7363fe6851424c8a7e7c23", size = 1995126, upload-time = "2025-11-04T13:41:21.418Z" },
+    { url = "https://files.pythonhosted.org/packages/48/5d/56ba7b24e9557f99c9237e29f5c09913c81eeb2f3217e40e922353668092/pydantic_core-2.41.5-cp314-cp314-win_amd64.whl", hash = "sha256:8e7c86f27c585ef37c35e56a96363ab8de4e549a95512445b85c96d3e2f7c1bf", size = 2015489, upload-time = "2025-11-04T13:41:24.076Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/bb/f7a190991ec9e3e0ba22e4993d8755bbc4a32925c0b5b42775c03e8148f9/pydantic_core-2.41.5-cp314-cp314-win_arm64.whl", hash = "sha256:e672ba74fbc2dc8eea59fb6d4aed6845e6905fc2a8afe93175d94a83ba2a01a0", size = 1977288, upload-time = "2025-11-04T13:41:26.33Z" },
+    { url = "https://files.pythonhosted.org/packages/92/ed/77542d0c51538e32e15afe7899d79efce4b81eee631d99850edc2f5e9349/pydantic_core-2.41.5-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:8566def80554c3faa0e65ac30ab0932b9e3a5cd7f8323764303d468e5c37595a", size = 2120255, upload-time = "2025-11-04T13:41:28.569Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/3d/6913dde84d5be21e284439676168b28d8bbba5600d838b9dca99de0fad71/pydantic_core-2.41.5-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:b80aa5095cd3109962a298ce14110ae16b8c1aece8b72f9dafe81cf597ad80b3", size = 1863760, upload-time = "2025-11-04T13:41:31.055Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/f0/e5e6b99d4191da102f2b0eb9687aaa7f5bea5d9964071a84effc3e40f997/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3006c3dd9ba34b0c094c544c6006cc79e87d8612999f1a5d43b769b89181f23c", size = 1878092, upload-time = "2025-11-04T13:41:33.21Z" },
+    { url = "https://files.pythonhosted.org/packages/71/48/36fb760642d568925953bcc8116455513d6e34c4beaa37544118c36aba6d/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:72f6c8b11857a856bcfa48c86f5368439f74453563f951e473514579d44aa612", size = 2053385, upload-time = "2025-11-04T13:41:35.508Z" },
+    { url = "https://files.pythonhosted.org/packages/20/25/92dc684dd8eb75a234bc1c764b4210cf2646479d54b47bf46061657292a8/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5cb1b2f9742240e4bb26b652a5aeb840aa4b417c7748b6f8387927bc6e45e40d", size = 2218832, upload-time = "2025-11-04T13:41:37.732Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/09/f53e0b05023d3e30357d82eb35835d0f6340ca344720a4599cd663dca599/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:bd3d54f38609ff308209bd43acea66061494157703364ae40c951f83ba99a1a9", size = 2327585, upload-time = "2025-11-04T13:41:40Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/4e/2ae1aa85d6af35a39b236b1b1641de73f5a6ac4d5a7509f77b814885760c/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:2ff4321e56e879ee8d2a879501c8e469414d948f4aba74a2d4593184eb326660", size = 2041078, upload-time = "2025-11-04T13:41:42.323Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/13/2e215f17f0ef326fc72afe94776edb77525142c693767fc347ed6288728d/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:d0d2568a8c11bf8225044aa94409e21da0cb09dcdafe9ecd10250b2baad531a9", size = 2173914, upload-time = "2025-11-04T13:41:45.221Z" },
+    { url = "https://files.pythonhosted.org/packages/02/7a/f999a6dcbcd0e5660bc348a3991c8915ce6599f4f2c6ac22f01d7a10816c/pydantic_core-2.41.5-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:a39455728aabd58ceabb03c90e12f71fd30fa69615760a075b9fec596456ccc3", size = 2129560, upload-time = "2025-11-04T13:41:47.474Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/b1/6c990ac65e3b4c079a4fb9f5b05f5b013afa0f4ed6780a3dd236d2cbdc64/pydantic_core-2.41.5-cp314-cp314t-musllinux_1_1_armv7l.whl", hash = "sha256:239edca560d05757817c13dc17c50766136d21f7cd0fac50295499ae24f90fdf", size = 2329244, upload-time = "2025-11-04T13:41:49.992Z" },
+    { url = "https://files.pythonhosted.org/packages/d9/02/3c562f3a51afd4d88fff8dffb1771b30cfdfd79befd9883ee094f5b6c0d8/pydantic_core-2.41.5-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:2a5e06546e19f24c6a96a129142a75cee553cc018ffee48a460059b1185f4470", size = 2331955, upload-time = "2025-11-04T13:41:54.079Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/96/5fb7d8c3c17bc8c62fdb031c47d77a1af698f1d7a406b0f79aaa1338f9ad/pydantic_core-2.41.5-cp314-cp314t-win32.whl", hash = "sha256:b4ececa40ac28afa90871c2cc2b9ffd2ff0bf749380fbdf57d165fd23da353aa", size = 1988906, upload-time = "2025-11-04T13:41:56.606Z" },
+    { url = "https://files.pythonhosted.org/packages/22/ed/182129d83032702912c2e2d8bbe33c036f342cc735737064668585dac28f/pydantic_core-2.41.5-cp314-cp314t-win_amd64.whl", hash = "sha256:80aa89cad80b32a912a65332f64a4450ed00966111b6615ca6816153d3585a8c", size = 1981607, upload-time = "2025-11-04T13:41:58.889Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/ed/068e41660b832bb0b1aa5b58011dea2a3fe0ba7861ff38c4d4904c1c1a99/pydantic_core-2.41.5-cp314-cp314t-win_arm64.whl", hash = "sha256:35b44f37a3199f771c3eaa53051bc8a70cd7b54f333531c59e29fd4db5d15008", size = 1974769, upload-time = "2025-11-04T13:42:01.186Z" },
+    { url = "https://files.pythonhosted.org/packages/11/72/90fda5ee3b97e51c494938a4a44c3a35a9c96c19bba12372fb9c634d6f57/pydantic_core-2.41.5-graalpy311-graalpy242_311_native-macosx_10_12_x86_64.whl", hash = "sha256:b96d5f26b05d03cc60f11a7761a5ded1741da411e7fe0909e27a5e6a0cb7b034", size = 2115441, upload-time = "2025-11-04T13:42:39.557Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/53/8942f884fa33f50794f119012dc6a1a02ac43a56407adaac20463df8e98f/pydantic_core-2.41.5-graalpy311-graalpy242_311_native-macosx_11_0_arm64.whl", hash = "sha256:634e8609e89ceecea15e2d61bc9ac3718caaaa71963717bf3c8f38bfde64242c", size = 1930291, upload-time = "2025-11-04T13:42:42.169Z" },
+    { url = "https://files.pythonhosted.org/packages/79/c8/ecb9ed9cd942bce09fc888ee960b52654fbdbede4ba6c2d6e0d3b1d8b49c/pydantic_core-2.41.5-graalpy311-graalpy242_311_native-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:93e8740d7503eb008aa2df04d3b9735f845d43ae845e6dcd2be0b55a2da43cd2", size = 1948632, upload-time = "2025-11-04T13:42:44.564Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/1b/687711069de7efa6af934e74f601e2a4307365e8fdc404703afc453eab26/pydantic_core-2.41.5-graalpy311-graalpy242_311_native-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:f15489ba13d61f670dcc96772e733aad1a6f9c429cc27574c6cdaed82d0146ad", size = 2138905, upload-time = "2025-11-04T13:42:47.156Z" },
+    { url = "https://files.pythonhosted.org/packages/09/32/59b0c7e63e277fa7911c2fc70ccfb45ce4b98991e7ef37110663437005af/pydantic_core-2.41.5-graalpy312-graalpy250_312_native-macosx_10_12_x86_64.whl", hash = "sha256:7da7087d756b19037bc2c06edc6c170eeef3c3bafcb8f532ff17d64dc427adfd", size = 2110495, upload-time = "2025-11-04T13:42:49.689Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/81/05e400037eaf55ad400bcd318c05bb345b57e708887f07ddb2d20e3f0e98/pydantic_core-2.41.5-graalpy312-graalpy250_312_native-macosx_11_0_arm64.whl", hash = "sha256:aabf5777b5c8ca26f7824cb4a120a740c9588ed58df9b2d196ce92fba42ff8dc", size = 1915388, upload-time = "2025-11-04T13:42:52.215Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/0d/e3549b2399f71d56476b77dbf3cf8937cec5cd70536bdc0e374a421d0599/pydantic_core-2.41.5-graalpy312-graalpy250_312_native-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:c007fe8a43d43b3969e8469004e9845944f1a80e6acd47c150856bb87f230c56", size = 1942879, upload-time = "2025-11-04T13:42:56.483Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/07/34573da085946b6a313d7c42f82f16e8920bfd730665de2d11c0c37a74b5/pydantic_core-2.41.5-graalpy312-graalpy250_312_native-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:76d0819de158cd855d1cbb8fcafdf6f5cf1eb8e470abe056d5d161106e38062b", size = 2139017, upload-time = "2025-11-04T13:42:59.471Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/b0/1a2aa41e3b5a4ba11420aba2d091b2d17959c8d1519ece3627c371951e73/pydantic_core-2.41.5-pp310-pypy310_pp73-macosx_10_12_x86_64.whl", hash = "sha256:b5819cd790dbf0c5eb9f82c73c16b39a65dd6dd4d1439dcdea7816ec9adddab8", size = 2103351, upload-time = "2025-11-04T13:43:02.058Z" },
+    { url = "https://files.pythonhosted.org/packages/a4/ee/31b1f0020baaf6d091c87900ae05c6aeae101fa4e188e1613c80e4f1ea31/pydantic_core-2.41.5-pp310-pypy310_pp73-macosx_11_0_arm64.whl", hash = "sha256:5a4e67afbc95fa5c34cf27d9089bca7fcab4e51e57278d710320a70b956d1b9a", size = 1925363, upload-time = "2025-11-04T13:43:05.159Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/89/ab8e86208467e467a80deaca4e434adac37b10a9d134cd2f99b28a01e483/pydantic_core-2.41.5-pp310-pypy310_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ece5c59f0ce7d001e017643d8d24da587ea1f74f6993467d85ae8a5ef9d4f42b", size = 2135615, upload-time = "2025-11-04T13:43:08.116Z" },
+    { url = "https://files.pythonhosted.org/packages/99/0a/99a53d06dd0348b2008f2f30884b34719c323f16c3be4e6cc1203b74a91d/pydantic_core-2.41.5-pp310-pypy310_pp73-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:16f80f7abe3351f8ea6858914ddc8c77e02578544a0ebc15b4c2e1a0e813b0b2", size = 2175369, upload-time = "2025-11-04T13:43:12.49Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/94/30ca3b73c6d485b9bb0bc66e611cff4a7138ff9736b7e66bcf0852151636/pydantic_core-2.41.5-pp310-pypy310_pp73-musllinux_1_1_aarch64.whl", hash = "sha256:33cb885e759a705b426baada1fe68cbb0a2e68e34c5d0d0289a364cf01709093", size = 2144218, upload-time = "2025-11-04T13:43:15.431Z" },
+    { url = "https://files.pythonhosted.org/packages/87/57/31b4f8e12680b739a91f472b5671294236b82586889ef764b5fbc6669238/pydantic_core-2.41.5-pp310-pypy310_pp73-musllinux_1_1_armv7l.whl", hash = "sha256:c8d8b4eb992936023be7dee581270af5c6e0697a8559895f527f5b7105ecd36a", size = 2329951, upload-time = "2025-11-04T13:43:18.062Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/73/3c2c8edef77b8f7310e6fb012dbc4b8551386ed575b9eb6fb2506e28a7eb/pydantic_core-2.41.5-pp310-pypy310_pp73-musllinux_1_1_x86_64.whl", hash = "sha256:242a206cd0318f95cd21bdacff3fcc3aab23e79bba5cac3db5a841c9ef9c6963", size = 2318428, upload-time = "2025-11-04T13:43:20.679Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/02/8559b1f26ee0d502c74f9cca5c0d2fd97e967e083e006bbbb4e97f3a043a/pydantic_core-2.41.5-pp310-pypy310_pp73-win_amd64.whl", hash = "sha256:d3a978c4f57a597908b7e697229d996d77a6d3c94901e9edee593adada95ce1a", size = 2147009, upload-time = "2025-11-04T13:43:23.286Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/9b/1b3f0e9f9305839d7e84912f9e8bfbd191ed1b1ef48083609f0dabde978c/pydantic_core-2.41.5-pp311-pypy311_pp73-macosx_10_12_x86_64.whl", hash = "sha256:b2379fa7ed44ddecb5bfe4e48577d752db9fc10be00a6b7446e9663ba143de26", size = 2101980, upload-time = "2025-11-04T13:43:25.97Z" },
+    { url = "https://files.pythonhosted.org/packages/a4/ed/d71fefcb4263df0da6a85b5d8a7508360f2f2e9b3bf5814be9c8bccdccc1/pydantic_core-2.41.5-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:266fb4cbf5e3cbd0b53669a6d1b039c45e3ce651fd5442eff4d07c2cc8d66808", size = 1923865, upload-time = "2025-11-04T13:43:28.763Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/3a/626b38db460d675f873e4444b4bb030453bbe7b4ba55df821d026a0493c4/pydantic_core-2.41.5-pp311-pypy311_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:58133647260ea01e4d0500089a8c4f07bd7aa6ce109682b1426394988d8aaacc", size = 2134256, upload-time = "2025-11-04T13:43:31.71Z" },
+    { url = "https://files.pythonhosted.org/packages/83/d9/8412d7f06f616bbc053d30cb4e5f76786af3221462ad5eee1f202021eb4e/pydantic_core-2.41.5-pp311-pypy311_pp73-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:287dad91cfb551c363dc62899a80e9e14da1f0e2b6ebde82c806612ca2a13ef1", size = 2174762, upload-time = "2025-11-04T13:43:34.744Z" },
+    { url = "https://files.pythonhosted.org/packages/55/4c/162d906b8e3ba3a99354e20faa1b49a85206c47de97a639510a0e673f5da/pydantic_core-2.41.5-pp311-pypy311_pp73-musllinux_1_1_aarch64.whl", hash = "sha256:03b77d184b9eb40240ae9fd676ca364ce1085f203e1b1256f8ab9984dca80a84", size = 2143141, upload-time = "2025-11-04T13:43:37.701Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/f2/f11dd73284122713f5f89fc940f370d035fa8e1e078d446b3313955157fe/pydantic_core-2.41.5-pp311-pypy311_pp73-musllinux_1_1_armv7l.whl", hash = "sha256:a668ce24de96165bb239160b3d854943128f4334822900534f2fe947930e5770", size = 2330317, upload-time = "2025-11-04T13:43:40.406Z" },
+    { url = "https://files.pythonhosted.org/packages/88/9d/b06ca6acfe4abb296110fb1273a4d848a0bfb2ff65f3ee92127b3244e16b/pydantic_core-2.41.5-pp311-pypy311_pp73-musllinux_1_1_x86_64.whl", hash = "sha256:f14f8f046c14563f8eb3f45f499cc658ab8d10072961e07225e507adb700e93f", size = 2316992, upload-time = "2025-11-04T13:43:43.602Z" },
+    { url = "https://files.pythonhosted.org/packages/36/c7/cfc8e811f061c841d7990b0201912c3556bfeb99cdcb7ed24adc8d6f8704/pydantic_core-2.41.5-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:56121965f7a4dc965bff783d70b907ddf3d57f6eba29b6d2e5dabfaf07799c51", size = 2145302, upload-time = "2025-11-04T13:43:46.64Z" },
+]
+
+[[package]]
+name = "pydantic-settings"
+version = "2.14.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pydantic" },
+    { name = "python-dotenv" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5c/b5/8f48e906c3e0205276e8bd8cb7512217a87b2685304d64be27cad5b3019f/pydantic_settings-2.14.2.tar.gz", hash = "sha256:c19dd64b19097f1de80184f0cc7b0272a13ae6e170cbf240a3e27e381ed14a5f", size = 237700, upload-time = "2026-06-19T13:44:56.324Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/77/c1/6e422f34e569cf8e18df68d1939c81c099d2b61e4f7d9621c8a77560799c/pydantic_settings-2.14.2-py3-none-any.whl", hash = "sha256:a20c97b37910b6550d5ea50fbcc2d4187defe58cd57070b73863d069419c9440", size = 61715, upload-time = "2026-06-19T13:44:55.02Z" },
+]
+
+[[package]]
+name = "pygments"
+version = "2.20.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c3/b2/bc9c9196916376152d655522fdcebac55e66de6603a76a02bca1b6414f6c/pygments-2.20.0.tar.gz", hash = "sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f", size = 4955991, upload-time = "2026-03-29T13:29:33.898Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl", hash = "sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176", size = 1231151, upload-time = "2026-03-29T13:29:30.038Z" },
+]
+
+[[package]]
+name = "pyjwt"
+version = "2.13.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/3b/81/58d0ac84e1ef3a3843791d6954d94c0b33d526c75eeb1efbce9d0a4c4077/pyjwt-2.13.0.tar.gz", hash = "sha256:41571c89ca91598c79e8ef18a2d07367d4810fbbd6f637794879baf1b7703423", size = 107515, upload-time = "2026-05-21T19:54:36.618Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a3/5e/ecf12fdb62546d64385c158514e9b2b671f7832108ef2ecd2020ce0af2d1/pyjwt-2.13.0-py3-none-any.whl", hash = "sha256:66adcc2aff09b3f1bbd95fc1e1577df8ac8723c978552fd43304c8a290ac5728", size = 31274, upload-time = "2026-05-21T19:54:35.362Z" },
+]
+
+[package.optional-dependencies]
+crypto = [
+    { name = "cryptography" },
+]
+
+[[package]]
+name = "pyperclip"
+version = "1.11.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e8/52/d87eba7cb129b81563019d1679026e7a112ef76855d6159d24754dbd2a51/pyperclip-1.11.0.tar.gz", hash = "sha256:244035963e4428530d9e3a6101a1ef97209c6825edab1567beac148ccc1db1b6", size = 12185, upload-time = "2025-09-26T14:40:37.245Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/df/80/fc9d01d5ed37ba4c42ca2b55b4339ae6e200b456be3a1aaddf4a9fa99b8c/pyperclip-1.11.0-py3-none-any.whl", hash = "sha256:299403e9ff44581cb9ba2ffeed69c7aa96a008622ad0c46cb575ca75b5b84273", size = 11063, upload-time = "2025-09-26T14:40:36.069Z" },
+]
+
+[[package]]
+name = "pytest"
+version = "9.0.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "exceptiongroup", marker = "python_full_version < '3.11'" },
+    { name = "iniconfig" },
+    { name = "packaging" },
+    { name = "pluggy" },
+    { name = "pygments" },
+    { name = "tomli", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/7d/0d/549bd94f1a0a402dc8cf64563a117c0f3765662e2e668477624baeec44d5/pytest-9.0.3.tar.gz", hash = "sha256:b86ada508af81d19edeb213c681b1d48246c1a91d304c6c81a427674c17eb91c", size = 1572165, upload-time = "2026-04-07T17:16:18.027Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl", hash = "sha256:2c5efc453d45394fdd706ade797c0a81091eccd1d6e4bccfcd476e2b8e0ab5d9", size = 375249, upload-time = "2026-04-07T17:16:16.13Z" },
+]
+
+[[package]]
+name = "pytest-asyncio"
+version = "1.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "backports-asyncio-runner", marker = "python_full_version < '3.11'" },
+    { name = "pytest" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/90/2c/8af215c0f776415f3590cac4f9086ccefd6fd463befeae41cd4d3f193e5a/pytest_asyncio-1.3.0.tar.gz", hash = "sha256:d7f52f36d231b80ee124cd216ffb19369aa168fc10095013c6b014a34d3ee9e5", size = 50087, upload-time = "2025-11-10T16:07:47.256Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl", hash = "sha256:611e26147c7f77640e6d0a92a38ed17c3e9848063698d5c93d5aa7aa11cebff5", size = 15075, upload-time = "2025-11-10T16:07:45.537Z" },
+]
+
+[[package]]
+name = "python-dotenv"
+version = "1.2.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/82/ed/0301aeeac3e5353ef3d94b6ec08bbcabd04a72018415dcb29e588514bba8/python_dotenv-1.2.2.tar.gz", hash = "sha256:2c371a91fbd7ba082c2c1dc1f8bf89ca22564a087c2c287cd9b662adde799cf3", size = 50135, upload-time = "2026-03-01T16:00:26.196Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0b/d7/1959b9648791274998a9c3526f6d0ec8fd2233e4d4acce81bbae76b44b2a/python_dotenv-1.2.2-py3-none-any.whl", hash = "sha256:1d8214789a24de455a8b8bd8ae6fe3c6b69a5e3d64aa8a8e5d68e694bbcb285a", size = 22101, upload-time = "2026-03-01T16:00:25.09Z" },
+]
+
+[[package]]
+name = "python-multipart"
+version = "0.0.32"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/5b/42/55c32bb9b12693c092ad250a0e82edb5b31ddeda6eb772de5f308b3804ad/python_multipart-0.0.32.tar.gz", hash = "sha256:be54b7f3fa167bb83e4fcd936b887b708f4e57fe75911c02aebf53efaf8d938e", size = 46881, upload-time = "2026-06-04T16:18:58.647Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e1/04/e8135ebd1ad02c56ec633277529b2602ff99ff634be76cdba5744cf554fd/python_multipart-0.0.32-py3-none-any.whl", hash = "sha256:ff6d3f776f16878c894e52e107296ffc890e913c611b1a4ec6c44e2821fe2e23", size = 30042, upload-time = "2026-06-04T16:18:57.319Z" },
+]
+
+[[package]]
+name = "pywin32"
+version = "311"
+source = { registry = "https://pypi.org/simple" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7b/40/44efbb0dfbd33aca6a6483191dae0716070ed99e2ecb0c53683f400a0b4f/pywin32-311-cp310-cp310-win32.whl", hash = "sha256:d03ff496d2a0cd4a5893504789d4a15399133fe82517455e78bad62efbb7f0a3", size = 8760432, upload-time = "2025-07-14T20:13:05.9Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/bf/360243b1e953bd254a82f12653974be395ba880e7ec23e3731d9f73921cc/pywin32-311-cp310-cp310-win_amd64.whl", hash = "sha256:797c2772017851984b97180b0bebe4b620bb86328e8a884bb626156295a63b3b", size = 9590103, upload-time = "2025-07-14T20:13:07.698Z" },
+    { url = "https://files.pythonhosted.org/packages/57/38/d290720e6f138086fb3d5ffe0b6caa019a791dd57866940c82e4eeaf2012/pywin32-311-cp310-cp310-win_arm64.whl", hash = "sha256:0502d1facf1fed4839a9a51ccbcc63d952cf318f78ffc00a7e78528ac27d7a2b", size = 8778557, upload-time = "2025-07-14T20:13:11.11Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/af/449a6a91e5d6db51420875c54f6aff7c97a86a3b13a0b4f1a5c13b988de3/pywin32-311-cp311-cp311-win32.whl", hash = "sha256:184eb5e436dea364dcd3d2316d577d625c0351bf237c4e9a5fabbcfa5a58b151", size = 8697031, upload-time = "2025-07-14T20:13:13.266Z" },
+    { url = "https://files.pythonhosted.org/packages/51/8f/9bb81dd5bb77d22243d33c8397f09377056d5c687aa6d4042bea7fbf8364/pywin32-311-cp311-cp311-win_amd64.whl", hash = "sha256:3ce80b34b22b17ccbd937a6e78e7225d80c52f5ab9940fe0506a1a16f3dab503", size = 9508308, upload-time = "2025-07-14T20:13:15.147Z" },
+    { url = "https://files.pythonhosted.org/packages/44/7b/9c2ab54f74a138c491aba1b1cd0795ba61f144c711daea84a88b63dc0f6c/pywin32-311-cp311-cp311-win_arm64.whl", hash = "sha256:a733f1388e1a842abb67ffa8e7aad0e70ac519e09b0f6a784e65a136ec7cefd2", size = 8703930, upload-time = "2025-07-14T20:13:16.945Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/ab/01ea1943d4eba0f850c3c61e78e8dd59757ff815ff3ccd0a84de5f541f42/pywin32-311-cp312-cp312-win32.whl", hash = "sha256:750ec6e621af2b948540032557b10a2d43b0cee2ae9758c54154d711cc852d31", size = 8706543, upload-time = "2025-07-14T20:13:20.765Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/a8/a0e8d07d4d051ec7502cd58b291ec98dcc0c3fff027caad0470b72cfcc2f/pywin32-311-cp312-cp312-win_amd64.whl", hash = "sha256:b8c095edad5c211ff31c05223658e71bf7116daa0ecf3ad85f3201ea3190d067", size = 9495040, upload-time = "2025-07-14T20:13:22.543Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/3a/2ae996277b4b50f17d61f0603efd8253cb2d79cc7ae159468007b586396d/pywin32-311-cp312-cp312-win_arm64.whl", hash = "sha256:e286f46a9a39c4a18b319c28f59b61de793654af2f395c102b4f819e584b5852", size = 8710102, upload-time = "2025-07-14T20:13:24.682Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/be/3fd5de0979fcb3994bfee0d65ed8ca9506a8a1260651b86174f6a86f52b3/pywin32-311-cp313-cp313-win32.whl", hash = "sha256:f95ba5a847cba10dd8c4d8fefa9f2a6cf283b8b88ed6178fa8a6c1ab16054d0d", size = 8705700, upload-time = "2025-07-14T20:13:26.471Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/28/e0a1909523c6890208295a29e05c2adb2126364e289826c0a8bc7297bd5c/pywin32-311-cp313-cp313-win_amd64.whl", hash = "sha256:718a38f7e5b058e76aee1c56ddd06908116d35147e133427e59a3983f703a20d", size = 9494700, upload-time = "2025-07-14T20:13:28.243Z" },
+    { url = "https://files.pythonhosted.org/packages/04/bf/90339ac0f55726dce7d794e6d79a18a91265bdf3aa70b6b9ca52f35e022a/pywin32-311-cp313-cp313-win_arm64.whl", hash = "sha256:7b4075d959648406202d92a2310cb990fea19b535c7f4a78d3f5e10b926eeb8a", size = 8709318, upload-time = "2025-07-14T20:13:30.348Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/31/097f2e132c4f16d99a22bfb777e0fd88bd8e1c634304e102f313af69ace5/pywin32-311-cp314-cp314-win32.whl", hash = "sha256:b7a2c10b93f8986666d0c803ee19b5990885872a7de910fc460f9b0c2fbf92ee", size = 8840714, upload-time = "2025-07-14T20:13:32.449Z" },
+    { url = "https://files.pythonhosted.org/packages/90/4b/07c77d8ba0e01349358082713400435347df8426208171ce297da32c313d/pywin32-311-cp314-cp314-win_amd64.whl", hash = "sha256:3aca44c046bd2ed8c90de9cb8427f581c479e594e99b5c0bb19b29c10fd6cb87", size = 9656800, upload-time = "2025-07-14T20:13:34.312Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/d2/21af5c535501a7233e734b8af901574572da66fcc254cb35d0609c9080dd/pywin32-311-cp314-cp314-win_arm64.whl", hash = "sha256:a508e2d9025764a8270f93111a970e1d0fbfc33f4153b388bb649b7eec4f9b42", size = 8932540, upload-time = "2025-07-14T20:13:36.379Z" },
+]
+
+[[package]]
+name = "pywin32-ctypes"
+version = "0.2.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/85/9f/01a1a99704853cb63f253eea009390c88e7131c67e66a0a02099a8c917cb/pywin32-ctypes-0.2.3.tar.gz", hash = "sha256:d162dc04946d704503b2edc4d55f3dba5c1d539ead017afa00142c38b9885755", size = 29471, upload-time = "2024-08-14T10:15:34.626Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/de/3d/8161f7711c017e01ac9f008dfddd9410dff3674334c233bde66e7ba65bbf/pywin32_ctypes-0.2.3-py3-none-any.whl", hash = "sha256:8a1513379d709975552d202d942d9837758905c8d01eb82b8bcc30918929e7b8", size = 30756, upload-time = "2024-08-14T10:15:33.187Z" },
+]
+
+[[package]]
+name = "pyyaml"
+version = "6.0.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/05/8e/961c0007c59b8dd7729d542c61a4d537767a59645b82a0b521206e1e25c2/pyyaml-6.0.3.tar.gz", hash = "sha256:d76623373421df22fb4cf8817020cbb7ef15c725b9d5e45f17e189bfc384190f", size = 130960, upload-time = "2025-09-25T21:33:16.546Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f4/a0/39350dd17dd6d6c6507025c0e53aef67a9293a6d37d3511f23ea510d5800/pyyaml-6.0.3-cp310-cp310-macosx_10_13_x86_64.whl", hash = "sha256:214ed4befebe12df36bcc8bc2b64b396ca31be9304b8f59e25c11cf94a4c033b", size = 184227, upload-time = "2025-09-25T21:31:46.04Z" },
+    { url = "https://files.pythonhosted.org/packages/05/14/52d505b5c59ce73244f59c7a50ecf47093ce4765f116cdb98286a71eeca2/pyyaml-6.0.3-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:02ea2dfa234451bbb8772601d7b8e426c2bfa197136796224e50e35a78777956", size = 174019, upload-time = "2025-09-25T21:31:47.706Z" },
+    { url = "https://files.pythonhosted.org/packages/43/f7/0e6a5ae5599c838c696adb4e6330a59f463265bfa1e116cfd1fbb0abaaae/pyyaml-6.0.3-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b30236e45cf30d2b8e7b3e85881719e98507abed1011bf463a8fa23e9c3e98a8", size = 740646, upload-time = "2025-09-25T21:31:49.21Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/3a/61b9db1d28f00f8fd0ae760459a5c4bf1b941baf714e207b6eb0657d2578/pyyaml-6.0.3-cp310-cp310-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:66291b10affd76d76f54fad28e22e51719ef9ba22b29e1d7d03d6777a9174198", size = 840793, upload-time = "2025-09-25T21:31:50.735Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/1e/7acc4f0e74c4b3d9531e24739e0ab832a5edf40e64fbae1a9c01941cabd7/pyyaml-6.0.3-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9c7708761fccb9397fe64bbc0395abcae8c4bf7b0eac081e12b809bf47700d0b", size = 770293, upload-time = "2025-09-25T21:31:51.828Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/ef/abd085f06853af0cd59fa5f913d61a8eab65d7639ff2a658d18a25d6a89d/pyyaml-6.0.3-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:418cf3f2111bc80e0933b2cd8cd04f286338bb88bdc7bc8e6dd775ebde60b5e0", size = 732872, upload-time = "2025-09-25T21:31:53.282Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/15/2bc9c8faf6450a8b3c9fc5448ed869c599c0a74ba2669772b1f3a0040180/pyyaml-6.0.3-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:5e0b74767e5f8c593e8c9b5912019159ed0533c70051e9cce3e8b6aa699fcd69", size = 758828, upload-time = "2025-09-25T21:31:54.807Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/00/531e92e88c00f4333ce359e50c19b8d1de9fe8d581b1534e35ccfbc5f393/pyyaml-6.0.3-cp310-cp310-win32.whl", hash = "sha256:28c8d926f98f432f88adc23edf2e6d4921ac26fb084b028c733d01868d19007e", size = 142415, upload-time = "2025-09-25T21:31:55.885Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/fa/926c003379b19fca39dd4634818b00dec6c62d87faf628d1394e137354d4/pyyaml-6.0.3-cp310-cp310-win_amd64.whl", hash = "sha256:bdb2c67c6c1390b63c6ff89f210c8fd09d9a1217a465701eac7316313c915e4c", size = 158561, upload-time = "2025-09-25T21:31:57.406Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/16/a95b6757765b7b031c9374925bb718d55e0a9ba8a1b6a12d25962ea44347/pyyaml-6.0.3-cp311-cp311-macosx_10_13_x86_64.whl", hash = "sha256:44edc647873928551a01e7a563d7452ccdebee747728c1080d881d68af7b997e", size = 185826, upload-time = "2025-09-25T21:31:58.655Z" },
+    { url = "https://files.pythonhosted.org/packages/16/19/13de8e4377ed53079ee996e1ab0a9c33ec2faf808a4647b7b4c0d46dd239/pyyaml-6.0.3-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:652cb6edd41e718550aad172851962662ff2681490a8a711af6a4d288dd96824", size = 175577, upload-time = "2025-09-25T21:32:00.088Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/62/d2eb46264d4b157dae1275b573017abec435397aa59cbcdab6fc978a8af4/pyyaml-6.0.3-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:10892704fc220243f5305762e276552a0395f7beb4dbf9b14ec8fd43b57f126c", size = 775556, upload-time = "2025-09-25T21:32:01.31Z" },
+    { url = "https://files.pythonhosted.org/packages/10/cb/16c3f2cf3266edd25aaa00d6c4350381c8b012ed6f5276675b9eba8d9ff4/pyyaml-6.0.3-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:850774a7879607d3a6f50d36d04f00ee69e7fc816450e5f7e58d7f17f1ae5c00", size = 882114, upload-time = "2025-09-25T21:32:03.376Z" },
+    { url = "https://files.pythonhosted.org/packages/71/60/917329f640924b18ff085ab889a11c763e0b573da888e8404ff486657602/pyyaml-6.0.3-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b8bb0864c5a28024fac8a632c443c87c5aa6f215c0b126c449ae1a150412f31d", size = 806638, upload-time = "2025-09-25T21:32:04.553Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/6f/529b0f316a9fd167281a6c3826b5583e6192dba792dd55e3203d3f8e655a/pyyaml-6.0.3-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:1d37d57ad971609cf3c53ba6a7e365e40660e3be0e5175fa9f2365a379d6095a", size = 767463, upload-time = "2025-09-25T21:32:06.152Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/6a/b627b4e0c1dd03718543519ffb2f1deea4a1e6d42fbab8021936a4d22589/pyyaml-6.0.3-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:37503bfbfc9d2c40b344d06b2199cf0e96e97957ab1c1b546fd4f87e53e5d3e4", size = 794986, upload-time = "2025-09-25T21:32:07.367Z" },
+    { url = "https://files.pythonhosted.org/packages/45/91/47a6e1c42d9ee337c4839208f30d9f09caa9f720ec7582917b264defc875/pyyaml-6.0.3-cp311-cp311-win32.whl", hash = "sha256:8098f252adfa6c80ab48096053f512f2321f0b998f98150cea9bd23d83e1467b", size = 142543, upload-time = "2025-09-25T21:32:08.95Z" },
+    { url = "https://files.pythonhosted.org/packages/da/e3/ea007450a105ae919a72393cb06f122f288ef60bba2dc64b26e2646fa315/pyyaml-6.0.3-cp311-cp311-win_amd64.whl", hash = "sha256:9f3bfb4965eb874431221a3ff3fdcddc7e74e3b07799e0e84ca4a0f867d449bf", size = 158763, upload-time = "2025-09-25T21:32:09.96Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/33/422b98d2195232ca1826284a76852ad5a86fe23e31b009c9886b2d0fb8b2/pyyaml-6.0.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:7f047e29dcae44602496db43be01ad42fc6f1cc0d8cd6c83d342306c32270196", size = 182063, upload-time = "2025-09-25T21:32:11.445Z" },
+    { url = "https://files.pythonhosted.org/packages/89/a0/6cf41a19a1f2f3feab0e9c0b74134aa2ce6849093d5517a0c550fe37a648/pyyaml-6.0.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:fc09d0aa354569bc501d4e787133afc08552722d3ab34836a80547331bb5d4a0", size = 173973, upload-time = "2025-09-25T21:32:12.492Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/23/7a778b6bd0b9a8039df8b1b1d80e2e2ad78aa04171592c8a5c43a56a6af4/pyyaml-6.0.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9149cad251584d5fb4981be1ecde53a1ca46c891a79788c0df828d2f166bda28", size = 775116, upload-time = "2025-09-25T21:32:13.652Z" },
+    { url = "https://files.pythonhosted.org/packages/65/30/d7353c338e12baef4ecc1b09e877c1970bd3382789c159b4f89d6a70dc09/pyyaml-6.0.3-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5fdec68f91a0c6739b380c83b951e2c72ac0197ace422360e6d5a959d8d97b2c", size = 844011, upload-time = "2025-09-25T21:32:15.21Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/9d/b3589d3877982d4f2329302ef98a8026e7f4443c765c46cfecc8858c6b4b/pyyaml-6.0.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ba1cc08a7ccde2d2ec775841541641e4548226580ab850948cbfda66a1befcdc", size = 807870, upload-time = "2025-09-25T21:32:16.431Z" },
+    { url = "https://files.pythonhosted.org/packages/05/c0/b3be26a015601b822b97d9149ff8cb5ead58c66f981e04fedf4e762f4bd4/pyyaml-6.0.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:8dc52c23056b9ddd46818a57b78404882310fb473d63f17b07d5c40421e47f8e", size = 761089, upload-time = "2025-09-25T21:32:17.56Z" },
+    { url = "https://files.pythonhosted.org/packages/be/8e/98435a21d1d4b46590d5459a22d88128103f8da4c2d4cb8f14f2a96504e1/pyyaml-6.0.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:41715c910c881bc081f1e8872880d3c650acf13dfa8214bad49ed4cede7c34ea", size = 790181, upload-time = "2025-09-25T21:32:18.834Z" },
+    { url = "https://files.pythonhosted.org/packages/74/93/7baea19427dcfbe1e5a372d81473250b379f04b1bd3c4c5ff825e2327202/pyyaml-6.0.3-cp312-cp312-win32.whl", hash = "sha256:96b533f0e99f6579b3d4d4995707cf36df9100d67e0c8303a0c55b27b5f99bc5", size = 137658, upload-time = "2025-09-25T21:32:20.209Z" },
+    { url = "https://files.pythonhosted.org/packages/86/bf/899e81e4cce32febab4fb42bb97dcdf66bc135272882d1987881a4b519e9/pyyaml-6.0.3-cp312-cp312-win_amd64.whl", hash = "sha256:5fcd34e47f6e0b794d17de1b4ff496c00986e1c83f7ab2fb8fcfe9616ff7477b", size = 154003, upload-time = "2025-09-25T21:32:21.167Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/08/67bd04656199bbb51dbed1439b7f27601dfb576fb864099c7ef0c3e55531/pyyaml-6.0.3-cp312-cp312-win_arm64.whl", hash = "sha256:64386e5e707d03a7e172c0701abfb7e10f0fb753ee1d773128192742712a98fd", size = 140344, upload-time = "2025-09-25T21:32:22.617Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/11/0fd08f8192109f7169db964b5707a2f1e8b745d4e239b784a5a1dd80d1db/pyyaml-6.0.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:8da9669d359f02c0b91ccc01cac4a67f16afec0dac22c2ad09f46bee0697eba8", size = 181669, upload-time = "2025-09-25T21:32:23.673Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/16/95309993f1d3748cd644e02e38b75d50cbc0d9561d21f390a76242ce073f/pyyaml-6.0.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:2283a07e2c21a2aa78d9c4442724ec1eb15f5e42a723b99cb3d822d48f5f7ad1", size = 173252, upload-time = "2025-09-25T21:32:25.149Z" },
+    { url = "https://files.pythonhosted.org/packages/50/31/b20f376d3f810b9b2371e72ef5adb33879b25edb7a6d072cb7ca0c486398/pyyaml-6.0.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ee2922902c45ae8ccada2c5b501ab86c36525b883eff4255313a253a3160861c", size = 767081, upload-time = "2025-09-25T21:32:26.575Z" },
+    { url = "https://files.pythonhosted.org/packages/49/1e/a55ca81e949270d5d4432fbbd19dfea5321eda7c41a849d443dc92fd1ff7/pyyaml-6.0.3-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a33284e20b78bd4a18c8c2282d549d10bc8408a2a7ff57653c0cf0b9be0afce5", size = 841159, upload-time = "2025-09-25T21:32:27.727Z" },
+    { url = "https://files.pythonhosted.org/packages/74/27/e5b8f34d02d9995b80abcef563ea1f8b56d20134d8f4e5e81733b1feceb2/pyyaml-6.0.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0f29edc409a6392443abf94b9cf89ce99889a1dd5376d94316ae5145dfedd5d6", size = 801626, upload-time = "2025-09-25T21:32:28.878Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/11/ba845c23988798f40e52ba45f34849aa8a1f2d4af4b798588010792ebad6/pyyaml-6.0.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:f7057c9a337546edc7973c0d3ba84ddcdf0daa14533c2065749c9075001090e6", size = 753613, upload-time = "2025-09-25T21:32:30.178Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/e0/7966e1a7bfc0a45bf0a7fb6b98ea03fc9b8d84fa7f2229e9659680b69ee3/pyyaml-6.0.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:eda16858a3cab07b80edaf74336ece1f986ba330fdb8ee0d6c0d68fe82bc96be", size = 794115, upload-time = "2025-09-25T21:32:31.353Z" },
+    { url = "https://files.pythonhosted.org/packages/de/94/980b50a6531b3019e45ddeada0626d45fa85cbe22300844a7983285bed3b/pyyaml-6.0.3-cp313-cp313-win32.whl", hash = "sha256:d0eae10f8159e8fdad514efdc92d74fd8d682c933a6dd088030f3834bc8e6b26", size = 137427, upload-time = "2025-09-25T21:32:32.58Z" },
+    { url = "https://files.pythonhosted.org/packages/97/c9/39d5b874e8b28845e4ec2202b5da735d0199dbe5b8fb85f91398814a9a46/pyyaml-6.0.3-cp313-cp313-win_amd64.whl", hash = "sha256:79005a0d97d5ddabfeeea4cf676af11e647e41d81c9a7722a193022accdb6b7c", size = 154090, upload-time = "2025-09-25T21:32:33.659Z" },
+    { url = "https://files.pythonhosted.org/packages/73/e8/2bdf3ca2090f68bb3d75b44da7bbc71843b19c9f2b9cb9b0f4ab7a5a4329/pyyaml-6.0.3-cp313-cp313-win_arm64.whl", hash = "sha256:5498cd1645aa724a7c71c8f378eb29ebe23da2fc0d7a08071d89469bf1d2defb", size = 140246, upload-time = "2025-09-25T21:32:34.663Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/8c/f4bd7f6465179953d3ac9bc44ac1a8a3e6122cf8ada906b4f96c60172d43/pyyaml-6.0.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:8d1fab6bb153a416f9aeb4b8763bc0f22a5586065f86f7664fc23339fc1c1fac", size = 181814, upload-time = "2025-09-25T21:32:35.712Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/9c/4d95bb87eb2063d20db7b60faa3840c1b18025517ae857371c4dd55a6b3a/pyyaml-6.0.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:34d5fcd24b8445fadc33f9cf348c1047101756fd760b4dacb5c3e99755703310", size = 173809, upload-time = "2025-09-25T21:32:36.789Z" },
+    { url = "https://files.pythonhosted.org/packages/92/b5/47e807c2623074914e29dabd16cbbdd4bf5e9b2db9f8090fa64411fc5382/pyyaml-6.0.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:501a031947e3a9025ed4405a168e6ef5ae3126c59f90ce0cd6f2bfc477be31b7", size = 766454, upload-time = "2025-09-25T21:32:37.966Z" },
+    { url = "https://files.pythonhosted.org/packages/02/9e/e5e9b168be58564121efb3de6859c452fccde0ab093d8438905899a3a483/pyyaml-6.0.3-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:b3bc83488de33889877a0f2543ade9f70c67d66d9ebb4ac959502e12de895788", size = 836355, upload-time = "2025-09-25T21:32:39.178Z" },
+    { url = "https://files.pythonhosted.org/packages/88/f9/16491d7ed2a919954993e48aa941b200f38040928474c9e85ea9e64222c3/pyyaml-6.0.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c458b6d084f9b935061bc36216e8a69a7e293a2f1e68bf956dcd9e6cbcd143f5", size = 794175, upload-time = "2025-09-25T21:32:40.865Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/3f/5989debef34dc6397317802b527dbbafb2b4760878a53d4166579111411e/pyyaml-6.0.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7c6610def4f163542a622a73fb39f534f8c101d690126992300bf3207eab9764", size = 755228, upload-time = "2025-09-25T21:32:42.084Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/ce/af88a49043cd2e265be63d083fc75b27b6ed062f5f9fd6cdc223ad62f03e/pyyaml-6.0.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:5190d403f121660ce8d1d2c1bb2ef1bd05b5f68533fc5c2ea899bd15f4399b35", size = 789194, upload-time = "2025-09-25T21:32:43.362Z" },
+    { url = "https://files.pythonhosted.org/packages/23/20/bb6982b26a40bb43951265ba29d4c246ef0ff59c9fdcdf0ed04e0687de4d/pyyaml-6.0.3-cp314-cp314-win_amd64.whl", hash = "sha256:4a2e8cebe2ff6ab7d1050ecd59c25d4c8bd7e6f400f5f82b96557ac0abafd0ac", size = 156429, upload-time = "2025-09-25T21:32:57.844Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/f4/a4541072bb9422c8a883ab55255f918fa378ecf083f5b85e87fc2b4eda1b/pyyaml-6.0.3-cp314-cp314-win_arm64.whl", hash = "sha256:93dda82c9c22deb0a405ea4dc5f2d0cda384168e466364dec6255b293923b2f3", size = 143912, upload-time = "2025-09-25T21:32:59.247Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/f9/07dd09ae774e4616edf6cda684ee78f97777bdd15847253637a6f052a62f/pyyaml-6.0.3-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:02893d100e99e03eda1c8fd5c441d8c60103fd175728e23e431db1b589cf5ab3", size = 189108, upload-time = "2025-09-25T21:32:44.377Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/78/8d08c9fb7ce09ad8c38ad533c1191cf27f7ae1effe5bb9400a46d9437fcf/pyyaml-6.0.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c1ff362665ae507275af2853520967820d9124984e0f7466736aea23d8611fba", size = 183641, upload-time = "2025-09-25T21:32:45.407Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/5b/3babb19104a46945cf816d047db2788bcaf8c94527a805610b0289a01c6b/pyyaml-6.0.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6adc77889b628398debc7b65c073bcb99c4a0237b248cacaf3fe8a557563ef6c", size = 831901, upload-time = "2025-09-25T21:32:48.83Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/cc/dff0684d8dc44da4d22a13f35f073d558c268780ce3c6ba1b87055bb0b87/pyyaml-6.0.3-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a80cb027f6b349846a3bf6d73b5e95e782175e52f22108cfa17876aaeff93702", size = 861132, upload-time = "2025-09-25T21:32:50.149Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/5e/f77dc6b9036943e285ba76b49e118d9ea929885becb0a29ba8a7c75e29fe/pyyaml-6.0.3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:00c4bdeba853cc34e7dd471f16b4114f4162dc03e6b7afcc2128711f0eca823c", size = 839261, upload-time = "2025-09-25T21:32:51.808Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/88/a9db1376aa2a228197c58b37302f284b5617f56a5d959fd1763fb1675ce6/pyyaml-6.0.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:66e1674c3ef6f541c35191caae2d429b967b99e02040f5ba928632d9a7f0f065", size = 805272, upload-time = "2025-09-25T21:32:52.941Z" },
+    { url = "https://files.pythonhosted.org/packages/da/92/1446574745d74df0c92e6aa4a7b0b3130706a4142b2d1a5869f2eaa423c6/pyyaml-6.0.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:16249ee61e95f858e83976573de0f5b2893b3677ba71c9dd36b9cf8be9ac6d65", size = 829923, upload-time = "2025-09-25T21:32:54.537Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/7a/1c7270340330e575b92f397352af856a8c06f230aa3e76f86b39d01b416a/pyyaml-6.0.3-cp314-cp314t-win_amd64.whl", hash = "sha256:4ad1906908f2f5ae4e5a8ddfce73c320c2a1429ec52eafd27138b7f1cbe341c9", size = 174062, upload-time = "2025-09-25T21:32:55.767Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/12/de94a39c2ef588c7e6455cfbe7343d3b2dc9d6b6b2f40c4c6565744c873d/pyyaml-6.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:ebc55a14a21cb14062aa4162f906cd962b28e2e9ea38f9b4391244cd8de4ae0b", size = 149341, upload-time = "2025-09-25T21:32:56.828Z" },
+]
+
+[[package]]
+name = "referencing"
+version = "0.37.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "attrs" },
+    { name = "rpds-py" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/22/f5/df4e9027acead3ecc63e50fe1e36aca1523e1719559c499951bb4b53188f/referencing-0.37.0.tar.gz", hash = "sha256:44aefc3142c5b842538163acb373e24cce6632bd54bdb01b21ad5863489f50d8", size = 78036, upload-time = "2025-10-13T15:30:48.871Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2c/58/ca301544e1fa93ed4f80d724bf5b194f6e4b945841c5bfd555878eea9fcb/referencing-0.37.0-py3-none-any.whl", hash = "sha256:381329a9f99628c9069361716891d34ad94af76e461dcb0335825aecc7692231", size = 26766, upload-time = "2025-10-13T15:30:47.625Z" },
+]
+
+[[package]]
+name = "rich"
+version = "14.3.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "markdown-it-py" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b3/c6/f3b320c27991c46f43ee9d856302c70dc2d0fb2dba4842ff739d5f46b393/rich-14.3.3.tar.gz", hash = "sha256:b8daa0b9e4eef54dd8cf7c86c03713f53241884e814f4e2f5fb342fe520f639b", size = 230582, upload-time = "2026-02-19T17:23:12.474Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/14/25/b208c5683343959b670dc001595f2f3737e051da617f66c31f7c4fa93abc/rich-14.3.3-py3-none-any.whl", hash = "sha256:793431c1f8619afa7d3b52b2cdec859562b950ea0d4b6b505397612db8d5362d", size = 310458, upload-time = "2026-02-19T17:23:13.732Z" },
+]
+
+[[package]]
+name = "rich-rst"
+version = "1.3.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "docutils" },
+    { name = "rich" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/bc/6d/a506aaa4a9eaa945ed8ab2b7347859f53593864289853c5d6d62b77246e0/rich_rst-1.3.2.tar.gz", hash = "sha256:a1196fdddf1e364b02ec68a05e8ff8f6914fee10fbca2e6b6735f166bb0da8d4", size = 14936, upload-time = "2025-10-14T16:49:45.332Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/13/2f/b4530fbf948867702d0a3f27de4a6aab1d156f406d72852ab902c4d04de9/rich_rst-1.3.2-py3-none-any.whl", hash = "sha256:a99b4907cbe118cf9d18b0b44de272efa61f15117c61e39ebdc431baf5df722a", size = 12567, upload-time = "2025-10-14T16:49:42.953Z" },
+]
+
+[[package]]
+name = "rpds-py"
+version = "0.30.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/20/af/3f2f423103f1113b36230496629986e0ef7e199d2aa8392452b484b38ced/rpds_py-0.30.0.tar.gz", hash = "sha256:dd8ff7cf90014af0c0f787eea34794ebf6415242ee1d6fa91eaba725cc441e84", size = 69469, upload-time = "2025-11-30T20:24:38.837Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/06/0c/0c411a0ec64ccb6d104dcabe0e713e05e153a9a2c3c2bd2b32ce412166fe/rpds_py-0.30.0-cp310-cp310-macosx_10_12_x86_64.whl", hash = "sha256:679ae98e00c0e8d68a7fda324e16b90fd5260945b45d3b824c892cec9eea3288", size = 370490, upload-time = "2025-11-30T20:21:33.256Z" },
+    { url = "https://files.pythonhosted.org/packages/19/6a/4ba3d0fb7297ebae71171822554abe48d7cab29c28b8f9f2c04b79988c05/rpds_py-0.30.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:4cc2206b76b4f576934f0ed374b10d7ca5f457858b157ca52064bdfc26b9fc00", size = 359751, upload-time = "2025-11-30T20:21:34.591Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/7c/e4933565ef7f7a0818985d87c15d9d273f1a649afa6a52ea35ad011195ea/rpds_py-0.30.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:389a2d49eded1896c3d48b0136ead37c48e221b391c052fba3f4055c367f60a6", size = 389696, upload-time = "2025-11-30T20:21:36.122Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/01/6271a2511ad0815f00f7ed4390cf2567bec1d4b1da39e2c27a41e6e3b4de/rpds_py-0.30.0-cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:32c8528634e1bf7121f3de08fa85b138f4e0dc47657866630611b03967f041d7", size = 403136, upload-time = "2025-11-30T20:21:37.728Z" },
+    { url = "https://files.pythonhosted.org/packages/55/64/c857eb7cd7541e9b4eee9d49c196e833128a55b89a9850a9c9ac33ccf897/rpds_py-0.30.0-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:f207f69853edd6f6700b86efb84999651baf3789e78a466431df1331608e5324", size = 524699, upload-time = "2025-11-30T20:21:38.92Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/ed/94816543404078af9ab26159c44f9e98e20fe47e2126d5d32c9d9948d10a/rpds_py-0.30.0-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:67b02ec25ba7a9e8fa74c63b6ca44cf5707f2fbfadae3ee8e7494297d56aa9df", size = 412022, upload-time = "2025-11-30T20:21:40.407Z" },
+    { url = "https://files.pythonhosted.org/packages/61/b5/707f6cf0066a6412aacc11d17920ea2e19e5b2f04081c64526eb35b5c6e7/rpds_py-0.30.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0c0e95f6819a19965ff420f65578bacb0b00f251fefe2c8b23347c37174271f3", size = 390522, upload-time = "2025-11-30T20:21:42.17Z" },
+    { url = "https://files.pythonhosted.org/packages/13/4e/57a85fda37a229ff4226f8cbcf09f2a455d1ed20e802ce5b2b4a7f5ed053/rpds_py-0.30.0-cp310-cp310-manylinux_2_31_riscv64.whl", hash = "sha256:a452763cc5198f2f98898eb98f7569649fe5da666c2dc6b5ddb10fde5a574221", size = 404579, upload-time = "2025-11-30T20:21:43.769Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/da/c9339293513ec680a721e0e16bf2bac3db6e5d7e922488de471308349bba/rpds_py-0.30.0-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:e0b65193a413ccc930671c55153a03ee57cecb49e6227204b04fae512eb657a7", size = 421305, upload-time = "2025-11-30T20:21:44.994Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/be/522cb84751114f4ad9d822ff5a1aa3c98006341895d5f084779b99596e5c/rpds_py-0.30.0-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:858738e9c32147f78b3ac24dc0edb6610000e56dc0f700fd5f651d0a0f0eb9ff", size = 572503, upload-time = "2025-11-30T20:21:46.91Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/9b/de879f7e7ceddc973ea6e4629e9b380213a6938a249e94b0cdbcc325bb66/rpds_py-0.30.0-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:da279aa314f00acbb803da1e76fa18666778e8a8f83484fba94526da5de2cba7", size = 598322, upload-time = "2025-11-30T20:21:48.709Z" },
+    { url = "https://files.pythonhosted.org/packages/48/ac/f01fc22efec3f37d8a914fc1b2fb9bcafd56a299edbe96406f3053edea5a/rpds_py-0.30.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:7c64d38fb49b6cdeda16ab49e35fe0da2e1e9b34bc38bd78386530f218b37139", size = 560792, upload-time = "2025-11-30T20:21:50.024Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/da/4e2b19d0f131f35b6146425f846563d0ce036763e38913d917187307a671/rpds_py-0.30.0-cp310-cp310-win32.whl", hash = "sha256:6de2a32a1665b93233cde140ff8b3467bdb9e2af2b91079f0333a0974d12d464", size = 221901, upload-time = "2025-11-30T20:21:51.32Z" },
+    { url = "https://files.pythonhosted.org/packages/96/cb/156d7a5cf4f78a7cc571465d8aec7a3c447c94f6749c5123f08438bcf7bc/rpds_py-0.30.0-cp310-cp310-win_amd64.whl", hash = "sha256:1726859cd0de969f88dc8673bdd954185b9104e05806be64bcd87badbe313169", size = 235823, upload-time = "2025-11-30T20:21:52.505Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/6e/f964e88b3d2abee2a82c1ac8366da848fce1c6d834dc2132c3fda3970290/rpds_py-0.30.0-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:a2bffea6a4ca9f01b3f8e548302470306689684e61602aa3d141e34da06cf425", size = 370157, upload-time = "2025-11-30T20:21:53.789Z" },
+    { url = "https://files.pythonhosted.org/packages/94/ba/24e5ebb7c1c82e74c4e4f33b2112a5573ddc703915b13a073737b59b86e0/rpds_py-0.30.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:dc4f992dfe1e2bc3ebc7444f6c7051b4bc13cd8e33e43511e8ffd13bf407010d", size = 359676, upload-time = "2025-11-30T20:21:55.475Z" },
+    { url = "https://files.pythonhosted.org/packages/84/86/04dbba1b087227747d64d80c3b74df946b986c57af0a9f0c98726d4d7a3b/rpds_py-0.30.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:422c3cb9856d80b09d30d2eb255d0754b23e090034e1deb4083f8004bd0761e4", size = 389938, upload-time = "2025-11-30T20:21:57.079Z" },
+    { url = "https://files.pythonhosted.org/packages/42/bb/1463f0b1722b7f45431bdd468301991d1328b16cffe0b1c2918eba2c4eee/rpds_py-0.30.0-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:07ae8a593e1c3c6b82ca3292efbe73c30b61332fd612e05abee07c79359f292f", size = 402932, upload-time = "2025-11-30T20:21:58.47Z" },
+    { url = "https://files.pythonhosted.org/packages/99/ee/2520700a5c1f2d76631f948b0736cdf9b0acb25abd0ca8e889b5c62ac2e3/rpds_py-0.30.0-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:12f90dd7557b6bd57f40abe7747e81e0c0b119bef015ea7726e69fe550e394a4", size = 525830, upload-time = "2025-11-30T20:21:59.699Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/ad/bd0331f740f5705cc555a5e17fdf334671262160270962e69a2bdef3bf76/rpds_py-0.30.0-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:99b47d6ad9a6da00bec6aabe5a6279ecd3c06a329d4aa4771034a21e335c3a97", size = 412033, upload-time = "2025-11-30T20:22:00.991Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/1e/372195d326549bb51f0ba0f2ecb9874579906b97e08880e7a65c3bef1a99/rpds_py-0.30.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:33f559f3104504506a44bb666b93a33f5d33133765b0c216a5bf2f1e1503af89", size = 390828, upload-time = "2025-11-30T20:22:02.723Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/2b/d88bb33294e3e0c76bc8f351a3721212713629ffca1700fa94979cb3eae8/rpds_py-0.30.0-cp311-cp311-manylinux_2_31_riscv64.whl", hash = "sha256:946fe926af6e44f3697abbc305ea168c2c31d3e3ef1058cf68f379bf0335a78d", size = 404683, upload-time = "2025-11-30T20:22:04.367Z" },
+    { url = "https://files.pythonhosted.org/packages/50/32/c759a8d42bcb5289c1fac697cd92f6fe01a018dd937e62ae77e0e7f15702/rpds_py-0.30.0-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:495aeca4b93d465efde585977365187149e75383ad2684f81519f504f5c13038", size = 421583, upload-time = "2025-11-30T20:22:05.814Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/81/e729761dbd55ddf5d84ec4ff1f47857f4374b0f19bdabfcf929164da3e24/rpds_py-0.30.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:d9a0ca5da0386dee0655b4ccdf46119df60e0f10da268d04fe7cc87886872ba7", size = 572496, upload-time = "2025-11-30T20:22:07.713Z" },
+    { url = "https://files.pythonhosted.org/packages/14/f6/69066a924c3557c9c30baa6ec3a0aa07526305684c6f86c696b08860726c/rpds_py-0.30.0-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:8d6d1cc13664ec13c1b84241204ff3b12f9bb82464b8ad6e7a5d3486975c2eed", size = 598669, upload-time = "2025-11-30T20:22:09.312Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/48/905896b1eb8a05630d20333d1d8ffd162394127b74ce0b0784ae04498d32/rpds_py-0.30.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:3896fa1be39912cf0757753826bc8bdc8ca331a28a7c4ae46b7a21280b06bb85", size = 561011, upload-time = "2025-11-30T20:22:11.309Z" },
+    { url = "https://files.pythonhosted.org/packages/22/16/cd3027c7e279d22e5eb431dd3c0fbc677bed58797fe7581e148f3f68818b/rpds_py-0.30.0-cp311-cp311-win32.whl", hash = "sha256:55f66022632205940f1827effeff17c4fa7ae1953d2b74a8581baaefb7d16f8c", size = 221406, upload-time = "2025-11-30T20:22:13.101Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/5b/e7b7aa136f28462b344e652ee010d4de26ee9fd16f1bfd5811f5153ccf89/rpds_py-0.30.0-cp311-cp311-win_amd64.whl", hash = "sha256:a51033ff701fca756439d641c0ad09a41d9242fa69121c7d8769604a0a629825", size = 236024, upload-time = "2025-11-30T20:22:14.853Z" },
+    { url = "https://files.pythonhosted.org/packages/14/a6/364bba985e4c13658edb156640608f2c9e1d3ea3c81b27aa9d889fff0e31/rpds_py-0.30.0-cp311-cp311-win_arm64.whl", hash = "sha256:47b0ef6231c58f506ef0b74d44e330405caa8428e770fec25329ed2cb971a229", size = 229069, upload-time = "2025-11-30T20:22:16.577Z" },
+    { url = "https://files.pythonhosted.org/packages/03/e7/98a2f4ac921d82f33e03f3835f5bf3a4a40aa1bfdc57975e74a97b2b4bdd/rpds_py-0.30.0-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:a161f20d9a43006833cd7068375a94d035714d73a172b681d8881820600abfad", size = 375086, upload-time = "2025-11-30T20:22:17.93Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/a1/bca7fd3d452b272e13335db8d6b0b3ecde0f90ad6f16f3328c6fb150c889/rpds_py-0.30.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6abc8880d9d036ecaafe709079969f56e876fcf107f7a8e9920ba6d5a3878d05", size = 359053, upload-time = "2025-11-30T20:22:19.297Z" },
+    { url = "https://files.pythonhosted.org/packages/65/1c/ae157e83a6357eceff62ba7e52113e3ec4834a84cfe07fa4b0757a7d105f/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ca28829ae5f5d569bb62a79512c842a03a12576375d5ece7d2cadf8abe96ec28", size = 390763, upload-time = "2025-11-30T20:22:21.661Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/36/eb2eb8515e2ad24c0bd43c3ee9cd74c33f7ca6430755ccdb240fd3144c44/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:a1010ed9524c73b94d15919ca4d41d8780980e1765babf85f9a2f90d247153dd", size = 408951, upload-time = "2025-11-30T20:22:23.408Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/65/ad8dc1784a331fabbd740ef6f71ce2198c7ed0890dab595adb9ea2d775a1/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:f8d1736cfb49381ba528cd5baa46f82fdc65c06e843dab24dd70b63d09121b3f", size = 514622, upload-time = "2025-11-30T20:22:25.16Z" },
+    { url = "https://files.pythonhosted.org/packages/63/8e/0cfa7ae158e15e143fe03993b5bcd743a59f541f5952e1546b1ac1b5fd45/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:d948b135c4693daff7bc2dcfc4ec57237a29bd37e60c2fabf5aff2bbacf3e2f1", size = 414492, upload-time = "2025-11-30T20:22:26.505Z" },
+    { url = "https://files.pythonhosted.org/packages/60/1b/6f8f29f3f995c7ffdde46a626ddccd7c63aefc0efae881dc13b6e5d5bb16/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:47f236970bccb2233267d89173d3ad2703cd36a0e2a6e92d0560d333871a3d23", size = 394080, upload-time = "2025-11-30T20:22:27.934Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/d5/a266341051a7a3ca2f4b750a3aa4abc986378431fc2da508c5034d081b70/rpds_py-0.30.0-cp312-cp312-manylinux_2_31_riscv64.whl", hash = "sha256:2e6ecb5a5bcacf59c3f912155044479af1d0b6681280048b338b28e364aca1f6", size = 408680, upload-time = "2025-11-30T20:22:29.341Z" },
+    { url = "https://files.pythonhosted.org/packages/10/3b/71b725851df9ab7a7a4e33cf36d241933da66040d195a84781f49c50490c/rpds_py-0.30.0-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:a8fa71a2e078c527c3e9dc9fc5a98c9db40bcc8a92b4e8858e36d329f8684b51", size = 423589, upload-time = "2025-11-30T20:22:31.469Z" },
+    { url = "https://files.pythonhosted.org/packages/00/2b/e59e58c544dc9bd8bd8384ecdb8ea91f6727f0e37a7131baeff8d6f51661/rpds_py-0.30.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:73c67f2db7bc334e518d097c6d1e6fed021bbc9b7d678d6cc433478365d1d5f5", size = 573289, upload-time = "2025-11-30T20:22:32.997Z" },
+    { url = "https://files.pythonhosted.org/packages/da/3e/a18e6f5b460893172a7d6a680e86d3b6bc87a54c1f0b03446a3c8c7b588f/rpds_py-0.30.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:5ba103fb455be00f3b1c2076c9d4264bfcb037c976167a6047ed82f23153f02e", size = 599737, upload-time = "2025-11-30T20:22:34.419Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/e2/714694e4b87b85a18e2c243614974413c60aa107fd815b8cbc42b873d1d7/rpds_py-0.30.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:7cee9c752c0364588353e627da8a7e808a66873672bcb5f52890c33fd965b394", size = 563120, upload-time = "2025-11-30T20:22:35.903Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/ab/d5d5e3bcedb0a77f4f613706b750e50a5a3ba1c15ccd3665ecc636c968fd/rpds_py-0.30.0-cp312-cp312-win32.whl", hash = "sha256:1ab5b83dbcf55acc8b08fc62b796ef672c457b17dbd7820a11d6c52c06839bdf", size = 223782, upload-time = "2025-11-30T20:22:37.271Z" },
+    { url = "https://files.pythonhosted.org/packages/39/3b/f786af9957306fdc38a74cef405b7b93180f481fb48453a114bb6465744a/rpds_py-0.30.0-cp312-cp312-win_amd64.whl", hash = "sha256:a090322ca841abd453d43456ac34db46e8b05fd9b3b4ac0c78bcde8b089f959b", size = 240463, upload-time = "2025-11-30T20:22:39.021Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/d2/b91dc748126c1559042cfe41990deb92c4ee3e2b415f6b5234969ffaf0cc/rpds_py-0.30.0-cp312-cp312-win_arm64.whl", hash = "sha256:669b1805bd639dd2989b281be2cfd951c6121b65e729d9b843e9639ef1fd555e", size = 230868, upload-time = "2025-11-30T20:22:40.493Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/dc/d61221eb88ff410de3c49143407f6f3147acf2538c86f2ab7ce65ae7d5f9/rpds_py-0.30.0-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:f83424d738204d9770830d35290ff3273fbb02b41f919870479fab14b9d303b2", size = 374887, upload-time = "2025-11-30T20:22:41.812Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/32/55fb50ae104061dbc564ef15cc43c013dc4a9f4527a1f4d99baddf56fe5f/rpds_py-0.30.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:e7536cd91353c5273434b4e003cbda89034d67e7710eab8761fd918ec6c69cf8", size = 358904, upload-time = "2025-11-30T20:22:43.479Z" },
+    { url = "https://files.pythonhosted.org/packages/58/70/faed8186300e3b9bdd138d0273109784eea2396c68458ed580f885dfe7ad/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:2771c6c15973347f50fece41fc447c054b7ac2ae0502388ce3b6738cd366e3d4", size = 389945, upload-time = "2025-11-30T20:22:44.819Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/a8/073cac3ed2c6387df38f71296d002ab43496a96b92c823e76f46b8af0543/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:0a59119fc6e3f460315fe9d08149f8102aa322299deaa5cab5b40092345c2136", size = 407783, upload-time = "2025-11-30T20:22:46.103Z" },
+    { url = "https://files.pythonhosted.org/packages/77/57/5999eb8c58671f1c11eba084115e77a8899d6e694d2a18f69f0ba471ec8b/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:76fec018282b4ead0364022e3c54b60bf368b9d926877957a8624b58419169b7", size = 515021, upload-time = "2025-11-30T20:22:47.458Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/af/5ab4833eadc36c0a8ed2bc5c0de0493c04f6c06de223170bd0798ff98ced/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:692bef75a5525db97318e8cd061542b5a79812d711ea03dbc1f6f8dbb0c5f0d2", size = 414589, upload-time = "2025-11-30T20:22:48.872Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/de/f7192e12b21b9e9a68a6d0f249b4af3fdcdff8418be0767a627564afa1f1/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9027da1ce107104c50c81383cae773ef5c24d296dd11c99e2629dbd7967a20c6", size = 394025, upload-time = "2025-11-30T20:22:50.196Z" },
+    { url = "https://files.pythonhosted.org/packages/91/c4/fc70cd0249496493500e7cc2de87504f5aa6509de1e88623431fec76d4b6/rpds_py-0.30.0-cp313-cp313-manylinux_2_31_riscv64.whl", hash = "sha256:9cf69cdda1f5968a30a359aba2f7f9aa648a9ce4b580d6826437f2b291cfc86e", size = 408895, upload-time = "2025-11-30T20:22:51.87Z" },
+    { url = "https://files.pythonhosted.org/packages/58/95/d9275b05ab96556fefff73a385813eb66032e4c99f411d0795372d9abcea/rpds_py-0.30.0-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:a4796a717bf12b9da9d3ad002519a86063dcac8988b030e405704ef7d74d2d9d", size = 422799, upload-time = "2025-11-30T20:22:53.341Z" },
+    { url = "https://files.pythonhosted.org/packages/06/c1/3088fc04b6624eb12a57eb814f0d4997a44b0d208d6cace713033ff1a6ba/rpds_py-0.30.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:5d4c2aa7c50ad4728a094ebd5eb46c452e9cb7edbfdb18f9e1221f597a73e1e7", size = 572731, upload-time = "2025-11-30T20:22:54.778Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/42/c612a833183b39774e8ac8fecae81263a68b9583ee343db33ab571a7ce55/rpds_py-0.30.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:ba81a9203d07805435eb06f536d95a266c21e5b2dfbf6517748ca40c98d19e31", size = 599027, upload-time = "2025-11-30T20:22:56.212Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/60/525a50f45b01d70005403ae0e25f43c0384369ad24ffe46e8d9068b50086/rpds_py-0.30.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:945dccface01af02675628334f7cf49c2af4c1c904748efc5cf7bbdf0b579f95", size = 563020, upload-time = "2025-11-30T20:22:58.2Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/5d/47c4655e9bcd5ca907148535c10e7d489044243cc9941c16ed7cd53be91d/rpds_py-0.30.0-cp313-cp313-win32.whl", hash = "sha256:b40fb160a2db369a194cb27943582b38f79fc4887291417685f3ad693c5a1d5d", size = 223139, upload-time = "2025-11-30T20:23:00.209Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/e1/485132437d20aa4d3e1d8b3fb5a5e65aa8139f1e097080c2a8443201742c/rpds_py-0.30.0-cp313-cp313-win_amd64.whl", hash = "sha256:806f36b1b605e2d6a72716f321f20036b9489d29c51c91f4dd29a3e3afb73b15", size = 240224, upload-time = "2025-11-30T20:23:02.008Z" },
+    { url = "https://files.pythonhosted.org/packages/24/95/ffd128ed1146a153d928617b0ef673960130be0009c77d8fbf0abe306713/rpds_py-0.30.0-cp313-cp313-win_arm64.whl", hash = "sha256:d96c2086587c7c30d44f31f42eae4eac89b60dabbac18c7669be3700f13c3ce1", size = 230645, upload-time = "2025-11-30T20:23:03.43Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/1b/b10de890a0def2a319a2626334a7f0ae388215eb60914dbac8a3bae54435/rpds_py-0.30.0-cp313-cp313t-macosx_10_12_x86_64.whl", hash = "sha256:eb0b93f2e5c2189ee831ee43f156ed34e2a89a78a66b98cadad955972548be5a", size = 364443, upload-time = "2025-11-30T20:23:04.878Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/bf/27e39f5971dc4f305a4fb9c672ca06f290f7c4e261c568f3dea16a410d47/rpds_py-0.30.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:922e10f31f303c7c920da8981051ff6d8c1a56207dbdf330d9047f6d30b70e5e", size = 353375, upload-time = "2025-11-30T20:23:06.342Z" },
+    { url = "https://files.pythonhosted.org/packages/40/58/442ada3bba6e8e6615fc00483135c14a7538d2ffac30e2d933ccf6852232/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:cdc62c8286ba9bf7f47befdcea13ea0e26bf294bda99758fd90535cbaf408000", size = 383850, upload-time = "2025-11-30T20:23:07.825Z" },
+    { url = "https://files.pythonhosted.org/packages/14/14/f59b0127409a33c6ef6f5c1ebd5ad8e32d7861c9c7adfa9a624fc3889f6c/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:47f9a91efc418b54fb8190a6b4aa7813a23fb79c51f4bb84e418f5476c38b8db", size = 392812, upload-time = "2025-11-30T20:23:09.228Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/66/e0be3e162ac299b3a22527e8913767d869e6cc75c46bd844aa43fb81ab62/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:1f3587eb9b17f3789ad50824084fa6f81921bbf9a795826570bda82cb3ed91f2", size = 517841, upload-time = "2025-11-30T20:23:11.186Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/55/fa3b9cf31d0c963ecf1ba777f7cf4b2a2c976795ac430d24a1f43d25a6ba/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:39c02563fc592411c2c61d26b6c5fe1e51eaa44a75aa2c8735ca88b0d9599daa", size = 408149, upload-time = "2025-11-30T20:23:12.864Z" },
+    { url = "https://files.pythonhosted.org/packages/60/ca/780cf3b1a32b18c0f05c441958d3758f02544f1d613abf9488cd78876378/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:51a1234d8febafdfd33a42d97da7a43f5dcb120c1060e352a3fbc0c6d36e2083", size = 383843, upload-time = "2025-11-30T20:23:14.638Z" },
+    { url = "https://files.pythonhosted.org/packages/82/86/d5f2e04f2aa6247c613da0c1dd87fcd08fa17107e858193566048a1e2f0a/rpds_py-0.30.0-cp313-cp313t-manylinux_2_31_riscv64.whl", hash = "sha256:eb2c4071ab598733724c08221091e8d80e89064cd472819285a9ab0f24bcedb9", size = 396507, upload-time = "2025-11-30T20:23:16.105Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/9a/453255d2f769fe44e07ea9785c8347edaf867f7026872e76c1ad9f7bed92/rpds_py-0.30.0-cp313-cp313t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:6bdfdb946967d816e6adf9a3d8201bfad269c67efe6cefd7093ef959683c8de0", size = 414949, upload-time = "2025-11-30T20:23:17.539Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/31/622a86cdc0c45d6df0e9ccb6becdba5074735e7033c20e401a6d9d0e2ca0/rpds_py-0.30.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:c77afbd5f5250bf27bf516c7c4a016813eb2d3e116139aed0096940c5982da94", size = 565790, upload-time = "2025-11-30T20:23:19.029Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/5d/15bbf0fb4a3f58a3b1c67855ec1efcc4ceaef4e86644665fff03e1b66d8d/rpds_py-0.30.0-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:61046904275472a76c8c90c9ccee9013d70a6d0f73eecefd38c1ae7c39045a08", size = 590217, upload-time = "2025-11-30T20:23:20.885Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/61/21b8c41f68e60c8cc3b2e25644f0e3681926020f11d06ab0b78e3c6bbff1/rpds_py-0.30.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:4c5f36a861bc4b7da6516dbdf302c55313afa09b81931e8280361a4f6c9a2d27", size = 555806, upload-time = "2025-11-30T20:23:22.488Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/39/7e067bb06c31de48de3eb200f9fc7c58982a4d3db44b07e73963e10d3be9/rpds_py-0.30.0-cp313-cp313t-win32.whl", hash = "sha256:3d4a69de7a3e50ffc214ae16d79d8fbb0922972da0356dcf4d0fdca2878559c6", size = 211341, upload-time = "2025-11-30T20:23:24.449Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/4d/222ef0b46443cf4cf46764d9c630f3fe4abaa7245be9417e56e9f52b8f65/rpds_py-0.30.0-cp313-cp313t-win_amd64.whl", hash = "sha256:f14fc5df50a716f7ece6a80b6c78bb35ea2ca47c499e422aa4463455dd96d56d", size = 225768, upload-time = "2025-11-30T20:23:25.908Z" },
+    { url = "https://files.pythonhosted.org/packages/86/81/dad16382ebbd3d0e0328776d8fd7ca94220e4fa0798d1dc5e7da48cb3201/rpds_py-0.30.0-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:68f19c879420aa08f61203801423f6cd5ac5f0ac4ac82a2368a9fcd6a9a075e0", size = 362099, upload-time = "2025-11-30T20:23:27.316Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/60/19f7884db5d5603edf3c6bce35408f45ad3e97e10007df0e17dd57af18f8/rpds_py-0.30.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:ec7c4490c672c1a0389d319b3a9cfcd098dcdc4783991553c332a15acf7249be", size = 353192, upload-time = "2025-11-30T20:23:29.151Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/c4/76eb0e1e72d1a9c4703c69607cec123c29028bff28ce41588792417098ac/rpds_py-0.30.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f251c812357a3fed308d684a5079ddfb9d933860fc6de89f2b7ab00da481e65f", size = 384080, upload-time = "2025-11-30T20:23:30.785Z" },
+    { url = "https://files.pythonhosted.org/packages/72/87/87ea665e92f3298d1b26d78814721dc39ed8d2c74b86e83348d6b48a6f31/rpds_py-0.30.0-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:ac98b175585ecf4c0348fd7b29c3864bda53b805c773cbf7bfdaffc8070c976f", size = 394841, upload-time = "2025-11-30T20:23:32.209Z" },
+    { url = "https://files.pythonhosted.org/packages/77/ad/7783a89ca0587c15dcbf139b4a8364a872a25f861bdb88ed99f9b0dec985/rpds_py-0.30.0-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:3e62880792319dbeb7eb866547f2e35973289e7d5696c6e295476448f5b63c87", size = 516670, upload-time = "2025-11-30T20:23:33.742Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/3c/2882bdac942bd2172f3da574eab16f309ae10a3925644e969536553cb4ee/rpds_py-0.30.0-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:4e7fc54e0900ab35d041b0601431b0a0eb495f0851a0639b6ef90f7741b39a18", size = 408005, upload-time = "2025-11-30T20:23:35.253Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/81/9a91c0111ce1758c92516a3e44776920b579d9a7c09b2b06b642d4de3f0f/rpds_py-0.30.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:47e77dc9822d3ad616c3d5759ea5631a75e5809d5a28707744ef79d7a1bcfcad", size = 382112, upload-time = "2025-11-30T20:23:36.842Z" },
+    { url = "https://files.pythonhosted.org/packages/cf/8e/1da49d4a107027e5fbc64daeab96a0706361a2918da10cb41769244b805d/rpds_py-0.30.0-cp314-cp314-manylinux_2_31_riscv64.whl", hash = "sha256:b4dc1a6ff022ff85ecafef7979a2c6eb423430e05f1165d6688234e62ba99a07", size = 399049, upload-time = "2025-11-30T20:23:38.343Z" },
+    { url = "https://files.pythonhosted.org/packages/df/5a/7ee239b1aa48a127570ec03becbb29c9d5a9eb092febbd1699d567cae859/rpds_py-0.30.0-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:4559c972db3a360808309e06a74628b95eaccbf961c335c8fe0d590cf587456f", size = 415661, upload-time = "2025-11-30T20:23:40.263Z" },
+    { url = "https://files.pythonhosted.org/packages/70/ea/caa143cf6b772f823bc7929a45da1fa83569ee49b11d18d0ada7f5ee6fd6/rpds_py-0.30.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:0ed177ed9bded28f8deb6ab40c183cd1192aa0de40c12f38be4d59cd33cb5c65", size = 565606, upload-time = "2025-11-30T20:23:42.186Z" },
+    { url = "https://files.pythonhosted.org/packages/64/91/ac20ba2d69303f961ad8cf55bf7dbdb4763f627291ba3d0d7d67333cced9/rpds_py-0.30.0-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:ad1fa8db769b76ea911cb4e10f049d80bf518c104f15b3edb2371cc65375c46f", size = 591126, upload-time = "2025-11-30T20:23:44.086Z" },
+    { url = "https://files.pythonhosted.org/packages/21/20/7ff5f3c8b00c8a95f75985128c26ba44503fb35b8e0259d812766ea966c7/rpds_py-0.30.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:46e83c697b1f1c72b50e5ee5adb4353eef7406fb3f2043d64c33f20ad1c2fc53", size = 553371, upload-time = "2025-11-30T20:23:46.004Z" },
+    { url = "https://files.pythonhosted.org/packages/72/c7/81dadd7b27c8ee391c132a6b192111ca58d866577ce2d9b0ca157552cce0/rpds_py-0.30.0-cp314-cp314-win32.whl", hash = "sha256:ee454b2a007d57363c2dfd5b6ca4a5d7e2c518938f8ed3b706e37e5d470801ed", size = 215298, upload-time = "2025-11-30T20:23:47.696Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/d2/1aaac33287e8cfb07aab2e6b8ac1deca62f6f65411344f1433c55e6f3eb8/rpds_py-0.30.0-cp314-cp314-win_amd64.whl", hash = "sha256:95f0802447ac2d10bcc69f6dc28fe95fdf17940367b21d34e34c737870758950", size = 228604, upload-time = "2025-11-30T20:23:49.501Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/95/ab005315818cc519ad074cb7784dae60d939163108bd2b394e60dc7b5461/rpds_py-0.30.0-cp314-cp314-win_arm64.whl", hash = "sha256:613aa4771c99f03346e54c3f038e4cc574ac09a3ddfb0e8878487335e96dead6", size = 222391, upload-time = "2025-11-30T20:23:50.96Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/68/154fe0194d83b973cdedcdcc88947a2752411165930182ae41d983dcefa6/rpds_py-0.30.0-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:7e6ecfcb62edfd632e56983964e6884851786443739dbfe3582947e87274f7cb", size = 364868, upload-time = "2025-11-30T20:23:52.494Z" },
+    { url = "https://files.pythonhosted.org/packages/83/69/8bbc8b07ec854d92a8b75668c24d2abcb1719ebf890f5604c61c9369a16f/rpds_py-0.30.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:a1d0bc22a7cdc173fedebb73ef81e07faef93692b8c1ad3733b67e31e1b6e1b8", size = 353747, upload-time = "2025-11-30T20:23:54.036Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/00/ba2e50183dbd9abcce9497fa5149c62b4ff3e22d338a30d690f9af970561/rpds_py-0.30.0-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0d08f00679177226c4cb8c5265012eea897c8ca3b93f429e546600c971bcbae7", size = 383795, upload-time = "2025-11-30T20:23:55.556Z" },
+    { url = "https://files.pythonhosted.org/packages/05/6f/86f0272b84926bcb0e4c972262f54223e8ecc556b3224d281e6598fc9268/rpds_py-0.30.0-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:5965af57d5848192c13534f90f9dd16464f3c37aaf166cc1da1cae1fd5a34898", size = 393330, upload-time = "2025-11-30T20:23:57.033Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/e9/0e02bb2e6dc63d212641da45df2b0bf29699d01715913e0d0f017ee29438/rpds_py-0.30.0-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9a4e86e34e9ab6b667c27f3211ca48f73dba7cd3d90f8d5b11be56e5dbc3fb4e", size = 518194, upload-time = "2025-11-30T20:23:58.637Z" },
+    { url = "https://files.pythonhosted.org/packages/ee/ca/be7bca14cf21513bdf9c0606aba17d1f389ea2b6987035eb4f62bd923f25/rpds_py-0.30.0-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:e5d3e6b26f2c785d65cc25ef1e5267ccbe1b069c5c21b8cc724efee290554419", size = 408340, upload-time = "2025-11-30T20:24:00.2Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/c7/736e00ebf39ed81d75544c0da6ef7b0998f8201b369acf842f9a90dc8fce/rpds_py-0.30.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:626a7433c34566535b6e56a1b39a7b17ba961e97ce3b80ec62e6f1312c025551", size = 383765, upload-time = "2025-11-30T20:24:01.759Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/3f/da50dfde9956aaf365c4adc9533b100008ed31aea635f2b8d7b627e25b49/rpds_py-0.30.0-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:acd7eb3f4471577b9b5a41baf02a978e8bdeb08b4b355273994f8b87032000a8", size = 396834, upload-time = "2025-11-30T20:24:03.687Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/00/34bcc2565b6020eab2623349efbdec810676ad571995911f1abdae62a3a0/rpds_py-0.30.0-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:fe5fa731a1fa8a0a56b0977413f8cacac1768dad38d16b3a296712709476fbd5", size = 415470, upload-time = "2025-11-30T20:24:05.232Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/28/882e72b5b3e6f718d5453bd4d0d9cf8df36fddeb4ddbbab17869d5868616/rpds_py-0.30.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:74a3243a411126362712ee1524dfc90c650a503502f135d54d1b352bd01f2404", size = 565630, upload-time = "2025-11-30T20:24:06.878Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/97/04a65539c17692de5b85c6e293520fd01317fd878ea1995f0367d4532fb1/rpds_py-0.30.0-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:3e8eeb0544f2eb0d2581774be4c3410356eba189529a6b3e36bbbf9696175856", size = 591148, upload-time = "2025-11-30T20:24:08.445Z" },
+    { url = "https://files.pythonhosted.org/packages/85/70/92482ccffb96f5441aab93e26c4d66489eb599efdcf96fad90c14bbfb976/rpds_py-0.30.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:dbd936cde57abfee19ab3213cf9c26be06d60750e60a8e4dd85d1ab12c8b1f40", size = 556030, upload-time = "2025-11-30T20:24:10.956Z" },
+    { url = "https://files.pythonhosted.org/packages/20/53/7c7e784abfa500a2b6b583b147ee4bb5a2b3747a9166bab52fec4b5b5e7d/rpds_py-0.30.0-cp314-cp314t-win32.whl", hash = "sha256:dc824125c72246d924f7f796b4f63c1e9dc810c7d9e2355864b3c3a73d59ade0", size = 211570, upload-time = "2025-11-30T20:24:12.735Z" },
+    { url = "https://files.pythonhosted.org/packages/d0/02/fa464cdfbe6b26e0600b62c528b72d8608f5cc49f96b8d6e38c95d60c676/rpds_py-0.30.0-cp314-cp314t-win_amd64.whl", hash = "sha256:27f4b0e92de5bfbc6f86e43959e6edd1425c33b5e69aab0984a72047f2bcf1e3", size = 226532, upload-time = "2025-11-30T20:24:14.634Z" },
+    { url = "https://files.pythonhosted.org/packages/69/71/3f34339ee70521864411f8b6992e7ab13ac30d8e4e3309e07c7361767d91/rpds_py-0.30.0-pp311-pypy311_pp73-macosx_10_12_x86_64.whl", hash = "sha256:c2262bdba0ad4fc6fb5545660673925c2d2a5d9e2e0fb603aad545427be0fc58", size = 372292, upload-time = "2025-11-30T20:24:16.537Z" },
+    { url = "https://files.pythonhosted.org/packages/57/09/f183df9b8f2d66720d2ef71075c59f7e1b336bec7ee4c48f0a2b06857653/rpds_py-0.30.0-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:ee6af14263f25eedc3bb918a3c04245106a42dfd4f5c2285ea6f997b1fc3f89a", size = 362128, upload-time = "2025-11-30T20:24:18.086Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/68/5c2594e937253457342e078f0cc1ded3dd7b2ad59afdbf2d354869110a02/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3adbb8179ce342d235c31ab8ec511e66c73faa27a47e076ccc92421add53e2bb", size = 391542, upload-time = "2025-11-30T20:24:20.092Z" },
+    { url = "https://files.pythonhosted.org/packages/49/5c/31ef1afd70b4b4fbdb2800249f34c57c64beb687495b10aec0365f53dfc4/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:250fa00e9543ac9b97ac258bd37367ff5256666122c2d0f2bc97577c60a1818c", size = 404004, upload-time = "2025-11-30T20:24:22.231Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/63/0cfbea38d05756f3440ce6534d51a491d26176ac045e2707adc99bb6e60a/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9854cf4f488b3d57b9aaeb105f06d78e5529d3145b1e4a41750167e8c213c6d3", size = 527063, upload-time = "2025-11-30T20:24:24.302Z" },
+    { url = "https://files.pythonhosted.org/packages/42/e6/01e1f72a2456678b0f618fc9a1a13f882061690893c192fcad9f2926553a/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:993914b8e560023bc0a8bf742c5f303551992dcb85e247b1e5c7f4a7d145bda5", size = 413099, upload-time = "2025-11-30T20:24:25.916Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/25/8df56677f209003dcbb180765520c544525e3ef21ea72279c98b9aa7c7fb/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:58edca431fb9b29950807e301826586e5bbf24163677732429770a697ffe6738", size = 392177, upload-time = "2025-11-30T20:24:27.834Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/b4/0a771378c5f16f8115f796d1f437950158679bcd2a7c68cf251cfb00ed5b/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_31_riscv64.whl", hash = "sha256:dea5b552272a944763b34394d04577cf0f9bd013207bc32323b5a89a53cf9c2f", size = 406015, upload-time = "2025-11-30T20:24:29.457Z" },
+    { url = "https://files.pythonhosted.org/packages/36/d8/456dbba0af75049dc6f63ff295a2f92766b9d521fa00de67a2bd6427d57a/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:ba3af48635eb83d03f6c9735dfb21785303e73d22ad03d489e88adae6eab8877", size = 423736, upload-time = "2025-11-30T20:24:31.22Z" },
+    { url = "https://files.pythonhosted.org/packages/13/64/b4d76f227d5c45a7e0b796c674fd81b0a6c4fbd48dc29271857d8219571c/rpds_py-0.30.0-pp311-pypy311_pp73-musllinux_1_2_aarch64.whl", hash = "sha256:dff13836529b921e22f15cb099751209a60009731a68519630a24d61f0b1b30a", size = 573981, upload-time = "2025-11-30T20:24:32.934Z" },
+    { url = "https://files.pythonhosted.org/packages/20/91/092bacadeda3edf92bf743cc96a7be133e13a39cdbfd7b5082e7ab638406/rpds_py-0.30.0-pp311-pypy311_pp73-musllinux_1_2_i686.whl", hash = "sha256:1b151685b23929ab7beec71080a8889d4d6d9fa9a983d213f07121205d48e2c4", size = 599782, upload-time = "2025-11-30T20:24:35.169Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/b7/b95708304cd49b7b6f82fdd039f1748b66ec2b21d6a45180910802f1abf1/rpds_py-0.30.0-pp311-pypy311_pp73-musllinux_1_2_x86_64.whl", hash = "sha256:ac37f9f516c51e5753f27dfdef11a88330f04de2d564be3991384b2f3535d02e", size = 562191, upload-time = "2025-11-30T20:24:36.853Z" },
+]
+
+[[package]]
+name = "secretstorage"
+version = "3.5.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cryptography" },
+    { name = "jeepney" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/1c/03/e834bcd866f2f8a49a85eaff47340affa3bfa391ee9912a952a1faa68c7b/secretstorage-3.5.0.tar.gz", hash = "sha256:f04b8e4689cbce351744d5537bf6b1329c6fc68f91fa666f60a380edddcd11be", size = 19884, upload-time = "2025-11-23T19:02:53.191Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b7/46/f5af3402b579fd5e11573ce652019a67074317e18c1935cc0b4ba9b35552/secretstorage-3.5.0-py3-none-any.whl", hash = "sha256:0ce65888c0725fcb2c5bc0fdb8e5438eece02c523557ea40ce0703c266248137", size = 15554, upload-time = "2025-11-23T19:02:51.545Z" },
+]
+
+[[package]]
+name = "sse-starlette"
+version = "3.3.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "starlette" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5a/9f/c3695c2d2d4ef70072c3a06992850498b01c6bc9be531950813716b426fa/sse_starlette-3.3.2.tar.gz", hash = "sha256:678fca55a1945c734d8472a6cad186a55ab02840b4f6786f5ee8770970579dcd", size = 32326, upload-time = "2026-02-28T11:24:34.36Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/61/28/8cb142d3fe80c4a2d8af54ca0b003f47ce0ba920974e7990fa6e016402d1/sse_starlette-3.3.2-py3-none-any.whl", hash = "sha256:5c3ea3dad425c601236726af2f27689b74494643f57017cafcb6f8c9acfbb862", size = 14270, upload-time = "2026-02-28T11:24:32.984Z" },
+]
+
+[[package]]
+name = "starlette"
+version = "1.3.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/eb/e3/7c1dc7381d9f8ab7d854328ebfa884e62cb3f3d8549ddfd37c7814f42afa/starlette-1.3.1.tar.gz", hash = "sha256:05d0213193f2fbaae60e2ecb593b4add4262ad4e46536b54abe36f11a71724e0", size = 2703240, upload-time = "2026-06-12T09:23:11.602Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ec/bb/2799cc2ede3ed41131f8975621e7213dfc7ef4acbbaadfa440f32500c370/starlette-1.3.1-py3-none-any.whl", hash = "sha256:c7372aae11c3c3f26a42df7bd626cec2f47d03483d261d369516a615a53714c6", size = 73632, upload-time = "2026-06-12T09:23:10.017Z" },
+]
+
+[[package]]
+name = "testing-demo"
+version = "0.1.0"
+source = { virtual = "." }
+dependencies = [
+    { name = "dirty-equals" },
+    { name = "fastmcp" },
+    { name = "pytest" },
+    { name = "pytest-asyncio" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "dirty-equals", specifier = ">=0.9.0" },
+    { name = "fastmcp", specifier = ">=2.0.0" },
+    { name = "pytest", specifier = ">=9.0.3" },
+    { name = "pytest-asyncio", specifier = ">=1.2.0" },
+]
+
+[[package]]
+name = "tomli"
+version = "2.4.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/82/30/31573e9457673ab10aa432461bee537ce6cef177667deca369efb79df071/tomli-2.4.0.tar.gz", hash = "sha256:aa89c3f6c277dd275d8e243ad24f3b5e701491a860d5121f2cdd399fbb31fc9c", size = 17477, upload-time = "2026-01-11T11:22:38.165Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3c/d9/3dc2289e1f3b32eb19b9785b6a006b28ee99acb37d1d47f78d4c10e28bf8/tomli-2.4.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:b5ef256a3fd497d4973c11bf142e9ed78b150d36f5773f1ca6088c230ffc5867", size = 153663, upload-time = "2026-01-11T11:21:45.27Z" },
+    { url = "https://files.pythonhosted.org/packages/51/32/ef9f6845e6b9ca392cd3f64f9ec185cc6f09f0a2df3db08cbe8809d1d435/tomli-2.4.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:5572e41282d5268eb09a697c89a7bee84fae66511f87533a6f88bd2f7b652da9", size = 148469, upload-time = "2026-01-11T11:21:46.873Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/c2/506e44cce89a8b1b1e047d64bd495c22c9f71f21e05f380f1a950dd9c217/tomli-2.4.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:551e321c6ba03b55676970b47cb1b73f14a0a4dce6a3e1a9458fd6d921d72e95", size = 236039, upload-time = "2026-01-11T11:21:48.503Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/40/e1b65986dbc861b7e986e8ec394598187fa8aee85b1650b01dd925ca0be8/tomli-2.4.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5e3f639a7a8f10069d0e15408c0b96a2a828cfdec6fca05296ebcdcc28ca7c76", size = 243007, upload-time = "2026-01-11T11:21:49.456Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/6f/6e39ce66b58a5b7ae572a0f4352ff40c71e8573633deda43f6a379d56b3e/tomli-2.4.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:1b168f2731796b045128c45982d3a4874057626da0e2ef1fdd722848b741361d", size = 240875, upload-time = "2026-01-11T11:21:50.755Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/ad/cb089cb190487caa80204d503c7fd0f4d443f90b95cf4ef5cf5aa0f439b0/tomli-2.4.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:133e93646ec4300d651839d382d63edff11d8978be23da4cc106f5a18b7d0576", size = 246271, upload-time = "2026-01-11T11:21:51.81Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/63/69125220e47fd7a3a27fd0de0c6398c89432fec41bc739823bcc66506af6/tomli-2.4.0-cp311-cp311-win32.whl", hash = "sha256:b6c78bdf37764092d369722d9946cb65b8767bfa4110f902a1b2542d8d173c8a", size = 96770, upload-time = "2026-01-11T11:21:52.647Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/0d/a22bb6c83f83386b0008425a6cd1fa1c14b5f3dd4bad05e98cf3dbbf4a64/tomli-2.4.0-cp311-cp311-win_amd64.whl", hash = "sha256:d3d1654e11d724760cdb37a3d7691f0be9db5fbdaef59c9f532aabf87006dbaa", size = 107626, upload-time = "2026-01-11T11:21:53.459Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/6d/77be674a3485e75cacbf2ddba2b146911477bd887dda9d8c9dfb2f15e871/tomli-2.4.0-cp311-cp311-win_arm64.whl", hash = "sha256:cae9c19ed12d4e8f3ebf46d1a75090e4c0dc16271c5bce1c833ac168f08fb614", size = 94842, upload-time = "2026-01-11T11:21:54.831Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/43/7389a1869f2f26dba52404e1ef13b4784b6b37dac93bac53457e3ff24ca3/tomli-2.4.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:920b1de295e72887bafa3ad9f7a792f811847d57ea6b1215154030cf131f16b1", size = 154894, upload-time = "2026-01-11T11:21:56.07Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/05/2f9bf110b5294132b2edf13fe6ca6ae456204f3d749f623307cbb7a946f2/tomli-2.4.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:7d6d9a4aee98fac3eab4952ad1d73aee87359452d1c086b5ceb43ed02ddb16b8", size = 149053, upload-time = "2026-01-11T11:21:57.467Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/41/1eda3ca1abc6f6154a8db4d714a4d35c4ad90adc0bcf700657291593fbf3/tomli-2.4.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:36b9d05b51e65b254ea6c2585b59d2c4cb91c8a3d91d0ed0f17591a29aaea54a", size = 243481, upload-time = "2026-01-11T11:21:58.661Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/6d/02ff5ab6c8868b41e7d4b987ce2b5f6a51d3335a70aa144edd999e055a01/tomli-2.4.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:1c8a885b370751837c029ef9bc014f27d80840e48bac415f3412e6593bbc18c1", size = 251720, upload-time = "2026-01-11T11:22:00.178Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/57/0405c59a909c45d5b6f146107c6d997825aa87568b042042f7a9c0afed34/tomli-2.4.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:8768715ffc41f0008abe25d808c20c3d990f42b6e2e58305d5da280ae7d1fa3b", size = 247014, upload-time = "2026-01-11T11:22:01.238Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/0e/2e37568edd944b4165735687cbaf2fe3648129e440c26d02223672ee0630/tomli-2.4.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:7b438885858efd5be02a9a133caf5812b8776ee0c969fea02c45e8e3f296ba51", size = 251820, upload-time = "2026-01-11T11:22:02.727Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/1c/ee3b707fdac82aeeb92d1a113f803cf6d0f37bdca0849cb489553e1f417a/tomli-2.4.0-cp312-cp312-win32.whl", hash = "sha256:0408e3de5ec77cc7f81960c362543cbbd91ef883e3138e81b729fc3eea5b9729", size = 97712, upload-time = "2026-01-11T11:22:03.777Z" },
+    { url = "https://files.pythonhosted.org/packages/69/13/c07a9177d0b3bab7913299b9278845fc6eaaca14a02667c6be0b0a2270c8/tomli-2.4.0-cp312-cp312-win_amd64.whl", hash = "sha256:685306e2cc7da35be4ee914fd34ab801a6acacb061b6a7abca922aaf9ad368da", size = 108296, upload-time = "2026-01-11T11:22:04.86Z" },
+    { url = "https://files.pythonhosted.org/packages/18/27/e267a60bbeeee343bcc279bb9e8fbed0cbe224bc7b2a3dc2975f22809a09/tomli-2.4.0-cp312-cp312-win_arm64.whl", hash = "sha256:5aa48d7c2356055feef06a43611fc401a07337d5b006be13a30f6c58f869e3c3", size = 94553, upload-time = "2026-01-11T11:22:05.854Z" },
+    { url = "https://files.pythonhosted.org/packages/34/91/7f65f9809f2936e1f4ce6268ae1903074563603b2a2bd969ebbda802744f/tomli-2.4.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:84d081fbc252d1b6a982e1870660e7330fb8f90f676f6e78b052ad4e64714bf0", size = 154915, upload-time = "2026-01-11T11:22:06.703Z" },
+    { url = "https://files.pythonhosted.org/packages/20/aa/64dd73a5a849c2e8f216b755599c511badde80e91e9bc2271baa7b2cdbb1/tomli-2.4.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:9a08144fa4cba33db5255f9b74f0b89888622109bd2776148f2597447f92a94e", size = 149038, upload-time = "2026-01-11T11:22:07.56Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/8a/6d38870bd3d52c8d1505ce054469a73f73a0fe62c0eaf5dddf61447e32fa/tomli-2.4.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c73add4bb52a206fd0c0723432db123c0c75c280cbd67174dd9d2db228ebb1b4", size = 242245, upload-time = "2026-01-11T11:22:08.344Z" },
+    { url = "https://files.pythonhosted.org/packages/59/bb/8002fadefb64ab2669e5b977df3f5e444febea60e717e755b38bb7c41029/tomli-2.4.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:1fb2945cbe303b1419e2706e711b7113da57b7db31ee378d08712d678a34e51e", size = 250335, upload-time = "2026-01-11T11:22:09.951Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/3d/4cdb6f791682b2ea916af2de96121b3cb1284d7c203d97d92d6003e91c8d/tomli-2.4.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:bbb1b10aa643d973366dc2cb1ad94f99c1726a02343d43cbc011edbfac579e7c", size = 245962, upload-time = "2026-01-11T11:22:11.27Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/4a/5f25789f9a460bd858ba9756ff52d0830d825b458e13f754952dd15fb7bb/tomli-2.4.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:4cbcb367d44a1f0c2be408758b43e1ffb5308abe0ea222897d6bfc8e8281ef2f", size = 250396, upload-time = "2026-01-11T11:22:12.325Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/2f/b73a36fea58dfa08e8b3a268750e6853a6aac2a349241a905ebd86f3047a/tomli-2.4.0-cp313-cp313-win32.whl", hash = "sha256:7d49c66a7d5e56ac959cb6fc583aff0651094ec071ba9ad43df785abc2320d86", size = 97530, upload-time = "2026-01-11T11:22:13.865Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/af/ca18c134b5d75de7e8dc551c5234eaba2e8e951f6b30139599b53de9c187/tomli-2.4.0-cp313-cp313-win_amd64.whl", hash = "sha256:3cf226acb51d8f1c394c1b310e0e0e61fecdd7adcb78d01e294ac297dd2e7f87", size = 108227, upload-time = "2026-01-11T11:22:15.224Z" },
+    { url = "https://files.pythonhosted.org/packages/22/c3/b386b832f209fee8073c8138ec50f27b4460db2fdae9ffe022df89a57f9b/tomli-2.4.0-cp313-cp313-win_arm64.whl", hash = "sha256:d20b797a5c1ad80c516e41bc1fb0443ddb5006e9aaa7bda2d71978346aeb9132", size = 94748, upload-time = "2026-01-11T11:22:16.009Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/c4/84047a97eb1004418bc10bdbcfebda209fca6338002eba2dc27cc6d13563/tomli-2.4.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:26ab906a1eb794cd4e103691daa23d95c6919cc2fa9160000ac02370cc9dd3f6", size = 154725, upload-time = "2026-01-11T11:22:17.269Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/5d/d39038e646060b9d76274078cddf146ced86dc2b9e8bbf737ad5983609a0/tomli-2.4.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:20cedb4ee43278bc4f2fee6cb50daec836959aadaf948db5172e776dd3d993fc", size = 148901, upload-time = "2026-01-11T11:22:18.287Z" },
+    { url = "https://files.pythonhosted.org/packages/73/e5/383be1724cb30f4ce44983d249645684a48c435e1cd4f8b5cded8a816d3c/tomli-2.4.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:39b0b5d1b6dd03684b3fb276407ebed7090bbec989fa55838c98560c01113b66", size = 243375, upload-time = "2026-01-11T11:22:19.154Z" },
+    { url = "https://files.pythonhosted.org/packages/31/f0/bea80c17971c8d16d3cc109dc3585b0f2ce1036b5f4a8a183789023574f2/tomli-2.4.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a26d7ff68dfdb9f87a016ecfd1e1c2bacbe3108f4e0f8bcd2228ef9a766c787d", size = 250639, upload-time = "2026-01-11T11:22:20.168Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/8f/2853c36abbb7608e3f945d8a74e32ed3a74ee3a1f468f1ffc7d1cb3abba6/tomli-2.4.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:20ffd184fb1df76a66e34bd1b36b4a4641bd2b82954befa32fe8163e79f1a702", size = 246897, upload-time = "2026-01-11T11:22:21.544Z" },
+    { url = "https://files.pythonhosted.org/packages/49/f0/6c05e3196ed5337b9fe7ea003e95fd3819a840b7a0f2bf5a408ef1dad8ed/tomli-2.4.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:75c2f8bbddf170e8effc98f5e9084a8751f8174ea6ccf4fca5398436e0320bc8", size = 254697, upload-time = "2026-01-11T11:22:23.058Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/f5/2922ef29c9f2951883525def7429967fc4d8208494e5ab524234f06b688b/tomli-2.4.0-cp314-cp314-win32.whl", hash = "sha256:31d556d079d72db7c584c0627ff3a24c5d3fb4f730221d3444f3efb1b2514776", size = 98567, upload-time = "2026-01-11T11:22:24.033Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/31/22b52e2e06dd2a5fdbc3ee73226d763b184ff21fc24e20316a44ccc4d96b/tomli-2.4.0-cp314-cp314-win_amd64.whl", hash = "sha256:43e685b9b2341681907759cf3a04e14d7104b3580f808cfde1dfdb60ada85475", size = 108556, upload-time = "2026-01-11T11:22:25.378Z" },
+    { url = "https://files.pythonhosted.org/packages/48/3d/5058dff3255a3d01b705413f64f4306a141a8fd7a251e5a495e3f192a998/tomli-2.4.0-cp314-cp314-win_arm64.whl", hash = "sha256:3d895d56bd3f82ddd6faaff993c275efc2ff38e52322ea264122d72729dca2b2", size = 96014, upload-time = "2026-01-11T11:22:26.138Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/4e/75dab8586e268424202d3a1997ef6014919c941b50642a1682df43204c22/tomli-2.4.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:5b5807f3999fb66776dbce568cc9a828544244a8eb84b84b9bafc080c99597b9", size = 163339, upload-time = "2026-01-11T11:22:27.143Z" },
+    { url = "https://files.pythonhosted.org/packages/06/e3/b904d9ab1016829a776d97f163f183a48be6a4deb87304d1e0116a349519/tomli-2.4.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c084ad935abe686bd9c898e62a02a19abfc9760b5a79bc29644463eaf2840cb0", size = 159490, upload-time = "2026-01-11T11:22:28.399Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/5a/fc3622c8b1ad823e8ea98a35e3c632ee316d48f66f80f9708ceb4f2a0322/tomli-2.4.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0f2e3955efea4d1cfbcb87bc321e00dc08d2bcb737fd1d5e398af111d86db5df", size = 269398, upload-time = "2026-01-11T11:22:29.345Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/33/62bd6152c8bdd4c305ad9faca48f51d3acb2df1f8791b1477d46ff86e7f8/tomli-2.4.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0e0fe8a0b8312acf3a88077a0802565cb09ee34107813bba1c7cd591fa6cfc8d", size = 276515, upload-time = "2026-01-11T11:22:30.327Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/ff/ae53619499f5235ee4211e62a8d7982ba9e439a0fb4f2f351a93d67c1dd2/tomli-2.4.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:413540dce94673591859c4c6f794dfeaa845e98bf35d72ed59636f869ef9f86f", size = 273806, upload-time = "2026-01-11T11:22:32.56Z" },
+    { url = "https://files.pythonhosted.org/packages/47/71/cbca7787fa68d4d0a9f7072821980b39fbb1b6faeb5f5cf02f4a5559fa28/tomli-2.4.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:0dc56fef0e2c1c470aeac5b6ca8cc7b640bb93e92d9803ddaf9ea03e198f5b0b", size = 281340, upload-time = "2026-01-11T11:22:33.505Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/00/d595c120963ad42474cf6ee7771ad0d0e8a49d0f01e29576ee9195d9ecdf/tomli-2.4.0-cp314-cp314t-win32.whl", hash = "sha256:d878f2a6707cc9d53a1be1414bbb419e629c3d6e67f69230217bb663e76b5087", size = 108106, upload-time = "2026-01-11T11:22:34.451Z" },
+    { url = "https://files.pythonhosted.org/packages/de/69/9aa0c6a505c2f80e519b43764f8b4ba93b5a0bbd2d9a9de6e2b24271b9a5/tomli-2.4.0-cp314-cp314t-win_amd64.whl", hash = "sha256:2add28aacc7425117ff6364fe9e06a183bb0251b03f986df0e78e974047571fd", size = 120504, upload-time = "2026-01-11T11:22:35.764Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/9f/f1668c281c58cfae01482f7114a4b88d345e4c140386241a1a24dcc9e7bc/tomli-2.4.0-cp314-cp314t-win_arm64.whl", hash = "sha256:2b1e3b80e1d5e52e40e9b924ec43d81570f0e7d09d11081b797bc4692765a3d4", size = 99561, upload-time = "2026-01-11T11:22:36.624Z" },
+    { url = "https://files.pythonhosted.org/packages/23/d1/136eb2cb77520a31e1f64cbae9d33ec6df0d78bdf4160398e86eec8a8754/tomli-2.4.0-py3-none-any.whl", hash = "sha256:1f776e7d669ebceb01dee46484485f43a4048746235e683bcdffacdf1fb4785a", size = 14477, upload-time = "2026-01-11T11:22:37.446Z" },
+]
+
+[[package]]
+name = "typing-extensions"
+version = "4.15.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/94/1a15dd82efb362ac84269196e94cf00f187f7ed21c242792a923cdb1c61f/typing_extensions-4.15.0.tar.gz", hash = "sha256:0cea48d173cc12fa28ecabc3b837ea3cf6f38c6d1136f85cbaaf598984861466", size = 109391, upload-time = "2025-08-25T13:49:26.313Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl", hash = "sha256:f0fa19c6845758ab08074a0cfa8b7aecb71c999ca73d62883bc25cc018c4e548", size = 44614, upload-time = "2025-08-25T13:49:24.86Z" },
+]
+
+[[package]]
+name = "typing-inspection"
+version = "0.4.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/55/e3/70399cb7dd41c10ac53367ae42139cf4b1ca5f36bb3dc6c9d33acdb43655/typing_inspection-0.4.2.tar.gz", hash = "sha256:ba561c48a67c5958007083d386c3295464928b01faa735ab8547c5692e87f464", size = 75949, upload-time = "2025-10-01T02:14:41.687Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/dc/9b/47798a6c91d8bdb567fe2698fe81e0c6b7cb7ef4d13da4114b41d239f65d/typing_inspection-0.4.2-py3-none-any.whl", hash = "sha256:4ed1cacbdc298c220f1bd249ed5287caa16f34d44ef4e9c3d0cbad5b521545e7", size = 14611, upload-time = "2025-10-01T02:14:40.154Z" },
+]
+
+[[package]]
+name = "uncalled-for"
+version = "0.2.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/02/7c/b5b7d8136f872e3f13b0584e576886de0489d7213a12de6bebf29ff6ebfc/uncalled_for-0.2.0.tar.gz", hash = "sha256:b4f8fdbcec328c5a113807d653e041c5094473dd4afa7c34599ace69ccb7e69f", size = 49488, upload-time = "2026-02-27T17:40:58.137Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ff/7f/4320d9ce3be404e6310b915c3629fe27bf1e2f438a1a7a3cb0396e32e9a9/uncalled_for-0.2.0-py3-none-any.whl", hash = "sha256:2c0bd338faff5f930918f79e7eb9ff48290df2cb05fcc0b40a7f334e55d4d85f", size = 11351, upload-time = "2026-02-27T17:40:56.804Z" },
+]
+
+[[package]]
+name = "uvicorn"
+version = "0.41.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+    { name = "h11" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/32/ce/eeb58ae4ac36fe09e3842eb02e0eb676bf2c53ae062b98f1b2531673efdd/uvicorn-0.41.0.tar.gz", hash = "sha256:09d11cf7008da33113824ee5a1c6422d89fbc2ff476540d69a34c87fab8b571a", size = 82633, upload-time = "2026-02-16T23:07:24.1Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/83/e4/d04a086285c20886c0daad0e026f250869201013d18f81d9ff5eada73a88/uvicorn-0.41.0-py3-none-any.whl", hash = "sha256:29e35b1d2c36a04b9e180d4007ede3bcb32a85fbdfd6c6aeb3f26839de088187", size = 68783, upload-time = "2026-02-16T23:07:22.357Z" },
+]
+
+[[package]]
+name = "watchfiles"
+version = "1.1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c2/c9/8869df9b2a2d6c59d79220a4db37679e74f807c559ffe5265e08b227a210/watchfiles-1.1.1.tar.gz", hash = "sha256:a173cb5c16c4f40ab19cecf48a534c409f7ea983ab8fed0741304a1c0a31b3f2", size = 94440, upload-time = "2025-10-14T15:06:21.08Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a7/1a/206e8cf2dd86fddf939165a57b4df61607a1e0add2785f170a3f616b7d9f/watchfiles-1.1.1-cp310-cp310-macosx_10_12_x86_64.whl", hash = "sha256:eef58232d32daf2ac67f42dea51a2c80f0d03379075d44a587051e63cc2e368c", size = 407318, upload-time = "2025-10-14T15:04:18.753Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/0f/abaf5262b9c496b5dad4ed3c0e799cbecb1f8ea512ecb6ddd46646a9fca3/watchfiles-1.1.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:03fa0f5237118a0c5e496185cafa92878568b652a2e9a9382a5151b1a0380a43", size = 394478, upload-time = "2025-10-14T15:04:20.297Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/04/9cc0ba88697b34b755371f5ace8d3a4d9a15719c07bdc7bd13d7d8c6a341/watchfiles-1.1.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:8ca65483439f9c791897f7db49202301deb6e15fe9f8fe2fed555bf986d10c31", size = 449894, upload-time = "2025-10-14T15:04:21.527Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/9c/eda4615863cd8621e89aed4df680d8c3ec3da6a4cf1da113c17decd87c7f/watchfiles-1.1.1-cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:f0ab1c1af0cb38e3f598244c17919fb1a84d1629cc08355b0074b6d7f53138ac", size = 459065, upload-time = "2025-10-14T15:04:22.795Z" },
+    { url = "https://files.pythonhosted.org/packages/84/13/f28b3f340157d03cbc8197629bc109d1098764abe1e60874622a0be5c112/watchfiles-1.1.1-cp310-cp310-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:3bc570d6c01c206c46deb6e935a260be44f186a2f05179f52f7fcd2be086a94d", size = 488377, upload-time = "2025-10-14T15:04:24.138Z" },
+    { url = "https://files.pythonhosted.org/packages/86/93/cfa597fa9389e122488f7ffdbd6db505b3b915ca7435ecd7542e855898c2/watchfiles-1.1.1-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:e84087b432b6ac94778de547e08611266f1f8ffad28c0ee4c82e028b0fc5966d", size = 595837, upload-time = "2025-10-14T15:04:25.057Z" },
+    { url = "https://files.pythonhosted.org/packages/57/1e/68c1ed5652b48d89fc24d6af905d88ee4f82fa8bc491e2666004e307ded1/watchfiles-1.1.1-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:620bae625f4cb18427b1bb1a2d9426dc0dd5a5ba74c7c2cdb9de405f7b129863", size = 473456, upload-time = "2025-10-14T15:04:26.497Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/dc/1a680b7458ffa3b14bb64878112aefc8f2e4f73c5af763cbf0bd43100658/watchfiles-1.1.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:544364b2b51a9b0c7000a4b4b02f90e9423d97fbbf7e06689236443ebcad81ab", size = 455614, upload-time = "2025-10-14T15:04:27.539Z" },
+    { url = "https://files.pythonhosted.org/packages/61/a5/3d782a666512e01eaa6541a72ebac1d3aae191ff4a31274a66b8dd85760c/watchfiles-1.1.1-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:bbe1ef33d45bc71cf21364df962af171f96ecaeca06bd9e3d0b583efb12aec82", size = 630690, upload-time = "2025-10-14T15:04:28.495Z" },
+    { url = "https://files.pythonhosted.org/packages/9b/73/bb5f38590e34687b2a9c47a244aa4dd50c56a825969c92c9c5fc7387cea1/watchfiles-1.1.1-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:1a0bb430adb19ef49389e1ad368450193a90038b5b752f4ac089ec6942c4dff4", size = 622459, upload-time = "2025-10-14T15:04:29.491Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/ac/c9bb0ec696e07a20bd58af5399aeadaef195fb2c73d26baf55180fe4a942/watchfiles-1.1.1-cp310-cp310-win32.whl", hash = "sha256:3f6d37644155fb5beca5378feb8c1708d5783145f2a0f1c4d5a061a210254844", size = 272663, upload-time = "2025-10-14T15:04:30.435Z" },
+    { url = "https://files.pythonhosted.org/packages/11/a0/a60c5a7c2ec59fa062d9a9c61d02e3b6abd94d32aac2d8344c4bdd033326/watchfiles-1.1.1-cp310-cp310-win_amd64.whl", hash = "sha256:a36d8efe0f290835fd0f33da35042a1bb5dc0e83cbc092dcf69bce442579e88e", size = 287453, upload-time = "2025-10-14T15:04:31.53Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/f8/2c5f479fb531ce2f0564eda479faecf253d886b1ab3630a39b7bf7362d46/watchfiles-1.1.1-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:f57b396167a2565a4e8b5e56a5a1c537571733992b226f4f1197d79e94cf0ae5", size = 406529, upload-time = "2025-10-14T15:04:32.899Z" },
+    { url = "https://files.pythonhosted.org/packages/fe/cd/f515660b1f32f65df671ddf6f85bfaca621aee177712874dc30a97397977/watchfiles-1.1.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:421e29339983e1bebc281fab40d812742268ad057db4aee8c4d2bce0af43b741", size = 394384, upload-time = "2025-10-14T15:04:33.761Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/c3/28b7dc99733eab43fca2d10f55c86e03bd6ab11ca31b802abac26b23d161/watchfiles-1.1.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6e43d39a741e972bab5d8100b5cdacf69db64e34eb19b6e9af162bccf63c5cc6", size = 448789, upload-time = "2025-10-14T15:04:34.679Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/24/33e71113b320030011c8e4316ccca04194bf0cbbaeee207f00cbc7d6b9f5/watchfiles-1.1.1-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:f537afb3276d12814082a2e9b242bdcf416c2e8fd9f799a737990a1dbe906e5b", size = 460521, upload-time = "2025-10-14T15:04:35.963Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/c3/3c9a55f255aa57b91579ae9e98c88704955fa9dac3e5614fb378291155df/watchfiles-1.1.1-cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:b2cd9e04277e756a2e2d2543d65d1e2166d6fd4c9b183f8808634fda23f17b14", size = 488722, upload-time = "2025-10-14T15:04:37.091Z" },
+    { url = "https://files.pythonhosted.org/packages/49/36/506447b73eb46c120169dc1717fe2eff07c234bb3232a7200b5f5bd816e9/watchfiles-1.1.1-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5f3f58818dc0b07f7d9aa7fe9eb1037aecb9700e63e1f6acfed13e9fef648f5d", size = 596088, upload-time = "2025-10-14T15:04:38.39Z" },
+    { url = "https://files.pythonhosted.org/packages/82/ab/5f39e752a9838ec4d52e9b87c1e80f1ee3ccdbe92e183c15b6577ab9de16/watchfiles-1.1.1-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9bb9f66367023ae783551042d31b1d7fd422e8289eedd91f26754a66f44d5cff", size = 472923, upload-time = "2025-10-14T15:04:39.666Z" },
+    { url = "https://files.pythonhosted.org/packages/af/b9/a419292f05e302dea372fa7e6fda5178a92998411f8581b9830d28fb9edb/watchfiles-1.1.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:aebfd0861a83e6c3d1110b78ad54704486555246e542be3e2bb94195eabb2606", size = 456080, upload-time = "2025-10-14T15:04:40.643Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/c3/d5932fd62bde1a30c36e10c409dc5d54506726f08cb3e1d8d0ba5e2bc8db/watchfiles-1.1.1-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:5fac835b4ab3c6487b5dbad78c4b3724e26bcc468e886f8ba8cc4306f68f6701", size = 629432, upload-time = "2025-10-14T15:04:41.789Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/77/16bddd9779fafb795f1a94319dc965209c5641db5bf1edbbccace6d1b3c0/watchfiles-1.1.1-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:399600947b170270e80134ac854e21b3ccdefa11a9529a3decc1327088180f10", size = 623046, upload-time = "2025-10-14T15:04:42.718Z" },
+    { url = "https://files.pythonhosted.org/packages/46/ef/f2ecb9a0f342b4bfad13a2787155c6ee7ce792140eac63a34676a2feeef2/watchfiles-1.1.1-cp311-cp311-win32.whl", hash = "sha256:de6da501c883f58ad50db3a32ad397b09ad29865b5f26f64c24d3e3281685849", size = 271473, upload-time = "2025-10-14T15:04:43.624Z" },
+    { url = "https://files.pythonhosted.org/packages/94/bc/f42d71125f19731ea435c3948cad148d31a64fccde3867e5ba4edee901f9/watchfiles-1.1.1-cp311-cp311-win_amd64.whl", hash = "sha256:35c53bd62a0b885bf653ebf6b700d1bf05debb78ad9292cf2a942b23513dc4c4", size = 287598, upload-time = "2025-10-14T15:04:44.516Z" },
+    { url = "https://files.pythonhosted.org/packages/57/c9/a30f897351f95bbbfb6abcadafbaca711ce1162f4db95fc908c98a9165f3/watchfiles-1.1.1-cp311-cp311-win_arm64.whl", hash = "sha256:57ca5281a8b5e27593cb7d82c2ac927ad88a96ed406aa446f6344e4328208e9e", size = 277210, upload-time = "2025-10-14T15:04:45.883Z" },
+    { url = "https://files.pythonhosted.org/packages/74/d5/f039e7e3c639d9b1d09b07ea412a6806d38123f0508e5f9b48a87b0a76cc/watchfiles-1.1.1-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:8c89f9f2f740a6b7dcc753140dd5e1ab9215966f7a3530d0c0705c83b401bd7d", size = 404745, upload-time = "2025-10-14T15:04:46.731Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/96/a881a13aa1349827490dab2d363c8039527060cfcc2c92cc6d13d1b1049e/watchfiles-1.1.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:bd404be08018c37350f0d6e34676bd1e2889990117a2b90070b3007f172d0610", size = 391769, upload-time = "2025-10-14T15:04:48.003Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/5b/d3b460364aeb8da471c1989238ea0e56bec24b6042a68046adf3d9ddb01c/watchfiles-1.1.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:8526e8f916bb5b9a0a777c8317c23ce65de259422bba5b31325a6fa6029d33af", size = 449374, upload-time = "2025-10-14T15:04:49.179Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/44/5769cb62d4ed055cb17417c0a109a92f007114a4e07f30812a73a4efdb11/watchfiles-1.1.1-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:2edc3553362b1c38d9f06242416a5d8e9fe235c204a4072e988ce2e5bb1f69f6", size = 459485, upload-time = "2025-10-14T15:04:50.155Z" },
+    { url = "https://files.pythonhosted.org/packages/19/0c/286b6301ded2eccd4ffd0041a1b726afda999926cf720aab63adb68a1e36/watchfiles-1.1.1-cp312-cp312-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:30f7da3fb3f2844259cba4720c3fc7138eb0f7b659c38f3bfa65084c7fc7abce", size = 488813, upload-time = "2025-10-14T15:04:51.059Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/2b/8530ed41112dd4a22f4dcfdb5ccf6a1baad1ff6eed8dc5a5f09e7e8c41c7/watchfiles-1.1.1-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:f8979280bdafff686ba5e4d8f97840f929a87ed9cdf133cbbd42f7766774d2aa", size = 594816, upload-time = "2025-10-14T15:04:52.031Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/d2/f5f9fb49489f184f18470d4f99f4e862a4b3e9ac2865688eb2099e3d837a/watchfiles-1.1.1-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:dcc5c24523771db3a294c77d94771abcfcb82a0e0ee8efd910c37c59ec1b31bb", size = 475186, upload-time = "2025-10-14T15:04:53.064Z" },
+    { url = "https://files.pythonhosted.org/packages/cf/68/5707da262a119fb06fbe214d82dd1fe4a6f4af32d2d14de368d0349eb52a/watchfiles-1.1.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1db5d7ae38ff20153d542460752ff397fcf5c96090c1230803713cf3147a6803", size = 456812, upload-time = "2025-10-14T15:04:55.174Z" },
+    { url = "https://files.pythonhosted.org/packages/66/ab/3cbb8756323e8f9b6f9acb9ef4ec26d42b2109bce830cc1f3468df20511d/watchfiles-1.1.1-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:28475ddbde92df1874b6c5c8aaeb24ad5be47a11f87cde5a28ef3835932e3e94", size = 630196, upload-time = "2025-10-14T15:04:56.22Z" },
+    { url = "https://files.pythonhosted.org/packages/78/46/7152ec29b8335f80167928944a94955015a345440f524d2dfe63fc2f437b/watchfiles-1.1.1-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:36193ed342f5b9842edd3532729a2ad55c4160ffcfa3700e0d54be496b70dd43", size = 622657, upload-time = "2025-10-14T15:04:57.521Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/bf/95895e78dd75efe9a7f31733607f384b42eb5feb54bd2eb6ed57cc2e94f4/watchfiles-1.1.1-cp312-cp312-win32.whl", hash = "sha256:859e43a1951717cc8de7f4c77674a6d389b106361585951d9e69572823f311d9", size = 272042, upload-time = "2025-10-14T15:04:59.046Z" },
+    { url = "https://files.pythonhosted.org/packages/87/0a/90eb755f568de2688cb220171c4191df932232c20946966c27a59c400850/watchfiles-1.1.1-cp312-cp312-win_amd64.whl", hash = "sha256:91d4c9a823a8c987cce8fa2690923b069966dabb196dd8d137ea2cede885fde9", size = 288410, upload-time = "2025-10-14T15:05:00.081Z" },
+    { url = "https://files.pythonhosted.org/packages/36/76/f322701530586922fbd6723c4f91ace21364924822a8772c549483abed13/watchfiles-1.1.1-cp312-cp312-win_arm64.whl", hash = "sha256:a625815d4a2bdca61953dbba5a39d60164451ef34c88d751f6c368c3ea73d404", size = 278209, upload-time = "2025-10-14T15:05:01.168Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/f4/f750b29225fe77139f7ae5de89d4949f5a99f934c65a1f1c0b248f26f747/watchfiles-1.1.1-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:130e4876309e8686a5e37dba7d5e9bc77e6ed908266996ca26572437a5271e18", size = 404321, upload-time = "2025-10-14T15:05:02.063Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/f9/f07a295cde762644aa4c4bb0f88921d2d141af45e735b965fb2e87858328/watchfiles-1.1.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:5f3bde70f157f84ece3765b42b4a52c6ac1a50334903c6eaf765362f6ccca88a", size = 391783, upload-time = "2025-10-14T15:05:03.052Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/11/fc2502457e0bea39a5c958d86d2cb69e407a4d00b85735ca724bfa6e0d1a/watchfiles-1.1.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:14e0b1fe858430fc0251737ef3824c54027bedb8c37c38114488b8e131cf8219", size = 449279, upload-time = "2025-10-14T15:05:04.004Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/1f/d66bc15ea0b728df3ed96a539c777acfcad0eb78555ad9efcaa1274688f0/watchfiles-1.1.1-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:f27db948078f3823a6bb3b465180db8ebecf26dd5dae6f6180bd87383b6b4428", size = 459405, upload-time = "2025-10-14T15:05:04.942Z" },
+    { url = "https://files.pythonhosted.org/packages/be/90/9f4a65c0aec3ccf032703e6db02d89a157462fbb2cf20dd415128251cac0/watchfiles-1.1.1-cp313-cp313-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:059098c3a429f62fc98e8ec62b982230ef2c8df68c79e826e37b895bc359a9c0", size = 488976, upload-time = "2025-10-14T15:05:05.905Z" },
+    { url = "https://files.pythonhosted.org/packages/37/57/ee347af605d867f712be7029bb94c8c071732a4b44792e3176fa3c612d39/watchfiles-1.1.1-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:bfb5862016acc9b869bb57284e6cb35fdf8e22fe59f7548858e2f971d045f150", size = 595506, upload-time = "2025-10-14T15:05:06.906Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/78/cc5ab0b86c122047f75e8fc471c67a04dee395daf847d3e59381996c8707/watchfiles-1.1.1-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:319b27255aacd9923b8a276bb14d21a5f7ff82564c744235fc5eae58d95422ae", size = 474936, upload-time = "2025-10-14T15:05:07.906Z" },
+    { url = "https://files.pythonhosted.org/packages/62/da/def65b170a3815af7bd40a3e7010bf6ab53089ef1b75d05dd5385b87cf08/watchfiles-1.1.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:c755367e51db90e75b19454b680903631d41f9e3607fbd941d296a020c2d752d", size = 456147, upload-time = "2025-10-14T15:05:09.138Z" },
+    { url = "https://files.pythonhosted.org/packages/57/99/da6573ba71166e82d288d4df0839128004c67d2778d3b566c138695f5c0b/watchfiles-1.1.1-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:c22c776292a23bfc7237a98f791b9ad3144b02116ff10d820829ce62dff46d0b", size = 630007, upload-time = "2025-10-14T15:05:10.117Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/51/7439c4dd39511368849eb1e53279cd3454b4a4dbace80bab88feeb83c6b5/watchfiles-1.1.1-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:3a476189be23c3686bc2f4321dd501cb329c0a0469e77b7b534ee10129ae6374", size = 622280, upload-time = "2025-10-14T15:05:11.146Z" },
+    { url = "https://files.pythonhosted.org/packages/95/9c/8ed97d4bba5db6fdcdb2b298d3898f2dd5c20f6b73aee04eabe56c59677e/watchfiles-1.1.1-cp313-cp313-win32.whl", hash = "sha256:bf0a91bfb5574a2f7fc223cf95eeea79abfefa404bf1ea5e339c0c1560ae99a0", size = 272056, upload-time = "2025-10-14T15:05:12.156Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/f3/c14e28429f744a260d8ceae18bf58c1d5fa56b50d006a7a9f80e1882cb0d/watchfiles-1.1.1-cp313-cp313-win_amd64.whl", hash = "sha256:52e06553899e11e8074503c8e716d574adeeb7e68913115c4b3653c53f9bae42", size = 288162, upload-time = "2025-10-14T15:05:13.208Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/61/fe0e56c40d5cd29523e398d31153218718c5786b5e636d9ae8ae79453d27/watchfiles-1.1.1-cp313-cp313-win_arm64.whl", hash = "sha256:ac3cc5759570cd02662b15fbcd9d917f7ecd47efe0d6b40474eafd246f91ea18", size = 277909, upload-time = "2025-10-14T15:05:14.49Z" },
+    { url = "https://files.pythonhosted.org/packages/79/42/e0a7d749626f1e28c7108a99fb9bf524b501bbbeb9b261ceecde644d5a07/watchfiles-1.1.1-cp313-cp313t-macosx_10_12_x86_64.whl", hash = "sha256:563b116874a9a7ce6f96f87cd0b94f7faf92d08d0021e837796f0a14318ef8da", size = 403389, upload-time = "2025-10-14T15:05:15.777Z" },
+    { url = "https://files.pythonhosted.org/packages/15/49/08732f90ce0fbbc13913f9f215c689cfc9ced345fb1bcd8829a50007cc8d/watchfiles-1.1.1-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:3ad9fe1dae4ab4212d8c91e80b832425e24f421703b5a42ef2e4a1e215aff051", size = 389964, upload-time = "2025-10-14T15:05:16.85Z" },
+    { url = "https://files.pythonhosted.org/packages/27/0d/7c315d4bd5f2538910491a0393c56bf70d333d51bc5b34bee8e68e8cea19/watchfiles-1.1.1-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ce70f96a46b894b36eba678f153f052967a0d06d5b5a19b336ab0dbbd029f73e", size = 448114, upload-time = "2025-10-14T15:05:17.876Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/24/9e096de47a4d11bc4df41e9d1e61776393eac4cb6eb11b3e23315b78b2cc/watchfiles-1.1.1-cp313-cp313t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:cb467c999c2eff23a6417e58d75e5828716f42ed8289fe6b77a7e5a91036ca70", size = 460264, upload-time = "2025-10-14T15:05:18.962Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/0f/e8dea6375f1d3ba5fcb0b3583e2b493e77379834c74fd5a22d66d85d6540/watchfiles-1.1.1-cp313-cp313t-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:836398932192dae4146c8f6f737d74baeac8b70ce14831a239bdb1ca882fc261", size = 487877, upload-time = "2025-10-14T15:05:20.094Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/5b/df24cfc6424a12deb41503b64d42fbea6b8cb357ec62ca84a5a3476f654a/watchfiles-1.1.1-cp313-cp313t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:743185e7372b7bc7c389e1badcc606931a827112fbbd37f14c537320fca08620", size = 595176, upload-time = "2025-10-14T15:05:21.134Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/b5/853b6757f7347de4e9b37e8cc3289283fb983cba1ab4d2d7144694871d9c/watchfiles-1.1.1-cp313-cp313t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:afaeff7696e0ad9f02cbb8f56365ff4686ab205fcf9c4c5b6fdfaaa16549dd04", size = 473577, upload-time = "2025-10-14T15:05:22.306Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/f7/0a4467be0a56e80447c8529c9fce5b38eab4f513cb3d9bf82e7392a5696b/watchfiles-1.1.1-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:3f7eb7da0eb23aa2ba036d4f616d46906013a68caf61b7fdbe42fc8b25132e77", size = 455425, upload-time = "2025-10-14T15:05:23.348Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/e0/82583485ea00137ddf69bc84a2db88bd92ab4a6e3c405e5fb878ead8d0e7/watchfiles-1.1.1-cp313-cp313t-musllinux_1_1_aarch64.whl", hash = "sha256:831a62658609f0e5c64178211c942ace999517f5770fe9436be4c2faeba0c0ef", size = 628826, upload-time = "2025-10-14T15:05:24.398Z" },
+    { url = "https://files.pythonhosted.org/packages/28/9a/a785356fccf9fae84c0cc90570f11702ae9571036fb25932f1242c82191c/watchfiles-1.1.1-cp313-cp313t-musllinux_1_1_x86_64.whl", hash = "sha256:f9a2ae5c91cecc9edd47e041a930490c31c3afb1f5e6d71de3dc671bfaca02bf", size = 622208, upload-time = "2025-10-14T15:05:25.45Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/f4/0872229324ef69b2c3edec35e84bd57a1289e7d3fe74588048ed8947a323/watchfiles-1.1.1-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:d1715143123baeeaeadec0528bb7441103979a1d5f6fd0e1f915383fea7ea6d5", size = 404315, upload-time = "2025-10-14T15:05:26.501Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/22/16d5331eaed1cb107b873f6ae1b69e9ced582fcf0c59a50cd84f403b1c32/watchfiles-1.1.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:39574d6370c4579d7f5d0ad940ce5b20db0e4117444e39b6d8f99db5676c52fd", size = 390869, upload-time = "2025-10-14T15:05:27.649Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/7e/5643bfff5acb6539b18483128fdc0ef2cccc94a5b8fbda130c823e8ed636/watchfiles-1.1.1-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:7365b92c2e69ee952902e8f70f3ba6360d0d596d9299d55d7d386df84b6941fb", size = 449919, upload-time = "2025-10-14T15:05:28.701Z" },
+    { url = "https://files.pythonhosted.org/packages/51/2e/c410993ba5025a9f9357c376f48976ef0e1b1aefb73b97a5ae01a5972755/watchfiles-1.1.1-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:bfff9740c69c0e4ed32416f013f3c45e2ae42ccedd1167ef2d805c000b6c71a5", size = 460845, upload-time = "2025-10-14T15:05:30.064Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/a4/2df3b404469122e8680f0fcd06079317e48db58a2da2950fb45020947734/watchfiles-1.1.1-cp314-cp314-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:b27cf2eb1dda37b2089e3907d8ea92922b673c0c427886d4edc6b94d8dfe5db3", size = 489027, upload-time = "2025-10-14T15:05:31.064Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/84/4587ba5b1f267167ee715b7f66e6382cca6938e0a4b870adad93e44747e6/watchfiles-1.1.1-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:526e86aced14a65a5b0ec50827c745597c782ff46b571dbfe46192ab9e0b3c33", size = 595615, upload-time = "2025-10-14T15:05:32.074Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/0f/c6988c91d06e93cd0bb3d4a808bcf32375ca1904609835c3031799e3ecae/watchfiles-1.1.1-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:04e78dd0b6352db95507fd8cb46f39d185cf8c74e4cf1e4fbad1d3df96faf510", size = 474836, upload-time = "2025-10-14T15:05:33.209Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/36/ded8aebea91919485b7bbabbd14f5f359326cb5ec218cd67074d1e426d74/watchfiles-1.1.1-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:5c85794a4cfa094714fb9c08d4a218375b2b95b8ed1666e8677c349906246c05", size = 455099, upload-time = "2025-10-14T15:05:34.189Z" },
+    { url = "https://files.pythonhosted.org/packages/98/e0/8c9bdba88af756a2fce230dd365fab2baf927ba42cd47521ee7498fd5211/watchfiles-1.1.1-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:74d5012b7630714b66be7b7b7a78855ef7ad58e8650c73afc4c076a1f480a8d6", size = 630626, upload-time = "2025-10-14T15:05:35.216Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/84/a95db05354bf2d19e438520d92a8ca475e578c647f78f53197f5a2f17aaf/watchfiles-1.1.1-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:8fbe85cb3201c7d380d3d0b90e63d520f15d6afe217165d7f98c9c649654db81", size = 622519, upload-time = "2025-10-14T15:05:36.259Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/ce/d8acdc8de545de995c339be67711e474c77d643555a9bb74a9334252bd55/watchfiles-1.1.1-cp314-cp314-win32.whl", hash = "sha256:3fa0b59c92278b5a7800d3ee7733da9d096d4aabcfabb9a928918bd276ef9b9b", size = 272078, upload-time = "2025-10-14T15:05:37.63Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/c9/a74487f72d0451524be827e8edec251da0cc1fcf111646a511ae752e1a3d/watchfiles-1.1.1-cp314-cp314-win_amd64.whl", hash = "sha256:c2047d0b6cea13b3316bdbafbfa0c4228ae593d995030fda39089d36e64fc03a", size = 287664, upload-time = "2025-10-14T15:05:38.95Z" },
+    { url = "https://files.pythonhosted.org/packages/df/b8/8ac000702cdd496cdce998c6f4ee0ca1f15977bba51bdf07d872ebdfc34c/watchfiles-1.1.1-cp314-cp314-win_arm64.whl", hash = "sha256:842178b126593addc05acf6fce960d28bc5fae7afbaa2c6c1b3a7b9460e5be02", size = 277154, upload-time = "2025-10-14T15:05:39.954Z" },
+    { url = "https://files.pythonhosted.org/packages/47/a8/e3af2184707c29f0f14b1963c0aace6529f9d1b8582d5b99f31bbf42f59e/watchfiles-1.1.1-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:88863fbbc1a7312972f1c511f202eb30866370ebb8493aef2812b9ff28156a21", size = 403820, upload-time = "2025-10-14T15:05:40.932Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/ec/e47e307c2f4bd75f9f9e8afbe3876679b18e1bcec449beca132a1c5ffb2d/watchfiles-1.1.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:55c7475190662e202c08c6c0f4d9e345a29367438cf8e8037f3155e10a88d5a5", size = 390510, upload-time = "2025-10-14T15:05:41.945Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/a0/ad235642118090f66e7b2f18fd5c42082418404a79205cdfca50b6309c13/watchfiles-1.1.1-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3f53fa183d53a1d7a8852277c92b967ae99c2d4dcee2bfacff8868e6e30b15f7", size = 448408, upload-time = "2025-10-14T15:05:43.385Z" },
+    { url = "https://files.pythonhosted.org/packages/df/85/97fa10fd5ff3332ae17e7e40e20784e419e28521549780869f1413742e9d/watchfiles-1.1.1-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:6aae418a8b323732fa89721d86f39ec8f092fc2af67f4217a2b07fd3e93c6101", size = 458968, upload-time = "2025-10-14T15:05:44.404Z" },
+    { url = "https://files.pythonhosted.org/packages/47/c2/9059c2e8966ea5ce678166617a7f75ecba6164375f3b288e50a40dc6d489/watchfiles-1.1.1-cp314-cp314t-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:f096076119da54a6080e8920cbdaac3dbee667eb91dcc5e5b78840b87415bd44", size = 488096, upload-time = "2025-10-14T15:05:45.398Z" },
+    { url = "https://files.pythonhosted.org/packages/94/44/d90a9ec8ac309bc26db808a13e7bfc0e4e78b6fc051078a554e132e80160/watchfiles-1.1.1-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:00485f441d183717038ed2e887a7c868154f216877653121068107b227a2f64c", size = 596040, upload-time = "2025-10-14T15:05:46.502Z" },
+    { url = "https://files.pythonhosted.org/packages/95/68/4e3479b20ca305cfc561db3ed207a8a1c745ee32bf24f2026a129d0ddb6e/watchfiles-1.1.1-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:a55f3e9e493158d7bfdb60a1165035f1cf7d320914e7b7ea83fe22c6023b58fc", size = 473847, upload-time = "2025-10-14T15:05:47.484Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/55/2af26693fd15165c4ff7857e38330e1b61ab8c37d15dc79118cdba115b7a/watchfiles-1.1.1-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8c91ed27800188c2ae96d16e3149f199d62f86c7af5f5f4d2c61a3ed8cd3666c", size = 455072, upload-time = "2025-10-14T15:05:48.928Z" },
+    { url = "https://files.pythonhosted.org/packages/66/1d/d0d200b10c9311ec25d2273f8aad8c3ef7cc7ea11808022501811208a750/watchfiles-1.1.1-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:311ff15a0bae3714ffb603e6ba6dbfba4065ab60865d15a6ec544133bdb21099", size = 629104, upload-time = "2025-10-14T15:05:49.908Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/bd/fa9bb053192491b3867ba07d2343d9f2252e00811567d30ae8d0f78136fe/watchfiles-1.1.1-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:a916a2932da8f8ab582f242c065f5c81bed3462849ca79ee357dd9551b0e9b01", size = 622112, upload-time = "2025-10-14T15:05:50.941Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/4c/a888c91e2e326872fa4705095d64acd8aa2fb9c1f7b9bd0588f33850516c/watchfiles-1.1.1-pp310-pypy310_pp73-macosx_10_12_x86_64.whl", hash = "sha256:17ef139237dfced9da49fb7f2232c86ca9421f666d78c264c7ffca6601d154c3", size = 409611, upload-time = "2025-10-14T15:06:05.809Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/c7/5420d1943c8e3ce1a21c0a9330bcf7edafb6aa65d26b21dbb3267c9e8112/watchfiles-1.1.1-pp310-pypy310_pp73-macosx_11_0_arm64.whl", hash = "sha256:672b8adf25b1a0d35c96b5888b7b18699d27d4194bac8beeae75be4b7a3fc9b2", size = 396889, upload-time = "2025-10-14T15:06:07.035Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/e5/0072cef3804ce8d3aaddbfe7788aadff6b3d3f98a286fdbee9fd74ca59a7/watchfiles-1.1.1-pp310-pypy310_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:77a13aea58bc2b90173bc69f2a90de8e282648939a00a602e1dc4ee23e26b66d", size = 451616, upload-time = "2025-10-14T15:06:08.072Z" },
+    { url = "https://files.pythonhosted.org/packages/83/4e/b87b71cbdfad81ad7e83358b3e447fedd281b880a03d64a760fe0a11fc2e/watchfiles-1.1.1-pp310-pypy310_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0b495de0bb386df6a12b18335a0285dda90260f51bdb505503c02bcd1ce27a8b", size = 458413, upload-time = "2025-10-14T15:06:09.209Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/8e/e500f8b0b77be4ff753ac94dc06b33d8f0d839377fee1b78e8c8d8f031bf/watchfiles-1.1.1-pp311-pypy311_pp73-macosx_10_12_x86_64.whl", hash = "sha256:db476ab59b6765134de1d4fe96a1a9c96ddf091683599be0f26147ea1b2e4b88", size = 408250, upload-time = "2025-10-14T15:06:10.264Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/95/615e72cd27b85b61eec764a5ca51bd94d40b5adea5ff47567d9ebc4d275a/watchfiles-1.1.1-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:89eef07eee5e9d1fda06e38822ad167a044153457e6fd997f8a858ab7564a336", size = 396117, upload-time = "2025-10-14T15:06:11.28Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/81/e7fe958ce8a7fb5c73cc9fb07f5aeaf755e6aa72498c57d760af760c91f8/watchfiles-1.1.1-pp311-pypy311_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ce19e06cbda693e9e7686358af9cd6f5d61312ab8b00488bc36f5aabbaf77e24", size = 450493, upload-time = "2025-10-14T15:06:12.321Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/d4/ed38dd3b1767193de971e694aa544356e63353c33a85d948166b5ff58b9e/watchfiles-1.1.1-pp311-pypy311_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:3e6f39af2eab0118338902798b5aa6664f46ff66bc0280de76fca67a7f262a49", size = 457546, upload-time = "2025-10-14T15:06:13.372Z" },
+]
+
+[[package]]
+name = "websockets"
+version = "16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/04/24/4b2031d72e840ce4c1ccb255f693b15c334757fc50023e4db9537080b8c4/websockets-16.0.tar.gz", hash = "sha256:5f6261a5e56e8d5c42a4497b364ea24d94d9563e8fbd44e78ac40879c60179b5", size = 179346, upload-time = "2026-01-10T09:23:47.181Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/20/74/221f58decd852f4b59cc3354cccaf87e8ef695fede361d03dc9a7396573b/websockets-16.0-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:04cdd5d2d1dacbad0a7bf36ccbcd3ccd5a30ee188f2560b7a62a30d14107b31a", size = 177343, upload-time = "2026-01-10T09:22:21.28Z" },
+    { url = "https://files.pythonhosted.org/packages/19/0f/22ef6107ee52ab7f0b710d55d36f5a5d3ef19e8a205541a6d7ffa7994e5a/websockets-16.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:8ff32bb86522a9e5e31439a58addbb0166f0204d64066fb955265c4e214160f0", size = 175021, upload-time = "2026-01-10T09:22:22.696Z" },
+    { url = "https://files.pythonhosted.org/packages/10/40/904a4cb30d9b61c0e278899bf36342e9b0208eb3c470324a9ecbaac2a30f/websockets-16.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:583b7c42688636f930688d712885cf1531326ee05effd982028212ccc13e5957", size = 175320, upload-time = "2026-01-10T09:22:23.94Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/2f/4b3ca7e106bc608744b1cdae041e005e446124bebb037b18799c2d356864/websockets-16.0-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:7d837379b647c0c4c2355c2499723f82f1635fd2c26510e1f587d89bc2199e72", size = 183815, upload-time = "2026-01-10T09:22:25.469Z" },
+    { url = "https://files.pythonhosted.org/packages/86/26/d40eaa2a46d4302becec8d15b0fc5e45bdde05191e7628405a19cf491ccd/websockets-16.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:df57afc692e517a85e65b72e165356ed1df12386ecb879ad5693be08fac65dde", size = 185054, upload-time = "2026-01-10T09:22:27.101Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/ba/6500a0efc94f7373ee8fefa8c271acdfd4dca8bd49a90d4be7ccabfc397e/websockets-16.0-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:2b9f1e0d69bc60a4a87349d50c09a037a2607918746f07de04df9e43252c77a3", size = 184565, upload-time = "2026-01-10T09:22:28.293Z" },
+    { url = "https://files.pythonhosted.org/packages/04/b4/96bf2cee7c8d8102389374a2616200574f5f01128d1082f44102140344cc/websockets-16.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:335c23addf3d5e6a8633f9f8eda77efad001671e80b95c491dd0924587ece0b3", size = 183848, upload-time = "2026-01-10T09:22:30.394Z" },
+    { url = "https://files.pythonhosted.org/packages/02/8e/81f40fb00fd125357814e8c3025738fc4ffc3da4b6b4a4472a82ba304b41/websockets-16.0-cp310-cp310-win32.whl", hash = "sha256:37b31c1623c6605e4c00d466c9d633f9b812ea430c11c8a278774a1fde1acfa9", size = 178249, upload-time = "2026-01-10T09:22:32.083Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/5f/7e40efe8df57db9b91c88a43690ac66f7b7aa73a11aa6a66b927e44f26fa/websockets-16.0-cp310-cp310-win_amd64.whl", hash = "sha256:8e1dab317b6e77424356e11e99a432b7cb2f3ec8c5ab4dabbcee6add48f72b35", size = 178685, upload-time = "2026-01-10T09:22:33.345Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/db/de907251b4ff46ae804ad0409809504153b3f30984daf82a1d84a9875830/websockets-16.0-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:31a52addea25187bde0797a97d6fc3d2f92b6f72a9370792d65a6e84615ac8a8", size = 177340, upload-time = "2026-01-10T09:22:34.539Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/fa/abe89019d8d8815c8781e90d697dec52523fb8ebe308bf11664e8de1877e/websockets-16.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:417b28978cdccab24f46400586d128366313e8a96312e4b9362a4af504f3bbad", size = 175022, upload-time = "2026-01-10T09:22:36.332Z" },
+    { url = "https://files.pythonhosted.org/packages/58/5d/88ea17ed1ded2079358b40d31d48abe90a73c9e5819dbcde1606e991e2ad/websockets-16.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:af80d74d4edfa3cb9ed973a0a5ba2b2a549371f8a741e0800cb07becdd20f23d", size = 175319, upload-time = "2026-01-10T09:22:37.602Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/ae/0ee92b33087a33632f37a635e11e1d99d429d3d323329675a6022312aac2/websockets-16.0-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:08d7af67b64d29823fed316505a89b86705f2b7981c07848fb5e3ea3020c1abe", size = 184631, upload-time = "2026-01-10T09:22:38.789Z" },
+    { url = "https://files.pythonhosted.org/packages/c8/c5/27178df583b6c5b31b29f526ba2da5e2f864ecc79c99dae630a85d68c304/websockets-16.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7be95cfb0a4dae143eaed2bcba8ac23f4892d8971311f1b06f3c6b78952ee70b", size = 185870, upload-time = "2026-01-10T09:22:39.893Z" },
+    { url = "https://files.pythonhosted.org/packages/87/05/536652aa84ddc1c018dbb7e2c4cbcd0db884580bf8e95aece7593fde526f/websockets-16.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:d6297ce39ce5c2e6feb13c1a996a2ded3b6832155fcfc920265c76f24c7cceb5", size = 185361, upload-time = "2026-01-10T09:22:41.016Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/e2/d5332c90da12b1e01f06fb1b85c50cfc489783076547415bf9f0a659ec19/websockets-16.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:1c1b30e4f497b0b354057f3467f56244c603a79c0d1dafce1d16c283c25f6e64", size = 184615, upload-time = "2026-01-10T09:22:42.442Z" },
+    { url = "https://files.pythonhosted.org/packages/77/fb/d3f9576691cae9253b51555f841bc6600bf0a983a461c79500ace5a5b364/websockets-16.0-cp311-cp311-win32.whl", hash = "sha256:5f451484aeb5cafee1ccf789b1b66f535409d038c56966d6101740c1614b86c6", size = 178246, upload-time = "2026-01-10T09:22:43.654Z" },
+    { url = "https://files.pythonhosted.org/packages/54/67/eaff76b3dbaf18dcddabc3b8c1dba50b483761cccff67793897945b37408/websockets-16.0-cp311-cp311-win_amd64.whl", hash = "sha256:8d7f0659570eefb578dacde98e24fb60af35350193e4f56e11190787bee77dac", size = 178684, upload-time = "2026-01-10T09:22:44.941Z" },
+    { url = "https://files.pythonhosted.org/packages/84/7b/bac442e6b96c9d25092695578dda82403c77936104b5682307bd4deb1ad4/websockets-16.0-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:71c989cbf3254fbd5e84d3bff31e4da39c43f884e64f2551d14bb3c186230f00", size = 177365, upload-time = "2026-01-10T09:22:46.787Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/fe/136ccece61bd690d9c1f715baaeefd953bb2360134de73519d5df19d29ca/websockets-16.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:8b6e209ffee39ff1b6d0fa7bfef6de950c60dfb91b8fcead17da4ee539121a79", size = 175038, upload-time = "2026-01-10T09:22:47.999Z" },
+    { url = "https://files.pythonhosted.org/packages/40/1e/9771421ac2286eaab95b8575b0cb701ae3663abf8b5e1f64f1fd90d0a673/websockets-16.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:86890e837d61574c92a97496d590968b23c2ef0aeb8a9bc9421d174cd378ae39", size = 175328, upload-time = "2026-01-10T09:22:49.809Z" },
+    { url = "https://files.pythonhosted.org/packages/18/29/71729b4671f21e1eaa5d6573031ab810ad2936c8175f03f97f3ff164c802/websockets-16.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:9b5aca38b67492ef518a8ab76851862488a478602229112c4b0d58d63a7a4d5c", size = 184915, upload-time = "2026-01-10T09:22:51.071Z" },
+    { url = "https://files.pythonhosted.org/packages/97/bb/21c36b7dbbafc85d2d480cd65df02a1dc93bf76d97147605a8e27ff9409d/websockets-16.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e0334872c0a37b606418ac52f6ab9cfd17317ac26365f7f65e203e2d0d0d359f", size = 186152, upload-time = "2026-01-10T09:22:52.224Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/34/9bf8df0c0cf88fa7bfe36678dc7b02970c9a7d5e065a3099292db87b1be2/websockets-16.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:a0b31e0b424cc6b5a04b8838bbaec1688834b2383256688cf47eb97412531da1", size = 185583, upload-time = "2026-01-10T09:22:53.443Z" },
+    { url = "https://files.pythonhosted.org/packages/47/88/4dd516068e1a3d6ab3c7c183288404cd424a9a02d585efbac226cb61ff2d/websockets-16.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:485c49116d0af10ac698623c513c1cc01c9446c058a4e61e3bf6c19dff7335a2", size = 184880, upload-time = "2026-01-10T09:22:55.033Z" },
+    { url = "https://files.pythonhosted.org/packages/91/d6/7d4553ad4bf1c0421e1ebd4b18de5d9098383b5caa1d937b63df8d04b565/websockets-16.0-cp312-cp312-win32.whl", hash = "sha256:eaded469f5e5b7294e2bdca0ab06becb6756ea86894a47806456089298813c89", size = 178261, upload-time = "2026-01-10T09:22:56.251Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/f0/f3a17365441ed1c27f850a80b2bc680a0fa9505d733fe152fdf5e98c1c0b/websockets-16.0-cp312-cp312-win_amd64.whl", hash = "sha256:5569417dc80977fc8c2d43a86f78e0a5a22fee17565d78621b6bb264a115d4ea", size = 178693, upload-time = "2026-01-10T09:22:57.478Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/9c/baa8456050d1c1b08dd0ec7346026668cbc6f145ab4e314d707bb845bf0d/websockets-16.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:878b336ac47938b474c8f982ac2f7266a540adc3fa4ad74ae96fea9823a02cc9", size = 177364, upload-time = "2026-01-10T09:22:59.333Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/0c/8811fc53e9bcff68fe7de2bcbe75116a8d959ac699a3200f4847a8925210/websockets-16.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:52a0fec0e6c8d9a784c2c78276a48a2bdf099e4ccc2a4cad53b27718dbfd0230", size = 175039, upload-time = "2026-01-10T09:23:01.171Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/82/39a5f910cb99ec0b59e482971238c845af9220d3ab9fa76dd9162cda9d62/websockets-16.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:e6578ed5b6981005df1860a56e3617f14a6c307e6a71b4fff8c48fdc50f3ed2c", size = 175323, upload-time = "2026-01-10T09:23:02.341Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/28/0a25ee5342eb5d5f297d992a77e56892ecb65e7854c7898fb7d35e9b33bd/websockets-16.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:95724e638f0f9c350bb1c2b0a7ad0e83d9cc0c9259f3ea94e40d7b02a2179ae5", size = 184975, upload-time = "2026-01-10T09:23:03.756Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/66/27ea52741752f5107c2e41fda05e8395a682a1e11c4e592a809a90c6a506/websockets-16.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c0204dc62a89dc9d50d682412c10b3542d748260d743500a85c13cd1ee4bde82", size = 186203, upload-time = "2026-01-10T09:23:05.01Z" },
+    { url = "https://files.pythonhosted.org/packages/37/e5/8e32857371406a757816a2b471939d51c463509be73fa538216ea52b792a/websockets-16.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:52ac480f44d32970d66763115edea932f1c5b1312de36df06d6b219f6741eed8", size = 185653, upload-time = "2026-01-10T09:23:06.301Z" },
+    { url = "https://files.pythonhosted.org/packages/9b/67/f926bac29882894669368dc73f4da900fcdf47955d0a0185d60103df5737/websockets-16.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:6e5a82b677f8f6f59e8dfc34ec06ca6b5b48bc4fcda346acd093694cc2c24d8f", size = 184920, upload-time = "2026-01-10T09:23:07.492Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/a1/3d6ccdcd125b0a42a311bcd15a7f705d688f73b2a22d8cf1c0875d35d34a/websockets-16.0-cp313-cp313-win32.whl", hash = "sha256:abf050a199613f64c886ea10f38b47770a65154dc37181bfaff70c160f45315a", size = 178255, upload-time = "2026-01-10T09:23:09.245Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/ae/90366304d7c2ce80f9b826096a9e9048b4bb760e44d3b873bb272cba696b/websockets-16.0-cp313-cp313-win_amd64.whl", hash = "sha256:3425ac5cf448801335d6fdc7ae1eb22072055417a96cc6b31b3861f455fbc156", size = 178689, upload-time = "2026-01-10T09:23:10.483Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/1d/e88022630271f5bd349ed82417136281931e558d628dd52c4d8621b4a0b2/websockets-16.0-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:8cc451a50f2aee53042ac52d2d053d08bf89bcb31ae799cb4487587661c038a0", size = 177406, upload-time = "2026-01-10T09:23:12.178Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/78/e63be1bf0724eeb4616efb1ae1c9044f7c3953b7957799abb5915bffd38e/websockets-16.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:daa3b6ff70a9241cf6c7fc9e949d41232d9d7d26fd3522b1ad2b4d62487e9904", size = 175085, upload-time = "2026-01-10T09:23:13.511Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/f4/d3c9220d818ee955ae390cf319a7c7a467beceb24f05ee7aaaa2414345ba/websockets-16.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:fd3cb4adb94a2a6e2b7c0d8d05cb94e6f1c81a0cf9dc2694fb65c7e8d94c42e4", size = 175328, upload-time = "2026-01-10T09:23:14.727Z" },
+    { url = "https://files.pythonhosted.org/packages/63/bc/d3e208028de777087e6fb2b122051a6ff7bbcca0d6df9d9c2bf1dd869ae9/websockets-16.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:781caf5e8eee67f663126490c2f96f40906594cb86b408a703630f95550a8c3e", size = 185044, upload-time = "2026-01-10T09:23:15.939Z" },
+    { url = "https://files.pythonhosted.org/packages/ad/6e/9a0927ac24bd33a0a9af834d89e0abc7cfd8e13bed17a86407a66773cc0e/websockets-16.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:caab51a72c51973ca21fa8a18bd8165e1a0183f1ac7066a182ff27107b71e1a4", size = 186279, upload-time = "2026-01-10T09:23:17.148Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/ca/bf1c68440d7a868180e11be653c85959502efd3a709323230314fda6e0b3/websockets-16.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:19c4dc84098e523fd63711e563077d39e90ec6702aff4b5d9e344a60cb3c0cb1", size = 185711, upload-time = "2026-01-10T09:23:18.372Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/f8/fdc34643a989561f217bb477cbc47a3a07212cbda91c0e4389c43c296ebf/websockets-16.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:a5e18a238a2b2249c9a9235466b90e96ae4795672598a58772dd806edc7ac6d3", size = 184982, upload-time = "2026-01-10T09:23:19.652Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/d1/574fa27e233764dbac9c52730d63fcf2823b16f0856b3329fc6268d6ae4f/websockets-16.0-cp314-cp314-win32.whl", hash = "sha256:a069d734c4a043182729edd3e9f247c3b2a4035415a9172fd0f1b71658a320a8", size = 177915, upload-time = "2026-01-10T09:23:21.458Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/f1/ae6b937bf3126b5134ce1f482365fde31a357c784ac51852978768b5eff4/websockets-16.0-cp314-cp314-win_amd64.whl", hash = "sha256:c0ee0e63f23914732c6d7e0cce24915c48f3f1512ec1d079ed01fc629dab269d", size = 178381, upload-time = "2026-01-10T09:23:22.715Z" },
+    { url = "https://files.pythonhosted.org/packages/06/9b/f791d1db48403e1f0a27577a6beb37afae94254a8c6f08be4a23e4930bc0/websockets-16.0-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:a35539cacc3febb22b8f4d4a99cc79b104226a756aa7400adc722e83b0d03244", size = 177737, upload-time = "2026-01-10T09:23:24.523Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/40/53ad02341fa33b3ce489023f635367a4ac98b73570102ad2cdd770dacc9a/websockets-16.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:b784ca5de850f4ce93ec85d3269d24d4c82f22b7212023c974c401d4980ebc5e", size = 175268, upload-time = "2026-01-10T09:23:25.781Z" },
+    { url = "https://files.pythonhosted.org/packages/74/9b/6158d4e459b984f949dcbbb0c5d270154c7618e11c01029b9bbd1bb4c4f9/websockets-16.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:569d01a4e7fba956c5ae4fc988f0d4e187900f5497ce46339c996dbf24f17641", size = 175486, upload-time = "2026-01-10T09:23:27.033Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/2d/7583b30208b639c8090206f95073646c2c9ffd66f44df967981a64f849ad/websockets-16.0-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:50f23cdd8343b984957e4077839841146f67a3d31ab0d00e6b824e74c5b2f6e8", size = 185331, upload-time = "2026-01-10T09:23:28.259Z" },
+    { url = "https://files.pythonhosted.org/packages/45/b0/cce3784eb519b7b5ad680d14b9673a31ab8dcb7aad8b64d81709d2430aa8/websockets-16.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:152284a83a00c59b759697b7f9e9cddf4e3c7861dd0d964b472b70f78f89e80e", size = 186501, upload-time = "2026-01-10T09:23:29.449Z" },
+    { url = "https://files.pythonhosted.org/packages/19/60/b8ebe4c7e89fb5f6cdf080623c9d92789a53636950f7abacfc33fe2b3135/websockets-16.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:bc59589ab64b0022385f429b94697348a6a234e8ce22544e3681b2e9331b5944", size = 186062, upload-time = "2026-01-10T09:23:31.368Z" },
+    { url = "https://files.pythonhosted.org/packages/88/a8/a080593f89b0138b6cba1b28f8df5673b5506f72879322288b031337c0b8/websockets-16.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:32da954ffa2814258030e5a57bc73a3635463238e797c7375dc8091327434206", size = 185356, upload-time = "2026-01-10T09:23:32.627Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/b6/b9afed2afadddaf5ebb2afa801abf4b0868f42f8539bfe4b071b5266c9fe/websockets-16.0-cp314-cp314t-win32.whl", hash = "sha256:5a4b4cc550cb665dd8a47f868c8d04c8230f857363ad3c9caf7a0c3bf8c61ca6", size = 178085, upload-time = "2026-01-10T09:23:33.816Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/3e/28135a24e384493fa804216b79a6a6759a38cc4ff59118787b9fb693df93/websockets-16.0-cp314-cp314t-win_amd64.whl", hash = "sha256:b14dc141ed6d2dde437cddb216004bcac6a1df0935d79656387bd41632ba0bbd", size = 178531, upload-time = "2026-01-10T09:23:35.016Z" },
+    { url = "https://files.pythonhosted.org/packages/72/07/c98a68571dcf256e74f1f816b8cc5eae6eb2d3d5cfa44d37f801619d9166/websockets-16.0-pp311-pypy311_pp73-macosx_10_15_x86_64.whl", hash = "sha256:349f83cd6c9a415428ee1005cadb5c2c56f4389bc06a9af16103c3bc3dcc8b7d", size = 174947, upload-time = "2026-01-10T09:23:36.166Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/52/93e166a81e0305b33fe416338be92ae863563fe7bce446b0f687b9df5aea/websockets-16.0-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:4a1aba3340a8dca8db6eb5a7986157f52eb9e436b74813764241981ca4888f03", size = 175260, upload-time = "2026-01-10T09:23:37.409Z" },
+    { url = "https://files.pythonhosted.org/packages/56/0c/2dbf513bafd24889d33de2ff0368190a0e69f37bcfa19009ef819fe4d507/websockets-16.0-pp311-pypy311_pp73-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:f4a32d1bd841d4bcbffdcb3d2ce50c09c3909fbead375ab28d0181af89fd04da", size = 176071, upload-time = "2026-01-10T09:23:39.158Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/8f/aea9c71cc92bf9b6cc0f7f70df8f0b420636b6c96ef4feee1e16f80f75dd/websockets-16.0-pp311-pypy311_pp73-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0298d07ee155e2e9fda5be8a9042200dd2e3bb0b8a38482156576f863a9d457c", size = 176968, upload-time = "2026-01-10T09:23:41.031Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/3f/f70e03f40ffc9a30d817eef7da1be72ee4956ba8d7255c399a01b135902a/websockets-16.0-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:a653aea902e0324b52f1613332ddf50b00c06fdaf7e92624fbf8c77c78fa5767", size = 178735, upload-time = "2026-01-10T09:23:42.259Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/28/258ebab549c2bf3e64d2b0217b973467394a9cea8c42f70418ca2c5d0d2e/websockets-16.0-py3-none-any.whl", hash = "sha256:1637db62fad1dc833276dded54215f2c7fa46912301a24bd94d45d46a011ceec", size = 171598, upload-time = "2026-01-10T09:23:45.395Z" },
+]
+
+[[package]]
+name = "zipp"
+version = "3.23.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e3/02/0f2892c661036d50ede074e376733dca2ae7c6eb617489437771209d4180/zipp-3.23.0.tar.gz", hash = "sha256:a07157588a12518c9d4034df3fbbee09c814741a33ff63c05fa29d26a2404166", size = 25547, upload-time = "2025-06-08T17:06:39.4Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2e/54/647ade08bf0db230bfea292f893923872fd20be6ac6f53b2b936ba839d75/zipp-3.23.0-py3-none-any.whl", hash = "sha256:071652d6115ed432f5ce1d34c336c0adfd6a884660d1e9712a256d3d3bd4b14e", size = 10276, upload-time = "2025-06-08T17:06:38.034Z" },
+]
diff --git a/examples/text_me.py b/examples/text_me.py
new file mode 100644
index 0000000..f45cca6
--- /dev/null
+++ b/examples/text_me.py
@@ -0,0 +1,72 @@
+# /// script
+# dependencies = ["fastmcp"]
+# ///
+
+"""
+FastMCP Text Me Server
+--------------------------------
+This defines a simple FastMCP server that sends a text message to a phone number via https://surgemsg.com/.
+
+To run this example, create a `.env` file with the following values:
+
+SURGE_API_KEY=...
+SURGE_ACCOUNT_ID=...
+SURGE_MY_PHONE_NUMBER=...
+SURGE_MY_FIRST_NAME=...
+SURGE_MY_LAST_NAME=...
+
+Visit https://surgemsg.com/ and click "Get Started" to obtain these values.
+"""
+
+from typing import Annotated
+
+import httpx
+from pydantic import BeforeValidator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from fastmcp import FastMCP
+
+
+class SurgeSettings(BaseSettings):
+    model_config: SettingsConfigDict = SettingsConfigDict(
+        env_prefix="SURGE_", env_file=".env"
+    )
+
+    api_key: str
+    account_id: str
+    my_phone_number: Annotated[
+        str, BeforeValidator(lambda v: "+" + v if not v.startswith("+") else v)
+    ]
+    my_first_name: str
+    my_last_name: str
+
+
+# Create server
+mcp = FastMCP("Text me")
+surge_settings = SurgeSettings()  # type: ignore
+
+
+@mcp.tool(name="textme", description="Send a text message to me")
+def text_me(text_content: str) -> str:
+    """Send a text message to a phone number via https://surgemsg.com/"""
+    with httpx.Client() as client:
+        response = client.post(
+            "https://api.surgemsg.com/messages",
+            headers={
+                "Authorization": f"Bearer {surge_settings.api_key}",
+                "Surge-Account": surge_settings.account_id,
+                "Content-Type": "application/json",
+            },
+            json={
+                "body": text_content,
+                "conversation": {
+                    "contact": {
+                        "first_name": surge_settings.my_first_name,
+                        "last_name": surge_settings.my_last_name,
+                        "phone_number": surge_settings.my_phone_number,
+                    }
+                },
+            },
+        )
+        response.raise_for_status()
+        return f"Message sent: {text_content}"
diff --git a/examples/tool_result_echo.py b/examples/tool_result_echo.py
new file mode 100644
index 0000000..bd1185f
--- /dev/null
+++ b/examples/tool_result_echo.py
@@ -0,0 +1,41 @@
+"""
+FastMCP Echo Server with Metadata
+
+Demonstrates how to return metadata alongside content and structured data.
+The meta field can include execution details, versioning, or other information
+that clients may find useful.
+"""
+
+import time
+from dataclasses import dataclass
+
+from fastmcp import FastMCP
+from fastmcp.tools.tool import ToolResult
+
+mcp = FastMCP("Echo Server")
+
+
+@dataclass
+class EchoData:
+    data: str
+    length: int
+
+
+@mcp.tool
+def echo(text: str) -> ToolResult:
+    """Echo text back with metadata about the operation."""
+    start = time.perf_counter()
+
+    result = EchoData(data=text, length=len(text))
+
+    execution_time = (time.perf_counter() - start) * 1000
+
+    return ToolResult(
+        content=f"Echoed: {text}",
+        structured_content=result,
+        meta={
+            "execution_time_ms": round(execution_time, 2),
+            "character_count": len(text),
+            "word_count": len(text.split()),
+        },
+    )
diff --git a/examples/versioning/client_version_selection.py b/examples/versioning/client_version_selection.py
new file mode 100644
index 0000000..0d5519a
--- /dev/null
+++ b/examples/versioning/client_version_selection.py
@@ -0,0 +1,81 @@
+"""
+Client-Side Version Selection
+
+Discover available versions via metadata and request specific versions
+when calling tools, prompts, or resources.
+
+Run: uv run python examples/versioning/client_version_selection.py
+"""
+
+import asyncio
+
+from rich import print
+
+from fastmcp import Client, FastMCP
+from fastmcp.exceptions import ToolError
+
+mcp = FastMCP("Payment API")
+
+
+@mcp.tool(version="1.0")
+def charge(amount: int, currency: str = "USD") -> dict:
+    """Charge a payment (v1.0 - basic)."""
+    return {"status": "charged", "amount": amount, "currency": currency}
+
+
+@mcp.tool(version="1.1")
+def charge(  # noqa: F811
+    amount: int, currency: str = "USD", idempotency_key: str | None = None
+) -> dict:
+    """Charge a payment (v1.1 - added idempotency)."""
+    return {"status": "charged", "amount": amount, "idempotency_key": idempotency_key}
+
+
+@mcp.tool(version="2.0")
+def charge(  # noqa: F811
+    amount: int,
+    currency: str = "USD",
+    idempotency_key: str | None = None,
+    metadata: dict | None = None,
+) -> dict:
+    """Charge a payment (v2.0 - added metadata)."""
+    return {"status": "charged", "amount": amount, "metadata": metadata or {}}
+
+
+async def main():
+    async with Client(mcp) as client:
+        # Discover versions via metadata
+        tools = await client.list_tools()
+        tool = tools[0]
+        meta = tool.meta.get("fastmcp", {})
+
+        print(f"[bold]{tool.name}[/]")
+        print(f"  Current version: [green]{meta.get('version')}[/]")
+        print(f"  All versions:    {meta.get('versions')}")
+
+        # Call specific versions
+        print("\n[bold]Calling specific versions:[/]")
+
+        r1 = await client.call_tool("charge", {"amount": 100}, version="1.0")
+        print(f"  v1.0: {r1.data}")
+
+        r1_1 = await client.call_tool(
+            "charge", {"amount": 100, "idempotency_key": "abc"}, version="1.1"
+        )
+        print(f"  v1.1: {r1_1.data}")
+
+        r2 = await client.call_tool(
+            "charge", {"amount": 100, "metadata": {"order": "xyz"}}, version="2.0"
+        )
+        print(f"  v2.0: {r2.data}")
+
+        # Handle missing versions
+        print("\n[bold]Missing version:[/]")
+        try:
+            await client.call_tool("charge", {"amount": 100}, version="99.0")
+        except ToolError as e:
+            print(f"  [red]ToolError:[/] {e}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/versioning/version_filters.py b/examples/versioning/version_filters.py
new file mode 100644
index 0000000..896164d
--- /dev/null
+++ b/examples/versioning/version_filters.py
@@ -0,0 +1,91 @@
+"""
+Version Filters for API Surfaces
+
+Use VersionFilter to create distinct API surfaces from shared components.
+This lets you serve v1, v2, v3 APIs from a single codebase.
+
+Run: uv run python examples/versioning/version_filters.py
+"""
+
+import asyncio
+
+from rich import print
+from rich.table import Table
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.providers import LocalProvider
+from fastmcp.server.transforms import VersionFilter
+
+# Shared component pool with all versions
+components = LocalProvider()
+
+
+@components.tool(version="1.0")
+def process(data: str) -> str:
+    """Process data (v1 - uppercase only)."""
+    return data.upper()
+
+
+@components.tool(version="2.0")
+def process(data: str, mode: str = "upper") -> str:  # noqa: F811
+    """Process data (v2 - with mode selection)."""
+    return data.lower() if mode == "lower" else data.upper()
+
+
+@components.tool(version="3.0")
+def process(data: str, mode: str = "upper", repeat: int = 1) -> str:  # noqa: F811
+    """Process data (v3 - with repeat)."""
+    result = data.lower() if mode == "lower" else data.upper()
+    return result * repeat
+
+
+# Unversioned components pass through all filters
+@components.tool()
+def health() -> str:
+    """Health check (always available)."""
+    return "ok"
+
+
+# Create filtered API surfaces
+api_v1 = FastMCP("API v1", providers=[components])
+api_v1.add_transform(VersionFilter(version_lt="2.0"))
+
+api_v2 = FastMCP("API v2", providers=[components])
+api_v2.add_transform(VersionFilter(version_gte="2.0", version_lt="3.0"))
+
+api_v3 = FastMCP("API v3", providers=[components])
+api_v3.add_transform(VersionFilter(version_gte="3.0"))
+
+
+async def show_surface(name: str, server: FastMCP):
+    """Show what's visible through a filtered server."""
+    async with Client(server) as client:
+        tools = await client.list_tools()
+
+        table = Table(title=name)
+        table.add_column("Tool")
+        table.add_column("Version", style="green")
+
+        for tool in tools:
+            meta = tool.meta.get("fastmcp", {}) if tool.meta else {}
+            table.add_row(tool.name, meta.get("version", "(unversioned)"))
+
+        print(table)
+
+
+async def main():
+    # Show what each API surface exposes
+    await show_surface("API v1 (version_lt='2.0')", api_v1)
+    await show_surface("API v2 (version_gte='2.0', version_lt='3.0')", api_v2)
+    await show_surface("API v3 (version_gte='3.0')", api_v3)
+
+    # Same tool name, different behavior per API
+    print("\n[bold]Same call through different APIs:[/]")
+    for name, server in [("v1", api_v1), ("v2", api_v2), ("v3", api_v3)]:
+        async with Client(server) as client:
+            result = await client.call_tool("process", {"data": "Hello"})
+            print(f"  API {name}: process('Hello') -> '{result.data}'")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/versioning/versioned_components.py b/examples/versioning/versioned_components.py
new file mode 100644
index 0000000..5f53e3c
--- /dev/null
+++ b/examples/versioning/versioned_components.py
@@ -0,0 +1,101 @@
+"""
+Creating Versioned Components
+
+Register multiple versions of the same tool, resource, or prompt.
+Clients see the highest version by default but can request specific versions.
+
+Run: uv run python examples/versioning/versioned_components.py
+"""
+
+import asyncio
+
+from rich import print
+from rich.table import Table
+
+from fastmcp import Client, FastMCP
+
+mcp = FastMCP("Versioned API")
+
+
+# --- Versioned Tools ---
+# Same name, different versions with different signatures
+
+
+@mcp.tool(version="1.0")
+def calculate(x: int, y: int) -> int:
+    """Add two numbers (v1.0)."""
+    return x + y
+
+
+@mcp.tool(version="2.0")
+def calculate(x: int, y: int, z: int = 0) -> int:  # noqa: F811
+    """Add two or three numbers (v2.0)."""
+    return x + y + z
+
+
+# --- Versioned Resources ---
+# Same URI, different content per version
+
+
+@mcp.resource("config://app", version="1.0")
+def config_v1() -> str:
+    return '{"format": "legacy"}'
+
+
+@mcp.resource("config://app", version="2.0")
+def config_v2() -> str:
+    return '{"format": "modern", "telemetry": true}'
+
+
+# --- Versioned Prompts ---
+# Same prompt, different templates per version
+
+
+@mcp.prompt(version="1.0")
+def summarize(text: str) -> str:
+    return f"Summarize: {text}"
+
+
+@mcp.prompt(version="2.0")
+def summarize(text: str, style: str = "concise") -> str:  # noqa: F811
+    return f"Summarize in a {style} style: {text}"
+
+
+async def main():
+    async with Client(mcp) as client:
+        # List components - clients see highest version + all available versions
+        tools = await client.list_tools()
+
+        table = Table(title="Components (as seen by clients)")
+        table.add_column("Type")
+        table.add_column("Name")
+        table.add_column("Version", style="green")
+        table.add_column("All Versions", style="dim")
+
+        for tool in tools:
+            meta = tool.meta.get("fastmcp", {}) if tool.meta else {}
+            table.add_row(
+                "Tool",
+                tool.name,
+                meta.get("version"),
+                ", ".join(meta.get("versions", [])),
+            )
+
+        print(table)
+
+        # Call specific versions
+        print("\n[bold]Calling specific versions:[/]")
+
+        r_default = await client.call_tool("calculate", {"x": 5, "y": 3})
+        r_v1 = await client.call_tool("calculate", {"x": 5, "y": 3}, version="1.0")
+        r_v2 = await client.call_tool(
+            "calculate", {"x": 5, "y": 3, "z": 2}, version="2.0"
+        )
+
+        print(f"  calculate(5, 3)          -> {r_default.data}  (default: highest)")
+        print(f"  calculate(5, 3) v1.0     -> {r_v1.data}")
+        print(f"  calculate(5, 3, 2) v2.0  -> {r_v2.data}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/fastmcp_remote/README.md b/fastmcp_remote/README.md
new file mode 100644
index 0000000..7f576eb
--- /dev/null
+++ b/fastmcp_remote/README.md
@@ -0,0 +1,105 @@
+# fastmcp-remote
+
+`fastmcp-remote` is FastMCP's standalone Python stdio bridge for remote MCP servers. It lets MCP clients that launch local stdio processes connect to MCP servers hosted over Streamable HTTP or SSE.
+
+```json
+{
+  "mcpServers": {
+    "linear": {
+      "command": "uvx",
+      "args": ["fastmcp-remote", "https://mcp.linear.app/mcp"]
+    }
+  }
+}
+```
+
+The CLI is powered by [FastMCP](https://gofastmcp.com). Its command shape is inspired by the original [`mcp-remote`](https://github.com/geelen/mcp-remote) npm project, which established the stdio-to-remote bridge pattern used across the MCP ecosystem.
+
+`fastmcp-remote` is intentionally smaller than the general FastMCP CLI. It does not load Python files, discover local MCP configs, prepare project environments, or run development reload loops. It builds one FastMCP client for the URL you provide, exposes that client as a local stdio proxy, and leaves the rest alone.
+
+## Usage
+
+Run a remote MCP server through a local stdio bridge:
+
+```bash
+uvx fastmcp-remote https://example.com/mcp
+```
+
+Use the full MCP endpoint URL for the remote server. Many FastMCP HTTP servers expose MCP at `/mcp`, so a local development server may need `http://localhost:8000/mcp` rather than `http://localhost:8000`.
+
+`fastmcp-remote` starts a local stdio bridge, then connects to the upstream server when the MCP host initializes that bridge. If the upstream server is unavailable, the URL does not point to an MCP endpoint, or authentication cannot complete, initialization fails and the host should report the remote server as failed.
+
+For authenticated MCP servers, OAuth is enabled automatically. To pass a bearer token or other custom header instead, provide a header. The header name ends at the first colon, so values can contain additional colons. Quote the header when the value contains spaces, just like any other shell argument:
+
+```bash
+uvx fastmcp-remote https://example.com/mcp \
+  --header "Authorization: Bearer <token>"
+```
+
+Repeat `--header` to send multiple headers. Header values use `Name: Value` format:
+
+```bash
+uvx fastmcp-remote https://example.com/mcp \
+  --header "Authorization: Bearer <token>" \
+  --header "X-Workspace: production" \
+  --header "X-Client-Name: My MCP Host" \
+  --header "X-Callback-Url: https://example.com/oauth/callback"
+```
+
+Some MCP hosts on Windows have trouble preserving spaces inside command arguments. Put the spaced value in an environment variable and reference it from the header value:
+
+```json
+{
+  "mcpServers": {
+    "remote-api": {
+      "command": "uvx",
+      "args": [
+        "fastmcp-remote",
+        "https://example.com/mcp",
+        "--header",
+        "Authorization:${AUTH_HEADER}"
+      ],
+      "env": {
+        "AUTH_HEADER": "Bearer <token>"
+      }
+    }
+  }
+}
+```
+
+Use `--auth none` for unauthenticated development servers:
+
+```bash
+uvx fastmcp-remote http://localhost:8000/mcp --auth none
+```
+
+For servers behind a self-signed certificate, point `--verify` at a CA bundle that trusts the certificate:
+
+```bash
+uvx fastmcp-remote https://internal.example.com/mcp --verify /path/to/ca-bundle.pem
+```
+
+To disable certificate verification entirely (insecure, only for trusted private networks), pass `--verify false`:
+
+```bash
+uvx fastmcp-remote https://internal.example.com/mcp --verify false
+```
+
+A CA bundle can also be supplied through the standard `SSL_CERT_FILE` environment variable, which OpenSSL reads automatically:
+
+```bash
+SSL_CERT_FILE=/path/to/ca-bundle.pem uvx fastmcp-remote https://internal.example.com/mcp
+```
+
+## Options
+
+- `--transport`: Choose `http` or `sse`. Defaults to `http`.
+- `--header`: Add a header to upstream requests, for example `--header "Authorization: Bearer <token>"`. Values may contain colons. Quote headers whose values contain spaces. Use `${VAR}` to expand environment variables inside values. Repeat for multiple headers.
+- `--resource`: Isolate OAuth token storage for a named remote resource.
+- `--host`: Set the OAuth callback hostname. Defaults to `localhost`.
+- `--auth-timeout`: Set how long to wait for the OAuth callback. Defaults to 300 seconds.
+- `--ignore-tool`: Hide tools whose names match a glob pattern.
+- `--auth`: Choose `oauth` or `none`. The default uses OAuth unless an `Authorization` header is provided.
+- `--verify`: Control TLS certificate verification. Pass a path to a CA bundle to trust a self-signed certificate, or `false` to disable verification (insecure). Defaults to verification enabled.
+
+OAuth tokens are stored under `~/.fastmcp/remote` by default. Set `FASTMCP_REMOTE_CONFIG_DIR` to use another directory.
diff --git a/fastmcp_remote/fastmcp_remote/__init__.py b/fastmcp_remote/fastmcp_remote/__init__.py
new file mode 100644
index 0000000..a8af334
--- /dev/null
+++ b/fastmcp_remote/fastmcp_remote/__init__.py
@@ -0,0 +1,10 @@
+"""Python stdio bridge for remote MCP servers."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("fastmcp-remote")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]
diff --git a/fastmcp_remote/fastmcp_remote/cli.py b/fastmcp_remote/fastmcp_remote/cli.py
new file mode 100644
index 0000000..6c917ee
--- /dev/null
+++ b/fastmcp_remote/fastmcp_remote/cli.py
@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import hashlib
+import os
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+from urllib.parse import urlparse
+
+import anyio
+from key_value.aio.protocols import AsyncKeyValue
+from key_value.aio.stores.filetree import (
+    FileTreeStore,
+    FileTreeV1CollectionSanitizationStrategy,
+    FileTreeV1KeySanitizationStrategy,
+)
+
+from fastmcp import Client
+from fastmcp.client.auth import OAuth
+from fastmcp.client.transports import SSETransport, StreamableHttpTransport
+from fastmcp.server import create_proxy
+from fastmcp.server.transforms import GetToolNext, Transform
+from fastmcp.tools import Tool
+from fastmcp.utilities.versions import VersionSpec
+
+RemoteTransport = Literal["http", "sse"]
+AuthMode = Literal["oauth", "none"]
+ENV_VAR_PATTERN = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+@dataclass(frozen=True)
+class RemoteConfig:
+    url: str
+    headers: dict[str, str]
+    transport: RemoteTransport
+    auth: AuthMode | None
+    callback_port: int | None
+    callback_host: str
+    callback_timeout: float
+    storage_dir: Path
+    ignore_tools: tuple[str, ...]
+    show_banner: bool
+    log_level: str | None
+    verify: bool | str | None
+
+
+class IgnoreTools(Transform):
+    def __init__(self, patterns: Sequence[str]) -> None:
+        self.patterns = tuple(patterns)
+
+    def _matches(self, name: str) -> bool:
+        return any(fnmatch.fnmatchcase(name, pattern) for pattern in self.patterns)
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        return [tool for tool in tools if not self._matches(tool.name)]
+
+    async def get_tool(
+        self,
+        name: str,
+        call_next: GetToolNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> Tool | None:
+        if self._matches(name):
+            return None
+        return await call_next(name, version=version)
+
+
+def parse_header(value: str) -> tuple[str, str]:
+    name, separator, header_value = value.partition(":")
+    if not separator or not name.strip():
+        raise argparse.ArgumentTypeError("Headers must use the format 'Name: Value'.")
+    try:
+        expanded_value = ENV_VAR_PATTERN.sub(
+            lambda match: os.environ[match.group(1)], header_value
+        )
+    except KeyError as exc:
+        raise argparse.ArgumentTypeError(
+            f"Environment variable {exc.args[0]} is not set."
+        ) from exc
+    return name.strip(), expanded_value.strip()
+
+
+def parse_verify(value: str) -> bool | str:
+    """Interpret the --verify value as a boolean toggle or a CA bundle path."""
+    lowered = value.strip().lower()
+    if lowered in {"false", "0", "no", "off"}:
+        return False
+    if lowered in {"true", "1", "yes", "on"}:
+        return True
+    return value
+
+
+def default_storage_dir(resource: str | None = None) -> Path:
+    if config_dir := os.environ.get("FASTMCP_REMOTE_CONFIG_DIR"):
+        base = Path(config_dir).expanduser()
+    else:
+        base = Path.home() / ".fastmcp" / "remote"
+    if resource is None:
+        return base
+    digest = hashlib.sha256(resource.encode()).hexdigest()[:16]
+    return base / "resources" / digest
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="fastmcp-remote",
+        description="Bridge a remote MCP server to a local stdio MCP process.",
+    )
+    parser.add_argument("url", help="Remote MCP server URL.")
+    parser.add_argument(
+        "callback_port",
+        nargs="?",
+        type=int,
+        help="OAuth callback port. Defaults to an available local port.",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["http", "sse"],
+        default="http",
+        help="Remote transport. Defaults to http.",
+    )
+    parser.add_argument(
+        "--header",
+        action="append",
+        default=[],
+        type=parse_header,
+        help="Header to send upstream, in 'Name: Value' form. Repeat for multiple headers.",
+    )
+    parser.add_argument(
+        "--auth",
+        choices=["oauth", "none"],
+        default=None,
+        help="Authentication mode. Defaults to OAuth unless Authorization is provided.",
+    )
+    parser.add_argument(
+        "--resource",
+        help="Resource identifier used to isolate OAuth token storage.",
+    )
+    parser.add_argument(
+        "--host",
+        default="localhost",
+        help="OAuth callback hostname. Defaults to localhost.",
+    )
+    parser.add_argument(
+        "--auth-timeout",
+        type=float,
+        default=300.0,
+        help="Seconds to wait for the OAuth callback. Defaults to 300.",
+    )
+    parser.add_argument(
+        "--ignore-tool",
+        action="append",
+        default=[],
+        help="Hide tools matching this glob pattern. Repeat for multiple patterns.",
+    )
+    parser.add_argument(
+        "--verify",
+        type=parse_verify,
+        default=None,
+        metavar="VERIFY",
+        help=(
+            "SSL certificate verification. Pass a path to a CA bundle file, or "
+            "'false' to disable verification (insecure, for self-signed "
+            "certificates). Defaults to verification enabled."
+        ),
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable debug logging.",
+    )
+    parser.add_argument(
+        "--silent",
+        action="store_true",
+        help="Suppress non-critical logs.",
+    )
+    return parser
+
+
+def parse_args(argv: Sequence[str] | None = None) -> RemoteConfig:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    parsed_url = urlparse(args.url)
+    if parsed_url.scheme not in {"http", "https"}:
+        parser.error("The remote MCP server URL must start with http:// or https://.")
+
+    headers = dict(args.header)
+    if args.silent and args.debug:
+        parser.error("--silent and --debug cannot be used together.")
+    if args.auth_timeout <= 0:
+        parser.error("--auth-timeout must be greater than 0.")
+
+    log_level = "DEBUG" if args.debug else None
+    if args.silent:
+        log_level = "CRITICAL"
+
+    return RemoteConfig(
+        url=args.url,
+        headers=headers,
+        transport=args.transport,
+        auth=args.auth,
+        callback_port=args.callback_port,
+        callback_host=args.host,
+        callback_timeout=args.auth_timeout,
+        storage_dir=default_storage_dir(args.resource),
+        ignore_tools=tuple(args.ignore_tool),
+        show_banner=not args.silent,
+        log_level=log_level,
+        verify=args.verify,
+    )
+
+
+def build_token_storage(storage_dir: Path) -> AsyncKeyValue:
+    storage_dir.mkdir(parents=True, exist_ok=True)
+    return FileTreeStore(
+        data_directory=storage_dir,
+        key_sanitization_strategy=FileTreeV1KeySanitizationStrategy(storage_dir),
+        collection_sanitization_strategy=FileTreeV1CollectionSanitizationStrategy(
+            storage_dir
+        ),
+    )
+
+
+def resolve_auth(config: RemoteConfig) -> OAuth | None:
+    authorization_header = any(
+        name.lower() == "authorization" for name in config.headers
+    )
+    auth_mode = config.auth
+    if auth_mode is None and authorization_header:
+        auth_mode = "none"
+    elif auth_mode is None:
+        auth_mode = "oauth"
+
+    if auth_mode == "none":
+        return None
+
+    return OAuth(
+        token_storage=build_token_storage(config.storage_dir),
+        callback_port=config.callback_port,
+        callback_host=config.callback_host,
+        callback_timeout=config.callback_timeout,
+    )
+
+
+def build_transport(config: RemoteConfig) -> SSETransport | StreamableHttpTransport:
+    auth = resolve_auth(config)
+    if config.transport == "sse":
+        return SSETransport(
+            config.url, headers=config.headers, auth=auth, verify=config.verify
+        )
+    return StreamableHttpTransport(
+        config.url, headers=config.headers, auth=auth, verify=config.verify
+    )
+
+
+async def run(config: RemoteConfig) -> None:
+    client = Client(build_transport(config))
+    server = create_proxy(
+        client,
+        name="fastmcp-remote",
+        provider_error_strategy="raise",
+    )
+    if config.ignore_tools:
+        server.add_transform(IgnoreTools(config.ignore_tools))
+    await server.run_async(
+        transport="stdio",
+        show_banner=config.show_banner,
+        log_level=config.log_level,
+    )
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    config = parse_args(argv)
+    anyio.run(run, config)
diff --git a/fastmcp_remote/fastmcp_remote/py.typed b/fastmcp_remote/fastmcp_remote/py.typed
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/fastmcp_remote/fastmcp_remote/py.typed
@@ -0,0 +1 @@
+
diff --git a/fastmcp_remote/pyproject.toml b/fastmcp_remote/pyproject.toml
new file mode 100644
index 0000000..b752595
--- /dev/null
+++ b/fastmcp_remote/pyproject.toml
@@ -0,0 +1,62 @@
+[project]
+name = "fastmcp-remote"
+dynamic = ["version", "dependencies"]
+description = "A Python stdio bridge for remote MCP servers, powered by FastMCP."
+authors = [{ name = "Jeremiah Lowin" }]
+
+requires-python = ">=3.10"
+readme = "README.md"
+license = "Apache-2.0"
+
+keywords = [
+    "mcp",
+    "fastmcp remote",
+    "mcp remote",
+    "model context protocol",
+    "fastmcp",
+    "stdio",
+    "oauth",
+]
+classifiers = [
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://gofastmcp.com"
+Repository = "https://github.com/PrefectHQ/fastmcp"
+Documentation = "https://gofastmcp.com"
+"Original npm project" = "https://github.com/geelen/mcp-remote"
+
+[project.scripts]
+fastmcp-remote = "fastmcp_remote.cli:main"
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning>=0.7.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["fastmcp_remote"]
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+bump = true
+fallback-version = "0.0.0"
+
+[tool.hatch.metadata.hooks.uv-dynamic-versioning]
+dependencies = [
+    "fastmcp-slim[client,server]=={{ version }}",
+]
diff --git a/fastmcp_slim/README.md b/fastmcp_slim/README.md
new file mode 100644
index 0000000..9afc7f4
--- /dev/null
+++ b/fastmcp_slim/README.md
@@ -0,0 +1,120 @@
+<div align="center">
+
+<!-- omit in toc -->
+
+<picture>
+  <source width="550" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/PrefectHQ/fastmcp/main/docs/assets/brand/f-watercolor-waves-4-dark.png">
+  <source width="550" media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/PrefectHQ/fastmcp/main/docs/assets/brand/f-watercolor-waves-4.png">
+  <img width="550" alt="FastMCP Logo" src="https://raw.githubusercontent.com/PrefectHQ/fastmcp/main/docs/assets/brand/f-watercolor-waves-2.png">
+</picture>
+
+# FastMCP 🚀
+
+<strong>Move fast and make things.</strong>
+
+*Made with 💙 by [Prefect](https://www.prefect.io/)*
+
+[![Docs](https://img.shields.io/badge/docs-gofastmcp.com-blue)](https://gofastmcp.com)
+[![Discord](https://img.shields.io/badge/community-discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/uu8dJCgttd)
+[![PyPI - Version](https://img.shields.io/pypi/v/fastmcp.svg)](https://pypi.org/project/fastmcp)
+[![Tests](https://github.com/PrefectHQ/fastmcp/actions/workflows/run-tests.yml/badge.svg)](https://github.com/PrefectHQ/fastmcp/actions/workflows/run-tests.yml)
+[![License](https://img.shields.io/github/license/PrefectHQ/fastmcp.svg)](https://github.com/PrefectHQ/fastmcp/blob/main/LICENSE)
+
+<a href="https://trendshift.io/repositories/13266" target="_blank"><img src="https://trendshift.io/api/badge/repositories/13266" alt="prefecthq%2Ffastmcp | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+</div>
+
+---
+
+The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) connects LLMs to tools and data. FastMCP gives you everything you need to go from prototype to production:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("Demo 🚀")
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Why FastMCP
+
+Building an effective MCP application is harder than it looks. FastMCP handles all of it. Declare a tool with a Python function, and the schema, validation, and documentation are generated automatically. Connect to a server with a URL, and transport negotiation, authentication, and protocol lifecycle are managed for you. You focus on your logic, and the MCP part just works: **with FastMCP, best practices are built in.**
+
+**That's why FastMCP is the standard framework for working with MCP.** FastMCP 1.0 was incorporated into the official MCP Python SDK in 2024. Today, the actively maintained standalone project is downloaded a million times a day, and some version of FastMCP powers 70% of MCP servers across all languages.
+
+FastMCP has three pillars:
+
+<table>
+<tr>
+<td align="center" valign="top" width="33%">
+<a href="https://gofastmcp.com/servers/server">
+<img src="https://raw.githubusercontent.com/PrefectHQ/fastmcp/main/docs/assets/images/servers-card.png" alt="Servers" />
+<br /><strong>Servers</strong>
+</a>
+<br />Expose tools, resources, and prompts to LLMs.
+</td>
+<td align="center" valign="top" width="33%">
+<a href="https://gofastmcp.com/apps/overview">
+<img src="https://raw.githubusercontent.com/PrefectHQ/fastmcp/main/docs/assets/images/apps-card.png" alt="Apps" />
+<br /><strong>Apps</strong>
+</a>
+<br />Give your tools interactive UIs rendered directly in the conversation.
+</td>
+<td align="center" valign="top" width="33%">
+<a href="https://gofastmcp.com/clients/client">
+<img src="https://raw.githubusercontent.com/PrefectHQ/fastmcp/main/docs/assets/images/clients-card.png" alt="Clients" />
+<br /><strong>Clients</strong>
+</a>
+<br />Connect to any MCP server — local or remote, programmatic or CLI.
+</td>
+</tr>
+</table>
+
+**[Servers](https://gofastmcp.com/servers/server)** wrap your Python functions into MCP-compliant tools, resources, and prompts. **[Clients](https://gofastmcp.com/clients/client)** connect to any server with full protocol support. And **[Apps](https://gofastmcp.com/apps/overview)** give your tools interactive UIs rendered directly in the conversation.
+
+Ready to build? Start with the [installation guide](https://gofastmcp.com/getting-started/installation) or jump straight to the [quickstart](https://gofastmcp.com/getting-started/quickstart).
+
+## Run FastMCP in production with Horizon
+
+FastMCP is the standard way to build MCP servers. **[Prefect Horizon](https://www.prefect.io/horizon?utm_source=github&utm_medium=readme&utm_campaign=readme_horizon&utm_content=readme_body)** is the enterprise MCP gateway for running them safely.
+
+Built by the FastMCP team, Horizon packages the best practices we've learned shipping the world's most popular MCP framework.
+
+Deploy FastMCP servers from GitHub with branch previews and instant rollback. Create a private registry of every MCP your company uses. Secure access with SSO and tool-level RBAC. Get audit logs, observability, and governance across your MCP stack. Remix approved tools into purpose-built endpoints for teams and agents.
+
+Start with FastMCP. [Scale with Horizon →](https://www.prefect.io/horizon?utm_source=github&utm_medium=readme&utm_campaign=readme_horizon&utm_content=readme_cta)
+
+## Installation
+
+We recommend installing FastMCP with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv pip install fastmcp
+```
+
+For full installation instructions, including verification and upgrading, see the [**Installation Guide**](https://gofastmcp.com/getting-started/installation).
+
+**Upgrading?** We have guides for:
+- [Upgrading from FastMCP v2](https://gofastmcp.com/getting-started/upgrading/from-fastmcp-2)
+- [Upgrading from the MCP Python SDK](https://gofastmcp.com/getting-started/upgrading/from-mcp-sdk)
+- [Upgrading from the low-level SDK](https://gofastmcp.com/getting-started/upgrading/from-low-level-sdk)
+
+## 📚 Documentation
+
+FastMCP's complete documentation is available at **[gofastmcp.com](https://gofastmcp.com)**, including detailed guides, API references, and advanced patterns.
+
+Documentation is also available in [llms.txt format](https://llmstxt.org/), which is a simple markdown standard that LLMs can consume easily:
+
+- [`llms.txt`](https://gofastmcp.com/llms.txt) is essentially a sitemap, listing all the pages in the documentation.
+- [`llms-full.txt`](https://gofastmcp.com/llms-full.txt) contains the entire documentation. Note this may exceed the context window of your LLM.
+
+**Community:** Join our [Discord server](https://discord.gg/uu8dJCgttd) to connect with other FastMCP developers and share what you're building.
+
+## Contributing
+
+We welcome contributions! See the [Contributing Guide](https://gofastmcp.com/development/contributing) for setup instructions, testing requirements, and PR guidelines.
diff --git a/fastmcp_slim/fastmcp/__init__.py b/fastmcp_slim/fastmcp/__init__.py
new file mode 100644
index 0000000..0e1c33b
--- /dev/null
+++ b/fastmcp_slim/fastmcp/__init__.py
@@ -0,0 +1,112 @@
+"""FastMCP - An ergonomic MCP interface."""
+
+import importlib
+import warnings
+from importlib.metadata import PackageNotFoundError, version as _version
+from typing import TYPE_CHECKING
+
+from fastmcp import _install_hints, _sdk_patches
+from fastmcp.settings import Settings
+from fastmcp.utilities.logging import configure_logging as _configure_logging
+
+# Apply temporary SDK registry patches (SEP-1686 task methods) before any
+# client/server use. See fastmcp._sdk_patches for the upstream-gap rationale.
+_sdk_patches.install()
+
+if TYPE_CHECKING:
+    from fastmcp.client import Client as Client
+    from fastmcp.apps.app import FastMCPApp as FastMCPApp
+    from fastmcp.exceptions import (
+        FastMCPDeprecationWarning as FastMCPDeprecationWarning,
+    )
+    from fastmcp.server.context import Context as Context
+    from fastmcp.server.server import FastMCP as FastMCP
+
+settings = Settings()
+if settings.log_enabled:
+    _configure_logging(
+        level=settings.log_level,
+        enable_rich_tracebacks=settings.enable_rich_tracebacks,
+    )
+
+# Install camelCase compatibility shims for MCP SDK v2's snake_case rename.
+# Installed unconditionally; each shim's getter checks the live
+# `mcp_camelcase_compat` setting at read time, so the bridge can be toggled at
+# runtime. Patches only mcp_types model classes, no client chain.
+from fastmcp import _compat
+
+_compat.install()
+
+try:
+    __version__ = _version("fastmcp-slim")
+except PackageNotFoundError:
+    __version__ = _version("fastmcp")
+
+if settings.deprecation_warnings:
+    try:
+        from fastmcp.exceptions import FastMCPDeprecationWarning
+    except ImportError:
+        pass
+    else:
+        warnings.simplefilter("default", FastMCPDeprecationWarning)
+
+
+# --- Lazy imports for performance (see #3292) ---
+# Client and the client submodule are deferred so that server-only users
+# don't pay for the client import chain. Do not convert back to top-level.
+
+
+def __getattr__(name: str) -> object:
+    if name == "Client":
+        try:
+            from fastmcp.client import Client
+        except ImportError as exc:
+            raise ImportError(_install_hints.CLIENT_SUPPORT) from exc
+
+        return Client
+    if name == "Context":
+        try:
+            from fastmcp.server.context import Context
+        except ImportError as exc:
+            raise ImportError(_install_hints.SERVER_SUPPORT) from exc
+
+        return Context
+    if name == "FastMCP":
+        try:
+            from fastmcp.server.server import FastMCP
+        except ImportError as exc:
+            raise ImportError(_install_hints.SERVER_SUPPORT) from exc
+
+        return FastMCP
+    if name == "FastMCPApp":
+        try:
+            from fastmcp.apps.app import FastMCPApp
+        except ImportError as exc:
+            raise ImportError(_install_hints.APP_SUPPORT) from exc
+
+        return FastMCPApp
+    if name == "FastMCPDeprecationWarning":
+        from fastmcp.exceptions import FastMCPDeprecationWarning
+
+        return FastMCPDeprecationWarning
+    if name == "client":
+        try:
+            return importlib.import_module("fastmcp.client")
+        except ImportError as exc:
+            raise ImportError(_install_hints.CLIENT_SUPPORT) from exc
+    if name == "server":
+        try:
+            return importlib.import_module("fastmcp.server")
+        except ImportError as exc:
+            raise ImportError(_install_hints.SERVER_SUPPORT) from exc
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "Client",
+    "Context",
+    "FastMCP",
+    "FastMCPApp",
+    "FastMCPDeprecationWarning",
+    "settings",
+]
diff --git a/fastmcp_slim/fastmcp/_compat.py b/fastmcp_slim/fastmcp/_compat.py
new file mode 100644
index 0000000..f5fcc7f
--- /dev/null
+++ b/fastmcp_slim/fastmcp/_compat.py
@@ -0,0 +1,152 @@
+"""camelCase compatibility bridge for MCP SDK v2.
+
+MCP Python SDK v2 renamed protocol fields from camelCase (`inputSchema`) to
+snake_case (`input_schema`). FastMCP returns these SDK models directly from
+client calls, middleware hooks, and handler callbacks, so legacy user code that
+reads the old camelCase spellings would break.
+
+This module installs warn-once `@property` shims that route a small set of
+documented camelCase reads to their snake_case attributes. Only fields users
+actually read (per the docs boundary inventory) are bridged; each read emits a
+single `FastMCPDeprecationWarning` per (class, name) and returns the correct
+value. Installation is idempotent.
+
+The properties are installed unconditionally, but each getter checks the live
+`mcp_camelcase_compat` setting at read time: when the setting is enabled it
+warns and returns the snake_case value; when disabled it raises `AttributeError`
+exactly as if the property were never installed. This makes the setting a
+genuine runtime toggle (`fastmcp.settings.mcp_camelcase_compat = False` after
+import turns the bridge off) at negligible overhead.
+
+Guards ensure we never shadow a real upstream attribute: if a class already
+defines the camelCase name in its own `__dict__` or in its pydantic
+`model_fields`, we skip it. The property is a plain descriptor read, so values
+survive `model_copy`/`model_validate` (the underlying snake field is what gets
+copied/validated; the property reads through it every time).
+
+# TODO(sdk-v2-migration): remove once user code has migrated off camelCase reads.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+import mcp_types
+
+from fastmcp.exceptions import FastMCPDeprecationWarning
+
+# Map each SDK model class to the camelCase -> snake_case field reads we bridge.
+# Limited to fields FastMCP users actually read (docs boundary inventory).
+_ALIASES: dict[type, dict[str, str]] = {
+    mcp_types.Tool: {
+        "inputSchema": "input_schema",
+        "outputSchema": "output_schema",
+    },
+    mcp_types.Resource: {
+        "mimeType": "mime_type",
+    },
+    mcp_types.ResourceTemplate: {
+        "mimeType": "mime_type",
+        "uriTemplate": "uri_template",
+    },
+    mcp_types.TextResourceContents: {
+        "mimeType": "mime_type",
+    },
+    mcp_types.BlobResourceContents: {
+        "mimeType": "mime_type",
+    },
+    mcp_types.ImageContent: {
+        "mimeType": "mime_type",
+    },
+    mcp_types.AudioContent: {
+        "mimeType": "mime_type",
+    },
+    mcp_types.CallToolResult: {
+        "isError": "is_error",
+        "structuredContent": "structured_content",
+    },
+    mcp_types.Completion: {
+        "hasMore": "has_more",
+    },
+    mcp_types.InitializeResult: {
+        "serverInfo": "server_info",
+        "protocolVersion": "protocol_version",
+    },
+    mcp_types.ListToolsResult: {
+        "nextCursor": "next_cursor",
+    },
+    mcp_types.ListResourcesResult: {
+        "nextCursor": "next_cursor",
+    },
+    mcp_types.ListResourceTemplatesResult: {
+        "nextCursor": "next_cursor",
+        "resourceTemplates": "resource_templates",
+    },
+    mcp_types.ListPromptsResult: {
+        "nextCursor": "next_cursor",
+    },
+    mcp_types.CreateMessageRequestParams: {
+        "systemPrompt": "system_prompt",
+        "maxTokens": "max_tokens",
+        "stopSequences": "stop_sequences",
+        "modelPreferences": "model_preferences",
+        "toolChoice": "tool_choice",
+    },
+    mcp_types.ElicitRequestFormParams: {
+        "requestedSchema": "requested_schema",
+    },
+}
+
+_installed = False
+
+
+def _make_property(cls_name: str, camel: str, snake: str) -> property:
+    """Build a warn-once property routing a camelCase read to a snake attr.
+
+    The getter reads the live `mcp_camelcase_compat` setting on every access: if
+    the bridge is disabled it raises `AttributeError` (matching the message
+    Python raises for a genuinely missing attribute) so the shim is transparent;
+    if enabled it warns once and returns the snake_case value.
+    """
+    warned = False
+
+    def getter(self: object) -> object:
+        nonlocal warned
+        import fastmcp
+
+        if not fastmcp.settings.mcp_camelcase_compat:
+            raise AttributeError(f"{cls_name!r} object has no attribute {camel!r}")
+        if not warned:
+            warned = True
+            warnings.warn(
+                f"Accessing `{cls_name}.{camel}` is deprecated; MCP SDK v2 "
+                f"renamed this field to `{snake}`. Update your code to read "
+                f"`.{snake}` instead.",
+                FastMCPDeprecationWarning,
+                stacklevel=2,
+            )
+        return getattr(self, snake)
+
+    return property(getter)
+
+
+def install() -> None:
+    """Install camelCase compatibility properties on SDK v2 model classes.
+
+    Idempotent. Each bridged read warns once per (class, name) and returns the
+    snake_case value. Skips any camelCase name a class already defines to avoid
+    shadowing real upstream attributes.
+    """
+    global _installed
+    if _installed:
+        return
+
+    for cls, mapping in _ALIASES.items():
+        model_fields = getattr(cls, "model_fields", {})
+        for camel, snake in mapping.items():
+            # Never shadow a real upstream attribute or field.
+            if camel in cls.__dict__ or camel in model_fields:
+                continue
+            setattr(cls, camel, _make_property(cls.__name__, camel, snake))
+
+    _installed = True
diff --git a/fastmcp_slim/fastmcp/_install_hints.py b/fastmcp_slim/fastmcp/_install_hints.py
new file mode 100644
index 0000000..89c25f4
--- /dev/null
+++ b/fastmcp_slim/fastmcp/_install_hints.py
@@ -0,0 +1,25 @@
+CLIENT_SUPPORT = (
+    "FastMCP client support is not installed. Install `fastmcp` or "
+    "`fastmcp-slim[client]`."
+)
+
+SERVER_SUPPORT = (
+    "FastMCP server support is not installed. Install `fastmcp` or "
+    "`fastmcp-slim[server]`."
+)
+
+APP_SUPPORT = (
+    "FastMCP app support is not installed. Install `fastmcp[apps]` or "
+    "`fastmcp-slim[server,apps]`."
+)
+
+CLI_SUPPORT = (
+    "FastMCP CLI support is not installed. Install `fastmcp` or `fastmcp-slim[server]`."
+)
+
+
+def full_package(feature: str) -> str:
+    return (
+        f"{feature} require the full `fastmcp` package. "
+        "Install it with `pip install fastmcp`."
+    )
diff --git a/fastmcp_slim/fastmcp/_sdk_patches.py b/fastmcp_slim/fastmcp/_sdk_patches.py
new file mode 100644
index 0000000..a77765c
--- /dev/null
+++ b/fastmcp_slim/fastmcp/_sdk_patches.py
@@ -0,0 +1,131 @@
+"""Temporary in-place patches for gaps in the pinned MCP SDK.
+
+## SEP-1686 task methods missing from the handshake-era method registries
+
+This shim compensates for a genuine gap in the SDK's *handshake-era*
+(2025-11-25 and earlier) task registry. In the 2025-11-25 SEP-1686 model, tasks
+are a first-class part of the core protocol: `CallToolRequestParams` carries a
+`task: TaskMetadata` field and a task-augmented `tools/call` returns a
+`CreateTaskResult`. `mcp==2.0.0b1` ships those task types (`CreateTaskResult`,
+`GetTaskResult`, `GetTaskPayloadResult`, `ListTasksResult`, `CancelTaskResult`)
+and the `task` request field, but its `mcp_types.methods` registries were never
+wired for them: there are no `tasks/*` rows, and the handshake-era `tools/call`
+result rows are a plain `CallToolResult` with no `CreateTaskResult` arm.
+
+The lowlevel server runner (`mcp.server.runner`) serializes a handler's result
+through `serialize_server_result(method, version, ...)` for any method in
+`SPEC_CLIENT_METHODS`. `tools/call` is such a method, so when a FastMCP tool is
+submitted as a background task (`client.call_tool(..., task=True)`) the handler
+returns a `CreateTaskResult`, which fails validation against the un-widened
+`tools/call` surface row -> the client sees "Handler returned an invalid
+result". The `tasks/*` methods themselves are NOT in `SPEC_CLIENT_METHODS`, so
+their handler results already bypass serialization and reach the wire
+unvalidated; we still register their result rows here for symmetry and so the
+maps are consistent if a future SDK adds them to the spec method set.
+
+## Scope: handshake-era versions only
+
+The widening + `tasks/*` registration is gated to
+`HANDSHAKE_PROTOCOL_VERSIONS` (2025-11-25 and earlier) because those are the
+versions where the 2025 SEP-1686 task model actually applies and where the
+SDK's registry has the genuine gap we compensate for.
+
+The 2026-07-28 protocol is intentionally NOT patched here. Tasks left the core
+protocol in 2026-07-28 and became the separate `io.modelcontextprotocol/tasks`
+extension; `CreateTaskResult` and the `task` field on `CallToolRequestParams`
+do not exist in that schema (a task-augmented `tools/call` was replaced by the
+mutually-recursive `CallToolResult | InputRequiredResult` result). Injecting the
+2025-era `CreateTaskResult` into the 2026 `tools/call` union would assert the
+wrong task model onto that protocol, so we leave its rows untouched.
+
+This module widens the registries IN PLACE (the maps are `MappingProxyType`
+views over private dicts, so we reach the backing dict via `gc.get_referents`
+and mutate it, which the already-bound default-argument references in
+`mcp_types.methods` observe). `install()` is idempotent.
+
+# TODO(sdk-upstream): remove when mcp>=2.0.0bX wires SEP-1686 into the
+# handshake-era method registries.
+"""
+
+from __future__ import annotations
+
+import gc
+from types import MappingProxyType, UnionType
+
+import mcp_types
+from mcp_types import methods as _methods
+from mcp_types.version import HANDSHAKE_PROTOCOL_VERSIONS
+
+# Result type for each task method, keyed by the client request method name.
+_TASK_RESULT_TYPES: dict[str, type] = {
+    "tasks/get": mcp_types.GetTaskResult,
+    "tasks/result": mcp_types.GetTaskPayloadResult,
+    "tasks/list": mcp_types.ListTasksResult,
+    "tasks/cancel": mcp_types.CancelTaskResult,
+}
+
+_installed = False
+
+
+def _backing_dict(proxy: object) -> dict:
+    """Return the mutable dict a MappingProxyType wraps.
+
+    The `mcp_types.methods` surface maps are `MappingProxyType` views; their
+    sole dict referent is the backing store the module's functions read through
+    their default `surface=` arguments.
+    """
+    referents = [r for r in gc.get_referents(proxy) if isinstance(r, dict)]
+    if len(referents) != 1:
+        raise RuntimeError(
+            "expected exactly one backing dict for the method registry proxy, "
+            f"found {len(referents)}"
+        )
+    return referents[0]
+
+
+def install() -> None:
+    """Widen the SDK's server-result registry for SEP-1686 task methods.
+
+    Idempotent. Safe to call at import time before any client/server use.
+    """
+    global _installed
+    if _installed:
+        return
+
+    if not isinstance(_methods.SERVER_RESULTS, MappingProxyType):
+        # Registry shape changed upstream; the shim no longer applies.
+        _installed = True
+        return
+
+    server_results = _backing_dict(_methods.SERVER_RESULTS)
+
+    # Gate to handshake-era versions only: the 2025 SEP-1686 task model applies
+    # there, and 2026-07-28 tasks are the separate io.modelcontextprotocol/tasks
+    # extension (see module docstring) — its rows must stay untouched.
+    versions_with_tools_call = {
+        version
+        for (method, version) in server_results
+        if method == "tools/call" and version in HANDSHAKE_PROTOCOL_VERSIONS
+    }
+
+    for version in versions_with_tools_call:
+        # (a) widen tools/call so a CreateTaskResult validates (task submission).
+        existing = server_results[("tools/call", version)]
+        arms = get_union_arms(existing)
+        if mcp_types.CreateTaskResult not in arms:
+            server_results[("tools/call", version)] = (
+                existing | mcp_types.CreateTaskResult
+            )
+
+        # (b) register the tasks/* result rows for the same versions.
+        for method, result_type in _TASK_RESULT_TYPES.items():
+            server_results.setdefault((method, version), result_type)
+
+    _installed = True
+
+
+def get_union_arms(row: type | UnionType) -> tuple[type, ...]:
+    """Return the member types of a result row, whether a single type or union."""
+    if isinstance(row, UnionType):
+        return tuple(row.__args__)
+    return (row,)
diff --git a/fastmcp_slim/fastmcp/apps/__init__.py b/fastmcp_slim/fastmcp/apps/__init__.py
new file mode 100644
index 0000000..3c0ec32
--- /dev/null
+++ b/fastmcp_slim/fastmcp/apps/__init__.py
@@ -0,0 +1,42 @@
+"""FastMCP Apps — interactive UIs for MCP tools.
+
+This package contains the app-related components:
+
+- ``FastMCPApp`` — composable provider for interactive apps with backend tools
+- ``AppConfig`` — configuration for MCP App tools and resources
+- ``ResourceCSP`` / ``ResourcePermissions`` — security configuration
+"""
+
+from typing import TYPE_CHECKING as _TYPE_CHECKING
+
+from fastmcp.apps.config import AppConfig as AppConfig
+from fastmcp.apps.config import PrefabAppConfig as PrefabAppConfig
+from fastmcp.apps.config import ResourceCSP as ResourceCSP
+from fastmcp.apps.config import ResourcePermissions as ResourcePermissions
+from fastmcp.apps.config import UI_EXTENSION_ID as UI_EXTENSION_ID
+from fastmcp.apps.config import app_config_to_meta_dict as app_config_to_meta_dict
+from fastmcp.utilities.mime import UI_MIME_TYPE as UI_MIME_TYPE
+from fastmcp.utilities.mime import resolve_ui_mime_type as resolve_ui_mime_type
+
+__all__ = [
+    "UI_EXTENSION_ID",
+    "UI_MIME_TYPE",
+    "AppConfig",
+    "FastMCPApp",
+    "PrefabAppConfig",
+    "ResourceCSP",
+    "ResourcePermissions",
+    "app_config_to_meta_dict",
+    "resolve_ui_mime_type",
+]
+
+if _TYPE_CHECKING:
+    from fastmcp.apps.app import FastMCPApp as FastMCPApp
+
+
+def __getattr__(name: str) -> object:
+    if name == "FastMCPApp":
+        from fastmcp.apps.app import FastMCPApp
+
+        return FastMCPApp
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
diff --git a/fastmcp_slim/fastmcp/apps/app.py b/fastmcp_slim/fastmcp/apps/app.py
new file mode 100644
index 0000000..33e6061
--- /dev/null
+++ b/fastmcp_slim/fastmcp/apps/app.py
@@ -0,0 +1,437 @@
+"""FastMCPApp — a Provider that represents a composable MCP application.
+
+FastMCPApp binds entry-point tools (model calls these) together with backend
+tools (the UI calls these via CallTool).  Backend tools are tagged with
+``meta["fastmcp"]["app"]`` so they can be found through the provider chain
+even when transforms (namespace, visibility, etc.) have renamed or hidden
+them — the server sets a context var that tells ``Provider.get_tool`` to
+fall back to a direct lookup for app-visible tools.
+
+Usage::
+
+    from fastmcp import FastMCP, FastMCPApp
+
+    app = FastMCPApp("Dashboard")
+
+    @app.ui()
+    def show_dashboard() -> Component:
+        return Column(...)
+
+    @app.tool()
+    def save_contact(name: str, email: str) -> str:
+        return name
+
+    server = FastMCP("Platform")
+    server.add_provider(app)
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import AsyncIterator, Callable, Sequence
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any, Literal, TypeVar, overload
+
+from mcp_types import Icon, ToolAnnotations
+
+from fastmcp.server.providers.base import Provider
+from fastmcp.utilities.authorization import AuthCheck
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import AnyFunction
+
+if TYPE_CHECKING:
+    from fastmcp.server.providers.local_provider import LocalProvider
+    from fastmcp.tools.base import Tool
+
+logger = get_logger(__name__)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+# ---------------------------------------------------------------------------
+# CallTool resolver
+# ---------------------------------------------------------------------------
+
+
+def _make_resolver(app_name: str | None = None) -> Any:
+    """Create a CallTool resolver that prefixes tool names with a hash.
+
+    Structurally identical to the old ``___`` resolver — ``app_name`` is
+    the FastMCPApp's name, known at serialization time from the tool's
+    ``meta["fastmcp"]["app"]`` tag. The only change is the wire format:
+    ``<hash>_<local_name>`` instead of ``<app_name>___<local_name>``.
+
+    The dispatcher recognizes the hashed form and routes it via
+    ``get_tool_by_hash`` which walks the provider tree recursively —
+    same pattern as ``get_app_tool``.
+    """
+    from fastmcp.server.providers.addressing import (
+        hashed_backend_name,
+        parse_hashed_backend_name,
+    )
+
+    def _prefix(local_name: str) -> str:
+        if app_name:
+            # Don't re-hash an already-addressed name (same guard the
+            # old ___ resolver had with "___" not in name).
+            if parse_hashed_backend_name(local_name) is not None:
+                return local_name
+            return hashed_backend_name(app_name, local_name)
+        return local_name
+
+    def _resolve_tool_ref(fn: Any) -> Any:
+        from prefab_ui.app import ResolvedTool
+
+        if isinstance(fn, str):
+            return ResolvedTool(name=_prefix(fn))
+
+        fmeta: Any = None
+        try:
+            from fastmcp.decorators import get_fastmcp_meta
+
+            fmeta = get_fastmcp_meta(fn)
+        except Exception:
+            pass
+
+        if fmeta is not None:
+            name: str | None = getattr(fmeta, "name", None)
+            if name is not None:
+                return ResolvedTool(name=_prefix(name))
+
+        fn_name = getattr(fn, "__name__", None)
+        if fn_name is not None:
+            return ResolvedTool(name=_prefix(fn_name))
+
+        raise ValueError(f"Cannot resolve tool reference: {fn!r}")
+
+    return _resolve_tool_ref
+
+
+def _dispatch_decorator(
+    name_or_fn: str | AnyFunction | None,
+    name: str | None,
+    register: Callable[[Any, str | None], Any],
+    decorator_name: str,
+) -> Any:
+    """Shared dispatch logic for @app.tool() and @app.ui() calling patterns."""
+    if inspect.isroutine(name_or_fn):
+        return register(name_or_fn, name)
+
+    if isinstance(name_or_fn, str):
+        if name is not None:
+            raise TypeError(
+                "Cannot specify both a name as first argument and as keyword argument."
+            )
+        tool_name: str | None = name_or_fn
+    elif name_or_fn is None:
+        tool_name = name
+    else:
+        raise TypeError(
+            f"First argument to @{decorator_name} must be a function, string, or None, "
+            f"got {type(name_or_fn)}"
+        )
+
+    def decorator(fn: F) -> F:
+        return register(fn, tool_name)
+
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# FastMCPApp
+# ---------------------------------------------------------------------------
+
+
+class FastMCPApp(Provider):
+    """A Provider that represents an MCP application.
+
+    Binds together entry-point tools (``@app.ui``), backend tools
+    (``@app.tool``), and the Prefab renderer resource.  Backend tools
+    are tagged with ``meta["fastmcp"]["app"]`` so ``Provider.get_tool``
+    can find them by original name even when transforms have been applied.
+    """
+
+    def __init__(self, name: str) -> None:
+        from fastmcp.server.providers.local_provider import LocalProvider
+
+        super().__init__()
+        self.name = name
+        self._local: LocalProvider = LocalProvider(on_duplicate="error")
+
+    def __repr__(self) -> str:
+        return f"FastMCPApp({self.name!r})"
+
+    # ------------------------------------------------------------------
+    # @app.tool() — backend tools called by the UI
+    # ------------------------------------------------------------------
+
+    @overload
+    def tool(
+        self,
+        name_or_fn: F,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        model: bool = False,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+        timeout: float | None = None,
+    ) -> F: ...
+
+    @overload
+    def tool(
+        self,
+        name_or_fn: str | None = None,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        model: bool = False,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+        timeout: float | None = None,
+    ) -> Callable[[F], F]: ...
+
+    def tool(
+        self,
+        name_or_fn: str | AnyFunction | None = None,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        model: bool = False,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+        timeout: float | None = None,
+    ) -> Any:
+        """Register a backend tool that the UI calls via CallTool.
+
+        Backend tools default to ``visibility=["app"]``.  Pass ``model=True``
+        to also expose the tool to the model (``visibility=["app", "model"]``).
+
+        Supports multiple calling patterns::
+
+            @app.tool
+            def save(name: str): ...
+
+            @app.tool()
+            def save(name: str): ...
+
+            @app.tool("custom_name")
+            def save(name: str): ...
+        """
+        visibility: list[Literal["app", "model"]] = (
+            ["app", "model"] if model else ["app"]
+        )
+
+        def _register(fn: F, tool_name: str | None) -> F:
+            from fastmcp.tools.base import Tool
+
+            resolved_name = tool_name or getattr(fn, "__name__", None)
+            if resolved_name is None:
+                raise ValueError(f"Cannot determine tool name for {fn!r}")
+
+            from fastmcp.apps.config import AppConfig, app_config_to_meta_dict
+            from fastmcp.server.providers.addressing import hash_tool
+
+            app_config = AppConfig(visibility=visibility)
+            meta: dict[str, Any] = {
+                "ui": app_config_to_meta_dict(app_config),
+                "fastmcp": {
+                    "app": self.name,
+                    "_tool_hash": hash_tool(self.name, resolved_name),
+                },
+            }
+
+            tool_obj = Tool.from_function(
+                fn,
+                name=resolved_name,
+                description=description,
+                meta=meta,
+                timeout=timeout,
+                auth=auth,
+            )
+            self._local._add_component(tool_obj)
+            return fn
+
+        return _dispatch_decorator(name_or_fn, name, _register, "tool")
+
+    # ------------------------------------------------------------------
+    # @app.ui() — entry-point tools the model calls to open the app
+    # ------------------------------------------------------------------
+
+    @overload
+    def ui(
+        self,
+        name_or_fn: F,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        title: str | None = None,
+        tags: set[str] | None = None,
+        icons: list[Icon] | None = None,
+        annotations: ToolAnnotations | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+        timeout: float | None = None,
+    ) -> F: ...
+
+    @overload
+    def ui(
+        self,
+        name_or_fn: str | None = None,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        title: str | None = None,
+        tags: set[str] | None = None,
+        icons: list[Icon] | None = None,
+        annotations: ToolAnnotations | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+        timeout: float | None = None,
+    ) -> Callable[[F], F]: ...
+
+    def ui(
+        self,
+        name_or_fn: str | AnyFunction | None = None,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        title: str | None = None,
+        tags: set[str] | None = None,
+        icons: list[Icon] | None = None,
+        annotations: ToolAnnotations | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+        timeout: float | None = None,
+    ) -> Any:
+        """Register a UI entry-point tool that the model calls.
+
+        Entry-point tools default to ``visibility=["model"]`` and auto-wire
+        the Prefab renderer resource and CSP. They are tagged with the app
+        name so structured content includes ``_meta.fastmcp.app``.
+
+        Supports multiple calling patterns::
+
+            @app.ui
+            def dashboard() -> Component: ...
+
+            @app.ui()
+            def dashboard() -> Component: ...
+
+            @app.ui("my_dashboard")
+            def dashboard() -> Component: ...
+        """
+
+        def _register(fn: F, tool_name: str | None) -> F:
+            from fastmcp.apps.config import AppConfig, app_config_to_meta_dict
+            from fastmcp.server.providers.addressing import hash_tool
+            from fastmcp.server.providers.local_provider.decorators.tools import (
+                PREFAB_RENDERER_URI,
+            )
+            from fastmcp.tools.base import Tool
+
+            resolved = tool_name or getattr(fn, "__name__", None) or "unknown"
+            app_config = AppConfig(
+                resource_uri=PREFAB_RENDERER_URI,
+                visibility=["model"],
+            )
+
+            meta: dict[str, Any] = {
+                "ui": app_config_to_meta_dict(app_config),
+                "fastmcp": {
+                    "app": self.name,
+                    "_tool_hash": hash_tool(self.name, resolved),
+                },
+            }
+
+            tool_obj = Tool.from_function(
+                fn,
+                name=tool_name,
+                description=description,
+                title=title,
+                tags=tags,
+                icons=icons,
+                annotations=annotations,
+                meta=meta,
+                timeout=timeout,
+                auth=auth,
+            )
+            self._local._add_component(tool_obj)
+
+            return fn
+
+        return _dispatch_decorator(name_or_fn, name, _register, "ui")
+
+    # ------------------------------------------------------------------
+    # Programmatic tool addition
+    # ------------------------------------------------------------------
+
+    def add_tool(
+        self,
+        tool: Tool | Callable[..., Any],
+    ) -> Tool:
+        """Add a tool to this app programmatically.
+
+        The tool is tagged with this app's name for routing.
+        """
+        from fastmcp.tools.base import Tool
+
+        if not isinstance(tool, Tool):
+            tool = Tool._ensure_tool(tool)
+
+        from fastmcp.server.providers.addressing import hash_tool
+
+        meta = dict(tool.meta) if tool.meta else {}
+        fm = meta.setdefault("fastmcp", {})
+        fm["app"] = self.name
+        fm["_tool_hash"] = hash_tool(self.name, tool.name)
+        ui = meta.setdefault("ui", {})
+        if "visibility" not in ui:
+            ui["visibility"] = ["app"]
+        tool.meta = meta
+
+        self._local._add_component(tool)
+        return tool
+
+    # ------------------------------------------------------------------
+    # Provider interface — delegate to internal LocalProvider
+    # ------------------------------------------------------------------
+
+    async def _list_tools(self) -> Sequence[Tool]:
+        return await self._local._list_tools()
+
+    async def _get_tool(self, name: str, version: Any = None) -> Tool | None:
+        return await self._local._get_tool(name, version)
+
+    async def _list_resources(self) -> Sequence[Any]:
+        return await self._local._list_resources()
+
+    async def _get_resource(self, uri: str, version: Any = None) -> Any | None:
+        return await self._local._get_resource(uri, version)
+
+    async def _list_resource_templates(self) -> Sequence[Any]:
+        return await self._local._list_resource_templates()
+
+    async def _get_resource_template(self, uri: str, version: Any = None) -> Any | None:
+        return await self._local._get_resource_template(uri, version)
+
+    async def _list_prompts(self) -> Sequence[Any]:
+        return await self._local._list_prompts()
+
+    async def _get_prompt(self, name: str, version: Any = None) -> Any | None:
+        return await self._local._get_prompt(name, version)
+
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncIterator[None]:
+        async with self._local.lifespan():
+            yield
+
+    # ------------------------------------------------------------------
+    # Convenience runner
+    # ------------------------------------------------------------------
+
+    def run(
+        self,
+        transport: Literal["stdio", "http", "sse", "streamable-http"] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Create a temporary FastMCP server and run this app standalone."""
+        from fastmcp.server.server import FastMCP
+
+        server = FastMCP(self.name)
+        server.add_provider(self)
+        server.run(transport=transport, **kwargs)
diff --git a/fastmcp_slim/fastmcp/apps/approval.py b/fastmcp_slim/fastmcp/apps/approval.py
new file mode 100644
index 0000000..17b124e
--- /dev/null
+++ b/fastmcp_slim/fastmcp/apps/approval.py
@@ -0,0 +1,198 @@
+"""Approval — a Provider that adds human-in-the-loop approval to any server.
+
+The LLM presents a summary of what it's about to do, and the user
+approves or rejects via buttons. The result is sent back into the
+conversation as a message, prompting the LLM's next turn.
+
+Requires ``fastmcp[apps]`` (prefab-ui).
+
+Usage::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps.approval import Approval
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(Approval())
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+try:
+    from prefab_ui.actions import SetState
+    from prefab_ui.actions.mcp import SendMessage
+    from prefab_ui.app import PrefabApp
+    from prefab_ui.components import (
+        H3,
+        Button,
+        Card,
+        CardContent,
+        CardFooter,
+        CardHeader,
+        Column,
+        Muted,
+        Row,
+        Text,
+    )
+    from prefab_ui.components.control_flow import If
+    from prefab_ui.rx import STATE
+except ImportError as _exc:
+    raise ImportError(
+        "Approval requires prefab-ui. Install with: pip install 'fastmcp[apps]'"
+    ) from _exc
+
+
+from fastmcp.apps.app import FastMCPApp
+
+
+class Approval(FastMCPApp):
+    """A Provider that adds human-in-the-loop approval to a server.
+
+    The LLM calls the ``request_approval`` tool with a summary and
+    optional details. The user sees an approval card with Approve and
+    Reject buttons. Clicking either sends a message back into the
+    conversation (via ``SendMessage``), triggering the LLM's next turn.
+
+    The message appears as if the user sent it, so the LLM sees
+    something like ``'"Deploy v3.2 to production" is APPROVED'``.
+
+    Example::
+
+        from fastmcp import FastMCP
+        from fastmcp.apps.approval import Approval
+
+        mcp = FastMCP("My Server")
+        mcp.add_provider(Approval())
+
+    Customized::
+
+        Approval(
+            title="Deploy Gate",
+            approve_text="Ship it",
+            approve_variant="default",
+            reject_text="Abort",
+            reject_variant="destructive",
+        )
+    """
+
+    def __init__(
+        self,
+        name: str = "Approval",
+        *,
+        title: str = "Approval Required",
+        approve_text: str = "Approve",
+        reject_text: str = "Reject",
+        approve_variant: Literal[
+            "default", "destructive", "success", "info"
+        ] = "default",
+        reject_variant: Literal[
+            "default", "outline", "destructive", "success", "info"
+        ] = "outline",
+    ) -> None:
+        super().__init__(name)
+        self._title = title
+        self._approve_text = approve_text
+        self._reject_text = reject_text
+        self._approve_variant = approve_variant
+        self._reject_variant = reject_variant
+        self._register_tools()
+
+    def __repr__(self) -> str:
+        return f"Approval({self.name!r})"
+
+    def _register_tools(self) -> None:
+        provider = self
+
+        @self.ui()
+        def request_approval(
+            summary: str,
+            details: str | None = None,
+            title: str | None = None,
+            approve_text: str | None = None,
+            reject_text: str | None = None,
+            approve_variant: str | None = None,
+            reject_variant: str | None = None,
+        ) -> PrefabApp:
+            """Request human approval before proceeding with an action.
+
+            Call this tool proactively whenever you are about to take a
+            significant or irreversible action and want the user to
+            confirm first. Do NOT wait for the user to ask you to seek
+            approval — use your judgment about when confirmation is
+            appropriate.
+
+            The user will see an approval card with the summary, optional
+            details, and Approve/Reject buttons. When they click a button,
+            their decision appears as a message in the conversation (as if
+            the user typed it), like:
+
+                "Deploy v3.2 to production" — I selected: Approve
+
+            or:
+
+                "Deploy v3.2 to production" — I selected: Reject
+
+            IMPORTANT: After calling this tool, you MUST stop and wait
+            for the user's response. Do not continue, do not take any
+            other actions, do not generate further output until you see
+            the "I selected:" message. If approved, continue with the
+            action. If rejected, acknowledge and ask how to proceed.
+
+            Args:
+                summary: Brief description of the action requiring approval
+                    (shown prominently to the user).
+                details: Optional longer explanation, context, or
+                    consequences of the action.
+                title: Heading for the approval card (default: "Approval Required").
+                approve_text: Label for the approve button (default: "Approve").
+                reject_text: Label for the reject button (default: "Reject").
+                approve_variant: Button style — "default", "destructive",
+                    "success", or "info".
+                reject_variant: Button style for the reject button
+                    (same options plus "outline").
+            """
+            _title = title or provider._title
+            _approve = approve_text or provider._approve_text
+            _reject = reject_text or provider._reject_text
+            _approve_v = approve_variant or provider._approve_variant
+            _reject_v = reject_variant or provider._reject_variant
+
+            approve_msg = f'"{summary}" — I selected: {_approve}'
+            reject_msg = f'"{summary}" — I selected: {_reject}'
+
+            with Card(css_class="max-w-lg mx-auto") as view:
+                with CardHeader():
+                    H3(_title)
+
+                with CardContent(), Column(gap=3):
+                    Text(summary, css_class="font-medium")
+                    if details:
+                        Muted(details)
+
+                with CardFooter():
+                    with If(STATE.decided):
+                        Muted("Response sent.")
+                    with If(~STATE.decided):  # noqa: SIM117
+                        with Row(gap=2, css_class="w-full justify-end"):
+                            Button(
+                                _reject,
+                                variant=_reject_v,
+                                on_click=[
+                                    SendMessage(reject_msg),
+                                    SetState("decided", True),
+                                ],
+                            )
+                            Button(
+                                _approve,
+                                variant=_approve_v,
+                                on_click=[
+                                    SendMessage(approve_msg),
+                                    SetState("decided", True),
+                                ],
+                            )
+
+            return PrefabApp(
+                view=view,
+                state={"decided": False},
+            )
diff --git a/fastmcp_slim/fastmcp/apps/choice.py b/fastmcp_slim/fastmcp/apps/choice.py
new file mode 100644
index 0000000..aaffef9
--- /dev/null
+++ b/fastmcp_slim/fastmcp/apps/choice.py
@@ -0,0 +1,141 @@
+"""Choice — a Provider that lets the user pick from a set of options.
+
+The LLM presents options, the user clicks one, and the selection
+flows back into the conversation as a message.
+
+Requires ``fastmcp[apps]`` (prefab-ui).
+
+Usage::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps.choice import Choice
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(Choice())
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+try:
+    from prefab_ui.actions import SetState
+    from prefab_ui.actions.mcp import SendMessage
+    from prefab_ui.app import PrefabApp
+    from prefab_ui.components import (
+        H3,
+        Button,
+        Card,
+        CardContent,
+        CardFooter,
+        CardHeader,
+        Column,
+        Muted,
+        Text,
+    )
+    from prefab_ui.components.control_flow import If
+    from prefab_ui.rx import STATE
+except ImportError as _exc:
+    raise ImportError(
+        "Choice requires prefab-ui. Install with: pip install 'fastmcp[apps]'"
+    ) from _exc
+
+from fastmcp.apps.app import FastMCPApp
+
+
+class Choice(FastMCPApp):
+    """A Provider that lets the user choose from a set of options.
+
+    The LLM calls ``choose`` with a prompt and a list of options.
+    The user sees a card with one button per option. Clicking a button
+    sends the selection back into the conversation via ``SendMessage``,
+    triggering the LLM's next turn.
+
+    Example::
+
+        from fastmcp import FastMCP
+        from fastmcp.apps.choice import Choice
+
+        mcp = FastMCP("My Server")
+        mcp.add_provider(Choice())
+    """
+
+    def __init__(
+        self,
+        name: str = "Choice",
+        *,
+        title: str = "Choose an Option",
+        variant: Literal[
+            "default", "outline", "destructive", "success", "info"
+        ] = "outline",
+    ) -> None:
+        super().__init__(name)
+        self._title = title
+        self._variant = variant
+        self._register_tools()
+
+    def __repr__(self) -> str:
+        return f"Choice({self.name!r})"
+
+    def _register_tools(self) -> None:
+        provider = self
+
+        @self.ui()
+        def choose(
+            prompt: str,
+            options: list[str],
+            title: str | None = None,
+        ) -> PrefabApp:
+            """Present the user with a set of options to choose from.
+
+            Call this tool when you need the user to make a decision
+            between discrete alternatives. Use it proactively — don't
+            ask the user to type their choice in chat when you can
+            present clean, clickable options instead.
+
+            The user will see a card with one button per option. When
+            they click one, their choice appears as a message in the
+            conversation (as if the user typed it), like:
+
+                "Which deployment strategy?" — I selected: Blue-green
+
+            IMPORTANT: After calling this tool, you MUST stop and wait
+            for the user's response. Do not continue or take any other
+            actions until you see the "I selected:" message.
+
+            Args:
+                prompt: The question or decision to present to the user.
+                options: List of options the user can choose from.
+                title: Optional heading for the card.
+            """
+            _title = title or provider._title
+
+            with Card(css_class="max-w-lg mx-auto") as view:
+                with CardHeader():
+                    H3(_title)
+
+                with CardContent():
+                    Text(prompt, css_class="font-medium")
+
+                with CardFooter():
+                    with If(STATE.decided):
+                        Muted("Response sent.")
+                    with If(~STATE.decided):  # noqa: SIM117
+                        with Column(gap=2, css_class="w-full"):
+                            for option in options:
+                                Button(
+                                    option,
+                                    variant=provider._variant,
+                                    css_class="w-full justify-start",
+                                    on_click=[
+                                        SendMessage(
+                                            f'"{prompt}" — I selected: {option}'
+                                        ),
+                                        SetState("decided", True),
+                                    ],
+                                )
+
+            return PrefabApp(
+                view=view,
+                state={"decided": False},
+            )
diff --git a/fastmcp_slim/fastmcp/apps/config.py b/fastmcp_slim/fastmcp/apps/config.py
new file mode 100644
index 0000000..3d89aa3
--- /dev/null
+++ b/fastmcp_slim/fastmcp/apps/config.py
@@ -0,0 +1,184 @@
+"""MCP Apps support — extension negotiation and typed UI metadata models.
+
+Provides constants and Pydantic models for the MCP Apps extension
+(io.modelcontextprotocol/ui), enabling tools and resources to carry
+UI metadata for clients that support interactive app rendering.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from fastmcp.utilities.mime import UI_MIME_TYPE as UI_MIME_TYPE
+from fastmcp.utilities.mime import resolve_ui_mime_type as resolve_ui_mime_type
+
+UI_EXTENSION_ID = "io.modelcontextprotocol/ui"
+
+
+class ResourceCSP(BaseModel):
+    """Content Security Policy for MCP App resources.
+
+    Declares which external origins the app is allowed to connect to or
+    load resources from.  Hosts use these declarations to build the
+    ``Content-Security-Policy`` header for the sandboxed iframe.
+    """
+
+    connect_domains: list[str] | None = Field(
+        default=None,
+        validation_alias="connectDomains",
+        serialization_alias="connectDomains",
+        description="Origins allowed for fetch/XHR/WebSocket (connect-src)",
+    )
+    resource_domains: list[str] | None = Field(
+        default=None,
+        validation_alias="resourceDomains",
+        serialization_alias="resourceDomains",
+        description="Origins allowed for scripts, images, styles, fonts (script-src etc.)",
+    )
+    frame_domains: list[str] | None = Field(
+        default=None,
+        validation_alias="frameDomains",
+        serialization_alias="frameDomains",
+        description="Origins allowed for nested iframes (frame-src)",
+    )
+    base_uri_domains: list[str] | None = Field(
+        default=None,
+        validation_alias="baseUriDomains",
+        serialization_alias="baseUriDomains",
+        description="Allowed base URIs for the document (base-uri)",
+    )
+
+    model_config = {"populate_by_name": True, "extra": "allow"}
+
+
+class ResourcePermissions(BaseModel):
+    """Iframe sandbox permissions for MCP App resources.
+
+    Each field, when set (typically to ``{}``), requests that the host
+    grant the corresponding Permission Policy feature to the sandboxed
+    iframe.  Hosts MAY honour these; apps should use JS feature detection
+    as a fallback.
+    """
+
+    camera: dict[str, Any] | None = Field(
+        default=None, description="Request camera access"
+    )
+    microphone: dict[str, Any] | None = Field(
+        default=None, description="Request microphone access"
+    )
+    geolocation: dict[str, Any] | None = Field(
+        default=None, description="Request geolocation access"
+    )
+    clipboard_write: dict[str, Any] | None = Field(
+        default=None,
+        validation_alias="clipboardWrite",
+        serialization_alias="clipboardWrite",
+        description="Request clipboard-write access",
+    )
+
+    model_config = {"populate_by_name": True, "extra": "allow"}
+
+
+class AppConfig(BaseModel):
+    """Configuration for MCP App tools and resources.
+
+    Controls how a tool or resource participates in the MCP Apps extension.
+    On tools, ``resource_uri`` and ``visibility`` specify which UI resource
+    to render and where the tool appears.  On resources, those fields must
+    be left unset (the resource itself is the UI).
+
+    All fields use ``exclude_none`` serialization so only explicitly-set
+    values appear on the wire.  Aliases match the MCP Apps wire format
+    (camelCase).
+    """
+
+    resource_uri: str | None = Field(
+        default=None,
+        validation_alias="resourceUri",
+        serialization_alias="resourceUri",
+        description="URI of the UI resource (typically ui:// scheme). Tools only.",
+    )
+    visibility: list[Literal["app", "model"]] | None = Field(
+        default=None,
+        description="Where this tool is visible: 'app', 'model', or both. Tools only.",
+    )
+    csp: ResourceCSP | None = Field(
+        default=None, description="Content Security Policy for the app iframe"
+    )
+    permissions: ResourcePermissions | None = Field(
+        default=None, description="Iframe sandbox permissions"
+    )
+    domain: str | None = Field(default=None, description="Domain for the iframe")
+    prefers_border: bool | None = Field(
+        default=None,
+        validation_alias="prefersBorder",
+        serialization_alias="prefersBorder",
+        description="Whether the UI prefers a visible border",
+    )
+
+    model_config = {"populate_by_name": True, "extra": "allow"}
+
+
+class PrefabAppConfig(AppConfig):
+    """App configuration for Prefab tools with sensible defaults.
+
+    Like ``app=True`` but customizable. Auto-wires the Prefab renderer
+    URI and merges the renderer's CSP with any additional domains you
+    specify.  The renderer resource is registered automatically.
+
+    Example::
+
+        @mcp.tool(app=PrefabAppConfig())  # same as app=True
+
+        @mcp.tool(app=PrefabAppConfig(
+            csp=ResourceCSP(frame_domains=["https://example.com"]),
+        ))
+    """
+
+    def model_post_init(self, __context: Any) -> None:
+        # Set the renderer URI if not explicitly overridden
+        if self.resource_uri is None:
+            self.resource_uri = "ui://prefab/renderer.html"
+
+        # Merge renderer CSP with user-provided CSP
+        try:
+            from prefab_ui.renderer import get_renderer_csp
+
+            renderer_csp = get_renderer_csp()
+        except ImportError:
+            renderer_csp = {}
+
+        if renderer_csp:
+            user_csp = self.csp or ResourceCSP()
+            # Start from the user's CSP (preserves model_extra for
+            # forward-compat directives), then merge renderer domains.
+            merged_data = user_csp.model_dump(exclude_none=True)
+            merged_data["connect_domains"] = _merge_domains(
+                renderer_csp.get("connect_domains"),
+                user_csp.connect_domains,
+            )
+            merged_data["resource_domains"] = _merge_domains(
+                renderer_csp.get("resource_domains"),
+                user_csp.resource_domains,
+            )
+            self.csp = ResourceCSP(**merged_data)
+
+
+def _merge_domains(base: list[str] | None, extra: list[str] | None) -> list[str] | None:
+    """Merge two domain lists, deduplicating."""
+    if base is None and extra is None:
+        return None
+    combined = list(base or [])
+    for d in extra or []:
+        if d not in combined:
+            combined.append(d)
+    return combined or None
+
+
+def app_config_to_meta_dict(app: AppConfig | dict[str, Any]) -> dict[str, Any]:
+    """Convert an AppConfig or dict to the wire-format dict for ``meta["ui"]``."""
+    if isinstance(app, AppConfig):
+        return app.model_dump(by_alias=True, exclude_none=True)
+    return app
diff --git a/fastmcp_slim/fastmcp/apps/file_upload.py b/fastmcp_slim/fastmcp/apps/file_upload.py
new file mode 100644
index 0000000..ed302ce
--- /dev/null
+++ b/fastmcp_slim/fastmcp/apps/file_upload.py
@@ -0,0 +1,405 @@
+"""FileUpload — a Provider that adds drag-and-drop file upload to any server.
+
+Lets users upload files directly to the server through an interactive UI,
+bypassing the LLM context window entirely. The LLM can then read and work
+with uploaded files through model-visible tools.
+
+Requires ``fastmcp[apps]`` (prefab-ui).
+
+Usage::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps import FileUpload
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(FileUpload())
+
+For custom persistence, override the storage methods::
+
+    class S3Upload(FileUpload):
+        def on_store(self, files, ctx):
+            # write to S3, return summaries
+            ...
+
+        def on_list(self, ctx):
+            # list from S3
+            ...
+
+        def on_read(self, name, ctx):
+            # read from S3
+            ...
+"""
+
+from __future__ import annotations
+
+try:
+    from prefab_ui.actions import SetState, ShowToast
+    from prefab_ui.actions.mcp import CallTool
+    from prefab_ui.app import PrefabApp
+    from prefab_ui.components import (
+        H3,
+        Badge,
+        Button,
+        Card,
+        CardContent,
+        CardFooter,
+        CardHeader,
+        Column,
+        DropZone,
+        Muted,
+        Row,
+        Separator,
+        Small,
+        Text,
+    )
+    from prefab_ui.components.control_flow import Else, ForEach, If
+    from prefab_ui.rx import ERROR, RESULT, STATE, Rx
+except ImportError as _exc:
+    raise ImportError(
+        "FileUpload requires prefab-ui. Install with: pip install 'fastmcp[apps]'"
+    ) from _exc
+
+import base64
+from datetime import datetime, timezone
+from typing import Any
+
+from fastmcp.apps.app import FastMCPApp
+from fastmcp.server.context import Context
+
+_TEXT_EXTENSIONS = frozenset(
+    (".csv", ".json", ".txt", ".md", ".py", ".yaml", ".yml", ".toml")
+)
+
+
+def _b64_decoded_size(b64: str) -> int:
+    """Return the exact decoded byte-length of a base64 string without decoding it."""
+    n = len(b64)
+    if n == 0:
+        return 0
+    padding = b64.count("=", max(0, n - 2))
+    return n * 3 // 4 - padding
+
+
+def _format_size(size: int) -> str:
+    if size < 1024:
+        return f"{size} B"
+    elif size < 1024 * 1024:
+        return f"{size / 1024:.1f} KB"
+    else:
+        return f"{size / (1024 * 1024):.1f} MB"
+
+
+def _make_summary(entry: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "name": entry["name"],
+        "type": entry["type"],
+        "size": entry["size"],
+        "size_display": _format_size(entry["size"]),
+        "uploaded_at": entry["uploaded_at"],
+    }
+
+
+class FileUpload(FastMCPApp):
+    """A Provider that adds file upload capabilities to a server.
+
+    Registers a drag-and-drop UI tool, a backend storage tool, and
+    model-visible tools for listing and reading uploaded files.
+
+    Files are scoped by MCP session and stored in memory by default.
+    Override ``on_store``, ``on_list``, and ``on_read`` for custom
+    persistence (filesystem, S3, database, etc.). Each method receives
+    the current ``Context``, giving access to session ID, auth tokens,
+    and request metadata for partitioning and authorization.
+
+    **Session scoping:** The default storage uses ``ctx.session_id`` to
+    isolate files by session. This works with stdio, SSE, and stateful
+    HTTP transports. In **stateless HTTP** mode, each request creates a
+    new session, so files won't persist across requests. For stateless
+    deployments, override the storage methods to partition by a stable
+    identifier from the auth context::
+
+        class UserScopedUpload(FileUpload):
+            def on_store(self, files, ctx):
+                user_id = ctx.access_token["sub"]
+                ...
+
+    Example::
+
+        from fastmcp import FastMCP
+        from fastmcp.apps.file_upload import FileUpload
+
+        mcp = FastMCP("My Server")
+        mcp.add_provider(FileUpload())
+    """
+
+    def __init__(
+        self,
+        name: str = "Files",
+        *,
+        max_file_size: int = 10 * 1024 * 1024,
+        title: str = "File Upload",
+        description: str = (
+            "Drop files to upload them to the server. "
+            "The model can then read and analyze them "
+            "without using the context window."
+        ),
+        drop_label: str = "Drop files here",
+    ) -> None:
+        super().__init__(name)
+        self._max_file_size = max_file_size
+        self._title = title
+        self._description = description
+        self._drop_label = drop_label
+
+        # Default in-memory store, keyed by session_id
+        self._store: dict[str, dict[str, dict[str, Any]]] = {}
+
+        self._register_tools()
+
+    def __repr__(self) -> str:
+        return f"FileUpload({self.name!r})"
+
+    # ------------------------------------------------------------------
+    # Storage interface — override these for custom persistence
+    # ------------------------------------------------------------------
+
+    def _get_scope_key(self, ctx: Context) -> str:
+        """Return the key used to partition file storage.
+
+        Defaults to ``ctx.session_id``, which is stable for stdio, SSE,
+        and stateful HTTP. The default ``on_store``/``on_list``/``on_read``
+        implementations call this to partition the in-memory store.
+
+        Override to scope by user, tenant, or any other dimension::
+
+            def _get_scope_key(self, ctx):
+                return ctx.access_token["sub"]
+        """
+        try:
+            return ctx.session_id
+        except RuntimeError:
+            return "__default__"
+
+    def on_store(
+        self,
+        files: list[dict[str, Any]],
+        ctx: Context,
+    ) -> list[dict[str, Any]]:
+        """Store uploaded files and return summaries.
+
+        Args:
+            files: List of file dicts, each with ``name``, ``size``,
+                ``type``, and ``data`` (base64-encoded content).
+            ctx: The current request context. Use for session ID,
+                auth tokens, or any metadata needed for partitioning.
+
+        Override this method for custom persistence. The default
+        implementation stores files in memory, scoped by
+        ``_get_scope_key(ctx)``.
+
+        Returns:
+            List of file summary dicts (``name``, ``type``, ``size``,
+            ``size_display``, ``uploaded_at``).
+        """
+        scope = self._get_scope_key(ctx)
+        session_files = self._store.setdefault(scope, {})
+        for f in files:
+            session_files[f["name"]] = {
+                "name": f["name"],
+                "size": f["size"],
+                "type": f["type"],
+                "data": f["data"],
+                "uploaded_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+            }
+        return [_make_summary(e) for e in session_files.values()]
+
+    def on_list(self, ctx: Context) -> list[dict[str, Any]]:
+        """List all stored files.
+
+        Args:
+            ctx: The current request context.
+
+        Override this method for custom persistence. The default
+        implementation returns files from the current scope.
+
+        Returns:
+            List of file summary dicts.
+        """
+        scope = self._get_scope_key(ctx)
+        session_files = self._store.get(scope, {})
+        return [_make_summary(e) for e in session_files.values()]
+
+    def on_read(self, name: str, ctx: Context) -> dict[str, Any]:
+        """Read a file's contents by name.
+
+        Args:
+            name: The filename to read.
+            ctx: The current request context.
+
+        Override this method for custom persistence. The default
+        implementation reads from the current scope's in-memory store.
+        Text files are decoded from base64; binary files return a
+        truncated base64 preview.
+
+        Returns:
+            Dict with file metadata and ``content`` (text) or
+            ``content_base64`` (binary preview).
+
+        Raises:
+            ValueError: If the file is not found.
+        """
+        scope = self._get_scope_key(ctx)
+        session_files = self._store.get(scope, {})
+        if name not in session_files:
+            available = list(session_files.keys())
+            raise ValueError(f"File {name!r} not found. Available: {available}")
+        entry = session_files[name]
+        result: dict[str, Any] = {
+            "name": entry["name"],
+            "size": entry["size"],
+            "type": entry["type"],
+            "uploaded_at": entry["uploaded_at"],
+        }
+        is_text = entry["type"].startswith("text/") or any(
+            entry["name"].endswith(ext) for ext in _TEXT_EXTENSIONS
+        )
+        if is_text:
+            try:
+                result["content"] = base64.b64decode(entry["data"]).decode("utf-8")
+            except UnicodeDecodeError:
+                result["content_base64"] = entry["data"][:200] + "..."
+        else:
+            result["content_base64"] = entry["data"][:200] + "..."
+        return result
+
+    # ------------------------------------------------------------------
+    # Tool registration
+    # ------------------------------------------------------------------
+
+    def _register_tools(self) -> None:
+        provider = self
+
+        @self.tool()
+        def store_files(files: list[dict], ctx: Context) -> list[dict]:
+            """Store uploaded files. Receives file objects with name, size, type, data (base64)."""
+            for f in files:
+                # Compute actual data size from the base64 payload rather
+                # than trusting the client-reported ``size`` field.
+                actual_size = _b64_decoded_size(f.get("data", ""))
+                if actual_size > provider._max_file_size:
+                    raise ValueError(
+                        f"File {f.get('name', '?')!r} exceeds max size "
+                        f"({_format_size(actual_size)} > "
+                        f"{_format_size(provider._max_file_size)})"
+                    )
+            return provider.on_store(files, ctx)
+
+        @self.tool(model=True)
+        def list_files(ctx: Context) -> list[dict]:
+            """List all uploaded files with metadata."""
+            return provider.on_list(ctx)
+
+        @self.tool(model=True)
+        def read_file(name: str, ctx: Context) -> dict:
+            """Read an uploaded file's contents by name."""
+            return provider.on_read(name, ctx)
+
+        @self.ui()
+        def file_manager(ctx: Context) -> PrefabApp:
+            """Upload and manage files. Drop files here to send them to the server."""
+            with Card(css_class="max-w-2xl mx-auto") as view:
+                with CardHeader(), Row(gap=2, align="center"):
+                    H3(provider._title)
+                    with If(STATE.stored.length()):
+                        Badge(
+                            STATE.stored.length(),
+                            variant="secondary",
+                        )
+
+                with CardContent(), Column(gap=4):
+                    Muted(provider._description)
+
+                    DropZone(
+                        name="pending",
+                        icon="inbox",
+                        label=provider._drop_label,
+                        description=(
+                            "Any file type, up to "
+                            f"{_format_size(provider._max_file_size)}"
+                        ),
+                        multiple=True,
+                        max_size=provider._max_file_size,
+                    )
+
+                    with If(STATE.pending.length()), Column(gap=2):
+                        with (
+                            ForEach("pending"),
+                            Row(gap=2, align="center"),
+                            Column(gap=0),
+                        ):
+                            Small(Rx("$item.name"))
+                            Muted(Rx("$item.type"))
+
+                        Button(
+                            "Upload to Server",
+                            on_click=CallTool(
+                                "store_files",
+                                arguments={
+                                    "files": Rx("pending"),
+                                },
+                                on_success=[
+                                    SetState("stored", RESULT),
+                                    SetState("pending", []),
+                                    ShowToast(
+                                        "Files uploaded!",
+                                        variant="success",
+                                    ),
+                                ],
+                                on_error=ShowToast(
+                                    ERROR,
+                                    variant="error",
+                                ),
+                            ),
+                        )
+
+                    with If(STATE.stored.length()):
+                        Separator()
+                        Text(
+                            "Uploaded",
+                            css_class="font-medium text-sm",
+                        )
+                        with (
+                            ForEach("stored") as f,
+                            Row(
+                                gap=2,
+                                align="center",
+                                css_class="justify-between",
+                            ),
+                        ):
+                            with Column(gap=0):
+                                Small(f.name)
+                                Muted(f.uploaded_at)
+                            with Row(gap=2):
+                                Badge(f.type, variant="secondary")
+                                Badge(
+                                    f.size_display,
+                                    variant="outline",
+                                )
+
+                with CardFooter(), Row(align="center", css_class="w-full"):
+                    with If(STATE.stored.length()):
+                        Muted(
+                            f"{STATE.stored.length()}"
+                            f" {STATE.stored.length().pluralize('file')}"
+                            " on server"
+                        )
+                    with Else():
+                        Muted("No files uploaded yet")
+
+            return PrefabApp(
+                view=view,
+                state={
+                    "pending": [],
+                    "stored": provider.on_list(ctx),
+                },
+            )
diff --git a/fastmcp_slim/fastmcp/apps/form.py b/fastmcp_slim/fastmcp/apps/form.py
new file mode 100644
index 0000000..96ee35a
--- /dev/null
+++ b/fastmcp_slim/fastmcp/apps/form.py
@@ -0,0 +1,229 @@
+"""FormInput — a Provider that collects structured input from the user.
+
+Define a Pydantic model for the data you need, and ``FormInput``
+generates a form UI. The user fills it out, the submission is
+validated, and an optional callback processes the result.
+
+Requires ``fastmcp[apps]`` (prefab-ui).
+
+Usage::
+
+    from pydantic import BaseModel
+    from fastmcp import FastMCP
+    from fastmcp.apps.form import FormInput
+
+    class ShippingAddress(BaseModel):
+        street: str
+        city: str
+        state: str
+        zip_code: str
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(FormInput(model=ShippingAddress))
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import Any
+
+from packaging.version import InvalidVersion, Version
+
+try:
+    import prefab_ui
+    from prefab_ui.actions import SetState
+    from prefab_ui.actions.mcp import CallTool, SendMessage
+    from prefab_ui.app import PrefabApp
+    from prefab_ui.components import (
+        H3,
+        Card,
+        CardContent,
+        CardFooter,
+        CardHeader,
+        Column,
+        Form,
+        Muted,
+    )
+    from prefab_ui.components.control_flow import If
+    from prefab_ui.rx import RESULT, STATE
+except ImportError as _exc:
+    raise ImportError(
+        "FormInput requires prefab-ui. Install with: pip install 'fastmcp[apps]'"
+    ) from _exc
+
+# `defaults` kwarg on Form.from_model was added in prefab-ui 0.19.1. Gate on
+# version so that older prefab-ui keeps working — `default` silently no-ops.
+try:
+    _FORM_SUPPORTS_DEFAULTS = Version(prefab_ui.__version__) >= Version("0.19.1")
+except InvalidVersion:
+    _FORM_SUPPORTS_DEFAULTS = False
+
+import pydantic
+
+from fastmcp.apps.app import FastMCPApp
+
+
+def _backfill_boolean_defaults(
+    model: type[pydantic.BaseModel],
+    data: dict[str, Any],
+) -> dict[str, Any]:
+    """Fill in missing boolean fields with their model defaults.
+
+    HTML checkboxes omit the field entirely when unchecked, so the
+    submitted data dict won't contain a key for ``False`` booleans.
+    This backfills those missing keys so Pydantic validation succeeds.
+    """
+    for name, field_info in model.model_fields.items():
+        if name in data:
+            continue
+        if field_info.annotation is bool:
+            if field_info.default is not pydantic.fields.PydanticUndefined:
+                data[name] = field_info.default
+            else:
+                data[name] = False
+    return data
+
+
+class FormInput(FastMCPApp):
+    """A Provider that collects structured input via a Pydantic model.
+
+    Define a model for the data you need, and ``FormInput`` generates
+    a form from it using ``Form.from_model()``. Field types, labels,
+    descriptions, and validation are all derived from the model.
+
+    Optionally provide an ``on_submit`` callback to process the
+    validated data. The callback receives a model instance and returns
+    a string that goes back to the LLM. Without a callback, the
+    validated JSON is sent directly.
+
+    Example::
+
+        from pydantic import BaseModel
+        from fastmcp import FastMCP
+        from fastmcp.apps.form import FormInput
+
+        class Contact(BaseModel):
+            name: str
+            email: str
+
+        mcp = FastMCP("My Server")
+        mcp.add_provider(FormInput(model=Contact))
+
+    With a callback::
+
+        def save_contact(contact: Contact) -> str:
+            db.insert(contact.model_dump())
+            return f"Saved {contact.name}"
+
+        mcp.add_provider(FormInput(model=Contact, on_submit=save_contact))
+    """
+
+    def __init__(
+        self,
+        model: type[pydantic.BaseModel],
+        *,
+        name: str | None = None,
+        title: str | None = None,
+        submit_text: str = "Submit",
+        tool_name: str | None = None,
+        on_submit: Callable[..., str] | None = None,
+        send_message: bool = False,
+    ) -> None:
+        app_name = name or model.__name__
+        super().__init__(app_name)
+        self._model = model
+        self._title = title or model.__name__
+        self._submit_text = submit_text
+        self._tool_name = tool_name or f"collect_{model.__name__.lower()}"
+        self._on_submit = on_submit
+        self._send_message = send_message
+        self._register_tools()
+
+    def __repr__(self) -> str:
+        return f"FormInput({self._model.__name__!r})"
+
+    def _register_tools(self) -> None:
+        provider = self
+        model = self._model
+
+        @self.tool()
+        def submit_form(data: dict[str, Any] | None = None) -> str:
+            """Validate and process form submission."""
+            if data is None:
+                data = {}
+            data = _backfill_boolean_defaults(model, data)
+            validated = model.model_validate(data)
+            if provider._on_submit is not None:
+                return provider._on_submit(validated)
+            return json.dumps(validated.model_dump(mode="json"))
+
+        @self.ui(
+            name=provider._tool_name,
+            description=(
+                f"Collect {model.__name__} information from the user via a form. "
+                f"Call this tool when you need the user to provide "
+                f"{model.__name__} data. The user will see a validated form. "
+                f"After calling this tool, STOP and wait for the user to submit."
+            ),
+        )
+        def collect_input(
+            prompt: str,
+            title: str | None = None,
+            submit_text: str | None = None,
+            default: dict[str, Any] | None = None,
+        ) -> PrefabApp:
+            """Collect structured input from the user.
+
+            Args:
+                prompt: Tell the user what you need and why.
+                title: Optional heading for the form card.
+                submit_text: Optional label for the submit button.
+                default: Optional suggested response — a partial dict of form
+                    field values keyed by field name. The form renders with
+                    those values pre-filled so the user can confirm or edit
+                    rather than start from a blank form. Use this when you
+                    already know (or can infer) what the answer should be.
+                    Requires prefab-ui>=0.19.1; silently ignored on older
+                    versions.
+            """
+            _title = title or provider._title
+            _submit = submit_text or provider._submit_text
+
+            with Card(css_class="max-w-lg mx-auto") as view:
+                with CardHeader():
+                    H3(_title)
+
+                with CardContent(), Column(gap=4):
+                    Muted(prompt)
+
+                    on_success_actions: list[Any] = [
+                        SetState("submitted", True),
+                    ]
+                    if provider._send_message:
+                        on_success_actions.insert(
+                            0,
+                            SendMessage(RESULT),
+                        )
+
+                    from_model_kwargs: dict[str, Any] = {
+                        "submit_label": _submit,
+                        "on_submit": [
+                            CallTool(
+                                "submit_form",
+                                on_success=on_success_actions,
+                            ),
+                        ],
+                    }
+                    if default and _FORM_SUPPORTS_DEFAULTS:
+                        from_model_kwargs["defaults"] = default
+
+                    Form.from_model(model, **from_model_kwargs)
+
+                with CardFooter(), If(STATE.submitted):
+                    Muted("Submitted.")
+
+            return PrefabApp(
+                view=view,
+                state={"submitted": False},
+            )
diff --git a/fastmcp_slim/fastmcp/apps/generative.py b/fastmcp_slim/fastmcp/apps/generative.py
new file mode 100644
index 0000000..0ad78f1
--- /dev/null
+++ b/fastmcp_slim/fastmcp/apps/generative.py
@@ -0,0 +1,199 @@
+"""GenerativeUI — a Provider that adds LLM-generated UI capabilities.
+
+Registers tools and resources from ``prefab_ui.generative`` so that an
+LLM can write Prefab Python code, execute it in a sandbox, and render
+the result as a streaming interactive UI.
+
+Requires ``fastmcp[apps]`` (prefab-ui).
+
+Usage::
+
+    from fastmcp import FastMCP
+    from fastmcp.apps.generative import GenerativeUI
+
+    mcp = FastMCP("My Server")
+    mcp.add_provider(GenerativeUI())
+"""
+
+try:
+    import prefab_ui.generative as _gen
+    from prefab_ui.renderer import (
+        get_generative_renderer_csp,
+        get_generative_renderer_html,
+    )
+except ImportError as _exc:
+    raise ImportError(
+        "GenerativeUI requires prefab-ui. Install with: pip install 'fastmcp[apps]'"
+    ) from _exc
+
+import json
+from collections.abc import AsyncIterator, Sequence
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastmcp.apps.config import AppConfig, ResourceCSP, app_config_to_meta_dict
+from fastmcp.server.providers.base import Provider
+from fastmcp.server.providers.local_provider import LocalProvider
+from fastmcp.tools.base import Tool
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mime import UI_MIME_TYPE
+
+logger = get_logger(__name__)
+
+
+def _build_csp() -> ResourceCSP:
+    """Build CSP from the generative renderer's declared requirements."""
+    csp = get_generative_renderer_csp()
+    return ResourceCSP(
+        resource_domains=csp.get("resource_domains"),
+        connect_domains=csp.get("connect_domains"),
+    )
+
+
+class GenerativeUI(Provider):
+    """A Provider that adds generative UI capabilities to a server.
+
+    Registers:
+
+    - A ``generate_ui`` tool that accepts Prefab Python code, executes
+      it in a Pyodide sandbox, and returns the rendered PrefabApp.
+      Supports streaming via ``ontoolinputpartial``.
+    - A ``components`` tool that searches the Prefab component library.
+    - The generative renderer resource with CSP for Pyodide CDN access.
+
+    Example::
+
+        from fastmcp import FastMCP
+        from fastmcp.apps.generative import GenerativeUI
+
+        mcp = FastMCP("My Server")
+        mcp.add_provider(GenerativeUI())
+    """
+
+    def __init__(
+        self,
+        *,
+        tool_name: str = "generate_prefab_ui",
+        include_components_tool: bool = True,
+        components_tool_name: str = "search_prefab_components",
+    ) -> None:
+        super().__init__()
+        self._tool_name = tool_name
+        self._components_tool_name = components_tool_name
+        self._include_components_tool = include_components_tool
+        self._local = LocalProvider(on_duplicate="error")
+        self._sandbox: Any = None
+        self._setup_done = False
+
+    def __repr__(self) -> str:
+        return f"GenerativeUI(tool_name={self._tool_name!r})"
+
+    def _get_sandbox(self) -> Any:
+        """Lazily create the Pyodide sandbox."""
+        if self._sandbox is None:
+            from prefab_ui.sandbox import Sandbox
+
+            self._sandbox = Sandbox()
+        return self._sandbox
+
+    def _ensure_setup(self) -> None:
+        """Lazily register tools and resources on first access."""
+        if self._setup_done:
+            return
+
+        csp = _build_csp()
+        app_config = AppConfig(resource_uri=_gen.RESOURCE_URI, csp=csp)
+
+        # -- generate_ui tool --
+        # Wraps prefab_ui.generative.execute with sandbox lifecycle management.
+
+        from prefab_ui.app import PrefabApp
+
+        sandbox_ref = self  # capture for closure
+
+        async def generate_ui(
+            code: str,
+            data: str | dict[str, Any] | None = None,
+        ) -> PrefabApp:
+            parsed_data: dict[str, Any] | None
+            if isinstance(data, str):
+                parsed_data = json.loads(data) if data.strip() else None
+            else:
+                parsed_data = data
+            return await _gen.execute(
+                code,
+                data=parsed_data,
+                sandbox=sandbox_ref._get_sandbox(),
+            )
+
+        tool = Tool.from_function(
+            generate_ui,
+            name=self._tool_name,
+            description=_gen.execute.__doc__ or "",
+            meta={"ui": app_config_to_meta_dict(app_config)},
+        )
+        self._local._add_component(tool)
+
+        # -- components tool --
+
+        if self._include_components_tool:
+            components_tool = Tool.from_function(
+                _gen.search_components,
+                name=self._components_tool_name,
+                description=_gen.search_components.__doc__ or "",
+            )
+            self._local._add_component(components_tool)
+
+        # -- generative renderer resource --
+
+        from fastmcp.resources.types import TextResource
+
+        resource_config = AppConfig(csp=csp)
+        resource = TextResource(
+            uri=_gen.RESOURCE_URI,  # type: ignore[arg-type]
+            name="Prefab Generative Renderer",
+            text=get_generative_renderer_html(),
+            mime_type=UI_MIME_TYPE,
+            meta={"ui": app_config_to_meta_dict(resource_config)},
+        )
+        self._local._add_component(resource)
+
+        self._setup_done = True
+
+    # ------------------------------------------------------------------
+    # Provider interface
+    # ------------------------------------------------------------------
+
+    async def _list_tools(self) -> Sequence[Tool]:
+        self._ensure_setup()
+        return await self._local._list_tools()
+
+    async def _get_tool(self, name: str, version: Any = None) -> Tool | None:
+        self._ensure_setup()
+        return await self._local._get_tool(name, version)
+
+    async def _list_resources(self) -> Sequence[Any]:
+        self._ensure_setup()
+        return await self._local._list_resources()
+
+    async def _get_resource(self, uri: str, version: Any = None) -> Any | None:
+        self._ensure_setup()
+        return await self._local._get_resource(uri, version)
+
+    async def _list_resource_templates(self) -> Sequence[Any]:
+        return []
+
+    async def _get_resource_template(self, uri: str, version: Any = None) -> Any | None:
+        return None
+
+    async def _list_prompts(self) -> Sequence[Any]:
+        return []
+
+    async def _get_prompt(self, name: str, version: Any = None) -> Any | None:
+        return None
+
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncIterator[None]:
+        self._ensure_setup()
+        async with self._local.lifespan():
+            yield
diff --git a/fastmcp_slim/fastmcp/cli/__init__.py b/fastmcp_slim/fastmcp/cli/__init__.py
new file mode 100644
index 0000000..9afa621
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/__init__.py
@@ -0,0 +1,8 @@
+"""FastMCP CLI package."""
+
+try:
+    from .cli import app
+except ImportError as exc:
+    from fastmcp import _install_hints
+
+    raise ImportError(_install_hints.CLI_SUPPORT) from exc
diff --git a/fastmcp_slim/fastmcp/cli/__main__.py b/fastmcp_slim/fastmcp/cli/__main__.py
new file mode 100644
index 0000000..92500fb
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/__main__.py
@@ -0,0 +1,5 @@
+"""FastMCP CLI as a runnable package"""
+
+from . import app
+
+app()
diff --git a/fastmcp_slim/fastmcp/cli/apps_dev.py b/fastmcp_slim/fastmcp/cli/apps_dev.py
new file mode 100644
index 0000000..803e0f7
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/apps_dev.py
@@ -0,0 +1,1874 @@
+"""Dev server for previewing FastMCPApp UIs locally.
+
+Starts the user's MCP server on a configurable port, then starts a lightweight
+Starlette dev server that:
+
+  - Serves a Prefab-based tool picker at GET /
+  - Proxies /mcp to the user's server (avoids browser CORS restrictions)
+  - Serves the AppBridge host page at GET /launch
+
+The host page uses @modelcontextprotocol/ext-apps to connect to the MCP server
+and render the selected UI tool inside an iframe.
+
+Startup sequence
+----------------
+1. Download ext-apps app-bridge.js from npm and patch its bare
+   ``@modelcontextprotocol/sdk/…`` imports to use concrete esm.sh URLs.
+2. Detect the exact Zod v4 module URL that esm.sh serves for that SDK version
+   and build an import-map entry that redirects the broken ``v4.mjs`` (which
+   only re-exports ``{z, default}``) to ``v4/classic/index.mjs`` (which
+   correctly exports every named Zod v4 function).  Import maps apply to the
+   full module graph in the document, including cross-origin esm.sh modules.
+3. Serve both the patched JS and the import-map JSON from the dev server.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import html
+import io
+import json
+import logging
+import os
+import re
+import signal
+import sys
+import tarfile
+import tempfile
+import time
+import webbrowser
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlencode
+
+import httpcore
+import httpx
+import uvicorn
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import HTMLResponse, Response, StreamingResponse
+from starlette.routing import Route
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def _json_for_script(value: Any) -> str:
+    """Serialize JSON for embedding inside an HTML script element."""
+    return (
+        json.dumps(value)
+        .replace("&", "\\u0026")
+        .replace("<", "\\u003c")
+        .replace(">", "\\u003e")
+        .replace("\u2028", "\\u2028")
+        .replace("\u2029", "\\u2029")
+    )
+
+
+# ---------------------------------------------------------------------------
+# MCP message log (captures proxy traffic for the dev UI log panel)
+# ---------------------------------------------------------------------------
+
+
+class _MessageLog:
+    """In-memory buffer of MCP JSON-RPC messages flowing through the proxy."""
+
+    def __init__(self) -> None:
+        self._entries: list[dict[str, Any]] = []
+        self._counter = 0
+        self._request_methods: dict[int | str, str] = {}
+        self._request_times: dict[int | str, float] = {}
+
+    def log_request(self, body: dict[str, Any]) -> None:
+        method = body.get("method", "unknown")
+        jsonrpc_id = body.get("id")
+        timestamp = time.time()
+        if jsonrpc_id is not None:
+            self._request_methods[jsonrpc_id] = method
+            self._request_times[jsonrpc_id] = timestamp
+        self._counter += 1
+        self._entries.append(
+            {
+                "id": self._counter,
+                "timestamp": timestamp,
+                "direction": "request",
+                "method": method,
+                "body": body,
+            }
+        )
+
+    def log_response(self, body: dict[str, Any]) -> None:
+        # Server-initiated notifications have "method" but no "id"
+        if "method" in body and "id" not in body:
+            self._counter += 1
+            self._entries.append(
+                {
+                    "id": self._counter,
+                    "timestamp": time.time(),
+                    "direction": "notification",
+                    "method": body.get("method", "unknown"),
+                    "body": body,
+                }
+            )
+            return
+
+        jsonrpc_id = body.get("id")
+        method = (
+            self._request_methods.pop(jsonrpc_id, None)
+            if jsonrpc_id is not None
+            else None
+        )
+        request_time = (
+            self._request_times.pop(jsonrpc_id, None)
+            if jsonrpc_id is not None
+            else None
+        )
+        timestamp = time.time()
+        duration_ms = (
+            round((timestamp - request_time) * 1000, 1) if request_time else None
+        )
+        self._counter += 1
+        self._entries.append(
+            {
+                "id": self._counter,
+                "timestamp": timestamp,
+                "direction": "response",
+                "method": method,
+                "body": body,
+                "duration_ms": duration_ms,
+            }
+        )
+
+    def get_since(self, since_id: int = 0) -> list[dict[str, Any]]:
+        return [e for e in self._entries if e["id"] > since_id]
+
+    def log_bridge(self, body: dict[str, Any]) -> None:
+        method = body.get("method", "unknown")
+        self._counter += 1
+        self._entries.append(
+            {
+                "id": self._counter,
+                "timestamp": time.time(),
+                "direction": "bridge",
+                "method": method,
+                "body": body,
+            }
+        )
+
+    def clear(self) -> None:
+        self._entries.clear()
+        self._request_methods.clear()
+        self._request_times.clear()
+
+
+def _log_response_bytes(log: _MessageLog, raw: bytes, content_type: str) -> None:
+    """Parse accumulated proxy response bytes and log as message entries."""
+    if not raw:
+        return
+    try:
+        if "text/event-stream" in content_type:
+            for line in raw.decode("utf-8", errors="replace").splitlines():
+                if line.startswith("data: "):
+                    with contextlib.suppress(json.JSONDecodeError):
+                        log.log_response(json.loads(line[6:]))
+        else:
+            body = json.loads(raw)
+            if isinstance(body, list):
+                for item in body:
+                    log.log_response(item)
+            else:
+                log.log_response(body)
+    except (json.JSONDecodeError, TypeError):
+        pass
+
+
+_EXT_APPS_VERSION = "1.0.1"
+# Pin to the SDK version ext-apps 1.0.1 was compiled against so the client
+# and transport modules are API-compatible with the app-bridge internals.
+_MCP_SDK_VERSION = "1.25.2"
+
+# ---------------------------------------------------------------------------
+# Shared AppBridge host shell
+# ---------------------------------------------------------------------------
+
+# Both the picker and the app launcher use the same host-page structure: an
+# iframe that hosts a Prefab renderer, wired to the MCP server via AppBridge.
+# The only differences are (a) which URL loads in the iframe and (b) what
+# oninitialized does.
+#
+# app-bridge.js is served locally (see _fetch_app_bridge_bundle).
+# Client/Transport are loaded from esm.sh.
+# The import map (injected as {import_map_tag}) patches the broken esm.sh
+# Zod v4 module so all Zod named exports are visible to the SDK at runtime.
+
+_HOST_SHELL = """\
+<!doctype html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>{title}</title>
+{import_map_tag}
+  <style>
+    html, body {{ margin: 0; padding: 0; width: 100%; height: 100vh; overflow: hidden; }}
+    #app-frame {{ width: 100%; height: 100%; border: none; display: none; }}
+    #status {{
+      display: flex; align-items: center; justify-content: center; height: 100vh;
+      font-family: system-ui, sans-serif; color: #666; font-size: 1rem;
+    }}
+  </style>
+</head>
+<body>
+  <div id="status" style="display:{status_display}">{status_text}</div>
+  <iframe id="app-frame" style="display:{frame_display}"></iframe>
+  <script type="module">
+    import {{ AppBridge, PostMessageTransport }}
+      from "/js/app-bridge.js";
+    import {{ Client }}
+      from "https://esm.sh/@modelcontextprotocol/sdk@{mcp_sdk_version}/client/index.js";
+    import {{ StreamableHTTPClientTransport }}
+      from "https://esm.sh/@modelcontextprotocol/sdk@{mcp_sdk_version}/client/streamableHttp.js";
+
+    const status = document.getElementById("status");
+    const iframe  = document.getElementById("app-frame");
+
+    async function main() {{
+      const client = new Client({{ name: "fastmcp-dev", version: "1.0.0" }});
+      await client.connect(
+        new StreamableHTTPClientTransport(new URL("/mcp", window.location.origin))
+      );
+      const serverCaps = client.getServerCapabilities();
+
+      // Set iframe src after adding load listener to avoid race condition
+      const loaded = new Promise(r => iframe.addEventListener("load", r, {{ once: true }}));
+      iframe.src = {iframe_src_json};
+      await loaded;
+
+      const transport = new PostMessageTransport(
+        iframe.contentWindow,
+        iframe.contentWindow,
+      );
+      const bridge = new AppBridge(
+        client,
+        {{ name: "fastmcp-dev", version: "1.0.0" }},
+        {{
+          openLinks: {{}},
+          serverTools: serverCaps?.tools,
+          serverResources: serverCaps?.resources,
+        }},
+        {{
+          hostContext: {{
+            theme: window.matchMedia("(prefers-color-scheme: dark)").matches
+              ? "dark" : "light",
+            platform: "web",
+            containerDimensions: {{ maxHeight: 8000 }},
+            displayMode: "inline",
+            availableDisplayModes: ["inline", "fullscreen"],
+          }},
+        }},
+      );
+
+      bridge.onmessage = async () => ({{}});
+      {on_open_link}
+      {on_initialized}
+
+      await bridge.connect(transport);
+    }}
+
+    main().catch(err => {{
+      console.error(err);
+      if (status) {{
+        status.style.display = "flex";
+        status.textContent = "Error: " + err.message;
+      }}
+    }});
+  </script>
+</body>
+</html>
+"""
+
+# ---------------------------------------------------------------------------
+# Host page HTML
+# ---------------------------------------------------------------------------
+
+_HOST_HTML_TEMPLATE = """\
+<!doctype html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>FastMCP Dev — {tool_name}</title>
+{import_map_tag}
+  <style>
+    html, body {{ margin: 0; padding: 0; width: 100%; height: 100vh; overflow: hidden; }}
+    #app-frame {{ width: 100%; height: 100%; border: none; display: none; }}
+    #status {{
+      display: flex; align-items: center; justify-content: center; height: 100vh;
+      font-family: system-ui, sans-serif; color: #666; font-size: 1rem;
+    }}
+  </style>
+</head>
+<body>
+  <div id="status">Launching {tool_name}…</div>
+  <iframe id="app-frame"></iframe>
+  <script type="module">
+    import {{ AppBridge, PostMessageTransport, getToolUiResourceUri }}
+      from "/js/app-bridge.js";
+    import {{ Client }}
+      from "https://esm.sh/@modelcontextprotocol/sdk@{mcp_sdk_version}/client/index.js";
+    import {{ StreamableHTTPClientTransport }}
+      from "https://esm.sh/@modelcontextprotocol/sdk@{mcp_sdk_version}/client/streamableHttp.js";
+
+    const toolName = {tool_name_json};
+    const toolArgs = {tool_args_json};
+    const status = document.getElementById("status");
+    const iframe  = document.getElementById("app-frame");
+
+    async function main() {{
+      // Connect to the proxied MCP server (same-origin, no CORS needed)
+      const client = new Client({{ name: "fastmcp-dev", version: "1.0.0" }});
+      await client.connect(
+        new StreamableHTTPClientTransport(new URL("/mcp", window.location.origin))
+      );
+
+      // Find the tool and its UI resource URI
+      const {{ tools }} = await client.listTools();
+      const tool = tools.find(t => t.name === toolName);
+      if (!tool) throw new Error("Tool not found: " + toolName);
+
+      const uiUri = getToolUiResourceUri(tool);
+      if (!uiUri) throw new Error("Tool has no UI resource: " + toolName);
+
+      // The Prefab renderer calls earlyBridge.connect() at module-load time
+      // (synchronously, before React mounts) so it sends its ui/initialize
+      // request very early — potentially before the iframe's load event fires.
+      // Fix: create the AppBridge and call bridge.connect() BEFORE loading the
+      // iframe so our window.addEventListener is registered first.  We pass
+      // null as the PostMessageTransport source so early messages from the
+      // not-yet-known renderer window are not filtered out.  After the iframe
+      // loads we update transport.eventTarget / .eventSource to the real
+      // renderer window; the load-event microtask always runs before the
+      // message macrotask, so the response reaches the correct window.
+      const serverCaps = client.getServerCapabilities();
+      const transport = new PostMessageTransport(iframe.contentWindow, null);
+      const bridge = new AppBridge(
+        client,
+        {{ name: "fastmcp-dev", version: "1.0.0" }},
+        {{
+          openLinks: {{}},
+          serverTools: serverCaps?.tools,
+          serverResources: serverCaps?.resources,
+        }},
+        {{
+          hostContext: {{
+            theme: window.matchMedia("(prefers-color-scheme: dark)").matches
+              ? "dark" : "light",
+            platform: "web",
+            containerDimensions: {{ maxHeight: 8000 }},
+            displayMode: "inline",
+            availableDisplayModes: ["inline", "fullscreen"],
+          }},
+        }},
+      );
+
+      bridge.onopenlink = async ({{ url }}) => {{
+        window.open(url, "_blank", "noopener,noreferrer");
+        return {{}};
+      }};
+      bridge.onmessage = async () => ({{}});
+
+      // When the View initializes: send input args, call the tool, send result
+      bridge.oninitialized = async () => {{
+        await bridge.sendToolInput({{ arguments: toolArgs }});
+        const result = await client.callTool({{ name: toolName, arguments: toolArgs }});
+        await bridge.sendToolResult(result);
+        status.style.display = "none";
+        iframe.style.display = "block";
+        // Prevent horizontal scrollbar when vertical scrollbar appears
+        try {{ iframe.contentDocument.documentElement.style.overflowX = "hidden"; }} catch(e) {{}}
+      }};
+
+      // Start listening before the iframe loads
+      await bridge.connect(transport);
+
+      // Now load the renderer HTML via the server-side proxy
+      const frameUrl = "/ui-resource?uri=" + encodeURIComponent(uiUri);
+      const loaded = new Promise(r => {{ iframe.addEventListener("load", r, {{ once: true }}); }});
+      iframe.src = frameUrl;
+      await loaded;
+
+      // Update transport to the real renderer window.  This microtask runs
+      // before the ui/initialize message macrotask, ensuring the response
+      // is dispatched to the correct window.
+      transport.eventTarget = iframe.contentWindow;
+      transport.eventSource = iframe.contentWindow;
+    }}
+
+    main().catch(err => {{
+      status.textContent = "Error: " + err.message;
+      console.error(err);
+    }});
+  </script>
+</body>
+</html>
+"""
+
+# ---------------------------------------------------------------------------
+# Dev log panel (injected into host pages)
+# ---------------------------------------------------------------------------
+
+_LOG_PANEL_HTML = """\
+<style>
+  #mcp-log-panel {
+    position: fixed; top: 0; left: 0; bottom: 0; width: 360px;
+    z-index: 10000;
+    font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
+    font-size: 12px; background: #1e1e2e; color: #cdd6f4;
+    border-right: 1px solid #45475a;
+    display: flex; flex-direction: column;
+  }
+  #mcp-log-panel.hidden { display: none; }
+  #app-frame {
+    width: 100% !important; height: 100% !important;
+    margin-left: 0 !important;
+  }
+  #mcp-log-resize {
+    position: absolute; right: -3px; top: 0; bottom: 0; width: 6px;
+    cursor: col-resize; z-index: 1;
+  }
+  #mcp-log-resize:hover, #mcp-log-resize.active { background: #585b70; }
+  #mcp-log-header {
+    display: flex; justify-content: space-between; align-items: center;
+    padding: 10px 12px; background: #181825;
+    border-bottom: 1px solid #45475a; flex-shrink: 0;
+  }
+  #mcp-log-brand {
+    display: flex; align-items: center; gap: 8px;
+  }
+  #mcp-log-brand svg { flex-shrink: 0; }
+  #mcp-log-brand-text {
+    font-weight: 700; font-size: 13px; color: #cdd6f4;
+    letter-spacing: -0.3px;
+  }
+  #mcp-log-count-badge {
+    font-size: 11px; color: #6c7086; font-weight: 400;
+  }
+  #mcp-log-actions { display: flex; gap: 6px; }
+  #mcp-log-actions button {
+    background: #313244; color: #cdd6f4; border: 1px solid #45475a;
+    padding: 2px 8px; border-radius: 3px; cursor: pointer;
+    font-size: 11px; font-family: inherit;
+  }
+  #mcp-log-actions button:hover { background: #45475a; }
+  #mcp-log-entries { flex: 1; overflow-y: auto; }
+  .log-entry {
+    padding: 6px 12px; border-bottom: 1px solid #232334; cursor: pointer;
+  }
+  .log-entry:hover { background: #313244; }
+  .log-entry.error { background: rgba(243, 139, 168, 0.08); }
+  .log-entry.error:hover { background: rgba(243, 139, 168, 0.14); }
+  .log-entry.error .log-method { color: #f38ba8; }
+  .log-primary {
+    display: flex; justify-content: space-between;
+    align-items: baseline; gap: 8px;
+  }
+  .log-left {
+    display: flex; gap: 6px; align-items: baseline; min-width: 0;
+  }
+  .log-dir { flex-shrink: 0; }
+  .log-dir.request { color: #89b4fa; }
+  .log-dir.response { color: #a6e3a1; }
+  .log-dir.error { color: #f38ba8; }
+  .log-dir.bridge { color: #cba6f7; }
+  .log-dir.notification { color: #fab387; }
+  .log-method {
+    color: #f9e2af; font-weight: 600;
+    white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+  }
+  .log-meta { color: #6c7086; font-size: 11px; white-space: nowrap; flex-shrink: 0; }
+  .log-subtitle {
+    color: #a6adc8; font-size: 11px; padding-left: 22px;
+    overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+    margin-top: 1px;
+  }
+  .log-detail {
+    display: none; padding: 8px 12px 4px 22px; background: #11111b;
+    white-space: pre-wrap; word-break: break-all;
+    color: #bac2de; font-size: 11px; line-height: 1.4;
+    margin-top: 4px; border-radius: 4px;
+  }
+  .log-entry.expanded .log-detail { display: block; }
+  @keyframes log-flash {
+    from { background: rgba(137, 180, 250, 0.22); }
+    to { background: transparent; }
+  }
+  @keyframes log-flash-error {
+    from { background: rgba(243, 139, 168, 0.25); }
+    to { background: rgba(243, 139, 168, 0.08); }
+  }
+  .log-entry.new { animation: log-flash 2s ease-out; }
+  .log-entry.error.new { animation: log-flash-error 2s ease-out; }
+  .log-copy {
+    opacity: 0; transition: opacity 0.15s;
+    background: #313244; color: #a6adc8; border: 1px solid #45475a;
+    padding: 1px 6px; border-radius: 3px; cursor: pointer;
+    font-size: 10px; font-family: inherit; flex-shrink: 0;
+  }
+  .log-entry:hover .log-copy { opacity: 1; }
+  .log-copy:hover { background: #45475a; color: #cdd6f4; }
+  #mcp-log-open {
+    position: fixed; bottom: 12px; left: 12px; z-index: 10000;
+    background: #181825; color: #cdd6f4; border: 1px solid #45475a;
+    padding: 6px 12px; border-radius: 6px; cursor: pointer;
+    font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
+    font-size: 11px; display: block;
+  }
+  #mcp-log-open:hover { background: #313244; }
+  #mcp-log-filters {
+    display: flex; gap: 8px; align-items: center;
+    padding: 6px 12px; border-bottom: 1px solid #45475a; flex-shrink: 0;
+  }
+  .log-seg {
+    display: inline-flex; border: 1px solid #45475a; border-radius: 6px;
+    overflow: hidden;
+  }
+  .log-seg button {
+    background: transparent; color: #6c7086; border: none;
+    border-right: 1px solid #45475a; padding: 3px 10px; cursor: pointer;
+    font-size: 10px; font-family: inherit; transition: all 0.15s;
+  }
+  .log-seg button:last-child { border-right: none; }
+  .log-seg button:hover { background: rgba(205, 214, 244, 0.06); }
+  .log-seg button.active[data-filter="tools"] { background: rgba(137, 180, 250, 0.15); color: #89b4fa; }
+  .log-seg button.active[data-filter="notifications"] { background: rgba(250, 179, 135, 0.15); color: #fab387; }
+  .log-seg button.active[data-filter="bridge"] { background: rgba(203, 166, 247, 0.15); color: #cba6f7; }
+  .log-seg button.active[data-filter="errors"] { background: rgba(243, 139, 168, 0.15); color: #f38ba8; }
+  #mcp-log-filters-label {
+    font-size: 9px; color: #6c7086; text-transform: uppercase;
+    letter-spacing: 0.5px; font-weight: 600;
+  }
+  #mcp-log-level-select {
+    background: #313244; color: #cdd6f4; border: 1px solid #45475a;
+    border-radius: 6px; padding: 3px 8px; cursor: pointer;
+    font-size: 10px; font-family: inherit;
+  }
+  #mcp-log-level-select option { background: #1e1e2e; }
+  .log-level {
+    font-size: 9px; padding: 0 5px; border-radius: 3px;
+    font-weight: 600; text-transform: uppercase; letter-spacing: 0.3px;
+    flex-shrink: 0; line-height: 16px;
+  }
+  .log-level-debug { background: #313244; color: #6c7086; }
+  .log-level-info { background: rgba(137, 180, 250, 0.15); color: #89b4fa; }
+  .log-level-warning { background: rgba(249, 226, 175, 0.15); color: #f9e2af; }
+  .log-level-error { background: rgba(243, 139, 168, 0.15); color: #f38ba8; }
+  .log-level-notice { background: rgba(148, 226, 213, 0.15); color: #94e2d5; }
+  .log-level-critical { background: rgba(243, 139, 168, 0.2); color: #f38ba8; }
+  .log-level-alert { background: rgba(243, 139, 168, 0.25); color: #f38ba8; }
+  .log-level-emergency { background: rgba(243, 139, 168, 0.3); color: #f38ba8; }
+</style>
+<div id="mcp-log-panel" class="hidden">
+  <div id="mcp-log-resize"></div>
+  <div id="mcp-log-header">
+    <div id="mcp-log-brand">
+      <svg width="20" height="20" viewBox="0 0 196 196" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M145.747 44.611L145.355 44.3877L144.96 44.611L86.0283 78.5276V171.267L86.4014 171.499L99.6674 179.667V86.3859L159 52.2379L145.747 44.611Z" fill="#cdd6f4"/><path d="M121.616 30.2714L121.224 30.0454L120.832 30.2714L61.8975 64.188V156.928L62.2732 157.156L75.5393 165.325V72.0463L134.869 37.8983L121.616 30.2714Z" fill="#cdd6f4"/><path d="M97.4894 16.3818L97.0973 16.1558L96.7025 16.3818L37.7705 50.3038V142.066L51.4096 150.463V58.1567L110.742 24.0086L97.4894 16.3818Z" fill="#cdd6f4"/><path d="M131.23 113.671L124.979 117.266L124.584 117.494V117.5L116.796 121.987L110.547 125.581L110.152 125.807V141.51L144.564 121.709V121.698L158.999 113.394V97.6851L139.277 109.034L131.23 113.671Z" fill="#cdd6f4"/></svg>
+      <span id="mcp-log-brand-text">FastMCP Apps</span>
+      <span id="mcp-log-count-badge">\u00b7 <span id="mcp-log-count">0</span></span>
+    </div>
+    <div id="mcp-log-actions">
+      <button id="mcp-log-reset" onclick="window.location.href='/'">&#8592; Back</button>
+      <script>if (window.location.pathname === "/") document.getElementById("mcp-log-reset").style.display = "none";</script>
+      <button id="mcp-log-clear">Clear</button>
+      <button id="mcp-log-close">\u00d7</button>
+    </div>
+  </div>
+  <div id="mcp-log-filters">
+    <span id="mcp-log-filters-label">Show</span>
+    <div class="log-seg">
+      <button class="active" data-filter="tools">Tools</button>
+      <button class="active" data-filter="notifications">Logs</button>
+      <button class="active" data-filter="bridge">Host</button>
+      <button class="active" data-filter="errors">Errors</button>
+    </div>
+    <select id="mcp-log-level-select">
+      <option value="debug">Debug+</option>
+      <option value="info">Info+</option>
+      <option value="warning">Warn+</option>
+      <option value="error">Error+</option>
+      <option value="critical">Critical+</option>
+    </select>
+  </div>
+  <div id="mcp-log-entries"></div>
+</div>
+<button id="mcp-log-open">MCP Log</button>
+<script>
+(function() {
+  var lastId = 0, totalCount = 0, panelWidth = 360;
+  var panel = document.getElementById("mcp-log-panel");
+  var entries = document.getElementById("mcp-log-entries");
+  var countEl = document.getElementById("mcp-log-count");
+  var openBtn = document.getElementById("mcp-log-open");
+  var resizeHandle = document.getElementById("mcp-log-resize");
+  var allFilterKeys = ["tools", "notifications", "bridge", "errors"];
+
+  function syncURL() {
+    var params = new URLSearchParams(window.location.search);
+    if (!panel.classList.contains("hidden")) {
+      params.set("log", "open");
+    } else {
+      params.delete("log");
+    }
+    var on = [];
+    for (var i = 0; i < allFilterKeys.length; i++) {
+      if (activeFilters[allFilterKeys[i]]) on.push(allFilterKeys[i]);
+    }
+    if (on.length === allFilterKeys.length) {
+      params.delete("filters");
+    } else {
+      params.set("filters", on.join(","));
+    }
+    if (minLevel === 0) {
+      params.delete("level");
+    } else {
+      params.set("level", levelOrder[minLevel]);
+    }
+    var qs = params.toString();
+    var url = window.location.pathname + (qs ? "?" + qs : "");
+    history.replaceState(null, "", url);
+  }
+
+  function setFrameLayout(w) {
+    var frame = document.getElementById("app-frame");
+    if (!frame) return;
+    frame.style.setProperty("width", w, "important");
+    frame.style.setProperty("margin-left", w === "100%" ? "0" : panelWidth + "px", "important");
+  }
+
+  document.getElementById("mcp-log-close").addEventListener("click", function() {
+    panel.classList.add("hidden");
+    openBtn.style.display = "block";
+    setFrameLayout("100%");
+    syncURL();
+  });
+
+  openBtn.addEventListener("click", function() {
+    panel.classList.remove("hidden");
+    openBtn.style.display = "none";
+    setFrameLayout("calc(100% - " + panelWidth + "px)");
+    entries.scrollTop = entries.scrollHeight;
+    syncURL();
+  });
+
+  resizeHandle.addEventListener("mousedown", function(e) {
+    e.preventDefault();
+    resizeHandle.classList.add("active");
+    var frame = document.getElementById("app-frame");
+    if (frame) frame.style.pointerEvents = "none";
+    document.addEventListener("mousemove", onResize);
+    document.addEventListener("mouseup", stopResize);
+  });
+
+  function onResize(e) {
+    var w = Math.max(200, Math.min(e.clientX, window.innerWidth * 0.8));
+    panelWidth = w;
+    panel.style.width = w + "px";
+    setFrameLayout("calc(100% - " + w + "px)");
+  }
+
+  function stopResize() {
+    resizeHandle.classList.remove("active");
+    var frame = document.getElementById("app-frame");
+    if (frame) frame.style.pointerEvents = "";
+    document.removeEventListener("mousemove", onResize);
+    document.removeEventListener("mouseup", stopResize);
+  }
+
+  document.getElementById("mcp-log-clear").addEventListener("click", function() {
+    entries.innerHTML = "";
+    totalCount = 0;
+    countEl.textContent = "0";
+    fetch("/api/logs/clear", { method: "POST" });
+  });
+
+  var activeFilters = {tools: true, notifications: true, bridge: true, errors: true};
+  var levelOrder = ["debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"];
+  var minLevel = 0;
+
+  // Restore state from URL params
+  (function restoreURL() {
+    var params = new URLSearchParams(window.location.search);
+    if (params.get("log") === "open") {
+      panel.classList.remove("hidden");
+      openBtn.style.display = "none";
+      setFrameLayout("calc(100% - " + panelWidth + "px)");
+    }
+    var fp = params.get("filters");
+    if (fp !== null) {
+      var on = fp ? fp.split(",") : [];
+      for (var i = 0; i < allFilterKeys.length; i++) {
+        var k = allFilterKeys[i];
+        activeFilters[k] = on.indexOf(k) !== -1;
+        var btn = document.querySelector("[data-filter='" + k + "']");
+        if (btn) btn.classList.toggle("active", activeFilters[k]);
+      }
+    }
+    var lp = params.get("level");
+    if (lp) {
+      var idx = levelOrder.indexOf(lp);
+      if (idx >= 0) {
+        minLevel = idx;
+        document.getElementById("mcp-log-level-select").value = lp;
+      }
+    }
+  })();
+
+  document.getElementById("mcp-log-filters").addEventListener("click", function(e) {
+    var btn = e.target.closest("[data-filter]");
+    if (!btn) return;
+    var f = btn.dataset.filter;
+    activeFilters[f] = !activeFilters[f];
+    btn.classList.toggle("active", activeFilters[f]);
+    applyFilters();
+    syncURL();
+  });
+
+  document.getElementById("mcp-log-level-select").addEventListener("change", function(e) {
+    minLevel = levelOrder.indexOf(e.target.value);
+    applyFilters();
+    syncURL();
+  });
+
+  function shouldShow(el) {
+    var cat = el.dataset.category || "";
+    if (activeFilters[cat] === false) return false;
+    var lv = el.dataset.level;
+    if (lv && levelOrder.indexOf(lv) < minLevel) return false;
+    return true;
+  }
+
+  function applyFilters() {
+    var items = entries.querySelectorAll(".log-entry");
+    for (var i = 0; i < items.length; i++) {
+      items[i].style.display = shouldShow(items[i]) ? "" : "none";
+    }
+  }
+
+  function summarize(entry) {
+    var b = entry.body;
+    if (!b) return "";
+    if (entry.direction === "request" || entry.direction === "notification") {
+      if (b.method === "tools/call" && b.params) return b.params.name || "";
+      if (b.method === "resources/read" && b.params) return b.params.uri || "";
+      if (b.method === "notifications/message" && b.params) {
+        var d = b.params.data;
+        if (d && typeof d === "object") return d.msg || d.message || JSON.stringify(d);
+        return d || b.params.level || "";
+      }
+      return "";
+    }
+    if (b.error) return "error: " + (b.error.message || JSON.stringify(b.error));
+    if (b.result && typeof b.result === "object") {
+      if (Array.isArray(b.result.tools)) return b.result.tools.length + " tools";
+      if (Array.isArray(b.result.resources)) return b.result.resources.length + " resources";
+      if (Array.isArray(b.result.prompts)) return b.result.prompts.length + " prompts";
+      if (b.result.content) {
+        var first = b.result.content[0];
+        if (first && first.text) {
+          return first.text.length > 60 ? first.text.slice(0, 60) + "\u2026" : first.text;
+        }
+        return b.result.content.length + " content item(s)";
+      }
+    }
+    return "";
+  }
+
+  function formatTime(ts) {
+    var d = new Date(ts * 1000);
+    return String(d.getHours()).padStart(2, "0") + ":"
+      + String(d.getMinutes()).padStart(2, "0") + ":"
+      + String(d.getSeconds()).padStart(2, "0");
+  }
+
+  function renderEntry(entry) {
+    var div = document.createElement("div");
+    var isError = entry.direction === "response" && entry.body
+      && (entry.body.error || (entry.body.result && entry.body.result.isError));
+    div.className = "log-entry" + (isError ? " error" : "");
+    var dirClass = isError ? "error" : entry.direction;
+    var arrows = {request: "\u2192", response: "\u2190", bridge: "\u2191", notification: "\u2193"};
+
+    // Categorize for filtering
+    if (isError) div.dataset.category = "errors";
+    else if (entry.direction === "bridge") div.dataset.category = "bridge";
+    else if (entry.direction === "notification") div.dataset.category = "notifications";
+    else div.dataset.category = "tools";
+
+    var primary = document.createElement("div");
+    primary.className = "log-primary";
+
+    var left = document.createElement("div");
+    left.className = "log-left";
+
+    var dirEl = document.createElement("span");
+    dirEl.className = "log-dir " + dirClass;
+    dirEl.textContent = arrows[entry.direction] || "\u2190";
+
+    var methodEl = document.createElement("span");
+    methodEl.className = "log-method";
+    methodEl.textContent = entry.method || "";
+
+    left.appendChild(dirEl);
+    left.appendChild(methodEl);
+
+    // Log level badge for notifications
+    if (entry.direction === "notification" && entry.body && entry.body.params) {
+      var level = (entry.body.params.level || "").toLowerCase();
+      if (level) {
+        div.dataset.level = level;
+        var lvl = document.createElement("span");
+        lvl.className = "log-level log-level-" + level;
+        lvl.textContent = level;
+        left.appendChild(lvl);
+      }
+    }
+
+    var metaEl = document.createElement("span");
+    metaEl.className = "log-meta";
+    metaEl.textContent = entry.duration_ms != null
+      ? entry.duration_ms + "ms"
+      : formatTime(entry.timestamp);
+
+    var copyBtn = document.createElement("button");
+    copyBtn.className = "log-copy";
+    copyBtn.textContent = "Copy";
+    copyBtn.addEventListener("click", function(e) {
+      e.stopPropagation();
+      navigator.clipboard.writeText(JSON.stringify(entry.body, null, 2));
+      copyBtn.textContent = "Copied";
+      setTimeout(function() { copyBtn.textContent = "Copy"; }, 1000);
+    });
+
+    primary.appendChild(left);
+    primary.appendChild(metaEl);
+    primary.appendChild(copyBtn);
+    div.appendChild(primary);
+
+    var summary = summarize(entry);
+    if (summary) {
+      var subtitle = document.createElement("div");
+      subtitle.className = "log-subtitle";
+      subtitle.textContent = summary;
+      div.appendChild(subtitle);
+    }
+
+    var detail = document.createElement("div");
+    detail.className = "log-detail";
+    detail.textContent = JSON.stringify(entry.body, null, 2);
+    div.appendChild(detail);
+
+    div.addEventListener("click", function() { div.classList.toggle("expanded"); });
+    return div;
+  }
+
+  var polling = false;
+  var firstPoll = true;
+  function poll() {
+    if (polling) return;
+    polling = true;
+    fetch("/api/logs?since=" + lastId)
+      .then(function(r) { return r.ok ? r.json() : []; })
+      .then(function(data) {
+        if (!data || !data.length) return;
+        lastId = data[data.length - 1].id;
+        totalCount += data.length;
+        countEl.textContent = String(totalCount);
+        var panelVisible = !panel.classList.contains("hidden");
+        var atBottom = !panelVisible || entries.scrollHeight - entries.scrollTop - entries.clientHeight < 40;
+        for (var i = 0; i < data.length; i++) {
+          var el = renderEntry(data[i]);
+          el.classList.add("new");
+          if (!shouldShow(el)) el.style.display = "none";
+          entries.appendChild(el);
+        }
+        if (atBottom || (firstPoll && panelVisible)) entries.scrollTop = entries.scrollHeight;
+        firstPoll = false;
+      })
+      .catch(function() {})
+      .finally(function() { polling = false; });
+  }
+
+  window.addEventListener("message", function(event) {
+    var data = event.data;
+    if (typeof data === "string") {
+      try { data = JSON.parse(data); } catch(e) { return; }
+    }
+    if (!data || typeof data !== "object") return;
+    if (!data.jsonrpc && !data.method) return;
+    fetch("/api/logs/bridge", {
+      method: "POST",
+      headers: {"Content-Type": "application/json"},
+      body: JSON.stringify({body: data})
+    });
+  });
+
+  setInterval(poll, 500);
+  poll();
+})();
+</script>
+"""
+
+
+def _inject_log_panel(html: str) -> str:
+    """Inject the MCP message log panel before </body>."""
+    return html.replace("</body>", _LOG_PANEL_HTML + "\n</body>")
+
+
+# ---------------------------------------------------------------------------
+# Picker UI (Prefab-based, built in Python)
+# ---------------------------------------------------------------------------
+
+
+def _has_ui_resource(tool: dict[str, Any]) -> bool:
+    """Return True if the tool has a UI resourceUri in its metadata."""
+    for key in ("meta", "_meta"):
+        m = tool.get(key)
+        if isinstance(m, dict):
+            ui = m.get("ui")
+            if isinstance(ui, dict) and ui.get("resourceUri"):
+                return True
+    return False
+
+
+def _model_from_schema(tool_name: str, input_schema: dict[str, Any]) -> type[Any]:
+    """Dynamically create a Pydantic model from a JSON Schema for form generation."""
+    import pydantic
+    import pydantic.fields
+
+    properties: dict[str, Any] = input_schema.get("properties") or {}
+    required: list[str] = input_schema.get("required") or []
+
+    field_definitions: dict[str, Any] = {}
+    for prop_name, prop in properties.items():
+        json_type = prop.get("type", "string")
+
+        # Handle anyOf / oneOf (union types like str | dict | None)
+        for key in ("anyOf", "oneOf"):
+            if key in prop:
+                non_null = [
+                    t
+                    for t in prop[key]
+                    if isinstance(t, dict) and t.get("type") != "null"
+                ]
+                if non_null:
+                    types = [t.get("type") for t in non_null if "type" in t]
+                    # Prefer object/array (need textarea for JSON editing),
+                    # then string (most versatile text input), then scalars.
+                    for candidate in (
+                        "object",
+                        "array",
+                        "string",
+                        "integer",
+                        "number",
+                        "boolean",
+                    ):
+                        if candidate in types:
+                            json_type = candidate
+                            break
+                break
+
+        match json_type:
+            case "integer":
+                py_type: type = int
+            case "number":
+                py_type = float
+            case "boolean":
+                py_type = bool
+            case "object" | "array":
+                # Render as a string textarea; api_launch parses JSON later
+                py_type = str
+            case _:
+                py_type = str
+
+        title = prop.get("title") or prop_name.replace("_", " ").title()
+        description = prop.get("description")
+        is_required = prop_name in required
+        if is_required:
+            default = pydantic.fields.PydanticUndefined
+        elif "default" in prop:
+            default = prop["default"]
+        else:
+            default = None
+            py_type = py_type | None  # type: ignore[assignment]  # ty:ignore[invalid-assignment]
+
+        extra: dict[str, Any] = {}
+        if prop.get("enum"):
+            from typing import Literal
+
+            py_type = Literal[tuple(prop["enum"])]  # type: ignore[assignment]  # ty:ignore[invalid-type-form]
+
+        # Textarea detection:
+        # 1. Explicit format: "textarea" in JSON schema
+        # 2. UI annotation: {"ui": {"type": "textarea"}} (json_schema_extra merged flat)
+        # 3. Object/array types need multiline JSON editing
+        use_textarea = (
+            prop.get("format") == "textarea"
+            or (
+                isinstance(prop.get("ui"), dict)
+                and prop["ui"].get("type") == "textarea"
+            )
+            or json_type in ("object", "array")
+        )
+        if use_textarea:
+            extra["json_schema_extra"] = {"ui": {"type": "textarea"}}
+
+        field_definitions[prop_name] = (
+            py_type,
+            pydantic.Field(
+                default=default, title=title, description=description, **extra
+            ),
+        )
+
+    return pydantic.create_model(f"{tool_name.title()}Form", **field_definitions)
+
+
+def _build_picker_html(tools: list[dict[str, Any]]) -> str:
+    """Build Prefab picker page: dropdown selector with per-tool forms."""
+    try:
+        from prefab_ui.actions import Fetch, OpenLink, SetState, ShowToast
+        from prefab_ui.app import PrefabApp
+        from prefab_ui.components import (
+            Button,
+            Column,
+            Heading,
+            Label,
+            Markdown,
+            Muted,
+            Page,
+            Pages,
+            Select,
+            SelectOption,
+            Textarea,
+        )
+        from prefab_ui.components.form import Form
+        from prefab_ui.rx import RESULT, Rx
+    except ImportError:
+        return "<html><body><p>prefab-ui not installed. Run: pip install fastmcp[apps]</p></body></html>"
+
+    if not tools:
+        with Column(gap=4, css_class="p-6 max-w-2xl mx-auto") as view:
+            Heading("FastMCP Apps")
+            Muted(
+                "No UI tools found on this server. Use @app.ui() to register entry-point tools."
+            )
+        return PrefabApp(title="FastMCP Apps", view=view).html()
+
+    first_name: str = tools[0]["name"]
+
+    def _tool_title(tool: dict[str, Any]) -> str:
+        return tool.get("title") or tool["name"]
+
+    with Column(gap=6, css_class="p-8 max-w-2xl mx-auto") as view:
+        Heading("FastMCP Apps")
+
+        if len(tools) > 1:
+            with Column(gap=1):
+                Label("Tool")
+                with Select(
+                    placeholder="Choose a tool…",
+                    on_change=SetState("activeTool", Rx("$event")),
+                ):
+                    for tool in tools:
+                        SelectOption(
+                            _tool_title(tool),
+                            value=tool["name"],
+                            selected=tool["name"] == first_name,
+                        )
+        else:
+            Heading(_tool_title(tools[0]), level=3)
+
+        with Pages(name="activeTool", value=first_name):
+            for tool in tools:
+                name: str = tool["name"]
+                desc: str = tool.get("description") or ""
+                input_schema: dict[str, Any] = tool.get("inputSchema") or {}
+                model = _model_from_schema(name, input_schema)
+
+                form_body: dict[str, Any] = {"tool": name}
+                for field_name in model.model_fields:
+                    form_body[field_name] = Rx(field_name)
+
+                json_body: dict[str, Any] = {
+                    "tool": name,
+                    "__json_args__": Rx("__json_args__"),
+                }
+
+                on_error = ShowToast(Rx("$error"), variant="error")  # type: ignore[arg-type]
+
+                input_mode = f"_mode_{name}"
+                _desc_max_lines = 10
+                with Page(name, value=name), Column(gap=4):
+                    if desc:
+                        lines = desc.split("\n")
+                        md_css = "text-sm text-muted-foreground"
+                        if len(lines) <= _desc_max_lines:
+                            Markdown(desc, css_class=md_css)
+                        else:
+                            desc_state = f"_desc_{name}"
+                            short = "\n".join(lines[:_desc_max_lines])
+                            with Pages(name=desc_state, value="short"):
+                                with (
+                                    Page("short", value="short"),
+                                    Column(gap=1, css_class="items-start"),
+                                ):
+                                    Markdown(short, css_class=md_css)
+                                    Button(
+                                        "Show more \u25be",
+                                        variant="link",
+                                        size="xs",
+                                        on_click=SetState(desc_state, "full"),
+                                        css_class="text-muted-foreground p-0 h-auto",
+                                    )
+                                with (
+                                    Page("full", value="full"),
+                                    Column(gap=1, css_class="items-start"),
+                                ):
+                                    Markdown(desc, css_class=md_css)
+                                    Button(
+                                        "Show less \u25b4",
+                                        variant="link",
+                                        size="xs",
+                                        on_click=SetState(desc_state, "short"),
+                                        css_class="text-muted-foreground p-0 h-auto",
+                                    )
+
+                    with Pages(name=input_mode, value="form"):
+                        with Page("form", value="form"), Column(gap=4):
+                            with Column(gap=1, css_class="items-start"):
+                                Heading("Arguments", level=3)
+                                Button(
+                                    "Edit as JSON",
+                                    variant="link",
+                                    size="xs",
+                                    on_click=SetState(input_mode, "json"),
+                                    css_class="text-muted-foreground p-0 h-auto",
+                                )
+                            with Form(
+                                on_submit=Fetch.post(
+                                    "/api/launch",
+                                    body=form_body,
+                                    on_success=OpenLink(RESULT),
+                                    on_error=on_error,
+                                ),
+                            ):
+                                Form.from_model(model, fields_only=True)
+                                Button(
+                                    "Launch",
+                                    variant="success",
+                                    button_type="submit",
+                                )
+                        with Page("json", value="json"), Column(gap=4):
+                            with Column(gap=1, css_class="items-start"):
+                                Heading("Arguments", level=3)
+                                Button(
+                                    "Use form",
+                                    variant="link",
+                                    size="xs",
+                                    on_click=SetState(input_mode, "form"),
+                                    css_class="text-muted-foreground p-0 h-auto",
+                                )
+                            with Form(
+                                on_submit=Fetch.post(
+                                    "/api/launch",
+                                    body=json_body,
+                                    on_success=OpenLink(RESULT),
+                                    on_error=on_error,
+                                ),
+                            ):
+                                Textarea(
+                                    name="__json_args__",
+                                    placeholder='{"key": "value"}',
+                                    rows=8,
+                                )
+                                Button(
+                                    "Launch",
+                                    variant="success",
+                                    button_type="submit",
+                                )
+
+        Markdown(
+            "Generated by [Prefab](https://prefab.prefect.io) 🎨",
+            css_class="text-xs text-muted-foreground text-right",
+        )
+
+    return PrefabApp(title="FastMCP Apps", view=view).html()
+
+
+# ---------------------------------------------------------------------------
+# MCP tool listing helper
+# ---------------------------------------------------------------------------
+
+
+async def _list_tools(mcp_url: str) -> list[dict[str, Any]]:
+    """Return raw tool dicts from the MCP server at mcp_url."""
+    try:
+        from mcp import ClientSession
+        from mcp.client.streamable_http import streamable_http_client
+    except ImportError:
+        return []
+
+    try:
+        async with streamable_http_client(mcp_url) as (read, write):  # noqa: SIM117
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                result = await session.list_tools()
+                return [t.model_dump(by_alias=True) for t in result.tools]
+    except Exception as exc:
+        logger.debug(f"Could not list tools from {mcp_url}: {exc}")
+        return []
+
+
+async def _read_mcp_resource(mcp_url: str, uri: str) -> str | None:
+    """Read an MCP resource by URI and return its text content."""
+    try:
+        from mcp import ClientSession
+        from mcp.client.streamable_http import streamable_http_client
+    except ImportError:
+        return None
+
+    try:
+        async with streamable_http_client(mcp_url) as (read, write):  # noqa: SIM117
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                result = await session.read_resource(uri)
+                for content in result.contents:
+                    text = getattr(content, "text", None)
+                    if text:
+                        return text
+        return None
+    except Exception as exc:
+        logger.debug(f"Could not read resource {uri} from {mcp_url}: {exc}")
+        return None
+
+
+# ---------------------------------------------------------------------------
+# app-bridge.js download, patch, and Zod import-map generation
+# ---------------------------------------------------------------------------
+
+
+def _fetch_app_bridge_bundle_sync(
+    version: str,
+    sdk_version: str,
+) -> tuple[str, str]:
+    """Download app-bridge.js and build an import-map that fixes Zod v4 on esm.sh.
+
+    Returns ``(app_bridge_js, import_map_json)`` where *import_map_json* is a
+    JSON string ready to embed in a ``<script type="importmap">`` tag.
+
+    Background
+    ----------
+    esm.sh's ``zod@x.y.z/es2022/v4.mjs`` only re-exports ``{z, default}``,
+    losing all individual named exports (``custom``, ``string``, etc.).  The
+    MCP SDK does ``import * as t from "zod/v4"`` and calls ``t.custom(…)``
+    which fails.  ``zod@x.y.z/es2022/v4/classic/index.mjs`` exports everything
+    correctly.  An import-map that remaps the broken URL to the working one
+    fixes all modules in the page's graph, including those loaded cross-origin
+    from esm.sh.
+
+    ext-apps app-bridge.js imports the SDK via bare specifiers
+    (``@modelcontextprotocol/sdk/types.js`` etc.) that the browser cannot
+    resolve.  We rewrite them to concrete esm.sh URLs before serving.
+
+    Caching
+    -------
+    ``app_bridge_js`` is cached on disk because it is static for a given
+    ext-apps + SDK version pair (downloaded from npm).
+
+    The import map is NOT cached.  It contains the concrete zod version that
+    esm.sh resolves ``zod@^x`` to at fetch time, and that version can change
+    when esm.sh publishes a new zod release.  A stale cached import map would
+    redirect the old version URL while the browser loads the new version URL,
+    so the redirect would not apply and ``t.custom`` would be undefined.
+    """
+    sdk_base = f"https://esm.sh/@modelcontextprotocol/sdk@{sdk_version}"
+
+    # -- Detect the broken Zod v4.mjs URL (always fresh, never cached) ------
+    # The SDK's types module imports zod/v4 via a version-range URL like
+    # /zod@^4.3.5/v4?target=es2022.  That wrapper re-exports from the
+    # version-specific v4.mjs (e.g. /zod@4.3.6/es2022/v4.mjs) which is
+    # broken.  We fetch the wrapper to discover the exact version.
+    #
+    # We do this before the (potentially cached) app-bridge download so that
+    # any network error is surfaced early and clearly.
+    types_url = f"{sdk_base}/types.js"
+    with httpx.Client(timeout=30.0) as client:
+        resp = client.get(types_url, follow_redirects=True)
+        resp.raise_for_status()
+        types_content = resp.text
+
+    # Extract the zod/v4?target=es2022 path from the types.js redirect
+    zod_wrapper_match = re.search(r'import "(/zod@[^"]*v4[^"]*)"', types_content)
+    if not zod_wrapper_match:
+        raise RuntimeError(
+            f"Could not find zod/v4 import in {types_url}:\n{types_content[:500]}"
+        )
+    zod_wrapper_path = zod_wrapper_match.group(1)  # e.g. /zod@^4.3.5/v4?target=es2022
+
+    zod_wrapper_url = f"https://esm.sh{zod_wrapper_path}"
+    with httpx.Client(timeout=30.0) as client:
+        resp = client.get(zod_wrapper_url, follow_redirects=True)
+        resp.raise_for_status()
+        wrapper_content = resp.text
+
+    # The wrapper does: export * from "/zod@4.3.6/es2022/v4.mjs"
+    broken_match = re.search(
+        r'export \* from "(/zod@[\d.]+/es2022/v4\.mjs)"', wrapper_content
+    )
+    if not broken_match:
+        raise RuntimeError(
+            f"Could not find v4.mjs re-export in {zod_wrapper_url}:\n{wrapper_content[:500]}"
+        )
+    broken_path = broken_match.group(1)  # e.g. /zod@4.3.6/es2022/v4.mjs
+    zod_version = broken_path.split("@")[1].split("/")[0]  # e.g. 4.3.6
+
+    broken_url = f"https://esm.sh{broken_path}"
+    fixed_url = f"https://esm.sh/zod@{zod_version}/es2022/v4/classic/index.mjs"
+
+    import_map_json = json.dumps({"imports": {broken_url: fixed_url}})
+
+    # -- Download and patch app-bridge.js (cached per ext-apps + SDK version) -
+    app_bridge_cache = (
+        Path(tempfile.gettempdir()) / f"fastmcp-ext-apps-{version}-sdk-{sdk_version}.js"
+    )
+    if app_bridge_cache.exists():
+        app_bridge_js = app_bridge_cache.read_text(encoding="utf-8")
+        return app_bridge_js, import_map_json
+
+    npm_url = f"https://registry.npmjs.org/@modelcontextprotocol/ext-apps/-/ext-apps-{version}.tgz"
+    with httpx.Client(timeout=30.0) as client:
+        resp = client.get(npm_url, follow_redirects=True)
+        resp.raise_for_status()
+        data = resp.content
+
+    with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as tar:
+        member = tar.extractfile("package/dist/src/app-bridge.js")
+        if member is None:
+            raise RuntimeError("app-bridge.js not found in ext-apps tarball")
+        app_bridge_js = member.read().decode()
+
+    # Rewrite bare SDK module specifiers to concrete esm.sh URLs
+    for sdk_path in ("types.js", "shared/protocol.js"):
+        app_bridge_js = app_bridge_js.replace(
+            f'from"@modelcontextprotocol/sdk/{sdk_path}"',
+            f'from"{sdk_base}/{sdk_path}"',
+        )
+
+    app_bridge_cache.write_text(app_bridge_js, encoding="utf-8")
+    return app_bridge_js, import_map_json
+
+
+async def _fetch_app_bridge_bundle(
+    version: str,
+    sdk_version: str,
+) -> tuple[str, str]:
+    """Async wrapper around _fetch_app_bridge_bundle_sync."""
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(
+        None, _fetch_app_bridge_bundle_sync, version, sdk_version
+    )
+
+
+# ---------------------------------------------------------------------------
+# FastAPI dev server
+# ---------------------------------------------------------------------------
+
+
+def _make_dev_app(
+    mcp_url: str,
+    app_bridge_js: str,
+    import_map_tag: str,
+    message_log: _MessageLog,
+    log_panel: bool,
+) -> Starlette:
+    """Build the Starlette dev server application."""
+
+    async def picker(request: Request) -> HTMLResponse:
+        """AppBridge host page — loads the picker app in an iframe and wires the bridge."""
+        host_html = _HOST_SHELL.format(
+            title="FastMCP Apps",
+            import_map_tag=import_map_tag,
+            status_text="",
+            status_display="none",
+            frame_display="block",
+            mcp_sdk_version=_MCP_SDK_VERSION,
+            iframe_src_json=json.dumps("/picker-app"),
+            on_open_link="bridge.onopenlink = async ({ url }) => { window.location.href = url; return {}; };",
+            on_initialized="bridge.oninitialized = async () => {};",
+        )
+        return (
+            HTMLResponse(_inject_log_panel(host_html))
+            if log_panel
+            else HTMLResponse(host_html)
+        )
+
+    async def picker_app(request: Request) -> HTMLResponse:
+        """Prefab picker UI — tool list with one tab per UI tool."""
+        try:
+            raw_tools = await _list_tools(mcp_url)
+            ui_tools = [t for t in raw_tools if _has_ui_resource(t)]
+            html = _build_picker_html(ui_tools)
+        except Exception as exc:
+            logger.exception("Error building picker UI")
+            html = f"<pre style='padding:2rem;color:red'>Error: {exc}</pre>"
+        return HTMLResponse(html)
+
+    async def launch(request: Request) -> HTMLResponse:
+        """Host page: GET /launch?tool=name&args={...}"""
+        tool = request.query_params.get("tool", "")
+        args_raw = request.query_params.get("args", "{}")
+        tool_args = json.loads(args_raw)
+        host_html = _HOST_HTML_TEMPLATE.format(
+            tool_name=html.escape(tool, quote=True),
+            import_map_tag=import_map_tag,
+            tool_name_json=_json_for_script(tool),
+            tool_args_json=_json_for_script(tool_args),
+            mcp_sdk_version=_MCP_SDK_VERSION,
+        )
+        return (
+            HTMLResponse(_inject_log_panel(host_html))
+            if log_panel
+            else HTMLResponse(host_html)
+        )
+
+    async def api_launch(request: Request) -> Response:
+        """Picker form submits here; returns a /launch URL string for OpenLink."""
+        data = await request.json()
+        tool = data.pop("tool", "")
+
+        # JSON mode: the entire argument dict arrives as a raw JSON string.
+        # Key uses a dunder prefix to avoid collisions with real tool params.
+        raw_json_args = data.pop("__json_args__", None)
+        if raw_json_args is not None:
+            if not raw_json_args.strip():
+                tool_args = {}
+            else:
+                try:
+                    tool_args = json.loads(raw_json_args)
+                except json.JSONDecodeError as exc:
+                    return Response(
+                        content=json.dumps({"error": f"Invalid JSON: {exc}"}),
+                        status_code=400,
+                        media_type="application/json",
+                    )
+                if not isinstance(tool_args, dict):
+                    return Response(
+                        content=json.dumps(
+                            {
+                                "error": "JSON must be an object, not "
+                                + type(tool_args).__name__
+                            }
+                        ),
+                        status_code=400,
+                        media_type="application/json",
+                    )
+        else:
+            # Form mode: inputs are always strings — try to parse values
+            # that look like JSON objects or arrays.
+            tool_args = {}
+            for k, v in data.items():
+                if isinstance(v, str):
+                    stripped = v.strip()
+                    # Skip empty strings — the form sends them for
+                    # unfilled optional fields, but they'll fail
+                    # validation against non-string types.
+                    if not stripped:
+                        continue
+                    if stripped[0] in ("{", "["):
+                        try:
+                            parsed = json.loads(stripped)
+                            if isinstance(parsed, (dict, list)):
+                                v = parsed
+                        except (json.JSONDecodeError, TypeError):
+                            pass
+                tool_args[k] = v
+        url = "/launch?" + urlencode({"tool": tool, "args": json.dumps(tool_args)})
+        return Response(
+            content=json.dumps(url),
+            media_type="application/json",
+        )
+
+    async def ui_resource(request: Request) -> Response:
+        """Fetch an MCP resource server-side and return it as HTML.
+
+        Used by the launch page to load the renderer via iframe.src rather
+        than iframe.srcdoc — avoids a race condition where the Prefab renderer
+        sends its MCP initialize message before the AppBridge transport is
+        listening (srcdoc parses and runs module scripts synchronously, while
+        iframe.src load adds the network-roundtrip gap needed).
+        """
+        uri = request.query_params.get("uri", "")
+        if not uri:
+            return Response("Missing uri parameter", status_code=400)
+        html = await _read_mcp_resource(mcp_url, uri)
+        if html is None:
+            return Response(f"Could not read MCP resource: {uri}", status_code=502)
+        return HTMLResponse(html)
+
+    async def serve_app_bridge_js(request: Request) -> Response:
+        """Serve the locally patched app-bridge.js."""
+        return Response(
+            content=app_bridge_js,
+            media_type="application/javascript",
+        )
+
+    async def proxy_mcp(request: Request) -> Response:
+        """Proxy all MCP requests to the user's server (avoids browser CORS)."""
+        body = await request.body()
+
+        # Log MCP requests
+        if body and request.method == "POST":
+            try:
+                req_json = json.loads(body)
+                if isinstance(req_json, list):
+                    for item in req_json:
+                        if isinstance(item, dict):
+                            message_log.log_request(item)
+                elif isinstance(req_json, dict):
+                    message_log.log_request(req_json)
+            except (json.JSONDecodeError, TypeError):
+                pass
+
+        headers = {
+            k: v
+            for k, v in request.headers.items()
+            if k.lower() not in ("host", "content-length")
+        }
+
+        # Use a reasonable default timeout to prevent the proxy from hanging
+        # if the backend server is unresponsive.
+        client = httpx.AsyncClient(
+            timeout=httpx.Timeout(60.0, read=None), trust_env=False
+        )
+
+        async def _stream_and_cleanup(resp: httpx.Response) -> Any:
+            is_sse = "text/event-stream" in resp.headers.get("content-type", "")
+            buf: list[bytes] = []
+            sse_buf = ""
+            try:
+                async for chunk in resp.aiter_bytes():
+                    yield chunk
+                    if is_sse:
+                        # Parse SSE events incrementally
+                        sse_buf += chunk.decode("utf-8", errors="replace")
+                        while "\r\n\r\n" in sse_buf or "\n\n" in sse_buf:
+                            # Split on whichever double-newline appears first
+                            ri = sse_buf.find("\r\n\r\n")
+                            ni = sse_buf.find("\n\n")
+                            if ri >= 0 and (ni < 0 or ri < ni):
+                                event, sse_buf = sse_buf[:ri], sse_buf[ri + 4 :]
+                            else:
+                                event, sse_buf = sse_buf[:ni], sse_buf[ni + 2 :]
+                            for line in event.splitlines():
+                                if line.startswith("data: "):
+                                    with contextlib.suppress(json.JSONDecodeError):
+                                        message_log.log_response(json.loads(line[6:]))
+                    else:
+                        buf.append(chunk)
+            except (
+                httpx.RemoteProtocolError,
+                httpx.ReadError,
+                httpx.ReadTimeout,
+                httpcore.RemoteProtocolError,
+            ):
+                pass  # Connection closed during shutdown — not an error
+            finally:
+                # Log non-SSE responses (JSON) after stream completes
+                if buf:
+                    _log_response_bytes(message_log, b"".join(buf), "application/json")
+                with contextlib.suppress(Exception):
+                    await resp.aclose()
+                with contextlib.suppress(Exception):
+                    await client.aclose()
+
+        try:
+            req = client.build_request(
+                method=request.method,
+                url=mcp_url,
+                content=body,
+                headers=headers,
+                params=dict(request.query_params),
+            )
+            resp = await client.send(req, stream=True)
+            content_type = resp.headers.get("content-type", "")
+            # Strip hop-by-hop headers that shouldn't be forwarded
+            fwd_headers = {
+                k: v
+                for k, v in resp.headers.items()
+                if k.lower()
+                not in (
+                    "transfer-encoding",
+                    "connection",
+                    "keep-alive",
+                    "content-encoding",
+                )
+            }
+            return StreamingResponse(
+                _stream_and_cleanup(resp),
+                status_code=resp.status_code,
+                headers=fwd_headers,
+                media_type=content_type or "application/octet-stream",
+            )
+        except (httpx.ConnectError, httpx.ConnectTimeout):
+            await client.aclose()
+            return Response(
+                content=json.dumps({"error": "MCP server not reachable"}).encode(),
+                status_code=503,
+                media_type="application/json",
+            )
+
+    async def api_logs(request: Request) -> Response:
+        """Return message log entries since a given id."""
+        since = int(request.query_params.get("since", "0"))
+        entries = message_log.get_since(since)
+        return Response(
+            content=json.dumps(entries),
+            media_type="application/json",
+        )
+
+    async def api_logs_bridge(request: Request) -> Response:
+        """Log a bridge message (postMessage between app iframe and host)."""
+        data = await request.json()
+        message_log.log_bridge(data.get("body", data))
+        return Response(content="{}", media_type="application/json")
+
+    async def api_logs_clear(request: Request) -> Response:
+        """Clear the message log."""
+        message_log.clear()
+        return Response(content="{}", media_type="application/json")
+
+    return Starlette(
+        routes=[
+            Route("/", picker),
+            Route("/picker-app", picker_app),
+            Route("/launch", launch),
+            Route("/api/launch", api_launch, methods=["POST"]),
+            Route("/api/logs", api_logs),
+            Route("/api/logs/bridge", api_logs_bridge, methods=["POST"]),
+            Route("/api/logs/clear", api_logs_clear, methods=["POST"]),
+            Route("/ui-resource", ui_resource),
+            Route("/js/app-bridge.js", serve_app_bridge_js),
+            Route(
+                "/mcp",
+                proxy_mcp,
+                methods=["GET", "POST", "DELETE", "PUT", "PATCH", "OPTIONS"],
+            ),
+        ]
+    )
+
+
+# ---------------------------------------------------------------------------
+# Launch helpers
+# ---------------------------------------------------------------------------
+
+
+async def _start_user_server(
+    server_spec: str,
+    mcp_port: int,
+    *,
+    reload: bool = True,
+    host: str = "127.0.0.1",
+) -> asyncio.subprocess.Process:
+    """Start the user's MCP server as a subprocess on mcp_port."""
+    cmd = [
+        sys.executable,
+        "-m",
+        "fastmcp.cli",
+        "run",
+        server_spec,
+        "--transport",
+        "http",
+        "--host",
+        host,
+        "--port",
+        str(mcp_port),
+        "--no-banner",
+    ]
+    if reload:
+        cmd.append("--reload")
+    else:
+        cmd.append("--no-reload")
+    env = {**os.environ, "FASTMCP_LOG_LEVEL": "WARNING"}
+    process = await asyncio.create_subprocess_exec(
+        *cmd,
+        env=env,
+        start_new_session=sys.platform != "win32",
+    )
+    return process
+
+
+async def _wait_for_server(url: str, timeout: float = 15.0) -> bool:
+    """Poll until the server is accepting connections."""
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + timeout
+    async with httpx.AsyncClient(trust_env=False) as client:
+        while loop.time() < deadline:
+            try:
+                await client.get(url, timeout=1.0)
+                return True
+            except (
+                httpx.ConnectError,
+                httpx.RemoteProtocolError,
+                httpx.TimeoutException,
+            ):
+                await asyncio.sleep(0.25)
+    return False
+
+
+async def run_dev_apps(
+    server_spec: str,
+    *,
+    mcp_port: int = 8000,
+    dev_port: int = 8080,
+    reload: bool = True,
+    host: str = "127.0.0.1",
+    log_panel: bool = True,
+) -> None:
+    """Start the full dev environment for a FastMCPApp server.
+
+    Starts the user's MCP server on *mcp_port*, starts the Prefab dev UI
+    on *dev_port* (with an /mcp proxy to the user's server), then opens
+    the browser.
+    """
+    mcp_url = (
+        f"http://{host}:{mcp_port}/mcp"
+        if ":" not in host
+        else f"http://[{host}]:{mcp_port}/mcp"
+    )
+    dev_url = (
+        f"http://{host}:{dev_port}"
+        if ":" not in host
+        else f"http://[{host}]:{dev_port}"
+    )
+
+    user_proc: asyncio.subprocess.Process | None = None
+
+    async def _body() -> None:
+        nonlocal user_proc
+
+        # Check ports before starting anything
+        import socket
+
+        for port, label, flag in [
+            (mcp_port, "MCP server", "--mcp-port"),
+            (dev_port, "dev UI", "--dev-port"),
+        ]:
+            in_use = False
+            _targets = (
+                (
+                    (socket.AF_INET, ("127.0.0.1", port)),
+                    (socket.AF_INET6, ("::1", port, 0, 0)),
+                )
+                if host == "127.0.0.1"
+                else (
+                    ((socket.AF_INET6, (host, port, 0, 0)),)
+                    if ":" in host
+                    else ((socket.AF_INET, (host, port)),)
+                )
+            )
+
+            for family, addr in _targets:
+                try:
+                    with socket.socket(family, socket.SOCK_STREAM) as s:
+                        if s.connect_ex(addr) == 0:
+                            in_use = True
+                            break
+                except OSError:
+                    continue
+            if in_use:
+                logger.error(
+                    f"Port {port} ({label}) is already in use. "
+                    f"Try {flag} to use a different port."
+                )
+                sys.exit(1)
+
+        logger.info(f"Starting user server on port {mcp_port}…")
+        logger.info("Fetching app-bridge.js from npm…")
+
+        # Start the server first so user_proc is assigned before anything
+        # that might fail (e.g. npm fetch).  This ensures the finally
+        # cleanup can kill the subprocess even if the bundle fetch raises.
+        user_proc = await _start_user_server(
+            server_spec, mcp_port, reload=reload, host=host
+        )
+        app_bridge_js, import_map_json = await _fetch_app_bridge_bundle(
+            _EXT_APPS_VERSION, _MCP_SDK_VERSION
+        )
+
+        import_map_tag = (
+            f'  <script type="importmap">\n  {import_map_json}\n  </script>'
+        )
+
+        ready = await _wait_for_server(mcp_url, timeout=15.0)
+        if not ready:
+            raise RuntimeError(f"User server did not start on port {mcp_port}")
+
+        logger.info(f"FastMCP dev UI at {dev_url}")
+
+        dev_app = _make_dev_app(
+            mcp_url, app_bridge_js, import_map_tag, _MessageLog(), log_panel
+        )
+        config = uvicorn.Config(
+            dev_app,
+            host=host,
+            port=dev_port,
+            log_level="warning",
+            ws="websockets-sansio",
+        )
+        server = uvicorn.Server(config)
+        # Suppress uvicorn's own signal handlers — they use signal.signal() which
+        # conflicts with asyncio and causes hangs.  We cancel the task instead.
+        server.install_signal_handlers = lambda: None  # type: ignore[method-assign]  # ty:ignore[unresolved-attribute]
+
+        async def _open_browser() -> None:
+            await asyncio.sleep(0.8)
+            webbrowser.open(dev_url)
+
+        await asyncio.gather(server.serve(), _open_browser())
+
+    # Register signal handlers before any work starts so that Ctrl+C during
+    # startup (server spawn, npm fetch, server-ready poll) is handled the same
+    # way as Ctrl+C during the running phase — both cancel the body task and
+    # fall through to the cleanup finally block.
+    loop = asyncio.get_running_loop()
+    task = asyncio.ensure_future(_body())
+
+    def _on_signal() -> None:
+        # Silence uvicorn's error logger before cancelling so that the
+        # CancelledError propagating through uvicorn doesn't get logged as
+        # an ERROR during the forced shutdown.
+        logging.getLogger("uvicorn.error").setLevel(logging.CRITICAL)
+        task.cancel()
+
+    if sys.platform != "win32":
+        loop.add_signal_handler(signal.SIGINT, _on_signal)
+        loop.add_signal_handler(signal.SIGTERM, _on_signal)
+
+    try:
+        await task
+    except asyncio.CancelledError:
+        pass
+    finally:
+        if sys.platform != "win32":
+            loop.remove_signal_handler(signal.SIGINT)
+            loop.remove_signal_handler(signal.SIGTERM)
+        if user_proc is not None and user_proc.returncode is None:
+            # Kill the entire process group (not just the top-level process)
+            # because --reload creates a watcher that spawns child processes.
+            # Killing only the watcher leaves the actual server holding the port.
+            try:
+                if sys.platform != "win32":
+                    os.killpg(os.getpgid(user_proc.pid), signal.SIGTERM)
+                else:
+                    user_proc.kill()
+            except (ProcessLookupError, PermissionError):
+                user_proc.kill()
+            await user_proc.wait()
diff --git a/fastmcp_slim/fastmcp/cli/auth.py b/fastmcp_slim/fastmcp/cli/auth.py
new file mode 100644
index 0000000..4ea401b
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/auth.py
@@ -0,0 +1,13 @@
+"""Authentication-related CLI commands."""
+
+import cyclopts
+
+from fastmcp.cli.cimd import cimd_app
+
+auth_app = cyclopts.App(
+    name="auth",
+    help="Authentication-related utilities and configuration.",
+)
+
+# Nest CIMD commands under auth
+auth_app.command(cimd_app)
diff --git a/fastmcp_slim/fastmcp/cli/cimd.py b/fastmcp_slim/fastmcp/cli/cimd.py
new file mode 100644
index 0000000..d2def49
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/cimd.py
@@ -0,0 +1,218 @@
+"""CIMD (Client ID Metadata Document) CLI commands."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import cyclopts
+from rich.console import Console
+
+from fastmcp.server.auth.cimd import (
+    CIMDFetcher,
+    CIMDFetchError,
+    CIMDValidationError,
+)
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger("cli.cimd")
+console = Console()
+
+
+cimd_app = cyclopts.App(
+    name="cimd",
+    help="CIMD (Client ID Metadata Document) utilities for OAuth authentication.",
+)
+
+
+@cimd_app.command(name="create")
+def create_command(
+    *,
+    name: Annotated[
+        str,
+        cyclopts.Parameter(help="Human-readable name of the client application"),
+    ],
+    redirect_uri: Annotated[
+        list[str],
+        cyclopts.Parameter(
+            name=["--redirect-uri", "-r"],
+            help="Allowed redirect URIs (can specify multiple)",
+        ),
+    ],
+    client_id: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name="--client-id",
+            help="The URL where this document will be hosted (sets client_id directly)",
+        ),
+    ] = None,
+    client_uri: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name="--client-uri",
+            help="URL of the client's home page",
+        ),
+    ] = None,
+    logo_uri: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name="--logo-uri",
+            help="URL of the client's logo image",
+        ),
+    ] = None,
+    scope: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name="--scope",
+            help="Space-separated list of scopes the client may request",
+        ),
+    ] = None,
+    output: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--output", "-o"],
+            help="Output file path (default: stdout)",
+        ),
+    ] = None,
+    pretty: Annotated[
+        bool,
+        cyclopts.Parameter(
+            help="Pretty-print JSON output",
+        ),
+    ] = True,
+) -> None:
+    """Generate a CIMD document for hosting.
+
+    Create a Client ID Metadata Document that you can host at an HTTPS URL.
+    The URL where you host this document becomes your client_id.
+
+    Example:
+        fastmcp cimd create --name "My App" -r "http://localhost:*/callback"
+
+    After creating the document, host it at an HTTPS URL with a non-root path,
+    for example: https://myapp.example.com/oauth/client.json
+    """
+    # Build the document
+    doc = {
+        "client_id": client_id or "https://YOUR-DOMAIN.com/path/to/client.json",
+        "client_name": name,
+        "redirect_uris": redirect_uri,
+        "token_endpoint_auth_method": "none",
+        "grant_types": ["authorization_code"],
+        "response_types": ["code"],
+    }
+
+    # Add optional fields
+    if client_uri:
+        doc["client_uri"] = client_uri
+    if logo_uri:
+        doc["logo_uri"] = logo_uri
+    if scope:
+        doc["scope"] = scope
+
+    # Format output
+    json_output = json.dumps(doc, indent=2) if pretty else json.dumps(doc)
+
+    # Write output
+    if output:
+        output_path = Path(output).expanduser().resolve()
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(output_path, "w") as f:
+            f.write(json_output)
+            f.write("\n")
+        console.print(f"[green]✓[/green] CIMD document written to {output}")
+        if not client_id:
+            console.print(
+                "\n[yellow]Important:[/yellow] client_id is a placeholder. Update it to the URL where you will host this document, or re-run with --client-id."
+            )
+    else:
+        print(json_output)
+        if not client_id:
+            # Print instructions to stderr so they don't interfere with piping
+            stderr_console = Console(stderr=True)
+            stderr_console.print(
+                "\n[yellow]Important:[/yellow] client_id is a placeholder."
+                " Update it to the URL where you will host this document,"
+                " or re-run with --client-id."
+            )
+
+
+@cimd_app.command(name="validate")
+def validate_command(
+    url: Annotated[
+        str,
+        cyclopts.Parameter(help="URL of the CIMD document to validate"),
+    ],
+    *,
+    timeout: Annotated[
+        float,
+        cyclopts.Parameter(
+            name=["--timeout", "-t"],
+            help="HTTP request timeout in seconds",
+        ),
+    ] = 10.0,
+) -> None:
+    """Validate a hosted CIMD document.
+
+    Fetches the document from the given URL and validates:
+    - URL is valid CIMD URL (HTTPS, non-root path)
+    - Document is valid JSON
+    - Document conforms to CIMD schema
+    - client_id in document matches the URL
+
+    Example:
+        fastmcp cimd validate https://myapp.example.com/oauth/client.json
+    """
+
+    async def _validate() -> bool:
+        fetcher = CIMDFetcher(timeout=timeout)
+
+        # Check URL format first
+        if not fetcher.is_cimd_client_id(url):
+            console.print(f"[red]✗[/red] Invalid CIMD URL: {url}")
+            console.print()
+            console.print("CIMD URLs must:")
+            console.print("  • Use HTTPS (not HTTP)")
+            console.print("  • Have a non-root path (e.g., /client.json, not just /)")
+            return False
+
+        console.print(f"[blue]→[/blue] Fetching {url}...")
+
+        try:
+            doc = await fetcher.fetch(url)
+        except CIMDFetchError as e:
+            console.print(f"[red]✗[/red] Failed to fetch document: {e}")
+            return False
+        except CIMDValidationError as e:
+            console.print(f"[red]✗[/red] Validation error: {e}")
+            return False
+
+        # Success - show document details
+        console.print("[green]✓[/green] Valid CIMD document")
+        console.print()
+        console.print("[bold]Document details:[/bold]")
+        console.print(f"  client_id: {doc.client_id}")
+        console.print(f"  client_name: {doc.client_name or '(not set)'}")
+        console.print(f"  token_endpoint_auth_method: {doc.token_endpoint_auth_method}")
+
+        if doc.redirect_uris:
+            console.print("  redirect_uris:")
+            for uri in doc.redirect_uris:
+                console.print(f"    • {uri}")
+        else:
+            console.print("  redirect_uris: (none)")
+
+        if doc.scope:
+            console.print(f"  scope: {doc.scope}")
+
+        if doc.client_uri:
+            console.print(f"  client_uri: {doc.client_uri}")
+
+        return True
+
+    success = asyncio.run(_validate())
+    if not success:
+        sys.exit(1)
diff --git a/fastmcp_slim/fastmcp/cli/cli.py b/fastmcp_slim/fastmcp/cli/cli.py
new file mode 100644
index 0000000..6c85c80
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/cli.py
@@ -0,0 +1,1143 @@
+"""FastMCP CLI tools using Cyclopts."""
+
+import importlib.metadata
+import importlib.util
+import json
+import os
+import platform
+import subprocess
+import sys
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Annotated, Literal
+
+import cyclopts
+import pyperclip
+from cyclopts import Parameter
+from rich.console import Console
+from rich.table import Table
+
+import fastmcp
+from fastmcp.cli import run as run_module
+from fastmcp.cli.auth import auth_app
+from fastmcp.cli.client import call_command, discover_command, list_command
+from fastmcp.cli.generate import generate_cli_command
+from fastmcp.cli.install import install_app
+from fastmcp.cli.tasks import tasks_app
+from fastmcp.utilities.cli import is_already_in_uv_subprocess, load_and_merge_config
+from fastmcp.utilities.inspect import (
+    InspectFormat,
+    format_info,
+    inspect_fastmcp,
+)
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_server_config import MCPServerConfig
+from fastmcp.utilities.version_check import check_for_newer_version
+
+logger = get_logger("cli")
+console = Console()
+
+app = cyclopts.App(
+    name="fastmcp",
+    help="FastMCP - The fast, Pythonic way to build MCP servers and clients.",
+    version=fastmcp.__version__,
+    # Disable automatic negative parameters by default
+    default_parameter=Parameter(negative=()),
+)
+
+
+def _get_npx_command():
+    """Get the correct npx command for the current platform."""
+    if sys.platform == "win32":
+        # Try both npx.cmd and npx.exe on Windows
+        for cmd in ["npx.cmd", "npx.exe", "npx"]:
+            try:
+                subprocess.run([cmd, "--version"], check=True, capture_output=True)
+                return cmd
+            except (subprocess.CalledProcessError, FileNotFoundError):
+                continue
+        return None
+    return "npx"  # On Unix-like systems, just use npx
+
+
+def _parse_env_var(env_var: str) -> tuple[str, str]:
+    """Parse environment variable string in format KEY=VALUE."""
+    if "=" not in env_var:
+        logger.error("Invalid environment variable format. Must be KEY=VALUE")
+        sys.exit(1)
+    key, value = env_var.split("=", 1)
+    if not key.strip():
+        logger.error("Invalid environment variable format. KEY cannot be empty")
+        sys.exit(1)
+    return key.strip(), value.strip()
+
+
+@contextmanager
+def with_argv(args: list[str] | None):
+    """Temporarily replace sys.argv if args provided.
+
+    This context manager is used at the CLI boundary to inject
+    server arguments when needed, without mutating sys.argv deep
+    in the source loading logic.
+
+    Args are provided without the script name, so we preserve sys.argv[0]
+    and replace the rest.
+    """
+    if args is not None:
+        original = sys.argv[:]
+        try:
+            # Preserve the script name (sys.argv[0]) and replace the rest
+            sys.argv = [sys.argv[0], *args]
+            yield
+        finally:
+            sys.argv = original
+    else:
+        yield
+
+
+@app.command
+def version(
+    *,
+    copy: Annotated[
+        bool,
+        cyclopts.Parameter("--copy", help="Copy version information to clipboard"),
+    ] = False,
+):
+    """Display version information and platform details."""
+    info = {
+        "FastMCP version": fastmcp.__version__,
+        "MCP version": importlib.metadata.version("mcp"),
+        "Python version": platform.python_version(),
+        "Platform": platform.platform(),
+        "FastMCP root path": Path(fastmcp.__file__ or ".").resolve().parents[1],
+    }
+
+    g = Table.grid(padding=(0, 1))
+    g.add_column(style="bold", justify="left")
+    g.add_column(style="cyan", justify="right")
+    for k, v in info.items():
+        g.add_row(k + ":", str(v).replace("\n", " "))
+
+    if copy:
+        # Use Rich's plain text rendering for copying
+        plain_console = Console(file=None, force_terminal=False, legacy_windows=False)
+        with plain_console.capture() as capture:
+            plain_console.print(g)
+        pyperclip.copy(capture.get())
+        console.print("[green]✓[/green] Version information copied to clipboard")
+    else:
+        console.print(g)
+
+        # Check for updates (not included in --copy output)
+        if newer_version := check_for_newer_version():
+            console.print()
+            console.print(
+                f"[bold]🎉 FastMCP update available:[/bold] [green]{newer_version}[/green]"
+            )
+            console.print("[dim]Run: pip install --upgrade fastmcp[/dim]")
+
+
+# Create dev subcommand group
+dev_app = cyclopts.App(name="dev", help="Development tools for MCP servers")
+
+
+@dev_app.command
+async def inspector(
+    server_spec: str | None = None,
+    *,
+    with_editable: Annotated[
+        list[Path] | None,
+        cyclopts.Parameter(
+            "--with-editable",
+            help="Directory containing pyproject.toml to install in editable mode (can be used multiple times)",
+        ),
+    ] = None,
+    with_packages: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            "--with", help="Additional packages to install (can be used multiple times)"
+        ),
+    ] = None,
+    inspector_version: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--inspector-version",
+            help="Version of the MCP Inspector to use",
+        ),
+    ] = None,
+    ui_port: Annotated[
+        int | None,
+        cyclopts.Parameter(
+            "--ui-port",
+            help="Port for the MCP Inspector UI",
+        ),
+    ] = None,
+    server_port: Annotated[
+        int | None,
+        cyclopts.Parameter(
+            "--server-port",
+            help="Port for the MCP Inspector Proxy server",
+        ),
+    ] = None,
+    python: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--python",
+            help="Python version to use (e.g., 3.10, 3.11)",
+        ),
+    ] = None,
+    with_requirements: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--with-requirements",
+            help="Requirements file to install dependencies from",
+        ),
+    ] = None,
+    project: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--project",
+            help="Run the command within the given project directory",
+        ),
+    ] = None,
+    reload: Annotated[
+        bool,
+        cyclopts.Parameter(
+            "--reload",
+            help="Enable auto-reload on file changes (enabled by default)",
+            negative="--no-reload",
+        ),
+    ] = True,
+    reload_dir: Annotated[
+        list[Path] | None,
+        cyclopts.Parameter(
+            "--reload-dir",
+            help="Directories to watch for changes (default: current directory)",
+        ),
+    ] = None,
+    module: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["--module", "-m"],
+            help="Run a Python module (python -m <module>) instead of importing a server object",
+        ),
+    ] = False,
+) -> None:
+    """Run an MCP server with the MCP Inspector for development.
+
+    Args:
+        server_spec: Python file to run, optionally with :object suffix, or None to auto-detect fastmcp.json
+    """
+
+    try:
+        # Load config and apply CLI overrides
+        config, server_spec = load_and_merge_config(
+            server_spec,
+            python=python,
+            with_packages=with_packages or [],
+            with_requirements=with_requirements,
+            project=project,
+            editable=[str(p) for p in with_editable] if with_editable else None,
+            port=server_port,  # Use deployment config for server port
+        )
+
+        # Get server port from config if not specified via CLI
+        if not server_port:
+            server_port = config.deployment.port
+
+    except FileNotFoundError:
+        sys.exit(1)
+
+    logger.debug(
+        "Starting dev server",
+        extra={
+            "server_spec": server_spec,
+            "with_editable": config.environment.editable,
+            "with_packages": config.environment.dependencies,
+            "ui_port": ui_port,
+            "server_port": server_port,
+        },
+    )
+
+    try:
+        if not config:
+            logger.error("No configuration available")
+            sys.exit(1)
+        assert config is not None  # For type checker
+
+        # Skip server-object validation in module mode — the module
+        # manages its own startup and may not expose an importable server.
+        if not module:
+            await config.source.load_server()
+
+        env_vars = {}
+        if ui_port:
+            env_vars["CLIENT_PORT"] = str(ui_port)
+        if server_port:
+            env_vars["SERVER_PORT"] = str(server_port)
+
+        # Get the correct npx command
+        npx_cmd = _get_npx_command()
+        if not npx_cmd:
+            logger.error(
+                "npx not found. Please ensure Node.js and npm are properly installed "
+                "and added to your system PATH."
+            )
+            sys.exit(1)
+
+        inspector_cmd = "@modelcontextprotocol/inspector"
+        if inspector_version:
+            inspector_cmd += f"@{inspector_version}"
+
+        # Build the fastmcp run command
+        fastmcp_cmd = ["fastmcp", "run", server_spec, "--no-banner"]
+
+        # Forward module mode flag
+        if module:
+            fastmcp_cmd.append("--module")
+
+        # Add reload flags if enabled - the server will handle reloading
+        if reload:
+            fastmcp_cmd.append("--reload")
+            if reload_dir:
+                for dir_path in reload_dir:
+                    fastmcp_cmd.extend(["--reload-dir", str(dir_path)])
+
+        # Use the environment from config (already has CLI overrides applied)
+        uv_cmd = config.environment.build_command(fastmcp_cmd)
+
+        # Set marker to prevent infinite loops when subprocess calls FastMCP
+        env = dict(os.environ.items()) | env_vars | {"FASTMCP_UV_SPAWNED": "1"}
+
+        # Run the MCP Inspector command
+        process = subprocess.run(
+            [npx_cmd, inspector_cmd, *uv_cmd],
+            check=True,
+            env=env,
+        )
+        sys.exit(process.returncode)
+    except subprocess.CalledProcessError as e:
+        logger.error(
+            "Dev server failed",
+            extra={
+                "file": str(server_spec),
+                "error": str(e),
+                "returncode": e.returncode,
+            },
+        )
+        sys.exit(e.returncode)
+    except FileNotFoundError:
+        logger.error(
+            "npx not found. Please ensure Node.js and npm are properly installed "
+            "and added to your system PATH. You may need to restart your terminal "
+            "after installation.",
+            extra={"file": str(server_spec)},
+        )
+        sys.exit(1)
+
+
+@dev_app.command
+async def apps(
+    server_spec: str,
+    *,
+    mcp_port: Annotated[
+        int,
+        cyclopts.Parameter(
+            "--mcp-port",
+            help="Port for the user's MCP server",
+        ),
+    ] = 8000,
+    dev_port: Annotated[
+        int,
+        cyclopts.Parameter(
+            "--dev-port",
+            help="Port for the FastMCP dev UI",
+        ),
+    ] = 8080,
+    reload: Annotated[
+        bool,
+        cyclopts.Parameter(
+            "--reload",
+            negative="--no-reload",
+            help="Auto-reload the MCP server on file changes",
+        ),
+    ] = True,
+    host: Annotated[
+        str,
+        cyclopts.Parameter(
+            "--host",
+            help="Host to bind to",
+        ),
+    ] = "127.0.0.1",
+    log_panel: Annotated[
+        bool,
+        cyclopts.Parameter(
+            "--log-panel",
+            negative="--no-log-panel",
+            help="Log panel feature in FastMCP dev UI",
+        ),
+    ] = True,
+) -> None:
+    """Preview a FastMCPApp UI in the browser.
+
+    Starts the MCP server from SERVER_SPEC on --mcp-port, launches a local
+    dev UI on --dev-port with a tool picker and AppBridge host, then opens
+    the browser automatically.
+
+    Requires fastmcp[apps] to be installed (prefab-ui).
+    """
+    try:
+        import prefab_ui  # noqa: F401
+    except ImportError:
+        logger.error(
+            "fastmcp dev apps requires prefab-ui. Install with: pip install 'fastmcp[apps]'"
+        )
+        sys.exit(1)
+
+    from fastmcp.cli.apps_dev import run_dev_apps
+
+    await run_dev_apps(
+        server_spec,
+        mcp_port=mcp_port,
+        dev_port=dev_port,
+        reload=reload,
+        host=host,
+        log_panel=log_panel,
+    )
+
+
+@app.command
+async def run(
+    server_spec: str | None = None,
+    *server_args: str,
+    transport: Annotated[
+        run_module.TransportType | None,
+        cyclopts.Parameter(
+            name=["--transport", "-t"],
+            help="Transport protocol to use",
+        ),
+    ] = None,
+    host: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--host",
+            help="Host to bind to when using http transport (default: 127.0.0.1)",
+        ),
+    ] = None,
+    port: Annotated[
+        int | None,
+        cyclopts.Parameter(
+            name=["--port", "-p"],
+            help="Port to bind to when using http transport (default: 8000)",
+        ),
+    ] = None,
+    path: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--path",
+            help="The route path for the server (default: /mcp/ for http transport, /sse/ for sse transport)",
+        ),
+    ] = None,
+    log_level: Annotated[
+        Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | None,
+        cyclopts.Parameter(
+            name=["--log-level", "-l"],
+            help="Log level",
+        ),
+    ] = None,
+    no_banner: Annotated[
+        bool,
+        cyclopts.Parameter("--no-banner", help="Don't show the server banner"),
+    ] = False,
+    python: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--python",
+            help="Python version to use (e.g., 3.10, 3.11)",
+        ),
+    ] = None,
+    with_packages: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            "--with", help="Additional packages to install (can be used multiple times)"
+        ),
+    ] = None,
+    project: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--project",
+            help="Run the command within the given project directory",
+        ),
+    ] = None,
+    with_requirements: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--with-requirements",
+            help="Requirements file to install dependencies from",
+        ),
+    ] = None,
+    skip_source: Annotated[
+        bool,
+        cyclopts.Parameter(
+            "--skip-source",
+            help="Skip source preparation step (use when source is already prepared)",
+        ),
+    ] = False,
+    skip_env: Annotated[
+        bool,
+        cyclopts.Parameter(
+            "--skip-env",
+            help="Skip environment configuration (for internal use when already in a uv environment)",
+        ),
+    ] = False,
+    reload: Annotated[
+        bool,
+        cyclopts.Parameter(
+            "--reload",
+            negative="--no-reload",
+            help="Enable auto-reload on file changes (development mode)",
+        ),
+    ] = False,
+    reload_dir: Annotated[
+        list[Path] | None,
+        cyclopts.Parameter(
+            "--reload-dir",
+            help="Directories to watch for changes (default: current directory)",
+        ),
+    ] = None,
+    stateless: Annotated[
+        bool,
+        cyclopts.Parameter(
+            "--stateless",
+            help="Run in stateless mode (no session, used internally for reload)",
+        ),
+    ] = False,
+    module: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["--module", "-m"],
+            help="Run a Python module (python -m <module>) instead of importing a server object",
+        ),
+    ] = False,
+) -> None:
+    """Run an MCP server or connect to a remote one.
+
+    The server can be specified in several ways:
+    1. Module approach: "server.py" - runs the module directly, looking for an object named 'mcp', 'server', or 'app'
+    2. Import approach: "server.py:app" - imports and runs the specified server object
+    3. URL approach: "http://server-url" - connects to a remote server and creates a proxy
+    4. MCPConfig file: "mcp.json" - runs as a proxy server for the MCP Servers in the MCPConfig file
+    5. FastMCP config: "fastmcp.json" - runs server using FastMCP configuration
+    6. No argument: looks for fastmcp.json in current directory
+    7. Module mode: "-m my_module" - runs the module directly via python -m
+
+    Server arguments can be passed after -- :
+    fastmcp run server.py -- --config config.json --debug
+
+    Args:
+        server_spec: Python file, object specification (file:obj), config file, URL, or None to auto-detect
+    """
+
+    # --- Module mode: delegate to python -m and exit early ---
+    if module:
+        if server_spec is None:
+            logger.error("A module name is required when using --module / -m")
+            sys.exit(1)
+
+        # Warn about options that are ignored in module mode
+        ignored_options: list[str] = []
+        if transport is not None:
+            ignored_options.append("--transport")
+        if host is not None:
+            ignored_options.append("--host")
+        if port is not None:
+            ignored_options.append("--port")
+        if path is not None:
+            ignored_options.append("--path")
+        if ignored_options:
+            logger.warning(
+                f"Options {', '.join(ignored_options)} are ignored in module mode "
+                f"(-m). The module manages its own server startup."
+            )
+
+        # Build environment wrapper if needed
+        env_builder = None
+        if not skip_env and not is_already_in_uv_subprocess():
+            from fastmcp.utilities.mcp_server_config.v1.environments.uv import (
+                UVEnvironment,
+            )
+
+            env = UVEnvironment(
+                python=python,
+                dependencies=with_packages or None,
+                requirements=with_requirements,
+                project=project,
+            )
+            test_cmd = ["test"]
+            if env.build_command(test_cmd) != test_cmd:
+                env_builder = env.build_command
+
+        if reload:
+            # Build a fastmcp run command for the reload watcher to restart
+            reload_cmd = ["fastmcp", "run", server_spec, "--module", "--no-reload"]
+            if log_level:
+                reload_cmd.extend(["--log-level", log_level])
+            if no_banner:
+                reload_cmd.append("--no-banner")
+            if env_builder is not None:
+                reload_cmd.append("--skip-env")
+            if server_args:
+                reload_cmd.append("--")
+                reload_cmd.extend(server_args)
+            if env_builder is not None:
+                reload_cmd = env_builder(reload_cmd)
+            await run_module.run_with_reload(
+                reload_cmd, reload_dirs=reload_dir, is_stdio=True
+            )
+            return
+
+        run_module.run_module_command(
+            server_spec,
+            env_command_builder=env_builder,
+            extra_args=list(server_args) if server_args else None,
+        )
+        return
+
+    # Check if we were spawned by uv (or user explicitly set --skip-env)
+    if skip_env or is_already_in_uv_subprocess():
+        skip_env = True
+
+    try:
+        # Load config and apply CLI overrides
+        config, server_spec = load_and_merge_config(
+            server_spec,
+            python=python,
+            with_packages=with_packages or [],
+            with_requirements=with_requirements,
+            project=project,
+            transport=transport,
+            host=host,
+            port=port,
+            path=path,
+            log_level=log_level,
+            server_args=list(server_args) if server_args else None,
+        )
+    except FileNotFoundError:
+        sys.exit(1)
+
+    # Get effective values (CLI overrides take precedence)
+    final_transport = (
+        transport if transport is not None else config.deployment.transport
+    )
+    final_host = host if host is not None else config.deployment.host
+    final_port = port if port is not None else config.deployment.port
+    final_path = path if path is not None else config.deployment.path
+    final_log_level = (
+        log_level if log_level is not None else config.deployment.log_level
+    )
+    final_server_args = server_args or config.deployment.args
+    # Use CLI override if provided, otherwise use settings
+    # no_banner CLI flag overrides the show_server_banner setting
+    final_no_banner = (
+        no_banner if no_banner else not fastmcp.settings.show_server_banner
+    )
+
+    logger.debug(
+        "Running server or client",
+        extra={
+            "server_spec": server_spec,
+            "transport": final_transport,
+            "host": final_host,
+            "port": final_port,
+            "path": final_path,
+            "log_level": final_log_level,
+            "server_args": list(final_server_args) if final_server_args else [],
+        },
+    )
+
+    # Handle reload mode
+    if reload:
+        # SSE is incompatible with reload (no stateless mode exists)
+        if final_transport == "sse":
+            logger.warning(
+                "--reload is not supported with SSE transport (sessions are lost on restart). "
+                "Use streamable-http transport instead, or use --no-reload. "
+                "Running without reload."
+            )
+            # Fall through to normal execution
+        else:
+            # Build command for subprocess (with --no-reload to prevent infinite spawning)
+            reload_cmd = ["fastmcp", "run", server_spec]
+            if final_transport:
+                reload_cmd.extend(["--transport", final_transport])
+            if final_transport != "stdio":
+                if final_host is not None:
+                    reload_cmd.extend(["--host", final_host])
+                if final_port is not None:
+                    reload_cmd.extend(["--port", str(final_port)])
+                if final_path is not None:
+                    reload_cmd.extend(["--path", final_path])
+            if final_log_level:
+                reload_cmd.extend(["--log-level", final_log_level])
+            if final_no_banner:
+                reload_cmd.append("--no-banner")
+            reload_cmd.append("--no-reload")  # Prevent infinite spawning
+            reload_cmd.append("--stateless")  # Stateless mode for reload compatibility
+
+            # If environment setup is needed, wrap with uv
+            test_cmd = ["test"]
+            needs_uv = (
+                config.environment.build_command(test_cmd) != test_cmd and not skip_env
+            )
+            if needs_uv:
+                # Add --skip-env to prevent nested uv runs (child would spawn another uv)
+                reload_cmd.append("--skip-env")
+
+            if final_server_args:
+                reload_cmd.append("--")
+                reload_cmd.extend(final_server_args)
+
+            if needs_uv:
+                reload_cmd = config.environment.build_command(reload_cmd)
+
+            is_stdio = final_transport in ("stdio", None)
+            await run_module.run_with_reload(
+                reload_cmd, reload_dirs=reload_dir, is_stdio=is_stdio
+            )
+            return
+
+    # Check if we need to use uv run (but skip if we're already in uv or user said to skip)
+    # We check if the environment would modify the command
+    test_cmd = ["test"]
+    needs_uv = config.environment.build_command(test_cmd) != test_cmd and not skip_env
+
+    if needs_uv:
+        # Build the inner fastmcp command
+        inner_cmd = ["fastmcp", "run", server_spec]
+
+        # Add transport options to the inner command
+        if final_transport:
+            inner_cmd.extend(["--transport", final_transport])
+        # Only add HTTP-specific options for non-stdio transports
+        if final_transport != "stdio":
+            if final_host is not None:
+                inner_cmd.extend(["--host", final_host])
+            if final_port is not None:
+                inner_cmd.extend(["--port", str(final_port)])
+            if final_path is not None:
+                inner_cmd.extend(["--path", final_path])
+        if final_log_level:
+            inner_cmd.extend(["--log-level", final_log_level])
+        if final_no_banner:
+            inner_cmd.append("--no-banner")
+        if stateless:
+            inner_cmd.append("--stateless")
+        # Add skip-env flag to prevent infinite recursion
+        inner_cmd.append("--skip-env")
+
+        # Add server args if any
+        if final_server_args:
+            inner_cmd.append("--")
+            inner_cmd.extend(final_server_args)
+
+        # Build the full uv command using the config's environment
+        cmd = config.environment.build_command(inner_cmd)
+
+        # Set marker to prevent infinite loops when subprocess calls FastMCP again
+        env = os.environ | {"FASTMCP_UV_SPAWNED": "1"}
+
+        # Run the command
+        logger.debug(f"Running command: {' '.join(cmd)}")
+        try:
+            process = subprocess.run(cmd, check=True, env=env)
+            sys.exit(process.returncode)
+        except subprocess.CalledProcessError as e:
+            logger.exception(
+                f"Failed to run: {e}",
+                extra={
+                    "server_spec": server_spec,
+                    "error": str(e),
+                    "returncode": e.returncode,
+                },
+            )
+            sys.exit(e.returncode)
+    else:
+        # Use direct import for backwards compatibility
+        try:
+            await run_module.run_command(
+                server_spec=server_spec,
+                transport=final_transport,
+                host=final_host,
+                port=final_port,
+                path=final_path,
+                log_level=final_log_level,
+                server_args=list(final_server_args) if final_server_args else [],
+                show_banner=not final_no_banner,
+                skip_source=skip_source,
+                stateless=stateless,
+            )
+        except Exception as e:
+            logger.exception(
+                f"Failed to run: {e}",
+                extra={
+                    "server_spec": server_spec,
+                    "error": str(e),
+                },
+            )
+            sys.exit(1)
+
+
+@app.command
+async def inspect(
+    server_spec: str | None = None,
+    *,
+    format: Annotated[
+        InspectFormat | None,
+        cyclopts.Parameter(
+            name=["--format", "-f"],
+            help="Output format: fastmcp (FastMCP-specific) or mcp (MCP protocol). Required when using -o.",
+        ),
+    ] = None,
+    output: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            name=["--output", "-o"],
+            help="Output file path for the JSON report. If not specified, outputs to stdout when format is provided.",
+        ),
+    ] = None,
+    python: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--python",
+            help="Python version to use (e.g., 3.10, 3.11)",
+        ),
+    ] = None,
+    with_packages: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            "--with", help="Additional packages to install (can be used multiple times)"
+        ),
+    ] = None,
+    project: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--project",
+            help="Run the command within the given project directory",
+        ),
+    ] = None,
+    with_requirements: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--with-requirements",
+            help="Requirements file to install dependencies from",
+        ),
+    ] = None,
+    skip_env: Annotated[
+        bool,
+        cyclopts.Parameter(
+            "--skip-env",
+            help="Skip environment configuration (for internal use when already in a uv environment)",
+        ),
+    ] = False,
+) -> None:
+    """Inspect an MCP server and display information or generate a JSON report.
+
+    This command analyzes an MCP server. Without flags, it displays a text summary.
+    Use --format to output complete JSON data.
+
+    Examples:
+        # Show text summary
+        fastmcp inspect server.py
+
+        # Output FastMCP format JSON to stdout
+        fastmcp inspect server.py --format fastmcp
+
+        # Save MCP protocol format to file (format required with -o)
+        fastmcp inspect server.py --format mcp -o manifest.json
+
+        # Inspect from fastmcp.json configuration
+        fastmcp inspect fastmcp.json
+        fastmcp inspect  # auto-detect fastmcp.json
+
+    Args:
+        server_spec: Python file to inspect, optionally with :object suffix, or fastmcp.json
+    """
+
+    # Check if we were spawned by uv (or user explicitly set --skip-env)
+    if skip_env or is_already_in_uv_subprocess():
+        skip_env = True
+
+    try:
+        # Load config and apply CLI overrides
+        config, server_spec = load_and_merge_config(
+            server_spec,
+            python=python,
+            with_packages=with_packages or [],
+            with_requirements=with_requirements,
+            project=project,
+        )
+
+        # Check if it's an MCPConfig (which inspect doesn't support)
+        if server_spec.endswith(".json") and config is None:
+            # This might be an MCPConfig, check the file
+            try:
+                with open(Path(server_spec)) as f:
+                    data = json.load(f)
+                if "mcpServers" in data:
+                    logger.error("MCPConfig files are not supported by inspect command")
+                    sys.exit(1)
+            except (json.JSONDecodeError, FileNotFoundError):
+                pass
+
+    except FileNotFoundError:
+        sys.exit(1)
+
+    # Check if we need to use uv run (but skip if we're already in uv or user said to skip)
+    # We check if the environment would modify the command
+    test_cmd = ["test"]
+    needs_uv = config.environment.build_command(test_cmd) != test_cmd and not skip_env
+
+    if needs_uv:
+        # Build and run uv command
+        # The environment is already configured in the config object
+        inspect_command = [
+            "fastmcp",
+            "inspect",
+            server_spec,
+            "--skip-env",  # Prevent infinite recursion
+        ]
+
+        # Add format and output flags if specified
+        if format:
+            inspect_command.extend(["--format", format.value])
+        if output:
+            inspect_command.extend(["--output", str(output)])
+
+        # Run the command using subprocess
+        import subprocess
+
+        cmd = config.environment.build_command(inspect_command)
+        env = os.environ | {"FASTMCP_UV_SPAWNED": "1"}
+        process = subprocess.run(cmd, check=True, env=env)
+        sys.exit(process.returncode)
+
+    logger.debug(
+        "Inspecting server",
+        extra={
+            "server_spec": server_spec,
+            "format": format,
+            "output": str(output) if output else None,
+        },
+    )
+
+    try:
+        # Load the server using the config
+        if not config:
+            logger.error("No configuration available")
+            sys.exit(1)
+        assert config is not None  # For type checker
+        server = await config.source.load_server()
+
+        # Get basic server information
+        info = await inspect_fastmcp(server)
+
+        # Check for invalid combination
+        if output and not format:
+            console.print(
+                "[bold red]Error:[/bold red] --format is required when using -o/--output"
+            )
+            console.print(
+                "[dim]Use --format fastmcp or --format mcp to specify the output format[/dim]"
+            )
+            sys.exit(1)
+
+        # If no format specified, show text summary
+        if format is None:
+            # Display text summary
+            console.print()
+
+            # Server section
+            console.print("[bold]Server[/bold]")
+            console.print(f"  Name:         {info.name}")
+            if info.version:
+                console.print(f"  Version:      {info.version}")
+            if info.website_url:
+                console.print(f"  Website:      {info.website_url}")
+            if info.icons:
+                console.print(f"  Icons:        {len(info.icons)}")
+            console.print(f"  Generation:   {info.server_generation}")
+            if info.instructions:
+                console.print(f"  Instructions: {info.instructions}")
+            console.print()
+
+            # Components section
+            console.print("[bold]Components[/bold]")
+            console.print(f"  Tools:        {len(info.tools)}")
+            console.print(f"  Prompts:      {len(info.prompts)}")
+            console.print(f"  Resources:    {len(info.resources)}")
+            console.print(f"  Templates:    {len(info.templates)}")
+            console.print()
+
+            # Environment section
+            console.print("[bold]Environment[/bold]")
+            console.print(f"  FastMCP:      {info.fastmcp_version}")
+            console.print(f"  MCP:          {info.mcp_version}")
+            console.print()
+
+            console.print(
+                "[dim]Use --format \\[fastmcp|mcp] for complete JSON output[/dim]"
+            )
+            return
+
+        # Generate formatted JSON output
+        formatted_json = await format_info(server, format, info)
+
+        # Output to file or stdout
+        if output:
+            # Ensure output directory exists
+            output.parent.mkdir(parents=True, exist_ok=True)
+
+            # Write JSON report
+            with output.open("wb") as f:
+                f.write(formatted_json)
+
+            logger.info(f"Server inspection complete. Report saved to {output}")
+
+            # Print confirmation to console
+            console.print(
+                f"[bold green]✓[/bold green] Server inspection saved to: [cyan]{output}[/cyan]"
+            )
+            console.print(f"  Server: [bold]{info.name}[/bold]")
+            console.print(f"  Format: {format.value}")
+        else:
+            # Output JSON to stdout
+            console.print(formatted_json.decode("utf-8"))
+
+    except Exception as e:
+        logger.exception(
+            f"Failed to inspect server: {e}",
+            extra={
+                "server_spec": server_spec,
+                "error": str(e),
+            },
+        )
+        console.print(f"[bold red]✗[/bold red] Failed to inspect server: {e}")
+        sys.exit(1)
+
+
+# Create project subcommand group
+project_app = cyclopts.App(name="project", help="Manage FastMCP projects")
+
+
+@project_app.command
+async def prepare(
+    config_path: Annotated[
+        str | None,
+        cyclopts.Parameter(help="Path to fastmcp.json configuration file"),
+    ] = None,
+    output_dir: Annotated[
+        str | None,
+        cyclopts.Parameter(help="Directory to create the persistent environment in"),
+    ] = None,
+    skip_source: Annotated[
+        bool,
+        cyclopts.Parameter(help="Skip source preparation (e.g., git clone)"),
+    ] = False,
+) -> None:
+    """Prepare a FastMCP project by creating a persistent uv environment.
+
+    This command creates a persistent uv project with all dependencies installed:
+    - Creates a pyproject.toml with dependencies from the config
+    - Installs all Python packages into a .venv
+    - Prepares the source (git clone, download, etc.) unless --skip-source
+
+    After running this command, you can use:
+    fastmcp run <config> --project <output-dir>
+
+    This is useful for:
+    - CI/CD pipelines with separate build and run stages
+    - Docker images where you prepare during build
+    - Production deployments where you want fast startup times
+
+    Example:
+        fastmcp project prepare myserver.json --output-dir ./prepared-env
+        fastmcp run myserver.json --project ./prepared-env
+    """
+    from pathlib import Path
+
+    # Require output-dir
+    if output_dir is None:
+        logger.error(
+            "The --output-dir parameter is required.\n"
+            "Please specify where to create the persistent environment."
+        )
+        sys.exit(1)
+
+    # Auto-detect fastmcp.json if not provided
+    if config_path is None:
+        found_config = MCPServerConfig.find_config()
+        if found_config:
+            config_path = str(found_config)
+            logger.info(f"Using configuration from {config_path}")
+        else:
+            logger.error(
+                "No configuration file specified and no fastmcp.json found.\n"
+                "Please specify a configuration file or create a fastmcp.json."
+            )
+            sys.exit(1)
+
+    assert config_path is not None
+    config_file = Path(config_path)
+    if not config_file.exists():
+        logger.error(f"Configuration file not found: {config_path}")
+        sys.exit(1)
+
+    assert output_dir is not None
+    output_path = Path(output_dir)
+
+    try:
+        # Load the configuration
+        config = MCPServerConfig.from_file(config_file)
+
+        # Prepare environment and source
+        await config.prepare(
+            skip_source=skip_source,
+            output_dir=output_path,
+        )
+
+        console.print(
+            f"[bold green]✓[/bold green] Project prepared successfully in {output_path}!\n"
+            f"You can now run the server with:\n"
+            f"  [cyan]fastmcp run {config_path} --project {output_dir}[/cyan]"
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to prepare project: {e}")
+        console.print(f"[bold red]✗[/bold red] Failed to prepare project: {e}")
+        sys.exit(1)
+
+
+# Add dev subcommand group
+app.command(dev_app)
+
+# Add project subcommand group
+app.command(project_app)
+
+# Add install subcommands using proper Cyclopts pattern
+app.command(install_app)
+
+# Add tasks subcommand group
+app.command(tasks_app)
+
+# Add client query commands
+app.command(list_command, name="list")
+app.command(call_command, name="call")
+app.command(discover_command, name="discover")
+app.command(generate_cli_command, name="generate-cli")
+
+# Add auth subcommand group (includes CIMD commands)
+app.command(auth_app)
+
+
+if __name__ == "__main__":
+    app()
diff --git a/fastmcp_slim/fastmcp/cli/client.py b/fastmcp_slim/fastmcp/cli/client.py
new file mode 100644
index 0000000..73fe468
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/client.py
@@ -0,0 +1,986 @@
+"""Client-side CLI commands for querying and invoking MCP servers."""
+
+import difflib
+import json
+import shlex
+import sys
+from pathlib import Path
+from typing import Annotated, Any, Literal
+
+import cyclopts
+import mcp_types
+from rich.console import Console
+from rich.markup import escape as escape_rich_markup
+
+from fastmcp.cli.discovery import DiscoveredServer, discover_servers, resolve_name
+from fastmcp.client.client import CallToolResult, Client
+from fastmcp.client.elicitation import ElicitResult
+from fastmcp.client.transports.base import ClientTransport
+from fastmcp.client.transports.http import StreamableHttpTransport
+from fastmcp.client.transports.sse import SSETransport
+from fastmcp.client.transports.stdio import StdioTransport
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger("cli.client")
+console = Console()
+
+
+# ---------------------------------------------------------------------------
+# Server spec resolution
+# ---------------------------------------------------------------------------
+
+_JSON_SCHEMA_TYPE_MAP: dict[str, str] = {
+    "string": "str",
+    "integer": "int",
+    "number": "float",
+    "boolean": "bool",
+    "array": "list",
+    "object": "dict",
+    "null": "None",
+}
+
+
+def resolve_server_spec(
+    server_spec: str | None,
+    *,
+    command: str | None = None,
+    transport: str | None = None,
+) -> str | dict[str, Any] | ClientTransport:
+    """Turn CLI inputs into something ``Client()`` accepts.
+
+    Exactly one of ``server_spec`` or ``command`` should be provided.
+
+    Resolution order for ``server_spec``:
+    1. URLs (``http://``, ``https://``) — passed through as-is.
+       If ``--transport`` is ``sse``, the URL is rewritten to end with ``/sse``
+       so ``infer_transport`` picks the right transport.
+    2. Existing file paths, or strings ending in ``.py``/``.js``/``.json``.
+    3. Anything else — name-based resolution via ``resolve_name``.
+
+    When ``command`` is provided, the string is shell-split into a
+    ``StdioTransport(command, args)``.
+    """
+
+    if command is not None and server_spec is not None:
+        console.print(
+            "[bold red]Error:[/bold red] Cannot use both a server spec and --command"
+        )
+        sys.exit(1)
+
+    if command is not None:
+        return _build_stdio_from_command(command)
+
+    if server_spec is None:
+        console.print(
+            "[bold red]Error:[/bold red] Provide a server spec or use --command"
+        )
+        sys.exit(1)
+
+    assert isinstance(server_spec, str)
+    spec: str = server_spec
+
+    # 1. URL
+    if spec.startswith(("http://", "https://")):
+        if transport == "sse" and not spec.rstrip("/").endswith("/sse"):
+            spec = spec.rstrip("/") + "/sse"
+        return spec
+
+    # 2. File path (must be a file, not a directory)
+    path = Path(spec)
+    is_file = path.is_file() or (
+        not path.is_dir() and spec.endswith((".py", ".js", ".json"))
+    )
+
+    if is_file:
+        if spec.endswith(".json"):
+            return _resolve_json_spec(path)
+        if spec.endswith(".py"):
+            # Run via `fastmcp run` so scripts don't need mcp.run()
+            resolved_path = path.resolve()
+            return StdioTransport(
+                command="fastmcp",
+                args=["run", str(resolved_path), "--no-banner"],
+            )
+        # .js — pass through for Client's infer_transport
+        return spec
+
+    # 3. Name-based resolution (bare name or source:name)
+    try:
+        return resolve_name(spec)
+    except ValueError as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        sys.exit(1)
+
+
+def _build_stdio_from_command(command_str: str) -> StdioTransport:
+    """Shell-split a command string into a ``StdioTransport``."""
+    try:
+        parts = shlex.split(command_str)
+    except ValueError as exc:
+        console.print(f"[bold red]Error:[/bold red] Invalid command: {exc}")
+        sys.exit(1)
+
+    if not parts:
+        console.print("[bold red]Error:[/bold red] Empty --command")
+        sys.exit(1)
+
+    return StdioTransport(command=parts[0], args=parts[1:])
+
+
+def _resolve_json_spec(path: Path) -> str | dict[str, Any]:
+    """Disambiguate a ``.json`` server spec."""
+
+    if not path.exists():
+        console.print(
+            f"[bold red]Error:[/bold red] File not found: [cyan]{path}[/cyan]"
+        )
+        sys.exit(1)
+
+    try:
+        data = json.loads(path.read_text())
+    except json.JSONDecodeError as exc:
+        console.print(f"[bold red]Error:[/bold red] Invalid JSON in {path}: {exc}")
+        sys.exit(1)
+
+    if isinstance(data, dict) and "mcpServers" in data:
+        return data
+
+    # Likely a fastmcp.json (MCPServerConfig) — not directly usable as a client target.
+    console.print(
+        f"[bold red]Error:[/bold red] [cyan]{path}[/cyan] is a FastMCP server config, not an MCPConfig.\n"
+        f"Start the server first, then query it:\n\n"
+        f"  fastmcp run {path}\n"
+        f"  fastmcp list http://localhost:8000/mcp\n"
+    )
+    sys.exit(1)
+
+
+def _is_http_target(resolved: str | dict[str, Any] | ClientTransport) -> bool:
+    """Return True if the resolved target will use an HTTP-based transport.
+
+    MCPConfig dicts are excluded because ``MCPConfigTransport`` manages
+    individual server transports internally and does not support top-level auth.
+    """
+    if isinstance(resolved, str):
+        return resolved.startswith(("http://", "https://"))
+    return isinstance(resolved, (StreamableHttpTransport, SSETransport))
+
+
+async def _terminal_elicitation_handler(
+    message: str,
+    response_type: type[Any] | None,
+    params: Any,
+    context: Any,
+) -> ElicitResult[dict[str, Any]]:
+    """Prompt the user on the terminal for elicitation responses.
+
+    Prints the server's message and prompts for each field in the schema.
+    The user can type 'decline' or 'cancel' instead of a value to abort.
+    """
+    from mcp_types import ElicitRequestFormParams
+
+    console.print(f"\n[bold yellow]Server asks:[/bold yellow] {message}")
+
+    if not isinstance(params, ElicitRequestFormParams):
+        answer = console.input(
+            "[dim](press Enter to accept, or type 'decline'):[/dim] "
+        )
+        if answer.strip().lower() == "decline":
+            return ElicitResult(action="decline")
+        if answer.strip().lower() == "cancel":
+            return ElicitResult(action="cancel")
+        return ElicitResult(action="accept", content={})
+
+    schema = params.requested_schema
+    properties = schema.get("properties", {})
+    required = set(schema.get("required", []))
+
+    if not properties:
+        answer = console.input(
+            "[dim](press Enter to accept, or type 'decline'):[/dim] "
+        )
+        if answer.strip().lower() == "decline":
+            return ElicitResult(action="decline")
+        if answer.strip().lower() == "cancel":
+            return ElicitResult(action="cancel")
+        return ElicitResult(action="accept", content={})
+
+    result: dict[str, Any] = {}
+    for field_name, field_schema in properties.items():
+        type_hint = field_schema.get("type", "string")
+        req_marker = " [red]*[/red]" if field_name in required else ""
+        prompt_text = f"  [cyan]{field_name}[/cyan] ({type_hint}){req_marker}: "
+
+        raw = console.input(prompt_text)
+        if raw.strip().lower() == "decline":
+            return ElicitResult(action="decline")
+        if raw.strip().lower() == "cancel":
+            return ElicitResult(action="cancel")
+
+        if raw == "" and field_name not in required:
+            continue
+
+        result[field_name] = coerce_value(raw, field_schema)
+
+    return ElicitResult(action="accept", content=result)
+
+
+def _build_client(
+    resolved: str | dict[str, Any] | ClientTransport,
+    *,
+    timeout: float | None = None,
+    auth: str | None = None,
+) -> Client:
+    """Build a ``Client`` from a resolved server spec.
+
+    Applies ``auth='oauth'`` automatically for HTTP-based targets unless
+    the caller explicitly passes ``--auth none`` to disable it.
+
+    ``auth=None`` means "not specified" (use default), ``auth="none"``
+    means "explicitly disabled".
+    """
+    if auth == "none":
+        effective_auth: str | None = None
+    elif auth is not None:
+        effective_auth = auth
+    elif _is_http_target(resolved):
+        effective_auth = "oauth"
+    else:
+        effective_auth = None
+
+    return Client(
+        resolved,
+        timeout=timeout,
+        auth=effective_auth,
+        elicitation_handler=_terminal_elicitation_handler,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Argument coercion
+# ---------------------------------------------------------------------------
+
+
+def coerce_value(raw: str, schema: dict[str, Any]) -> Any:
+    """Coerce a string CLI value according to a JSON-Schema type hint."""
+
+    schema_type = schema.get("type", "string")
+
+    if schema_type == "integer":
+        try:
+            return int(raw)
+        except ValueError:
+            raise ValueError(f"Expected integer, got {raw!r}") from None
+
+    if schema_type == "number":
+        try:
+            return float(raw)
+        except ValueError:
+            raise ValueError(f"Expected number, got {raw!r}") from None
+
+    if schema_type == "boolean":
+        if raw.lower() in ("true", "1", "yes"):
+            return True
+        if raw.lower() in ("false", "0", "no"):
+            return False
+        raise ValueError(f"Expected boolean, got {raw!r}")
+
+    if schema_type in ("array", "object"):
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError:
+            raise ValueError(f"Expected JSON {schema_type}, got {raw!r}") from None
+
+    # Default: treat as string
+    return raw
+
+
+def parse_tool_arguments(
+    raw_args: tuple[str, ...],
+    input_json: str | None,
+    input_schema: dict[str, Any],
+) -> dict[str, Any]:
+    """Build a tool-call argument dict from CLI inputs.
+
+    A single JSON object argument is treated as the full argument dict.
+    ``--input-json`` provides the base dict; ``key=value`` pairs override.
+    Values are coerced using the tool's ``inputSchema``.
+    """
+
+    # A single positional arg that looks like JSON → treat as input-json
+    if len(raw_args) == 1 and raw_args[0].startswith("{") and input_json is None:
+        input_json = raw_args[0]
+        raw_args = ()
+
+    result: dict[str, Any] = {}
+
+    if input_json is not None:
+        try:
+            parsed = json.loads(input_json)
+        except json.JSONDecodeError as exc:
+            console.print(f"[bold red]Error:[/bold red] Invalid --input-json: {exc}")
+            sys.exit(1)
+        if not isinstance(parsed, dict):
+            console.print(
+                "[bold red]Error:[/bold red] --input-json must be a JSON object"
+            )
+            sys.exit(1)
+        result.update(parsed)
+
+    properties = input_schema.get("properties", {})
+
+    for arg in raw_args:
+        if "=" not in arg:
+            console.print(
+                f"[bold red]Error:[/bold red] Invalid argument [cyan]{arg}[/cyan] — expected key=value"
+            )
+            sys.exit(1)
+        key, value = arg.split("=", 1)
+        prop_schema = properties.get(key, {})
+        try:
+            result[key] = coerce_value(value, prop_schema)
+        except ValueError as exc:
+            console.print(
+                f"[bold red]Error:[/bold red] Argument [cyan]{key}[/cyan]: {exc}"
+            )
+            sys.exit(1)
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Tool signature formatting
+# ---------------------------------------------------------------------------
+
+
+def _json_schema_type_to_str(schema: dict[str, Any]) -> str:
+    """Produce a short Python-style type string from a JSON-Schema fragment."""
+
+    if "anyOf" in schema:
+        parts = [_json_schema_type_to_str(s) for s in schema["anyOf"]]
+        return " | ".join(parts)
+
+    schema_type = schema.get("type", "any")
+    if isinstance(schema_type, list):
+        return " | ".join(_JSON_SCHEMA_TYPE_MAP.get(t, t) for t in schema_type)
+
+    return _JSON_SCHEMA_TYPE_MAP.get(schema_type, schema_type)
+
+
+def format_tool_signature(tool: mcp_types.Tool) -> str:
+    """Build ``name(param: type, ...) -> return_type`` from a tool's JSON schemas."""
+
+    params: list[str] = []
+    schema = tool.input_schema
+    properties = schema.get("properties", {})
+    required = set(schema.get("required", []))
+
+    for prop_name, prop_schema in properties.items():
+        type_str = _json_schema_type_to_str(prop_schema)
+        if prop_name in required:
+            params.append(f"{prop_name}: {type_str}")
+        else:
+            default = prop_schema.get("default")
+            default_repr = repr(default) if default is not None else "..."
+            params.append(f"{prop_name}: {type_str} = {default_repr}")
+
+    sig = f"{tool.name}({', '.join(params)})"
+
+    if tool.output_schema:
+        ret = _json_schema_type_to_str(tool.output_schema)
+        sig += f" -> {ret}"
+
+    return sig
+
+
+# ---------------------------------------------------------------------------
+# Output formatting
+# ---------------------------------------------------------------------------
+
+
+def _print_schema(label: str, schema: dict[str, Any]) -> None:
+    """Print a JSON schema with a label."""
+    properties = schema.get("properties", {})
+    if not properties:
+        return
+    console.print(f"    [dim]{label}: {json.dumps(schema)}[/dim]")
+
+
+def _sanitize_untrusted_text(value: str) -> str:
+    """Escape rich markup and encode control chars for terminal-safe output."""
+    sanitized = escape_rich_markup(value)
+    return "".join(
+        ch
+        if ch in {"\n", "\t"} or (0x20 <= ord(ch) < 0x7F) or ord(ch) > 0x9F
+        else f"\\x{ord(ch):02x}"
+        for ch in sanitized
+    )
+
+
+def _format_call_result_text(result: CallToolResult) -> None:
+    """Pretty-print a tool call result to the console."""
+
+    if result.is_error:
+        for block in result.content:
+            if isinstance(block, mcp_types.TextContent):
+                console.print(
+                    f"[bold red]Error:[/bold red] {_sanitize_untrusted_text(block.text)}"
+                )
+            else:
+                console.print(
+                    f"[bold red]Error:[/bold red] {_sanitize_untrusted_text(str(block))}"
+                )
+        return
+
+    if result.structured_content is not None:
+        console.print_json(json.dumps(result.structured_content))
+        return
+
+    for block in result.content:
+        if isinstance(block, mcp_types.TextContent):
+            console.print(_sanitize_untrusted_text(block.text))
+        elif isinstance(block, mcp_types.ImageContent):
+            size = len(block.data) * 3 // 4  # rough decoded size
+            console.print(f"[dim][Image: {block.mime_type}, ~{size} bytes][/dim]")
+        elif isinstance(block, mcp_types.AudioContent):
+            size = len(block.data) * 3 // 4
+            console.print(f"[dim][Audio: {block.mime_type}, ~{size} bytes][/dim]")
+        else:
+            console.print(_sanitize_untrusted_text(str(block)))
+
+
+def _content_block_to_dict(block: mcp_types.ContentBlock) -> dict[str, Any]:
+    """Serialize a single content block to a JSON-safe dict."""
+    if isinstance(block, mcp_types.TextContent):
+        return {"type": "text", "text": block.text}
+    if isinstance(block, mcp_types.ImageContent):
+        return {"type": "image", "mimeType": block.mime_type, "data": block.data}
+    if isinstance(block, mcp_types.AudioContent):
+        return {"type": "audio", "mimeType": block.mime_type, "data": block.data}
+    return {"type": "unknown", "value": str(block)}
+
+
+def _call_result_to_dict(result: CallToolResult) -> dict[str, Any]:
+    """Serialize a ``CallToolResult`` to a JSON-safe dict."""
+
+    content_list = [_content_block_to_dict(block) for block in result.content]
+    out: dict[str, Any] = {"content": content_list, "is_error": result.is_error}
+    if result.structured_content is not None:
+        out["structured_content"] = result.structured_content
+    return out
+
+
+def _tools_to_json(tools: list[mcp_types.Tool]) -> list[dict[str, Any]]:
+    """Serialize a list of tools to JSON-safe dicts."""
+
+    return [
+        {
+            "name": t.name,
+            "description": t.description,
+            "inputSchema": t.input_schema,
+            **({"outputSchema": t.output_schema} if t.output_schema else {}),
+        }
+        for t in tools
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Call handlers (tool, resource, prompt)
+# ---------------------------------------------------------------------------
+
+
+async def _handle_tool_call(
+    client: Client,
+    tool_name: str,
+    arguments: tuple[str, ...],
+    input_json: str | None,
+    json_output: bool,
+) -> None:
+    """Handle a tool call within an open client session."""
+    tools = await client.list_tools()
+    tool_map = {t.name: t for t in tools}
+
+    if tool_name not in tool_map:
+        close_matches = difflib.get_close_matches(
+            tool_name, tool_map.keys(), n=3, cutoff=0.5
+        )
+        msg = f"Tool [cyan]{tool_name}[/cyan] not found."
+        if close_matches:
+            suggestions = ", ".join(f"[cyan]{m}[/cyan]" for m in close_matches)
+            msg += f" Did you mean: {suggestions}?"
+        console.print(f"[bold red]Error:[/bold red] {msg}")
+        sys.exit(1)
+
+    tool = tool_map[tool_name]
+    parsed_args = parse_tool_arguments(arguments, input_json, tool.input_schema)
+
+    required = set(tool.input_schema.get("required", []))
+    provided = set(parsed_args.keys())
+    missing = required - provided
+    if missing:
+        missing_str = ", ".join(f"[cyan]{m}[/cyan]" for m in sorted(missing))
+        console.print(
+            f"[bold red]Error:[/bold red] Missing required arguments: {missing_str}"
+        )
+        console.print()
+        sig = format_tool_signature(tool)
+        console.print(f"  [dim]{sig}[/dim]")
+        sys.exit(1)
+
+    result = await client.call_tool(tool_name, parsed_args, raise_on_error=False)
+
+    if json_output:
+        console.print_json(json.dumps(_call_result_to_dict(result)))
+    else:
+        _format_call_result_text(result)
+
+    if result.is_error:
+        sys.exit(1)
+
+
+async def _handle_resource(
+    client: Client,
+    uri: str,
+    json_output: bool,
+) -> None:
+    """Handle a resource read within an open client session."""
+    contents = await client.read_resource(uri)
+
+    if json_output:
+        data = []
+        for block in contents:
+            if isinstance(block, mcp_types.TextResourceContents):
+                data.append(
+                    {
+                        "uri": str(block.uri),
+                        "mimeType": block.mime_type,
+                        "text": block.text,
+                    }
+                )
+            elif isinstance(block, mcp_types.BlobResourceContents):
+                data.append(
+                    {
+                        "uri": str(block.uri),
+                        "mimeType": block.mime_type,
+                        "blob": block.blob,
+                    }
+                )
+        console.print_json(json.dumps(data))
+        return
+
+    for block in contents:
+        if isinstance(block, mcp_types.TextResourceContents):
+            console.print(_sanitize_untrusted_text(block.text))
+        elif isinstance(block, mcp_types.BlobResourceContents):
+            size = len(block.blob) * 3 // 4
+            console.print(f"[dim][Blob: {block.mime_type}, ~{size} bytes][/dim]")
+
+
+async def _handle_prompt(
+    client: Client,
+    prompt_name: str,
+    arguments: tuple[str, ...],
+    input_json: str | None,
+    json_output: bool,
+) -> None:
+    """Handle a prompt get within an open client session."""
+    # Prompt arguments are always string->string, but we reuse
+    # parse_tool_arguments for the key=value / --input-json parsing.
+    # Pass an empty schema so values stay as strings.
+    parsed_args = parse_tool_arguments(arguments, input_json, {"type": "object"})
+
+    prompts = await client.list_prompts()
+    prompt_map = {p.name: p for p in prompts}
+
+    if prompt_name not in prompt_map:
+        close_matches = difflib.get_close_matches(
+            prompt_name, prompt_map.keys(), n=3, cutoff=0.5
+        )
+        msg = f"Prompt [cyan]{prompt_name}[/cyan] not found."
+        if close_matches:
+            suggestions = ", ".join(f"[cyan]{m}[/cyan]" for m in close_matches)
+            msg += f" Did you mean: {suggestions}?"
+        console.print(f"[bold red]Error:[/bold red] {msg}")
+        sys.exit(1)
+
+    result = await client.get_prompt(prompt_name, parsed_args or None)
+
+    if json_output:
+        data: dict[str, Any] = {}
+        if result.description:
+            data["description"] = result.description
+        data["messages"] = [
+            {
+                "role": msg.role,
+                "content": _content_block_to_dict(msg.content),
+            }
+            for msg in result.messages
+        ]
+        console.print_json(json.dumps(data))
+        return
+
+    for msg in result.messages:
+        console.print(f"[bold]{_sanitize_untrusted_text(msg.role)}:[/bold]")
+        if isinstance(msg.content, mcp_types.TextContent):
+            console.print(f"  {_sanitize_untrusted_text(msg.content.text)}")
+        elif isinstance(msg.content, mcp_types.ImageContent):
+            size = len(msg.content.data) * 3 // 4
+            console.print(
+                f"  [dim][Image: {msg.content.mime_type}, ~{size} bytes][/dim]"
+            )
+        else:
+            console.print(f"  {_sanitize_untrusted_text(str(msg.content))}")
+        console.print()
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+
+async def list_command(
+    server_spec: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            help="Server URL, Python file, MCPConfig JSON, or .js file",
+        ),
+    ] = None,
+    *,
+    command: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--command",
+            help="Stdio command to connect to (e.g. 'npx -y @mcp/server')",
+        ),
+    ] = None,
+    transport: Annotated[
+        Literal["http", "sse"] | None,
+        cyclopts.Parameter(
+            name=["--transport", "-t"],
+            help="Force transport type for URL targets (http or sse)",
+        ),
+    ] = None,
+    resources: Annotated[
+        bool,
+        cyclopts.Parameter("--resources", help="Also list resources"),
+    ] = False,
+    prompts: Annotated[
+        bool,
+        cyclopts.Parameter("--prompts", help="Also list prompts"),
+    ] = False,
+    input_schema: Annotated[
+        bool,
+        cyclopts.Parameter("--input-schema", help="Show full input schemas"),
+    ] = False,
+    output_schema: Annotated[
+        bool,
+        cyclopts.Parameter("--output-schema", help="Show full output schemas"),
+    ] = False,
+    json_output: Annotated[
+        bool,
+        cyclopts.Parameter("--json", help="Output as JSON"),
+    ] = False,
+    timeout: Annotated[
+        float | None,
+        cyclopts.Parameter("--timeout", help="Connection timeout in seconds"),
+    ] = None,
+    auth: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--auth",
+            help="Auth method: 'oauth', a bearer token string, or 'none' to disable",
+        ),
+    ] = None,
+) -> None:
+    """List tools available on an MCP server.
+
+    Examples:
+        fastmcp list http://localhost:8000/mcp
+        fastmcp list server.py
+        fastmcp list mcp.json --json
+        fastmcp list --command 'npx -y @mcp/server' --resources
+        fastmcp list http://server/mcp --transport sse
+    """
+
+    resolved = resolve_server_spec(server_spec, command=command, transport=transport)
+    client = _build_client(resolved, timeout=timeout, auth=auth)
+
+    try:
+        async with client:
+            tools = await client.list_tools()
+
+            if json_output:
+                data: dict[str, Any] = {"tools": _tools_to_json(tools)}
+                if resources:
+                    res = await client.list_resources()
+                    data["resources"] = [
+                        {
+                            "uri": str(r.uri),
+                            "name": r.name,
+                            "description": r.description,
+                            "mimeType": r.mime_type,
+                        }
+                        for r in res
+                    ]
+                if prompts:
+                    prm = await client.list_prompts()
+                    data["prompts"] = [
+                        {
+                            "name": p.name,
+                            "description": p.description,
+                            "arguments": [a.model_dump() for a in (p.arguments or [])],
+                        }
+                        for p in prm
+                    ]
+                console.print_json(json.dumps(data))
+                return
+
+            # Text output
+            if not tools:
+                console.print("[dim]No tools found.[/dim]")
+            else:
+                console.print(f"[bold]Tools ({len(tools)})[/bold]")
+                console.print()
+                for tool in tools:
+                    sig = format_tool_signature(tool)
+                    console.print(f"  [cyan]{_sanitize_untrusted_text(sig)}[/cyan]")
+                    if tool.description:
+                        console.print(
+                            f"    {_sanitize_untrusted_text(tool.description)}"
+                        )
+                    if input_schema:
+                        _print_schema("Input", tool.input_schema)
+                    if output_schema and tool.output_schema:
+                        _print_schema("Output", tool.output_schema)
+                    console.print()
+
+            if resources:
+                res = await client.list_resources()
+                console.print(f"[bold]Resources ({len(res)})[/bold]")
+                console.print()
+                if not res:
+                    console.print("  [dim]No resources found.[/dim]")
+                for r in res:
+                    console.print(
+                        f"  [cyan]{_sanitize_untrusted_text(str(r.uri))}[/cyan]"
+                    )
+                    desc_parts = [r.name or "", r.description or ""]
+                    desc = " — ".join(p for p in desc_parts if p)
+                    if desc:
+                        console.print(f"    {_sanitize_untrusted_text(desc)}")
+                console.print()
+
+            if prompts:
+                prm = await client.list_prompts()
+                console.print(f"[bold]Prompts ({len(prm)})[/bold]")
+                console.print()
+                if not prm:
+                    console.print("  [dim]No prompts found.[/dim]")
+                for p in prm:
+                    args_str = ""
+                    if p.arguments:
+                        parts = [a.name for a in p.arguments]
+                        args_str = f"({', '.join(parts)})"
+                    console.print(
+                        f"  [cyan]{_sanitize_untrusted_text(p.name + args_str)}[/cyan]"
+                    )
+                    if p.description:
+                        console.print(f"    {_sanitize_untrusted_text(p.description)}")
+                console.print()
+
+    except Exception as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        sys.exit(1)
+
+
+async def call_command(
+    server_spec: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            help="Server URL, Python file, MCPConfig JSON, or .js file",
+        ),
+    ] = None,
+    target: Annotated[
+        str,
+        cyclopts.Parameter(
+            help="Tool name, resource URI, or prompt name (with --prompt)",
+        ),
+    ] = "",
+    *arguments: str,
+    command: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--command",
+            help="Stdio command to connect to (e.g. 'npx -y @mcp/server')",
+        ),
+    ] = None,
+    transport: Annotated[
+        Literal["http", "sse"] | None,
+        cyclopts.Parameter(
+            name=["--transport", "-t"],
+            help="Force transport type for URL targets (http or sse)",
+        ),
+    ] = None,
+    prompt: Annotated[
+        bool,
+        cyclopts.Parameter("--prompt", help="Treat target as a prompt name"),
+    ] = False,
+    input_json: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--input-json",
+            help="JSON string of arguments (merged with key=value args)",
+        ),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        cyclopts.Parameter("--json", help="Output raw JSON result"),
+    ] = False,
+    timeout: Annotated[
+        float | None,
+        cyclopts.Parameter("--timeout", help="Connection timeout in seconds"),
+    ] = None,
+    auth: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--auth",
+            help="Auth method: 'oauth', a bearer token string, or 'none' to disable",
+        ),
+    ] = None,
+) -> None:
+    """Call a tool, read a resource, or get a prompt on an MCP server.
+
+    By default the target is treated as a tool name. If the target
+    contains ``://`` it is treated as a resource URI. Pass ``--prompt``
+    to treat it as a prompt name.
+
+    Arguments are passed as key=value pairs. Use --input-json for complex
+    or nested arguments.
+
+    Examples:
+        ```
+        fastmcp call server.py greet name=World
+        fastmcp call server.py resource://docs/readme
+        fastmcp call server.py analyze --prompt data='[1,2,3]'
+        fastmcp call http://server/mcp create --input-json '{"tags": ["a","b"]}'
+        ```
+    """
+
+    if not target:
+        console.print(
+            "[bold red]Error:[/bold red] Missing target.\n\n"
+            "Usage: fastmcp call <server> <target> [key=value ...]\n\n"
+            "  target can be a tool name, a resource URI, or a prompt name (with --prompt).\n\n"
+            "Use [cyan]fastmcp list <server>[/cyan] to see available tools."
+        )
+        sys.exit(1)
+
+    resolved = resolve_server_spec(server_spec, command=command, transport=transport)
+    client = _build_client(resolved, timeout=timeout, auth=auth)
+
+    try:
+        async with client:
+            if prompt:
+                await _handle_prompt(client, target, arguments, input_json, json_output)
+            elif "://" in target:
+                await _handle_resource(client, target, json_output)
+            else:
+                await _handle_tool_call(
+                    client, target, arguments, input_json, json_output
+                )
+
+    except Exception as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        sys.exit(1)
+
+
+async def discover_command(
+    *,
+    source: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            "--source",
+            help="Only show servers from these sources (e.g. claude-code, cursor, gemini)",
+        ),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        cyclopts.Parameter("--json", help="Output as JSON"),
+    ] = False,
+) -> None:
+    """Discover MCP servers configured in editor and project configs.
+
+    Scans Claude Desktop, Claude Code, Cursor, Gemini CLI, Goose, and
+    project-level mcp.json files for MCP server definitions.
+
+    Discovered server names can be used directly with ``fastmcp list``
+    and ``fastmcp call`` instead of specifying a URL or file path.
+
+    Examples:
+        fastmcp discover
+        fastmcp discover --source claude-code
+        fastmcp discover --source cursor --source gemini --json
+        fastmcp list weather
+        fastmcp call cursor:weather get_forecast city=London
+    """
+
+    servers = discover_servers()
+
+    if source:
+        servers = [s for s in servers if s.source in source]
+
+    if json_output:
+        data: list[dict[str, Any]] = [
+            {
+                "name": s.name,
+                "source": s.source,
+                "qualified_name": s.qualified_name,
+                "transport_summary": s.transport_summary,
+                "config_path": str(s.config_path),
+            }
+            for s in servers
+        ]
+        console.print_json(json.dumps(data))
+        return
+
+    if not servers:
+        console.print("[dim]No MCP servers found.[/dim]")
+        console.print()
+        console.print("Searched:")
+        console.print("  • Claude Desktop config")
+        console.print("  • ~/.claude.json (Claude Code)")
+        console.print("  • .cursor/mcp.json (walked up from cwd)")
+        console.print("  • ~/.gemini/settings.json (Gemini CLI)")
+        console.print("  • ~/.config/goose/config.yaml (Goose)")
+        console.print("  • ./mcp.json")
+        return
+
+    from rich.table import Table
+
+    # Group by source
+    by_source: dict[str, list[DiscoveredServer]] = {}
+    for s in servers:
+        by_source.setdefault(s.source, []).append(s)
+
+    for source_name, group in by_source.items():
+        console.print()
+        console.print(f"[bold]Source:[/bold]  {source_name}")
+        console.print(f"[bold]Config:[/bold]  [dim]{group[0].config_path}[/dim]")
+        console.print()
+
+        table = Table(
+            show_header=True,
+            header_style="bold",
+            show_edge=False,
+            pad_edge=False,
+            box=None,
+            padding=(0, 2),
+        )
+        table.add_column("Server", style="cyan")
+        table.add_column("Transport", style="dim")
+
+        for s in group:
+            table.add_row(s.name, s.transport_summary)
+
+        console.print(table)
+        console.print()
diff --git a/fastmcp_slim/fastmcp/cli/discovery.py b/fastmcp_slim/fastmcp/cli/discovery.py
new file mode 100644
index 0000000..5acd42d
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/discovery.py
@@ -0,0 +1,375 @@
+"""Discover MCP servers configured in editor config files.
+
+Scans filesystem-readable config files from editors like Claude Desktop,
+Claude Code, Cursor, Gemini CLI, and Goose, as well as project-level
+``mcp.json`` files. Each discovered server can be resolved by name
+(or ``source:name``) so the CLI can connect without requiring a URL
+or file path.
+"""
+
+import json
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from fastmcp.client.transports.base import ClientTransport
+from fastmcp.mcp_config import (
+    MCPConfig,
+    MCPServerTypes,
+    RemoteMCPServer,
+    StdioMCPServer,
+)
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger("cli.discovery")
+
+
+# ---------------------------------------------------------------------------
+# Data model
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class DiscoveredServer:
+    """A single MCP server found in an editor or project config."""
+
+    name: str
+    source: str
+    config: MCPServerTypes
+    config_path: Path
+
+    @property
+    def qualified_name(self) -> str:
+        """Fully qualified ``source:name`` identifier."""
+        return f"{self.source}:{self.name}"
+
+    @property
+    def transport_summary(self) -> str:
+        """Human-readable one-liner describing the transport."""
+        cfg = self.config
+        if isinstance(cfg, StdioMCPServer):
+            parts = [cfg.command, *cfg.args]
+            return f"stdio: {' '.join(parts)}"
+        if isinstance(cfg, RemoteMCPServer):
+            transport = cfg.transport or "http"
+            return f"{transport}: {cfg.url}"
+        return str(type(cfg).__name__)
+
+
+# ---------------------------------------------------------------------------
+# Scanners — one per config source
+# ---------------------------------------------------------------------------
+
+
+def _normalize_server_entry(entry: dict[str, Any]) -> dict[str, Any]:
+    """Normalize editor-specific server config fields to MCPConfig format.
+
+    Handles two known differences:
+    - Claude Code uses ``type`` where MCPConfig uses ``transport`` for
+      remote servers.
+    - Gemini CLI uses ``httpUrl`` where MCPConfig uses ``url``.
+    """
+    # Gemini: httpUrl → url
+    if "httpUrl" in entry and "url" not in entry:
+        entry = {**entry, "url": entry["httpUrl"]}
+        del entry["httpUrl"]
+
+    # Claude Code / others: type → transport (for url-based entries only)
+    if "url" in entry and "type" in entry and "transport" not in entry:
+        transport = entry["type"]
+        entry = {k: v for k, v in entry.items() if k != "type"}
+        entry["transport"] = transport
+
+    return entry
+
+
+def _parse_mcp_servers(
+    servers_dict: dict[str, Any],
+    *,
+    source: str,
+    config_path: Path,
+) -> list[DiscoveredServer]:
+    """Parse an ``mcpServers``-style dict into discovered servers."""
+    if not servers_dict:
+        return []
+
+    normalized = {
+        name: _normalize_server_entry(entry)
+        for name, entry in servers_dict.items()
+        if isinstance(entry, dict)
+    }
+
+    try:
+        config = MCPConfig.from_dict({"mcpServers": normalized})
+    except Exception as exc:
+        logger.warning("Could not parse MCP servers from %s: %s", config_path, exc)
+        return []
+
+    return [
+        DiscoveredServer(
+            name=name, source=source, config=server, config_path=config_path
+        )
+        for name, server in config.mcpServers.items()
+    ]
+
+
+def _parse_mcp_config(path: Path, source: str) -> list[DiscoveredServer]:
+    """Parse an mcpServers-style JSON file into discovered servers."""
+    try:
+        text = path.read_text()
+    except OSError as exc:
+        logger.debug("Could not read %s: %s", path, exc)
+        return []
+
+    try:
+        data: dict[str, Any] = json.loads(text)
+    except json.JSONDecodeError as exc:
+        logger.warning("Invalid JSON in %s: %s", path, exc)
+        return []
+
+    if not isinstance(data, dict) or "mcpServers" not in data:
+        return []
+
+    return _parse_mcp_servers(data["mcpServers"], source=source, config_path=path)
+
+
+def _scan_claude_desktop() -> list[DiscoveredServer]:
+    """Scan the Claude Desktop config file."""
+    if sys.platform == "win32":
+        config_dir = Path(Path.home(), "AppData", "Roaming", "Claude")
+    elif sys.platform == "darwin":
+        config_dir = Path(Path.home(), "Library", "Application Support", "Claude")
+    elif sys.platform.startswith("linux"):
+        config_dir = Path(
+            os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"), "Claude"
+        )
+    else:
+        return []
+
+    path = config_dir / "claude_desktop_config.json"
+    return _parse_mcp_config(path, "claude-desktop")
+
+
+def _scan_claude_code(start_dir: Path) -> list[DiscoveredServer]:
+    """Scan ``~/.claude.json`` for global and project-scoped MCP servers."""
+    path = Path.home() / ".claude.json"
+    try:
+        text = path.read_text()
+    except OSError:
+        return []
+
+    try:
+        data: dict[str, Any] = json.loads(text)
+    except json.JSONDecodeError as exc:
+        logger.warning("Invalid JSON in %s: %s", path, exc)
+        return []
+
+    if not isinstance(data, dict):
+        return []
+
+    results: list[DiscoveredServer] = []
+
+    # Global servers
+    if global_servers := data.get("mcpServers"):
+        if isinstance(global_servers, dict):
+            results.extend(
+                _parse_mcp_servers(
+                    global_servers, source="claude-code", config_path=path
+                )
+            )
+
+    # Project-scoped servers matching start_dir
+    resolved_dir = str(start_dir.resolve())
+    projects = data.get("projects", {})
+    if isinstance(projects, dict):
+        project_data = projects.get(resolved_dir, {})
+        if isinstance(project_data, dict):
+            if project_servers := project_data.get("mcpServers"):
+                if isinstance(project_servers, dict):
+                    results.extend(
+                        _parse_mcp_servers(
+                            project_servers,
+                            source="claude-code",
+                            config_path=path,
+                        )
+                    )
+
+    return results
+
+
+def _scan_cursor_workspace(start_dir: Path) -> list[DiscoveredServer]:
+    """Walk up from *start_dir* looking for ``.cursor/mcp.json``."""
+    current = start_dir.resolve()
+    home = Path.home().resolve()
+
+    while True:
+        candidate = current / ".cursor" / "mcp.json"
+        if candidate.is_file():
+            return _parse_mcp_config(candidate, "cursor")
+
+        parent = current.parent
+        # Stop at filesystem root or home directory
+        if parent == current or current == home:
+            break
+        current = parent
+
+    return []
+
+
+def _scan_project_mcp_json(start_dir: Path) -> list[DiscoveredServer]:
+    """Check for ``mcp.json`` in *start_dir*."""
+    candidate = start_dir.resolve() / "mcp.json"
+    if candidate.is_file():
+        return _parse_mcp_config(candidate, "project")
+    return []
+
+
+def _scan_gemini(start_dir: Path) -> list[DiscoveredServer]:
+    """Scan Gemini CLI settings for MCP servers.
+
+    Checks both user-level ``~/.gemini/settings.json`` and project-level
+    ``.gemini/settings.json``.
+    """
+    results: list[DiscoveredServer] = []
+
+    # User-level
+    user_path = Path.home() / ".gemini" / "settings.json"
+    results.extend(_parse_mcp_config(user_path, "gemini"))
+
+    # Project-level
+    project_path = start_dir.resolve() / ".gemini" / "settings.json"
+    if project_path != user_path:
+        results.extend(_parse_mcp_config(project_path, "gemini"))
+
+    return results
+
+
+def _scan_goose() -> list[DiscoveredServer]:
+    """Scan Goose config for MCP server extensions.
+
+    Goose uses YAML (``~/.config/goose/config.yaml``) with a different
+    schema — MCP servers are defined as ``extensions`` with ``type: stdio``.
+    """
+    if sys.platform == "win32":
+        config_dir = Path(
+            os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming"),
+            "Block",
+            "goose",
+            "config",
+        )
+    else:
+        config_dir = Path(
+            os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"),
+            "goose",
+        )
+
+    path = config_dir / "config.yaml"
+    try:
+        text = path.read_text()
+    except OSError:
+        return []
+
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        logger.warning("Invalid YAML in %s: %s", path, exc)
+        return []
+
+    if not isinstance(data, dict):
+        return []
+
+    extensions = data.get("extensions", {})
+    if not isinstance(extensions, dict):
+        return []
+
+    # Convert Goose extensions to mcpServers format
+    servers: dict[str, Any] = {}
+    for name, ext in extensions.items():
+        if not isinstance(ext, dict):
+            continue
+        if not ext.get("enabled", True):
+            continue
+        ext_type = ext.get("type", "")
+        if ext_type == "stdio" and "cmd" in ext:
+            servers[name] = {
+                "command": ext["cmd"],
+                "args": ext.get("args", []),
+                "env": ext.get("envs", {}),
+            }
+        elif ext_type == "sse" and "uri" in ext:
+            servers[name] = {"url": ext["uri"], "transport": "sse"}
+
+    return _parse_mcp_servers(servers, source="goose", config_path=path)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def discover_servers(start_dir: Path | None = None) -> list[DiscoveredServer]:
+    """Run all scanners and return the combined results.
+
+    Duplicate names across sources are preserved — callers can
+    use :pyattr:`DiscoveredServer.qualified_name` to disambiguate.
+    """
+    cwd = start_dir or Path.cwd()
+    results: list[DiscoveredServer] = []
+    results.extend(_scan_claude_desktop())
+    results.extend(_scan_claude_code(cwd))
+    results.extend(_scan_cursor_workspace(cwd))
+    results.extend(_scan_gemini(cwd))
+    results.extend(_scan_goose())
+    results.extend(_scan_project_mcp_json(cwd))
+    return results
+
+
+def resolve_name(name: str, start_dir: Path | None = None) -> ClientTransport:
+    """Resolve a server name (or ``source:name``) to a transport.
+
+    Raises :class:`ValueError` when the name is not found or is ambiguous.
+    """
+    servers = discover_servers(start_dir)
+
+    # Qualified form: "cursor:weather"
+    if ":" in name:
+        source, server_name = name.split(":", 1)
+        matches = [s for s in servers if s.source == source and s.name == server_name]
+        if not matches:
+            raise ValueError(
+                f"No server named '{server_name}' found in source '{source}'."
+            )
+        return matches[0].config.to_transport()
+
+    # Bare name: "weather"
+    matches = [s for s in servers if s.name == name]
+
+    if not matches:
+        if servers:
+            available = ", ".join(sorted({s.name for s in servers}))
+            raise ValueError(f"No server named '{name}' found. Available: {available}")
+        locations = [
+            "Claude Desktop config",
+            "~/.claude.json (Claude Code)",
+            ".cursor/mcp.json (walked up from cwd)",
+            "~/.gemini/settings.json (Gemini CLI)",
+            "~/.config/goose/config.yaml (Goose)",
+            "./mcp.json",
+        ]
+        raise ValueError(
+            f"No server named '{name}' found. Searched: {', '.join(locations)}"
+        )
+
+    if len(matches) == 1:
+        return matches[0].config.to_transport()
+
+    # Ambiguous — list qualified alternatives
+    alternatives = ", ".join(f"'{m.qualified_name}'" for m in matches)
+    raise ValueError(
+        f"Ambiguous server name '{name}' — found in multiple sources. "
+        f"Use a qualified name: {alternatives}"
+    )
diff --git a/fastmcp_slim/fastmcp/cli/generate.py b/fastmcp_slim/fastmcp/cli/generate.py
new file mode 100644
index 0000000..1457765
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/generate.py
@@ -0,0 +1,806 @@
+"""Generate a standalone CLI script and agent skill from an MCP server."""
+
+import keyword
+import re
+import sys
+import textwrap
+from pathlib import Path
+from typing import Annotated, Any
+from urllib.parse import urlparse
+
+import cyclopts
+import mcp_types
+import pydantic_core
+from mcp import MCPError
+from rich.console import Console
+
+from fastmcp.cli.client import _build_client, resolve_server_spec
+from fastmcp.client.transports.base import ClientTransport
+from fastmcp.client.transports.stdio import StdioTransport
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger("cli.generate")
+console = Console()
+
+# ---------------------------------------------------------------------------
+# JSON Schema type → Python type string
+# ---------------------------------------------------------------------------
+
+_SIMPLE_TYPES = {"string", "integer", "number", "boolean", "null"}
+
+
+def _is_simple_type(schema: dict[str, Any]) -> bool:
+    """Check if a schema represents a simple (non-complex) type."""
+    schema_type = schema.get("type")
+    if isinstance(schema_type, list):
+        # Union of types - simple only if all are simple
+        return all(t in _SIMPLE_TYPES for t in schema_type)
+    return schema_type in _SIMPLE_TYPES
+
+
+def _is_simple_array(schema: dict[str, Any]) -> tuple[bool, str | None]:
+    """Check if schema is an array of simple types.
+
+    Returns (is_simple_array, item_type_str).
+    """
+    if schema.get("type") != "array":
+        return False, None
+
+    items = schema.get("items", {})
+    if not _is_simple_type(items):
+        return False, None
+
+    # Map JSON Schema type to Python type
+    item_type = items.get("type", "string")
+    if isinstance(item_type, list):
+        return False, None
+    type_map = {
+        "string": "str",
+        "integer": "int",
+        "number": "float",
+        "boolean": "bool",
+    }
+    py_type = type_map.get(item_type)
+    if py_type is None:
+        return False, None
+    return True, py_type
+
+
+def _schema_to_python_type(schema: dict[str, Any]) -> tuple[str, bool]:
+    """Convert a JSON Schema to a Python type annotation.
+
+    Returns (type_annotation, needs_json_parsing).
+    """
+    # Check for simple array first
+    is_simple_arr, item_type = _is_simple_array(schema)
+    if is_simple_arr:
+        return f"list[{item_type}]", False
+
+    # Check for simple type
+    if _is_simple_type(schema):
+        schema_type = schema.get("type", "string")
+        if isinstance(schema_type, list):
+            # Union of simple types
+            type_map = {
+                "string": "str",
+                "integer": "int",
+                "number": "float",
+                "boolean": "bool",
+                "null": "None",
+            }
+            parts = [type_map.get(t, "str") for t in schema_type]
+            return " | ".join(parts), False
+
+        type_map = {
+            "string": "str",
+            "integer": "int",
+            "number": "float",
+            "boolean": "bool",
+            "null": "None",
+        }
+        return type_map.get(schema_type, "str"), False
+
+    # Complex type - needs JSON parsing
+    return "str", True
+
+
+def _format_schema_for_help(schema: dict[str, Any]) -> str:
+    """Format a JSON schema for display in help text."""
+    # Pretty print the schema, indented for help text
+    schema_str = pydantic_core.to_json(schema, indent=2).decode()
+    # Indent each line for help text alignment
+    lines = schema_str.split("\n")
+    indented = "\n                          ".join(lines)
+    return f"JSON Schema: {indented}"
+
+
+# ---------------------------------------------------------------------------
+# Transport serialization
+# ---------------------------------------------------------------------------
+
+
+def serialize_transport(
+    resolved: str | dict[str, Any] | ClientTransport,
+) -> tuple[str, set[str]]:
+    """Serialize a resolved transport to a Python expression string.
+
+    Returns ``(expression, extra_imports)`` where *extra_imports* is a set of
+    import lines needed by the expression.
+    """
+    if isinstance(resolved, str):
+        return repr(resolved), set()
+
+    if isinstance(resolved, StdioTransport):
+        parts = [f"command={resolved.command!r}", f"args={resolved.args!r}"]
+        if resolved.env:
+            parts.append(f"env={resolved.env!r}")
+        if resolved.cwd:
+            parts.append(f"cwd={resolved.cwd!r}")
+        expr = f"StdioTransport({', '.join(parts)})"
+        imports = {"from fastmcp.client.transports import StdioTransport"}
+        return expr, imports
+
+    if isinstance(resolved, dict):
+        return repr(resolved), set()
+
+    # Fallback: try repr
+    return repr(resolved), set()
+
+
+# ---------------------------------------------------------------------------
+# Per-tool code generation
+# ---------------------------------------------------------------------------
+
+
+def _to_python_identifier(name: str) -> str:
+    """Sanitize a string into a valid Python identifier."""
+    safe = re.sub(r"[^a-zA-Z0-9_]", "_", name)
+    if safe and safe[0].isdigit():
+        safe = f"_{safe}"
+    safe = safe or "_unnamed"
+    if keyword.iskeyword(safe):
+        safe = f"{safe}_"
+    return safe
+
+
+def _tool_function_source(tool: mcp_types.Tool) -> str:
+    """Generate the source for a single ``@call_tool_app.command`` function."""
+    schema = tool.input_schema
+    properties: dict[str, Any] = schema.get("properties", {})
+    required = set(schema.get("required", []))
+
+    # Build parameter lines and track which need JSON parsing
+    param_lines: list[str] = []
+    call_args: list[str] = []
+    json_params: list[tuple[str, str]] = []  # (prop_name, safe_name)
+    seen_names: dict[str, str] = {}  # safe_name -> original prop_name
+
+    for prop_name, prop_schema in properties.items():
+        py_type, needs_json = _schema_to_python_type(prop_schema)
+        help_text = prop_schema.get("description", "")
+        is_required = prop_name in required
+        safe_name = _to_python_identifier(prop_name)
+
+        # Check for name collisions after sanitization
+        if safe_name in seen_names:
+            raise ValueError(
+                f"Parameter name collision: '{prop_name}' and '{seen_names[safe_name]}' "
+                f"both sanitize to '{safe_name}'"
+            )
+        seen_names[safe_name] = prop_name
+
+        # For complex types, add schema to help text
+        if needs_json:
+            schema_help = _format_schema_for_help(prop_schema)
+            help_text = f"{help_text}\\n{schema_help}" if help_text else schema_help
+            json_params.append((prop_name, safe_name))
+
+        # Escape special characters in help text
+        help_escaped = (
+            help_text.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+        )
+
+        # Build parameter annotation
+        if is_required:
+            annotation = (
+                f'Annotated[{py_type}, cyclopts.Parameter(help="{help_escaped}")]'
+            )
+            param_lines.append(f"    {safe_name}: {annotation},")
+        else:
+            default = prop_schema.get("default")
+            if default is not None:
+                # For complex types with defaults, serialize to JSON string
+                if needs_json:
+                    default_str = pydantic_core.to_json(default, fallback=str).decode()
+                    annotation = f'Annotated[{py_type}, cyclopts.Parameter(help="{help_escaped}")]'
+                    param_lines.append(
+                        f"    {safe_name}: {annotation} = {default_str!r},"
+                    )
+                else:
+                    annotation = f'Annotated[{py_type}, cyclopts.Parameter(help="{help_escaped}")]'
+                    param_lines.append(f"    {safe_name}: {annotation} = {default!r},")
+            else:
+                # For list types, default to empty list; others default to None
+                if py_type.startswith("list["):
+                    annotation = f'Annotated[{py_type}, cyclopts.Parameter(help="{help_escaped}")]'
+                    param_lines.append(f"    {safe_name}: {annotation} = [],")
+                else:
+                    annotation = f'Annotated[{py_type} | None, cyclopts.Parameter(help="{help_escaped}")]'
+                    param_lines.append(f"    {safe_name}: {annotation} = None,")
+
+        call_args.append(f"{prop_name!r}: {safe_name}")
+
+    # Function name: sanitize to valid Python identifier
+    fn_name = _to_python_identifier(tool.name)
+
+    # Docstring - use single-quoted docstrings to avoid triple-quote escaping issues
+    description = (tool.description or "").replace("\\", "\\\\").replace("'", "\\'")
+
+    lines = []
+    lines.append("")
+    # Always pass name= to preserve the original tool name (cyclopts
+    # would otherwise convert underscores to hyphens).
+    lines.append(f"@call_tool_app.command(name={tool.name!r})")
+    lines.append(f"async def {fn_name}(")
+
+    if param_lines:
+        lines.append("    *,")
+        lines.extend(param_lines)
+
+    lines.append(") -> None:")
+    lines.append(f"    '''{description}'''")
+
+    # Add JSON parsing for complex parameters
+    if json_params:
+        lines.append("    # Parse JSON parameters")
+        for _prop_name, safe_name in json_params:
+            lines.append(
+                f"    {safe_name}_parsed = json.loads({safe_name}) if isinstance({safe_name}, str) else {safe_name}"
+            )
+        lines.append("")
+
+    # Build call arguments, using parsed versions for JSON params
+    call_arg_parts = []
+    for prop_name in properties:
+        safe_name = _to_python_identifier(prop_name)
+        if any(pn == prop_name for pn, _ in json_params):
+            call_arg_parts.append(f"{prop_name!r}: {safe_name}_parsed")
+        else:
+            call_arg_parts.append(f"{prop_name!r}: {safe_name}")
+
+    dict_items = ", ".join(call_arg_parts)
+    lines.append(f"    await _call_tool({tool.name!r}, {{{dict_items}}})")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Full script generation
+# ---------------------------------------------------------------------------
+
+
+def generate_cli_script(
+    server_name: str,
+    server_spec: str,
+    transport_code: str,
+    extra_imports: set[str],
+    tools: list[mcp_types.Tool],
+) -> str:
+    """Generate the full CLI script source code."""
+
+    # Determine app name from server_name - sanitize for use in string literal
+    app_name = (
+        server_name.replace(" ", "-").lower().replace("\\", "\\\\").replace('"', '\\"')
+    )
+
+    # --- Header ---
+    lines: list[str] = []
+    lines.append("#!/usr/bin/env python3")
+    lines.append(f'"""CLI for {server_name} MCP server.')
+    lines.append("")
+    lines.append(f"Generated by: fastmcp generate-cli {server_spec}")
+    lines.append('"""')
+    lines.append("")
+
+    # --- Imports ---
+    lines.append("import json")
+    lines.append("import sys")
+    lines.append("from typing import Annotated")
+    lines.append("")
+    lines.append("import cyclopts")
+    lines.append("import mcp_types")
+    lines.append("from rich.console import Console")
+    lines.append("")
+    lines.append("from fastmcp import Client")
+    lines.extend(sorted(extra_imports))
+    lines.append("")
+
+    # --- Transport config ---
+    lines.append("# Modify this to change how the CLI connects to the MCP server.")
+    lines.append(f"CLIENT_SPEC = {transport_code}")
+    lines.append("")
+
+    # --- App setup ---
+    server_name_escaped = server_name.replace("\\", "\\\\").replace('"', '\\"')
+    lines.append(
+        f'app = cyclopts.App(name="{app_name}", help="CLI for {server_name_escaped} MCP server")'
+    )
+    lines.append(
+        'call_tool_app = cyclopts.App(name="call-tool", help="Call a tool on the server")'
+    )
+    lines.append("app.command(call_tool_app)")
+    lines.append("")
+    lines.append("console = Console()")
+    lines.append("")
+    lines.append("")
+
+    # --- Shared helpers ---
+    lines.append(
+        textwrap.dedent("""\
+        # ---------------------------------------------------------------------------
+        # Helpers
+        # ---------------------------------------------------------------------------
+
+
+        def _print_tool_result(result):
+            if result.is_error:
+                for block in result.content:
+                    if isinstance(block, mcp_types.TextContent):
+                        console.print(f"[bold red]Error:[/bold red] {block.text}")
+                    else:
+                        console.print(f"[bold red]Error:[/bold red] {block}")
+                sys.exit(1)
+
+            if result.structured_content is not None:
+                console.print_json(json.dumps(result.structured_content))
+                return
+
+            for block in result.content:
+                if isinstance(block, mcp_types.TextContent):
+                    console.print(block.text)
+                elif isinstance(block, mcp_types.ImageContent):
+                    size = len(block.data) * 3 // 4
+                    console.print(f"[dim][Image: {block.mime_type}, ~{size} bytes][/dim]")
+                elif isinstance(block, mcp_types.AudioContent):
+                    size = len(block.data) * 3 // 4
+                    console.print(f"[dim][Audio: {block.mime_type}, ~{size} bytes][/dim]")
+
+
+        async def _call_tool(tool_name: str, arguments: dict) -> None:
+            # Filter out None values and empty lists (defaults for optional array params)
+            filtered = {
+                k: v
+                for k, v in arguments.items()
+                if v is not None and (not isinstance(v, list) or len(v) > 0)
+            }
+            async with Client(CLIENT_SPEC) as client:
+                result = await client.call_tool(tool_name, filtered, raise_on_error=False)
+                _print_tool_result(result)
+                if result.is_error:
+                    sys.exit(1)""")
+    )
+    lines.append("")
+    lines.append("")
+
+    # --- Generic commands ---
+    lines.append(
+        textwrap.dedent("""\
+        # ---------------------------------------------------------------------------
+        # List / read commands
+        # ---------------------------------------------------------------------------
+
+
+        @app.command
+        async def list_tools() -> None:
+            \"\"\"List available tools.\"\"\"
+            async with Client(CLIENT_SPEC) as client:
+                tools = await client.list_tools()
+                if not tools:
+                    console.print("[dim]No tools found.[/dim]")
+                    return
+                for tool in tools:
+                    sig_parts = []
+                    props = tool.input_schema.get("properties", {})
+                    required = set(tool.input_schema.get("required", []))
+                    for pname, pschema in props.items():
+                        ptype = pschema.get("type", "string")
+                        if pname in required:
+                            sig_parts.append(f"{pname}: {ptype}")
+                        else:
+                            sig_parts.append(f"{pname}: {ptype} = ...")
+                    sig = f"{tool.name}({', '.join(sig_parts)})"
+                    console.print(f"  [cyan]{sig}[/cyan]")
+                    if tool.description:
+                        console.print(f"    {tool.description}")
+                    console.print()
+
+
+        @app.command
+        async def list_resources() -> None:
+            \"\"\"List available resources.\"\"\"
+            async with Client(CLIENT_SPEC) as client:
+                resources = await client.list_resources()
+                if not resources:
+                    console.print("[dim]No resources found.[/dim]")
+                    return
+                for r in resources:
+                    console.print(f"  [cyan]{r.uri}[/cyan]")
+                    desc_parts = [r.name or "", r.description or ""]
+                    desc = " — ".join(p for p in desc_parts if p)
+                    if desc:
+                        console.print(f"    {desc}")
+                console.print()
+
+
+        @app.command
+        async def read_resource(uri: Annotated[str, cyclopts.Parameter(help="Resource URI")]) -> None:
+            \"\"\"Read a resource by URI.\"\"\"
+            async with Client(CLIENT_SPEC) as client:
+                contents = await client.read_resource(uri)
+                for block in contents:
+                    if isinstance(block, mcp_types.TextResourceContents):
+                        console.print(block.text)
+                    elif isinstance(block, mcp_types.BlobResourceContents):
+                        size = len(block.blob) * 3 // 4
+                        console.print(f"[dim][Blob: {block.mime_type}, ~{size} bytes][/dim]")
+
+
+        @app.command
+        async def list_prompts() -> None:
+            \"\"\"List available prompts.\"\"\"
+            async with Client(CLIENT_SPEC) as client:
+                prompts = await client.list_prompts()
+                if not prompts:
+                    console.print("[dim]No prompts found.[/dim]")
+                    return
+                for p in prompts:
+                    args_str = ""
+                    if p.arguments:
+                        parts = [a.name for a in p.arguments]
+                        args_str = f"({', '.join(parts)})"
+                    console.print(f"  [cyan]{p.name}{args_str}[/cyan]")
+                    if p.description:
+                        console.print(f"    {p.description}")
+                console.print()
+
+
+        @app.command
+        async def get_prompt(
+            name: Annotated[str, cyclopts.Parameter(help="Prompt name")],
+            *arguments: str,
+        ) -> None:
+            \"\"\"Get a prompt by name. Pass arguments as key=value pairs.\"\"\"
+            parsed: dict[str, str] = {}
+            for arg in arguments:
+                if "=" not in arg:
+                    console.print(f"[bold red]Error:[/bold red] Invalid argument {arg!r} — expected key=value")
+                    sys.exit(1)
+                key, value = arg.split("=", 1)
+                parsed[key] = value
+
+            async with Client(CLIENT_SPEC) as client:
+                result = await client.get_prompt(name, parsed or None)
+                for msg in result.messages:
+                    console.print(f"[bold]{msg.role}:[/bold]")
+                    if isinstance(msg.content, mcp_types.TextContent):
+                        console.print(f"  {msg.content.text}")
+                    elif isinstance(msg.content, mcp_types.ImageContent):
+                        size = len(msg.content.data) * 3 // 4
+                        console.print(f"  [dim][Image: {msg.content.mime_type}, ~{size} bytes][/dim]")
+                    else:
+                        console.print(f"  {msg.content}")
+                    console.print()""")
+    )
+    lines.append("")
+    lines.append("")
+
+    # --- Generated tool commands ---
+    if tools:
+        lines.append(
+            "# ---------------------------------------------------------------------------"
+        )
+        lines.append("# Tool commands (generated from server schema)")
+        lines.append(
+            "# ---------------------------------------------------------------------------"
+        )
+
+        lines.extend(_tool_function_source(tool) for tool in tools)
+
+    # --- Entry point ---
+    lines.append("")
+    lines.append('if __name__ == "__main__":')
+    lines.append("    app()")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Skill (SKILL.md) generation
+# ---------------------------------------------------------------------------
+
+_JSON_SCHEMA_TYPE_LABELS: dict[str, str] = {
+    "string": "string",
+    "integer": "integer",
+    "number": "number",
+    "boolean": "boolean",
+    "null": "null",
+    "array": "array",
+    "object": "object",
+}
+
+
+def _param_to_cli_flag(prop_name: str) -> str:
+    """Convert a JSON Schema property name to its CLI flag form.
+
+    Replicates cyclopts' default_name_transform: camelCase → snake_case,
+    lowercase, underscores → hyphens, strip leading/trailing hyphens.
+    """
+    safe = _to_python_identifier(prop_name)
+    # camelCase / PascalCase → snake_case
+    safe = re.sub(r"(.)([A-Z][a-z]+)", r"\1_\2", safe)
+    safe = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", safe)
+    safe = safe.lower().replace("_", "-").strip("-")
+    return f"--{safe}" if safe else "--arg"
+
+
+def _schema_type_label(prop_schema: dict[str, Any]) -> str:
+    """Return a human-readable type label for a property schema."""
+    schema_type = prop_schema.get("type", "string")
+    if isinstance(schema_type, list):
+        labels = [_JSON_SCHEMA_TYPE_LABELS.get(t, t) for t in schema_type]
+        return " | ".join(labels)
+
+    label = _JSON_SCHEMA_TYPE_LABELS.get(schema_type, schema_type)
+
+    # For arrays, include item type if simple
+    if schema_type == "array":
+        items = prop_schema.get("items", {})
+        item_type = items.get("type", "")
+        if isinstance(item_type, str) and item_type in _JSON_SCHEMA_TYPE_LABELS:
+            return f"array[{item_type}]"
+
+    return label
+
+
+def _tool_skill_section(tool: mcp_types.Tool, cli_filename: str) -> str:
+    """Generate a SKILL.md section for a single tool."""
+    schema = tool.input_schema
+    properties: dict[str, Any] = schema.get("properties", {})
+    required = set(schema.get("required", []))
+
+    # Build example invocation flags
+    flag_parts_list: list[str] = []
+    for p, p_schema in properties.items():
+        flag = _param_to_cli_flag(p)
+        schema_type = p_schema.get("type")
+        is_bool = schema_type == "boolean" or (
+            isinstance(schema_type, list) and "boolean" in schema_type
+        )
+        if is_bool:
+            flag_parts_list.append(flag)
+        else:
+            flag_parts_list.append(f"{flag} <value>")
+    flag_parts = " ".join(flag_parts_list)
+    invocation = f"uv run --with fastmcp python {cli_filename} call-tool {tool.name}"
+    if flag_parts:
+        invocation += f" {flag_parts}"
+
+    # Build parameter table rows
+    rows: list[str] = []
+    for prop_name, prop_schema in properties.items():
+        flag = f"`{_param_to_cli_flag(prop_name)}`"
+        type_label = _schema_type_label(prop_schema).replace("|", "\\|")
+        is_required = "yes" if prop_name in required else "no"
+        description = prop_schema.get("description", "")
+        _, needs_json = _schema_to_python_type(prop_schema)
+        if needs_json:
+            description = (
+                f"{description} (JSON string)" if description else "JSON string"
+            )
+        description = description.replace("\n", " ").replace("|", "\\|")
+        rows.append(f"| {flag} | {type_label} | {is_required} | {description} |")
+
+    param_table = ""
+    if rows:
+        header = "| Flag | Type | Required | Description |\n|------|------|----------|-------------|"
+        param_table = f"\n{header}\n" + "\n".join(rows) + "\n"
+
+    lines: list[str] = [f"### {tool.name}"]
+    if tool.description:
+        lines.extend(["", tool.description])
+    lines.extend(["", "```bash", invocation, "```"])
+    if param_table:
+        lines.extend(["", param_table.strip("\n")])
+    return "\n".join(lines)
+
+
+def generate_skill_content(
+    server_name: str,
+    cli_filename: str,
+    tools: list[mcp_types.Tool],
+) -> str:
+    """Generate a SKILL.md file for a generated CLI script."""
+    skill_name = (
+        server_name.replace(" ", "-").lower().replace("\\", "").replace('"', "")
+    )
+    safe_name = server_name.replace("\\", "").replace('"', "")
+    description = f"CLI for the {safe_name} MCP server. Call tools, list resources, and get prompts."
+
+    lines = [
+        "---",
+        f'name: "{skill_name}-cli"',
+        f'description: "{description}"',
+        "---",
+        "",
+        f"# {server_name} CLI",
+        "",
+    ]
+
+    if tools:
+        tool_bodies = "\n\n".join(
+            _tool_skill_section(tool, cli_filename) for tool in tools
+        )
+        lines.extend(["## Tool Commands", "", tool_bodies, ""])
+
+    lines.extend(
+        [
+            "## Utility Commands",
+            "",
+            "```bash",
+            f"uv run --with fastmcp python {cli_filename} list-tools",
+            f"uv run --with fastmcp python {cli_filename} list-resources",
+            f"uv run --with fastmcp python {cli_filename} read-resource <uri>",
+            f"uv run --with fastmcp python {cli_filename} list-prompts",
+            f"uv run --with fastmcp python {cli_filename} get-prompt <name> [key=value ...]",
+            "```",
+            "",
+        ]
+    )
+
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# CLI command
+# ---------------------------------------------------------------------------
+
+
+async def generate_cli_command(
+    server_spec: Annotated[
+        str,
+        cyclopts.Parameter(
+            help="Server URL, Python file, MCPConfig JSON, discovered name, or .js file",
+        ),
+    ],
+    output: Annotated[
+        str,
+        cyclopts.Parameter(
+            help="Output file path (default: cli.py)",
+        ),
+    ] = "cli.py",
+    *,
+    force: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["-f", "--force"],
+            help="Overwrite output file if it exists",
+        ),
+    ] = False,
+    timeout: Annotated[
+        float | None,
+        cyclopts.Parameter("--timeout", help="Connection timeout in seconds"),
+    ] = None,
+    auth: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--auth",
+            help="Auth method: 'oauth', a bearer token string, or 'none' to disable",
+        ),
+    ] = None,
+    no_skill: Annotated[
+        bool,
+        cyclopts.Parameter(
+            "--no-skill",
+            help="Skip generating a SKILL.md agent skill alongside the CLI",
+        ),
+    ] = False,
+) -> None:
+    """Generate a standalone CLI script from an MCP server.
+
+    Connects to the server, reads its tools/resources/prompts, and writes
+    a Python script that can invoke them directly. Also generates a SKILL.md
+    agent skill file unless --no-skill is passed.
+
+    Examples:
+        fastmcp generate-cli weather
+        fastmcp generate-cli weather my_cli.py
+        fastmcp generate-cli http://localhost:8000/mcp
+        fastmcp generate-cli server.py output.py -f
+        fastmcp generate-cli weather --no-skill
+    """
+    output_path = Path(output)
+    skill_path = output_path.parent / "SKILL.md"
+
+    # Check both files up front before doing any work
+    existing: list[Path] = []
+    if output_path.exists() and not force:
+        existing.append(output_path)
+    if not no_skill and skill_path.exists() and not force:
+        existing.append(skill_path)
+    if existing:
+        names = ", ".join(f"[cyan]{p}[/cyan]" for p in existing)
+        console.print(
+            f"[bold red]Error:[/bold red] {names} already exist(s). "
+            f"Use [cyan]-f[/cyan] to overwrite."
+        )
+        sys.exit(1)
+
+    # Resolve the server spec to a transport
+    resolved = resolve_server_spec(server_spec)
+    transport_code, extra_imports = serialize_transport(resolved)
+
+    # Derive a human-friendly server name from the spec
+    server_name = _derive_server_name(server_spec)
+
+    # Connect and discover capabilities
+    client = _build_client(resolved, timeout=timeout, auth=auth)
+
+    try:
+        async with client:
+            tools = await client.list_tools()
+            console.print(
+                f"[dim]Discovered {len(tools)} tool(s) from {server_spec}[/dim]"
+            )
+
+    except (RuntimeError, TimeoutError, MCPError, OSError) as exc:
+        console.print(f"[bold red]Error:[/bold red] Could not connect: {exc}")
+        sys.exit(1)
+
+    # Generate and write the script
+    script = generate_cli_script(
+        server_name=server_name,
+        server_spec=server_spec,
+        transport_code=transport_code,
+        extra_imports=extra_imports,
+        tools=tools,
+    )
+
+    output_path.write_text(script)
+    output_path.chmod(output_path.stat().st_mode | 0o111)  # make executable
+
+    console.print(
+        f"[green]✓[/green] Wrote [cyan]{output_path}[/cyan] "
+        f"with {len(tools)} tool command(s)"
+    )
+
+    if not no_skill:
+        skill_content = generate_skill_content(
+            server_name=server_name,
+            cli_filename=output_path.name,
+            tools=tools,
+        )
+        skill_path.write_text(skill_content)
+        console.print(f"[green]✓[/green] Wrote [cyan]{skill_path}[/cyan]")
+
+    console.print(f"[dim]Run: python {output_path} --help[/dim]")
+
+
+def _derive_server_name(server_spec: str) -> str:
+    """Derive a human-friendly name from a server spec."""
+    # URL — use hostname
+    if server_spec.startswith(("http://", "https://")):
+        parsed = urlparse(server_spec)
+        return parsed.hostname or "server"
+
+    # File path — use stem
+    if server_spec.endswith((".py", ".js", ".json")):
+        return Path(server_spec).stem
+
+    # Bare name or qualified name
+    if ":" in server_spec:
+        name = server_spec.split(":", 1)[1]
+        return name or server_spec.split(":", 1)[0]
+
+    return server_spec
diff --git a/fastmcp_slim/fastmcp/cli/install/__init__.py b/fastmcp_slim/fastmcp/cli/install/__init__.py
new file mode 100644
index 0000000..35b8d83
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/install/__init__.py
@@ -0,0 +1,26 @@
+"""Install subcommands for FastMCP CLI using Cyclopts."""
+
+import cyclopts
+
+from .claude_code import claude_code_command
+from .claude_desktop import claude_desktop_command
+from .cursor import cursor_command
+from .gemini_cli import gemini_cli_command
+from .goose import goose_command
+from .mcp_json import mcp_json_command
+from .stdio import stdio_command
+
+# Create a cyclopts app for install subcommands
+install_app = cyclopts.App(
+    name="install",
+    help="Install MCP servers in various clients and formats.",
+)
+
+# Register each command from its respective module
+install_app.command(claude_code_command, name="claude-code")
+install_app.command(claude_desktop_command, name="claude-desktop")
+install_app.command(cursor_command, name="cursor")
+install_app.command(gemini_cli_command, name="gemini-cli")
+install_app.command(goose_command, name="goose")
+install_app.command(mcp_json_command, name="mcp-json")
+install_app.command(stdio_command, name="stdio")
diff --git a/fastmcp_slim/fastmcp/cli/install/claude_code.py b/fastmcp_slim/fastmcp/cli/install/claude_code.py
new file mode 100644
index 0000000..5aa3775
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/install/claude_code.py
@@ -0,0 +1,242 @@
+"""Claude Code integration for FastMCP install using Cyclopts."""
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import cyclopts
+from rich import print
+
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_server_config.v1.environments.uv import UVEnvironment
+
+from .shared import process_common_args, validate_server_name
+
+logger = get_logger(__name__)
+
+
+def find_claude_command() -> str | None:
+    """Find the Claude Code CLI command.
+
+    Checks common installation locations since 'claude' is often a shell alias
+    that doesn't work with subprocess calls.
+    """
+    # First try shutil.which() in case it's a real executable in PATH
+    claude_in_path = shutil.which("claude")
+    if claude_in_path:
+        try:
+            result = subprocess.run(
+                [claude_in_path, "--version"],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            if "Claude Code" in result.stdout:
+                return claude_in_path
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            pass
+
+    # Check common installation locations (aliases don't work with subprocess)
+    potential_paths = [
+        # Default Claude Code installation location (after migration)
+        Path.home() / ".claude" / "local" / "claude",
+        # npm global installation on macOS/Linux (default)
+        Path("/usr/local/bin/claude"),
+        # npm global installation with custom prefix
+        Path.home() / ".npm-global" / "bin" / "claude",
+    ]
+
+    for path in potential_paths:
+        if path.exists():
+            try:
+                result = subprocess.run(
+                    [str(path), "--version"],
+                    check=True,
+                    capture_output=True,
+                    text=True,
+                )
+                if "Claude Code" in result.stdout:
+                    return str(path)
+            except (subprocess.CalledProcessError, FileNotFoundError):
+                continue
+
+    return None
+
+
+def check_claude_code_available() -> bool:
+    """Check if Claude Code CLI is available."""
+    return find_claude_command() is not None
+
+
+def install_claude_code(
+    file: Path,
+    server_object: str | None,
+    name: str,
+    *,
+    with_editable: list[Path] | None = None,
+    with_packages: list[str] | None = None,
+    env_vars: dict[str, str] | None = None,
+    python_version: str | None = None,
+    with_requirements: Path | None = None,
+    project: Path | None = None,
+) -> bool:
+    """Install FastMCP server in Claude Code.
+
+    Args:
+        file: Path to the server file
+        server_object: Optional server object name (for :object suffix)
+        name: Name for the server in Claude Code
+        with_editable: Optional list of directories to install in editable mode
+        with_packages: Optional list of additional packages to install
+        env_vars: Optional dictionary of environment variables
+        python_version: Optional Python version to use
+        with_requirements: Optional requirements file to install from
+        project: Optional project directory to run within
+
+    Returns:
+        True if installation was successful, False otherwise
+    """
+    # Check if Claude Code CLI is available
+    claude_cmd = find_claude_command()
+    if not claude_cmd:
+        print(
+            "[red]Claude Code CLI not found.[/red]\n"
+            "[blue]Please ensure Claude Code is installed. Try running 'claude --version' to verify.[/blue]"
+        )
+        return False
+
+    env_config = UVEnvironment(
+        python=python_version,
+        dependencies=(with_packages or []) + ["fastmcp"],
+        requirements=with_requirements,
+        project=project,
+        editable=with_editable,
+    )
+
+    # Build server spec from parsed components
+    if server_object:
+        server_spec = f"{file.resolve()}:{server_object}"
+    else:
+        server_spec = str(file.resolve())
+
+    # Build the full command
+    full_command = env_config.build_command(["fastmcp", "run", server_spec])
+
+    validate_server_name(name)
+
+    # Build claude mcp add command
+    cmd_parts = [claude_cmd, "mcp", "add", name]
+
+    # Add environment variables if specified
+    if env_vars:
+        for key, value in env_vars.items():
+            cmd_parts.extend(["-e", f"{key}={value}"])
+
+    # Add server name and command
+    cmd_parts.append("--")
+    cmd_parts.extend(full_command)
+
+    try:
+        # Run the claude mcp add command
+        subprocess.run(cmd_parts, check=True, capture_output=True, text=True)
+        return True
+    except subprocess.CalledProcessError as e:
+        print(
+            f"[red]Failed to install '[bold]{name}[/bold]' in Claude Code: {e.stderr.strip() if e.stderr else str(e)}[/red]"
+        )
+        return False
+    except Exception as e:
+        print(f"[red]Failed to install '[bold]{name}[/bold]' in Claude Code: {e}[/red]")
+        return False
+
+
+async def claude_code_command(
+    server_spec: str,
+    *,
+    server_name: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--name", "-n"],
+            help="Custom name for the server in Claude Code",
+        ),
+    ] = None,
+    with_editable: Annotated[
+        list[Path] | None,
+        cyclopts.Parameter(
+            "--with-editable",
+            help="Directory with pyproject.toml to install in editable mode (can be used multiple times)",
+        ),
+    ] = None,
+    with_packages: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            "--with", help="Additional packages to install (can be used multiple times)"
+        ),
+    ] = None,
+    env_vars: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            "--env",
+            help="Environment variables in KEY=VALUE format (can be used multiple times)",
+        ),
+    ] = None,
+    env_file: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--env-file",
+            help="Load environment variables from .env file",
+        ),
+    ] = None,
+    python: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--python",
+            help="Python version to use (e.g., 3.10, 3.11)",
+        ),
+    ] = None,
+    with_requirements: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--with-requirements",
+            help="Requirements file to install dependencies from",
+        ),
+    ] = None,
+    project: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--project",
+            help="Run the command within the given project directory",
+        ),
+    ] = None,
+) -> None:
+    """Install an MCP server in Claude Code.
+
+    Args:
+        server_spec: Python file to install, optionally with :object suffix
+    """
+    # Convert None to empty lists for list parameters
+    with_editable = with_editable or []
+    with_packages = with_packages or []
+    env_vars = env_vars or []
+    file, server_object, name, packages, env_dict = await process_common_args(
+        server_spec, server_name, with_packages, env_vars, env_file
+    )
+
+    success = install_claude_code(
+        file=file,
+        server_object=server_object,
+        name=name,
+        with_editable=with_editable,
+        with_packages=packages,
+        env_vars=env_dict,
+        python_version=python,
+        with_requirements=with_requirements,
+        project=project,
+    )
+
+    if success:
+        print(f"[green]Successfully installed '{name}' in Claude Code[/green]")
+    else:
+        sys.exit(1)
diff --git a/fastmcp_slim/fastmcp/cli/install/claude_desktop.py b/fastmcp_slim/fastmcp/cli/install/claude_desktop.py
new file mode 100644
index 0000000..780b97c
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/install/claude_desktop.py
@@ -0,0 +1,232 @@
+"""Claude Desktop integration for FastMCP install using Cyclopts."""
+
+import os
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import cyclopts
+from rich import print
+
+from fastmcp.mcp_config import StdioMCPServer, update_config_file
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_server_config.v1.environments.uv import UVEnvironment
+
+from .shared import process_common_args
+
+logger = get_logger(__name__)
+
+
+def get_claude_config_path(config_path: Path | None = None) -> Path | None:
+    """Get the Claude config directory based on platform.
+
+    Args:
+        config_path: Optional custom path to the Claude Desktop config directory
+    """
+
+    if config_path:
+        if not config_path.exists():
+            print(f"[red]The specified config path does not exist: {config_path}[/red]")
+            return None
+        return config_path
+
+    if sys.platform == "win32":
+        path = Path(Path.home(), "AppData", "Roaming", "Claude")
+    elif sys.platform == "darwin":
+        path = Path(Path.home(), "Library", "Application Support", "Claude")
+    elif sys.platform.startswith("linux"):
+        path = Path(
+            os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"), "Claude"
+        )
+    else:
+        return None
+
+    if path.exists():
+        return path
+    return None
+
+
+def install_claude_desktop(
+    file: Path,
+    server_object: str | None,
+    name: str,
+    *,
+    with_editable: list[Path] | None = None,
+    with_packages: list[str] | None = None,
+    env_vars: dict[str, str] | None = None,
+    python_version: str | None = None,
+    with_requirements: Path | None = None,
+    project: Path | None = None,
+    config_path: Path | None = None,
+) -> bool:
+    """Install FastMCP server in Claude Desktop.
+
+    Args:
+        file: Path to the server file
+        server_object: Optional server object name (for :object suffix)
+        name: Name for the server in Claude's config
+        with_editable: Optional list of directories to install in editable mode
+        with_packages: Optional list of additional packages to install
+        env_vars: Optional dictionary of environment variables
+        python_version: Optional Python version to use
+        with_requirements: Optional requirements file to install from
+        project: Optional project directory to run within
+        config_path: Optional custom path to Claude Desktop config directory
+
+    Returns:
+        True if installation was successful, False otherwise
+    """
+    config_dir = get_claude_config_path(config_path=config_path)
+    if not config_dir:
+        if not config_path:
+            print(
+                "[red]Claude Desktop config directory not found.[/red]\n"
+                "[blue]Please ensure Claude Desktop is installed and has been run at least once to initialize its config.[/blue]"
+            )
+        return False
+
+    config_file = config_dir / "claude_desktop_config.json"
+
+    env_config = UVEnvironment(
+        python=python_version,
+        dependencies=(with_packages or []) + ["fastmcp"],
+        requirements=with_requirements,
+        project=project,
+        editable=with_editable,
+    )
+    # Build server spec from parsed components
+    if server_object:
+        server_spec = f"{file.resolve()}:{server_object}"
+    else:
+        server_spec = str(file.resolve())
+
+    # Build the full command
+    full_command = env_config.build_command(["fastmcp", "run", server_spec])
+
+    # Create server configuration
+    server_config = StdioMCPServer(
+        command=full_command[0],
+        args=full_command[1:],
+        env=env_vars or {},
+    )
+
+    try:
+        # Handle environment variable merging manually since we need to preserve existing config
+        if config_file.exists():
+            import json
+
+            content = config_file.read_text().strip()
+            if content:
+                config = json.loads(content)
+                if "mcpServers" in config and name in config["mcpServers"]:
+                    existing_env = config["mcpServers"][name].get("env", {})
+                    if env_vars:
+                        # New vars take precedence over existing ones
+                        merged_env = {**existing_env, **env_vars}
+                    else:
+                        merged_env = existing_env
+                    server_config.env = merged_env
+
+        # Update configuration with correct function signature
+        update_config_file(config_file, name, server_config)
+        print(f"[green]Successfully installed '{name}' in Claude Desktop[/green]")
+        return True
+    except Exception as e:
+        print(f"[red]Failed to install server: {e}[/red]")
+        return False
+
+
+async def claude_desktop_command(
+    server_spec: str,
+    *,
+    server_name: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--name", "-n"],
+            help="Custom name for the server in Claude Desktop's config",
+        ),
+    ] = None,
+    with_editable: Annotated[
+        list[Path] | None,
+        cyclopts.Parameter(
+            "--with-editable",
+            help="Directory with pyproject.toml to install in editable mode (can be used multiple times)",
+        ),
+    ] = None,
+    with_packages: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            "--with", help="Additional packages to install (can be used multiple times)"
+        ),
+    ] = None,
+    env_vars: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            "--env",
+            help="Environment variables in KEY=VALUE format (can be used multiple times)",
+        ),
+    ] = None,
+    env_file: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--env-file",
+            help="Load environment variables from .env file",
+        ),
+    ] = None,
+    python: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--python",
+            help="Python version to use (e.g., 3.10, 3.11)",
+        ),
+    ] = None,
+    with_requirements: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--with-requirements",
+            help="Requirements file to install dependencies from",
+        ),
+    ] = None,
+    project: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--project",
+            help="Run the command within the given project directory",
+        ),
+    ] = None,
+    config_path: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--config-path",
+            help="Custom path to Claude Desktop config directory",
+        ),
+    ] = None,
+) -> None:
+    """Install an MCP server in Claude Desktop.
+
+    Args:
+        server_spec: Python file to install, optionally with :object suffix
+    """
+    # Convert None to empty lists for list parameters
+    with_editable = with_editable or []
+    with_packages = with_packages or []
+    env_vars = env_vars or []
+    file, server_object, name, with_packages, env_dict = await process_common_args(
+        server_spec, server_name, with_packages, env_vars, env_file
+    )
+
+    success = install_claude_desktop(
+        file=file,
+        server_object=server_object,
+        name=name,
+        with_editable=with_editable,
+        with_packages=with_packages,
+        env_vars=env_dict,
+        python_version=python,
+        with_requirements=with_requirements,
+        project=project,
+        config_path=config_path,
+    )
+
+    if not success:
+        sys.exit(1)
diff --git a/fastmcp_slim/fastmcp/cli/install/cursor.py b/fastmcp_slim/fastmcp/cli/install/cursor.py
new file mode 100644
index 0000000..560d17e
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/install/cursor.py
@@ -0,0 +1,321 @@
+"""Cursor integration for FastMCP install using Cyclopts."""
+
+import base64
+import sys
+from pathlib import Path
+from typing import Annotated
+from urllib.parse import quote
+
+import cyclopts
+from rich import print
+
+from fastmcp.mcp_config import StdioMCPServer, update_config_file
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_server_config.v1.environments.uv import UVEnvironment
+
+from .shared import open_deeplink as _shared_open_deeplink
+from .shared import process_common_args
+
+logger = get_logger(__name__)
+
+
+def generate_cursor_deeplink(
+    server_name: str,
+    server_config: StdioMCPServer,
+) -> str:
+    """Generate a Cursor deeplink for installing the MCP server.
+
+    Args:
+        server_name: Name of the server
+        server_config: Server configuration
+
+    Returns:
+        Deeplink URL that can be clicked to install the server
+    """
+    # Create the configuration structure expected by Cursor
+    # Base64 encode the configuration (URL-safe for query parameter)
+    config_json = server_config.model_dump_json(exclude_none=True)
+    config_b64 = base64.urlsafe_b64encode(config_json.encode()).decode()
+
+    # Generate the deeplink URL with properly encoded server name
+    encoded_name = quote(server_name, safe="")
+    deeplink = f"cursor://anysphere.cursor-deeplink/mcp/install?name={encoded_name}&config={config_b64}"
+
+    return deeplink
+
+
+def open_deeplink(deeplink: str) -> bool:
+    """Attempt to open a Cursor deeplink URL using the system's default handler.
+
+    Args:
+        deeplink: The deeplink URL to open
+
+    Returns:
+        True if the command succeeded, False otherwise
+    """
+    return _shared_open_deeplink(deeplink, expected_scheme="cursor")
+
+
+def install_cursor_workspace(
+    file: Path,
+    server_object: str | None,
+    name: str,
+    workspace_path: Path,
+    *,
+    with_editable: list[Path] | None = None,
+    with_packages: list[str] | None = None,
+    env_vars: dict[str, str] | None = None,
+    python_version: str | None = None,
+    with_requirements: Path | None = None,
+    project: Path | None = None,
+) -> bool:
+    """Install FastMCP server to workspace-specific Cursor configuration.
+
+    Args:
+        file: Path to the server file
+        server_object: Optional server object name (for :object suffix)
+        name: Name for the server in Cursor
+        workspace_path: Path to the workspace directory
+        with_editable: Optional list of directories to install in editable mode
+        with_packages: Optional list of additional packages to install
+        env_vars: Optional dictionary of environment variables
+        python_version: Optional Python version to use
+        with_requirements: Optional requirements file to install from
+        project: Optional project directory to run within
+
+    Returns:
+        True if installation was successful, False otherwise
+    """
+    # Ensure workspace path is absolute and exists
+    workspace_path = workspace_path.resolve()
+    if not workspace_path.exists():
+        print(f"[red]Workspace directory does not exist: {workspace_path}[/red]")
+        return False
+    if not workspace_path.is_dir():
+        print(f"[red]Workspace path is not a directory: {workspace_path}[/red]")
+        return False
+
+    # Create .cursor directory in workspace
+    cursor_dir = workspace_path / ".cursor"
+    cursor_dir.mkdir(exist_ok=True)
+
+    config_file = cursor_dir / "mcp.json"
+
+    env_config = UVEnvironment(
+        python=python_version,
+        dependencies=(with_packages or []) + ["fastmcp"],
+        requirements=with_requirements,
+        project=project,
+        editable=with_editable,
+    )
+    # Build server spec from parsed components
+    if server_object:
+        server_spec = f"{file.resolve()}:{server_object}"
+    else:
+        server_spec = str(file.resolve())
+
+    # Build the full command
+    full_command = env_config.build_command(["fastmcp", "run", server_spec])
+
+    # Create server configuration
+    server_config = StdioMCPServer(
+        command=full_command[0],
+        args=full_command[1:],
+        env=env_vars or {},
+    )
+
+    try:
+        # Create the config file if it doesn't exist
+        if not config_file.exists():
+            config_file.write_text('{"mcpServers": {}}')
+
+        # Update configuration with the new server
+        update_config_file(config_file, name, server_config)
+        print(
+            f"[green]Successfully installed '{name}' to workspace at {workspace_path}[/green]"
+        )
+        return True
+    except Exception as e:
+        print(f"[red]Failed to install server to workspace: {e}[/red]")
+        return False
+
+
+def install_cursor(
+    file: Path,
+    server_object: str | None,
+    name: str,
+    *,
+    with_editable: list[Path] | None = None,
+    with_packages: list[str] | None = None,
+    env_vars: dict[str, str] | None = None,
+    python_version: str | None = None,
+    with_requirements: Path | None = None,
+    project: Path | None = None,
+    workspace: Path | None = None,
+) -> bool:
+    """Install FastMCP server in Cursor.
+
+    Args:
+        file: Path to the server file
+        server_object: Optional server object name (for :object suffix)
+        name: Name for the server in Cursor
+        with_editable: Optional list of directories to install in editable mode
+        with_packages: Optional list of additional packages to install
+        env_vars: Optional dictionary of environment variables
+        python_version: Optional Python version to use
+        with_requirements: Optional requirements file to install from
+        project: Optional project directory to run within
+        workspace: Optional workspace directory for project-specific installation
+
+    Returns:
+        True if installation was successful, False otherwise
+    """
+
+    env_config = UVEnvironment(
+        python=python_version,
+        dependencies=(with_packages or []) + ["fastmcp"],
+        requirements=with_requirements,
+        project=project,
+        editable=with_editable,
+    )
+    # Build server spec from parsed components
+    if server_object:
+        server_spec = f"{file.resolve()}:{server_object}"
+    else:
+        server_spec = str(file.resolve())
+
+    # Build the full command
+    full_command = env_config.build_command(["fastmcp", "run", server_spec])
+
+    # If workspace is specified, install to workspace-specific config
+    if workspace:
+        return install_cursor_workspace(
+            file=file,
+            server_object=server_object,
+            name=name,
+            workspace_path=workspace,
+            with_editable=with_editable,
+            with_packages=with_packages,
+            env_vars=env_vars,
+            python_version=python_version,
+            with_requirements=with_requirements,
+            project=project,
+        )
+
+    # Create server configuration
+    server_config = StdioMCPServer(
+        command=full_command[0],
+        args=full_command[1:],
+        env=env_vars or {},
+    )
+
+    # Generate deeplink
+    deeplink = generate_cursor_deeplink(name, server_config)
+
+    print(f"[blue]Opening Cursor to install '{name}'[/blue]")
+
+    if open_deeplink(deeplink):
+        print("[green]Cursor should now open with the installation dialog[/green]")
+        return True
+    else:
+        print(
+            "[red]Could not open Cursor automatically.[/red]\n"
+            f"[blue]Please copy this link and open it in Cursor: {deeplink}[/blue]"
+        )
+        return False
+
+
+async def cursor_command(
+    server_spec: str,
+    *,
+    server_name: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--name", "-n"],
+            help="Custom name for the server in Cursor",
+        ),
+    ] = None,
+    with_editable: Annotated[
+        list[Path] | None,
+        cyclopts.Parameter(
+            "--with-editable",
+            help="Directory with pyproject.toml to install in editable mode (can be used multiple times)",
+        ),
+    ] = None,
+    with_packages: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            "--with", help="Additional packages to install (can be used multiple times)"
+        ),
+    ] = None,
+    env_vars: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            "--env",
+            help="Environment variables in KEY=VALUE format (can be used multiple times)",
+        ),
+    ] = None,
+    env_file: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--env-file",
+            help="Load environment variables from .env file",
+        ),
+    ] = None,
+    python: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--python",
+            help="Python version to use (e.g., 3.10, 3.11)",
+        ),
+    ] = None,
+    with_requirements: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--with-requirements",
+            help="Requirements file to install dependencies from",
+        ),
+    ] = None,
+    project: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--project",
+            help="Run the command within the given project directory",
+        ),
+    ] = None,
+    workspace: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--workspace",
+            help="Install to workspace directory (will create .cursor/ inside it) instead of using deeplink",
+        ),
+    ] = None,
+) -> None:
+    """Install an MCP server in Cursor.
+
+    Args:
+        server_spec: Python file to install, optionally with :object suffix
+    """
+    # Convert None to empty lists for list parameters
+    with_editable = with_editable or []
+    with_packages = with_packages or []
+    env_vars = env_vars or []
+    file, server_object, name, with_packages, env_dict = await process_common_args(
+        server_spec, server_name, with_packages, env_vars, env_file
+    )
+
+    success = install_cursor(
+        file=file,
+        server_object=server_object,
+        name=name,
+        with_editable=with_editable,
+        with_packages=with_packages,
+        env_vars=env_dict,
+        python_version=python,
+        with_requirements=with_requirements,
+        project=project,
+        workspace=workspace,
+    )
+
+    if not success:
+        sys.exit(1)
diff --git a/fastmcp_slim/fastmcp/cli/install/gemini_cli.py b/fastmcp_slim/fastmcp/cli/install/gemini_cli.py
new file mode 100644
index 0000000..29cc39e
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/install/gemini_cli.py
@@ -0,0 +1,239 @@
+"""Gemini CLI integration for FastMCP install using Cyclopts."""
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import cyclopts
+from rich import print
+
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_server_config.v1.environments.uv import UVEnvironment
+
+from .shared import process_common_args, validate_server_name
+
+logger = get_logger(__name__)
+
+
+def find_gemini_command() -> str | None:
+    """Find the Gemini CLI command."""
+    # First try shutil.which() in case it's a real executable in PATH
+    gemini_in_path = shutil.which("gemini")
+    if gemini_in_path:
+        try:
+            # If 'gemini --version' fails, it's not the correct path
+            subprocess.run(
+                [gemini_in_path, "--version"],
+                check=True,
+                capture_output=True,
+            )
+            return gemini_in_path
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            pass
+
+    # Check common installation locations (aliases don't work with subprocess)
+    potential_paths = [
+        # Default Gemini CLI installation location (after migration)
+        Path.home() / ".gemini" / "local" / "gemini",
+        # npm global installation on macOS/Linux (default)
+        Path("/usr/local/bin/gemini"),
+        # npm global installation with custom prefix
+        Path.home() / ".npm-global" / "bin" / "gemini",
+        # Homebrew installation on macOS
+        Path("/opt/homebrew/bin/gemini"),
+    ]
+
+    for path in potential_paths:
+        if path.exists():
+            # If 'gemini --version' fails, it's not the correct path
+            try:
+                subprocess.run(
+                    [str(path), "--version"],
+                    check=True,
+                    capture_output=True,
+                )
+                return str(path)
+            except (subprocess.CalledProcessError, FileNotFoundError):
+                continue
+
+    return None
+
+
+def check_gemini_cli_available() -> bool:
+    """Check if Gemini CLI is available."""
+    return find_gemini_command() is not None
+
+
+def install_gemini_cli(
+    file: Path,
+    server_object: str | None,
+    name: str,
+    *,
+    with_editable: list[Path] | None = None,
+    with_packages: list[str] | None = None,
+    env_vars: dict[str, str] | None = None,
+    python_version: str | None = None,
+    with_requirements: Path | None = None,
+    project: Path | None = None,
+) -> bool:
+    """Install FastMCP server in Gemini CLI.
+
+    Args:
+        file: Path to the server file
+        server_object: Optional server object name (for :object suffix)
+        name: Name for the server in Gemini CLI
+        with_editable: Optional list of directories to install in editable mode
+        with_packages: Optional list of additional packages to install
+        env_vars: Optional dictionary of environment variables
+        python_version: Optional Python version to use
+        with_requirements: Optional requirements file to install from
+        project: Optional project directory to run within
+
+    Returns:
+        True if installation was successful, False otherwise
+    """
+    # Check if Gemini CLI is available
+    gemini_cmd = find_gemini_command()
+    if not gemini_cmd:
+        print(
+            "[red]Gemini CLI not found.[/red]\n"
+            "[blue]Please ensure Gemini CLI is installed. Try running 'gemini --version' to verify.[/blue]\n"
+            "[blue]You can install it using 'npm install -g @google/gemini-cli'.[/blue]\n"
+        )
+        return False
+
+    env_config = UVEnvironment(
+        python=python_version,
+        dependencies=(with_packages or []) + ["fastmcp"],
+        requirements=with_requirements,
+        project=project,
+        editable=with_editable,
+    )
+
+    # Build server spec from parsed components
+    if server_object:
+        server_spec = f"{file.resolve()}:{server_object}"
+    else:
+        server_spec = str(file.resolve())
+
+    # Build the full command
+    full_command = env_config.build_command(["fastmcp", "run", server_spec])
+
+    # Build gemini mcp add command
+    cmd_parts = [gemini_cmd, "mcp", "add"]
+
+    # Add environment variables if specified (before the name and command)
+    if env_vars:
+        for key, value in env_vars.items():
+            cmd_parts.extend(["-e", f"{key}={value}"])
+
+    validate_server_name(name)
+
+    # Add server name and command
+    cmd_parts.extend([name, full_command[0], "--"])
+    cmd_parts.extend(full_command[1:])
+
+    try:
+        # Run the gemini mcp add command
+        subprocess.run(cmd_parts, check=True, capture_output=True, text=True)
+        return True
+    except subprocess.CalledProcessError as e:
+        print(
+            f"[red]Failed to install '[bold]{name}[/bold]' in Gemini CLI: {e.stderr.strip() if e.stderr else str(e)}[/red]"
+        )
+        return False
+    except Exception as e:
+        print(f"[red]Failed to install '[bold]{name}[/bold]' in Gemini CLI: {e}[/red]")
+        return False
+
+
+async def gemini_cli_command(
+    server_spec: str,
+    *,
+    server_name: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--name", "-n"],
+            help="Custom name for the server in Gemini CLI",
+        ),
+    ] = None,
+    with_editable: Annotated[
+        list[Path] | None,
+        cyclopts.Parameter(
+            "--with-editable",
+            help="Directory with pyproject.toml to install in editable mode (can be used multiple times)",
+        ),
+    ] = None,
+    with_packages: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            "--with", help="Additional packages to install (can be used multiple times)"
+        ),
+    ] = None,
+    env_vars: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            "--env",
+            help="Environment variables in KEY=VALUE format (can be used multiple times)",
+        ),
+    ] = None,
+    env_file: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--env-file",
+            help="Load environment variables from .env file",
+        ),
+    ] = None,
+    python: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--python",
+            help="Python version to use (e.g., 3.10, 3.11)",
+        ),
+    ] = None,
+    with_requirements: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--with-requirements",
+            help="Requirements file to install dependencies from",
+        ),
+    ] = None,
+    project: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--project",
+            help="Run the command within the given project directory",
+        ),
+    ] = None,
+) -> None:
+    """Install an MCP server in Gemini CLI.
+
+    Args:
+        server_spec: Python file to install, optionally with :object suffix
+    """
+    # Convert None to empty lists for list parameters
+    with_editable = with_editable or []
+    with_packages = with_packages or []
+    env_vars = env_vars or []
+    file, server_object, name, packages, env_dict = await process_common_args(
+        server_spec, server_name, with_packages, env_vars, env_file
+    )
+
+    success = install_gemini_cli(
+        file=file,
+        server_object=server_object,
+        name=name,
+        with_editable=with_editable,
+        with_packages=packages,
+        env_vars=env_dict,
+        python_version=python,
+        with_requirements=with_requirements,
+        project=project,
+    )
+
+    if success:
+        print(f"[green]Successfully installed '{name}' in Gemini CLI")
+    else:
+        sys.exit(1)
diff --git a/fastmcp_slim/fastmcp/cli/install/goose.py b/fastmcp_slim/fastmcp/cli/install/goose.py
new file mode 100644
index 0000000..8d57128
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/install/goose.py
@@ -0,0 +1,208 @@
+"""Goose integration for FastMCP install using Cyclopts."""
+
+import re
+import sys
+from pathlib import Path
+from typing import Annotated
+from urllib.parse import quote
+
+import cyclopts
+from rich import print
+
+from fastmcp.utilities.logging import get_logger
+
+from .shared import open_deeplink, process_common_args
+
+logger = get_logger(__name__)
+
+
+def _slugify(name: str) -> str:
+    """Convert a display name to a URL-safe identifier.
+
+    Lowercases, replaces non-alphanumeric runs with hyphens,
+    and strips leading/trailing hyphens.
+    """
+    slug = re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+    return slug or "fastmcp-server"
+
+
+def generate_goose_deeplink(
+    name: str,
+    command: str,
+    args: list[str],
+    *,
+    description: str = "MCP server installed via FastMCP",
+) -> str:
+    """Generate a Goose deeplink for installing an MCP extension.
+
+    Args:
+        name: Human-readable display name for the extension.
+        command: The executable command (e.g. "uv").
+        args: Arguments to the command.
+        description: Short description shown in Goose.
+
+    Returns:
+        A goose://extension?... deeplink URL.
+    """
+    extension_id = _slugify(name)
+
+    params: list[str] = [f"cmd={quote(command, safe='')}"]
+    params.extend(f"arg={quote(arg, safe='')}" for arg in args)
+    params.append(f"id={quote(extension_id, safe='')}")
+    params.append(f"name={quote(name, safe='')}")
+    params.append(f"description={quote(description, safe='')}")
+
+    return f"goose://extension?{'&'.join(params)}"
+
+
+def _build_uvx_command(
+    server_spec: str,
+    *,
+    python_version: str | None = None,
+    with_packages: list[str] | None = None,
+) -> list[str]:
+    """Build a uvx command for running a FastMCP server.
+
+    Goose requires uvx (not uv run) as the command. The uvx format is:
+        uvx [--with pkg] [--python X] fastmcp run <spec>
+
+    uvx automatically infers that the `fastmcp` command comes from the
+    `fastmcp` package, so --from is not needed.
+    """
+    args: list[str] = ["uvx"]
+
+    if python_version:
+        args.extend(["--python", python_version])
+
+    for pkg in sorted(set(with_packages or [])):
+        if pkg != "fastmcp":
+            args.extend(["--with", pkg])
+
+    args.extend(["fastmcp", "run", server_spec])
+    return args
+
+
+def install_goose(
+    file: Path,
+    server_object: str | None,
+    name: str,
+    *,
+    with_packages: list[str] | None = None,
+    python_version: str | None = None,
+) -> bool:
+    """Install FastMCP server in Goose via deeplink.
+
+    Args:
+        file: Path to the server file.
+        server_object: Optional server object name (for :object suffix).
+        name: Name for the extension in Goose.
+        with_packages: Optional list of additional packages to install.
+        python_version: Optional Python version to use.
+
+    Returns:
+        True if installation was successful, False otherwise.
+    """
+    if server_object:
+        server_spec = f"{file.resolve()}:{server_object}"
+    else:
+        server_spec = str(file.resolve())
+
+    full_command = _build_uvx_command(
+        server_spec,
+        python_version=python_version,
+        with_packages=with_packages,
+    )
+
+    deeplink = generate_goose_deeplink(
+        name=name,
+        command=full_command[0],
+        args=full_command[1:],
+    )
+
+    print(f"[blue]Opening Goose to install '{name}'[/blue]")
+
+    if open_deeplink(deeplink, expected_scheme="goose"):
+        print("[green]Goose should now open with the installation dialog[/green]")
+        return True
+    else:
+        print(
+            "[red]Could not open Goose automatically.[/red]\n"
+            f"[blue]Please copy this link and open it in Goose: {deeplink}[/blue]"
+        )
+        return False
+
+
+async def goose_command(
+    server_spec: str,
+    *,
+    server_name: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--name", "-n"],
+            help="Custom name for the extension in Goose",
+        ),
+    ] = None,
+    with_packages: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            "--with",
+            help="Additional packages to install (can be used multiple times)",
+        ),
+    ] = None,
+    env_vars: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            "--env",
+            help="Environment variables in KEY=VALUE format (can be used multiple times)",
+        ),
+    ] = None,
+    env_file: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--env-file",
+            help="Load environment variables from .env file",
+        ),
+    ] = None,
+    python: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--python",
+            help="Python version to use (e.g., 3.10, 3.11)",
+        ),
+    ] = None,
+) -> None:
+    """Install an MCP server in Goose.
+
+    Uses uvx to run the server. Environment variables are not included
+    in the deeplink; use `fastmcp install mcp-json` to generate a full
+    config for manual installation.
+
+    Args:
+        server_spec: Python file to install, optionally with :object suffix
+    """
+    with_packages = with_packages or []
+    env_vars = env_vars or []
+
+    if env_vars or env_file:
+        print(
+            "[red]Goose deeplinks cannot include environment variables.[/red]\n"
+            "[yellow]Use `fastmcp install mcp-json` to generate a config, then add it "
+            "to your Goose config file with env vars: "
+            "https://block.github.io/goose/docs/getting-started/using-extensions/#config-entry[/yellow]"
+        )
+        sys.exit(1)
+
+    file, server_object, name, with_packages, _env_dict = await process_common_args(
+        server_spec, server_name, with_packages, env_vars, env_file
+    )
+
+    success = install_goose(
+        file=file,
+        server_object=server_object,
+        name=name,
+        with_packages=with_packages,
+        python_version=python,
+    )
+
+    if not success:
+        sys.exit(1)
diff --git a/fastmcp_slim/fastmcp/cli/install/mcp_json.py b/fastmcp_slim/fastmcp/cli/install/mcp_json.py
new file mode 100644
index 0000000..ed2ac73
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/install/mcp_json.py
@@ -0,0 +1,191 @@
+"""MCP configuration JSON generation for FastMCP install using Cyclopts."""
+
+import json
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import cyclopts
+import pyperclip
+from rich import print
+
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_server_config.v1.environments.uv import UVEnvironment
+
+from .shared import process_common_args
+
+logger = get_logger(__name__)
+
+
+def install_mcp_json(
+    file: Path,
+    server_object: str | None,
+    name: str,
+    *,
+    with_editable: list[Path] | None = None,
+    with_packages: list[str] | None = None,
+    env_vars: dict[str, str] | None = None,
+    copy: bool = False,
+    python_version: str | None = None,
+    with_requirements: Path | None = None,
+    project: Path | None = None,
+) -> bool:
+    """Generate MCP configuration JSON for manual installation.
+
+    Args:
+        file: Path to the server file
+        server_object: Optional server object name (for :object suffix)
+        name: Name for the server in MCP config
+        with_editable: Optional list of directories to install in editable mode
+        with_packages: Optional list of additional packages to install
+        env_vars: Optional dictionary of environment variables
+        copy: If True, copy to clipboard instead of printing to stdout
+        python_version: Optional Python version to use
+        with_requirements: Optional requirements file to install from
+        project: Optional project directory to run within
+
+    Returns:
+        True if generation was successful, False otherwise
+    """
+    try:
+        env_config = UVEnvironment(
+            python=python_version,
+            dependencies=(with_packages or []) + ["fastmcp"],
+            requirements=with_requirements,
+            project=project,
+            editable=with_editable,
+        )
+        # Build server spec from parsed components
+        if server_object:
+            server_spec = f"{file.resolve()}:{server_object}"
+        else:
+            server_spec = str(file.resolve())
+
+        # Build the full command
+        full_command = env_config.build_command(["fastmcp", "run", server_spec])
+
+        # Build MCP server configuration
+        server_config: dict[str, str | list[str] | dict[str, str]] = {
+            "command": full_command[0],
+            "args": full_command[1:],
+        }
+
+        # Add environment variables if provided
+        if env_vars:
+            server_config["env"] = env_vars
+
+        # Wrap with server name as root key
+        config = {name: server_config}
+
+        # Convert to JSON
+        json_output = json.dumps(config, indent=2)
+
+        # Handle output
+        if copy:
+            pyperclip.copy(json_output)
+            print(f"[green]MCP configuration for '{name}' copied to clipboard[/green]")
+        else:
+            # Print to stdout (for piping)
+            print(json_output)
+
+        return True
+
+    except Exception as e:
+        print(f"[red]Failed to generate MCP configuration: {e}[/red]")
+        return False
+
+
+async def mcp_json_command(
+    server_spec: str,
+    *,
+    server_name: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--name", "-n"],
+            help="Custom name for the server in MCP config",
+        ),
+    ] = None,
+    with_editable: Annotated[
+        list[Path] | None,
+        cyclopts.Parameter(
+            "--with-editable",
+            help="Directory with pyproject.toml to install in editable mode (can be used multiple times)",
+        ),
+    ] = None,
+    with_packages: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            "--with", help="Additional packages to install (can be used multiple times)"
+        ),
+    ] = None,
+    env_vars: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            "--env",
+            help="Environment variables in KEY=VALUE format (can be used multiple times)",
+        ),
+    ] = None,
+    env_file: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--env-file",
+            help="Load environment variables from .env file",
+        ),
+    ] = None,
+    copy: Annotated[
+        bool,
+        cyclopts.Parameter(
+            "--copy",
+            help="Copy configuration to clipboard instead of printing to stdout",
+        ),
+    ] = False,
+    python: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--python",
+            help="Python version to use (e.g., 3.10, 3.11)",
+        ),
+    ] = None,
+    with_requirements: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--with-requirements",
+            help="Requirements file to install dependencies from",
+        ),
+    ] = None,
+    project: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--project",
+            help="Run the command within the given project directory",
+        ),
+    ] = None,
+) -> None:
+    """Generate MCP configuration JSON for manual installation.
+
+    Args:
+        server_spec: Python file to install, optionally with :object suffix
+    """
+    # Convert None to empty lists for list parameters
+    with_editable = with_editable or []
+    with_packages = with_packages or []
+    env_vars = env_vars or []
+    file, server_object, name, packages, env_dict = await process_common_args(
+        server_spec, server_name, with_packages, env_vars, env_file
+    )
+
+    success = install_mcp_json(
+        file=file,
+        server_object=server_object,
+        name=name,
+        with_editable=with_editable,
+        with_packages=packages,
+        env_vars=env_dict,
+        copy=copy,
+        python_version=python,
+        with_requirements=with_requirements,
+        project=project,
+    )
+
+    if not success:
+        sys.exit(1)
diff --git a/fastmcp_slim/fastmcp/cli/install/shared.py b/fastmcp_slim/fastmcp/cli/install/shared.py
new file mode 100644
index 0000000..84026ed
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/install/shared.py
@@ -0,0 +1,200 @@
+"""Shared utilities for install commands."""
+
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from urllib.parse import urlparse
+
+from dotenv import dotenv_values
+from pydantic import ValidationError
+from rich import print
+
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_server_config import MCPServerConfig
+from fastmcp.utilities.mcp_server_config.v1.sources.filesystem import FileSystemSource
+
+logger = get_logger(__name__)
+
+# Server names are passed as subprocess arguments to CLI tools like `claude`
+# and `gemini`. On Windows these may resolve to .cmd/.bat wrappers that run
+# through cmd.exe, where shell metacharacters (& | ; etc.) in arguments can
+# cause command injection. Restrict names to safe characters.
+_SAFE_NAME_RE = re.compile(r"^[\w\-. ]+$")
+
+
+def validate_server_name(name: str) -> str:
+    """Validate that a server name is safe for use as a subprocess argument.
+
+    Raises SystemExit if the name contains shell metacharacters.
+    """
+    if not _SAFE_NAME_RE.match(name):
+        print(
+            f"[red]Invalid server name '[bold]{name}[/bold]': "
+            "names may only contain letters, numbers, hyphens, underscores, dots, and spaces.[/red]"
+        )
+        sys.exit(1)
+    return name
+
+
+def parse_env_var(env_var: str) -> tuple[str, str]:
+    """Parse environment variable string in format KEY=VALUE."""
+    if "=" not in env_var:
+        print(
+            f"[red]Invalid environment variable format: '[bold]{env_var}[/bold]'. Must be KEY=VALUE[/red]"
+        )
+        sys.exit(1)
+    key, value = env_var.split("=", 1)
+    if not key.strip():
+        print(
+            f"[red]Invalid environment variable format: '[bold]{env_var}[/bold]'. KEY cannot be empty[/red]"
+        )
+        sys.exit(1)
+    return key.strip(), value.strip()
+
+
+async def process_common_args(
+    server_spec: str,
+    server_name: str | None,
+    with_packages: list[str] | None,
+    env_vars: list[str] | None,
+    env_file: Path | None,
+) -> tuple[Path, str | None, str, list[str], dict[str, str] | None]:
+    """Process common arguments shared by all install commands.
+
+    Handles both fastmcp.json config files and traditional file.py:object syntax.
+    """
+    # Convert None to empty lists for list parameters
+    with_packages = with_packages or []
+    env_vars = env_vars or []
+    # Create MCPServerConfig from server_spec
+    config = None
+    config_path: Path | None = None
+    if server_spec.endswith(".json"):
+        config_path = Path(server_spec).resolve()
+        if not config_path.exists():
+            print(f"[red]Configuration file not found: {config_path}[/red]")
+            sys.exit(1)
+
+        try:
+            with open(config_path) as f:
+                data = json.load(f)
+
+            # Check if it's an MCPConfig (has mcpServers key)
+            if "mcpServers" in data:
+                # MCPConfig files aren't supported for install
+                print("[red]MCPConfig files are not supported for installation[/red]")
+                sys.exit(1)
+            else:
+                # It's a MCPServerConfig
+                config = MCPServerConfig.from_file(config_path)
+
+                # Merge packages from config if not overridden
+                if config.environment.dependencies:
+                    # Merge with CLI packages (CLI takes precedence)
+                    config_packages = list(config.environment.dependencies)
+                    with_packages = list(set(with_packages + config_packages))
+        except (json.JSONDecodeError, ValidationError) as e:
+            print(f"[red]Invalid configuration file: {e}[/red]")
+            sys.exit(1)
+    else:
+        # Create config from file path
+        source = FileSystemSource(path=server_spec)
+        config = MCPServerConfig(source=source)
+
+    # Extract file and server_object from the source
+    # The FileSystemSource handles parsing path:object syntax
+    source_path = Path(config.source.path).expanduser()
+    # If loaded from a JSON config, resolve relative paths against the config's directory
+    if not source_path.is_absolute() and config_path is not None:
+        file = (config_path.parent / source_path).resolve()
+    else:
+        file = source_path.resolve()
+    # Update the source path so load_server() resolves correctly
+    config.source.path = str(file)
+    server_object = (
+        config.source.entrypoint if hasattr(config.source, "entrypoint") else None
+    )
+
+    logger.debug(
+        "Installing server",
+        extra={
+            "file": str(file),
+            "server_name": server_name,
+            "server_object": server_object,
+            "with_packages": with_packages,
+        },
+    )
+
+    # Verify the resolved file actually exists
+    if not file.is_file():
+        print(f"[red]Server file not found: {file}[/red]")
+        sys.exit(1)
+
+    # Try to import server to get its name and dependencies.
+    # load_server() resolves paths against cwd, which may differ from our
+    # config-relative resolution, so we catch SystemExit from its file check.
+    name = server_name
+    server = None
+    if not name:
+        try:
+            server = await config.source.load_server()
+            name = server.name
+        except (ImportError, ModuleNotFoundError, SystemExit) as e:
+            logger.debug(
+                "Could not import server (likely missing dependencies), using file name",
+                extra={"error": str(e)},
+            )
+            name = file.stem
+
+    # Process environment variables if provided
+    env_dict: dict[str, str] | None = None
+    if env_file or env_vars:
+        env_dict = {}
+        # Load from .env file if specified
+        if env_file:
+            try:
+                env_dict |= {
+                    k: v for k, v in dotenv_values(env_file).items() if v is not None
+                }
+            except Exception as e:
+                print(f"[red]Failed to load .env file: {e}[/red]")
+                sys.exit(1)
+
+        # Add command line environment variables
+        for env_var in env_vars:
+            key, value = parse_env_var(env_var)
+            env_dict[key] = value
+
+    return file, server_object, name, with_packages, env_dict
+
+
+def open_deeplink(url: str, *, expected_scheme: str) -> bool:
+    """Attempt to open a deeplink URL using the system's default handler.
+
+    Args:
+        url: The deeplink URL to open.
+        expected_scheme: The URL scheme to validate (e.g. "cursor", "goose").
+
+    Returns:
+        True if the command succeeded, False otherwise.
+    """
+    parsed = urlparse(url)
+    if parsed.scheme != expected_scheme:
+        logger.warning(
+            f"Invalid deeplink scheme: {parsed.scheme}, expected {expected_scheme}"
+        )
+        return False
+
+    try:
+        if sys.platform == "darwin":
+            subprocess.run(["open", url], check=True, capture_output=True)
+        elif sys.platform == "win32":
+            os.startfile(url)
+        else:
+            subprocess.run(["xdg-open", url], check=True, capture_output=True)
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError, OSError):
+        return False
diff --git a/fastmcp_slim/fastmcp/cli/install/stdio.py b/fastmcp_slim/fastmcp/cli/install/stdio.py
new file mode 100644
index 0000000..31c89c1
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/install/stdio.py
@@ -0,0 +1,156 @@
+"""Stdio command generation for FastMCP install using Cyclopts."""
+
+import builtins
+import shlex
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import cyclopts
+import pyperclip
+from rich import print as rich_print
+
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_server_config.v1.environments.uv import UVEnvironment
+
+from .shared import process_common_args
+
+logger = get_logger(__name__)
+
+
+def install_stdio(
+    file: Path,
+    server_object: str | None,
+    *,
+    with_editable: list[Path] | None = None,
+    with_packages: list[str] | None = None,
+    copy: bool = False,
+    python_version: str | None = None,
+    with_requirements: Path | None = None,
+    project: Path | None = None,
+) -> bool:
+    """Generate the stdio command for running a FastMCP server.
+
+    Args:
+        file: Path to the server file
+        server_object: Optional server object name (for :object suffix)
+        with_editable: Optional list of directories to install in editable mode
+        with_packages: Optional list of additional packages to install
+        copy: If True, copy to clipboard instead of printing to stdout
+        python_version: Optional Python version to use
+        with_requirements: Optional requirements file to install from
+        project: Optional project directory to run within
+
+    Returns:
+        True if generation was successful, False otherwise
+    """
+    try:
+        env_config = UVEnvironment(
+            python=python_version,
+            dependencies=(with_packages or []) + ["fastmcp"],
+            requirements=with_requirements,
+            project=project,
+            editable=with_editable,
+        )
+        # Build server spec from parsed components
+        if server_object:
+            server_spec = f"{file.resolve()}:{server_object}"
+        else:
+            server_spec = str(file.resolve())
+
+        # Build the full command
+        full_command = env_config.build_command(["fastmcp", "run", server_spec])
+        command_str = shlex.join(full_command)
+
+        if copy:
+            pyperclip.copy(command_str)
+            rich_print("[green]✓ Command copied to clipboard[/green]")
+        else:
+            builtins.print(command_str)
+
+        return True
+
+    except (OSError, ValueError, pyperclip.PyperclipException) as e:
+        rich_print(f"[red]Failed to generate stdio command: {e}[/red]")
+        return False
+
+
+async def stdio_command(
+    server_spec: str,
+    *,
+    server_name: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--name", "-n"],
+            help="Custom name for the server (used for dependency resolution)",
+        ),
+    ] = None,
+    with_editable: Annotated[
+        list[Path] | None,
+        cyclopts.Parameter(
+            "--with-editable",
+            help="Directory with pyproject.toml to install in editable mode (can be used multiple times)",
+        ),
+    ] = None,
+    with_packages: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            "--with", help="Additional packages to install (can be used multiple times)"
+        ),
+    ] = None,
+    copy: Annotated[
+        bool,
+        cyclopts.Parameter(
+            "--copy",
+            help="Copy command to clipboard instead of printing to stdout",
+        ),
+    ] = False,
+    python: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            "--python",
+            help="Python version to use (e.g., 3.10, 3.11)",
+        ),
+    ] = None,
+    with_requirements: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--with-requirements",
+            help="Requirements file to install dependencies from",
+        ),
+    ] = None,
+    project: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--project",
+            help="Run the command within the given project directory",
+        ),
+    ] = None,
+) -> None:
+    """Generate the stdio command for running a FastMCP server.
+
+    Outputs the shell command that an MCP host would use to start this server
+    over stdio transport. Useful for manual configuration or debugging.
+
+    Args:
+        server_spec: Python file to run, optionally with :object suffix
+    """
+    with_editable = with_editable or []
+    with_packages = with_packages or []
+    file, server_object, _name, packages, _env_dict = await process_common_args(
+        server_spec, server_name, with_packages, [], None
+    )
+
+    success = install_stdio(
+        file=file,
+        server_object=server_object,
+        with_editable=with_editable,
+        with_packages=packages,
+        copy=copy,
+        python_version=python,
+        with_requirements=with_requirements,
+        project=project,
+    )
+
+    if not success:
+        sys.exit(1)
diff --git a/fastmcp_slim/fastmcp/cli/run.py b/fastmcp_slim/fastmcp/cli/run.py
new file mode 100644
index 0000000..476c026
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/run.py
@@ -0,0 +1,492 @@
+"""FastMCP run command implementation with enhanced type hints."""
+
+import asyncio
+import contextlib
+import json
+import os
+import re
+import signal
+import subprocess
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, Literal
+
+from mcp.server.mcpserver import MCPServer as SDKServer
+from watchfiles import Change, awatch
+
+import fastmcp
+from fastmcp.server.server import FastMCP, create_proxy
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_server_config import (
+    MCPServerConfig,
+)
+from fastmcp.utilities.mcp_server_config.v1.sources.filesystem import FileSystemSource
+
+logger = get_logger("cli.run")
+
+# Type aliases for better type safety
+TransportType = Literal["stdio", "http", "sse", "streamable-http"]
+LogLevelType = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+# File extensions to watch for reload
+WATCHED_EXTENSIONS: set[str] = {
+    # Python
+    ".py",
+    # JavaScript/TypeScript
+    ".js",
+    ".ts",
+    ".jsx",
+    ".tsx",
+    # Markup/Content
+    ".html",
+    ".md",
+    ".mdx",
+    ".txt",
+    ".xml",
+    # Styles
+    ".css",
+    ".scss",
+    ".sass",
+    ".less",
+    # Data/Config
+    ".json",
+    ".yaml",
+    ".yml",
+    ".toml",
+    # Framework-specific
+    ".vue",
+    ".svelte",
+    # GraphQL
+    ".graphql",
+    ".gql",
+    # Images
+    ".svg",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".ico",
+    ".webp",
+    # Media
+    ".mp3",
+    ".mp4",
+    ".wav",
+    ".webm",
+    # Fonts
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".eot",
+}
+
+
+def is_url(path: str) -> bool:
+    """Check if a string is a URL."""
+    url_pattern = re.compile(r"^https?://")
+    return bool(url_pattern.match(path))
+
+
+def create_client_server(url: str) -> Any:
+    """Create a FastMCP server from a client URL.
+
+    Args:
+        url: The URL to connect to
+
+    Returns:
+        A FastMCP server instance
+    """
+    try:
+        import fastmcp
+
+        client = fastmcp.Client(url)
+        server = create_proxy(client)
+        return server
+    except Exception as e:
+        logger.error(f"Failed to create client for URL {url}: {e}")
+        sys.exit(1)
+
+
+def create_mcp_config_server(mcp_config_path: Path) -> FastMCP[None]:
+    """Create a FastMCP server from a MCPConfig."""
+    with mcp_config_path.open() as src:
+        mcp_config = json.load(src)
+
+    server = create_proxy(mcp_config)
+    return server
+
+
+def load_mcp_server_config(config_path: Path) -> MCPServerConfig:
+    """Load a FastMCP configuration from a fastmcp.json file.
+
+    Args:
+        config_path: Path to fastmcp.json file
+
+    Returns:
+        MCPServerConfig object
+    """
+    config = MCPServerConfig.from_file(config_path)
+
+    # Apply runtime settings from deployment config
+    config.deployment.apply_runtime_settings(config_path)
+
+    return config
+
+
+async def run_command(
+    server_spec: str,
+    transport: TransportType | None = None,
+    host: str | None = None,
+    port: int | None = None,
+    path: str | None = None,
+    log_level: LogLevelType | None = None,
+    server_args: list[str] | None = None,
+    show_banner: bool = True,
+    use_direct_import: bool = False,
+    skip_source: bool = False,
+    stateless: bool = False,
+) -> None:
+    """Run a MCP server or connect to a remote one.
+
+    Args:
+        server_spec: Python file, object specification (file:obj), config file, or URL
+        transport: Transport protocol to use
+        host: Host to bind to when using http transport
+        port: Port to bind to when using http transport
+        path: Path to bind to when using http transport
+        log_level: Log level
+        server_args: Additional arguments to pass to the server
+        show_banner: Whether to show the server banner
+        use_direct_import: Whether to use direct import instead of subprocess
+        skip_source: Whether to skip source preparation step
+        stateless: Whether to run in stateless mode (no session)
+    """
+    # Special case: URLs
+    if is_url(server_spec):
+        # Handle URL case
+        server = create_client_server(server_spec)
+        logger.debug(f"Created client proxy server for {server_spec}")
+    # Special case: MCPConfig files (legacy)
+    elif server_spec.endswith(".json"):
+        # Load JSON and check which type of config it is
+        config_path = Path(server_spec)
+        with open(config_path) as f:
+            data = json.load(f)
+
+        # Check if it's an MCPConfig first (has canonical mcpServers key)
+        if "mcpServers" in data:
+            # It's an MCP config
+            server = create_mcp_config_server(config_path)
+        else:
+            # It's a FastMCP config - load it properly
+            config = load_mcp_server_config(config_path)
+
+            # Merge deployment config with CLI arguments (CLI takes precedence)
+            transport = (
+                transport if transport is not None else config.deployment.transport
+            )
+            host = host if host is not None else config.deployment.host
+            port = port if port is not None else config.deployment.port
+            path = path if path is not None else config.deployment.path
+            log_level = (
+                log_level if log_level is not None else config.deployment.log_level
+            )
+            server_args = (
+                server_args if server_args is not None else config.deployment.args
+            )
+
+            # Prepare source only (environment is handled by uv run)
+            await config.prepare_source() if not skip_source else None
+
+            # Load the server using the source
+            from contextlib import nullcontext
+
+            from fastmcp.cli.cli import with_argv
+
+            # Use sys.argv context manager if deployment args specified
+            argv_context = with_argv(server_args) if server_args else nullcontext()
+
+            with argv_context:
+                server = await config.source.load_server()
+
+            logger.debug(f'Found server "{server.name}" from config {config_path}')
+    else:
+        # Regular file case - create a MCPServerConfig with FileSystemSource
+        source = FileSystemSource(path=server_spec)
+        config = MCPServerConfig(source=source)
+
+        # Prepare source only (environment is handled by uv run)
+        await config.prepare_source() if not skip_source else None
+
+        # Load the server
+        from contextlib import nullcontext
+
+        from fastmcp.cli.cli import with_argv
+
+        # Use sys.argv context manager if server_args specified
+        argv_context = with_argv(server_args) if server_args else nullcontext()
+
+        with argv_context:
+            server = await config.source.load_server()
+
+        logger.debug(f'Found server "{server.name}" in {source.path}')
+
+    # Run the server
+
+    # handle the SDK's own high-level MCPServer (not a fastmcp.FastMCP)
+    if isinstance(server, SDKServer):
+        await run_v1_server_async(server, host=host, port=port, transport=transport)
+        return
+
+    kwargs: dict[str, Any] = {}
+    if transport is not None:
+        kwargs["transport"] = transport
+    # Resolve effective transport for the HTTP kwargs guard — transport
+    # may be None here if the user didn't pass --transport, in which case
+    # run_async will resolve it from settings.transport.
+    effective_transport = (
+        transport if transport is not None else fastmcp.settings.transport
+    )
+    if effective_transport != "stdio":
+        if host is not None:
+            kwargs["host"] = host
+        if port is not None:
+            kwargs["port"] = port
+        if path is not None:
+            kwargs["path"] = path
+    if log_level is not None:
+        kwargs["log_level"] = log_level
+    if stateless:
+        kwargs["stateless"] = True
+
+    if not show_banner:
+        kwargs["show_banner"] = False
+
+    try:
+        await server.run_async(**kwargs)
+    except Exception as e:
+        logger.error(f"Failed to run server: {e}")
+        sys.exit(1)
+
+
+def run_module_command(
+    module_name: str,
+    *,
+    env_command_builder: Callable[[list[str]], list[str]] | None = None,
+    extra_args: list[str] | None = None,
+) -> None:
+    """Run a Python module directly using ``python -m <module>``.
+
+    When ``-m`` is used, the module manages its own server startup.
+    No server-object discovery or transport overrides are applied.
+
+    Args:
+        module_name: Dotted module name (e.g. ``my_package``).
+        env_command_builder: An optional callable that wraps a command list
+            with environment setup (e.g. ``UVEnvironment.build_command``).
+        extra_args: Extra arguments forwarded after the module name.
+    """
+    # Use bare "python" when an env wrapper (e.g. uv run) is active so that
+    # the wrapper can resolve the interpreter via --python / environment config.
+    # Fall back to sys.executable for direct execution without a wrapper.
+    python = "python" if env_command_builder is not None else sys.executable
+    cmd: list[str] = [python, "-m", module_name]
+    if extra_args:
+        cmd.extend(extra_args)
+
+    # Wrap with environment (e.g. uv run) if configured
+    if env_command_builder is not None:
+        cmd = env_command_builder(cmd)
+
+    logger.debug(f"Running module: {' '.join(cmd)}")
+
+    try:
+        process = subprocess.run(cmd, check=True)
+        sys.exit(process.returncode)
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Module {module_name} exited with code {e.returncode}")
+        sys.exit(e.returncode)
+
+
+async def run_v1_server_async(
+    server: SDKServer,
+    host: str | None = None,
+    port: int | None = None,
+    transport: TransportType | None = None,
+) -> None:
+    """Run a FastMCP 1.x server using async methods.
+
+    Args:
+        server: FastMCP 1.x server instance
+        host: Host to bind to
+        port: Port to bind to
+        transport: Transport protocol to use
+    """
+    # In v1 (MCPServer), host/port are no longer stored on `settings`; they are
+    # passed directly to the transport runners as keyword arguments.
+    bind_kwargs: dict[str, Any] = {}
+    if host is not None:
+        bind_kwargs["host"] = host
+    if port is not None:
+        bind_kwargs["port"] = port
+
+    match transport:
+        case "stdio":
+            await server.run_stdio_async()
+        case "http" | "streamable-http" | None:
+            await server.run_streamable_http_async(**bind_kwargs)
+        case "sse":
+            await server.run_sse_async(**bind_kwargs)
+
+
+def _watch_filter(_change: Change, path: str) -> bool:
+    """Filter for files that should trigger reload."""
+    return any(path.endswith(ext) for ext in WATCHED_EXTENSIONS)
+
+
+async def _terminate_process(process: asyncio.subprocess.Process) -> None:
+    """Terminate a subprocess and all its children.
+
+    Sends SIGTERM to the process group first for graceful shutdown,
+    then falls back to SIGKILL if the process doesn't exit in time.
+    """
+    if process.returncode is not None:
+        return
+
+    pid = process.pid
+
+    if sys.platform != "win32":
+        # Send SIGTERM to the entire process group for graceful shutdown
+        with contextlib.suppress(ProcessLookupError, OSError):
+            os.killpg(os.getpgid(pid), signal.SIGTERM)
+
+        # Wait briefly for graceful exit
+        try:
+            await asyncio.wait_for(process.wait(), timeout=3.0)
+            return
+        except asyncio.TimeoutError:
+            pass
+
+        # Force kill the entire process group
+        with contextlib.suppress(ProcessLookupError, OSError):
+            os.killpg(os.getpgid(pid), signal.SIGKILL)
+    else:
+        process.kill()
+
+    await process.wait()
+
+
+async def run_with_reload(
+    cmd: list[str],
+    reload_dirs: list[Path] | None = None,
+    is_stdio: bool = False,
+) -> None:
+    """Run a command with file watching and auto-reload.
+
+    Args:
+        cmd: Command to run as subprocess (should include --no-reload)
+        reload_dirs: Directories to watch for changes (default: cwd)
+        is_stdio: Whether this is stdio transport
+    """
+    watch_paths = reload_dirs or [Path.cwd()]
+    process: asyncio.subprocess.Process | None = None
+
+    if is_stdio:
+        logger.info("Reload mode enabled (using stateless sessions)")
+    else:
+        logger.info(
+            "Reload mode enabled (using stateless HTTP). "
+            "Some features requiring bidirectional communication "
+            "(like elicitation) are not available."
+        )
+
+    # Handle SIGTERM/SIGINT gracefully with proper asyncio integration
+    shutdown_event = asyncio.Event()
+    loop = asyncio.get_running_loop()
+
+    def signal_handler() -> None:
+        logger.info("Received shutdown signal, stopping...")
+        shutdown_event.set()
+
+    # Windows doesn't support add_signal_handler
+    if sys.platform != "win32":
+        loop.add_signal_handler(signal.SIGTERM, signal_handler)
+        loop.add_signal_handler(signal.SIGINT, signal_handler)
+
+    try:
+        while not shutdown_event.is_set():
+            process = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdin=None,
+                stdout=None,
+                stderr=None,
+                # Own process group so _terminate_process can kill the whole tree
+                start_new_session=sys.platform != "win32",
+            )
+
+            # Watch for either: file changes OR process death
+            watch_task = asyncio.create_task(
+                anext(aiter(awatch(*watch_paths, watch_filter=_watch_filter)))  # ty: ignore[invalid-argument-type]
+            )
+            wait_task = asyncio.create_task(process.wait())
+            shutdown_task = asyncio.create_task(shutdown_event.wait())
+
+            done, pending = await asyncio.wait(
+                [watch_task, wait_task, shutdown_task],
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+
+            for task in pending:
+                task.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await task
+
+            if shutdown_task in done:
+                # User requested shutdown
+                break
+
+            if wait_task in done:
+                # Server died on its own - wait for file change before restart
+                code = wait_task.result()
+                if code != 0:
+                    logger.error(
+                        f"Server exited with code {code}, waiting for file change..."
+                    )
+                else:
+                    logger.info("Server exited, waiting for file change...")
+
+                # Wait for file change or shutdown (avoid hot loop on crash)
+                watch_task = asyncio.create_task(
+                    anext(aiter(awatch(*watch_paths, watch_filter=_watch_filter)))  # ty: ignore[invalid-argument-type]
+                )
+                shutdown_task = asyncio.create_task(shutdown_event.wait())
+                done, pending = await asyncio.wait(
+                    [watch_task, shutdown_task],
+                    return_when=asyncio.FIRST_COMPLETED,
+                )
+                for task in pending:
+                    task.cancel()
+                    with contextlib.suppress(asyncio.CancelledError):
+                        await task
+                if shutdown_task in done:
+                    break
+                logger.info("Detected changes, restarting...")
+            else:
+                # File changed - restart server
+                changes = watch_task.result()
+                logger.info(
+                    f"Detected changes in {len(changes)} file(s), restarting..."
+                )
+                await _terminate_process(process)
+
+    except KeyboardInterrupt:
+        # Handle Ctrl+C on Windows (where add_signal_handler isn't available)
+        logger.info("Received shutdown signal, stopping...")
+
+    finally:
+        # Clean up signal handlers
+        if sys.platform != "win32":
+            loop.remove_signal_handler(signal.SIGTERM)
+            loop.remove_signal_handler(signal.SIGINT)
+        if process and process.returncode is None:
+            await _terminate_process(process)
diff --git a/fastmcp_slim/fastmcp/cli/tasks.py b/fastmcp_slim/fastmcp/cli/tasks.py
new file mode 100644
index 0000000..23ddc6e
--- /dev/null
+++ b/fastmcp_slim/fastmcp/cli/tasks.py
@@ -0,0 +1,110 @@
+"""FastMCP tasks CLI for Docket task management."""
+
+import asyncio
+import sys
+from typing import Annotated
+
+import cyclopts
+from rich.console import Console
+
+from fastmcp.utilities.cli import load_and_merge_config
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger("cli.tasks")
+console = Console()
+
+tasks_app = cyclopts.App(
+    name="tasks",
+    help="Manage FastMCP background tasks using Docket",
+)
+
+
+def check_distributed_backend() -> None:
+    """Check if Docket is configured with a distributed backend.
+
+    The CLI worker runs as a separate process, so it needs Redis/Valkey
+    to coordinate with the main server process.
+
+    Raises:
+        SystemExit: If using memory:// URL
+    """
+    import fastmcp
+
+    docket_url = fastmcp.settings.docket.url
+
+    # Check for memory:// URL and provide helpful error
+    if docket_url.startswith("memory://"):
+        console.print(
+            "[bold red]✗ In-memory backend not supported by CLI[/bold red]\n\n"
+            "Your Docket configuration uses an in-memory backend (memory://) which\n"
+            "only works within a single process.\n\n"
+            "To use [cyan]fastmcp tasks[/cyan] CLI commands (which run in separate\n"
+            "processes), you need a distributed backend:\n\n"
+            "[bold]1. Install Redis or Valkey:[/bold]\n"
+            "   [dim]macOS:[/dim]     brew install redis\n"
+            "   [dim]Ubuntu:[/dim]    apt install redis-server\n"
+            "   [dim]Valkey:[/dim]    See https://valkey.io/\n\n"
+            "[bold]2. Start the service:[/bold]\n"
+            "   redis-server\n\n"
+            "[bold]3. Configure Docket URL:[/bold]\n"
+            "   [dim]Environment variable:[/dim]\n"
+            "   export FASTMCP_DOCKET_URL=redis://localhost:6379/0\n\n"
+            "[bold]4. Try again[/bold]\n\n"
+            "The memory backend works great for single-process servers, but the CLI\n"
+            "commands need a distributed backend to coordinate across processes.\n\n"
+            "Need help? See: [cyan]https://gofastmcp.com/docs/tasks[/cyan]"
+        )
+        sys.exit(1)
+
+
+@tasks_app.command
+def worker(
+    server_spec: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            help="Python file to run, optionally with :object suffix, or None to auto-detect fastmcp.json"
+        ),
+    ] = None,
+) -> None:
+    """Start an additional worker to process background tasks.
+
+    Connects to your Docket backend and processes tasks in parallel with
+    any other running workers. Configure via environment variables
+    (FASTMCP_DOCKET_*).
+
+    Example:
+        fastmcp tasks worker server.py
+        fastmcp tasks worker examples/tasks/server.py
+    """
+    import fastmcp
+
+    check_distributed_backend()
+
+    # Load server to get task functions
+    try:
+        config, _resolved_spec = load_and_merge_config(server_spec)
+    except FileNotFoundError:
+        sys.exit(1)
+
+    # Load the server
+    server = asyncio.run(config.source.load_server())
+
+    async def run_worker():
+        """Enter server lifespan and camp forever."""
+        async with server._lifespan_manager():
+            console.print(
+                f"[bold green]✓[/bold green] Starting worker for [cyan]{server.name}[/cyan]"
+            )
+            console.print(f"  Docket: {fastmcp.settings.docket.name}")
+            console.print(f"  Backend: {fastmcp.settings.docket.url}")
+            console.print(f"  Concurrency: {fastmcp.settings.docket.concurrency}")
+
+            # Server's lifespan has started its worker - just camp here forever
+            while True:
+                await asyncio.sleep(3600)
+
+    try:
+        asyncio.run(run_worker())
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Worker stopped[/yellow]")
+        sys.exit(0)
diff --git a/fastmcp_slim/fastmcp/client/__init__.py b/fastmcp_slim/fastmcp/client/__init__.py
new file mode 100644
index 0000000..d5e65e2
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/__init__.py
@@ -0,0 +1,35 @@
+from fastmcp import _install_hints
+
+try:
+    from .auth import OAuth, BearerAuth
+    from .client import Client
+    from .transports import (
+        ClientTransport,
+        FastMCPTransport,
+        NodeStdioTransport,
+        NpxStdioTransport,
+        PythonStdioTransport,
+        SSETransport,
+        StdioTransport,
+        StreamableHttpTransport,
+        UvStdioTransport,
+        UvxStdioTransport,
+    )
+except ImportError as exc:
+    raise ImportError(_install_hints.CLIENT_SUPPORT) from exc
+
+__all__ = [
+    "BearerAuth",
+    "Client",
+    "ClientTransport",
+    "FastMCPTransport",
+    "NodeStdioTransport",
+    "NpxStdioTransport",
+    "OAuth",
+    "PythonStdioTransport",
+    "SSETransport",
+    "StdioTransport",
+    "StreamableHttpTransport",
+    "UvStdioTransport",
+    "UvxStdioTransport",
+]
diff --git a/fastmcp_slim/fastmcp/client/_sdk_context_shim.py b/fastmcp_slim/fastmcp/client/_sdk_context_shim.py
new file mode 100644
index 0000000..958bec3
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/_sdk_context_shim.py
@@ -0,0 +1,33 @@
+"""Subscriptable request-context alias for FastMCP client handler signatures.
+
+FastMCP exposes public generic handler type aliases (``SamplingHandler``,
+``RootsHandler``, ``ElicitationHandler``) parameterized over a session and a
+lifespan-context type. The MCP SDK v2 request context (
+``mcp.client.ClientRequestContext``) is a plain ``kw_only`` dataclass and is
+NOT subscriptable, so it cannot back those two-parameter aliases directly.
+
+This module keeps a subscriptable ``RequestContext[SessionT, LifespanContextT]``
+generic so the public alias surface is preserved unchanged. It is a permanent
+part of the client type surface, not a migration placeholder. The concrete
+context object handlers receive at runtime is the SDK's ``ClientRequestContext``;
+our ``create_*_callback`` wrappers pass it through opaquely.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar
+
+LifespanContextT = TypeVar("LifespanContextT")
+_SessionT = TypeVar("_SessionT")
+
+
+class RequestContext(Generic[_SessionT, LifespanContextT]):
+    """Placeholder for the removed SDK ``RequestContext`` generic.
+
+    Subscriptable with two type parameters to match existing client handler
+    annotations. Not instantiated anywhere; exists only so module imports and
+    annotation evaluation succeed until the Phase C client port lands.
+    """
+
+    def __class_getitem__(cls, item: Any) -> Any:  # pragma: no cover - typing only
+        return super().__class_getitem__(item)  # type: ignore[misc]
diff --git a/fastmcp_slim/fastmcp/client/auth/__init__.py b/fastmcp_slim/fastmcp/client/auth/__init__.py
new file mode 100644
index 0000000..6ec3ecf
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/auth/__init__.py
@@ -0,0 +1,4 @@
+from .bearer import BearerAuth
+from .oauth import OAuth
+
+__all__ = ["BearerAuth", "OAuth"]
diff --git a/fastmcp_slim/fastmcp/client/auth/bearer.py b/fastmcp_slim/fastmcp/client/auth/bearer.py
new file mode 100644
index 0000000..0c38a11
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/auth/bearer.py
@@ -0,0 +1,17 @@
+import httpx
+from pydantic import SecretStr
+
+from fastmcp.utilities.logging import get_logger
+
+__all__ = ["BearerAuth"]
+
+logger = get_logger(__name__)
+
+
+class BearerAuth(httpx.Auth):
+    def __init__(self, token: str):
+        self.token = SecretStr(token)
+
+    def auth_flow(self, request):
+        request.headers["Authorization"] = f"Bearer {self.token.get_secret_value()}"
+        yield request
diff --git a/fastmcp_slim/fastmcp/client/auth/oauth.py b/fastmcp_slim/fastmcp/client/auth/oauth.py
new file mode 100644
index 0000000..2a15697
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/auth/oauth.py
@@ -0,0 +1,457 @@
+from __future__ import annotations
+
+import time
+import webbrowser
+from collections.abc import AsyncGenerator
+from contextlib import aclosing
+from typing import Any
+
+import anyio
+import httpx
+from key_value.aio.adapters.pydantic import PydanticAdapter
+from key_value.aio.protocols import AsyncKeyValue
+from key_value.aio.stores.memory import MemoryStore
+from mcp.client.auth import OAuthClientProvider, TokenStorage
+from mcp.shared._httpx_utils import McpHttpClientFactory
+from mcp.shared.auth import (
+    AuthorizationCodeResult,
+    OAuthClientInformationFull,
+    OAuthClientMetadata,
+    OAuthToken,
+)
+from pydantic import AnyHttpUrl
+from typing_extensions import override
+from uvicorn.server import Server
+
+from fastmcp.client.oauth_callback import (
+    OAuthCallbackResult,
+    create_oauth_callback_server,
+)
+from fastmcp.utilities.http import find_available_port
+from fastmcp.utilities.logging import get_logger
+
+__all__ = ["OAuth"]
+
+logger = get_logger(__name__)
+
+
+def _normalize_callback_host_for_bind(host: str) -> str:
+    if host.startswith("[") and host.endswith("]"):
+        return host[1:-1]
+    return host
+
+
+def _format_callback_host_for_url(host: str) -> str:
+    if ":" in host:
+        return f"[{host}]"
+    return host
+
+
+class ClientNotFoundError(Exception):
+    """Raised when OAuth client credentials are not found on the server."""
+
+
+async def check_if_auth_required(
+    mcp_url: str, httpx_kwargs: dict[str, Any] | None = None
+) -> bool:
+    """
+    Check if the MCP endpoint requires authentication by making a test request.
+
+    Returns:
+        True if auth appears to be required, False otherwise
+    """
+    async with httpx.AsyncClient(**(httpx_kwargs or {})) as client:
+        try:
+            # Try a simple request to the endpoint
+            response = await client.get(mcp_url, timeout=5.0)
+
+            # If we get 401/403, auth is likely required
+            if response.status_code in (401, 403):
+                return True
+
+            # Check for WWW-Authenticate header
+            if "WWW-Authenticate" in response.headers:  # noqa: SIM103
+                return True
+
+            # If we get a successful response, auth may not be required
+            return False
+
+        except httpx.RequestError:
+            # If we can't connect, assume auth might be required
+            return True
+
+
+class TokenStorageAdapter(TokenStorage):
+    _server_url: str
+    _key_value_store: AsyncKeyValue
+    _storage_oauth_token: PydanticAdapter[OAuthToken]
+    _storage_client_info: PydanticAdapter[OAuthClientInformationFull]
+
+    def __init__(self, async_key_value: AsyncKeyValue, server_url: str):
+        self._server_url = server_url
+        self._key_value_store = async_key_value
+        self._storage_oauth_token = PydanticAdapter[OAuthToken](
+            default_collection="mcp-oauth-token",
+            key_value=async_key_value,
+            pydantic_model=OAuthToken,
+            raise_on_validation_error=True,
+        )
+        self._storage_client_info = PydanticAdapter[OAuthClientInformationFull](
+            default_collection="mcp-oauth-client-info",
+            key_value=async_key_value,
+            pydantic_model=OAuthClientInformationFull,
+            raise_on_validation_error=True,
+        )
+
+    def _get_token_cache_key(self) -> str:
+        return f"{self._server_url}/tokens"
+
+    def _get_client_info_cache_key(self) -> str:
+        return f"{self._server_url}/client_info"
+
+    def _get_token_expiry_cache_key(self) -> str:
+        return f"{self._server_url}/token_expiry"
+
+    async def clear(self) -> None:
+        await self._storage_oauth_token.delete(key=self._get_token_cache_key())
+        await self._storage_client_info.delete(key=self._get_client_info_cache_key())
+        await self._key_value_store.delete(
+            key=self._get_token_expiry_cache_key(),
+            collection="mcp-oauth-token-expiry",
+        )
+
+    @override
+    async def get_tokens(self) -> OAuthToken | None:
+        return await self._storage_oauth_token.get(key=self._get_token_cache_key())
+
+    @override
+    async def set_tokens(self, tokens: OAuthToken) -> None:
+        # Don't set TTL based on access token expiry - the refresh token may be
+        # valid much longer. Use 1 year as a reasonable upper bound; the OAuth
+        # provider handles actual token expiry/refresh logic.
+        await self._storage_oauth_token.put(
+            key=self._get_token_cache_key(),
+            value=tokens,
+            ttl=60 * 60 * 24 * 365,  # 1 year
+        )
+        # Store absolute expiry so reloads don't misinterpret the stale
+        # relative expires_in value (#2862).
+        if tokens.expires_in is not None:
+            expires_at = time.time() + int(tokens.expires_in)
+            await self._key_value_store.put(
+                key=self._get_token_expiry_cache_key(),
+                value={"expires_at": expires_at},
+                collection="mcp-oauth-token-expiry",
+                ttl=60 * 60 * 24 * 365,
+            )
+
+    async def get_token_expiry(self) -> float | None:
+        raw = await self._key_value_store.get(
+            key=self._get_token_expiry_cache_key(),
+            collection="mcp-oauth-token-expiry",
+        )
+        if raw is not None:
+            return float(raw["expires_at"])
+        return None
+
+    @override
+    async def get_client_info(self) -> OAuthClientInformationFull | None:
+        return await self._storage_client_info.get(
+            key=self._get_client_info_cache_key()
+        )
+
+    @override
+    async def set_client_info(self, client_info: OAuthClientInformationFull) -> None:
+        ttl: int | None = None
+
+        if client_info.client_secret_expires_at:
+            ttl = client_info.client_secret_expires_at - int(time.time())
+
+        await self._storage_client_info.put(
+            key=self._get_client_info_cache_key(),
+            value=client_info,
+            ttl=ttl,
+        )
+
+
+class OAuth(OAuthClientProvider):
+    """
+    OAuth client provider for MCP servers with browser-based authentication.
+
+    This class provides OAuth authentication for FastMCP clients by opening
+    a browser for user authorization and running a local callback server.
+    """
+
+    _bound: bool
+
+    def __init__(
+        self,
+        mcp_url: str | None = None,
+        scopes: str | list[str] | None = None,
+        client_name: str = "FastMCP Client",
+        token_storage: AsyncKeyValue | None = None,
+        additional_client_metadata: dict[str, Any] | None = None,
+        callback_port: int | None = None,
+        callback_host: str = "localhost",
+        callback_timeout: float = 300.0,
+        httpx_client_factory: McpHttpClientFactory | None = None,
+        # Alternative to dynamic client registration:
+        # --- Clients host a static JSON document at an HTTPS URL ---
+        client_metadata_url: str | None = None,
+        # --- OR clients provide full client information ---
+        client_id: str | None = None,
+        client_secret: str | None = None,
+    ):
+        """
+        Initialize OAuth client provider for an MCP server.
+
+        Args:
+            mcp_url: Full URL to the MCP endpoint (e.g. "http://host/mcp/sse/").
+                Optional when OAuth is passed to Client(auth=...), which provides
+                the URL automatically from the transport.
+            scopes: OAuth scopes to request. Can be a
+            space-separated string or a list of strings.
+            client_name: Name for this client during registration
+            token_storage: An AsyncKeyValue-compatible token store, tokens are stored in memory if not provided
+            additional_client_metadata: Extra fields for OAuthClientMetadata
+            callback_port: Fixed port for OAuth callback (default: random available port)
+            callback_host: Hostname used for OAuth redirect URI and callback server.
+            callback_timeout: Seconds to wait for OAuth callback before timing out.
+            client_metadata_url: A CIMD (Client ID Metadata Document) URL. When
+                provided, this URL is used as the client_id instead of performing
+                Dynamic Client Registration. Must be an HTTPS URL with a non-root
+                path (e.g. "https://myapp.example.com/oauth/client.json").
+            client_id: Pre-registered OAuth client ID. When provided, skips dynamic
+                client registration and uses these static credentials instead.
+            client_secret: OAuth client secret (optional, used with client_id)
+        """
+        # Store config for deferred binding if mcp_url not yet known
+        self._scopes = scopes
+        self._client_name = client_name
+        self._token_storage = token_storage
+        self._additional_client_metadata = additional_client_metadata
+        self._callback_port = callback_port
+        self._callback_host = _normalize_callback_host_for_bind(callback_host)
+        self._callback_timeout = callback_timeout
+        self._client_metadata_url = client_metadata_url
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._static_client_info = None
+        self.httpx_client_factory = httpx_client_factory or httpx.AsyncClient
+        self._bound = False
+
+        if mcp_url is not None:
+            self._bind(mcp_url)
+
+    def _bind(self, mcp_url: str) -> None:
+        """Bind this OAuth provider to a specific MCP server URL.
+
+        Called automatically when mcp_url is provided to __init__, or by the
+        transport when OAuth is used without an explicit URL.
+        """
+        if self._bound:
+            return
+
+        mcp_url = mcp_url.rstrip("/")
+
+        self.redirect_port = self._callback_port or find_available_port(
+            host=self._callback_host
+        )
+        redirect_host = _format_callback_host_for_url(self._callback_host)
+        redirect_uri = f"http://{redirect_host}:{self.redirect_port}/callback"
+
+        scopes_str: str
+        if isinstance(self._scopes, list):
+            scopes_str = " ".join(self._scopes)
+        elif self._scopes is not None:
+            scopes_str = str(self._scopes)
+        else:
+            scopes_str = ""
+
+        client_metadata = OAuthClientMetadata(
+            client_name=self._client_name,
+            redirect_uris=[AnyHttpUrl(redirect_uri)],
+            grant_types=["authorization_code", "refresh_token"],
+            response_types=["code"],
+            scope=scopes_str,
+            **(self._additional_client_metadata or {}),
+        )
+
+        if self._client_id:
+            # Create the full static client info directly which will avoid DCR.
+            # Spread client_metadata so redirect_uris, grant_types, response_types,
+            # scope, etc. are included — servers may validate these fields.
+            metadata = client_metadata.model_dump(exclude_none=True)
+            # Default token_endpoint_auth_method based on whether a secret is
+            # provided, unless the caller already set it via additional_client_metadata.
+            if "token_endpoint_auth_method" not in metadata:
+                metadata["token_endpoint_auth_method"] = (
+                    "client_secret_post" if self._client_secret else "none"
+                )
+            self._static_client_info = OAuthClientInformationFull(
+                client_id=self._client_id,
+                client_secret=self._client_secret,
+                **metadata,
+            )
+
+        token_storage = self._token_storage or MemoryStore()
+
+        if isinstance(token_storage, MemoryStore):
+            from warnings import warn
+
+            warn(
+                message="Using in-memory token storage -- tokens will be lost when the client restarts. "
+                "For persistent storage across multiple MCP servers, provide an encrypted AsyncKeyValue backend. "
+                "See https://gofastmcp.com/clients/auth/oauth#token-storage for details.",
+                stacklevel=2,
+            )
+
+        # Use full URL for token storage to properly separate tokens per MCP endpoint
+        self.token_storage_adapter: TokenStorageAdapter = TokenStorageAdapter(
+            async_key_value=token_storage, server_url=mcp_url
+        )
+
+        self.mcp_url = mcp_url
+
+        super().__init__(
+            server_url=mcp_url,
+            client_metadata=client_metadata,
+            storage=self.token_storage_adapter,
+            redirect_handler=self.redirect_handler,
+            callback_handler=self.callback_handler,
+            timeout=self._callback_timeout,
+            client_metadata_url=self._client_metadata_url,
+        )
+
+        self._bound = True
+
+    async def _initialize(self) -> None:
+        """Load stored tokens and client info, properly setting token expiry."""
+        await super()._initialize()
+
+        if self._static_client_info is not None:
+            self.context.client_info = self._static_client_info
+            await self.token_storage_adapter.set_client_info(self._static_client_info)
+
+        if self.context.current_tokens and self.context.current_tokens.expires_in:
+            stored_expiry = await self.token_storage_adapter.get_token_expiry()
+            if stored_expiry is not None:
+                self.context.token_expiry_time = stored_expiry
+            else:
+                self.context.update_token_expiry(self.context.current_tokens)
+
+    async def redirect_handler(self, authorization_url: str) -> None:
+        """Open browser for authorization, with pre-flight check for invalid client."""
+        # Pre-flight check to detect invalid client_id before opening browser
+        async with self.httpx_client_factory() as client:
+            response = await client.get(authorization_url, follow_redirects=False)
+
+            # Check for client not found error (400 typically means bad client_id)
+            if response.status_code == 400:
+                raise ClientNotFoundError(
+                    "OAuth client not found - cached credentials may be stale"
+                )
+
+            # OAuth typically returns redirects, but some providers return 200 with HTML login pages
+            if response.status_code not in (200, 302, 303, 307, 308):
+                raise RuntimeError(
+                    f"Unexpected authorization response: {response.status_code}"
+                )
+
+        logger.info(f"OAuth authorization URL: {authorization_url}")
+        webbrowser.open(authorization_url)
+
+    async def callback_handler(self) -> AuthorizationCodeResult:
+        """Handle OAuth callback and return the authorization code result."""
+        # Create result container and event to capture the OAuth response
+        result = OAuthCallbackResult()
+        result_ready = anyio.Event()
+
+        # Create server with result tracking
+        server: Server = create_oauth_callback_server(
+            port=self.redirect_port,
+            host=self._callback_host,
+            server_url=self.mcp_url,
+            result_container=result,
+            result_ready=result_ready,
+        )
+
+        # Run server until response is received with timeout logic
+        async with anyio.create_task_group() as tg:
+            tg.start_soon(server.serve)
+            logger.info(
+                f"🎧 OAuth callback server started on http://{self._callback_host}:{self.redirect_port}"
+            )
+
+            try:
+                with anyio.fail_after(self._callback_timeout):
+                    await result_ready.wait()
+                    if result.error:
+                        raise result.error
+                    # `result.code` is set once `result_ready` fires without error.
+                    return AuthorizationCodeResult(
+                        code=result.code,  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+                        state=result.state,
+                    )
+            except TimeoutError as e:
+                raise TimeoutError(
+                    f"OAuth callback timed out after {self._callback_timeout} seconds"
+                ) from e
+            finally:
+                server.should_exit = True
+                await anyio.sleep(0.1)  # Allow server to shut down gracefully
+                tg.cancel_scope.cancel()
+
+        raise RuntimeError("OAuth callback handler could not be started")
+
+    async def async_auth_flow(
+        self, request: httpx.Request
+    ) -> AsyncGenerator[httpx.Request, httpx.Response]:
+        """HTTPX auth flow with automatic retry on stale cached credentials.
+
+        If the OAuth flow fails due to invalid/stale client credentials,
+        clears the cache and retries once with fresh registration.
+        """
+        if not self._bound:
+            raise RuntimeError(
+                "OAuth provider has no server URL. Either pass mcp_url to OAuth() "
+                "or use it with Client(auth=...) which provides the URL automatically."
+            )
+        try:
+            # First attempt with potentially cached credentials
+            async with aclosing(super().async_auth_flow(request)) as gen:
+                response = None
+                while True:
+                    try:
+                        # First iteration sends None, subsequent iterations send response
+                        yielded_request = await gen.asend(response)  # ty: ignore[invalid-argument-type]
+                        response = yield yielded_request
+                    except StopAsyncIteration:
+                        break
+
+        except ClientNotFoundError:
+            # Static credentials are fixed — retrying won't help. Surface the
+            # error so the user can correct their client_id / client_secret.
+            if self._static_client_info is not None:
+                raise ClientNotFoundError(
+                    "OAuth server rejected the static client credentials. "
+                    "Verify that the client_id (and client_secret, if provided) "
+                    "are correct and that the client is registered with the server."
+                ) from None
+
+            logger.debug(
+                "OAuth client not found on server, clearing cache and retrying..."
+            )
+            # Clear cached state and retry once
+            self._initialized = False
+            await self.token_storage_adapter.clear()
+
+            # Retry with fresh registration
+            async with aclosing(super().async_auth_flow(request)) as gen:
+                response = None
+                while True:
+                    try:
+                        yielded_request = await gen.asend(response)  # ty: ignore[invalid-argument-type]
+                        response = yield yielded_request
+                    except StopAsyncIteration:
+                        break
diff --git a/fastmcp_slim/fastmcp/client/client.py b/fastmcp_slim/fastmcp/client/client.py
new file mode 100644
index 0000000..2106c38
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/client.py
@@ -0,0 +1,1302 @@
+from __future__ import annotations
+
+import asyncio
+import copy
+import datetime
+import hashlib
+import secrets
+import ssl
+import uuid
+import weakref
+from collections.abc import Callable, Coroutine
+from contextlib import AsyncExitStack, asynccontextmanager, suppress
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar, cast, overload
+
+import anyio
+import anyio.lowlevel
+import httpx
+import mcp_types
+from exceptiongroup import catch
+from mcp import ClientSession, MCPError
+from mcp.client._input_required import (
+    DEFAULT_INPUT_REQUIRED_MAX_ROUNDS,
+    run_input_required_driver,
+)
+from mcp.client._probe import negotiate_auto
+from mcp.client.caching import (
+    CacheConfig,
+    CacheMode,
+    ClientResponseCache,
+    InMemoryResponseCacheStore,
+)
+from mcp.client.extension import NotificationBinding
+from mcp.client.session import ClientRequestContext, MessageHandlerFnT
+from mcp_types import (
+    GetTaskResult,
+    TaskStatusNotification,
+    TaskStatusNotificationParams,
+)
+from mcp_types.version import HANDSHAKE_PROTOCOL_VERSIONS, MODERN_PROTOCOL_VERSIONS
+from pydantic import AnyUrl
+
+import fastmcp as fastmcp
+from fastmcp.client.auth.oauth import OAuth
+from fastmcp.client.elicitation import (
+    ElicitationHandler,
+    create_elicitation_callback,
+)
+from fastmcp.client.logging import (
+    LogHandler,
+    create_log_callback,
+    default_log_handler,
+)
+from fastmcp.client.messages import MessageHandler, MessageHandlerT
+from fastmcp.client.mixins import (
+    ClientPromptsMixin,
+    ClientResourcesMixin,
+    ClientTaskManagementMixin,
+    ClientToolsMixin,
+)
+from fastmcp.client.progress import ProgressHandler, default_progress_handler
+from fastmcp.client.roots import (
+    RootsHandler,
+    RootsList,
+    create_roots_callback,
+)
+from fastmcp.client.sampling import (
+    SamplingHandler,
+    create_sampling_callback,
+)
+from fastmcp.client.tasks import (
+    PromptTask,
+    ResourceTask,
+    TaskNotificationHandler,
+    ToolTask,
+)
+from fastmcp.mcp_config import MCPConfig
+from fastmcp.utilities.exceptions import get_catch_handlers
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.timeout import normalize_timeout_to_seconds
+
+if TYPE_CHECKING:
+    from fastmcp.server import FastMCP
+else:
+    FastMCP = Any
+
+from .transports import (
+    ClientTransport,
+    ClientTransportT,
+    FastMCPTransport,
+    MCPConfigTransport,
+    NodeStdioTransport,
+    PythonStdioTransport,
+    SDKServer,
+    SessionKwargs,
+    SSETransport,
+    StreamableHttpTransport,
+    infer_transport,
+)
+
+__all__ = [
+    "Client",
+    "ElicitationHandler",
+    "LogHandler",
+    "MessageHandler",
+    "ProgressHandler",
+    "RootsHandler",
+    "RootsList",
+    "SamplingHandler",
+    "SessionKwargs",
+]
+
+logger = get_logger(__name__)
+
+T = TypeVar("T", bound="ClientTransport")
+ResultT = TypeVar("ResultT")
+CacheableT = TypeVar("CacheableT", bound=mcp_types.CacheableResult)
+
+ConnectMode = Literal["legacy", "auto"] | str
+"""How the client negotiates the protocol era at connect time.
+
+- ``"legacy"`` (the current default): the classic initialize handshake, byte-identical
+  to pre-v4 behavior for handshake-era servers.
+- ``"auto"``: probe ``server/discover`` at the newest modern version and adopt it, falling
+  back to the initialize handshake for any server that is not positive evidence of a modern
+  peer (a denylist fallback — see the SDK's ``negotiate_auto``).
+- a modern protocol-version string (e.g. ``"2026-07-28"``): adopt that version directly
+  without probing, synthesizing a minimal ``DiscoverResult`` when none is supplied.
+
+The ``str`` arm is only for the version-pin case; ``Client.__init__`` rejects any other value.
+"""
+
+
+def _synthesize_discover(protocol_version: str) -> mcp_types.DiscoverResult:
+    """Build a minimal ``DiscoverResult`` for a pinned modern version (no wire probe).
+
+    Mirrors the SDK Client's ``_synthesize_discover``: the version is pinned but the
+    server identity is unknown, so ``server_info`` is empty.
+    """
+    return mcp_types.DiscoverResult(
+        supported_versions=[protocol_version],
+        capabilities=mcp_types.ServerCapabilities(),
+        server_info=mcp_types.Implementation(name="", version=""),
+        result_type="complete",
+        ttl_ms=0,
+        cache_scope="public",
+    )
+
+
+def _evicting_message_handler(
+    cache: ClientResponseCache, user_handler: MessageHandlerFnT | None
+) -> MessageHandlerFnT:
+    """Compose cache eviction over an existing message handler (SEP-2549).
+
+    A server notification (tools/list_changed, resource updates, etc.) evicts the
+    entries it invalidates *before* the wrapped handler runs, so a downstream
+    consumer never observes a change while a stale cached listing is still served.
+    Mirrors the SDK Client's `_evicting_message_handler`, but delegates to FastMCP's
+    own handler chain rather than clobbering it. Eviction faults are contained: a
+    cache-store error must never block notification delivery.
+    """
+
+    async def handler(
+        message: Any,
+    ) -> None:
+        if isinstance(message, mcp_types.ServerNotification):
+            try:
+                await cache.evict_for_notification(message)
+            except Exception:
+                logger.exception(
+                    "Response cache eviction failed; the notification is still delivered"
+                )
+        if user_handler is not None:
+            await user_handler(message)
+        else:
+            await anyio.lowlevel.checkpoint()
+
+    return handler
+
+
+@dataclass
+class ClientSessionState:
+    """Holds all session-related state for a Client instance.
+
+    This allows clean separation of configuration (which is copied) from
+    session state (which should be fresh for each new client instance).
+    """
+
+    session: ClientSession | None = None
+    nesting_counter: int = 0
+    lock: anyio.Lock = field(default_factory=anyio.Lock)
+    session_task: asyncio.Task | None = None
+    ready_event: anyio.Event = field(default_factory=anyio.Event)
+    stop_event: anyio.Event = field(default_factory=anyio.Event)
+    initialize_result: mcp_types.InitializeResult | None = None
+
+
+@dataclass
+class CallToolResult:
+    """Parsed result from a tool call."""
+
+    content: list[mcp_types.ContentBlock]
+    structured_content: dict[str, Any] | None
+    meta: dict[str, Any] | None
+    data: Any = None
+    is_error: bool = False
+
+
+class Client(
+    Generic[ClientTransportT],
+    ClientResourcesMixin,
+    ClientPromptsMixin,
+    ClientToolsMixin,
+    ClientTaskManagementMixin,
+):
+    """
+    MCP client that delegates connection management to a Transport instance.
+
+    The Client class is responsible for MCP protocol logic, while the Transport
+    handles connection establishment and management. Client provides methods for
+    working with resources, prompts, tools and other MCP capabilities.
+
+    This client supports reentrant context managers (multiple concurrent
+    `async with client:` blocks) using reference counting and background session
+    management. This allows efficient session reuse in any scenario with
+    nested or concurrent client usage.
+
+    MCP SDK 1.10 introduced automatic list_tools() calls during call_tool()
+    execution. This created a race condition where events could be reset while
+    other tasks were waiting on them, causing deadlocks. The issue was exposed
+    in proxy scenarios but affects any reentrant usage.
+
+    The solution uses reference counting to track active context managers,
+    a background task to manage the session lifecycle, events to coordinate
+    between tasks, and ensures all session state changes happen within a lock.
+    Events are only created when needed, never reset outside locks.
+
+    This design prevents race conditions where tasks wait on events that get
+    replaced by other tasks, ensuring reliable coordination in concurrent scenarios.
+
+    Args:
+        transport:
+            Connection source specification, which can be:
+
+                - ClientTransport: Direct transport instance
+                - FastMCP: In-process FastMCP server
+                - AnyUrl or str: URL to connect to
+                - Path: File path for local socket
+                - MCPConfig: MCP server configuration
+                - dict: Transport configuration
+
+        roots: Optional RootsList or RootsHandler for filesystem access
+        sampling_handler: Optional handler for sampling requests
+        log_handler: Optional handler for log messages
+        message_handler: Optional handler for protocol messages
+        progress_handler: Optional handler for progress notifications
+        timeout: Optional timeout for requests (seconds or timedelta)
+        init_timeout: Optional timeout for initial connection (seconds or timedelta).
+            Set to 0 to disable. If None, uses the value in the FastMCP global settings.
+        mode: Protocol-era negotiation at connect time. `"legacy"` (the default) runs
+            the initialize handshake, byte-identical to pre-v4 behavior. `"auto"` probes
+            `server/discover` and negotiates the modern era, denylist-falling-back to the
+            handshake for legacy servers. A modern version string (e.g. `"2026-07-28"`)
+            adopts that version directly. `mode="auto"` as a future default is a
+            release-time decision; the conservative `"legacy"` is the default for now.
+        prior_discover: A previously obtained `DiscoverResult` to adopt when `mode` is a
+            version pin, reused instead of synthesizing a minimal one. Ignored otherwise.
+        input_required_max_rounds: Cap on `InputRequiredResult` (SEP-2322) retry rounds
+            for `call_tool` / `get_prompt` / `read_resource` before the driver gives up.
+            Only reachable on 2026-era servers that emit `InputRequiredResult`.
+        cache: Client-side response caching (SEP-2549), opt-in. `None` (default) and
+            `False` disable it; `True` enables the default in-memory store honoring
+            server `ttlMs`/`cacheScope` hints; a `CacheConfig` customizes it. Honoring is
+            modern-only, so a cache is inert on legacy connections. A custom `CacheConfig`
+            store requires `target_id`, since FastMCP transports expose no server URL to
+            derive a shared-store identity from.
+
+    Examples:
+        ```python
+        # Connect to FastMCP server
+        client = Client("http://localhost:8080")
+
+        async with client:
+            # List available resources
+            resources = await client.list_resources()
+
+            # Call a tool
+            result = await client.call_tool("my_tool", {"param": "value"})
+        ```
+    """
+
+    @overload
+    def __init__(self: Client[T], transport: T, *args: Any, **kwargs: Any) -> None: ...
+
+    @overload
+    def __init__(
+        self: Client[SSETransport | StreamableHttpTransport],
+        transport: AnyUrl,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self: Client[FastMCPTransport],
+        transport: FastMCP | SDKServer,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self: Client[PythonStdioTransport | NodeStdioTransport],
+        transport: Path,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self: Client[MCPConfigTransport],
+        transport: MCPConfig | dict[str, Any],
+        *args: Any,
+        **kwargs: Any,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self: Client[
+            PythonStdioTransport
+            | NodeStdioTransport
+            | SSETransport
+            | StreamableHttpTransport
+        ],
+        transport: str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None: ...
+
+    def __init__(
+        self,
+        transport: (
+            ClientTransportT
+            | FastMCP
+            | SDKServer
+            | AnyUrl
+            | Path
+            | MCPConfig
+            | dict[str, Any]
+            | str
+        ),
+        name: str | None = None,
+        roots: RootsList | RootsHandler | None = None,
+        sampling_handler: SamplingHandler | None = None,
+        sampling_capabilities: mcp_types.SamplingCapability | None = None,
+        elicitation_handler: ElicitationHandler | None = None,
+        log_handler: LogHandler | None = None,
+        message_handler: MessageHandlerT | MessageHandler | None = None,
+        progress_handler: ProgressHandler | None = None,
+        timeout: datetime.timedelta | float | int | None = None,
+        auto_initialize: bool = True,
+        init_timeout: datetime.timedelta | float | int | None = None,
+        client_info: mcp_types.Implementation | None = None,
+        auth: httpx.Auth | Literal["oauth"] | str | None = None,
+        verify: ssl.SSLContext | bool | str | None = None,
+        mode: ConnectMode = "legacy",
+        prior_discover: mcp_types.DiscoverResult | None = None,
+        input_required_max_rounds: int = DEFAULT_INPUT_REQUIRED_MAX_ROUNDS,
+        cache: CacheConfig | bool | None = None,
+    ) -> None:
+        self.name = name or self.generate_name()
+
+        self.input_required_max_rounds = input_required_max_rounds
+
+        if mode not in ("legacy", "auto") and mode not in MODERN_PROTOCOL_VERSIONS:
+            hint = (
+                f" ({mode!r} is a handshake-era version; use mode='legacy')"
+                if mode in HANDSHAKE_PROTOCOL_VERSIONS
+                else ""
+            )
+            raise ValueError(
+                "mode must be 'legacy', 'auto', or one of "
+                f"{list(MODERN_PROTOCOL_VERSIONS)}; got {mode!r}{hint}"
+            )
+        self.mode: ConnectMode = mode
+        self._prior_discover = prior_discover
+
+        self.transport = cast(ClientTransportT, infer_transport(transport))
+
+        if verify is not None:
+            from fastmcp.client.transports.http import StreamableHttpTransport
+            from fastmcp.client.transports.sse import SSETransport
+
+            if isinstance(self.transport, StreamableHttpTransport | SSETransport):
+                self.transport.verify = verify
+                # Re-sync existing OAuth auth with the new verify setting,
+                # but only if the transport doesn't have a custom factory
+                # (which takes precedence and was already applied to OAuth).
+                if (
+                    isinstance(self.transport.auth, OAuth)
+                    and auth is None
+                    and self.transport.httpx_client_factory is None
+                ):
+                    verify_factory = self.transport._make_verify_factory()
+                    if verify_factory is not None:
+                        self.transport.auth.httpx_client_factory = verify_factory
+            else:
+                raise ValueError(
+                    "The 'verify' parameter is only supported for HTTP transports."
+                )
+
+        if auth is not None:
+            self.transport._set_auth(auth)
+
+        if log_handler is None:
+            log_handler = default_log_handler
+
+        if progress_handler is None:
+            progress_handler = default_progress_handler
+
+        self._progress_handler = progress_handler
+
+        # Convert request timeout to float seconds (0 means disabled -> None)
+        read_timeout_seconds = normalize_timeout_to_seconds(timeout)
+
+        # handle init handshake timeout (0 means disabled)
+        if init_timeout is None:
+            init_timeout = fastmcp.settings.client_init_timeout
+        self._init_timeout = normalize_timeout_to_seconds(init_timeout)
+
+        self.auto_initialize = auto_initialize
+
+        # Client-side response cache (SEP-2549). Only honored at modern protocol
+        # versions (the SDK ClientResponseCache gates hint-reading on the negotiated
+        # era), so it is inert for legacy connections. `cache=False` disables it.
+        # Retained so `new()` can rebuild an independent cache per clone.
+        self._cache_arg: CacheConfig | bool | None = cache
+        self._response_cache: ClientResponseCache | None = self._build_response_cache(
+            cache
+        )
+
+        # The unwrapped base handler (default routes task notifications; a user
+        # handler is preserved as-is). Retained so `new()` can rebuild the clone's
+        # handler without unwrapping the cache-eviction wrapper below.
+        self._base_message_handler: MessageHandlerFnT | None = (
+            message_handler or TaskNotificationHandler(self)
+        )
+        effective_message_handler = self._base_message_handler
+        if self._response_cache is not None:
+            effective_message_handler = _evicting_message_handler(
+                self._response_cache, effective_message_handler
+            )
+
+        self._session_kwargs: SessionKwargs = {
+            "sampling_callback": None,
+            "list_roots_callback": None,
+            "logging_callback": create_log_callback(log_handler),
+            "message_handler": effective_message_handler,
+            "read_timeout_seconds": read_timeout_seconds,
+            "client_info": client_info,
+            # SDK v2 does not carry `notifications/tasks/status` in any protocol
+            # version's core notification tables, so it is never tee'd to the
+            # message_handler; a binding routes it to Task objects instead.
+            "notification_bindings": [self._task_status_binding()],
+        }
+
+        if roots is not None:
+            self.set_roots(roots)
+
+        if sampling_handler is not None:
+            self._session_kwargs["sampling_callback"] = create_sampling_callback(
+                sampling_handler
+            )
+            self._session_kwargs["sampling_capabilities"] = (
+                sampling_capabilities
+                if sampling_capabilities is not None
+                else mcp_types.SamplingCapability()
+            )
+
+        if elicitation_handler is not None:
+            self._session_kwargs["elicitation_callback"] = create_elicitation_callback(
+                elicitation_handler
+            )
+
+        # Maximum time to wait for a clean disconnect before giving up.
+        # Normally disconnects complete in <100ms; this is a safety net for
+        # unresponsive servers.
+        self._disconnect_timeout: float = fastmcp.settings.client_disconnect_timeout
+
+        # Session context management - see class docstring for detailed explanation
+        self._session_state = ClientSessionState()
+
+        # Track task IDs submitted by this client (for list_tasks support)
+        self._submitted_task_ids: set[str] = set()
+
+        # Registry for routing notifications/tasks/status to Task objects
+
+        self._task_registry: dict[
+            str, weakref.ref[ToolTask | PromptTask | ResourceTask]
+        ] = {}
+
+    def _build_response_cache(
+        self, cache: CacheConfig | bool | None
+    ) -> ClientResponseCache | None:
+        """Build the SEP-2549 response cache from the `cache=` argument.
+
+        Response caching is opt-in: `None` (the default) and `False` both leave it
+        disabled, so a legacy connection is byte-identical to pre-v4 behavior (no
+        message-handler wrapping, no caching). `True` enables it with the default
+        `CacheConfig` (honoring server `ttlMs`/`cacheScope` hints via a per-client
+        in-memory store); a `CacheConfig` customizes it.
+
+        Our transports abstract away the server URL the SDK Client uses to derive a
+        cache identity, so `target_id` comes from the explicit `CacheConfig.target_id`
+        or a random per-client id — meaning a custom shared store cannot serve one
+        client's entries to another (documented on the parameter).
+        """
+        if cache is None or cache is False:
+            return None
+        config = cache if isinstance(cache, CacheConfig) else CacheConfig()
+
+        target_id = config.target_id
+        if target_id is None:
+            if config.store is not None:
+                raise ValueError(
+                    "a custom cache store requires CacheConfig.target_id for FastMCP "
+                    "transports: the server URL the SDK derives an identity from is not "
+                    "available here, so entries in a shared store could never be served "
+                    "to another client"
+                )
+            target_id = uuid.uuid4().hex
+
+        return ClientResponseCache(
+            store=config.store
+            if config.store is not None
+            else InMemoryResponseCacheStore(),
+            partition=config.partition,
+            arm_id=hashlib.sha256(target_id.encode()).hexdigest(),
+            default_ttl_ms=config.default_ttl_ms,
+            clock=config.clock,
+            share_public=config.share_public,
+            # Lazy: the negotiated version is unknown until the handshake completes.
+            negotiated_version=lambda: (
+                self._session_state.session.protocol_version
+                if self._session_state.session is not None
+                else None
+            ),
+        )
+
+    def _reset_session_state(self, full: bool = False) -> None:
+        """Reset session state after disconnect or cancellation.
+
+        Args:
+            full: If True, also resets session_task and nesting_counter.
+                  Use full=True for cancellation cleanup where the session
+                  task was started but never completed normally.
+        """
+        self._session_state.session = None
+        self._session_state.initialize_result = None
+        if full:
+            self._session_state.session_task = None
+            self._session_state.nesting_counter = 0
+
+    @property
+    def session(self) -> ClientSession:
+        """Get the current active session. Raises RuntimeError if not connected."""
+        if self._session_state.session is None:
+            raise RuntimeError(
+                "Client is not connected. Use the 'async with client:' context manager first."
+            )
+
+        return self._session_state.session
+
+    @property
+    def initialize_result(self) -> mcp_types.InitializeResult | None:
+        """Get the result of the initialization request.
+
+        `None` on a modern (`server/discover`) connection, which negotiates via a
+        `DiscoverResult` rather than an `InitializeResult`. Use `protocol_version` /
+        `server_capabilities` for era-neutral access to the negotiated identity.
+        """
+        return self._session_state.initialize_result
+
+    @property
+    def protocol_version(self) -> str | None:
+        """The negotiated protocol version, or `None` when disconnected.
+
+        Set during connect-time negotiation regardless of era: the initialize
+        handshake, `server/discover`, or a direct version pin all populate it.
+        """
+        session = self._session_state.session
+        return session.protocol_version if session is not None else None
+
+    @property
+    def server_capabilities(self) -> mcp_types.ServerCapabilities | None:
+        """The server's advertised capabilities, or `None` when disconnected.
+
+        Populated from whichever negotiation result the era produced (the
+        `InitializeResult` on legacy, the `DiscoverResult` on modern).
+        """
+        session = self._session_state.session
+        return session.server_capabilities if session is not None else None
+
+    def set_roots(self, roots: RootsList | RootsHandler) -> None:
+        """Set the roots for the client. This does not automatically call `send_roots_list_changed`."""
+        self._session_kwargs["list_roots_callback"] = create_roots_callback(roots)
+
+    def set_sampling_callback(
+        self,
+        sampling_callback: SamplingHandler,
+        sampling_capabilities: mcp_types.SamplingCapability | None = None,
+    ) -> None:
+        """Set the sampling callback for the client."""
+        self._session_kwargs["sampling_callback"] = create_sampling_callback(
+            sampling_callback
+        )
+        self._session_kwargs["sampling_capabilities"] = (
+            sampling_capabilities
+            if sampling_capabilities is not None
+            else mcp_types.SamplingCapability()
+        )
+
+    def set_elicitation_callback(
+        self, elicitation_callback: ElicitationHandler
+    ) -> None:
+        """Set the elicitation callback for the client."""
+        self._session_kwargs["elicitation_callback"] = create_elicitation_callback(
+            elicitation_callback
+        )
+
+    def is_connected(self) -> bool:
+        """Check if the client is currently connected."""
+        return self._session_state.session is not None
+
+    def new(self) -> Client[ClientTransportT]:
+        """Create a new client instance with the same configuration but fresh session state.
+
+        This creates a new client with the same transport, handlers, and configuration,
+        but with no active session. Useful for creating independent sessions that don't
+        share state with the original client.
+
+        Returns:
+            A new Client instance with the same configuration but disconnected state.
+
+        Example:
+            ```python
+            # Create a fresh client for each concurrent operation
+            fresh_client = client.new()
+            async with fresh_client:
+                await fresh_client.call_tool("some_tool", {})
+            ```
+        """
+        new_client = copy.copy(self)
+
+        # Always reset session state so cloned clients start disconnected and do not
+        # share lifecycle state with the original instance.
+        new_client._session_state = ClientSessionState()
+
+        # Reset mutable task tracking state so new client is independent
+        new_client._task_registry = {}
+        new_client._submitted_task_ids = set()
+
+        # Give the clone its own response cache so cached entries are not shared
+        # across independent sessions, and rebuild the negotiated_version closure
+        # to point at the clone's session state.
+        new_client._response_cache = new_client._build_response_cache(self._cache_arg)
+
+        # Create a fresh session kwargs dict so the clone doesn't share
+        # the original's mutable dict. Rebind the task notification handler
+        # to the new client if the default handler is in use; preserve any
+        # custom message handler the user may have set.
+        new_client._session_kwargs = {**self._session_kwargs}  # type: ignore[typeddict-item]
+        # Recover the unwrapped base handler (never the cache-evicting wrapper): a
+        # default (TaskNotificationHandler) rebinds to the clone; a user handler is
+        # preserved. Then re-wrap with the clone's own cache if one exists.
+        base_handler: MessageHandlerFnT | None = self._base_message_handler
+        if isinstance(base_handler, TaskNotificationHandler) or base_handler is None:
+            base_handler = TaskNotificationHandler(new_client)
+        new_client._base_message_handler = base_handler
+        if new_client._response_cache is not None:
+            new_client._session_kwargs["message_handler"] = _evicting_message_handler(
+                new_client._response_cache, base_handler
+            )
+        else:
+            new_client._session_kwargs["message_handler"] = base_handler
+        # Rebind the task-status notification binding so it routes to the clone.
+        new_client._session_kwargs["notification_bindings"] = [
+            new_client._task_status_binding()
+        ]
+
+        new_client.name += f":{secrets.token_hex(2)}"
+
+        return new_client
+
+    @asynccontextmanager
+    async def _context_manager(self):
+        with catch(get_catch_handlers()):
+            async with self.transport.connect_session(
+                **self._session_kwargs
+            ) as session:
+                self._session_state.session = session
+                # Initialize the session if auto_initialize is enabled
+                try:
+                    if self.auto_initialize:
+                        await self._negotiate()
+                    yield
+                except anyio.ClosedResourceError as e:
+                    raise RuntimeError("Server session was closed unexpectedly") from e
+                finally:
+                    self._reset_session_state()
+
+    async def _negotiate(
+        self,
+        timeout: datetime.timedelta | float | int | None = None,
+    ) -> None:
+        """Run the connect-time protocol negotiation dictated by ``self.mode``.
+
+        - ``"legacy"``: today's initialize handshake (populates ``initialize_result``).
+        - ``"auto"``: probe ``server/discover`` at the newest modern version and adopt it,
+          denylist-falling-back to the initialize handshake for handshake-era servers.
+        - a modern version string: adopt that version directly (from ``prior_discover`` if
+          supplied, else a synthesized minimal ``DiscoverResult``).
+
+        Idempotent: once the session has a negotiated protocol version, this is a no-op.
+        """
+        if self.session.protocol_version is not None:
+            # Already negotiated (e.g. a manual initialize() call before context entry).
+            if self.session.initialize_result is not None:
+                self._session_state.initialize_result = self.session.initialize_result
+            return
+
+        if timeout is None:
+            timeout = self._init_timeout
+        else:
+            timeout = normalize_timeout_to_seconds(timeout)
+
+        try:
+            with anyio.fail_after(timeout):
+                if self.mode == "legacy":
+                    self._session_state.initialize_result = (
+                        await self.session.initialize()
+                    )
+                elif self.mode == "auto":
+                    await negotiate_auto(self.session)
+                    # auto may have fallen back to the legacy handshake; surface its
+                    # InitializeResult through the existing public property when so.
+                    self._session_state.initialize_result = (
+                        self.session.initialize_result
+                    )
+                else:
+                    self.session.adopt(
+                        self._prior_discover or _synthesize_discover(self.mode)
+                    )
+        except TimeoutError as e:
+            raise RuntimeError("Failed to initialize server session") from e
+
+    async def initialize(
+        self,
+        timeout: datetime.timedelta | float | int | None = None,
+    ) -> mcp_types.InitializeResult:
+        """Send an initialize request to the server.
+
+        This method performs the MCP initialization handshake with the server,
+        exchanging capabilities and server information. It is idempotent - calling
+        it multiple times returns the cached result from the first call.
+
+        The initialization happens automatically when entering the client context
+        manager unless `auto_initialize=False` was set during client construction.
+        Manual calls to this method are only needed when auto-initialization is disabled.
+
+        With `mode="auto"` or a pinned modern version, connect-time negotiation may adopt
+        the modern `server/discover` era, which has no `InitializeResult`; in that case
+        this method raises. Read `protocol_version` / `server_capabilities` instead, or use
+        `mode="legacy"` (the default) when you need the handshake result.
+
+        Args:
+            timeout: Optional timeout for the initialization request (seconds or timedelta).
+                If None, uses the client's init_timeout setting.
+
+        Returns:
+            InitializeResult: The server's initialization response containing server info,
+                capabilities, protocol version, and optional instructions.
+
+        Raises:
+            RuntimeError: If the client is not connected, initialization times out, or the
+                negotiated era carries no `InitializeResult` (a modern `discover` connection).
+
+        Example:
+            ```python
+            # With auto-initialization disabled
+            client = Client(server, auto_initialize=False)
+            async with client:
+                result = await client.initialize()
+                print(f"Server: {result.server_info.name}")
+                print(f"Instructions: {result.instructions}")
+            ```
+        """
+
+        if self.initialize_result is not None:
+            return self.initialize_result
+
+        await self._negotiate(timeout=timeout)
+
+        if self.initialize_result is None:
+            raise RuntimeError(
+                "The client negotiated a modern protocol era (server/discover), which has "
+                "no InitializeResult. Read client.protocol_version / client.server_capabilities "
+                "instead, or construct the client with mode='legacy'."
+            )
+        return self.initialize_result
+
+    async def __aenter__(self):
+        return await self._connect()
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self._disconnect()
+
+    async def _connect(self):
+        """
+        Establish or reuse a session connection.
+
+        This method implements the reentrant context manager pattern:
+        - First call: Creates background session task and waits for it to be ready
+        - Subsequent calls: Increments reference counter and reuses existing session
+        - All operations protected by _context_lock to prevent race conditions
+
+        The critical fix: Events are only created when starting a new session,
+        never reset outside the lock, preventing the deadlock scenario where
+        tasks wait on events that get replaced by other tasks.
+        """
+        # ensure only one session is running at a time to avoid race conditions
+        async with self._session_state.lock:
+            need_to_start = (
+                self._session_state.session_task is None
+                or self._session_state.session_task.done()
+            )
+
+            if need_to_start:
+                if self._session_state.nesting_counter != 0:
+                    raise RuntimeError(
+                        f"Internal error: nesting counter should be 0 when starting new session, got {self._session_state.nesting_counter}"
+                    )
+                self._session_state.stop_event = anyio.Event()
+                self._session_state.ready_event = anyio.Event()
+                self._session_state.session_task = asyncio.create_task(
+                    self._session_runner()
+                )
+                try:
+                    await self._session_state.ready_event.wait()
+                except asyncio.CancelledError:
+                    # Cancellation during initial connection startup can leave the
+                    # background session task running because __aexit__ is never invoked
+                    # when __aenter__ is cancelled. Since we hold the session lock here
+                    # and we know we started the session task, it's safe to tear it down
+                    # without impacting other active contexts.
+                    #
+                    # Note: session_task is an asyncio.Task (not anyio) because it needs
+                    # to outlive individual context manager scopes - anyio's structured
+                    # concurrency doesn't allow tasks to escape their task group.
+                    session_task = self._session_state.session_task
+                    if session_task is not None:
+                        # Request a graceful stop if the runner has already reached
+                        # its stop_event wait.
+                        self._session_state.stop_event.set()
+                        session_task.cancel()
+                        with anyio.CancelScope(shield=True):
+                            with anyio.move_on_after(3):
+                                try:
+                                    await session_task
+                                except asyncio.CancelledError:
+                                    pass
+                                except Exception as e:
+                                    logger.debug(
+                                        f"Error during cancelled session cleanup: {e}"
+                                    )
+
+                    # Reset session state so future callers can reconnect cleanly.
+                    self._reset_session_state(full=True)
+
+                    with anyio.CancelScope(shield=True):
+                        with anyio.move_on_after(3):
+                            try:
+                                await self.transport.close()
+                            except Exception as e:
+                                logger.debug(
+                                    f"Error closing transport after cancellation: {e}"
+                                )
+
+                    raise
+
+                if self._session_state.session_task.done():
+                    exception = self._session_state.session_task.exception()
+                    if exception is None:
+                        raise RuntimeError(
+                            "Session task completed without exception but connection failed"
+                        )
+                    # Preserve specific exception types that clients may want to handle
+                    if isinstance(exception, httpx.HTTPStatusError | MCPError):
+                        raise exception
+                    raise RuntimeError(
+                        f"Client failed to connect: {exception}"
+                    ) from exception
+
+            self._session_state.nesting_counter += 1
+
+        return self
+
+    async def _disconnect(self, force: bool = False):
+        """
+        Disconnect from session using reference counting.
+
+        This method implements proper cleanup for reentrant context managers:
+        - Decrements reference counter for normal exits
+        - Only stops session when counter reaches 0 (no more active contexts)
+        - Force flag bypasses reference counting for immediate shutdown
+        - Session cleanup happens inside the lock to ensure atomicity
+
+        Key fix: Removed the problematic "Reset for future reconnects" logic
+        that was resetting events outside the lock, causing race conditions.
+        Event recreation now happens only in _connect() when actually needed.
+        """
+        # ensure only one session is running at a time to avoid race conditions
+        async with self._session_state.lock:
+            # if we are forcing a disconnect, reset the nesting counter
+            if force:
+                self._session_state.nesting_counter = 0
+
+            # otherwise decrement to check if we are done nesting
+            else:
+                self._session_state.nesting_counter = max(
+                    0, self._session_state.nesting_counter - 1
+                )
+
+            # if we are still nested, return
+            if self._session_state.nesting_counter > 0:
+                return
+
+            # stop the active session
+            if self._session_state.session_task is None:
+                return
+            session_task = self._session_state.session_task
+            self._session_state.stop_event.set()
+            # Wait (bounded) for the runner to unwind gracefully. If it
+            # overruns — e.g. the transport's termination POST is blocked on
+            # a stale HTTP keep-alive connection — cancel the background
+            # task so transport resources (httpx connections, subprocess
+            # pipes) are actually released instead of leaking into the
+            # event loop. Force paths additionally shield the wait so an
+            # outer cancellation can't abandon cleanup half-done.
+            try:
+                with anyio.CancelScope(shield=force):
+                    with anyio.move_on_after(self._disconnect_timeout):
+                        with suppress(asyncio.CancelledError):
+                            await session_task
+            finally:
+                if not session_task.done():
+                    session_task.cancel()
+                    with anyio.CancelScope(shield=True):
+                        with anyio.move_on_after(self._disconnect_timeout):
+                            with suppress(Exception):
+                                await session_task
+                self._session_state.session_task = None
+
+    async def _session_runner(self):
+        """
+        Background task that manages the actual session lifecycle.
+
+        This task runs in the background and:
+        1. Establishes the transport connection via _context_manager()
+        2. Signals that the session is ready via _ready_event.set()
+        3. Waits for disconnect signal via _stop_event.wait()
+        4. Ensures _ready_event is always set, even on failures
+
+        The simplified error handling (compared to the original) removes
+        redundant exception re-raising while ensuring waiting tasks are
+        always unblocked via the finally block.
+        """
+        try:
+            async with AsyncExitStack() as stack:
+                await stack.enter_async_context(self._context_manager())
+                # Session/context is now ready
+                self._session_state.ready_event.set()
+                # Wait until disconnect/stop is requested
+                await self._session_state.stop_event.wait()
+        finally:
+            # Ensure ready event is set even if context manager entry fails
+            self._session_state.ready_event.set()
+
+    async def _await_with_session_monitoring(
+        self, coro: Coroutine[Any, Any, ResultT]
+    ) -> ResultT:
+        """Await a coroutine while monitoring the session task for errors.
+
+        When using HTTP transports, server errors (4xx/5xx) are raised in the
+        background session task, not in the coroutine waiting for a response.
+        This causes the client to hang indefinitely since the response never
+        arrives. This method monitors the session task and propagates any
+        exceptions that occur, preventing the client from hanging.
+
+        Args:
+            coro: The coroutine to await (typically a session method call)
+
+        Returns:
+            The result of the coroutine
+
+        Raises:
+            The exception from the session task if it fails, or RuntimeError
+            if the session task completes unexpectedly without an exception.
+        """
+        session_task = self._session_state.session_task
+
+        # If no session task, just await directly
+        if session_task is None:
+            return await coro
+
+        # If session task already failed, raise immediately
+        if session_task.done():
+            # Close the coroutine to avoid "was never awaited" warning
+            coro.close()
+            exc = session_task.exception()
+            if exc:
+                raise exc
+            raise RuntimeError("Session task completed unexpectedly")
+
+        # Create task for our call
+        call_task = asyncio.create_task(coro)
+
+        try:
+            done, _ = await asyncio.wait(
+                {call_task, session_task},
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+
+            if session_task in done:
+                # Session task completed (likely errored) before our call finished
+                call_task.cancel()
+                with anyio.CancelScope(shield=True), suppress(asyncio.CancelledError):
+                    await call_task
+
+                # Raise the session task exception
+                exc = session_task.exception()
+                if exc:
+                    raise exc
+                raise RuntimeError("Session task completed unexpectedly")
+
+            # Our call completed first - get the result
+            return call_task.result()
+        except asyncio.CancelledError:
+            call_task.cancel()
+            with anyio.CancelScope(shield=True), suppress(asyncio.CancelledError):
+                await call_task
+            raise
+
+    async def _cached_fetch(
+        self,
+        method: str,
+        *,
+        cursor: str | None,
+        cache_mode: CacheMode,
+        send: Callable[[], Coroutine[Any, Any, CacheableT]],
+        absorb: Callable[[CacheableT], CacheableT] | None = None,
+    ) -> CacheableT:
+        """Serve one of the cacheable list verbs through the response cache.
+
+        Mirrors the SDK Client's `_cached_fetch`: cursorless `use` calls are served
+        from (and stored to) the cache; a cursor page skips the cache (and evicts on
+        an expired-cursor `INVALID_PARAMS`, which signals the listing changed). The
+        cache is inert on legacy connections because the SDK cache reads no TTL/scope
+        hints below the modern era, so nothing is ever stored to serve.
+
+        `absorb` (tools/list only) re-applies the session's derived per-tool state to a
+        served cache hit, since a hit skips `session.list_tools`.
+        """
+        cache = self._response_cache
+        if cache is None or cache_mode == "bypass":
+            return await send()
+        # A closed (or never-entered) client must raise, never serve cached entries.
+        _ = self.session
+        if cursor is not None:
+            # Continuation pages skip the cache; an expired cursor means the listing
+            # changed, so evict (spec SHOULD) and re-raise.
+            try:
+                return await send()
+            except MCPError as e:
+                if e.code == mcp_types.INVALID_PARAMS:
+                    await cache.evict_method(method)
+                raise
+        if cache_mode == "use" and (hit := await cache.read(method, "")) is not None:
+            served = cast(CacheableT, hit)
+            return served if absorb is None else absorb(served)
+        gen = cache.capture(method, "")
+        result = await send()
+        await cache.write(method, "", result, gen, cache_mode)
+        return result
+
+    async def _drive_input_required(
+        self,
+        first: ResultT | mcp_types.InputRequiredResult,
+        retry: Callable[
+            [mcp_types.InputResponses | None, str | None],
+            Coroutine[Any, Any, ResultT | mcp_types.InputRequiredResult],
+        ],
+    ) -> ResultT:
+        """Resolve a SEP-2322 `InputRequiredResult` to its terminal result.
+
+        A 2026-era server may answer `tools/call` / `prompts/get` / `resources/read`
+        with an `InputRequiredResult` carrying embedded sampling / elicitation / roots
+        requests. This hands that off to the SDK's `run_input_required_driver`, which
+        dispatches each embedded request through the *same* callback table that serves
+        legacy server-initiated RPCs (`session.dispatch_input_request`) and retries the
+        original call until it returns a terminal result.
+
+        Legacy servers never emit `InputRequiredResult`, so a terminal `first` passes
+        straight through untouched — zero behavior change for pre-2026 servers.
+        """
+        if not isinstance(first, mcp_types.InputRequiredResult):
+            return first
+        session = self.session
+
+        async def dispatch(
+            key: str, req: mcp_types.InputRequest
+        ) -> mcp_types.InputResponse | mcp_types.ErrorData:
+            ctx = ClientRequestContext(
+                session=session,
+                request_id=key,
+                meta=req.params.meta if req.params else None,
+            )
+            return await session.dispatch_input_request(ctx, req)
+
+        return await run_input_required_driver(
+            first,
+            dispatch=dispatch,
+            retry=retry,
+            max_rounds=self.input_required_max_rounds,
+        )
+
+    def _handle_task_status_notification(
+        self, notification: TaskStatusNotification
+    ) -> None:
+        """Route task status notification to appropriate Task object.
+
+        Called when notifications/tasks/status is received from server.
+        Updates Task object's cache and triggers events/callbacks.
+        """
+        self._handle_task_status_params(notification.params)
+
+    def _handle_task_status_params(self, params: TaskStatusNotificationParams) -> None:
+        """Route task status notification params to the matching Task object."""
+        task_id = params.task_id
+        if not task_id:
+            return
+
+        # Look up task in registry (weakref)
+        task_ref = self._task_registry.get(task_id)
+        if task_ref:
+            task = task_ref()  # Dereference weakref
+            if task:
+                # Convert notification params to GetTaskResult (they share the same fields via Task)
+                status = GetTaskResult.model_validate(params.model_dump())
+                task._handle_status_notification(status)
+
+    def _task_status_binding(self) -> NotificationBinding[TaskStatusNotificationParams]:
+        """Build a binding routing `notifications/tasks/status` to Task objects.
+
+        SDK v2 drops notifications whose method is absent from the negotiated
+        version's core tables before they reach the message_handler; a binding is
+        the supported channel for observing such vendor notifications.
+        """
+        client_ref = weakref.ref(self)
+
+        async def _handler(params: TaskStatusNotificationParams) -> None:
+            client = client_ref()
+            if client is not None:
+                client._handle_task_status_params(params)
+
+        return NotificationBinding(
+            method="notifications/tasks/status",
+            params_type=TaskStatusNotificationParams,
+            handler=_handler,
+        )
+
+    async def close(self):
+        await self._disconnect(force=True)
+        await self.transport.close()
+
+    # --- MCP Client Methods ---
+
+    async def ping(self) -> bool:
+        """Send a ping request."""
+        result = await self._await_with_session_monitoring(self.session.send_ping())
+        return isinstance(result, mcp_types.EmptyResult)
+
+    async def cancel(
+        self,
+        request_id: str | int,
+        reason: str | None = None,
+    ) -> None:
+        """Send a cancellation notification for an in-progress request."""
+        notification = mcp_types.CancelledNotification(
+            method="notifications/cancelled",
+            params=mcp_types.CancelledNotificationParams(
+                request_id=request_id,
+                reason=reason,
+            ),
+        )
+        await self.session.send_notification(notification)
+
+    async def progress(
+        self,
+        progress_token: str | int,
+        progress: float,
+        total: float | None = None,
+        message: str | None = None,
+    ) -> None:
+        """Send a progress notification."""
+        # Deprecated upstream in SDK v2 but deliberately kept per compat directive;
+        # removed with the multi-round-trip follow-up.
+        await self.session.send_progress_notification(  # ty: ignore[deprecated]
+            progress_token, progress, total, message
+        )
+
+    async def set_logging_level(self, level: mcp_types.LoggingLevel) -> None:
+        """Send a logging/setLevel request."""
+        # Deprecated upstream in SDK v2 but deliberately kept per compat directive;
+        # removed with the multi-round-trip follow-up.
+        await self._await_with_session_monitoring(
+            self.session.set_logging_level(level)  # ty: ignore[deprecated]
+        )
+
+    async def send_roots_list_changed(self) -> None:
+        """Send a roots/list_changed notification."""
+        # Deprecated upstream in SDK v2 but deliberately kept per compat directive;
+        # removed with the multi-round-trip follow-up.
+        await self.session.send_roots_list_changed()  # ty: ignore[deprecated]
+
+    # --- Completion ---
+
+    async def complete_mcp(
+        self,
+        ref: mcp_types.ResourceTemplateReference | mcp_types.PromptReference,
+        argument: dict[str, str],
+        context_arguments: dict[str, Any] | None = None,
+    ) -> mcp_types.CompleteResult:
+        """Send a completion request and return the complete MCP protocol result.
+
+        Args:
+            ref (mcp_types.ResourceTemplateReference | mcp_types.PromptReference): The reference to complete.
+            argument (dict[str, str]): Arguments to pass to the completion request.
+            context_arguments (dict[str, Any] | None, optional): Optional context arguments to
+                include with the completion request. Defaults to None.
+
+        Returns:
+            mcp_types.CompleteResult: The complete response object from the protocol,
+                containing the completion and any additional metadata.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+            MCPError: If the request results in a TimeoutError | JSONRPCError
+        """
+        logger.debug(f"[{self.name}] called complete: {ref}")
+
+        result = await self._await_with_session_monitoring(
+            self.session.complete(
+                ref=ref, argument=argument, context_arguments=context_arguments
+            )
+        )
+        return result
+
+    async def complete(
+        self,
+        ref: mcp_types.ResourceTemplateReference | mcp_types.PromptReference,
+        argument: dict[str, str],
+        context_arguments: dict[str, Any] | None = None,
+    ) -> mcp_types.Completion:
+        """Send a completion request to the server.
+
+        Args:
+            ref (mcp_types.ResourceTemplateReference | mcp_types.PromptReference): The reference to complete.
+            argument (dict[str, str]): Arguments to pass to the completion request.
+            context_arguments (dict[str, Any] | None, optional): Optional context arguments to
+                include with the completion request. Defaults to None.
+
+        Returns:
+            mcp_types.Completion: The completion object.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+            MCPError: If the request results in a TimeoutError | JSONRPCError
+        """
+        result = await self.complete_mcp(
+            ref=ref, argument=argument, context_arguments=context_arguments
+        )
+        return result.completion
+
+    @classmethod
+    def generate_name(cls, name: str | None = None) -> str:
+        class_name = cls.__name__
+        if name is None:
+            return f"{class_name}-{secrets.token_hex(2)}"
+        else:
+            return f"{class_name}-{name}-{secrets.token_hex(2)}"
diff --git a/fastmcp_slim/fastmcp/client/dependencies.py b/fastmcp_slim/fastmcp/client/dependencies.py
new file mode 100644
index 0000000..54faaef
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/dependencies.py
@@ -0,0 +1,20 @@
+"""Client-side dependency helpers."""
+
+
+def get_http_headers(
+    include_all: bool = False,
+    include: set[str] | None = None,
+) -> dict[str, str]:
+    """Return HTTP headers from an ambient server request, when available.
+
+    The standalone client package has no server request context. When the full
+    FastMCP package is installed, delegate to its request-aware implementation.
+    """
+    try:
+        from fastmcp.server.dependencies import (
+            get_http_headers as get_server_http_headers,
+        )
+    except ImportError:
+        return {}
+
+    return get_server_http_headers(include_all=include_all, include=include)
diff --git a/fastmcp_slim/fastmcp/client/elicitation.py b/fastmcp_slim/fastmcp/client/elicitation.py
new file mode 100644
index 0000000..2b9ce5d
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/elicitation.py
@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any, Generic, TypeAlias
+
+import mcp_types
+from mcp import ClientSession
+from mcp.client.session import ClientRequestContext, ElicitationFnT
+from mcp_types import ElicitRequestFormParams, ElicitRequestParams
+from mcp_types import ElicitResult as MCPElicitResult
+from pydantic_core import to_jsonable_python
+from typing_extensions import TypeVar
+
+from fastmcp.client._sdk_context_shim import LifespanContextT, RequestContext
+from fastmcp.utilities.json_schema_type import json_schema_to_type
+
+__all__ = ["ElicitRequestParams", "ElicitResult", "ElicitationHandler"]
+
+T = TypeVar("T", default=Any)
+
+
+class ElicitResult(MCPElicitResult, Generic[T]):
+    content: T | None = None
+
+
+ElicitationHandler: TypeAlias = Callable[
+    [
+        str,  # message
+        type[T]
+        | None,  # a class for creating a structured response (None for URL elicitation)
+        ElicitRequestParams,
+        RequestContext[ClientSession, LifespanContextT],
+    ],
+    Awaitable[T | dict[str, Any] | ElicitResult[T | dict[str, Any]]],
+]
+
+
+def create_elicitation_callback(
+    elicitation_handler: ElicitationHandler,
+) -> ElicitationFnT:
+    async def _elicitation_handler(
+        context: ClientRequestContext,
+        params: ElicitRequestParams,
+    ) -> MCPElicitResult | mcp_types.ErrorData:
+        try:
+            # requestedSchema only exists on ElicitRequestFormParams, not ElicitRequestURLParams
+            if isinstance(params, ElicitRequestFormParams):
+                if params.requested_schema == {"type": "object", "properties": {}}:
+                    response_type = None
+                else:
+                    response_type = json_schema_to_type(params.requested_schema)
+            else:
+                # URL-based elicitation doesn't have a schema
+                response_type = None
+
+            # The public ElicitationHandler alias is typed against the
+            # subscriptable RequestContext shim; the runtime object is the SDK's
+            # ClientRequestContext, passed through opaquely.
+            result = await elicitation_handler(
+                params.message,
+                response_type,
+                params,
+                context,  # ty: ignore[invalid-argument-type]
+            )
+            # if the user returns data, we assume they've accepted the elicitation
+            if not isinstance(result, ElicitResult):
+                result = ElicitResult(action="accept", content=result)
+            content = to_jsonable_python(result.content)
+            if not isinstance(content, dict | None):
+                # Auto-wrap scalar values for ScalarElicitationType schemas
+                # (single "value" property). This lets handlers return T directly
+                # for ctx.elicit("msg", str/int/float/bool).
+                if isinstance(params, ElicitRequestFormParams) and set(
+                    params.requested_schema.get("properties", {}).keys()
+                ) == {"value"}:
+                    content = {"value": content}
+                else:
+                    raise ValueError(
+                        "Elicitation responses must be serializable as a JSON object (dict). Received: "
+                        f"{result.content!r}"
+                    )
+            return MCPElicitResult(
+                _meta=result.meta,  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
+                action=result.action,
+                content=content,
+            )
+
+        except Exception as e:
+            return mcp_types.ErrorData(
+                code=mcp_types.INTERNAL_ERROR,
+                message=str(e),
+            )
+
+    return _elicitation_handler
diff --git a/fastmcp_slim/fastmcp/client/logging.py b/fastmcp_slim/fastmcp/client/logging.py
new file mode 100644
index 0000000..b9e4aef
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/logging.py
@@ -0,0 +1,54 @@
+from collections.abc import Awaitable, Callable
+from logging import Logger
+from typing import TypeAlias
+
+from mcp.client.session import LoggingFnT
+from mcp_types import LoggingMessageNotificationParams
+
+from fastmcp.utilities.logging import get_logger
+
+logger: Logger = get_logger(name=__name__)
+from_server_logger: Logger = get_logger(name="fastmcp.client.from_server")
+
+LogMessage: TypeAlias = LoggingMessageNotificationParams
+LogHandler: TypeAlias = Callable[[LogMessage], Awaitable[None]]
+
+
+async def default_log_handler(message: LogMessage) -> None:
+    """Default handler that properly routes server log messages to appropriate log levels."""
+    # data can be any JSON-serializable type, not just a dict
+    data = message.data
+
+    # Map MCP log levels to Python logging levels
+    level_map = {
+        "debug": from_server_logger.debug,
+        "info": from_server_logger.info,
+        "notice": from_server_logger.info,  # Python doesn't have 'notice', map to info
+        "warning": from_server_logger.warning,
+        "error": from_server_logger.error,
+        "critical": from_server_logger.critical,
+        "alert": from_server_logger.critical,  # Map alert to critical
+        "emergency": from_server_logger.critical,  # Map emergency to critical
+    }
+
+    # Get the appropriate logging function based on the message level
+    log_fn = level_map.get(message.level.lower(), logger.info)
+
+    # Include logger name if available
+    msg_prefix: str = f"Received {message.level.upper()} from server"
+
+    if message.logger:
+        msg_prefix += f" ({message.logger})"
+
+    # Log with appropriate level and data
+    log_fn(msg=f"{msg_prefix}: {data}")
+
+
+def create_log_callback(handler: LogHandler | None = None) -> LoggingFnT:
+    if handler is None:
+        handler = default_log_handler
+
+    async def log_callback(params: LoggingMessageNotificationParams) -> None:
+        await handler(params)
+
+    return log_callback
diff --git a/fastmcp_slim/fastmcp/client/messages.py b/fastmcp_slim/fastmcp/client/messages.py
new file mode 100644
index 0000000..7183a8e
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/messages.py
@@ -0,0 +1,131 @@
+from typing import TypeAlias
+
+import mcp_types
+from mcp.client.session import MessageHandlerFnT
+from mcp.shared.session import RequestResponder
+
+Message: TypeAlias = (
+    RequestResponder[mcp_types.ServerRequest, mcp_types.ClientResult]
+    | mcp_types.ServerNotification
+    | Exception
+)
+
+MessageHandlerT: TypeAlias = MessageHandlerFnT
+
+
+class MessageHandler:
+    """
+    This class is used to handle MCP messages sent to the client. It is used to handle all messages,
+    requests, notifications, and exceptions. Users can override any of the hooks
+    """
+
+    async def __call__(
+        self,
+        message: RequestResponder[mcp_types.ServerRequest, mcp_types.ClientResult]
+        | mcp_types.ServerNotification
+        | Exception,
+    ) -> None:
+        return await self.dispatch(message)
+
+    async def dispatch(self, message: Message) -> None:
+        # handle all messages
+        await self.on_message(message)
+
+        # SDK v2 delivers server-to-client requests wrapped in a
+        # RequestResponder (with the request unwrapped on `.request`) and
+        # notifications unwrapped (the monolith notification model itself, no
+        # `.root` wrapper). `ServerNotification`/`ServerRequest` are UnionTypes,
+        # so they can't appear in class match patterns — branch on the concrete
+        # models directly.
+        if isinstance(message, RequestResponder):
+            # handle all requests
+            # ty doesn't narrow the generic RequestResponder cleanly here.
+            await self.on_request(message)  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+
+            # handle specific requests
+            request = message.request
+            match request:
+                case mcp_types.PingRequest():
+                    await self.on_ping(request)
+                case mcp_types.ListRootsRequest():
+                    await self.on_list_roots(request)
+                case mcp_types.CreateMessageRequest():
+                    await self.on_create_message(request)
+
+        elif isinstance(message, Exception):
+            await self.on_exception(message)
+
+        else:
+            # notifications (unwrapped monolith models)
+            await self.on_notification(message)
+
+            # handle specific notifications
+            match message:
+                case mcp_types.CancelledNotification():
+                    await self.on_cancelled(message)
+                case mcp_types.ProgressNotification():
+                    await self.on_progress(message)
+                case mcp_types.LoggingMessageNotification():
+                    await self.on_logging_message(message)
+                case mcp_types.ToolListChangedNotification():
+                    await self.on_tool_list_changed(message)
+                case mcp_types.ResourceListChangedNotification():
+                    await self.on_resource_list_changed(message)
+                case mcp_types.PromptListChangedNotification():
+                    await self.on_prompt_list_changed(message)
+                case mcp_types.ResourceUpdatedNotification():
+                    await self.on_resource_updated(message)
+
+    async def on_message(self, message: Message) -> None:
+        pass
+
+    async def on_request(
+        self, message: RequestResponder[mcp_types.ServerRequest, mcp_types.ClientResult]
+    ) -> None:
+        pass
+
+    async def on_ping(self, message: mcp_types.PingRequest) -> None:
+        pass
+
+    async def on_list_roots(self, message: mcp_types.ListRootsRequest) -> None:
+        pass
+
+    async def on_create_message(self, message: mcp_types.CreateMessageRequest) -> None:
+        pass
+
+    async def on_notification(self, message: mcp_types.ServerNotification) -> None:
+        pass
+
+    async def on_exception(self, message: Exception) -> None:
+        pass
+
+    async def on_progress(self, message: mcp_types.ProgressNotification) -> None:
+        pass
+
+    async def on_logging_message(
+        self, message: mcp_types.LoggingMessageNotification
+    ) -> None:
+        pass
+
+    async def on_tool_list_changed(
+        self, message: mcp_types.ToolListChangedNotification
+    ) -> None:
+        pass
+
+    async def on_resource_list_changed(
+        self, message: mcp_types.ResourceListChangedNotification
+    ) -> None:
+        pass
+
+    async def on_prompt_list_changed(
+        self, message: mcp_types.PromptListChangedNotification
+    ) -> None:
+        pass
+
+    async def on_resource_updated(
+        self, message: mcp_types.ResourceUpdatedNotification
+    ) -> None:
+        pass
+
+    async def on_cancelled(self, message: mcp_types.CancelledNotification) -> None:
+        pass
diff --git a/fastmcp_slim/fastmcp/client/mixins/__init__.py b/fastmcp_slim/fastmcp/client/mixins/__init__.py
new file mode 100644
index 0000000..323e209
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/mixins/__init__.py
@@ -0,0 +1,13 @@
+"""Client mixins for FastMCP."""
+
+from fastmcp.client.mixins.prompts import ClientPromptsMixin
+from fastmcp.client.mixins.resources import ClientResourcesMixin
+from fastmcp.client.mixins.task_management import ClientTaskManagementMixin
+from fastmcp.client.mixins.tools import ClientToolsMixin
+
+__all__ = [
+    "ClientPromptsMixin",
+    "ClientResourcesMixin",
+    "ClientTaskManagementMixin",
+    "ClientToolsMixin",
+]
diff --git a/fastmcp_slim/fastmcp/client/mixins/prompts.py b/fastmcp_slim/fastmcp/client/mixins/prompts.py
new file mode 100644
index 0000000..fba8ed3
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/mixins/prompts.py
@@ -0,0 +1,347 @@
+"""Prompt-related methods for FastMCP Client."""
+
+from __future__ import annotations
+
+import uuid
+import weakref
+from typing import TYPE_CHECKING, Any, Literal, cast, overload
+
+import mcp_types
+import pydantic_core
+from mcp.client.caching import CacheMode
+from pydantic import RootModel
+
+if TYPE_CHECKING:
+    from fastmcp.client.client import Client
+
+from fastmcp.client.tasks import PromptTask
+from fastmcp.client.telemetry import client_span
+from fastmcp.telemetry import inject_trace_context
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+AUTO_PAGINATION_MAX_PAGES = 250
+
+# Type alias for task response union (SEP-1686 graceful degradation)
+PromptTaskResponseUnion = RootModel[
+    mcp_types.CreateTaskResult | mcp_types.GetPromptResult
+]
+
+
+class ClientPromptsMixin:
+    """Mixin providing prompt-related methods for Client."""
+
+    # --- Prompts ---
+
+    async def list_prompts_mcp(
+        self: Client,
+        *,
+        cursor: str | None = None,
+        cache_mode: CacheMode = "use",
+    ) -> mcp_types.ListPromptsResult:
+        """Send a prompts/list request and return the complete MCP protocol result.
+
+        Args:
+            cursor: Optional pagination cursor from a previous request's nextCursor.
+            cache_mode: Response-cache behavior (only active with a cache and a modern
+                connection). See `list_tools_mcp`.
+
+        Returns:
+            mcp_types.ListPromptsResult: The complete response object from the protocol,
+                containing the list of prompts and any additional metadata.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+            MCPError: If the request results in a TimeoutError | JSONRPCError
+        """
+        with client_span(
+            "prompts/list",
+            "prompts/list",
+            "",
+            session_id=self.transport.get_session_id(),
+        ):
+            logger.debug(f"[{self.name}] called list_prompts")
+
+            params = (
+                mcp_types.PaginatedRequestParams(cursor=cursor)
+                if cursor is not None
+                else None
+            )
+
+            async def _send() -> mcp_types.ListPromptsResult:
+                return await self._await_with_session_monitoring(
+                    self.session.list_prompts(params=params)
+                )
+
+            return await self._cached_fetch(
+                "prompts/list", cursor=cursor, cache_mode=cache_mode, send=_send
+            )
+
+    async def list_prompts(
+        self: Client,
+        max_pages: int = AUTO_PAGINATION_MAX_PAGES,
+    ) -> list[mcp_types.Prompt]:
+        """Retrieve all prompts available on the server.
+
+        This method automatically fetches all pages if the server paginates results,
+        returning the complete list. For manual pagination control (e.g., to handle
+        large result sets incrementally), use list_prompts_mcp() with the cursor parameter.
+
+        Args:
+            max_pages: Maximum number of pages to fetch before raising. Defaults to 250.
+
+        Returns:
+            list[mcp_types.Prompt]: A list of all Prompt objects.
+
+        Raises:
+            RuntimeError: If the page limit is reached before pagination completes.
+            MCPError: If the request results in a TimeoutError | JSONRPCError
+        """
+        all_prompts: list[mcp_types.Prompt] = []
+        cursor: str | None = None
+        seen_cursors: set[str] = set()
+
+        for _ in range(max_pages):
+            result = await self.list_prompts_mcp(cursor=cursor)
+            all_prompts.extend(result.prompts)
+            if not result.next_cursor:
+                break
+            if result.next_cursor in seen_cursors:
+                logger.warning(
+                    f"[{self.name}] Server returned duplicate pagination cursor"
+                    f" {result.next_cursor!r} for list_prompts; stopping pagination"
+                )
+                break
+            seen_cursors.add(result.next_cursor)
+            cursor = result.next_cursor
+        else:
+            raise RuntimeError(
+                f"[{self.name}] Reached auto-pagination limit"
+                f" ({max_pages} pages) for list_prompts."
+                " Use list_prompts_mcp() with cursor for manual pagination,"
+                " or increase max_pages."
+            )
+
+        return all_prompts
+
+    # --- Prompt ---
+    async def get_prompt_mcp(
+        self: Client,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        meta: dict[str, Any] | None = None,
+    ) -> mcp_types.GetPromptResult:
+        """Send a prompts/get request and return the complete MCP protocol result.
+
+        Args:
+            name (str): The name of the prompt to retrieve.
+            arguments (dict[str, Any] | None, optional): Arguments to pass to the prompt. Defaults to None.
+            meta (dict[str, Any] | None, optional): Request metadata (e.g., for SEP-1686 tasks). Defaults to None.
+
+        Returns:
+            mcp_types.GetPromptResult: The complete response object from the protocol,
+                containing the prompt messages and any additional metadata.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+            MCPError: If the request results in a TimeoutError | JSONRPCError
+        """
+        with client_span(
+            f"prompts/get {name}",
+            "prompts/get",
+            name,
+            session_id=self.transport.get_session_id(),
+            prompt_name=name,
+        ):
+            logger.debug(f"[{self.name}] called get_prompt: {name}")
+
+            # Serialize arguments for MCP protocol - convert non-string values to JSON
+            serialized_arguments: dict[str, str] | None = None
+            if arguments:
+                serialized_arguments = {}
+                for key, value in arguments.items():
+                    if isinstance(value, str):
+                        serialized_arguments[key] = value
+                    else:
+                        # Use pydantic_core.to_json for consistent serialization
+                        serialized_arguments[key] = pydantic_core.to_json(value).decode(
+                            "utf-8"
+                        )
+
+            # Inject trace context into meta for propagation to server
+            propagated_meta = inject_trace_context(meta)
+            request_meta = cast("mcp_types.RequestParamsMeta | None", propagated_meta)
+
+            async def _retry(
+                input_responses: mcp_types.InputResponses | None,
+                request_state: str | None,
+            ) -> mcp_types.GetPromptResult | mcp_types.InputRequiredResult:
+                return await self.session.get_prompt(
+                    name=name,
+                    arguments=serialized_arguments,
+                    meta=request_meta,
+                    input_responses=input_responses,
+                    request_state=request_state,
+                    allow_input_required=True,
+                )
+
+            first = await self._await_with_session_monitoring(_retry(None, None))
+            result = await self._await_with_session_monitoring(
+                self._drive_input_required(first, _retry)
+            )
+            return result
+
+    @overload
+    async def get_prompt(
+        self: Client,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        version: str | None = None,
+        meta: dict[str, Any] | None = None,
+        task: Literal[False] = False,
+    ) -> mcp_types.GetPromptResult: ...
+
+    @overload
+    async def get_prompt(
+        self: Client,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        version: str | None = None,
+        meta: dict[str, Any] | None = None,
+        task: Literal[True],
+        task_id: str | None = None,
+        ttl: int = 60000,
+    ) -> PromptTask: ...
+
+    async def get_prompt(
+        self: Client,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        version: str | None = None,
+        meta: dict[str, Any] | None = None,
+        task: bool = False,
+        task_id: str | None = None,
+        ttl: int = 60000,
+    ) -> mcp_types.GetPromptResult | PromptTask:
+        """Retrieve a rendered prompt message list from the server.
+
+        Args:
+            name (str): The name of the prompt to retrieve.
+            arguments (dict[str, Any] | None, optional): Arguments to pass to the prompt. Defaults to None.
+            version (str | None, optional): Specific prompt version to get. If None, gets highest version.
+            meta (dict[str, Any] | None): Optional request-level metadata.
+            task (bool): If True, execute as background task (SEP-1686). Defaults to False.
+            task_id (str | None): Optional client-provided task ID (auto-generated if not provided).
+            ttl (int): Time to keep results available in milliseconds (default 60s).
+
+        Returns:
+            mcp_types.GetPromptResult | PromptTask: The complete response object if task=False,
+                or a PromptTask object if task=True.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+            MCPError: If the request results in a TimeoutError | JSONRPCError
+        """
+        # Merge version into request-level meta (not arguments)
+        request_meta = dict(meta) if meta else {}
+        if version is not None:
+            request_meta["fastmcp"] = {
+                **request_meta.get("fastmcp", {}),
+                "version": version,
+            }
+
+        if task:
+            return await self._get_prompt_as_task(
+                name, arguments, task_id, ttl, meta=request_meta or None
+            )
+
+        result = await self.get_prompt_mcp(
+            name=name, arguments=arguments, meta=request_meta or None
+        )
+        return result
+
+    async def _get_prompt_as_task(
+        self: Client,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        task_id: str | None = None,
+        ttl: int = 60000,
+        meta: dict[str, Any] | None = None,
+    ) -> PromptTask:
+        """Get a prompt for background execution (SEP-1686).
+
+        Returns a PromptTask object that handles both background and immediate execution.
+
+        Args:
+            name: Prompt name to get
+            arguments: Prompt arguments
+            task_id: Optional client-provided task ID (ignored, for backward compatibility)
+            ttl: Time to keep results available in milliseconds (default 60s)
+            meta: Optional request metadata (e.g., version info)
+
+        Returns:
+            PromptTask: Future-like object for accessing task status and results
+        """
+        # Per SEP-1686 final spec: client sends only ttl, server generates taskId
+        # Inject trace context into meta for propagation to server.
+        # SDK v2: request `_meta` is `RequestParamsMeta` (a TypedDict), not
+        # the old `RequestParams.Meta` nested model.
+        propagated_meta = inject_trace_context(meta)
+        request_meta = cast(
+            "mcp_types.RequestParamsMeta | None",
+            propagated_meta if propagated_meta else None,
+        )
+
+        # Serialize arguments for MCP protocol
+        serialized_arguments: dict[str, str] | None = None
+        if arguments:
+            serialized_arguments = {}
+            for key, value in arguments.items():
+                if isinstance(value, str):
+                    serialized_arguments[key] = value
+                else:
+                    serialized_arguments[key] = pydantic_core.to_json(value).decode(
+                        "utf-8"
+                    )
+
+        # SDK v2: GetPromptRequestParams has no `task` field, so this request
+        # cannot carry task metadata over the wire and the server graceful-
+        # degrades to immediate execution (sdk-feedback #3). `ttl` is retained on
+        # the public API but has no wire representation here.
+        request = mcp_types.GetPromptRequest(
+            params=mcp_types.GetPromptRequestParams(
+                name=name,
+                arguments=serialized_arguments,
+                _meta=request_meta,  # type: ignore[unknown-argument]  # pydantic alias
+            )
+        )
+
+        # Server returns CreateTaskResult (task accepted) or GetPromptResult (graceful degradation)
+        wrapped_result = await self._await_with_session_monitoring(
+            self.session.send_request(
+                request=request,  # type: ignore[arg-type]
+                result_type=PromptTaskResponseUnion,
+            )
+        )
+        raw_result = wrapped_result.root
+
+        if isinstance(raw_result, mcp_types.CreateTaskResult):
+            # Task was accepted - extract task info from CreateTaskResult
+            server_task_id = raw_result.task.task_id
+            self._submitted_task_ids.add(server_task_id)
+
+            task_obj = PromptTask(
+                self, server_task_id, prompt_name=name, immediate_result=None
+            )
+            self._task_registry[server_task_id] = weakref.ref(task_obj)
+            return task_obj
+        else:
+            # Graceful degradation - server returned GetPromptResult
+            synthetic_task_id = task_id or str(uuid.uuid4())
+            return PromptTask(
+                self, synthetic_task_id, prompt_name=name, immediate_result=raw_result
+            )
diff --git a/fastmcp_slim/fastmcp/client/mixins/resources.py b/fastmcp_slim/fastmcp/client/mixins/resources.py
new file mode 100644
index 0000000..7bbbd84
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/mixins/resources.py
@@ -0,0 +1,423 @@
+"""Resource-related methods for FastMCP Client."""
+
+from __future__ import annotations
+
+import uuid
+import weakref
+from typing import TYPE_CHECKING, Any, Literal, cast, overload
+
+import mcp_types
+from mcp.client.caching import CacheMode
+from pydantic import AnyUrl, RootModel
+
+if TYPE_CHECKING:
+    from fastmcp.client.client import Client
+
+from fastmcp.client.tasks import ResourceTask
+from fastmcp.client.telemetry import client_span
+from fastmcp.telemetry import inject_trace_context
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+AUTO_PAGINATION_MAX_PAGES = 250
+
+# Type alias for task response union (SEP-1686 graceful degradation)
+ResourceTaskResponseUnion = RootModel[
+    mcp_types.CreateTaskResult | mcp_types.ReadResourceResult
+]
+
+
+class ClientResourcesMixin:
+    """Mixin providing resource-related methods for Client."""
+
+    # --- Resources ---
+
+    async def list_resources_mcp(
+        self: Client,
+        *,
+        cursor: str | None = None,
+        cache_mode: CacheMode = "use",
+    ) -> mcp_types.ListResourcesResult:
+        """Send a resources/list request and return the complete MCP protocol result.
+
+        Args:
+            cursor: Optional pagination cursor from a previous request's nextCursor.
+            cache_mode: Response-cache behavior (only active with a cache and a modern
+                connection). See `list_tools_mcp`.
+
+        Returns:
+            mcp_types.ListResourcesResult: The complete response object from the protocol,
+                containing the list of resources and any additional metadata.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+            MCPError: If the request results in a TimeoutError | JSONRPCError
+        """
+        with client_span(
+            "resources/list",
+            "resources/list",
+            "",
+            session_id=self.transport.get_session_id(),
+        ):
+            logger.debug(f"[{self.name}] called list_resources")
+
+            params = (
+                mcp_types.PaginatedRequestParams(cursor=cursor)
+                if cursor is not None
+                else None
+            )
+
+            async def _send() -> mcp_types.ListResourcesResult:
+                return await self._await_with_session_monitoring(
+                    self.session.list_resources(params=params)
+                )
+
+            return await self._cached_fetch(
+                "resources/list", cursor=cursor, cache_mode=cache_mode, send=_send
+            )
+
+    async def list_resources(
+        self: Client,
+        max_pages: int = AUTO_PAGINATION_MAX_PAGES,
+    ) -> list[mcp_types.Resource]:
+        """Retrieve all resources available on the server.
+
+        This method automatically fetches all pages if the server paginates results,
+        returning the complete list. For manual pagination control (e.g., to handle
+        large result sets incrementally), use list_resources_mcp() with the cursor parameter.
+
+        Args:
+            max_pages: Maximum number of pages to fetch before raising. Defaults to 250.
+
+        Returns:
+            list[mcp_types.Resource]: A list of all Resource objects.
+
+        Raises:
+            RuntimeError: If the page limit is reached before pagination completes.
+            MCPError: If the request results in a TimeoutError | JSONRPCError
+        """
+        all_resources: list[mcp_types.Resource] = []
+        cursor: str | None = None
+        seen_cursors: set[str] = set()
+
+        for _ in range(max_pages):
+            result = await self.list_resources_mcp(cursor=cursor)
+            all_resources.extend(result.resources)
+            if not result.next_cursor:
+                break
+            if result.next_cursor in seen_cursors:
+                logger.warning(
+                    f"[{self.name}] Server returned duplicate pagination cursor"
+                    f" {result.next_cursor!r} for list_resources; stopping pagination"
+                )
+                break
+            seen_cursors.add(result.next_cursor)
+            cursor = result.next_cursor
+        else:
+            raise RuntimeError(
+                f"[{self.name}] Reached auto-pagination limit"
+                f" ({max_pages} pages) for list_resources."
+                " Use list_resources_mcp() with cursor for manual pagination,"
+                " or increase max_pages."
+            )
+
+        return all_resources
+
+    async def list_resource_templates_mcp(
+        self: Client,
+        *,
+        cursor: str | None = None,
+        cache_mode: CacheMode = "use",
+    ) -> mcp_types.ListResourceTemplatesResult:
+        """Send a resources/listResourceTemplates request and return the complete MCP protocol result.
+
+        Args:
+            cursor: Optional pagination cursor from a previous request's nextCursor.
+            cache_mode: Response-cache behavior (only active with a cache and a modern
+                connection). See `list_tools_mcp`.
+
+        Returns:
+            mcp_types.ListResourceTemplatesResult: The complete response object from the protocol,
+                containing the list of resource templates and any additional metadata.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+            MCPError: If the request results in a TimeoutError | JSONRPCError
+        """
+        with client_span(
+            "resources/templates/list",
+            "resources/templates/list",
+            "",
+            session_id=self.transport.get_session_id(),
+        ):
+            logger.debug(f"[{self.name}] called list_resource_templates")
+
+            params = (
+                mcp_types.PaginatedRequestParams(cursor=cursor)
+                if cursor is not None
+                else None
+            )
+
+            async def _send() -> mcp_types.ListResourceTemplatesResult:
+                return await self._await_with_session_monitoring(
+                    self.session.list_resource_templates(params=params)
+                )
+
+            return await self._cached_fetch(
+                "resources/templates/list",
+                cursor=cursor,
+                cache_mode=cache_mode,
+                send=_send,
+            )
+
+    async def list_resource_templates(
+        self: Client,
+        max_pages: int = AUTO_PAGINATION_MAX_PAGES,
+    ) -> list[mcp_types.ResourceTemplate]:
+        """Retrieve all resource templates available on the server.
+
+        This method automatically fetches all pages if the server paginates results,
+        returning the complete list. For manual pagination control (e.g., to handle
+        large result sets incrementally), use list_resource_templates_mcp() with the
+        cursor parameter.
+
+        Args:
+            max_pages: Maximum number of pages to fetch before raising. Defaults to 250.
+
+        Returns:
+            list[mcp_types.ResourceTemplate]: A list of all ResourceTemplate objects.
+
+        Raises:
+            RuntimeError: If the page limit is reached before pagination completes.
+            MCPError: If the request results in a TimeoutError | JSONRPCError
+        """
+        all_templates: list[mcp_types.ResourceTemplate] = []
+        cursor: str | None = None
+        seen_cursors: set[str] = set()
+
+        for _ in range(max_pages):
+            result = await self.list_resource_templates_mcp(cursor=cursor)
+            all_templates.extend(result.resource_templates)
+            if not result.next_cursor:
+                break
+            if result.next_cursor in seen_cursors:
+                logger.warning(
+                    f"[{self.name}] Server returned duplicate pagination cursor"
+                    f" {result.next_cursor!r} for list_resource_templates;"
+                    " stopping pagination"
+                )
+                break
+            seen_cursors.add(result.next_cursor)
+            cursor = result.next_cursor
+        else:
+            raise RuntimeError(
+                f"[{self.name}] Reached auto-pagination limit"
+                f" ({max_pages} pages) for list_resource_templates."
+                " Use list_resource_templates_mcp() with cursor for manual pagination,"
+                " or increase max_pages."
+            )
+
+        return all_templates
+
+    async def read_resource_mcp(
+        self: Client, uri: AnyUrl | str, meta: dict[str, Any] | None = None
+    ) -> mcp_types.ReadResourceResult:
+        """Send a resources/read request and return the complete MCP protocol result.
+
+        Args:
+            uri (AnyUrl | str): The URI of the resource to read. Can be a string or an AnyUrl object.
+            meta (dict[str, Any] | None, optional): Request metadata (e.g., for SEP-1686 tasks). Defaults to None.
+
+        Returns:
+            mcp_types.ReadResourceResult: The complete response object from the protocol,
+                containing the resource contents and any additional metadata.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+            MCPError: If the request results in a TimeoutError | JSONRPCError
+        """
+        # SDK v2: the wire `uri` is a plain string, but resources are stored
+        # under the AnyUrl-normalized form (e.g. a trailing slash for authority
+        # URIs), so normalize through AnyUrl to keep server-side lookups aligned.
+        uri_str = str(AnyUrl(uri)) if isinstance(uri, str) else str(uri)
+        with client_span(
+            "resources/read",
+            "resources/read",
+            uri_str,
+            session_id=self.transport.get_session_id(),
+            resource_uri=uri_str,
+        ):
+            logger.debug(f"[{self.name}] called read_resource: {uri}")
+
+            # Inject trace context into meta for propagation to server
+            propagated_meta = inject_trace_context(meta)
+            request_meta = cast("mcp_types.RequestParamsMeta | None", propagated_meta)
+
+            async def _retry(
+                input_responses: mcp_types.InputResponses | None,
+                request_state: str | None,
+            ) -> mcp_types.ReadResourceResult | mcp_types.InputRequiredResult:
+                return await self.session.read_resource(
+                    uri_str,
+                    meta=request_meta,
+                    input_responses=input_responses,
+                    request_state=request_state,
+                    allow_input_required=True,
+                )
+
+            first = await self._await_with_session_monitoring(_retry(None, None))
+            result = await self._await_with_session_monitoring(
+                self._drive_input_required(first, _retry)
+            )
+            return result
+
+    @overload
+    async def read_resource(
+        self: Client,
+        uri: AnyUrl | str,
+        *,
+        version: str | None = None,
+        meta: dict[str, Any] | None = None,
+        task: Literal[False] = False,
+    ) -> list[mcp_types.TextResourceContents | mcp_types.BlobResourceContents]: ...
+
+    @overload
+    async def read_resource(
+        self: Client,
+        uri: AnyUrl | str,
+        *,
+        version: str | None = None,
+        meta: dict[str, Any] | None = None,
+        task: Literal[True],
+        task_id: str | None = None,
+        ttl: int = 60000,
+    ) -> ResourceTask: ...
+
+    async def read_resource(
+        self: Client,
+        uri: AnyUrl | str,
+        *,
+        version: str | None = None,
+        meta: dict[str, Any] | None = None,
+        task: bool = False,
+        task_id: str | None = None,
+        ttl: int = 60000,
+    ) -> (
+        list[mcp_types.TextResourceContents | mcp_types.BlobResourceContents]
+        | ResourceTask
+    ):
+        """Read the contents of a resource or resolved template.
+
+        Args:
+            uri (AnyUrl | str): The URI of the resource to read. Can be a string or an AnyUrl object.
+            version (str | None): Specific version to read. If None, reads highest version.
+            meta (dict[str, Any] | None): Optional request-level metadata.
+            task (bool): If True, execute as background task (SEP-1686). Defaults to False.
+            task_id (str | None): Optional client-provided task ID (auto-generated if not provided).
+            ttl (int): Time to keep results available in milliseconds (default 60s).
+
+        Returns:
+            list[mcp_types.TextResourceContents | mcp_types.BlobResourceContents] | ResourceTask:
+                A list of content objects if task=False, or a ResourceTask object if task=True.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+            MCPError: If the request results in a TimeoutError | JSONRPCError
+        """
+        # Merge version into request-level meta (not arguments)
+        request_meta = dict(meta) if meta else {}
+        if version is not None:
+            request_meta["fastmcp"] = {
+                **request_meta.get("fastmcp", {}),
+                "version": version,
+            }
+
+        if task:
+            return await self._read_resource_as_task(
+                uri, task_id, ttl, meta=request_meta or None
+            )
+
+        if isinstance(uri, str):
+            try:
+                uri = AnyUrl(uri)  # Ensure AnyUrl
+            except Exception as e:
+                raise ValueError(
+                    f"Provided resource URI is invalid: {str(uri)!r}"
+                ) from e
+        result = await self.read_resource_mcp(uri, meta=request_meta or None)
+        return result.contents
+
+    async def _read_resource_as_task(
+        self: Client,
+        uri: AnyUrl | str,
+        task_id: str | None = None,
+        ttl: int = 60000,
+        meta: dict[str, Any] | None = None,
+    ) -> ResourceTask:
+        """Read a resource for background execution (SEP-1686).
+
+        Returns a ResourceTask object that handles both background and immediate execution.
+
+        Args:
+            uri: Resource URI to read
+            task_id: Optional client-provided task ID (ignored, for backward compatibility)
+            ttl: Time to keep results available in milliseconds (default 60s)
+            meta: Optional metadata to pass with the request (e.g., version info)
+
+        Returns:
+            ResourceTask: Future-like object for accessing task status and results
+        """
+        # Per SEP-1686 final spec: client sends only ttl, server generates taskId
+        # Inject trace context into meta for propagation to server.
+        # SDK v2: request `_meta` is `RequestParamsMeta` (a TypedDict), not
+        # the old `RequestParams.Meta` nested model.
+        propagated_meta = inject_trace_context(meta)
+        request_meta = cast(
+            "mcp_types.RequestParamsMeta | None",
+            propagated_meta if propagated_meta else None,
+        )
+
+        # SDK v2: ReadResourceRequestParams.uri is a plain string, but resources
+        # are stored under the AnyUrl-normalized form, so normalize to match.
+        uri_str = str(AnyUrl(uri)) if isinstance(uri, str) else str(uri)
+
+        # SDK v2: ReadResourceRequestParams has no `task` field, so this request
+        # cannot carry task metadata over the wire and the server graceful-
+        # degrades to immediate execution (sdk-feedback #3). `ttl` is retained on
+        # the public API but has no wire representation here.
+        request = mcp_types.ReadResourceRequest(
+            params=mcp_types.ReadResourceRequestParams(
+                uri=uri_str,
+                _meta=request_meta,  # type: ignore[unknown-argument]  # pydantic alias
+            )
+        )
+
+        # Server returns CreateTaskResult (task accepted) or ReadResourceResult (graceful degradation)
+        wrapped_result = await self._await_with_session_monitoring(
+            self.session.send_request(
+                request=request,  # type: ignore[arg-type]
+                result_type=ResourceTaskResponseUnion,
+            )
+        )
+        raw_result = wrapped_result.root
+
+        if isinstance(raw_result, mcp_types.CreateTaskResult):
+            # Task was accepted - extract task info from CreateTaskResult
+            server_task_id = raw_result.task.task_id
+            self._submitted_task_ids.add(server_task_id)
+
+            task_obj = ResourceTask(
+                self, server_task_id, uri=str(uri), immediate_result=None
+            )
+            self._task_registry[server_task_id] = weakref.ref(task_obj)
+            return task_obj
+        else:
+            # Graceful degradation - server returned ReadResourceResult
+            synthetic_task_id = task_id or str(uuid.uuid4())
+            return ResourceTask(
+                self,
+                synthetic_task_id,
+                uri=str(uri),
+                immediate_result=raw_result.contents,
+            )
diff --git a/fastmcp_slim/fastmcp/client/mixins/task_management.py b/fastmcp_slim/fastmcp/client/mixins/task_management.py
new file mode 100644
index 0000000..a011b13
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/mixins/task_management.py
@@ -0,0 +1,178 @@
+"""Task management methods for FastMCP Client."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import mcp_types
+from mcp import MCPError
+from mcp_types import Result
+from pydantic import ConfigDict
+
+if TYPE_CHECKING:
+    from fastmcp.client.client import Client
+from mcp_types import (
+    CancelTaskRequest,
+    CancelTaskRequestParams,
+    GetTaskPayloadRequest,
+    GetTaskPayloadRequestParams,
+    GetTaskRequest,
+    GetTaskRequestParams,
+    GetTaskResult,
+    ListTasksRequest,
+    PaginatedRequestParams,
+)
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class _RawTaskPayloadResult(Result):
+    """Permissive result type for `tasks/result` responses.
+
+    Per the v2 spec, a `tasks/result` payload arrives as extra wire fields whose
+    shape matches the original request's result type (CallToolResult,
+    GetPromptResult, ReadResourceResult, ...). `GetTaskPayloadResult` is a bare
+    `Result` that drops those fields on validation, so this subclass retains them
+    with `extra="allow"`; callers re-parse the resulting dict into the concrete
+    result type.
+    """
+
+    model_config = ConfigDict(
+        alias_generator=Result.model_config.get("alias_generator"),
+        populate_by_name=True,
+        extra="allow",
+    )
+
+
+class ClientTaskManagementMixin:
+    """Mixin providing task management methods for Client."""
+
+    async def get_task_status(self: Client, task_id: str) -> GetTaskResult:
+        """Query the status of a background task.
+
+        Sends a 'tasks/get' MCP protocol request over the existing transport.
+
+        Args:
+            task_id: The task ID returned from call_tool_as_task
+
+        Returns:
+            GetTaskResult: Status information including taskId, status, pollInterval, etc.
+
+        Raises:
+            RuntimeError: If client not connected
+            MCPError: If the request results in a TimeoutError | JSONRPCError
+        """
+        request = GetTaskRequest(params=GetTaskRequestParams(task_id=task_id))
+        return await self._await_with_session_monitoring(
+            self.session.send_request(
+                request=request,  # type: ignore[arg-type]
+                result_type=GetTaskResult,
+            )
+        )
+
+    async def get_task_result(self: Client, task_id: str) -> Any:
+        """Retrieve the raw result of a completed background task.
+
+        Sends a 'tasks/result' MCP protocol request over the existing transport.
+        Returns the raw result - callers should parse it appropriately.
+
+        Args:
+            task_id: The task ID returned from call_tool_as_task
+
+        Returns:
+            Any: The raw result (could be tool, prompt, or resource result)
+
+        Raises:
+            RuntimeError: If client not connected, task not found, or task failed
+            MCPError: If the request results in a TimeoutError | JSONRPCError
+        """
+        request = GetTaskPayloadRequest(
+            params=GetTaskPayloadRequestParams(task_id=task_id)
+        )
+        # Return raw result - Task classes handle type-specific parsing
+        result = await self._await_with_session_monitoring(
+            self.session.send_request(
+                request=request,  # type: ignore[arg-type]
+                result_type=_RawTaskPayloadResult,
+            )
+        )
+        # Return as dict for compatibility with Task class parsing. The payload
+        # fields (content, structuredContent, messages, contents, ...) survive
+        # via the permissive result type's extra="allow".
+        return result.model_dump(exclude_none=True, by_alias=True)
+
+    async def list_tasks(
+        self: Client,
+        cursor: str | None = None,
+        limit: int = 50,
+    ) -> dict[str, Any]:
+        """List background tasks.
+
+        Sends a 'tasks/list' MCP protocol request to the server. If the server
+        returns an empty list (indicating client-side tracking), falls back to
+        querying status for locally tracked task IDs.
+
+        Args:
+            cursor: Optional pagination cursor
+            limit: Maximum number of tasks to return (default 50)
+
+        Returns:
+            dict: Response with structure:
+                - tasks: List of task status dicts with taskId, status, etc.
+                - nextCursor: Optional cursor for next page
+
+        Raises:
+            RuntimeError: If client not connected
+            MCPError: If the request results in a TimeoutError | JSONRPCError
+        """
+        # Send protocol request
+        params = PaginatedRequestParams(cursor=cursor, limit=limit)  # type: ignore[call-arg]  # Optional field in MCP SDK  # ty:ignore[unknown-argument]
+        request = ListTasksRequest(params=params)
+        server_response = await self._await_with_session_monitoring(
+            self.session.send_request(
+                request=request,  # type: ignore[invalid-argument-type]
+                result_type=mcp_types.ListTasksResult,
+            )
+        )
+
+        # If server returned tasks, use those
+        if server_response.tasks:
+            return server_response.model_dump(by_alias=True)
+
+        # Server returned empty - fall back to client-side tracking
+        tasks = []
+        for task_id in list(self._submitted_task_ids)[:limit]:
+            try:
+                status = await self.get_task_status(task_id)
+                tasks.append(status.model_dump(by_alias=True))
+            except MCPError:
+                # Task may have expired or been deleted, skip it
+                continue
+
+        return {"tasks": tasks, "nextCursor": None}
+
+    async def cancel_task(self: Client, task_id: str) -> mcp_types.CancelTaskResult:
+        """Cancel a task, transitioning it to cancelled state.
+
+        Sends a 'tasks/cancel' MCP protocol request. Task will halt execution
+        and transition to cancelled state.
+
+        Args:
+            task_id: The task ID to cancel
+
+        Returns:
+            CancelTaskResult: The task status showing cancelled state
+
+        Raises:
+            RuntimeError: If task doesn't exist
+            MCPError: If the request results in a TimeoutError | JSONRPCError
+        """
+        request = CancelTaskRequest(params=CancelTaskRequestParams(task_id=task_id))
+        return await self._await_with_session_monitoring(
+            self.session.send_request(
+                request=request,  # type: ignore[invalid-argument-type]
+                result_type=mcp_types.CancelTaskResult,
+            )
+        )
diff --git a/fastmcp_slim/fastmcp/client/mixins/tools.py b/fastmcp_slim/fastmcp/client/mixins/tools.py
new file mode 100644
index 0000000..6e0a0de
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/mixins/tools.py
@@ -0,0 +1,526 @@
+"""Tool-related methods for FastMCP Client."""
+
+from __future__ import annotations
+
+import uuid
+import weakref
+from typing import TYPE_CHECKING, Any, Literal, cast, overload
+
+import mcp_types
+from mcp.client.caching import CacheMode
+from opentelemetry.trace import Status, StatusCode
+from pydantic import RootModel
+
+if TYPE_CHECKING:
+    import datetime
+
+    from fastmcp.client.client import CallToolResult, Client
+from fastmcp.client.progress import ProgressHandler
+from fastmcp.client.tasks import ToolTask
+from fastmcp.client.telemetry import client_span
+from fastmcp.exceptions import ToolError
+from fastmcp.telemetry import inject_trace_context
+from fastmcp.utilities.json_schema_type import json_schema_to_type
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.timeout import normalize_timeout_to_seconds
+from fastmcp.utilities.types import get_cached_typeadapter
+
+logger = get_logger(__name__)
+
+AUTO_PAGINATION_MAX_PAGES = 250
+
+# Type alias for task response union (SEP-1686 graceful degradation)
+ToolTaskResponseUnion = RootModel[mcp_types.CreateTaskResult | mcp_types.CallToolResult]
+
+
+class ClientToolsMixin:
+    """Mixin providing tool-related methods for Client."""
+
+    # --- Tools ---
+
+    async def list_tools_mcp(
+        self: Client,
+        *,
+        cursor: str | None = None,
+        cache_mode: CacheMode = "use",
+    ) -> mcp_types.ListToolsResult:
+        """Send a tools/list request and return the complete MCP protocol result.
+
+        Args:
+            cursor: Optional pagination cursor from a previous request's nextCursor.
+            cache_mode: Response-cache behavior for this call (only active when the
+                client was built with a cache and the connection is modern). `"use"`
+                (default) serves and stores; `"refresh"` stores without serving;
+                `"bypass"` skips the cache. A cursor page always skips the cache.
+
+        Returns:
+            mcp_types.ListToolsResult: The complete response object from the protocol,
+                containing the list of tools and any additional metadata.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+            MCPError: If the request results in a TimeoutError | JSONRPCError
+        """
+        with client_span(
+            "tools/list",
+            "tools/list",
+            "",
+            session_id=self.transport.get_session_id(),
+        ):
+            logger.debug(f"[{self.name}] called list_tools")
+
+            params = (
+                mcp_types.PaginatedRequestParams(cursor=cursor)
+                if cursor is not None
+                else None
+            )
+
+            async def _send() -> mcp_types.ListToolsResult:
+                return await self._await_with_session_monitoring(
+                    self.session.list_tools(params=params)
+                )
+
+            return await self._cached_fetch(
+                "tools/list",
+                cursor=cursor,
+                cache_mode=cache_mode,
+                send=_send,
+                # A cache hit skips session.list_tools, so re-absorb the served
+                # listing to rebuild the session's derived per-tool state. Hits are
+                # cursorless, but a cached page 1 can carry next_cursor — never prune
+                # on a partial listing.
+                absorb=lambda hit: self.session._absorb_tool_listing(
+                    hit, complete=hit.next_cursor is None
+                ),
+            )
+
+    async def list_tools(
+        self: Client,
+        max_pages: int = AUTO_PAGINATION_MAX_PAGES,
+    ) -> list[mcp_types.Tool]:
+        """Retrieve all tools available on the server.
+
+        This method automatically fetches all pages if the server paginates results,
+        returning the complete list. For manual pagination control (e.g., to handle
+        large result sets incrementally), use list_tools_mcp() with the cursor parameter.
+
+        Args:
+            max_pages: Maximum number of pages to fetch before raising. Defaults to 250.
+
+        Returns:
+            list[mcp_types.Tool]: A list of all Tool objects.
+
+        Raises:
+            RuntimeError: If the page limit is reached before pagination completes.
+            MCPError: If the request results in a TimeoutError | JSONRPCError
+        """
+        all_tools: list[mcp_types.Tool] = []
+        cursor: str | None = None
+        seen_cursors: set[str] = set()
+
+        for _ in range(max_pages):
+            result = await self.list_tools_mcp(cursor=cursor)
+            all_tools.extend(result.tools)
+            if not result.next_cursor:
+                break
+            if result.next_cursor in seen_cursors:
+                logger.warning(
+                    f"[{self.name}] Server returned duplicate pagination cursor"
+                    f" {result.next_cursor!r} for list_tools; stopping pagination"
+                )
+                break
+            seen_cursors.add(result.next_cursor)
+            cursor = result.next_cursor
+        else:
+            raise RuntimeError(
+                f"[{self.name}] Reached auto-pagination limit"
+                f" ({max_pages} pages) for list_tools."
+                " Use list_tools_mcp() with cursor for manual pagination,"
+                " or increase max_pages."
+            )
+
+        return all_tools
+
+    # --- Call Tool ---
+
+    async def call_tool_mcp(
+        self: Client,
+        name: str,
+        arguments: dict[str, Any],
+        progress_handler: ProgressHandler | None = None,
+        timeout: datetime.timedelta | float | int | None = None,
+        meta: dict[str, Any] | None = None,
+    ) -> mcp_types.CallToolResult:
+        """Send a tools/call request and return the complete MCP protocol result.
+
+        This method returns the raw CallToolResult object, which includes an isError flag
+        and other metadata. It does not raise an exception if the tool call results in an error.
+
+        Args:
+            name (str): The name of the tool to call.
+            arguments (dict[str, Any]): Arguments to pass to the tool.
+            timeout (datetime.timedelta | float | int | None, optional): The timeout for the tool call. Defaults to None.
+            progress_handler (ProgressHandler | None, optional): The progress handler to use for the tool call. Defaults to None.
+            meta (dict[str, Any] | None, optional): Additional metadata to include with the request.
+                This is useful for passing contextual information (like user IDs, trace IDs, or preferences)
+                that shouldn't be tool arguments but may influence server-side processing. The server
+                can access this via `context.request_context.meta`. Defaults to None.
+
+        Returns:
+            mcp_types.CallToolResult: The complete response object from the protocol,
+                containing the tool result and any additional metadata.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+            MCPError: If the tool call requests results in a TimeoutError | JSONRPCError
+        """
+        with client_span(
+            f"tools/call {name}",
+            "tools/call",
+            name,
+            session_id=self.transport.get_session_id(),
+            tool_name=name,
+        ) as span:
+            logger.debug(f"[{self.name}] called call_tool: {name}")
+
+            # Inject trace context into meta for propagation to server.
+            # SDK v2: request `_meta` is `RequestParamsMeta` (a TypedDict), not
+            # the old `RequestParams.Meta` nested model.
+            propagated_meta = inject_trace_context(meta)
+            request_meta = cast(
+                "mcp_types.RequestParamsMeta | None",
+                propagated_meta if propagated_meta else None,
+            )
+
+            read_timeout_seconds = normalize_timeout_to_seconds(timeout)
+            progress_callback = progress_handler or self._progress_handler
+
+            async def _retry(
+                input_responses: mcp_types.InputResponses | None,
+                request_state: str | None,
+            ) -> mcp_types.CallToolResult | mcp_types.InputRequiredResult:
+                return await self.session.call_tool(
+                    name=name,
+                    arguments=arguments,
+                    read_timeout_seconds=read_timeout_seconds,
+                    progress_callback=progress_callback,
+                    meta=request_meta,
+                    input_responses=input_responses,
+                    request_state=request_state,
+                    allow_input_required=True,
+                )
+
+            first = await self._await_with_session_monitoring(_retry(None, None))
+            result = await self._await_with_session_monitoring(
+                self._drive_input_required(first, _retry)
+            )
+
+            # Reflect tool-level errors on the span so callers see ERROR
+            # status even though the MCP protocol call itself succeeded.
+            if result.is_error and span.is_recording():
+                span.set_attribute("error.type", "tool_error")
+                description = ""
+                if result.content and isinstance(
+                    result.content[0], mcp_types.TextContent
+                ):
+                    description = result.content[0].text
+                span.set_status(Status(StatusCode.ERROR, description))
+
+            return result
+
+    async def _parse_call_tool_result(
+        self: Client,
+        name: str,
+        result: mcp_types.CallToolResult,
+        raise_on_error: bool = False,
+    ) -> CallToolResult:
+        """Parse an mcp_types.CallToolResult into our CallToolResult dataclass.
+
+        Args:
+            name: Tool name (for schema lookup)
+            result: Raw MCP protocol result
+            raise_on_error: Whether to raise ToolError on errors
+
+        Returns:
+            CallToolResult: Parsed result with structured data
+        """
+
+        return await _parse_call_tool_result(
+            name=name,
+            result=result,
+            tool_output_schemas=self.session._tool_output_schemas,
+            list_tools_fn=self.session.list_tools,
+            client_name=self.name,
+            raise_on_error=raise_on_error,
+        )
+
+    @overload
+    async def call_tool(
+        self: Client,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        version: str | None = None,
+        timeout: datetime.timedelta | float | int | None = None,
+        progress_handler: ProgressHandler | None = None,
+        raise_on_error: bool = True,
+        meta: dict[str, Any] | None = None,
+        task: Literal[False] = False,
+    ) -> CallToolResult: ...
+
+    @overload
+    async def call_tool(
+        self: Client,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        version: str | None = None,
+        timeout: datetime.timedelta | float | int | None = None,
+        progress_handler: ProgressHandler | None = None,
+        raise_on_error: bool = True,
+        meta: dict[str, Any] | None = None,
+        task: Literal[True],
+        task_id: str | None = None,
+        ttl: int = 60000,
+    ) -> ToolTask: ...
+
+    async def call_tool(
+        self: Client,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        version: str | None = None,
+        timeout: datetime.timedelta | float | int | None = None,
+        progress_handler: ProgressHandler | None = None,
+        raise_on_error: bool = True,
+        meta: dict[str, Any] | None = None,
+        task: bool = False,
+        task_id: str | None = None,
+        ttl: int = 60000,
+    ) -> CallToolResult | ToolTask:
+        """Call a tool on the server.
+
+        Unlike call_tool_mcp, this method raises a ToolError if the tool call results in an error.
+
+        Args:
+            name (str): The name of the tool to call.
+            arguments (dict[str, Any] | None, optional): Arguments to pass to the tool. Defaults to None.
+            version (str | None, optional): Specific tool version to call. If None, calls highest version.
+            timeout (datetime.timedelta | float | int | None, optional): The timeout for the tool call. Defaults to None.
+            progress_handler (ProgressHandler | None, optional): The progress handler to use for the tool call. Defaults to None.
+            raise_on_error (bool, optional): Whether to raise an exception if the tool call results in an error. Defaults to True.
+            meta (dict[str, Any] | None, optional): Additional metadata to include with the request.
+                This is useful for passing contextual information (like user IDs, trace IDs, or preferences)
+                that shouldn't be tool arguments but may influence server-side processing. The server
+                can access this via `context.request_context.meta`. Defaults to None.
+            task (bool): If True, execute as background task (SEP-1686). Defaults to False.
+            task_id (str | None): Optional client-provided task ID (auto-generated if not provided).
+            ttl (int): Time to keep results available in milliseconds (default 60s).
+
+        Returns:
+            CallToolResult | ToolTask: The content returned by the tool if task=False,
+                or a ToolTask object if task=True. If the tool returns structured
+                outputs, they are returned as a dataclass (if an output schema
+                is available) or a dictionary; otherwise, a list of content
+                blocks is returned. Note: to receive both structured and
+                unstructured outputs, use call_tool_mcp instead and access the
+                raw result object.
+
+        Raises:
+            ToolError: If the tool call results in an error.
+            MCPError: If the tool call request results in a TimeoutError | JSONRPCError
+            RuntimeError: If called while the client is not connected.
+        """
+        # Merge version into request-level meta (not arguments)
+        request_meta = dict(meta) if meta else {}
+        if version is not None:
+            request_meta["fastmcp"] = {
+                **request_meta.get("fastmcp", {}),
+                "version": version,
+            }
+
+        if task:
+            return await self._call_tool_as_task(
+                name,
+                arguments,
+                task_id,
+                ttl,
+                raise_on_error=raise_on_error,
+                meta=request_meta or None,
+            )
+
+        result = await self.call_tool_mcp(
+            name=name,
+            arguments=arguments or {},
+            timeout=timeout,
+            progress_handler=progress_handler,
+            meta=request_meta or None,
+        )
+        return await self._parse_call_tool_result(
+            name, result, raise_on_error=raise_on_error
+        )
+
+    async def _call_tool_as_task(
+        self: Client,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        task_id: str | None = None,
+        ttl: int = 60000,
+        raise_on_error: bool = True,
+        meta: dict[str, Any] | None = None,
+    ) -> ToolTask:
+        """Call a tool for background execution (SEP-1686).
+
+        Returns a ToolTask object that handles both background and immediate execution.
+        If the server accepts background execution, ToolTask will poll for results.
+        If the server declines (graceful degradation), ToolTask wraps the immediate result.
+
+        Args:
+            name: Tool name to call
+            arguments: Tool arguments
+            task_id: Optional client-provided task ID (ignored, for backward compatibility)
+            ttl: Time to keep results available in milliseconds (default 60s)
+            raise_on_error: Whether task.result() should raise ToolError on errors
+            meta: Optional request metadata (e.g., version info)
+
+        Returns:
+            ToolTask: Future-like object for accessing task status and results
+        """
+        # Per SEP-1686 final spec: client sends only ttl, server generates taskId
+        # Inject trace context into meta for propagation to server
+        propagated_meta = inject_trace_context(meta)
+        # SDK v2: request `_meta` is `RequestParamsMeta` (a TypedDict), not the
+        # old `RequestParams.Meta` nested model.
+        request_meta = cast(mcp_types.RequestParamsMeta | None, propagated_meta)
+
+        # Build request with task metadata
+        request = mcp_types.CallToolRequest(
+            params=mcp_types.CallToolRequestParams(
+                name=name,
+                arguments=arguments or {},
+                task=mcp_types.TaskMetadata(ttl=ttl),
+                _meta=request_meta,  # type: ignore[unknown-argument]  # pydantic alias
+            )
+        )
+
+        # Server returns CreateTaskResult (task accepted) or CallToolResult (graceful degradation)
+        # Use RootModel with Union to handle both response types (SDK calls model_validate)
+        wrapped_result = await self._await_with_session_monitoring(
+            self.session.send_request(
+                request=request,  # type: ignore[arg-type]
+                result_type=ToolTaskResponseUnion,
+            )
+        )
+        raw_result = wrapped_result.root
+
+        if isinstance(raw_result, mcp_types.CreateTaskResult):
+            # Task was accepted - extract task info from CreateTaskResult
+            server_task_id = raw_result.task.task_id
+            self._submitted_task_ids.add(server_task_id)
+
+            task_obj = ToolTask(
+                self,
+                server_task_id,
+                tool_name=name,
+                immediate_result=None,
+                raise_on_error=raise_on_error,
+            )
+            self._task_registry[server_task_id] = weakref.ref(task_obj)
+            return task_obj
+        else:
+            # Graceful degradation - server returned CallToolResult
+            parsed_result = await self._parse_call_tool_result(name, raw_result)
+            synthetic_task_id = task_id or str(uuid.uuid4())
+            return ToolTask(
+                self,
+                synthetic_task_id,
+                tool_name=name,
+                immediate_result=parsed_result,
+                raise_on_error=raise_on_error,
+            )
+
+
+async def _parse_call_tool_result(
+    name: str,
+    result: mcp_types.CallToolResult,
+    tool_output_schemas: dict[str, dict[str, Any] | None],
+    list_tools_fn: Any,  # Callable[[], Awaitable[None]]
+    client_name: str | None = None,
+    raise_on_error: bool = False,
+) -> CallToolResult:
+    """Parse an mcp_types.CallToolResult into our CallToolResult dataclass.
+
+    Args:
+        name: Tool name (for schema lookup)
+        result: Raw MCP protocol result
+        tool_output_schemas: Dictionary mapping tool names to their output schemas
+        list_tools_fn: Async function to refresh tool schemas if needed
+        client_name: Optional client name for logging
+        raise_on_error: Whether to raise ToolError on errors
+
+    Returns:
+        CallToolResult: Parsed result with structured data
+    """
+    # Local import: CallToolResult is under TYPE_CHECKING at module level to
+    # avoid a circular import (client.client -> mixins.tools -> client.client),
+    # but we need the concrete class here to construct the return value.
+    from fastmcp.client.client import CallToolResult
+
+    data = None
+    if result.is_error and raise_on_error:
+        if result.content and isinstance(result.content[0], mcp_types.TextContent):
+            msg = result.content[0].text
+        else:
+            msg = f"Tool '{name}' returned an error"
+        raise ToolError(msg)
+    elif result.structured_content and not result.is_error:
+        try:
+            raw_fastmcp_meta = (result.meta or {}).get("fastmcp")
+            fastmcp_meta = (
+                raw_fastmcp_meta if isinstance(raw_fastmcp_meta, dict) else {}
+            )
+            wrap_from_meta = fastmcp_meta.get("wrap_result", False)
+
+            # Ensure the schema cache is populated for type validation.
+            # When meta tells us the result is wrapped we can skip the
+            # schema check for *wrap detection*, but we still need the
+            # schema for proper type coercion (e.g. list → set, str → datetime).
+            if name not in tool_output_schemas:
+                await list_tools_fn()
+
+            if wrap_from_meta:
+                # Meta tells us the result is wrapped — unwrap and validate.
+                structured_content = result.structured_content.get("result")
+            elif name in tool_output_schemas:
+                output_schema = tool_output_schemas.get(name)
+                if output_schema and output_schema.get("x-fastmcp-wrap-result"):
+                    structured_content = result.structured_content.get("result")
+                else:
+                    structured_content = result.structured_content
+            else:
+                structured_content = result.structured_content
+
+            # Type-validate through the schema if available.
+            output_schema = tool_output_schemas.get(name)
+            if output_schema:
+                if wrap_from_meta or output_schema.get("x-fastmcp-wrap-result"):
+                    output_schema = output_schema.get("properties", {}).get(
+                        "result", output_schema
+                    )
+                output_type = json_schema_to_type(output_schema)
+                type_adapter = get_cached_typeadapter(output_type)
+                data = type_adapter.validate_python(structured_content)
+            else:
+                data = structured_content
+        except Exception as e:
+            logger.error(
+                f"[{client_name or 'client'}] Error parsing structured content: {e}"
+            )
+
+    return CallToolResult(
+        content=result.content,
+        structured_content=result.structured_content,
+        meta=result.meta,
+        data=data,
+        is_error=result.is_error,
+    )
diff --git a/fastmcp_slim/fastmcp/client/oauth_callback.py b/fastmcp_slim/fastmcp/client/oauth_callback.py
new file mode 100644
index 0000000..3d7a742
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/oauth_callback.py
@@ -0,0 +1,252 @@
+"""
+OAuth callback server for handling authorization code flows.
+
+This module provides a reusable callback server that can handle OAuth redirects
+and display styled responses to users.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import anyio
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.routing import Route
+from uvicorn import Config, Server
+
+from fastmcp.utilities.http import find_available_port
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.ui import (
+    HELPER_TEXT_STYLES,
+    INFO_BOX_STYLES,
+    STATUS_MESSAGE_STYLES,
+    create_info_box,
+    create_logo,
+    create_page,
+    create_secure_html_response,
+    create_status_message,
+)
+
+logger = get_logger(__name__)
+
+
+def create_callback_html(
+    message: str,
+    is_success: bool = True,
+    title: str = "FastMCP OAuth",
+    server_url: str | None = None,
+) -> str:
+    """Create a styled HTML response for OAuth callbacks."""
+    # Build the main status message
+    status_title = (
+        "Authentication successful" if is_success else "Authentication failed"
+    )
+
+    # Add detail info box for both success and error cases
+    detail_info = ""
+    if is_success and server_url:
+        detail_info = create_info_box(
+            f"Connected to: {server_url}", centered=True, monospace=True
+        )
+    elif not is_success:
+        detail_info = create_info_box(
+            message, is_error=True, centered=True, monospace=True
+        )
+
+    # Build the page content
+    content = f"""
+        <div class="container">
+            {create_logo()}
+            {create_status_message(status_title, is_success=is_success)}
+            {detail_info}
+            <div class="close-instruction">
+                You can safely close this tab now.
+            </div>
+        </div>
+    """
+
+    # Additional styles needed for this page
+    additional_styles = STATUS_MESSAGE_STYLES + INFO_BOX_STYLES + HELPER_TEXT_STYLES
+
+    return create_page(
+        content=content,
+        title=title,
+        additional_styles=additional_styles,
+    )
+
+
+@dataclass
+class CallbackResponse:
+    code: str | None = None
+    state: str | None = None
+    error: str | None = None
+    error_description: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, str]) -> CallbackResponse:
+        return cls(**{k: v for k, v in data.items() if k in cls.__annotations__})
+
+    def to_dict(self) -> dict[str, str]:
+        return {k: v for k, v in self.__dict__.items() if v is not None}
+
+
+@dataclass
+class OAuthCallbackResult:
+    """Container for OAuth callback results, used with anyio.Event for async coordination."""
+
+    code: str | None = None
+    state: str | None = None
+    error: Exception | None = None
+
+
+def create_oauth_callback_server(
+    port: int,
+    host: str = "127.0.0.1",
+    callback_path: str = "/callback",
+    server_url: str | None = None,
+    result_container: OAuthCallbackResult | None = None,
+    result_ready: anyio.Event | None = None,
+) -> Server:
+    """
+    Create an OAuth callback server.
+
+    Args:
+        port: The port to run the server on
+        callback_path: The path to listen for OAuth redirects on
+        server_url: Optional server URL to display in success messages
+        result_container: Optional container to store callback results
+        result_ready: Optional event to signal when callback is received
+
+    Returns:
+        Configured uvicorn Server instance (not yet running)
+    """
+
+    def store_result_once(
+        *,
+        code: str | None = None,
+        state: str | None = None,
+        error: Exception | None = None,
+    ) -> None:
+        """Store the first callback result and ignore subsequent requests."""
+        if result_container is None or result_ready is None or result_ready.is_set():
+            return
+
+        result_container.code = code
+        result_container.state = state
+        result_container.error = error
+        result_ready.set()
+
+    async def callback_handler(request: Request):
+        """Handle OAuth callback requests with proper HTML responses."""
+        query_params = dict(request.query_params)
+        callback_response = CallbackResponse.from_dict(query_params)
+
+        if callback_response.error:
+            error_desc = callback_response.error_description or "Unknown error"
+
+            # Create user-friendly error messages
+            if callback_response.error == "access_denied":
+                user_message = "Access was denied by the authorization server."
+            else:
+                user_message = f"Authorization failed: {error_desc}"
+
+            # Store error and signal completion if result tracking provided
+            store_result_once(error=RuntimeError(user_message))
+
+            return create_secure_html_response(
+                create_callback_html(
+                    user_message,
+                    is_success=False,
+                ),
+                status_code=400,
+            )
+
+        if not callback_response.code:
+            user_message = "No authorization code was received from the server."
+
+            # Store error and signal completion if result tracking provided
+            store_result_once(error=RuntimeError(user_message))
+
+            return create_secure_html_response(
+                create_callback_html(
+                    user_message,
+                    is_success=False,
+                ),
+                status_code=400,
+            )
+
+        # Check for missing state parameter (indicates OAuth flow issue)
+        if callback_response.state is None:
+            user_message = (
+                "The OAuth server did not return the expected state parameter."
+            )
+
+            # Store error and signal completion if result tracking provided
+            store_result_once(error=RuntimeError(user_message))
+
+            return create_secure_html_response(
+                create_callback_html(
+                    user_message,
+                    is_success=False,
+                ),
+                status_code=400,
+            )
+
+        # Success case - store result and signal completion if result tracking provided
+        store_result_once(
+            code=callback_response.code,
+            state=callback_response.state,
+        )
+
+        return create_secure_html_response(
+            create_callback_html("", is_success=True, server_url=server_url)
+        )
+
+    app = Starlette(routes=[Route(callback_path, callback_handler)])
+
+    return Server(
+        Config(
+            app=app,
+            host=host,
+            port=port,
+            lifespan="off",
+            log_level="warning",
+            ws="websockets-sansio",
+        )
+    )
+
+
+if __name__ == "__main__":
+    """Run a test server when executed directly."""
+    import webbrowser
+
+    import uvicorn
+
+    port = find_available_port()
+    print("🎭 OAuth Callback Test Server")
+    print("📍 Test URLs:")
+    print(f"  Success: http://localhost:{port}/callback?code=test123&state=xyz")
+    print(
+        f"  Error:   http://localhost:{port}/callback?error=access_denied&error_description=User%20denied"
+    )
+    print(f"  Missing: http://localhost:{port}/callback")
+    print("🛑 Press Ctrl+C to stop")
+    print()
+
+    # Create test server without future (just for testing HTML responses)
+    server = create_oauth_callback_server(
+        port=port, server_url="https://fastmcp-test-server.example.com"
+    )
+
+    # Open browser to success example
+    webbrowser.open(f"http://localhost:{port}/callback?code=test123&state=xyz")
+
+    # Run with uvicorn directly
+    uvicorn.run(
+        server.config.app,
+        host="127.0.0.1",
+        port=port,
+        log_level="warning",
+        access_log=False,
+    )
diff --git a/fastmcp_slim/fastmcp/client/progress.py b/fastmcp_slim/fastmcp/client/progress.py
new file mode 100644
index 0000000..826d2cb
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/progress.py
@@ -0,0 +1,41 @@
+from typing import TypeAlias
+
+from mcp.shared.session import ProgressFnT
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+ProgressHandler: TypeAlias = ProgressFnT
+
+
+async def default_progress_handler(
+    progress: float, total: float | None, message: str | None
+) -> None:
+    """Default handler for progress notifications.
+
+    Logs progress updates at debug level, properly handling missing total or message values.
+
+    Args:
+        progress: Current progress value
+        total: Optional total expected value
+        message: Optional status message
+    """
+    if total not in (None, 0):
+        # We have both progress and total
+        percent = (progress / total) * 100
+        progress_str = f"{progress}/{total} ({percent:.1f}%)"
+    elif total == 0:
+        # Avoid division by zero when a server reports an invalid total.
+        progress_str = f"{progress}/{total}"
+    else:
+        # We only have progress
+        progress_str = f"{progress}"
+
+    # Include message if available
+    if message:
+        log_msg = f"Progress: {progress_str} - {message}"
+    else:
+        log_msg = f"Progress: {progress_str}"
+
+    logger.debug(log_msg)
diff --git a/fastmcp_slim/fastmcp/client/roots.py b/fastmcp_slim/fastmcp/client/roots.py
new file mode 100644
index 0000000..cb655c1
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/roots.py
@@ -0,0 +1,82 @@
+import inspect
+from collections.abc import Awaitable, Callable
+from typing import TypeAlias, cast
+
+import mcp_types
+import pydantic
+from mcp import ClientSession
+from mcp.client.session import ClientRequestContext, ListRootsFnT
+
+from fastmcp.client._sdk_context_shim import LifespanContextT, RequestContext
+
+RootsList: TypeAlias = list[str] | list[mcp_types.Root] | list[str | mcp_types.Root]
+
+RootsHandler: TypeAlias = (
+    Callable[[RequestContext[ClientSession, LifespanContextT]], RootsList]
+    | Callable[[RequestContext[ClientSession, LifespanContextT]], Awaitable[RootsList]]
+)
+
+
+def convert_roots_list(roots: RootsList) -> list[mcp_types.Root]:
+    roots_list = []
+    for r in roots:
+        if isinstance(r, mcp_types.Root):
+            roots_list.append(r)
+        elif isinstance(r, pydantic.FileUrl):
+            roots_list.append(mcp_types.Root(uri=r))
+        elif isinstance(r, str):
+            roots_list.append(mcp_types.Root(uri=pydantic.FileUrl(r)))
+        else:
+            raise ValueError(f"Invalid root: {r}")
+    return roots_list
+
+
+def create_roots_callback(
+    handler: RootsList | RootsHandler,
+) -> ListRootsFnT:
+    if isinstance(handler, list):
+        # TODO(ty): remove when ty supports isinstance union narrowing
+        return _create_roots_callback_from_roots(handler)  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+    elif inspect.isfunction(handler):
+        return _create_roots_callback_from_fn(handler)
+    else:
+        raise ValueError(f"Invalid roots handler: {handler}")
+
+
+def _create_roots_callback_from_roots(
+    roots: RootsList,
+) -> ListRootsFnT:
+    roots = convert_roots_list(roots)
+
+    async def _roots_callback(
+        context: ClientRequestContext,
+    ) -> mcp_types.ListRootsResult:
+        return mcp_types.ListRootsResult(roots=roots)
+
+    return _roots_callback
+
+
+def _create_roots_callback_from_fn(
+    fn: Callable[[RequestContext[ClientSession, LifespanContextT]], RootsList]
+    | Callable[[RequestContext[ClientSession, LifespanContextT]], Awaitable[RootsList]],
+) -> ListRootsFnT:
+    async def _roots_callback(
+        context: ClientRequestContext,
+    ) -> mcp_types.ListRootsResult | mcp_types.ErrorData:
+        try:
+            # The public RootsHandler alias is typed against the subscriptable
+            # RequestContext shim; the runtime object is the SDK's
+            # ClientRequestContext, passed through opaquely.
+            roots = fn(context)  # ty: ignore[invalid-argument-type]
+            if inspect.isawaitable(roots):
+                roots = await roots
+            return mcp_types.ListRootsResult(
+                roots=convert_roots_list(cast(RootsList, roots))
+            )
+        except Exception as e:
+            return mcp_types.ErrorData(
+                code=mcp_types.INTERNAL_ERROR,
+                message=str(e),
+            )
+
+    return _roots_callback
diff --git a/fastmcp_slim/fastmcp/client/sampling/__init__.py b/fastmcp_slim/fastmcp/client/sampling/__init__.py
new file mode 100644
index 0000000..e35e5c6
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/sampling/__init__.py
@@ -0,0 +1,71 @@
+import inspect
+from collections.abc import Awaitable, Callable
+from typing import TypeAlias, TypeVar, cast
+
+import mcp_types
+from mcp import ClientSession, CreateMessageResult
+from mcp.client.session import SamplingFnT
+from mcp.server.session import ServerSession
+from fastmcp.client._sdk_context_shim import LifespanContextT, RequestContext
+from mcp_types import CreateMessageRequestParams as SamplingParams
+from mcp_types import CreateMessageResultWithTools, SamplingMessage
+
+# Result type that handlers can return
+SamplingHandlerResult: TypeAlias = (
+    str | CreateMessageResult | CreateMessageResultWithTools
+)
+
+# Session type for sampling handlers - works with both client and server sessions
+SessionT = TypeVar("SessionT", ClientSession, ServerSession)
+
+# Unified sampling handler type that works for both clients and servers.
+# Handlers receive messages and parameters from the MCP sampling flow
+# and return LLM responses.
+SamplingHandler: TypeAlias = Callable[
+    [
+        list[SamplingMessage],
+        SamplingParams,
+        RequestContext[SessionT, LifespanContextT],
+    ],
+    SamplingHandlerResult | Awaitable[SamplingHandlerResult],
+]
+
+
+__all__ = [
+    "RequestContext",
+    "SamplingHandler",
+    "SamplingHandlerResult",
+    "SamplingMessage",
+    "SamplingParams",
+    "create_sampling_callback",
+]
+
+
+def create_sampling_callback(
+    sampling_handler: SamplingHandler,
+) -> SamplingFnT:
+    async def _sampling_handler(
+        context,
+        params: SamplingParams,
+    ) -> CreateMessageResult | CreateMessageResultWithTools | mcp_types.ErrorData:
+        try:
+            result = sampling_handler(params.messages, params, context)
+            if inspect.isawaitable(result):
+                result = await result
+
+            result = cast(SamplingHandlerResult, result)
+
+            if isinstance(result, str):
+                result = CreateMessageResult(
+                    role="assistant",
+                    model="fastmcp-slim",
+                    content=mcp_types.TextContent(type="text", text=result),
+                )
+            return result
+        except Exception as e:
+            return mcp_types.ErrorData(
+                code=mcp_types.INTERNAL_ERROR,
+                message=str(e),
+            )
+
+    return _sampling_handler
diff --git a/fastmcp_slim/fastmcp/client/sampling/handlers/__init__.py b/fastmcp_slim/fastmcp/client/sampling/handlers/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/fastmcp_slim/fastmcp/client/sampling/handlers/anthropic.py b/fastmcp_slim/fastmcp/client/sampling/handlers/anthropic.py
new file mode 100644
index 0000000..88eb132
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/sampling/handlers/anthropic.py
@@ -0,0 +1,453 @@
+"""Anthropic sampling handler for FastMCP."""
+
+from collections.abc import Iterator, Sequence
+from typing import Any
+
+from mcp_types import (
+    AudioContent,
+    CreateMessageResult,
+    CreateMessageResultWithTools,
+    ImageContent,
+    ModelPreferences,
+    SamplingMessage,
+    SamplingMessageContentBlock,
+    StopReason,
+    TextContent,
+    Tool,
+    ToolChoice,
+    ToolResultContent,
+    ToolUseContent,
+)
+from mcp_types import CreateMessageRequestParams as SamplingParams
+
+try:
+    from anthropic import AsyncAnthropic
+    from anthropic.types import (
+        Base64ImageSourceParam,
+        ImageBlockParam,
+        Message,
+        MessageParam,
+        TextBlock,
+        TextBlockParam,
+        ToolParam,
+        ToolResultBlockParam,
+        ToolUseBlock,
+        ToolUseBlockParam,
+    )
+    from anthropic.types.model_param import ModelParam
+    from anthropic.types.tool_choice_any_param import ToolChoiceAnyParam
+    from anthropic.types.tool_choice_auto_param import ToolChoiceAutoParam
+    from anthropic.types.tool_choice_param import ToolChoiceParam
+except ImportError as e:
+    raise ImportError(
+        "The `anthropic` package is not installed. "
+        "Install it with `pip install fastmcp-slim[anthropic]` or add `anthropic` to your dependencies."
+    ) from e
+
+__all__ = ["AnthropicSamplingHandler"]
+
+# Anthropic supports these image MIME types
+_ANTHROPIC_IMAGE_MEDIA_TYPES = frozenset(
+    {"image/jpeg", "image/png", "image/gif", "image/webp"}
+)
+
+
+def _image_content_to_anthropic_block(content: ImageContent) -> ImageBlockParam:
+    """Convert MCP ImageContent to Anthropic ImageBlockParam."""
+    if content.mime_type not in _ANTHROPIC_IMAGE_MEDIA_TYPES:
+        raise ValueError(
+            f"Unsupported image MIME type for Anthropic: {content.mime_type!r}. "
+            f"Supported types: {', '.join(sorted(_ANTHROPIC_IMAGE_MEDIA_TYPES))}"
+        )
+    return ImageBlockParam(
+        type="image",
+        source=Base64ImageSourceParam(
+            type="base64",
+            media_type=content.mime_type,  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+            data=content.data,
+        ),
+    )
+
+
+class AnthropicSamplingHandler:
+    """Sampling handler that uses the Anthropic API.
+
+    Example:
+        ```python
+        from anthropic import AsyncAnthropic
+        from fastmcp import FastMCP
+        from fastmcp.client.sampling.handlers.anthropic import AnthropicSamplingHandler
+
+        handler = AnthropicSamplingHandler(
+            default_model="claude-sonnet-4-5",
+            client=AsyncAnthropic(),
+        )
+
+        server = FastMCP(sampling_handler=handler)
+        ```
+    """
+
+    def __init__(
+        self, default_model: ModelParam, client: AsyncAnthropic | None = None
+    ) -> None:
+        self.client: AsyncAnthropic = client or AsyncAnthropic()
+        self.default_model: ModelParam = default_model
+
+    async def __call__(
+        self,
+        messages: list[SamplingMessage],
+        params: SamplingParams,
+        context: Any,
+    ) -> CreateMessageResult | CreateMessageResultWithTools:
+        anthropic_messages: list[MessageParam] = self._convert_to_anthropic_messages(
+            messages=messages,
+        )
+
+        model: ModelParam = self._select_model_from_preferences(
+            params.model_preferences
+        )
+
+        # Convert MCP tools to Anthropic format
+        anthropic_tools: list[ToolParam] | None = None
+        if params.tools:
+            anthropic_tools = self._convert_tools_to_anthropic(params.tools)
+
+        # Convert tool_choice to Anthropic format
+        # Returns None if mode is "none", signaling tools should be omitted
+        anthropic_tool_choice: ToolChoiceParam | None = None
+        if params.tool_choice:
+            converted = self._convert_tool_choice_to_anthropic(params.tool_choice)
+            if converted is None:
+                # tool_choice="none" means don't use tools
+                anthropic_tools = None
+            else:
+                anthropic_tool_choice = converted
+
+        # Build kwargs to avoid sentinel type compatibility issues across
+        # anthropic SDK versions (NotGiven vs Omit)
+        kwargs: dict[str, Any] = {
+            "model": model,
+            "messages": anthropic_messages,
+            "max_tokens": params.max_tokens,
+        }
+        if params.system_prompt is not None:
+            kwargs["system"] = params.system_prompt
+        if params.temperature is not None:
+            kwargs["temperature"] = params.temperature
+        if params.stop_sequences is not None:
+            kwargs["stop_sequences"] = params.stop_sequences
+        if anthropic_tools is not None:
+            kwargs["tools"] = anthropic_tools
+        if anthropic_tool_choice is not None:
+            kwargs["tool_choice"] = anthropic_tool_choice
+
+        response = await self.client.messages.create(**kwargs)
+
+        # Return appropriate result type based on whether tools were provided
+        if params.tools:
+            return self._message_to_result_with_tools(response)
+        return self._message_to_create_message_result(response)
+
+    @staticmethod
+    def _iter_models_from_preferences(
+        model_preferences: ModelPreferences | str | list[str] | None,
+    ) -> Iterator[str]:
+        if model_preferences is None:
+            return
+
+        if isinstance(model_preferences, str):
+            yield model_preferences
+
+        elif isinstance(model_preferences, list):
+            yield from model_preferences
+
+        elif isinstance(model_preferences, ModelPreferences):
+            if not (hints := model_preferences.hints):
+                return
+
+            for hint in hints:
+                if not (name := hint.name):
+                    continue
+
+                yield name
+
+    @staticmethod
+    def _convert_to_anthropic_messages(
+        messages: Sequence[SamplingMessage],
+    ) -> list[MessageParam]:
+        anthropic_messages: list[MessageParam] = []
+
+        for message in messages:
+            content = message.content
+
+            # Handle list content (from CreateMessageResultWithTools)
+            if isinstance(content, list):
+                content_blocks: list[
+                    TextBlockParam
+                    | ImageBlockParam
+                    | ToolUseBlockParam
+                    | ToolResultBlockParam
+                ] = []
+
+                for item in content:
+                    if isinstance(item, ToolUseContent):
+                        content_blocks.append(
+                            ToolUseBlockParam(
+                                type="tool_use",
+                                id=item.id,
+                                name=item.name,
+                                input=item.input,
+                            )
+                        )
+                    elif isinstance(item, TextContent):
+                        content_blocks.append(
+                            TextBlockParam(type="text", text=item.text)
+                        )
+                    elif isinstance(item, ImageContent):
+                        if message.role != "user":
+                            raise ValueError(
+                                "ImageContent is only supported in user messages "
+                                "for Anthropic"
+                            )
+                        content_blocks.append(_image_content_to_anthropic_block(item))
+                    elif isinstance(item, AudioContent):
+                        raise ValueError(
+                            "AudioContent is not supported by the Anthropic API"
+                        )
+                    elif isinstance(item, ToolResultContent):
+                        # Extract text content from the result
+                        result_content: str | list[TextBlockParam] = ""
+                        if item.content:
+                            text_blocks: list[TextBlockParam] = [
+                                TextBlockParam(type="text", text=sub_item.text)
+                                for sub_item in item.content
+                                if isinstance(sub_item, TextContent)
+                            ]
+                            if len(text_blocks) == 1:
+                                result_content = text_blocks[0]["text"]
+                            elif text_blocks:
+                                result_content = text_blocks
+
+                        content_blocks.append(
+                            ToolResultBlockParam(
+                                type="tool_result",
+                                tool_use_id=item.tool_use_id,
+                                content=result_content,
+                                is_error=item.is_error if item.is_error else False,
+                            )
+                        )
+                    else:
+                        raise ValueError(
+                            f"Unsupported content type for Anthropic: {type(item).__name__}"
+                        )
+
+                if content_blocks:
+                    anthropic_messages.append(
+                        MessageParam(
+                            role=message.role,
+                            content=content_blocks,
+                        )
+                    )
+                continue
+
+            # Handle ToolUseContent (assistant's tool calls)
+            if isinstance(content, ToolUseContent):
+                anthropic_messages.append(
+                    MessageParam(
+                        role="assistant",
+                        content=[
+                            ToolUseBlockParam(
+                                type="tool_use",
+                                id=content.id,
+                                name=content.name,
+                                input=content.input,
+                            )
+                        ],
+                    )
+                )
+                continue
+
+            # Handle ToolResultContent (user's tool results)
+            if isinstance(content, ToolResultContent):
+                result_content_str: str | list[TextBlockParam] = ""
+                if content.content:
+                    text_parts: list[TextBlockParam] = [
+                        TextBlockParam(type="text", text=item.text)
+                        for item in content.content
+                        if isinstance(item, TextContent)
+                    ]
+                    if len(text_parts) == 1:
+                        result_content_str = text_parts[0]["text"]
+                    elif text_parts:
+                        result_content_str = text_parts
+
+                anthropic_messages.append(
+                    MessageParam(
+                        role="user",
+                        content=[
+                            ToolResultBlockParam(
+                                type="tool_result",
+                                tool_use_id=content.tool_use_id,
+                                content=result_content_str,
+                                is_error=content.is_error
+                                if content.is_error
+                                else False,
+                            )
+                        ],
+                    )
+                )
+                continue
+
+            # Handle TextContent
+            if isinstance(content, TextContent):
+                anthropic_messages.append(
+                    MessageParam(
+                        role=message.role,
+                        content=content.text,
+                    )
+                )
+                continue
+
+            # Handle ImageContent
+            if isinstance(content, ImageContent):
+                if message.role != "user":
+                    raise ValueError(
+                        "ImageContent is only supported in user messages for Anthropic"
+                    )
+                anthropic_messages.append(
+                    MessageParam(
+                        role="user",
+                        content=[_image_content_to_anthropic_block(content)],
+                    )
+                )
+                continue
+
+            # Handle AudioContent - not supported by Anthropic
+            if isinstance(content, AudioContent):
+                raise ValueError("AudioContent is not supported by the Anthropic API")
+
+            raise ValueError(f"Unsupported content type: {type(content)}")
+
+        return anthropic_messages
+
+    @staticmethod
+    def _message_to_create_message_result(
+        message: Message,
+    ) -> CreateMessageResult:
+        if len(message.content) == 0:
+            raise ValueError("No content in response from Anthropic")
+
+        # Join all text blocks to avoid dropping content
+        text = "".join(
+            block.text for block in message.content if isinstance(block, TextBlock)
+        )
+        if text:
+            return CreateMessageResult(
+                content=TextContent(type="text", text=text),
+                role="assistant",
+                model=message.model,
+            )
+
+        raise ValueError(
+            f"No text content in response from Anthropic: {[type(b).__name__ for b in message.content]}"
+        )
+
+    def _select_model_from_preferences(
+        self, model_preferences: ModelPreferences | str | list[str] | None
+    ) -> ModelParam:
+        for model_option in self._iter_models_from_preferences(model_preferences):
+            # Accept any model that starts with "claude"
+            if model_option.startswith("claude"):
+                return model_option
+
+        return self.default_model
+
+    @staticmethod
+    def _convert_tools_to_anthropic(tools: list[Tool]) -> list[ToolParam]:
+        """Convert MCP tools to Anthropic tool format."""
+        anthropic_tools: list[ToolParam] = []
+        for tool in tools:
+            # Build input_schema dict, ensuring required fields
+            input_schema: dict[str, Any] = dict(tool.input_schema)
+            if "type" not in input_schema:
+                input_schema["type"] = "object"
+
+            anthropic_tools.append(
+                ToolParam(
+                    name=tool.name,
+                    description=tool.description or "",
+                    input_schema=input_schema,
+                )
+            )
+        return anthropic_tools
+
+    @staticmethod
+    def _convert_tool_choice_to_anthropic(
+        tool_choice: ToolChoice,
+    ) -> ToolChoiceParam | None:
+        """Convert MCP tool_choice to Anthropic format.
+
+        Returns None for "none" mode, signaling that tools should be omitted
+        from the request entirely (Anthropic doesn't have an explicit "none" option).
+        """
+        if tool_choice.mode == "auto":
+            return ToolChoiceAutoParam(type="auto")
+        elif tool_choice.mode == "required":
+            return ToolChoiceAnyParam(type="any")
+        elif tool_choice.mode == "none":
+            # Anthropic doesn't have a "none" option - return None to signal
+            # that tools should be omitted from the request entirely
+            return None
+        else:
+            raise ValueError(f"Unsupported tool_choice mode: {tool_choice.mode!r}")
+
+    @staticmethod
+    def _message_to_result_with_tools(
+        message: Message,
+    ) -> CreateMessageResultWithTools:
+        """Convert Anthropic response to CreateMessageResultWithTools."""
+        if len(message.content) == 0:
+            raise ValueError("No content in response from Anthropic")
+
+        # Determine stop reason
+        stop_reason: StopReason
+        if message.stop_reason == "tool_use":
+            stop_reason = "toolUse"
+        elif message.stop_reason == "end_turn":
+            stop_reason = "endTurn"
+        elif message.stop_reason == "max_tokens":
+            stop_reason = "maxTokens"
+        elif message.stop_reason == "stop_sequence":
+            stop_reason = "endTurn"
+        else:
+            stop_reason = "endTurn"
+
+        # Build content list
+        content: list[SamplingMessageContentBlock] = []
+
+        for block in message.content:
+            if isinstance(block, TextBlock):
+                content.append(TextContent(type="text", text=block.text))
+            elif isinstance(block, ToolUseBlock):
+                # Anthropic returns input as dict directly
+                arguments = block.input if isinstance(block.input, dict) else {}
+
+                content.append(
+                    ToolUseContent(
+                        type="tool_use",
+                        id=block.id,
+                        name=block.name,
+                        input=arguments,
+                    )
+                )
+
+        # Must have at least some content
+        if not content:
+            raise ValueError("No content in response from Anthropic")
+
+        return CreateMessageResultWithTools(
+            content=content,
+            role="assistant",
+            model=message.model,
+            stop_reason=stop_reason,
+        )
diff --git a/fastmcp_slim/fastmcp/client/sampling/handlers/google_genai.py b/fastmcp_slim/fastmcp/client/sampling/handlers/google_genai.py
new file mode 100644
index 0000000..d79e98b
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/sampling/handlers/google_genai.py
@@ -0,0 +1,404 @@
+"""Google GenAI sampling handler with tool support for FastMCP 3.0."""
+
+import base64
+from collections.abc import Sequence
+from uuid import uuid4
+
+try:
+    from google.genai import Client as GoogleGenaiClient
+    from google.genai.types import (
+        Blob,
+        Candidate,
+        Content,
+        FunctionCall,
+        FunctionCallingConfig,
+        FunctionCallingConfigMode,
+        FunctionDeclaration,
+        FunctionResponse,
+        GenerateContentConfig,
+        GenerateContentResponse,
+        ModelContent,
+        Part,
+        ThinkingConfig,
+        ToolConfig,
+        UserContent,
+    )
+    from google.genai.types import Tool as GoogleTool
+except ImportError as e:
+    raise ImportError(
+        "The `google-genai` package is not installed. "
+        "Install it with `pip install fastmcp-slim[gemini]` or add `google-genai` "
+        "to your dependencies."
+    ) from e
+
+from mcp import ClientSession, ServerSession
+from mcp_types import (
+    AudioContent,
+    CreateMessageResult,
+    CreateMessageResultWithTools,
+    ImageContent,
+    ModelPreferences,
+    SamplingMessage,
+    SamplingMessageContentBlock,
+    StopReason,
+    TextContent,
+    ToolChoice,
+    ToolResultContent,
+    ToolUseContent,
+)
+from mcp_types import CreateMessageRequestParams as SamplingParams
+from mcp_types import Tool as MCPTool
+
+from fastmcp.client._sdk_context_shim import LifespanContextT, RequestContext
+
+__all__ = ["GoogleGenaiSamplingHandler"]
+
+
+class GoogleGenaiSamplingHandler:
+    """Sampling handler that uses the Google GenAI API with tool support.
+
+    Example:
+        ```python
+        from google.genai import Client
+        from fastmcp import FastMCP
+        from fastmcp.client.sampling.handlers.google_genai import (
+            GoogleGenaiSamplingHandler,
+        )
+
+        handler = GoogleGenaiSamplingHandler(
+            default_model="gemini-2.0-flash",
+            client=Client(),
+        )
+
+        server = FastMCP(sampling_handler=handler)
+        ```
+    """
+
+    def __init__(
+        self,
+        default_model: str,
+        client: GoogleGenaiClient | None = None,
+        thinking_budget: int | None = None,
+    ) -> None:
+        self.client: GoogleGenaiClient = client or GoogleGenaiClient()
+        self.default_model: str = default_model
+        self.thinking_budget: int | None = thinking_budget
+
+    async def __call__(
+        self,
+        messages: list[SamplingMessage],
+        params: SamplingParams,
+        context: RequestContext[ServerSession, LifespanContextT]
+        | RequestContext[ClientSession, LifespanContextT],
+    ) -> CreateMessageResult | CreateMessageResultWithTools:
+        contents: list[Content] = _convert_messages_to_google_genai_content(messages)
+
+        # Convert MCP tools to Google GenAI format
+        google_tools: list[GoogleTool] | None = None
+        tool_config: ToolConfig | None = None
+
+        if params.tools:
+            google_tools = [
+                _convert_tool_to_google_genai(tool) for tool in params.tools
+            ]
+            tool_config = _convert_tool_choice_to_google_genai(params.tool_choice)
+
+        # Select the model based on preferences
+        selected_model = self._get_model(model_preferences=params.model_preferences)
+
+        # Configure thinking if a budget is specified
+        thinking_config = (
+            ThinkingConfig(thinking_budget=self.thinking_budget)
+            if self.thinking_budget is not None
+            else None
+        )
+
+        response: GenerateContentResponse = (
+            await self.client.aio.models.generate_content(
+                model=selected_model,
+                contents=contents,
+                config=GenerateContentConfig(
+                    system_instruction=params.system_prompt,
+                    temperature=params.temperature,
+                    max_output_tokens=params.max_tokens,
+                    stop_sequences=params.stop_sequences,
+                    thinking_config=thinking_config,
+                    tools=google_tools,  # ty: ignore[invalid-argument-type]
+                    tool_config=tool_config,
+                ),
+            )
+        )
+
+        # Return appropriate result type based on whether tools were provided
+        if params.tools:
+            return _response_to_result_with_tools(response, selected_model)
+        return _response_to_create_message_result(response, selected_model)
+
+    def _get_model(self, model_preferences: ModelPreferences | None) -> str:
+        if model_preferences and model_preferences.hints:
+            for hint in model_preferences.hints:
+                if hint.name and hint.name.startswith("gemini"):
+                    return hint.name
+        return self.default_model
+
+
+def _convert_tool_to_google_genai(tool: MCPTool) -> GoogleTool:
+    """Convert an MCP Tool to Google GenAI format.
+
+    We prune ``title`` fields from the schema because Gemini 2.5 Flash
+    produces ``MALFORMED_FUNCTION_CALL`` when Pydantic's auto-generated
+    title annotations are present.
+    """
+    from fastmcp.utilities.json_schema import compress_schema
+
+    schema = compress_schema(tool.input_schema, prune_titles=True)
+    return GoogleTool(
+        function_declarations=[
+            FunctionDeclaration(
+                name=tool.name,
+                description=tool.description or "",
+                parameters_json_schema=schema,
+            )
+        ]
+    )
+
+
+def _convert_tool_choice_to_google_genai(tool_choice: ToolChoice | None) -> ToolConfig:
+    """Convert MCP ToolChoice to Google GenAI ToolConfig."""
+    if tool_choice is None:
+        return ToolConfig(
+            function_calling_config=FunctionCallingConfig(
+                mode=FunctionCallingConfigMode.AUTO
+            )
+        )
+
+    if tool_choice.mode == "required":
+        return ToolConfig(
+            function_calling_config=FunctionCallingConfig(
+                mode=FunctionCallingConfigMode.ANY
+            )
+        )
+    if tool_choice.mode == "none":
+        return ToolConfig(
+            function_calling_config=FunctionCallingConfig(
+                mode=FunctionCallingConfigMode.NONE
+            )
+        )
+
+    # Default to AUTO for "auto" or any other value
+    return ToolConfig(
+        function_calling_config=FunctionCallingConfig(
+            mode=FunctionCallingConfigMode.AUTO
+        )
+    )
+
+
+def _sampling_content_to_google_genai_part(
+    content: TextContent
+    | ImageContent
+    | AudioContent
+    | ToolUseContent
+    | ToolResultContent,
+) -> Part:
+    """Convert MCP content to Google GenAI Part."""
+    if isinstance(content, TextContent):
+        return Part(text=content.text)
+
+    if isinstance(content, ImageContent):
+        return Part(
+            inline_data=Blob(
+                data=base64.b64decode(content.data),
+                mime_type=content.mime_type,
+            )
+        )
+
+    if isinstance(content, AudioContent):
+        return Part(
+            inline_data=Blob(
+                data=base64.b64decode(content.data),
+                mime_type=content.mime_type,
+            )
+        )
+
+    if isinstance(content, ToolUseContent):
+        # Note: thought_signature bypass is required for manually constructed tool calls.
+        # Google's Gemini 3+ models enforce thought signature validation for function calls.
+        # Since we're constructing these Parts from MCP protocol data (not from model responses),
+        # they lack legitimate signatures. The bypass value allows validation to pass.
+        # See: https://ai.google.dev/gemini-api/docs/thought-signatures
+        return Part(
+            function_call=FunctionCall(
+                name=content.name,
+                args=content.input,
+            ),
+            thought_signature=b"skip_thought_signature_validator",
+        )
+
+    if isinstance(content, ToolResultContent):
+        # Extract text from tool result content
+        result_parts: list[str] = []
+        if content.content:
+            for item in content.content:
+                if isinstance(item, TextContent):
+                    result_parts.append(item.text)
+                else:
+                    msg = f"Unsupported tool result content type: {type(item).__name__}"
+                    raise ValueError(msg)
+        result_text = "".join(result_parts)
+
+        # Extract function name from toolUseId
+        # Our IDs are formatted as "{function_name}_{uuid8}", so extract the name.
+        # Note: This is a limitation of MCP's ToolResultContent which only carries
+        # toolUseId, while Google's FunctionResponse requires the function name.
+        tool_use_id = content.tool_use_id
+        if "_" in tool_use_id:
+            # Split and rejoin all but the last part (the UUID suffix)
+            parts = tool_use_id.rsplit("_", 1)
+            function_name = parts[0]
+        else:
+            # Fallback: use the full ID as the name
+            function_name = tool_use_id
+
+        return Part(
+            function_response=FunctionResponse(
+                name=function_name,
+                response={"result": result_text},
+            )
+        )
+
+    msg = f"Unsupported content type: {type(content)}"
+    raise ValueError(msg)
+
+
+def _convert_messages_to_google_genai_content(
+    messages: Sequence[SamplingMessage],
+) -> list[Content]:
+    """Convert MCP messages to Google GenAI content."""
+    google_messages: list[Content] = []
+
+    for message in messages:
+        content = message.content
+
+        # Handle list content (tool calls + results)
+        if isinstance(content, list):
+            parts: list[Part] = [
+                _sampling_content_to_google_genai_part(item) for item in content
+            ]
+
+            if message.role == "user":
+                google_messages.append(UserContent(parts=parts))
+            elif message.role == "assistant":
+                google_messages.append(ModelContent(parts=parts))
+            else:
+                msg = f"Invalid message role: {message.role}"
+                raise ValueError(msg)
+            continue
+
+        # Handle single content item
+        part = _sampling_content_to_google_genai_part(content)
+
+        if message.role == "user":
+            google_messages.append(UserContent(parts=[part]))
+        elif message.role == "assistant":
+            google_messages.append(ModelContent(parts=[part]))
+        else:
+            msg = f"Invalid message role: {message.role}"
+            raise ValueError(msg)
+
+    return google_messages
+
+
+def _get_candidate_from_response(response: GenerateContentResponse) -> Candidate:
+    """Extract the first candidate from a response."""
+    if response.candidates and response.candidates[0]:
+        return response.candidates[0]
+    msg = "No candidate in response from completion."
+    raise ValueError(msg)
+
+
+def _response_to_create_message_result(
+    response: GenerateContentResponse,
+    model: str,
+) -> CreateMessageResult:
+    """Convert Google GenAI response to CreateMessageResult (no tools)."""
+    if not (text := response.text):
+        candidate = _get_candidate_from_response(response)
+        # Check if the response only contained thinking
+        has_thoughts = (
+            candidate.content
+            and candidate.content.parts
+            and all(getattr(p, "thought", False) for p in candidate.content.parts)
+        )
+        if has_thoughts:
+            msg = (
+                "Model returned only thinking/reasoning content with no response text."
+            )
+        else:
+            msg = f"No content in response (finish_reason={candidate.finish_reason})"
+        raise ValueError(msg)
+
+    return CreateMessageResult(
+        content=TextContent(type="text", text=text),
+        role="assistant",
+        model=model,
+    )
+
+
+def _response_to_result_with_tools(
+    response: GenerateContentResponse,
+    model: str,
+) -> CreateMessageResultWithTools:
+    """Convert Google GenAI response to CreateMessageResultWithTools."""
+    candidate = _get_candidate_from_response(response)
+
+    # Determine stop reason and check for function calls
+    stop_reason: StopReason
+    finish_reason = candidate.finish_reason
+    has_function_calls = False
+
+    if candidate.content and candidate.content.parts:
+        for part in candidate.content.parts:
+            if part.function_call is not None:
+                has_function_calls = True
+                break
+
+    if has_function_calls:
+        stop_reason = "toolUse"
+    elif finish_reason == "STOP":
+        stop_reason = "endTurn"
+    elif finish_reason == "MAX_TOKENS":
+        stop_reason = "maxTokens"
+    else:
+        stop_reason = "endTurn"
+
+    # Build content list
+    content: list[SamplingMessageContentBlock] = []
+
+    if candidate.content and candidate.content.parts:
+        for part in candidate.content.parts:
+            # Note: Skip thought parts from thinking_config - not relevant for MCP responses
+            if part.text and not part.thought:
+                content.append(TextContent(type="text", text=part.text))
+            elif part.function_call is not None:
+                fc = part.function_call
+                fc_name: str = fc.name or "unknown"
+                content.append(
+                    ToolUseContent(
+                        type="tool_use",
+                        id=f"{fc_name}_{uuid4().hex[:8]}",  # Generate unique ID
+                        name=fc_name,
+                        input=dict(fc.args) if fc.args else {},
+                    )
+                )
+
+    if not content:
+        finish = candidate.finish_reason if candidate else "unknown"
+        msg = f"No content in response from completion (finish_reason={finish})"
+        raise ValueError(msg)
+
+    return CreateMessageResultWithTools(
+        content=content,
+        role="assistant",
+        model=model,
+        stop_reason=stop_reason,
+    )
diff --git a/fastmcp_slim/fastmcp/client/sampling/handlers/openai.py b/fastmcp_slim/fastmcp/client/sampling/handlers/openai.py
new file mode 100644
index 0000000..af54ba0
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/sampling/handlers/openai.py
@@ -0,0 +1,514 @@
+"""OpenAI sampling handler for FastMCP."""
+
+import json
+from collections.abc import Iterator, Sequence
+from typing import Any, Literal, get_args
+
+from mcp import ClientSession, ServerSession
+from mcp_types import (
+    AudioContent,
+    CreateMessageResult,
+    CreateMessageResultWithTools,
+    ImageContent,
+    ModelPreferences,
+    SamplingMessage,
+    StopReason,
+    TextContent,
+    Tool,
+    ToolChoice,
+    ToolResultContent,
+    ToolUseContent,
+)
+from mcp_types import CreateMessageRequestParams as SamplingParams
+
+from fastmcp.client._sdk_context_shim import LifespanContextT, RequestContext
+
+try:
+    from openai import AsyncOpenAI
+    from openai.types.chat import (
+        ChatCompletion,
+        ChatCompletionAssistantMessageParam,
+        ChatCompletionContentPartImageParam,
+        ChatCompletionContentPartInputAudioParam,
+        ChatCompletionContentPartParam,
+        ChatCompletionContentPartTextParam,
+        ChatCompletionMessageParam,
+        ChatCompletionMessageToolCallParam,
+        ChatCompletionSystemMessageParam,
+        ChatCompletionToolChoiceOptionParam,
+        ChatCompletionToolMessageParam,
+        ChatCompletionToolParam,
+        ChatCompletionUserMessageParam,
+    )
+    from openai.types.shared.chat_model import ChatModel
+    from openai.types.shared_params import FunctionDefinition
+except ImportError as e:
+    raise ImportError(
+        "The `openai` package is not installed. "
+        "Please install `fastmcp-slim[openai]` or add `openai` to your dependencies manually."
+    ) from e
+
+# OpenAI only supports wav and mp3 for input audio
+_OPENAI_AUDIO_FORMATS: dict[str, Literal["wav", "mp3"]] = {
+    "audio/wav": "wav",
+    "audio/x-wav": "wav",
+    "audio/mp3": "mp3",
+    "audio/mpeg": "mp3",
+}
+
+_OPENAI_IMAGE_MEDIA_TYPES: frozenset[str] = frozenset(
+    {"image/jpeg", "image/png", "image/gif", "image/webp"}
+)
+
+
+def _image_content_to_openai_part(
+    content: ImageContent,
+) -> ChatCompletionContentPartImageParam:
+    """Convert MCP ImageContent to OpenAI image_url content part."""
+    if content.mime_type not in _OPENAI_IMAGE_MEDIA_TYPES:
+        raise ValueError(
+            f"Unsupported image MIME type for OpenAI: {content.mime_type!r}. "
+            f"Supported types: {', '.join(sorted(_OPENAI_IMAGE_MEDIA_TYPES))}"
+        )
+    data_url = f"data:{content.mime_type};base64,{content.data}"
+    return ChatCompletionContentPartImageParam(
+        type="image_url",
+        image_url={"url": data_url},
+    )
+
+
+def _audio_content_to_openai_part(
+    content: AudioContent,
+) -> ChatCompletionContentPartInputAudioParam:
+    """Convert MCP AudioContent to OpenAI input_audio content part."""
+    audio_format = _OPENAI_AUDIO_FORMATS.get(content.mime_type)
+    if audio_format is None:
+        raise ValueError(
+            f"Unsupported audio MIME type for OpenAI: {content.mime_type!r}. "
+            f"Supported types: {', '.join(sorted(_OPENAI_AUDIO_FORMATS))}"
+        )
+    return ChatCompletionContentPartInputAudioParam(
+        type="input_audio",
+        input_audio={"data": content.data, "format": audio_format},
+    )
+
+
+class OpenAISamplingHandler:
+    """Sampling handler that uses the OpenAI API."""
+
+    def __init__(
+        self,
+        default_model: ChatModel,
+        client: AsyncOpenAI | None = None,
+    ) -> None:
+        self.client: AsyncOpenAI = client or AsyncOpenAI()
+        self.default_model: ChatModel = default_model
+
+    async def __call__(
+        self,
+        messages: list[SamplingMessage],
+        params: SamplingParams,
+        context: RequestContext[ServerSession, LifespanContextT]
+        | RequestContext[ClientSession, LifespanContextT],
+    ) -> CreateMessageResult | CreateMessageResultWithTools:
+        openai_messages: list[ChatCompletionMessageParam] = (
+            self._convert_to_openai_messages(
+                system_prompt=params.system_prompt,
+                messages=messages,
+            )
+        )
+
+        model: ChatModel = self._select_model_from_preferences(params.model_preferences)
+
+        # Convert MCP tools to OpenAI format
+        openai_tools: list[ChatCompletionToolParam] | None = None
+        if params.tools:
+            openai_tools = self._convert_tools_to_openai(params.tools)
+
+        # Convert tool_choice to OpenAI format
+        openai_tool_choice: ChatCompletionToolChoiceOptionParam | None = None
+        if params.tool_choice:
+            openai_tool_choice = self._convert_tool_choice_to_openai(params.tool_choice)
+
+        # Build kwargs to avoid sentinel type compatibility issues across
+        # openai SDK versions (NotGiven vs Omit)
+        kwargs: dict[str, Any] = {
+            "model": model,
+            "messages": openai_messages,
+        }
+        if params.max_tokens is not None:
+            kwargs["max_completion_tokens"] = params.max_tokens
+        if params.temperature is not None:
+            kwargs["temperature"] = params.temperature
+        if params.stop_sequences:
+            kwargs["stop"] = params.stop_sequences
+        if openai_tools is not None:
+            kwargs["tools"] = openai_tools
+        if openai_tool_choice is not None:
+            kwargs["tool_choice"] = openai_tool_choice
+
+        response = await self.client.chat.completions.create(**kwargs)
+
+        # Return appropriate result type based on whether tools were provided
+        if params.tools:
+            return self._chat_completion_to_result_with_tools(response)
+        return self._chat_completion_to_create_message_result(response)
+
+    @staticmethod
+    def _iter_models_from_preferences(
+        model_preferences: ModelPreferences | str | list[str] | None,
+    ) -> Iterator[str]:
+        if model_preferences is None:
+            return
+
+        if isinstance(model_preferences, str) and model_preferences in get_args(
+            ChatModel
+        ):
+            yield model_preferences
+
+        elif isinstance(model_preferences, list):
+            yield from model_preferences
+
+        elif isinstance(model_preferences, ModelPreferences):
+            if not (hints := model_preferences.hints):
+                return
+
+            for hint in hints:
+                if not (name := hint.name):
+                    continue
+
+                yield name
+
+    @staticmethod
+    def _convert_to_openai_messages(
+        system_prompt: str | None, messages: Sequence[SamplingMessage]
+    ) -> list[ChatCompletionMessageParam]:
+        openai_messages: list[ChatCompletionMessageParam] = []
+
+        if system_prompt:
+            openai_messages.append(
+                ChatCompletionSystemMessageParam(
+                    role="system",
+                    content=system_prompt,
+                )
+            )
+
+        for message in messages:
+            content = message.content
+
+            # Handle list content (from CreateMessageResultWithTools)
+            if isinstance(content, list):
+                # Collect tool calls, content parts, and text from the list
+                tool_calls: list[ChatCompletionMessageToolCallParam] = []
+                content_parts: list[ChatCompletionContentPartParam] = []
+                text_parts: list[str] = []
+                # Collect tool results separately to maintain correct ordering
+                tool_messages: list[ChatCompletionToolMessageParam] = []
+
+                for item in content:
+                    if isinstance(item, ToolUseContent):
+                        tool_calls.append(
+                            ChatCompletionMessageToolCallParam(
+                                id=item.id,
+                                type="function",
+                                function={
+                                    "name": item.name,
+                                    "arguments": json.dumps(item.input),
+                                },
+                            )
+                        )
+                    elif isinstance(item, TextContent):
+                        text_parts.append(item.text)
+                        content_parts.append(
+                            ChatCompletionContentPartTextParam(
+                                type="text", text=item.text
+                            )
+                        )
+                    elif isinstance(item, ImageContent):
+                        content_parts.append(_image_content_to_openai_part(item))
+                    elif isinstance(item, AudioContent):
+                        content_parts.append(_audio_content_to_openai_part(item))
+                    elif isinstance(item, ToolResultContent):
+                        # Collect tool results (added after assistant message)
+                        content_text = ""
+                        if item.content:
+                            result_texts = [
+                                sub_item.text
+                                for sub_item in item.content
+                                if isinstance(sub_item, TextContent)
+                            ]
+                            content_text = "\n".join(result_texts)
+                        tool_messages.append(
+                            ChatCompletionToolMessageParam(
+                                role="tool",
+                                tool_call_id=item.tool_use_id,
+                                content=content_text,
+                            )
+                        )
+                    else:
+                        raise ValueError(
+                            f"Unsupported content type for OpenAI: {type(item).__name__}"
+                        )
+
+                # Add assistant message with tool calls if present
+                # OpenAI requires: assistant (with tool_calls) -> tool messages
+                if tool_calls or content_parts:
+                    if tool_calls:
+                        has_multimodal = len(content_parts) > len(text_parts)
+                        if has_multimodal:
+                            raise ValueError(
+                                "ImageContent/AudioContent is only supported "
+                                "in user messages for OpenAI"
+                            )
+                        text_str = "\n".join(text_parts) or None
+                        openai_messages.append(
+                            ChatCompletionAssistantMessageParam(
+                                role="assistant",
+                                content=text_str,
+                                tool_calls=tool_calls,
+                            )
+                        )
+                        # Add tool messages AFTER assistant message
+                        openai_messages.extend(tool_messages)
+                    elif content_parts:
+                        if message.role == "user":
+                            openai_messages.append(
+                                ChatCompletionUserMessageParam(
+                                    role="user",
+                                    content=content_parts,
+                                )
+                            )
+                        else:
+                            has_multimodal = len(content_parts) > len(text_parts)
+                            if has_multimodal:
+                                raise ValueError(
+                                    "ImageContent/AudioContent is only supported "
+                                    "in user messages for OpenAI"
+                                )
+                            assistant_text = "\n".join(text_parts)
+                            if assistant_text:
+                                openai_messages.append(
+                                    ChatCompletionAssistantMessageParam(
+                                        role="assistant",
+                                        content=assistant_text,
+                                    )
+                                )
+                elif tool_messages:
+                    # Tool results only (assistant message was in previous message)
+                    openai_messages.extend(tool_messages)
+                continue
+
+            # Handle ToolUseContent (assistant's tool calls)
+            if isinstance(content, ToolUseContent):
+                openai_messages.append(
+                    ChatCompletionAssistantMessageParam(
+                        role="assistant",
+                        tool_calls=[
+                            ChatCompletionMessageToolCallParam(
+                                id=content.id,
+                                type="function",
+                                function={
+                                    "name": content.name,
+                                    "arguments": json.dumps(content.input),
+                                },
+                            )
+                        ],
+                    )
+                )
+                continue
+
+            # Handle ToolResultContent (user's tool results)
+            if isinstance(content, ToolResultContent):
+                # Extract text parts from the content list
+                result_texts: list[str] = []
+                if content.content:
+                    for item in content.content:
+                        if isinstance(item, TextContent):
+                            result_texts.append(item.text)
+                openai_messages.append(
+                    ChatCompletionToolMessageParam(
+                        role="tool",
+                        tool_call_id=content.tool_use_id,
+                        content="\n".join(result_texts),
+                    )
+                )
+                continue
+
+            # Handle TextContent
+            if isinstance(content, TextContent):
+                if message.role == "user":
+                    openai_messages.append(
+                        ChatCompletionUserMessageParam(
+                            role="user",
+                            content=content.text,
+                        )
+                    )
+                else:
+                    openai_messages.append(
+                        ChatCompletionAssistantMessageParam(
+                            role="assistant",
+                            content=content.text,
+                        )
+                    )
+                continue
+
+            # Handle ImageContent
+            if isinstance(content, ImageContent):
+                if message.role != "user":
+                    raise ValueError(
+                        "ImageContent is only supported in user messages for OpenAI"
+                    )
+                openai_messages.append(
+                    ChatCompletionUserMessageParam(
+                        role="user",
+                        content=[_image_content_to_openai_part(content)],
+                    )
+                )
+                continue
+
+            # Handle AudioContent
+            if isinstance(content, AudioContent):
+                if message.role != "user":
+                    raise ValueError(
+                        "AudioContent is only supported in user messages for OpenAI"
+                    )
+                openai_messages.append(
+                    ChatCompletionUserMessageParam(
+                        role="user",
+                        content=[_audio_content_to_openai_part(content)],
+                    )
+                )
+                continue
+
+            raise ValueError(f"Unsupported content type: {type(content)}")
+
+        return openai_messages
+
+    @staticmethod
+    def _chat_completion_to_create_message_result(
+        chat_completion: ChatCompletion,
+    ) -> CreateMessageResult:
+        if len(chat_completion.choices) == 0:
+            raise ValueError("No response for completion")
+
+        first_choice = chat_completion.choices[0]
+
+        if content := first_choice.message.content:
+            return CreateMessageResult(
+                content=TextContent(type="text", text=content),
+                role="assistant",
+                model=chat_completion.model,
+            )
+
+        raise ValueError("No content in response from completion")
+
+    def _select_model_from_preferences(
+        self, model_preferences: ModelPreferences | str | list[str] | None
+    ) -> ChatModel:
+        for model_option in self._iter_models_from_preferences(model_preferences):
+            if model_option in get_args(ChatModel):
+                chosen_model: ChatModel = model_option  # type: ignore[assignment]  # ty:ignore[invalid-assignment]
+                return chosen_model
+
+        return self.default_model
+
+    @staticmethod
+    def _convert_tools_to_openai(tools: list[Tool]) -> list[ChatCompletionToolParam]:
+        """Convert MCP tools to OpenAI tool format."""
+        openai_tools: list[ChatCompletionToolParam] = []
+        for tool in tools:
+            # Build parameters dict, ensuring required fields
+            parameters: dict[str, Any] = dict(tool.input_schema)
+            if "type" not in parameters:
+                parameters["type"] = "object"
+
+            openai_tools.append(
+                ChatCompletionToolParam(
+                    type="function",
+                    function=FunctionDefinition(
+                        name=tool.name,
+                        description=tool.description or "",
+                        parameters=parameters,
+                    ),
+                )
+            )
+        return openai_tools
+
+    @staticmethod
+    def _convert_tool_choice_to_openai(
+        tool_choice: ToolChoice,
+    ) -> ChatCompletionToolChoiceOptionParam:
+        """Convert MCP tool_choice to OpenAI format."""
+        if tool_choice.mode == "auto":
+            return "auto"
+        elif tool_choice.mode == "required":
+            return "required"
+        elif tool_choice.mode == "none":
+            return "none"
+        else:
+            raise ValueError(f"Unsupported tool_choice mode: {tool_choice.mode!r}")
+
+    @staticmethod
+    def _chat_completion_to_result_with_tools(
+        chat_completion: ChatCompletion,
+    ) -> CreateMessageResultWithTools:
+        """Convert OpenAI response to CreateMessageResultWithTools."""
+        if len(chat_completion.choices) == 0:
+            raise ValueError("No response for completion")
+
+        first_choice = chat_completion.choices[0]
+        message = first_choice.message
+
+        # Determine stop reason
+        stop_reason: StopReason
+        if first_choice.finish_reason == "tool_calls":
+            stop_reason = "toolUse"
+        elif first_choice.finish_reason == "stop":
+            stop_reason = "endTurn"
+        elif first_choice.finish_reason == "length":
+            stop_reason = "maxTokens"
+        else:
+            stop_reason = "endTurn"
+
+        # Build content list
+        content: list[TextContent | ToolUseContent] = []
+
+        # Add text content if present
+        if message.content:
+            content.append(TextContent(type="text", text=message.content))
+
+        # Add tool calls if present
+        if message.tool_calls:
+            for tool_call in message.tool_calls:
+                # Skip non-function tool calls
+                if not hasattr(tool_call, "function"):
+                    continue
+                func = tool_call.function
+                # Parse the arguments JSON string
+                try:
+                    arguments = json.loads(func.arguments)  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+                except json.JSONDecodeError as e:
+                    raise ValueError(
+                        f"Invalid JSON in tool arguments for "
+                        f"'{func.name}': {func.arguments}"  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+                    ) from e
+
+                content.append(
+                    ToolUseContent(
+                        type="tool_use",
+                        id=tool_call.id,
+                        name=func.name,  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+                        input=arguments,
+                    )
+                )
+
+        # Must have at least some content
+        if not content:
+            raise ValueError("No content in response from completion")
+
+        return CreateMessageResultWithTools(
+            content=content,  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+            role="assistant",
+            model=chat_completion.model,
+            stop_reason=stop_reason,
+        )
diff --git a/fastmcp_slim/fastmcp/client/tasks.py b/fastmcp_slim/fastmcp/client/tasks.py
new file mode 100644
index 0000000..ee3958f
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/tasks.py
@@ -0,0 +1,585 @@
+"""SEP-1686 client Task classes."""
+
+from __future__ import annotations
+
+import abc
+import asyncio
+import inspect
+import time
+import weakref
+from collections.abc import Awaitable, Callable
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+import mcp_types
+from mcp_types import GetTaskResult, TaskStatusNotification
+
+from fastmcp.client.messages import Message, MessageHandler
+from fastmcp.exceptions import ToolError
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+if TYPE_CHECKING:
+    from fastmcp.client.client import CallToolResult, Client
+
+
+class TaskNotificationHandler(MessageHandler):
+    """MessageHandler that routes task status notifications to Task objects."""
+
+    def __init__(self, client: Client):
+        super().__init__()
+        self._client_ref: weakref.ref[Client] = weakref.ref(client)
+
+    async def dispatch(self, message: Message) -> None:
+        """Dispatch messages, including task status notifications."""
+        # SDK v2 delivers notifications unwrapped (no `.root` wrapper).
+        if isinstance(message, TaskStatusNotification):
+            client = self._client_ref()
+            if client:
+                client._handle_task_status_notification(message)
+
+        await super().dispatch(message)
+
+
+TaskResultT = TypeVar("TaskResultT")
+
+
+class Task(abc.ABC, Generic[TaskResultT]):
+    """
+    Abstract base class for MCP background tasks (SEP-1686).
+
+    Provides a uniform API whether the server accepts background execution
+    or executes synchronously (graceful degradation per SEP-1686).
+
+    Subclasses:
+        - ToolTask: For tool calls (result type: CallToolResult)
+        - PromptTask: For prompts (future, result type: GetPromptResult)
+        - ResourceTask: For resources (future, result type: ReadResourceResult)
+    """
+
+    def __init__(
+        self,
+        client: Client,
+        task_id: str,
+        immediate_result: TaskResultT | None = None,
+    ):
+        """
+        Create a Task wrapper.
+
+        Args:
+            client: The FastMCP client
+            task_id: The task identifier
+            immediate_result: If server executed synchronously, the immediate result
+        """
+        self._client = client
+        self._task_id = task_id
+        self._immediate_result = immediate_result
+        self._is_immediate = immediate_result is not None
+
+        # Notification-based optimization (SEP-1686 notifications/tasks/status)
+        self._status_cache: GetTaskResult | None = None
+        self._status_event: asyncio.Event | None = None  # Lazy init
+        self._status_callbacks: list[
+            Callable[[GetTaskResult], None | Awaitable[None]]
+        ] = []
+        self._cached_result: TaskResultT | None = None
+
+    def _check_client_connected(self) -> None:
+        """Validate that client context is still active.
+
+        Raises:
+            RuntimeError: If accessed outside client context (unless immediate)
+        """
+        if self._is_immediate:
+            return  # Already resolved, no client needed
+
+        try:
+            _ = self._client.session
+        except RuntimeError as e:
+            raise RuntimeError(
+                "Cannot access task results outside client context. "
+                "Task futures must be used within 'async with client:' block."
+            ) from e
+
+    @property
+    def task_id(self) -> str:
+        """Get the task ID."""
+        return self._task_id
+
+    @property
+    def returned_immediately(self) -> bool:
+        """Check if server executed the task immediately.
+
+        Returns:
+            True if server executed synchronously (graceful degradation or no task support)
+            False if server accepted background execution
+        """
+        return self._is_immediate
+
+    def _handle_status_notification(self, status: GetTaskResult) -> None:
+        """Process incoming notifications/tasks/status (internal).
+
+        Called by Client when a notification is received for this task.
+        Updates cache, triggers events, and invokes user callbacks.
+
+        Args:
+            status: Task status from notification
+        """
+        # Update cache for next status() call
+        self._status_cache = status
+
+        # Wake up any wait() calls
+        if self._status_event is not None:
+            self._status_event.set()
+
+        # Invoke user callbacks
+        for callback in self._status_callbacks:
+            try:
+                result = callback(status)
+                if inspect.isawaitable(result):
+                    # Fire and forget async callbacks
+                    asyncio.create_task(result)  # type: ignore[arg-type] # noqa: RUF006  # ty:ignore[invalid-argument-type]
+            except Exception as e:
+                logger.warning(f"Task callback error: {e}", exc_info=True)
+
+    def on_status_change(
+        self,
+        callback: Callable[[GetTaskResult], None | Awaitable[None]],
+    ) -> None:
+        """Register callback for status change notifications.
+
+        The callback will be invoked when a notifications/tasks/status is received
+        for this task (optional server feature per SEP-1686 lines 436-444).
+
+        Supports both sync and async callbacks (auto-detected).
+
+        Args:
+            callback: Function to call with GetTaskResult when status changes.
+                     Can return None (sync) or Awaitable[None] (async).
+
+        Example:
+            >>> task = await client.call_tool("slow_operation", {}, task=True)
+            >>>
+            >>> def on_update(status: GetTaskResult):
+            ...     print(f"Task {status.task_id} is now {status.status}")
+            >>>
+            >>> task.on_status_change(on_update)
+            >>> result = await task  # Callback fires when status changes
+        """
+        self._status_callbacks.append(callback)
+
+    async def status(self) -> GetTaskResult:
+        """Get current task status.
+
+        If server executed immediately, returns synthetic completed status.
+        Otherwise queries the server for current status.
+        """
+        self._check_client_connected()
+
+        if self._is_immediate:
+            # Return synthetic completed status. SDK v2 types the task
+            # timestamps as ISO 8601 strings.
+            now = datetime.now(timezone.utc).isoformat()
+            return GetTaskResult(
+                task_id=self._task_id,
+                status="completed",
+                created_at=now,
+                last_updated_at=now,
+                ttl=None,
+                poll_interval=1000,
+            )
+
+        # Return cached status if available (from notification)
+        if self._status_cache is not None:
+            cached = self._status_cache
+            # Don't clear cache - keep it for next call
+            return cached
+
+        # Query server and cache the result
+        self._status_cache = await self._client.get_task_status(self._task_id)
+        return self._status_cache
+
+    @abc.abstractmethod
+    async def result(self) -> TaskResultT:
+        """Wait for and return the task result.
+
+        Must be implemented by subclasses to return the appropriate result type.
+        """
+        ...
+
+    async def wait(
+        self, *, state: str | None = None, timeout: float = 300.0
+    ) -> GetTaskResult:
+        """Wait for task to reach a specific state or complete.
+
+        Uses event-based waiting when notifications are available (fast),
+        with fallback to polling (reliable). Optimally wakes up immediately
+        on status changes when server sends notifications/tasks/status.
+
+        Args:
+            state: Desired state ('working', 'input_required', 'completed', 'failed', 'cancelled').
+                   If None, waits until the task exits the 'working' state (completed, failed, cancelled, input_required, etc.)
+            timeout: Maximum time to wait in seconds
+
+        Returns:
+            GetTaskResult: Final task status
+
+        Raises:
+            TimeoutError: If desired state not reached within timeout
+        """
+        self._check_client_connected()
+
+        if self._is_immediate:
+            # Already done
+            return await self.status()
+
+        # Initialize event for notification wake-ups
+        if self._status_event is None:
+            self._status_event = asyncio.Event()
+
+        start = time.time()
+        in_progress_states = {"working"}
+        poll_interval = 0.5  # Fallback polling interval (500ms)
+
+        while True:
+            # Check cached status first (updated by notifications)
+            if self._status_cache:
+                current = self._status_cache.status
+                if state is None:
+                    if current not in in_progress_states:
+                        return self._status_cache
+                elif current == state:
+                    return self._status_cache
+
+            # Check timeout
+            elapsed = time.time() - start
+            if elapsed >= timeout:
+                raise TimeoutError(
+                    f"Task {self._task_id} did not reach {state or 'terminal state'} within {timeout}s"
+                )
+
+            remaining = timeout - elapsed
+
+            # Wait for notification event OR poll timeout
+            try:
+                await asyncio.wait_for(
+                    self._status_event.wait(), timeout=min(poll_interval, remaining)
+                )
+                self._status_event.clear()
+            except asyncio.TimeoutError:
+                # Fallback: poll server (notification didn't arrive in time)
+                self._status_cache = await self._client.get_task_status(self._task_id)
+
+    async def _wait_terminal(self, timeout: float = 300.0) -> GetTaskResult:
+        """Wait until task reaches a terminal state (completed, failed, cancelled).
+
+        Unlike wait(), this will not return on input_required — it continues
+        waiting until the task fully resolves. Used internally by result().
+        """
+        terminal_states = {"completed", "failed", "cancelled"}
+        status = await self.wait(timeout=timeout)
+        while status.status not in terminal_states:
+            # Task is in a non-terminal state (e.g. input_required) — reset
+            # cache so the next wait() call blocks instead of returning immediately.
+            self._status_cache = None
+            status = await self.wait(timeout=timeout)
+        return status
+
+    async def cancel(self) -> None:
+        """Cancel this task, transitioning it to cancelled state.
+
+        Sends a tasks/cancel protocol request. The server will attempt to halt
+        execution and move the task to cancelled state.
+
+        Note: If server executed immediately (graceful degradation), this is a no-op
+        as there's no server-side task to cancel.
+        """
+        if self._is_immediate:
+            # No server-side task to cancel
+            return
+        self._check_client_connected()
+        await self._client.cancel_task(self._task_id)
+        # Invalidate cache to force fresh status fetch
+        self._status_cache = None
+
+    def __await__(self):
+        """Allow 'await task' to get result."""
+        return self.result().__await__()
+
+
+class ToolTask(Task["CallToolResult"]):
+    """
+    Represents a tool call that may execute in background or immediately.
+
+    Provides a uniform API whether the server accepts background execution
+    or executes synchronously (graceful degradation per SEP-1686).
+
+    Usage:
+        task = await client.call_tool_as_task("analyze", args)
+
+        # Check status
+        status = await task.status()
+
+        # Wait for completion
+        await task.wait()
+
+        # Get result (waits if needed)
+        result = await task.result()  # Returns CallToolResult
+
+        # Or just await the task directly
+        result = await task
+    """
+
+    def __init__(
+        self,
+        client: Client,
+        task_id: str,
+        tool_name: str,
+        immediate_result: CallToolResult | None = None,
+        raise_on_error: bool = True,
+    ):
+        """
+        Create a ToolTask wrapper.
+
+        Args:
+            client: The FastMCP client
+            task_id: The task identifier
+            tool_name: Name of the tool being executed
+            immediate_result: If server executed synchronously, the immediate result
+            raise_on_error: Whether task.result() should raise ToolError on errors
+        """
+        super().__init__(client, task_id, immediate_result)
+        self._tool_name = tool_name
+        self._raise_on_error = raise_on_error
+
+    async def result(self) -> CallToolResult:
+        """Wait for and return the tool result.
+
+        If server executed immediately, returns the immediate result.
+        Otherwise waits for background task to complete and retrieves result.
+
+        Returns:
+            CallToolResult: The parsed tool result (same as call_tool returns)
+        """
+        # Check cache first
+        if self._cached_result is not None:
+            return self._cached_result
+
+        if self._is_immediate:
+            assert self._immediate_result is not None  # Type narrowing
+            result = self._immediate_result
+            if result.is_error and self._raise_on_error:
+                if result.content and isinstance(
+                    result.content[0], mcp_types.TextContent
+                ):
+                    msg = result.content[0].text
+                else:
+                    msg = f"Tool '{self._tool_name}' returned an error"
+                raise ToolError(msg)
+        else:
+            # Check client connected
+            self._check_client_connected()
+
+            # Wait for completion using event-based wait (respects notifications)
+            await self._wait_terminal()
+
+            # Get the raw result (dict or CallToolResult)
+            raw_result = await self._client.get_task_result(self._task_id)
+
+            # Convert to CallToolResult if needed and parse
+            if isinstance(raw_result, dict):
+                # Raw dict from get_task_result - parse as CallToolResult
+                mcp_result = mcp_types.CallToolResult.model_validate(raw_result)
+                result = await self._client._parse_call_tool_result(
+                    self._tool_name,
+                    mcp_result,
+                    raise_on_error=self._raise_on_error,
+                )
+            elif isinstance(raw_result, mcp_types.CallToolResult):
+                # Already a CallToolResult from MCP protocol - parse it
+                result = await self._client._parse_call_tool_result(
+                    self._tool_name,
+                    raw_result,
+                    raise_on_error=self._raise_on_error,
+                )
+            else:
+                # Legacy ToolResult format - convert to MCP type
+                if hasattr(raw_result, "content") and hasattr(
+                    raw_result, "structured_content"
+                ):
+                    mcp_result = mcp_types.CallToolResult(
+                        content=raw_result.content,
+                        structured_content=raw_result.structured_content,
+                        _meta=raw_result.meta,  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
+                    )
+                    result = await self._client._parse_call_tool_result(
+                        self._tool_name,
+                        mcp_result,
+                        raise_on_error=self._raise_on_error,
+                    )
+                else:
+                    # Unknown type - just return it
+                    result = raw_result
+
+        # Cache before returning
+        self._cached_result = result
+        return result
+
+
+class PromptTask(Task[mcp_types.GetPromptResult]):
+    """
+    Represents a prompt call that may execute in background or immediately.
+
+    Provides a uniform API whether the server accepts background execution
+    or executes synchronously (graceful degradation per SEP-1686).
+
+    Usage:
+        task = await client.get_prompt_as_task("analyze", args)
+        result = await task  # Returns GetPromptResult
+    """
+
+    def __init__(
+        self,
+        client: Client,
+        task_id: str,
+        prompt_name: str,
+        immediate_result: mcp_types.GetPromptResult | None = None,
+    ):
+        """
+        Create a PromptTask wrapper.
+
+        Args:
+            client: The FastMCP client
+            task_id: The task identifier
+            prompt_name: Name of the prompt being executed
+            immediate_result: If server executed synchronously, the immediate result
+        """
+        super().__init__(client, task_id, immediate_result)
+        self._prompt_name = prompt_name
+
+    async def result(self) -> mcp_types.GetPromptResult:
+        """Wait for and return the prompt result.
+
+        If server executed immediately, returns the immediate result.
+        Otherwise waits for background task to complete and retrieves result.
+
+        Returns:
+            GetPromptResult: The prompt result with messages and description
+        """
+        # Check cache first
+        if self._cached_result is not None:
+            return self._cached_result
+
+        if self._is_immediate:
+            assert self._immediate_result is not None
+            result = self._immediate_result
+        else:
+            # Check client connected
+            self._check_client_connected()
+
+            # Wait for completion using event-based wait (respects notifications)
+            await self._wait_terminal()
+
+            # Get the raw MCP result
+            mcp_result = await self._client.get_task_result(self._task_id)
+
+            # Parse as GetPromptResult
+            result = mcp_types.GetPromptResult.model_validate(mcp_result)
+
+        # Cache before returning
+        self._cached_result = result
+        return result
+
+
+class ResourceTask(
+    Task[list[mcp_types.TextResourceContents | mcp_types.BlobResourceContents]]
+):
+    """
+    Represents a resource read that may execute in background or immediately.
+
+    Provides a uniform API whether the server accepts background execution
+    or executes synchronously (graceful degradation per SEP-1686).
+
+    Usage:
+        task = await client.read_resource_as_task("file://data.txt")
+        contents = await task  # Returns list[ReadResourceContents]
+    """
+
+    def __init__(
+        self,
+        client: Client,
+        task_id: str,
+        uri: str,
+        immediate_result: list[
+            mcp_types.TextResourceContents | mcp_types.BlobResourceContents
+        ]
+        | None = None,
+    ):
+        """
+        Create a ResourceTask wrapper.
+
+        Args:
+            client: The FastMCP client
+            task_id: The task identifier
+            uri: URI of the resource being read
+            immediate_result: If server executed synchronously, the immediate result
+        """
+        super().__init__(client, task_id, immediate_result)
+        self._uri = uri
+
+    async def result(
+        self,
+    ) -> list[mcp_types.TextResourceContents | mcp_types.BlobResourceContents]:
+        """Wait for and return the resource contents.
+
+        If server executed immediately, returns the immediate result.
+        Otherwise waits for background task to complete and retrieves result.
+
+        Returns:
+            list[ReadResourceContents]: The resource contents
+        """
+        # Check cache first
+        if self._cached_result is not None:
+            return self._cached_result
+
+        if self._is_immediate:
+            assert self._immediate_result is not None
+            result = self._immediate_result
+        else:
+            # Check client connected
+            self._check_client_connected()
+
+            # Wait for completion using event-based wait (respects notifications)
+            await self._wait_terminal()
+
+            # Get the raw MCP result
+            mcp_result = await self._client.get_task_result(self._task_id)
+
+            # Parse as ReadResourceResult or extract contents
+            if isinstance(mcp_result, mcp_types.ReadResourceResult):
+                # Already parsed by TasksResponse - extract contents
+                result = list(mcp_result.contents)
+            elif isinstance(mcp_result, dict) and "contents" in mcp_result:
+                # Dict format - parse each content item
+                parsed_contents = []
+                for item in mcp_result["contents"]:
+                    if isinstance(item, dict):
+                        if "blob" in item:
+                            parsed_contents.append(
+                                mcp_types.BlobResourceContents.model_validate(item)
+                            )
+                        else:
+                            parsed_contents.append(
+                                mcp_types.TextResourceContents.model_validate(item)
+                            )
+                    else:
+                        parsed_contents.append(item)
+                result = parsed_contents
+            else:
+                # Fallback - might be the list directly
+                result = mcp_result if isinstance(mcp_result, list) else [mcp_result]
+
+        # Cache before returning
+        self._cached_result = result
+        return result
diff --git a/fastmcp_slim/fastmcp/client/telemetry.py b/fastmcp_slim/fastmcp/client/telemetry.py
new file mode 100644
index 0000000..e66cd7b
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/telemetry.py
@@ -0,0 +1,57 @@
+"""Client-side telemetry helpers."""
+
+from collections.abc import Generator
+from contextlib import contextmanager
+
+from opentelemetry.trace import Span, SpanKind, Status, StatusCode
+
+from fastmcp.exceptions import ToolError as _ToolError
+from fastmcp.telemetry import get_tracer
+
+
+@contextmanager
+def client_span(
+    name: str,
+    method: str,
+    component_key: str,
+    session_id: str | None = None,
+    resource_uri: str | None = None,
+    tool_name: str | None = None,
+    prompt_name: str | None = None,
+) -> Generator[Span, None, None]:
+    """Create a CLIENT span with standard MCP attributes.
+
+    Automatically records any exception on the span and sets error status.
+    """
+    tracer = get_tracer()
+    with tracer.start_as_current_span(name, kind=SpanKind.CLIENT) as span:
+        if span.is_recording():
+            attrs: dict[str, str] = {
+                # MCP semantic conventions
+                "mcp.method.name": method,
+                # FastMCP-specific attributes
+                "fastmcp.component.key": component_key,
+            }
+            if session_id is not None:
+                attrs["mcp.session.id"] = session_id
+            if resource_uri:
+                attrs["mcp.resource.uri"] = resource_uri
+            if tool_name is not None:
+                attrs["gen_ai.tool.name"] = tool_name
+            if prompt_name is not None:
+                attrs["gen_ai.prompt.name"] = prompt_name
+            span.set_attributes(attrs)
+        try:
+            yield span
+        except Exception as e:
+            if span.is_recording():
+                error_type = (
+                    "tool_error" if isinstance(e, _ToolError) else type(e).__qualname__
+                )
+                span.set_attribute("error.type", error_type)
+                span.record_exception(e)
+                span.set_status(Status(StatusCode.ERROR, str(e)))
+            raise
+
+
+__all__ = ["client_span"]
diff --git a/fastmcp_slim/fastmcp/client/transports/__init__.py b/fastmcp_slim/fastmcp/client/transports/__init__.py
new file mode 100644
index 0000000..287697b
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/transports/__init__.py
@@ -0,0 +1,36 @@
+from mcp.server.mcpserver import MCPServer as SDKServer
+
+from fastmcp.client.transports.base import (
+    ClientTransport,
+    ClientTransportT,
+    SessionKwargs,
+)
+from fastmcp.client.transports.config import MCPConfigTransport
+from fastmcp.client.transports.http import StreamableHttpTransport
+from fastmcp.client.transports.inference import infer_transport
+from fastmcp.client.transports.sse import SSETransport
+from fastmcp.client.transports.memory import FastMCPTransport
+from fastmcp.client.transports.stdio import (
+    FastMCPStdioTransport,
+    NodeStdioTransport,
+    NpxStdioTransport,
+    PythonStdioTransport,
+    StdioTransport,
+    UvStdioTransport,
+    UvxStdioTransport,
+)
+
+__all__ = [
+    "ClientTransport",
+    "FastMCPStdioTransport",
+    "FastMCPTransport",
+    "NodeStdioTransport",
+    "NpxStdioTransport",
+    "PythonStdioTransport",
+    "SSETransport",
+    "StdioTransport",
+    "StreamableHttpTransport",
+    "UvStdioTransport",
+    "UvxStdioTransport",
+    "infer_transport",
+]
diff --git a/fastmcp_slim/fastmcp/client/transports/base.py b/fastmcp_slim/fastmcp/client/transports/base.py
new file mode 100644
index 0000000..8732641
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/transports/base.py
@@ -0,0 +1,83 @@
+import abc
+import contextlib
+from collections.abc import AsyncIterator, Sequence
+from typing import Any, Literal, TypeVar
+
+import httpx
+import mcp_types
+from mcp import ClientSession
+from mcp.client.extension import NotificationBinding
+from mcp.client.session import (
+    ElicitationFnT,
+    ListRootsFnT,
+    LoggingFnT,
+    MessageHandlerFnT,
+    SamplingFnT,
+)
+from typing_extensions import TypedDict, Unpack
+
+# TypeVar for preserving specific ClientTransport subclass types
+ClientTransportT = TypeVar("ClientTransportT", bound="ClientTransport")
+
+
+class SessionKwargs(TypedDict, total=False):
+    """Keyword arguments for the MCP ClientSession constructor."""
+
+    read_timeout_seconds: float | None
+    sampling_callback: SamplingFnT | None
+    sampling_capabilities: mcp_types.SamplingCapability | None
+    list_roots_callback: ListRootsFnT | None
+    logging_callback: LoggingFnT | None
+    elicitation_callback: ElicitationFnT | None
+    message_handler: MessageHandlerFnT | None
+    client_info: mcp_types.Implementation | None
+    notification_bindings: Sequence[NotificationBinding[Any]] | None
+
+
+class ClientTransport(abc.ABC):
+    """
+    Abstract base class for different MCP client transport mechanisms.
+
+    A Transport is responsible for establishing and managing connections
+    to an MCP server, and providing a ClientSession within an async context.
+
+    """
+
+    @abc.abstractmethod
+    @contextlib.asynccontextmanager
+    async def connect_session(
+        self, **session_kwargs: Unpack[SessionKwargs]
+    ) -> AsyncIterator[ClientSession]:
+        """
+        Establishes a connection and yields an active ClientSession.
+
+        The ClientSession is *not* expected to be initialized in this context manager.
+
+        The session is guaranteed to be valid only within the scope of the
+        async context manager. Connection setup and teardown are handled
+        within this context.
+
+        Args:
+            **session_kwargs: Keyword arguments to pass to the ClientSession
+                              constructor (e.g., callbacks, timeouts).
+
+        Yields:
+            A mcp.ClientSession instance.
+        """
+        raise NotImplementedError
+        yield  # ty:ignore[invalid-yield]
+
+    def __repr__(self) -> str:
+        # Basic representation for subclasses
+        return f"<{self.__class__.__name__}>"
+
+    async def close(self):  # noqa: B027
+        """Close the transport."""
+
+    def get_session_id(self) -> str | None:
+        """Get the session ID for this transport, if available."""
+        return None
+
+    def _set_auth(self, auth: httpx.Auth | Literal["oauth"] | str | None):
+        if auth is not None:
+            raise ValueError("This transport does not support auth")
diff --git a/fastmcp_slim/fastmcp/client/transports/config.py b/fastmcp_slim/fastmcp/client/transports/config.py
new file mode 100644
index 0000000..472e94b
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/transports/config.py
@@ -0,0 +1,223 @@
+import contextlib
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING, Any
+
+from mcp import ClientSession
+from typing_extensions import Unpack
+
+from fastmcp import _install_hints
+from fastmcp.client.transports.base import ClientTransport, SessionKwargs
+from fastmcp.client.transports.memory import FastMCPTransport
+from fastmcp.mcp_config import (
+    MCPConfig,
+    MCPServerTypes,
+    RemoteMCPServer,
+    StdioMCPServer,
+    TransformingRemoteMCPServer,
+    TransformingStdioMCPServer,
+    _coerce_tool_transform_configs,
+)
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP
+
+logger = get_logger(__name__)
+
+
+class MCPConfigTransport(ClientTransport):
+    """Transport for connecting to one or more MCP servers defined in an MCPConfig.
+
+    This transport provides a unified interface to multiple MCP servers defined in an MCPConfig
+    object or dictionary matching the MCPConfig schema. It supports two key scenarios:
+
+    1. If the MCPConfig contains exactly one server, it creates a direct transport to that server.
+    2. If the MCPConfig contains multiple servers, it creates a composite client by mounting
+       all servers on a single FastMCP instance, with each server's name, by default, used as its mounting prefix.
+
+    In the multiserver case, tools are accessible with the prefix pattern `{server_name}_{tool_name}`
+    and resources with the pattern `protocol://{server_name}/path/to/resource`.
+
+    This is particularly useful for creating clients that need to interact with multiple specialized
+    MCP servers through a single interface, simplifying client code.
+
+    Examples:
+        ```python
+        from fastmcp import Client
+
+        # Create a config with multiple servers
+        config = {
+            "mcpServers": {
+                "weather": {
+                    "url": "https://weather-api.example.com/mcp",
+                    "transport": "http"
+                },
+                "calendar": {
+                    "url": "https://calendar-api.example.com/mcp",
+                    "transport": "http"
+                }
+            }
+        }
+
+        # Create a client with the config
+        client = Client(config)
+
+        async with client:
+            # Access tools with prefixes
+            weather = await client.call_tool("weather_get_forecast", {"city": "London"})
+            events = await client.call_tool("calendar_list_events", {"date": "2023-06-01"})
+
+            # Access resources with prefixed URIs
+            icons = await client.read_resource("weather://weather/icons/sunny")
+        ```
+    """
+
+    def __init__(self, config: MCPConfig | dict, name_as_prefix: bool = True):
+        if isinstance(config, dict):
+            config = MCPConfig.from_dict(config)
+        self.config = config
+        self.name_as_prefix = name_as_prefix
+        self._transports: list[ClientTransport] = []
+
+        if not self.config.mcpServers:
+            raise ValueError("No MCP servers defined in the config")
+
+        # For single server, create transport eagerly so it can be inspected
+        if len(self.config.mcpServers) == 1:
+            self.transport = next(iter(self.config.mcpServers.values())).to_transport()
+            self._transports.append(self.transport)
+
+    @contextlib.asynccontextmanager
+    async def connect_session(
+        self, **session_kwargs: Unpack[SessionKwargs]
+    ) -> AsyncIterator[ClientSession]:
+        # Single server - delegate directly to pre-created transport
+        if len(self.config.mcpServers) == 1:
+            async with self.transport.connect_session(**session_kwargs) as session:
+                yield session
+            return
+
+        # Multiple servers - create composite with mounted proxies, connecting
+        # each ProxyClient so its underlying transport session stays alive for
+        # the duration of this context (fixes session persistence for
+        # streamable-http backends — see #2790).
+        try:
+            from fastmcp.server.server import FastMCP
+        except ImportError as exc:
+            raise ImportError(
+                _install_hints.full_package("MCP configs with multiple servers")
+            ) from exc
+
+        timeout = session_kwargs.get("read_timeout_seconds")
+        composite = FastMCP[Any](name="MCPRouter")
+
+        async with contextlib.AsyncExitStack() as stack:
+            # Close any previous transports from prior connections to avoid leaking
+            for t in self._transports:
+                await t.close()
+            self._transports = []
+
+            for name, server_config in self.config.mcpServers.items():
+                try:
+                    transport, _client, proxy = await self._create_proxy(
+                        name, server_config, timeout, stack
+                    )
+                except Exception:  # Broad catch is intentional: failure modes
+                    # are diverse (OSError, TimeoutError, RuntimeError, etc.)
+                    # and the whole point is to skip any server that can't connect.
+                    logger.warning(
+                        "Failed to connect to MCP server %r, skipping",
+                        name,
+                        exc_info=True,
+                    )
+                    continue
+                self._transports.append(transport)
+                composite.mount(proxy, namespace=name if self.name_as_prefix else None)
+
+            if not self._transports:
+                raise ConnectionError("All MCP servers failed to connect")
+
+            async with FastMCPTransport(mcp=composite).connect_session(
+                **session_kwargs
+            ) as session:
+                yield session
+
+    async def _create_proxy(
+        self,
+        name: str,
+        config: MCPServerTypes,
+        timeout: float | None,
+        stack: contextlib.AsyncExitStack,
+    ) -> tuple[ClientTransport, Any, "FastMCP[Any]"]:
+        """Create underlying transport, proxy client, and proxy server for a single backend.
+
+        The ProxyClient is connected via the AsyncExitStack *before* being
+        passed to create_proxy so the factory sees it as connected and reuses
+        the same session for all tool calls (instead of creating fresh copies).
+
+        Returns a tuple of (transport, proxy_client, proxy_server).
+        """
+        # Import here to avoid circular dependency
+        from fastmcp.server.providers.proxy import StatefulProxyClient
+        from fastmcp.server.server import create_proxy
+
+        tool_transforms = None
+        include_tags = None
+        exclude_tags = None
+
+        # Handle transforming servers - call base class to_transport() for underlying transport
+        if isinstance(config, TransformingStdioMCPServer):
+            transport = StdioMCPServer.to_transport(config)
+            tool_transforms = config.tools
+            include_tags = config.include_tags
+            exclude_tags = config.exclude_tags
+        elif isinstance(config, TransformingRemoteMCPServer):
+            transport = RemoteMCPServer.to_transport(config)
+            tool_transforms = config.tools
+            include_tags = config.include_tags
+            exclude_tags = config.exclude_tags
+        else:
+            transport = config.to_transport()
+
+        client = StatefulProxyClient(transport=transport, timeout=timeout)
+        # Connect the client *before* create_proxy so _create_client_factory
+        # detects it as connected and reuses it for all tool calls, preserving
+        # the session ID across requests. StatefulProxyClient is used instead
+        # of ProxyClient because its context-restoring handler wrappers prevent
+        # stale ContextVars in the reused session's receive loop.
+        #
+        # StatefulProxyClient.__aexit__ is a no-op (by design, for the
+        # new_stateful() use case), so we cannot rely on enter_async_context
+        # alone to clean up.  Instead we connect manually and push an
+        # explicit force-disconnect callback so the subprocess is terminated
+        # when the AsyncExitStack unwinds.
+        await client.__aenter__()
+        # Callbacks run LIFO: transport.close() must run *after*
+        # client._disconnect so push it first.
+        stack.push_async_callback(transport.close)
+        stack.push_async_callback(client._disconnect, force=True)
+        # Create proxy without include_tags/exclude_tags - we'll add them after tool transforms
+        proxy = create_proxy(
+            client,
+            name=f"Proxy-{name}",
+        )
+        # Add tool transforms FIRST - they may add/modify tags
+        if tool_transforms:
+            from fastmcp.server.transforms import ToolTransform
+
+            proxy.add_transform(
+                ToolTransform(_coerce_tool_transform_configs(tool_transforms))
+            )
+        # Then add enabled filters - they filter based on tags
+        if include_tags:
+            proxy.enable(tags=set(include_tags), only=True)
+        if exclude_tags:
+            proxy.disable(tags=set(exclude_tags))
+        return transport, client, proxy
+
+    async def close(self):
+        for transport in self._transports:
+            await transport.close()
+
+    def __repr__(self) -> str:
+        return f"<MCPConfigTransport(config='{self.config}')>"
diff --git a/fastmcp_slim/fastmcp/client/transports/http.py b/fastmcp_slim/fastmcp/client/transports/http.py
new file mode 100644
index 0000000..73caf3c
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/transports/http.py
@@ -0,0 +1,217 @@
+"""Streamable HTTP transport for FastMCP Client."""
+
+from __future__ import annotations
+
+import contextlib
+import ssl
+from collections.abc import AsyncIterator
+from typing import Any, Literal, cast
+
+import httpx
+from mcp import ClientSession
+from mcp.client.streamable_http import streamable_http_client
+from mcp.shared._httpx_utils import McpHttpClientFactory, create_mcp_http_client
+from pydantic import AnyUrl
+from typing_extensions import Unpack
+
+from fastmcp.client.auth.bearer import BearerAuth
+from fastmcp.client.auth.oauth import OAuth
+from fastmcp.client.dependencies import get_http_headers
+from fastmcp.client.transports.base import ClientTransport, SessionKwargs
+
+
+class StreamableHttpTransport(ClientTransport):
+    """Transport implementation that connects to an MCP server via Streamable HTTP Requests."""
+
+    def __init__(
+        self,
+        url: str | AnyUrl,
+        headers: dict[str, str] | None = None,
+        auth: httpx.Auth | Literal["oauth"] | str | None = None,
+        httpx_client_factory: McpHttpClientFactory | None = None,
+        verify: ssl.SSLContext | bool | str | None = None,
+    ):
+        """Initialize a Streamable HTTP transport.
+
+        Args:
+            url: The MCP server endpoint URL.
+            headers: Optional headers to include in requests.
+            auth: Authentication method - httpx.Auth, "oauth" for OAuth flow,
+                or a bearer token string.
+            httpx_client_factory: Optional factory for creating httpx.AsyncClient.
+                If provided, must accept keyword arguments: headers, auth,
+                follow_redirects, and optionally timeout. Using **kwargs is
+                recommended to ensure forward compatibility.
+            verify: SSL certificate verification. Accepts False to disable
+                verification, a path to a CA bundle, or an ssl.SSLContext
+                for full control. None (default) uses httpx defaults (verification
+                enabled). Ignored when httpx_client_factory is provided.
+        """
+        if isinstance(url, AnyUrl):
+            url = str(url)
+        if not isinstance(url, str) or not url.startswith("http"):
+            raise ValueError("Invalid HTTP/S URL provided for Streamable HTTP.")
+
+        # Don't modify the URL path - respect the exact URL provided by the user
+        # Some servers are strict about trailing slashes (e.g., PayPal MCP)
+
+        self.url: str = url
+        self.headers = headers or {}
+        self.httpx_client_factory = httpx_client_factory
+        self.verify: ssl.SSLContext | bool | str | None = verify
+
+        if httpx_client_factory is not None and verify is not None:
+            import warnings
+
+            warnings.warn(
+                "Both 'httpx_client_factory' and 'verify' were provided. "
+                "The 'verify' parameter will be ignored because "
+                "'httpx_client_factory' takes precedence. Configure SSL "
+                "verification directly in your httpx_client_factory instead.",
+                UserWarning,
+                stacklevel=2,
+            )
+
+        self._set_auth(auth)
+
+        self.forward_incoming_headers: bool = False
+
+        # SDK v2's streamable_http_client no longer exposes a get_session_id
+        # callback. We recover the session id ourselves by capturing the
+        # `mcp-session-id` response header via an httpx event hook on the
+        # client we own (see connect_session / _capture_session_id).
+        self._session_id: str | None = None
+
+    async def _capture_session_id(self, response: httpx.Response) -> None:
+        """httpx response event hook: record the server's `mcp-session-id`.
+
+        The streamable HTTP server assigns the session id in the response to
+        the initialize request and echoes it on subsequent responses; we keep
+        the latest non-empty value.
+        """
+        sid = response.headers.get("mcp-session-id")
+        if sid:
+            self._session_id = sid
+
+    def _set_auth(self, auth: httpx.Auth | Literal["oauth"] | str | None):
+        resolved: httpx.Auth | None
+        if auth == "oauth":
+            resolved = OAuth(
+                self.url,
+                httpx_client_factory=self.httpx_client_factory
+                or self._make_verify_factory(),
+            )
+        elif isinstance(auth, OAuth):
+            auth._bind(self.url)
+            # Only inject the transport's factory into OAuth if OAuth still
+            # has the bare default — preserve any factory the caller attached
+            if auth.httpx_client_factory is httpx.AsyncClient:
+                factory = self.httpx_client_factory or self._make_verify_factory()
+                if factory is not None:
+                    auth.httpx_client_factory = factory
+            resolved = auth
+        elif isinstance(auth, str):
+            resolved = BearerAuth(auth)
+        else:
+            resolved = auth
+        self.auth: httpx.Auth | None = resolved
+
+    def _make_verify_factory(self) -> McpHttpClientFactory | None:
+        if self.verify is None:
+            return None
+        verify = self.verify
+
+        def factory(
+            headers: dict[str, str] | None = None,
+            timeout: httpx.Timeout | None = None,
+            auth: httpx.Auth | None = None,
+        ) -> httpx.AsyncClient:
+            if timeout is None:
+                timeout = httpx.Timeout(30.0, read=300.0)
+            kwargs: dict[str, Any] = {
+                "follow_redirects": True,
+                "timeout": timeout,
+                "verify": verify,
+            }
+            if headers is not None:
+                kwargs["headers"] = headers
+            if auth is not None:
+                kwargs["auth"] = auth
+            return httpx.AsyncClient(**kwargs)
+
+        return cast(McpHttpClientFactory, factory)
+
+    @contextlib.asynccontextmanager
+    async def connect_session(
+        self, **session_kwargs: Unpack[SessionKwargs]
+    ) -> AsyncIterator[ClientSession]:
+        # When used in a proxy, forward the inbound request's authorization
+        # header to the upstream server. This is off by default so that a
+        # plain Client used inside a server tool handler doesn't accidentally
+        # leak the caller's credentials to an unrelated remote server.
+        if self.forward_incoming_headers:
+            headers = get_http_headers(include={"authorization"}) | self.headers
+        else:
+            headers = dict(self.headers)
+
+        # Configure timeout if provided, preserving MCP's 30s connect default.
+        # SDK v2 session read timeouts are float seconds (see SessionKwargs).
+        timeout: httpx.Timeout | None = None
+        read_timeout_seconds = session_kwargs.get("read_timeout_seconds")
+        if read_timeout_seconds is not None:
+            timeout = httpx.Timeout(30.0, read=read_timeout_seconds)
+
+        # Create httpx client from factory or use default with MCP-appropriate
+        # timeouts. Note: create_mcp_http_client enables follow_redirects, but
+        # httpx automatically strips Authorization headers on cross-origin
+        # redirects to prevent credential leakage.
+        verify_factory = self._make_verify_factory()
+        if self.httpx_client_factory is not None:
+            http_client = self.httpx_client_factory(
+                headers=headers,
+                auth=self.auth,
+                follow_redirects=True,  # type: ignore[call-arg]  # ty:ignore[unknown-argument]
+                **({"timeout": timeout} if timeout else {}),
+            )
+        elif verify_factory is not None:
+            http_client = verify_factory(
+                headers=headers,
+                timeout=timeout,
+                auth=self.auth,
+            )
+        else:
+            http_client = create_mcp_http_client(
+                headers=headers,
+                timeout=timeout,
+                auth=self.auth,
+            )
+
+        # SDK v2's streamable_http_client no longer surfaces the session id, so
+        # capture it off the `mcp-session-id` response header on the client we
+        # own. Register on whichever instance is actually used (factory paths).
+        self._session_id = None
+        http_client.event_hooks.setdefault("response", []).append(
+            self._capture_session_id
+        )
+
+        # Ensure httpx client is closed after use. SDK v2 streamable_http_client
+        # yields a 2-tuple (read, write); get_session_id is gone from the transport.
+        async with (
+            http_client,
+            streamable_http_client(self.url, http_client=http_client) as (
+                read_stream,
+                write_stream,
+            ),
+            ClientSession(read_stream, write_stream, **session_kwargs) as session,
+        ):
+            yield session
+
+    def get_session_id(self) -> str | None:
+        return self._session_id
+
+    async def close(self):
+        # Reset the captured session id
+        self._session_id = None
+
+    def __repr__(self) -> str:
+        return f"<StreamableHttpTransport(url='{self.url}')>"
diff --git a/fastmcp_slim/fastmcp/client/transports/inference.py b/fastmcp_slim/fastmcp/client/transports/inference.py
new file mode 100644
index 0000000..84711d1
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/transports/inference.py
@@ -0,0 +1,170 @@
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast, overload
+
+from mcp.server.mcpserver import MCPServer as SDKServer
+from pydantic import AnyUrl
+
+from fastmcp.client.transports.base import ClientTransport, ClientTransportT
+from fastmcp.client.transports.config import MCPConfigTransport
+from fastmcp.client.transports.http import StreamableHttpTransport
+from fastmcp.client.transports.memory import FastMCPTransport
+from fastmcp.client.transports.sse import SSETransport
+from fastmcp.client.transports.stdio import (
+    NodeStdioTransport,
+    PythonStdioTransport,
+)
+from fastmcp.mcp_config import MCPConfig, infer_transport_type_from_url
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP
+else:
+    FastMCP = Any
+
+logger = get_logger(__name__)
+
+
+@overload
+def infer_transport(transport: ClientTransportT) -> ClientTransportT: ...
+
+
+@overload
+def infer_transport(transport: FastMCP) -> FastMCPTransport: ...
+
+
+@overload
+def infer_transport(transport: SDKServer) -> FastMCPTransport: ...
+
+
+@overload
+def infer_transport(transport: MCPConfig) -> MCPConfigTransport: ...
+
+
+@overload
+def infer_transport(transport: dict[str, Any]) -> MCPConfigTransport: ...
+
+
+@overload
+def infer_transport(
+    transport: AnyUrl,
+) -> SSETransport | StreamableHttpTransport: ...
+
+
+@overload
+def infer_transport(
+    transport: str,
+) -> (
+    PythonStdioTransport | NodeStdioTransport | SSETransport | StreamableHttpTransport
+): ...
+
+
+@overload
+def infer_transport(transport: Path) -> PythonStdioTransport | NodeStdioTransport: ...
+
+
+def infer_transport(
+    transport: ClientTransport
+    | FastMCP
+    | SDKServer
+    | AnyUrl
+    | Path
+    | MCPConfig
+    | dict[str, Any]
+    | str,
+) -> ClientTransport:
+    """
+    Infer the appropriate transport type from the given transport argument.
+
+    This function attempts to infer the correct transport type from the provided
+    argument, handling various input types and converting them to the appropriate
+    ClientTransport subclass.
+
+    The function supports these input types:
+    - ClientTransport: Used directly without modification
+    - FastMCP or SDKServer: Creates an in-memory FastMCPTransport
+    - Path or str (file path): Creates PythonStdioTransport (.py) or NodeStdioTransport (.js)
+    - AnyUrl or str (URL): Creates StreamableHttpTransport (default) or SSETransport (for /sse endpoints)
+    - MCPConfig or dict: Creates MCPConfigTransport, potentially connecting to multiple servers
+
+    For HTTP URLs, they are assumed to be Streamable HTTP URLs unless they end in `/sse`.
+
+    For MCPConfig with multiple servers, a composite client is created where each server
+    is mounted with its name as prefix. This allows accessing tools and resources from multiple
+    servers through a single unified client interface, using naming patterns like
+    `servername_toolname` for tools and `protocol://servername/path` for resources.
+    If the MCPConfig contains only one server, a direct connection is established without prefixing.
+
+    Examples:
+        ```python
+        # Connect to a local Python script
+        transport = infer_transport("my_script.py")
+
+        # Connect to a remote server via HTTP
+        transport = infer_transport("http://example.com/mcp")
+
+        # Connect to multiple servers using MCPConfig
+        config = {
+            "mcpServers": {
+                "weather": {"url": "http://weather.example.com/mcp"},
+                "calendar": {"url": "http://calendar.example.com/mcp"}
+            }
+        }
+        transport = infer_transport(config)
+        ```
+    """
+
+    # the transport is already a ClientTransport
+    if isinstance(transport, ClientTransport):
+        return transport
+
+    # the transport is a FastMCP server (2.x or 1.0)
+    elif _is_fastmcp_server(transport):
+        inferred_transport = FastMCPTransport(
+            mcp=cast("FastMCP[Any] | SDKServer", transport)
+        )
+
+    # the transport is a path to a script
+    elif isinstance(transport, Path | str) and Path(transport).exists():
+        if str(transport).endswith(".py"):
+            inferred_transport = PythonStdioTransport(script_path=cast(Path, transport))
+        elif str(transport).endswith(".js"):
+            inferred_transport = NodeStdioTransport(script_path=cast(Path, transport))
+        else:
+            raise ValueError(f"Unsupported script type: {transport}")
+
+    # the transport is an http(s) URL
+    elif isinstance(transport, AnyUrl | str) and str(transport).startswith("http"):
+        inferred_transport_type = infer_transport_type_from_url(
+            cast(AnyUrl | str, transport)
+        )
+        if inferred_transport_type == "sse":
+            inferred_transport = SSETransport(url=cast(AnyUrl | str, transport))
+        else:
+            inferred_transport = StreamableHttpTransport(
+                url=cast(AnyUrl | str, transport)
+            )
+
+    # if the transport is a config dict or MCPConfig
+    elif isinstance(transport, dict | MCPConfig):
+        inferred_transport = MCPConfigTransport(
+            config=cast(dict | MCPConfig, transport)
+        )
+
+    # the transport is an unknown type
+    else:
+        raise ValueError(f"Could not infer a valid transport from: {transport}")
+
+    logger.debug(f"Inferred transport: {inferred_transport}")
+    return inferred_transport
+
+
+def _is_fastmcp_server(transport: object) -> bool:
+    if isinstance(transport, SDKServer):
+        return True
+
+    try:
+        from fastmcp.server.server import FastMCP as FastMCP2Server
+    except ImportError:
+        return False
+
+    return isinstance(transport, FastMCP2Server)
diff --git a/fastmcp_slim/fastmcp/client/transports/memory.py b/fastmcp_slim/fastmcp/client/transports/memory.py
new file mode 100644
index 0000000..ad683ef
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/transports/memory.py
@@ -0,0 +1,128 @@
+import contextlib
+import importlib
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING, Any
+
+import anyio
+from mcp import ClientSession
+from mcp.server import Server
+from mcp.server.mcpserver import MCPServer as SDKServer
+from mcp.shared.memory import create_client_server_memory_streams
+from typing_extensions import Unpack
+
+from fastmcp import _install_hints
+from fastmcp.client.transports.base import ClientTransport, SessionKwargs
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP
+
+
+def _lowlevel_of(server: "FastMCP[Any] | SDKServer") -> Server:
+    """Resolve the underlying lowlevel MCP `Server` for either server type.
+
+    The SDK's own high-level `MCPServer` exposes its lowlevel server as
+    `_lowlevel_server` and its own `run()` is synchronous, so we always drive
+    the async lowlevel `Server.run` here. FastMCP servers expose the same
+    lowlevel server as `_mcp_server`.
+    """
+    if isinstance(server, SDKServer):
+        return server._lowlevel_server
+    return server._mcp_server
+
+
+class FastMCPTransport(ClientTransport):
+    """In-memory transport for FastMCP servers.
+
+    This transport connects directly to a FastMCP server instance in the same
+    Python process. It works with both FastMCP servers and the SDK's own
+    high-level `MCPServer` from the low-level MCP SDK. This is particularly
+    useful for unit tests or scenarios where client and server run in the same
+    runtime.
+    """
+
+    def __init__(self, mcp: "FastMCP[Any] | SDKServer", raise_exceptions: bool = False):
+        """Initialize a FastMCPTransport from a FastMCP server instance."""
+
+        # Accept both FastMCP 2.x and FastMCP 1.0 servers. Their underlying
+        # lowlevel MCP ``Server`` lives on different attributes
+        # (``_mcp_server`` vs ``_lowlevel_server``); ``_lowlevel_of`` resolves
+        # it uniformly so we can drive the async ``Server.run`` for both.
+        self.server = mcp
+        self.raise_exceptions = raise_exceptions
+
+    @contextlib.asynccontextmanager
+    async def connect_session(
+        self, **session_kwargs: Unpack[SessionKwargs]
+    ) -> AsyncIterator[ClientSession]:
+        async with create_client_server_memory_streams() as (
+            client_streams,
+            server_streams,
+        ):
+            client_read, client_write = client_streams
+            server_read, server_write = server_streams
+
+            # Capture exceptions to re-raise after task group cleanup.
+            # anyio task groups can suppress exceptions when cancel_scope.cancel()
+            # is called during cleanup, so we capture and re-raise manually.
+            exception_to_raise: BaseException | None = None
+
+            # IMPORTANT: The lifespan MUST be the outer context and the task
+            # group MUST be the inner context. This ensures the task group
+            # (containing the server's run() and all its pub/sub subscriptions)
+            # is cancelled and fully drained BEFORE the lifespan tears down
+            # the Docket Worker and closes Redis connections. Reversing this
+            # order (e.g. via `async with (tg, lifespan):`) causes the Worker
+            # shutdown to hang for 5 seconds per test because fakeredis
+            # blocking operations hold references that prevent clean
+            # cancellation.
+            lowlevel = _lowlevel_of(self.server)
+            async with _enter_server_lifespan(server=self.server):  # noqa: SIM117
+                async with anyio.create_task_group() as tg:
+                    tg.start_soon(
+                        lambda: lowlevel.run(
+                            server_read,
+                            server_write,
+                            lowlevel.create_initialization_options(),
+                            raise_exceptions=self.raise_exceptions,
+                        )
+                    )
+
+                    try:
+                        async with ClientSession(
+                            read_stream=client_read,
+                            write_stream=client_write,
+                            **session_kwargs,
+                        ) as client_session:
+                            yield client_session
+                    except BaseException as e:
+                        exception_to_raise = e
+                    finally:
+                        tg.cancel_scope.cancel()
+
+            # Re-raise after task group has exited cleanly
+            if exception_to_raise is not None:
+                raise exception_to_raise
+
+    def __repr__(self) -> str:
+        return f"<FastMCPTransport(server='{self.server.name}')>"
+
+
+@contextlib.asynccontextmanager
+async def _enter_server_lifespan(
+    server: "FastMCP[Any] | SDKServer",
+) -> AsyncIterator[None]:
+    """Enters the server's lifespan context for FastMCP servers and does nothing for the SDK's own high-level servers."""
+    FastMCP2: type[Any] | None
+    try:
+        FastMCP2 = importlib.import_module("fastmcp.server.server").FastMCP
+    except ImportError:
+        FastMCP2 = None
+
+    if FastMCP2 is None and not isinstance(server, SDKServer):
+        raise ImportError(_install_hints.full_package("In-memory FastMCP transports"))
+
+    if FastMCP2 is not None and isinstance(server, FastMCP2):
+        async with server._lifespan_manager():
+            yield
+    else:
+        yield
diff --git a/fastmcp_slim/fastmcp/client/transports/sse.py b/fastmcp_slim/fastmcp/client/transports/sse.py
new file mode 100644
index 0000000..09e7fff
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/transports/sse.py
@@ -0,0 +1,158 @@
+"""Server-Sent Events (SSE) transport for FastMCP Client."""
+
+from __future__ import annotations
+
+import contextlib
+import datetime
+import ssl
+from collections.abc import AsyncIterator
+from typing import Any, Literal, cast
+
+import httpx
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+from mcp.shared._httpx_utils import McpHttpClientFactory
+from pydantic import AnyUrl
+from typing_extensions import Unpack
+
+from fastmcp.client.auth.bearer import BearerAuth
+from fastmcp.client.auth.oauth import OAuth
+from fastmcp.client.dependencies import get_http_headers
+from fastmcp.client.transports.base import ClientTransport, SessionKwargs
+from fastmcp.utilities.timeout import normalize_timeout_to_timedelta
+
+
+class SSETransport(ClientTransport):
+    """Transport implementation that connects to an MCP server via Server-Sent Events."""
+
+    def __init__(
+        self,
+        url: str | AnyUrl,
+        headers: dict[str, str] | None = None,
+        auth: httpx.Auth | Literal["oauth"] | str | None = None,
+        sse_read_timeout: datetime.timedelta | float | int | None = None,
+        httpx_client_factory: McpHttpClientFactory | None = None,
+        verify: ssl.SSLContext | bool | str | None = None,
+    ):
+        if isinstance(url, AnyUrl):
+            url = str(url)
+        if not isinstance(url, str) or not url.startswith("http"):
+            raise ValueError("Invalid HTTP/S URL provided for SSE.")
+
+        # Don't modify the URL path - respect the exact URL provided by the user
+        # Some servers are strict about trailing slashes (e.g., PayPal MCP)
+
+        self.url: str = url
+        self.headers = headers or {}
+        self.httpx_client_factory = httpx_client_factory
+        self.verify: ssl.SSLContext | bool | str | None = verify
+
+        if httpx_client_factory is not None and verify is not None:
+            import warnings
+
+            warnings.warn(
+                "Both 'httpx_client_factory' and 'verify' were provided. "
+                "The 'verify' parameter will be ignored because "
+                "'httpx_client_factory' takes precedence. Configure SSL "
+                "verification directly in your httpx_client_factory instead.",
+                UserWarning,
+                stacklevel=2,
+            )
+
+        self._set_auth(auth)
+
+        self.forward_incoming_headers: bool = False
+
+        self.sse_read_timeout = normalize_timeout_to_timedelta(sse_read_timeout)
+
+    def _set_auth(self, auth: httpx.Auth | Literal["oauth"] | str | None):
+        resolved: httpx.Auth | None
+        if auth == "oauth":
+            resolved = OAuth(
+                self.url,
+                httpx_client_factory=self.httpx_client_factory
+                or self._make_verify_factory(),
+            )
+        elif isinstance(auth, OAuth):
+            auth._bind(self.url)
+            # Only inject the transport's factory into OAuth if OAuth still
+            # has the bare default — preserve any factory the caller attached
+            if auth.httpx_client_factory is httpx.AsyncClient:
+                factory = self.httpx_client_factory or self._make_verify_factory()
+                if factory is not None:
+                    auth.httpx_client_factory = factory
+            resolved = auth
+        elif isinstance(auth, str):
+            resolved = BearerAuth(auth)
+        else:
+            resolved = auth
+        self.auth: httpx.Auth | None = resolved
+
+    def _make_verify_factory(self) -> McpHttpClientFactory | None:
+        if self.verify is None:
+            return None
+        verify = self.verify
+
+        def factory(
+            headers: dict[str, str] | None = None,
+            timeout: httpx.Timeout | None = None,
+            auth: httpx.Auth | None = None,
+        ) -> httpx.AsyncClient:
+            if timeout is None:
+                timeout = httpx.Timeout(30.0, read=300.0)
+            kwargs: dict[str, Any] = {
+                "follow_redirects": True,
+                "timeout": timeout,
+                "verify": verify,
+            }
+            if headers is not None:
+                kwargs["headers"] = headers
+            if auth is not None:
+                kwargs["auth"] = auth
+            return httpx.AsyncClient(**kwargs)
+
+        return cast(McpHttpClientFactory, factory)
+
+    @contextlib.asynccontextmanager
+    async def connect_session(
+        self, **session_kwargs: Unpack[SessionKwargs]
+    ) -> AsyncIterator[ClientSession]:
+        client_kwargs: dict[str, Any] = {}
+
+        # When used in a proxy, forward the inbound request's authorization
+        # header to the upstream server. This is off by default so that a
+        # plain Client used inside a server tool handler doesn't accidentally
+        # leak the caller's credentials to an unrelated remote server.
+        if self.forward_incoming_headers:
+            client_kwargs["headers"] = (
+                get_http_headers(include={"authorization"}) | self.headers
+            )
+        else:
+            client_kwargs["headers"] = dict(self.headers)
+
+        # sse_read_timeout has a default value set, so we can't pass None without overriding it
+        # instead we simply leave the kwarg out if it's not provided
+        if self.sse_read_timeout is not None:
+            client_kwargs["sse_read_timeout"] = self.sse_read_timeout.total_seconds()
+        # SDK v2 session read timeouts are float seconds (see SessionKwargs);
+        # sse_client's `timeout` param is likewise float seconds.
+        read_timeout_seconds = session_kwargs.get("read_timeout_seconds")
+        if read_timeout_seconds is not None:
+            client_kwargs["timeout"] = read_timeout_seconds
+
+        if self.httpx_client_factory is not None:
+            client_kwargs["httpx_client_factory"] = self.httpx_client_factory
+        else:
+            verify_factory = self._make_verify_factory()
+            if verify_factory is not None:
+                client_kwargs["httpx_client_factory"] = verify_factory
+
+        async with sse_client(self.url, auth=self.auth, **client_kwargs) as transport:
+            read_stream, write_stream = transport
+            async with ClientSession(
+                read_stream, write_stream, **session_kwargs
+            ) as session:
+                yield session
+
+    def __repr__(self) -> str:
+        return f"<SSETransport(url='{self.url}')>"
diff --git a/fastmcp_slim/fastmcp/client/transports/stdio.py b/fastmcp_slim/fastmcp/client/transports/stdio.py
new file mode 100644
index 0000000..a0067bf
--- /dev/null
+++ b/fastmcp_slim/fastmcp/client/transports/stdio.py
@@ -0,0 +1,569 @@
+import asyncio
+import contextlib
+import os
+import shutil
+import sys
+from collections.abc import AsyncIterator
+from pathlib import Path
+from typing import TextIO, cast
+
+import anyio
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+from typing_extensions import Unpack
+
+from fastmcp.client.transports.base import ClientTransport, SessionKwargs
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class StdioTransport(ClientTransport):
+    """
+    Base transport for connecting to an MCP server via subprocess with stdio.
+
+    This is a base class that can be subclassed for specific command-based
+    transports like Python, Node, Uvx, etc.
+    """
+
+    def __init__(
+        self,
+        command: str,
+        args: list[str],
+        env: dict[str, str] | None = None,
+        cwd: str | None = None,
+        keep_alive: bool | None = None,
+        log_file: Path | TextIO | None = None,
+    ):
+        """
+        Initialize a Stdio transport.
+
+        Args:
+            command: The command to run (e.g., "python", "node", "uvx")
+            args: The arguments to pass to the command
+            env: Environment variables to set for the subprocess
+            cwd: Current working directory for the subprocess
+            keep_alive: Whether to keep the subprocess alive between connections.
+                       Defaults to True. When True, the subprocess remains active
+                       after the connection context exits, allowing reuse in
+                       subsequent connections.
+            log_file: Optional path or file-like object where subprocess stderr will
+                   be written. Can be a Path or TextIO object. Defaults to sys.stderr
+                   if not provided. When a Path is provided, the file will be created
+                   if it doesn't exist, or appended to if it does. When set, server
+                   errors will be written to this file instead of appearing in the console.
+        """
+        self.command = command
+        self.args = args
+        self.env = env
+        self.cwd = cwd
+        if keep_alive is None:
+            keep_alive = True
+        self.keep_alive = keep_alive
+        self.log_file = log_file
+
+        self._session: ClientSession | None = None
+        self._connect_task: asyncio.Task | None = None
+        self._ready_event = anyio.Event()
+        self._stop_event = anyio.Event()
+
+    @contextlib.asynccontextmanager
+    async def connect_session(
+        self, **session_kwargs: Unpack[SessionKwargs]
+    ) -> AsyncIterator[ClientSession]:
+        try:
+            await self.connect(**session_kwargs)
+            yield cast(ClientSession, self._session)
+        finally:
+            if not self.keep_alive:
+                await self.disconnect()
+            else:
+                logger.debug("Stdio transport has keep_alive=True, not disconnecting")
+
+    async def connect(
+        self, **session_kwargs: Unpack[SessionKwargs]
+    ) -> ClientSession | None:
+        # If the connect task completed or the session's streams are dead,
+        # the subprocess has exited. Tear down so we can start fresh.
+        if self._connect_task is not None and (
+            self._connect_task.done() or self._is_session_dead()
+        ):
+            await self.disconnect()
+
+        if self._connect_task is not None:
+            return
+
+        session_future: asyncio.Future[ClientSession] = asyncio.Future()
+
+        # start the connection task
+        self._connect_task = asyncio.create_task(
+            _stdio_transport_connect_task(
+                command=self.command,
+                args=self.args,
+                env=self.env,
+                cwd=self.cwd,
+                log_file=self.log_file,
+                # TODO(ty): remove when ty supports Unpack[TypedDict] inference
+                session_kwargs=session_kwargs,  # type: ignore[arg-type]
+                ready_event=self._ready_event,
+                stop_event=self._stop_event,
+                session_future=session_future,
+            )
+        )
+
+        # wait for the client to be ready before returning
+        await self._ready_event.wait()
+
+        # Check if connect task completed with an exception (early failure)
+        if self._connect_task.done():
+            exception = self._connect_task.exception()
+            if exception is not None:
+                raise exception
+
+        self._session = await session_future
+        return self._session
+
+    async def disconnect(self):
+        if self._connect_task is None:
+            return
+
+        # signal the connection task to stop
+        self._stop_event.set()
+
+        # wait for the connection task to finish cleanly
+        with contextlib.suppress(Exception):
+            await self._connect_task
+
+        # reset variables and events for potential future reconnects
+        self._connect_task = None
+        self._session = None
+        self._stop_event = anyio.Event()
+        self._ready_event = anyio.Event()
+
+    def _is_session_dead(self) -> bool:
+        """Check whether the session's underlying connection has closed.
+
+        SDK v2 drives the session through a `JSONRPCDispatcher` rather than
+        exposing raw read/write streams: when the subprocess exits, the
+        dispatcher's read loop ends and marks itself closed (or never-running).
+        Detect that so a keep_alive transport tears the stale session down and
+        reconnects instead of reusing a dead subprocess.
+        """
+        if self._session is None:
+            return False
+        dispatcher = getattr(self._session, "_dispatcher", None)
+        if dispatcher is None:
+            return False
+        # A dispatcher that has closed, or that started running and then
+        # stopped, indicates the connection is gone. `_running` is False before
+        # the read loop starts too, so only treat "not running" as dead once the
+        # dispatcher has been closed.
+        return bool(getattr(dispatcher, "_closed", False))
+
+    async def close(self):
+        await self.disconnect()
+
+    def __del__(self):
+        """Ensure that we send a disconnection signal to the transport task if we are being garbage collected."""
+        if not self._stop_event.is_set():
+            self._stop_event.set()
+
+    def __repr__(self) -> str:
+        return (
+            f"<{self.__class__.__name__}(command='{self.command}', args={self.args})>"
+        )
+
+
+async def _stdio_transport_connect_task(
+    command: str,
+    args: list[str],
+    env: dict[str, str] | None,
+    cwd: str | None,
+    log_file: Path | TextIO | None,
+    session_kwargs: SessionKwargs,
+    ready_event: anyio.Event,
+    stop_event: anyio.Event,
+    session_future: asyncio.Future[ClientSession],
+):
+    """A standalone connection task for a stdio transport. It is not a part of the StdioTransport class
+    to ensure that the connection task does not hold a reference to the Transport object."""
+
+    try:
+        async with contextlib.AsyncExitStack() as stack:
+            try:
+                server_params = StdioServerParameters(
+                    command=command,
+                    args=args,
+                    env=env,
+                    cwd=cwd,
+                )
+                # Handle log_file: Path needs to be opened, TextIO used as-is
+                if log_file is None:
+                    log_file_handle = sys.stderr
+                elif isinstance(log_file, Path):
+                    log_file_handle = stack.enter_context(log_file.open("a"))
+                else:
+                    # Must be TextIO - use it directly
+                    log_file_handle = log_file
+
+                transport = await stack.enter_async_context(
+                    stdio_client(server_params, errlog=log_file_handle)
+                )
+                read_stream, write_stream = transport
+                session_future.set_result(
+                    await stack.enter_async_context(
+                        ClientSession(read_stream, write_stream, **session_kwargs)
+                    )
+                )
+
+                logger.debug("Stdio transport connected")
+                ready_event.set()
+
+                # Wait until disconnect is requested (stop_event is set)
+                await stop_event.wait()
+            finally:
+                # Clean up client on exit
+                logger.debug("Stdio transport disconnected")
+    except Exception:
+        # Ensure ready event is set even if connection fails
+        ready_event.set()
+        raise
+
+
+class PythonStdioTransport(StdioTransport):
+    """Transport for running Python scripts."""
+
+    def __init__(
+        self,
+        script_path: str | Path,
+        args: list[str] | None = None,
+        env: dict[str, str] | None = None,
+        cwd: str | None = None,
+        python_cmd: str = sys.executable,
+        keep_alive: bool | None = None,
+        log_file: Path | TextIO | None = None,
+    ):
+        """
+        Initialize a Python transport.
+
+        Args:
+            script_path: Path to the Python script to run
+            args: Additional arguments to pass to the script
+            env: Environment variables to set for the subprocess
+            cwd: Current working directory for the subprocess
+            python_cmd: Python command to use (default: "python")
+            keep_alive: Whether to keep the subprocess alive between connections.
+                       Defaults to True. When True, the subprocess remains active
+                       after the connection context exits, allowing reuse in
+                       subsequent connections.
+            log_file: Optional path or file-like object where subprocess stderr will
+                   be written. Can be a Path or TextIO object. Defaults to sys.stderr
+                   if not provided. When a Path is provided, the file will be created
+                   if it doesn't exist, or appended to if it does. When set, server
+                   errors will be written to this file instead of appearing in the console.
+        """
+        script_path = Path(script_path).resolve()
+        if not script_path.is_file():
+            raise FileNotFoundError(f"Script not found: {script_path}")
+        if not str(script_path).endswith(".py"):
+            raise ValueError(f"Not a Python script: {script_path}")
+
+        full_args = [str(script_path)]
+        if args:
+            full_args.extend(args)
+
+        super().__init__(
+            command=python_cmd,
+            args=full_args,
+            env=env,
+            cwd=cwd,
+            keep_alive=keep_alive,
+            log_file=log_file,
+        )
+        self.script_path = script_path
+
+
+class FastMCPStdioTransport(StdioTransport):
+    """Transport for running FastMCP servers using the FastMCP CLI."""
+
+    def __init__(
+        self,
+        script_path: str | Path,
+        args: list[str] | None = None,
+        env: dict[str, str] | None = None,
+        cwd: str | None = None,
+        keep_alive: bool | None = None,
+        log_file: Path | TextIO | None = None,
+    ):
+        script_path = Path(script_path).resolve()
+        if not script_path.is_file():
+            raise FileNotFoundError(f"Script not found: {script_path}")
+        if not str(script_path).endswith(".py"):
+            raise ValueError(f"Not a Python script: {script_path}")
+
+        super().__init__(
+            command="fastmcp",
+            args=["run", str(script_path)],
+            env=env,
+            cwd=cwd,
+            keep_alive=keep_alive,
+            log_file=log_file,
+        )
+        self.script_path = script_path
+
+
+class NodeStdioTransport(StdioTransport):
+    """Transport for running Node.js scripts."""
+
+    def __init__(
+        self,
+        script_path: str | Path,
+        args: list[str] | None = None,
+        env: dict[str, str] | None = None,
+        cwd: str | None = None,
+        node_cmd: str = "node",
+        keep_alive: bool | None = None,
+        log_file: Path | TextIO | None = None,
+    ):
+        """
+        Initialize a Node transport.
+
+        Args:
+            script_path: Path to the Node.js script to run
+            args: Additional arguments to pass to the script
+            env: Environment variables to set for the subprocess
+            cwd: Current working directory for the subprocess
+            node_cmd: Node.js command to use (default: "node")
+            keep_alive: Whether to keep the subprocess alive between connections.
+                       Defaults to True. When True, the subprocess remains active
+                       after the connection context exits, allowing reuse in
+                       subsequent connections.
+            log_file: Optional path or file-like object where subprocess stderr will
+                   be written. Can be a Path or TextIO object. Defaults to sys.stderr
+                   if not provided. When a Path is provided, the file will be created
+                   if it doesn't exist, or appended to if it does. When set, server
+                   errors will be written to this file instead of appearing in the console.
+        """
+        script_path = Path(script_path).resolve()
+        if not script_path.is_file():
+            raise FileNotFoundError(f"Script not found: {script_path}")
+        if not str(script_path).endswith(".js"):
+            raise ValueError(f"Not a JavaScript script: {script_path}")
+
+        full_args = [str(script_path)]
+        if args:
+            full_args.extend(args)
+
+        super().__init__(
+            command=node_cmd,
+            args=full_args,
+            env=env,
+            cwd=cwd,
+            keep_alive=keep_alive,
+            log_file=log_file,
+        )
+        self.script_path = script_path
+
+
+class UvStdioTransport(StdioTransport):
+    """Transport for running commands via the uv tool."""
+
+    def __init__(
+        self,
+        command: str,
+        args: list[str] | None = None,
+        module: bool = False,
+        project_directory: Path | None = None,
+        python_version: str | None = None,
+        with_packages: list[str] | None = None,
+        with_requirements: Path | None = None,
+        env_vars: dict[str, str] | None = None,
+        keep_alive: bool | None = None,
+    ):
+        # Basic validation
+        if project_directory and not project_directory.exists():
+            raise NotADirectoryError(
+                f"Project directory not found: {project_directory}"
+            )
+
+        # Build uv arguments using the config
+        uv_args: list[str] = []
+
+        # Check if we need any environment setup
+        if any(
+            [
+                python_version,
+                with_packages,
+                with_requirements,
+                project_directory,
+            ]
+        ):
+            # Use the config to build args, but we need to handle the command differently
+            # since transport has specific needs
+            uv_args = ["run"]
+
+            if python_version:
+                uv_args.extend(["--python", python_version])
+            if project_directory:
+                uv_args.extend(["--directory", str(project_directory)])
+
+            # Note: Don't add fastmcp as dependency here, transport is for general use
+            for pkg in with_packages or []:
+                uv_args.extend(["--with", pkg])
+            if with_requirements:
+                uv_args.extend(["--with-requirements", str(with_requirements)])
+        else:
+            # No environment setup needed
+            uv_args = ["run"]
+
+        if module:
+            uv_args.append("--module")
+
+        if not args:
+            args = []
+
+        uv_args.extend([command, *args])
+
+        # Get environment with any additional variables
+        env: dict[str, str] | None = None
+        if env_vars or project_directory:
+            env = os.environ.copy()
+            if project_directory:
+                env["UV_PROJECT_DIR"] = str(project_directory)
+            if env_vars:
+                env.update(env_vars)
+
+        super().__init__(
+            command="uv",
+            args=uv_args,
+            env=env,
+            cwd=None,  # Use --directory flag instead of cwd
+            keep_alive=keep_alive,
+        )
+
+
+class UvxStdioTransport(StdioTransport):
+    """Transport for running commands via the uvx tool."""
+
+    def __init__(
+        self,
+        tool_name: str,
+        tool_args: list[str] | None = None,
+        project_directory: str | None = None,
+        python_version: str | None = None,
+        with_packages: list[str] | None = None,
+        from_package: str | None = None,
+        env_vars: dict[str, str] | None = None,
+        keep_alive: bool | None = None,
+    ):
+        """
+        Initialize a Uvx transport.
+
+        Args:
+            tool_name: Name of the tool to run via uvx
+            tool_args: Arguments to pass to the tool
+            project_directory: Project directory (for package resolution)
+            python_version: Python version to use
+            with_packages: Additional packages to include
+            from_package: Package to install the tool from
+            env_vars: Additional environment variables
+            keep_alive: Whether to keep the subprocess alive between connections.
+                       Defaults to True. When True, the subprocess remains active
+                       after the connection context exits, allowing reuse in
+                       subsequent connections.
+        """
+        # Basic validation
+        if project_directory and not Path(project_directory).exists():
+            raise NotADirectoryError(
+                f"Project directory not found: {project_directory}"
+            )
+
+        # Build uvx arguments
+        uvx_args: list[str] = []
+        if python_version:
+            uvx_args.extend(["--python", python_version])
+        if from_package:
+            uvx_args.extend(["--from", from_package])
+        for pkg in with_packages or []:
+            uvx_args.extend(["--with", pkg])
+
+        # Add the tool name and tool args
+        uvx_args.append(tool_name)
+        if tool_args:
+            uvx_args.extend(tool_args)
+
+        env: dict[str, str] | None = None
+        if env_vars:
+            env = os.environ.copy()
+            env.update(env_vars)
+
+        super().__init__(
+            command="uvx",
+            args=uvx_args,
+            env=env,
+            cwd=project_directory,
+            keep_alive=keep_alive,
+        )
+        self.tool_name: str = tool_name
+
+
+class NpxStdioTransport(StdioTransport):
+    """Transport for running commands via the npx tool."""
+
+    def __init__(
+        self,
+        package: str,
+        args: list[str] | None = None,
+        project_directory: str | None = None,
+        env_vars: dict[str, str] | None = None,
+        use_package_lock: bool = True,
+        keep_alive: bool | None = None,
+    ):
+        """
+        Initialize an Npx transport.
+
+        Args:
+            package: Name of the npm package to run
+            args: Arguments to pass to the package command
+            project_directory: Project directory with package.json
+            env_vars: Additional environment variables
+            use_package_lock: Whether to use package-lock.json (--prefer-offline)
+            keep_alive: Whether to keep the subprocess alive between connections.
+                       Defaults to True. When True, the subprocess remains active
+                       after the connection context exits, allowing reuse in
+                       subsequent connections.
+        """
+        # verify npx is installed
+        if shutil.which("npx") is None:
+            raise ValueError("Command 'npx' not found")
+
+        # Basic validation
+        if project_directory and not Path(project_directory).exists():
+            raise NotADirectoryError(
+                f"Project directory not found: {project_directory}"
+            )
+
+        # Build npx arguments
+        npx_args = []
+        if use_package_lock:
+            npx_args.append("--prefer-offline")
+
+        # Add the package name and args
+        npx_args.append(package)
+        if args:
+            npx_args.extend(args)
+
+        # Get environment with any additional variables
+        env = None
+        if env_vars:
+            env = os.environ.copy()
+            env.update(env_vars)
+
+        super().__init__(
+            command="npx",
+            args=npx_args,
+            env=env,
+            cwd=project_directory,
+            keep_alive=keep_alive,
+        )
+        self.package = package
diff --git a/fastmcp_slim/fastmcp/contrib/README.md b/fastmcp_slim/fastmcp/contrib/README.md
new file mode 100644
index 0000000..7b1dbb5
--- /dev/null
+++ b/fastmcp_slim/fastmcp/contrib/README.md
@@ -0,0 +1,19 @@
+# FastMCP Contrib Modules
+
+This directory holds community-contributed modules for FastMCP. These modules extend FastMCP's functionality but are not officially maintained by the core team.
+
+**Guarantees:**
+*   Modules in `contrib` may have different testing requirements or stability guarantees compared to the core library.
+*   Changes to the core FastMCP library might break modules in `contrib` without explicit warnings in the main changelog.
+
+Use these modules at your own discretion. Contributions are welcome, but please include tests and documentation.
+
+## Usage
+
+To use a contrib module, import it from the `fastmcp.contrib` package.
+
+```python
+from fastmcp.contrib import my_module
+```
+
+Note that the contrib modules may have different dependencies than the core library, which can be noted in their respective README's or even separate requirements / dependency files.
\ No newline at end of file
diff --git a/fastmcp_slim/fastmcp/contrib/bulk_tool_caller/README.md b/fastmcp_slim/fastmcp/contrib/bulk_tool_caller/README.md
new file mode 100644
index 0000000..41daa77
--- /dev/null
+++ b/fastmcp_slim/fastmcp/contrib/bulk_tool_caller/README.md
@@ -0,0 +1,35 @@
+# Bulk Tool Caller
+
+This module provides the `BulkToolCaller` class, which extends the `MCPMixin` to offer tools for performing multiple tool calls in a single request to a FastMCP server. This can be useful for optimizing interactions with the server by reducing the overhead of individual tool calls.
+
+## Usage
+
+To use the `BulkToolCaller`, see the example [example.py](./example.py) file. The `BulkToolCaller` can be instantiated and then registered with a FastMCP server URL. It provides methods to call multiple tools in bulk, either different tools or the same tool with different arguments.
+
+
+## Provided Tools
+
+The `BulkToolCaller` provides the following tools:
+
+### `call_tools_bulk`
+
+Calls multiple different tools registered on the MCP server in a single request.
+
+- **Arguments:**
+    - `tool_calls` (list of `CallToolRequest`): A list of objects, where each object specifies the `tool` name and `arguments` for an individual tool call.
+    - `continue_on_error` (bool, optional): If `True`, continue executing subsequent tool calls even if a previous one resulted in an error. Defaults to `True`.
+
+- **Returns:**
+    A list of `CallToolRequestResult` objects, each containing the result (`isError`, `content`) and the original `tool` name and `arguments` for each call.
+
+### `call_tool_bulk`
+
+Calls a single tool registered on the MCP server multiple times with different arguments in a single request.
+
+- **Arguments:**
+    - `tool` (str): The name of the tool to call.
+    - `tool_arguments` (list of dict): A list of dictionaries, where each dictionary contains the arguments for an individual run of the tool.
+    - `continue_on_error` (bool, optional): If `True`, continue executing subsequent tool calls even if a previous one resulted in an error. Defaults to `True`.
+
+- **Returns:**
+    A list of `CallToolRequestResult` objects, each containing the result (`isError`, `content`) and the original `tool` name and `arguments` for each call.
\ No newline at end of file
diff --git a/fastmcp_slim/fastmcp/contrib/bulk_tool_caller/__init__.py b/fastmcp_slim/fastmcp/contrib/bulk_tool_caller/__init__.py
new file mode 100644
index 0000000..b8f66ed
--- /dev/null
+++ b/fastmcp_slim/fastmcp/contrib/bulk_tool_caller/__init__.py
@@ -0,0 +1,3 @@
+from .bulk_tool_caller import BulkToolCaller
+
+__all__ = ["BulkToolCaller"]
diff --git a/fastmcp_slim/fastmcp/contrib/bulk_tool_caller/bulk_tool_caller.py b/fastmcp_slim/fastmcp/contrib/bulk_tool_caller/bulk_tool_caller.py
new file mode 100644
index 0000000..ab7c20e
--- /dev/null
+++ b/fastmcp_slim/fastmcp/contrib/bulk_tool_caller/bulk_tool_caller.py
@@ -0,0 +1,151 @@
+from typing import Any
+
+from mcp_types import CallToolResult, TextContent
+from pydantic import BaseModel, Field
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.transports import FastMCPTransport
+from fastmcp.contrib.mcp_mixin.mcp_mixin import (
+    _DEFAULT_SEPARATOR_TOOL,
+    MCPMixin,
+    mcp_tool,
+)
+
+
+class CallToolRequest(BaseModel):
+    """A class to represent a request to call a tool with specific arguments."""
+
+    tool: str = Field(description="The name of the tool to call.")
+    arguments: dict[str, Any] = Field(
+        description="A dictionary containing the arguments for the tool call."
+    )
+
+
+class CallToolRequestResult(CallToolResult):
+    """
+    A class to represent the result of a bulk tool call.
+    It extends CallToolResult to include information about the requested tool call.
+    """
+
+    tool: str = Field(description="The name of the tool that was called.")
+    arguments: dict[str, Any] = Field(
+        description="The arguments used for the tool call."
+    )
+
+    @classmethod
+    def from_call_tool_result(
+        cls, result: CallToolResult, tool: str, arguments: dict[str, Any]
+    ) -> "CallToolRequestResult":
+        """
+        Create a CallToolRequestResult from a CallToolResult.
+        """
+        return cls(
+            tool=tool,
+            arguments=arguments,
+            is_error=result.is_error,
+            content=result.content,
+        )
+
+
+class BulkToolCaller(MCPMixin):
+    """
+    A class to provide a "bulk tool call" tool for a FastMCP server
+    """
+
+    _BULK_TOOL_NAMES: frozenset[str] = frozenset({"call_tools_bulk", "call_tool_bulk"})
+
+    def register_tools(
+        self,
+        mcp_server: "FastMCP",
+        prefix: str | None = None,
+        separator: str = _DEFAULT_SEPARATOR_TOOL,
+    ) -> None:
+        """
+        Register the tools provided by this class with the given MCP server.
+        """
+        self.connection = FastMCPTransport(mcp_server)
+
+        super().register_tools(mcp_server=mcp_server)
+
+    @mcp_tool()
+    async def call_tools_bulk(
+        self, tool_calls: list[CallToolRequest], continue_on_error: bool = True
+    ) -> list[CallToolRequestResult]:
+        """
+        Call multiple tools registered on this MCP server in a single request. Each call can
+         be for a different tool and can include different arguments. Useful for speeding up
+         what would otherwise take several individual tool calls.
+        """
+        results = []
+
+        for tool_call in tool_calls:
+            result = await self._call_tool(tool_call.tool, tool_call.arguments)
+
+            results.append(result)
+
+            if result.is_error and not continue_on_error:
+                return results
+
+        return results
+
+    @mcp_tool()
+    async def call_tool_bulk(
+        self,
+        tool: str,
+        tool_arguments: list[dict[str, str | int | float | bool | None]],
+        continue_on_error: bool = True,
+    ) -> list[CallToolRequestResult]:
+        """
+        Call a single tool registered on this MCP server multiple times with a single request.
+         Each call can include different arguments. Useful for speeding up what would otherwise
+         take several individual tool calls.
+
+        Args:
+            tool: The name of the tool to call.
+            tool_arguments: A list of dictionaries, where each dictionary contains the arguments for an individual run of the tool.
+        """
+        results = []
+
+        for tool_call_arguments in tool_arguments:
+            result = await self._call_tool(tool, tool_call_arguments)
+
+            results.append(result)
+
+            if result.is_error and not continue_on_error:
+                return results
+
+        return results
+
+    async def _call_tool(
+        self, tool: str, arguments: dict[str, Any]
+    ) -> CallToolRequestResult:
+        """
+        Helper method to call a tool with the provided arguments.
+        """
+
+        if tool in self._BULK_TOOL_NAMES:
+            return CallToolRequestResult(
+                tool=tool,
+                arguments=arguments,
+                is_error=True,
+                content=[
+                    TextContent(
+                        type="text",
+                        text=(
+                            "BulkToolCaller cannot call itself. "
+                            "The tools 'call_tools_bulk' and 'call_tool_bulk' are disallowed."
+                        ),
+                    )
+                ],
+            )
+
+        async with Client(self.connection) as client:
+            result = await client.call_tool_mcp(name=tool, arguments=arguments)
+
+            return CallToolRequestResult(
+                tool=tool,
+                arguments=arguments,
+                is_error=result.is_error,
+                content=result.content,
+            )
diff --git a/fastmcp_slim/fastmcp/contrib/bulk_tool_caller/example.py b/fastmcp_slim/fastmcp/contrib/bulk_tool_caller/example.py
new file mode 100644
index 0000000..b86a53e
--- /dev/null
+++ b/fastmcp_slim/fastmcp/contrib/bulk_tool_caller/example.py
@@ -0,0 +1,17 @@
+"""Sample code for FastMCP using MCPMixin."""
+
+from fastmcp import FastMCP
+from fastmcp.contrib.bulk_tool_caller import BulkToolCaller
+
+mcp = FastMCP()
+
+
+@mcp.tool
+def echo_tool(text: str) -> str:
+    """Echo the input text"""
+    return text
+
+
+bulk_tool_caller = BulkToolCaller()
+
+bulk_tool_caller.register_tools(mcp)
diff --git a/fastmcp_slim/fastmcp/contrib/component_manager/README.md b/fastmcp_slim/fastmcp/contrib/component_manager/README.md
new file mode 100644
index 0000000..0cc99ad
--- /dev/null
+++ b/fastmcp_slim/fastmcp/contrib/component_manager/README.md
@@ -0,0 +1,164 @@
+# Component Manager – Contrib Module for FastMCP
+
+The **Component Manager** provides a unified API for enabling and disabling tools, resources, and prompts at runtime in a FastMCP server. This module is useful for dynamic control over which components are active, enabling advanced features like feature toggling, admin interfaces, or automation workflows.
+
+---
+
+## 🔧 Features
+
+- Enable/disable **tools**, **resources**, and **prompts** via HTTP endpoints.
+- Supports **local** and **mounted (server)** components.
+- Customizable **API root path**.
+- Optional **Auth scopes** for secured access.
+- Fully integrates with FastMCP with minimal configuration.
+
+---
+
+## 📦 Installation
+
+This module is part of the `fastmcp.contrib` package. No separate installation is required if you're already using **FastMCP**.
+
+---
+
+## 🚀 Usage
+
+### Basic Setup
+
+```python
+from fastmcp import FastMCP
+from fastmcp.contrib.component_manager import set_up_component_manager
+
+mcp = FastMCP(name="Component Manager", instructions="This is a test server with component manager.")
+set_up_component_manager(server=mcp)
+```
+
+---
+
+## 🔗 API Endpoints
+
+All endpoints are registered at `/` by default, or under the custom path if one is provided.
+
+### Tools
+
+```http
+POST /tools/{tool_name}/enable
+POST /tools/{tool_name}/disable
+```
+
+### Resources
+
+```http
+POST /resources/{uri:path}/enable
+POST /resources/{uri:path}/disable
+```
+
+ * Supports template URIs as well
+```http
+POST /resources/example://test/{id}/enable
+POST /resources/example://test/{id}/disable
+```
+
+### Prompts
+
+```http
+POST /prompts/{prompt_name}/enable
+POST /prompts/{prompt_name}/disable
+```
+---
+
+#### 🧪 Example Response
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "message": "Disabled tool: example_tool"
+}
+
+```
+
+---
+
+## ⚙️ Configuration Options
+
+### Custom Root Path
+
+To mount the API under a different path:
+
+```python
+set_up_component_manager(server=mcp, path="/admin")
+```
+
+### Securing Endpoints with Auth Scopes
+
+If your server uses authentication:
+
+```python
+mcp = FastMCP(name="Component Manager", instructions="This is a test server with component manager.", auth=auth)
+set_up_component_manager(server=mcp, required_scopes=["write", "read"])
+```
+
+---
+
+## 🧪 Example: Enabling a Tool with Curl
+
+```bash
+curl -X POST \
+  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
+  -H "Content-Type: application/json" \
+  http://localhost:8001/tools/example_tool/enable
+```
+
+---
+
+## 🧱 Working with Mounted Servers
+
+You can also combine different configurations when working with mounted servers — for example, using different scopes:
+
+```python
+mcp = FastMCP(name="Component Manager", instructions="This is a test server with component manager.", auth=auth)
+set_up_component_manager(server=mcp, required_scopes=["mcp:write"])
+
+mounted = FastMCP(name="Component Manager", instructions="This is a test server with component manager.", auth=auth)
+set_up_component_manager(server=mounted, required_scopes=["mounted:write"])
+
+mcp.mount(server=mounted, namespace="mo")
+```
+
+This allows you to grant different levels of access:
+
+```bash
+# Accessing the main server gives you control over both local and mounted components
+curl -X POST \
+  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
+  -H "Content-Type: application/json" \
+  http://localhost:8001/tools/mo_example_tool/enable
+
+# Accessing the mounted server gives you control only over its own components
+curl -X POST \
+  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
+  -H "Content-Type: application/json" \
+  http://localhost:8002/tools/example_tool/enable
+```
+
+---
+
+## ⚙️ How It Works
+
+- `set_up_component_manager()` registers HTTP routes for tools, resources, and prompts.
+- Each endpoint calls `server.enable()` or `server.disable()` with the component name.
+- Returns a success message in JSON.
+
+---
+
+## Maintenance Notice
+
+This module is not officially maintained by the core FastMCP team. It is an independent extension developed by [gorocode](https://github.com/gorocode).
+
+If you encounter any issues or wish to contribute, please feel free to open an issue or submit a pull request, and kindly notify me. I'd love to stay up to date.
+
+
+## 📄 License
+
+This module follows the license of the main [FastMCP](https://github.com/PrefectHQ/fastmcp) project.
\ No newline at end of file
diff --git a/fastmcp_slim/fastmcp/contrib/component_manager/__init__.py b/fastmcp_slim/fastmcp/contrib/component_manager/__init__.py
new file mode 100644
index 0000000..b89a6d9
--- /dev/null
+++ b/fastmcp_slim/fastmcp/contrib/component_manager/__init__.py
@@ -0,0 +1,3 @@
+from .component_manager import set_up_component_manager
+
+__all__ = ["set_up_component_manager"]
diff --git a/fastmcp_slim/fastmcp/contrib/component_manager/component_manager.py b/fastmcp_slim/fastmcp/contrib/component_manager/component_manager.py
new file mode 100644
index 0000000..099b905
--- /dev/null
+++ b/fastmcp_slim/fastmcp/contrib/component_manager/component_manager.py
@@ -0,0 +1,121 @@
+"""
+HTTP routes for enabling/disabling components in FastMCP.
+
+Provides REST endpoints for controlling component enabled state with optional
+authentication scopes.
+"""
+
+from mcp.server.auth.middleware.bearer_auth import RequireAuthMiddleware
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.routing import Mount, Route
+
+from fastmcp.server.server import FastMCP
+
+
+def set_up_component_manager(
+    server: FastMCP, path: str = "/", required_scopes: list[str] | None = None
+) -> None:
+    """Set up HTTP routes for enabling/disabling tools, resources, and prompts.
+
+    Args:
+        server: The FastMCP server instance.
+        path: Base path for component management routes.
+        required_scopes: Optional list of scopes required for these routes.
+            Applies only if authentication is enabled.
+
+    Routes created:
+        POST /tools/{name}/enable[?version=v1]
+        POST /tools/{name}/disable[?version=v1]
+        POST /resources/{uri}/enable[?version=v1]
+        POST /resources/{uri}/disable[?version=v1]
+        POST /prompts/{name}/enable[?version=v1]
+        POST /prompts/{name}/disable[?version=v1]
+    """
+    if required_scopes is None:
+        # No auth - include path prefix in routes
+        routes = _build_routes(server, path)
+        server._additional_http_routes.extend(routes)
+    else:
+        # With auth - Mount handles path prefix, routes shouldn't have it
+        routes = _build_routes(server, "/")
+        mount = Mount(
+            path if path != "/" else "",
+            app=RequireAuthMiddleware(Starlette(routes=routes), required_scopes),
+        )
+        server._additional_http_routes.append(mount)
+
+
+def _build_routes(server: FastMCP, base_path: str) -> list[Route]:
+    """Build all component management routes."""
+    prefix = base_path.rstrip("/") if base_path != "/" else ""
+
+    return [
+        # Tools
+        Route(
+            f"{prefix}/tools/{{name}}/enable",
+            endpoint=_make_endpoint(server, "tool", "enable"),
+            methods=["POST"],
+        ),
+        Route(
+            f"{prefix}/tools/{{name}}/disable",
+            endpoint=_make_endpoint(server, "tool", "disable"),
+            methods=["POST"],
+        ),
+        # Resources
+        Route(
+            f"{prefix}/resources/{{uri:path}}/enable",
+            endpoint=_make_endpoint(server, "resource", "enable"),
+            methods=["POST"],
+        ),
+        Route(
+            f"{prefix}/resources/{{uri:path}}/disable",
+            endpoint=_make_endpoint(server, "resource", "disable"),
+            methods=["POST"],
+        ),
+        # Prompts
+        Route(
+            f"{prefix}/prompts/{{name}}/enable",
+            endpoint=_make_endpoint(server, "prompt", "enable"),
+            methods=["POST"],
+        ),
+        Route(
+            f"{prefix}/prompts/{{name}}/disable",
+            endpoint=_make_endpoint(server, "prompt", "disable"),
+            methods=["POST"],
+        ),
+    ]
+
+
+def _make_endpoint(server: FastMCP, component_type: str, action: str):
+    """Create an endpoint function for enabling/disabling a component type."""
+
+    async def endpoint(request: Request) -> JSONResponse:
+        # Get name from path params (tools/prompts use 'name', resources use 'uri')
+        name = request.path_params.get("name") or request.path_params.get("uri")
+        version = request.query_params.get("version")
+
+        # Map component type to components list
+        # Note: "resource" in the route can refer to either a resource or template
+        # We need to check if it's a template (contains {}) and use "template" if so
+        if component_type == "resource" and name is not None and "{" in name:
+            components = ["template"]
+        elif component_type == "resource":
+            components = ["resource"]
+        else:
+            component_map = {
+                "tool": ["tool"],
+                "prompt": ["prompt"],
+            }
+            components = component_map[component_type]
+
+        # Call server.enable() or server.disable()
+        method = getattr(server, action)
+        method(names={name} if name else None, version=version, components=components)
+
+        return JSONResponse(
+            {"message": f"{action.capitalize()}d {component_type}: {name}"}
+        )
+
+    return endpoint
diff --git a/fastmcp_slim/fastmcp/contrib/component_manager/example.py b/fastmcp_slim/fastmcp/contrib/component_manager/example.py
new file mode 100644
index 0000000..7780f8a
--- /dev/null
+++ b/fastmcp_slim/fastmcp/contrib/component_manager/example.py
@@ -0,0 +1,59 @@
+from fastmcp import FastMCP
+from fastmcp.contrib.component_manager import set_up_component_manager
+from fastmcp.server.auth.providers.jwt import JWTVerifier, RSAKeyPair
+
+key_pair = RSAKeyPair.generate()
+
+auth = JWTVerifier(
+    public_key=key_pair.public_key,
+    issuer="https://dev.example.com",
+    audience="my-dev-server",
+    required_scopes=["mcp:read"],
+)
+
+# Build main server
+mcp_token = key_pair.create_token(
+    subject="dev-user",
+    issuer="https://dev.example.com",
+    audience="my-dev-server",
+    scopes=["mcp:write", "mcp:read"],
+)
+mcp = FastMCP(
+    name="Component Manager",
+    instructions="This is a test server with component manager.",
+    auth=auth,
+)
+
+# Set up main server component manager
+set_up_component_manager(server=mcp, required_scopes=["mcp:write"])
+
+# Build mounted server
+mounted_token = key_pair.create_token(
+    subject="dev-user",
+    issuer="https://dev.example.com",
+    audience="my-dev-server",
+    scopes=["mounted:write", "mcp:read"],
+)
+mounted = FastMCP(
+    name="Component Manager",
+    instructions="This is a test server with component manager.",
+    auth=auth,
+)
+
+# Set up mounted server component manager
+set_up_component_manager(server=mounted, required_scopes=["mounted:write"])
+
+# Mount
+mcp.mount(server=mounted, namespace="mo")
+
+
+@mcp.resource("resource://greeting")
+def get_greeting() -> str:
+    """Provides a simple greeting message."""
+    return "Hello from FastMCP Resources!"
+
+
+@mounted.tool("greeting")
+def get_info() -> str:
+    """Provides a simple info."""
+    return "You are using component manager contrib module!"
diff --git a/fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md b/fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md
new file mode 100644
index 0000000..39c3a23
--- /dev/null
+++ b/fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md
@@ -0,0 +1,147 @@
+from mcp.types import ToolAnnotations
+
+# MCP Mixin
+
+This module provides the `MCPMixin` base class and associated decorators (`@mcp_tool`, `@mcp_resource`, `@mcp_prompt`).
+
+It allows developers to easily define classes whose methods can be registered as tools, resources, or prompts with a `FastMCP` server instance using the `register_all()`, `register_tools()`, `register_resources()`, or `register_prompts()` methods provided by the mixin.
+
+Includes support for
+Tools:
+* [enable/disable](https://gofastmcp.com/servers/tools#disabling-tools)
+* [annotations](https://gofastmcp.com/servers/tools#annotations-2)
+* [excluded arguments](https://gofastmcp.com/servers/tools#excluding-arguments)
+* [meta](https://gofastmcp.com/servers/tools#param-meta)
+
+Prompts:
+* [enable/disable](https://gofastmcp.com/servers/prompts#disabling-prompts)
+* [meta](https://gofastmcp.com/servers/prompts#param-meta)
+
+Resources:
+* [enable/disable](https://gofastmcp.com/servers/resources#disabling-resources)
+* [meta](https://gofastmcp.com/servers/resources#param-meta)
+  
+## Usage
+
+Inherit from `MCPMixin` and use the decorators on the methods you want to register.
+
+```python
+from mcp.types import ToolAnnotations
+from fastmcp import FastMCP
+from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool, mcp_resource, mcp_prompt
+
+class MyComponent(MCPMixin):
+    @mcp_tool(name="my_tool", description="Does something cool.")
+    def tool_method(self):
+        return "Tool executed!"
+
+    # example of disabled tool
+    @mcp_tool(name="my_tool", description="Does something cool.", enabled=False)
+    def disabled_tool_method(self):
+        # This function can't be called by client because it's disabled
+        return "You'll never get here!"
+
+    # example of excluded parameter tool
+    @mcp_tool(
+        name="my_tool", description="Does something cool.",
+        enabled=False, exclude_args=['delete_everything'],
+    )
+    def excluded_param_tool_method(self, delete_everything=False):
+        # MCP tool calls can't pass the "delete_everything" argument
+        if delete_everything:
+            return "Nothing to delete, I bet you're not a tool :)"
+        return "You might be a tool if..."
+
+    # example tool w/annotations
+    @mcp_tool(
+        name="my_tool", description="Does something cool.",
+        annotations=ToolAnnotations(
+            title="Attn LLM, use this tool first!",
+            readOnlyHint=False,
+            destructiveHint=False,
+            idempotentHint=False,
+        )
+    )
+    def tool_method(self):
+        return "Tool executed!"
+
+    # example tool w/everything
+    @mcp_tool(
+        name="my_tool", description="Does something cool.",
+        enabled=True,
+        exclude_args=['delete_all'],
+        annotations=ToolAnnotations(
+            title="Attn LLM, use this tool first!",
+            readOnlyHint=False,
+            destructiveHint=False,
+            idempotentHint=False,
+        )
+    )
+    def tool_method(self, delete_all=False):
+        if delete_all:
+            return "99 records deleted. I bet you're not a tool :)"
+        return "Tool executed, but you might be a tool!"
+
+    # example tool w/ meta
+    @mcp_tool(
+        name="data_tool",
+        description="Fetches user data from database",
+        meta={"version": "2.0", "category": "database", "author": "dev-team"}
+    )
+    def data_tool_method(self, user_id: int):
+        return f"Fetching data for user {user_id}"
+
+    @mcp_resource(uri="component://data")
+    def resource_method(self):
+        return {"data": "some data"}
+
+    # Disabled resource
+    @mcp_resource(uri="component://data", enabled=False)
+    def resource_method(self):
+        return {"data": "some data"}
+
+    # example resource w/meta and title
+    @mcp_resource(
+        uri="component://config",
+        title="Data resource Title,
+        meta={"internal": True, "cache_ttl": 3600, "priority": "high"}
+    )
+    def config_resource_method(self):
+        return {"config": "data"}
+
+    # prompt
+    @mcp_prompt(name="A prompt")
+    def prompt_method(self, name):
+        return f"What's up {name}?"
+
+    # disabled prompt
+    @mcp_prompt(name="A prompt", enabled=False)
+    def prompt_method(self, name):
+        return f"What's up {name}?"
+
+    # example prompt w/title and meta
+    @mcp_prompt(
+        name="analysis_prompt",
+        title="Data Analysis Prompt",
+        description="Analyzes data patterns",
+        meta={"complexity": "high", "domain": "analytics", "requires_context": True}
+    )
+    def analysis_prompt_method(self, dataset: str):
+        return f"Analyze the patterns in {dataset}"
+
+mcp_server = FastMCP()
+component = MyComponent()
+
+# Register all decorated methods with a prefix
+# Useful if you will have multiple instantiated objects of the same class
+# and want to avoid name collisions.
+component.register_all(mcp_server, prefix="my_comp") 
+
+# Register without a prefix
+# component.register_all(mcp_server) 
+
+# Now 'my_comp_my_tool' tool and 'my_comp+component://data' resource are registered (if prefix used)
+# Or 'my_tool' and 'component://data' are registered (if no prefix used)
+```
+
+The `prefix` argument in registration methods is optional. If omitted, methods are registered with their original decorated names/URIs. Individual separators (`tools_separator`, `resources_separator`, `prompts_separator`) can also be provided to `register_all` to change the separator for specific types.
diff --git a/fastmcp_slim/fastmcp/contrib/mcp_mixin/__init__.py b/fastmcp_slim/fastmcp/contrib/mcp_mixin/__init__.py
new file mode 100644
index 0000000..48a5366
--- /dev/null
+++ b/fastmcp_slim/fastmcp/contrib/mcp_mixin/__init__.py
@@ -0,0 +1,8 @@
+from .mcp_mixin import MCPMixin, mcp_tool, mcp_resource, mcp_prompt
+
+__all__ = [
+    "MCPMixin",
+    "mcp_prompt",
+    "mcp_resource",
+    "mcp_tool",
+]
diff --git a/fastmcp_slim/fastmcp/contrib/mcp_mixin/example.py b/fastmcp_slim/fastmcp/contrib/mcp_mixin/example.py
new file mode 100644
index 0000000..b282b58
--- /dev/null
+++ b/fastmcp_slim/fastmcp/contrib/mcp_mixin/example.py
@@ -0,0 +1,52 @@
+"""Sample code for FastMCP using MCPMixin."""
+
+import asyncio
+
+from fastmcp import FastMCP
+from fastmcp.contrib.mcp_mixin import (
+    MCPMixin,
+    mcp_prompt,
+    mcp_resource,
+    mcp_tool,
+)
+
+mcp = FastMCP()
+
+
+class Sample(MCPMixin):
+    def __init__(self, name):
+        self.name = name
+
+    @mcp_tool()
+    def first_tool(self):
+        """First tool description."""
+        return f"Executed tool {self.name}."
+
+    @mcp_resource(uri="test://test")
+    def first_resource(self):
+        """First resource description."""
+        return f"Executed resource {self.name}."
+
+    @mcp_prompt()
+    def first_prompt(self):
+        """First prompt description."""
+        return f"here's a prompt! {self.name}."
+
+
+first_sample = Sample("First")
+second_sample = Sample("Second")
+
+first_sample.register_all(mcp_server=mcp, prefix="first")
+second_sample.register_all(mcp_server=mcp, prefix="second")
+
+
+async def list_components() -> None:
+    print("MCP Server running with registered components...")
+    print("Tools:", list(await mcp.list_tools()))
+    print("Resources:", list(await mcp.list_resources()))
+    print("Prompts:", list(await mcp.list_prompts()))
+
+
+if __name__ == "__main__":
+    asyncio.run(list_components())
+    mcp.run()
diff --git a/fastmcp_slim/fastmcp/contrib/mcp_mixin/mcp_mixin.py b/fastmcp_slim/fastmcp/contrib/mcp_mixin/mcp_mixin.py
new file mode 100644
index 0000000..3503596
--- /dev/null
+++ b/fastmcp_slim/fastmcp/contrib/mcp_mixin/mcp_mixin.py
@@ -0,0 +1,309 @@
+"""Provides a base mixin class and decorators for easy registration of class methods with FastMCP."""
+
+import inspect
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from fastmcp.prompts.base import Prompt
+from fastmcp.resources.base import Resource
+from fastmcp.tools.base import Tool
+from fastmcp.utilities.types import get_fn_name
+
+if TYPE_CHECKING:
+    from fastmcp.server import FastMCP
+
+_MCP_REGISTRATION_TOOL_ATTR = "_mcp_tool_registration"
+_MCP_REGISTRATION_RESOURCE_ATTR = "_mcp_resource_registration"
+_MCP_REGISTRATION_PROMPT_ATTR = "_mcp_prompt_registration"
+
+_DEFAULT_SEPARATOR_TOOL = "_"
+_DEFAULT_SEPARATOR_RESOURCE = "+"
+_DEFAULT_SEPARATOR_PROMPT = "_"
+
+# Sentinel key stored in registration dicts for the mixin-only `enabled` flag.
+# Prefixed with an underscore to avoid collisions with any from_function parameter.
+_MIXIN_ENABLED_KEY = "_mixin_enabled"
+
+# Valid keyword arguments for each from_function, derived once at import time
+# directly from the live signatures.  They stay in sync automatically whenever
+# the underlying signatures gain or lose parameters — no manual updates needed.
+_TOOL_VALID_KWARGS: frozenset[str] = frozenset(
+    p for p in inspect.signature(Tool.from_function).parameters if p != "fn"
+)
+_RESOURCE_VALID_KWARGS: frozenset[str] = frozenset(
+    p
+    for p in inspect.signature(Resource.from_function).parameters
+    if p not in ("fn", "uri")
+)
+_PROMPT_VALID_KWARGS: frozenset[str] = frozenset(
+    p for p in inspect.signature(Prompt.from_function).parameters if p != "fn"
+)
+
+
+def mcp_tool(
+    name: str | None = None,
+    *,
+    enabled: bool | None = None,
+    **kwargs: Any,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator to mark a method as an MCP tool for later registration.
+
+    Accepts all parameters supported by ``Tool.from_function``.  Any new
+    parameters added to ``Tool.from_function`` are automatically forwarded
+    without requiring changes here.
+
+    Args:
+        name: Tool name.  Defaults to the decorated method name.
+        enabled: If ``False``, the tool is skipped during registration.
+        **kwargs: Additional keyword arguments forwarded verbatim to
+            ``Tool.from_function`` (e.g. ``description``, ``tags``,
+            ``annotations``, ``auth``, ``timeout``, ``version``, …).
+
+    Raises:
+        TypeError: If an unrecognised keyword argument is supplied.  The error
+            is raised immediately at decoration time rather than later.
+    """
+    unknown = set(kwargs) - _TOOL_VALID_KWARGS
+    if unknown:
+        raise TypeError(
+            f"mcp_tool() got unexpected keyword argument(s): {sorted(unknown)!r}. "
+            f"Valid keyword arguments are: {sorted(_TOOL_VALID_KWARGS)}"
+        )
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        call_args: dict[str, Any] = {"name": name or get_fn_name(func), **kwargs}
+        if enabled is not None:
+            call_args[_MIXIN_ENABLED_KEY] = enabled
+        setattr(func, _MCP_REGISTRATION_TOOL_ATTR, call_args)
+        return func
+
+    return decorator
+
+
+def mcp_resource(
+    uri: str,
+    *,
+    name: str | None = None,
+    enabled: bool | None = None,
+    **kwargs: Any,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator to mark a method as an MCP resource for later registration.
+
+    Accepts all parameters supported by ``Resource.from_function``.  Any new
+    parameters added to ``Resource.from_function`` are automatically forwarded
+    without requiring changes here.
+
+    Args:
+        uri: Resource URI (required).
+        name: Resource name.  Defaults to the decorated method name.
+        enabled: If ``False``, the resource is skipped during registration.
+        **kwargs: Additional keyword arguments forwarded verbatim to
+            ``Resource.from_function`` (e.g. ``description``, ``tags``,
+            ``mime_type``, ``auth``, ``version``, …).
+
+    Raises:
+        TypeError: If an unrecognised keyword argument is supplied.  The error
+            is raised immediately at decoration time rather than later.
+    """
+    unknown = set(kwargs) - _RESOURCE_VALID_KWARGS
+    if unknown:
+        raise TypeError(
+            f"mcp_resource() got unexpected keyword argument(s): {sorted(unknown)!r}. "
+            f"Valid keyword arguments are: {sorted(_RESOURCE_VALID_KWARGS)}"
+        )
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        call_args: dict[str, Any] = {
+            "uri": uri,
+            "name": name or get_fn_name(func),
+            **kwargs,
+        }
+        if enabled is not None:
+            call_args[_MIXIN_ENABLED_KEY] = enabled
+        setattr(func, _MCP_REGISTRATION_RESOURCE_ATTR, call_args)
+        return func
+
+    return decorator
+
+
+def mcp_prompt(
+    name: str | None = None,
+    *,
+    enabled: bool | None = None,
+    **kwargs: Any,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator to mark a method as an MCP prompt for later registration.
+
+    Accepts all parameters supported by ``Prompt.from_function``.  Any new
+    parameters added to ``Prompt.from_function`` are automatically forwarded
+    without requiring changes here.
+
+    Args:
+        name: Prompt name.  Defaults to the decorated method name.
+        enabled: If ``False``, the prompt is skipped during registration.
+        **kwargs: Additional keyword arguments forwarded verbatim to
+            ``Prompt.from_function`` (e.g. ``description``, ``tags``,
+            ``auth``, ``version``, …).
+
+    Raises:
+        TypeError: If an unrecognised keyword argument is supplied.  The error
+            is raised immediately at decoration time rather than later.
+    """
+    unknown = set(kwargs) - _PROMPT_VALID_KWARGS
+    if unknown:
+        raise TypeError(
+            f"mcp_prompt() got unexpected keyword argument(s): {sorted(unknown)!r}. "
+            f"Valid keyword arguments are: {sorted(_PROMPT_VALID_KWARGS)}"
+        )
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        call_args: dict[str, Any] = {"name": name or get_fn_name(func), **kwargs}
+        if enabled is not None:
+            call_args[_MIXIN_ENABLED_KEY] = enabled
+        setattr(func, _MCP_REGISTRATION_PROMPT_ATTR, call_args)
+        return func
+
+    return decorator
+
+
+class MCPMixin:
+    """Base mixin class for objects that can register tools, resources, and prompts
+    with a FastMCP server instance using decorators.
+
+    This mixin provides methods like ``register_all``, ``register_tools``, etc.,
+    which iterate over the methods of the inheriting class, find methods
+    decorated with ``@mcp_tool``, ``@mcp_resource``, or ``@mcp_prompt``, and
+    register them with the provided FastMCP server instance.
+    """
+
+    def _get_methods_to_register(self, registration_type: str):
+        """Retrieves all methods marked for a specific registration type."""
+        return [
+            (
+                getattr(self, method_name),
+                getattr(getattr(self, method_name), registration_type).copy(),
+            )
+            for method_name in dir(self)
+            if callable(getattr(self, method_name))
+            and hasattr(getattr(self, method_name), registration_type)
+        ]
+
+    def register_tools(
+        self,
+        mcp_server: "FastMCP",
+        prefix: str | None = None,
+        separator: str = _DEFAULT_SEPARATOR_TOOL,
+    ) -> None:
+        """Registers all methods marked with @mcp_tool with the FastMCP server.
+
+        Args:
+            mcp_server: The FastMCP server instance to register tools with.
+            prefix: Optional prefix to prepend to tool names.  If provided, the
+                final name will be ``f"{prefix}{separator}{original_name}"``.
+            separator: The separator string used between prefix and original name.
+                Defaults to ``'_'``.
+        """
+        for method, registration_info in self._get_methods_to_register(
+            _MCP_REGISTRATION_TOOL_ATTR
+        ):
+            if prefix:
+                registration_info["name"] = (
+                    f"{prefix}{separator}{registration_info['name']}"
+                )
+
+            enabled = registration_info.pop(_MIXIN_ENABLED_KEY, True)
+            if enabled is False:
+                continue
+
+            tool = Tool.from_function(fn=method, **registration_info)
+            mcp_server.add_tool(tool)
+
+    def register_resources(
+        self,
+        mcp_server: "FastMCP",
+        prefix: str | None = None,
+        separator: str = _DEFAULT_SEPARATOR_RESOURCE,
+    ) -> None:
+        """Registers all methods marked with @mcp_resource with the FastMCP server.
+
+        Args:
+            mcp_server: The FastMCP server instance to register resources with.
+            prefix: Optional prefix to prepend to resource names and URIs.  If
+                provided, the final name will be
+                ``f"{prefix}{separator}{original_name}"`` and the final URI will
+                be ``f"{prefix}{separator}{original_uri}"``.
+            separator: The separator string used between prefix and original
+                name/URI.  Defaults to ``'+'``.
+        """
+        for method, registration_info in self._get_methods_to_register(
+            _MCP_REGISTRATION_RESOURCE_ATTR
+        ):
+            if prefix:
+                registration_info["name"] = (
+                    f"{prefix}{separator}{registration_info['name']}"
+                )
+                registration_info["uri"] = (
+                    f"{prefix}{separator}{registration_info['uri']}"
+                )
+
+            enabled = registration_info.pop(_MIXIN_ENABLED_KEY, True)
+            if enabled is False:
+                continue
+
+            resource = Resource.from_function(fn=method, **registration_info)
+            mcp_server.add_resource(resource)
+
+    def register_prompts(
+        self,
+        mcp_server: "FastMCP",
+        prefix: str | None = None,
+        separator: str = _DEFAULT_SEPARATOR_PROMPT,
+    ) -> None:
+        """Registers all methods marked with @mcp_prompt with the FastMCP server.
+
+        Args:
+            mcp_server: The FastMCP server instance to register prompts with.
+            prefix: Optional prefix to prepend to prompt names.  If provided,
+                the final name will be ``f"{prefix}{separator}{original_name}"``.
+            separator: The separator string used between prefix and original name.
+                Defaults to ``'_'``.
+        """
+        for method, registration_info in self._get_methods_to_register(
+            _MCP_REGISTRATION_PROMPT_ATTR
+        ):
+            if prefix:
+                registration_info["name"] = (
+                    f"{prefix}{separator}{registration_info['name']}"
+                )
+
+            enabled = registration_info.pop(_MIXIN_ENABLED_KEY, True)
+            if enabled is False:
+                continue
+
+            prompt = Prompt.from_function(fn=method, **registration_info)
+            mcp_server.add_prompt(prompt)
+
+    def register_all(
+        self,
+        mcp_server: "FastMCP",
+        prefix: str | None = None,
+        tool_separator: str = _DEFAULT_SEPARATOR_TOOL,
+        resource_separator: str = _DEFAULT_SEPARATOR_RESOURCE,
+        prompt_separator: str = _DEFAULT_SEPARATOR_PROMPT,
+    ) -> None:
+        """Registers all marked tools, resources, and prompts with the server.
+
+        This method calls ``register_tools``, ``register_resources``, and
+        ``register_prompts`` internally, passing the provided prefix and
+        separators.
+
+        Args:
+            mcp_server: The FastMCP server instance to register with.
+            prefix: Optional prefix applied to all registered items.
+            tool_separator: Separator for tool names (defaults to ``'_'``).
+            resource_separator: Separator for resource names/URIs (defaults to ``'+'``).
+            prompt_separator: Separator for prompt names (defaults to ``'_'``).
+        """
+        self.register_tools(mcp_server, prefix=prefix, separator=tool_separator)
+        self.register_resources(mcp_server, prefix=prefix, separator=resource_separator)
+        self.register_prompts(mcp_server, prefix=prefix, separator=prompt_separator)
diff --git a/fastmcp_slim/fastmcp/decorators.py b/fastmcp_slim/fastmcp/decorators.py
new file mode 100644
index 0000000..75dff25
--- /dev/null
+++ b/fastmcp_slim/fastmcp/decorators.py
@@ -0,0 +1,41 @@
+"""Shared decorator utilities for FastMCP."""
+
+from __future__ import annotations
+
+import inspect
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from fastmcp.prompts.function_prompt import PromptMeta
+    from fastmcp.resources.function_resource import ResourceMeta
+    from fastmcp.server.tasks.config import TaskConfig
+    from fastmcp.tools.function_tool import ToolMeta
+
+    FastMCPMeta = ToolMeta | ResourceMeta | PromptMeta
+
+
+def resolve_task_config(task: bool | TaskConfig | None) -> bool | TaskConfig:
+    """Resolve task config, defaulting None to False."""
+    return task if task is not None else False
+
+
+@runtime_checkable
+class HasFastMCPMeta(Protocol):
+    """Protocol for callables decorated with FastMCP metadata."""
+
+    __fastmcp__: Any
+
+
+def get_fastmcp_meta(fn: Any) -> Any | None:
+    """Extract FastMCP metadata from a function, handling bound methods and wrappers."""
+    if hasattr(fn, "__fastmcp__"):
+        return fn.__fastmcp__
+    if hasattr(fn, "__func__") and hasattr(fn.__func__, "__fastmcp__"):
+        return fn.__func__.__fastmcp__
+    try:
+        unwrapped = inspect.unwrap(fn)
+        if unwrapped is not fn and hasattr(unwrapped, "__fastmcp__"):
+            return unwrapped.__fastmcp__
+    except ValueError:
+        pass
+    return None
diff --git a/fastmcp_slim/fastmcp/dependencies.py b/fastmcp_slim/fastmcp/dependencies.py
new file mode 100644
index 0000000..2aa8c14
--- /dev/null
+++ b/fastmcp_slim/fastmcp/dependencies.py
@@ -0,0 +1,40 @@
+"""Dependency injection exports for FastMCP.
+
+This module re-exports dependency injection symbols to provide a clean,
+centralized import location for all dependency-related functionality.
+
+DI features (Depends, CurrentContext, CurrentFastMCP) work without pydocket
+using the uncalled-for DI engine. Only task-related dependencies (CurrentDocket,
+CurrentWorker) and background task execution require fastmcp[tasks].
+"""
+
+from uncalled_for import Dependency, Depends, Shared
+
+from fastmcp.server.dependencies import (
+    CurrentAccessToken,
+    CurrentContext,
+    CurrentDocket,
+    CurrentFastMCP,
+    CurrentHeaders,
+    CurrentRequest,
+    CurrentWorker,
+    Progress,
+    ProgressLike,
+    TokenClaim,
+)
+
+__all__ = [
+    "CurrentAccessToken",
+    "CurrentContext",
+    "CurrentDocket",
+    "CurrentFastMCP",
+    "CurrentHeaders",
+    "CurrentRequest",
+    "CurrentWorker",
+    "Dependency",
+    "Depends",
+    "Progress",
+    "ProgressLike",
+    "Shared",
+    "TokenClaim",
+]
diff --git a/fastmcp_slim/fastmcp/exceptions.py b/fastmcp_slim/fastmcp/exceptions.py
new file mode 100644
index 0000000..fb6571f
--- /dev/null
+++ b/fastmcp_slim/fastmcp/exceptions.py
@@ -0,0 +1,114 @@
+"""Custom exceptions for FastMCP."""
+
+import logging
+from typing import Any
+
+from mcp_types import INTERNAL_ERROR, INVALID_PARAMS, ErrorData
+
+try:
+    from mcp import MCPError
+except ImportError:
+
+    class MCPError(Exception):  # type: ignore[no-redef]
+        """Fallback used when MCP dependencies are not installed.
+
+        Mirrors the real ``mcp.MCPError`` interface — the ``(code, message,
+        data)`` constructor and the ``.error`` ``ErrorData`` payload — so static
+        analysis of both construction and read sites (e.g. ``to_mcp_error`` and
+        callers reading ``err.error.code``) is valid regardless of which branch
+        is in effect.
+        """
+
+        def __init__(self, code: int, message: str, data: Any = None) -> None:
+            super().__init__(message)
+            self.error = ErrorData(code=code, message=message, data=data)
+
+
+# Catch-compatibility alias for the pre-v2 SDK name. `except McpError` must
+# catch SDK-raised `MCPError`, so this is a plain alias (a subclass would not
+# catch the base). Construction differs in v2 (`MCPError(code=, message=)`);
+# see the migration notes.
+McpError = MCPError
+
+
+class FastMCPDeprecationWarning(DeprecationWarning):
+    """Deprecation warning for FastMCP APIs.
+
+    Subclass of DeprecationWarning so that standard warning filters
+    still apply, but FastMCP can selectively enable its own warnings
+    without affecting other libraries in the process.
+    """
+
+
+class FastMCPError(Exception):
+    """Base error for FastMCP."""
+
+    def __init__(self, *args: object, log_level: int = logging.ERROR) -> None:
+        super().__init__(*args)
+        self.log_level = log_level
+
+
+class ValidationError(FastMCPError):
+    """Error in validating parameters or return values."""
+
+
+class ResourceError(FastMCPError):
+    """Error in resource operations."""
+
+
+class ToolError(FastMCPError):
+    """Error in tool operations."""
+
+
+class PromptError(FastMCPError):
+    """Error in prompt operations."""
+
+
+class InvalidSignature(Exception):
+    """Invalid signature for use with FastMCP."""
+
+
+class ClientError(Exception):
+    """Error in client operations."""
+
+
+class NotFoundError(Exception):
+    """Object not found."""
+
+
+class DisabledError(Exception):
+    """Object is disabled."""
+
+
+class AuthorizationError(FastMCPError):
+    """Error when authorization check fails."""
+
+
+def to_mcp_error(exc: Exception, *, default_code: int = INTERNAL_ERROR) -> MCPError:
+    """Translate a FastMCP exception into a wire-format ``MCPError``.
+
+    Central mapping from FastMCP's public exception types to the JSON-RPC error
+    codes defined by the MCP spec (imported from ``mcp_types``). Request-handler
+    adapters call this instead of hand-rolling ``MCPError(code=..., ...)`` per
+    call site, so the wire codes stay spec-correct and consistent across
+    resources, prompts, and tools.
+
+    ``NotFoundError`` and ``DisabledError`` map to ``INVALID_PARAMS`` (-32602):
+    per SEP-2164 a request naming a component that does not exist (or is
+    disabled) is an invalid-params error, which matches the SDK's own
+    ``ResourceNotFoundError -> INVALID_PARAMS`` mapping in ``mcp.server.mcpserver``.
+    ``ValidationError`` is also an invalid-params error. Everything else falls
+    back to ``default_code`` (``INTERNAL_ERROR`` by default).
+
+    If ``exc`` is already an ``MCPError``, it is returned unchanged so an
+    explicit code chosen upstream survives translation.
+    """
+    if isinstance(exc, MCPError):
+        return exc
+
+    message = str(exc)
+    if isinstance(exc, (NotFoundError, DisabledError)):
+        return MCPError(code=INVALID_PARAMS, message=message)
+    if isinstance(exc, ValidationError):
+        return MCPError(code=INVALID_PARAMS, message=message)
+    return MCPError(code=default_code, message=message)
diff --git a/fastmcp_slim/fastmcp/experimental/__init__.py b/fastmcp_slim/fastmcp/experimental/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/fastmcp_slim/fastmcp/experimental/sampling/__init__.py b/fastmcp_slim/fastmcp/experimental/sampling/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/fastmcp_slim/fastmcp/experimental/sampling/handlers/__init__.py b/fastmcp_slim/fastmcp/experimental/sampling/handlers/__init__.py
new file mode 100644
index 0000000..627dfd0
--- /dev/null
+++ b/fastmcp_slim/fastmcp/experimental/sampling/handlers/__init__.py
@@ -0,0 +1,5 @@
+# Re-export for backwards compatibility
+# The canonical location is now fastmcp.client.sampling.handlers
+from fastmcp.client.sampling.handlers.openai import OpenAISamplingHandler
+
+__all__ = ["OpenAISamplingHandler"]
diff --git a/fastmcp_slim/fastmcp/experimental/sampling/handlers/openai.py b/fastmcp_slim/fastmcp/experimental/sampling/handlers/openai.py
new file mode 100644
index 0000000..b466f7a
--- /dev/null
+++ b/fastmcp_slim/fastmcp/experimental/sampling/handlers/openai.py
@@ -0,0 +1,5 @@
+# Re-export for backwards compatibility
+# The canonical location is now fastmcp.client.sampling.handlers.openai
+from fastmcp.client.sampling.handlers.openai import OpenAISamplingHandler
+
+__all__ = ["OpenAISamplingHandler"]
diff --git a/fastmcp_slim/fastmcp/experimental/transforms/__init__.py b/fastmcp_slim/fastmcp/experimental/transforms/__init__.py
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/fastmcp_slim/fastmcp/experimental/transforms/__init__.py
@@ -0,0 +1 @@
+
diff --git a/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py b/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py
new file mode 100644
index 0000000..5978785
--- /dev/null
+++ b/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py
@@ -0,0 +1,647 @@
+import asyncio
+import importlib
+import json
+from collections.abc import Awaitable, Callable, Sequence
+from typing import TYPE_CHECKING, Annotated, Any, Literal, Protocol
+
+if TYPE_CHECKING:
+    from pydantic_monty import ResourceLimits
+
+from mcp_types import TextContent
+from pydantic import Field
+
+from fastmcp.exceptions import NotFoundError, ToolError
+from fastmcp.server.context import Context
+from fastmcp.server.transforms import GetToolNext
+from fastmcp.server.transforms.catalog import CatalogTransform
+from fastmcp.server.transforms.search.base import (
+    serialize_tools_for_output_json,
+    serialize_tools_for_output_markdown,
+)
+from fastmcp.tools.base import Tool, ToolResult
+from fastmcp.utilities.async_utils import is_coroutine_function
+from fastmcp.utilities.versions import VersionSpec
+
+# ---------------------------------------------------------------------------
+# Type aliases
+# ---------------------------------------------------------------------------
+
+GetToolCatalog = Callable[[Context], Awaitable[Sequence[Tool]]]
+"""Async callable that returns the auth-filtered tool catalog."""
+
+SearchFn = Callable[[Sequence[Tool], str], Awaitable[Sequence[Tool]]]
+"""Async callable that searches a tool sequence by query string."""
+
+DiscoveryToolFactory = Callable[[GetToolCatalog], Tool]
+"""Factory that receives catalog access and returns a synthetic Tool."""
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _ensure_async(fn: Callable[..., Any]) -> Callable[..., Any]:
+    if is_coroutine_function(fn):
+        return fn
+
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+        return fn(*args, **kwargs)
+
+    return wrapper
+
+
+def _unwrap_tool_result(result: ToolResult) -> dict[str, Any] | str:
+    """Convert a ToolResult for use in the sandbox.
+
+    - Output schema present → structured_content dict (matches the schema)
+    - Otherwise → concatenated text content as a string
+    """
+    if result.structured_content is not None:
+        return result.structured_content
+
+    parts: list[str] = []
+    for content in result.content:
+        if isinstance(content, TextContent):
+            parts.append(content.text)
+        else:
+            parts.append(str(content))
+    return "\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Sandbox providers
+# ---------------------------------------------------------------------------
+
+
+class SandboxProvider(Protocol):
+    """Interface for executing LLM-generated Python code in a sandbox.
+
+    WARNING: The ``code`` parameter passed to ``run`` contains untrusted,
+    LLM-generated Python.  Implementations MUST execute it in an isolated
+    sandbox — never with plain ``exec()``.  Use ``MontySandboxProvider``
+    (backed by ``pydantic-monty``) for production workloads.
+    """
+
+    async def run(
+        self,
+        code: str,
+        *,
+        inputs: dict[str, Any] | None = None,
+        external_functions: dict[str, Callable[..., Any]] | None = None,
+    ) -> Any: ...
+
+
+class _UnsetType:
+    """Sentinel distinguishing "argument omitted" from an explicit value."""
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+
+_UNSET = _UnsetType()
+
+
+_DEFAULT_LIMITS: "ResourceLimits" = {
+    "max_duration_secs": 30.0,
+    "max_memory": 100_000_000,  # 100 MB
+}
+"""Baseline limits applied when ``MontySandboxProvider`` is constructed
+without an explicit ``limits`` argument. Pass ``limits=None`` to opt out
+entirely, or a dict to override."""
+
+
+class MontySandboxProvider:
+    """Sandbox provider backed by `pydantic-monty`.
+
+    Args:
+        limits: Resource limits for sandbox execution. Supported keys:
+            ``max_duration_secs`` (float), ``max_allocations`` (int),
+            ``max_memory`` (int), ``max_recursion_depth`` (int),
+            ``gc_interval`` (int).  All are optional; omit a key to
+            leave that limit uncapped.
+
+            When the argument is omitted entirely, a conservative baseline
+            is applied (``max_duration_secs=30``, ``max_memory=100 MB``) so
+            the out-of-box configuration is not unbounded. Pass
+            ``limits=None`` to explicitly run without any limits, or a dict
+            to set your own.
+    """
+
+    def __init__(
+        self,
+        *,
+        limits: "ResourceLimits | None | _UnsetType" = _UNSET,
+    ) -> None:
+        # Copy the baseline so each provider owns its dict — `limits` is a
+        # mutable public attribute, and sharing the module-level object would
+        # let one provider's edits leak into every other default provider.
+        self.limits: ResourceLimits | None = (
+            _DEFAULT_LIMITS.copy() if isinstance(limits, _UnsetType) else limits
+        )
+
+    async def run(
+        self,
+        code: str,
+        *,
+        inputs: dict[str, Any] | None = None,
+        external_functions: dict[str, Callable[..., Any]] | None = None,
+    ) -> Any:
+        try:
+            pydantic_monty = importlib.import_module("pydantic_monty")
+        except ModuleNotFoundError as exc:
+            raise ImportError(
+                "CodeMode requires pydantic-monty for the Monty sandbox provider. "
+                "Install it with `fastmcp[code-mode]` or pass a custom SandboxProvider."
+            ) from exc
+
+        inputs = inputs or {}
+        async_functions = {
+            key: _ensure_async(value)
+            for key, value in (external_functions or {}).items()
+        }
+
+        monty = pydantic_monty.Monty(code, inputs=list(inputs))
+        future = asyncio.ensure_future(
+            self._run_monty(
+                monty,
+                inputs=inputs or None,
+                external_functions=async_functions or None,
+            )
+        )
+        try:
+            return await future
+        except asyncio.CancelledError:
+            # Awaiting alone does not stop the native sandbox thread when the
+            # surrounding task is cancelled (e.g. an HTTP client disconnects
+            # mid-execution). Explicitly cancel so the Monty runtime tears the
+            # thread down instead of leaving it running to completion.
+            future.cancel()
+            raise
+
+    def _run_monty(
+        self,
+        monty: Any,
+        *,
+        inputs: dict[str, Any] | None,
+        external_functions: dict[str, Callable[..., Any]] | None,
+    ) -> Any:
+        """Launch the sandbox and return its awaitable.
+
+        Isolated so the cancellation handling in `run()` can be exercised
+        without a live `pydantic-monty` runtime.
+        """
+        return monty.run_async(
+            inputs=inputs,
+            external_functions=external_functions,
+            limits=self.limits,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Built-in discovery tools
+# ---------------------------------------------------------------------------
+
+
+ToolDetailLevel = Literal["brief", "detailed", "full"]
+"""Detail level for discovery tool output.
+
+- ``"brief"``: tool names and one-line descriptions
+- ``"detailed"``: compact markdown with parameter names, types, and required markers
+- ``"full"``: complete JSON schema
+"""
+
+
+def _render_tools(tools: Sequence[Tool], detail: ToolDetailLevel) -> str:
+    """Render tools at the requested detail level.
+
+    The same detail value produces the same output format regardless of
+    which discovery tool calls this, so ``detail="detailed"`` on Search
+    gives identical formatting to ``detail="detailed"`` on GetSchemas.
+    """
+    if not tools:
+        if detail == "full":
+            return json.dumps([], indent=2)
+        return "No tools matched the query."
+    if detail == "full":
+        return json.dumps(serialize_tools_for_output_json(tools), indent=2)
+    if detail == "detailed":
+        return serialize_tools_for_output_markdown(tools)
+    # brief
+    lines: list[str] = []
+    for tool in tools:
+        desc = f": {tool.description}" if tool.description else ""
+        lines.append(f"- {tool.name}{desc}")
+    return "\n".join(lines)
+
+
+class Search:
+    """Discovery tool factory that searches the catalog by query.
+
+    Args:
+        search_fn: Async callable ``(tools, query) -> matching_tools``.
+            Defaults to BM25 ranking.
+        name: Name of the synthetic tool exposed to the LLM.
+        default_detail: Default detail level for search results.
+            ``"brief"`` returns tool names and descriptions only.
+            ``"detailed"`` returns compact markdown with parameter schemas.
+            ``"full"`` returns complete JSON tool definitions.
+        default_limit: Maximum number of results to return.
+            The LLM can override this per call.  ``None`` means no limit.
+    """
+
+    def __init__(
+        self,
+        *,
+        search_fn: SearchFn | None = None,
+        name: str = "search",
+        default_detail: ToolDetailLevel | None = None,
+        default_limit: int | None = None,
+    ) -> None:
+        if search_fn is None:
+            from fastmcp.server.transforms.search.bm25 import BM25SearchTransform
+
+            _bm25 = BM25SearchTransform(max_results=default_limit or 50)
+            search_fn = _bm25._search
+        self._search_fn = search_fn
+        self._name = name
+        self._default_detail: ToolDetailLevel = default_detail or "brief"
+        self._default_limit = default_limit
+
+    def __call__(self, get_catalog: GetToolCatalog) -> Tool:
+        search_fn = self._search_fn
+        default_detail = self._default_detail
+        default_limit = self._default_limit
+
+        async def search(
+            query: Annotated[str, "Search query to find available tools"],
+            tags: Annotated[
+                list[str] | None,
+                "Filter to tools with any of these tags before searching",
+            ] = None,
+            detail: Annotated[
+                ToolDetailLevel,
+                "'brief' for names and descriptions, 'detailed' for parameter schemas as markdown, 'full' for complete JSON schemas",
+            ] = default_detail,
+            limit: Annotated[
+                int | None,
+                "Maximum number of results to return",
+            ] = default_limit,
+            ctx: Context = None,  # type: ignore[assignment]  # ty:ignore[invalid-parameter-default]
+        ) -> str:
+            """Search for available tools by query.
+
+            Returns matching tools ranked by relevance.
+            """
+            catalog = await get_catalog(ctx)
+            catalog_size = len(catalog)
+            tools: Sequence[Tool] = catalog
+            if tags:
+                tag_set = set(tags)
+                has_untagged = "untagged" in tag_set
+                real_tags = tag_set - {"untagged"}
+                tools = [
+                    t
+                    for t in tools
+                    if (t.tags & real_tags) or (has_untagged and not t.tags)
+                ]
+            results = await search_fn(tools, query)
+            if limit is not None:
+                results = results[:limit]
+            rendered = _render_tools(results, detail)
+            if len(results) < catalog_size and detail != "full":
+                n = len(results)
+                rendered = f"{n} of {catalog_size} tools:\n\n{rendered}"
+            return rendered
+
+        return Tool.from_function(fn=search, name=self._name)
+
+
+class GetSchemas:
+    """Discovery tool factory that returns schemas for tools by name.
+
+    Args:
+        name: Name of the synthetic tool exposed to the LLM.
+        default_detail: Default detail level for schema results.
+            ``"brief"`` returns tool names and descriptions only.
+            ``"detailed"`` renders compact markdown with parameter names,
+            types, and required markers.
+            ``"full"`` returns the complete JSON schema.
+    """
+
+    def __init__(
+        self,
+        *,
+        name: str = "get_schema",
+        default_detail: ToolDetailLevel | None = None,
+    ) -> None:
+        self._name = name
+        self._default_detail: ToolDetailLevel = default_detail or "detailed"
+
+    def __call__(self, get_catalog: GetToolCatalog) -> Tool:
+        default_detail = self._default_detail
+
+        async def get_schema(
+            tools: Annotated[
+                list[str],
+                "List of tool names to get schemas for",
+            ],
+            detail: Annotated[
+                ToolDetailLevel,
+                "'brief' for names and descriptions, 'detailed' for parameter schemas as markdown, 'full' for complete JSON schemas",
+            ] = default_detail,
+            ctx: Context = None,  # type: ignore[assignment]  # ty:ignore[invalid-parameter-default]
+        ) -> str:
+            """Get parameter schemas for specific tools.
+
+            Use after searching to get the detail needed to call a tool.
+            """
+            catalog = await get_catalog(ctx)
+            catalog_by_name = {t.name: t for t in catalog}
+            matched = [catalog_by_name[n] for n in tools if n in catalog_by_name]
+            not_found = [n for n in tools if n not in catalog_by_name]
+
+            if not matched and not_found:
+                return f"Tools not found: {', '.join(not_found)}"
+
+            if detail == "full":
+                data = serialize_tools_for_output_json(matched)
+                if not_found:
+                    data.append({"not_found": not_found})
+                return json.dumps(data, indent=2)
+
+            result = _render_tools(matched, detail)
+            if not_found:
+                result += f"\n\nTools not found: {', '.join(not_found)}"
+            return result
+
+        return Tool.from_function(fn=get_schema, name=self._name)
+
+
+class GetTags:
+    """Discovery tool factory that lists tool tags from the catalog.
+
+    Reads ``tool.tags`` from the catalog and groups tools by tag. Tools
+    without tags appear under ``"untagged"``.
+
+    Args:
+        name: Name of the synthetic tool exposed to the LLM.
+        default_detail: Default detail level.
+            ``"brief"`` returns tag names with tool counts.
+            ``"full"`` lists all tools under each tag.
+    """
+
+    def __init__(
+        self,
+        *,
+        name: str = "tags",
+        default_detail: Literal["brief", "full"] | None = None,
+    ) -> None:
+        self._name = name
+        self._default_detail: Literal["brief", "full"] = default_detail or "brief"
+
+    def __call__(self, get_catalog: GetToolCatalog) -> Tool:
+        default_detail = self._default_detail
+
+        async def tags(
+            detail: Annotated[
+                Literal["brief", "full"],
+                "Level of detail: 'brief' for tag names and counts, 'full' for tools listed under each tag",
+            ] = default_detail,
+            ctx: Context = None,  # type: ignore[assignment]  # ty:ignore[invalid-parameter-default]
+        ) -> str:
+            """List available tool tags.
+
+            Use to browse available tools by tag before searching.
+            """
+            catalog = await get_catalog(ctx)
+            by_tag: dict[str, list[Tool]] = {}
+            for tool in catalog:
+                if tool.tags:
+                    for tag in tool.tags:
+                        by_tag.setdefault(tag, []).append(tool)
+                else:
+                    by_tag.setdefault("untagged", []).append(tool)
+
+            if not by_tag:
+                return "No tools available."
+
+            if detail == "brief":
+                lines = [
+                    f"- {tag} ({len(tools)} tool{'s' if len(tools) != 1 else ''})"
+                    for tag, tools in sorted(by_tag.items())
+                ]
+                return "\n".join(lines)
+
+            blocks: list[str] = []
+            for tag, tools in sorted(by_tag.items()):
+                lines = [f"### {tag}"]
+                for tool in tools:
+                    desc = f": {tool.description}" if tool.description else ""
+                    lines.append(f"- {tool.name}{desc}")
+                blocks.append("\n".join(lines))
+            return "\n\n".join(blocks)
+
+        return Tool.from_function(fn=tags, name=self._name)
+
+
+class ListTools:
+    """Discovery tool factory that lists all tools in the catalog.
+
+    Args:
+        name: Name of the synthetic tool exposed to the LLM.
+        default_detail: Default detail level.
+            ``"brief"`` returns tool names and one-line descriptions.
+            ``"detailed"`` returns compact markdown with parameter schemas.
+            ``"full"`` returns the complete JSON schema.
+    """
+
+    def __init__(
+        self,
+        *,
+        name: str = "list_tools",
+        default_detail: ToolDetailLevel | None = None,
+    ) -> None:
+        self._name = name
+        self._default_detail: ToolDetailLevel = default_detail or "brief"
+
+    def __call__(self, get_catalog: GetToolCatalog) -> Tool:
+        default_detail = self._default_detail
+
+        async def list_tools(
+            detail: Annotated[
+                ToolDetailLevel,
+                "'brief' for names and descriptions, 'detailed' for parameter schemas as markdown, 'full' for complete JSON schemas",
+            ] = default_detail,
+            ctx: Context = None,  # type: ignore[assignment]  # ty:ignore[invalid-parameter-default]
+        ) -> str:
+            """List all available tools.
+
+            Use to see the full catalog before searching or calling tools.
+            """
+            catalog = await get_catalog(ctx)
+            return _render_tools(catalog, detail)
+
+        return Tool.from_function(fn=list_tools, name=self._name)
+
+
+# ---------------------------------------------------------------------------
+# CodeMode
+# ---------------------------------------------------------------------------
+
+
+def _default_discovery_tools() -> list[DiscoveryToolFactory]:
+    return [Search(), GetSchemas()]
+
+
+class CodeMode(CatalogTransform):
+    """Transform that collapses all tools into discovery + execute meta-tools.
+
+    Discovery tools are composable via the ``discovery_tools`` parameter.
+    Each is a callable that receives catalog access and returns a ``Tool``.
+    By default, ``Search`` and ``GetSchemas`` are included for
+    progressive disclosure: search finds candidates, get_schema retrieves
+    parameter details, and execute runs code.
+
+    The ``execute`` tool is always present and provides a sandboxed Python
+    environment with ``call_tool(name, params)`` in scope.
+    """
+
+    def __init__(
+        self,
+        *,
+        sandbox_provider: SandboxProvider | None = None,
+        discovery_tools: list[DiscoveryToolFactory] | None = None,
+        execute_tool_name: str = "execute",
+        execute_description: str | None = None,
+        max_tool_calls: int | None = 50,
+    ) -> None:
+        super().__init__()
+        self.execute_tool_name = execute_tool_name
+        self.execute_description = execute_description
+        self.max_tool_calls = max_tool_calls
+        self.sandbox_provider = sandbox_provider or MontySandboxProvider()
+
+        self._discovery_factories = (
+            discovery_tools
+            if discovery_tools is not None
+            else _default_discovery_tools()
+        )
+        self._built_discovery_tools: list[Tool] | None = None
+        self._cached_execute_tool: Tool | None = None
+
+    def _build_discovery_tools(self) -> list[Tool]:
+        if self._built_discovery_tools is None:
+            tools = [
+                factory(self.get_tool_catalog) for factory in self._discovery_factories
+            ]
+            names = {t.name for t in tools}
+            if self.execute_tool_name in names:
+                raise ValueError(
+                    f"Discovery tool name '{self.execute_tool_name}' "
+                    f"collides with execute_tool_name."
+                )
+            if len(names) != len(tools):
+                raise ValueError("Discovery tools must have unique names.")
+            self._built_discovery_tools = tools
+        return self._built_discovery_tools
+
+    async def transform_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        return [*self._build_discovery_tools(), self._get_execute_tool()]
+
+    async def get_tool(
+        self,
+        name: str,
+        call_next: GetToolNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> Tool | None:
+        for tool in self._build_discovery_tools():
+            if tool.name == name:
+                return tool
+        if name == self.execute_tool_name:
+            return self._get_execute_tool()
+        return await call_next(name, version=version)
+
+    def _build_execute_description(self) -> str:
+        if self.execute_description is not None:
+            return self.execute_description
+
+        return (
+            "Chain `await call_tool(...)` calls in one Python block; prefer returning the final answer from a single block.\n"
+            "Use `return` to produce output.\n"
+            "Only `call_tool(tool_name: str, params: dict) -> Any` is available in scope."
+        )
+
+    @staticmethod
+    def _find_tool(name: str, tools: Sequence[Tool]) -> Tool | None:
+        """Find a tool by name from a pre-fetched list."""
+        for tool in tools:
+            if tool.name == name:
+                return tool
+        return None
+
+    def _get_execute_tool(self) -> Tool:
+        if self._cached_execute_tool is None:
+            self._cached_execute_tool = self._make_execute_tool()
+        return self._cached_execute_tool
+
+    def _make_execute_tool(self) -> Tool:
+        transform = self
+        max_tool_calls = self.max_tool_calls
+
+        async def execute(
+            code: Annotated[
+                str,
+                Field(
+                    description=(
+                        "Python async code to execute tool calls via call_tool(name, arguments)"
+                    )
+                ),
+            ],
+            ctx: Context = None,  # type: ignore[assignment]  # ty:ignore[invalid-parameter-default]
+        ) -> Any:
+            """Execute tool calls using Python code."""
+
+            call_count = 0
+
+            async def call_tool(tool_name: str, params: dict[str, Any]) -> Any:
+                nonlocal call_count
+                if max_tool_calls is not None:
+                    call_count += 1
+                    if call_count > max_tool_calls:
+                        raise ToolError(
+                            f"Tool call limit exceeded: at most {max_tool_calls} "
+                            "call_tool() invocations are allowed per execute()."
+                        )
+
+                backend_tools = await transform.get_tool_catalog(ctx)
+                tool = transform._find_tool(tool_name, backend_tools)
+                if tool is None:
+                    raise NotFoundError(f"Unknown tool: {tool_name}")
+
+                result = await ctx.fastmcp.call_tool(tool.name, params)
+                return _unwrap_tool_result(result)
+
+            return await transform.sandbox_provider.run(
+                code,
+                external_functions={"call_tool": call_tool},
+            )
+
+        return Tool.from_function(
+            fn=execute,
+            name=self.execute_tool_name,
+            description=self._build_execute_description(),
+        )
+
+
+__all__ = [
+    "CodeMode",
+    "GetSchemas",
+    "GetTags",
+    "GetToolCatalog",
+    "ListTools",
+    "MontySandboxProvider",
+    "SandboxProvider",
+    "Search",
+]
diff --git a/fastmcp_slim/fastmcp/mcp_config.py b/fastmcp_slim/fastmcp/mcp_config.py
new file mode 100644
index 0000000..286e34c
--- /dev/null
+++ b/fastmcp_slim/fastmcp/mcp_config.py
@@ -0,0 +1,388 @@
+"""Canonical MCP Configuration Format.
+
+This module defines the standard configuration format for Model Context Protocol (MCP) servers.
+It provides a client-agnostic, extensible format that can be used across all MCP implementations.
+
+The configuration format supports both stdio and remote (HTTP/SSE) transports, with comprehensive
+field definitions for server metadata, authentication, and execution parameters.
+
+Example configuration:
+```json
+{
+    "mcpServers": {
+        "my-server": {
+            "command": "npx",
+            "args": ["-y", "@my/mcp-server"],
+            "env": {"API_KEY": "secret"},
+            "timeout": 30000,
+            "description": "My MCP server"
+        }
+    }
+}
+```
+"""
+
+from __future__ import annotations
+
+import datetime
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated, Any, Literal, cast
+from urllib.parse import urlparse
+
+import httpx
+from pydantic import (
+    AnyUrl,
+    BaseModel,
+    ConfigDict,
+    Field,
+    model_validator,
+)
+from typing_extensions import Self, override
+
+from fastmcp import _install_hints
+
+if TYPE_CHECKING:
+    from fastmcp.client.transports import (
+        ClientTransport,
+        SSETransport,
+        StdioTransport,
+        StreamableHttpTransport,
+    )
+
+
+def infer_transport_type_from_url(
+    url: str | AnyUrl,
+) -> Literal["http", "sse"]:
+    """
+    Infer the appropriate transport type from the given URL.
+    """
+    url = str(url)
+    if not url.startswith("http"):
+        raise ValueError(f"Invalid URL: {url}")
+
+    parsed_url = urlparse(url)
+    path = parsed_url.path
+
+    # Match /sse followed by /, ?, &, or end of string
+    if re.search(r"/sse(/|\?|&|$)", path):
+        return "sse"
+    else:
+        return "http"
+
+
+def _coerce_tool_transform_configs(tools: dict[str, Any]) -> dict[str, Any]:
+    from fastmcp.tools.tool_transform import ToolTransformConfig
+
+    return {
+        name: config
+        if isinstance(config, ToolTransformConfig)
+        else ToolTransformConfig.model_validate(config)
+        for name, config in tools.items()
+    }
+
+
+class _TransformingMCPServerMixin(BaseModel):
+    """A mixin that enables wrapping an MCP Server with tool transforms."""
+
+    tools: dict[str, Any] = Field(default_factory=dict)
+    """The multi-tool transform to apply to the tools."""
+
+    include_tags: set[str] | None = Field(
+        default=None,
+        description="The tags to include in the proxy.",
+    )
+
+    exclude_tags: set[str] | None = Field(
+        default=None,
+        description="The tags to exclude in the proxy.",
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def _require_at_least_one_transform_field(
+        cls, values: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Reject if none of the transforming fields are set.
+
+        This ensures that plain server configs (without tools, include_tags,
+        or exclude_tags) fall through to the base server types during union
+        validation, avoiding unnecessary proxy wrapping.
+        """
+        if isinstance(values, dict):
+            has_tools = bool(values.get("tools"))
+            has_include = values.get("include_tags") is not None
+            has_exclude = values.get("exclude_tags") is not None
+            if not (has_tools or has_include or has_exclude):
+                raise ValueError(
+                    "At least one of 'tools', 'include_tags', or 'exclude_tags' is required"
+                )
+        return values
+
+    def _to_server_and_underlying_transport(
+        self,
+        server_name: str | None = None,
+        client_name: str | None = None,
+    ) -> tuple[Any, ClientTransport]:
+        """Turn the transforming server into a FastMCP proxy and return its transport."""
+        try:
+            from fastmcp import Client
+            from fastmcp.server import create_proxy
+            from fastmcp.server.transforms import ToolTransform
+        except ImportError as exc:
+            raise ImportError(
+                _install_hints.full_package(
+                    "MCP configs that use FastMCP-specific tool transforms or tag filters"
+                )
+            ) from exc
+
+        transport = cast("ClientTransport", super().to_transport())  # ty: ignore[unresolved-attribute]
+        client = Client(transport=transport, name=client_name)
+        wrapped_mcp_server = create_proxy(client, name=server_name)
+
+        if self.include_tags is not None:
+            wrapped_mcp_server.enable(tags=self.include_tags, only=True)
+        if self.exclude_tags is not None:
+            wrapped_mcp_server.disable(tags=self.exclude_tags)
+        if self.tools:
+            wrapped_mcp_server.add_transform(
+                ToolTransform(_coerce_tool_transform_configs(self.tools))
+            )
+
+        return wrapped_mcp_server, transport
+
+    def to_transport(self) -> ClientTransport:
+        """Get the transport for the transforming MCP server."""
+        try:
+            from fastmcp.client.transports import FastMCPTransport
+        except ImportError as exc:
+            raise ImportError(
+                _install_hints.full_package(
+                    "MCP configs that use FastMCP-specific tool transforms or tag filters"
+                )
+            ) from exc
+
+        return FastMCPTransport(mcp=self._to_server_and_underlying_transport()[0])
+
+
+class StdioMCPServer(BaseModel):
+    """MCP server configuration for stdio transport.
+
+    This is the canonical configuration format for MCP servers using stdio transport.
+    """
+
+    # Required fields
+    command: str
+
+    # Common optional fields
+    args: list[str] = Field(default_factory=list)
+    env: dict[str, Any] = Field(default_factory=dict)
+
+    # Transport specification
+    transport: Literal["stdio"] = "stdio"
+    type: Literal["stdio"] | None = None  # Alternative transport field name
+
+    # Execution context
+    cwd: str | None = None  # Working directory for command execution
+    timeout: int | None = None  # Maximum response time in milliseconds
+    keep_alive: bool | None = (
+        None  # Whether to keep the subprocess alive between connections
+    )
+
+    # Metadata
+    description: str | None = None  # Human-readable server description
+    icon: str | None = None  # Icon path or URL for UI display
+
+    # Authentication configuration
+    authentication: dict[str, Any] | None = None  # Auth configuration object
+
+    model_config = ConfigDict(extra="allow")  # Preserve unknown fields
+
+    def to_transport(self) -> StdioTransport:
+        from fastmcp.client.transports import StdioTransport
+
+        return StdioTransport(
+            command=self.command,
+            args=self.args,
+            env=self.env,
+            cwd=self.cwd,
+            keep_alive=self.keep_alive,
+        )
+
+
+class TransformingStdioMCPServer(_TransformingMCPServerMixin, StdioMCPServer):
+    """A Stdio server with tool transforms."""
+
+
+class RemoteMCPServer(BaseModel):
+    """MCP server configuration for HTTP/SSE transport.
+
+    This is the canonical configuration format for MCP servers using remote transports.
+    """
+
+    # Required fields
+    url: str
+
+    # Transport configuration
+    transport: Literal["http", "streamable-http", "sse"] | None = None
+    headers: dict[str, str] = Field(default_factory=dict)
+
+    # Authentication
+    auth: Annotated[
+        str | Literal["oauth"] | httpx.Auth | None,
+        Field(
+            description='Either a string representing a Bearer token, the literal "oauth" to use OAuth authentication, or an httpx.Auth instance for custom authentication.',
+        ),
+    ] = None
+
+    # Timeout configuration
+    sse_read_timeout: datetime.timedelta | int | float | None = None
+    timeout: int | None = None  # Maximum response time in milliseconds
+
+    # Metadata
+    description: str | None = None  # Human-readable server description
+    icon: str | None = None  # Icon path or URL for UI display
+
+    # Authentication configuration
+    authentication: dict[str, Any] | None = None  # Auth configuration object
+
+    model_config = ConfigDict(
+        extra="allow", arbitrary_types_allowed=True
+    )  # Preserve unknown fields
+
+    def to_transport(self) -> StreamableHttpTransport | SSETransport:
+        from fastmcp.client.transports import (
+            SSETransport,
+            StreamableHttpTransport,
+        )
+
+        if self.transport is None:
+            transport = infer_transport_type_from_url(self.url)
+        else:
+            transport = self.transport
+
+        if transport == "sse":
+            return SSETransport(
+                self.url,
+                headers=self.headers,
+                auth=self.auth,
+                sse_read_timeout=self.sse_read_timeout,
+            )
+        else:
+            # Both "http" and "streamable-http" map to StreamableHttpTransport
+            return StreamableHttpTransport(
+                self.url,
+                headers=self.headers,
+                auth=self.auth,
+            )
+
+
+class TransformingRemoteMCPServer(_TransformingMCPServerMixin, RemoteMCPServer):
+    """A Remote server with tool transforms."""
+
+
+TransformingMCPServerTypes = TransformingStdioMCPServer | TransformingRemoteMCPServer
+
+CanonicalMCPServerTypes = StdioMCPServer | RemoteMCPServer
+
+MCPServerTypes = TransformingMCPServerTypes | CanonicalMCPServerTypes
+
+
+class MCPConfig(BaseModel):
+    """A configuration object for MCP Servers that conforms to the canonical MCP configuration format
+    while adding additional fields for enabling FastMCP-specific features like tool transformations
+    and filtering by tags.
+
+    For an MCPConfig that is strictly canonical, see the `CanonicalMCPConfig` class.
+    """
+
+    mcpServers: dict[str, MCPServerTypes] = Field(default_factory=dict)
+
+    model_config = ConfigDict(extra="allow")  # Preserve unknown top-level fields
+
+    @model_validator(mode="before")
+    @classmethod
+    def wrap_servers_at_root(cls, values: dict[str, Any]) -> dict[str, Any]:
+        """If there's no mcpServers key but there are server configs at root, wrap them."""
+        if "mcpServers" not in values:
+            # Check if any values look like server configs
+            has_servers = any(
+                isinstance(v, dict) and ("command" in v or "url" in v)
+                for v in values.values()
+            )
+            if has_servers:
+                # Move all server-like configs under mcpServers
+                return {"mcpServers": values}
+        return values
+
+    def add_server(self, name: str, server: MCPServerTypes) -> None:
+        """Add or update a server in the configuration."""
+        self.mcpServers[name] = server
+
+    @classmethod
+    def from_dict(cls, config: dict[str, Any]) -> Self:
+        """Parse MCP configuration from dictionary format."""
+        return cls.model_validate(config)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert MCPConfig to dictionary format, preserving all fields."""
+        return self.model_dump(exclude_none=True)
+
+    def write_to_file(self, file_path: Path) -> None:
+        """Write configuration to JSON file."""
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_text(self.model_dump_json(indent=2), encoding="utf-8")
+
+    @classmethod
+    def from_file(cls, file_path: Path) -> Self:
+        """Load configuration from JSON file."""
+        if file_path.exists() and (
+            content := file_path.read_text(encoding="utf-8").strip()
+        ):
+            return cls.model_validate_json(content)
+
+        raise ValueError(f"No MCP servers defined in the config: {file_path}")
+
+
+class CanonicalMCPConfig(MCPConfig):
+    """Canonical MCP configuration format.
+
+    This defines the standard configuration format for Model Context Protocol servers.
+    The format is designed to be client-agnostic and extensible for future use cases.
+    """
+
+    mcpServers: dict[str, CanonicalMCPServerTypes] = Field(default_factory=dict)
+
+    @override
+    def add_server(self, name: str, server: CanonicalMCPServerTypes) -> None:
+        """Add or update a server in the configuration."""
+        self.mcpServers[name] = server
+
+
+def update_config_file(
+    file_path: Path,
+    server_name: str,
+    server_config: CanonicalMCPServerTypes,
+) -> None:
+    """Update an MCP configuration file from a server object, preserving existing fields.
+
+    This is used for updating the mcpServer configurations of third-party tools so we do not
+    worry about transforming server objects here."""
+    config = MCPConfig.from_file(file_path)
+
+    # If updating an existing server, merge with existing configuration
+    # to preserve any unknown fields
+    if existing_server := config.mcpServers.get(server_name):
+        # Get the raw dict representation of both servers
+        existing_dict = existing_server.model_dump()
+
+        new_dict = server_config.model_dump(exclude_none=True)
+
+        # Merge, with new values taking precedence
+        merged_config = server_config.model_validate({**existing_dict, **new_dict})
+
+        config.add_server(server_name, merged_config)
+    else:
+        config.add_server(server_name, server_config)
+
+    config.write_to_file(file_path)
diff --git a/fastmcp_slim/fastmcp/prompts/__init__.py b/fastmcp_slim/fastmcp/prompts/__init__.py
new file mode 100644
index 0000000..d1b8660
--- /dev/null
+++ b/fastmcp_slim/fastmcp/prompts/__init__.py
@@ -0,0 +1,20 @@
+import sys
+
+from .function_prompt import FunctionPrompt, prompt
+from .base import Message, Prompt, PromptArgument, PromptMessage, PromptResult
+
+# Backward compat: prompt.py was renamed to base.py to stop Pyright from resolving
+# `from fastmcp.prompts import prompt` as the submodule instead of the decorator function.
+# This shim keeps `from fastmcp.prompts.prompt import Prompt` working at runtime.
+# Safe to remove once we're confident no external code imports from the old path.
+sys.modules[f"{__name__}.prompt"] = sys.modules[f"{__name__}.base"]
+
+__all__ = [
+    "FunctionPrompt",
+    "Message",
+    "Prompt",
+    "PromptArgument",
+    "PromptMessage",
+    "PromptResult",
+    "prompt",
+]
diff --git a/fastmcp_slim/fastmcp/prompts/base.py b/fastmcp_slim/fastmcp/prompts/base.py
new file mode 100644
index 0000000..f56243e
--- /dev/null
+++ b/fastmcp_slim/fastmcp/prompts/base.py
@@ -0,0 +1,414 @@
+"""Base classes for FastMCP prompts."""
+
+from __future__ import annotations as _annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, ClassVar, Literal, overload
+
+import pydantic
+import pydantic_core
+
+if TYPE_CHECKING:
+    from docket import Docket
+    from docket.execution import Execution
+
+    from fastmcp.prompts.function_prompt import FunctionPrompt
+import mcp_types
+from mcp import GetPromptResult
+from mcp_types import (
+    AudioContent,
+    EmbeddedResource,
+    Icon,
+    ImageContent,
+    PromptMessage,
+    TextContent,
+)
+from mcp_types import Prompt as SDKPrompt
+from mcp_types import PromptArgument as SDKPromptArgument
+from pydantic import Field
+from pydantic.json_schema import SkipJsonSchema
+
+from fastmcp.utilities.authorization import AuthCheck
+from fastmcp.utilities.components import FastMCPComponent
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.tasks import TaskConfig, TaskMeta
+from fastmcp.utilities.types import (
+    FastMCPBaseModel,
+)
+
+logger = get_logger(__name__)
+
+
+class Message(pydantic.BaseModel):
+    """Wrapper for prompt message with auto-serialization.
+
+    Accepts any content - strings pass through, other types
+    (dict, list, BaseModel) are JSON-serialized to text.
+
+    Example:
+        ```python
+        from fastmcp.prompts import Message
+
+        # String content (user role by default)
+        Message("Hello, world!")
+
+        # Explicit role
+        Message("I can help with that.", role="assistant")
+
+        # Auto-serialized to JSON
+        Message({"key": "value"})
+        Message(["item1", "item2"])
+        ```
+    """
+
+    role: Literal["user", "assistant"]
+    content: TextContent | ImageContent | AudioContent | EmbeddedResource
+
+    def __init__(
+        self,
+        content: Any,
+        role: Literal["user", "assistant"] = "user",
+    ):
+        """Create Message with automatic serialization.
+
+        Args:
+            content: The message content. str passes through directly.
+                     TextContent, ImageContent, AudioContent, and
+                     EmbeddedResource pass through.
+                     Other types (dict, list, BaseModel) are JSON-serialized.
+            role: The message role, either "user" or "assistant".
+        """
+        # Handle already-wrapped content types
+        if isinstance(
+            content, (TextContent, ImageContent, AudioContent, EmbeddedResource)
+        ):
+            normalized_content: (
+                TextContent | ImageContent | AudioContent | EmbeddedResource
+            ) = content
+        elif isinstance(content, str):
+            normalized_content = TextContent(type="text", text=content)
+        else:
+            # dict, list, BaseModel → JSON string
+            serialized = pydantic_core.to_json(content, fallback=str).decode()
+            normalized_content = TextContent(type="text", text=serialized)
+
+        super().__init__(role=role, content=normalized_content)
+
+    def to_mcp_prompt_message(self) -> PromptMessage:
+        """Convert to MCP PromptMessage."""
+        return PromptMessage(role=self.role, content=self.content)
+
+
+class PromptArgument(FastMCPBaseModel):
+    """An argument that can be passed to a prompt."""
+
+    name: str = Field(description="Name of the argument")
+    description: str | None = Field(
+        default=None, description="Description of what the argument does"
+    )
+    required: bool = Field(
+        default=False, description="Whether the argument is required"
+    )
+
+
+class PromptResult(pydantic.BaseModel):
+    """Canonical result type for prompt rendering.
+
+    Provides explicit control over prompt responses: multiple messages,
+    roles, and metadata at both the message and result level.
+
+    Accepts:
+        - str: Wrapped as single Message (user role)
+        - list[Message]: Used directly for multiple messages or custom roles
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.prompts import PromptResult, Message
+
+        mcp = FastMCP()
+
+        # Simple string content
+        @mcp.prompt
+        def greet() -> PromptResult:
+            return PromptResult("Hello!")
+
+        # Multiple messages with roles
+        @mcp.prompt
+        def conversation() -> PromptResult:
+            return PromptResult([
+                Message("What's the weather?"),
+                Message("It's sunny today.", role="assistant"),
+            ])
+        ```
+    """
+
+    messages: list[Message]
+    description: str | None = None
+    meta: dict[str, Any] | None = None
+
+    def __init__(
+        self,
+        messages: str | list[Message],
+        description: str | None = None,
+        meta: dict[str, Any] | None = None,
+    ):
+        """Create PromptResult.
+
+        Args:
+            messages: String or list of Message objects.
+            description: Optional description of the prompt result.
+            meta: Optional metadata about the prompt result.
+        """
+        normalized = self._normalize_messages(messages)
+        super().__init__(messages=normalized, description=description, meta=meta)
+
+    @staticmethod
+    def _normalize_messages(
+        messages: str | list[Message],
+    ) -> list[Message]:
+        """Normalize input to list[Message]."""
+        if isinstance(messages, str):
+            return [Message(messages)]
+        if isinstance(messages, list):
+            # Validate all items are Message
+            for i, item in enumerate(messages):
+                if not isinstance(item, Message):
+                    raise TypeError(
+                        f"messages[{i}] must be Message, got {type(item).__name__}. "
+                        f"Use Message({item!r}) to wrap the value."
+                    )
+            return messages
+        raise TypeError(
+            f"messages must be str or list[Message], got {type(messages).__name__}"
+        )
+
+    def to_mcp_prompt_result(self) -> GetPromptResult:
+        """Convert to MCP GetPromptResult."""
+        mcp_messages = [m.to_mcp_prompt_message() for m in self.messages]
+        return GetPromptResult(
+            description=self.description,
+            messages=mcp_messages,
+            _meta=self.meta,  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
+        )
+
+
+class Prompt(FastMCPComponent):
+    """A prompt template that can be rendered with parameters."""
+
+    KEY_PREFIX: ClassVar[str] = "prompt"
+
+    arguments: list[PromptArgument] | None = Field(
+        default=None, description="Arguments that can be passed to the prompt"
+    )
+    auth: SkipJsonSchema[AuthCheck | list[AuthCheck] | None] = Field(
+        default=None, description="Authorization checks for this prompt", exclude=True
+    )
+
+    def to_mcp_prompt(
+        self,
+        **overrides: Any,
+    ) -> SDKPrompt:
+        """Convert the prompt to an MCP prompt."""
+        arguments = [
+            SDKPromptArgument(
+                name=arg.name,
+                description=arg.description,
+                required=arg.required,
+            )
+            for arg in self.arguments or []
+        ]
+
+        return SDKPrompt(
+            name=overrides.get("name", self.name),
+            description=overrides.get("description", self.description),
+            arguments=arguments,
+            title=overrides.get("title", self.title),
+            icons=overrides.get("icons", self.icons),
+            _meta=overrides.get(  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
+                "_meta", self.get_meta()
+            ),
+        )
+
+    @classmethod
+    def from_function(
+        cls,
+        fn: Callable[..., Any],
+        *,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[Icon] | None = None,
+        tags: set[str] | None = None,
+        meta: dict[str, Any] | None = None,
+        task: bool | TaskConfig | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+    ) -> FunctionPrompt:
+        """Create a Prompt from a function.
+
+        The function can return:
+        - str: wrapped as single user Message
+        - list[Message | str]: converted to list[Message]
+        - PromptResult: used directly
+        """
+        from fastmcp.prompts.function_prompt import FunctionPrompt
+
+        return FunctionPrompt.from_function(
+            fn=fn,
+            name=name,
+            version=version,
+            title=title,
+            description=description,
+            icons=icons,
+            tags=tags,
+            meta=meta,
+            task=task,
+            auth=auth,
+        )
+
+    async def render(
+        self,
+        arguments: dict[str, Any] | None = None,
+    ) -> str | list[Message | str] | PromptResult:
+        """Render the prompt with arguments.
+
+        Subclasses must implement this method. Return one of:
+        - str: Wrapped as single user Message
+        - list[Message | str]: Converted to list[Message]
+        - PromptResult: Used directly
+        """
+        raise NotImplementedError("Subclasses must implement render()")
+
+    def convert_result(self, raw_value: Any) -> PromptResult:
+        """Convert a raw return value to PromptResult.
+
+        Accepts:
+            - PromptResult: passed through
+            - str: wrapped as single Message
+            - list[Message | str]: converted to list[Message]
+
+        Raises:
+            TypeError: for unsupported types
+        """
+        if isinstance(raw_value, PromptResult):
+            return raw_value
+
+        if isinstance(raw_value, str):
+            return PromptResult(raw_value, description=self.description, meta=self.meta)
+
+        if isinstance(raw_value, list | tuple):
+            messages: list[Message] = []
+            for i, item in enumerate(raw_value):
+                if isinstance(item, Message):
+                    messages.append(item)
+                elif isinstance(item, str):
+                    messages.append(Message(item))
+                else:
+                    raise TypeError(
+                        f"messages[{i}] must be Message or str, got {type(item).__name__}. "
+                        f"Use Message({item!r}) to wrap the value."
+                    )
+            return PromptResult(messages, description=self.description, meta=self.meta)
+
+        raise TypeError(
+            f"Prompt must return str, list[Message], or PromptResult, "
+            f"got {type(raw_value).__name__}"
+        )
+
+    @overload
+    async def _render(
+        self,
+        arguments: dict[str, Any] | None = None,
+        task_meta: None = None,
+    ) -> PromptResult: ...
+
+    @overload
+    async def _render(
+        self,
+        arguments: dict[str, Any] | None,
+        task_meta: TaskMeta,
+    ) -> mcp_types.CreateTaskResult: ...
+
+    async def _render(
+        self,
+        arguments: dict[str, Any] | None = None,
+        task_meta: TaskMeta | None = None,
+    ) -> PromptResult | mcp_types.CreateTaskResult:
+        """Server entry point that handles task routing.
+
+        This allows ANY Prompt subclass to support background execution by setting
+        task_config.mode to "supported" or "required". The server calls this
+        method instead of render() directly.
+
+        Args:
+            arguments: Prompt arguments
+            task_meta: If provided, execute as background task and return
+                CreateTaskResult. If None (default), execute synchronously and
+                return PromptResult.
+
+        Returns:
+            PromptResult when task_meta is None.
+            CreateTaskResult when task_meta is provided.
+
+        Subclasses can override this to customize task routing behavior.
+        For example, FastMCPProviderPrompt overrides to delegate to child
+        middleware without submitting to Docket.
+        """
+        from fastmcp.server.tasks.routing import check_background_task
+
+        task_result = await check_background_task(
+            component=self,
+            task_type="prompt",
+            arguments=arguments,
+            task_meta=task_meta,
+        )
+        if task_result:
+            return task_result
+
+        # Synchronous execution
+        result = await self.render(arguments)
+        return self.convert_result(result)
+
+    def register_with_docket(self, docket: Docket) -> None:
+        """Register this prompt with docket for background execution."""
+        if not self.task_config.supports_tasks():
+            return
+        docket.register(self.render, names=[self.key])
+
+    async def add_to_docket(  # type: ignore[override]
+        self,
+        docket: Docket,
+        arguments: dict[str, Any] | None,
+        *,
+        fn_key: str | None = None,
+        task_key: str | None = None,
+        **kwargs: Any,
+    ) -> Execution:
+        """Schedule this prompt for background execution via docket.
+
+        Args:
+            docket: The Docket instance
+            arguments: Prompt arguments
+            fn_key: Function lookup key in Docket registry (defaults to self.key)
+            task_key: Redis storage key for the result
+            **kwargs: Additional kwargs passed to docket.add()
+        """
+        lookup_key = fn_key or self.key
+        if task_key:
+            kwargs["key"] = task_key
+        return await docket.add(lookup_key, **kwargs)(arguments)
+
+    def get_span_attributes(self) -> dict[str, Any]:
+        return super().get_span_attributes() | {
+            "fastmcp.component.type": "prompt",
+            "fastmcp.provider.type": "LocalProvider",
+        }
+
+
+__all__ = [
+    "Message",
+    "Prompt",
+    "PromptArgument",
+    "PromptResult",
+]
diff --git a/fastmcp_slim/fastmcp/prompts/function_prompt.py b/fastmcp_slim/fastmcp/prompts/function_prompt.py
new file mode 100644
index 0000000..959bebd
--- /dev/null
+++ b/fastmcp_slim/fastmcp/prompts/function_prompt.py
@@ -0,0 +1,490 @@
+"""Standalone @prompt decorator for FastMCP."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import json
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from types import MethodType
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    Protocol,
+    TypeVar,
+    cast,
+    overload,
+    runtime_checkable,
+)
+
+import pydantic_core
+from mcp_types import Icon
+from pydantic.json_schema import SkipJsonSchema
+
+from fastmcp.exceptions import FastMCPError, PromptError
+from fastmcp.prompts.base import Prompt, PromptArgument, PromptResult
+from fastmcp.utilities.async_utils import (
+    call_sync_fn_in_threadpool,
+    is_coroutine_function,
+)
+from fastmcp.utilities.authorization import AuthCheck
+from fastmcp.utilities.docstring_parsing import ParsedDocstring, parse_docstring
+from fastmcp.utilities.json_schema import compress_schema
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.tasks import TaskConfig
+from fastmcp.utilities.types import get_cached_typeadapter
+
+if TYPE_CHECKING:
+    from docket import Docket
+    from docket.execution import Execution
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+logger = get_logger(__name__)
+
+
+@runtime_checkable
+class DecoratedPrompt(Protocol):
+    """Protocol for functions decorated with @prompt."""
+
+    __fastmcp__: PromptMeta
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any: ...
+
+
+@dataclass(frozen=True, kw_only=True)
+class PromptMeta:
+    """Metadata attached to functions by the @prompt decorator."""
+
+    type: Literal["prompt"] = field(default="prompt", init=False)
+    name: str | None = None
+    version: str | int | None = None
+    title: str | None = None
+    description: str | None = None
+    icons: list[Icon] | None = None
+    tags: set[str] | None = None
+    meta: dict[str, Any] | None = None
+    task: bool | TaskConfig | None = None
+    auth: AuthCheck | list[AuthCheck] | None = None
+    enabled: bool = True
+
+
+class FunctionPrompt(Prompt):
+    """A prompt that is a function."""
+
+    fn: SkipJsonSchema[Callable[..., Any]]
+
+    @classmethod
+    def from_function(
+        cls,
+        fn: Callable[..., Any],
+        *,
+        metadata: PromptMeta | None = None,
+        # Keep individual params for backwards compat
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[Icon] | None = None,
+        tags: set[str] | None = None,
+        meta: dict[str, Any] | None = None,
+        task: bool | TaskConfig | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+    ) -> FunctionPrompt:
+        """Create a Prompt from a function.
+
+        Args:
+            fn: The function to wrap
+            metadata: PromptMeta object with all configuration. If provided,
+                individual parameters must not be passed.
+            name, title, etc.: Individual parameters for backwards compatibility.
+                Cannot be used together with metadata parameter.
+
+        The function can return:
+        - str: wrapped as single user Message
+        - list[Message | str]: converted to list[Message]
+        - PromptResult: used directly
+        """
+        # Check mutual exclusion
+        individual_params_provided = any(
+            x is not None
+            for x in [name, version, title, description, icons, tags, meta, task, auth]
+        )
+
+        if metadata is not None and individual_params_provided:
+            raise TypeError(
+                "Cannot pass both 'metadata' and individual parameters to from_function(). "
+                "Use metadata alone or individual parameters alone."
+            )
+
+        # Build metadata from kwargs if not provided
+        if metadata is None:
+            metadata = PromptMeta(
+                name=name,
+                version=version,
+                title=title,
+                description=description,
+                icons=icons,
+                tags=tags,
+                meta=meta,
+                task=task,
+                auth=auth,
+            )
+
+        func_name = (
+            metadata.name or getattr(fn, "__name__", None) or fn.__class__.__name__
+        )
+
+        if func_name == "<lambda>":
+            raise ValueError("You must provide a name for lambda functions")
+
+        # Reject functions with *args or **kwargs
+        sig = inspect.signature(fn)
+        for param in sig.parameters.values():
+            if param.kind == inspect.Parameter.VAR_POSITIONAL:
+                raise ValueError("Functions with *args are not supported as prompts")
+            if param.kind == inspect.Parameter.VAR_KEYWORD:
+                raise ValueError("Functions with **kwargs are not supported as prompts")
+
+        # Parse the outer docstring (before unwrapping) to preserve the class
+        # docstring as the prompt description for callable class instances.
+        outer_docstring = parse_docstring(fn)
+
+        # Normalize task to TaskConfig and validate
+        task_value = metadata.task
+        if task_value is None:
+            task_config = TaskConfig(mode="forbidden")
+        elif isinstance(task_value, bool):
+            task_config = TaskConfig.from_bool(task_value)
+        else:
+            task_config = task_value
+        task_config.validate_function(fn, func_name)
+
+        # if the fn is a callable class, we need to get the __call__ method from here out
+        if not inspect.isroutine(fn) and not isinstance(fn, functools.partial):
+            fn = fn.__call__
+        # if the fn is a staticmethod, we need to work with the underlying function
+        if isinstance(fn, staticmethod):
+            fn = fn.__func__
+
+        # For callable classes, argument descriptions must come from
+        # __call__'s docstring — where the exposed parameters are actually
+        # declared. The class docstring's Args section, if any, typically
+        # describes __init__, so falling back to it would risk injecting
+        # constructor docs into __call__'s arguments on overlapping names.
+        # The description, however, comes from the class docstring (which
+        # describes what the prompt IS) when present.
+        inner_docstring = parse_docstring(fn)
+        parsed_docstring = ParsedDocstring(
+            description=outer_docstring.description or inner_docstring.description,
+            parameters=inner_docstring.parameters,
+        )
+        description = (
+            metadata.description
+            if metadata.description is not None
+            else parsed_docstring.description
+        )
+
+        # Transform Context type annotations to Depends() for unified DI
+        from fastmcp.server.dependencies import (
+            transform_context_annotations,
+            without_injected_parameters,
+        )
+
+        fn = transform_context_annotations(fn)
+
+        # Wrap fn to handle dependency resolution internally
+        wrapped_fn = without_injected_parameters(fn)
+        type_adapter = get_cached_typeadapter(wrapped_fn)
+        parameters = type_adapter.json_schema()
+        parameters = compress_schema(parameters, prune_titles=True)
+
+        # Inject parameter descriptions from the docstring into the schema.
+        # Explicit annotations (Field(description=...), Annotated[x, "..."])
+        # already have a "description" key and take precedence.
+        if parsed_docstring.parameters:
+            properties = parameters.get("properties", {})
+            for param_name, param_desc in parsed_docstring.parameters.items():
+                if (
+                    param_name in properties
+                    and "description" not in properties[param_name]
+                ):
+                    properties[param_name]["description"] = param_desc
+
+        # Convert parameters to PromptArguments
+        arguments: list[PromptArgument] = []
+        if "properties" in parameters:
+            for param_name, param in parameters["properties"].items():
+                arg_description = param.get("description")
+
+                # For non-string parameters, append JSON schema info to help users
+                # understand the expected format when passing as strings (MCP requirement)
+                if param_name in sig.parameters:
+                    sig_param = sig.parameters[param_name]
+                    if (
+                        sig_param.annotation != inspect.Parameter.empty
+                        and sig_param.annotation is not str
+                    ):
+                        # Get the JSON schema for this specific parameter type
+                        try:
+                            param_adapter = get_cached_typeadapter(sig_param.annotation)
+                            param_schema = param_adapter.json_schema()
+
+                            # Create compact schema representation
+                            schema_str = json.dumps(param_schema, separators=(",", ":"))
+
+                            # Append schema info to description
+                            schema_note = f"Provide as a JSON string matching the following schema: {schema_str}"
+                            if arg_description:
+                                arg_description = f"{arg_description}\n\n{schema_note}"
+                            else:
+                                arg_description = schema_note
+                        except Exception as e:
+                            # If schema generation fails, skip enhancement
+                            logger.debug(
+                                "Failed to generate schema for prompt argument %s: %s",
+                                param_name,
+                                e,
+                            )
+
+                arguments.append(
+                    PromptArgument(
+                        name=param_name,
+                        description=arg_description,
+                        required=param_name in parameters.get("required", []),
+                    )
+                )
+
+        return cls(
+            name=func_name,
+            version=str(metadata.version) if metadata.version is not None else None,
+            title=metadata.title,
+            description=description,
+            icons=metadata.icons,
+            arguments=arguments,
+            tags=metadata.tags or set(),
+            fn=wrapped_fn,
+            meta=metadata.meta,
+            task_config=task_config,
+            auth=metadata.auth,
+        )
+
+    def _convert_string_arguments(self, kwargs: dict[str, Any]) -> dict[str, Any]:
+        """Convert string arguments to expected types based on function signature."""
+        from fastmcp.server.dependencies import without_injected_parameters
+
+        wrapper_fn = without_injected_parameters(self.fn)
+        sig = inspect.signature(wrapper_fn)
+        converted_kwargs = {}
+
+        for param_name, param_value in kwargs.items():
+            if param_name in sig.parameters:
+                param = sig.parameters[param_name]
+
+                # If parameter has no annotation or annotation is str, pass as-is
+                if (
+                    param.annotation == inspect.Parameter.empty
+                    or param.annotation is str
+                ) or not isinstance(param_value, str):
+                    converted_kwargs[param_name] = param_value
+                else:
+                    # Try to convert string argument using type adapter
+                    try:
+                        adapter = get_cached_typeadapter(param.annotation)
+                        # Try JSON parsing first for complex types
+                        try:
+                            converted_kwargs[param_name] = adapter.validate_json(
+                                param_value
+                            )
+                        except (ValueError, TypeError, pydantic_core.ValidationError):
+                            # Fallback to direct validation
+                            converted_kwargs[param_name] = adapter.validate_python(
+                                param_value
+                            )
+                    except (ValueError, TypeError, pydantic_core.ValidationError) as e:
+                        # If conversion fails, provide informative error
+                        raise PromptError(
+                            f"Could not convert argument '{param_name}' with value '{param_value}' "
+                            f"to expected type {param.annotation}. Error: {e}"
+                        ) from e
+            else:
+                # Parameter not in function signature, pass as-is
+                converted_kwargs[param_name] = param_value
+
+        return converted_kwargs
+
+    async def render(
+        self,
+        arguments: dict[str, Any] | None = None,
+    ) -> PromptResult:
+        """Render the prompt with arguments."""
+        # Validate required arguments
+        if self.arguments:
+            required = {arg.name for arg in self.arguments if arg.required}
+            provided = set(arguments or {})
+            missing = required - provided
+            if missing:
+                raise ValueError(f"Missing required arguments: {missing}")
+
+        try:
+            # Prepare arguments
+            kwargs = arguments.copy() if arguments else {}
+
+            # Convert string arguments to expected types BEFORE validation
+            kwargs = self._convert_string_arguments(kwargs)
+
+            # Filter out arguments that aren't in the function signature
+            # This is important for security: dependencies should not be overridable
+            # from external callers. self.fn is wrapped by without_injected_parameters,
+            # so we only accept arguments that are in the wrapped function's signature.
+            sig = inspect.signature(self.fn)
+            valid_params = set(sig.parameters.keys())
+            kwargs = {k: v for k, v in kwargs.items() if k in valid_params}
+
+            # Use type adapter to validate arguments and handle Field() defaults
+            # This matches the behavior of tools in function_tool
+            type_adapter = get_cached_typeadapter(self.fn)
+
+            # self.fn is wrapped by without_injected_parameters which handles
+            # dependency resolution internally
+            if is_coroutine_function(self.fn):
+                result = await type_adapter.validate_python(kwargs)
+            else:
+                # Run sync functions in threadpool to avoid blocking the event loop
+                result = await call_sync_fn_in_threadpool(
+                    type_adapter.validate_python, kwargs
+                )
+                # Handle sync wrappers that return awaitables (e.g., partial(async_fn))
+                if inspect.isawaitable(result):
+                    result = await result
+
+            return self.convert_result(result)
+        except FastMCPError:
+            raise
+        except Exception as e:
+            logger.exception(f"Error rendering prompt {self.name}")
+            raise PromptError(f"Error rendering prompt {self.name!r}: {e}") from e
+
+    def register_with_docket(self, docket: Docket) -> None:
+        """Register this prompt with docket for background execution."""
+        if not self.task_config.supports_tasks():
+            return
+        docket.register(self.fn, names=[self.key])
+
+    async def add_to_docket(
+        self,
+        docket: Docket,
+        arguments: dict[str, Any] | None,
+        *,
+        fn_key: str | None = None,
+        task_key: str | None = None,
+        **kwargs: Any,
+    ) -> Execution:
+        """Schedule this prompt for background execution via docket.
+
+        FunctionPrompt splats the arguments dict since .fn expects **kwargs.
+
+        Args:
+            docket: The Docket instance
+            arguments: Prompt arguments
+            fn_key: Function lookup key in Docket registry (defaults to self.key)
+            task_key: Redis storage key for the result
+            **kwargs: Additional kwargs passed to docket.add()
+        """
+        lookup_key = fn_key or self.key
+        if task_key:
+            kwargs["key"] = task_key
+        return await docket.add(lookup_key, **kwargs)(**(arguments or {}))
+
+
+@overload
+def prompt(fn: F) -> F: ...
+@overload
+def prompt(
+    name_or_fn: str,
+    *,
+    version: str | int | None = None,
+    title: str | None = None,
+    description: str | None = None,
+    icons: list[Icon] | None = None,
+    tags: set[str] | None = None,
+    meta: dict[str, Any] | None = None,
+    task: bool | TaskConfig | None = None,
+    auth: AuthCheck | list[AuthCheck] | None = None,
+) -> Callable[[F], F]: ...
+@overload
+def prompt(
+    name_or_fn: None = None,
+    *,
+    name: str | None = None,
+    version: str | int | None = None,
+    title: str | None = None,
+    description: str | None = None,
+    icons: list[Icon] | None = None,
+    tags: set[str] | None = None,
+    meta: dict[str, Any] | None = None,
+    task: bool | TaskConfig | None = None,
+    auth: AuthCheck | list[AuthCheck] | None = None,
+) -> Callable[[F], F]: ...
+
+
+def prompt(
+    name_or_fn: str | Callable[..., Any] | None = None,
+    *,
+    name: str | None = None,
+    version: str | int | None = None,
+    title: str | None = None,
+    description: str | None = None,
+    icons: list[Icon] | None = None,
+    tags: set[str] | None = None,
+    meta: dict[str, Any] | None = None,
+    task: bool | TaskConfig | None = None,
+    auth: AuthCheck | list[AuthCheck] | None = None,
+) -> Any:
+    """Standalone decorator to mark a function as an MCP prompt.
+
+    Returns the original function with metadata attached. Register with a server
+    using mcp.add_prompt().
+    """
+    if isinstance(name_or_fn, classmethod):
+        raise TypeError(
+            "To decorate a classmethod, use @classmethod above @prompt. "
+            "See https://gofastmcp.com/servers/prompts#using-with-methods"
+        )
+
+    def attach_metadata(fn: F, prompt_name: str | None) -> F:
+        metadata = PromptMeta(
+            name=prompt_name,
+            version=version,
+            title=title,
+            description=description,
+            icons=icons,
+            tags=tags,
+            meta=meta,
+            task=task,
+            auth=auth,
+        )
+        target = fn.__func__ if isinstance(fn, staticmethod | MethodType) else fn
+        cast(Any, target).__fastmcp__ = metadata
+        return fn
+
+    def decorator(fn: F, prompt_name: str | None) -> F:
+        return attach_metadata(fn, prompt_name)
+
+    if inspect.isroutine(name_or_fn):
+        return decorator(name_or_fn, name)
+    elif isinstance(name_or_fn, str):
+        if name is not None:
+            raise TypeError("Cannot specify name both as first argument and keyword")
+        prompt_name = name_or_fn
+    elif name_or_fn is None:
+        prompt_name = name
+    else:
+        raise TypeError(f"Invalid first argument: {type(name_or_fn)}")
+
+    def wrapper(fn: F) -> F:
+        return decorator(fn, prompt_name)
+
+    return wrapper
diff --git a/fastmcp_slim/fastmcp/py.typed b/fastmcp_slim/fastmcp/py.typed
new file mode 100644
index 0000000..e69de29
diff --git a/fastmcp_slim/fastmcp/resources/__init__.py b/fastmcp_slim/fastmcp/resources/__init__.py
new file mode 100644
index 0000000..cbcfff7
--- /dev/null
+++ b/fastmcp_slim/fastmcp/resources/__init__.py
@@ -0,0 +1,32 @@
+import sys
+
+from .function_resource import FunctionResource, resource
+from .base import Resource, ResourceContent, ResourceResult
+from .template import ResourceTemplate
+from .types import (
+    BinaryResource,
+    DirectoryResource,
+    FileResource,
+    HttpResource,
+    TextResource,
+)
+
+__all__ = [
+    "BinaryResource",
+    "DirectoryResource",
+    "FileResource",
+    "FunctionResource",
+    "HttpResource",
+    "Resource",
+    "ResourceContent",
+    "ResourceResult",
+    "ResourceTemplate",
+    "TextResource",
+    "resource",
+]
+
+# Backward compat: resource.py was renamed to base.py to stop Pyright from resolving
+# `from fastmcp.resources import resource` as the submodule instead of the decorator function.
+# This shim keeps `from fastmcp.resources.resource import Resource` working at runtime.
+# Safe to remove once we're confident no external code imports from the old path.
+sys.modules[f"{__name__}.resource"] = sys.modules[f"{__name__}.base"]
diff --git a/fastmcp_slim/fastmcp/resources/base.py b/fastmcp_slim/fastmcp/resources/base.py
new file mode 100644
index 0000000..b4e4d0d
--- /dev/null
+++ b/fastmcp_slim/fastmcp/resources/base.py
@@ -0,0 +1,470 @@
+"""Base classes and interfaces for FastMCP resources."""
+
+from __future__ import annotations
+
+import base64
+import json
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Annotated, Any, ClassVar, overload
+
+import mcp_types
+
+if TYPE_CHECKING:
+    from docket import Docket
+    from docket.execution import Execution
+
+    from fastmcp.resources.function_resource import FunctionResource
+
+import pydantic
+import pydantic_core
+from mcp_types import Annotations, Icon
+from mcp_types import Resource as SDKResource
+from pydantic import (
+    AnyUrl,
+    ConfigDict,
+    Field,
+    UrlConstraints,
+    field_validator,
+    model_validator,
+)
+from pydantic.json_schema import SkipJsonSchema
+from typing_extensions import Self
+
+from fastmcp.utilities.authorization import AuthCheck
+from fastmcp.utilities.components import FastMCPComponent
+from fastmcp.utilities.tasks import TaskConfig, TaskMeta
+
+
+class ResourceContent(pydantic.BaseModel):
+    """Wrapper for resource content with optional MIME type and metadata.
+
+    Accepts any value for content - strings and bytes pass through directly,
+    other types (dict, list, BaseModel, etc.) are automatically JSON-serialized.
+
+    Example:
+        ```python
+        from fastmcp.resources import ResourceContent
+
+        # String content
+        ResourceContent("plain text")
+
+        # Binary content
+        ResourceContent(b"binary data", mime_type="application/octet-stream")
+
+        # Auto-serialized to JSON
+        ResourceContent({"key": "value"})
+        ResourceContent(["a", "b", "c"])
+        ```
+    """
+
+    content: str | bytes
+    mime_type: str | None = None
+    meta: dict[str, Any] | None = None
+
+    def __init__(
+        self,
+        content: Any,
+        mime_type: str | None = None,
+        meta: dict[str, Any] | None = None,
+    ):
+        """Create ResourceContent with automatic serialization.
+
+        Args:
+            content: The content value. str and bytes pass through directly.
+                     Other types (dict, list, BaseModel) are JSON-serialized.
+            mime_type: Optional MIME type. Defaults based on content type:
+                       str → "text/plain", bytes → "application/octet-stream",
+                       other → "application/json"
+            meta: Optional metadata dictionary.
+        """
+        if isinstance(content, str):
+            normalized_content: str | bytes = content
+            mime_type = mime_type or "text/plain"
+        elif isinstance(content, bytes):
+            normalized_content = content
+            mime_type = mime_type or "application/octet-stream"
+        else:
+            # dict, list, BaseModel, etc → JSON
+            normalized_content = pydantic_core.to_json(content, fallback=str).decode()
+            mime_type = mime_type or "application/json"
+
+        super().__init__(content=normalized_content, mime_type=mime_type, meta=meta)
+
+    def to_mcp_resource_contents(
+        self, uri: AnyUrl | str
+    ) -> mcp_types.TextResourceContents | mcp_types.BlobResourceContents:
+        """Convert to MCP resource contents type.
+
+        Args:
+            uri: The URI of the resource (required by MCP types)
+
+        Returns:
+            TextResourceContents for str content, BlobResourceContents for bytes
+        """
+        if isinstance(self.content, str):
+            return mcp_types.TextResourceContents(
+                uri=str(uri),
+                text=self.content,
+                mime_type=self.mime_type or "text/plain",
+                _meta=self.meta,  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
+            )
+        else:
+            return mcp_types.BlobResourceContents(
+                uri=str(uri),
+                blob=base64.b64encode(self.content).decode(),
+                mime_type=self.mime_type or "application/octet-stream",
+                _meta=self.meta,  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
+            )
+
+
+class ResourceResult(pydantic.BaseModel):
+    """Canonical result type for resource reads.
+
+    Provides explicit control over resource responses: multiple content items,
+    per-item MIME types, and metadata at both the item and result level.
+
+    Accepts:
+        - str: Wrapped as single ResourceContent (text/plain)
+        - bytes: Wrapped as single ResourceContent (application/octet-stream)
+        - list[ResourceContent]: Used directly for multiple items or custom MIME types
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.resources import ResourceResult, ResourceContent
+
+        mcp = FastMCP()
+
+        # Simple string content
+        @mcp.resource("data://simple")
+        def get_simple() -> ResourceResult:
+            return ResourceResult("hello world")
+
+        # Multiple items with custom MIME types
+        @mcp.resource("data://items")
+        def get_items() -> ResourceResult:
+            return ResourceResult(
+                contents=[
+                    ResourceContent({"key": "value"}),  # auto-serialized to JSON
+                    ResourceContent(b"binary data"),
+                ],
+                meta={"count": 2}
+            )
+        ```
+    """
+
+    contents: list[ResourceContent]
+    meta: dict[str, Any] | None = None
+
+    def __init__(
+        self,
+        contents: str | bytes | list[ResourceContent],
+        meta: dict[str, Any] | None = None,
+    ):
+        """Create ResourceResult.
+
+        Args:
+            contents: String, bytes, or list of ResourceContent objects.
+            meta: Optional metadata about the resource result.
+        """
+        normalized = self._normalize_contents(contents)
+        super().__init__(contents=normalized, meta=meta)
+
+    @staticmethod
+    def _normalize_contents(
+        contents: str | bytes | list[ResourceContent],
+    ) -> list[ResourceContent]:
+        """Normalize input to list[ResourceContent]."""
+        if isinstance(contents, str):
+            return [ResourceContent(contents)]
+        if isinstance(contents, bytes):
+            return [ResourceContent(contents)]
+        if isinstance(contents, list):
+            # Validate all items are ResourceContent
+            for i, item in enumerate(contents):
+                if not isinstance(item, ResourceContent):
+                    raise TypeError(
+                        f"contents[{i}] must be ResourceContent, got {type(item).__name__}. "
+                        f"Use ResourceContent({item!r}) to wrap the value."
+                    )
+            return contents
+        # Auto-serialize JSON-native types to JSON text
+        if (
+            isinstance(contents, dict | list | tuple | int | float | bool)
+            or contents is None
+        ):
+            return [ResourceContent(json.dumps(contents), mime_type="application/json")]
+        raise TypeError(
+            f"contents must be str, bytes, or list[ResourceContent], got {type(contents).__name__}"
+        )
+
+    def to_mcp_result(self, uri: AnyUrl | str) -> mcp_types.ReadResourceResult:
+        """Convert to MCP ReadResourceResult.
+
+        Args:
+            uri: The URI of the resource (required by MCP types)
+
+        Returns:
+            MCP ReadResourceResult with converted contents
+        """
+        mcp_contents = [item.to_mcp_resource_contents(uri) for item in self.contents]
+        return mcp_types.ReadResourceResult(
+            contents=mcp_contents,
+            _meta=self.meta,  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
+        )
+
+
+class Resource(FastMCPComponent):
+    """Base class for all resources."""
+
+    KEY_PREFIX: ClassVar[str] = "resource"
+
+    model_config = ConfigDict(validate_default=True)
+
+    uri: Annotated[AnyUrl, UrlConstraints(host_required=False)] = Field(
+        default=..., description="URI of the resource"
+    )
+    name: str = Field(default="", description="Name of the resource")
+    mime_type: str = Field(
+        default="text/plain",
+        description="MIME type of the resource content",
+    )
+    annotations: Annotated[
+        Annotations | None,
+        Field(description="Optional annotations about the resource's behavior"),
+    ] = None
+    auth: Annotated[
+        SkipJsonSchema[AuthCheck | list[AuthCheck] | None],
+        Field(description="Authorization checks for this resource", exclude=True),
+    ] = None
+
+    @classmethod
+    def from_function(
+        cls,
+        fn: Callable[..., Any],
+        uri: str | AnyUrl,
+        *,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[Icon] | None = None,
+        mime_type: str | None = None,
+        tags: set[str] | None = None,
+        annotations: Annotations | None = None,
+        meta: dict[str, Any] | None = None,
+        task: bool | TaskConfig | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+    ) -> FunctionResource:
+        from fastmcp.resources.function_resource import (
+            FunctionResource,
+        )
+
+        return FunctionResource.from_function(
+            fn=fn,
+            uri=uri,
+            name=name,
+            version=version,
+            title=title,
+            description=description,
+            icons=icons,
+            mime_type=mime_type,
+            tags=tags,
+            annotations=annotations,
+            meta=meta,
+            task=task,
+            auth=auth,
+        )
+
+    @field_validator("mime_type", mode="before")
+    @classmethod
+    def set_default_mime_type(cls, mime_type: str | None) -> str:
+        """Set default MIME type if not provided."""
+        if mime_type:
+            return mime_type
+        return "text/plain"
+
+    @model_validator(mode="after")
+    def set_default_name(self) -> Self:
+        """Set default name from URI if not provided."""
+        if self.name:
+            pass
+        elif self.uri:
+            self.name = str(self.uri)
+        else:
+            raise ValueError("Either name or uri must be provided")
+        return self
+
+    async def read(
+        self,
+    ) -> str | bytes | ResourceResult:
+        """Read the resource content.
+
+        Subclasses implement this to return resource data. Supported return types:
+            - str: Text content
+            - bytes: Binary content
+            - ResourceResult: Full control over contents and result-level meta
+        """
+        raise NotImplementedError("Subclasses must implement read()")
+
+    def convert_result(self, raw_value: Any) -> ResourceResult:
+        """Convert a raw result to ResourceResult.
+
+        This is used in two contexts:
+        1. In _read() to convert user function return values to ResourceResult
+        2. In tasks_result_handler() to convert Docket task results to ResourceResult
+
+        Handles ResourceResult passthrough and converts raw values using
+        ResourceResult's normalization.  When the raw value is a plain
+        string or bytes, the resource's own ``mime_type`` is forwarded so
+        that ``ui://`` resources (and others with non-default MIME types)
+        don't fall back to ``text/plain``.
+
+        The resource's component-level ``meta`` (e.g. ``ui`` metadata for
+        MCP Apps CSP/permissions) is propagated to each content item so
+        that hosts can read it from the ``resources/read`` response.
+        """
+        if isinstance(raw_value, ResourceResult):
+            return raw_value
+
+        # For plain str/bytes returns, wrap in ResourceContent with the
+        # resource's MIME type and component meta so the wire response
+        # carries the correct type and metadata (e.g. CSP for MCP Apps).
+        if isinstance(raw_value, (str, bytes)):
+            return ResourceResult(
+                [ResourceContent(raw_value, mime_type=self.mime_type, meta=self.meta)]
+            )
+
+        # For JSON-native types (dict, list, tuple, int, float, bool, None),
+        # serialize and wrap in ResourceContent with the component's meta,
+        # matching the str/bytes path above so CSP/permissions propagate.
+        # Exclude list[ResourceContent] which should go through ResourceResult
+        # normalization below.
+        if (
+            isinstance(raw_value, dict | list | tuple | int | float | bool)
+            or raw_value is None
+        ) and not (
+            isinstance(raw_value, list)
+            and raw_value
+            and isinstance(raw_value[0], ResourceContent)
+        ):
+            return ResourceResult(
+                [
+                    ResourceContent(
+                        json.dumps(raw_value),
+                        mime_type=self.mime_type or "application/json",
+                        meta=self.meta,
+                    )
+                ]
+            )
+
+        # All other types fall through to ResourceResult for error handling
+        return ResourceResult(raw_value)
+
+    @overload
+    async def _read(self, task_meta: None = None) -> ResourceResult: ...
+
+    @overload
+    async def _read(self, task_meta: TaskMeta) -> mcp_types.CreateTaskResult: ...
+
+    async def _read(
+        self, task_meta: TaskMeta | None = None
+    ) -> ResourceResult | mcp_types.CreateTaskResult:
+        """Server entry point that handles task routing.
+
+        This allows ANY Resource subclass to support background execution by setting
+        task_config.mode to "supported" or "required". The server calls this
+        method instead of read() directly.
+
+        Args:
+            task_meta: If provided, execute as a background task and return
+                CreateTaskResult. If None (default), execute synchronously and
+                return ResourceResult.
+
+        Returns:
+            ResourceResult when task_meta is None.
+            CreateTaskResult when task_meta is provided.
+
+        Subclasses can override this to customize task routing behavior.
+        For example, FastMCPProviderResource overrides to delegate to child
+        middleware without submitting to Docket.
+        """
+        from fastmcp.server.tasks.routing import check_background_task
+
+        task_result = await check_background_task(
+            component=self, task_type="resource", arguments=None, task_meta=task_meta
+        )
+        if task_result:
+            return task_result
+
+        # Synchronous execution - convert result to ResourceResult
+        result = await self.read()
+        return self.convert_result(result)
+
+    def to_mcp_resource(
+        self,
+        **overrides: Any,
+    ) -> SDKResource:
+        """Convert the resource to an SDKResource."""
+
+        return SDKResource(
+            name=overrides.get("name", self.name),
+            uri=str(overrides.get("uri", self.uri)),
+            description=overrides.get("description", self.description),
+            mime_type=overrides.get("mimeType", self.mime_type),
+            title=overrides.get("title", self.title),
+            icons=overrides.get("icons", self.icons),
+            annotations=overrides.get("annotations", self.annotations),
+            _meta=overrides.get(  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
+                "_meta", self.get_meta()
+            ),
+        )
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(uri={self.uri!r}, name={self.name!r}, description={self.description!r}, tags={self.tags})"
+
+    @property
+    def key(self) -> str:
+        """The globally unique lookup key for this resource."""
+        base_key = self.make_key(str(self.uri))
+        return f"{base_key}@{self.version or ''}"
+
+    def register_with_docket(self, docket: Docket) -> None:
+        """Register this resource with docket for background execution."""
+        if not self.task_config.supports_tasks():
+            return
+        docket.register(self.read, names=[self.key])
+
+    async def add_to_docket(  # type: ignore[override]
+        self,
+        docket: Docket,
+        *,
+        fn_key: str | None = None,
+        task_key: str | None = None,
+        **kwargs: Any,
+    ) -> Execution:
+        """Schedule this resource for background execution via docket.
+
+        Args:
+            docket: The Docket instance
+            fn_key: Function lookup key in Docket registry (defaults to self.key)
+            task_key: Redis storage key for the result
+            **kwargs: Additional kwargs passed to docket.add()
+        """
+        lookup_key = fn_key or self.key
+        if task_key:
+            kwargs["key"] = task_key
+        return await docket.add(lookup_key, **kwargs)()
+
+    def get_span_attributes(self) -> dict[str, Any]:
+        return super().get_span_attributes() | {
+            "fastmcp.component.type": "resource",
+            "fastmcp.provider.type": "LocalProvider",
+        }
+
+
+__all__ = [
+    "Resource",
+    "ResourceContent",
+    "ResourceResult",
+]
diff --git a/fastmcp_slim/fastmcp/resources/function_resource.py b/fastmcp_slim/fastmcp/resources/function_resource.py
new file mode 100644
index 0000000..71817f8
--- /dev/null
+++ b/fastmcp_slim/fastmcp/resources/function_resource.py
@@ -0,0 +1,295 @@
+"""Standalone @resource decorator for FastMCP."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from types import MethodType
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    Protocol,
+    TypeVar,
+    cast,
+    runtime_checkable,
+)
+
+from mcp_types import Annotations, Icon
+from pydantic import AnyUrl
+from pydantic.json_schema import SkipJsonSchema
+
+from fastmcp.resources.base import Resource, ResourceResult
+from fastmcp.utilities.async_utils import (
+    call_sync_fn_in_threadpool,
+    is_coroutine_function,
+)
+from fastmcp.utilities.authorization import AuthCheck
+from fastmcp.utilities.mime import resolve_ui_mime_type
+from fastmcp.utilities.tasks import TaskConfig
+
+if TYPE_CHECKING:
+    from docket import Docket
+
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@runtime_checkable
+class DecoratedResource(Protocol):
+    """Protocol for functions decorated with @resource."""
+
+    __fastmcp__: ResourceMeta
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any: ...
+
+
+@dataclass(frozen=True, kw_only=True)
+class ResourceMeta:
+    """Metadata attached to functions by the @resource decorator."""
+
+    type: Literal["resource"] = field(default="resource", init=False)
+    uri: str
+    name: str | None = None
+    version: str | int | None = None
+    title: str | None = None
+    description: str | None = None
+    icons: list[Icon] | None = None
+    tags: set[str] | None = None
+    mime_type: str | None = None
+    annotations: Annotations | None = None
+    meta: dict[str, Any] | None = None
+    task: bool | TaskConfig | None = None
+    auth: AuthCheck | list[AuthCheck] | None = None
+    enabled: bool = True
+
+
+class FunctionResource(Resource):
+    """A resource that defers data loading by wrapping a function.
+
+    The function is only called when the resource is read, allowing for lazy loading
+    of potentially expensive data. This is particularly useful when listing resources,
+    as the function won't be called until the resource is actually accessed.
+
+    The function can return:
+    - str for text content (default)
+    - bytes for binary content
+    - other types will be converted to JSON
+    """
+
+    fn: SkipJsonSchema[Callable[..., Any]]
+
+    @classmethod
+    def from_function(
+        cls,
+        fn: Callable[..., Any],
+        uri: str | AnyUrl | None = None,
+        *,
+        metadata: ResourceMeta | None = None,
+        # Keep individual params for backwards compat
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[Icon] | None = None,
+        mime_type: str | None = None,
+        tags: set[str] | None = None,
+        annotations: Annotations | None = None,
+        meta: dict[str, Any] | None = None,
+        task: bool | TaskConfig | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+    ) -> FunctionResource:
+        """Create a FunctionResource from a function.
+
+        Args:
+            fn: The function to wrap
+            uri: The URI for the resource (required if metadata not provided)
+            metadata: ResourceMeta object with all configuration. If provided,
+                individual parameters must not be passed.
+            name, title, etc.: Individual parameters for backwards compatibility.
+                Cannot be used together with metadata parameter.
+        """
+        # Check mutual exclusion
+        individual_params_provided = (
+            any(
+                x is not None
+                for x in [
+                    name,
+                    version,
+                    title,
+                    description,
+                    icons,
+                    mime_type,
+                    tags,
+                    annotations,
+                    meta,
+                    task,
+                    auth,
+                ]
+            )
+            or uri is not None
+        )
+
+        if metadata is not None and individual_params_provided:
+            raise TypeError(
+                "Cannot pass both 'metadata' and individual parameters to from_function(). "
+                "Use metadata alone or individual parameters alone."
+            )
+
+        # Build metadata from kwargs if not provided
+        if metadata is None:
+            if uri is None:
+                raise TypeError("uri is required when metadata is not provided")
+            metadata = ResourceMeta(
+                uri=str(uri),
+                name=name,
+                version=version,
+                title=title,
+                description=description,
+                icons=icons,
+                tags=tags,
+                mime_type=mime_type,
+                annotations=annotations,
+                meta=meta,
+                task=task,
+                auth=auth,
+            )
+
+        uri_obj = AnyUrl(metadata.uri)
+
+        # Get function name - use class name for callable objects
+        func_name = (
+            metadata.name or getattr(fn, "__name__", None) or fn.__class__.__name__
+        )
+
+        # Normalize task to TaskConfig and validate
+        task_value = metadata.task
+        if task_value is None:
+            task_config = TaskConfig(mode="forbidden")
+        elif isinstance(task_value, bool):
+            task_config = TaskConfig.from_bool(task_value)
+        else:
+            task_config = task_value
+        task_config.validate_function(fn, func_name)
+
+        # if the fn is a callable class, we need to get the __call__ method from here out
+        if not inspect.isroutine(fn) and not isinstance(fn, functools.partial):
+            fn = fn.__call__
+        # if the fn is a staticmethod, we need to work with the underlying function
+        if isinstance(fn, staticmethod):
+            fn = fn.__func__
+
+        # Transform Context type annotations to Depends() for unified DI
+        from fastmcp.server.dependencies import (
+            transform_context_annotations,
+            without_injected_parameters,
+        )
+
+        fn = transform_context_annotations(fn)
+
+        # Wrap fn to handle dependency resolution internally
+        wrapped_fn = without_injected_parameters(fn)
+
+        # Apply ui:// MIME default, then fall back to text/plain
+        resolved_mime = resolve_ui_mime_type(metadata.uri, metadata.mime_type)
+
+        return cls(
+            fn=wrapped_fn,
+            uri=uri_obj,
+            name=func_name,
+            version=str(metadata.version) if metadata.version is not None else None,
+            title=metadata.title,
+            description=metadata.description
+            if metadata.description is not None
+            else inspect.getdoc(fn),
+            icons=metadata.icons,
+            mime_type=resolved_mime or "text/plain",
+            tags=metadata.tags or set(),
+            annotations=metadata.annotations,
+            meta=metadata.meta,
+            task_config=task_config,
+            auth=metadata.auth,
+        )
+
+    async def read(
+        self,
+    ) -> str | bytes | ResourceResult:
+        """Read the resource by calling the wrapped function."""
+        # self.fn is wrapped by without_injected_parameters which handles
+        # dependency resolution internally
+        if is_coroutine_function(self.fn):
+            result = await self.fn()
+        else:
+            # Run sync functions in threadpool to avoid blocking the event loop
+            result = await call_sync_fn_in_threadpool(self.fn)
+            # Handle sync wrappers that return awaitables (e.g., partial(async_fn))
+            if inspect.isawaitable(result):
+                result = await result
+
+        # If user returned another Resource, read it recursively
+        if isinstance(result, Resource):
+            return await result.read()
+
+        return result
+
+    def register_with_docket(self, docket: Docket) -> None:
+        """Register this resource with docket for background execution."""
+        if not self.task_config.supports_tasks():
+            return
+        docket.register(self.fn, names=[self.key])
+
+
+def resource(
+    uri: str,
+    *,
+    name: str | None = None,
+    version: str | int | None = None,
+    title: str | None = None,
+    description: str | None = None,
+    icons: list[Icon] | None = None,
+    mime_type: str | None = None,
+    tags: set[str] | None = None,
+    annotations: Annotations | dict[str, Any] | None = None,
+    meta: dict[str, Any] | None = None,
+    task: bool | TaskConfig | None = None,
+    auth: AuthCheck | list[AuthCheck] | None = None,
+) -> Callable[[F], F]:
+    """Standalone decorator to mark a function as an MCP resource.
+
+    Returns the original function with metadata attached. Register with a server
+    using mcp.add_resource().
+    """
+    if isinstance(annotations, dict):
+        annotations = Annotations(**annotations)
+
+    if inspect.isroutine(uri):
+        raise TypeError(
+            "The @resource decorator requires a URI. "
+            "Use @resource('uri') instead of @resource"
+        )
+
+    def attach_metadata(fn: F) -> F:
+        metadata = ResourceMeta(
+            uri=uri,
+            name=name,
+            version=version,
+            title=title,
+            description=description,
+            icons=icons,
+            tags=tags,
+            mime_type=mime_type,
+            annotations=annotations,
+            meta=meta,
+            task=task,
+            auth=auth,
+        )
+        target = fn.__func__ if isinstance(fn, staticmethod | MethodType) else fn
+        cast(Any, target).__fastmcp__ = metadata
+        return fn
+
+    def decorator(fn: F) -> F:
+        return attach_metadata(fn)
+
+    return decorator
diff --git a/fastmcp_slim/fastmcp/resources/template.py b/fastmcp_slim/fastmcp/resources/template.py
new file mode 100644
index 0000000..7cd7b24
--- /dev/null
+++ b/fastmcp_slim/fastmcp/resources/template.py
@@ -0,0 +1,686 @@
+"""Resource template functionality."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import re
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, ClassVar, overload
+from urllib.parse import parse_qs, quote, unquote
+
+import mcp_types
+from mcp_types import Annotations, Icon
+from pydantic.json_schema import SkipJsonSchema
+
+if TYPE_CHECKING:
+    from docket import Docket
+    from docket.execution import Execution
+from mcp_types import ResourceTemplate as SDKResourceTemplate
+from pydantic import (
+    Field,
+    field_validator,
+    validate_call,
+)
+
+from fastmcp.resources.base import Resource, ResourceResult
+from fastmcp.utilities.authorization import AuthCheck
+from fastmcp.utilities.components import FastMCPComponent
+from fastmcp.utilities.json_schema import compress_schema
+from fastmcp.utilities.mime import resolve_ui_mime_type
+from fastmcp.utilities.tasks import TaskConfig, TaskMeta
+from fastmcp.utilities.types import get_cached_typeadapter
+
+
+def extract_query_params(uri_template: str) -> set[str]:
+    """Extract query parameter names from RFC 6570 `{?param1,param2}` syntax."""
+    match = re.search(r"\{\?([^}]+)\}", uri_template)
+    if match:
+        return {p.strip() for p in match.group(1).split(",")}
+    return set()
+
+
+def build_regex(template: str) -> re.Pattern[str] | None:
+    """Build regex pattern for URI template, handling RFC 6570 syntax.
+
+    Supports:
+    - `{var}` - simple path parameter
+    - `{var*}` - wildcard path parameter (captures multiple segments)
+    - `{?var1,var2}` - query parameters (ignored in path matching)
+
+    Hyphens in parameter names are normalized to underscores in regex group
+    names so that matched groups are valid Python identifiers.
+
+    Returns None if the template produces an invalid regex (e.g. parameter
+    names with leading digits or duplicates from a remote server).
+    """
+    # Remove query parameter syntax for path matching
+    template_without_query = re.sub(r"\{\?[^}]+\}", "", template)
+
+    parts = re.split(r"(\{[^}]+\})", template_without_query)
+    pattern = ""
+    for part in parts:
+        if part.startswith("{") and part.endswith("}"):
+            name = part[1:-1]
+            if name.endswith("*"):
+                name = name[:-1]
+                group = name.replace("-", "_")
+                pattern += f"(?P<{group}>.+)"
+            else:
+                group = name.replace("-", "_")
+                pattern += f"(?P<{group}>[^/]+)"
+        else:
+            pattern += re.escape(part)
+    try:
+        return re.compile(f"^{pattern}$")
+    except re.error:
+        return None
+
+
+def match_uri_template(uri: str, uri_template: str) -> dict[str, str] | None:
+    """Match URI against template and extract both path and query parameters.
+
+    Supports RFC 6570 URI templates:
+    - Path params: `{var}`, `{var*}`
+    - Query params: `{?var1,var2}`
+    """
+    # Split URI into path and query parts
+    uri_path, _, query_string = uri.partition("?")
+
+    # Match path parameters
+    regex = build_regex(uri_template)
+    if regex is None:
+        return None
+    match = regex.match(uri_path)
+    if not match:
+        return None
+
+    params = {k: unquote(v) for k, v in match.groupdict().items()}
+
+    # Extract query parameters if present in URI and template
+    if query_string:
+        query_param_names = extract_query_params(uri_template)
+        # keep_blank_values=True preserves empty values (e.g. ?format=)
+        # so callers can distinguish "explicitly empty" from "missing".
+        parsed_query = parse_qs(query_string, keep_blank_values=True)
+
+        for name in query_param_names:
+            if name in parsed_query:
+                # Take first value if multiple provided.
+                # Normalize hyphens to underscores to match Python param names.
+                # Don't overwrite path params that were already extracted.
+                key = name.replace("-", "_")
+                if key not in params:
+                    params[key] = parsed_query[name][0]
+
+    return params
+
+
+def expand_uri_template(uri_template: str, params: dict[str, Any]) -> str:
+    """Expand a URI template with parameters — inverse of `match_uri_template`.
+
+    Supports the same RFC 6570 subset:
+    - Path params: `{var}`, `{var*}`
+    - Query params: `{?var1,var2}`
+    """
+    result = uri_template
+
+    # Replace {name} and {name*} path placeholders, percent-encoding the
+    # substituted values so the result round-trips through match_uri_template
+    # (which unquotes captured groups). Simple {name} placeholders match a
+    # single segment ([^/]+), so reserved characters including "/" are encoded;
+    # wildcard {name*} placeholders may span segments, so "/" is preserved.
+    #
+    # Params use underscored keys (e.g. user_id) but templates may use
+    # hyphens (e.g. {user-id}), so try both forms.
+    for key, value in params.items():
+        value_str = str(value)
+        simple = quote(value_str, safe="")
+        wildcard = quote(value_str, safe="/")
+        forms = [key]
+        hyphenated = key.replace("_", "-")
+        if hyphenated != key:
+            forms.append(hyphenated)
+        for form in forms:
+            result = result.replace(f"{{{form}}}", simple)
+            result = result.replace(f"{{{form}*}}", wildcard)
+
+    # Expand {?param1,param2,...} query parameter blocks
+    def _expand_query_block(match: re.Match[str]) -> str:
+        names = [n.strip() for n in match.group(1).split(",")]
+        parts = []
+        for name in names:
+            underscored = name.replace("-", "_")
+            if name in params:
+                parts.append(f"{quote(name)}={quote(str(params[name]))}")
+            elif underscored in params:
+                parts.append(f"{quote(name)}={quote(str(params[underscored]))}")
+        if parts:
+            return "?" + "&".join(parts)
+        return ""
+
+    result = re.sub(r"\{\?([^}]+)\}", _expand_query_block, result)
+
+    return result
+
+
+class ResourceTemplate(FastMCPComponent):
+    """A template for dynamically creating resources."""
+
+    KEY_PREFIX: ClassVar[str] = "template"
+
+    uri_template: str = Field(
+        description="URI template with parameters (e.g. weather://{city}/current)"
+    )
+    mime_type: str = Field(
+        default="text/plain", description="MIME type of the resource content"
+    )
+    parameters: dict[str, Any] = Field(
+        description="JSON schema for function parameters"
+    )
+    annotations: Annotations | None = Field(
+        default=None, description="Optional annotations about the resource's behavior"
+    )
+    auth: SkipJsonSchema[AuthCheck | list[AuthCheck] | None] = Field(
+        default=None,
+        description="Authorization checks for this resource template",
+        exclude=True,
+    )
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(uri_template={self.uri_template!r}, name={self.name!r}, description={self.description!r}, tags={self.tags})"
+
+    @staticmethod
+    def from_function(
+        fn: Callable[..., Any],
+        uri_template: str,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[Icon] | None = None,
+        mime_type: str | None = None,
+        tags: set[str] | None = None,
+        annotations: Annotations | None = None,
+        meta: dict[str, Any] | None = None,
+        task: bool | TaskConfig | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+    ) -> FunctionResourceTemplate:
+        return FunctionResourceTemplate.from_function(
+            fn=fn,
+            uri_template=uri_template,
+            name=name,
+            version=version,
+            title=title,
+            description=description,
+            icons=icons,
+            mime_type=mime_type,
+            tags=tags,
+            annotations=annotations,
+            meta=meta,
+            task=task,
+            auth=auth,
+        )
+
+    @field_validator("mime_type", mode="before")
+    @classmethod
+    def set_default_mime_type(cls, mime_type: str | None) -> str:
+        """Set default MIME type if not provided."""
+        if mime_type:
+            return mime_type
+        return "text/plain"
+
+    def matches(self, uri: str) -> dict[str, Any] | None:
+        """Check if URI matches template and extract parameters."""
+        return match_uri_template(uri, self.uri_template)
+
+    async def read(self, arguments: dict[str, Any]) -> str | bytes | ResourceResult:
+        """Read the resource content."""
+        raise NotImplementedError(
+            "Subclasses must implement read() or override create_resource()"
+        )
+
+    def convert_result(self, raw_value: Any) -> ResourceResult:
+        """Convert a raw result to ResourceResult.
+
+        This is used in two contexts:
+        1. In _read() to convert user function return values to ResourceResult
+        2. In tasks_result_handler() to convert Docket task results to ResourceResult
+
+        Handles ResourceResult passthrough and converts raw values using
+        ResourceResult's normalization.
+        """
+        if isinstance(raw_value, ResourceResult):
+            return raw_value
+
+        # ResourceResult.__init__ handles all normalization
+        return ResourceResult(raw_value)
+
+    @overload
+    async def _read(
+        self, uri: str, params: dict[str, Any], task_meta: None = None
+    ) -> ResourceResult: ...
+
+    @overload
+    async def _read(
+        self, uri: str, params: dict[str, Any], task_meta: TaskMeta
+    ) -> mcp_types.CreateTaskResult: ...
+
+    async def _read(
+        self, uri: str, params: dict[str, Any], task_meta: TaskMeta | None = None
+    ) -> ResourceResult | mcp_types.CreateTaskResult:
+        """Server entry point that handles task routing.
+
+        This allows ANY ResourceTemplate subclass to support background execution
+        by setting task_config.mode to "supported" or "required". The server calls
+        this method instead of create_resource()/read() directly.
+
+        Args:
+            uri: The concrete URI being read
+            params: Template parameters extracted from the URI
+            task_meta: If provided, execute as a background task and return
+                CreateTaskResult. If None (default), execute synchronously and
+                return ResourceResult.
+
+        Returns:
+            ResourceResult when task_meta is None.
+            CreateTaskResult when task_meta is provided.
+
+        Subclasses can override this to customize task routing behavior.
+        For example, FastMCPProviderResourceTemplate overrides to delegate to child
+        middleware without submitting to Docket.
+        """
+        from fastmcp.server.tasks.routing import check_background_task
+
+        task_result = await check_background_task(
+            component=self, task_type="template", arguments=params, task_meta=task_meta
+        )
+        if task_result:
+            return task_result
+
+        # Synchronous execution - create resource and read directly
+        # Call resource.read() not resource._read() to avoid task routing on ephemeral resource
+        resource = await self.create_resource(uri, params)
+        result = await resource.read()
+        return self.convert_result(result)
+
+    async def create_resource(self, uri: str, params: dict[str, Any]) -> Resource:
+        """Create a resource from the template with the given parameters.
+
+        The base implementation does not support background tasks.
+        Use FunctionResourceTemplate for task support.
+        """
+        raise NotImplementedError(
+            "Subclasses must implement create_resource(). "
+            "Use FunctionResourceTemplate for task support."
+        )
+
+    def to_mcp_template(
+        self,
+        **overrides: Any,
+    ) -> SDKResourceTemplate:
+        """Convert the resource template to an SDKResourceTemplate."""
+
+        return SDKResourceTemplate(
+            name=overrides.get("name", self.name),
+            uri_template=overrides.get("uriTemplate", self.uri_template),
+            description=overrides.get("description", self.description),
+            mime_type=overrides.get("mimeType", self.mime_type),
+            title=overrides.get("title", self.title),
+            icons=overrides.get("icons", self.icons),
+            annotations=overrides.get("annotations", self.annotations),
+            _meta=overrides.get(  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
+                "_meta", self.get_meta()
+            ),
+        )
+
+    @classmethod
+    def from_mcp_template(cls, mcp_template: SDKResourceTemplate) -> ResourceTemplate:
+        """Creates a FastMCP ResourceTemplate from a raw MCP ResourceTemplate object."""
+        # Note: This creates a simple ResourceTemplate instance. For function-based templates,
+        # the original function is lost, which is expected for remote templates.
+        return cls(
+            uri_template=mcp_template.uri_template,
+            name=mcp_template.name,
+            description=mcp_template.description,
+            mime_type=mcp_template.mime_type or "text/plain",
+            parameters={},  # Remote templates don't have local parameters
+        )
+
+    @property
+    def key(self) -> str:
+        """The globally unique lookup key for this template."""
+        base_key = self.make_key(self.uri_template)
+        return f"{base_key}@{self.version or ''}"
+
+    def register_with_docket(self, docket: Docket) -> None:
+        """Register this template with docket for background execution."""
+        if not self.task_config.supports_tasks():
+            return
+        docket.register(self.read, names=[self.key])
+
+    async def add_to_docket(  # type: ignore[override]
+        self,
+        docket: Docket,
+        params: dict[str, Any],
+        *,
+        fn_key: str | None = None,
+        task_key: str | None = None,
+        **kwargs: Any,
+    ) -> Execution:
+        """Schedule this template for background execution via docket.
+
+        Args:
+            docket: The Docket instance
+            params: Template parameters
+            fn_key: Function lookup key in Docket registry (defaults to self.key)
+            task_key: Redis storage key for the result
+            **kwargs: Additional kwargs passed to docket.add()
+        """
+        lookup_key = fn_key or self.key
+        if task_key:
+            kwargs["key"] = task_key
+        return await docket.add(lookup_key, **kwargs)(params)
+
+    def get_span_attributes(self) -> dict[str, Any]:
+        return super().get_span_attributes() | {
+            "fastmcp.component.type": "resource_template",
+            "fastmcp.provider.type": "LocalProvider",
+        }
+
+
+class FunctionResourceTemplate(ResourceTemplate):
+    """A template for dynamically creating resources."""
+
+    fn: SkipJsonSchema[Callable[..., Any]]
+
+    @overload
+    async def _read(
+        self, uri: str, params: dict[str, Any], task_meta: None = None
+    ) -> ResourceResult: ...
+
+    @overload
+    async def _read(
+        self, uri: str, params: dict[str, Any], task_meta: TaskMeta
+    ) -> mcp_types.CreateTaskResult: ...
+
+    async def _read(
+        self, uri: str, params: dict[str, Any], task_meta: TaskMeta | None = None
+    ) -> ResourceResult | mcp_types.CreateTaskResult:
+        """Optimized server entry point that skips ephemeral resource creation.
+
+        For FunctionResourceTemplate, we can call read() directly instead of
+        creating a temporary resource, which is more efficient.
+
+        Args:
+            uri: The concrete URI being read
+            params: Template parameters extracted from the URI
+            task_meta: If provided, execute as a background task and return
+                CreateTaskResult. If None (default), execute synchronously and
+                return ResourceResult.
+
+        Returns:
+            ResourceResult when task_meta is None.
+            CreateTaskResult when task_meta is provided.
+        """
+        from fastmcp.server.tasks.routing import check_background_task
+
+        task_result = await check_background_task(
+            component=self, task_type="template", arguments=params, task_meta=task_meta
+        )
+        if task_result:
+            return task_result
+
+        # Synchronous execution - call read() directly, skip resource creation
+        result = await self.read(arguments=params)
+        return self.convert_result(result)
+
+    async def create_resource(self, uri: str, params: dict[str, Any]) -> Resource:
+        """Create a resource from the template with the given parameters."""
+
+        async def resource_read_fn() -> str | bytes | ResourceResult:
+            # Call function and check if result is a coroutine
+            result = await self.read(arguments=params)
+            return result
+
+        return Resource.from_function(
+            fn=resource_read_fn,
+            uri=uri,
+            name=self.name,
+            description=self.description,
+            mime_type=self.mime_type,
+            tags=self.tags,
+            annotations=self.annotations,
+            meta=self.meta,
+            title=self.title,
+            icons=self.icons,
+            task=self.task_config,
+            auth=self.auth,
+        )
+
+    async def read(self, arguments: dict[str, Any]) -> str | bytes | ResourceResult:
+        """Read the resource content."""
+        # Type coercion for query parameters (which arrive as strings)
+        kwargs = arguments.copy()
+        sig = inspect.signature(self.fn)
+        for param_name, param_value in list(kwargs.items()):
+            if param_name in sig.parameters and isinstance(param_value, str):
+                param = sig.parameters[param_name]
+                annotation = param.annotation
+
+                if annotation is inspect.Parameter.empty or annotation is str:
+                    continue
+
+                try:
+                    if annotation is int:
+                        kwargs[param_name] = int(param_value)
+                    elif annotation is float:
+                        kwargs[param_name] = float(param_value)
+                    elif annotation is bool:
+                        lower = param_value.lower()
+                        if lower in ("true", "1", "yes"):
+                            kwargs[param_name] = True
+                        elif lower in ("false", "0", "no"):
+                            kwargs[param_name] = False
+                        else:
+                            raise ValueError(
+                                f"Invalid boolean value for {param_name}: {param_value!r}"
+                            )
+                except (ValueError, AttributeError):
+                    raise
+
+        # self.fn is wrapped by without_injected_parameters which handles
+        # dependency resolution internally, so we call it directly
+        result = self.fn(**kwargs)
+        if inspect.isawaitable(result):
+            result = await result
+
+        return result
+
+    def register_with_docket(self, docket: Docket) -> None:
+        """Register this template with docket for background execution."""
+        if not self.task_config.supports_tasks():
+            return
+        docket.register(self.fn, names=[self.key])
+
+    async def add_to_docket(
+        self,
+        docket: Docket,
+        params: dict[str, Any],
+        *,
+        fn_key: str | None = None,
+        task_key: str | None = None,
+        **kwargs: Any,
+    ) -> Execution:
+        """Schedule this template for background execution via docket.
+
+        FunctionResourceTemplate splats the params dict since .fn expects **kwargs.
+
+        Args:
+            docket: The Docket instance
+            params: Template parameters
+            fn_key: Function lookup key in Docket registry (defaults to self.key)
+            task_key: Redis storage key for the result
+            **kwargs: Additional kwargs passed to docket.add()
+        """
+        lookup_key = fn_key or self.key
+        if task_key:
+            kwargs["key"] = task_key
+        return await docket.add(lookup_key, **kwargs)(**params)
+
+    @classmethod
+    def from_function(
+        cls,
+        fn: Callable[..., Any],
+        uri_template: str,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[Icon] | None = None,
+        mime_type: str | None = None,
+        tags: set[str] | None = None,
+        annotations: Annotations | None = None,
+        meta: dict[str, Any] | None = None,
+        task: bool | TaskConfig | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+    ) -> FunctionResourceTemplate:
+        """Create a template from a function."""
+
+        func_name = name or getattr(fn, "__name__", None) or fn.__class__.__name__
+        if func_name == "<lambda>":
+            raise ValueError("You must provide a name for lambda functions")
+
+        # Reject functions with *args
+        # (**kwargs is allowed because the URI will define the parameter names)
+        sig = inspect.signature(fn)
+        for param in sig.parameters.values():
+            if param.kind == inspect.Parameter.VAR_POSITIONAL:
+                raise ValueError(
+                    "Functions with *args are not supported as resource templates"
+                )
+
+        # Extract path and query parameters from URI template.
+        # Allow hyphens in names and normalize to underscores so they
+        # match Python function parameter names.
+        raw_path_params = set(re.findall(r"{([\w-]+)(?:\*)?}", uri_template))
+        raw_query_params = extract_query_params(uri_template)
+
+        # Detect collisions: two raw param names that normalize to the
+        # same Python identifier (e.g. {user-id} and {user_id}).
+        all_raw = raw_path_params | raw_query_params
+        seen: dict[str, str] = {}
+        for raw_name in sorted(all_raw):
+            normalized = raw_name.replace("-", "_")
+            if normalized in seen:
+                raise ValueError(
+                    f"URI template parameters '{seen[normalized]}' and "
+                    f"'{raw_name}' both normalize to '{normalized}'. "
+                    f"Use one or the other, not both."
+                )
+            seen[normalized] = raw_name
+
+        path_params = {p.replace("-", "_") for p in raw_path_params}
+        query_params = {p.replace("-", "_") for p in raw_query_params}
+        all_uri_params = path_params | query_params
+
+        if not all_uri_params:
+            raise ValueError("URI template must contain at least one parameter")
+
+        # Use wrapper to get user-facing parameters (excludes injected params)
+        from fastmcp.server.dependencies import (
+            transform_context_annotations,
+            without_injected_parameters,
+        )
+
+        wrapper_fn = without_injected_parameters(fn)
+        user_sig = inspect.signature(wrapper_fn)
+        func_params = set(user_sig.parameters.keys())
+
+        # Get required and optional function parameters
+        required_params = {
+            p
+            for p in func_params
+            if user_sig.parameters[p].default is inspect.Parameter.empty
+            and user_sig.parameters[p].kind != inspect.Parameter.VAR_KEYWORD
+        }
+        optional_params = {
+            p
+            for p in func_params
+            if user_sig.parameters[p].default is not inspect.Parameter.empty
+            and user_sig.parameters[p].kind != inspect.Parameter.VAR_KEYWORD
+        }
+
+        # Validate RFC 6570 query parameters
+        # Query params must be optional (have defaults)
+        if query_params:
+            invalid_query_params = query_params - optional_params
+            if invalid_query_params:
+                raise ValueError(
+                    f"Query parameters {invalid_query_params} must be optional function parameters with default values"
+                )
+
+        # Check if required parameters are a subset of the path parameters
+        if not required_params.issubset(path_params):
+            raise ValueError(
+                f"Required function arguments {required_params} must be a subset of the URI path parameters {path_params}"
+            )
+
+        # Check if all URI parameters are valid function parameters (skip if **kwargs present)
+        if not any(
+            param.kind == inspect.Parameter.VAR_KEYWORD
+            for param in sig.parameters.values()
+        ):
+            if not all_uri_params.issubset(func_params):
+                raise ValueError(
+                    f"URI parameters {all_uri_params} must be a subset of the function arguments: {func_params}"
+                )
+
+        description = description if description is not None else inspect.getdoc(fn)
+
+        # Normalize task to TaskConfig and validate
+        if task is None:
+            task_config = TaskConfig(mode="forbidden")
+        elif isinstance(task, bool):
+            task_config = TaskConfig.from_bool(task)
+        else:
+            task_config = task
+        task_config.validate_function(fn, func_name)
+
+        # if the fn is a callable class, we need to get the __call__ method from here out
+        if not inspect.isroutine(fn) and not isinstance(fn, functools.partial):
+            fn = fn.__call__
+        # if the fn is a staticmethod, we need to work with the underlying function
+        if isinstance(fn, staticmethod):
+            fn = fn.__func__
+
+        # Transform Context type annotations to Depends() for unified DI
+        fn = transform_context_annotations(fn)
+
+        wrapper_fn = without_injected_parameters(fn)
+        type_adapter = get_cached_typeadapter(wrapper_fn)
+        parameters = type_adapter.json_schema()
+        parameters = compress_schema(parameters, prune_titles=True)
+
+        # Use validate_call on wrapper for runtime type coercion
+        fn = validate_call(wrapper_fn)
+
+        # Apply ui:// MIME default, then fall back to text/plain
+        resolved_mime = resolve_ui_mime_type(uri_template, mime_type)
+
+        return cls(
+            uri_template=uri_template,
+            name=func_name,
+            version=str(version) if version is not None else None,
+            title=title,
+            description=description,
+            icons=icons,
+            mime_type=resolved_mime or "text/plain",
+            fn=fn,
+            parameters=parameters,
+            tags=tags or set(),
+            annotations=annotations,
+            meta=meta,
+            task_config=task_config,
+            auth=auth,
+        )
diff --git a/fastmcp_slim/fastmcp/resources/types.py b/fastmcp_slim/fastmcp/resources/types.py
new file mode 100644
index 0000000..ed514c5
--- /dev/null
+++ b/fastmcp_slim/fastmcp/resources/types.py
@@ -0,0 +1,188 @@
+"""Concrete resource implementations."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import httpx
+import pydantic.json
+from anyio import Path as AsyncPath
+from pydantic import Field, ValidationInfo
+from typing_extensions import override
+
+from fastmcp.exceptions import ResourceError
+from fastmcp.resources.base import Resource, ResourceContent, ResourceResult
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class TextResource(Resource):
+    """A resource that reads from a string."""
+
+    text: str = Field(description="Text content of the resource")
+
+    async def read(self) -> ResourceResult:
+        """Read the text content."""
+        return ResourceResult(
+            contents=[
+                ResourceContent(
+                    content=self.text, mime_type=self.mime_type, meta=self.meta
+                )
+            ]
+        )
+
+
+class BinaryResource(Resource):
+    """A resource that reads from bytes."""
+
+    data: bytes = Field(description="Binary content of the resource")
+
+    async def read(self) -> ResourceResult:
+        """Read the binary content."""
+        return ResourceResult(
+            contents=[
+                ResourceContent(
+                    content=self.data, mime_type=self.mime_type, meta=self.meta
+                )
+            ]
+        )
+
+
+class FileResource(Resource):
+    """A resource that reads from a file.
+
+    Set is_binary=True to read file as binary data instead of text.
+    """
+
+    path: Path = Field(description="Path to the file")
+    is_binary: bool = Field(
+        default=False,
+        description="Whether to read the file as binary data",
+    )
+    mime_type: str = Field(
+        default="text/plain",
+        description="MIME type of the resource content",
+    )
+    encoding: str | None = Field(
+        default="utf-8",
+        description=(
+            "Encoding to use when reading text files. "
+            "Defaults to 'utf-8' for cross-platform compatibility. "
+            "Set to None to use the system default encoding."
+        ),
+    )
+
+    @property
+    def _async_path(self) -> AsyncPath:
+        return AsyncPath(self.path)
+
+    @pydantic.field_validator("path")
+    @classmethod
+    def validate_absolute_path(cls, path: Path) -> Path:
+        """Ensure path is absolute."""
+        if not path.is_absolute():
+            raise ValueError("Path must be absolute")
+        return path
+
+    @pydantic.field_validator("is_binary")
+    @classmethod
+    def set_binary_from_mime_type(cls, is_binary: bool, info: ValidationInfo) -> bool:
+        """Set is_binary based on mime_type if not explicitly set."""
+        if is_binary:
+            return True
+        mime_type = info.data.get("mime_type", "text/plain")
+        return not mime_type.startswith("text/")
+
+    @override
+    async def read(self) -> ResourceResult:
+        """Read the file content."""
+        try:
+            if self.is_binary:
+                content: str | bytes = await self._async_path.read_bytes()
+            else:
+                content = await self._async_path.read_text(encoding=self.encoding)
+            return ResourceResult(
+                contents=[ResourceContent(content=content, mime_type=self.mime_type)]
+            )
+        except Exception as e:
+            raise ResourceError(f"Error reading file {self.path}") from e
+
+
+class HttpResource(Resource):
+    """A resource that reads from an HTTP endpoint."""
+
+    url: str = Field(description="URL to fetch content from")
+    mime_type: str = Field(
+        default="application/json", description="MIME type of the resource content"
+    )
+
+    @override
+    async def read(self) -> ResourceResult:
+        """Read the HTTP content."""
+        async with httpx.AsyncClient() as client:
+            response = await client.get(self.url)
+            _ = response.raise_for_status()
+            return ResourceResult(
+                contents=[
+                    ResourceContent(content=response.text, mime_type=self.mime_type)
+                ]
+            )
+
+
+class DirectoryResource(Resource):
+    """A resource that lists files in a directory."""
+
+    path: Path = Field(description="Path to the directory")
+    recursive: bool = Field(
+        default=False, description="Whether to list files recursively"
+    )
+    pattern: str | None = Field(
+        default=None, description="Optional glob pattern to filter files"
+    )
+    mime_type: str = Field(
+        default="application/json", description="MIME type of the resource content"
+    )
+
+    @property
+    def _async_path(self) -> AsyncPath:
+        return AsyncPath(self.path)
+
+    @pydantic.field_validator("path")
+    @classmethod
+    def validate_absolute_path(cls, path: Path) -> Path:
+        """Ensure path is absolute."""
+        if not path.is_absolute():
+            raise ValueError("Path must be absolute")
+        return path
+
+    async def list_files(self) -> list[Path]:
+        """List files in the directory."""
+        if not await self._async_path.exists():
+            raise FileNotFoundError(f"Directory not found: {self.path}")
+        if not await self._async_path.is_dir():
+            raise NotADirectoryError(f"Not a directory: {self.path}")
+
+        pattern = self.pattern or "*"
+
+        glob_fn = self._async_path.rglob if self.recursive else self._async_path.glob
+        try:
+            return [Path(p) async for p in glob_fn(pattern) if await p.is_file()]
+        except Exception as e:
+            raise ResourceError(f"Error listing directory {self.path}") from e
+
+    @override
+    async def read(self) -> ResourceResult:
+        """Read the directory listing."""
+        try:
+            files: list[Path] = await self.list_files()
+
+            file_list = [str(f.relative_to(self.path)) for f in files]
+
+            content = json.dumps({"files": file_list}, indent=2)
+            return ResourceResult(
+                contents=[ResourceContent(content=content, mime_type=self.mime_type)]
+            )
+        except Exception as e:
+            raise ResourceError(f"Error reading directory {self.path}") from e
diff --git a/fastmcp_slim/fastmcp/server/__init__.py b/fastmcp_slim/fastmcp/server/__init__.py
new file mode 100644
index 0000000..d6edbc4
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/__init__.py
@@ -0,0 +1,18 @@
+import importlib
+
+from fastmcp import _install_hints
+
+try:
+    from .context import Context
+    from .server import FastMCP, create_proxy
+except ImportError as exc:
+    raise ImportError(_install_hints.SERVER_SUPPORT) from exc
+
+
+def __getattr__(name: str) -> object:
+    if name == "dependencies":
+        return importlib.import_module("fastmcp.server.dependencies")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = ["Context", "FastMCP", "create_proxy"]
diff --git a/fastmcp_slim/fastmcp/server/auth/__init__.py b/fastmcp_slim/fastmcp/server/auth/__init__.py
new file mode 100644
index 0000000..cd6a300
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/__init__.py
@@ -0,0 +1,75 @@
+from typing import TYPE_CHECKING
+
+from .auth import (
+    OAuthProvider,
+    TokenVerifier,
+    RemoteAuthProvider,
+    MultiAuth,
+    AccessToken,
+    AuthProvider,
+)
+from .authorization import (
+    AuthCheck,
+    AuthContext,
+    require_scopes,
+    restrict_tag,
+    run_auth_checks,
+)
+
+if TYPE_CHECKING:
+    from .oauth_proxy import OAuthProxy as OAuthProxy
+    from .oidc_proxy import OIDCProxy as OIDCProxy
+    from .providers.debug import DebugTokenVerifier as DebugTokenVerifier
+    from .providers.jwt import JWTVerifier as JWTVerifier
+    from .providers.jwt import StaticTokenVerifier as StaticTokenVerifier
+
+
+# --- Lazy imports for performance (see #3292) ---
+# These providers pull in heavy deps (authlib, cryptography, key_value.aio,
+# beartype) that most users never need. Keeping them behind __getattr__
+# avoids ~150ms+ of import overhead for the common server-only case.
+# Do not convert these back to top-level imports.
+
+
+def __getattr__(name: str) -> object:
+    if name == "DebugTokenVerifier":
+        from .providers.debug import DebugTokenVerifier
+
+        return DebugTokenVerifier
+    if name == "JWTVerifier":
+        from .providers.jwt import JWTVerifier
+
+        return JWTVerifier
+    if name == "StaticTokenVerifier":
+        from .providers.jwt import StaticTokenVerifier
+
+        return StaticTokenVerifier
+    if name == "OAuthProxy":
+        from .oauth_proxy import OAuthProxy
+
+        return OAuthProxy
+    if name == "OIDCProxy":
+        from .oidc_proxy import OIDCProxy
+
+        return OIDCProxy
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "AccessToken",
+    "AuthCheck",
+    "AuthContext",
+    "AuthProvider",
+    "DebugTokenVerifier",
+    "JWTVerifier",
+    "MultiAuth",
+    "OAuthProvider",
+    "OAuthProxy",
+    "OIDCProxy",
+    "RemoteAuthProvider",
+    "StaticTokenVerifier",
+    "TokenVerifier",
+    "require_scopes",
+    "restrict_tag",
+    "run_auth_checks",
+]
diff --git a/fastmcp_slim/fastmcp/server/auth/auth.py b/fastmcp_slim/fastmcp/server/auth/auth.py
new file mode 100644
index 0000000..dc203fb
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/auth.py
@@ -0,0 +1,872 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlparse
+
+from mcp.server.auth.handlers.token import TokenErrorResponse
+from mcp.server.auth.handlers.token import TokenHandler as _SDKTokenHandler
+from mcp.server.auth.json_response import PydanticJSONResponse
+from mcp.server.auth.middleware.auth_context import AuthContextMiddleware
+from mcp.server.auth.middleware.bearer_auth import BearerAuthBackend
+from mcp.server.auth.middleware.client_auth import (
+    AuthenticationError,
+    ClientAuthenticator,
+)
+from mcp.server.auth.middleware.client_auth import (
+    ClientAuthenticator as _SDKClientAuthenticator,
+)
+from mcp.server.auth.provider import (
+    AccessToken as _SDKAccessToken,
+)
+from mcp.server.auth.provider import (
+    AuthorizationCode,
+    OAuthAuthorizationServerProvider,
+    RefreshToken,
+)
+from mcp.server.auth.provider import (
+    TokenVerifier as TokenVerifierProtocol,
+)
+from mcp.server.auth.routes import (
+    cors_middleware,
+    create_auth_routes,
+    create_protected_resource_routes,
+)
+from mcp.server.auth.settings import (
+    ClientRegistrationOptions,
+    RevocationOptions,
+)
+from mcp.shared.auth import OAuthClientInformationFull
+from pydantic import AnyHttpUrl, Field
+from starlette.middleware import Middleware
+from starlette.middleware.authentication import AuthenticationMiddleware
+from starlette.requests import Request
+from starlette.routing import Route
+
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    from fastmcp.server.auth.cimd import CIMDClientManager
+
+logger = get_logger(__name__)
+
+
+class AccessToken(_SDKAccessToken):
+    """AccessToken that includes all JWT claims."""
+
+    claims: dict[str, Any] = Field(default_factory=dict)
+
+
+class TokenHandler(_SDKTokenHandler):
+    """TokenHandler that returns MCP-compliant error responses.
+
+    This handler addresses two SDK issues:
+
+    1. Error code: The SDK returns `unauthorized_client` for client authentication
+       failures, but RFC 6749 Section 5.2 requires `invalid_client` with HTTP 401.
+       This distinction matters for client re-registration behavior.
+
+    2. Status code: The SDK returns HTTP 400 for all token errors including
+       `invalid_grant` (expired/invalid tokens). However, the MCP spec requires:
+       "Invalid or expired tokens MUST receive a HTTP 401 response."
+
+    This handler transforms responses to be compliant with both OAuth 2.1 and MCP specs.
+    """
+
+    async def handle(self, request: Any):
+        """Wrap SDK handle() and transform auth error responses."""
+        response = await super().handle(request)
+
+        # Transform 401 unauthorized_client -> invalid_client
+        if response.status_code == 401:
+            try:
+                body = json.loads(response.body)
+                if body.get("error") == "unauthorized_client":
+                    return PydanticJSONResponse(
+                        content=TokenErrorResponse(
+                            error="invalid_client",
+                            error_description=body.get("error_description"),
+                        ),
+                        status_code=401,
+                        headers={
+                            "Cache-Control": "no-store",
+                            "Pragma": "no-cache",
+                        },
+                    )
+            except (json.JSONDecodeError, AttributeError):
+                pass  # Not JSON or unexpected format, return as-is
+
+        # Transform 400 invalid_grant -> 401 for expired/invalid tokens
+        # Per MCP spec: "Invalid or expired tokens MUST receive a HTTP 401 response."
+        if response.status_code == 400:
+            try:
+                body = json.loads(response.body)
+                if body.get("error") == "invalid_grant":
+                    return PydanticJSONResponse(
+                        content=TokenErrorResponse(
+                            error="invalid_grant",
+                            error_description=body.get("error_description"),
+                        ),
+                        status_code=401,
+                        headers={
+                            "Cache-Control": "no-store",
+                            "Pragma": "no-cache",
+                        },
+                    )
+            except (json.JSONDecodeError, AttributeError):
+                pass  # Not JSON or unexpected format, return as-is
+
+        return response
+
+
+# Expected assertion type for private_key_jwt
+JWT_BEARER_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+
+
+class PrivateKeyJWTClientAuthenticator(_SDKClientAuthenticator):
+    """Client authenticator with private_key_jwt support for CIMD clients.
+
+    Extends the SDK's ClientAuthenticator to add support for the `private_key_jwt`
+    authentication method per RFC 7523. This is required for CIMD (Client ID Metadata
+    Document) clients that use asymmetric keys for authentication.
+
+    The authenticator:
+    1. Delegates to SDK for standard methods (client_secret_basic, client_secret_post, none)
+    2. Adds private_key_jwt handling for CIMD clients
+    3. Validates JWT assertions against client's JWKS
+    """
+
+    def __init__(
+        self,
+        provider: OAuthAuthorizationServerProvider[Any, Any, Any],
+        cimd_manager: CIMDClientManager,
+        token_endpoint_url: str,
+    ):
+        """Initialize the authenticator.
+
+        Args:
+            provider: OAuth provider for client lookups
+            cimd_manager: CIMD manager for private_key_jwt validation
+            token_endpoint_url: Token endpoint URL for audience validation
+        """
+        super().__init__(provider)
+        self._cimd_manager = cimd_manager
+        self._token_endpoint_url = token_endpoint_url
+
+    async def authenticate_request(
+        self, request: Request
+    ) -> OAuthClientInformationFull:
+        """Authenticate a client from an HTTP request.
+
+        Extends SDK authentication to support private_key_jwt for CIMD clients.
+        Delegates to SDK for client_secret_basic (Authorization header) and
+        client_secret_post (form body) authentication.
+        """
+        form_data = await request.form()
+        client_id = form_data.get("client_id")
+
+        # If client_id is not in form data, delegate to SDK
+        # This handles client_secret_basic which sends credentials in Authorization header
+        if not client_id:
+            return await super().authenticate_request(request)
+
+        client = await self.provider.get_client(str(client_id))
+        if not client:
+            raise AuthenticationError("Invalid client_id")
+
+        # Handle private_key_jwt authentication for CIMD clients
+        if client.token_endpoint_auth_method == "private_key_jwt":
+            # Validate assertion parameters
+            assertion_type = form_data.get("client_assertion_type")
+            assertion = form_data.get("client_assertion")
+
+            if assertion_type != JWT_BEARER_ASSERTION_TYPE:
+                raise AuthenticationError(
+                    f"Invalid client_assertion_type: expected {JWT_BEARER_ASSERTION_TYPE}"
+                )
+
+            if not assertion or not isinstance(assertion, str):
+                raise AuthenticationError("Missing client_assertion")
+
+            # Validate the JWT assertion using CIMD manager
+            try:
+                await self._cimd_manager.validate_private_key_jwt(
+                    assertion=assertion,
+                    client=client,
+                    token_endpoint=self._token_endpoint_url,
+                )
+            except ValueError as e:
+                raise AuthenticationError(f"Invalid client assertion: {e}") from e
+
+            return client
+
+        # Delegate to SDK for other authentication methods
+        return await super().authenticate_request(request)
+
+
+class AuthProvider(TokenVerifierProtocol):
+    """Base class for all FastMCP authentication providers.
+
+    This class provides a unified interface for all authentication providers,
+    whether they are simple token verifiers or full OAuth authorization servers.
+    All providers must be able to verify tokens and can optionally provide
+    custom authentication routes.
+    """
+
+    def __init__(
+        self,
+        base_url: AnyHttpUrl | str | None = None,
+        required_scopes: list[str] | None = None,
+        resource_base_url: AnyHttpUrl | str | None = None,
+    ):
+        """
+        Initialize the auth provider.
+
+        Args:
+            base_url: The base URL of this server (e.g., http://localhost:8000).
+                This is used for constructing .well-known endpoints and OAuth metadata.
+            resource_base_url: Optional public base URL for the protected resource.
+                When provided, the resource URL advertised in protected resource
+                metadata (RFC 9728) is derived from this URL instead of ``base_url``,
+                while operational OAuth routes remain rooted at ``base_url``.
+                Providers that mint their own downstream tokens (e.g. ``OAuthProxy``)
+                also use this as the minted token audience. Upstream token audience
+                validation is configured separately on the token verifier.
+            required_scopes: List of OAuth scopes required for all requests.
+        """
+        if isinstance(base_url, str):
+            base_url = AnyHttpUrl(base_url)
+        if isinstance(resource_base_url, str):
+            resource_base_url = AnyHttpUrl(resource_base_url)
+        self.base_url = base_url
+        self.resource_base_url = resource_base_url
+        self.required_scopes = required_scopes or []
+        self._mcp_path: str | None = None
+        self._resource_url: AnyHttpUrl | None = None
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify a bearer token and return access info if valid.
+
+        All auth providers must implement token verification.
+
+        Args:
+            token: The token string to validate
+
+        Returns:
+            AccessToken object if valid, None if invalid or expired
+        """
+        raise NotImplementedError("Subclasses must implement verify_token")
+
+    def set_mcp_path(self, mcp_path: str | None) -> None:
+        """Set the MCP endpoint path and compute resource URL.
+
+        This method is called by get_routes() to configure the expected
+        resource URL before route creation. Subclasses can override to
+        perform additional initialization that depends on knowing the
+        MCP endpoint path.
+
+        Args:
+            mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
+        """
+        self._mcp_path = mcp_path
+        self._resource_url = self._get_resource_url(mcp_path)
+
+    def get_routes(
+        self,
+        mcp_path: str | None = None,
+    ) -> list[Route]:
+        """Get all routes for this authentication provider.
+
+        This includes both well-known discovery routes and operational routes.
+        Each provider is responsible for creating whatever routes it needs:
+        - TokenVerifier: typically no routes (default implementation)
+        - RemoteAuthProvider: protected resource metadata routes
+        - OAuthProvider: full OAuth authorization server routes
+        - Custom providers: whatever routes they need
+
+        Args:
+            mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
+                This is used to advertise the resource URL in metadata, but the
+                provider does not create the actual MCP endpoint route.
+
+        Returns:
+            List of all routes for this provider (excluding the MCP endpoint itself)
+        """
+        return []
+
+    def get_well_known_routes(
+        self,
+        mcp_path: str | None = None,
+    ) -> list[Route]:
+        """Get well-known discovery routes for this authentication provider.
+
+        This is a utility method that filters get_routes() to return only
+        well-known discovery routes (those starting with /.well-known/).
+
+        Well-known routes provide OAuth metadata and discovery endpoints that
+        clients use to discover authentication capabilities. These routes should
+        be mounted at the root level of the application to comply with RFC 8414
+        and RFC 9728.
+
+        Common well-known routes:
+        - /.well-known/oauth-authorization-server (authorization server metadata)
+        - /.well-known/oauth-protected-resource/* (protected resource metadata)
+
+        Args:
+            mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
+                This is used to construct path-scoped well-known URLs.
+
+        Returns:
+            List of well-known discovery routes (typically mounted at root level)
+        """
+        all_routes = self.get_routes(mcp_path)
+        return [
+            route
+            for route in all_routes
+            if isinstance(route, Route) and route.path.startswith("/.well-known/")
+        ]
+
+    def get_middleware(self) -> list:
+        """Get HTTP application-level middleware for this auth provider.
+
+        Returns:
+            List of Starlette Middleware instances to apply to the HTTP app
+        """
+        return [
+            Middleware(
+                AuthenticationMiddleware,  # type: ignore[arg-type]
+                backend=BearerAuthBackend(self),
+            ),
+            Middleware(AuthContextMiddleware),  # type: ignore[arg-type]
+        ]
+
+    def _get_resource_url(self, path: str | None = None) -> AnyHttpUrl | None:
+        """Get the actual resource URL being protected.
+
+        Uses ``resource_base_url`` if set; otherwise falls back to
+        ``base_url``.
+
+        Args:
+            path: The path where the resource endpoint is mounted (e.g., "/mcp")
+
+        Returns:
+            The full URL of the protected resource
+        """
+        resource_base_url = self.resource_base_url or self.base_url
+        if resource_base_url is None:
+            return None
+
+        if path:
+            prefix = str(resource_base_url).rstrip("/")
+            suffix = path.lstrip("/")
+            return AnyHttpUrl(f"{prefix}/{suffix}")
+        return resource_base_url
+
+
+class TokenVerifier(AuthProvider):
+    """Base class for token verifiers (Resource Servers).
+
+    This class provides token verification capability without OAuth server functionality.
+    Token verifiers typically don't provide authentication routes by default.
+    """
+
+    def __init__(
+        self,
+        base_url: AnyHttpUrl | str | None = None,
+        required_scopes: list[str] | None = None,
+        resource_base_url: AnyHttpUrl | str | None = None,
+    ):
+        """
+        Initialize the token verifier.
+
+        Args:
+            base_url: The base URL of this server
+            resource_base_url: Optional public base URL for the protected resource.
+                When provided, the resource URL advertised in protected resource
+                metadata is derived from this URL instead of ``base_url``. Does not
+                configure upstream token audience validation — set ``audience`` on
+                your verifier to match.
+            required_scopes: Scopes that are required for all requests
+        """
+        super().__init__(
+            base_url=base_url,
+            resource_base_url=resource_base_url,
+            required_scopes=required_scopes,
+        )
+
+    @property
+    def scopes_supported(self) -> list[str]:
+        """Scopes to advertise in OAuth metadata.
+
+        Defaults to required_scopes. Override in subclasses when the
+        advertised scopes differ from the validation scopes (e.g., Azure AD
+        where tokens contain short-form scopes but clients request full URI
+        scopes).
+        """
+        return self.required_scopes or []
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify a bearer token and return access info if valid."""
+        raise NotImplementedError("Subclasses must implement verify_token")
+
+
+class RemoteAuthProvider(AuthProvider):
+    """Authentication provider for resource servers that verify tokens from known authorization servers.
+
+    This provider composes a TokenVerifier with authorization server metadata to create
+    standardized OAuth 2.0 Protected Resource endpoints (RFC 9728). Perfect for:
+    - JWT verification with known issuers
+    - Remote token introspection services
+    - Any resource server that knows where its tokens come from
+
+    Use this when you have token verification logic and want to advertise
+    the authorization servers that issue valid tokens.
+    """
+
+    base_url: AnyHttpUrl
+
+    def __init__(
+        self,
+        token_verifier: TokenVerifier,
+        authorization_servers: list[AnyHttpUrl],
+        base_url: AnyHttpUrl | str,
+        scopes_supported: list[str] | None = None,
+        resource_base_url: AnyHttpUrl | str | None = None,
+        resource_name: str | None = None,
+        resource_documentation: AnyHttpUrl | None = None,
+    ):
+        """Initialize the remote auth provider.
+
+        Args:
+            token_verifier: TokenVerifier instance for token validation
+            authorization_servers: List of authorization servers that issue valid tokens
+            base_url: The base URL of this server
+            resource_base_url: Optional public base URL for the protected resource.
+                When provided, the resource URL advertised in protected resource
+                metadata is derived from this URL instead of ``base_url``. Does not
+                configure the token verifier's audience — set ``audience`` on the
+                verifier to match if you want validated tokens bound to the same
+                resource.
+            scopes_supported: Scopes to advertise in OAuth metadata. If None,
+                uses the token verifier's scopes_supported property. Use this
+                when the scopes clients request differ from the scopes that
+                appear in tokens (e.g., Azure AD full URI scopes vs short-form).
+            resource_name: Optional name for the protected resource
+            resource_documentation: Optional documentation URL for the protected resource
+        """
+        super().__init__(
+            base_url=base_url,
+            resource_base_url=resource_base_url,
+            required_scopes=token_verifier.required_scopes,
+        )
+        self.token_verifier = token_verifier
+        self.authorization_servers = authorization_servers
+        self._scopes_supported = scopes_supported
+        self.resource_name = resource_name
+        self.resource_documentation = resource_documentation
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify token using the configured token verifier."""
+        return await self.token_verifier.verify_token(token)
+
+    def get_routes(
+        self,
+        mcp_path: str | None = None,
+    ) -> list[Route]:
+        """Get routes for this provider.
+
+        Creates protected resource metadata routes (RFC 9728).
+        """
+        # Lifecycle hook: let subclasses react to the mcp_path becoming known
+        # (e.g., bind token audience to the resource URL). Mirrors the call in
+        # OAuthAuthorizationServerProvider.get_routes so all providers see the
+        # path at the same point in their lifecycle.
+        self.set_mcp_path(mcp_path)
+
+        routes = []
+
+        # Get the resource URL based on the MCP path
+        resource_url = self._get_resource_url(mcp_path)
+
+        if resource_url:
+            # Add protected resource metadata routes
+            routes.extend(
+                create_protected_resource_routes(
+                    resource_url=resource_url,
+                    authorization_servers=self.authorization_servers,
+                    scopes_supported=(
+                        self._scopes_supported
+                        if self._scopes_supported is not None
+                        else self.token_verifier.scopes_supported
+                    ),
+                    resource_name=self.resource_name,
+                    resource_documentation=self.resource_documentation,
+                )
+            )
+
+        return routes
+
+
+class MultiAuth(AuthProvider):
+    """Composes an optional auth server with additional token verifiers.
+
+    Use this when a single server needs to accept tokens from multiple sources.
+    For example, an OAuth proxy for interactive clients combined with a JWT
+    verifier for machine-to-machine tokens.
+
+    Token verification tries the server first (if present), then each verifier
+    in order, returning the first successful result. Routes and OAuth metadata
+    come from the server; verifiers contribute only token verification.
+
+    Example:
+        ```python
+        from fastmcp.server.auth import MultiAuth, JWTVerifier, OAuthProxy
+
+        auth = MultiAuth(
+            server=OAuthProxy(issuer_url="https://login.example.com/..."),
+            verifiers=[JWTVerifier(jwks_uri="https://example.com/.well-known/jwks.json")],
+        )
+        mcp = FastMCP("my-server", auth=auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        server: AuthProvider | None = None,
+        verifiers: list[TokenVerifier] | TokenVerifier | None = None,
+        base_url: AnyHttpUrl | str | None = None,
+        resource_base_url: AnyHttpUrl | str | None = None,
+        required_scopes: list[str] | None = None,
+    ):
+        """Initialize the multi-auth provider.
+
+        Args:
+            server: Optional auth provider (e.g., OAuthProxy) that owns routes
+                and OAuth metadata. Also participates in token verification as
+                the first verifier tried.
+            verifiers: One or more token verifiers to try after the server.
+            base_url: Override the base URL. Defaults to the server's base_url.
+            resource_base_url: Override the protected resource base URL. Defaults
+                to the server's resource_base_url when available.
+            required_scopes: Override required scopes. Defaults to the server's.
+        """
+        if verifiers is None:
+            verifiers = []
+        elif isinstance(verifiers, TokenVerifier):
+            verifiers = [verifiers]
+
+        if server is None and not verifiers:
+            raise ValueError("MultiAuth requires at least a server or one verifier")
+
+        effective_base_url = base_url or (server.base_url if server else None)
+        effective_resource_base_url = resource_base_url or (
+            server.resource_base_url if server else None
+        )
+        effective_scopes = (
+            required_scopes
+            if required_scopes is not None
+            else (server.required_scopes if server else None)
+        )
+
+        super().__init__(
+            base_url=effective_base_url,
+            resource_base_url=effective_resource_base_url,
+            required_scopes=effective_scopes,
+        )
+        self.server = server
+        self.verifiers = list(verifiers)
+
+        # If an explicit resource_base_url override was passed to MultiAuth,
+        # propagate it to the wrapped server so its routes advertise metadata
+        # consistent with the outer auth challenge URL.
+        if resource_base_url is not None and self.server is not None:
+            self.server.resource_base_url = self.resource_base_url
+
+        self._sources: list[AuthProvider] = []
+        if self.server is not None:
+            self._sources.append(self.server)
+        self._sources.extend(self.verifiers)
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify a token by trying the server, then each verifier in order.
+
+        Each source is tried independently. If a source raises an exception,
+        it is logged and treated as a non-match so that remaining sources
+        still get a chance to verify the token.
+        """
+        for source in self._sources:
+            try:
+                result = await source.verify_token(token)
+                if result is not None:
+                    return result
+            except Exception:
+                logger.debug(
+                    "Token verification failed for %s, trying next source",
+                    type(source).__name__,
+                    exc_info=True,
+                )
+
+        return None
+
+    def set_mcp_path(self, mcp_path: str | None) -> None:
+        """Propagate MCP path to the server and all verifiers."""
+        super().set_mcp_path(mcp_path)
+        if self.server is not None:
+            self.server.set_mcp_path(mcp_path)
+        for verifier in self.verifiers:
+            verifier.set_mcp_path(mcp_path)
+
+    def get_routes(self, mcp_path: str | None = None) -> list[Route]:
+        """Delegate route creation to the server."""
+        if self.server is not None:
+            return self.server.get_routes(mcp_path)
+        return []
+
+    def get_well_known_routes(self, mcp_path: str | None = None) -> list[Route]:
+        """Delegate well-known route creation to the server.
+
+        This ensures that server-specific well-known route logic (e.g.,
+        OAuthProvider's RFC 8414 path-aware discovery) is preserved.
+        """
+        if self.server is not None:
+            return self.server.get_well_known_routes(mcp_path)
+        return []
+
+
+class OAuthProvider(
+    AuthProvider,
+    OAuthAuthorizationServerProvider[AuthorizationCode, RefreshToken, AccessToken],
+):
+    """OAuth Authorization Server provider.
+
+    This class provides full OAuth server functionality including client registration,
+    authorization flows, token issuance, and token verification.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: AnyHttpUrl | str,
+        resource_base_url: AnyHttpUrl | str | None = None,
+        issuer_url: AnyHttpUrl | str | None = None,
+        service_documentation_url: AnyHttpUrl | str | None = None,
+        client_registration_options: ClientRegistrationOptions | None = None,
+        revocation_options: RevocationOptions | None = None,
+        required_scopes: list[str] | None = None,
+    ):
+        """
+        Initialize the OAuth provider.
+
+        Args:
+            base_url: The public URL of this FastMCP server
+            resource_base_url: Optional public base URL for the protected resource.
+                When provided, the protected resource metadata and token audience are
+                derived from this URL instead of ``base_url``.
+            issuer_url: The issuer URL for OAuth metadata (defaults to base_url)
+            service_documentation_url: The URL of the service documentation.
+            client_registration_options: The client registration options.
+            revocation_options: The revocation options.
+            required_scopes: Scopes that are required for all requests.
+        """
+
+        super().__init__(
+            base_url=base_url,
+            resource_base_url=resource_base_url,
+            required_scopes=required_scopes,
+        )
+
+        if issuer_url is None:
+            self.issuer_url = self.base_url
+        elif isinstance(issuer_url, str):
+            self.issuer_url = AnyHttpUrl(issuer_url)
+        else:
+            self.issuer_url = issuer_url
+
+        # Log if issuer_url and base_url differ (requires additional setup)
+        if (
+            self.base_url is not None
+            and self.issuer_url is not None
+            and str(self.base_url) != str(self.issuer_url)
+        ):
+            logger.info(
+                f"OAuth endpoints at {self.base_url}, issuer at {self.issuer_url}. "
+                f"Ensure well-known routes are accessible at root ({self.issuer_url}/.well-known/). "
+                f"See: https://gofastmcp.com/deployment/http#mounting-authenticated-servers"
+            )
+
+        # Initialize OAuth Authorization Server Provider
+        OAuthAuthorizationServerProvider.__init__(self)
+
+        if isinstance(service_documentation_url, str):
+            service_documentation_url = AnyHttpUrl(service_documentation_url)
+
+        self.service_documentation_url = service_documentation_url
+        self.client_registration_options = client_registration_options
+        self.revocation_options = revocation_options
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """
+        Verify a bearer token and return access info if valid.
+
+        This method implements the TokenVerifier protocol by delegating
+        to our existing load_access_token method.
+
+        Args:
+            token: The token string to validate
+
+        Returns:
+            AccessToken object if valid, None if invalid or expired
+        """
+        return await self.load_access_token(token)
+
+    def get_routes(
+        self,
+        mcp_path: str | None = None,
+    ) -> list[Route]:
+        """Get OAuth authorization server routes and optional protected resource routes.
+
+        This method creates the full set of OAuth routes including:
+        - Standard OAuth authorization server routes (/.well-known/oauth-authorization-server, /authorize, /token, etc.)
+        - Optional protected resource routes
+
+        Returns:
+            List of OAuth routes
+        """
+        # Configure resource URL before creating routes
+        self.set_mcp_path(mcp_path)
+
+        # Create standard OAuth authorization server routes
+        # Pass base_url as issuer_url to ensure metadata declares endpoints where
+        # they're actually accessible (operational routes are mounted at
+        # base_url)
+        assert self.base_url is not None  # typing check
+        assert (
+            self.issuer_url is not None
+        )  # typing check (issuer_url defaults to base_url)
+
+        sdk_routes = create_auth_routes(
+            provider=self,
+            issuer_url=self.base_url,
+            service_documentation_url=self.service_documentation_url,
+            client_registration_options=self.client_registration_options,
+            revocation_options=self.revocation_options,
+        )
+
+        # Replace the token endpoint with our custom handler that returns
+        # proper OAuth 2.1 error codes (invalid_client instead of unauthorized_client)
+        oauth_routes: list[Route] = []
+        for route in sdk_routes:
+            if (
+                isinstance(route, Route)
+                and route.path == "/token"
+                and route.methods is not None
+                and "POST" in route.methods
+            ):
+                # Replace with our OAuth 2.1 compliant token handler
+                token_handler = TokenHandler(
+                    provider=self, client_authenticator=ClientAuthenticator(self)
+                )
+                oauth_routes.append(
+                    Route(
+                        path="/token",
+                        endpoint=cors_middleware(
+                            token_handler.handle, ["POST", "OPTIONS"]
+                        ),
+                        methods=["POST", "OPTIONS"],
+                    )
+                )
+            else:
+                oauth_routes.append(route)
+
+        # Add protected resource routes if this server is also acting as a resource server
+        if self._resource_url:
+            supported_scopes = (
+                self.client_registration_options.valid_scopes
+                if self.client_registration_options
+                and self.client_registration_options.valid_scopes
+                else self.required_scopes
+            )
+            protected_routes = create_protected_resource_routes(
+                resource_url=self._resource_url,
+                authorization_servers=[self.issuer_url],
+                scopes_supported=supported_scopes,
+            )
+            oauth_routes.extend(protected_routes)
+
+        # Add base routes
+        oauth_routes.extend(super().get_routes(mcp_path))
+
+        return oauth_routes
+
+    def get_well_known_routes(
+        self,
+        mcp_path: str | None = None,
+    ) -> list[Route]:
+        """Get well-known discovery routes with RFC 8414 path-aware support.
+
+        Overrides the base implementation to support path-aware authorization
+        server metadata discovery per RFC 8414. If issuer_url has a path component,
+        the authorization server metadata route is adjusted to include that path.
+
+        For example, if issuer_url is "http://example.com/api", the discovery
+        endpoint will be at "/.well-known/oauth-authorization-server/api" instead
+        of just "/.well-known/oauth-authorization-server".
+
+        Args:
+            mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
+
+        Returns:
+            List of well-known discovery routes
+        """
+        routes = super().get_well_known_routes(mcp_path)
+
+        if not self.issuer_url:
+            return routes
+
+        parsed = urlparse(str(self.issuer_url))
+        issuer_path = parsed.path.rstrip("/")
+
+        new_routes = []
+        for route in routes:
+            if route.path != "/.well-known/oauth-authorization-server":
+                new_routes.append(route)
+                continue
+
+            if issuer_path and issuer_path != "/":
+                # RFC 8414: replace base path with path-aware authorization server metadata
+                new_routes.append(
+                    Route(
+                        f"/.well-known/oauth-authorization-server{issuer_path}",
+                        endpoint=route.endpoint,
+                        methods=route.methods,
+                    )
+                )
+                # RFC 8414 §5: path-aware OIDC discovery alias
+                new_routes.append(
+                    Route(
+                        f"/.well-known/openid-configuration{issuer_path}",
+                        endpoint=route.endpoint,
+                        methods=route.methods,
+                    )
+                )
+            else:
+                # Root deployment: keep standard RFC 8414 path
+                new_routes.append(route)
+
+            # Always register /.well-known/openid-configuration regardless of path depth.
+            # Two reasons:
+            # 1. Root deployments: direct OIDC discovery alias (RFC 8414 §5 / OIDC 1.0).
+            # 2. Path-prefix reverse proxy deployments: the proxy strips the path prefix
+            #    before forwarding, so a client request for
+            #    /{prefix}/.well-known/openid-configuration arrives here as
+            #    /.well-known/openid-configuration.
+            new_routes.append(
+                Route(
+                    "/.well-known/openid-configuration",
+                    endpoint=route.endpoint,
+                    methods=route.methods,
+                )
+            )
+
+        return new_routes
diff --git a/fastmcp_slim/fastmcp/server/auth/authorization.py b/fastmcp_slim/fastmcp/server/auth/authorization.py
new file mode 100644
index 0000000..ba252f9
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/authorization.py
@@ -0,0 +1,17 @@
+"""Backward-compatible exports for component authorization primitives."""
+
+from fastmcp.utilities.authorization import (
+    AuthCheck,
+    AuthContext,
+    require_scopes,
+    restrict_tag,
+    run_auth_checks,
+)
+
+__all__ = [
+    "AuthCheck",
+    "AuthContext",
+    "require_scopes",
+    "restrict_tag",
+    "run_auth_checks",
+]
diff --git a/fastmcp_slim/fastmcp/server/auth/cimd.py b/fastmcp_slim/fastmcp/server/auth/cimd.py
new file mode 100644
index 0000000..98297c6
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/cimd.py
@@ -0,0 +1,803 @@
+"""CIMD (Client ID Metadata Document) support for FastMCP.
+
+.. warning::
+    **Beta Feature**: CIMD support is currently in beta. The API may change
+    in future releases. Please report any issues you encounter.
+
+CIMD is a simpler alternative to Dynamic Client Registration where clients
+host a static JSON document at an HTTPS URL, and that URL becomes their
+client_id. See the IETF draft: draft-parecki-oauth-client-id-metadata-document
+
+This module provides:
+- CIMDDocument: Pydantic model for CIMD document validation
+- CIMDFetcher: Fetch and validate CIMD documents with SSRF protection
+- CIMDClientManager: Manages CIMD client operations
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import timezone
+from email.utils import parsedate_to_datetime
+from typing import TYPE_CHECKING, Any, Literal
+from urllib.parse import urlparse
+
+from joserfc import jwk
+from joserfc.errors import JoseError
+from pydantic import AnyHttpUrl, BaseModel, Field, field_validator
+
+from fastmcp.server.auth.redirect_validation import matches_allowed_pattern
+from fastmcp.server.auth.ssrf import (
+    SSRFError,
+    SSRFFetchError,
+    ssrf_safe_fetch_response,
+    validate_url,
+)
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+logger = get_logger(__name__)
+
+
+def _jwk_to_pem(key_data: dict[str, Any]) -> str:
+    key_type = key_data.get("kty")
+    if key_type == "RSA":
+        return jwk.import_key(key_data, "RSA").as_pem().decode("utf-8")
+    if key_type == "EC":
+        return jwk.import_key(key_data, "EC").as_pem().decode("utf-8")
+    raise ValueError(f"Unsupported JWK key type: {key_type!r}")
+
+
+class CIMDDocument(BaseModel):
+    """CIMD document per draft-parecki-oauth-client-id-metadata-document.
+
+    The client metadata document is a JSON document containing OAuth client
+    metadata. The client_id property MUST match the URL where this document
+    is hosted.
+
+    Key constraint: token_endpoint_auth_method MUST NOT use shared secrets
+    (client_secret_post, client_secret_basic, client_secret_jwt).
+
+    redirect_uris is required and must contain at least one entry.
+    """
+
+    client_id: AnyHttpUrl = Field(
+        ...,
+        description="Must match the URL where this document is hosted",
+    )
+    client_name: str | None = Field(
+        default=None,
+        description="Human-readable name of the client",
+    )
+    client_uri: AnyHttpUrl | None = Field(
+        default=None,
+        description="URL of the client's home page",
+    )
+    logo_uri: AnyHttpUrl | None = Field(
+        default=None,
+        description="URL of the client's logo image",
+    )
+    redirect_uris: list[str] = Field(
+        ...,
+        description="Array of allowed redirect URIs (may include wildcards like http://localhost:*/callback)",
+    )
+    token_endpoint_auth_method: Literal["none", "private_key_jwt"] = Field(
+        default="none",
+        description="Authentication method for token endpoint (no shared secrets allowed)",
+    )
+    grant_types: list[str] = Field(
+        default_factory=lambda: ["authorization_code"],
+        description="OAuth grant types the client will use",
+    )
+    response_types: list[str] = Field(
+        default_factory=lambda: ["code"],
+        description="OAuth response types the client will use",
+    )
+    scope: str | None = Field(
+        default=None,
+        description="Space-separated list of scopes the client may request",
+    )
+    contacts: list[str] | None = Field(
+        default=None,
+        description="Contact information for the client developer",
+    )
+    tos_uri: AnyHttpUrl | None = Field(
+        default=None,
+        description="URL of the client's terms of service",
+    )
+    policy_uri: AnyHttpUrl | None = Field(
+        default=None,
+        description="URL of the client's privacy policy",
+    )
+    jwks_uri: AnyHttpUrl | None = Field(
+        default=None,
+        description="URL of the client's JSON Web Key Set (for private_key_jwt)",
+    )
+    jwks: dict[str, Any] | None = Field(
+        default=None,
+        description="Client's JSON Web Key Set (for private_key_jwt)",
+    )
+    software_id: str | None = Field(
+        default=None,
+        description="Unique identifier for the client software",
+    )
+    software_version: str | None = Field(
+        default=None,
+        description="Version of the client software",
+    )
+
+    @field_validator("token_endpoint_auth_method")
+    @classmethod
+    def validate_auth_method(cls, v: str) -> str:
+        """Ensure no shared-secret auth methods are used."""
+        forbidden = {"client_secret_post", "client_secret_basic", "client_secret_jwt"}
+        if v in forbidden:
+            raise ValueError(
+                f"CIMD documents cannot use shared-secret auth methods: {v}. "
+                "Use 'none' or 'private_key_jwt' instead."
+            )
+        return v
+
+    @field_validator("redirect_uris")
+    @classmethod
+    def validate_redirect_uris(cls, v: list[str]) -> list[str]:
+        """Ensure redirect_uris is non-empty and each entry is a valid URI."""
+        if not v:
+            raise ValueError("CIMD documents must include at least one redirect_uri")
+        for uri in v:
+            if not uri or not uri.strip():
+                raise ValueError("CIMD redirect_uris must be non-empty strings")
+            parsed = urlparse(uri)
+            if not parsed.scheme:
+                raise ValueError(
+                    f"CIMD redirect_uri must have a scheme (e.g. http:// or https://): {uri!r}"
+                )
+            if not parsed.netloc and not uri.startswith("urn:"):
+                raise ValueError(f"CIMD redirect_uri must have a host: {uri!r}")
+        return v
+
+
+class CIMDValidationError(Exception):
+    """Raised when CIMD document validation fails."""
+
+
+class CIMDFetchError(Exception):
+    """Raised when CIMD document fetching fails."""
+
+
+@dataclass
+class _CIMDCacheEntry:
+    """Cached CIMD document and associated HTTP cache metadata."""
+
+    doc: CIMDDocument
+    etag: str | None
+    last_modified: str | None
+    expires_at: float
+    freshness_lifetime: float
+    must_revalidate: bool
+
+
+@dataclass
+class _CIMDCachePolicy:
+    """Normalized cache directives parsed from HTTP response headers."""
+
+    etag: str | None
+    last_modified: str | None
+    expires_at: float
+    freshness_lifetime: float
+    no_store: bool
+    must_revalidate: bool
+
+
+class CIMDFetcher:
+    """Fetch and validate CIMD documents with SSRF protection.
+
+    Delegates HTTP fetching to ssrf_safe_fetch_response, which provides DNS
+    pinning, IP validation, size limits, and timeout enforcement. Documents are
+    cached using HTTP caching semantics (Cache-Control/ETag/Last-Modified), with
+    a TTL fallback when response headers do not define caching behavior.
+    """
+
+    # Maximum response size (bytes)
+    MAX_RESPONSE_SIZE = 5120  # 5KB
+    # Default cache TTL (seconds)
+    DEFAULT_CACHE_TTL_SECONDS = 3600
+
+    def __init__(
+        self,
+        timeout: float = 10.0,
+    ):
+        """Initialize the CIMD fetcher.
+
+        Args:
+            timeout: HTTP request timeout in seconds (default 10.0)
+        """
+        self.timeout = timeout
+        self._cache: dict[str, _CIMDCacheEntry] = {}
+
+    def _parse_cache_policy(
+        self, headers: Mapping[str, str], now: float
+    ) -> _CIMDCachePolicy:
+        """Parse HTTP cache headers and derive cache behavior."""
+        normalized = {k.lower(): v for k, v in headers.items()}
+        cache_control = normalized.get("cache-control", "")
+        directives = {
+            part.strip().lower() for part in cache_control.split(",") if part.strip()
+        }
+
+        no_store = "no-store" in directives
+        must_revalidate = "no-cache" in directives
+        max_age: int | None = None
+
+        for directive in directives:
+            if directive.startswith("max-age="):
+                value = directive.removeprefix("max-age=").strip()
+                try:
+                    max_age = max(0, int(value))
+                except ValueError:
+                    logger.debug(
+                        "Ignoring invalid Cache-Control max-age value: %s", value
+                    )
+                break
+
+        expires_at: float | None = None
+        if max_age is not None:
+            expires_at = now + max_age
+        elif "expires" in normalized:
+            try:
+                dt = parsedate_to_datetime(normalized["expires"])
+                if dt.tzinfo is None:
+                    dt = dt.replace(tzinfo=timezone.utc)
+                expires_at = dt.timestamp()
+            except (TypeError, ValueError):
+                logger.debug(
+                    "Ignoring invalid Expires header on CIMD response: %s",
+                    normalized["expires"],
+                )
+
+        if expires_at is None:
+            expires_at = now + self.DEFAULT_CACHE_TTL_SECONDS
+        freshness_lifetime = max(0.0, expires_at - now)
+
+        return _CIMDCachePolicy(
+            etag=normalized.get("etag"),
+            last_modified=normalized.get("last-modified"),
+            expires_at=expires_at,
+            freshness_lifetime=freshness_lifetime,
+            no_store=no_store,
+            must_revalidate=must_revalidate,
+        )
+
+    def _has_freshness_headers(self, headers: Mapping[str, str]) -> bool:
+        """Return True when response includes cache freshness directives."""
+        normalized = {k.lower() for k in headers}
+        return "cache-control" in normalized or "expires" in normalized
+
+    def is_cimd_client_id(self, client_id: str) -> bool:
+        """Check if a client_id looks like a CIMD URL.
+
+        CIMD URLs must be HTTPS with a host and non-root path.
+        """
+        if not client_id:
+            return False
+        try:
+            parsed = urlparse(client_id)
+            return (
+                parsed.scheme == "https"
+                and bool(parsed.netloc)
+                and parsed.path not in ("", "/")
+            )
+        except (ValueError, AttributeError):
+            return False
+
+    async def fetch(self, client_id_url: str) -> CIMDDocument:
+        """Fetch and validate a CIMD document with SSRF protection.
+
+        Uses ssrf_safe_fetch_response for the HTTP layer, which provides:
+        - HTTPS only, DNS resolution with IP validation
+        - DNS pinning (connects to validated IP directly)
+        - Blocks private/loopback/link-local/multicast IPs
+        - Response size limit and timeout enforcement
+        - Redirects disabled
+
+        Args:
+            client_id_url: The URL to fetch (also the expected client_id)
+
+        Returns:
+            Validated CIMDDocument
+
+        Raises:
+            CIMDValidationError: If document is invalid or URL blocked
+            CIMDFetchError: If document cannot be fetched
+        """
+        cached = self._cache.get(client_id_url)
+        now = time.time()
+        request_headers: dict[str, str] | None = None
+        allowed_status_codes = {200}
+
+        if cached is not None:
+            if not cached.must_revalidate and now < cached.expires_at:
+                return cached.doc
+
+            request_headers = {}
+            if cached.etag:
+                request_headers["If-None-Match"] = cached.etag
+            if cached.last_modified:
+                request_headers["If-Modified-Since"] = cached.last_modified
+            if request_headers:
+                allowed_status_codes = {200, 304}
+
+        try:
+            response = await ssrf_safe_fetch_response(
+                client_id_url,
+                require_path=True,
+                max_size=self.MAX_RESPONSE_SIZE,
+                timeout=self.timeout,
+                overall_timeout=30.0,
+                request_headers=request_headers,
+                allowed_status_codes=allowed_status_codes,
+            )
+        except SSRFError as e:
+            raise CIMDValidationError(str(e)) from e
+        except SSRFFetchError as e:
+            raise CIMDFetchError(str(e)) from e
+
+        if response.status_code == 304:
+            if cached is None:
+                raise CIMDFetchError(
+                    "CIMD server returned 304 Not Modified without cached document"
+                )
+
+            now = time.time()
+            if self._has_freshness_headers(response.headers):
+                policy = self._parse_cache_policy(response.headers, now)
+            else:
+                # RFC allows 304 to omit unchanged headers. Preserve existing
+                # cache policy rather than resetting to fallback defaults.
+                policy = _CIMDCachePolicy(
+                    etag=None,
+                    last_modified=None,
+                    expires_at=now + cached.freshness_lifetime,
+                    freshness_lifetime=cached.freshness_lifetime,
+                    no_store=False,
+                    must_revalidate=cached.must_revalidate,
+                )
+
+            if not policy.no_store:
+                self._cache[client_id_url] = _CIMDCacheEntry(
+                    doc=cached.doc,
+                    etag=policy.etag or cached.etag,
+                    last_modified=policy.last_modified or cached.last_modified,
+                    expires_at=policy.expires_at,
+                    freshness_lifetime=policy.freshness_lifetime,
+                    must_revalidate=policy.must_revalidate,
+                )
+            else:
+                self._cache.pop(client_id_url, None)
+            return cached.doc
+
+        now = time.time()
+        policy = self._parse_cache_policy(response.headers, now)
+
+        try:
+            data = json.loads(response.content)
+        except json.JSONDecodeError as e:
+            raise CIMDValidationError(f"CIMD document is not valid JSON: {e}") from e
+
+        try:
+            doc = CIMDDocument.model_validate(data)
+        except Exception as e:
+            raise CIMDValidationError(f"Invalid CIMD document: {e}") from e
+
+        if str(doc.client_id).rstrip("/") != client_id_url.rstrip("/"):
+            raise CIMDValidationError(
+                f"CIMD client_id mismatch: document says '{doc.client_id}' "
+                f"but was fetched from '{client_id_url}'"
+            )
+
+        # Validate jwks_uri if present (SSRF check for JWKS endpoint)
+        if doc.jwks_uri:
+            jwks_uri_str = str(doc.jwks_uri)
+            try:
+                await validate_url(jwks_uri_str)
+            except SSRFError as e:
+                raise CIMDValidationError(
+                    f"CIMD jwks_uri failed SSRF validation: {e}"
+                ) from e
+
+        logger.info(
+            "CIMD document fetched and validated: %s (client_name=%s)",
+            client_id_url,
+            doc.client_name,
+        )
+
+        if not policy.no_store:
+            self._cache[client_id_url] = _CIMDCacheEntry(
+                doc=doc,
+                etag=policy.etag,
+                last_modified=policy.last_modified,
+                expires_at=policy.expires_at,
+                freshness_lifetime=policy.freshness_lifetime,
+                must_revalidate=policy.must_revalidate,
+            )
+        else:
+            self._cache.pop(client_id_url, None)
+
+        return doc
+
+    def validate_redirect_uri(self, doc: CIMDDocument, redirect_uri: str) -> bool:
+        """Validate that a redirect_uri is allowed by the CIMD document.
+
+        Uses component-level matching (scheme, host, port, path) which correctly
+        handles RFC 8252 §7.3 loopback port flexibility and wildcard patterns.
+
+        Args:
+            doc: The CIMD document
+            redirect_uri: The redirect URI to validate
+
+        Returns:
+            True if valid, False otherwise
+        """
+        if not doc.redirect_uris:
+            # No redirect_uris specified - reject all
+            return False
+
+        # Normalize for comparison
+        redirect_uri = redirect_uri.rstrip("/")
+
+        for allowed in doc.redirect_uris:
+            allowed_str = allowed.rstrip("/")
+            if matches_allowed_pattern(redirect_uri, allowed_str):
+                return True
+
+        return False
+
+
+class CIMDAssertionValidator:
+    """Validates JWT assertions for private_key_jwt CIMD clients.
+
+    Implements RFC 7523 (JSON Web Token (JWT) Profile for OAuth 2.0 Client
+    Authentication and Authorization Grants) for CIMD client authentication.
+
+    JTI replay protection uses TTL-based caching to ensure proper security:
+    - JTIs are cached with expiration matching the JWT's exp claim
+    - Expired JTIs are automatically cleaned up
+    - Maximum assertion lifetime is enforced (5 minutes)
+    """
+
+    # Maximum allowed assertion lifetime in seconds (RFC 7523 recommends short-lived)
+    MAX_ASSERTION_LIFETIME = 300  # 5 minutes
+
+    def __init__(self):
+        # JTI cache: maps jti -> expiration timestamp
+        self._jti_cache: dict[str, float] = {}
+        self._jti_cache_max_size = 10000
+        self._last_cleanup = time.monotonic()
+        self._cleanup_interval = 60  # Cleanup every 60 seconds
+        # Cache JWTVerifier per jwks_uri so JWKS keys are not re-fetched
+        # on every token exchange
+        self._verifier_cache: dict[str, JWTVerifier] = {}
+        self._verifier_cache_max_size = 100
+        self.logger = get_logger(__name__)
+
+    def _cleanup_expired_jtis(self) -> None:
+        """Remove expired JTIs from cache."""
+        now = time.time()
+        expired = [jti for jti, exp in self._jti_cache.items() if exp < now]
+        for jti in expired:
+            del self._jti_cache[jti]
+        if expired:
+            self.logger.debug("Cleaned up %d expired JTIs from cache", len(expired))
+
+    def _maybe_cleanup(self) -> None:
+        """Periodically cleanup expired JTIs to prevent unbounded growth."""
+        now = time.monotonic()
+        if now - self._last_cleanup > self._cleanup_interval:
+            self._cleanup_expired_jtis()
+            self._last_cleanup = now
+
+    async def validate_assertion(
+        self,
+        assertion: str,
+        client_id: str,
+        token_endpoint: str,
+        cimd_doc: CIMDDocument,
+    ) -> bool:
+        """Validate JWT assertion from client.
+
+        Args:
+            assertion: The JWT assertion string
+            client_id: Expected client_id (must match iss and sub claims)
+            token_endpoint: Token endpoint URL (must match aud claim)
+            cimd_doc: CIMD document containing JWKS for key verification
+
+        Returns:
+            True if valid
+
+        Raises:
+            ValueError: If validation fails
+        """
+        from fastmcp.server.auth.providers.jwt import JWTVerifier as _JWTVerifier
+
+        # Periodic cleanup of expired JTIs
+        self._maybe_cleanup()
+
+        # 1. Validate CIMD document has key material and get/create verifier
+        if cimd_doc.jwks_uri:
+            jwks_uri_str = str(cimd_doc.jwks_uri)
+            cache_key = f"{jwks_uri_str}|{client_id}|{token_endpoint}"
+            verifier = self._verifier_cache.get(cache_key)
+            if verifier is None:
+                verifier = _JWTVerifier(
+                    jwks_uri=jwks_uri_str,
+                    issuer=client_id,
+                    audience=token_endpoint,
+                    ssrf_safe=True,
+                )
+                if len(self._verifier_cache) >= self._verifier_cache_max_size:
+                    oldest_key = next(iter(self._verifier_cache))
+                    del self._verifier_cache[oldest_key]
+                self._verifier_cache[cache_key] = verifier
+        elif cimd_doc.jwks:
+            # Inline JWKS — no caching since the key is embedded
+            public_key = self._extract_public_key_from_jwks(assertion, cimd_doc.jwks)
+            verifier = _JWTVerifier(
+                public_key=public_key,
+                issuer=client_id,
+                audience=token_endpoint,
+            )
+        else:
+            raise ValueError(
+                "CIMD document must have jwks_uri or jwks for private_key_jwt"
+            )
+
+        # 2. Verify JWT using JWTVerifier (handles signature, exp, iss, aud)
+        access_token = await verifier.load_access_token(assertion)
+        if not access_token:
+            raise ValueError("Invalid JWT assertion")
+
+        claims = access_token.claims
+
+        # 3. Validate assertion lifetime (exp and iat)
+        now = time.time()
+        exp = claims.get("exp")
+        iat = claims.get("iat")
+
+        if not exp:
+            raise ValueError("Assertion must include exp claim")
+
+        # Validate exp is in the future (with small clock skew tolerance)
+        if exp < now - 30:  # 30 second clock skew tolerance
+            raise ValueError("Assertion has expired")
+
+        # If iat is present, validate it and check assertion lifetime
+        if iat:
+            if iat > now + 30:  # 30 second clock skew tolerance
+                raise ValueError("Assertion iat is in the future")
+            if exp - iat > self.MAX_ASSERTION_LIFETIME:
+                raise ValueError(
+                    f"Assertion lifetime too long: {exp - iat}s (max {self.MAX_ASSERTION_LIFETIME}s)"
+                )
+        else:
+            # No iat, enforce max lifetime from now
+            if exp > now + self.MAX_ASSERTION_LIFETIME:
+                raise ValueError(
+                    f"Assertion exp too far in future (max {self.MAX_ASSERTION_LIFETIME}s)"
+                )
+
+        # 4. Additional RFC 7523 validation: sub claim must equal client_id
+        if claims.get("sub") != client_id:
+            raise ValueError(f"Assertion sub claim must be {client_id}")
+
+        # 5. Check jti for replay attacks (RFC 7523 requirement)
+        jti = claims.get("jti")
+        if not jti:
+            raise ValueError("Assertion must include jti claim")
+
+        # Check if JTI was already used (and hasn't expired from cache)
+        if jti in self._jti_cache:
+            cached_exp = self._jti_cache[jti]
+            if cached_exp > now:  # Still valid in cache
+                raise ValueError(f"Assertion replay detected: jti {jti} already used")
+            # Expired in cache, can be reused (clean it up)
+            del self._jti_cache[jti]
+
+        # Add to cache with expiration time
+        # Use the assertion's exp claim so it stays cached until it would expire anyway
+        self._jti_cache[jti] = exp
+
+        # Emergency size limit (shouldn't hit with proper TTL cleanup)
+        if len(self._jti_cache) > self._jti_cache_max_size:
+            self._cleanup_expired_jtis()
+            # If still over limit after cleanup, reject to prevent DoS
+            if len(self._jti_cache) > self._jti_cache_max_size:
+                self.logger.warning(
+                    "JTI cache at max capacity (%d), possible attack",
+                    self._jti_cache_max_size,
+                )
+                raise ValueError("Server overloaded, please retry")
+
+        self.logger.debug(
+            "JWT assertion validated successfully for client %s", client_id
+        )
+        return True
+
+    def _extract_public_key_from_jwks(self, token: str, jwks: dict) -> str:
+        """Extract public key from inline JWKS.
+
+        Args:
+            token: JWT token to extract kid from
+            jwks: JWKS document containing keys
+
+        Returns:
+            PEM-encoded public key
+
+        Raises:
+            ValueError: If key cannot be found or extracted
+        """
+        # Extract kid from token header
+        try:
+            header_b64 = token.split(".")[0]
+            header_b64 += "=" * (4 - len(header_b64) % 4)  # Add padding
+            header = json.loads(base64.urlsafe_b64decode(header_b64))
+            kid = header.get("kid")
+        except (IndexError, ValueError, json.JSONDecodeError) as e:
+            raise ValueError(f"Failed to extract key ID from token: {e}") from e
+
+        # Find matching key in JWKS
+        keys = jwks.get("keys", [])
+        if not keys:
+            raise ValueError("JWKS document contains no keys")
+
+        matching_key = None
+        for key in keys:
+            if kid and key.get("kid") == kid:
+                matching_key = key
+                break
+
+        if not matching_key:
+            # If no kid match, try first key as fallback
+            if len(keys) == 1:
+                matching_key = keys[0]
+                self.logger.warning(
+                    "No matching kid in JWKS, using single available key"
+                )
+            else:
+                raise ValueError(f"No matching key found for kid={kid} in JWKS")
+
+        # Convert JWK to PEM
+        try:
+            return _jwk_to_pem(matching_key)
+        except (JoseError, TypeError, ValueError) as e:
+            raise ValueError(f"Failed to convert JWK to PEM: {e}") from e
+
+
+class CIMDClientManager:
+    """Manages all CIMD client operations for OAuth proxy.
+
+    This class encapsulates:
+    - CIMD client detection
+    - Document fetching and validation
+    - Synthetic OAuth client creation
+    - Private key JWT assertion validation
+
+    This allows the OAuth proxy to delegate all CIMD-specific logic to a
+    single, focused manager class.
+    """
+
+    def __init__(
+        self,
+        enable_cimd: bool = True,
+        default_scope: str = "",
+        allowed_redirect_uri_patterns: list[str] | None = None,
+    ):
+        """Initialize CIMD client manager.
+
+        Args:
+            enable_cimd: Whether CIMD support is enabled
+            default_scope: Default scope for CIMD clients if not specified in document
+            allowed_redirect_uri_patterns: Allowed redirect URI patterns (proxy's config)
+        """
+        self.enabled = enable_cimd
+        self.default_scope = default_scope
+        self.allowed_redirect_uri_patterns = allowed_redirect_uri_patterns
+
+        self._fetcher = CIMDFetcher()
+        self._assertion_validator = CIMDAssertionValidator()
+        self.logger = get_logger(__name__)
+
+    def is_cimd_client_id(self, client_id: str) -> bool:
+        """Check if client_id is a CIMD URL.
+
+        Args:
+            client_id: Client ID to check
+
+        Returns:
+            True if client_id is an HTTPS URL (CIMD format)
+        """
+        return self.enabled and self._fetcher.is_cimd_client_id(client_id)
+
+    async def get_client(self, client_id_url: str):
+        """Fetch CIMD document and create synthetic OAuth client.
+
+        Args:
+            client_id_url: HTTPS URL pointing to CIMD document
+
+        Returns:
+            OAuthProxyClient with CIMD document attached, or None if fetch fails
+
+        Note:
+            Return type is left untyped to avoid circular import with oauth_proxy.
+            Returns OAuthProxyClient instance or None.
+        """
+        if not self.enabled:
+            return None
+
+        try:
+            cimd_doc = await self._fetcher.fetch(client_id_url)
+        except (CIMDFetchError, CIMDValidationError) as e:
+            self.logger.warning("CIMD fetch failed for %s: %s", client_id_url, e)
+            return None
+
+        # Import here to avoid circular dependency
+        from fastmcp.server.auth.oauth_proxy.models import ProxyDCRClient
+
+        # Create synthetic client from CIMD document.
+        # Keep CIMD redirect_uris as strings on the document itself so wildcard
+        # patterns like http://localhost:*/callback remain valid.
+        redirect_uris = None
+        client = ProxyDCRClient(
+            client_id=client_id_url,
+            client_secret=None,
+            redirect_uris=redirect_uris,
+            grant_types=cimd_doc.grant_types,
+            scope=cimd_doc.scope or self.default_scope,
+            token_endpoint_auth_method=cimd_doc.token_endpoint_auth_method,
+            allowed_redirect_uri_patterns=self.allowed_redirect_uri_patterns,
+            client_name=cimd_doc.client_name,
+            cimd_document=cimd_doc,
+            cimd_fetched_at=time.time(),
+        )
+
+        self.logger.debug(
+            "CIMD client resolved: %s (name=%s)",
+            client_id_url,
+            cimd_doc.client_name,
+        )
+        return client
+
+    async def validate_private_key_jwt(
+        self,
+        assertion: str,
+        client,  # OAuthProxyClient, untyped to avoid circular import
+        token_endpoint: str,
+    ) -> bool:
+        """Validate JWT assertion for private_key_jwt auth.
+
+        Args:
+            assertion: JWT assertion string from client
+            client: OAuth proxy client (must have cimd_document)
+            token_endpoint: Token endpoint URL for aud validation
+
+        Returns:
+            True if assertion is valid
+
+        Raises:
+            ValueError: If client doesn't have CIMD document or validation fails
+        """
+        if not hasattr(client, "cimd_document") or not client.cimd_document:
+            raise ValueError("Client must have CIMD document for private_key_jwt")
+
+        cimd_doc = client.cimd_document
+        if cimd_doc.token_endpoint_auth_method != "private_key_jwt":
+            raise ValueError("CIMD document must specify private_key_jwt auth method")
+
+        return await self._assertion_validator.validate_assertion(
+            assertion, client.client_id, token_endpoint, cimd_doc
+        )
diff --git a/fastmcp_slim/fastmcp/server/auth/handlers/__init__.py b/fastmcp_slim/fastmcp/server/auth/handlers/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/fastmcp_slim/fastmcp/server/auth/handlers/authorize.py b/fastmcp_slim/fastmcp/server/auth/handlers/authorize.py
new file mode 100644
index 0000000..f91b266
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/handlers/authorize.py
@@ -0,0 +1,326 @@
+"""Enhanced authorization handler with improved error responses.
+
+This module provides an enhanced authorization handler that wraps the MCP SDK's
+AuthorizationHandler to provide better error messages when clients attempt to
+authorize with unregistered client IDs.
+
+The enhancement adds:
+- Content negotiation: HTML for browsers, JSON for API clients
+- Enhanced JSON responses with registration endpoint hints
+- Styled HTML error pages with registration links/forms
+- Link headers pointing to registration endpoints
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from mcp.server.auth.handlers.authorize import (
+    AuthorizationHandler as SDKAuthorizationHandler,
+)
+from pydantic import AnyHttpUrl
+from starlette.requests import Request
+from starlette.responses import Response
+
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.ui import (
+    INFO_BOX_STYLES,
+    TOOLTIP_STYLES,
+    create_logo,
+    create_page,
+    create_secure_html_response,
+)
+
+if TYPE_CHECKING:
+    from mcp.server.auth.provider import OAuthAuthorizationServerProvider
+
+logger = get_logger(__name__)
+
+
+def create_unregistered_client_html(
+    client_id: str,
+    registration_endpoint: str,
+    discovery_endpoint: str,
+    server_name: str | None = None,
+    server_icon_url: str | None = None,
+    title: str = "Client Not Registered",
+) -> str:
+    """Create styled HTML error page for unregistered client attempts.
+
+    Args:
+        client_id: The unregistered client ID that was provided
+        registration_endpoint: URL of the registration endpoint
+        discovery_endpoint: URL of the OAuth metadata discovery endpoint
+        server_name: Optional server name for branding
+        server_icon_url: Optional server icon URL
+        title: Page title
+
+    Returns:
+        HTML string for the error page
+    """
+    import html as html_module
+
+    client_id_escaped = html_module.escape(client_id)
+
+    # Main error message
+    error_box = f"""
+        <div class="info-box error">
+            <p>The client ID <code>{client_id_escaped}</code> was not found in the server's client registry.</p>
+        </div>
+    """
+
+    # What to do - yellow warning box
+    warning_box = """
+        <div class="info-box warning">
+            <p>Your MCP client opened this page to complete OAuth authorization,
+            but the server did not recognize its client ID. To fix this:</p>
+            <ul>
+                <li>Close this browser window</li>
+                <li>Clear authentication tokens in your MCP client (or restart it)</li>
+                <li>Try connecting again - your client should automatically re-register</li>
+            </ul>
+        </div>
+    """
+
+    # Help link with tooltip (similar to consent screen)
+    help_link = """
+        <div class="help-link-container">
+            <span class="help-link">
+                Why am I seeing this?
+                <span class="tooltip">
+                    OAuth 2.0 requires clients to register before authorization.
+                    This server returned a 400 error because the provided client
+                    ID was not found.
+                    <br><br>
+                    In browser-delegated OAuth flows, your application cannot
+                    detect this error automatically; it's waiting for a
+                    callback that will never arrive. You must manually clear
+                    auth tokens and reconnect.
+                </span>
+            </span>
+        </div>
+    """
+
+    # Build page content
+    content = f"""
+        <div class="container">
+            {create_logo(icon_url=server_icon_url, alt_text=server_name or "FastMCP")}
+            <h1>{title}</h1>
+            {error_box}
+            {warning_box}
+        </div>
+        {help_link}
+    """
+
+    # Use same styles as consent page
+    additional_styles = (
+        INFO_BOX_STYLES
+        + TOOLTIP_STYLES
+        + """
+        /* Error variant for info-box */
+        .info-box.error {
+            background: #fef2f2;
+            border-color: #f87171;
+        }
+        .info-box.error strong {
+            color: #991b1b;
+        }
+        /* Warning variant for info-box (yellow) */
+        .info-box.warning {
+            background: #fffbeb;
+            border-color: #fbbf24;
+        }
+        .info-box.warning strong {
+            color: #92400e;
+        }
+        .info-box code {
+            background: rgba(0, 0, 0, 0.05);
+            padding: 2px 6px;
+            border-radius: 3px;
+            font-family: 'SF Mono', Monaco, 'Cascadia Code', monospace;
+            font-size: 0.9em;
+        }
+        .info-box ul {
+            margin: 10px 0;
+            padding-left: 20px;
+        }
+        .info-box li {
+            margin: 6px 0;
+        }
+        """
+    )
+
+    return create_page(
+        content=content,
+        title=title,
+        additional_styles=additional_styles,
+    )
+
+
+class AuthorizationHandler(SDKAuthorizationHandler):
+    """Authorization handler with enhanced error responses for unregistered clients.
+
+    This handler extends the MCP SDK's AuthorizationHandler to provide better UX
+    when clients attempt to authorize without being registered. It implements
+    content negotiation to return:
+
+    - HTML error pages for browser requests
+    - Enhanced JSON with registration hints for API clients
+    - Link headers pointing to registration endpoints
+
+    This maintains OAuth 2.1 compliance (returns 400 for invalid client_id)
+    while providing actionable guidance to fix the error.
+    """
+
+    def __init__(
+        self,
+        provider: OAuthAuthorizationServerProvider,
+        base_url: AnyHttpUrl | str,
+        server_name: str | None = None,
+        server_icon_url: str | None = None,
+    ):
+        """Initialize the enhanced authorization handler.
+
+        Args:
+            provider: OAuth authorization server provider
+            base_url: Base URL of the server for constructing endpoint URLs
+            server_name: Optional server name for branding
+            server_icon_url: Optional server icon URL for branding
+        """
+        super().__init__(provider)
+        self._base_url = str(base_url).rstrip("/")
+        self._server_name = server_name
+        self._server_icon_url = server_icon_url
+
+    async def handle(self, request: Request) -> Response:
+        """Handle authorization request with enhanced error responses.
+
+        This method extends the SDK's authorization handler and intercepts
+        errors for unregistered clients to provide better error responses
+        based on the client's Accept header.
+
+        Args:
+            request: The authorization request
+
+        Returns:
+            Response (redirect on success, error response on failure)
+        """
+        # Call the SDK handler
+        response = await super().handle(request)
+
+        # Check if this is a client not found error
+        if response.status_code == 400:
+            # Try to extract client_id from request for enhanced error
+            client_id: str | None = None
+            if request.method == "GET":
+                client_id = request.query_params.get("client_id")
+            else:
+                form = await request.form()
+                client_id_value = form.get("client_id")
+                # Ensure client_id is a string, not UploadFile
+                if isinstance(client_id_value, str):
+                    client_id = client_id_value
+
+            # If we have a client_id and the error is about it not being found,
+            # enhance the response
+            if client_id:
+                try:
+                    # Check if response body contains "not found" error
+                    if hasattr(response, "body"):
+                        body = json.loads(bytes(response.body))
+                        if (
+                            body.get("error") == "invalid_request"
+                            and "not found" in body.get("error_description", "").lower()
+                        ):
+                            return await self._create_enhanced_error_response(
+                                request, client_id, body.get("state")
+                            )
+                except Exception:
+                    # If we can't parse the response, just return the original
+                    pass
+
+        return response
+
+    async def _create_enhanced_error_response(
+        self, request: Request, client_id: str, state: str | None
+    ) -> Response:
+        """Create enhanced error response with content negotiation.
+
+        Args:
+            request: The original request
+            client_id: The unregistered client ID
+            state: The state parameter from the request
+
+        Returns:
+            HTML or JSON error response based on Accept header
+        """
+        registration_endpoint = f"{self._base_url}/register"
+        discovery_endpoint = f"{self._base_url}/.well-known/oauth-authorization-server"
+
+        # Extract server metadata from app state (same pattern as consent screen)
+        from fastmcp.server.server import FastMCP
+
+        fastmcp = getattr(request.app.state, "fastmcp_server", None)
+
+        if isinstance(fastmcp, FastMCP):
+            server_name = fastmcp.name
+            icons = fastmcp.icons
+            server_icon_url = icons[0].src if icons else None
+        else:
+            server_name = self._server_name
+            server_icon_url = self._server_icon_url
+
+        # Check Accept header for content negotiation
+        accept = request.headers.get("accept", "")
+
+        # Prefer HTML for browsers
+        if "text/html" in accept:
+            html = create_unregistered_client_html(
+                client_id=client_id,
+                registration_endpoint=registration_endpoint,
+                discovery_endpoint=discovery_endpoint,
+                server_name=server_name,
+                server_icon_url=server_icon_url,
+            )
+            response = create_secure_html_response(html, status_code=400)
+        else:
+            # Return enhanced JSON for API clients
+            from mcp.server.auth.handlers.authorize import AuthorizationErrorResponse
+
+            error_data = AuthorizationErrorResponse(
+                error="invalid_request",
+                error_description=(
+                    f"Client ID '{client_id}' is not registered with this server. "
+                    f"MCP clients should automatically re-register by sending a POST request to "
+                    f"the registration_endpoint and retry authorization. "
+                    f"If this persists, clear cached authentication tokens and reconnect."
+                ),
+                state=state,
+            )
+
+            # Add extra fields to help clients discover registration
+            error_dict = error_data.model_dump(exclude_none=True)
+            error_dict["registration_endpoint"] = registration_endpoint
+            error_dict["authorization_server_metadata"] = discovery_endpoint
+
+            from starlette.responses import JSONResponse
+
+            response = JSONResponse(
+                status_code=400,
+                content=error_dict,
+                headers={"Cache-Control": "no-store"},
+            )
+
+        # Add Link header for registration endpoint discovery
+        response.headers["Link"] = (
+            f'<{registration_endpoint}>; rel="http://oauth.net/core/2.1/#registration"'
+        )
+
+        logger.info(
+            "Unregistered client_id=%s, returned %s error response",
+            client_id,
+            "HTML" if "text/html" in accept else "JSON",
+        )
+
+        return response
diff --git a/fastmcp_slim/fastmcp/server/auth/jwt_issuer.py b/fastmcp_slim/fastmcp/server/auth/jwt_issuer.py
new file mode 100644
index 0000000..ae5c537
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/jwt_issuer.py
@@ -0,0 +1,282 @@
+"""JWT token issuance and verification for FastMCP OAuth Proxy.
+
+This module implements the token factory pattern for OAuth proxies, where the proxy
+issues its own JWT tokens to clients instead of forwarding upstream provider tokens.
+This maintains proper OAuth 2.0 token audience boundaries.
+"""
+
+from __future__ import annotations
+
+import base64
+import time
+from typing import Any, overload
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+from joserfc import jwk, jwt
+from joserfc.errors import JoseError
+
+import fastmcp
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+KDF_ITERATIONS = 1_000_000
+KDF_ITERATIONS_TEST = 10
+
+
+@overload
+def derive_jwt_key(*, high_entropy_material: str, salt: str) -> bytes:
+    """Derive JWT signing key from a high-entropy key material and server salt."""
+
+
+@overload
+def derive_jwt_key(*, low_entropy_material: str, salt: str) -> bytes:
+    """Derive JWT signing key from a low-entropy key material and server salt."""
+
+
+def derive_jwt_key(
+    *,
+    high_entropy_material: str | None = None,
+    low_entropy_material: str | None = None,
+    salt: str,
+) -> bytes:
+    """Derive JWT signing key from a high-entropy or low-entropy key material and server salt."""
+    if high_entropy_material is not None and low_entropy_material is not None:
+        raise ValueError(
+            "Either high_entropy_material or low_entropy_material must be provided, but not both"
+        )
+
+    if high_entropy_material is not None:
+        derived_key = HKDF(
+            algorithm=hashes.SHA256(),
+            length=32,
+            salt=salt.encode(),
+            info=b"Fernet",
+        ).derive(key_material=high_entropy_material.encode())
+
+        return base64.urlsafe_b64encode(derived_key)
+
+    if low_entropy_material is not None:
+        iterations = (
+            KDF_ITERATIONS_TEST if fastmcp.settings.test_mode else KDF_ITERATIONS
+        )
+        pbkdf2 = PBKDF2HMAC(
+            algorithm=hashes.SHA256(),
+            length=32,
+            salt=salt.encode(),
+            iterations=iterations,
+        ).derive(key_material=low_entropy_material.encode())
+
+        return base64.urlsafe_b64encode(pbkdf2)
+
+    raise ValueError(
+        "Either high_entropy_material or low_entropy_material must be provided"
+    )
+
+
+class JWTIssuer:
+    """Issues and validates FastMCP-signed JWT tokens using HS256.
+
+    This issuer creates JWT tokens for MCP clients with proper audience claims,
+    maintaining OAuth 2.0 token boundaries. Tokens are signed with HS256 using
+    a key derived from the upstream client secret.
+    """
+
+    def __init__(
+        self,
+        issuer: str,
+        audience: str,
+        signing_key: bytes,
+    ):
+        """Initialize JWT issuer.
+
+        Args:
+            issuer: Token issuer (FastMCP server base URL)
+            audience: Token audience (typically {base_url}/mcp)
+            signing_key: HS256 signing key (32 bytes)
+        """
+        self.issuer = issuer
+        self.audience = audience
+        self._signing_key = signing_key
+        self._jwt_key = jwk.import_key(signing_key, "oct")
+
+    def issue_access_token(
+        self,
+        client_id: str,
+        scopes: list[str],
+        jti: str,
+        expires_in: int = 3600,
+        upstream_claims: dict[str, Any] | None = None,
+    ) -> str:
+        """Issue a minimal FastMCP access token.
+
+        FastMCP tokens are reference tokens containing only the minimal claims
+        needed for validation and lookup. The JTI maps to the upstream token
+        which contains actual user identity and authorization data.
+
+        Args:
+            client_id: MCP client ID
+            scopes: Token scopes
+            jti: Unique token identifier (maps to upstream token)
+            expires_in: Token lifetime in seconds
+            upstream_claims: Optional claims from upstream IdP token to include
+
+        Returns:
+            Signed JWT token
+        """
+        now = int(time.time())
+
+        header = {"alg": "HS256", "typ": "JWT"}
+        payload: dict[str, Any] = {
+            "iss": self.issuer,
+            "aud": self.audience,
+            "client_id": client_id,
+            "scope": " ".join(scopes),
+            "exp": now + expires_in,
+            "iat": now,
+            "jti": jti,
+        }
+
+        if upstream_claims:
+            payload["upstream_claims"] = upstream_claims
+
+        token = jwt.encode(
+            header,
+            payload,
+            self._jwt_key,
+            algorithms=["HS256"],
+        )
+
+        logger.debug(
+            "Issued access token for client=%s jti=%s exp=%d",
+            client_id,
+            jti[:8],
+            payload["exp"],
+        )
+
+        return token
+
+    def issue_refresh_token(
+        self,
+        client_id: str,
+        scopes: list[str],
+        jti: str,
+        expires_in: int,
+        upstream_claims: dict[str, Any] | None = None,
+    ) -> str:
+        """Issue a minimal FastMCP refresh token.
+
+        FastMCP refresh tokens are reference tokens containing only the minimal
+        claims needed for validation and lookup. The JTI maps to the upstream
+        token which contains actual user identity and authorization data.
+
+        Args:
+            client_id: MCP client ID
+            scopes: Token scopes
+            jti: Unique token identifier (maps to upstream token)
+            expires_in: Token lifetime in seconds (should match upstream refresh expiry)
+            upstream_claims: Optional claims from upstream IdP token to include
+
+        Returns:
+            Signed JWT token
+        """
+        now = int(time.time())
+
+        header = {"alg": "HS256", "typ": "JWT"}
+        payload: dict[str, Any] = {
+            "iss": self.issuer,
+            "aud": self.audience,
+            "client_id": client_id,
+            "scope": " ".join(scopes),
+            "exp": now + expires_in,
+            "iat": now,
+            "jti": jti,
+            "token_use": "refresh",
+        }
+
+        if upstream_claims:
+            payload["upstream_claims"] = upstream_claims
+
+        token = jwt.encode(
+            header,
+            payload,
+            self._jwt_key,
+            algorithms=["HS256"],
+        )
+
+        logger.debug(
+            "Issued refresh token for client=%s jti=%s exp=%d",
+            client_id,
+            jti[:8],
+            payload["exp"],
+        )
+
+        return token
+
+    def verify_token(
+        self,
+        token: str,
+        expected_token_use: str = "access",
+    ) -> dict[str, Any]:
+        """Verify and decode a FastMCP token.
+
+        Validates JWT signature, expiration, issuer, audience, and token type.
+
+        Args:
+            token: JWT token to verify
+            expected_token_use: Expected token type ("access" or "refresh").
+                Defaults to "access", which rejects refresh tokens.
+
+        Returns:
+            Decoded token payload
+
+        Raises:
+            JoseError: If token is invalid, expired, or has wrong claims
+        """
+        try:
+            # Decode and verify signature
+            payload = jwt.decode(
+                token,
+                self._jwt_key,
+                algorithms=["HS256"],
+            ).claims
+
+            # Validate token type
+            token_use = payload.get("token_use", "access")
+            if token_use != expected_token_use:
+                logger.debug(
+                    "Token type mismatch: expected %s, got %s",
+                    expected_token_use,
+                    token_use,
+                )
+                raise JoseError(
+                    f"Token type mismatch: expected {expected_token_use}, "
+                    f"got {token_use}"
+                )
+
+            # Validate expiration
+            exp = payload.get("exp")
+            if exp is not None and exp < time.time():
+                logger.debug("Token expired")
+                raise JoseError("Token has expired")
+
+            # Validate issuer
+            if payload.get("iss") != self.issuer:
+                logger.debug("Token has invalid issuer")
+                raise JoseError("Invalid token issuer")
+
+            # Validate audience
+            if payload.get("aud") != self.audience:
+                logger.debug("Token has invalid audience")
+                raise JoseError("Invalid token audience")
+
+            logger.debug(
+                "Token verified successfully for subject=%s", payload.get("sub")
+            )
+            return payload
+
+        except JoseError as e:
+            logger.debug("Token validation failed: %s", e)
+            raise
diff --git a/fastmcp_slim/fastmcp/server/auth/middleware.py b/fastmcp_slim/fastmcp/server/auth/middleware.py
new file mode 100644
index 0000000..f0eb824
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/middleware.py
@@ -0,0 +1,179 @@
+"""Enhanced authentication middleware with better error messages.
+
+This module provides enhanced versions of MCP SDK authentication middleware
+that return more helpful error messages for developers troubleshooting
+authentication issues.
+
+Implements RFC 6750 §3.1 compliance by distinguishing between missing
+authentication (no error attribute) and invalid authentication (with error).
+"""
+
+from __future__ import annotations
+
+import json
+
+from mcp.server.auth.middleware.bearer_auth import (
+    RequireAuthMiddleware as SDKRequireAuthMiddleware,
+)
+from starlette.types import Receive, Scope, Send
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class RequireAuthMiddleware(SDKRequireAuthMiddleware):
+    """Enhanced authentication middleware with detailed error messages.
+
+    Extends the SDK's RequireAuthMiddleware to provide more actionable
+    error messages when authentication fails. This helps developers
+    understand what went wrong and how to fix it.
+
+    Also implements RFC 6750 §3.1 compliance by distinguishing between
+    missing authentication (initial discovery) and invalid authentication
+    (token validation failure).
+    """
+
+    async def __call__(
+        self,
+        scope: Scope,
+        receive: Receive,
+        send: Send,
+    ) -> None:
+        """Process ASGI scope, distinguishing missing vs invalid auth.
+
+        Per RFC 6750 §3.1:
+        - Missing auth (no Authorization header) → 401 without error attribute
+        - Invalid auth (Authorization header present) → 401 with error attribute
+
+        This ensures OAuth flow initialization works correctly in MCP clients
+        during initial discovery phase.
+
+        Args:
+            scope: ASGI scope
+            receive: ASGI receive callable
+            send: ASGI send callable
+        """
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        # Check if Authorization header is present
+        headers = scope.get("headers", [])
+        has_auth_header = any(
+            header[0].lower() == b"authorization" for header in headers
+        )
+
+        if not has_auth_header:
+            # Per RFC 6750 §3.1: missing auth should not include error attribute
+            await self._send_missing_auth(send)
+            return
+
+        # Authorization header is present - use parent's validation logic
+        # This will check token validity and call _send_auth_error if invalid
+        await super().__call__(scope, receive, send)
+
+    async def _send_missing_auth(self, send: Send) -> None:
+        """Send 401 response for missing authentication (RFC 6750 §3.1 compliant).
+
+        When a request lacks any authentication information, per RFC 6750 §3.1:
+        "If the request lacks any authentication information, the error
+        attribute SHOULD NOT be included."
+
+        This allows MCP clients to properly initiate OAuth flow during
+        initial discovery phase.
+
+        Args:
+            send: ASGI send callable
+        """
+        www_auth_parts = []
+        if self.resource_metadata_url:
+            www_auth_parts.append(f'resource_metadata="{self.resource_metadata_url}"')
+
+        www_authenticate = (
+            ("Bearer " + ", ".join(www_auth_parts)) if www_auth_parts else "Bearer"
+        )
+
+        await send(
+            {
+                "type": "http.response.start",
+                "status": 401,
+                "headers": [
+                    (b"content-length", b"0"),
+                    (b"www-authenticate", www_authenticate.encode()),
+                ],
+            }
+        )
+        await send({"type": "http.response.body", "body": b""})
+
+        logger.debug(
+            "Missing auth: sent 401 without error attribute (RFC 6750 §3.1 compliant)"
+        )
+
+    async def _send_auth_error(
+        self, send: Send, status_code: int, error: str, description: str
+    ) -> None:
+        """Send an authentication error response with enhanced error messages.
+
+        Overrides the SDK's _send_auth_error to provide more detailed
+        error descriptions that help developers troubleshoot authentication
+        issues.
+
+        Args:
+            send: ASGI send callable
+            status_code: HTTP status code (401 or 403)
+            error: OAuth error code
+            description: Base error description
+        """
+        # Enhance error descriptions based on error type
+        enhanced_description = description
+
+        if error == "invalid_token" and status_code == 401:
+            # This is the "Authentication required" error
+            enhanced_description = (
+                "Authentication failed. The provided bearer token is invalid, expired, or no longer recognized by the server. "
+                "To resolve: clear authentication tokens in your MCP client and reconnect. "
+                "Your client should automatically re-register and obtain new tokens."
+            )
+        elif error == "insufficient_scope":
+            # Scope error - already has good detail from SDK
+            pass
+
+        # Build WWW-Authenticate header value
+        www_auth_parts = [
+            f'error="{error}"',
+            f'error_description="{enhanced_description}"',
+        ]
+        if self.resource_metadata_url:
+            www_auth_parts.append(f'resource_metadata="{self.resource_metadata_url}"')
+
+        www_authenticate = f"Bearer {', '.join(www_auth_parts)}"
+
+        # Send response
+        body = {"error": error, "error_description": enhanced_description}
+        body_bytes = json.dumps(body).encode()
+
+        await send(
+            {
+                "type": "http.response.start",
+                "status": status_code,
+                "headers": [
+                    (b"content-type", b"application/json"),
+                    (b"content-length", str(len(body_bytes)).encode()),
+                    (b"www-authenticate", www_authenticate.encode()),
+                ],
+            }
+        )
+
+        await send(
+            {
+                "type": "http.response.body",
+                "body": body_bytes,
+            }
+        )
+
+        logger.info(
+            "Auth error returned: %s (status=%d)",
+            error,
+            status_code,
+        )
diff --git a/fastmcp_slim/fastmcp/server/auth/oauth_proxy/__init__.py b/fastmcp_slim/fastmcp/server/auth/oauth_proxy/__init__.py
new file mode 100644
index 0000000..5e9ff43
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/oauth_proxy/__init__.py
@@ -0,0 +1,14 @@
+"""OAuth Proxy Provider for FastMCP.
+
+This package provides OAuth proxy functionality split across multiple modules:
+- models: Pydantic models and constants
+- ui: HTML generation functions
+- consent: Consent management mixin
+- proxy: Main OAuthProxy class
+"""
+
+from fastmcp.server.auth.oauth_proxy.proxy import OAuthProxy
+
+__all__ = [
+    "OAuthProxy",
+]
diff --git a/fastmcp_slim/fastmcp/server/auth/oauth_proxy/consent.py b/fastmcp_slim/fastmcp/server/auth/oauth_proxy/consent.py
new file mode 100644
index 0000000..c251949
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/oauth_proxy/consent.py
@@ -0,0 +1,593 @@
+"""OAuth Proxy Consent Management.
+
+This module contains consent management functionality for the OAuth proxy.
+The ConsentMixin class provides methods for handling user consent flows,
+cookie management, and consent page rendering.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import secrets
+import time
+from base64 import urlsafe_b64encode
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlencode, urlparse
+
+from pydantic import AnyUrl
+from starlette.requests import Request
+from starlette.responses import HTMLResponse, RedirectResponse
+
+from fastmcp.server.auth.oauth_proxy.models import ProxyDCRClient
+from fastmcp.server.auth.oauth_proxy.ui import create_consent_html
+from fastmcp.server.auth.redirect_validation import validate_redirect_uri
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.ui import create_secure_html_response
+
+if TYPE_CHECKING:
+    from fastmcp.server.auth.oauth_proxy.proxy import OAuthProxy
+
+# Maximum number of remembered client approvals/denials stored in cookies.
+# Keeps the Cookie header bounded to avoid hitting reverse proxy header limits.
+_MAX_REMEMBERED_CLIENTS = 25
+
+logger = get_logger(__name__)
+
+
+class ConsentMixin:
+    """Mixin class providing consent management functionality for OAuthProxy.
+
+    This mixin contains all methods related to:
+    - Cookie signing and verification
+    - Consent page rendering
+    - Consent approval/denial handling
+    - URI normalization for consent tracking
+    """
+
+    def _normalize_uri(self, uri: str) -> str:
+        """Normalize a URI to a canonical form for consent tracking."""
+        parsed = urlparse(uri)
+        path = parsed.path or ""
+        normalized = f"{parsed.scheme.lower()}://{parsed.netloc.lower()}{path}"
+        if normalized.endswith("/") and len(path) > 1:
+            normalized = normalized[:-1]
+        return normalized
+
+    def _make_client_key(self, client_id: str, redirect_uri: str | AnyUrl) -> str:
+        """Create a stable key for consent tracking from client_id and redirect_uri."""
+        normalized = self._normalize_uri(str(redirect_uri))
+        return f"{client_id}:{normalized}"
+
+    def _validate_client_redirect_uri(
+        self: OAuthProxy,
+        redirect_uri: str,
+    ) -> bool:
+        """Validate a stored transaction redirect URI before sending a browser to it."""
+        return validate_redirect_uri(
+            redirect_uri=redirect_uri,
+            allowed_patterns=self._allowed_client_redirect_uris,
+        )
+
+    def _cookie_name(self: OAuthProxy, base_name: str) -> str:
+        """Return secure cookie name for HTTPS, fallback for HTTP development."""
+        if self._is_https:
+            return f"__Host-{base_name}"
+        return f"__{base_name}"
+
+    def _cookie_signing_key(self: OAuthProxy) -> bytes:
+        """Return the key used for HMAC-signing consent cookies.
+
+        Uses the upstream client secret when available, falling back to the
+        JWT signing key (which is always present — OAuthProxy requires it
+        when no client secret is provided).
+        """
+        if self._upstream_client_secret is not None:
+            return self._upstream_client_secret.get_secret_value().encode()
+        return self._jwt_signing_key
+
+    def _sign_cookie(self: OAuthProxy, payload: str) -> str:
+        """Sign a cookie payload with HMAC-SHA256.
+
+        Returns: base64(payload).base64(signature)
+        """
+        key = self._cookie_signing_key()
+        signature = hmac.new(key, payload.encode(), hashlib.sha256).digest()
+        signature_b64 = base64.b64encode(signature).decode()
+        return f"{payload}.{signature_b64}"
+
+    def _verify_cookie(self: OAuthProxy, signed_value: str) -> str | None:
+        """Verify and extract payload from signed cookie.
+
+        Returns: payload if signature valid, None otherwise
+        """
+        try:
+            if "." not in signed_value:
+                return None
+            payload, signature_b64 = signed_value.rsplit(".", 1)
+
+            # Verify signature
+            key = self._cookie_signing_key()
+            expected_sig = hmac.new(key, payload.encode(), hashlib.sha256).digest()
+            provided_sig = base64.b64decode(signature_b64.encode())
+
+            # Constant-time comparison
+            if not hmac.compare_digest(expected_sig, provided_sig):
+                return None
+
+            return payload
+        except Exception:
+            return None
+
+    def _decode_list_cookie(
+        self: OAuthProxy, request: Request, base_name: str
+    ) -> list[str]:
+        """Decode and verify a signed base64-encoded JSON list from cookie. Returns [] if missing/invalid."""
+        secure_name = self._cookie_name(base_name)
+        raw = request.cookies.get(secure_name)
+        # Only fall back to the non-__Host- name over plain HTTP. On HTTPS,
+        # __Host- enforces host-only scope; accepting the weaker name would
+        # let a sibling-subdomain attacker inject a domain-scoped cookie.
+        if not raw and not self._is_https:
+            raw = request.cookies.get(f"__{base_name}")
+        if not raw:
+            return []
+        try:
+            # Verify signature
+            payload = self._verify_cookie(raw)
+            if not payload:
+                logger.debug("Cookie signature verification failed for %s", secure_name)
+                return []
+
+            # Decode payload
+            data = base64.b64decode(payload.encode())
+            value = json.loads(data.decode())
+            if isinstance(value, list):
+                return [str(x) for x in value]
+        except Exception:
+            logger.debug("Failed to decode cookie %s; treating as empty", secure_name)
+        return []
+
+    def _encode_list_cookie(self: OAuthProxy, values: list[str]) -> str:
+        """Encode values to base64 and sign with HMAC.
+
+        Returns: signed cookie value (payload.signature)
+        """
+        payload = json.dumps(values, separators=(",", ":")).encode()
+        payload_b64 = base64.b64encode(payload).decode()
+        return self._sign_cookie(payload_b64)
+
+    def _set_list_cookie(
+        self: OAuthProxy,
+        response: HTMLResponse | RedirectResponse,
+        base_name: str,
+        value_b64: str,
+        max_age: int,
+    ) -> None:
+        name = self._cookie_name(base_name)
+        response.set_cookie(
+            name,
+            value_b64,
+            max_age=max_age,
+            secure=self._is_https,
+            httponly=True,
+            samesite="lax",
+            path="/",
+        )
+
+    def _read_consent_bindings(self: OAuthProxy, request: Request) -> dict[str, str]:
+        """Read the consent binding map from the signed cookie.
+
+        Returns a dict of {txn_id: consent_token} for all pending flows.
+        """
+        cookie_name = self._cookie_name("MCP_CONSENT_BINDING")
+        raw = request.cookies.get(cookie_name)
+        # Only fall back to the non-__Host- name over plain HTTP. On HTTPS,
+        # __Host- enforces host-only scope; accepting the weaker name would
+        # bypass that guarantee.
+        if not raw and not self._is_https:
+            raw = request.cookies.get("__MCP_CONSENT_BINDING")
+        if not raw:
+            return {}
+        payload = self._verify_cookie(raw)
+        if not payload:
+            return {}
+        try:
+            data = json.loads(base64.b64decode(payload.encode()).decode())
+            if isinstance(data, dict):
+                return {str(k): str(v) for k, v in data.items()}
+        except Exception:
+            logger.debug("Failed to decode consent binding cookie")
+        return {}
+
+    def _write_consent_bindings(
+        self: OAuthProxy,
+        response: HTMLResponse | RedirectResponse,
+        bindings: dict[str, str],
+    ) -> None:
+        """Write the consent binding map to a signed cookie."""
+        name = self._cookie_name("MCP_CONSENT_BINDING")
+        if not bindings:
+            response.set_cookie(
+                name,
+                "",
+                max_age=0,
+                secure=self._is_https,
+                httponly=True,
+                samesite="lax",
+                path="/",
+            )
+            return
+        payload_bytes = json.dumps(bindings, separators=(",", ":")).encode()
+        payload_b64 = base64.b64encode(payload_bytes).decode()
+        signed_value = self._sign_cookie(payload_b64)
+        response.set_cookie(
+            name,
+            signed_value,
+            max_age=15 * 60,
+            secure=self._is_https,
+            httponly=True,
+            samesite="lax",
+            path="/",
+        )
+
+    def _set_consent_binding_cookie(
+        self: OAuthProxy,
+        request: Request,
+        response: HTMLResponse | RedirectResponse,
+        txn_id: str,
+        consent_token: str,
+    ) -> None:
+        """Add a consent binding entry for a transaction.
+
+        This cookie binds the browser that approved consent to the IdP callback,
+        ensuring a different browser cannot complete the OAuth flow. Multiple
+        concurrent flows are supported by storing a map of txn_id → consent_token.
+        """
+        bindings = self._read_consent_bindings(request)
+        bindings[txn_id] = consent_token
+        self._write_consent_bindings(response, bindings)
+
+    def _clear_consent_binding_cookie(
+        self: OAuthProxy,
+        request: Request,
+        response: HTMLResponse | RedirectResponse,
+        txn_id: str,
+    ) -> None:
+        """Remove a specific consent binding entry after successful callback."""
+        bindings = self._read_consent_bindings(request)
+        bindings.pop(txn_id, None)
+        self._write_consent_bindings(response, bindings)
+
+    def _verify_consent_binding_cookie(
+        self: OAuthProxy,
+        request: Request,
+        txn_id: str,
+        expected_token: str,
+    ) -> bool:
+        """Verify the consent binding for a specific transaction."""
+        bindings = self._read_consent_bindings(request)
+        actual = bindings.get(txn_id)
+        if not actual:
+            return False
+        return hmac.compare_digest(actual, expected_token)
+
+    def _build_upstream_authorize_url(
+        self: OAuthProxy, txn_id: str, transaction: dict[str, Any]
+    ) -> str:
+        """Construct the upstream IdP authorization URL using stored transaction data."""
+        query_params: dict[str, Any] = {
+            "response_type": "code",
+            "client_id": self._upstream_client_id,
+            "redirect_uri": f"{str(self.base_url).rstrip('/')}{self._redirect_path}",
+            "state": txn_id,
+        }
+
+        scopes_to_use = transaction.get("scopes") or self.required_scopes or []
+        if scopes_to_use:
+            query_params["scope"] = " ".join(scopes_to_use)
+
+        # If PKCE forwarding was enabled, include the proxy challenge
+        proxy_code_verifier = transaction.get("proxy_code_verifier")
+        if proxy_code_verifier:
+            challenge_bytes = hashlib.sha256(proxy_code_verifier.encode()).digest()
+            proxy_code_challenge = (
+                urlsafe_b64encode(challenge_bytes).decode().rstrip("=")
+            )
+            query_params["code_challenge"] = proxy_code_challenge
+            query_params["code_challenge_method"] = "S256"
+
+        # Forward resource indicator if present in transaction
+        if self._forward_resource:
+            if resource := transaction.get("resource"):
+                query_params["resource"] = resource
+
+        # Extra configured parameters
+        if self._extra_authorize_params:
+            query_params.update(self._extra_authorize_params)
+
+        separator = "&" if "?" in self._upstream_authorization_endpoint else "?"
+        return f"{self._upstream_authorization_endpoint}{separator}{urlencode(query_params)}"
+
+    async def _handle_consent(
+        self: OAuthProxy, request: Request
+    ) -> HTMLResponse | RedirectResponse:
+        """Handle consent page - dispatch to GET or POST handler based on method."""
+        if request.method == "POST":
+            return await self._submit_consent(request)
+        return await self._show_consent_page(request)
+
+    async def _show_consent_page(
+        self: OAuthProxy, request: Request
+    ) -> HTMLResponse | RedirectResponse:
+        """Display consent page or auto-approve/deny based on cookies."""
+        from fastmcp.server.server import FastMCP
+
+        txn_id = request.query_params.get("txn_id")
+        if not txn_id:
+            return create_secure_html_response(
+                "<h1>Error</h1><p>Invalid or expired transaction</p>", status_code=400
+            )
+
+        txn_model = await self._transaction_store.get(key=txn_id)
+        if not txn_model:
+            return create_secure_html_response(
+                "<h1>Error</h1><p>Invalid or expired transaction</p>", status_code=400
+            )
+
+        txn = txn_model.model_dump()
+        client_key = self._make_client_key(txn["client_id"], txn["client_redirect_uri"])
+
+        # Silent consent only fires in "remember" mode, and only when the
+        # request arrived via a safe navigation context. AS-in-the-middle
+        # attacks surface as cross-site redirects from a third-party origin
+        # into /authorize; forcing the HTML prompt in that case preserves
+        # the consent-screen mitigation without blocking legitimate
+        # client-initiated flows (Sec-Fetch-Site: none).
+        if self._require_authorization_consent == "remember":
+            sec_fetch_site = request.headers.get("Sec-Fetch-Site")
+            # Fail closed on missing header: legacy clients degrade to the
+            # explicit prompt rather than silent approval.
+            silent_eligible = sec_fetch_site in ("same-origin", "same-site", "none")
+
+            if silent_eligible:
+                approved = set(
+                    self._decode_list_cookie(request, "MCP_APPROVED_CLIENTS")
+                )
+                denied = set(self._decode_list_cookie(request, "MCP_DENIED_CLIENTS"))
+
+                if client_key in approved:
+                    consent_token = secrets.token_urlsafe(32)
+                    txn_model.consent_token = consent_token
+                    await self._transaction_store.put(
+                        key=txn_id, value=txn_model, ttl=15 * 60
+                    )
+                    upstream_url = self._build_upstream_authorize_url(txn_id, txn)
+                    response = RedirectResponse(url=upstream_url, status_code=302)
+                    self._set_consent_binding_cookie(
+                        request, response, txn_id, consent_token
+                    )
+                    return response
+
+                if client_key in denied:
+                    if not self._validate_client_redirect_uri(
+                        txn["client_redirect_uri"]
+                    ):
+                        logger.warning(
+                            "Blocked consent denial redirect to disallowed URI for transaction %s",
+                            txn_id,
+                        )
+                        return create_secure_html_response(
+                            "<h1>Error</h1><p>Invalid redirect URI</p>",
+                            status_code=400,
+                        )
+
+                    callback_params = {
+                        "error": "access_denied",
+                        "state": txn.get("client_state") or "",
+                    }
+                    sep = "&" if "?" in txn["client_redirect_uri"] else "?"
+                    return RedirectResponse(
+                        url=f"{txn['client_redirect_uri']}{sep}{urlencode(callback_params)}",
+                        status_code=302,
+                    )
+            else:
+                logger.info(
+                    "Silent consent skipped for transaction %s: Sec-Fetch-Site=%r "
+                    "(cross-site navigation; forcing explicit consent prompt)",
+                    txn_id,
+                    sec_fetch_site,
+                )
+
+        # Need consent: issue CSRF token and show HTML
+        csrf_token = secrets.token_urlsafe(32)
+        csrf_expires_at = time.time() + 15 * 60
+
+        # Update transaction with CSRF token
+        txn_model.csrf_token = csrf_token
+        txn_model.csrf_expires_at = csrf_expires_at
+        await self._transaction_store.put(
+            key=txn_id, value=txn_model, ttl=15 * 60
+        )  # Auto-expire after 15 minutes
+
+        # Update dict for use in HTML generation
+        txn["csrf_token"] = csrf_token
+        txn["csrf_expires_at"] = csrf_expires_at
+
+        # Load client to get client_name and CIMD info if available
+        client = await self.get_client(txn["client_id"])
+        client_name = getattr(client, "client_name", None) if client else None
+
+        # Detect CIMD clients for verified domain badge
+        is_cimd_client = False
+        cimd_domain: str | None = None
+        if isinstance(client, ProxyDCRClient) and client.cimd_document is not None:
+            is_cimd_client = True
+            cimd_domain = urlparse(txn["client_id"]).hostname
+
+        # Extract server metadata from app state
+        fastmcp = getattr(request.app.state, "fastmcp_server", None)
+
+        if isinstance(fastmcp, FastMCP):
+            server_name = fastmcp.name
+            icons = fastmcp.icons
+            server_icon_url = icons[0].src if icons else None
+            server_website_url = fastmcp.website_url
+        else:
+            server_name = None
+            server_icon_url = None
+            server_website_url = None
+
+        html = create_consent_html(
+            client_id=txn["client_id"],
+            redirect_uri=txn["client_redirect_uri"],
+            scopes=txn.get("scopes") or [],
+            txn_id=txn_id,
+            csrf_token=csrf_token,
+            client_name=client_name,
+            server_name=server_name,
+            server_icon_url=server_icon_url,
+            server_website_url=server_website_url,
+            csp_policy=self._consent_csp_policy,
+            is_cimd_client=is_cimd_client,
+            cimd_domain=cimd_domain,
+        )
+        response = create_secure_html_response(html)
+        # Merge new CSRF token with any existing ones (supports concurrent flows)
+        existing_tokens = self._decode_list_cookie(request, "MCP_CONSENT_STATE")
+        existing_tokens.append(csrf_token)
+        self._set_list_cookie(
+            response,
+            "MCP_CONSENT_STATE",
+            self._encode_list_cookie(existing_tokens),
+            max_age=15 * 60,
+        )
+        return response
+
+    async def _submit_consent(
+        self: OAuthProxy, request: Request
+    ) -> RedirectResponse | HTMLResponse:
+        """Handle consent approval/denial, set cookies, and redirect appropriately."""
+        form = await request.form()
+        txn_id = str(form.get("txn_id", ""))
+        action = str(form.get("action", ""))
+        csrf_token = str(form.get("csrf_token", ""))
+
+        if not txn_id:
+            return create_secure_html_response(
+                "<h1>Error</h1><p>Invalid or expired transaction</p>", status_code=400
+            )
+
+        txn_model = await self._transaction_store.get(key=txn_id)
+        if not txn_model:
+            return create_secure_html_response(
+                "<h1>Error</h1><p>Invalid or expired transaction</p>", status_code=400
+            )
+
+        txn = txn_model.model_dump()
+        expected_csrf = txn.get("csrf_token")
+        expires_at = float(txn.get("csrf_expires_at") or 0)
+
+        if not expected_csrf or csrf_token != expected_csrf or time.time() > expires_at:
+            return create_secure_html_response(
+                "<h1>Error</h1><p>Invalid or expired consent token</p>", status_code=400
+            )
+
+        # Double-submit CSRF check: verify the form token matches the cookie.
+        # Without this, an attacker who knows their own tx_id/csrf_token can
+        # CSRF the victim's browser into approving consent, bypassing the
+        # consent binding cookie protection.
+        cookie_csrf_tokens = self._decode_list_cookie(request, "MCP_CONSENT_STATE")
+        if csrf_token not in cookie_csrf_tokens:
+            logger.warning(
+                "CSRF double-submit check failed for transaction %s "
+                "(possible cross-site consent forgery)",
+                txn_id,
+            )
+            return create_secure_html_response(
+                "<h1>Error</h1><p>Authorization session mismatch. "
+                "Please try authenticating again.</p>",
+                status_code=403,
+            )
+
+        client_key = self._make_client_key(txn["client_id"], txn["client_redirect_uri"])
+
+        remember_mode = self._require_authorization_consent == "remember"
+
+        if action == "approve":
+            consent_token = secrets.token_urlsafe(32)
+            txn_model.consent_token = consent_token
+            await self._transaction_store.put(key=txn_id, value=txn_model, ttl=15 * 60)
+
+            upstream_url = self._build_upstream_authorize_url(txn_id, txn)
+            response = RedirectResponse(url=upstream_url, status_code=302)
+
+            # Only persist the approval for future silent consent in "remember"
+            # mode; in the default "always" mode the cookie would never be read.
+            if remember_mode:
+                approved = list(
+                    self._decode_list_cookie(request, "MCP_APPROVED_CLIENTS")
+                )
+                if client_key in approved:
+                    approved.remove(client_key)
+                approved.append(client_key)
+                approved = approved[-_MAX_REMEMBERED_CLIENTS:]
+                self._set_list_cookie(
+                    response,
+                    "MCP_APPROVED_CLIENTS",
+                    self._encode_list_cookie(approved),
+                    max_age=365 * 24 * 3600,
+                )
+
+            # Clear CSRF cookie by setting empty short-lived value
+            self._set_list_cookie(
+                response, "MCP_CONSENT_STATE", self._encode_list_cookie([]), max_age=60
+            )
+            self._set_consent_binding_cookie(request, response, txn_id, consent_token)
+            return response
+
+        elif action == "deny":
+            if not self._validate_client_redirect_uri(txn["client_redirect_uri"]):
+                logger.warning(
+                    "Blocked consent denial redirect to disallowed URI for transaction %s",
+                    txn_id,
+                )
+                return create_secure_html_response(
+                    "<h1>Error</h1><p>Invalid redirect URI</p>",
+                    status_code=400,
+                )
+
+            callback_params = {
+                "error": "access_denied",
+                "state": txn.get("client_state") or "",
+            }
+            sep = "&" if "?" in txn["client_redirect_uri"] else "?"
+            client_callback_url = (
+                f"{txn['client_redirect_uri']}{sep}{urlencode(callback_params)}"
+            )
+            response = RedirectResponse(url=client_callback_url, status_code=302)
+
+            if remember_mode:
+                denied = list(self._decode_list_cookie(request, "MCP_DENIED_CLIENTS"))
+                if client_key in denied:
+                    denied.remove(client_key)
+                denied.append(client_key)
+                denied = denied[-_MAX_REMEMBERED_CLIENTS:]
+                self._set_list_cookie(
+                    response,
+                    "MCP_DENIED_CLIENTS",
+                    self._encode_list_cookie(denied),
+                    max_age=365 * 24 * 3600,
+                )
+
+            self._set_list_cookie(
+                response, "MCP_CONSENT_STATE", self._encode_list_cookie([]), max_age=60
+            )
+            return response
+
+        else:
+            return create_secure_html_response(
+                "<h1>Error</h1><p>Invalid action</p>", status_code=400
+            )
diff --git a/fastmcp_slim/fastmcp/server/auth/oauth_proxy/models.py b/fastmcp_slim/fastmcp/server/auth/oauth_proxy/models.py
new file mode 100644
index 0000000..7668d98
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/oauth_proxy/models.py
@@ -0,0 +1,319 @@
+"""OAuth Proxy Models and Constants.
+
+This module contains all Pydantic models and constants used by the OAuth proxy.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any, Final
+from urllib.parse import urlparse
+
+from mcp.shared.auth import InvalidRedirectUriError, OAuthClientInformationFull
+from pydantic import AnyUrl, BaseModel, Field, ValidationError
+
+from fastmcp.server.auth.cimd import CIMDDocument
+from fastmcp.server.auth.redirect_validation import (
+    matches_allowed_pattern,
+    validate_redirect_uri,
+)
+
+# -------------------------------------------------------------------------
+# Constants
+# -------------------------------------------------------------------------
+
+# Default token expiration times
+DEFAULT_ACCESS_TOKEN_EXPIRY_SECONDS: Final[int] = 60 * 60  # 1 hour
+DEFAULT_ACCESS_TOKEN_EXPIRY_NO_REFRESH_SECONDS: Final[int] = (
+    60 * 60 * 24 * 365
+)  # 1 year
+DEFAULT_REFRESH_TOKEN_EXPIRY_SECONDS: Final[int] = 60 * 60 * 24 * 365  # 1 year
+DEFAULT_AUTH_CODE_EXPIRY_SECONDS: Final[int] = 5 * 60  # 5 minutes
+
+# HTTP client timeout
+HTTP_TIMEOUT_SECONDS: Final[int] = 30
+
+
+# -------------------------------------------------------------------------
+# Pydantic Models
+# -------------------------------------------------------------------------
+
+
+class OAuthTransaction(BaseModel):
+    """OAuth transaction state for consent flow.
+
+    Stored server-side to track active authorization flows with client context.
+    Includes CSRF tokens for consent protection per MCP security best practices.
+    """
+
+    txn_id: str
+    client_id: str
+    client_redirect_uri: str
+    client_state: str
+    code_challenge: str | None
+    code_challenge_method: str
+    scopes: list[str]
+    created_at: float
+    resource: str | None = None
+    proxy_code_verifier: str | None = None
+    csrf_token: str | None = None
+    csrf_expires_at: float | None = None
+    consent_token: str | None = None
+
+
+class ClientCode(BaseModel):
+    """Client authorization code with PKCE and upstream tokens.
+
+    Stored server-side after upstream IdP callback. Contains the upstream
+    tokens bound to the client's PKCE challenge for secure token exchange.
+    """
+
+    code: str
+    client_id: str
+    redirect_uri: str
+    code_challenge: str | None
+    code_challenge_method: str
+    scopes: list[str]
+    idp_tokens: dict[str, Any]
+    expires_at: float
+    created_at: float
+
+
+class UpstreamTokenSet(BaseModel):
+    """Stored upstream OAuth tokens from identity provider.
+
+    These tokens are obtained from the upstream provider (Google, GitHub, etc.)
+    and stored in plaintext within this model. Encryption is handled transparently
+    at the storage layer via FernetEncryptionWrapper. Tokens are never exposed to MCP clients.
+    """
+
+    upstream_token_id: str  # Unique ID for this token set
+    access_token: str  # Upstream access token
+    refresh_token: str | None  # Upstream refresh token
+    refresh_token_expires_at: (
+        float | None
+    )  # Unix timestamp when refresh token expires (if known)
+    expires_at: float  # Unix timestamp when access token expires
+    token_type: str  # Usually "Bearer"
+    scope: str  # Space-separated scopes
+    client_id: str  # MCP client this is bound to
+    created_at: float  # Unix timestamp
+    raw_token_data: dict[str, Any] = Field(default_factory=dict)  # Full token response
+
+
+class JTIMapping(BaseModel):
+    """Maps FastMCP token JTI to upstream token ID.
+
+    This allows stateless JWT validation while still being able to look up
+    the corresponding upstream token when tools need to access upstream APIs.
+    """
+
+    jti: str  # JWT ID from FastMCP-issued token
+    upstream_token_id: str  # References UpstreamTokenSet
+    created_at: float  # Unix timestamp
+
+
+class RefreshTokenMetadata(BaseModel):
+    """Metadata for a refresh token, stored keyed by token hash.
+
+    We store only metadata (not the token itself) for security - if storage
+    is compromised, attackers get hashes they can't reverse into usable tokens.
+    """
+
+    client_id: str
+    scopes: list[str]
+    expires_at: int | None = None
+    created_at: float
+
+
+def _hash_token(token: str) -> str:
+    """Hash a token for secure storage lookup.
+
+    Uses SHA-256 to create a one-way hash. The original token cannot be
+    recovered from the hash, providing defense in depth if storage is compromised.
+    """
+    return hashlib.sha256(token.encode()).hexdigest()
+
+
+def _redirect_uri_path(uri_path: str) -> str:
+    return uri_path or "/"
+
+
+def _is_loopback_host(host: str | None) -> bool:
+    return host is not None and host.lower() in {"localhost", "127.0.0.1", "::1"}
+
+
+def _matches_registered_loopback_redirect_uri(
+    redirect_uri: AnyUrl,
+    registered_uri: AnyUrl,
+) -> bool:
+    requested = urlparse(str(redirect_uri))
+    registered = urlparse(str(registered_uri))
+
+    if requested.username or requested.password:
+        return False
+    if registered.username or registered.password:
+        return False
+
+    requested_host = requested.hostname.lower() if requested.hostname else None
+    registered_host = registered.hostname.lower() if registered.hostname else None
+
+    if not _is_loopback_host(registered_host):
+        return False
+    if requested_host != registered_host:
+        return False
+
+    return (
+        requested.scheme.lower() == registered.scheme.lower()
+        and _redirect_uri_path(requested.path) == _redirect_uri_path(registered.path)
+        and requested.params == registered.params
+        and requested.query == registered.query
+        and requested.fragment == registered.fragment
+    )
+
+
+def _matches_registered_redirect_uri(
+    redirect_uri: AnyUrl,
+    registered_uris: list[AnyUrl] | None,
+) -> bool:
+    if not registered_uris:
+        return False
+
+    return any(
+        redirect_uri == registered_uri
+        or _matches_registered_loopback_redirect_uri(redirect_uri, registered_uri)
+        for registered_uri in registered_uris
+    )
+
+
+class ProxyDCRClient(OAuthClientInformationFull):
+    """Client for DCR proxy with configurable redirect URI validation.
+
+    This special client class is critical for the OAuth proxy to work correctly
+    with Dynamic Client Registration (DCR). Here's why it exists:
+
+    Problem:
+    --------
+    When MCP clients use OAuth, they dynamically register with random localhost
+    ports (e.g., http://localhost:55454/callback). The OAuth proxy needs to:
+    1. Accept these dynamic redirect URIs from clients based on configured patterns
+    2. Use its own fixed redirect URI with the upstream provider (Google, GitHub, etc.)
+    3. Forward the authorization code back to the client's dynamic URI
+
+    Solution:
+    ---------
+    This class validates redirect URIs against configurable patterns,
+    while the proxy internally uses its own fixed redirect URI with the upstream
+    provider. This allows the flow to work even when clients reconnect with
+    different ports or when tokens are cached.
+
+    Without proper validation, clients could get "Redirect URI not registered" errors
+    when trying to authenticate with cached tokens, or security vulnerabilities could
+    arise from accepting arbitrary redirect URIs.
+    """
+
+    allowed_redirect_uri_patterns: list[str] | None = Field(default=None)
+    client_name: str | None = Field(default=None)
+    cimd_document: CIMDDocument | None = Field(default=None)
+    cimd_fetched_at: float | None = Field(default=None)
+    allow_unregistered_redirect_uris: bool = Field(default=False, exclude=True)
+
+    def validate_redirect_uri(self, redirect_uri: AnyUrl | None) -> AnyUrl:
+        """Validate redirect URI against proxy patterns and optionally CIMD redirect_uris.
+
+        For CIMD clients: validates against BOTH the CIMD document's redirect_uris
+        AND the proxy's allowed patterns (if configured). Both must pass.
+
+        For DCR clients: validates against proxy patterns when configured. Without
+        proxy patterns, validates against registered redirect_uris while allowing
+        loopback ports to vary for MCP client compatibility.
+        """
+        if redirect_uri is None and self.cimd_document is not None:
+            cimd_redirect_uris = self.cimd_document.redirect_uris
+            if len(cimd_redirect_uris) == 1:
+                candidate = cimd_redirect_uris[0]
+                if "*" in candidate:
+                    raise InvalidRedirectUriError(
+                        "redirect_uri must be specified when CIMD redirect_uris uses wildcards."
+                    )
+                try:
+                    resolved = AnyUrl(candidate)
+                except ValidationError as e:
+                    raise InvalidRedirectUriError(
+                        f"Invalid CIMD redirect_uri: {e}"
+                    ) from e
+
+                if not validate_redirect_uri(
+                    redirect_uri=resolved,
+                    allowed_patterns=self.allowed_redirect_uri_patterns,
+                ):
+                    raise InvalidRedirectUriError(
+                        f"Redirect URI '{resolved}' does not match allowed patterns."
+                    )
+
+                return resolved
+
+            raise InvalidRedirectUriError(
+                "redirect_uri must be specified when CIMD lists multiple redirect_uris."
+            )
+
+        if redirect_uri is not None:
+            if not validate_redirect_uri(redirect_uri, None):
+                raise InvalidRedirectUriError(
+                    f"Redirect URI '{redirect_uri}' uses an unsafe scheme."
+                )
+
+            cimd_redirect_uris = (
+                self.cimd_document.redirect_uris if self.cimd_document else None
+            )
+
+            if cimd_redirect_uris:
+                uri_str = str(redirect_uri)
+                cimd_match = any(
+                    matches_allowed_pattern(uri_str, pattern)
+                    for pattern in cimd_redirect_uris
+                )
+                if not cimd_match:
+                    raise InvalidRedirectUriError(
+                        f"Redirect URI '{redirect_uri}' does not match CIMD redirect_uris."
+                    )
+
+                if self.allowed_redirect_uri_patterns is not None:
+                    if not validate_redirect_uri(
+                        redirect_uri=redirect_uri,
+                        allowed_patterns=self.allowed_redirect_uri_patterns,
+                    ):
+                        raise InvalidRedirectUriError(
+                            f"Redirect URI '{redirect_uri}' does not match allowed patterns."
+                        )
+
+                return redirect_uri
+
+            if self.allowed_redirect_uri_patterns is None:
+                if self.allow_unregistered_redirect_uris:
+                    return redirect_uri
+                if _matches_registered_redirect_uri(redirect_uri, self.redirect_uris):
+                    return redirect_uri
+                raise InvalidRedirectUriError(
+                    f"Redirect URI '{redirect_uri}' not registered for client"
+                )
+
+            if validate_redirect_uri(
+                redirect_uri=redirect_uri,
+                allowed_patterns=self.allowed_redirect_uri_patterns,
+            ):
+                return redirect_uri
+
+            raise InvalidRedirectUriError(
+                f"Redirect URI '{redirect_uri}' does not match allowed patterns."
+            )
+
+        # redirect_uri is None with no CIMD document: let base class resolve the URI
+        # (handles the single-registered-URI shortcut for DCR clients), then validate
+        # the resolved URI against patterns so [] and other restrictions are enforced.
+        resolved = super().validate_redirect_uri(redirect_uri)
+        if not validate_redirect_uri(resolved, self.allowed_redirect_uri_patterns):
+            raise InvalidRedirectUriError(
+                f"Redirect URI '{resolved}' does not match allowed patterns."
+            )
+        return resolved
diff --git a/fastmcp_slim/fastmcp/server/auth/oauth_proxy/proxy.py b/fastmcp_slim/fastmcp/server/auth/oauth_proxy/proxy.py
new file mode 100644
index 0000000..603f8ad
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/oauth_proxy/proxy.py
@@ -0,0 +1,2380 @@
+"""OAuth Proxy Provider for FastMCP.
+
+This provider acts as a transparent proxy to an upstream OAuth Authorization Server,
+handling Dynamic Client Registration locally while forwarding all other OAuth flows.
+This enables authentication with upstream providers that don't support DCR or have
+restricted client registration policies.
+
+Key features:
+- Proxies authorization and token endpoints to upstream server
+- Implements local Dynamic Client Registration with fixed upstream credentials
+- Validates tokens using upstream JWKS
+- Maintains minimal local state for bookkeeping
+- Enhanced logging with request correlation
+
+This implementation is based on the OAuth 2.1 specification and is designed for
+production use with enterprise identity providers.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+import time
+from base64 import urlsafe_b64encode
+from collections import OrderedDict
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any, Literal
+from urllib.parse import urlencode, urlparse, urlunparse
+
+import anyio
+import httpx
+from authlib.common.security import generate_token
+from authlib.integrations.httpx_client import AsyncOAuth2Client
+from cryptography.fernet import Fernet
+from key_value.aio.adapters.pydantic import PydanticAdapter
+from key_value.aio.protocols import AsyncKeyValue
+from key_value.aio.stores.filetree import (
+    FileTreeStore,
+    FileTreeV1CollectionSanitizationStrategy,
+    FileTreeV1KeySanitizationStrategy,
+)
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+from mcp.server.auth.handlers.metadata import MetadataHandler
+from mcp.server.auth.provider import (
+    AccessToken,
+    AuthorizationCode,
+    AuthorizationParams,
+    AuthorizeError,
+    RefreshToken,
+    RegistrationError,
+    TokenError,
+)
+from mcp.server.auth.routes import build_metadata, cors_middleware
+from mcp.server.auth.settings import (
+    ClientRegistrationOptions,
+    RevocationOptions,
+)
+from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
+from pydantic import AnyHttpUrl, AnyUrl, SecretStr
+from starlette.requests import Request
+from starlette.responses import HTMLResponse, RedirectResponse
+from starlette.routing import Route
+from typing_extensions import override
+
+from fastmcp import settings
+from fastmcp.server.auth.auth import (
+    OAuthProvider,
+    PrivateKeyJWTClientAuthenticator,
+    TokenHandler,
+    TokenVerifier,
+)
+from fastmcp.server.auth.cimd import CIMDClientManager
+from fastmcp.server.auth.handlers.authorize import AuthorizationHandler
+from fastmcp.server.auth.jwt_issuer import (
+    JWTIssuer,
+    derive_jwt_key,
+)
+from fastmcp.server.auth.oauth_proxy.consent import ConsentMixin
+from fastmcp.server.auth.oauth_proxy.models import (
+    DEFAULT_ACCESS_TOKEN_EXPIRY_NO_REFRESH_SECONDS,
+    DEFAULT_ACCESS_TOKEN_EXPIRY_SECONDS,
+    DEFAULT_AUTH_CODE_EXPIRY_SECONDS,
+    DEFAULT_REFRESH_TOKEN_EXPIRY_SECONDS,
+    HTTP_TIMEOUT_SECONDS,
+    ClientCode,
+    JTIMapping,
+    OAuthTransaction,
+    ProxyDCRClient,
+    RefreshTokenMetadata,
+    UpstreamTokenSet,
+    _hash_token,
+)
+from fastmcp.server.auth.oauth_proxy.ui import create_error_html
+from fastmcp.server.auth.redirect_validation import validate_redirect_uri
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+_REFRESH_LOCK_CACHE_SIZE = 10_000
+
+
+def _normalize_resource_url(url: str) -> str:
+    """Normalize a resource URL by removing query parameters and trailing slashes.
+
+    RFC 8707 allows clients to include query parameters in resource URLs, but the
+    server's configured resource URL typically doesn't include them. This function
+    normalizes URLs for comparison by stripping query params and fragments.
+
+    Args:
+        url: The URL to normalize
+
+    Returns:
+        Normalized URL with scheme, host, and path only (no query/fragment)
+    """
+    parsed = urlparse(str(url))
+    return urlunparse(
+        (parsed.scheme, parsed.netloc, parsed.path.rstrip("/"), "", "", "")
+    )
+
+
+def _server_url_has_query(url: str) -> bool:
+    """Check if a URL has query parameters."""
+    return bool(urlparse(str(url)).query)
+
+
+class OAuthProxy(OAuthProvider, ConsentMixin):
+    """OAuth provider that presents a DCR-compliant interface while proxying to non-DCR IDPs.
+
+    Purpose
+    -------
+    MCP clients expect OAuth providers to support Dynamic Client Registration (DCR),
+    where clients can register themselves dynamically and receive unique credentials.
+    Most enterprise IDPs (Google, GitHub, Azure AD, etc.) don't support DCR and require
+    pre-registered OAuth applications with fixed credentials.
+
+    This proxy bridges that gap by:
+    - Presenting a full DCR-compliant OAuth interface to MCP clients
+    - Translating DCR registration requests to use pre-configured upstream credentials
+    - Proxying all OAuth flows to the upstream IDP with appropriate translations
+    - Managing the state and security requirements of both protocols
+
+    Architecture Overview
+    --------------------
+    The proxy maintains a single OAuth app registration with the upstream provider
+    while allowing unlimited MCP clients to register and authenticate dynamically.
+    It implements the complete OAuth 2.1 + DCR specification for clients while
+    translating to whatever OAuth variant the upstream provider requires.
+
+    Key Translation Challenges Solved
+    ---------------------------------
+    1. Dynamic Client Registration:
+       - MCP clients expect to register dynamically and get unique credentials
+       - Upstream IDPs require pre-registered apps with fixed credentials
+       - Solution: Accept DCR requests, return shared upstream credentials
+
+    2. Dynamic Redirect URIs:
+       - MCP clients use random localhost ports that change between sessions
+       - Upstream IDPs require fixed, pre-registered redirect URIs
+       - Solution: Use proxy's fixed callback URL with upstream, forward to client's dynamic URI
+
+    3. Authorization Code Mapping:
+       - Upstream returns codes for the proxy's redirect URI
+       - Clients expect codes for their own redirect URIs
+       - Solution: Exchange upstream code server-side, issue new code to client
+
+    4. State Parameter Collision:
+       - Both client and proxy need to maintain state through the flow
+       - Only one state parameter available in OAuth
+       - Solution: Use transaction ID as state with upstream, preserve client's state
+
+    5. Token Management:
+       - Clients may expect different token formats/claims than upstream provides
+       - Need to track tokens for revocation and refresh
+       - Solution: Store token relationships, forward upstream tokens transparently
+
+    OAuth Flow Implementation
+    ------------------------
+    1. Client Registration (DCR):
+       - Accept any client registration request
+       - Store ProxyDCRClient that accepts dynamic redirect URIs
+
+    2. Authorization:
+       - Store transaction mapping client details to proxy flow
+       - Redirect to upstream with proxy's fixed redirect URI
+       - Use transaction ID as state parameter with upstream
+
+    3. Upstream Callback:
+       - Exchange upstream authorization code for tokens (server-side)
+       - Generate new authorization code bound to client's PKCE challenge
+       - Redirect to client's original dynamic redirect URI
+
+    4. Token Exchange:
+       - Validate client's code and PKCE verifier
+       - Return previously obtained upstream tokens
+       - Clean up one-time use authorization code
+
+    5. Token Refresh:
+       - Forward refresh requests to upstream using authlib
+       - Handle token rotation if upstream issues new refresh token
+       - Update local token mappings
+
+    State Management
+    ---------------
+    The proxy maintains minimal but crucial state via pluggable storage (client_storage):
+    - _oauth_transactions: Active authorization flows with client context
+    - _client_codes: Authorization codes with PKCE challenges and upstream tokens
+    - _jti_mapping_store: Maps FastMCP token JTIs to upstream token IDs
+    - _refresh_token_store: Refresh token metadata (keyed by token hash)
+
+    All state is stored in the configured client_storage backend (Redis, disk, etc.)
+    enabling horizontal scaling across multiple instances.
+
+    Security Considerations
+    ----------------------
+    - Refresh tokens stored by hash only (defense in depth if storage compromised)
+    - PKCE enforced end-to-end (client to proxy, proxy to upstream)
+    - Authorization codes are single-use with short expiry
+    - Transaction IDs are cryptographically random
+    - All state is cleaned up after use to prevent replay
+    - Token validation delegates to upstream provider
+
+    Provider Compatibility
+    ---------------------
+    Works with any OAuth 2.0 provider that supports:
+    - Authorization code flow
+    - Fixed redirect URI (configured in provider's app settings)
+    - Standard token endpoint
+
+    Handles provider-specific requirements:
+    - Google: Ensures minimum scope requirements
+    - GitHub: Compatible with OAuth Apps and GitHub Apps
+    - Azure AD: Handles tenant-specific endpoints
+    - Generic: Works with any spec-compliant provider
+    """
+
+    def __init__(
+        self,
+        *,
+        # Upstream server configuration
+        upstream_authorization_endpoint: str,
+        upstream_token_endpoint: str,
+        upstream_client_id: str,
+        upstream_client_secret: str | None = None,
+        upstream_revocation_endpoint: str | None = None,
+        # Token validation
+        token_verifier: TokenVerifier,
+        # FastMCP server configuration
+        base_url: AnyHttpUrl | str,
+        resource_base_url: AnyHttpUrl | str | None = None,
+        redirect_path: str | None = None,
+        issuer_url: AnyHttpUrl | str | None = None,
+        service_documentation_url: AnyHttpUrl | str | None = None,
+        # Client redirect URI validation
+        allowed_client_redirect_uris: list[str] | None = None,
+        valid_scopes: list[str] | None = None,
+        # PKCE configuration
+        forward_pkce: bool = True,
+        # Resource indicator (RFC 8707)
+        forward_resource: bool = True,
+        # Token endpoint authentication
+        token_endpoint_auth_method: str | None = None,
+        # Extra parameters to forward to authorization endpoint
+        extra_authorize_params: dict[str, str] | None = None,
+        # Extra parameters to forward to token endpoint
+        extra_token_params: dict[str, str] | None = None,
+        # Client storage
+        client_storage: AsyncKeyValue | None = None,
+        # JWT signing key
+        jwt_signing_key: str | bytes | None = None,
+        # Consent screen configuration
+        require_authorization_consent: bool | Literal["remember", "external"] = True,
+        consent_csp_policy: str | None = None,
+        # Token expiry fallback
+        fallback_access_token_expiry_seconds: int | None = None,
+        fallback_refresh_token_expiry_seconds: int | None = None,
+        # FastMCP-issued access token lifetime (decoupled from upstream)
+        fastmcp_access_token_expiry_seconds: int | None = None,
+        # Token refresh threshold
+        token_expiry_threshold_seconds: int = 0,
+        # CIMD (Client ID Metadata Document) support
+        enable_cimd: bool = True,
+    ):
+        """Initialize the OAuth proxy provider.
+
+        Args:
+            upstream_authorization_endpoint: URL of upstream authorization endpoint
+            upstream_token_endpoint: URL of upstream token endpoint
+            upstream_client_id: Client ID registered with upstream server
+            upstream_client_secret: Client secret for upstream server. Optional for
+                PKCE public clients or when using alternative credentials (e.g.,
+                managed identity). When omitted, jwt_signing_key must be provided.
+            upstream_revocation_endpoint: Optional upstream revocation endpoint
+            token_verifier: Token verifier for validating access tokens
+            base_url: Public URL of the server that exposes this FastMCP server; redirect path is
+                relative to this URL
+            resource_base_url: Optional public base URL for the protected resource metadata
+                and token audience. Defaults to ``base_url``.
+            redirect_path: Redirect path configured in upstream OAuth app (defaults to "/auth/callback")
+            issuer_url: Issuer URL for OAuth metadata (defaults to base_url)
+            service_documentation_url: Optional service documentation URL
+            allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
+                Patterns support wildcards (e.g., "http://localhost:*", "https://*.example.com/*").
+                If None (default), DCR clients use registered redirect URIs, with loopback
+                ports allowed to vary for MCP compatibility. Unsafe browser schemes are rejected.
+                If empty list, no redirect URIs are allowed.
+                These are for MCP clients performing loopback redirects, NOT for the upstream OAuth app.
+            valid_scopes: List of all the possible valid scopes for a client.
+                These are advertised to clients through the `/.well-known` endpoints. Defaults to `required_scopes` if not provided.
+            forward_pkce: Whether to forward PKCE to upstream server (default True).
+                Enable for providers that support/require PKCE (Google, Azure, AWS, etc.).
+                Disable only if upstream provider doesn't support PKCE.
+            token_endpoint_auth_method: Token endpoint authentication method for upstream server.
+                Common values: "client_secret_basic", "client_secret_post", "none".
+                If None, authlib will use its default (typically "client_secret_basic").
+            extra_authorize_params: Additional parameters to forward to the upstream authorization endpoint.
+                Useful for provider-specific parameters like Auth0's "audience".
+                Example: {"audience": "https://api.example.com"}
+            extra_token_params: Additional parameters to forward to the upstream token endpoint.
+                Useful for provider-specific parameters during token exchange.
+            client_storage: Storage backend for OAuth state (client registrations, tokens).
+                If None, an encrypted file store will be created in the data directory.
+            jwt_signing_key: Secret for signing FastMCP JWT tokens (any string or bytes).
+                If bytes are provided, they will be used as-is.
+                If a string is provided, it will be derived into a 32-byte key using PBKDF2 (1.2M iterations).
+                If not provided, it will be derived from the upstream client secret using HKDF.
+            require_authorization_consent: Consent screen behavior (default True).
+                - True: always show the consent screen before redirecting to the
+                  upstream IdP. Strongest protection against AS-in-the-middle
+                  attacks.
+                - "remember": show the consent screen the first time, then silently
+                  approve subsequent authorizations for the same (client_id,
+                  redirect_uri) in the same browser. Cross-site navigations are
+                  still prompted to block AS-in-the-middle attacks. Lower UX
+                  friction, but weaker protection than True.
+                - "external": skip the built-in consent screen; consent is handled
+                  externally (e.g. by the upstream IdP or a custom login page).
+                - False: skip consent entirely. SECURITY WARNING: only set to
+                  False for local development or testing environments.
+            consent_csp_policy: Content Security Policy for the consent page.
+                If None (default), uses the built-in CSP policy with appropriate directives.
+                If empty string "", disables CSP entirely (no meta tag is rendered).
+                If a non-empty string, uses that as the CSP policy value.
+                This allows organizations with their own CSP policies to override or disable
+                the built-in CSP directives.
+            fallback_access_token_expiry_seconds: Expiry time to use when upstream provider
+                doesn't return `expires_in` in the token response. If not set, uses smart
+                defaults: 1 hour if a refresh token is available (since we can refresh),
+                or 1 year if no refresh token (for API-key-style tokens like GitHub OAuth Apps).
+                Set explicitly to override these defaults.
+            fallback_refresh_token_expiry_seconds: Expiry time to use when upstream provider
+                doesn't return `refresh_expires_in` (e.g. Cognito, GitHub, many OIDC IdPs).
+                Defaults to 1 year. Note: this only controls the FastMCP-issued refresh token
+                lifetime — the actual upstream refresh remains the source of truth. If the
+                upstream rejects the refresh, the client gets `invalid_grant` and re-auths,
+                regardless of how much life is left on the FastMCP refresh token.
+            fastmcp_access_token_expiry_seconds: Lifetime for the FastMCP-issued access
+                token (JWT), decoupling it from the upstream provider's `expires_in`. By
+                default (None) the FastMCP access token mirrors the upstream access token
+                lifetime. The FastMCP JWT is a reference token — `load_access_token`
+                re-validates the upstream token on every request and transparently refreshes
+                it when expired — so issuing a longer-lived FastMCP token does not extend
+                upstream access: a revoked or expired upstream session still fails validation
+                and forces re-auth. Set this for bridges whose upstream issues short-lived
+                access tokens (5-60 min) that some MCP clients can't refresh gracefully
+                (e.g. `mcp-remote`), where the short client-facing TTL forces a full re-auth
+                on every idle period. Only affects the FastMCP-issued token; the upstream
+                token's real expiry is preserved internally to drive transparent refresh.
+                When the upstream provider issues no refresh token there is no way to renew
+                the access token, so the lifetime is capped at the upstream `expires_in`
+                regardless of this value (it can still be used to shorten it).
+            token_expiry_threshold_seconds: Number of seconds before actual expiry to consider
+                a token as expired (default 0). This prevents race conditions where a token
+                passes the expiry check but expires before the next operation completes.
+                For example, set to 30 to refresh tokens that will expire within 30 seconds.
+            enable_cimd: Enable CIMD (Client ID Metadata Document) support for URL-based
+                client IDs. When True, clients can authenticate using HTTPS URLs as client
+                IDs, with metadata fetched from the URL. Supports private_key_jwt auth.
+        """
+
+        default_scopes = valid_scopes or token_verifier.required_scopes
+
+        # Always enable DCR since we implement it locally for MCP clients
+        client_registration_options = ClientRegistrationOptions(
+            enabled=True,
+            valid_scopes=list(default_scopes) if default_scopes is not None else None,
+            default_scopes=list(default_scopes) if default_scopes is not None else None,
+        )
+
+        # Enable revocation only if upstream endpoint provided
+        revocation_options = (
+            RevocationOptions(enabled=True) if upstream_revocation_endpoint else None
+        )
+
+        super().__init__(
+            base_url=base_url,
+            resource_base_url=resource_base_url,
+            issuer_url=issuer_url,
+            service_documentation_url=service_documentation_url,
+            client_registration_options=client_registration_options,
+            revocation_options=revocation_options,
+            required_scopes=token_verifier.required_scopes,
+        )
+
+        # Store upstream configuration
+        self._upstream_authorization_endpoint: str = upstream_authorization_endpoint
+        self._upstream_token_endpoint: str = upstream_token_endpoint
+        self._upstream_client_id: str = upstream_client_id
+        self._upstream_client_secret: SecretStr | None = (
+            SecretStr(secret_value=upstream_client_secret)
+            if upstream_client_secret is not None
+            else None
+        )
+        self._upstream_revocation_endpoint: str | None = upstream_revocation_endpoint
+        self._default_scope_str: str = " ".join(default_scopes or [])
+
+        # Store redirect configuration
+        if not redirect_path:
+            self._redirect_path = "/auth/callback"
+        else:
+            self._redirect_path = (
+                redirect_path if redirect_path.startswith("/") else f"/{redirect_path}"
+            )
+
+        if (
+            isinstance(allowed_client_redirect_uris, list)
+            and not allowed_client_redirect_uris
+        ):
+            logger.warning(
+                "allowed_client_redirect_uris is empty list; no redirect URIs will be accepted. "
+                "This will block all OAuth clients."
+            )
+        self._allowed_client_redirect_uris: list[str] | None = (
+            allowed_client_redirect_uris
+        )
+
+        # PKCE configuration
+        self._forward_pkce: bool = forward_pkce
+        # Resource indicator (RFC 8707)
+        self._forward_resource: bool = forward_resource
+
+        # Token endpoint authentication
+        self._token_endpoint_auth_method: str | None = token_endpoint_auth_method
+
+        # Consent screen configuration
+        self._require_authorization_consent: bool | Literal["remember", "external"] = (
+            require_authorization_consent
+        )
+        self._consent_csp_policy: str | None = consent_csp_policy
+        if require_authorization_consent == "external":
+            logger.info(
+                "Built-in consent screen disabled; consent is handled externally."
+            )
+        elif require_authorization_consent == "remember":
+            logger.info(
+                "Consent screen in 'remember' mode: silent consent on return visits "
+                "for previously-approved clients (with Sec-Fetch-Site gating). "
+                "Set require_authorization_consent=True for strongest protection "
+                "against AS-in-the-middle attacks."
+            )
+        elif not require_authorization_consent:
+            logger.warning(
+                "Authorization consent screen disabled - only use for local development or testing. "
+                "In production, this screen protects against confused deputy attacks."
+            )
+
+        # Extra parameters for authorization and token endpoints
+        self._extra_authorize_params: dict[str, str] = extra_authorize_params or {}
+        self._extra_token_params: dict[str, str] = extra_token_params or {}
+
+        # Token expiry fallback (None means use smart default based on refresh token)
+        self._fallback_access_token_expiry_seconds: int | None = (
+            fallback_access_token_expiry_seconds
+        )
+        self._fallback_refresh_token_expiry_seconds: int = (
+            fallback_refresh_token_expiry_seconds
+            if fallback_refresh_token_expiry_seconds is not None
+            else DEFAULT_REFRESH_TOKEN_EXPIRY_SECONDS
+        )
+        self._fastmcp_access_token_expiry_seconds: int | None = (
+            fastmcp_access_token_expiry_seconds
+        )
+        self._token_expiry_threshold_seconds: int = token_expiry_threshold_seconds
+
+        if jwt_signing_key is None:
+            if upstream_client_secret is None:
+                raise ValueError(
+                    "jwt_signing_key is required when upstream_client_secret is not provided. "
+                    "The JWT signing key cannot be derived without a client secret."
+                )
+            jwt_signing_key = derive_jwt_key(
+                high_entropy_material=upstream_client_secret,
+                salt="fastmcp-jwt-signing-key",
+            )
+
+        if isinstance(jwt_signing_key, str):
+            if len(jwt_signing_key) < 12:
+                logger.warning(
+                    "jwt_signing_key is less than 12 characters; it is recommended to use a longer. "
+                    "string for the key derivation."
+                )
+            jwt_signing_key = derive_jwt_key(
+                low_entropy_material=jwt_signing_key,
+                salt="fastmcp-jwt-signing-key",
+            )
+
+        # Store JWT signing key for deferred JWTIssuer creation in set_mcp_path()
+        self._jwt_signing_key: bytes = jwt_signing_key
+        # JWTIssuer will be created in set_mcp_path() with correct audience
+        self._jwt_issuer: JWTIssuer | None = None
+
+        # If the user does not provide a store, we will provide an encrypted file store.
+        # The storage directory is derived from the encryption key so that different
+        # keys get isolated directories (e.g. two servers on the same machine with
+        # different keys won't collide). Decryption errors are treated as cache misses
+        # rather than hard failures, so key rotation just causes re-registration.
+        if client_storage is None:
+            storage_encryption_key = derive_jwt_key(
+                high_entropy_material=jwt_signing_key.decode(),
+                salt="fastmcp-storage-encryption-key",
+            )
+
+            key_fingerprint = hashlib.sha256(storage_encryption_key).hexdigest()[:12]
+            storage_dir = settings.home / "oauth-proxy" / key_fingerprint
+            storage_dir.mkdir(parents=True, exist_ok=True)
+
+            file_store = FileTreeStore(
+                data_directory=storage_dir,
+                key_sanitization_strategy=FileTreeV1KeySanitizationStrategy(
+                    storage_dir
+                ),
+                collection_sanitization_strategy=FileTreeV1CollectionSanitizationStrategy(
+                    storage_dir
+                ),
+            )
+
+            client_storage = FernetEncryptionWrapper(
+                key_value=file_store,
+                fernet=Fernet(key=storage_encryption_key),
+                raise_on_decryption_error=False,
+            )
+
+        self._client_storage: AsyncKeyValue = client_storage
+
+        # Cache HTTPS check to avoid repeated logging
+        self._is_https: bool = str(self.base_url).startswith("https://")
+        if not self._is_https:
+            logger.warning(
+                "Using non-secure cookies for development; deploy with HTTPS for production."
+            )
+
+        self._upstream_token_store: PydanticAdapter[UpstreamTokenSet] = PydanticAdapter[
+            UpstreamTokenSet
+        ](
+            key_value=self._client_storage,
+            pydantic_model=UpstreamTokenSet,
+            default_collection="mcp-upstream-tokens",
+            raise_on_validation_error=True,
+        )
+
+        self._client_store: PydanticAdapter[ProxyDCRClient] = PydanticAdapter[
+            ProxyDCRClient
+        ](
+            key_value=self._client_storage,
+            pydantic_model=ProxyDCRClient,
+            default_collection="mcp-oauth-proxy-clients",
+            raise_on_validation_error=True,
+        )
+
+        # OAuth transaction storage for IdP callback forwarding
+        # Reuse client_storage with different collections for state management
+        self._transaction_store: PydanticAdapter[OAuthTransaction] = PydanticAdapter[
+            OAuthTransaction
+        ](
+            key_value=self._client_storage,
+            pydantic_model=OAuthTransaction,
+            default_collection="mcp-oauth-transactions",
+            raise_on_validation_error=True,
+        )
+
+        self._code_store: PydanticAdapter[ClientCode] = PydanticAdapter[ClientCode](
+            key_value=self._client_storage,
+            pydantic_model=ClientCode,
+            default_collection="mcp-authorization-codes",
+            raise_on_validation_error=True,
+        )
+
+        # Storage for JTI mappings (FastMCP token -> upstream token)
+        self._jti_mapping_store: PydanticAdapter[JTIMapping] = PydanticAdapter[
+            JTIMapping
+        ](
+            key_value=self._client_storage,
+            pydantic_model=JTIMapping,
+            default_collection="mcp-jti-mappings",
+            raise_on_validation_error=True,
+        )
+
+        # Refresh token metadata storage, keyed by token hash for security.
+        # We only store metadata (not the token itself) - if storage is compromised,
+        # attackers get hashes they can't reverse into usable tokens.
+        self._refresh_token_store: PydanticAdapter[RefreshTokenMetadata] = (
+            PydanticAdapter[RefreshTokenMetadata](
+                key_value=self._client_storage,
+                pydantic_model=RefreshTokenMetadata,
+                default_collection="mcp-refresh-tokens",
+                raise_on_validation_error=True,
+            )
+        )
+
+        # Use the provided token validator
+        self._token_validator: TokenVerifier = token_verifier
+
+        # CIMD (Client ID Metadata Document) support
+        self._cimd_manager: CIMDClientManager | None = None
+        if enable_cimd:
+            self._cimd_manager = CIMDClientManager(
+                enable_cimd=True,
+                default_scope=self._default_scope_str,
+                allowed_redirect_uri_patterns=self._allowed_client_redirect_uris,
+            )
+
+        # Advisory locks for transparent upstream token refresh, keyed by
+        # upstream_token_id. Prevents concurrent async tasks from racing to
+        # refresh the same token within a single process. Does not protect
+        # against cross-process races in distributed deployments — those are
+        # handled by re-reading from storage after refresh failure.
+        self._refresh_locks: OrderedDict[str, anyio.Lock] = OrderedDict()
+
+        logger.debug(
+            "Initialized OAuth proxy provider with upstream server %s",
+            self._upstream_authorization_endpoint,
+        )
+
+    # -------------------------------------------------------------------------
+    # Scope Management
+    # -------------------------------------------------------------------------
+
+    def update_default_scopes(self, scopes: list[str]) -> None:
+        """Update the default scopes advertised to clients and used for DCR/CIMD fallback.
+
+        Use this method when the available scope set is determined after provider
+        initialization (e.g., after tool registration widens the required scopes).
+
+        This updates all internal state derived from scopes:
+        - The default scope string used for DCR client registration fallback
+        - The CIMD manager's default scope (if CIMD is enabled)
+        - The client registration options default_scopes and valid_scopes (if registration options exist)
+
+        Args:
+            scopes: The new list of valid scopes to advertise and use as defaults.
+        """
+        scopes = list(scopes)
+        self._default_scope_str = " ".join(scopes)
+        if self._cimd_manager is not None:
+            self._cimd_manager.default_scope = self._default_scope_str
+        if self.client_registration_options is not None:
+            self.client_registration_options.default_scopes = list(scopes)
+            self.client_registration_options.valid_scopes = list(scopes)
+
+    # -------------------------------------------------------------------------
+    # MCP Path Configuration
+    # -------------------------------------------------------------------------
+
+    def set_mcp_path(self, mcp_path: str | None) -> None:
+        """Set the MCP endpoint path and create JWTIssuer with correct audience.
+
+        This method is called by get_routes() to configure the resource URL
+        and create the JWTIssuer. The JWT audience is set to the full resource
+        URL (e.g., http://localhost:8000/mcp) to ensure tokens are bound to
+        this specific MCP endpoint.
+
+        Args:
+            mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
+        """
+        super().set_mcp_path(mcp_path)
+
+        # Create JWT issuer with correct audience based on actual MCP path
+        # This ensures tokens are bound to the specific resource URL
+        self._jwt_issuer = JWTIssuer(
+            issuer=str(self.base_url),
+            audience=str(self._resource_url),
+            signing_key=self._jwt_signing_key,
+        )
+
+        logger.debug("Configured OAuth proxy for resource URL: %s", self._resource_url)
+
+    @property
+    def jwt_issuer(self) -> JWTIssuer:
+        """Get the JWT issuer, ensuring it has been initialized.
+
+        The JWT issuer is created when set_mcp_path() is called (via get_routes()).
+        This property ensures a clear error if used before initialization.
+        """
+        if self._jwt_issuer is None:
+            raise RuntimeError(
+                "JWT issuer not initialized. Ensure get_routes() is called "
+                "before token operations."
+            )
+        return self._jwt_issuer
+
+    # -------------------------------------------------------------------------
+    # Upstream OAuth Client
+    # -------------------------------------------------------------------------
+
+    def _create_upstream_oauth_client(self) -> AsyncOAuth2Client:
+        """Create an OAuth2 client for communicating with the upstream IdP.
+
+        This is the single point for constructing the client used in token
+        exchange, refresh, and other upstream interactions. Subclasses can
+        override this to provide alternative authentication methods (e.g.,
+        managed-identity client assertions instead of a static client secret).
+        """
+        return AsyncOAuth2Client(
+            client_id=self._upstream_client_id,
+            client_secret=(
+                self._upstream_client_secret.get_secret_value()
+                if self._upstream_client_secret is not None
+                else None
+            ),
+            token_endpoint_auth_method=self._token_endpoint_auth_method,
+            timeout=HTTP_TIMEOUT_SECONDS,
+        )
+
+    @asynccontextmanager
+    async def _upstream_oauth_client(self) -> AsyncIterator[AsyncOAuth2Client]:
+        oauth_client = self._create_upstream_oauth_client()
+        try:
+            yield oauth_client
+        finally:
+            await oauth_client.aclose()
+
+    def _get_refresh_lock(self, token_id: str) -> anyio.Lock:
+        """Get or create a per-token refresh lock, evicting LRU entries when at capacity."""
+        lock = self._refresh_locks.get(token_id)
+        if lock is None:
+            lock = anyio.Lock()
+            self._refresh_locks[token_id] = lock
+            if len(self._refresh_locks) > _REFRESH_LOCK_CACHE_SIZE:
+                self._refresh_locks.popitem(last=False)
+        else:
+            self._refresh_locks.move_to_end(token_id)
+        return lock
+
+    # -------------------------------------------------------------------------
+    # PKCE Helper Methods
+    # -------------------------------------------------------------------------
+
+    def _generate_pkce_pair(self) -> tuple[str, str]:
+        """Generate PKCE code verifier and challenge pair.
+
+        Returns:
+            Tuple of (code_verifier, code_challenge) using S256 method
+        """
+        # Generate code verifier: 43-128 characters from unreserved set
+        code_verifier = generate_token(48)
+
+        # Generate code challenge using S256 (SHA256 + base64url)
+        challenge_bytes = hashlib.sha256(code_verifier.encode()).digest()
+        code_challenge = urlsafe_b64encode(challenge_bytes).decode().rstrip("=")
+
+        return code_verifier, code_challenge
+
+    # -------------------------------------------------------------------------
+    # Client Registration (Local Implementation)
+    # -------------------------------------------------------------------------
+
+    @override
+    async def get_client(self, client_id: str) -> OAuthClientInformationFull | None:
+        """Get client information by ID. This is generally the random ID
+        provided to the DCR client during registration, not the upstream client ID.
+
+        For unregistered clients, returns None (which will raise an error in the SDK).
+        CIMD clients (URL-based client IDs) are looked up and cached automatically.
+        """
+        # Load from storage
+        client = await self._client_store.get(key=client_id)
+
+        if client is not None:
+            if self._allowed_client_redirect_uris is not None:
+                client.allowed_redirect_uri_patterns = (
+                    self._allowed_client_redirect_uris
+                )
+
+            # Refresh CIMD clients using HTTP cache-aware fetcher.
+            if self._cimd_manager is not None and client.cimd_document is not None:
+                try:
+                    refreshed = await self._cimd_manager.get_client(client_id)
+                    if refreshed is not None:
+                        await self._client_store.put(key=client_id, value=refreshed)
+                        return refreshed
+                except Exception as e:
+                    logger.debug(
+                        "CIMD refresh failed for %s, using cached client: %s",
+                        client_id,
+                        e,
+                    )
+
+            return client
+
+        # Client not in storage — try CIMD lookup for URL-based client IDs
+        if self._cimd_manager is not None and self._cimd_manager.is_cimd_client_id(
+            client_id
+        ):
+            cimd_client = await self._cimd_manager.get_client(client_id)
+            if cimd_client is not None:
+                await self._client_store.put(key=client_id, value=cimd_client)
+                return cimd_client
+
+        # Some MCP clients (e.g. claude.ai) skip Dynamic Client Registration and
+        # send the upstream OAuth App's client_id directly in the /authorize request.
+        # Synthesize a client on-the-fly so these clients aren't rejected with 400.
+        if client_id == self._upstream_client_id:
+            logger.debug(
+                "Client %s matched upstream client_id — synthesizing client without DCR",
+                client_id,
+            )
+            return ProxyDCRClient(
+                client_id=client_id,
+                client_secret=None,
+                redirect_uris=[AnyUrl("http://localhost")],
+                grant_types=["authorization_code", "refresh_token"],
+                scope=self._default_scope_str,
+                token_endpoint_auth_method="none",
+                allowed_redirect_uri_patterns=self._allowed_client_redirect_uris,
+                allow_unregistered_redirect_uris=True,
+            )
+
+        return None
+
+    @override
+    async def register_client(self, client_info: OAuthClientInformationFull) -> None:
+        """Register a client locally
+
+        When a client registers, we create a ProxyDCRClient that is more
+        forgiving about validating redirect URIs, since the DCR client's
+        redirect URI will likely be localhost or unknown to the proxied IDP. The
+        proxied IDP only knows about this server's fixed redirect URI.
+        """
+
+        # Create a ProxyDCRClient with configured redirect URI validation
+        if client_info.client_id is None:
+            raise ValueError("client_id is required for client registration")
+        if client_info.redirect_uris:
+            for redirect_uri in client_info.redirect_uris:
+                if not validate_redirect_uri(
+                    redirect_uri=redirect_uri,
+                    allowed_patterns=self._allowed_client_redirect_uris,
+                ):
+                    raise RegistrationError(
+                        "invalid_redirect_uri",
+                        f"Redirect URI '{redirect_uri}' is not allowed.",
+                    )
+
+        redirect_uris = client_info.redirect_uris or [AnyUrl("http://localhost")]
+
+        # We use token_endpoint_auth_method="none" because the proxy handles
+        # all upstream authentication. The client_secret must also be None
+        # because the SDK requires secrets to be provided if they're set,
+        # regardless of auth method.
+        proxy_client: ProxyDCRClient = ProxyDCRClient(
+            client_id=client_info.client_id,
+            client_secret=None,
+            redirect_uris=redirect_uris,
+            grant_types=client_info.grant_types
+            or ["authorization_code", "refresh_token"],
+            scope=client_info.scope or self._default_scope_str,
+            token_endpoint_auth_method="none",
+            allowed_redirect_uri_patterns=self._allowed_client_redirect_uris,
+            client_name=getattr(client_info, "client_name", None),
+        )
+
+        await self._client_store.put(
+            key=client_info.client_id,
+            value=proxy_client,
+        )
+
+        # Log redirect URIs to help users discover what patterns they might need
+        if client_info.redirect_uris:
+            for uri in client_info.redirect_uris:
+                logger.debug(
+                    "Client registered with redirect_uri: %s - if restricting redirect URIs, "
+                    "ensure this pattern is allowed in allowed_client_redirect_uris",
+                    uri,
+                )
+
+        logger.debug(
+            "Registered client %s with %d redirect URIs",
+            client_info.client_id,
+            len(proxy_client.redirect_uris) if proxy_client.redirect_uris else 0,
+        )
+
+    # -------------------------------------------------------------------------
+    # Authorization Flow (Proxy to Upstream)
+    # -------------------------------------------------------------------------
+
+    @override
+    async def authorize(
+        self,
+        client: OAuthClientInformationFull,
+        params: AuthorizationParams,
+    ) -> str:
+        """Start OAuth transaction and route through consent interstitial.
+
+        Flow:
+        1. Validate client's resource matches server's resource URL (security check)
+        2. Store transaction with client details and PKCE (if forwarding)
+        3. Return local /consent URL; browser visits consent first
+        4. Consent handler redirects to upstream IdP if approved/already approved
+
+        If consent is disabled (require_authorization_consent=False or "external"),
+        skip the consent screen and redirect directly to the upstream IdP. In
+        "remember" mode, still route through /consent so the cookie lookup and
+        Sec-Fetch-Site gating can run.
+        """
+        # Security check: validate client's requested resource matches this server
+        # This prevents tokens intended for one server from being used on another
+        #
+        # Per RFC 8707, clients may include query parameters in resource URLs (e.g.,
+        # ChatGPT sends ?kb_name=X). We handle two cases:
+        #
+        # 1. Server URL has NO query params: normalize both URLs (strip query/fragment)
+        #    to allow clients like ChatGPT that add query params to still match.
+        #
+        # 2. Server URL HAS query params (e.g., multi-tenant ?tenant=X): require exact
+        #    match to prevent clients from bypassing tenant isolation by changing params.
+        #
+        # Claude doesn't send a resource parameter at all, so this check is skipped.
+        client_resource = getattr(params, "resource", None)
+        if client_resource and self._resource_url:
+            server_url = str(self._resource_url)
+            client_url = str(client_resource)
+
+            if _server_url_has_query(server_url):
+                # Server has query params - require exact match for security
+                urls_match = client_url.rstrip("/") == server_url.rstrip("/")
+            else:
+                # Server has no query params - normalize both for comparison
+                urls_match = _normalize_resource_url(
+                    client_url
+                ) == _normalize_resource_url(server_url)
+
+            if not urls_match:
+                logger.warning(
+                    "Resource mismatch: client requested %s but server is %s",
+                    client_resource,
+                    self._resource_url,
+                )
+                raise AuthorizeError(
+                    error="invalid_target",  # type: ignore[arg-type]
+                    error_description="Resource does not match this server",
+                )
+
+        # Generate transaction ID for this authorization request
+        txn_id = secrets.token_urlsafe(32)
+
+        # Generate proxy's own PKCE parameters if forwarding is enabled
+        proxy_code_verifier = None
+        proxy_code_challenge = None
+        if self._forward_pkce and params.code_challenge:
+            proxy_code_verifier, proxy_code_challenge = self._generate_pkce_pair()
+            logger.debug(
+                "Generated proxy PKCE for transaction %s (forwarding client PKCE to upstream)",
+                txn_id,
+            )
+
+        # Store transaction data for IdP callback processing
+        if client.client_id is None:
+            raise AuthorizeError(
+                error="invalid_client",  # type: ignore[arg-type]  # "invalid_client" is valid OAuth error but not in Literal type  # ty:ignore[invalid-argument-type]
+                error_description="Client ID is required",
+            )
+        transaction = OAuthTransaction(
+            txn_id=txn_id,
+            client_id=client.client_id,
+            client_redirect_uri=str(params.redirect_uri),
+            client_state=params.state or "",
+            code_challenge=params.code_challenge,
+            code_challenge_method=getattr(params, "code_challenge_method", "S256"),
+            scopes=params.scopes or [],
+            created_at=time.time(),
+            resource=getattr(params, "resource", None),
+            proxy_code_verifier=proxy_code_verifier,
+        )
+        await self._transaction_store.put(
+            key=txn_id,
+            value=transaction,
+            ttl=15 * 60,  # Auto-expire after 15 minutes
+        )
+
+        # If consent is disabled or handled externally, skip consent screen.
+        # "remember" mode still routes through /consent so cookie lookup and
+        # Sec-Fetch-Site gating can run.
+        if self._require_authorization_consent in (False, "external"):
+            upstream_url = self._build_upstream_authorize_url(
+                txn_id, transaction.model_dump()
+            )
+            logger.debug(
+                "Starting OAuth transaction %s for client %s, redirecting directly to upstream IdP (consent disabled, PKCE forwarding: %s)",
+                txn_id,
+                client.client_id,
+                "enabled" if proxy_code_challenge else "disabled",
+            )
+            return upstream_url
+
+        consent_url = f"{str(self.base_url).rstrip('/')}/consent?txn_id={txn_id}"
+
+        logger.debug(
+            "Starting OAuth transaction %s for client %s, redirecting to consent page (PKCE forwarding: %s)",
+            txn_id,
+            client.client_id,
+            "enabled" if proxy_code_challenge else "disabled",
+        )
+        return consent_url
+
+    # -------------------------------------------------------------------------
+    # Authorization Code Handling
+    # -------------------------------------------------------------------------
+
+    @override
+    async def load_authorization_code(
+        self,
+        client: OAuthClientInformationFull,
+        authorization_code: str,
+    ) -> AuthorizationCode | None:
+        """Load authorization code for validation.
+
+        Look up our client code and return authorization code object
+        with PKCE challenge for validation.
+        """
+        # Look up client code data
+        code_model = await self._code_store.get(key=authorization_code)
+        if not code_model:
+            logger.debug("Authorization code not found: %s", authorization_code)
+            return None
+
+        # Check if code expired
+        if time.time() > code_model.expires_at:
+            logger.debug("Authorization code expired: %s", authorization_code)
+            _ = await self._code_store.delete(key=authorization_code)
+            return None
+
+        # Verify client ID matches
+        if code_model.client_id != client.client_id:
+            logger.debug(
+                "Authorization code client ID mismatch: %s vs %s",
+                code_model.client_id,
+                client.client_id,
+            )
+            return None
+
+        # Create authorization code object with PKCE challenge
+        if client.client_id is None:
+            raise AuthorizeError(
+                error="invalid_client",  # type: ignore[arg-type]  # "invalid_client" is valid OAuth error but not in Literal type  # ty:ignore[invalid-argument-type]
+                error_description="Client ID is required",
+            )
+        return AuthorizationCode(
+            code=authorization_code,
+            client_id=client.client_id,
+            redirect_uri=AnyUrl(url=code_model.redirect_uri),
+            redirect_uri_provided_explicitly=True,
+            scopes=code_model.scopes,
+            expires_at=code_model.expires_at,
+            code_challenge=code_model.code_challenge or "",
+        )
+
+    @override
+    async def exchange_authorization_code(
+        self,
+        client: OAuthClientInformationFull,
+        authorization_code: AuthorizationCode,
+    ) -> OAuthToken:
+        """Exchange authorization code for FastMCP-issued tokens.
+
+        Implements the token factory pattern:
+        1. Retrieves upstream tokens from stored authorization code
+        2. Extracts user identity from upstream token
+        3. Encrypts and stores upstream tokens
+        4. Issues FastMCP-signed JWT tokens
+        5. Returns FastMCP tokens (NOT upstream tokens)
+
+        PKCE validation is handled by the MCP framework before this method is called.
+        """
+        # Look up stored code data
+        code_model = await self._code_store.get(key=authorization_code.code)
+        if not code_model:
+            logger.error(
+                "Authorization code not found in client codes: %s",
+                authorization_code.code,
+            )
+            raise TokenError("invalid_grant", "Authorization code not found")
+
+        # Get stored upstream tokens
+        idp_tokens = code_model.idp_tokens
+
+        # Use IdP-granted scopes when available (RFC 6749 §5.1: the IdP MUST
+        # include a scope parameter when the granted scope differs from the
+        # requested scope).  Fall back to requested scopes only when the IdP
+        # omits scope, meaning it granted exactly what was requested.
+        granted_scopes: list[str] = (
+            parse_scopes(idp_tokens["scope"]) or []
+            if "scope" in idp_tokens
+            else list(authorization_code.scopes)
+        )
+        # Translate IdP-wire scopes into the client-facing form before they
+        # propagate to storage, the FastMCP JWT, and the response body. Default
+        # implementation is identity; AzureProvider overrides this to strip the
+        # identifier_uri prefix Azure echoes back on custom API scopes.
+        granted_scopes = self._translate_scopes_from_idp(granted_scopes)
+
+        # Clean up client code (one-time use)
+        await self._code_store.delete(key=authorization_code.code)
+
+        # Generate IDs for token storage
+        upstream_token_id = secrets.token_urlsafe(32)
+        access_jti = secrets.token_urlsafe(32)
+        refresh_jti = (
+            secrets.token_urlsafe(32) if idp_tokens.get("refresh_token") else None
+        )
+
+        # Calculate token expiry times
+        # If upstream provides expires_in, use it. Otherwise use fallback based on:
+        # - User-provided fallback if set
+        # - 1 hour if refresh token available (can refresh when expired)
+        # - 1 year if no refresh token (likely API-key-style token like GitHub OAuth Apps)
+        if "expires_in" in idp_tokens:
+            expires_in = int(idp_tokens["expires_in"])
+            logger.debug(
+                "Access token TTL: %d seconds (from IdP expires_in)", expires_in
+            )
+        elif self._fallback_access_token_expiry_seconds is not None:
+            expires_in = self._fallback_access_token_expiry_seconds
+            logger.debug(
+                "Access token TTL: %d seconds (using configured fallback)", expires_in
+            )
+        elif idp_tokens.get("refresh_token"):
+            expires_in = DEFAULT_ACCESS_TOKEN_EXPIRY_SECONDS
+            logger.debug(
+                "Access token TTL: %d seconds (default, has refresh token)", expires_in
+            )
+        else:
+            expires_in = DEFAULT_ACCESS_TOKEN_EXPIRY_NO_REFRESH_SECONDS
+            logger.debug(
+                "Access token TTL: %d seconds (default, no refresh token)", expires_in
+            )
+
+        # The FastMCP-issued access token is a reference into our storage and may
+        # outlive the upstream access token, because transparent refresh keeps the
+        # upstream token fresh on each request. `expires_in` stays the upstream
+        # lifetime; this drives only the FastMCP JWT, its JTI mapping, and the
+        # response's expires_in. Extending past the upstream lifetime is only safe
+        # when we can refresh: without an upstream refresh token there is no way to
+        # renew the access token, so the FastMCP token must not claim to outlive the
+        # upstream token it points at.
+        fastmcp_access_expires_in = expires_in
+        if self._fastmcp_access_token_expiry_seconds is not None:
+            fastmcp_access_expires_in = self._fastmcp_access_token_expiry_seconds
+            if not idp_tokens.get("refresh_token"):
+                fastmcp_access_expires_in = min(fastmcp_access_expires_in, expires_in)
+
+        # Calculate refresh token expiry if provided by upstream
+        # Some providers include refresh_expires_in, some don't
+        refresh_expires_in = None
+        refresh_token_expires_at = None
+        if idp_tokens.get("refresh_token"):
+            if "refresh_expires_in" in idp_tokens and int(
+                idp_tokens["refresh_expires_in"]
+            ):
+                refresh_expires_in = int(idp_tokens["refresh_expires_in"])
+                refresh_token_expires_at = time.time() + refresh_expires_in
+                logger.debug(
+                    "Upstream refresh token expires in %d seconds", refresh_expires_in
+                )
+            else:
+                # Upstream didn't specify; use configured fallback (default 1 year).
+                # The FastMCP refresh JWT is just a signed pointer — if the real
+                # upstream refresh has expired or been revoked, the next refresh
+                # call to upstream will fail and the client re-auths.
+                refresh_expires_in = self._fallback_refresh_token_expiry_seconds
+                refresh_token_expires_at = time.time() + refresh_expires_in
+                logger.debug(
+                    "Upstream refresh token expiry unknown, using fallback %d seconds",
+                    refresh_expires_in,
+                )
+
+        # Encrypt and store upstream tokens
+        upstream_token_set = UpstreamTokenSet(
+            upstream_token_id=upstream_token_id,
+            access_token=idp_tokens["access_token"],
+            refresh_token=idp_tokens["refresh_token"]
+            if idp_tokens.get("refresh_token")
+            else None,
+            refresh_token_expires_at=refresh_token_expires_at,
+            expires_at=time.time() + expires_in,
+            token_type=idp_tokens.get("token_type", "Bearer"),
+            scope=" ".join(granted_scopes),
+            client_id=client.client_id or "",
+            created_at=time.time(),
+            raw_token_data=idp_tokens,
+        )
+        await self._upstream_token_store.put(
+            key=upstream_token_id,
+            value=upstream_token_set,
+            ttl=max(
+                refresh_expires_in or 0, expires_in, fastmcp_access_expires_in, 1
+            ),  # Keep until longest-lived token expires (min 1s for safety)
+        )
+        logger.debug("Stored encrypted upstream tokens (jti=%s)", access_jti[:8])
+
+        # Extract upstream claims to embed in FastMCP JWT (if subclass implements)
+        upstream_claims = await self._extract_upstream_claims(idp_tokens)
+
+        # Issue minimal FastMCP access token (just a reference via JTI)
+        if client.client_id is None:
+            raise TokenError("invalid_client", "Client ID is required")
+        fastmcp_access_token = self.jwt_issuer.issue_access_token(
+            client_id=client.client_id,
+            scopes=granted_scopes,
+            jti=access_jti,
+            expires_in=fastmcp_access_expires_in,
+            upstream_claims=upstream_claims,
+        )
+
+        # Issue minimal FastMCP refresh token if upstream provided one
+        # Use upstream refresh token expiry to align lifetimes
+        fastmcp_refresh_token = None
+        if refresh_jti and refresh_expires_in:
+            fastmcp_refresh_token = self.jwt_issuer.issue_refresh_token(
+                client_id=client.client_id,
+                scopes=granted_scopes,
+                jti=refresh_jti,
+                expires_in=refresh_expires_in,
+                upstream_claims=upstream_claims,
+            )
+
+        # Store JTI mappings
+        await self._jti_mapping_store.put(
+            key=access_jti,
+            value=JTIMapping(
+                jti=access_jti,
+                upstream_token_id=upstream_token_id,
+                created_at=time.time(),
+            ),
+            ttl=fastmcp_access_expires_in,  # Auto-expire with FastMCP access token
+        )
+        if refresh_jti:
+            await self._jti_mapping_store.put(
+                key=refresh_jti,
+                value=JTIMapping(
+                    jti=refresh_jti,
+                    upstream_token_id=upstream_token_id,
+                    created_at=time.time(),
+                ),
+                ttl=refresh_expires_in or self._fallback_refresh_token_expiry_seconds,
+            )
+
+        # Store refresh token metadata (keyed by hash for security)
+        if fastmcp_refresh_token and refresh_expires_in:
+            await self._refresh_token_store.put(
+                key=_hash_token(fastmcp_refresh_token),
+                value=RefreshTokenMetadata(
+                    client_id=client.client_id,
+                    scopes=granted_scopes,
+                    expires_at=int(time.time()) + refresh_expires_in,
+                    created_at=time.time(),
+                ),
+                ttl=refresh_expires_in,
+            )
+
+        logger.debug(
+            "Issued FastMCP tokens for client=%s (access_jti=%s, refresh_jti=%s)",
+            client.client_id,
+            access_jti[:8],
+            refresh_jti[:8] if refresh_jti else "none",
+        )
+
+        # Return FastMCP-issued tokens (NOT upstream tokens!)
+        return OAuthToken(
+            access_token=fastmcp_access_token,
+            token_type="Bearer",
+            expires_in=fastmcp_access_expires_in,
+            refresh_token=fastmcp_refresh_token,
+            scope=" ".join(granted_scopes),
+        )
+
+    # -------------------------------------------------------------------------
+    # Refresh Token Flow
+    # -------------------------------------------------------------------------
+
+    def _prepare_scopes_for_token_exchange(self, scopes: list[str]) -> list[str]:
+        """Prepare scopes for initial token exchange (auth code -> tokens).
+
+        Override this method to provide scopes during the authorization
+        code exchange. Some providers (like Azure) require scopes to be sent.
+
+        Args:
+            scopes: Scopes from the authorization request
+
+        Returns:
+            List of scopes to send, or empty list to omit scope parameter
+        """
+        return scopes
+
+    def _translate_scopes_from_idp(self, scopes: list[str]) -> list[str]:
+        """Translate IdP-returned scopes into the client-facing form.
+
+        Some IdPs (notably Azure) require scopes on the wire in a form that
+        differs from the form MCP clients use — e.g. Azure requires custom API
+        scopes to be prefixed with the application's identifier URI
+        (``api://{client_id}/read``) on outbound requests and echoes that same
+        prefixed form back in the token response. MCP clients, however, request
+        and recognize the short form (``read``) advertised via
+        ``/.well-known/oauth-authorization-server``.
+
+        This hook is the inverse of provider-specific outbound translation
+        (e.g. :meth:`AzureProvider._prefix_scopes_for_azure`). The default
+        implementation returns the scopes unchanged, which is correct for any
+        provider where IdP-wire scopes already match the client-facing form.
+
+        It is called once on each ``scope`` value parsed out of an IdP token
+        response, before that value is stored, embedded in the FastMCP JWT
+        scope claim, or echoed to the client. Applying the translation here
+        keeps storage, the issued JWT, and the response body consistent.
+
+        Args:
+            scopes: Scopes parsed from the IdP token response's ``scope`` field.
+
+        Returns:
+            List of scopes in the form clients expect.
+        """
+        return scopes
+
+    def _prepare_scopes_for_upstream_refresh(self, scopes: list[str]) -> list[str]:
+        """Prepare scopes for upstream token refresh request.
+
+        Override this method to transform scopes before sending to upstream provider.
+        For example, Azure needs to prefix scopes and add additional Graph scopes.
+
+        The scopes parameter represents what should be stored in the RefreshToken.
+        This method returns what should be sent to the upstream provider.
+
+        Args:
+            scopes: Base scopes that will be stored in RefreshToken
+
+        Returns:
+            Scopes to send to upstream provider (may be transformed/augmented)
+        """
+        return scopes
+
+    async def _extract_upstream_claims(
+        self, idp_tokens: dict[str, Any]
+    ) -> dict[str, Any] | None:
+        """Extract upstream claims to embed in FastMCP JWT.
+
+        Override this method to decode upstream tokens, call userinfo endpoints,
+        or otherwise extract claims that should be embedded in the FastMCP JWT
+        issued to MCP clients. This enables gateways to inspect upstream identity
+        information by decoding the JWT without server-side storage lookups.
+
+        Args:
+            idp_tokens: Full token response from upstream provider. Contains
+                access_token, and for OIDC providers may include id_token,
+                refresh_token, and other response fields.
+
+        Returns:
+            Dict of claims to embed in JWT under the "upstream_claims" key,
+            or None to not embed any upstream claims.
+
+        Example:
+            For Azure/Entra ID, you might decode the access_token JWT and
+            extract claims like sub, oid, name, preferred_username, email,
+            roles, and groups.
+        """
+        _ = idp_tokens
+        return None
+
+    async def load_refresh_token(
+        self,
+        client: OAuthClientInformationFull,
+        refresh_token: str,
+    ) -> RefreshToken | None:
+        """Load refresh token metadata from distributed storage.
+
+        Looks up by token hash and reconstructs the RefreshToken object.
+        Validates that the token belongs to the requesting client.
+        """
+        token_hash = _hash_token(refresh_token)
+        metadata = await self._refresh_token_store.get(key=token_hash)
+        if not metadata:
+            logger.warning(
+                "Refresh token not found for client=%s (token_hash=%s); it was "
+                "already rotated, expired, or revoked. Rejecting with invalid_grant, "
+                "which forces the client to re-authenticate.",
+                client.client_id,
+                token_hash[:8],
+            )
+            return None
+        # Verify token belongs to this client (prevents cross-client token usage)
+        if metadata.client_id != client.client_id:
+            logger.warning(
+                "Refresh token client_id mismatch: expected %s, got %s",
+                client.client_id,
+                metadata.client_id,
+            )
+            return None
+        return RefreshToken(
+            token=refresh_token,
+            client_id=metadata.client_id,
+            scopes=metadata.scopes,
+            expires_at=metadata.expires_at,
+        )
+
+    async def exchange_refresh_token(
+        self,
+        client: OAuthClientInformationFull,
+        refresh_token: RefreshToken,
+        scopes: list[str],
+    ) -> OAuthToken:
+        """Exchange FastMCP refresh token for new FastMCP access token.
+
+        Implements two-tier refresh:
+        1. Verify FastMCP refresh token
+        2. Look up upstream token via JTI mapping
+        3. Refresh upstream token with upstream provider
+        4. Update stored upstream token
+        5. Issue new FastMCP access token
+        6. Keep same FastMCP refresh token (unless upstream rotates)
+        """
+        # Verify FastMCP refresh token
+        try:
+            refresh_payload = self.jwt_issuer.verify_token(
+                refresh_token.token, expected_token_use="refresh"
+            )
+            refresh_jti = refresh_payload["jti"]
+        except Exception as e:
+            logger.debug("FastMCP refresh token validation failed: %s", e)
+            raise TokenError("invalid_grant", "Invalid refresh token") from e
+
+        # Look up upstream token via JTI mapping
+        jti_mapping = await self._jti_mapping_store.get(key=refresh_jti)
+        if not jti_mapping:
+            logger.error("JTI mapping not found for refresh token: %s", refresh_jti[:8])
+            raise TokenError("invalid_grant", "Refresh token mapping not found")
+
+        upstream_token_set = await self._upstream_token_store.get(
+            key=jti_mapping.upstream_token_id
+        )
+        if not upstream_token_set:
+            logger.error(
+                "Upstream token set not found: %s", jti_mapping.upstream_token_id[:8]
+            )
+            raise TokenError("invalid_grant", "Upstream token not found")
+
+        # Decrypt upstream refresh token
+        if not upstream_token_set.refresh_token:
+            logger.error("No upstream refresh token available")
+            raise TokenError("invalid_grant", "Refresh not supported for this token")
+
+        # Allow child classes to transform scopes before sending to upstream
+        # This enables provider-specific scope formatting (e.g., Azure prefixing)
+        # while keeping original scopes in storage
+        upstream_scopes = self._prepare_scopes_for_upstream_refresh(scopes)
+
+        try:
+            logger.debug("Refreshing upstream token (jti=%s)", refresh_jti[:8])
+            async with self._upstream_oauth_client() as oauth_client:
+                token_response: dict[str, Any] = await oauth_client.refresh_token(
+                    url=self._upstream_token_endpoint,
+                    refresh_token=upstream_token_set.refresh_token,
+                    scope=" ".join(upstream_scopes) if upstream_scopes else None,
+                    **self._extra_token_params,
+                )
+            logger.debug("Successfully refreshed upstream token")
+        except Exception as e:
+            logger.error("Upstream token refresh failed: %s", e)
+            raise TokenError("invalid_grant", f"Upstream refresh failed: {e}") from e
+
+        # Update stored upstream token
+        # In refresh flow, we know there's a refresh token, so default to 1 hour
+        # (user override still applies if set)
+        if "expires_in" in token_response:
+            new_expires_in = int(token_response["expires_in"])
+            logger.debug(
+                "Refreshed access token TTL: %d seconds (from IdP expires_in)",
+                new_expires_in,
+            )
+        elif self._fallback_access_token_expiry_seconds is not None:
+            new_expires_in = self._fallback_access_token_expiry_seconds
+            logger.debug(
+                "Refreshed access token TTL: %d seconds (using configured fallback)",
+                new_expires_in,
+            )
+        else:
+            new_expires_in = DEFAULT_ACCESS_TOKEN_EXPIRY_SECONDS
+            logger.debug(
+                "Refreshed access token TTL: %d seconds (default)", new_expires_in
+            )
+        upstream_token_set.access_token = token_response["access_token"]
+        upstream_token_set.expires_at = time.time() + new_expires_in
+
+        # See exchange_authorization_code: the FastMCP access token may outlive the
+        # upstream one. `new_expires_in` stays the upstream lifetime (drives
+        # upstream_token_set.expires_at and transparent refresh).
+        fastmcp_access_expires_in = (
+            self._fastmcp_access_token_expiry_seconds
+            if self._fastmcp_access_token_expiry_seconds is not None
+            else new_expires_in
+        )
+
+        # Prefer IdP-granted scopes from refresh response (RFC 6749 §5.1)
+        refreshed_scopes: list[str] = (
+            parse_scopes(token_response["scope"]) or []
+            if "scope" in token_response
+            else scopes
+        )
+        # Same translation as in exchange_authorization_code — keep storage,
+        # the rotated FastMCP JWT, and the response body all in client-facing
+        # scope form.
+        refreshed_scopes = self._translate_scopes_from_idp(refreshed_scopes)
+        upstream_token_set.scope = " ".join(refreshed_scopes)
+
+        # Handle upstream refresh token rotation and expiry
+        new_refresh_expires_in = None
+        if new_upstream_refresh := token_response.get("refresh_token"):
+            if new_upstream_refresh != upstream_token_set.refresh_token:
+                upstream_token_set.refresh_token = new_upstream_refresh
+                logger.debug("Upstream refresh token rotated")
+
+            # Update refresh token expiry if provided
+            if "refresh_expires_in" in token_response and int(
+                token_response["refresh_expires_in"]
+            ):
+                new_refresh_expires_in = int(token_response["refresh_expires_in"])
+                upstream_token_set.refresh_token_expires_at = (
+                    time.time() + new_refresh_expires_in
+                )
+                logger.debug(
+                    "Upstream refresh token expires in %d seconds",
+                    new_refresh_expires_in,
+                )
+            elif upstream_token_set.refresh_token_expires_at:
+                # Keep existing expiry if upstream doesn't provide new one
+                new_refresh_expires_in = int(
+                    upstream_token_set.refresh_token_expires_at - time.time()
+                )
+            else:
+                # Upstream rotated the refresh token but gave no expiry; use fallback
+                new_refresh_expires_in = self._fallback_refresh_token_expiry_seconds
+                upstream_token_set.refresh_token_expires_at = (
+                    time.time() + new_refresh_expires_in
+                )
+
+        upstream_token_set.raw_token_data = {
+            **upstream_token_set.raw_token_data,
+            **token_response,
+        }
+        # Calculate refresh TTL for storage
+        refresh_ttl = new_refresh_expires_in or (
+            int(upstream_token_set.refresh_token_expires_at - time.time())
+            if upstream_token_set.refresh_token_expires_at
+            else self._fallback_refresh_token_expiry_seconds
+        )
+        # Guard against past expiry (e.g. existing upstream refresh has already
+        # ticked past its recorded expiry). Storage TTL must be > 0.
+        refresh_ttl = max(refresh_ttl, 1)
+        await self._upstream_token_store.put(
+            key=upstream_token_set.upstream_token_id,
+            value=upstream_token_set,
+            ttl=max(
+                refresh_ttl, new_expires_in, fastmcp_access_expires_in, 1
+            ),  # Keep until longest-lived token expires (min 1s for safety)
+        )
+
+        # Re-extract upstream claims from refreshed token response
+        upstream_claims = await self._extract_upstream_claims(
+            upstream_token_set.raw_token_data
+        )
+
+        # Issue new minimal FastMCP access token (just a reference via JTI)
+        if client.client_id is None:
+            raise TokenError("invalid_client", "Client ID is required")
+        new_access_jti = secrets.token_urlsafe(32)
+        new_fastmcp_access = self.jwt_issuer.issue_access_token(
+            client_id=client.client_id,
+            scopes=refreshed_scopes,
+            jti=new_access_jti,
+            expires_in=fastmcp_access_expires_in,
+            upstream_claims=upstream_claims,
+        )
+
+        # Store new access token JTI mapping
+        await self._jti_mapping_store.put(
+            key=new_access_jti,
+            value=JTIMapping(
+                jti=new_access_jti,
+                upstream_token_id=upstream_token_set.upstream_token_id,
+                created_at=time.time(),
+            ),
+            ttl=fastmcp_access_expires_in,  # Auto-expire with FastMCP access token
+        )
+
+        # Issue NEW minimal FastMCP refresh token (rotation for security).
+        # Use refresh_ttl so the JWT exp claim matches the storage TTL — otherwise
+        # providers that don't rotate the refresh token (e.g. Cognito) would get
+        # a JWT with a hardcoded short exp even when the upstream refresh is
+        # still valid for much longer.
+        new_refresh_jti = secrets.token_urlsafe(32)
+        new_fastmcp_refresh = self.jwt_issuer.issue_refresh_token(
+            client_id=client.client_id,
+            scopes=refreshed_scopes,
+            jti=new_refresh_jti,
+            expires_in=refresh_ttl,
+            upstream_claims=upstream_claims,
+        )
+
+        # Store new refresh token JTI mapping with aligned expiry
+        # (reuse refresh_ttl calculated above for upstream token store)
+        await self._jti_mapping_store.put(
+            key=new_refresh_jti,
+            value=JTIMapping(
+                jti=new_refresh_jti,
+                upstream_token_id=upstream_token_set.upstream_token_id,
+                created_at=time.time(),
+            ),
+            ttl=refresh_ttl,  # Align with upstream refresh token expiry
+        )
+
+        # Invalidate old refresh token (refresh token rotation - enforces one-time use)
+        await self._jti_mapping_store.delete(key=refresh_jti)
+        logger.debug(
+            "Rotated refresh token (old JTI invalidated - one-time use enforced)"
+        )
+
+        # Store new refresh token metadata (keyed by hash)
+        await self._refresh_token_store.put(
+            key=_hash_token(new_fastmcp_refresh),
+            value=RefreshTokenMetadata(
+                client_id=client.client_id,
+                scopes=refreshed_scopes,
+                expires_at=int(time.time()) + refresh_ttl,
+                created_at=time.time(),
+            ),
+            ttl=refresh_ttl,
+        )
+
+        # Delete old refresh token (by hash)
+        await self._refresh_token_store.delete(key=_hash_token(refresh_token.token))
+
+        logger.info(
+            "Issued new FastMCP tokens (rotated refresh) for client=%s (access_jti=%s, refresh_jti=%s)",
+            client.client_id,
+            new_access_jti[:8],
+            new_refresh_jti[:8],
+        )
+
+        # Return new FastMCP tokens (both access AND refresh are new)
+        return OAuthToken(
+            access_token=new_fastmcp_access,
+            token_type="Bearer",
+            expires_in=fastmcp_access_expires_in,
+            refresh_token=new_fastmcp_refresh,  # NEW refresh token (rotated)
+            scope=" ".join(refreshed_scopes),
+        )
+
+    # -------------------------------------------------------------------------
+    # Token Validation
+    # -------------------------------------------------------------------------
+
+    def _get_verification_token(
+        self, upstream_token_set: UpstreamTokenSet
+    ) -> str | None:
+        """Get the token string to pass to the token verifier.
+
+        Returns the upstream access token by default. Subclasses can override
+        to verify a different token (e.g., the OIDC id_token for providers
+        that issue opaque access tokens).
+        """
+        return upstream_token_set.access_token
+
+    def _uses_alternate_verification(self) -> bool:
+        """Whether this provider verifies a different token than the access token.
+
+        When True, ``load_access_token`` patches the validated result with
+        the upstream access token, scopes, and expiry so that the returned
+        ``AccessToken`` reflects the access token rather than the
+        verification token.
+
+        The default implementation compares token values, but subclasses
+        should override this to use an intent-based flag so the patch is
+        applied even when the verification token and access token happen to
+        carry the same value (e.g., some OIDC providers issue identical
+        JWTs for both).
+        """
+        return False
+
+    async def _try_transparent_refresh(
+        self,
+        upstream_token_set: UpstreamTokenSet,
+    ) -> UpstreamTokenSet:
+        """Refresh the upstream token transparently and update storage.
+
+        Called during load_access_token when the upstream token has expired
+        but a refresh token is available. This avoids returning a 401 that
+        would force the client into a full re-authentication flow.
+
+        Mutates and returns the upstream_token_set with refreshed token data.
+        Raises on failure (caller should catch and fall through to None).
+        """
+        scopes = upstream_token_set.scope.split() if upstream_token_set.scope else []
+        upstream_scopes = self._prepare_scopes_for_upstream_refresh(scopes)
+
+        async with self._upstream_oauth_client() as oauth_client:
+            token_response: dict[str, Any] = await oauth_client.refresh_token(
+                url=self._upstream_token_endpoint,
+                refresh_token=upstream_token_set.refresh_token,
+                scope=" ".join(upstream_scopes) if upstream_scopes else None,
+                **self._extra_token_params,
+            )
+        logger.debug(
+            "Transparent upstream refresh succeeded (token_id=%s)",
+            upstream_token_set.upstream_token_id[:8],
+        )
+
+        # Calculate new expiry
+        if "expires_in" in token_response:
+            new_expires_in = int(token_response["expires_in"])
+        elif self._fallback_access_token_expiry_seconds is not None:
+            new_expires_in = self._fallback_access_token_expiry_seconds
+        else:
+            new_expires_in = DEFAULT_ACCESS_TOKEN_EXPIRY_SECONDS
+
+        upstream_token_set.access_token = token_response["access_token"]
+        upstream_token_set.expires_at = time.time() + new_expires_in
+        refreshed_scopes = (
+            parse_scopes(token_response["scope"]) or []
+            if "scope" in token_response
+            else scopes
+        )
+        upstream_token_set.scope = " ".join(
+            self._translate_scopes_from_idp(refreshed_scopes)
+        )
+
+        # Handle upstream refresh token rotation
+        new_refresh_expires_in = None
+        if new_upstream_refresh := token_response.get("refresh_token"):
+            if new_upstream_refresh != upstream_token_set.refresh_token:
+                upstream_token_set.refresh_token = new_upstream_refresh
+            if "refresh_expires_in" in token_response and int(
+                token_response["refresh_expires_in"]
+            ):
+                new_refresh_expires_in = int(token_response["refresh_expires_in"])
+                upstream_token_set.refresh_token_expires_at = (
+                    time.time() + new_refresh_expires_in
+                )
+            elif upstream_token_set.refresh_token_expires_at:
+                new_refresh_expires_in = int(
+                    upstream_token_set.refresh_token_expires_at - time.time()
+                )
+            else:
+                new_refresh_expires_in = self._fallback_refresh_token_expiry_seconds
+                upstream_token_set.refresh_token_expires_at = (
+                    time.time() + new_refresh_expires_in
+                )
+
+        upstream_token_set.raw_token_data = {
+            **upstream_token_set.raw_token_data,
+            **token_response,
+        }
+
+        refresh_ttl = new_refresh_expires_in or (
+            int(upstream_token_set.refresh_token_expires_at - time.time())
+            if upstream_token_set.refresh_token_expires_at
+            else self._fallback_refresh_token_expiry_seconds
+        )
+        await self._upstream_token_store.put(
+            key=upstream_token_set.upstream_token_id,
+            value=upstream_token_set,
+            # Include the configured FastMCP lifetime so the upstream token never
+            # expires before an extended access JTI mapping that still points at it.
+            ttl=max(
+                refresh_ttl,
+                new_expires_in,
+                self._fastmcp_access_token_expiry_seconds or 0,
+                1,
+            ),
+        )
+
+        return upstream_token_set
+
+    async def load_access_token(self, token: str) -> AccessToken | None:  # type: ignore[override]  # ty:ignore[invalid-method-override]
+        """Validate FastMCP JWT by swapping for upstream token.
+
+        This implements the token swap pattern:
+        1. Verify FastMCP JWT signature (proves it's our token)
+        2. Look up upstream token via JTI mapping
+        3. Decrypt upstream token
+        4. Validate upstream token with provider (GitHub API, JWT validation, etc.)
+        5. If upstream validation fails, attempt transparent refresh
+        6. Return upstream validation result
+
+        The FastMCP JWT is a reference token - all authorization data comes
+        from validating the upstream token via the TokenVerifier.
+        """
+        try:
+            # 1. Verify FastMCP JWT signature and claims
+            payload = self.jwt_issuer.verify_token(token)
+            jti = payload["jti"]
+            upstream_claims = payload.get("upstream_claims")
+
+            # 2. Look up upstream token via JTI mapping
+            jti_mapping = await self._jti_mapping_store.get(key=jti)
+            if not jti_mapping:
+                logger.info(
+                    "JTI mapping not found (token may have expired): jti=%s...",
+                    jti[:16],
+                )
+                return None
+
+            upstream_token_set = await self._upstream_token_store.get(
+                key=jti_mapping.upstream_token_id
+            )
+            if not upstream_token_set:
+                logger.debug(
+                    "Upstream token not found: %s", jti_mapping.upstream_token_id
+                )
+                return None
+
+            # 3. Validate with upstream provider (delegated to TokenVerifier)
+            # This calls the real token validator (GitHub API, JWKS, etc.)
+            verification_token = self._get_verification_token(upstream_token_set)
+            if verification_token is None:
+                logger.debug("No verification token available")
+                return None
+            validated = await self._token_validator.verify_token(verification_token)
+
+            # 4. Determine if refresh is needed. Two cases:
+            #    a) Validation failed and token is expired/within threshold
+            #    b) Validation passed but token is within threshold (proactive)
+            needs_refresh = upstream_token_set.refresh_token and (
+                upstream_token_set.expires_at
+                <= time.time() + self._token_expiry_threshold_seconds
+            )
+            should_refresh = needs_refresh and (
+                not validated
+                or (validated and self._token_expiry_threshold_seconds > 0)
+            )
+
+            if should_refresh:
+                try:
+                    token_id = upstream_token_set.upstream_token_id
+
+                    # Advisory lock prevents concurrent requests from racing
+                    # to refresh the same upstream token.
+                    lock = self._get_refresh_lock(token_id)
+
+                    async with lock:
+                        # Re-read from storage — another task may have
+                        # already refreshed while we waited for the lock.
+                        upstream_token_set = (
+                            await self._upstream_token_store.get(key=token_id)
+                            or upstream_token_set
+                        )
+
+                        verification_token = self._get_verification_token(
+                            upstream_token_set
+                        )
+                        if verification_token is not None:
+                            validated = await self._token_validator.verify_token(
+                                verification_token
+                            )
+
+                        # Only refresh if the (possibly reloaded) token is
+                        # still within threshold — a freshly-refreshed token
+                        # doesn't need another refresh.
+                        if (
+                            upstream_token_set.expires_at
+                            <= time.time() + self._token_expiry_threshold_seconds
+                        ):
+                            upstream_token_set = await self._try_transparent_refresh(
+                                upstream_token_set
+                            )
+                            verification_token = self._get_verification_token(
+                                upstream_token_set
+                            )
+                            if verification_token is not None:
+                                validated = await self._token_validator.verify_token(
+                                    verification_token
+                                )
+                except Exception as e:
+                    logger.debug("Transparent upstream refresh failed: %s", e)
+                    # In a distributed deployment, another worker may have
+                    # already refreshed and rotated the token, causing our
+                    # stale refresh token to fail. Re-read and re-validate.
+                    try:
+                        reloaded = await self._upstream_token_store.get(
+                            key=upstream_token_set.upstream_token_id
+                        )
+                        if reloaded:
+                            verification_token = self._get_verification_token(reloaded)
+                            if verification_token is not None:
+                                validated = await self._token_validator.verify_token(
+                                    verification_token
+                                )
+                                if validated:
+                                    upstream_token_set = reloaded
+                    except Exception:
+                        pass
+
+            if not validated:
+                logger.debug("Upstream token validation failed")
+                return None
+
+            # When alternate verification is in use (e.g., id_token
+            # verification in OIDCProxy), ensure the returned AccessToken
+            # carries the upstream access token and its scopes, not the
+            # verification token's values.  We use an intent-based check
+            # rather than value equality because some IdPs issue identical
+            # JWTs for both access_token and id_token, which would cause
+            # the scope patch to be skipped even though it's needed.
+            if self._uses_alternate_verification():
+                validated = validated.model_copy(
+                    update={
+                        "token": upstream_token_set.access_token,
+                        "scopes": upstream_token_set.scope.split()
+                        if upstream_token_set.scope
+                        else validated.scopes,
+                        "expires_at": int(upstream_token_set.expires_at),
+                    }
+                )
+
+            # Propagate upstream claims from the verified FastMCP JWT into the
+            # final AccessToken object. This allows subclasses to access custom
+            # identity data extracted during the initial authorization flow.
+            # We perform a model copy to avoid mutating a potentially cached
+            # reference shared across concurrent requests.
+            if validated and upstream_claims:
+                validated = validated.model_copy(deep=True)
+                if validated.claims is None:
+                    validated.claims = {}
+                validated.claims["upstream_claims"] = upstream_claims
+
+            logger.debug(
+                "Token swap successful for JTI=%s (upstream validated)", jti[:8]
+            )
+            return validated
+
+        except Exception as e:
+            logger.debug("Token swap validation failed: %s", e)
+            return None
+
+    # -------------------------------------------------------------------------
+    # Token Revocation
+    # -------------------------------------------------------------------------
+
+    async def revoke_token(self, token: AccessToken | RefreshToken) -> None:
+        """Revoke token locally and with upstream server if supported.
+
+        For refresh tokens, removes from local storage by hash.
+        For all tokens, attempts upstream revocation if endpoint is configured.
+        Access token JTI mappings expire via TTL.
+        """
+        # For refresh tokens, delete from local storage by hash
+        if isinstance(token, RefreshToken):
+            await self._refresh_token_store.delete(key=_hash_token(token.token))
+
+        # Attempt upstream revocation if endpoint is configured
+        if self._upstream_revocation_endpoint:
+            try:
+                async with httpx.AsyncClient(
+                    timeout=HTTP_TIMEOUT_SECONDS
+                ) as http_client:
+                    revocation_data: dict[str, str] = {"token": token.token}
+                    request_kwargs: dict[str, Any] = {"data": revocation_data}
+
+                    # Use the factory method when available (supports alternative auth like
+                    # client assertions for managed identity), falling back to basic auth
+                    # or client_id-only for public clients per RFC 7009
+                    async with self._upstream_oauth_client() as oauth_client:
+                        if oauth_client.client_secret is not None:
+                            # Client secret is available, use HTTP Basic auth
+                            request_kwargs["auth"] = (
+                                self._upstream_client_id,
+                                oauth_client.client_secret,
+                            )
+                        else:
+                            # No secret; public client must still identify itself per RFC 7009
+                            revocation_data["client_id"] = self._upstream_client_id
+
+                    await http_client.post(
+                        self._upstream_revocation_endpoint,
+                        **request_kwargs,
+                    )
+                    logger.debug("Successfully revoked token with upstream server")
+            except Exception as e:
+                logger.warning("Failed to revoke token with upstream server: %s", e)
+        else:
+            logger.debug("No upstream revocation endpoint configured")
+
+        logger.debug("Token revoked successfully")
+
+    def get_routes(
+        self,
+        mcp_path: str | None = None,
+    ) -> list[Route]:
+        """Get OAuth routes with custom handlers for better error UX.
+
+        This method creates standard OAuth routes and replaces:
+        - /authorize endpoint: Enhanced error responses for unregistered clients
+        - /token endpoint: OAuth 2.1 compliant error codes
+
+        Args:
+            mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
+                This is used to advertise the resource URL in metadata.
+        """
+        # Get standard OAuth routes from parent class
+        # Note: parent already replaces /token with TokenHandler for proper error codes
+        routes = super().get_routes(mcp_path)
+        custom_routes = []
+
+        logger.debug(
+            f"get_routes called - configuring OAuth routes in {len(routes)} routes"
+        )
+
+        for i, route in enumerate(routes):
+            logger.debug(
+                f"Route {i}: {route} - path: {getattr(route, 'path', 'N/A')}, methods: {getattr(route, 'methods', 'N/A')}"
+            )
+
+            # Replace the authorize endpoint with our enhanced handler for better error UX
+            if (
+                isinstance(route, Route)
+                and route.path == "/authorize"
+                and route.methods is not None
+                and ("GET" in route.methods or "POST" in route.methods)
+            ):
+                # Replace with our enhanced authorization handler
+                # Note: self.base_url is guaranteed to be set in parent __init__
+                authorize_handler = AuthorizationHandler(
+                    provider=self,
+                    base_url=self.base_url,  # ty: ignore[invalid-argument-type]
+                    server_name=None,  # Could be extended to pass server metadata
+                    server_icon_url=None,
+                )
+                custom_routes.append(
+                    Route(
+                        path="/authorize",
+                        endpoint=authorize_handler.handle,
+                        methods=["GET", "POST"],
+                    )
+                )
+            elif (
+                self._cimd_manager is not None
+                and isinstance(route, Route)
+                and route.path == "/token"
+                and route.methods is not None
+                and "POST" in route.methods
+            ):
+                # Replace the token endpoint authenticator with one that supports
+                # private_key_jwt for CIMD clients
+                token_endpoint_url = f"{self.base_url}/token"
+                cimd_authenticator = PrivateKeyJWTClientAuthenticator(
+                    provider=self,
+                    cimd_manager=self._cimd_manager,
+                    token_endpoint_url=token_endpoint_url,
+                )
+                token_handler = TokenHandler(
+                    provider=self, client_authenticator=cimd_authenticator
+                )
+                custom_routes.append(
+                    Route(
+                        path="/token",
+                        endpoint=cors_middleware(
+                            token_handler.handle, ["POST", "OPTIONS"]
+                        ),
+                        methods=["POST", "OPTIONS"],
+                    )
+                )
+            elif (
+                self._cimd_manager is not None
+                and isinstance(route, Route)
+                and route.path.startswith("/.well-known/oauth-authorization-server")
+            ):
+                client_registration_options = (
+                    self.client_registration_options or ClientRegistrationOptions()
+                )
+                revocation_options = self.revocation_options or RevocationOptions()
+                metadata = build_metadata(
+                    self.base_url,  # ty: ignore[invalid-argument-type]
+                    self.service_documentation_url,
+                    client_registration_options,
+                    revocation_options,
+                )
+                metadata.client_id_metadata_document_supported = True
+                existing = metadata.token_endpoint_auth_methods_supported or []
+                metadata.token_endpoint_auth_methods_supported = [
+                    *existing,
+                    "private_key_jwt",
+                    "none",
+                ]
+                handler = MetadataHandler(metadata)
+                methods = route.methods or ["GET", "OPTIONS"]
+
+                custom_routes.append(
+                    Route(
+                        path=route.path,
+                        endpoint=cors_middleware(handler.handle, ["GET", "OPTIONS"]),
+                        methods=methods,
+                        name=route.name,
+                        include_in_schema=route.include_in_schema,
+                    )
+                )
+            else:
+                # Keep all other standard OAuth routes unchanged
+                custom_routes.append(route)
+
+        # Add OAuth callback endpoint for forwarding to client callbacks
+        custom_routes.append(
+            Route(
+                path=self._redirect_path,
+                endpoint=self._handle_idp_callback,
+                methods=["GET"],
+            )
+        )
+
+        # Add consent endpoints
+        # Handle both GET (show page) and POST (submit) at /consent
+        custom_routes.append(
+            Route(
+                path="/consent", endpoint=self._handle_consent, methods=["GET", "POST"]
+            )
+        )
+
+        return custom_routes
+
+    # -------------------------------------------------------------------------
+    # IdP Callback Forwarding
+    # -------------------------------------------------------------------------
+
+    async def _handle_idp_callback(
+        self, request: Request
+    ) -> HTMLResponse | RedirectResponse:
+        """Handle callback from upstream IdP and forward to client.
+
+        This implements the DCR-compliant callback forwarding:
+        1. Receive IdP callback with code and txn_id as state
+        2. Exchange IdP code for tokens (server-side)
+        3. Generate our own client code bound to PKCE challenge
+        4. Redirect to client's callback with client code and original state
+        """
+        try:
+            idp_code = request.query_params.get("code")
+            txn_id = request.query_params.get("state")
+            error = request.query_params.get("error")
+
+            if not idp_code and not error:
+                logger.error("IdP callback missing code or transaction ID")
+                html_content = create_error_html(
+                    error_title="OAuth Error",
+                    error_message="Missing authorization code or transaction ID from the identity provider.",
+                )
+                return HTMLResponse(content=html_content, status_code=400)
+
+            # Look up transaction data
+            transaction_model = (
+                await self._transaction_store.get(key=txn_id) if txn_id else None
+            )
+
+            if error:
+                error_description = request.query_params.get("error_description")
+                logger.error(
+                    "IdP callback error: %s - %s",
+                    error,
+                    error_description,
+                )
+                if transaction_model:
+                    # Forward the error to the client's redirect_uri (RFC 6749 §4.1.2.1)
+                    client_redirect_uri = transaction_model.client_redirect_uri
+                    if not self._validate_client_redirect_uri(client_redirect_uri):
+                        logger.warning(
+                            "Blocked IdP callback error redirect to disallowed URI "
+                            "for transaction %s",
+                            txn_id,
+                        )
+                        html_content = create_error_html(
+                            error_title="OAuth Error",
+                            error_message="Invalid redirect URI",
+                        )
+                        return HTMLResponse(content=html_content, status_code=400)
+
+                    error_params: dict[str, str] = {
+                        "error": error,
+                        "state": transaction_model.client_state,
+                    }
+                    if error_description:
+                        error_params["error_description"] = error_description
+                    separator = "&" if "?" in client_redirect_uri else "?"
+                    return RedirectResponse(
+                        url=f"{client_redirect_uri}{separator}{urlencode(error_params)}",
+                        status_code=302,
+                    )
+                # No trusted redirect_uri available — show local error page
+                html_content = create_error_html(
+                    error_title="OAuth Error",
+                    error_message=f"Authentication failed: {error_description or 'Unknown error'}",
+                    error_details={"Error Code": error},
+                )
+                return HTMLResponse(content=html_content, status_code=400)
+            if not txn_id or not transaction_model:
+                logger.error("IdP callback with invalid transaction ID: %s", txn_id)
+                html_content = create_error_html(
+                    error_title="OAuth Error",
+                    error_message="Invalid or expired authorization transaction. Please try authenticating again.",
+                )
+                return HTMLResponse(content=html_content, status_code=400)
+
+            if not self._validate_client_redirect_uri(
+                transaction_model.client_redirect_uri
+            ):
+                logger.warning(
+                    "Blocked IdP callback redirect to disallowed URI for transaction %s",
+                    txn_id,
+                )
+                html_content = create_error_html(
+                    error_title="OAuth Error",
+                    error_message="Invalid redirect URI",
+                )
+                return HTMLResponse(content=html_content, status_code=400)
+
+            # Verify consent binding cookie to prevent confused deputy attacks.
+            # When consent is enabled, the browser that approved consent receives
+            # a signed cookie. A different browser (e.g., a victim lured to the
+            # IdP URL) won't have this cookie and will be rejected. "remember"
+            # mode still issues consent tokens (on silent approval or HTML
+            # approval), so both code paths need binding verification.
+            if self._require_authorization_consent in (True, "remember"):
+                consent_token = transaction_model.consent_token
+                if not consent_token:
+                    logger.error("Transaction %s missing consent_token", txn_id)
+                    html_content = create_error_html(
+                        error_title="Authorization Error",
+                        error_message="Invalid authorization flow. Please try authenticating again.",
+                    )
+                    return HTMLResponse(content=html_content, status_code=403)
+
+                if not self._verify_consent_binding_cookie(
+                    request, txn_id, consent_token
+                ):
+                    logger.warning(
+                        "Consent binding cookie missing or invalid for transaction %s "
+                        "(possible confused deputy attack)",
+                        txn_id,
+                    )
+                    html_content = create_error_html(
+                        error_title="Authorization Error",
+                        error_message=(
+                            "Authorization session mismatch. This can happen if you "
+                            "followed a link from another person or your session expired. "
+                            "Please try authenticating again."
+                        ),
+                    )
+                    return HTMLResponse(content=html_content, status_code=403)
+
+            transaction = transaction_model.model_dump()
+
+            try:
+                idp_redirect_uri = (
+                    f"{str(self.base_url).rstrip('/')}{self._redirect_path}"
+                )
+                logger.debug(
+                    f"Exchanging IdP code for tokens with redirect_uri: {idp_redirect_uri}"
+                )
+
+                # Build token exchange parameters
+                token_params = {
+                    "url": self._upstream_token_endpoint,
+                    "code": idp_code,
+                    "redirect_uri": idp_redirect_uri,
+                }
+
+                # Include proxy's code_verifier if we forwarded PKCE
+                proxy_code_verifier = transaction.get("proxy_code_verifier")
+                if proxy_code_verifier:
+                    token_params["code_verifier"] = proxy_code_verifier
+                    logger.debug(
+                        "Including proxy code_verifier in token exchange for transaction %s",
+                        txn_id,
+                    )
+
+                # Allow providers to specify scope for token exchange
+                exchange_scopes = self._prepare_scopes_for_token_exchange(
+                    transaction.get("scopes") or []
+                )
+                if exchange_scopes:
+                    token_params["scope"] = " ".join(exchange_scopes)
+
+                # Add any extra token parameters configured for this proxy
+                if self._extra_token_params:
+                    token_params.update(self._extra_token_params)
+                    logger.debug(
+                        "Adding extra token parameters for transaction %s: %s",
+                        txn_id,
+                        list(self._extra_token_params.keys()),
+                    )
+
+                # Exchange IdP code for tokens (server-side)
+                async with self._upstream_oauth_client() as oauth_client:
+                    idp_tokens: dict[str, Any] = await oauth_client.fetch_token(
+                        **token_params
+                    )
+
+                logger.debug(
+                    f"Successfully exchanged IdP code for tokens (transaction: {txn_id}, PKCE: {bool(proxy_code_verifier)})"
+                )
+                logger.debug(
+                    "IdP token response: expires_in=%s, has_refresh_token=%s",
+                    idp_tokens.get("expires_in"),
+                    "refresh_token" in idp_tokens,
+                )
+
+            except Exception as e:
+                logger.error("IdP token exchange failed: %s", e)
+                html_content = create_error_html(
+                    error_title="OAuth Error",
+                    error_message=f"Token exchange with identity provider failed: {e}",
+                )
+                return HTMLResponse(content=html_content, status_code=500)
+
+            # Generate our own authorization code for the client
+            client_code = secrets.token_urlsafe(32)
+            code_expires_at = int(time.time() + DEFAULT_AUTH_CODE_EXPIRY_SECONDS)
+
+            # Store client code with PKCE challenge and IdP tokens
+            await self._code_store.put(
+                key=client_code,
+                value=ClientCode(
+                    code=client_code,
+                    client_id=transaction["client_id"],
+                    redirect_uri=transaction["client_redirect_uri"],
+                    code_challenge=transaction["code_challenge"],
+                    code_challenge_method=transaction["code_challenge_method"],
+                    scopes=transaction["scopes"],
+                    idp_tokens=idp_tokens,
+                    expires_at=code_expires_at,
+                    created_at=time.time(),
+                ),
+                ttl=DEFAULT_AUTH_CODE_EXPIRY_SECONDS,  # Auto-expire after 5 minutes
+            )
+
+            # Clean up transaction
+            await self._transaction_store.delete(key=txn_id)
+
+            # Build client callback URL with our code and original state
+            client_redirect_uri = transaction["client_redirect_uri"]
+            client_state = transaction["client_state"]
+
+            callback_params = {
+                "code": client_code,
+                "state": client_state,
+            }
+
+            # Add query parameters to client redirect URI
+            separator = "&" if "?" in client_redirect_uri else "?"
+            client_callback_url = (
+                f"{client_redirect_uri}{separator}{urlencode(callback_params)}"
+            )
+
+            logger.debug(f"Forwarding to client callback for transaction {txn_id}")
+
+            response = RedirectResponse(url=client_callback_url, status_code=302)
+            self._clear_consent_binding_cookie(request, response, txn_id)
+            return response
+
+        except Exception as e:
+            logger.error("Error in IdP callback handler: %s", e, exc_info=True)
+            html_content = create_error_html(
+                error_title="OAuth Error",
+                error_message="Internal server error during OAuth callback processing. Please try again.",
+            )
+            return HTMLResponse(content=html_content, status_code=500)
diff --git a/fastmcp_slim/fastmcp/server/auth/oauth_proxy/ui.py b/fastmcp_slim/fastmcp/server/auth/oauth_proxy/ui.py
new file mode 100644
index 0000000..4ae6b5f
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/oauth_proxy/ui.py
@@ -0,0 +1,300 @@
+"""OAuth Proxy UI Generation Functions.
+
+This module contains HTML generation functions for consent and error pages.
+"""
+
+from __future__ import annotations
+
+from fastmcp.utilities.ui import (
+    BUTTON_STYLES,
+    DETAIL_BOX_STYLES,
+    DETAILS_STYLES,
+    INFO_BOX_STYLES,
+    REDIRECT_SECTION_STYLES,
+    TOOLTIP_STYLES,
+    create_logo,
+    create_page,
+)
+
+
+def create_consent_html(
+    client_id: str,
+    redirect_uri: str,
+    scopes: list[str],
+    txn_id: str,
+    csrf_token: str,
+    client_name: str | None = None,
+    title: str = "Application Access Request",
+    server_name: str | None = None,
+    server_icon_url: str | None = None,
+    server_website_url: str | None = None,
+    client_website_url: str | None = None,
+    csp_policy: str | None = None,
+    is_cimd_client: bool = False,
+    cimd_domain: str | None = None,
+) -> str:
+    """Create a styled HTML consent page for OAuth authorization requests.
+
+    Args:
+        csp_policy: Content Security Policy override.
+            If None, uses the built-in CSP policy with appropriate directives.
+            If empty string "", disables CSP entirely (no meta tag is rendered).
+            If a non-empty string, uses that as the CSP policy value.
+    """
+    import html as html_module
+
+    client_display = html_module.escape(client_name or client_id)
+    server_name_escaped = html_module.escape(server_name or "FastMCP")
+
+    # Make server name a hyperlink if website URL is available
+    if server_website_url:
+        website_url_escaped = html_module.escape(server_website_url)
+        server_display = f'<a href="{website_url_escaped}" target="_blank" rel="noopener noreferrer" class="server-name-link">{server_name_escaped}</a>'
+    else:
+        server_display = server_name_escaped
+
+    # Build intro box with call-to-action
+    intro_box = f"""
+        <div class="info-box">
+            <p>The application <strong>{client_display}</strong> wants to access the MCP server <strong>{server_display}</strong>. Please ensure you recognize the callback address below.</p>
+        </div>
+    """
+
+    # Build CIMD verified domain badge if applicable
+    cimd_badge = ""
+    if is_cimd_client and cimd_domain:
+        cimd_domain_escaped = html_module.escape(cimd_domain)
+        cimd_badge = f"""
+        <div class="cimd-badge">
+            <span class="cimd-check">&#x2713;</span>
+            Verified domain: <strong>{cimd_domain_escaped}</strong>
+        </div>
+        """
+
+    # Build redirect URI section (yellow box, centered)
+    redirect_uri_escaped = html_module.escape(redirect_uri)
+    redirect_section = f"""
+        <div class="redirect-section">
+            <span class="label">Credentials will be sent to:</span>
+            <div class="value">{redirect_uri_escaped}</div>
+        </div>
+    """
+
+    # Build advanced details with collapsible section
+    detail_rows = [
+        ("Application Name", html_module.escape(client_name or client_id)),
+        ("Application Website", html_module.escape(client_website_url or "N/A")),
+        ("Application ID", html_module.escape(client_id)),
+        ("Redirect URI", redirect_uri_escaped),
+        (
+            "Requested Scopes",
+            ", ".join(html_module.escape(s) for s in scopes) if scopes else "None",
+        ),
+    ]
+
+    detail_rows_html = "\n".join(
+        [
+            f"""
+        <div class="detail-row">
+            <div class="detail-label">{label}:</div>
+            <div class="detail-value">{value}</div>
+        </div>
+        """
+            for label, value in detail_rows
+        ]
+    )
+
+    advanced_details = f"""
+        <details>
+            <summary>Advanced Details</summary>
+            <div class="detail-box">
+                {detail_rows_html}
+            </div>
+        </details>
+    """
+
+    # Build form with buttons
+    # Use empty action to submit to current URL (/consent or /mcp/consent)
+    # The POST handler is registered at the same path as GET
+    form = f"""
+        <form id="consentForm" method="POST" action="">
+            <input type="hidden" name="txn_id" value="{txn_id}" />
+            <input type="hidden" name="csrf_token" value="{csrf_token}" />
+            <input type="hidden" name="submit" value="true" />
+            <div class="button-group">
+                <button type="submit" name="action" value="approve" class="btn-approve">Allow Access</button>
+                <button type="submit" name="action" value="deny" class="btn-deny">Deny</button>
+            </div>
+        </form>
+    """
+
+    # Build help link with tooltip (identical to current implementation)
+    help_link = """
+        <div class="help-link-container">
+            <span class="help-link">
+                Why am I seeing this?
+                <span class="tooltip">
+                    This FastMCP server requires your consent to allow a new client
+                    to connect. This protects you from <a
+                    href="https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#confused-deputy-problem"
+                    target="_blank" class="tooltip-link">confused deputy
+                    attacks</a>, where malicious clients could impersonate you
+                    and steal access.<br><br>
+                    <a
+                    href="https://gofastmcp.com/servers/auth/oauth-proxy#confused-deputy-attacks"
+                    target="_blank" class="tooltip-link">Learn more about
+                    FastMCP security →</a>
+                </span>
+            </span>
+        </div>
+    """
+
+    # Build the page content
+    content = f"""
+        <div class="container">
+            {create_logo(icon_url=server_icon_url, alt_text=server_name or "FastMCP")}
+            <h1>Application Access Request</h1>
+            {intro_box}
+            {cimd_badge}
+            {redirect_section}
+            {advanced_details}
+            {form}
+        </div>
+        {help_link}
+    """
+
+    # Additional styles needed for this page
+    cimd_badge_styles = """
+        .cimd-badge {
+            background: #ecfdf5;
+            border: 1px solid #6ee7b7;
+            border-radius: 8px;
+            padding: 8px 16px;
+            margin-bottom: 16px;
+            font-size: 14px;
+            color: #065f46;
+            text-align: center;
+        }
+        .cimd-check {
+            color: #059669;
+            font-weight: bold;
+            margin-right: 4px;
+        }
+    """
+    additional_styles = (
+        INFO_BOX_STYLES
+        + REDIRECT_SECTION_STYLES
+        + DETAILS_STYLES
+        + DETAIL_BOX_STYLES
+        + BUTTON_STYLES
+        + TOOLTIP_STYLES
+        + cimd_badge_styles
+    )
+
+    # Determine CSP policy to use
+    # If csp_policy is None, build the default CSP policy
+    # If csp_policy is empty string, CSP will be disabled entirely in create_page
+    # If csp_policy is a non-empty string, use it as-is
+    if csp_policy is None:
+        # The consent form posts to itself (action="") and all subsequent redirects
+        # are server-controlled. Chrome enforces form-action across the entire redirect
+        # chain (Chromium issue #40923007), which breaks flows where an HTTPS callback
+        # internally redirects to a custom scheme (e.g., claude:// or cursor://).
+        # Since the form target is same-origin and we control the redirect chain,
+        # omitting form-action is safe and avoids these browser-specific CSP issues.
+        csp_policy = "default-src 'none'; style-src 'unsafe-inline'; img-src https: data:; base-uri 'none'"
+
+    return create_page(
+        content=content,
+        title=title,
+        additional_styles=additional_styles,
+        csp_policy=csp_policy,
+    )
+
+
+def create_error_html(
+    error_title: str,
+    error_message: str,
+    error_details: dict[str, str] | None = None,
+    server_name: str | None = None,
+    server_icon_url: str | None = None,
+) -> str:
+    """Create a styled HTML error page for OAuth errors.
+
+    Args:
+        error_title: The error title (e.g., "OAuth Error", "Authorization Failed")
+        error_message: The main error message to display
+        error_details: Optional dictionary of error details to show (e.g., `{"Error Code": "invalid_client"}`)
+        server_name: Optional server name to display
+        server_icon_url: Optional URL to server icon/logo
+
+    Returns:
+        Complete HTML page as a string
+    """
+    import html as html_module
+
+    error_message_escaped = html_module.escape(error_message)
+
+    # Build error message box
+    error_box = f"""
+        <div class="info-box error">
+            <p>{error_message_escaped}</p>
+        </div>
+    """
+
+    # Build error details section if provided
+    details_section = ""
+    if error_details:
+        detail_rows_html = "\n".join(
+            [
+                f"""
+            <div class="detail-row">
+                <div class="detail-label">{html_module.escape(label)}:</div>
+                <div class="detail-value">{html_module.escape(value)}</div>
+            </div>
+            """
+                for label, value in error_details.items()
+            ]
+        )
+
+        details_section = f"""
+            <details>
+                <summary>Error Details</summary>
+                <div class="detail-box">
+                    {detail_rows_html}
+                </div>
+            </details>
+        """
+
+    # Build the page content
+    content = f"""
+        <div class="container">
+            {create_logo(icon_url=server_icon_url, alt_text=server_name or "FastMCP")}
+            <h1>{html_module.escape(error_title)}</h1>
+            {error_box}
+            {details_section}
+        </div>
+    """
+
+    # Additional styles needed for this page
+    # Override .info-box.error to use normal text color instead of red
+    additional_styles = (
+        INFO_BOX_STYLES
+        + DETAILS_STYLES
+        + DETAIL_BOX_STYLES
+        + """
+        .info-box.error {
+            color: #111827;
+        }
+        """
+    )
+
+    # Simple CSP policy for error pages (no forms needed)
+    csp_policy = "default-src 'none'; style-src 'unsafe-inline'; img-src https: data:; base-uri 'none'"
+
+    return create_page(
+        content=content,
+        title=error_title,
+        additional_styles=additional_styles,
+        csp_policy=csp_policy,
+    )
diff --git a/fastmcp_slim/fastmcp/server/auth/oidc_proxy.py b/fastmcp_slim/fastmcp/server/auth/oidc_proxy.py
new file mode 100644
index 0000000..ac7bfae
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/oidc_proxy.py
@@ -0,0 +1,525 @@
+"""OIDC Proxy Provider for FastMCP.
+
+This provider acts as a transparent proxy to an upstream OIDC compliant Authorization
+Server. It leverages the OAuthProxy class to handle Dynamic Client Registration and
+forwarding of all OAuth flows.
+
+This implementation is based on:
+    OpenID Connect Discovery 1.0 - https://openid.net/specs/openid-connect-discovery-1_0.html
+    OAuth 2.0 Authorization Server Metadata - https://datatracker.ietf.org/doc/html/rfc8414
+"""
+
+from collections.abc import Sequence
+from typing import Any, Literal
+
+import httpx
+from key_value.aio.protocols import AsyncKeyValue
+from pydantic import AnyHttpUrl, BaseModel, model_validator
+from typing_extensions import Self
+
+from fastmcp.server.auth import TokenVerifier
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.server.auth.oauth_proxy.models import UpstreamTokenSet
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+#: Default timeout, in seconds, for the OIDC discovery request made during
+#: provider construction. Bounds how long startup can block on a slow or
+#: unreachable issuer metadata endpoint. Pass ``timeout_seconds=None`` to fall
+#: back to the HTTP client's own default timeout instead.
+DEFAULT_OIDC_DISCOVERY_TIMEOUT_SECONDS = 10
+
+
+class OIDCConfiguration(BaseModel):
+    """OIDC Configuration.
+
+    See:
+        https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
+        https://datatracker.ietf.org/doc/html/rfc8414#section-2
+    """
+
+    strict: bool = True
+
+    # OpenID Connect Discovery 1.0
+    issuer: AnyHttpUrl | str | None = None  # Strict
+
+    authorization_endpoint: AnyHttpUrl | str | None = None  # Strict
+    token_endpoint: AnyHttpUrl | str | None = None  # Strict
+    userinfo_endpoint: AnyHttpUrl | str | None = None
+
+    jwks_uri: AnyHttpUrl | str | None = None  # Strict
+
+    registration_endpoint: AnyHttpUrl | str | None = None
+
+    scopes_supported: Sequence[str] | None = None
+
+    response_types_supported: Sequence[str] | None = None  # Strict
+    response_modes_supported: Sequence[str] | None = None
+
+    grant_types_supported: Sequence[str] | None = None
+
+    acr_values_supported: Sequence[str] | None = None
+
+    subject_types_supported: Sequence[str] | None = None  # Strict
+
+    id_token_signing_alg_values_supported: Sequence[str] | None = None  # Strict
+    id_token_encryption_alg_values_supported: Sequence[str] | None = None
+    id_token_encryption_enc_values_supported: Sequence[str] | None = None
+
+    userinfo_signing_alg_values_supported: Sequence[str] | None = None
+    userinfo_encryption_alg_values_supported: Sequence[str] | None = None
+    userinfo_encryption_enc_values_supported: Sequence[str] | None = None
+
+    request_object_signing_alg_values_supported: Sequence[str] | None = None
+    request_object_encryption_alg_values_supported: Sequence[str] | None = None
+    request_object_encryption_enc_values_supported: Sequence[str] | None = None
+
+    token_endpoint_auth_methods_supported: Sequence[str] | None = None
+    token_endpoint_auth_signing_alg_values_supported: Sequence[str] | None = None
+
+    display_values_supported: Sequence[str] | None = None
+
+    claim_types_supported: Sequence[str] | None = None
+    claims_supported: Sequence[str] | None = None
+
+    service_documentation: AnyHttpUrl | str | None = None
+
+    claims_locales_supported: Sequence[str] | None = None
+    ui_locales_supported: Sequence[str] | None = None
+
+    claims_parameter_supported: bool | None = None
+    request_parameter_supported: bool | None = None
+    request_uri_parameter_supported: bool | None = None
+
+    require_request_uri_registration: bool | None = None
+
+    op_policy_uri: AnyHttpUrl | str | None = None
+    op_tos_uri: AnyHttpUrl | str | None = None
+
+    # OAuth 2.0 Authorization Server Metadata
+    revocation_endpoint: AnyHttpUrl | str | None = None
+    revocation_endpoint_auth_methods_supported: Sequence[str] | None = None
+    revocation_endpoint_auth_signing_alg_values_supported: Sequence[str] | None = None
+
+    introspection_endpoint: AnyHttpUrl | str | None = None
+    introspection_endpoint_auth_methods_supported: Sequence[str] | None = None
+    introspection_endpoint_auth_signing_alg_values_supported: Sequence[str] | None = (
+        None
+    )
+
+    code_challenge_methods_supported: Sequence[str] | None = None
+
+    signed_metadata: str | None = None
+
+    @model_validator(mode="after")
+    def _enforce_strict(self) -> Self:
+        """Enforce strict rules."""
+        if not self.strict:
+            return self
+
+        def enforce(attr: str, is_url: bool = False) -> None:
+            value = getattr(self, attr, None)
+            if not value:
+                message = f"Missing required configuration metadata: {attr}"
+                logger.error(message)
+                raise ValueError(message)
+
+            if not is_url or isinstance(value, AnyHttpUrl):
+                return
+
+            try:
+                AnyHttpUrl(value)
+            except Exception as e:
+                message = f"Invalid URL for configuration metadata: {attr}"
+                logger.error(message)
+                raise ValueError(message) from e
+
+        enforce("issuer", True)
+        enforce("authorization_endpoint", True)
+        enforce("token_endpoint", True)
+        enforce("jwks_uri", True)
+        enforce("response_types_supported")
+        enforce("subject_types_supported")
+        enforce("id_token_signing_alg_values_supported")
+
+        return self
+
+    @classmethod
+    def get_oidc_configuration(
+        cls, config_url: AnyHttpUrl, *, strict: bool | None, timeout_seconds: int | None
+    ) -> Self:
+        """Get the OIDC configuration for the specified config URL.
+
+        Args:
+            config_url: The OIDC config URL
+            strict: The strict flag for the configuration
+            timeout_seconds: HTTP request timeout in seconds
+        """
+        get_kwargs: dict[str, Any] = {}
+        if timeout_seconds is not None:
+            get_kwargs["timeout"] = timeout_seconds
+
+        try:
+            response = httpx.get(str(config_url), **get_kwargs)
+            response.raise_for_status()
+
+            config_data = response.json()
+            if strict is not None:
+                config_data["strict"] = strict
+
+            return cls.model_validate(config_data)
+        except Exception:
+            logger.exception(
+                f"Unable to get OIDC configuration for config url: {config_url}"
+            )
+            raise
+
+
+class OIDCProxy(OAuthProxy):
+    """OAuth provider that wraps OAuthProxy to provide configuration via an OIDC configuration URL.
+
+    This provider makes it easier to add OAuth protection for any upstream provider
+    that is OIDC compliant.
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth.oidc_proxy import OIDCProxy
+
+        # Simple OIDC based protection
+        auth = OIDCProxy(
+            config_url="https://oidc.config.url",
+            client_id="your-oidc-client-id",
+            client_secret="your-oidc-client-secret",
+            base_url="https://your.server.url",
+        )
+
+        mcp = FastMCP("My Protected Server", auth=auth)
+        ```
+    """
+
+    oidc_config: OIDCConfiguration
+
+    def __init__(
+        self,
+        *,
+        # OIDC configuration
+        config_url: AnyHttpUrl | str,
+        strict: bool | None = None,
+        # Upstream server configuration
+        client_id: str,
+        client_secret: str | None = None,
+        audience: str | None = None,
+        timeout_seconds: int | None = DEFAULT_OIDC_DISCOVERY_TIMEOUT_SECONDS,
+        # Token verifier
+        token_verifier: TokenVerifier | None = None,
+        algorithm: str | None = None,
+        required_scopes: list[str] | None = None,
+        verify_id_token: bool = False,
+        # FastMCP server configuration
+        base_url: AnyHttpUrl | str,
+        resource_base_url: AnyHttpUrl | str | None = None,
+        issuer_url: AnyHttpUrl | str | None = None,
+        redirect_path: str | None = None,
+        # Client configuration
+        allowed_client_redirect_uris: list[str] | None = None,
+        client_storage: AsyncKeyValue | None = None,
+        # JWT and encryption keys
+        jwt_signing_key: str | bytes | None = None,
+        # Token validation configuration
+        token_endpoint_auth_method: str | None = None,
+        # Consent screen configuration
+        require_authorization_consent: bool | Literal["remember", "external"] = True,
+        consent_csp_policy: str | None = None,
+        forward_resource: bool = True,
+        # Extra parameters
+        extra_authorize_params: dict[str, str] | None = None,
+        extra_token_params: dict[str, str] | None = None,
+        # Token expiry fallback
+        fallback_access_token_expiry_seconds: int | None = None,
+        fallback_refresh_token_expiry_seconds: int | None = None,
+        # FastMCP-issued access token lifetime (decoupled from upstream)
+        fastmcp_access_token_expiry_seconds: int | None = None,
+        # Token refresh threshold
+        token_expiry_threshold_seconds: int = 0,
+        # CIMD configuration
+        enable_cimd: bool = True,
+    ) -> None:
+        """Initialize the OIDC proxy provider.
+
+        Args:
+            config_url: URL of upstream configuration
+            strict: Optional strict flag for the configuration
+            client_id: Client ID registered with upstream server
+            client_secret: Client secret for upstream server. Optional for PKCE public
+                clients or when using alternative credentials. When omitted,
+                jwt_signing_key must be provided.
+            audience: Audience for upstream server
+            timeout_seconds: Timeout, in seconds, for the OIDC discovery request
+                made during construction. Defaults to 10 seconds so a slow or
+                unreachable issuer cannot block server startup indefinitely. Pass
+                None to fall back to the HTTP client's own default timeout.
+            token_verifier: Optional custom token verifier (e.g., IntrospectionTokenVerifier for opaque tokens).
+                If not provided, a JWTVerifier will be created using the OIDC configuration.
+                Cannot be used with algorithm or required_scopes parameters (configure these on your verifier instead).
+            algorithm: Token verifier algorithm (only used if token_verifier is not provided)
+            required_scopes: Required scopes for token validation (only used if token_verifier is not provided)
+            verify_id_token: If True, verify the OIDC id_token instead of the access_token.
+                Useful for providers that issue opaque (non-JWT) access tokens, since the
+                id_token is always a standard JWT verifiable via the provider's JWKS.
+            base_url: Public URL where OAuth endpoints will be accessible (includes any mount path)
+            resource_base_url: Optional public base URL for the protected resource metadata
+                and token audience. Defaults to ``base_url``.
+            issuer_url: Issuer URL for OAuth metadata (defaults to base_url). Use root-level URL
+                to avoid 404s during discovery when mounting under a path.
+            redirect_path: Redirect path configured in upstream OAuth app (defaults to "/auth/callback")
+            allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
+                Patterns support wildcards (e.g., "http://localhost:*", "https://*.example.com/*").
+                If None (default), DCR clients use registered redirect URIs, with loopback
+                ports allowed to vary for MCP compatibility. Unsafe browser schemes are rejected.
+                If empty list, no redirect URIs are allowed.
+                These are for MCP clients performing loopback redirects, NOT for the upstream OAuth app.
+            client_storage: Storage backend for OAuth state (client registrations, encrypted tokens).
+                If None, an encrypted file store will be created in the data directory
+                (derived from `platformdirs`).
+            jwt_signing_key: Secret for signing FastMCP JWT tokens (any string or bytes). If bytes are provided,
+                they will be used as is. If a string is provided, it will be derived into a 32-byte key. If not
+                provided, the upstream client secret will be used to derive a 32-byte key using PBKDF2.
+            token_endpoint_auth_method: Token endpoint authentication method for upstream server.
+                Common values: "client_secret_basic", "client_secret_post", "none".
+                If None, authlib will use its default (typically "client_secret_basic").
+            require_authorization_consent: Whether to require user consent before authorizing clients (default True).
+                When True, users see a consent screen before being redirected to the upstream IdP.
+                When False, authorization proceeds directly without user confirmation.
+                When "external", the built-in consent screen is skipped but no warning is
+                logged, indicating that consent is handled externally (e.g. by the upstream IdP).
+                SECURITY WARNING: Only set to False for local development or testing environments.
+            consent_csp_policy: Content Security Policy for the consent page.
+                If None (default), uses the built-in CSP policy with appropriate directives.
+                If empty string "", disables CSP entirely (no meta tag is rendered).
+                If a non-empty string, uses that as the CSP policy value.
+            extra_authorize_params: Additional parameters to forward to the upstream authorization endpoint.
+                Useful for provider-specific parameters like prompt=consent or access_type=offline.
+                Example: {"prompt": "consent", "access_type": "offline"}
+            extra_token_params: Additional parameters to forward to the upstream token endpoint.
+                Useful for provider-specific parameters during token exchange.
+            fallback_access_token_expiry_seconds: Expiry time to use when upstream provider
+                doesn't return `expires_in` in the token response. If not set, uses smart
+                defaults: 1 hour if a refresh token is available (since we can refresh),
+                or 1 year if no refresh token (for API-key-style tokens like GitHub OAuth Apps).
+            fallback_refresh_token_expiry_seconds: Expiry time to use when upstream provider
+                doesn't return `refresh_expires_in` (e.g. Cognito, GitHub, many OIDC IdPs).
+                Defaults to 1 year. The actual upstream refresh remains the source of
+                truth — if upstream rejects the refresh, the client gets `invalid_grant`
+                and re-auths.
+            fastmcp_access_token_expiry_seconds: Lifetime for the FastMCP-issued access
+                token (JWT), decoupling it from the upstream provider's `expires_in`. By
+                default (None) the FastMCP access token mirrors the upstream access token
+                lifetime. The FastMCP JWT is a reference token re-validated against upstream
+                on every request, so a longer FastMCP lifetime does not extend upstream
+                access — a revoked or expired upstream session still fails validation. Set
+                this for bridges whose upstream issues short-lived access tokens that some
+                MCP clients can't refresh gracefully (e.g. `mcp-remote`).
+            token_expiry_threshold_seconds: Number of seconds before actual expiry to consider
+                a token as expired (default 0). Prevents race conditions where a token
+                passes the expiry check but expires before the next operation completes.
+            enable_cimd: Whether to enable CIMD (Client ID Metadata Document) client support.
+                When True, clients can use their metadata document URL as client_id instead of
+                Dynamic Client Registration. Default is True.
+        """
+        if not config_url:
+            raise ValueError("Missing required config URL")
+
+        if not client_id:
+            raise ValueError("Missing required client id")
+
+        if not client_secret and not jwt_signing_key:
+            raise ValueError(
+                "Either client_secret or jwt_signing_key must be provided. "
+                "jwt_signing_key is required when client_secret is omitted "
+                "(e.g., for PKCE public clients)."
+            )
+
+        if not base_url:
+            raise ValueError("Missing required base URL")
+
+        # Validate that verifier-specific parameters are not used with custom verifier
+        if token_verifier is not None:
+            if algorithm is not None:
+                raise ValueError(
+                    "Cannot specify 'algorithm' when providing a custom token_verifier. "
+                    "Configure the algorithm on your token verifier instead."
+                )
+            if required_scopes is not None:
+                raise ValueError(
+                    "Cannot specify 'required_scopes' when providing a custom token_verifier. "
+                    "Configure required scopes on your token verifier instead."
+                )
+
+        if isinstance(config_url, str):
+            config_url = AnyHttpUrl(config_url)
+
+        self.oidc_config = self.get_oidc_configuration(
+            config_url, strict, timeout_seconds
+        )
+        if (
+            not self.oidc_config.authorization_endpoint
+            or not self.oidc_config.token_endpoint
+        ):
+            logger.debug(f"Invalid OIDC Configuration: {self.oidc_config}")
+            raise ValueError("Missing required OIDC endpoints")
+
+        revocation_endpoint = (
+            str(self.oidc_config.revocation_endpoint)
+            if self.oidc_config.revocation_endpoint
+            else None
+        )
+
+        # Use custom verifier if provided, otherwise create default JWTVerifier
+        if token_verifier is None:
+            # When verifying id_tokens:
+            # - aud is always the OAuth client_id (per OIDC Core §2), not
+            #   the API audience, so use client_id for audience validation.
+            # - id_tokens don't carry scope/scp claims, so don't pass
+            #   required_scopes to the verifier (scope enforcement happens
+            #   at the FastMCP token level instead).
+            verifier_audience = client_id if verify_id_token else audience
+            verifier_scopes = None if verify_id_token else required_scopes
+            token_verifier = self.get_token_verifier(
+                algorithm=algorithm,
+                audience=verifier_audience,
+                required_scopes=verifier_scopes,
+                timeout_seconds=timeout_seconds,
+            )
+
+        init_kwargs: dict[str, object] = {
+            "upstream_authorization_endpoint": str(
+                self.oidc_config.authorization_endpoint
+            ),
+            "upstream_token_endpoint": str(self.oidc_config.token_endpoint),
+            "upstream_client_id": client_id,
+            "upstream_client_secret": client_secret,
+            "upstream_revocation_endpoint": revocation_endpoint,
+            "token_verifier": token_verifier,
+            "base_url": base_url,
+            "resource_base_url": resource_base_url,
+            "issuer_url": issuer_url or base_url,
+            "service_documentation_url": self.oidc_config.service_documentation,
+            "allowed_client_redirect_uris": allowed_client_redirect_uris,
+            "client_storage": client_storage,
+            "jwt_signing_key": jwt_signing_key,
+            "token_endpoint_auth_method": token_endpoint_auth_method,
+            "require_authorization_consent": require_authorization_consent,
+            "consent_csp_policy": consent_csp_policy,
+            "forward_resource": forward_resource,
+            "fallback_access_token_expiry_seconds": fallback_access_token_expiry_seconds,
+            "fallback_refresh_token_expiry_seconds": fallback_refresh_token_expiry_seconds,
+            "fastmcp_access_token_expiry_seconds": fastmcp_access_token_expiry_seconds,
+            "token_expiry_threshold_seconds": token_expiry_threshold_seconds,
+            "enable_cimd": enable_cimd,
+        }
+
+        if redirect_path:
+            init_kwargs["redirect_path"] = redirect_path
+
+        # Build extra params, merging audience with user-provided params
+        # User params override audience if there's a conflict
+        final_authorize_params: dict[str, str] = {}
+        final_token_params: dict[str, str] = {}
+
+        if audience:
+            final_authorize_params["audience"] = audience
+            final_token_params["audience"] = audience
+
+        if extra_authorize_params:
+            final_authorize_params.update(extra_authorize_params)
+        if extra_token_params:
+            final_token_params.update(extra_token_params)
+
+        if final_authorize_params:
+            init_kwargs["extra_authorize_params"] = final_authorize_params
+        if final_token_params:
+            init_kwargs["extra_token_params"] = final_token_params
+
+        super().__init__(**init_kwargs)  # ty: ignore[invalid-argument-type]
+
+        self._verify_id_token = verify_id_token
+
+        # When verify_id_token strips scopes from the verifier, restore
+        # them on the provider so they're still advertised to clients
+        # and enforced at the FastMCP token level.  We also need to
+        # recompute derived state that OAuthProxy.__init__ already built
+        # from the (empty) verifier scopes.
+        if verify_id_token and required_scopes:
+            self.required_scopes = required_scopes
+            self.update_default_scopes(required_scopes)
+
+    def _get_verification_token(
+        self, upstream_token_set: UpstreamTokenSet
+    ) -> str | None:
+        """Get the token to verify from the upstream token set.
+
+        When verify_id_token is enabled, returns the id_token from the
+        upstream token response instead of the access_token.
+        """
+        if self._verify_id_token:
+            id_token = upstream_token_set.raw_token_data.get("id_token")
+            if id_token is None:
+                logger.warning(
+                    "verify_id_token is enabled but no id_token found in"
+                    " upstream token response"
+                )
+            return id_token
+        return upstream_token_set.access_token
+
+    def _uses_alternate_verification(self) -> bool:
+        """Return True when id_token verification is enabled.
+
+        This ensures ``load_access_token`` always patches the validated
+        result with upstream scopes, even when the IdP issues the same
+        JWT for both ``access_token`` and ``id_token``.
+        """
+        return self._verify_id_token
+
+    def get_oidc_configuration(
+        self,
+        config_url: AnyHttpUrl,
+        strict: bool | None,
+        timeout_seconds: int | None,
+    ) -> OIDCConfiguration:
+        """Gets the OIDC configuration for the specified configuration URL.
+
+        Args:
+            config_url: The OIDC configuration URL
+            strict: The strict flag for the configuration
+            timeout_seconds: HTTP request timeout in seconds
+        """
+        return OIDCConfiguration.get_oidc_configuration(
+            config_url, strict=strict, timeout_seconds=timeout_seconds
+        )
+
+    def get_token_verifier(
+        self,
+        *,
+        algorithm: str | None = None,
+        audience: str | None = None,
+        required_scopes: list[str] | None = None,
+        timeout_seconds: int | None = None,
+    ) -> TokenVerifier:
+        """Creates the token verifier for the specified OIDC configuration and arguments.
+
+        Args:
+            algorithm: Optional token verifier algorithm
+            audience: Optional token verifier audience
+            required_scopes: Optional token verifier required_scopes
+            timeout_seconds: HTTP request timeout in seconds
+        """
+        return JWTVerifier(
+            jwks_uri=str(self.oidc_config.jwks_uri),
+            issuer=str(self.oidc_config.issuer),
+            algorithm=algorithm,
+            audience=audience,
+            required_scopes=required_scopes,
+        )
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/__init__.py b/fastmcp_slim/fastmcp/server/auth/providers/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/auth0.py b/fastmcp_slim/fastmcp/server/auth/providers/auth0.py
new file mode 100644
index 0000000..16ad684
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/auth0.py
@@ -0,0 +1,161 @@
+"""Auth0 OAuth provider for FastMCP.
+
+This module provides a complete Auth0 integration that's ready to use with
+just the configuration URL, client ID, client secret, audience, and base URL.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth.providers.auth0 import Auth0Provider
+
+    # Simple Auth0 OAuth protection
+    auth = Auth0Provider(
+        config_url="https://auth0.config.url",
+        client_id="your-auth0-client-id",
+        client_secret="your-auth0-client-secret",
+        audience="your-auth0-api-audience",
+        base_url="http://localhost:8000",
+    )
+
+    mcp = FastMCP("My Protected Server", auth=auth)
+    ```
+"""
+
+from typing import Literal
+
+from key_value.aio.protocols import AsyncKeyValue
+from pydantic import AnyHttpUrl
+
+from fastmcp.server.auth.oidc_proxy import (
+    DEFAULT_OIDC_DISCOVERY_TIMEOUT_SECONDS,
+    OIDCProxy,
+)
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class Auth0Provider(OIDCProxy):
+    """An Auth0 provider implementation for FastMCP.
+
+    This provider is a complete Auth0 integration that's ready to use with
+    just the configuration URL, client ID, client secret, audience, and base URL.
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth.providers.auth0 import Auth0Provider
+
+        # Simple Auth0 OAuth protection
+        auth = Auth0Provider(
+            config_url="https://auth0.config.url",
+            client_id="your-auth0-client-id",
+            client_secret="your-auth0-client-secret",
+            audience="your-auth0-api-audience",
+            base_url="http://localhost:8000",
+        )
+
+        mcp = FastMCP("My Protected Server", auth=auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        config_url: AnyHttpUrl | str,
+        client_id: str,
+        client_secret: str,
+        audience: str,
+        timeout_seconds: int | None = DEFAULT_OIDC_DISCOVERY_TIMEOUT_SECONDS,
+        base_url: AnyHttpUrl | str,
+        resource_base_url: AnyHttpUrl | str | None = None,
+        issuer_url: AnyHttpUrl | str | None = None,
+        required_scopes: list[str] | None = None,
+        redirect_path: str | None = None,
+        allowed_client_redirect_uris: list[str] | None = None,
+        client_storage: AsyncKeyValue | None = None,
+        jwt_signing_key: str | bytes | None = None,
+        require_authorization_consent: bool | Literal["remember", "external"] = True,
+        consent_csp_policy: str | None = None,
+        forward_resource: bool = True,
+        fallback_refresh_token_expiry_seconds: int | None = None,
+        fastmcp_access_token_expiry_seconds: int | None = None,
+        token_expiry_threshold_seconds: int = 0,
+    ) -> None:
+        """Initialize Auth0 OAuth provider.
+
+        Args:
+            config_url: Auth0 config URL
+            client_id: Auth0 application client id
+            client_secret: Auth0 application client secret
+            audience: Auth0 API audience
+            timeout_seconds: Timeout, in seconds, for the OIDC discovery request
+                made during construction. Defaults to 10 seconds so a slow or
+                unreachable issuer cannot block server startup indefinitely. Pass
+                None to fall back to the HTTP client's own default timeout.
+            base_url: Public URL where OAuth endpoints will be accessible (includes any mount path)
+            resource_base_url: Optional public base URL for the protected resource metadata
+                and token audience. Defaults to ``base_url``.
+            issuer_url: Issuer URL for OAuth metadata (defaults to base_url). Use root-level URL
+                to avoid 404s during discovery when mounting under a path.
+            required_scopes: Required Auth0 scopes (defaults to ["openid"])
+            redirect_path: Redirect path configured in Auth0 application
+            allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
+                If None (default), all URIs are allowed. If empty list, no URIs are allowed.
+            client_storage: Storage backend for OAuth state (client registrations, encrypted tokens).
+                If None, an encrypted file store will be created in the data directory
+                (derived from `platformdirs`).
+            jwt_signing_key: Secret for signing FastMCP JWT tokens (any string or bytes). If bytes are provided,
+                they will be used as is. If a string is provided, it will be derived into a 32-byte key. If not
+                provided, the upstream client secret will be used to derive a 32-byte key using PBKDF2.
+            require_authorization_consent: Whether to require user consent before authorizing clients (default True).
+                When True, users see a consent screen before being redirected to Auth0.
+                When False, authorization proceeds directly without user confirmation.
+                When "external", the built-in consent screen is skipped but no warning is
+                logged, indicating that consent is handled externally (e.g. by the upstream IdP).
+                SECURITY WARNING: Only set to False for local development or testing environments.
+            fallback_refresh_token_expiry_seconds: Lifetime for the FastMCP-issued
+                refresh token when the upstream provider omits `refresh_expires_in`
+                (e.g. Cognito, GitHub, many OIDC IdPs). Defaults to 1 year. The upstream
+                refresh remains the source of truth. See `OAuthProxy` for details.
+            fastmcp_access_token_expiry_seconds: Lifetime for the FastMCP-issued access
+                token, decoupling it from the upstream provider's `expires_in`. Defaults
+                to None (mirror the upstream lifetime). Set this for bridges whose
+                upstream issues short-lived access tokens that some MCP clients can't
+                refresh gracefully (e.g. `mcp-remote`). See `OAuthProxy` for details.
+            token_expiry_threshold_seconds: Number of seconds before actual expiry to
+                treat a token as expired, refreshing early to avoid races. Defaults to 0.
+        """
+        # Parse scopes if provided as string
+        auth0_required_scopes = (
+            parse_scopes(required_scopes) if required_scopes is not None else ["openid"]
+        )
+
+        super().__init__(
+            config_url=config_url,
+            client_id=client_id,
+            client_secret=client_secret,
+            audience=audience,
+            timeout_seconds=timeout_seconds,
+            base_url=base_url,
+            resource_base_url=resource_base_url,
+            issuer_url=issuer_url,
+            redirect_path=redirect_path,
+            required_scopes=auth0_required_scopes,
+            allowed_client_redirect_uris=allowed_client_redirect_uris,
+            client_storage=client_storage,
+            jwt_signing_key=jwt_signing_key,
+            require_authorization_consent=require_authorization_consent,
+            consent_csp_policy=consent_csp_policy,
+            forward_resource=forward_resource,
+            fallback_refresh_token_expiry_seconds=fallback_refresh_token_expiry_seconds,
+            fastmcp_access_token_expiry_seconds=fastmcp_access_token_expiry_seconds,
+            token_expiry_threshold_seconds=token_expiry_threshold_seconds,
+        )
+
+        logger.debug(
+            "Initialized Auth0 OAuth provider for client %s with scopes: %s",
+            client_id,
+            auth0_required_scopes,
+        )
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/aws.py b/fastmcp_slim/fastmcp/server/auth/providers/aws.py
new file mode 100644
index 0000000..ff6add3
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/aws.py
@@ -0,0 +1,255 @@
+"""AWS Cognito OAuth provider for FastMCP.
+
+This module provides a complete AWS Cognito OAuth integration that's ready to use
+with a user pool ID, domain prefix, client ID and client secret. It handles all
+the complexity of AWS Cognito's OAuth flow, token validation, and user management.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth.providers.aws_cognito import AWSCognitoProvider
+
+    # Simple AWS Cognito OAuth protection
+    auth = AWSCognitoProvider(
+        user_pool_id="your-user-pool-id",
+        aws_region="eu-central-1",
+        client_id="your-cognito-client-id",
+        client_secret="your-cognito-client-secret"
+    )
+
+    mcp = FastMCP("My Protected Server", auth=auth)
+    ```
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from key_value.aio.protocols import AsyncKeyValue
+from pydantic import AnyHttpUrl
+
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.server.auth.oidc_proxy import (
+    DEFAULT_OIDC_DISCOVERY_TIMEOUT_SECONDS,
+    OIDCProxy,
+)
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class AWSCognitoTokenVerifier(JWTVerifier):
+    """Token verifier for Cognito access tokens.
+
+    Cognito access tokens use a ``client_id`` claim instead of the
+    standard ``aud`` claim.  This subclass passes ``audience=None``
+    to the parent (skipping the ``aud`` check) and validates the
+    ``client_id`` claim directly.
+    """
+
+    def __init__(self, *, audience: str | list[str] | None = None, **kwargs):
+        self._expected_client_id = audience
+        super().__init__(audience=None, **kwargs)
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify token and filter claims to Cognito-specific subset."""
+        access_token = await super().verify_token(token)
+        if not access_token:
+            return None
+
+        # Validate client_id claim (Cognito's equivalent of aud)
+        if self._expected_client_id:
+            token_client_id = access_token.claims.get("client_id")
+            if isinstance(self._expected_client_id, list):
+                valid = token_client_id in self._expected_client_id
+            else:
+                valid = token_client_id == self._expected_client_id
+            if not valid:
+                self.logger.debug(
+                    "Token validation failed: client_id mismatch (expected %s, got %s)",
+                    self._expected_client_id,
+                    token_client_id,
+                )
+                return None
+
+        # Filter claims to Cognito-specific subset
+        cognito_claims = {
+            "sub": access_token.claims.get("sub"),
+            "username": access_token.claims.get("username"),
+            "cognito:groups": access_token.claims.get("cognito:groups", []),
+        }
+
+        return AccessToken(
+            token=access_token.token,
+            client_id=access_token.client_id,
+            scopes=access_token.scopes,
+            expires_at=access_token.expires_at,
+            claims=cognito_claims,
+        )
+
+
+class AWSCognitoProvider(OIDCProxy):
+    """Complete AWS Cognito OAuth provider for FastMCP.
+
+    This provider makes it trivial to add AWS Cognito OAuth protection to any
+    FastMCP server using OIDC Discovery. Just provide your Cognito User Pool details,
+    client credentials, and a base URL, and you're ready to go.
+
+    Features:
+    - Automatic OIDC Discovery from AWS Cognito User Pool
+    - Automatic JWT token validation via Cognito's public keys
+    - Cognito-specific claim filtering (sub, username, cognito:groups)
+    - Support for Cognito User Pools
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth.providers.aws_cognito import AWSCognitoProvider
+
+        auth = AWSCognitoProvider(
+            user_pool_id="eu-central-1_XXXXXXXXX",
+            aws_region="eu-central-1",
+            client_id="your-cognito-client-id",
+            client_secret="your-cognito-client-secret",
+            base_url="https://my-server.com",
+            redirect_path="/custom/callback",
+        )
+
+        mcp = FastMCP("My App", auth=auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        user_pool_id: str,
+        client_id: str,
+        client_secret: str,
+        timeout_seconds: int | None = DEFAULT_OIDC_DISCOVERY_TIMEOUT_SECONDS,
+        base_url: AnyHttpUrl | str,
+        resource_base_url: AnyHttpUrl | str | None = None,
+        aws_region: str = "eu-central-1",
+        issuer_url: AnyHttpUrl | str | None = None,
+        redirect_path: str = "/auth/callback",
+        required_scopes: list[str] | None = None,
+        allowed_client_redirect_uris: list[str] | None = None,
+        client_storage: AsyncKeyValue | None = None,
+        jwt_signing_key: str | bytes | None = None,
+        require_authorization_consent: bool | Literal["remember", "external"] = True,
+        consent_csp_policy: str | None = None,
+        forward_resource: bool = True,
+        fallback_refresh_token_expiry_seconds: int | None = None,
+        fastmcp_access_token_expiry_seconds: int | None = None,
+        token_expiry_threshold_seconds: int = 0,
+    ):
+        """Initialize AWS Cognito OAuth provider.
+
+        Args:
+            user_pool_id: Your Cognito User Pool ID (e.g., "eu-central-1_XXXXXXXXX")
+            client_id: Cognito app client ID
+            client_secret: Cognito app client secret
+            timeout_seconds: Timeout, in seconds, for the OIDC discovery request
+                made during construction. Defaults to 10 seconds so a slow or
+                unreachable issuer cannot block server startup indefinitely. Pass
+                None to fall back to the HTTP client's own default timeout.
+            base_url: Public URL where OAuth endpoints will be accessible (includes any mount path)
+            resource_base_url: Optional public base URL for the protected resource metadata
+                and token audience. Defaults to ``base_url``.
+            aws_region: AWS region where your User Pool is located (defaults to "eu-central-1")
+            issuer_url: Issuer URL for OAuth metadata (defaults to base_url). Use root-level URL
+                to avoid 404s during discovery when mounting under a path.
+            redirect_path: Redirect path configured in Cognito app (defaults to "/auth/callback")
+            required_scopes: Required Cognito scopes (defaults to ["openid"])
+            allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
+                If None (default), all URIs are allowed. If empty list, no URIs are allowed.
+            client_storage: Storage backend for OAuth state (client registrations, encrypted tokens).
+                If None, an encrypted file store will be created in the data directory
+                (derived from `platformdirs`).
+            jwt_signing_key: Secret for signing FastMCP JWT tokens (any string or bytes). If bytes are provided,
+                they will be used as is. If a string is provided, it will be derived into a 32-byte key. If not
+                provided, the upstream client secret will be used to derive a 32-byte key using PBKDF2.
+            require_authorization_consent: Whether to require user consent before authorizing clients (default True).
+                When True, users see a consent screen before being redirected to AWS Cognito.
+                When False, authorization proceeds directly without user confirmation.
+                When "external", the built-in consent screen is skipped but no warning is
+                logged, indicating that consent is handled externally (e.g. by the upstream IdP).
+                SECURITY WARNING: Only set to False for local development or testing environments.
+            fallback_refresh_token_expiry_seconds: Lifetime for the FastMCP-issued
+                refresh token when the upstream provider omits `refresh_expires_in`
+                (e.g. Cognito, GitHub, many OIDC IdPs). Defaults to 1 year. The upstream
+                refresh remains the source of truth. See `OAuthProxy` for details.
+            fastmcp_access_token_expiry_seconds: Lifetime for the FastMCP-issued access
+                token, decoupling it from the upstream provider's `expires_in`. Defaults
+                to None (mirror the upstream lifetime). Set this for bridges whose
+                upstream issues short-lived access tokens that some MCP clients can't
+                refresh gracefully (e.g. `mcp-remote`). See `OAuthProxy` for details.
+            token_expiry_threshold_seconds: Number of seconds before actual expiry to
+                treat a token as expired, refreshing early to avoid races. Defaults to 0.
+        """
+        # Parse scopes if provided as string
+        required_scopes_final = (
+            parse_scopes(required_scopes) if required_scopes is not None else ["openid"]
+        )
+
+        # Construct OIDC discovery URL
+        config_url = f"https://cognito-idp.{aws_region}.amazonaws.com/{user_pool_id}/.well-known/openid-configuration"
+
+        # Store Cognito-specific info for claim filtering
+        self.user_pool_id = user_pool_id
+        self.aws_region = aws_region
+        self.client_id = client_id
+
+        # Initialize OIDC proxy with Cognito discovery
+        super().__init__(
+            config_url=config_url,
+            client_id=client_id,
+            client_secret=client_secret,
+            timeout_seconds=timeout_seconds,
+            algorithm="RS256",
+            required_scopes=required_scopes_final,
+            base_url=base_url,
+            resource_base_url=resource_base_url,
+            issuer_url=issuer_url,
+            redirect_path=redirect_path,
+            allowed_client_redirect_uris=allowed_client_redirect_uris,
+            client_storage=client_storage,
+            jwt_signing_key=jwt_signing_key,
+            require_authorization_consent=require_authorization_consent,
+            consent_csp_policy=consent_csp_policy,
+            forward_resource=forward_resource,
+            fallback_refresh_token_expiry_seconds=fallback_refresh_token_expiry_seconds,
+            fastmcp_access_token_expiry_seconds=fastmcp_access_token_expiry_seconds,
+            token_expiry_threshold_seconds=token_expiry_threshold_seconds,
+        )
+
+        logger.debug(
+            "Initialized AWS Cognito OAuth provider for client %s with scopes: %s",
+            client_id,
+            required_scopes_final,
+        )
+
+    def get_token_verifier(
+        self,
+        *,
+        algorithm: str | None = None,
+        audience: str | None = None,
+        required_scopes: list[str] | None = None,
+        timeout_seconds: int | None = None,
+    ) -> AWSCognitoTokenVerifier:
+        """Creates a Cognito-specific token verifier with claim filtering.
+
+        Args:
+            algorithm: Optional token verifier algorithm
+            audience: Optional token verifier audience
+            required_scopes: Optional token verifier required_scopes
+            timeout_seconds: HTTP request timeout in seconds
+        """
+        return AWSCognitoTokenVerifier(
+            issuer=str(self.oidc_config.issuer),
+            audience=audience or self.client_id,
+            algorithm=algorithm,
+            jwks_uri=str(self.oidc_config.jwks_uri),
+            required_scopes=required_scopes,
+        )
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/azure.py b/fastmcp_slim/fastmcp/server/auth/providers/azure.py
new file mode 100644
index 0000000..89853d8
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/azure.py
@@ -0,0 +1,903 @@
+"""Azure (Microsoft Entra) OAuth provider for FastMCP.
+
+This provider implements Azure/Microsoft Entra ID OAuth authentication
+using the OAuth Proxy pattern for non-DCR OAuth flows.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections import OrderedDict
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+import httpx
+from key_value.aio.protocols import AsyncKeyValue
+
+from fastmcp.dependencies import Dependency
+from fastmcp.server.auth.auth import MultiAuth
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.utilities.auth import decode_jwt_payload, parse_scopes
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    from azure.identity.aio import OnBehalfOfCredential
+    from mcp.server.auth.provider import AuthorizationParams
+    from mcp.shared.auth import OAuthClientInformationFull
+    from pydantic import AnyHttpUrl
+
+    from fastmcp.server.auth.auth import AuthProvider
+
+logger = get_logger(__name__)
+
+# Standard OIDC scopes that should never be prefixed with identifier_uri.
+# Per Microsoft docs: https://learn.microsoft.com/en-us/entra/identity-platform/scopes-oidc
+# "OIDC scopes are requested as simple string identifiers without resource prefixes"
+OIDC_SCOPES = frozenset({"openid", "profile", "email", "offline_access"})
+
+
+class AzureProvider(OAuthProxy):
+    """Azure (Microsoft Entra) OAuth provider for FastMCP.
+
+    This provider implements Azure/Microsoft Entra ID authentication using the
+    OAuth Proxy pattern. It supports both organizational accounts and personal
+    Microsoft accounts depending on the tenant configuration.
+
+    Scope Handling:
+    - required_scopes: Provide unprefixed scope names (e.g., ["read", "write"])
+      → Automatically prefixed with identifier_uri during initialization
+      → Validated on all tokens and advertised to MCP clients
+    - additional_authorize_scopes: Provide full format (e.g., ["User.Read"])
+      → NOT prefixed, NOT validated, NOT advertised to clients
+      → Used to request Microsoft Graph or other upstream API permissions
+
+    Features:
+    - OAuth proxy to Azure/Microsoft identity platform
+    - JWT validation using tenant issuer and JWKS
+    - Supports tenant configurations: specific tenant ID, "organizations", or "consumers"
+    - Custom API scopes and Microsoft Graph scopes in a single provider
+
+    Setup:
+    1. Create an App registration in Azure Portal
+    2. Configure Web platform redirect URI: http://localhost:8000/auth/callback (or your custom path)
+    3. Add an Application ID URI under "Expose an API" (defaults to api://{client_id})
+    4. Add custom scopes (e.g., "read", "write") under "Expose an API"
+    5. Set access token version to 2 in the App manifest: "requestedAccessTokenVersion": 2
+    6. Create a client secret
+    7. Get Application (client) ID, Directory (tenant) ID, and client secret
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth.providers.azure import AzureProvider
+
+        # Standard Azure (Public Cloud)
+        auth = AzureProvider(
+            client_id="your-client-id",
+            client_secret="your-client-secret",
+            tenant_id="your-tenant-id",
+            required_scopes=["read", "write"],  # Unprefixed scope names
+            additional_authorize_scopes=["User.Read", "Mail.Read"],  # Optional Graph scopes
+            base_url="http://localhost:8000",
+            # identifier_uri defaults to api://{client_id}
+        )
+
+        # Azure Government
+        auth_gov = AzureProvider(
+            client_id="your-client-id",
+            client_secret="your-client-secret",
+            tenant_id="your-tenant-id",
+            required_scopes=["read", "write"],
+            base_authority="login.microsoftonline.us",  # Override for Azure Gov
+            base_url="http://localhost:8000",
+        )
+
+        mcp = FastMCP("My App", auth=auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        client_id: str,
+        client_secret: str | None = None,
+        tenant_id: str,
+        required_scopes: list[str],
+        base_url: str,
+        resource_base_url: AnyHttpUrl | str | None = None,
+        identifier_uri: str | None = None,
+        issuer_url: str | None = None,
+        redirect_path: str | None = None,
+        additional_authorize_scopes: list[str] | None = None,
+        allowed_client_redirect_uris: list[str] | None = None,
+        client_storage: AsyncKeyValue | None = None,
+        jwt_signing_key: str | bytes | None = None,
+        require_authorization_consent: bool | Literal["remember", "external"] = True,
+        consent_csp_policy: str | None = None,
+        forward_resource: bool = True,
+        fallback_refresh_token_expiry_seconds: int | None = None,
+        fastmcp_access_token_expiry_seconds: int | None = None,
+        token_expiry_threshold_seconds: int = 0,
+        base_authority: str = "login.microsoftonline.com",
+        token_issuer: str | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        enable_cimd: bool = True,
+    ) -> None:
+        """Initialize Azure OAuth provider.
+
+        Args:
+            client_id: Azure application (client) ID from your App registration
+            client_secret: Azure client secret from your App registration. Optional when
+                using alternative credentials (e.g., managed identity with a custom
+                _create_upstream_oauth_client override). When omitted, jwt_signing_key
+                must be provided.
+            tenant_id: Azure tenant ID (specific tenant GUID, "organizations", or "consumers")
+            identifier_uri: Optional Application ID URI for your custom API (defaults to api://{client_id}).
+                This URI is automatically prefixed to all required_scopes during initialization.
+                Example: identifier_uri="api://my-api" + required_scopes=["read"]
+                → tokens validated for "api://my-api/read"
+            base_url: Public URL where OAuth endpoints will be accessible (includes any mount path)
+            resource_base_url: Optional public base URL for the protected resource metadata
+                and token audience. Defaults to ``base_url``.
+            issuer_url: Issuer URL for OAuth metadata (defaults to base_url). Use root-level URL
+                to avoid 404s during discovery when mounting under a path.
+            redirect_path: Redirect path configured in Azure App registration (defaults to "/auth/callback")
+            base_authority: Azure authority base URL (defaults to "login.microsoftonline.com").
+                For Azure Government, use "login.microsoftonline.us".
+            token_issuer: Override the expected `iss` claim value for JWT validation.
+                Defaults to the standard Entra ID issuer derived from `base_authority`
+                and `tenant_id`. Pass an explicit string to enforce a specific issuer.
+            required_scopes: Custom API scope names WITHOUT prefix (e.g., ["read", "write"]).
+                - Automatically prefixed with identifier_uri during initialization
+                - Validated on all tokens
+                - Advertised in Protected Resource Metadata
+                - Must match scope names defined in Azure Portal under "Expose an API"
+                Example: ["read", "write"] → validates tokens containing ["api://xxx/read", "api://xxx/write"]
+            additional_authorize_scopes: Microsoft Graph or other upstream scopes in full format.
+                - NOT prefixed with identifier_uri
+                - NOT validated on tokens
+                - NOT advertised to MCP clients
+                - Used to request additional permissions from Azure (e.g., Graph API access)
+                Example: ["User.Read", "Mail.Read"]
+                These scopes allow your FastMCP server to call Microsoft Graph APIs using the
+                upstream Azure token, but MCP clients are unaware of them.
+                Note: "offline_access" is automatically included to obtain refresh tokens.
+            allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
+                If None (default), all URIs are allowed. If empty list, no URIs are allowed.
+            client_storage: Storage backend for OAuth state (client registrations, encrypted tokens).
+                If None, an encrypted file store will be created in the data directory
+                (derived from `platformdirs`).
+            jwt_signing_key: Secret for signing FastMCP JWT tokens (any string or bytes). If bytes are provided,
+                they will be used as is. If a string is provided, it will be derived into a 32-byte key. If not
+                provided, the upstream client secret will be used to derive a 32-byte key using PBKDF2.
+            require_authorization_consent: Whether to require user consent before authorizing clients (default True).
+                When True, users see a consent screen before being redirected to Azure.
+                When False, authorization proceeds directly without user confirmation.
+                When "external", the built-in consent screen is skipped but no warning is
+                logged, indicating that consent is handled externally (e.g. by the upstream IdP).
+                SECURITY WARNING: Only set to False for local development or testing environments.
+            http_client: Optional httpx.AsyncClient for connection pooling in JWKS fetches.
+                When provided, the client is reused for JWT key fetches and the caller
+                is responsible for its lifecycle. When None (default), a fresh client is created per fetch.
+            enable_cimd: Enable CIMD (Client ID Metadata Document) support for URL-based
+                client IDs (default True). Set to False to disable.
+            fallback_refresh_token_expiry_seconds: Lifetime for the FastMCP-issued
+                refresh token when the upstream provider omits `refresh_expires_in`
+                (e.g. Cognito, GitHub, many OIDC IdPs). Defaults to 1 year. The upstream
+                refresh remains the source of truth. See `OAuthProxy` for details.
+            fastmcp_access_token_expiry_seconds: Lifetime for the FastMCP-issued access
+                token, decoupling it from the upstream provider's `expires_in`. Defaults
+                to None (mirror the upstream lifetime). Set this for bridges whose
+                upstream issues short-lived access tokens that some MCP clients can't
+                refresh gracefully (e.g. `mcp-remote`). See `OAuthProxy` for details.
+            token_expiry_threshold_seconds: Number of seconds before actual expiry to
+                treat a token as expired, refreshing early to avoid races. Defaults to 0.
+        """
+        # Parse scopes if provided as string
+        parsed_required_scopes = parse_scopes(required_scopes)
+        parsed_additional_scopes: list[str] = (
+            parse_scopes(additional_authorize_scopes) or []
+            if additional_authorize_scopes
+            else []
+        )
+
+        # Always include offline_access to get refresh tokens from Azure
+        if "offline_access" not in parsed_additional_scopes:
+            parsed_additional_scopes = [*parsed_additional_scopes, "offline_access"]
+
+        # Store Azure-specific config for OBO credential creation
+        self._tenant_id = tenant_id
+        self._base_authority = base_authority
+
+        # Cache of OBO credentials keyed by hash of user assertion token.
+        # Reusing credentials allows the Azure SDK's internal token cache
+        # to avoid redundant OBO exchanges for the same user + scopes.
+        self._obo_credentials: OrderedDict[str, OnBehalfOfCredential] = OrderedDict()
+        self._obo_max_credentials: int = 128
+        self._obo_supported = True
+
+        # Apply defaults
+        self.identifier_uri = identifier_uri or f"api://{client_id}"
+        self.additional_authorize_scopes: list[str] = parsed_additional_scopes
+
+        # Always validate tokens against the app's API client ID using JWT
+        issuer = token_issuer or f"https://{base_authority}/{tenant_id}/v2.0"
+        jwks_uri = f"https://{base_authority}/{tenant_id}/discovery/v2.0/keys"
+
+        # Azure access tokens only include custom API scopes in the `scp` claim,
+        # NOT standard OIDC scopes (openid, profile, email, offline_access).
+        # Filter out OIDC scopes from validation - they'll still be sent to Azure
+        # during authorization (handled by _prefix_scopes_for_azure).
+        validation_scopes = [
+            s for s in (parsed_required_scopes or []) if s not in OIDC_SCOPES
+        ]
+        if not validation_scopes:
+            raise ValueError(
+                "AzureProvider requires at least one non-OIDC scope in "
+                "required_scopes (e.g., 'read', 'write'). OIDC scopes like "
+                "'openid', 'profile', 'email', and 'offline_access' are not "
+                "included in Azure access token claims and cannot be used for "
+                "scope enforcement."
+            )
+
+        token_verifier = JWTVerifier(
+            jwks_uri=jwks_uri,
+            issuer=issuer,
+            audience=[client_id, self.identifier_uri],
+            algorithm="RS256",
+            required_scopes=validation_scopes,  # Only validate non-OIDC scopes
+            http_client=http_client,
+        )
+
+        # Build Azure OAuth endpoints with tenant
+        authorization_endpoint = (
+            f"https://{base_authority}/{tenant_id}/oauth2/v2.0/authorize"
+        )
+        token_endpoint = f"https://{base_authority}/{tenant_id}/oauth2/v2.0/token"
+
+        # Initialize OAuth proxy with Azure endpoints
+        # Remember there's hooks called, such as _prepare_scopes_for_token_exchange
+        # and _prepare_scopes_for_upstream_refresh
+        super().__init__(
+            upstream_authorization_endpoint=authorization_endpoint,
+            upstream_token_endpoint=token_endpoint,
+            upstream_client_id=client_id,
+            upstream_client_secret=client_secret,
+            token_verifier=token_verifier,
+            base_url=base_url,
+            resource_base_url=resource_base_url,
+            redirect_path=redirect_path,
+            issuer_url=issuer_url or base_url,  # Default to base_url if not specified
+            allowed_client_redirect_uris=allowed_client_redirect_uris,
+            client_storage=client_storage,
+            jwt_signing_key=jwt_signing_key,
+            require_authorization_consent=require_authorization_consent,
+            consent_csp_policy=consent_csp_policy,
+            forward_resource=forward_resource,
+            fallback_refresh_token_expiry_seconds=fallback_refresh_token_expiry_seconds,
+            fastmcp_access_token_expiry_seconds=fastmcp_access_token_expiry_seconds,
+            token_expiry_threshold_seconds=token_expiry_threshold_seconds,
+            valid_scopes=parsed_required_scopes,
+            enable_cimd=enable_cimd,
+        )
+
+        authority_info = ""
+        if base_authority != "login.microsoftonline.com":
+            authority_info = f" using authority {base_authority}"
+        logger.info(
+            "Initialized Azure OAuth provider for client %s with tenant %s%s%s",
+            client_id,
+            tenant_id,
+            f" and identifier_uri {self.identifier_uri}" if self.identifier_uri else "",
+            authority_info,
+        )
+
+    @classmethod
+    def from_b2c(
+        cls,
+        *,
+        tenant_name: str,
+        policy_name: str,
+        client_id: str,
+        client_secret: str | None = None,
+        required_scopes: list[str],
+        base_url: str,
+        custom_domain: str | None = None,
+        identifier_uri: str | None = None,
+        token_issuer: str | None = None,
+        **kwargs: Any,
+    ) -> AzureProvider:
+        """Create an AzureProvider pre-configured for Azure AD B2C.
+
+        Derives authority host, tenant path, and identifier URI from
+        `tenant_name` and `policy_name`, then delegates to the standard
+        constructor. Returns a plain `AzureProvider` instance.
+
+        B2C issuer validation is disabled by default (`token_issuer=None`)
+        because B2C issuers embed the tenant GUID. Pass an explicit
+        `token_issuer` string once you know the real `iss` value.
+
+        Azure AD B2C does **not** support OBO.
+
+        Args:
+            tenant_name: Short B2C tenant name without `.onmicrosoft.com`
+                (e.g. `"mytenant"`).
+            policy_name: User-flow or custom-policy name
+                (e.g. `"B2C_1_susi"`).
+            client_id: Application (client) ID from the B2C app registration.
+            client_secret: Client secret from the B2C app registration.
+            required_scopes: Custom API scope names without prefix
+                (e.g. `["mcp-access"]`).
+            base_url: Public base URL of this server.
+            custom_domain: Custom domain for the B2C authority
+                (e.g. `"auth.mycompany.com"`). Defaults to
+                `{tenant_name}.b2clogin.com`.
+            identifier_uri: Application ID URI. Defaults to
+                `https://{tenant_name}.onmicrosoft.com/{client_id}`.
+            token_issuer: Expected `iss` claim. `None` (default) disables
+                issuer validation.
+            **kwargs: Forwarded to `AzureProvider.__init__`.
+        """
+        if ".onmicrosoft.com" in tenant_name:
+            raise ValueError(
+                f"tenant_name should be the short name without the "
+                f".onmicrosoft.com suffix (e.g. 'mytenant'), got {tenant_name!r}"
+            )
+
+        if custom_domain is not None:
+            custom_domain = (
+                custom_domain.removeprefix("https://")
+                .removeprefix("http://")
+                .rstrip("/")
+            )
+
+        authority = custom_domain or f"{tenant_name}.b2clogin.com"
+        tenant_path = f"{tenant_name}.onmicrosoft.com/{policy_name}"
+        uri = identifier_uri or f"https://{tenant_name}.onmicrosoft.com/{client_id}"
+
+        provider = cls(
+            client_id=client_id,
+            client_secret=client_secret,
+            tenant_id=tenant_path,
+            required_scopes=required_scopes,
+            base_url=base_url,
+            base_authority=authority,
+            identifier_uri=uri,
+            token_issuer=token_issuer,
+            **kwargs,
+        )
+        if isinstance(provider._token_validator, JWTVerifier):
+            provider._token_validator.issuer = token_issuer
+        provider._obo_supported = False
+        return provider
+
+    async def authorize(
+        self,
+        client: OAuthClientInformationFull,
+        params: AuthorizationParams,
+    ) -> str:
+        """Start OAuth transaction and redirect to Azure AD.
+
+        Override parent's authorize method to filter out the 'resource' parameter
+        which is not supported by Azure AD v2.0 endpoints. The v2.0 endpoints use
+        scopes to determine the resource/audience instead of a separate parameter.
+
+        Args:
+            client: OAuth client information
+            params: Authorization parameters from the client
+
+        Returns:
+            Authorization URL to redirect the user to Azure AD
+        """
+        # Clear the resource parameter that Azure AD v2.0 doesn't support
+        # This parameter comes from RFC 8707 (OAuth 2.0 Resource Indicators)
+        # but Azure AD v2.0 uses scopes instead to determine the audience
+        params_to_use = params
+        if hasattr(params, "resource"):
+            original_resource = getattr(params, "resource", None)
+            if original_resource is not None:
+                params_to_use = params.model_copy(update={"resource": None})
+                if original_resource:
+                    logger.debug(
+                        "Filtering out 'resource' parameter '%s' for Azure AD v2.0 (use scopes instead)",
+                        original_resource,
+                    )
+        # Don't modify the scopes in params - they stay unprefixed for MCP clients
+        # We'll prefix them when building the Azure authorization URL (in _build_upstream_authorize_url)
+        auth_url = await super().authorize(client, params_to_use)
+        separator = "&" if "?" in auth_url else "?"
+        return f"{auth_url}{separator}prompt=select_account"
+
+    def _prefix_scopes_for_azure(self, scopes: list[str]) -> list[str]:
+        """Prefix unprefixed custom API scopes with identifier_uri for Azure.
+
+        This helper centralizes the scope prefixing logic used in both
+        authorization and token refresh flows.
+
+        Scopes that are NOT prefixed:
+        - Standard OIDC scopes (openid, profile, email, offline_access)
+        - Fully-qualified URIs (contain "://")
+        - Scopes with path component (contain "/")
+
+        Note: Microsoft Graph scopes (e.g., User.Read) should be passed via
+        `additional_authorize_scopes` or use fully-qualified format
+        (e.g., https://graph.microsoft.com/User.Read).
+
+        Args:
+            scopes: List of scopes, may be prefixed or unprefixed
+
+        Returns:
+            List of scopes with identifier_uri prefix applied where needed
+        """
+        prefixed = []
+        for scope in scopes:
+            if scope in OIDC_SCOPES:
+                # Standard OIDC scopes - never prefix
+                prefixed.append(scope)
+            elif "://" in scope or "/" in scope:
+                # Already fully-qualified (e.g., "api://xxx/read" or
+                # "https://graph.microsoft.com/User.Read")
+                prefixed.append(scope)
+            else:
+                # Unprefixed custom API scope - prefix with identifier_uri
+                prefixed.append(f"{self.identifier_uri}/{scope}")
+        return prefixed
+
+    def _translate_scopes_from_idp(self, scopes: list[str]) -> list[str]:
+        """Strip ``{identifier_uri}/`` from custom API scopes Azure echoes back.
+
+        Inverse of :meth:`_prefix_scopes_for_azure`. Azure echoes the prefixed
+        form (``api://{client_id}/read``) in its token response's ``scope``
+        field, while MCP clients request and recognize the short form
+        (``read``) — the same form advertised on
+        ``/.well-known/oauth-authorization-server`` via ``valid_scopes``. Without
+        this translation, strict clients compare requested vs. granted scopes
+        and surface a "permissions not granted" warning (e.g. ChatGPT) even
+        when nothing is actually wrong.
+
+        OIDC scopes (``openid``, ``profile``, ``email``, ``offline_access``) and
+        external resource URIs (Microsoft Graph, etc.) never carry the prefix,
+        so :meth:`str.removeprefix` is a no-op on them and they pass through
+        unchanged.
+        """
+        prefix = f"{self.identifier_uri}/"
+        return [s.removeprefix(prefix) for s in scopes]
+
+    def _build_upstream_authorize_url(
+        self, txn_id: str, transaction: dict[str, Any]
+    ) -> str:
+        """Build Azure authorization URL with prefixed scopes.
+
+        Overrides parent to prefix scopes with identifier_uri before sending to Azure,
+        while keeping unprefixed scopes in the transaction for MCP clients.
+        """
+        # Get unprefixed scopes from transaction
+        unprefixed_scopes = transaction.get("scopes") or self.required_scopes or []
+
+        # Prefix scopes for Azure authorization request
+        prefixed_scopes = self._prefix_scopes_for_azure(unprefixed_scopes)
+
+        # Add Microsoft Graph scopes (not validated, not prefixed)
+        if self.additional_authorize_scopes:
+            prefixed_scopes.extend(self.additional_authorize_scopes)
+
+        # Temporarily modify transaction dict for parent's URL building
+        modified_transaction = transaction.copy()
+        modified_transaction["scopes"] = prefixed_scopes
+
+        # Let parent build the URL with prefixed scopes
+        return super()._build_upstream_authorize_url(txn_id, modified_transaction)
+
+    def _prepare_scopes_for_token_exchange(self, scopes: list[str]) -> list[str]:
+        """Prepare scopes for Azure authorization code exchange.
+
+        Azure requires scopes during token exchange (AADSTS28003 error if missing).
+        Azure only allows ONE resource per token request (AADSTS28000), so we only
+        include scopes for this API plus OIDC scopes.
+
+        Args:
+            scopes: Scopes from the authorization request (unprefixed)
+
+        Returns:
+            List of scopes for Azure token endpoint
+        """
+        # Prefix scopes for this API. Some clients omit the scope parameter on
+        # the MCP authorization request; use the provider's configured scopes
+        # just like the authorize URL path does.
+        prefixed_scopes = self._prefix_scopes_for_azure(
+            scopes or self.required_scopes or []
+        )
+
+        # Add OIDC scopes only (not other API scopes) to avoid AADSTS28000
+        if self.additional_authorize_scopes:
+            prefixed_scopes.extend(
+                s for s in self.additional_authorize_scopes if s in OIDC_SCOPES
+            )
+
+        deduplicated = list(dict.fromkeys(prefixed_scopes))
+        logger.debug("Token exchange scopes: %s", deduplicated)
+        return deduplicated
+
+    def _prepare_scopes_for_upstream_refresh(self, scopes: list[str]) -> list[str]:
+        """Prepare scopes for Azure token refresh.
+
+        Azure requires fully-qualified scopes and only allows ONE resource per
+        token request (AADSTS28000). We include scopes for this API plus OIDC scopes.
+
+        Args:
+            scopes: Base scopes from RefreshToken (unprefixed, e.g., ["read"])
+
+        Returns:
+            Deduplicated list of scopes formatted for Azure token endpoint
+        """
+        logger.debug("Base scopes from storage: %s", scopes)
+
+        # Some clients omit the scope parameter on the MCP authorization request;
+        # use the provider's configured scopes just like the authorize URL path does.
+        requested_scopes = scopes or self.required_scopes or []
+
+        # Filter out any additional_authorize_scopes that may have been stored
+        additional_scopes_set = set(self.additional_authorize_scopes or [])
+        base_scopes = [s for s in requested_scopes if s not in additional_scopes_set]
+
+        # Prefix base scopes with identifier_uri for Azure
+        prefixed_scopes = self._prefix_scopes_for_azure(base_scopes)
+
+        # Add OIDC scopes only (not other API scopes) to avoid AADSTS28000
+        if self.additional_authorize_scopes:
+            prefixed_scopes.extend(
+                s for s in self.additional_authorize_scopes if s in OIDC_SCOPES
+            )
+
+        deduplicated_scopes = list(dict.fromkeys(prefixed_scopes))
+        logger.debug("Scopes for Azure token endpoint: %s", deduplicated_scopes)
+        return deduplicated_scopes
+
+    async def _extract_upstream_claims(
+        self, idp_tokens: dict[str, Any]
+    ) -> dict[str, Any] | None:
+        """Extract claims from Azure token response to embed in FastMCP JWT.
+
+        Decodes the Azure access token (which is a JWT) to extract user identity
+        claims. This allows gateways to inspect upstream identity information by
+        decoding the FastMCP JWT without needing server-side storage lookups.
+
+        Azure access tokens contain claims like:
+        - sub: Subject identifier (unique per user per application)
+        - oid: Object ID (unique user identifier across Azure AD)
+        - tid: Tenant ID
+        - azp: Authorized party (client ID that requested the token)
+        - name: Display name
+        - given_name: First name
+        - family_name: Last name
+        - preferred_username: User principal name (email format)
+        - upn: User Principal Name
+        - email: Email address (if available)
+        - roles: Application roles assigned to the user
+        - groups: Group memberships (if configured)
+
+        Args:
+            idp_tokens: Full token response from Azure, containing access_token
+                and potentially id_token.
+
+        Returns:
+            Dict of extracted claims, or None if extraction fails.
+        """
+        access_token = idp_tokens.get("access_token")
+        if not access_token:
+            return None
+
+        try:
+            # Azure access tokens are JWTs - decode without verification
+            # (already validated by token_verifier during token exchange)
+            payload = decode_jwt_payload(access_token)
+
+            # Extract useful identity claims
+            claims: dict[str, Any] = {}
+            claim_keys = [
+                "sub",
+                "oid",
+                "tid",
+                "azp",
+                "name",
+                "given_name",
+                "family_name",
+                "preferred_username",
+                "upn",
+                "email",
+                "roles",
+                "groups",
+            ]
+            for claim in claim_keys:
+                if claim in payload:
+                    claims[claim] = payload[claim]
+
+            if claims:
+                logger.debug(
+                    "Extracted %d Azure claims for embedding in FastMCP JWT",
+                    len(claims),
+                )
+                return claims
+
+            return None
+
+        except Exception as e:
+            logger.debug("Failed to extract Azure claims: %s", e)
+            return None
+
+    async def get_obo_credential(self, user_assertion: str) -> OnBehalfOfCredential:
+        """Get a cached or new OnBehalfOfCredential for OBO token exchange.
+
+        Credentials are cached by user assertion so the Azure SDK's internal
+        token cache can avoid redundant OBO exchanges when the same user
+        calls multiple tools with the same scopes.
+
+        Args:
+            user_assertion: The user's access token to exchange via OBO.
+
+        Returns:
+            A configured OnBehalfOfCredential ready for get_token() calls.
+
+        Raises:
+            NotImplementedError: If OBO is not supported (e.g. Azure AD B2C).
+            ImportError: If azure-identity is not installed (requires fastmcp[azure]).
+        """
+        if not self._obo_supported:
+            raise NotImplementedError(
+                "Azure AD B2C does not support the On-Behalf-Of (OBO) flow. "
+                "Use AzureProvider with standard Entra ID for OBO scenarios."
+            )
+        _require_azure_identity("OBO token exchange")
+        from azure.identity.aio import OnBehalfOfCredential
+
+        key = hashlib.sha256(user_assertion.encode()).hexdigest()
+
+        if key in self._obo_credentials:
+            self._obo_credentials.move_to_end(key)
+            return self._obo_credentials[key]
+
+        obo_kwargs: dict[str, Any] = {
+            "tenant_id": self._tenant_id,
+            "client_id": self._upstream_client_id,
+            "user_assertion": user_assertion,
+            "authority": f"https://{self._base_authority}",
+        }
+        if self._upstream_client_secret is not None:
+            obo_kwargs["client_secret"] = (
+                self._upstream_client_secret.get_secret_value()
+            )
+        else:
+            raise ValueError(
+                "OBO token exchange requires either a client_secret or a subclass "
+                "that overrides get_obo_credential() to provide alternative credentials "
+                "(e.g., client_assertion_func for managed identity)."
+            )
+        credential = OnBehalfOfCredential(**obo_kwargs)
+        self._obo_credentials[key] = credential
+
+        # Evict oldest if over capacity
+        while len(self._obo_credentials) > self._obo_max_credentials:
+            _, evicted = self._obo_credentials.popitem(last=False)
+            await evicted.close()
+
+        return credential
+
+    async def close_obo_credentials(self) -> None:
+        """Close all cached OBO credentials."""
+        credentials = list(self._obo_credentials.values())
+        self._obo_credentials.clear()
+        for credential in credentials:
+            try:
+                await credential.close()
+            except Exception:
+                logger.debug("Error closing OBO credential", exc_info=True)
+
+
+class AzureJWTVerifier(JWTVerifier):
+    """JWT verifier pre-configured for Azure AD / Microsoft Entra ID.
+
+    Auto-configures JWKS URI, issuer, audience, and scope handling from your
+    Azure app registration details. Designed for Managed Identity and other
+    token-verification-only scenarios where AzureProvider's full OAuth proxy
+    isn't needed.
+
+    Handles Azure's scope format automatically:
+    - Validates tokens using short-form scopes (what Azure puts in ``scp`` claims)
+    - Advertises full-URI scopes in OAuth metadata (what clients need to request)
+
+    Example::
+
+        from fastmcp.server.auth import RemoteAuthProvider
+        from fastmcp.server.auth.providers.azure import AzureJWTVerifier
+        from pydantic import AnyHttpUrl
+
+        verifier = AzureJWTVerifier(
+            client_id="your-client-id",
+            tenant_id="your-tenant-id",
+            required_scopes=["access_as_user"],
+        )
+
+        auth = RemoteAuthProvider(
+            token_verifier=verifier,
+            authorization_servers=[
+                AnyHttpUrl("https://login.microsoftonline.com/your-tenant-id/v2.0")
+            ],
+            base_url="https://my-server.com",
+        )
+    """
+
+    def __init__(
+        self,
+        *,
+        client_id: str,
+        tenant_id: str,
+        required_scopes: list[str] | None = None,
+        identifier_uri: str | None = None,
+        base_authority: str = "login.microsoftonline.com",
+    ):
+        """Initialize Azure JWT verifier.
+
+        Args:
+            client_id: Azure application (client) ID from your App registration
+            tenant_id: Azure tenant ID (specific tenant GUID, "organizations", or "consumers").
+                For multi-tenant apps ("organizations" or "consumers"), issuer validation
+                is skipped since Azure tokens carry the actual tenant GUID as issuer.
+            required_scopes: Scope names as they appear in Azure Portal under "Expose an API"
+                (e.g., ["access_as_user", "read"]). These are validated against
+                the short-form scopes in token ``scp`` claims, and automatically
+                prefixed with identifier_uri for OAuth metadata.
+            identifier_uri: Application ID URI (defaults to ``api://{client_id}``).
+                Used to prefix scopes in OAuth metadata so clients know the full
+                scope URIs to request from Azure.
+            base_authority: Azure authority base URL (defaults to "login.microsoftonline.com").
+                For Azure Government, use "login.microsoftonline.us".
+        """
+        self._identifier_uri = identifier_uri or f"api://{client_id}"
+
+        # For multi-tenant apps, Azure tokens carry the actual tenant GUID as
+        # issuer, not the literal "organizations" or "consumers" string. Skip
+        # issuer validation for these — audience still protects against wrong-app tokens.
+        multi_tenant_values = {"organizations", "consumers", "common"}
+        issuer: str | None = (
+            None
+            if tenant_id in multi_tenant_values
+            else f"https://{base_authority}/{tenant_id}/v2.0"
+        )
+
+        super().__init__(
+            jwks_uri=f"https://{base_authority}/{tenant_id}/discovery/v2.0/keys",
+            issuer=issuer,
+            audience=[client_id, self._identifier_uri],
+            algorithm="RS256",
+            required_scopes=required_scopes,
+        )
+
+    @property
+    def scopes_supported(self) -> list[str]:
+        """Return scopes with Azure URI prefix for OAuth metadata.
+
+        Azure tokens contain short-form scopes (e.g., ``read``) in the ``scp``
+        claim, but clients must request full URI scopes (e.g.,
+        ``api://client-id/read``) from the Azure authorization endpoint. This
+        property returns the full-URI form for OAuth metadata while
+        ``required_scopes`` retains the short form for token validation.
+        """
+        if not self.required_scopes:
+            return []
+        prefixed = []
+        for scope in self.required_scopes:
+            if scope in OIDC_SCOPES or "://" in scope or "/" in scope:
+                prefixed.append(scope)
+            else:
+                prefixed.append(f"{self._identifier_uri}/{scope}")
+        return prefixed
+
+
+# --- Dependency injection support ---
+# These require fastmcp[azure] extra for azure-identity
+
+
+def _require_azure_identity(feature: str) -> None:
+    """Raise ImportError with install instructions if azure-identity is not available."""
+    try:
+        import azure.identity  # noqa: F401
+    except ImportError as e:
+        raise ImportError(
+            f"{feature} requires the `azure` extra. "
+            "Install with: pip install 'fastmcp[azure]'"
+        ) from e
+
+
+def _find_azure_provider(auth: AuthProvider | None) -> AzureProvider | None:
+    """Extract an AzureProvider from an auth provider, unwrapping MultiAuth if needed."""
+    if isinstance(auth, AzureProvider):
+        return auth
+
+    if isinstance(auth, MultiAuth) and isinstance(auth.server, AzureProvider):
+        return auth.server
+
+    return None
+
+
+class _EntraOBOToken(Dependency[str]):
+    """Dependency that performs OBO token exchange for Microsoft Entra.
+
+    Uses azure.identity's OnBehalfOfCredential for async-native OBO,
+    with automatic token caching and refresh. Credentials are cached on
+    the AzureProvider so repeated tool calls reuse existing credentials
+    and benefit from the Azure SDK's internal token cache.
+    """
+
+    def __init__(self, scopes: list[str]):
+        self.scopes = scopes
+
+    async def __aenter__(self) -> str:
+        _require_azure_identity("EntraOBOToken")
+
+        from fastmcp.server.dependencies import get_access_token, get_server
+
+        access_token = get_access_token()
+        if access_token is None:
+            raise RuntimeError(
+                "No access token available. Cannot perform OBO exchange."
+            )
+
+        server = get_server()
+        azure_provider = _find_azure_provider(server.auth)
+        if azure_provider is None:
+            raise RuntimeError(
+                "EntraOBOToken requires an AzureProvider as the auth provider. "
+                f"Current provider: {type(server.auth).__name__}"
+            )
+
+        credential = await azure_provider.get_obo_credential(
+            user_assertion=access_token.token,
+        )
+
+        result = await credential.get_token(*self.scopes)
+        return result.token
+
+
+def EntraOBOToken(scopes: list[str]) -> str:
+    """Exchange the user's Entra token for a downstream API token via OBO.
+
+    This dependency performs a Microsoft Entra On-Behalf-Of (OBO) token exchange,
+    allowing your MCP server to call downstream APIs (like Microsoft Graph) on
+    behalf of the authenticated user.
+
+    Args:
+        scopes: The scopes to request for the downstream API. For Microsoft Graph,
+            use scopes like ["https://graph.microsoft.com/Mail.Read"] or
+            ["https://graph.microsoft.com/.default"].
+
+    Returns:
+        A dependency that resolves to the downstream API access token string
+
+    Raises:
+        ImportError: If fastmcp[azure] is not installed
+        RuntimeError: If no access token is available, provider is not Azure,
+            or OBO exchange fails
+
+    Example:
+        ```python
+        from fastmcp.server.auth.providers.azure import EntraOBOToken
+        import httpx
+
+        @mcp.tool()
+        async def get_my_emails(
+            graph_token: str = EntraOBOToken(["https://graph.microsoft.com/Mail.Read"])
+        ):
+            async with httpx.AsyncClient() as client:
+                resp = await client.get(
+                    "https://graph.microsoft.com/v1.0/me/messages",
+                    headers={"Authorization": f"Bearer {graph_token}"}
+                )
+                return resp.json()
+        ```
+
+    Note:
+        For OBO to work, ensure the scopes are included in the AzureProvider's
+        `additional_authorize_scopes` parameter, and that admin consent has been
+        granted for those scopes in your Entra app registration.
+    """
+    return cast(str, _EntraOBOToken(scopes))
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/clerk.py b/fastmcp_slim/fastmcp/server/auth/providers/clerk.py
new file mode 100644
index 0000000..21d7c3b
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/clerk.py
@@ -0,0 +1,405 @@
+"""Clerk OAuth provider for FastMCP.
+
+This module provides a complete Clerk OAuth integration that's ready to use
+with a Clerk domain, client ID, and client secret. It handles all the complexity
+of Clerk's OAuth/OIDC flow, token validation, and user management.
+
+Clerk uses standard OIDC endpoints derived from the instance domain
+(e.g., ``https://<instance>.clerk.accounts.dev``). Token verification is
+performed via the introspection endpoint (RFC 7662) for security-critical
+checks (active status, audience, scopes), followed by the userinfo endpoint
+for profile enrichment. Userinfo failure is non-fatal.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth.providers.clerk import ClerkProvider
+
+    auth = ClerkProvider(
+        domain="saving-primate-16.clerk.accounts.dev",
+        client_id="your-clerk-client-id",
+        client_secret="your-clerk-client-secret",
+        base_url="https://my-server.com",
+    )
+
+    mcp = FastMCP("My Protected Server", auth=auth)
+    ```
+"""
+
+from __future__ import annotations
+
+import contextlib
+from typing import Literal
+
+import httpx
+from key_value.aio.protocols import AsyncKeyValue
+from pydantic import AnyHttpUrl
+
+from fastmcp.server.auth import TokenVerifier
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class ClerkTokenVerifier(TokenVerifier):
+    """Token verifier for Clerk OAuth tokens.
+
+    Clerk issues standard OIDC tokens. Verification uses the introspection
+    endpoint (RFC 7662) as the primary security gate — it confirms the token
+    is active and provides metadata (scopes, expiry, audience). The userinfo
+    endpoint is called second for profile enrichment (name, email, picture)
+    and its failure is non-fatal.
+
+    When a ``client_id`` is configured, the audience from introspection is
+    validated against it. When ``required_scopes`` are configured,
+    introspection must return the token's scopes — the verifier will not
+    assume scopes when introspection is unavailable.
+    """
+
+    def __init__(
+        self,
+        *,
+        domain: str,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        required_scopes: list[str] | None = None,
+        timeout_seconds: int = 10,
+        http_client: httpx.AsyncClient | None = None,
+    ):
+        """Initialize the Clerk token verifier.
+
+        Args:
+            domain: Clerk instance domain (e.g., "saving-primate-16.clerk.accounts.dev")
+            client_id: Clerk OAuth client ID, used for introspection endpoint authentication
+            client_secret: Clerk OAuth client secret, used for introspection endpoint authentication
+            required_scopes: Required OAuth scopes (e.g., ["openid", "email", "profile"])
+            timeout_seconds: HTTP request timeout
+            http_client: Optional httpx.AsyncClient for connection pooling. When provided,
+                the client is reused across calls and the caller is responsible for its
+                lifecycle. When None (default), a fresh client is created per call.
+        """
+        super().__init__(required_scopes=required_scopes)
+        self.domain = domain.rstrip("/")
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self.timeout_seconds = timeout_seconds
+        self._http_client = http_client
+
+        self._userinfo_url = f"https://{self.domain}/oauth/userinfo"
+        self._introspection_url = f"https://{self.domain}/oauth/token_info"
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify a Clerk OAuth token via introspection and userinfo.
+
+        Calls the introspection endpoint first to validate the token and
+        retrieve auth metadata (active status, scopes, expiry, audience).
+        If the token passes security checks, the userinfo endpoint is called
+        for profile enrichment. Userinfo failure is non-fatal.
+
+        When a ``client_id`` is configured, the token's audience must match it.
+        When ``required_scopes`` are configured, introspection must confirm
+        them; tokens are rejected if scope information is unavailable.
+        """
+        try:
+            async with (
+                contextlib.nullcontext(self._http_client)
+                if self._http_client is not None
+                else httpx.AsyncClient(timeout=self.timeout_seconds)
+            ) as client:
+                # Step 1: Validate token via introspection (RFC 7662).
+                # Security-critical checks (active, audience, scopes) come first.
+                introspect_data_payload: dict = {"token": token}
+                introspect_kwargs: dict = {
+                    "data": introspect_data_payload,
+                    "headers": {"User-Agent": "FastMCP-Clerk-OAuth"},
+                }
+
+                if self._client_id and self._client_secret:
+                    introspect_kwargs["auth"] = (
+                        self._client_id,
+                        self._client_secret,
+                    )
+                elif self._client_id:
+                    introspect_data_payload["client_id"] = self._client_id
+
+                introspect_response = await client.post(
+                    self._introspection_url,
+                    **introspect_kwargs,
+                )
+
+                if introspect_response.status_code != 200:
+                    logger.debug(
+                        "Clerk introspection failed: %d",
+                        introspect_response.status_code,
+                    )
+                    return None
+
+                introspect_data = introspect_response.json()
+
+                # RFC 7662 requires the 'active' field in the response.
+                # A missing field indicates a malformed response — reject.
+                if "active" not in introspect_data or not introspect_data["active"]:
+                    logger.debug(
+                        "Clerk introspection: token inactive or missing 'active' field"
+                    )
+                    return None
+
+                scope_str = introspect_data.get("scope", "")
+                token_scopes = scope_str.split() if scope_str else []
+
+                aud = introspect_data.get("aud") or introspect_data.get("client_id")
+
+                expires_at: int | None = None
+                exp = introspect_data.get("exp")
+                if exp is not None:
+                    with contextlib.suppress(ValueError, TypeError):
+                        expires_at = int(exp)
+
+                if self._client_id and aud != self._client_id:
+                    logger.debug(
+                        "Clerk token audience mismatch: got %s, expected %s",
+                        aud,
+                        self._client_id,
+                    )
+                    return None
+
+                if self.required_scopes:
+                    if not token_scopes:
+                        logger.debug(
+                            "Clerk token missing scope information; "
+                            "cannot verify required scopes %s",
+                            self.required_scopes,
+                        )
+                        return None
+                    token_scopes_set = set(token_scopes)
+                    required_scopes_set = set(self.required_scopes)
+                    if not required_scopes_set.issubset(token_scopes_set):
+                        logger.debug(
+                            "Clerk token missing required scopes. Has %s, needs %s",
+                            token_scopes_set,
+                            required_scopes_set,
+                        )
+                        return None
+
+                # Step 2: Fetch user profile via userinfo.
+                # Enriches the token with profile data (name, email, picture).
+                sub = introspect_data.get("sub")
+                user_data: dict = {}
+                try:
+                    userinfo_response = await client.get(
+                        self._userinfo_url,
+                        headers={
+                            "Authorization": f"Bearer {token}",
+                            "User-Agent": "FastMCP-Clerk-OAuth",
+                        },
+                    )
+                    if userinfo_response.status_code == 200:
+                        user_data = userinfo_response.json()
+                        if not sub:
+                            sub = user_data.get("sub")
+                except Exception as e:
+                    logger.debug("Clerk userinfo call failed: %s", e)
+
+                if not sub:
+                    logger.debug("Clerk token missing 'sub' claim")
+                    return None
+
+                access_token = AccessToken(
+                    token=token,
+                    client_id=aud or sub,
+                    scopes=token_scopes,
+                    expires_at=expires_at,
+                    claims={
+                        "sub": sub,
+                        "aud": aud,
+                        "email": user_data.get("email"),
+                        "email_verified": user_data.get("email_verified"),
+                        "name": user_data.get("name"),
+                        "picture": user_data.get("picture"),
+                        "given_name": user_data.get("given_name"),
+                        "family_name": user_data.get("family_name"),
+                        "preferred_username": user_data.get("preferred_username"),
+                        "iss": user_data.get("iss"),
+                        "clerk_user_data": user_data or None,
+                    },
+                )
+                logger.debug("Clerk token verified successfully for sub=%s", sub)
+                return access_token
+
+        except httpx.RequestError as e:
+            logger.debug("Failed to verify Clerk token: %s", e)
+            return None
+        except Exception as e:
+            logger.debug("Clerk token verification error: %s", e)
+            return None
+
+
+class ClerkProvider(OAuthProxy):
+    """Complete Clerk OAuth provider for FastMCP.
+
+    This provider makes it trivial to add Clerk OAuth protection to any
+    FastMCP server. Provide your Clerk instance domain, OAuth app credentials,
+    and a base URL, and you're ready to go.
+
+    Clerk uses standard OIDC endpoints derived from the instance domain.
+    All endpoint URLs are constructed automatically from the domain parameter.
+
+    Features:
+    - Transparent OAuth proxy to Clerk
+    - Automatic token validation via Clerk's userinfo & introspection APIs
+    - User information extraction from Clerk's OIDC claims
+    - PKCE support (S256)
+    - Minimal configuration required
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth.providers.clerk import ClerkProvider
+
+        auth = ClerkProvider(
+            domain="saving-primate-16.clerk.accounts.dev",
+            client_id="your-clerk-client-id",
+            client_secret="your-clerk-client-secret",
+            base_url="https://my-server.com",
+        )
+
+        mcp = FastMCP("My App", auth=auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        domain: str,
+        client_id: str,
+        client_secret: str | None = None,
+        base_url: AnyHttpUrl | str,
+        resource_base_url: AnyHttpUrl | str | None = None,
+        issuer_url: AnyHttpUrl | str | None = None,
+        redirect_path: str | None = None,
+        required_scopes: list[str] | None = None,
+        valid_scopes: list[str] | None = None,
+        timeout_seconds: int = 10,
+        allowed_client_redirect_uris: list[str] | None = None,
+        client_storage: AsyncKeyValue | None = None,
+        jwt_signing_key: str | bytes | None = None,
+        require_authorization_consent: bool | Literal["remember", "external"] = True,
+        consent_csp_policy: str | None = None,
+        forward_resource: bool = True,
+        fallback_refresh_token_expiry_seconds: int | None = None,
+        fastmcp_access_token_expiry_seconds: int | None = None,
+        token_expiry_threshold_seconds: int = 0,
+        extra_authorize_params: dict[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        enable_cimd: bool = True,
+    ):
+        """Initialize Clerk OAuth provider.
+
+        Args:
+            domain: Clerk instance domain (e.g., "saving-primate-16.clerk.accounts.dev").
+                This is used to derive all OAuth/OIDC endpoint URLs.
+            client_id: Clerk OAuth application client ID
+            client_secret: Clerk OAuth application client secret.
+                Optional for PKCE public clients. When omitted, jwt_signing_key must be provided.
+            base_url: Public URL where OAuth endpoints will be accessible (includes any mount path)
+            resource_base_url: Optional public base URL for the protected resource metadata
+                and token audience. Defaults to ``base_url``.
+            issuer_url: Issuer URL for OAuth metadata (defaults to base_url). Use root-level URL
+                to avoid 404s during discovery when mounting under a path.
+            redirect_path: Redirect path configured in Clerk OAuth app (defaults to "/auth/callback")
+            required_scopes: Required Clerk scopes (defaults to ["openid", "email", "profile"]).
+                Clerk supports: "openid", "email", "profile", "public_metadata",
+                "private_metadata", "offline_access".
+            valid_scopes: All scopes that clients are allowed to request, advertised through
+                well-known endpoints. Defaults to required_scopes if not provided.
+            timeout_seconds: HTTP request timeout for Clerk API calls (defaults to 10)
+            allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
+                If None (default), all URIs are allowed. If empty list, no URIs are allowed.
+            client_storage: Storage backend for OAuth state (client registrations, encrypted tokens).
+                If None, an encrypted file store will be created in the data directory
+                (derived from ``platformdirs``).
+            jwt_signing_key: Secret for signing FastMCP JWT tokens (any string or bytes). If bytes
+                are provided, they will be used as is. If a string is provided, it will be derived
+                into a 32-byte key. If not provided, the upstream client secret will be used to
+                derive a 32-byte key using PBKDF2.
+            require_authorization_consent: Whether to require user consent before authorizing
+                clients (default True). When "external", the built-in consent screen is skipped
+                but no warning is logged, indicating that consent is handled externally by Clerk.
+            consent_csp_policy: Custom CSP policy for the consent page.
+            extra_authorize_params: Additional parameters to forward to Clerk's authorization
+                endpoint. Example: {"prompt": "login"} to force re-authentication.
+            http_client: Optional httpx.AsyncClient for connection pooling in token verification.
+                When provided, the client is reused across verify_token calls and the caller
+                is responsible for its lifecycle. When None (default), a fresh client is created
+                per call.
+            enable_cimd: Enable CIMD (Client ID Metadata Document) support for URL-based
+                client IDs (default True). Set to False to disable.
+            fallback_refresh_token_expiry_seconds: Lifetime for the FastMCP-issued
+                refresh token when the upstream provider omits `refresh_expires_in`
+                (e.g. Cognito, GitHub, many OIDC IdPs). Defaults to 1 year. The upstream
+                refresh remains the source of truth. See `OAuthProxy` for details.
+            fastmcp_access_token_expiry_seconds: Lifetime for the FastMCP-issued access
+                token, decoupling it from the upstream provider's `expires_in`. Defaults
+                to None (mirror the upstream lifetime). Set this for bridges whose
+                upstream issues short-lived access tokens that some MCP clients can't
+                refresh gracefully (e.g. `mcp-remote`). See `OAuthProxy` for details.
+            token_expiry_threshold_seconds: Number of seconds before actual expiry to
+                treat a token as expired, refreshing early to avoid races. Defaults to 0.
+        """
+        domain = domain.rstrip("/")
+
+        required_scopes_final = (
+            parse_scopes(required_scopes)
+            if required_scopes is not None
+            else ["openid", "email", "profile"]
+        )
+
+        parsed_valid_scopes = (
+            parse_scopes(valid_scopes) if valid_scopes is not None else None
+        )
+
+        token_verifier = ClerkTokenVerifier(
+            domain=domain,
+            client_id=client_id,
+            client_secret=client_secret,
+            required_scopes=required_scopes_final,
+            timeout_seconds=timeout_seconds,
+            http_client=http_client,
+        )
+
+        extra_authorize_params_final = (
+            dict(extra_authorize_params) if extra_authorize_params else {}
+        )
+
+        super().__init__(
+            upstream_authorization_endpoint=f"https://{domain}/oauth/authorize",
+            upstream_token_endpoint=f"https://{domain}/oauth/token",
+            upstream_client_id=client_id,
+            upstream_client_secret=client_secret,
+            token_verifier=token_verifier,
+            base_url=base_url,
+            resource_base_url=resource_base_url,
+            redirect_path=redirect_path,
+            issuer_url=issuer_url or base_url,
+            allowed_client_redirect_uris=allowed_client_redirect_uris,
+            client_storage=client_storage,
+            jwt_signing_key=jwt_signing_key,
+            require_authorization_consent=require_authorization_consent,
+            consent_csp_policy=consent_csp_policy,
+            forward_resource=forward_resource,
+            fallback_refresh_token_expiry_seconds=fallback_refresh_token_expiry_seconds,
+            fastmcp_access_token_expiry_seconds=fastmcp_access_token_expiry_seconds,
+            token_expiry_threshold_seconds=token_expiry_threshold_seconds,
+            extra_authorize_params=extra_authorize_params_final or None,
+            valid_scopes=parsed_valid_scopes,
+            enable_cimd=enable_cimd,
+        )
+
+        logger.debug(
+            "Initialized Clerk OAuth provider for domain %s with scopes: %s",
+            domain,
+            required_scopes_final,
+        )
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/debug.py b/fastmcp_slim/fastmcp/server/auth/providers/debug.py
new file mode 100644
index 0000000..5b6de01
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/debug.py
@@ -0,0 +1,114 @@
+"""Debug token verifier for testing and special cases.
+
+This module provides a flexible token verifier that delegates validation
+to a custom callable. Useful for testing, development, or scenarios where
+standard verification isn't possible (like opaque tokens without introspection).
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth.providers.debug import DebugTokenVerifier
+
+    # Accept all tokens (default - useful for testing)
+    auth = DebugTokenVerifier()
+
+    # Custom sync validation logic
+    auth = DebugTokenVerifier(validate=lambda token: token.startswith("valid-"))
+
+    # Custom async validation logic
+    async def check_cache(token: str) -> bool:
+        return await redis.exists(f"token:{token}")
+
+    auth = DebugTokenVerifier(validate=check_cache)
+
+    mcp = FastMCP("My Server", auth=auth)
+    ```
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+
+from fastmcp.server.auth import TokenVerifier
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class DebugTokenVerifier(TokenVerifier):
+    """Token verifier with custom validation logic.
+
+    This verifier delegates token validation to a user-provided callable.
+    By default, it accepts all non-empty tokens (useful for testing).
+
+    Use cases:
+    - Testing: Accept any token without real verification
+    - Development: Custom validation logic for prototyping
+    - Opaque tokens: When you have tokens with no introspection endpoint
+
+    WARNING: This bypasses standard security checks. Only use in controlled
+    environments or when you understand the security implications.
+    """
+
+    def __init__(
+        self,
+        validate: Callable[[str], bool]
+        | Callable[[str], Awaitable[bool]] = lambda token: True,
+        client_id: str = "debug-client",
+        scopes: list[str] | None = None,
+        required_scopes: list[str] | None = None,
+    ):
+        """Initialize the debug token verifier.
+
+        Args:
+            validate: Callable that takes a token string and returns True if valid.
+                Can be sync or async. Default accepts all tokens.
+            client_id: Client ID to assign to validated tokens
+            scopes: Scopes to assign to validated tokens
+            required_scopes: Required scopes (inherited from TokenVerifier base class)
+        """
+        super().__init__(required_scopes=required_scopes)
+        self.validate = validate
+        self.client_id = client_id
+        self.scopes = scopes or []
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify token using custom validation logic.
+
+        Args:
+            token: The token string to validate
+
+        Returns:
+            AccessToken if validation succeeds, None otherwise
+        """
+        # Reject empty tokens
+        if not token or not token.strip():
+            logger.debug("Rejecting empty token")
+            return None
+
+        try:
+            # Call validation function and await if result is awaitable
+            result = self.validate(token)
+            if inspect.isawaitable(result):
+                is_valid = await result
+            else:
+                is_valid = result
+
+            if not is_valid:
+                logger.debug("Token validation failed: callable returned False")
+                return None
+
+            # Return valid AccessToken
+            return AccessToken(
+                token=token,
+                client_id=self.client_id,
+                scopes=self.scopes,
+                expires_at=None,  # No expiration
+                claims={"token": token},  # Store original token in claims
+            )
+
+        except Exception as e:
+            logger.debug("Token validation error: %s", e, exc_info=True)
+            return None
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/descope.py b/fastmcp_slim/fastmcp/server/auth/providers/descope.py
new file mode 100644
index 0000000..3bdccf8
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/descope.py
@@ -0,0 +1,209 @@
+"""Descope authentication provider for FastMCP.
+
+This module provides DescopeProvider - a complete authentication solution that integrates
+with Descope's OAuth 2.1 and OpenID Connect services, supporting Dynamic Client Registration (DCR)
+for seamless MCP client authentication.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+import httpx
+from pydantic import AnyHttpUrl
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from fastmcp.server.auth import RemoteAuthProvider, TokenVerifier
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class DescopeProvider(RemoteAuthProvider):
+    """Descope metadata provider for DCR (Dynamic Client Registration).
+
+    This provider implements Descope integration using metadata forwarding.
+    This is the recommended approach for Descope DCR
+    as it allows Descope to handle the OAuth flow directly while FastMCP acts
+    as a resource server.
+
+    IMPORTANT SETUP REQUIREMENTS:
+
+    1. Create an MCP Server in Descope Console:
+       - Go to the [MCP Servers page](https://app.descope.com/mcp-servers) of the Descope Console
+       - Create a new MCP Server
+       - Ensure that **Dynamic Client Registration (DCR)** is enabled
+       - Note your Well-Known URL
+
+    2. Note your Well-Known URL:
+       - Save your Well-Known URL from [MCP Server Settings](https://app.descope.com/mcp-servers)
+       - Format: ``https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration``
+
+    For detailed setup instructions, see:
+    https://docs.descope.com/identity-federation/inbound-apps/creating-inbound-apps#method-2-dynamic-client-registration-dcr
+
+    Example:
+        ```python
+        from fastmcp.server.auth.providers.descope import DescopeProvider
+
+        # Create Descope metadata provider (JWT verifier created automatically)
+        descope_auth = DescopeProvider(
+            config_url="https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration",
+            base_url="https://your-fastmcp-server.com",
+        )
+
+        # Use with FastMCP
+        mcp = FastMCP("My App", auth=descope_auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: AnyHttpUrl | str,
+        config_url: AnyHttpUrl | str | None = None,
+        project_id: str | None = None,
+        descope_base_url: AnyHttpUrl | str | None = None,
+        required_scopes: list[str] | None = None,
+        scopes_supported: list[str] | None = None,
+        resource_name: str | None = None,
+        resource_documentation: AnyHttpUrl | None = None,
+        token_verifier: TokenVerifier | None = None,
+    ):
+        """Initialize Descope metadata provider.
+
+        Args:
+            base_url: Public URL of this FastMCP server
+            config_url: Your Descope Well-Known URL (e.g., "https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration")
+                This is the new recommended way. If provided, project_id and descope_base_url are ignored.
+            project_id: Your Descope Project ID (e.g., "P2abc123"). Used with descope_base_url for backwards compatibility.
+            descope_base_url: Your Descope base URL (e.g., "https://api.descope.com"). Used with project_id for backwards compatibility.
+            required_scopes: Optional list of scopes that must be present in validated tokens.
+                These scopes will be included in the protected resource metadata.
+            scopes_supported: Optional list of scopes to advertise in OAuth metadata.
+                If None, uses required_scopes. Use this when the scopes clients should
+                request differ from the scopes enforced on tokens.
+            resource_name: Optional name for the protected resource metadata.
+            resource_documentation: Optional documentation URL for the protected resource.
+            token_verifier: Optional token verifier. If None, creates JWT verifier for Descope
+        """
+        self.base_url = AnyHttpUrl(str(base_url).rstrip("/"))
+
+        # Parse scopes if provided as string
+        parsed_scopes = (
+            parse_scopes(required_scopes) if required_scopes is not None else None
+        )
+
+        # Determine which API is being used
+        if config_url is not None:
+            # New API: use config_url
+            # Strip /.well-known/openid-configuration from config_url if present
+            issuer_url = str(config_url)
+            if issuer_url.endswith("/.well-known/openid-configuration"):
+                issuer_url = issuer_url[: -len("/.well-known/openid-configuration")]
+
+            # Parse the issuer URL to extract descope_base_url and project_id for other uses
+            parsed_url = urlparse(issuer_url)
+            path_parts = parsed_url.path.strip("/").split("/")
+
+            # Extract project_id from path (format: /v1/apps/agentic/P.../M...)
+            if "agentic" in path_parts:
+                agentic_index = path_parts.index("agentic")
+                if agentic_index + 1 < len(path_parts):
+                    self.project_id = path_parts[agentic_index + 1]
+                else:
+                    raise ValueError(
+                        f"Could not extract project_id from config_url: {issuer_url}"
+                    )
+            else:
+                raise ValueError(
+                    f"Could not find 'agentic' in config_url path: {issuer_url}"
+                )
+
+            # Extract descope_base_url (scheme + netloc)
+            self.descope_base_url = f"{parsed_url.scheme}://{parsed_url.netloc}".rstrip(
+                "/"
+            )
+        elif project_id is not None and descope_base_url is not None:
+            # Old API: use project_id and descope_base_url
+            self.project_id = project_id
+            descope_base_url_str = str(descope_base_url).rstrip("/")
+            # Ensure descope_base_url has a scheme
+            if not descope_base_url_str.startswith(("http://", "https://")):
+                descope_base_url_str = f"https://{descope_base_url_str}"
+            self.descope_base_url = descope_base_url_str
+            # Old issuer format
+            issuer_url = f"{self.descope_base_url}/v1/apps/{self.project_id}"
+        else:
+            raise ValueError(
+                "Either config_url (new API) or both project_id and descope_base_url (old API) must be provided"
+            )
+
+        # Create default JWT verifier if none provided
+        if token_verifier is None:
+            token_verifier = JWTVerifier(
+                jwks_uri=f"{self.descope_base_url}/{self.project_id}/.well-known/jwks.json",
+                issuer=issuer_url,
+                algorithm="RS256",
+                audience=self.project_id,
+                required_scopes=parsed_scopes,
+            )
+
+        # Initialize RemoteAuthProvider with Descope as the authorization server
+        super().__init__(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl(issuer_url)],
+            base_url=self.base_url,
+            scopes_supported=scopes_supported,
+            resource_name=resource_name,
+            resource_documentation=resource_documentation,
+        )
+
+    def get_routes(
+        self,
+        mcp_path: str | None = None,
+    ) -> list[Route]:
+        """Get OAuth routes including Descope authorization server metadata forwarding.
+
+        This returns the standard protected resource routes plus an authorization server
+        metadata endpoint that forwards Descope's OAuth metadata to clients.
+
+        Args:
+            mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
+                This is used to advertise the resource URL in metadata.
+        """
+        # Get the standard protected resource routes from RemoteAuthProvider
+        routes = super().get_routes(mcp_path)
+
+        async def oauth_authorization_server_metadata(request):
+            """Forward Descope OAuth authorization server metadata with FastMCP customizations."""
+            try:
+                async with httpx.AsyncClient() as client:
+                    response = await client.get(
+                        f"{self.descope_base_url}/v1/apps/{self.project_id}/.well-known/oauth-authorization-server"
+                    )
+                    response.raise_for_status()
+                    metadata = response.json()
+                    return JSONResponse(metadata)
+            except Exception as e:
+                return JSONResponse(
+                    {
+                        "error": "server_error",
+                        "error_description": f"Failed to fetch Descope metadata: {e}",
+                    },
+                    status_code=500,
+                )
+
+        # Add Descope authorization server metadata forwarding
+        routes.append(
+            Route(
+                "/.well-known/oauth-authorization-server",
+                endpoint=oauth_authorization_server_metadata,
+                methods=["GET"],
+            )
+        )
+
+        return routes
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/discord.py b/fastmcp_slim/fastmcp/server/auth/providers/discord.py
new file mode 100644
index 0000000..da13a07
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/discord.py
@@ -0,0 +1,305 @@
+"""Discord OAuth provider for FastMCP.
+
+This module provides a complete Discord OAuth integration that's ready to use
+with just a client ID and client secret. It handles all the complexity of
+Discord's OAuth flow, token validation, and user management.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth.providers.discord import DiscordProvider
+
+    # Simple Discord OAuth protection
+    auth = DiscordProvider(
+        client_id="your-discord-client-id",
+        client_secret="your-discord-client-secret"
+    )
+
+    mcp = FastMCP("My Protected Server", auth=auth)
+    ```
+"""
+
+from __future__ import annotations
+
+import contextlib
+import time
+from datetime import datetime
+from typing import Literal
+
+import httpx
+from key_value.aio.protocols import AsyncKeyValue
+from pydantic import AnyHttpUrl
+
+from fastmcp.server.auth import TokenVerifier
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class DiscordTokenVerifier(TokenVerifier):
+    """Token verifier for Discord OAuth tokens.
+
+    Discord OAuth tokens are opaque (not JWTs), so we verify them
+    by calling Discord's tokeninfo API to check if they're valid and get user info.
+    """
+
+    def __init__(
+        self,
+        *,
+        expected_client_id: str,
+        required_scopes: list[str] | None = None,
+        timeout_seconds: int = 10,
+        http_client: httpx.AsyncClient | None = None,
+    ):
+        """Initialize the Discord token verifier.
+
+        Args:
+            expected_client_id: Expected Discord OAuth client ID for audience binding
+            required_scopes: Required OAuth scopes (e.g., ['email'])
+            timeout_seconds: HTTP request timeout
+            http_client: Optional httpx.AsyncClient for connection pooling. When provided,
+                the client is reused across calls and the caller is responsible for its
+                lifecycle. When None (default), a fresh client is created per call.
+        """
+        super().__init__(required_scopes=required_scopes)
+        self.expected_client_id = expected_client_id
+        self.timeout_seconds = timeout_seconds
+        self._http_client = http_client
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify Discord OAuth token by calling Discord's tokeninfo API."""
+        try:
+            async with (
+                contextlib.nullcontext(self._http_client)
+                if self._http_client is not None
+                else httpx.AsyncClient(timeout=self.timeout_seconds)
+            ) as client:
+                # Use Discord's tokeninfo endpoint to validate the token
+                headers = {
+                    "Authorization": f"Bearer {token}",
+                    "User-Agent": "FastMCP-Discord-OAuth",
+                }
+                response = await client.get(
+                    "https://discord.com/api/oauth2/@me",
+                    headers=headers,
+                )
+
+                if response.status_code != 200:
+                    logger.debug(
+                        "Discord token verification failed: %d",
+                        response.status_code,
+                    )
+                    return None
+
+                token_info = response.json()
+
+                # Check if token is expired (Discord returns ISO timestamp)
+                expires_str = token_info.get("expires")
+                expires_at = None
+                if expires_str:
+                    expires_dt = datetime.fromisoformat(
+                        expires_str.replace("Z", "+00:00")
+                    )
+                    expires_at = int(expires_dt.timestamp())
+                    if expires_at <= int(time.time()):
+                        logger.debug("Discord token has expired")
+                        return None
+
+                token_scopes = token_info.get("scopes", [])
+
+                # Check required scopes
+                if self.required_scopes:
+                    token_scopes_set = set(token_scopes)
+                    required_scopes_set = set(self.required_scopes)
+                    if not required_scopes_set.issubset(token_scopes_set):
+                        logger.debug(
+                            "Discord token missing required scopes. Has %d, needs %d",
+                            len(token_scopes_set),
+                            len(required_scopes_set),
+                        )
+                        return None
+
+                user_data = token_info.get("user", {})
+                application = token_info.get("application") or {}
+                client_id = str(application.get("id", "unknown"))
+                if client_id != self.expected_client_id:
+                    logger.debug(
+                        "Discord token app ID mismatch: expected %s, got %s",
+                        self.expected_client_id,
+                        client_id,
+                    )
+                    return None
+
+                # Create AccessToken with Discord user info
+                access_token = AccessToken(
+                    token=token,
+                    client_id=client_id,
+                    scopes=token_scopes,
+                    expires_at=expires_at,
+                    claims={
+                        "sub": user_data.get("id"),
+                        "username": user_data.get("username"),
+                        "discriminator": user_data.get("discriminator"),
+                        "avatar": user_data.get("avatar"),
+                        "email": user_data.get("email"),
+                        "verified": user_data.get("verified"),
+                        "locale": user_data.get("locale"),
+                        "discord_user": user_data,
+                        "discord_token_info": token_info,
+                    },
+                )
+                logger.debug("Discord token verified successfully")
+                return access_token
+
+        except httpx.RequestError as e:
+            logger.debug("Failed to verify Discord token: %s", e)
+            return None
+        except Exception as e:
+            logger.debug("Discord token verification error: %s", e)
+            return None
+
+
+class DiscordProvider(OAuthProxy):
+    """Complete Discord OAuth provider for FastMCP.
+
+    This provider makes it trivial to add Discord OAuth protection to any
+    FastMCP server. Just provide your Discord OAuth app credentials and
+    a base URL, and you're ready to go.
+
+    Features:
+    - Transparent OAuth proxy to Discord
+    - Automatic token validation via Discord's API
+    - User information extraction from Discord APIs
+    - Minimal configuration required
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth.providers.discord import DiscordProvider
+
+        auth = DiscordProvider(
+            client_id="123456789",
+            client_secret="discord-client-secret-abc123...",
+            base_url="https://my-server.com"
+        )
+
+        mcp = FastMCP("My App", auth=auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        client_id: str,
+        client_secret: str,
+        base_url: AnyHttpUrl | str,
+        resource_base_url: AnyHttpUrl | str | None = None,
+        issuer_url: AnyHttpUrl | str | None = None,
+        redirect_path: str | None = None,
+        required_scopes: list[str] | None = None,
+        timeout_seconds: int = 10,
+        allowed_client_redirect_uris: list[str] | None = None,
+        client_storage: AsyncKeyValue | None = None,
+        jwt_signing_key: str | bytes | None = None,
+        require_authorization_consent: bool | Literal["remember", "external"] = True,
+        consent_csp_policy: str | None = None,
+        forward_resource: bool = True,
+        fallback_refresh_token_expiry_seconds: int | None = None,
+        fastmcp_access_token_expiry_seconds: int | None = None,
+        token_expiry_threshold_seconds: int = 0,
+        http_client: httpx.AsyncClient | None = None,
+        enable_cimd: bool = True,
+    ):
+        """Initialize Discord OAuth provider.
+
+        Args:
+            client_id: Discord OAuth client ID (e.g., "123456789")
+            client_secret: Discord OAuth client secret (e.g., "S....")
+            base_url: Public URL where OAuth endpoints will be accessible (includes any mount path)
+            resource_base_url: Optional public base URL for the protected resource metadata
+                and token audience. Defaults to ``base_url``.
+            issuer_url: Issuer URL for OAuth metadata (defaults to base_url). Use root-level URL
+                to avoid 404s during discovery when mounting under a path.
+            redirect_path: Redirect path configured in Discord OAuth app (defaults to "/auth/callback")
+            required_scopes: Required Discord scopes (defaults to ["identify"]). Common scopes include:
+                - "identify" for profile info (default)
+                - "email" for email access
+                - "guilds" for server membership info
+            timeout_seconds: HTTP request timeout for Discord API calls (defaults to 10)
+            allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
+                If None (default), all URIs are allowed. If empty list, no URIs are allowed.
+            client_storage: Storage backend for OAuth state (client registrations, encrypted tokens).
+                If None, an encrypted file store will be created in the data directory
+                (derived from `platformdirs`).
+            jwt_signing_key: Secret for signing FastMCP JWT tokens (any string or bytes). If bytes are provided,
+                they will be used as is. If a string is provided, it will be derived into a 32-byte key. If not
+                provided, the upstream client secret will be used to derive a 32-byte key using PBKDF2.
+            require_authorization_consent: Whether to require user consent before authorizing clients (default True).
+                When True, users see a consent screen before being redirected to Discord.
+                When False, authorization proceeds directly without user confirmation.
+                When "external", the built-in consent screen is skipped but no warning is
+                logged, indicating that consent is handled externally (e.g. by the upstream IdP).
+                SECURITY WARNING: Only set to False for local development or testing environments.
+            http_client: Optional httpx.AsyncClient for connection pooling in token verification.
+                When provided, the client is reused across verify_token calls and the caller
+                is responsible for its lifecycle. When None (default), a fresh client is created per call.
+            enable_cimd: Enable CIMD (Client ID Metadata Document) support for URL-based
+                client IDs (default True). Set to False to disable.
+            fallback_refresh_token_expiry_seconds: Lifetime for the FastMCP-issued
+                refresh token when the upstream provider omits `refresh_expires_in`
+                (e.g. Cognito, GitHub, many OIDC IdPs). Defaults to 1 year. The upstream
+                refresh remains the source of truth. See `OAuthProxy` for details.
+            fastmcp_access_token_expiry_seconds: Lifetime for the FastMCP-issued access
+                token, decoupling it from the upstream provider's `expires_in`. Defaults
+                to None (mirror the upstream lifetime). Set this for bridges whose
+                upstream issues short-lived access tokens that some MCP clients can't
+                refresh gracefully (e.g. `mcp-remote`). See `OAuthProxy` for details.
+            token_expiry_threshold_seconds: Number of seconds before actual expiry to
+                treat a token as expired, refreshing early to avoid races. Defaults to 0.
+        """
+        # Parse scopes if provided as string
+        required_scopes_final = (
+            parse_scopes(required_scopes)
+            if required_scopes is not None
+            else ["identify"]
+        )
+
+        # Create Discord token verifier
+        token_verifier = DiscordTokenVerifier(
+            expected_client_id=client_id,
+            required_scopes=required_scopes_final,
+            timeout_seconds=timeout_seconds,
+            http_client=http_client,
+        )
+
+        # Initialize OAuth proxy with Discord endpoints
+        super().__init__(
+            upstream_authorization_endpoint="https://discord.com/oauth2/authorize",
+            upstream_token_endpoint="https://discord.com/api/oauth2/token",
+            upstream_client_id=client_id,
+            upstream_client_secret=client_secret,
+            token_verifier=token_verifier,
+            base_url=base_url,
+            resource_base_url=resource_base_url,
+            redirect_path=redirect_path,
+            issuer_url=issuer_url or base_url,  # Default to base_url if not specified
+            allowed_client_redirect_uris=allowed_client_redirect_uris,
+            client_storage=client_storage,
+            jwt_signing_key=jwt_signing_key,
+            require_authorization_consent=require_authorization_consent,
+            consent_csp_policy=consent_csp_policy,
+            forward_resource=forward_resource,
+            fallback_refresh_token_expiry_seconds=fallback_refresh_token_expiry_seconds,
+            fastmcp_access_token_expiry_seconds=fastmcp_access_token_expiry_seconds,
+            token_expiry_threshold_seconds=token_expiry_threshold_seconds,
+            enable_cimd=enable_cimd,
+        )
+
+        logger.debug(
+            "Initialized Discord OAuth provider for client %s with scopes: %s",
+            client_id,
+            required_scopes_final,
+        )
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/github.py b/fastmcp_slim/fastmcp/server/auth/providers/github.py
new file mode 100644
index 0000000..d14aeb0
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/github.py
@@ -0,0 +1,320 @@
+"""GitHub OAuth provider for FastMCP.
+
+This module provides a complete GitHub OAuth integration that's ready to use
+with just a client ID and client secret. It handles all the complexity of
+GitHub's OAuth flow, token validation, and user management.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth.providers.github import GitHubProvider
+
+    # Simple GitHub OAuth protection
+    auth = GitHubProvider(
+        client_id="your-github-client-id",
+        client_secret="your-github-client-secret"
+    )
+
+    mcp = FastMCP("My Protected Server", auth=auth)
+    ```
+"""
+
+from __future__ import annotations
+
+import contextlib
+from typing import Literal
+
+import httpx
+from key_value.aio.protocols import AsyncKeyValue
+from pydantic import AnyHttpUrl
+
+from fastmcp.server.auth import TokenVerifier
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.token_cache import TokenCache
+
+logger = get_logger(__name__)
+
+
+class GitHubTokenVerifier(TokenVerifier):
+    """Token verifier for GitHub OAuth tokens.
+
+    GitHub OAuth tokens are opaque (not JWTs), so we verify them
+    by calling GitHub's API to check if they're valid and get user info.
+
+    Caching is disabled by default.  Set ``cache_ttl_seconds`` to a positive
+    integer to cache successful verification results and avoid repeated
+    GitHub API calls for the same token.
+    """
+
+    def __init__(
+        self,
+        *,
+        required_scopes: list[str] | None = None,
+        timeout_seconds: int = 10,
+        cache_ttl_seconds: int | None = None,
+        max_cache_size: int | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ):
+        """Initialize the GitHub token verifier.
+
+        Args:
+            required_scopes: Required OAuth scopes (e.g., ['user:email'])
+            timeout_seconds: HTTP request timeout
+            cache_ttl_seconds: How long to cache verification results in seconds.
+                Caching is disabled by default (None).  Set to a positive integer
+                to enable (e.g., 300 for 5 minutes).
+            max_cache_size: Maximum number of tokens to cache.  Default: 10 000.
+            http_client: Optional httpx.AsyncClient for connection pooling. When provided,
+                the client is reused across calls and the caller is responsible for its
+                lifecycle. When None (default), a fresh client is created per call.
+        """
+        super().__init__(required_scopes=required_scopes)
+        self.timeout_seconds = timeout_seconds
+        self._http_client = http_client
+        self._cache = TokenCache(
+            ttl_seconds=cache_ttl_seconds,
+            max_size=max_cache_size,
+        )
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify GitHub OAuth token by calling GitHub API."""
+        is_cached, cached_result = self._cache.get(token)
+        if is_cached:
+            logger.debug("GitHub token cache hit")
+            return cached_result
+
+        try:
+            async with (
+                contextlib.nullcontext(self._http_client)
+                if self._http_client is not None
+                else httpx.AsyncClient(timeout=self.timeout_seconds)
+            ) as client:
+                # Get token info from GitHub API
+                response = await client.get(
+                    "https://api.github.com/user",
+                    headers={
+                        "Authorization": f"Bearer {token}",
+                        "Accept": "application/vnd.github.v3+json",
+                        "User-Agent": "FastMCP-GitHub-OAuth",
+                    },
+                )
+
+                if response.status_code != 200:
+                    logger.debug(
+                        "GitHub token verification failed: %d - %s",
+                        response.status_code,
+                        response.text[:200],
+                    )
+                    return None
+
+                user_data = response.json()
+
+                # Get token scopes from GitHub API
+                # GitHub includes scopes in the X-OAuth-Scopes header
+                scopes_response = await client.get(
+                    "https://api.github.com/user/repos",  # Any authenticated endpoint
+                    headers={
+                        "Authorization": f"Bearer {token}",
+                        "Accept": "application/vnd.github.v3+json",
+                        "User-Agent": "FastMCP-GitHub-OAuth",
+                    },
+                )
+
+                # Extract scopes from X-OAuth-Scopes header if available
+                scopes_verified = scopes_response.status_code == 200
+                oauth_scopes_header = scopes_response.headers.get("x-oauth-scopes", "")
+                token_scopes = [
+                    scope.strip()
+                    for scope in oauth_scopes_header.split(",")
+                    if scope.strip()
+                ]
+
+                # If no scopes in header, assume basic scopes based on successful user API call
+                if not token_scopes:
+                    token_scopes = ["user"]  # Basic scope if we can access user info
+
+                # Check required scopes
+                if self.required_scopes:
+                    token_scopes_set = set(token_scopes)
+                    required_scopes_set = set(self.required_scopes)
+                    if not required_scopes_set.issubset(token_scopes_set):
+                        logger.debug(
+                            "GitHub token missing required scopes. Has %d, needs %d",
+                            len(token_scopes_set),
+                            len(required_scopes_set),
+                        )
+                        return None
+
+                # Create AccessToken with GitHub user info
+                result = AccessToken(
+                    token=token,
+                    client_id=str(user_data.get("id", "unknown")),  # Use GitHub user ID
+                    scopes=token_scopes,
+                    expires_at=None,  # GitHub tokens don't typically expire
+                    claims={
+                        "sub": str(user_data["id"]),
+                        "login": user_data.get("login"),
+                        "name": user_data.get("name"),
+                        "email": user_data.get("email"),
+                        "avatar_url": user_data.get("avatar_url"),
+                        "github_user_data": user_data,
+                    },
+                )
+                if scopes_verified:
+                    self._cache.set(token, result)
+                return result
+
+        except httpx.RequestError as e:
+            logger.debug("Failed to verify GitHub token: %s", e)
+            return None
+        except Exception as e:
+            logger.debug("GitHub token verification error: %s", e)
+            return None
+
+
+class GitHubProvider(OAuthProxy):
+    """Complete GitHub OAuth provider for FastMCP.
+
+    This provider makes it trivial to add GitHub OAuth protection to any
+    FastMCP server. Just provide your GitHub OAuth app credentials and
+    a base URL, and you're ready to go.
+
+    Features:
+    - Transparent OAuth proxy to GitHub
+    - Automatic token validation via GitHub API
+    - User information extraction
+    - Minimal configuration required
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth.providers.github import GitHubProvider
+
+        auth = GitHubProvider(
+            client_id="Ov23li...",
+            client_secret="abc123...",
+            base_url="https://my-server.com"
+        )
+
+        mcp = FastMCP("My App", auth=auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        client_id: str,
+        client_secret: str,
+        base_url: AnyHttpUrl | str,
+        resource_base_url: AnyHttpUrl | str | None = None,
+        issuer_url: AnyHttpUrl | str | None = None,
+        redirect_path: str | None = None,
+        required_scopes: list[str] | None = None,
+        timeout_seconds: int = 10,
+        cache_ttl_seconds: int | None = None,
+        max_cache_size: int | None = None,
+        allowed_client_redirect_uris: list[str] | None = None,
+        client_storage: AsyncKeyValue | None = None,
+        jwt_signing_key: str | bytes | None = None,
+        require_authorization_consent: bool | Literal["remember", "external"] = True,
+        consent_csp_policy: str | None = None,
+        forward_resource: bool = True,
+        fallback_refresh_token_expiry_seconds: int | None = None,
+        fastmcp_access_token_expiry_seconds: int | None = None,
+        token_expiry_threshold_seconds: int = 0,
+        http_client: httpx.AsyncClient | None = None,
+        enable_cimd: bool = True,
+    ):
+        """Initialize GitHub OAuth provider.
+
+        Args:
+            client_id: GitHub OAuth app client ID (e.g., "Ov23li...")
+            client_secret: GitHub OAuth app client secret
+            base_url: Public URL where OAuth endpoints will be accessible (includes any mount path)
+            resource_base_url: Optional public base URL for the protected resource metadata
+                and token audience. Defaults to ``base_url``.
+            issuer_url: Issuer URL for OAuth metadata (defaults to base_url). Use root-level URL
+                to avoid 404s during discovery when mounting under a path.
+            redirect_path: Redirect path configured in GitHub OAuth app (defaults to "/auth/callback")
+            required_scopes: Required GitHub scopes (defaults to ["user"])
+            timeout_seconds: HTTP request timeout for GitHub API calls (defaults to 10)
+            cache_ttl_seconds: How long to cache token verification results in seconds.
+                Caching is disabled by default (None).  Set to a positive integer to
+                enable (e.g., 300 for 5 minutes).
+            max_cache_size: Maximum number of tokens to cache.  Default: 10 000.
+            allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
+                If None (default), all URIs are allowed. If empty list, no URIs are allowed.
+            client_storage: Storage backend for OAuth state (client registrations, encrypted tokens).
+                If None, an encrypted file store will be created in the data directory
+                (derived from `platformdirs`).
+            jwt_signing_key: Secret for signing FastMCP JWT tokens (any string or bytes). If bytes are provided,
+                they will be used as is. If a string is provided, it will be derived into a 32-byte key. If not
+                provided, the upstream client secret will be used to derive a 32-byte key using PBKDF2.
+            require_authorization_consent: Whether to require user consent before authorizing clients (default True).
+                When True, users see a consent screen before being redirected to GitHub.
+                When False, authorization proceeds directly without user confirmation.
+                When "external", the built-in consent screen is skipped but no warning is
+                logged, indicating that consent is handled externally (e.g. by the upstream IdP).
+                SECURITY WARNING: Only set to False for local development or testing environments.
+            http_client: Optional httpx.AsyncClient for connection pooling in token verification.
+                When provided, the client is reused across verify_token calls and the caller
+                is responsible for its lifecycle. When None (default), a fresh client is created per call.
+            enable_cimd: Enable CIMD (Client ID Metadata Document) support for URL-based
+                client IDs (default True). Set to False to disable.
+            fallback_refresh_token_expiry_seconds: Lifetime for the FastMCP-issued
+                refresh token when the upstream provider omits `refresh_expires_in`
+                (e.g. Cognito, GitHub, many OIDC IdPs). Defaults to 1 year. The upstream
+                refresh remains the source of truth. See `OAuthProxy` for details.
+            fastmcp_access_token_expiry_seconds: Lifetime for the FastMCP-issued access
+                token, decoupling it from the upstream provider's `expires_in`. Defaults
+                to None (mirror the upstream lifetime). Set this for bridges whose
+                upstream issues short-lived access tokens that some MCP clients can't
+                refresh gracefully (e.g. `mcp-remote`). See `OAuthProxy` for details.
+            token_expiry_threshold_seconds: Number of seconds before actual expiry to
+                treat a token as expired, refreshing early to avoid races. Defaults to 0.
+        """
+        # Parse scopes if provided as string
+        required_scopes_final = (
+            parse_scopes(required_scopes) if required_scopes is not None else ["user"]
+        )
+
+        # Create GitHub token verifier
+        token_verifier = GitHubTokenVerifier(
+            required_scopes=required_scopes_final,
+            timeout_seconds=timeout_seconds,
+            cache_ttl_seconds=cache_ttl_seconds,
+            max_cache_size=max_cache_size,
+            http_client=http_client,
+        )
+
+        # Initialize OAuth proxy with GitHub endpoints
+        super().__init__(
+            upstream_authorization_endpoint="https://github.com/login/oauth/authorize",
+            upstream_token_endpoint="https://github.com/login/oauth/access_token",
+            upstream_client_id=client_id,
+            upstream_client_secret=client_secret,
+            token_verifier=token_verifier,
+            base_url=base_url,
+            resource_base_url=resource_base_url,
+            redirect_path=redirect_path,
+            issuer_url=issuer_url or base_url,  # Default to base_url if not specified
+            allowed_client_redirect_uris=allowed_client_redirect_uris,
+            client_storage=client_storage,
+            jwt_signing_key=jwt_signing_key,
+            require_authorization_consent=require_authorization_consent,
+            consent_csp_policy=consent_csp_policy,
+            forward_resource=forward_resource,
+            fallback_refresh_token_expiry_seconds=fallback_refresh_token_expiry_seconds,
+            fastmcp_access_token_expiry_seconds=fastmcp_access_token_expiry_seconds,
+            token_expiry_threshold_seconds=token_expiry_threshold_seconds,
+            enable_cimd=enable_cimd,
+        )
+
+        logger.debug(
+            "Initialized GitHub OAuth provider for client %s with scopes: %s",
+            client_id,
+            required_scopes_final,
+        )
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/google.py b/fastmcp_slim/fastmcp/server/auth/providers/google.py
new file mode 100644
index 0000000..07f7570
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/google.py
@@ -0,0 +1,382 @@
+"""Google OAuth provider for FastMCP.
+
+This module provides a complete Google OAuth integration that's ready to use
+with just a client ID and client secret. It handles all the complexity of
+Google's OAuth flow, token validation, and user management.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth.providers.google import GoogleProvider
+
+    # Simple Google OAuth protection
+    auth = GoogleProvider(
+        client_id="your-google-client-id.apps.googleusercontent.com",
+        client_secret="your-google-client-secret"
+    )
+
+    mcp = FastMCP("My Protected Server", auth=auth)
+    ```
+"""
+
+from __future__ import annotations
+
+import contextlib
+import time
+from typing import Literal
+
+import httpx
+from key_value.aio.protocols import AsyncKeyValue
+from pydantic import AnyHttpUrl
+
+from fastmcp.server.auth import TokenVerifier
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+GOOGLE_SCOPE_ALIASES: dict[str, str] = {
+    "email": "https://www.googleapis.com/auth/userinfo.email",
+    "profile": "https://www.googleapis.com/auth/userinfo.profile",
+}
+
+
+def _normalize_google_scope(scope: str) -> str:
+    """Normalize a Google scope shorthand to its canonical full URI.
+
+    Google accepts shorthand scopes like "email" and "profile" in authorization
+    requests, but returns the full URI form in token responses. This normalizes
+    to the full URI so comparisons work regardless of which form was used.
+    """
+    return GOOGLE_SCOPE_ALIASES.get(scope, scope)
+
+
+class GoogleTokenVerifier(TokenVerifier):
+    """Token verifier for Google OAuth tokens.
+
+    Google OAuth tokens are opaque (not JWTs), so we verify them by calling
+    Google's tokeninfo endpoint with the access token as a query parameter.
+    This returns the OAuth app ID (``aud``), granted scopes, and expiry time.
+    User profile data (name, picture, etc.) is fetched separately from the
+    v2 userinfo endpoint when the token is valid.
+    """
+
+    def __init__(
+        self,
+        *,
+        required_scopes: list[str] | None = None,
+        timeout_seconds: int = 10,
+        http_client: httpx.AsyncClient | None = None,
+    ):
+        """Initialize the Google token verifier.
+
+        Args:
+            required_scopes: Required OAuth scopes (e.g., ['openid', 'https://www.googleapis.com/auth/userinfo.email'])
+            timeout_seconds: HTTP request timeout
+            http_client: Optional httpx.AsyncClient for connection pooling. When provided,
+                the client is reused across calls and the caller is responsible for its
+                lifecycle. When None (default), a fresh client is created per call.
+        """
+        normalized = (
+            [_normalize_google_scope(s) for s in required_scopes]
+            if required_scopes
+            else required_scopes
+        )
+        super().__init__(required_scopes=normalized)
+        self.timeout_seconds = timeout_seconds
+        self._http_client = http_client
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify a Google OAuth token using the tokeninfo endpoint.
+
+        Calls ``https://oauth2.googleapis.com/tokeninfo?access_token=TOKEN``
+        to validate the token and retrieve the OAuth app ID (``aud``), granted
+        scopes, and expiry time.  On success, fetches user profile data from
+        the v2 userinfo endpoint to populate name, picture, and locale claims.
+        """
+        try:
+            async with (
+                contextlib.nullcontext(self._http_client)
+                if self._http_client is not None
+                else httpx.AsyncClient(timeout=self.timeout_seconds)
+            ) as client:
+                # Step 1: Verify token via tokeninfo endpoint.
+                # Returns aud (OAuth app ID), scope (space-separated), expires_in, sub, email.
+                response = await client.get(
+                    "https://oauth2.googleapis.com/tokeninfo",
+                    params={"access_token": token},
+                    headers={"User-Agent": "FastMCP-Google-OAuth"},
+                )
+
+                if response.status_code != 200:
+                    logger.debug(
+                        "Google token verification failed: %d",
+                        response.status_code,
+                    )
+                    return None
+
+                token_data = response.json()
+
+                # aud is the OAuth app ID (client_id / audience)
+                aud = token_data.get("aud")
+                if not aud:
+                    logger.debug("Google tokeninfo missing 'aud' claim")
+                    return None
+
+                # sub is required (unique Google user ID)
+                sub = token_data.get("sub")
+                if not sub:
+                    logger.debug("Google tokeninfo missing 'sub' claim")
+                    return None
+
+                # Parse scopes directly from the tokeninfo response (space-separated)
+                scope_str = token_data.get("scope", "")
+                token_scopes = scope_str.split() if scope_str else []
+
+                # Check required scopes
+                if self.required_scopes:
+                    token_scopes_set = set(token_scopes)
+                    required_scopes_set = set(self.required_scopes)
+                    if not required_scopes_set.issubset(token_scopes_set):
+                        logger.debug(
+                            "Google token missing required scopes. Has %d, needs %d",
+                            len(token_scopes_set),
+                            len(required_scopes_set),
+                        )
+                        return None
+
+                # Compute expiry from expires_in (seconds until expiry)
+                expires_at: int | None = None
+                expires_in = token_data.get("expires_in")
+                if expires_in is not None:
+                    with contextlib.suppress(ValueError, TypeError):
+                        expires_at = int(time.time()) + int(expires_in)
+
+                # Step 2: Fetch user profile from v2 userinfo endpoint.
+                # tokeninfo provides auth data; userinfo provides name, picture, locale.
+                user_data: dict = {}
+                try:
+                    userinfo_response = await client.get(
+                        "https://www.googleapis.com/oauth2/v2/userinfo",
+                        headers={
+                            "Authorization": f"Bearer {token}",
+                            "User-Agent": "FastMCP-Google-OAuth",
+                        },
+                    )
+                    if userinfo_response.status_code == 200:
+                        user_data = userinfo_response.json()
+                except Exception as e:
+                    logger.debug("Failed to fetch Google user profile: %s", e)
+
+                access_token = AccessToken(
+                    token=token,
+                    client_id=sub,
+                    scopes=token_scopes,
+                    expires_at=expires_at,
+                    claims={
+                        "sub": sub,
+                        "aud": aud,
+                        "email": token_data.get("email") or user_data.get("email"),
+                        "email_verified": token_data.get("email_verified")
+                        or user_data.get("verified_email"),
+                        "name": user_data.get("name"),
+                        "picture": user_data.get("picture"),
+                        "given_name": user_data.get("given_name"),
+                        "family_name": user_data.get("family_name"),
+                        "locale": user_data.get("locale"),
+                        "google_user_data": user_data or None,
+                    },
+                )
+                logger.debug("Google token verified successfully")
+                return access_token
+
+        except httpx.RequestError as e:
+            logger.debug("Failed to verify Google token: %s", e)
+            return None
+        except Exception as e:
+            logger.debug("Google token verification error: %s", e)
+            return None
+
+
+class GoogleProvider(OAuthProxy):
+    """Complete Google OAuth provider for FastMCP.
+
+    This provider makes it trivial to add Google OAuth protection to any
+    FastMCP server. Just provide your Google OAuth app credentials and
+    a base URL, and you're ready to go.
+
+    Features:
+    - Transparent OAuth proxy to Google
+    - Automatic token validation via Google's tokeninfo API
+    - User information extraction from Google APIs
+    - Minimal configuration required
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth.providers.google import GoogleProvider
+
+        auth = GoogleProvider(
+            client_id="123456789.apps.googleusercontent.com",
+            client_secret="GOCSPX-abc123...",
+            base_url="https://my-server.com"
+        )
+
+        mcp = FastMCP("My App", auth=auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        client_id: str,
+        client_secret: str | None = None,
+        base_url: AnyHttpUrl | str,
+        resource_base_url: AnyHttpUrl | str | None = None,
+        issuer_url: AnyHttpUrl | str | None = None,
+        redirect_path: str | None = None,
+        required_scopes: list[str] | None = None,
+        valid_scopes: list[str] | None = None,
+        timeout_seconds: int = 10,
+        allowed_client_redirect_uris: list[str] | None = None,
+        client_storage: AsyncKeyValue | None = None,
+        jwt_signing_key: str | bytes | None = None,
+        require_authorization_consent: bool | Literal["remember", "external"] = True,
+        consent_csp_policy: str | None = None,
+        forward_resource: bool = True,
+        fallback_refresh_token_expiry_seconds: int | None = None,
+        fastmcp_access_token_expiry_seconds: int | None = None,
+        token_expiry_threshold_seconds: int = 0,
+        extra_authorize_params: dict[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        enable_cimd: bool = True,
+    ):
+        """Initialize Google OAuth provider.
+
+        Args:
+            client_id: Google OAuth client ID (e.g., "123456789.apps.googleusercontent.com")
+            client_secret: Google OAuth client secret (e.g., "GOCSPX-abc123...").
+                Optional for PKCE public clients (e.g., native apps). When omitted,
+                jwt_signing_key must be provided.
+            base_url: Public URL where OAuth endpoints will be accessible (includes any mount path)
+            resource_base_url: Optional public base URL for the protected resource metadata
+                and token audience. Defaults to ``base_url``.
+            issuer_url: Issuer URL for OAuth metadata (defaults to base_url). Use root-level URL
+                to avoid 404s during discovery when mounting under a path.
+            redirect_path: Redirect path configured in Google OAuth app (defaults to "/auth/callback")
+            required_scopes: Required Google scopes (defaults to ["openid"]). Common scopes include:
+                - "openid" for OpenID Connect (default)
+                - "https://www.googleapis.com/auth/userinfo.email" for email access
+                - "https://www.googleapis.com/auth/userinfo.profile" for profile info
+                Google scope shorthands like "email" and "profile" are automatically
+                normalized to their full URI forms for token verification.
+            valid_scopes: All scopes that clients are allowed to request, advertised through
+                well-known endpoints. Defaults to required_scopes if not provided. Use this
+                when you want clients to be able to request additional scopes beyond the
+                required minimum. Shorthands are normalized to full URI forms.
+            timeout_seconds: HTTP request timeout for Google API calls (defaults to 10)
+            allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
+                If None (default), all URIs are allowed. If empty list, no URIs are allowed.
+            client_storage: Storage backend for OAuth state (client registrations, encrypted tokens).
+                If None, an encrypted file store will be created in the data directory
+                (derived from `platformdirs`).
+            jwt_signing_key: Secret for signing FastMCP JWT tokens (any string or bytes). If bytes are provided,
+                they will be used as is. If a string is provided, it will be derived into a 32-byte key. If not
+                provided, the upstream client secret will be used to derive a 32-byte key using PBKDF2.
+            require_authorization_consent: Whether to require user consent before authorizing clients (default True).
+                When True, users see a consent screen before being redirected to Google.
+                When False, authorization proceeds directly without user confirmation.
+                When "external", the built-in consent screen is skipped but no warning is
+                logged, indicating that consent is handled externally (e.g. by Google's own consent).
+                SECURITY WARNING: Only set to False for local development or testing environments.
+            extra_authorize_params: Additional parameters to forward to Google's authorization endpoint.
+                By default, GoogleProvider sets {"access_type": "offline", "prompt": "consent"} to ensure
+                refresh tokens are returned. You can override these defaults or add additional parameters.
+                Example: {"prompt": "select_account"} to let users choose their Google account.
+            http_client: Optional httpx.AsyncClient for connection pooling in token verification.
+                When provided, the client is reused across verify_token calls and the caller
+                is responsible for its lifecycle. When None (default), a fresh client is created per call.
+            enable_cimd: Enable CIMD (Client ID Metadata Document) support for URL-based
+                client IDs (default True). Set to False to disable.
+            fallback_refresh_token_expiry_seconds: Lifetime for the FastMCP-issued
+                refresh token when the upstream provider omits `refresh_expires_in`
+                (e.g. Cognito, GitHub, many OIDC IdPs). Defaults to 1 year. The upstream
+                refresh remains the source of truth. See `OAuthProxy` for details.
+            fastmcp_access_token_expiry_seconds: Lifetime for the FastMCP-issued access
+                token, decoupling it from the upstream provider's `expires_in`. Defaults
+                to None (mirror the upstream lifetime). Set this for bridges whose
+                upstream issues short-lived access tokens that some MCP clients can't
+                refresh gracefully (e.g. `mcp-remote`). See `OAuthProxy` for details.
+            token_expiry_threshold_seconds: Number of seconds before actual expiry to
+                treat a token as expired, refreshing early to avoid races. Defaults to 0.
+        """
+        # Parse scopes if provided as string
+        # Google requires at least one scope - openid is the minimal OIDC scope
+        required_scopes_final = (
+            parse_scopes(required_scopes) if required_scopes is not None else ["openid"]
+        )
+
+        # Normalize valid_scopes if provided
+        parsed_valid_scopes = (
+            parse_scopes(valid_scopes) if valid_scopes is not None else None
+        )
+        valid_scopes_final = (
+            [_normalize_google_scope(s) for s in parsed_valid_scopes]
+            if parsed_valid_scopes is not None
+            else None
+        )
+
+        # Create Google token verifier
+        # Normalization of shorthand scopes (e.g. "email" -> full URI) happens
+        # inside GoogleTokenVerifier so required_scopes match what Google returns.
+        token_verifier = GoogleTokenVerifier(
+            required_scopes=required_scopes_final,
+            timeout_seconds=timeout_seconds,
+            http_client=http_client,
+        )
+
+        # Set Google-specific defaults for extra authorize params
+        # access_type=offline ensures refresh tokens are returned
+        # prompt=consent forces consent screen to get refresh token (Google only issues on first auth otherwise)
+        google_defaults = {
+            "access_type": "offline",
+            "prompt": "consent",
+        }
+        # User-provided params override defaults
+        if extra_authorize_params:
+            google_defaults.update(extra_authorize_params)
+        extra_authorize_params_final = google_defaults
+
+        # Initialize OAuth proxy with Google endpoints
+        super().__init__(
+            upstream_authorization_endpoint="https://accounts.google.com/o/oauth2/v2/auth",
+            upstream_token_endpoint="https://oauth2.googleapis.com/token",
+            upstream_client_id=client_id,
+            upstream_client_secret=client_secret,
+            token_verifier=token_verifier,
+            base_url=base_url,
+            resource_base_url=resource_base_url,
+            redirect_path=redirect_path,
+            issuer_url=issuer_url or base_url,  # Default to base_url if not specified
+            allowed_client_redirect_uris=allowed_client_redirect_uris,
+            client_storage=client_storage,
+            jwt_signing_key=jwt_signing_key,
+            require_authorization_consent=require_authorization_consent,
+            consent_csp_policy=consent_csp_policy,
+            forward_resource=forward_resource,
+            fallback_refresh_token_expiry_seconds=fallback_refresh_token_expiry_seconds,
+            fastmcp_access_token_expiry_seconds=fastmcp_access_token_expiry_seconds,
+            token_expiry_threshold_seconds=token_expiry_threshold_seconds,
+            extra_authorize_params=extra_authorize_params_final,
+            valid_scopes=valid_scopes_final,
+            enable_cimd=enable_cimd,
+        )
+
+        logger.debug(
+            "Initialized Google OAuth provider for client %s with scopes: %s",
+            client_id,
+            required_scopes_final,
+        )
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/huggingface.py b/fastmcp_slim/fastmcp/server/auth/providers/huggingface.py
new file mode 100644
index 0000000..b3ca363
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/huggingface.py
@@ -0,0 +1,280 @@
+"""Hugging Face OAuth provider for FastMCP."""
+
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Mapping
+from json import JSONDecodeError
+from typing import Any, Literal
+
+import httpx
+from key_value.aio.protocols import AsyncKeyValue
+from pydantic import AnyHttpUrl
+
+from fastmcp.server.auth import TokenVerifier
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+HUGGINGFACE_AUTHORIZATION_ENDPOINT = "https://huggingface.co/oauth/authorize"
+HUGGINGFACE_TOKEN_ENDPOINT = "https://huggingface.co/oauth/token"
+HUGGINGFACE_USERINFO_ENDPOINT = "https://huggingface.co/oauth/userinfo"
+HUGGINGFACE_WHOAMI_ENDPOINT = "https://huggingface.co/api/whoami-v2"
+
+DEFAULT_HUGGINGFACE_SCOPES = ["openid", "profile"]
+
+
+def _extract_scopes(data: Mapping[str, Any]) -> list[str]:
+    scope_value = data.get("scope") or data.get("scopes")
+    if isinstance(scope_value, str):
+        return parse_scopes(scope_value) or []
+    if isinstance(scope_value, list):
+        return [str(scope).strip() for scope in scope_value if str(scope).strip()]
+
+    auth = data.get("auth")
+    if not isinstance(auth, Mapping):
+        return []
+    access_token = auth.get("accessToken")
+    if not isinstance(access_token, Mapping):
+        return []
+
+    nested_scopes = access_token.get("scopes") or access_token.get("scope")
+    if isinstance(nested_scopes, str):
+        return parse_scopes(nested_scopes) or []
+    if isinstance(nested_scopes, list):
+        return [
+            str(scope.get("name") if isinstance(scope, Mapping) else scope).strip()
+            for scope in nested_scopes
+            if str(scope.get("name") if isinstance(scope, Mapping) else scope).strip()
+        ]
+    return []
+
+
+class HuggingFaceTokenVerifier(TokenVerifier):
+    """Token verifier for Hugging Face OAuth access tokens.
+
+    Hugging Face OAuth access tokens are opaque, so validation is performed by
+    calling Hugging Face's userinfo endpoint.
+    """
+
+    def __init__(
+        self,
+        *,
+        required_scopes: list[str] | None = None,
+        timeout_seconds: int = 10,
+        http_client: httpx.AsyncClient | None = None,
+    ):
+        super().__init__(required_scopes=required_scopes)
+        self.timeout_seconds = timeout_seconds
+        self._http_client = http_client
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify a Hugging Face OAuth token using the userinfo endpoint."""
+        try:
+            async with (
+                contextlib.nullcontext(self._http_client)
+                if self._http_client is not None
+                else httpx.AsyncClient(timeout=self.timeout_seconds)
+            ) as client:
+                userinfo_response = await client.get(
+                    HUGGINGFACE_USERINFO_ENDPOINT,
+                    headers={
+                        "Authorization": f"Bearer {token}",
+                        "User-Agent": "FastMCP-HuggingFace-OAuth",
+                    },
+                )
+                if userinfo_response.status_code != 200:
+                    logger.debug(
+                        "Hugging Face token verification failed: %d",
+                        userinfo_response.status_code,
+                    )
+                    return None
+
+                userinfo = userinfo_response.json()
+                sub = userinfo.get("sub")
+                if not sub:
+                    logger.debug("Hugging Face userinfo missing 'sub' claim")
+                    return None
+
+                token_scopes = _extract_scopes(userinfo)
+                whoami: dict[str, Any] | None = None
+                if not token_scopes or (
+                    self.required_scopes
+                    and not set(self.required_scopes).issubset(set(token_scopes))
+                ):
+                    whoami = await self._fetch_whoami(client, token)
+                    if whoami:
+                        token_scopes = list(
+                            dict.fromkeys([*token_scopes, *_extract_scopes(whoami)])
+                        )
+
+                if not token_scopes:
+                    token_scopes = list(DEFAULT_HUGGINGFACE_SCOPES)
+
+                if self.required_scopes and not set(self.required_scopes).issubset(
+                    set(token_scopes)
+                ):
+                    logger.debug(
+                        "Hugging Face token missing required scopes. Has %d, needs %d",
+                        len(token_scopes),
+                        len(self.required_scopes),
+                    )
+                    return None
+
+                username = (
+                    userinfo.get("preferred_username")
+                    or userinfo.get("nickname")
+                    or userinfo.get("name")
+                )
+                return AccessToken(
+                    token=token,
+                    client_id=str(sub),
+                    scopes=token_scopes,
+                    expires_at=None,
+                    claims={
+                        "sub": str(sub),
+                        "name": userinfo.get("name"),
+                        "preferred_username": username,
+                        "email": userinfo.get("email"),
+                        "email_verified": userinfo.get("email_verified"),
+                        "profile": userinfo.get("profile"),
+                        "picture": userinfo.get("picture"),
+                        "organizations": userinfo.get("organizations"),
+                        "huggingface_userinfo": userinfo,
+                        "huggingface_whoami": whoami,
+                    },
+                )
+
+        except httpx.RequestError as e:
+            logger.debug("Failed to verify Hugging Face token: %s", e)
+            return None
+        except JSONDecodeError as e:
+            logger.debug("Hugging Face token verification error: %s", e)
+            return None
+
+    async def _fetch_whoami(
+        self, client: httpx.AsyncClient, token: str
+    ) -> dict[str, Any] | None:
+        response = await client.get(
+            HUGGINGFACE_WHOAMI_ENDPOINT,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "User-Agent": "FastMCP-HuggingFace-OAuth",
+            },
+        )
+        if response.status_code != 200:
+            logger.debug("Hugging Face whoami lookup failed: %d", response.status_code)
+            return None
+        return response.json()
+
+
+class HuggingFaceProvider(OAuthProxy):
+    """Complete Hugging Face OAuth provider for FastMCP."""
+
+    def __init__(
+        self,
+        *,
+        client_id: str,
+        client_secret: str | None = None,
+        base_url: AnyHttpUrl | str,
+        resource_base_url: AnyHttpUrl | str | None = None,
+        issuer_url: AnyHttpUrl | str | None = None,
+        redirect_path: str | None = None,
+        required_scopes: list[str] | None = None,
+        valid_scopes: list[str] | None = None,
+        timeout_seconds: int = 10,
+        allowed_client_redirect_uris: list[str] | None = None,
+        client_storage: AsyncKeyValue | None = None,
+        jwt_signing_key: str | bytes | None = None,
+        require_authorization_consent: bool | Literal["remember", "external"] = True,
+        consent_csp_policy: str | None = None,
+        forward_resource: bool = True,
+        fallback_refresh_token_expiry_seconds: int | None = None,
+        fastmcp_access_token_expiry_seconds: int | None = None,
+        token_expiry_threshold_seconds: int = 0,
+        extra_authorize_params: dict[str, str] | None = None,
+        extra_token_params: dict[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        enable_cimd: bool = True,
+    ):
+        """Initialize Hugging Face OAuth provider.
+
+        Args:
+            client_id: Hugging Face OAuth app client ID. Public apps and CIMD
+                client IDs are supported.
+            client_secret: Hugging Face OAuth app client secret. Optional for
+                public PKCE apps; when omitted, ``jwt_signing_key`` is required.
+            base_url: Public URL where OAuth endpoints will be accessible.
+            required_scopes: Required Hugging Face scopes. Defaults to
+                ``["openid", "profile"]``.
+            valid_scopes: Scopes clients may request. Defaults to required scopes.
+            extra_authorize_params: Extra authorization parameters, such as
+                ``{"orgIds": "your-org-id"}`` for organization grants.
+        """
+        required_scopes_final = (
+            parse_scopes(required_scopes)
+            if required_scopes is not None
+            else list(DEFAULT_HUGGINGFACE_SCOPES)
+        ) or []
+        valid_scopes_final = parse_scopes(valid_scopes)
+
+        # Do not pass provider-level required_scopes into the verifier here.
+        # Hugging Face's userinfo endpoint validates opaque access tokens and
+        # returns identity claims, but granted scopes are carried reliably in
+        # the upstream token response. OAuthProxy stores those scopes, enforces
+        # provider.required_scopes against FastMCP-issued tokens, and
+        # _uses_alternate_verification() patches the stored upstream scopes
+        # onto the returned AccessToken.
+        token_verifier = HuggingFaceTokenVerifier(
+            timeout_seconds=timeout_seconds,
+            http_client=http_client,
+        )
+
+        super().__init__(
+            upstream_authorization_endpoint=HUGGINGFACE_AUTHORIZATION_ENDPOINT,
+            upstream_token_endpoint=HUGGINGFACE_TOKEN_ENDPOINT,
+            upstream_client_id=client_id,
+            upstream_client_secret=client_secret,
+            token_verifier=token_verifier,
+            base_url=base_url,
+            resource_base_url=resource_base_url,
+            redirect_path=redirect_path,
+            issuer_url=issuer_url or base_url,
+            allowed_client_redirect_uris=allowed_client_redirect_uris,
+            client_storage=client_storage,
+            jwt_signing_key=jwt_signing_key,
+            require_authorization_consent=require_authorization_consent,
+            consent_csp_policy=consent_csp_policy,
+            forward_resource=forward_resource,
+            fallback_refresh_token_expiry_seconds=fallback_refresh_token_expiry_seconds,
+            fastmcp_access_token_expiry_seconds=fastmcp_access_token_expiry_seconds,
+            token_expiry_threshold_seconds=token_expiry_threshold_seconds,
+            extra_authorize_params=extra_authorize_params,
+            extra_token_params=extra_token_params,
+            token_endpoint_auth_method="client_secret_basic"
+            if client_secret
+            else "none",
+            valid_scopes=valid_scopes_final,
+            enable_cimd=enable_cimd,
+        )
+
+        logger.debug(
+            "Initialized Hugging Face OAuth provider for client %s with scopes: %s",
+            client_id,
+            required_scopes_final,
+        )
+
+        self.required_scopes = required_scopes_final
+        self.update_default_scopes(valid_scopes_final or required_scopes_final)
+
+    def _uses_alternate_verification(self) -> bool:
+        """Patch returned token scopes from the upstream token response.
+
+        Hugging Face OAuth access tokens are opaque. The userinfo endpoint
+        validates the token and returns identity claims, but scope information is
+        carried by the token response stored in OAuthProxy's upstream token set.
+        """
+        return True
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/in_memory.py b/fastmcp_slim/fastmcp/server/auth/providers/in_memory.py
new file mode 100644
index 0000000..3ae686d
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/in_memory.py
@@ -0,0 +1,366 @@
+import secrets
+import time
+
+from mcp.server.auth.provider import (
+    AccessToken,
+    AuthorizationCode,
+    AuthorizationParams,
+    AuthorizeError,
+    RefreshToken,
+    TokenError,
+    construct_redirect_uri,
+)
+from mcp.shared.auth import (
+    OAuthClientInformationFull,
+    OAuthToken,
+)
+from pydantic import AnyHttpUrl
+
+from fastmcp.server.auth.auth import (
+    ClientRegistrationOptions,
+    OAuthProvider,
+    RevocationOptions,
+)
+
+# Default expiration times (in seconds)
+DEFAULT_AUTH_CODE_EXPIRY_SECONDS = 5 * 60  # 5 minutes
+DEFAULT_ACCESS_TOKEN_EXPIRY_SECONDS = 60 * 60  # 1 hour
+DEFAULT_REFRESH_TOKEN_EXPIRY_SECONDS = None  # No expiry
+
+
+class InMemoryOAuthProvider(OAuthProvider):
+    """
+    An in-memory OAuth provider for testing purposes.
+    It simulates the OAuth 2.1 flow locally without external calls.
+    """
+
+    def __init__(
+        self,
+        base_url: AnyHttpUrl | str | None = None,
+        resource_base_url: AnyHttpUrl | str | None = None,
+        service_documentation_url: AnyHttpUrl | str | None = None,
+        client_registration_options: ClientRegistrationOptions | None = None,
+        revocation_options: RevocationOptions | None = None,
+        required_scopes: list[str] | None = None,
+    ):
+        super().__init__(
+            base_url=base_url or "http://fastmcp.example.com",
+            resource_base_url=resource_base_url,
+            service_documentation_url=service_documentation_url,
+            client_registration_options=client_registration_options,
+            revocation_options=revocation_options,
+            required_scopes=required_scopes,
+        )
+        self.clients: dict[str, OAuthClientInformationFull] = {}
+        self.auth_codes: dict[str, AuthorizationCode] = {}
+        self.access_tokens: dict[str, AccessToken] = {}
+        self.refresh_tokens: dict[str, RefreshToken] = {}
+
+        # For revoking associated tokens
+        self._access_to_refresh_map: dict[
+            str, str
+        ] = {}  # access_token_str -> refresh_token_str
+        self._refresh_to_access_map: dict[
+            str, str
+        ] = {}  # refresh_token_str -> access_token_str
+
+    async def get_client(self, client_id: str) -> OAuthClientInformationFull | None:
+        return self.clients.get(client_id)
+
+    async def register_client(self, client_info: OAuthClientInformationFull) -> None:
+        # Validate scopes against valid_scopes if configured (matches MCP SDK behavior)
+        if (
+            client_info.scope is not None
+            and self.client_registration_options is not None
+            and self.client_registration_options.valid_scopes is not None
+        ):
+            requested_scopes = set(client_info.scope.split())
+            valid_scopes = set(self.client_registration_options.valid_scopes)
+            invalid_scopes = requested_scopes - valid_scopes
+            if invalid_scopes:
+                raise ValueError(
+                    f"Requested scopes are not valid: {', '.join(invalid_scopes)}"
+                )
+
+        if client_info.client_id is None:
+            raise ValueError("client_id is required for client registration")
+        if client_info.client_id in self.clients:
+            # As per RFC 7591, if client_id is already known, it's an update.
+            # For this simple provider, we'll treat it as re-registration.
+            # A real provider might handle updates or raise errors for conflicts.
+            pass
+        self.clients[client_info.client_id] = client_info
+
+    async def authorize(
+        self, client: OAuthClientInformationFull, params: AuthorizationParams
+    ) -> str:
+        """
+        Simulates user authorization and generates an authorization code.
+        Returns a redirect URI with the code and state.
+        """
+        if client.client_id not in self.clients:
+            raise AuthorizeError(
+                error="unauthorized_client",
+                error_description=f"Client '{client.client_id}' not registered.",
+            )
+
+        # Validate redirect_uri (already validated by AuthorizationHandler, but good practice)
+        try:
+            # OAuthClientInformationFull should have a method like validate_redirect_uri
+            # For this test provider, we assume it's valid if it matches one in client_info
+            # The AuthorizationHandler already does robust validation using client.validate_redirect_uri
+            if client.redirect_uris and params.redirect_uri not in client.redirect_uris:
+                # This check might be too simplistic if redirect_uris can be patterns
+                # or if params.redirect_uri is None and client has a default.
+                # However, the AuthorizationHandler handles the primary validation.
+                pass  # Let's assume AuthorizationHandler did its job.
+        except Exception as e:  # Replace with specific validation error if client.validate_redirect_uri existed
+            raise AuthorizeError(
+                error="invalid_request", error_description="Invalid redirect_uri."
+            ) from e
+
+        auth_code_value = f"test_auth_code_{secrets.token_hex(16)}"
+        expires_at = time.time() + DEFAULT_AUTH_CODE_EXPIRY_SECONDS
+
+        # Ensure scopes are a list
+        scopes_list = params.scopes if params.scopes is not None else []
+        if client.scope:  # Filter params.scopes against client's registered scopes
+            client_allowed_scopes = set(client.scope.split())
+            scopes_list = [s for s in scopes_list if s in client_allowed_scopes]
+
+        if client.client_id is None:
+            raise AuthorizeError(
+                error="invalid_client", error_description="Client ID is required"
+            )
+        auth_code = AuthorizationCode(
+            code=auth_code_value,
+            client_id=client.client_id,
+            redirect_uri=params.redirect_uri,
+            redirect_uri_provided_explicitly=params.redirect_uri_provided_explicitly,
+            scopes=scopes_list,
+            expires_at=expires_at,
+            code_challenge=params.code_challenge,
+            # code_challenge_method is assumed S256 by the framework
+        )
+        self.auth_codes[auth_code_value] = auth_code
+
+        return construct_redirect_uri(
+            str(params.redirect_uri), code=auth_code_value, state=params.state
+        )
+
+    async def load_authorization_code(
+        self, client: OAuthClientInformationFull, authorization_code: str
+    ) -> AuthorizationCode | None:
+        auth_code_obj = self.auth_codes.get(authorization_code)
+        if auth_code_obj:
+            if auth_code_obj.client_id != client.client_id:
+                return None  # Belongs to a different client
+            if auth_code_obj.expires_at < time.time():
+                del self.auth_codes[authorization_code]  # Expired
+                return None
+            return auth_code_obj
+        return None
+
+    async def exchange_authorization_code(
+        self, client: OAuthClientInformationFull, authorization_code: AuthorizationCode
+    ) -> OAuthToken:
+        # Authorization code should have been validated (existence, expiry, client_id match)
+        # by the TokenHandler calling load_authorization_code before this.
+        # We might want to re-verify or simply trust it's valid.
+
+        if authorization_code.code not in self.auth_codes:
+            raise TokenError(
+                "invalid_grant", "Authorization code not found or already used."
+            )
+
+        # Consume the auth code
+        del self.auth_codes[authorization_code.code]
+
+        access_token_value = f"test_access_token_{secrets.token_hex(32)}"
+        refresh_token_value = f"test_refresh_token_{secrets.token_hex(32)}"
+
+        access_token_expires_at = int(time.time() + DEFAULT_ACCESS_TOKEN_EXPIRY_SECONDS)
+
+        # Refresh token expiry
+        refresh_token_expires_at = None
+        if DEFAULT_REFRESH_TOKEN_EXPIRY_SECONDS is not None:
+            refresh_token_expires_at = int(
+                time.time() + DEFAULT_REFRESH_TOKEN_EXPIRY_SECONDS
+            )
+
+        if client.client_id is None:
+            raise TokenError("invalid_client", "Client ID is required")
+        self.access_tokens[access_token_value] = AccessToken(
+            token=access_token_value,
+            client_id=client.client_id,
+            scopes=authorization_code.scopes,
+            expires_at=access_token_expires_at,
+        )
+        self.refresh_tokens[refresh_token_value] = RefreshToken(
+            token=refresh_token_value,
+            client_id=client.client_id,
+            scopes=authorization_code.scopes,  # Refresh token inherits scopes
+            expires_at=refresh_token_expires_at,
+        )
+
+        self._access_to_refresh_map[access_token_value] = refresh_token_value
+        self._refresh_to_access_map[refresh_token_value] = access_token_value
+
+        return OAuthToken(
+            access_token=access_token_value,
+            token_type="Bearer",
+            expires_in=DEFAULT_ACCESS_TOKEN_EXPIRY_SECONDS,
+            refresh_token=refresh_token_value,
+            scope=" ".join(authorization_code.scopes),
+        )
+
+    async def load_refresh_token(
+        self, client: OAuthClientInformationFull, refresh_token: str
+    ) -> RefreshToken | None:
+        token_obj = self.refresh_tokens.get(refresh_token)
+        if token_obj:
+            if token_obj.client_id != client.client_id:
+                return None  # Belongs to different client
+            if token_obj.expires_at is not None and token_obj.expires_at < time.time():
+                self._revoke_internal(
+                    refresh_token_str=token_obj.token
+                )  # Clean up expired
+                return None
+            return token_obj
+        return None
+
+    async def exchange_refresh_token(
+        self,
+        client: OAuthClientInformationFull,
+        refresh_token: RefreshToken,  # This is the RefreshToken object, already loaded
+        scopes: list[str],  # Requested scopes for the new access token
+    ) -> OAuthToken:
+        # Validate scopes: requested scopes must be a subset of original scopes
+        original_scopes = set(refresh_token.scopes)
+        requested_scopes = set(scopes)
+        if not requested_scopes.issubset(original_scopes):
+            raise TokenError(
+                "invalid_scope",
+                "Requested scopes exceed those authorized by the refresh token.",
+            )
+
+        # Invalidate old refresh token and its associated access token (rotation)
+        self._revoke_internal(refresh_token_str=refresh_token.token)
+
+        # Issue new tokens
+        new_access_token_value = f"test_access_token_{secrets.token_hex(32)}"
+        new_refresh_token_value = f"test_refresh_token_{secrets.token_hex(32)}"
+
+        access_token_expires_at = int(time.time() + DEFAULT_ACCESS_TOKEN_EXPIRY_SECONDS)
+
+        # Refresh token expiry
+        refresh_token_expires_at = None
+        if DEFAULT_REFRESH_TOKEN_EXPIRY_SECONDS is not None:
+            refresh_token_expires_at = int(
+                time.time() + DEFAULT_REFRESH_TOKEN_EXPIRY_SECONDS
+            )
+
+        if client.client_id is None:
+            raise TokenError("invalid_client", "Client ID is required")
+        self.access_tokens[new_access_token_value] = AccessToken(
+            token=new_access_token_value,
+            client_id=client.client_id,
+            scopes=scopes,  # Use newly requested (and validated) scopes
+            expires_at=access_token_expires_at,
+        )
+        self.refresh_tokens[new_refresh_token_value] = RefreshToken(
+            token=new_refresh_token_value,
+            client_id=client.client_id,
+            scopes=scopes,  # New refresh token also gets these scopes
+            expires_at=refresh_token_expires_at,
+        )
+
+        self._access_to_refresh_map[new_access_token_value] = new_refresh_token_value
+        self._refresh_to_access_map[new_refresh_token_value] = new_access_token_value
+
+        return OAuthToken(
+            access_token=new_access_token_value,
+            token_type="Bearer",
+            expires_in=DEFAULT_ACCESS_TOKEN_EXPIRY_SECONDS,
+            refresh_token=new_refresh_token_value,
+            scope=" ".join(scopes),
+        )
+
+    async def load_access_token(self, token: str) -> AccessToken | None:  # type: ignore[override]  # ty:ignore[invalid-method-override]
+        token_obj = self.access_tokens.get(token)
+        if token_obj:
+            if token_obj.expires_at is not None and token_obj.expires_at < time.time():
+                self._revoke_internal(
+                    access_token_str=token_obj.token
+                )  # Clean up expired
+                return None
+            return token_obj
+        return None
+
+    async def verify_token(self, token: str) -> AccessToken | None:  # type: ignore[override]  # ty:ignore[invalid-method-override]
+        """
+        Verify a bearer token and return access info if valid.
+
+        This method implements the TokenVerifier protocol by delegating
+        to our existing load_access_token method.
+
+        Args:
+            token: The token string to validate
+
+        Returns:
+            AccessToken object if valid, None if invalid or expired
+        """
+        return await self.load_access_token(token)
+
+    def _revoke_internal(
+        self, access_token_str: str | None = None, refresh_token_str: str | None = None
+    ):
+        """Internal helper to remove tokens and their associations."""
+        removed_access_token = None
+        removed_refresh_token = None
+
+        if access_token_str:
+            if access_token_str in self.access_tokens:
+                del self.access_tokens[access_token_str]
+                removed_access_token = access_token_str
+
+            # Get associated refresh token
+            associated_refresh = self._access_to_refresh_map.pop(access_token_str, None)
+            if associated_refresh:
+                if associated_refresh in self.refresh_tokens:
+                    del self.refresh_tokens[associated_refresh]
+                    removed_refresh_token = associated_refresh
+                self._refresh_to_access_map.pop(associated_refresh, None)
+
+        if refresh_token_str:
+            if refresh_token_str in self.refresh_tokens:
+                del self.refresh_tokens[refresh_token_str]
+                removed_refresh_token = refresh_token_str
+
+            # Get associated access token
+            associated_access = self._refresh_to_access_map.pop(refresh_token_str, None)
+            if associated_access:
+                if associated_access in self.access_tokens:
+                    del self.access_tokens[associated_access]
+                    removed_access_token = associated_access
+                self._access_to_refresh_map.pop(associated_access, None)
+
+        # Clean up any dangling references if one part of the pair was already gone
+        if removed_access_token and removed_access_token in self._access_to_refresh_map:
+            del self._access_to_refresh_map[removed_access_token]
+        if (
+            removed_refresh_token
+            and removed_refresh_token in self._refresh_to_access_map
+        ):
+            del self._refresh_to_access_map[removed_refresh_token]
+
+    async def revoke_token(
+        self,
+        token: AccessToken | RefreshToken,
+    ) -> None:
+        """Revokes an access or refresh token and its counterpart."""
+        if isinstance(token, AccessToken):
+            self._revoke_internal(access_token_str=token.token)
+        elif isinstance(token, RefreshToken):
+            self._revoke_internal(refresh_token_str=token.token)
+        # If token is not found or already revoked, _revoke_internal does nothing, which is correct.
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/introspection.py b/fastmcp_slim/fastmcp/server/auth/providers/introspection.py
new file mode 100644
index 0000000..f24b548
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/introspection.py
@@ -0,0 +1,305 @@
+"""OAuth 2.0 Token Introspection (RFC 7662) provider for FastMCP.
+
+This module provides token verification for opaque tokens using the OAuth 2.0
+Token Introspection protocol defined in RFC 7662. It allows FastMCP servers to
+validate tokens issued by authorization servers that don't use JWT format.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth.providers.introspection import IntrospectionTokenVerifier
+
+    # Verify opaque tokens via RFC 7662 introspection
+    verifier = IntrospectionTokenVerifier(
+        introspection_url="https://auth.example.com/oauth/introspect",
+        client_id="your-client-id",
+        client_secret="your-client-secret",
+        required_scopes=["read", "write"]
+    )
+
+    mcp = FastMCP("My Protected Server", auth=verifier)
+    ```
+"""
+
+from __future__ import annotations
+
+import base64
+import contextlib
+import time
+from typing import Any, Literal, get_args
+
+import httpx
+from pydantic import AnyHttpUrl, SecretStr
+
+from fastmcp.server.auth import AccessToken, TokenVerifier
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.token_cache import TokenCache
+
+logger = get_logger(__name__)
+
+
+ClientAuthMethod = Literal["client_secret_basic", "client_secret_post"]
+
+
+class IntrospectionTokenVerifier(TokenVerifier):
+    """
+    OAuth 2.0 Token Introspection verifier (RFC 7662).
+
+    This verifier validates opaque tokens by calling an OAuth 2.0 token introspection
+    endpoint. Unlike JWT verification which is stateless, token introspection requires
+    a network call to the authorization server for each token validation.
+
+    The verifier authenticates to the introspection endpoint using either:
+    - HTTP Basic Auth (client_secret_basic, default): credentials in Authorization header
+    - POST body authentication (client_secret_post): credentials in request body
+
+    Both methods are specified in RFC 6749 (OAuth 2.0) and RFC 7662 (Token Introspection).
+
+    Use this when:
+    - Your authorization server issues opaque (non-JWT) tokens
+    - You need to validate tokens from Auth0, Okta, Keycloak, or other OAuth servers
+    - Your tokens require real-time revocation checking
+    - Your authorization server supports RFC 7662 introspection
+
+    Caching is disabled by default to preserve real-time revocation semantics.
+    Set ``cache_ttl_seconds`` to enable caching and reduce load on the
+    introspection endpoint (e.g., ``cache_ttl_seconds=300`` for 5 minutes).
+
+    Example:
+        ```python
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="my-service",
+            client_secret="secret-key",
+            required_scopes=["api:read"]
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        introspection_url: str,
+        client_id: str,
+        client_secret: str | SecretStr,
+        client_auth_method: ClientAuthMethod = "client_secret_basic",
+        timeout_seconds: int = 10,
+        required_scopes: list[str] | None = None,
+        base_url: AnyHttpUrl | str | None = None,
+        cache_ttl_seconds: int | None = None,
+        max_cache_size: int | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ):
+        """
+        Initialize the introspection token verifier.
+
+        Args:
+            introspection_url: URL of the OAuth 2.0 token introspection endpoint
+            client_id: OAuth client ID for authenticating to the introspection endpoint
+            client_secret: OAuth client secret for authenticating to the introspection endpoint
+            client_auth_method: Client authentication method. "client_secret_basic" (default)
+                uses HTTP Basic Auth header, "client_secret_post" sends credentials in POST body
+            timeout_seconds: HTTP request timeout in seconds (default: 10)
+            required_scopes: Required scopes for all tokens (optional)
+            base_url: Base URL for TokenVerifier protocol
+            cache_ttl_seconds: How long to cache introspection results in seconds.
+                Caching is disabled by default (None) to preserve real-time
+                revocation semantics. Set to a positive integer to enable caching
+                (e.g., 300 for 5 minutes).
+            max_cache_size: Maximum number of tokens to cache when caching is
+                enabled. Default: 10000.
+            http_client: Optional httpx.AsyncClient for connection pooling. When provided,
+                the client is reused across calls and the caller is responsible for its
+                lifecycle. When None (default), a fresh client is created per call.
+        """
+        # Parse scopes if provided as string
+        parsed_required_scopes = (
+            parse_scopes(required_scopes) if required_scopes is not None else None
+        )
+
+        super().__init__(base_url=base_url, required_scopes=parsed_required_scopes)
+
+        self.introspection_url = introspection_url
+        self.client_id = client_id
+        self.client_secret = (
+            client_secret.get_secret_value()
+            if isinstance(client_secret, SecretStr)
+            else client_secret
+        )
+
+        # Validate client_auth_method to catch typos/invalid values early
+        valid_methods = get_args(ClientAuthMethod)
+        if client_auth_method not in valid_methods:
+            options = " or ".join(f"'{m}'" for m in valid_methods)
+            raise ValueError(
+                f"Invalid client_auth_method: {client_auth_method!r}. "
+                f"Must be {options}."
+            )
+        self.client_auth_method: ClientAuthMethod = client_auth_method
+
+        self.timeout_seconds = timeout_seconds
+        self._http_client = http_client
+        self.logger = get_logger(__name__)
+
+        self._cache = TokenCache(
+            ttl_seconds=cache_ttl_seconds,
+            max_size=max_cache_size,
+        )
+
+    def _create_basic_auth_header(self) -> str:
+        """Create HTTP Basic Auth header value from client credentials."""
+        credentials = f"{self.client_id}:{self.client_secret}"
+        encoded = base64.b64encode(credentials.encode("utf-8")).decode("utf-8")
+        return f"Basic {encoded}"
+
+    def _extract_scopes(self, introspection_response: dict[str, Any]) -> list[str]:
+        """
+        Extract scopes from introspection response.
+
+        RFC 7662 allows scopes to be returned as either:
+        - A space-separated string in the 'scope' field
+        - An array of strings in the 'scope' field (less common but valid)
+        """
+        scope_value = introspection_response.get("scope")
+
+        if scope_value is None:
+            return []
+
+        # Handle string (space-separated) scopes
+        if isinstance(scope_value, str):
+            return [s.strip() for s in scope_value.split() if s.strip()]
+
+        # Handle array of scopes
+        if isinstance(scope_value, list):
+            return [str(s) for s in scope_value if s]
+
+        return []
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """
+        Verify a bearer token using OAuth 2.0 Token Introspection (RFC 7662).
+
+        This method makes a POST request to the introspection endpoint with the token,
+        authenticated using the configured client authentication method (client_secret_basic
+        or client_secret_post).
+
+        Results are cached in-memory to reduce load on the introspection endpoint.
+        Cache TTL and size are configurable via constructor parameters.
+
+        Args:
+            token: The opaque token string to validate
+
+        Returns:
+            AccessToken object if valid and active, None if invalid, inactive, or expired
+        """
+        # Check cache first
+        is_cached, cached_result = self._cache.get(token)
+        if is_cached:
+            self.logger.debug("Token introspection cache hit")
+            return cached_result
+
+        try:
+            async with (
+                contextlib.nullcontext(self._http_client)
+                if self._http_client is not None
+                else httpx.AsyncClient(timeout=self.timeout_seconds)
+            ) as client:
+                # Prepare introspection request per RFC 7662
+                # Build request data with token and token_type_hint
+                data = {
+                    "token": token,
+                    "token_type_hint": "access_token",
+                }
+
+                # Build headers
+                headers = {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    "Accept": "application/json",
+                }
+
+                # Add client authentication based on method
+                if self.client_auth_method == "client_secret_basic":
+                    headers["Authorization"] = self._create_basic_auth_header()
+                elif self.client_auth_method == "client_secret_post":
+                    data["client_id"] = self.client_id
+                    data["client_secret"] = self.client_secret
+
+                response = await client.post(
+                    self.introspection_url,
+                    data=data,
+                    headers=headers,
+                )
+
+                # Check for HTTP errors - don't cache HTTP errors (may be transient)
+                if response.status_code != 200:
+                    self.logger.debug(
+                        "Token introspection failed: HTTP %d - %s",
+                        response.status_code,
+                        response.text[:200] if response.text else "",
+                    )
+                    return None
+
+                introspection_data = response.json()
+
+                # Check if token is active (required field per RFC 7662)
+                # Don't cache inactive tokens - they may become valid later
+                # (e.g., tokens with future nbf, or propagation delays)
+                if not introspection_data.get("active", False):
+                    self.logger.debug("Token introspection returned active=false")
+                    return None
+
+                # Extract client_id (should be present for active tokens)
+                client_id = introspection_data.get(
+                    "client_id"
+                ) or introspection_data.get("sub", "unknown")
+
+                # Extract expiration time
+                exp = introspection_data.get("exp")
+                if exp:
+                    # Validate expiration (belt and suspenders - server should set active=false)
+                    if exp < time.time():
+                        self.logger.debug(
+                            "Token validation failed: expired token for client %s",
+                            client_id,
+                        )
+                        return None
+
+                # Extract scopes
+                scopes = self._extract_scopes(introspection_data)
+
+                # Check required scopes
+                # Don't cache scope failures - permissions may be updated dynamically
+                if self.required_scopes:
+                    token_scopes = set(scopes)
+                    required_scopes = set(self.required_scopes)
+                    if not required_scopes.issubset(token_scopes):
+                        self.logger.debug(
+                            "Token missing required scopes. Has: %s, Required: %s",
+                            token_scopes,
+                            required_scopes,
+                        )
+                        return None
+
+                # Create AccessToken with introspection response data
+                result = AccessToken(
+                    token=token,
+                    client_id=str(client_id),
+                    scopes=scopes,
+                    expires_at=int(exp) if exp is not None else None,
+                    claims=introspection_data,  # Store full response for extensibility
+                )
+                self._cache.set(token, result)
+                return result
+
+        except httpx.TimeoutException:
+            self.logger.debug(
+                "Token introspection timed out after %d seconds", self.timeout_seconds
+            )
+            return None
+        except httpx.RequestError as e:
+            self.logger.debug("Token introspection request failed: %s", e)
+            return None
+        except Exception as e:
+            self.logger.debug("Token introspection error: %s", e)
+            return None
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/jwt.py b/fastmcp_slim/fastmcp/server/auth/providers/jwt.py
new file mode 100644
index 0000000..6ed151f
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/jwt.py
@@ -0,0 +1,655 @@
+"""TokenVerifier implementations for FastMCP."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import time
+from dataclasses import dataclass
+from typing import Any, TypeAlias, cast
+
+import httpx
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+from joserfc import jwk, jwt
+from joserfc.errors import JoseError
+from joserfc.jws import JWSRegistry
+from joserfc.registry import JWS_HEADER_REGISTRY
+from pydantic import AnyHttpUrl, SecretStr
+from typing_extensions import TypedDict
+
+from fastmcp.server.auth import AccessToken, TokenVerifier
+from fastmcp.server.auth.ssrf import SSRFError, SSRFFetchError, ssrf_safe_fetch
+from fastmcp.utilities.auth import decode_jwt_header, parse_scopes
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+JWKKeyData: TypeAlias = dict[str, str | list[str]]
+SUPPORTED_JWS_HEADER_FIELDS = frozenset(JWS_HEADER_REGISTRY)
+
+
+def _import_key_for_algorithm(key: str | bytes | JWKKeyData, algorithm: str):
+    if algorithm.startswith("HS"):
+        return jwk.import_key(key, "oct")
+    if algorithm.startswith(("RS", "PS")):
+        return jwk.import_key(key, "RSA")
+    if algorithm.startswith("ES"):
+        return jwk.import_key(key, "EC")
+    raise ValueError(f"Unsupported algorithm: {algorithm}.")
+
+
+def _jwk_to_pem(key_data: JWKKeyData) -> str:
+    key_type = key_data.get("kty")
+    if key_type == "RSA":
+        return jwk.import_key(key_data, "RSA").as_pem().decode("utf-8")
+    if key_type == "EC":
+        return jwk.import_key(key_data, "EC").as_pem().decode("utf-8")
+    raise ValueError(f"Unsupported JWK key type: {key_type!r}")
+
+
+def _has_unsupported_critical_headers(header: dict[str, Any]) -> bool:
+    crit = header.get("crit")
+    if crit is None:
+        return False
+    if not isinstance(crit, list):
+        return True
+
+    return any(
+        not isinstance(header_name, str)
+        or header_name not in header
+        or header_name not in SUPPORTED_JWS_HEADER_FIELDS
+        for header_name in crit
+    )
+
+
+class JWKData(TypedDict, total=False):
+    """JSON Web Key data structure."""
+
+    kty: str  # Key type (e.g., "RSA") - required
+    kid: str  # Key ID (optional but recommended)
+    use: str  # Usage (e.g., "sig")
+    alg: str  # Algorithm (e.g., "RS256")
+    n: str  # Modulus (for RSA keys)
+    e: str  # Exponent (for RSA keys)
+    x5c: list[str]  # X.509 certificate chain (for JWKs)
+    x5t: str  # X.509 certificate thumbprint (for JWKs)
+
+
+class JWKSData(TypedDict):
+    """JSON Web Key Set data structure."""
+
+    keys: list[JWKData]
+
+
+@dataclass(frozen=True, kw_only=True, repr=False)
+class RSAKeyPair:
+    """RSA key pair for JWT testing."""
+
+    private_key: SecretStr
+    public_key: str
+
+    @classmethod
+    def generate(cls) -> RSAKeyPair:
+        """
+        Generate an RSA key pair for testing.
+
+        Returns:
+            RSAKeyPair: Generated key pair
+        """
+        # Generate private key
+        private_key = rsa.generate_private_key(
+            public_exponent=65537,
+            key_size=2048,
+        )
+
+        # Serialize private key to PEM format
+        private_pem = private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.NoEncryption(),
+        ).decode("utf-8")
+
+        # Serialize public key to PEM format
+        public_pem = (
+            private_key.public_key()
+            .public_bytes(
+                encoding=serialization.Encoding.PEM,
+                format=serialization.PublicFormat.SubjectPublicKeyInfo,
+            )
+            .decode("utf-8")
+        )
+
+        return cls(
+            private_key=SecretStr(private_pem),
+            public_key=public_pem,
+        )
+
+    def create_token(
+        self,
+        subject: str = "fastmcp-user",
+        issuer: str = "https://fastmcp.example.com",
+        audience: str | list[str] | None = None,
+        scopes: list[str] | None = None,
+        expires_in_seconds: int = 3600,
+        additional_claims: dict[str, Any] | None = None,
+        kid: str | None = None,
+    ) -> str:
+        """
+        Generate a test JWT token for testing purposes.
+
+        Args:
+            subject: Subject claim (usually user ID)
+            issuer: Issuer claim
+            audience: Audience claim - can be a string or list of strings (optional)
+            scopes: List of scopes to include
+            expires_in_seconds: Token expiration time in seconds
+            additional_claims: Any additional claims to include
+            kid: Key ID to include in header
+        """
+        # Create header
+        header = {"alg": "RS256"}
+        if kid:
+            header["kid"] = kid
+
+        # Create payload
+        payload: dict[str, str | int | list[str]] = {
+            "sub": subject,
+            "iss": issuer,
+            "iat": int(time.time()),
+            "exp": int(time.time()) + expires_in_seconds,
+        }
+
+        if audience:
+            payload["aud"] = audience
+
+        if scopes:
+            payload["scope"] = " ".join(scopes)
+
+        if additional_claims:
+            payload.update(additional_claims)
+
+        # Create JWT
+        signing_key = _import_key_for_algorithm(
+            self.private_key.get_secret_value(), "RS256"
+        )
+        token = jwt.encode(header, payload, signing_key, algorithms=["RS256"])
+
+        return token
+
+
+def _looks_like_pem_public_key(key: str | bytes) -> bool:
+    """Return True when key text appears to be PEM-encoded asymmetric key material."""
+    if isinstance(key, bytes):
+        key = key.decode("utf-8", errors="replace")
+    key_text = key.strip()
+    pem_markers = (
+        "-----BEGIN PUBLIC KEY-----",
+        "-----BEGIN RSA PUBLIC KEY-----",
+        "-----BEGIN EC PUBLIC KEY-----",
+        "-----BEGIN CERTIFICATE-----",
+    )
+    return any(marker in key_text for marker in pem_markers)
+
+
+class JWTVerifier(TokenVerifier):
+    """
+    JWT token verifier supporting both asymmetric (RSA/ECDSA) and symmetric (HMAC) algorithms.
+
+    This verifier validates JWT tokens using various signing algorithms:
+    - **Asymmetric algorithms** (RS256/384/512, ES256/384/512, PS256/384/512):
+      Uses public/private key pairs. Ideal for external clients and services where
+      only the authorization server has the private key.
+    - **Symmetric algorithms** (HS256/384/512): Uses a shared secret for both
+      signing and verification. Perfect for internal microservices and trusted
+      environments where the secret can be securely shared.
+
+    Use this when:
+    - You have JWT tokens issued by an external service (asymmetric)
+    - You need JWKS support for automatic key rotation (asymmetric)
+    - You have internal microservices sharing a secret key (symmetric)
+    - Your tokens contain standard OAuth scopes and claims
+    """
+
+    def __init__(
+        self,
+        *,
+        public_key: str | bytes | None = None,
+        jwks_uri: str | None = None,
+        issuer: str | list[str] | None = None,
+        audience: str | list[str] | None = None,
+        algorithm: str | None = None,
+        required_scopes: list[str] | None = None,
+        base_url: AnyHttpUrl | str | None = None,
+        ssrf_safe: bool = False,
+        http_client: httpx.AsyncClient | None = None,
+    ):
+        """
+        Initialize a JWTVerifier configured to validate JWTs using either a static key or a JWKS endpoint.
+
+        Parameters:
+            public_key: PEM-encoded public key for asymmetric algorithms or shared secret for symmetric algorithms.
+            jwks_uri: URI to fetch a JSON Web Key Set; used when verifying tokens with remote JWKS.
+            issuer: Expected issuer claim value or list of allowed issuer values.
+            audience: Expected audience claim value or list of allowed audience values.
+            algorithm: JWT signing algorithm to accept (default: "RS256"). Supported: HS256/384/512, RS256/384/512, ES256/384/512, PS256/384/512.
+            required_scopes: Scopes that must be present in validated tokens.
+            base_url: Base URL passed to the parent TokenVerifier.
+            ssrf_safe: If True, JWKS fetches use SSRF protection (HTTPS-only,
+                public IPs, DNS pinning). Enable when the JWKS URI comes from
+                untrusted input (e.g. CIMD documents). Defaults to False so
+                operator-configured JWKS URIs (including localhost) work normally.
+            http_client: Optional httpx.AsyncClient for connection pooling. When provided,
+                the client is reused for JWKS fetches and the caller is responsible for
+                its lifecycle. When None (default), a fresh client is created per fetch.
+                Cannot be used with ssrf_safe=True.
+
+        Raises:
+            ValueError: If neither or both of `public_key` and `jwks_uri` are provided,
+                if `algorithm` is unsupported, or if `http_client` is provided with `ssrf_safe=True`.
+        """
+        if not public_key and not jwks_uri:
+            raise ValueError("Either public_key or jwks_uri must be provided")
+
+        if public_key and jwks_uri:
+            raise ValueError("Provide either public_key or jwks_uri, not both")
+
+        # Only enforce ssrf_safe/http_client exclusivity when JWKS fetching is used
+        if jwks_uri and ssrf_safe and http_client is not None:
+            raise ValueError(
+                "http_client cannot be used with ssrf_safe=True; "
+                "SSRF-safe mode requires its own hardened transport"
+            )
+
+        algorithm = algorithm or "RS256"
+        if algorithm not in {
+            "HS256",
+            "HS384",
+            "HS512",
+            "RS256",
+            "RS384",
+            "RS512",
+            "ES256",
+            "ES384",
+            "ES512",
+            "PS256",
+            "PS384",
+            "PS512",
+        }:
+            raise ValueError(f"Unsupported algorithm: {algorithm}.")
+
+        if algorithm.startswith("HS"):
+            if jwks_uri:
+                raise ValueError(
+                    "Symmetric HS* algorithms cannot be used with jwks_uri; "
+                    "configure a shared secret via public_key instead."
+                )
+            if public_key and _looks_like_pem_public_key(public_key):
+                raise ValueError(
+                    "Symmetric HS* algorithms require a shared secret, not a public key."
+                )
+
+        # Parse scopes if provided as string
+        parsed_required_scopes = (
+            parse_scopes(required_scopes) if required_scopes is not None else None
+        )
+
+        # Initialize parent TokenVerifier
+        super().__init__(
+            base_url=base_url,
+            required_scopes=parsed_required_scopes,
+        )
+
+        self.algorithm = algorithm
+        self.issuer = issuer
+        self.audience = audience
+        self.public_key = public_key
+        self.jwks_uri = jwks_uri
+        self.ssrf_safe = ssrf_safe
+        self._http_client = http_client
+        self.logger = get_logger(__name__)
+
+        # Simple JWKS cache
+        self._jwks_cache: dict[str, str] = {}
+        self._jwks_cache_time: float = 0
+        self._cache_ttl = 3600  # 1 hour
+
+    async def _get_verification_key(self, token: str) -> str | bytes:
+        """Get the verification key for the token."""
+        if self.public_key:
+            return self.public_key
+
+        # Extract kid from token header for JWKS lookup
+        try:
+            header = decode_jwt_header(token)
+            kid = header.get("kid")
+            return await self._get_jwks_key(kid)
+
+        except (ValueError, KeyError, IndexError, json.JSONDecodeError) as e:
+            raise ValueError(f"Failed to extract key ID from token: {e}") from e
+
+    async def _get_jwks_key(self, kid: str | None) -> str:
+        """Fetch key from JWKS with simple caching and SSRF protection."""
+        if not self.jwks_uri:
+            raise ValueError("JWKS URI not configured")
+
+        current_time = time.time()
+
+        # Check cache first
+        if current_time - self._jwks_cache_time < self._cache_ttl:
+            if kid and kid in self._jwks_cache:
+                return self._jwks_cache[kid]
+            elif not kid and len(self._jwks_cache) == 1:
+                # If no kid but only one key cached, use it
+                return next(iter(self._jwks_cache.values()))
+
+        # Fetch JWKS — with SSRF protection when enabled (untrusted URIs)
+        try:
+            jwks_data = await self._fetch_jwks()
+
+            # Cache all keys
+            self._jwks_cache = {}
+            for key_data in jwks_data.get("keys", []):
+                key_kid = key_data.get("kid")
+                public_key = _jwk_to_pem(key_data)
+
+                if key_kid:
+                    self._jwks_cache[key_kid] = public_key
+                else:
+                    # Key without kid - use a default identifier
+                    self._jwks_cache["_default"] = public_key
+
+            self._jwks_cache_time = current_time
+
+            # Select the appropriate key
+            if kid:
+                if kid not in self._jwks_cache:
+                    self.logger.debug(
+                        "JWKS key lookup failed: key ID '%s' not found", kid
+                    )
+                    raise ValueError(f"Key ID '{kid}' not found in JWKS")
+                return self._jwks_cache[kid]
+            else:
+                # No kid in token - only allow if there's exactly one key
+                if len(self._jwks_cache) == 1:
+                    return next(iter(self._jwks_cache.values()))
+                elif len(self._jwks_cache) > 1:
+                    raise ValueError(
+                        "Multiple keys in JWKS but no key ID (kid) in token"
+                    )
+                else:
+                    raise ValueError("No keys found in JWKS")
+
+        except (SSRFError, SSRFFetchError) as e:
+            self.logger.debug("JWKS fetch blocked by SSRF protection: %s", e)
+            raise ValueError(f"Failed to fetch JWKS: {e}") from e
+        except httpx.HTTPError as e:
+            raise ValueError(f"Failed to fetch JWKS: {e}") from e
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JWKS JSON: {e}") from e
+        except (JoseError, TypeError, KeyError, ValueError) as e:
+            self.logger.debug("JWKS key processing failed: %s", e)
+            raise ValueError(f"Failed to process JWKS: {e}") from e
+
+    async def _fetch_jwks(self) -> dict[str, Any]:
+        """Fetch JWKS data, using SSRF-safe or standard fetch based on config."""
+        if not self.jwks_uri:
+            raise ValueError("JWKS URI not configured")
+
+        if self.ssrf_safe:
+            content = await ssrf_safe_fetch(
+                self.jwks_uri,
+                max_size=65536,
+                timeout=10.0,
+                overall_timeout=30.0,
+            )
+            return json.loads(content)
+        else:
+            async with (
+                contextlib.nullcontext(self._http_client)
+                if self._http_client is not None
+                else httpx.AsyncClient(timeout=httpx.Timeout(10.0))
+            ) as client:
+                response = await client.get(self.jwks_uri)
+                response.raise_for_status()
+                return response.json()
+
+    def _extract_scopes(self, claims: dict[str, Any]) -> list[str]:
+        """
+        Extract scopes from JWT claims. Supports both 'scope' and 'scp'
+        claims.
+
+        Checks the `scope` claim first (standard OAuth2 claim), then the `scp`
+        claim (used by some Identity Providers).
+        """
+        for claim in ["scope", "scp"]:
+            if claim in claims:
+                if isinstance(claims[claim], str):
+                    return claims[claim].split()
+                elif isinstance(claims[claim], list):
+                    return claims[claim]
+
+        return []
+
+    async def load_access_token(self, token: str) -> AccessToken | None:
+        """
+        Validate a JWT bearer token and return an AccessToken when the token is valid.
+
+        Parameters:
+            token (str): The JWT bearer token string to validate.
+
+        Returns:
+            AccessToken | None: An AccessToken populated from token claims if the token is valid; `None` if the token is expired, has an invalid signature or format, fails issuer/audience/scope validation, or any other validation error occurs.
+        """
+        try:
+            # Get verification key (static or from JWKS)
+            verification_key = await self._get_verification_key(token)
+
+            # Decode and verify the JWT token
+            key = _import_key_for_algorithm(verification_key, self.algorithm)
+            header = decode_jwt_header(token)
+            if _has_unsupported_critical_headers(header):
+                self.logger.debug(
+                    "Token validation failed: unsupported critical JWT header"
+                )
+                return None
+
+            claims = jwt.decode(
+                token,
+                key,
+                algorithms=[self.algorithm],
+                registry=JWSRegistry(
+                    algorithms=[self.algorithm],
+                    strict_check_header=False,
+                ),
+            ).claims
+
+            # Extract client ID early for logging
+            client_id = (
+                claims.get("client_id")
+                or claims.get("azp")
+                or claims.get("sub")
+                or "unknown"
+            )
+
+            # Validate expiration. Kept at INFO (not WARNING like issuer/
+            # audience/scope mismatches below) — expiry is expected-path noise
+            # from normal token rotation, not a configuration error worth
+            # surfacing by default.
+            exp = claims.get("exp")
+            if exp is not None and exp < time.time():
+                self.logger.info(
+                    "Bearer token rejected for client %s: token expired",
+                    client_id,
+                )
+                return None
+
+            # Validate issuer - note we use issuer instead of issuer_url here because
+            # issuer is optional, allowing users to make this check optional
+            if self.issuer:
+                iss = claims.get("iss")
+
+                # Handle different combinations of issuer types
+                issuer_valid = False
+                if isinstance(self.issuer, list):
+                    # self.issuer is a list - check if token issuer matches any expected issuer
+                    issuer_valid = iss in self.issuer
+                else:
+                    # self.issuer is a string - check for equality
+                    issuer_valid = iss == self.issuer
+
+                if not issuer_valid:
+                    self.logger.warning(
+                        "Bearer token rejected for client %s: issuer mismatch "
+                        "(got %r, expected %r)",
+                        client_id,
+                        iss,
+                        self.issuer,
+                    )
+                    return None
+
+            # Validate audience if configured
+            if self.audience:
+                aud = claims.get("aud")
+
+                # Handle different combinations of audience types
+                audience_valid = False
+                if isinstance(self.audience, list):
+                    # self.audience is a list - check if any expected audience is present
+                    if isinstance(aud, list):
+                        # Both are lists - check for intersection
+                        audience_valid = any(
+                            expected in aud for expected in self.audience
+                        )
+                    else:
+                        # aud is a string - check if it's in our expected list
+                        audience_valid = aud in cast(list, self.audience)
+                else:
+                    # self.audience is a string - use original logic
+                    if isinstance(aud, list):
+                        audience_valid = self.audience in aud
+                    else:
+                        audience_valid = aud == self.audience
+
+                if not audience_valid:
+                    self.logger.warning(
+                        "Bearer token rejected for client %s: audience mismatch "
+                        "(got %r, expected %r)",
+                        client_id,
+                        aud,
+                        self.audience,
+                    )
+                    return None
+
+            # Extract scopes
+            scopes = self._extract_scopes(claims)
+
+            # Check required scopes
+            if self.required_scopes:
+                token_scopes = set(scopes)
+                required_scopes = set(self.required_scopes)
+                if not required_scopes.issubset(token_scopes):
+                    self.logger.warning(
+                        "Bearer token rejected for client %s: missing required "
+                        "scopes (has %s, requires %s)",
+                        client_id,
+                        sorted(token_scopes),
+                        sorted(required_scopes),
+                    )
+                    return None
+
+            return AccessToken(
+                token=token,
+                client_id=str(client_id),
+                scopes=scopes,
+                expires_at=int(exp) if exp is not None else None,
+                claims=claims,
+            )
+
+        except JoseError:
+            self.logger.debug("Token validation failed: JWT signature/format invalid")
+            return None
+        except (ValueError, TypeError, KeyError, AttributeError) as e:
+            self.logger.debug("Token validation failed: %s", str(e))
+            return None
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """
+        Verify a bearer token and return access info if valid.
+
+        This method implements the TokenVerifier protocol by delegating
+        to our existing load_access_token method.
+
+        Args:
+            token: The JWT token string to validate
+
+        Returns:
+            AccessToken object if valid, None if invalid or expired
+        """
+        return await self.load_access_token(token)
+
+
+class StaticTokenVerifier(TokenVerifier):
+    """
+    Simple static token verifier for testing and development.
+
+    This verifier validates tokens against a predefined dictionary of valid token
+    strings and their associated claims. When a token string matches a key in the
+    dictionary, the verifier returns the corresponding claims as if the token was
+    validated by a real authorization server.
+
+    Use this when:
+    - You're developing or testing locally without a real OAuth server
+    - You need predictable tokens for automated testing
+    - You want to simulate different users/scopes without complex setup
+    - You're prototyping and need simple API key-style authentication
+
+    WARNING: Never use this in production - tokens are stored in plain text!
+    """
+
+    def __init__(
+        self,
+        tokens: dict[str, dict[str, Any]],
+        required_scopes: list[str] | None = None,
+    ):
+        """
+        Initialize the static token verifier.
+
+        Args:
+            tokens: Dict mapping token strings to token metadata
+                   Each token should have: client_id, scopes, expires_at (optional)
+            required_scopes: Required scopes for all tokens
+        """
+        super().__init__(required_scopes=required_scopes)
+        self.tokens = tokens
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify token against static token dictionary."""
+        token_data = self.tokens.get(token)
+        if not token_data:
+            return None
+
+        # Check expiration if present
+        expires_at = token_data.get("expires_at")
+        if expires_at is not None and expires_at < time.time():
+            return None
+
+        scopes = token_data.get("scopes", [])
+
+        # Check required scopes
+        if self.required_scopes:
+            token_scopes = set(scopes)
+            required_scopes = set(self.required_scopes)
+            if not required_scopes.issubset(token_scopes):
+                logger.debug(
+                    f"Token missing required scopes. Has: {token_scopes}, Required: {required_scopes}"
+                )
+                return None
+
+        return AccessToken(
+            token=token,
+            client_id=token_data["client_id"],
+            scopes=scopes,
+            expires_at=expires_at,
+            claims=token_data,
+        )
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/keycloak.py b/fastmcp_slim/fastmcp/server/auth/providers/keycloak.py
new file mode 100644
index 0000000..d018bc4
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/keycloak.py
@@ -0,0 +1,74 @@
+"""Keycloak authentication provider for FastMCP."""
+
+from __future__ import annotations
+
+from pydantic import AnyHttpUrl
+
+from fastmcp.server.auth import RemoteAuthProvider, TokenVerifier
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class KeycloakAuthProvider(RemoteAuthProvider):
+    """Keycloak authentication provider using Dynamic Client Registration (DCR).
+
+    Requires Keycloak 26.6.0 or later, which includes the fix for DCR compatibility
+    with MCP clients (https://github.com/keycloak/keycloak/pull/45309).
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth.providers.keycloak import KeycloakAuthProvider
+
+        auth = KeycloakAuthProvider(
+            realm_url="https://keycloak.example.com/realms/myrealm",
+            base_url="https://my-mcp-server.example.com",
+        )
+
+        mcp = FastMCP("My App", auth=auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        realm_url: AnyHttpUrl | str,
+        base_url: AnyHttpUrl | str,
+        required_scopes: list[str] | str | None = None,
+        audience: str | list[str] | None = None,
+        token_verifier: TokenVerifier | None = None,
+    ):
+        """Initialize the Keycloak auth provider.
+
+        Args:
+            realm_url: Keycloak realm URL (e.g., "https://keycloak.example.com/realms/myrealm")
+            base_url: Public URL of this FastMCP server
+            required_scopes: Scopes to require on incoming tokens. Defaults to
+                ["openid"], which ensures the `sub` claim (user identifier) is
+                present in the access token. Override to require additional scopes.
+            audience: Optional audience(s) for JWT validation. Recommended for production.
+            token_verifier: Optional custom token verifier. Defaults to a JWTVerifier
+                configured for Keycloak's JWKS endpoint and issuer.
+        """
+        self.realm_url = str(realm_url).rstrip("/")
+        parsed_scopes = (
+            parse_scopes(required_scopes) if required_scopes is not None else ["openid"]
+        )
+
+        if token_verifier is None:
+            token_verifier = JWTVerifier(
+                jwks_uri=f"{self.realm_url}/protocol/openid-connect/certs",
+                issuer=self.realm_url,
+                algorithm="RS256",
+                required_scopes=parsed_scopes,
+                audience=audience,
+            )
+
+        super().__init__(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl(self.realm_url)],
+            base_url=AnyHttpUrl(str(base_url).rstrip("/")),
+        )
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/oci.py b/fastmcp_slim/fastmcp/server/auth/providers/oci.py
new file mode 100644
index 0000000..f5fb8be
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/oci.py
@@ -0,0 +1,213 @@
+"""OCI OIDC provider for FastMCP.
+
+The pull request for the provider is submitted to fastmcp.
+
+This module provides OIDC Implementation to integrate MCP servers with OCI.
+You only need OCI Identity Domain's discovery URL, client ID, client secret, and base URL.
+
+Post Authentication, you get OCI IAM domain access token. That is not authorized to invoke OCI control plane.
+You need to exchange the IAM domain access token for OCI UPST token to invoke OCI control plane APIs.
+The sample code below has get_oci_signer function that returns OCI TokenExchangeSigner object.
+You can use the signer object to create OCI service object.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth.providers.oci import OCIProvider
+    from fastmcp.server.dependencies import get_access_token
+    from fastmcp.utilities.logging import get_logger
+
+    import os
+
+    import oci
+    from oci.auth.signers import TokenExchangeSigner
+
+    logger = get_logger(__name__)
+
+    # Load configuration from environment
+    config_url = os.environ.get("OCI_CONFIG_URL")  # OCI IAM Domain OIDC discovery URL
+    client_id = os.environ.get("OCI_CLIENT_ID")  # Client ID configured for the OCI IAM Domain Integrated Application
+    client_secret = os.environ.get("OCI_CLIENT_SECRET")  # Client secret configured for the OCI IAM Domain Integrated Application
+    iam_guid = os.environ.get("OCI_IAM_GUID")  # IAM GUID configured for the OCI IAM Domain
+
+    # Simple OCI OIDC protection
+    auth = OCIProvider(
+        config_url=config_url,  # config URL is the OCI IAM Domain OIDC discovery URL
+        client_id=client_id,  # This is same as the client ID configured for the OCI IAM Domain Integrated Application
+        client_secret=client_secret,  # This is same as the client secret configured for the OCI IAM Domain Integrated Application
+        required_scopes=["openid", "profile", "email"],
+        redirect_path="/auth/callback",
+        base_url="http://localhost:8000",
+    )
+
+    # NOTE: For production use, replace this with a thread-safe cache implementation
+    # such as threading.Lock-protected dict or a proper caching library
+    _global_token_cache = {}  # In memory cache for OCI session token signer
+
+    def get_oci_signer() -> TokenExchangeSigner:
+
+        authntoken = get_access_token()
+        tokenID = authntoken.claims.get("jti")
+        token = authntoken.token
+
+        # Check if the signer exists for the token ID in memory cache
+        cached_signer = _global_token_cache.get(tokenID)
+        logger.debug(f"Global cached signer: {cached_signer}")
+        if cached_signer:
+            logger.debug(f"Using globally cached signer for token ID: {tokenID}")
+            return cached_signer
+
+        # If the signer is not yet created for the token then create new OCI signer object
+        logger.debug(f"Creating new signer for token ID: {tokenID}")
+        signer = TokenExchangeSigner(
+            jwt_or_func=token,
+            oci_domain_id=iam_guid.split(".")[0] if iam_guid else None,  # This is same as IAM GUID configured for the OCI IAM Domain
+            client_id=client_id,  # This is same as the client ID configured for the OCI IAM Domain Integrated Application
+            client_secret=client_secret,  # This is same as the client secret configured for the OCI IAM Domain Integrated Application
+        )
+        logger.debug(f"Signer {signer} created for token ID: {tokenID}")
+
+        #Cache the signer object in memory cache
+        _global_token_cache[tokenID] = signer
+        logger.debug(f"Signer cached for token ID: {tokenID}")
+
+        return signer
+
+    mcp = FastMCP("My Protected Server", auth=auth)
+    ```
+"""
+
+from typing import Literal
+
+from key_value.aio.protocols import AsyncKeyValue
+from pydantic import AnyHttpUrl
+
+from fastmcp.server.auth.oidc_proxy import (
+    DEFAULT_OIDC_DISCOVERY_TIMEOUT_SECONDS,
+    OIDCProxy,
+)
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class OCIProvider(OIDCProxy):
+    """An OCI IAM Domain provider implementation for FastMCP.
+
+    This provider is a complete OCI integration that's ready to use with
+    just the configuration URL, client ID, client secret, and base URL.
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth.providers.oci import OCIProvider
+
+        import os
+
+        # Load configuration from environment
+        auth = OCIProvider(
+            config_url=os.environ.get("OCI_CONFIG_URL"),  # OCI IAM Domain OIDC discovery URL
+            client_id=os.environ.get("OCI_CLIENT_ID"),  # Client ID configured for the OCI IAM Domain Integrated Application
+            client_secret=os.environ.get("OCI_CLIENT_SECRET"),  # Client secret configured for the OCI IAM Domain Integrated Application
+            base_url="http://localhost:8000",
+            required_scopes=["openid", "profile", "email"],
+            redirect_path="/auth/callback",
+        )
+
+        mcp = FastMCP("My Protected Server", auth=auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        config_url: AnyHttpUrl | str,
+        client_id: str,
+        client_secret: str,
+        timeout_seconds: int | None = DEFAULT_OIDC_DISCOVERY_TIMEOUT_SECONDS,
+        base_url: AnyHttpUrl | str,
+        resource_base_url: AnyHttpUrl | str | None = None,
+        audience: str | None = None,
+        issuer_url: AnyHttpUrl | str | None = None,
+        required_scopes: list[str] | None = None,
+        redirect_path: str | None = None,
+        allowed_client_redirect_uris: list[str] | None = None,
+        client_storage: AsyncKeyValue | None = None,
+        jwt_signing_key: str | bytes | None = None,
+        require_authorization_consent: bool | Literal["remember", "external"] = True,
+        consent_csp_policy: str | None = None,
+        forward_resource: bool = True,
+        fallback_refresh_token_expiry_seconds: int | None = None,
+        fastmcp_access_token_expiry_seconds: int | None = None,
+        token_expiry_threshold_seconds: int = 0,
+    ) -> None:
+        """Initialize OCI OIDC provider.
+
+        Args:
+            config_url: OCI OIDC Discovery URL
+            client_id: OCI IAM Domain Integrated Application client id
+            client_secret: OCI Integrated Application client secret
+            timeout_seconds: Timeout, in seconds, for the OIDC discovery request
+                made during construction. Defaults to 10 seconds so a slow or
+                unreachable issuer cannot block server startup indefinitely. Pass
+                None to fall back to the HTTP client's own default timeout.
+            base_url: Public URL where OIDC endpoints will be accessible (includes any mount path)
+            resource_base_url: Optional public base URL for the protected resource metadata
+                and token audience. Defaults to ``base_url``.
+            audience: OCI API audience (optional)
+            issuer_url: Issuer URL for OCI IAM Domain metadata. This will override issuer URL from the discovery URL.
+            required_scopes: Required OCI scopes (defaults to ["openid"])
+            redirect_path: Redirect path configured in OCI IAM Domain Integrated Application. The default is "/auth/callback".
+            allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
+            fallback_refresh_token_expiry_seconds: Lifetime for the FastMCP-issued
+                refresh token when the upstream provider omits `refresh_expires_in`
+                (e.g. Cognito, GitHub, many OIDC IdPs). Defaults to 1 year. The upstream
+                refresh remains the source of truth. See `OAuthProxy` for details.
+            fastmcp_access_token_expiry_seconds: Lifetime for the FastMCP-issued access
+                token, decoupling it from the upstream provider's `expires_in`. Defaults
+                to None (mirror the upstream lifetime). Set this for bridges whose
+                upstream issues short-lived access tokens that some MCP clients can't
+                refresh gracefully (e.g. `mcp-remote`). See `OAuthProxy` for details.
+            token_expiry_threshold_seconds: Number of seconds before actual expiry to
+                treat a token as expired, refreshing early to avoid races. Defaults to 0.
+        """
+        # Parse scopes if provided as string
+        oci_required_scopes = (
+            parse_scopes(required_scopes) if required_scopes is not None else ["openid"]
+        )
+
+        super().__init__(
+            config_url=config_url,
+            client_id=client_id,
+            client_secret=client_secret,
+            audience=audience,
+            timeout_seconds=timeout_seconds,
+            base_url=base_url,
+            resource_base_url=resource_base_url,
+            issuer_url=issuer_url,
+            redirect_path=redirect_path,
+            required_scopes=oci_required_scopes,
+            allowed_client_redirect_uris=allowed_client_redirect_uris,
+            client_storage=client_storage,
+            jwt_signing_key=jwt_signing_key,
+            require_authorization_consent=require_authorization_consent,
+            consent_csp_policy=consent_csp_policy,
+            forward_resource=forward_resource,
+            fallback_refresh_token_expiry_seconds=fallback_refresh_token_expiry_seconds,
+            fastmcp_access_token_expiry_seconds=fastmcp_access_token_expiry_seconds,
+            token_expiry_threshold_seconds=token_expiry_threshold_seconds,
+        )
+
+        logger.debug(
+            "Initialized OCI OAuth provider for client %s with scopes: %s",
+            client_id,
+            oci_required_scopes,
+        )
+
+    def _prepare_scopes_for_token_exchange(self, scopes: list[str]) -> list[str]:
+        """Omit scope from the upstream auth-code token exchange."""
+        logger.debug(
+            "Omitting scope from upstream token exchange. Original scopes: %s", scopes
+        )
+        return []
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/propelauth.py b/fastmcp_slim/fastmcp/server/auth/providers/propelauth.py
new file mode 100644
index 0000000..82e55e1
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/propelauth.py
@@ -0,0 +1,234 @@
+"""PropelAuth authentication provider for FastMCP.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth.providers.propelauth import PropelAuthProvider
+
+    auth = PropelAuthProvider(
+        auth_url="https://auth.yourdomain.com",
+        introspection_client_id="your-client-id",
+        introspection_client_secret="your-client-secret",
+        base_url="https://your-fastmcp-server.com",
+        required_scopes=["read:user_data"],
+    )
+
+    mcp = FastMCP("My App", auth=auth)
+    ```
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+import httpx
+from pydantic import AnyHttpUrl, SecretStr
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from fastmcp.server.auth import AccessToken, RemoteAuthProvider
+from fastmcp.server.auth.providers.introspection import IntrospectionTokenVerifier
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class PropelAuthTokenIntrospectionOverrides(TypedDict, total=False):
+    timeout_seconds: int
+    cache_ttl_seconds: int | None
+    max_cache_size: int | None
+    http_client: httpx.AsyncClient | None
+
+
+class PropelAuthProvider(RemoteAuthProvider):
+    """PropelAuth resource server provider using OAuth 2.1 token introspection.
+
+    This provider validates access tokens via PropelAuth's introspection endpoint
+    and forwards authorization server metadata for OAuth discovery.
+
+    Setup:
+        1. Enable MCP authentication in the PropelAuth Dashboard
+        2. Configure scopes on the MCP page
+        3. Select which redirect URIs to enable by picking which clients you support
+        4. Generate introspection credentials (Client ID + Client Secret)
+
+    For detailed setup instructions, see:
+    https://docs.propelauth.com/mcp-authentication/overview
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth.providers.propelauth import PropelAuthProvider
+
+        auth = PropelAuthProvider(
+            auth_url="https://auth.yourdomain.com",
+            introspection_client_id="your-client-id",
+            introspection_client_secret="your-client-secret",
+            base_url="https://your-fastmcp-server.com",
+            required_scopes=["read:user_data"],
+        )
+
+        mcp = FastMCP("My App", auth=auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        auth_url: AnyHttpUrl | str,
+        introspection_client_id: str,
+        introspection_client_secret: str | SecretStr,
+        base_url: AnyHttpUrl | str,
+        required_scopes: list[str] | None = None,
+        scopes_supported: list[str] | None = None,
+        resource_name: str | None = None,
+        resource_documentation: AnyHttpUrl | None = None,
+        resource: AnyHttpUrl | str | None = None,
+        token_introspection_overrides: (
+            PropelAuthTokenIntrospectionOverrides | None
+        ) = None,
+    ):
+        """Initialize PropelAuth provider.
+
+        Args:
+            auth_url: Your PropelAuth Auth URL (from the Backend Integration page)
+            introspection_client_id: Introspection Client ID from the PropelAuth Dashboard
+            introspection_client_secret: Introspection Client Secret from the PropelAuth Dashboard
+            base_url: Public URL of this FastMCP server
+            required_scopes: Optional list of scopes that must be present in tokens
+            scopes_supported: Optional list of scopes to advertise in OAuth metadata.
+                If None, uses required_scopes. Use this when the scopes clients should
+                request differ from the scopes enforced on tokens.
+            resource_name: Optional name for the protected resource metadata.
+            resource_documentation: Optional documentation URL for the protected resource.
+            resource: Optional resource URI (RFC 8707) identifying this MCP server.
+                Use this when multiple MCP servers share the same PropelAuth
+                authorization server (e.g. ``resource="https://api.example.com/mcp"``),
+                so only tokens intended for this MCP server are accepted.
+            token_introspection_overrides: Optional overrides for the underlying
+                IntrospectionTokenVerifier (timeout, caching, http_client)
+        """
+        normalized_auth_url = str(auth_url).rstrip("/")
+        introspection_url = f"{normalized_auth_url}/oauth/2.1/introspect"
+        authorization_server_url = AnyHttpUrl(f"{normalized_auth_url}/oauth/2.1")
+
+        if resource is None:
+            self._resource = None
+            logger.debug(
+                "PropelAuthProvider: no resource configured, audience checking disabled"
+            )
+        else:
+            self._resource = str(resource)
+
+        token_verifier = self._create_token_verifier(
+            introspection_url=introspection_url,
+            client_id=introspection_client_id,
+            client_secret=introspection_client_secret,
+            required_scopes=required_scopes,
+            introspection_overrides=token_introspection_overrides,
+        )
+
+        self._normalized_auth_url = normalized_auth_url
+        super().__init__(
+            token_verifier=token_verifier,
+            authorization_servers=[authorization_server_url],
+            base_url=base_url,
+            scopes_supported=scopes_supported,
+            resource_name=resource_name,
+            resource_documentation=resource_documentation,
+        )
+
+    def get_routes(
+        self,
+        mcp_path: str | None = None,
+    ) -> list[Route]:
+        """Get routes for this provider.
+
+        Includes the standard routes from the RemoteAuthProvider (protected resource metadata routes (RFC 9728)),
+        and creates an authorization server metadata route that forwards to PropelAuth's route
+
+        Args:
+            mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
+                This is used to advertise the resource URL in metadata.
+        """
+        routes = super().get_routes(mcp_path)
+
+        async def oauth_authorization_server_metadata(request):
+            """Forward PropelAuth OAuth authorization server metadata"""
+            try:
+                async with httpx.AsyncClient() as client:
+                    response = await client.get(
+                        f"{self._normalized_auth_url}/.well-known/oauth-authorization-server/oauth/2.1"
+                    )
+                    response.raise_for_status()
+                    metadata = response.json()
+                    return JSONResponse(metadata)
+            except Exception as e:
+                return JSONResponse(
+                    {
+                        "error": "server_error",
+                        "error_description": f"Failed to fetch PropelAuth metadata: {e}",
+                    },
+                    status_code=500,
+                )
+
+        routes.append(
+            Route(
+                "/.well-known/oauth-authorization-server",
+                endpoint=oauth_authorization_server_metadata,
+                methods=["GET"],
+            )
+        )
+
+        return routes
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify token and check the ``aud`` claim against the configured resource."""
+        result = await super().verify_token(token)
+        if result is None or self._resource is None:
+            return result
+
+        aud = result.claims.get("aud")
+        if aud != self._resource:
+            logger.debug(
+                "PropelAuthProvider: token audience %r does not match resource %s",
+                aud,
+                self._resource,
+            )
+            return None
+
+        return result
+
+    def _create_token_verifier(
+        self,
+        introspection_url: str,
+        client_id: str,
+        client_secret: str | SecretStr,
+        required_scopes: list[str] | None,
+        introspection_overrides: PropelAuthTokenIntrospectionOverrides | None,
+    ) -> IntrospectionTokenVerifier:
+        # Being defensive here, check for only the fields we are expecting
+        safe_overrides: PropelAuthTokenIntrospectionOverrides = {}
+        if introspection_overrides is not None:
+            if "timeout_seconds" in introspection_overrides:
+                safe_overrides["timeout_seconds"] = introspection_overrides[
+                    "timeout_seconds"
+                ]
+            if "cache_ttl_seconds" in introspection_overrides:
+                safe_overrides["cache_ttl_seconds"] = introspection_overrides[
+                    "cache_ttl_seconds"
+                ]
+            if "max_cache_size" in introspection_overrides:
+                safe_overrides["max_cache_size"] = introspection_overrides[
+                    "max_cache_size"
+                ]
+            if "http_client" in introspection_overrides:
+                safe_overrides["http_client"] = introspection_overrides["http_client"]
+
+        return IntrospectionTokenVerifier(
+            introspection_url=introspection_url,
+            client_id=client_id,
+            client_secret=client_secret,
+            required_scopes=required_scopes,
+            **safe_overrides,
+        )
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/scalekit.py b/fastmcp_slim/fastmcp/server/auth/providers/scalekit.py
new file mode 100644
index 0000000..ffcacc9
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/scalekit.py
@@ -0,0 +1,212 @@
+"""Scalekit authentication provider for FastMCP.
+
+This module provides ScalekitProvider - a complete authentication solution that integrates
+with Scalekit's OAuth 2.1 and OpenID Connect services, supporting Resource Server
+authentication for seamless MCP client authentication.
+"""
+
+from __future__ import annotations
+
+import httpx
+from pydantic import AnyHttpUrl
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from fastmcp.server.auth import RemoteAuthProvider, TokenVerifier
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class ScalekitProvider(RemoteAuthProvider):
+    """Scalekit resource server provider for OAuth 2.1 authentication.
+
+    This provider implements Scalekit integration using resource server pattern.
+    FastMCP acts as a protected resource server that validates access tokens issued
+    by Scalekit's authorization server.
+
+    IMPORTANT SETUP REQUIREMENTS:
+
+    1. Create an MCP Server in Scalekit Dashboard:
+       - Go to your [Scalekit Dashboard](https://app.scalekit.com/)
+       - Navigate to MCP Servers section
+       - Register a new MCP Server with appropriate scopes
+       - Ensure the Resource Identifier matches exactly what you configure as MCP URL
+       - Note the Resource ID
+
+    2. Environment Configuration:
+       - Set SCALEKIT_ENVIRONMENT_URL (e.g., https://your-env.scalekit.com)
+       - Set SCALEKIT_RESOURCE_ID from your created resource
+       - Set BASE_URL to your FastMCP server's public URL
+
+    For detailed setup instructions, see:
+    https://docs.scalekit.com/mcp/overview/
+
+    Example:
+        ```python
+        from fastmcp.server.auth.providers.scalekit import ScalekitProvider
+
+        # Create Scalekit resource server provider
+        scalekit_auth = ScalekitProvider(
+            environment_url="https://your-env.scalekit.com",
+            resource_id="sk_resource_...",
+            base_url="https://your-fastmcp-server.com",
+        )
+
+        # Use with FastMCP
+        mcp = FastMCP("My App", auth=scalekit_auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        environment_url: AnyHttpUrl | str,
+        resource_id: str,
+        base_url: AnyHttpUrl | str | None = None,
+        mcp_url: AnyHttpUrl | str | None = None,
+        client_id: str | None = None,
+        required_scopes: list[str] | None = None,
+        scopes_supported: list[str] | None = None,
+        resource_name: str | None = None,
+        resource_documentation: AnyHttpUrl | None = None,
+        token_verifier: TokenVerifier | None = None,
+    ):
+        """Initialize Scalekit resource server provider.
+
+        Args:
+            environment_url: Your Scalekit environment URL (e.g., "https://your-env.scalekit.com")
+            resource_id: Your Scalekit resource ID
+            base_url: Public URL of this FastMCP server (or use mcp_url for backwards compatibility)
+            mcp_url: Deprecated alias for base_url. Will be removed in a future release.
+            client_id: Deprecated parameter, no longer required. Will be removed in a future release.
+            required_scopes: Optional list of scopes that must be present in tokens
+            scopes_supported: Optional list of scopes to advertise in OAuth metadata.
+                If None, uses required_scopes. Use this when the scopes clients should
+                request differ from the scopes enforced on tokens.
+            resource_name: Optional name for the protected resource metadata.
+            resource_documentation: Optional documentation URL for the protected resource.
+            token_verifier: Optional token verifier. If None, creates JWT verifier for Scalekit
+        """
+        # Resolve base_url from mcp_url if needed (backwards compatibility)
+        resolved_base_url = base_url or mcp_url
+        if not resolved_base_url:
+            raise ValueError("Either base_url or mcp_url must be provided")
+
+        if mcp_url is not None:
+            logger.warning(
+                "ScalekitProvider parameter 'mcp_url' is deprecated and will be removed in a future release. "
+                "Rename it to 'base_url'."
+            )
+
+        if client_id is not None:
+            logger.warning(
+                "ScalekitProvider no longer requires 'client_id'. The parameter is accepted only for backward "
+                "compatibility and will be removed in a future release."
+            )
+
+        self.environment_url = str(environment_url).rstrip("/")
+        self.resource_id = resource_id
+        parsed_scopes = (
+            parse_scopes(required_scopes) if required_scopes is not None else []
+        )
+        self.required_scopes = parsed_scopes
+        base_url_value = str(resolved_base_url)
+
+        logger.debug(
+            "Initializing ScalekitProvider: environment_url=%s resource_id=%s base_url=%s required_scopes=%s",
+            self.environment_url,
+            self.resource_id,
+            base_url_value,
+            self.required_scopes,
+        )
+
+        # Create default JWT verifier if none provided
+        if token_verifier is None:
+            logger.debug(
+                "Creating default JWTVerifier for Scalekit: jwks_uri=%s issuer=%s required_scopes=%s",
+                f"{self.environment_url}/keys",
+                self.environment_url,
+                self.required_scopes,
+            )
+            token_verifier = JWTVerifier(
+                jwks_uri=f"{self.environment_url}/keys",
+                issuer=self.environment_url,
+                algorithm="RS256",
+                audience=self.resource_id,
+                required_scopes=self.required_scopes or None,
+            )
+        else:
+            logger.debug("Using custom token verifier for ScalekitProvider")
+
+        # Initialize RemoteAuthProvider with Scalekit as the authorization server
+        super().__init__(
+            token_verifier=token_verifier,
+            authorization_servers=[
+                AnyHttpUrl(f"{self.environment_url}/resources/{self.resource_id}")
+            ],
+            base_url=base_url_value,
+            scopes_supported=scopes_supported,
+            resource_name=resource_name,
+            resource_documentation=resource_documentation,
+        )
+
+    def get_routes(
+        self,
+        mcp_path: str | None = None,
+    ) -> list[Route]:
+        """Get OAuth routes including Scalekit authorization server metadata forwarding.
+
+        This returns the standard protected resource routes plus an authorization server
+        metadata endpoint that forwards Scalekit's OAuth metadata to clients.
+
+        Args:
+            mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
+                This is used to advertise the resource URL in metadata.
+        """
+        # Get the standard protected resource routes from RemoteAuthProvider
+        routes = super().get_routes(mcp_path)
+        logger.debug(
+            "Preparing Scalekit metadata routes: mcp_path=%s resource_id=%s",
+            mcp_path,
+            self.resource_id,
+        )
+
+        async def oauth_authorization_server_metadata(request):
+            """Forward Scalekit OAuth authorization server metadata with FastMCP customizations."""
+            try:
+                metadata_url = f"{self.environment_url}/.well-known/oauth-authorization-server/resources/{self.resource_id}"
+                logger.debug(
+                    "Fetching Scalekit OAuth metadata: metadata_url=%s", metadata_url
+                )
+                async with httpx.AsyncClient() as client:
+                    response = await client.get(metadata_url)
+                    response.raise_for_status()
+                    metadata = response.json()
+                    logger.debug(
+                        "Scalekit metadata fetched successfully: metadata_keys=%s",
+                        list(metadata.keys()),
+                    )
+                    return JSONResponse(metadata)
+            except Exception as e:
+                logger.error(f"Failed to fetch Scalekit metadata: {e}")
+                return JSONResponse(
+                    {
+                        "error": "server_error",
+                        "error_description": f"Failed to fetch Scalekit metadata: {e}",
+                    },
+                    status_code=500,
+                )
+
+        # Add Scalekit authorization server metadata forwarding
+        routes.append(
+            Route(
+                "/.well-known/oauth-authorization-server",
+                endpoint=oauth_authorization_server_metadata,
+                methods=["GET"],
+            )
+        )
+
+        return routes
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/supabase.py b/fastmcp_slim/fastmcp/server/auth/providers/supabase.py
new file mode 100644
index 0000000..527d701
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/supabase.py
@@ -0,0 +1,181 @@
+"""Supabase authentication provider for FastMCP.
+
+This module provides SupabaseProvider - a complete authentication solution that integrates
+with Supabase Auth's JWT verification, supporting Dynamic Client Registration (DCR)
+for seamless MCP client authentication.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import httpx
+from pydantic import AnyHttpUrl
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from fastmcp.server.auth import RemoteAuthProvider, TokenVerifier
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class SupabaseProvider(RemoteAuthProvider):
+    """Supabase metadata provider for DCR (Dynamic Client Registration).
+
+    This provider implements Supabase Auth integration using metadata forwarding.
+    This approach allows Supabase to handle the OAuth flow directly while FastMCP acts
+    as a resource server, verifying JWTs issued by Supabase Auth.
+
+    IMPORTANT SETUP REQUIREMENTS:
+
+    1. Supabase Project Setup:
+       - Create a Supabase project at https://supabase.com
+       - Note your project URL (e.g., "https://abc123.supabase.co")
+       - Configure your JWT algorithm in Supabase Auth settings (RS256 or ES256)
+       - Asymmetric keys (RS256/ES256) are recommended for production
+
+    2. JWT Verification:
+       - FastMCP verifies JWTs using the JWKS endpoint at {project_url}{auth_route}/.well-known/jwks.json
+       - JWTs are issued by {project_url}{auth_route}
+       - Default auth_route is "/auth/v1" (can be customized for self-hosted setups)
+       - Tokens are cached for up to 10 minutes by Supabase's edge servers
+       - Algorithm must match your Supabase Auth configuration
+
+    3. Authorization:
+       - Supabase uses Row Level Security (RLS) policies for database authorization
+       - OAuth-level scopes are an upcoming feature in Supabase Auth
+       - Both approaches will be supported once scope handling is available
+
+    For detailed setup instructions, see:
+    https://supabase.com/docs/guides/auth/jwts
+
+    Example:
+        ```python
+        from fastmcp.server.auth.providers.supabase import SupabaseProvider
+
+        # Create Supabase metadata provider (JWT verifier created automatically)
+        supabase_auth = SupabaseProvider(
+            project_url="https://abc123.supabase.co",
+            base_url="https://your-fastmcp-server.com",
+            algorithm="ES256",  # Match your Supabase Auth configuration
+        )
+
+        # Use with FastMCP
+        mcp = FastMCP("My App", auth=supabase_auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        project_url: AnyHttpUrl | str,
+        base_url: AnyHttpUrl | str,
+        auth_route: str = "/auth/v1",
+        algorithm: Literal["RS256", "ES256"] = "ES256",
+        required_scopes: list[str] | None = None,
+        scopes_supported: list[str] | None = None,
+        resource_name: str | None = None,
+        resource_documentation: AnyHttpUrl | None = None,
+        token_verifier: TokenVerifier | None = None,
+    ):
+        """Initialize Supabase metadata provider.
+
+        Args:
+            project_url: Your Supabase project URL (e.g., "https://abc123.supabase.co")
+            base_url: Public URL of this FastMCP server
+            auth_route: Supabase Auth route. Defaults to "/auth/v1". Can be customized
+                for self-hosted Supabase Auth setups using custom routes.
+            algorithm: JWT signing algorithm (RS256 or ES256). Must match your
+                Supabase Auth configuration. Defaults to ES256.
+            required_scopes: Optional list of scopes to require for all requests.
+                Note: Supabase currently uses RLS policies for authorization. OAuth-level
+                scopes are an upcoming feature.
+            scopes_supported: Optional list of scopes to advertise in OAuth metadata.
+                If None, uses required_scopes. Use this when the scopes clients should
+                request differ from the scopes enforced on tokens.
+            resource_name: Optional name for the protected resource metadata.
+            resource_documentation: Optional documentation URL for the protected resource.
+            token_verifier: Optional token verifier. If None, creates JWT verifier for Supabase
+        """
+        self.project_url = str(project_url).rstrip("/")
+        self.base_url = AnyHttpUrl(str(base_url).rstrip("/"))
+        self.auth_route = auth_route.strip("/")
+
+        # Parse scopes if provided as string
+        parsed_scopes = (
+            parse_scopes(required_scopes) if required_scopes is not None else None
+        )
+
+        # Create default JWT verifier if none provided
+        if token_verifier is None:
+            logger.warning(
+                "SupabaseProvider cannot validate token audience for the specific resource "
+                "because Supabase Auth does not support RFC 8707 resource indicators. "
+                "This may leave the server vulnerable to cross-server token replay."
+            )
+            token_verifier = JWTVerifier(
+                jwks_uri=f"{self.project_url}/{self.auth_route}/.well-known/jwks.json",
+                issuer=f"{self.project_url}/{self.auth_route}",
+                algorithm=algorithm,
+                audience="authenticated",
+                required_scopes=parsed_scopes,
+            )
+
+        # Initialize RemoteAuthProvider with Supabase as the authorization server
+        super().__init__(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl(f"{self.project_url}/{self.auth_route}")],
+            base_url=self.base_url,
+            scopes_supported=scopes_supported,
+            resource_name=resource_name,
+            resource_documentation=resource_documentation,
+        )
+
+    def get_routes(
+        self,
+        mcp_path: str | None = None,
+    ) -> list[Route]:
+        """Get OAuth routes including Supabase authorization server metadata forwarding.
+
+        This returns the standard protected resource routes plus an authorization server
+        metadata endpoint that forwards Supabase's OAuth metadata to clients.
+
+        Args:
+            mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
+                This is used to advertise the resource URL in metadata.
+        """
+        # Get the standard protected resource routes from RemoteAuthProvider
+        routes = super().get_routes(mcp_path)
+
+        async def oauth_authorization_server_metadata(request):
+            """Forward Supabase OAuth authorization server metadata with FastMCP customizations."""
+            try:
+                async with httpx.AsyncClient() as client:
+                    response = await client.get(
+                        f"{self.project_url}/{self.auth_route}/.well-known/oauth-authorization-server"
+                    )
+                    response.raise_for_status()
+                    metadata = response.json()
+                    return JSONResponse(metadata)
+            except Exception as e:
+                return JSONResponse(
+                    {
+                        "error": "server_error",
+                        "error_description": f"Failed to fetch Supabase metadata: {e}",
+                    },
+                    status_code=500,
+                )
+
+        # Add Supabase authorization server metadata forwarding
+        routes.append(
+            Route(
+                "/.well-known/oauth-authorization-server",
+                endpoint=oauth_authorization_server_metadata,
+                methods=["GET"],
+            )
+        )
+
+        return routes
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/workos.py b/fastmcp_slim/fastmcp/server/auth/providers/workos.py
new file mode 100644
index 0000000..0a3f556
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/providers/workos.py
@@ -0,0 +1,460 @@
+"""WorkOS authentication providers for FastMCP.
+
+This module provides two WorkOS authentication strategies:
+
+1. WorkOSProvider - OAuth proxy for WorkOS Connect applications (non-DCR)
+2. AuthKitProvider - DCR-compliant provider for WorkOS AuthKit
+
+Choose based on your WorkOS setup and authentication requirements.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from typing import Literal
+
+import httpx
+from key_value.aio.protocols import AsyncKeyValue
+from pydantic import AnyHttpUrl
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from fastmcp.server.auth import AccessToken, RemoteAuthProvider, TokenVerifier
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class WorkOSTokenVerifier(TokenVerifier):
+    """Token verifier for WorkOS OAuth tokens.
+
+    WorkOS AuthKit tokens are opaque, so we verify them by calling
+    the /oauth2/userinfo endpoint to check validity and get user info.
+    """
+
+    def __init__(
+        self,
+        *,
+        authkit_domain: str,
+        required_scopes: list[str] | None = None,
+        timeout_seconds: int = 10,
+        http_client: httpx.AsyncClient | None = None,
+    ):
+        """Initialize the WorkOS token verifier.
+
+        Args:
+            authkit_domain: WorkOS AuthKit domain (e.g., "https://your-app.authkit.app")
+            required_scopes: Required OAuth scopes
+            timeout_seconds: HTTP request timeout
+            http_client: Optional httpx.AsyncClient for connection pooling. When provided,
+                the client is reused across calls and the caller is responsible for its
+                lifecycle. When None (default), a fresh client is created per call.
+        """
+        super().__init__(required_scopes=required_scopes)
+        self.authkit_domain = authkit_domain.rstrip("/")
+        self.timeout_seconds = timeout_seconds
+        self._http_client = http_client
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify WorkOS OAuth token by calling userinfo endpoint."""
+        try:
+            async with (
+                contextlib.nullcontext(self._http_client)
+                if self._http_client is not None
+                else httpx.AsyncClient(timeout=self.timeout_seconds)
+            ) as client:
+                # Use WorkOS AuthKit userinfo endpoint to validate token
+                response = await client.get(
+                    f"{self.authkit_domain}/oauth2/userinfo",
+                    headers={
+                        "Authorization": f"Bearer {token}",
+                        "User-Agent": "FastMCP-WorkOS-OAuth",
+                    },
+                )
+
+                if response.status_code != 200:
+                    logger.debug(
+                        "WorkOS token verification failed: %d - %s",
+                        response.status_code,
+                        response.text[:200],
+                    )
+                    return None
+
+                user_data = response.json()
+                token_scopes = (
+                    parse_scopes(user_data.get("scope") or user_data.get("scopes"))
+                    or []
+                )
+
+                if self.required_scopes and not all(
+                    scope in token_scopes for scope in self.required_scopes
+                ):
+                    logger.debug(
+                        "WorkOS token missing required scopes. required=%s actual=%s",
+                        self.required_scopes,
+                        token_scopes,
+                    )
+                    return None
+
+                # Create AccessToken with WorkOS user info
+                return AccessToken(
+                    token=token,
+                    client_id=str(user_data.get("sub", "unknown")),
+                    scopes=token_scopes,
+                    expires_at=None,  # Will be set from token introspection if needed
+                    claims={
+                        "sub": user_data.get("sub"),
+                        "email": user_data.get("email"),
+                        "email_verified": user_data.get("email_verified"),
+                        "name": user_data.get("name"),
+                        "given_name": user_data.get("given_name"),
+                        "family_name": user_data.get("family_name"),
+                    },
+                )
+
+        except httpx.RequestError as e:
+            logger.debug("Failed to verify WorkOS token: %s", e)
+            return None
+        except Exception as e:
+            logger.debug("WorkOS token verification error: %s", e)
+            return None
+
+
+class WorkOSProvider(OAuthProxy):
+    """Complete WorkOS OAuth provider for FastMCP.
+
+    This provider implements WorkOS AuthKit OAuth using the OAuth Proxy pattern.
+    It provides OAuth2 authentication for users through WorkOS Connect applications.
+
+    Features:
+    - Transparent OAuth proxy to WorkOS AuthKit
+    - Automatic token validation via userinfo endpoint
+    - User information extraction from ID tokens
+    - Support for standard OAuth scopes (openid, profile, email)
+
+    Setup Requirements:
+    1. Create a WorkOS Connect application in your dashboard
+    2. Note your AuthKit domain (e.g., "https://your-app.authkit.app")
+    3. Configure redirect URI as: http://localhost:8000/auth/callback
+    4. Note your Client ID and Client Secret
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth.providers.workos import WorkOSProvider
+
+        auth = WorkOSProvider(
+            client_id="client_123",
+            client_secret="sk_test_456",
+            authkit_domain="https://your-app.authkit.app",
+            base_url="http://localhost:8000"
+        )
+
+        mcp = FastMCP("My App", auth=auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        client_id: str,
+        client_secret: str,
+        authkit_domain: str,
+        base_url: AnyHttpUrl | str,
+        resource_base_url: AnyHttpUrl | str | None = None,
+        issuer_url: AnyHttpUrl | str | None = None,
+        redirect_path: str | None = None,
+        required_scopes: list[str] | None = None,
+        valid_scopes: list[str] | None = None,
+        timeout_seconds: int = 10,
+        allowed_client_redirect_uris: list[str] | None = None,
+        client_storage: AsyncKeyValue | None = None,
+        jwt_signing_key: str | bytes | None = None,
+        require_authorization_consent: bool | Literal["remember", "external"] = True,
+        consent_csp_policy: str | None = None,
+        forward_resource: bool = True,
+        fallback_refresh_token_expiry_seconds: int | None = None,
+        fastmcp_access_token_expiry_seconds: int | None = None,
+        token_expiry_threshold_seconds: int = 0,
+        extra_authorize_params: dict[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        enable_cimd: bool = True,
+    ):
+        """Initialize WorkOS OAuth provider.
+
+        Args:
+            client_id: WorkOS client ID
+            client_secret: WorkOS client secret
+            authkit_domain: Your WorkOS AuthKit domain (e.g., "https://your-app.authkit.app")
+            base_url: Public URL where OAuth endpoints will be accessible (includes any mount path)
+            resource_base_url: Optional public base URL for the protected resource metadata
+                and token audience. Defaults to ``base_url``.
+            issuer_url: Issuer URL for OAuth metadata (defaults to base_url). Use root-level URL
+                to avoid 404s during discovery when mounting under a path.
+            redirect_path: Redirect path configured in WorkOS (defaults to "/auth/callback")
+            required_scopes: Required OAuth scopes (no default)
+            valid_scopes: All scopes that clients are allowed to request, advertised through
+                well-known endpoints. Defaults to required_scopes if not provided. Use this
+                when you want clients to be able to request additional scopes beyond the
+                required minimum.
+            timeout_seconds: HTTP request timeout for WorkOS API calls (defaults to 10)
+            allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
+                If None (default), all URIs are allowed. If empty list, no URIs are allowed.
+            client_storage: Storage backend for OAuth state (client registrations, encrypted tokens).
+                If None, an encrypted file store will be created in the data directory
+                (derived from `platformdirs`).
+            jwt_signing_key: Secret for signing FastMCP JWT tokens (any string or bytes). If bytes are provided,
+                they will be used as is. If a string is provided, it will be derived into a 32-byte key. If not
+                provided, the upstream client secret will be used to derive a 32-byte key using PBKDF2.
+            require_authorization_consent: Whether to require user consent before authorizing clients (default True).
+                When True, users see a consent screen before being redirected to WorkOS.
+                When False, authorization proceeds directly without user confirmation.
+                When "external", the built-in consent screen is skipped but no warning is
+                logged, indicating that consent is handled externally (e.g. by the upstream IdP).
+                SECURITY WARNING: Only set to False for local development or testing environments.
+            extra_authorize_params: Additional parameters to forward to WorkOS's authorization endpoint.
+                Useful for forcing scopes like `offline_access` so WorkOS issues a refresh token,
+                e.g. ``{"scope": "openid profile email offline_access"}``.
+            fallback_refresh_token_expiry_seconds: Lifetime for the FastMCP-issued
+                refresh token when the upstream provider omits `refresh_expires_in`
+                (e.g. Cognito, GitHub, many OIDC IdPs). Defaults to 1 year. The upstream
+                refresh remains the source of truth. See `OAuthProxy` for details.
+            fastmcp_access_token_expiry_seconds: Lifetime for the FastMCP-issued access
+                token, decoupling it from the upstream provider's `expires_in`. Defaults
+                to None (mirror the upstream lifetime). Set this for bridges whose
+                upstream issues short-lived access tokens that some MCP clients can't
+                refresh gracefully (e.g. `mcp-remote`). See `OAuthProxy` for details.
+            token_expiry_threshold_seconds: Number of seconds before actual expiry to consider
+                a token as expired (default 0). Prevents race conditions where a token
+                passes the expiry check but expires before the next operation completes.
+            http_client: Optional httpx.AsyncClient for connection pooling in token verification.
+                When provided, the client is reused across verify_token calls and the caller
+                is responsible for its lifecycle. When None (default), a fresh client is created per call.
+            enable_cimd: Enable CIMD (Client ID Metadata Document) support for URL-based
+                client IDs (default True). Set to False to disable.
+        """
+        # Apply defaults and ensure authkit_domain is a full URL
+        authkit_domain_str = authkit_domain
+        if not authkit_domain_str.startswith(("http://", "https://")):
+            authkit_domain_str = f"https://{authkit_domain_str}"
+        authkit_domain_final = authkit_domain_str.rstrip("/")
+        scopes_final = (
+            parse_scopes(required_scopes) if required_scopes is not None else []
+        )
+        valid_scopes_final = (
+            parse_scopes(valid_scopes) if valid_scopes is not None else None
+        )
+
+        # Create WorkOS token verifier
+        token_verifier = WorkOSTokenVerifier(
+            authkit_domain=authkit_domain_final,
+            required_scopes=scopes_final,
+            timeout_seconds=timeout_seconds,
+            http_client=http_client,
+        )
+
+        # Initialize OAuth proxy with WorkOS AuthKit endpoints
+        super().__init__(
+            upstream_authorization_endpoint=f"{authkit_domain_final}/oauth2/authorize",
+            upstream_token_endpoint=f"{authkit_domain_final}/oauth2/token",
+            upstream_client_id=client_id,
+            upstream_client_secret=client_secret,
+            token_verifier=token_verifier,
+            base_url=base_url,
+            resource_base_url=resource_base_url,
+            redirect_path=redirect_path,
+            issuer_url=issuer_url or base_url,  # Default to base_url if not specified
+            allowed_client_redirect_uris=allowed_client_redirect_uris,
+            client_storage=client_storage,
+            jwt_signing_key=jwt_signing_key,
+            require_authorization_consent=require_authorization_consent,
+            consent_csp_policy=consent_csp_policy,
+            forward_resource=forward_resource,
+            fallback_refresh_token_expiry_seconds=fallback_refresh_token_expiry_seconds,
+            fastmcp_access_token_expiry_seconds=fastmcp_access_token_expiry_seconds,
+            token_expiry_threshold_seconds=token_expiry_threshold_seconds,
+            extra_authorize_params=extra_authorize_params,
+            valid_scopes=valid_scopes_final,
+            enable_cimd=enable_cimd,
+        )
+
+        logger.debug(
+            "Initialized WorkOS OAuth provider for client %s with AuthKit domain %s",
+            client_id,
+            authkit_domain_final,
+        )
+
+
+class AuthKitProvider(RemoteAuthProvider):
+    """AuthKit metadata provider for DCR (Dynamic Client Registration).
+
+    This provider implements AuthKit integration using metadata forwarding
+    instead of OAuth proxying. This is the recommended approach for WorkOS DCR
+    as it allows WorkOS to handle the OAuth flow directly while FastMCP acts
+    as a resource server.
+
+    IMPORTANT SETUP REQUIREMENTS:
+
+    1. Enable Dynamic Client Registration in WorkOS Dashboard:
+       - Go to Applications → Configuration
+       - Toggle "Dynamic Client Registration" to enabled
+
+    2. Configure your FastMCP server URL as a callback:
+       - Add your server URL to the Redirects tab in WorkOS dashboard
+       - Example: https://your-fastmcp-server.com/oauth2/callback
+
+    For detailed setup instructions, see:
+    https://workos.com/docs/authkit/mcp/integrating/token-verification
+
+    Token audience is bound to this server automatically: when the MCP
+    mount path becomes known (typically at ``http_app()`` construction),
+    ``JWTVerifier.audience`` is set to the resource URL advertised in
+    ``.well-known/oauth-protected-resource``. Enable Resource Indicators
+    (RFC 8707) in your WorkOS Dashboard and list that same URL — AuthKit
+    will then mint tokens with the matching ``aud`` claim.
+
+    Example:
+        ```python
+        from fastmcp.server.auth.providers.workos import AuthKitProvider
+
+        workos_auth = AuthKitProvider(
+            authkit_domain="https://your-workos-domain.authkit.app",
+            base_url="https://your-fastmcp-server.com",
+        )
+
+        mcp = FastMCP("My App", auth=workos_auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        authkit_domain: AnyHttpUrl | str,
+        base_url: AnyHttpUrl | str,
+        resource_base_url: AnyHttpUrl | str | None = None,
+        required_scopes: list[str] | None = None,
+        scopes_supported: list[str] | None = None,
+        resource_name: str | None = None,
+        resource_documentation: AnyHttpUrl | None = None,
+        token_verifier: TokenVerifier | None = None,
+    ):
+        """Initialize AuthKit metadata provider.
+
+        Args:
+            authkit_domain: Your AuthKit domain (e.g., "https://your-app.authkit.app")
+            base_url: Public URL of this FastMCP server
+            resource_base_url: Optional public base URL for the protected resource.
+                When provided, this URL is advertised in protected resource metadata
+                instead of ``base_url``. Useful when OAuth callbacks and the protected
+                MCP resource live under different public URLs.
+            required_scopes: Optional list of scopes to require for all requests
+            scopes_supported: Optional list of scopes to advertise in OAuth metadata.
+                If None, uses required_scopes. Use this when the scopes clients should
+                request differ from the scopes enforced on tokens.
+            resource_name: Optional name for the protected resource metadata.
+            resource_documentation: Optional documentation URL for the protected resource.
+            token_verifier: Optional token verifier. If provided, it is used as-is and
+                audience auto-wiring is skipped — the caller is responsible for setting
+                an appropriate ``audience``. If None (default), a ``JWTVerifier`` is
+                created with audience bound to this server's resource URL.
+        """
+        self.authkit_domain = str(authkit_domain).rstrip("/")
+        self.base_url = AnyHttpUrl(str(base_url).rstrip("/"))
+
+        # Parse scopes if provided as string
+        parsed_scopes = (
+            parse_scopes(required_scopes) if required_scopes is not None else None
+        )
+
+        # When no custom verifier is provided, we own the JWTVerifier and can
+        # bind its audience to our resource URL once set_mcp_path() is called.
+        self._auto_bind_audience = token_verifier is None
+        if token_verifier is None:
+            token_verifier = JWTVerifier(
+                jwks_uri=f"{self.authkit_domain}/oauth2/jwks",
+                issuer=self.authkit_domain,
+                algorithm="RS256",
+                required_scopes=parsed_scopes,
+            )
+
+        # Initialize RemoteAuthProvider with AuthKit as the authorization server
+        super().__init__(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl(self.authkit_domain)],
+            base_url=self.base_url,
+            resource_base_url=resource_base_url,
+            scopes_supported=scopes_supported,
+            resource_name=resource_name,
+            resource_documentation=resource_documentation,
+        )
+
+    def set_mcp_path(self, mcp_path: str | None) -> None:
+        """Bind the default verifier's audience to this server's resource URL.
+
+        AuthKit with Resource Indicators (RFC 8707) mints tokens whose ``aud``
+        claim equals the resource URL the client requested — which is the URL
+        we advertise in ``.well-known/oauth-protected-resource``. Binding the
+        audience here keeps validation in lock-step with what clients are sent.
+        """
+        super().set_mcp_path(mcp_path)
+        if (
+            self._auto_bind_audience
+            and self._resource_url is not None
+            and isinstance(self.token_verifier, JWTVerifier)
+        ):
+            resource_url = str(self._resource_url)
+            self.token_verifier.audience = resource_url
+            logger.info(
+                "AuthKit tokens will be validated against aud=%s. "
+                "Configure this URL as a Resource Indicator in the WorkOS Dashboard.",
+                resource_url,
+            )
+
+    def get_routes(
+        self,
+        mcp_path: str | None = None,
+    ) -> list[Route]:
+        """Get OAuth routes including AuthKit authorization server metadata forwarding.
+
+        This returns the standard protected resource routes plus an authorization server
+        metadata endpoint that forwards AuthKit's OAuth metadata to clients.
+
+        Args:
+            mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
+                This is used to advertise the resource URL in metadata.
+        """
+        # Get the standard protected resource routes from RemoteAuthProvider
+        routes = super().get_routes(mcp_path)
+
+        async def oauth_authorization_server_metadata(request):
+            """Forward AuthKit OAuth authorization server metadata with FastMCP customizations."""
+            try:
+                async with httpx.AsyncClient() as client:
+                    response = await client.get(
+                        f"{self.authkit_domain}/.well-known/oauth-authorization-server"
+                    )
+                    response.raise_for_status()
+                    metadata = response.json()
+                    return JSONResponse(metadata)
+            except Exception as e:
+                return JSONResponse(
+                    {
+                        "error": "server_error",
+                        "error_description": f"Failed to fetch AuthKit metadata: {e}",
+                    },
+                    status_code=500,
+                )
+
+        # Add AuthKit authorization server metadata forwarding
+        routes.append(
+            Route(
+                "/.well-known/oauth-authorization-server",
+                endpoint=oauth_authorization_server_metadata,
+                methods=["GET"],
+            )
+        )
+
+        return routes
diff --git a/fastmcp_slim/fastmcp/server/auth/redirect_validation.py b/fastmcp_slim/fastmcp/server/auth/redirect_validation.py
new file mode 100644
index 0000000..cdc62cc
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/redirect_validation.py
@@ -0,0 +1,273 @@
+"""Utilities for validating client redirect URIs in OAuth flows.
+
+This module provides secure redirect URI validation with wildcard support,
+protecting against userinfo-based bypass attacks like http://localhost@evil.com.
+"""
+
+import fnmatch
+from urllib.parse import unquote, urlparse
+
+from pydantic import AnyUrl
+
+UNSAFE_REDIRECT_URI_SCHEMES = frozenset(
+    {
+        "javascript",
+        "data",
+        "file",
+        "vbscript",
+    }
+)
+
+
+def _parse_host_port(netloc: str) -> tuple[str | None, str | None]:
+    """Parse host and port from netloc, handling wildcards.
+
+    Args:
+        netloc: The netloc component (e.g., "localhost:8080" or "localhost:*")
+
+    Returns:
+        Tuple of (host, port_str) where port_str may be "*" or a number string
+    """
+    # Handle userinfo (remove it for parsing, but we check separately)
+    if "@" in netloc:
+        netloc = netloc.split("@")[-1]
+
+    # Handle IPv6 addresses [::1]:port
+    if netloc.startswith("["):
+        bracket_end = netloc.find("]")
+        if bracket_end == -1:
+            return netloc, None
+        host = netloc[1:bracket_end]
+        rest = netloc[bracket_end + 1 :]
+        if rest.startswith(":"):
+            return host, rest[1:]
+        return host, None
+
+    # Handle regular host:port
+    if ":" in netloc:
+        host, port = netloc.rsplit(":", 1)
+        return host, port
+
+    return netloc, None
+
+
+def _match_host(uri_host: str | None, pattern_host: str | None) -> bool:
+    """Match host component, supporting *.example.com wildcard patterns.
+
+    Args:
+        uri_host: The host from the URI being validated
+        pattern_host: The host pattern (may start with *.)
+
+    Returns:
+        True if the host matches
+    """
+    if not uri_host or not pattern_host:
+        return uri_host == pattern_host
+
+    # Normalize to lowercase for comparison
+    uri_host = uri_host.lower()
+    pattern_host = pattern_host.lower()
+
+    # Handle *.example.com wildcard subdomain patterns
+    if pattern_host.startswith("*."):
+        suffix = pattern_host[1:]  # .example.com
+        # Only match actual subdomains (foo.example.com), NOT the base domain
+        return uri_host.endswith(suffix) and uri_host != pattern_host[2:]
+
+    return uri_host == pattern_host
+
+
+def _is_loopback_host(host: str | None) -> bool:
+    """Check if a host is a loopback address.
+
+    Per RFC 8252 §7.3, loopback addresses include localhost, 127.0.0.1, and ::1.
+    """
+    if not host:
+        return False
+    host = host.lower()
+    return host in ("localhost", "127.0.0.1", "::1")
+
+
+def _match_port(
+    uri_port: str | None,
+    pattern_port: str | None,
+    uri_scheme: str,
+) -> bool:
+    """Match port component, supporting * wildcard for any port.
+
+    Args:
+        uri_port: The port from the URI (None if default, string otherwise)
+        pattern_port: The port from the pattern (None if default, "*" for wildcard)
+        uri_scheme: The URI scheme (http/https) for default port handling
+
+    Returns:
+        True if the port matches
+    """
+    # Wildcard matches any port
+    if pattern_port == "*":
+        return True
+
+    # Normalize None to default ports
+    default_port = "443" if uri_scheme == "https" else "80"
+    uri_effective = uri_port if uri_port else default_port
+    pattern_effective = pattern_port if pattern_port else default_port
+
+    return uri_effective == pattern_effective
+
+
+def _has_dot_segments(path: str) -> bool:
+    """Return True if a URI path contains `.` or `..` segments.
+
+    Browsers collapse dot-segments when resolving a 302 Location per RFC
+    3986 §5.2.4. Allowing them through the allowlist lets an attacker craft
+    a URI that passes pattern matching but lands on a different path after
+    redirect. Checks both the raw path and its percent-decoded form so that
+    encoded variants like `/foo/%2e%2e/bar` are rejected.
+    """
+    for candidate in (path, unquote(path)):
+        if any(seg in (".", "..") for seg in candidate.split("/")):
+            return True
+    return False
+
+
+def _match_path(uri_path: str, pattern_path: str) -> bool:
+    """Match path component using fnmatch for wildcard support.
+
+    Args:
+        uri_path: The path from the URI
+        pattern_path: The path pattern (may contain * wildcards)
+
+    Returns:
+        True if the path matches
+    """
+    # Normalize empty paths to /
+    uri_path = uri_path or "/"
+    pattern_path = pattern_path or "/"
+
+    # Empty or root pattern path matches any path
+    # This makes http://localhost:* match http://localhost:3000/callback
+    if pattern_path == "/":
+        return True
+
+    # Use fnmatch for path wildcards (e.g., /auth/*)
+    return fnmatch.fnmatch(uri_path, pattern_path)
+
+
+def _is_unsafe_redirect_uri(uri: str) -> bool:
+    try:
+        parsed = urlparse(uri)
+    except ValueError:
+        return True
+
+    return parsed.scheme.lower() in UNSAFE_REDIRECT_URI_SCHEMES
+
+
+def matches_allowed_pattern(uri: str, pattern: str) -> bool:
+    """Securely check if a URI matches an allowed pattern with wildcard support.
+
+    This function parses both the URI and pattern as URLs, comparing each
+    component separately to prevent bypass attacks like userinfo injection.
+
+    Patterns support wildcards:
+    - http://localhost:* matches any localhost port
+    - http://127.0.0.1:* matches any 127.0.0.1 port
+    - https://*.example.com/* matches any subdomain of example.com
+    - https://app.example.com/auth/* matches any path under /auth/
+
+    Security: Rejects URIs with userinfo (user:pass@host) which could bypass
+    naive string matching (e.g., http://localhost@evil.com).
+
+    Args:
+        uri: The redirect URI to validate
+        pattern: The allowed pattern (may contain wildcards)
+
+    Returns:
+        True if the URI matches the pattern
+    """
+    try:
+        uri_parsed = urlparse(uri)
+        pattern_parsed = urlparse(pattern)
+    except ValueError:
+        return False
+
+    if uri_parsed.scheme.lower() in UNSAFE_REDIRECT_URI_SCHEMES:
+        return False
+
+    # SECURITY: Reject URIs with userinfo (user:pass@host)
+    # This prevents bypass attacks like http://localhost@evil.com/callback
+    # which would match http://localhost:* with naive fnmatch
+    if uri_parsed.username is not None or uri_parsed.password is not None:
+        return False
+
+    # SECURITY: Reject URIs with dot-segments in the path.
+    # fnmatch's `*` matches across `/`, so a pattern like `/oauth/callback/*`
+    # would accept `/oauth/callback/../../steal`; a browser receiving that in
+    # a 302 Location resolves the dot-segments and lands at `/steal`, outside
+    # the intended allowlist prefix. Reject at validation time so the stored
+    # redirect_uri cannot later be emitted verbatim in a redirect.
+    if _has_dot_segments(uri_parsed.path):
+        return False
+
+    # Scheme must match exactly
+    if uri_parsed.scheme.lower() != pattern_parsed.scheme.lower():
+        return False
+
+    # Parse host and port manually to handle wildcards
+    uri_host, uri_port = _parse_host_port(uri_parsed.netloc)
+    pattern_host, pattern_port = _parse_host_port(pattern_parsed.netloc)
+
+    # Host must match (with subdomain wildcard support)
+    if not _match_host(uri_host, pattern_host):
+        return False
+
+    # RFC 8252 §7.3: loopback patterns without an explicit port match any port
+    if not (_is_loopback_host(pattern_host) and pattern_port is None):
+        if not _match_port(uri_port, pattern_port, uri_parsed.scheme.lower()):
+            return False
+
+    # Path must match (with fnmatch wildcards)
+    return _match_path(uri_parsed.path, pattern_parsed.path)
+
+
+def validate_redirect_uri(
+    redirect_uri: str | AnyUrl | None,
+    allowed_patterns: list[str] | None,
+) -> bool:
+    """Validate a redirect URI against allowed patterns.
+
+    Args:
+        redirect_uri: The redirect URI to validate
+        allowed_patterns: List of allowed patterns. If None, ordinary URIs are allowed
+                         for DCR compatibility, while unsafe browser schemes are rejected.
+                         If empty list, no URIs are allowed.
+                         To restrict to localhost only, explicitly pass DEFAULT_LOCALHOST_PATTERNS.
+
+    Returns:
+        True if the redirect URI is allowed
+    """
+    if redirect_uri is None:
+        return True  # None is allowed (will use client's default)
+
+    uri_str = str(redirect_uri)
+
+    if _is_unsafe_redirect_uri(uri_str):
+        return False
+
+    # If no patterns specified, preserve broad DCR compatibility after the
+    # unsafe browser-scheme check above.
+    if allowed_patterns is None:
+        return True
+
+    # Check if URI matches any allowed pattern
+    for pattern in allowed_patterns:
+        if matches_allowed_pattern(uri_str, pattern):
+            return True
+
+    return False
+
+
+# Default patterns for localhost-only validation
+DEFAULT_LOCALHOST_PATTERNS = [
+    "http://localhost:*",
+    "http://127.0.0.1:*",
+]
diff --git a/fastmcp_slim/fastmcp/server/auth/ssrf.py b/fastmcp_slim/fastmcp/server/auth/ssrf.py
new file mode 100644
index 0000000..1e24067
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/auth/ssrf.py
@@ -0,0 +1,402 @@
+"""SSRF-safe HTTP utilities for FastMCP.
+
+This module provides SSRF-protected HTTP fetching with:
+- DNS resolution and IP validation before requests
+- DNS pinning to prevent rebinding TOCTOU attacks
+- Support for both CIMD and JWKS fetches
+"""
+
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+import socket
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+import httpx
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+NAT64_PREFIXES: tuple[
+    tuple[ipaddress.IPv6Network, tuple[tuple[int, int, int, int], ...]], ...
+] = (
+    (ipaddress.IPv6Network("64:ff9b::/96"), ((12, 13, 14, 15),)),
+    (
+        ipaddress.IPv6Network("64:ff9b:1::/48"),
+        (
+            (6, 7, 9, 10),
+            (7, 9, 10, 11),
+            (9, 10, 11, 12),
+            (12, 13, 14, 15),
+        ),
+    ),
+)
+LOW32_OFFSETS = (12, 13, 14, 15)
+IPV4_TRANSLATED_PREFIX = ipaddress.IPv6Network("0:0:0:0:ffff:0:0:0/96")
+ISATAP_INTERFACE_IDS = (b"\x00\x00\x5e\xfe", b"\x02\x00\x5e\xfe")
+
+
+def format_ip_for_url(ip_str: str) -> str:
+    """Format IP address for use in URL (bracket IPv6 addresses).
+
+    IPv6 addresses must be bracketed in URLs to distinguish the address from
+    the port separator. For example: https://[2001:db8::1]:443/path
+
+    Args:
+        ip_str: IP address string
+
+    Returns:
+        IP string suitable for URL (IPv6 addresses are bracketed)
+    """
+    try:
+        ip = ipaddress.ip_address(ip_str)
+        if isinstance(ip, ipaddress.IPv6Address):
+            return f"[{ip_str}]"
+        return ip_str
+    except ValueError:
+        return ip_str
+
+
+class SSRFError(Exception):
+    """Raised when an SSRF protection check fails."""
+
+
+class SSRFFetchError(Exception):
+    """Raised when SSRF-safe fetch fails."""
+
+
+def _embedded_ipv4_addresses(
+    ip: ipaddress.IPv6Address,
+) -> set[ipaddress.IPv4Address]:
+    """Return IPv4 addresses embedded in known IPv6 transition forms."""
+    candidates: set[ipaddress.IPv4Address] = set()
+    packed = ip.packed
+
+    def from_offsets(offsets: tuple[int, int, int, int]) -> ipaddress.IPv4Address:
+        return ipaddress.IPv4Address(bytes(packed[i] for i in offsets))
+
+    if ip.ipv4_mapped:
+        candidates.add(ip.ipv4_mapped)
+    if ip.sixtofour:
+        candidates.add(ip.sixtofour)
+    if ip.teredo:
+        server, client = ip.teredo
+        candidates.update((server, client))
+    if ip in IPV4_TRANSLATED_PREFIX:
+        candidates.add(from_offsets(LOW32_OFFSETS))
+
+    for prefix, offset_options in NAT64_PREFIXES:
+        if ip in prefix:
+            candidates.update(from_offsets(offsets) for offsets in offset_options)
+
+    if int(ip) >> 32 == 0 and not ip.is_loopback and not ip.is_unspecified:
+        candidates.add(from_offsets(LOW32_OFFSETS))
+
+    if packed[8:12] in ISATAP_INTERFACE_IDS:
+        candidates.add(from_offsets(LOW32_OFFSETS))
+
+    return candidates
+
+
+def is_ip_allowed(ip_str: str) -> bool:
+    """Check if an IP address is allowed (must be globally routable unicast).
+
+    Uses ip.is_global which catches:
+    - Private (10.x, 172.16-31.x, 192.168.x)
+    - Loopback (127.x, ::1)
+    - Link-local (169.254.x, fe80::) - includes AWS metadata!
+    - Reserved, unspecified
+    - RFC6598 Carrier-Grade NAT (100.64.0.0/10) - can point to internal networks
+    - IPv6 transition forms that embed blocked IPv4 targets
+
+    Additionally blocks multicast addresses (not caught by is_global).
+
+    Args:
+        ip_str: IP address string to check
+
+    Returns:
+        True if the IP is allowed (public unicast internet), False if blocked
+    """
+    try:
+        ip = ipaddress.ip_address(ip_str)
+    except ValueError:
+        return False
+
+    if isinstance(ip, ipaddress.IPv6Address):
+        if any(
+            not is_ip_allowed(str(embedded_ip))
+            for embedded_ip in _embedded_ipv4_addresses(ip)
+        ):
+            return False
+
+    if not ip.is_global:
+        return False
+
+    # Block multicast (not caught by is_global for some ranges)
+    return not ip.is_multicast
+
+
+async def resolve_hostname(hostname: str, port: int = 443) -> list[str]:
+    """Resolve hostname to IP addresses using DNS.
+
+    Args:
+        hostname: Hostname to resolve
+        port: Port number (used for getaddrinfo)
+
+    Returns:
+        List of resolved IP addresses
+
+    Raises:
+        SSRFError: If resolution fails
+    """
+    loop = asyncio.get_running_loop()
+    try:
+        infos = await loop.run_in_executor(
+            None,
+            lambda: socket.getaddrinfo(
+                hostname, port, socket.AF_UNSPEC, socket.SOCK_STREAM
+            ),
+        )
+        ips = list({info[4][0] for info in infos})
+        if not ips:
+            raise SSRFError(f"DNS resolution returned no addresses for {hostname}")
+        return ips  # ty: ignore[invalid-return-type]
+    except socket.gaierror as e:
+        raise SSRFError(f"DNS resolution failed for {hostname}: {e}") from e
+
+
+@dataclass
+class ValidatedURL:
+    """A URL that has been validated for SSRF with resolved IPs."""
+
+    original_url: str
+    hostname: str
+    port: int
+    path: str
+    resolved_ips: list[str]
+
+
+@dataclass
+class SSRFFetchResponse:
+    """Response payload from an SSRF-safe fetch."""
+
+    content: bytes
+    status_code: int
+    headers: dict[str, str]
+
+
+async def validate_url(url: str, require_path: bool = False) -> ValidatedURL:
+    """Validate URL for SSRF and resolve to IPs.
+
+    Args:
+        url: URL to validate
+        require_path: If True, require non-root path (for CIMD)
+
+    Returns:
+        ValidatedURL with resolved IPs
+
+    Raises:
+        SSRFError: If URL is invalid or resolves to blocked IPs
+    """
+    try:
+        parsed = urlparse(url)
+    except (ValueError, AttributeError) as e:
+        raise SSRFError(f"Invalid URL: {e}") from e
+
+    if parsed.scheme != "https":
+        raise SSRFError(f"URL must use HTTPS, got: {parsed.scheme}")
+
+    if not parsed.netloc:
+        raise SSRFError("URL must have a host")
+
+    if require_path and parsed.path in ("", "/"):
+        raise SSRFError("URL must have a non-root path")
+
+    hostname = parsed.hostname or parsed.netloc
+    port = parsed.port or 443
+
+    # Resolve and validate IPs
+    resolved_ips = await resolve_hostname(hostname, port)
+
+    blocked = [ip for ip in resolved_ips if not is_ip_allowed(ip)]
+    if blocked:
+        raise SSRFError(
+            f"URL resolves to blocked IP address(es): {blocked}. "
+            f"Private, loopback, link-local, and reserved IPs are not allowed."
+        )
+
+    return ValidatedURL(
+        original_url=url,
+        hostname=hostname,
+        port=port,
+        path=parsed.path + ("?" + parsed.query if parsed.query else ""),
+        resolved_ips=resolved_ips,
+    )
+
+
+async def ssrf_safe_fetch(
+    url: str,
+    *,
+    require_path: bool = False,
+    max_size: int = 5120,
+    timeout: float = 10.0,
+    overall_timeout: float = 30.0,
+) -> bytes:
+    """Fetch URL with comprehensive SSRF protection and DNS pinning.
+
+    Security measures:
+    1. HTTPS only
+    2. DNS resolution with IP validation
+    3. Connects to validated IP directly (DNS pinning prevents rebinding)
+    4. Response size limit
+    5. Redirects disabled
+    6. Overall timeout
+
+    Args:
+        url: URL to fetch
+        require_path: If True, require non-root path
+        max_size: Maximum response size in bytes (default 5KB)
+        timeout: Per-operation timeout in seconds
+        overall_timeout: Overall timeout for entire operation
+
+    Returns:
+        Response body as bytes
+
+    Raises:
+        SSRFError: If SSRF validation fails
+        SSRFFetchError: If fetch fails
+    """
+    response = await ssrf_safe_fetch_response(
+        url,
+        require_path=require_path,
+        max_size=max_size,
+        timeout=timeout,
+        overall_timeout=overall_timeout,
+        allowed_status_codes={200},
+    )
+    return response.content
+
+
+async def ssrf_safe_fetch_response(
+    url: str,
+    *,
+    require_path: bool = False,
+    max_size: int = 5120,
+    timeout: float = 10.0,
+    overall_timeout: float = 30.0,
+    request_headers: Mapping[str, str] | None = None,
+    allowed_status_codes: set[int] | None = None,
+) -> SSRFFetchResponse:
+    """Fetch URL with SSRF protection and return response metadata.
+
+    This is equivalent to :func:`ssrf_safe_fetch` but returns response headers
+    and status code, and supports conditional request headers.
+    """
+    start_time = time.monotonic()
+
+    # Validate URL and resolve DNS
+    validated = await validate_url(url, require_path=require_path)
+
+    last_error: Exception | None = None
+    expected_statuses = allowed_status_codes or {200}
+
+    for pinned_ip in validated.resolved_ips:
+        elapsed = time.monotonic() - start_time
+        if elapsed > overall_timeout:
+            raise SSRFFetchError(f"Overall timeout exceeded: {url}")
+        remaining = max(1.0, overall_timeout - elapsed)
+
+        pinned_url = (
+            f"https://{format_ip_for_url(pinned_ip)}:{validated.port}{validated.path}"
+        )
+
+        logger.debug(
+            "SSRF-safe fetch: %s -> %s (pinned to %s)",
+            url,
+            pinned_url,
+            pinned_ip,
+        )
+
+        headers = {"Host": validated.hostname}
+        if request_headers:
+            for key, value in request_headers.items():
+                # Host must remain pinned to the validated hostname.
+                if key.lower() == "host":
+                    continue
+                headers[key] = value
+
+        try:
+            # Use httpx with streaming to enforce size limit during download
+            async with (
+                httpx.AsyncClient(
+                    timeout=httpx.Timeout(
+                        connect=min(timeout, remaining),
+                        read=min(timeout, remaining),
+                        write=min(timeout, remaining),
+                        pool=min(timeout, remaining),
+                    ),
+                    follow_redirects=False,
+                    verify=True,
+                ) as client,
+                client.stream(
+                    "GET",
+                    pinned_url,
+                    headers=headers,
+                    extensions={"sni_hostname": validated.hostname},
+                ) as response,
+            ):
+                if time.monotonic() - start_time > overall_timeout:
+                    raise SSRFFetchError(f"Overall timeout exceeded: {url}")
+
+                if response.status_code not in expected_statuses:
+                    raise SSRFFetchError(f"HTTP {response.status_code} fetching {url}")
+
+                # Check Content-Length header first if available
+                content_length = response.headers.get("content-length")
+                if content_length:
+                    try:
+                        size = int(content_length)
+                        if size > max_size:
+                            raise SSRFFetchError(
+                                f"Response too large: {size} bytes (max {max_size})"
+                            )
+                    except ValueError:
+                        pass
+
+                # Stream the response and enforce size limit during download
+                chunks = []
+                total = 0
+                async for chunk in response.aiter_bytes():
+                    if time.monotonic() - start_time > overall_timeout:
+                        raise SSRFFetchError(f"Overall timeout exceeded: {url}")
+                    total += len(chunk)
+                    if total > max_size:
+                        raise SSRFFetchError(
+                            f"Response too large: exceeded {max_size} bytes"
+                        )
+                    chunks.append(chunk)
+
+                return SSRFFetchResponse(
+                    content=b"".join(chunks),
+                    status_code=response.status_code,
+                    headers=dict(response.headers),
+                )
+
+        except httpx.TimeoutException as e:
+            last_error = e
+            continue
+        except httpx.RequestError as e:
+            last_error = e
+            continue
+
+    if last_error is not None:
+        if isinstance(last_error, httpx.TimeoutException):
+            raise SSRFFetchError(f"Timeout fetching {url}") from last_error
+        raise SSRFFetchError(f"Error fetching {url}: {last_error}") from last_error
+
+    raise SSRFFetchError(f"Error fetching {url}: no resolved IPs succeeded")
diff --git a/fastmcp_slim/fastmcp/server/caching.py b/fastmcp_slim/fastmcp/server/caching.py
new file mode 100644
index 0000000..a5ae177
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/caching.py
@@ -0,0 +1,58 @@
+"""Server-level cache hints for FastMCP (SEP-2549).
+
+A FastMCP server opts every SDK-cacheable result it emits into client-side
+caching by setting `cache_ttl` (seconds) and, optionally, `cache_scope` on the
+`FastMCP` constructor. The hint is uniform by construction: one server-level
+value applies to `tools/list`, `prompts/list`, `resources/list`,
+`resources/templates/list`, `resources/read`, and `server/discover` alike — no
+per-component surface and no aggregation.
+
+FastMCP does not hand-set the wire fields. It passes the hint through to the SDK
+low-level `Server(cache_hints=...)`, whose runner fills `ttlMs`/`cacheScope` on
+every cacheable result via `apply_cache_hint`, leaving any field a handler set
+explicitly untouched. Honoring is modern-only and opt-in on the client: a hinted
+server is inert unless the client passes `cache=` and negotiates `2026-07-28`.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, get_args
+
+from mcp.server.caching import CacheHint
+from mcp_types.methods import CacheableMethod
+
+CacheScope = Literal["public", "private"]
+"""Whether a cached result may be shared across authorization contexts
+(`"public"`) or reused only within the one that produced it (`"private"`)."""
+
+
+def build_cache_hints(
+    cache_ttl: int | None,
+    cache_scope: CacheScope | None,
+) -> dict[CacheableMethod, CacheHint] | None:
+    """Build the per-method `CacheHint` map for the SDK low-level server.
+
+    `cache_ttl` is in seconds and is converted to the wire's milliseconds. When
+    `cache_ttl` is `None` the server emits no hint, so its wire output is
+    identical to a server that never set one; a `cache_scope` given without a
+    `cache_ttl` is meaningless (the client gates caching on the presence of a
+    TTL) and is rejected rather than silently ignored.
+
+    Returns `None` when no hint is set, or a map applying the same hint to every
+    SDK-cacheable method otherwise.
+
+    Raises:
+        ValueError: If `cache_ttl` is not positive, or if `cache_scope` is set
+            without `cache_ttl`.
+    """
+    if cache_ttl is None:
+        if cache_scope is not None:
+            raise ValueError(
+                "cache_scope requires cache_ttl; a scope without a TTL does not "
+                "enable caching"
+            )
+        return None
+    if cache_ttl <= 0:
+        raise ValueError(f"cache_ttl must be a positive integer, got {cache_ttl}")
+    hint = CacheHint(ttl_ms=cache_ttl * 1000, scope=cache_scope or "private")
+    return dict.fromkeys(get_args(CacheableMethod), hint)
diff --git a/fastmcp_slim/fastmcp/server/context.py b/fastmcp_slim/fastmcp/server/context.py
new file mode 100644
index 0000000..e2c2f19
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/context.py
@@ -0,0 +1,1616 @@
+from __future__ import annotations
+
+import logging
+import warnings
+import weakref
+from collections.abc import Callable, Generator, Mapping, Sequence
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+from dataclasses import dataclass
+from logging import Logger
+from typing import Any, Literal, cast, overload
+
+import mcp_types
+from mcp import LoggingLevel, ServerSession
+from mcp.server.context import ServerRequestContext
+from mcp_types import (
+    GetPromptResult,
+    ModelPreferences,
+    Root,
+    SamplingMessage,
+)
+from mcp_types import Prompt as SDKPrompt
+from mcp_types import Resource as SDKResource
+from mcp_types.version import MODERN_PROTOCOL_VERSIONS
+from pydantic.networks import AnyUrl
+from typing_extensions import TypeVar
+from uncalled_for import SharedContext
+
+import fastmcp
+from fastmcp.exceptions import FastMCPDeprecationWarning, ToolError
+from fastmcp.resources.base import ResourceResult
+from fastmcp.server.dependencies import FastMCPRequestContext, fastmcp_request_ctx
+from fastmcp.server.elicitation import (
+    AcceptedElicitation,
+    CancelledElicitation,
+    DeclinedElicitation,
+    handle_elicit_accept,
+    parse_elicit_response_type,
+)
+from fastmcp.server.low_level import client_supports_extension
+from fastmcp.server.sampling import SampleStep, SamplingResult, SamplingTool
+from fastmcp.server.sampling.run import (
+    sample_impl,
+    sample_step_impl,
+)
+from fastmcp.server.server import FastMCP, StateValue
+from fastmcp.server.transforms.visibility import (
+    Visibility,
+)
+from fastmcp.server.transforms.visibility import (
+    disable_components as _disable_components,
+)
+from fastmcp.server.transforms.visibility import (
+    enable_components as _enable_components,
+)
+from fastmcp.server.transforms.visibility import (
+    get_session_transforms as _get_session_transforms,
+)
+from fastmcp.server.transforms.visibility import (
+    get_visibility_rules as _get_visibility_rules,
+)
+from fastmcp.server.transforms.visibility import (
+    reset_visibility as _reset_visibility,
+)
+from fastmcp.utilities.logging import _clamp_logger, get_logger
+from fastmcp.utilities.versions import VersionSpec
+
+logger: Logger = get_logger(name=__name__)
+to_client_logger: Logger = logger.getChild(suffix="to_client")
+
+# Convert all levels of server -> client messages to debug level
+# This clamp can be undone at runtime by calling `_unclamp_logger` or calling
+# `_clamp_logger` with a different max level.
+_clamp_logger(logger=to_client_logger, max_level="DEBUG")
+
+
+T = TypeVar("T", default=Any)
+ResultT = TypeVar("ResultT", default=str)
+
+# Import ToolChoiceOption from sampling module (after other imports)
+from fastmcp.server.sampling.run import ToolChoiceOption  # noqa: E402
+
+# Warn-once guard for the sampling deprecation. Server-initiated createMessage
+# was removed from MCP as of 2026-07-28 (SEP-2577); the warning fires a single
+# time per process to flag that ctx.sample/ctx.sample_step are on their way out.
+# A mutable set (mutated in place, never rebound) rather than a `global` boolean
+# so the warn-once state is unambiguously read and written from the module.
+_sample_deprecation_warned: set[bool] = set()
+
+_SAMPLING_DEPRECATION_MESSAGE = (
+    "ctx.sample() and ctx.sample_step() are deprecated and will be removed in a "
+    "future FastMCP release. They rely on server-initiated createMessage "
+    "requests, which were removed from MCP as of 2026-07-28 (SEP-2577), so they "
+    "work only on session-based (handshake-era) connections. Call an LLM "
+    "directly from your server instead."
+)
+
+_SAMPLING_MODERN_ERROR = (
+    "server-initiated sampling is not available on MCP 2026-07-28 connections; "
+    "SEP-2577 removed it — call an LLM from your server instead."
+)
+
+_ELICIT_MODERN_ERROR = (
+    "elicitation via server-initiated requests is unavailable on 2026-07-28 "
+    "connections."
+)
+
+
+def _warn_sampling_deprecated() -> None:
+    """Emit the sampling deprecation warning once per process.
+
+    Gated on ``settings.deprecation_warnings`` like every other FastMCP
+    deprecation; fires a single time (module-level flag) rather than per call.
+    """
+    if _sample_deprecation_warned or not fastmcp.settings.deprecation_warnings:
+        return
+    _sample_deprecation_warned.add(True)
+    warnings.warn(
+        _SAMPLING_DEPRECATION_MESSAGE,
+        FastMCPDeprecationWarning,
+        stacklevel=3,
+    )
+
+
+_current_context: ContextVar[Context | None] = ContextVar("context", default=None)
+
+TransportType = Literal["stdio", "sse", "streamable-http"]
+_current_transport: ContextVar[TransportType | None] = ContextVar(
+    "transport", default=None
+)
+
+
+def set_transport(
+    transport: TransportType,
+) -> Token[TransportType | None]:
+    """Set the current transport type. Returns token for reset."""
+    return _current_transport.set(transport)
+
+
+def reset_transport(token: Token[TransportType | None]) -> None:
+    """Reset transport to previous value."""
+    _current_transport.reset(token)
+
+
+@dataclass
+class LogData:
+    """Data object for passing log arguments to client-side handlers.
+
+    This provides an interface to match the Python standard library logging,
+    for compatibility with structured logging.
+    """
+
+    msg: str
+    extra: Mapping[str, Any] | None = None
+
+
+_mcp_level_to_python_level = {
+    "debug": logging.DEBUG,
+    "info": logging.INFO,
+    "notice": logging.INFO,
+    "warning": logging.WARNING,
+    "error": logging.ERROR,
+    "critical": logging.CRITICAL,
+    "alert": logging.CRITICAL,
+    "emergency": logging.CRITICAL,
+}
+
+
+@contextmanager
+def set_context(context: Context) -> Generator[Context, None, None]:
+    token = _current_context.set(context)
+    try:
+        yield context
+    finally:
+        _current_context.reset(token)
+
+
+@dataclass
+class Context:
+    """Context object providing access to MCP capabilities.
+
+    This provides a cleaner interface to MCP's RequestContext functionality.
+    It gets injected into tool and resource functions that request it via type hints.
+
+    To use context in a tool function, add a parameter with the Context type annotation:
+
+    ```python
+    @server.tool
+    async def my_tool(x: int, ctx: Context) -> str:
+        # Log messages to the client
+        await ctx.info(f"Processing {x}")
+        await ctx.debug("Debug info")
+        await ctx.warning("Warning message")
+        await ctx.error("Error message")
+
+        # Report progress
+        await ctx.report_progress(50, 100, "Processing")
+
+        # Access resources
+        data = await ctx.read_resource("resource://data")
+
+        # Get request info
+        request_id = ctx.request_id
+        client_id = ctx.client_id
+
+        # Manage state across the session (persists across requests)
+        await ctx.set_state("key", "value")
+        value = await ctx.get_state("key")
+
+        # Store non-serializable values for the current request only
+        await ctx.set_state("client", http_client, serializable=False)
+
+        return str(x)
+    ```
+
+    State Management:
+    Context provides session-scoped state that persists across requests within
+    the same MCP session. State is automatically keyed by session, ensuring
+    isolation between different clients.
+
+    State set during `on_initialize` middleware will persist to subsequent tool
+    calls when using the same session object (STDIO, SSE, single-server HTTP).
+    For distributed/serverless HTTP deployments where different machines handle
+    the init and tool calls, state is isolated by the mcp-session-id header.
+
+    The context parameter name can be anything as long as it's annotated with Context.
+    The context is optional - tools that don't need it can omit the parameter.
+
+    """
+
+    # Default TTL for session state: 1 day in seconds
+    _STATE_TTL_SECONDS: int = 86400
+
+    def __init__(
+        self,
+        fastmcp: FastMCP,
+        session: ServerSession | None = None,
+        *,
+        task_id: str | None = None,
+        origin_request_id: str | None = None,
+    ):
+        self._fastmcp: weakref.ref[FastMCP] = weakref.ref(fastmcp)
+        self._session: ServerSession | None = session  # For state ops during init
+        self._tokens: list[Token] = []
+        # Background task support (SEP-1686)
+        self._task_id: str | None = task_id
+        self._origin_request_id: str | None = origin_request_id
+        # Request-scoped state for non-serializable values (serializable=False)
+        self._request_state: dict[str, Any] = {}
+
+    @property
+    def is_background_task(self) -> bool:
+        """True when this context is running in a background task (Docket worker).
+
+        When True, certain operations like elicit() and sample() will use
+        task-aware implementations that can pause the task and wait for
+        client input.
+
+        Example:
+            ```python
+            @server.tool(task=True)
+            async def my_task(ctx: Context) -> str:
+                # Works transparently in both foreground and background task modes
+                result = await ctx.elicit("Need input", str)
+                return str(result)
+            ```
+        """
+        return self._task_id is not None
+
+    @property
+    def task_id(self) -> str | None:
+        """Get the background task ID if running in a background task.
+
+        Returns None if not running in a background task context.
+        """
+        return self._task_id
+
+    @property
+    def origin_request_id(self) -> str | None:
+        """Get the request ID that originated this execution, if available.
+
+        In foreground request mode, this is the current request_id.
+        In background task mode, this is the request_id captured when the task
+        was submitted, if one was available.
+        """
+        if self.request_context is not None:
+            return str(self.request_context.request_id)
+        return self._origin_request_id
+
+    @property
+    def fastmcp(self) -> FastMCP:
+        """Get the FastMCP instance."""
+        fastmcp = self._fastmcp()
+        if fastmcp is None:
+            raise RuntimeError("FastMCP instance is no longer available")
+        return fastmcp
+
+    async def __aenter__(self) -> Context:
+        """Enter the context manager and set this context as the current context."""
+        # Inherit request-scoped state from parent context so middleware
+        # and tool contexts share the same in-memory state dict.
+        parent = _current_context.get(None)
+        if parent is not None:
+            self._request_state = parent._request_state
+
+        # Always set this context and save the token
+        token = _current_context.set(self)
+        self._tokens.append(token)
+
+        # Set current server for dependency injection (use weakref to avoid reference cycles)
+        from fastmcp.server.dependencies import (
+            _current_docket,
+            _current_server,
+            _current_worker,
+            is_docket_available,
+        )
+
+        self._server_token = _current_server.set(weakref.ref(self.fastmcp))
+
+        # Re-set docket/worker from the server instance so mounted children
+        # inherit the parent's Docket via the ContextVar. Only servers that
+        # own the Docket (the parent) have _docket set; children skip this,
+        # leaving the parent's value in place.
+        if is_docket_available():
+            server = self.fastmcp
+            if server._docket is not None:
+                self._docket_token = _current_docket.set(server._docket)
+            if server._worker is not None:
+                self._worker_token = _current_worker.set(server._worker)
+
+        if not is_docket_available():
+            # Without docket, the lifespan won't provide a SharedContext,
+            # so create one scoped to this Context for Shared() dependencies.
+            self._shared_context = SharedContext()
+            await self._shared_context.__aenter__()
+
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit the context manager and reset the most recent token."""
+        from fastmcp.server.dependencies import (
+            _current_docket,
+            _current_server,
+            _current_worker,
+        )
+
+        if hasattr(self, "_worker_token"):
+            _current_worker.reset(self._worker_token)
+            del self._worker_token
+        if hasattr(self, "_docket_token"):
+            _current_docket.reset(self._docket_token)
+            del self._docket_token
+        if hasattr(self, "_shared_context"):
+            await self._shared_context.__aexit__(exc_type, exc_val, exc_tb)
+            del self._shared_context
+
+        if hasattr(self, "_server_token"):
+            _current_server.reset(self._server_token)
+            del self._server_token
+
+        # Reset context token
+        if self._tokens:
+            token = self._tokens.pop()
+            _current_context.reset(token)
+
+    @property
+    def request_context(self) -> FastMCPRequestContext | None:
+        """Access to the underlying request context.
+
+        Returns None when the MCP session has not been established yet.
+        Returns the FastMCPRequestContext wrapper once the MCP session is available.
+
+        For HTTP request access in middleware, use `get_http_request()` from fastmcp.server.dependencies,
+        which works whether or not the MCP session is available.
+
+        Example in middleware:
+        ```python
+        async def on_request(self, context, call_next):
+            ctx = context.fastmcp_context
+            if ctx.request_context:
+                # MCP session available - can access session_id, request_id, etc.
+                session_id = ctx.session_id
+            else:
+                # MCP session not available yet - use HTTP helpers
+                from fastmcp.server.dependencies import get_http_request
+                request = get_http_request()
+            return await call_next(context)
+        ```
+        """
+        return fastmcp_request_ctx.get()
+
+    @property
+    def lifespan_context(self) -> dict[str, Any]:
+        """Access the server's lifespan context.
+
+        Returns the context dict yielded by *this* server's lifespan function.
+        For a mounted child this is the child's own lifespan, not the parent's
+        — the MCP session always belongs to the parent, so reading from the
+        request context would return the parent's. We read directly from the
+        server's cached lifespan result instead, which is set by the
+        per-server ``_lifespan_manager`` regardless of mount position.
+
+        Returns an empty dict if no lifespan was configured.
+
+        Example:
+        ```python
+        @server.tool
+        def my_tool(ctx: Context) -> str:
+            db = ctx.lifespan_context.get("db")
+            if db:
+                return db.query("SELECT 1")
+            return "No database connection"
+        ```
+        """
+        result = self.fastmcp._lifespan_result
+        if result is not None:
+            return result
+        # Server's lifespan was never entered for this Context's server (or
+        # yielded None). Fall back to the request context's lifespan, which
+        # for a mounted child will be the parent's — preserved for parity
+        # with prior behavior, but in normal operation a child's own
+        # lifespan populates `_lifespan_result` and short-circuits above.
+        rc = self.request_context
+        if rc is None:
+            return {}
+        return rc.lifespan_context
+
+    async def report_progress(
+        self, progress: float, total: float | None = None, message: str | None = None
+    ) -> None:
+        """Report progress for the current operation.
+
+        Works in both foreground (MCP progress notifications) and background
+        (Docket task execution) contexts.
+
+        Args:
+            progress: Current progress value e.g. 24
+            total: Optional total value e.g. 100
+            message: Optional status message describing current progress
+        """
+
+        rc = self.request_context
+        progress_token = (
+            rc._srctx.meta.get("progress_token")
+            if rc is not None and rc._srctx.meta is not None
+            else None
+        )
+
+        # Foreground: Send MCP progress notification if we have a token
+        if progress_token is not None:
+            await self.session.send_progress_notification(
+                progress_token=progress_token,
+                progress=progress,
+                total=total,
+                message=message,
+                related_request_id=self.request_id,
+            )
+            return
+
+        # Background: Update Docket execution progress (stored in Redis)
+        # This makes progress visible via tasks/get and notifications/tasks/status
+        from fastmcp.server.dependencies import is_docket_available
+
+        if not is_docket_available():
+            return
+
+        try:
+            from docket.dependencies import current_execution
+
+            execution = current_execution.get()
+
+            # Update progress in Redis using Docket's progress API.
+            # Docket only exposes increment() (relative), so we compute
+            # the delta from the last reported value stored on this execution.
+            if total is not None:
+                await execution.progress.set_total(int(total))
+
+            current = int(progress)
+            last: int = getattr(execution, "_fastmcp_last_progress", 0)
+            delta = current - last
+            if delta > 0:
+                await execution.progress.increment(delta)
+            execution._fastmcp_last_progress = current  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+
+            if message is not None:
+                await execution.progress.set_message(message)
+        except LookupError:
+            # Not running in Docket worker context - no progress tracking available
+            pass
+
+    async def _paginate_list(
+        self,
+        call_handler: Callable[[Any, Any], Any],
+        extract_items: Callable[[Any], list[Any]],
+    ) -> list[Any]:
+        """Generic pagination helper for list operations.
+
+        Invokes a FastMCP ``_on_*`` list handler (``(ctx, params) -> result``)
+        page by page. The SDK request context comes from the active request;
+        outside a request context a fresh stand-in is used.
+
+        Args:
+            call_handler: FastMCP list handler taking ``(ctx, params)``.
+            extract_items: Function to extract items from the result.
+
+        Returns:
+            List of all items across all pages
+        """
+        rc = self.request_context
+        srctx = rc._srctx if rc is not None else _detached_request_context(self)
+
+        all_items: list[Any] = []
+        cursor: str | None = None
+        seen_cursors: set[str] = set()
+        while True:
+            params = mcp_types.PaginatedRequestParams(cursor=cursor) if cursor else None
+            result = await call_handler(srctx, params)
+            all_items.extend(extract_items(result))
+            if not result.next_cursor:
+                break
+            if result.next_cursor in seen_cursors:
+                break
+            seen_cursors.add(result.next_cursor)
+            cursor = result.next_cursor
+        return all_items
+
+    async def list_resources(self) -> list[SDKResource]:
+        """List all available resources from the server.
+
+        Returns:
+            List of Resource objects available on the server
+        """
+        return await self._paginate_list(
+            call_handler=self.fastmcp._on_list_resources,
+            extract_items=lambda result: result.resources,
+        )
+
+    async def list_prompts(self) -> list[SDKPrompt]:
+        """List all available prompts from the server.
+
+        Returns:
+            List of Prompt objects available on the server
+        """
+        return await self._paginate_list(
+            call_handler=self.fastmcp._on_list_prompts,
+            extract_items=lambda result: result.prompts,
+        )
+
+    async def get_prompt(
+        self, name: str, arguments: dict[str, Any] | None = None
+    ) -> GetPromptResult:
+        """Get a prompt by name with optional arguments.
+
+        Args:
+            name: The name of the prompt to get
+            arguments: Optional arguments to pass to the prompt
+
+        Returns:
+            The prompt result
+        """
+        result = await self.fastmcp.render_prompt(name, arguments)
+        if isinstance(result, mcp_types.CreateTaskResult):
+            raise RuntimeError(
+                "Unexpected CreateTaskResult: Context calls should not have task metadata"
+            )
+        return result.to_mcp_prompt_result()
+
+    async def read_resource(self, uri: str | AnyUrl) -> ResourceResult:
+        """Read a resource by URI.
+
+        Args:
+            uri: Resource URI to read
+
+        Returns:
+            ResourceResult with contents
+        """
+        result = await self.fastmcp.read_resource(str(uri))
+        if isinstance(result, mcp_types.CreateTaskResult):
+            raise RuntimeError(
+                "Unexpected CreateTaskResult: Context calls should not have task metadata"
+            )
+        return result
+
+    async def log(
+        self,
+        message: str,
+        level: LoggingLevel | None = None,
+        logger_name: str | None = None,
+        extra: Mapping[str, Any] | None = None,
+    ) -> None:
+        """Send a log message to the client.
+
+        Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`.
+
+        Args:
+            message: Log message
+            level: Optional log level. One of "debug", "info", "notice", "warning", "error", "critical",
+                "alert", or "emergency". Default is "info".
+            logger_name: Optional logger name
+            extra: Optional mapping for additional arguments
+        """
+        data = LogData(msg=message, extra=extra)
+        related_request_id = self.origin_request_id
+
+        # Resolve the client-requested minimum level (set via logging/setLevel),
+        # keyed by session id, falling back to the server's configured default.
+        min_level = self.fastmcp.client_log_level
+        session = self.session
+        session_min = self.fastmcp._client_log_levels.get(
+            _log_level_session_key(session)
+        )
+        if session_min is not None:
+            min_level = session_min
+
+        await _log_to_server_and_client(
+            data=data,
+            session=session,
+            level=level or "info",
+            logger_name=logger_name,
+            related_request_id=related_request_id,
+            min_level=min_level,
+        )
+
+    @property
+    def transport(self) -> TransportType | None:
+        """Get the current transport type.
+
+        Returns the transport type used to run this server: "stdio", "sse",
+        or "streamable-http". Returns None if called outside of a server context.
+        """
+        return _current_transport.get()
+
+    def client_supports_extension(self, extension_id: str) -> bool:
+        """Check whether the connected client supports a given MCP extension.
+
+        Inspects the ``extensions`` extra field on ``ClientCapabilities``
+        sent by the client during initialization.
+
+        Reads the client's advertised capabilities from the session, which is
+        available in request mode and in background-task mode (where the
+        snapshot session preserves the client's initialize params). Returns
+        ``False`` when no session is available (e.g., a distributed worker with
+        no live session, or outside any context) or when the client did not
+        advertise the extension.
+
+        Example::
+
+            from fastmcp.apps.config import UI_EXTENSION_ID
+
+            @mcp.tool
+            async def my_tool(ctx: Context) -> str:
+                if ctx.client_supports_extension(UI_EXTENSION_ID):
+                    return "UI-capable client"
+                return "text-only client"
+        """
+        try:
+            session = self.session
+        except RuntimeError:
+            return False
+        return client_supports_extension(session, extension_id)
+
+    @property
+    def client_id(self) -> str | None:
+        """Get the client ID if available."""
+        rc = self.request_context
+        return (
+            rc.meta.get("client_id") if rc is not None and rc.meta is not None else None
+        )
+
+    @property
+    def request_id(self) -> str:
+        """Get the unique ID for this request.
+
+        Raises RuntimeError if MCP request context is not available.
+        """
+        if self.request_context is None:
+            raise RuntimeError(
+                "request_id is not available because the MCP session has not been established yet. "
+                "Check `context.request_context` for None before accessing this attribute."
+            )
+        return str(self.request_context.request_id)
+
+    @property
+    def session_id(self) -> str:
+        """Get the MCP session ID for ALL transports.
+
+        Returns the session ID that can be used as a key for session-based
+        data storage (e.g., Redis) to share data between tool calls within
+        the same client session.
+
+        Returns:
+            The session ID for StreamableHTTP transports, or a generated ID
+            for other transports.
+
+        Raises:
+            RuntimeError if no session is available.
+
+        Example:
+            ```python
+            @server.tool
+            def store_data(data: dict, ctx: Context) -> str:
+                session_id = ctx.session_id
+                redis_client.set(f"session:{session_id}:data", json.dumps(data))
+                return f"Data stored for session {session_id}"
+            ```
+        """
+        from uuid import uuid4
+
+        # Get session from request context or _session (for on_initialize)
+        request_ctx = self.request_context
+        if request_ctx is not None:
+            session = request_ctx.session
+        elif self._session is not None:
+            session = self._session
+        else:
+            raise RuntimeError(
+                "session_id is not available because no session exists. "
+                "This typically means you're outside a request context."
+            )
+
+        # In SDK v2 the ServerSession is constructed fresh per request, so the
+        # stable per-client identity lives on the underlying Connection, which
+        # persists for the whole client session. Cache the state prefix on the
+        # connection (its `session_id` for HTTP, its `state` dict otherwise) so
+        # session-scoped state survives across tool calls.
+        connection = getattr(session, "_connection", None)
+
+        # Check for a cached prefix on the stable connection (or the session, as
+        # a fallback for on_initialize where only a raw session is available).
+        if connection is not None:
+            cached = connection.state.get("_fastmcp_state_prefix")
+            if cached is not None:
+                return cached
+        session_cached = getattr(session, "_fastmcp_state_prefix", None)
+        if session_cached is not None:
+            return session_cached
+
+        # For HTTP, prefer the connection's negotiated session id, then the
+        # incoming request header.
+        session_id: str | None = None
+        if connection is not None:
+            session_id = connection.session_id
+        if session_id is None and request_ctx is not None:
+            request = request_ctx.request
+            if request:
+                session_id = request.headers.get("mcp-session-id")
+
+        # For STDIO/SSE/in-memory, generate a UUID.
+        if session_id is None:
+            session_id = str(uuid4())
+
+        # Cache on the stable connection (falling back to the session).
+        if connection is not None:
+            connection.state["_fastmcp_state_prefix"] = session_id
+        else:
+            session._fastmcp_state_prefix = session_id  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+        return session_id
+
+    @property
+    def session(self) -> ServerSession:
+        """Access to the underlying session for advanced usage.
+
+        In request mode: Returns the session from the active request context.
+        In background task mode: Returns the session stored at Context creation.
+
+        Raises RuntimeError if no session is available.
+        """
+        # Background task mode: use the stored session
+        if self.is_background_task and self._session is not None:
+            return self._session
+
+        # Request mode: use request context
+        if self.request_context is not None:
+            return self.request_context.session
+
+        # Fallback to stored session (e.g., during on_initialize)
+        if self._session is not None:
+            return self._session
+
+        raise RuntimeError(
+            "session is not available because the MCP session has not been established yet. "
+            "Check `context.request_context` for None before accessing this attribute."
+        )
+
+    # Convenience methods for common log levels
+    async def debug(
+        self,
+        message: str,
+        logger_name: str | None = None,
+        extra: Mapping[str, Any] | None = None,
+    ) -> None:
+        """Send a `DEBUG`-level message to the connected MCP Client.
+
+        Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`."""
+        await self.log(
+            level="debug",
+            message=message,
+            logger_name=logger_name,
+            extra=extra,
+        )
+
+    async def info(
+        self,
+        message: str,
+        logger_name: str | None = None,
+        extra: Mapping[str, Any] | None = None,
+    ) -> None:
+        """Send a `INFO`-level message to the connected MCP Client.
+
+        Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`."""
+        await self.log(
+            level="info",
+            message=message,
+            logger_name=logger_name,
+            extra=extra,
+        )
+
+    async def warning(
+        self,
+        message: str,
+        logger_name: str | None = None,
+        extra: Mapping[str, Any] | None = None,
+    ) -> None:
+        """Send a `WARNING`-level message to the connected MCP Client.
+
+        Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`."""
+        await self.log(
+            level="warning",
+            message=message,
+            logger_name=logger_name,
+            extra=extra,
+        )
+
+    async def error(
+        self,
+        message: str,
+        logger_name: str | None = None,
+        extra: Mapping[str, Any] | None = None,
+    ) -> None:
+        """Send a `ERROR`-level message to the connected MCP Client.
+
+        Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`."""
+        await self.log(
+            level="error",
+            message=message,
+            logger_name=logger_name,
+            extra=extra,
+        )
+
+    async def list_roots(self) -> list[Root]:
+        """List the roots available to the server, as indicated by the client."""
+        # Deprecated upstream in SDK v2 but deliberately kept per compat directive;
+        # removed with the multi-round-trip follow-up.
+        result = await self.session.list_roots()  # ty: ignore[deprecated]
+        return result.roots
+
+    async def send_notification(
+        self, notification: mcp_types.ServerNotification
+    ) -> None:
+        """Send a notification to the client immediately.
+
+        Args:
+            notification: An MCP notification instance (e.g., ToolListChangedNotification())
+        """
+        # v2: ServerNotification is a union of concrete notification models;
+        # ServerSession.send_notification takes an instance directly (no wrapper).
+        await self.session.send_notification(notification)
+
+    async def close_sse_stream(self) -> None:
+        """Close the current response stream to trigger client reconnection.
+
+        When using StreamableHTTP transport with an EventStore configured, this
+        method gracefully closes the HTTP connection for the current request.
+        The client will automatically reconnect (after `retry_interval` milliseconds)
+        and resume receiving events from where it left off via the EventStore.
+
+        This is useful for long-running operations to avoid load balancer timeouts.
+        Instead of holding a connection open for minutes, you can periodically close
+        and let the client reconnect.
+
+        Example:
+            ```python
+            @mcp.tool
+            async def long_running_task(ctx: Context) -> str:
+                for i in range(100):
+                    await ctx.report_progress(i, 100)
+
+                    # Close connection every 30 iterations to avoid LB timeouts
+                    if i % 30 == 0 and i > 0:
+                        await ctx.close_sse_stream()
+
+                    await do_work()
+                return "Done"
+            ```
+
+        Note:
+            This is a no-op (with a debug log) if not using StreamableHTTP
+            transport with an EventStore configured.
+        """
+        if not self.request_context or not self.request_context.close_sse_stream:
+            logger.debug(
+                "close_sse_stream() called but not applicable "
+                "(requires StreamableHTTP transport with event_store)"
+            )
+            return
+        await self.request_context.close_sse_stream()
+
+    def _is_modern_protocol(self) -> bool:
+        """True when the negotiated MCP protocol era removed the back-channel.
+
+        Reads the negotiated protocol version from the active request context.
+        The 2026-07-28 era (SEP-2577) has no back-channel for server-initiated
+        requests such as sampling/elicitation. Returns False when no request
+        context is available (e.g. background task or pre-session), leaving the
+        existing wire path to surface its own error.
+        """
+        rc = self.request_context
+        if rc is None:
+            return False
+        return rc.protocol_version in MODERN_PROTOCOL_VERSIONS
+
+    def _server_can_sample(self) -> bool:
+        """True when a server-configured sampling handler can serve the request
+        without the client back-channel.
+
+        FastMCP supports a server-side sampling handler (``FastMCP(sampling_handler=...)``).
+        With ``sampling_handler_behavior="always"`` the handler always answers;
+        with ``"fallback"`` it answers whenever the client cannot. On modern
+        connections the client back-channel is gone, so either configuration lets
+        the server answer entirely server-side as long as a handler is set. (For
+        ``"always"`` without a handler the sampling implementation raises its own
+        clear "no handler configured" error, which is not an era concern.)
+        """
+        fastmcp = self.fastmcp
+        if fastmcp.sampling_handler_behavior == "always":
+            return True
+        return fastmcp.sampling_handler is not None
+
+    async def sample_step(
+        self,
+        messages: str | Sequence[str | SamplingMessage],
+        *,
+        system_prompt: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        model_preferences: ModelPreferences | str | list[str] | None = None,
+        tools: Sequence[SamplingTool | Callable[..., Any]] | None = None,
+        tool_choice: ToolChoiceOption | str | None = None,
+        execute_tools: bool = True,
+        mask_error_details: bool | None = None,
+        tool_concurrency: int | None = None,
+    ) -> SampleStep:
+        """
+        Make a single LLM sampling call.
+
+        This is a stateless function that makes exactly one LLM call and optionally
+        executes any requested tools. Use this for fine-grained control over the
+        sampling loop.
+
+        Args:
+            messages: The message(s) to send. Can be a string, list of strings,
+                or list of SamplingMessage objects.
+            system_prompt: Optional system prompt for the LLM.
+            temperature: Optional sampling temperature.
+            max_tokens: Maximum tokens to generate. Defaults to 512.
+            model_preferences: Optional model preferences.
+            tools: Optional list of tools the LLM can use.
+            tool_choice: Tool choice mode ("auto", "required", or "none").
+            execute_tools: If True (default), execute tool calls and append results
+                to history. If False, return immediately with tool_calls available
+                in the step for manual execution.
+            mask_error_details: If True, mask detailed error messages from tool
+                execution. When None (default), uses the global settings value.
+                Tools can raise ToolError to bypass masking.
+            tool_concurrency: Controls parallel execution of tools:
+                - None (default): Sequential execution (one at a time)
+                - 0: Unlimited parallel execution
+                - N > 0: Execute at most N tools concurrently
+                If any tool has sequential=True, all tools execute sequentially
+                regardless of this setting.
+
+        Returns:
+            SampleStep containing:
+            - .response: The raw LLM response
+            - .history: Messages including input, assistant response, and tool results
+            - .is_tool_use: True if the LLM requested tool execution
+            - .tool_calls: List of tool calls (if any)
+            - .text: The text content (if any)
+
+        Example:
+            messages = "Research X"
+
+            while True:
+                step = await ctx.sample_step(messages, tools=[search])
+
+                if not step.is_tool_use:
+                    print(step.text)
+                    break
+
+                # Continue with tool results
+                messages = step.history
+        """
+        _warn_sampling_deprecated()
+        # On modern (2026-07-28) connections the client back-channel is gone
+        # (SEP-2577). A server-configured sampling handler can still answer
+        # entirely server-side; only raise the era error when nothing can serve
+        # the request. When modern, force the handler path (never attempt the
+        # dead client) by passing client_available=False.
+        client_available = not self._is_modern_protocol()
+        if not client_available and not self._server_can_sample():
+            raise ToolError(_SAMPLING_MODERN_ERROR)
+        return await sample_step_impl(
+            self,
+            messages=messages,
+            system_prompt=system_prompt,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            model_preferences=model_preferences,
+            tools=tools,
+            tool_choice=tool_choice,
+            auto_execute_tools=execute_tools,
+            mask_error_details=mask_error_details,
+            tool_concurrency=tool_concurrency,
+            client_available=client_available,
+        )
+
+    @overload
+    async def sample(
+        self,
+        messages: str | Sequence[str | SamplingMessage],
+        *,
+        system_prompt: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        model_preferences: ModelPreferences | str | list[str] | None = None,
+        tools: Sequence[SamplingTool | Callable[..., Any]] | None = None,
+        result_type: type[ResultT],
+        mask_error_details: bool | None = None,
+        tool_concurrency: int | None = None,
+    ) -> SamplingResult[ResultT]:
+        """Overload: With result_type, returns SamplingResult[ResultT]."""
+
+    @overload
+    async def sample(
+        self,
+        messages: str | Sequence[str | SamplingMessage],
+        *,
+        system_prompt: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        model_preferences: ModelPreferences | str | list[str] | None = None,
+        tools: Sequence[SamplingTool | Callable[..., Any]] | None = None,
+        result_type: None = None,
+        mask_error_details: bool | None = None,
+        tool_concurrency: int | None = None,
+    ) -> SamplingResult[str]:
+        """Overload: Without result_type, returns SamplingResult[str]."""
+
+    async def sample(
+        self,
+        messages: str | Sequence[str | SamplingMessage],
+        *,
+        system_prompt: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        model_preferences: ModelPreferences | str | list[str] | None = None,
+        tools: Sequence[SamplingTool | Callable[..., Any]] | None = None,
+        result_type: type[ResultT] | None = None,
+        mask_error_details: bool | None = None,
+        tool_concurrency: int | None = None,
+    ) -> SamplingResult[ResultT] | SamplingResult[str]:
+        """
+        Send a sampling request to the client and await the response.
+
+        This method runs to completion automatically. When tools are provided,
+        it executes a tool loop: if the LLM returns a tool use request, the tools
+        are executed and the results are sent back to the LLM. This continues
+        until the LLM provides a final text response.
+
+        When result_type is specified, a synthetic `final_response` tool is
+        created. The LLM calls this tool to provide the structured response,
+        which is validated against the result_type and returned as `.result`.
+
+        For fine-grained control over the sampling loop, use sample_step() instead.
+
+        Args:
+            messages: The message(s) to send. Can be a string, list of strings,
+                or list of SamplingMessage objects.
+            system_prompt: Optional system prompt for the LLM.
+            temperature: Optional sampling temperature.
+            max_tokens: Maximum tokens to generate. Defaults to 512.
+            model_preferences: Optional model preferences.
+            tools: Optional list of tools the LLM can use. Accepts plain
+                functions or SamplingTools.
+            result_type: Optional type for structured output. When specified,
+                a synthetic `final_response` tool is created and the LLM's
+                response is validated against this type.
+            mask_error_details: If True, mask detailed error messages from tool
+                execution. When None (default), uses the global settings value.
+                Tools can raise ToolError to bypass masking.
+            tool_concurrency: Controls parallel execution of tools:
+                - None (default): Sequential execution (one at a time)
+                - 0: Unlimited parallel execution
+                - N > 0: Execute at most N tools concurrently
+                If any tool has sequential=True, all tools execute sequentially
+                regardless of this setting.
+
+        Returns:
+            SamplingResult[T] containing:
+            - .text: The text representation (raw text or JSON for structured)
+            - .result: The typed result (str for text, parsed object for structured)
+            - .history: All messages exchanged during sampling
+
+        Deprecated:
+            Server-initiated sampling relies on the createMessage back-channel,
+            which MCP removed as of 2026-07-28 (SEP-2577). This method works only
+            on session-based (handshake-era) connections and will be removed in a
+            future FastMCP release. Call an LLM directly from your server instead.
+        """
+        _warn_sampling_deprecated()
+        # On modern (2026-07-28) connections the client back-channel is gone
+        # (SEP-2577). A server-configured sampling handler can still answer
+        # entirely server-side; only raise the era error when nothing can serve
+        # the request. When modern, force the handler path (never attempt the
+        # dead client) by passing client_available=False.
+        client_available = not self._is_modern_protocol()
+        if not client_available and not self._server_can_sample():
+            raise ToolError(_SAMPLING_MODERN_ERROR)
+        return await sample_impl(  # ty: ignore[invalid-return-type]
+            self,
+            messages=messages,
+            system_prompt=system_prompt,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            model_preferences=model_preferences,
+            tools=tools,
+            result_type=result_type,
+            mask_error_details=mask_error_details,
+            tool_concurrency=tool_concurrency,
+            client_available=client_available,
+        )
+
+    @overload
+    async def elicit(
+        self,
+        message: str,
+        response_type: None,
+        *,
+        response_title: str | None = None,
+        response_description: str | None = None,
+    ) -> (
+        AcceptedElicitation[dict[str, Any]] | DeclinedElicitation | CancelledElicitation
+    ): ...
+
+    """When response_type is None, the accepted elicitation will contain an
+    empty dict"""
+
+    @overload
+    async def elicit(
+        self,
+        message: str,
+        response_type: type[T],
+        *,
+        response_title: str | None = None,
+        response_description: str | None = None,
+    ) -> AcceptedElicitation[T] | DeclinedElicitation | CancelledElicitation: ...
+
+    """When response_type is not None, the accepted elicitation will contain the
+    response data"""
+
+    @overload
+    async def elicit(
+        self,
+        message: str,
+        response_type: list[str],
+        *,
+        response_title: str | None = None,
+        response_description: str | None = None,
+    ) -> AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation: ...
+
+    """When response_type is a list of strings, the accepted elicitation will
+    contain the selected string response"""
+
+    @overload
+    async def elicit(
+        self,
+        message: str,
+        response_type: dict[str, dict[str, str]],
+        *,
+        response_title: str | None = None,
+        response_description: str | None = None,
+    ) -> AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation: ...
+
+    """When response_type is a dict mapping keys to title dicts, the accepted
+    elicitation will contain the selected key"""
+
+    @overload
+    async def elicit(
+        self,
+        message: str,
+        response_type: list[list[str]],
+        *,
+        response_title: str | None = None,
+        response_description: str | None = None,
+    ) -> (
+        AcceptedElicitation[list[str]] | DeclinedElicitation | CancelledElicitation
+    ): ...
+
+    """When response_type is a list containing a list of strings (multi-select),
+    the accepted elicitation will contain a list of selected strings"""
+
+    @overload
+    async def elicit(
+        self,
+        message: str,
+        response_type: list[dict[str, dict[str, str]]],
+        *,
+        response_title: str | None = None,
+        response_description: str | None = None,
+    ) -> (
+        AcceptedElicitation[list[str]] | DeclinedElicitation | CancelledElicitation
+    ): ...
+
+    """When response_type is a list containing a dict mapping keys to title dicts
+    (multi-select with titles), the accepted elicitation will contain a list of
+    selected keys"""
+
+    async def elicit(
+        self,
+        message: str,
+        response_type: type[T]
+        | list[str]
+        | dict[str, dict[str, str]]
+        | list[list[str]]
+        | list[dict[str, dict[str, str]]]
+        | None = None,
+        *,
+        response_title: str | None = None,
+        response_description: str | None = None,
+    ) -> (
+        AcceptedElicitation[T]
+        | AcceptedElicitation[dict[str, Any]]
+        | AcceptedElicitation[str]
+        | AcceptedElicitation[list[str]]
+        | DeclinedElicitation
+        | CancelledElicitation
+    ):
+        """
+        Send an elicitation request to the client and await the response.
+
+        Call this method at any time to request additional information from
+        the user through the client. The client must support elicitation,
+        or the request will error.
+
+        Note that the MCP protocol only supports simple object schemas with
+        primitive types. You can provide a dataclass, TypedDict, or BaseModel to
+        comply. If you provide a primitive type, an object schema with a single
+        "value" field will be generated for the MCP interaction and
+        automatically deconstructed into the primitive type upon response.
+
+        Passing ``response_type=None`` (or omitting it) is deprecated and will
+        be removed in a future version. The resulting empty-schema form-mode
+        request is ambiguous and causes some clients (e.g. VS Code) to hang on
+        an empty form. Pass an explicit ``response_type`` describing the data
+        you want back.
+
+        Args:
+            message: A human-readable message explaining what information is needed
+            response_type: The type of the response, which should be a primitive
+                type or dataclass or BaseModel. If it is a primitive type, an
+                object schema with a single "value" field will be generated.
+            response_title: Optional label to display for the wrapped ``value``
+                field when ``response_type`` is a scalar, Literal, Enum, or one
+                of the dict/list shorthand forms. Overrides the auto-generated
+                "Value" label. Raises ``TypeError`` if passed with a BaseModel,
+                dataclass, or ``None`` response type (use ``Field(title=...)``
+                on the model instead).
+            response_description: Optional description to attach to the wrapped
+                ``value`` field. Same scope rules as ``response_title``.
+
+        Note:
+            This method works transparently in both request and background task
+            contexts. In background task mode (SEP-1686), it will set the task
+            status to "input_required" and wait for the client to provide input.
+        """
+        if response_type is None and fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "Calling ctx.elicit() without a response_type is deprecated "
+                "and will be removed in a future version. The empty-schema "
+                "form-mode request is ambiguous under the current MCP spec "
+                "and causes some clients (e.g. VS Code) to render an empty, "
+                "non-functional form. Pass an explicit response_type "
+                "describing the data you expect back.",
+                FastMCPDeprecationWarning,
+                stacklevel=2,
+            )
+        config = parse_elicit_response_type(
+            response_type,
+            response_title=response_title,
+            response_description=response_description,
+        )
+
+        if self.is_background_task:
+            # Background task mode: use task-aware elicitation
+            result = await self._elicit_for_task(
+                message=message,
+                schema=config.schema,
+            )
+        else:
+            # Foreground push path: server-initiated elicitation needs a
+            # back-channel, which the 2026-07-28 era removed (SEP-2577). Raise a
+            # clear era-aware error before hitting the wire instead of the SDK's
+            # opaque "Method not found". Handshake-era behavior is unchanged.
+            if self._is_modern_protocol():
+                raise ToolError(_ELICIT_MODERN_ERROR)
+            # Standard request mode: use session.elicit directly
+            result = await self.session.elicit(
+                message=message,
+                requested_schema=config.schema,
+                related_request_id=self.request_id,
+            )
+
+        if result.action == "accept":
+            return handle_elicit_accept(config, result.content)
+        elif result.action == "decline":
+            return DeclinedElicitation()
+        elif result.action == "cancel":
+            return CancelledElicitation()
+        else:
+            raise ValueError(f"Unexpected elicitation action: {result.action}")
+
+    async def _elicit_for_task(
+        self,
+        message: str,
+        schema: dict[str, Any],
+    ) -> mcp_types.ElicitResult:
+        """Send an elicitation request from a background task (SEP-1686).
+
+        This method handles elicitation when running in a Docket worker context,
+        where there's no active MCP request. It:
+        1. Sets the task status to "input_required"
+        2. Sends the elicitation request with task metadata
+        3. Waits for the client to provide input via tasks/sendInput
+        4. Returns the result and resumes task execution
+
+        Args:
+            message: The message to display to the user
+            schema: The JSON schema for the expected response
+
+        Returns:
+            ElicitResult with the user's response
+
+        Raises:
+            RuntimeError: If not running in a background task context
+        """
+        if not self.is_background_task:
+            raise RuntimeError(
+                "_elicit_for_task called but not in a background task context"
+            )
+
+        # Import here to avoid circular imports and optional dependency issues
+        from fastmcp.server.tasks.elicitation import elicit_for_task
+
+        return await elicit_for_task(
+            task_id=self._task_id,  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+            session=self._session,
+            message=message,
+            schema=schema,
+            fastmcp=self.fastmcp,
+        )
+
+    def _make_state_key(self, key: str) -> str:
+        """Create session-prefixed key for state storage."""
+        return f"{self.session_id}:{key}"
+
+    async def set_state(
+        self, key: str, value: Any, *, serializable: bool = True
+    ) -> None:
+        """Set a value in the state store.
+
+        By default, values are stored in the session-scoped state store and
+        persist across requests within the same MCP session. Values must be
+        JSON-serializable (dicts, lists, strings, numbers, etc.).
+
+        For non-serializable values (e.g., HTTP clients, database connections),
+        pass ``serializable=False``. These values are stored in a request-scoped
+        dict and only live for the current MCP request (tool call, resource
+        read, or prompt render). They will not be available in subsequent
+        requests.
+
+        The key is automatically prefixed with the session identifier.
+        """
+        prefixed_key = self._make_state_key(key)
+        if not serializable:
+            self._request_state[prefixed_key] = value
+            return
+        # Clear any request-scoped shadow so the session value is visible
+        self._request_state.pop(prefixed_key, None)
+        try:
+            await self.fastmcp._state_store.put(
+                key=prefixed_key,
+                value=StateValue(value=value),
+                ttl=self._STATE_TTL_SECONDS,
+            )
+        except Exception as e:
+            # Catch serialization errors from Pydantic (ValueError) or
+            # the key_value library (SerializationError). Both contain
+            # "serialize" in the message. Other exceptions propagate as-is.
+            if "serialize" in str(e).lower():
+                raise TypeError(
+                    f"Value for state key {key!r} is not serializable. "
+                    f"Use set_state({key!r}, value, serializable=False) to store "
+                    f"non-serializable values. Note: non-serializable state is "
+                    f"request-scoped and will not persist across requests."
+                ) from e
+            raise
+
+    async def get_state(self, key: str) -> Any:
+        """Get a value from the state store.
+
+        Checks request-scoped state first (set with ``serializable=False``),
+        then falls back to the session-scoped state store.
+
+        Returns None if the key is not found.
+        """
+        prefixed_key = self._make_state_key(key)
+        if prefixed_key in self._request_state:
+            return self._request_state[prefixed_key]
+        result = await self.fastmcp._state_store.get(key=prefixed_key)
+        return result.value if result is not None else None
+
+    async def delete_state(self, key: str) -> None:
+        """Delete a value from the state store.
+
+        Removes from both request-scoped and session-scoped stores.
+        """
+        prefixed_key = self._make_state_key(key)
+        self._request_state.pop(prefixed_key, None)
+        await self.fastmcp._state_store.delete(key=prefixed_key)
+
+    # -------------------------------------------------------------------------
+    # Session visibility control
+    # -------------------------------------------------------------------------
+
+    async def _get_visibility_rules(self) -> list[dict[str, Any]]:
+        """Load visibility rule dicts from session state."""
+        return await _get_visibility_rules(self)
+
+    async def _get_session_transforms(self) -> list[Visibility]:
+        """Get session-specific Visibility transforms from state store."""
+        return await _get_session_transforms(self)
+
+    async def enable_components(
+        self,
+        *,
+        names: set[str] | None = None,
+        keys: set[str] | None = None,
+        version: VersionSpec | None = None,
+        tags: set[str] | None = None,
+        components: set[Literal["tool", "resource", "template", "prompt"]]
+        | None = None,
+        match_all: bool = False,
+    ) -> None:
+        """Enable components matching criteria for this session only.
+
+        Session rules override global transforms. Rules accumulate - each call
+        adds a new rule to the session. Later marks override earlier ones
+        (Visibility transform semantics).
+
+        Sends notifications to this session only: ToolListChangedNotification,
+        ResourceListChangedNotification, and PromptListChangedNotification.
+
+        Args:
+            names: Component names or URIs to match.
+            keys: Component keys to match (e.g., {"tool:my_tool@v1"}).
+            version: Component version spec to match.
+            tags: Tags to match (component must have at least one).
+            components: Component types to match (e.g., {"tool", "prompt"}).
+            match_all: If True, matches all components regardless of other criteria.
+        """
+        await _enable_components(
+            self,
+            names=names,
+            keys=keys,
+            version=version,
+            tags=tags,
+            components=components,
+            match_all=match_all,
+        )
+
+    async def disable_components(
+        self,
+        *,
+        names: set[str] | None = None,
+        keys: set[str] | None = None,
+        version: VersionSpec | None = None,
+        tags: set[str] | None = None,
+        components: set[Literal["tool", "resource", "template", "prompt"]]
+        | None = None,
+        match_all: bool = False,
+    ) -> None:
+        """Disable components matching criteria for this session only.
+
+        Session rules override global transforms. Rules accumulate - each call
+        adds a new rule to the session. Later marks override earlier ones
+        (Visibility transform semantics).
+
+        Sends notifications to this session only: ToolListChangedNotification,
+        ResourceListChangedNotification, and PromptListChangedNotification.
+
+        Args:
+            names: Component names or URIs to match.
+            keys: Component keys to match (e.g., {"tool:my_tool@v1"}).
+            version: Component version spec to match.
+            tags: Tags to match (component must have at least one).
+            components: Component types to match (e.g., {"tool", "prompt"}).
+            match_all: If True, matches all components regardless of other criteria.
+        """
+        await _disable_components(
+            self,
+            names=names,
+            keys=keys,
+            version=version,
+            tags=tags,
+            components=components,
+            match_all=match_all,
+        )
+
+    async def reset_visibility(self) -> None:
+        """Clear all session visibility rules.
+
+        Use this to reset session visibility back to global defaults.
+
+        Sends notifications to this session only: ToolListChangedNotification,
+        ResourceListChangedNotification, and PromptListChangedNotification.
+        """
+        await _reset_visibility(self)
+
+
+_MCP_LEVEL_SEVERITY: dict[LoggingLevel, int] = {
+    "debug": 0,
+    "info": 1,
+    "notice": 2,
+    "warning": 3,
+    "error": 4,
+    "critical": 5,
+    "alert": 6,
+    "emergency": 7,
+}
+
+
+def _detached_request_context(context: Context) -> ServerRequestContext:
+    """Build a minimal SDK request context for internal handler invocation.
+
+    Used by ``Context._paginate_list`` when no request context is active (e.g.
+    introspection outside a live request), so the ``_on_*`` list handlers have a
+    context to bind. The list handlers only read ``self`` (the FastMCP server)
+    to enumerate components, so a session-less context is sufficient.
+    """
+    return ServerRequestContext(
+        session=cast(ServerSession, context._session),
+        lifespan_context={},
+        protocol_version="2025-06-18",
+        method="internal",
+        params=None,
+        request_id=None,
+        meta=None,
+        request=None,
+    )
+
+
+def _log_level_session_key(session: ServerSession) -> str:
+    """Derive the per-session key used for logging/setLevel gating.
+
+    v2 constructs sessions per-request, so the stable identity is the
+    connection session id (stateful HTTP). stdio/in-memory has no session id,
+    so a sentinel key is used — all such connections share one gate, matching
+    the single-connection nature of those transports.
+    """
+    connection = getattr(session, "_connection", None)
+    session_id = getattr(connection, "session_id", None) if connection else None
+    return session_id if session_id is not None else "__no_session__"
+
+
+async def _log_to_server_and_client(
+    data: LogData,
+    session: ServerSession,
+    level: LoggingLevel,
+    logger_name: str | None = None,
+    related_request_id: str | None = None,
+    min_level: LoggingLevel | None = None,
+) -> None:
+    """Log a message to the server and client."""
+    if min_level is not None:
+        if _MCP_LEVEL_SEVERITY[level] < _MCP_LEVEL_SEVERITY[min_level]:
+            return
+
+    msg_prefix = f"Sending {level.upper()} to client"
+
+    if logger_name:
+        msg_prefix += f" ({logger_name})"
+
+    to_client_logger.log(
+        level=_mcp_level_to_python_level[level],
+        msg=f"{msg_prefix}: {data.msg}",
+        extra=data.extra,
+    )
+
+    # Deprecated upstream in SDK v2 but deliberately kept per compat directive;
+    # removed with the multi-round-trip follow-up.
+    await session.send_log_message(  # ty: ignore[deprecated]
+        level=level,
+        data=data,
+        logger=logger_name,
+        related_request_id=related_request_id,
+    )
diff --git a/fastmcp_slim/fastmcp/server/dependencies.py b/fastmcp_slim/fastmcp/server/dependencies.py
new file mode 100644
index 0000000..3e056cb
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/dependencies.py
@@ -0,0 +1,1480 @@
+"""Dependency injection for FastMCP.
+
+DI features (Depends, CurrentContext, CurrentFastMCP) work without pydocket
+using the uncalled-for DI engine. Only task-related dependencies (CurrentDocket,
+CurrentWorker) and background task execution require fastmcp[tasks].
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import inspect
+import weakref
+from collections.abc import AsyncGenerator, Callable, Generator, Mapping
+from contextlib import AsyncExitStack, asynccontextmanager, contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from functools import lru_cache
+from types import TracebackType
+from typing import TYPE_CHECKING, Any, Protocol, cast, get_type_hints, runtime_checkable
+
+from mcp.server.auth.middleware.auth_context import (
+    get_access_token as _sdk_get_access_token,
+)
+from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser
+from mcp.server.auth.provider import (
+    AccessToken as _SDKAccessToken,
+)
+from mcp.server.context import ServerRequestContext
+from mcp.server.session import ServerSession
+from packaging.version import Version
+from starlette.requests import Request
+from uncalled_for import Dependency, get_dependency_parameters
+from uncalled_for.resolution import _Depends
+
+from fastmcp.exceptions import FastMCPError
+from fastmcp.server.auth import AccessToken
+from fastmcp.server.http import _current_http_request
+from fastmcp.utilities.async_utils import (
+    call_sync_fn_in_threadpool,
+    is_coroutine_function,
+)
+from fastmcp.utilities.types import find_kwarg_by_type, is_class_member_of_type
+
+if TYPE_CHECKING:
+    from docket import Docket
+    from docket.worker import Worker
+
+    from fastmcp.server.context import Context
+    from fastmcp.server.server import FastMCP
+
+
+@dataclass
+class FastMCPRequestContext:
+    """FastMCP-owned wrapper around the SDK's per-request context.
+
+    The SDK v2 runner hands each handler a fresh ``ServerRequestContext`` as an
+    argument rather than exposing it through a ContextVar. FastMCP owns this
+    ContextVar (``fastmcp_request_ctx``) and each request adapter binds a
+    ``FastMCPRequestContext`` at the top of the handler (and the initialize
+    middleware binds it too).
+
+    A wrapper rather than the raw context because the SDK's
+    ``ServerRequestContext.meta`` is a bare ``RequestParamsMeta`` TypedDict that
+    only carries ``progress_token`` — it does not carry ``_meta.fastmcp`` or the
+    distributed-trace parent. Those live in the raw params dict under ``_meta``,
+    which this wrapper lifts once so downstream consumers have a stable surface.
+    """
+
+    session: ServerSession
+    request_id: str | None
+    meta: dict[str, Any] | None
+    """The raw ``_meta`` block lifted from the request params, if any."""
+    request: Request | None
+    protocol_version: str
+    close_sse_stream: Any | None
+    lifespan_context: Any
+    _srctx: ServerRequestContext
+    """Escape hatch to the underlying SDK request context."""
+
+
+fastmcp_request_ctx: ContextVar[FastMCPRequestContext | None] = ContextVar(
+    "fastmcp_request_ctx", default=None
+)
+
+
+def _lift_meta(ctx: ServerRequestContext) -> dict[str, Any] | None:
+    """Lift the raw ``_meta`` block from the request params.
+
+    ``ctx.params`` is the raw params mapping (or None); its ``_meta`` key holds
+    the full metadata block (``fastmcp.version``, traceparent, progressToken,
+    ...). ``ctx.meta`` (a TypedDict) only carries ``progress_token``, so version
+    and trace extraction must read from here.
+    """
+    if ctx.params and isinstance(ctx.params, Mapping):
+        meta = ctx.params.get("_meta")
+        if isinstance(meta, Mapping):
+            return dict(meta)
+    return None
+
+
+@contextmanager
+def bind_request_context(
+    ctx: ServerRequestContext,
+) -> Generator[FastMCPRequestContext, None, None]:
+    """Bind a ``FastMCPRequestContext`` for the duration of a handler.
+
+    Constructs the wrapper from the SDK's per-request context and sets/resets
+    the ``fastmcp_request_ctx`` ContextVar. Every request adapter and the
+    initialize middleware enters this so ``Context`` and dependency helpers can
+    read the active request from the ContextVar.
+    """
+    wrapper = FastMCPRequestContext(
+        session=ctx.session,
+        request_id=str(ctx.request_id) if ctx.request_id is not None else None,
+        meta=_lift_meta(ctx),
+        request=ctx.request,
+        protocol_version=ctx.protocol_version,
+        close_sse_stream=ctx.close_sse_stream,
+        lifespan_context=ctx.lifespan_context,
+        _srctx=ctx,
+    )
+    token = fastmcp_request_ctx.set(wrapper)
+    try:
+        yield wrapper
+    finally:
+        fastmcp_request_ctx.reset(token)
+
+
+def extract_version_spec(meta: dict[str, Any] | None) -> str | None:
+    """Extract the FastMCP component version from a lifted ``_meta`` block."""
+    if not meta:
+        return None
+    fastmcp_meta = meta.get("fastmcp")
+    if isinstance(fastmcp_meta, Mapping):
+        version = fastmcp_meta.get("version")
+        if isinstance(version, str):
+            return version
+    return None
+
+
+__all__ = [
+    "AccessToken",
+    "CurrentAccessToken",
+    "CurrentContext",
+    "CurrentDocket",
+    "CurrentFastMCP",
+    "CurrentHeaders",
+    "CurrentRequest",
+    "CurrentWorker",
+    "FastMCPRequestContext",
+    "Progress",
+    "TaskContextInfo",
+    "TaskContextSnapshot",
+    "TokenClaim",
+    "bind_request_context",
+    "extract_version_spec",
+    "fastmcp_request_ctx",
+    "get_access_token",
+    "get_context",
+    "get_http_headers",
+    "get_http_request",
+    "get_server",
+    "get_task_context",
+    "get_task_session",
+    "is_docket_available",
+    "register_task_server",
+    "register_task_session",
+    "require_docket",
+    "resolve_dependencies",
+    "transform_context_annotations",
+    "without_injected_parameters",
+]
+
+
+# Task context lives in fastmcp.server.tasks.context; public symbols are
+# re-exported here so existing imports from dependencies continue to work.
+from fastmcp.server.tasks.context import (  # noqa: E402
+    TaskContextInfo,
+    TaskContextSnapshot,
+    _recall_snapshot,
+    get_task_context,
+    get_task_server,
+    get_task_session,
+    register_task_server,
+    register_task_session,
+)
+
+_current_server: ContextVar[weakref.ref[FastMCP] | None] = ContextVar(
+    "server", default=None
+)
+
+_current_docket: ContextVar[Docket | None] = ContextVar("docket", default=None)
+_current_worker: ContextVar[Worker | None] = ContextVar("worker", default=None)
+
+
+# --- Docket availability check ---
+
+_DOCKET_AVAILABLE: bool | None = None
+
+
+_MIN_DOCKET_VERSION = Version("0.19.0")
+
+
+def is_docket_available() -> bool:
+    """Check if a compatible pydocket (>= 0.19.0) is installed and importable.
+
+    Three things have to be true for fastmcp's task features to work:
+      1. pydocket distribution metadata is discoverable
+      2. its version is at least ``_MIN_DOCKET_VERSION`` (older versions are
+         missing symbols like ``docket.dependencies.current_execution``,
+         which fastmcp imports on the request hot path)
+      3. the package actually imports — guards against broken/partial
+         installs where metadata exists but ``import docket`` blows up
+
+    Any of those failing means we treat docket as unavailable and fall back
+    to the no-tasks code paths instead of crashing deep inside a request.
+    """
+    global _DOCKET_AVAILABLE
+    if _DOCKET_AVAILABLE is None:
+        try:
+            installed = Version(importlib.metadata.version("pydocket"))
+            if installed < _MIN_DOCKET_VERSION:
+                _DOCKET_AVAILABLE = False
+            else:
+                import docket  # noqa: F401
+
+                _DOCKET_AVAILABLE = True
+        except (importlib.metadata.PackageNotFoundError, ImportError):
+            _DOCKET_AVAILABLE = False
+    return _DOCKET_AVAILABLE
+
+
+def require_docket(feature: str) -> None:
+    """Raise ImportError with install instructions if docket not available.
+
+    Args:
+        feature: Description of what requires docket (e.g., "`task=True`",
+                 "CurrentDocket()"). Will be included in the error message.
+    """
+    if is_docket_available():
+        return
+
+    try:
+        installed = importlib.metadata.version("pydocket")
+    except importlib.metadata.PackageNotFoundError:
+        installed = None
+
+    if installed is None:
+        detail = (
+            "FastMCP background tasks require the `tasks` extra. "
+            "Install with: pip install 'fastmcp[tasks]'."
+        )
+    else:
+        detail = (
+            f"FastMCP background tasks require pydocket>={_MIN_DOCKET_VERSION}, "
+            f"but pydocket {installed} is installed (likely pulled in by another "
+            f"package). Upgrade with: pip install -U 'pydocket>={_MIN_DOCKET_VERSION}'."
+        )
+
+    raise ImportError(f"{detail} (Triggered by {feature})")
+
+
+# Import Progress separately — it's docket-specific, not part of uncalled-for
+try:
+    from docket.dependencies import Progress as DocketProgress
+except ImportError:
+    DocketProgress = None  # type: ignore[assignment]  # ty:ignore[invalid-assignment]
+
+
+# --- Context utilities ---
+
+
+def transform_context_annotations(fn: Callable[..., Any]) -> Callable[..., Any]:
+    """Transform ctx: Context into ctx: Context = CurrentContext().
+
+    Transforms ALL params typed as Context to use Docket's DI system,
+    unless they already have a Dependency-based default (like CurrentContext()).
+
+    This unifies the legacy type annotation DI with Docket's Depends() system,
+    allowing both patterns to work through a single resolution path.
+
+    Note: Only POSITIONAL_OR_KEYWORD parameters are reordered (params with defaults
+    after those without). KEYWORD_ONLY parameters keep their position since Python
+    allows them to have defaults in any order.
+
+    Args:
+        fn: Function to transform
+
+    Returns:
+        Function with modified signature (same function object, updated __signature__)
+    """
+    from fastmcp.server.context import Context
+
+    # Get the function's signature
+    try:
+        sig = inspect.signature(fn)
+    except (ValueError, TypeError):
+        return fn
+
+    # Get type hints for accurate type checking
+    try:
+        type_hints = get_type_hints(fn, include_extras=True)
+    except Exception:
+        type_hints = getattr(fn, "__annotations__", {})
+
+    # First pass: identify which params need transformation
+    params_to_transform: set[str] = set()
+    optional_context_params: set[str] = set()
+    for name, param in sig.parameters.items():
+        annotation = type_hints.get(name, param.annotation)
+        if is_class_member_of_type(annotation, Context):
+            if not isinstance(param.default, Dependency):
+                params_to_transform.add(name)
+                if param.default is None:
+                    optional_context_params.add(name)
+
+    if not params_to_transform:
+        return fn
+
+    # Second pass: build new param list preserving parameter kind structure
+    # Python signature structure: [POSITIONAL_ONLY] / [POSITIONAL_OR_KEYWORD] *args [KEYWORD_ONLY] **kwargs
+    # Within POSITIONAL_ONLY and POSITIONAL_OR_KEYWORD: params without defaults must come first
+    # KEYWORD_ONLY params can have defaults in any order
+    P = inspect.Parameter
+
+    # Group params by section, preserving order within each
+    positional_only_no_default: list[P] = []
+    positional_only_with_default: list[P] = []
+    positional_or_keyword_no_default: list[P] = []
+    positional_or_keyword_with_default: list[P] = []
+    var_positional: list[P] = []  # *args (at most one)
+    keyword_only: list[P] = []  # After * or *args, order preserved
+    var_keyword: list[P] = []  # **kwargs (at most one)
+
+    for name, param in sig.parameters.items():
+        # Transform Context params by adding CurrentContext default
+        if name in params_to_transform:
+            # We use CurrentContext() instead of Depends(get_context) because
+            # get_context() returns the Context which is an AsyncContextManager,
+            # and the DI system would try to enter it again (it's already entered)
+            if name in optional_context_params:
+                param = param.replace(default=OptionalCurrentContext())
+            else:
+                param = param.replace(default=CurrentContext())
+
+        # Sort into buckets based on parameter kind
+        if param.kind == P.POSITIONAL_ONLY:
+            if param.default is P.empty:
+                positional_only_no_default.append(param)
+            else:
+                positional_only_with_default.append(param)
+        elif param.kind == P.POSITIONAL_OR_KEYWORD:
+            if param.default is P.empty:
+                positional_or_keyword_no_default.append(param)
+            else:
+                positional_or_keyword_with_default.append(param)
+        elif param.kind == P.VAR_POSITIONAL:
+            var_positional.append(param)
+        elif param.kind == P.KEYWORD_ONLY:
+            keyword_only.append(param)
+        elif param.kind == P.VAR_KEYWORD:
+            var_keyword.append(param)
+
+    # Reconstruct parameter list maintaining Python's required structure
+    new_params: list[P] = (
+        positional_only_no_default
+        + positional_only_with_default
+        + positional_or_keyword_no_default
+        + positional_or_keyword_with_default
+        + var_positional
+        + keyword_only
+        + var_keyword
+    )
+
+    # Update function's signature in place
+    # Handle methods by setting signature on the underlying function
+    # For bound methods, we need to preserve the 'self' parameter because
+    # inspect.signature(bound_method) automatically removes the first param
+    if inspect.ismethod(fn):
+        # Get the original __func__ signature which includes 'self'
+        func_sig = inspect.signature(fn.__func__)
+        # Insert 'self' at the beginning of our new params
+        self_param = next(iter(func_sig.parameters.values()))  # Should be 'self'
+        new_sig = func_sig.replace(parameters=[self_param, *new_params])
+        fn.__func__.__signature__ = new_sig  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+    else:
+        new_sig = sig.replace(parameters=new_params)
+        fn.__signature__ = new_sig  # type: ignore[attr-defined]  # ty:ignore[invalid-assignment]
+
+    # Clear caches that may have cached the old signature
+    # This ensures get_dependency_parameters and without_injected_parameters
+    # see the transformed signature
+    _clear_signature_caches(fn)
+
+    return fn
+
+
+def _clear_signature_caches(fn: Callable[..., Any]) -> None:
+    """Clear signature-related caches for a function.
+
+    Called after modifying a function's signature to ensure downstream
+    code sees the updated signature.
+    """
+    from uncalled_for.introspection import _parameter_cache, _signature_cache
+
+    _signature_cache.pop(fn, None)
+    _parameter_cache.pop(fn, None)
+
+    if inspect.ismethod(fn):
+        _signature_cache.pop(fn.__func__, None)
+        _parameter_cache.pop(fn.__func__, None)
+
+
+def get_context() -> Context:
+    """Get the current FastMCP Context instance directly."""
+    from fastmcp.server.context import _current_context
+
+    context = _current_context.get()
+    if context is None:
+        raise RuntimeError("No active context found.")
+    return context
+
+
+def get_server() -> FastMCP:
+    """Get the current FastMCP server instance directly.
+
+    In a background-task worker, checks the task-server map first so that
+    mounted-child tasks resolve to the child server (not the parent that
+    started the worker).
+
+    Returns:
+        The active FastMCP server
+
+    Raises:
+        RuntimeError: If no server in context
+    """
+    # In a task context, prefer the task-specific server mapping.
+    # This handles mounted-child tasks where _current_server is the parent.
+    task_info = get_task_context()
+    if task_info is not None:
+        task_server = get_task_server(task_info.task_id)
+        if task_server is not None:
+            return task_server
+
+    server_ref = _current_server.get()
+    if server_ref is None:
+        raise RuntimeError("No FastMCP server instance in context")
+    server = server_ref()
+    if server is None:
+        raise RuntimeError("FastMCP server instance is no longer available")
+    return server
+
+
+def get_http_request() -> Request:
+    """Get the current HTTP request.
+
+    Tries MCP SDK's request_ctx first, then falls back to FastMCP's HTTP context.
+    In background tasks, returns a synthetic request populated with the
+    snapshotted headers from the originating HTTP request.
+    """
+    # Try FastMCP's request context first (set during normal MCP request handling)
+    request = None
+    fastmcp_ctx = fastmcp_request_ctx.get()
+    if fastmcp_ctx is not None:
+        request = fastmcp_ctx.request
+
+    # Fallback to FastMCP's HTTP context variable
+    # This is needed during `on_initialize` middleware where request_ctx isn't set yet
+    if request is None:
+        request = _current_http_request.get()
+
+    # In Docket workers, restore a minimal request from the snapshotted
+    # headers.  The snapshot is preloaded by restore_task_snapshot before
+    # user code runs, so this is a pure ContextVar read.
+    if request is None:
+        task_info = get_task_context()
+        snapshot = _recall_snapshot(task_info.task_id) if task_info else None
+        task_headers = snapshot.http_headers if snapshot else None
+        if task_headers:
+            request = Request(
+                {
+                    "type": "http",
+                    "http_version": "1.1",
+                    "method": "POST",
+                    "scheme": "http",
+                    "path": "/",
+                    "raw_path": b"/",
+                    "query_string": b"",
+                    "headers": [
+                        (name.encode("latin-1"), value.encode("latin-1"))
+                        for name, value in task_headers.items()
+                    ],
+                    "client": None,
+                    "server": None,
+                    "root_path": "",
+                }
+            )
+
+    if request is None:
+        raise RuntimeError("No active HTTP request found.")
+    return request
+
+
+def get_http_headers(
+    include_all: bool = False,
+    include: set[str] | None = None,
+) -> dict[str, str]:
+    """Extract headers from the current HTTP request if available.
+
+    Never raises an exception, even if there is no active HTTP request (in which case
+    an empty dict is returned).
+
+    By default, strips problematic headers like `content-length` and `authorization`
+    that cause issues if forwarded to downstream services. If `include_all` is True,
+    all headers are returned.
+
+    The `include` parameter allows specific headers to be included even if they would
+    normally be excluded. This is useful for proxy transports that need to forward
+    authorization headers to upstream MCP servers.
+    """
+    if include_all:
+        exclude_headers: set[str] = set()
+    else:
+        exclude_headers = {
+            "host",
+            "content-length",
+            "content-type",
+            "connection",
+            "transfer-encoding",
+            "upgrade",
+            "te",
+            "keep-alive",
+            "expect",
+            "accept",
+            "authorization",
+            # Proxy-related headers
+            "proxy-authenticate",
+            "proxy-authorization",
+            "proxy-connection",
+            # MCP-related headers
+            "mcp-session-id",
+        }
+        if include:
+            exclude_headers -= {h.lower() for h in include}
+        # Sanity check: all entries must already be lowercase
+        if not all(h.lower() == h for h in exclude_headers):
+            raise ValueError("Excluded headers must be lowercase")
+    headers: dict[str, str] = {}
+
+    try:
+        request = get_http_request()
+        for name, value in request.headers.items():
+            lower_name = name.lower()
+            if lower_name not in exclude_headers:
+                headers[lower_name] = str(value)
+        return headers
+    except RuntimeError:
+        return {}
+
+
+def get_access_token() -> AccessToken | None:
+    """Get the FastMCP access token from the current context.
+
+    This function first tries to get the token from the current HTTP request's scope,
+    which is more reliable for long-lived connections where the SDK's auth_context_var
+    may become stale after token refresh. Falls back to the SDK's context var if no
+    request is available. In background tasks (Docket workers), falls back to the
+    token snapshot stored in Redis at task submission time.
+
+    Returns:
+        The access token if an authenticated user is available, None otherwise.
+    """
+    access_token: _SDKAccessToken | None = None
+
+    # First, try to get from current HTTP request's scope (issue #1863)
+    # This is more reliable than auth_context_var for Streamable HTTP sessions
+    # where tokens may be refreshed between MCP messages
+    try:
+        request = get_http_request()
+        user = request.scope.get("user")
+        if isinstance(user, AuthenticatedUser):
+            access_token = user.access_token
+    except RuntimeError:
+        # No HTTP request available, fall back to context var
+        pass
+
+    # Fall back to SDK's context var if we didn't get a token from the request
+    if access_token is None:
+        access_token = _sdk_get_access_token()
+
+    # Fall back to background task snapshot (#3095).  In Docket workers,
+    # neither the HTTP request nor the SDK context var is available; the
+    # snapshot is preloaded by restore_task_snapshot before user code runs.
+    if access_token is None:
+        task_info = get_task_context()
+        snapshot = _recall_snapshot(task_info.task_id) if task_info else None
+        if snapshot is not None and snapshot.access_token_json is not None:
+            task_token = AccessToken.model_validate_json(snapshot.access_token_json)
+            if task_token.expires_at is not None:
+                if task_token.expires_at < int(datetime.now(timezone.utc).timestamp()):
+                    return None
+            return task_token
+
+    if access_token is None or isinstance(access_token, AccessToken):
+        return access_token
+
+    # If the object is not a FastMCP AccessToken, convert it to one if the
+    # fields are compatible (e.g. `claims` is not present in the SDK's AccessToken).
+    # This is a workaround for the case where the SDK or auth provider returns a different type
+    # If it fails, it will raise a TypeError
+    try:
+        access_token_as_dict = access_token.model_dump()
+        return AccessToken(
+            token=access_token_as_dict["token"],
+            client_id=access_token_as_dict["client_id"],
+            scopes=access_token_as_dict["scopes"],
+            # Optional fields
+            expires_at=access_token_as_dict.get("expires_at"),
+            resource=access_token_as_dict.get("resource"),
+            claims=access_token_as_dict.get("claims") or {},
+        )
+    except Exception as e:
+        raise TypeError(
+            f"Expected fastmcp.server.auth.auth.AccessToken, got {type(access_token).__name__}. "
+            "Ensure the SDK is using the correct AccessToken type."
+        ) from e
+
+
+# --- Schema generation helper ---
+
+
+@lru_cache(maxsize=5000)
+def without_injected_parameters(
+    fn: Callable[..., Any], *, run_in_thread: bool = True
+) -> Callable[..., Any]:
+    """Create a wrapper function without injected parameters.
+
+    Returns a wrapper that excludes Context and Docket dependency parameters,
+    making it safe to use with Pydantic TypeAdapter for schema generation and
+    validation. The wrapper internally handles all dependency resolution and
+    Context injection when called.
+
+    Handles:
+    - Legacy Context injection (always works)
+    - Depends() injection (always works - uses docket or vendored DI engine)
+
+    Args:
+        fn: Original function with Context and/or dependencies
+        run_in_thread: For sync ``fn``, whether to dispatch the call to a worker
+            thread after resolving dependencies. Defaults to True. Set to False
+            to call ``fn`` inline on the event loop thread — required for
+            thread-affinity libraries (e.g. Windows COM). Ignored for async fns.
+
+    Returns:
+        Async wrapper function without injected parameters
+    """
+    from fastmcp.server.context import Context
+
+    # Identify parameters to exclude
+    context_kwarg = find_kwarg_by_type(fn, Context)
+    dependency_params = get_dependency_parameters(fn)
+
+    exclude = set()
+    if context_kwarg:
+        exclude.add(context_kwarg)
+    if dependency_params:
+        exclude.update(dependency_params.keys())
+
+    if not exclude:
+        return fn
+
+    # Build new signature with only user parameters
+    sig = inspect.signature(fn)
+    user_params = [
+        param for name, param in sig.parameters.items() if name not in exclude
+    ]
+    new_sig = inspect.Signature(user_params)
+
+    # Create async wrapper that handles dependency resolution
+    fn_is_async = is_coroutine_function(fn)
+
+    async def wrapper(**user_kwargs: Any) -> Any:
+        async with resolve_dependencies(fn, user_kwargs) as resolved_kwargs:
+            if fn_is_async:
+                return await fn(**resolved_kwargs)
+            elif run_in_thread:
+                # Run sync functions in threadpool to avoid blocking the event loop
+                result = await call_sync_fn_in_threadpool(fn, **resolved_kwargs)
+                # Handle sync wrappers that return awaitables (e.g., partial(async_fn))
+                if inspect.isawaitable(result):
+                    result = await result
+                return result
+            else:
+                # Call inline on the event loop thread (thread affinity opt-in).
+                result = fn(**resolved_kwargs)
+                if inspect.isawaitable(result):
+                    result = await result
+                return result
+
+    # Resolve string annotations (from `from __future__ import annotations`) using
+    # the original function's module context. The wrapper's __globals__ points to
+    # this module (dependencies.py) and is read-only, so some Pydantic versions
+    # can't resolve names like Annotated or Literal from string annotations.
+    try:
+        resolved_hints = get_type_hints(fn, include_extras=True)
+    except Exception:
+        resolved_hints = getattr(fn, "__annotations__", {})
+
+    wrapper.__signature__ = new_sig  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+    wrapper.__annotations__ = {
+        k: v for k, v in resolved_hints.items() if k not in exclude and k != "return"
+    }
+    wrapper.__name__ = getattr(fn, "__name__", "wrapper")
+    wrapper.__doc__ = getattr(fn, "__doc__", None)
+    wrapper.__module__ = fn.__module__
+    wrapper.__qualname__ = getattr(fn, "__qualname__", wrapper.__qualname__)
+
+    return wrapper
+
+
+# --- Dependency resolution ---
+
+
+@asynccontextmanager
+async def _resolve_fastmcp_dependencies(
+    fn: Callable[..., Any], arguments: dict[str, Any]
+) -> AsyncGenerator[dict[str, Any], None]:
+    """Resolve Docket dependencies for a FastMCP function.
+
+    Sets up the minimal context needed for Docket's Depends() to work:
+    - A cache for resolved dependencies
+    - An AsyncExitStack for managing context manager lifetimes
+
+    The Docket instance (for CurrentDocket dependency) is managed separately
+    by the server's lifespan and made available via ContextVar.
+
+    Note: This does NOT set up Docket's Execution context. If user code needs
+    Docket-specific dependencies like TaskArgument(), TaskKey(), etc., those
+    will fail with clear errors about missing context.
+
+    Args:
+        fn: The function to resolve dependencies for
+        arguments: The arguments passed to the function
+
+    Yields:
+        Dictionary of resolved dependencies merged with provided arguments
+    """
+    dependency_params = get_dependency_parameters(fn)
+
+    if not dependency_params:
+        yield arguments
+        return
+
+    # Initialize dependency cache and exit stack
+    cache_token = _Depends.cache.set({})
+    try:
+        async with AsyncExitStack() as stack:
+            stack_token = _Depends.stack.set(stack)
+            try:
+                resolved: dict[str, Any] = {}
+
+                for parameter, dependency in dependency_params.items():
+                    # If argument was explicitly provided, use that instead
+                    if parameter in arguments:
+                        resolved[parameter] = arguments[parameter]
+                        continue
+
+                    # Resolve the dependency
+                    try:
+                        resolved[parameter] = await stack.enter_async_context(
+                            dependency
+                        )
+                    except FastMCPError:
+                        # Let FastMCPError subclasses (ToolError, ResourceError, etc.)
+                        # propagate unchanged so they can be handled appropriately
+                        raise
+                    except Exception as error:
+                        fn_name = getattr(fn, "__name__", repr(fn))
+                        raise RuntimeError(
+                            f"Failed to resolve dependency '{parameter}' for {fn_name}"
+                        ) from error
+
+                # Merge resolved dependencies with provided arguments
+                final_arguments = {**arguments, **resolved}
+
+                yield final_arguments
+            finally:
+                _Depends.stack.reset(stack_token)
+    finally:
+        _Depends.cache.reset(cache_token)
+
+
+@asynccontextmanager
+async def resolve_dependencies(
+    fn: Callable[..., Any], arguments: dict[str, Any]
+) -> AsyncGenerator[dict[str, Any], None]:
+    """Resolve dependencies for a FastMCP function.
+
+    This function:
+    1. Filters out any dependency parameter names from user arguments (security)
+    2. Resolves Depends() parameters via the DI system
+
+    The filtering prevents external callers from overriding injected parameters by
+    providing values for dependency parameter names. This is a security feature.
+
+    Note: Context injection is handled via transform_context_annotations() which
+    converts `ctx: Context` to `ctx: Context = Depends(get_context)` at registration
+    time, so all injection goes through the unified DI system.
+
+    Args:
+        fn: The function to resolve dependencies for
+        arguments: User arguments (may contain keys that match dependency names,
+                  which will be filtered out)
+
+    Yields:
+        Dictionary of filtered user args + resolved dependencies
+
+    Example:
+        ```python
+        async with resolve_dependencies(my_tool, {"name": "Alice"}) as kwargs:
+            result = my_tool(**kwargs)
+            if inspect.isawaitable(result):
+                result = await result
+        ```
+    """
+    # Filter out dependency parameters from user arguments to prevent override
+    # This is a security measure - external callers should never be able to
+    # provide values for injected parameters
+    dependency_params = get_dependency_parameters(fn)
+    user_args = {k: v for k, v in arguments.items() if k not in dependency_params}
+
+    async with _resolve_fastmcp_dependencies(fn, user_args) as resolved_kwargs:
+        yield resolved_kwargs
+
+
+# --- Dependency classes ---
+# These must inherit from docket.dependencies.Dependency when docket is available
+# so that get_dependency_parameters can detect them.
+
+
+class _CurrentContext(Dependency["Context"]):
+    """Async context manager for Context dependency.
+
+    In foreground (request) mode: returns the active context from _current_context.
+    In background (Docket worker) mode: creates a task-aware Context with task_id
+    and loads the unified task snapshot from Redis.
+
+    The shared default instance is a stateless factory. All per-invocation
+    state lives on the returned Context or in task-local ContextVars, so
+    concurrent tasks never share mutable state.
+    """
+
+    async def __aenter__(self) -> Context:
+        from fastmcp.server.context import Context, _current_context
+
+        # Try foreground context first (normal MCP request)
+        context = _current_context.get()
+        if context is not None:
+            return context
+
+        # Check if we're in a Docket worker context
+        task_info = get_task_context()
+        if task_info is not None:
+            server = get_server()
+
+            # The snapshot is preloaded by restore_task_snapshot (worker-level
+            # Docket dependency) before any task code runs, so this is a pure
+            # ContextVar read — no Redis I/O here.
+            snapshot = _recall_snapshot(task_info.task_id)
+            origin_request_id = snapshot.origin_request_id if snapshot else None
+
+            # Session ID is stored in the snapshot for notification delivery
+            snapshot_session_id = snapshot.session_id if snapshot else None
+            session = (
+                get_task_session(snapshot_session_id) if snapshot_session_id else None
+            )
+
+            ctx = Context(
+                fastmcp=server,
+                session=session,
+                task_id=task_info.task_id,
+                origin_request_id=origin_request_id,
+            )
+            await ctx.__aenter__()
+            return ctx
+
+        raise RuntimeError(
+            "No active context found. This can happen if:\n"
+            "  - Called outside an MCP request handler\n"
+            "  - Called in a background task before session was registered\n"
+            "Check `context.request_context` for None before accessing."
+        )
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        from fastmcp.server.context import _current_context
+
+        ctx = _current_context.get()
+        if ctx is not None and ctx.is_background_task:
+            await ctx.__aexit__(exc_type, exc_value, traceback)
+
+
+class _OptionalCurrentContext(Dependency["Context | None"]):
+    """Context dependency that returns None instead of raising when no context
+    is active. Used for ``ctx: Context = None`` parameter patterns.
+
+    Delegates entirely to ``_CurrentContext`` — just catches the RuntimeError.
+    Cleanup is handled by ``_CurrentContext.__aexit__`` reading from the
+    task-local ContextVar.
+    """
+
+    async def __aenter__(self) -> Context | None:
+        try:
+            return await _CurrentContext().__aenter__()
+        except RuntimeError as exc:
+            if "No active context found" in str(exc):
+                return None
+            raise
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        from fastmcp.server.context import _current_context
+
+        ctx = _current_context.get()
+        if ctx is not None and ctx.is_background_task:
+            await _CurrentContext().__aexit__(exc_type, exc_value, traceback)
+
+
+def CurrentContext() -> Context:
+    """Get the current FastMCP Context instance.
+
+    This dependency provides access to the active FastMCP Context for the
+    current MCP operation (tool/resource/prompt call).
+
+    Returns:
+        A dependency that resolves to the active Context instance
+
+    Raises:
+        RuntimeError: If no active context found (during resolution)
+
+    Example:
+        ```python
+        from fastmcp.dependencies import CurrentContext
+
+        @mcp.tool()
+        async def log_progress(ctx: Context = CurrentContext()) -> str:
+            ctx.report_progress(50, 100, "Halfway done")
+            return "Working"
+        ```
+    """
+    return cast("Context", _CurrentContext())
+
+
+def OptionalCurrentContext() -> Context | None:
+    """Get the current FastMCP Context, or None when no context is active."""
+    return cast("Context | None", _OptionalCurrentContext())
+
+
+class _CurrentDocket(Dependency["Docket"]):
+    """Async context manager for Docket dependency."""
+
+    async def __aenter__(self) -> Docket:
+        require_docket("CurrentDocket()")
+        # Check server instance first, fall back to ContextVar for mounted children
+        # whose parent owns the Docket
+        try:
+            docket = get_server()._docket
+        except RuntimeError:
+            docket = None
+        if docket is None:
+            docket = _current_docket.get()
+        if docket is None:
+            raise RuntimeError(
+                "No Docket instance found. Docket is only initialized when there are "
+                "task-enabled components (task=True). Add task=True to a component "
+                "to enable Docket infrastructure."
+            )
+        return docket
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        pass
+
+
+def CurrentDocket() -> Docket:
+    """Get the current Docket instance managed by FastMCP.
+
+    This dependency provides access to the Docket instance that FastMCP
+    automatically creates for background task scheduling.
+
+    Returns:
+        A dependency that resolves to the active Docket instance
+
+    Raises:
+        RuntimeError: If not within a FastMCP server context
+        ImportError: If fastmcp[tasks] not installed
+
+    Example:
+        ```python
+        from fastmcp.dependencies import CurrentDocket
+
+        @mcp.tool()
+        async def schedule_task(docket: Docket = CurrentDocket()) -> str:
+            await docket.add(some_function)(arg1, arg2)
+            return "Scheduled"
+        ```
+    """
+    require_docket("CurrentDocket()")
+    return cast("Docket", _CurrentDocket())
+
+
+class _CurrentWorker(Dependency["Worker"]):
+    """Async context manager for Worker dependency."""
+
+    async def __aenter__(self) -> Worker:
+        require_docket("CurrentWorker()")
+        # Check server instance first, fall back to ContextVar for mounted children
+        try:
+            worker = get_server()._worker
+        except RuntimeError:
+            worker = None
+        if worker is None:
+            worker = _current_worker.get()
+        if worker is None:
+            raise RuntimeError(
+                "No Worker instance found. Worker is only initialized when there are "
+                "task-enabled components (task=True). Add task=True to a component "
+                "to enable Docket infrastructure."
+            )
+        return worker
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        pass
+
+
+def CurrentWorker() -> Worker:
+    """Get the current Docket Worker instance managed by FastMCP.
+
+    This dependency provides access to the Worker instance that FastMCP
+    automatically creates for background task processing.
+
+    Returns:
+        A dependency that resolves to the active Worker instance
+
+    Raises:
+        RuntimeError: If not within a FastMCP server context
+        ImportError: If fastmcp[tasks] not installed
+
+    Example:
+        ```python
+        from fastmcp.dependencies import CurrentWorker
+
+        @mcp.tool()
+        async def check_worker_status(worker: Worker = CurrentWorker()) -> str:
+            return f"Worker: {worker.name}"
+        ```
+    """
+    require_docket("CurrentWorker()")
+    return cast("Worker", _CurrentWorker())
+
+
+class _CurrentFastMCP(Dependency["FastMCP"]):
+    """Async context manager for FastMCP server dependency."""
+
+    async def __aenter__(self) -> FastMCP:
+        return get_server()
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        pass
+
+
+def CurrentFastMCP() -> FastMCP:
+    """Get the current FastMCP server instance.
+
+    This dependency provides access to the active FastMCP server.
+
+    Returns:
+        A dependency that resolves to the active FastMCP server
+
+    Raises:
+        RuntimeError: If no server in context (during resolution)
+
+    Example:
+        ```python
+        from fastmcp.dependencies import CurrentFastMCP
+
+        @mcp.tool()
+        async def introspect(server: FastMCP = CurrentFastMCP()) -> str:
+            return f"Server: {server.name}"
+        ```
+    """
+    from fastmcp.server.server import FastMCP
+
+    return cast(FastMCP, _CurrentFastMCP())
+
+
+class _CurrentRequest(Dependency[Request]):
+    """Async context manager for HTTP Request dependency."""
+
+    async def __aenter__(self) -> Request:
+        return get_http_request()
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        pass
+
+
+def CurrentRequest() -> Request:
+    """Get the current HTTP request.
+
+    This dependency provides access to the Starlette Request object for the
+    current HTTP request. Only available when running over HTTP transports
+    (SSE or Streamable HTTP).
+
+    Returns:
+        A dependency that resolves to the active Starlette Request
+
+    Raises:
+        RuntimeError: If no HTTP request in context (e.g., STDIO transport)
+
+    Example:
+        ```python
+        from fastmcp.server.dependencies import CurrentRequest
+        from starlette.requests import Request
+
+        @mcp.tool()
+        async def get_client_ip(request: Request = CurrentRequest()) -> str:
+            return request.client.host if request.client else "Unknown"
+        ```
+    """
+    return cast(Request, _CurrentRequest())
+
+
+class _CurrentHeaders(Dependency[dict[str, str]]):
+    """Async context manager for HTTP Headers dependency."""
+
+    async def __aenter__(self) -> dict[str, str]:
+        return get_http_headers(include={"authorization"})
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        pass
+
+
+def CurrentHeaders() -> dict[str, str]:
+    """Get the current HTTP request headers.
+
+    This dependency provides access to the HTTP headers for the current request,
+    including the authorization header. Returns an empty dictionary when no HTTP
+    request is available, making it safe to use in code that might run over any
+    transport.
+
+    Returns:
+        A dependency that resolves to a dictionary of header name -> value
+
+    Example:
+        ```python
+        from fastmcp.server.dependencies import CurrentHeaders
+
+        @mcp.tool()
+        async def get_auth_type(headers: dict = CurrentHeaders()) -> str:
+            auth = headers.get("authorization", "")
+            return "Bearer" if auth.startswith("Bearer ") else "None"
+        ```
+    """
+    return cast(dict[str, str], _CurrentHeaders())
+
+
+# --- Progress dependency ---
+
+
+@runtime_checkable
+class ProgressLike(Protocol):
+    """Protocol for progress tracking interface.
+
+    Defines the common interface between InMemoryProgress (server context)
+    and Docket's Progress (worker context).
+    """
+
+    @property
+    def current(self) -> int | None:
+        """Current progress value."""
+        ...
+
+    @property
+    def total(self) -> int:
+        """Total/target progress value."""
+        ...
+
+    @property
+    def message(self) -> str | None:
+        """Current progress message."""
+        ...
+
+    async def set_total(self, total: int) -> None:
+        """Set the total/target value for progress tracking."""
+        ...
+
+    async def increment(self, amount: int = 1) -> None:
+        """Atomically increment the current progress value."""
+        ...
+
+    async def set_message(self, message: str | None) -> None:
+        """Update the progress status message."""
+        ...
+
+
+class InMemoryProgress:
+    """In-memory progress tracker for immediate tool execution.
+
+    Provides the same interface as Docket's Progress but stores state in memory
+    instead of Redis. Useful for testing and immediate execution where
+    progress doesn't need to be observable across processes.
+    """
+
+    def __init__(self) -> None:
+        self._current: int | None = None
+        self._total: int = 1
+        self._message: str | None = None
+
+    async def __aenter__(self) -> InMemoryProgress:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        pass
+
+    @property
+    def current(self) -> int | None:
+        return self._current
+
+    @property
+    def total(self) -> int:
+        return self._total
+
+    @property
+    def message(self) -> str | None:
+        return self._message
+
+    async def set_total(self, total: int) -> None:
+        """Set the total/target value for progress tracking."""
+        if total < 1:
+            raise ValueError("Total must be at least 1")
+        self._total = total
+
+    async def increment(self, amount: int = 1) -> None:
+        """Atomically increment the current progress value."""
+        if amount < 1:
+            raise ValueError("Amount must be at least 1")
+        if self._current is None:
+            self._current = amount
+        else:
+            self._current += amount
+
+    async def set_message(self, message: str | None) -> None:
+        """Update the progress status message."""
+        self._message = message
+
+
+class Progress(Dependency["Progress"]):
+    """Progress dependency that works in both server and worker contexts.
+
+    In a Docket worker, delegates to the execution's Redis-backed progress
+    (observable across processes). Otherwise, uses in-memory tracking.
+
+    The shared default instance acts as a stateless factory — ``__aenter__``
+    creates a fresh ``Progress`` per invocation so concurrent tasks never
+    share mutable state.
+    """
+
+    _impl: ProgressLike | None = None
+
+    async def __aenter__(self) -> Progress:
+        server_ref = _current_server.get()
+        if server_ref is None or server_ref() is None:
+            raise RuntimeError("Progress dependency requires a FastMCP server context.")
+
+        instance = Progress()
+
+        if is_docket_available():
+            try:
+                from docket.dependencies import current_execution
+
+                instance._impl = current_execution.get().progress
+                return instance
+            except LookupError:
+                pass
+
+        instance._impl = InMemoryProgress()
+        return instance
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        pass
+
+    @property
+    def current(self) -> int | None:
+        """Current progress value."""
+        assert self._impl is not None, "Progress must be used as a dependency"
+        return self._impl.current
+
+    @property
+    def total(self) -> int:
+        """Total/target progress value."""
+        assert self._impl is not None, "Progress must be used as a dependency"
+        return self._impl.total
+
+    @property
+    def message(self) -> str | None:
+        """Current progress message."""
+        assert self._impl is not None, "Progress must be used as a dependency"
+        return self._impl.message
+
+    async def set_total(self, total: int) -> None:
+        """Set the total/target value for progress tracking."""
+        assert self._impl is not None, "Progress must be used as a dependency"
+        await self._impl.set_total(total)
+
+    async def increment(self, amount: int = 1) -> None:
+        """Atomically increment the current progress value."""
+        assert self._impl is not None, "Progress must be used as a dependency"
+        await self._impl.increment(amount)
+
+    async def set_message(self, message: str | None) -> None:
+        """Update the progress status message."""
+        assert self._impl is not None, "Progress must be used as a dependency"
+        await self._impl.set_message(message)
+
+
+# --- Access Token dependency ---
+
+
+class _CurrentAccessToken(Dependency[AccessToken]):
+    """Async context manager for AccessToken dependency."""
+
+    async def __aenter__(self) -> AccessToken:
+        token = get_access_token()
+
+        if token is None:
+            raise RuntimeError(
+                "No access token found. Ensure authentication is configured "
+                "and the request is authenticated."
+            )
+        return token
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        pass
+
+
+def CurrentAccessToken() -> AccessToken:
+    """Get the current access token for the authenticated user.
+
+    This dependency provides access to the AccessToken for the current
+    authenticated request. Raises an error if no authentication is present.
+
+    Returns:
+        A dependency that resolves to the active AccessToken
+
+    Raises:
+        RuntimeError: If no authenticated user (use get_access_token() for optional)
+
+    Example:
+        ```python
+        from fastmcp.server.dependencies import CurrentAccessToken
+        from fastmcp.server.auth import AccessToken
+
+        @mcp.tool()
+        async def get_user_id(token: AccessToken = CurrentAccessToken()) -> str:
+            return token.claims.get("sub", "unknown")
+        ```
+    """
+    return cast(AccessToken, _CurrentAccessToken())
+
+
+# --- Token Claim dependency ---
+
+
+class _TokenClaim(Dependency[str]):
+    """Dependency that extracts a specific claim from the access token."""
+
+    def __init__(self, claim_name: str):
+        self.claim_name = claim_name
+
+    async def __aenter__(self) -> str:
+        token = get_access_token()
+        if token is None:
+            raise RuntimeError(
+                f"No access token available. Cannot extract claim '{self.claim_name}'."
+            )
+        value = token.claims.get(self.claim_name)
+        if value is None:
+            raise RuntimeError(
+                f"Claim '{self.claim_name}' not found in access token. "
+                f"Available claims: {list(token.claims.keys())}"
+            )
+        return str(value)
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        pass
+
+
+def TokenClaim(name: str) -> str:
+    """Get a specific claim from the access token.
+
+    This dependency extracts a single claim value from the current access token.
+    It's useful for getting user identifiers, roles, or other token claims
+    without needing the full token object.
+
+    Args:
+        name: The name of the claim to extract (e.g., "oid", "sub", "email")
+
+    Returns:
+        A dependency that resolves to the claim value as a string
+
+    Raises:
+        RuntimeError: If no access token is available or claim is missing
+
+    Example:
+        ```python
+        from fastmcp.server.dependencies import TokenClaim
+
+        @mcp.tool()
+        async def add_expense(
+            user_id: str = TokenClaim("oid"),  # Azure object ID
+            amount: float,
+        ):
+            # user_id is automatically injected from the token
+            await db.insert({"user_id": user_id, "amount": amount})
+        ```
+    """
+    return cast(str, _TokenClaim(name))
diff --git a/fastmcp_slim/fastmcp/server/elicitation.py b/fastmcp_slim/fastmcp/server/elicitation.py
new file mode 100644
index 0000000..5947d22
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/elicitation.py
@@ -0,0 +1,508 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Generic, Literal, cast, get_origin
+
+from mcp.server.elicitation import (
+    CancelledElicitation,
+    DeclinedElicitation,
+)
+from pydantic import BaseModel
+from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue
+from pydantic_core import core_schema
+from typing_extensions import TypeVar
+
+from fastmcp.utilities.json_schema import compress_schema
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import get_cached_typeadapter
+
+__all__ = [
+    "AcceptedElicitation",
+    "CancelledElicitation",
+    "DeclinedElicitation",
+    "ElicitConfig",
+    "ScalarElicitationType",
+    "get_elicitation_schema",
+    "handle_elicit_accept",
+    "parse_elicit_response_type",
+]
+
+logger = get_logger(__name__)
+
+T = TypeVar("T", default=Any)
+
+
+class ElicitationJsonSchema(GenerateJsonSchema):
+    """Custom JSON schema generator for MCP elicitation that always inlines enums.
+
+    MCP elicitation requires inline enum schemas without $ref/$defs references.
+    This generator ensures enums are always generated inline for compatibility.
+    Optionally adds enumNames for better UI display when available.
+    """
+
+    def generate_inner(self, schema: core_schema.CoreSchema) -> JsonSchemaValue:  # type: ignore[override]  # ty:ignore[invalid-method-override]
+        """Override to prevent ref generation for enums and handle list schemas."""
+        # For enum schemas, bypass the ref mechanism entirely
+        if schema["type"] == "enum":
+            # Directly call our custom enum_schema without going through handler
+            # This prevents the ref/defs mechanism from being invoked
+            return self.enum_schema(schema)
+        # For list schemas, check if items are enums
+        if schema["type"] == "list":
+            return self.list_schema(schema)
+        # For all other types, use the default implementation
+        return super().generate_inner(schema)
+
+    def list_schema(self, schema: core_schema.ListSchema) -> JsonSchemaValue:
+        """Generate schema for list types, detecting enum items for multi-select."""
+        items_schema = schema.get("items_schema")
+
+        # Check if items are enum/Literal
+        if items_schema and items_schema.get("type") == "enum":
+            # Generate array with enum items
+            items = self.enum_schema(items_schema)  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+            # If items have oneOf pattern, convert to anyOf for multi-select per SEP-1330
+            if "oneOf" in items:
+                items = {"anyOf": items["oneOf"]}
+            return {
+                "type": "array",
+                "items": items,  # Will be {"enum": [...]} or {"anyOf": [...]}
+            }
+
+        # Check if items are Literal (which Pydantic represents differently)
+        if items_schema:
+            # Try to detect Literal patterns
+            items_result = super().generate_inner(items_schema)
+            # If it's a const pattern or enum-like, allow it
+            if (
+                "const" in items_result
+                or "enum" in items_result
+                or "oneOf" in items_result
+            ):
+                # Convert oneOf to anyOf for multi-select
+                if "oneOf" in items_result:
+                    items_result = {"anyOf": items_result["oneOf"]}
+                return {
+                    "type": "array",
+                    "items": items_result,
+                }
+
+        # Default behavior for non-enum arrays
+        return super().list_schema(schema)
+
+    def enum_schema(self, schema: core_schema.EnumSchema) -> JsonSchemaValue:
+        """Generate inline enum schema.
+
+        Always generates enum pattern: `{"enum": [value, ...]}`
+        Titled enums are handled separately via dict-based syntax in ctx.elicit().
+        """
+        # Get the base schema from parent - always use simple enum pattern
+        return super().enum_schema(schema)
+
+
+# we can't use the low-level AcceptedElicitation because it only works with BaseModels
+class AcceptedElicitation(BaseModel, Generic[T]):
+    """Result when user accepts the elicitation."""
+
+    action: Literal["accept"] = "accept"
+    data: T
+
+
+@dataclass
+class ScalarElicitationType(Generic[T]):
+    value: T
+
+
+@dataclass
+class ElicitConfig:
+    """Configuration for an elicitation request.
+
+    Attributes:
+        schema: The JSON schema to send to the client
+        response_type: The type to validate responses with (None for raw schemas)
+        is_raw: True if schema was built directly (extract "value" from response)
+    """
+
+    schema: dict[str, Any]
+    response_type: type | None
+    is_raw: bool
+
+
+def parse_elicit_response_type(
+    response_type: Any,
+    response_title: str | None = None,
+    response_description: str | None = None,
+) -> ElicitConfig:
+    """Parse response_type into schema and handling configuration.
+
+    Supports multiple syntaxes:
+    - None: Empty object schema, expect empty response
+    - dict: `{"low": {"title": "..."}}` -> single-select titled enum
+    - list patterns:
+        - `[["a", "b"]]` -> multi-select untitled
+        - `[{"low": {...}}]` -> multi-select titled
+        - `["a", "b"]` -> single-select untitled
+    - `list[X]` type annotation: multi-select with type
+    - Scalar types (bool, int, float, str, Literal, Enum): single value
+    - Other types (dataclass, BaseModel): use directly
+
+    The ``response_title`` and ``response_description`` arguments customize the
+    label and description of the wrapped ``value`` property for the scalar/dict/list
+    shorthand forms. They are only valid when FastMCP is wrapping the response
+    type; passing them with a full BaseModel/dataclass (or ``None``) raises
+    ``TypeError``, because in those cases the user already controls field
+    metadata via ``Field(title=..., description=...)``.
+    """
+    has_response_metadata = (
+        response_title is not None or response_description is not None
+    )
+
+    if response_type is None:
+        if has_response_metadata:
+            raise TypeError(
+                "response_title and response_description are not supported when "
+                "response_type is None, because the elicitation schema has no "
+                "fields to label."
+            )
+        return ElicitConfig(
+            schema={"type": "object", "properties": {}},
+            response_type=None,
+            is_raw=False,
+        )
+
+    if isinstance(response_type, dict):
+        config = _parse_dict_syntax(response_type)
+    elif isinstance(response_type, list):
+        config = _parse_list_syntax(response_type)
+    elif get_origin(response_type) is list:
+        config = _parse_generic_list(response_type)
+    elif _is_scalar_type(response_type):
+        config = _parse_scalar_type(response_type)
+    else:
+        # Other types (dataclass, BaseModel, etc.) - use directly
+        if has_response_metadata:
+            raise TypeError(
+                "response_title and response_description are only supported when "
+                "response_type is a scalar, Literal, Enum, or the dict/list "
+                "shorthand forms. For BaseModel or dataclass response types, use "
+                "Field(title=..., description=...) on the individual fields."
+            )
+        return ElicitConfig(
+            schema=get_elicitation_schema(response_type),
+            response_type=response_type,
+            is_raw=False,
+        )
+
+    if has_response_metadata:
+        _apply_value_metadata(config.schema, response_title, response_description)
+    return config
+
+
+def _apply_value_metadata(
+    schema: dict[str, Any],
+    title: str | None,
+    description: str | None,
+) -> None:
+    """Override title/description on the wrapped ``value`` property in-place."""
+    value_schema = schema.get("properties", {}).get("value")
+    if value_schema is None:
+        return
+    if title is not None:
+        value_schema["title"] = title
+    if description is not None:
+        value_schema["description"] = description
+
+
+def _is_scalar_type(response_type: Any) -> bool:
+    """Check if response_type is a scalar type that needs wrapping."""
+    return (
+        response_type in {bool, int, float, str}
+        or get_origin(response_type) is Literal
+        or (isinstance(response_type, type) and issubclass(response_type, Enum))
+    )
+
+
+def _parse_dict_syntax(d: dict[str, Any]) -> ElicitConfig:
+    """Parse dict syntax: {"low": {"title": "..."}} -> single-select titled."""
+    if not d:
+        raise ValueError("Dict response_type cannot be empty.")
+    enum_schema = _dict_to_enum_schema(d, multi_select=False)
+    return ElicitConfig(
+        schema={
+            "type": "object",
+            "properties": {"value": enum_schema},
+            "required": ["value"],
+        },
+        response_type=None,
+        is_raw=True,
+    )
+
+
+def _parse_list_syntax(lst: list[Any]) -> ElicitConfig:
+    """Parse list patterns: [[...]], [{...}], or [...]."""
+    # [["a", "b", "c"]] -> multi-select untitled
+    if (
+        len(lst) == 1
+        and isinstance(lst[0], list)
+        and lst[0]
+        and all(isinstance(item, str) for item in lst[0])
+    ):
+        return ElicitConfig(
+            schema={
+                "type": "object",
+                "properties": {"value": {"type": "array", "items": {"enum": lst[0]}}},
+                "required": ["value"],
+            },
+            response_type=None,
+            is_raw=True,
+        )
+
+    # [{"low": {"title": "..."}}] -> multi-select titled
+    if len(lst) == 1 and isinstance(lst[0], dict) and lst[0]:
+        enum_schema = _dict_to_enum_schema(lst[0], multi_select=True)
+        return ElicitConfig(
+            schema={
+                "type": "object",
+                "properties": {"value": {"type": "array", "items": enum_schema}},
+                "required": ["value"],
+            },
+            response_type=None,
+            is_raw=True,
+        )
+
+    # ["a", "b", "c"] -> single-select untitled
+    if lst and all(isinstance(item, str) for item in lst):
+        # Construct Literal type from tuple - use cast since we can't construct Literal dynamically
+        # but we know the values are all strings
+        choice_literal: type[Any] = cast(type[Any], Literal[tuple(lst)])  # type: ignore[valid-type]  # ty:ignore[invalid-type-form]
+        wrapped = ScalarElicitationType[choice_literal]  # type: ignore[valid-type]  # ty:ignore[invalid-type-form]
+        return ElicitConfig(
+            schema=get_elicitation_schema(wrapped),
+            response_type=wrapped,
+            is_raw=False,
+        )
+
+    raise ValueError(f"Invalid list response_type format. Received: {lst}")
+
+
+def _parse_generic_list(response_type: Any) -> ElicitConfig:
+    """Parse list[X] type annotation -> multi-select."""
+    wrapped = ScalarElicitationType[response_type]
+    return ElicitConfig(
+        schema=get_elicitation_schema(wrapped),
+        response_type=wrapped,
+        is_raw=False,
+    )
+
+
+def _parse_scalar_type(response_type: Any) -> ElicitConfig:
+    """Parse scalar types (bool, int, float, str, Literal, Enum)."""
+    wrapped = ScalarElicitationType[response_type]
+    return ElicitConfig(
+        schema=get_elicitation_schema(wrapped),
+        response_type=wrapped,
+        is_raw=False,
+    )
+
+
+def handle_elicit_accept(
+    config: ElicitConfig, content: Any
+) -> AcceptedElicitation[Any]:
+    """Handle an accepted elicitation response.
+
+    Args:
+        config: The elicitation configuration from parse_elicit_response_type
+        content: The response content from the client
+
+    Returns:
+        AcceptedElicitation with the extracted/validated data
+    """
+    # For raw schemas (dict/nested-list syntax), extract value directly
+    if config.is_raw:
+        if not isinstance(content, dict) or "value" not in content:
+            raise ValueError("Elicitation response missing required 'value' field.")
+        return AcceptedElicitation[Any](data=content["value"])
+
+    # For typed schemas, validate with Pydantic
+    if config.response_type is not None:
+        type_adapter = get_cached_typeadapter(config.response_type)
+        validated_data = type_adapter.validate_python(content)
+        if isinstance(validated_data, ScalarElicitationType):
+            return AcceptedElicitation[Any](data=validated_data.value)
+        return AcceptedElicitation[Any](data=validated_data)
+
+    # For None response_type, expect empty response
+    if content:
+        raise ValueError(
+            f"Elicitation expected an empty response, but received: {content}"
+        )
+    return AcceptedElicitation[dict[str, Any]](data={})
+
+
+def _dict_to_enum_schema(
+    enum_dict: dict[str, dict[str, str]], multi_select: bool = False
+) -> dict[str, Any]:
+    """Convert dict enum to SEP-1330 compliant schema pattern.
+
+    Args:
+        enum_dict: {"low": {"title": "Low Priority"}, "medium": {"title": "Medium Priority"}}
+        multi_select: If True, use anyOf pattern; if False, use oneOf pattern
+
+    Returns:
+        {"type": "string", "oneOf": [...]} for single-select
+        {"anyOf": [...]} for multi-select (used as array items)
+    """
+    pattern_key = "anyOf" if multi_select else "oneOf"
+    pattern = []
+    for value, metadata in enum_dict.items():
+        title = metadata.get("title", value)
+        pattern.append({"const": value, "title": title})
+
+    result: dict[str, Any] = {pattern_key: pattern}
+    if not multi_select:
+        result["type"] = "string"
+    return result
+
+
+def get_elicitation_schema(response_type: type[T]) -> dict[str, Any]:
+    """Get the schema for an elicitation response.
+
+    Args:
+        response_type: The type of the response
+    """
+
+    # Use custom schema generator that inlines enums for MCP compatibility
+    schema = get_cached_typeadapter(response_type).json_schema(
+        schema_generator=ElicitationJsonSchema
+    )
+    schema = compress_schema(schema)
+
+    # Validate the schema to ensure it follows MCP elicitation requirements
+    validate_elicitation_json_schema(schema)
+
+    return schema
+
+
+def validate_elicitation_json_schema(schema: dict[str, Any]) -> None:
+    """Validate that a JSON schema follows MCP elicitation requirements.
+
+    This ensures the schema is compatible with MCP elicitation requirements:
+    - Must be an object schema
+    - Must only contain primitive field types (string, number, integer, boolean)
+    - Must be flat (no nested objects or arrays of objects)
+    - Allows const fields (for Literal types) and enum fields (for Enum types)
+    - Only primitive types and their nullable variants are allowed
+
+    Args:
+        schema: The JSON schema to validate
+
+    Raises:
+        TypeError: If the schema doesn't meet MCP elicitation requirements
+    """
+    ALLOWED_TYPES = {"string", "number", "integer", "boolean"}
+
+    # Check that the schema is an object
+    if schema.get("type") != "object":
+        raise TypeError(
+            f"Elicitation schema must be an object schema, got type '{schema.get('type')}'. "
+            "Elicitation schemas are limited to flat objects with primitive properties only."
+        )
+
+    properties = schema.get("properties", {})
+
+    for prop_name, prop_schema in properties.items():
+        prop_type = prop_schema.get("type")
+
+        # Handle nullable types
+        if isinstance(prop_type, list):
+            if "null" in prop_type:
+                prop_type = [t for t in prop_type if t != "null"]
+                if len(prop_type) == 1:
+                    prop_type = prop_type[0]
+        elif prop_schema.get("nullable", False):
+            continue  # Nullable with no other type is fine
+
+        # Handle const fields (Literal types)
+        if "const" in prop_schema:
+            continue  # const fields are allowed regardless of type
+
+        # Handle enum fields (Enum types)
+        if "enum" in prop_schema:
+            continue  # enum fields are allowed regardless of type
+
+        # Handle references to definitions (like Enum types)
+        if "$ref" in prop_schema:
+            # Get the referenced definition
+            ref_path = prop_schema["$ref"]
+            if ref_path.startswith("#/$defs/"):
+                def_name = ref_path[8:]  # Remove "#/$defs/" prefix
+                ref_def = schema.get("$defs", {}).get(def_name, {})
+                # If the referenced definition has an enum, it's allowed
+                if "enum" in ref_def:
+                    continue
+                # If the referenced definition has a type that's allowed, it's allowed
+                ref_type = ref_def.get("type")
+                if ref_type in ALLOWED_TYPES:
+                    continue
+            # If we can't determine what the ref points to, reject it for safety
+            raise TypeError(
+                f"Elicitation schema field '{prop_name}' contains a reference '{ref_path}' "
+                "that could not be validated. Only references to enum types or primitive types are allowed."
+            )
+
+        # Handle union types (oneOf/anyOf)
+        if "oneOf" in prop_schema or "anyOf" in prop_schema:
+            union_schemas = prop_schema.get("oneOf", []) + prop_schema.get("anyOf", [])
+            for union_schema in union_schemas:
+                # Allow const and enum in unions
+                if "const" in union_schema or "enum" in union_schema:
+                    continue
+                union_type = union_schema.get("type")
+                if union_type not in ALLOWED_TYPES:
+                    raise TypeError(
+                        f"Elicitation schema field '{prop_name}' has union type '{union_type}' which is not "
+                        f"a primitive type. Only {ALLOWED_TYPES} are allowed in elicitation schemas."
+                    )
+            continue
+
+        # Check for arrays before checking primitive types
+        if prop_type == "array":
+            items_schema = prop_schema.get("items", {})
+            if items_schema.get("type") == "object":
+                raise TypeError(
+                    f"Elicitation schema field '{prop_name}' is an array of objects, but arrays of objects are not allowed. "
+                    "Elicitation schemas must be flat objects with primitive properties only."
+                )
+
+            # Allow arrays with enum patterns (for multi-select)
+            if "enum" in items_schema:
+                continue  # Allowed: {"type": "array", "items": {"enum": [...]}}
+
+            # Allow arrays with oneOf/anyOf const patterns (SEP-1330)
+            if "oneOf" in items_schema or "anyOf" in items_schema:
+                union_schemas = items_schema.get("oneOf", []) + items_schema.get(
+                    "anyOf", []
+                )
+                if union_schemas and all("const" in s for s in union_schemas):
+                    continue  # Allowed: {"type": "array", "items": {"anyOf": [{"const": ...}, ...]}}
+
+            # Reject other array types (e.g., arrays of primitives without enum pattern)
+            raise TypeError(
+                f"Elicitation schema field '{prop_name}' is an array, but arrays are only allowed "
+                "when items are enums (for multi-select). Only enum arrays are supported in elicitation schemas."
+            )
+
+        # Check for nested objects (not allowed)
+        if prop_type == "object":
+            raise TypeError(
+                f"Elicitation schema field '{prop_name}' is an object, but nested objects are not allowed. "
+                "Elicitation schemas must be flat objects with primitive properties only."
+            )
+
+        # Check if it's a primitive type
+        if prop_type not in ALLOWED_TYPES:
+            raise TypeError(
+                f"Elicitation schema field '{prop_name}' has type '{prop_type}' which is not "
+                f"a primitive type. Only {ALLOWED_TYPES} are allowed in elicitation schemas."
+            )
diff --git a/fastmcp_slim/fastmcp/server/event_store.py b/fastmcp_slim/fastmcp/server/event_store.py
new file mode 100644
index 0000000..86897aa
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/event_store.py
@@ -0,0 +1,234 @@
+"""EventStore implementation backed by AsyncKeyValue.
+
+This module provides an EventStore implementation that enables SSE polling/resumability
+for Streamable HTTP transports. Events are stored using the key_value package's
+AsyncKeyValue protocol, allowing users to configure any compatible backend
+(in-memory, Redis, etc.) following the same pattern as ResponseCachingMiddleware.
+"""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+from key_value.aio.adapters.pydantic import PydanticAdapter
+from key_value.aio.protocols import AsyncKeyValue
+from key_value.aio.stores.memory import MemoryStore
+from mcp.server.streamable_http import EventCallback, EventId, EventMessage, StreamId
+from mcp.server.streamable_http import EventStore as SDKEventStore
+from mcp_types import JSONRPCMessage
+from pydantic import TypeAdapter
+
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import FastMCPBaseModel
+
+logger = get_logger(__name__)
+
+# In the v2 SDK `JSONRPCMessage` is a bare union (no `.model_validate`); use a
+# TypeAdapter to validate a stored dict back into the correct member.
+_jsonrpc_message_adapter: TypeAdapter[JSONRPCMessage] = TypeAdapter(JSONRPCMessage)
+
+
+class EventEntry(FastMCPBaseModel):
+    """Stored event entry."""
+
+    event_id: str
+    stream_id: str
+    message: dict | None  # JSONRPCMessage serialized to dict
+
+
+class StreamEventList(FastMCPBaseModel):
+    """List of event IDs for a stream."""
+
+    event_ids: list[str]
+
+
+class SessionScopedEventStore(SDKEventStore):
+    """EventStore adapter that isolates stream IDs to one transport session."""
+
+    def __init__(self, event_store: SDKEventStore, session_id: str):
+        self._event_store = event_store
+        self._stream_prefix = f"{len(session_id)}:{session_id}:"
+
+    def _scope_stream_id(self, stream_id: StreamId) -> StreamId:
+        return f"{self._stream_prefix}{stream_id}"
+
+    def _unscope_stream_id(self, stream_id: StreamId) -> StreamId | None:
+        if not stream_id.startswith(self._stream_prefix):
+            return None
+        return stream_id[len(self._stream_prefix) :]
+
+    async def store_event(
+        self, stream_id: StreamId, message: JSONRPCMessage | None
+    ) -> EventId:
+        return await self._event_store.store_event(
+            self._scope_stream_id(stream_id), message
+        )
+
+    async def replay_events_after(
+        self,
+        last_event_id: EventId,
+        send_callback: EventCallback,
+    ) -> StreamId | None:
+        replayed_events: list[EventMessage] = []
+
+        async def buffer_event(event: EventMessage) -> None:
+            replayed_events.append(event)
+
+        scoped_stream_id = await self._event_store.replay_events_after(
+            last_event_id, buffer_event
+        )
+        if scoped_stream_id is None:
+            return None
+
+        stream_id = self._unscope_stream_id(scoped_stream_id)
+        if stream_id is None:
+            logger.warning(
+                "Event ID %s does not belong to this session-scoped event store",
+                last_event_id,
+            )
+            return None
+
+        for event in replayed_events:
+            await send_callback(event)
+
+        return stream_id
+
+
+class EventStore(SDKEventStore):
+    """EventStore implementation backed by AsyncKeyValue.
+
+    Enables SSE polling/resumability by storing events that can be replayed
+    when clients reconnect. Works with any AsyncKeyValue backend (memory, Redis, etc.)
+    following the same pattern as ResponseCachingMiddleware and OAuthProxy.
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.event_store import EventStore
+
+        # Default in-memory storage
+        event_store = EventStore()
+
+        # Or with a custom backend
+        from key_value.aio.stores.redis import RedisStore
+        redis_backend = RedisStore(url="redis://localhost")
+        event_store = EventStore(storage=redis_backend)
+
+        mcp = FastMCP("MyServer")
+        app = mcp.http_app(event_store=event_store, retry_interval=2000)
+        ```
+
+    Args:
+        storage: AsyncKeyValue backend. Defaults to MemoryStore.
+        max_events_per_stream: Maximum events to retain per stream. Default 100.
+        ttl: Event TTL in seconds. Default 3600 (1 hour). Set to None for no expiration.
+    """
+
+    def __init__(
+        self,
+        storage: AsyncKeyValue | None = None,
+        max_events_per_stream: int = 100,
+        ttl: int | None = 3600,
+    ):
+        self._storage: AsyncKeyValue = storage or MemoryStore()
+        self._max_events_per_stream = max_events_per_stream
+        self._ttl = ttl
+
+        # PydanticAdapter for type-safe storage (following OAuth proxy pattern)
+        self._event_store: PydanticAdapter[EventEntry] = PydanticAdapter[EventEntry](
+            key_value=self._storage,
+            pydantic_model=EventEntry,
+            default_collection="fastmcp_events",
+        )
+        self._stream_store: PydanticAdapter[StreamEventList] = PydanticAdapter[
+            StreamEventList
+        ](
+            key_value=self._storage,
+            pydantic_model=StreamEventList,
+            default_collection="fastmcp_streams",
+        )
+
+    async def store_event(
+        self, stream_id: StreamId, message: JSONRPCMessage | None
+    ) -> EventId:
+        """Store an event and return its ID.
+
+        Args:
+            stream_id: ID of the stream the event belongs to
+            message: The JSON-RPC message to store, or None for priming events
+
+        Returns:
+            The generated event ID for the stored event
+        """
+        event_id = str(uuid4())
+
+        # Store the event entry
+        entry = EventEntry(
+            event_id=event_id,
+            stream_id=stream_id,
+            message=message.model_dump(mode="json", by_alias=True) if message else None,
+        )
+        await self._event_store.put(key=event_id, value=entry, ttl=self._ttl)
+
+        # Update stream's event list
+        stream_data = await self._stream_store.get(key=stream_id)
+        event_ids = stream_data.event_ids if stream_data else []
+        event_ids.append(event_id)
+
+        # Trim to max events (delete old events)
+        if len(event_ids) > self._max_events_per_stream:
+            for old_id in event_ids[: -self._max_events_per_stream]:
+                await self._event_store.delete(key=old_id)
+            event_ids = event_ids[-self._max_events_per_stream :]
+
+        await self._stream_store.put(
+            key=stream_id,
+            value=StreamEventList(event_ids=event_ids),
+            ttl=self._ttl,
+        )
+
+        return event_id
+
+    async def replay_events_after(
+        self,
+        last_event_id: EventId,
+        send_callback: EventCallback,
+    ) -> StreamId | None:
+        """Replay events that occurred after the specified event ID.
+
+        Args:
+            last_event_id: The ID of the last event the client received
+            send_callback: A callback function to send events to the client
+
+        Returns:
+            The stream ID of the replayed events, or None if the event ID was not found
+        """
+        # Look up the event to find its stream
+        entry = await self._event_store.get(key=last_event_id)
+        if not entry:
+            logger.warning(f"Event ID {last_event_id} not found in store")
+            return None
+
+        stream_id = entry.stream_id
+        stream_data = await self._stream_store.get(key=stream_id)
+        if not stream_data:
+            logger.warning(f"Stream {stream_id} not found in store")
+            return None
+
+        event_ids = stream_data.event_ids
+
+        # Find events after last_event_id
+        try:
+            start_idx = event_ids.index(last_event_id) + 1
+        except ValueError:
+            logger.warning(f"Event ID {last_event_id} not found in stream {stream_id}")
+            return None
+
+        # Replay events after the last one
+        for event_id in event_ids[start_idx:]:
+            event = await self._event_store.get(key=event_id)
+            if event and event.message:
+                msg = _jsonrpc_message_adapter.validate_python(event.message)
+                await send_callback(EventMessage(msg, event.event_id))
+
+        return stream_id
diff --git a/fastmcp_slim/fastmcp/server/http.py b/fastmcp_slim/fastmcp/server/http.py
new file mode 100644
index 0000000..2421bad
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/http.py
@@ -0,0 +1,718 @@
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Callable, Generator, Sequence
+from contextlib import asynccontextmanager, contextmanager
+from contextvars import ContextVar
+from fnmatch import fnmatchcase
+from ipaddress import ip_address
+from typing import TYPE_CHECKING, Any, Literal
+from urllib.parse import urlsplit
+from uuid import uuid4
+
+from mcp.server.auth.routes import build_resource_metadata_url
+from mcp.server.lowlevel.server import LifespanResultT
+from mcp.server.sse import SseServerTransport
+from mcp.server.streamable_http import (
+    EventStore,
+)
+from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+from mcp.server.transport_security import TransportSecuritySettings
+from starlette.applications import Starlette
+from starlette.datastructures import Headers
+from starlette.middleware import Middleware
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.routing import BaseRoute, Mount, Route
+from starlette.types import ASGIApp, Lifespan, Receive, Scope, Send
+
+from fastmcp.server.auth import AuthProvider
+from fastmcp.server.auth.middleware import RequireAuthMiddleware
+from fastmcp.server.event_store import SessionScopedEventStore
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP
+
+logger = get_logger(__name__)
+
+DEFAULT_HOSTS = ("127.0.0.1", "localhost", "::1")
+HostOriginProtection = bool | Literal["auto"]
+HostOriginProtectionMode = Literal["auto", "strict"]
+
+
+class FastMCPStreamableHTTPSessionManager(StreamableHTTPSessionManager):
+    """Session manager that scopes resumability storage per transport session."""
+
+    def __init__(
+        self,
+        app: Any,
+        event_store: EventStore | None = None,
+        json_response: bool = False,
+        stateless: bool = False,
+        security_settings: TransportSecuritySettings | None = None,
+        retry_interval: int | None = None,
+        session_idle_timeout: float | None = None,
+    ) -> None:
+        self._shared_event_store: EventStore | None = None
+        super().__init__(
+            app=app,
+            event_store=event_store,
+            json_response=json_response,
+            stateless=stateless,
+            security_settings=security_settings,
+            retry_interval=retry_interval,
+            session_idle_timeout=session_idle_timeout,
+        )
+
+    @property
+    def event_store(self) -> EventStore | None:
+        if self._shared_event_store is None:
+            return None
+        # The SDK reads `self.event_store` once when constructing each transport.
+        # A fresh adapter gives that transport a private stream namespace.
+        return SessionScopedEventStore(self._shared_event_store, session_id=uuid4().hex)
+
+    @event_store.setter
+    def event_store(self, event_store: EventStore | None) -> None:
+        self._shared_event_store = event_store
+
+
+class StreamableHTTPASGIApp:
+    """ASGI application wrapper for Streamable HTTP server transport."""
+
+    def __init__(self, session_manager: StreamableHTTPSessionManager | None):
+        self.session_manager = session_manager
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        try:
+            if self.session_manager is None:
+                raise RuntimeError(
+                    "Task group is not initialized. Make sure to use run()."
+                )
+            await self.session_manager.handle_request(scope, receive, send)
+        except RuntimeError as e:
+            if str(e) == "Task group is not initialized. Make sure to use run().":
+                logger.error(
+                    f"Original RuntimeError from mcp library: {e}", exc_info=True
+                )
+                new_error_message = (
+                    "FastMCP's StreamableHTTPSessionManager task group was not initialized. "
+                    "This commonly occurs when the FastMCP application's lifespan is not "
+                    "passed to the parent ASGI application (e.g., FastAPI or Starlette). "
+                    "Please ensure you are setting `lifespan=mcp_app.lifespan` in your "
+                    "parent app's constructor, where `mcp_app` is the application instance "
+                    "returned by `fastmcp_instance.http_app()`. \\n"
+                    "For more details, see the FastMCP ASGI integration documentation: "
+                    "https://gofastmcp.com/deployment/asgi"
+                )
+                # Raise a new RuntimeError that includes the original error's message
+                # for full context, but leads with the more helpful guidance.
+                raise RuntimeError(f"{new_error_message}\\nOriginal error: {e}") from e
+            else:
+                # Re-raise other RuntimeErrors if they don't match the specific message
+                raise
+
+
+def _normalize_host(host: str) -> str:
+    host = host.strip().lower()
+    if not host:
+        return ""
+
+    if host.startswith("["):
+        end = host.find("]")
+        if end == -1:
+            return host
+        return host[1:end]
+
+    if host.count(":") == 1:
+        return host.rsplit(":", 1)[0]
+
+    return host
+
+
+def _is_loopback_host(host: str) -> bool:
+    host = _normalize_host(host)
+    if host == "localhost":
+        return True
+
+    try:
+        return ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+def _is_unspecified_host(host: str) -> bool:
+    host = _normalize_host(host)
+    if not host:
+        return True
+
+    try:
+        return ip_address(host).is_unspecified
+    except ValueError:
+        return False
+
+
+def _host_matches(host: str, allowed_hosts: Sequence[str]) -> bool:
+    host = _normalize_host(host)
+    for allowed_host in allowed_hosts:
+        pattern = _normalize_host(allowed_host)
+        if pattern == "*" or fnmatchcase(host, pattern):
+            return True
+
+    return False
+
+
+def _origin_host(origin: str) -> str:
+    try:
+        parsed = urlsplit(origin)
+    except ValueError:
+        return ""
+
+    return parsed.hostname or ""
+
+
+def _origin_port(scheme: str, port: int | None) -> int | None:
+    if port is not None:
+        return port
+    if scheme == "http":
+        return 80
+    if scheme == "https":
+        return 443
+    return None
+
+
+def _format_origin_host(host: str) -> str:
+    if ":" in host and not host.startswith("["):
+        return f"[{host}]"
+    return host
+
+
+def _normalize_origin(origin: str) -> str:
+    origin = origin.strip().rstrip("/")
+    try:
+        parsed = urlsplit(origin)
+        port = parsed.port
+    except ValueError:
+        return origin.lower()
+
+    if not parsed.scheme or not parsed.hostname:
+        return origin.lower()
+
+    if parsed.path or parsed.query or parsed.fragment:
+        return origin.lower()
+
+    scheme = parsed.scheme.lower()
+    host = _format_origin_host(_normalize_host(parsed.hostname))
+    normalized_port = _origin_port(scheme, port)
+    if normalized_port is None:
+        return f"{scheme}://{host}"
+
+    return f"{scheme}://{host}:{normalized_port}"
+
+
+def _request_origin(scope: Scope, host: str) -> str:
+    return _normalize_origin(f"{scope.get('scheme', 'http')}://{host}")
+
+
+def _origin_matches(origin: str, allowed_origins: Sequence[str]) -> bool:
+    origin = _normalize_origin(origin)
+    for allowed_origin in allowed_origins:
+        pattern = _normalize_origin(allowed_origin)
+        if pattern == "*" or fnmatchcase(origin, pattern):
+            return True
+
+    return False
+
+
+class HostOriginGuardMiddleware:
+    """Validate Host and Origin headers before requests reach MCP sessions."""
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        allowed_hosts: Sequence[str] | None = None,
+        allowed_origins: Sequence[str] | None = None,
+        mode: HostOriginProtectionMode = "auto",
+    ) -> None:
+        self.app = app
+        self.allowed_hosts = tuple(allowed_hosts or ())
+        self.allowed_origins = tuple(allowed_origins or ())
+        self.mode = mode
+        self.has_explicit_allowed_hosts = allowed_hosts is not None
+        self.has_explicit_allowed_origins = allowed_origins is not None
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        headers = Headers(scope=scope)
+        host = headers.get("host", "")
+
+        if self._should_validate_host(scope) and not _host_matches(
+            host,
+            self._allowed_hosts_for_scope(scope),
+        ):
+            response = Response("Misdirected Request", status_code=421)
+            await response(scope, receive, send)
+            return
+
+        origin = headers.get("origin")
+        request_origin = _request_origin(scope, host)
+        if (
+            origin
+            and self._should_validate_origin(scope, host)
+            and not self._origin_allowed(
+                origin,
+                request_origin,
+                host,
+                allow_same_origin_fallback=self._allow_same_origin_fallback(
+                    scope,
+                    host,
+                ),
+            )
+        ):
+            response = Response("Forbidden Origin", status_code=403)
+            await response(scope, receive, send)
+            return
+
+        await self.app(scope, receive, send)
+
+    def _should_validate_host(self, scope: Scope) -> bool:
+        if self.mode == "strict" or self.has_explicit_allowed_hosts:
+            return True
+
+        server = scope.get("server")
+        return bool(server and _is_loopback_host(server[0]))
+
+    def _should_validate_origin(self, scope: Scope, host: str) -> bool:
+        if (
+            self.mode == "strict"
+            or self.has_explicit_allowed_hosts
+            or self.has_explicit_allowed_origins
+            or _is_loopback_host(host)
+        ):
+            return True
+
+        server = scope.get("server")
+        return bool(server and _is_loopback_host(server[0]))
+
+    def _allow_same_origin_fallback(self, scope: Scope, host: str) -> bool:
+        if not self.has_explicit_allowed_origins:
+            return True
+
+        if self.mode == "strict" or self.has_explicit_allowed_hosts:
+            return True
+
+        server = scope.get("server")
+        return _is_loopback_host(host) or bool(server and _is_loopback_host(server[0]))
+
+    def _allowed_hosts_for_scope(self, scope: Scope) -> tuple[str, ...]:
+        allowed_hosts = list(DEFAULT_HOSTS)
+        allowed_hosts.extend(self.allowed_hosts)
+
+        server = scope.get("server")
+        if server:
+            server_host = server[0]
+            if not _is_unspecified_host(server_host):
+                allowed_hosts.append(server_host)
+
+        return tuple(allowed_hosts)
+
+    def _origin_allowed(
+        self,
+        origin: str,
+        request_origin: str,
+        host: str,
+        allow_same_origin_fallback: bool,
+    ) -> bool:
+        if _origin_matches(origin, self.allowed_origins):
+            return True
+
+        if not allow_same_origin_fallback:
+            return False
+
+        origin_host = _origin_host(origin)
+        if _is_loopback_host(origin_host) and _is_loopback_host(host):
+            return True
+
+        return _normalize_origin(origin) == request_origin
+
+
+_current_http_request: ContextVar[Request | None] = ContextVar(
+    "http_request",
+    default=None,
+)
+
+
+class StarletteWithLifespan(Starlette):
+    @property
+    def lifespan(self) -> Lifespan[Starlette]:
+        return self.router.lifespan_context
+
+
+@contextmanager
+def set_http_request(request: Request) -> Generator[Request, None, None]:
+    token = _current_http_request.set(request)
+    try:
+        yield request
+    finally:
+        _current_http_request.reset(token)
+
+
+class RequestContextMiddleware:
+    """
+    Middleware that stores each request in a ContextVar and sets transport type.
+    """
+
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] == "http":
+            from fastmcp.server.context import reset_transport, set_transport
+
+            # Get transport type from app state (set during app creation)
+            transport_type = getattr(scope["app"].state, "transport_type", None)
+            transport_token = set_transport(transport_type) if transport_type else None
+            try:
+                with set_http_request(Request(scope)):
+                    await self.app(scope, receive, send)
+            finally:
+                if transport_token is not None:
+                    reset_transport(transport_token)
+        else:
+            await self.app(scope, receive, send)
+
+
+def create_base_app(
+    routes: list[BaseRoute],
+    middleware: list[Middleware],
+    debug: bool = False,
+    lifespan: Callable | None = None,
+) -> StarletteWithLifespan:
+    """Create a base Starlette app with common middleware and routes.
+
+    Args:
+        routes: List of routes to include in the app
+        middleware: List of middleware to include in the app
+        debug: Whether to enable debug mode
+        lifespan: Optional lifespan manager for the app
+
+    Returns:
+        A Starlette application
+    """
+    # Always add RequestContextMiddleware as the outermost middleware
+    middleware.insert(0, Middleware(RequestContextMiddleware))  # type: ignore[arg-type]
+
+    return StarletteWithLifespan(
+        routes=routes,
+        middleware=middleware,
+        debug=debug,
+        lifespan=lifespan,
+    )
+
+
+def create_sse_app(
+    server: FastMCP[LifespanResultT],
+    message_path: str,
+    sse_path: str,
+    auth: AuthProvider | None = None,
+    debug: bool = False,
+    routes: list[BaseRoute] | None = None,
+    middleware: list[Middleware] | None = None,
+) -> StarletteWithLifespan:
+    """Return an instance of the SSE server app.
+
+    Args:
+        server: The FastMCP server instance
+        message_path: Path for SSE messages
+        sse_path: Path for SSE connections
+        auth: Optional authentication provider (AuthProvider)
+        debug: Whether to enable debug mode
+        routes: Optional list of custom routes
+        middleware: Optional list of middleware
+    Returns:
+        A Starlette application with RequestContextMiddleware
+    """
+
+    server_routes: list[BaseRoute] = []
+    server_middleware: list[Middleware] = []
+
+    # Set up SSE transport
+    sse = SseServerTransport(message_path)
+
+    # Create handler for SSE connections
+    async def handle_sse(scope: Scope, receive: Receive, send: Send) -> Response:
+        async with sse.connect_sse(scope, receive, send) as streams:
+            await server._mcp_server.run(
+                streams[0],
+                streams[1],
+                server._mcp_server.create_initialization_options(),
+            )
+        return Response()
+
+    # Set up auth if enabled
+    if auth:
+        # Get auth middleware from the provider
+        auth_middleware = auth.get_middleware()
+
+        # Get auth provider's own routes (OAuth endpoints, metadata, etc)
+        auth_routes = auth.get_routes(mcp_path=sse_path)
+        server_routes.extend(auth_routes)
+        server_middleware.extend(auth_middleware)
+
+        # Build RFC 9728-compliant metadata URL
+        resource_url = auth._get_resource_url(sse_path)
+        resource_metadata_url = (
+            build_resource_metadata_url(resource_url) if resource_url else None
+        )
+
+        # Create protected SSE endpoint route
+        server_routes.append(
+            Route(
+                sse_path,
+                endpoint=RequireAuthMiddleware(
+                    handle_sse,
+                    auth.required_scopes,
+                    resource_metadata_url,
+                ),
+                methods=["GET"],
+            )
+        )
+
+        # Wrap the SSE message endpoint with RequireAuthMiddleware
+        server_routes.append(
+            Mount(
+                message_path,
+                app=RequireAuthMiddleware(
+                    sse.handle_post_message,
+                    auth.required_scopes,
+                    resource_metadata_url,
+                ),
+            )
+        )
+    else:
+        # No auth required
+        async def sse_endpoint(request: Request) -> Response:
+            return await handle_sse(request.scope, request.receive, request._send)
+
+        server_routes.append(
+            Route(
+                sse_path,
+                endpoint=sse_endpoint,
+                methods=["GET"],
+            )
+        )
+        server_routes.append(
+            Mount(
+                message_path,
+                app=sse.handle_post_message,
+            )
+        )
+
+    # Add custom routes with lowest precedence
+    if routes:
+        server_routes.extend(routes)
+    server_routes.extend(server._get_additional_http_routes())
+
+    # Add middleware
+    if middleware:
+        server_middleware.extend(middleware)
+
+    @asynccontextmanager
+    async def lifespan(app: Starlette) -> AsyncGenerator[None, None]:
+        async with server._lifespan_manager():
+            yield
+
+    # Create and return the app
+    app = create_base_app(
+        routes=server_routes,
+        middleware=server_middleware,
+        debug=debug,
+        lifespan=lifespan,
+    )
+    # Store the FastMCP server instance on the Starlette app state
+    app.state.fastmcp_server = server
+    app.state.path = sse_path
+    app.state.transport_type = "sse"
+
+    return app
+
+
+def create_streamable_http_app(
+    server: FastMCP[LifespanResultT],
+    streamable_http_path: str,
+    event_store: EventStore | None = None,
+    retry_interval: int | None = None,
+    auth: AuthProvider | None = None,
+    json_response: bool = False,
+    stateless_http: bool = False,
+    debug: bool = False,
+    routes: list[BaseRoute] | None = None,
+    middleware: list[Middleware] | None = None,
+    host_origin_protection: HostOriginProtection = False,
+    allowed_hosts: Sequence[str] | None = None,
+    allowed_origins: Sequence[str] | None = None,
+    session_idle_timeout: float | None = None,
+) -> StarletteWithLifespan:
+    """Return an instance of the StreamableHTTP server app.
+
+    Args:
+        server: The FastMCP server instance
+        streamable_http_path: Path for StreamableHTTP connections
+        event_store: Optional event store for SSE polling/resumability
+        retry_interval: Optional retry interval in milliseconds for SSE polling.
+            Controls how quickly clients should reconnect after server-initiated
+            disconnections. Requires event_store to be set. Defaults to SDK default.
+        auth: Optional authentication provider (AuthProvider)
+        json_response: Whether to use JSON response format
+        stateless_http: Whether to use stateless mode (new transport per request)
+        debug: Whether to enable debug mode
+        routes: Optional list of custom routes
+        middleware: Optional list of middleware
+        host_origin_protection: Whether to validate Host and Origin headers
+            before requests reach the MCP endpoint. Defaults to False for
+            compatibility. "auto" protects localhost-bound servers and explicit
+            host/origin allowlists.
+        allowed_hosts: Additional hostnames that may appear in the Host header.
+        allowed_origins: Additional browser origins trusted by the request guard.
+            Configure CORS separately when browser JavaScript must read
+            cross-origin responses.
+        session_idle_timeout: Maximum time in seconds a session may remain idle
+            before it is terminated. The deadline is pushed forward on every
+            request. When None, sessions never expire from inactivity. Not
+            supported in stateless mode.
+
+    Returns:
+        A Starlette application with StreamableHTTP support
+    """
+    server_routes: list[BaseRoute] = []
+    server_middleware: list[Middleware] = []
+
+    # Create the ASGI app wrapper (session manager is set each lifespan cycle)
+    streamable_http_app = StreamableHTTPASGIApp(None)
+
+    # Add StreamableHTTP routes with or without auth
+    if auth:
+        # Get auth middleware from the provider
+        auth_middleware = auth.get_middleware()
+
+        # Get auth provider's own routes (OAuth endpoints, metadata, etc)
+        auth_routes = auth.get_routes(mcp_path=streamable_http_path)
+        server_routes.extend(auth_routes)
+        server_middleware.extend(auth_middleware)
+
+        # Build RFC 9728-compliant metadata URL
+        resource_url = auth._get_resource_url(streamable_http_path)
+        resource_metadata_url = (
+            build_resource_metadata_url(resource_url) if resource_url else None
+        )
+
+        # Create protected HTTP endpoint route
+        # Stateless servers have no session tracking, so GET SSE streams
+        # (for server-initiated notifications) serve no purpose.
+        http_methods = (
+            ["POST", "DELETE"] if stateless_http else ["GET", "POST", "DELETE"]
+        )
+        server_routes.append(
+            Route(
+                streamable_http_path,
+                endpoint=RequireAuthMiddleware(
+                    streamable_http_app,
+                    auth.required_scopes,
+                    resource_metadata_url,
+                ),
+                methods=http_methods,
+            )
+        )
+    else:
+        # No auth required
+        http_methods = ["POST", "DELETE"] if stateless_http else None
+        server_routes.append(
+            Route(
+                streamable_http_path,
+                endpoint=streamable_http_app,
+                methods=http_methods,
+            )
+        )
+
+    # Add custom routes with lowest precedence
+    if routes:
+        server_routes.extend(routes)
+    server_routes.extend(server._get_additional_http_routes())
+
+    # Add middleware
+    if host_origin_protection not in (True, False, "auto"):
+        raise ValueError("host_origin_protection must be True, False, or 'auto'.")
+
+    if host_origin_protection is not False:
+        server_middleware.insert(
+            0,
+            Middleware(
+                HostOriginGuardMiddleware,
+                allowed_hosts=allowed_hosts,
+                allowed_origins=allowed_origins,
+                mode="strict" if host_origin_protection is True else "auto",
+            ),
+        )
+    if middleware:
+        server_middleware.extend(middleware)
+
+    # Create a lifespan manager to start and stop the session manager
+    @asynccontextmanager
+    async def lifespan(app: Starlette) -> AsyncGenerator[None, None]:
+        streamable_http_app.session_manager = FastMCPStreamableHTTPSessionManager(
+            app=server._mcp_server,
+            event_store=event_store,
+            retry_interval=retry_interval,
+            json_response=json_response,
+            stateless=stateless_http,
+            session_idle_timeout=session_idle_timeout,
+            # FastMCP owns DNS-rebinding protection via HostOriginGuardMiddleware,
+            # which is more expressive and already the documented surface. Always
+            # disable the SDK's own protection so the two layers don't
+            # double-block with confusing errors from two allowlists.
+            security_settings=TransportSecuritySettings(
+                enable_dns_rebinding_protection=False
+            ),
+        )
+        # The session manager's `run()` enters `server._mcp_server.lifespan`
+        # (our `_lifespan_proxy`), which now drives `server._lifespan_manager()`.
+        # Entering it here too would double-stack the same lifespan, so we let
+        # the manager own the single entry.
+        async with streamable_http_app.session_manager.run():
+            try:
+                yield
+            finally:
+                # Gracefully terminate active streamable-HTTP transports before
+                # the session manager's task group is cancelled. Without this,
+                # active SSE/streaming responses are aborted mid-flight and
+                # Uvicorn logs "ASGI callable returned without completing
+                # response." See PrefectHQ/fastmcp#3025.
+                sm = streamable_http_app.session_manager
+                # `_server_instances` is a private attribute of the upstream
+                # `StreamableHTTPSessionManager` (mcp SDK); termination is
+                # idempotent and tolerates new instances being added concurrently.
+                for transport in list(sm._server_instances.values()):
+                    try:
+                        await transport.terminate()
+                    except Exception:
+                        logger.debug(
+                            "Error terminating streamable-HTTP transport on shutdown",
+                            exc_info=True,
+                        )
+
+    # Create and return the app with lifespan
+    app = create_base_app(
+        routes=server_routes,
+        middleware=server_middleware,
+        debug=debug,
+        lifespan=lifespan,
+    )
+    # Store the FastMCP server instance on the Starlette app state
+    app.state.fastmcp_server = server
+    app.state.path = streamable_http_path
+    app.state.transport_type = "streamable-http"
+
+    return app
diff --git a/fastmcp_slim/fastmcp/server/lifespan.py b/fastmcp_slim/fastmcp/server/lifespan.py
new file mode 100644
index 0000000..c3cd916
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/lifespan.py
@@ -0,0 +1,198 @@
+"""Composable lifespans for FastMCP servers.
+
+This module provides a `@lifespan` decorator for creating composable server lifespans
+that can be combined using the `|` operator.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.lifespan import lifespan
+
+    @lifespan
+    async def db_lifespan(server):
+        conn = await connect_db()
+        yield {"db": conn}
+        await conn.close()
+
+    @lifespan
+    async def cache_lifespan(server):
+        cache = await connect_cache()
+        yield {"cache": cache}
+        await cache.close()
+
+    mcp = FastMCP("server", lifespan=db_lifespan | cache_lifespan)
+    ```
+
+To compose with existing `@asynccontextmanager` lifespans, wrap them explicitly:
+
+    ```python
+    from contextlib import asynccontextmanager
+    from fastmcp.server.lifespan import lifespan, ContextManagerLifespan
+
+    @asynccontextmanager
+    async def legacy_lifespan(server):
+        yield {"legacy": True}
+
+    @lifespan
+    async def new_lifespan(server):
+        yield {"new": True}
+
+    # Wrap the legacy lifespan explicitly
+    combined = ContextManagerLifespan(legacy_lifespan) | new_lifespan
+    ```
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP
+
+
+LifespanFn = Callable[["FastMCP[Any]"], AsyncIterator[dict[str, Any] | None]]
+LifespanContextManagerFn = Callable[
+    ["FastMCP[Any]"], AbstractAsyncContextManager[dict[str, Any] | None]
+]
+
+
+class Lifespan:
+    """Composable lifespan wrapper.
+
+    Wraps an async generator function and enables composition via the `|` operator.
+    The wrapped function should yield a dict that becomes part of the lifespan context.
+    """
+
+    def __init__(self, fn: LifespanFn) -> None:
+        """Initialize a Lifespan wrapper.
+
+        Args:
+            fn: An async generator function that takes a FastMCP server and yields
+                a dict for the lifespan context.
+        """
+        self._fn = fn
+
+    @asynccontextmanager
+    async def __call__(self, server: FastMCP[Any]) -> AsyncIterator[dict[str, Any]]:
+        """Execute the lifespan as an async context manager.
+
+        Args:
+            server: The FastMCP server instance.
+
+        Yields:
+            The lifespan context dict.
+        """
+        async with asynccontextmanager(self._fn)(server) as result:
+            yield result if result is not None else {}
+
+    def __or__(self, other: Lifespan) -> ComposedLifespan:
+        """Compose with another lifespan using the | operator.
+
+        Args:
+            other: Another Lifespan instance.
+
+        Returns:
+            A ComposedLifespan that runs both lifespans.
+
+        Raises:
+            TypeError: If other is not a Lifespan instance.
+        """
+        if not isinstance(other, Lifespan):
+            raise TypeError(
+                f"Cannot compose Lifespan with {type(other).__name__}. "
+                f"Use @lifespan decorator or wrap with ContextManagerLifespan()."
+            )
+        return ComposedLifespan(self, other)
+
+
+class ContextManagerLifespan(Lifespan):
+    """Lifespan wrapper for already-wrapped context manager functions.
+
+    Use this for functions already decorated with @asynccontextmanager.
+    """
+
+    _fn: LifespanContextManagerFn  # Override type for this subclass
+
+    def __init__(self, fn: LifespanContextManagerFn) -> None:
+        """Initialize with a context manager factory function."""
+        self._fn = fn
+
+    @asynccontextmanager
+    async def __call__(self, server: FastMCP[Any]) -> AsyncIterator[dict[str, Any]]:
+        """Execute the lifespan as an async context manager.
+
+        Args:
+            server: The FastMCP server instance.
+
+        Yields:
+            The lifespan context dict.
+        """
+        # self._fn is already a context manager factory, just call it
+        async with self._fn(server) as result:
+            yield result if result is not None else {}
+
+
+class ComposedLifespan(Lifespan):
+    """Two lifespans composed together.
+
+    Enters the left lifespan first, then the right. Exits in reverse order.
+    Results are shallow-merged into a single dict.
+    """
+
+    def __init__(self, left: Lifespan, right: Lifespan) -> None:
+        """Initialize a composed lifespan.
+
+        Args:
+            left: The first lifespan to enter.
+            right: The second lifespan to enter.
+        """
+        # Don't call super().__init__ since we override __call__
+        self._left = left
+        self._right = right
+
+    @asynccontextmanager
+    async def __call__(self, server: FastMCP[Any]) -> AsyncIterator[dict[str, Any]]:
+        """Execute both lifespans, merging their results.
+
+        Args:
+            server: The FastMCP server instance.
+
+        Yields:
+            The merged lifespan context dict from both lifespans.
+        """
+        async with (
+            self._left(server) as left_result,
+            self._right(server) as right_result,
+        ):
+            yield {**left_result, **right_result}
+
+
+def lifespan(fn: LifespanFn) -> Lifespan:
+    """Decorator to create a composable lifespan.
+
+    Use this decorator on an async generator function to make it composable
+    with other lifespans using the `|` operator.
+
+    Example:
+        ```python
+        @lifespan
+        async def my_lifespan(server):
+            # Setup
+            resource = await create_resource()
+            yield {"resource": resource}
+            # Teardown
+            await resource.close()
+
+        mcp = FastMCP("server", lifespan=my_lifespan | other_lifespan)
+        ```
+
+    Args:
+        fn: An async generator function that takes a FastMCP server and yields
+            a dict for the lifespan context.
+
+    Returns:
+        A composable Lifespan wrapper.
+    """
+    return Lifespan(fn)
diff --git a/fastmcp_slim/fastmcp/server/low_level.py b/fastmcp_slim/fastmcp/server/low_level.py
new file mode 100644
index 0000000..5267b1c
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/low_level.py
@@ -0,0 +1,315 @@
+from __future__ import annotations
+
+import weakref
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, cast
+
+import mcp_types
+from mcp.server._otel import OpenTelemetryMiddleware
+from mcp.server.context import (
+    CallNext,
+    HandlerResult,
+    ServerMiddleware,
+    ServerRequestContext,
+)
+from mcp.server.lowlevel.server import (
+    LifespanResultT,
+    NotificationOptions,
+)
+from mcp.server.lowlevel.server import (
+    Server as _Server,
+)
+from mcp.server.models import InitializationOptions
+from mcp.server.session import ServerSession
+from mcp.server.stdio import stdio_server as stdio_server
+from mcp.shared.exceptions import MCPError
+from pydantic import ValidationError
+
+from fastmcp.apps.config import UI_EXTENSION_ID
+from fastmcp.server.telemetry import seam_span
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    from fastmcp.server.middleware import CallNext as FastMCPCallNext
+    from fastmcp.server.server import FastMCP
+
+logger = get_logger(__name__)
+
+
+def client_supports_extension(session: ServerSession, extension_id: str) -> bool:
+    """Check whether the connected client supports a given MCP extension.
+
+    Inspects the ``extensions`` capability on ``ClientCapabilities`` sent by the
+    client during initialization. In v2 the client's initialize params are
+    reachable via ``session.client_params``.
+
+    SDK v2 declares ``extensions`` as a real field on ``ClientCapabilities``, so
+    a client sending ``ClientCapabilities(extensions={...})`` populates the field
+    directly. We read that field first and fall back to ``model_extra`` only for
+    legacy-serialized clients that carried ``extensions`` as an extra key.
+    """
+    client_params = session.client_params
+    if client_params is None:
+        return False
+    caps = client_params.capabilities
+    if caps is None:
+        return False
+    extensions: dict[str, Any] | None = caps.extensions
+    if extensions is None:
+        # Legacy fallback: clients that serialized `extensions` as an extra key
+        # (ClientCapabilities uses extra="allow") rather than the real field.
+        extras = caps.model_extra or {}
+        extensions = extras.get("extensions")
+    if not extensions:
+        return False
+    return extension_id in extensions
+
+
+class FastMCPServerMiddleware:
+    """SDK v2 server middleware that routes ``initialize`` through FastMCP middleware.
+
+    v2 no longer lets FastMCP subclass ``ServerSession`` (the runner constructs
+    it per request), so the old ``MiddlewareServerSession._received_request``
+    override is replaced by a ``ServerMiddleware``. This middleware binds the
+    FastMCP request-context ContextVar for the whole chain (covering
+    ``initialize``, where no handler adapter runs) and routes the initialize
+    request through the FastMCP middleware chain so ``on_initialize`` hooks fire
+    and can observe the ``InitializeResult`` or veto with ``MCPError``.
+    """
+
+    def __init__(self, fastmcp: FastMCP):
+        self._ref: weakref.ref[FastMCP] = weakref.ref(fastmcp)
+
+    async def __call__(
+        self, ctx: ServerRequestContext, call_next: CallNext
+    ) -> HandlerResult:
+        from fastmcp.server.dependencies import bind_request_context
+
+        fastmcp = self._ref()
+        with (
+            self._apply_shared_context(fastmcp),
+            bind_request_context(ctx),
+            self._seam_span(fastmcp, ctx),
+        ):
+            # Only initialize requests (request_id present) go through FastMCP
+            # middleware here; every other request already binds the context in
+            # its own adapter, so we just pass through.
+            if ctx.method == "initialize" and ctx.request_id is not None:
+                if fastmcp is not None:
+                    return await self._run_initialize_mw(fastmcp, ctx, call_next)
+            return await call_next(ctx)
+
+    @contextmanager
+    def _seam_span(
+        self, fastmcp: FastMCP | None, ctx: ServerRequestContext
+    ) -> Iterator[None]:
+        """Open the per-request SERVER span at the middleware seam.
+
+        The removed SDK ``OpenTelemetryMiddleware`` produced one SERVER span per
+        inbound message. FastMCP re-creates that guarantee for *every* request
+        method here — the last place shared by all request methods regardless of
+        how their handler is registered — so a request rejected *before* the
+        high-level path (FastMCP middleware, auth check, not-found mapping,
+        params failure) is still traced with an error span.
+
+        For the high-level methods (tools/resources/prompts), the deep
+        ``server_span(...)`` call in ``fastmcp.server.server`` detects this seam
+        span as the active span and *enriches* it in place with component
+        attributes instead of opening a second span, so there is exactly one
+        richly-attributed SERVER span per request. Notifications
+        (``request_id is None``) are skipped — a SERVER span models an inbound
+        request/response, not a fire-and-forget notification.
+        """
+        if fastmcp is None or ctx.request_id is None:
+            yield
+            return
+        with seam_span(ctx.method, fastmcp.name):
+            yield
+
+    @contextmanager
+    def _apply_shared_context(self, fastmcp: FastMCP | None) -> Iterator[None]:
+        """Re-establish app-scoped SharedContext ContextVars for this request.
+
+        The SDK v2 dispatcher runs handlers in the message sender's context, so
+        the ``SharedContext`` ContextVars set during the server lifespan are not
+        visible here. Re-apply the lifespan's captured snapshot so ``Shared()``
+        dependencies resolve (and stay shared) across requests.
+        """
+        snapshot = fastmcp._shared_context_snapshot if fastmcp is not None else None
+        if not snapshot:
+            yield
+            return
+        tokens = [(var, var.set(value)) for var, value in snapshot.items()]
+        try:
+            yield
+        finally:
+            for var, token in reversed(tokens):
+                var.reset(token)
+
+    async def _run_initialize_mw(
+        self,
+        fastmcp: FastMCP,
+        ctx: ServerRequestContext,
+        call_next: CallNext,
+    ) -> HandlerResult:
+        from fastmcp.server.context import Context
+        from fastmcp.server.middleware.middleware import MiddlewareContext
+
+        # Reconstruct the InitializeRequest from the raw params so FastMCP
+        # middleware `on_initialize` hooks that inspect the message still work.
+        init_message: mcp_types.InitializeRequest | None = None
+        try:
+            params = ctx.params if isinstance(ctx.params, dict) else {}
+            init_message = mcp_types.InitializeRequest.model_validate(
+                {"method": "initialize", "params": params}, by_name=False
+            )
+        except ValidationError:
+            init_message = None
+
+        # Track the initialize result produced by the SDK chain so a FastMCP
+        # middleware that raises `MCPError` *after* `call_next` can be
+        # logged-and-swallowed (the result is already committed) rather than
+        # producing a duplicate error response — preserving the pre-v2 contract.
+        captured_result: mcp_types.InitializeResult | None = None
+        call_next_completed = False
+
+        async def call_original_handler(
+            _mw_ctx: MiddlewareContext,
+        ) -> mcp_types.InitializeResult | None:
+            # call_next(ctx) runs the rest of the SDK chain, which for
+            # initialize returns the serialized InitializeResult dict. FastMCP
+            # middleware `on_initialize` hooks expect a typed InitializeResult,
+            # so deserialize before handing control back up the FastMCP chain.
+            # The runner's `_dump_result` re-serializes whatever we return, so a
+            # returned model round-trips cleanly.
+            nonlocal captured_result, call_next_completed
+            raw = await call_next(ctx)
+            if isinstance(raw, mcp_types.InitializeResult):
+                captured_result = raw
+            elif isinstance(raw, Mapping):
+                captured_result = mcp_types.InitializeResult.model_validate(dict(raw))
+            call_next_completed = True
+            return captured_result if raw is not None else None
+
+        async with Context(fastmcp=fastmcp, session=ctx.session) as fastmcp_ctx:
+            mw_context = MiddlewareContext(
+                message=init_message,
+                source="client",
+                type="request",
+                method="initialize",
+                fastmcp_context=fastmcp_ctx,
+            )
+            try:
+                return await fastmcp._run_middleware(
+                    mw_context,
+                    cast("FastMCPCallNext[Any, Any]", call_original_handler),
+                )
+            except MCPError:
+                # A middleware raised after the initialize response was already
+                # produced: log and return the committed result instead of
+                # re-raising to avoid responding to initialize twice. If the
+                # error was raised before `call_next` succeeded, re-raise so the
+                # dispatcher turns it into the wire error.
+                if not call_next_completed:
+                    raise
+                logger.warning(
+                    "MCPError raised by FastMCP middleware after the initialize "
+                    "response was produced; logging and not re-raising to avoid a "
+                    "duplicate response.",
+                    exc_info=True,
+                )
+                return captured_result
+
+
+class LowLevelServer(_Server[LifespanResultT]):
+    def __init__(self, fastmcp: FastMCP, *args: Any, **kwargs: Any):
+        super().__init__(*args, **kwargs)
+        # Store a weak reference to FastMCP to avoid circular references
+        self._fastmcp_ref: weakref.ref[FastMCP] = weakref.ref(fastmcp)
+
+        # FastMCP servers support notifications for all components. v2 derives
+        # capabilities from registered handlers + protocol_version, but legacy
+        # clients still read NotificationOptions at create_initialization_options
+        # time, so keep a default here and pass it through.
+        self.notification_options = NotificationOptions(
+            prompts_changed=True,
+            resources_changed=True,
+            tools_changed=True,
+        )
+
+        # The SDK seeds `OpenTelemetryMiddleware` into `self.middleware` so every
+        # lowlevel server emits a SERVER span per message. FastMCP emits its own,
+        # richer SERVER span per request (see `fastmcp.server.telemetry`), so the
+        # SDK's would produce a second, duplicate SERVER span with different
+        # attribute conventions for every request. Drop it — match by type rather
+        # than position so we don't depend on the SDK seeding it at index 0, and
+        # leave any other seeded middleware intact. FastMCP's telemetry extracts
+        # inbound W3C trace context from `_meta` itself, so distributed-trace
+        # propagation is unaffected.
+        self.middleware = [
+            mw for mw in self.middleware if not isinstance(mw, OpenTelemetryMiddleware)
+        ]
+
+        # Route initialize through FastMCP middleware.
+        self.middleware.append(
+            cast("ServerMiddleware[LifespanResultT]", FastMCPServerMiddleware(fastmcp))
+        )
+
+    @property
+    def fastmcp(self) -> FastMCP:
+        """Get the FastMCP instance."""
+        fastmcp = self._fastmcp_ref()
+        if fastmcp is None:
+            raise RuntimeError("FastMCP instance is no longer available")
+        return fastmcp
+
+    def create_initialization_options(
+        self,
+        notification_options: NotificationOptions | None = None,
+        experimental_capabilities: dict[str, dict[str, Any]] | None = None,
+        extensions: dict[str, dict[str, Any]] | None = None,
+    ) -> InitializationOptions:
+        # ensure we use the FastMCP notification options
+        if notification_options is None:
+            notification_options = self.notification_options
+        merged = {
+            **self.fastmcp.experimental_capabilities,
+            **(experimental_capabilities or {}),
+        }
+        return super().create_initialization_options(
+            notification_options=notification_options,
+            experimental_capabilities=merged or None,
+            extensions=extensions,
+        )
+
+    def get_capabilities(
+        self,
+        notification_options: NotificationOptions | None = None,
+        experimental_capabilities: dict[str, dict[str, Any]] | None = None,
+        extensions: dict[str, dict[str, Any]] | None = None,
+        *,
+        protocol_version: str | None = None,
+    ) -> mcp_types.ServerCapabilities:
+        """Override to set capabilities.tasks as a first-class field per SEP-1686
+        and advertise the MCP Apps UI extension.
+
+        ``ServerCapabilities.tasks`` and ``ServerCapabilities.extensions`` are
+        real declared fields in v2, so we update them directly.
+        """
+        from fastmcp.server.tasks.capabilities import get_task_capabilities
+
+        capabilities = super().get_capabilities(
+            notification_options,
+            experimental_capabilities,
+            extensions,
+            protocol_version=protocol_version,
+        )
+
+        existing_extensions = capabilities.extensions or {}
+        return capabilities.model_copy(
+            update={
+                "tasks": get_task_capabilities(),
+                "extensions": {**existing_extensions, UI_EXTENSION_ID: {}},
+            }
+        )
diff --git a/fastmcp_slim/fastmcp/server/middleware/__init__.py b/fastmcp_slim/fastmcp/server/middleware/__init__.py
new file mode 100644
index 0000000..8df6962
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/middleware/__init__.py
@@ -0,0 +1,15 @@
+from .authorization import AuthMiddleware
+from .middleware import (
+    CallNext,
+    Middleware,
+    MiddlewareContext,
+)
+from .ping import PingMiddleware
+
+__all__ = [
+    "AuthMiddleware",
+    "CallNext",
+    "Middleware",
+    "MiddlewareContext",
+    "PingMiddleware",
+]
diff --git a/fastmcp_slim/fastmcp/server/middleware/authorization.py b/fastmcp_slim/fastmcp/server/middleware/authorization.py
new file mode 100644
index 0000000..2040778
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/middleware/authorization.py
@@ -0,0 +1,368 @@
+"""Authorization middleware for FastMCP.
+
+This module provides middleware-based authorization using callable auth checks.
+AuthMiddleware applies auth checks globally to all components on the server.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth import require_scopes, restrict_tag
+    from fastmcp.server.middleware import AuthMiddleware
+
+    # Require specific scope for all components
+    mcp = FastMCP(middleware=[
+        AuthMiddleware(auth=require_scopes("api"))
+    ])
+
+    # Tag-based: components tagged "admin" require "admin" scope
+    mcp = FastMCP(middleware=[
+        AuthMiddleware(auth=restrict_tag("admin", scopes=["admin"]))
+    ])
+    ```
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+import mcp_types as mt
+
+from fastmcp.exceptions import AuthorizationError
+from fastmcp.prompts.base import Prompt, PromptResult
+from fastmcp.resources.base import Resource, ResourceResult
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.auth.authorization import (
+    AuthCheck,
+    AuthContext,
+    run_auth_checks,
+)
+from fastmcp.server.dependencies import get_access_token
+from fastmcp.server.middleware.middleware import (
+    CallNext,
+    Middleware,
+    MiddlewareContext,
+)
+from fastmcp.tools.base import Tool, ToolResult
+from fastmcp.utilities.versions import VersionSpec
+
+logger = logging.getLogger(__name__)
+
+
+def _requested_version(meta: Mapping[str, Any] | None) -> VersionSpec | None:
+    # SDK v2: request `_meta` is a plain dict (the `Meta` type alias), not the
+    # old `RequestParams.Meta` nested model.
+    if not meta:
+        return None
+
+    fastmcp_meta = meta.get("fastmcp")
+    if not isinstance(fastmcp_meta, dict):
+        return None
+
+    version = fastmcp_meta.get("version")
+    if isinstance(version, str):
+        return VersionSpec(eq=version)
+
+    if isinstance(version, dict):
+        gte = version.get("gte")
+        lt = version.get("lt")
+        eq = version.get("eq")
+
+        if not all(value is None or isinstance(value, str) for value in (gte, lt, eq)):
+            return None
+
+        return VersionSpec(gte=gte, lt=lt, eq=eq)
+
+    return None
+
+
+class AuthMiddleware(Middleware):
+    """Global authorization middleware using callable checks.
+
+    This middleware applies auth checks to all components (tools, resources,
+    prompts) on the server. It uses the same callable API as component-level
+    auth checks.
+
+    The middleware:
+    - Filters tools/resources/prompts from list responses based on auth checks
+    - Checks auth before tool execution, resource read, and prompt render
+    - Skips all auth checks for STDIO transport (no OAuth concept)
+
+    Args:
+        auth: A single auth check function or list of check functions.
+            All checks must pass for authorization to succeed (AND logic).
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth import require_scopes
+
+        # Require specific scope for all components
+        mcp = FastMCP(middleware=[AuthMiddleware(auth=require_scopes("api"))])
+
+        # Multiple scopes (AND logic)
+        mcp = FastMCP(middleware=[
+            AuthMiddleware(auth=require_scopes("read", "api"))
+        ])
+        ```
+    """
+
+    def __init__(self, auth: AuthCheck | list[AuthCheck]) -> None:
+        self.auth = auth
+
+    async def on_list_tools(
+        self,
+        context: MiddlewareContext[mt.ListToolsRequest],
+        call_next: CallNext[mt.ListToolsRequest, Sequence[Tool]],
+    ) -> Sequence[Tool]:
+        """Filter tools/list response based on auth checks."""
+        tools = await call_next(context)
+
+        # STDIO has no auth concept, skip filtering
+        # Late import to avoid circular import with context.py
+        from fastmcp.server.context import _current_transport
+
+        if _current_transport.get() == "stdio":
+            return tools
+
+        token = get_access_token()
+
+        authorized_tools: list[Tool] = []
+        for tool in tools:
+            ctx = AuthContext(token=token, component=tool)
+            try:
+                if await run_auth_checks(self.auth, ctx):
+                    authorized_tools.append(tool)
+            except AuthorizationError:
+                continue
+
+        return authorized_tools
+
+    async def on_call_tool(
+        self,
+        context: MiddlewareContext[mt.CallToolRequestParams],
+        call_next: CallNext[mt.CallToolRequestParams, ToolResult],
+    ) -> ToolResult:
+        """Check auth before tool execution."""
+        # STDIO has no auth concept, skip enforcement
+        # Late import to avoid circular import with context.py
+        from fastmcp.server.context import _current_transport
+
+        if _current_transport.get() == "stdio":
+            return await call_next(context)
+
+        # Get the tool being called
+        tool_name = context.message.name
+        fastmcp = context.fastmcp_context
+        if fastmcp is None:
+            # Fail closed: deny access when context is missing
+            logger.warning(
+                f"AuthMiddleware: fastmcp_context is None for tool '{tool_name}'. "
+                "Denying access for security."
+            )
+            raise AuthorizationError(
+                f"Authorization failed for tool '{tool_name}': missing context"
+            )
+
+        # get_tool returns None both when the tool does not exist and when
+        # component-level auth denied access, so the two cases are
+        # indistinguishable here. Keep the message ambiguous to avoid
+        # disclosing existence of tools the caller is not authorized to see.
+        version = _requested_version(context.message.meta)
+        tool = await fastmcp.fastmcp.get_tool(tool_name, version=version)
+        if tool is None:
+            raise AuthorizationError(
+                f"Authorization failed for tool '{tool_name}': "
+                "not found or not authorized"
+            )
+
+        # Global auth check
+        token = get_access_token()
+        ctx = AuthContext(token=token, component=tool)
+        if not await run_auth_checks(self.auth, ctx):
+            raise AuthorizationError(
+                f"Authorization failed for tool '{tool_name}': insufficient permissions"
+            )
+
+        return await call_next(context)
+
+    async def on_list_resources(
+        self,
+        context: MiddlewareContext[mt.ListResourcesRequest],
+        call_next: CallNext[mt.ListResourcesRequest, Sequence[Resource]],
+    ) -> Sequence[Resource]:
+        """Filter resources/list response based on auth checks."""
+        resources = await call_next(context)
+
+        # STDIO has no auth concept, skip filtering
+        from fastmcp.server.context import _current_transport
+
+        if _current_transport.get() == "stdio":
+            return resources
+
+        token = get_access_token()
+
+        authorized_resources: list[Resource] = []
+        for resource in resources:
+            ctx = AuthContext(token=token, component=resource)
+            try:
+                if await run_auth_checks(self.auth, ctx):
+                    authorized_resources.append(resource)
+            except AuthorizationError:
+                continue
+
+        return authorized_resources
+
+    async def on_read_resource(
+        self,
+        context: MiddlewareContext[mt.ReadResourceRequestParams],
+        call_next: CallNext[mt.ReadResourceRequestParams, ResourceResult],
+    ) -> ResourceResult:
+        """Check auth before resource read."""
+        # STDIO has no auth concept, skip enforcement
+        from fastmcp.server.context import _current_transport
+
+        if _current_transport.get() == "stdio":
+            return await call_next(context)
+
+        # Get the resource being read
+        uri = context.message.uri
+        fastmcp = context.fastmcp_context
+        if fastmcp is None:
+            logger.warning(
+                f"AuthMiddleware: fastmcp_context is None for resource '{uri}'. "
+                "Denying access for security."
+            )
+            raise AuthorizationError(
+                f"Authorization failed for resource '{uri}': missing context"
+            )
+
+        # get_resource/get_resource_template return None both when the resource
+        # does not exist and when component-level auth denied access, so the two
+        # cases are indistinguishable here. Keep the message ambiguous to avoid
+        # disclosing existence of resources the caller is not authorized to see.
+        version = _requested_version(context.message.meta)
+        component = await fastmcp.fastmcp.get_resource(str(uri), version=version)
+        if component is None:
+            component = await fastmcp.fastmcp.get_resource_template(
+                str(uri),
+                version=version,
+            )
+        if component is None:
+            raise AuthorizationError(
+                f"Authorization failed for resource '{uri}': "
+                "not found or not authorized"
+            )
+
+        # Global auth check
+        token = get_access_token()
+        ctx = AuthContext(token=token, component=component)
+        if not await run_auth_checks(self.auth, ctx):
+            raise AuthorizationError(
+                f"Authorization failed for resource '{uri}': insufficient permissions"
+            )
+
+        return await call_next(context)
+
+    async def on_list_resource_templates(
+        self,
+        context: MiddlewareContext[mt.ListResourceTemplatesRequest],
+        call_next: CallNext[
+            mt.ListResourceTemplatesRequest, Sequence[ResourceTemplate]
+        ],
+    ) -> Sequence[ResourceTemplate]:
+        """Filter resource templates/list response based on auth checks."""
+        templates = await call_next(context)
+
+        # STDIO has no auth concept, skip filtering
+        from fastmcp.server.context import _current_transport
+
+        if _current_transport.get() == "stdio":
+            return templates
+
+        token = get_access_token()
+
+        authorized_templates: list[ResourceTemplate] = []
+        for template in templates:
+            ctx = AuthContext(token=token, component=template)
+            try:
+                if await run_auth_checks(self.auth, ctx):
+                    authorized_templates.append(template)
+            except AuthorizationError:
+                continue
+
+        return authorized_templates
+
+    async def on_list_prompts(
+        self,
+        context: MiddlewareContext[mt.ListPromptsRequest],
+        call_next: CallNext[mt.ListPromptsRequest, Sequence[Prompt]],
+    ) -> Sequence[Prompt]:
+        """Filter prompts/list response based on auth checks."""
+        prompts = await call_next(context)
+
+        # STDIO has no auth concept, skip filtering
+        from fastmcp.server.context import _current_transport
+
+        if _current_transport.get() == "stdio":
+            return prompts
+
+        token = get_access_token()
+
+        authorized_prompts: list[Prompt] = []
+        for prompt in prompts:
+            ctx = AuthContext(token=token, component=prompt)
+            try:
+                if await run_auth_checks(self.auth, ctx):
+                    authorized_prompts.append(prompt)
+            except AuthorizationError:
+                continue
+
+        return authorized_prompts
+
+    async def on_get_prompt(
+        self,
+        context: MiddlewareContext[mt.GetPromptRequestParams],
+        call_next: CallNext[mt.GetPromptRequestParams, PromptResult],
+    ) -> PromptResult:
+        """Check auth before prompt render."""
+        # STDIO has no auth concept, skip enforcement
+        from fastmcp.server.context import _current_transport
+
+        if _current_transport.get() == "stdio":
+            return await call_next(context)
+
+        # Get the prompt being rendered
+        prompt_name = context.message.name
+        fastmcp = context.fastmcp_context
+        if fastmcp is None:
+            logger.warning(
+                f"AuthMiddleware: fastmcp_context is None for prompt '{prompt_name}'. "
+                "Denying access for security."
+            )
+            raise AuthorizationError(
+                f"Authorization failed for prompt '{prompt_name}': missing context"
+            )
+
+        # get_prompt returns None both when the prompt does not exist and when
+        # component-level auth denied access, so the two cases are
+        # indistinguishable here. Keep the message ambiguous to avoid
+        # disclosing existence of prompts the caller is not authorized to see.
+        version = _requested_version(context.message.meta)
+        prompt = await fastmcp.fastmcp.get_prompt(prompt_name, version=version)
+        if prompt is None:
+            raise AuthorizationError(
+                f"Authorization failed for prompt '{prompt_name}': "
+                "not found or not authorized"
+            )
+
+        # Global auth check
+        token = get_access_token()
+        ctx = AuthContext(token=token, component=prompt)
+        if not await run_auth_checks(self.auth, ctx):
+            raise AuthorizationError(
+                f"Authorization failed for prompt '{prompt_name}': insufficient permissions"
+            )
+
+        return await call_next(context)
diff --git a/fastmcp_slim/fastmcp/server/middleware/caching.py b/fastmcp_slim/fastmcp/server/middleware/caching.py
new file mode 100644
index 0000000..0a38a4f
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/middleware/caching.py
@@ -0,0 +1,593 @@
+"""A middleware for response caching."""
+
+import hashlib
+from collections.abc import Sequence
+from logging import Logger
+from typing import Any, TypedDict
+
+import mcp_types
+import pydantic_core
+from key_value.aio.adapters.pydantic import PydanticAdapter
+from key_value.aio.protocols.key_value import AsyncKeyValue
+from key_value.aio.stores.memory import MemoryStore
+from key_value.aio.wrappers.limit_size import LimitSizeWrapper
+from key_value.aio.wrappers.statistics import StatisticsWrapper
+from key_value.aio.wrappers.statistics.wrapper import (
+    KVStoreCollectionStatistics,
+)
+from pydantic import Field
+from typing_extensions import NotRequired, Self, override
+
+from fastmcp.prompts.base import Message, Prompt, PromptResult
+from fastmcp.resources.base import Resource, ResourceContent, ResourceResult
+from fastmcp.server.dependencies import get_access_token
+from fastmcp.server.middleware.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.tools.base import Tool, ToolResult
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import FastMCPBaseModel
+
+logger: Logger = get_logger(name=__name__)
+
+# Constants
+ONE_HOUR_IN_SECONDS = 3600
+FIVE_MINUTES_IN_SECONDS = 300
+
+ONE_MB_IN_BYTES = 1024 * 1024
+
+ANONYMOUS_AUTH_KEY = "__anonymous__"
+
+
+class CachableResourceContent(FastMCPBaseModel):
+    """A wrapper for ResourceContent that can be cached."""
+
+    content: str | bytes
+    mime_type: str | None = None
+    meta: dict[str, Any] | None = None
+
+
+class CachableResourceResult(FastMCPBaseModel):
+    """A wrapper for ResourceResult that can be cached."""
+
+    contents: list[CachableResourceContent]
+    meta: dict[str, Any] | None = None
+
+    def get_size(self) -> int:
+        return len(self.model_dump_json())
+
+    @classmethod
+    def wrap(cls, value: ResourceResult) -> Self:
+        return cls(
+            contents=[
+                CachableResourceContent(
+                    content=item.content, mime_type=item.mime_type, meta=item.meta
+                )
+                for item in value.contents
+            ],
+            meta=value.meta,
+        )
+
+    def unwrap(self) -> ResourceResult:
+        return ResourceResult(
+            contents=[
+                ResourceContent(
+                    content=item.content, mime_type=item.mime_type, meta=item.meta
+                )
+                for item in self.contents
+            ],
+            meta=self.meta,
+        )
+
+
+class CachableToolResult(FastMCPBaseModel):
+    content: list[mcp_types.ContentBlock]
+    structured_content: dict[str, Any] | None
+    meta: dict[str, Any] | None
+    is_error: bool = False
+
+    @classmethod
+    def wrap(cls, value: ToolResult) -> Self:
+        return cls(
+            content=value.content,
+            structured_content=value.structured_content,
+            meta=value.meta,
+            is_error=value.is_error,
+        )
+
+    def unwrap(self) -> ToolResult:
+        return ToolResult(
+            content=self.content,
+            structured_content=self.structured_content,
+            meta=self.meta,
+            is_error=self.is_error,
+        )
+
+
+class CachableMessage(FastMCPBaseModel):
+    """A wrapper for Message that can be cached."""
+
+    role: str
+    content: (
+        mcp_types.TextContent
+        | mcp_types.ImageContent
+        | mcp_types.AudioContent
+        | mcp_types.EmbeddedResource
+    )
+
+
+class CachablePromptResult(FastMCPBaseModel):
+    """A wrapper for PromptResult that can be cached."""
+
+    messages: list[CachableMessage]
+    description: str | None = None
+    meta: dict[str, Any] | None = None
+
+    def get_size(self) -> int:
+        return len(self.model_dump_json())
+
+    @classmethod
+    def wrap(cls, value: PromptResult) -> Self:
+        return cls(
+            messages=[
+                CachableMessage(role=m.role, content=m.content) for m in value.messages
+            ],
+            description=value.description,
+            meta=value.meta,
+        )
+
+    def unwrap(self) -> PromptResult:
+        return PromptResult(
+            messages=[
+                Message(content=m.content, role=m.role)  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+                for m in self.messages
+            ],
+            description=self.description,
+            meta=self.meta,
+        )
+
+
+class SharedMethodSettings(TypedDict):
+    """Shared config for a cache method."""
+
+    ttl: NotRequired[int]
+    enabled: NotRequired[bool]
+
+
+class ListToolsSettings(SharedMethodSettings):
+    """Configuration options for Tool-related caching."""
+
+
+class ListResourcesSettings(SharedMethodSettings):
+    """Configuration options for Resource-related caching."""
+
+
+class ListPromptsSettings(SharedMethodSettings):
+    """Configuration options for Prompt-related caching."""
+
+
+class CallToolSettings(SharedMethodSettings):
+    """Configuration options for Tool-related caching."""
+
+    included_tools: NotRequired[list[str]]
+    excluded_tools: NotRequired[list[str]]
+
+
+class ReadResourceSettings(SharedMethodSettings):
+    """Configuration options for Resource-related caching."""
+
+
+class GetPromptSettings(SharedMethodSettings):
+    """Configuration options for Prompt-related caching."""
+
+
+class ResponseCachingStatistics(FastMCPBaseModel):
+    list_tools: KVStoreCollectionStatistics | None = Field(default=None)
+    list_resources: KVStoreCollectionStatistics | None = Field(default=None)
+    list_prompts: KVStoreCollectionStatistics | None = Field(default=None)
+    read_resource: KVStoreCollectionStatistics | None = Field(default=None)
+    get_prompt: KVStoreCollectionStatistics | None = Field(default=None)
+    call_tool: KVStoreCollectionStatistics | None = Field(default=None)
+
+
+class ResponseCachingMiddleware(Middleware):
+    """The response caching middleware offers a simple way to cache responses to mcp methods. The Middleware
+    supports cache invalidation via notifications from the server. The Middleware implements TTL-based caching
+    but cache implementations may offer additional features like LRU eviction, size limits, and more.
+
+    When items are retrieved from the cache they will no longer be the original objects, but rather no-op objects
+    this means that response caching may not be compatible with other middleware that expects original subclasses.
+
+    Notes:
+    - Caches `tools/call`, `resources/read`, `prompts/get`, `tools/list`, `resources/list`, and `prompts/list` requests.
+    - Cache keys are derived from the method name, arguments, and the caller's
+      access token. Entries are partitioned per-token so that responses filtered
+      by per-component authorization (e.g. `auth=require_scopes(...)`) cannot
+      leak across users with different permissions. Unauthenticated callers
+      (including STDIO) share a single anonymous partition.
+    """
+
+    def __init__(
+        self,
+        cache_storage: AsyncKeyValue | None = None,
+        list_tools_settings: ListToolsSettings | None = None,
+        list_resources_settings: ListResourcesSettings | None = None,
+        list_prompts_settings: ListPromptsSettings | None = None,
+        read_resource_settings: ReadResourceSettings | None = None,
+        get_prompt_settings: GetPromptSettings | None = None,
+        call_tool_settings: CallToolSettings | None = None,
+        max_item_size: int = ONE_MB_IN_BYTES,
+    ):
+        """Initialize the response caching middleware.
+
+        Args:
+            cache_storage: The cache backend to use. If None, an in-memory cache is used.
+            list_tools_settings: The settings for the list tools method. If None, the default settings are used (5 minute TTL).
+            list_resources_settings: The settings for the list resources method. If None, the default settings are used (5 minute TTL).
+            list_prompts_settings: The settings for the list prompts method. If None, the default settings are used (5 minute TTL).
+            read_resource_settings: The settings for the read resource method. If None, the default settings are used (1 hour TTL).
+            get_prompt_settings: The settings for the get prompt method. If None, the default settings are used (1 hour TTL).
+            call_tool_settings: The settings for the call tool method. If None, the default settings are used (1 hour TTL).
+            max_item_size: The maximum size of items eligible for caching. Defaults to 1MB.
+        """
+
+        self._backend: AsyncKeyValue = cache_storage or MemoryStore()
+
+        # When the size limit is exceeded, the put will silently fail
+        self._size_limiter: LimitSizeWrapper = LimitSizeWrapper(
+            key_value=self._backend, max_size=max_item_size, raise_on_too_large=False
+        )
+        self._stats: StatisticsWrapper = StatisticsWrapper(key_value=self._size_limiter)
+
+        self._list_tools_settings: ListToolsSettings = (
+            list_tools_settings or ListToolsSettings()
+        )
+        self._list_resources_settings: ListResourcesSettings = (
+            list_resources_settings or ListResourcesSettings()
+        )
+        self._list_prompts_settings: ListPromptsSettings = (
+            list_prompts_settings or ListPromptsSettings()
+        )
+
+        self._read_resource_settings: ReadResourceSettings = (
+            read_resource_settings or ReadResourceSettings()
+        )
+        self._get_prompt_settings: GetPromptSettings = (
+            get_prompt_settings or GetPromptSettings()
+        )
+        self._call_tool_settings: CallToolSettings = (
+            call_tool_settings or CallToolSettings()
+        )
+
+        self._list_tools_cache: PydanticAdapter[list[Tool]] = PydanticAdapter(
+            key_value=self._stats,
+            pydantic_model=list[Tool],
+            default_collection="tools/list",
+        )
+
+        self._list_resources_cache: PydanticAdapter[list[Resource]] = PydanticAdapter(
+            key_value=self._stats,
+            pydantic_model=list[Resource],
+            default_collection="resources/list",
+        )
+
+        self._list_prompts_cache: PydanticAdapter[list[Prompt]] = PydanticAdapter(
+            key_value=self._stats,
+            pydantic_model=list[Prompt],
+            default_collection="prompts/list",
+        )
+
+        self._read_resource_cache: PydanticAdapter[CachableResourceResult] = (
+            PydanticAdapter(
+                key_value=self._stats,
+                pydantic_model=CachableResourceResult,
+                default_collection="resources/read",
+            )
+        )
+
+        self._get_prompt_cache: PydanticAdapter[CachablePromptResult] = PydanticAdapter(
+            key_value=self._stats,
+            pydantic_model=CachablePromptResult,
+            default_collection="prompts/get",
+        )
+
+        self._call_tool_cache: PydanticAdapter[CachableToolResult] = PydanticAdapter(
+            key_value=self._stats,
+            pydantic_model=CachableToolResult,
+            default_collection="tools/call",
+        )
+
+    @override
+    async def on_list_tools(
+        self,
+        context: MiddlewareContext[mcp_types.ListToolsRequest],
+        call_next: CallNext[mcp_types.ListToolsRequest, Sequence[Tool]],
+    ) -> Sequence[Tool]:
+        """List tools from the cache, if caching is enabled, and the result is in the cache. Otherwise,
+        otherwise call the next middleware and store the result in the cache if caching is enabled."""
+        if self._list_tools_settings.get("enabled") is False:
+            return await call_next(context)
+
+        cache_key: str = _get_auth_partition_key()
+
+        if cached_value := await self._list_tools_cache.get(key=cache_key):
+            return cached_value
+
+        tools: Sequence[Tool] = await call_next(context)
+
+        # Turn any subclass of Tool into a Tool
+        cachable_tools: list[Tool] = [
+            Tool(
+                name=tool.name,
+                title=tool.title,
+                description=tool.description,
+                parameters=tool.parameters,
+                output_schema=tool.output_schema,
+                annotations=tool.annotations,
+                meta=tool.meta,
+                tags=tool.tags,
+            )
+            for tool in tools
+        ]
+
+        await self._list_tools_cache.put(
+            key=cache_key,
+            value=cachable_tools,
+            ttl=self._list_tools_settings.get("ttl", FIVE_MINUTES_IN_SECONDS),
+        )
+
+        return cachable_tools
+
+    @override
+    async def on_list_resources(
+        self,
+        context: MiddlewareContext[mcp_types.ListResourcesRequest],
+        call_next: CallNext[mcp_types.ListResourcesRequest, Sequence[Resource]],
+    ) -> Sequence[Resource]:
+        """List resources from the cache, if caching is enabled, and the result is in the cache. Otherwise,
+        otherwise call the next middleware and store the result in the cache if caching is enabled."""
+        if self._list_resources_settings.get("enabled") is False:
+            return await call_next(context)
+
+        cache_key: str = _get_auth_partition_key()
+
+        if cached_value := await self._list_resources_cache.get(key=cache_key):
+            return cached_value
+
+        resources: Sequence[Resource] = await call_next(context)
+
+        # Turn any subclass of Resource into a Resource
+        cachable_resources: list[Resource] = [
+            Resource(
+                name=resource.name,
+                title=resource.title,
+                description=resource.description,
+                tags=resource.tags,
+                meta=resource.meta,
+                mime_type=resource.mime_type,
+                annotations=resource.annotations,
+                uri=resource.uri,
+            )
+            for resource in resources
+        ]
+
+        await self._list_resources_cache.put(
+            key=cache_key,
+            value=cachable_resources,
+            ttl=self._list_resources_settings.get("ttl", FIVE_MINUTES_IN_SECONDS),
+        )
+
+        return cachable_resources
+
+    @override
+    async def on_list_prompts(
+        self,
+        context: MiddlewareContext[mcp_types.ListPromptsRequest],
+        call_next: CallNext[mcp_types.ListPromptsRequest, Sequence[Prompt]],
+    ) -> Sequence[Prompt]:
+        """List prompts from the cache, if caching is enabled, and the result is in the cache. Otherwise,
+        otherwise call the next middleware and store the result in the cache if caching is enabled."""
+        if self._list_prompts_settings.get("enabled") is False:
+            return await call_next(context)
+
+        cache_key: str = _get_auth_partition_key()
+
+        if cached_value := await self._list_prompts_cache.get(key=cache_key):
+            return cached_value
+
+        prompts: Sequence[Prompt] = await call_next(context)
+
+        # Turn any subclass of Prompt into a Prompt
+        cachable_prompts: list[Prompt] = [
+            Prompt(
+                name=prompt.name,
+                title=prompt.title,
+                description=prompt.description,
+                tags=prompt.tags,
+                meta=prompt.meta,
+                arguments=prompt.arguments,
+            )
+            for prompt in prompts
+        ]
+
+        await self._list_prompts_cache.put(
+            key=cache_key,
+            value=cachable_prompts,
+            ttl=self._list_prompts_settings.get("ttl", FIVE_MINUTES_IN_SECONDS),
+        )
+
+        return cachable_prompts
+
+    @override
+    async def on_call_tool(
+        self,
+        context: MiddlewareContext[mcp_types.CallToolRequestParams],
+        call_next: CallNext[mcp_types.CallToolRequestParams, ToolResult],
+    ) -> ToolResult:
+        """Call a tool from the cache, if caching is enabled, and the result is in the cache. Otherwise,
+        otherwise call the next middleware and store the result in the cache if caching is enabled."""
+        tool_name = context.message.name
+
+        if self._call_tool_settings.get(
+            "enabled"
+        ) is False or not self._matches_tool_cache_settings(tool_name=tool_name):
+            return await call_next(context)
+
+        cache_key: str = _make_call_tool_cache_key(
+            msg=context.message, auth_key=_get_auth_partition_key()
+        )
+
+        if cached_value := await self._call_tool_cache.get(key=cache_key):
+            return cached_value.unwrap()
+
+        tool_result: ToolResult = await call_next(context)
+        cachable_tool_result: CachableToolResult = CachableToolResult.wrap(
+            value=tool_result
+        )
+
+        await self._call_tool_cache.put(
+            key=cache_key,
+            value=cachable_tool_result,
+            ttl=self._call_tool_settings.get("ttl", ONE_HOUR_IN_SECONDS),
+        )
+
+        return cachable_tool_result.unwrap()
+
+    @override
+    async def on_read_resource(
+        self,
+        context: MiddlewareContext[mcp_types.ReadResourceRequestParams],
+        call_next: CallNext[mcp_types.ReadResourceRequestParams, ResourceResult],
+    ) -> ResourceResult:
+        """Read a resource from the cache, if caching is enabled, and the result is in the cache. Otherwise,
+        otherwise call the next middleware and store the result in the cache if caching is enabled."""
+        if self._read_resource_settings.get("enabled") is False:
+            return await call_next(context)
+
+        cache_key: str = _make_read_resource_cache_key(
+            msg=context.message, auth_key=_get_auth_partition_key()
+        )
+        cached_value: CachableResourceResult | None
+
+        if cached_value := await self._read_resource_cache.get(key=cache_key):
+            return cached_value.unwrap()
+
+        value: ResourceResult = await call_next(context)
+        cached_value = CachableResourceResult.wrap(value)
+
+        await self._read_resource_cache.put(
+            key=cache_key,
+            value=cached_value,
+            ttl=self._read_resource_settings.get("ttl", ONE_HOUR_IN_SECONDS),
+        )
+
+        return cached_value.unwrap()
+
+    @override
+    async def on_get_prompt(
+        self,
+        context: MiddlewareContext[mcp_types.GetPromptRequestParams],
+        call_next: CallNext[mcp_types.GetPromptRequestParams, PromptResult],
+    ) -> PromptResult:
+        """Get a prompt from the cache, if caching is enabled, and the result is in the cache. Otherwise,
+        otherwise call the next middleware and store the result in the cache if caching is enabled."""
+        if self._get_prompt_settings.get("enabled") is False:
+            return await call_next(context)
+
+        cache_key: str = _make_get_prompt_cache_key(
+            msg=context.message, auth_key=_get_auth_partition_key()
+        )
+
+        if cached_value := await self._get_prompt_cache.get(key=cache_key):
+            return cached_value.unwrap()
+
+        value: PromptResult = await call_next(context)
+        cached_value = CachablePromptResult.wrap(value)
+
+        await self._get_prompt_cache.put(
+            key=cache_key,
+            value=cached_value,
+            ttl=self._get_prompt_settings.get("ttl", ONE_HOUR_IN_SECONDS),
+        )
+
+        return cached_value.unwrap()
+
+    def _matches_tool_cache_settings(self, tool_name: str) -> bool:
+        """Check if the tool matches the cache settings for tool calls."""
+
+        if included_tools := self._call_tool_settings.get("included_tools"):
+            if tool_name not in included_tools:
+                return False
+
+        if excluded_tools := self._call_tool_settings.get("excluded_tools"):
+            if tool_name in excluded_tools:
+                return False
+
+        return True
+
+    def statistics(self) -> ResponseCachingStatistics:
+        """Get the statistics for the cache."""
+        return ResponseCachingStatistics(
+            list_tools=self._stats.statistics.collections.get("tools/list"),
+            list_resources=self._stats.statistics.collections.get("resources/list"),
+            list_prompts=self._stats.statistics.collections.get("prompts/list"),
+            read_resource=self._stats.statistics.collections.get("resources/read"),
+            get_prompt=self._stats.statistics.collections.get("prompts/get"),
+            call_tool=self._stats.statistics.collections.get("tools/call"),
+        )
+
+
+def _get_arguments_str(arguments: dict[str, Any] | None) -> str:
+    """Get a string representation of the arguments."""
+
+    if arguments is None:
+        return "null"
+
+    try:
+        return pydantic_core.to_json(value=arguments, fallback=str).decode()
+
+    except TypeError:
+        return repr(arguments)
+
+
+def _hash_cache_key(value: str) -> str:
+    """Build a fixed-length SHA-256 cache key from request-derived input."""
+
+    return hashlib.sha256(value.encode()).hexdigest()
+
+
+def _get_auth_partition_key() -> str:
+    """Return a stable, hashed identifier for the current access token.
+
+    Cache entries are partitioned by access token so that responses filtered
+    by per-component authorization (e.g. `auth=require_scopes(...)`) are not
+    leaked across users with different permissions. Unauthenticated callers
+    (including STDIO) share a single anonymous partition.
+    """
+
+    token = get_access_token()
+    if token is None:
+        return ANONYMOUS_AUTH_KEY
+    return _hash_cache_key(token.token)
+
+
+def _make_call_tool_cache_key(
+    msg: mcp_types.CallToolRequestParams, auth_key: str = ANONYMOUS_AUTH_KEY
+) -> str:
+    """Make a cache key for a tool call using a stable hash of name and arguments."""
+
+    return _hash_cache_key(f"{auth_key}:{msg.name}:{_get_arguments_str(msg.arguments)}")
+
+
+def _make_read_resource_cache_key(
+    msg: mcp_types.ReadResourceRequestParams, auth_key: str = ANONYMOUS_AUTH_KEY
+) -> str:
+    """Make a cache key for a resource read using a stable hash of URI."""
+
+    return _hash_cache_key(f"{auth_key}:{msg.uri}")
+
+
+def _make_get_prompt_cache_key(
+    msg: mcp_types.GetPromptRequestParams, auth_key: str = ANONYMOUS_AUTH_KEY
+) -> str:
+    """Make a cache key for a prompt get using a stable hash of name and arguments."""
+
+    return _hash_cache_key(f"{auth_key}:{msg.name}:{_get_arguments_str(msg.arguments)}")
diff --git a/fastmcp_slim/fastmcp/server/middleware/dereference.py b/fastmcp_slim/fastmcp/server/middleware/dereference.py
new file mode 100644
index 0000000..9a551dd
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/middleware/dereference.py
@@ -0,0 +1,78 @@
+"""Middleware that dereferences $ref in JSON schemas before sending to clients."""
+
+from collections.abc import Sequence
+from typing import Any
+
+import mcp_types as mt
+from typing_extensions import override
+
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.middleware.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.tools.base import Tool
+from fastmcp.utilities.json_schema import dereference_refs
+
+
+class DereferenceRefsMiddleware(Middleware):
+    """Dereferences $ref in component schemas before sending to clients.
+
+    Some MCP clients (e.g., VS Code Copilot) don't handle JSON Schema $ref
+    properly. This middleware inlines all $ref definitions so schemas are
+    self-contained. Enabled by default via ``FastMCP(dereference_schemas=True)``.
+    """
+
+    @override
+    async def on_list_tools(
+        self,
+        context: MiddlewareContext[mt.ListToolsRequest],
+        call_next: CallNext[mt.ListToolsRequest, Sequence[Tool]],
+    ) -> Sequence[Tool]:
+        tools = await call_next(context)
+        return [_dereference_tool(tool) for tool in tools]
+
+    @override
+    async def on_list_resource_templates(
+        self,
+        context: MiddlewareContext[mt.ListResourceTemplatesRequest],
+        call_next: CallNext[
+            mt.ListResourceTemplatesRequest, Sequence[ResourceTemplate]
+        ],
+    ) -> Sequence[ResourceTemplate]:
+        templates = await call_next(context)
+        return [_dereference_resource_template(t) for t in templates]
+
+
+def _dereference_tool(tool: Tool) -> Tool:
+    """Return a copy of the tool with dereferenced schemas."""
+    updates: dict[str, object] = {}
+    if "$defs" in tool.parameters or _has_ref(tool.parameters):
+        updates["parameters"] = dereference_refs(tool.parameters)
+    if tool.output_schema is not None and (
+        "$defs" in tool.output_schema or _has_ref(tool.output_schema)
+    ):
+        updates["output_schema"] = dereference_refs(tool.output_schema)
+    if updates:
+        return tool.model_copy(update=updates)
+    return tool
+
+
+def _dereference_resource_template(template: ResourceTemplate) -> ResourceTemplate:
+    """Return a copy of the template with dereferenced schemas."""
+    if "$defs" in template.parameters or _has_ref(template.parameters):
+        return template.model_copy(
+            update={"parameters": dereference_refs(template.parameters)}
+        )
+    return template
+
+
+def _has_ref(schema: dict[str, Any]) -> bool:
+    """Check if a schema contains any $ref."""
+    if "$ref" in schema:
+        return True
+    for value in schema.values():
+        if isinstance(value, dict) and _has_ref(value):
+            return True
+        if isinstance(value, list):
+            for item in value:
+                if isinstance(item, dict) and _has_ref(item):
+                    return True
+    return False
diff --git a/fastmcp_slim/fastmcp/server/middleware/error_handling.py b/fastmcp_slim/fastmcp/server/middleware/error_handling.py
new file mode 100644
index 0000000..449ee28
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/middleware/error_handling.py
@@ -0,0 +1,215 @@
+"""Error handling middleware for consistent error responses and tracking."""
+
+import asyncio
+import logging
+import traceback
+from collections.abc import Callable
+from typing import Any
+
+import anyio
+from mcp import MCPError
+
+from fastmcp.exceptions import NotFoundError
+
+from .middleware import CallNext, Middleware, MiddlewareContext
+
+
+class ErrorHandlingMiddleware(Middleware):
+    """Middleware that provides consistent error handling and logging.
+
+    Catches exceptions, logs them appropriately, and converts them to
+    proper MCP error responses. Also tracks error patterns for monitoring.
+
+    Example:
+        ```python
+        from fastmcp.server.middleware.error_handling import ErrorHandlingMiddleware
+        import logging
+
+        # Configure logging to see error details
+        logging.basicConfig(level=logging.ERROR)
+
+        mcp = FastMCP("MyServer")
+        mcp.add_middleware(ErrorHandlingMiddleware())
+        ```
+    """
+
+    def __init__(
+        self,
+        logger: logging.Logger | None = None,
+        include_traceback: bool = False,
+        error_callback: Callable[[Exception, MiddlewareContext], None] | None = None,
+        transform_errors: bool = True,
+    ):
+        """Initialize error handling middleware.
+
+        Args:
+            logger: Logger instance for error logging. If None, uses 'fastmcp.errors'
+            include_traceback: Whether to include full traceback in error logs
+            error_callback: Optional callback function called for each error
+            transform_errors: Whether to transform non-MCP errors to MCPError
+        """
+        self.logger = logger or logging.getLogger("fastmcp.errors")
+        self.include_traceback = include_traceback
+        self.error_callback = error_callback
+        self.transform_errors = transform_errors
+        self.error_counts = {}
+
+    def _log_error(self, error: Exception, context: MiddlewareContext) -> None:
+        """Log error with appropriate detail level."""
+        error_type = type(error).__name__
+        method = context.method or "unknown"
+
+        # Track error counts
+        error_key = f"{error_type}:{method}"
+        self.error_counts[error_key] = self.error_counts.get(error_key, 0) + 1
+
+        base_message = f"Error in {method}: {error_type}: {error!s}"
+
+        if self.include_traceback:
+            self.logger.error(f"{base_message}\n{traceback.format_exc()}")
+        else:
+            self.logger.error(base_message)
+
+        # Call custom error callback if provided
+        if self.error_callback:
+            try:
+                self.error_callback(error, context)
+            except Exception as callback_error:
+                self.logger.error(f"Error in error callback: {callback_error}")
+
+    def _transform_error(
+        self, error: Exception, context: MiddlewareContext
+    ) -> Exception:
+        """Transform non-MCP errors to proper MCP errors."""
+        if isinstance(error, MCPError):
+            return error
+
+        if not self.transform_errors:
+            return error
+
+        # Map common exceptions to appropriate MCP error codes
+        error_type = type(error.__cause__) if error.__cause__ else type(error)
+
+        if error_type in (ValueError, TypeError):
+            return MCPError(code=-32602, message=f"Invalid params: {error!s}")
+        elif error_type in (FileNotFoundError, KeyError, NotFoundError):
+            # MCP spec defines -32002 specifically for resource not found
+            method = context.method or ""
+            if method.startswith("resources/"):
+                return MCPError(code=-32002, message=f"Resource not found: {error!s}")
+            return MCPError(code=-32001, message=f"Not found: {error!s}")
+        elif error_type is PermissionError:
+            return MCPError(code=-32000, message=f"Permission denied: {error!s}")
+        # asyncio.TimeoutError is a subclass of TimeoutError in Python 3.10, alias in 3.11+
+        elif error_type in (TimeoutError, asyncio.TimeoutError):
+            return MCPError(code=-32000, message=f"Request timeout: {error!s}")
+        else:
+            return MCPError(code=-32603, message=f"Internal error: {error!s}")
+
+    async def on_message(self, context: MiddlewareContext, call_next: CallNext) -> Any:
+        """Handle errors for all messages."""
+        try:
+            return await call_next(context)
+        except Exception as error:
+            self._log_error(error, context)
+
+            # Transform and re-raise
+            transformed_error = self._transform_error(error, context)
+            raise transformed_error from error
+
+    def get_error_stats(self) -> dict[str, int]:
+        """Get error statistics for monitoring."""
+        return self.error_counts.copy()
+
+
+class RetryMiddleware(Middleware):
+    """Middleware that implements automatic retry logic for failed requests.
+
+    Retries requests that fail with transient errors, using exponential
+    backoff to avoid overwhelming the server or external dependencies.
+
+    Example:
+        ```python
+        from fastmcp.server.middleware.error_handling import RetryMiddleware
+
+        # Retry up to 3 times with exponential backoff
+        retry_middleware = RetryMiddleware(
+            max_retries=3,
+            retry_exceptions=(ConnectionError, TimeoutError)
+        )
+
+        mcp = FastMCP("MyServer")
+        mcp.add_middleware(retry_middleware)
+        ```
+    """
+
+    def __init__(
+        self,
+        max_retries: int = 3,
+        base_delay: float = 1.0,
+        max_delay: float = 60.0,
+        backoff_multiplier: float = 2.0,
+        retry_exceptions: tuple[type[Exception], ...] = (ConnectionError, TimeoutError),
+        logger: logging.Logger | None = None,
+    ):
+        """Initialize retry middleware.
+
+        Args:
+            max_retries: Maximum number of retry attempts
+            base_delay: Initial delay between retries in seconds
+            max_delay: Maximum delay between retries in seconds
+            backoff_multiplier: Multiplier for exponential backoff
+            retry_exceptions: Tuple of exception types that should trigger retries
+            logger: Logger for retry attempts
+        """
+        self.max_retries = max_retries
+        self.base_delay = base_delay
+        self.max_delay = max_delay
+        self.backoff_multiplier = backoff_multiplier
+        self.retry_exceptions = retry_exceptions
+        self.logger = logger or logging.getLogger("fastmcp.retry")
+
+    def _should_retry(self, error: Exception) -> bool:
+        """Determine if an error should trigger a retry.
+
+        Checks both the error itself and its ``__cause__``, since FastMCP
+        wraps tool exceptions as ``ToolError(...) from original``. Only one
+        level of cause is inspected — middleware below this one must not
+        re-wrap errors with a new ``from`` clause, or the real type will be
+        hidden from the retry decision.
+        """
+        if isinstance(error, self.retry_exceptions):
+            return True
+        cause = error.__cause__
+        return cause is not None and isinstance(cause, self.retry_exceptions)
+
+    def _calculate_delay(self, attempt: int) -> float:
+        """Calculate delay for the given attempt number."""
+        delay = self.base_delay * (self.backoff_multiplier**attempt)
+        return min(delay, self.max_delay)
+
+    async def on_request(self, context: MiddlewareContext, call_next: CallNext) -> Any:
+        """Implement retry logic for requests."""
+        last_error = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                return await call_next(context)
+            except Exception as error:
+                last_error = error
+
+                # Don't retry on the last attempt or if it's not a retryable error
+                if attempt == self.max_retries or not self._should_retry(error):
+                    break
+
+                delay = self._calculate_delay(attempt)
+                self.logger.warning(
+                    f"Request {context.method} failed (attempt {attempt + 1}/{self.max_retries + 1}): "
+                    f"{type(error).__name__}: {error!s}. Retrying in {delay:.1f}s..."
+                )
+
+                await anyio.sleep(delay)
+
+        # Re-raise the last error if all retries failed
+        if last_error:
+            raise last_error
diff --git a/fastmcp_slim/fastmcp/server/middleware/logging.py b/fastmcp_slim/fastmcp/server/middleware/logging.py
new file mode 100644
index 0000000..33825df
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/middleware/logging.py
@@ -0,0 +1,256 @@
+"""Comprehensive logging middleware for FastMCP servers."""
+
+import json
+import logging
+import time
+from collections.abc import Callable
+from logging import Logger
+from typing import Any
+
+import pydantic_core
+
+from .middleware import CallNext, Middleware, MiddlewareContext
+
+
+def default_serializer(data: Any) -> str:
+    """The default serializer for Payloads in the logging middleware."""
+    return pydantic_core.to_json(data, fallback=str).decode()
+
+
+class BaseLoggingMiddleware(Middleware):
+    """Base class for logging middleware."""
+
+    logger: Logger
+    log_level: int
+    include_payloads: bool
+    include_payload_length: bool
+    estimate_payload_tokens: bool
+    max_payload_length: int | None
+    methods: list[str] | None
+    structured_logging: bool
+    payload_serializer: Callable[[Any], str] | None
+
+    def _serialize_payload(self, context: MiddlewareContext[Any]) -> str:
+        payload: str
+
+        if not self.payload_serializer:
+            payload = default_serializer(context.message)
+        else:
+            try:
+                payload = self.payload_serializer(context.message)
+            except Exception as e:
+                self.logger.warning(
+                    f"Failed to serialize payload due to {e}: {context.type} {context.method} {context.source}."
+                )
+                payload = default_serializer(context.message)
+
+        return payload
+
+    def _format_message(self, message: dict[str, str | int | float]) -> str:
+        """Format a message for logging."""
+        if self.structured_logging:
+            return json.dumps(message)
+        else:
+            return " ".join([f"{k}={v}" for k, v in message.items()])
+
+    def _create_before_message(
+        self, context: MiddlewareContext[Any]
+    ) -> dict[str, str | int | float]:
+        message: dict[str, str | int | float] = {
+            "event": context.type + "_start",
+            "method": context.method or "unknown",
+            "source": context.source,
+        }
+
+        if (
+            self.include_payloads
+            or self.include_payload_length
+            or self.estimate_payload_tokens
+        ):
+            payload = self._serialize_payload(context)
+
+            if self.include_payload_length or self.estimate_payload_tokens:
+                payload_length = len(payload)
+                payload_tokens = payload_length // 4
+                if self.estimate_payload_tokens:
+                    message["payload_tokens"] = payload_tokens
+                if self.include_payload_length:
+                    message["payload_length"] = payload_length
+
+            if self.max_payload_length and len(payload) > self.max_payload_length:
+                payload = payload[: self.max_payload_length] + "..."
+
+            if self.include_payloads:
+                message["payload"] = payload
+                message["payload_type"] = type(context.message).__name__
+
+        return message
+
+    def _create_error_message(
+        self,
+        context: MiddlewareContext[Any],
+        start_time: float,
+        error: Exception,
+    ) -> dict[str, str | int | float]:
+        duration_ms: float = _get_duration_ms(start_time)
+        message = {
+            "event": context.type + "_error",
+            "method": context.method or "unknown",
+            "source": context.source,
+            "duration_ms": duration_ms,
+            "error": str(object=error),
+        }
+        return message
+
+    def _create_after_message(
+        self,
+        context: MiddlewareContext[Any],
+        start_time: float,
+    ) -> dict[str, str | int | float]:
+        duration_ms: float = _get_duration_ms(start_time)
+        message = {
+            "event": context.type + "_success",
+            "method": context.method or "unknown",
+            "source": context.source,
+            "duration_ms": duration_ms,
+        }
+        return message
+
+    def _log_message(
+        self, message: dict[str, str | int | float], log_level: int | None = None
+    ):
+        self.logger.log(log_level or self.log_level, self._format_message(message))
+
+    async def on_message(
+        self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]
+    ) -> Any:
+        """Log messages for configured methods."""
+
+        if self.methods and context.method not in self.methods:
+            return await call_next(context)
+
+        self._log_message(self._create_before_message(context))
+
+        start_time = time.perf_counter()
+        try:
+            result = await call_next(context)
+
+            self._log_message(self._create_after_message(context, start_time))
+
+            return result
+        except Exception as e:
+            self._log_message(
+                self._create_error_message(context, start_time, e), logging.ERROR
+            )
+            raise
+
+
+class LoggingMiddleware(BaseLoggingMiddleware):
+    """Middleware that provides comprehensive request and response logging.
+
+    Logs all MCP messages with configurable detail levels. Useful for debugging,
+    monitoring, and understanding server usage patterns.
+
+    Example:
+        ```python
+        from fastmcp.server.middleware.logging import LoggingMiddleware
+        import logging
+
+        # Configure logging
+        logging.basicConfig(level=logging.INFO)
+
+        mcp = FastMCP("MyServer")
+        mcp.add_middleware(LoggingMiddleware())
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        logger: logging.Logger | None = None,
+        log_level: int = logging.INFO,
+        include_payloads: bool = False,
+        include_payload_length: bool = False,
+        estimate_payload_tokens: bool = False,
+        max_payload_length: int = 1000,
+        methods: list[str] | None = None,
+        payload_serializer: Callable[[Any], str] | None = None,
+    ):
+        """Initialize logging middleware.
+
+        Args:
+            logger: Logger instance to use. If None, creates a logger named 'fastmcp.requests'
+            log_level: Log level for messages (default: INFO)
+            include_payloads: Whether to include message payloads in logs
+            include_payload_length: Whether to include response size in logs
+            estimate_payload_tokens: Whether to estimate response tokens
+            max_payload_length: Maximum length of payload to log (prevents huge logs)
+            methods: List of methods to log. If None, logs all methods.
+            payload_serializer: Callable that converts objects to a JSON string for the
+                payload. If not provided, uses FastMCP's default tool serializer.
+        """
+        self.logger: Logger = logger or logging.getLogger("fastmcp.middleware.logging")
+        self.log_level = log_level
+        self.include_payloads: bool = include_payloads
+        self.include_payload_length: bool = include_payload_length
+        self.estimate_payload_tokens: bool = estimate_payload_tokens
+        self.max_payload_length: int = max_payload_length
+        self.methods: list[str] | None = methods
+        self.payload_serializer: Callable[[Any], str] | None = payload_serializer
+        self.structured_logging: bool = False
+
+
+class StructuredLoggingMiddleware(BaseLoggingMiddleware):
+    """Middleware that provides structured JSON logging for better log analysis.
+
+    Outputs structured logs that are easier to parse and analyze with log
+    aggregation tools like ELK stack, Splunk, or cloud logging services.
+
+    Example:
+        ```python
+        from fastmcp.server.middleware.logging import StructuredLoggingMiddleware
+        import logging
+
+        mcp = FastMCP("MyServer")
+        mcp.add_middleware(StructuredLoggingMiddleware())
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        logger: logging.Logger | None = None,
+        log_level: int = logging.INFO,
+        include_payloads: bool = False,
+        include_payload_length: bool = False,
+        estimate_payload_tokens: bool = False,
+        methods: list[str] | None = None,
+        payload_serializer: Callable[[Any], str] | None = None,
+    ):
+        """Initialize structured logging middleware.
+
+        Args:
+            logger: Logger instance to use. If None, creates a logger named 'fastmcp.structured'
+            log_level: Log level for messages (default: INFO)
+            include_payloads: Whether to include message payloads in logs
+            include_payload_length: Whether to include payload size in logs
+            estimate_payload_tokens: Whether to estimate token count using length // 4
+            methods: List of methods to log. If None, logs all methods.
+            payload_serializer: Callable that converts objects to a JSON string for the
+                payload. If not provided, uses FastMCP's default tool serializer.
+        """
+        self.logger: Logger = logger or logging.getLogger(
+            "fastmcp.middleware.structured_logging"
+        )
+        self.log_level: int = log_level
+        self.include_payloads: bool = include_payloads
+        self.include_payload_length: bool = include_payload_length
+        self.estimate_payload_tokens: bool = estimate_payload_tokens
+        self.methods: list[str] | None = methods
+        self.payload_serializer: Callable[[Any], str] | None = payload_serializer
+        self.max_payload_length: int | None = None
+        self.structured_logging: bool = True
+
+
+def _get_duration_ms(start_time: float, /) -> float:
+    return round(number=(time.perf_counter() - start_time) * 1000, ndigits=2)
diff --git a/fastmcp_slim/fastmcp/server/middleware/middleware.py b/fastmcp_slim/fastmcp/server/middleware/middleware.py
new file mode 100644
index 0000000..d2bada0
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/middleware/middleware.py
@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass, field, replace
+from datetime import datetime, timezone
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    Literal,
+    Protocol,
+    runtime_checkable,
+)
+
+import mcp_types as mt
+from typing_extensions import TypeVar
+
+from fastmcp.prompts.base import Prompt, PromptResult
+from fastmcp.resources.base import Resource, ResourceResult
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.tools.base import Tool, ToolResult
+
+if TYPE_CHECKING:
+    from fastmcp.server.context import Context
+
+__all__ = [
+    "CallNext",
+    "Middleware",
+    "MiddlewareContext",
+]
+
+logger = logging.getLogger(__name__)
+
+
+T = TypeVar("T", default=Any)
+R = TypeVar("R", covariant=True, default=Any)
+
+
+@runtime_checkable
+class CallNext(Protocol[T, R]):
+    def __call__(self, context: MiddlewareContext[T]) -> Awaitable[R]: ...
+
+
+@dataclass(kw_only=True, frozen=True)
+class MiddlewareContext(Generic[T]):
+    """
+    Unified context for all middleware operations.
+    """
+
+    message: T
+
+    fastmcp_context: Context | None = None
+
+    # Common metadata
+    source: Literal["client", "server"] = "client"
+    type: Literal["request", "notification"] = "request"
+    method: str | None = None
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    def copy(self, **kwargs: Any) -> MiddlewareContext[T]:
+        return replace(self, **kwargs)
+
+
+def make_middleware_wrapper(
+    middleware: Middleware, call_next: CallNext[T, R]
+) -> CallNext[T, R]:
+    """Create a wrapper that applies a single middleware to a context. The
+    closure bakes in the middleware and call_next function, so it can be
+    passed to other functions that expect a call_next function."""
+
+    async def wrapper(context: MiddlewareContext[T]) -> R:
+        return await middleware(context, call_next)
+
+    return wrapper
+
+
+def make_handler_wrapper(
+    handler: Callable[..., Awaitable[Any]],
+    call_next: CallNext[Any, Any],
+) -> CallNext[Any, Any]:
+    async def wrapper(context: MiddlewareContext[Any]) -> Any:
+        return await handler(context, call_next=call_next)
+
+    return wrapper
+
+
+class Middleware:
+    """Base class for FastMCP middleware with dispatching hooks."""
+
+    async def __call__(
+        self,
+        context: MiddlewareContext[T],
+        call_next: CallNext[T, Any],
+    ) -> Any:
+        """Main entry point that orchestrates the pipeline."""
+        handler_chain = await self._dispatch_handler(
+            context,
+            call_next=call_next,
+        )
+        return await handler_chain(context)
+
+    async def _dispatch_handler(
+        self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]
+    ) -> CallNext[Any, Any]:
+        """Builds a chain of handlers for a given message."""
+        handler = call_next
+
+        match context.method:
+            case "initialize":
+                handler = make_handler_wrapper(self.on_initialize, handler)
+            case "tools/call":
+                handler = make_handler_wrapper(self.on_call_tool, handler)
+            case "resources/read":
+                handler = make_handler_wrapper(self.on_read_resource, handler)
+            case "prompts/get":
+                handler = make_handler_wrapper(self.on_get_prompt, handler)
+            case "tools/list":
+                handler = make_handler_wrapper(self.on_list_tools, handler)
+            case "resources/list":
+                handler = make_handler_wrapper(self.on_list_resources, handler)
+            case "resources/templates/list":
+                handler = make_handler_wrapper(
+                    self.on_list_resource_templates,
+                    handler,
+                )
+            case "prompts/list":
+                handler = make_handler_wrapper(self.on_list_prompts, handler)
+
+        match context.type:
+            case "request":
+                handler = make_handler_wrapper(self.on_request, handler)
+            case "notification":
+                handler = make_handler_wrapper(self.on_notification, handler)
+
+        handler = make_handler_wrapper(self.on_message, handler)
+
+        return handler
+
+    async def on_message(
+        self,
+        context: MiddlewareContext[Any],
+        call_next: CallNext[Any, Any],
+    ) -> Any:
+        return await call_next(context)
+
+    async def on_request(
+        self,
+        context: MiddlewareContext[mt.Request[Any, Any]],
+        call_next: CallNext[mt.Request[Any, Any], Any],
+    ) -> Any:
+        return await call_next(context)
+
+    async def on_notification(
+        self,
+        context: MiddlewareContext[mt.Notification[Any, Any]],
+        call_next: CallNext[mt.Notification[Any, Any], Any],
+    ) -> Any:
+        return await call_next(context)
+
+    async def on_initialize(
+        self,
+        context: MiddlewareContext[mt.InitializeRequest],
+        call_next: CallNext[mt.InitializeRequest, mt.InitializeResult | None],
+    ) -> mt.InitializeResult | None:
+        return await call_next(context)
+
+    async def on_call_tool(
+        self,
+        context: MiddlewareContext[mt.CallToolRequestParams],
+        call_next: CallNext[mt.CallToolRequestParams, ToolResult],
+    ) -> ToolResult:
+        return await call_next(context)
+
+    async def on_read_resource(
+        self,
+        context: MiddlewareContext[mt.ReadResourceRequestParams],
+        call_next: CallNext[mt.ReadResourceRequestParams, ResourceResult],
+    ) -> ResourceResult:
+        return await call_next(context)
+
+    async def on_get_prompt(
+        self,
+        context: MiddlewareContext[mt.GetPromptRequestParams],
+        call_next: CallNext[mt.GetPromptRequestParams, PromptResult],
+    ) -> PromptResult:
+        return await call_next(context)
+
+    async def on_list_tools(
+        self,
+        context: MiddlewareContext[mt.ListToolsRequest],
+        call_next: CallNext[mt.ListToolsRequest, Sequence[Tool]],
+    ) -> Sequence[Tool]:
+        return await call_next(context)
+
+    async def on_list_resources(
+        self,
+        context: MiddlewareContext[mt.ListResourcesRequest],
+        call_next: CallNext[mt.ListResourcesRequest, Sequence[Resource]],
+    ) -> Sequence[Resource]:
+        return await call_next(context)
+
+    async def on_list_resource_templates(
+        self,
+        context: MiddlewareContext[mt.ListResourceTemplatesRequest],
+        call_next: CallNext[
+            mt.ListResourceTemplatesRequest, Sequence[ResourceTemplate]
+        ],
+    ) -> Sequence[ResourceTemplate]:
+        return await call_next(context)
+
+    async def on_list_prompts(
+        self,
+        context: MiddlewareContext[mt.ListPromptsRequest],
+        call_next: CallNext[mt.ListPromptsRequest, Sequence[Prompt]],
+    ) -> Sequence[Prompt]:
+        return await call_next(context)
diff --git a/fastmcp_slim/fastmcp/server/middleware/ping.py b/fastmcp_slim/fastmcp/server/middleware/ping.py
new file mode 100644
index 0000000..e81ccc3
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/middleware/ping.py
@@ -0,0 +1,89 @@
+"""Ping middleware for keeping client connections alive."""
+
+import asyncio
+import contextlib
+from typing import Any
+
+import anyio
+
+from .middleware import CallNext, Middleware, MiddlewareContext
+
+
+class PingMiddleware(Middleware):
+    """Middleware that sends periodic pings to keep client connections alive.
+
+    Starts a background ping task on first message from each session. The task
+    sends server-to-client pings at the configured interval until the session
+    ends.
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.middleware import PingMiddleware
+
+        mcp = FastMCP("MyServer")
+        mcp.add_middleware(PingMiddleware(interval_ms=5000))
+        ```
+    """
+
+    def __init__(self, interval_ms: int = 30000):
+        """Initialize ping middleware.
+
+        Args:
+            interval_ms: Interval between pings in milliseconds (default: 30000)
+
+        Raises:
+            ValueError: If interval_ms is not positive
+        """
+        if interval_ms <= 0:
+            raise ValueError("interval_ms must be positive")
+        self.interval_ms = interval_ms
+        self._active_sessions: set[int] = set()
+        self._lock = anyio.Lock()
+
+    async def on_message(self, context: MiddlewareContext, call_next: CallNext) -> Any:
+        """Start ping task on first message from a connection."""
+        if (
+            context.fastmcp_context is None
+            or context.fastmcp_context.request_context is None
+        ):
+            return await call_next(context)
+
+        session = context.fastmcp_context.session
+        # SDK v2 constructs a ServerSession per request; the stable per-connection
+        # identity lives on the underlying Connection. Key the keepalive loop off
+        # it so one ping task runs for the whole connection and is torn down when
+        # the connection closes.
+        connection = getattr(session, "_connection", None)
+        connection_id = id(connection) if connection is not None else id(session)
+
+        async with self._lock:
+            if connection_id not in self._active_sessions:
+                self._active_sessions.add(connection_id)
+                ping_task = asyncio.create_task(
+                    self._ping_loop(session, connection_id),
+                    name=f"ping-keepalive-{connection_id}",
+                )
+
+                if connection is not None:
+
+                    async def _cancel_ping() -> None:
+                        ping_task.cancel()
+                        with contextlib.suppress(asyncio.CancelledError):
+                            await ping_task
+
+                    connection.exit_stack.push_async_callback(_cancel_ping)
+
+        return await call_next(context)
+
+    async def _ping_loop(self, session: Any, connection_id: int) -> None:
+        """Send periodic pings until the connection ends."""
+        try:
+            while True:
+                await anyio.sleep(self.interval_ms / 1000)
+                try:
+                    await session.send_ping()
+                except (anyio.ClosedResourceError, anyio.BrokenResourceError):
+                    return
+        finally:
+            self._active_sessions.discard(connection_id)
diff --git a/fastmcp_slim/fastmcp/server/middleware/rate_limiting.py b/fastmcp_slim/fastmcp/server/middleware/rate_limiting.py
new file mode 100644
index 0000000..a18ebbd
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/middleware/rate_limiting.py
@@ -0,0 +1,243 @@
+"""Rate limiting middleware for protecting FastMCP servers from abuse."""
+
+import inspect
+import time
+from collections import defaultdict, deque
+from collections.abc import Awaitable, Callable
+from typing import Any, cast
+
+import anyio
+from mcp import MCPError
+
+from .middleware import CallNext, Middleware, MiddlewareContext
+
+
+class RateLimitError(MCPError):
+    """Error raised when rate limit is exceeded."""
+
+    def __init__(self, message: str = "Rate limit exceeded"):
+        super().__init__(code=-32000, message=message)
+
+
+class TokenBucketRateLimiter:
+    """Token bucket implementation for rate limiting."""
+
+    def __init__(self, capacity: int, refill_rate: float):
+        """Initialize token bucket.
+
+        Args:
+            capacity: Maximum number of tokens in the bucket
+            refill_rate: Tokens added per second
+        """
+        self.capacity = capacity
+        self.refill_rate = refill_rate
+        self.tokens = capacity
+        self.last_refill = time.time()
+        self._lock = anyio.Lock()
+
+    async def consume(self, tokens: int = 1) -> bool:
+        """Try to consume tokens from the bucket.
+
+        Args:
+            tokens: Number of tokens to consume
+
+        Returns:
+            True if tokens were available and consumed, False otherwise
+        """
+        async with self._lock:
+            now = time.time()
+            elapsed = now - self.last_refill
+
+            # Add tokens based on elapsed time
+            self.tokens = min(self.capacity, self.tokens + elapsed * self.refill_rate)
+            self.last_refill = now
+
+            if self.tokens >= tokens:
+                self.tokens -= tokens
+                return True
+            return False
+
+
+class SlidingWindowRateLimiter:
+    """Sliding window rate limiter implementation."""
+
+    def __init__(self, max_requests: int, window_seconds: int):
+        """Initialize sliding window rate limiter.
+
+        Args:
+            max_requests: Maximum requests allowed in the time window
+            window_seconds: Time window in seconds
+        """
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+        self.requests = deque()
+        self._lock = anyio.Lock()
+
+    async def is_allowed(self) -> bool:
+        """Check if a request is allowed."""
+        async with self._lock:
+            now = time.time()
+            cutoff = now - self.window_seconds
+
+            # Remove old requests outside the window
+            while self.requests and self.requests[0] < cutoff:
+                self.requests.popleft()
+
+            if len(self.requests) < self.max_requests:
+                self.requests.append(now)
+                return True
+            return False
+
+
+class RateLimitingMiddleware(Middleware):
+    """Middleware that implements rate limiting to prevent server abuse.
+
+    Uses a token bucket algorithm by default, allowing for burst traffic
+    while maintaining a sustainable long-term rate.
+
+    Example:
+        ```python
+        from fastmcp.server.middleware.rate_limiting import RateLimitingMiddleware
+
+        # Allow 10 requests per second with bursts up to 20
+        rate_limiter = RateLimitingMiddleware(
+            max_requests_per_second=10,
+            burst_capacity=20
+        )
+
+        mcp = FastMCP("MyServer")
+        mcp.add_middleware(rate_limiter)
+        ```
+    """
+
+    def __init__(
+        self,
+        max_requests_per_second: float = 10.0,
+        burst_capacity: int | None = None,
+        get_client_id: Callable[[MiddlewareContext], str]
+        | Callable[[MiddlewareContext], Awaitable[str]]
+        | None = None,
+        global_limit: bool = False,
+    ):
+        """Initialize rate limiting middleware.
+
+        Args:
+            max_requests_per_second: Sustained requests per second allowed
+            burst_capacity: Maximum burst capacity. If None, defaults to 2x max_requests_per_second
+            get_client_id: Function to extract client ID from context. Can be sync or async.
+                If None, uses global limiting
+            global_limit: If True, apply limit globally; if False, per-client
+        """
+        self.max_requests_per_second = max_requests_per_second
+        self.burst_capacity = burst_capacity or int(max_requests_per_second * 2)
+        self.get_client_id = get_client_id
+        self.global_limit = global_limit
+
+        # Storage for rate limiters per client
+        self.limiters: dict[str, TokenBucketRateLimiter] = defaultdict(
+            lambda: TokenBucketRateLimiter(
+                self.burst_capacity, self.max_requests_per_second
+            )
+        )
+
+        # Global rate limiter
+        if self.global_limit:
+            self.global_limiter = TokenBucketRateLimiter(
+                self.burst_capacity, self.max_requests_per_second
+            )
+
+    async def _get_client_identifier(self, context: MiddlewareContext) -> str:
+        """Get client identifier for rate limiting."""
+        if self.get_client_id:
+            client_id = self.get_client_id(context)
+            if inspect.isawaitable(client_id):
+                return cast(str, await client_id)
+            return client_id
+        return "global"
+
+    async def on_request(self, context: MiddlewareContext, call_next: CallNext) -> Any:
+        """Apply rate limiting to requests."""
+        if self.global_limit:
+            # Global rate limiting
+            allowed = await self.global_limiter.consume()
+            if not allowed:
+                raise RateLimitError("Global rate limit exceeded")
+        else:
+            # Per-client rate limiting
+            client_id = await self._get_client_identifier(context)
+            limiter = self.limiters[client_id]
+            allowed = await limiter.consume()
+            if not allowed:
+                raise RateLimitError(f"Rate limit exceeded for client: {client_id}")
+
+        return await call_next(context)
+
+
+class SlidingWindowRateLimitingMiddleware(Middleware):
+    """Middleware that implements sliding window rate limiting.
+
+    Uses a sliding window approach which provides more precise rate limiting
+    but uses more memory to track individual request timestamps.
+
+    Example:
+        ```python
+        from fastmcp.server.middleware.rate_limiting import SlidingWindowRateLimitingMiddleware
+
+        # Allow 100 requests per minute
+        rate_limiter = SlidingWindowRateLimitingMiddleware(
+            max_requests=100,
+            window_minutes=1
+        )
+
+        mcp = FastMCP("MyServer")
+        mcp.add_middleware(rate_limiter)
+        ```
+    """
+
+    def __init__(
+        self,
+        max_requests: int,
+        window_minutes: int = 1,
+        get_client_id: Callable[[MiddlewareContext], str]
+        | Callable[[MiddlewareContext], Awaitable[str]]
+        | None = None,
+    ):
+        """Initialize sliding window rate limiting middleware.
+
+        Args:
+            max_requests: Maximum requests allowed in the time window
+            window_minutes: Time window in minutes
+            get_client_id: Function to extract client ID from context. Can be sync or async.
+                If None, uses global limiting
+        """
+        self.max_requests = max_requests
+        self.window_seconds = window_minutes * 60
+        self.get_client_id = get_client_id
+
+        # Storage for rate limiters per client
+        self.limiters: dict[str, SlidingWindowRateLimiter] = defaultdict(
+            lambda: SlidingWindowRateLimiter(self.max_requests, self.window_seconds)
+        )
+
+    async def _get_client_identifier(self, context: MiddlewareContext) -> str:
+        """Get client identifier for rate limiting."""
+        if self.get_client_id:
+            client_id = self.get_client_id(context)
+            if inspect.isawaitable(client_id):
+                return cast(str, await client_id)
+            return client_id
+        return "global"
+
+    async def on_request(self, context: MiddlewareContext, call_next: CallNext) -> Any:
+        """Apply sliding window rate limiting to requests."""
+        client_id = await self._get_client_identifier(context)
+        limiter = self.limiters[client_id]
+
+        allowed = await limiter.is_allowed()
+        if not allowed:
+            raise RateLimitError(
+                f"Rate limit exceeded: {self.max_requests} requests per "
+                f"{self.window_seconds // 60} minutes for client: {client_id}"
+            )
+
+        return await call_next(context)
diff --git a/fastmcp_slim/fastmcp/server/middleware/response_limiting.py b/fastmcp_slim/fastmcp/server/middleware/response_limiting.py
new file mode 100644
index 0000000..32f08c0
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/middleware/response_limiting.py
@@ -0,0 +1,137 @@
+"""Response limiting middleware for controlling tool response sizes."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import mcp_types as mt
+import pydantic_core
+from mcp_types import TextContent
+
+from fastmcp.tools.base import ToolResult
+
+from .middleware import CallNext, Middleware, MiddlewareContext
+
+__all__ = ["ResponseLimitingMiddleware"]
+
+logger = logging.getLogger(__name__)
+
+
+class ResponseLimitingMiddleware(Middleware):
+    """Middleware that limits the response size of tool calls.
+
+    Intercepts tool call responses and enforces size limits. If a response
+    exceeds the limit, it extracts text content, truncates it, and returns
+    a single TextContent block.
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.middleware.response_limiting import (
+            ResponseLimitingMiddleware,
+        )
+
+        mcp = FastMCP("MyServer")
+
+        # Limit all tool responses to 500KB
+        mcp.add_middleware(ResponseLimitingMiddleware(max_size=500_000))
+
+        # Limit only specific tools
+        mcp.add_middleware(
+            ResponseLimitingMiddleware(
+                max_size=100_000,
+                tools=["search", "fetch_data"],
+            )
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        max_size: int = 1_000_000,
+        truncation_suffix: str = "\n\n[Response truncated due to size limit]",
+        tools: list[str] | None = None,
+    ) -> None:
+        """Initialize response limiting middleware.
+
+        Args:
+            max_size: Maximum response size in bytes. Defaults to 1MB (1,000,000).
+            truncation_suffix: Suffix to append when truncating responses.
+                Defaults to "\\n\\n[Response truncated due to size limit]".
+            tools: List of tool names to apply limiting to. If None, applies to all.
+        """
+        if max_size <= 0:
+            raise ValueError(f"max_size must be positive, got {max_size}")
+        self.max_size = max_size
+        self.truncation_suffix = truncation_suffix
+        self.tools = set(tools) if tools is not None else None
+
+    def _truncate_to_result(
+        self,
+        text: str,
+        meta: dict[str, Any] | None = None,
+    ) -> ToolResult:
+        """Truncate text to fit within max_size and wrap in ToolResult."""
+        suffix_bytes = len(self.truncation_suffix.encode("utf-8"))
+        # Account for JSON wrapper overhead: {"content":[{"type":"text","text":"..."}]}
+        overhead = 50
+        target_size = self.max_size - suffix_bytes - overhead
+
+        if target_size <= 0:
+            # Edge case: max_size too small for even the suffix
+            truncated = self.truncation_suffix
+        else:
+            # Truncate to target size, preserving UTF-8 boundaries
+            encoded = text.encode("utf-8")
+            if len(encoded) <= target_size:
+                truncated = text + self.truncation_suffix
+            else:
+                truncated = (
+                    encoded[:target_size].decode("utf-8", errors="ignore")
+                    + self.truncation_suffix
+                )
+
+        # Preserve original meta, falling back to {} when absent. Having
+        # meta set ensures to_mcp_result() returns a CallToolResult, which
+        # bypasses MCP SDK outputSchema validation — a truncated response
+        # is no longer valid structured output.
+        return ToolResult(
+            content=[TextContent(type="text", text=truncated)],
+            meta=meta if meta is not None else {},
+        )
+
+    async def on_call_tool(
+        self,
+        context: MiddlewareContext[mt.CallToolRequestParams],
+        call_next: CallNext[mt.CallToolRequestParams, ToolResult],
+    ) -> ToolResult:
+        """Intercept tool calls and limit response size."""
+        result = await call_next(context)
+
+        # Check if we should limit this tool
+        if self.tools is not None and context.message.name not in self.tools:
+            return result
+
+        # Measure serialized size
+        serialized = pydantic_core.to_json(result, fallback=str)
+        if len(serialized) <= self.max_size:
+            return result
+
+        # Over limit: extract text, truncate, return single TextContent
+        logger.warning(
+            "Tool %r response exceeds size limit: %d bytes > %d bytes, truncating",
+            context.message.name,
+            len(serialized),
+            self.max_size,
+        )
+
+        texts = [b.text for b in result.content if isinstance(b, TextContent)]
+        text = (
+            "\n\n".join(texts)
+            if texts
+            else serialized.decode("utf-8", errors="replace")
+        )
+
+        return self._truncate_to_result(text, meta=result.meta)
diff --git a/fastmcp_slim/fastmcp/server/middleware/timing.py b/fastmcp_slim/fastmcp/server/middleware/timing.py
new file mode 100644
index 0000000..178b3b2
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/middleware/timing.py
@@ -0,0 +1,156 @@
+"""Timing middleware for measuring and logging request performance."""
+
+import logging
+import time
+from typing import Any
+
+from .middleware import CallNext, Middleware, MiddlewareContext
+
+
+class TimingMiddleware(Middleware):
+    """Middleware that logs the execution time of requests.
+
+    Only measures and logs timing for request messages (not notifications).
+    Provides insights into performance characteristics of your MCP server.
+
+    Example:
+        ```python
+        from fastmcp.server.middleware.timing import TimingMiddleware
+
+        mcp = FastMCP("MyServer")
+        mcp.add_middleware(TimingMiddleware())
+
+        # Now all requests will be timed and logged
+        ```
+    """
+
+    def __init__(
+        self, logger: logging.Logger | None = None, log_level: int = logging.INFO
+    ):
+        """Initialize timing middleware.
+
+        Args:
+            logger: Logger instance to use. If None, creates a logger named 'fastmcp.timing'
+            log_level: Log level for timing messages (default: INFO)
+        """
+        self.logger = logger or logging.getLogger("fastmcp.timing")
+        self.log_level = log_level
+
+    async def on_request(self, context: MiddlewareContext, call_next: CallNext) -> Any:
+        """Time request execution and log the results."""
+        method = context.method or "unknown"
+
+        start_time = time.perf_counter()
+        try:
+            result = await call_next(context)
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            self.logger.log(
+                self.log_level, f"Request {method} completed in {duration_ms:.2f}ms"
+            )
+            return result
+        except Exception as e:
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            self.logger.log(
+                self.log_level,
+                f"Request {method} failed after {duration_ms:.2f}ms: {e}",
+            )
+            raise
+
+
+class DetailedTimingMiddleware(Middleware):
+    """Enhanced timing middleware with per-operation breakdowns.
+
+    Provides detailed timing information for different types of MCP operations,
+    allowing you to identify performance bottlenecks in specific operations.
+
+    Example:
+        ```python
+        from fastmcp.server.middleware.timing import DetailedTimingMiddleware
+        import logging
+
+        # Configure logging to see the output
+        logging.basicConfig(level=logging.INFO)
+
+        mcp = FastMCP("MyServer")
+        mcp.add_middleware(DetailedTimingMiddleware())
+        ```
+    """
+
+    def __init__(
+        self, logger: logging.Logger | None = None, log_level: int = logging.INFO
+    ):
+        """Initialize detailed timing middleware.
+
+        Args:
+            logger: Logger instance to use. If None, creates a logger named 'fastmcp.timing.detailed'
+            log_level: Log level for timing messages (default: INFO)
+        """
+        self.logger = logger or logging.getLogger("fastmcp.timing.detailed")
+        self.log_level = log_level
+
+    async def _time_operation(
+        self, context: MiddlewareContext, call_next: CallNext, operation_name: str
+    ) -> Any:
+        """Helper method to time any operation."""
+        start_time = time.perf_counter()
+        try:
+            result = await call_next(context)
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            self.logger.log(
+                self.log_level, f"{operation_name} completed in {duration_ms:.2f}ms"
+            )
+            return result
+        except Exception as e:
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            self.logger.log(
+                self.log_level,
+                f"{operation_name} failed after {duration_ms:.2f}ms: {e}",
+            )
+            raise
+
+    async def on_call_tool(
+        self, context: MiddlewareContext, call_next: CallNext
+    ) -> Any:
+        """Time tool execution."""
+        tool_name = getattr(context.message, "name", "unknown")
+        return await self._time_operation(context, call_next, f"Tool '{tool_name}'")
+
+    async def on_read_resource(
+        self, context: MiddlewareContext, call_next: CallNext
+    ) -> Any:
+        """Time resource reading."""
+        resource_uri = getattr(context.message, "uri", "unknown")
+        return await self._time_operation(
+            context, call_next, f"Resource '{resource_uri}'"
+        )
+
+    async def on_get_prompt(
+        self, context: MiddlewareContext, call_next: CallNext
+    ) -> Any:
+        """Time prompt retrieval."""
+        prompt_name = getattr(context.message, "name", "unknown")
+        return await self._time_operation(context, call_next, f"Prompt '{prompt_name}'")
+
+    async def on_list_tools(
+        self, context: MiddlewareContext, call_next: CallNext
+    ) -> Any:
+        """Time tool listing."""
+        return await self._time_operation(context, call_next, "List tools")
+
+    async def on_list_resources(
+        self, context: MiddlewareContext, call_next: CallNext
+    ) -> Any:
+        """Time resource listing."""
+        return await self._time_operation(context, call_next, "List resources")
+
+    async def on_list_resource_templates(
+        self, context: MiddlewareContext, call_next: CallNext
+    ) -> Any:
+        """Time resource template listing."""
+        return await self._time_operation(context, call_next, "List resource templates")
+
+    async def on_list_prompts(
+        self, context: MiddlewareContext, call_next: CallNext
+    ) -> Any:
+        """Time prompt listing."""
+        return await self._time_operation(context, call_next, "List prompts")
diff --git a/fastmcp_slim/fastmcp/server/middleware/tool_injection.py b/fastmcp_slim/fastmcp/server/middleware/tool_injection.py
new file mode 100644
index 0000000..ef88dfc
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/middleware/tool_injection.py
@@ -0,0 +1,46 @@
+"""A middleware for injecting tools into the MCP server context."""
+
+from collections.abc import Sequence
+from logging import Logger
+
+import mcp_types
+from typing_extensions import override
+
+from fastmcp.server.middleware.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.tools.base import Tool, ToolResult
+from fastmcp.utilities.logging import get_logger
+
+logger: Logger = get_logger(name=__name__)
+
+
+class ToolInjectionMiddleware(Middleware):
+    """A middleware for injecting tools into the context."""
+
+    def __init__(self, tools: Sequence[Tool]):
+        """Initialize the tool injection middleware."""
+        self._tools_to_inject: Sequence[Tool] = tools
+        self._tools_to_inject_by_name: dict[str, Tool] = {
+            tool.name: tool for tool in tools
+        }
+
+    @override
+    async def on_list_tools(
+        self,
+        context: MiddlewareContext[mcp_types.ListToolsRequest],
+        call_next: CallNext[mcp_types.ListToolsRequest, Sequence[Tool]],
+    ) -> Sequence[Tool]:
+        """Inject tools into the response."""
+        return [*self._tools_to_inject, *await call_next(context)]
+
+    @override
+    async def on_call_tool(
+        self,
+        context: MiddlewareContext[mcp_types.CallToolRequestParams],
+        call_next: CallNext[mcp_types.CallToolRequestParams, ToolResult],
+    ) -> ToolResult:
+        """Intercept tool calls to injected tools."""
+        if context.message.name in self._tools_to_inject_by_name:
+            tool = self._tools_to_inject_by_name[context.message.name]
+            return await tool.run(arguments=context.message.arguments or {})
+
+        return await call_next(context)
diff --git a/fastmcp_slim/fastmcp/server/mixins/__init__.py b/fastmcp_slim/fastmcp/server/mixins/__init__.py
new file mode 100644
index 0000000..3df6e8d
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/mixins/__init__.py
@@ -0,0 +1,7 @@
+"""Server mixins for FastMCP."""
+
+from fastmcp.server.mixins.lifespan import LifespanMixin
+from fastmcp.server.mixins.mcp_operations import MCPOperationsMixin
+from fastmcp.server.mixins.transport import TransportMixin
+
+__all__ = ["LifespanMixin", "MCPOperationsMixin", "TransportMixin"]
diff --git a/fastmcp_slim/fastmcp/server/mixins/lifespan.py b/fastmcp_slim/fastmcp/server/mixins/lifespan.py
new file mode 100644
index 0000000..77374d3
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/mixins/lifespan.py
@@ -0,0 +1,334 @@
+"""Lifespan and Docket task infrastructure for FastMCP Server."""
+
+from __future__ import annotations
+
+import asyncio
+import weakref
+from collections.abc import AsyncIterator
+from contextlib import AsyncExitStack, asynccontextmanager, suppress
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, Any
+
+import anyio
+from uncalled_for import SharedContext
+
+import fastmcp
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    from docket import Docket
+
+    from fastmcp.server.server import FastMCP
+
+logger = get_logger(__name__)
+
+
+# Set True by `FastMCPProvider.lifespan` immediately before it enters the
+# wrapped (mounted) server's `_lifespan_manager`, and reset on exit. The
+# mounted server's `_docket_lifespan` reads this and becomes a no-op so that
+# Docket / Worker / SharedContext are not re-initialized — there's one set
+# per runtime tree, owned by the root.
+#
+# Independent servers entered as siblings (e.g. via `AsyncExitStack` in the
+# same async context) are NOT in a parent/child relationship; the flag is not
+# set in that case, so each independently establishes its own Docket and
+# server context.
+_lifespan_root_active: ContextVar[bool] = ContextVar(
+    "fastmcp_lifespan_root_active", default=False
+)
+
+
+class LifespanMixin:
+    """Mixin providing lifespan and Docket task infrastructure for FastMCP."""
+
+    @property
+    def docket(self: FastMCP) -> Docket | None:
+        """The Docket instance owned by this server.
+
+        Returns the Docket that this server initialized as the root of a
+        runtime tree. Mounted children do not own their own Docket — they
+        share the root's via ``_current_docket`` ContextVar inheritance —
+        so accessing ``.docket`` on a mounted child returns None even while
+        its tasks run on the root's Docket. For "the Docket in scope right
+        now," prefer reading ``_current_docket`` directly or use the
+        ``CurrentDocket`` dependency injection.
+        """
+        return self._docket
+
+    @asynccontextmanager
+    async def _docket_lifespan(self: FastMCP) -> AsyncIterator[None]:
+        """Manage Docket instance and Worker for background task execution.
+
+        Docket is process-level, not server-level: only the first server in a
+        runtime tree starts Docket and the Worker. Mounted children entered
+        via ``FastMCPProvider.lifespan`` see ``_lifespan_root_active=True``
+        (set by the provider before delegating to ``_lifespan_manager``) and
+        become no-ops, sharing the root's Docket via ``_current_docket``.
+
+        Independent servers entered as siblings — for example two unrelated
+        ``FastMCP`` instances each entered through ``AsyncExitStack`` in the
+        same async context — are not in a parent/child relationship; no
+        provider has set the flag for them, so each runs the full root setup.
+
+        Docket infrastructure is only initialized at the root if:
+        1. pydocket is installed (fastmcp[tasks] extra)
+        2. There are task-enabled components (task_config.mode != 'forbidden')
+
+        Users with pydocket installed but no task-enabled components won't spin
+        up Docket / Worker infrastructure even at the root.
+        """
+        # Nested entry: a parent in this runtime tree already owns Docket and
+        # SharedContext (the FastMCPProvider that mounted us set the flag).
+        # Stay out of their way and inherit via ContextVars.
+        if _lifespan_root_active.get():
+            yield
+            return
+
+        async with self._docket_lifespan_root():
+            yield
+
+    @asynccontextmanager
+    async def _docket_lifespan_root(self: FastMCP) -> AsyncIterator[None]:
+        """Root-only Docket lifecycle. See _docket_lifespan for the dispatch."""
+        from fastmcp.server.dependencies import _current_server, is_docket_available
+
+        # Set FastMCP server in ContextVar so CurrentFastMCP can access it
+        # (use weakref to avoid reference cycles)
+        server_token = _current_server.set(weakref.ref(self))
+
+        try:
+            # If docket is not available, skip task infrastructure but still
+            # set up SharedContext so Shared() dependencies work.
+            if not is_docket_available():
+                async with SharedContext():
+                    self._capture_shared_context()
+                    yield
+                return
+
+            # Collect task-enabled components at startup with all transforms applied.
+            # Components must be available now to be registered with Docket workers;
+            # dynamically added components after startup won't be registered.
+            try:
+                task_components = list(await self.get_tasks())
+            except Exception as e:
+                logger.warning(f"Failed to get tasks: {e}")
+                if fastmcp.settings.mounted_components_raise_on_load_error:
+                    raise
+                task_components = []
+
+            # If no task-enabled components, skip Docket infrastructure but still
+            # set up SharedContext so Shared() dependencies work.
+            if not task_components:
+                async with SharedContext():
+                    self._capture_shared_context()
+                    yield
+                return
+
+            # Docket is available AND there are task-enabled components
+            from docket import Depends, Docket, Worker
+
+            from fastmcp import settings
+            from fastmcp.server.dependencies import (
+                _current_docket,
+                _current_worker,
+            )
+            from fastmcp.server.tasks.context import restore_task_snapshot
+
+            # Create Docket instance using configured name and URL
+            async with (
+                SharedContext(),
+                Docket(
+                    name=settings.docket.name,
+                    url=settings.docket.url,
+                ) as docket,
+            ):
+                self._capture_shared_context()
+                self._docket = docket
+
+                # Register task-enabled components with Docket
+                for component in task_components:
+                    component.register_with_docket(docket)
+
+                docket_token = _current_docket.set(docket)
+                try:
+                    # Build worker kwargs from settings
+                    worker_kwargs: dict[str, Any] = {
+                        "concurrency": settings.docket.concurrency,
+                        "redelivery_timeout": settings.docket.redelivery_timeout,
+                        "reconnection_delay": settings.docket.reconnection_delay,
+                        "minimum_check_interval": settings.docket.minimum_check_interval,
+                    }
+                    if settings.docket.worker_name:
+                        worker_kwargs["name"] = settings.docket.worker_name
+
+                    # Create and start Worker.  The restore_task_snapshot
+                    # worker-level dependency runs before every task so the
+                    # per-task snapshot ContextVar is populated before user
+                    # code or task-scoped dependencies observe it.
+                    async with Worker(
+                        docket,
+                        dependencies=[Depends(restore_task_snapshot)],
+                        **worker_kwargs,
+                    ) as worker:
+                        self._worker = worker
+                        worker_token = _current_worker.set(worker)
+                        try:
+                            worker_task = asyncio.create_task(worker.run_forever())
+                            try:
+                                yield
+                            finally:
+                                worker_task.cancel()
+                                with suppress(asyncio.CancelledError):
+                                    await worker_task
+                        finally:
+                            _current_worker.reset(worker_token)
+                            self._worker = None
+                finally:
+                    _current_docket.reset(docket_token)
+                    self._docket = None
+        finally:
+            # Reset server ContextVar
+            _current_server.reset(server_token)
+
+    def _capture_shared_context(self: FastMCP) -> None:
+        """Snapshot the live ``SharedContext`` ContextVar values.
+
+        The SDK v2 dispatcher runs each request handler in the *message
+        sender's* contextvars (via ``ContextReceiveStream.last_context``), not
+        the server-lifespan context. App-scoped ``Shared()`` dependencies rely
+        on ``uncalled_for.SharedContext`` ContextVars set during the lifespan,
+        which are therefore invisible to handlers. We capture those values here
+        so ``FastMCPServerMiddleware`` can re-apply them per request.
+        """
+        try:
+            self._shared_context_snapshot = {
+                SharedContext.resolved: SharedContext.resolved.get(),
+                SharedContext.lock: SharedContext.lock.get(),
+                SharedContext.stack: SharedContext.stack.get(),
+            }
+        except LookupError:  # pragma: no cover - SharedContext not active
+            self._shared_context_snapshot = None
+
+    @asynccontextmanager
+    async def _lifespan_manager(self: FastMCP) -> AsyncIterator[None]:
+        async with self._lifespan_lock:
+            if self._lifespan_result_set:
+                self._lifespan_ref_count += 1
+                should_enter_lifespan = False
+            else:
+                self._lifespan_ref_count = 1
+                should_enter_lifespan = True
+
+        if not should_enter_lifespan:
+            try:
+                yield
+            finally:
+                async with self._lifespan_lock:
+                    self._lifespan_ref_count -= 1
+                    if self._lifespan_ref_count == 0:
+                        self._lifespan_result_set = False
+                        self._lifespan_result = None
+            return
+
+        # Use an explicit AsyncExitStack so we can shield teardown from
+        # cancellation. Without this, Ctrl-C causes CancelledError to
+        # propagate into lifespan finally blocks, preventing any async
+        # cleanup (e.g. closing DB connections, flushing buffers).
+        stack = AsyncExitStack()
+        try:
+            user_lifespan_result = await stack.enter_async_context(self._lifespan(self))
+            await stack.enter_async_context(self._docket_lifespan())
+
+            self._lifespan_result = user_lifespan_result
+            self._lifespan_result_set = True
+
+            # Start lifespans for all providers
+            for provider in self.providers:
+                await stack.enter_async_context(provider.lifespan())
+
+            self._started.set()
+            try:
+                yield
+            finally:
+                self._started.clear()
+        finally:
+            try:
+                with anyio.CancelScope(shield=True):
+                    await stack.aclose()
+            finally:
+                async with self._lifespan_lock:
+                    self._lifespan_ref_count -= 1
+                    if self._lifespan_ref_count == 0:
+                        self._lifespan_result_set = False
+                        self._lifespan_result = None
+
+    def _setup_task_protocol_handlers(self: FastMCP) -> None:
+        """Register SEP-1686 task protocol handlers with SDK.
+
+        Only registers handlers if docket is installed. Without docket,
+        task protocol requests will return "method not found" errors.
+        """
+        from fastmcp.server.dependencies import is_docket_available
+
+        if not is_docket_available():
+            return
+
+        from mcp.server.context import ServerRequestContext
+        from mcp_types import (
+            CancelTaskRequestParams,
+            GetTaskPayloadRequestParams,
+            GetTaskRequestParams,
+            PaginatedRequestParams,
+        )
+
+        from fastmcp.server.dependencies import bind_request_context
+        from fastmcp.server.tasks.requests import (
+            tasks_cancel_handler,
+            tasks_get_handler,
+            tasks_list_handler,
+            tasks_result_handler,
+        )
+
+        # v2 handlers take (ctx, params) and return the bare result model.
+
+        async def handle_get_task(
+            ctx: ServerRequestContext, params: GetTaskRequestParams
+        ) -> Any:
+            with bind_request_context(ctx):
+                p = params.model_dump(by_alias=True, exclude_none=True)
+                return await tasks_get_handler(self, p)
+
+        async def handle_get_task_result(
+            ctx: ServerRequestContext, params: GetTaskPayloadRequestParams
+        ) -> Any:
+            with bind_request_context(ctx):
+                p = params.model_dump(by_alias=True, exclude_none=True)
+                return await tasks_result_handler(self, p)
+
+        async def handle_list_tasks(
+            ctx: ServerRequestContext, params: PaginatedRequestParams | None
+        ) -> Any:
+            with bind_request_context(ctx):
+                p = (
+                    params.model_dump(by_alias=True, exclude_none=True)
+                    if params
+                    else {}
+                )
+                return await tasks_list_handler(self, p)
+
+        async def handle_cancel_task(
+            ctx: ServerRequestContext, params: CancelTaskRequestParams
+        ) -> Any:
+            with bind_request_context(ctx):
+                p = params.model_dump(by_alias=True, exclude_none=True)
+                return await tasks_cancel_handler(self, p)
+
+        s = self._mcp_server
+        s.add_request_handler("tasks/get", GetTaskRequestParams, handle_get_task)
+        s.add_request_handler(
+            "tasks/result", GetTaskPayloadRequestParams, handle_get_task_result
+        )
+        s.add_request_handler("tasks/list", PaginatedRequestParams, handle_list_tasks)
+        s.add_request_handler(
+            "tasks/cancel", CancelTaskRequestParams, handle_cancel_task
+        )
diff --git a/fastmcp_slim/fastmcp/server/mixins/mcp_operations.py b/fastmcp_slim/fastmcp/server/mixins/mcp_operations.py
new file mode 100644
index 0000000..74e59ae
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/mixins/mcp_operations.py
@@ -0,0 +1,342 @@
+"""MCP protocol handler setup and wire-format handlers for FastMCP Server."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any, TypeVar
+
+import mcp_types
+from mcp.server.context import ServerRequestContext
+from mcp.shared.exceptions import MCPError
+from mcp_types import (
+    INVALID_PARAMS,
+    CallToolRequestParams,
+    EmptyResult,
+    GetPromptRequestParams,
+    PaginatedRequestParams,
+    ReadResourceRequestParams,
+    SetLevelRequestParams,
+)
+
+from fastmcp.exceptions import (
+    DisabledError,
+    FastMCPError,
+    NotFoundError,
+    to_mcp_error,
+)
+from fastmcp.server.dependencies import bind_request_context, extract_version_spec
+from fastmcp.server.tasks.config import TaskMeta
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.pagination import paginate_sequence
+from fastmcp.utilities.versions import VersionSpec, dedupe_with_versions
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP
+
+logger = get_logger(__name__)
+
+PaginateT = TypeVar("PaginateT")
+
+
+def _apply_pagination(
+    items: Sequence[PaginateT],
+    cursor: str | None,
+    page_size: int | None,
+) -> tuple[list[PaginateT], str | None]:
+    """Apply pagination to items, raising MCPError for invalid cursors.
+
+    If page_size is None, returns all items without pagination.
+    """
+    if page_size is None:
+        return list(items), None
+    try:
+        return paginate_sequence(items, cursor, page_size)
+    except ValueError as e:
+        raise MCPError(code=INVALID_PARAMS, message=str(e)) from e
+
+
+def _normalize_call_tool_result(
+    result: Any,
+) -> mcp_types.CallToolResult:
+    """Normalize a tool's ``to_mcp_result()`` output into a ``CallToolResult``.
+
+    ``ToolResult.to_mcp_result()`` returns one of three shapes for backward
+    compatibility: a ``CallToolResult`` (error/meta case), a bare
+    ``list[ContentBlock]`` (unstructured), or a ``(content, structured)`` tuple.
+    The SDK v2 runner requires a ``BaseModel`` result, so wrap the shorthand
+    forms here (the SDK's old ``call_tool`` decorator used to do this).
+    """
+    if isinstance(result, mcp_types.CallToolResult):
+        return result
+    if isinstance(result, tuple):
+        content, structured = result
+        return mcp_types.CallToolResult(content=content, structured_content=structured)
+    return mcp_types.CallToolResult(content=result)
+
+
+def _version_from_ctx(ctx: ServerRequestContext) -> VersionSpec | None:
+    """Extract the FastMCP component version from the request's lifted _meta."""
+    from fastmcp.server.dependencies import _lift_meta
+
+    version_str = extract_version_spec(_lift_meta(ctx))
+    return VersionSpec(eq=version_str) if version_str else None
+
+
+class MCPOperationsMixin:
+    """Mixin providing MCP protocol handler setup and wire-format handlers.
+
+    Handlers are registered via ``add_request_handler(method, params_type,
+    handler)`` on the low-level SDK server. Each adapter takes
+    ``(ctx: ServerRequestContext, params)`` and returns the bare SDK result
+    model (no ``ServerResult`` wrapping — the SDK v2 runner serializes the
+    result itself).
+    """
+
+    def _setup_handlers(self: FastMCP) -> None:
+        """Register core MCP protocol handlers with the low-level SDK server."""
+        s = self._mcp_server
+        s.add_request_handler("tools/list", PaginatedRequestParams, self._on_list_tools)
+        s.add_request_handler(
+            "resources/list", PaginatedRequestParams, self._on_list_resources
+        )
+        s.add_request_handler(
+            "resources/templates/list",
+            PaginatedRequestParams,
+            self._on_list_resource_templates,
+        )
+        s.add_request_handler(
+            "prompts/list", PaginatedRequestParams, self._on_list_prompts
+        )
+        s.add_request_handler("tools/call", CallToolRequestParams, self._on_call_tool)
+        s.add_request_handler(
+            "resources/read", ReadResourceRequestParams, self._on_read_resource
+        )
+        s.add_request_handler(
+            "prompts/get", GetPromptRequestParams, self._on_get_prompt
+        )
+        s.add_request_handler(
+            "logging/setLevel", SetLevelRequestParams, self._on_set_logging_level
+        )
+
+        # Register SEP-1686 task protocol handlers
+        self._setup_task_protocol_handlers()
+
+    async def _on_list_tools(
+        self: FastMCP,
+        ctx: ServerRequestContext,
+        params: PaginatedRequestParams | None,
+    ) -> mcp_types.ListToolsResult:
+        """List all available tools. Supports pagination via params.cursor."""
+        with bind_request_context(ctx):
+            logger.debug(f"[{self.name}] Handler called: list_tools")
+
+            tools = dedupe_with_versions(
+                list(await self.list_tools()), lambda t: t.name
+            )
+            sdk_tools = [tool.to_mcp_tool(name=tool.name) for tool in tools]
+            cursor = params.cursor if params else None
+            page, next_cursor = _apply_pagination(
+                sdk_tools, cursor, self._list_page_size
+            )
+            return mcp_types.ListToolsResult(tools=page, next_cursor=next_cursor)
+
+    async def _on_list_resources(
+        self: FastMCP,
+        ctx: ServerRequestContext,
+        params: PaginatedRequestParams | None,
+    ) -> mcp_types.ListResourcesResult:
+        """List all available resources. Supports pagination via params.cursor."""
+        with bind_request_context(ctx):
+            logger.debug(f"[{self.name}] Handler called: list_resources")
+
+            resources = dedupe_with_versions(
+                list(await self.list_resources()), lambda r: str(r.uri)
+            )
+            sdk_resources = [
+                resource.to_mcp_resource(uri=str(resource.uri))
+                for resource in resources
+            ]
+            cursor = params.cursor if params else None
+            page, next_cursor = _apply_pagination(
+                sdk_resources, cursor, self._list_page_size
+            )
+            return mcp_types.ListResourcesResult(
+                resources=page, next_cursor=next_cursor
+            )
+
+    async def _on_list_resource_templates(
+        self: FastMCP,
+        ctx: ServerRequestContext,
+        params: PaginatedRequestParams | None,
+    ) -> mcp_types.ListResourceTemplatesResult:
+        """List all available resource templates. Supports pagination."""
+        with bind_request_context(ctx):
+            logger.debug(f"[{self.name}] Handler called: list_resource_templates")
+
+            templates = dedupe_with_versions(
+                list(await self.list_resource_templates()), lambda t: t.uri_template
+            )
+            sdk_templates = [
+                template.to_mcp_template(uri_template=template.uri_template)
+                for template in templates
+            ]
+            cursor = params.cursor if params else None
+            page, next_cursor = _apply_pagination(
+                sdk_templates, cursor, self._list_page_size
+            )
+            return mcp_types.ListResourceTemplatesResult(
+                resource_templates=page, next_cursor=next_cursor
+            )
+
+    async def _on_list_prompts(
+        self: FastMCP,
+        ctx: ServerRequestContext,
+        params: PaginatedRequestParams | None,
+    ) -> mcp_types.ListPromptsResult:
+        """List all available prompts. Supports pagination via params.cursor."""
+        with bind_request_context(ctx):
+            logger.debug(f"[{self.name}] Handler called: list_prompts")
+
+            prompts = dedupe_with_versions(
+                list(await self.list_prompts()), lambda p: p.name
+            )
+            sdk_prompts = [prompt.to_mcp_prompt(name=prompt.name) for prompt in prompts]
+            cursor = params.cursor if params else None
+            page, next_cursor = _apply_pagination(
+                sdk_prompts, cursor, self._list_page_size
+            )
+            return mcp_types.ListPromptsResult(prompts=page, next_cursor=next_cursor)
+
+    async def _on_call_tool(
+        self: FastMCP,
+        ctx: ServerRequestContext,
+        params: CallToolRequestParams,
+    ) -> mcp_types.CallToolResult | mcp_types.CreateTaskResult:
+        """Handle MCP 'tools/call' requests.
+
+        Task metadata is a first-class params field (``params.task``); its
+        presence triggers backgrounding. The tool's ``_run()`` handles the
+        backgrounding decision so middleware runs before Docket.
+        """
+        with bind_request_context(ctx):
+            key = params.name
+            arguments = params.arguments or {}
+            logger.debug(
+                f"[{self.name}] Handler called: call_tool %s with %s", key, arguments
+            )
+
+            version = _version_from_ctx(ctx)
+            task_meta = (
+                TaskMeta(ttl=params.task.ttl) if params.task is not None else None
+            )
+
+            try:
+                result = await self.call_tool(
+                    key, arguments, version=version, task_meta=task_meta
+                )
+            except (DisabledError, NotFoundError):
+                # Unknown/disabled tool: return an error result (matching the
+                # v1 SDK's call_tool behavior) so the client surfaces a
+                # ToolError rather than a raw protocol error.
+                return mcp_types.CallToolResult(
+                    content=[
+                        mcp_types.TextContent(
+                            type="text", text=f"Unknown tool: {key!r}"
+                        )
+                    ],
+                    is_error=True,
+                )
+            except FastMCPError as e:
+                # Tool-visible errors (ToolError, ValidationError, ...) must be
+                # RETURNED as an error result, never raised — the SDK v2 runner
+                # turns a raise into a -32603 wire error. Masking already
+                # happened inside call_tool.
+                return mcp_types.CallToolResult(
+                    content=[mcp_types.TextContent(type="text", text=str(e))],
+                    is_error=True,
+                )
+
+            if isinstance(result, mcp_types.CreateTaskResult):
+                return result
+            return _normalize_call_tool_result(result.to_mcp_result())
+
+    async def _on_read_resource(
+        self: FastMCP,
+        ctx: ServerRequestContext,
+        params: ReadResourceRequestParams,
+    ) -> mcp_types.ReadResourceResult | mcp_types.CreateTaskResult:
+        """Handle MCP 'resources/read' requests.
+
+        Note: ``ReadResourceRequestParams`` has no ``task`` field in this SDK
+        version, so resource task submission over the wire is not expressible;
+        ``task_meta`` is always None here. The CreateTaskResult return branch is
+        retained harmlessly pending an upstream ``task`` field on these params.
+        """
+        with bind_request_context(ctx):
+            uri = params.uri
+            logger.debug(f"[{self.name}] Handler called: read_resource %s", uri)
+
+            version = _version_from_ctx(ctx)
+
+            try:
+                result = await self.read_resource(str(uri), version=version)
+            except (DisabledError, NotFoundError) as e:
+                raise to_mcp_error(
+                    NotFoundError(f"Resource not found: {str(uri)!r}")
+                ) from e
+
+            if isinstance(result, mcp_types.CreateTaskResult):
+                return result
+            return result.to_mcp_result(uri)
+
+    async def _on_get_prompt(
+        self: FastMCP,
+        ctx: ServerRequestContext,
+        params: GetPromptRequestParams,
+    ) -> mcp_types.GetPromptResult | mcp_types.CreateTaskResult:
+        """Handle MCP 'prompts/get' requests.
+
+        Note: ``GetPromptRequestParams`` has no ``task`` field in this SDK
+        version, so prompt task submission over the wire is not expressible;
+        ``task_meta`` is always None here.
+        """
+        with bind_request_context(ctx):
+            name = params.name
+            arguments = params.arguments
+            logger.debug(
+                f"[{self.name}] Handler called: get_prompt %s with %s",
+                name,
+                arguments,
+            )
+
+            version = _version_from_ctx(ctx)
+
+            try:
+                result = await self.render_prompt(name, arguments, version=version)
+            except (DisabledError, NotFoundError) as e:
+                raise to_mcp_error(NotFoundError(f"Unknown prompt: {name!r}")) from e
+
+            if isinstance(result, mcp_types.CreateTaskResult):
+                return result
+            return result.to_mcp_prompt_result()
+
+    async def _on_set_logging_level(
+        self: FastMCP,
+        ctx: ServerRequestContext,
+        params: SetLevelRequestParams,
+    ) -> mcp_types.EmptyResult:
+        """Handle MCP 'logging/setLevel' requests.
+
+        Stores the requested minimum log level keyed by session id so that
+        subsequent log messages below this level are suppressed. v2 sessions are
+        per-request, so this state lives on the FastMCP server.
+        """
+        from fastmcp.server.context import _log_level_session_key
+
+        with bind_request_context(ctx) as rc:
+            logger.debug(
+                f"[{self.name}] Handler called: set_logging_level %s", params.level
+            )
+            session_id = _log_level_session_key(rc.session)
+            self._client_log_levels[session_id] = params.level
+            return EmptyResult()
diff --git a/fastmcp_slim/fastmcp/server/mixins/transport.py b/fastmcp_slim/fastmcp/server/mixins/transport.py
new file mode 100644
index 0000000..ddc96db
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/mixins/transport.py
@@ -0,0 +1,466 @@
+"""Transport-related methods for FastMCP Server."""
+
+from __future__ import annotations
+
+import socket
+from collections.abc import Awaitable, Callable
+from functools import partial
+from typing import TYPE_CHECKING, Any, Literal
+
+import anyio
+import uvicorn
+from mcp.server.lowlevel.server import NotificationOptions
+from mcp.server.stdio import stdio_server
+from starlette.middleware import Middleware as ASGIMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.routing import BaseRoute, Route
+
+import fastmcp
+from fastmcp.server.event_store import EventStore
+from fastmcp.server.http import (
+    HostOriginProtection,
+    StarletteWithLifespan,
+    _is_loopback_host,
+    create_sse_app,
+    create_streamable_http_app,
+)
+from fastmcp.server.providers.base import Provider
+from fastmcp.server.providers.fastmcp_provider import FastMCPProvider
+from fastmcp.server.providers.wrapped_provider import _WrappedProvider
+from fastmcp.utilities.cli import log_server_banner
+from fastmcp.utilities.logging import get_logger, temporary_log_level
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP, Transport
+
+logger = get_logger(__name__)
+
+
+def _format_host_for_url(host: str) -> str:
+    """Format a host for inclusion in a URL, bracketing IPv6 addresses.
+
+    A bare IPv6 address like ``::1`` must be wrapped in brackets when placed
+    before a ``:port`` suffix, otherwise the result (``http://::1:8000``) is an
+    invalid URL. Hostnames and IPv4 addresses are returned unchanged, as are
+    addresses that are already bracketed.
+    """
+    if ":" in host and not host.startswith("["):
+        return f"[{host}]"
+    return host
+
+
+def _resolve_allowed_hosts_for_run(
+    *,
+    host: str,
+    host_origin_protection: HostOriginProtection,
+    allowed_hosts: list[str] | None,
+    configured_allowed_hosts: list[str] | None,
+) -> list[str] | None:
+    if allowed_hosts is not None:
+        return allowed_hosts
+
+    if host_origin_protection == "auto" and _is_loopback_host(host):
+        return [*(configured_allowed_hosts or []), host]
+
+    return configured_allowed_hosts
+
+
+class TransportMixin:
+    """Mixin providing transport-related methods for FastMCP.
+
+    Includes HTTP/stdio/SSE transport handling and custom HTTP routes.
+    """
+
+    async def run_async(
+        self: FastMCP,
+        transport: Transport | None = None,
+        show_banner: bool | None = None,
+        **transport_kwargs: Any,
+    ) -> None:
+        """Run the FastMCP server asynchronously.
+
+        Args:
+            transport: Transport protocol to use ("stdio", "http", "sse", or "streamable-http")
+            show_banner: Whether to display the server banner. If None, uses the
+                FASTMCP_SHOW_SERVER_BANNER setting (default: True).
+        """
+        if show_banner is None:
+            show_banner = fastmcp.settings.show_server_banner
+        if transport is None:
+            transport = fastmcp.settings.transport
+        if transport not in {"stdio", "http", "sse", "streamable-http"}:
+            raise ValueError(f"Unknown transport: {transport}")
+
+        if transport == "stdio":
+            await self.run_stdio_async(
+                show_banner=show_banner,
+                **transport_kwargs,
+            )
+        elif transport in {"http", "sse", "streamable-http"}:
+            await self.run_http_async(
+                transport=transport,
+                show_banner=show_banner,
+                **transport_kwargs,
+            )
+        else:
+            raise ValueError(f"Unknown transport: {transport}")
+
+    def run(
+        self: FastMCP,
+        transport: Transport | None = None,
+        show_banner: bool | None = None,
+        **transport_kwargs: Any,
+    ) -> None:
+        """Run the FastMCP server. Note this is a synchronous function.
+
+        Args:
+            transport: Transport protocol to use ("http", "stdio", "sse", or "streamable-http")
+            show_banner: Whether to display the server banner. If None, uses the
+                FASTMCP_SHOW_SERVER_BANNER setting (default: True).
+        """
+
+        anyio.run(
+            partial(
+                self.run_async,
+                transport,
+                show_banner=show_banner,
+                **transport_kwargs,
+            )
+        )
+
+    def custom_route(
+        self: FastMCP,
+        path: str,
+        methods: list[str],
+        name: str | None = None,
+        include_in_schema: bool = True,
+    ) -> Callable[
+        [Callable[[Request], Awaitable[Response]]],
+        Callable[[Request], Awaitable[Response]],
+    ]:
+        """
+        Decorator to register a custom HTTP route on the FastMCP server.
+
+        Allows adding arbitrary HTTP endpoints outside the standard MCP protocol,
+        which can be useful for OAuth callbacks, health checks, or admin APIs.
+        The handler function must be an async function that accepts a Starlette
+        Request and returns a Response.
+
+        Args:
+            path: URL path for the route (e.g., "/auth/callback")
+            methods: List of HTTP methods to support (e.g., ["GET", "POST"])
+            name: Optional name for the route (to reference this route with
+                Starlette's reverse URL lookup feature)
+            include_in_schema: Whether to include in OpenAPI schema, defaults to True
+
+        Example:
+            Register a custom HTTP route for a health check endpoint:
+            ```python
+            @server.custom_route("/health", methods=["GET"])
+            async def health_check(request: Request) -> Response:
+                return JSONResponse({"status": "ok"})
+            ```
+        """
+
+        def decorator(
+            fn: Callable[[Request], Awaitable[Response]],
+        ) -> Callable[[Request], Awaitable[Response]]:
+            self._additional_http_routes.append(
+                Route(
+                    path,
+                    endpoint=fn,
+                    methods=methods,
+                    name=name,
+                    include_in_schema=include_in_schema,
+                )
+            )
+            return fn
+
+        return decorator
+
+    def _get_additional_http_routes(self: FastMCP) -> list[BaseRoute]:
+        """Get all additional HTTP routes including from mounted servers.
+
+        Collects custom HTTP routes registered via ``@server.custom_route()``
+        from this server **and** from any FastMCP servers reachable through
+        mounted providers (recursively).  This ensures that routes defined on
+        a child server are forwarded to the parent's HTTP app when using
+        ``server.mount(child)``.
+
+        Note:
+            When path collisions occur between a parent and a mounted child,
+            the parent's routes take precedence because they appear first in
+            the returned list.
+
+        Returns:
+            List of Starlette Route objects
+        """
+        routes: list[BaseRoute] = list(self._additional_http_routes)
+
+        def _unwrap_provider(provider: Provider) -> Provider:
+            """Unwrap _WrappedProvider layers to find the inner provider."""
+            while isinstance(provider, _WrappedProvider):
+                provider = provider._inner
+            return provider
+
+        for provider in self.providers:
+            inner = _unwrap_provider(provider)
+            if isinstance(inner, FastMCPProvider):
+                # Recurse into the mounted server to collect its routes
+                # (and any routes from servers mounted on *it*).
+                routes.extend(inner.server._get_additional_http_routes())
+
+        return routes
+
+    async def run_stdio_async(
+        self: FastMCP,
+        show_banner: bool = True,
+        log_level: str | None = None,
+        stateless: bool = False,
+    ) -> None:
+        """Run the server using stdio transport.
+
+        Args:
+            show_banner: Whether to display the server banner
+            log_level: Log level for the server
+            stateless: Whether to run in stateless mode (no session initialization)
+        """
+        from fastmcp.server.context import reset_transport, set_transport
+
+        # Display server banner
+        if show_banner:
+            log_server_banner(server=self)
+
+        token = set_transport("stdio")
+        try:
+            with temporary_log_level(log_level):
+                async with self._lifespan_manager():
+                    async with stdio_server() as (read_stream, write_stream):
+                        mode = " (stateless)" if stateless else ""
+                        logger.info(
+                            f"Starting MCP server {self.name!r} with transport 'stdio'{mode}"
+                        )
+
+                        await self._mcp_server.run(
+                            read_stream,
+                            write_stream,
+                            self._mcp_server.create_initialization_options(
+                                notification_options=NotificationOptions(
+                                    tools_changed=True
+                                ),
+                            ),
+                        )
+        finally:
+            reset_transport(token)
+
+    async def run_http_async(
+        self: FastMCP,
+        show_banner: bool = True,
+        transport: Literal["http", "streamable-http", "sse"] = "http",
+        host: str | None = None,
+        port: int | None = None,
+        log_level: str | None = None,
+        path: str | None = None,
+        uvicorn_config: dict[str, Any] | None = None,
+        middleware: list[ASGIMiddleware] | None = None,
+        json_response: bool | None = None,
+        stateless_http: bool | None = None,
+        stateless: bool | None = None,
+        host_origin_protection: HostOriginProtection | None = None,
+        allowed_hosts: list[str] | None = None,
+        allowed_origins: list[str] | None = None,
+        sockets: list[socket.socket] | None = None,
+    ) -> None:
+        """Run the server using HTTP transport.
+
+        Args:
+            transport: Transport protocol to use - "http" (default), "streamable-http", or "sse"
+            host: Host address to bind to (defaults to settings.host)
+            port: Port to bind to (defaults to settings.port)
+            log_level: Log level for the server (defaults to settings.log_level)
+            path: Path for the endpoint (defaults to settings.streamable_http_path or settings.sse_path)
+            uvicorn_config: Additional configuration for the Uvicorn server
+            middleware: A list of middleware to apply to the app
+            json_response: Whether to use JSON response format (defaults to settings.json_response)
+            stateless_http: Whether to use stateless HTTP (defaults to settings.stateless_http)
+            stateless: Alias for stateless_http for CLI consistency
+            host_origin_protection: Whether to validate Host and Origin headers
+                before requests reach the MCP endpoint. Defaults to
+                settings.http_host_origin_protection. "auto" protects
+                localhost-bound servers and explicit host/origin allowlists.
+            allowed_hosts: Additional hostnames that may appear in the Host header.
+            allowed_origins: Additional browser origins trusted by the request guard.
+                Configure CORS separately when browser JavaScript must read
+                cross-origin responses.
+            sockets: Pre-bound sockets to pass to Uvicorn
+        """
+        # Allow stateless as alias for stateless_http
+        if stateless is not None and stateless_http is None:
+            stateless_http = stateless
+
+        # Resolve from settings/env var if not explicitly set
+        if stateless_http is None:
+            stateless_http = fastmcp.settings.stateless_http
+
+        # SSE doesn't support stateless mode
+        if stateless_http and transport == "sse":
+            raise ValueError("SSE transport does not support stateless mode")
+
+        host = host if host is not None else fastmcp.settings.host
+        port = port if port is not None else fastmcp.settings.port
+        resolved_host_origin_protection = (
+            host_origin_protection
+            if host_origin_protection is not None
+            else fastmcp.settings.http_host_origin_protection
+        )
+        resolved_allowed_hosts = _resolve_allowed_hosts_for_run(
+            host=host,
+            host_origin_protection=resolved_host_origin_protection,
+            allowed_hosts=allowed_hosts,
+            configured_allowed_hosts=fastmcp.settings.http_allowed_hosts,
+        )
+        default_log_level_to_use = (
+            log_level if log_level is not None else fastmcp.settings.log_level
+        ).lower()
+
+        app = self.http_app(
+            path=path,
+            transport=transport,
+            middleware=middleware,
+            json_response=json_response,
+            stateless_http=stateless_http,
+            host_origin_protection=resolved_host_origin_protection,
+            allowed_hosts=resolved_allowed_hosts,
+            allowed_origins=allowed_origins,
+        )
+
+        # Display server banner
+        if show_banner:
+            log_server_banner(server=self)
+        uvicorn_config_from_user = uvicorn_config or {}
+
+        config_kwargs: dict[str, Any] = {
+            "timeout_graceful_shutdown": 2,
+            "lifespan": "on",
+            "ws": "websockets-sansio",
+        }
+        config_kwargs.update(uvicorn_config_from_user)
+
+        if "log_config" not in config_kwargs and "log_level" not in config_kwargs:
+            config_kwargs["log_level"] = default_log_level_to_use
+
+        with temporary_log_level(log_level):
+            async with self._lifespan_manager():
+                config = uvicorn.Config(app, host=host, port=port, **config_kwargs)
+                server = uvicorn.Server(config)
+                path = getattr(app.state, "path", "").lstrip("/")
+                mode = " (stateless)" if stateless_http else ""
+                display_host = _format_host_for_url(host)
+                logger.info(
+                    f"Starting MCP server {self.name!r} with transport {transport!r}{mode} on http://{display_host}:{port}/{path}"
+                )
+
+                if sockets is not None:
+                    await server.serve(sockets=sockets)
+                else:
+                    await server.serve()
+
+    def http_app(
+        self: FastMCP,
+        path: str | None = None,
+        middleware: list[ASGIMiddleware] | None = None,
+        json_response: bool | None = None,
+        stateless_http: bool | None = None,
+        transport: Literal["http", "streamable-http", "sse"] = "http",
+        event_store: EventStore | None = None,
+        retry_interval: int | None = None,
+        host_origin_protection: HostOriginProtection | None = None,
+        allowed_hosts: list[str] | None = None,
+        allowed_origins: list[str] | None = None,
+        session_idle_timeout: float | None = None,
+    ) -> StarletteWithLifespan:
+        """Create a Starlette app using the specified HTTP transport.
+
+        Args:
+            path: The path for the HTTP endpoint
+            middleware: A list of middleware to apply to the app
+            json_response: Whether to use JSON response format
+            stateless_http: Whether to use stateless mode (new transport per request)
+            transport: Transport protocol to use - "http", "streamable-http", or "sse"
+            event_store: Optional event store for SSE polling/resumability. When set,
+                enables clients to reconnect and resume receiving events after
+                server-initiated disconnections. Only used with streamable-http transport.
+            retry_interval: Optional retry interval in milliseconds for SSE polling.
+                Controls how quickly clients should reconnect after server-initiated
+                disconnections. Requires event_store to be set. Only used with
+                streamable-http transport.
+            host_origin_protection: Whether to validate Host and Origin headers
+                before requests reach the MCP endpoint. Defaults to
+                settings.http_host_origin_protection. "auto" protects
+                localhost-bound servers and explicit host/origin allowlists.
+            allowed_hosts: Additional hostnames that may appear in the Host header.
+            allowed_origins: Additional browser origins trusted by the request guard.
+                Configure CORS separately when browser JavaScript must read
+                cross-origin responses.
+            session_idle_timeout: Maximum time in seconds a streamable-HTTP
+                session may remain idle before it is terminated. When None,
+                falls back to the ``http_session_idle_timeout`` setting.
+
+        Returns:
+            A Starlette application configured with the specified transport
+        """
+
+        if transport in ("streamable-http", "http"):
+            return create_streamable_http_app(
+                server=self,
+                streamable_http_path=path
+                if path is not None
+                else fastmcp.settings.streamable_http_path,
+                event_store=event_store,
+                retry_interval=retry_interval,
+                auth=self.auth,
+                json_response=(
+                    json_response
+                    if json_response is not None
+                    else fastmcp.settings.json_response
+                ),
+                stateless_http=(
+                    stateless_http
+                    if stateless_http is not None
+                    else fastmcp.settings.stateless_http
+                ),
+                debug=fastmcp.settings.debug,
+                middleware=middleware,
+                host_origin_protection=(
+                    host_origin_protection
+                    if host_origin_protection is not None
+                    else fastmcp.settings.http_host_origin_protection
+                ),
+                allowed_hosts=(
+                    allowed_hosts
+                    if allowed_hosts is not None
+                    else fastmcp.settings.http_allowed_hosts
+                ),
+                allowed_origins=(
+                    allowed_origins
+                    if allowed_origins is not None
+                    else fastmcp.settings.http_allowed_origins
+                ),
+                session_idle_timeout=(
+                    session_idle_timeout
+                    if session_idle_timeout is not None
+                    else fastmcp.settings.http_session_idle_timeout
+                ),
+            )
+        elif transport == "sse":
+            return create_sse_app(
+                server=self,
+                message_path=fastmcp.settings.message_path,
+                sse_path=path if path is not None else fastmcp.settings.sse_path,
+                auth=self.auth,
+                debug=fastmcp.settings.debug,
+                middleware=middleware,
+            )
+        else:
+            raise ValueError(f"Unknown transport: {transport}")
diff --git a/fastmcp_slim/fastmcp/server/providers/__init__.py b/fastmcp_slim/fastmcp/server/providers/__init__.py
new file mode 100644
index 0000000..fe0c248
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/__init__.py
@@ -0,0 +1,71 @@
+"""Providers for dynamic MCP components.
+
+This module provides the `Provider` abstraction for providing tools,
+resources, and prompts dynamically at runtime.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.providers import Provider
+    from fastmcp.tools import Tool
+
+    class DatabaseProvider(Provider):
+        def __init__(self, db_url: str):
+            self.db = Database(db_url)
+
+        async def _list_tools(self) -> list[Tool]:
+            rows = await self.db.fetch("SELECT * FROM tools")
+            return [self._make_tool(row) for row in rows]
+
+        async def _get_tool(self, name: str) -> Tool | None:
+            row = await self.db.fetchone("SELECT * FROM tools WHERE name = ?", name)
+            return self._make_tool(row) if row else None
+
+    mcp = FastMCP("Server", providers=[DatabaseProvider(db_url)])
+    ```
+"""
+
+from typing import TYPE_CHECKING
+
+from fastmcp.server.providers.aggregate import AggregateProvider
+from fastmcp.server.providers.base import Provider
+from fastmcp.server.providers.fastmcp_provider import FastMCPProvider
+from fastmcp.server.providers.filesystem import FileSystemProvider
+from fastmcp.server.providers.local_provider import LocalProvider
+from fastmcp.server.providers.skills import (
+    ClaudeSkillsProvider,
+    SkillProvider,
+    SkillsDirectoryProvider,
+    SkillsProvider,
+)
+
+if TYPE_CHECKING:
+    from fastmcp.server.providers.openapi import OpenAPIProvider as OpenAPIProvider
+    from fastmcp.server.providers.proxy import ProxyProvider as ProxyProvider
+
+__all__ = [
+    "AggregateProvider",
+    "ClaudeSkillsProvider",
+    "FastMCPProvider",
+    "FileSystemProvider",
+    "LocalProvider",
+    "OpenAPIProvider",
+    "Provider",
+    "ProxyProvider",
+    "SkillProvider",
+    "SkillsDirectoryProvider",
+    "SkillsProvider",  # Backwards compatibility alias for SkillsDirectoryProvider
+]
+
+
+def __getattr__(name: str) -> object:
+    """Lazy import for providers to avoid circular imports."""
+    if name == "ProxyProvider":
+        from fastmcp.server.providers.proxy import ProxyProvider
+
+        return ProxyProvider
+    if name == "OpenAPIProvider":
+        from fastmcp.server.providers.openapi import OpenAPIProvider
+
+        return OpenAPIProvider
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
diff --git a/fastmcp_slim/fastmcp/server/providers/addressing.py b/fastmcp_slim/fastmcp/server/providers/addressing.py
new file mode 100644
index 0000000..71a70a0
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/addressing.py
@@ -0,0 +1,69 @@
+"""Deterministic tool hashing for backend-tool routing and per-tool resources.
+
+Each FastMCPApp backend tool gets a deterministic hash computed from its
+app name + tool name. The hash serves two purposes:
+
+1. **Backend-tool routing.** Tools with ``"app"`` in their visibility are
+   callable via ``<hash>_<local_name>``. The dispatcher parses the prefix,
+   then walks providers recursively (same pattern as the old ``get_app_tool``)
+   to find a tool whose stored hash matches.
+
+2. **Per-tool Prefab renderer URIs.** Each prefab tool gets a unique renderer
+   resource at ``ui://prefab/tool/<hash>/renderer.html``. ``list_resources``
+   and ``read_resource`` synthesize these on demand from the tool's meta.
+
+The hash is computed at registration time from ``(app_name, tool_name)`` —
+both known at that moment — and stored in ``meta["fastmcp"]["_tool_hash"]``.
+Deterministic across replicas (same code → same hash), no registry walk
+needed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+#: Length of the hex hash prefix used in URIs and backend-tool names.
+HASH_LENGTH = 12
+
+
+def hash_tool(app_name: str, tool_name: str) -> str:
+    """Deterministic hex hash for a tool in an app.
+
+    Same inputs on every replica produce the same output.
+    """
+    payload = f"{app_name}\x00{tool_name}".encode()
+    return hashlib.sha256(payload).hexdigest()[:HASH_LENGTH]
+
+
+def hashed_backend_name(app_name: str, tool_name: str) -> str:
+    """Format the universal name for a backend tool: ``<hash>_<local_name>``."""
+    return f"{hash_tool(app_name, tool_name)}_{tool_name}"
+
+
+def parse_hashed_backend_name(name: str) -> tuple[str, str] | None:
+    """Parse ``<HASH_LENGTH hex>_<rest>`` → ``(hash, local_tool_name)`` or None."""
+    if len(name) <= HASH_LENGTH + 1:
+        return None
+    prefix = name[:HASH_LENGTH]
+    if name[HASH_LENGTH] != "_":
+        return None
+    if not all(c in "0123456789abcdef" for c in prefix):
+        return None
+    return prefix, name[HASH_LENGTH + 1 :]
+
+
+def hashed_resource_uri(app_name: str, tool_name: str) -> str:
+    """Per-tool Prefab renderer resource URI."""
+    return f"ui://prefab/tool/{hash_tool(app_name, tool_name)}/renderer.html"
+
+
+def parse_hashed_resource_uri(uri: str) -> str | None:
+    """Extract the hash from a Prefab renderer URI, or None."""
+    prefix = "ui://prefab/tool/"
+    suffix = "/renderer.html"
+    if not uri.startswith(prefix) or not uri.endswith(suffix):
+        return None
+    h = uri[len(prefix) : -len(suffix)]
+    if len(h) != HASH_LENGTH or not all(c in "0123456789abcdef" for c in h):
+        return None
+    return h
diff --git a/fastmcp_slim/fastmcp/server/providers/aggregate.py b/fastmcp_slim/fastmcp/server/providers/aggregate.py
new file mode 100644
index 0000000..766d648
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/aggregate.py
@@ -0,0 +1,328 @@
+"""AggregateProvider for combining multiple providers into one.
+
+This module provides `AggregateProvider`, a utility class that presents
+multiple providers as a single unified provider. Useful when you want to
+combine custom providers without creating a full FastMCP server.
+
+Example:
+    ```python
+    from fastmcp.server.providers import AggregateProvider
+
+    # Combine multiple providers into one
+    combined = AggregateProvider()
+    combined.add_provider(provider1)
+    combined.add_provider(provider2, namespace="api")  # Tools become "api_foo"
+
+    # Use like any other provider
+    tools = await combined.list_tools()
+    ```
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator, Sequence
+from contextlib import AsyncExitStack, asynccontextmanager
+from typing import TYPE_CHECKING, Literal, TypeVar
+
+from fastmcp.exceptions import NotFoundError
+from fastmcp.server.providers.base import Provider
+from fastmcp.server.transforms import Namespace
+from fastmcp.utilities.async_utils import gather
+from fastmcp.utilities.components import FastMCPComponent
+from fastmcp.utilities.versions import VersionSpec, version_sort_key
+
+if TYPE_CHECKING:
+    from fastmcp.prompts.base import Prompt
+    from fastmcp.resources.base import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.tools.base import Tool
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+ProviderErrorStrategy = Literal["warn", "raise"]
+
+
+class AggregateProvider(Provider):
+    """Utility provider that combines multiple providers into one.
+
+    Components are aggregated from all providers. For get_* operations,
+    providers are queried in parallel and the highest version is returned.
+
+    When adding providers with a namespace, wrap_transform() is used to apply
+    the Namespace transform. This means namespace transformation is handled
+    by the wrapped provider, not by AggregateProvider.
+
+    Errors from individual providers are logged and skipped by default. Set
+    ``provider_error_strategy="raise"`` to fail the aggregate operation when
+    any provider fails.
+
+    Example:
+        ```python
+        combined = AggregateProvider()
+        combined.add_provider(db_provider)
+        combined.add_provider(api_provider, namespace="api")
+        # db_provider's tools keep original names
+        # api_provider's tools become "api_foo", "api_bar", etc.
+        ```
+    """
+
+    def __init__(
+        self,
+        providers: Sequence[Provider] | None = None,
+        *,
+        provider_error_strategy: ProviderErrorStrategy = "warn",
+    ) -> None:
+        """Initialize with an optional sequence of providers.
+
+        Args:
+            providers: Optional initial providers (without namespacing).
+                For namespaced providers, use add_provider() instead.
+            provider_error_strategy: How provider errors should affect aggregate
+                operations. ``"warn"`` logs and skips failed providers.
+                ``"raise"`` propagates the first provider error.
+        """
+        super().__init__()
+        self.provider_error_strategy = provider_error_strategy
+        self.providers: list[Provider] = list(providers or [])
+
+    def add_provider(self, provider: Provider, *, namespace: str = "") -> None:
+        """Add a provider with optional namespace.
+
+        If the provider is a FastMCP server, it's automatically wrapped in
+        FastMCPProvider to ensure middleware is invoked correctly.
+
+        Args:
+            provider: The provider to add.
+            namespace: Optional namespace prefix. When set:
+                - Tools become "namespace_toolname"
+                - Resources become "protocol://namespace/path"
+                - Prompts become "namespace_promptname"
+        """
+        # Import here to avoid circular imports
+        from fastmcp.server.server import FastMCP
+
+        # Auto-wrap FastMCP servers to ensure middleware is invoked
+        if isinstance(provider, FastMCP):
+            from fastmcp.server.providers.fastmcp_provider import FastMCPProvider
+
+            provider = FastMCPProvider(provider)
+
+        # Apply namespace via wrap_transform if specified
+        if namespace:
+            provider = provider.wrap_transform(Namespace(namespace))
+
+        self.providers.append(provider)
+
+    def _collect_list_results(
+        self, results: list[Sequence[T] | BaseException], operation: str
+    ) -> list[T]:
+        """Collect successful list results, logging any exceptions.
+
+        Emits a warning when the same MCP identity is returned by more than
+        one provider — surfaces composition mistakes to the server author.
+        This is always a warning: cross-provider collisions happen at runtime
+        (sometimes dynamically), so an errorable/strict mode would give the
+        author no way to react and would crash list calls in production.
+        """
+        collected: list[T] = []
+        # FastMCPComponent.key encodes type, identifier, and version —
+        # so version variants of the same component are NOT reported as
+        # collisions (matching _get_highest_version_result behavior).
+        seen_keys: dict[str, int] = {}
+        for i, result in enumerate(results):
+            if isinstance(result, BaseException):
+                if self.provider_error_strategy == "raise":
+                    raise result
+                logger.warning(
+                    f"Error during {operation} from provider "
+                    f"{self.providers[i]}: {result}"
+                )
+                continue
+            for item in result:
+                key = getattr(item, "key", None)
+                if key is not None:
+                    first = seen_keys.setdefault(key, i)
+                    if first != i:
+                        logger.warning(
+                            f"Duplicate {operation} component {key!r} "
+                            f"from provider {self.providers[i]} "
+                            f"(first seen from provider {self.providers[first]})"
+                        )
+                collected.append(item)
+        return collected
+
+    def _get_highest_version_result(
+        self,
+        results: list[FastMCPComponent | None | BaseException],
+        operation: str,
+    ) -> FastMCPComponent | None:
+        """Get the highest version from successful non-None results.
+
+        Used for versioned components where we want the highest version
+        across all providers rather than the first match.
+        """
+        valid: list[FastMCPComponent] = []
+        for i, result in enumerate(results):
+            if isinstance(result, BaseException):
+                if not isinstance(result, NotFoundError):
+                    if self.provider_error_strategy == "raise":
+                        raise result
+                    logger.warning(
+                        f"Error during {operation} from provider "
+                        f"{self.providers[i]}: {result}"
+                    )
+                continue
+            if result is not None:
+                valid.append(result)
+        if not valid:
+            return None
+        return max(valid, key=version_sort_key)
+
+    def __repr__(self) -> str:
+        return f"AggregateProvider(providers={self.providers!r})"
+
+    # -------------------------------------------------------------------------
+    # Tools
+    # -------------------------------------------------------------------------
+
+    async def _list_tools(self) -> Sequence[Tool]:
+        """List all tools from all providers."""
+        results = await gather(
+            *[p.list_tools() for p in self.providers],
+            return_exceptions=True,
+        )
+        return self._collect_list_results(results, "list_tools")
+
+    async def _get_tool(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get tool by name from providers."""
+        results = await gather(
+            *[p.get_tool(name, version) for p in self.providers],
+            return_exceptions=True,
+        )
+        return self._get_highest_version_result(results, f"get_tool({name!r})")  # type: ignore[return-value]  # ty:ignore[invalid-argument-type, invalid-return-type]
+
+    async def get_app_tool(self, app_name: str, tool_name: str) -> Tool | None:
+        """Query all child providers for an app tool."""
+        results = await gather(
+            *[p.get_app_tool(app_name, tool_name) for p in self.providers],
+            return_exceptions=True,
+        )
+        for r in results:
+            if isinstance(r, BaseException):
+                if self.provider_error_strategy == "raise":
+                    raise r
+                continue
+            if r is not None:
+                return r
+        return None
+
+    async def get_tool_by_hash(self, tool_hash: str, tool_name: str) -> Tool | None:
+        """Query all child providers for a tool matching a hash."""
+        results = await gather(
+            *[p.get_tool_by_hash(tool_hash, tool_name) for p in self.providers],
+            return_exceptions=True,
+        )
+        for r in results:
+            if isinstance(r, BaseException):
+                if self.provider_error_strategy == "raise":
+                    raise r
+                continue
+            if r is not None:
+                return r
+        return None
+
+    # -------------------------------------------------------------------------
+    # Resources
+    # -------------------------------------------------------------------------
+
+    async def _list_resources(self) -> Sequence[Resource]:
+        """List all resources from all providers."""
+        results = await gather(
+            *[p.list_resources() for p in self.providers],
+            return_exceptions=True,
+        )
+        return self._collect_list_results(results, "list_resources")
+
+    async def _get_resource(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> Resource | None:
+        """Get resource by URI from providers."""
+        results = await gather(
+            *[p.get_resource(uri, version) for p in self.providers],
+            return_exceptions=True,
+        )
+        return self._get_highest_version_result(results, f"get_resource({uri!r})")  # type: ignore[return-value]  # ty:ignore[invalid-argument-type, invalid-return-type]
+
+    # -------------------------------------------------------------------------
+    # Resource Templates
+    # -------------------------------------------------------------------------
+
+    async def _list_resource_templates(self) -> Sequence[ResourceTemplate]:
+        """List all resource templates from all providers."""
+        results = await gather(
+            *[p.list_resource_templates() for p in self.providers],
+            return_exceptions=True,
+        )
+        return self._collect_list_results(results, "list_resource_templates")
+
+    async def _get_resource_template(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> ResourceTemplate | None:
+        """Get resource template by URI from providers."""
+        results = await gather(
+            *[p.get_resource_template(uri, version) for p in self.providers],
+            return_exceptions=True,
+        )
+        return self._get_highest_version_result(
+            list(results), f"get_resource_template({uri!r})"
+        )  # type: ignore[return-value]  # ty:ignore[invalid-return-type]
+
+    # -------------------------------------------------------------------------
+    # Prompts
+    # -------------------------------------------------------------------------
+
+    async def _list_prompts(self) -> Sequence[Prompt]:
+        """List all prompts from all providers."""
+        results = await gather(
+            *[p.list_prompts() for p in self.providers],
+            return_exceptions=True,
+        )
+        return self._collect_list_results(results, "list_prompts")
+
+    async def _get_prompt(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        """Get prompt by name from providers."""
+        results = await gather(
+            *[p.get_prompt(name, version) for p in self.providers],
+            return_exceptions=True,
+        )
+        return self._get_highest_version_result(results, f"get_prompt({name!r})")  # type: ignore[return-value]  # ty:ignore[invalid-argument-type, invalid-return-type]
+
+    # -------------------------------------------------------------------------
+    # Tasks
+    # -------------------------------------------------------------------------
+
+    async def get_tasks(self) -> Sequence[FastMCPComponent]:
+        """Get all task-eligible components from all providers."""
+        results = await gather(
+            *[p.get_tasks() for p in self.providers],
+            return_exceptions=True,
+        )
+        return self._collect_list_results(results, "get_tasks")
+
+    # -------------------------------------------------------------------------
+    # Lifecycle
+    # -------------------------------------------------------------------------
+
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncIterator[None]:
+        """Combine lifespans of all providers."""
+        async with AsyncExitStack() as stack:
+            for p in self.providers:
+                await stack.enter_async_context(p.lifespan())
+            yield
diff --git a/fastmcp_slim/fastmcp/server/providers/base.py b/fastmcp_slim/fastmcp/server/providers/base.py
new file mode 100644
index 0000000..402dff3
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/base.py
@@ -0,0 +1,650 @@
+"""Base Provider class for dynamic MCP components.
+
+This module provides the `Provider` abstraction for providing tools,
+resources, and prompts dynamically at runtime.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.providers import Provider
+    from fastmcp.tools import Tool
+
+    class DatabaseProvider(Provider):
+        def __init__(self, db_url: str):
+            super().__init__()
+            self.db = Database(db_url)
+
+        async def _list_tools(self) -> list[Tool]:
+            rows = await self.db.fetch("SELECT * FROM tools")
+            return [self._make_tool(row) for row in rows]
+
+        async def _get_tool(self, name: str) -> Tool | None:
+            row = await self.db.fetchone("SELECT * FROM tools WHERE name = ?", name)
+            return self._make_tool(row) if row else None
+
+    mcp = FastMCP("Server", providers=[DatabaseProvider(db_url)])
+    ```
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Sequence
+from contextlib import asynccontextmanager
+from functools import partial
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from typing_extensions import Self
+
+from fastmcp.server.transforms.visibility import Visibility
+from fastmcp.utilities.async_utils import gather
+from fastmcp.utilities.components import FastMCPComponent
+from fastmcp.utilities.versions import VersionSpec, version_sort_key
+
+if TYPE_CHECKING:
+    from fastmcp.prompts.base import Prompt
+    from fastmcp.resources.base import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.server.transforms import (
+        GetPromptNext,
+        GetResourceNext,
+        GetResourceTemplateNext,
+        GetToolNext,
+        Transform,
+    )
+    from fastmcp.tools.base import Tool
+
+
+class Provider:
+    """Base class for dynamic component providers.
+
+    Subclass and override whichever methods you need. Default implementations
+    return empty lists / None, so you only need to implement what your provider
+    supports.
+
+    Provider semantics:
+        - Return `None` from `get_*` methods to indicate "I don't have it" (search continues)
+        - Static components (registered via decorators) always take precedence over providers
+        - Providers are queried in registration order; first non-None wins
+        - Components execute themselves via run()/read()/render() - providers just source them
+
+    Error handling:
+        - `list_*` methods: Errors are logged and the provider returns empty (graceful degradation).
+          This allows other providers to still contribute their components.
+    """
+
+    def __init__(self) -> None:
+        self._transforms: list[Transform] = []
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}()"
+
+    @property
+    def transforms(self) -> list[Transform]:
+        """All transforms applied to components from this provider."""
+        return list(self._transforms)
+
+    def add_transform(self, transform: Transform) -> None:
+        """Add a transform to this provider.
+
+        Transforms modify components (tools, resources, prompts) as they flow
+        through the provider. They're applied in order - first added is innermost.
+
+        Args:
+            transform: The transform to add.
+
+        Example:
+            ```python
+            from fastmcp.server.transforms import Namespace
+
+            provider = MyProvider()
+            provider.add_transform(Namespace("api"))
+            # Tools become "api_toolname"
+            ```
+        """
+        self._transforms.append(transform)
+
+    def wrap_transform(self, transform: Transform) -> Provider:
+        """Return a new provider with this transform applied (immutable).
+
+        Unlike add_transform() which mutates this provider, wrap_transform()
+        returns a new provider that wraps this one. The original provider
+        is unchanged.
+
+        This is useful when you want to apply transforms without side effects,
+        such as adding the same provider to multiple aggregators with different
+        namespaces.
+
+        Args:
+            transform: The transform to apply.
+
+        Returns:
+            A new provider that wraps this one with the transform applied.
+
+        Example:
+            ```python
+            from fastmcp.server.transforms import Namespace
+
+            provider = MyProvider()
+            namespaced = provider.wrap_transform(Namespace("api"))
+            # provider is unchanged
+            # namespaced returns tools as "api_toolname"
+            ```
+        """
+        # Import here to avoid circular imports
+        from fastmcp.server.providers.wrapped_provider import _WrappedProvider
+
+        return _WrappedProvider(self, transform)
+
+    # -------------------------------------------------------------------------
+    # Internal transform chain building
+    # -------------------------------------------------------------------------
+
+    async def list_tools(self) -> Sequence[Tool]:
+        """List tools with all transforms applied.
+
+        Applies transforms sequentially: base → transforms (in order).
+        Each transform receives the result from the previous transform.
+        Components may be marked as disabled but are NOT filtered here -
+        filtering happens at the server level to allow session transforms to override.
+
+        Returns:
+            Transformed sequence of tools (including disabled ones).
+        """
+        tools = await self._list_tools()
+        for transform in self.transforms:
+            tools = await transform.list_tools(tools)
+        return tools
+
+    async def get_tool(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get tool by transformed name with all transforms applied.
+
+        Note: This method does NOT filter disabled components. The Server
+        (FastMCP) performs enabled filtering after all transforms complete,
+        allowing session-level transforms to override provider-level disables.
+
+        Args:
+            name: The transformed tool name to look up.
+            version: Optional version filter. If None, returns highest version.
+
+        Returns:
+            The tool if found (may be marked disabled), None if not found.
+        """
+
+        async def base(n: str, *, version: VersionSpec | None = None) -> Tool | None:
+            return await self._get_tool(n, version)
+
+        chain: GetToolNext = cast("GetToolNext", base)
+        for transform in self.transforms:
+            chain = cast(
+                "GetToolNext",
+                partial(cast(Any, transform.get_tool), call_next=chain),
+            )
+
+        return await chain(name, version=version)
+
+    async def get_app_tool(self, app_name: str, tool_name: str) -> Tool | None:
+        """Look up an app-visible tool by original name, bypassing transforms.
+
+        Searches for a tool named ``tool_name`` tagged with the given app
+        name.  Skips the transform chain entirely.
+
+        Returns:
+            The tool if found and tagged with the given app name, else None.
+        """
+        tool = await self._get_tool(tool_name)
+        if tool is not None:
+            meta = tool.meta or {}
+            fastmcp_meta = meta.get("fastmcp")
+            ui_meta = meta.get("ui")
+            # Must match app name AND have app visibility (not model-only)
+            visibility = (
+                ui_meta.get("visibility", []) if isinstance(ui_meta, dict) else []
+            )
+            if (
+                isinstance(fastmcp_meta, dict)
+                and fastmcp_meta.get("app") == app_name
+                and "app" in visibility
+            ):
+                return tool
+        return None
+
+    async def get_tool_by_hash(self, tool_hash: str, tool_name: str) -> Tool | None:
+        """Look up an app-visible tool by its deterministic hash.
+
+        Same recursive-walk semantics as ``get_app_tool`` but matches on
+        ``meta["fastmcp"]["_tool_hash"]`` instead of the app name tag.
+        Used by the dispatcher when receiving hashed backend-tool calls.
+        """
+        tool = await self._get_tool(tool_name)
+        if tool is not None:
+            meta = tool.meta or {}
+            fastmcp_meta = meta.get("fastmcp")
+            ui_meta = meta.get("ui")
+            visibility = (
+                ui_meta.get("visibility", []) if isinstance(ui_meta, dict) else []
+            )
+            if (
+                isinstance(fastmcp_meta, dict)
+                and fastmcp_meta.get("_tool_hash") == tool_hash
+                and "app" in visibility
+            ):
+                return tool
+        return None
+
+    async def list_resources(self) -> Sequence[Resource]:
+        """List resources with all transforms applied.
+
+        Components may be marked as disabled but are NOT filtered here.
+        """
+        resources = await self._list_resources()
+        for transform in self.transforms:
+            resources = await transform.list_resources(resources)
+        return resources
+
+    async def get_resource(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> Resource | None:
+        """Get resource by transformed URI with all transforms applied.
+
+        Note: This method does NOT filter disabled components. The Server
+        (FastMCP) performs enabled filtering after all transforms complete.
+
+        Args:
+            uri: The transformed resource URI to look up.
+            version: Optional version filter. If None, returns highest version.
+
+        Returns:
+            The resource if found (may be marked disabled), None if not found.
+        """
+
+        async def base(
+            u: str, *, version: VersionSpec | None = None
+        ) -> Resource | None:
+            return await self._get_resource(u, version)
+
+        chain: GetResourceNext = cast("GetResourceNext", base)
+        for transform in self.transforms:
+            chain = cast(
+                "GetResourceNext",
+                partial(cast(Any, transform.get_resource), call_next=chain),
+            )
+
+        return await chain(uri, version=version)
+
+    async def list_resource_templates(self) -> Sequence[ResourceTemplate]:
+        """List resource templates with all transforms applied.
+
+        Components may be marked as disabled but are NOT filtered here.
+        """
+        templates = await self._list_resource_templates()
+        for transform in self.transforms:
+            templates = await transform.list_resource_templates(templates)
+        return templates
+
+    async def get_resource_template(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> ResourceTemplate | None:
+        """Get resource template by transformed URI with all transforms applied.
+
+        Note: This method does NOT filter disabled components. The Server
+        (FastMCP) performs enabled filtering after all transforms complete.
+
+        Args:
+            uri: The transformed template URI to look up.
+            version: Optional version filter. If None, returns highest version.
+
+        Returns:
+            The template if found (may be marked disabled), None if not found.
+        """
+
+        async def base(
+            u: str, *, version: VersionSpec | None = None
+        ) -> ResourceTemplate | None:
+            return await self._get_resource_template(u, version)
+
+        chain: GetResourceTemplateNext = cast("GetResourceTemplateNext", base)
+        for transform in self.transforms:
+            chain = cast(
+                "GetResourceTemplateNext",
+                partial(
+                    cast(Any, transform.get_resource_template),
+                    call_next=chain,
+                ),
+            )
+
+        return await chain(uri, version=version)
+
+    async def list_prompts(self) -> Sequence[Prompt]:
+        """List prompts with all transforms applied.
+
+        Components may be marked as disabled but are NOT filtered here.
+        """
+        prompts = await self._list_prompts()
+        for transform in self.transforms:
+            prompts = await transform.list_prompts(prompts)
+        return prompts
+
+    async def get_prompt(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        """Get prompt by transformed name with all transforms applied.
+
+        Note: This method does NOT filter disabled components. The Server
+        (FastMCP) performs enabled filtering after all transforms complete.
+
+        Args:
+            name: The transformed prompt name to look up.
+            version: Optional version filter. If None, returns highest version.
+
+        Returns:
+            The prompt if found (may be marked disabled), None if not found.
+        """
+
+        async def base(n: str, *, version: VersionSpec | None = None) -> Prompt | None:
+            return await self._get_prompt(n, version)
+
+        chain: GetPromptNext = cast("GetPromptNext", base)
+        for transform in self.transforms:
+            chain = cast(
+                "GetPromptNext",
+                partial(cast(Any, transform.get_prompt), call_next=chain),
+            )
+
+        return await chain(name, version=version)
+
+    # -------------------------------------------------------------------------
+    # Private list/get methods (override these to provide components)
+    # -------------------------------------------------------------------------
+
+    async def _list_tools(self) -> Sequence[Tool]:
+        """Return all available tools.
+
+        Override to provide tools dynamically. Returns ALL versions of all tools.
+        The server handles deduplication to show one tool per name.
+        """
+        return []
+
+    async def _get_tool(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get a specific tool by name.
+
+        Default implementation filters _list_tools() and picks the highest version
+        that matches the spec.
+
+        Args:
+            name: The tool name.
+            version: Optional version filter. If None, returns highest version.
+                     If specified, returns highest version matching the spec.
+
+        Returns:
+            The Tool if found, or None to continue searching other providers.
+        """
+        tools = await self._list_tools()
+        matching = [t for t in tools if t.name == name]
+        if version:
+            matching = [t for t in matching if version.matches(t.version)]
+        if not matching:
+            return None
+        return max(matching, key=version_sort_key)
+
+    async def _list_resources(self) -> Sequence[Resource]:
+        """Return all available resources.
+
+        Override to provide resources dynamically. Returns ALL versions of all resources.
+        The server handles deduplication to show one resource per URI.
+        """
+        return []
+
+    async def _get_resource(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> Resource | None:
+        """Get a specific resource by URI.
+
+        Default implementation filters _list_resources() and returns highest
+        version matching the spec.
+
+        Args:
+            uri: The resource URI.
+            version: Optional version filter. If None, returns highest version.
+
+        Returns:
+            The Resource if found, or None to continue searching other providers.
+        """
+        resources = await self._list_resources()
+        matching = [r for r in resources if str(r.uri) == uri]
+        if version:
+            matching = [r for r in matching if version.matches(r.version)]
+        if not matching:
+            return None
+        return max(matching, key=version_sort_key)
+
+    async def _list_resource_templates(self) -> Sequence[ResourceTemplate]:
+        """Return all available resource templates.
+
+        Override to provide resource templates dynamically. Returns ALL versions.
+        The server handles deduplication.
+        """
+        return []
+
+    async def _get_resource_template(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> ResourceTemplate | None:
+        """Get a resource template that matches the given URI.
+
+        Default implementation lists all templates, finds those whose pattern
+        matches the URI, and returns the highest version matching the spec.
+
+        Args:
+            uri: The URI to match against templates.
+            version: Optional version filter. If None, returns highest version.
+
+        Returns:
+            The ResourceTemplate if a matching one is found, or None to continue searching.
+        """
+        templates = await self._list_resource_templates()
+        matching = [t for t in templates if t.matches(uri) is not None]
+        if version:
+            matching = [t for t in matching if version.matches(t.version)]
+        if not matching:
+            return None
+        return max(matching, key=version_sort_key)
+
+    async def _list_prompts(self) -> Sequence[Prompt]:
+        """Return all available prompts.
+
+        Override to provide prompts dynamically. Returns ALL versions of all prompts.
+        The server handles deduplication to show one prompt per name.
+        """
+        return []
+
+    async def _get_prompt(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        """Get a specific prompt by name.
+
+        Default implementation filters _list_prompts() and picks the highest version
+        matching the spec.
+
+        Args:
+            name: The prompt name.
+            version: Optional version filter. If None, returns highest version.
+
+        Returns:
+            The Prompt if found, or None to continue searching other providers.
+        """
+        prompts = await self._list_prompts()
+        matching = [p for p in prompts if p.name == name]
+        if version:
+            matching = [p for p in matching if version.matches(p.version)]
+        if not matching:
+            return None
+        return max(matching, key=version_sort_key)
+
+    # -------------------------------------------------------------------------
+    # Task registration
+    # -------------------------------------------------------------------------
+
+    async def get_tasks(self) -> Sequence[FastMCPComponent]:
+        """Return components that should be registered as background tasks.
+
+        Override to customize which components are task-eligible.
+        Default calls list_* methods, applies provider transforms, and filters
+        for components with task_config.mode != 'forbidden'.
+
+        Used by the server during startup to register functions with Docket.
+        """
+        # Fetch all component types in parallel
+        results = await gather(
+            self._list_tools(),
+            self._list_resources(),
+            self._list_resource_templates(),
+            self._list_prompts(),
+        )
+        tools = cast("Sequence[Tool]", results[0])
+        resources = cast("Sequence[Resource]", results[1])
+        templates = cast("Sequence[ResourceTemplate]", results[2])
+        prompts = cast("Sequence[Prompt]", results[3])
+
+        # Apply provider's own transforms sequentially
+        # For tasks, we need the fully-transformed names
+        for transform in self.transforms:
+            tools = await transform.list_tools(tools)
+            resources = await transform.list_resources(resources)
+            templates = await transform.list_resource_templates(templates)
+            prompts = await transform.list_prompts(prompts)
+
+        return [
+            c
+            for c in [
+                *tools,
+                *resources,
+                *templates,
+                *prompts,
+            ]
+            if c.task_config.supports_tasks()
+        ]
+
+    # -------------------------------------------------------------------------
+    # Lifecycle methods
+    # -------------------------------------------------------------------------
+
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncIterator[None]:
+        """User-overridable lifespan for custom setup and teardown.
+
+        Override this method to perform provider-specific initialization
+        like opening database connections, setting up external resources,
+        or other state management needed for the provider's lifetime.
+
+        The lifespan scope matches the server's lifespan - code before yield
+        runs at startup, code after yield runs at shutdown.
+
+        Example:
+            ```python
+            @asynccontextmanager
+            async def lifespan(self):
+                # Setup
+                self.db = await connect_database()
+                try:
+                    yield
+                finally:
+                    # Teardown
+                    await self.db.close()
+            ```
+        """
+        yield
+
+    # -------------------------------------------------------------------------
+    # Enable/Disable
+    # -------------------------------------------------------------------------
+
+    def enable(
+        self,
+        *,
+        names: set[str] | None = None,
+        keys: set[str] | None = None,
+        version: VersionSpec | None = None,
+        tags: set[str] | None = None,
+        components: set[Literal["tool", "resource", "template", "prompt"]]
+        | None = None,
+        only: bool = False,
+    ) -> Self:
+        """Enable components matching all specified criteria.
+
+        Adds a visibility transform that marks matching components as enabled.
+        Later transforms override earlier ones, so enable after disable makes
+        the component enabled.
+
+        With only=True, switches to allowlist mode - first disables everything,
+        then enables matching components.
+
+        Args:
+            names: Component names or URIs to enable.
+            keys: Component keys to enable (e.g., {"tool:my_tool@v1"}).
+            version: Component version spec to enable (e.g., VersionSpec(eq="v1") or
+                VersionSpec(gte="v2")). Unversioned components will not match.
+            tags: Enable components with these tags.
+            components: Component types to include (e.g., {"tool", "prompt"}).
+            only: If True, ONLY enable matching components (allowlist mode).
+
+        Returns:
+            Self for method chaining.
+        """
+        if only:
+            # Allowlist: disable everything, then enable matching
+            # The enable transform runs later on return path, so it overrides
+            self._transforms.append(Visibility(False, match_all=True))
+        self._transforms.append(
+            Visibility(
+                True,
+                names=names,
+                keys=keys,
+                version=version,
+                components=set(components) if components else None,
+                tags=set(tags) if tags else None,
+            )
+        )
+
+        return self
+
+    def disable(
+        self,
+        *,
+        names: set[str] | None = None,
+        keys: set[str] | None = None,
+        version: VersionSpec | None = None,
+        tags: set[str] | None = None,
+        components: set[Literal["tool", "resource", "template", "prompt"]]
+        | None = None,
+    ) -> Self:
+        """Disable components matching all specified criteria.
+
+        Adds a visibility transform that marks matching components as disabled.
+        Components can be re-enabled by calling enable() with matching criteria
+        (the later transform wins).
+
+        Args:
+            names: Component names or URIs to disable.
+            keys: Component keys to disable (e.g., {"tool:my_tool@v1"}).
+            version: Component version spec to disable (e.g., VersionSpec(eq="v1") or
+                VersionSpec(gte="v2")). Unversioned components will not match.
+            tags: Disable components with these tags.
+            components: Component types to include (e.g., {"tool", "prompt"}).
+
+        Returns:
+            Self for method chaining.
+        """
+        self._transforms.append(
+            Visibility(
+                False,
+                names=names,
+                keys=keys,
+                version=version,
+                components=set(components) if components else None,
+                tags=set(tags) if tags else None,
+            )
+        )
+        return self
diff --git a/fastmcp_slim/fastmcp/server/providers/fastmcp_provider.py b/fastmcp_slim/fastmcp/server/providers/fastmcp_provider.py
new file mode 100644
index 0000000..14dbbba
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/fastmcp_provider.py
@@ -0,0 +1,736 @@
+"""FastMCPProvider for wrapping FastMCP servers as providers.
+
+This module provides the `FastMCPProvider` class that wraps a FastMCP server
+and exposes its components through the Provider interface.
+
+It also provides FastMCPProvider* component classes that delegate execution to
+the wrapped server's middleware, ensuring middleware runs when components are
+executed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Sequence
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any, overload
+
+import mcp_types
+from pydantic import AnyUrl
+
+from fastmcp.prompts.base import Prompt, PromptResult
+from fastmcp.resources.base import Resource, ResourceResult
+from fastmcp.resources.template import ResourceTemplate, expand_uri_template
+from fastmcp.server.providers.base import Provider
+from fastmcp.server.tasks.config import TaskMeta
+from fastmcp.server.telemetry import delegate_span
+from fastmcp.tools.base import Tool, ToolResult
+from fastmcp.utilities.components import FastMCPComponent
+from fastmcp.utilities.versions import VersionSpec
+
+if TYPE_CHECKING:
+    from docket import Docket
+    from docket.execution import Execution
+
+    from fastmcp.server.server import FastMCP
+
+
+# -----------------------------------------------------------------------------
+# FastMCPProvider component classes
+# -----------------------------------------------------------------------------
+
+
+class FastMCPProviderTool(Tool):
+    """Tool that delegates execution to a wrapped server's middleware.
+
+    When `run()` is called, this tool invokes the wrapped server's
+    `_call_tool_middleware()` method, ensuring the server's middleware
+    chain is executed.
+    """
+
+    _server: Any = None  # FastMCP, but Any to avoid circular import
+    _original_name: str | None = None
+
+    def __init__(
+        self,
+        server: Any,
+        original_name: str,
+        **kwargs: Any,
+    ):
+        super().__init__(**kwargs)
+        self._server = server
+        self._original_name = original_name
+
+    @classmethod
+    def wrap(cls, server: Any, tool: Tool) -> FastMCPProviderTool:
+        """Wrap a Tool to delegate execution to the server's middleware."""
+        return cls(
+            server=server,
+            original_name=tool.name,
+            name=tool.name,
+            version=tool.version,
+            description=tool.description,
+            parameters=tool.parameters,
+            output_schema=tool.output_schema,
+            tags=tool.tags,
+            annotations=tool.annotations,
+            task_config=tool.task_config,
+            execution=tool.execution,
+            meta=tool.get_meta(),
+            title=tool.title,
+            icons=tool.icons,
+        )
+
+    @overload
+    async def _run(
+        self,
+        arguments: dict[str, Any],
+        task_meta: None = None,
+    ) -> ToolResult: ...
+
+    @overload
+    async def _run(
+        self,
+        arguments: dict[str, Any],
+        task_meta: TaskMeta,
+    ) -> mcp_types.CreateTaskResult: ...
+
+    async def _run(
+        self,
+        arguments: dict[str, Any],
+        task_meta: TaskMeta | None = None,
+    ) -> ToolResult | mcp_types.CreateTaskResult:
+        """Delegate to child server's call_tool() with task_meta.
+
+        Passes task_meta through to the child server so it can handle
+        backgrounding appropriately. fn_key is already set by the parent
+        server before calling this method.
+        """
+        # Pass exact version so child executes the correct version
+        version = VersionSpec(eq=self.version) if self.version else None
+
+        with delegate_span(
+            self._original_name or "",
+            "FastMCPProvider",
+            self._original_name or "",
+            method="tools/call",
+        ):
+            return await self._server.call_tool(
+                self._original_name,
+                arguments,
+                version=version,
+                task_meta=task_meta,
+            )
+
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
+        """Delegate to child server's call_tool() without task_meta.
+
+        This is called when the tool is used within a TransformedTool
+        forwarding function or other contexts where task_meta is not available.
+        """
+        # Pass exact version so child executes the correct version
+        version = VersionSpec(eq=self.version) if self.version else None
+
+        result = await self._server.call_tool(
+            self._original_name, arguments, version=version
+        )
+        # Result from call_tool should always be ToolResult when no task_meta
+        if isinstance(result, mcp_types.CreateTaskResult):
+            raise RuntimeError(
+                "Unexpected CreateTaskResult from call_tool without task_meta"
+            )
+        return result
+
+    def get_span_attributes(self) -> dict[str, Any]:
+        return super().get_span_attributes() | {
+            "fastmcp.provider.type": "FastMCPProvider",
+            "fastmcp.delegate.original_name": self._original_name,
+        }
+
+
+class FastMCPProviderResource(Resource):
+    """Resource that delegates reading to a wrapped server's read_resource().
+
+    When `read()` is called, this resource invokes the wrapped server's
+    `read_resource()` method, ensuring the server's middleware chain is executed.
+    """
+
+    _server: Any = None  # FastMCP, but Any to avoid circular import
+    _original_uri: str | None = None
+
+    def __init__(
+        self,
+        server: Any,
+        original_uri: str,
+        **kwargs: Any,
+    ):
+        super().__init__(**kwargs)
+        self._server = server
+        self._original_uri = original_uri
+
+    @classmethod
+    def wrap(cls, server: Any, resource: Resource) -> FastMCPProviderResource:
+        """Wrap a Resource to delegate reading to the server's middleware."""
+        return cls(
+            server=server,
+            original_uri=str(resource.uri),
+            uri=resource.uri,
+            version=resource.version,
+            name=resource.name,
+            description=resource.description,
+            mime_type=resource.mime_type,
+            tags=resource.tags,
+            annotations=resource.annotations,
+            task_config=resource.task_config,
+            meta=resource.get_meta(),
+            title=resource.title,
+            icons=resource.icons,
+        )
+
+    @overload
+    async def _read(self, task_meta: None = None) -> ResourceResult: ...
+
+    @overload
+    async def _read(self, task_meta: TaskMeta) -> mcp_types.CreateTaskResult: ...
+
+    async def _read(
+        self, task_meta: TaskMeta | None = None
+    ) -> ResourceResult | mcp_types.CreateTaskResult:
+        """Delegate to child server's read_resource() with task_meta.
+
+        Passes task_meta through to the child server so it can handle
+        backgrounding appropriately. fn_key is already set by the parent
+        server before calling this method.
+        """
+        # Pass exact version so child reads the correct version
+        version = VersionSpec(eq=self.version) if self.version else None
+
+        with delegate_span(
+            self._original_uri or "",
+            "FastMCPProvider",
+            self._original_uri or "",
+            method="resources/read",
+        ):
+            return await self._server.read_resource(
+                self._original_uri, version=version, task_meta=task_meta
+            )
+
+    def get_span_attributes(self) -> dict[str, Any]:
+        return super().get_span_attributes() | {
+            "fastmcp.provider.type": "FastMCPProvider",
+            "fastmcp.delegate.original_uri": self._original_uri,
+        }
+
+
+class FastMCPProviderPrompt(Prompt):
+    """Prompt that delegates rendering to a wrapped server's render_prompt().
+
+    When `render()` is called, this prompt invokes the wrapped server's
+    `render_prompt()` method, ensuring the server's middleware chain is executed.
+    """
+
+    _server: Any = None  # FastMCP, but Any to avoid circular import
+    _original_name: str | None = None
+
+    def __init__(
+        self,
+        server: Any,
+        original_name: str,
+        **kwargs: Any,
+    ):
+        super().__init__(**kwargs)
+        self._server = server
+        self._original_name = original_name
+
+    @classmethod
+    def wrap(cls, server: Any, prompt: Prompt) -> FastMCPProviderPrompt:
+        """Wrap a Prompt to delegate rendering to the server's middleware."""
+        return cls(
+            server=server,
+            original_name=prompt.name,
+            name=prompt.name,
+            version=prompt.version,
+            description=prompt.description,
+            arguments=prompt.arguments,
+            tags=prompt.tags,
+            task_config=prompt.task_config,
+            meta=prompt.get_meta(),
+            title=prompt.title,
+            icons=prompt.icons,
+        )
+
+    @overload
+    async def _render(
+        self,
+        arguments: dict[str, Any] | None = None,
+        task_meta: None = None,
+    ) -> PromptResult: ...
+
+    @overload
+    async def _render(
+        self,
+        arguments: dict[str, Any] | None,
+        task_meta: TaskMeta,
+    ) -> mcp_types.CreateTaskResult: ...
+
+    async def _render(
+        self,
+        arguments: dict[str, Any] | None = None,
+        task_meta: TaskMeta | None = None,
+    ) -> PromptResult | mcp_types.CreateTaskResult:
+        """Delegate to child server's render_prompt() with task_meta.
+
+        Passes task_meta through to the child server so it can handle
+        backgrounding appropriately. fn_key is already set by the parent
+        server before calling this method.
+        """
+        # Pass exact version so child renders the correct version
+        version = VersionSpec(eq=self.version) if self.version else None
+
+        with delegate_span(
+            self._original_name or "",
+            "FastMCPProvider",
+            self._original_name or "",
+            method="prompts/get",
+        ):
+            return await self._server.render_prompt(
+                self._original_name, arguments, version=version, task_meta=task_meta
+            )
+
+    async def render(self, arguments: dict[str, Any] | None = None) -> PromptResult:
+        """Delegate to child server's render_prompt() without task_meta.
+
+        This is called when the prompt is used within a transformed context
+        or other contexts where task_meta is not available.
+        """
+        # Pass exact version so child renders the correct version
+        version = VersionSpec(eq=self.version) if self.version else None
+
+        result = await self._server.render_prompt(
+            self._original_name, arguments, version=version
+        )
+        # Result from render_prompt should always be PromptResult when no task_meta
+        if isinstance(result, mcp_types.CreateTaskResult):
+            raise RuntimeError(
+                "Unexpected CreateTaskResult from render_prompt without task_meta"
+            )
+        return result
+
+    def get_span_attributes(self) -> dict[str, Any]:
+        return super().get_span_attributes() | {
+            "fastmcp.provider.type": "FastMCPProvider",
+            "fastmcp.delegate.original_name": self._original_name,
+        }
+
+
+class FastMCPProviderResourceTemplate(ResourceTemplate):
+    """Resource template that creates FastMCPProviderResources.
+
+    When `create_resource()` is called, this template creates a
+    FastMCPProviderResource that will invoke the wrapped server's middleware
+    when read.
+    """
+
+    _server: Any = None  # FastMCP, but Any to avoid circular import
+    _original_uri_template: str | None = None
+
+    def __init__(
+        self,
+        server: Any,
+        original_uri_template: str,
+        **kwargs: Any,
+    ):
+        super().__init__(**kwargs)
+        self._server = server
+        self._original_uri_template = original_uri_template
+
+    @classmethod
+    def wrap(
+        cls, server: Any, template: ResourceTemplate
+    ) -> FastMCPProviderResourceTemplate:
+        """Wrap a ResourceTemplate to create FastMCPProviderResources."""
+        return cls(
+            server=server,
+            original_uri_template=template.uri_template,
+            uri_template=template.uri_template,
+            version=template.version,
+            name=template.name,
+            description=template.description,
+            mime_type=template.mime_type,
+            parameters=template.parameters,
+            tags=template.tags,
+            annotations=template.annotations,
+            task_config=template.task_config,
+            meta=template.get_meta(),
+            title=template.title,
+            icons=template.icons,
+        )
+
+    async def create_resource(self, uri: str, params: dict[str, Any]) -> Resource:
+        """Create a FastMCPProviderResource for the given URI.
+
+        The `uri` is the external/transformed URI (e.g., with namespace prefix).
+        We use `_original_uri_template` with `params` to construct the internal
+        URI that the nested server understands.
+        """
+        # Expand the original template with params to get internal URI
+        original_uri = expand_uri_template(self._original_uri_template or "", params)
+        return FastMCPProviderResource(
+            server=self._server,
+            original_uri=original_uri,
+            uri=AnyUrl(uri),
+            name=self.name,
+            description=self.description,
+            mime_type=self.mime_type,
+            tags=self.tags,
+            annotations=self.annotations,
+            meta=self.meta,
+            title=self.title,
+            icons=self.icons,
+        )
+
+    @overload
+    async def _read(
+        self, uri: str, params: dict[str, Any], task_meta: None = None
+    ) -> ResourceResult: ...
+
+    @overload
+    async def _read(
+        self, uri: str, params: dict[str, Any], task_meta: TaskMeta
+    ) -> mcp_types.CreateTaskResult: ...
+
+    async def _read(
+        self, uri: str, params: dict[str, Any], task_meta: TaskMeta | None = None
+    ) -> ResourceResult | mcp_types.CreateTaskResult:
+        """Delegate to child server's read_resource() with task_meta.
+
+        Passes task_meta through to the child server so it can handle
+        backgrounding appropriately. fn_key is already set by the parent
+        server before calling this method.
+        """
+        # Expand the original template with params to get internal URI
+        original_uri = expand_uri_template(self._original_uri_template or "", params)
+
+        # Pass exact version so child reads the correct version
+        version = VersionSpec(eq=self.version) if self.version else None
+
+        with delegate_span(
+            original_uri,
+            "FastMCPProvider",
+            self._original_uri_template or "",
+            method="resources/read",
+        ):
+            return await self._server.read_resource(
+                original_uri, version=version, task_meta=task_meta
+            )
+
+    async def read(self, arguments: dict[str, Any]) -> str | bytes | ResourceResult:
+        """Read the resource content for background task execution.
+
+        Reads the resource via the wrapped server and returns the ResourceResult.
+        This method is called by Docket during background task execution.
+        """
+        # Expand the original template with arguments to get internal URI
+        original_uri = expand_uri_template(self._original_uri_template or "", arguments)
+
+        # Pass exact version so child reads the correct version
+        version = VersionSpec(eq=self.version) if self.version else None
+
+        # Read from the wrapped server
+        result = await self._server.read_resource(original_uri, version=version)
+        if isinstance(result, mcp_types.CreateTaskResult):
+            raise RuntimeError("Unexpected CreateTaskResult during Docket execution")
+
+        return result
+
+    def register_with_docket(self, docket: Docket) -> None:
+        """No-op: the child's actual template is registered via get_tasks()."""
+
+    async def add_to_docket(
+        self,
+        docket: Docket,
+        params: dict[str, Any],
+        *,
+        fn_key: str | None = None,
+        task_key: str | None = None,
+        **kwargs: Any,
+    ) -> Execution:
+        """Schedule this template for background execution via docket.
+
+        The child's FunctionResourceTemplate.fn is registered (via get_tasks),
+        and it expects splatted **kwargs, so we splat params here.
+        """
+        lookup_key = fn_key or self.key
+        if task_key:
+            kwargs["key"] = task_key
+        return await docket.add(lookup_key, **kwargs)(**params)
+
+    def get_span_attributes(self) -> dict[str, Any]:
+        return super().get_span_attributes() | {
+            "fastmcp.provider.type": "FastMCPProvider",
+            "fastmcp.delegate.original_uri_template": self._original_uri_template,
+        }
+
+
+# -----------------------------------------------------------------------------
+# FastMCPProvider
+# -----------------------------------------------------------------------------
+
+
+class FastMCPProvider(Provider):
+    """Provider that wraps a FastMCP server.
+
+    This provider enables mounting one FastMCP server onto another, exposing
+    the mounted server's tools, resources, and prompts through the parent
+    server.
+
+    Components returned by this provider are wrapped in FastMCPProvider*
+    classes that delegate execution to the wrapped server's middleware chain.
+    This ensures middleware runs when components are executed.
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.providers import FastMCPProvider
+
+        main = FastMCP("Main")
+        sub = FastMCP("Sub")
+
+        @sub.tool
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        # Mount directly - tools accessible by original names
+        main.add_provider(FastMCPProvider(sub))
+
+        # Or with namespace
+        from fastmcp.server.transforms import Namespace
+        provider = FastMCPProvider(sub)
+        provider.add_transform(Namespace("sub"))
+        main.add_provider(provider)
+        ```
+
+    Note:
+        Normally you would use `FastMCP.mount()` which handles proxy conversion
+        and creates the provider with namespace automatically.
+    """
+
+    def __init__(self, server: FastMCP[Any]):
+        """Initialize a FastMCPProvider.
+
+        Args:
+            server: The FastMCP server to wrap.
+        """
+        super().__init__()
+        self.server = server
+
+    # -------------------------------------------------------------------------
+    # Tool methods
+    # -------------------------------------------------------------------------
+
+    async def _list_tools(self) -> Sequence[Tool]:
+        """List all tools from the mounted server as FastMCPProviderTools.
+
+        Runs the mounted server's middleware so filtering/transformation applies.
+        Wraps each tool as a FastMCPProviderTool that delegates execution to
+        the nested server's middleware.
+        """
+        raw_tools = await self.server.list_tools()
+        return [FastMCPProviderTool.wrap(self.server, t) for t in raw_tools]
+
+    async def _get_tool(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get a tool by name as a FastMCPProviderTool.
+
+        Passes the full VersionSpec to the nested server, which handles both
+        exact version matching and range filtering. Uses get_tool to ensure
+        the nested server's transforms are applied.
+        """
+        raw_tool = await self.server.get_tool(name, version)
+        if raw_tool is None:
+            return None
+        return FastMCPProviderTool.wrap(self.server, raw_tool)
+
+    async def get_app_tool(self, app_name: str, tool_name: str) -> Tool | None:
+        """Delegate to nested server's get_app_tool, wrapping for middleware."""
+        raw_tool = await self.server.get_app_tool(app_name, tool_name)
+        if raw_tool is None:
+            return None
+        wrapped = FastMCPProviderTool.wrap(self.server, raw_tool)
+        from fastmcp.server.providers.addressing import hashed_backend_name
+
+        wrapped._original_name = hashed_backend_name(app_name, tool_name)
+        return wrapped
+
+    async def get_tool_by_hash(self, tool_hash: str, tool_name: str) -> Tool | None:
+        """Delegate to nested server's get_tool_by_hash, wrapping for middleware."""
+        raw_tool = await self.server.get_tool_by_hash(tool_hash, tool_name)
+        if raw_tool is None:
+            return None
+        wrapped = FastMCPProviderTool.wrap(self.server, raw_tool)
+        wrapped._original_name = f"{tool_hash}_{tool_name}"
+        return wrapped
+
+    # -------------------------------------------------------------------------
+    # Resource methods
+    # -------------------------------------------------------------------------
+
+    async def _list_resources(self) -> Sequence[Resource]:
+        """List all resources from the mounted server as FastMCPProviderResources.
+
+        Runs the mounted server's middleware so filtering/transformation applies.
+        Wraps each resource as a FastMCPProviderResource that delegates reading
+        to the nested server's middleware.
+        """
+        raw_resources = await self.server.list_resources()
+        return [FastMCPProviderResource.wrap(self.server, r) for r in raw_resources]
+
+    async def _get_resource(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> Resource | None:
+        """Get a concrete resource by URI as a FastMCPProviderResource.
+
+        Passes the full VersionSpec to the nested server, which handles both
+        exact version matching and range filtering. Uses get_resource to ensure
+        the nested server's transforms are applied.
+        """
+        raw_resource = await self.server.get_resource(uri, version)
+        if raw_resource is None:
+            return None
+        return FastMCPProviderResource.wrap(self.server, raw_resource)
+
+    # -------------------------------------------------------------------------
+    # Resource template methods
+    # -------------------------------------------------------------------------
+
+    async def _list_resource_templates(self) -> Sequence[ResourceTemplate]:
+        """List all resource templates from the mounted server.
+
+        Runs the mounted server's middleware so filtering/transformation applies.
+        Returns FastMCPProviderResourceTemplate instances that create
+        FastMCPProviderResources when materialized.
+        """
+        raw_templates = await self.server.list_resource_templates()
+        return [
+            FastMCPProviderResourceTemplate.wrap(self.server, t) for t in raw_templates
+        ]
+
+    async def _get_resource_template(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> ResourceTemplate | None:
+        """Get a resource template that matches the given URI.
+
+        Passes the full VersionSpec to the nested server, which handles both
+        exact version matching and range filtering. Uses get_resource_template
+        to ensure the nested server's transforms are applied.
+        """
+        raw_template = await self.server.get_resource_template(uri, version)
+        if raw_template is None:
+            return None
+        return FastMCPProviderResourceTemplate.wrap(self.server, raw_template)
+
+    # -------------------------------------------------------------------------
+    # Prompt methods
+    # -------------------------------------------------------------------------
+
+    async def _list_prompts(self) -> Sequence[Prompt]:
+        """List all prompts from the mounted server as FastMCPProviderPrompts.
+
+        Runs the mounted server's middleware so filtering/transformation applies.
+        Returns FastMCPProviderPrompt instances that delegate rendering to the
+        wrapped server's middleware.
+        """
+        raw_prompts = await self.server.list_prompts()
+        return [FastMCPProviderPrompt.wrap(self.server, p) for p in raw_prompts]
+
+    async def _get_prompt(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        """Get a prompt by name as a FastMCPProviderPrompt.
+
+        Passes the full VersionSpec to the nested server, which handles both
+        exact version matching and range filtering. Uses get_prompt to ensure
+        the nested server's transforms are applied.
+        """
+        raw_prompt = await self.server.get_prompt(name, version)
+        if raw_prompt is None:
+            return None
+        return FastMCPProviderPrompt.wrap(self.server, raw_prompt)
+
+    # -------------------------------------------------------------------------
+    # Task registration
+    # -------------------------------------------------------------------------
+
+    async def get_tasks(self) -> Sequence[FastMCPComponent]:
+        """Return task-eligible components from the mounted server.
+
+        Returns the child's ACTUAL components (not wrapped) so their actual
+        functions get registered with Docket. Gets components with child
+        server's transforms applied, then applies this provider's transforms
+        for correct registration keys.
+        """
+        # Get tasks with child server's transforms already applied
+        components = list(await self.server.get_tasks())
+
+        # Separate by type for this provider's transform application
+        tools = [c for c in components if isinstance(c, Tool)]
+        resources = [c for c in components if isinstance(c, Resource)]
+        templates = [c for c in components if isinstance(c, ResourceTemplate)]
+        prompts = [c for c in components if isinstance(c, Prompt)]
+
+        # Apply this provider's transforms sequentially
+        for transform in self.transforms:
+            tools = await transform.list_tools(tools)
+            resources = await transform.list_resources(resources)
+            templates = await transform.list_resource_templates(templates)
+            prompts = await transform.list_prompts(prompts)
+
+        # Filter to only task-eligible components (same as base Provider)
+        return [
+            c
+            for c in [
+                *tools,
+                *resources,
+                *templates,
+                *prompts,
+            ]
+            if c.task_config.supports_tasks()
+        ]
+
+    # -------------------------------------------------------------------------
+    # Lifecycle methods
+    # -------------------------------------------------------------------------
+
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncIterator[None]:
+        """Start the mounted server's lifespan.
+
+        Sets ``_lifespan_root_active=True`` to signal to the wrapped server's
+        ``_docket_lifespan`` that it is running below an existing root in the
+        same runtime tree, then delegates to its full ``_lifespan_manager``.
+        The root's Docket / Worker / SharedContext are reused through
+        ContextVars (``_current_docket`` etc.); the mounted server's user
+        lifespan, ``_lifespan_result`` cache, and its own sub-providers
+        (nested mounts) all run normally.
+
+        The flag is reset as soon as ``_lifespan_manager`` finishes entering,
+        so it doesn't leak into the caller's async scope. Unrelated servers
+        entered later in the same task (e.g. siblings via ``AsyncExitStack``)
+        correctly see no active root and start their own infrastructure.
+        """
+        from fastmcp.server.mixins.lifespan import _lifespan_root_active
+
+        token = _lifespan_root_active.set(True)
+        flag_active = True
+        try:
+            async with self.server._lifespan_manager():
+                # Inner entry is complete; the flag's job (telling _docket_lifespan
+                # to no-op during _lifespan_manager's setup) is done. Reset now so
+                # unrelated lifespans entered later in this task aren't misclassified
+                # as nested.
+                _lifespan_root_active.reset(token)
+                flag_active = False
+                yield
+        finally:
+            if flag_active:
+                _lifespan_root_active.reset(token)
diff --git a/fastmcp_slim/fastmcp/server/providers/filesystem.py b/fastmcp_slim/fastmcp/server/providers/filesystem.py
new file mode 100644
index 0000000..6c69272
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/filesystem.py
@@ -0,0 +1,225 @@
+"""FileSystemProvider for filesystem-based component discovery.
+
+FileSystemProvider scans a directory for Python files, imports them, and
+registers any Tool, Resource, ResourceTemplate, or Prompt objects found.
+
+Components are created using the standalone decorators from fastmcp.tools,
+fastmcp.resources, and fastmcp.prompts:
+
+Example:
+    ```python
+    # In mcp/tools.py
+    from fastmcp.tools import tool
+
+    @tool
+    def greet(name: str) -> str:
+        return f"Hello, {name}!"
+
+    # In main.py
+    from pathlib import Path
+
+    from fastmcp import FastMCP
+    from fastmcp.server.providers import FileSystemProvider
+
+    mcp = FastMCP("MyServer", providers=[FileSystemProvider(Path(__file__).parent / "mcp")])
+    ```
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Any
+
+from fastmcp.prompts.base import Prompt
+from fastmcp.resources.base import Resource
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.providers.filesystem_discovery import discover_and_import
+from fastmcp.server.providers.local_provider import LocalProvider
+from fastmcp.tools.base import Tool
+from fastmcp.utilities.components import FastMCPComponent
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.versions import VersionSpec
+
+logger = get_logger(__name__)
+
+
+class FileSystemProvider(LocalProvider):
+    """Provider that discovers components from the filesystem.
+
+    Scans a directory for Python files and registers any Tool, Resource,
+    ResourceTemplate, or Prompt objects found. Components are created using
+    the standalone decorators:
+    - @tool from fastmcp.tools
+    - @resource from fastmcp.resources
+    - @prompt from fastmcp.prompts
+
+    Args:
+        root: Root directory to scan. Defaults to current directory.
+        reload: If True, re-scan files on every request (dev mode).
+            Defaults to False (scan once at init, cache results).
+
+    Example:
+        ```python
+        # In mcp/tools.py
+        from fastmcp.tools import tool
+
+        @tool
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        # In main.py
+        from pathlib import Path
+
+        from fastmcp import FastMCP
+        from fastmcp.server.providers import FileSystemProvider
+
+        # Path relative to this file
+        mcp = FastMCP("MyServer", providers=[FileSystemProvider(Path(__file__).parent / "mcp")])
+
+        # Dev mode - re-scan on every request
+        mcp = FastMCP("MyServer", providers=[FileSystemProvider(Path(__file__).parent / "mcp", reload=True)])
+        ```
+    """
+
+    def __init__(
+        self,
+        root: str | Path = ".",
+        reload: bool = False,
+    ) -> None:
+        super().__init__(on_duplicate="replace")
+        self._root = Path(root).resolve()
+        self._reload = reload
+        self._loaded = False
+        # Track files we've warned about: path -> mtime when warned
+        # Re-warn if file changes (mtime differs)
+        self._warned_files: dict[Path, float] = {}
+        # Lock for serializing reload operations (created lazily)
+        self._reload_lock: asyncio.Lock | None = None
+        # Generation counter to deduplicate concurrent reloads
+        self._reload_generation: int = 0
+
+        # Always load once at init to catch errors early
+        self._load_components()
+
+    def _load_components(self) -> None:
+        """Discover and register all components from the filesystem."""
+        if self._loaded:
+            self._components.clear()
+
+        if not self._root.exists():
+            logger.warning("FileSystemProvider root does not exist: %s", self._root)
+
+        result = discover_and_import(self._root)
+
+        # Log warnings for failed files (only once per file version)
+        for file_path, error in result.failed_files.items():
+            try:
+                current_mtime = file_path.stat().st_mtime
+            except OSError:
+                current_mtime = 0.0
+
+            # Warn if we haven't warned about this file, or if it changed
+            last_warned_mtime = self._warned_files.get(file_path)
+            if last_warned_mtime is None or last_warned_mtime != current_mtime:
+                logger.warning(f"Failed to import {file_path}: {error}")
+                self._warned_files[file_path] = current_mtime
+
+        # Clear warnings for files that now import successfully
+        successful_files = {fp for fp, _ in result.components}
+        for fp in successful_files:
+            self._warned_files.pop(fp, None)
+
+        for file_path, component in result.components:
+            try:
+                self._register_component(component)
+            except Exception:
+                logger.exception(
+                    "Failed to register %s from %s",
+                    getattr(component, "name", repr(component)),
+                    file_path,
+                )
+
+        self._loaded = True
+        logger.debug(
+            f"FileSystemProvider loaded {len(self._components)} components from {self._root}"
+        )
+
+    def _register_component(self, component: FastMCPComponent) -> None:
+        """Register a single component based on its type."""
+        if isinstance(component, Tool):
+            self.add_tool(component)
+        elif isinstance(component, ResourceTemplate):
+            self.add_template(component)
+        elif isinstance(component, Resource):
+            self.add_resource(component)
+        elif isinstance(component, Prompt):
+            self.add_prompt(component)
+        else:
+            logger.debug("Ignoring unknown component type: %r", type(component))
+
+    async def _with_reload(self, coro_fn: Callable[..., Any], *args: Any) -> Any:
+        """Acquire the reload lock, reload if needed, then run *coro_fn*.
+
+        Holding the lock across both the reload and the read prevents
+        concurrent readers from seeing a partially-rebuilt ``_components``
+        dict (the ``clear()`` + re-register window).
+
+        A generation counter deduplicates concurrent reload requests:
+        if another caller already reloaded while we waited for the lock,
+        we skip the redundant reload.
+        """
+        if not self._reload and self._loaded:
+            return await coro_fn(*args)
+
+        # Create lock lazily (can't create in __init__ without event loop)
+        if self._reload_lock is None:
+            self._reload_lock = asyncio.Lock()
+
+        generation_before = self._reload_generation
+
+        async with self._reload_lock:
+            if not self._loaded or (
+                self._reload and self._reload_generation == generation_before
+            ):
+                await asyncio.to_thread(self._load_components)
+                self._reload_generation += 1
+            return await coro_fn(*args)
+
+    # Override provider methods to support reload mode
+
+    async def _list_tools(self) -> Sequence[Tool]:
+        return await self._with_reload(super()._list_tools)
+
+    async def _get_tool(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Tool | None:
+        return await self._with_reload(super()._get_tool, name, version)
+
+    async def _list_resources(self) -> Sequence[Resource]:
+        return await self._with_reload(super()._list_resources)
+
+    async def _get_resource(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> Resource | None:
+        return await self._with_reload(super()._get_resource, uri, version)
+
+    async def _list_resource_templates(self) -> Sequence[ResourceTemplate]:
+        return await self._with_reload(super()._list_resource_templates)
+
+    async def _get_resource_template(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> ResourceTemplate | None:
+        return await self._with_reload(super()._get_resource_template, uri, version)
+
+    async def _list_prompts(self) -> Sequence[Prompt]:
+        return await self._with_reload(super()._list_prompts)
+
+    async def _get_prompt(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        return await self._with_reload(super()._get_prompt, name, version)
+
+    def __repr__(self) -> str:
+        return f"FileSystemProvider(root={self._root!r}, reload={self._reload})"
diff --git a/fastmcp_slim/fastmcp/server/providers/filesystem_discovery.py b/fastmcp_slim/fastmcp/server/providers/filesystem_discovery.py
new file mode 100644
index 0000000..0c1340e
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/filesystem_discovery.py
@@ -0,0 +1,438 @@
+"""File discovery and module import utilities for filesystem-based routing.
+
+This module provides functions to:
+1. Discover Python files in a directory tree
+2. Import modules (as packages if __init__.py exists, else directly)
+3. Extract decorated components (Tool, Resource, Prompt objects) from imported modules
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import importlib.util
+import sys
+from dataclasses import dataclass, field
+from importlib.machinery import ModuleSpec
+from pathlib import Path
+from types import ModuleType
+
+from fastmcp.utilities.components import FastMCPComponent
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class DiscoveryResult:
+    """Result of filesystem discovery."""
+
+    # Components are real objects (Tool, Resource, ResourceTemplate, Prompt)
+    components: list[tuple[Path, FastMCPComponent]] = field(default_factory=list)
+    failed_files: dict[Path, str] = field(default_factory=dict)  # path -> error message
+
+
+def discover_files(root: Path) -> list[Path]:
+    """Recursively discover all Python files under a directory.
+
+    Excludes __init__.py files (they're for package structure, not components).
+
+    Args:
+        root: Root directory to scan.
+
+    Returns:
+        List of .py file paths, sorted for deterministic order.
+    """
+    if not root.exists():
+        return []
+
+    if not root.is_dir():
+        # If root is a file, just return it (if it's a .py file)
+        if root.suffix == ".py" and root.name != "__init__.py":
+            return [root]
+        return []
+
+    files: list[Path] = []
+    for path in root.rglob("*.py"):
+        # Skip __init__.py files
+        if path.name == "__init__.py":
+            continue
+        # Skip __pycache__ directories
+        if "__pycache__" in path.parts:
+            continue
+        files.append(path)
+
+    # Sort for deterministic discovery order
+    return sorted(files)
+
+
+def _is_package_dir(directory: Path) -> bool:
+    """Check if a directory is a Python package (has __init__.py)."""
+    return (directory / "__init__.py").exists()
+
+
+def _find_package_root(file_path: Path, stop_at: Path | None = None) -> Path | None:
+    """Find the root of the package containing this file.
+
+    Walks up the directory tree until we find a directory without __init__.py,
+    but never above stop_at (the provider root). This prevents escaping into
+    ancestor packages when the provider is nested inside a larger Python project.
+
+    Args:
+        file_path: Path to the Python file.
+        stop_at: Do not walk above this directory. Typically the provider root.
+
+    Returns:
+        The package root directory, or None if not in a package.
+    """
+    current = file_path.parent
+    package_root = None
+
+    while current != current.parent:  # Stop at filesystem root
+        if stop_at is not None and current == stop_at.parent:
+            break  # Don't escape above the provider root
+        if _is_package_dir(current):
+            package_root = current
+            current = current.parent
+        else:
+            break
+
+    return package_root
+
+
+def _compute_module_name(file_path: Path, package_root: Path) -> str:
+    """Compute the dotted module name for a file within a package.
+
+    Args:
+        file_path: Path to the Python file.
+        package_root: Root directory of the package.
+
+    Returns:
+        Dotted module name (e.g., "mcp.tools.greet").
+    """
+    relative = file_path.relative_to(package_root.parent)
+    parts = list(relative.parts)
+    # Remove .py extension from last part
+    parts[-1] = parts[-1].removesuffix(".py")
+    return ".".join(parts)
+
+
+def _package_path_matches(module: ModuleType, package_root: Path) -> bool:
+    """Check whether a package module's __path__ points at package_root.
+
+    Used to tell whether a top-level package name already present in
+    sys.modules belongs to this provider (same directory) or to a different
+    provider that happens to share the package name.
+    """
+    module_paths = getattr(module, "__path__", None)
+    if not module_paths:
+        return False
+    package_root = package_root.resolve()
+    return any(Path(p).resolve() == package_root for p in module_paths)
+
+
+def _private_package_prefix(directory: Path) -> str:
+    """Compute a collision-safe synthetic package name anchored at a directory."""
+    digest = hashlib.sha1(str(directory.resolve()).encode()).hexdigest()[:12]
+    return f"_fastmcp_pkg_{digest}"
+
+
+def import_module_from_file(
+    file_path: Path, provider_root: Path | None = None
+) -> ModuleType:
+    """Import a Python file as a module.
+
+    If the file is part of a package (directory has __init__.py), imports
+    it as a proper package member (relative imports work). Otherwise,
+    imports directly using spec_from_file_location.
+
+    sys.path is modified only for the duration of the import and restored
+    immediately after, so no permanent pollution occurs.
+
+    Args:
+        file_path: Path to the Python file.
+        provider_root: The provider's root directory. Prevents package root
+            discovery from walking above this boundary into ancestor packages.
+
+    Returns:
+        The imported module.
+
+    Raises:
+        ImportError: If the module cannot be imported.
+    """
+    file_path = file_path.resolve()
+    if provider_root is not None:
+        provider_root = provider_root.resolve()
+
+    # Check if this file is part of a package
+    package_root = _find_package_root(file_path, stop_at=provider_root)
+
+    if package_root is not None:
+        # Import as part of a package
+        module_name = _compute_module_name(file_path, package_root)
+
+        # If another provider has already registered this top-level package name
+        # from a different directory, importing normally would resolve against
+        # that provider's directory (wrong file, or ModuleNotFoundError for a
+        # sibling that only exists here). Isolate this provider's tree under a
+        # private anchor package so both providers coexist. The anchor is a
+        # namespace package whose __path__ points at this provider's tree, so
+        # importlib resolves every intermediate package and relative import
+        # normally beneath it.
+        top_name = module_name.split(".")[0]
+        existing_top = sys.modules.get(top_name)
+        if existing_top is not None and not _package_path_matches(
+            existing_top, package_root
+        ):
+            anchor = _private_package_prefix(package_root.parent)
+            if anchor not in sys.modules:
+                spec = ModuleSpec(anchor, loader=None, is_package=True)
+                anchor_module = importlib.util.module_from_spec(spec)
+                anchor_module.__path__ = [str(package_root.parent)]
+                sys.modules[anchor] = anchor_module
+            private_name = f"{anchor}.{module_name}"
+            try:
+                if private_name in sys.modules:
+                    return importlib.reload(sys.modules[private_name])
+                return importlib.import_module(private_name)
+            except ImportError as e:
+                raise ImportError(
+                    f"Failed to import {module_name} from {file_path}: {e}"
+                ) from e
+
+        # Temporarily add package root's parent to sys.path for the import
+        package_parent = str(package_root.parent)
+        path_added = package_parent not in sys.path
+        if path_added:
+            sys.path.insert(0, package_parent)
+
+        try:
+            # If already imported, reload to pick up changes (for reload mode)
+            if module_name in sys.modules:
+                return importlib.reload(sys.modules[module_name])
+            return importlib.import_module(module_name)
+        except ImportError as e:
+            raise ImportError(
+                f"Failed to import {module_name} from {file_path}: {e}"
+            ) from e
+        finally:
+            if path_added:
+                with contextlib.suppress(ValueError):
+                    sys.path.remove(package_parent)
+    else:
+        # Import directly using spec_from_file_location
+        stem = file_path.stem
+        parent_dir = str(file_path.parent)
+
+        # Determine the sys.modules key. Prefer the bare stem (so that sibling
+        # imports like `import helpers` resolve correctly), but fall back to a
+        # private collision-safe key if the bare stem is already claimed by
+        # something else (stdlib, a third-party package, or another provider file
+        # from a different directory).
+        existing = sys.modules.get(stem)
+        if existing is not None and getattr(existing, "__file__", None) != str(
+            file_path
+        ):
+            module_name = f"_fastmcp_{stem}_{hashlib.sha1(str(file_path).encode()).hexdigest()[:12]}"
+        else:
+            module_name = stem
+
+        # Temporarily add parent to sys.path so module-level sibling imports resolve.
+        # Safe to remove after exec_module: all top-level imports are resolved by then,
+        # and sibling files imported as side effects are already in sys.modules.
+        path_added = parent_dir not in sys.path
+        if path_added:
+            sys.path.insert(0, parent_dir)
+
+        try:
+            spec = importlib.util.spec_from_file_location(module_name, file_path)
+            if spec is None or spec.loader is None:
+                raise ImportError(f"Cannot load spec for {file_path}")
+
+            existing = sys.modules.get(module_name)
+            if existing is not None:
+                # Re-exec in place rather than importlib.reload: reload() re-finds
+                # the module by name via sys.path, which fails for private keys
+                # (the file is tool.py, not _fastmcp_tool_xxx.py).
+                existing.__spec__ = spec
+                existing.__loader__ = spec.loader
+                existing.__file__ = str(file_path)
+                try:
+                    spec.loader.exec_module(existing)
+                except Exception as e:
+                    raise ImportError(
+                        f"Failed to reload module {file_path}: {e}"
+                    ) from e
+                return existing
+
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[module_name] = module
+
+            try:
+                spec.loader.exec_module(module)
+            except Exception as e:
+                # Clean up sys.modules on failure
+                sys.modules.pop(module_name, None)
+                raise ImportError(f"Failed to execute module {file_path}: {e}") from e
+
+            return module
+        finally:
+            if path_added:
+                with contextlib.suppress(ValueError):
+                    sys.path.remove(parent_dir)
+
+
+def extract_components(module: ModuleType) -> list[FastMCPComponent]:
+    """Extract all MCP components from a module.
+
+    Scans all module attributes for instances of Tool, Resource,
+    ResourceTemplate, or Prompt objects created by standalone decorators,
+    or functions decorated with @tool/@resource/@prompt that have __fastmcp__ metadata.
+
+    Args:
+        module: The imported module to scan.
+
+    Returns:
+        List of component objects (Tool, Resource, ResourceTemplate, Prompt).
+    """
+    # Import here to avoid circular imports
+    import inspect
+
+    from fastmcp.decorators import get_fastmcp_meta
+    from fastmcp.prompts.base import Prompt
+    from fastmcp.prompts.function_prompt import PromptMeta
+    from fastmcp.resources.base import Resource
+    from fastmcp.resources.function_resource import ResourceMeta
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.server.dependencies import without_injected_parameters
+    from fastmcp.tools.base import Tool
+    from fastmcp.tools.function_tool import ToolMeta
+
+    component_types = (Tool, Resource, ResourceTemplate, Prompt)
+    components: list[FastMCPComponent] = []
+
+    for name in dir(module):
+        # Skip private/magic attributes
+        if name.startswith("_"):
+            continue
+
+        try:
+            obj = getattr(module, name)
+        except AttributeError:
+            continue
+
+        # Check if this object is a component type
+        if isinstance(obj, component_types):
+            components.append(obj)
+            continue
+
+        # Check for functions with __fastmcp__ metadata
+        meta = get_fastmcp_meta(obj)
+        if meta is not None:
+            if isinstance(meta, ToolMeta):
+                resolved_task = meta.task if meta.task is not None else False
+                tool = Tool.from_function(
+                    obj,
+                    name=meta.name,
+                    version=meta.version,
+                    title=meta.title,
+                    description=meta.description,
+                    icons=meta.icons,
+                    tags=meta.tags,
+                    output_schema=meta.output_schema,
+                    annotations=meta.annotations,
+                    meta=meta.meta,
+                    task=resolved_task,
+                    timeout=meta.timeout,
+                    auth=meta.auth,
+                    run_in_thread=meta.run_in_thread,
+                )
+                components.append(tool)
+            elif isinstance(meta, ResourceMeta):
+                resolved_task = meta.task if meta.task is not None else False
+                has_uri_params = "{" in meta.uri and "}" in meta.uri
+                wrapper_fn = without_injected_parameters(obj)
+                has_func_params = bool(inspect.signature(wrapper_fn).parameters)
+
+                if has_uri_params or has_func_params:
+                    resource = ResourceTemplate.from_function(
+                        fn=obj,
+                        uri_template=meta.uri,
+                        name=meta.name,
+                        version=meta.version,
+                        title=meta.title,
+                        description=meta.description,
+                        icons=meta.icons,
+                        mime_type=meta.mime_type,
+                        tags=meta.tags,
+                        annotations=meta.annotations,
+                        meta=meta.meta,
+                        task=resolved_task,
+                        auth=meta.auth,
+                    )
+                else:
+                    resource = Resource.from_function(
+                        fn=obj,
+                        uri=meta.uri,
+                        name=meta.name,
+                        version=meta.version,
+                        title=meta.title,
+                        description=meta.description,
+                        icons=meta.icons,
+                        mime_type=meta.mime_type,
+                        tags=meta.tags,
+                        annotations=meta.annotations,
+                        meta=meta.meta,
+                        task=resolved_task,
+                        auth=meta.auth,
+                    )
+                components.append(resource)
+            elif isinstance(meta, PromptMeta):
+                resolved_task = meta.task if meta.task is not None else False
+                prompt = Prompt.from_function(
+                    obj,
+                    name=meta.name,
+                    version=meta.version,
+                    title=meta.title,
+                    description=meta.description,
+                    icons=meta.icons,
+                    tags=meta.tags,
+                    meta=meta.meta,
+                    task=resolved_task,
+                    auth=meta.auth,
+                )
+                components.append(prompt)
+
+    return components
+
+
+def discover_and_import(root: Path) -> DiscoveryResult:
+    """Discover files, import modules, and extract components.
+
+    This is the main entry point for filesystem-based discovery.
+
+    Args:
+        root: Root directory to scan.
+
+    Returns:
+        DiscoveryResult with components and any failed files.
+
+    Note:
+        Files that fail to import are tracked in failed_files, not logged.
+        The caller is responsible for logging/handling failures.
+        Files with no components are silently skipped.
+    """
+    result = DiscoveryResult()
+
+    for file_path in discover_files(root):
+        try:
+            module = import_module_from_file(file_path, provider_root=root)
+        except Exception as e:
+            result.failed_files[file_path] = str(e)
+            continue
+
+        components = extract_components(module)
+        for component in components:
+            result.components.append((file_path, component))
+
+    return result
diff --git a/fastmcp_slim/fastmcp/server/providers/local_provider/__init__.py b/fastmcp_slim/fastmcp/server/providers/local_provider/__init__.py
new file mode 100644
index 0000000..f3587e2
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/local_provider/__init__.py
@@ -0,0 +1,11 @@
+"""LocalProvider for locally-defined MCP components.
+
+This module provides the `LocalProvider` class that manages tools, resources,
+templates, and prompts registered via decorators or direct methods.
+"""
+
+from fastmcp.server.providers.local_provider.local_provider import (
+    LocalProvider,
+)
+
+__all__ = ["LocalProvider"]
diff --git a/fastmcp_slim/fastmcp/server/providers/local_provider/decorators/__init__.py b/fastmcp_slim/fastmcp/server/providers/local_provider/decorators/__init__.py
new file mode 100644
index 0000000..fe66eaf
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/local_provider/decorators/__init__.py
@@ -0,0 +1,15 @@
+"""Decorator mixins for LocalProvider.
+
+This module provides mixin classes that add decorator functionality
+to LocalProvider for tools, resources, templates, and prompts.
+"""
+
+from .prompts import PromptDecoratorMixin
+from .resources import ResourceDecoratorMixin
+from .tools import ToolDecoratorMixin
+
+__all__ = [
+    "PromptDecoratorMixin",
+    "ResourceDecoratorMixin",
+    "ToolDecoratorMixin",
+]
diff --git a/fastmcp_slim/fastmcp/server/providers/local_provider/decorators/prompts.py b/fastmcp_slim/fastmcp/server/providers/local_provider/decorators/prompts.py
new file mode 100644
index 0000000..ba16218
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/local_provider/decorators/prompts.py
@@ -0,0 +1,237 @@
+"""Prompt decorator mixin for LocalProvider.
+
+This module provides the PromptDecoratorMixin class that adds prompt
+registration functionality to LocalProvider.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from functools import partial
+from typing import TYPE_CHECKING, Any, TypeVar, overload
+
+import mcp_types
+
+from fastmcp.prompts.base import Prompt
+from fastmcp.prompts.function_prompt import FunctionPrompt
+from fastmcp.server.auth.authorization import AuthCheck
+from fastmcp.server.tasks.config import TaskConfig
+from fastmcp.utilities.types import AnyFunction
+
+if TYPE_CHECKING:
+    from fastmcp.server.providers.local_provider import LocalProvider
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class PromptDecoratorMixin:
+    """Mixin class providing prompt decorator functionality for LocalProvider.
+
+    This mixin contains all methods related to:
+    - Prompt registration via add_prompt()
+    - Prompt decorator (@provider.prompt)
+    """
+
+    def add_prompt(self: LocalProvider, prompt: Prompt | Callable[..., Any]) -> Prompt:
+        """Add a prompt to this provider's storage.
+
+        Accepts either a Prompt object or a decorated function with __fastmcp__ metadata.
+        """
+        enabled = True
+        if not isinstance(prompt, Prompt):
+            from fastmcp.decorators import get_fastmcp_meta
+            from fastmcp.prompts.function_prompt import PromptMeta
+
+            meta = get_fastmcp_meta(prompt)
+            if meta is not None and isinstance(meta, PromptMeta):
+                resolved_task = meta.task if meta.task is not None else False
+                enabled = meta.enabled
+                prompt = Prompt.from_function(
+                    prompt,
+                    name=meta.name,
+                    version=meta.version,
+                    title=meta.title,
+                    description=meta.description,
+                    icons=meta.icons,
+                    tags=meta.tags,
+                    meta=meta.meta,
+                    task=resolved_task,
+                    auth=meta.auth,
+                )
+            else:
+                raise TypeError(
+                    f"Expected Prompt or @prompt-decorated function, got {type(prompt).__name__}. "
+                    "Use @prompt decorator or pass a Prompt instance."
+                )
+        self._add_component(prompt)
+        if not enabled:
+            self.disable(keys={prompt.key})
+        return prompt
+
+    @overload
+    def prompt(
+        self: LocalProvider,
+        name_or_fn: F,
+        *,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[mcp_types.Icon] | None = None,
+        tags: set[str] | None = None,
+        enabled: bool = True,
+        meta: dict[str, Any] | None = None,
+        task: bool | TaskConfig | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+    ) -> F: ...
+
+    @overload
+    def prompt(
+        self: LocalProvider,
+        name_or_fn: str | None = None,
+        *,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[mcp_types.Icon] | None = None,
+        tags: set[str] | None = None,
+        enabled: bool = True,
+        meta: dict[str, Any] | None = None,
+        task: bool | TaskConfig | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+    ) -> Callable[[F], F]: ...
+
+    def prompt(
+        self: LocalProvider,
+        name_or_fn: str | AnyFunction | None = None,
+        *,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[mcp_types.Icon] | None = None,
+        tags: set[str] | None = None,
+        enabled: bool = True,
+        meta: dict[str, Any] | None = None,
+        task: bool | TaskConfig | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+    ) -> (
+        Callable[[AnyFunction], FunctionPrompt]
+        | FunctionPrompt
+        | partial[Callable[[AnyFunction], FunctionPrompt] | FunctionPrompt]
+    ):
+        """Decorator to register a prompt.
+
+        This decorator supports multiple calling patterns:
+        - @provider.prompt (without parentheses)
+        - @provider.prompt() (with empty parentheses)
+        - @provider.prompt("custom_name") (with name as first argument)
+        - @provider.prompt(name="custom_name") (with name as keyword argument)
+        - provider.prompt(function, name="custom_name") (direct function call)
+
+        Args:
+            name_or_fn: Either a function (when used as @prompt), a string name, or None
+            name: Optional name for the prompt (keyword-only, alternative to name_or_fn)
+            title: Optional title for the prompt
+            description: Optional description of what the prompt does
+            icons: Optional icons for the prompt
+            tags: Optional set of tags for categorizing the prompt
+            enabled: Whether the prompt is enabled (default True). If False, adds to blocklist.
+            meta: Optional meta information about the prompt
+            task: Optional task configuration for background execution
+            auth: Optional authorization checks for the prompt
+
+        Returns:
+            The registered FunctionPrompt or a decorator function.
+
+        Example:
+            ```python
+            provider = LocalProvider()
+
+            @provider.prompt
+            def analyze(topic: str) -> list:
+                return [{"role": "user", "content": f"Analyze: {topic}"}]
+
+            @provider.prompt("custom_name")
+            def my_prompt(data: str) -> list:
+                return [{"role": "user", "content": data}]
+            ```
+        """
+        if isinstance(name_or_fn, classmethod):
+            raise TypeError(
+                "To decorate a classmethod, use @classmethod above @prompt. "
+                "See https://gofastmcp.com/servers/prompts#using-with-methods"
+            )
+
+        def decorate_and_register(
+            fn: AnyFunction, prompt_name: str | None
+        ) -> FunctionPrompt | AnyFunction:
+            # Check for unbound method
+            try:
+                params = list(inspect.signature(fn).parameters.keys())
+            except (ValueError, TypeError):
+                params = []
+            if params and params[0] in ("self", "cls"):
+                fn_name = getattr(fn, "__name__", "function")
+                raise TypeError(
+                    f"The function '{fn_name}' has '{params[0]}' as its first parameter. "
+                    f"Use the standalone @prompt decorator and register the bound method:\n\n"
+                    f"    from fastmcp.prompts import prompt\n\n"
+                    f"    class MyClass:\n"
+                    f"        @prompt\n"
+                    f"        def {fn_name}(...):\n"
+                    f"            ...\n\n"
+                    f"    obj = MyClass()\n"
+                    f"    mcp.add_prompt(obj.{fn_name})\n\n"
+                    f"See https://gofastmcp.com/servers/prompts#using-with-methods"
+                )
+
+            from fastmcp.prompts.function_prompt import PromptMeta
+
+            metadata = PromptMeta(
+                name=prompt_name,
+                version=version,
+                title=title,
+                description=description,
+                icons=icons,
+                tags=tags,
+                meta=meta,
+                task=task,
+                auth=auth,
+                enabled=enabled,
+            )
+            target = fn.__func__ if hasattr(fn, "__func__") else fn
+            target.__fastmcp__ = metadata  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+            self.add_prompt(fn)
+            return fn
+
+        if inspect.isroutine(name_or_fn):
+            return decorate_and_register(name_or_fn, name)
+
+        elif isinstance(name_or_fn, str):
+            if name is not None:
+                raise TypeError(
+                    f"Cannot specify both a name as first argument and as keyword argument. "
+                    f"Use either @prompt('{name_or_fn}') or @prompt(name='{name}'), not both."
+                )
+            prompt_name = name_or_fn
+        elif name_or_fn is None:
+            prompt_name = name
+        else:
+            raise TypeError(f"Invalid first argument: {type(name_or_fn)}")
+
+        return partial(
+            self.prompt,
+            name=prompt_name,
+            version=version,
+            title=title,
+            description=description,
+            icons=icons,
+            tags=tags,
+            meta=meta,
+            enabled=enabled,
+            task=task,
+            auth=auth,
+        )
diff --git a/fastmcp_slim/fastmcp/server/providers/local_provider/decorators/resources.py b/fastmcp_slim/fastmcp/server/providers/local_provider/decorators/resources.py
new file mode 100644
index 0000000..c9cb475
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/local_provider/decorators/resources.py
@@ -0,0 +1,211 @@
+"""Resource decorator mixin for LocalProvider.
+
+This module provides the ResourceDecoratorMixin class that adds resource
+and template registration functionality to LocalProvider.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, TypeVar
+
+import mcp_types
+from mcp_types import Annotations
+
+from fastmcp.resources.base import Resource
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.auth.authorization import AuthCheck
+from fastmcp.server.tasks.config import TaskConfig
+from fastmcp.utilities.types import AnyFunction
+
+if TYPE_CHECKING:
+    from fastmcp.server.providers.local_provider import LocalProvider
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class ResourceDecoratorMixin:
+    """Mixin class providing resource decorator functionality for LocalProvider.
+
+    This mixin contains all methods related to:
+    - Resource registration via add_resource()
+    - Resource template registration via add_template()
+    - Resource decorator (@provider.resource)
+    """
+
+    def add_resource(
+        self: LocalProvider, resource: Resource | ResourceTemplate | Callable[..., Any]
+    ) -> Resource | ResourceTemplate:
+        """Add a resource to this provider's storage.
+
+        Accepts either a Resource/ResourceTemplate object or a decorated function with __fastmcp__ metadata.
+        """
+        enabled = True
+        if not isinstance(resource, (Resource, ResourceTemplate)):
+            from fastmcp.decorators import get_fastmcp_meta
+            from fastmcp.resources.function_resource import ResourceMeta
+            from fastmcp.server.dependencies import without_injected_parameters
+
+            meta = get_fastmcp_meta(resource)
+            if meta is not None and isinstance(meta, ResourceMeta):
+                resolved_task = meta.task if meta.task is not None else False
+                enabled = meta.enabled
+                has_uri_params = "{" in meta.uri and "}" in meta.uri
+                wrapper_fn = without_injected_parameters(resource)
+                has_func_params = bool(inspect.signature(wrapper_fn).parameters)
+
+                if has_uri_params or has_func_params:
+                    resource = ResourceTemplate.from_function(
+                        fn=resource,
+                        uri_template=meta.uri,
+                        name=meta.name,
+                        version=meta.version,
+                        title=meta.title,
+                        description=meta.description,
+                        icons=meta.icons,
+                        mime_type=meta.mime_type,
+                        tags=meta.tags,
+                        annotations=meta.annotations,
+                        meta=meta.meta,
+                        task=resolved_task,
+                        auth=meta.auth,
+                    )
+                else:
+                    resource = Resource.from_function(
+                        fn=resource,
+                        uri=meta.uri,
+                        name=meta.name,
+                        version=meta.version,
+                        title=meta.title,
+                        description=meta.description,
+                        icons=meta.icons,
+                        mime_type=meta.mime_type,
+                        tags=meta.tags,
+                        annotations=meta.annotations,
+                        meta=meta.meta,
+                        task=resolved_task,
+                        auth=meta.auth,
+                    )
+            else:
+                raise TypeError(
+                    f"Expected Resource, ResourceTemplate, or @resource-decorated function, got {type(resource).__name__}. "
+                    "Use @resource('uri') decorator or pass a Resource/ResourceTemplate instance."
+                )
+        self._add_component(resource)
+        if not enabled:
+            self.disable(keys={resource.key})
+        return resource
+
+    def add_template(
+        self: LocalProvider, template: ResourceTemplate
+    ) -> ResourceTemplate:
+        """Add a resource template to this provider's storage."""
+        return self._add_component(template)
+
+    def resource(
+        self: LocalProvider,
+        uri: str,
+        *,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[mcp_types.Icon] | None = None,
+        mime_type: str | None = None,
+        tags: set[str] | None = None,
+        enabled: bool = True,
+        annotations: Annotations | dict[str, Any] | None = None,
+        meta: dict[str, Any] | None = None,
+        task: bool | TaskConfig | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+    ) -> Callable[[F], F]:
+        """Decorator to register a function as a resource.
+
+        If the URI contains parameters (e.g. "resource://{param}") or the function
+        has parameters, it will be registered as a template resource.
+
+        Args:
+            uri: URI for the resource (e.g. "resource://my-resource" or "resource://{param}")
+            name: Optional name for the resource
+            title: Optional title for the resource
+            description: Optional description of the resource
+            icons: Optional icons for the resource
+            mime_type: Optional MIME type for the resource
+            tags: Optional set of tags for categorizing the resource
+            enabled: Whether the resource is enabled (default True). If False, adds to blocklist.
+            annotations: Optional annotations about the resource's behavior
+            meta: Optional meta information about the resource
+            task: Optional task configuration for background execution
+            auth: Optional authorization checks for the resource
+
+        Returns:
+            A decorator function.
+
+        Example:
+            ```python
+            provider = LocalProvider()
+
+            @provider.resource("data://config")
+            def get_config() -> str:
+                return '{"setting": "value"}'
+
+            @provider.resource("data://{city}/weather")
+            def get_weather(city: str) -> str:
+                return f"Weather for {city}"
+            ```
+        """
+        if isinstance(annotations, dict):
+            annotations = Annotations(**annotations)
+
+        if inspect.isroutine(uri):
+            raise TypeError(
+                "The @resource decorator was used incorrectly. "
+                "It requires a URI as the first argument. "
+                "Use @resource('uri') instead of @resource"
+            )
+
+        def decorator(fn: AnyFunction) -> Any:
+            # Check for unbound method
+            try:
+                params = list(inspect.signature(fn).parameters.keys())
+            except (ValueError, TypeError):
+                params = []
+            if params and params[0] in ("self", "cls"):
+                fn_name = getattr(fn, "__name__", "function")
+                raise TypeError(
+                    f"The function '{fn_name}' has '{params[0]}' as its first parameter. "
+                    f"Use the standalone @resource decorator and register the bound method:\n\n"
+                    f"    from fastmcp.resources import resource\n\n"
+                    f"    class MyClass:\n"
+                    f"        @resource('{uri}')\n"
+                    f"        def {fn_name}(...):\n"
+                    f"            ...\n\n"
+                    f"    obj = MyClass()\n"
+                    f"    mcp.add_resource(obj.{fn_name})\n\n"
+                    f"See https://gofastmcp.com/servers/resources#using-with-methods"
+                )
+
+            from fastmcp.resources.function_resource import ResourceMeta
+
+            metadata = ResourceMeta(
+                uri=uri,
+                name=name,
+                version=version,
+                title=title,
+                description=description,
+                icons=icons,
+                tags=tags,
+                mime_type=mime_type,
+                annotations=annotations,
+                meta=meta,
+                task=task,
+                auth=auth,
+                enabled=enabled,
+            )
+            target = fn.__func__ if hasattr(fn, "__func__") else fn
+            target.__fastmcp__ = metadata  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+            self.add_resource(fn)
+            return fn
+
+        return decorator
diff --git a/fastmcp_slim/fastmcp/server/providers/local_provider/decorators/tools.py b/fastmcp_slim/fastmcp/server/providers/local_provider/decorators/tools.py
new file mode 100644
index 0000000..dcf1c0a
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/local_provider/decorators/tools.py
@@ -0,0 +1,369 @@
+"""Tool decorator mixin for LocalProvider.
+
+This module provides the ToolDecoratorMixin class that adds tool
+registration functionality to LocalProvider.
+"""
+
+from __future__ import annotations
+
+import inspect
+import types
+from collections.abc import Callable
+from functools import partial
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    Literal,
+    TypeVar,
+    Union,
+    get_args,
+    get_origin,
+    overload,
+)
+
+import mcp_types
+from mcp_types import ToolAnnotations
+
+from fastmcp.server.auth.authorization import AuthCheck
+from fastmcp.server.tasks.config import TaskConfig
+from fastmcp.tools.base import Tool
+from fastmcp.tools.function_tool import FunctionTool
+from fastmcp.utilities.types import AnyFunction, NotSet, NotSetT
+
+try:
+    from prefab_ui.app import PrefabApp as _PrefabApp
+    from prefab_ui.components.base import Component as _PrefabComponent
+
+    _HAS_PREFAB = True
+except ImportError:
+    _HAS_PREFAB = False
+
+if TYPE_CHECKING:
+    from fastmcp.server.providers.local_provider import LocalProvider
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+DuplicateBehavior = Literal["error", "warn", "replace", "ignore"]
+
+PREFAB_RENDERER_URI = "ui://prefab/renderer.html"
+
+
+def _is_prefab_type(tp: Any) -> bool:
+    """Check if *tp* is or contains a prefab type, recursing through unions and Annotated."""
+    if isinstance(tp, type) and issubclass(tp, (_PrefabApp, _PrefabComponent)):
+        return True
+    origin = get_origin(tp)
+    if origin is Union or origin is types.UnionType or origin is Annotated:
+        return any(_is_prefab_type(a) for a in get_args(tp))
+    return False
+
+
+def _has_prefab_return_type(tool: Tool) -> bool:
+    """Check if a FunctionTool's return type annotation is a prefab type."""
+    if not _HAS_PREFAB or not isinstance(tool, FunctionTool):
+        return False
+    rt = tool.return_type
+    if rt is None or rt is inspect.Parameter.empty:
+        return False
+    return _is_prefab_type(rt)
+
+
+def _stamp_prefab_marker(tool: Tool) -> None:
+    """Mark a tool as needing a Prefab renderer resource.
+
+    Sets ``meta["ui"]["resourceUri"]`` to a placeholder URI. The server
+    recognizes the placeholder at list_tools / list_resources / read_resource
+    time and synthesizes a per-tool resource on the fly with a hashed URI
+    derived from the tool's mount-point address. Nothing is stored — the
+    renderer HTML and CSP are generated on demand from the tool's own meta.
+    """
+    from fastmcp.apps.config import AppConfig, app_config_to_meta_dict
+
+    app_config = AppConfig(resource_uri=PREFAB_RENDERER_URI)
+    meta = dict(tool.meta) if tool.meta else {}
+    meta["ui"] = app_config_to_meta_dict(app_config)
+    tool.meta = meta
+
+
+def _maybe_apply_prefab_ui(provider: LocalProvider, tool: Tool) -> None:
+    """Mark a tool as a Prefab tool if its config or return type implies it.
+
+    Per-tool renderer resources are synthesized lazily at list/read time;
+    here we only normalize the tool's meta so the synthesis pass can spot
+    it. ``app=True``, return-type inference, and ``PrefabAppConfig`` all
+    funnel through the same placeholder marker.
+    """
+    if not _HAS_PREFAB:
+        return
+
+    meta = tool.meta or {}
+    ui = meta.get("ui")
+
+    if ui is True:
+        # Explicit app=True: stamp the placeholder so the synthesizer finds it.
+        _stamp_prefab_marker(tool)
+    elif ui is None and _has_prefab_return_type(tool):
+        # Inference: return type is a prefab type, stamp the placeholder.
+        _stamp_prefab_marker(tool)
+    # Otherwise the tool either has no ui meta at all (not a prefab tool)
+    # or it already has a fully-formed dict from FastMCP.tool(app=...) — the
+    # synthesizer picks up both flavors by looking for the placeholder URI.
+
+
+class ToolDecoratorMixin:
+    """Mixin class providing tool decorator functionality for LocalProvider.
+
+    This mixin contains all methods related to:
+    - Tool registration via add_tool()
+    - Tool decorator (@provider.tool)
+    """
+
+    def add_tool(self: LocalProvider, tool: Tool | Callable[..., Any]) -> Tool:
+        """Add a tool to this provider's storage.
+
+        Accepts either a Tool object or a decorated function with __fastmcp__ metadata.
+        """
+        enabled = True
+        if not isinstance(tool, Tool):
+            from fastmcp.decorators import get_fastmcp_meta
+            from fastmcp.tools.function_tool import ToolMeta
+
+            fmeta = get_fastmcp_meta(tool)
+            if fmeta is not None and isinstance(fmeta, ToolMeta):
+                resolved_task = fmeta.task if fmeta.task is not None else False
+                enabled = fmeta.enabled
+
+                # Merge ToolMeta.app into the meta dict
+                tool_meta = fmeta.meta
+                if fmeta.app is not None:
+                    from fastmcp.apps.config import app_config_to_meta_dict
+
+                    tool_meta = dict(tool_meta) if tool_meta else {}
+                    if fmeta.app is True:
+                        tool_meta["ui"] = True
+                    else:
+                        tool_meta["ui"] = app_config_to_meta_dict(fmeta.app)
+
+                tool = Tool.from_function(
+                    tool,
+                    name=fmeta.name,
+                    version=fmeta.version,
+                    title=fmeta.title,
+                    description=fmeta.description,
+                    icons=fmeta.icons,
+                    tags=fmeta.tags,
+                    output_schema=fmeta.output_schema,
+                    annotations=fmeta.annotations,
+                    meta=tool_meta,
+                    task=resolved_task,
+                    timeout=fmeta.timeout,
+                    auth=fmeta.auth,
+                    run_in_thread=fmeta.run_in_thread,
+                )
+            else:
+                tool = Tool.from_function(tool)
+        self._add_component(tool)
+        if not enabled:
+            self.disable(keys={tool.key})
+        _maybe_apply_prefab_ui(self, tool)
+        return tool
+
+    @overload
+    def tool(
+        self: LocalProvider,
+        name_or_fn: F,
+        *,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[mcp_types.Icon] | None = None,
+        tags: set[str] | None = None,
+        output_schema: dict[str, Any] | NotSetT | None = NotSet,
+        annotations: ToolAnnotations | dict[str, Any] | None = None,
+        meta: dict[str, Any] | None = None,
+        enabled: bool = True,
+        task: bool | TaskConfig | None = None,
+        timeout: float | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+        run_in_thread: bool = True,
+    ) -> F: ...
+
+    @overload
+    def tool(
+        self: LocalProvider,
+        name_or_fn: str | None = None,
+        *,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[mcp_types.Icon] | None = None,
+        tags: set[str] | None = None,
+        output_schema: dict[str, Any] | NotSetT | None = NotSet,
+        annotations: ToolAnnotations | dict[str, Any] | None = None,
+        meta: dict[str, Any] | None = None,
+        enabled: bool = True,
+        task: bool | TaskConfig | None = None,
+        timeout: float | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+        run_in_thread: bool = True,
+    ) -> Callable[[F], F]: ...
+
+    # NOTE: This method mirrors fastmcp.tools.tool() but adds registration and
+    # the `enabled` param. It could delegate to the standalone decorator to
+    # reduce duplication.
+    def tool(
+        self: LocalProvider,
+        name_or_fn: str | AnyFunction | None = None,
+        *,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[mcp_types.Icon] | None = None,
+        tags: set[str] | None = None,
+        output_schema: dict[str, Any] | NotSetT | None = NotSet,
+        annotations: ToolAnnotations | dict[str, Any] | None = None,
+        meta: dict[str, Any] | None = None,
+        enabled: bool = True,
+        task: bool | TaskConfig | None = None,
+        timeout: float | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+        run_in_thread: bool = True,
+    ) -> (
+        Callable[[AnyFunction], FunctionTool]
+        | FunctionTool
+        | partial[Callable[[AnyFunction], FunctionTool] | FunctionTool]
+    ):
+        """Decorator to register a tool.
+
+        This decorator supports multiple calling patterns:
+        - @provider.tool (without parentheses)
+        - @provider.tool() (with empty parentheses)
+        - @provider.tool("custom_name") (with name as first argument)
+        - @provider.tool(name="custom_name") (with name as keyword argument)
+        - provider.tool(function, name="custom_name") (direct function call)
+
+        Args:
+            name_or_fn: Either a function (when used as @tool), a string name, or None
+            name: Optional name for the tool (keyword-only, alternative to name_or_fn)
+            title: Optional title for the tool
+            description: Optional description of what the tool does
+            icons: Optional icons for the tool
+            tags: Optional set of tags for categorizing the tool
+            output_schema: Optional JSON schema for the tool's output
+            annotations: Optional annotations about the tool's behavior
+            meta: Optional meta information about the tool
+            enabled: Whether the tool is enabled (default True). If False, adds to blocklist.
+            task: Optional task configuration for background execution
+
+        Returns:
+            The registered FunctionTool or a decorator function.
+
+        Example:
+            ```python
+            provider = LocalProvider()
+
+            @provider.tool
+            def greet(name: str) -> str:
+                return f"Hello, {name}!"
+
+            @provider.tool("custom_name")
+            def my_tool(x: int) -> str:
+                return str(x)
+            ```
+        """
+        if isinstance(annotations, dict):
+            annotations = ToolAnnotations(**annotations)
+
+        if isinstance(name_or_fn, classmethod):
+            raise TypeError(
+                "To decorate a classmethod, use @classmethod above @tool. "
+                "See https://gofastmcp.com/servers/tools#using-with-methods"
+            )
+
+        def decorate_and_register(
+            fn: AnyFunction, tool_name: str | None
+        ) -> FunctionTool | AnyFunction:
+            # Check for unbound method
+            try:
+                params = list(inspect.signature(fn).parameters.keys())
+            except (ValueError, TypeError):
+                params = []
+            if params and params[0] in ("self", "cls"):
+                fn_name = getattr(fn, "__name__", "function")
+                raise TypeError(
+                    f"The function '{fn_name}' has '{params[0]}' as its first parameter. "
+                    f"Use the standalone @tool decorator and register the bound method:\n\n"
+                    f"    from fastmcp.tools import tool\n\n"
+                    f"    class MyClass:\n"
+                    f"        @tool\n"
+                    f"        def {fn_name}(...):\n"
+                    f"            ...\n\n"
+                    f"    obj = MyClass()\n"
+                    f"    mcp.add_tool(obj.{fn_name})\n\n"
+                    f"See https://gofastmcp.com/servers/tools#using-with-methods"
+                )
+
+            from fastmcp.tools.function_tool import ToolMeta
+
+            metadata = ToolMeta(
+                name=tool_name,
+                version=version,
+                title=title,
+                description=description,
+                icons=icons,
+                tags=tags,
+                output_schema=output_schema,
+                annotations=annotations,
+                meta=meta,
+                task=task,
+                timeout=timeout,
+                auth=auth,
+                enabled=enabled,
+                run_in_thread=run_in_thread,
+            )
+            target = fn.__func__ if hasattr(fn, "__func__") else fn
+            target.__fastmcp__ = metadata  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+            self.add_tool(fn)
+            return fn
+
+        if inspect.isroutine(name_or_fn):
+            return decorate_and_register(name_or_fn, name)
+
+        elif isinstance(name_or_fn, str):
+            # Case 3: @tool("custom_name") - name passed as first argument
+            if name is not None:
+                raise TypeError(
+                    "Cannot specify both a name as first argument and as keyword argument. "
+                    f"Use either @tool('{name_or_fn}') or @tool(name='{name}'), not both."
+                )
+            tool_name = name_or_fn
+        elif name_or_fn is None:
+            # Case 4: @tool() or @tool(name="something") - use keyword name
+            tool_name = name
+        else:
+            raise TypeError(
+                f"First argument to @tool must be a function, string, or None, got {type(name_or_fn)}"
+            )
+
+        # Return partial for cases where we need to wait for the function
+        return partial(
+            self.tool,
+            name=tool_name,
+            version=version,
+            title=title,
+            description=description,
+            icons=icons,
+            tags=tags,
+            output_schema=output_schema,
+            annotations=annotations,
+            meta=meta,
+            enabled=enabled,
+            task=task,
+            timeout=timeout,
+            auth=auth,
+            run_in_thread=run_in_thread,
+        )
diff --git a/fastmcp_slim/fastmcp/server/providers/local_provider/local_provider.py b/fastmcp_slim/fastmcp/server/providers/local_provider/local_provider.py
new file mode 100644
index 0000000..f8d790a
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/local_provider/local_provider.py
@@ -0,0 +1,465 @@
+"""LocalProvider for locally-defined MCP components.
+
+This module provides the `LocalProvider` class that manages tools, resources,
+templates, and prompts registered via decorators or direct methods.
+
+LocalProvider can be used standalone and attached to multiple servers:
+
+```python
+from fastmcp.server.providers import LocalProvider
+
+# Create a reusable provider with tools
+provider = LocalProvider()
+
+@provider.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+# Attach to any server
+from fastmcp import FastMCP
+server1 = FastMCP("Server1", providers=[provider])
+server2 = FastMCP("Server2", providers=[provider])
+```
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Literal, TypeVar
+
+from fastmcp.prompts.base import Prompt
+from fastmcp.resources.base import Resource
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.providers.base import Provider
+from fastmcp.server.providers.local_provider.decorators import (
+    PromptDecoratorMixin,
+    ResourceDecoratorMixin,
+    ToolDecoratorMixin,
+)
+from fastmcp.tools.base import Tool
+from fastmcp.utilities.components import FastMCPComponent
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.versions import VersionSpec, version_sort_key
+
+logger = get_logger(__name__)
+
+DuplicateBehavior = Literal["error", "warn", "replace", "ignore"]
+
+_C = TypeVar("_C", bound=FastMCPComponent)
+
+
+class LocalProvider(
+    Provider,
+    ToolDecoratorMixin,
+    ResourceDecoratorMixin,
+    PromptDecoratorMixin,
+):
+    """Provider for locally-defined components.
+
+    Supports decorator-based registration (`@provider.tool`, `@provider.resource`,
+    `@provider.prompt`) and direct object registration methods.
+
+    When used standalone, LocalProvider uses default settings. When attached
+    to a FastMCP server via the server's decorators, server-level settings
+    like `_tool_serializer` and `_support_tasks_by_default` are injected.
+
+    Example:
+        ```python
+        from fastmcp.server.providers import LocalProvider
+
+        # Standalone usage
+        provider = LocalProvider()
+
+        @provider.tool
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        @provider.resource("data://config")
+        def get_config() -> str:
+            return '{"setting": "value"}'
+
+        @provider.prompt
+        def analyze(topic: str) -> list:
+            return [{"role": "user", "content": f"Analyze: {topic}"}]
+
+        # Attach to server(s)
+        from fastmcp import FastMCP
+        server = FastMCP("MyServer", providers=[provider])
+        ```
+    """
+
+    def __init__(
+        self,
+        on_duplicate: DuplicateBehavior = "error",
+    ) -> None:
+        """Initialize a LocalProvider with empty storage.
+
+        Args:
+            on_duplicate: Behavior when adding a component that already exists:
+                - "error": Raise ValueError
+                - "warn": Log warning and replace
+                - "replace": Silently replace
+                - "ignore": Keep existing, return it
+        """
+        super().__init__()
+        self._on_duplicate = on_duplicate
+        # Unified component storage - keyed by prefixed key (e.g., "tool:name", "resource:uri")
+        self._components: dict[str, FastMCPComponent] = {}
+
+    # =========================================================================
+    # Storage methods
+    # =========================================================================
+
+    def _get_component_identity(self, component: FastMCPComponent) -> tuple[type, str]:
+        """Get the identity (type, name/uri) for a component.
+
+        Returns:
+            A tuple of (component_type, logical_name) where logical_name is
+            the name for tools/prompts or URI for resources/templates.
+        """
+        if isinstance(component, Tool):
+            return (Tool, component.name)
+        elif isinstance(component, ResourceTemplate):
+            return (ResourceTemplate, component.uri_template)
+        elif isinstance(component, Resource):
+            return (Resource, str(component.uri))
+        elif isinstance(component, Prompt):
+            return (Prompt, component.name)
+        else:
+            # Fall back to key without version suffix
+            key = component.key
+            base_key = key.rsplit("@", 1)[0] if "@" in key else key
+            return (type(component), base_key)
+
+    def _check_version_mixing(self, component: _C) -> None:
+        """Check that versioned and unversioned components aren't mixed.
+
+        LocalProvider enforces a simple rule: for any given name/URI, all
+        registered components must either be versioned or unversioned, not both.
+        This prevents confusing situations where unversioned components can't
+        be filtered out by version filters.
+
+        Args:
+            component: The component being added.
+
+        Raises:
+            ValueError: If adding would mix versioned and unversioned components.
+        """
+        comp_type, logical_name = self._get_component_identity(component)
+        is_versioned = component.version is not None
+
+        # Check all existing components of the same type and logical name
+        for existing in self._components.values():
+            if not isinstance(existing, comp_type):
+                continue
+
+            _, existing_name = self._get_component_identity(existing)
+            if existing_name != logical_name:
+                continue
+
+            existing_versioned = existing.version is not None
+            if is_versioned != existing_versioned:
+                type_name = comp_type.__name__.lower()
+                if is_versioned:
+                    raise ValueError(
+                        f"Cannot add versioned {type_name} {logical_name!r} "
+                        f"(version={component.version!r}): an unversioned "
+                        f"{type_name} with this name already exists. "
+                        f"Either version all components or none."
+                    )
+                else:
+                    raise ValueError(
+                        f"Cannot add unversioned {type_name} {logical_name!r}: "
+                        f"versioned {type_name}s with this name already exist "
+                        f"(e.g., version={existing.version!r}). "
+                        f"Either version all components or none."
+                    )
+
+    def _add_component(self, component: _C) -> _C:
+        """Add a component to unified storage.
+
+        Args:
+            component: The component to add.
+
+        Returns:
+            The component that was added (or existing if on_duplicate="ignore").
+        """
+        existing = self._components.get(component.key)
+        if existing:
+            if self._on_duplicate == "error":
+                raise ValueError(f"Component already exists: {component.key}")
+            elif self._on_duplicate == "warn":
+                logger.warning(f"Component already exists: {component.key}")
+            elif self._on_duplicate == "ignore":
+                return existing  # type: ignore[return-value]  # ty:ignore[invalid-return-type]
+            # "replace" and "warn" fall through to add
+
+        # Check for versioned/unversioned mixing before adding
+        self._check_version_mixing(component)
+
+        self._components[component.key] = component
+        return component
+
+    def _remove_component(self, key: str) -> None:
+        """Remove a component from unified storage.
+
+        Args:
+            key: The prefixed key of the component.
+
+        Raises:
+            KeyError: If the component is not found.
+        """
+        component = self._components.get(key)
+        if component is None:
+            raise KeyError(f"Component {key!r} not found")
+
+        del self._components[key]
+
+    def _get_component(self, key: str) -> FastMCPComponent | None:
+        """Get a component by its prefixed key.
+
+        Args:
+            key: The prefixed key (e.g., "tool:name", "resource:uri").
+
+        Returns:
+            The component, or None if not found.
+        """
+        return self._components.get(key)
+
+    def remove_tool(self, name: str, version: str | None = None) -> None:
+        """Remove tool(s) from this provider's storage.
+
+        Args:
+            name: The tool name.
+            version: If None, removes ALL versions. If specified, removes only that version.
+
+        Raises:
+            KeyError: If no matching tool is found.
+        """
+        if version is None:
+            # Remove all versions
+            keys_to_remove = [
+                k
+                for k, c in self._components.items()
+                if isinstance(c, Tool) and c.name == name
+            ]
+            if not keys_to_remove:
+                raise KeyError(f"Tool {name!r} not found")
+            for key in keys_to_remove:
+                self._remove_component(key)
+        else:
+            # Remove specific version - key format is "tool:name@version"
+            key = f"{Tool.make_key(name)}@{version}"
+            if key not in self._components:
+                raise KeyError(f"Tool {name!r} version {version!r} not found")
+            self._remove_component(key)
+
+    def remove_resource(self, uri: str, version: str | None = None) -> None:
+        """Remove resource(s) from this provider's storage.
+
+        Args:
+            uri: The resource URI.
+            version: If None, removes ALL versions. If specified, removes only that version.
+
+        Raises:
+            KeyError: If no matching resource is found.
+        """
+        if version is None:
+            # Remove all versions
+            keys_to_remove = [
+                k
+                for k, c in self._components.items()
+                if isinstance(c, Resource) and str(c.uri) == uri
+            ]
+            if not keys_to_remove:
+                raise KeyError(f"Resource {uri!r} not found")
+            for key in keys_to_remove:
+                self._remove_component(key)
+        else:
+            # Remove specific version
+            key = f"{Resource.make_key(uri)}@{version}"
+            if key not in self._components:
+                raise KeyError(f"Resource {uri!r} version {version!r} not found")
+            self._remove_component(key)
+
+    def remove_template(self, uri_template: str, version: str | None = None) -> None:
+        """Remove resource template(s) from this provider's storage.
+
+        Args:
+            uri_template: The template URI pattern.
+            version: If None, removes ALL versions. If specified, removes only that version.
+
+        Raises:
+            KeyError: If no matching template is found.
+        """
+        if version is None:
+            # Remove all versions
+            keys_to_remove = [
+                k
+                for k, c in self._components.items()
+                if isinstance(c, ResourceTemplate) and c.uri_template == uri_template
+            ]
+            if not keys_to_remove:
+                raise KeyError(f"Template {uri_template!r} not found")
+            for key in keys_to_remove:
+                self._remove_component(key)
+        else:
+            # Remove specific version
+            key = f"{ResourceTemplate.make_key(uri_template)}@{version}"
+            if key not in self._components:
+                raise KeyError(
+                    f"Template {uri_template!r} version {version!r} not found"
+                )
+            self._remove_component(key)
+
+    def remove_prompt(self, name: str, version: str | None = None) -> None:
+        """Remove prompt(s) from this provider's storage.
+
+        Args:
+            name: The prompt name.
+            version: If None, removes ALL versions. If specified, removes only that version.
+
+        Raises:
+            KeyError: If no matching prompt is found.
+        """
+        if version is None:
+            # Remove all versions
+            keys_to_remove = [
+                k
+                for k, c in self._components.items()
+                if isinstance(c, Prompt) and c.name == name
+            ]
+            if not keys_to_remove:
+                raise KeyError(f"Prompt {name!r} not found")
+            for key in keys_to_remove:
+                self._remove_component(key)
+        else:
+            # Remove specific version
+            key = f"{Prompt.make_key(name)}@{version}"
+            if key not in self._components:
+                raise KeyError(f"Prompt {name!r} version {version!r} not found")
+            self._remove_component(key)
+
+    # =========================================================================
+    # Provider interface implementation
+    # =========================================================================
+
+    async def _list_tools(self) -> Sequence[Tool]:
+        """Return all tools."""
+        return [v for v in self._components.values() if isinstance(v, Tool)]
+
+    async def _get_tool(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get a tool by name.
+
+        Args:
+            name: The tool name.
+            version: Optional version filter. If None, returns highest version.
+        """
+        matching = [
+            v
+            for v in self._components.values()
+            if isinstance(v, Tool) and v.name == name
+        ]
+        if version:
+            matching = [t for t in matching if version.matches(t.version)]
+        if not matching:
+            return None
+        return max(matching, key=version_sort_key)
+
+    async def _list_resources(self) -> Sequence[Resource]:
+        """Return all resources."""
+        return [v for v in self._components.values() if isinstance(v, Resource)]
+
+    async def _get_resource(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> Resource | None:
+        """Get a resource by URI.
+
+        Args:
+            uri: The resource URI.
+            version: Optional version filter. If None, returns highest version.
+        """
+        matching = [
+            v
+            for v in self._components.values()
+            if isinstance(v, Resource) and str(v.uri) == uri
+        ]
+        if version:
+            matching = [r for r in matching if version.matches(r.version)]
+        if not matching:
+            return None
+        return max(matching, key=version_sort_key)
+
+    async def _list_resource_templates(self) -> Sequence[ResourceTemplate]:
+        """Return all resource templates."""
+        return [v for v in self._components.values() if isinstance(v, ResourceTemplate)]
+
+    async def _get_resource_template(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> ResourceTemplate | None:
+        """Get a resource template that matches the given URI.
+
+        Args:
+            uri: The URI to match against templates.
+            version: Optional version filter. If None, returns highest version.
+        """
+        # Find all templates that match the URI
+        matching = [
+            component
+            for component in self._components.values()
+            if isinstance(component, ResourceTemplate)
+            and component.matches(uri) is not None
+        ]
+        if version:
+            matching = [t for t in matching if version.matches(t.version)]
+        if not matching:
+            return None
+        return max(matching, key=version_sort_key)
+
+    async def _list_prompts(self) -> Sequence[Prompt]:
+        """Return all prompts."""
+        return [v for v in self._components.values() if isinstance(v, Prompt)]
+
+    async def _get_prompt(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        """Get a prompt by name.
+
+        Args:
+            name: The prompt name.
+            version: Optional version filter. If None, returns highest version.
+        """
+        matching = [
+            v
+            for v in self._components.values()
+            if isinstance(v, Prompt) and v.name == name
+        ]
+        if version:
+            matching = [p for p in matching if version.matches(p.version)]
+        if not matching:
+            return None
+        return max(matching, key=version_sort_key)
+
+    # =========================================================================
+    # Task registration
+    # =========================================================================
+
+    async def get_tasks(self) -> Sequence[FastMCPComponent]:
+        """Return components eligible for background task execution.
+
+        Returns components that have task_config.mode != 'forbidden'.
+        This includes both FunctionTool/Resource/Prompt instances created via
+        decorators and custom Tool/Resource/Prompt subclasses.
+        """
+        return [c for c in self._components.values() if c.task_config.supports_tasks()]
+
+    # =========================================================================
+    # Decorator methods
+    # =========================================================================
+    # Note: Decorator methods (tool, resource, prompt, add_tool, add_resource,
+    # add_template, add_prompt) are provided by mixin classes:
+    # - ToolDecoratorMixin
+    # - ResourceDecoratorMixin
+    # - PromptDecoratorMixin
diff --git a/fastmcp_slim/fastmcp/server/providers/openapi/README.md b/fastmcp_slim/fastmcp/server/providers/openapi/README.md
new file mode 100644
index 0000000..8c5e890
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/openapi/README.md
@@ -0,0 +1,266 @@
+# OpenAPI Server Implementation (New)
+
+This directory contains the next-generation FastMCP server implementation for OpenAPI integration, designed to replace the legacy implementation in `/server/openapi.py`.
+
+## Architecture Overview
+
+The new implementation uses a **stateless request building approach** with `openapi-core` and `RequestDirector`, providing zero-latency startup and robust OpenAPI support optimized for serverless environments.
+
+### Core Components
+
+1. **`server.py`** - `FastMCPOpenAPI` main server class with RequestDirector integration
+2. **`components.py`** - Simplified component implementations using RequestDirector
+3. **`routing.py`** - Route mapping and component selection logic
+
+### Key Architecture Principles
+
+#### 1. Stateless Performance
+- **Zero Startup Latency**: No code generation or heavy initialization
+- **RequestDirector**: Stateless HTTP request building using openapi-core
+- **Pre-calculated Schemas**: All complex processing done during parsing
+
+#### 2. Unified Implementation
+- **Single Code Path**: All components use RequestDirector consistently
+- **No Fallbacks**: Simplified architecture without hybrid complexity
+- **Performance First**: Optimized for cold starts and serverless deployments
+
+#### 3. OpenAPI Compliance
+- **openapi-core Integration**: Leverages proven library for parameter serialization
+- **Full Feature Support**: Complete OpenAPI 3.0/3.1 support including deepObject
+- **Error Handling**: Comprehensive HTTP error mapping to MCP errors
+
+## Component Classes
+
+### RequestDirector-Based Components
+
+#### `OpenAPITool`
+- Executes operations using RequestDirector for HTTP request building
+- Automatic parameter validation and OpenAPI-compliant serialization
+- Built-in error handling and structured response processing
+- **Advantages**: Zero latency, robust, comprehensive OpenAPI support
+
+#### `OpenAPIResource` / `OpenAPIResourceTemplate`  
+- Provides resource access using RequestDirector
+- Consistent parameter handling across all resource types
+- Support for complex parameter patterns and collision resolution
+- **Advantages**: High performance, simplified architecture, reliable error handling
+
+## Server Implementation
+
+### `FastMCPOpenAPI` Class
+
+The main server class orchestrates the stateless request building approach:
+
+```python
+class FastMCPOpenAPI(FastMCP):
+    def __init__(self, openapi_spec: dict, client: httpx.AsyncClient, **kwargs):
+        # 1. Parse OpenAPI spec to HTTP routes with pre-calculated schemas
+        self._routes = parse_openapi_to_http_routes(openapi_spec)
+        
+        # 2. Initialize RequestDirector with openapi-core Spec
+        self._spec = Spec.from_dict(openapi_spec)
+        self._director = RequestDirector(self._spec)
+            
+        # 3. Create components using RequestDirector
+        self._create_components()
+```
+
+### Component Creation Logic
+
+```python
+def _create_tool(self, route: HTTPRoute) -> Tool:
+    # All tools use RequestDirector for consistent, high-performance request building
+    return OpenAPITool(
+        client=self._client, 
+        route=route, 
+        director=self._director,
+        name=tool_name,
+        description=description,
+        parameters=flat_param_schema
+    )
+```
+
+## Data Flow
+
+### Stateless Request Building
+
+```
+OpenAPI Spec → HTTPRoute with Pre-calculated Fields → RequestDirector → HTTP Request → Structured Response
+```
+
+1. **Spec Parsing**: OpenAPI spec parsed to `HTTPRoute` models with pre-calculated schemas
+2. **RequestDirector Setup**: openapi-core Spec initialized for request building
+3. **Component Creation**: Create components with RequestDirector reference
+4. **Request Building**: RequestDirector builds HTTP request from flat parameters
+5. **Request Execution**: Execute request with httpx client
+6. **Response Processing**: Return structured MCP response
+
+## Key Features
+
+### 1. Enhanced Parameter Handling
+
+#### Parameter Collision Resolution
+- **Automatic Suffixing**: Colliding parameters get location-based suffixes
+- **Example**: `id` in path and body becomes `id__path` and `id`
+- **Transparent**: LLMs see suffixed parameters, implementation routes correctly
+
+#### DeepObject Style Support
+- **Native Support**: Generated client handles all deepObject variations
+- **Explode Handling**: Proper support for explode=true/false
+- **Complex Objects**: Nested object serialization works correctly
+
+### 2. Robust Error Handling
+
+#### HTTP Error Mapping
+- **Status Code Mapping**: HTTP errors mapped to appropriate MCP errors
+- **Structured Responses**: Error details preserved in tool results
+- **Timeout Handling**: Network timeouts handled gracefully
+
+#### Request Building Error Handling
+- **Parameter Validation**: Invalid parameters caught during request building
+- **Schema Validation**: openapi-core validates all OpenAPI constraints
+- **Graceful Degradation**: Missing optional parameters handled smoothly
+
+### 3. Performance Optimizations
+
+#### Efficient Client Reuse
+- **Connection Pooling**: HTTP connections reused across requests
+- **Client Caching**: Generated clients cached for performance
+- **Async Support**: Full async/await throughout
+
+#### Request Optimization
+- **Pre-calculated Schemas**: All complex processing done during initialization
+- **Parameter Mapping**: Collision resolution handled upfront
+- **Zero Latency**: No runtime code generation or complex schema processing
+
+## Configuration
+
+### Server Options
+
+```python
+server = FastMCPOpenAPI(
+    openapi_spec=spec,           # Required: OpenAPI specification
+    client=httpx_client,         # Required: HTTP client instance
+    name="API Server",           # Optional: Server name
+    route_map=custom_routes,     # Optional: Custom route mappings
+    enable_caching=True,         # Optional: Enable response caching
+)
+```
+
+### Route Mapping Customization
+
+```python
+from fastmcp.server.openapi_new.routing import RouteMap
+
+custom_routes = RouteMap({
+    "GET:/users": "tool",        # Force specific operations to be tools
+    "GET:/status": "resource",   # Force specific operations to be resources
+})
+```
+
+## Testing Strategy
+
+### Test Structure
+
+Tests are organized by functionality:
+- `test_server.py` - Server integration and RequestDirector behavior
+- `test_parameter_collisions.py` - Parameter collision handling
+- `test_deepobject_style.py` - DeepObject parameter style support
+- `test_openapi_features.py` - General OpenAPI feature compliance
+
+### Testing Philosophy
+
+1. **Real Integration**: Test with real OpenAPI specs and HTTP clients
+2. **Minimal Mocking**: Only mock external API endpoints
+3. **Behavioral Focus**: Test behavior, not implementation details
+4. **Performance Focus**: Test that initialization is fast and stateless
+
+### Example Test Pattern
+
+```python
+async def test_stateless_request_building():
+    """Test that server works with stateless RequestDirector approach."""
+    
+    # Test server initialization is fast
+    start_time = time.time()
+    server = FastMCPOpenAPI(spec=valid_spec, client=client)
+    init_time = time.time() - start_time
+    assert init_time < 0.01  # Should be very fast
+    
+    # Verify RequestDirector functionality
+    assert hasattr(server, '_director')
+    assert hasattr(server, '_spec')
+```
+
+## Migration Benefits
+
+### From Legacy Implementation
+
+1. **Eliminated Startup Latency**: Zero code generation overhead (100-200ms improvement)
+2. **Better OpenAPI Compliance**: openapi-core handles all OpenAPI features correctly
+3. **Serverless Friendly**: Perfect for cold-start environments
+4. **Simplified Architecture**: Single RequestDirector approach eliminates complexity
+5. **Enhanced Reliability**: No dynamic code generation failures
+
+### Backward Compatibility
+
+- **Same Interface**: Public API unchanged from legacy implementation
+- **Performance Improvement**: Significantly faster initialization
+- **No Breaking Changes**: Existing code works without modification
+
+## Monitoring and Debugging
+
+### Logging
+
+```python
+# Enable debug logging to see implementation choices
+import logging
+logging.getLogger("fastmcp.server.openapi_new").setLevel(logging.DEBUG)
+```
+
+### Key Log Messages
+- **RequestDirector Initialization**: Success/failure of RequestDirector setup
+- **Schema Pre-calculation**: Pre-calculated schema and parameter map status
+- **Request Building**: Parameter mapping and URL construction details
+- **Performance Metrics**: Request timing and error rates
+
+### Debugging Common Issues
+
+1. **RequestDirector Initialization Fails**
+   - Check OpenAPI spec validity with `openapi-core`
+   - Verify spec format is correct JSON/YAML
+   - Ensure all required OpenAPI fields are present
+
+2. **Parameter Issues**
+   - Enable debug logging for parameter processing
+   - Check for parameter collision warnings
+   - Verify OpenAPI spec parameter definitions
+
+3. **Performance Issues**
+   - Monitor RequestDirector request building timing
+   - Check HTTP client configuration
+   - Review response processing timing
+
+## Future Enhancements
+
+### Planned Features
+
+1. **Advanced Caching**: Intelligent response caching with TTL
+2. **Streaming Support**: Handle streaming API responses
+3. **Batch Operations**: Optimize multiple operation calls
+4. **Enhanced Monitoring**: Detailed metrics and health checks
+5. **Configuration Management**: Dynamic configuration updates
+
+### Performance Improvements
+
+1. **Enhanced Schema Caching**: More aggressive schema pre-calculation
+2. **Parallel Processing**: Concurrent operation execution
+3. **Memory Optimization**: Further reduce memory footprint
+4. **Request Optimization**: Smart request batching and deduplication
+
+## Related Documentation
+
+- `/utilities/openapi_new/README.md` - Utility implementation details
+- `/server/openapi/README.md` - Legacy implementation reference
+- `/tests/server/openapi_new/` - Comprehensive test suite
+- Project documentation on OpenAPI integration patterns
\ No newline at end of file
diff --git a/fastmcp_slim/fastmcp/server/providers/openapi/__init__.py b/fastmcp_slim/fastmcp/server/providers/openapi/__init__.py
new file mode 100644
index 0000000..3cbdde5
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/openapi/__init__.py
@@ -0,0 +1,39 @@
+"""OpenAPI provider for FastMCP.
+
+This module provides OpenAPI integration for FastMCP through the Provider pattern.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.providers.openapi import OpenAPIProvider
+    import httpx
+
+    client = httpx.AsyncClient(base_url="https://api.example.com")
+    provider = OpenAPIProvider(openapi_spec=spec, client=client)
+    mcp = FastMCP("API Server", providers=[provider])
+    ```
+"""
+
+from fastmcp.server.providers.openapi.components import (
+    OpenAPIResource,
+    OpenAPIResourceTemplate,
+    OpenAPITool,
+)
+from fastmcp.server.providers.openapi.provider import OpenAPIProvider
+from fastmcp.server.providers.openapi.routing import (
+    ComponentFn,
+    MCPType,
+    RouteMap,
+    RouteMapFn,
+)
+
+__all__ = [
+    "ComponentFn",
+    "MCPType",
+    "OpenAPIProvider",
+    "OpenAPIResource",
+    "OpenAPIResourceTemplate",
+    "OpenAPITool",
+    "RouteMap",
+    "RouteMapFn",
+]
diff --git a/fastmcp_slim/fastmcp/server/providers/openapi/components.py b/fastmcp_slim/fastmcp/server/providers/openapi/components.py
new file mode 100644
index 0000000..45b493c
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/openapi/components.py
@@ -0,0 +1,411 @@
+"""OpenAPI component classes: Tool, Resource, and ResourceTemplate."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import TYPE_CHECKING, Any
+
+import httpx
+from mcp_types import ToolAnnotations
+from pydantic.networks import AnyUrl
+
+from fastmcp.resources import (
+    Resource,
+    ResourceContent,
+    ResourceResult,
+    ResourceTemplate,
+)
+from fastmcp.server.dependencies import get_http_headers
+from fastmcp.server.tasks.config import TaskConfig
+from fastmcp.tools.base import Tool, ToolResult
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.openapi import HTTPRoute
+from fastmcp.utilities.openapi.director import RequestDirector
+
+if TYPE_CHECKING:
+    from fastmcp.server import Context
+
+_SAFE_HEADERS = frozenset(
+    {
+        "accept",
+        "accept-encoding",
+        "accept-language",
+        "cache-control",
+        "connection",
+        "content-length",
+        "content-type",
+        "host",
+        "user-agent",
+    }
+)
+
+
+def _redact_headers(headers: httpx.Headers) -> dict[str, str]:
+    return {k: v if k.lower() in _SAFE_HEADERS else "***" for k, v in headers.items()}
+
+
+__all__ = [
+    "OpenAPIResource",
+    "OpenAPIResourceTemplate",
+    "OpenAPITool",
+    "_extract_mime_type_from_route",
+]
+
+logger = get_logger(__name__)
+
+# Default MIME type when no response content type can be inferred
+_DEFAULT_MIME_TYPE = "application/json"
+
+
+def _extract_mime_type_from_route(route: HTTPRoute) -> str:
+    """Extract the primary MIME type from an HTTPRoute's response definitions.
+
+    Looks for the first successful response (2xx) and returns its content type.
+    Prefers JSON-compatible types when multiple are available.
+    Falls back to "application/json" when no response content type is declared.
+    """
+    if not route.responses:
+        return _DEFAULT_MIME_TYPE
+
+    # Priority order for success status codes
+    success_codes = ["200", "201", "202", "204"]
+
+    response_info = None
+    for status_code in success_codes:
+        if status_code in route.responses:
+            response_info = route.responses[status_code]
+            break
+
+    # If no explicit success codes, try any 2xx response
+    if response_info is None:
+        for status_code, resp_info in route.responses.items():
+            if status_code.startswith("2"):
+                response_info = resp_info
+                break
+
+    if response_info is None or not response_info.content_schema:
+        return _DEFAULT_MIME_TYPE
+
+    # If there's only one content type, use it directly
+    content_types = list(response_info.content_schema.keys())
+    if len(content_types) == 1:
+        return content_types[0]
+
+    # When multiple types exist, prefer JSON-compatible types
+    json_compatible_types = [
+        "application/json",
+        "application/vnd.api+json",
+        "application/hal+json",
+        "application/ld+json",
+        "text/json",
+    ]
+    for ct in json_compatible_types:
+        if ct in response_info.content_schema:
+            return ct
+
+    # Fall back to the first available content type
+    return content_types[0]
+
+
+def _slugify(text: str) -> str:
+    """Convert text to a URL-friendly slug format.
+
+    Only contains lowercase letters, uppercase letters, numbers, and underscores.
+    """
+    if not text:
+        return ""
+
+    # Replace spaces and common separators with underscores
+    slug = re.sub(r"[\s\-\.]+", "_", text)
+
+    # Remove non-alphanumeric characters except underscores
+    slug = re.sub(r"[^a-zA-Z0-9_]", "", slug)
+
+    # Remove multiple consecutive underscores
+    slug = re.sub(r"_+", "_", slug)
+
+    # Remove leading/trailing underscores
+    slug = slug.strip("_")
+
+    return slug
+
+
+class OpenAPITool(Tool):
+    """Tool implementation for OpenAPI endpoints."""
+
+    task_config: TaskConfig = TaskConfig(mode="forbidden")
+
+    def __init__(
+        self,
+        client: httpx.AsyncClient,
+        route: HTTPRoute,
+        director: RequestDirector,
+        name: str,
+        description: str,
+        parameters: dict[str, Any],
+        output_schema: dict[str, Any] | None = None,
+        tags: set[str] | None = None,
+        annotations: ToolAnnotations | None = None,
+    ):
+        super().__init__(
+            name=name,
+            description=description,
+            parameters=parameters,
+            output_schema=output_schema,
+            tags=tags or set(),
+            annotations=annotations,
+        )
+        self._client = client
+        self._route = route
+        self._director = director
+
+    def __repr__(self) -> str:
+        return f"OpenAPITool(name={self.name!r}, method={self._route.method}, path={self._route.path})"
+
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
+        """Execute the HTTP request using RequestDirector."""
+        # Build the request — errors here are programming/schema issues,
+        # not HTTP failures, so we catch them separately.
+        try:
+            base_url = str(self._client.base_url) or "http://localhost"
+            request = self._director.build(self._route, arguments, base_url)
+
+            if self._client.headers:
+                for key, value in self._client.headers.items():
+                    if key not in request.headers:
+                        request.headers[key] = value
+
+            mcp_headers = get_http_headers()
+            if mcp_headers:
+                for key, value in mcp_headers.items():
+                    if key not in request.headers:
+                        request.headers[key] = value
+        except Exception as e:
+            raise ValueError(
+                f"Error building request for {self._route.method.upper()} "
+                f"{self._route.path}: {type(e).__name__}: {e}"
+            ) from e
+
+        # Send the request and process the response.
+        try:
+            logger.debug(
+                f"run - sending request; headers: {_redact_headers(request.headers)}"
+            )
+
+            response = await self._client.send(request)
+            response.raise_for_status()
+
+            # Try to parse as JSON first
+            try:
+                result = response.json()
+
+                # Handle structured content based on output schema
+                if self.output_schema is not None:
+                    if self.output_schema.get("x-fastmcp-wrap-result"):
+                        structured_output = {"result": result}
+                    else:
+                        structured_output = result
+                elif not isinstance(result, dict):
+                    structured_output = {"result": result}
+                else:
+                    structured_output = result
+
+                # Structured content must be a dict for the MCP protocol.
+                # Wrap non-dict values that slipped through (e.g. a backend
+                # returning an array when the schema declared an object).
+                if not isinstance(structured_output, dict):
+                    structured_output = {"result": structured_output}
+
+                return ToolResult(structured_content=structured_output)
+            except json.JSONDecodeError:
+                return ToolResult(content=response.text)
+
+        except httpx.HTTPStatusError as e:
+            error_message = (
+                f"HTTP error {e.response.status_code}: {e.response.reason_phrase}"
+            )
+            try:
+                error_data = e.response.json()
+                error_message += f" - {error_data}"
+            except (json.JSONDecodeError, ValueError):
+                if e.response.text:
+                    error_message += f" - {e.response.text}"
+            raise ValueError(error_message) from e
+
+        except httpx.TimeoutException as e:
+            raise ValueError(f"HTTP request timed out ({type(e).__name__})") from e
+
+        except httpx.RequestError as e:
+            raise ValueError(f"Request error ({type(e).__name__}): {e!s}") from e
+
+
+class OpenAPIResource(Resource):
+    """Resource implementation for OpenAPI endpoints."""
+
+    task_config: TaskConfig = TaskConfig(mode="forbidden")
+
+    def __init__(
+        self,
+        client: httpx.AsyncClient,
+        route: HTTPRoute,
+        director: RequestDirector,
+        uri: str,
+        name: str,
+        description: str,
+        mime_type: str = "application/json",
+        tags: set[str] | None = None,
+        arguments: dict[str, Any] | None = None,
+    ):
+        super().__init__(
+            uri=AnyUrl(uri),
+            name=name,
+            description=description,
+            mime_type=mime_type,
+            tags=tags or set(),
+        )
+        self._client = client
+        self._route = route
+        self._director = director
+        self._arguments = dict(arguments or {})
+
+    def __repr__(self) -> str:
+        return f"OpenAPIResource(name={self.name!r}, uri={self.uri!r}, path={self._route.path})"
+
+    async def read(self) -> ResourceResult:
+        """Fetch the resource data by making an HTTP request."""
+        try:
+            base_url = str(self._client.base_url) or "http://localhost"
+            directed_request = self._director.build(
+                self._route, self._arguments, base_url
+            )
+            request = self._client.build_request(
+                method=directed_request.method,
+                url=directed_request.url.copy_with(query=None),
+                params=directed_request.url.params,
+                headers=directed_request.headers,
+                content=directed_request.content,
+                extensions=directed_request.extensions,
+            )
+            mcp_headers = get_http_headers()
+            if mcp_headers:
+                request.headers.update(mcp_headers)
+
+            response = await self._client.send(request)
+            response.raise_for_status()
+
+            content_type = response.headers.get("content-type", "").lower()
+
+            if "application/json" in content_type:
+                result = response.json()
+                return ResourceResult(
+                    contents=[
+                        ResourceContent(
+                            content=json.dumps(result), mime_type="application/json"
+                        )
+                    ]
+                )
+            elif any(ct in content_type for ct in ["text/", "application/xml"]):
+                return ResourceResult(
+                    contents=[
+                        ResourceContent(content=response.text, mime_type=self.mime_type)
+                    ]
+                )
+            else:
+                return ResourceResult(
+                    contents=[
+                        ResourceContent(
+                            content=response.content, mime_type=self.mime_type
+                        )
+                    ]
+                )
+
+        except httpx.HTTPStatusError as e:
+            error_message = (
+                f"HTTP error {e.response.status_code}: {e.response.reason_phrase}"
+            )
+            try:
+                error_data = e.response.json()
+                error_message += f" - {error_data}"
+            except (json.JSONDecodeError, ValueError):
+                if e.response.text:
+                    error_message += f" - {e.response.text}"
+            raise ValueError(error_message) from e
+
+        except httpx.TimeoutException as e:
+            raise ValueError(f"HTTP request timed out ({type(e).__name__})") from e
+
+        except httpx.RequestError as e:
+            raise ValueError(f"Request error ({type(e).__name__}): {e!s}") from e
+
+
+def _path_argument_name(route: HTTPRoute, parameter_name: str) -> str:
+    for argument_name, mapping in route.parameter_map.items():
+        if mapping["location"] == "path" and mapping["openapi_name"] == parameter_name:
+            return argument_name
+    return parameter_name
+
+
+class OpenAPIResourceTemplate(ResourceTemplate):
+    """Resource template implementation for OpenAPI endpoints."""
+
+    task_config: TaskConfig = TaskConfig(mode="forbidden")
+
+    def __init__(
+        self,
+        client: httpx.AsyncClient,
+        route: HTTPRoute,
+        director: RequestDirector,
+        uri_template: str,
+        name: str,
+        description: str,
+        parameters: dict[str, Any],
+        tags: set[str] | None = None,
+        mime_type: str = _DEFAULT_MIME_TYPE,
+    ):
+        super().__init__(
+            uri_template=uri_template,
+            name=name,
+            description=description,
+            parameters=parameters,
+            tags=tags or set(),
+            mime_type=mime_type,
+        )
+        self._client = client
+        self._route = route
+        self._director = director
+
+    def __repr__(self) -> str:
+        return f"OpenAPIResourceTemplate(name={self.name!r}, uri_template={self.uri_template!r}, path={self._route.path})"
+
+    async def create_resource(
+        self,
+        uri: str,
+        params: dict[str, Any],
+        context: Context | None = None,
+    ) -> Resource:
+        """Create a resource with the given parameters."""
+        uri_parts = [f"{key}={value}" for key, value in params.items()]
+        arguments = {}
+        for parameter in self._route.parameters:
+            if parameter.location != "path":
+                continue
+            argument_name = _path_argument_name(self._route, parameter.name)
+            if parameter.name in params:
+                arguments[argument_name] = params[parameter.name]
+                continue
+            normalized_name = parameter.name.replace("-", "_")
+            if normalized_name in params:
+                arguments[argument_name] = params[normalized_name]
+
+        return OpenAPIResource(
+            client=self._client,
+            route=self._route,
+            director=self._director,
+            uri=uri,
+            name=f"{self.name}-{'-'.join(uri_parts)}",
+            description=self.description or f"Resource for {self._route.path}",
+            mime_type=self.mime_type,
+            tags=set(self._route.tags or []),
+            arguments=arguments,
+        )
diff --git a/fastmcp_slim/fastmcp/server/providers/openapi/provider.py b/fastmcp_slim/fastmcp/server/providers/openapi/provider.py
new file mode 100644
index 0000000..72e811d
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/openapi/provider.py
@@ -0,0 +1,436 @@
+"""OpenAPIProvider for creating MCP components from OpenAPI specifications."""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import AsyncIterator, Sequence
+from contextlib import asynccontextmanager
+from typing import Any, Literal, cast
+
+import httpx
+from jsonschema_path import SchemaPath
+
+from fastmcp.prompts import Prompt
+from fastmcp.resources import Resource, ResourceTemplate
+from fastmcp.server.providers.base import Provider
+from fastmcp.server.providers.openapi.components import (
+    OpenAPIResource,
+    OpenAPIResourceTemplate,
+    OpenAPITool,
+    _extract_mime_type_from_route,
+    _slugify,
+)
+from fastmcp.server.providers.openapi.routing import (
+    DEFAULT_ROUTE_MAPPINGS,
+    ComponentFn,
+    MCPType,
+    RouteMap,
+    RouteMapFn,
+    _determine_route_type,
+)
+from fastmcp.tools.base import Tool
+from fastmcp.utilities.components import FastMCPComponent
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.openapi import (
+    HTTPRoute,
+    extract_output_schema_from_responses,
+    parse_openapi_to_http_routes,
+)
+from fastmcp.utilities.openapi.director import RequestDirector
+from fastmcp.utilities.versions import VersionSpec, version_sort_key
+
+__all__ = [
+    "OpenAPIProvider",
+]
+
+logger = get_logger(__name__)
+
+DEFAULT_TIMEOUT: float = 30.0
+
+
+class OpenAPIProvider(Provider):
+    """Provider that creates MCP components from an OpenAPI specification.
+
+    Components are created eagerly during initialization by parsing the OpenAPI
+    spec. Each component makes HTTP calls to the described API endpoints.
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.providers.openapi import OpenAPIProvider
+        import httpx
+
+        client = httpx.AsyncClient(base_url="https://api.example.com")
+        provider = OpenAPIProvider(openapi_spec=spec, client=client)
+
+        mcp = FastMCP("API Server")
+        mcp.add_provider(provider)
+        ```
+    """
+
+    def __init__(
+        self,
+        openapi_spec: dict[str, Any],
+        client: httpx.AsyncClient | None = None,
+        *,
+        route_maps: list[RouteMap] | None = None,
+        route_map_fn: RouteMapFn | None = None,
+        mcp_component_fn: ComponentFn | None = None,
+        mcp_names: dict[str, str] | None = None,
+        tags: set[str] | None = None,
+        validate_output: bool = True,
+    ):
+        """Initialize provider by parsing OpenAPI spec and creating components.
+
+        Args:
+            openapi_spec: OpenAPI schema as a dictionary
+            client: Optional httpx AsyncClient for making HTTP requests.
+                If not provided, a default client is created using the first
+                server URL from the OpenAPI spec with a 30-second timeout.
+                To customize timeout or other settings, pass your own client.
+            route_maps: Optional list of RouteMap objects defining route mappings
+            route_map_fn: Optional callable for advanced route type mapping
+            mcp_component_fn: Optional callable for component customization
+            mcp_names: Optional dictionary mapping operationId to component names
+            tags: Optional set of tags to add to all components
+            validate_output: If True (default), tools use the output schema
+                extracted from the OpenAPI spec for response validation. If
+                False, a permissive schema is used instead, allowing any
+                response structure while still returning structured JSON.
+        """
+        super().__init__()
+
+        self._owns_client = client is None
+        if client is None:
+            client = self._create_default_client(openapi_spec)
+        self._client = client
+        self._mcp_component_fn = mcp_component_fn
+        self._validate_output = validate_output
+
+        # Keep track of names to detect collisions
+        self._used_names: dict[str, Counter[str]] = {
+            "tool": Counter(),
+            "resource": Counter(),
+            "resource_template": Counter(),
+            "prompt": Counter(),
+        }
+
+        # Pre-created component storage
+        self._tools: dict[str, OpenAPITool] = {}
+        self._resources: dict[str, OpenAPIResource] = {}
+        self._templates: dict[str, OpenAPIResourceTemplate] = {}
+
+        # Create openapi-core Spec and RequestDirector
+        try:
+            self._spec = SchemaPath.from_dict(cast(Any, openapi_spec))
+            self._director = RequestDirector(self._spec)
+        except Exception as e:
+            logger.exception("Failed to initialize RequestDirector")
+            raise ValueError(f"Invalid OpenAPI specification: {e}") from e
+
+        http_routes = parse_openapi_to_http_routes(openapi_spec)
+
+        # Process routes
+        route_maps = (route_maps or []) + DEFAULT_ROUTE_MAPPINGS
+        for route in http_routes:
+            route_map = _determine_route_type(route, route_maps)
+            route_type = route_map.mcp_type
+
+            if route_map_fn is not None:
+                try:
+                    result = route_map_fn(route, route_type)
+                    if result is not None:
+                        route_type = result
+                        logger.debug(
+                            f"Route {route.method} {route.path} mapping customized: "
+                            f"type={route_type.name}"
+                        )
+                except Exception as e:
+                    logger.warning(
+                        f"Error in route_map_fn for {route.method} {route.path}: {e}. "
+                        f"Using default values."
+                    )
+
+            component_name = self._generate_default_name(route, mcp_names)
+            route_tags = set(route.tags) | route_map.mcp_tags | (tags or set())
+
+            if route_type == MCPType.TOOL:
+                self._create_openapi_tool(route, component_name, tags=route_tags)
+            elif route_type == MCPType.RESOURCE:
+                self._create_openapi_resource(route, component_name, tags=route_tags)
+            elif route_type == MCPType.RESOURCE_TEMPLATE:
+                self._create_openapi_template(route, component_name, tags=route_tags)
+            elif route_type == MCPType.EXCLUDE:
+                logger.debug(f"Excluding route: {route.method} {route.path}")
+
+        logger.debug(f"Created OpenAPIProvider with {len(http_routes)} routes")
+
+    @classmethod
+    def _create_default_client(cls, openapi_spec: dict[str, Any]) -> httpx.AsyncClient:
+        """Create a default httpx client from the OpenAPI spec's server URL."""
+        servers = openapi_spec.get("servers", [])
+        if not servers or not servers[0].get("url"):
+            raise ValueError(
+                "No server URL found in OpenAPI spec. Either add a 'servers' "
+                "entry to the spec or provide an httpx.AsyncClient explicitly."
+            )
+        base_url = servers[0]["url"]
+        variables = servers[0].get("variables", {})
+        for name, var in variables.items():
+            base_url = base_url.replace(f"{{{name}}}", var.get("default", ""))
+        return httpx.AsyncClient(base_url=base_url, timeout=DEFAULT_TIMEOUT)
+
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncIterator[None]:
+        """Manage the lifecycle of the auto-created httpx client."""
+        if self._owns_client:
+            async with self._client:
+                yield
+        else:
+            yield
+
+    def _generate_default_name(
+        self, route: HTTPRoute, mcp_names_map: dict[str, str] | None = None
+    ) -> str:
+        """Generate a default name from the route."""
+        mcp_names_map = mcp_names_map or {}
+
+        if route.operation_id:
+            if route.operation_id in mcp_names_map:
+                name = mcp_names_map[route.operation_id]
+            else:
+                name = route.operation_id.split("__")[0]
+        else:
+            name = route.summary or f"{route.method}_{route.path}"
+
+        name = _slugify(name)
+
+        if len(name) > 56:
+            name = name[:56]
+
+        return name
+
+    def _get_unique_name(
+        self,
+        name: str,
+        component_type: Literal["tool", "resource", "resource_template", "prompt"],
+    ) -> str:
+        """Ensure the name is unique by appending numbers if needed."""
+        self._used_names[component_type][name] += 1
+        if self._used_names[component_type][name] == 1:
+            return name
+
+        new_name = f"{name}_{self._used_names[component_type][name]}"
+        logger.debug(
+            f"Name collision: '{name}' exists as {component_type}. Using '{new_name}'."
+        )
+        return new_name
+
+    def _create_openapi_tool(
+        self,
+        route: HTTPRoute,
+        name: str,
+        tags: set[str],
+    ) -> None:
+        """Create and register an OpenAPITool."""
+        combined_schema = route.flat_param_schema
+        output_schema = extract_output_schema_from_responses(
+            route.responses,
+            route.response_schemas,
+            route.openapi_version,
+        )
+
+        if not self._validate_output and output_schema is not None:
+            # Use a permissive schema that accepts any object, preserving
+            # the wrap-result flag so non-object responses still get wrapped
+            permissive: dict[str, Any] = {
+                "type": "object",
+                "additionalProperties": True,
+            }
+            if output_schema.get("x-fastmcp-wrap-result"):
+                permissive["x-fastmcp-wrap-result"] = True
+            output_schema = permissive
+
+        tool_name = self._get_unique_name(name, "tool")
+        base_description = (
+            route.description
+            or route.summary
+            or f"Executes {route.method} {route.path}"
+        )
+
+        tool = OpenAPITool(
+            client=self._client,
+            route=route,
+            director=self._director,
+            name=tool_name,
+            description=base_description,
+            parameters=combined_schema,
+            output_schema=output_schema,
+            tags=set(route.tags or []) | tags,
+        )
+
+        if self._mcp_component_fn is not None:
+            try:
+                self._mcp_component_fn(route, tool)
+                logger.debug(f"Tool {tool_name} customized by component_fn")
+            except Exception as e:
+                logger.warning(f"Error in component_fn for tool {tool_name}: {e}")
+
+        self._tools[tool.name] = tool
+
+    def _create_openapi_resource(
+        self,
+        route: HTTPRoute,
+        name: str,
+        tags: set[str],
+    ) -> None:
+        """Create and register an OpenAPIResource."""
+        resource_name = self._get_unique_name(name, "resource")
+        resource_uri = f"resource://{resource_name}"
+        base_description = (
+            route.description or route.summary or f"Represents {route.path}"
+        )
+
+        resource = OpenAPIResource(
+            client=self._client,
+            route=route,
+            director=self._director,
+            uri=resource_uri,
+            name=resource_name,
+            description=base_description,
+            mime_type=_extract_mime_type_from_route(route),
+            tags=set(route.tags or []) | tags,
+        )
+
+        if self._mcp_component_fn is not None:
+            try:
+                self._mcp_component_fn(route, resource)
+                logger.debug(f"Resource {resource_uri} customized by component_fn")
+            except Exception as e:
+                logger.warning(
+                    f"Error in component_fn for resource {resource_uri}: {e}"
+                )
+
+        self._resources[str(resource.uri)] = resource
+
+    def _create_openapi_template(
+        self,
+        route: HTTPRoute,
+        name: str,
+        tags: set[str],
+    ) -> None:
+        """Create and register an OpenAPIResourceTemplate."""
+        template_name = self._get_unique_name(name, "resource_template")
+
+        path_params = sorted(p.name for p in route.parameters if p.location == "path")
+        uri_template_str = f"resource://{template_name}"
+        if path_params:
+            uri_template_str += "/" + "/".join(f"{{{p}}}" for p in path_params)
+
+        base_description = (
+            route.description or route.summary or f"Template for {route.path}"
+        )
+
+        template_params_schema = {
+            "type": "object",
+            "properties": {
+                p.name: {
+                    **(p.schema_.copy() if isinstance(p.schema_, dict) else {}),
+                    **(
+                        {"description": p.description}
+                        if p.description
+                        and not (
+                            isinstance(p.schema_, dict) and "description" in p.schema_
+                        )
+                        else {}
+                    ),
+                }
+                for p in route.parameters
+                if p.location == "path"
+            },
+            "required": [
+                p.name for p in route.parameters if p.location == "path" and p.required
+            ],
+        }
+
+        template = OpenAPIResourceTemplate(
+            client=self._client,
+            route=route,
+            director=self._director,
+            uri_template=uri_template_str,
+            name=template_name,
+            description=base_description,
+            parameters=template_params_schema,
+            tags=set(route.tags or []) | tags,
+            mime_type=_extract_mime_type_from_route(route),
+        )
+
+        if self._mcp_component_fn is not None:
+            try:
+                self._mcp_component_fn(route, template)
+                logger.debug(f"Template {uri_template_str} customized by component_fn")
+            except Exception as e:
+                logger.warning(
+                    f"Error in component_fn for template {uri_template_str}: {e}"
+                )
+
+        self._templates[template.uri_template] = template
+
+    # -------------------------------------------------------------------------
+    # Provider interface
+    # -------------------------------------------------------------------------
+
+    async def _list_tools(self) -> Sequence[Tool]:
+        """Return all tools created from the OpenAPI spec."""
+        return list(self._tools.values())
+
+    async def _get_tool(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get a tool by name."""
+        tool = self._tools.get(name)
+        if tool is None:
+            return None
+        if version is not None and not version.matches(tool.version):
+            return None
+        return tool
+
+    async def _list_resources(self) -> Sequence[Resource]:
+        """Return all resources created from the OpenAPI spec."""
+        return list(self._resources.values())
+
+    async def _get_resource(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> Resource | None:
+        """Get a resource by URI."""
+        resource = self._resources.get(uri)
+        if resource is None:
+            return None
+        if version is not None and not version.matches(resource.version):
+            return None
+        return resource
+
+    async def _list_resource_templates(self) -> Sequence[ResourceTemplate]:
+        """Return all resource templates created from the OpenAPI spec."""
+        return list(self._templates.values())
+
+    async def _get_resource_template(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> ResourceTemplate | None:
+        """Get a resource template that matches the given URI."""
+        matching = [t for t in self._templates.values() if t.matches(uri) is not None]
+        if not matching:
+            return None
+        if version is not None:
+            matching = [t for t in matching if version.matches(t.version)]
+        if not matching:
+            return None
+        return max(matching, key=version_sort_key)
+
+    async def _list_prompts(self) -> Sequence[Prompt]:
+        """Return empty list - OpenAPI doesn't create prompts."""
+        return []
+
+    async def get_tasks(self) -> Sequence[FastMCPComponent]:
+        """Return empty list - OpenAPI components don't support tasks."""
+        return []
diff --git a/fastmcp_slim/fastmcp/server/providers/openapi/routing.py b/fastmcp_slim/fastmcp/server/providers/openapi/routing.py
new file mode 100644
index 0000000..7805f00
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/openapi/routing.py
@@ -0,0 +1,109 @@
+"""Route mapping logic for OpenAPI operations."""
+
+from __future__ import annotations
+
+import enum
+import re
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from re import Pattern
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from fastmcp.server.providers.openapi.components import (
+        OpenAPIResource,
+        OpenAPIResourceTemplate,
+        OpenAPITool,
+    )
+
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.openapi import HttpMethod, HTTPRoute
+
+__all__ = [
+    "ComponentFn",
+    "MCPType",
+    "RouteMap",
+    "RouteMapFn",
+]
+
+logger = get_logger(__name__)
+
+# Type definitions for the mapping functions
+RouteMapFn = Callable[[HTTPRoute, "MCPType"], "MCPType | None"]
+ComponentFn = Callable[
+    [
+        HTTPRoute,
+        "OpenAPITool | OpenAPIResource | OpenAPIResourceTemplate",
+    ],
+    None,
+]
+
+
+class MCPType(enum.Enum):
+    """Type of FastMCP component to create from a route.
+
+    Enum values:
+        TOOL: Convert the route to a callable Tool
+        RESOURCE: Convert the route to a Resource (typically GET endpoints)
+        RESOURCE_TEMPLATE: Convert the route to a ResourceTemplate (typically GET with path params)
+        EXCLUDE: Exclude the route from being converted to any MCP component
+    """
+
+    TOOL = "TOOL"
+    RESOURCE = "RESOURCE"
+    RESOURCE_TEMPLATE = "RESOURCE_TEMPLATE"
+    EXCLUDE = "EXCLUDE"
+
+
+@dataclass(kw_only=True)
+class RouteMap:
+    """Mapping configuration for HTTP routes to FastMCP component types."""
+
+    methods: list[HttpMethod] | Literal["*"] = field(default="*")
+    pattern: Pattern[str] | str = field(default=r".*")
+
+    tags: set[str] = field(
+        default_factory=set,
+        metadata={"description": "A set of tags to match. All tags must match."},
+    )
+    mcp_type: MCPType = field(
+        metadata={"description": "The type of FastMCP component to create."},
+    )
+    mcp_tags: set[str] = field(
+        default_factory=set,
+        metadata={
+            "description": "A set of tags to apply to the generated FastMCP component."
+        },
+    )
+
+
+# Default route mapping: all routes become tools.
+DEFAULT_ROUTE_MAPPINGS = [
+    RouteMap(mcp_type=MCPType.TOOL),
+]
+
+
+def _determine_route_type(
+    route: HTTPRoute,
+    mappings: list[RouteMap],
+) -> RouteMap:
+    """Determine the FastMCP component type based on the route and mappings."""
+    for route_map in mappings:
+        if route_map.methods == "*" or route.method in route_map.methods:
+            if isinstance(route_map.pattern, Pattern):
+                pattern_matches = route_map.pattern.search(route.path)
+            else:
+                pattern_matches = re.search(route_map.pattern, route.path)
+
+            if pattern_matches:
+                if route_map.tags:
+                    route_tags_set = set(route.tags or [])
+                    if not route_map.tags.issubset(route_tags_set):
+                        continue
+
+                logger.debug(
+                    f"Route {route.method} {route.path} mapped to {route_map.mcp_type.name}"
+                )
+                return route_map
+
+    return RouteMap(mcp_type=MCPType.TOOL)
diff --git a/fastmcp_slim/fastmcp/server/providers/prefab_synthesis.py b/fastmcp_slim/fastmcp/server/providers/prefab_synthesis.py
new file mode 100644
index 0000000..2ee639d
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/prefab_synthesis.py
@@ -0,0 +1,247 @@
+"""On-demand Prefab renderer resource synthesis.
+
+Tools marked as Prefab (via ``app=True``, ``PrefabAppConfig``, etc.) carry
+a placeholder ``meta.ui.resourceUri`` and optionally a hash in
+``meta.fastmcp._tool_hash``. This module synthesizes per-tool renderer
+resources on demand at ``list_resources`` and ``read_resource`` time
+without storing or materializing anything.
+
+Each tool's resource URI is ``ui://prefab/tool/<hash>/renderer.html``
+where the hash comes from the tool's own meta (set at registration from
+the app name + tool name). CSP on the resource is the tool's
+``meta.ui.csp`` merged with the renderer defaults across all four
+``*_domains`` fields.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from fastmcp.server.providers.addressing import (
+    HASH_LENGTH,
+    hash_tool,
+    parse_hashed_resource_uri,
+)
+
+if TYPE_CHECKING:
+    from fastmcp.resources.base import Resource
+    from fastmcp.server.server import FastMCP
+    from fastmcp.tools.base import Tool
+
+#: The placeholder URI that decorators stamp on tools needing a renderer.
+PREFAB_PLACEHOLDER_URI = "ui://prefab/renderer.html"
+
+
+def _is_prefab_tool(tool: Tool) -> bool:
+    """True if *tool* was marked as needing a Prefab renderer at registration."""
+    meta = tool.meta
+    if not meta:
+        return False
+    ui = meta.get("ui")
+    if not isinstance(ui, dict):
+        return False
+    return ui.get("resourceUri") == PREFAB_PLACEHOLDER_URI
+
+
+def _get_tool_hash(tool: Tool) -> str | None:
+    """Read the stored hash from tool meta, or compute from app name + tool name."""
+    meta = tool.meta or {}
+    fastmcp_meta = meta.get("fastmcp")
+    if isinstance(fastmcp_meta, dict):
+        h = fastmcp_meta.get("_tool_hash")
+        if isinstance(h, str) and len(h) == HASH_LENGTH:
+            return h
+        # Fall back to computing from app name
+        app = fastmcp_meta.get("app")
+        if isinstance(app, str):
+            return hash_tool(app, tool.name)
+    # Root-level prefab tool (no app name) — hash from empty prefix.
+    return hash_tool("", tool.name)
+
+
+def _merge_domain_lists(
+    base: list[str] | None, extra: list[str] | None
+) -> list[str] | None:
+    if base is None and extra is None:
+        return None
+    combined = list(base or [])
+    for item in extra or []:
+        if item not in combined:
+            combined.append(item)
+    return combined or None
+
+
+def _build_resource_for_tool(tool: Tool) -> Resource | None:
+    """Synthesize a TextResource for a prefab tool. Returns None if prefab_ui isn't installed."""
+    try:
+        from prefab_ui.renderer import get_renderer_csp, get_renderer_html
+    except ImportError:
+        return None
+
+    from fastmcp.apps.config import (
+        UI_MIME_TYPE,
+        AppConfig,
+        ResourceCSP,
+        app_config_to_meta_dict,
+    )
+    from fastmcp.resources.types import TextResource
+
+    tool_hash = _get_tool_hash(tool)
+    if tool_hash is None:
+        return None
+
+    # Merge user CSP with renderer defaults — all four domain fields.
+    defaults: dict[str, Any] = get_renderer_csp() or {}
+    user_csp: dict[str, Any] = {}
+    if tool.meta and isinstance(tool.meta.get("ui"), dict):
+        raw = tool.meta["ui"].get("csp")
+        if isinstance(raw, dict):
+            user_csp = raw
+
+    def _get(d: dict[str, Any], snake: str, camel: str) -> list[str] | None:
+        val = d.get(snake)
+        if val is None:
+            val = d.get(camel)
+        return val if isinstance(val, list) else None
+
+    merged = {
+        "connect_domains": _merge_domain_lists(
+            defaults.get("connect_domains"),
+            _get(user_csp, "connect_domains", "connectDomains"),
+        ),
+        "resource_domains": _merge_domain_lists(
+            defaults.get("resource_domains"),
+            _get(user_csp, "resource_domains", "resourceDomains"),
+        ),
+        "frame_domains": _merge_domain_lists(
+            defaults.get("frame_domains"),
+            _get(user_csp, "frame_domains", "frameDomains"),
+        ),
+        "base_uri_domains": _merge_domain_lists(
+            defaults.get("base_uri_domains"),
+            _get(user_csp, "base_uri_domains", "baseUriDomains"),
+        ),
+    }
+
+    resource_csp = ResourceCSP(**merged) if any(merged.values()) else None
+
+    # Carry permissions from the tool's meta to the resource (same
+    # principle as CSP — belongs on the resource, not the tool).
+    user_permissions = None
+    if tool.meta and isinstance(tool.meta.get("ui"), dict):
+        raw_perms = tool.meta["ui"].get("permissions")
+        if isinstance(raw_perms, dict):
+            from fastmcp.apps.config import ResourcePermissions
+
+            user_permissions = ResourcePermissions(**raw_perms)
+
+    resource_app = AppConfig(
+        csp=resource_csp,
+        permissions=user_permissions,
+    )
+    uri = f"ui://prefab/tool/{tool_hash}/renderer.html"
+
+    return TextResource(
+        uri=uri,  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+        name=f"Prefab Renderer ({tool.name})",
+        text=get_renderer_html(),
+        mime_type=UI_MIME_TYPE,
+        meta={"ui": app_config_to_meta_dict(resource_app)},
+    )
+
+
+def _walk_prefab_tools(server: FastMCP) -> list[Tool]:
+    """Enumerate all prefab tools across the server's providers (sync walk of _components)."""
+    from fastmcp.apps.app import FastMCPApp
+    from fastmcp.server.providers.base import Provider
+    from fastmcp.server.providers.local_provider import LocalProvider
+    from fastmcp.server.providers.wrapped_provider import _WrappedProvider
+    from fastmcp.tools.base import Tool
+
+    results: list[Tool] = []
+
+    def _walk_provider(provider: Provider) -> None:
+        # Unwrap transform wrappers
+        inner = provider
+        while isinstance(inner, _WrappedProvider):
+            inner = inner._inner
+
+        # Extract tools from local storage
+        sources: list[LocalProvider] = []
+        if isinstance(inner, LocalProvider):
+            sources.append(inner)
+        if isinstance(inner, FastMCPApp):
+            sources.append(inner._local)
+        for src in sources:
+            results.extend(
+                component
+                for component in src._components.values()
+                if isinstance(component, Tool) and _is_prefab_tool(component)
+            )
+
+        # Recurse into aggregate children
+        from fastmcp.server.providers.aggregate import AggregateProvider
+        from fastmcp.server.providers.fastmcp_provider import FastMCPProvider
+
+        if isinstance(inner, AggregateProvider):
+            for child in inner.providers:
+                _walk_provider(child)
+        # Recurse into mounted FastMCP servers
+        if isinstance(inner, FastMCPProvider):
+            for child in inner.server.providers:
+                _walk_provider(child)
+
+    for provider in server.providers:
+        _walk_provider(provider)
+
+    return results
+
+
+async def synthesize_prefab_resources(server: FastMCP) -> list[Resource]:
+    """Return fresh synthetic Prefab resources for all prefab tools. Pure."""
+    resources: list[Resource] = []
+    seen_hashes: set[str] = set()
+    for tool in _walk_prefab_tools(server):
+        h = _get_tool_hash(tool)
+        if h is None or h in seen_hashes:
+            continue
+        seen_hashes.add(h)
+        resource = _build_resource_for_tool(tool)
+        if resource is not None:
+            resources.append(resource)
+    return resources
+
+
+async def synthesize_prefab_resource_by_uri(
+    server: FastMCP, uri: str
+) -> Resource | None:
+    """Intercept a Prefab renderer URI and synthesize on demand."""
+    digest = parse_hashed_resource_uri(uri)
+    if digest is None:
+        return None
+    for tool in _walk_prefab_tools(server):
+        if _get_tool_hash(tool) == digest:
+            return _build_resource_for_tool(tool)
+    return None
+
+
+def rewrite_tool_meta_for_wire(tool: Tool) -> Tool:
+    """Return a model_copy with the per-tool URI and CSP stripped.
+
+    Reads the hash from the tool's own meta. If no hash is found,
+    returns the tool unchanged. Produces a fresh copy — the original
+    Tool object is untouched.
+    """
+    if not _is_prefab_tool(tool):
+        return tool
+    tool_hash = _get_tool_hash(tool)
+    if tool_hash is None:
+        return tool
+    assert tool.meta is not None
+    new_ui = dict(tool.meta["ui"])
+    new_ui["resourceUri"] = f"ui://prefab/tool/{tool_hash}/renderer.html"
+    new_ui.pop("csp", None)
+    new_ui.pop("permissions", None)
+    new_meta = dict(tool.meta)
+    new_meta["ui"] = new_ui
+    return tool.model_copy(update={"meta": new_meta})
diff --git a/fastmcp_slim/fastmcp/server/providers/proxy.py b/fastmcp_slim/fastmcp/server/providers/proxy.py
new file mode 100644
index 0000000..fd0817a
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/proxy.py
@@ -0,0 +1,1252 @@
+"""ProxyProvider for proxying to remote MCP servers.
+
+This module provides the `ProxyProvider` class that proxies components from
+a remote MCP server via a client factory. It also provides proxy component
+classes that forward execution to remote servers.
+"""
+
+from __future__ import annotations
+
+import base64
+import inspect
+import time
+from collections.abc import Awaitable, Callable, Sequence
+from typing import TYPE_CHECKING, Any, cast
+
+import anyio
+import httpx
+import mcp_types
+from mcp.server.connection import Connection
+from mcp.server.context import ServerRequestContext
+from mcp.shared.exceptions import MCPError
+from mcp_types import (
+    METHOD_NOT_FOUND,
+    BlobResourceContents,
+    ElicitRequestFormParams,
+    TextResourceContents,
+)
+from pydantic.networks import AnyUrl
+
+from fastmcp.client.client import Client, SDKServer
+from fastmcp.client.elicitation import ElicitResult, create_elicitation_callback
+from fastmcp.client.logging import LogMessage, create_log_callback
+from fastmcp.client.roots import RootsList, create_roots_callback
+from fastmcp.client.sampling import create_sampling_callback
+from fastmcp.client.telemetry import client_span
+from fastmcp.client.transports import ClientTransportT
+from fastmcp.exceptions import ResourceError
+from fastmcp.mcp_config import MCPConfig
+from fastmcp.prompts import Message, Prompt, PromptResult
+from fastmcp.prompts.base import PromptArgument
+from fastmcp.resources import Resource, ResourceTemplate
+from fastmcp.resources.base import ResourceContent, ResourceResult
+from fastmcp.resources.template import expand_uri_template
+from fastmcp.server.context import Context
+from fastmcp.server.dependencies import fastmcp_request_ctx, get_context
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.server.providers.aggregate import ProviderErrorStrategy
+from fastmcp.server.providers.base import Provider
+from fastmcp.server.server import FastMCP
+from fastmcp.server.tasks.config import TaskConfig
+from fastmcp.tools.base import Tool, ToolResult
+from fastmcp.utilities.components import FastMCPComponent, get_fastmcp_metadata
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.versions import VersionSpec, version_sort_key
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from fastmcp.client.transports import ClientTransport
+
+logger = get_logger(__name__)
+
+# Type alias for client factory functions
+ClientFactoryT = Callable[[], Client] | Callable[[], Awaitable[Client]]
+
+
+def _proxy_upstream_error(error: Exception) -> MCPError:
+    return MCPError(
+        code=mcp_types.INTERNAL_ERROR,
+        message=str(error),
+    )
+
+
+def _stash_proxy_request_context(client: Client, ctx: Context) -> None:
+    """Stash the proxy's ``RequestContext`` on a ``ProxyClient`` before a backend call.
+
+    Every proxy component (tool, resource, template, prompt) must call this
+    before relaying to its backend so the forwarding handlers can restore the
+    proxy's request context before relaying a server-initiated request
+    (roots/sampling/elicitation) back to the proxy's client. Required for every
+    proxy client: under SDK v2 an in-memory backend shares this event loop, so a
+    handler's ``get_context()`` would otherwise resolve to the backend context
+    and the server-initiated request would hang until timeout.
+
+    We stash a ``(RequestContext, weakref[FastMCP])`` tuple — never a ``Context``
+    instance — because ``Context`` properties are themselves ContextVar-dependent
+    and would resolve stale values in the receive loop.
+    """
+    if isinstance(client, ProxyClient):
+        client._proxy_rc_ref[0] = (
+            ctx.request_context,
+            ctx._fastmcp,  # weakref to FastMCP, not the Context
+        )
+
+
+class ProxyInitializeMiddleware(Middleware):
+    def __init__(self, proxy: FastMCPProxy) -> None:
+        self.proxy = proxy
+
+    async def on_initialize(
+        self,
+        context: MiddlewareContext[mcp_types.InitializeRequest],
+        call_next: CallNext[
+            mcp_types.InitializeRequest,
+            mcp_types.InitializeResult | None,
+        ],
+    ) -> mcp_types.InitializeResult | None:
+        client = await self.proxy._get_client()
+        try:
+            if isinstance(client, ProxyClient):
+                ctx = context.fastmcp_context
+                if ctx is not None:
+                    client._proxy_rc_ref[0] = (
+                        ctx.request_context,
+                        ctx._fastmcp,
+                    )
+            async with client:
+                await client.initialize()
+        except MCPError:
+            raise
+        except (
+            RuntimeError,
+            TimeoutError,
+            httpx.HTTPError,
+            anyio.ClosedResourceError,
+            anyio.EndOfStream,
+            anyio.BrokenResourceError,
+        ) as error:
+            raise _proxy_upstream_error(error) from error
+
+        return await call_next(context)
+
+
+# -----------------------------------------------------------------------------
+# Proxy Component Classes
+# -----------------------------------------------------------------------------
+
+
+class ProxyTool(Tool):
+    """A Tool that represents and executes a tool on a remote server."""
+
+    task_config: TaskConfig = TaskConfig(mode="forbidden")
+    _backend_name: str | None = None
+
+    def __init__(self, client_factory: ClientFactoryT, **kwargs: Any):
+        super().__init__(**kwargs)
+        self._client_factory = client_factory
+
+    async def _get_client(self) -> Client:
+        """Gets a client instance by calling the sync or async factory."""
+        client = self._client_factory()
+        if inspect.isawaitable(client):
+            client = cast(Client, await client)
+        return client
+
+    def model_copy(self, **kwargs: Any) -> ProxyTool:
+        """Override to preserve _backend_name when name changes."""
+        update = kwargs.get("update", {})
+        if "name" in update and self._backend_name is None:
+            # First time name is being changed, preserve original for backend calls
+            update = {**update, "_backend_name": self.name}
+            kwargs["update"] = update
+        return super().model_copy(**kwargs)
+
+    @classmethod
+    def from_mcp_tool(
+        cls, client_factory: ClientFactoryT, mcp_tool: mcp_types.Tool
+    ) -> ProxyTool:
+        """Factory method to create a ProxyTool from a raw MCP tool schema."""
+        return cls(
+            client_factory=client_factory,
+            name=mcp_tool.name,
+            title=mcp_tool.title,
+            description=mcp_tool.description,
+            parameters=mcp_tool.input_schema,
+            annotations=mcp_tool.annotations,
+            output_schema=mcp_tool.output_schema,
+            icons=mcp_tool.icons,
+            meta=mcp_tool.meta,
+            tags=get_fastmcp_metadata(mcp_tool.meta).get("tags", []),
+            execution=mcp_tool.execution,
+        )
+
+    async def run(
+        self,
+        arguments: dict[str, Any],
+        context: Context | None = None,
+    ) -> ToolResult:
+        """Executes the tool by making a call through the client."""
+        backend_name = self._backend_name or self.name
+        with client_span(
+            f"tools/call {backend_name}",
+            "tools/call",
+            backend_name,
+            tool_name=backend_name,
+        ) as span:
+            span.set_attribute("fastmcp.provider.type", "ProxyProvider")
+            client = await self._get_client()
+            async with client:
+                ctx = context or get_context()
+                _stash_proxy_request_context(client, ctx)
+                # Forward the inbound request's `_meta` block (trace context,
+                # version, etc.) to the backend. In SDK v2 the request context
+                # exposes the lifted `_meta` dict directly; task submission is a
+                # first-class params field rather than context state, so there
+                # is no separate task-metadata injection here.
+                req_ctx = ctx.request_context
+                meta: dict[str, Any] | None = (
+                    dict(req_ctx.meta) if req_ctx is not None and req_ctx.meta else None
+                )
+
+                result = await client.call_tool_mcp(
+                    name=backend_name, arguments=arguments, meta=meta
+                )
+            # Pass an upstream error result through faithfully rather than
+            # collapsing it into a raised ToolError — this preserves the
+            # backend's content (including non-text and structured content),
+            # and the client still raises on isError by default.
+            # Preserve backend's meta (includes task metadata for background tasks)
+            return ToolResult(
+                content=result.content,
+                structured_content=result.structured_content,
+                meta=result.meta,
+                is_error=result.is_error,
+            )
+
+    def get_span_attributes(self) -> dict[str, Any]:
+        return super().get_span_attributes() | {
+            "fastmcp.provider.type": "ProxyProvider",
+            "fastmcp.proxy.backend_name": self._backend_name or self.name,
+        }
+
+
+class ProxyResource(Resource):
+    """A Resource that represents and reads a resource from a remote server."""
+
+    task_config: TaskConfig = TaskConfig(mode="forbidden")
+    _cached_content: ResourceResult | None = None
+    _backend_uri: str | None = None
+
+    def __init__(
+        self,
+        client_factory: ClientFactoryT,
+        *,
+        _cached_content: ResourceResult | None = None,
+        **kwargs: Any,
+    ):
+        super().__init__(**kwargs)
+        self._client_factory = client_factory
+        self._cached_content = _cached_content
+
+    async def _get_client(self) -> Client:
+        """Gets a client instance by calling the sync or async factory."""
+        client = self._client_factory()
+        if inspect.isawaitable(client):
+            client = cast(Client, await client)
+        return client
+
+    def model_copy(self, **kwargs: Any) -> ProxyResource:
+        """Override to preserve _backend_uri when uri changes."""
+        update = kwargs.get("update", {})
+        if "uri" in update and self._backend_uri is None:
+            # First time uri is being changed, preserve original for backend calls
+            update = {**update, "_backend_uri": str(self.uri)}
+            kwargs["update"] = update
+        return super().model_copy(**kwargs)
+
+    @classmethod
+    def from_mcp_resource(
+        cls,
+        client_factory: ClientFactoryT,
+        mcp_resource: mcp_types.Resource,
+    ) -> ProxyResource:
+        """Factory method to create a ProxyResource from a raw MCP resource schema."""
+
+        return cls(
+            client_factory=client_factory,
+            uri=mcp_resource.uri,
+            name=mcp_resource.name,
+            title=mcp_resource.title,
+            description=mcp_resource.description,
+            mime_type=mcp_resource.mime_type or "text/plain",
+            icons=mcp_resource.icons,
+            meta=mcp_resource.meta,
+            tags=get_fastmcp_metadata(mcp_resource.meta).get("tags", []),
+            task_config=TaskConfig(mode="forbidden"),
+        )
+
+    async def read(self) -> ResourceResult:
+        """Read the resource content from the remote server."""
+        if self._cached_content is not None:
+            return self._cached_content
+
+        backend_uri = self._backend_uri or str(self.uri)
+        with client_span(
+            "resources/read",
+            "resources/read",
+            backend_uri,
+            resource_uri=backend_uri,
+        ) as span:
+            span.set_attribute("fastmcp.provider.type", "ProxyProvider")
+            client = await self._get_client()
+            async with client:
+                _stash_proxy_request_context(client, get_context())
+                result = await client.read_resource(backend_uri)
+            if not result:
+                raise ResourceError(
+                    f"Remote server returned empty content for {backend_uri}"
+                )
+
+            # Process all items in the result list, not just the first one
+            contents: list[ResourceContent] = []
+            for item in result:
+                if isinstance(item, TextResourceContents):
+                    contents.append(
+                        ResourceContent(
+                            content=item.text,
+                            mime_type=item.mime_type,
+                            meta=item.meta,
+                        )
+                    )
+                elif isinstance(item, BlobResourceContents):
+                    contents.append(
+                        ResourceContent(
+                            content=base64.b64decode(item.blob),
+                            mime_type=item.mime_type,
+                            meta=item.meta,
+                        )
+                    )
+                else:
+                    raise ResourceError(f"Unsupported content type: {type(item)}")
+
+            return ResourceResult(contents=contents)
+
+    def get_span_attributes(self) -> dict[str, Any]:
+        return super().get_span_attributes() | {
+            "fastmcp.provider.type": "ProxyProvider",
+            "fastmcp.proxy.backend_uri": self._backend_uri or str(self.uri),
+        }
+
+
+class ProxyTemplate(ResourceTemplate):
+    """A ResourceTemplate that represents and creates resources from a remote server template."""
+
+    task_config: TaskConfig = TaskConfig(mode="forbidden")
+    _backend_uri_template: str | None = None
+
+    def __init__(self, client_factory: ClientFactoryT, **kwargs: Any):
+        super().__init__(**kwargs)
+        self._client_factory = client_factory
+
+    async def _get_client(self) -> Client:
+        """Gets a client instance by calling the sync or async factory."""
+        client = self._client_factory()
+        if inspect.isawaitable(client):
+            client = cast(Client, await client)
+        return client
+
+    def model_copy(self, **kwargs: Any) -> ProxyTemplate:
+        """Override to preserve _backend_uri_template when uri_template changes."""
+        update = kwargs.get("update", {})
+        if "uri_template" in update and self._backend_uri_template is None:
+            # First time uri_template is being changed, preserve original for backend
+            update = {**update, "_backend_uri_template": self.uri_template}
+            kwargs["update"] = update
+        return super().model_copy(**kwargs)
+
+    @classmethod
+    def from_mcp_template(  # type: ignore[override]
+        cls, client_factory: ClientFactoryT, mcp_template: mcp_types.ResourceTemplate
+    ) -> ProxyTemplate:  # ty:ignore[invalid-method-override]
+        """Factory method to create a ProxyTemplate from a raw MCP template schema."""
+
+        return cls(
+            client_factory=client_factory,
+            uri_template=mcp_template.uri_template,
+            name=mcp_template.name,
+            title=mcp_template.title,
+            description=mcp_template.description,
+            mime_type=mcp_template.mime_type or "text/plain",
+            icons=mcp_template.icons,
+            parameters={},  # Remote templates don't have local parameters
+            meta=mcp_template.meta,
+            tags=get_fastmcp_metadata(mcp_template.meta).get("tags", []),
+            task_config=TaskConfig(mode="forbidden"),
+        )
+
+    async def create_resource(
+        self,
+        uri: str,
+        params: dict[str, Any],
+        context: Context | None = None,
+    ) -> ProxyResource:
+        """Create a resource from the template by calling the remote server."""
+        # don't use the provided uri, because it may not be the same as the
+        # uri_template on the remote server. expand_uri_template percent-encodes
+        # path and query values so the backend URI round-trips correctly.
+        backend_template = self._backend_uri_template or self.uri_template
+        parameterized_uri = expand_uri_template(backend_template, params)
+        client = await self._get_client()
+        async with client:
+            _stash_proxy_request_context(client, context or get_context())
+            result = await client.read_resource(parameterized_uri)
+
+        if not result:
+            raise ResourceError(
+                f"Remote server returned empty content for {parameterized_uri}"
+            )
+
+        # Process all items in the result list, not just the first one
+        contents: list[ResourceContent] = []
+        for item in result:
+            if isinstance(item, TextResourceContents):
+                contents.append(
+                    ResourceContent(
+                        content=item.text,
+                        mime_type=item.mime_type,
+                        meta=item.meta,
+                    )
+                )
+            elif isinstance(item, BlobResourceContents):
+                contents.append(
+                    ResourceContent(
+                        content=base64.b64decode(item.blob),
+                        mime_type=item.mime_type,
+                        meta=item.meta,
+                    )
+                )
+            else:
+                raise ResourceError(f"Unsupported content type: {type(item)}")
+
+        cached_content = ResourceResult(contents=contents)
+
+        return ProxyResource(
+            client_factory=self._client_factory,
+            uri=parameterized_uri,
+            name=self.name,
+            title=self.title,
+            description=self.description,
+            mime_type=result[
+                0
+            ].mime_type,  # Use first item's mimeType for backward compatibility
+            icons=self.icons,
+            meta=self.meta,
+            tags=get_fastmcp_metadata(self.meta).get("tags", []),
+            _cached_content=cached_content,
+        )
+
+    def get_span_attributes(self) -> dict[str, Any]:
+        return super().get_span_attributes() | {
+            "fastmcp.provider.type": "ProxyProvider",
+            "fastmcp.proxy.backend_uri_template": (
+                self._backend_uri_template or self.uri_template
+            ),
+        }
+
+
+class ProxyPrompt(Prompt):
+    """A Prompt that represents and renders a prompt from a remote server."""
+
+    task_config: TaskConfig = TaskConfig(mode="forbidden")
+    _backend_name: str | None = None
+
+    def __init__(self, client_factory: ClientFactoryT, **kwargs):
+        super().__init__(**kwargs)
+        self._client_factory = client_factory
+
+    async def _get_client(self) -> Client:
+        """Gets a client instance by calling the sync or async factory."""
+        client = self._client_factory()
+        if inspect.isawaitable(client):
+            client = cast(Client, await client)
+        return client
+
+    def model_copy(self, **kwargs: Any) -> ProxyPrompt:
+        """Override to preserve _backend_name when name changes."""
+        update = kwargs.get("update", {})
+        if "name" in update and self._backend_name is None:
+            # First time name is being changed, preserve original for backend calls
+            update = {**update, "_backend_name": self.name}
+            kwargs["update"] = update
+        return super().model_copy(**kwargs)
+
+    @classmethod
+    def from_mcp_prompt(
+        cls, client_factory: ClientFactoryT, mcp_prompt: mcp_types.Prompt
+    ) -> ProxyPrompt:
+        """Factory method to create a ProxyPrompt from a raw MCP prompt schema."""
+        arguments = [
+            PromptArgument(
+                name=arg.name,
+                description=arg.description,
+                required=arg.required or False,
+            )
+            for arg in mcp_prompt.arguments or []
+        ]
+        return cls(
+            client_factory=client_factory,
+            name=mcp_prompt.name,
+            title=mcp_prompt.title,
+            description=mcp_prompt.description,
+            arguments=arguments,
+            icons=mcp_prompt.icons,
+            meta=mcp_prompt.meta,
+            tags=get_fastmcp_metadata(mcp_prompt.meta).get("tags", []),
+            task_config=TaskConfig(mode="forbidden"),
+        )
+
+    async def render(self, arguments: dict[str, Any]) -> PromptResult:  # type: ignore[override]  # ty:ignore[invalid-method-override]
+        """Render the prompt by making a call through the client."""
+        backend_name = self._backend_name or self.name
+        with client_span(
+            f"prompts/get {backend_name}",
+            "prompts/get",
+            backend_name,
+            prompt_name=backend_name,
+        ) as span:
+            span.set_attribute("fastmcp.provider.type", "ProxyProvider")
+            client = await self._get_client()
+            async with client:
+                _stash_proxy_request_context(client, get_context())
+                result = await client.get_prompt(backend_name, arguments)
+            # Convert GetPromptResult to PromptResult, preserving meta from result
+            # (not the static prompt meta which includes fastmcp tags)
+            # Convert PromptMessages to Messages
+            messages = [
+                Message(content=m.content, role=m.role) for m in result.messages
+            ]
+            return PromptResult(
+                messages=messages,
+                description=result.description,
+                meta=result.meta,
+            )
+
+    def get_span_attributes(self) -> dict[str, Any]:
+        return super().get_span_attributes() | {
+            "fastmcp.provider.type": "ProxyProvider",
+            "fastmcp.proxy.backend_name": self._backend_name or self.name,
+        }
+
+
+# -----------------------------------------------------------------------------
+# ProxyProvider
+# -----------------------------------------------------------------------------
+
+
+class _CacheEntry:
+    """A cached sequence of components with a monotonic timestamp."""
+
+    __slots__ = ("items", "timestamp")
+
+    def __init__(self, items: Sequence[Any], timestamp: float):
+        self.items = items
+        self.timestamp = timestamp
+
+    def is_fresh(self, ttl: float) -> bool:
+        return (time.monotonic() - self.timestamp) < ttl
+
+
+_DEFAULT_CACHE_TTL: float = 300.0
+
+
+class ProxyProvider(Provider):
+    """Provider that proxies to a remote MCP server via a client factory.
+
+    This provider fetches components from a remote server and returns Proxy*
+    component instances that forward execution to the remote server.
+
+    All components returned by this provider have task_config.mode="forbidden"
+    because tasks cannot be executed through a proxy.
+
+    Component lists (tools, resources, templates, prompts) are cached so that
+    individual lookups (e.g. during ``call_tool``) can resolve from the cache
+    instead of opening a new backend connection.  The cache stores the
+    backend's raw component metadata and is shared across all sessions;
+    per-session visibility and auth filtering are applied after cache lookup
+    by the server layer.  The cache is refreshed whenever a ``list_*`` call
+    is made, and entries expire after ``cache_ttl`` seconds (default 300).
+    Set ``cache_ttl=0`` to disable caching.  Disabling is recommended for
+    backends whose component lists change dynamically.
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.providers.proxy import ProxyProvider, ProxyClient
+
+        # Create a proxy provider for a remote server
+        proxy = ProxyProvider(lambda: ProxyClient("http://localhost:8000/mcp"))
+
+        mcp = FastMCP("Proxy Server")
+        mcp.add_provider(proxy)
+
+        # Can also add with namespace
+        mcp.add_provider(proxy.with_namespace("remote"))
+        ```
+    """
+
+    def __init__(
+        self,
+        client_factory: ClientFactoryT,
+        cache_ttl: float | None = None,
+    ):
+        """Initialize a ProxyProvider.
+
+        Args:
+            client_factory: A callable that returns a Client instance when called.
+                           This gives you full control over session creation and reuse.
+                           Can be either a synchronous or asynchronous function.
+            cache_ttl: How long (in seconds) to cache component lists for
+                      individual lookups.  Defaults to 300.  Set to 0 to
+                      disable caching.
+        """
+        super().__init__()
+        self.client_factory = client_factory
+        self._cache_ttl = cache_ttl if cache_ttl is not None else _DEFAULT_CACHE_TTL
+        self._tools_cache: _CacheEntry[Tool] | None = None
+        self._resources_cache: _CacheEntry[Resource] | None = None
+        self._templates_cache: _CacheEntry[ResourceTemplate] | None = None
+        self._prompts_cache: _CacheEntry[Prompt] | None = None
+
+    async def _get_client(self) -> Client:
+        """Gets a client instance by calling the sync or async factory."""
+        client = self.client_factory()
+        if inspect.isawaitable(client):
+            client = cast(Client, await client)
+        return client
+
+    # -------------------------------------------------------------------------
+    # Tool methods
+    # -------------------------------------------------------------------------
+
+    async def _list_tools(self) -> Sequence[Tool]:
+        """List all tools from the remote server."""
+        try:
+            client = await self._get_client()
+            async with client:
+                mcp_tools = await client.list_tools()
+                tools = [
+                    ProxyTool.from_mcp_tool(self.client_factory, t) for t in mcp_tools
+                ]
+        except MCPError as e:
+            if e.error.code == METHOD_NOT_FOUND:
+                tools = []
+            else:
+                raise
+        self._tools_cache = _CacheEntry(tools, time.monotonic())
+        return tools
+
+    async def _get_tool(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Tool | None:
+        cache = self._tools_cache
+        if cache is None or not cache.is_fresh(self._cache_ttl):
+            await self._list_tools()
+            cache = self._tools_cache
+        assert cache is not None
+        matching = [t for t in cache.items if t.name == name]
+        if version:
+            matching = [t for t in matching if version.matches(t.version)]
+        if not matching:
+            return None
+        return max(matching, key=version_sort_key)
+
+    # -------------------------------------------------------------------------
+    # Resource methods
+    # -------------------------------------------------------------------------
+
+    async def _list_resources(self) -> Sequence[Resource]:
+        """List all resources from the remote server."""
+        try:
+            client = await self._get_client()
+            async with client:
+                mcp_resources = await client.list_resources()
+                resources = [
+                    ProxyResource.from_mcp_resource(self.client_factory, r)
+                    for r in mcp_resources
+                ]
+        except MCPError as e:
+            if e.error.code == METHOD_NOT_FOUND:
+                resources = []
+            else:
+                raise
+        self._resources_cache = _CacheEntry(resources, time.monotonic())
+        return resources
+
+    async def _get_resource(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> Resource | None:
+        cache = self._resources_cache
+        if cache is None or not cache.is_fresh(self._cache_ttl):
+            await self._list_resources()
+            cache = self._resources_cache
+        assert cache is not None
+        matching = [r for r in cache.items if str(r.uri) == uri]
+        if version:
+            matching = [r for r in matching if version.matches(r.version)]
+        if not matching:
+            return None
+        return max(matching, key=version_sort_key)
+
+    # -------------------------------------------------------------------------
+    # Resource template methods
+    # -------------------------------------------------------------------------
+
+    async def _list_resource_templates(self) -> Sequence[ResourceTemplate]:
+        """List all resource templates from the remote server."""
+        try:
+            client = await self._get_client()
+            async with client:
+                mcp_templates = await client.list_resource_templates()
+                templates = [
+                    ProxyTemplate.from_mcp_template(self.client_factory, t)
+                    for t in mcp_templates
+                ]
+        except MCPError as e:
+            if e.error.code == METHOD_NOT_FOUND:
+                templates = []
+            else:
+                raise
+        self._templates_cache = _CacheEntry(templates, time.monotonic())
+        return templates
+
+    async def _get_resource_template(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> ResourceTemplate | None:
+        cache = self._templates_cache
+        if cache is None or not cache.is_fresh(self._cache_ttl):
+            await self._list_resource_templates()
+            cache = self._templates_cache
+        assert cache is not None
+        matching = [t for t in cache.items if t.matches(uri) is not None]
+        if version:
+            matching = [t for t in matching if version.matches(t.version)]
+        if not matching:
+            return None
+        return max(matching, key=version_sort_key)
+
+    # -------------------------------------------------------------------------
+    # Prompt methods
+    # -------------------------------------------------------------------------
+
+    async def _list_prompts(self) -> Sequence[Prompt]:
+        """List all prompts from the remote server."""
+        try:
+            client = await self._get_client()
+            async with client:
+                mcp_prompts = await client.list_prompts()
+                prompts = [
+                    ProxyPrompt.from_mcp_prompt(self.client_factory, p)
+                    for p in mcp_prompts
+                ]
+        except MCPError as e:
+            if e.error.code == METHOD_NOT_FOUND:
+                prompts = []
+            else:
+                raise
+        self._prompts_cache = _CacheEntry(prompts, time.monotonic())
+        return prompts
+
+    async def _get_prompt(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        cache = self._prompts_cache
+        if cache is None or not cache.is_fresh(self._cache_ttl):
+            await self._list_prompts()
+            cache = self._prompts_cache
+        assert cache is not None
+        matching = [p for p in cache.items if p.name == name]
+        if version:
+            matching = [p for p in matching if version.matches(p.version)]
+        if not matching:
+            return None
+        return max(matching, key=version_sort_key)
+
+    # -------------------------------------------------------------------------
+    # Task methods
+    # -------------------------------------------------------------------------
+
+    async def get_tasks(self) -> Sequence[FastMCPComponent]:
+        """Return empty list since proxy components don't support tasks.
+
+        Override the base implementation to avoid calling list_tools() during
+        server lifespan initialization, which would open the client before any
+        context is set. All Proxy* components have task_config.mode="forbidden".
+        """
+        return []
+
+    # lifespan() uses default implementation (empty context manager)
+    # because client cleanup is handled per-request
+
+
+# -----------------------------------------------------------------------------
+# Factory Functions
+# -----------------------------------------------------------------------------
+
+
+def _create_client_factory(
+    target: (
+        Client[ClientTransportT]
+        | ClientTransport
+        | FastMCP[Any]
+        | SDKServer
+        | AnyUrl
+        | Path
+        | MCPConfig
+        | dict[str, Any]
+        | str
+    ),
+) -> ClientFactoryT:
+    """Create a client factory from the given target.
+
+    Internal helper that handles the session strategy based on the target type:
+    - Connected Client: reuses existing session (with warning about context mixing)
+    - Disconnected Client: creates fresh sessions per request
+    - Other targets: creates ProxyClient and fresh sessions per request
+    """
+    if isinstance(target, Client):
+        client = target
+
+        # Plain Clients used as proxy backends also need header forwarding,
+        # same as ProxyClient (which sets this in __init__).
+        from fastmcp.client.transports.http import StreamableHttpTransport
+        from fastmcp.client.transports.sse import SSETransport
+
+        if isinstance(client.transport, StreamableHttpTransport | SSETransport):
+            client.transport.forward_incoming_headers = True
+
+        if client.is_connected() and type(client) is ProxyClient:
+            logger.info(
+                "Proxy detected connected ProxyClient - creating fresh sessions for each "
+                "request to avoid request context leakage."
+            )
+
+            def fresh_client_factory() -> Client:
+                return client.new()
+
+            return fresh_client_factory
+
+        if client.is_connected():
+            logger.info(
+                "Proxy detected connected client - reusing existing session for all requests. "
+                "This may cause context mixing in concurrent scenarios."
+            )
+
+            def reuse_client_factory() -> Client:
+                return client
+
+            return reuse_client_factory
+
+        def fresh_client_factory() -> Client:
+            return client.new()
+
+        return fresh_client_factory
+    else:
+        # target is not a Client, so it's compatible with ProxyClient.__init__
+        base_client = ProxyClient(cast(Any, target))
+
+        def proxy_client_factory() -> Client:
+            return base_client.new()
+
+        return proxy_client_factory
+
+
+# -----------------------------------------------------------------------------
+# FastMCPProxy - Convenience Wrapper
+# -----------------------------------------------------------------------------
+
+
+class FastMCPProxy(FastMCP):
+    """A FastMCP server that acts as a proxy to a remote MCP-compliant server.
+
+    This is a convenience wrapper that creates a FastMCP server with a
+    ProxyProvider. For more control, use FastMCP with add_provider(ProxyProvider(...)).
+
+    Example:
+        ```python
+        from fastmcp.server import create_proxy
+        from fastmcp.server.providers.proxy import FastMCPProxy, ProxyClient
+
+        # Create a proxy server using create_proxy (recommended)
+        proxy = create_proxy("http://localhost:8000/mcp")
+
+        # Or use FastMCPProxy directly with explicit client factory
+        proxy = FastMCPProxy(client_factory=lambda: ProxyClient("http://localhost:8000/mcp"))
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        client_factory: ClientFactoryT,
+        provider_error_strategy: ProviderErrorStrategy = "warn",
+        **kwargs,
+    ):
+        """Initialize the proxy server.
+
+        FastMCPProxy requires explicit session management via client_factory.
+        Use create_proxy() for convenience with automatic session strategy.
+
+        Args:
+            client_factory: A callable that returns a Client instance when called.
+                           This gives you full control over session creation and reuse.
+                           Can be either a synchronous or asynchronous function.
+            provider_error_strategy: How provider errors should affect aggregate
+                operations. Defaults to ``"warn"`` for compatibility; use
+                ``"raise"`` when the proxy should surface upstream failures.
+            **kwargs: Additional settings for the FastMCP server.
+        """
+        super().__init__(**kwargs)
+        self.provider_error_strategy = provider_error_strategy
+        self.client_factory = client_factory
+        provider: Provider = ProxyProvider(client_factory)
+        self.add_provider(provider)
+        self.middleware.append(ProxyInitializeMiddleware(self))
+        self._setup_proxy_ping_handler()
+
+    async def _get_client(self) -> Client:
+        client = self.client_factory()
+        if inspect.isawaitable(client):
+            client = cast(Client, await client)
+        return client
+
+    def _setup_proxy_ping_handler(self) -> None:
+        async def ping_remote(
+            _ctx: ServerRequestContext[Any, Any],
+            _params: mcp_types.RequestParams | None,
+        ) -> mcp_types.EmptyResult:
+            client = await self._get_client()
+            async with client:
+                await client.ping()
+            return mcp_types.EmptyResult()
+
+        self._mcp_server.add_request_handler(
+            "ping", mcp_types.RequestParams, ping_remote
+        )
+
+
+# -----------------------------------------------------------------------------
+# ProxyClient and Related
+# -----------------------------------------------------------------------------
+
+
+async def default_proxy_roots_handler(
+    context: ServerRequestContext[Any, Any],
+) -> RootsList:
+    """Forward list roots request from remote server to proxy's connected clients."""
+    ctx = get_context()
+    return await ctx.list_roots()
+
+
+async def default_proxy_sampling_handler(
+    messages: list[mcp_types.SamplingMessage],
+    params: mcp_types.CreateMessageRequestParams,
+    context: ServerRequestContext[Any, Any],
+) -> mcp_types.CreateMessageResult:
+    """Forward sampling request from remote server to proxy's connected clients."""
+    ctx = get_context()
+    result = await ctx.sample(
+        list(messages),
+        system_prompt=params.system_prompt,
+        temperature=params.temperature,
+        max_tokens=params.max_tokens,
+        model_preferences=params.model_preferences,
+    )
+    content = mcp_types.TextContent(type="text", text=result.text or "")
+    return mcp_types.CreateMessageResult(
+        role="assistant",
+        model="fastmcp-client",
+        # TODO(ty): remove when ty supports isinstance exclusion narrowing
+        content=content,
+    )
+
+
+async def default_proxy_elicitation_handler(
+    message: str,
+    response_type: type,
+    params: mcp_types.ElicitRequestParams,
+    context: ServerRequestContext[Any, Any],
+) -> ElicitResult:
+    """Forward elicitation request from remote server to proxy's connected clients."""
+    ctx = get_context()
+    # requestedSchema only exists on ElicitRequestFormParams, not ElicitRequestURLParams
+    requested_schema = (
+        params.requested_schema
+        if isinstance(params, ElicitRequestFormParams)
+        else {"type": "object", "properties": {}}
+    )
+    result = await ctx.session.elicit(
+        message=message,
+        requested_schema=requested_schema,
+        related_request_id=ctx.request_id,
+    )
+    return ElicitResult(action=result.action, content=result.content)
+
+
+async def default_proxy_log_handler(message: LogMessage) -> None:
+    """Forward log notification from remote server to proxy's connected clients."""
+    ctx = get_context()
+    msg = message.data.get("msg")
+    extra = message.data.get("extra")
+    await ctx.log(msg, level=message.level, logger_name=message.logger, extra=extra)
+
+
+async def default_proxy_progress_handler(
+    progress: float,
+    total: float | None,
+    message: str | None,
+) -> None:
+    """Forward progress notification from remote server to proxy's connected clients."""
+    ctx = get_context()
+    await ctx.report_progress(progress, total, message)
+
+
+def _restore_request_context(
+    rc_ref: list[Any],
+) -> None:
+    """Set the ``request_ctx``, ``_current_context`` and ``_current_server``
+    ContextVars from stashed values so a proxy forwarding handler relays to the
+    proxy's own client rather than the upstream server.
+
+    Called at the start of every proxy handler invocation. The stashed proxy
+    ``RequestContext`` is the correct forwarding target, so we restore it unless
+    it is already active. This covers two cases:
+
+    - Stateful proxy: the reused receive-loop task carries a stale ContextVar
+      from an earlier request (same session, different request_id).
+    - In-memory backend (SDK v2): the backend runs in this event loop, so the
+      handler may inherit the *backend's* request_ctx (a different session).
+
+    We stash a ``(RequestContext, weakref[FastMCP])`` tuple — never a
+    ``Context`` instance — because ``Context`` properties are themselves
+    ContextVar-dependent and would resolve stale values in the receive
+    loop.  Instead we construct a fresh ``Context`` here after restoring
+    ``request_ctx``, so its property accesses read the correct values.
+
+    This is a set-only repair of a long-lived task's ContextVars, not a
+    scope: we never ``reset()`` because the prior values are stale and
+    the loop keeps running.  ``_current_server`` is restored alongside
+    ``_current_context`` so handlers that resolve the server via
+    dependency injection (e.g. ``get_server()``) see the right instance;
+    it is set directly rather than via ``Context.__aenter__`` to avoid
+    opening a context-manager lifecycle on an unscoped path.
+    """
+    import weakref
+
+    from fastmcp.server.context import Context, _current_context
+    from fastmcp.server.dependencies import _current_server
+
+    stashed = rc_ref[0]
+    if stashed is None:
+        return
+
+    rc, fastmcp_ref = stashed
+    current_rc = fastmcp_request_ctx.get()
+    # Restore unless the stashed proxy context is already the active one.
+    if current_rc is rc:
+        return
+    fastmcp_request_ctx.set(rc)
+    fastmcp = fastmcp_ref()
+    if fastmcp is not None:
+        _current_context.set(Context(fastmcp))
+        _current_server.set(weakref.ref(fastmcp))
+
+
+def _make_restoring_handler(handler: Callable, rc_ref: list[Any]) -> Callable:
+    """Wrap a proxy handler to restore request_ctx before delegating.
+
+    The wrapper is a plain ``async def`` so it passes
+    ``inspect.isfunction()`` checks in handler registration paths
+    (e.g., ``create_roots_callback``).
+    """
+
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+        _restore_request_context(rc_ref)
+        return await handler(*args, **kwargs)
+
+    return wrapper
+
+
+class ProxyClient(Client[ClientTransportT]):
+    """A proxy client that forwards advanced interactions between a remote MCP server and the proxy's connected clients.
+
+    Supports forwarding roots, sampling, elicitation, logging, and progress.
+
+    The default forwarding handlers must resolve the *proxy's* request context so
+    they relay server-initiated requests (roots/sampling/elicitation) back to the
+    proxy's own connected client, not to the upstream server they are talking to.
+    Under SDK v2 an in-memory backend runs in the same event loop as this client,
+    so a naive ``get_context()`` inside a handler can resolve to the backend's
+    context and forward the request straight back to the backend — an infinite
+    loop. To avoid that, ``ProxyTool.run`` (and the other proxy components) stash
+    the proxy-side ``RequestContext`` in ``_proxy_rc_ref`` before each backend
+    call, and the handlers are wrapped to restore it before forwarding.
+    """
+
+    # Mutable list shared across copies (Client.new() uses copy.copy, which
+    # preserves references to mutable containers). Proxy components write [0]
+    # before each backend call; handlers read it to restore the proxy's
+    # request_ctx before forwarding. Stores a (RequestContext, weakref[FastMCP])
+    # tuple — never a Context instance — because Context properties are
+    # ContextVar-dependent and would resolve stale values in the receive loop.
+    _proxy_rc_ref: list[Any]
+    _proxy_restoring_handler_keys: set[str]
+
+    def __init__(
+        self,
+        transport: ClientTransportT
+        | FastMCP[Any]
+        | SDKServer
+        | AnyUrl
+        | Path
+        | MCPConfig
+        | dict[str, Any]
+        | str,
+        **kwargs,
+    ):
+        if "name" not in kwargs:
+            kwargs["name"] = self.generate_name()
+        # Install context-restoring handler wrappers BEFORE super().__init__
+        # registers them with the Client's session kwargs.
+        self._proxy_rc_ref = [None]
+        self._proxy_restoring_handler_keys = set()
+        for key, default_fn in (
+            ("roots", default_proxy_roots_handler),
+            ("sampling_handler", default_proxy_sampling_handler),
+            ("elicitation_handler", default_proxy_elicitation_handler),
+            ("log_handler", default_proxy_log_handler),
+            ("progress_handler", default_proxy_progress_handler),
+        ):
+            if key not in kwargs:
+                kwargs[key] = _make_restoring_handler(default_fn, self._proxy_rc_ref)
+                self._proxy_restoring_handler_keys.add(key)
+        super().__init__(transport=transport, **kwargs)  # ty: ignore[no-matching-overload]
+
+        # Enable forwarding of inbound HTTP headers (e.g. authorization) to
+        # the upstream server. This is only appropriate for proxy clients,
+        # where the caller's credentials should be propagated.
+        from fastmcp.client.transports.http import StreamableHttpTransport
+        from fastmcp.client.transports.sse import SSETransport
+
+        if isinstance(self.transport, StreamableHttpTransport | SSETransport):
+            self.transport.forward_incoming_headers = True
+
+    def _bind_restoring_handlers(self) -> None:
+        if "roots" in self._proxy_restoring_handler_keys:
+            self._session_kwargs["list_roots_callback"] = create_roots_callback(
+                _make_restoring_handler(default_proxy_roots_handler, self._proxy_rc_ref)
+            )
+        if "sampling_handler" in self._proxy_restoring_handler_keys:
+            self._session_kwargs["sampling_callback"] = create_sampling_callback(
+                _make_restoring_handler(
+                    default_proxy_sampling_handler, self._proxy_rc_ref
+                )
+            )
+        if "elicitation_handler" in self._proxy_restoring_handler_keys:
+            self._session_kwargs["elicitation_callback"] = create_elicitation_callback(
+                _make_restoring_handler(
+                    default_proxy_elicitation_handler, self._proxy_rc_ref
+                )
+            )
+        if "log_handler" in self._proxy_restoring_handler_keys:
+            self._session_kwargs["logging_callback"] = create_log_callback(
+                _make_restoring_handler(default_proxy_log_handler, self._proxy_rc_ref)
+            )
+        if "progress_handler" in self._proxy_restoring_handler_keys:
+            self._progress_handler = _make_restoring_handler(
+                default_proxy_progress_handler, self._proxy_rc_ref
+            )
+
+    def new(self) -> ProxyClient[ClientTransportT]:
+        new_client = cast(ProxyClient[ClientTransportT], super().new())
+        new_client._proxy_rc_ref = [None]
+        new_client._proxy_restoring_handler_keys = set(
+            self._proxy_restoring_handler_keys
+        )
+        new_client._bind_restoring_handlers()
+        return new_client
+
+
+class StatefulProxyClient(ProxyClient[ClientTransportT]):
+    """A proxy client that provides a stateful client factory for the proxy server.
+
+    The stateful proxy client bound its copy to the server session.
+    And it will be disconnected when the session is exited.
+
+    This is useful to proxy a stateful mcp server such as the Playwright MCP server.
+    Note that it is essential to ensure that the proxy server itself is also stateful.
+
+    The base ``ProxyClient`` already installs the context-restoring handlers
+    (see its docstring); this subclass additionally caches one client per stable
+    ``Connection`` and forces disconnect when the connection is torn down.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any):
+        super().__init__(*args, **kwargs)
+        # SDK v2 constructs a ServerSession per request, so per-session keying
+        # would build a fresh proxy client for every request. Key by the stable
+        # per-connection `Connection` instead, and tie cleanup to its exit stack.
+        self._caches: dict[Connection, Client[ClientTransportT]] = {}
+
+    def new(self) -> StatefulProxyClient[ClientTransportT]:
+        return cast(StatefulProxyClient[ClientTransportT], super().new())
+
+    async def __aexit__(self, exc_type, exc_value, traceback) -> None:  # type: ignore[override]  # ty:ignore[invalid-method-override]
+        """The stateful proxy client will be forced disconnected when the session is exited.
+
+        So we do nothing here.
+        """
+
+    async def clear(self):
+        """Clear all cached clients and force disconnect them."""
+        while self._caches:
+            _, cache = self._caches.popitem()
+            await cache._disconnect(force=True)
+
+    def new_stateful(self) -> Client[ClientTransportT]:
+        """Create a new stateful proxy client instance with the same configuration.
+
+        Use this method as the client factory for stateful proxy server.
+        """
+        session = get_context().session
+        # SDK v2: the ServerSession is per-request; the Connection is the stable
+        # per-connection object that owns the exit stack. Key the cache and the
+        # cleanup callback off it so one proxy client is reused for the whole
+        # connection instead of one per request.
+        connection = getattr(session, "_connection", None)
+        if connection is None:
+            raise RuntimeError(
+                "Stateful proxy requires a per-connection server session; "
+                "no connection is available on the current context."
+            )
+        proxy_client = self._caches.get(connection, None)
+
+        if proxy_client is None:
+            proxy_client = self.new()
+            logger.debug(f"{proxy_client} created for {connection}")
+            self._caches[connection] = proxy_client
+
+            async def _on_connection_exit():
+                self._caches.pop(connection, None)
+                logger.debug(f"{proxy_client} will be disconnect")
+                # This callback runs while the connection's exit stack is
+                # unwinding, which usually happens because the owning task is
+                # being cancelled. Shield the disconnect so the forced cleanup
+                # actually runs to completion instead of aborting at the first
+                # cancellation checkpoint (e.g. acquiring the session lock).
+                with anyio.CancelScope(shield=True):
+                    await proxy_client._disconnect(force=True)
+
+            connection.exit_stack.push_async_callback(_on_connection_exit)
+
+        return proxy_client
diff --git a/fastmcp_slim/fastmcp/server/providers/skills/__init__.py b/fastmcp_slim/fastmcp/server/providers/skills/__init__.py
new file mode 100644
index 0000000..b15c1c6
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/skills/__init__.py
@@ -0,0 +1,59 @@
+"""Skills providers for exposing agent skills as MCP resources.
+
+This module provides a two-layer architecture for skill discovery:
+
+- **SkillProvider**: Handles a single skill folder, exposing its files as resources.
+- **SkillsDirectoryProvider**: Scans a directory, creates a SkillProvider per folder.
+- **Vendor providers**: Platform-specific providers for Claude, Cursor, VS Code, Codex,
+  Gemini, Goose, Copilot, and OpenCode.
+
+Example:
+    ```python
+    from pathlib import Path
+    from fastmcp import FastMCP
+    from fastmcp.server.providers.skills import ClaudeSkillsProvider, SkillProvider
+
+    mcp = FastMCP("Skills Server")
+
+    # Load a single skill
+    mcp.add_provider(SkillProvider(Path.home() / ".claude/skills/pdf-processing"))
+
+    # Or load all skills in a directory
+    mcp.add_provider(ClaudeSkillsProvider())  # Uses ~/.claude/skills/
+    ```
+"""
+
+from __future__ import annotations
+
+# Import providers
+from fastmcp.server.providers.skills.claude_provider import ClaudeSkillsProvider
+from fastmcp.server.providers.skills.directory_provider import SkillsDirectoryProvider
+from fastmcp.server.providers.skills.skill_provider import SkillProvider
+from fastmcp.server.providers.skills.vendor_providers import (
+    CodexSkillsProvider,
+    CopilotSkillsProvider,
+    CursorSkillsProvider,
+    GeminiSkillsProvider,
+    GooseSkillsProvider,
+    OpenCodeSkillsProvider,
+    VSCodeSkillsProvider,
+)
+
+
+# Backwards compatibility alias
+SkillsProvider = SkillsDirectoryProvider
+
+
+__all__ = [
+    "ClaudeSkillsProvider",
+    "CodexSkillsProvider",
+    "CopilotSkillsProvider",
+    "CursorSkillsProvider",
+    "GeminiSkillsProvider",
+    "GooseSkillsProvider",
+    "OpenCodeSkillsProvider",
+    "SkillProvider",
+    "SkillsDirectoryProvider",
+    "SkillsProvider",  # Backwards compatibility alias
+    "VSCodeSkillsProvider",
+]
diff --git a/fastmcp_slim/fastmcp/server/providers/skills/_common.py b/fastmcp_slim/fastmcp/server/providers/skills/_common.py
new file mode 100644
index 0000000..d0e1177
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/skills/_common.py
@@ -0,0 +1,107 @@
+"""Shared utilities and data structures for skills providers."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class SkillFileInfo:
+    """Information about a file within a skill."""
+
+    path: str  # Relative path within skill directory
+    size: int
+    hash: str  # sha256 hash
+
+
+@dataclass
+class SkillInfo:
+    """Parsed information about a skill."""
+
+    name: str  # Directory name (canonical identifier)
+    description: str  # From frontmatter or first line
+    path: Path  # Absolute path to skill directory
+    main_file: str  # Name of main file (e.g., "SKILL.md")
+    files: list[SkillFileInfo] = field(default_factory=list)
+    frontmatter: dict[str, Any] = field(default_factory=dict)
+
+
+def parse_frontmatter(content: str) -> tuple[dict[str, Any], str]:
+    """Parse YAML frontmatter from markdown content.
+
+    Args:
+        content: Markdown content potentially starting with ---
+
+    Returns:
+        Tuple of (frontmatter dict, remaining content)
+    """
+    if not content.startswith("---"):
+        return {}, content
+
+    # Find the closing ---
+    end_match = re.search(r"\n---\s*\n", content[3:])
+    if not end_match:
+        return {}, content
+
+    frontmatter_text = content[3 : 3 + end_match.start()]
+    remaining = content[3 + end_match.end() :]
+
+    # Parse YAML (simple key: value parsing, no complex types)
+    frontmatter: dict[str, Any] = {}
+    for line in frontmatter_text.strip().split("\n"):
+        if ":" in line:
+            key, _, value = line.partition(":")
+            key = key.strip()
+            value = value.strip()
+
+            # Handle quoted strings
+            if (value.startswith('"') and value.endswith('"')) or (
+                value.startswith("'") and value.endswith("'")
+            ):
+                value = value[1:-1]
+
+            # Handle lists [a, b, c]
+            if value.startswith("[") and value.endswith("]"):
+                items = value[1:-1].split(",")
+                value = [item.strip().strip("\"'") for item in items if item.strip()]
+
+            frontmatter[key] = value
+
+    return frontmatter, remaining
+
+
+def compute_file_hash(path: Path) -> str:
+    """Compute SHA256 hash of a file."""
+    sha256 = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            sha256.update(chunk)
+    return f"sha256:{sha256.hexdigest()}"
+
+
+def scan_skill_files(skill_dir: Path) -> list[SkillFileInfo]:
+    """Scan a skill directory for all files."""
+    files = []
+    resolved_skill_dir = skill_dir.resolve()
+
+    # Sort for deterministic ordering across platforms
+    for file_path in sorted(skill_dir.rglob("*")):
+        if file_path.is_file():
+            resolved_file_path = file_path.resolve()
+            if not resolved_file_path.is_relative_to(resolved_skill_dir):
+                continue
+
+            rel_path = file_path.relative_to(skill_dir)
+            files.append(
+                SkillFileInfo(
+                    # Use POSIX paths for cross-platform URI consistency
+                    path=rel_path.as_posix(),
+                    size=resolved_file_path.stat().st_size,
+                    hash=compute_file_hash(resolved_file_path),
+                )
+            )
+    return files
diff --git a/fastmcp_slim/fastmcp/server/providers/skills/claude_provider.py b/fastmcp_slim/fastmcp/server/providers/skills/claude_provider.py
new file mode 100644
index 0000000..b726495
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/skills/claude_provider.py
@@ -0,0 +1,44 @@
+"""Claude-specific skills provider for Claude Code skills."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from fastmcp.server.providers.skills.directory_provider import SkillsDirectoryProvider
+
+
+class ClaudeSkillsProvider(SkillsDirectoryProvider):
+    """Provider for Claude Code skills from ~/.claude/skills/.
+
+    A convenience subclass that sets the default root to Claude's skills location.
+
+    Args:
+        reload: If True, re-scan on every request. Defaults to False.
+        supporting_files: How supporting files are exposed:
+            - "template": Accessed via ResourceTemplate, hidden from list_resources().
+            - "resources": Each file exposed as individual Resource in list_resources().
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.providers.skills import ClaudeSkillsProvider
+
+        mcp = FastMCP("Claude Skills")
+        mcp.add_provider(ClaudeSkillsProvider())  # Uses default location
+        ```
+    """
+
+    def __init__(
+        self,
+        reload: bool = False,
+        supporting_files: Literal["template", "resources"] = "template",
+    ) -> None:
+        root = Path.home() / ".claude" / "skills"
+
+        super().__init__(
+            roots=[root],
+            reload=reload,
+            main_file_name="SKILL.md",
+            supporting_files=supporting_files,
+        )
diff --git a/fastmcp_slim/fastmcp/server/providers/skills/directory_provider.py b/fastmcp_slim/fastmcp/server/providers/skills/directory_provider.py
new file mode 100644
index 0000000..c390b42
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/skills/directory_provider.py
@@ -0,0 +1,153 @@
+"""Directory scanning provider for discovering multiple skills."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Literal
+
+from fastmcp.resources.base import Resource
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.providers.aggregate import AggregateProvider
+from fastmcp.server.providers.skills.skill_provider import SkillProvider
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.versions import VersionSpec
+
+logger = get_logger(__name__)
+
+
+class SkillsDirectoryProvider(AggregateProvider):
+    """Provider that scans directories and creates a SkillProvider per skill folder.
+
+    This extends AggregateProvider to combine multiple SkillProviders into one.
+    Each subdirectory containing a main file (default: SKILL.md) becomes a skill.
+    Can scan multiple root directories - if a skill name appears in multiple roots,
+    the first one found wins.
+
+    Args:
+        roots: Root directory(ies) containing skill folders. Can be a single path
+            or a sequence of paths.
+        reload: If True, re-discover skills on each request. Defaults to False.
+        main_file_name: Name of the main skill file. Defaults to "SKILL.md".
+        supporting_files: How supporting files are exposed in child SkillProviders:
+            - "template": Accessed via ResourceTemplate, hidden from list_resources().
+            - "resources": Each file exposed as individual Resource in list_resources().
+
+    Example:
+        ```python
+        from pathlib import Path
+        from fastmcp import FastMCP
+        from fastmcp.server.providers.skills import SkillsDirectoryProvider
+
+        mcp = FastMCP("Skills")
+        # Single directory
+        mcp.add_provider(SkillsDirectoryProvider(
+            roots=Path.home() / ".claude" / "skills",
+            reload=True,  # Re-scan on each request
+        ))
+        # Multiple directories
+        mcp.add_provider(SkillsDirectoryProvider(
+            roots=[Path("/etc/skills"), Path.home() / ".local" / "skills"],
+        ))
+        ```
+    """
+
+    def __init__(
+        self,
+        roots: str | Path | Sequence[str | Path],
+        reload: bool = False,
+        main_file_name: str = "SKILL.md",
+        supporting_files: Literal["template", "resources"] = "template",
+    ) -> None:
+        super().__init__()
+        # Normalize to sequence: single path becomes list
+        if isinstance(roots, (str, Path)):
+            roots = [roots]
+
+        self._roots = [Path(r).resolve() for r in roots]
+        self._reload = reload
+        self._main_file_name = main_file_name
+        self._supporting_files = supporting_files
+        self._discovered = False
+
+        # Discover skills at init
+        self._discover_skills()
+
+    def _discover_skills(self) -> None:
+        """Scan root directories and create SkillProvider per valid skill folder."""
+        # Clear existing providers if reloading
+        self.providers.clear()
+
+        seen_skill_names: set[str] = set()
+
+        for root in self._roots:
+            if not root.exists():
+                logger.debug(f"Skills root does not exist: {root}")
+                continue
+
+            for skill_dir in root.iterdir():
+                if not skill_dir.is_dir():
+                    continue
+
+                main_file = skill_dir / self._main_file_name
+                if not main_file.exists():
+                    continue
+
+                skill_name = skill_dir.name
+                # Skip if we've already seen this skill name (first wins)
+                if skill_name in seen_skill_names:
+                    logger.debug(
+                        f"Skipping duplicate skill '{skill_name}' from {root} "
+                        f"(already found in earlier root)"
+                    )
+                    continue
+
+                try:
+                    provider = SkillProvider(
+                        skill_path=skill_dir,
+                        main_file_name=self._main_file_name,
+                        supporting_files=self._supporting_files,
+                    )
+                    self.providers.append(provider)
+                    seen_skill_names.add(skill_name)
+                except (FileNotFoundError, PermissionError, OSError):
+                    logger.exception(f"Failed to load skill: {skill_dir.name}")
+
+        self._discovered = True
+        logger.debug(
+            f"SkillsDirectoryProvider loaded {len(self.providers)} skills "
+            f"from {len(self._roots)} root(s)"
+        )
+
+    async def _ensure_discovered(self) -> None:
+        """Ensure skills are discovered, rediscovering if reload is enabled."""
+        if self._reload or not self._discovered:
+            self._discover_skills()
+
+    # Override list methods to support reload
+    async def _list_resources(self) -> Sequence[Resource]:
+        await self._ensure_discovered()
+        return await super()._list_resources()
+
+    async def _list_resource_templates(self) -> Sequence[ResourceTemplate]:
+        await self._ensure_discovered()
+        return await super()._list_resource_templates()
+
+    async def _get_resource(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> Resource | None:
+        await self._ensure_discovered()
+        return await super()._get_resource(uri, version)
+
+    async def _get_resource_template(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> ResourceTemplate | None:
+        await self._ensure_discovered()
+        return await super()._get_resource_template(uri, version)
+
+    def __repr__(self) -> str:
+        roots_repr = self._roots[0] if len(self._roots) == 1 else self._roots
+        return (
+            f"SkillsDirectoryProvider(roots={roots_repr!r}, "
+            f"reload={self._reload}, skills={len(self.providers)})"
+        )
diff --git a/fastmcp_slim/fastmcp/server/providers/skills/skill_provider.py b/fastmcp_slim/fastmcp/server/providers/skills/skill_provider.py
new file mode 100644
index 0000000..0550e90
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/skills/skill_provider.py
@@ -0,0 +1,450 @@
+"""Basic skill provider for handling a single skill folder."""
+
+from __future__ import annotations
+
+import json
+import mimetypes
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any, Literal, cast
+
+from mcp.shared.path_security import PathEscapeError, safe_join
+from pydantic import AnyUrl
+
+from fastmcp.resources.base import Resource, ResourceResult
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.providers.base import Provider
+from fastmcp.server.providers.skills._common import (
+    SkillInfo,
+    parse_frontmatter,
+    scan_skill_files,
+)
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.versions import VersionSpec
+
+logger = get_logger(__name__)
+
+# Ensure .md is recognized as text/markdown on all platforms (Windows may not have this)
+mimetypes.add_type("text/markdown", ".md")
+
+
+# -----------------------------------------------------------------------------
+# Skill-specific Resource and ResourceTemplate subclasses
+# -----------------------------------------------------------------------------
+
+
+class SkillResource(Resource):
+    """A resource representing a skill's main file or manifest."""
+
+    skill_info: SkillInfo
+    is_manifest: bool = False
+
+    def get_meta(self) -> dict[str, Any]:
+        meta = super().get_meta()
+        fastmcp = cast(dict[str, Any], meta["fastmcp"])
+        fastmcp["skill"] = {
+            "name": self.skill_info.name,
+            "is_manifest": self.is_manifest,
+        }
+        return meta
+
+    async def read(self) -> str | bytes | ResourceResult:
+        """Read the resource content."""
+        if self.is_manifest:
+            return self._generate_manifest()
+        else:
+            main_file_path = self.skill_info.path / self.skill_info.main_file
+            return main_file_path.read_text(encoding="utf-8")
+
+    def _generate_manifest(self) -> str:
+        """Generate JSON manifest for the skill."""
+        manifest = {
+            "skill": self.skill_info.name,
+            "files": [
+                {"path": f.path, "size": f.size, "hash": f.hash}
+                for f in self.skill_info.files
+            ],
+        }
+        return json.dumps(manifest, indent=2)
+
+
+class SkillFileTemplate(ResourceTemplate):
+    """A template for accessing files within a skill."""
+
+    skill_info: SkillInfo
+
+    async def read(self, arguments: dict[str, Any]) -> str | bytes | ResourceResult:
+        """Read a file from the skill directory."""
+        file_path = arguments.get("path", "")
+
+        # Security: reject traversal, absolute-path injection, null bytes, and
+        # symlink escapes before touching the filesystem.
+        try:
+            full_path = safe_join(self.skill_info.path, file_path)
+        except PathEscapeError as e:
+            raise ValueError(f"Invalid path: {e}") from e
+
+        if not full_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        if not full_path.is_file():
+            raise ValueError(f"Not a file: {file_path}")
+
+        # Determine if binary or text based on mime type
+        mime_type, _ = mimetypes.guess_type(str(full_path))
+        if mime_type and mime_type.startswith("text/"):
+            return full_path.read_text(encoding="utf-8")
+        else:
+            return full_path.read_bytes()
+
+    async def _read(  # type: ignore[override]
+        self,
+        uri: str,
+        params: dict[str, Any],
+        task_meta: Any = None,
+    ) -> ResourceResult:  # ty:ignore[invalid-method-override]
+        """Server entry point - read file directly without creating ephemeral resource.
+
+        Note: task_meta is ignored - this template doesn't support background tasks.
+        """
+        # Call read() directly and convert to ResourceResult
+        result = await self.read(arguments=params)
+        return self.convert_result(result)
+
+    async def create_resource(self, uri: str, params: dict[str, Any]) -> Resource:
+        """Create a resource for the given URI and parameters.
+
+        Note: This is not typically used since _read() handles file reading directly.
+        Provided for compatibility with the ResourceTemplate interface.
+        """
+        file_path = params.get("path", "")
+
+        # Security: reject traversal, absolute-path injection, null bytes, and
+        # symlink escapes before touching the filesystem.
+        try:
+            full_path = safe_join(self.skill_info.path, file_path)
+        except PathEscapeError as e:
+            raise ValueError(f"Invalid path: {e}") from e
+
+        mime_type, _ = mimetypes.guess_type(str(full_path))
+
+        # Create a SkillFileResource that can read the file
+        return SkillFileResource(
+            uri=AnyUrl(uri),
+            name=f"{self.skill_info.name}/{file_path}",
+            description=f"File from {self.skill_info.name} skill",
+            mime_type=mime_type or "application/octet-stream",
+            skill_info=self.skill_info,
+            file_path=file_path,
+        )
+
+
+class SkillFileResource(Resource):
+    """A resource representing a specific file within a skill."""
+
+    skill_info: SkillInfo
+    file_path: str
+
+    def get_meta(self) -> dict[str, Any]:
+        meta = super().get_meta()
+        fastmcp = cast(dict[str, Any], meta["fastmcp"])
+        fastmcp["skill"] = {
+            "name": self.skill_info.name,
+        }
+        return meta
+
+    async def read(self) -> str | bytes | ResourceResult:
+        """Read the file content."""
+        # Security: reject traversal, absolute-path injection, null bytes, and
+        # symlink escapes before touching the filesystem.
+        try:
+            full_path = safe_join(self.skill_info.path, self.file_path)
+        except PathEscapeError as e:
+            raise ValueError(f"Invalid path: {e}") from e
+
+        if not full_path.exists():
+            raise FileNotFoundError(f"File not found: {self.file_path}")
+
+        mime_type, _ = mimetypes.guess_type(str(full_path))
+        if mime_type and mime_type.startswith("text/"):
+            return full_path.read_text(encoding="utf-8")
+        else:
+            return full_path.read_bytes()
+
+
+# -----------------------------------------------------------------------------
+# SkillProvider - handles a SINGLE skill folder
+# -----------------------------------------------------------------------------
+
+
+class SkillProvider(Provider):
+    """Provider that exposes a single skill folder as MCP resources.
+
+    Each skill folder must contain a main file (default: SKILL.md) and may
+    contain additional supporting files.
+
+    Exposes:
+    - A Resource for the main file (skill://{name}/SKILL.md)
+    - A Resource for the synthetic manifest (skill://{name}/_manifest)
+    - Supporting files via ResourceTemplate or Resources (configurable)
+
+    Args:
+        skill_path: Path to the skill directory.
+        main_file_name: Name of the main skill file. Defaults to "SKILL.md".
+        supporting_files: How supporting files (everything except main file and
+            manifest) are exposed to clients:
+            - "template": Accessed via ResourceTemplate, hidden from list_resources().
+              Clients discover files by reading the manifest first.
+            - "resources": Each file exposed as individual Resource in list_resources().
+              Full enumeration upfront.
+
+    Example:
+        ```python
+        from pathlib import Path
+        from fastmcp import FastMCP
+        from fastmcp.server.providers.skills import SkillProvider
+
+        mcp = FastMCP("My Skill")
+        mcp.add_provider(SkillProvider(
+            Path.home() / ".claude/skills/pdf-processing"
+        ))
+        ```
+    """
+
+    def __init__(
+        self,
+        skill_path: str | Path,
+        main_file_name: str = "SKILL.md",
+        supporting_files: Literal["template", "resources"] = "template",
+    ) -> None:
+        super().__init__()
+        self._skill_path = Path(skill_path).resolve()
+        self._main_file_name = main_file_name
+        self._supporting_files = supporting_files
+        self._skill_info: SkillInfo | None = None
+
+        # Load at init to catch errors early
+        self._load_skill()
+
+    def _load_skill(self) -> None:
+        """Load and parse the skill directory."""
+        main_file = self._skill_path / self._main_file_name
+
+        if not self._skill_path.exists():
+            raise FileNotFoundError(f"Skill directory not found: {self._skill_path}")
+
+        if not main_file.exists():
+            raise FileNotFoundError(
+                f"Main skill file not found: {main_file}. "
+                f"Expected {self._main_file_name} in {self._skill_path}"
+            )
+
+        content = main_file.read_text(encoding="utf-8")
+        frontmatter, body = parse_frontmatter(content)
+
+        # Get description from frontmatter or first non-empty line
+        description = frontmatter.get("description", "")
+        if not description:
+            for line in body.strip().split("\n"):
+                line = line.strip()
+                if line and not line.startswith("#"):
+                    description = line[:200]
+                    break
+                elif line.startswith("#"):
+                    description = line.lstrip("#").strip()[:200]
+                    break
+
+        # Scan all files in the skill directory
+        files = scan_skill_files(self._skill_path)
+
+        self._skill_info = SkillInfo(
+            name=self._skill_path.name,
+            description=description or f"Skill: {self._skill_path.name}",
+            path=self._skill_path,
+            main_file=self._main_file_name,
+            files=files,
+            frontmatter=frontmatter,
+        )
+
+        logger.debug(f"SkillProvider loaded skill: {self._skill_info.name}")
+
+    @property
+    def skill_info(self) -> SkillInfo:
+        """Get the loaded skill info."""
+        if self._skill_info is None:
+            raise RuntimeError("Skill not loaded")
+        return self._skill_info
+
+    # -------------------------------------------------------------------------
+    # Provider interface implementation
+    # -------------------------------------------------------------------------
+
+    async def _list_resources(self) -> Sequence[Resource]:
+        """List skill resources."""
+        skill = self.skill_info
+        resources: list[Resource] = []
+
+        # Main skill file
+        resources.append(
+            SkillResource(
+                uri=AnyUrl(f"skill://{skill.name}/{self._main_file_name}"),
+                name=f"{skill.name}/{self._main_file_name}",
+                description=skill.description,
+                mime_type="text/markdown",
+                skill_info=skill,
+                is_manifest=False,
+            )
+        )
+
+        # Synthetic manifest
+        resources.append(
+            SkillResource(
+                uri=AnyUrl(f"skill://{skill.name}/_manifest"),
+                name=f"{skill.name}/_manifest",
+                description=f"File listing for {skill.name}",
+                mime_type="application/json",
+                skill_info=skill,
+                is_manifest=True,
+            )
+        )
+
+        # If supporting_files="resources", add all supporting files as resources
+        if self._supporting_files == "resources":
+            for file_info in skill.files:
+                # Skip main file and manifest (already added)
+                if file_info.path == self._main_file_name:
+                    continue
+
+                mime_type, _ = mimetypes.guess_type(file_info.path)
+                resources.append(
+                    SkillFileResource(
+                        uri=AnyUrl(f"skill://{skill.name}/{file_info.path}"),
+                        name=f"{skill.name}/{file_info.path}",
+                        description=f"File from {skill.name} skill",
+                        mime_type=mime_type or "application/octet-stream",
+                        skill_info=skill,
+                        file_path=file_info.path,
+                    )
+                )
+
+        return resources
+
+    async def _get_resource(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> Resource | None:
+        """Get a resource by URI."""
+        skill = self.skill_info
+
+        # Parse URI: skill://{skill_name}/{file_path}
+        if not uri.startswith("skill://"):
+            return None
+
+        path_part = uri[len("skill://") :]
+        parts = path_part.split("/", 1)
+        if len(parts) != 2:
+            return None
+
+        skill_name, file_path = parts
+        if skill_name != skill.name:
+            return None
+
+        if file_path == "_manifest":
+            return SkillResource(
+                uri=AnyUrl(uri),
+                name=f"{skill_name}/_manifest",
+                description=f"File listing for {skill_name}",
+                mime_type="application/json",
+                skill_info=skill,
+                is_manifest=True,
+            )
+        elif file_path == self._main_file_name:
+            return SkillResource(
+                uri=AnyUrl(uri),
+                name=f"{skill_name}/{self._main_file_name}",
+                description=skill.description,
+                mime_type="text/markdown",
+                skill_info=skill,
+                is_manifest=False,
+            )
+        elif self._supporting_files == "resources":
+            # Check if it's a known supporting file
+            for file_info in skill.files:
+                if file_info.path == file_path:
+                    mime_type, _ = mimetypes.guess_type(file_path)
+                    return SkillFileResource(
+                        uri=AnyUrl(uri),
+                        name=f"{skill_name}/{file_path}",
+                        description=f"File from {skill_name} skill",
+                        mime_type=mime_type or "application/octet-stream",
+                        skill_info=skill,
+                        file_path=file_path,
+                    )
+
+        return None
+
+    async def _list_resource_templates(self) -> Sequence[ResourceTemplate]:
+        """List resource templates for accessing files within the skill."""
+        # Only expose template if supporting_files="template"
+        if self._supporting_files != "template":
+            return []
+
+        skill = self.skill_info
+        return [
+            SkillFileTemplate(
+                uri_template=f"skill://{skill.name}/{{path*}}",
+                name=f"{skill.name}_files",
+                description=f"Access files within {skill.name}",
+                mime_type="application/octet-stream",
+                parameters={
+                    "type": "object",
+                    "properties": {"path": {"type": "string"}},
+                    "required": ["path"],
+                },
+                skill_info=skill,
+            )
+        ]
+
+    async def _get_resource_template(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> ResourceTemplate | None:
+        """Get a resource template that matches the given URI."""
+        # Only match if supporting_files="template"
+        if self._supporting_files != "template":
+            return None
+
+        skill = self.skill_info
+
+        if not uri.startswith("skill://"):
+            return None
+
+        path_part = uri[len("skill://") :]
+        parts = path_part.split("/", 1)
+        if len(parts) != 2:
+            return None
+
+        skill_name, file_path = parts
+        if skill_name != skill.name:
+            return None
+
+        # Don't match known resources (main file, manifest)
+        if file_path == "_manifest" or file_path == self._main_file_name:
+            return None
+
+        return SkillFileTemplate(
+            uri_template=f"skill://{skill.name}/{{path*}}",
+            name=f"{skill.name}_files",
+            description=f"Access files within {skill.name}",
+            mime_type="application/octet-stream",
+            parameters={
+                "type": "object",
+                "properties": {"path": {"type": "string"}},
+                "required": ["path"],
+            },
+            skill_info=skill,
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"SkillProvider(skill_path={self._skill_path!r}, "
+            f"supporting_files={self._supporting_files!r})"
+        )
diff --git a/fastmcp_slim/fastmcp/server/providers/skills/vendor_providers.py b/fastmcp_slim/fastmcp/server/providers/skills/vendor_providers.py
new file mode 100644
index 0000000..df870f1
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/skills/vendor_providers.py
@@ -0,0 +1,142 @@
+"""Vendor-specific skills providers for various AI coding platforms."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from fastmcp.server.providers.skills.directory_provider import SkillsDirectoryProvider
+
+
+class CursorSkillsProvider(SkillsDirectoryProvider):
+    """Cursor skills from ~/.cursor/skills/."""
+
+    def __init__(
+        self,
+        reload: bool = False,
+        supporting_files: Literal["template", "resources"] = "template",
+    ) -> None:
+        root = Path.home() / ".cursor" / "skills"
+
+        super().__init__(
+            roots=[root],
+            reload=reload,
+            main_file_name="SKILL.md",
+            supporting_files=supporting_files,
+        )
+
+
+class VSCodeSkillsProvider(SkillsDirectoryProvider):
+    """VS Code skills from ~/.copilot/skills/."""
+
+    def __init__(
+        self,
+        reload: bool = False,
+        supporting_files: Literal["template", "resources"] = "template",
+    ) -> None:
+        root = Path.home() / ".copilot" / "skills"
+
+        super().__init__(
+            roots=[root],
+            reload=reload,
+            main_file_name="SKILL.md",
+            supporting_files=supporting_files,
+        )
+
+
+class CodexSkillsProvider(SkillsDirectoryProvider):
+    """Codex skills from /etc/codex/skills/ and ~/.codex/skills/.
+
+    Scans both system-level and user-level directories. System skills take
+    precedence if duplicates exist.
+    """
+
+    def __init__(
+        self,
+        reload: bool = False,
+        supporting_files: Literal["template", "resources"] = "template",
+    ) -> None:
+        system_root = Path("/etc/codex/skills")
+        user_root = Path.home() / ".codex" / "skills"
+
+        # Include both paths (system first, then user)
+        roots = [system_root, user_root]
+
+        super().__init__(
+            roots=roots,
+            reload=reload,
+            main_file_name="SKILL.md",
+            supporting_files=supporting_files,
+        )
+
+
+class GeminiSkillsProvider(SkillsDirectoryProvider):
+    """Gemini skills from ~/.gemini/skills/."""
+
+    def __init__(
+        self,
+        reload: bool = False,
+        supporting_files: Literal["template", "resources"] = "template",
+    ) -> None:
+        root = Path.home() / ".gemini" / "skills"
+
+        super().__init__(
+            roots=[root],
+            reload=reload,
+            main_file_name="SKILL.md",
+            supporting_files=supporting_files,
+        )
+
+
+class GooseSkillsProvider(SkillsDirectoryProvider):
+    """Goose skills from ~/.config/agents/skills/."""
+
+    def __init__(
+        self,
+        reload: bool = False,
+        supporting_files: Literal["template", "resources"] = "template",
+    ) -> None:
+        root = Path.home() / ".config" / "agents" / "skills"
+
+        super().__init__(
+            roots=[root],
+            reload=reload,
+            main_file_name="SKILL.md",
+            supporting_files=supporting_files,
+        )
+
+
+class CopilotSkillsProvider(SkillsDirectoryProvider):
+    """GitHub Copilot skills from ~/.copilot/skills/."""
+
+    def __init__(
+        self,
+        reload: bool = False,
+        supporting_files: Literal["template", "resources"] = "template",
+    ) -> None:
+        root = Path.home() / ".copilot" / "skills"
+
+        super().__init__(
+            roots=[root],
+            reload=reload,
+            main_file_name="SKILL.md",
+            supporting_files=supporting_files,
+        )
+
+
+class OpenCodeSkillsProvider(SkillsDirectoryProvider):
+    """OpenCode skills from ~/.config/opencode/skills/."""
+
+    def __init__(
+        self,
+        reload: bool = False,
+        supporting_files: Literal["template", "resources"] = "template",
+    ) -> None:
+        root = Path.home() / ".config" / "opencode" / "skills"
+
+        super().__init__(
+            roots=[root],
+            reload=reload,
+            main_file_name="SKILL.md",
+            supporting_files=supporting_files,
+        )
diff --git a/fastmcp_slim/fastmcp/server/providers/wrapped_provider.py b/fastmcp_slim/fastmcp/server/providers/wrapped_provider.py
new file mode 100644
index 0000000..f33e9d5
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/providers/wrapped_provider.py
@@ -0,0 +1,148 @@
+"""WrappedProvider for immutable transform composition.
+
+This module provides `_WrappedProvider`, an internal class that wraps a provider
+with an additional transform. Created by `Provider.wrap_transform()`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Sequence
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING
+
+from fastmcp.server.providers.base import Provider
+from fastmcp.utilities.versions import VersionSpec
+
+if TYPE_CHECKING:
+    from fastmcp.prompts.base import Prompt
+    from fastmcp.resources.base import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.server.transforms import Transform
+    from fastmcp.tools.base import Tool
+    from fastmcp.utilities.components import FastMCPComponent
+
+
+class _WrappedProvider(Provider):
+    """Internal provider that wraps another provider with a transform.
+
+    Created by Provider.wrap_transform(). Delegates all component sourcing
+    to the inner provider's public methods (which apply inner's transforms),
+    then applies the wrapper's transform on top.
+
+    This enables immutable transform composition - the inner provider is
+    unchanged, and the wrapper adds its transform layer.
+    """
+
+    def __init__(self, inner: Provider, transform: Transform) -> None:
+        """Initialize wrapped provider.
+
+        Args:
+            inner: The provider to wrap.
+            transform: The transform to apply on top of inner's results.
+        """
+        super().__init__()
+        self._inner = inner
+        # Add the transform to this provider's transform list
+        # It will be applied via the normal transform chain
+        self._transforms.append(transform)
+
+    def __repr__(self) -> str:
+        return f"_WrappedProvider({self._inner!r}, transforms={self._transforms!r})"
+
+    # -------------------------------------------------------------------------
+    # Delegate to inner provider's public methods (which apply inner's transforms)
+    # -------------------------------------------------------------------------
+
+    async def _list_tools(self) -> Sequence[Tool]:
+        """Delegate to inner's list_tools (includes inner's transforms)."""
+        return await self._inner.list_tools()
+
+    async def _get_tool(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Delegate to inner's get_tool (includes inner's transforms)."""
+        return await self._inner.get_tool(name, version)
+
+    async def get_app_tool(self, app_name: str, tool_name: str) -> Tool | None:
+        """Delegate to inner, bypassing this wrapper's transforms."""
+        return await self._inner.get_app_tool(app_name, tool_name)
+
+    async def get_tool_by_hash(self, tool_hash: str, tool_name: str) -> Tool | None:
+        """Delegate to inner, bypassing this wrapper's transforms."""
+        return await self._inner.get_tool_by_hash(tool_hash, tool_name)
+
+    async def _list_resources(self) -> Sequence[Resource]:
+        """Delegate to inner's list_resources (includes inner's transforms)."""
+        return await self._inner.list_resources()
+
+    async def _get_resource(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> Resource | None:
+        """Delegate to inner's get_resource (includes inner's transforms)."""
+        return await self._inner.get_resource(uri, version)
+
+    async def _list_resource_templates(self) -> Sequence[ResourceTemplate]:
+        """Delegate to inner's list_resource_templates (includes inner's transforms)."""
+        return await self._inner.list_resource_templates()
+
+    async def _get_resource_template(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> ResourceTemplate | None:
+        """Delegate to inner's get_resource_template (includes inner's transforms)."""
+        return await self._inner.get_resource_template(uri, version)
+
+    async def _list_prompts(self) -> Sequence[Prompt]:
+        """Delegate to inner's list_prompts (includes inner's transforms)."""
+        return await self._inner.list_prompts()
+
+    async def _get_prompt(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        """Delegate to inner's get_prompt (includes inner's transforms)."""
+        return await self._inner.get_prompt(name, version)
+
+    async def get_tasks(self) -> Sequence[FastMCPComponent]:
+        """Delegate to inner's get_tasks and apply wrapper's transforms."""
+        # Import here to avoid circular imports
+        from fastmcp.prompts.base import Prompt
+        from fastmcp.resources.base import Resource
+        from fastmcp.resources.template import ResourceTemplate
+        from fastmcp.tools.base import Tool
+
+        # Get tasks from inner (already has inner's transforms)
+        components = list(await self._inner.get_tasks())
+
+        # Apply this wrapper's transforms to the components
+        # We need to apply transforms per component type
+        tools = [c for c in components if isinstance(c, Tool)]
+        resources = [c for c in components if isinstance(c, Resource)]
+        templates = [c for c in components if isinstance(c, ResourceTemplate)]
+        prompts = [c for c in components if isinstance(c, Prompt)]
+
+        # Apply this wrapper's transforms sequentially
+        for transform in self.transforms:
+            tools = await transform.list_tools(tools)
+            resources = await transform.list_resources(resources)
+            templates = await transform.list_resource_templates(templates)
+            prompts = await transform.list_prompts(prompts)
+
+        return [
+            c
+            for c in [
+                *tools,
+                *resources,
+                *templates,
+                *prompts,
+            ]
+            if c.task_config.supports_tasks()
+        ]
+
+    # -------------------------------------------------------------------------
+    # Lifecycle - combine with inner
+    # -------------------------------------------------------------------------
+
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncIterator[None]:
+        """Combine lifespan with inner provider."""
+        async with self._inner.lifespan():
+            yield
diff --git a/fastmcp_slim/fastmcp/server/sampling/__init__.py b/fastmcp_slim/fastmcp/server/sampling/__init__.py
new file mode 100644
index 0000000..392326d
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/sampling/__init__.py
@@ -0,0 +1,10 @@
+"""Sampling module for FastMCP servers."""
+
+from fastmcp.server.sampling.run import SampleStep, SamplingResult
+from fastmcp.server.sampling.sampling_tool import SamplingTool
+
+__all__ = [
+    "SampleStep",
+    "SamplingResult",
+    "SamplingTool",
+]
diff --git a/fastmcp_slim/fastmcp/server/sampling/run.py b/fastmcp_slim/fastmcp/server/sampling/run.py
new file mode 100644
index 0000000..cb0a1e9
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/sampling/run.py
@@ -0,0 +1,809 @@
+"""Sampling types and helper functions for FastMCP servers."""
+
+from __future__ import annotations
+
+import inspect
+import json
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Generic, Literal, cast
+
+import anyio
+from mcp_types import (
+    ClientCapabilities,
+    CreateMessageResult,
+    CreateMessageResultWithTools,
+    ModelHint,
+    ModelPreferences,
+    SamplingCapability,
+    SamplingMessage,
+    SamplingMessageContentBlock,
+    SamplingToolsCapability,
+    TextContent,
+    ToolChoice,
+    ToolResultContent,
+    ToolUseContent,
+)
+from mcp_types import CreateMessageRequestParams as SamplingParams
+from mcp_types import Tool as SDKTool
+from opentelemetry.trace import SpanKind, Status, StatusCode
+from pydantic import ValidationError
+from typing_extensions import TypeVar
+
+from fastmcp import settings
+from fastmcp.exceptions import ToolError
+from fastmcp.server.sampling.sampling_tool import SamplingTool
+from fastmcp.telemetry import get_tracer
+from fastmcp.tools.function_tool import FunctionTool
+from fastmcp.tools.tool_transform import TransformedTool
+from fastmcp.utilities.async_utils import gather
+from fastmcp.utilities.json_schema import compress_schema
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import get_cached_typeadapter
+
+logger = get_logger(__name__)
+
+if TYPE_CHECKING:
+    from fastmcp.server.context import Context
+
+ResultT = TypeVar("ResultT")
+
+# Maximum number of consecutive final_response validation retries (not
+# counting the initial attempt) before aborting.  Total attempts = N + 1.
+_MAX_VALIDATION_RETRIES = 3
+
+# Simplified tool choice type - just the mode string instead of the full MCP object
+ToolChoiceOption = Literal["auto", "required", "none"]
+
+# How many times we retry when the LLM returns text instead of calling final_response
+_MAX_TEXT_RESPONSE_RETRIES = 3
+
+
+@dataclass
+class SamplingResult(Generic[ResultT]):
+    """Result of a sampling operation.
+
+    Attributes:
+        text: The text representation of the result (raw text or JSON for structured).
+        result: The typed result (str for text, parsed object for structured output).
+        history: All messages exchanged during sampling.
+    """
+
+    text: str | None
+    result: ResultT
+    history: list[SamplingMessage]
+
+
+@dataclass
+class SampleStep:
+    """Result of a single sampling call.
+
+    Represents what the LLM returned in this step plus the message history.
+    """
+
+    response: CreateMessageResult | CreateMessageResultWithTools
+    history: list[SamplingMessage]
+
+    @property
+    def is_tool_use(self) -> bool:
+        """True if the LLM is requesting tool execution."""
+        if isinstance(self.response, CreateMessageResultWithTools):
+            return self.response.stop_reason == "toolUse"
+        return False
+
+    @property
+    def text(self) -> str | None:
+        """Extract text from the response, if available."""
+        content = self.response.content
+        if isinstance(content, list):
+            for block in content:
+                if isinstance(block, TextContent):
+                    return block.text
+            return None
+        elif isinstance(content, TextContent):
+            return content.text
+        return None
+
+    @property
+    def tool_calls(self) -> list[ToolUseContent]:
+        """Get the list of tool calls from the response."""
+        content = self.response.content
+        if isinstance(content, list):
+            return [c for c in content if isinstance(c, ToolUseContent)]
+        elif isinstance(content, ToolUseContent):
+            return [content]
+        return []
+
+
+def _parse_model_preferences(
+    model_preferences: ModelPreferences | str | list[str] | None,
+) -> ModelPreferences | None:
+    """Convert model preferences to ModelPreferences object."""
+    if model_preferences is None:
+        return None
+    elif isinstance(model_preferences, ModelPreferences):
+        return model_preferences
+    elif isinstance(model_preferences, str):
+        return ModelPreferences(hints=[ModelHint(name=model_preferences)])
+    elif isinstance(model_preferences, list):
+        if not all(isinstance(h, str) for h in model_preferences):
+            raise ValueError("All elements of model_preferences list must be strings.")
+        return ModelPreferences(hints=[ModelHint(name=h) for h in model_preferences])
+    else:
+        raise ValueError(
+            "model_preferences must be one of: ModelPreferences, str, list[str], or None."
+        )
+
+
+# --- Standalone functions for sample_step() ---
+
+
+def determine_handler_mode(
+    context: Context, needs_tools: bool, *, client_available: bool = True
+) -> bool:
+    """Determine whether to use fallback handler or client for sampling.
+
+    Args:
+        context: The MCP context.
+        needs_tools: Whether the sampling request requires tool support.
+        client_available: Whether the client back-channel can be reached at all.
+            On modern (2026-07-28) connections the server-initiated createMessage
+            back-channel was removed (SEP-2577), so the client can never serve a
+            sampling request; pass False there to force the server-side handler
+            path (``"fallback"`` behaves like ``"always"`` when a handler exists).
+
+    Returns:
+        True if fallback handler should be used, False to use client.
+
+    Raises:
+        ValueError: If client lacks required capability and no fallback configured.
+    """
+    fastmcp = context.fastmcp
+    session = context.session
+
+    # Check what capabilities the client has. On connections without a
+    # back-channel the client can never serve the request regardless of the
+    # capabilities it advertised, so treat both as unavailable.
+    has_sampling = client_available and session.check_client_capability(
+        capability=ClientCapabilities(sampling=SamplingCapability())
+    )
+    has_tools_capability = client_available and session.check_client_capability(
+        capability=ClientCapabilities(
+            sampling=SamplingCapability(tools=SamplingToolsCapability())
+        )
+    )
+
+    if fastmcp.sampling_handler_behavior == "always":
+        if fastmcp.sampling_handler is None:
+            raise ValueError(
+                "sampling_handler_behavior is 'always' but no handler configured"
+            )
+        return True
+    elif fastmcp.sampling_handler_behavior == "fallback":
+        client_sufficient = has_sampling and (not needs_tools or has_tools_capability)
+        if not client_sufficient:
+            if fastmcp.sampling_handler is None:
+                if needs_tools and has_sampling and not has_tools_capability:
+                    raise ValueError(
+                        "Client does not support sampling with tools. "
+                        "The client must advertise the sampling.tools capability."
+                    )
+                raise ValueError("Client does not support sampling")
+            return True
+    elif fastmcp.sampling_handler_behavior is not None:
+        raise ValueError(
+            f"Invalid sampling_handler_behavior: {fastmcp.sampling_handler_behavior!r}. "
+            "Must be 'always', 'fallback', or None."
+        )
+    elif not has_sampling:
+        raise ValueError("Client does not support sampling")
+    elif needs_tools and not has_tools_capability:
+        raise ValueError(
+            "Client does not support sampling with tools. "
+            "The client must advertise the sampling.tools capability."
+        )
+
+    return False
+
+
+async def call_sampling_handler(
+    context: Context,
+    messages: list[SamplingMessage],
+    *,
+    system_prompt: str | None,
+    temperature: float | None,
+    max_tokens: int,
+    model_preferences: ModelPreferences | str | list[str] | None,
+    sdk_tools: list[SDKTool] | None,
+    tool_choice: ToolChoice | None,
+) -> CreateMessageResult | CreateMessageResultWithTools:
+    """Make LLM call using the fallback handler.
+
+    Note: This function expects the caller (sample_step) to have validated that
+    sampling_handler is set via determine_handler_mode(). The checks below are
+    safeguards against internal misuse.
+    """
+    if context.fastmcp.sampling_handler is None:
+        raise RuntimeError("sampling_handler is None")
+    if context.request_context is None:
+        raise RuntimeError("request_context is None")
+
+    result = context.fastmcp.sampling_handler(
+        messages,
+        SamplingParams(
+            system_prompt=system_prompt,
+            messages=messages,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            model_preferences=_parse_model_preferences(model_preferences),
+            tools=sdk_tools,
+            tool_choice=tool_choice,
+        ),
+        # SamplingHandler is typed against the SDK's RequestContext placeholder,
+        # but FastMCP hands handlers its own FastMCPRequestContext wrapper at
+        # runtime; the two aren't structurally related in the type system.
+        context.request_context,  # ty: ignore[invalid-argument-type]
+    )
+
+    if inspect.isawaitable(result):
+        result = await result
+
+    result = cast("str | CreateMessageResult | CreateMessageResultWithTools", result)
+
+    # Convert string to CreateMessageResult
+    if isinstance(result, str):
+        return CreateMessageResult(
+            role="assistant",
+            content=TextContent(type="text", text=result),
+            model="unknown",
+            stop_reason="endTurn",
+        )
+
+    return result
+
+
+async def execute_tools(
+    tool_calls: list[ToolUseContent],
+    tool_map: dict[str, SamplingTool],
+    mask_error_details: bool = False,
+    tool_concurrency: int | None = None,
+) -> list[ToolResultContent]:
+    """Execute tool calls and return results.
+
+    Args:
+        tool_calls: List of tool use requests from the LLM.
+        tool_map: Mapping from tool name to SamplingTool.
+        mask_error_details: If True, mask detailed error messages from tool execution.
+            When masked, only generic error messages are returned to the LLM.
+            Tools can explicitly raise ToolError to bypass masking when they want
+            to provide specific error messages to the LLM.
+        tool_concurrency: Controls parallel execution of tools:
+            - None (default): Sequential execution (one at a time)
+            - 0: Unlimited parallel execution
+            - N > 0: Execute at most N tools concurrently
+            If any tool has sequential=True, all tools execute sequentially
+            regardless of this setting.
+
+    Returns:
+        List of tool result content blocks in the same order as tool_calls.
+    """
+    if tool_concurrency is not None and tool_concurrency < 0:
+        raise ValueError(
+            f"tool_concurrency must be None, 0 (unlimited), or a positive integer, "
+            f"got {tool_concurrency}"
+        )
+
+    async def _execute_single_tool(tool_use: ToolUseContent) -> ToolResultContent:
+        """Execute a single tool and return its result."""
+        tool = tool_map.get(tool_use.name)
+        if tool is None:
+            return ToolResultContent(
+                type="tool_result",
+                tool_use_id=tool_use.id,
+                content=[
+                    TextContent(
+                        type="text",
+                        text=f"Error: Unknown tool '{tool_use.name}'",
+                    )
+                ],
+                is_error=True,
+            )
+
+        tracer = get_tracer()
+        with tracer.start_as_current_span(
+            f"sampling tool {tool_use.name}",
+            kind=SpanKind.INTERNAL,
+        ) as span:
+            if span.is_recording():
+                span.set_attribute("gen_ai.tool.name", tool_use.name)
+                span.set_attribute("fastmcp.tool.use_id", tool_use.id)
+            try:
+                result_value = await tool.run(tool_use.input)
+                return ToolResultContent(
+                    type="tool_result",
+                    tool_use_id=tool_use.id,
+                    content=[TextContent(type="text", text=str(result_value))],
+                )
+            except ToolError as e:
+                if span.is_recording():
+                    span.set_attribute("error.type", "tool_error")
+                    span.record_exception(e)
+                    span.set_status(Status(StatusCode.ERROR, str(e)))
+                logger.log(
+                    e.log_level,
+                    f"Error calling sampling tool '{tool_use.name}'",
+                    exc_info=True,
+                )
+                return ToolResultContent(
+                    type="tool_result",
+                    tool_use_id=tool_use.id,
+                    content=[TextContent(type="text", text=str(e))],
+                    is_error=True,
+                )
+            except Exception as e:
+                if span.is_recording():
+                    span.set_attribute("error.type", type(e).__qualname__)
+                    span.record_exception(e)
+                    span.set_status(Status(StatusCode.ERROR, str(e)))
+                logger.exception(f"Error calling sampling tool '{tool_use.name}'")
+                if mask_error_details:
+                    error_text = f"Error executing tool '{tool_use.name}'"
+                else:
+                    error_text = f"Error executing tool '{tool_use.name}': {e}"
+                return ToolResultContent(
+                    type="tool_result",
+                    tool_use_id=tool_use.id,
+                    content=[TextContent(type="text", text=error_text)],
+                    is_error=True,
+                )
+
+    # Check if any tool requires sequential execution
+    requires_sequential = any(
+        tool.sequential
+        for tool_use in tool_calls
+        if (tool := tool_map.get(tool_use.name)) is not None
+    )
+
+    # Execute sequentially if required or if concurrency is None (default)
+    if tool_concurrency is None or requires_sequential:
+        tool_results: list[ToolResultContent] = []
+        for tool_use in tool_calls:
+            result = await _execute_single_tool(tool_use)
+            tool_results.append(result)
+        return tool_results
+
+    # Execute in parallel
+    if tool_concurrency == 0:
+        # Unlimited parallel execution
+        return await gather(*[_execute_single_tool(tc) for tc in tool_calls])
+    else:
+        # Bounded parallel execution with semaphore
+        semaphore = anyio.Semaphore(tool_concurrency)
+
+        async def bounded_execute(tool_use: ToolUseContent) -> ToolResultContent:
+            async with semaphore:
+                return await _execute_single_tool(tool_use)
+
+        return await gather(*[bounded_execute(tc) for tc in tool_calls])
+
+
+# --- Helper functions for sampling ---
+
+
+def prepare_messages(
+    messages: str | Sequence[str | SamplingMessage],
+) -> list[SamplingMessage]:
+    """Convert various message formats to a list of SamplingMessage objects."""
+    if isinstance(messages, str):
+        return [
+            SamplingMessage(
+                content=TextContent(text=messages, type="text"), role="user"
+            )
+        ]
+    else:
+        return [
+            SamplingMessage(content=TextContent(text=m, type="text"), role="user")
+            if isinstance(m, str)
+            else m
+            for m in messages
+        ]
+
+
+def prepare_tools(
+    tools: Sequence[SamplingTool | FunctionTool | TransformedTool | Callable[..., Any]]
+    | None,
+) -> list[SamplingTool] | None:
+    """Convert tools to SamplingTool objects.
+
+    Accepts SamplingTool instances, FunctionTool instances, TransformedTool instances,
+    or plain callable functions. FunctionTool and TransformedTool are converted using
+    from_callable_tool(), while plain functions use from_function().
+
+    Args:
+        tools: Sequence of tools to prepare. Can be SamplingTool, FunctionTool,
+            TransformedTool, or plain callable functions.
+
+    Returns:
+        List of SamplingTool instances, or None if tools is None.
+    """
+    if tools is None:
+        return None
+
+    sampling_tools: list[SamplingTool] = []
+    for t in tools:
+        if isinstance(t, SamplingTool):
+            sampling_tools.append(t)
+        elif isinstance(t, (FunctionTool, TransformedTool)):
+            sampling_tools.append(SamplingTool.from_callable_tool(t))
+        elif callable(t):
+            sampling_tools.append(SamplingTool.from_function(t))
+        else:
+            raise TypeError(
+                f"Expected SamplingTool, FunctionTool, TransformedTool, or callable, got {type(t)}"
+            )
+
+    return sampling_tools if sampling_tools else None
+
+
+def extract_tool_calls(
+    response: CreateMessageResult | CreateMessageResultWithTools,
+) -> list[ToolUseContent]:
+    """Extract tool calls from a response."""
+    content = response.content
+    if isinstance(content, list):
+        return [c for c in content if isinstance(c, ToolUseContent)]
+    elif isinstance(content, ToolUseContent):
+        return [content]
+    return []
+
+
+def create_final_response_tool(result_type: type) -> SamplingTool:
+    """Create a synthetic 'final_response' tool for structured output.
+
+    This tool is used to capture structured responses from the LLM.
+    The tool's schema is derived from the result_type.
+    """
+    type_adapter = get_cached_typeadapter(result_type)
+    schema = type_adapter.json_schema()
+    schema = compress_schema(schema, prune_titles=True)
+
+    # Tool parameters must be object-shaped. Wrap primitives in {"value": <schema>}
+    if schema.get("type") != "object":
+        schema = {
+            "type": "object",
+            "properties": {"value": schema},
+            "required": ["value"],
+        }
+
+    # The fn just returns the input as-is (validation happens in the loop)
+    def final_response(**kwargs: Any) -> dict[str, Any]:
+        return kwargs
+
+    return SamplingTool(
+        name="final_response",
+        description=(
+            "Call this tool to provide your final response. "
+            "Use this when you have completed the task and are ready to return the result."
+        ),
+        parameters=schema,
+        fn=final_response,
+    )
+
+
+# --- Implementation functions for Context methods ---
+
+
+async def sample_step_impl(
+    context: Context,
+    messages: str | Sequence[str | SamplingMessage],
+    *,
+    system_prompt: str | None = None,
+    temperature: float | None = None,
+    max_tokens: int | None = None,
+    model_preferences: ModelPreferences | str | list[str] | None = None,
+    tools: Sequence[SamplingTool | FunctionTool | TransformedTool | Callable[..., Any]]
+    | None = None,
+    tool_choice: ToolChoiceOption | str | None = None,
+    auto_execute_tools: bool = True,
+    mask_error_details: bool | None = None,
+    tool_concurrency: int | None = None,
+    client_available: bool = True,
+) -> SampleStep:
+    """Implementation of Context.sample_step().
+
+    Make a single LLM sampling call. This is a stateless function that makes
+    exactly one LLM call and optionally executes any requested tools.
+
+    When ``client_available`` is False (e.g. a modern 2026-07-28 connection with
+    no back-channel), the client is never used and a configured sampling handler
+    serves the request; the caller is responsible for raising a clear era error
+    when no handler can serve it.
+    """
+    # Convert messages to SamplingMessage objects
+    current_messages = prepare_messages(messages)
+
+    # Convert tools to SamplingTools
+    sampling_tools = prepare_tools(tools)
+    sdk_tools: list[SDKTool] | None = (
+        [t._to_sdk_tool() for t in sampling_tools] if sampling_tools else None
+    )
+    tool_map: dict[str, SamplingTool] = (
+        {t.name: t for t in sampling_tools} if sampling_tools else {}
+    )
+
+    # Determine whether to use fallback handler or client
+    use_fallback = determine_handler_mode(
+        context, bool(sampling_tools), client_available=client_available
+    )
+
+    # Build tool choice
+    effective_tool_choice: ToolChoice | None = None
+    if tool_choice is not None:
+        if tool_choice not in ("auto", "required", "none"):
+            raise ValueError(
+                f"Invalid tool_choice: {tool_choice!r}. "
+                "Must be 'auto', 'required', or 'none'."
+            )
+        effective_tool_choice = ToolChoice(
+            mode=cast(Literal["auto", "required", "none"], tool_choice)
+        )
+
+    # Effective max_tokens
+    effective_max_tokens = max_tokens if max_tokens is not None else 512
+
+    # Make the LLM call
+    tracer = get_tracer()
+    with tracer.start_as_current_span(
+        "sampling create_message",
+        kind=SpanKind.CLIENT,
+        record_exception=False,
+        set_status_on_exception=False,
+    ) as span:
+        if span.is_recording():
+            span.set_attribute("mcp.method.name", "sampling/createMessage")
+            span.set_attribute("fastmcp.server.name", context.fastmcp.name)
+        try:
+            if use_fallback:
+                response = await call_sampling_handler(
+                    context,
+                    current_messages,
+                    system_prompt=system_prompt,
+                    temperature=temperature,
+                    max_tokens=effective_max_tokens,
+                    model_preferences=model_preferences,
+                    sdk_tools=sdk_tools,
+                    tool_choice=effective_tool_choice,
+                )
+            else:
+                # Deprecated upstream in SDK v2 but deliberately kept per compat
+                # directive; removed with the multi-round-trip follow-up.
+                response = await context.session.create_message(  # ty: ignore[deprecated]
+                    messages=current_messages,
+                    system_prompt=system_prompt,
+                    temperature=temperature,
+                    max_tokens=effective_max_tokens,
+                    model_preferences=_parse_model_preferences(model_preferences),
+                    tools=sdk_tools,
+                    tool_choice=effective_tool_choice,
+                    related_request_id=context.origin_request_id,
+                )
+        except Exception as e:
+            if span.is_recording():
+                span.set_attribute("error.type", type(e).__qualname__)
+                span.record_exception(e)
+                span.set_status(Status(StatusCode.ERROR, str(e)))
+            raise
+
+    # Check if this is a tool use response
+    is_tool_use_response = (
+        isinstance(response, CreateMessageResultWithTools)
+        and response.stop_reason == "toolUse"
+    )
+
+    # Always include the assistant response in history
+    current_messages.append(SamplingMessage(role="assistant", content=response.content))
+
+    # If not a tool use, return immediately
+    if not is_tool_use_response:
+        return SampleStep(response=response, history=current_messages)
+
+    # If not executing tools, return with assistant message but no tool results
+    if not auto_execute_tools:
+        return SampleStep(response=response, history=current_messages)
+
+    # Execute tools and add results to history
+    step_tool_calls = extract_tool_calls(response)
+    if step_tool_calls:
+        effective_mask = (
+            mask_error_details
+            if mask_error_details is not None
+            else settings.mask_error_details
+        )
+        tool_results: list[ToolResultContent] = await execute_tools(
+            step_tool_calls,
+            tool_map,
+            mask_error_details=effective_mask,
+            tool_concurrency=tool_concurrency,
+        )
+
+        if tool_results:
+            current_messages.append(
+                SamplingMessage(
+                    role="user",
+                    content=cast(list[SamplingMessageContentBlock], tool_results),
+                )
+            )
+
+    return SampleStep(response=response, history=current_messages)
+
+
+async def sample_impl(
+    context: Context,
+    messages: str | Sequence[str | SamplingMessage],
+    *,
+    system_prompt: str | None = None,
+    temperature: float | None = None,
+    max_tokens: int | None = None,
+    model_preferences: ModelPreferences | str | list[str] | None = None,
+    tools: Sequence[SamplingTool | FunctionTool | TransformedTool | Callable[..., Any]]
+    | None = None,
+    result_type: type[ResultT] | None = None,
+    mask_error_details: bool | None = None,
+    tool_concurrency: int | None = None,
+    client_available: bool = True,
+) -> SamplingResult[ResultT]:
+    """Implementation of Context.sample().
+
+    Send a sampling request to the client and await the response. This method
+    runs to completion automatically, executing a tool loop until the LLM
+    provides a final text response.
+
+    When ``client_available`` is False (e.g. a modern 2026-07-28 connection with
+    no back-channel), the client is never used and a configured sampling handler
+    serves the request; the caller is responsible for raising a clear era error
+    when no handler can serve it.
+    """
+    # Safety limit to prevent infinite loops
+    max_iterations = 100
+
+    # Convert tools to SamplingTools
+    sampling_tools = prepare_tools(tools)
+
+    # Handle structured output with result_type
+    tool_choice: str | None = None
+    if result_type is not None and result_type is not str:
+        final_response_tool = create_final_response_tool(result_type)
+        sampling_tools = list(sampling_tools) if sampling_tools else []
+        sampling_tools.append(final_response_tool)
+
+        # Always require tool calls when result_type is set - the LLM must
+        # eventually call final_response (text responses are not accepted)
+        tool_choice = "required"
+
+    # Convert messages for the loop
+    current_messages: str | Sequence[str | SamplingMessage] = messages
+
+    text_response_retries = 0
+    consecutive_validation_failures = 0
+
+    for _iteration in range(max_iterations):
+        step = await sample_step_impl(
+            context,
+            messages=current_messages,
+            system_prompt=system_prompt,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            model_preferences=model_preferences,
+            tools=sampling_tools,
+            tool_choice=tool_choice,
+            mask_error_details=mask_error_details,
+            tool_concurrency=tool_concurrency,
+            client_available=client_available,
+        )
+
+        # Check for final_response tool call for structured output
+        had_final_response = False
+        if result_type is not None and result_type is not str and step.is_tool_use:
+            for tool_call in step.tool_calls:
+                if tool_call.name == "final_response":
+                    had_final_response = True
+                    # Validate and return the structured result
+                    type_adapter = get_cached_typeadapter(result_type)
+
+                    # Unwrap if we wrapped primitives (non-object schemas)
+                    input_data = tool_call.input
+                    original_schema = compress_schema(
+                        type_adapter.json_schema(), prune_titles=True
+                    )
+                    if (
+                        original_schema.get("type") != "object"
+                        and isinstance(input_data, dict)
+                        and "value" in input_data
+                    ):
+                        input_data = input_data["value"]
+
+                    try:
+                        validated_result = type_adapter.validate_python(input_data)
+                        text = json.dumps(
+                            type_adapter.dump_python(validated_result, mode="json")
+                        )
+                        return SamplingResult(
+                            text=text,
+                            result=validated_result,
+                            history=step.history,
+                        )
+                    except ValidationError as e:
+                        consecutive_validation_failures += 1
+                        if consecutive_validation_failures > _MAX_VALIDATION_RETRIES:
+                            raise RuntimeError(
+                                f"Structured output validation failed "
+                                f"{consecutive_validation_failures} consecutive "
+                                f"times for type {result_type.__name__}: {e}"
+                            ) from e
+                        # Validation failed - add error as tool result
+                        step.history.append(
+                            SamplingMessage(
+                                role="user",
+                                content=[
+                                    ToolResultContent(
+                                        type="tool_result",
+                                        tool_use_id=tool_call.id,
+                                        content=[
+                                            TextContent(
+                                                type="text",
+                                                text=(
+                                                    f"Validation error: {e}. "
+                                                    "Please try again with valid data."
+                                                ),
+                                            )
+                                        ],
+                                        is_error=True,
+                                    )
+                                ],
+                            )
+                        )
+
+        # The LLM called tools but not final_response — reset validation counter
+        if not had_final_response:
+            consecutive_validation_failures = 0
+
+        # If not a tool use response, we're done
+        if not step.is_tool_use:
+            # For structured output, the LLM must use the final_response tool
+            if result_type is not None and result_type is not str:
+                text_response_retries += 1
+                if text_response_retries > _MAX_TEXT_RESPONSE_RETRIES:
+                    raise RuntimeError(
+                        f"Expected structured output of type {result_type.__name__}, "
+                        "but the LLM returned a text response instead of calling "
+                        f"the final_response tool ({text_response_retries} attempts)."
+                    )
+                # Nudge the LLM to use the tool
+                step.history.append(
+                    SamplingMessage(
+                        role="user",
+                        content=TextContent(
+                            type="text",
+                            text=(
+                                "You must call the `final_response` tool to provide "
+                                "your answer. Do not respond with text — use the tool."
+                            ),
+                        ),
+                    )
+                )
+                current_messages = step.history
+                continue
+            return SamplingResult(
+                text=step.text,
+                result=cast(ResultT, step.text if step.text else ""),
+                history=step.history,
+            )
+
+        # Continue with the updated history
+        current_messages = step.history
+
+        # After first iteration, reset tool_choice to auto (unless structured output is required)
+        if result_type is None or result_type is str:
+            tool_choice = None
+
+    raise RuntimeError(f"Sampling exceeded maximum iterations ({max_iterations})")
diff --git a/fastmcp_slim/fastmcp/server/sampling/sampling_tool.py b/fastmcp_slim/fastmcp/server/sampling/sampling_tool.py
new file mode 100644
index 0000000..05063dc
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/sampling/sampling_tool.py
@@ -0,0 +1,204 @@
+"""SamplingTool for use during LLM sampling requests."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from mcp_types import TextContent
+from mcp_types import Tool as SDKTool
+from pydantic import ConfigDict
+
+from fastmcp.exceptions import AuthorizationError
+from fastmcp.server.auth.authorization import AuthContext, run_auth_checks
+from fastmcp.server.dependencies import get_access_token
+from fastmcp.tools.base import ToolResult
+from fastmcp.tools.function_parsing import ParsedFunction
+from fastmcp.tools.function_tool import FunctionTool
+from fastmcp.tools.tool_transform import TransformedTool
+from fastmcp.utilities.types import FastMCPBaseModel
+
+
+class SamplingTool(FastMCPBaseModel):
+    """A tool that can be used during LLM sampling.
+
+    SamplingTools bundle a tool's schema (name, description, parameters) with
+    an executor function, enabling servers to execute agentic workflows where
+    the LLM can request tool calls during sampling.
+
+    In most cases, pass functions directly to ctx.sample():
+
+        def search(query: str) -> str:
+            '''Search the web.'''
+            return web_search(query)
+
+        result = await context.sample(
+            messages="Find info about Python",
+            tools=[search],  # Plain functions work directly
+        )
+
+    Create a SamplingTool explicitly when you need custom name/description:
+
+        tool = SamplingTool.from_function(search, name="web_search")
+    """
+
+    name: str
+    description: str | None = None
+    parameters: dict[str, Any]
+    fn: Callable[..., Any]
+    sequential: bool = False
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    async def run(self, arguments: dict[str, Any] | None = None) -> Any:
+        """Execute the tool with the given arguments.
+
+        Args:
+            arguments: Dictionary of arguments to pass to the tool function.
+
+        Returns:
+            The result of executing the tool function.
+        """
+        if arguments is None:
+            arguments = {}
+
+        result = self.fn(**arguments)
+        if inspect.isawaitable(result):
+            result = await result
+        return result
+
+    def _to_sdk_tool(self) -> SDKTool:
+        """Convert to an mcp_types.Tool for SDK compatibility.
+
+        This is used internally when passing tools to the MCP SDK's
+        create_message() method.
+        """
+        return SDKTool(
+            name=self.name,
+            description=self.description,
+            input_schema=self.parameters,
+        )
+
+    @classmethod
+    def from_function(
+        cls,
+        fn: Callable[..., Any],
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        sequential: bool = False,
+    ) -> SamplingTool:
+        """Create a SamplingTool from a function.
+
+        The function's signature is analyzed to generate a JSON schema for
+        the tool's parameters. Type hints are used to determine parameter types.
+
+        Args:
+            fn: The function to create a tool from.
+            name: Optional name override. Defaults to the function's name.
+            description: Optional description override. Defaults to the function's docstring.
+            sequential: If True, this tool requires sequential execution and prevents
+                parallel execution of all tools in the batch. Set to True for tools
+                with shared state, file writes, or other operations that cannot run
+                concurrently. Defaults to False.
+
+        Returns:
+            A SamplingTool wrapping the function.
+
+        Raises:
+            ValueError: If the function is a lambda without a name override.
+        """
+        parsed = ParsedFunction.from_function(fn, validate=True)
+
+        if name is None and parsed.name == "<lambda>":
+            raise ValueError("You must provide a name for lambda functions")
+
+        return cls(
+            name=name or parsed.name,
+            description=description if description is not None else parsed.description,
+            parameters=parsed.input_schema,
+            fn=parsed.fn,
+            sequential=sequential,
+        )
+
+    @classmethod
+    def from_callable_tool(
+        cls,
+        tool: FunctionTool | TransformedTool,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> SamplingTool:
+        """Create a SamplingTool from a FunctionTool or TransformedTool.
+
+        Reuses existing server tools in sampling contexts. For TransformedTool,
+        the tool's .run() method is used to ensure proper argument transformation,
+        and the ToolResult is automatically unwrapped.
+
+        Args:
+            tool: A FunctionTool or TransformedTool to convert.
+            name: Optional name override. Defaults to tool.name.
+            description: Optional description override. Defaults to tool.description.
+
+        Raises:
+            TypeError: If the tool is not a FunctionTool or TransformedTool.
+        """
+        # Validate that the tool is a supported type
+        if not isinstance(tool, (FunctionTool, TransformedTool)):
+            raise TypeError(
+                f"Expected FunctionTool or TransformedTool, got {type(tool).__name__}. "
+                "Only callable tools can be converted to SamplingTools."
+            )
+
+        # Both FunctionTool and TransformedTool need .run() to ensure proper
+        # result processing (serializers, output_schema, wrap-result flags)
+        async def wrapper(**kwargs: Any) -> Any:
+            # Enforce per-tool auth checks, mirroring what the server
+            # dispatcher does for direct tool calls.  Without this, an
+            # auth-protected tool wrapped as a SamplingTool could be
+            # invoked by the LLM during sampling without authorization.
+            if tool.auth is not None:
+                # Late import to avoid circular import with context.py
+                from fastmcp.server.context import _current_transport
+
+                is_stdio = _current_transport.get() == "stdio"
+                if not is_stdio:
+                    token = get_access_token()
+                    ctx = AuthContext(token=token, component=tool)
+                    if not await run_auth_checks(tool.auth, ctx):
+                        raise AuthorizationError(
+                            f"Authorization failed for tool '{tool.name}': "
+                            "insufficient permissions"
+                        )
+
+            result = await tool.run(kwargs)
+            # Unwrap ToolResult - extract the actual value
+            if isinstance(result, ToolResult):
+                # If there's structured_content, use that
+                if result.structured_content is not None:
+                    # Check tool's schema - this is the source of truth
+                    if tool.output_schema and tool.output_schema.get(
+                        "x-fastmcp-wrap-result"
+                    ):
+                        # Tool wraps results: {"result": value} -> value
+                        return result.structured_content.get("result")
+                    else:
+                        # No wrapping: use structured_content directly
+                        return result.structured_content
+                # Otherwise, extract from text content
+                if result.content and len(result.content) > 0:
+                    first_content = result.content[0]
+                    if isinstance(first_content, TextContent):
+                        return first_content.text
+            return result
+
+        fn = wrapper
+
+        # Extract the callable function, name, description, and parameters
+        return cls(
+            name=name or tool.name,
+            description=description or tool.description,
+            parameters=tool.parameters,
+            fn=fn,
+        )
diff --git a/fastmcp_slim/fastmcp/server/server.py b/fastmcp_slim/fastmcp/server/server.py
new file mode 100644
index 0000000..aea64f1
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/server.py
@@ -0,0 +1,2316 @@
+"""FastMCP - A more ergonomic interface for MCP servers."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import secrets
+from collections.abc import (
+    AsyncIterator,
+    Callable,
+    Sequence,
+)
+from contextlib import (
+    AbstractAsyncContextManager,
+    asynccontextmanager,
+)
+from dataclasses import replace
+from functools import partial
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar, cast, overload
+
+import httpx
+import mcp_types
+from key_value.aio.adapters.pydantic import PydanticAdapter
+from key_value.aio.protocols import AsyncKeyValue
+from key_value.aio.stores.memory import MemoryStore
+from mcp.server.lowlevel.server import LifespanResultT
+from mcp.shared.exceptions import MCPError
+from mcp_types import (
+    Annotations,
+    CallToolRequestParams,
+    ToolAnnotations,
+)
+from pydantic import AnyUrl
+from pydantic import ValidationError as PydanticValidationError
+from starlette.routing import BaseRoute
+from typing_extensions import Self
+
+import fastmcp
+import fastmcp.server
+from fastmcp.apps.config import (
+    AppConfig,
+    app_config_to_meta_dict,
+    resolve_ui_mime_type,
+)
+from fastmcp.exceptions import (
+    AuthorizationError,
+    FastMCPError,
+    NotFoundError,
+    PromptError,
+    ResourceError,
+    ToolError,
+    ValidationError,
+)
+from fastmcp.mcp_config import MCPConfig
+from fastmcp.prompts import Prompt
+from fastmcp.prompts.base import PromptResult
+from fastmcp.prompts.function_prompt import FunctionPrompt
+from fastmcp.resources.base import Resource, ResourceResult
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.auth import AuthCheck, AuthContext, AuthProvider, run_auth_checks
+from fastmcp.server.caching import build_cache_hints
+from fastmcp.server.lifespan import Lifespan
+from fastmcp.server.low_level import LowLevelServer
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.server.mixins import LifespanMixin, MCPOperationsMixin, TransportMixin
+from fastmcp.server.providers import LocalProvider, Provider
+from fastmcp.server.providers.aggregate import AggregateProvider
+from fastmcp.server.tasks.config import TaskConfig, TaskMeta
+from fastmcp.server.telemetry import server_span
+from fastmcp.server.transforms import (
+    ToolTransform,
+    Transform,
+)
+from fastmcp.server.transforms.visibility import apply_session_transforms, is_enabled
+from fastmcp.settings import DuplicateBehavior as DuplicateBehaviorSetting
+from fastmcp.tools.base import Tool, ToolResult
+from fastmcp.tools.function_tool import FunctionTool
+from fastmcp.tools.tool_transform import ToolTransformConfig
+from fastmcp.utilities.components import FastMCPComponent, _coerce_version
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import AnyFunction, FastMCPBaseModel, NotSet, NotSetT
+from fastmcp.utilities.versions import (
+    VersionSpec,
+    version_sort_key,
+)
+
+if TYPE_CHECKING:
+    from fastmcp.client import Client
+    from fastmcp.client.client import SDKServer
+    from fastmcp.client.sampling import SamplingHandler
+    from fastmcp.client.transports import ClientTransport, ClientTransportT
+    from fastmcp.server.providers.openapi import ComponentFn as OpenAPIComponentFn
+    from fastmcp.server.providers.openapi import RouteMap
+    from fastmcp.server.providers.openapi import RouteMapFn as OpenAPIRouteMapFn
+    from fastmcp.server.providers.proxy import FastMCPProxy
+
+logger = get_logger(__name__)
+
+
+def _version_request_meta(
+    version: VersionSpec | None,
+) -> dict[str, Any] | None:
+    if version is None:
+        return None
+
+    if version.eq is not None and version.gte is None and version.lt is None:
+        version_value: str | dict[str, str] = version.eq
+    else:
+        version_value = {
+            key: value
+            for key, value in {
+                "gte": version.gte,
+                "lt": version.lt,
+                "eq": version.eq,
+            }.items()
+            if value is not None
+        }
+
+    if not version_value:
+        return None
+
+    # SDK v2: request `_meta` is a plain dict (the `Meta` type alias), not the
+    # old `RequestParams.Meta` nested model.
+    return {"fastmcp": {"version": version_value}}
+
+
+# The MCP SDK warns "Tool X not listed, no validation will be performed"
+# for every call to app-only tools (hidden from list_tools by design).
+# This fires even when validate_input=False. Suppress it.
+class _SuppressUnlistedToolWarning(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        return "not listed, no validation" not in record.getMessage()
+
+
+logging.getLogger("mcp.server.lowlevel.server").addFilter(
+    _SuppressUnlistedToolWarning()
+)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+DuplicateBehavior = Literal["warn", "error", "replace", "ignore"]
+
+
+_REMOVED_KWARGS: dict[str, str] = {
+    "host": "Pass `host` to `run_http_async()`, or set FASTMCP_HOST.",
+    "port": "Pass `port` to `run_http_async()`, or set FASTMCP_PORT.",
+    "sse_path": "Pass `path` to `run_http_async()` or `http_app()`, or set FASTMCP_SSE_PATH.",
+    "message_path": "Set FASTMCP_MESSAGE_PATH.",
+    "streamable_http_path": "Pass `path` to `run_http_async()` or `http_app()`, or set FASTMCP_STREAMABLE_HTTP_PATH.",
+    "json_response": "Pass `json_response` to `run_http_async()` or `http_app()`, or set FASTMCP_JSON_RESPONSE.",
+    "stateless_http": "Pass `stateless_http` to `run_http_async()` or `http_app()`, or set FASTMCP_STATELESS_HTTP.",
+    "debug": "Set FASTMCP_DEBUG.",
+    "log_level": "Pass `log_level` to `run_http_async()`, or set FASTMCP_LOG_LEVEL.",
+    "on_duplicate_tools": "Use `on_duplicate=` instead.",
+    "on_duplicate_resources": "Use `on_duplicate=` instead.",
+    "on_duplicate_prompts": "Use `on_duplicate=` instead.",
+    "tool_serializer": "Return ToolResult from your tools instead. See https://gofastmcp.com/servers/tools#custom-serialization",
+    "include_tags": "Use `server.enable(tags=..., only=True)` after creating the server.",
+    "exclude_tags": "Use `server.disable(tags=...)` after creating the server.",
+    "tool_transformations": "Use `server.add_transform(ToolTransform(...))` after creating the server.",
+}
+
+
+def _check_removed_kwargs(kwargs: dict[str, Any]) -> None:
+    """Raise helpful TypeErrors for kwargs removed in v3."""
+    for key in kwargs:
+        if key in _REMOVED_KWARGS:
+            raise TypeError(
+                f"FastMCP() no longer accepts `{key}`. {_REMOVED_KWARGS[key]}"
+            )
+    if kwargs:
+        raise TypeError(
+            f"FastMCP() got unexpected keyword argument(s): {', '.join(repr(k) for k in kwargs)}"
+        )
+
+
+Transport = Literal["stdio", "http", "sse", "streamable-http"]
+
+
+LifespanCallable = Callable[
+    ["FastMCP[LifespanResultT]"], AbstractAsyncContextManager[LifespanResultT]
+]
+
+
+def _get_auth_context() -> tuple[bool, Any]:
+    """Get auth context for the current request.
+
+    Returns a tuple of (skip_auth, token) where:
+    - skip_auth=True means auth checks should be skipped (STDIO transport)
+    - token is the access token for HTTP transports (may be None if unauthenticated)
+
+    Uses late import to avoid circular import with context.py.
+    """
+    from fastmcp.server.context import _current_transport
+
+    is_stdio = _current_transport.get() == "stdio"
+    if is_stdio:
+        return (True, None)
+    from fastmcp.server.dependencies import get_access_token
+
+    return (False, get_access_token())
+
+
+def _is_backend_tool(tool: Tool) -> bool:
+    """Check whether a tool is handled specially as backend tool
+
+    Tools registered via ``@app.tool()`` (without ``model=True``) have
+    ``meta["ui"]["visibility"] == ["app"]`` — they are callable by app UIs
+    but should not appear in tool list the client passes to the model.
+
+    They are handled specially for in various ways - e.g. they are looked
+    up via get_app_tool(), and don't appear in the tools/list output.
+    (FIXME: the latter isn't correct behavior according to the mcp-apps spec.)
+
+    Returns True (a backend tool) when:
+    - The tool has ``meta.fastmcp.app``.
+    - The tool has ``meta.ui.visibility``.
+    - The visibility is precisely ``["app"]``.
+
+    Returns False otherwise.
+    """
+    meta = tool.meta
+    if not meta:
+        return False
+    fastmcp = meta.get("fastmcp")
+    if not isinstance(fastmcp, dict):
+        return False
+    if fastmcp.get("app") is None:
+        return False
+    ui = meta.get("ui")
+    if not isinstance(ui, dict):
+        return False
+    visibility = ui.get("visibility")
+    if not isinstance(visibility, list):
+        return False
+    return len(visibility) == 1 and visibility[0] == "app"
+
+
+def _is_app_visible(tool: Tool) -> bool:
+    """Check whether a tool has explicitly opted into app-callable visibility.
+
+    Gates the dispatcher's hashed-name routing path: only tools whose
+    ``meta.ui.visibility`` list contains ``"app"`` can be reached via
+    ``<hash>_<local_name>`` calls. Tools without an explicit visibility
+    declaration are NOT app-callable — they must be reached by their
+    display name through the normal transform-aware resolution path.
+
+    This is the inverse of the "everything is dot-callable" trap: the
+    hashed-name path is an opt-in mechanism for FastMCPApp backend tools,
+    not a general bypass for arbitrary tools.
+    """
+    meta = tool.meta
+    if not meta:
+        return False
+    ui = meta.get("ui")
+    if not isinstance(ui, dict):
+        return False
+    visibility = ui.get("visibility")
+    if not isinstance(visibility, list):
+        return False
+    return "app" in visibility
+
+
+@asynccontextmanager
+async def default_lifespan(server: FastMCP[LifespanResultT]) -> AsyncIterator[Any]:
+    """Default lifespan context manager that does nothing.
+
+    Args:
+        server: The server instance this lifespan is managing
+
+    Returns:
+        An empty dictionary as the lifespan result.
+    """
+    yield {}
+
+
+def _lifespan_proxy(
+    fastmcp_server: FastMCP[LifespanResultT],
+) -> Callable[
+    [LowLevelServer[LifespanResultT]], AbstractAsyncContextManager[LifespanResultT]
+]:
+    @asynccontextmanager
+    async def wrap(
+        low_level_server: LowLevelServer[LifespanResultT],
+    ) -> AsyncIterator[LifespanResultT]:
+        # Drive the FastMCP lifespan rather than merely reading it back. The
+        # SDK enters this proxy exactly once per manager/server run (via
+        # ``StreamableHTTPSessionManager.run`` → ``app.lifespan(app)`` or
+        # ``Server.run`` → ``self.lifespan(self)``) and reuses the yielded
+        # state for every session. ``_lifespan_manager`` is ref-counted, so
+        # when an outer caller (``run_http_async``/``run_stdio_async``) has
+        # already entered it, this nested entry reuses the existing result
+        # instead of re-running setup.
+        async with fastmcp_server._lifespan_manager():
+            yield fastmcp_server._lifespan_result  # ty:ignore[invalid-yield]
+
+    return wrap
+
+
+class StateValue(FastMCPBaseModel):
+    """Wrapper for stored context state values."""
+
+    value: Any
+
+
+class FastMCP(
+    AggregateProvider,
+    LifespanMixin,
+    MCPOperationsMixin,
+    TransportMixin,
+    Generic[LifespanResultT],
+):
+    def __init__(
+        self,
+        name: str | None = None,
+        instructions: str | None = None,
+        *,
+        version: str | int | float | None = None,
+        website_url: str | None = None,
+        icons: list[mcp_types.Icon] | None = None,
+        auth: AuthProvider | None = None,
+        middleware: Sequence[Middleware] | None = None,
+        providers: Sequence[Provider] | None = None,
+        transforms: Sequence[Transform] | None = None,
+        lifespan: LifespanCallable | Lifespan | None = None,
+        tools: Sequence[Tool | Callable[..., Any]] | None = None,
+        on_duplicate: DuplicateBehavior | None = None,
+        mask_error_details: bool | None = None,
+        dereference_schemas: bool = True,
+        strict_input_validation: bool | None = None,
+        list_page_size: int | None = None,
+        cache_ttl: int | None = None,
+        cache_scope: Literal["public", "private"] | None = None,
+        tasks: bool | None = None,
+        session_state_store: AsyncKeyValue | None = None,
+        sampling_handler: SamplingHandler | None = None,
+        sampling_handler_behavior: Literal["always", "fallback"] | None = None,
+        client_log_level: mcp_types.LoggingLevel | None = None,
+        experimental_capabilities: dict[str, dict[str, Any]] | None = None,
+        **kwargs: Any,
+    ):
+        _check_removed_kwargs(kwargs)
+
+        # Initialize Provider (sets up _transforms)
+        super().__init__()
+
+        self._on_duplicate: DuplicateBehaviorSetting = on_duplicate or "warn"
+
+        # Resolve server default for background task support
+        self._support_tasks_by_default: bool = tasks if tasks is not None else False
+
+        # Docket and Worker instances (set during lifespan for cross-task access)
+        self._docket = None
+        self._worker = None
+
+        self._additional_http_routes: list[BaseRoute] = []
+
+        # Session-scoped state store (shared across all requests)
+        self._state_storage: AsyncKeyValue = session_state_store or MemoryStore()
+        self._state_store: PydanticAdapter[StateValue] = PydanticAdapter[StateValue](
+            key_value=self._state_storage,
+            pydantic_model=StateValue,
+            default_collection="fastmcp_state",
+        )
+
+        # Create LocalProvider for local components
+        self._local_provider: LocalProvider = LocalProvider(
+            on_duplicate=self._on_duplicate
+        )
+
+        # Add providers using AggregateProvider's add_provider
+        # LocalProvider is always first (no namespace)
+        self.add_provider(self._local_provider)
+        for p in providers or []:
+            self.add_provider(p)
+
+        for t in transforms or []:
+            self.add_transform(t)
+
+        # Store mask_error_details for execution error handling
+        self._mask_error_details: bool = (
+            mask_error_details
+            if mask_error_details is not None
+            else fastmcp.settings.mask_error_details
+        )
+
+        # Store list_page_size for pagination of list operations
+        if list_page_size is not None and list_page_size <= 0:
+            raise ValueError("list_page_size must be a positive integer")
+        self._list_page_size: int | None = list_page_size
+
+        # Server-level SEP-2549 cache hints, applied uniformly to every
+        # SDK-cacheable result by the low-level server's runner (raises on
+        # invalid ttl/scope).
+        cache_hints = build_cache_hints(cache_ttl, cache_scope)
+
+        # Handle Lifespan instances (they're callable) or regular lifespan functions
+        if lifespan is not None:
+            self._lifespan: LifespanCallable[LifespanResultT] = cast(
+                LifespanCallable[LifespanResultT], lifespan
+            )
+        else:
+            self._lifespan = cast(LifespanCallable[LifespanResultT], default_lifespan)
+        self._lifespan_result: LifespanResultT | None = None
+        self._lifespan_result_set: bool = False
+        # Snapshot of SharedContext ContextVar values captured during the
+        # lifespan, re-applied per request by FastMCPServerMiddleware because
+        # the SDK v2 dispatcher runs handlers in the sender's context.
+        self._shared_context_snapshot: dict[Any, Any] | None = None
+        self._lifespan_ref_count: int = 0
+        self._lifespan_lock: asyncio.Lock = asyncio.Lock()
+        self._started: asyncio.Event = asyncio.Event()
+
+        # Generate random ID if no name provided
+        self._mcp_server: LowLevelServer[LifespanResultT] = LowLevelServer[
+            LifespanResultT
+        ](
+            fastmcp=self,
+            name=name or self.generate_name(),
+            version=_coerce_version(version) or fastmcp.__version__,
+            instructions=instructions,
+            website_url=website_url,
+            icons=icons,
+            lifespan=_lifespan_proxy(fastmcp_server=self),
+            cache_hints=cache_hints,
+        )
+
+        self.auth: AuthProvider | None = auth
+
+        if tools:
+            for tool in tools:
+                if not isinstance(tool, Tool):
+                    tool = Tool.from_function(tool)
+                self.add_tool(tool)
+
+        self.strict_input_validation: bool = (
+            strict_input_validation
+            if strict_input_validation is not None
+            else fastmcp.settings.strict_input_validation
+        )
+
+        self.client_log_level: mcp_types.LoggingLevel | None = (
+            client_log_level
+            if client_log_level is not None
+            else fastmcp.settings.client_log_level
+        )
+
+        # Per-session minimum log level requested by clients via logging/setLevel.
+        # Keyed by session id (a sentinel for stdio where session_id is None).
+        # v2 sessions are per-request so this state lives on the server, not the
+        # session object.
+        self._client_log_levels: dict[str, mcp_types.LoggingLevel] = {}
+
+        self.experimental_capabilities: dict[str, dict[str, Any]] = (
+            experimental_capabilities or {}
+        )
+
+        self.middleware: list[Middleware] = list(middleware or [])
+
+        if dereference_schemas:
+            from fastmcp.server.middleware.dereference import (
+                DereferenceRefsMiddleware,
+            )
+
+            self.middleware.append(DereferenceRefsMiddleware())
+
+        # Set up MCP protocol handlers
+        self._setup_handlers()
+
+        self.sampling_handler: SamplingHandler | None = sampling_handler
+        self.sampling_handler_behavior: Literal["always", "fallback"] = (
+            sampling_handler_behavior or "fallback"
+        )
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.name!r})"
+
+    @property
+    def name(self) -> str:
+        return self._mcp_server.name
+
+    @property
+    def instructions(self) -> str | None:
+        return self._mcp_server.instructions
+
+    @instructions.setter
+    def instructions(self, value: str | None) -> None:
+        self._mcp_server.instructions = value
+
+    @property
+    def version(self) -> str | None:
+        return self._mcp_server.version
+
+    @property
+    def website_url(self) -> str | None:
+        return self._mcp_server.website_url
+
+    @property
+    def icons(self) -> list[mcp_types.Icon]:
+        if self._mcp_server.icons is None:
+            return []
+        else:
+            return list(self._mcp_server.icons)
+
+    @property
+    def local_provider(self) -> LocalProvider:
+        """The server's local provider, which stores directly-registered components.
+
+        Use this to remove components:
+
+            mcp.local_provider.remove_tool("my_tool")
+            mcp.local_provider.remove_resource("data://info")
+            mcp.local_provider.remove_prompt("my_prompt")
+        """
+        return self._local_provider
+
+    async def _run_middleware(
+        self,
+        context: MiddlewareContext[Any],
+        call_next: CallNext[Any, Any],
+    ) -> Any:
+        """Builds and executes the middleware chain."""
+        chain = call_next
+        for mw in reversed(self.middleware):
+            next_chain: CallNext[Any, Any] = chain
+
+            async def wrapped(
+                context: MiddlewareContext[Any],
+                mw: Middleware = mw,
+                call_next: CallNext[Any, Any] = next_chain,
+            ) -> Any:
+                return await mw(context, call_next)
+
+            chain = cast(CallNext[Any, Any], wrapped)
+        return await chain(context)
+
+    def add_middleware(self, middleware: Middleware) -> None:
+        self.middleware.append(middleware)
+
+    def add_provider(self, provider: Provider, *, namespace: str = "") -> None:
+        """Add a provider for dynamic tools, resources, and prompts.
+
+        Providers are queried in registration order. The first provider to return
+        a non-None result wins. Static components (registered via decorators)
+        always take precedence over providers.
+
+        Args:
+            provider: A Provider instance that will provide components dynamically.
+            namespace: Optional namespace prefix. When set:
+                - Tools become "namespace_toolname"
+                - Resources become "protocol://namespace/path"
+                - Prompts become "namespace_promptname"
+        """
+        super().add_provider(provider, namespace=namespace)
+
+    def _rewrite_prefab_uris(self, tools: list[Tool]) -> list[Tool]:
+        """Replace placeholder Prefab URIs with per-tool hashed ones.
+
+        For each tool whose ``meta.ui.resourceUri`` is the placeholder,
+        reads the tool's stored hash from ``meta.fastmcp._tool_hash``
+        and rewrites the URI to the per-tool form. Also strips CSP from
+        tool meta (it belongs on the resource). Produces ``model_copy``
+        views — originals are untouched.
+        """
+        from fastmcp.server.providers.prefab_synthesis import (
+            _is_prefab_tool,
+            rewrite_tool_meta_for_wire,
+        )
+
+        return [
+            rewrite_tool_meta_for_wire(t) if _is_prefab_tool(t) else t for t in tools
+        ]
+
+    # -------------------------------------------------------------------------
+    # Provider interface overrides - inherited from AggregateProvider
+    # -------------------------------------------------------------------------
+    # _list_tools, _list_resources, _list_resource_templates, _list_prompts
+    # are inherited from AggregateProvider which handles aggregation and namespacing
+
+    async def get_tasks(self) -> Sequence[FastMCPComponent]:
+        """Get task-eligible components with all transforms applied.
+
+        Overrides AggregateProvider.get_tasks() to apply server-level transforms
+        after aggregation. AggregateProvider handles provider-level namespacing.
+        """
+        # Get tasks from AggregateProvider (handles aggregation and namespacing)
+        components = list(await super().get_tasks())
+
+        # Separate by component type for server-level transform application
+        tools = [c for c in components if isinstance(c, Tool)]
+        resources = [c for c in components if isinstance(c, Resource)]
+        templates = [c for c in components if isinstance(c, ResourceTemplate)]
+        prompts = [c for c in components if isinstance(c, Prompt)]
+
+        # Apply server-level transforms sequentially
+        for transform in self.transforms:
+            tools = await transform.list_tools(tools)
+            resources = await transform.list_resources(resources)
+            templates = await transform.list_resource_templates(templates)
+            prompts = await transform.list_prompts(prompts)
+
+        return [
+            *tools,
+            *resources,
+            *templates,
+            *prompts,
+        ]
+
+    def add_transform(self, transform: Transform) -> None:
+        """Add a server-level transform.
+
+        Server-level transforms are applied after all providers are aggregated.
+        They transform tools, resources, and prompts from ALL providers.
+
+        Args:
+            transform: The transform to add.
+
+        Example:
+            ```python
+            from fastmcp.server.transforms import Namespace
+
+            server = FastMCP("Server")
+            server.add_transform(Namespace("api"))
+            # All tools from all providers become "api_toolname"
+            ```
+        """
+        self._transforms.append(transform)
+
+    async def list_tools(self, *, run_middleware: bool = True) -> Sequence[Tool]:
+        """List all enabled tools from providers.
+
+        Overrides Provider.list_tools() to add visibility filtering, auth filtering,
+        and middleware execution. Returns all versions (no deduplication).
+        Protocol handlers deduplicate for MCP wire format.
+        """
+        async with fastmcp.server.context.Context(fastmcp=self) as ctx:
+            if run_middleware:
+                mw_context = MiddlewareContext(
+                    message=mcp_types.ListToolsRequest(method="tools/list"),
+                    source="client",
+                    type="request",
+                    method="tools/list",
+                    fastmcp_context=ctx,
+                )
+                return await self._run_middleware(
+                    context=mw_context,
+                    call_next=lambda context: self.list_tools(run_middleware=False),
+                )
+
+            # Core logic: list tools
+            with server_span("tools/list", "tools/list", self.name, "tool", ""):
+                # Get all tools, apply session transforms, then filter enabled
+                # and model-visible (app-only tools are hidden from the model).
+                tools = list(await super().list_tools())
+                tools = await apply_session_transforms(tools)
+                tools = [t for t in tools if is_enabled(t) and not _is_backend_tool(t)]
+
+                # Rewrite per-tool Prefab renderer URIs based on the tool's
+                # mount-point address. The walk pairs each tool with the
+                # provider that yielded it, computes the hashed URI, and
+                # produces a model_copy with the URI in place. Original
+                # Tool objects are not mutated.
+                tools = self._rewrite_prefab_uris(tools)
+
+                skip_auth, token = _get_auth_context()
+                authorized: list[Tool] = []
+                for tool in tools:
+                    if not skip_auth and tool.auth is not None:
+                        ctx = AuthContext(token=token, component=tool)
+                        try:
+                            if not await run_auth_checks(tool.auth, ctx):
+                                continue
+                        except AuthorizationError:
+                            continue
+                    authorized.append(tool)
+                return authorized
+
+    async def _get_tool(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get a tool by name via aggregation from providers.
+
+        Extends AggregateProvider._get_tool() with component-level auth checks.
+
+        Args:
+            name: The tool name.
+            version: Version filter (None returns highest version).
+
+        Returns:
+            The tool if found and authorized, None if not found or unauthorized.
+        """
+        # Get tool from AggregateProvider (handles aggregation and namespacing)
+        tool = await super()._get_tool(name, version)
+        if tool is None:
+            return None
+
+        # Component auth - return None if unauthorized (consistent with list filtering)
+        skip_auth, token = _get_auth_context()
+        if not skip_auth and tool.auth is not None:
+            ctx = AuthContext(token=token, component=tool)
+            try:
+                if not await run_auth_checks(tool.auth, ctx):
+                    return None
+            except AuthorizationError:
+                return None
+
+        return tool
+
+    async def get_tool(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get a tool by name, filtering disabled tools.
+
+        Overrides Provider.get_tool() to add visibility filtering after all
+        transforms (including session-level) have been applied. This ensures
+        session transforms can override provider-level disables.
+
+        When the highest version is disabled and no explicit version was
+        requested, falls back to the next-highest enabled version.
+
+        Args:
+            name: The tool name.
+            version: Version filter (None returns highest version).
+
+        Returns:
+            The tool if found and enabled, None otherwise.
+        """
+        tool = await super().get_tool(name, version)
+        if tool is None:
+            return None
+
+        # Apply session transforms to single item
+        tools = await apply_session_transforms([tool])
+        if tools and is_enabled(tools[0]) and not _is_backend_tool(tools[0]):
+            return tools[0]
+
+        # The highest version is disabled (or app-only). If an explicit version
+        # was requested, respect that. Otherwise fall back to the next-highest
+        # enabled, model-visible version.
+        if version is not None:
+            return None
+
+        all_tools = [t for t in await super().list_tools() if t.name == name]
+        all_tools = list(await apply_session_transforms(all_tools))
+        enabled = [t for t in all_tools if is_enabled(t) and not _is_backend_tool(t)]
+
+        skip_auth, token = _get_auth_context()
+        authorized: list[Tool] = []
+        for t in enabled:
+            if not skip_auth and t.auth is not None:
+                ctx = AuthContext(token=token, component=t)
+                try:
+                    if not await run_auth_checks(t.auth, ctx):
+                        continue
+                except AuthorizationError:
+                    continue
+            authorized.append(t)
+
+        if not authorized:
+            return None
+        return max(authorized, key=version_sort_key)
+
+    async def list_resources(
+        self, *, run_middleware: bool = True
+    ) -> Sequence[Resource]:
+        """List all enabled resources from providers.
+
+        Overrides Provider.list_resources() to add visibility filtering, auth filtering,
+        and middleware execution. Returns all versions (no deduplication).
+        Protocol handlers deduplicate for MCP wire format.
+        """
+        async with fastmcp.server.context.Context(fastmcp=self) as ctx:
+            if run_middleware:
+                mw_context = MiddlewareContext(
+                    message={},
+                    source="client",
+                    type="request",
+                    method="resources/list",
+                    fastmcp_context=ctx,
+                )
+                return await self._run_middleware(
+                    context=mw_context,
+                    call_next=lambda context: self.list_resources(run_middleware=False),
+                )
+
+            # Core logic: list resources
+            with server_span(
+                "resources/list", "resources/list", self.name, "resource", ""
+            ):
+                # Get all resources, apply session transforms, then filter enabled
+                resources = list(await super().list_resources())
+                resources = await apply_session_transforms(resources)
+                resources = [r for r in resources if is_enabled(r)]
+
+                # Append synthetic Prefab renderer resources — one per
+                # prefab tool, hashed by mount address. These don't live on
+                # any provider's storage; they're computed on demand.
+                from fastmcp.server.providers.prefab_synthesis import (
+                    synthesize_prefab_resources,
+                )
+
+                resources.extend(await synthesize_prefab_resources(self))
+
+                skip_auth, token = _get_auth_context()
+                authorized: list[Resource] = []
+                for resource in resources:
+                    if not skip_auth and resource.auth is not None:
+                        ctx = AuthContext(token=token, component=resource)
+                        try:
+                            if not await run_auth_checks(resource.auth, ctx):
+                                continue
+                        except AuthorizationError:
+                            continue
+                    authorized.append(resource)
+                return authorized
+
+    async def _get_resource(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> Resource | None:
+        """Get a resource by URI via aggregation from providers.
+
+        Extends AggregateProvider._get_resource() with component-level auth checks.
+
+        Args:
+            uri: The resource URI.
+            version: Version filter (None returns highest version).
+
+        Returns:
+            The resource if found and authorized, None if not found or unauthorized.
+        """
+        # Get resource from AggregateProvider (handles aggregation and namespacing)
+        resource = await super()._get_resource(uri, version)
+        if resource is None:
+            return None
+
+        # Component auth - return None if unauthorized (consistent with list filtering)
+        skip_auth, token = _get_auth_context()
+        if not skip_auth and resource.auth is not None:
+            ctx = AuthContext(token=token, component=resource)
+            try:
+                if not await run_auth_checks(resource.auth, ctx):
+                    return None
+            except AuthorizationError:
+                return None
+
+        return resource
+
+    async def get_resource(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> Resource | None:
+        """Get a resource by URI, filtering disabled resources.
+
+        Overrides Provider.get_resource() to add visibility filtering after all
+        transforms (including session-level) have been applied.
+
+        When the highest version is disabled and no explicit version was
+        requested, falls back to the next-highest enabled version.
+
+        Args:
+            uri: The resource URI.
+            version: Version filter (None returns highest version).
+
+        Returns:
+            The resource if found and enabled, None otherwise.
+        """
+        resource = await super().get_resource(uri, version)
+        if resource is None:
+            return None
+
+        # Apply session transforms to single item
+        resources = await apply_session_transforms([resource])
+        if resources and is_enabled(resources[0]):
+            return resources[0]
+
+        if version is not None:
+            return None
+
+        all_resources = [r for r in await super().list_resources() if str(r.uri) == uri]
+        all_resources = list(await apply_session_transforms(all_resources))
+        enabled = [r for r in all_resources if is_enabled(r)]
+
+        skip_auth, token = _get_auth_context()
+        authorized: list[Resource] = []
+        for r in enabled:
+            if not skip_auth and r.auth is not None:
+                ctx = AuthContext(token=token, component=r)
+                try:
+                    if not await run_auth_checks(r.auth, ctx):
+                        continue
+                except AuthorizationError:
+                    continue
+            authorized.append(r)
+
+        if not authorized:
+            return None
+        return max(authorized, key=version_sort_key)
+
+    async def list_resource_templates(
+        self, *, run_middleware: bool = True
+    ) -> Sequence[ResourceTemplate]:
+        """List all enabled resource templates from providers.
+
+        Overrides Provider.list_resource_templates() to add visibility filtering,
+        auth filtering, and middleware execution. Returns all versions (no deduplication).
+        Protocol handlers deduplicate for MCP wire format.
+        """
+        async with fastmcp.server.context.Context(fastmcp=self) as ctx:
+            if run_middleware:
+                mw_context = MiddlewareContext(
+                    message={},
+                    source="client",
+                    type="request",
+                    method="resources/templates/list",
+                    fastmcp_context=ctx,
+                )
+                return await self._run_middleware(
+                    context=mw_context,
+                    call_next=lambda context: self.list_resource_templates(
+                        run_middleware=False
+                    ),
+                )
+
+            # Core logic: list resource templates
+            with server_span(
+                "resources/templates/list",
+                "resources/templates/list",
+                self.name,
+                "resource_template",
+                "",
+            ):
+                # Get all templates, apply session transforms, then filter enabled
+                templates = list(await super().list_resource_templates())
+                templates = await apply_session_transforms(templates)
+                templates = [t for t in templates if is_enabled(t)]
+
+                skip_auth, token = _get_auth_context()
+                authorized: list[ResourceTemplate] = []
+                for template in templates:
+                    if not skip_auth and template.auth is not None:
+                        ctx = AuthContext(token=token, component=template)
+                        try:
+                            if not await run_auth_checks(template.auth, ctx):
+                                continue
+                        except AuthorizationError:
+                            continue
+                    authorized.append(template)
+                return authorized
+
+    async def _get_resource_template(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> ResourceTemplate | None:
+        """Get a resource template by URI via aggregation from providers.
+
+        Extends AggregateProvider._get_resource_template() with component-level auth checks.
+
+        Args:
+            uri: The template URI to match.
+            version: Version filter (None returns highest version).
+
+        Returns:
+            The template if found and authorized, None if not found or unauthorized.
+        """
+        # Get template from AggregateProvider (handles aggregation and namespacing)
+        template = await super()._get_resource_template(uri, version)
+        if template is None:
+            return None
+
+        # Component auth - return None if unauthorized (consistent with list filtering)
+        skip_auth, token = _get_auth_context()
+        if not skip_auth and template.auth is not None:
+            ctx = AuthContext(token=token, component=template)
+            try:
+                if not await run_auth_checks(template.auth, ctx):
+                    return None
+            except AuthorizationError:
+                return None
+
+        return template
+
+    async def get_resource_template(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> ResourceTemplate | None:
+        """Get a resource template by URI, filtering disabled templates.
+
+        Overrides Provider.get_resource_template() to add visibility filtering after
+        all transforms (including session-level) have been applied.
+
+        When the highest version is disabled and no explicit version was
+        requested, falls back to the next-highest enabled version.
+
+        Args:
+            uri: The template URI.
+            version: Version filter (None returns highest version).
+
+        Returns:
+            The template if found and enabled, None otherwise.
+        """
+        template = await super().get_resource_template(uri, version)
+        if template is None:
+            return None
+
+        # Apply session transforms to single item
+        templates = await apply_session_transforms([template])
+        if templates and is_enabled(templates[0]):
+            return templates[0]
+
+        if version is not None:
+            return None
+
+        all_templates = [
+            t
+            for t in await super().list_resource_templates()
+            if t.matches(uri) is not None
+        ]
+        all_templates = list(await apply_session_transforms(all_templates))
+        enabled = [t for t in all_templates if is_enabled(t)]
+
+        skip_auth, token = _get_auth_context()
+        authorized: list[ResourceTemplate] = []
+        for t in enabled:
+            if not skip_auth and t.auth is not None:
+                ctx = AuthContext(token=token, component=t)
+                try:
+                    if not await run_auth_checks(t.auth, ctx):
+                        continue
+                except AuthorizationError:
+                    continue
+            authorized.append(t)
+
+        if not authorized:
+            return None
+        return max(authorized, key=version_sort_key)
+
+    async def list_prompts(self, *, run_middleware: bool = True) -> Sequence[Prompt]:
+        """List all enabled prompts from providers.
+
+        Overrides Provider.list_prompts() to add visibility filtering, auth filtering,
+        and middleware execution. Returns all versions (no deduplication).
+        Protocol handlers deduplicate for MCP wire format.
+        """
+        async with fastmcp.server.context.Context(fastmcp=self) as ctx:
+            if run_middleware:
+                mw_context = MiddlewareContext(
+                    message={},
+                    source="client",
+                    type="request",
+                    method="prompts/list",
+                    fastmcp_context=ctx,
+                )
+                return await self._run_middleware(
+                    context=mw_context,
+                    call_next=lambda context: self.list_prompts(run_middleware=False),
+                )
+
+            # Core logic: list prompts
+            with server_span("prompts/list", "prompts/list", self.name, "prompt", ""):
+                # Get all prompts, apply session transforms, then filter enabled
+                prompts = list(await super().list_prompts())
+                prompts = await apply_session_transforms(prompts)
+                prompts = [p for p in prompts if is_enabled(p)]
+
+                skip_auth, token = _get_auth_context()
+                authorized: list[Prompt] = []
+                for prompt in prompts:
+                    if not skip_auth and prompt.auth is not None:
+                        ctx = AuthContext(token=token, component=prompt)
+                        try:
+                            if not await run_auth_checks(prompt.auth, ctx):
+                                continue
+                        except AuthorizationError:
+                            continue
+                    authorized.append(prompt)
+                return authorized
+
+    async def _get_prompt(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        """Get a prompt by name via aggregation from providers.
+
+        Extends AggregateProvider._get_prompt() with component-level auth checks.
+
+        Args:
+            name: The prompt name.
+            version: Version filter (None returns highest version).
+
+        Returns:
+            The prompt if found and authorized, None if not found or unauthorized.
+        """
+        # Get prompt from AggregateProvider (handles aggregation and namespacing)
+        prompt = await super()._get_prompt(name, version)
+        if prompt is None:
+            return None
+
+        # Component auth - return None if unauthorized (consistent with list filtering)
+        skip_auth, token = _get_auth_context()
+        if not skip_auth and prompt.auth is not None:
+            ctx = AuthContext(token=token, component=prompt)
+            try:
+                if not await run_auth_checks(prompt.auth, ctx):
+                    return None
+            except AuthorizationError:
+                return None
+
+        return prompt
+
+    async def get_prompt(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        """Get a prompt by name, filtering disabled prompts.
+
+        Overrides Provider.get_prompt() to add visibility filtering after all
+        transforms (including session-level) have been applied.
+
+        When the highest version is disabled and no explicit version was
+        requested, falls back to the next-highest enabled version.
+
+        Args:
+            name: The prompt name.
+            version: Version filter (None returns highest version).
+
+        Returns:
+            The prompt if found and enabled, None otherwise.
+        """
+        prompt = await super().get_prompt(name, version)
+        if prompt is None:
+            return None
+
+        # Apply session transforms to single item
+        prompts = await apply_session_transforms([prompt])
+        if prompts and is_enabled(prompts[0]):
+            return prompts[0]
+
+        if version is not None:
+            return None
+
+        all_prompts = [p for p in await super().list_prompts() if p.name == name]
+        all_prompts = list(await apply_session_transforms(all_prompts))
+        enabled = [p for p in all_prompts if is_enabled(p)]
+
+        skip_auth, token = _get_auth_context()
+        authorized: list[Prompt] = []
+        for p in enabled:
+            if not skip_auth and p.auth is not None:
+                ctx = AuthContext(token=token, component=p)
+                try:
+                    if not await run_auth_checks(p.auth, ctx):
+                        continue
+                except AuthorizationError:
+                    continue
+            authorized.append(p)
+
+        if not authorized:
+            return None
+        return max(authorized, key=version_sort_key)
+
+    @overload
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        version: VersionSpec | None = None,
+        run_middleware: bool = True,
+        task_meta: None = None,
+    ) -> ToolResult: ...
+
+    @overload
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        version: VersionSpec | None = None,
+        run_middleware: bool = True,
+        task_meta: TaskMeta,
+    ) -> mcp_types.CreateTaskResult: ...
+
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        version: VersionSpec | None = None,
+        run_middleware: bool = True,
+        task_meta: TaskMeta | None = None,
+    ) -> ToolResult | mcp_types.CreateTaskResult:
+        """Call a tool by name.
+
+        This is the public API for executing tools. By default, middleware is applied.
+
+        Args:
+            name: The tool name
+            arguments: Tool arguments (optional)
+            version: Specific version to call. If None, calls highest version.
+            run_middleware: If True (default), apply the middleware chain.
+                Set to False when called from middleware to avoid re-applying.
+            task_meta: If provided, execute as a background task and return
+                CreateTaskResult. If None (default), execute synchronously and
+                return ToolResult.
+
+        Returns:
+            ToolResult when task_meta is None.
+            CreateTaskResult when task_meta is provided.
+
+        Raises:
+            NotFoundError: If tool not found or disabled
+            ToolError: If tool execution fails
+            ValidationError: If arguments fail validation
+        """
+        # Note: fn_key enrichment happens here after finding the tool.
+        # For mounted servers, the parent's provider sets fn_key to the
+        # namespaced key before delegating, ensuring correct Docket routing.
+
+        from fastmcp.server.providers.addressing import (
+            parse_hashed_backend_name,
+        )
+
+        # Two routing paths:
+        #   1. Hashed-name path — backend tools that opted into
+        #      app-callable visibility. Recognized by their
+        #      `<hash>_<local_name>` format and resolved via the
+        #      reverse-hash map. Address is known eagerly.
+        #   2. Display-name path — everything else. Goes through normal
+        #      `get_tool` aggregation/transforms. Address is determined
+        #      after resolution by walking the registry.
+        async with fastmcp.server.context.Context(fastmcp=self) as ctx:
+            if run_middleware:
+                mw_context = MiddlewareContext[CallToolRequestParams](
+                    message=mcp_types.CallToolRequestParams(
+                        name=name,
+                        arguments=arguments or {},
+                        # `_meta` carries the app-level `fastmcp` version key, which the
+                        # reserved-key RequestParamsMeta TypedDict can't express statically.
+                        _meta=_version_request_meta(version),  # type: ignore[unknown-argument]  # ty: ignore[invalid-argument-type]
+                    ),
+                    source="client",
+                    type="request",
+                    method="tools/call",
+                    fastmcp_context=ctx,
+                )
+                return await self._run_middleware(
+                    context=mw_context,
+                    call_next=lambda context: self.call_tool(
+                        context.message.name,
+                        context.message.arguments or {},
+                        version=version,
+                        run_middleware=False,
+                        task_meta=task_meta,
+                    ),
+                )
+
+            # Core logic: find and execute tool
+            with server_span(
+                f"tools/call {name}",
+                "tools/call",
+                self.name,
+                "tool",
+                name,
+                tool_name=name,
+            ) as span:
+                # Try normal display-name resolution first.
+                tool: Tool | None = await self.get_tool(name, version=version)
+
+                # If that fails, try hashed-name dispatch. This walks
+                # the provider tree recursively (same pattern as the old
+                # get_app_tool) looking for a tool whose stored hash
+                # matches the parsed prefix.
+                if tool is None:
+                    hashed = parse_hashed_backend_name(name)
+                    if hashed is not None:
+                        digest, local_name = hashed
+                        tool = await self.get_tool_by_hash(digest, local_name)
+                        if tool is not None:
+                            # Auth still applies on the bypass path.
+                            skip_auth, token = _get_auth_context()
+                            if not skip_auth and tool.auth is not None:
+                                try:
+                                    auth_ctx = AuthContext(token=token, component=tool)
+                                    if not await run_auth_checks(tool.auth, auth_ctx):
+                                        raise NotFoundError(f"Unknown tool: {name!r}")
+                                except AuthorizationError:
+                                    raise NotFoundError(
+                                        f"Unknown tool: {name!r}"
+                                    ) from None
+
+                if tool is None:
+                    raise NotFoundError(f"Unknown tool: {name!r}")
+                span.set_attributes(tool.get_span_attributes())
+                if task_meta is not None and task_meta.fn_key is None:
+                    task_meta = replace(task_meta, fn_key=tool.key)
+                try:
+                    return await tool._run(arguments or {}, task_meta=task_meta)
+                except ValidationError as e:
+                    # Argument-validation failure (a bad call). FunctionTool
+                    # converts pydantic's call-validation error into fastmcp's
+                    # ValidationError (see #4128) so it can be filtered as a
+                    # client error. Log the underlying detail without a URL or
+                    # traceback, matching the previous pydantic-error logging.
+                    cause = e.__cause__
+                    detail = (
+                        cause.errors(include_url=False)
+                        if isinstance(cause, PydanticValidationError)
+                        else str(e)
+                    )
+                    logger.warning("Invalid arguments for tool %r: %s", name, detail)
+                    raise
+                except FastMCPError as e:
+                    logger.log(
+                        e.log_level, f"Error calling tool {name!r}", exc_info=False
+                    )
+                    raise
+                except PydanticValidationError as e:
+                    # A pydantic error that is NOT an argument-validation failure
+                    # (e.g. raised by a non-FunctionTool's own validation). Kept
+                    # for backward compatibility.
+                    logger.warning(
+                        "Invalid arguments for tool %r: %s",
+                        name,
+                        e.errors(include_url=False),
+                    )
+                    raise
+                except Exception as e:
+                    logger.exception(f"Error calling tool {name!r}")
+                    # Handle actionable errors that should reach the LLM
+                    # even when masking is enabled
+                    if isinstance(e, httpx.HTTPStatusError):
+                        if e.response.status_code == 429:
+                            raise ToolError(
+                                "Rate limited by upstream API, please retry later"
+                            ) from e
+                    if isinstance(e, httpx.TimeoutException):
+                        raise ToolError(
+                            "Upstream request timed out, please retry"
+                        ) from e
+                    # Standard masking logic
+                    if self._mask_error_details:
+                        raise ToolError(f"Error calling tool {name!r}") from e
+                    raise ToolError(f"Error calling tool {name!r}: {e}") from e
+
+    @overload
+    async def read_resource(
+        self,
+        uri: str,
+        *,
+        version: VersionSpec | None = None,
+        run_middleware: bool = True,
+        task_meta: None = None,
+    ) -> ResourceResult: ...
+
+    @overload
+    async def read_resource(
+        self,
+        uri: str,
+        *,
+        version: VersionSpec | None = None,
+        run_middleware: bool = True,
+        task_meta: TaskMeta,
+    ) -> mcp_types.CreateTaskResult: ...
+
+    async def read_resource(
+        self,
+        uri: str,
+        *,
+        version: VersionSpec | None = None,
+        run_middleware: bool = True,
+        task_meta: TaskMeta | None = None,
+    ) -> ResourceResult | mcp_types.CreateTaskResult:
+        """Read a resource by URI.
+
+        This is the public API for reading resources. By default, middleware is applied.
+        Checks concrete resources first, then templates.
+
+        Args:
+            uri: The resource URI
+            version: Specific version to read. If None, reads highest version.
+            run_middleware: If True (default), apply the middleware chain.
+                Set to False when called from middleware to avoid re-applying.
+            task_meta: If provided, execute as a background task and return
+                CreateTaskResult. If None (default), execute synchronously and
+                return ResourceResult.
+
+        Returns:
+            ResourceResult when task_meta is None.
+            CreateTaskResult when task_meta is provided.
+
+        Raises:
+            NotFoundError: If resource not found or disabled
+            ResourceError: If resource read fails
+        """
+        # Note: fn_key enrichment happens here after finding the resource/template.
+        # Resources and templates use different key formats:
+        # - Resources use resource.key (derived from the concrete URI)
+        # - Templates use template.key (the template pattern)
+        # For mounted servers, the parent's provider sets fn_key to the
+        # namespaced key before delegating, ensuring correct Docket routing.
+
+        async with fastmcp.server.context.Context(fastmcp=self) as ctx:
+            if run_middleware:
+                mw_context = MiddlewareContext(
+                    message=mcp_types.ReadResourceRequestParams(
+                        uri=str(uri),
+                        # `_meta` carries the app-level `fastmcp` version key, which the
+                        # reserved-key RequestParamsMeta TypedDict can't express statically.
+                        _meta=_version_request_meta(version),  # type: ignore[unknown-argument]  # ty: ignore[invalid-argument-type]
+                    ),
+                    source="client",
+                    type="request",
+                    method="resources/read",
+                    fastmcp_context=ctx,
+                )
+                return await self._run_middleware(
+                    context=mw_context,
+                    call_next=lambda context: self.read_resource(
+                        str(context.message.uri),
+                        version=version,
+                        run_middleware=False,
+                        task_meta=task_meta,
+                    ),
+                )
+
+            # Core logic: find and read resource (providers queried in parallel)
+            with server_span(
+                "resources/read",
+                "resources/read",
+                self.name,
+                "resource",
+                uri,
+                resource_uri=uri,
+            ) as span:
+                # Intercept synthetic Prefab renderer URIs before normal
+                # resolution. The resource isn't stored anywhere — we
+                # build it on demand from the matching tool's CSP.
+                from fastmcp.server.providers.prefab_synthesis import (
+                    synthesize_prefab_resource_by_uri,
+                )
+
+                synthesized = await synthesize_prefab_resource_by_uri(self, uri)
+                if synthesized is not None:
+                    span.set_attributes(synthesized.get_span_attributes())
+                    return await synthesized._read(task_meta=task_meta)
+
+                # Try concrete resources first (transforms + auth via _get_resource)
+                resource = await self.get_resource(uri, version=version)
+                if resource is not None:
+                    span.set_attributes(resource.get_span_attributes())
+                    if task_meta is not None and task_meta.fn_key is None:
+                        task_meta = replace(task_meta, fn_key=resource.key)
+                    try:
+                        return await resource._read(task_meta=task_meta)
+                    except FastMCPError as e:
+                        logger.log(
+                            e.log_level,
+                            f"Error reading resource {uri!r}",
+                            exc_info=True,
+                        )
+                        raise
+                    except MCPError:
+                        logger.exception(f"Error reading resource {uri!r}")
+                        raise
+                    except Exception as e:
+                        logger.exception(f"Error reading resource {uri!r}")
+                        # Handle actionable errors that should reach the LLM
+                        if isinstance(e, httpx.HTTPStatusError):
+                            if e.response.status_code == 429:
+                                raise ResourceError(
+                                    "Rate limited by upstream API, please retry later"
+                                ) from e
+                        if isinstance(e, httpx.TimeoutException):
+                            raise ResourceError(
+                                "Upstream request timed out, please retry"
+                            ) from e
+                        # Standard masking logic
+                        if self._mask_error_details:
+                            raise ResourceError(
+                                f"Error reading resource {uri!r}"
+                            ) from e
+                        raise ResourceError(
+                            f"Error reading resource {uri!r}: {e}"
+                        ) from e
+
+                # Try templates (transforms + auth via get_resource_template)
+                template = await self.get_resource_template(uri, version=version)
+                if template is None:
+                    if version is None:
+                        raise NotFoundError(f"Unknown resource: {uri!r}")
+                    raise NotFoundError(
+                        f"Unknown resource: {uri!r} version {version!r}"
+                    )
+                span.set_attributes(template.get_span_attributes())
+                params = template.matches(uri)
+                assert params is not None
+                if task_meta is not None and task_meta.fn_key is None:
+                    task_meta = replace(task_meta, fn_key=template.key)
+                try:
+                    return await template._read(uri, params, task_meta=task_meta)
+                except FastMCPError as e:
+                    logger.log(
+                        e.log_level, f"Error reading resource {uri!r}", exc_info=True
+                    )
+                    raise
+                except MCPError:
+                    logger.exception(f"Error reading resource {uri!r}")
+                    raise
+                except Exception as e:
+                    logger.exception(f"Error reading resource {uri!r}")
+                    # Handle actionable errors that should reach the LLM
+                    if isinstance(e, httpx.HTTPStatusError):
+                        if e.response.status_code == 429:
+                            raise ResourceError(
+                                "Rate limited by upstream API, please retry later"
+                            ) from e
+                    if isinstance(e, httpx.TimeoutException):
+                        raise ResourceError(
+                            "Upstream request timed out, please retry"
+                        ) from e
+                    # Standard masking logic
+                    if self._mask_error_details:
+                        raise ResourceError(f"Error reading resource {uri!r}") from e
+                    raise ResourceError(f"Error reading resource {uri!r}: {e}") from e
+
+    @overload
+    async def render_prompt(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        version: VersionSpec | None = None,
+        run_middleware: bool = True,
+        task_meta: None = None,
+    ) -> PromptResult: ...
+
+    @overload
+    async def render_prompt(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        version: VersionSpec | None = None,
+        run_middleware: bool = True,
+        task_meta: TaskMeta,
+    ) -> mcp_types.CreateTaskResult: ...
+
+    async def render_prompt(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        version: VersionSpec | None = None,
+        run_middleware: bool = True,
+        task_meta: TaskMeta | None = None,
+    ) -> PromptResult | mcp_types.CreateTaskResult:
+        """Render a prompt by name.
+
+        This is the public API for rendering prompts. By default, middleware is applied.
+        Use get_prompt() to retrieve the prompt definition without rendering.
+
+        Args:
+            name: The prompt name
+            arguments: Prompt arguments (optional)
+            version: Specific version to render. If None, renders highest version.
+            run_middleware: If True (default), apply the middleware chain.
+                Set to False when called from middleware to avoid re-applying.
+            task_meta: If provided, execute as a background task and return
+                CreateTaskResult. If None (default), execute synchronously and
+                return PromptResult.
+
+        Returns:
+            PromptResult when task_meta is None.
+            CreateTaskResult when task_meta is provided.
+
+        Raises:
+            NotFoundError: If prompt not found or disabled
+            PromptError: If prompt rendering fails
+        """
+        async with fastmcp.server.context.Context(fastmcp=self) as ctx:
+            if run_middleware:
+                mw_context = MiddlewareContext(
+                    message=mcp_types.GetPromptRequestParams(
+                        name=name,
+                        arguments=arguments,
+                        # `_meta` carries the app-level `fastmcp` version key, which the
+                        # reserved-key RequestParamsMeta TypedDict can't express statically.
+                        _meta=_version_request_meta(version),  # type: ignore[unknown-argument]  # ty: ignore[invalid-argument-type]
+                    ),
+                    source="client",
+                    type="request",
+                    method="prompts/get",
+                    fastmcp_context=ctx,
+                )
+                return await self._run_middleware(
+                    context=mw_context,
+                    call_next=lambda context: self.render_prompt(
+                        context.message.name,
+                        context.message.arguments,
+                        version=version,
+                        run_middleware=False,
+                        task_meta=task_meta,
+                    ),
+                )
+
+            # Core logic: find and render prompt (providers queried in parallel)
+            # Use get_prompt to apply transforms and filter disabled
+            with server_span(
+                f"prompts/get {name}",
+                "prompts/get",
+                self.name,
+                "prompt",
+                name,
+                prompt_name=name,
+            ) as span:
+                prompt = await self.get_prompt(name, version=version)
+                if prompt is None:
+                    raise NotFoundError(f"Unknown prompt: {name!r}")
+                span.set_attributes(prompt.get_span_attributes())
+                if task_meta is not None and task_meta.fn_key is None:
+                    task_meta = replace(task_meta, fn_key=prompt.key)
+                try:
+                    return await prompt._render(arguments, task_meta=task_meta)
+                except FastMCPError as e:
+                    logger.log(
+                        e.log_level, f"Error rendering prompt {name!r}", exc_info=True
+                    )
+                    raise
+                except MCPError:
+                    logger.exception(f"Error rendering prompt {name!r}")
+                    raise
+                except Exception as e:
+                    logger.exception(f"Error rendering prompt {name!r}")
+                    if self._mask_error_details:
+                        raise PromptError(f"Error rendering prompt {name!r}") from e
+                    raise PromptError(f"Error rendering prompt {name!r}: {e}") from e
+
+    def add_tool(self, tool: Tool | Callable[..., Any]) -> Tool:
+        """Add a tool to the server.
+
+        The tool function can optionally request a Context object by adding a parameter
+        with the Context type annotation. See the @tool decorator for examples.
+
+        Args:
+            tool: The Tool instance or @tool-decorated function to register
+
+        Returns:
+            The tool instance that was added to the server.
+        """
+        return self._local_provider.add_tool(tool)
+
+    @overload
+    def tool(
+        self,
+        name_or_fn: F,
+        *,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[mcp_types.Icon] | None = None,
+        tags: set[str] | None = None,
+        output_schema: dict[str, Any] | NotSetT | None = NotSet,
+        annotations: ToolAnnotations | dict[str, Any] | None = None,
+        meta: dict[str, Any] | None = None,
+        app: AppConfig | dict[str, Any] | bool | None = None,
+        task: bool | TaskConfig | None = None,
+        timeout: float | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+        run_in_thread: bool = True,
+    ) -> F: ...
+
+    @overload
+    def tool(
+        self,
+        name_or_fn: str | None = None,
+        *,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[mcp_types.Icon] | None = None,
+        tags: set[str] | None = None,
+        output_schema: dict[str, Any] | NotSetT | None = NotSet,
+        annotations: ToolAnnotations | dict[str, Any] | None = None,
+        meta: dict[str, Any] | None = None,
+        app: AppConfig | dict[str, Any] | bool | None = None,
+        task: bool | TaskConfig | None = None,
+        timeout: float | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+        run_in_thread: bool = True,
+    ) -> Callable[[F], F]: ...
+
+    def tool(
+        self,
+        name_or_fn: str | AnyFunction | None = None,
+        *,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[mcp_types.Icon] | None = None,
+        tags: set[str] | None = None,
+        output_schema: dict[str, Any] | NotSetT | None = NotSet,
+        annotations: ToolAnnotations | dict[str, Any] | None = None,
+        meta: dict[str, Any] | None = None,
+        app: AppConfig | dict[str, Any] | bool | None = None,
+        task: bool | TaskConfig | None = None,
+        timeout: float | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+        run_in_thread: bool = True,
+    ) -> (
+        Callable[[AnyFunction], FunctionTool]
+        | FunctionTool
+        | partial[Callable[[AnyFunction], FunctionTool] | FunctionTool]
+    ):
+        """Decorator to register a tool.
+
+        Tools can optionally request a Context object by adding a parameter with the
+        Context type annotation. The context provides access to MCP capabilities like
+        logging, progress reporting, and resource access.
+
+        This decorator supports multiple calling patterns:
+        - @server.tool (without parentheses)
+        - @server.tool (with empty parentheses)
+        - @server.tool("custom_name") (with name as first argument)
+        - @server.tool(name="custom_name") (with name as keyword argument)
+        - server.tool(function, name="custom_name") (direct function call)
+
+        Args:
+            name_or_fn: Either a function (when used as @tool), a string name, or None
+            name: Optional name for the tool (keyword-only, alternative to name_or_fn)
+            description: Optional description of what the tool does
+            tags: Optional set of tags for categorizing the tool
+            output_schema: Optional JSON schema for the tool's output
+            annotations: Optional annotations about the tool's behavior
+            meta: Optional meta information about the tool
+
+        Examples:
+            Register a tool with a custom name:
+            ```python
+            @server.tool
+            def my_tool(x: int) -> str:
+                return str(x)
+
+            # Register a tool with a custom name
+            @server.tool
+            def my_tool(x: int) -> str:
+                return str(x)
+
+            @server.tool("custom_name")
+            def my_tool(x: int) -> str:
+                return str(x)
+
+            @server.tool(name="custom_name")
+            def my_tool(x: int) -> str:
+                return str(x)
+
+            # Direct function call
+            server.tool(my_function, name="custom_name")
+            ```
+        """
+        # Merge app config into meta["ui"] (wire format) before passing to provider
+        if app is not None and app is not False:
+            meta = dict(meta) if meta else {}
+            if app is True:
+                meta["ui"] = True
+            else:
+                meta["ui"] = app_config_to_meta_dict(app)
+
+        # Delegate to LocalProvider with server-level defaults
+        result = self._local_provider.tool(
+            name_or_fn,
+            name=name,
+            version=version,
+            title=title,
+            description=description,
+            icons=icons,
+            tags=tags,
+            output_schema=output_schema,
+            annotations=annotations,
+            meta=meta,
+            task=task if task is not None else self._support_tasks_by_default,
+            timeout=timeout,
+            auth=auth,
+            run_in_thread=run_in_thread,
+        )
+
+        return result
+
+    def add_resource(
+        self, resource: Resource | Callable[..., Any]
+    ) -> Resource | ResourceTemplate:
+        """Add a resource to the server.
+
+        Args:
+            resource: A Resource instance or @resource-decorated function to add
+
+        Returns:
+            The resource instance that was added to the server.
+        """
+        return self._local_provider.add_resource(resource)
+
+    def add_template(self, template: ResourceTemplate) -> ResourceTemplate:
+        """Add a resource template to the server.
+
+        Args:
+            template: A ResourceTemplate instance to add
+
+        Returns:
+            The template instance that was added to the server.
+        """
+        return self._local_provider.add_template(template)
+
+    def resource(
+        self,
+        uri: str,
+        *,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[mcp_types.Icon] | None = None,
+        mime_type: str | None = None,
+        tags: set[str] | None = None,
+        annotations: Annotations | dict[str, Any] | None = None,
+        meta: dict[str, Any] | None = None,
+        app: AppConfig | dict[str, Any] | bool | None = None,
+        task: bool | TaskConfig | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+    ) -> Callable[[F], F]:
+        """Decorator to register a function as a resource.
+
+        The function will be called when the resource is read to generate its content.
+        The function can return:
+        - str for text content
+        - bytes for binary content
+        - other types will be converted to JSON
+
+        Resources can optionally request a Context object by adding a parameter with the
+        Context type annotation. The context provides access to MCP capabilities like
+        logging, progress reporting, and session information.
+
+        If the URI contains parameters (e.g. "resource://{param}") or the function
+        has parameters, it will be registered as a template resource.
+
+        Args:
+            uri: URI for the resource (e.g. "resource://my-resource" or "resource://{param}")
+            name: Optional name for the resource
+            description: Optional description of the resource
+            mime_type: Optional MIME type for the resource
+            tags: Optional set of tags for categorizing the resource
+            annotations: Optional annotations about the resource's behavior
+            meta: Optional meta information about the resource
+
+        Examples:
+            Register a resource with a custom name:
+            ```python
+            @server.resource("resource://my-resource")
+            def get_data() -> str:
+                return "Hello, world!"
+
+            @server.resource("resource://my-resource")
+            async get_data() -> str:
+                data = await fetch_data()
+                return f"Hello, world! {data}"
+
+            @server.resource("resource://{city}/weather")
+            def get_weather(city: str) -> str:
+                return f"Weather for {city}"
+
+            @server.resource("resource://{city}/weather")
+            async def get_weather_with_context(city: str, ctx: Context) -> str:
+                await ctx.info(f"Fetching weather for {city}")
+                return f"Weather for {city}"
+
+            @server.resource("resource://{city}/weather")
+            async def get_weather(city: str) -> str:
+                data = await fetch_weather(city)
+                return f"Weather for {city}: {data}"
+            ```
+        """
+        # Catch incorrect decorator usage early (before any processing)
+        if not isinstance(uri, str):
+            raise TypeError(
+                "The @resource decorator was used incorrectly. "
+                "It requires a URI as the first argument. "
+                "Use @resource('uri') instead of @resource"
+            )
+
+        # Apply default MIME type for ui:// scheme resources
+        mime_type = resolve_ui_mime_type(uri, mime_type)
+
+        # Validate app config for resources — resource_uri and visibility
+        # don't apply since the resource itself is the UI
+        if isinstance(app, AppConfig):
+            if app.resource_uri is not None:
+                raise ValueError(
+                    "resource_uri cannot be set on resources — "
+                    "the resource itself is the UI. "
+                    "Use resource_uri on tools to point to a UI resource."
+                )
+            if app.visibility is not None:
+                raise ValueError(
+                    "visibility cannot be set on resources — it only applies to tools."
+                )
+
+        # Merge app config into meta["ui"] (wire format) before passing to provider
+        if app is not None and app is not False:
+            meta = dict(meta) if meta else {}
+            if app is True:
+                meta["ui"] = True
+            else:
+                meta["ui"] = app_config_to_meta_dict(app)
+
+        # Delegate to LocalProvider with server-level defaults
+        inner_decorator = self._local_provider.resource(
+            uri,
+            name=name,
+            version=version,
+            title=title,
+            description=description,
+            icons=icons,
+            mime_type=mime_type,
+            tags=tags,
+            annotations=annotations,
+            meta=meta,
+            task=task if task is not None else self._support_tasks_by_default,
+            auth=auth,
+        )
+
+        return inner_decorator
+
+    def add_prompt(self, prompt: Prompt | Callable[..., Any]) -> Prompt:
+        """Add a prompt to the server.
+
+        Args:
+            prompt: A Prompt instance or @prompt-decorated function to add
+
+        Returns:
+            The prompt instance that was added to the server.
+        """
+        return self._local_provider.add_prompt(prompt)
+
+    @overload
+    def prompt(
+        self,
+        name_or_fn: F,
+        *,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[mcp_types.Icon] | None = None,
+        tags: set[str] | None = None,
+        meta: dict[str, Any] | None = None,
+        task: bool | TaskConfig | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+    ) -> F: ...
+
+    @overload
+    def prompt(
+        self,
+        name_or_fn: str | None = None,
+        *,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[mcp_types.Icon] | None = None,
+        tags: set[str] | None = None,
+        meta: dict[str, Any] | None = None,
+        task: bool | TaskConfig | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+    ) -> Callable[[F], F]: ...
+
+    def prompt(
+        self,
+        name_or_fn: str | AnyFunction | None = None,
+        *,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[mcp_types.Icon] | None = None,
+        tags: set[str] | None = None,
+        meta: dict[str, Any] | None = None,
+        task: bool | TaskConfig | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+    ) -> (
+        Callable[[AnyFunction], FunctionPrompt]
+        | FunctionPrompt
+        | partial[Callable[[AnyFunction], FunctionPrompt] | FunctionPrompt]
+    ):
+        """Decorator to register a prompt.
+
+        Prompts can optionally request a Context object by adding a parameter with the
+        Context type annotation. The context provides access to MCP capabilities like
+        logging, progress reporting, and session information.
+
+        This decorator supports multiple calling patterns:
+        - @server.prompt (without parentheses)
+        - @server.prompt() (with empty parentheses)
+        - @server.prompt("custom_name") (with name as first argument)
+        - @server.prompt(name="custom_name") (with name as keyword argument)
+        - server.prompt(function, name="custom_name") (direct function call)
+
+        Args:
+            name_or_fn: Either a function (when used as @prompt), a string name, or None
+            name: Optional name for the prompt (keyword-only, alternative to name_or_fn)
+            description: Optional description of what the prompt does
+            tags: Optional set of tags for categorizing the prompt
+            meta: Optional meta information about the prompt
+
+        Examples:
+
+            ```python
+            @server.prompt
+            def analyze_table(table_name: str) -> list[Message]:
+                schema = read_table_schema(table_name)
+                return [
+                    {
+                        "role": "user",
+                        "content": f"Analyze this schema:\n{schema}"
+                    }
+                ]
+
+            @server.prompt()
+            async def analyze_with_context(table_name: str, ctx: Context) -> list[Message]:
+                await ctx.info(f"Analyzing table {table_name}")
+                schema = read_table_schema(table_name)
+                return [
+                    {
+                        "role": "user",
+                        "content": f"Analyze this schema:\n{schema}"
+                    }
+                ]
+
+            @server.prompt("custom_name")
+            async def analyze_file(path: str) -> list[Message]:
+                content = await read_file(path)
+                return [
+                    {
+                        "role": "user",
+                        "content": {
+                            "type": "resource",
+                            "resource": {
+                                "uri": f"file://{path}",
+                                "text": content
+                            }
+                        }
+                    }
+                ]
+
+            @server.prompt(name="custom_name")
+            def another_prompt(data: str) -> list[Message]:
+                return [{"role": "user", "content": data}]
+
+            # Direct function call
+            server.prompt(my_function, name="custom_name")
+            ```
+        """
+        # Delegate to LocalProvider with server-level defaults
+        return self._local_provider.prompt(
+            name_or_fn,
+            name=name,
+            version=version,
+            title=title,
+            description=description,
+            icons=icons,
+            tags=tags,
+            meta=meta,
+            task=task if task is not None else self._support_tasks_by_default,
+            auth=auth,
+        )
+
+    def mount(
+        self,
+        server: FastMCP[LifespanResultT],
+        namespace: str | None = None,
+        tool_names: dict[str, str] | None = None,
+    ) -> None:
+        """Mount another FastMCP server on this server with an optional namespace.
+
+        Mounting establishes a dynamic connection between servers. When a client
+        interacts with a mounted server's objects through the parent server, requests
+        are forwarded to the mounted server in real-time. This means changes to the
+        mounted server are immediately reflected when accessed through the parent.
+
+        When a server is mounted with a namespace:
+        - Tools from the mounted server are accessible with namespaced names.
+          Example: If server has a tool named "get_weather", it will be available as "namespace_get_weather".
+        - Resources are accessible with namespaced URIs.
+          Example: If server has a resource with URI "weather://forecast", it will be available as
+          "weather://namespace/forecast".
+        - Templates are accessible with namespaced URI templates.
+          Example: If server has a template with URI "weather://location/{id}", it will be available
+          as "weather://namespace/location/{id}".
+        - Prompts are accessible with namespaced names.
+          Example: If server has a prompt named "weather_prompt", it will be available as
+          "namespace_weather_prompt".
+
+        When a server is mounted without a namespace (namespace=None), its tools, resources, templates,
+        and prompts are accessible with their original names. Multiple servers can be mounted
+        without namespaces, and they will be tried in order until a match is found.
+
+        The mounted server's lifespan is executed when the parent server starts, and its
+        middleware chain is invoked for all operations (tool calls, resource reads, prompts).
+
+        Args:
+            server: The FastMCP server to mount.
+            namespace: Optional namespace to use for the mounted server's objects. If None,
+                the server's objects are accessible with their original names.
+            tool_names: Optional mapping of original tool names to custom names. Use this
+                to override namespaced names. Keys are the original tool names from the
+                mounted server.
+        """
+        from fastmcp.server.providers.fastmcp_provider import FastMCPProvider
+
+        if server is self:
+            raise ValueError("Cannot mount a server onto itself")
+
+        # Warn if parent masks errors but child doesn't (or vice versa)
+        if self._mask_error_details and not server._mask_error_details:
+            logger.warning(
+                f"Parent server {self.name!r} has mask_error_details=True but "
+                f"mounted server {server.name!r} does not. Error details from "
+                f"{server.name!r} may leak through to clients. Set "
+                f"mask_error_details=True on the child server to prevent this."
+            )
+
+        # Create provider and add it with namespace
+        provider: Provider = FastMCPProvider(server)
+
+        # Apply tool renames first (scoped to this provider), then namespace
+        # So foo → bar with namespace="baz" becomes baz_bar
+        if tool_names:
+            transforms = {
+                old_name: ToolTransformConfig(name=new_name)
+                for old_name, new_name in tool_names.items()
+            }
+            provider = provider.wrap_transform(ToolTransform(transforms))
+
+        # Use add_provider with namespace (applies namespace in AggregateProvider)
+        self.add_provider(provider, namespace=namespace or "")
+
+    @classmethod
+    def from_openapi(
+        cls,
+        openapi_spec: dict[str, Any],
+        client: httpx.AsyncClient | None = None,
+        name: str = "OpenAPI Server",
+        route_maps: list[RouteMap] | None = None,
+        route_map_fn: OpenAPIRouteMapFn | None = None,
+        mcp_component_fn: OpenAPIComponentFn | None = None,
+        mcp_names: dict[str, str] | None = None,
+        tags: set[str] | None = None,
+        validate_output: bool = True,
+        **settings: Any,
+    ) -> Self:
+        """
+        Create a FastMCP server from an OpenAPI specification.
+
+        Args:
+            openapi_spec: OpenAPI schema as a dictionary
+            client: Optional httpx AsyncClient for making HTTP requests.
+                If not provided, a default client is created using the first
+                server URL from the OpenAPI spec with a 30-second timeout.
+            name: Name for the MCP server
+            route_maps: Optional list of RouteMap objects defining route mappings
+            route_map_fn: Optional callable for advanced route type mapping
+            mcp_component_fn: Optional callable for component customization
+            mcp_names: Optional dictionary mapping operationId to component names
+            tags: Optional set of tags to add to all components
+            validate_output: If True (default), tools use the output schema
+                extracted from the OpenAPI spec for response validation. If
+                False, a permissive schema is used instead, allowing any
+                response structure while still returning structured JSON.
+            **settings: Additional settings passed to FastMCP
+
+        Returns:
+            A FastMCP server with an OpenAPIProvider attached.
+        """
+        from .providers.openapi import OpenAPIProvider
+
+        provider: Provider = OpenAPIProvider(
+            openapi_spec=openapi_spec,
+            client=client,
+            route_maps=route_maps,
+            route_map_fn=route_map_fn,
+            mcp_component_fn=mcp_component_fn,
+            mcp_names=mcp_names,
+            tags=tags,
+            validate_output=validate_output,
+        )
+        return cls(name=name, providers=[provider], **settings)
+
+    @classmethod
+    def from_fastapi(
+        cls,
+        app: Any,
+        name: str | None = None,
+        route_maps: list[RouteMap] | None = None,
+        route_map_fn: OpenAPIRouteMapFn | None = None,
+        mcp_component_fn: OpenAPIComponentFn | None = None,
+        mcp_names: dict[str, str] | None = None,
+        httpx_client_kwargs: dict[str, Any] | None = None,
+        tags: set[str] | None = None,
+        **settings: Any,
+    ) -> Self:
+        """
+        Create a FastMCP server from a FastAPI application.
+
+        Args:
+            app: FastAPI application instance
+            name: Name for the MCP server (defaults to app.title)
+            route_maps: Optional list of RouteMap objects defining route mappings
+            route_map_fn: Optional callable for advanced route type mapping
+            mcp_component_fn: Optional callable for component customization
+            mcp_names: Optional dictionary mapping operationId to component names
+            httpx_client_kwargs: Optional kwargs passed to httpx.AsyncClient.
+                Use this to configure timeout and other client settings.
+            tags: Optional set of tags to add to all components
+            **settings: Additional settings passed to FastMCP
+
+        Returns:
+            A FastMCP server with an OpenAPIProvider attached.
+        """
+        from .providers.openapi import OpenAPIProvider
+
+        if httpx_client_kwargs is None:
+            httpx_client_kwargs = {}
+        httpx_client_kwargs.setdefault("base_url", "http://fastapi")
+
+        client = httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=app),
+            **httpx_client_kwargs,
+        )
+
+        server_name = name or app.title
+
+        provider: Provider = OpenAPIProvider(
+            openapi_spec=app.openapi(),
+            client=client,
+            route_maps=route_maps,
+            route_map_fn=route_map_fn,
+            mcp_component_fn=mcp_component_fn,
+            mcp_names=mcp_names,
+            tags=tags,
+        )
+        return cls(name=server_name, providers=[provider], **settings)
+
+    @classmethod
+    def generate_name(cls, name: str | None = None) -> str:
+        class_name = cls.__name__
+
+        if name is None:
+            return f"{class_name}-{secrets.token_hex(2)}"
+        else:
+            return f"{class_name}-{name}-{secrets.token_hex(2)}"
+
+
+# -----------------------------------------------------------------------------
+# Module-level Factory Functions
+# -----------------------------------------------------------------------------
+
+
+def create_proxy(
+    target: (
+        Client[ClientTransportT]
+        | ClientTransport
+        | FastMCP[Any]
+        | SDKServer
+        | AnyUrl
+        | Path
+        | MCPConfig
+        | dict[str, Any]
+        | str
+    ),
+    **settings: Any,
+) -> FastMCPProxy:
+    """Create a FastMCP proxy server for the given target.
+
+    This is the recommended way to create a proxy server. For lower-level control,
+    use `FastMCPProxy` or `ProxyProvider` directly from `fastmcp.server.providers.proxy`.
+
+    Args:
+        target: The backend to proxy to. Can be:
+            - A Client instance (connected or disconnected)
+            - A ClientTransport
+            - A FastMCP server instance
+            - A URL string or AnyUrl
+            - A Path to a server script
+            - An MCPConfig or dict
+        **settings: Additional settings passed to FastMCPProxy (name, etc.)
+
+    Returns:
+        A FastMCPProxy server that proxies to the target.
+
+    Example:
+        ```python
+        from fastmcp.server import create_proxy
+
+        # Create a proxy to a remote server
+        proxy = create_proxy("http://remote-server/mcp")
+
+        # Create a proxy to another FastMCP server
+        proxy = create_proxy(other_server)
+        ```
+    """
+    from fastmcp.server.providers.proxy import (
+        FastMCPProxy,
+        _create_client_factory,
+    )
+
+    client_factory = _create_client_factory(target)
+    return FastMCPProxy(
+        client_factory=client_factory,
+        **settings,
+    )
diff --git a/fastmcp_slim/fastmcp/server/tasks/__init__.py b/fastmcp_slim/fastmcp/server/tasks/__init__.py
new file mode 100644
index 0000000..008332d
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/tasks/__init__.py
@@ -0,0 +1,38 @@
+"""MCP SEP-1686 background tasks support.
+
+This module implements protocol-level background task execution for MCP servers.
+"""
+
+from fastmcp.server.tasks.capabilities import get_task_capabilities
+from fastmcp.server.tasks.config import TaskConfig, TaskMeta, TaskMode
+from fastmcp.server.tasks.elicitation import (
+    elicit_for_task,
+    handle_task_input,
+    relay_elicitation,
+)
+from fastmcp.server.tasks.keys import (
+    build_task_key,
+    get_client_task_id_from_key,
+    parse_task_key,
+)
+from fastmcp.server.tasks.notifications import (
+    ensure_subscriber_running,
+    push_notification,
+    stop_subscriber,
+)
+
+__all__ = [
+    "TaskConfig",
+    "TaskMeta",
+    "TaskMode",
+    "build_task_key",
+    "elicit_for_task",
+    "ensure_subscriber_running",
+    "get_client_task_id_from_key",
+    "get_task_capabilities",
+    "handle_task_input",
+    "parse_task_key",
+    "push_notification",
+    "relay_elicitation",
+    "stop_subscriber",
+]
diff --git a/fastmcp_slim/fastmcp/server/tasks/capabilities.py b/fastmcp_slim/fastmcp/server/tasks/capabilities.py
new file mode 100644
index 0000000..d2ed14f
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/tasks/capabilities.py
@@ -0,0 +1,48 @@
+"""SEP-1686 task capabilities declaration."""
+
+from mcp_types import (
+    ServerTasksCapability,
+    ServerTasksRequestsCapability,
+    TasksCallCapability,
+    TasksCancelCapability,
+    TasksListCapability,
+    TasksToolsCapability,
+)
+
+
+def get_task_capabilities() -> ServerTasksCapability | None:
+    """Return the SEP-1686 task capabilities.
+
+    Returns task capabilities as a first-class ServerCapabilities field,
+    declaring support for list, cancel, and request operations per SEP-1686.
+
+    Returns None if a compatible pydocket is not installed (no task support).
+    Uses the canonical ``is_docket_available()`` check so that capability
+    advertisement and handler registration stay in sync — otherwise a server
+    with an old transitive pydocket would advertise task support and then
+    return "method not found" when clients invoked it.
+
+    Only tools are advertised as task-capable. In the SDK v2 b1 wire types,
+    ``ReadResourceRequestParams`` / ``GetPromptRequestParams`` carry no ``task``
+    field (sdk-feedback #3), so resource/prompt task submissions are not
+    wire-expressible and always graceful-degrade to synchronous execution.
+    Advertising ``prompts``/``resources`` task support would mislead
+    capability-discovering clients into sending task-augmented reads/gets that
+    silently run synchronously. Restore them here once the SDK adds task
+    metadata to those request params.
+    """
+    # Function-local import to avoid a circular import at module load time:
+    # fastmcp.server.tasks.__init__ pulls in this module, and dependencies
+    # transitively reaches back into fastmcp.server.tasks.keys.
+    from fastmcp.server.dependencies import is_docket_available
+
+    if not is_docket_available():
+        return None
+
+    return ServerTasksCapability(
+        list=TasksListCapability(),
+        cancel=TasksCancelCapability(),
+        requests=ServerTasksRequestsCapability(
+            tools=TasksToolsCapability(call=TasksCallCapability()),
+        ),
+    )
diff --git a/fastmcp_slim/fastmcp/server/tasks/config.py b/fastmcp_slim/fastmcp/server/tasks/config.py
new file mode 100644
index 0000000..b7fe2c5
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/tasks/config.py
@@ -0,0 +1,19 @@
+"""Backward-compatible exports for task configuration primitives."""
+
+from fastmcp.utilities.tasks import (
+    DEFAULT_POLL_INTERVAL,
+    DEFAULT_POLL_INTERVAL_MS,
+    DEFAULT_TTL_MS,
+    TaskConfig,
+    TaskMeta,
+    TaskMode,
+)
+
+__all__ = [
+    "DEFAULT_POLL_INTERVAL",
+    "DEFAULT_POLL_INTERVAL_MS",
+    "DEFAULT_TTL_MS",
+    "TaskConfig",
+    "TaskMeta",
+    "TaskMode",
+]
diff --git a/fastmcp_slim/fastmcp/server/tasks/context.py b/fastmcp_slim/fastmcp/server/tasks/context.py
new file mode 100644
index 0000000..7ade43d
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/tasks/context.py
@@ -0,0 +1,334 @@
+"""Task context and scoping for background task execution.
+
+Determines authorization scope (``get_task_scope``), manages the context
+snapshot that is captured at task submission and restored in workers
+(``TaskContextSnapshot``), and maintains in-process registries for live
+sessions and servers.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import weakref
+from collections import OrderedDict
+from contextvars import ContextVar
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from fastmcp.server.tasks.keys import parse_task_key, task_redis_prefix
+
+try:
+    from docket import TaskKey
+except ImportError:
+
+    def TaskKey() -> str:  # type: ignore[no-redef]
+        # Stub so this module stays importable without the fastmcp[tasks]
+        # extra. ``restore_task_snapshot`` is only ever invoked inside a
+        # Docket worker, where the real ``docket.TaskKey`` sentinel is
+        # always present.
+        return ""
+
+
+if TYPE_CHECKING:
+    from docket import Docket
+    from mcp.server.session import ServerSession
+
+    from fastmcp.server.server import FastMCP
+
+_logger = logging.getLogger(__name__)
+
+
+def get_task_scope() -> str | None:
+    """Get the authorization scope for task isolation.
+
+    Returns the raw scope identifier for the current access token, or
+    ``None`` when no auth context is present (anonymous tasks).
+
+    The scope is composed as ``client_id|sub`` when the token carries a
+    ``sub`` claim — necessary for fixed-OAuth servers where ``client_id`` is
+    shared across all users — and falls back to ``client_id`` alone for
+    DCR/CIMD flows where the client identity is already per-user.
+
+    Encoding for Redis/Docket keys happens at the boundary in ``keys.py``;
+    this function returns the raw value.
+    """
+    from fastmcp.server.dependencies import get_access_token
+
+    token = get_access_token()
+    if token is None:
+        return None
+    sub = token.claims.get("sub") if token.claims else None
+    if sub:
+        return f"{token.client_id}|{sub}"
+    return token.client_id
+
+
+@dataclass(frozen=True, slots=True)
+class TaskContextInfo:
+    """Information about the current background task context.
+
+    Returned by ``get_task_context()`` when running inside a Docket worker.
+    Contains identifiers needed to communicate with the MCP session.
+    """
+
+    task_id: str
+    """The MCP task ID (server-generated UUID)."""
+
+    task_scope: str | None
+    """The authorization scope that owns this task, or ``None`` if anonymous."""
+
+
+def get_task_context() -> TaskContextInfo | None:
+    """Get the current task context if running inside a background task worker.
+
+    This function extracts task information from the Docket execution context.
+    Returns None if not running in a task context (e.g., foreground execution).
+
+    Returns:
+        TaskContextInfo with task_id and task_scope, or None if not in a task.
+    """
+    from fastmcp.server.dependencies import is_docket_available
+
+    if not is_docket_available():
+        return None
+
+    from docket.dependencies import current_execution
+
+    try:
+        execution = current_execution.get()
+        key_parts = parse_task_key(execution.key)
+        return TaskContextInfo(
+            task_id=key_parts["client_task_id"],
+            task_scope=key_parts["task_scope"],
+        )
+    except LookupError:
+        return None
+    except (ValueError, KeyError):
+        return None
+
+
+@dataclass(frozen=True, slots=True)
+class TaskContextSnapshot:
+    """All context data snapshotted at task-submission time.
+
+    Stored as a single Redis key per task, restored once in the worker.
+    """
+
+    access_token_json: str | None = None
+    http_headers: dict[str, str] | None = None
+    origin_request_id: str | None = None
+    session_id: str | None = None
+
+    @classmethod
+    def capture(cls) -> TaskContextSnapshot:
+        """Capture current context for background task execution."""
+        from fastmcp.server.dependencies import (
+            get_access_token,
+            get_context,
+            get_http_headers,
+        )
+
+        access_token = get_access_token()
+        ctx = get_context()
+        request_context = ctx.request_context
+        try:
+            session_id = ctx.session_id
+        except RuntimeError:
+            session_id = None
+        return cls(
+            access_token_json=(
+                access_token.model_dump_json() if access_token else None
+            ),
+            http_headers=get_http_headers(include_all=True) or None,
+            origin_request_id=(
+                str(request_context.request_id) if request_context is not None else None
+            ),
+            session_id=session_id,
+        )
+
+    @classmethod
+    def from_json(cls, raw: str | bytes) -> TaskContextSnapshot:
+        """Deserialize from JSON stored in Redis."""
+        if isinstance(raw, bytes):
+            raw = raw.decode()
+        parsed = json.loads(raw)
+        headers = parsed.get("http_headers")
+        if isinstance(headers, dict):
+            headers = {str(k).lower(): str(v) for k, v in headers.items()}
+        return cls(
+            access_token_json=parsed.get("access_token_json"),
+            http_headers=headers,
+            origin_request_id=parsed.get("origin_request_id"),
+            session_id=parsed.get("session_id"),
+        )
+
+    def to_json(self) -> str:
+        """Serialize to JSON for Redis storage."""
+        return json.dumps(
+            {
+                "access_token_json": self.access_token_json,
+                "http_headers": self.http_headers,
+                "origin_request_id": self.origin_request_id,
+                "session_id": self.session_id,
+            }
+        )
+
+    async def save(
+        self,
+        docket: Docket,
+        task_scope: str | None,
+        task_id: str,
+        ttl_seconds: int,
+    ) -> None:
+        """Store this snapshot as a single Redis key."""
+        key = docket.key(f"{task_redis_prefix(task_scope)}:{task_id}:snapshot")
+        async with docket.redis() as redis:
+            await redis.set(key, self.to_json(), ex=ttl_seconds)
+
+
+# Cache keyed by task_id so stale entries from previous tasks in the same
+# asyncio context are automatically ignored (Docket workers may reuse contexts).
+_task_snapshot: ContextVar[tuple[str, TaskContextSnapshot] | None] = ContextVar(
+    "task_snapshot", default=None
+)
+
+
+def _remember_snapshot(task_id: str, snapshot: TaskContextSnapshot) -> None:
+    """Bind a snapshot to the current asyncio context under ``task_id``.
+
+    Nothing outside this task's context sees it; stale entries left in a
+    reused context are ignored on recall.
+    """
+    _task_snapshot.set((task_id, snapshot))
+
+
+def _recall_snapshot(task_id: str) -> TaskContextSnapshot | None:
+    """Return the snapshot bound for ``task_id`` in the current context.
+
+    Returns ``None`` if nothing is bound, or if the bound entry belongs to
+    a different task (a stale leftover from a reused asyncio context).
+    """
+    cached = _task_snapshot.get()
+    if cached is not None:
+        cached_task_id, snapshot = cached
+        if cached_task_id == task_id:
+            return snapshot
+    return None
+
+
+def get_task_session_id() -> str | None:
+    """Get the session_id for the current background task, if available.
+
+    Reads the cached snapshot set by the worker-level restore dependency.
+    Returns None if not in a task context or the snapshot wasn't restored.
+    """
+    task_info = get_task_context()
+    if task_info is None:
+        return None
+    snapshot = _recall_snapshot(task_info.task_id)
+    return snapshot.session_id if snapshot else None
+
+
+async def restore_task_snapshot(key: str = TaskKey()) -> None:
+    """Worker-level Docket dependency that restores the task-context snapshot.
+
+    Runs before each fastmcp-owned task, populating the snapshot ContextVar
+    so user code — and any task-scoped dependency like ``_CurrentContext`` —
+    sees a ready snapshot without touching Redis itself.  All Redis I/O
+    goes through Docket's async client, so cluster URLs and the memory://
+    backend work transparently (#3897).  Failures are non-fatal: the task
+    still runs, and sync helpers return ``None`` as they would have before
+    the snapshot was captured.
+    """
+    try:
+        parts = parse_task_key(key)
+    except ValueError:
+        # Non-fastmcp key (e.g. docket scheduler internals) — nothing to do.
+        return
+
+    from fastmcp.server.dependencies import _current_docket, get_server
+
+    try:
+        docket = get_server()._docket
+    except RuntimeError:
+        docket = None
+    if docket is None:
+        docket = _current_docket.get()
+    if docket is None:
+        return
+
+    task_scope = parts["task_scope"]
+    task_id = parts["client_task_id"]
+    try:
+        async with docket.redis() as redis:
+            raw = await redis.get(
+                docket.key(f"{task_redis_prefix(task_scope)}:{task_id}:snapshot")
+            )
+        if raw is None:
+            return
+        _remember_snapshot(task_id, TaskContextSnapshot.from_json(raw))
+    except Exception:
+        _logger.warning("Failed to restore task snapshot for %s", key, exc_info=True)
+
+
+# In-process optimization: when the Docket worker runs in the same process as
+# the MCP server, we can hand background tasks a live ServerSession so they can
+# call session methods directly (e.g. send_notification).  In distributed
+# deployments where workers are separate processes, these registries will be
+# empty and the worker's Context will have session=None — that's fine, because
+# elicitation and notifications have Redis-based fallbacks that work across
+# process boundaries (see notifications.py and elicitation.py).
+
+_task_sessions: dict[str, weakref.ref[ServerSession]] = {}
+
+
+def register_task_session(session_id: str, session: ServerSession) -> None:
+    """Register a session for in-process background task access.
+
+    Called automatically when a task is submitted to Docket. The session is
+    stored as a weakref so it doesn't prevent garbage collection when the
+    client disconnects.
+    """
+    _task_sessions[session_id] = weakref.ref(session)
+
+
+def get_task_session(session_id: str) -> ServerSession | None:
+    """Get a registered session by ID if still alive.
+
+    Returns None in distributed workers where the session lives in another
+    process — callers must handle this gracefully.
+    """
+    ref = _task_sessions.get(session_id)
+    if ref is None:
+        return None
+    session = ref()
+    if session is None:
+        _task_sessions.pop(session_id, None)
+    return session
+
+
+_task_server_map: OrderedDict[str, weakref.ref[FastMCP]] = OrderedDict()
+_TASK_SERVER_MAP_MAX_SIZE = 10_000
+
+
+def register_task_server(task_id: str, server: FastMCP) -> None:
+    """Register the server for a background task.
+
+    Called at task-submission time so that background workers can resolve
+    the correct (child) server for mounted tasks.
+    """
+    _task_server_map[task_id] = weakref.ref(server)
+    while len(_task_server_map) > _TASK_SERVER_MAP_MAX_SIZE:
+        _task_server_map.popitem(last=False)
+
+
+def get_task_server(task_id: str) -> FastMCP | None:
+    """Get the registered server for a background task, if still alive."""
+    ref = _task_server_map.get(task_id)
+    if ref is None:
+        return None
+    server = ref()
+    if server is None:
+        _task_server_map.pop(task_id, None)
+    return server
diff --git a/fastmcp_slim/fastmcp/server/tasks/elicitation.py b/fastmcp_slim/fastmcp/server/tasks/elicitation.py
new file mode 100644
index 0000000..d9a6e6d
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/tasks/elicitation.py
@@ -0,0 +1,347 @@
+"""Background task elicitation support (SEP-1686).
+
+This module provides elicitation capabilities for background tasks running
+in Docket workers. Unlike regular MCP requests, background tasks don't have
+an active request context, so elicitation requires special handling:
+
+1. Set task status to "input_required" via Redis
+2. Send notifications/tasks/status with elicitation metadata
+3. Wait for client to send input via tasks/sendInput
+4. Resume task execution with the provided input
+
+This uses the public MCP SDK APIs where possible, with minimal use of
+internal APIs for background task coordination.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import uuid
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any
+
+import mcp_types
+from mcp import ServerSession
+
+from fastmcp.server.tasks.context import get_task_context, get_task_session_id
+from fastmcp.server.tasks.keys import task_redis_prefix
+from fastmcp.server.tasks.notifications import push_notification
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP
+
+
+# TTL for elicitation state (1 hour)
+ELICIT_TTL_SECONDS = 3600
+
+
+def _elicit_keys(task_scope: str | None, task_id: str) -> tuple[str, str, str]:
+    """Build (request, response, status) Redis keys for a task's elicitation."""
+    prefix = f"{task_redis_prefix(task_scope)}:{task_id}:elicit"
+    return f"{prefix}:request", f"{prefix}:response", f"{prefix}:status"
+
+
+async def elicit_for_task(
+    task_id: str,
+    session: ServerSession | None,
+    message: str,
+    schema: dict[str, Any],
+    fastmcp: FastMCP,
+) -> mcp_types.ElicitResult:
+    """Send an elicitation request from a background task.
+
+    This function handles the complexity of eliciting user input when running
+    in a Docket worker context where there's no active MCP request.
+
+    Args:
+        task_id: The background task ID
+        session: The MCP ServerSession for this task
+        message: The message to display to the user
+        schema: The JSON schema for the expected response
+        fastmcp: The FastMCP server instance
+
+    Returns:
+        ElicitResult containing the user's response
+
+    Raises:
+        RuntimeError: If Docket is not available
+        MCPError: If the elicitation request fails
+    """
+    docket = fastmcp._docket
+    if docket is None:
+        raise RuntimeError(
+            "Background task elicitation requires Docket. "
+            "Ensure 'fastmcp[tasks]' is installed and the server has task-enabled components."
+        )
+
+    # Generate a unique request ID for this elicitation
+    request_id = str(uuid.uuid4())
+
+    task_context = get_task_context()
+    if task_context is not None:
+        task_scope = task_context.task_scope
+        # Prefer the live session's cached ID (always available in-process),
+        # fall back to the snapshot for distributed workers.
+        session_id = (
+            getattr(session, "_fastmcp_state_prefix", None) or get_task_session_id()
+        )
+    else:
+        raise RuntimeError(
+            "Cannot determine task scope for elicitation. "
+            "This typically means elicit_for_task() was called outside a Docket worker context."
+        )
+
+    # Store elicitation request in Redis
+    request_key, response_key, status_key = _elicit_keys(task_scope, task_id)
+
+    elicit_request = {
+        "request_id": request_id,
+        "message": message,
+        "schema": schema,
+    }
+
+    async with docket.redis() as redis:
+        # Store the elicitation request
+        await redis.set(
+            docket.key(request_key),
+            json.dumps(elicit_request),
+            ex=ELICIT_TTL_SECONDS,
+        )
+        # Set status to "waiting"
+        await redis.set(
+            docket.key(status_key),
+            "waiting",
+            ex=ELICIT_TTL_SECONDS,
+        )
+
+    # Send task status update notification with input_required status.
+    # Use notifications/tasks/status so typed MCP clients can consume it.
+    #
+    # NOTE: We use the distributed notification queue instead of session.send_notification()
+    # This enables notifications to work when workers run in separate processes
+    # (Azure Web PubSub / Service Bus inspired pattern)
+    timestamp = datetime.now(timezone.utc).isoformat()
+    notification_dict = {
+        "method": "notifications/tasks/status",
+        "params": {
+            "taskId": task_id,
+            "status": "input_required",
+            "statusMessage": message,
+            "createdAt": timestamp,
+            "lastUpdatedAt": timestamp,
+            "ttl": ELICIT_TTL_SECONDS * 1000,
+        },
+        "_meta": {
+            "io.modelcontextprotocol/related-task": {
+                "taskId": task_id,
+                "status": "input_required",
+                "statusMessage": message,
+                "task_scope": task_scope,
+                "elicitation": {
+                    "requestId": request_id,
+                    "message": message,
+                    "requestedSchema": schema,
+                },
+            }
+        },
+    }
+
+    if session_id is None:
+        logger.warning(
+            "No session_id available for task %s, cannot deliver elicitation notification",
+            task_id,
+        )
+        return mcp_types.ElicitResult(action="cancel", content=None)
+
+    try:
+        await push_notification(session_id, notification_dict, docket)
+    except Exception as e:
+        # Fail fast: if notification can't be queued, client won't know to respond
+        # Return cancel immediately rather than waiting for 1-hour timeout
+        logger.warning(
+            "Failed to queue input_required notification for task %s, cancelling elicitation: %s",
+            task_id,
+            e,
+        )
+        # Best-effort cleanup
+        try:
+            async with docket.redis() as redis:
+                await redis.delete(
+                    docket.key(request_key),
+                    docket.key(status_key),
+                )
+        except Exception:
+            pass  # Keys will expire via TTL
+        return mcp_types.ElicitResult(action="cancel", content=None)
+
+    # Wait for response using BLPOP (blocking pop)
+    # This is much more efficient than polling - single Redis round-trip
+    # that blocks until a response is pushed, vs 7,200 round-trips/hour with polling
+    max_wait_seconds = ELICIT_TTL_SECONDS
+
+    try:
+        async with docket.redis() as redis:
+            # BLPOP blocks until an item is pushed to the list or timeout
+            # Returns tuple of (key, value) or None on timeout
+            result = await redis.blpop(
+                [docket.key(response_key)],
+                timeout=max_wait_seconds,
+            )
+
+            if result:
+                # result is (key, value) tuple
+                _key, response_data = result
+                response = json.loads(response_data)
+
+                # Clean up Redis keys
+                await redis.delete(
+                    docket.key(request_key),
+                    docket.key(status_key),
+                )
+
+                # Convert to ElicitResult
+                return mcp_types.ElicitResult(
+                    action=response.get("action", "accept"),
+                    content=response.get("content"),
+                )
+    except Exception as e:
+        logger.warning(
+            "BLPOP failed for task %s elicitation, falling back to cancel: %s",
+            task_id,
+            e,
+        )
+
+    # Timeout or error - treat as cancellation
+    # Best-effort cleanup - if Redis is unavailable, keys will expire via TTL
+    try:
+        async with docket.redis() as redis:
+            await redis.delete(
+                docket.key(request_key),
+                docket.key(response_key),
+                docket.key(status_key),
+            )
+    except Exception as cleanup_error:
+        logger.debug(
+            "Failed to clean up elicitation keys for task %s (will expire via TTL): %s",
+            task_id,
+            cleanup_error,
+        )
+
+    return mcp_types.ElicitResult(action="cancel", content=None)
+
+
+async def relay_elicitation(
+    session: ServerSession,
+    task_scope: str | None,
+    task_id: str,
+    elicitation: dict[str, Any],
+    fastmcp: FastMCP,
+) -> None:
+    """Relay elicitation from a background task worker to the client.
+
+    Called by the notification subscriber when it detects an input_required
+    notification with elicitation metadata. Sends a standard elicitation/create
+    request to the client session, then uses handle_task_input() to push the
+    response to Redis so the blocked worker can resume.
+
+    Args:
+        session: MCP ServerSession
+        task_scope: Authorization scope for Redis key construction
+        task_id: Background task ID
+        elicitation: Elicitation metadata (message, requestedSchema)
+        fastmcp: FastMCP server instance
+    """
+    try:
+        result = await session.elicit(
+            message=elicitation["message"],
+            requested_schema=elicitation["requestedSchema"],
+        )
+        await handle_task_input(
+            task_id=task_id,
+            task_scope=task_scope,
+            action=result.action,
+            content=result.content,
+            fastmcp=fastmcp,
+        )
+        logger.debug(
+            "Relayed elicitation response for task %s (action=%s)",
+            task_id,
+            result.action,
+        )
+    except Exception as e:
+        logger.warning("Failed to relay elicitation for task %s: %s", task_id, e)
+        # Push a cancel response so the worker's BLPOP doesn't block forever
+        success = await handle_task_input(
+            task_id=task_id,
+            task_scope=task_scope,
+            action="cancel",
+            content=None,
+            fastmcp=fastmcp,
+        )
+        if not success:
+            logger.warning(
+                "Failed to push cancel response for task %s "
+                "(worker may block until TTL)",
+                task_id,
+            )
+
+
+async def handle_task_input(
+    task_id: str,
+    task_scope: str | None,
+    action: str,
+    content: dict[str, Any] | None,
+    fastmcp: FastMCP,
+) -> bool:
+    """Handle input sent to a background task via tasks/sendInput.
+
+    This is called when a client sends input in response to an elicitation
+    request from a background task.
+
+    Args:
+        task_id: The background task ID
+        task_scope: Authorization scope for Redis key construction
+        action: The elicitation action ("accept", "decline", "cancel")
+        content: The response content (for "accept" action)
+        fastmcp: The FastMCP server instance
+
+    Returns:
+        True if the input was successfully stored, False otherwise
+    """
+    docket = fastmcp._docket
+    if docket is None:
+        return False
+
+    _, response_key, status_key = _elicit_keys(task_scope, task_id)
+
+    response = {
+        "action": action,
+        "content": content,
+    }
+
+    async with docket.redis() as redis:
+        # Check if there's a pending elicitation
+        status = await redis.get(docket.key(status_key))
+        if status is None or status.decode("utf-8") != "waiting":
+            return False
+
+        # Push response to list - this wakes up the BLPOP in elicit_for_task
+        # Using LPUSH instead of SET enables the efficient blocking wait pattern
+        await redis.lpush(
+            docket.key(response_key),
+            json.dumps(response),
+        )
+        # Set TTL on the response list (in case BLPOP doesn't consume it)
+        await redis.expire(docket.key(response_key), ELICIT_TTL_SECONDS)
+
+        # Update status to "responded"
+        await redis.set(
+            docket.key(status_key),
+            "responded",
+            ex=ELICIT_TTL_SECONDS,
+        )
+
+    return True
diff --git a/fastmcp_slim/fastmcp/server/tasks/handlers.py b/fastmcp_slim/fastmcp/server/tasks/handlers.py
new file mode 100644
index 0000000..4b2ac17
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/tasks/handlers.py
@@ -0,0 +1,263 @@
+"""SEP-1686 task execution handlers.
+
+Handles queuing tool/prompt/resource executions to Docket as background tasks.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from contextlib import suppress
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any, Literal
+
+import mcp_types
+from mcp.shared.exceptions import MCPError
+from mcp_types import INTERNAL_ERROR
+
+from fastmcp.server.dependencies import (
+    _current_docket,
+    get_context,
+)
+from fastmcp.server.tasks.config import TaskMeta
+from fastmcp.server.tasks.context import (
+    TaskContextSnapshot,
+    get_task_scope,
+    register_task_server,
+    register_task_session,
+)
+from fastmcp.server.tasks.keys import build_task_key, task_redis_prefix
+from fastmcp.tools.function_tool import _strict_input_validation
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    from fastmcp.prompts.base import Prompt
+    from fastmcp.resources.base import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.tools.base import Tool
+
+logger = get_logger(__name__)
+
+# Redis mapping TTL buffer: Add 15 minutes to Docket's execution_ttl
+TASK_MAPPING_TTL_BUFFER_SECONDS = 15 * 60
+
+
+async def submit_to_docket(
+    task_type: Literal["tool", "resource", "template", "prompt"],
+    key: str,
+    component: Tool | Resource | ResourceTemplate | Prompt,
+    arguments: dict[str, Any] | None = None,
+    task_meta: TaskMeta | None = None,
+) -> mcp_types.CreateTaskResult:
+    """Submit any component to Docket for background execution (SEP-1686).
+
+    Unified handler for all component types. Called by component's internal
+    methods (_run, _read, _render) when task metadata is present and mode allows.
+
+    Queues the component's method to Docket, stores raw return values,
+    and converts to MCP types on retrieval.
+
+    Args:
+        task_type: Component type for task key construction
+        key: The component key as seen by MCP layer (with namespace prefix)
+        component: The component instance (Tool, Resource, ResourceTemplate, Prompt)
+        arguments: Arguments/params (None for Resource which has no args)
+        task_meta: Task execution metadata. If task_meta.ttl is provided, it
+            overrides the server default (docket.execution_ttl).
+
+    Returns:
+        CreateTaskResult: Task stub with proper Task object
+    """
+    # Validate and coerce arguments before creating any task state. A failure
+    # here must surface before the Redis metadata and initial "working"
+    # notification below are written, otherwise an invalid input would orphan a
+    # task the client has already observed (#4349).
+    #
+    # Honor the server's strict_input_validation setting so a strict tool
+    # rejects lax coercions (e.g. {"n": "1"} for n: int) at submission just as
+    # it does on the synchronous call path — otherwise task=True would bypass
+    # strict validation entirely.
+    if arguments is not None:
+        arguments = component.coerce_task_arguments(
+            arguments, strict=_strict_input_validation()
+        )
+
+    # Generate server-side task ID per SEP-1686 final spec (line 375-377)
+    # Server MUST generate task IDs, clients no longer provide them
+    server_task_id = str(uuid.uuid4())
+
+    # Record creation timestamp per SEP-1686 final spec (line 430). SDK v2
+    # types `Task.created_at` / `TaskStatusNotificationParams.created_at` as ISO
+    # strings, so carry a serialized copy for wire-crossing models.
+    created_at = datetime.now(timezone.utc)
+    created_at_iso = created_at.isoformat()
+
+    ctx = get_context()
+
+    # Authorization scope for task isolation (auth identity, or None for anonymous)
+    task_scope = get_task_scope()
+
+    # Transport session ID for notification delivery
+    try:
+        session_id = ctx.session_id
+    except RuntimeError:
+        session_id = None
+
+    # Try the server's own Docket first; fall back to the ContextVar for
+    # mounted children (whose parent server owns the Docket instance).
+    docket = ctx.fastmcp._docket or _current_docket.get()
+    if docket is None:
+        raise MCPError(
+            code=INTERNAL_ERROR,
+            message="Background tasks require a running FastMCP server context",
+        )
+
+    # Register the current server so background workers resolve
+    # CurrentFastMCP() / ctx.fastmcp to the correct (child) server
+    # for mounted tasks. At this point ctx.fastmcp is the child because
+    # we're inside the child's call_tool dispatch.
+    register_task_server(server_task_id, ctx.fastmcp)
+
+    # Build full task key with embedded metadata
+    task_key = build_task_key(task_scope, server_task_id, task_type, key)
+
+    # Determine TTL: use task_meta.ttl if provided, else docket default
+    if task_meta is not None and task_meta.ttl is not None:
+        ttl_ms = task_meta.ttl
+    else:
+        ttl_ms = int(docket.execution_ttl.total_seconds() * 1000)
+    ttl_seconds = int(ttl_ms / 1000) + TASK_MAPPING_TTL_BUFFER_SECONDS
+
+    # Store task metadata in Redis for protocol handlers
+    prefix = task_redis_prefix(task_scope)
+    task_meta_key = docket.key(f"{prefix}:{server_task_id}")
+    created_at_key = docket.key(f"{prefix}:{server_task_id}:created_at")
+    poll_interval_key = docket.key(f"{prefix}:{server_task_id}:poll_interval")
+    poll_interval_ms = int(component.task_config.poll_interval.total_seconds() * 1000)
+
+    # Snapshot all context (access token, headers, origin request ID,
+    # and session_id for notification delivery in background workers)
+    snapshot = TaskContextSnapshot.capture()
+
+    async with docket.redis() as redis:
+        await redis.set(task_meta_key, task_key, ex=ttl_seconds)
+        await redis.set(created_at_key, created_at.isoformat(), ex=ttl_seconds)
+        await redis.set(poll_interval_key, str(poll_interval_ms), ex=ttl_seconds)
+
+    await snapshot.save(docket, task_scope, server_task_id, ttl_seconds)
+
+    # Register session for Context access in background workers (SEP-1686)
+    # This enables elicitation/sampling from background tasks via weakref
+    # Skip when there is no session (programmatic calls without MCP session)
+    if session_id is not None:
+        register_task_session(session_id, ctx.session)
+
+    # Send an initial tasks/status notification before queueing.
+    # This guarantees clients can observe task creation immediately.
+    notification = mcp_types.TaskStatusNotification.model_validate(
+        {
+            "method": "notifications/tasks/status",
+            "params": {
+                "taskId": server_task_id,
+                "status": "working",
+                "statusMessage": "Task submitted",
+                "createdAt": created_at_iso,
+                "lastUpdatedAt": created_at_iso,
+                "ttl": ttl_ms,
+                "pollInterval": poll_interval_ms,
+            },
+            "_meta": {
+                "io.modelcontextprotocol/related-task": {
+                    "taskId": server_task_id,
+                }
+            },
+        }
+    )
+    # SDK v2: `ServerNotification` is a union type, not a wrapper class;
+    # `send_notification` takes the bare notification model directly.
+    with suppress(Exception):
+        # Don't let notification failures break task creation
+        await ctx.session.send_notification(notification)  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+
+    # Queue function to Docket by key (result storage via execution_ttl)
+    # Use component.add_to_docket() which handles calling conventions
+    # `fn_key` is the function lookup key (e.g., "child_multiply")
+    # `task_key` is the task result key (e.g., "fastmcp:task:{task_scope}:{task_id}:tool:child_multiply")
+    # Resources don't take arguments; tools/prompts/templates always pass arguments (even if None/empty)
+    if task_type == "resource":
+        await component.add_to_docket(docket, fn_key=key, task_key=task_key)  # type: ignore[call-arg]  # ty:ignore[missing-argument]
+    else:
+        await component.add_to_docket(docket, arguments, fn_key=key, task_key=task_key)  # type: ignore[call-arg]  # ty:ignore[invalid-argument-type, too-many-positional-arguments]
+
+    # Spawn subscription task to send status notifications (SEP-1686 optional feature).
+    # SDK v2 constructs a ServerSession per request and exposes no per-connection
+    # task group, so the subscription runs as a standalone asyncio task that
+    # outlives the submitting request; it is cancelled when the connection closes.
+    # Deferred: subscriptions and notifications depend on docket at import time
+    from fastmcp.server.tasks.subscriptions import subscribe_to_task_updates
+
+    subscription_task = asyncio.create_task(
+        subscribe_to_task_updates(
+            server_task_id,
+            task_key,
+            ctx.session,
+            docket,
+            poll_interval_ms,
+        ),
+        name=f"task-subscription-{server_task_id[:8]}",
+    )
+    connection = getattr(ctx.session, "_connection", None)
+    if connection is not None:
+
+        async def _cancel_subscription() -> None:
+            if not subscription_task.done():
+                subscription_task.cancel()
+                with suppress(asyncio.CancelledError):
+                    await subscription_task
+
+        connection.exit_stack.push_async_callback(_cancel_subscription)
+
+    # Deferred: notifications depends on docket at import time
+    from fastmcp.server.tasks.notifications import (
+        ensure_subscriber_running,
+        stop_subscriber,
+    )
+
+    if session_id is not None:
+        try:
+            await ensure_subscriber_running(
+                session_id, ctx.session, docket, ctx.fastmcp
+            )
+
+            # Register cleanup callback on connection exit (once per session).
+            # SDK v2 constructs ServerSession per request, so the stable
+            # per-connection lifecycle hook lives on the underlying Connection
+            # (`connection.exit_stack`), not the session. The registration flag
+            # is likewise stashed on the connection's `state` so it survives
+            # across requests.
+            connection = getattr(ctx.session, "_connection", None)
+            if connection is not None and not connection.state.get(
+                "_notification_cleanup_registered"
+            ):
+
+                async def _cleanup_subscriber() -> None:
+                    await stop_subscriber(session_id)  # type: ignore[arg-type]
+
+                connection.exit_stack.push_async_callback(_cleanup_subscriber)
+                connection.state["_notification_cleanup_registered"] = True
+        except Exception as e:
+            # Non-fatal: elicitation will still work via polling fallback
+            logger.debug("Failed to start notification subscriber: %s", e)
+
+    # Return CreateTaskResult with proper Task object
+    # Tasks MUST begin in "working" status per SEP-1686 final spec (line 381)
+    return mcp_types.CreateTaskResult(
+        task=mcp_types.Task(
+            task_id=server_task_id,
+            status="working",
+            created_at=created_at_iso,
+            last_updated_at=created_at_iso,
+            ttl=ttl_ms,
+            poll_interval=poll_interval_ms,
+        )
+    )
diff --git a/fastmcp_slim/fastmcp/server/tasks/keys.py b/fastmcp_slim/fastmcp/server/tasks/keys.py
new file mode 100644
index 0000000..10af6a6
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/tasks/keys.py
@@ -0,0 +1,165 @@
+"""Docket and Redis key encoding for background tasks.
+
+The compound Docket task key embeds the auth boundary so that the parser can
+reject cross-scope access without consulting Redis.  Authenticated and
+anonymous tasks live in disjoint keyspaces:
+
+    auth:{enc_scope}:{client_task_id}:{task_type}:{enc_identifier}
+    anon:{client_task_id}:{task_type}:{enc_identifier}
+
+The same `auth/anon` partition is used for the per-task Redis prefix
+(``fastmcp:task:auth:{enc_scope}`` vs ``fastmcp:task:anon``) — see
+``task_redis_prefix``.
+
+``task_scope`` is the raw scope identifier (typically derived from
+``client_id`` or ``client_id|sub``); encoding happens once, at the boundary,
+in this module.
+"""
+
+from typing import TypedDict
+from urllib.parse import quote, unquote
+
+
+class TaskKeyParts(TypedDict):
+    """Decoded segments of a Docket task key.
+
+    ``task_scope`` is ``None`` for anonymous tasks, the raw scope string
+    otherwise.
+    """
+
+    task_scope: str | None
+    client_task_id: str
+    task_type: str
+    component_identifier: str
+
+
+_AUTH_TAG = "auth"
+_ANON_TAG = "anon"
+_VALID_TAGS = (_AUTH_TAG, _ANON_TAG)
+
+
+def build_task_key(
+    task_scope: str | None,
+    client_task_id: str,
+    task_type: str,
+    component_identifier: str,
+) -> str:
+    """Build Docket task key with embedded metadata.
+
+    When ``task_scope`` is ``None`` the task is anonymous and lives in the
+    ``anon`` keyspace.  Otherwise it lives under ``auth:{enc_scope}``.
+
+    Args:
+        task_scope: Raw authorization scope, or ``None`` for anonymous tasks
+        client_task_id: Client-provided task ID
+        task_type: Type of task ("tool", "prompt", "resource")
+        component_identifier: Tool name, prompt name, or resource URI
+
+    Returns:
+        Encoded task key for Docket
+
+    Examples:
+        >>> build_task_key("client-a", "task456", "tool", "my_tool")
+        'auth:client-a:task456:tool:my_tool'
+
+        >>> build_task_key(None, "task456", "tool", "my_tool")
+        'anon:task456:tool:my_tool'
+
+        >>> build_task_key("client-a", "task456", "resource", "file://data.txt")
+        'auth:client-a:task456:resource:file%3A%2F%2Fdata.txt'
+    """
+    encoded_identifier = quote(component_identifier, safe="")
+    if task_scope is None:
+        return f"{_ANON_TAG}:{client_task_id}:{task_type}:{encoded_identifier}"
+    encoded_scope = quote(task_scope, safe="")
+    return (
+        f"{_AUTH_TAG}:{encoded_scope}:{client_task_id}:{task_type}:{encoded_identifier}"
+    )
+
+
+def parse_task_key(task_key: str) -> TaskKeyParts:
+    """Parse Docket task key to extract metadata.
+
+    Args:
+        task_key: Encoded task key from Docket
+
+    Returns:
+        Dict with keys: ``task_scope`` (``str | None``), ``client_task_id``,
+        ``task_type``, ``component_identifier``.
+
+    Raises:
+        ValueError: If the key has an unrecognized tag or wrong segment count.
+
+    Examples:
+        >>> parse_task_key("auth:client-a:task456:tool:my_tool")
+        `{'task_scope': 'client-a', 'client_task_id': 'task456', 'task_type': 'tool', 'component_identifier': 'my_tool'}`
+
+        >>> parse_task_key("anon:task456:tool:my_tool")
+        `{'task_scope': None, 'client_task_id': 'task456', 'task_type': 'tool', 'component_identifier': 'my_tool'}`
+    """
+    tag, _, rest = task_key.partition(":")
+    if tag not in _VALID_TAGS or not rest:
+        raise ValueError(
+            f"Invalid task key format: {task_key}. "
+            f"Expected leading tag in {_VALID_TAGS}."
+        )
+
+    if tag == _ANON_TAG:
+        parts = rest.split(":", 2)
+        if len(parts) != 3:
+            raise ValueError(
+                f"Invalid anonymous task key: {task_key}. "
+                f"Expected: anon:{{client_task_id}}:{{task_type}}:{{component_identifier}}"
+            )
+        client_task_id, task_type, encoded_identifier = parts
+        return {
+            "task_scope": None,
+            "client_task_id": client_task_id,
+            "task_type": task_type,
+            "component_identifier": unquote(encoded_identifier),
+        }
+
+    parts = rest.split(":", 3)
+    if len(parts) != 4:
+        raise ValueError(
+            f"Invalid authenticated task key: {task_key}. "
+            f"Expected: auth:{{enc_scope}}:{{client_task_id}}:{{task_type}}:{{component_identifier}}"
+        )
+    encoded_scope, client_task_id, task_type, encoded_identifier = parts
+    return {
+        "task_scope": unquote(encoded_scope),
+        "client_task_id": client_task_id,
+        "task_type": task_type,
+        "component_identifier": unquote(encoded_identifier),
+    }
+
+
+def get_client_task_id_from_key(task_key: str) -> str:
+    """Extract just the client task ID from a task key.
+
+    Args:
+        task_key: Full encoded task key
+
+    Returns:
+        Client-provided task ID
+
+    Examples:
+        >>> get_client_task_id_from_key("auth:client-a:task456:tool:my_tool")
+        'task456'
+
+        >>> get_client_task_id_from_key("anon:task456:tool:my_tool")
+        'task456'
+    """
+    return parse_task_key(task_key)["client_task_id"]
+
+
+def task_redis_prefix(task_scope: str | None) -> str:
+    """Return the Redis key prefix that owns a given scope.
+
+    Authenticated tasks live under ``fastmcp:task:auth:{enc_scope}``;
+    anonymous tasks live under ``fastmcp:task:anon``.  Callers append
+    ``f":{task_id}:..."`` to compose the final key.
+    """
+    if task_scope is None:
+        return f"fastmcp:task:{_ANON_TAG}"
+    return f"fastmcp:task:{_AUTH_TAG}:{quote(task_scope, safe='')}"
diff --git a/fastmcp_slim/fastmcp/server/tasks/notifications.py b/fastmcp_slim/fastmcp/server/tasks/notifications.py
new file mode 100644
index 0000000..9a662cd
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/tasks/notifications.py
@@ -0,0 +1,312 @@
+"""Distributed notification queue for background task events (SEP-1686).
+
+Enables distributed Docket workers to send MCP notifications to clients
+without holding session references. Workers push to a Redis queue,
+the MCP server process subscribes and forwards to the client's session.
+
+Pattern: Fire-and-forward with retry
+- One queue per session_id
+- LPUSH/BRPOP for reliable ordered delivery
+- Retry up to 3 times on delivery failure, then discard
+- TTL-based expiration for stale messages
+
+Note: Docket's execution.subscribe() handles task state/progress events via
+Redis Pub/Sub. This module handles elicitation-specific notifications that
+require reliable delivery (input_required prompts, cancel signals).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import weakref
+from contextlib import suppress
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any
+
+import mcp_types
+
+if TYPE_CHECKING:
+    from docket import Docket
+    from mcp.server.session import ServerSession
+
+    from fastmcp.server.server import FastMCP
+
+logger = logging.getLogger(__name__)
+
+# Redis key patterns
+NOTIFICATION_QUEUE_KEY = "fastmcp:notifications:{session_id}"
+NOTIFICATION_ACTIVE_KEY = "fastmcp:notifications:{session_id}:active"
+
+# Configuration
+NOTIFICATION_TTL_SECONDS = 300  # 5 minute message TTL (elicitation response window)
+MAX_DELIVERY_ATTEMPTS = 3  # Retry failed deliveries before discarding
+SUBSCRIBER_TIMEOUT_SECONDS = 30  # BRPOP timeout (also heartbeat interval)
+
+
+async def push_notification(
+    session_id: str,
+    notification: dict[str, Any],
+    docket: Docket,
+) -> None:
+    """Push notification to session's queue (called from Docket worker).
+
+    Used for elicitation-specific notifications (input_required, cancel)
+    that need reliable delivery across distributed processes.
+
+    Args:
+        session_id: Target session's identifier
+        notification: MCP notification dict (method, params, _meta)
+        docket: Docket instance for Redis access
+    """
+    key = docket.key(NOTIFICATION_QUEUE_KEY.format(session_id=session_id))
+    message = json.dumps(
+        {
+            "notification": notification,
+            "attempt": 0,
+            "enqueued_at": datetime.now(timezone.utc).isoformat(),
+        }
+    )
+    async with docket.redis() as redis:
+        await redis.lpush(key, message)
+        await redis.expire(key, NOTIFICATION_TTL_SECONDS)
+
+
+async def notification_subscriber_loop(
+    session_id: str,
+    session: ServerSession,
+    docket: Docket,
+    fastmcp: FastMCP,
+) -> None:
+    """Subscribe to notification queue and forward to session.
+
+    Runs in the MCP server process. Bridges distributed workers to clients.
+
+    This loop:
+    1. Maintains a heartbeat (active subscriber marker for debugging)
+    2. Blocks on BRPOP waiting for notifications
+    3. Forwards notifications to the client's session
+    4. Retries failed deliveries, then discards (no dead-letter queue)
+
+    Args:
+        session_id: Session identifier to subscribe to
+        session: MCP ServerSession for sending notifications
+        docket: Docket instance for Redis access
+        fastmcp: FastMCP server instance (for elicitation relay)
+    """
+    queue_key = docket.key(NOTIFICATION_QUEUE_KEY.format(session_id=session_id))
+    active_key = docket.key(NOTIFICATION_ACTIVE_KEY.format(session_id=session_id))
+
+    logger.debug("Starting notification subscriber for session %s", session_id)
+
+    while True:
+        try:
+            async with docket.redis() as redis:
+                # Heartbeat: mark subscriber as active (for distributed debugging)
+                await redis.set(active_key, "1", ex=SUBSCRIBER_TIMEOUT_SECONDS * 2)
+
+                # Blocking wait for notification (timeout refreshes heartbeat)
+                # Using BRPOP (right pop) for FIFO order with LPUSH (left push)
+                result = await redis.brpop(
+                    [queue_key], timeout=SUBSCRIBER_TIMEOUT_SECONDS
+                )
+                if not result:
+                    continue  # Timeout - refresh heartbeat and retry
+
+                _, message_bytes = result
+                message = json.loads(message_bytes)
+                notification_dict = message["notification"]
+                attempt = message.get("attempt", 0)
+
+                try:
+                    # Reconstruct and send MCP notification
+                    await _send_mcp_notification(
+                        session, notification_dict, session_id, docket, fastmcp
+                    )
+                    logger.debug(
+                        "Delivered notification to session %s (attempt %d)",
+                        session_id,
+                        attempt + 1,
+                    )
+                except Exception as send_error:
+                    # Delivery failed - retry or discard
+                    if attempt < MAX_DELIVERY_ATTEMPTS - 1:
+                        # Re-queue with incremented attempt (back of queue)
+                        message["attempt"] = attempt + 1
+                        message["last_error"] = str(send_error)
+                        await redis.lpush(queue_key, json.dumps(message))
+                        logger.debug(
+                            "Requeued notification for session %s (attempt %d): %s",
+                            session_id,
+                            attempt + 2,
+                            send_error,
+                        )
+                    else:
+                        # Discard after max attempts (session likely disconnected)
+                        logger.warning(
+                            "Discarding notification for session %s after %d attempts: %s",
+                            session_id,
+                            MAX_DELIVERY_ATTEMPTS,
+                            send_error,
+                        )
+
+        except asyncio.CancelledError:
+            # Graceful shutdown - leave pending messages in queue for reconnect
+            logger.debug("Notification subscriber cancelled for session %s", session_id)
+            break
+        except Exception as e:
+            logger.debug(
+                "Notification subscriber error for session %s: %s", session_id, e
+            )
+            await asyncio.sleep(1)  # Backoff on error
+
+
+async def _send_mcp_notification(
+    session: ServerSession,
+    notification_dict: dict[str, Any],
+    session_id: str,
+    docket: Docket,
+    fastmcp: FastMCP,
+) -> None:
+    """Reconstruct MCP notification from dict and send to session.
+
+    For input_required notifications with elicitation metadata, also sends
+    a standard elicitation/create request to the client and relays the
+    response back to the worker via Redis.
+
+    Args:
+        session: MCP ServerSession
+        notification_dict: Notification as dict (method, params, _meta)
+        session_id: Session identifier (for elicitation relay)
+        docket: Docket instance (for notification delivery)
+        fastmcp: FastMCP server instance (for elicitation relay)
+    """
+    method = notification_dict.get("method", "notifications/tasks/status")
+    if method != "notifications/tasks/status":
+        raise ValueError(f"Unsupported notification method for subscriber: {method}")
+
+    # SDK v2: a notification's `_meta` lives on its params (`params._meta`), not
+    # at the notification envelope level, so nest it under params before parsing.
+    params_dict = dict(notification_dict.get("params", {}))
+    meta_dict = notification_dict.get("_meta")
+    if meta_dict is not None:
+        params_dict["_meta"] = meta_dict
+    notification = mcp_types.TaskStatusNotification.model_validate(
+        {
+            "method": "notifications/tasks/status",
+            "params": params_dict,
+        }
+    )
+    # SDK v2: `ServerNotification` is a union type; send the bare model.
+    await session.send_notification(notification)  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+
+    # If this is an input_required notification with elicitation metadata,
+    # relay the elicitation to the client via standard elicitation/create
+    params = notification_dict.get("params", {})
+    if params.get("status") == "input_required":
+        meta = notification_dict.get("_meta", {})
+        related_task = meta.get("io.modelcontextprotocol/related-task", {})
+        elicitation = related_task.get("elicitation")
+        if elicitation:
+            task_id = params.get("taskId")
+            if not task_id:
+                logger.warning(
+                    "input_required notification missing taskId, skipping relay"
+                )
+                return
+            if "task_scope" not in related_task:
+                logger.warning(
+                    "input_required notification for task %s missing task_scope "
+                    "metadata, skipping elicitation relay",
+                    task_id,
+                )
+                return
+            task_scope = related_task["task_scope"]
+            from fastmcp.server.tasks.elicitation import relay_elicitation
+
+            task = asyncio.create_task(
+                relay_elicitation(session, task_scope, task_id, elicitation, fastmcp),
+                name=f"elicitation-relay-{task_id[:8]}",
+            )
+            _background_tasks.add(task)
+            task.add_done_callback(_background_tasks.discard)
+
+
+# =============================================================================
+# Subscriber Management
+# =============================================================================
+
+# Strong references to fire-and-forget relay tasks (prevent GC mid-flight)
+_background_tasks: set[asyncio.Task[None]] = set()
+
+# Registry of active subscribers per session (prevents duplicates)
+# Uses weakref to session to detect disconnects
+_active_subscribers: dict[
+    str, tuple[asyncio.Task[None], weakref.ref[ServerSession]]
+] = {}
+
+
+async def ensure_subscriber_running(
+    session_id: str,
+    session: ServerSession,
+    docket: Docket,
+    fastmcp: FastMCP,
+) -> None:
+    """Start notification subscriber if not already running (idempotent).
+
+    Subscriber is created on first task submission and cleaned up on disconnect.
+    Safe to call multiple times for the same session.
+
+    Args:
+        session_id: Session identifier
+        session: MCP ServerSession
+        docket: Docket instance
+        fastmcp: FastMCP server instance (for elicitation relay)
+    """
+    # Check if subscriber already running for this session
+    if session_id in _active_subscribers:
+        task, session_ref = _active_subscribers[session_id]
+        # Check if task is still running AND session is still alive
+        if not task.done() and session_ref() is not None:
+            return  # Already running
+
+        # Task finished or session dead - clean up
+        if not task.done():
+            task.cancel()
+            with suppress(asyncio.CancelledError):
+                await task
+        del _active_subscribers[session_id]
+
+    # Start new subscriber task
+    task = asyncio.create_task(
+        notification_subscriber_loop(session_id, session, docket, fastmcp),
+        name=f"notification-subscriber-{session_id[:8]}",
+    )
+    _active_subscribers[session_id] = (task, weakref.ref(session))
+    logger.debug("Started notification subscriber for session %s", session_id)
+
+
+async def stop_subscriber(session_id: str) -> None:
+    """Stop notification subscriber for a session.
+
+    Called when session disconnects. Pending messages remain in queue
+    for delivery if client reconnects (with TTL expiration).
+
+    Args:
+        session_id: Session identifier
+    """
+    if session_id not in _active_subscribers:
+        return
+
+    task, _ = _active_subscribers.pop(session_id)
+    if not task.done():
+        task.cancel()
+        with suppress(asyncio.CancelledError):
+            await task
+    logger.debug("Stopped notification subscriber for session %s", session_id)
+
+
+def get_subscriber_count() -> int:
+    """Get number of active subscribers (for monitoring)."""
+    return len(_active_subscribers)
diff --git a/fastmcp_slim/fastmcp/server/tasks/requests.py b/fastmcp_slim/fastmcp/server/tasks/requests.py
new file mode 100644
index 0000000..0cbc77a
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/tasks/requests.py
@@ -0,0 +1,456 @@
+"""SEP-1686 task request handlers.
+
+Handles MCP task protocol requests: tasks/get, tasks/result, tasks/list, tasks/cancel.
+These handlers query and manage existing tasks (contrast with handlers.py which creates tasks).
+
+This module requires fastmcp[tasks] (pydocket). It is only imported when docket is available.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING, Any, Literal
+
+import mcp_types
+from docket.execution import ExecutionState
+from mcp.shared.exceptions import MCPError
+from mcp_types import (
+    INTERNAL_ERROR,
+    INVALID_PARAMS,
+    CancelTaskResult,
+    GetTaskResult,
+    ListTasksResult,
+)
+
+import fastmcp.server.context
+from fastmcp.exceptions import NotFoundError
+from fastmcp.prompts.base import Prompt
+from fastmcp.resources.base import Resource
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.tasks.config import DEFAULT_POLL_INTERVAL_MS, DEFAULT_TTL_MS
+from fastmcp.server.tasks.context import get_task_scope
+from fastmcp.server.tasks.keys import parse_task_key, task_redis_prefix
+from fastmcp.tools.base import Tool
+from fastmcp.utilities.versions import VersionSpec
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP
+
+
+# Map Docket execution states to MCP task status strings
+# Per SEP-1686 final spec (line 381): tasks MUST begin in "working" status
+DOCKET_TO_MCP_STATE: dict[ExecutionState, str] = {
+    ExecutionState.SCHEDULED: "working",  # Initial state per spec
+    ExecutionState.QUEUED: "working",  # Initial state per spec
+    ExecutionState.RUNNING: "working",
+    ExecutionState.COMPLETED: "completed",
+    ExecutionState.FAILED: "failed",
+    ExecutionState.CANCELLED: "cancelled",
+}
+
+
+def _normalize_iso_timestamp(stored: str | None) -> str:
+    """Return an ISO 8601 timestamp string for a Task's createdAt/lastUpdatedAt.
+
+    The v2 Task model types these fields as ISO 8601 strings. `stored` is the
+    value read from Redis (already an ISO string) or None; either way this
+    returns a valid ISO string, falling back to the current UTC time.
+    """
+    if stored:
+        try:
+            return datetime.fromisoformat(stored.replace("Z", "+00:00")).isoformat()
+        except (ValueError, AttributeError):
+            pass
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _parse_key_version(key_suffix: str) -> tuple[str, str | None]:
+    """Parse a key suffix into (name_or_uri, version).
+
+    Keys always contain @ as a version delimiter (sentinel pattern):
+    - "add@1.0" → ("add", "1.0")  # versioned
+    - "add@" → ("add", None)      # unversioned
+    - "user@example.com@1.0" → ("user@example.com", "1.0")  # @ in URI
+
+    Uses rsplit to split on the LAST @ which is always the version delimiter.
+    Falls back to treating the whole string as the name if @ is not present
+    (for backwards compatibility with legacy task keys).
+    """
+    if "@" not in key_suffix:
+        # Legacy key without version sentinel - treat as unversioned
+        return key_suffix, None
+    name_or_uri, version = key_suffix.rsplit("@", 1)
+    return name_or_uri, version if version else None
+
+
+async def _lookup_task_execution(
+    docket: Any,
+    task_scope: str | None,
+    client_task_id: str,
+) -> tuple[Any, str | None, int]:
+    """Look up task execution and metadata from Redis.
+
+    Consolidates the common pattern of fetching task metadata from Redis,
+    validating it exists, and retrieving the Docket execution.
+
+    Args:
+        docket: Docket instance
+        task_scope: Authorization scope
+        client_task_id: Client-provided task ID
+
+    Returns:
+        Tuple of (execution, created_at, poll_interval_ms)
+
+    Raises:
+        MCPError: If task not found or execution not found
+    """
+    prefix = task_redis_prefix(task_scope)
+    task_meta_key = docket.key(f"{prefix}:{client_task_id}")
+    created_at_key = docket.key(f"{prefix}:{client_task_id}:created_at")
+    poll_interval_key = docket.key(f"{prefix}:{client_task_id}:poll_interval")
+
+    # Fetch metadata (single round-trip with mget)
+    async with docket.redis() as redis:
+        task_key_bytes, created_at_bytes, poll_interval_bytes = await redis.mget(
+            task_meta_key, created_at_key, poll_interval_key
+        )
+
+    # Decode and validate task_key
+    task_key = task_key_bytes.decode("utf-8") if task_key_bytes else None
+    if not task_key:
+        raise MCPError(code=INVALID_PARAMS, message=f"Task {client_task_id} not found")
+
+    # Get execution
+    execution = await docket.get_execution(task_key)
+    if not execution:
+        raise MCPError(
+            code=INVALID_PARAMS,
+            message=f"Task {client_task_id} execution not found",
+        )
+
+    # Parse metadata with defaults
+    created_at = created_at_bytes.decode("utf-8") if created_at_bytes else None
+    try:
+        poll_interval_ms = (
+            int(poll_interval_bytes.decode("utf-8"))
+            if poll_interval_bytes
+            else DEFAULT_POLL_INTERVAL_MS
+        )
+    except (ValueError, UnicodeDecodeError):
+        poll_interval_ms = DEFAULT_POLL_INTERVAL_MS
+
+    return execution, created_at, poll_interval_ms
+
+
+async def tasks_get_handler(server: FastMCP, params: dict[str, Any]) -> GetTaskResult:
+    """Handle MCP 'tasks/get' request (SEP-1686).
+
+    Args:
+        server: FastMCP server instance
+        params: Request params containing taskId
+
+    Returns:
+        GetTaskResult: Task status response with spec-compliant fields
+    """
+    async with fastmcp.server.context.Context(fastmcp=server):
+        client_task_id = params.get("taskId")
+        if not client_task_id:
+            raise MCPError(
+                code=INVALID_PARAMS, message="Missing required parameter: taskId"
+            )
+
+        # Get authorization scope for task lookup
+        task_scope = get_task_scope()
+
+        # Get Docket instance
+        docket = server._docket
+        if docket is None:
+            raise MCPError(
+                code=INTERNAL_ERROR,
+                message="Background tasks require Docket",
+            )
+
+        # Look up task execution and metadata
+        execution, created_at, poll_interval_ms = await _lookup_task_execution(
+            docket, task_scope, client_task_id
+        )
+
+        # Sync state from Redis
+        await execution.sync()
+
+        # Map Docket state to MCP state
+        state_map = DOCKET_TO_MCP_STATE
+        mcp_state: Literal[
+            "working", "input_required", "completed", "failed", "cancelled"
+        ] = state_map.get(execution.state, "failed")  # type: ignore[assignment]  # ty:ignore[invalid-assignment]
+
+        # Build response (use default ttl since we don't track per-task values)
+        # createdAt is REQUIRED per SEP-1686 final spec (line 430)
+        # Per spec lines 447-448: SHOULD NOT include related-task metadata in tasks/get
+        error_message = None
+        status_message = None
+
+        if execution.state == ExecutionState.FAILED:
+            try:
+                await execution.get_result(timeout=timedelta(seconds=0))
+            except Exception as error:
+                error_message = str(error)
+                status_message = f"Task failed: {error_message}"
+        elif execution.progress and execution.progress.message:
+            # Extract progress message from Docket if available (spec line 403)
+            status_message = execution.progress.message
+
+        # createdAt is required per spec, but can be None from Redis. The v2
+        # Task model types createdAt/lastUpdatedAt as ISO 8601 strings, so
+        # normalize the stored value (or fall back to now) to an ISO string.
+        created_at_iso = _normalize_iso_timestamp(created_at)
+
+        return GetTaskResult(
+            task_id=client_task_id,
+            status=mcp_state,
+            created_at=created_at_iso,
+            last_updated_at=datetime.now(timezone.utc).isoformat(),
+            ttl=DEFAULT_TTL_MS,
+            poll_interval=poll_interval_ms,
+            status_message=status_message,
+        )
+
+
+async def tasks_result_handler(server: FastMCP, params: dict[str, Any]) -> Any:
+    """Handle MCP 'tasks/result' request (SEP-1686).
+
+    Converts raw task return values to MCP types based on task type.
+
+    Args:
+        server: FastMCP server instance
+        params: Request params containing taskId
+
+    Returns:
+        MCP result (CallToolResult, GetPromptResult, or ReadResourceResult)
+    """
+    async with fastmcp.server.context.Context(fastmcp=server):
+        client_task_id = params.get("taskId")
+        if not client_task_id:
+            raise MCPError(
+                code=INVALID_PARAMS, message="Missing required parameter: taskId"
+            )
+
+        # Get authorization scope for task lookup
+        task_scope = get_task_scope()
+
+        # Get execution from Docket (use instance attribute for cross-task access)
+        docket = server._docket
+        if docket is None:
+            raise MCPError(
+                code=INTERNAL_ERROR,
+                message="Background tasks require Docket",
+            )
+
+        # Look up full task key from Redis
+        task_meta_key = docket.key(f"{task_redis_prefix(task_scope)}:{client_task_id}")
+        async with docket.redis() as redis:
+            task_key_bytes = await redis.get(task_meta_key)
+
+        task_key = None if task_key_bytes is None else task_key_bytes.decode("utf-8")
+
+        if task_key is None:
+            raise MCPError(
+                code=INVALID_PARAMS,
+                message=f"Invalid taskId: {client_task_id} not found",
+            )
+
+        execution = await docket.get_execution(task_key)
+        if execution is None:
+            raise MCPError(
+                code=INVALID_PARAMS,
+                message=f"Invalid taskId: {client_task_id} not found",
+            )
+
+        # Sync state from Redis
+        await execution.sync()
+
+        # Check if completed
+        state_map = DOCKET_TO_MCP_STATE
+        if execution.state not in (ExecutionState.COMPLETED, ExecutionState.FAILED):
+            mcp_state = state_map.get(execution.state, "failed")
+            raise MCPError(
+                code=INVALID_PARAMS,
+                message=f"Task not completed yet (current state: {mcp_state})",
+            )
+
+        # Get result from Docket
+        try:
+            raw_value = await execution.get_result(timeout=timedelta(seconds=0))
+        except Exception as error:
+            # Task failed - return error result
+            return mcp_types.CallToolResult(
+                content=[mcp_types.TextContent(type="text", text=str(error))],
+                is_error=True,
+                _meta={  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
+                    "io.modelcontextprotocol/related-task": {
+                        "taskId": client_task_id,
+                    }
+                },
+            )
+
+        # Parse task key to get component key
+        key_parts = parse_task_key(task_key)
+        component_key = key_parts["component_identifier"]
+
+        # Look up component by its prefixed key (inlined from deleted get_component)
+        component: Tool | Resource | ResourceTemplate | Prompt | None = None
+        try:
+            if component_key.startswith("tool:"):
+                name, version_str = _parse_key_version(component_key[5:])
+                version = VersionSpec(eq=version_str) if version_str else None
+                component = await server.get_tool(name, version)
+            elif component_key.startswith("resource:"):
+                uri, version_str = _parse_key_version(component_key[9:])
+                version = VersionSpec(eq=version_str) if version_str else None
+                component = await server.get_resource(uri, version)
+            elif component_key.startswith("template:"):
+                uri, version_str = _parse_key_version(component_key[9:])
+                version = VersionSpec(eq=version_str) if version_str else None
+                component = await server.get_resource_template(uri, version)
+            elif component_key.startswith("prompt:"):
+                name, version_str = _parse_key_version(component_key[7:])
+                version = VersionSpec(eq=version_str) if version_str else None
+                component = await server.get_prompt(name, version)
+        except NotFoundError:
+            component = None
+
+        if component is None:
+            raise MCPError(
+                code=INTERNAL_ERROR,
+                message=f"Component not found for task: {component_key}",
+            )
+
+        # Build related-task metadata
+        related_task_meta = {
+            "io.modelcontextprotocol/related-task": {
+                "taskId": client_task_id,
+            }
+        }
+
+        # Convert based on component type.
+        # Each branch merges related_task_meta with any existing _meta
+        # (e.g. fastmcp.wrap_result) rather than overwriting it.
+        if isinstance(component, Tool):
+            fastmcp_result = component.convert_result(raw_value)
+            mcp_result = fastmcp_result.to_mcp_result()
+            if isinstance(mcp_result, mcp_types.CallToolResult):
+                merged = {**(mcp_result.meta or {}), **related_task_meta}
+                mcp_result._meta = merged  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+            elif isinstance(mcp_result, tuple):
+                content, structured_content = mcp_result
+                mcp_result = mcp_types.CallToolResult(
+                    content=content,
+                    structured_content=structured_content,
+                    _meta=related_task_meta,  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
+                )
+            else:
+                mcp_result = mcp_types.CallToolResult(
+                    content=mcp_result,
+                    _meta=related_task_meta,  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
+                )
+            return mcp_result
+
+        elif isinstance(component, Prompt):
+            fastmcp_result = component.convert_result(raw_value)
+            mcp_result = fastmcp_result.to_mcp_prompt_result()
+            merged = {**(mcp_result.meta or {}), **related_task_meta}
+            mcp_result._meta = merged  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+            return mcp_result
+
+        elif isinstance(component, ResourceTemplate):
+            fastmcp_result = component.convert_result(raw_value)
+            mcp_result = fastmcp_result.to_mcp_result(component.uri_template)
+            merged = {**(mcp_result.meta or {}), **related_task_meta}
+            mcp_result._meta = merged  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+            return mcp_result
+
+        elif isinstance(component, Resource):
+            fastmcp_result = component.convert_result(raw_value)
+            mcp_result = fastmcp_result.to_mcp_result(str(component.uri))
+            merged = {**(mcp_result.meta or {}), **related_task_meta}
+            mcp_result._meta = merged  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+            return mcp_result
+
+        else:
+            raise MCPError(
+                code=INTERNAL_ERROR,
+                message=f"Internal error: Unknown component type: {type(component).__name__}",
+            )
+
+
+async def tasks_list_handler(
+    server: FastMCP, params: dict[str, Any]
+) -> ListTasksResult:
+    """Handle MCP 'tasks/list' request (SEP-1686).
+
+    Note: With client-side tracking, this returns minimal info.
+
+    Args:
+        server: FastMCP server instance
+        params: Request params (cursor, limit)
+
+    Returns:
+        ListTasksResult: Response with tasks list and pagination
+    """
+    # Return empty list - client tracks tasks locally
+    return ListTasksResult(tasks=[], next_cursor=None)
+
+
+async def tasks_cancel_handler(
+    server: FastMCP, params: dict[str, Any]
+) -> CancelTaskResult:
+    """Handle MCP 'tasks/cancel' request (SEP-1686).
+
+    Cancels a running task, transitioning it to cancelled state.
+
+    Args:
+        server: FastMCP server instance
+        params: Request params containing taskId
+
+    Returns:
+        CancelTaskResult: Task status response showing cancelled state
+    """
+    async with fastmcp.server.context.Context(fastmcp=server):
+        client_task_id = params.get("taskId")
+        if not client_task_id:
+            raise MCPError(
+                code=INVALID_PARAMS, message="Missing required parameter: taskId"
+            )
+
+        # Get authorization scope for task lookup
+        task_scope = get_task_scope()
+
+        # Get Docket instance
+        docket = server._docket
+        if docket is None:
+            raise MCPError(
+                code=INTERNAL_ERROR,
+                message="Background tasks require Docket",
+            )
+
+        # Look up task execution and metadata
+        execution, created_at, poll_interval_ms = await _lookup_task_execution(
+            docket, task_scope, client_task_id
+        )
+
+        # Cancel via Docket (now sets CANCELLED state natively)
+        # Note: We need to get task_key from execution.key for cancellation
+        await docket.cancel(execution.key)
+
+        # Return task status with cancelled state
+        # createdAt is REQUIRED per SEP-1686 final spec (line 430)
+        # Per spec lines 447-448: SHOULD NOT include related-task metadata in tasks/cancel
+        return CancelTaskResult(
+            task_id=client_task_id,
+            status="cancelled",
+            created_at=_normalize_iso_timestamp(created_at),
+            last_updated_at=datetime.now(timezone.utc).isoformat(),
+            ttl=DEFAULT_TTL_MS,
+            poll_interval=poll_interval_ms,
+            status_message="Task cancelled",
+        )
diff --git a/fastmcp_slim/fastmcp/server/tasks/routing.py b/fastmcp_slim/fastmcp/server/tasks/routing.py
new file mode 100644
index 0000000..97839ef
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/tasks/routing.py
@@ -0,0 +1,72 @@
+"""Task routing helper for MCP components.
+
+Provides unified task mode enforcement and docket routing logic.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+import mcp_types
+from mcp.shared.exceptions import MCPError
+from mcp_types import METHOD_NOT_FOUND
+
+from fastmcp.server.tasks.config import TaskMeta
+from fastmcp.server.tasks.handlers import submit_to_docket
+
+if TYPE_CHECKING:
+    from fastmcp.prompts.base import Prompt
+    from fastmcp.resources.base import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.tools.base import Tool
+
+TaskType = Literal["tool", "resource", "template", "prompt"]
+
+
+async def check_background_task(
+    component: Tool | Resource | ResourceTemplate | Prompt,
+    task_type: TaskType,
+    arguments: dict[str, Any] | None = None,
+    task_meta: TaskMeta | None = None,
+) -> mcp_types.CreateTaskResult | None:
+    """Check task mode and submit to background if requested.
+
+    Args:
+        component: The MCP component
+        task_type: Type of task ("tool", "resource", "template", "prompt")
+        arguments: Arguments for tool/prompt/template execution
+        task_meta: Task execution metadata. If provided, execute as background task.
+
+    Returns:
+        CreateTaskResult if submitted to docket, None for sync execution
+
+    Raises:
+        MCPError: If mode="required" but no task metadata, or mode="forbidden"
+                  but task metadata is present
+    """
+    task_config = component.task_config
+
+    # Infer label from component
+    entity_label = f"{type(component).__name__} '{component.title or component.key}'"
+
+    # Enforce mode="required" - must have task metadata
+    if task_config.mode == "required" and not task_meta:
+        raise MCPError(
+            code=METHOD_NOT_FOUND,
+            message=f"{entity_label} requires task-augmented execution",
+        )
+
+    # Enforce mode="forbidden" - cannot be called with task metadata
+    if not task_config.supports_tasks() and task_meta:
+        raise MCPError(
+            code=METHOD_NOT_FOUND,
+            message=f"{entity_label} does not support task-augmented execution",
+        )
+
+    # No task metadata - synchronous execution
+    if not task_meta:
+        return None
+
+    # fn_key is expected to be set; fall back to component.key for direct calls
+    fn_key = task_meta.fn_key or component.key
+    return await submit_to_docket(task_type, fn_key, component, arguments, task_meta)
diff --git a/fastmcp_slim/fastmcp/server/tasks/subscriptions.py b/fastmcp_slim/fastmcp/server/tasks/subscriptions.py
new file mode 100644
index 0000000..c116bd1
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/tasks/subscriptions.py
@@ -0,0 +1,222 @@
+"""Task subscription helpers for sending MCP notifications (SEP-1686).
+
+Subscribes to Docket execution state changes and sends notifications/tasks/status
+to clients when their tasks change state.
+
+This module requires fastmcp[tasks] (pydocket). It is only imported when docket is available.
+"""
+
+from __future__ import annotations
+
+from contextlib import suppress
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+from docket.execution import ExecutionState
+from mcp_types import TaskStatusNotification, TaskStatusNotificationParams
+
+from fastmcp.server.tasks.config import DEFAULT_TTL_MS
+from fastmcp.server.tasks.keys import parse_task_key, task_redis_prefix
+from fastmcp.server.tasks.requests import DOCKET_TO_MCP_STATE
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    from docket import Docket
+    from docket.execution import Execution
+    from mcp.server.session import ServerSession
+
+logger = get_logger(__name__)
+
+
+async def subscribe_to_task_updates(
+    task_id: str,
+    task_key: str,
+    session: ServerSession,
+    docket: Docket,
+    poll_interval_ms: int = 5000,
+) -> None:
+    """Subscribe to Docket execution events and send MCP notifications.
+
+    Per SEP-1686 lines 436-444, servers MAY send notifications/tasks/status
+    when task state changes. This is an optional optimization that reduces
+    client polling frequency.
+
+    Args:
+        task_id: Client-visible task ID (server-generated UUID)
+        task_key: Internal Docket execution key (includes session, type, component)
+        session: MCP ServerSession for sending notifications
+        docket: Docket instance for subscribing to execution events
+        poll_interval_ms: Poll interval in milliseconds to include in notifications
+    """
+    try:
+        execution = await docket.get_execution(task_key)
+        if execution is None:
+            logger.warning(f"No execution found for task {task_id}")
+            return
+
+        # Subscribe to state and progress events from Docket
+        terminal_states = {
+            ExecutionState.COMPLETED,
+            ExecutionState.FAILED,
+            ExecutionState.CANCELLED,
+        }
+        async for event in execution.subscribe():
+            if event["type"] == "state":
+                state = ExecutionState(event["state"])
+                # Send notifications/tasks/status when state changes
+                await _send_status_notification(
+                    session=session,
+                    task_id=task_id,
+                    task_key=task_key,
+                    docket=docket,
+                    state=state,
+                    poll_interval_ms=poll_interval_ms,
+                )
+                # Stop subscribing once the task reaches a terminal state
+                if state in terminal_states:
+                    break
+            elif event["type"] == "progress":
+                # Send notification when progress message changes
+                await _send_progress_notification(
+                    session=session,
+                    task_id=task_id,
+                    task_key=task_key,
+                    docket=docket,
+                    execution=execution,
+                    poll_interval_ms=poll_interval_ms,
+                )
+
+    except Exception as e:
+        logger.warning(f"Subscription task failed for {task_id}: {e}", exc_info=True)
+
+
+async def _send_status_notification(
+    session: ServerSession,
+    task_id: str,
+    task_key: str,
+    docket: Docket,
+    state: ExecutionState,
+    poll_interval_ms: int = 5000,
+) -> None:
+    """Send notifications/tasks/status to client.
+
+    Per SEP-1686 line 454: notification SHOULD NOT include related-task metadata
+    (taskId is already in params).
+
+    Args:
+        session: MCP ServerSession
+        task_id: Client-visible task ID
+        task_key: Internal task key (for metadata lookup)
+        docket: Docket instance
+        state: Docket execution state (enum)
+        poll_interval_ms: Poll interval in milliseconds
+    """
+    # Map Docket state to MCP status
+    state_map = DOCKET_TO_MCP_STATE
+    mcp_status = state_map.get(state, "failed")
+
+    # Extract task_scope from task_key for Redis lookup
+    key_parts = parse_task_key(task_key)
+    task_scope = key_parts["task_scope"]
+
+    created_at_key = docket.key(f"{task_redis_prefix(task_scope)}:{task_id}:created_at")
+    async with docket.redis() as redis:
+        created_at_bytes = await redis.get(created_at_key)
+
+    created_at = (
+        created_at_bytes.decode("utf-8")
+        if created_at_bytes
+        else datetime.now(timezone.utc).isoformat()
+    )
+
+    # Build status message
+    status_message = None
+    if state == ExecutionState.COMPLETED:
+        status_message = "Task completed successfully"
+    elif state == ExecutionState.FAILED:
+        status_message = "Task failed"
+    elif state == ExecutionState.CANCELLED:
+        status_message = "Task cancelled"
+
+    params_dict = {
+        "taskId": task_id,
+        "status": mcp_status,
+        "createdAt": created_at,
+        "lastUpdatedAt": datetime.now(timezone.utc).isoformat(),
+        "ttl": DEFAULT_TTL_MS,
+        "pollInterval": poll_interval_ms,
+    }
+
+    if status_message:
+        params_dict["statusMessage"] = status_message
+
+    # Create notification (no related-task metadata per spec line 454)
+    notification = TaskStatusNotification(
+        params=TaskStatusNotificationParams.model_validate(params_dict),
+    )
+
+    # Send notification (don't let failures break the subscription)
+    with suppress(Exception):
+        await session.send_notification(notification)  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+
+
+async def _send_progress_notification(
+    session: ServerSession,
+    task_id: str,
+    task_key: str,
+    docket: Docket,
+    execution: Execution,
+    poll_interval_ms: int = 5000,
+) -> None:
+    """Send notifications/tasks/status when progress updates.
+
+    Args:
+        session: MCP ServerSession
+        task_id: Client-visible task ID
+        task_key: Internal task key
+        docket: Docket instance
+        execution: Execution object with current progress
+        poll_interval_ms: Poll interval in milliseconds
+    """
+    # Sync execution to get latest progress
+    await execution.sync()
+
+    # Only send if there's a progress message
+    if not execution.progress or not execution.progress.message:
+        return
+
+    # Map Docket state to MCP status
+    state_map = DOCKET_TO_MCP_STATE
+    mcp_status = state_map.get(execution.state, "failed")
+
+    # Extract task_scope from task_key for Redis lookup
+    key_parts = parse_task_key(task_key)
+    task_scope = key_parts["task_scope"]
+
+    created_at_key = docket.key(f"{task_redis_prefix(task_scope)}:{task_id}:created_at")
+    async with docket.redis() as redis:
+        created_at_bytes = await redis.get(created_at_key)
+
+    created_at = (
+        created_at_bytes.decode("utf-8")
+        if created_at_bytes
+        else datetime.now(timezone.utc).isoformat()
+    )
+
+    params_dict = {
+        "taskId": task_id,
+        "status": mcp_status,
+        "createdAt": created_at,
+        "lastUpdatedAt": datetime.now(timezone.utc).isoformat(),
+        "ttl": DEFAULT_TTL_MS,
+        "pollInterval": poll_interval_ms,
+        "statusMessage": execution.progress.message,
+    }
+
+    # Create and send notification
+    notification = TaskStatusNotification(
+        params=TaskStatusNotificationParams.model_validate(params_dict),
+    )
+
+    with suppress(Exception):
+        await session.send_notification(notification)  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
diff --git a/fastmcp_slim/fastmcp/server/telemetry.py b/fastmcp_slim/fastmcp/server/telemetry.py
new file mode 100644
index 0000000..eeaa0ae
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/telemetry.py
@@ -0,0 +1,251 @@
+"""Server-side telemetry helpers."""
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+from opentelemetry.context import Context
+from opentelemetry.trace import Span, SpanKind, Status, StatusCode, get_current_span
+
+from fastmcp.exceptions import ToolError as _ToolError
+from fastmcp.telemetry import extract_trace_context, get_tracer
+
+# Marker attribute set on the SERVER span opened at the FastMCP middleware seam
+# (see `fastmcp.server.low_level.FastMCPServerMiddleware._seam_span`). The seam
+# opens one span per inbound request so failures rejected *before* the
+# high-level path (auth, not-found, middleware vetoes) are still traced. The
+# attribute is set for observability; enrichment detection uses the ContextVar
+# below (the API `Span` type does not expose readable attributes).
+SEAM_SPAN_MARKER = "fastmcp.span.seam"
+
+# Tracks the SERVER span opened at the current request's seam. When the
+# high-level path reaches `server_span` and this span is still the active span,
+# `server_span` enriches it with component attributes instead of opening a
+# second span — restoring attribute parity on the single per-request span.
+_active_seam_span: ContextVar[Span | None] = ContextVar(
+    "fastmcp_active_seam_span", default=None
+)
+
+
+def get_auth_span_attributes() -> dict[str, str]:
+    """Get auth attributes for the current request, if authenticated."""
+    from fastmcp.server.dependencies import get_access_token
+
+    attrs: dict[str, str] = {}
+    try:
+        token = get_access_token()
+        if token:
+            if token.client_id:
+                attrs["enduser.id"] = token.client_id
+            if token.scopes:
+                attrs["enduser.scope"] = " ".join(token.scopes)
+    except RuntimeError:
+        pass
+    return attrs
+
+
+def get_session_span_attributes() -> dict[str, str]:
+    """Get session attributes for the current request."""
+    from fastmcp.server.dependencies import get_context
+
+    attrs: dict[str, str] = {}
+    try:
+        ctx = get_context()
+        if ctx.request_context is not None and ctx.session_id is not None:
+            attrs["mcp.session.id"] = ctx.session_id
+    except RuntimeError:
+        pass
+    return attrs
+
+
+def _get_parent_trace_context() -> Context | None:
+    """Get parent trace context from request meta for distributed tracing."""
+    from fastmcp.server.dependencies import fastmcp_request_ctx
+
+    req_ctx = fastmcp_request_ctx.get()
+    if req_ctx is not None and req_ctx.meta:
+        return extract_trace_context(req_ctx.meta)
+    return None
+
+
+def _build_server_span_attrs(
+    method: str,
+    server_name: str,
+    component_type: str,
+    component_key: str,
+    resource_uri: str | None,
+    tool_name: str | None,
+    prompt_name: str | None,
+) -> dict[str, str]:
+    attrs: dict[str, str] = {
+        # MCP semantic conventions
+        "mcp.method.name": method,
+        # FastMCP-specific attributes
+        "fastmcp.server.name": server_name,
+        "fastmcp.component.type": component_type,
+        "fastmcp.component.key": component_key,
+        **get_auth_span_attributes(),
+        **get_session_span_attributes(),
+    }
+    if resource_uri is not None:
+        attrs["mcp.resource.uri"] = resource_uri
+    if tool_name is not None:
+        attrs["gen_ai.tool.name"] = tool_name
+    if prompt_name is not None:
+        attrs["gen_ai.prompt.name"] = prompt_name
+    return attrs
+
+
+def record_span_exception(span: Span, e: Exception) -> None:
+    """Record an exception and error status on a span."""
+    if span.is_recording():
+        error_type = "tool_error" if isinstance(e, _ToolError) else type(e).__qualname__
+        span.set_attribute("error.type", error_type)
+        span.record_exception(e)
+        span.set_status(Status(StatusCode.ERROR, str(e)))
+
+
+@contextmanager
+def seam_span(method: str, server_name: str) -> Generator[Span, None, None]:
+    """Open the per-request SERVER span at the FastMCP middleware seam.
+
+    The span is named after the method and carries the base MCP attributes
+    (`mcp.method.name`, `fastmcp.server.name`, auth/session context) so
+    seam-only methods (`logging/setLevel`, `tasks/*`, `ping`, `initialize`, ...)
+    are fully attributed even though they never reach the high-level path. It is
+    marked with `SEAM_SPAN_MARKER` so a later `server_span` call in the
+    high-level path enriches this span with component attributes instead of
+    opening a second one. Exceptions raised anywhere below the seam — including
+    rejections *before* the high-level path (auth, not-found, middleware vetoes)
+    that would otherwise produce no SERVER span at all — are recorded here.
+    """
+    tracer = get_tracer()
+    with tracer.start_as_current_span(
+        method,
+        context=_get_parent_trace_context(),
+        kind=SpanKind.SERVER,
+    ) as span:
+        if span.is_recording():
+            span.set_attribute(SEAM_SPAN_MARKER, True)
+            span.set_attributes(
+                {
+                    "mcp.method.name": method,
+                    "fastmcp.server.name": server_name,
+                    **get_auth_span_attributes(),
+                    **get_session_span_attributes(),
+                }
+            )
+        token = _active_seam_span.set(span)
+        try:
+            yield span
+        except Exception as e:
+            record_span_exception(span, e)
+            raise
+        finally:
+            _active_seam_span.reset(token)
+
+
+@contextmanager
+def server_span(
+    name: str,
+    method: str,
+    server_name: str,
+    component_type: str,
+    component_key: str,
+    resource_uri: str | None = None,
+    tool_name: str | None = None,
+    prompt_name: str | None = None,
+) -> Generator[Span, None, None]:
+    """Emit or enrich a SERVER span with standard MCP attributes and auth context.
+
+    When the current active span is the request's seam span (opened by
+    `FastMCPServerMiddleware` and marked with `SEAM_SPAN_MARKER`), this sets the
+    component attributes on that span and yields it *without* starting a second
+    span — so failures rejected before this point and the successful high-level
+    call share one richly-attributed SERVER span. Otherwise (non-seam contexts,
+    e.g. in-process `mcp.call_tool()` calls that bypass the dispatcher) it opens a
+    new SERVER span as before.
+
+    Automatically records any exception on the span and sets error status.
+    """
+    attrs = _build_server_span_attrs(
+        method,
+        server_name,
+        component_type,
+        component_key,
+        resource_uri,
+        tool_name,
+        prompt_name,
+    )
+
+    seam = _active_seam_span.get()
+    active = get_current_span()
+    if (
+        seam is not None
+        and seam is active
+        and seam.is_recording()
+        and seam.get_span_context().is_valid
+    ):
+        # Enrich the already-active seam span rather than opening a second one.
+        seam.update_name(name)
+        seam.set_attributes(attrs)
+        try:
+            yield seam
+        except Exception as e:
+            record_span_exception(seam, e)
+            raise
+        return
+
+    tracer = get_tracer()
+    with tracer.start_as_current_span(
+        name,
+        context=_get_parent_trace_context(),
+        kind=SpanKind.SERVER,
+    ) as span:
+        if span.is_recording():
+            span.set_attributes(attrs)
+        try:
+            yield span
+        except Exception as e:
+            record_span_exception(span, e)
+            raise
+
+
+@contextmanager
+def delegate_span(
+    name: str,
+    provider_type: str,
+    component_key: str,
+    method: str | None = None,
+) -> Generator[Span, None, None]:
+    """Create an INTERNAL span for provider delegation.
+
+    Used by FastMCPProvider when delegating to mounted servers.
+    Automatically records any exception on the span and sets error status.
+    """
+    tracer = get_tracer()
+    with tracer.start_as_current_span(f"delegate {name}") as span:
+        if span.is_recording():
+            attrs: dict[str, str] = {
+                "fastmcp.provider.type": provider_type,
+                "fastmcp.component.key": component_key,
+            }
+            if method is not None:
+                attrs["mcp.method.name"] = method
+            span.set_attributes(attrs)
+        try:
+            yield span
+        except Exception as e:
+            record_span_exception(span, e)
+            raise
+
+
+__all__ = [
+    "SEAM_SPAN_MARKER",
+    "delegate_span",
+    "get_auth_span_attributes",
+    "get_session_span_attributes",
+    "record_span_exception",
+    "seam_span",
+    "server_span",
+]
diff --git a/fastmcp_slim/fastmcp/server/transforms/__init__.py b/fastmcp_slim/fastmcp/server/transforms/__init__.py
new file mode 100644
index 0000000..411a2e0
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/transforms/__init__.py
@@ -0,0 +1,240 @@
+"""Transform system for component transformations.
+
+Transforms modify components (tools, resources, prompts). List operations use a pure
+function pattern where transforms receive sequences and return transformed sequences.
+Get operations use a middleware pattern with `call_next` to chain lookups.
+
+Unlike middleware (which operates on requests), transforms are observable by the
+system for task registration, tag filtering, and component introspection.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.transforms import Namespace
+
+    server = FastMCP("Server")
+    mount = server.mount(other_server)
+    mount.add_transform(Namespace("api"))  # Tools become api_toolname
+    ```
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Sequence
+from typing import TYPE_CHECKING, Protocol
+
+from fastmcp.utilities.versions import VersionSpec
+
+if TYPE_CHECKING:
+    from fastmcp.prompts.base import Prompt
+    from fastmcp.resources.base import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.tools.base import Tool
+
+
+# Get methods use Protocol to express keyword-only version parameter
+class GetToolNext(Protocol):
+    """Protocol for get_tool call_next functions."""
+
+    def __call__(
+        self, name: str, *, version: VersionSpec | None = None
+    ) -> Awaitable[Tool | None]: ...
+
+
+class GetResourceNext(Protocol):
+    """Protocol for get_resource call_next functions."""
+
+    def __call__(
+        self, uri: str, *, version: VersionSpec | None = None
+    ) -> Awaitable[Resource | None]: ...
+
+
+class GetResourceTemplateNext(Protocol):
+    """Protocol for get_resource_template call_next functions."""
+
+    def __call__(
+        self, uri: str, *, version: VersionSpec | None = None
+    ) -> Awaitable[ResourceTemplate | None]: ...
+
+
+class GetPromptNext(Protocol):
+    """Protocol for get_prompt call_next functions."""
+
+    def __call__(
+        self, name: str, *, version: VersionSpec | None = None
+    ) -> Awaitable[Prompt | None]: ...
+
+
+class Transform:
+    """Base class for component transformations.
+
+    List operations use a pure function pattern: transforms receive sequences
+    and return transformed sequences. Get operations use a middleware pattern
+    with `call_next` to chain lookups.
+
+    Example:
+        ```python
+        class MyTransform(Transform):
+            async def list_tools(self, tools):
+                return [transform(t) for t in tools]  # Transform sequence
+
+            async def get_tool(self, name, call_next, *, version=None):
+                original = self.reverse_name(name)  # Map to original name
+                tool = await call_next(original, version=version)  # Get from downstream
+                return transform(tool) if tool else None
+        ```
+    """
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}()"
+
+    # -------------------------------------------------------------------------
+    # Tools
+    # -------------------------------------------------------------------------
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        """List tools with transformation applied.
+
+        Args:
+            tools: Sequence of tools to transform.
+
+        Returns:
+            Transformed sequence of tools.
+        """
+        return tools
+
+    async def get_tool(
+        self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get a tool by name.
+
+        Args:
+            name: The requested tool name (may be transformed).
+            call_next: Callable to get tool from downstream.
+            version: Optional version filter to apply.
+
+        Returns:
+            The tool if found, None otherwise.
+        """
+        return await call_next(name, version=version)
+
+    # -------------------------------------------------------------------------
+    # Resources
+    # -------------------------------------------------------------------------
+
+    async def list_resources(self, resources: Sequence[Resource]) -> Sequence[Resource]:
+        """List resources with transformation applied.
+
+        Args:
+            resources: Sequence of resources to transform.
+
+        Returns:
+            Transformed sequence of resources.
+        """
+        return resources
+
+    async def get_resource(
+        self,
+        uri: str,
+        call_next: GetResourceNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> Resource | None:
+        """Get a resource by URI.
+
+        Args:
+            uri: The requested resource URI (may be transformed).
+            call_next: Callable to get resource from downstream.
+            version: Optional version filter to apply.
+
+        Returns:
+            The resource if found, None otherwise.
+        """
+        return await call_next(uri, version=version)
+
+    # -------------------------------------------------------------------------
+    # Resource Templates
+    # -------------------------------------------------------------------------
+
+    async def list_resource_templates(
+        self, templates: Sequence[ResourceTemplate]
+    ) -> Sequence[ResourceTemplate]:
+        """List resource templates with transformation applied.
+
+        Args:
+            templates: Sequence of resource templates to transform.
+
+        Returns:
+            Transformed sequence of resource templates.
+        """
+        return templates
+
+    async def get_resource_template(
+        self,
+        uri: str,
+        call_next: GetResourceTemplateNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> ResourceTemplate | None:
+        """Get a resource template by URI.
+
+        Args:
+            uri: The requested template URI (may be transformed).
+            call_next: Callable to get template from downstream.
+            version: Optional version filter to apply.
+
+        Returns:
+            The resource template if found, None otherwise.
+        """
+        return await call_next(uri, version=version)
+
+    # -------------------------------------------------------------------------
+    # Prompts
+    # -------------------------------------------------------------------------
+
+    async def list_prompts(self, prompts: Sequence[Prompt]) -> Sequence[Prompt]:
+        """List prompts with transformation applied.
+
+        Args:
+            prompts: Sequence of prompts to transform.
+
+        Returns:
+            Transformed sequence of prompts.
+        """
+        return prompts
+
+    async def get_prompt(
+        self, name: str, call_next: GetPromptNext, *, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        """Get a prompt by name.
+
+        Args:
+            name: The requested prompt name (may be transformed).
+            call_next: Callable to get prompt from downstream.
+            version: Optional version filter to apply.
+
+        Returns:
+            The prompt if found, None otherwise.
+        """
+        return await call_next(name, version=version)
+
+
+# Re-export built-in transforms (must be after Transform class to avoid circular imports)
+from fastmcp.server.transforms.visibility import Visibility, is_enabled  # noqa: E402
+from fastmcp.server.transforms.namespace import Namespace  # noqa: E402
+from fastmcp.server.transforms.prompts_as_tools import PromptsAsTools  # noqa: E402
+from fastmcp.server.transforms.resources_as_tools import ResourcesAsTools  # noqa: E402
+from fastmcp.server.transforms.tool_transform import ToolTransform  # noqa: E402
+from fastmcp.server.transforms.version_filter import VersionFilter  # noqa: E402
+
+__all__ = [
+    "Namespace",
+    "PromptsAsTools",
+    "ResourcesAsTools",
+    "ToolTransform",
+    "Transform",
+    "VersionFilter",
+    "VersionSpec",
+    "Visibility",
+    "is_enabled",
+]
diff --git a/fastmcp_slim/fastmcp/server/transforms/catalog.py b/fastmcp_slim/fastmcp/server/transforms/catalog.py
new file mode 100644
index 0000000..936fcd9
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/transforms/catalog.py
@@ -0,0 +1,245 @@
+"""Base class for transforms that need to read the real component catalog.
+
+Some transforms replace ``list_tools()`` output with synthetic components
+(e.g. a search interface) while still needing access to the *real*
+(auth-filtered) catalog at call time.  ``CatalogTransform`` provides the
+bypass machinery so subclasses can call ``get_tool_catalog()`` without
+triggering their own replacement logic.
+
+Re-entrancy problem
+-------------------
+
+When a synthetic tool handler calls ``get_tool_catalog()``, that calls
+``ctx.fastmcp.list_tools()`` which re-enters the transform pipeline —
+including *this* transform's ``list_tools()``.  If the subclass overrides
+``list_tools()`` directly, the re-entrant call would hit the subclass's
+replacement logic again (returning synthetic tools instead of the real
+catalog).  A ``super()`` call can't prevent this because Python can't
+short-circuit a method after ``super()`` returns.
+
+Solution: ``CatalogTransform`` owns ``list_tools()`` and uses a
+per-instance ``ContextVar`` to detect re-entrant calls.  During bypass,
+it passes through to the base ``Transform.list_tools()`` (a no-op).
+Otherwise, it delegates to ``transform_tools()`` — the subclass hook
+where replacement logic lives.  Same pattern for resources, prompts,
+and resource templates.
+
+This is *not* the same as the ``Provider._list_tools()`` convention
+(which produces raw components with no arguments).  ``transform_tools()``
+receives the current catalog and returns a transformed version.  The
+distinct name avoids confusion between the two patterns.
+
+Usage::
+
+    class MyTransform(CatalogTransform):
+        async def transform_tools(self, tools):
+            return [self._make_search_tool()]
+
+        def _make_search_tool(self):
+            async def search(ctx: Context = None):
+                real_tools = await self.get_tool_catalog(ctx)
+                ...
+            return Tool.from_function(fn=search, name="search")
+"""
+
+from __future__ import annotations
+
+import itertools
+from collections.abc import Sequence
+from contextvars import ContextVar
+from typing import TYPE_CHECKING
+
+from fastmcp.server.transforms import Transform
+from fastmcp.utilities.versions import dedupe_with_versions
+
+if TYPE_CHECKING:
+    from fastmcp.prompts.base import Prompt
+    from fastmcp.resources.base import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.server.context import Context
+    from fastmcp.tools.base import Tool
+
+_instance_counter = itertools.count()
+
+
+class CatalogTransform(Transform):
+    """Transform that needs access to the real component catalog.
+
+    Subclasses override ``transform_tools()`` / ``transform_resources()``
+    / ``transform_prompts()`` / ``transform_resource_templates()``
+    instead of the ``list_*()`` methods.  The base class owns
+    ``list_*()`` and handles re-entrant bypass automatically — subclasses
+    never see re-entrant calls from ``get_*_catalog()``.
+
+    The ``get_*_catalog()`` methods fetch the real (auth-filtered) catalog
+    by temporarily setting a bypass flag so that this transform's
+    ``list_*()`` passes through without calling the subclass hook.
+    """
+
+    def __init__(self) -> None:
+        self._instance_id: int = next(_instance_counter)
+        self._bypass: ContextVar[bool] = ContextVar(
+            f"_catalog_bypass_{self._instance_id}", default=False
+        )
+
+    # ------------------------------------------------------------------
+    # list_* (bypass-aware — subclasses override transform_* instead)
+    # ------------------------------------------------------------------
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        if self._bypass.get():
+            return await super().list_tools(tools)
+        return await self.transform_tools(tools)
+
+    async def list_resources(self, resources: Sequence[Resource]) -> Sequence[Resource]:
+        if self._bypass.get():
+            return await super().list_resources(resources)
+        return await self.transform_resources(resources)
+
+    async def list_resource_templates(
+        self, templates: Sequence[ResourceTemplate]
+    ) -> Sequence[ResourceTemplate]:
+        if self._bypass.get():
+            return await super().list_resource_templates(templates)
+        return await self.transform_resource_templates(templates)
+
+    async def list_prompts(self, prompts: Sequence[Prompt]) -> Sequence[Prompt]:
+        if self._bypass.get():
+            return await super().list_prompts(prompts)
+        return await self.transform_prompts(prompts)
+
+    # ------------------------------------------------------------------
+    # Subclass hooks (override these, not list_*)
+    # ------------------------------------------------------------------
+
+    async def transform_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        """Transform the tool catalog.
+
+        Override this method to replace, filter, or augment the tool listing.
+        The default implementation passes through unchanged.
+
+        Do NOT override ``list_tools()`` directly — the base class uses it
+        to handle re-entrant bypass when ``get_tool_catalog()`` reads the
+        real catalog.
+        """
+        return tools
+
+    async def transform_resources(
+        self, resources: Sequence[Resource]
+    ) -> Sequence[Resource]:
+        """Transform the resource catalog.
+
+        Override this method to replace, filter, or augment the resource listing.
+        The default implementation passes through unchanged.
+
+        Do NOT override ``list_resources()`` directly — the base class uses it
+        to handle re-entrant bypass when ``get_resource_catalog()`` reads the
+        real catalog.
+        """
+        return resources
+
+    async def transform_resource_templates(
+        self, templates: Sequence[ResourceTemplate]
+    ) -> Sequence[ResourceTemplate]:
+        """Transform the resource template catalog.
+
+        Override this method to replace, filter, or augment the template listing.
+        The default implementation passes through unchanged.
+
+        Do NOT override ``list_resource_templates()`` directly — the base class
+        uses it to handle re-entrant bypass when
+        ``get_resource_template_catalog()`` reads the real catalog.
+        """
+        return templates
+
+    async def transform_prompts(self, prompts: Sequence[Prompt]) -> Sequence[Prompt]:
+        """Transform the prompt catalog.
+
+        Override this method to replace, filter, or augment the prompt listing.
+        The default implementation passes through unchanged.
+
+        Do NOT override ``list_prompts()`` directly — the base class uses it
+        to handle re-entrant bypass when ``get_prompt_catalog()`` reads the
+        real catalog.
+        """
+        return prompts
+
+    # ------------------------------------------------------------------
+    # Catalog accessors
+    # ------------------------------------------------------------------
+
+    async def get_tool_catalog(
+        self, ctx: Context, *, run_middleware: bool = True
+    ) -> Sequence[Tool]:
+        """Fetch the real tool catalog, bypassing this transform.
+
+        The result is deduplicated by name so that only the highest version
+        of each tool is returned — matching what protocol handlers expose
+        on the wire.
+
+        Args:
+            ctx: The current request context.
+            run_middleware: Whether to run middleware on the inner call.
+                Defaults to True because this is typically called from a
+                tool handler where list_tools middleware has not yet run.
+        """
+        token = self._bypass.set(True)
+        try:
+            tools = await ctx.fastmcp.list_tools(run_middleware=run_middleware)
+        finally:
+            self._bypass.reset(token)
+        return dedupe_with_versions(tools, lambda t: t.name)
+
+    async def get_resource_catalog(
+        self, ctx: Context, *, run_middleware: bool = True
+    ) -> Sequence[Resource]:
+        """Fetch the real resource catalog, bypassing this transform.
+
+        Args:
+            ctx: The current request context.
+            run_middleware: Whether to run middleware on the inner call.
+                Defaults to True because this is typically called from a
+                tool handler where list_resources middleware has not yet run.
+        """
+        token = self._bypass.set(True)
+        try:
+            return await ctx.fastmcp.list_resources(run_middleware=run_middleware)
+        finally:
+            self._bypass.reset(token)
+
+    async def get_prompt_catalog(
+        self, ctx: Context, *, run_middleware: bool = True
+    ) -> Sequence[Prompt]:
+        """Fetch the real prompt catalog, bypassing this transform.
+
+        Args:
+            ctx: The current request context.
+            run_middleware: Whether to run middleware on the inner call.
+                Defaults to True because this is typically called from a
+                tool handler where list_prompts middleware has not yet run.
+        """
+        token = self._bypass.set(True)
+        try:
+            return await ctx.fastmcp.list_prompts(run_middleware=run_middleware)
+        finally:
+            self._bypass.reset(token)
+
+    async def get_resource_template_catalog(
+        self, ctx: Context, *, run_middleware: bool = True
+    ) -> Sequence[ResourceTemplate]:
+        """Fetch the real resource template catalog, bypassing this transform.
+
+        Args:
+            ctx: The current request context.
+            run_middleware: Whether to run middleware on the inner call.
+                Defaults to True because this is typically called from a
+                tool handler where list_resource_templates middleware has
+                not yet run.
+        """
+        token = self._bypass.set(True)
+        try:
+            return await ctx.fastmcp.list_resource_templates(
+                run_middleware=run_middleware
+            )
+        finally:
+            self._bypass.reset(token)
diff --git a/fastmcp_slim/fastmcp/server/transforms/namespace.py b/fastmcp_slim/fastmcp/server/transforms/namespace.py
new file mode 100644
index 0000000..f1a219a
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/transforms/namespace.py
@@ -0,0 +1,193 @@
+"""Namespace transform for prefixing component names."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from fastmcp.server.transforms import (
+    GetPromptNext,
+    GetResourceNext,
+    GetResourceTemplateNext,
+    GetToolNext,
+    Transform,
+)
+from fastmcp.utilities.versions import VersionSpec
+
+if TYPE_CHECKING:
+    from fastmcp.prompts.base import Prompt
+    from fastmcp.resources.base import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.tools.base import Tool
+
+# Pattern for matching URIs: protocol://path
+_URI_PATTERN = re.compile(r"^([^:]+://)(.*?)$")
+
+
+class Namespace(Transform):
+    """Prefixes component names with a namespace.
+
+    - Tools: name → namespace_name
+    - Prompts: name → namespace_name
+    - Resources: protocol://path → protocol://namespace/path
+    - Resource Templates: same as resources
+
+    Example:
+        ```python
+        transform = Namespace("math")
+        # Tool "add" becomes "math_add"
+        # Resource "file://data.txt" becomes "file://math/data.txt"
+        ```
+    """
+
+    def __init__(self, prefix: str) -> None:
+        """Initialize Namespace transform.
+
+        Args:
+            prefix: The namespace prefix to apply.
+        """
+        self._prefix = prefix
+        self._name_prefix = f"{prefix}_"
+
+    def __repr__(self) -> str:
+        return f"Namespace({self._prefix!r})"
+
+    # -------------------------------------------------------------------------
+    # Name transformation helpers
+    # -------------------------------------------------------------------------
+
+    def _transform_name(self, name: str) -> str:
+        """Apply namespace prefix to a name."""
+        return f"{self._name_prefix}{name}"
+
+    def _reverse_name(self, name: str) -> str | None:
+        """Remove namespace prefix from a name, or None if no match."""
+        if name.startswith(self._name_prefix):
+            return name[len(self._name_prefix) :]
+        return None
+
+    # -------------------------------------------------------------------------
+    # URI transformation helpers
+    # -------------------------------------------------------------------------
+
+    def _transform_uri(self, uri: str) -> str:
+        """Apply namespace to a URI: protocol://path → protocol://namespace/path."""
+        match = _URI_PATTERN.match(uri)
+        if match:
+            protocol, path = match.groups()
+            return f"{protocol}{self._prefix}/{path}"
+        return uri
+
+    def _reverse_uri(self, uri: str) -> str | None:
+        """Remove namespace from a URI, or None if no match."""
+        match = _URI_PATTERN.match(uri)
+        if match:
+            protocol, path = match.groups()
+            prefix = f"{self._prefix}/"
+            if path.startswith(prefix):
+                return f"{protocol}{path[len(prefix) :]}"
+            return None
+        return None
+
+    # -------------------------------------------------------------------------
+    # Tools
+    # -------------------------------------------------------------------------
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        """Prefix tool names with namespace."""
+        return [
+            t.model_copy(update={"name": self._transform_name(t.name)}) for t in tools
+        ]
+
+    async def get_tool(
+        self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get tool by namespaced name."""
+        original = self._reverse_name(name)
+        if original is None:
+            return None
+        tool = await call_next(original, version=version)
+        if tool:
+            return tool.model_copy(update={"name": name})
+        return None
+
+    # -------------------------------------------------------------------------
+    # Resources
+    # -------------------------------------------------------------------------
+
+    async def list_resources(self, resources: Sequence[Resource]) -> Sequence[Resource]:
+        """Add namespace path segment to resource URIs."""
+        return [
+            r.model_copy(update={"uri": self._transform_uri(str(r.uri))})
+            for r in resources
+        ]
+
+    async def get_resource(
+        self,
+        uri: str,
+        call_next: GetResourceNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> Resource | None:
+        """Get resource by namespaced URI."""
+        original = self._reverse_uri(uri)
+        if original is None:
+            return None
+        resource = await call_next(original, version=version)
+        if resource:
+            return resource.model_copy(update={"uri": uri})
+        return None
+
+    # -------------------------------------------------------------------------
+    # Resource Templates
+    # -------------------------------------------------------------------------
+
+    async def list_resource_templates(
+        self, templates: Sequence[ResourceTemplate]
+    ) -> Sequence[ResourceTemplate]:
+        """Add namespace path segment to template URIs."""
+        return [
+            t.model_copy(update={"uri_template": self._transform_uri(t.uri_template)})
+            for t in templates
+        ]
+
+    async def get_resource_template(
+        self,
+        uri: str,
+        call_next: GetResourceTemplateNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> ResourceTemplate | None:
+        """Get resource template by namespaced URI."""
+        original = self._reverse_uri(uri)
+        if original is None:
+            return None
+        template = await call_next(original, version=version)
+        if template:
+            return template.model_copy(
+                update={"uri_template": self._transform_uri(template.uri_template)}
+            )
+        return None
+
+    # -------------------------------------------------------------------------
+    # Prompts
+    # -------------------------------------------------------------------------
+
+    async def list_prompts(self, prompts: Sequence[Prompt]) -> Sequence[Prompt]:
+        """Prefix prompt names with namespace."""
+        return [
+            p.model_copy(update={"name": self._transform_name(p.name)}) for p in prompts
+        ]
+
+    async def get_prompt(
+        self, name: str, call_next: GetPromptNext, *, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        """Get prompt by namespaced name."""
+        original = self._reverse_name(name)
+        if original is None:
+            return None
+        prompt = await call_next(original, version=version)
+        if prompt:
+            return prompt.model_copy(update={"name": name})
+        return None
diff --git a/fastmcp_slim/fastmcp/server/transforms/prompts_as_tools.py b/fastmcp_slim/fastmcp/server/transforms/prompts_as_tools.py
new file mode 100644
index 0000000..81c421b
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/transforms/prompts_as_tools.py
@@ -0,0 +1,171 @@
+"""Transform that exposes prompts as tools.
+
+This transform generates tools for listing and getting prompts, enabling
+clients that only support tools to access prompt functionality.
+
+The generated tools route through `ctx.fastmcp` at runtime, so all server
+middleware (auth, visibility, rate limiting, etc.) applies to prompt
+operations exactly as it would for direct `prompts/get` calls.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.transforms import PromptsAsTools
+
+    mcp = FastMCP("Server")
+    mcp.add_transform(PromptsAsTools(mcp))
+    # Now has list_prompts and get_prompt tools
+    ```
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Annotated, Any
+
+from mcp_types import TextContent
+
+from fastmcp.server.dependencies import get_context
+from fastmcp.server.transforms import GetToolNext, Transform
+from fastmcp.tools.base import Tool
+from fastmcp.utilities.versions import VersionSpec
+
+if TYPE_CHECKING:
+    from fastmcp.server.providers.base import Provider
+
+
+class PromptsAsTools(Transform):
+    """Transform that adds tools for listing and getting prompts.
+
+    Generates two tools:
+    - `list_prompts`: Lists all prompts
+    - `get_prompt`: Gets a specific prompt with optional arguments
+
+    The generated tools route through the server at runtime, so auth,
+    middleware, and visibility apply automatically.
+
+    This transform should be applied to a FastMCP server instance, not
+    a raw Provider, because the generated tools need the server's
+    middleware chain for auth and visibility filtering.
+
+    Example:
+        ```python
+        mcp = FastMCP("Server")
+        mcp.add_transform(PromptsAsTools(mcp))
+        # Now has list_prompts and get_prompt tools
+        ```
+    """
+
+    def __init__(self, provider: Provider) -> None:
+        from fastmcp.server.server import FastMCP
+
+        if not isinstance(provider, FastMCP):
+            raise TypeError(
+                "PromptsAsTools requires a FastMCP server instance, not a"
+                f" {type(provider).__name__}. The generated tools route through"
+                " the server's middleware chain at runtime for auth and"
+                " visibility. Pass your FastMCP server: PromptsAsTools(mcp)"
+            )
+        self._provider = provider
+
+    def __repr__(self) -> str:
+        return f"PromptsAsTools({self._provider!r})"
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        """Add prompt tools to the tool list."""
+        return [
+            *tools,
+            self._make_list_prompts_tool(),
+            self._make_get_prompt_tool(),
+        ]
+
+    async def get_tool(
+        self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get a tool by name, including generated prompt tools."""
+        if name == "list_prompts":
+            return self._make_list_prompts_tool()
+        if name == "get_prompt":
+            return self._make_get_prompt_tool()
+        return await call_next(name, version=version)
+
+    def _make_list_prompts_tool(self) -> Tool:
+        """Create the list_prompts tool."""
+
+        async def list_prompts() -> str:
+            """List all available prompts.
+
+            Returns JSON with prompt metadata including name, description,
+            and optional arguments.
+            """
+            ctx = get_context()
+            prompts = await ctx.fastmcp.list_prompts()
+
+            result: list[dict[str, Any]] = []
+            for p in prompts:
+                result.append(  # noqa: PERF401
+                    {
+                        "name": p.name,
+                        "description": p.description,
+                        "arguments": [
+                            {
+                                "name": arg.name,
+                                "description": arg.description,
+                                "required": arg.required,
+                            }
+                            for arg in (p.arguments or [])
+                        ],
+                    }
+                )
+
+            return json.dumps(result, indent=2)
+
+        return Tool.from_function(fn=list_prompts)
+
+    def _make_get_prompt_tool(self) -> Tool:
+        """Create the get_prompt tool."""
+
+        async def get_prompt(
+            name: Annotated[str, "The name of the prompt to get"],
+            arguments: Annotated[
+                dict[str, Any] | None,
+                "Optional arguments for the prompt",
+            ] = None,
+        ) -> str:
+            """Get a prompt by name with optional arguments.
+
+            Returns the rendered prompt as JSON with a messages array.
+            Arguments should be provided as a dict mapping argument names
+            to values.
+            """
+            ctx = get_context()
+            result = await ctx.fastmcp.render_prompt(name, arguments=arguments or {})
+            return _format_prompt_result(result)
+
+        return Tool.from_function(fn=get_prompt)
+
+
+def _format_prompt_result(result: Any) -> str:
+    """Format PromptResult for tool output.
+
+    Returns JSON with the messages array. Preserves embedded resources
+    as structured JSON objects.
+    """
+    messages = []
+    for msg in result.messages:
+        if isinstance(msg.content, TextContent):
+            content = msg.content.text
+        else:
+            content = msg.content.model_dump(
+                mode="json", by_alias=True, exclude_none=True
+            )
+
+        messages.append(
+            {
+                "role": msg.role,
+                "content": content,
+            }
+        )
+
+    return json.dumps({"messages": messages}, indent=2)
diff --git a/fastmcp_slim/fastmcp/server/transforms/resources_as_tools.py b/fastmcp_slim/fastmcp/server/transforms/resources_as_tools.py
new file mode 100644
index 0000000..9861fc6
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/transforms/resources_as_tools.py
@@ -0,0 +1,180 @@
+"""Transform that exposes resources as tools.
+
+This transform generates tools for listing and reading resources, enabling
+clients that only support tools to access resource functionality.
+
+The generated tools route through `ctx.fastmcp` at runtime, so all server
+middleware (auth, visibility, rate limiting, etc.) applies to resource
+operations exactly as it would for direct `resources/read` calls.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.transforms import ResourcesAsTools
+
+    mcp = FastMCP("Server")
+    mcp.add_transform(ResourcesAsTools(mcp))
+    # Now has list_resources and read_resource tools
+    ```
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Annotated, Any
+
+from mcp_types import ToolAnnotations
+
+from fastmcp.server.dependencies import get_context
+from fastmcp.server.transforms import GetToolNext, Transform
+from fastmcp.tools.base import Tool
+from fastmcp.utilities.versions import VersionSpec
+
+_DEFAULT_ANNOTATIONS = ToolAnnotations(read_only_hint=True)
+
+if TYPE_CHECKING:
+    from fastmcp.server.providers.base import Provider
+
+
+class ResourcesAsTools(Transform):
+    """Transform that adds tools for listing and reading resources.
+
+    Generates two tools:
+    - `list_resources`: Lists all resources and templates
+    - `read_resource`: Reads a resource by URI
+
+    The generated tools route through the server at runtime, so auth,
+    middleware, and visibility apply automatically.
+
+    This transform should be applied to a FastMCP server instance, not
+    a raw Provider, because the generated tools need the server's
+    middleware chain for auth and visibility filtering.
+
+    Example:
+        ```python
+        mcp = FastMCP("Server")
+        mcp.add_transform(ResourcesAsTools(mcp))
+        # Now has list_resources and read_resource tools
+        ```
+    """
+
+    def __init__(self, provider: Provider) -> None:
+        from fastmcp.server.server import FastMCP
+
+        if not isinstance(provider, FastMCP):
+            raise TypeError(
+                "ResourcesAsTools requires a FastMCP server instance, not a"
+                f" {type(provider).__name__}. The generated tools route through"
+                " the server's middleware chain at runtime for auth and"
+                " visibility. Pass your FastMCP server: ResourcesAsTools(mcp)"
+            )
+        self._provider = provider
+
+    def __repr__(self) -> str:
+        return f"ResourcesAsTools({self._provider!r})"
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        """Add resource tools to the tool list."""
+        return [
+            *tools,
+            self._make_list_resources_tool(),
+            self._make_read_resource_tool(),
+        ]
+
+    async def get_tool(
+        self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get a tool by name, including generated resource tools."""
+        if name == "list_resources":
+            return self._make_list_resources_tool()
+        if name == "read_resource":
+            return self._make_read_resource_tool()
+        return await call_next(name, version=version)
+
+    def _make_list_resources_tool(self) -> Tool:
+        """Create the list_resources tool."""
+
+        async def list_resources() -> str:
+            """List all available resources and resource templates.
+
+            Returns JSON with resource metadata. Static resources have a
+            'uri' field, while templates have a 'uri_template' field with
+            placeholders like {name}.
+            """
+            ctx = get_context()
+            resources = await ctx.fastmcp.list_resources()
+            templates = await ctx.fastmcp.list_resource_templates()
+
+            result: list[dict[str, Any]] = []
+
+            for r in resources:
+                result.append(  # noqa: PERF401
+                    {
+                        "uri": str(r.uri),
+                        "name": r.name,
+                        "description": r.description,
+                        "mime_type": r.mime_type,
+                    }
+                )
+
+            for t in templates:
+                result.append(  # noqa: PERF401
+                    {
+                        "uri_template": t.uri_template,
+                        "name": t.name,
+                        "description": t.description,
+                    }
+                )
+
+            return json.dumps(result, indent=2)
+
+        return Tool.from_function(fn=list_resources, annotations=_DEFAULT_ANNOTATIONS)
+
+    def _make_read_resource_tool(self) -> Tool:
+        """Create the read_resource tool."""
+
+        async def read_resource(
+            uri: Annotated[str, "The URI of the resource to read"],
+        ) -> str:
+            """Read a resource by its URI.
+
+            For static resources, provide the exact URI. For templated
+            resources, provide the URI with template parameters filled in.
+
+            Returns the resource content as a string. Binary content is
+            base64-encoded.
+            """
+            ctx = get_context()
+            result = await ctx.fastmcp.read_resource(uri)
+            return _format_result(result)
+
+        return Tool.from_function(fn=read_resource, annotations=_DEFAULT_ANNOTATIONS)
+
+
+def _format_result(result: Any) -> str:
+    """Format ResourceResult for tool output.
+
+    Single text content is returned as-is. Single binary content is
+    base64-encoded. Multiple contents are JSON-encoded.
+    """
+    if len(result.contents) == 1:
+        content = result.contents[0].content
+        if isinstance(content, bytes):
+            return base64.b64encode(content).decode()
+        return content
+
+    return json.dumps(
+        [
+            {
+                "content": (
+                    c.content
+                    if isinstance(c.content, str)
+                    else base64.b64encode(c.content).decode()
+                ),
+                "mime_type": c.mime_type,
+            }
+            for c in result.contents
+        ]
+    )
diff --git a/fastmcp_slim/fastmcp/server/transforms/search/__init__.py b/fastmcp_slim/fastmcp/server/transforms/search/__init__.py
new file mode 100644
index 0000000..756244f
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/transforms/search/__init__.py
@@ -0,0 +1,31 @@
+"""Search transforms for tool discovery.
+
+Search transforms collapse a large tool catalog into a search interface,
+letting LLMs discover tools on demand instead of seeing the full list.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.transforms.search import RegexSearchTransform
+
+    mcp = FastMCP("Server")
+    mcp.add_transform(RegexSearchTransform())
+    # list_tools now returns only search_tools + call_tool
+    ```
+"""
+
+from fastmcp.server.transforms.search.base import (
+    SearchResultSerializer,
+    serialize_tools_for_output_json,
+    serialize_tools_for_output_markdown,
+)
+from fastmcp.server.transforms.search.bm25 import BM25SearchTransform
+from fastmcp.server.transforms.search.regex import RegexSearchTransform
+
+__all__ = [
+    "BM25SearchTransform",
+    "RegexSearchTransform",
+    "SearchResultSerializer",
+    "serialize_tools_for_output_json",
+    "serialize_tools_for_output_markdown",
+]
diff --git a/fastmcp_slim/fastmcp/server/transforms/search/base.py b/fastmcp_slim/fastmcp/server/transforms/search/base.py
new file mode 100644
index 0000000..cfeac69
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/transforms/search/base.py
@@ -0,0 +1,270 @@
+"""Base class for search transforms.
+
+Search transforms replace ``list_tools()`` output with a small set of
+synthetic tools — a search tool and a call-tool proxy — so LLMs can
+discover tools on demand instead of receiving the full catalog.
+
+All concrete search transforms (``RegexSearchTransform``,
+``BM25SearchTransform``, etc.) inherit from ``BaseSearchTransform`` and
+implement ``_make_search_tool()`` and ``_search()`` to provide their
+specific search strategy.
+
+Example::
+
+    from fastmcp import FastMCP
+    from fastmcp.server.transforms.search import RegexSearchTransform
+
+    mcp = FastMCP("Server")
+
+    @mcp.tool
+    def add(a: int, b: int) -> int: ...
+
+    @mcp.tool
+    def multiply(x: float, y: float) -> float: ...
+
+    # Clients now see only ``search_tools`` and ``call_tool``.
+    # The original tools are discoverable via search.
+    mcp.add_transform(RegexSearchTransform())
+"""
+
+from abc import abstractmethod
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Annotated, Any
+
+from fastmcp.server.context import Context
+from fastmcp.server.transforms import GetToolNext
+from fastmcp.server.transforms.catalog import CatalogTransform
+from fastmcp.tools.base import Tool, ToolResult
+from fastmcp.utilities.versions import VersionSpec
+
+
+def _extract_searchable_text(tool: Tool) -> str:
+    """Combine tool name, description, and parameter info into searchable text."""
+    parts = [tool.name]
+    if tool.description:
+        parts.append(tool.description)
+
+    schema = tool.parameters
+    if schema:
+        properties = schema.get("properties", {})
+        for param_name, param_info in properties.items():
+            parts.append(param_name)
+            if isinstance(param_info, dict):
+                desc = param_info.get("description", "")
+                if desc:
+                    parts.append(desc)
+
+    return " ".join(parts)
+
+
+def serialize_tools_for_output_json(tools: Sequence[Tool]) -> list[dict[str, Any]]:
+    """Serialize tools to the same dict format as ``list_tools`` output."""
+    return [
+        tool.to_mcp_tool().model_dump(mode="json", by_alias=True, exclude_none=True)
+        for tool in tools
+    ]
+
+
+SearchResultSerializer = Callable[[Sequence[Tool]], Any | Awaitable[Any]]
+
+
+async def _invoke_serializer(
+    serializer: SearchResultSerializer, tools: Sequence[Tool]
+) -> Any:
+    """Call a serializer and await the result if it returns a coroutine."""
+    result = serializer(tools)
+    if isinstance(result, Awaitable):
+        return await result
+    return result
+
+
+def _union_type(branches: list[Any]) -> str:
+    branch_types = list(dict.fromkeys(_schema_type(b) for b in branches))
+    if "null" not in branch_types:
+        return " | ".join(branch_types) if branch_types else "any"
+    non_null = [b for b in branch_types if b != "null"]
+    if not non_null:
+        return "null"
+    return f"{' | '.join(non_null)}?"
+
+
+def _schema_type(schema: Any) -> str:
+    # Intentionally heuristic: the goal is a concise readable label, not a
+    # complete type system. Malformed schemas (e.g. {"type": ""}) → "any".
+    if not isinstance(schema, dict):
+        return "any"
+    t = schema.get("type")
+    if isinstance(t, str) and t:
+        if t == "array":
+            return f"{_schema_type(schema.get('items'))}[]"
+        if t == "null":
+            return "null"
+        return t
+    if "$ref" in schema:
+        return "object"
+    if "anyOf" in schema:
+        return _union_type(schema["anyOf"])
+    if "oneOf" in schema:
+        return _union_type(schema["oneOf"])
+    if "allOf" in schema:
+        # allOf = intersection / Pydantic composed model → always an object
+        return "object"
+    return "object" if "properties" in schema else "any"
+
+
+def _schema_section(schema: dict[str, Any] | None, title: str) -> list[str]:
+    lines = [f"**{title}**"]
+    if not isinstance(schema, dict):
+        lines.append("- `value` (any)")
+        return lines
+
+    props = schema.get("properties")
+    raw_required = schema.get("required")
+    req = set(raw_required) if isinstance(raw_required, list) else set()
+    if props is None:
+        # Not a properties-based schema — treat as a single unnamed value.
+        lines.append(f"- `value` ({_schema_type(schema)})")
+        return lines
+    if not props:
+        # Object schema with no properties — zero-argument tool.
+        lines.append("*(no parameters)*")
+        return lines
+
+    for name, field in props.items():
+        required = ", required" if name in req else ""
+        lines.append(f"- `{name}` ({_schema_type(field)}{required})")
+    return lines
+
+
+def serialize_tools_for_output_markdown(tools: Sequence[Tool]) -> str:
+    """Serialize tools to compact markdown, using ~65-70% fewer tokens than JSON."""
+    if not tools:
+        return "No tools matched the query."
+    blocks: list[str] = []
+    for tool in tools:
+        lines = [f"### {tool.name}"]
+        if tool.description:
+            lines.extend(["", tool.description.strip()])
+        lines.extend(["", *_schema_section(tool.parameters, "Parameters")])
+        if tool.output_schema is not None:
+            lines.extend(["", *_schema_section(tool.output_schema, "Returns")])
+        blocks.append("\n".join(lines))
+    return "\n\n".join(blocks)
+
+
+class BaseSearchTransform(CatalogTransform):
+    """Replace the tool listing with a search interface.
+
+    When this transform is active, ``list_tools()`` returns only:
+
+    * Any tools listed in ``always_visible`` (pinned).
+    * A **search tool** that finds tools matching a query.
+    * A **call_tool** proxy that executes tools discovered via search.
+
+    Hidden tools remain callable — ``get_tool()`` delegates unknown
+    names downstream, so direct calls and the call-tool proxy both work.
+
+    Search results respect the full auth pipeline: middleware, visibility
+    transforms, and component-level auth checks all apply.
+
+    Args:
+        max_results: Maximum number of tools returned per search.
+        always_visible: Tool names that stay in the ``list_tools``
+            output alongside the synthetic search/call tools.
+        search_tool_name: Name of the generated search tool.
+        call_tool_name: Name of the generated call-tool proxy.
+    """
+
+    def __init__(
+        self,
+        *,
+        max_results: int = 5,
+        always_visible: list[str] | None = None,
+        search_tool_name: str = "search_tools",
+        call_tool_name: str = "call_tool",
+        search_result_serializer: SearchResultSerializer | None = None,
+    ) -> None:
+        super().__init__()
+        self._max_results = max_results
+        self._always_visible = set(always_visible or [])
+        self._search_tool_name = search_tool_name
+        self._call_tool_name = call_tool_name
+        self._search_result_serializer: SearchResultSerializer = (
+            search_result_serializer or serialize_tools_for_output_json
+        )
+
+    # ------------------------------------------------------------------
+    # Transform interface
+    # ------------------------------------------------------------------
+
+    async def transform_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        """Replace the catalog with pinned + synthetic search/call tools."""
+        pinned = [t for t in tools if t.name in self._always_visible]
+        return [*pinned, self._make_search_tool(), self._make_call_tool()]
+
+    async def get_tool(
+        self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Intercept synthetic tool names; delegate everything else."""
+        if name == self._search_tool_name:
+            return self._make_search_tool()
+        if name == self._call_tool_name:
+            return self._make_call_tool()
+        return await call_next(name, version=version)
+
+    # ------------------------------------------------------------------
+    # Synthetic tools
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    def _make_search_tool(self) -> Tool:
+        """Create the search tool. Subclasses define the parameter schema."""
+        ...
+
+    def _make_call_tool(self) -> Tool:
+        """Create the call_tool proxy that executes discovered tools."""
+        transform = self
+
+        async def call_tool(
+            name: Annotated[str, "The name of the tool to call"],
+            arguments: Annotated[
+                dict[str, Any] | None, "Arguments to pass to the tool"
+            ] = None,
+            ctx: Context = None,  # type: ignore[assignment]  # ty:ignore[invalid-parameter-default]
+        ) -> ToolResult:
+            """Call a tool by name with the given arguments.
+
+            Use this to execute tools discovered via search_tools.
+            """
+            if name in {transform._call_tool_name, transform._search_tool_name}:
+                raise ValueError(
+                    f"'{name}' is a synthetic search tool and cannot be called via the call_tool proxy"
+                )
+            return await ctx.fastmcp.call_tool(name, arguments)
+
+        return Tool.from_function(fn=call_tool, name=self._call_tool_name)
+
+    # ------------------------------------------------------------------
+    # Serialization
+    # ------------------------------------------------------------------
+
+    async def _render_results(self, tools: Sequence[Tool]) -> Any:
+        return await _invoke_serializer(self._search_result_serializer, tools)
+
+    # ------------------------------------------------------------------
+    # Catalog access
+    # ------------------------------------------------------------------
+
+    async def _get_visible_tools(self, ctx: Context) -> Sequence[Tool]:
+        """Get the auth-filtered tool catalog, excluding pinned tools."""
+        tools = await self.get_tool_catalog(ctx)
+        return [t for t in tools if t.name not in self._always_visible]
+
+    # ------------------------------------------------------------------
+    # Abstract search
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def _search(self, tools: Sequence[Tool], query: str) -> Sequence[Tool]:
+        """Search the given tools and return matches."""
+        ...
diff --git a/fastmcp_slim/fastmcp/server/transforms/search/bm25.py b/fastmcp_slim/fastmcp/server/transforms/search/bm25.py
new file mode 100644
index 0000000..447db8c
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/transforms/search/bm25.py
@@ -0,0 +1,144 @@
+"""BM25-based search transform."""
+
+import hashlib
+import math
+import re
+from collections.abc import Sequence
+from typing import Annotated, Any
+
+from fastmcp.server.context import Context
+from fastmcp.server.transforms.search.base import (
+    BaseSearchTransform,
+    SearchResultSerializer,
+    _extract_searchable_text,
+)
+from fastmcp.tools.base import Tool
+
+
+def _tokenize(text: str) -> list[str]:
+    """Lowercase, split on non-alphanumeric, filter short tokens."""
+    return [t for t in re.split(r"[^a-z0-9]+", text.lower()) if len(t) > 1]
+
+
+class _BM25Index:
+    """Self-contained BM25 Okapi index."""
+
+    def __init__(self, k1: float = 1.5, b: float = 0.75) -> None:
+        self.k1 = k1
+        self.b = b
+        self._doc_tokens: list[list[str]] = []
+        self._doc_lengths: list[int] = []
+        self._avg_dl: float = 0.0
+        self._df: dict[str, int] = {}
+        self._tf: list[dict[str, int]] = []
+        self._n: int = 0
+
+    def build(self, documents: list[str]) -> None:
+        self._doc_tokens = [_tokenize(doc) for doc in documents]
+        self._doc_lengths = [len(tokens) for tokens in self._doc_tokens]
+        self._n = len(documents)
+        self._avg_dl = sum(self._doc_lengths) / self._n if self._n else 0.0
+
+        self._df = {}
+        self._tf = []
+        for tokens in self._doc_tokens:
+            tf: dict[str, int] = {}
+            seen: set[str] = set()
+            for token in tokens:
+                tf[token] = tf.get(token, 0) + 1
+                if token not in seen:
+                    self._df[token] = self._df.get(token, 0) + 1
+                    seen.add(token)
+            self._tf.append(tf)
+
+    def query(self, text: str, top_k: int) -> list[int]:
+        """Return indices of top_k documents sorted by BM25 score."""
+        query_tokens = _tokenize(text)
+        if not query_tokens or not self._n:
+            return []
+
+        scores: list[float] = [0.0] * self._n
+        for token in query_tokens:
+            if token not in self._df:
+                continue
+            idf = math.log(
+                (self._n - self._df[token] + 0.5) / (self._df[token] + 0.5) + 1.0
+            )
+            for i in range(self._n):
+                tf = self._tf[i].get(token, 0)
+                if tf == 0:
+                    continue
+                dl = self._doc_lengths[i]
+                numerator = tf * (self.k1 + 1)
+                denominator = tf + self.k1 * (1 - self.b + self.b * dl / self._avg_dl)
+                scores[i] += idf * numerator / denominator
+
+        ranked = sorted(range(self._n), key=lambda i: scores[i], reverse=True)
+        return [i for i in ranked[:top_k] if scores[i] > 0]
+
+
+def _catalog_hash(tools: Sequence[Tool]) -> str:
+    """SHA256 hash of sorted tool searchable text for staleness detection."""
+    key = "|".join(sorted(_extract_searchable_text(t) for t in tools))
+    return hashlib.sha256(key.encode()).hexdigest()
+
+
+class BM25SearchTransform(BaseSearchTransform):
+    """Search transform using BM25 Okapi relevance ranking.
+
+    Maintains an in-memory index that is lazily rebuilt when the tool
+    catalog changes (detected via a hash of tool names).
+    """
+
+    def __init__(
+        self,
+        *,
+        max_results: int = 5,
+        always_visible: list[str] | None = None,
+        search_tool_name: str = "search_tools",
+        call_tool_name: str = "call_tool",
+        search_result_serializer: SearchResultSerializer | None = None,
+    ) -> None:
+        super().__init__(
+            max_results=max_results,
+            always_visible=always_visible,
+            search_tool_name=search_tool_name,
+            call_tool_name=call_tool_name,
+            search_result_serializer=search_result_serializer,
+        )
+        self._index = _BM25Index()
+        self._indexed_tools: Sequence[Tool] = ()
+        self._last_hash: str = ""
+
+    def _make_search_tool(self) -> Tool:
+        transform = self
+
+        async def search_tools(
+            query: Annotated[str, "Natural language query to search for tools"],
+            ctx: Context = None,  # type: ignore[assignment]  # ty:ignore[invalid-parameter-default]
+        ) -> str | list[dict[str, Any]]:
+            """Search for tools using natural language.
+
+            Returns matching tool definitions ranked by relevance,
+            in the same format as list_tools.
+            """
+            hidden = await transform._get_visible_tools(ctx)
+            results = await transform._search(hidden, query)
+            return await transform._render_results(results)
+
+        return Tool.from_function(fn=search_tools, name=self._search_tool_name)
+
+    async def _search(self, tools: Sequence[Tool], query: str) -> Sequence[Tool]:
+        current_hash = _catalog_hash(tools)
+        if current_hash != self._last_hash:
+            documents = [_extract_searchable_text(t) for t in tools]
+            new_index = _BM25Index(self._index.k1, self._index.b)
+            new_index.build(documents)
+            self._index, self._indexed_tools, self._last_hash = (
+                new_index,
+                tools,
+                current_hash,
+            )
+
+        indices = self._index.query(query, self._max_results)
+        return [self._indexed_tools[i] for i in indices]
diff --git a/fastmcp_slim/fastmcp/server/transforms/search/regex.py b/fastmcp_slim/fastmcp/server/transforms/search/regex.py
new file mode 100644
index 0000000..f1b2d25
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/transforms/search/regex.py
@@ -0,0 +1,55 @@
+"""Regex-based search transform."""
+
+import re
+from collections.abc import Sequence
+from typing import Annotated, Any
+
+from fastmcp.server.context import Context
+from fastmcp.server.transforms.search.base import (
+    BaseSearchTransform,
+    _extract_searchable_text,
+)
+from fastmcp.tools.base import Tool
+
+
+class RegexSearchTransform(BaseSearchTransform):
+    """Search transform using regex pattern matching.
+
+    Tools are matched against their name, description, and parameter
+    information using ``re.search`` with ``re.IGNORECASE``.
+    """
+
+    def _make_search_tool(self) -> Tool:
+        transform = self
+
+        async def search_tools(
+            pattern: Annotated[
+                str,
+                "Regex pattern to match against tool names, descriptions, and parameters",
+            ],
+            ctx: Context = None,  # type: ignore[assignment]  # ty:ignore[invalid-parameter-default]
+        ) -> str | list[dict[str, Any]]:
+            """Search for tools matching a regex pattern.
+
+            Returns matching tool definitions in the same format as list_tools.
+            """
+            hidden = await transform._get_visible_tools(ctx)
+            results = await transform._search(hidden, pattern)
+            return await transform._render_results(results)
+
+        return Tool.from_function(fn=search_tools, name=self._search_tool_name)
+
+    async def _search(self, tools: Sequence[Tool], query: str) -> Sequence[Tool]:
+        try:
+            compiled = re.compile(query, re.IGNORECASE)
+        except re.error:
+            return []
+
+        matches: list[Tool] = []
+        for tool in tools:
+            text = _extract_searchable_text(tool)
+            if compiled.search(text):
+                matches.append(tool)
+                if len(matches) >= self._max_results:
+                    break
+        return matches
diff --git a/fastmcp_slim/fastmcp/server/transforms/tool_transform.py b/fastmcp_slim/fastmcp/server/transforms/tool_transform.py
new file mode 100644
index 0000000..bd4f168
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/transforms/tool_transform.py
@@ -0,0 +1,96 @@
+"""Transform for applying tool transformations."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from fastmcp.server.transforms import GetToolNext, Transform
+from fastmcp.tools.tool_transform import ToolTransformConfig
+from fastmcp.utilities.versions import VersionSpec
+
+if TYPE_CHECKING:
+    from fastmcp.tools.base import Tool
+
+
+class ToolTransform(Transform):
+    """Applies tool transformations to modify tool schemas.
+
+    Wraps ToolTransformConfig to apply argument renames, schema changes,
+    hidden arguments, and other transformations at the transform level.
+
+    Example:
+        ```python
+        transform = ToolTransform({
+            "my_tool": ToolTransformConfig(
+                name="renamed_tool",
+                arguments={"old_arg": ArgTransformConfig(name="new_arg")}
+            )
+        })
+        ```
+    """
+
+    def __init__(self, transforms: dict[str, ToolTransformConfig]) -> None:
+        """Initialize ToolTransform.
+
+        Args:
+            transforms: Map of original tool name → transform config.
+        """
+        self._transforms = transforms
+
+        # Build reverse mapping: final_name → original_name
+        self._name_reverse: dict[str, str] = {}
+        for original_name, config in transforms.items():
+            final_name = config.name if config.name else original_name
+            self._name_reverse[final_name] = original_name
+
+        # Validate no duplicate target names
+        seen_targets: dict[str, str] = {}
+        for original_name, config in transforms.items():
+            target = config.name if config.name else original_name
+            if target in seen_targets:
+                raise ValueError(
+                    f"ToolTransform has duplicate target name {target!r}: "
+                    f"both {seen_targets[target]!r} and {original_name!r} map to it"
+                )
+            seen_targets[target] = original_name
+
+    def __repr__(self) -> str:
+        names = list(self._transforms.keys())
+        if len(names) <= 3:
+            return f"ToolTransform({names!r})"
+        return f"ToolTransform({names[:3]!r}... +{len(names) - 3} more)"
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        """Apply transforms to matching tools."""
+        result: list[Tool] = []
+        for tool in tools:
+            if tool.name in self._transforms:
+                transformed = self._transforms[tool.name].apply(tool)
+                result.append(transformed)
+            else:
+                result.append(tool)
+        return result
+
+    async def get_tool(
+        self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get tool by transformed name."""
+        # Check if this name is a transformed name
+        original_name = self._name_reverse.get(name, name)
+
+        # Get the original tool
+        tool = await call_next(original_name, version=version)
+        if tool is None:
+            return None
+
+        # Apply transform if applicable
+        if original_name in self._transforms:
+            transformed = self._transforms[original_name].apply(tool)
+            # Only return if requested name matches transformed name
+            if transformed.name == name:
+                return transformed
+            return None
+
+        # No transform, return as-is only if name matches
+        return tool if tool.name == name else None
diff --git a/fastmcp_slim/fastmcp/server/transforms/version_filter.py b/fastmcp_slim/fastmcp/server/transforms/version_filter.py
new file mode 100644
index 0000000..11a5862
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/transforms/version_filter.py
@@ -0,0 +1,148 @@
+"""Version filter transform for filtering components by version range."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from fastmcp.server.transforms import (
+    GetPromptNext,
+    GetResourceNext,
+    GetResourceTemplateNext,
+    GetToolNext,
+    Transform,
+)
+from fastmcp.utilities.versions import VersionSpec
+
+if TYPE_CHECKING:
+    from fastmcp.prompts.base import Prompt
+    from fastmcp.resources.base import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.tools.base import Tool
+
+
+class VersionFilter(Transform):
+    """Filters components by version range.
+
+    When applied to a provider or server, components within the version range
+    are visible, and unversioned components are included by default. Within
+    that filtered set, the highest version of each component is exposed to
+    clients (standard deduplication behavior). Set
+    ``include_unversioned=False`` to exclude unversioned components.
+
+    Parameters mirror comparison operators for clarity:
+
+        # Versions < 3.0 (v1 and v2)
+        server.add_transform(VersionFilter(version_lt="3.0"))
+
+        # Versions >= 2.0 and < 3.0 (only v2.x)
+        server.add_transform(VersionFilter(version_gte="2.0", version_lt="3.0"))
+
+    Works with any version string - PEP 440 (1.0, 2.0) or dates (2025-01-01).
+
+    Args:
+        version_gte: Versions >= this value pass through.
+        version_lt: Versions < this value pass through.
+        include_unversioned: Whether unversioned components (``version=None``)
+            should pass through the filter. Defaults to True.
+    """
+
+    def __init__(
+        self,
+        *,
+        version_gte: str | None = None,
+        version_lt: str | None = None,
+        include_unversioned: bool = True,
+    ) -> None:
+        if version_gte is None and version_lt is None:
+            raise ValueError(
+                "At least one of version_gte or version_lt must be specified"
+            )
+        self.version_gte = version_gte
+        self.version_lt = version_lt
+        self.include_unversioned = include_unversioned
+        self._spec = VersionSpec(gte=version_gte, lt=version_lt)
+
+    def __repr__(self) -> str:
+        parts = []
+        if self.version_gte:
+            parts.append(f"version_gte={self.version_gte!r}")
+        if self.version_lt:
+            parts.append(f"version_lt={self.version_lt!r}")
+        if not self.include_unversioned:
+            parts.append("include_unversioned=False")
+        return f"VersionFilter({', '.join(parts)})"
+
+    # -------------------------------------------------------------------------
+    # Tools
+    # -------------------------------------------------------------------------
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        return [
+            t
+            for t in tools
+            if self._spec.matches(t.version, match_none=self.include_unversioned)
+        ]
+
+    async def get_tool(
+        self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
+    ) -> Tool | None:
+        return await call_next(name, version=self._spec.intersect(version))
+
+    # -------------------------------------------------------------------------
+    # Resources
+    # -------------------------------------------------------------------------
+
+    async def list_resources(self, resources: Sequence[Resource]) -> Sequence[Resource]:
+        return [
+            r
+            for r in resources
+            if self._spec.matches(r.version, match_none=self.include_unversioned)
+        ]
+
+    async def get_resource(
+        self,
+        uri: str,
+        call_next: GetResourceNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> Resource | None:
+        return await call_next(uri, version=self._spec.intersect(version))
+
+    # -------------------------------------------------------------------------
+    # Resource Templates
+    # -------------------------------------------------------------------------
+
+    async def list_resource_templates(
+        self, templates: Sequence[ResourceTemplate]
+    ) -> Sequence[ResourceTemplate]:
+        return [
+            t
+            for t in templates
+            if self._spec.matches(t.version, match_none=self.include_unversioned)
+        ]
+
+    async def get_resource_template(
+        self,
+        uri: str,
+        call_next: GetResourceTemplateNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> ResourceTemplate | None:
+        return await call_next(uri, version=self._spec.intersect(version))
+
+    # -------------------------------------------------------------------------
+    # Prompts
+    # -------------------------------------------------------------------------
+
+    async def list_prompts(self, prompts: Sequence[Prompt]) -> Sequence[Prompt]:
+        return [
+            p
+            for p in prompts
+            if self._spec.matches(p.version, match_none=self.include_unversioned)
+        ]
+
+    async def get_prompt(
+        self, name: str, call_next: GetPromptNext, *, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        return await call_next(name, version=self._spec.intersect(version))
diff --git a/fastmcp_slim/fastmcp/server/transforms/visibility.py b/fastmcp_slim/fastmcp/server/transforms/visibility.py
new file mode 100644
index 0000000..d294d49
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/transforms/visibility.py
@@ -0,0 +1,526 @@
+"""Visibility transform for marking component visibility state.
+
+Each Visibility instance marks components via internal metadata. Multiple
+visibility transforms can be stacked - later transforms override earlier ones.
+Final filtering happens at the Provider level.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any, Literal, TypeVar
+
+import mcp_types
+
+from fastmcp.resources.base import Resource
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.transforms import (
+    GetPromptNext,
+    GetResourceNext,
+    GetResourceTemplateNext,
+    GetToolNext,
+    Transform,
+)
+from fastmcp.utilities.versions import VersionSpec
+
+if TYPE_CHECKING:
+    from fastmcp.prompts.base import Prompt
+    from fastmcp.server.context import Context
+    from fastmcp.tools.base import Tool
+    from fastmcp.utilities.components import FastMCPComponent
+
+T = TypeVar("T", bound="FastMCPComponent")
+
+# Visibility state stored at meta["fastmcp"]["_internal"]["visibility"]
+_FASTMCP_KEY = "fastmcp"
+_INTERNAL_KEY = "_internal"
+
+
+class Visibility(Transform):
+    """Sets visibility state on matching components.
+
+    Does NOT filter inline - just marks components with visibility state.
+    Later transforms in the chain can override earlier marks.
+    Final filtering happens at the Provider level after all transforms run.
+
+    Example:
+        ```python
+        # Disable components tagged "internal"
+        Visibility(False, tags={"internal"})
+
+        # Re-enable specific tool (override earlier disable)
+        Visibility(True, names={"safe_tool"})
+
+        # Allowlist via composition:
+        Visibility(False, match_all=True)  # disable everything
+        Visibility(True, tags={"public"})  # enable public
+        ```
+    """
+
+    def __init__(
+        self,
+        enabled: bool,
+        *,
+        names: set[str] | None = None,
+        keys: set[str] | None = None,
+        version: VersionSpec | None = None,
+        tags: set[str] | None = None,
+        components: set[Literal["tool", "resource", "template", "prompt"]]
+        | None = None,
+        match_all: bool = False,
+    ) -> None:
+        """Initialize a visibility marker.
+
+        Args:
+            enabled: If True, mark matching as enabled; if False, mark as disabled.
+            names: Component names or URIs to match.
+            keys: Component keys to match (e.g., {"tool:my_tool@v1"}).
+            version: Component version spec to match. Unversioned components (version=None)
+                will NOT match a version spec.
+            tags: Tags to match (component must have at least one).
+            components: Component types to match (e.g., {"tool", "prompt"}).
+            match_all: If True, matches all components regardless of other criteria.
+        """
+        self._enabled = enabled
+        self.names = names
+        self.keys = keys
+        self.version = version
+        self.tags = tags  # e.g., {"internal", "deprecated"}
+        self.components = components  # e.g., {"tool", "prompt"}
+        self.match_all = match_all
+
+    def __repr__(self) -> str:
+        action = "enable" if self._enabled else "disable"
+        if self.match_all:
+            return f"Visibility({self._enabled}, match_all=True)"
+        parts = []
+        if self.names:
+            parts.append(f"names={set(self.names)}")
+        if self.keys:
+            parts.append(f"keys={set(self.keys)}")
+        if self.version:
+            parts.append(f"version={self.version!r}")
+        if self.components:
+            parts.append(f"components={set(self.components)}")
+        if self.tags:
+            parts.append(f"tags={set(self.tags)}")
+        if parts:
+            return f"Visibility({action}, {', '.join(parts)})"
+        return f"Visibility({action})"
+
+    def _matches(self, component: FastMCPComponent) -> bool:
+        """Check if this transform applies to the component.
+
+        All specified criteria must match (intersection semantics).
+        An empty rule (no criteria) matches nothing.
+        Use match_all=True to match everything.
+
+        Args:
+            component: Component to check.
+
+        Returns:
+            True if this transform should mark the component.
+        """
+        # Match-all flag matches everything
+        if self.match_all:
+            return True
+
+        # Empty criteria matches nothing (safe default)
+        if (
+            self.names is None
+            and self.keys is None
+            and self.version is None
+            and self.components is None
+            and self.tags is None
+        ):
+            return False
+
+        # Check component type if specified
+        if self.components is not None:
+            component_type = component.key.split(":")[
+                0
+            ]  # e.g., "tool" from "tool:foo@"
+            if component_type not in self.components:
+                return False
+
+        # Check keys if specified (exact match only)
+        if self.keys is not None:
+            if component.key not in self.keys:
+                return False
+
+        # Check names if specified
+        if self.names is not None:
+            # For resources, also check URI; for templates, check uri_template
+            matches_name = component.name in self.names
+            matches_uri = False
+            if isinstance(component, Resource):
+                matches_uri = str(component.uri) in self.names
+            elif isinstance(component, ResourceTemplate):
+                matches_uri = component.uri_template in self.names
+            if not (matches_name or matches_uri):
+                return False
+
+        # Check version if specified
+        # Note: match_none=False means unversioned components don't match a version spec
+        if self.version is not None and not self.version.matches(
+            component.version, match_none=False
+        ):
+            return False
+
+        # Check tags if specified (component must have at least one matching tag)
+        return self.tags is None or bool(component.tags & self.tags)
+
+    def _mark_component(self, component: T) -> T:
+        """Set visibility state in component metadata if rule matches.
+
+        Returns a copy of the component with updated metadata to avoid
+        mutating shared objects cached in providers.
+        """
+        if not self._matches(component):
+            return component
+
+        if component.meta is None:
+            new_meta = {_FASTMCP_KEY: {_INTERNAL_KEY: {"visibility": self._enabled}}}
+        else:
+            old_fastmcp = component.meta.get(_FASTMCP_KEY, {})
+            old_internal = old_fastmcp.get(_INTERNAL_KEY, {})
+            new_internal = {**old_internal, "visibility": self._enabled}
+            new_fastmcp = {**old_fastmcp, _INTERNAL_KEY: new_internal}
+            new_meta = {**component.meta, _FASTMCP_KEY: new_fastmcp}
+        return component.model_copy(update={"meta": new_meta})
+
+    # -------------------------------------------------------------------------
+    # Transform methods (mark components, don't filter)
+    # -------------------------------------------------------------------------
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        """Mark tools by visibility state."""
+        return [self._mark_component(t) for t in tools]
+
+    async def get_tool(
+        self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Mark tool if found."""
+        tool = await call_next(name, version=version)
+        if tool is None:
+            return None
+        return self._mark_component(tool)
+
+    # -------------------------------------------------------------------------
+    # Resources
+    # -------------------------------------------------------------------------
+
+    async def list_resources(self, resources: Sequence[Resource]) -> Sequence[Resource]:
+        """Mark resources by visibility state."""
+        return [self._mark_component(r) for r in resources]
+
+    async def get_resource(
+        self,
+        uri: str,
+        call_next: GetResourceNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> Resource | None:
+        """Mark resource if found."""
+        resource = await call_next(uri, version=version)
+        if resource is None:
+            return None
+        return self._mark_component(resource)
+
+    # -------------------------------------------------------------------------
+    # Resource Templates
+    # -------------------------------------------------------------------------
+
+    async def list_resource_templates(
+        self, templates: Sequence[ResourceTemplate]
+    ) -> Sequence[ResourceTemplate]:
+        """Mark resource templates by visibility state."""
+        return [self._mark_component(t) for t in templates]
+
+    async def get_resource_template(
+        self,
+        uri: str,
+        call_next: GetResourceTemplateNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> ResourceTemplate | None:
+        """Mark resource template if found."""
+        template = await call_next(uri, version=version)
+        if template is None:
+            return None
+        return self._mark_component(template)
+
+    # -------------------------------------------------------------------------
+    # Prompts
+    # -------------------------------------------------------------------------
+
+    async def list_prompts(self, prompts: Sequence[Prompt]) -> Sequence[Prompt]:
+        """Mark prompts by visibility state."""
+        return [self._mark_component(p) for p in prompts]
+
+    async def get_prompt(
+        self, name: str, call_next: GetPromptNext, *, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        """Mark prompt if found."""
+        prompt = await call_next(name, version=version)
+        if prompt is None:
+            return None
+        return self._mark_component(prompt)
+
+
+def is_enabled(component: FastMCPComponent) -> bool:
+    """Check if component is enabled.
+
+    Returns True if:
+    - No visibility mark exists (default is enabled)
+    - Visibility mark is True
+
+    Returns False if visibility mark is False.
+
+    Args:
+        component: Component to check.
+
+    Returns:
+        True if component should be enabled/visible to clients.
+    """
+    meta = component.meta or {}
+    fastmcp = meta.get(_FASTMCP_KEY, {})
+    internal = fastmcp.get(_INTERNAL_KEY, {})
+    return internal.get("visibility", True)  # Default True if not set
+
+
+# -------------------------------------------------------------------------
+# Session visibility control
+# -------------------------------------------------------------------------
+
+if TYPE_CHECKING:
+    from fastmcp.server.context import Context
+
+
+async def get_visibility_rules(context: Context) -> list[dict[str, Any]]:
+    """Load visibility rule dicts from session state."""
+    return await context.get_state("_visibility_rules") or []
+
+
+async def save_visibility_rules(
+    context: Context,
+    rules: list[dict[str, Any]],
+    *,
+    components: set[Literal["tool", "resource", "template", "prompt"]] | None = None,
+) -> None:
+    """Save visibility rule dicts to session state and send notifications.
+
+    Args:
+        context: The context to save rules for.
+        rules: The visibility rules to save.
+        components: Optional hint about which component types are affected.
+            If None, sends notifications for all types (safe default).
+            If provided, only sends notifications for specified types.
+    """
+    await context.set_state("_visibility_rules", rules)
+
+    # Send notifications based on components hint
+    # Note: MCP has no separate template notification - templates use ResourceListChangedNotification
+    if components is None or "tool" in components:
+        await context.send_notification(mcp_types.ToolListChangedNotification())
+    if components is None or "resource" in components or "template" in components:
+        await context.send_notification(mcp_types.ResourceListChangedNotification())
+    if components is None or "prompt" in components:
+        await context.send_notification(mcp_types.PromptListChangedNotification())
+
+
+def create_visibility_transforms(rules: list[dict[str, Any]]) -> list[Visibility]:
+    """Convert rule dicts to Visibility transforms."""
+    transforms = []
+    for params in rules:
+        version = None
+        if params.get("version"):
+            version_dict = params["version"]
+            version = VersionSpec(
+                gte=version_dict.get("gte"),
+                lt=version_dict.get("lt"),
+                eq=version_dict.get("eq"),
+            )
+        transforms.append(
+            Visibility(
+                params["enabled"],
+                names=set(params["names"]) if params.get("names") else None,
+                keys=set(params["keys"]) if params.get("keys") else None,
+                version=version,
+                tags=set(params["tags"]) if params.get("tags") else None,
+                components=(
+                    set(params["components"]) if params.get("components") else None
+                ),
+                match_all=params.get("match_all", False),
+            )
+        )
+    return transforms
+
+
+async def get_session_transforms(context: Context) -> list[Visibility]:
+    """Get session-specific Visibility transforms from state store."""
+    try:
+        # Will raise RuntimeError if no session available
+        _ = context.session_id
+    except RuntimeError:
+        return []
+
+    rules = await get_visibility_rules(context)
+    return create_visibility_transforms(rules)
+
+
+async def enable_components(
+    context: Context,
+    *,
+    names: set[str] | None = None,
+    keys: set[str] | None = None,
+    version: VersionSpec | None = None,
+    tags: set[str] | None = None,
+    components: set[Literal["tool", "resource", "template", "prompt"]] | None = None,
+    match_all: bool = False,
+) -> None:
+    """Enable components matching criteria for this session only.
+
+    Session rules override global transforms. Rules accumulate - each call
+    adds a new rule to the session. Later marks override earlier ones
+    (Visibility transform semantics).
+
+    Sends notifications to this session only: ToolListChangedNotification,
+    ResourceListChangedNotification, and PromptListChangedNotification.
+
+    Args:
+        context: The context for this session.
+        names: Component names or URIs to match.
+        keys: Component keys to match (e.g., {"tool:my_tool@v1"}).
+        version: Component version spec to match.
+        tags: Tags to match (component must have at least one).
+        components: Component types to match (e.g., {"tool", "prompt"}).
+        match_all: If True, matches all components regardless of other criteria.
+    """
+    # Normalize empty sets to None (empty = match all)
+    components = components if components else None
+
+    # Load current rules
+    rules = await get_visibility_rules(context)
+
+    # Create new rule dict
+    rule: dict[str, Any] = {
+        "enabled": True,
+        "names": list(names) if names else None,
+        "keys": list(keys) if keys else None,
+        "version": (
+            {"gte": version.gte, "lt": version.lt, "eq": version.eq}
+            if version
+            else None
+        ),
+        "tags": list(tags) if tags else None,
+        "components": list(components) if components else None,
+        "match_all": match_all,
+    }
+
+    # Add and save (notifications sent by save_visibility_rules)
+    rules.append(rule)
+    await save_visibility_rules(context, rules, components=components)
+
+
+async def disable_components(
+    context: Context,
+    *,
+    names: set[str] | None = None,
+    keys: set[str] | None = None,
+    version: VersionSpec | None = None,
+    tags: set[str] | None = None,
+    components: set[Literal["tool", "resource", "template", "prompt"]] | None = None,
+    match_all: bool = False,
+) -> None:
+    """Disable components matching criteria for this session only.
+
+    Session rules override global transforms. Rules accumulate - each call
+    adds a new rule to the session. Later marks override earlier ones
+    (Visibility transform semantics).
+
+    Sends notifications to this session only: ToolListChangedNotification,
+    ResourceListChangedNotification, and PromptListChangedNotification.
+
+    Args:
+        context: The context for this session.
+        names: Component names or URIs to match.
+        keys: Component keys to match (e.g., {"tool:my_tool@v1"}).
+        version: Component version spec to match.
+        tags: Tags to match (component must have at least one).
+        components: Component types to match (e.g., {"tool", "prompt"}).
+        match_all: If True, matches all components regardless of other criteria.
+    """
+    # Normalize empty sets to None (empty = match all)
+    components = components if components else None
+
+    # Load current rules
+    rules = await get_visibility_rules(context)
+
+    # Create new rule dict
+    rule: dict[str, Any] = {
+        "enabled": False,
+        "names": list(names) if names else None,
+        "keys": list(keys) if keys else None,
+        "version": (
+            {"gte": version.gte, "lt": version.lt, "eq": version.eq}
+            if version
+            else None
+        ),
+        "tags": list(tags) if tags else None,
+        "components": list(components) if components else None,
+        "match_all": match_all,
+    }
+
+    # Add and save (notifications sent by save_visibility_rules)
+    rules.append(rule)
+    await save_visibility_rules(context, rules, components=components)
+
+
+async def reset_visibility(context: Context) -> None:
+    """Clear all session visibility rules.
+
+    Use this to reset session visibility back to global defaults.
+
+    Sends notifications to this session only: ToolListChangedNotification,
+    ResourceListChangedNotification, and PromptListChangedNotification.
+
+    Args:
+        context: The context for this session.
+    """
+    await save_visibility_rules(context, [])
+
+
+ComponentT = TypeVar("ComponentT", bound="FastMCPComponent")
+
+
+async def apply_session_transforms(
+    components: Sequence[ComponentT],
+) -> Sequence[ComponentT]:
+    """Apply session-specific visibility transforms to components.
+
+    This helper applies session-level enable/disable rules by marking
+    components with their visibility state. Session transforms override
+    global transforms due to mark-based semantics (later marks win).
+
+    Args:
+        components: The components to apply session transforms to.
+
+    Returns:
+        The components with session transforms applied.
+    """
+    from fastmcp.server.context import _current_context
+
+    current_ctx = _current_context.get()
+    if current_ctx is None:
+        return components
+
+    session_transforms = await get_session_transforms(current_ctx)
+    if not session_transforms:
+        return components
+
+    # Apply each transform's marking to each component
+    result = list(components)
+    for transform in session_transforms:
+        result = [transform._mark_component(c) for c in result]
+    return result
diff --git a/fastmcp_slim/fastmcp/settings.py b/fastmcp_slim/fastmcp/settings.py
new file mode 100644
index 0000000..dccfcf5
--- /dev/null
+++ b/fastmcp_slim/fastmcp/settings.py
@@ -0,0 +1,398 @@
+from __future__ import annotations as _annotations
+
+import inspect
+import os
+from datetime import timedelta
+from pathlib import Path
+from typing import Annotated, Any, Literal
+
+from platformdirs import user_data_dir
+from pydantic import Field, field_validator
+from pydantic_settings import (
+    BaseSettings,
+    SettingsConfigDict,
+)
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+ENV_FILE = os.getenv("FASTMCP_ENV_FILE", ".env")
+
+LOG_LEVEL = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+MCP_LOG_LEVEL = Literal[
+    "debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"
+]
+
+DuplicateBehavior = Literal["warn", "error", "replace", "ignore"]
+
+TEN_MB_IN_BYTES = 1024 * 1024 * 10
+
+
+class DocketSettings(BaseSettings):
+    """Docket worker configuration."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="FASTMCP_DOCKET_",
+        extra="ignore",
+    )
+
+    name: Annotated[
+        str,
+        Field(
+            description=inspect.cleandoc(
+                """
+                Name for the Docket queue. All servers/workers sharing the same name
+                and backend URL will share a task queue.
+                """
+            ),
+        ),
+    ] = "fastmcp"
+
+    url: Annotated[
+        str,
+        Field(
+            description=inspect.cleandoc(
+                """
+                URL for the Docket backend. Supports:
+                - memory:// - In-memory backend (single process only)
+                - redis://host:port/db - Redis/Valkey backend (distributed, multi-process)
+
+                Example: redis://localhost:6379/0
+
+                Default is memory:// for single-process scenarios. Use Redis or Valkey
+                when coordinating tasks across multiple processes (e.g., additional
+                workers via the fastmcp tasks CLI).
+                """
+            ),
+        ),
+    ] = "memory://"
+
+    worker_name: Annotated[
+        str | None,
+        Field(
+            description=inspect.cleandoc(
+                """
+                Name for the Docket worker. If None, Docket will auto-generate
+                a unique worker name.
+                """
+            ),
+        ),
+    ] = None
+
+    concurrency: Annotated[
+        int,
+        Field(
+            description=inspect.cleandoc(
+                """
+                Maximum number of tasks the worker can process concurrently.
+                """
+            ),
+        ),
+    ] = 10
+
+    redelivery_timeout: Annotated[
+        timedelta,
+        Field(
+            description=inspect.cleandoc(
+                """
+                Task redelivery timeout. If a worker doesn't complete
+                a task within this time, the task will be redelivered to another
+                worker.
+                """
+            ),
+        ),
+    ] = timedelta(seconds=300)
+
+    reconnection_delay: Annotated[
+        timedelta,
+        Field(
+            description=inspect.cleandoc(
+                """
+                Delay between reconnection attempts when the worker
+                loses connection to the Docket backend.
+                """
+            ),
+        ),
+    ] = timedelta(seconds=5)
+
+    minimum_check_interval: Annotated[
+        timedelta,
+        Field(
+            description=inspect.cleandoc(
+                """
+                How frequently the worker polls for new tasks. Lower
+                values reduce latency for task pickup at the cost of
+                more CPU usage. The default of 50ms is a good balance;
+                increase for high-volume production deployments where
+                tasks are long-running.
+                """
+            ),
+        ),
+    ] = timedelta(milliseconds=50)
+
+
+class Settings(BaseSettings):
+    """FastMCP settings."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="FASTMCP_",
+        env_file=ENV_FILE,
+        extra="ignore",
+        env_nested_delimiter="__",
+        nested_model_default_partial_update=True,
+        validate_assignment=True,
+    )
+
+    def get_setting(self, attr: str) -> Any:
+        """
+        Get a setting. If the setting contains one or more `__`, it will be
+        treated as a nested setting.
+        """
+        settings = self
+        while "__" in attr:
+            parent_attr, attr = attr.split("__", 1)
+            if not hasattr(settings, parent_attr):
+                raise AttributeError(f"Setting {parent_attr} does not exist.")
+            settings = getattr(settings, parent_attr)
+        return getattr(settings, attr)
+
+    def set_setting(self, attr: str, value: Any) -> None:
+        """
+        Set a setting. If the setting contains one or more `__`, it will be
+        treated as a nested setting.
+        """
+        settings = self
+        while "__" in attr:
+            parent_attr, attr = attr.split("__", 1)
+            if not hasattr(settings, parent_attr):
+                raise AttributeError(f"Setting {parent_attr} does not exist.")
+            settings = getattr(settings, parent_attr)
+        setattr(settings, attr, value)
+
+    home: Path = Path(user_data_dir("fastmcp", appauthor=False))
+
+    test_mode: bool = False
+
+    log_enabled: bool = True
+    log_level: LOG_LEVEL = "INFO"
+
+    @field_validator("log_level", mode="before")
+    @classmethod
+    def normalize_log_level(cls, v):
+        if isinstance(v, str):
+            return v.upper()
+        return v
+
+    docket: DocketSettings = DocketSettings()
+
+    enable_rich_logging: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """
+                If True, will use rich formatting for log output. If False,
+                will use standard Python logging without rich formatting.
+                """
+            )
+        ),
+    ] = True
+
+    enable_rich_tracebacks: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """
+                If True, will use rich tracebacks for logging.
+                """
+            )
+        ),
+    ] = True
+
+    deprecation_warnings: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """
+                Whether to show deprecation warnings. You can completely reset
+                Python's warning behavior by running `warnings.resetwarnings()`.
+                Note this will NOT apply to deprecation warnings from the
+                settings class itself.
+                """,
+            )
+        ),
+    ] = True
+
+    mcp_camelcase_compat: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """
+                Whether to install compatibility shims that let legacy
+                camelCase reads on MCP SDK objects (e.g. `tool.inputSchema`,
+                `result.isError`) keep working after the SDK v2 rename to
+                snake_case. Each bridged read emits a
+                `FastMCPDeprecationWarning`. Set to False to disable the shims
+                entirely, in which case only the snake_case names resolve.
+                """
+            ),
+        ),
+    ] = True
+
+    client_raise_first_exceptiongroup_error: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """
+                Many MCP components operate in anyio taskgroups, and raise
+                ExceptionGroups instead of exceptions. If this setting is True, FastMCP Clients
+                will `raise` the first error in any ExceptionGroup instead of raising
+                the ExceptionGroup as a whole. This is useful for debugging, but may
+                mask other errors.
+                """
+            ),
+        ),
+    ] = True
+
+    client_init_timeout: Annotated[
+        float | None,
+        Field(
+            description="The timeout for the client's initialization handshake, in seconds. Set to None or 0 to disable.",
+        ),
+    ] = None
+
+    client_disconnect_timeout: Annotated[
+        float,
+        Field(
+            description="Maximum time to wait for a clean disconnect before giving up, in seconds.",
+        ),
+    ] = 5
+
+    # Transport settings
+    transport: Literal["stdio", "http", "sse", "streamable-http"] = "stdio"
+
+    # HTTP settings
+    host: str = "127.0.0.1"
+    port: int = 8000
+    sse_path: str = "/sse"
+    message_path: str = "/messages/"
+    streamable_http_path: str = "/mcp"
+    debug: bool = False
+
+    # error handling
+    mask_error_details: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """
+                If True, error details from user-supplied functions (tool, resource, prompt)
+                will be masked before being sent to clients. Only error messages from explicitly
+                raised ToolError, ResourceError, or PromptError will be included in responses.
+                If False (default), all error details will be included in responses, but prefixed
+                with appropriate context.
+                """
+            ),
+        ),
+    ] = False
+
+    client_log_level: Annotated[
+        MCP_LOG_LEVEL | None,
+        Field(
+            description=inspect.cleandoc(
+                """
+                Default minimum log level for messages sent to MCP clients.
+                When set, log messages below this level are suppressed.
+                Individual clients can override this per-session using the
+                MCP logging/setLevel request.
+                """
+            ),
+        ),
+    ] = None
+
+    strict_input_validation: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """
+                If True, tool inputs are strictly validated against the input
+                JSON schema. For example, providing the string \"10\" to an
+                integer field will raise an error. If False, compatible inputs
+                will be coerced to match the schema, which can increase
+                compatibility. For example, providing the string \"10\" to an
+                integer field will be coerced to 10. Defaults to False.
+                """
+            ),
+        ),
+    ] = False
+
+    server_dependencies: list[str] = Field(
+        default_factory=list,
+        description="List of dependencies to install in the server environment",
+    )
+
+    # StreamableHTTP settings
+    json_response: bool = False
+    stateless_http: bool = (
+        False  # If True, uses true stateless mode (new transport per request)
+    )
+    http_host_origin_protection: bool | Literal["auto"] = False
+    http_allowed_hosts: list[str] | None = None
+    http_allowed_origins: list[str] | None = None
+    http_session_idle_timeout: Annotated[
+        float | None,
+        Field(
+            description=inspect.cleandoc(
+                """
+                Maximum time in seconds a streamable-HTTP session may remain
+                idle before it is terminated. A session's deadline is pushed
+                forward on every request. When None (default), sessions never
+                expire from inactivity. Not supported in stateless HTTP mode.
+                Must be a positive number of seconds when set.
+                """
+            ),
+            gt=0,
+        ),
+    ] = None
+
+    mounted_components_raise_on_load_error: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """
+                If True, errors encountered when loading mounted components (tools, resources, prompts)
+                will be raised instead of logged as warnings. This is useful for debugging
+                but will interrupt normal operation.
+                """
+            ),
+        ),
+    ] = False
+
+    show_server_banner: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """
+                If True, the server banner will be displayed when running the server.
+                This setting can be overridden by the --no-banner CLI flag or by
+                passing show_banner=False to server.run().
+                Set to False via FASTMCP_SHOW_SERVER_BANNER=false to suppress the banner.
+                """
+            ),
+        ),
+    ] = True
+
+    check_for_updates: Annotated[
+        Literal["stable", "prerelease", "off"],
+        Field(
+            description=inspect.cleandoc(
+                """
+                Controls update checking when displaying the CLI banner.
+                - "stable": Check for stable releases only (default)
+                - "prerelease": Also check for pre-release versions (alpha, beta, rc)
+                - "off": Disable update checking entirely
+                Set via FASTMCP_CHECK_FOR_UPDATES environment variable.
+                """
+            ),
+        ),
+    ] = "stable"
diff --git a/fastmcp_slim/fastmcp/telemetry.py b/fastmcp_slim/fastmcp/telemetry.py
new file mode 100644
index 0000000..0965b8b
--- /dev/null
+++ b/fastmcp_slim/fastmcp/telemetry.py
@@ -0,0 +1,122 @@
+"""OpenTelemetry instrumentation for FastMCP.
+
+This module provides native OpenTelemetry integration for FastMCP servers and clients.
+It uses only the opentelemetry-api package, so telemetry is a no-op unless the user
+installs an OpenTelemetry SDK and configures exporters.
+
+Example usage with SDK:
+    ```python
+    from opentelemetry import trace
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
+
+    # Configure the SDK (user responsibility)
+    provider = TracerProvider()
+    provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
+    trace.set_tracer_provider(provider)
+
+    # Now FastMCP will emit traces
+    from fastmcp import FastMCP
+    mcp = FastMCP("my-server")
+    ```
+"""
+
+from typing import Any
+
+from opentelemetry import context as otel_context
+from opentelemetry import propagate, trace
+from opentelemetry.context import Context
+from opentelemetry.trace import Span, Status, StatusCode, Tracer
+from opentelemetry.trace import get_tracer as otel_get_tracer
+
+INSTRUMENTATION_NAME = "fastmcp"
+
+TRACE_PARENT_KEY = "traceparent"
+TRACE_STATE_KEY = "tracestate"
+
+
+def get_tracer(version: str | None = None) -> Tracer:
+    """Get the FastMCP tracer for creating spans.
+
+    Args:
+        version: Optional version string for the instrumentation
+
+    Returns:
+        A tracer instance. Returns a no-op tracer if no SDK is configured.
+    """
+    return otel_get_tracer(INSTRUMENTATION_NAME, version)
+
+
+def inject_trace_context(
+    meta: dict[str, Any] | None = None,
+) -> dict[str, Any] | None:
+    """Inject current trace context into a meta dict for MCP request propagation.
+
+    Args:
+        meta: Optional existing meta dict to merge with trace context
+
+    Returns:
+        A new dict containing the original meta (if any) plus trace context keys,
+        or None if no trace context to inject and meta was None
+    """
+    carrier: dict[str, str] = {}
+    propagate.inject(carrier)
+
+    trace_meta: dict[str, Any] = {}
+    if "traceparent" in carrier:
+        trace_meta[TRACE_PARENT_KEY] = carrier["traceparent"]
+    if "tracestate" in carrier:
+        trace_meta[TRACE_STATE_KEY] = carrier["tracestate"]
+
+    if trace_meta:
+        return {**(meta or {}), **trace_meta}
+    return meta
+
+
+def record_span_error(span: Span, exception: BaseException) -> None:
+    """Record an exception on a span and set error status."""
+    span.record_exception(exception)
+    span.set_status(Status(StatusCode.ERROR))
+
+
+def extract_trace_context(meta: dict[str, Any] | None) -> Context:
+    """Extract trace context from an MCP request meta dict.
+
+    If already in a valid trace (e.g., from HTTP propagation), the existing
+    trace context is preserved and meta is not used.
+
+    Args:
+        meta: The meta dict from an MCP request (ctx.request_context.meta)
+
+    Returns:
+        An OpenTelemetry Context with the extracted trace context,
+        or the current context if no trace context found or already in a trace
+    """
+    # Don't override existing trace context (e.g., from HTTP propagation)
+    current_span = trace.get_current_span()
+    if current_span.get_span_context().is_valid:
+        return otel_context.get_current()
+
+    if not meta:
+        return otel_context.get_current()
+
+    carrier: dict[str, str] = {}
+    if TRACE_PARENT_KEY in meta:
+        carrier["traceparent"] = str(meta[TRACE_PARENT_KEY])
+    if TRACE_STATE_KEY in meta:
+        carrier["tracestate"] = str(meta[TRACE_STATE_KEY])
+
+    if carrier:
+        return propagate.extract(carrier)
+    return otel_context.get_current()
+
+
+__all__ = [
+    "INSTRUMENTATION_NAME",
+    "TRACE_PARENT_KEY",
+    "TRACE_STATE_KEY",
+    "extract_trace_context",
+    "get_tracer",
+    "inject_trace_context",
+    "record_span_error",
+]
diff --git a/fastmcp_slim/fastmcp/tools/__init__.py b/fastmcp_slim/fastmcp/tools/__init__.py
new file mode 100644
index 0000000..64360b2
--- /dev/null
+++ b/fastmcp_slim/fastmcp/tools/__init__.py
@@ -0,0 +1,20 @@
+import sys
+
+from .function_tool import FunctionTool, tool
+from .base import Tool, ToolResult
+from .tool_transform import forward, forward_raw
+
+# Backward compat: tool.py was renamed to base.py to stop Pyright from resolving
+# `from fastmcp.tools import tool` as the submodule instead of the decorator function.
+# This shim keeps `from fastmcp.tools.tool import Tool` working at runtime.
+# Safe to remove once we're confident no external code imports from the old path.
+sys.modules[f"{__name__}.tool"] = sys.modules[f"{__name__}.base"]
+
+__all__ = [
+    "FunctionTool",
+    "Tool",
+    "ToolResult",
+    "forward",
+    "forward_raw",
+    "tool",
+]
diff --git a/fastmcp_slim/fastmcp/tools/base.py b/fastmcp_slim/fastmcp/tools/base.py
new file mode 100644
index 0000000..011cacd
--- /dev/null
+++ b/fastmcp_slim/fastmcp/tools/base.py
@@ -0,0 +1,593 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    ClassVar,
+    overload,
+)
+
+import mcp_types
+import pydantic_core
+from mcp.shared.tool_name_validation import validate_and_warn_tool_name
+from mcp_types import (
+    CallToolResult,
+    ContentBlock,
+    Icon,
+    TextContent,
+    ToolAnnotations,
+    ToolExecution,
+)
+from mcp_types import Tool as MCPTool
+from pydantic import BaseModel, Field, model_validator
+from pydantic.json_schema import SkipJsonSchema
+
+from fastmcp.utilities.authorization import AuthCheck
+from fastmcp.utilities.components import FastMCPComponent
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.tasks import TaskConfig, TaskMeta
+from fastmcp.utilities.types import (
+    Audio,
+    File,
+    Image,
+    NotSet,
+    NotSetT,
+)
+
+try:
+    from prefab_ui.app import PrefabApp as _PrefabApp
+    from prefab_ui.components.base import Component as _PrefabComponent
+
+    _HAS_PREFAB = True
+except ImportError:
+    _HAS_PREFAB = False
+
+if TYPE_CHECKING:
+    from docket import Docket
+    from docket.execution import Execution
+
+    from fastmcp.tools.function_tool import FunctionTool
+    from fastmcp.tools.tool_transform import ArgTransform, TransformedTool
+
+# Re-export from function_tool module
+
+logger = get_logger(__name__)
+
+
+def resolve_serialize_by_alias(value: Any) -> bool:
+    """Resolve the effective ``by_alias`` setting for serializing *value*.
+
+    Pydantic's low-level serialization helpers (``to_json``,
+    ``to_jsonable_python``) default ``by_alias`` to ``True``, which silently
+    ignores a model's ``serialize_by_alias`` config. When *value* is a Pydantic
+    model we consult that config instead, falling back to ``True`` to preserve
+    FastMCP's longstanding default of emitting aliases when no preference is
+    declared.
+    """
+    if isinstance(value, type):
+        model = value if issubclass(value, BaseModel) else None
+    elif isinstance(value, BaseModel):
+        model = type(value)
+    else:
+        model = None
+
+    if model is None:
+        return True
+
+    configured = model.model_config.get("serialize_by_alias")
+    return True if configured is None else configured
+
+
+def default_serializer(data: Any) -> str:
+    return pydantic_core.to_json(
+        data, fallback=str, by_alias=resolve_serialize_by_alias(data)
+    ).decode()
+
+
+class ToolResult(BaseModel):
+    content: list[ContentBlock] = Field(
+        description="List of content blocks for the tool result"
+    )
+    structured_content: dict[str, Any] | None = Field(
+        default=None, description="Structured content matching the tool's output schema"
+    )
+    meta: dict[str, Any] | None = Field(
+        default=None, description="Runtime metadata about the tool execution"
+    )
+    is_error: bool = Field(
+        default=False,
+        description="Whether this result represents a tool execution error. "
+        "When True, it maps to CallToolResult.is_error so the error is returned "
+        "to the client rather than raised.",
+    )
+
+    def __init__(
+        self,
+        content: list[ContentBlock] | Any | None = None,
+        structured_content: dict[str, Any] | Any | None = None,
+        meta: dict[str, Any] | None = None,
+        is_error: bool = False,
+    ):
+        if content is None and structured_content is None:
+            raise ValueError("Either content or structured_content must be provided")
+        elif content is None:
+            content = structured_content
+
+        converted_content: list[ContentBlock] = _convert_to_content(result=content)
+
+        if structured_content is not None:
+            # Convert Prefab types to their wire-format envelope before
+            # generic serialization, so the renderer gets the right shape.
+            if _HAS_PREFAB:
+                if isinstance(structured_content, _PrefabApp):
+                    structured_content = _prefab_to_json(structured_content)
+                elif isinstance(structured_content, _PrefabComponent):
+                    structured_content = _prefab_to_json(
+                        _PrefabApp(view=structured_content)
+                    )
+
+            try:
+                structured_content = pydantic_core.to_jsonable_python(
+                    value=structured_content,
+                    by_alias=resolve_serialize_by_alias(structured_content),
+                )
+            except pydantic_core.PydanticSerializationError as e:
+                logger.error(
+                    f"Could not serialize structured content. If this is unexpected, set your tool's output_schema to None to disable automatic serialization: {e}"
+                )
+                raise
+            if not isinstance(structured_content, dict):
+                raise ValueError(
+                    "structured_content must be a dict or None. "
+                    f"Got {type(structured_content).__name__}: {structured_content!r}. "
+                    "Tools should wrap non-dict values based on their output_schema."
+                )
+
+        super().__init__(
+            content=converted_content,
+            structured_content=structured_content,
+            meta=meta,
+            is_error=is_error,
+        )
+
+    def to_mcp_result(
+        self,
+    ) -> (
+        list[ContentBlock] | tuple[list[ContentBlock], dict[str, Any]] | CallToolResult
+    ):
+        # An error result must round-trip through CallToolResult so isError
+        # reaches the client; the plain content/tuple returns can't carry it.
+        if self.meta is not None or self.is_error:
+            return CallToolResult(
+                structured_content=self.structured_content,
+                content=self.content,
+                is_error=self.is_error,
+                _meta=self.meta,  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
+            )
+        if self.structured_content is None:
+            return self.content
+        return self.content, self.structured_content
+
+
+class Tool(FastMCPComponent):
+    """Internal tool registration info."""
+
+    KEY_PREFIX: ClassVar[str] = "tool"
+
+    parameters: Annotated[
+        dict[str, Any], Field(description="JSON schema for tool parameters")
+    ]
+    output_schema: Annotated[
+        dict[str, Any] | None, Field(description="JSON schema for tool output")
+    ] = None
+    annotations: Annotated[
+        ToolAnnotations | None,
+        Field(description="Additional annotations about the tool"),
+    ] = None
+    execution: Annotated[
+        ToolExecution | None,
+        Field(description="Task execution configuration (SEP-1686)"),
+    ] = None
+    auth: Annotated[
+        SkipJsonSchema[AuthCheck | list[AuthCheck] | None],
+        Field(description="Authorization checks for this tool", exclude=True),
+    ] = None
+    timeout: Annotated[
+        float | None,
+        Field(
+            description="Execution timeout in seconds. If None, no timeout is applied."
+        ),
+    ] = None
+
+    @model_validator(mode="after")
+    def _validate_tool_name(self) -> Tool:
+        """Validate tool name according to MCP specification (SEP-986)."""
+        validate_and_warn_tool_name(self.name)
+        return self
+
+    def to_mcp_tool(
+        self,
+        **overrides: Any,
+    ) -> MCPTool:
+        """Convert the FastMCP tool to an MCP tool."""
+        title = None
+
+        if self.title:
+            title = self.title
+        elif self.annotations and self.annotations.title:
+            title = self.annotations.title
+
+        mcp_tool = MCPTool(
+            name=overrides.get("name", self.name),
+            title=overrides.get("title", title),
+            description=overrides.get("description", self.description),
+            input_schema=overrides.get("inputSchema", self.parameters),
+            output_schema=overrides.get("outputSchema", self.output_schema),
+            icons=overrides.get("icons", self.icons),
+            annotations=overrides.get("annotations", self.annotations),
+            execution=overrides.get("execution", self.execution),
+            _meta=overrides.get(  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
+                "_meta", self.get_meta()
+            ),
+        )
+
+        if (
+            self.task_config.supports_tasks()
+            and "execution" not in overrides
+            and not self.execution
+        ):
+            mcp_tool.execution = ToolExecution(task_support=self.task_config.mode)
+
+        return mcp_tool
+
+    @classmethod
+    def from_function(
+        cls,
+        fn: Callable[..., Any],
+        *,
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[Icon] | None = None,
+        tags: set[str] | None = None,
+        annotations: ToolAnnotations | None = None,
+        output_schema: dict[str, Any] | NotSetT | None = NotSet,
+        meta: dict[str, Any] | None = None,
+        task: bool | TaskConfig | None = None,
+        timeout: float | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+        run_in_thread: bool | None = None,
+    ) -> FunctionTool:
+        """Create a Tool from a function."""
+        from fastmcp.tools.function_tool import FunctionTool
+
+        return FunctionTool.from_function(
+            fn=fn,
+            name=name,
+            version=version,
+            title=title,
+            description=description,
+            icons=icons,
+            tags=tags,
+            annotations=annotations,
+            output_schema=output_schema,
+            meta=meta,
+            task=task,
+            timeout=timeout,
+            auth=auth,
+            run_in_thread=run_in_thread,
+        )
+
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
+        """
+        Run the tool with arguments.
+
+        This method is not implemented in the base Tool class and must be
+        implemented by subclasses.
+
+        `run()` can EITHER return a list of ContentBlocks, or a tuple of
+        (list of ContentBlocks, dict of structured output).
+        """
+        raise NotImplementedError("Subclasses must implement run()")
+
+    def convert_result(self, raw_value: Any) -> ToolResult:
+        """Convert a raw result to ToolResult.
+
+        Handles ToolResult passthrough and converts raw values using the tool's
+        attributes (output_schema) for proper conversion.
+        """
+        if isinstance(raw_value, ToolResult):
+            return raw_value
+
+        if _HAS_PREFAB:
+            if isinstance(raw_value, _PrefabApp):
+                return _prefab_to_tool_result(
+                    raw_value,
+                    fastmcp_app_name=_get_fastmcp_app_name(self),
+                )
+            if isinstance(raw_value, _PrefabComponent):
+                return _prefab_to_tool_result(
+                    _PrefabApp(view=raw_value),
+                    fastmcp_app_name=_get_fastmcp_app_name(self),
+                )
+
+        content = _convert_to_content(raw_value)
+
+        # Bytes can't be represented as structured JSON content
+        if isinstance(raw_value, bytes):
+            return ToolResult(content=content)
+
+        # Skip structured content for ContentBlock types only if no output_schema
+        # (if output_schema exists, MCP SDK requires structured_content)
+        if self.output_schema is None and (
+            isinstance(raw_value, ContentBlock | Audio | Image | File)
+            or (
+                isinstance(raw_value, list | tuple)
+                and any(isinstance(item, ContentBlock) for item in raw_value)
+            )
+        ):
+            return ToolResult(content=content)
+
+        try:
+            structured = pydantic_core.to_jsonable_python(
+                raw_value, by_alias=resolve_serialize_by_alias(raw_value)
+            )
+        except (pydantic_core.PydanticSerializationError, UnicodeDecodeError):
+            return ToolResult(content=content)
+
+        if self.output_schema is None:
+            # No schema - only use structured_content for dicts
+            if isinstance(structured, dict):
+                return ToolResult(content=content, structured_content=structured)
+            return ToolResult(content=content)
+
+        # Has output_schema - wrap if x-fastmcp-wrap-result is set
+        wrap_result = self.output_schema.get("x-fastmcp-wrap-result")
+        return ToolResult(
+            content=content,
+            structured_content={"result": structured} if wrap_result else structured,
+            meta={"fastmcp": {"wrap_result": True}} if wrap_result else None,
+        )
+
+    @overload
+    async def _run(
+        self,
+        arguments: dict[str, Any],
+        task_meta: None = None,
+    ) -> ToolResult: ...
+
+    @overload
+    async def _run(
+        self,
+        arguments: dict[str, Any],
+        task_meta: TaskMeta,
+    ) -> mcp_types.CreateTaskResult: ...
+
+    async def _run(
+        self,
+        arguments: dict[str, Any],
+        task_meta: TaskMeta | None = None,
+    ) -> ToolResult | mcp_types.CreateTaskResult:
+        """Server entry point that handles task routing.
+
+        This allows ANY Tool subclass to support background execution by setting
+        task_config.mode to "supported" or "required". The server calls this
+        method instead of run() directly.
+
+        Args:
+            arguments: Tool arguments
+            task_meta: If provided, execute as background task and return
+                CreateTaskResult. If None (default), execute synchronously and
+                return ToolResult.
+
+        Returns:
+            ToolResult when task_meta is None.
+            CreateTaskResult when task_meta is provided.
+
+        Subclasses can override this to customize task routing behavior.
+        For example, FastMCPProviderTool overrides to delegate to child
+        middleware without submitting to Docket.
+        """
+        from fastmcp.server.tasks.routing import check_background_task
+
+        task_result = await check_background_task(
+            component=self,
+            task_type="tool",
+            arguments=arguments,
+            task_meta=task_meta,
+        )
+        if task_result:
+            return task_result
+
+        return await self.run(arguments)
+
+    def register_with_docket(self, docket: Docket) -> None:
+        """Register this tool with docket for background execution."""
+        if not self.task_config.supports_tasks():
+            return
+        docket.register(self.run, names=[self.key])
+
+    async def add_to_docket(  # type: ignore[override]
+        self,
+        docket: Docket,
+        arguments: dict[str, Any],
+        *,
+        fn_key: str | None = None,
+        task_key: str | None = None,
+        **kwargs: Any,
+    ) -> Execution:
+        """Schedule this tool for background execution via docket.
+
+        Args:
+            docket: The Docket instance
+            arguments: Tool arguments
+            fn_key: Function lookup key in Docket registry (defaults to self.key)
+            task_key: Redis storage key for the result
+            **kwargs: Additional kwargs passed to docket.add()
+        """
+        lookup_key = fn_key or self.key
+        if task_key:
+            kwargs["key"] = task_key
+        return await docket.add(lookup_key, **kwargs)(arguments)
+
+    @classmethod
+    def from_tool(
+        cls,
+        tool: Tool | Callable[..., Any],
+        *,
+        name: str | None = None,
+        title: str | NotSetT | None = NotSet,
+        description: str | NotSetT | None = NotSet,
+        tags: set[str] | None = None,
+        annotations: ToolAnnotations | NotSetT | None = NotSet,
+        output_schema: dict[str, Any] | NotSetT | None = NotSet,
+        meta: dict[str, Any] | NotSetT | None = NotSet,
+        transform_args: dict[str, ArgTransform] | None = None,
+        transform_fn: Callable[..., Any] | None = None,
+    ) -> TransformedTool:
+        from fastmcp.tools.tool_transform import TransformedTool
+
+        tool = cls._ensure_tool(tool)
+
+        return TransformedTool.from_tool(
+            tool=tool,
+            transform_fn=transform_fn,
+            name=name,
+            title=title,
+            transform_args=transform_args,
+            description=description,
+            tags=tags,
+            annotations=annotations,
+            output_schema=output_schema,
+            meta=meta,
+        )
+
+    @classmethod
+    def _ensure_tool(cls, tool: Tool | Callable[..., Any]) -> Tool:
+        """Coerce a callable into a Tool, respecting @tool decorator metadata."""
+        if isinstance(tool, Tool):
+            return tool
+
+        from fastmcp.decorators import get_fastmcp_meta
+        from fastmcp.tools.function_tool import FunctionTool, ToolMeta
+
+        fmeta = get_fastmcp_meta(tool)
+        if isinstance(fmeta, ToolMeta):
+            return FunctionTool.from_function(tool, metadata=fmeta)
+
+        return cls.from_function(tool)
+
+    def get_span_attributes(self) -> dict[str, Any]:
+        return super().get_span_attributes() | {
+            "fastmcp.component.type": "tool",
+            "fastmcp.provider.type": "LocalProvider",
+        }
+
+
+def _convert_to_single_content_block(
+    item: Any,
+) -> ContentBlock:
+    if isinstance(item, ContentBlock):
+        return item
+
+    if isinstance(item, Image):
+        return item.to_image_content()
+
+    if isinstance(item, Audio):
+        return item.to_audio_content()
+
+    if isinstance(item, File):
+        return item.to_resource_content()
+
+    if isinstance(item, str):
+        return TextContent(type="text", text=item)
+
+    if isinstance(item, bytes):
+        try:
+            return TextContent(type="text", text=item.decode("utf-8"))
+        except UnicodeDecodeError:
+            import base64
+
+            return TextContent(type="text", text=base64.b64encode(item).decode("ascii"))
+
+    return TextContent(type="text", text=default_serializer(item))
+
+
+_PREFAB_TEXT_FALLBACK = "[Rendered Prefab UI]"
+
+
+def _get_tool_resolver(app_name: str | None = None) -> Callable[..., str] | None:
+    """Get the Prefab peer-reference resolver bound to an app name."""
+    try:
+        from fastmcp.apps.app import _make_resolver
+
+        return _make_resolver(app_name)
+    except ImportError:
+        return None
+
+
+def _prefab_to_json(app: Any, fastmcp_app_name: str | None = None) -> dict[str, Any]:
+    """Call PrefabApp.to_json() with the hash-based resolver.
+
+    The resolver prefixes peer-tool references with a deterministic hash
+    derived from the app name + tool name. The dispatcher recognizes that
+    format and routes calls via ``get_tool_by_hash`` which walks the
+    provider tree recursively — same pattern as the old ``get_app_tool``.
+    """
+    data = app.to_json(tool_resolver=_get_tool_resolver(fastmcp_app_name))
+    return data
+
+
+def _get_fastmcp_app_name(tool: Tool) -> str | None:
+    """Read the FastMCPApp name from a tool's metadata, if present."""
+    meta = tool.meta
+    if not meta:
+        return None
+    fastmcp_meta = meta.get("fastmcp")
+    if isinstance(fastmcp_meta, dict):
+        app = fastmcp_meta.get("app")
+        if isinstance(app, str):
+            return app
+    return None
+
+
+def _prefab_to_tool_result(app: Any, fastmcp_app_name: str | None = None) -> ToolResult:
+    """Convert a PrefabApp to a FastMCP ToolResult."""
+    return ToolResult(
+        content=[TextContent(type="text", text=_PREFAB_TEXT_FALLBACK)],
+        structured_content=_prefab_to_json(app, fastmcp_app_name=fastmcp_app_name),
+    )
+
+
+def _convert_to_content(
+    result: Any,
+) -> list[ContentBlock]:
+    """Convert a result to a sequence of content objects."""
+
+    if result is None:
+        return []
+
+    if not isinstance(result, (list | tuple)):
+        return [_convert_to_single_content_block(result)]
+
+    # If all items are ContentBlocks, return them as is
+    if all(isinstance(item, ContentBlock) for item in result):
+        return result
+
+    # If any item is a ContentBlock, convert non-ContentBlock items to TextContent
+    # without aggregating them
+    if any(isinstance(item, ContentBlock | Image | Audio | File) for item in result):
+        return [
+            _convert_to_single_content_block(item)
+            if not isinstance(item, ContentBlock)
+            else item
+            for item in result
+        ]
+    # If none of the items are ContentBlocks, aggregate all items into a single TextContent
+    return [TextContent(type="text", text=default_serializer(result))]
+
+
+__all__ = ["Tool", "ToolResult"]
diff --git a/fastmcp_slim/fastmcp/tools/function_parsing.py b/fastmcp_slim/fastmcp/tools/function_parsing.py
new file mode 100644
index 0000000..9f653a3
--- /dev/null
+++ b/fastmcp_slim/fastmcp/tools/function_parsing.py
@@ -0,0 +1,344 @@
+"""Function introspection and schema generation for FastMCP tools."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import types
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Annotated, Any, Generic, Union, get_args, get_origin, get_type_hints
+
+import mcp_types
+from pydantic import BaseModel, PydanticSchemaGenerationError
+from typing_extensions import TypeVar as TypeVarExt
+
+from fastmcp.tools.base import ToolResult, resolve_serialize_by_alias
+from fastmcp.utilities.docstring_parsing import ParsedDocstring, parse_docstring
+from fastmcp.utilities.json_schema import compress_schema
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import (
+    Audio,
+    File,
+    Image,
+    get_cached_typeadapter,
+    is_class_member_of_type,
+    replace_type,
+)
+
+try:
+    from prefab_ui.app import PrefabApp as _PrefabApp
+    from prefab_ui.components.base import Component as _PrefabComponent
+
+    _PREFAB_TYPES: tuple[type, ...] = (_PrefabApp, _PrefabComponent)
+except ImportError:
+    _PREFAB_TYPES = ()
+
+
+def _contains_bytes_type(tp: Any) -> bool:
+    """Check if *tp* is or contains bytes, recursing through unions and Annotated."""
+    if tp is bytes:
+        return True
+    origin = get_origin(tp)
+    if origin is Union or origin is types.UnionType or origin is Annotated:
+        return any(_contains_bytes_type(a) for a in get_args(tp))
+    return False
+
+
+def _contains_prefab_type(tp: Any) -> bool:
+    """Check if *tp* is or contains a prefab type, recursing through unions and Annotated."""
+    if isinstance(tp, type) and issubclass(tp, _PREFAB_TYPES):
+        return True
+    origin = get_origin(tp)
+    if origin is Union or origin is types.UnionType or origin is Annotated:
+        return any(_contains_prefab_type(a) for a in get_args(tp))
+    return False
+
+
+def _unwrap_model(tp: Any) -> type[BaseModel] | None:
+    """Unwrap ``Annotated`` and return the underlying Pydantic model, if any."""
+    if get_origin(tp) is Annotated:
+        return _unwrap_model(get_args(tp)[0])
+    if isinstance(tp, type) and issubclass(tp, BaseModel):
+        return tp
+    return None
+
+
+def _resolve_output_by_alias(tp: Any) -> bool:
+    """Resolve ``by_alias`` for the output schema of return type *tp*.
+
+    Unwraps ``Annotated`` and ``Optional``/``Union`` wrappers to find the
+    underlying Pydantic model so the generated schema honors the model's
+    ``serialize_by_alias`` config — keeping it consistent with how the runtime
+    result is serialized. Containers (``list[Model]`` etc.) are not unwrapped:
+    their schema keeps the default, matching the runtime path which only
+    special-cases a directly-returned model.
+
+    Known limitation: a single schema is generated with one ``by_alias`` value,
+    while the runtime resolves the alias mode per returned value. They cannot
+    diverge for a plain single-model return, but a union return can produce more
+    than one runtime alias mode that no single schema can describe:
+
+    - distinct models with *conflicting* ``serialize_by_alias`` (e.g. ``A | B``
+      where ``A`` opts out but ``B`` opts in), and
+    - a model arm alongside a container arm (e.g. ``Model | list[Model]``):
+      a directly-returned model honors its config, but a returned ``list`` is
+      serialized with the default alias mode, so the two variants disagree.
+
+    Pydantic's schema generator does not consult per-model ``serialize_by_alias``
+    and the runtime does not recurse into containers, so honoring every variant
+    would require per-arm schema assembly. This is an accepted edge; single-model
+    returns and unions whose arms all resolve to the same mode are consistent.
+    """
+    origin = get_origin(tp)
+    if origin is Annotated:
+        return _resolve_output_by_alias(get_args(tp)[0])
+    if origin is Union or origin is types.UnionType:
+        for arg in get_args(tp):
+            model = _unwrap_model(arg)
+            if model is not None:
+                return resolve_serialize_by_alias(model)
+        return True
+    return resolve_serialize_by_alias(tp)
+
+
+T = TypeVarExt("T", default=Any)
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class _WrappedResult(Generic[T]):
+    result: T
+
+
+class _UnserializableType:
+    pass
+
+
+def _is_object_schema(
+    schema: dict[str, Any],
+    *,
+    _root_schema: dict[str, Any] | None = None,
+    _seen_refs: set[str] | None = None,
+) -> bool:
+    """Check if a JSON schema represents an object type."""
+    root_schema = _root_schema or schema
+    seen_refs = _seen_refs or set()
+
+    # Direct object type
+    if schema.get("type") == "object":
+        return True
+
+    # Schema with properties but no explicit type is treated as object
+    if "properties" in schema:
+        return True
+
+    # Resolve local $ref definitions and recurse into the target schema.
+    ref = schema.get("$ref")
+    if not isinstance(ref, str) or not ref.startswith("#/"):
+        return False
+
+    if ref in seen_refs:
+        return False
+
+    # Walk the JSON Pointer path from the root schema, unescaping each
+    # token per RFC 6901 (~1 → /, ~0 → ~).
+    pointer = ref.removeprefix("#/")
+    segments = pointer.split("/")
+    target: Any = root_schema
+    for segment in segments:
+        unescaped = segment.replace("~1", "/").replace("~0", "~")
+        if not isinstance(target, dict) or unescaped not in target:
+            return False
+        target = target[unescaped]
+
+    target_schema = target
+    if not isinstance(target_schema, dict):
+        return False
+
+    return _is_object_schema(
+        target_schema,
+        _root_schema=root_schema,
+        _seen_refs=seen_refs | {ref},
+    )
+
+
+@dataclass
+class ParsedFunction:
+    fn: Callable[..., Any]
+    name: str
+    description: str | None
+    input_schema: dict[str, Any]
+    output_schema: dict[str, Any] | None
+    return_type: Any = None
+
+    @classmethod
+    def from_function(
+        cls,
+        fn: Callable[..., Any],
+        validate: bool = True,
+        wrap_non_object_output_schema: bool = True,
+    ) -> ParsedFunction:
+        if validate:
+            sig = inspect.signature(fn)
+            # Reject functions with *args or **kwargs
+            for param in sig.parameters.values():
+                if param.kind == inspect.Parameter.VAR_POSITIONAL:
+                    raise ValueError("Functions with *args are not supported as tools")
+                if param.kind == inspect.Parameter.VAR_KEYWORD:
+                    raise ValueError(
+                        "Functions with **kwargs are not supported as tools"
+                    )
+
+        # collect name and description before we potentially modify the function
+        fn_name = getattr(fn, "__name__", None) or fn.__class__.__name__
+        outer_docstring = parse_docstring(fn)
+
+        # if the fn is a callable class, we need to get the __call__ method from here out
+        if not inspect.isroutine(fn) and not isinstance(fn, functools.partial):
+            fn = fn.__call__
+        # if the fn is a staticmethod, we need to work with the underlying function
+        if isinstance(fn, staticmethod):
+            fn = fn.__func__
+
+        # For callable classes, parameter descriptions must come from
+        # __call__'s docstring — where the exposed parameters are actually
+        # declared. The class docstring's Args section, if any, typically
+        # describes __init__, so falling back to it would risk injecting
+        # constructor docs into __call__'s schema on overlapping names.
+        # The description, however, comes from the class docstring (which
+        # describes what the tool IS) when present.
+        inner_docstring = parse_docstring(fn)
+        parsed_docstring = ParsedDocstring(
+            description=outer_docstring.description or inner_docstring.description,
+            parameters=inner_docstring.parameters,
+        )
+
+        # Transform Context type annotations to Depends() for unified DI
+        from fastmcp.server.dependencies import (
+            transform_context_annotations,
+            without_injected_parameters,
+        )
+
+        fn = transform_context_annotations(fn)
+
+        # Handle injected parameters (Context, Docket dependencies)
+        wrapper_fn = without_injected_parameters(fn)
+
+        input_type_adapter = get_cached_typeadapter(wrapper_fn)
+        input_schema = input_type_adapter.json_schema()
+
+        input_schema = compress_schema(input_schema, prune_titles=True)
+
+        # Inject parameter descriptions from the docstring into the schema.
+        # Explicit annotations (Field(description=...), Annotated[x, "..."])
+        # already have a "description" key and take precedence.
+        if parsed_docstring.parameters:
+            properties = input_schema.get("properties", {})
+            for param_name, param_desc in parsed_docstring.parameters.items():
+                if (
+                    param_name in properties
+                    and "description" not in properties[param_name]
+                ):
+                    properties[param_name]["description"] = param_desc
+
+        output_schema = None
+        # Get the return annotation from the signature
+        sig = inspect.signature(fn)
+        output_type = sig.return_annotation
+
+        # If the annotation is a string (from __future__ annotations), resolve it
+        if isinstance(output_type, str):
+            try:
+                # Use get_type_hints to resolve the return type
+                # include_extras=True preserves Annotated metadata
+                type_hints = get_type_hints(fn, include_extras=True)
+                output_type = type_hints.get("return", output_type)
+            except Exception as e:
+                # If resolution fails, keep the string annotation
+                logger.debug("Failed to resolve type hint for return annotation: %s", e)
+
+        # Save original for return_type before any schema-related replacement
+        original_output_type = output_type
+
+        if output_type not in (inspect._empty, None, Any, ...):
+            # bytes can't be represented as structured JSON output — skip schema
+            if _contains_bytes_type(output_type):
+                output_type = _UnserializableType
+
+            # Prefab component subclasses (Column, Card, etc.) shouldn't
+            # produce output schemas — replace_type only does exact matching,
+            # so we handle subclass matching explicitly here.  We also need
+            # to handle composite types like ``Column | None`` and
+            # ``Annotated[PrefabApp, ...]`` by recursing into their args.
+            if _PREFAB_TYPES and _contains_prefab_type(output_type):
+                output_type = _UnserializableType
+
+            # ToolResult subclasses should suppress schema generation just
+            # like ToolResult itself — replace_type only does exact matching.
+            if is_class_member_of_type(output_type, ToolResult):
+                output_type = _UnserializableType
+
+            # there are a variety of types that we don't want to attempt to
+            # serialize because they are either used by FastMCP internally,
+            # or are MCP content types that explicitly don't form structured
+            # content. By replacing them with an explicitly unserializable type,
+            # we ensure that no output schema is automatically generated.
+            clean_output_type = replace_type(
+                output_type,
+                dict.fromkeys(
+                    (
+                        Image,
+                        Audio,
+                        File,
+                        ToolResult,
+                        mcp_types.TextContent,
+                        mcp_types.ImageContent,
+                        mcp_types.AudioContent,
+                        mcp_types.ResourceLink,
+                        mcp_types.EmbeddedResource,
+                        *_PREFAB_TYPES,
+                    ),
+                    _UnserializableType,
+                ),
+            )
+
+            try:
+                # Honor the model's serialize_by_alias config so the schema's
+                # field names match the serialized result (see base.py).
+                by_alias = _resolve_output_by_alias(clean_output_type)
+                type_adapter = get_cached_typeadapter(clean_output_type)
+                base_schema = type_adapter.json_schema(
+                    mode="serialization", by_alias=by_alias
+                )
+
+                # Generate schema for wrapped type if it's non-object
+                # because MCP requires that output schemas are objects
+                # Check if schema is an object type, resolving $ref references
+                # (self-referencing types use $ref at root level)
+                if wrap_non_object_output_schema and not _is_object_schema(base_schema):
+                    # Use the wrapped result schema directly
+                    wrapped_type = _WrappedResult[clean_output_type]
+                    wrapped_adapter = get_cached_typeadapter(wrapped_type)
+                    output_schema = wrapped_adapter.json_schema(
+                        mode="serialization", by_alias=by_alias
+                    )
+                    output_schema["x-fastmcp-wrap-result"] = True
+                else:
+                    output_schema = base_schema
+
+                output_schema = compress_schema(output_schema, prune_titles=True)
+
+            except PydanticSchemaGenerationError as e:
+                if "_UnserializableType" not in str(e):
+                    logger.debug(f"Unable to generate schema for type {output_type!r}")
+
+        return cls(
+            fn=fn,
+            name=fn_name,
+            description=parsed_docstring.description,
+            input_schema=input_schema,
+            output_schema=output_schema or None,
+            return_type=original_output_type,
+        )
diff --git a/fastmcp_slim/fastmcp/tools/function_tool.py b/fastmcp_slim/fastmcp/tools/function_tool.py
new file mode 100644
index 0000000..dd4c236
--- /dev/null
+++ b/fastmcp_slim/fastmcp/tools/function_tool.py
@@ -0,0 +1,681 @@
+"""Standalone @tool decorator for FastMCP."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from functools import lru_cache
+from types import MethodType
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    Literal,
+    Protocol,
+    TypeVar,
+    cast,
+    get_type_hints,
+    overload,
+    runtime_checkable,
+)
+
+import anyio
+from mcp.shared.exceptions import MCPError
+from mcp_types import Icon, ToolAnnotations
+from pydantic import Field, TypeAdapter
+from pydantic import ValidationError as PydanticValidationError
+from pydantic.json_schema import SkipJsonSchema
+
+from fastmcp.decorators import get_fastmcp_meta
+from fastmcp.exceptions import ValidationError
+from fastmcp.tools.base import (
+    Tool,
+    ToolResult,
+)
+from fastmcp.tools.function_parsing import ParsedFunction, _is_object_schema
+from fastmcp.utilities.async_utils import (
+    call_sync_fn_in_threadpool,
+    is_coroutine_function,
+)
+from fastmcp.utilities.authorization import AuthCheck
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.tasks import TaskConfig
+from fastmcp.utilities.types import (
+    NotSet,
+    NotSetT,
+    get_cached_typeadapter,
+)
+
+logger = get_logger(__name__)
+
+if TYPE_CHECKING:
+    from docket import Docket
+    from docket.execution import Execution
+
+
+class _ToolBodyError(Exception):
+    """Marks a ``pydantic.ValidationError`` raised while executing a tool's body.
+
+    Pydantic validates a tool's arguments *before* invoking the body, so a bare
+    ``pydantic.ValidationError`` surfacing from the call adapter is unambiguously
+    an argument-validation failure (a bad call). Errors a tool raises from its
+    own body — e.g. constructing a model from upstream data — are a different
+    class of problem (a server-side bug) that must not be reclassified as a bad
+    call. We wrap the body so those are tagged and can be told apart. See #4128.
+    """
+
+
+@lru_cache(maxsize=5000)
+def _wrap_body_errors(fn: Callable[..., Any]) -> Callable[..., Any]:
+    """Wrap ``fn`` so a ``pydantic.ValidationError`` raised by its body is
+    re-raised as ``_ToolBodyError``.
+
+    The wrapper preserves ``fn``'s signature and annotations so the cached
+    ``TypeAdapter`` validates arguments identically — only body execution is
+    affected. Argument validation happens before the wrapper is called, so it
+    keeps raising a bare ``pydantic.ValidationError``.
+    """
+    if is_coroutine_function(fn):
+
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return await fn(*args, **kwargs)
+            except PydanticValidationError as e:
+                raise _ToolBodyError from e
+    else:
+
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return fn(*args, **kwargs)
+            except PydanticValidationError as e:
+                raise _ToolBodyError from e
+
+    # Mirror the original callable so TypeAdapter builds the identical schema and
+    # binds arguments the same way. Annotations must cover every signature
+    # parameter or pydantic's call-schema generation raises KeyError — so prefer
+    # resolved type hints (handles string/forward refs) but fall back to the
+    # signature's own annotations, which is the only source for callables like
+    # functools.partial that carry no __annotations__.
+    try:
+        resolved_hints = get_type_hints(fn, include_extras=True)
+    except Exception:
+        resolved_hints = {}
+    sig = inspect.signature(fn)
+    annotations: dict[str, Any] = {}
+    for param_name, param in sig.parameters.items():
+        if param_name in resolved_hints:
+            annotations[param_name] = resolved_hints[param_name]
+        elif param.annotation is not inspect.Parameter.empty:
+            annotations[param_name] = param.annotation
+    if "return" in resolved_hints:
+        annotations["return"] = resolved_hints["return"]
+    elif sig.return_annotation is not inspect.Signature.empty:
+        annotations["return"] = sig.return_annotation
+
+    wrapper.__signature__ = sig  # type: ignore[attr-defined]  # ty: ignore[invalid-assignment]
+    wrapper.__annotations__ = annotations
+    wrapper.__name__ = getattr(fn, "__name__", "wrapper")
+    wrapper.__doc__ = getattr(fn, "__doc__", None)
+    wrapper.__module__ = getattr(fn, "__module__", wrapper.__module__)
+    wrapper.__qualname__ = getattr(fn, "__qualname__", wrapper.__qualname__)
+    return wrapper
+
+
+def _strict_input_validation() -> bool:
+    """Whether the running server enforces strict argument validation.
+
+    Reads ``strict_input_validation`` off the active request's ``FastMCP``
+    instance. Returns ``False`` outside a request context (e.g. a tool invoked
+    directly in tests), preserving the default coercing behavior.
+    """
+    from fastmcp.server.context import _current_context
+
+    context = _current_context.get(None)
+    if context is None:
+        return False
+    return context.fastmcp.strict_input_validation
+
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@runtime_checkable
+class DecoratedTool(Protocol):
+    """Protocol for functions decorated with @tool."""
+
+    __fastmcp__: ToolMeta
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any: ...
+
+
+@dataclass(frozen=True, kw_only=True)
+class ToolMeta:
+    """Metadata attached to functions by the @tool decorator."""
+
+    type: Literal["tool"] = field(default="tool", init=False)
+    name: str | None = None
+    version: str | int | None = None
+    title: str | None = None
+    description: str | None = None
+    icons: list[Icon] | None = None
+    tags: set[str] | None = None
+    output_schema: dict[str, Any] | NotSetT | None = NotSet
+    annotations: ToolAnnotations | None = None
+    meta: dict[str, Any] | None = None
+    app: Any = None
+    task: bool | TaskConfig | None = None
+    timeout: float | None = None
+    auth: AuthCheck | list[AuthCheck] | None = None
+    enabled: bool = True
+    run_in_thread: bool = True
+
+
+def _resolve_param_hints(fn: Callable[..., Any]) -> dict[str, Any]:
+    """Resolve a callable's parameter type hints, tolerating partials.
+
+    ``get_type_hints`` rejects ``functools.partial`` objects (and other
+    non-function callables), which the synchronous TypeAdapter path handles
+    natively. For those, resolve hints against the underlying function and keep
+    only the parameters that remain in the partially-bound signature.
+    """
+    try:
+        return get_type_hints(fn, include_extras=True)
+    except TypeError:
+        target = fn
+        while isinstance(target, functools.partial):
+            target = target.func
+        try:
+            resolved = get_type_hints(target, include_extras=True)
+        except TypeError:
+            return {}
+        return {
+            name: resolved[name]
+            for name in inspect.signature(fn).parameters
+            if name in resolved
+        }
+
+
+class FunctionTool(Tool):
+    fn: SkipJsonSchema[Callable[..., Any]]
+    return_type: Annotated[SkipJsonSchema[Any], Field(exclude=True)] = None
+    run_in_thread: Annotated[
+        bool,
+        Field(
+            description=(
+                "Applies to sync tool functions only. When True (default), sync "
+                "functions are dispatched to a worker thread so they don't block "
+                "the event loop. Set to False to run the sync function inline on "
+                "the event loop thread — useful for libraries with thread "
+                "affinity (e.g. Windows COM, tkinter). Ignored for async functions, "
+                "which always run on the event loop. Cannot be combined with "
+                "`timeout` on a sync function: inline calls have no cancellation "
+                "checkpoints, so the timeout would be a silent no-op."
+            )
+        ),
+    ] = True
+
+    @classmethod
+    def from_function(
+        cls,
+        fn: Callable[..., Any],
+        *,
+        metadata: ToolMeta | None = None,
+        # Keep individual params for backwards compat
+        name: str | None = None,
+        version: str | int | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[Icon] | None = None,
+        tags: set[str] | None = None,
+        annotations: ToolAnnotations | None = None,
+        output_schema: dict[str, Any] | NotSetT | None = NotSet,
+        meta: dict[str, Any] | None = None,
+        task: bool | TaskConfig | None = None,
+        timeout: float | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+        run_in_thread: bool | None = None,
+    ) -> FunctionTool:
+        """Create a FunctionTool from a function.
+
+        Args:
+            fn: The function to wrap
+            metadata: ToolMeta object with all configuration. If provided,
+                individual parameters must not be passed.
+            name, title, etc.: Individual parameters for backwards compatibility.
+                Cannot be used together with metadata parameter.
+        """
+        # Check mutual exclusion
+        individual_params_provided = (
+            any(
+                x is not None and x is not NotSet
+                for x in [
+                    name,
+                    version,
+                    title,
+                    description,
+                    icons,
+                    tags,
+                    annotations,
+                    meta,
+                    task,
+                    timeout,
+                    auth,
+                    run_in_thread,
+                ]
+            )
+            or output_schema is not NotSet
+        )
+
+        if metadata is not None and individual_params_provided:
+            raise TypeError(
+                "Cannot pass both 'metadata' and individual parameters to from_function(). "
+                "Use metadata alone or individual parameters alone."
+            )
+
+        if metadata is None and not individual_params_provided:
+            fmeta = get_fastmcp_meta(fn)
+            if isinstance(fmeta, ToolMeta):
+                metadata = fmeta
+
+        # Build metadata from kwargs if not provided
+        if metadata is None:
+            metadata = ToolMeta(
+                name=name,
+                version=version,
+                title=title,
+                description=description,
+                icons=icons,
+                tags=tags,
+                output_schema=output_schema,
+                annotations=annotations,
+                meta=meta,
+                task=task,
+                timeout=timeout,
+                auth=auth,
+                run_in_thread=True if run_in_thread is None else run_in_thread,
+            )
+
+        parsed_fn = ParsedFunction.from_function(fn)
+        func_name = metadata.name or parsed_fn.name
+
+        if func_name == "<lambda>":
+            raise ValueError("You must provide a name for lambda functions")
+
+        # Inline sync execution has no cancellation checkpoints, so
+        # anyio.fail_after cannot preempt the call — the timeout would be
+        # silently ignored. Reject the combination so users make an
+        # explicit choice. Async generators are async even though
+        # is_coroutine_function returns False for them; the generator's
+        # iteration has checkpoints, so timeout enforcement still works.
+        if (
+            metadata.timeout is not None
+            and not metadata.run_in_thread
+            and not is_coroutine_function(fn)
+            and not inspect.isasyncgenfunction(fn)
+        ):
+            raise ValueError(
+                f"Tool {func_name!r}: timeout cannot be enforced when "
+                "run_in_thread=False on a sync function. Inline execution has "
+                "no cancellation checkpoints, so the timeout would be a no-op. "
+                "Either drop the timeout or remove run_in_thread=False and "
+                "accept worker-thread dispatch."
+            )
+
+        # Normalize task to TaskConfig
+        task_value = metadata.task
+        if task_value is None:
+            task_config = TaskConfig(mode="forbidden")
+        elif isinstance(task_value, bool):
+            task_config = TaskConfig.from_bool(task_value)
+        else:
+            task_config = task_value
+        task_config.validate_function(fn, func_name)
+
+        # Handle output_schema
+        if isinstance(metadata.output_schema, NotSetT):
+            final_output_schema = parsed_fn.output_schema
+        else:
+            final_output_schema = metadata.output_schema
+
+        if final_output_schema is not None and isinstance(final_output_schema, dict):
+            if not _is_object_schema(final_output_schema):
+                raise ValueError(
+                    f"Output schemas must represent object types due to MCP spec limitations. "
+                    f"Received: {final_output_schema!r}"
+                )
+
+        return cls(
+            fn=parsed_fn.fn,
+            return_type=parsed_fn.return_type,
+            name=metadata.name or parsed_fn.name,
+            version=str(metadata.version) if metadata.version is not None else None,
+            title=metadata.title,
+            description=metadata.description
+            if metadata.description is not None
+            else parsed_fn.description,
+            icons=metadata.icons,
+            parameters=parsed_fn.input_schema,
+            output_schema=final_output_schema,
+            annotations=metadata.annotations,
+            tags=metadata.tags or set(),
+            meta=metadata.meta,
+            task_config=task_config,
+            timeout=metadata.timeout,
+            auth=metadata.auth,
+            run_in_thread=metadata.run_in_thread,
+        )
+
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
+        """Run the tool with arguments."""
+        from fastmcp.server.dependencies import without_injected_parameters
+
+        wrapper_fn = without_injected_parameters(
+            self.fn, run_in_thread=self.run_in_thread
+        )
+        # Tag pydantic errors raised by the body so they can be distinguished
+        # from argument-validation errors (which pydantic raises first). See #4128.
+        exec_fn = _wrap_body_errors(wrapper_fn)
+        type_adapter = get_cached_typeadapter(exec_fn)
+        exec_is_async = is_coroutine_function(wrapper_fn)
+        strict = _strict_input_validation()
+
+        try:
+            if self.timeout is not None:
+                try:
+                    with anyio.fail_after(self.timeout):
+                        result = await self._execute(
+                            type_adapter, exec_is_async, arguments, strict=strict
+                        )
+                except TimeoutError:
+                    logger.warning(
+                        f"Tool '{self.name}' timed out after {self.timeout}s. "
+                        f"Consider using task=True for long-running operations. "
+                        f"See https://gofastmcp.com/servers/tasks"
+                    )
+                    raise MCPError(
+                        code=-32000,
+                        message=f"Tool '{self.name}' execution timed out after {self.timeout}s",
+                    ) from None
+            else:
+                result = await self._execute(
+                    type_adapter, exec_is_async, arguments, strict=strict
+                )
+        except PydanticValidationError as e:
+            # Body errors are re-raised as _ToolBodyError, so a bare pydantic
+            # ValidationError here is an argument-validation failure (a bad call).
+            # Convert it to fastmcp's ValidationError so the middleware chain and
+            # downstream error taxonomy (e.g. Sentry filters) can treat it as a
+            # client error rather than a server bug.
+            raise ValidationError(str(e), log_level=logging.WARNING) from e
+        except _ToolBodyError as e:
+            # The tool's own body raised a pydantic ValidationError. Surface the
+            # original so it is treated as a server-side error, hiding the
+            # internal sentinel while preserving the error's own chained cause.
+            original = e.__cause__
+            assert original is not None
+            raise original from original.__cause__
+
+        return self.convert_result(result)
+
+    async def _execute(
+        self,
+        type_adapter: TypeAdapter[Any],
+        exec_is_async: bool,
+        arguments: dict[str, Any],
+        *,
+        strict: bool = False,
+    ) -> Any:
+        """Validate arguments and execute the tool body.
+
+        Argument validation runs first and raises a bare
+        ``pydantic.ValidationError`` on bad input. Body execution (awaiting the
+        result and materializing generators) is wrapped so any pydantic error it
+        raises is tagged as ``_ToolBodyError``.
+
+        When ``strict`` is set (server-level ``strict_input_validation``),
+        pydantic validates in strict mode, so lax coercions such as the JSON
+        string ``"10"`` into an ``int`` are rejected rather than coerced.
+        """
+        # Combining timeout with run_in_thread=False on a sync function is
+        # rejected at registration (see FunctionTool.from_function), so this only
+        # needs to handle async and threadpool-sync under a timeout.
+        if exec_is_async:
+            # Argument validation is synchronous; the body runs on await below.
+            result = type_adapter.validate_python(arguments, strict=strict)
+        elif self.run_in_thread:
+            # Sync function: run in threadpool to avoid blocking the event loop.
+            result = await call_sync_fn_in_threadpool(
+                type_adapter.validate_python, arguments, strict=strict
+            )
+        else:
+            result = type_adapter.validate_python(arguments, strict=strict)
+
+        try:
+            if inspect.isawaitable(result):
+                result = await result
+            # Materialize generators (here, so slow generators are still bound by
+            # any configured timeout scope).
+            return await self._materialize_generator(result)
+        except PydanticValidationError as e:
+            # A pydantic error from awaiting the result or materializing a
+            # generator is body execution, not argument validation.
+            raise _ToolBodyError from e
+
+    @staticmethod
+    async def _materialize_generator(result: Any) -> Any:
+        """Consume generators/async generators into lists.
+
+        Without this, async generators pass through as objects (repr string),
+        and sync generators get consumed during text serialization but are
+        exhausted by the time structured content is built.
+        """
+        if inspect.isasyncgen(result):
+            return [item async for item in result]
+        if inspect.isgenerator(result):
+            return list(result)
+        return result
+
+    def register_with_docket(self, docket: Docket) -> None:
+        """Register this tool with docket for background execution.
+
+        Registers the raw function so Docket sees and resolves ALL
+        dependencies — both FastMCP's (CurrentContext, Progress) and
+        Docket-native ones (Retry, Timeout, ConcurrencyLimit).
+        """
+        if not self.task_config.supports_tasks():
+            return
+        docket.register(self.fn, names=[self.key])
+
+    async def add_to_docket(
+        self,
+        docket: Docket,
+        arguments: dict[str, Any],
+        *,
+        fn_key: str | None = None,
+        task_key: str | None = None,
+        **kwargs: Any,
+    ) -> Execution:
+        """Schedule this tool for background execution via docket.
+
+        FunctionTool splats the arguments dict since .fn expects **kwargs.
+
+        Args:
+            docket: The Docket instance
+            arguments: Tool arguments
+            fn_key: Function lookup key in Docket registry (defaults to self.key)
+            task_key: Redis storage key for the result
+            **kwargs: Additional kwargs passed to docket.add()
+        """
+        lookup_key = fn_key or self.key
+        if task_key:
+            kwargs["key"] = task_key
+        return await docket.add(lookup_key, **kwargs)(**arguments)
+
+    def coerce_task_arguments(
+        self, arguments: dict[str, Any], *, strict: bool = False
+    ) -> dict[str, Any]:
+        """Validate client arguments against their declared parameter types.
+
+        The synchronous ``run()`` path validates arguments through the
+        function's Pydantic TypeAdapter, so a parameter typed as a model
+        arrives as a model instance. The task path hands the raw arguments to
+        Docket, which binds them to the function signature without coercion —
+        so without this a model-typed parameter would reach the function as a
+        raw dict (#4349). ``submit_to_docket`` calls this up front so coerced
+        values are what get queued, and validation errors surface before any
+        task state is created. Coerced values survive the trip to the worker
+        because Docket serializes task arguments with cloudpickle.
+
+        ``strict`` mirrors the synchronous path's ``strict_input_validation``
+        handling: when set, arguments are validated in strict mode so lax
+        coercions (e.g. the string ``"1"`` into an ``int``) are rejected at
+        submission rather than silently coerced and queued.
+
+        Injected dependency parameters (Context, Depends()) are excluded via
+        the same wrapper used by the synchronous path, so only client-supplied
+        arguments are coerced and Docket's dependency resolution is untouched.
+        """
+        from fastmcp.server.dependencies import without_injected_parameters
+
+        wrapper_fn = without_injected_parameters(
+            self.fn, run_in_thread=self.run_in_thread
+        )
+        hints = _resolve_param_hints(wrapper_fn)
+
+        coerced = dict(arguments)
+        for name, value in arguments.items():
+            annotation = hints.get(name)
+            if annotation is None:
+                continue
+            adapter = get_cached_typeadapter(annotation)
+            try:
+                coerced[name] = adapter.validate_python(value, strict=strict)
+            except PydanticValidationError as e:
+                # Argument coercion failure on the task path is a bad call, just
+                # like the synchronous path — surface it as fastmcp's
+                # ValidationError so it is classified consistently (see #4128).
+                raise ValidationError(str(e), log_level=logging.WARNING) from e
+        return coerced
+
+
+@overload
+def tool(fn: F) -> F: ...
+@overload
+def tool(
+    name_or_fn: str,
+    *,
+    version: str | int | None = None,
+    title: str | None = None,
+    description: str | None = None,
+    icons: list[Icon] | None = None,
+    tags: set[str] | None = None,
+    output_schema: dict[str, Any] | NotSetT | None = NotSet,
+    annotations: ToolAnnotations | dict[str, Any] | None = None,
+    meta: dict[str, Any] | None = None,
+    task: bool | TaskConfig | None = None,
+    timeout: float | None = None,
+    auth: AuthCheck | list[AuthCheck] | None = None,
+    run_in_thread: bool = True,
+) -> Callable[[F], F]: ...
+@overload
+def tool(
+    name_or_fn: None = None,
+    *,
+    name: str | None = None,
+    version: str | int | None = None,
+    title: str | None = None,
+    description: str | None = None,
+    icons: list[Icon] | None = None,
+    tags: set[str] | None = None,
+    output_schema: dict[str, Any] | NotSetT | None = NotSet,
+    annotations: ToolAnnotations | dict[str, Any] | None = None,
+    meta: dict[str, Any] | None = None,
+    task: bool | TaskConfig | None = None,
+    timeout: float | None = None,
+    auth: AuthCheck | list[AuthCheck] | None = None,
+    run_in_thread: bool = True,
+) -> Callable[[F], F]: ...
+
+
+def tool(
+    name_or_fn: str | Callable[..., Any] | None = None,
+    *,
+    name: str | None = None,
+    version: str | int | None = None,
+    title: str | None = None,
+    description: str | None = None,
+    icons: list[Icon] | None = None,
+    tags: set[str] | None = None,
+    output_schema: dict[str, Any] | NotSetT | None = NotSet,
+    annotations: ToolAnnotations | dict[str, Any] | None = None,
+    meta: dict[str, Any] | None = None,
+    task: bool | TaskConfig | None = None,
+    timeout: float | None = None,
+    auth: AuthCheck | list[AuthCheck] | None = None,
+    run_in_thread: bool = True,
+) -> Any:
+    """Standalone decorator to mark a function as an MCP tool.
+
+    Returns the original function with metadata attached. Register with a server
+    using mcp.add_tool().
+
+    Args:
+        run_in_thread: Applies to sync tool functions only. When True (default),
+            the sync function is dispatched to a worker thread so it does not
+            block the event loop. Set to False to run the function inline on the
+            event loop thread — useful for libraries with thread affinity
+            (e.g. Windows COM via `uiautomation`/`comtypes`/`pywin32`, `tkinter`,
+            some GPU/driver bindings). Ignored for async functions. Cannot be
+            combined with `timeout` on a sync function: inline calls have no
+            cancellation checkpoints, so the timeout would be a silent no-op.
+    """
+    if isinstance(annotations, dict):
+        annotations = ToolAnnotations(**annotations)
+
+    if isinstance(name_or_fn, classmethod):
+        raise TypeError(
+            "To decorate a classmethod, use @classmethod above @tool. "
+            "See https://gofastmcp.com/servers/tools#using-with-methods"
+        )
+
+    def attach_metadata(fn: F, tool_name: str | None) -> F:
+        metadata = ToolMeta(
+            name=tool_name,
+            version=version,
+            title=title,
+            description=description,
+            icons=icons,
+            tags=tags,
+            output_schema=output_schema,
+            annotations=annotations,
+            meta=meta,
+            task=task,
+            timeout=timeout,
+            auth=auth,
+            run_in_thread=run_in_thread,
+        )
+        target = fn.__func__ if isinstance(fn, staticmethod | MethodType) else fn
+        cast(Any, target).__fastmcp__ = metadata
+        return fn
+
+    def decorator(fn: F, tool_name: str | None) -> F:
+        return attach_metadata(fn, tool_name)
+
+    if inspect.isroutine(name_or_fn):
+        return decorator(name_or_fn, name)
+    elif isinstance(name_or_fn, str):
+        if name is not None:
+            raise TypeError("Cannot specify name both as first argument and keyword")
+        tool_name = name_or_fn
+    elif name_or_fn is None:
+        tool_name = name
+    else:
+        raise TypeError(f"Invalid first argument: {type(name_or_fn)}")
+
+    def wrapper(fn: F) -> F:
+        return decorator(fn, tool_name)
+
+    return wrapper
diff --git a/fastmcp_slim/fastmcp/tools/tool_transform.py b/fastmcp_slim/fastmcp/tools/tool_transform.py
new file mode 100644
index 0000000..425a970
--- /dev/null
+++ b/fastmcp_slim/fastmcp/tools/tool_transform.py
@@ -0,0 +1,1018 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from contextvars import ContextVar
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Annotated, Any, Literal, cast
+
+import pydantic_core
+from mcp_types import ToolAnnotations
+from pydantic import ConfigDict
+from pydantic.fields import Field
+from pydantic.functional_validators import BeforeValidator
+from pydantic.json_schema import SkipJsonSchema
+
+from fastmcp.tools.base import (
+    Tool,
+    ToolResult,
+    _convert_to_content,
+    resolve_serialize_by_alias,
+)
+from fastmcp.tools.function_parsing import ParsedFunction
+from fastmcp.utilities.async_utils import (
+    call_sync_fn_in_threadpool,
+    is_coroutine_function,
+)
+from fastmcp.utilities.components import _convert_set_default_none
+from fastmcp.utilities.json_schema import compress_schema
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import (
+    FastMCPBaseModel,
+    NotSet,
+    NotSetT,
+    get_cached_typeadapter,
+    issubclass_safe,
+)
+
+logger = get_logger(__name__)
+
+
+# Context variable to store current transformed tool
+_current_tool: ContextVar[TransformedTool | None] = ContextVar(
+    "_current_tool", default=None
+)
+
+
+async def forward(**kwargs: Any) -> ToolResult:
+    """Forward to parent tool with argument transformation applied.
+
+    This function can only be called from within a transformed tool's custom
+    function. It applies argument transformation (renaming, validation) before
+    calling the parent tool.
+
+    For example, if the parent tool has args `x` and `y`, but the transformed
+    tool has args `a` and `b`, and an `transform_args` was provided that maps `x` to
+    `a` and `y` to `b`, then `forward(a=1, b=2)` will call the parent tool with
+    `x=1` and `y=2`.
+
+    Args:
+        **kwargs: Arguments to forward to the parent tool (using transformed names).
+
+    Returns:
+        The ToolResult from the parent tool execution.
+
+    Raises:
+        RuntimeError: If called outside a transformed tool context.
+        TypeError: If provided arguments don't match the transformed schema.
+    """
+    tool = _current_tool.get()
+    if tool is None:
+        raise RuntimeError("forward() can only be called within a transformed tool")
+
+    # Use the forwarding function that handles mapping
+    return await tool.forwarding_fn(**kwargs)
+
+
+async def forward_raw(**kwargs: Any) -> ToolResult:
+    """Forward directly to parent tool without transformation.
+
+    This function bypasses all argument transformation and validation, calling the parent
+    tool directly with the provided arguments. Use this when you need to call the parent
+    with its original parameter names and structure.
+
+    For example, if the parent tool has args `x` and `y`, then `forward_raw(x=1,
+    y=2)` will call the parent tool with `x=1` and `y=2`.
+
+    Args:
+        **kwargs: Arguments to pass directly to the parent tool (using original names).
+
+    Returns:
+        The ToolResult from the parent tool execution.
+
+    Raises:
+        RuntimeError: If called outside a transformed tool context.
+    """
+    tool = _current_tool.get()
+    if tool is None:
+        raise RuntimeError("forward_raw() can only be called within a transformed tool")
+
+    return await tool.parent_tool.run(kwargs)
+
+
+@dataclass(kw_only=True)
+class ArgTransform:
+    """Configuration for transforming a parent tool's argument.
+
+    This class allows fine-grained control over how individual arguments are transformed
+    when creating a new tool from an existing one. You can rename arguments, change their
+    descriptions, add default values, or hide them from clients while passing constants.
+
+    Attributes:
+        name: New name for the argument. Use None to keep original name, or ... for no change.
+        description: New description for the argument. Use None to remove description, or ... for no change.
+        default: New default value for the argument. Use ... for no change.
+        default_factory: Callable that returns a default value. Cannot be used with default.
+        type: New type for the argument. Use ... for no change.
+        hide: If True, hide this argument from clients but pass a constant value to parent.
+        required: If True, make argument required (remove default). Use ... for no change.
+        examples: Examples for the argument. Use ... for no change.
+
+    Examples:
+        Rename argument 'old_name' to 'new_name'
+        ```python
+        ArgTransform(name="new_name")
+        ```
+
+        Change description only
+        ```python
+        ArgTransform(description="Updated description")
+        ```
+
+        Add a default value (makes argument optional)
+        ```python
+        ArgTransform(default=42)
+        ```
+
+        Add a default factory (makes argument optional)
+        ```python
+        ArgTransform(default_factory=lambda: time.time())
+        ```
+
+        Change the type
+        ```python
+        ArgTransform(type=str)
+        ```
+
+        Hide the argument entirely from clients
+        ```python
+        ArgTransform(hide=True)
+        ```
+
+        Hide argument but pass a constant value to parent
+        ```python
+        ArgTransform(hide=True, default="constant_value")
+        ```
+
+        Hide argument but pass a factory-generated value to parent
+        ```python
+        ArgTransform(hide=True, default_factory=lambda: uuid.uuid4().hex)
+        ```
+
+        Make an optional parameter required (removes any default)
+        ```python
+        ArgTransform(required=True)
+        ```
+
+        Combine multiple transformations
+        ```python
+        ArgTransform(name="new_name", description="New desc", default=None, type=int)
+        ```
+    """
+
+    name: str | NotSetT = NotSet
+    description: str | NotSetT = NotSet
+    default: Any | NotSetT = NotSet
+    default_factory: Callable[[], Any] | NotSetT = NotSet
+    type: Any | NotSetT = NotSet
+    hide: bool = False
+    required: Literal[True] | NotSetT = NotSet
+    examples: Any | NotSetT = NotSet
+
+    def __post_init__(self):
+        """Validate that only one of default or default_factory is provided."""
+        has_default = self.default is not NotSet
+        has_factory = self.default_factory is not NotSet
+
+        if has_default and has_factory:
+            raise ValueError(
+                "Cannot specify both 'default' and 'default_factory' in ArgTransform. "
+                "Use either 'default' for a static value or 'default_factory' for a callable."
+            )
+
+        if has_factory and not self.hide:
+            raise ValueError(
+                "default_factory can only be used with hide=True. "
+                "Visible parameters must use static 'default' values since JSON schema "
+                "cannot represent dynamic factories."
+            )
+
+        if self.required is True and (has_default or has_factory):
+            raise ValueError(
+                "Cannot specify 'required=True' with 'default' or 'default_factory'. "
+                "Required parameters cannot have defaults."
+            )
+
+        if self.hide and self.required is True:
+            raise ValueError(
+                "Cannot specify both 'hide=True' and 'required=True'. "
+                "Hidden parameters cannot be required since clients cannot provide them."
+            )
+
+        if self.required is False:
+            raise ValueError(
+                "Cannot specify 'required=False'. Set a default value instead."
+            )
+
+
+class ArgTransformConfig(FastMCPBaseModel):
+    """A model for requesting a single argument transform."""
+
+    name: str | None = Field(default=None, description="The new name for the argument.")
+    description: str | None = Field(
+        default=None, description="The new description for the argument."
+    )
+    default: str | int | float | bool | None = Field(
+        default=None, description="The new default value for the argument."
+    )
+    hide: bool = Field(
+        default=False, description="Whether to hide the argument from the tool."
+    )
+    required: Literal[True] | None = Field(
+        default=None, description="Whether the argument is required."
+    )
+    examples: Any | None = Field(default=None, description="Examples of the argument.")
+
+    def to_arg_transform(self) -> ArgTransform:
+        """Convert the argument transform to a FastMCP argument transform."""
+
+        return ArgTransform(**self.model_dump(exclude_unset=True))  # pyright: ignore[reportAny]
+
+
+class TransformedTool(Tool):
+    """A tool that is transformed from another tool.
+
+    This class represents a tool that has been created by transforming another tool.
+    It supports argument renaming, schema modification, custom function injection,
+    structured output control, and provides context for the forward() and forward_raw() functions.
+
+    The transformation can be purely schema-based (argument renaming, dropping, etc.)
+    or can include a custom function that uses forward() to call the parent tool
+    with transformed arguments. Output schemas and structured outputs are automatically
+    inherited from the parent tool but can be overridden or disabled.
+
+    Attributes:
+        parent_tool: The original tool that this tool was transformed from.
+        fn: The function to execute when this tool is called (either the forwarding
+            function for pure transformations or a custom user function).
+        forwarding_fn: Internal function that handles argument transformation and
+            validation when forward() is called from custom functions.
+    """
+
+    model_config = ConfigDict(extra="allow", arbitrary_types_allowed=True)
+
+    parent_tool: SkipJsonSchema[Tool]
+    fn: SkipJsonSchema[Callable[..., Any]]
+    forwarding_fn: SkipJsonSchema[
+        Callable[..., Any]
+    ]  # Always present, handles arg transformation
+    transform_args: dict[str, ArgTransform]
+
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
+        """Run the tool with context set for forward() functions.
+
+        This method executes the tool's function while setting up the context
+        that allows forward() and forward_raw() to work correctly within custom
+        functions.
+
+        Args:
+            arguments: Dictionary of arguments to pass to the tool's function.
+
+        Returns:
+            ToolResult object containing content and optional structured output.
+        """
+
+        # Fill in missing arguments with schema defaults to ensure
+        # ArgTransform defaults take precedence over function defaults
+        arguments = arguments.copy()
+        properties = self.parameters.get("properties", {})
+
+        for param_name, param_schema in properties.items():
+            if param_name not in arguments and "default" in param_schema:
+                # Check if this parameter has a default_factory from transform_args
+                # We need to call the factory for each run, not use the cached schema value
+                has_factory_default = False
+                if self.transform_args:
+                    # Find the original parameter name that maps to this param_name
+                    for orig_name, transform in self.transform_args.items():
+                        transform_name = (
+                            transform.name
+                            if transform.name is not NotSet
+                            else orig_name
+                        )
+                        if (
+                            transform_name == param_name
+                            and transform.default_factory is not NotSet
+                        ):
+                            # Type check to ensure default_factory is callable
+                            if callable(transform.default_factory):
+                                arguments[param_name] = transform.default_factory()
+                                has_factory_default = True
+                                break
+
+                if not has_factory_default:
+                    arguments[param_name] = param_schema["default"]
+
+        token = _current_tool.set(self)
+        try:
+            if is_coroutine_function(self.fn):
+                result = await self.fn(**arguments)
+            else:
+                result = await call_sync_fn_in_threadpool(self.fn, **arguments)
+                if inspect.isawaitable(result):
+                    result = await result
+
+            # If transform function returns ToolResult, respect our output_schema setting
+            if isinstance(result, ToolResult):
+                if self.output_schema is None:
+                    return result
+                elif self.output_schema.get(
+                    "type"
+                ) != "object" and not self.output_schema.get("x-fastmcp-wrap-result"):
+                    # Non-object explicit schemas disable structured content
+                    return ToolResult(
+                        content=result.content,
+                        structured_content=None,
+                    )
+                else:
+                    return result
+
+            # Otherwise convert to content and create ToolResult with proper structured content
+
+            unstructured_result = _convert_to_content(result)
+
+            structured_output = None
+            # First handle structured content based on output schema, if any
+            if self.output_schema is not None:
+                if self.output_schema.get("x-fastmcp-wrap-result"):
+                    # Schema says wrap - serialize the inner result first (so its
+                    # serialize_by_alias config is honored) before nesting, since
+                    # wrapping in a dict would otherwise mask the model's config.
+                    structured_output = {
+                        "result": pydantic_core.to_jsonable_python(
+                            result, by_alias=resolve_serialize_by_alias(result)
+                        )
+                    }
+                else:
+                    structured_output = result
+            # If no output schema, try to serialize the result. If it is a dict, use
+            # it as structured content. If it is not a dict, ignore it.
+            if structured_output is None:
+                try:
+                    structured_output = pydantic_core.to_jsonable_python(
+                        result, by_alias=resolve_serialize_by_alias(result)
+                    )
+                    if not isinstance(structured_output, dict):
+                        structured_output = None
+                except Exception:
+                    pass
+
+            return ToolResult(
+                content=unstructured_result,
+                structured_content=structured_output,
+            )
+        finally:
+            _current_tool.reset(token)
+
+    @classmethod
+    def from_tool(
+        cls,
+        tool: Tool | Callable[..., Any],
+        name: str | None = None,
+        version: str | NotSetT | None = NotSet,
+        title: str | NotSetT | None = NotSet,
+        description: str | NotSetT | None = NotSet,
+        tags: set[str] | None = None,
+        transform_fn: Callable[..., Any] | None = None,
+        transform_args: dict[str, ArgTransform] | None = None,
+        annotations: ToolAnnotations | NotSetT | None = NotSet,
+        output_schema: dict[str, Any] | NotSetT | None = NotSet,
+        meta: dict[str, Any] | NotSetT | None = NotSet,
+    ) -> TransformedTool:
+        """Create a transformed tool from a parent tool.
+
+        Args:
+            tool: The parent tool to transform.
+            transform_fn: Optional custom function. Can use forward() and forward_raw()
+                to call the parent tool. Functions with **kwargs receive transformed
+                argument names.
+            name: New name for the tool. Defaults to parent tool's name.
+            version: New version for the tool. Defaults to parent tool's version.
+            title: New title for the tool. Defaults to parent tool's title.
+            transform_args: Optional transformations for parent tool arguments.
+                Only specified arguments are transformed, others pass through unchanged.
+                Use ArgTransform for rename, description, default, or hide operations.
+            description: New description. Defaults to parent's description.
+            tags: New tags. Defaults to parent's tags.
+            annotations: New annotations. Defaults to parent's annotations.
+            output_schema: Control output schema for structured outputs:
+                - None (default): Inherit from transform_fn if available, then parent tool
+                - dict: Use custom output schema
+            meta: Control meta information:
+                - NotSet (default): Inherit from parent tool
+                - dict: Use custom meta information
+                - None: Remove meta information
+
+        Returns:
+            TransformedTool with the specified transformations.
+
+        Examples:
+            # Transform specific arguments only
+            ```python
+            Tool.from_tool(parent, transform_args={"old": "new"})  # Others unchanged
+            ```
+
+            # Custom function with partial transforms
+            ```python
+            async def custom(x: int, y: int) -> str:
+                result = await forward(x=x, y=y)
+                return f"Custom: {result}"
+
+            Tool.from_tool(parent, transform_fn=custom, transform_args={"a": "x", "b": "y"})
+            ```
+
+            # Using **kwargs (gets all args, transformed and untransformed)
+            ```python
+            async def flexible(**kwargs) -> str:
+                result = await forward(**kwargs)
+                return f"Got: {kwargs}"
+
+            Tool.from_tool(parent, transform_fn=flexible, transform_args={"a": "x"})
+            ```
+
+            # Control structured outputs and schemas
+            ```python
+            # Custom output schema
+            Tool.from_tool(parent, output_schema={
+                "type": "object",
+                "properties": {"status": {"type": "string"}}
+            })
+
+            # Disable structured outputs
+            Tool.from_tool(parent, output_schema=None)
+
+            # Return ToolResult for full control
+            async def custom_output(**kwargs) -> ToolResult:
+                result = await forward(**kwargs)
+                return ToolResult(
+                    content=[TextContent(text="Summary")],
+                    structured_content={"processed": True}
+                )
+            ```
+        """
+        tool = Tool._ensure_tool(tool)
+
+        transform_args = transform_args or {}
+
+        if transform_fn is not None:
+            parsed_fn = ParsedFunction.from_function(transform_fn, validate=False)
+        else:
+            parsed_fn = None
+
+        # Validate transform_args
+        parent_params = set(tool.parameters.get("properties", {}).keys())
+        unknown_args = set(transform_args.keys()) - parent_params
+        if unknown_args:
+            raise ValueError(
+                f"Unknown arguments in transform_args: {', '.join(sorted(unknown_args))}. "
+                f"Parent tool `{tool.name}` has: {', '.join(sorted(parent_params))}"
+            )
+
+        # Always create the forwarding transform
+        schema, forwarding_fn = cls._create_forwarding_transform(tool, transform_args)
+
+        # Handle output schema
+        if output_schema is NotSet:
+            # Use smart fallback: try custom function, then parent
+            if transform_fn is not None:
+                # parsed fn is not none here
+                final_output_schema = cast(ParsedFunction, parsed_fn).output_schema
+                if final_output_schema is None:
+                    # Check if function returns ToolResult (or subclass) - if so, don't fall back to parent.
+                    # Use parsed_fn.return_type (resolved via get_type_hints) instead of
+                    # inspect.signature, which returns strings under `from __future__ import annotations`.
+                    return_type = cast(ParsedFunction, parsed_fn).return_type
+                    if issubclass_safe(return_type, ToolResult):
+                        final_output_schema = None
+                    else:
+                        final_output_schema = tool.output_schema
+            else:
+                final_output_schema = tool.output_schema
+        else:
+            final_output_schema = cast(dict | None, output_schema)
+
+        if transform_fn is None:
+            # User wants pure transformation - use forwarding_fn as the main function
+            final_fn = forwarding_fn
+            final_schema = schema
+        else:
+            # parsed fn is not none here
+            parsed_fn = cast(ParsedFunction, parsed_fn)
+            # User provided custom function - merge schemas
+            final_fn = transform_fn
+
+            has_kwargs = cls._function_has_kwargs(transform_fn)
+
+            # Validate function parameters against transformed schema
+            fn_params = set(parsed_fn.input_schema.get("properties", {}).keys())
+            transformed_params = set(schema.get("properties", {}).keys())
+
+            if not has_kwargs:
+                # Without **kwargs, function must declare all transformed params
+                # Check if function is missing any parameters required after transformation
+                missing_params = transformed_params - fn_params
+                if missing_params:
+                    raise ValueError(
+                        f"Function missing parameters required after transformation: "
+                        f"{', '.join(sorted(missing_params))}. "
+                        f"Function declares: {', '.join(sorted(fn_params))}"
+                    )
+
+                # ArgTransform takes precedence over function signature
+                # Start with function schema as base, then override with transformed schema
+                final_schema = cls._merge_schema_with_precedence(
+                    parsed_fn.input_schema, schema
+                )
+            else:
+                # With **kwargs, function can access all transformed params
+                # ArgTransform takes precedence over function signature
+                # No validation needed - kwargs makes everything accessible
+
+                # Start with function schema as base, then override with transformed schema
+                final_schema = cls._merge_schema_with_precedence(
+                    parsed_fn.input_schema, schema
+                )
+
+        # Additional validation: check for naming conflicts after transformation
+        if transform_args:
+            new_names = []
+            for old_name in parent_params:
+                transform = transform_args.get(old_name, ArgTransform())
+
+                if transform.hide:
+                    continue
+
+                if transform.name is not NotSet:
+                    new_names.append(transform.name)
+                else:
+                    new_names.append(old_name)
+
+            # Check for duplicate names after transformation
+            name_counts = {}
+            for arg_name in new_names:
+                name_counts[arg_name] = name_counts.get(arg_name, 0) + 1
+
+            duplicates = [
+                arg_name for arg_name, count in name_counts.items() if count > 1
+            ]
+            if duplicates:
+                raise ValueError(
+                    f"Multiple arguments would be mapped to the same names: "
+                    f"{', '.join(sorted(duplicates))}"
+                )
+
+        final_name = name or tool.name
+        final_version = version if not isinstance(version, NotSetT) else tool.version
+        final_description = (
+            description if not isinstance(description, NotSetT) else tool.description
+        )
+        final_title = title if not isinstance(title, NotSetT) else tool.title
+        final_meta = meta if not isinstance(meta, NotSetT) else tool.meta
+        final_annotations = (
+            annotations if not isinstance(annotations, NotSetT) else tool.annotations
+        )
+
+        transformed_tool = cls(
+            fn=final_fn,
+            forwarding_fn=forwarding_fn,
+            parent_tool=tool,
+            name=final_name,
+            version=final_version,
+            title=final_title,
+            description=final_description,
+            parameters=final_schema,
+            output_schema=final_output_schema,
+            tags=tags or tool.tags,
+            annotations=final_annotations,
+            meta=final_meta,
+            transform_args=transform_args,
+            auth=tool.auth,
+        )
+
+        return transformed_tool
+
+    @classmethod
+    def _create_forwarding_transform(
+        cls,
+        parent_tool: Tool,
+        transform_args: dict[str, ArgTransform] | None,
+    ) -> tuple[dict[str, Any], Callable[..., Any]]:
+        """Create schema and forwarding function that encapsulates all transformation logic.
+
+        This method builds a new JSON schema for the transformed tool and creates a
+        forwarding function that validates arguments against the new schema and maps
+        them back to the parent tool's expected arguments.
+
+        Args:
+            parent_tool: The original tool to transform.
+            transform_args: Dictionary defining how to transform each argument.
+
+        Returns:
+            A tuple containing:
+            - The new JSON schema for the transformed tool as a dictionary
+            - Async function that validates and forwards calls to the parent tool
+        """
+
+        # Build transformed schema and mapping
+        # Deep copy to prevent mutations from corrupting the parent tool's schema
+        parent_defs = deepcopy(parent_tool.parameters.get("$defs", {}))
+        parent_props = deepcopy(parent_tool.parameters.get("properties", {}))
+        parent_required = set(parent_tool.parameters.get("required", []))
+
+        new_props = {}
+        new_required = set()
+        new_to_old = {}
+        hidden_defaults = {}  # Track hidden parameters with constant values
+
+        for old_name, old_schema in parent_props.items():
+            # Check if parameter is in transform_args
+            if transform_args and old_name in transform_args:
+                transform = transform_args[old_name]
+            else:
+                # Default behavior - pass through (no transformation)
+                transform = ArgTransform()  # Default ArgTransform with no changes
+
+            # Handle hidden parameters with defaults
+            if transform.hide:
+                # Validate that hidden parameters without user defaults have parent defaults
+                has_user_default = (
+                    transform.default is not NotSet
+                    or transform.default_factory is not NotSet
+                )
+                if not has_user_default and old_name in parent_required:
+                    raise ValueError(
+                        f"Hidden parameter '{old_name}' has no default value in parent tool "
+                        f"and no default or default_factory provided in ArgTransform. Either provide a default "
+                        f"or default_factory in ArgTransform or don't hide required parameters."
+                    )
+                if has_user_default:
+                    # Store info for later factory calling or direct value
+                    hidden_defaults[old_name] = transform
+                # Skip adding to schema (not exposed to clients)
+                continue
+
+            transform_result = cls._apply_single_transform(
+                old_name,
+                old_schema,
+                transform,
+                old_name in parent_required,
+            )
+
+            if transform_result:
+                new_name, new_schema, is_required, extracted_defs = transform_result
+                new_props[new_name] = new_schema
+                new_to_old[new_name] = old_name
+                if is_required:
+                    new_required.add(new_name)
+                # Hoist any $defs introduced by an ArgTransform(type=...) so that
+                # $ref values like "#/$defs/..." resolve at the schema root.
+                # Fail loudly on key collisions whose schemas differ, since
+                # silently overwriting would point earlier $ref values at the
+                # wrong type. Identical re-introductions are a no-op.
+                for def_name, def_schema in extracted_defs.items():
+                    existing = parent_defs.get(def_name)
+                    if existing is not None and existing != def_schema:
+                        raise ValueError(
+                            f"$defs collision for '{def_name}': an ArgTransform "
+                            f"introduces a definition with the same name as an "
+                            f"existing $defs entry but a different schema. "
+                            f"Rename one of the colliding types to avoid the "
+                            f"conflict."
+                        )
+                    parent_defs[def_name] = def_schema
+
+        schema = {
+            "type": "object",
+            "properties": new_props,
+            "required": list(new_required),
+            "additionalProperties": False,
+        }
+
+        if parent_defs:
+            schema["$defs"] = parent_defs
+            schema = compress_schema(schema)
+
+        # Create forwarding function that closes over everything it needs
+        async def _forward(**kwargs: Any):
+            # Validate arguments
+            valid_args = set(new_props.keys())
+            provided_args = set(kwargs.keys())
+            unknown_args = provided_args - valid_args
+
+            if unknown_args:
+                raise TypeError(
+                    f"Got unexpected keyword argument(s): {', '.join(sorted(unknown_args))}"
+                )
+
+            # Check required arguments
+            missing_args = new_required - provided_args
+            if missing_args:
+                raise TypeError(
+                    f"Missing required argument(s): {', '.join(sorted(missing_args))}"
+                )
+
+            # Map arguments to parent names
+            parent_args = {}
+            for new_name, value in kwargs.items():
+                old_name = new_to_old.get(new_name, new_name)
+                parent_args[old_name] = value
+
+            # Add hidden defaults (constant values for hidden parameters)
+            for old_name, transform in hidden_defaults.items():
+                if transform.default is not NotSet:
+                    parent_args[old_name] = transform.default
+                elif transform.default_factory is not NotSet:
+                    # Type check to ensure default_factory is callable
+                    if callable(transform.default_factory):
+                        parent_args[old_name] = transform.default_factory()
+
+            return await parent_tool.run(parent_args)
+
+        return schema, _forward
+
+    @staticmethod
+    def _apply_single_transform(
+        old_name: str,
+        old_schema: dict[str, Any],
+        transform: ArgTransform,
+        is_required: bool,
+    ) -> tuple[str, dict[str, Any], bool, dict[str, Any]] | None:
+        """Apply transformation to a single parameter.
+
+        This method handles the transformation of a single argument according to
+        the specified transformation rules.
+
+        Args:
+            old_name: Original name of the parameter.
+            old_schema: Original JSON schema for the parameter.
+            transform: ArgTransform object specifying how to transform the parameter.
+            is_required: Whether the original parameter was required.
+
+        Returns:
+            Tuple of (new_name, new_schema, new_is_required, extracted_defs) if
+            parameter should be kept, None if parameter should be dropped.
+            extracted_defs contains any $defs pulled off a type transform so the
+            caller can hoist them to the schema root.
+        """
+        if transform.hide:
+            return None
+
+        # Handle name transformation - ensure we always have a string
+        if transform.name is not NotSet:
+            new_name = transform.name if transform.name is not None else old_name
+        else:
+            new_name = old_name
+
+        # Ensure new_name is always a string
+        if not isinstance(new_name, str):
+            new_name = old_name
+
+        new_schema = old_schema.copy()
+
+        # Handle description transformation
+        if transform.description is not NotSet:
+            if transform.description is None:
+                new_schema.pop("description", None)  # Remove description
+            else:
+                new_schema["description"] = transform.description
+
+        # Handle required transformation first
+        if transform.required is not NotSet:
+            is_required = bool(transform.required)
+            if transform.required is True:
+                # Remove any existing default when making required
+                new_schema.pop("default", None)
+
+        # Handle default value transformation (only if not making required)
+        if transform.default is not NotSet and transform.required is not True:
+            new_schema["default"] = transform.default
+            is_required = False
+
+        # Handle type transformation
+        extracted_defs: dict[str, Any] = {}
+        if transform.type is not NotSet:
+            # Use TypeAdapter to get proper JSON schema for the type
+            type_schema = get_cached_typeadapter(transform.type).json_schema()
+            # Strip $defs from the type schema so they can be hoisted to the
+            # root of the parent schema by the caller. Otherwise they would be
+            # nested inside this property while $ref values still point to
+            # "#/$defs/..." at the root, leaving the references dangling.
+            extracted_defs = type_schema.pop("$defs", {})
+            # Update the schema with the type information from TypeAdapter
+            new_schema.update(type_schema)
+
+        # Handle examples transformation
+        if transform.examples is not NotSet:
+            new_schema["examples"] = transform.examples
+
+        return new_name, new_schema, is_required, extracted_defs
+
+    @staticmethod
+    def _merge_schema_with_precedence(
+        base_schema: dict[str, Any], override_schema: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Merge two schemas, with the override schema taking precedence.
+
+        Args:
+            base_schema: Base schema to start with
+            override_schema: Schema that takes precedence for overlapping properties
+
+        Returns:
+            Merged schema with override taking precedence
+        """
+        merged_props = base_schema.get("properties", {}).copy()
+        merged_required = set(base_schema.get("required", []))
+
+        override_props = override_schema.get("properties", {})
+        override_required = set(override_schema.get("required", []))
+
+        # Override properties
+        for param_name, param_schema in override_props.items():
+            if param_name in merged_props:
+                # Merge the schemas, with override taking precedence
+                base_param = merged_props[param_name].copy()
+                base_param.update(param_schema)
+                merged_props[param_name] = base_param
+            else:
+                merged_props[param_name] = param_schema.copy()
+
+        # Handle required parameters - override takes complete precedence
+        # Start with override's required set
+        final_required = override_required.copy()
+
+        # For parameters not in override, inherit base requirement status
+        # but only if they don't have a default in the final merged properties
+        for param_name in merged_required:
+            if param_name not in override_props:
+                # Parameter not mentioned in override, keep base requirement status
+                final_required.add(param_name)
+            elif (
+                param_name in override_props
+                and "default" not in merged_props[param_name]
+            ):
+                # Parameter in override but no default, keep required if it was required in base
+                if param_name not in override_required:
+                    # Override doesn't specify it as required, and it has no default,
+                    # so inherit from base
+                    final_required.add(param_name)
+
+        # Remove any parameters that have defaults (they become optional)
+        for param_name, param_schema in merged_props.items():
+            if "default" in param_schema:
+                final_required.discard(param_name)
+
+        # Merge $defs from both schemas, with override taking precedence
+        merged_defs = base_schema.get("$defs", {}).copy()
+        override_defs = override_schema.get("$defs", {})
+
+        for def_name, def_schema in override_defs.items():
+            if def_name in merged_defs:
+                base_def = merged_defs[def_name].copy()
+                base_def.update(def_schema)
+                merged_defs[def_name] = base_def
+            else:
+                merged_defs[def_name] = def_schema.copy()
+
+        result = {
+            "type": "object",
+            "properties": merged_props,
+            "required": list(final_required),
+            "additionalProperties": False,
+        }
+
+        if merged_defs:
+            result["$defs"] = merged_defs
+            result = compress_schema(result)
+
+        return result
+
+    @staticmethod
+    def _function_has_kwargs(fn: Callable[..., Any]) -> bool:
+        """Check if function accepts **kwargs.
+
+        This determines whether a custom function can accept arbitrary keyword arguments,
+        which affects how schemas are merged during tool transformation.
+
+        Args:
+            fn: Function to inspect.
+
+        Returns:
+            True if the function has a **kwargs parameter, False otherwise.
+        """
+        sig = inspect.signature(fn)
+        return any(
+            p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
+        )
+
+
+def _set_visibility_metadata(tool: Tool, *, enabled: bool) -> None:
+    """Set visibility state in tool metadata.
+
+    This uses the same metadata format as the Visibility transform,
+    so tools marked here will be filtered by the standard visibility system.
+
+    Args:
+        tool: Tool to mark.
+        enabled: Whether the tool should be visible to clients.
+    """
+    # Import here to avoid circular imports
+    from fastmcp.server.transforms.visibility import _FASTMCP_KEY, _INTERNAL_KEY
+
+    if tool.meta is None:
+        tool.meta = {_FASTMCP_KEY: {_INTERNAL_KEY: {"visibility": enabled}}}
+    else:
+        old_fastmcp = tool.meta.get(_FASTMCP_KEY, {})
+        old_internal = old_fastmcp.get(_INTERNAL_KEY, {})
+        new_internal = {**old_internal, "visibility": enabled}
+        new_fastmcp = {**old_fastmcp, _INTERNAL_KEY: new_internal}
+        tool.meta = {**tool.meta, _FASTMCP_KEY: new_fastmcp}
+
+
+class ToolTransformConfig(FastMCPBaseModel):
+    """Provides a way to transform a tool."""
+
+    name: str | None = Field(default=None, description="The new name for the tool.")
+    version: str | None = Field(
+        default=None, description="The new version for the tool."
+    )
+    title: str | None = Field(
+        default=None,
+        description="The new title of the tool.",
+    )
+    description: str | None = Field(
+        default=None,
+        description="The new description of the tool.",
+    )
+    tags: Annotated[set[str], BeforeValidator(_convert_set_default_none)] = Field(
+        default_factory=set,
+        description="The new tags for the tool.",
+    )
+    meta: dict[str, Any] | None = Field(
+        default=None,
+        description="The new meta information for the tool.",
+    )
+    enabled: bool = Field(
+        default=True,
+        description="Whether the tool is enabled. If False, the tool will be hidden from clients.",
+    )
+
+    arguments: dict[str, ArgTransformConfig] = Field(
+        default_factory=dict,
+        description="A dictionary of argument transforms to apply to the tool.",
+    )
+
+    def apply(self, tool: Tool) -> TransformedTool:
+        """Create a TransformedTool from a provided tool and this transformation configuration."""
+
+        tool_changes: dict[str, Any] = self.model_dump(
+            exclude_unset=True, exclude={"arguments", "enabled"}
+        )
+
+        transformed = TransformedTool.from_tool(
+            tool=tool,
+            **tool_changes,
+            transform_args={k: v.to_arg_transform() for k, v in self.arguments.items()},
+        )
+
+        # Set visibility metadata if enabled was explicitly provided.
+        # This allows enabled=True to override an earlier disable (later transforms win).
+        if "enabled" in self.model_fields_set:
+            _set_visibility_metadata(transformed, enabled=self.enabled)
+
+        return transformed
+
+
+def apply_transformations_to_tools(
+    tools: dict[str, Tool],
+    transformations: dict[str, ToolTransformConfig],
+) -> dict[str, Tool]:
+    """Apply a list of transformations to a list of tools. Tools that do not have any transformations
+    are left unchanged.
+
+    Note: tools dict is keyed by prefixed key (e.g., "tool:my_tool"),
+    but transformations are keyed by tool name (e.g., "my_tool").
+    """
+
+    transformed_tools: dict[str, Tool] = {}
+
+    for tool_key, tool in tools.items():
+        # Look up transformation by tool name, not prefixed key
+        if transformation := transformations.get(tool.name):
+            transformed = transformation.apply(tool)
+            transformed_tools[transformed.key] = transformed
+            continue
+
+        transformed_tools[tool_key] = tool
+
+    return transformed_tools
diff --git a/fastmcp_slim/fastmcp/types.py b/fastmcp_slim/fastmcp/types.py
new file mode 100644
index 0000000..4b33e7c
--- /dev/null
+++ b/fastmcp_slim/fastmcp/types.py
@@ -0,0 +1,140 @@
+"""Reusable type annotations for FastMCP tool parameters.
+
+These types can be used in tool function signatures to influence how
+parameters are presented in UIs (e.g. `fastmcp dev apps`) and
+serialized in JSON Schema.
+
+Example:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.types import Textarea
+
+mcp = FastMCP("demo")
+
+@mcp.tool()
+def run_query(sql: Textarea) -> str:
+    ...
+```
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from mcp_types import (
+    Annotations as Annotations,
+)
+from mcp_types import (
+    AudioContent as AudioContent,
+)
+from mcp_types import (
+    BlobResourceContents as BlobResourceContents,
+)
+from mcp_types import (
+    CallToolResult as CallToolResult,
+)
+from mcp_types import (
+    Completion as Completion,
+)
+from mcp_types import (
+    ContentBlock as ContentBlock,
+)
+from mcp_types import (
+    CreateMessageResult as CreateMessageResult,
+)
+from mcp_types import (
+    EmbeddedResource as EmbeddedResource,
+)
+from mcp_types import (
+    ErrorData as ErrorData,
+)
+from mcp_types import (
+    GetPromptResult as GetPromptResult,
+)
+from mcp_types import (
+    Icon as Icon,
+)
+from mcp_types import (
+    ImageContent as ImageContent,
+)
+from mcp_types import (
+    Prompt as Prompt,
+)
+from mcp_types import (
+    PromptMessage as PromptMessage,
+)
+from mcp_types import (
+    ReadResourceResult as ReadResourceResult,
+)
+from mcp_types import (
+    Resource as Resource,
+)
+from mcp_types import (
+    ResourceLink as ResourceLink,
+)
+from mcp_types import (
+    ResourceTemplate as ResourceTemplate,
+)
+from mcp_types import (
+    Root as Root,
+)
+from mcp_types import (
+    SamplingCapability as SamplingCapability,
+)
+from mcp_types import (
+    SamplingMessage as SamplingMessage,
+)
+from mcp_types import (
+    TextContent as TextContent,
+)
+from mcp_types import (
+    TextResourceContents as TextResourceContents,
+)
+from mcp_types import (
+    Tool as Tool,
+)
+from mcp_types import (
+    ToolAnnotations as ToolAnnotations,
+)
+from mcp_types import (
+    ToolResultContent as ToolResultContent,
+)
+from pydantic import Field
+
+Textarea = Annotated[str, Field(json_schema_extra={"format": "textarea"})]
+"""A string rendered as a multiline textarea in form-based UIs.
+
+Produces `"format": "textarea"` in the JSON Schema, which
+`fastmcp dev apps` picks up automatically.
+"""
+
+__all__ = [
+    "Annotations",
+    "AudioContent",
+    "BlobResourceContents",
+    "CallToolResult",
+    "Completion",
+    "ContentBlock",
+    "CreateMessageResult",
+    "EmbeddedResource",
+    "ErrorData",
+    "GetPromptResult",
+    "Icon",
+    "ImageContent",
+    "Prompt",
+    "PromptMessage",
+    "ReadResourceResult",
+    "Resource",
+    "ResourceLink",
+    "ResourceTemplate",
+    "Root",
+    "SamplingCapability",
+    "SamplingMessage",
+    "TextContent",
+    "TextResourceContents",
+    "Textarea",
+    "Tool",
+    "ToolAnnotations",
+    "ToolResultContent",
+]
diff --git a/fastmcp_slim/fastmcp/utilities/__init__.py b/fastmcp_slim/fastmcp/utilities/__init__.py
new file mode 100644
index 0000000..be448f9
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/__init__.py
@@ -0,0 +1 @@
+"""FastMCP utility modules."""
diff --git a/fastmcp_slim/fastmcp/utilities/async_utils.py b/fastmcp_slim/fastmcp/utilities/async_utils.py
new file mode 100644
index 0000000..8fc24f4
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/async_utils.py
@@ -0,0 +1,82 @@
+"""Async utilities for FastMCP."""
+
+import functools
+import inspect
+from collections.abc import Awaitable, Callable
+from typing import Any, Literal, TypeVar, overload
+
+import anyio
+from anyio.to_thread import run_sync as run_sync_in_threadpool
+
+T = TypeVar("T")
+
+
+def is_coroutine_function(fn: Any) -> bool:
+    """Check if a callable is a coroutine function, unwrapping functools.partial.
+
+    ``inspect.iscoroutinefunction`` returns ``False`` for
+    ``functools.partial`` objects wrapping an async function on Python < 3.12.
+    This helper unwraps any layers of ``partial`` before checking.
+    """
+    while isinstance(fn, functools.partial):
+        fn = fn.func
+    return inspect.iscoroutinefunction(fn)
+
+
+async def call_sync_fn_in_threadpool(
+    fn: Callable[..., Any], *args: Any, **kwargs: Any
+) -> Any:
+    """Call a sync function in a threadpool to avoid blocking the event loop.
+
+    Uses anyio.to_thread.run_sync which properly propagates contextvars,
+    making this safe for functions that depend on context (like dependency injection).
+    """
+    return await run_sync_in_threadpool(functools.partial(fn, *args, **kwargs))
+
+
+@overload
+async def gather(
+    *awaitables: Awaitable[T],
+    return_exceptions: Literal[True],
+) -> list[T | BaseException]: ...
+
+
+@overload
+async def gather(
+    *awaitables: Awaitable[T],
+    return_exceptions: Literal[False] = ...,
+) -> list[T]: ...
+
+
+async def gather(
+    *awaitables: Awaitable[T],
+    return_exceptions: bool = False,
+) -> list[T] | list[T | BaseException]:
+    """Run awaitables concurrently and return results in order.
+
+    Uses anyio TaskGroup for structured concurrency.
+
+    Args:
+        *awaitables: Awaitables to run concurrently
+        return_exceptions: If True, exceptions are returned in results.
+                          If False, first exception cancels all and raises.
+
+    Returns:
+        List of results in the same order as input awaitables.
+    """
+    results: list[T | BaseException] = [None] * len(awaitables)  # type: ignore[assignment]  # ty:ignore[invalid-assignment]
+
+    async def run_at(i: int, aw: Awaitable[T]) -> None:
+        try:
+            results[i] = await aw
+        except BaseException as e:
+            if return_exceptions:
+                results[i] = e
+            else:
+                raise
+
+    async with anyio.create_task_group() as tg:
+        for i, aw in enumerate(awaitables):
+            tg.start_soon(run_at, i, aw)
+
+    return results
diff --git a/fastmcp_slim/fastmcp/utilities/auth.py b/fastmcp_slim/fastmcp/utilities/auth.py
new file mode 100644
index 0000000..03eb59b
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/auth.py
@@ -0,0 +1,91 @@
+"""Authentication utility helpers."""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any
+
+
+def _decode_jwt_part(token: str, part_index: int) -> dict[str, Any]:
+    """Decode a JWT part (header or payload) without signature verification.
+
+    Args:
+        token: JWT token string (header.payload.signature)
+        part_index: 0 for header, 1 for payload
+
+    Returns:
+        Decoded part as a dictionary
+
+    Raises:
+        ValueError: If token is not a valid JWT format
+    """
+    parts = token.split(".")
+    if len(parts) != 3:
+        raise ValueError("Invalid JWT format (expected 3 parts)")
+
+    part_b64 = parts[part_index]
+    part_b64 += "=" * (-len(part_b64) % 4)  # Add padding
+    return json.loads(base64.urlsafe_b64decode(part_b64))
+
+
+def decode_jwt_header(token: str) -> dict[str, Any]:
+    """Decode JWT header without signature verification.
+
+    Useful for extracting the key ID (kid) for JWKS lookup.
+
+    Args:
+        token: JWT token string (header.payload.signature)
+
+    Returns:
+        Decoded header as a dictionary
+
+    Raises:
+        ValueError: If token is not a valid JWT format
+    """
+    return _decode_jwt_part(token, 0)
+
+
+def decode_jwt_payload(token: str) -> dict[str, Any]:
+    """Decode JWT payload without signature verification.
+
+    Use only for tokens received directly from trusted sources (e.g., IdP token endpoints).
+
+    Args:
+        token: JWT token string (header.payload.signature)
+
+    Returns:
+        Decoded payload as a dictionary
+
+    Raises:
+        ValueError: If token is not a valid JWT format
+    """
+    return _decode_jwt_part(token, 1)
+
+
+def parse_scopes(value: Any) -> list[str] | None:
+    """Parse scopes from environment variables or settings values.
+
+    Accepts either a JSON array string, a comma- or space-separated string,
+    a list of strings, or ``None``. Returns a list of scopes or ``None`` if
+    no value is provided.
+    """
+    if value is None or value == "":
+        return None if value is None else []
+    if isinstance(value, list):
+        return [str(v).strip() for v in value if str(v).strip()]
+    if isinstance(value, str):
+        value = value.strip()
+        if not value:
+            return []
+        # Try JSON array first
+        if value.startswith("["):
+            try:
+                data = json.loads(value)
+                if isinstance(data, list):
+                    return [str(v).strip() for v in data if str(v).strip()]
+            except Exception:
+                pass
+        # Fallback to comma/space separated list
+        return [s.strip() for s in value.replace(",", " ").split() if s.strip()]
+    return value
diff --git a/fastmcp_slim/fastmcp/utilities/authorization.py b/fastmcp_slim/fastmcp/utilities/authorization.py
new file mode 100644
index 0000000..4e193c7
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/authorization.py
@@ -0,0 +1,101 @@
+"""Authorization checks for FastMCP components.
+
+Auth checks are callables that receive an ``AuthContext`` and return True to
+allow access or False to deny it. They can also raise ``AuthorizationError`` to
+deny with a custom message; other exceptions are masked and treated as denial.
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, cast
+
+from fastmcp.exceptions import AuthorizationError
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from fastmcp.server.auth import AccessToken
+    from fastmcp.tools.base import Tool
+    from fastmcp.utilities.components import FastMCPComponent
+
+
+@dataclass
+class AuthContext:
+    """Context passed to auth check callables.
+
+    Attributes:
+        token: The current access token, or None if unauthenticated.
+        component: The tool, resource, resource template, or prompt being accessed.
+        tool: Backwards-compatible alias for component when it is a Tool.
+    """
+
+    token: AccessToken | None
+    component: FastMCPComponent
+
+    @property
+    def tool(self) -> Tool | None:
+        """Backwards-compatible access to the component as a Tool."""
+        from fastmcp.tools.base import Tool
+
+        return self.component if isinstance(self.component, Tool) else None
+
+
+AuthCheck = Callable[[AuthContext], bool] | Callable[[AuthContext], Awaitable[bool]]
+
+
+def require_scopes(*scopes: str) -> AuthCheck:
+    """Require all of the given OAuth scopes."""
+    required = set(scopes)
+
+    def check(ctx: AuthContext) -> bool:
+        if ctx.token is None:
+            return False
+        return required.issubset(set(ctx.token.scopes))
+
+    return check
+
+
+def restrict_tag(tag: str, *, scopes: list[str]) -> AuthCheck:
+    """Require scopes when the accessed component has a specific tag."""
+    required = set(scopes)
+
+    def check(ctx: AuthContext) -> bool:
+        if tag not in ctx.component.tags:
+            return True
+        if ctx.token is None:
+            return False
+        return required.issubset(set(ctx.token.scopes))
+
+    return check
+
+
+async def run_auth_checks(
+    checks: AuthCheck | list[AuthCheck],
+    ctx: AuthContext,
+) -> bool:
+    """Run auth checks with AND logic."""
+    check_list = [checks] if not isinstance(checks, list) else checks
+    check_list = cast(list[AuthCheck], check_list)
+
+    for check in check_list:
+        try:
+            result = check(ctx)
+            if inspect.isawaitable(result):
+                result = await result
+            if not result:
+                return False
+        except AuthorizationError:
+            raise
+        except Exception:
+            logger.warning(
+                f"Auth check {getattr(check, '__name__', repr(check))} "
+                "raised an unexpected exception",
+                exc_info=True,
+            )
+            return False
+
+    return True
diff --git a/fastmcp_slim/fastmcp/utilities/cli.py b/fastmcp_slim/fastmcp/utilities/cli.py
new file mode 100644
index 0000000..ad03691
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/cli.py
@@ -0,0 +1,268 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from pydantic import ValidationError
+from rich.align import Align
+from rich.console import Console, Group
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+import fastmcp
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_server_config import MCPServerConfig
+from fastmcp.utilities.mcp_server_config.v1.sources.filesystem import FileSystemSource
+from fastmcp.utilities.types import get_cached_typeadapter
+from fastmcp.utilities.version_check import check_for_newer_version
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+logger = get_logger("cli.config")
+
+
+def is_already_in_uv_subprocess() -> bool:
+    """Check if we're already running in a FastMCP uv subprocess."""
+    return bool(os.environ.get("FASTMCP_UV_SPAWNED"))
+
+
+def load_and_merge_config(
+    server_spec: str | None,
+    **cli_overrides,
+) -> tuple[MCPServerConfig, str]:
+    """Load config from server_spec and apply CLI overrides.
+
+    This consolidates the config parsing logic that was duplicated across
+    run, inspect, and dev commands.
+
+    Args:
+        server_spec: Python file, config file, URL, or None to auto-detect
+        cli_overrides: CLI arguments that override config values
+
+    Returns:
+        Tuple of (MCPServerConfig, resolved_server_spec)
+    """
+    config = None
+    config_path = None
+
+    # Auto-detect fastmcp.json if no server_spec provided
+    if server_spec is None:
+        config_path = Path("fastmcp.json")
+        if not config_path.exists():
+            found_config = MCPServerConfig.find_config()
+            if found_config:
+                config_path = found_config
+            else:
+                logger.error(
+                    "No server specification provided and no fastmcp.json found in current directory.\n"
+                    "Please specify a server file or create a fastmcp.json configuration."
+                )
+                raise FileNotFoundError("No server specification or fastmcp.json found")
+
+        resolved_spec = str(config_path)
+        logger.info(f"Using configuration from {config_path}")
+    else:
+        resolved_spec = server_spec
+
+    # Load config if server_spec is a .json file
+    if resolved_spec.endswith(".json"):
+        config_path = Path(resolved_spec)
+        if config_path.exists():
+            try:
+                with open(config_path) as f:
+                    data = json.load(f)
+
+                # Check if it's an MCPConfig first (has canonical mcpServers key)
+                if "mcpServers" in data:
+                    # MCPConfig - we don't process these here, just pass through
+                    pass
+                else:
+                    # Try to parse as MCPServerConfig
+                    try:
+                        adapter = get_cached_typeadapter(MCPServerConfig)
+                        config = adapter.validate_python(data)
+
+                        # Apply deployment settings
+                        if config.deployment:
+                            config.deployment.apply_runtime_settings(config_path)
+
+                    except ValidationError:
+                        # Not a valid MCPServerConfig, just pass through
+                        pass
+            except (json.JSONDecodeError, FileNotFoundError):
+                # Not a valid JSON file, just pass through
+                pass
+
+    # If we don't have a config object yet, create one from filesystem source
+    if config is None:
+        source = FileSystemSource(path=resolved_spec)
+        config = MCPServerConfig(source=source)
+
+    # Convert to dict for immutable transformation
+    config_dict = config.model_dump()
+
+    # Apply CLI overrides to config's environment (always exists due to default_factory)
+    if python_override := cli_overrides.get("python"):
+        config_dict["environment"]["python"] = python_override
+    if packages_override := cli_overrides.get("with_packages"):
+        # Merge packages - CLI packages are added to config packages
+        existing = config_dict["environment"].get("dependencies") or []
+        config_dict["environment"]["dependencies"] = packages_override + existing
+    if requirements_override := cli_overrides.get("with_requirements"):
+        config_dict["environment"]["requirements"] = str(requirements_override)
+    if project_override := cli_overrides.get("project"):
+        config_dict["environment"]["project"] = str(project_override)
+    if editable_override := cli_overrides.get("editable"):
+        config_dict["environment"]["editable"] = editable_override
+
+    # Apply deployment CLI overrides (always exists due to default_factory)
+    if transport_override := cli_overrides.get("transport"):
+        config_dict["deployment"]["transport"] = transport_override
+    if host_override := cli_overrides.get("host"):
+        config_dict["deployment"]["host"] = host_override
+    if port_override := cli_overrides.get("port"):
+        config_dict["deployment"]["port"] = port_override
+    if path_override := cli_overrides.get("path"):
+        config_dict["deployment"]["path"] = path_override
+    if log_level_override := cli_overrides.get("log_level"):
+        config_dict["deployment"]["log_level"] = log_level_override
+    if server_args_override := cli_overrides.get("server_args"):
+        config_dict["deployment"]["args"] = server_args_override
+
+    # Create new config from modified dict
+    new_config = MCPServerConfig(**config_dict)
+    return new_config, resolved_spec
+
+
+LOGO_ASCII_1 = r"""
+    _ __ ___  _____           __  __  _____________    ____    ____ 
+   _ __ ___ .'____/___ ______/ /_/  |/  / ____/ __ \  |___ \  / __ \
+  _ __ ___ / /_  / __ `/ ___/ __/ /|_/ / /   / /_/ /  ___/ / / / / /
+ _ __ ___ / __/ / /_/ (__  ) /_/ /  / / /___/ ____/  /  __/_/ /_/ / 
+_ __ ___ /_/    \____/____/\__/_/  /_/\____/_/      /_____(*)____/  
+
+""".lstrip("\n")
+
+# This prints the below in a blue gradient
+#  █▀▀ ▄▀█ █▀▀ ▀█▀ █▀▄▀█ █▀▀ █▀█
+#  █▀  █▀█ ▄▄█  █  █ ▀ █ █▄▄ █▀▀
+LOGO_ASCII_2 = (
+    "\x1b[38;2;0;198;255m \x1b[38;2;0;195;255m█\x1b[38;2;0;192;255m▀\x1b[38;2;0;189;255m▀\x1b[38;2;0;186;255m "
+    "\x1b[38;2;0;184;255m▄\x1b[38;2;0;181;255m▀\x1b[38;2;0;178;255m█\x1b[38;2;0;175;255m "
+    "\x1b[38;2;0;172;255m█\x1b[38;2;0;169;255m▀\x1b[38;2;0;166;255m▀\x1b[38;2;0;163;255m "
+    "\x1b[38;2;0;160;255m▀\x1b[38;2;0;157;255m█\x1b[38;2;0;155;255m▀\x1b[38;2;0;152;255m "
+    "\x1b[38;2;0;149;255m█\x1b[38;2;0;146;255m▀\x1b[38;2;0;143;255m▄\x1b[38;2;0;140;255m▀\x1b[38;2;0;137;255m█\x1b[38;2;0;134;255m "
+    "\x1b[38;2;0;131;255m█\x1b[38;2;0;128;255m▀\x1b[38;2;0;126;255m▀\x1b[38;2;0;123;255m "
+    "\x1b[38;2;0;120;255m█\x1b[38;2;0;117;255m▀\x1b[38;2;0;114;255m█\x1b[39m\n"
+    "\x1b[38;2;0;198;255m \x1b[38;2;0;195;255m█\x1b[38;2;0;192;255m▀\x1b[38;2;0;189;255m \x1b[38;2;0;186;255m "
+    "\x1b[38;2;0;184;255m█\x1b[38;2;0;181;255m▀\x1b[38;2;0;178;255m█\x1b[38;2;0;175;255m "
+    "\x1b[38;2;0;172;255m▄\x1b[38;2;0;169;255m▄\x1b[38;2;0;166;255m█\x1b[38;2;0;163;255m "
+    "\x1b[38;2;0;160;255m \x1b[38;2;0;157;255m█\x1b[38;2;0;155;255m \x1b[38;2;0;152;255m "
+    "\x1b[38;2;0;149;255m█\x1b[38;2;0;146;255m \x1b[38;2;0;143;255m▀\x1b[38;2;0;140;255m \x1b[38;2;0;137;255m█\x1b[38;2;0;134;255m "
+    "\x1b[38;2;0;131;255m█\x1b[38;2;0;128;255m▄\x1b[38;2;0;126;255m▄\x1b[38;2;0;123;255m "
+    "\x1b[38;2;0;120;255m█\x1b[38;2;0;117;255m▀\x1b[38;2;0;114;255m▀\x1b[39m"
+).strip()
+
+# Prints the below in a blue gradient - stylized F
+#  ▄▀▀▀
+#  █▀▀
+# ▀
+LOGO_ASCII_3 = (
+    " \x1b[38;2;0;170;255m▄\x1b[38;2;0;142;255m▀\x1b[38;2;0;114;255m▀\x1b[38;2;0;86;255m▀\x1b[39m\n"
+    " \x1b[38;2;0;170;255m█\x1b[38;2;0;142;255m▀\x1b[38;2;0;114;255m▀\x1b[39m\n"
+    "\x1b[38;2;0;170;255m▀\x1b[39m\n"
+    "\x1b[0m"
+)
+
+# Prints the below in a blue gradient - block logo with slightly stylized F
+#  ▄▀▀ ▄▀█ █▀▀ ▀█▀ █▀▄▀█ █▀▀ █▀█
+#  █▀  █▀█ ▄▄█  █  █ ▀ █ █▄▄ █▀▀
+
+LOGO_ASCII_4 = (
+    "\x1b[38;2;0;198;255m \x1b[38;2;0;195;255m▄\x1b[38;2;0;192;255m▀\x1b[38;2;0;189;255m▀\x1b[38;2;0;186;255m \x1b[38;2;0;184;255m▄\x1b[38;2;0;181;255m▀\x1b[38;2;0;178;255m█\x1b[38;2;0;175;255m "
+    "\x1b[38;2;0;172;255m█\x1b[38;2;0;169;255m▀\x1b[38;2;0;166;255m▀\x1b[38;2;0;163;255m "
+    "\x1b[38;2;0;160;255m▀\x1b[38;2;0;157;255m█\x1b[38;2;0;155;255m▀\x1b[38;2;0;152;255m "
+    "\x1b[38;2;0;149;255m█\x1b[38;2;0;146;255m▀\x1b[38;2;0;143;255m▄\x1b[38;2;0;140;255m▀\x1b[38;2;0;137;255m█\x1b[38;2;0;134;255m "
+    "\x1b[38;2;0;131;255m█\x1b[38;2;0;128;255m▀\x1b[38;2;0;126;255m▀\x1b[38;2;0;123;255m "
+    "\x1b[38;2;0;120;255m█\x1b[38;2;0;117;255m▀\x1b[38;2;0;114;255m█\x1b[39m\n"
+    "\x1b[38;2;0;198;255m \x1b[38;2;0;195;255m█\x1b[38;2;0;192;255m▀\x1b[38;2;0;189;255m \x1b[38;2;0;186;255m \x1b[38;2;0;184;255m█\x1b[38;2;0;181;255m▀\x1b[38;2;0;178;255m█\x1b[38;2;0;175;255m "
+    "\x1b[38;2;0;172;255m▄\x1b[38;2;0;169;255m▄\x1b[38;2;0;166;255m█\x1b[38;2;0;163;255m "
+    "\x1b[38;2;0;160;255m \x1b[38;2;0;157;255m█\x1b[38;2;0;155;255m \x1b[38;2;0;152;255m "
+    "\x1b[38;2;0;149;255m█\x1b[38;2;0;146;255m \x1b[38;2;0;143;255m▀\x1b[38;2;0;140;255m \x1b[38;2;0;137;255m█\x1b[38;2;0;134;255m "
+    "\x1b[38;2;0;131;255m█\x1b[38;2;0;128;255m▄\x1b[38;2;0;126;255m▄\x1b[38;2;0;123;255m "
+    "\x1b[38;2;0;120;255m█\x1b[38;2;0;117;255m▀\x1b[38;2;0;114;255m▀\x1b[39m\n"
+)
+
+
+def log_server_banner(server: FastMCP[Any]) -> None:
+    """Creates and logs a formatted banner with server information and logo."""
+
+    # Check for updates (non-blocking, fails silently)
+    newer_version = check_for_newer_version()
+
+    # Create the logo text
+    # Use Text with no_wrap and markup disabled to preserve ANSI escape codes
+    logo_text = Text.from_ansi(LOGO_ASCII_4, no_wrap=True)
+
+    # Create the main title
+    title_text = Text(f"FastMCP {fastmcp.__version__}", style="bold blue")
+
+    # Create the information table
+    info_table = Table.grid(padding=(0, 1))
+    info_table.add_column(style="bold", justify="center")  # Emoji column
+    info_table.add_column(style="cyan", justify="left")  # Label column
+    info_table.add_column(style="dim", justify="left")  # Value column
+
+    server_info = server.name
+    if server.version:
+        server_info += f", {server.version}"
+    info_table.add_row("🖥", "Server:", Text(server_info, style="dim"))
+    info_table.add_row("🚀", "Deploy free:", "https://horizon.prefect.io")
+
+    # Create panel with logo, title, and information using Group
+    docs_url = Text("https://gofastmcp.com", style="dim")
+    panel_content = Group(
+        "",
+        Align.center(logo_text),
+        "",
+        "",
+        Align.center(title_text),
+        Align.center(docs_url),
+        "",
+        Align.center(info_table),
+    )
+
+    panel = Panel(
+        panel_content,
+        border_style="dim",
+        padding=(1, 4),
+        width=80,  # Set max width for the panel
+    )
+
+    console = Console(stderr=True)
+
+    # Build output elements
+    output_elements: list[Align | Panel | str] = ["\n", Align.center(panel)]
+
+    # Add update notice if a newer version is available (shown last for visibility)
+    if newer_version:
+        update_line1 = Text.assemble(
+            ("🎉 Update available: ", "bold"),
+            (newer_version, "bold green"),
+        )
+        update_line2 = Text("Run: pip install --upgrade fastmcp", style="dim")
+        update_notice = Panel(
+            Group(Align.center(update_line1), Align.center(update_line2)),
+            border_style="blue",
+            padding=(0, 2),
+            width=80,
+        )
+        output_elements.append(Align.center(update_notice))
+
+    output_elements.append("\n")
+
+    console.print(Group(*output_elements))
diff --git a/fastmcp_slim/fastmcp/utilities/components.py b/fastmcp_slim/fastmcp/utilities/components.py
new file mode 100644
index 0000000..0fc8ea4
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/components.py
@@ -0,0 +1,282 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Annotated, Any, ClassVar, TypedDict, cast
+
+from mcp_types import Icon
+from pydantic import BeforeValidator, Field
+from typing_extensions import Self, TypeVar
+
+from fastmcp.utilities.tasks import TaskConfig
+from fastmcp.utilities.types import FastMCPBaseModel
+
+if TYPE_CHECKING:
+    from docket import Docket
+    from docket.execution import Execution
+
+T = TypeVar("T", default=Any)
+
+
+class FastMCPMeta(TypedDict, total=False):
+    tags: list[str]
+    version: str
+    versions: list[str]
+
+
+def get_fastmcp_metadata(meta: dict[str, Any] | None) -> FastMCPMeta:
+    """Extract FastMCP metadata from a component's meta dict.
+
+    Handles both the current `fastmcp` namespace and the legacy `_fastmcp`
+    namespace for compatibility with older FastMCP servers.
+    """
+    if not meta:
+        return {}
+
+    for key in ("fastmcp", "_fastmcp"):
+        metadata = meta.get(key)
+        if isinstance(metadata, dict):
+            return cast(FastMCPMeta, metadata)
+
+    return {}
+
+
+def _convert_set_default_none(maybe_set: set[T] | Sequence[T] | None) -> set[T]:
+    """Convert a sequence to a set, defaulting to an empty set if None."""
+    if maybe_set is None:
+        return set()
+    if isinstance(maybe_set, set):
+        return maybe_set
+    return set(maybe_set)
+
+
+def _coerce_version(v: str | int | float | None) -> str | None:
+    """Coerce version to string, accepting int, float, or str.
+
+    Raises TypeError for non-scalar types (list, dict, set, etc.).
+    Raises ValueError if version contains '@' (used as key delimiter).
+    """
+    if v is None:
+        return None
+    if isinstance(v, bool):
+        raise TypeError(f"Version must be a string, int, or float, got bool: {v!r}")
+    if not isinstance(v, (str, int, float)):
+        raise TypeError(
+            f"Version must be a string, int, or float, got {type(v).__name__}: {v!r}"
+        )
+    version = str(v)
+    if "@" in version:
+        raise ValueError(
+            f"Version string cannot contain '@' (used as key delimiter): {version!r}"
+        )
+    return version
+
+
+class FastMCPComponent(FastMCPBaseModel):
+    """Base class for FastMCP tools, prompts, resources, and resource templates."""
+
+    KEY_PREFIX: ClassVar[str] = ""
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        # Warn if a subclass doesn't define KEY_PREFIX (inherited or its own)
+        if not cls.KEY_PREFIX:
+            import warnings
+
+            warnings.warn(
+                f"{cls.__name__} does not define KEY_PREFIX. "
+                f"Component keys will not be type-prefixed, which may cause collisions.",
+                UserWarning,
+                stacklevel=2,
+            )
+
+    name: str = Field(
+        description="The name of the component.",
+    )
+    version: Annotated[str | None, BeforeValidator(_coerce_version)] = Field(
+        default=None,
+        description="Optional version identifier for this component. "
+        "Multiple versions of the same component (same name) can coexist.",
+    )
+    title: str | None = Field(
+        default=None,
+        description="The title of the component for display purposes.",
+    )
+    description: str | None = Field(
+        default=None,
+        description="The description of the component.",
+    )
+    icons: list[Icon] | None = Field(
+        default=None,
+        description="Optional list of icons for this component to display in user interfaces.",
+    )
+    tags: Annotated[set[str], BeforeValidator(_convert_set_default_none)] = Field(
+        default_factory=set,
+        description="Tags for the component.",
+    )
+    meta: dict[str, Any] | None = Field(
+        default=None, description="Meta information about the component"
+    )
+    task_config: Annotated[
+        TaskConfig,
+        Field(description="Background task execution configuration (SEP-1686)."),
+    ] = Field(default_factory=lambda: TaskConfig(mode="forbidden"))
+
+    @classmethod
+    def make_key(cls, identifier: str) -> str:
+        """Construct the lookup key for this component type.
+
+        Args:
+            identifier: The raw identifier (name for tools/prompts, uri for resources)
+
+        Returns:
+            A prefixed key like "tool:name" or "resource:uri"
+        """
+        if cls.KEY_PREFIX:
+            return f"{cls.KEY_PREFIX}:{identifier}"
+        return identifier
+
+    @property
+    def key(self) -> str:
+        """The globally unique lookup key for this component.
+
+        Format: "{key_prefix}:{identifier}@{version}" or "{key_prefix}:{identifier}@"
+        e.g. "tool:my_tool@v2", "tool:my_tool@", "resource:file://x.txt@"
+
+        The @ suffix is ALWAYS present to enable unambiguous parsing of keys
+        (URIs may contain @ characters, so we always include the delimiter).
+
+        Subclasses should override this to use their specific identifier.
+        Base implementation uses name.
+
+        Prefer `.key` over ad-hoc `name or uri or uri_template` logic for any
+        cross-component identity work (dedupe, grouping, collision detection,
+        lookup tables). It encodes type, identifier, and version, so variants
+        of the same component don't falsely collide with each other, and
+        cross-type identifiers (e.g. a tool and a resource both named "foo")
+        can't clash.
+        """
+        base_key = self.make_key(self.name)
+        return f"{base_key}@{self.version or ''}"
+
+    def get_meta(self) -> dict[str, Any]:
+        """Get the meta information about the component.
+
+        Returns a dict that always includes a `fastmcp` key containing:
+        - `tags`: sorted list of component tags
+        - `version`: component version (only if set)
+
+        Internal keys (prefixed with `_`) are stripped from the fastmcp namespace.
+        """
+        meta = dict(self.meta) if self.meta else {}
+
+        fastmcp_meta: FastMCPMeta = {"tags": sorted(self.tags)}
+        if self.version is not None:
+            fastmcp_meta["version"] = self.version
+
+        # Merge with upstream fastmcp meta, stripping internal keys
+        if (upstream_meta := meta.get("fastmcp")) is not None:
+            if not isinstance(upstream_meta, dict):
+                raise TypeError("meta['fastmcp'] must be a dict")
+            # Filter out internal keys (e.g., _internal used for enabled state)
+            public_upstream = {
+                k: v for k, v in upstream_meta.items() if not k.startswith("_")
+            }
+            fastmcp_meta = cast(FastMCPMeta, public_upstream | fastmcp_meta)
+        meta["fastmcp"] = fastmcp_meta
+
+        return meta
+
+    def __eq__(self, other: object) -> bool:
+        if type(self) is not type(other):
+            return False
+        if not isinstance(other, type(self)):
+            return False
+        return self.model_dump() == other.model_dump()
+
+    def __repr__(self) -> str:
+        parts = [f"name={self.name!r}"]
+        if self.version:
+            parts.append(f"version={self.version!r}")
+        parts.extend(
+            [
+                f"title={self.title!r}",
+                f"description={self.description!r}",
+                f"tags={self.tags}",
+            ]
+        )
+        return f"{self.__class__.__name__}({', '.join(parts)})"
+
+    def enable(self) -> None:
+        """Removed in 3.0. Use server.enable(keys=[...]) instead."""
+        raise NotImplementedError(
+            f"Component.enable() was removed in FastMCP 3.0. "
+            f"Use server.enable(keys=['{self.key}']) instead."
+        )
+
+    def disable(self) -> None:
+        """Removed in 3.0. Use server.disable(keys=[...]) instead."""
+        raise NotImplementedError(
+            f"Component.disable() was removed in FastMCP 3.0. "
+            f"Use server.disable(keys=['{self.key}']) instead."
+        )
+
+    def copy(self) -> Self:  # type: ignore[override]  # ty:ignore[invalid-method-override]
+        """Create a copy of the component."""
+        return self.model_copy()
+
+    def register_with_docket(self, docket: Docket) -> None:
+        """Register this component with docket for background execution.
+
+        No-ops if task_config.mode is "forbidden". Subclasses override to
+        register their callable (self.run, self.read, self.render, or self.fn).
+        """
+        # Base implementation: no-op (subclasses override)
+
+    def coerce_task_arguments(
+        self, arguments: dict[str, Any], *, strict: bool = False
+    ) -> dict[str, Any]:
+        """Validate and coerce task arguments before any task state is created.
+
+        Called by ``submit_to_docket`` up front, so invalid inputs raise before
+        the task's Redis metadata and initial status notification exist —
+        otherwise a coercion failure during queueing would orphan a task the
+        client has already observed. The base implementation is a no-op;
+        components that splat arguments into a typed Python callable (e.g.
+        ``FunctionTool``) override this to mirror the synchronous validation
+        path.
+
+        When ``strict`` is set (server-level ``strict_input_validation``),
+        overrides validate in strict mode so the task path rejects lax
+        coercions (e.g. the string ``"1"`` into an ``int``) exactly as the
+        synchronous call path does.
+        """
+        return arguments
+
+    async def add_to_docket(
+        self, docket: Docket, *args: Any, **kwargs: Any
+    ) -> Execution:
+        """Schedule this component for background execution via docket.
+
+        Subclasses override this to handle their specific calling conventions:
+        - Tool: add_to_docket(docket, arguments: dict, **kwargs)
+        - Resource: add_to_docket(docket, **kwargs)
+        - ResourceTemplate: add_to_docket(docket, params: dict, **kwargs)
+        - Prompt: add_to_docket(docket, arguments: dict | None, **kwargs)
+
+        The **kwargs are passed through to docket.add() (e.g., key=task_key).
+        """
+        if not self.task_config.supports_tasks():
+            raise RuntimeError(
+                f"Cannot add {self.__class__.__name__} '{self.name}' to docket: "
+                f"task execution not supported"
+            )
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not implement add_to_docket()"
+        )
+
+    def get_span_attributes(self) -> dict[str, Any]:
+        """Return span attributes for telemetry.
+
+        Subclasses should call super() and merge their specific attributes.
+        """
+        return {"fastmcp.component.key": self.key}
diff --git a/fastmcp_slim/fastmcp/utilities/docstring_parsing.py b/fastmcp_slim/fastmcp/utilities/docstring_parsing.py
new file mode 100644
index 0000000..babcb1e
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/docstring_parsing.py
@@ -0,0 +1,65 @@
+"""Extract descriptions from function docstrings.
+
+Uses griffelib to parse Google, NumPy, and Sphinx-style docstrings. The
+interface is intentionally narrow — a single function returning a
+`ParsedDocstring` — so the implementation can be swapped without touching
+callers.
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from griffe import Docstring, DocstringSectionKind
+
+_PARSERS = ("google", "numpy", "sphinx")
+
+logger = logging.getLogger("griffe")
+# Griffe warns about missing type annotations in docstrings, which is noisy
+# and irrelevant — we only care about descriptions.
+logger.setLevel(logging.ERROR)
+
+
+@dataclass(frozen=True)
+class ParsedDocstring:
+    """The extracted description and per-parameter descriptions from a docstring."""
+
+    description: str | None = None
+    parameters: dict[str, str] = field(default_factory=dict)
+
+
+def parse_docstring(fn: Callable[..., Any]) -> ParsedDocstring:
+    """Parse a function's docstring into a summary and parameter descriptions.
+
+    Tries Google, NumPy, and Sphinx parsers in order, using the first one that
+    successfully extracts parameter descriptions. If none do, returns the full
+    docstring as the description with no parameter descriptions.
+    """
+    doc = inspect.getdoc(fn)
+    if not doc:
+        return ParsedDocstring()
+
+    # Try each parser and use the first one that finds parameters.
+    for parser in _PARSERS:
+        docstring = Docstring(doc, lineno=1, parser=parser)
+        sections = docstring.parse()
+
+        description: str | None = None
+        parameters: dict[str, str] = {}
+
+        for section in sections:
+            if section.kind == DocstringSectionKind.text and description is None:
+                description = section.value
+            elif section.kind == DocstringSectionKind.parameters:
+                for param in section.value:
+                    parameters[param.name] = param.description
+
+        if parameters:
+            return ParsedDocstring(description=description, parameters=parameters)
+
+    # No parser found parameters — return the full docstring unchanged.
+    return ParsedDocstring(description=doc)
diff --git a/fastmcp_slim/fastmcp/utilities/exceptions.py b/fastmcp_slim/fastmcp/utilities/exceptions.py
new file mode 100644
index 0000000..dfdda67
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/exceptions.py
@@ -0,0 +1,46 @@
+from collections.abc import Callable, Iterable, Mapping
+from typing import Any
+
+import httpx
+from exceptiongroup import BaseExceptionGroup
+from mcp import MCPError
+
+import fastmcp
+
+
+def iter_exc(group: BaseExceptionGroup):
+    for exc in group.exceptions:
+        if isinstance(exc, BaseExceptionGroup):
+            yield from iter_exc(exc)
+        else:
+            yield exc
+
+
+def _exception_handler(group: BaseExceptionGroup):
+    for leaf in iter_exc(group):
+        if isinstance(leaf, httpx.ConnectTimeout):
+            raise MCPError(
+                code=httpx.codes.REQUEST_TIMEOUT,
+                message="Timed out while waiting for response.",
+            )
+        raise leaf
+
+
+# this catch handler is used to catch taskgroup exception groups and raise the
+# first exception. This allows more sane debugging.
+_catch_handlers: Mapping[
+    type[BaseException] | Iterable[type[BaseException]],
+    Callable[[BaseExceptionGroup[Any]], Any],
+] = {
+    Exception: _exception_handler,
+}
+
+
+def get_catch_handlers() -> Mapping[
+    type[BaseException] | Iterable[type[BaseException]],
+    Callable[[BaseExceptionGroup[Any]], Any],
+]:
+    if fastmcp.settings.client_raise_first_exceptiongroup_error:
+        return _catch_handlers
+    else:
+        return {}
diff --git a/fastmcp_slim/fastmcp/utilities/http.py b/fastmcp_slim/fastmcp/utilities/http.py
new file mode 100644
index 0000000..a6127fd
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/http.py
@@ -0,0 +1,9 @@
+import socket
+
+
+def find_available_port(host: str = "127.0.0.1") -> int:
+    """Find an available port by letting the OS assign one."""
+    family = socket.AF_INET6 if ":" in host else socket.AF_INET
+    with socket.socket(family, socket.SOCK_STREAM) as s:
+        s.bind((host, 0))
+        return s.getsockname()[1]
diff --git a/fastmcp_slim/fastmcp/utilities/inspect.py b/fastmcp_slim/fastmcp/utilities/inspect.py
new file mode 100644
index 0000000..b9e3d08
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/inspect.py
@@ -0,0 +1,526 @@
+"""Utilities for inspecting FastMCP instances."""
+
+from __future__ import annotations
+
+import importlib.metadata
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Literal, cast
+
+import pydantic_core
+from mcp.server.mcpserver import MCPServer as SDKServer
+
+import fastmcp
+from fastmcp import Client
+from fastmcp.server.server import FastMCP
+
+
+@dataclass
+class ToolInfo:
+    """Information about a tool."""
+
+    key: str
+    name: str
+    description: str | None
+    input_schema: dict[str, Any]
+    output_schema: dict[str, Any] | None = None
+    annotations: dict[str, Any] | None = None
+    tags: list[str] | None = None
+    title: str | None = None
+    icons: list[dict[str, Any]] | None = None
+    meta: dict[str, Any] | None = None
+
+
+@dataclass
+class PromptInfo:
+    """Information about a prompt."""
+
+    key: str
+    name: str
+    description: str | None
+    arguments: list[dict[str, Any]] | None = None
+    tags: list[str] | None = None
+    title: str | None = None
+    icons: list[dict[str, Any]] | None = None
+    meta: dict[str, Any] | None = None
+
+
+@dataclass
+class ResourceInfo:
+    """Information about a resource."""
+
+    key: str
+    uri: str
+    name: str | None
+    description: str | None
+    mime_type: str | None = None
+    annotations: dict[str, Any] | None = None
+    tags: list[str] | None = None
+    title: str | None = None
+    icons: list[dict[str, Any]] | None = None
+    meta: dict[str, Any] | None = None
+
+
+@dataclass
+class TemplateInfo:
+    """Information about a resource template."""
+
+    key: str
+    uri_template: str
+    name: str | None
+    description: str | None
+    mime_type: str | None = None
+    parameters: dict[str, Any] | None = None
+    annotations: dict[str, Any] | None = None
+    tags: list[str] | None = None
+    title: str | None = None
+    icons: list[dict[str, Any]] | None = None
+    meta: dict[str, Any] | None = None
+
+
+@dataclass
+class FastMCPInfo:
+    """Information extracted from a FastMCP instance."""
+
+    name: str
+    instructions: str | None
+    version: str | None  # The server's own version string (if specified)
+    website_url: str | None
+    icons: list[dict[str, Any]] | None
+    fastmcp_version: str  # Version of FastMCP generating this manifest
+    mcp_version: str  # Version of MCP protocol library
+    server_generation: int  # Server generation: 1 (mcp package) or 2 (fastmcp)
+    tools: list[ToolInfo]
+    prompts: list[PromptInfo]
+    resources: list[ResourceInfo]
+    templates: list[TemplateInfo]
+    capabilities: dict[str, Any]
+
+
+async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:
+    """Extract information from a FastMCP v2.x instance.
+
+    Args:
+        mcp: The FastMCP v2.x instance to inspect
+
+    Returns:
+        FastMCPInfo dataclass containing the extracted information
+    """
+    # Get all components (list_* includes middleware, enabled/auth filtering)
+    tools_list = await mcp.list_tools()
+    prompts_list = await mcp.list_prompts()
+    resources_list = await mcp.list_resources()
+    templates_list = await mcp.list_resource_templates()
+
+    # Extract detailed tool information
+    tool_infos = []
+    for tool in tools_list:
+        mcp_tool = tool.to_mcp_tool(name=tool.name)
+        tool_infos.append(
+            ToolInfo(
+                key=tool.key,
+                name=tool.name or tool.key,
+                description=tool.description,
+                input_schema=mcp_tool.input_schema if mcp_tool.input_schema else {},
+                output_schema=tool.output_schema,
+                annotations=tool.annotations.model_dump() if tool.annotations else None,
+                tags=list(tool.tags) if tool.tags else None,
+                title=tool.title,
+                icons=[
+                    icon.model_dump(by_alias=True, exclude_none=True)
+                    for icon in tool.icons
+                ]
+                if tool.icons
+                else None,
+                meta=tool.meta,
+            )
+        )
+
+    # Extract detailed prompt information
+    prompt_infos = []
+    for prompt in prompts_list:
+        prompt_infos.append(  # noqa: PERF401
+            PromptInfo(
+                key=prompt.key,
+                name=prompt.name or prompt.key,
+                description=prompt.description,
+                arguments=[arg.model_dump() for arg in prompt.arguments]
+                if prompt.arguments
+                else None,
+                tags=list(prompt.tags) if prompt.tags else None,
+                title=prompt.title,
+                icons=[
+                    icon.model_dump(by_alias=True, exclude_none=True)
+                    for icon in prompt.icons
+                ]
+                if prompt.icons
+                else None,
+                meta=prompt.meta,
+            )
+        )
+
+    # Extract detailed resource information
+    resource_infos = []
+    for resource in resources_list:
+        resource_infos.append(  # noqa: PERF401
+            ResourceInfo(
+                key=resource.key,
+                uri=str(resource.uri),
+                name=resource.name,
+                description=resource.description,
+                mime_type=resource.mime_type,
+                annotations=resource.annotations.model_dump()
+                if resource.annotations
+                else None,
+                tags=list(resource.tags) if resource.tags else None,
+                title=resource.title,
+                icons=[
+                    icon.model_dump(by_alias=True, exclude_none=True)
+                    for icon in resource.icons
+                ]
+                if resource.icons
+                else None,
+                meta=resource.meta,
+            )
+        )
+
+    # Extract detailed template information
+    template_infos = []
+    for template in templates_list:
+        template_infos.append(  # noqa: PERF401
+            TemplateInfo(
+                key=template.key,
+                uri_template=template.uri_template,
+                name=template.name,
+                description=template.description,
+                mime_type=template.mime_type,
+                parameters=template.parameters,
+                annotations=template.annotations.model_dump()
+                if template.annotations
+                else None,
+                tags=list(template.tags) if template.tags else None,
+                title=template.title,
+                icons=[
+                    icon.model_dump(by_alias=True, exclude_none=True)
+                    for icon in template.icons
+                ]
+                if template.icons
+                else None,
+                meta=template.meta,
+            )
+        )
+
+    # Basic MCP capabilities that FastMCP supports
+    capabilities = {
+        "tools": {"listChanged": True},
+        "resources": {"subscribe": False, "listChanged": False},
+        "prompts": {"listChanged": False},
+        "logging": {},
+    }
+
+    # Extract server-level icons and website_url
+    server_icons = (
+        [
+            icon.model_dump(by_alias=True, exclude_none=True)
+            for icon in mcp._mcp_server.icons
+        ]
+        if hasattr(mcp._mcp_server, "icons") and mcp._mcp_server.icons
+        else None
+    )
+    server_website_url = (
+        mcp._mcp_server.website_url if hasattr(mcp._mcp_server, "website_url") else None
+    )
+
+    return FastMCPInfo(
+        name=mcp.name,
+        instructions=mcp.instructions,
+        version=(mcp.version if hasattr(mcp, "version") else mcp._mcp_server.version),
+        website_url=server_website_url,
+        icons=server_icons,
+        fastmcp_version=fastmcp.__version__,
+        mcp_version=importlib.metadata.version("mcp"),
+        server_generation=2,  # FastMCP v2
+        tools=tool_infos,
+        prompts=prompt_infos,
+        resources=resource_infos,
+        templates=template_infos,
+        capabilities=capabilities,
+    )
+
+
+async def inspect_fastmcp_v1(mcp: SDKServer) -> FastMCPInfo:
+    """Extract information from a FastMCP v1.x instance using a Client.
+
+    Args:
+        mcp: The FastMCP v1.x instance to inspect
+
+    Returns:
+        FastMCPInfo dataclass containing the extracted information
+    """
+    # Use a client to interact with the SDK's high-level MCPServer
+    async with Client(mcp) as client:
+        # Get components via client calls (these return MCP objects)
+        mcp_tools = await client.list_tools()
+        mcp_prompts = await client.list_prompts()
+        mcp_resources = await client.list_resources()
+
+        # Try to get resource templates (FastMCP 1.x does have templates)
+        try:
+            mcp_templates = await client.list_resource_templates()
+        except Exception:
+            mcp_templates = []
+
+        # Extract detailed tool information from MCP Tool objects
+        tool_infos = []
+        for mcp_tool in mcp_tools:
+            tool_infos.append(  # noqa: PERF401
+                ToolInfo(
+                    key=mcp_tool.name,
+                    name=mcp_tool.name,
+                    description=mcp_tool.description,
+                    input_schema=mcp_tool.input_schema if mcp_tool.input_schema else {},
+                    output_schema=None,  # v1 doesn't have output_schema
+                    annotations=None,  # v1 doesn't have annotations
+                    tags=None,  # v1 doesn't have tags
+                    title=None,  # v1 doesn't have title
+                    icons=[
+                        icon.model_dump(by_alias=True, exclude_none=True)
+                        for icon in mcp_tool.icons
+                    ]
+                    if hasattr(mcp_tool, "icons") and mcp_tool.icons
+                    else None,
+                    meta=None,  # v1 doesn't have meta field
+                )
+            )
+
+        # Extract detailed prompt information from MCP Prompt objects
+        prompt_infos = []
+        for mcp_prompt in mcp_prompts:
+            # Convert arguments if they exist
+            arguments = None
+            if hasattr(mcp_prompt, "arguments") and mcp_prompt.arguments:
+                arguments = [arg.model_dump() for arg in mcp_prompt.arguments]
+
+            prompt_infos.append(
+                PromptInfo(
+                    key=mcp_prompt.name,
+                    name=mcp_prompt.name,
+                    description=mcp_prompt.description,
+                    arguments=arguments,
+                    tags=None,  # v1 doesn't have tags
+                    title=None,  # v1 doesn't have title
+                    icons=[
+                        icon.model_dump(by_alias=True, exclude_none=True)
+                        for icon in mcp_prompt.icons
+                    ]
+                    if hasattr(mcp_prompt, "icons") and mcp_prompt.icons
+                    else None,
+                    meta=None,  # v1 doesn't have meta field
+                )
+            )
+
+        # Extract detailed resource information from MCP Resource objects
+        resource_infos = []
+        for mcp_resource in mcp_resources:
+            resource_infos.append(  # noqa: PERF401
+                ResourceInfo(
+                    key=str(mcp_resource.uri),
+                    uri=str(mcp_resource.uri),
+                    name=mcp_resource.name,
+                    description=mcp_resource.description,
+                    mime_type=mcp_resource.mime_type,
+                    annotations=None,  # v1 doesn't have annotations
+                    tags=None,  # v1 doesn't have tags
+                    title=None,  # v1 doesn't have title
+                    icons=[
+                        icon.model_dump(by_alias=True, exclude_none=True)
+                        for icon in mcp_resource.icons
+                    ]
+                    if hasattr(mcp_resource, "icons") and mcp_resource.icons
+                    else None,
+                    meta=None,  # v1 doesn't have meta field
+                )
+            )
+
+        # Extract detailed template information from MCP ResourceTemplate objects
+        template_infos = []
+        for mcp_template in mcp_templates:
+            template_infos.append(  # noqa: PERF401
+                TemplateInfo(
+                    key=str(mcp_template.uri_template),
+                    uri_template=str(mcp_template.uri_template),
+                    name=mcp_template.name,
+                    description=mcp_template.description,
+                    mime_type=mcp_template.mime_type,
+                    parameters=None,  # v1 doesn't expose template parameters
+                    annotations=None,  # v1 doesn't have annotations
+                    tags=None,  # v1 doesn't have tags
+                    title=None,  # v1 doesn't have title
+                    icons=[
+                        icon.model_dump(by_alias=True, exclude_none=True)
+                        for icon in mcp_template.icons
+                    ]
+                    if hasattr(mcp_template, "icons") and mcp_template.icons
+                    else None,
+                    meta=None,  # v1 doesn't have meta field
+                )
+            )
+
+        # Basic MCP capabilities
+        capabilities = {
+            "tools": {"listChanged": True},
+            "resources": {"subscribe": False, "listChanged": False},
+            "prompts": {"listChanged": False},
+            "logging": {},
+        }
+
+        # Extract server-level icons and website_url from serverInfo
+        server_info = client.initialize_result.server_info
+        server_icons = (
+            [
+                icon.model_dump(by_alias=True, exclude_none=True)
+                for icon in server_info.icons
+            ]
+            if hasattr(server_info, "icons") and server_info.icons
+            else None
+        )
+        server_website_url = (
+            server_info.website_url if hasattr(server_info, "website_url") else None
+        )
+
+        # SDK v2's MCPServer (FastMCP 1.x) exposes name/instructions/version
+        # directly; the v1 `_mcp_server` low-level wrapper attribute is gone.
+        return FastMCPInfo(
+            name=mcp.name,
+            instructions=mcp.instructions,
+            version=mcp.version,
+            website_url=server_website_url,
+            icons=server_icons,
+            fastmcp_version=fastmcp.__version__,  # Version generating this manifest
+            mcp_version=importlib.metadata.version("mcp"),
+            server_generation=1,  # MCP v1
+            tools=tool_infos,
+            prompts=prompt_infos,
+            resources=resource_infos,
+            templates=template_infos,
+            capabilities=capabilities,
+        )
+
+
+async def inspect_fastmcp(mcp: FastMCP[Any] | SDKServer) -> FastMCPInfo:
+    """Extract information from a FastMCP instance into a dataclass.
+
+    This function automatically detects whether the instance is FastMCP v1.x or v2.x
+    and uses the appropriate extraction method.
+
+    Args:
+        mcp: The FastMCP instance to inspect (v1.x or v2.x)
+
+    Returns:
+        FastMCPInfo dataclass containing the extracted information
+    """
+    if isinstance(mcp, SDKServer):
+        return await inspect_fastmcp_v1(mcp)
+    else:
+        return await inspect_fastmcp_v2(cast(FastMCP[Any], mcp))
+
+
+class InspectFormat(str, Enum):
+    """Output format for inspect command."""
+
+    FASTMCP = "fastmcp"
+    MCP = "mcp"
+
+
+def format_fastmcp_info(info: FastMCPInfo) -> bytes:
+    """Format FastMCPInfo as FastMCP-specific JSON.
+
+    This includes FastMCP-specific fields like tags, enabled, annotations, etc.
+    """
+    # Build the output dict with nested structure
+    result = {
+        "server": {
+            "name": info.name,
+            "instructions": info.instructions,
+            "version": info.version,
+            "website_url": info.website_url,
+            "icons": info.icons,
+            "generation": info.server_generation,
+            "capabilities": info.capabilities,
+        },
+        "environment": {
+            "fastmcp": info.fastmcp_version,
+            "mcp": info.mcp_version,
+        },
+        "tools": info.tools,
+        "prompts": info.prompts,
+        "resources": info.resources,
+        "templates": info.templates,
+    }
+
+    return pydantic_core.to_json(result, indent=2)
+
+
+async def format_mcp_info(mcp: FastMCP[Any] | SDKServer) -> bytes:
+    """Format server info as standard MCP protocol JSON.
+
+    Uses Client to get the standard MCP protocol format with camelCase fields.
+    Includes version metadata at the top level.
+    """
+    async with Client(mcp) as client:
+        # Get all the MCP protocol objects
+        tools_result = await client.list_tools_mcp()
+        prompts_result = await client.list_prompts_mcp()
+        resources_result = await client.list_resources_mcp()
+        templates_result = await client.list_resource_templates_mcp()
+
+        # Get server info from the initialize result
+        server_info = client.initialize_result.server_info
+
+        # Combine into MCP protocol structure with environment metadata
+        result = {
+            "environment": {
+                "fastmcp": fastmcp.__version__,  # Version generating this manifest
+                "mcp": importlib.metadata.version("mcp"),  # MCP protocol version
+            },
+            "serverInfo": server_info,
+            "capabilities": {},  # MCP format doesn't include capabilities at top level
+            "tools": tools_result.tools,
+            "prompts": prompts_result.prompts,
+            "resources": resources_result.resources,
+            "resourceTemplates": templates_result.resource_templates,
+        }
+
+        return pydantic_core.to_json(result, indent=2)
+
+
+async def format_info(
+    mcp: FastMCP[Any] | SDKServer,
+    format: InspectFormat | Literal["fastmcp", "mcp"],
+    info: FastMCPInfo | None = None,
+) -> bytes:
+    """Format server information according to the specified format.
+
+    Args:
+        mcp: The FastMCP instance
+        format: Output format ("fastmcp" or "mcp")
+        info: Pre-extracted FastMCPInfo (optional, will be extracted if not provided)
+
+    Returns:
+        JSON bytes in the requested format
+    """
+    # Convert string to enum if needed
+    if isinstance(format, str):
+        format = InspectFormat(format)
+
+    if format == InspectFormat.MCP:
+        # MCP format doesn't need FastMCPInfo, it uses Client directly
+        return await format_mcp_info(mcp)
+    elif format == InspectFormat.FASTMCP:
+        # For FastMCP format, we need the FastMCPInfo
+        # This works for both v1 and v2 servers
+        if info is None:
+            info = await inspect_fastmcp(mcp)
+        return format_fastmcp_info(info)
+    else:
+        raise ValueError(f"Unknown format: {format}")
diff --git a/fastmcp_slim/fastmcp/utilities/json_schema.py b/fastmcp_slim/fastmcp/utilities/json_schema.py
new file mode 100644
index 0000000..2cd604e
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/json_schema.py
@@ -0,0 +1,728 @@
+from __future__ import annotations
+
+import copy
+from collections import defaultdict
+from typing import Any
+
+from jsonref import JsonRefError, replace_refs
+
+
+def _defs_have_cycles(defs: dict[str, Any]) -> bool:
+    """Check whether any definitions in ``$defs`` form a reference cycle.
+
+    A cycle means a definition directly or transitively references itself
+    (e.g. Node → children → Node, or A → B → A).  ``jsonref.replace_refs``
+    silently produces Python-level object cycles for these, which Pydantic's
+    serializer rejects.
+    """
+    if not defs:
+        return False
+
+    # Build adjacency: def_name -> set of def_names it references.
+    edges: dict[str, set[str]] = defaultdict(set)
+
+    def _collect_refs(obj: Any, source: str) -> None:
+        if isinstance(obj, dict):
+            ref = obj.get("$ref")
+            if isinstance(ref, str) and ref.startswith("#/$defs/"):
+                edges[source].add(ref.split("/")[-1])
+            for v in obj.values():
+                _collect_refs(v, source)
+        elif isinstance(obj, list):
+            for item in obj:
+                _collect_refs(item, source)
+
+    for name, definition in defs.items():
+        _collect_refs(definition, name)
+
+    # DFS cycle detection.
+    UNVISITED, IN_STACK, DONE = 0, 1, 2
+    state: dict[str, int] = defaultdict(int)
+
+    def _has_cycle(node: str) -> bool:
+        state[node] = IN_STACK
+        for neighbor in edges.get(node, ()):
+            if neighbor not in defs:
+                continue
+            if state[neighbor] == IN_STACK:
+                return True
+            if state[neighbor] == UNVISITED and _has_cycle(neighbor):
+                return True
+        state[node] = DONE
+        return False
+
+    return any(state[name] == UNVISITED and _has_cycle(name) for name in defs)
+
+
+def _strip_remote_refs(obj: Any) -> Any:
+    """Return a deep copy of *obj* with non-local ``$ref`` values removed.
+
+    Local refs (starting with ``#``) are kept intact.  Remote refs
+    (``http://``, ``https://``, ``file://``, or any other URI scheme) are
+    stripped so that ``jsonref.replace_refs`` never attempts to fetch an
+    external resource.  This prevents SSRF / LFI when proxying schemas
+    from untrusted servers.
+    """
+    if isinstance(obj, dict):
+        ref = obj.get("$ref")
+        if isinstance(ref, str) and not ref.startswith("#"):
+            # Drop the remote $ref key; keep all other keys.
+            return {k: _strip_remote_refs(v) for k, v in obj.items() if k != "$ref"}
+        return {k: _strip_remote_refs(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_strip_remote_refs(item) for item in obj]
+    return obj
+
+
+def _strip_discriminator(obj: Any) -> Any:
+    """Recursively remove OpenAPI ``discriminator`` keys from a schema.
+
+    Pydantic emits ``discriminator.mapping`` with values like
+    ``#/$defs/ClassName``.  After ``$defs`` are inlined and removed by
+    ``dereference_refs``, those mapping entries dangle.  The keyword is an
+    OpenAPI extension — the ``anyOf`` variants already carry ``const`` on
+    the discriminant field, so the mapping is redundant.
+
+    Only strips ``discriminator`` when it appears alongside ``anyOf`` or
+    ``oneOf``, which is where the OpenAPI keyword lives.  A property
+    *named* ``discriminator`` (inside ``properties``) is left alone.
+    """
+    if isinstance(obj, dict):
+        skip = "discriminator" in obj and ("anyOf" in obj or "oneOf" in obj)
+        if skip:
+            obj = require_discriminator_property(obj)
+        # Keys that hold instance data, not sub-schemas — don't recurse.
+        _DATA_KEYS = {"default", "const", "examples", "enum"}
+        return {
+            k: (v if k in _DATA_KEYS else _strip_discriminator(v))
+            for k, v in obj.items()
+            if not (k == "discriminator" and skip)
+        }
+    if isinstance(obj, list):
+        return [_strip_discriminator(item) for item in obj]
+    return obj
+
+
+def _require_property(schema: dict[str, Any], property_name: str) -> dict[str, Any]:
+    """Return a copy of *schema* with *property_name* in ``required``."""
+    required = schema.get("required")
+    if required is None:
+        return {**schema, "required": [property_name]}
+    if isinstance(required, list) and property_name not in required:
+        return {**schema, "required": [*required, property_name]}
+    return schema
+
+
+def require_discriminator_property(schema: dict[str, Any]) -> dict[str, Any]:
+    """Keep an OpenAPI discriminator's tag mandatory after the keyword is dropped.
+
+    Returns a copy of *schema* with ``discriminator.propertyName`` added to each
+    ``anyOf``/``oneOf`` variant's ``required`` list. A Pydantic discriminated
+    union whose tag has a default omits that tag from ``required``; without this,
+    an untagged payload passes the generated schema but fails later in the source
+    model with ``union_tag_not_found``. No-op if there is no string
+    ``propertyName``.
+    """
+    discriminator = schema.get("discriminator")
+    if not isinstance(discriminator, dict):
+        return schema
+    property_name = discriminator.get("propertyName")
+    if not isinstance(property_name, str):
+        return schema
+
+    result = schema.copy()
+    for key in ("anyOf", "oneOf"):
+        variants = result.get(key)
+        if not isinstance(variants, list):
+            continue
+        result[key] = [
+            _require_property(variant, property_name)
+            if isinstance(variant, dict)
+            else variant
+            for variant in variants
+        ]
+    return result
+
+
+def dereference_refs(schema: dict[str, Any]) -> dict[str, Any]:
+    """Resolve all $ref references in a JSON schema by inlining definitions.
+
+    This function resolves $ref references that point to $defs, replacing them
+    with the actual definition content while preserving sibling keywords (like
+    description, default, examples) that Pydantic places alongside $ref.
+
+    This is necessary because some MCP clients (e.g., VS Code Copilot) don't
+    properly handle $ref in tool input schemas.
+
+    For self-referencing/circular schemas where full dereferencing is not possible,
+    this function falls back to resolving only the root-level $ref while preserving
+    $defs for nested references.
+
+    Only local ``$ref`` values (those starting with ``#``) are resolved.
+    Remote URIs (``http://``, ``file://``, etc.) are stripped before
+    resolution to prevent SSRF / local-file-inclusion attacks when proxying
+    schemas from untrusted servers.
+
+    Args:
+        schema: JSON schema dict that may contain $ref references
+
+    Returns:
+        A new schema dict with $ref resolved where possible and $defs removed
+        when no longer needed
+
+    Example:
+        >>> schema = {
+        ...     "$defs": {"Category": {"enum": ["a", "b"], "type": "string"}},
+        ...     "properties": {"cat": {"$ref": "#/$defs/Category", "default": "a"}}
+        ... }
+        >>> resolved = dereference_refs(schema)
+        >>> # Result: {"properties": {"cat": {"enum": ["a", "b"], "type": "string", "default": "a"}}}
+    """
+    # Strip any remote $ref values before processing to prevent SSRF / LFI.
+    schema = _strip_remote_refs(schema)
+
+    # Circular $defs can't be fully inlined — jsonref.replace_refs produces
+    # Python dicts with object-identity cycles that Pydantic's model_dump
+    # rejects with "Circular reference detected (id repeated)".
+    # Detect cycles up front and fall back to root-only resolution.
+    if _defs_have_cycles(schema.get("$defs", {})):
+        return resolve_root_ref(schema)
+
+    try:
+        # Use jsonref to resolve all $ref references
+        # proxies=False returns plain dicts (not proxy objects)
+        # lazy_load=False resolves immediately
+        dereferenced = replace_refs(schema, proxies=False, lazy_load=False)
+
+        # Merge sibling keywords that were lost during dereferencing
+        # Pydantic puts description, default, examples as siblings to $ref
+        defs = schema.get("$defs", {})
+        merged = _merge_ref_siblings(schema, dereferenced, defs)
+        # Type assertion: top-level schema is always a dict
+        assert isinstance(merged, dict)
+        dereferenced = merged
+
+        # Remove $defs since all references have been resolved
+        if "$defs" in dereferenced:
+            dereferenced = {k: v for k, v in dereferenced.items() if k != "$defs"}
+
+        # Strip `discriminator` keys — they contain `mapping` values that
+        # point at `#/$defs/...` entries we just removed.  `discriminator`
+        # is an OpenAPI extension; after inlining, the `anyOf` variants
+        # already carry `const` on the discriminant field, making the
+        # mapping redundant.
+        dereferenced = _strip_discriminator(dereferenced)
+
+        return dereferenced
+
+    except (JsonRefError, RecursionError):
+        # Self-referencing/circular schemas can't be fully dereferenced.
+        # RecursionError covers circular $ref using JSON Pointer paths
+        # (e.g. "#/properties/nodes/items") that bypass $defs-based cycle
+        # detection — common in schemas from .NET/System.Text.Json.
+        # Fall back to resolving only root-level $ref (for MCP spec compliance)
+        return resolve_root_ref(schema)
+
+
+def _merge_ref_siblings(
+    original: Any,
+    dereferenced: Any,
+    defs: dict[str, Any],
+    visited: set[str] | None = None,
+) -> Any:
+    """Merge sibling keywords from original $ref nodes into dereferenced schema.
+
+    When jsonref resolves $ref, it replaces the entire node with the referenced
+    definition, losing any sibling keywords like description, default, or examples.
+    This function walks both trees in parallel and merges those siblings back.
+
+    Args:
+        original: The original schema with $ref and potential siblings
+        dereferenced: The schema after jsonref processing
+        defs: The $defs from the original schema, for looking up referenced definitions
+        visited: Set of definition names already being processed (prevents cycles)
+
+    Returns:
+        The dereferenced schema with sibling keywords restored
+    """
+    if visited is None:
+        visited = set()
+
+    if isinstance(original, dict) and isinstance(dereferenced, dict):
+        # Check if original had a $ref
+        if "$ref" in original:
+            ref = original["$ref"]
+            siblings = {k: v for k, v in original.items() if k not in ("$ref", "$defs")}
+
+            # Look up the referenced definition to process its nested siblings
+            if isinstance(ref, str) and ref.startswith("#/$defs/"):
+                def_name = ref.split("/")[-1]
+                # Prevent infinite recursion on circular references
+                if def_name in defs and def_name not in visited:
+                    # Recursively process the definition's content for nested siblings
+                    dereferenced = _merge_ref_siblings(
+                        defs[def_name], dereferenced, defs, visited | {def_name}
+                    )
+
+            if siblings:
+                # Merge local siblings, which take precedence
+                merged = dict(dereferenced)
+                merged.update(siblings)
+                return merged
+            return dereferenced
+
+        # Recurse into nested structures
+        result = {}
+        for key, value in dereferenced.items():
+            if key in original:
+                result[key] = _merge_ref_siblings(original[key], value, defs, visited)
+            else:
+                result[key] = value
+        return result
+
+    elif isinstance(original, list) and isinstance(dereferenced, list):
+        # Process list items in parallel
+        min_len = min(len(original), len(dereferenced))
+        return [
+            _merge_ref_siblings(o, d, defs, visited)
+            for o, d in zip(original[:min_len], dereferenced[:min_len], strict=False)
+        ] + dereferenced[min_len:]
+
+    return dereferenced
+
+
+def resolve_root_ref(schema: dict[str, Any]) -> dict[str, Any]:
+    """Resolve $ref at root level to meet MCP spec requirements.
+
+    MCP specification requires outputSchema to have "type": "object" at the root level.
+    When Pydantic generates schemas for self-referential models, it uses $ref at the
+    root level pointing to $defs. This function resolves such references by inlining
+    the referenced definition while preserving $defs for nested references.
+
+    Args:
+        schema: JSON schema dict that may have $ref at root level
+
+    Returns:
+        A new schema dict with root-level $ref resolved, or the original schema
+        if no resolution is needed
+
+    Example:
+        >>> schema = {
+        ...     "$defs": {"Node": {"type": "object", "properties": {...}}},
+        ...     "$ref": "#/$defs/Node"
+        ... }
+        >>> resolved = resolve_root_ref(schema)
+        >>> # Result: {"type": "object", "properties": {...}, "$defs": {...}}
+    """
+    # Only resolve if we have $ref at root level with $defs but no explicit type
+    if "$ref" in schema and "$defs" in schema and "type" not in schema:
+        ref = schema["$ref"]
+        # Only handle local $defs references
+        if isinstance(ref, str) and ref.startswith("#/$defs/"):
+            def_name = ref.split("/")[-1]
+            defs = schema["$defs"]
+            if def_name in defs:
+                # Create a new schema by copying the referenced definition
+                resolved = dict(defs[def_name])
+
+                # Preserve root-level sibling metadata from the original schema.
+                # Pydantic may put user-facing fields such as title, description,
+                # default, or examples next to the root $ref. Those fields still
+                # describe the root schema even when we can only resolve that
+                # root reference for circular schemas.
+                resolved.update(
+                    {
+                        key: value
+                        for key, value in schema.items()
+                        if key not in {"$ref", "$defs"}
+                    }
+                )
+
+                # Preserve $defs for nested references (other fields may still use them)
+                resolved["$defs"] = defs
+                return resolved
+    return schema
+
+
+def _prune_param(schema: dict[str, Any], param: str) -> dict[str, Any]:
+    """Return a new schema with *param* removed from `properties`, `required`,
+    and (if no longer referenced) `$defs`.
+    """
+    schema = copy.deepcopy(schema)
+
+    # ── 1. drop from properties/required ──────────────────────────────
+    props = schema.get("properties", {})
+    removed = props.pop(param, None)
+    if removed is None:  # nothing to do
+        return schema
+
+    # Keep empty properties object rather than removing it entirely
+    schema["properties"] = props
+    if param in schema.get("required", []):
+        schema["required"].remove(param)
+        if not schema["required"]:
+            schema.pop("required")
+
+    return schema
+
+
+# JSON Schema structural keywords — a node containing any of these is a
+# schema, so a string "title" sibling is metadata we can safely drop.
+_SCHEMA_KEYWORDS = frozenset(
+    {
+        "type",
+        "properties",
+        "$ref",
+        "items",
+        "allOf",
+        "oneOf",
+        "anyOf",
+        "required",
+    }
+)
+
+# Pure schema-metadata keys. A node containing only these (e.g. Pydantic's
+# `{"title": "X"}` for Any-typed fields) is also a schema, just one with no
+# structural keywords alongside — still safe to strip title from.
+_METADATA_KEYS = frozenset(
+    {
+        "title",
+        "description",
+        "deprecated",
+        "readOnly",
+        "writeOnly",
+    }
+)
+
+# Keywords whose values are literal user data, not sub-schemas. Skipping
+# recursion here prevents `default: {"title": "X"}` from losing the "title"
+# data value because it happens to look metadata-shaped. Includes both
+# `examples` (JSON Schema draft 7+) and `example` (OpenAPI/Swagger 2.0).
+_LITERAL_KEYWORDS = frozenset({"default", "const", "examples", "example", "enum"})
+
+# Keys whose values are dicts of arbitrary-name -> sub-schema. When we see
+# these, we traverse into each sub-schema regardless of its name — the keys
+# are user property/definition names, not schema keywords, so a property
+# literally named "enum" or "default" must not be confused with the
+# schema keywords of the same name.
+#
+# `dependencies` is a draft-07 keyword whose values can be sub-schemas OR
+# lists of required property names; list values short-circuit in the list
+# branch, so including it here is safe for both shapes.
+_SUBSCHEMA_MAP_KEYS = frozenset(
+    {
+        "properties",
+        "patternProperties",
+        "$defs",
+        "definitions",
+        "dependentSchemas",
+        "dependencies",
+    }
+)
+
+# Keys whose values are a single sub-schema (not a dict of sub-schemas).
+# We traverse into them and treat the result as a schema node.
+# `additionalItems` is the draft-07 predecessor of `unevaluatedItems`.
+# `contentSchema` is a 2019-09+ keyword for typed string payloads.
+_SUBSCHEMA_VALUE_KEYS = frozenset(
+    {
+        "items",
+        "additionalItems",
+        "additionalProperties",
+        "contains",
+        "contentSchema",
+        "propertyNames",
+        "unevaluatedItems",
+        "unevaluatedProperties",
+        "if",
+        "then",
+        "else",
+        "not",
+    }
+)
+
+# Keys whose values are LISTS of sub-schemas.
+_SUBSCHEMA_LIST_KEYS = frozenset({"allOf", "anyOf", "oneOf", "prefixItems"})
+
+
+def _single_pass_optimize(
+    schema: dict[str, Any],
+    prune_titles: bool = False,
+    prune_additional_properties: bool = False,
+    prune_defs: bool = True,
+) -> dict[str, Any]:
+    """
+    Optimize JSON schemas in a single traversal for better performance.
+
+    This function combines three schema cleanup operations that would normally require
+    separate tree traversals:
+
+    1. **Remove unused definitions** (prune_defs): Finds and removes `$defs` entries
+       that aren't referenced anywhere in the schema, reducing schema size.
+
+    2. **Remove titles** (prune_titles): Strips `title` fields throughout the schema
+       to reduce verbosity while preserving functional information.
+
+    3. **Remove restrictive additionalProperties** (prune_additional_properties):
+       Removes `"additionalProperties": false` constraints to make schemas more flexible.
+
+    **Performance Benefits:**
+    - Single tree traversal instead of multiple passes (2-3x faster)
+    - Immutable design prevents shared reference bugs
+    - Early termination prevents runaway recursion on deeply nested schemas
+
+    **Algorithm Overview:**
+    1. Traverse main schema, collecting $ref references and applying cleanups
+    2. Traverse $defs section to map inter-definition dependencies
+    3. Remove unused definitions based on reference analysis
+
+    Args:
+        schema: JSON schema dict to optimize (not modified)
+        prune_titles: Remove title fields for cleaner output
+        prune_additional_properties: Remove "additionalProperties": false constraints
+        prune_defs: Remove unused $defs entries to reduce size
+
+    Returns:
+        A new optimized schema dict
+
+    Example:
+        >>> schema = {
+        ...     "type": "object",
+        ...     "title": "MySchema",
+        ...     "additionalProperties": False,
+        ...     "$defs": {"UnusedDef": {"type": "string"}}
+        ... }
+        >>> result = _single_pass_optimize(schema, prune_titles=True, prune_defs=True)
+        >>> # Result: {"type": "object", "additionalProperties": False}
+    """
+    if not (prune_defs or prune_titles or prune_additional_properties):
+        return schema  # Nothing to do
+
+    # Phase 1: Collect references and apply simple cleanups
+    # Track which $defs are referenced from the main schema and from other $defs
+    root_refs: set[str] = set()  # $defs referenced directly from main schema
+    def_dependencies: defaultdict[str, list[str]] = defaultdict(
+        list
+    )  # def A references def B
+    defs = schema.get("$defs")
+
+    def traverse_and_clean(
+        node: object,
+        current_def_name: str | None = None,
+        skip_defs_section: bool = False,
+        depth: int = 0,
+        in_schema: bool = True,
+    ) -> None:
+        """Traverse schema tree, collecting $ref info and applying cleanups.
+
+        The `in_schema` flag tracks whether the current node is reached via a
+        known JSON-Schema-valued position (root, `properties` value, `items`,
+        `allOf` element, etc.). When False — e.g. we descended through a user
+        extension key like `x-ui` whose payload is opaque to us — we still
+        collect `$ref` references (they may point at `$defs` the user cares
+        about) but we skip all cleanups so we don't mutate user data that
+        happens to look metadata-shaped.
+        """
+        if depth > 50:  # Prevent infinite recursion
+            return
+
+        if isinstance(node, dict):
+            # Collect $ref references for unused definition removal. We do
+            # this regardless of `in_schema` — a $ref in a user extension
+            # still pins the referenced $def as "used".
+            if prune_defs:
+                ref = node.get("$ref")
+                if isinstance(ref, str) and ref.startswith("#/$defs/"):
+                    referenced_def = ref.split("/")[-1]
+                    if current_def_name:
+                        # We're inside a $def, so this is a def->def reference
+                        def_dependencies[referenced_def].append(current_def_name)
+                    else:
+                        # We're in the main schema, so this is a root reference
+                        root_refs.add(referenced_def)
+
+            # Cleanups only run when we know this node is a schema, never on
+            # user extension payloads (`json_schema_extra={"x-ui": {...}}`).
+            if in_schema:
+                # Only remove "title" when it's schema metadata. A schema
+                # node is either (a) one containing a structural keyword or
+                # (b) one containing only metadata keys — Pydantic emits
+                # bare `{"title": "X"}` for Any-typed fields with no sibling
+                # type/properties, and Gemini 2.5 Flash rejects those with
+                # MALFORMED_FUNCTION_CALL. The `isinstance(str)` guard
+                # protects against deleting a user property literally named
+                # "title" (its value would be a dict, not a string).
+                if (
+                    prune_titles
+                    and "title" in node
+                    and isinstance(node["title"], str)  # type: ignore
+                    and (
+                        any(k in node for k in _SCHEMA_KEYWORDS)
+                        or all(k in _METADATA_KEYS for k in node)
+                    )
+                ):
+                    node.pop("title")  # type: ignore
+
+                if (
+                    prune_additional_properties
+                    and node.get("additionalProperties") is False
+                ):
+                    node.pop("additionalProperties")  # type: ignore
+
+            # Recursive traversal
+            for key, value in node.items():
+                if skip_defs_section and key == "$defs":
+                    continue  # Skip $defs during main schema traversal
+
+                # If we're not in a schema context, keep $ref-collecting but
+                # don't promote sub-values to schema context — user extension
+                # payloads can contain anything and must not be interpreted
+                # as schemas.
+                if not in_schema:
+                    traverse_and_clean(
+                        value, current_def_name, depth=depth + 1, in_schema=False
+                    )
+                    continue
+
+                # Arbitrary-key dicts of sub-schemas. The keys are user names
+                # (property/definition names), not schema keywords, so we
+                # must NOT apply the literal-keyword skip to them — a user
+                # property named "enum" or "default" still needs its
+                # sub-schema traversed (e.g. to collect $ref references).
+                if key in _SUBSCHEMA_MAP_KEYS and isinstance(value, dict):
+                    for sub_schema in value.values():
+                        traverse_and_clean(
+                            sub_schema,
+                            current_def_name,
+                            depth=depth + 1,
+                            in_schema=True,
+                        )
+                    continue
+
+                # Don't descend into keywords that carry literal data, not
+                # sub-schemas — `default: {"title": "X"}` is a user value,
+                # not schema metadata, and stripping "title" there would
+                # corrupt it.
+                if key in _LITERAL_KEYWORDS:
+                    continue
+
+                # Keywords whose values are sub-schemas (or lists thereof).
+                if key in _SUBSCHEMA_LIST_KEYS and isinstance(value, list):
+                    for item in value:
+                        traverse_and_clean(
+                            item,
+                            current_def_name,
+                            depth=depth + 1,
+                            in_schema=True,
+                        )
+                    continue
+
+                if key in _SUBSCHEMA_VALUE_KEYS:
+                    traverse_and_clean(
+                        value,
+                        current_def_name,
+                        depth=depth + 1,
+                        in_schema=True,
+                    )
+                    continue
+
+                # Unknown keys (user extensions like `x-ui`, vendor
+                # metadata, etc.) — descend for $ref collection but mark
+                # in_schema=False so cleanups don't touch user payloads.
+                traverse_and_clean(
+                    value, current_def_name, depth=depth + 1, in_schema=False
+                )
+
+        elif isinstance(node, list):
+            for item in node:
+                traverse_and_clean(
+                    item, current_def_name, depth=depth + 1, in_schema=in_schema
+                )
+
+    # Phase 2: Traverse main schema (excluding $defs section)
+    traverse_and_clean(schema, skip_defs_section=True, in_schema=True)
+
+    # Phase 3: Traverse $defs to find inter-definition references
+    if prune_defs and defs:
+        for def_name, def_schema in defs.items():
+            traverse_and_clean(def_schema, current_def_name=def_name, in_schema=True)
+
+        # Phase 4: Remove unused definitions
+        def is_def_used(def_name: str, visiting: set[str] | None = None) -> bool:
+            """Check if a definition is used, handling circular references."""
+            if def_name in root_refs:
+                return True  # Used directly from main schema
+
+            # Check if any definition that references this one is itself used
+            referencing_defs = def_dependencies.get(def_name, [])
+            if referencing_defs:
+                if visiting is None:
+                    visiting = set()
+
+                # Avoid infinite recursion on circular references
+                if def_name in visiting:
+                    return False
+                visiting = visiting | {def_name}
+
+                # If any referencing def is used, then this def is used
+                for referencing_def in referencing_defs:
+                    if referencing_def not in visiting and is_def_used(
+                        referencing_def, visiting
+                    ):
+                        return True
+
+            return False
+
+        # Remove unused definitions
+        for def_name in list(defs.keys()):
+            if not is_def_used(def_name):
+                defs.pop(def_name)
+
+        # Clean up empty $defs section
+        if not defs:
+            schema.pop("$defs", None)
+
+    return schema
+
+
+def compress_schema(
+    schema: dict[str, Any],
+    prune_params: list[str] | None = None,
+    prune_additional_properties: bool = False,
+    prune_titles: bool = False,
+    dereference: bool = False,
+) -> dict[str, Any]:
+    """
+    Compress and optimize a JSON schema for MCP compatibility.
+
+    Args:
+        schema: The schema to compress
+        prune_params: List of parameter names to remove from properties
+        prune_additional_properties: Whether to remove additionalProperties: false.
+            Defaults to False to maintain MCP client compatibility, as some clients
+            (e.g., Claude) require additionalProperties: false for strict validation.
+        prune_titles: Whether to remove title fields from the schema
+        dereference: Whether to dereference $ref by inlining definitions.
+            Defaults to False; dereferencing is typically handled by
+            middleware at serve-time instead.
+    """
+    if dereference:
+        schema = dereference_refs(schema)
+
+    # Resolve root-level $ref for MCP spec compliance (requires type: object at root)
+    schema = resolve_root_ref(schema)
+
+    # Remove specific parameters if requested
+    for param in prune_params or []:
+        schema = _prune_param(schema, param=param)
+
+    # Apply combined optimizations in a single tree traversal.
+    # Always prune unused $defs to keep schemas clean after parameter removal.
+    schema = _single_pass_optimize(
+        schema,
+        prune_titles=prune_titles,
+        prune_additional_properties=prune_additional_properties,
+        prune_defs=True,
+    )
+
+    return schema
diff --git a/fastmcp_slim/fastmcp/utilities/json_schema_type.py b/fastmcp_slim/fastmcp/utilities/json_schema_type.py
new file mode 100644
index 0000000..de1db29
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/json_schema_type.py
@@ -0,0 +1,819 @@
+"""Convert JSON Schema to Python types with validation.
+
+The json_schema_to_type function converts a JSON Schema into a Python type that can be used
+for validation with Pydantic. It supports:
+
+- Basic types (string, number, integer, boolean, null)
+- Complex types (arrays, objects)
+- Format constraints (date-time, email, uri)
+- Numeric constraints (minimum, maximum, multipleOf)
+- String constraints (minLength, maxLength, pattern)
+- Array constraints (minItems, maxItems, uniqueItems)
+- Object properties with defaults
+- References and recursive schemas
+- Enums and constants
+- Union types
+
+## Unsupported regex patterns
+
+Pydantic uses a Rust-based regex engine that does not support all regex
+features found in real-world JSON Schemas (particularly those from AWS,
+Azure, and other large OpenAPI providers). Unsupported constructs include
+lookahead/lookbehind assertions (`(?!...)`, `(?<=...)`), Unicode property
+escapes (`\\p{Graph}`, `\\p{Print}`), and very large compiled patterns.
+
+When a `pattern` constraint cannot be compiled, `json_schema_to_type`
+degrades gracefully:
+
+1. The pattern is **dropped** from the Pydantic `StringConstraints` so
+   the type will not raise a `SchemaError`.
+2. A `UserWarning` is emitted with the unsupported pattern.
+3. The original pattern is preserved in the type metadata as
+   `x-unsupported-pattern` (visible via `TypeAdapter(T).json_schema()`).
+4. Other constraints (`minLength`, `maxLength`) are still enforced.
+
+Example:
+    ```python
+    schema = {
+        "type": "object",
+        "properties": {
+            "name": {"type": "string", "minLength": 1},
+            "age": {"type": "integer", "minimum": 0},
+            "email": {"type": "string", "format": "email"}
+        },
+        "required": ["name", "age"]
+    }
+
+    # Name is optional and will be inferred from schema's "title" property if not provided
+    Person = json_schema_to_type(schema)
+    # Creates a validated dataclass with name, age, and optional email fields
+    ```
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import keyword
+import re
+import warnings
+from collections.abc import Callable, Mapping
+from copy import deepcopy
+from dataclasses import MISSING, field, make_dataclass
+from datetime import date, datetime
+from typing import (
+    Annotated,
+    Any,
+    ForwardRef,
+    Literal,
+    Union,
+    cast,
+)
+
+from pydantic import (
+    AnyUrl,
+    BaseModel,
+    BeforeValidator,
+    ConfigDict,
+    EmailStr,
+    Field,
+    Json,
+    StringConstraints,
+    TypeAdapter,
+    model_validator,
+)
+from pydantic_core import SchemaError as _PydanticSchemaError
+from typing_extensions import NotRequired, TypedDict
+
+__all__ = ["JSONSchema", "json_schema_to_type"]
+
+
+def _normalize_yaml_types(obj: Any) -> Any:
+    """Convert YAML-parsed types back to JSON-native types.
+
+    ``yaml.safe_load`` converts ISO date-time strings to ``datetime``/``date``
+    objects.  These crash ``json.dumps`` and produce wrong default values in
+    dataclass fields.  This function recursively normalises them to strings.
+    """
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    if isinstance(obj, date):
+        return obj.isoformat()
+    if isinstance(obj, dict):
+        return {
+            str(k) if not isinstance(k, str) else k: _normalize_yaml_types(v)
+            for k, v in obj.items()
+        }
+    if isinstance(obj, list):
+        return [_normalize_yaml_types(v) for v in obj]
+    return obj
+
+
+def _reject_all(v: Any) -> Any:
+    """Validator that rejects every value, implementing JSON Schema `false`."""
+    raise ValueError("No value is valid against a false schema")
+
+
+# JSON Schema `false` means no value is valid. This type rejects everything
+# during Pydantic validation.
+_UnsatisfiableType = Annotated[Any, BeforeValidator(_reject_all)]
+
+FORMAT_TYPES: dict[str, Any] = {
+    "date-time": datetime,
+    "email": EmailStr,
+    "uri": AnyUrl,
+    "json": Json,
+}
+
+_classes: dict[tuple[str, Any], type | None] = {}
+
+
+class JSONSchema(TypedDict):
+    type: NotRequired[str | list[str]]
+    properties: NotRequired[dict[str, JSONSchema]]
+    required: NotRequired[list[str]]
+    additionalProperties: NotRequired[bool | JSONSchema]
+    items: NotRequired[JSONSchema | list[JSONSchema]]
+    enum: NotRequired[list[Any]]
+    const: NotRequired[Any]
+    default: NotRequired[Any]
+    description: NotRequired[str]
+    title: NotRequired[str]
+    examples: NotRequired[list[Any]]
+    format: NotRequired[str]
+    allOf: NotRequired[list[JSONSchema]]
+    anyOf: NotRequired[list[JSONSchema]]
+    oneOf: NotRequired[list[JSONSchema]]
+    not_: NotRequired[JSONSchema]
+    definitions: NotRequired[dict[str, JSONSchema]]
+    dependencies: NotRequired[dict[str, JSONSchema | list[str]]]
+    pattern: NotRequired[str]
+    minLength: NotRequired[int]
+    maxLength: NotRequired[int]
+    minimum: NotRequired[int | float]
+    maximum: NotRequired[int | float]
+    exclusiveMinimum: NotRequired[int | float]
+    exclusiveMaximum: NotRequired[int | float]
+    multipleOf: NotRequired[int | float]
+    uniqueItems: NotRequired[bool]
+    minItems: NotRequired[int]
+    maxItems: NotRequired[int]
+    additionalItems: NotRequired[bool | JSONSchema]
+
+
+def json_schema_to_type(
+    schema: Mapping[str, Any] | bool,
+    name: str | None = None,
+) -> type:
+    """Convert JSON schema to appropriate Python type with validation.
+
+    Args:
+        schema: A JSON Schema dictionary defining the type structure and validation rules.
+            Boolean schemas are also accepted (``True`` = any type, ``False`` = unsatisfiable).
+        name: Optional name for object schemas. Only allowed when schema type is "object".
+            If not provided for objects, name will be inferred from schema's "title"
+            property or default to "Root".
+
+    Returns:
+        A Python type (typically a dataclass for objects) with Pydantic validation
+
+    Raises:
+        ValueError: If a name is provided for a non-object schema
+
+    Examples:
+        Create a dataclass from an object schema:
+        ```python
+        schema = {
+            "type": "object",
+            "title": "Person",
+            "properties": {
+                "name": {"type": "string", "minLength": 1},
+                "age": {"type": "integer", "minimum": 0},
+                "email": {"type": "string", "format": "email"}
+            },
+            "required": ["name", "age"]
+        }
+
+        Person = json_schema_to_type(schema)
+        # Creates a dataclass with name, age, and optional email fields:
+        # @dataclass
+        # class Person:
+        #     name: str
+        #     age: int
+        #     email: str | None = None
+        ```
+        Person(name="John", age=30)
+
+        Create a scalar type with constraints:
+        ```python
+        schema = {
+            "type": "string",
+            "minLength": 3,
+            "pattern": "^[A-Z][a-z]+$"
+        }
+
+        NameType = json_schema_to_type(schema)
+        # Creates Annotated[str, StringConstraints(min_length=3, pattern="^[A-Z][a-z]+$")]
+
+        @dataclass
+        class Name:
+            name: NameType
+        ```
+    """
+    # Boolean schemas (JSON Schema 2020-12 §4.3.2; also valid since draft-06)
+    if schema is True:
+        return Any
+    if schema is False:
+        return _UnsatisfiableType  # type: ignore[return-value]  # ty:ignore[invalid-return-type]
+
+    # Normalise YAML-parsed types (datetime/date → str, non-str keys → str)
+    # so that downstream json.dumps/hashing and default values work correctly.
+    schema = _normalize_yaml_types(schema)
+
+    # Always use the top-level schema for references
+    if schema.get("type") == "object":
+        return _object_schema_to_type(schema, schemas=schema, name=name)
+    elif name:
+        raise ValueError(f"Can not apply name to non-object schema: {name}")
+    result = _schema_to_type(schema, schemas=schema)
+    return result  # type: ignore[return-value]  # ty:ignore[invalid-return-type]
+
+
+def _hash_schema(schema: Mapping[str, Any]) -> str:
+    """Generate a deterministic hash for schema caching.
+
+    Handles non-JSON-native types (datetime, date, bool keys) that can
+    appear in schemas loaded from YAML, which auto-parses date strings.
+    Uses ``default=str`` for unserializable values and drops ``sort_keys``
+    to avoid ``TypeError`` when dicts mix ``bool`` and ``str`` keys.
+    """
+    try:
+        raw = json.dumps(schema, sort_keys=True, default=str)
+    except TypeError:
+        # Mixed key types (bool + str) can't be sorted; fall back
+        raw = json.dumps(schema, default=str)
+    return hashlib.sha256(raw.encode()).hexdigest()
+
+
+def _resolve_ref(ref: str, schemas: Mapping[str, Any]) -> Mapping[str, Any]:
+    """Resolve JSON Schema reference to target schema."""
+    path = ref.replace("#/", "").split("/")
+    current = schemas
+    for part in path:
+        current = current.get(part, {})
+    return current
+
+
+def _create_string_type(schema: Mapping[str, Any]) -> type | Annotated[Any, ...]:
+    """Create string type with optional constraints."""
+    if "const" in schema:
+        return Literal[schema["const"]]  # type: ignore
+
+    if fmt := schema.get("format"):
+        if fmt == "uri":
+            return AnyUrl
+        elif fmt == "uri-reference":
+            return str
+        return FORMAT_TYPES.get(fmt, str)
+
+    constraints = {
+        k: v
+        for k, v in {
+            "min_length": schema.get("minLength"),
+            "max_length": schema.get("maxLength"),
+            "pattern": schema.get("pattern"),
+        }.items()
+        if v is not None
+    }
+
+    if not constraints:
+        return str
+
+    annotated: Any = Annotated[str, StringConstraints(**constraints)]
+
+    if "pattern" in constraints:
+        try:
+            TypeAdapter(annotated)
+        except _PydanticSchemaError as exc:
+            if "regex" not in str(exc).lower():
+                raise
+            pattern = constraints.pop("pattern")
+            warnings.warn(
+                f"Pattern {pattern!r} is not supported by Pydantic's regex engine "
+                f"and will not be enforced.",
+                UserWarning,
+                stacklevel=2,
+            )
+            pattern_field = Field(json_schema_extra={"x-unsupported-pattern": pattern})
+            if constraints:
+                annotated = Annotated[
+                    str, StringConstraints(**constraints), pattern_field
+                ]  # type: ignore[valid-type]
+            else:
+                annotated = Annotated[str, pattern_field]  # type: ignore[valid-type]
+
+    return annotated
+
+
+def _create_numeric_type(
+    base: type[int | float], schema: Mapping[str, Any]
+) -> type | Annotated[Any, ...]:
+    """Create numeric type with optional constraints."""
+    if "const" in schema:
+        return Literal[schema["const"]]  # type: ignore
+
+    constraints = {
+        k: v
+        for k, v in {
+            "gt": schema.get("exclusiveMinimum"),
+            "ge": schema.get("minimum"),
+            "lt": schema.get("exclusiveMaximum"),
+            "le": schema.get("maximum"),
+            "multiple_of": schema.get("multipleOf"),
+        }.items()
+        if v is not None
+    }
+
+    return Annotated[base, Field(**constraints)] if constraints else base  # type: ignore[return-value]  # ty:ignore[invalid-type-form]
+
+
+def _create_enum(name: str, values: list[Any]) -> type:
+    """Create enum type from list of values."""
+    if not values:
+        # Empty enum means no value is valid (same semantics as ``false``
+        # schema).  Return the unsatisfiable type instead of ``Literal[()]``
+        # which triggers an AssertionError in Pydantic.
+        return _UnsatisfiableType  # type: ignore[return-value]  # ty:ignore[invalid-return-type]
+    # Always return Literal for enum fields to preserve the literal nature
+    return Literal[tuple(values)]  # type: ignore[return-value]  # ty:ignore[invalid-type-form]
+
+
+def _create_array_type(
+    schema: Mapping[str, Any],
+    schemas: Mapping[str, Any],
+    resolving_refs: frozenset[str],
+) -> type | Annotated[Any, ...]:
+    """Create list/set type with optional constraints."""
+    items = schema.get("items", {})
+    if isinstance(items, list):
+        # Handle positional item schemas
+        item_types = [_schema_to_type(s, schemas, resolving_refs) for s in items]
+        combined = Union[tuple(item_types)]  # noqa: UP007
+        base = list[combined]  # type: ignore[valid-type]  # ty:ignore[invalid-type-form]
+    else:
+        # Handle single item schema
+        item_type = _schema_to_type(items, schemas, resolving_refs)
+        base_class = set if schema.get("uniqueItems") else list
+        base = base_class[item_type]
+
+    constraints = {
+        k: v
+        for k, v in {
+            "min_length": schema.get("minItems"),
+            "max_length": schema.get("maxItems"),
+        }.items()
+        if v is not None
+    }
+
+    return Annotated[base, Field(**constraints)] if constraints else base  # type: ignore[return-value]  # ty:ignore[invalid-type-form]
+
+
+def _return_Any() -> Any:
+    return Any
+
+
+def _object_schema_to_type(
+    schema: Mapping[str, Any],
+    schemas: Mapping[str, Any],
+    name: str | None = None,
+    resolving_refs: frozenset[str] = frozenset(),
+) -> type:
+    """Convert an object schema to the appropriate Python type.
+
+    Single source of truth for the four object-schema cases, used by both the
+    top-level ``json_schema_to_type`` entry point and the recursive
+    ``_schema_to_type`` path:
+
+    1. No ``properties`` with ``additionalProperties`` truthy — ``dict[str, T]``
+       (``T = Any`` when ``additionalProperties is True``, else the value schema's type)
+    2. No ``properties`` and no ``additionalProperties`` — ``dict[str, Any]``
+    3. Has ``properties`` and ``additionalProperties is True`` — Pydantic model
+       (so ``extra="allow"`` can preserve unknown keys)
+    4. Has ``properties`` otherwise — dataclass
+
+    ``name`` is used as the generated class name for cases 3 and 4; it falls
+    back to the schema's ``title`` when not provided.
+    """
+    has_properties = bool(schema.get("properties"))
+    additional_props = schema.get("additionalProperties")
+    class_name = name if name is not None else schema.get("title")
+
+    if not has_properties and additional_props:
+        if additional_props is True:
+            return dict[str, Any]
+        value_type = _schema_to_type(additional_props, schemas, resolving_refs)
+        return cast(type[Any], dict[str, value_type])  # type: ignore[valid-type]  # ty:ignore[invalid-type-form]
+
+    if not has_properties and not additional_props:
+        return dict[str, Any]
+
+    if has_properties and additional_props is True:
+        return _create_pydantic_model(schema, class_name, schemas, resolving_refs)
+
+    return _create_dataclass(schema, class_name, schemas, resolving_refs)
+
+
+def _get_from_type_handler(
+    schema: Mapping[str, Any],
+    schemas: Mapping[str, Any],
+    resolving_refs: frozenset[str],
+) -> Callable[..., Any]:
+    """Get the appropriate type handler for the schema."""
+
+    type_handlers: dict[str, Callable[..., Any]] = {
+        "string": lambda s: _create_string_type(s),
+        "integer": lambda s: _create_numeric_type(int, s),
+        "number": lambda s: _create_numeric_type(float, s),
+        "boolean": lambda _: bool,
+        "null": lambda _: type(None),
+        "array": lambda s: _create_array_type(s, schemas, resolving_refs),
+        "object": lambda s: _object_schema_to_type(
+            s, schemas, resolving_refs=resolving_refs
+        ),
+    }
+    return type_handlers.get(schema.get("type", None), _return_Any)
+
+
+def _schema_to_type(
+    schema: Mapping[str, Any] | bool,
+    schemas: Mapping[str, Any],
+    resolving_refs: frozenset[str] = frozenset(),
+) -> type | ForwardRef:
+    """Convert schema to appropriate Python type."""
+    # Boolean schemas are valid in JSON Schema draft-06+:
+    # true means "any value is valid" (equivalent to {}),
+    # false means "no value is valid" (unsatisfiable).
+    if schema is True:
+        return Any
+    if schema is False:
+        return _UnsatisfiableType  # type: ignore[return-value]  # ty:ignore[invalid-return-type]
+
+    if not schema:
+        return object
+
+    if "type" not in schema and "properties" in schema:
+        return _create_dataclass(schema, schema.get("title", "<unknown>"), schemas)
+
+    # Handle references first
+    if "$ref" in schema:
+        ref = schema["$ref"]
+        # Handle self-reference
+        if ref == "#":
+            return ForwardRef(schema.get("title", "Root"))
+        if ref in resolving_refs:
+            resolved = _resolve_ref(ref, schemas)
+            if isinstance(resolved, Mapping) and (
+                resolved.get("type") == "object" or "properties" in resolved
+            ):
+                return _schema_to_type(resolved, schemas, resolving_refs)
+            return Any
+        return _schema_to_type(
+            _resolve_ref(ref, schemas), schemas, resolving_refs | {ref}
+        )
+
+    if "const" in schema:
+        return Literal[schema["const"]]  # type: ignore
+
+    if "enum" in schema:
+        return _create_enum(f"Enum_{len(_classes)}", schema["enum"])
+
+    # Handle anyOf unions
+    if "anyOf" in schema:
+        types: list[type | Any] = [
+            _schema_to_type(subschema, schemas, resolving_refs)
+            for subschema in schema["anyOf"]
+        ]
+
+        # Check if one of the types is None (null)
+        has_null = type(None) in types
+        types = [t for t in types if t is not type(None)]
+
+        if len(types) == 0:
+            return type(None)
+        elif len(types) == 1:
+            if has_null:
+                return types[0] | None  # type: ignore
+            else:
+                return types[0]
+        else:
+            if has_null:
+                return Union[(*types, type(None))]  # type: ignore
+            else:
+                return Union[tuple(types)]  # type: ignore # noqa: UP007
+
+    schema_type = schema.get("type")
+    if not schema_type:
+        return Any
+
+    if isinstance(schema_type, list):
+        # Create a copy of the schema for each type, but keep all constraints
+        types: list[type | Any] = []
+        for t in schema_type:
+            type_schema = dict(schema)
+            type_schema["type"] = t
+            types.append(_schema_to_type(type_schema, schemas, resolving_refs))
+        has_null = type(None) in types
+        types = [t for t in types if t is not type(None)]
+        if has_null:
+            if len(types) == 1:
+                return types[0] | None  # type: ignore
+            else:
+                return Union[(*types, type(None))]  # type: ignore
+        return Union[tuple(types)]  # type: ignore # noqa: UP007
+
+    return _get_from_type_handler(schema, schemas, resolving_refs)(schema)
+
+
+def _sanitize_name(name: str) -> str:
+    """Convert string to valid Python identifier."""
+    original_name = name
+    # Step 1: replace everything except [0-9a-zA-Z_] with underscores
+    cleaned = re.sub(r"[^0-9a-zA-Z_]", "_", name)
+    # Step 2: deduplicate underscores
+    cleaned = re.sub(r"__+", "_", cleaned)
+    # Step 3: if the first char of original name isn't a letter or underscore, prepend field_
+    if not name or not re.match(r"[a-zA-Z_]", name[0]):
+        cleaned = f"field_{cleaned}"
+    # Step 4: deduplicate again
+    cleaned = re.sub(r"__+", "_", cleaned)
+    # Step 5: only strip trailing underscores if they weren't in the original name
+    if not original_name.endswith("_"):
+        cleaned = cleaned.rstrip("_")
+    # Step 6: if result is a Python keyword, append an underscore (PEP 8 convention)
+    if keyword.iskeyword(cleaned):
+        cleaned = f"{cleaned}_"
+    return cleaned
+
+
+def _get_default_value(
+    schema: dict[str, Any],
+    prop_name: str,
+    parent_default: dict[str, Any] | None = None,
+) -> Any:
+    """Get default value with proper priority ordering.
+    1. Value from parent's default if it exists
+    2. Property's own default if it exists
+    3. None
+    """
+    if parent_default is not None and prop_name in parent_default:
+        return parent_default[prop_name]
+    return schema.get("default")
+
+
+def _create_field_with_default(
+    field_type: type,
+    default_value: Any,
+    schema: dict[str, Any],
+) -> Any:
+    """Create a field with simplified default handling."""
+    # Always use None as default for complex types
+    if isinstance(default_value, dict | list) or default_value is None:
+        return field(default=None)
+
+    # For simple types, use the value directly
+    return field(default=default_value)
+
+
+def _create_pydantic_model(
+    schema: Mapping[str, Any],
+    name: str | None = None,
+    schemas: Mapping[str, Any] | None = None,
+    resolving_refs: frozenset[str] = frozenset(),
+) -> type:
+    """Create Pydantic BaseModel from object schema with additionalProperties."""
+    name = name or schema.get("title", "Root")
+    if name is None:
+        raise ValueError("Name is required")
+    sanitized_name = _sanitize_name(name)
+    schema_hash = _hash_schema(schema)
+    cache_key = (schema_hash, sanitized_name)
+
+    # Return existing class if already built
+    if cache_key in _classes:
+        existing = _classes[cache_key]
+        if existing is None:
+            return ForwardRef(sanitized_name)  # type: ignore[return-value]  # ty:ignore[invalid-return-type]
+        return existing
+
+    # Place placeholder for recursive references
+    _classes[cache_key] = None
+
+    properties = schema.get("properties", {})
+    required = schema.get("required", [])
+
+    # Build field annotations and defaults
+    annotations = {}
+    defaults = {}
+
+    for prop_name, prop_schema in properties.items():
+        # Boolean schemas (JSON Schema draft-06+): resolve type directly,
+        # then use an empty dict for .get() calls below.
+        if isinstance(prop_schema, bool):
+            field_type = _schema_to_type(prop_schema, schemas or {}, resolving_refs)
+            prop_schema = {}
+        else:
+            field_type = _schema_to_type(prop_schema, schemas or {}, resolving_refs)
+
+        # Handle defaults
+        default_value = prop_schema.get("default", MISSING)
+        if default_value is not MISSING:
+            defaults[prop_name] = default_value
+            annotations[prop_name] = field_type
+        elif prop_name in required:
+            annotations[prop_name] = field_type
+        else:
+            annotations[prop_name] = Union[field_type, type(None)]  # type: ignore[misc]  # noqa: UP007  # ty:ignore[invalid-type-form]
+            defaults[prop_name] = None
+
+    # Create Pydantic model class
+    cls_dict = {
+        "__annotations__": annotations,
+        "model_config": ConfigDict(extra="allow"),
+        **defaults,
+    }
+
+    cls = type(sanitized_name, (BaseModel,), cls_dict)
+
+    # Store completed class
+    _classes[cache_key] = cls
+    return cls
+
+
+def _create_dataclass(
+    schema: Mapping[str, Any],
+    name: str | None = None,
+    schemas: Mapping[str, Any] | None = None,
+    resolving_refs: frozenset[str] = frozenset(),
+) -> type:
+    """Create dataclass from object schema."""
+    name = name or schema.get("title", "Root")
+    # Sanitize name for class creation
+    if name is None:
+        raise ValueError("Name is required")
+    sanitized_name = _sanitize_name(name)
+    schema_hash = _hash_schema(schema)
+    cache_key = (schema_hash, sanitized_name)
+    original_schema = dict(schema)  # Store copy for validator
+
+    # Return existing class if already built
+    if cache_key in _classes:
+        existing = _classes[cache_key]
+        if existing is None:
+            return ForwardRef(sanitized_name)  # type: ignore[return-value]  # ty:ignore[invalid-return-type]
+        return existing
+
+    # Place placeholder for recursive references
+    _classes[cache_key] = None
+
+    if "$ref" in schema:
+        ref = schema["$ref"]
+        if ref == "#":
+            return ForwardRef(sanitized_name)  # type: ignore[return-value]  # ty:ignore[invalid-return-type]
+        if ref in resolving_refs:
+            return Any
+        schema = _resolve_ref(ref, schemas or {})
+        resolving_refs = resolving_refs | {ref}
+
+    properties = schema.get("properties", {})
+    required = schema.get("required", [])
+
+    fields: list[tuple[Any, ...]] = []
+    used_field_names: set[str] = set()
+    for prop_name, prop_schema in properties.items():
+        field_name = _sanitize_name(prop_name)
+        # Deduplicate: if sanitized names collide (e.g. "foo-bar" and
+        # "foo_bar" both become "foo_bar"), append a numeric suffix.
+        base = field_name
+        counter = 2
+        while field_name in used_field_names:
+            field_name = f"{base}_{counter}"
+            counter += 1
+        used_field_names.add(field_name)
+
+        # Boolean schemas (JSON Schema draft-06+): resolve type directly,
+        # then use an empty dict for .get() calls below.
+        if isinstance(prop_schema, bool):
+            field_type = _schema_to_type(prop_schema, schemas or {}, resolving_refs)
+            prop_schema = {}
+        elif prop_schema.get("$ref") == "#":
+            # Check for self-reference in property
+            field_type = ForwardRef(sanitized_name)
+        else:
+            field_type = _schema_to_type(prop_schema, schemas or {}, resolving_refs)
+
+        default_val = prop_schema.get("default", MISSING)
+        is_required = prop_name in required
+
+        # Include alias in field metadata
+        meta = {"alias": prop_name}
+
+        if default_val is not MISSING:
+            if isinstance(default_val, dict | list):
+                field_def = field(
+                    default_factory=lambda d=default_val: deepcopy(d), metadata=meta
+                )
+            else:
+                field_def = field(default=default_val, metadata=meta)
+        else:
+            if is_required:
+                field_def = field(metadata=meta)
+            else:
+                field_def = field(default=None, metadata=meta)
+
+        if is_required or default_val is not MISSING:
+            fields.append((field_name, field_type, field_def))
+        else:
+            fields.append((field_name, Union[field_type, type(None)], field_def))  # type: ignore[misc]  # noqa: UP007  # ty:ignore[invalid-type-form]
+
+    cls = make_dataclass(sanitized_name, fields, kw_only=True)
+
+    # Add model validator for defaults
+    @model_validator(mode="before")
+    @classmethod
+    def _apply_defaults(cls, data: Mapping[str, Any]):
+        if isinstance(data, dict):
+            return _merge_defaults(data, original_schema)
+        return data
+
+    cls._apply_defaults = _apply_defaults  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+
+    # Store completed class
+    _classes[cache_key] = cls
+    return cls
+
+
+def _merge_defaults(
+    data: Mapping[str, Any],
+    schema: Mapping[str, Any],
+    parent_default: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Merge defaults with provided data at all levels."""
+    # If we have no data
+    if not data:
+        # Start with parent default if available
+        if parent_default:
+            result = dict(parent_default)
+        # Otherwise use schema default if available
+        elif "default" in schema:
+            result = dict(schema["default"])
+        # Otherwise start empty
+        else:
+            result = {}
+    # If we have data and a parent default, merge them
+    elif parent_default:
+        result = dict(parent_default)
+        for key, value in data.items():
+            if (
+                isinstance(value, dict)
+                and key in result
+                and isinstance(result[key], dict)
+            ):
+                # recursively merge nested dicts
+                result[key] = _merge_defaults(value, {"properties": {}}, result[key])
+            else:
+                result[key] = value
+    # Otherwise just use the data
+    else:
+        result = dict(data)
+
+    # For each property in the schema
+    for prop_name, prop_schema in schema.get("properties", {}).items():
+        # Normalize boolean schemas (JSON Schema draft-06+)
+        if isinstance(prop_schema, bool):
+            continue
+
+        # If property is missing, apply defaults in priority order
+        if prop_name not in result:
+            if parent_default and prop_name in parent_default:
+                result[prop_name] = parent_default[prop_name]
+            elif "default" in prop_schema:
+                result[prop_name] = prop_schema["default"]
+
+        # If property exists and is an object, recursively merge
+        if (
+            prop_name in result
+            and isinstance(result[prop_name], dict)
+            and prop_schema.get("type") == "object"
+        ):
+            # Get the appropriate default for this nested object
+            nested_default = None
+            if parent_default and prop_name in parent_default:
+                nested_default = parent_default[prop_name]
+            elif "default" in prop_schema:
+                nested_default = prop_schema["default"]
+
+            result[prop_name] = _merge_defaults(
+                result[prop_name], prop_schema, nested_default
+            )
+
+    return result
diff --git a/fastmcp_slim/fastmcp/utilities/lifespan.py b/fastmcp_slim/fastmcp/utilities/lifespan.py
new file mode 100644
index 0000000..f7f00b8
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/lifespan.py
@@ -0,0 +1,56 @@
+"""Lifespan utilities for combining async context manager lifespans."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable, Mapping
+from contextlib import AbstractAsyncContextManager, AsyncExitStack, asynccontextmanager
+from typing import Any, TypeVar
+
+AppT = TypeVar("AppT")
+
+
+def combine_lifespans(
+    *lifespans: Callable[[AppT], AbstractAsyncContextManager[Mapping[str, Any] | None]],
+) -> Callable[[AppT], AbstractAsyncContextManager[dict[str, Any]]]:
+    """Combine multiple lifespans into a single lifespan.
+
+    Useful when mounting FastMCP into FastAPI and you need to run
+    both your app's lifespan and the MCP server's lifespan.
+
+    Works with both FastAPI-style lifespans (yield None) and FastMCP-style
+    lifespans (yield dict). Results are merged; later lifespans override
+    earlier ones on key conflicts.
+
+    Lifespans are entered in order and exited in reverse order (LIFO).
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.utilities.lifespan import combine_lifespans
+        from fastapi import FastAPI
+
+        mcp = FastMCP("Tools")
+        mcp_app = mcp.http_app()
+
+        app = FastAPI(lifespan=combine_lifespans(app_lifespan, mcp_app.lifespan))
+        app.mount("/mcp", mcp_app)  # MCP endpoint at /mcp
+        ```
+
+    Args:
+        *lifespans: Lifespan context manager factories to combine.
+
+    Returns:
+        A combined lifespan context manager factory.
+    """
+
+    @asynccontextmanager
+    async def combined(app: AppT) -> AsyncIterator[dict[str, Any]]:
+        merged: dict[str, Any] = {}
+        async with AsyncExitStack() as stack:
+            for ls in lifespans:
+                result = await stack.enter_async_context(ls(app))
+                if result is not None:
+                    merged.update(result)
+            yield merged
+
+    return combined
diff --git a/fastmcp_slim/fastmcp/utilities/logging.py b/fastmcp_slim/fastmcp/utilities/logging.py
new file mode 100644
index 0000000..d39d6ef
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/logging.py
@@ -0,0 +1,244 @@
+"""Logging utilities for FastMCP."""
+
+import contextlib
+import logging
+from typing import Any, Literal, cast
+
+from rich.console import Console
+from rich.logging import RichHandler
+from typing_extensions import override
+
+import fastmcp
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a logger nested under FastMCP namespace.
+
+    Args:
+        name: the name of the logger, which will be prefixed with 'FastMCP.'
+
+    Returns:
+        a configured logger instance
+    """
+    if name.startswith("fastmcp."):
+        return logging.getLogger(name=name)
+
+    return logging.getLogger(name=f"fastmcp.{name}")
+
+
+def configure_logging(
+    level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | int = "INFO",
+    logger: logging.Logger | None = None,
+    enable_rich_tracebacks: bool | None = None,
+    **rich_kwargs: Any,
+) -> None:
+    """
+    Configure logging for FastMCP.
+
+    Args:
+        logger: the logger to configure
+        level: the log level to use
+        rich_kwargs: the parameters to use for creating RichHandler
+    """
+    # Check if logging is disabled in settings
+    if not fastmcp.settings.log_enabled:
+        return
+
+    # Use settings default if not specified
+    if enable_rich_tracebacks is None:
+        enable_rich_tracebacks = fastmcp.settings.enable_rich_tracebacks
+
+    if logger is None:
+        logger = logging.getLogger("fastmcp")
+
+    formatter = logging.Formatter("%(message)s")
+
+    # Don't propagate to the root logger
+    logger.propagate = False
+    logger.setLevel(level)
+
+    # Remove any existing handlers to avoid duplicates on reconfiguration
+    for hdlr in logger.handlers[:]:
+        logger.removeHandler(hdlr)
+
+    # Use standard logging handlers if rich logging is disabled
+    if not fastmcp.settings.enable_rich_logging:
+        # Create a standard StreamHandler for stderr
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("%(levelname)s: %(message)s"))
+        logger.addHandler(handler)
+        return
+
+    # Configure the handler for normal logs
+    handler = RichHandler(
+        console=Console(stderr=True),
+        **rich_kwargs,
+    )
+    handler.setFormatter(formatter)
+
+    # filter to exclude tracebacks
+    handler.addFilter(lambda record: record.exc_info is None)
+
+    # Configure the handler for tracebacks, for tracebacks we use a compressed format:
+    # no path or level name to maximize width available for the traceback
+    # suppress framework frames and limit the number of frames to 3
+
+    import pydantic
+
+    try:
+        import mcp
+    except ImportError:
+        tracebacks_suppress = [fastmcp, pydantic]
+    else:
+        tracebacks_suppress = [fastmcp, mcp, pydantic]
+
+    # Build traceback kwargs with defaults that can be overridden
+    traceback_kwargs = {
+        "console": Console(stderr=True),
+        "show_path": False,
+        "show_level": False,
+        "rich_tracebacks": enable_rich_tracebacks,
+        "tracebacks_max_frames": 3,
+        "tracebacks_suppress": tracebacks_suppress,
+    }
+    # Override defaults with user-provided values
+    traceback_kwargs.update(rich_kwargs)
+
+    traceback_handler = RichHandler(**traceback_kwargs)  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+    traceback_handler.setFormatter(formatter)
+
+    traceback_handler.addFilter(lambda record: record.exc_info is not None)
+
+    logger.addHandler(handler)
+    logger.addHandler(traceback_handler)
+
+
+@contextlib.contextmanager
+def temporary_log_level(
+    level: str | None,
+    logger: logging.Logger | None = None,
+    enable_rich_tracebacks: bool | None = None,
+    **rich_kwargs: Any,
+):
+    """Context manager to temporarily set log level and restore it afterwards.
+
+    Args:
+        level: The temporary log level to set (e.g., "DEBUG", "INFO")
+        logger: Optional logger to configure (defaults to FastMCP logger)
+        enable_rich_tracebacks: Whether to enable rich tracebacks
+        **rich_kwargs: Additional parameters for RichHandler
+
+    Usage:
+        with temporary_log_level("DEBUG"):
+            # Code that runs with DEBUG logging
+            pass
+        # Original log level is restored here
+    """
+    if level:
+        # Get the original log level from settings
+        original_level = fastmcp.settings.log_level
+
+        # Configure with new level
+        # Cast to proper type for type checker
+        log_level_literal = cast(
+            Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+            level.upper(),
+        )
+        configure_logging(
+            level=log_level_literal,
+            logger=logger,
+            enable_rich_tracebacks=enable_rich_tracebacks,
+            **rich_kwargs,
+        )
+        try:
+            yield
+        finally:
+            # Restore original configuration using configure_logging
+            # This will respect the log_enabled setting
+            configure_logging(
+                level=original_level,
+                logger=logger,
+                enable_rich_tracebacks=enable_rich_tracebacks,
+                **rich_kwargs,
+            )
+    else:
+        yield
+
+
+_level_to_no: dict[
+    Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | None, int | None
+] = {
+    "DEBUG": logging.DEBUG,
+    "INFO": logging.INFO,
+    "WARNING": logging.WARNING,
+    "ERROR": logging.ERROR,
+    "CRITICAL": logging.CRITICAL,
+    None: None,
+}
+
+
+class _ClampedLogFilter(logging.Filter):
+    min_level: tuple[int, str] | None
+    max_level: tuple[int, str] | None
+
+    def __init__(
+        self,
+        min_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+        | None = None,
+        max_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+        | None = None,
+    ):
+        self.min_level = None
+        self.max_level = None
+
+        if min_level_no := _level_to_no.get(min_level):
+            self.min_level = (min_level_no, str(min_level))
+        if max_level_no := _level_to_no.get(max_level):
+            self.max_level = (max_level_no, str(max_level))
+
+        super().__init__()
+
+    @override
+    def filter(self, record: logging.LogRecord) -> bool:
+        if self.max_level:
+            max_level_no, max_level_name = self.max_level
+
+            if record.levelno > max_level_no:
+                record.levelno = max_level_no
+                record.levelname = max_level_name
+                return True
+
+        if self.min_level:
+            min_level_no, min_level_name = self.min_level
+            if record.levelno < min_level_no:
+                record.levelno = min_level_no
+                record.levelname = min_level_name
+                return True
+
+        return True
+
+
+def _clamp_logger(
+    logger: logging.Logger,
+    min_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | None = None,
+    max_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | None = None,
+) -> None:
+    """Clamp the logger to a minimum and maximum level.
+
+    If min_level is provided, messages logged at a lower level than `min_level` will have their level increased to `min_level`.
+    If max_level is provided, messages logged at a higher level than `max_level` will have their level decreased to `max_level`.
+
+    Args:
+        min_level: The lower bound of the clamp
+        max_level: The upper bound of the clamp
+    """
+    _unclamp_logger(logger=logger)
+
+    logger.addFilter(filter=_ClampedLogFilter(min_level=min_level, max_level=max_level))
+
+
+def _unclamp_logger(logger: logging.Logger) -> None:
+    """Remove all clamped log filters from the logger."""
+    for filter in logger.filters[:]:
+        if isinstance(filter, _ClampedLogFilter):
+            logger.removeFilter(filter)
diff --git a/fastmcp_slim/fastmcp/utilities/mcp_server_config/__init__.py b/fastmcp_slim/fastmcp/utilities/mcp_server_config/__init__.py
new file mode 100644
index 0000000..6cdfadc
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/mcp_server_config/__init__.py
@@ -0,0 +1,25 @@
+"""FastMCP Configuration module.
+
+This module provides versioned configuration support for FastMCP servers.
+The current version is v1, which is re-exported here for convenience.
+"""
+
+from fastmcp.utilities.mcp_server_config.v1.environments.base import Environment
+from fastmcp.utilities.mcp_server_config.v1.environments.uv import UVEnvironment
+from fastmcp.utilities.mcp_server_config.v1.mcp_server_config import (
+    Deployment,
+    MCPServerConfig,
+    generate_schema,
+)
+from fastmcp.utilities.mcp_server_config.v1.sources.base import Source
+from fastmcp.utilities.mcp_server_config.v1.sources.filesystem import FileSystemSource
+
+__all__ = [
+    "Deployment",
+    "Environment",
+    "FileSystemSource",
+    "MCPServerConfig",
+    "Source",
+    "UVEnvironment",
+    "generate_schema",
+]
diff --git a/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/__init__.py b/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/__init__.py b/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/__init__.py
new file mode 100644
index 0000000..3cccf54
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/__init__.py
@@ -0,0 +1,6 @@
+"""Environment configuration for MCP servers."""
+
+from fastmcp.utilities.mcp_server_config.v1.environments.base import Environment
+from fastmcp.utilities.mcp_server_config.v1.environments.uv import UVEnvironment
+
+__all__ = ["Environment", "UVEnvironment"]
diff --git a/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/base.py b/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/base.py
new file mode 100644
index 0000000..0d1b1f8
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/base.py
@@ -0,0 +1,29 @@
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+
+class Environment(BaseModel, ABC):
+    """Base class for environment configuration."""
+
+    type: str = Field(description="Environment type identifier")
+
+    @abstractmethod
+    def build_command(self, command: list[str]) -> list[str]:
+        """Build the full command with environment setup.
+
+        Args:
+            command: Base command to wrap with environment setup
+
+        Returns:
+            Full command ready for subprocess execution
+        """
+
+    async def prepare(self, output_dir: Path | None = None) -> None:
+        """Prepare the environment (optional, can be no-op).
+
+        Args:
+            output_dir: Directory for persistent environment setup
+        """
+        # Default no-op implementation
diff --git a/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/uv.py b/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/uv.py
new file mode 100644
index 0000000..a889654
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/uv.py
@@ -0,0 +1,271 @@
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Literal
+
+from pydantic import Field
+
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_server_config.v1.environments.base import Environment
+
+logger = get_logger("cli.config")
+
+
+class UVEnvironment(Environment):
+    """Configuration for Python environment setup."""
+
+    type: Literal["uv"] = "uv"
+
+    python: str | None = Field(
+        default=None,
+        description="Python version constraint",
+        examples=["3.10", "3.11", "3.12"],
+    )
+
+    dependencies: list[str] | None = Field(
+        default=None,
+        description="Python packages to install with PEP 508 specifiers",
+        examples=[["fastmcp>=2.0,<3", "httpx", "pandas>=2.0"]],
+    )
+
+    requirements: Path | None = Field(
+        default=None,
+        description="Path to requirements.txt file",
+        examples=["requirements.txt", "../requirements/prod.txt"],
+    )
+
+    project: Path | None = Field(
+        default=None,
+        description="Path to project directory containing pyproject.toml",
+        examples=[".", "../my-project"],
+    )
+
+    editable: list[Path] | None = Field(
+        default=None,
+        description="Directories to install in editable mode",
+        examples=[[".", "../my-package"], ["/path/to/package"]],
+    )
+
+    def build_command(self, command: list[str]) -> list[str]:
+        """Build complete uv run command with environment args and command to execute.
+
+        Args:
+            command: Command to execute (e.g., ["fastmcp", "run", "server.py"])
+
+        Returns:
+            Complete command ready for subprocess.run, including "uv" prefix if needed.
+            If no environment configuration is set, returns the command unchanged.
+        """
+        # If no environment setup is needed, return command as-is
+        if not self._must_run_with_uv():
+            return command
+
+        args = ["uv", "run"]
+
+        # Add project if specified
+        if self.project:
+            args.extend(["--project", str(self.project.resolve())])
+
+        # Add Python version if specified (only if no project, as project has its own Python)
+        if self.python and not self.project:
+            args.extend(["--python", self.python])
+
+        # Always add dependencies, requirements, and editable packages
+        # These work with --project to add additional packages on top of the project env
+        if self.dependencies:
+            for dep in sorted(set(self.dependencies)):
+                args.extend(["--with", dep])
+
+        # Add requirements file
+        if self.requirements:
+            args.extend(["--with-requirements", str(self.requirements.resolve())])
+
+        # Add editable packages
+        if self.editable:
+            for editable_path in self.editable:
+                args.extend(["--with-editable", str(editable_path.resolve())])
+
+        # Add the command
+        args.extend(command)
+
+        return args
+
+    def _must_run_with_uv(self) -> bool:
+        """Check if this environment config requires uv to set up.
+
+        Returns:
+            True if any environment settings require uv run
+        """
+        return any(
+            [
+                self.python is not None,
+                self.dependencies is not None,
+                self.requirements is not None,
+                self.project is not None,
+                self.editable is not None,
+            ]
+        )
+
+    async def prepare(self, output_dir: Path | None = None) -> None:
+        """Prepare the Python environment using uv.
+
+        Args:
+            output_dir: Directory where the persistent uv project will be created.
+                       If None, creates a temporary directory for ephemeral use.
+        """
+
+        # Check if uv is available
+        if not shutil.which("uv"):
+            raise RuntimeError(
+                "uv is not installed. Please install it with: "
+                "curl -LsSf https://astral.sh/uv/install.sh | sh"
+            )
+
+        # Only prepare environment if there are actual settings to apply
+        if not self._must_run_with_uv():
+            logger.debug("No environment settings configured, skipping preparation")
+            return
+
+        # Handle None case for ephemeral use
+        if output_dir is None:
+            import tempfile
+
+            output_dir = Path(tempfile.mkdtemp(prefix="fastmcp-env-"))
+            logger.info(f"Creating ephemeral environment in {output_dir}")
+        else:
+            logger.info(f"Creating persistent environment in {output_dir}")
+            output_dir = Path(output_dir).resolve()
+
+        # Initialize the project
+        logger.debug(f"Initializing uv project in {output_dir}")
+        try:
+            subprocess.run(
+                [
+                    "uv",
+                    "init",
+                    "--project",
+                    str(output_dir),
+                    "--name",
+                    "fastmcp-env",
+                ],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+        except subprocess.CalledProcessError as e:
+            # If project already exists, that's fine - continue
+            if "already initialized" in e.stderr.lower():
+                logger.debug(
+                    f"Project already initialized at {output_dir}, continuing..."
+                )
+            else:
+                logger.error(f"Failed to initialize project: {e.stderr}")
+                raise RuntimeError(f"Failed to initialize project: {e.stderr}") from e
+
+        # Pin Python version if specified
+        if self.python:
+            logger.debug(f"Pinning Python version to {self.python}")
+            try:
+                subprocess.run(
+                    [
+                        "uv",
+                        "python",
+                        "pin",
+                        self.python,
+                        "--project",
+                        str(output_dir),
+                    ],
+                    check=True,
+                    capture_output=True,
+                    text=True,
+                )
+            except subprocess.CalledProcessError as e:
+                logger.error(f"Failed to pin Python version: {e.stderr}")
+                raise RuntimeError(f"Failed to pin Python version: {e.stderr}") from e
+
+        # Add dependencies with --no-sync to defer installation
+        # dependencies ALWAYS include fastmcp; this is compatible with
+        # specific fastmcp versions that might be in the dependencies list
+        dependencies = (self.dependencies or []) + ["fastmcp"]
+        logger.debug(f"Adding dependencies: {', '.join(dependencies)}")
+        try:
+            subprocess.run(
+                [
+                    "uv",
+                    "add",
+                    *dependencies,
+                    "--no-sync",
+                    "--project",
+                    str(output_dir),
+                ],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+        except subprocess.CalledProcessError as e:
+            logger.error(f"Failed to add dependencies: {e.stderr}")
+            raise RuntimeError(f"Failed to add dependencies: {e.stderr}") from e
+
+        # Add requirements file if specified
+        if self.requirements:
+            logger.debug(f"Adding requirements from {self.requirements}")
+            # Resolve requirements path relative to current directory
+            req_path = Path(self.requirements).resolve()
+            try:
+                subprocess.run(
+                    [
+                        "uv",
+                        "add",
+                        "-r",
+                        str(req_path),
+                        "--no-sync",
+                        "--project",
+                        str(output_dir),
+                    ],
+                    check=True,
+                    capture_output=True,
+                    text=True,
+                )
+            except subprocess.CalledProcessError as e:
+                logger.error(f"Failed to add requirements: {e.stderr}")
+                raise RuntimeError(f"Failed to add requirements: {e.stderr}") from e
+
+        # Add editable packages if specified
+        if self.editable:
+            editable_paths = [str(Path(e).resolve()) for e in self.editable]
+            logger.debug(f"Adding editable packages: {', '.join(editable_paths)}")
+            try:
+                subprocess.run(
+                    [
+                        "uv",
+                        "add",
+                        "--editable",
+                        *editable_paths,
+                        "--no-sync",
+                        "--project",
+                        str(output_dir),
+                    ],
+                    check=True,
+                    capture_output=True,
+                    text=True,
+                )
+            except subprocess.CalledProcessError as e:
+                logger.error(f"Failed to add editable packages: {e.stderr}")
+                raise RuntimeError(
+                    f"Failed to add editable packages: {e.stderr}"
+                ) from e
+
+        # Final sync to install everything
+        logger.info("Installing dependencies...")
+        try:
+            subprocess.run(
+                ["uv", "sync", "--project", str(output_dir)],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+        except subprocess.CalledProcessError as e:
+            logger.error(f"Failed to sync dependencies: {e.stderr}")
+            raise RuntimeError(f"Failed to sync dependencies: {e.stderr}") from e
+
+        logger.info(f"Environment prepared successfully in {output_dir}")
diff --git a/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py b/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py
new file mode 100644
index 0000000..b926beb
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py
@@ -0,0 +1,447 @@
+"""FastMCP Configuration File Support.
+
+This module provides support for fastmcp.json configuration files that allow
+users to specify server settings in a declarative format instead of using
+command-line arguments.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal, TypeAlias, cast, overload
+
+from pydantic import BaseModel, Field, field_validator
+
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_server_config.v1.environments.uv import UVEnvironment
+from fastmcp.utilities.mcp_server_config.v1.sources.base import Source
+from fastmcp.utilities.mcp_server_config.v1.sources.filesystem import FileSystemSource
+
+logger = get_logger("cli.config")
+
+# JSON Schema for IDE support
+FASTMCP_JSON_SCHEMA = "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json"
+
+
+# Type alias for source union (will expand with GitSource, etc. in future)
+SourceType: TypeAlias = FileSystemSource
+
+# Type alias for environment union (will expand with other environments in future)
+EnvironmentType: TypeAlias = UVEnvironment
+
+
+class Deployment(BaseModel):
+    """Configuration for server deployment and runtime settings."""
+
+    transport: Literal["stdio", "http", "sse", "streamable-http"] | None = Field(
+        default=None,
+        description="Transport protocol to use",
+    )
+
+    host: str | None = Field(
+        default=None,
+        description="Host to bind to when using HTTP transport",
+        examples=["127.0.0.1", "0.0.0.0", "localhost"],
+    )
+
+    port: int | None = Field(
+        default=None,
+        description="Port to bind to when using HTTP transport",
+        examples=[8000, 3000, 5000],
+    )
+
+    path: str | None = Field(
+        default=None,
+        description="URL path for the server endpoint",
+        examples=["/mcp/", "/api/mcp/", "/sse/"],
+    )
+
+    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | None = Field(
+        default=None,
+        description="Log level for the server",
+    )
+
+    cwd: str | None = Field(
+        default=None,
+        description="Working directory for the server process",
+        examples=[".", "./src", "/app"],
+    )
+
+    env: dict[str, str] | None = Field(
+        default=None,
+        description="Environment variables to set when running the server",
+        examples=[{"API_KEY": "secret", "DEBUG": "true"}],
+    )
+
+    args: list[str] | None = Field(
+        default=None,
+        description="Arguments to pass to the server (after --)",
+        examples=[["--config", "config.json", "--debug"]],
+    )
+
+    def apply_runtime_settings(self, config_path: Path | None = None) -> None:
+        """Apply runtime settings like environment variables and working directory.
+
+        Args:
+            config_path: Path to config file for resolving relative paths
+
+        Environment variables support interpolation with ${VAR_NAME} syntax.
+        For example: "API_URL": "https://api.${ENVIRONMENT}.example.com"
+        will substitute the value of the ENVIRONMENT variable at runtime.
+        """
+        import os
+        from pathlib import Path
+
+        # Set environment variables with interpolation support
+        if self.env:
+            for key, value in self.env.items():
+                # Interpolate environment variables in the value
+                interpolated_value = self._interpolate_env_vars(value)
+                os.environ[key] = interpolated_value
+
+        # Change working directory
+        if self.cwd:
+            cwd_path = Path(self.cwd)
+            if not cwd_path.is_absolute() and config_path:
+                cwd_path = (config_path.parent / cwd_path).resolve()
+            os.chdir(cwd_path)
+
+    def _interpolate_env_vars(self, value: str) -> str:
+        """Interpolate environment variables in a string.
+
+        Replaces ${VAR_NAME} with the value of VAR_NAME from the environment.
+        If the variable is not set, the placeholder is left unchanged.
+
+        Args:
+            value: String potentially containing ${VAR_NAME} placeholders
+
+        Returns:
+            String with environment variables interpolated
+        """
+
+        def replace_var(match: re.Match) -> str:
+            var_name = match.group(1)
+            # Return the environment variable value if it exists, otherwise keep the placeholder
+            return os.environ.get(var_name, match.group(0))
+
+        # Match ${VAR_NAME} pattern and replace with environment variable values
+        return re.sub(r"\$\{([^}]+)\}", replace_var, value)
+
+
+class MCPServerConfig(BaseModel):
+    """Configuration for a FastMCP server.
+
+    This configuration file allows you to specify all settings needed to run
+    a FastMCP server in a declarative format.
+    """
+
+    # Schema field for IDE support
+    schema_: str | None = Field(
+        default="https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+        alias="$schema",
+        description="JSON schema for IDE support and validation",
+    )
+
+    # Server source - defines where and how to load the server
+    source: SourceType = Field(
+        description="Source configuration for the server",
+        examples=[
+            {"path": "server.py"},
+            {"path": "server.py", "entrypoint": "app"},
+            {"type": "filesystem", "path": "src/server.py", "entrypoint": "mcp"},
+        ],
+    )
+
+    # Environment configuration
+    environment: EnvironmentType = Field(
+        default_factory=lambda: UVEnvironment(),
+        description="Python environment setup configuration",
+    )
+
+    # Deployment configuration
+    deployment: Deployment = Field(
+        default_factory=lambda: Deployment(),
+        description="Server deployment and runtime settings",
+    )
+
+    # purely for static type checkers to avoid issues with providing dict source
+    if TYPE_CHECKING:
+
+        @overload
+        def __init__(self, *, source: dict | FileSystemSource, **data) -> None: ...
+        @overload
+        def __init__(self, *, environment: dict | UVEnvironment, **data) -> None: ...
+        @overload
+        def __init__(self, *, deployment: dict | Deployment, **data) -> None: ...
+        def __init__(self, **data) -> None: ...
+
+    @field_validator("source", mode="before")
+    @classmethod
+    def validate_source(cls, v: dict | Source) -> SourceType:
+        """Validate and convert source to proper format.
+
+        Supports:
+        - Dict format: `{"path": "server.py", "entrypoint": "app"}`
+        - FileSystemSource instance (passed through)
+
+        No string parsing happens here - that's only at CLI boundaries.
+        MCPServerConfig works only with properly typed objects.
+        """
+        if isinstance(v, dict):
+            return FileSystemSource(**v)
+        return v  # type: ignore[return-value]  # ty:ignore[invalid-return-type]
+
+    @field_validator("environment", mode="before")
+    @classmethod
+    def validate_environment(cls, v: dict | Any) -> EnvironmentType:
+        """Ensure environment has a type field for discrimination.
+
+        For backward compatibility, if no type is specified, default to "uv".
+        """
+        if isinstance(v, dict):
+            return UVEnvironment(**v)
+        return v
+
+    @field_validator("deployment", mode="before")
+    @classmethod
+    def validate_deployment(cls, v: dict | Deployment) -> Deployment:
+        """Validate and convert deployment to Deployment.
+
+        Accepts:
+        - Deployment instance
+        - dict that can be converted to Deployment
+
+        """
+        if isinstance(v, dict):
+            return Deployment(**v)
+        return cast(Deployment, v)  # type: ignore[return-value]  # ty:ignore[redundant-cast]
+
+    @classmethod
+    def from_file(cls, file_path: Path) -> MCPServerConfig:
+        """Load configuration from a JSON file.
+
+        Args:
+            file_path: Path to the configuration file
+
+        Returns:
+            MCPServerConfig instance
+
+        Raises:
+            FileNotFoundError: If the file doesn't exist
+            json.JSONDecodeError: If the file is not valid JSON
+            pydantic.ValidationError: If the configuration is invalid
+        """
+        if not file_path.exists():
+            raise FileNotFoundError(f"Configuration file not found: {file_path}")
+
+        with file_path.open("r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        return cls.model_validate(data)
+
+    @classmethod
+    def from_cli_args(
+        cls,
+        source: FileSystemSource,
+        transport: Literal["stdio", "http", "sse", "streamable-http"] | None = None,
+        host: str | None = None,
+        port: int | None = None,
+        path: str | None = None,
+        log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+        | None = None,
+        python: str | None = None,
+        dependencies: list[str] | None = None,
+        requirements: str | None = None,
+        project: str | None = None,
+        editable: str | None = None,
+        env: dict[str, str] | None = None,
+        cwd: str | None = None,
+        args: list[str] | None = None,
+    ) -> MCPServerConfig:
+        """Create a config from CLI arguments.
+
+        This allows us to have a single code path where everything
+        goes through a config object.
+
+        Args:
+            source: Server source (FileSystemSource instance)
+            transport: Transport protocol
+            host: Host for HTTP transport
+            port: Port for HTTP transport
+            path: URL path for server
+            log_level: Logging level
+            python: Python version
+            dependencies: Python packages to install
+            requirements: Path to requirements file
+            project: Path to project directory
+            editable: Path to install in editable mode
+            env: Environment variables
+            cwd: Working directory
+            args: Server arguments
+
+        Returns:
+            MCPServerConfig instance
+        """
+        # Build environment config if any env args provided
+        environment = None
+        if any([python, dependencies, requirements, project, editable]):
+            environment = UVEnvironment(
+                python=python,
+                dependencies=dependencies,
+                requirements=Path(requirements) if requirements else None,
+                project=Path(project) if project else None,
+                editable=[Path(editable)] if editable else None,
+            )
+
+        # Build deployment config if any deployment args provided
+        deployment = None
+        if any([transport, host, port, path, log_level, env, cwd, args]):
+            # Convert streamable-http to http for backward compatibility
+            if transport == "streamable-http":
+                transport = "http"
+            deployment = Deployment(
+                transport=transport,
+                host=host,
+                port=port,
+                path=path,
+                log_level=log_level,
+                env=env,
+                cwd=cwd,
+                args=args,
+            )
+
+        return cls(
+            source=source,
+            environment=environment,
+            deployment=deployment,
+        )
+
+    @classmethod
+    def find_config(cls, start_path: Path | None = None) -> Path | None:
+        """Find a fastmcp.json file in the specified directory.
+
+        Args:
+            start_path: Directory to look in (defaults to current directory)
+
+        Returns:
+            Path to the configuration file, or None if not found
+        """
+        if start_path is None:
+            start_path = Path.cwd()
+
+        config_path = start_path / "fastmcp.json"
+        if config_path.exists():
+            logger.debug(f"Found configuration file: {config_path}")
+            return config_path
+
+        return None
+
+    async def prepare(
+        self,
+        skip_source: bool = False,
+        output_dir: Path | None = None,
+    ) -> None:
+        """Prepare environment and source for execution.
+
+        When output_dir is provided, creates a persistent uv project.
+        When output_dir is None, does ephemeral caching (for backwards compatibility).
+
+        Args:
+            skip_source: Skip source preparation if True
+            output_dir: Directory to create the persistent uv project in (optional)
+        """
+        # Prepare environment (persistent if output_dir provided, ephemeral otherwise)
+        if self.environment:
+            await self.prepare_environment(output_dir=output_dir)
+
+        if not skip_source:
+            await self.prepare_source()
+
+    async def prepare_environment(self, output_dir: Path | None = None) -> None:
+        """Prepare the Python environment.
+
+        Args:
+            output_dir: If provided, creates a persistent uv project in this directory.
+                       If None, just populates uv's cache for ephemeral use.
+
+        Delegates to the environment's prepare() method
+        """
+        await self.environment.prepare(output_dir=output_dir)
+
+    async def prepare_source(self) -> None:
+        """Prepare the source for loading.
+
+        Delegates to the source's prepare() method.
+        """
+        await self.source.prepare()
+
+    async def run_server(self, **kwargs: Any) -> None:
+        """Load and run the server with this configuration.
+
+        Args:
+            **kwargs: Additional arguments to pass to server.run_async()
+                     These override config settings
+        """
+        # Apply deployment settings (env vars, cwd)
+        if self.deployment:
+            self.deployment.apply_runtime_settings()
+
+        # Load the server
+        server = await self.source.load_server()
+
+        # Build run arguments from config
+        run_args = {}
+        if self.deployment:
+            if self.deployment.transport:
+                run_args["transport"] = self.deployment.transport
+            if self.deployment.host:
+                run_args["host"] = self.deployment.host
+            if self.deployment.port:
+                run_args["port"] = self.deployment.port
+            if self.deployment.path:
+                run_args["path"] = self.deployment.path
+            if self.deployment.log_level:
+                run_args["log_level"] = self.deployment.log_level
+
+        # Override with any provided kwargs
+        run_args.update(kwargs)
+
+        # Run the server
+        await server.run_async(**run_args)
+
+
+def generate_schema(output_path: Path | str | None = None) -> dict[str, Any] | None:
+    """Generate JSON schema for fastmcp.json files.
+
+    This is used to create the schema file that IDEs can use for
+    validation and auto-completion.
+
+    Args:
+        output_path: Optional path to write the schema to. If provided,
+                    writes the schema and returns None. If not provided,
+                    returns the schema as a dictionary.
+
+    Returns:
+        JSON schema as a dictionary if output_path is None, otherwise None
+    """
+    schema = MCPServerConfig.model_json_schema()
+
+    # Add some metadata
+    schema["$id"] = FASTMCP_JSON_SCHEMA
+    schema["title"] = "FastMCP Configuration"
+    schema["description"] = "Configuration file for FastMCP servers"
+
+    if output_path:
+        import json
+
+        output = Path(output_path)
+        output.parent.mkdir(parents=True, exist_ok=True)
+        with open(output, "w") as f:
+            json.dump(schema, f, indent=2)
+            f.write("\n")  # Add trailing newline
+        return None
+
+    return schema
diff --git a/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/schema.json b/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/schema.json
new file mode 100644
index 0000000..aa1f59c
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/schema.json
@@ -0,0 +1,365 @@
+{
+  "$defs": {
+    "Deployment": {
+      "description": "Configuration for server deployment and runtime settings.",
+      "properties": {
+        "transport": {
+          "anyOf": [
+            {
+              "enum": [
+                "stdio",
+                "http",
+                "sse",
+                "streamable-http"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Transport protocol to use",
+          "title": "Transport"
+        },
+        "host": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Host to bind to when using HTTP transport",
+          "examples": [
+            "127.0.0.1",
+            "0.0.0.0",
+            "localhost"
+          ],
+          "title": "Host"
+        },
+        "port": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Port to bind to when using HTTP transport",
+          "examples": [
+            8000,
+            3000,
+            5000
+          ],
+          "title": "Port"
+        },
+        "path": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "URL path for the server endpoint",
+          "examples": [
+            "/mcp/",
+            "/api/mcp/",
+            "/sse/"
+          ],
+          "title": "Path"
+        },
+        "log_level": {
+          "anyOf": [
+            {
+              "enum": [
+                "DEBUG",
+                "INFO",
+                "WARNING",
+                "ERROR",
+                "CRITICAL"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Log level for the server",
+          "title": "Log Level"
+        },
+        "cwd": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Working directory for the server process",
+          "examples": [
+            ".",
+            "./src",
+            "/app"
+          ],
+          "title": "Cwd"
+        },
+        "env": {
+          "anyOf": [
+            {
+              "additionalProperties": {
+                "type": "string"
+              },
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Environment variables to set when running the server",
+          "examples": [
+            {
+              "API_KEY": "secret",
+              "DEBUG": "true"
+            }
+          ],
+          "title": "Env"
+        },
+        "args": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Arguments to pass to the server (after --)",
+          "examples": [
+            [
+              "--config",
+              "config.json",
+              "--debug"
+            ]
+          ],
+          "title": "Args"
+        }
+      },
+      "title": "Deployment",
+      "type": "object"
+    },
+    "FileSystemSource": {
+      "description": "Source for local Python files.",
+      "properties": {
+        "type": {
+          "const": "filesystem",
+          "default": "filesystem",
+          "title": "Type",
+          "type": "string"
+        },
+        "path": {
+          "description": "Path to Python file containing the server",
+          "title": "Path",
+          "type": "string"
+        },
+        "entrypoint": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Name of server instance or factory function (a no-arg function that returns a FastMCP server)",
+          "title": "Entrypoint"
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "title": "FileSystemSource",
+      "type": "object"
+    },
+    "UVEnvironment": {
+      "description": "Configuration for Python environment setup.",
+      "properties": {
+        "type": {
+          "const": "uv",
+          "default": "uv",
+          "title": "Type",
+          "type": "string"
+        },
+        "python": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Python version constraint",
+          "examples": [
+            "3.10",
+            "3.11",
+            "3.12"
+          ],
+          "title": "Python"
+        },
+        "dependencies": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Python packages to install with PEP 508 specifiers",
+          "examples": [
+            [
+              "fastmcp>=2.0,<3",
+              "httpx",
+              "pandas>=2.0"
+            ]
+          ],
+          "title": "Dependencies"
+        },
+        "requirements": {
+          "anyOf": [
+            {
+              "format": "path",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Path to requirements.txt file",
+          "examples": [
+            "requirements.txt",
+            "../requirements/prod.txt"
+          ],
+          "title": "Requirements"
+        },
+        "project": {
+          "anyOf": [
+            {
+              "format": "path",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Path to project directory containing pyproject.toml",
+          "examples": [
+            ".",
+            "../my-project"
+          ],
+          "title": "Project"
+        },
+        "editable": {
+          "anyOf": [
+            {
+              "items": {
+                "format": "path",
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Directories to install in editable mode",
+          "examples": [
+            [
+              ".",
+              "../my-package"
+            ],
+            [
+              "/path/to/package"
+            ]
+          ],
+          "title": "Editable"
+        }
+      },
+      "title": "UVEnvironment",
+      "type": "object"
+    }
+  },
+  "description": "Configuration file for FastMCP servers",
+  "properties": {
+    "$schema": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+      "description": "JSON schema for IDE support and validation",
+      "title": "$Schema"
+    },
+    "source": {
+      "$ref": "#/$defs/FileSystemSource",
+      "description": "Source configuration for the server",
+      "examples": [
+        {
+          "path": "server.py"
+        },
+        {
+          "entrypoint": "app",
+          "path": "server.py"
+        },
+        {
+          "entrypoint": "mcp",
+          "path": "src/server.py",
+          "type": "filesystem"
+        }
+      ]
+    },
+    "environment": {
+      "$ref": "#/$defs/UVEnvironment",
+      "description": "Python environment setup configuration"
+    },
+    "deployment": {
+      "$ref": "#/$defs/Deployment",
+      "description": "Server deployment and runtime settings"
+    }
+  },
+  "required": [
+    "source"
+  ],
+  "title": "FastMCP Configuration",
+  "type": "object",
+  "$id": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json"
+}
diff --git a/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/sources/__init__.py b/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/sources/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/sources/base.py b/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/sources/base.py
new file mode 100644
index 0000000..cc1e941
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/sources/base.py
@@ -0,0 +1,29 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Source(BaseModel, ABC):
+    """Abstract base class for all source types."""
+
+    type: str = Field(description="Source type identifier")
+
+    async def prepare(self) -> None:
+        """Prepare the source (download, clone, install, etc).
+
+        For sources that need preparation (e.g., git clone, download),
+        this method performs that preparation. For sources that don't
+        need preparation (e.g., local files), this is a no-op.
+        """
+        # Default implementation for sources that don't need preparation
+
+    @abstractmethod
+    async def load_server(self) -> Any:
+        """Load and return the FastMCP server instance.
+
+        Must be called after prepare() if the source requires preparation.
+        All information needed to load the server should be available
+        as attributes on the source instance.
+        """
+        ...
diff --git a/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/sources/filesystem.py b/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/sources/filesystem.py
new file mode 100644
index 0000000..2e865f8
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/sources/filesystem.py
@@ -0,0 +1,217 @@
+import importlib.util
+import inspect
+import sys
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import Field, field_validator
+
+from fastmcp.utilities.async_utils import is_coroutine_function
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_server_config.v1.sources.base import Source
+
+logger = get_logger(__name__)
+
+
+class FileSystemSource(Source):
+    """Source for local Python files."""
+
+    type: Literal["filesystem"] = "filesystem"
+
+    path: str = Field(description="Path to Python file containing the server")
+    entrypoint: str | None = Field(
+        default=None,
+        description="Name of server instance or factory function (a no-arg function that returns a FastMCP server)",
+    )
+
+    @field_validator("path", mode="before")
+    @classmethod
+    def parse_path_with_object(cls, v: str) -> str:
+        """Parse path:object syntax and extract the object name.
+
+        This validator runs before the model is created, allowing us to
+        handle the "file.py:object" syntax at the model boundary.
+        """
+        if isinstance(v, str) and ":" in v:
+            # Check if it's a Windows path (e.g., C:\...)
+            has_windows_drive = len(v) > 1 and v[1] == ":"
+
+            # Only split if colon is not part of Windows drive
+            if ":" in (v[2:] if has_windows_drive else v):
+                # This path has an object specification
+                # We'll handle it in __init__ by setting entrypoint
+                return v
+        return v
+
+    def __init__(self, **data: Any) -> None:
+        """Initialize FileSystemSource, handling path:object syntax."""
+        # Check if path contains an object specification
+        if "path" in data and isinstance(data["path"], str) and ":" in data["path"]:
+            path_str = data["path"]
+            # Check if it's a Windows path (e.g., C:\...)
+            has_windows_drive = len(path_str) > 1 and path_str[1] == ":"
+
+            # Only split if colon is not part of Windows drive
+            if ":" in (path_str[2:] if has_windows_drive else path_str):
+                file_str, obj = path_str.rsplit(":", 1)
+                data["path"] = file_str
+                # Only set entrypoint if not already provided
+                if "entrypoint" not in data or data["entrypoint"] is None:
+                    data["entrypoint"] = obj
+
+        super().__init__(**data)
+
+    async def load_server(self) -> Any:
+        """Load server from filesystem."""
+        # Resolve the file path
+        file_path = Path(self.path).expanduser().resolve()
+        if not file_path.exists():
+            logger.error(f"File not found: {file_path}")
+            sys.exit(1)
+        if not file_path.is_file():
+            logger.error(f"Not a file: {file_path}")
+            sys.exit(1)
+
+        # Import the module
+        module = self._import_module(file_path)
+
+        # Find the server object
+        server = await self._find_server_object(module, file_path)
+
+        return server
+
+    def _import_module(self, file_path: Path) -> Any:
+        """Import a Python module from a file path.
+
+        Args:
+            file_path: Path to the Python file
+
+        Returns:
+            The imported module
+        """
+        # Add parent directory to Python path so imports can be resolved
+        file_dir = str(file_path.parent)
+        if file_dir not in sys.path:
+            sys.path.insert(0, file_dir)
+
+        # Import the module
+        spec = importlib.util.spec_from_file_location("server_module", file_path)
+        if not spec or not spec.loader:
+            logger.error("Could not load module", extra={"file": str(file_path)})
+            sys.exit(1)
+
+        module = importlib.util.module_from_spec(spec)
+        sys.modules["server_module"] = module  # Register in sys.modules
+        spec.loader.exec_module(module)
+
+        return module
+
+    async def _find_server_object(self, module: Any, file_path: Path) -> Any:
+        """Find the server object in the module.
+
+        Args:
+            module: The imported Python module
+            file_path: Path to the file (for error messages)
+
+        Returns:
+            The server object (or result of calling a factory function)
+        """
+        # Avoid circular import by importing here
+        from mcp.server.mcpserver import MCPServer as SDKServer
+
+        from fastmcp.server.server import FastMCP
+
+        # If entrypoint is specified, use it
+        if self.entrypoint:
+            # Handle module:object syntax (though this is legacy)
+            if ":" in self.entrypoint:
+                module_name, object_name = self.entrypoint.split(":", 1)
+                try:
+                    import importlib
+
+                    server_module = importlib.import_module(module_name)
+                    obj = getattr(server_module, object_name, None)
+                except ImportError:
+                    logger.error(
+                        f"Could not import module '{module_name}'",
+                        extra={"file": str(file_path)},
+                    )
+                    sys.exit(1)
+            else:
+                # Just object name
+                obj = getattr(module, self.entrypoint, None)
+
+            if obj is None:
+                logger.error(
+                    f"Server object '{self.entrypoint}' not found",
+                    extra={"file": str(file_path)},
+                )
+                sys.exit(1)
+
+            return await self._resolve_factory(obj, file_path, self.entrypoint)
+
+        # No entrypoint specified, try common server names
+        for name in ["mcp", "server", "app"]:
+            if hasattr(module, name):
+                obj = getattr(module, name)
+                if isinstance(obj, FastMCP | SDKServer):
+                    return await self._resolve_factory(obj, file_path, name)
+
+        # No server found
+        logger.error(
+            f"No server object found in {file_path}. Please either:\n"
+            "1. Use a standard variable name (mcp, server, or app)\n"
+            "2. Specify the entrypoint name in fastmcp.json or use `file.py:object` syntax as your path.",
+            extra={"file": str(file_path)},
+        )
+        sys.exit(1)
+
+    async def _resolve_factory(self, obj: Any, file_path: Path, name: str) -> Any:
+        """Resolve a server object or factory function to a server instance.
+
+        Args:
+            obj: The object that might be a server or factory function
+            file_path: Path to the file for error messages
+            name: Name of the object for error messages
+
+        Returns:
+            A server instance
+        """
+        # Avoid circular import by importing here
+        from mcp.server.mcpserver import MCPServer as SDKServer
+
+        from fastmcp.server.server import FastMCP
+
+        # Check if it's a function or coroutine function
+        if inspect.isfunction(obj) or is_coroutine_function(obj):
+            logger.debug(f"Found factory function '{name}' in {file_path}")
+
+            try:
+                if is_coroutine_function(obj):
+                    # Async factory function
+                    server = await obj()
+                else:
+                    # Sync factory function
+                    server = obj()
+
+                # Validate the result is a FastMCP server
+                if not isinstance(server, FastMCP | SDKServer):
+                    logger.error(
+                        f"Factory function '{name}' must return a FastMCP server instance, "
+                        f"got {type(server).__name__}",
+                        extra={"file": str(file_path)},
+                    )
+                    sys.exit(1)
+
+                logger.debug(f"Factory function '{name}' created server: {server.name}")
+                return server
+
+            except Exception as e:
+                logger.error(
+                    f"Failed to call factory function '{name}': {e}",
+                    extra={"file": str(file_path)},
+                )
+                sys.exit(1)
+
+        # Not a function, return as-is (should be a server instance)
+        return obj
diff --git a/fastmcp_slim/fastmcp/utilities/mime.py b/fastmcp_slim/fastmcp/utilities/mime.py
new file mode 100644
index 0000000..73b912e
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/mime.py
@@ -0,0 +1,27 @@
+"""MIME type constants and helpers for MCP Apps UI resources.
+
+This module has no dependencies on the server or resource packages,
+so it can be safely imported from anywhere.
+"""
+
+UI_MIME_TYPE = "text/html;profile=mcp-app"
+
+
+def resolve_ui_mime_type(uri: str, explicit_mime_type: str | None) -> str | None:
+    """Return the appropriate MIME type for a resource URI.
+
+    For ``ui://`` scheme resources, defaults to ``UI_MIME_TYPE`` when no
+    explicit MIME type is provided.
+
+    Args:
+        uri: The resource URI string
+        explicit_mime_type: The MIME type explicitly provided by the user
+
+    Returns:
+        The resolved MIME type (explicit value, UI default, or None)
+    """
+    if explicit_mime_type is not None:
+        return explicit_mime_type
+    if uri.lower().startswith("ui://"):
+        return UI_MIME_TYPE
+    return None
diff --git a/fastmcp_slim/fastmcp/utilities/openapi/README.md b/fastmcp_slim/fastmcp/utilities/openapi/README.md
new file mode 100644
index 0000000..2f2a5f4
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/openapi/README.md
@@ -0,0 +1,211 @@
+# OpenAPI Utilities
+
+This directory contains the OpenAPI integration utilities for FastMCP.
+
+## Architecture Overview
+
+The implementation follows a **stateless request building strategy** using `openapi-core` for high-performance, per-request HTTP request construction, eliminating startup latency while maintaining robust OpenAPI compliance.
+
+### Core Components
+
+1. **`director.py`** - `RequestDirector` for stateless HTTP request building
+2. **`parser.py`** - OpenAPI spec parsing and route extraction with pre-calculated schemas
+3. **`schemas.py`** - Schema processing with parameter mapping for collision handling
+4. **`models.py`** - Enhanced data models with pre-calculated fields for performance
+5. **`formatters.py`** - Response formatting and processing utilities
+
+### Key Architecture Principles
+
+#### 1. Stateless Request Building
+- Uses `openapi-core` library for robust OpenAPI parameter serialization
+- Builds HTTP requests on-demand with zero startup latency
+- Offloads OpenAPI compliance to a well-tested library without code generation overhead
+
+#### 2. Pre-calculated Optimization
+- **Schema Pre-calculation**: Combined schemas calculated once during parsing
+- **Parameter Mapping**: Collision resolution mapping calculated upfront
+- **Zero Runtime Overhead**: All complex processing done during initialization
+
+#### 3. Performance-First Design
+- **No Code Generation**: Eliminates 100-200ms startup latency
+- **Serverless Friendly**: Ideal for cold-start environments
+- **Minimal Dependencies**: Uses lightweight `openapi-core` instead of full client generation
+
+## Data Flow
+
+### Initialization Process
+
+```
+OpenAPI Spec → Parser → HTTPRoute with Pre-calculated Fields → RequestDirector + SchemaPath
+```
+
+1. **Input**: Raw OpenAPI specification (dict)
+2. **Parsing**: Extract operations to `HTTPRoute` models
+3. **Pre-calculation**: Generate combined schemas and parameter maps during parsing
+4. **Director Setup**: Create `RequestDirector` with `SchemaPath` for request building
+
+### Request Processing
+
+```
+MCP Tool Call → RequestDirector.build() → httpx.Request → HTTP Response → Structured Output
+```
+
+1. **Tool Invocation**: FastMCP receives tool call with parameters
+2. **Request Building**: RequestDirector builds HTTP request using parameter map
+3. **Parameter Handling**: openapi-core handles all OpenAPI serialization rules
+4. **Response Processing**: Parse response into structured format with proper error handling
+
+## Key Features
+
+### 1. High-Performance Request Building
+- Zero startup latency - no code generation required
+- Stateless request building scales infinitely
+- Uses proven `openapi-core` library for OpenAPI compliance
+- Perfect for serverless and cold-start environments
+
+### 2. Comprehensive Parameter Support
+- **Parameter Collisions**: Intelligent collision resolution with suffixing
+- **DeepObject Style**: Full support for deepObject parameters with explode=true/false
+- **Complex Schemas**: Handles nested objects, arrays, and all OpenAPI types
+- **Pre-calculated Mapping**: Parameter location mapping done upfront for performance
+
+### 3. Enhanced Error Handling
+- HTTP status code mapping to MCP errors
+- Structured error responses with detailed information
+- Graceful handling of network timeouts and connection errors
+- Proper error context preservation
+
+### 4. Advanced Schema Processing
+- **Pre-calculated Schemas**: Combined parameter and body schemas calculated once
+- **Collision-aware**: Automatically handles parameter name collisions
+- **Type Safety**: Full Pydantic model validation
+- **Performance**: Zero runtime schema processing overhead
+
+## Component Integration
+
+### Server Components (`/server/openapi/`)
+
+1. **`OpenAPITool`** - Simplified tool implementation using RequestDirector
+2. **`OpenAPIResource`** - Resource implementation with RequestDirector
+3. **`OpenAPIResourceTemplate`** - Resource template with RequestDirector support
+4. **`FastMCPOpenAPI`** - Main server class with stateless request building
+
+### RequestDirector Integration
+
+All components use the same RequestDirector approach:
+- Consistent parameter handling across all component types
+- Uniform error handling and response processing
+- Simplified architecture without fallback complexity
+- High performance for all operation types
+
+## Usage Examples
+
+### Basic Server Setup
+
+```python
+import httpx
+from fastmcp.server.openapi import FastMCPOpenAPI
+
+# OpenAPI spec (can be loaded from file/URL)
+openapi_spec = {...}
+
+# Create HTTP client
+async with httpx.AsyncClient() as client:
+    # Create server with stateless request building
+    server = FastMCPOpenAPI(
+        openapi_spec=openapi_spec,
+        client=client,
+        name="My API Server"
+    )
+    
+    # Server automatically creates RequestDirector and pre-calculates schemas
+```
+
+### Direct RequestDirector Usage
+
+```python
+from fastmcp.utilities.openapi.director import RequestDirector
+from jsonschema_path import SchemaPath
+
+# Create RequestDirector manually
+spec = SchemaPath.from_dict(openapi_spec)
+director = RequestDirector(spec)
+
+# Build HTTP request
+request = director.build(route, flat_arguments, base_url)
+
+# Execute with httpx
+async with httpx.AsyncClient() as client:
+    response = await client.send(request)
+```
+
+## Testing Strategy
+
+Tests are located in `/tests/server/openapi/`:
+
+### Test Categories
+
+1. **Core Functionality**
+   - `test_server.py` - Server initialization and RequestDirector integration
+
+2. **OpenAPI Features**  
+   - `test_parameter_collisions.py` - Parameter name collision handling
+   - `test_deepobject_style.py` - DeepObject parameter style support
+   - `test_openapi_features.py` - General OpenAPI feature compliance
+
+### Testing Philosophy
+
+- **Real Objects**: Use real HTTPRoute models and OpenAPI specifications
+- **Minimal Mocking**: Only mock external HTTP endpoints
+- **Performance Focus**: Test that initialization is fast and stateless
+- **Behavioral Testing**: Verify OpenAPI compliance without implementation details
+
+## Future Enhancements
+
+### Planned Features
+
+1. **Response Streaming**: Handle streaming API responses
+2. **Enhanced Authentication**: More auth provider integrations
+3. **Advanced Metrics**: Detailed request/response monitoring
+4. **Schema Validation**: Enhanced input/output validation
+5. **Batch Operations**: Optimized multi-operation requests
+
+### Performance Improvements
+
+1. **Schema Caching**: More aggressive schema pre-calculation
+2. **Memory Optimization**: Further reduce memory footprint
+3. **Request Batching**: Smart batching for bulk operations
+4. **Connection Optimization**: Enhanced connection pooling strategies
+
+## Troubleshooting
+
+### Common Issues
+
+1. **RequestDirector Initialization Fails**
+   - Check OpenAPI spec validity with `jsonschema-path`
+   - Verify spec format is correct JSON/YAML
+   - Ensure all required OpenAPI fields are present
+
+2. **Parameter Mapping Issues**
+   - Check parameter collision resolution in debug logs
+   - Verify parameter names match OpenAPI spec exactly
+   - Review pre-calculated parameter map in HTTPRoute
+
+3. **Request Building Errors**
+   - Check network connectivity to target API
+   - Verify base URL configuration
+   - Review parameter validation and type mismatches
+
+### Debugging
+
+- Enable debug logging: `logger.setLevel(logging.DEBUG)`
+- Check RequestDirector initialization logs
+- Review parameter mapping in HTTPRoute models
+- Monitor request building and API response patterns
+
+## Dependencies
+
+- `openapi-core` - OpenAPI specification processing and validation
+- `httpx` - HTTP client library
+- `pydantic` - Data validation and serialization
+- `urllib.parse` - URL building and manipulation
\ No newline at end of file
diff --git a/fastmcp_slim/fastmcp/utilities/openapi/__init__.py b/fastmcp_slim/fastmcp/utilities/openapi/__init__.py
new file mode 100644
index 0000000..eb25666
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/openapi/__init__.py
@@ -0,0 +1,61 @@
+"""OpenAPI utilities for FastMCP - refactored for better maintainability."""
+
+# Import from models
+from .models import (
+    HTTPRoute,
+    HttpMethod,
+    JsonSchema,
+    ParameterInfo,
+    ParameterLocation,
+    RequestBodyInfo,
+    ResponseInfo,
+)
+
+# Import from parser
+from .parser import parse_openapi_to_http_routes
+
+# Import from formatters
+from .formatters import (
+    format_array_parameter,
+    format_deep_object_parameter,
+    format_description_with_responses,
+    format_json_for_description,
+    generate_example_from_schema,
+)
+
+# Import from schemas
+from .schemas import (
+    _combine_schemas,
+    extract_output_schema_from_responses,
+    clean_schema_for_display,
+    _make_optional_parameter_nullable,
+)
+
+# Import from json_schema_converter
+from .json_schema_converter import (
+    convert_openapi_schema_to_json_schema,
+    convert_schema_definitions,
+)
+
+# Export public symbols - maintaining backward compatibility
+__all__ = [
+    "HTTPRoute",
+    "HttpMethod",
+    "JsonSchema",
+    "ParameterInfo",
+    "ParameterLocation",
+    "RequestBodyInfo",
+    "ResponseInfo",
+    "_combine_schemas",
+    "_make_optional_parameter_nullable",
+    "clean_schema_for_display",
+    "convert_openapi_schema_to_json_schema",
+    "convert_schema_definitions",
+    "extract_output_schema_from_responses",
+    "format_array_parameter",
+    "format_deep_object_parameter",
+    "format_description_with_responses",
+    "format_json_for_description",
+    "generate_example_from_schema",
+    "parse_openapi_to_http_routes",
+]
diff --git a/fastmcp_slim/fastmcp/utilities/openapi/director.py b/fastmcp_slim/fastmcp/utilities/openapi/director.py
new file mode 100644
index 0000000..4615739
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/openapi/director.py
@@ -0,0 +1,375 @@
+"""Request director using openapi-core for stateless HTTP request building."""
+
+import io
+import json as _json
+from typing import Any, ClassVar
+from urllib.parse import quote, urljoin
+
+import httpx
+from jsonschema_path import SchemaPath
+
+from fastmcp.utilities.logging import get_logger
+
+from .models import HTTPRoute, ParameterInfo
+
+logger = get_logger(__name__)
+
+
+def _query_scalar_to_str(value: Any) -> str:
+    """Convert a scalar to its query-string representation.
+
+    Booleans are lowercased to match JSON/OpenAPI conventions (true/false)
+    rather than Python's str(True) → "True".
+    """
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+class RequestDirector:
+    """Builds httpx.Request objects from HTTPRoute and arguments using openapi-core."""
+
+    def __init__(self, spec: SchemaPath):
+        """Initialize with a parsed SchemaPath object."""
+        self._spec = spec
+
+    def build(
+        self,
+        route: HTTPRoute,
+        flat_args: dict[str, Any],
+        base_url: str = "http://localhost",
+    ) -> httpx.Request:
+        """
+        Constructs a final httpx.Request object, handling all OpenAPI serialization.
+
+        Args:
+            route: HTTPRoute containing OpenAPI operation details
+            flat_args: Flattened arguments from LLM (may include suffixed parameters)
+            base_url: Base URL for the request
+
+        Returns:
+            httpx.Request: Properly formatted HTTP request
+        """
+        logger.debug(
+            f"Building request for {route.method} {route.path} with args: {flat_args}"
+        )
+
+        # Step 1: Un-flatten arguments into path, query, body, etc. using parameter map
+        path_params, query_params, header_params, cookie_params, body = (
+            self._unflatten_arguments(route, flat_args)
+        )
+
+        logger.debug(
+            f"Unflattened - path: {path_params}, query: {query_params}, headers: {header_params}, body: {body}"
+        )
+
+        # Step 2: Serialize query parameters according to OpenAPI style/explode
+        query_params = self._serialize_query_params(route, query_params)
+
+        # Step 3: Build base URL with path parameters
+        url = self._build_url(route.path, path_params, base_url)
+
+        # Step 4: Prepare request data
+        method: str = route.method.upper()
+        params = query_params if query_params else None
+        headers = header_params if header_params else None
+        json_body: dict[str, Any] | list[Any] | None = None
+        content: str | bytes | None = None
+
+        # Step 5: Determine the declared content type from the OpenAPI spec.
+        # Use the raw value for outgoing Content-Type headers (preserves
+        # parameters like charset), but normalize for dispatch matching.
+        raw_content_type: str | None = None
+        declared_content_type: str | None = None
+        if route.request_body and route.request_body.content_schema:
+            raw_content_type = next(iter(route.request_body.content_schema))
+            declared_content_type = raw_content_type.split(";")[0].strip().lower()
+
+        # httpx requires cookie values to be strings; use OpenAPI-style
+        # serialization (e.g. true/false for booleans, not True/False)
+        cookies = (
+            {k: _query_scalar_to_str(v) for k, v in cookie_params.items()}
+            if cookie_params
+            else None
+        )
+
+        # Step 6: Handle request body — dispatch on declared content type.
+        # httpx body kwargs (json, content, data, files) are mutually exclusive
+        # but all accept None, so we set exactly one and pass all to Request().
+        files: dict[str, Any] | None = None
+        data: dict[str, Any] | None = None
+        if body is not None:
+            if declared_content_type == "multipart/form-data" and isinstance(
+                body, dict
+            ):
+                # Wrap plain values as (None, stringified) tuples so httpx
+                # treats them as form fields. Scalars must be stringified
+                # because httpx rejects non-string/bytes values in files=.
+                # Use _query_scalar_to_str for booleans (true/false, not True/False).
+                files = {}
+                for k, v in body.items():
+                    if isinstance(v, tuple):
+                        files[k] = v
+                    elif isinstance(v, bytes | io.IOBase):
+                        # bytes and file-like objects are passed directly so
+                        # httpx can transmit them as binary parts without
+                        # stringifying to their Python repr.
+                        files[k] = (None, v)
+                    else:
+                        files[k] = (None, _query_scalar_to_str(v))
+            elif (
+                declared_content_type == "application/x-www-form-urlencoded"
+                and isinstance(body, dict)
+            ):
+                data = body
+            elif isinstance(body, dict | list):
+                if (
+                    declared_content_type is not None
+                    and declared_content_type != "application/json"
+                    and "json" in declared_content_type
+                ):
+                    # JSON-compatible types like application/json-patch+json
+                    # or application/merge-patch+json need an explicit
+                    # Content-Type header since httpx's json= always
+                    # sets application/json.
+                    content = _json.dumps(body, allow_nan=False).encode("utf-8")
+                    headers = dict(headers) if headers else {}
+                    headers["Content-Type"] = raw_content_type
+                else:
+                    json_body = body
+            else:
+                content = body
+
+        # Step 7: Create httpx.Request
+        return httpx.Request(
+            method=method,
+            url=url,
+            params=params,
+            headers=headers,
+            json=json_body,
+            content=content,
+            data=data,
+            files=files,
+            cookies=cookies,
+        )
+
+    def _unflatten_arguments(
+        self, route: HTTPRoute, flat_args: dict[str, Any]
+    ) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any], dict[str, Any], Any]:
+        """
+        Maps flat arguments back to their OpenAPI locations using the parameter map.
+
+        Args:
+            route: HTTPRoute with parameter_map containing location mappings
+            flat_args: Flat arguments from LLM call
+
+        Returns:
+            Tuple of (path_params, query_params, header_params, cookie_params, body)
+        """
+        path_params = {}
+        query_params = {}
+        header_params = {}
+        cookie_params = {}
+        body_props = {}
+
+        # Use parameter map to route arguments to correct locations
+        if hasattr(route, "parameter_map") and route.parameter_map:
+            for arg_name, value in flat_args.items():
+                if value is None:
+                    continue  # Skip None values for optional parameters
+
+                if arg_name not in route.parameter_map:
+                    logger.warning(
+                        f"Argument '{arg_name}' not found in parameter map for {route.operation_id}"
+                    )
+                    continue
+
+                mapping = route.parameter_map[arg_name]
+                location = mapping["location"]
+                openapi_name = mapping["openapi_name"]
+
+                if location == "path":
+                    path_params[openapi_name] = value
+                elif location == "query":
+                    query_params[openapi_name] = value
+                elif location == "header":
+                    header_params[openapi_name] = value
+                elif location == "cookie":
+                    cookie_params[openapi_name] = value
+                elif location == "body":
+                    body_props[openapi_name] = value
+                else:
+                    logger.warning(
+                        f"Unknown parameter location '{location}' for {arg_name}"
+                    )
+        else:
+            # Fallback: try to map arguments based on parameter definitions
+            logger.debug("No parameter map available, using fallback mapping")
+
+            # Create a mapping from parameter names to their locations
+            param_locations = {}
+            for param in route.parameters:
+                param_locations[param.name] = param.location
+
+            # Map arguments to locations
+            for arg_name, value in flat_args.items():
+                if value is None:
+                    continue
+
+                # Check if it's a suffixed parameter (e.g., id__path)
+                if "__" in arg_name:
+                    base_name, location = arg_name.rsplit("__", 1)
+                    if location in ["path", "query", "header", "cookie"]:
+                        if location == "path":
+                            path_params[base_name] = value
+                        elif location == "query":
+                            query_params[base_name] = value
+                        elif location == "header":
+                            header_params[base_name] = value
+                        elif location == "cookie":
+                            cookie_params[base_name] = value
+                        continue
+
+                # Check if it's a known parameter
+                if arg_name in param_locations:
+                    location = param_locations[arg_name]
+                    if location == "path":
+                        path_params[arg_name] = value
+                    elif location == "query":
+                        query_params[arg_name] = value
+                    elif location == "header":
+                        header_params[arg_name] = value
+                    elif location == "cookie":
+                        cookie_params[arg_name] = value
+                else:
+                    # Assume it's a body property
+                    body_props[arg_name] = value
+
+        # Handle body construction
+        body = None
+        if body_props:
+            # If we have body properties, construct the body object
+            if (
+                route.request_body
+                and route.request_body.content_schema
+                and len(route.request_body.content_schema) > 0
+            ):
+                content_type = next(iter(route.request_body.content_schema))
+                body_schema = route.request_body.content_schema[content_type]
+
+                if (
+                    isinstance(body_schema, dict)
+                    and body_schema.get("type") == "object"
+                ):
+                    body = body_props
+                elif len(body_props) == 1:
+                    # If body schema is not an object and we have exactly one property,
+                    # use the property value directly
+                    body = next(iter(body_props.values()))
+                else:
+                    # Multiple properties but schema is not object - wrap in object
+                    body = body_props
+            else:
+                body = body_props
+
+        return path_params, query_params, header_params, cookie_params, body
+
+    # Delimiter per OpenAPI style when explode=false
+    _STYLE_DELIMITERS: ClassVar[dict[str, str]] = {
+        "form": ",",
+        "spaceDelimited": " ",
+        "pipeDelimited": "|",
+    }
+
+    def _serialize_query_params(
+        self,
+        route: HTTPRoute,
+        query_params: dict[str, Any],
+    ) -> dict[str, Any]:
+        """
+        Serialize query parameter values according to their OpenAPI style/explode settings.
+
+        By default (style=form, explode=true), list values are passed through as-is
+        so httpx repeats the key (e.g. values=a&values=b). When explode=false,
+        list values are joined with the style-appropriate delimiter:
+          - form (default): comma  (values=a,b)
+          - pipeDelimited:  pipe   (values=a|b)
+          - spaceDelimited: space  (values=a%20b)
+        """
+        if not query_params:
+            return query_params
+
+        # Build a lookup from openapi_name -> ParameterInfo for query params
+        param_lookup: dict[str, ParameterInfo] = {
+            p.name: p for p in route.parameters if p.location == "query"
+        }
+
+        serialized: dict[str, Any] = {}
+        for key, value in query_params.items():
+            param_info = param_lookup.get(key)
+            if param_info is not None:
+                explode = param_info.explode if param_info.explode is not None else True
+                if isinstance(value, dict):
+                    if not value:
+                        continue
+                    if explode:
+                        # form,explode=true on objects: each property becomes
+                        # a separate query parameter.
+                        # e.g. {"R": 100, "G": 200} → R=100&G=200
+                        for k, v in value.items():
+                            serialized[_query_scalar_to_str(k)] = _query_scalar_to_str(
+                                v
+                            )
+                    else:
+                        style = param_info.style or "form"
+                        delimiter = self._STYLE_DELIMITERS.get(style, ",")
+                        # form,explode=false on objects: key,value pairs
+                        # e.g. {"R": 100, "G": 200} → "R,100,G,200"
+                        parts: list[str] = []
+                        for k, v in value.items():
+                            parts.append(_query_scalar_to_str(k))
+                            parts.append(_query_scalar_to_str(v))
+                        serialized[key] = delimiter.join(parts)
+                    continue
+                if not explode:
+                    style = param_info.style or "form"
+                    delimiter = self._STYLE_DELIMITERS.get(style, ",")
+                    if isinstance(value, list):
+                        if not value:
+                            continue
+                        serialized[key] = delimiter.join(
+                            _query_scalar_to_str(v) for v in value
+                        )
+                        continue
+            serialized[key] = value
+        return serialized
+
+    def _build_url(
+        self, path_template: str, path_params: dict[str, Any], base_url: str
+    ) -> str:
+        """
+        Build URL by substituting path parameters in the template.
+
+        Args:
+            path_template: OpenAPI path template (e.g., "/users/{id}")
+            path_params: Path parameter values
+            base_url: Base URL to prepend
+
+        Returns:
+            Complete URL with path parameters substituted
+        """
+        # Substitute path parameters with URL-encoding to prevent
+        # path traversal and SSRF via crafted parameter values
+        url_path = path_template
+        for param_name, param_value in path_params.items():
+            placeholder = f"{{{param_name}}}"
+            if placeholder in url_path:
+                safe_value = quote(str(param_value), safe="").replace(".", "%2E")
+                url_path = url_path.replace(placeholder, safe_value)
+
+        # Combine with base URL
+        return urljoin(base_url.rstrip("/") + "/", url_path.lstrip("/"))
+
+
+# Export public symbols
+__all__ = ["RequestDirector"]
diff --git a/fastmcp_slim/fastmcp/utilities/openapi/formatters.py b/fastmcp_slim/fastmcp/utilities/openapi/formatters.py
new file mode 100644
index 0000000..a0bd75b
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/openapi/formatters.py
@@ -0,0 +1,355 @@
+"""Parameter formatting functions for OpenAPI operations."""
+
+import json
+import logging
+from typing import Any
+
+from .models import JsonSchema, ParameterInfo, RequestBodyInfo
+
+logger = logging.getLogger(__name__)
+
+
+def format_array_parameter(
+    values: list, parameter_name: str, is_query_parameter: bool = False
+) -> str | list:
+    """
+    Format an array parameter according to OpenAPI specifications.
+
+    Args:
+        values: List of values to format
+        parameter_name: Name of the parameter (for error messages)
+        is_query_parameter: If True, can return list for explode=True behavior
+
+    Returns:
+        String (comma-separated) or list (for query params with explode=True)
+    """
+    # For arrays of simple types (strings, numbers, etc.), join with commas
+    if all(isinstance(item, str | int | float | bool) for item in values):
+        return ",".join(str(v) for v in values)
+
+    # For complex types, try to create a simpler representation
+    try:
+        # Try to create a simple string representation
+        formatted_parts = []
+        for item in values:
+            if isinstance(item, dict):
+                # For objects, serialize key-value pairs
+                item_parts = []
+                for k, v in item.items():
+                    item_parts.append(f"{k}:{v}")
+                formatted_parts.append(".".join(item_parts))
+            else:
+                formatted_parts.append(str(item))
+
+        return ",".join(formatted_parts)
+    except Exception as e:
+        param_type = "query" if is_query_parameter else "path"
+        logger.warning(
+            f"Failed to format complex array {param_type} parameter '{parameter_name}': {e}"
+        )
+
+        if is_query_parameter:
+            # For query parameters, fallback to original list
+            return values
+        else:
+            # For path parameters, fallback to string representation without Python syntax
+            str_value = (
+                str(values)
+                .replace("[", "")
+                .replace("]", "")
+                .replace("'", "")
+                .replace('"', "")
+            )
+            return str_value
+
+
+def format_deep_object_parameter(
+    param_value: dict, parameter_name: str
+) -> dict[str, str]:
+    """
+    Format a dictionary parameter for deep-object style serialization.
+
+    According to OpenAPI 3.0 spec, deepObject style with explode=true serializes
+    object properties as separate query parameters with bracket notation.
+
+    For example, `{"id": "123", "type": "user"}` becomes
+    `param[id]=123&param[type]=user`.
+
+    Args:
+        param_value: Dictionary value to format
+        parameter_name: Name of the parameter
+
+    Returns:
+        Dictionary with bracketed parameter names as keys
+    """
+    if not isinstance(param_value, dict):
+        logger.warning(
+            f"Deep-object style parameter '{parameter_name}' expected dict, got {type(param_value)}"
+        )
+        return {}
+
+    result = {}
+    for key, value in param_value.items():
+        # Format as param[key]=value
+        bracketed_key = f"{parameter_name}[{key}]"
+        result[bracketed_key] = str(value)
+
+    return result
+
+
+def generate_example_from_schema(schema: JsonSchema | None) -> Any:
+    """
+    Generate a simple example value from a JSON schema dictionary.
+    Very basic implementation focusing on types.
+    """
+    if not schema or not isinstance(schema, dict):
+        return "unknown"  # Or None?
+
+    # Use default value if provided
+    if "default" in schema:
+        return schema["default"]
+    # Use first enum value if provided
+    if "enum" in schema and isinstance(schema["enum"], list) and schema["enum"]:
+        return schema["enum"][0]
+    # Use first example if provided
+    if (
+        "examples" in schema
+        and isinstance(schema["examples"], list)
+        and schema["examples"]
+    ):
+        return schema["examples"][0]
+    if "example" in schema:
+        return schema["example"]
+
+    schema_type = schema.get("type")
+
+    if schema_type == "object":
+        result = {}
+        properties = schema.get("properties", {})
+        if isinstance(properties, dict):
+            # Generate example for first few properties or required ones? Limit complexity.
+            required_props = set(schema.get("required", []))
+            props_to_include = list(properties.keys())[
+                :3
+            ]  # Limit to first 3 for brevity
+            for prop_name in props_to_include:
+                if prop_name in properties:
+                    result[prop_name] = generate_example_from_schema(
+                        properties[prop_name]
+                    )
+            # Ensure required props are present if possible
+            for req_prop in required_props:
+                if req_prop not in result and req_prop in properties:
+                    result[req_prop] = generate_example_from_schema(
+                        properties[req_prop]
+                    )
+        return result if result else {"key": "value"}  # Basic object if no props
+
+    elif schema_type == "array":
+        items_schema = schema.get("items")
+        if isinstance(items_schema, dict):
+            # Generate one example item
+            item_example = generate_example_from_schema(items_schema)
+            return [item_example] if item_example is not None else []
+        return ["example_item"]  # Fallback
+
+    elif schema_type == "string":
+        format_type = schema.get("format")
+        if format_type == "date-time":
+            return "2024-01-01T12:00:00Z"
+        if format_type == "date":
+            return "2024-01-01"
+        if format_type == "email":
+            return "user@example.com"
+        if format_type == "uuid":
+            return "123e4567-e89b-12d3-a456-426614174000"
+        if format_type == "byte":
+            return "ZXhhbXBsZQ=="  # "example" base64
+        return "string"
+
+    elif schema_type == "integer":
+        return 1
+    elif schema_type == "number":
+        return 1.5
+    elif schema_type == "boolean":
+        return True
+    elif schema_type == "null":
+        return None
+
+    # Fallback if type is unknown or missing
+    return "unknown_type"
+
+
+def format_json_for_description(data: Any, indent: int = 2) -> str:
+    """Formats Python data as a JSON string block for Markdown."""
+    try:
+        json_str = json.dumps(data, indent=indent)
+        return f"```json\n{json_str}\n```"
+    except TypeError:
+        return f"```\nCould not serialize to JSON: {data}\n```"
+
+
+def format_description_with_responses(
+    base_description: str,
+    responses: dict[
+        str, Any
+    ],  # Changed from specific ResponseInfo type to avoid circular imports
+    parameters: list[ParameterInfo] | None = None,  # Add parameters parameter
+    request_body: RequestBodyInfo | None = None,  # Add request_body parameter
+) -> str:
+    """
+    Formats the base description string with response, parameter, and request body information.
+
+    Args:
+        base_description (str): The initial description to be formatted.
+        responses (dict[str, Any]): A dictionary of response information, keyed by status code.
+        parameters (list[ParameterInfo] | None, optional): A list of parameter information,
+            including path and query parameters. Each parameter includes details such as name,
+            location, whether it is required, and a description.
+        request_body (RequestBodyInfo | None, optional): Information about the request body,
+            including its description, whether it is required, and its content schema.
+
+    Returns:
+        str: The formatted description string with additional details about responses, parameters,
+        and the request body.
+    """
+    desc_parts = [base_description]
+
+    # Add parameter information
+    if parameters:
+        # Process path parameters
+        path_params = [p for p in parameters if p.location == "path"]
+        if path_params:
+            param_section = "\n\n**Path Parameters:**"
+            desc_parts.append(param_section)
+            for param in path_params:
+                required_marker = " (Required)" if param.required else ""
+                param_desc = f"\n- **{param.name}**{required_marker}: {param.description or 'No description.'}"
+                desc_parts.append(param_desc)
+
+        # Process query parameters
+        query_params = [p for p in parameters if p.location == "query"]
+        if query_params:
+            param_section = "\n\n**Query Parameters:**"
+            desc_parts.append(param_section)
+            for param in query_params:
+                required_marker = " (Required)" if param.required else ""
+                param_desc = f"\n- **{param.name}**{required_marker}: {param.description or 'No description.'}"
+                desc_parts.append(param_desc)
+
+    # Add request body information if present
+    if request_body and request_body.description:
+        req_body_section = "\n\n**Request Body:**"
+        desc_parts.append(req_body_section)
+        required_marker = " (Required)" if request_body.required else ""
+        desc_parts.append(f"\n{request_body.description}{required_marker}")
+
+        # Add request body property descriptions if available
+        if request_body.content_schema:
+            media_type = (
+                "application/json"
+                if "application/json" in request_body.content_schema
+                else next(iter(request_body.content_schema), None)
+            )
+            if media_type:
+                schema = request_body.content_schema.get(media_type, {})
+                if isinstance(schema, dict) and "properties" in schema:
+                    desc_parts.append("\n\n**Request Properties:**")
+                    for prop_name, prop_schema in schema["properties"].items():
+                        if (
+                            isinstance(prop_schema, dict)
+                            and "description" in prop_schema
+                        ):
+                            required = prop_name in schema.get("required", [])
+                            req_mark = " (Required)" if required else ""
+                            desc_parts.append(
+                                f"\n- **{prop_name}**{req_mark}: {prop_schema['description']}"
+                            )
+
+    # Add response information
+    if responses:
+        response_section = "\n\n**Responses:**"
+        added_response_section = False
+
+        # Determine success codes (common ones)
+        success_codes = {"200", "201", "202", "204"}  # As strings
+        success_status = next((s for s in success_codes if s in responses), None)
+
+        # Process all responses
+        responses_to_process = responses.items()
+
+        for status_code, resp_info in sorted(responses_to_process):
+            if not added_response_section:
+                desc_parts.append(response_section)
+                added_response_section = True
+
+            status_marker = " (Success)" if status_code == success_status else ""
+            desc_parts.append(
+                f"\n- **{status_code}**{status_marker}: {resp_info.description or 'No description.'}"
+            )
+
+            # Process content schemas for this response
+            if resp_info.content_schema:
+                # Prioritize json, then take first available
+                media_type = (
+                    "application/json"
+                    if "application/json" in resp_info.content_schema
+                    else next(iter(resp_info.content_schema), None)
+                )
+
+                if media_type:
+                    schema = resp_info.content_schema.get(media_type)
+                    desc_parts.append(f"  - Content-Type: `{media_type}`")
+
+                    # Add response property descriptions
+                    if isinstance(schema, dict):
+                        # Handle array responses
+                        if schema.get("type") == "array" and "items" in schema:
+                            items_schema = schema["items"]
+                            if (
+                                isinstance(items_schema, dict)
+                                and "properties" in items_schema
+                            ):
+                                desc_parts.append("\n  - **Response Item Properties:**")
+                                for prop_name, prop_schema in items_schema[
+                                    "properties"
+                                ].items():
+                                    if (
+                                        isinstance(prop_schema, dict)
+                                        and "description" in prop_schema
+                                    ):
+                                        desc_parts.append(
+                                            f"\n    - **{prop_name}**: {prop_schema['description']}"
+                                        )
+                        # Handle object responses
+                        elif "properties" in schema:
+                            desc_parts.append("\n  - **Response Properties:**")
+                            for prop_name, prop_schema in schema["properties"].items():
+                                if (
+                                    isinstance(prop_schema, dict)
+                                    and "description" in prop_schema
+                                ):
+                                    desc_parts.append(
+                                        f"\n    - **{prop_name}**: {prop_schema['description']}"
+                                    )
+
+                    # Generate Example
+                    if schema:
+                        example = generate_example_from_schema(schema)
+                        if example != "unknown_type" and example is not None:
+                            desc_parts.append("\n  - **Example:**")
+                            desc_parts.append(
+                                format_json_for_description(example, indent=2)
+                            )
+
+    return "\n".join(desc_parts)
+
+
+# Export public symbols
+__all__ = [
+    "format_array_parameter",
+    "format_deep_object_parameter",
+    "format_description_with_responses",
+    "format_json_for_description",
+    "generate_example_from_schema",
+]
diff --git a/fastmcp_slim/fastmcp/utilities/openapi/json_schema_converter.py b/fastmcp_slim/fastmcp/utilities/openapi/json_schema_converter.py
new file mode 100644
index 0000000..ac6b549
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/openapi/json_schema_converter.py
@@ -0,0 +1,350 @@
+"""
+Clean OpenAPI 3.0 to JSON Schema converter for the experimental parser.
+
+This module provides a systematic approach to converting OpenAPI 3.0 schemas
+to JSON Schema, inspired by py-openapi-schema-to-json-schema but optimized
+for our specific use case.
+"""
+
+from typing import Any
+
+from fastmcp.utilities.json_schema import require_discriminator_property
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+# OpenAPI-specific fields that should be removed from JSON Schema
+OPENAPI_SPECIFIC_FIELDS = {
+    "nullable",  # Handled by converting to type arrays
+    "discriminator",  # OpenAPI-specific
+    "readOnly",  # OpenAPI-specific metadata
+    "writeOnly",  # OpenAPI-specific metadata
+    "xml",  # OpenAPI-specific metadata
+    "externalDocs",  # OpenAPI-specific metadata
+    "deprecated",  # Can be kept but not part of JSON Schema core
+}
+
+# Fields that should be recursively processed
+RECURSIVE_FIELDS = {
+    "properties": dict,
+    "$defs": dict,
+    "$definitions": dict,
+    "items": dict,
+    "additionalProperties": dict,
+    "allOf": list,
+    "anyOf": list,
+    "oneOf": list,
+    "not": dict,
+}
+
+
+def convert_openapi_schema_to_json_schema(
+    schema: dict[str, Any],
+    openapi_version: str | None = None,
+    remove_read_only: bool = False,
+    remove_write_only: bool = False,
+    convert_one_of_to_any_of: bool = True,
+) -> dict[str, Any]:
+    """
+    Convert an OpenAPI schema to JSON Schema format.
+
+    This is a clean, systematic approach that:
+    1. Removes OpenAPI-specific fields
+    2. Converts nullable fields to type arrays (for OpenAPI 3.0 only)
+    3. Converts oneOf to anyOf for overlapping union handling
+    4. Recursively processes nested schemas
+    5. Optionally removes readOnly/writeOnly properties
+
+    Args:
+        schema: OpenAPI schema dictionary
+        openapi_version: OpenAPI version for optimization
+        remove_read_only: Whether to remove readOnly properties
+        remove_write_only: Whether to remove writeOnly properties
+        convert_one_of_to_any_of: Whether to convert oneOf to anyOf
+
+    Returns:
+        JSON Schema-compatible dictionary
+    """
+    if not isinstance(schema, dict):
+        return schema
+
+    # Early exit optimization - check if conversion is needed
+    needs_conversion = (
+        any(field in schema for field in OPENAPI_SPECIFIC_FIELDS)
+        or (remove_read_only and _has_read_only_properties(schema))
+        or (remove_write_only and _has_write_only_properties(schema))
+        or (convert_one_of_to_any_of and "oneOf" in schema)
+        or _needs_recursive_processing(
+            schema,
+            openapi_version,
+            remove_read_only,
+            remove_write_only,
+            convert_one_of_to_any_of,
+        )
+    )
+
+    if not needs_conversion:
+        return schema
+
+    # Work on a copy to avoid mutation
+    result = schema.copy()
+
+    # Step 1: Handle nullable field conversion (OpenAPI 3.0 only)
+    if openapi_version and openapi_version.startswith("3.0"):
+        result = _convert_nullable_field(result)
+
+    # Step 2: Convert oneOf to anyOf if requested
+    if convert_one_of_to_any_of and "oneOf" in result:
+        result["anyOf"] = result.pop("oneOf")
+
+    # Step 3: Preserve discriminator tag presence before removing the keyword
+    result = require_discriminator_property(result)
+
+    # Step 4: Remove OpenAPI-specific fields
+    for field in OPENAPI_SPECIFIC_FIELDS:
+        result.pop(field, None)
+
+    # Step 5: Handle readOnly/writeOnly property removal
+    if remove_read_only or remove_write_only:
+        result = _filter_properties_by_access(
+            result, remove_read_only, remove_write_only
+        )
+
+    # Step 6: Recursively process nested schemas
+    for field_name, field_type in RECURSIVE_FIELDS.items():
+        if field_name in result:
+            if field_type is dict and isinstance(result[field_name], dict):
+                if field_name in ("properties", "$defs", "$definitions"):
+                    # Handle maps of schemas (properties, $defs, $definitions)
+                    result[field_name] = {
+                        name: convert_openapi_schema_to_json_schema(
+                            sub_schema,
+                            openapi_version,
+                            remove_read_only,
+                            remove_write_only,
+                            convert_one_of_to_any_of,
+                        )
+                        if isinstance(sub_schema, dict)
+                        else sub_schema
+                        for name, sub_schema in result[field_name].items()
+                    }
+                else:
+                    result[field_name] = convert_openapi_schema_to_json_schema(
+                        result[field_name],
+                        openapi_version,
+                        remove_read_only,
+                        remove_write_only,
+                        convert_one_of_to_any_of,
+                    )
+            elif field_type is list and isinstance(result[field_name], list):
+                result[field_name] = [
+                    convert_openapi_schema_to_json_schema(
+                        item,
+                        openapi_version,
+                        remove_read_only,
+                        remove_write_only,
+                        convert_one_of_to_any_of,
+                    )
+                    if isinstance(item, dict)
+                    else item
+                    for item in result[field_name]
+                ]
+
+    return result
+
+
+def _convert_nullable_field(schema: dict[str, Any]) -> dict[str, Any]:
+    """Convert OpenAPI nullable field to JSON Schema type array."""
+    if "nullable" not in schema:
+        return schema
+
+    result = schema.copy()
+    nullable_value = result.pop("nullable")
+
+    # Only convert if nullable is True and we have a type structure
+    if not nullable_value:
+        return result
+
+    if "type" in result:
+        current_type = result["type"]
+        if isinstance(current_type, str):
+            result["type"] = [current_type, "null"]
+        elif isinstance(current_type, list) and "null" not in current_type:
+            result["type"] = [*current_type, "null"]
+    elif "oneOf" in result:
+        # Convert oneOf to anyOf with null
+        result["anyOf"] = [*result.pop("oneOf"), {"type": "null"}]
+    elif "anyOf" in result:
+        # Add null to anyOf if not present
+        if not any(item.get("type") == "null" for item in result["anyOf"]):
+            result["anyOf"] = [*result["anyOf"], {"type": "null"}]
+    elif "allOf" in result:
+        # Wrap allOf in anyOf with null option
+        result["anyOf"] = [{"allOf": result.pop("allOf")}, {"type": "null"}]
+
+    # Handle enum fields - add null to enum values if present
+    if "enum" in result and None not in result["enum"]:
+        result["enum"] = result["enum"] + [None]
+
+    return result
+
+
+def _has_read_only_properties(schema: dict[str, Any]) -> bool:
+    """Quick check if schema has any readOnly properties."""
+    if "properties" not in schema:
+        return False
+    return any(
+        isinstance(prop, dict) and prop.get("readOnly")
+        for prop in schema["properties"].values()
+    )
+
+
+def _has_write_only_properties(schema: dict[str, Any]) -> bool:
+    """Quick check if schema has any writeOnly properties."""
+    if "properties" not in schema:
+        return False
+    return any(
+        isinstance(prop, dict) and prop.get("writeOnly")
+        for prop in schema["properties"].values()
+    )
+
+
+def _needs_recursive_processing(
+    schema: dict[str, Any],
+    openapi_version: str | None,
+    remove_read_only: bool,
+    remove_write_only: bool,
+    convert_one_of_to_any_of: bool,
+) -> bool:
+    """Check if the schema needs recursive processing (smarter than just checking for recursive fields)."""
+    for field_name, field_type in RECURSIVE_FIELDS.items():
+        if field_name in schema:
+            if field_type is dict and isinstance(schema[field_name], dict):
+                if field_name in ("properties", "$defs", "$definitions"):
+                    # Check if any schema in the map needs conversion
+                    for sub_schema in schema[field_name].values():
+                        if isinstance(sub_schema, dict):
+                            nested_needs_conversion = (
+                                any(
+                                    field in sub_schema
+                                    for field in OPENAPI_SPECIFIC_FIELDS
+                                )
+                                or (remove_read_only and sub_schema.get("readOnly"))
+                                or (remove_write_only and sub_schema.get("writeOnly"))
+                                or (convert_one_of_to_any_of and "oneOf" in sub_schema)
+                                or _needs_recursive_processing(
+                                    sub_schema,
+                                    openapi_version,
+                                    remove_read_only,
+                                    remove_write_only,
+                                    convert_one_of_to_any_of,
+                                )
+                            )
+                            if nested_needs_conversion:
+                                return True
+                else:
+                    # Check if nested schema needs conversion
+                    nested_needs_conversion = (
+                        any(
+                            field in schema[field_name]
+                            for field in OPENAPI_SPECIFIC_FIELDS
+                        )
+                        or (
+                            remove_read_only
+                            and _has_read_only_properties(schema[field_name])
+                        )
+                        or (
+                            remove_write_only
+                            and _has_write_only_properties(schema[field_name])
+                        )
+                        or (convert_one_of_to_any_of and "oneOf" in schema[field_name])
+                        or _needs_recursive_processing(
+                            schema[field_name],
+                            openapi_version,
+                            remove_read_only,
+                            remove_write_only,
+                            convert_one_of_to_any_of,
+                        )
+                    )
+                    if nested_needs_conversion:
+                        return True
+            elif field_type is list and isinstance(schema[field_name], list):
+                # Check if any list item needs conversion
+                for item in schema[field_name]:
+                    if isinstance(item, dict):
+                        nested_needs_conversion = (
+                            any(field in item for field in OPENAPI_SPECIFIC_FIELDS)
+                            or (remove_read_only and _has_read_only_properties(item))
+                            or (remove_write_only and _has_write_only_properties(item))
+                            or (convert_one_of_to_any_of and "oneOf" in item)
+                            or _needs_recursive_processing(
+                                item,
+                                openapi_version,
+                                remove_read_only,
+                                remove_write_only,
+                                convert_one_of_to_any_of,
+                            )
+                        )
+                        if nested_needs_conversion:
+                            return True
+    return False
+
+
+def _filter_properties_by_access(
+    schema: dict[str, Any], remove_read_only: bool, remove_write_only: bool
+) -> dict[str, Any]:
+    """Remove readOnly and/or writeOnly properties from schema."""
+    if "properties" not in schema:
+        return schema
+
+    result = schema.copy()
+    filtered_properties = {}
+
+    for prop_name, prop_schema in result["properties"].items():
+        if not isinstance(prop_schema, dict):
+            filtered_properties[prop_name] = prop_schema
+            continue
+
+        should_remove = (remove_read_only and prop_schema.get("readOnly")) or (
+            remove_write_only and prop_schema.get("writeOnly")
+        )
+
+        if not should_remove:
+            filtered_properties[prop_name] = prop_schema
+
+    result["properties"] = filtered_properties
+
+    # Clean up required array if properties were removed
+    if "required" in result and filtered_properties:
+        result["required"] = [
+            prop for prop in result["required"] if prop in filtered_properties
+        ]
+        if not result["required"]:
+            result.pop("required")
+
+    return result
+
+
+def convert_schema_definitions(
+    schema_definitions: dict[str, Any] | None,
+    openapi_version: str | None = None,
+    **kwargs,
+) -> dict[str, Any]:
+    """
+    Convert a dictionary of OpenAPI schema definitions to JSON Schema.
+
+    Args:
+        schema_definitions: Dictionary of schema definitions
+        openapi_version: OpenAPI version for optimization
+        **kwargs: Additional arguments passed to convert_openapi_schema_to_json_schema
+
+    Returns:
+        Dictionary of converted schema definitions
+    """
+    if not schema_definitions:
+        return {}
+
+    return {
+        name: convert_openapi_schema_to_json_schema(schema, openapi_version, **kwargs)
+        for name, schema in schema_definitions.items()
+    }
diff --git a/fastmcp_slim/fastmcp/utilities/openapi/models.py b/fastmcp_slim/fastmcp/utilities/openapi/models.py
new file mode 100644
index 0000000..03d2eb6
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/openapi/models.py
@@ -0,0 +1,88 @@
+"""Intermediate Representation (IR) models for OpenAPI operations."""
+
+from typing import Any, Literal
+
+from pydantic import Field
+
+from fastmcp.utilities.types import FastMCPBaseModel
+
+# Type definitions
+HttpMethod = Literal[
+    "GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD", "TRACE"
+]
+ParameterLocation = Literal["path", "query", "header", "cookie"]
+JsonSchema = dict[str, Any]
+
+
+class ParameterInfo(FastMCPBaseModel):
+    """Represents a single parameter for an HTTP operation in our IR."""
+
+    name: str
+    location: ParameterLocation  # Mapped from 'in' field of openapi-pydantic Parameter
+    required: bool = False
+    schema_: JsonSchema = Field(..., alias="schema")  # Target name in IR
+    description: str | None = None
+    explode: bool | None = None  # OpenAPI explode property for array parameters
+    style: str | None = None  # OpenAPI style property for parameter serialization
+
+
+class RequestBodyInfo(FastMCPBaseModel):
+    """Represents the request body for an HTTP operation in our IR."""
+
+    required: bool = False
+    content_schema: dict[str, JsonSchema] = Field(
+        default_factory=dict
+    )  # Key: media type
+    description: str | None = None
+
+
+class ResponseInfo(FastMCPBaseModel):
+    """Represents response information in our IR."""
+
+    description: str | None = None
+    # Store schema per media type, key is media type
+    content_schema: dict[str, JsonSchema] = Field(default_factory=dict)
+
+
+class HTTPRoute(FastMCPBaseModel):
+    """Intermediate Representation for a single OpenAPI operation."""
+
+    path: str
+    method: HttpMethod
+    operation_id: str | None = None
+    summary: str | None = None
+    description: str | None = None
+    tags: list[str] = Field(default_factory=list)
+    parameters: list[ParameterInfo] = Field(default_factory=list)
+    request_body: RequestBodyInfo | None = None
+    responses: dict[str, ResponseInfo] = Field(
+        default_factory=dict
+    )  # Key: status code str
+    request_schemas: dict[str, JsonSchema] = Field(
+        default_factory=dict
+    )  # Store schemas needed for input (parameters/request body)
+    response_schemas: dict[str, JsonSchema] = Field(
+        default_factory=dict
+    )  # Store schemas needed for output (responses)
+    extensions: dict[str, Any] = Field(default_factory=dict)
+    openapi_version: str | None = None
+
+    # Pre-calculated fields for performance
+    flat_param_schema: JsonSchema = Field(
+        default_factory=dict
+    )  # Combined schema for MCP tools
+    parameter_map: dict[str, dict[str, str]] = Field(
+        default_factory=dict
+    )  # Maps flat args to locations
+
+
+# Export public symbols
+__all__ = [
+    "HTTPRoute",
+    "HttpMethod",
+    "JsonSchema",
+    "ParameterInfo",
+    "ParameterLocation",
+    "RequestBodyInfo",
+    "ResponseInfo",
+]
diff --git a/fastmcp_slim/fastmcp/utilities/openapi/parser.py b/fastmcp_slim/fastmcp/utilities/openapi/parser.py
new file mode 100644
index 0000000..f83a452
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/openapi/parser.py
@@ -0,0 +1,825 @@
+"""OpenAPI parsing logic for converting OpenAPI specs to HTTPRoute objects."""
+
+from typing import Any, Generic, TypeVar, cast
+
+from openapi_pydantic import (
+    OpenAPI,
+    Operation,
+    Parameter,
+    PathItem,
+    Reference,
+    RequestBody,
+    Response,
+    Schema,
+)
+
+# Import OpenAPI 3.0 models as well
+from openapi_pydantic.v3.v3_0 import OpenAPI as OpenAPI_30
+from openapi_pydantic.v3.v3_0 import Operation as Operation_30
+from openapi_pydantic.v3.v3_0 import Parameter as Parameter_30
+from openapi_pydantic.v3.v3_0 import PathItem as PathItem_30
+from openapi_pydantic.v3.v3_0 import Reference as Reference_30
+from openapi_pydantic.v3.v3_0 import RequestBody as RequestBody_30
+from openapi_pydantic.v3.v3_0 import Response as Response_30
+from openapi_pydantic.v3.v3_0 import Schema as Schema_30
+from pydantic import BaseModel, ValidationError
+
+from fastmcp.utilities.logging import get_logger
+
+from .models import (
+    HTTPRoute,
+    JsonSchema,
+    ParameterInfo,
+    ParameterLocation,
+    RequestBodyInfo,
+    ResponseInfo,
+)
+from .schemas import (
+    _combine_schemas_and_map_params,
+    _replace_ref_with_defs,
+)
+
+logger = get_logger(__name__)
+
+# Type variables for generic parser
+TOpenAPI = TypeVar("TOpenAPI", OpenAPI, OpenAPI_30)
+TSchema = TypeVar("TSchema", Schema, Schema_30)
+TReference = TypeVar("TReference", Reference, Reference_30)
+TParameter = TypeVar("TParameter", Parameter, Parameter_30)
+TRequestBody = TypeVar("TRequestBody", RequestBody, RequestBody_30)
+TResponse = TypeVar("TResponse", Response, Response_30)
+TOperation = TypeVar("TOperation", Operation, Operation_30)
+TPathItem = TypeVar("TPathItem", PathItem, PathItem_30)
+
+
+def parse_openapi_to_http_routes(openapi_dict: dict[str, Any]) -> list[HTTPRoute]:
+    """
+    Parses an OpenAPI schema dictionary into a list of HTTPRoute objects
+    using the openapi-pydantic library.
+
+    Supports both OpenAPI 3.0.x and 3.1.x versions.
+    """
+    # Check OpenAPI version to use appropriate model
+    openapi_version = openapi_dict.get("openapi", "")
+
+    try:
+        if openapi_version.startswith("3.0"):
+            # Use OpenAPI 3.0 models
+            openapi_30 = OpenAPI_30.model_validate(openapi_dict)
+            logger.debug(
+                f"Successfully parsed OpenAPI 3.0 schema version: {openapi_30.openapi}"
+            )
+            parser = OpenAPIParser(
+                openapi_30,
+                Reference_30,
+                Schema_30,
+                Parameter_30,
+                RequestBody_30,
+                Response_30,
+                Operation_30,
+                PathItem_30,
+                openapi_version,
+            )
+            return parser.parse()
+        else:
+            # Default to OpenAPI 3.1 models
+            openapi_31 = OpenAPI.model_validate(openapi_dict)
+            logger.debug(
+                f"Successfully parsed OpenAPI 3.1 schema version: {openapi_31.openapi}"
+            )
+            parser = OpenAPIParser(
+                openapi_31,
+                Reference,
+                Schema,
+                Parameter,
+                RequestBody,
+                Response,
+                Operation,
+                PathItem,
+                openapi_version,
+            )
+            return parser.parse()
+    except ValidationError as e:
+        logger.error(f"OpenAPI schema validation failed: {e}")
+        error_details = e.errors()
+        logger.error(f"Validation errors: {error_details}")
+        raise ValueError(f"Invalid OpenAPI schema: {error_details}") from e
+
+
+class OpenAPIParser(
+    Generic[
+        TOpenAPI,
+        TReference,
+        TSchema,
+        TParameter,
+        TRequestBody,
+        TResponse,
+        TOperation,
+        TPathItem,
+    ]
+):
+    """Unified parser for OpenAPI schemas with generic type parameters to handle both 3.0 and 3.1."""
+
+    def __init__(
+        self,
+        openapi: TOpenAPI,
+        reference_cls: type[TReference],
+        schema_cls: type[TSchema],
+        parameter_cls: type[TParameter],
+        request_body_cls: type[TRequestBody],
+        response_cls: type[TResponse],
+        operation_cls: type[TOperation],
+        path_item_cls: type[TPathItem],
+        openapi_version: str,
+    ):
+        """Initialize the parser with the OpenAPI schema and type classes."""
+        self.openapi = openapi
+        self.reference_cls = reference_cls
+        self.schema_cls = schema_cls
+        self.parameter_cls = parameter_cls
+        self.request_body_cls = request_body_cls
+        self.response_cls = response_cls
+        self.operation_cls = operation_cls
+        self.path_item_cls = path_item_cls
+        self.openapi_version = openapi_version
+
+    def _convert_to_parameter_location(self, param_in: str) -> ParameterLocation:
+        """Convert string parameter location to our ParameterLocation type."""
+        if param_in in ["path", "query", "header", "cookie"]:
+            return cast(ParameterLocation, param_in)
+        logger.warning(f"Unknown parameter location: {param_in}, defaulting to 'query'")
+        return cast(ParameterLocation, "query")
+
+    def _resolve_ref(self, item: Any) -> Any:
+        """Resolves a reference to its target definition."""
+        if isinstance(item, self.reference_cls):
+            ref_str = item.ref
+            # Ensure ref_str is a string before calling startswith()
+            if not isinstance(ref_str, str):
+                return item
+            try:
+                if not ref_str.startswith("#/"):
+                    raise ValueError(
+                        f"External or non-local reference not supported: {ref_str}"
+                    )
+
+                parts = ref_str.strip("#/").split("/")
+                target = self.openapi
+
+                for part in parts:
+                    if part.isdigit() and isinstance(target, list):
+                        target = target[int(part)]
+                    elif isinstance(target, BaseModel):
+                        # Check class fields first, then model_extra
+                        if part in target.__class__.model_fields:
+                            target = getattr(target, part, None)
+                        elif target.model_extra and part in target.model_extra:
+                            target = target.model_extra[part]
+                        else:
+                            # Special handling for components
+                            if part == "components" and hasattr(target, "components"):
+                                target = target.components
+                            elif hasattr(target, part):  # Fallback check
+                                target = getattr(target, part, None)
+                            else:
+                                target = None  # Part not found
+                    elif isinstance(target, dict):
+                        target = target.get(part)
+                    else:
+                        raise ValueError(
+                            f"Cannot traverse part '{part}' in reference '{ref_str}'"
+                        )
+
+                    if target is None:
+                        raise ValueError(
+                            f"Reference part '{part}' not found in path '{ref_str}'"
+                        )
+
+                # Handle nested references
+                if isinstance(target, self.reference_cls):
+                    return self._resolve_ref(target)
+
+                return target
+            except (AttributeError, KeyError, IndexError, TypeError, ValueError) as e:
+                raise ValueError(f"Failed to resolve reference '{ref_str}': {e}") from e
+
+        return item
+
+    def _extract_schema_as_dict(self, schema_obj: Any) -> JsonSchema:
+        """Resolves a schema and returns it as a dictionary."""
+        try:
+            resolved_schema = self._resolve_ref(schema_obj)
+
+            if isinstance(resolved_schema, self.schema_cls):
+                # Convert schema to dictionary
+                result = resolved_schema.model_dump(
+                    mode="json", by_alias=True, exclude_none=True
+                )
+            elif isinstance(resolved_schema, dict):
+                result = resolved_schema
+            else:
+                logger.warning(
+                    f"Expected Schema after resolving, got {type(resolved_schema)}. Returning empty dict."
+                )
+                result = {}
+
+            # Convert refs from OpenAPI format to JSON Schema format using recursive approach
+
+            result = _replace_ref_with_defs(result)
+            return result
+        except ValueError as e:
+            # Re-raise ValueError for external reference errors and other validation issues
+            if "External or non-local reference not supported" in str(e):
+                raise
+            logger.error(f"Failed to extract schema as dict: {e}", exc_info=False)
+            return {}
+        except Exception as e:
+            logger.error(f"Failed to extract schema as dict: {e}", exc_info=False)
+            return {}
+
+    def _extract_parameters(
+        self,
+        operation_params: list[Any] | None = None,
+        path_item_params: list[Any] | None = None,
+    ) -> list[ParameterInfo]:
+        """Extract and resolve parameters from operation and path item."""
+        extracted_params: list[ParameterInfo] = []
+        seen_params: dict[
+            tuple[str, str], bool
+        ] = {}  # Use tuple of (name, location) as key
+        all_params = (operation_params or []) + (path_item_params or [])
+
+        for param_or_ref in all_params:
+            try:
+                parameter = self._resolve_ref(param_or_ref)
+
+                if not isinstance(parameter, self.parameter_cls):
+                    logger.warning(
+                        f"Expected Parameter after resolving, got {type(parameter)}. Skipping."
+                    )
+                    continue
+
+                # Extract parameter info - handle both 3.0 and 3.1 parameter models
+                param_in = parameter.param_in  # Both use param_in
+                # Handle enum or string parameter locations
+                from enum import Enum
+
+                param_in_str = (
+                    param_in.value if isinstance(param_in, Enum) else param_in
+                )
+                param_location = self._convert_to_parameter_location(param_in_str)
+                param_schema_obj = parameter.param_schema  # Both use param_schema
+
+                # Skip duplicate parameters (same name and location)
+                param_key = (parameter.name, param_in_str)
+                if param_key in seen_params:
+                    continue
+                seen_params[param_key] = True
+
+                # Extract schema
+                param_schema_dict = {}
+                if param_schema_obj:
+                    # Process schema object
+                    param_schema_dict = self._extract_schema_as_dict(param_schema_obj)
+
+                    # Handle default value
+                    resolved_schema = self._resolve_ref(param_schema_obj)
+                    if (
+                        not isinstance(resolved_schema, self.reference_cls)
+                        and hasattr(resolved_schema, "default")
+                        and resolved_schema.default is not None
+                    ):
+                        param_schema_dict["default"] = resolved_schema.default
+
+                elif hasattr(parameter, "content") and parameter.content:
+                    # Handle content-based parameters
+                    first_media_type = next(iter(parameter.content.values()), None)
+                    if (
+                        first_media_type
+                        and hasattr(first_media_type, "media_type_schema")
+                        and first_media_type.media_type_schema
+                    ):
+                        media_schema = first_media_type.media_type_schema
+                        param_schema_dict = self._extract_schema_as_dict(media_schema)
+
+                        # Handle default value in content schema
+                        resolved_media_schema = self._resolve_ref(media_schema)
+                        if (
+                            not isinstance(resolved_media_schema, self.reference_cls)
+                            and hasattr(resolved_media_schema, "default")
+                            and resolved_media_schema.default is not None
+                        ):
+                            param_schema_dict["default"] = resolved_media_schema.default
+
+                # Extract explode and style properties if present
+                explode = getattr(parameter, "explode", None)
+                style = getattr(parameter, "style", None)
+
+                # Create parameter info object
+                param_info = ParameterInfo(
+                    name=parameter.name,
+                    location=param_location,
+                    required=parameter.required,
+                    schema=param_schema_dict,
+                    description=parameter.description,
+                    explode=explode,
+                    style=style,
+                )
+                extracted_params.append(param_info)
+            except Exception as e:
+                param_name = getattr(
+                    param_or_ref, "name", getattr(param_or_ref, "ref", "unknown")
+                )
+                logger.error(
+                    f"Failed to extract parameter '{param_name}': {e}", exc_info=False
+                )
+
+        return extracted_params
+
+    def _extract_request_body(self, request_body_or_ref: Any) -> RequestBodyInfo | None:
+        """Extract and resolve request body information."""
+        if not request_body_or_ref:
+            return None
+
+        try:
+            request_body = self._resolve_ref(request_body_or_ref)
+
+            if not isinstance(request_body, self.request_body_cls):
+                logger.warning(
+                    f"Expected RequestBody after resolving, got {type(request_body)}. Returning None."
+                )
+                return None
+
+            # Create request body info
+            request_body_info = RequestBodyInfo(
+                required=request_body.required,
+                description=request_body.description,
+            )
+
+            # Extract content schemas
+            if hasattr(request_body, "content") and request_body.content:
+                for media_type_str, media_type_obj in request_body.content.items():
+                    if (
+                        media_type_obj
+                        and hasattr(media_type_obj, "media_type_schema")
+                        and media_type_obj.media_type_schema
+                    ):
+                        try:
+                            schema_dict = self._extract_schema_as_dict(
+                                media_type_obj.media_type_schema
+                            )
+                            request_body_info.content_schema[media_type_str] = (
+                                schema_dict
+                            )
+                        except ValueError as e:
+                            # Re-raise ValueError for external reference errors
+                            if "External or non-local reference not supported" in str(
+                                e
+                            ):
+                                raise
+                            logger.error(
+                                f"Failed to extract schema for media type '{media_type_str}': {e}"
+                            )
+                        except Exception as e:
+                            logger.error(
+                                f"Failed to extract schema for media type '{media_type_str}': {e}"
+                            )
+
+            return request_body_info
+        except ValueError as e:
+            # Re-raise ValueError for external reference errors
+            if "External or non-local reference not supported" in str(e):
+                raise
+            ref_name = getattr(request_body_or_ref, "ref", "unknown")
+            logger.error(
+                f"Failed to extract request body '{ref_name}': {e}", exc_info=False
+            )
+            return None
+        except Exception as e:
+            ref_name = getattr(request_body_or_ref, "ref", "unknown")
+            logger.error(
+                f"Failed to extract request body '{ref_name}': {e}", exc_info=False
+            )
+            return None
+
+    def _is_success_status_code(self, status_code: str) -> bool:
+        """Check if a status code represents a successful response (2xx)."""
+        try:
+            code_int = int(status_code)
+            return 200 <= code_int < 300
+        except (ValueError, TypeError):
+            # Handle special cases like 'default' or other non-numeric codes
+            return status_code.lower() in ["default", "2xx"]
+
+    def _get_primary_success_response(
+        self, operation_responses: dict[str, Any]
+    ) -> tuple[str, Any] | None:
+        """Get the primary success response for an MCP tool. We only need one success response."""
+        if not operation_responses:
+            return None
+
+        # Priority order: 200, 201, 202, 204, 207, then any other 2xx
+        priority_codes = ["200", "201", "202", "204", "207"]
+
+        # First check priority codes
+        for code in priority_codes:
+            if code in operation_responses:
+                return (code, operation_responses[code])
+
+        # Then check any other 2xx codes
+        for status_code, resp_or_ref in operation_responses.items():
+            if self._is_success_status_code(status_code):
+                return (status_code, resp_or_ref)
+
+        # If no success codes found, return None (tool will have no output schema)
+        return None
+
+    def _extract_responses(
+        self, operation_responses: dict[str, Any] | None
+    ) -> dict[str, ResponseInfo]:
+        """Extract and resolve response information. Only includes the primary success response for MCP tools."""
+        extracted_responses: dict[str, ResponseInfo] = {}
+
+        if not operation_responses:
+            return extracted_responses
+
+        # For MCP tools, we only need the primary success response
+        primary_response = self._get_primary_success_response(operation_responses)
+        if not primary_response:
+            logger.debug("No success responses found, tool will have no output schema")
+            return extracted_responses
+
+        status_code, resp_or_ref = primary_response
+        logger.debug(f"Using primary success response: {status_code}")
+
+        try:
+            response = self._resolve_ref(resp_or_ref)
+
+            if not isinstance(response, self.response_cls):
+                logger.warning(
+                    f"Expected Response after resolving for status code {status_code}, "
+                    f"got {type(response)}. Returning empty responses."
+                )
+                return extracted_responses
+
+            # Create response info
+            resp_info = ResponseInfo(description=response.description)
+
+            # Extract content schemas
+            if hasattr(response, "content") and response.content:
+                for media_type_str, media_type_obj in response.content.items():
+                    if (
+                        media_type_obj
+                        and hasattr(media_type_obj, "media_type_schema")
+                        and media_type_obj.media_type_schema
+                    ):
+                        try:
+                            # Track if this is a top-level $ref before resolution
+                            top_level_schema_name = None
+                            media_schema = media_type_obj.media_type_schema
+                            if isinstance(media_schema, self.reference_cls):
+                                ref_str = media_schema.ref
+                                if isinstance(ref_str, str) and ref_str.startswith(
+                                    "#/components/schemas/"
+                                ):
+                                    top_level_schema_name = ref_str.split("/")[-1]
+
+                            schema_dict = self._extract_schema_as_dict(media_schema)
+                            # Add marker for top-level schema if it was a ref
+                            if top_level_schema_name:
+                                schema_dict["x-fastmcp-top-level-schema"] = (
+                                    top_level_schema_name
+                                )
+                            resp_info.content_schema[media_type_str] = schema_dict
+                        except ValueError as e:
+                            # Re-raise ValueError for external reference errors
+                            if "External or non-local reference not supported" in str(
+                                e
+                            ):
+                                raise
+                            logger.error(
+                                f"Failed to extract schema for media type '{media_type_str}' "
+                                f"in response {status_code}: {e}"
+                            )
+                        except Exception as e:
+                            logger.error(
+                                f"Failed to extract schema for media type '{media_type_str}' "
+                                f"in response {status_code}: {e}"
+                            )
+                    else:
+                        # Record the media type even without a schema so MIME
+                        # type inference can still use the declared content type.
+                        resp_info.content_schema.setdefault(media_type_str, {})
+
+            extracted_responses[str(status_code)] = resp_info
+        except ValueError as e:
+            # Re-raise ValueError for external reference errors
+            if "External or non-local reference not supported" in str(e):
+                raise
+            ref_name = getattr(resp_or_ref, "ref", "unknown")
+            logger.error(
+                f"Failed to extract response for status code {status_code} "
+                f"from reference '{ref_name}': {e}",
+                exc_info=False,
+            )
+        except Exception as e:
+            ref_name = getattr(resp_or_ref, "ref", "unknown")
+            logger.error(
+                f"Failed to extract response for status code {status_code} "
+                f"from reference '{ref_name}': {e}",
+                exc_info=False,
+            )
+
+        return extracted_responses
+
+    def _extract_schema_dependencies(
+        self,
+        schema: dict,
+        all_schemas: dict[str, Any],
+        collected: set[str] | None = None,
+    ) -> set[str]:
+        """
+        Extract all schema names referenced by a schema (including transitive dependencies).
+
+        Args:
+            schema: The schema to analyze
+            all_schemas: All available schema definitions
+            collected: Set of already collected schema names (for recursion)
+
+        Returns:
+            Set of schema names that are referenced
+        """
+        if collected is None:
+            collected = set()
+
+        def find_refs(obj):
+            """Recursively find all $ref references."""
+            if isinstance(obj, dict):
+                if "$ref" in obj and isinstance(obj["$ref"], str):
+                    ref = obj["$ref"]
+                    # Handle both converted and unconverted refs
+                    if ref.startswith(("#/$defs/", "#/components/schemas/")):
+                        schema_name = ref.split("/")[-1]
+                    else:
+                        return
+
+                    # Add this schema and recursively find its dependencies
+                    if (
+                        collected is not None
+                        and schema_name not in collected
+                        and schema_name in all_schemas
+                    ):
+                        collected.add(schema_name)
+                        # Recursively find dependencies of this schema
+                        find_refs(all_schemas[schema_name])
+
+                # Continue searching in all values
+                for value in obj.values():
+                    find_refs(value)
+            elif isinstance(obj, list):
+                for item in obj:
+                    find_refs(item)
+
+        find_refs(schema)
+        return collected
+
+    def _extract_input_schema_dependencies(
+        self,
+        parameters: list[ParameterInfo],
+        request_body: RequestBodyInfo | None,
+        all_schemas: dict[str, Any],
+    ) -> dict[str, Any]:
+        """
+        Extract only the schema definitions needed for input (parameters and request body).
+
+        Args:
+            parameters: Route parameters
+            request_body: Route request body
+            all_schemas: All available schema definitions
+
+        Returns:
+            Dictionary containing only the schemas needed for input
+        """
+        needed_schemas = set()
+
+        # Check parameters for schema references
+        for param in parameters:
+            if param.schema_:
+                deps = self._extract_schema_dependencies(param.schema_, all_schemas)
+                needed_schemas.update(deps)
+
+        # Check request body for schema references
+        if request_body and request_body.content_schema:
+            for content_schema in request_body.content_schema.values():
+                deps = self._extract_schema_dependencies(content_schema, all_schemas)
+                needed_schemas.update(deps)
+
+        # Return only the needed input schemas
+        return {
+            name: all_schemas[name] for name in needed_schemas if name in all_schemas
+        }
+
+    def _extract_output_schema_dependencies(
+        self,
+        responses: dict[str, ResponseInfo],
+        all_schemas: dict[str, Any],
+    ) -> dict[str, Any]:
+        """
+        Extract only the schema definitions needed for outputs (responses).
+
+        Args:
+            responses: Route responses
+            all_schemas: All available schema definitions
+
+        Returns:
+            Dictionary containing only the schemas needed for outputs
+        """
+        if not responses or not all_schemas:
+            return {}
+
+        needed_schemas: set[str] = set()
+
+        for response in responses.values():
+            if not response.content_schema:
+                continue
+
+            for content_schema in response.content_schema.values():
+                deps = self._extract_schema_dependencies(content_schema, all_schemas)
+                needed_schemas.update(deps)
+
+                schema_name = content_schema.get("x-fastmcp-top-level-schema")
+                if isinstance(schema_name, str) and schema_name in all_schemas:
+                    needed_schemas.add(schema_name)
+                    self._extract_schema_dependencies(
+                        all_schemas[schema_name],
+                        all_schemas,
+                        collected=needed_schemas,
+                    )
+
+        return {
+            name: all_schemas[name] for name in needed_schemas if name in all_schemas
+        }
+
+    def parse(self) -> list[HTTPRoute]:
+        """Parse the OpenAPI schema into HTTP routes."""
+        routes: list[HTTPRoute] = []
+
+        if not hasattr(self.openapi, "paths") or not self.openapi.paths:
+            logger.warning("OpenAPI schema has no paths defined.")
+            return []
+
+        # Extract component schemas
+        schema_definitions = {}
+        if hasattr(self.openapi, "components") and self.openapi.components:
+            components = self.openapi.components
+            if hasattr(components, "schemas") and components.schemas:
+                for name, schema in components.schemas.items():
+                    try:
+                        if isinstance(schema, self.reference_cls):
+                            resolved_schema = self._resolve_ref(schema)
+                            schema_definitions[name] = self._extract_schema_as_dict(
+                                resolved_schema
+                            )
+                        else:
+                            schema_definitions[name] = self._extract_schema_as_dict(
+                                schema
+                            )
+                    except Exception as e:
+                        logger.warning(
+                            f"Failed to extract schema definition '{name}': {e}"
+                        )
+
+        # Convert schema definitions refs from OpenAPI to JSON Schema format (once)
+        if schema_definitions:
+            # Convert each schema definition recursively
+            for name, schema in schema_definitions.items():
+                if isinstance(schema, dict):
+                    schema_definitions[name] = _replace_ref_with_defs(schema)
+
+        # Process paths and operations
+        for path_str, path_item_obj in self.openapi.paths.items():
+            if not isinstance(path_item_obj, self.path_item_cls):
+                logger.warning(
+                    f"Skipping invalid path item for path '{path_str}' (type: {type(path_item_obj)})"
+                )
+                continue
+
+            path_level_params = (
+                path_item_obj.parameters
+                if hasattr(path_item_obj, "parameters")
+                else None
+            )
+
+            # Get HTTP methods from the path item class fields
+            http_methods = [
+                "get",
+                "put",
+                "post",
+                "delete",
+                "options",
+                "head",
+                "patch",
+                "trace",
+            ]
+            for method_lower in http_methods:
+                operation = getattr(path_item_obj, method_lower, None)
+
+                if operation and isinstance(operation, self.operation_cls):
+                    # Cast method to HttpMethod - safe since we only use valid HTTP methods
+                    method_upper = method_lower.upper()
+
+                    try:
+                        parameters = self._extract_parameters(
+                            getattr(operation, "parameters", None), path_level_params
+                        )
+
+                        request_body_info = self._extract_request_body(
+                            getattr(operation, "requestBody", None)
+                        )
+
+                        responses = self._extract_responses(
+                            getattr(operation, "responses", None)
+                        )
+
+                        extensions = {}
+                        if hasattr(operation, "model_extra") and operation.model_extra:
+                            extensions = {
+                                k: v
+                                for k, v in operation.model_extra.items()
+                                if k.startswith("x-")
+                            }
+
+                        # Extract schemas separately for input and output
+                        input_schemas = self._extract_input_schema_dependencies(
+                            parameters,
+                            request_body_info,
+                            schema_definitions,
+                        )
+                        output_schemas = self._extract_output_schema_dependencies(
+                            responses,
+                            schema_definitions,
+                        )
+
+                        # Create initial route without pre-calculated fields
+                        route = HTTPRoute(
+                            path=path_str,
+                            method=method_upper,  # type: ignore[arg-type]  # Known valid HTTP method  # ty:ignore[invalid-argument-type]
+                            operation_id=getattr(operation, "operationId", None),
+                            summary=getattr(operation, "summary", None),
+                            description=getattr(operation, "description", None),
+                            tags=getattr(operation, "tags", []) or [],
+                            parameters=parameters,
+                            request_body=request_body_info,
+                            responses=responses,
+                            request_schemas=input_schemas,
+                            response_schemas=output_schemas,
+                            extensions=extensions,
+                            openapi_version=self.openapi_version,
+                        )
+
+                        # Pre-calculate schema and parameter mapping for performance
+                        try:
+                            flat_schema, param_map = _combine_schemas_and_map_params(
+                                route,
+                                convert_refs=False,  # Parser already converted refs
+                            )
+                            route.flat_param_schema = flat_schema
+                            route.parameter_map = param_map
+                        except Exception as schema_error:
+                            logger.warning(
+                                f"Failed to pre-calculate schema for route {method_upper} {path_str}: {schema_error}"
+                            )
+                            # Continue with empty pre-calculated fields
+                            route.flat_param_schema = {
+                                "type": "object",
+                                "properties": {},
+                            }
+                            route.parameter_map = {}
+                        routes.append(route)
+                    except ValueError as op_error:
+                        # Re-raise ValueError for external reference errors
+                        if "External or non-local reference not supported" in str(
+                            op_error
+                        ):
+                            raise
+                        op_id = getattr(operation, "operationId", "unknown")
+                        logger.error(
+                            f"Failed to process operation {method_upper} {path_str} (ID: {op_id}): {op_error}",
+                            exc_info=True,
+                        )
+                    except Exception as op_error:
+                        op_id = getattr(operation, "operationId", "unknown")
+                        logger.error(
+                            f"Failed to process operation {method_upper} {path_str} (ID: {op_id}): {op_error}",
+                            exc_info=True,
+                        )
+
+        logger.debug(f"Finished parsing. Extracted {len(routes)} HTTP routes.")
+        return routes
+
+
+# Export public symbols
+__all__ = [
+    "OpenAPIParser",
+    "parse_openapi_to_http_routes",
+]
diff --git a/fastmcp_slim/fastmcp/utilities/openapi/schemas.py b/fastmcp_slim/fastmcp/utilities/openapi/schemas.py
new file mode 100644
index 0000000..5980621
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/openapi/schemas.py
@@ -0,0 +1,612 @@
+"""Schema manipulation utilities for OpenAPI operations."""
+
+from collections import Counter
+from typing import Any
+
+from fastmcp.utilities.logging import get_logger
+
+from .json_schema_converter import convert_openapi_schema_to_json_schema
+from .models import HTTPRoute, JsonSchema, ResponseInfo
+
+logger = get_logger(__name__)
+
+
+def clean_schema_for_display(schema: JsonSchema | None) -> JsonSchema | None:
+    """
+    Clean up a schema dictionary for display by removing internal/complex fields.
+    """
+    if not schema or not isinstance(schema, dict):
+        return schema
+
+    # Make a copy to avoid modifying the input schema
+    cleaned = schema.copy()
+
+    # Fields commonly removed for simpler display to LLMs or users
+    fields_to_remove = [
+        "allOf",
+        "anyOf",
+        "oneOf",
+        "not",  # Composition keywords
+        "nullable",  # Handled by type unions usually
+        "discriminator",
+        "readOnly",
+        "writeOnly",
+        "deprecated",
+        "xml",
+        "externalDocs",
+        # Can be verbose, maybe remove based on flag?
+        # "pattern", "minLength", "maxLength",
+        # "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum",
+        # "multipleOf", "minItems", "maxItems", "uniqueItems",
+        # "minProperties", "maxProperties"
+    ]
+
+    for field in fields_to_remove:
+        if field in cleaned:
+            cleaned.pop(field)
+
+    # Recursively clean properties and items
+    if "properties" in cleaned:
+        cleaned["properties"] = {
+            k: clean_schema_for_display(v) for k, v in cleaned["properties"].items()
+        }
+        # Remove properties section if empty after cleaning
+        if not cleaned["properties"]:
+            cleaned.pop("properties")
+
+    if "items" in cleaned:
+        cleaned["items"] = clean_schema_for_display(cleaned["items"])
+        # Remove items section if empty after cleaning
+        if not cleaned["items"]:
+            cleaned.pop("items")
+
+    if "additionalProperties" in cleaned:
+        # Often verbose, can be simplified
+        if isinstance(cleaned["additionalProperties"], dict):
+            cleaned["additionalProperties"] = clean_schema_for_display(
+                cleaned["additionalProperties"]
+            )
+        elif cleaned["additionalProperties"] is True:
+            # Maybe keep 'true' or represent as 'Allows additional properties' text?
+            pass  # Keep simple boolean for now
+
+    return cleaned
+
+
+def _replace_ref_with_defs(
+    info: dict[str, Any], description: str | None = None
+) -> dict[str, Any]:
+    """
+    Replace openapi $ref with jsonschema $defs recursively.
+
+    Examples:
+    - {"type": "object", "properties": {"$ref": "#/components/schemas/..."}}
+    - {"type": "object", "additionalProperties": {"$ref": "#/components/schemas/..."}, "properties": {...}}
+    - {"$ref": "#/components/schemas/..."}
+    - {"items": {"$ref": "#/components/schemas/..."}}
+    - {"anyOf": [{"$ref": "#/components/schemas/..."}]}
+    - {"allOf": [{"$ref": "#/components/schemas/..."}]}
+    - {"oneOf": [{"$ref": "#/components/schemas/..."}]}
+
+    Args:
+        info: dict[str, Any]
+        description: str | None
+
+    Returns:
+        dict[str, Any]
+    """
+    schema = info.copy()
+    if ref_path := schema.get("$ref"):
+        if isinstance(ref_path, str):
+            if ref_path.startswith("#/components/schemas/"):
+                schema_name = ref_path.split("/")[-1]
+                schema["$ref"] = f"#/$defs/{schema_name}"
+            elif not ref_path.startswith("#/"):
+                raise ValueError(
+                    f"External or non-local reference not supported: {ref_path}. "
+                    f"FastMCP only supports local schema references starting with '#/'. "
+                    f"Please include all schema definitions within the OpenAPI document."
+                )
+    elif properties := schema.get("properties"):
+        if "$ref" in properties:
+            schema["properties"] = _replace_ref_with_defs(properties)
+        else:
+            schema["properties"] = {
+                prop_name: _replace_ref_with_defs(prop_schema)
+                for prop_name, prop_schema in properties.items()
+            }
+    elif item_schema := schema.get("items"):
+        schema["items"] = _replace_ref_with_defs(item_schema)
+    for section in ["anyOf", "allOf", "oneOf"]:
+        if section in schema:
+            schema[section] = [_replace_ref_with_defs(item) for item in schema[section]]
+    if additionalProperties := schema.get("additionalProperties"):
+        if not isinstance(additionalProperties, bool):
+            schema["additionalProperties"] = _replace_ref_with_defs(
+                additionalProperties
+            )
+    # Handle propertyNames
+    if property_names := schema.get("propertyNames"):
+        if isinstance(property_names, dict):
+            schema["propertyNames"] = _replace_ref_with_defs(property_names)
+    # Handle patternProperties
+    if pattern_properties := schema.get("patternProperties"):
+        if isinstance(pattern_properties, dict):
+            schema["patternProperties"] = {
+                pattern: _replace_ref_with_defs(subschema)
+                if isinstance(subschema, dict)
+                else subschema
+                for pattern, subschema in pattern_properties.items()
+            }
+    if info.get("description", description) and not schema.get("description"):
+        schema["description"] = description
+    return schema
+
+
+def _make_optional_parameter_nullable(schema: dict[str, Any]) -> dict[str, Any]:
+    """
+    Make an optional parameter schema nullable to allow None values.
+
+    For optional parameters, we need to allow null values in addition to the
+    specified type to handle cases where None is passed for optional parameters.
+    """
+    # If schema already has multiple types or is already nullable, don't modify
+    if "anyOf" in schema or "oneOf" in schema or "allOf" in schema:
+        return schema
+
+    # If it's already nullable (type includes null), don't modify
+    if isinstance(schema.get("type"), list) and "null" in schema["type"]:
+        return schema
+
+    # Create a new schema that allows null in addition to the original type
+    if "type" in schema:
+        original_type = schema["type"]
+        if isinstance(original_type, str):
+            # Handle different types appropriately
+            if original_type in ("array", "object"):
+                # For complex types (array/object), preserve the full structure
+                # and allow null as an alternative
+                if original_type == "array" and "items" in schema:
+                    # Array with items - preserve items in anyOf branch
+                    array_schema = schema.copy()
+                    top_level_fields = ["default", "description", "title", "example"]
+                    nullable_schema = {}
+
+                    # Move top-level fields to the root
+                    for field in top_level_fields:
+                        if field in array_schema:
+                            nullable_schema[field] = array_schema.pop(field)
+
+                    nullable_schema["anyOf"] = [array_schema, {"type": "null"}]
+                    return nullable_schema
+
+                elif original_type == "object" and "properties" in schema:
+                    # Object with properties - preserve properties in anyOf branch
+                    object_schema = schema.copy()
+                    top_level_fields = ["default", "description", "title", "example"]
+                    nullable_schema = {}
+
+                    # Move top-level fields to the root
+                    for field in top_level_fields:
+                        if field in object_schema:
+                            nullable_schema[field] = object_schema.pop(field)
+
+                    nullable_schema["anyOf"] = [object_schema, {"type": "null"}]
+                    return nullable_schema
+                else:
+                    # Simple object/array without items/properties
+                    nullable_schema = {}
+                    original_schema = schema.copy()
+                    top_level_fields = ["default", "description", "title", "example"]
+
+                    for field in top_level_fields:
+                        if field in original_schema:
+                            nullable_schema[field] = original_schema.pop(field)
+
+                    nullable_schema["anyOf"] = [original_schema, {"type": "null"}]
+                    return nullable_schema
+            else:
+                # Simple types (string, integer, number, boolean)
+                top_level_fields = ["default", "description", "title", "example"]
+                nullable_schema = {}
+                original_schema = schema.copy()
+
+                for field in top_level_fields:
+                    if field in original_schema:
+                        nullable_schema[field] = original_schema.pop(field)
+
+                nullable_schema["anyOf"] = [original_schema, {"type": "null"}]
+                return nullable_schema
+
+    return schema
+
+
+def _combine_schemas_and_map_params(
+    route: HTTPRoute,
+    convert_refs: bool = True,
+) -> tuple[dict[str, Any], dict[str, dict[str, str]]]:
+    """
+    Combines parameter and request body schemas into a single schema.
+    Handles parameter name collisions by adding location suffixes.
+    Also returns parameter mapping for request director.
+
+    Args:
+        route: HTTPRoute object
+
+    Returns:
+        Tuple of (combined schema dictionary, parameter mapping)
+        Parameter mapping format: {'flat_arg_name': {'location': 'path', 'openapi_name': 'id'}}
+    """
+    properties = {}
+    required = []
+    parameter_map = {}  # Track mapping from flat arg names to OpenAPI locations
+
+    # First pass: collect parameter names by location and body properties
+    param_names_by_location = {
+        "path": set(),
+        "query": set(),
+        "header": set(),
+        "cookie": set(),
+    }
+    body_schema: dict[str, Any] = {}
+    body_props: dict[str, Any] = {}
+
+    for param in route.parameters:
+        param_names_by_location[param.location].add(param.name)
+
+    if route.request_body and route.request_body.content_schema:
+        content_type = next(iter(route.request_body.content_schema))
+
+        # Convert refs if needed
+        if convert_refs:
+            body_schema = _replace_ref_with_defs(
+                route.request_body.content_schema[content_type]
+            )
+        else:
+            body_schema = route.request_body.content_schema[content_type]
+
+        if route.request_body.description and not body_schema.get("description"):
+            body_schema["description"] = route.request_body.description
+
+        # Handle allOf at the top level by merging all schemas
+        if "allOf" in body_schema and isinstance(body_schema["allOf"], list):
+            merged_props = {}
+            merged_required = []
+
+            for sub_schema in body_schema["allOf"]:
+                if isinstance(sub_schema, dict):
+                    # Merge properties
+                    if "properties" in sub_schema:
+                        merged_props.update(sub_schema["properties"])
+                    # Merge required fields
+                    if "required" in sub_schema:
+                        merged_required.extend(sub_schema["required"])
+
+            # Update body_schema with merged properties
+            body_schema["properties"] = merged_props
+            if merged_required:
+                # Remove duplicates while preserving order
+                seen = set()
+                body_schema["required"] = [
+                    x for x in merged_required if not (x in seen or seen.add(x))
+                ]
+            # Remove the allOf since we've merged it
+            body_schema.pop("allOf", None)
+
+        body_props = body_schema.get("properties", {})
+
+    # Detect collisions: parameters that exist in multiple non-body locations
+    # or between body and path/query/header/cookie.
+    all_non_body_params = set()
+    for location_params in param_names_by_location.values():
+        all_non_body_params.update(location_params)
+
+    body_param_names = set(body_props.keys())
+    non_body_param_counts = Counter(param.name for param in route.parameters)
+    colliding_params = (all_non_body_params & body_param_names) | {
+        name for name, count in non_body_param_counts.items() if count > 1
+    }
+
+    # Add parameters with suffixes for collisions
+    for param in route.parameters:
+        if param.name in colliding_params:
+            # Add suffix for non-body parameters when collision detected
+            suffixed_name = f"{param.name}__{param.location}"
+            if param.required:
+                required.append(suffixed_name)
+
+            # Track parameter mapping
+            parameter_map[suffixed_name] = {
+                "location": param.location,
+                "openapi_name": param.name,
+            }
+
+            # Convert refs if needed
+            if convert_refs:
+                param_schema = _replace_ref_with_defs(param.schema_, param.description)
+            else:
+                param_schema = param.schema_.copy()
+                if param.description and not param_schema.get("description"):
+                    param_schema["description"] = param.description
+            original_desc = param_schema.get("description", "")
+            location_desc = f"({param.location.capitalize()} parameter)"
+            if original_desc:
+                param_schema["description"] = f"{original_desc} {location_desc}"
+            else:
+                param_schema["description"] = location_desc
+
+            # Don't make optional parameters nullable - they can simply be omitted
+            # The OpenAPI specification doesn't require optional parameters to accept null values
+
+            properties[suffixed_name] = param_schema
+        else:
+            # No collision, use original name
+            if param.required:
+                required.append(param.name)
+
+            # Track parameter mapping
+            parameter_map[param.name] = {
+                "location": param.location,
+                "openapi_name": param.name,
+            }
+
+            # Convert refs if needed
+            if convert_refs:
+                param_schema = _replace_ref_with_defs(param.schema_, param.description)
+            else:
+                param_schema = param.schema_.copy()
+                if param.description and not param_schema.get("description"):
+                    param_schema["description"] = param.description
+
+            # Don't make optional parameters nullable - they can simply be omitted
+            # The OpenAPI specification doesn't require optional parameters to accept null values
+
+            properties[param.name] = param_schema
+
+    # Add request body properties (no suffixes for body parameters)
+    if route.request_body and route.request_body.content_schema:
+        # If body is just a $ref, we need to handle it differently
+        if "$ref" in body_schema and not body_props:
+            # The entire body is a reference to a schema
+            # We need to expand this inline or keep the ref
+            # For simplicity, we'll keep it as a single property
+            properties["body"] = body_schema
+            if route.request_body.required:
+                required.append("body")
+            parameter_map["body"] = {"location": "body", "openapi_name": "body"}
+        elif body_props:
+            # Normal case: body has properties
+            for prop_name, prop_schema in body_props.items():
+                properties[prop_name] = prop_schema
+
+                # Track parameter mapping for body properties
+                parameter_map[prop_name] = {
+                    "location": "body",
+                    "openapi_name": prop_name,
+                }
+
+            if route.request_body.required:
+                required.extend(body_schema.get("required", []))
+        else:
+            # Handle direct array/primitive schemas (like list[str] parameters from FastAPI)
+            # Use the schema title as parameter name, fall back to generic name
+            param_name = body_schema.get("title", "body").lower()
+
+            # Clean the parameter name to be valid
+            import re
+
+            param_name = re.sub(r"[^a-zA-Z0-9_]", "_", param_name)
+            if not param_name or param_name[0].isdigit():
+                param_name = "body_data"
+
+            properties[param_name] = body_schema
+            if route.request_body.required:
+                required.append(param_name)
+            parameter_map[param_name] = {"location": "body", "openapi_name": param_name}
+
+    result = {
+        "type": "object",
+        "properties": properties,
+        "required": required,
+    }
+    # Add schema definitions if available
+    schema_defs = route.request_schemas
+    if schema_defs:
+        if convert_refs:
+            # Need to convert refs and prune
+            all_defs = schema_defs.copy()
+            # Convert each schema definition recursively
+            for name, schema in all_defs.items():
+                if isinstance(schema, dict):
+                    all_defs[name] = _replace_ref_with_defs(schema)
+
+            # Prune to only needed schemas
+            used_refs = set()
+
+            def find_refs_in_value(value):
+                """Recursively find all $ref references."""
+                if isinstance(value, dict):
+                    if "$ref" in value and isinstance(value["$ref"], str):
+                        ref = value["$ref"]
+                        if ref.startswith("#/$defs/"):
+                            used_refs.add(ref.split("/")[-1])
+                    for v in value.values():
+                        find_refs_in_value(v)
+                elif isinstance(value, list):
+                    for item in value:
+                        find_refs_in_value(item)
+
+            # Find refs in properties
+            find_refs_in_value(properties)
+
+            # Collect transitive dependencies
+            if used_refs:
+                collected_all = False
+                while not collected_all:
+                    initial_count = len(used_refs)
+                    for name in list(used_refs):
+                        if name in all_defs:
+                            find_refs_in_value(all_defs[name])
+                    collected_all = len(used_refs) == initial_count
+
+                result["$defs"] = {
+                    name: def_schema
+                    for name, def_schema in all_defs.items()
+                    if name in used_refs
+                }
+        else:
+            # From parser - already converted and pruned
+            result["$defs"] = schema_defs
+
+    if route.openapi_version and route.openapi_version.startswith("3"):
+        result = convert_openapi_schema_to_json_schema(result, route.openapi_version)
+
+    return result, parameter_map
+
+
+def _combine_schemas(route: HTTPRoute) -> dict[str, Any]:
+    """
+    Combines parameter and request body schemas into a single schema.
+    Handles parameter name collisions by adding location suffixes.
+
+    This is a backward compatibility wrapper around _combine_schemas_and_map_params.
+
+    Args:
+        route: HTTPRoute object
+
+    Returns:
+        Combined schema dictionary
+    """
+    schema, _ = _combine_schemas_and_map_params(route)
+    return schema
+
+
+def extract_output_schema_from_responses(
+    responses: dict[str, ResponseInfo],
+    schema_definitions: dict[str, Any] | None = None,
+    openapi_version: str | None = None,
+) -> dict[str, Any] | None:
+    """
+    Extract output schema from OpenAPI responses for use as MCP tool output schema.
+
+    This function finds the first successful response (200, 201, 202, 204) with a
+    JSON-compatible content type and extracts its schema. If the schema is not an
+    object type, it wraps it to comply with MCP requirements.
+
+    Args:
+        responses: Dictionary of ResponseInfo objects keyed by status code
+        schema_definitions: Optional schema definitions to include in the output schema
+        openapi_version: OpenAPI version string, used to optimize nullable field handling
+
+    Returns:
+        dict: MCP-compliant output schema with potential wrapping, or None if no suitable schema found
+    """
+    if not responses:
+        return None
+
+    # Priority order for success status codes
+    success_codes = ["200", "201", "202", "204"]
+
+    # Find the first successful response
+    response_info = None
+    for status_code in success_codes:
+        if status_code in responses:
+            response_info = responses[status_code]
+            break
+
+    # If no explicit success codes, try any 2xx response
+    if response_info is None:
+        for status_code, resp_info in responses.items():
+            if status_code.startswith("2"):
+                response_info = resp_info
+                break
+
+    if response_info is None or not response_info.content_schema:
+        return None
+
+    # Prefer application/json, then fall back to other JSON-compatible types
+    json_compatible_types = [
+        "application/json",
+        "application/vnd.api+json",
+        "application/hal+json",
+        "application/ld+json",
+        "text/json",
+    ]
+
+    schema = None
+    for content_type in json_compatible_types:
+        if content_type in response_info.content_schema:
+            schema = response_info.content_schema[content_type]
+            break
+
+    # If no JSON-compatible type found, try the first available content type
+    if schema is None and response_info.content_schema:
+        first_content_type = next(iter(response_info.content_schema))
+        schema = response_info.content_schema[first_content_type]
+        logger.debug(
+            f"Using non-JSON content type for output schema: {first_content_type}"
+        )
+
+    if not schema or not isinstance(schema, dict):
+        return None
+
+    # Convert refs if needed
+    output_schema = _replace_ref_with_defs(schema)
+
+    # If schema has a $ref, resolve it first before processing nullable fields
+    if "$ref" in output_schema and schema_definitions:
+        ref_path = output_schema["$ref"]
+        if ref_path.startswith("#/$defs/"):
+            schema_name = ref_path.split("/")[-1]
+            if schema_name in schema_definitions:
+                # Replace $ref with the actual schema definition
+                output_schema = _replace_ref_with_defs(schema_definitions[schema_name])
+
+    if openapi_version and openapi_version.startswith("3"):
+        # Convert OpenAPI 3.x schema to JSON Schema format for proper handling
+        # of constructs like oneOf, anyOf, and nullable fields
+        output_schema = convert_openapi_schema_to_json_schema(
+            output_schema, openapi_version
+        )
+
+    # MCP requires output schemas to be objects. If this schema is not an object,
+    # we need to wrap it similar to how ParsedFunction.from_function() does it
+    if output_schema.get("type") != "object":
+        # Create a wrapped schema that contains the original schema under a "result" key
+        wrapped_schema = {
+            "type": "object",
+            "properties": {"result": output_schema},
+            "required": ["result"],
+            "x-fastmcp-wrap-result": True,
+        }
+        output_schema = wrapped_schema
+
+    # Add schema definitions if available
+    if schema_definitions:
+        # Convert refs if needed
+        processed_defs = schema_definitions.copy()
+        # Convert each schema definition recursively
+        for name, schema in processed_defs.items():
+            if isinstance(schema, dict):
+                processed_defs[name] = _replace_ref_with_defs(schema)
+
+        # Convert OpenAPI schema definitions to JSON Schema format if needed
+        if openapi_version and openapi_version.startswith("3"):
+            for def_name in list(processed_defs.keys()):
+                processed_defs[def_name] = convert_openapi_schema_to_json_schema(
+                    processed_defs[def_name], openapi_version
+                )
+
+        output_schema["$defs"] = processed_defs
+
+    return output_schema
+
+
+# Export public symbols
+__all__ = [
+    "_combine_schemas",
+    "_combine_schemas_and_map_params",
+    "_make_optional_parameter_nullable",
+    "clean_schema_for_display",
+    "extract_output_schema_from_responses",
+]
diff --git a/fastmcp_slim/fastmcp/utilities/pagination.py b/fastmcp_slim/fastmcp/utilities/pagination.py
new file mode 100644
index 0000000..48e2e45
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/pagination.py
@@ -0,0 +1,80 @@
+"""Pagination utilities for MCP list operations."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass
+class CursorState:
+    """Internal representation of pagination cursor state.
+
+    The cursor encodes the offset into the result set. This is opaque to clients
+    per the MCP spec - they should not parse or modify cursors.
+    """
+
+    offset: int
+
+    def encode(self) -> str:
+        """Encode cursor state to an opaque string."""
+        data = json.dumps({"o": self.offset})
+        return base64.urlsafe_b64encode(data.encode()).decode()
+
+    @classmethod
+    def decode(cls, cursor: str) -> CursorState:
+        """Decode cursor from an opaque string.
+
+        Raises:
+            ValueError: If the cursor is invalid or malformed.
+        """
+        try:
+            data = json.loads(base64.urlsafe_b64decode(cursor.encode()).decode())
+            return cls(offset=data["o"])
+        except (
+            json.JSONDecodeError,
+            KeyError,
+            ValueError,
+            TypeError,
+            binascii.Error,
+        ) as e:
+            raise ValueError(f"Invalid cursor: {cursor}") from e
+
+
+def paginate_sequence(
+    items: Sequence[T],
+    cursor: str | None,
+    page_size: int,
+) -> tuple[list[T], str | None]:
+    """Paginate a sequence of items.
+
+    Args:
+        items: The full sequence to paginate.
+        cursor: Optional cursor from a previous request. None for first page.
+        page_size: Maximum number of items per page.
+
+    Returns:
+        Tuple of (page_items, next_cursor). next_cursor is None if no more pages.
+
+    Raises:
+        ValueError: If the cursor is invalid.
+    """
+    offset = 0
+    if cursor:
+        state = CursorState.decode(cursor)
+        offset = state.offset
+
+    end = offset + page_size
+    page = list(items[offset:end])
+
+    next_cursor = None
+    if end < len(items):
+        next_cursor = CursorState(offset=end).encode()
+
+    return page, next_cursor
diff --git a/fastmcp_slim/fastmcp/utilities/skills.py b/fastmcp_slim/fastmcp/utilities/skills.py
new file mode 100644
index 0000000..2c93b1f
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/skills.py
@@ -0,0 +1,257 @@
+"""Client utilities for discovering and downloading skills from MCP servers."""
+
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import mcp_types
+
+if TYPE_CHECKING:
+    from fastmcp.client import Client
+
+
+@dataclass
+class SkillSummary:
+    """Summary information about a skill available on a server."""
+
+    name: str
+    description: str
+    uri: str
+
+
+@dataclass
+class SkillFile:
+    """Information about a file within a skill."""
+
+    path: str
+    size: int
+    hash: str
+
+
+@dataclass
+class SkillManifest:
+    """Full manifest of a skill including all files."""
+
+    name: str
+    files: list[SkillFile]
+
+
+async def list_skills(client: Client) -> list[SkillSummary]:
+    """List all available skills from an MCP server.
+
+    Discovers skills by finding resources with URIs matching the
+    `skill://{name}/SKILL.md` pattern.
+
+    Args:
+        client: Connected FastMCP client
+
+    Returns:
+        List of SkillSummary objects with name, description, and URI
+
+    Example:
+        ```python
+        from fastmcp import Client
+        from fastmcp.utilities.skills import list_skills
+
+        async with Client("http://skills-server/mcp") as client:
+            skills = await list_skills(client)
+            for skill in skills:
+                print(f"{skill.name}: {skill.description}")
+        ```
+    """
+    resources = await client.list_resources()
+    skills = []
+
+    for resource in resources:
+        uri = str(resource.uri)
+        # Match skill://{name}/SKILL.md pattern
+        if uri.startswith("skill://") and uri.endswith("/SKILL.md"):
+            # Extract skill name from URI
+            path_part = uri[len("skill://") :]
+            name = path_part.rsplit("/", 1)[0]
+            skills.append(
+                SkillSummary(
+                    name=name,
+                    description=resource.description or "",
+                    uri=uri,
+                )
+            )
+
+    return skills
+
+
+async def get_skill_manifest(client: Client, skill_name: str) -> SkillManifest:
+    """Get the manifest for a specific skill.
+
+    Args:
+        client: Connected FastMCP client
+        skill_name: Name of the skill
+
+    Returns:
+        SkillManifest with file listing
+
+    Raises:
+        ValueError: If manifest cannot be read or parsed
+    """
+    manifest_uri = f"skill://{skill_name}/_manifest"
+    result = await client.read_resource(manifest_uri)
+
+    if not result:
+        raise ValueError(f"Could not read manifest for skill: {skill_name}")
+
+    content = result[0]
+    if isinstance(content, mcp_types.TextResourceContents):
+        try:
+            manifest_data = json.loads(content.text)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid manifest JSON for skill: {skill_name}") from e
+    else:
+        raise ValueError(f"Unexpected manifest format for skill: {skill_name}")
+
+    try:
+        return SkillManifest(
+            name=manifest_data["skill"],
+            files=[
+                SkillFile(path=f["path"], size=f["size"], hash=f["hash"])
+                for f in manifest_data["files"]
+            ],
+        )
+    except (KeyError, TypeError) as e:
+        raise ValueError(f"Invalid manifest format for skill: {skill_name}") from e
+
+
+async def download_skill(
+    client: Client,
+    skill_name: str,
+    target_dir: str | Path,
+    *,
+    overwrite: bool = False,
+) -> Path:
+    """Download a skill and all its files to a local directory.
+
+    Creates a subdirectory named after the skill containing all files.
+
+    Args:
+        client: Connected FastMCP client
+        skill_name: Name of the skill to download
+        target_dir: Directory where skill folder will be created
+        overwrite: If True, overwrite existing skill directory. If False
+            (default), raise FileExistsError if directory exists.
+
+    Returns:
+        Path to the downloaded skill directory
+
+    Raises:
+        ValueError: If skill cannot be found or downloaded
+        FileExistsError: If skill directory exists and overwrite=False
+
+    Example:
+        ```python
+        from fastmcp import Client
+        from fastmcp.utilities.skills import download_skill
+
+        async with Client("http://skills-server/mcp") as client:
+            skill_path = await download_skill(
+                client,
+                "pdf-processing",
+                "~/.claude/skills"
+            )
+            print(f"Downloaded to: {skill_path}")
+        ```
+    """
+    target_dir = Path(target_dir).expanduser().resolve()
+    skill_dir = (target_dir / skill_name).resolve()
+
+    # Security: ensure skill_dir stays within target_dir
+    if not skill_dir.is_relative_to(target_dir):
+        raise ValueError(f"Skill name {skill_name!r} would escape the target directory")
+
+    # Check if directory exists
+    if skill_dir.exists() and not overwrite:
+        raise FileExistsError(
+            f"Skill directory already exists: {skill_dir}. "
+            "Use overwrite=True to replace."
+        )
+
+    # Get manifest to know what files to download
+    manifest = await get_skill_manifest(client, skill_name)
+
+    # Create skill directory
+    skill_dir.mkdir(parents=True, exist_ok=True)
+
+    # Download each file
+    for file_info in manifest.files:
+        # Security: reject absolute paths and paths that escape skill_dir
+        if Path(file_info.path).is_absolute():
+            continue
+        file_path = (skill_dir / file_info.path).resolve()
+        if not file_path.is_relative_to(skill_dir):
+            continue
+
+        file_uri = f"skill://{skill_name}/{file_info.path}"
+        result = await client.read_resource(file_uri)
+
+        if not result:
+            continue
+
+        content = result[0]
+
+        # Create parent directories if needed
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write content
+        if isinstance(content, mcp_types.TextResourceContents):
+            file_path.write_text(content.text)
+        elif isinstance(content, mcp_types.BlobResourceContents):
+            file_path.write_bytes(base64.b64decode(content.blob))
+        else:
+            # Skip unknown content types
+            continue
+
+    return skill_dir
+
+
+async def sync_skills(
+    client: Client,
+    target_dir: str | Path,
+    *,
+    overwrite: bool = False,
+) -> list[Path]:
+    """Download all available skills from a server.
+
+    Args:
+        client: Connected FastMCP client
+        target_dir: Directory where skill folders will be created
+        overwrite: If True, overwrite existing files
+
+    Returns:
+        List of paths to downloaded skill directories
+
+    Example:
+        ```python
+        from fastmcp import Client
+        from fastmcp.utilities.skills import sync_skills
+
+        async with Client("http://skills-server/mcp") as client:
+            paths = await sync_skills(client, "~/.claude/skills")
+            print(f"Downloaded {len(paths)} skills")
+        ```
+    """
+    skills = await list_skills(client)
+    downloaded = []
+
+    for skill in skills:
+        try:
+            path = await download_skill(
+                client, skill.name, target_dir, overwrite=overwrite
+            )
+            downloaded.append(path)
+        except FileExistsError:
+            # Skip existing skills when not overwriting
+            continue
+
+    return downloaded
diff --git a/fastmcp_slim/fastmcp/utilities/tasks.py b/fastmcp_slim/fastmcp/utilities/tasks.py
new file mode 100644
index 0000000..0886dac
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/tasks.py
@@ -0,0 +1,80 @@
+"""Task configuration primitives for FastMCP components."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import Any, Literal
+
+from fastmcp.utilities.async_utils import is_coroutine_function
+
+TaskMode = Literal["forbidden", "optional", "required"]
+
+DEFAULT_POLL_INTERVAL = timedelta(seconds=5)
+DEFAULT_POLL_INTERVAL_MS = int(DEFAULT_POLL_INTERVAL.total_seconds() * 1000)
+DEFAULT_TTL_MS = 60_000
+
+
+@dataclass
+class TaskMeta:
+    """Metadata for task-augmented execution requests.
+
+    Attributes:
+        ttl: Client-requested TTL in milliseconds. If None, uses server default.
+        fn_key: Docket routing key. Auto-derived from component name if None.
+    """
+
+    ttl: int | None = None
+    fn_key: str | None = None
+
+
+@dataclass
+class TaskConfig:
+    """Configuration for MCP background task execution.
+
+    Controls how a component handles task-augmented requests:
+
+    - ``forbidden``: Component does not support task execution.
+    - ``optional``: Component supports both synchronous and task execution.
+    - ``required``: Component requires task execution.
+    """
+
+    mode: TaskMode = "optional"
+    poll_interval: timedelta = DEFAULT_POLL_INTERVAL
+
+    @classmethod
+    def from_bool(cls, value: bool) -> TaskConfig:
+        """Convert a boolean task flag to a TaskConfig."""
+        return cls(mode="optional" if value else "forbidden")
+
+    def supports_tasks(self) -> bool:
+        """Check if this component supports task execution."""
+        return self.mode != "forbidden"
+
+    def validate_function(self, fn: Callable[..., Any], name: str) -> None:
+        """Validate that a function is compatible with this task config."""
+        if not self.supports_tasks():
+            return
+
+        from fastmcp.server.dependencies import require_docket
+
+        require_docket(f"`task=True` on function '{name}'")
+
+        fn_to_check = fn
+        if (
+            not inspect.isroutine(fn)
+            and not isinstance(fn, functools.partial)
+            and callable(fn)
+        ):
+            fn_to_check = fn.__call__
+        if isinstance(fn_to_check, staticmethod):
+            fn_to_check = fn_to_check.__func__
+
+        if not is_coroutine_function(fn_to_check):
+            raise ValueError(
+                f"'{name}' uses a sync function but has task execution enabled. "
+                "Background tasks require async functions."
+            )
diff --git a/fastmcp_slim/fastmcp/utilities/tests.py b/fastmcp_slim/fastmcp/utilities/tests.py
new file mode 100644
index 0000000..0ca29c1
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/tests.py
@@ -0,0 +1,275 @@
+from __future__ import annotations
+
+import copy
+import multiprocessing
+import socket
+import time
+from collections.abc import AsyncGenerator, Callable, Generator
+from contextlib import asynccontextmanager, contextmanager, suppress
+from typing import TYPE_CHECKING, Any, Literal
+from urllib.parse import parse_qs, urlparse
+
+import httpx
+import uvicorn
+from mcp.shared.auth import AuthorizationCodeResult
+
+from fastmcp import settings
+from fastmcp.client.auth.oauth import OAuth
+from fastmcp.utilities.http import find_available_port
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP
+
+
+@contextmanager
+def temporary_settings(**kwargs: Any):
+    """
+    Temporarily override FastMCP setting values.
+
+    Args:
+        **kwargs: The settings to override, including nested settings.
+
+    Example:
+        Temporarily override a setting:
+        ```python
+        import fastmcp
+        from fastmcp.utilities.tests import temporary_settings
+
+        with temporary_settings(log_level='DEBUG'):
+            assert fastmcp.settings.log_level == 'DEBUG'
+        assert fastmcp.settings.log_level == 'INFO'
+        ```
+    """
+    old_settings = copy.deepcopy(settings)
+
+    try:
+        # apply the new settings
+        for attr, value in kwargs.items():
+            settings.set_setting(attr, value)
+        yield
+
+    finally:
+        # restore the old settings
+        for attr in kwargs:
+            settings.set_setting(attr, old_settings.get_setting(attr))
+
+
+def _run_server(mcp_server: FastMCP, transport: Literal["sse"], port: int) -> None:
+    # Some Starlette apps are not pickleable, so we need to create them here based on the indicated transport
+    if transport == "sse":
+        app = mcp_server.http_app(transport="sse")
+    else:
+        raise ValueError(f"Invalid transport: {transport}")
+    uvicorn_server = uvicorn.Server(
+        config=uvicorn.Config(
+            app=app,
+            host="127.0.0.1",
+            port=port,
+            log_level="error",
+            ws="websockets-sansio",
+        )
+    )
+    uvicorn_server.run()
+
+
+@contextmanager
+def run_server_in_process(
+    server_fn: Callable[..., None],
+    *args: Any,
+    provide_host_and_port: bool = True,
+    host: str = "127.0.0.1",
+    port: int | None = None,
+    **kwargs: Any,
+) -> Generator[str, None, None]:
+    """
+    Context manager that runs a FastMCP server in a separate process and
+    returns the server URL. When the context manager is exited, the server process is killed.
+
+    Args:
+        server_fn: The function that runs a FastMCP server. FastMCP servers are
+            not pickleable, so we need a function that creates and runs one.
+        *args: Arguments to pass to the server function.
+        provide_host_and_port: Whether to provide the host and port to the server function as kwargs.
+        host: Host to bind the server to (default: "127.0.0.1").
+        port: Port to bind the server to (default: find available port).
+        **kwargs: Keyword arguments to pass to the server function.
+
+    Returns:
+        The server URL.
+    """
+    # Use provided port or find an available one
+    if port is None:
+        port = find_available_port()
+
+    if provide_host_and_port:
+        kwargs |= {"host": host, "port": port}
+
+    proc = multiprocessing.Process(
+        target=server_fn, args=args, kwargs=kwargs, daemon=True
+    )
+    proc.start()
+
+    # Wait for server to be running
+    max_attempts = 30
+    attempt = 0
+    while attempt < max_attempts and proc.is_alive():
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.connect((host, port))
+                break
+        except ConnectionRefusedError:
+            if attempt < 5:
+                time.sleep(0.05)
+            elif attempt < 15:
+                time.sleep(0.1)
+            else:
+                time.sleep(0.2)
+            attempt += 1
+    else:
+        raise RuntimeError(f"Server failed to start after {max_attempts} attempts")
+
+    yield f"http://{host}:{port}"
+
+    proc.terminate()
+    proc.join(timeout=5)
+    if proc.is_alive():
+        # If it's still alive, then force kill it
+        proc.kill()
+        proc.join(timeout=2)
+        if proc.is_alive():
+            raise RuntimeError("Server process failed to terminate even after kill")
+
+
+@asynccontextmanager
+async def run_server_async(
+    server: FastMCP,
+    port: int | None = None,
+    transport: Literal["http", "streamable-http", "sse"] = "http",
+    path: str = "/mcp",
+    host: str = "127.0.0.1",
+) -> AsyncGenerator[str, None]:
+    """
+    Start a FastMCP server as an asyncio task for in-process async testing.
+
+    This is the recommended way to test FastMCP servers. It runs the server
+    as an async task in the same process, eliminating subprocess coordination,
+    sleeps, and cleanup issues.
+
+    Args:
+        server: FastMCP server instance
+        port: Port to bind to (default: find available port)
+        transport: Transport type ("http", "streamable-http", or "sse")
+        path: URL path for the server (default: "/mcp")
+        host: Host to bind to (default: "127.0.0.1")
+
+    Yields:
+        Server URL string
+
+    Example:
+        ```python
+        import pytest
+        from fastmcp import FastMCP, Client
+        from fastmcp.client.transports import StreamableHttpTransport
+        from fastmcp.utilities.tests import run_server_async
+
+        @pytest.fixture
+        async def server():
+            mcp = FastMCP("test")
+
+            @mcp.tool()
+            def greet(name: str) -> str:
+                return f"Hello, {name}!"
+
+            async with run_server_async(mcp) as url:
+                yield url
+
+        async def test_greet(server: str):
+            async with Client(StreamableHttpTransport(server)) as client:
+                result = await client.call_tool("greet", {"name": "World"})
+                assert result.content[0].text == "Hello, World!"
+        ```
+    """
+    import asyncio
+
+    if port is None:
+        port = find_available_port()
+
+    # Wait a tiny bit for the port to be released if it was just used
+    await asyncio.sleep(0.01)
+
+    # Start server as a background task
+    server_task = asyncio.create_task(
+        server.run_http_async(
+            host=host,
+            port=port,
+            transport=transport,
+            path=path,
+            show_banner=False,
+        )
+    )
+
+    # Wait for server lifespan to be ready
+    await server._started.wait()
+
+    # Give uvicorn a moment to bind the port after lifespan is ready
+    await asyncio.sleep(0.1)
+
+    try:
+        yield f"http://{host}:{port}{path}"
+    finally:
+        # Cleanup: cancel the task with timeout to avoid hanging on Windows
+        server_task.cancel()
+        with suppress(asyncio.CancelledError, asyncio.TimeoutError):
+            await asyncio.wait_for(server_task, timeout=2.0)
+
+
+class HeadlessOAuth(OAuth):
+    """
+    OAuth provider that bypasses browser interaction for testing.
+
+    This simulates the complete OAuth flow programmatically by making HTTP requests
+    instead of opening a browser and running a callback server. Useful for automated testing.
+    """
+
+    def __init__(self, mcp_url: str, **kwargs):
+        """Initialize HeadlessOAuth with stored response tracking."""
+        self._stored_response = None
+        super().__init__(mcp_url, **kwargs)
+
+    async def redirect_handler(self, authorization_url: str) -> None:
+        """Make HTTP request to authorization URL and store response for callback handler."""
+        async with httpx.AsyncClient() as client:
+            response = await client.get(authorization_url, follow_redirects=False)
+            self._stored_response = response
+
+    async def callback_handler(self) -> AuthorizationCodeResult:
+        """Parse stored response and return the authorization code result."""
+        if not self._stored_response:
+            raise RuntimeError(
+                "No authorization response stored. redirect_handler must be called first."
+            )
+
+        response = self._stored_response
+
+        # Extract auth code from redirect location
+        if response.status_code == 302:
+            redirect_url = response.headers["location"]
+            parsed = urlparse(redirect_url)
+            # keep_blank_values=True so explicitly-empty params (e.g. ?state=)
+            # survive parsing instead of being silently dropped. Real OAuth
+            # callbacks can include empty `state` or `error_description`,
+            # and downstream code distinguishes "" from missing.
+            query_params = parse_qs(parsed.query, keep_blank_values=True)
+
+            if "error" in query_params:
+                error = query_params["error"][0]
+                error_desc = query_params.get("error_description", ["Unknown error"])[0]
+                raise RuntimeError(
+                    f"OAuth authorization failed: {error} - {error_desc}"
+                )
+
+            auth_code = query_params["code"][0]
+            state = query_params.get("state", [None])[0]
+            return AuthorizationCodeResult(code=auth_code, state=state)
+        else:
+            raise RuntimeError(f"Authorization failed: {response.status_code}")
diff --git a/fastmcp_slim/fastmcp/utilities/timeout.py b/fastmcp_slim/fastmcp/utilities/timeout.py
new file mode 100644
index 0000000..b129978
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/timeout.py
@@ -0,0 +1,47 @@
+"""Timeout normalization utilities."""
+
+from __future__ import annotations
+
+import datetime
+
+
+def normalize_timeout_to_timedelta(
+    value: int | float | datetime.timedelta | None,
+) -> datetime.timedelta | None:
+    """Normalize a timeout value to a timedelta.
+
+    Args:
+        value: Timeout value as int/float (seconds), timedelta, or None
+
+    Returns:
+        timedelta if value provided, None otherwise
+    """
+    if value is None:
+        return None
+    if isinstance(value, datetime.timedelta):
+        return value
+    if isinstance(value, int | float):
+        return datetime.timedelta(seconds=float(value))
+    raise TypeError(f"Invalid timeout type: {type(value)}")
+
+
+def normalize_timeout_to_seconds(
+    value: int | float | datetime.timedelta | None,
+) -> float | None:
+    """Normalize a timeout value to seconds (float).
+
+    Args:
+        value: Timeout value as int/float (seconds), timedelta, or None.
+            Zero values are treated as "disabled" and return None.
+
+    Returns:
+        float seconds if value provided and non-zero, None otherwise
+    """
+    if value is None:
+        return None
+    if isinstance(value, datetime.timedelta):
+        seconds = value.total_seconds()
+        return None if seconds == 0 else seconds
+    if isinstance(value, int | float):
+        return None if value == 0 else float(value)
+    raise TypeError(f"Invalid timeout type: {type(value)}")
diff --git a/fastmcp_slim/fastmcp/utilities/token_cache.py b/fastmcp_slim/fastmcp/utilities/token_cache.py
new file mode 100644
index 0000000..9446090
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/token_cache.py
@@ -0,0 +1,173 @@
+"""In-memory cache for token verification results.
+
+Provides a generic TTL-based cache for ``AccessToken`` objects, designed to
+reduce repeated network calls during opaque-token verification.  Only
+*successful* verifications should be cached; errors and failures must be
+retried on every request.
+
+Example:
+    ```python
+    from fastmcp.utilities.token_cache import TokenCache
+
+    cache = TokenCache(ttl_seconds=300, max_size=10000)
+
+    # On cache miss, call the upstream verifier and store the result.
+    hit, token = cache.get(raw_token)
+    if not hit:
+        token = await _call_upstream(raw_token)
+        if token is not None:
+            cache.set(raw_token, token)
+    ```
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from dataclasses import dataclass
+
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+DEFAULT_MAX_CACHE_SIZE = 10_000
+_CLEANUP_INTERVAL = 60  # seconds between periodic sweeps
+
+
+@dataclass
+class _CacheEntry:
+    """A cached token result with its absolute expiration timestamp."""
+
+    result: AccessToken
+    expires_at: float
+
+
+class TokenCache:
+    """TTL-based in-memory cache for ``AccessToken`` objects.
+
+    Features:
+    - SHA-256 hashed cache keys (fixed size, regardless of token length).
+    - Per-entry TTL that respects both the configured ``ttl_seconds`` and the
+      token's own ``expires_at`` claim (whichever is sooner).
+    - Bounded size with FIFO eviction when the cache is full.
+    - Periodic cleanup of expired entries to prevent unbounded growth.
+    - Defensive deep copies on both store and retrieve to prevent
+      callers from mutating cached values.
+
+    Caching is disabled when ``ttl_seconds`` is ``None`` or ``0``, or
+    when ``max_size`` is ``0``.  Negative values raise ``ValueError``.
+    """
+
+    def __init__(
+        self,
+        *,
+        ttl_seconds: int | None = None,
+        max_size: int | None = None,
+    ) -> None:
+        """Initialise the cache.
+
+        Args:
+            ttl_seconds: How long cached entries remain valid, in seconds.
+                ``None`` or ``0`` disables caching entirely.
+            max_size: Upper bound on the number of entries.  When the limit is
+                reached, expired entries are swept first; if still full the
+                oldest entry is evicted.  Defaults to 10 000.
+        """
+        if ttl_seconds is not None and ttl_seconds < 0:
+            raise ValueError(
+                f"cache_ttl_seconds must be non-negative, got {ttl_seconds}"
+            )
+        if max_size is not None and max_size < 0:
+            raise ValueError(f"max_cache_size must be non-negative, got {max_size}")
+        self._ttl = ttl_seconds or 0
+        self._max_size = max_size if max_size is not None else DEFAULT_MAX_CACHE_SIZE
+        self._entries: dict[str, _CacheEntry] = {}
+        self._last_cleanup = time.monotonic()
+
+    @property
+    def enabled(self) -> bool:
+        """Return whether caching is active."""
+        return self._ttl > 0 and self._max_size > 0
+
+    # -- public API ----------------------------------------------------------
+
+    def get(self, token: str) -> tuple[bool, AccessToken | None]:
+        """Look up a cached verification result.
+
+        Returns:
+            ``(True, AccessToken)`` on a cache hit, ``(False, None)`` on a miss
+            or when caching is disabled.  The returned ``AccessToken`` is a deep
+            copy that is safe to mutate.
+        """
+        if not self.enabled:
+            return (False, None)
+
+        cache_key = self._hash_token(token)
+        entry = self._entries.get(cache_key)
+
+        if entry is None:
+            return (False, None)
+
+        if entry.expires_at < time.time():
+            del self._entries[cache_key]
+            return (False, None)
+
+        return (True, entry.result.model_copy(deep=True))
+
+    def set(self, token: str, result: AccessToken) -> None:
+        """Store a *successful* verification result.
+
+        Only successful verifications should be cached.  Failures (inactive
+        tokens, missing scopes, HTTP errors, timeouts) must **not** be cached
+        so that transient problems do not produce sticky false negatives.
+        """
+        if not self.enabled:
+            return
+
+        cache_key = self._hash_token(token)
+
+        self._maybe_cleanup()
+        if cache_key not in self._entries:
+            self._enforce_size_limit()
+
+        expires_at = time.time() + self._ttl
+        if result.expires_at:
+            expires_at = min(expires_at, float(result.expires_at))
+
+        self._entries[cache_key] = _CacheEntry(
+            result=result.model_copy(deep=True),
+            expires_at=expires_at,
+        )
+
+    # -- internals -----------------------------------------------------------
+
+    @staticmethod
+    def _hash_token(token: str) -> str:
+        """Return the SHA-256 hex digest of *token*."""
+        return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+    def _cleanup_expired(self) -> None:
+        """Remove all entries whose TTL has elapsed."""
+        now = time.time()
+        expired = [k for k, v in self._entries.items() if v.expires_at < now]
+        for key in expired:
+            del self._entries[key]
+        if expired:
+            logger.debug("Cleaned up %d expired cache entries", len(expired))
+
+    def _maybe_cleanup(self) -> None:
+        """Run ``_cleanup_expired`` at most once per cleanup interval."""
+        now = time.monotonic()
+        if now - self._last_cleanup > _CLEANUP_INTERVAL:
+            self._cleanup_expired()
+            self._last_cleanup = now
+
+    def _enforce_size_limit(self) -> None:
+        """Ensure there is room for at least one new entry."""
+        if len(self._entries) < self._max_size:
+            return
+        self._cleanup_expired()
+        if len(self._entries) >= self._max_size:
+            oldest_key = next(iter(self._entries))
+            del self._entries[oldest_key]
diff --git a/fastmcp_slim/fastmcp/utilities/types.py b/fastmcp_slim/fastmcp/utilities/types.py
new file mode 100644
index 0000000..fe43c90
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/types.py
@@ -0,0 +1,505 @@
+"""Common types used across FastMCP."""
+
+import base64
+import inspect
+import mimetypes
+import os
+from collections.abc import Callable
+from functools import lru_cache
+from pathlib import Path
+from types import EllipsisType, UnionType
+from typing import (
+    Annotated,
+    Any,
+    Protocol,
+    TypeAlias,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+import mcp_types
+from mcp_types import Annotations, ContentBlock, ModelPreferences, SamplingMessage
+from pydantic import AnyUrl, BaseModel, ConfigDict, Field, TypeAdapter, UrlConstraints
+from typing_extensions import TypeVar
+
+T = TypeVar("T", default=Any)
+
+# TODO(sdkv2): the SDK's `mcp.types.AnyFunction` alias was removed with the
+# mcp.types module. FastMCP owns it now; keep the same `Callable[..., Any]`
+# meaning used by tool/prompt/resource decorators.
+AnyFunction: TypeAlias = Callable[..., Any]
+
+# sentinel values for optional arguments
+NotSet = ...
+NotSetT: TypeAlias = EllipsisType
+
+
+def get_fn_name(fn: Callable[..., Any]) -> str:
+    return fn.__name__  # ty: ignore[unresolved-attribute]
+
+
+class FastMCPBaseModel(BaseModel):
+    """Base model for FastMCP models."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+@lru_cache(maxsize=5000)
+def get_cached_typeadapter(cls: T) -> TypeAdapter[T]:
+    """
+    TypeAdapters are heavy objects, and in an application context we'd typically
+    create them once in a global scope and reuse them as often as possible.
+    However, this isn't feasible for user-generated functions. Instead, we use a
+    cache to minimize the cost of creating them as much as possible.
+    """
+    # For functions, process annotations to handle forward references and convert
+    # Annotated[Type, "string"] to Annotated[Type, Field(description="string")]
+    if inspect.isfunction(cls) or inspect.ismethod(cls):
+        if hasattr(cls, "__annotations__") and cls.__annotations__:
+            try:
+                # Resolve forward references first
+                resolved_hints = get_type_hints(cls, include_extras=True)
+            except Exception:
+                # If forward reference resolution fails, use original annotations
+                resolved_hints = cls.__annotations__
+
+            # Process annotations to convert string descriptions to Fields
+            processed_hints = {}
+
+            for name, annotation in resolved_hints.items():
+                # Check if this is Annotated[Type, "string"] and convert to Annotated[Type, Field(description="string")]
+                if (
+                    get_origin(annotation) is Annotated
+                    and len(get_args(annotation)) == 2
+                    and isinstance(get_args(annotation)[1], str)
+                ):
+                    base_type, description = get_args(annotation)
+                    processed_hints[name] = Annotated[
+                        base_type, Field(description=description)
+                    ]
+                else:
+                    processed_hints[name] = annotation
+
+            # Create new function if annotations changed
+            if processed_hints != cls.__annotations__:
+                import types
+
+                # Handle both functions and methods
+                if inspect.ismethod(cls):
+                    actual_func = cls.__func__
+                    code = actual_func.__code__  # ty: ignore[unresolved-attribute]
+                    globals_dict = actual_func.__globals__  # ty: ignore[unresolved-attribute]
+                    name = actual_func.__name__  # ty: ignore[unresolved-attribute]
+                    defaults = actual_func.__defaults__  # ty: ignore[unresolved-attribute]
+                    kwdefaults = actual_func.__kwdefaults__  # ty: ignore[unresolved-attribute]
+                    closure = actual_func.__closure__  # ty: ignore[unresolved-attribute]
+                else:
+                    code = cls.__code__
+                    globals_dict = cls.__globals__
+                    name = cls.__name__
+                    defaults = cls.__defaults__
+                    kwdefaults = cls.__kwdefaults__
+                    closure = cls.__closure__
+
+                new_func = types.FunctionType(
+                    code,
+                    globals_dict,
+                    name,
+                    defaults,
+                    closure,
+                )
+                new_func.__dict__.update(cls.__dict__)
+                new_func.__module__ = cls.__module__
+                new_func.__qualname__ = getattr(cls, "__qualname__", cls.__name__)
+                new_func.__annotations__ = processed_hints
+                new_func.__kwdefaults__ = kwdefaults
+
+                if inspect.ismethod(cls):
+                    new_method = types.MethodType(new_func, cls.__self__)
+                    return TypeAdapter(new_method)
+                else:
+                    return TypeAdapter(new_func)
+
+    return TypeAdapter(cls)
+
+
+def issubclass_safe(cls: type, base: type) -> bool:
+    """Check if cls is a subclass of base, even if cls is a type variable."""
+    try:
+        if origin := get_origin(cls):
+            return issubclass_safe(origin, base)
+        return issubclass(cls, base)
+    except TypeError:
+        return False
+
+
+def is_class_member_of_type(cls: Any, base: type) -> bool:
+    """
+    Check if cls is a member of base, even if cls is a type variable.
+
+    Base can be a type, a UnionType, or an Annotated type. Generic types are not
+    considered members (e.g. T is not a member of list[T]).
+    """
+    origin = get_origin(cls)
+    # Handle both types of unions: UnionType (from types module, used with | syntax)
+    # and typing.Union (used with Union[] syntax)
+    if origin is UnionType or origin == Union:
+        return any(is_class_member_of_type(arg, base) for arg in get_args(cls))
+    elif origin is Annotated:
+        # For Annotated[T, ...], check if T is a member of base
+        args = get_args(cls)
+        if args:
+            return is_class_member_of_type(args[0], base)
+        return False
+    else:
+        return issubclass_safe(cls, base)
+
+
+def find_kwarg_by_type(fn: Callable, kwarg_type: type) -> str | None:
+    """
+    Find the name of the kwarg that is of type kwarg_type.
+
+    Includes union types that contain the kwarg_type, as well as Annotated types.
+    """
+    if inspect.ismethod(fn) and hasattr(fn, "__func__"):
+        fn = fn.__func__
+
+    # Try to get resolved type hints
+    try:
+        # Use include_extras=True to preserve Annotated metadata
+        type_hints = get_type_hints(fn, include_extras=True)
+    except Exception:
+        # If resolution fails, use raw annotations if they exist
+        type_hints = getattr(fn, "__annotations__", {})
+
+    sig = inspect.signature(fn)
+    for name, param in sig.parameters.items():
+        # Use resolved hint if available, otherwise raw annotation
+        annotation = type_hints.get(name, param.annotation)
+        if is_class_member_of_type(annotation, kwarg_type):
+            return name
+    return None
+
+
+def create_function_without_params(
+    fn: Callable[..., Any], exclude_params: list[str]
+) -> Callable[..., Any]:
+    """
+    Create a new function with the same code but without the specified parameters in annotations.
+
+    This is used to exclude parameters from type adapter processing when they can't be serialized.
+    The excluded parameters are removed from the function's __annotations__ dictionary.
+    """
+    import types
+
+    if inspect.ismethod(fn):
+        actual_func = fn.__func__
+        code = actual_func.__code__  # ty: ignore[unresolved-attribute]
+        globals_dict = actual_func.__globals__  # ty: ignore[unresolved-attribute]
+        name = actual_func.__name__  # ty: ignore[unresolved-attribute]
+        defaults = actual_func.__defaults__  # ty: ignore[unresolved-attribute]
+        closure = actual_func.__closure__  # ty: ignore[unresolved-attribute]
+    else:
+        code = fn.__code__  # ty: ignore[unresolved-attribute]
+        globals_dict = fn.__globals__  # ty: ignore[unresolved-attribute]
+        name = fn.__name__  # ty: ignore[unresolved-attribute]
+        defaults = fn.__defaults__  # ty: ignore[unresolved-attribute]
+        closure = fn.__closure__  # ty: ignore[unresolved-attribute]
+
+    # Create a copy of annotations without the excluded parameters
+    original_annotations = getattr(fn, "__annotations__", {})
+    new_annotations = {
+        k: v for k, v in original_annotations.items() if k not in exclude_params
+    }
+
+    # Create new signature without the excluded parameters
+    sig = inspect.signature(fn)
+    new_params = [
+        param for name, param in sig.parameters.items() if name not in exclude_params
+    ]
+    new_sig = inspect.Signature(new_params, return_annotation=sig.return_annotation)
+
+    new_func = types.FunctionType(
+        code,
+        globals_dict,
+        name,
+        defaults,
+        closure,
+    )
+    new_func.__dict__.update(fn.__dict__)
+    new_func.__module__ = fn.__module__
+    new_func.__qualname__ = getattr(fn, "__qualname__", fn.__name__)  # ty: ignore[unresolved-attribute]
+    new_func.__annotations__ = new_annotations
+    new_func.__signature__ = new_sig  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+
+    if inspect.ismethod(fn):
+        return types.MethodType(new_func, fn.__self__)
+    else:
+        return new_func
+
+
+class Image:
+    """Helper class for returning images from tools."""
+
+    def __init__(
+        self,
+        path: str | Path | None = None,
+        data: bytes | None = None,
+        format: str | None = None,
+        annotations: Annotations | None = None,
+    ):
+        if path is None and data is None:
+            raise ValueError("Either path or data must be provided")
+        if path is not None and data is not None:
+            raise ValueError("Only one of path or data can be provided")
+
+        self.path = self._get_expanded_path(path)
+        self.data = data
+        self._format = format
+        self._mime_type = self._get_mime_type()
+        self.annotations = annotations
+
+    @staticmethod
+    def _get_expanded_path(path: str | Path | None) -> Path | None:
+        """Expand environment variables and user home in path."""
+        return Path(os.path.expandvars(str(path))).expanduser() if path else None
+
+    def _get_mime_type(self) -> str:
+        """Get MIME type from format or guess from file extension."""
+        if self._format:
+            return f"image/{self._format.lower()}"
+
+        if self.path:
+            # Workaround for WEBP in Py3.10
+            mimetypes.add_type("image/webp", ".webp")
+            resp = mimetypes.guess_type(self.path, strict=False)
+            if resp and resp[0] is not None:
+                return resp[0]
+            return "application/octet-stream"
+        return "image/png"  # default for raw binary data
+
+    def _get_data(self) -> str:
+        """Get raw image data as base64-encoded string."""
+        if self.path:
+            with open(self.path, "rb") as f:
+                data = base64.b64encode(f.read()).decode()
+        elif self.data is not None:
+            data = base64.b64encode(self.data).decode()
+        else:
+            raise ValueError("No image data available")
+        return data
+
+    def to_image_content(
+        self,
+        mime_type: str | None = None,
+        annotations: Annotations | None = None,
+    ) -> mcp_types.ImageContent:
+        """Convert to MCP ImageContent."""
+        data = self._get_data()
+
+        return mcp_types.ImageContent(
+            type="image",
+            data=data,
+            mime_type=mime_type or self._mime_type,
+            annotations=annotations or self.annotations,
+        )
+
+    def to_data_uri(self, mime_type: str | None = None) -> str:
+        """Get image as a data URI."""
+        data = self._get_data()
+        return f"data:{mime_type or self._mime_type};base64,{data}"
+
+
+class Audio:
+    """Helper class for returning audio from tools."""
+
+    def __init__(
+        self,
+        path: str | Path | None = None,
+        data: bytes | None = None,
+        format: str | None = None,
+        annotations: Annotations | None = None,
+    ):
+        if path is None and data is None:
+            raise ValueError("Either path or data must be provided")
+        if path is not None and data is not None:
+            raise ValueError("Only one of path or data can be provided")
+
+        self.path = Path(os.path.expandvars(str(path))).expanduser() if path else None
+        self.data = data
+        self._format = format
+        self._mime_type = self._get_mime_type()
+        self.annotations = annotations
+
+    def _get_mime_type(self) -> str:
+        """Get MIME type from format or guess from file extension."""
+        if self._format:
+            return f"audio/{self._format.lower()}"
+
+        if self.path:
+            suffix = self.path.suffix.lower()
+            return {
+                ".wav": "audio/wav",
+                ".mp3": "audio/mpeg",
+                ".ogg": "audio/ogg",
+                ".m4a": "audio/mp4",
+                ".flac": "audio/flac",
+            }.get(suffix, "application/octet-stream")
+        return "audio/wav"  # default for raw binary data
+
+    def to_audio_content(
+        self,
+        mime_type: str | None = None,
+        annotations: Annotations | None = None,
+    ) -> mcp_types.AudioContent:
+        if self.path:
+            with open(self.path, "rb") as f:
+                data = base64.b64encode(f.read()).decode()
+        elif self.data is not None:
+            data = base64.b64encode(self.data).decode()
+        else:
+            raise ValueError("No audio data available")
+
+        return mcp_types.AudioContent(
+            type="audio",
+            data=data,
+            mime_type=mime_type or self._mime_type,
+            annotations=annotations or self.annotations,
+        )
+
+
+class File:
+    """Helper class for returning file data from tools."""
+
+    def __init__(
+        self,
+        path: str | Path | None = None,
+        data: bytes | None = None,
+        format: str | None = None,
+        name: str | None = None,
+        annotations: Annotations | None = None,
+    ):
+        if path is None and data is None:
+            raise ValueError("Either path or data must be provided")
+        if path is not None and data is not None:
+            raise ValueError("Only one of path or data can be provided")
+
+        self.path = Path(os.path.expandvars(str(path))).expanduser() if path else None
+        self.data = data
+        self._format = format
+        self._mime_type = self._get_mime_type()
+        self._name = name
+        self.annotations = annotations
+
+    def _get_mime_type(self) -> str:
+        """Get MIME type from format or guess from file extension."""
+        if self._format:
+            fmt = self._format.lower()
+            # Map common text formats to text/plain
+            if fmt in {"plain", "txt", "text"}:
+                return "text/plain"
+            return f"application/{fmt}"
+
+        if self.path:
+            mime_type, _ = mimetypes.guess_type(self.path)
+            if mime_type:
+                return mime_type
+
+        return "application/octet-stream"
+
+    def to_resource_content(
+        self,
+        mime_type: str | None = None,
+        annotations: Annotations | None = None,
+    ) -> mcp_types.EmbeddedResource:
+        if self.path:
+            with open(self.path, "rb") as f:
+                raw_data = f.read()
+                uri_str = self.path.resolve().as_uri()
+        elif self.data is not None:
+            raw_data = self.data
+            if self._name:
+                uri_str = f"file:///{self._name}.{self._mime_type.split('/')[1]}"
+            else:
+                uri_str = f"file:///resource.{self._mime_type.split('/')[1]}"
+        else:
+            raise ValueError("No resource data available")
+
+        mime = mime_type or self._mime_type
+        # Validate the URI shape, then pass the string form to the SDK types
+        # (their `uri` fields are plain `str` in the v2 SDK).
+        UriType = Annotated[AnyUrl, UrlConstraints(host_required=False)]
+        uri = str(TypeAdapter(UriType).validate_python(uri_str))
+
+        if mime.startswith("text/"):
+            try:
+                text = raw_data.decode("utf-8")
+            except UnicodeDecodeError:
+                text = raw_data.decode("latin-1")
+            resource = mcp_types.TextResourceContents(
+                text=text,
+                mime_type=mime,
+                uri=uri,
+            )
+        else:
+            data = base64.b64encode(raw_data).decode()
+            resource = mcp_types.BlobResourceContents(
+                blob=data,
+                mime_type=mime,
+                uri=uri,
+            )
+
+        return mcp_types.EmbeddedResource(
+            type="resource",
+            resource=resource,
+            annotations=annotations or self.annotations,
+        )
+
+
+def replace_type(type_, type_map: dict[type, type]):
+    """
+    Given a (possibly generic, nested, or otherwise complex) type, replaces all
+    instances of keys in type_map with their corresponding values.
+
+    This is useful for transforming types when creating tools.
+
+    Args:
+        type_: The type to transform.
+        type_map: A mapping of types to replace (keys are replaced by values).
+
+    Examples:
+    ```python
+    >>> replace_type(list[int | bool], {int: str})
+    list[str | bool]
+
+    >>> replace_type(list[list[int]], {int: str})
+    list[list[str]]
+    ```
+    """
+    if type_ in type_map:
+        return type_map[type_]
+
+    origin = get_origin(type_)
+    if not origin:
+        return type_
+
+    args = get_args(type_)
+    new_args = tuple(replace_type(arg, type_map) for arg in args)
+
+    if origin is UnionType:
+        return Union[new_args]  # noqa: UP007
+    else:
+        return origin[new_args]
+
+
+class ContextSamplingFallbackProtocol(Protocol):
+    async def __call__(
+        self,
+        messages: str | list[str | SamplingMessage],
+        system_prompt: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        model_preferences: ModelPreferences | str | list[str] | None = None,
+    ) -> ContentBlock: ...
diff --git a/fastmcp_slim/fastmcp/utilities/ui.py b/fastmcp_slim/fastmcp/utilities/ui.py
new file mode 100644
index 0000000..8baacdd
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/ui.py
@@ -0,0 +1,626 @@
+"""
+Shared UI utilities for FastMCP HTML pages.
+
+This module provides reusable HTML/CSS components for OAuth callbacks,
+consent pages, and other user-facing interfaces.
+"""
+
+from __future__ import annotations
+
+import html
+
+from starlette.responses import HTMLResponse
+
+# FastMCP branding
+FASTMCP_LOGO_URL = "https://gofastmcp.com/assets/brand/blue-logo.png"
+
+# Base CSS styles shared across all FastMCP pages
+BASE_STYLES = """
+    * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+    }
+
+    body {
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+        margin: 0;
+        padding: 0;
+        min-height: 100vh;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        background: #f9fafb;
+        color: #0a0a0a;
+    }
+
+    .container {
+        background: #ffffff;
+        border: 1px solid #e5e7eb;
+        padding: 3rem 2.5rem;
+        border-radius: 1rem;
+        box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
+        text-align: center;
+        max-width: 36rem;
+        margin: 1rem;
+        width: 100%;
+    }
+
+    @media (max-width: 640px) {
+        .container {
+            padding: 2rem 1.5rem;
+            margin: 0.5rem;
+        }
+    }
+
+    .logo {
+        width: 64px;
+        height: auto;
+        margin-bottom: 1.5rem;
+        display: block;
+        margin-left: auto;
+        margin-right: auto;
+    }
+
+    h1 {
+        font-size: 1.5rem;
+        font-weight: 600;
+        margin-bottom: 1.5rem;
+        color: #111827;
+    }
+"""
+
+# Button styles
+BUTTON_STYLES = """
+    .button-group {
+        display: flex;
+        gap: 0.75rem;
+        margin-top: 1.5rem;
+        justify-content: center;
+    }
+
+    button {
+        padding: 0.75rem 2rem;
+        font-size: 0.9375rem;
+        font-weight: 500;
+        border-radius: 0.5rem;
+        border: none;
+        cursor: pointer;
+        transition: all 0.15s;
+        font-family: inherit;
+    }
+
+    button:hover {
+        transform: translateY(-1px);
+        box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+    }
+
+    .btn-approve, .btn-primary {
+        background: #10b981;
+        color: #ffffff;
+        min-width: 120px;
+    }
+
+    .btn-deny, .btn-secondary {
+        background: #6b7280;
+        color: #ffffff;
+        min-width: 120px;
+    }
+"""
+
+# Info box / message box styles
+INFO_BOX_STYLES = """
+    .info-box {
+        background: #f0f9ff;
+        border: 1px solid #bae6fd;
+        border-radius: 0.5rem;
+        padding: 1rem;
+        margin-bottom: 1.5rem;
+        text-align: left;
+        font-size: 0.9375rem;
+        line-height: 1.5;
+        color: #374151;
+    }
+
+    .info-box p {
+        margin-bottom: 0.5rem;
+    }
+
+    .info-box p:last-child {
+        margin-bottom: 0;
+    }
+
+    .info-box.centered {
+        text-align: center;
+    }
+
+    .info-box.error {
+        background: #fef2f2;
+        border-color: #fecaca;
+        color: #991b1b;
+    }
+
+    .info-box strong {
+        color: #0ea5e9;
+        font-weight: 600;
+    }
+
+    .info-box .server-name-link {
+        color: #0ea5e9;
+        text-decoration: underline;
+        font-weight: 600;
+        cursor: pointer;
+        transition: opacity 0.15s;
+    }
+
+    .info-box .server-name-link:hover {
+        opacity: 0.8;
+    }
+
+    /* Monospace info box - gray styling with code font */
+    .info-box-mono {
+        background: #f9fafb;
+        border: 1px solid #e5e7eb;
+        border-radius: 0.5rem;
+        padding: 0.875rem;
+        margin: 1.25rem 0;
+        font-size: 0.875rem;
+        color: #6b7280;
+        font-family: 'SF Mono', 'Monaco', 'Consolas', 'Courier New', monospace;
+        text-align: left;
+    }
+
+    .info-box-mono.centered {
+        text-align: center;
+    }
+
+    .info-box-mono.error {
+        background: #fef2f2;
+        border-color: #fecaca;
+        color: #991b1b;
+    }
+
+    .info-box-mono strong {
+        color: #111827;
+        font-weight: 600;
+    }
+
+    .warning-box {
+        background: #f0f9ff;
+        border: 1px solid #bae6fd;
+        border-radius: 0.5rem;
+        padding: 1rem;
+        margin-bottom: 1.5rem;
+        text-align: center;
+    }
+
+    .warning-box p {
+        margin-bottom: 0.5rem;
+        line-height: 1.5;
+        color: #6b7280;
+        font-size: 0.9375rem;
+    }
+
+    .warning-box p:last-child {
+        margin-bottom: 0;
+    }
+
+    .warning-box strong {
+        color: #0ea5e9;
+        font-weight: 600;
+    }
+
+    .warning-box a {
+        color: #0ea5e9;
+        text-decoration: underline;
+        font-weight: 600;
+    }
+
+    .warning-box a:hover {
+        color: #0284c7;
+        text-decoration: underline;
+    }
+"""
+
+# Status message styles (for success/error indicators)
+STATUS_MESSAGE_STYLES = """
+    .status-message {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        gap: 0.75rem;
+        margin-bottom: 1.5rem;
+    }
+
+    .status-icon {
+        font-size: 1.5rem;
+        line-height: 1;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: 2rem;
+        height: 2rem;
+        border-radius: 0.5rem;
+        flex-shrink: 0;
+    }
+
+    .status-icon.success {
+        background: #10b98120;
+    }
+
+    .status-icon.error {
+        background: #ef444420;
+    }
+
+    .message {
+        font-size: 1.125rem;
+        line-height: 1.75;
+        color: #111827;
+        font-weight: 600;
+        text-align: left;
+    }
+"""
+
+# Detail box styles (for key-value pairs)
+DETAIL_BOX_STYLES = """
+    .detail-box {
+        background: #f9fafb;
+        border: 1px solid #e5e7eb;
+        border-radius: 0.5rem;
+        padding: 1rem;
+        margin-bottom: 1.5rem;
+        text-align: left;
+    }
+
+    .detail-row {
+        display: flex;
+        padding: 0.5rem 0;
+        border-bottom: 1px solid #e5e7eb;
+    }
+
+    .detail-row:last-child {
+        border-bottom: none;
+    }
+
+    .detail-label {
+        font-weight: 600;
+        min-width: 160px;
+        color: #6b7280;
+        font-size: 0.875rem;
+        flex-shrink: 0;
+        padding-right: 1rem;
+    }
+
+    .detail-value {
+        flex: 1;
+        font-family: 'SF Mono', 'Monaco', 'Consolas', 'Courier New', monospace;
+        font-size: 0.75rem;
+        color: #111827;
+        word-break: break-all;
+        overflow-wrap: break-word;
+    }
+"""
+
+# Redirect section styles (for OAuth redirect URI box)
+REDIRECT_SECTION_STYLES = """
+    .redirect-section {
+        background: #fffbeb;
+        border: 1px solid #fcd34d;
+        border-radius: 0.5rem;
+        padding: 1rem;
+        margin-bottom: 1.5rem;
+        text-align: left;
+    }
+
+    .redirect-section .label {
+        font-size: 0.875rem;
+        color: #6b7280;
+        font-weight: 600;
+        margin-bottom: 0.5rem;
+        display: block;
+    }
+
+    .redirect-section .value {
+        font-family: 'SF Mono', 'Monaco', 'Consolas', 'Courier New', monospace;
+        font-size: 0.875rem;
+        color: #111827;
+        word-break: break-all;
+        margin-top: 0.25rem;
+    }
+"""
+
+# Collapsible details styles
+DETAILS_STYLES = """
+    details {
+        margin-bottom: 1.5rem;
+        text-align: left;
+    }
+
+    summary {
+        cursor: pointer;
+        font-size: 0.875rem;
+        color: #6b7280;
+        font-weight: 600;
+        list-style: none;
+        padding: 0.5rem;
+        border-radius: 0.25rem;
+    }
+
+    summary:hover {
+        background: #f9fafb;
+    }
+
+    summary::marker {
+        display: none;
+    }
+
+    summary::before {
+        content: "▶";
+        display: inline-block;
+        margin-right: 0.5rem;
+        transition: transform 0.2s;
+        font-size: 0.75rem;
+    }
+
+    details[open] summary::before {
+        transform: rotate(90deg);
+    }
+"""
+
+# Helper text styles
+HELPER_TEXT_STYLES = """
+    .close-instruction, .help-text {
+        font-size: 0.875rem;
+        color: #6b7280;
+        margin-top: 1.5rem;
+    }
+"""
+
+# Tooltip styles for hover help
+TOOLTIP_STYLES = """
+    .help-link-container {
+        position: fixed;
+        bottom: 1.5rem;
+        right: 1.5rem;
+        font-size: 0.875rem;
+    }
+
+    .help-link {
+        color: #6b7280;
+        text-decoration: none;
+        cursor: help;
+        position: relative;
+        display: inline-block;
+        border-bottom: 1px dotted #9ca3af;
+    }
+
+    @media (max-width: 640px) {
+        .help-link {
+            background: #ffffff;
+            padding: 0.25rem 0.5rem;
+            border-radius: 0.25rem;
+            box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+        }
+    }
+
+    .help-link:hover {
+        color: #111827;
+        border-bottom-color: #111827;
+    }
+
+    .help-link:hover .tooltip {
+        opacity: 1;
+        visibility: visible;
+    }
+
+    .tooltip {
+        position: absolute;
+        bottom: 100%;
+        right: 0;
+        left: auto;
+        margin-bottom: 0.5rem;
+        background: #1f2937;
+        color: #ffffff;
+        padding: 0.75rem 1rem;
+        border-radius: 0.5rem;
+        font-size: 0.8125rem;
+        line-height: 1.5;
+        width: 280px;
+        max-width: calc(100vw - 3rem);
+        opacity: 0;
+        visibility: hidden;
+        transition: opacity 0.2s, visibility 0.2s;
+        box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
+        text-align: left;
+    }
+
+    .tooltip::after {
+        content: '';
+        position: absolute;
+        top: 100%;
+        right: 1rem;
+        border: 6px solid transparent;
+        border-top-color: #1f2937;
+    }
+
+    .tooltip-link {
+        color: #60a5fa;
+        text-decoration: underline;
+    }
+"""
+
+
+def create_page(
+    content: str,
+    title: str = "FastMCP",
+    additional_styles: str = "",
+    csp_policy: str = "default-src 'none'; style-src 'unsafe-inline'; img-src https: data:; base-uri 'none'",
+) -> str:
+    """
+    Create a complete HTML page with FastMCP styling.
+
+    Args:
+        content: HTML content to place inside the page
+        title: Page title
+        additional_styles: Extra CSS to include
+        csp_policy: Content Security Policy header value.
+            If empty string "", the CSP meta tag is omitted entirely.
+
+    Returns:
+        Complete HTML page as string
+    """
+    title = html.escape(title)
+
+    # Only include CSP meta tag if policy is non-empty
+    csp_meta = (
+        f'<meta http-equiv="Content-Security-Policy" content="{html.escape(csp_policy, quote=True)}" />'
+        if csp_policy
+        else ""
+    )
+
+    return f"""
+    <!DOCTYPE html>
+    <html lang="en">
+    <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <title>{title}</title>
+        <style>
+            {BASE_STYLES}
+            {additional_styles}
+        </style>
+        {csp_meta}
+    </head>
+    <body>
+        {content}
+    </body>
+    </html>
+    """
+
+
+def create_logo(icon_url: str | None = None, alt_text: str = "FastMCP") -> str:
+    """Create logo HTML.
+
+    Args:
+        icon_url: Optional custom icon URL. If not provided, uses the FastMCP logo.
+        alt_text: Alt text for the logo image.
+
+    Returns:
+        HTML for logo image tag.
+    """
+    url = icon_url or FASTMCP_LOGO_URL
+    alt = html.escape(alt_text)
+    return f'<img src="{html.escape(url)}" alt="{alt}" class="logo" />'
+
+
+def create_status_message(message: str, is_success: bool = True) -> str:
+    """
+    Create a status message with icon.
+
+    Args:
+        message: Status message text
+        is_success: True for success (✓), False for error (✕)
+
+    Returns:
+        HTML for status message
+    """
+    message = html.escape(message)
+    icon = "✓" if is_success else "✕"
+    icon_class = "success" if is_success else "error"
+
+    return f"""
+        <div class="status-message">
+            <span class="status-icon {icon_class}">{icon}</span>
+            <div class="message">{message}</div>
+        </div>
+    """
+
+
+def create_info_box(
+    content: str,
+    is_error: bool = False,
+    centered: bool = False,
+    monospace: bool = False,
+) -> str:
+    """
+    Create an info box.
+
+    Args:
+        content: HTML content for the info box
+        is_error: True for error styling, False for normal
+        centered: True to center the text, False for left-aligned
+        monospace: True to use gray monospace font styling instead of blue
+
+    Returns:
+        HTML for info box
+    """
+    content = html.escape(content)
+    base_class = "info-box-mono" if monospace else "info-box"
+    classes = [base_class]
+    if is_error:
+        classes.append("error")
+    if centered:
+        classes.append("centered")
+    class_str = " ".join(classes)
+    return f'<div class="{class_str}">{content}</div>'
+
+
+def create_detail_box(rows: list[tuple[str, str]]) -> str:
+    """
+    Create a detail box with key-value pairs.
+
+    Args:
+        rows: List of (label, value) tuples
+
+    Returns:
+        HTML for detail box
+    """
+    rows_html = "\n".join(
+        f"""
+        <div class="detail-row">
+            <div class="detail-label">{html.escape(label)}:</div>
+            <div class="detail-value">{html.escape(value)}</div>
+        </div>
+        """
+        for label, value in rows
+    )
+
+    return f'<div class="detail-box">{rows_html}</div>'
+
+
+def create_button_group(buttons: list[tuple[str, str, str]]) -> str:
+    """
+    Create a group of buttons.
+
+    Args:
+        buttons: List of (text, value, css_class) tuples
+
+    Returns:
+        HTML for button group
+    """
+    buttons_html = "\n".join(
+        f'<button type="submit" name="action" value="{value}" class="{css_class}">{text}</button>'
+        for text, value, css_class in buttons
+    )
+
+    return f'<div class="button-group">{buttons_html}</div>'
+
+
+def create_secure_html_response(html: str, status_code: int = 200) -> HTMLResponse:
+    """
+    Create an HTMLResponse with security headers.
+
+    Adds X-Frame-Options: DENY to prevent clickjacking attacks per MCP security best practices.
+
+    Args:
+        html: HTML content to return
+        status_code: HTTP status code
+
+    Returns:
+        HTMLResponse with security headers
+    """
+    return HTMLResponse(
+        content=html,
+        status_code=status_code,
+        headers={"X-Frame-Options": "DENY"},
+    )
diff --git a/fastmcp_slim/fastmcp/utilities/version_check.py b/fastmcp_slim/fastmcp/utilities/version_check.py
new file mode 100644
index 0000000..5c3aba6
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/version_check.py
@@ -0,0 +1,153 @@
+"""Version checking utilities for FastMCP."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+import httpx
+from packaging.version import Version
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+PYPI_URL = "https://pypi.org/pypi/fastmcp/json"
+CACHE_TTL_SECONDS = 60 * 60 * 12  # 12 hours
+REQUEST_TIMEOUT_SECONDS = 2.0
+
+
+def _get_cache_path(include_prereleases: bool = False) -> Path:
+    """Get the path to the version cache file."""
+    import fastmcp
+
+    suffix = "_prerelease" if include_prereleases else ""
+    return fastmcp.settings.home / f"version_cache{suffix}.json"
+
+
+def _read_cache(include_prereleases: bool = False) -> tuple[str | None, float]:
+    """Read cached version info.
+
+    Returns:
+        Tuple of (cached_version, cache_timestamp) or (None, 0) if no cache.
+    """
+    cache_path = _get_cache_path(include_prereleases)
+    if not cache_path.exists():
+        return None, 0
+
+    try:
+        data = json.loads(cache_path.read_text())
+        return data.get("latest_version"), data.get("timestamp", 0)
+    except (json.JSONDecodeError, OSError):
+        return None, 0
+
+
+def _write_cache(latest_version: str, include_prereleases: bool = False) -> None:
+    """Write version info to cache."""
+    cache_path = _get_cache_path(include_prereleases)
+    try:
+        cache_path.parent.mkdir(parents=True, exist_ok=True)
+        cache_path.write_text(
+            json.dumps({"latest_version": latest_version, "timestamp": time.time()})
+        )
+    except OSError:
+        # Silently ignore cache write failures
+        pass
+
+
+def _fetch_latest_version(include_prereleases: bool = False) -> str | None:
+    """Fetch the latest version from PyPI.
+
+    Args:
+        include_prereleases: If True, include pre-release versions (alpha, beta, rc).
+
+    Returns:
+        The latest version string, or None if the fetch failed.
+    """
+    try:
+        response = httpx.get(PYPI_URL, timeout=REQUEST_TIMEOUT_SECONDS)
+        response.raise_for_status()
+        data = response.json()
+
+        releases = data.get("releases", {})
+        if not releases:
+            return None
+
+        versions = []
+        for version_str in releases:
+            try:
+                v = Version(version_str)
+                # Skip prereleases if not requested
+                if not include_prereleases and v.is_prerelease:
+                    continue
+                versions.append(v)
+            except ValueError:
+                logger.debug(f"Skipping invalid version string: {version_str}")
+                continue
+
+        if not versions:
+            return None
+
+        return str(max(versions))
+
+    except (httpx.HTTPError, json.JSONDecodeError, KeyError):
+        return None
+
+
+def get_latest_version(include_prereleases: bool = False) -> str | None:
+    """Get the latest version of FastMCP from PyPI, using cache when available.
+
+    Args:
+        include_prereleases: If True, include pre-release versions.
+
+    Returns:
+        The latest version string, or None if unavailable.
+    """
+    # Check cache first
+    cached_version, cache_timestamp = _read_cache(include_prereleases)
+    if cached_version and (time.time() - cache_timestamp) < CACHE_TTL_SECONDS:
+        return cached_version
+
+    # Fetch from PyPI
+    latest_version = _fetch_latest_version(include_prereleases)
+
+    # Update cache if we got a valid version
+    if latest_version:
+        _write_cache(latest_version, include_prereleases)
+        return latest_version
+
+    # Return stale cache if available
+    return cached_version
+
+
+def check_for_newer_version() -> str | None:
+    """Check if a newer version of FastMCP is available.
+
+    Returns:
+        The latest version string if newer than current, None otherwise.
+    """
+    import fastmcp
+
+    setting = fastmcp.settings.check_for_updates
+    if setting == "off":
+        return None
+
+    include_prereleases = setting == "prerelease"
+    latest_version = get_latest_version(include_prereleases)
+    if not latest_version:
+        return None
+
+    try:
+        current = Version(fastmcp.__version__)
+        latest = Version(latest_version)
+
+        if latest > current:
+            return latest_version
+    except ValueError:
+        logger.debug(
+            f"Could not compare versions: current={fastmcp.__version__!r}, "
+            f"latest={latest_version!r}"
+        )
+
+    return None
diff --git a/fastmcp_slim/fastmcp/utilities/versions.py b/fastmcp_slim/fastmcp/utilities/versions.py
new file mode 100644
index 0000000..a8a7a89
--- /dev/null
+++ b/fastmcp_slim/fastmcp/utilities/versions.py
@@ -0,0 +1,348 @@
+"""Version comparison utilities for component versioning.
+
+This module provides utilities for comparing component versions. Versions are
+strings that are first attempted to be parsed as PEP 440 versions (using the
+`packaging` library), falling back to lexicographic string comparison.
+
+Examples:
+    - "1", "2", "10" → parsed as PEP 440, compared semantically (1 < 2 < 10)
+    - "1.0", "2.0" → parsed as PEP 440
+    - "v1.0" → 'v' prefix stripped, parsed as "1.0"
+    - "2025-01-15" → not valid PEP 440, compared as strings
+    - None → sorts lowest (unversioned components)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from functools import total_ordering
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from packaging.version import InvalidVersion, Version
+
+if TYPE_CHECKING:
+    from fastmcp.utilities.components import FastMCPComponent
+
+C = TypeVar("C", bound=Any)
+
+
+@dataclass
+class VersionSpec:
+    """Specification for filtering components by version.
+
+    Used by transforms and providers to filter components to a specific
+    version or version range. Unversioned components (version=None) always
+    match any spec.
+
+    Args:
+        gte: If set, only versions >= this value match.
+        lt: If set, only versions < this value match.
+        eq: If set, only this exact version matches (gte/lt ignored).
+            Matching is PEP 440-normalized and `v`-prefix insensitive, so
+            `eq="v1.0"` matches a component versioned `"1.0"`, and `eq="1.0"`
+            matches `"1"` (PEP 440 treats `1` and `1.0` as the same version).
+            If a server registers two PEP 440-equivalent spellings of the
+            same component (e.g. both `"1"` and `"1.0"`), they are the same
+            version under this spec; selection among them is deterministic
+            (see `version_sort_key`), not registration-order dependent.
+    """
+
+    gte: str | None = None
+    lt: str | None = None
+    eq: str | None = None
+
+    def matches(self, version: str | None, *, match_none: bool = True) -> bool:
+        """Check if a version matches this spec.
+
+        Args:
+            version: The version to check, or None for unversioned.
+            match_none: Whether unversioned (None) components match. Defaults to True
+                for backward compatibility with retrieval operations. Set to False
+                when filtering (e.g., enable/disable) to exclude unversioned components
+                from version-specific rules.
+
+        Returns:
+            True if the version matches the spec.
+        """
+        if version is None:
+            return match_none
+
+        if self.eq is not None:
+            return parse_version_key(version) == parse_version_key(self.eq)
+
+        key = parse_version_key(version)
+
+        if self.gte is not None:
+            gte_key = parse_version_key(self.gte)
+            if key < gte_key:
+                return False
+
+        if self.lt is not None:
+            lt_key = parse_version_key(self.lt)
+            if not key < lt_key:
+                return False
+
+        return True
+
+    def intersect(self, other: VersionSpec | None) -> VersionSpec:
+        """Return a spec that satisfies both this spec and other.
+
+        Used by transforms to combine caller constraints with filter constraints.
+        For example, if a VersionFilter has lt="3.0" and caller requests eq="1.0",
+        the intersection validates "1.0" is in range and returns the exact spec.
+
+        Args:
+            other: Another spec to intersect with, or None.
+
+        Returns:
+            A VersionSpec that matches only versions satisfying both specs.
+        """
+        if other is None:
+            return self
+
+        if self.eq is not None:
+            # This spec wants exact - validate against other's range
+            if other.matches(self.eq):
+                return self
+            return VersionSpec(eq="__impossible__")
+
+        if other.eq is not None:
+            # Other wants exact - validate against our range
+            if self.matches(other.eq):
+                return other
+            return VersionSpec(eq="__impossible__")
+
+        # Both are ranges - take tighter bounds
+        return VersionSpec(
+            gte=max_version(self.gte, other.gte),
+            lt=min_version(self.lt, other.lt),
+        )
+
+
+@total_ordering
+class VersionKey:
+    """A comparable version key that handles None, PEP 440 versions, and strings.
+
+    Comparison order:
+    1. None (unversioned) sorts lowest
+    2. PEP 440 versions sort by semantic version order
+    3. Invalid versions (strings) sort lexicographically
+    4. When comparing PEP 440 vs string, PEP 440 comes first
+    """
+
+    __slots__ = ("_is_none", "_is_pep440", "_parsed", "_raw")
+
+    def __init__(self, version: str | None) -> None:
+        self._raw = version
+        self._is_none = version is None
+        self._is_pep440 = False
+        self._parsed: Version | str | None = None
+
+        if version is not None:
+            # Strip leading 'v' if present (common convention like "v1.0")
+            normalized = version.lstrip("v") if version.startswith("v") else version
+            try:
+                self._parsed = Version(normalized)
+                self._is_pep440 = True
+            except InvalidVersion:
+                # Fall back to string comparison for non-PEP 440 versions
+                self._parsed = version
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, VersionKey):
+            return NotImplemented
+        if self._is_none and other._is_none:
+            return True
+        if self._is_none != other._is_none:
+            return False
+        # Both are not None
+        if self._is_pep440 and other._is_pep440:
+            return self._parsed == other._parsed
+        if not self._is_pep440 and not other._is_pep440:
+            return self._parsed == other._parsed
+        # One is PEP 440, other is string - never equal
+        return False
+
+    def __lt__(self, other: object) -> bool:
+        if not isinstance(other, VersionKey):
+            return NotImplemented
+        # None sorts lowest
+        if self._is_none and other._is_none:
+            return False  # Equal
+        if self._is_none:
+            return True  # None < anything
+        if other._is_none:
+            return False  # anything > None
+
+        # Both are not None
+        if self._is_pep440 and other._is_pep440:
+            # Both PEP 440 - compare normally
+            assert isinstance(self._parsed, Version)
+            assert isinstance(other._parsed, Version)
+            return self._parsed < other._parsed
+        if not self._is_pep440 and not other._is_pep440:
+            # Both strings - lexicographic
+            assert isinstance(self._parsed, str)
+            assert isinstance(other._parsed, str)
+            return self._parsed < other._parsed
+        # Mixed: PEP 440 sorts before strings
+        # (arbitrary but consistent choice)
+        return self._is_pep440
+
+    def __repr__(self) -> str:
+        return f"VersionKey({self._raw!r})"
+
+
+def parse_version_key(version: str | None) -> VersionKey:
+    """Parse a version string into a sortable key.
+
+    Args:
+        version: The version string, or None for unversioned.
+
+    Returns:
+        A VersionKey suitable for sorting.
+    """
+    return VersionKey(version)
+
+
+def version_sort_key(component: FastMCPComponent) -> tuple[VersionKey, str]:
+    """Get a sort key for a component based on its version.
+
+    Use with sorted() or max() to order components by version.
+
+    The key is a `(VersionKey, raw)` tuple. The `VersionKey` orders by PEP 440
+    semantics (or lexicographically for non-PEP 440 strings); the raw version
+    string is a deterministic tie-breaker so that two components whose versions
+    are PEP 440-equivalent but spelled differently (e.g. `"1"` and `"1.0"`) are
+    ordered reproducibly instead of by registration order. The raw tie-breaker
+    only affects equivalent-version ties and never the primary version order,
+    so range/equality matching (which uses `VersionKey` directly) is unchanged.
+
+    Args:
+        component: The component to get a sort key for.
+
+    Returns:
+        A deterministic, sortable `(VersionKey, raw)` tuple.
+
+    Example:
+        ```python
+        tools = [tool_v1, tool_v2, tool_unversioned]
+        highest = max(tools, key=version_sort_key)  # Returns tool_v2
+        ```
+    """
+    return (parse_version_key(component.version), component.version or "")
+
+
+def compare_versions(a: str | None, b: str | None) -> int:
+    """Compare two version strings.
+
+    Args:
+        a: First version string (or None).
+        b: Second version string (or None).
+
+    Returns:
+        -1 if a < b, 0 if a == b, 1 if a > b.
+
+    Example:
+        ```python
+        compare_versions("1.0", "2.0")  # Returns -1
+        compare_versions("2.0", "1.0")  # Returns 1
+        compare_versions(None, "1.0")   # Returns -1 (None < any version)
+        ```
+    """
+    key_a = parse_version_key(a)
+    key_b = parse_version_key(b)
+    return (key_a > key_b) - (key_a < key_b)
+
+
+def is_version_greater(a: str | None, b: str | None) -> bool:
+    """Check if version a is greater than version b.
+
+    Args:
+        a: First version string (or None).
+        b: Second version string (or None).
+
+    Returns:
+        True if a > b, False otherwise.
+    """
+    return compare_versions(a, b) > 0
+
+
+def max_version(a: str | None, b: str | None) -> str | None:
+    """Return the greater of two versions.
+
+    Args:
+        a: First version string (or None).
+        b: Second version string (or None).
+
+    Returns:
+        The greater version, or None if both are None.
+    """
+    if a is None:
+        return b
+    if b is None:
+        return a
+    return a if compare_versions(a, b) >= 0 else b
+
+
+def min_version(a: str | None, b: str | None) -> str | None:
+    """Return the lesser of two versions.
+
+    Args:
+        a: First version string (or None).
+        b: Second version string (or None).
+
+    Returns:
+        The lesser version, or None if both are None.
+    """
+    if a is None:
+        return b
+    if b is None:
+        return a
+    return a if compare_versions(a, b) <= 0 else b
+
+
+def dedupe_with_versions(
+    components: Sequence[C],
+    key_fn: Callable[[C], str],
+) -> list[C]:
+    """Deduplicate components by key, keeping highest version.
+
+    Groups components by key, selects the highest version from each group,
+    and injects available versions into meta if any component is versioned.
+
+    Args:
+        components: Sequence of components to deduplicate.
+        key_fn: Function to extract the grouping key from a component.
+
+    Returns:
+        Deduplicated list with versions injected into meta.
+    """
+    by_key: dict[str, list[C]] = {}
+    for c in components:
+        by_key.setdefault(key_fn(c), []).append(c)
+
+    result: list[C] = []
+    for versions in by_key.values():
+        highest: C = max(versions, key=version_sort_key)
+        if any(c.version is not None for c in versions):
+            all_versions = sorted(
+                [c.version for c in versions if c.version is not None],
+                key=parse_version_key,
+                reverse=True,
+            )
+            meta = highest.meta or {}
+            highest = highest.model_copy(
+                update={
+                    "meta": {
+                        **meta,
+                        "fastmcp": {
+                            **meta.get("fastmcp", {}),
+                            "versions": all_versions,
+                        },
+                    }
+                }
+            )
+        result.append(highest)
+    return result
diff --git a/fastmcp_slim/pyproject.toml b/fastmcp_slim/pyproject.toml
new file mode 100644
index 0000000..7555ae5
--- /dev/null
+++ b/fastmcp_slim/pyproject.toml
@@ -0,0 +1,108 @@
+[project]
+name = "fastmcp-slim"
+dynamic = ["version", "optional-dependencies"]
+description = "The dependency-slim FastMCP package."
+authors = [{ name = "Jeremiah Lowin" }]
+dependencies = [
+    "mcp-types==2.0.0b1",
+    "platformdirs>=4.0.0",
+    "pydantic[email]>=2.12.0",
+    "pydantic-settings>=2.0.0",
+    "python-dotenv>=1.1.0",
+    "rich>=13.9.4",
+    "typing-extensions>=4.0.0",
+]
+
+requires-python = ">=3.10"
+readme = "README.md"
+license = "Apache-2.0"
+
+keywords = [
+    "mcp",
+    "mcp server",
+    "mcp client",
+    "model context protocol",
+    "fastmcp",
+    "llm",
+    "agent",
+]
+classifiers = [
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://gofastmcp.com"
+Repository = "https://github.com/PrefectHQ/fastmcp"
+Documentation = "https://gofastmcp.com"
+
+[project.scripts]
+fastmcp = "fastmcp.cli:app"
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning>=0.7.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["fastmcp"]
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+bump = true
+fallback-version = "0.0.0"
+
+[tool.hatch.metadata.hooks.uv-dynamic-versioning.optional-dependencies]
+anthropic = ["anthropic>=0.48.0"]
+apps = ["prefab-ui>=0.18.0"]
+# PyJWT floor: transitive via msal; CVE-2026-32597 affects <= 2.11.0
+azure = ["azure-identity>=1.16.0", "PyJWT>=2.12.0"]
+client = [
+    "fastmcp-slim[mcp]=={{ version }}",
+    "authlib>=1.6.11",
+    "py-key-value-aio[filetree,keyring,memory]>=0.4.4,<0.5.0",
+]
+code-mode = ["pydantic-monty==0.0.17"]
+gemini = ["google-genai>=1.18.0", "jsonref>=1.1.0"]
+mcp = [
+    "exceptiongroup>=1.2.2",
+    "httpx>=0.28.1,<1.0",
+    "mcp==2.0.0b1",
+    "opentelemetry-api>=1.28.0",
+    # starlette floor: transitive via mcp (which only requires >=0.27).
+    # Pin past CVE-2026-48710, which was patched in 1.0.1.
+    "starlette>=1.0.1",
+]
+openai = ["openai>=1.102.0"]
+server = [
+    "fastmcp-slim[mcp]=={{ version }}",
+    "authlib>=1.6.11",
+    "cyclopts>=4.0.0",
+    "griffelib>=2.0.0",
+    "jsonref>=1.1.0",
+    "jsonschema-path>=0.3.4",
+    "joserfc>=1.1.0",
+    "openapi-pydantic>=0.5.1",
+    "packaging>=24.0",
+    "py-key-value-aio[filetree,keyring,memory]>=0.4.4,<0.5.0",
+    "pyperclip>=1.9.0",
+    "python-multipart>=0.0.26",
+    "pyyaml>=6.0,<7.0",
+    "uncalled-for>=0.2.0",
+    "uvicorn>=0.35",
+    "watchfiles>=1.0.0",
+    "websockets>=15.0.1",
+]
+tasks = ["pydocket>=0.20.0"]
diff --git a/justfile b/justfile
new file mode 100644
index 0000000..2876e6f
--- /dev/null
+++ b/justfile
@@ -0,0 +1,35 @@
+api_ref_package := "fastmcp-slim[anthropic,apps,azure,code-mode,full,gemini,openai,tasks] @ file://" + justfile_directory() + "/fastmcp_slim"
+
+# Build the project
+build:
+    uv sync
+
+# Run tests
+test: build
+    uv run --frozen pytest -xvs tests
+
+# Run ty type checker on all files
+typecheck:
+    uv run --frozen ty check
+
+# Serve documentation locally
+docs:
+    cd docs && npx --yes mint@latest dev
+
+# Check for broken links in documentation
+docs-broken-links:
+    cd docs && npx --yes mint@latest broken-links
+
+# Generate API reference documentation for all modules
+api-ref-all:
+    uvx --with-editable "{{api_ref_package}}" --refresh-package mdxify mdxify@latest --all --root-module fastmcp --nav-output docs/python-sdk-pages.json --exclude fastmcp.contrib
+# Generate API reference for specific modules (e.g., just api-ref prefect.flows prefect.tasks)
+api-ref *MODULES:
+    uvx --with-editable "{{api_ref_package}}" --refresh-package mdxify mdxify@latest {{MODULES}} --root-module fastmcp --nav-output docs/python-sdk-pages.json
+
+# Clean up API reference documentation
+api-ref-clean:
+    rm -rf docs/python-sdk
+
+copy-context:
+    uvx --with-editable fastmcp_slim --refresh-package copychat copychat@latest fastmcp_slim/fastmcp docs/ -x changelog.mdx -x python-sdk/ -v
diff --git a/logo.py b/logo.py
new file mode 100644
index 0000000..4a887d8
--- /dev/null
+++ b/logo.py
@@ -0,0 +1,25 @@
+LOGO_ASCII_3 = (
+    " \x1b[38;2;0;170;255m▄\x1b[38;2;0;142;255m▀\x1b[38;2;0;114;255m▀\x1b[38;2;0;86;255m▀\x1b[39m\n"
+    " \x1b[38;2;0;170;255m█\x1b[38;2;0;142;255m▀\x1b[38;2;0;114;255m▀\x1b[39m\n"
+    "\x1b[38;2;0;170;255m▀\x1b[39m\n"
+    "\x1b[0m"
+)
+
+LOGO_ASCII_4 = (
+    "\x1b[38;2;0;198;255m \x1b[38;2;0;195;255m▄\x1b[38;2;0;192;255m▀\x1b[38;2;0;189;255m▀\x1b[38;2;0;186;255m \x1b[38;2;0;184;255m▄\x1b[38;2;0;181;255m▀\x1b[38;2;0;178;255m█\x1b[38;2;0;175;255m "
+    "\x1b[38;2;0;172;255m█\x1b[38;2;0;169;255m▀\x1b[38;2;0;166;255m▀\x1b[38;2;0;163;255m "
+    "\x1b[38;2;0;160;255m▀\x1b[38;2;0;157;255m█\x1b[38;2;0;155;255m▀\x1b[38;2;0;152;255m "
+    "\x1b[38;2;0;149;255m█\x1b[38;2;0;146;255m▀\x1b[38;2;0;143;255m▄\x1b[38;2;0;140;255m▀\x1b[38;2;0;137;255m█\x1b[38;2;0;134;255m "
+    "\x1b[38;2;0;131;255m█\x1b[38;2;0;128;255m▀\x1b[38;2;0;126;255m▀\x1b[38;2;0;123;255m "
+    "\x1b[38;2;0;120;255m█\x1b[38;2;0;117;255m▀\x1b[38;2;0;114;255m█\x1b[39m\n"
+    "\x1b[38;2;0;198;255m \x1b[38;2;0;195;255m█\x1b[38;2;0;192;255m▀\x1b[38;2;0;189;255m \x1b[38;2;0;186;255m \x1b[38;2;0;184;255m█\x1b[38;2;0;181;255m▀\x1b[38;2;0;178;255m█\x1b[38;2;0;175;255m "
+    "\x1b[38;2;0;172;255m▄\x1b[38;2;0;169;255m▄\x1b[38;2;0;166;255m█\x1b[38;2;0;163;255m "
+    "\x1b[38;2;0;160;255m \x1b[38;2;0;157;255m█\x1b[38;2;0;155;255m \x1b[38;2;0;152;255m "
+    "\x1b[38;2;0;149;255m█\x1b[38;2;0;146;255m \x1b[38;2;0;143;255m▀\x1b[38;2;0;140;255m \x1b[38;2;0;137;255m█\x1b[38;2;0;134;255m "
+    "\x1b[38;2;0;131;255m█\x1b[38;2;0;128;255m▄\x1b[38;2;0;126;255m▄\x1b[38;2;0;123;255m "
+    "\x1b[38;2;0;120;255m█\x1b[38;2;0;117;255m▀\x1b[38;2;0;114;255m▀\x1b[39m\n"
+    "\x1b[38;2;0;198;255m \x1b[39m\n"
+    "\x1b[0m"
+)
+
+print(LOGO_ASCII_3)
diff --git a/loq.toml b/loq.toml
new file mode 100644
index 0000000..654c599
--- /dev/null
+++ b/loq.toml
@@ -0,0 +1,67 @@
+# loq configuration - file size enforcement
+# Run `loq baseline` to update when files exceed limits
+
+default_max_lines = 1000
+respect_gitignore = true
+
+exclude = ["**/uv.lock", ".git/**", ".claude/**", "docs/**"]
+
+[[rules]]
+path = "tests/**"
+max_lines = 1000
+
+[[rules]]
+path = "fastmcp_slim/fastmcp/server/context.py"
+max_lines = 1404
+
+[[rules]]
+path = "fastmcp_slim/fastmcp/server/server.py"
+max_lines = 2410
+
+[[rules]]
+path = "fastmcp_slim/fastmcp/server/auth/oauth_proxy/proxy.py"
+max_lines = 2098
+
+[[rules]]
+path = "fastmcp_slim/fastmcp/cli/apps_dev.py"
+max_lines = 1814
+
+[[rules]]
+path = "fastmcp_slim/fastmcp/cli/cli.py"
+max_lines = 1116
+
+[[rules]]
+path = "fastmcp_slim/fastmcp/server/dependencies.py"
+max_lines = 1686
+
+[[rules]]
+path = "fastmcp_slim/fastmcp/server/providers/proxy.py"
+max_lines = 1096
+
+[[rules]]
+path = "fastmcp_slim/fastmcp/tools/tool_transform.py"
+max_lines = 1004
+
+[[rules]]
+path = "tests/resources/test_resource_template.py"
+max_lines = 1016
+
+[[rules]]
+path = "tests/server/providers/openapi/test_openapi_features.py"
+max_lines = 1029
+
+[[rules]]
+path = "tests/server/tasks/test_task_mount.py"
+max_lines = 1088
+
+[[rules]]
+path = "tests/server/test_dependencies.py"
+max_lines = 1194
+
+[[rules]]
+path = "tests/test_mcp_config.py"
+max_lines = 1185
+
+[[rules]]
+path = "tests/utilities/openapi/test_director.py"
+max_lines = 1154
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..55079ec
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,223 @@
+[project]
+name = "fastmcp"
+dynamic = ["version", "dependencies", "optional-dependencies"]
+description = "The fast, Pythonic way to build MCP servers and clients."
+authors = [{ name = "Jeremiah Lowin" }]
+requires-python = ">=3.10"
+readme = "README.md"
+license = "Apache-2.0"
+keywords = [
+    "mcp",
+    "mcp server",
+    "mcp client",
+    "model context protocol",
+    "fastmcp",
+    "llm",
+    "agent",
+]
+classifiers = [
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://gofastmcp.com"
+Repository = "https://github.com/PrefectHQ/fastmcp"
+Documentation = "https://gofastmcp.com"
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning>=0.7.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.hatch.build.targets.wheel]
+bypass-selection = true
+only-include = []
+exclude = ["/*"]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.metadata.hooks.uv-dynamic-versioning]
+dependencies = [
+    "fastmcp-slim[client,server]=={{ version }}",
+]
+
+[tool.hatch.metadata.hooks.uv-dynamic-versioning.optional-dependencies]
+anthropic = ["fastmcp-slim[anthropic]=={{ version }}"]
+apps = ["fastmcp-slim[apps]=={{ version }}"]
+azure = ["fastmcp-slim[azure]=={{ version }}"]
+code-mode = ["fastmcp-slim[code-mode]=={{ version }}"]
+gemini = ["fastmcp-slim[gemini]=={{ version }}"]
+openai = ["fastmcp-slim[openai]=={{ version }}"]
+tasks = ["fastmcp-slim[tasks]=={{ version }}"]
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+bump = true
+fallback-version = "0.0.0"
+
+[tool.uv.workspace]
+members = ["fastmcp_slim", "fastmcp_remote"]
+
+[tool.uv]
+default-groups = ["dev"]
+exclude-newer = "1 week"
+exclude-newer-package = { prefab-ui = false, mcp = false, mcp-types = false }
+
+[dependency-groups]
+dev = [
+    "dirty-equals>=0.9.0",
+    "fastmcp[anthropic,apps,azure,code-mode,gemini,openai,tasks]",
+    "fastapi>=0.115.12",
+    "fastmcp-remote",
+    "opentelemetry-sdk>=1.20.0",
+    "inline-snapshot[dirty-equals]>=0.27.2",
+    "ipython>=8.12.3",
+    "pdbpp>=0.11.7",
+    "psutil>=7.0.0",
+    "pyinstrument>=5.0.2",
+    "pyperclip>=1.9.0",
+    "pytest>=8.3.3",
+    "pytest-asyncio>=1.2.0",
+    "pytest-cov>=6.1.1",
+    "pytest-env>=1.1.5",
+    "pytest-flakefinder>=1.1.0",
+    "pytest-httpx>=0.35.0",
+    "pytest-report>=0.2.1",
+    "pytest-retry>=1.7.0",
+    "pytest-timeout>=2.4.0",
+    "pytest-xdist>=3.6.1",
+    "ruff>=0.12.8",
+    "ty>=0.0.55",
+    "prek>=0.2.12",
+    "loq>=0.1.0a3",
+    "opentelemetry-exporter-otlp-proto-grpc>=1.39.0",
+    "pytest-examples>=0.0.18",
+]
+
+[tool.uv.sources]
+fastmcp = { workspace = true }
+fastmcp-slim = { workspace = true }
+fastmcp-remote = { workspace = true }
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+filterwarnings = [
+    "ignore:Using in-memory token storage:UserWarning",
+    "error:coroutine .* was never awaited:RuntimeWarning",
+    "error:Exception ignored in.*coroutine:pytest.PytestUnraisableExceptionWarning",
+]
+timeout = 5
+env = [
+    "FASTMCP_TEST_MODE=1",
+    'D:FASTMCP_LOG_LEVEL=DEBUG',
+    'D:FASTMCP_ENABLE_RICH_TRACEBACKS=0',
+]
+markers = [
+    "integration: marks tests as integration tests (deselect with '-m \"not integration\"')",
+    "client_process: marks tests that spawn client processes via stdio transport. These can create issues when run in the same CI environment as other subprocess-based tests.",
+    "conformance: marks MCP conformance tests (require Node.js/npx)",
+]
+pythonpath = ["fastmcp_slim", "fastmcp_remote"]
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = ["--inline-snapshot=disable"]
+
+[tool.ty.src]
+include = ["fastmcp_slim", "fastmcp_remote", "tests"]
+exclude = ["**/node_modules", "**/__pycache__", ".venv", ".git", "dist"]
+
+[tool.ty.environment]
+python-version = "3.10"
+
+[tool.ty.analysis]
+replace-imports-with-any = ["prefab_ui.**"]
+
+[tool.ty.rules]
+division-by-zero = "warn"
+possibly-missing-attribute = "warn"
+possibly-missing-import = "warn"
+possibly-unresolved-reference = "warn"
+unsupported-dynamic-base = "warn"
+unsupported-operator = "warn"
+unused-ignore-comment = "warn"
+
+[tool.ty.terminal]
+error-on-warning = true
+
+[tool.ruff.lint]
+fixable = ["ALL"]
+ignore = [
+    "COM812",
+    "PERF203",
+    "PLR0913",
+    "SIM102",
+]
+extend-select = [
+    "B",
+    "C4",
+    "DTZ",
+    "ERA",
+    "FA",
+    "FLY",
+    "I",
+    "INP",
+    "ISC",
+    "LOG",
+    "PERF",
+    "PIE",
+    "PLE",
+    "RSE",
+    "RUF",
+    "SIM",
+    "SLOT",
+    "T20",
+    "TID",
+    "UP",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["fastmcp", "fastmcp_remote"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401", "I001", "RUF013"]
+"fastmcp_slim/fastmcp/__init__.py" = ["E402"]
+"fastmcp_slim/fastmcp/cli/**.py" = ["T20"]
+"fastmcp_slim/fastmcp/client/oauth_callback.py" = ["T20"]
+"fastmcp_slim/fastmcp/contrib/**/example.py" = ["T20"]
+"!fastmcp_slim/fastmcp/**.py" = [
+    "B",
+    "C4",
+    "DTZ",
+    "ERA",
+    "FA",
+    "FLY",
+    "INP",
+    "ISC",
+    "LOG",
+    "PERF",
+    "PIE",
+    "PLE",
+    "RSE",
+    "RUF",
+    "SIM",
+    "SLOT",
+    "T20",
+    "TID",
+]
+
+[tool.codespell]
+ignore-words-list = "asend,shttp,te"
diff --git a/scripts/auto_close_duplicates.py b/scripts/auto_close_duplicates.py
new file mode 100644
index 0000000..87965fb
--- /dev/null
+++ b/scripts/auto_close_duplicates.py
@@ -0,0 +1,371 @@
+#!/usr/bin/env python
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "httpx",
+# ]
+# ///
+"""
+Auto-close duplicate GitHub issues.
+
+This script runs on a schedule to automatically close issues that have been
+marked as duplicates and haven't received any preventing activity.
+"""
+
+import os
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+import httpx
+
+
+@dataclass
+class Issue:
+    """Represents a GitHub issue."""
+
+    number: int
+    title: str
+    state: str
+    created_at: str
+    user_id: int
+    user_login: str
+
+
+@dataclass
+class Comment:
+    """Represents a GitHub comment."""
+
+    id: int
+    body: str
+    created_at: str
+    user_id: int
+    user_login: str
+    user_type: str
+
+
+@dataclass
+class Reaction:
+    """Represents a reaction on a comment."""
+
+    user_id: int
+    user_login: str
+    content: str
+
+
+class GitHubClient:
+    """Client for interacting with GitHub API."""
+
+    def __init__(self, token: str, owner: str, repo: str):
+        self.token = token
+        self.owner = owner
+        self.repo = repo
+        self.headers = {
+            "Authorization": f"token {token}",
+            "Accept": "application/vnd.github.v3+json",
+        }
+        self.base_url = f"https://api.github.com/repos/{owner}/{repo}"
+
+    def get_potential_duplicate_issues(self) -> list[Issue]:
+        """Fetch open issues with the potential-duplicate label."""
+        url = f"{self.base_url}/issues"
+        issues = []
+
+        with httpx.Client() as client:
+            page = 1
+            while page <= 10:  # Safety limit
+                response = client.get(
+                    url,
+                    headers=self.headers,
+                    params={
+                        "state": "open",
+                        "labels": "potential-duplicate",
+                        "per_page": 100,
+                        "page": page,
+                    },
+                )
+
+                if response.status_code != 200:
+                    print(f"Error fetching issues: {response.status_code}")
+                    break
+
+                data = response.json()
+                if not data:
+                    break
+
+                for item in data:
+                    # Skip pull requests
+                    if "pull_request" in item:
+                        continue
+
+                    issues.append(
+                        Issue(
+                            number=item["number"],
+                            title=item["title"],
+                            state=item["state"],
+                            created_at=item["created_at"],
+                            user_id=item["user"]["id"],
+                            user_login=item["user"]["login"],
+                        )
+                    )
+
+                page += 1
+
+        return issues
+
+    def get_issue_comments(self, issue_number: int) -> list[Comment]:
+        """Fetch all comments for an issue."""
+        url = f"{self.base_url}/issues/{issue_number}/comments"
+        comments = []
+
+        with httpx.Client() as client:
+            page = 1
+            while True:
+                response = client.get(
+                    url, headers=self.headers, params={"page": page, "per_page": 100}
+                )
+
+                if response.status_code != 200:
+                    break
+
+                data = response.json()
+                if not data:
+                    break
+
+                for comment_data in data:
+                    comments.append(
+                        Comment(
+                            id=comment_data["id"],
+                            body=comment_data["body"],
+                            created_at=comment_data["created_at"],
+                            user_id=comment_data["user"]["id"],
+                            user_login=comment_data["user"]["login"],
+                            user_type=comment_data["user"]["type"],
+                        )
+                    )
+
+                page += 1
+                if page > 10:  # Safety limit
+                    break
+
+        return comments
+
+    def get_comment_reactions(
+        self, issue_number: int, comment_id: int
+    ) -> list[Reaction]:
+        """Fetch reactions for a specific comment."""
+        url = f"{self.base_url}/issues/{issue_number}/comments/{comment_id}/reactions"
+        reactions = []
+
+        with httpx.Client() as client:
+            response = client.get(url, headers=self.headers)
+
+            if response.status_code != 200:
+                return reactions
+
+            data = response.json()
+            for reaction_data in data:
+                reactions.append(
+                    Reaction(
+                        user_id=reaction_data["user"]["id"],
+                        user_login=reaction_data["user"]["login"],
+                        content=reaction_data["content"],
+                    )
+                )
+
+        return reactions
+
+    def remove_label(self, issue_number: int, label: str) -> bool:
+        """Remove a label from an issue."""
+        url = f"{self.base_url}/issues/{issue_number}/labels/{label}"
+        with httpx.Client() as client:
+            response = client.delete(url, headers=self.headers)
+            return response.status_code in [200, 204]
+
+    def close_issue(self, issue_number: int, comment: str) -> bool:
+        """Close an issue with a comment and add duplicate label."""
+        # First add the comment
+        comment_url = f"{self.base_url}/issues/{issue_number}/comments"
+        with httpx.Client() as client:
+            response = client.post(
+                comment_url, headers=self.headers, json={"body": comment}
+            )
+
+            if response.status_code != 201:
+                print(f"Failed to add comment to issue #{issue_number}")
+                return False
+
+        # Swap labels: remove potential-duplicate, add duplicate
+        self.remove_label(issue_number, "potential-duplicate")
+
+        labels_url = f"{self.base_url}/issues/{issue_number}/labels"
+        with httpx.Client() as client:
+            response = client.post(
+                labels_url, headers=self.headers, json={"labels": ["duplicate"]}
+            )
+
+            if response.status_code not in [200, 201]:
+                print(f"Failed to add duplicate label to issue #{issue_number}")
+
+        # Then close the issue
+        issue_url = f"{self.base_url}/issues/{issue_number}"
+        with httpx.Client() as client:
+            response = client.patch(
+                issue_url, headers=self.headers, json={"state": "closed"}
+            )
+
+            return response.status_code == 200
+
+
+def find_duplicate_comment(comments: list[Comment]) -> Comment | None:
+    """Find a bot comment marking the issue as duplicate."""
+    for comment in comments:
+        # Check for the specific duplicate message format from a bot
+        if (
+            comment.user_type == "Bot"
+            and "possible duplicate issues" in comment.body.lower()
+        ):
+            return comment
+    return None
+
+
+def was_already_auto_closed(comments: list[Comment]) -> bool:
+    """Check if this issue was already auto-closed once."""
+    for comment in comments:
+        if (
+            comment.user_type == "Bot"
+            and "closing this issue as a duplicate" in comment.body.lower()
+        ):
+            return True
+    return False
+
+
+def is_past_cooldown(duplicate_comment: Comment) -> bool:
+    """Check if the 3-day cooldown period has passed."""
+    comment_date = datetime.fromisoformat(
+        duplicate_comment.created_at.replace("Z", "+00:00")
+    )
+    three_days_ago = datetime.now(timezone.utc) - timedelta(days=3)
+    return comment_date <= three_days_ago
+
+
+def has_human_activity(
+    issue: Issue,
+    duplicate_comment: Comment,
+    all_comments: list[Comment],
+    reactions: list[Reaction],
+) -> bool:
+    """Check if there's human activity that should prevent auto-closure."""
+    comment_date = datetime.fromisoformat(
+        duplicate_comment.created_at.replace("Z", "+00:00")
+    )
+
+    # Check for preventing reactions (thumbs down)
+    for reaction in reactions:
+        if reaction.content in ["-1", "confused"]:
+            print(
+                f"Issue #{issue.number}: Has preventing reaction from {reaction.user_login}"
+            )
+            return True
+
+    # Check for any human comment after the duplicate marking
+    for comment in all_comments:
+        comment_date_check = datetime.fromisoformat(
+            comment.created_at.replace("Z", "+00:00")
+        )
+        if comment_date_check > comment_date:
+            if comment.user_type != "Bot":
+                print(
+                    f"Issue #{issue.number}: {comment.user_login} commented after duplicate marking"
+                )
+                return True
+
+    return False
+
+
+def main():
+    """Main entry point for auto-closing duplicate issues."""
+    print("[DEBUG] Starting auto-close duplicates script")
+
+    # Get environment variables
+    token = os.environ.get("GITHUB_TOKEN")
+    if not token:
+        raise ValueError("GITHUB_TOKEN environment variable is required")
+
+    owner = os.environ.get("GITHUB_REPOSITORY_OWNER", "prefecthq")
+    repo = os.environ.get("GITHUB_REPOSITORY_NAME", "fastmcp")
+
+    print(f"[DEBUG] Repository: {owner}/{repo}")
+
+    # Initialize client
+    client = GitHubClient(token, owner, repo)
+
+    # Only fetch issues with the potential-duplicate label
+    all_issues = client.get_potential_duplicate_issues()
+
+    print(f"[DEBUG] Found {len(all_issues)} open issues with potential-duplicate label")
+
+    closed_count = 0
+    cleared_count = 0
+
+    for issue in all_issues:
+        # Get comments for this issue
+        comments = client.get_issue_comments(issue.number)
+
+        # Look for duplicate marking comment
+        duplicate_comment = find_duplicate_comment(comments)
+        if not duplicate_comment:
+            # Label exists but no bot comment - clean up the label
+            print(f"[DEBUG] Issue #{issue.number} has label but no duplicate comment")
+            client.remove_label(issue.number, "potential-duplicate")
+            cleared_count += 1
+            continue
+
+        # Skip if already auto-closed once (someone reopened it intentionally)
+        if was_already_auto_closed(comments):
+            print(
+                f"[DEBUG] Issue #{issue.number} was already auto-closed, removing label"
+            )
+            client.remove_label(issue.number, "potential-duplicate")
+            cleared_count += 1
+            continue
+
+        print(f"[DEBUG] Issue #{issue.number} has duplicate comment")
+
+        # Still in cooldown period - skip for now, check again later
+        if not is_past_cooldown(duplicate_comment):
+            print(f"[DEBUG] Issue #{issue.number} still in 3-day cooldown period")
+            continue
+
+        # Get reactions on the duplicate comment
+        reactions = client.get_comment_reactions(issue.number, duplicate_comment.id)
+
+        # Check for human activity that prevents closure
+        if has_human_activity(issue, duplicate_comment, comments, reactions):
+            print(f"[DEBUG] Issue #{issue.number} has human activity, removing label")
+            client.remove_label(issue.number, "potential-duplicate")
+            cleared_count += 1
+            continue
+
+        # No human activity after cooldown - close as duplicate
+        close_message = (
+            "Closing this issue as a duplicate based on the automated analysis above.\n\n"
+            "The duplicate issues identified contain existing discussions and potential solutions. "
+            "Please add your 👍 to those issues if they match your use case.\n\n"
+            "If this was closed in error, please leave a comment explaining why this is not "
+            "a duplicate and we'll reopen it."
+        )
+
+        if client.close_issue(issue.number, close_message):
+            print(f"[SUCCESS] Closed issue #{issue.number} as duplicate")
+            closed_count += 1
+        else:
+            print(f"[ERROR] Failed to close issue #{issue.number}")
+
+    print(
+        f"[DEBUG] Processing complete. Closed {closed_count} duplicates, "
+        f"cleared {cleared_count} from review"
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/auto_close_needs_mre.py b/scripts/auto_close_needs_mre.py
new file mode 100644
index 0000000..240e83a
--- /dev/null
+++ b/scripts/auto_close_needs_mre.py
@@ -0,0 +1,415 @@
+#!/usr/bin/env python
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "httpx",
+# ]
+# ///
+"""
+Auto-close issues that need MRE (Minimal Reproducible Example).
+
+This script runs on a schedule to automatically close issues that have been
+marked as "needs MRE" and haven't received activity from the issue author
+within 7 days.
+"""
+
+import os
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+import httpx
+
+MAINTAINER_AUTHOR_ASSOCIATIONS = {"OWNER", "MEMBER", "COLLABORATOR"}
+
+
+@dataclass
+class Issue:
+    """Represents a GitHub issue."""
+
+    number: int
+    title: str
+    state: str
+    created_at: str
+    user_id: int
+    user_login: str
+    body: str | None
+    author_association: str
+
+
+@dataclass
+class Comment:
+    """Represents a GitHub comment."""
+
+    id: int
+    body: str
+    created_at: str
+    user_id: int
+    user_login: str
+
+
+@dataclass
+class Event:
+    """Represents a GitHub issue event."""
+
+    event: str
+    created_at: str
+    label_name: str | None
+
+
+class GitHubClient:
+    """Client for interacting with GitHub API."""
+
+    def __init__(self, token: str, owner: str, repo: str):
+        self.token = token
+        self.owner = owner
+        self.repo = repo
+        self.headers = {
+            "Authorization": f"token {token}",
+            "Accept": "application/vnd.github.v3+json",
+        }
+        self.base_url = f"https://api.github.com/repos/{owner}/{repo}"
+
+    def get_issues_with_label(
+        self, label: str, page: int = 1, per_page: int = 100
+    ) -> list[Issue]:
+        """Fetch open issues with a specific label."""
+        url = f"{self.base_url}/issues"
+        issues = []
+
+        with httpx.Client() as client:
+            response = client.get(
+                url,
+                headers=self.headers,
+                params={
+                    "state": "open",
+                    "labels": label,
+                    "per_page": per_page,
+                    "page": page,
+                },
+            )
+
+            if response.status_code != 200:
+                print(f"Error fetching issues: {response.status_code}")
+                return issues
+
+            data = response.json()
+            for item in data:
+                # Skip pull requests
+                if "pull_request" in item:
+                    continue
+
+                issues.append(
+                    Issue(
+                        number=item["number"],
+                        title=item["title"],
+                        state=item["state"],
+                        created_at=item["created_at"],
+                        user_id=item["user"]["id"],
+                        user_login=item["user"]["login"],
+                        body=item.get("body"),
+                        author_association=item.get("author_association", "NONE"),
+                    )
+                )
+
+        return issues
+
+    def get_issue_events(self, issue_number: int) -> list[Event]:
+        """Fetch all events for an issue."""
+        url = f"{self.base_url}/issues/{issue_number}/events"
+        events = []
+
+        with httpx.Client() as client:
+            page = 1
+            while True:
+                response = client.get(
+                    url, headers=self.headers, params={"page": page, "per_page": 100}
+                )
+
+                if response.status_code != 200:
+                    break
+
+                data = response.json()
+                if not data:
+                    break
+
+                for event_data in data:
+                    label_name = None
+                    if event_data["event"] == "labeled" and "label" in event_data:
+                        label_name = event_data["label"]["name"]
+
+                    events.append(
+                        Event(
+                            event=event_data["event"],
+                            created_at=event_data["created_at"],
+                            label_name=label_name,
+                        )
+                    )
+
+                page += 1
+                if page > 10:  # Safety limit
+                    break
+
+        return events
+
+    def get_issue_comments(self, issue_number: int) -> list[Comment]:
+        """Fetch all comments for an issue."""
+        url = f"{self.base_url}/issues/{issue_number}/comments"
+        comments = []
+
+        with httpx.Client() as client:
+            page = 1
+            while True:
+                response = client.get(
+                    url, headers=self.headers, params={"page": page, "per_page": 100}
+                )
+
+                if response.status_code != 200:
+                    break
+
+                data = response.json()
+                if not data:
+                    break
+
+                for comment_data in data:
+                    comments.append(
+                        Comment(
+                            id=comment_data["id"],
+                            body=comment_data["body"],
+                            created_at=comment_data["created_at"],
+                            user_id=comment_data["user"]["id"],
+                            user_login=comment_data["user"]["login"],
+                        )
+                    )
+
+                page += 1
+                if page > 10:  # Safety limit
+                    break
+
+        return comments
+
+    def get_issue_timeline(self, issue_number: int) -> list[dict]:
+        """Fetch timeline events for an issue (includes issue edits)."""
+        url = f"{self.base_url}/issues/{issue_number}/timeline"
+        timeline = []
+
+        with httpx.Client() as client:
+            page = 1
+            while True:
+                response = client.get(
+                    url,
+                    headers={
+                        **self.headers,
+                        "Accept": "application/vnd.github.mockingbird-preview+json",
+                    },
+                    params={"page": page, "per_page": 100},
+                )
+
+                if response.status_code != 200:
+                    break
+
+                data = response.json()
+                if not data:
+                    break
+
+                timeline.extend(data)
+
+                page += 1
+                if page > 10:  # Safety limit
+                    break
+
+        return timeline
+
+    def close_issue(self, issue_number: int, comment: str) -> tuple[bool, bool]:
+        """Close an issue with a comment.
+
+        Closes first, then comments — so a failed comment never leaves
+        a misleading "closing" notice on a still-open issue.
+
+        Returns (closed, commented) so the caller can log partial failures.
+        """
+        # Close the issue first
+        issue_url = f"{self.base_url}/issues/{issue_number}"
+        with httpx.Client() as client:
+            response = client.patch(
+                issue_url, headers=self.headers, json={"state": "closed"}
+            )
+
+            if response.status_code != 200:
+                print(
+                    f"Failed to close issue #{issue_number}: "
+                    f"{response.status_code} {response.text}"
+                )
+                return False, False
+
+        # Then add the comment
+        comment_url = f"{self.base_url}/issues/{issue_number}/comments"
+        with httpx.Client() as client:
+            response = client.post(
+                comment_url, headers=self.headers, json={"body": comment}
+            )
+
+            if response.status_code != 201:
+                print(
+                    f"Issue #{issue_number} was closed but comment failed: "
+                    f"{response.status_code} {response.text}"
+                )
+                return True, False
+
+        return True, True
+
+
+def find_label_application_date(
+    events: list[Event], label_name: str
+) -> datetime | None:
+    """Find when a specific label was applied to an issue."""
+    # Look for the most recent application of this label
+    for event in reversed(events):
+        if event.event == "labeled" and event.label_name == label_name:
+            return datetime.fromisoformat(event.created_at.replace("Z", "+00:00"))
+    return None
+
+
+def has_author_activity_after(
+    issue: Issue,
+    comments: list[Comment],
+    timeline: list[dict],
+    after_date: datetime,
+) -> bool:
+    """Check if the issue author had any activity after a specific date."""
+    # Check for comments from author
+    for comment in comments:
+        if comment.user_id == issue.user_id:
+            comment_date = datetime.fromisoformat(
+                comment.created_at.replace("Z", "+00:00")
+            )
+            if comment_date > after_date:
+                print(
+                    f"Issue #{issue.number}: Author commented after label application"
+                )
+                return True
+
+    # Check for issue body edits from author
+    for event in timeline:
+        if event.get("event") == "renamed" or event.get("event") == "edited":
+            if event.get("actor", {}).get("id") == issue.user_id:
+                event_date = datetime.fromisoformat(
+                    event["created_at"].replace("Z", "+00:00")
+                )
+                if event_date > after_date:
+                    print(
+                        f"Issue #{issue.number}: Author edited issue after label application"
+                    )
+                    return True
+
+    return False
+
+
+def should_close_as_needs_mre(
+    issue: Issue,
+    label_date: datetime,
+    comments: list[Comment],
+    timeline: list[dict],
+) -> bool:
+    """Determine if an issue should be closed for needing an MRE."""
+    if issue.author_association in MAINTAINER_AUTHOR_ASSOCIATIONS:
+        print(f"Issue #{issue.number}: Skipping maintainer-authored issue")
+        return False
+
+    # Check if label is old enough (7 days)
+    seven_days_ago = datetime.now(timezone.utc) - timedelta(days=7)
+
+    if label_date > seven_days_ago:
+        return False
+
+    # Check for author activity after the label was applied
+    if has_author_activity_after(issue, comments, timeline, label_date):
+        return False
+
+    return True
+
+
+def main():
+    """Main entry point for auto-closing needs MRE issues."""
+    print("[DEBUG] Starting auto-close needs MRE script")
+
+    # Get environment variables
+    token = os.environ.get("GITHUB_TOKEN")
+    if not token:
+        raise ValueError("GITHUB_TOKEN environment variable is required")
+
+    owner = os.environ.get("GITHUB_REPOSITORY_OWNER", "prefecthq")
+    repo = os.environ.get("GITHUB_REPOSITORY_NAME", "fastmcp")
+
+    print(f"[DEBUG] Repository: {owner}/{repo}")
+
+    # Initialize client
+    client = GitHubClient(token, owner, repo)
+
+    # Get issues with "needs MRE" label
+    all_issues = []
+    page = 1
+
+    while page <= 20:  # Safety limit
+        issues = client.get_issues_with_label("needs MRE", page=page)
+        if not issues:
+            break
+        all_issues.extend(issues)
+        page += 1
+
+    print(f"[DEBUG] Found {len(all_issues)} open issues with 'needs MRE' label")
+
+    processed_count = 0
+    closed_count = 0
+
+    for issue in all_issues:
+        processed_count += 1
+
+        if processed_count % 10 == 0:
+            print(f"[DEBUG] Processed {processed_count}/{len(all_issues)} issues")
+
+        # Get events to find when label was applied
+        events = client.get_issue_events(issue.number)
+        label_date = find_label_application_date(events, "needs MRE")
+
+        if not label_date:
+            print(
+                f"[DEBUG] Issue #{issue.number}: Could not find label application date"
+            )
+            continue
+
+        print(
+            f"[DEBUG] Issue #{issue.number}: Label applied on {label_date.isoformat()}"
+        )
+
+        # Get comments and timeline
+        comments = client.get_issue_comments(issue.number)
+        timeline = client.get_issue_timeline(issue.number)
+
+        # Check if we should close
+        if should_close_as_needs_mre(issue, label_date, comments, timeline):
+            close_message = (
+                "This issue is being automatically closed because we requested a minimal reproducible example (MRE) "
+                "7 days ago and haven't received a response from the issue author.\n\n"
+                "**If you can provide an MRE**, please add it as a comment and we'll reopen this issue. "
+                "An MRE should be a complete, runnable code snippet that demonstrates the problem.\n\n"
+                "**If this was closed in error**, please leave a comment explaining the situation and we'll reopen it."
+            )
+
+            closed, commented = client.close_issue(issue.number, close_message)
+            if closed:
+                closed_count += 1
+                if commented:
+                    print(f"[SUCCESS] Closed issue #{issue.number} (needs MRE)")
+                else:
+                    print(
+                        f"[WARNING] Closed issue #{issue.number} but "
+                        f"comment was not posted"
+                    )
+            else:
+                print(f"[ERROR] Failed to close issue #{issue.number}")
+
+    print(f"[DEBUG] Processing complete. Closed {closed_count} issues needing MRE")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/benchmark_imports.py b/scripts/benchmark_imports.py
new file mode 100644
index 0000000..6ad1dfe
--- /dev/null
+++ b/scripts/benchmark_imports.py
@@ -0,0 +1,212 @@
+#!/usr/bin/env python
+"""Benchmark import times for fastmcp and its dependency chain.
+
+Each measurement runs in a fresh subprocess so there's no shared module cache.
+Incremental costs are measured by pre-importing dependencies, so we can see
+what each module truly adds.
+
+Usage:
+    uv run python scripts/benchmark_imports.py
+    uv run python scripts/benchmark_imports.py --runs 10
+    uv run python scripts/benchmark_imports.py --json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from dataclasses import dataclass
+
+
+@dataclass
+class BenchmarkCase:
+    label: str
+    stmt: str
+    prereqs: str = ""
+    group: str = ""
+
+
+CASES = [
+    # --- Floor ---
+    BenchmarkCase("pydantic", "import pydantic", group="floor"),
+    BenchmarkCase("mcp", "import mcp", group="floor"),
+    BenchmarkCase(
+        "mcp (server only)", "import mcp.server.lowlevel.server", group="floor"
+    ),
+    # --- Auth stack (incremental over mcp) ---
+    BenchmarkCase(
+        "authlib.jose", "import authlib.jose", prereqs="import mcp", group="auth"
+    ),
+    BenchmarkCase(
+        "cryptography.fernet",
+        "from cryptography.fernet import Fernet",
+        prereqs="import mcp",
+        group="auth",
+    ),
+    BenchmarkCase(
+        "authlib.integrations.httpx_client",
+        "from authlib.integrations.httpx_client import AsyncOAuth2Client",
+        prereqs="import mcp",
+        group="auth",
+    ),
+    BenchmarkCase(
+        "key_value.aio", "import key_value.aio", prereqs="import mcp", group="auth"
+    ),
+    BenchmarkCase(
+        "key_value.aio.stores.filetree",
+        "from key_value.aio.stores.filetree import FileTreeStore",
+        prereqs="import mcp",
+        group="auth",
+    ),
+    BenchmarkCase("beartype", "import beartype", prereqs="import mcp", group="auth"),
+    # --- Docket stack (incremental over mcp) ---
+    BenchmarkCase("redis", "import redis", prereqs="import mcp", group="docket"),
+    BenchmarkCase(
+        "opentelemetry.sdk.metrics",
+        "import opentelemetry.sdk.metrics",
+        prereqs="import mcp",
+        group="docket",
+    ),
+    BenchmarkCase("docket", "import docket", prereqs="import mcp", group="docket"),
+    BenchmarkCase("croniter", "import croniter", prereqs="import mcp", group="docket"),
+    # --- Other deps (incremental over mcp) ---
+    BenchmarkCase("httpx", "import httpx", prereqs="import mcp", group="other"),
+    BenchmarkCase(
+        "starlette",
+        "from starlette.applications import Starlette",
+        prereqs="import mcp",
+        group="other",
+    ),
+    BenchmarkCase(
+        "pydantic_settings",
+        "import pydantic_settings",
+        prereqs="import mcp",
+        group="other",
+    ),
+    BenchmarkCase(
+        "rich.console", "import rich.console", prereqs="import mcp", group="other"
+    ),
+    BenchmarkCase("jsonref", "import jsonref", prereqs="import mcp", group="other"),
+    BenchmarkCase("requests", "import requests", prereqs="import mcp", group="other"),
+    # --- FastMCP (total and incremental) ---
+    BenchmarkCase("fastmcp (total)", "from fastmcp import FastMCP", group="fastmcp"),
+    BenchmarkCase(
+        "fastmcp (over mcp)",
+        "from fastmcp import FastMCP",
+        prereqs="import mcp",
+        group="fastmcp",
+    ),
+    BenchmarkCase(
+        "fastmcp (over mcp+docket)",
+        "from fastmcp import FastMCP",
+        prereqs="import mcp; import docket",
+        group="fastmcp",
+    ),
+    BenchmarkCase(
+        "fastmcp (over mcp+docket+auth deps)",
+        "from fastmcp import FastMCP",
+        prereqs=(
+            "import mcp; import docket; import authlib.jose;"
+            " from cryptography.fernet import Fernet;"
+            " import key_value.aio"
+        ),
+        group="fastmcp",
+    ),
+]
+
+
+def measure_once(stmt: str, prereqs: str) -> float | None:
+    pre = prereqs + "; " if prereqs else ""
+    code = (
+        f"{pre}"
+        "import time as _t; _s=_t.perf_counter(); "
+        f"{stmt}; "
+        "print(f'{(_t.perf_counter()-_s)*1000:.2f}')"
+    )
+    r = subprocess.run(
+        [sys.executable, "-c", code],
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    if r.returncode == 0 and r.stdout.strip():
+        return float(r.stdout.strip())
+    return None
+
+
+def measure(case: BenchmarkCase, runs: int) -> dict[str, float | str | None]:
+    times: list[float] = []
+    for _ in range(runs):
+        t = measure_once(case.stmt, case.prereqs)
+        if t is not None:
+            times.append(t)
+
+    if not times:
+        return {"label": case.label, "group": case.group, "median_ms": None}
+
+    times.sort()
+    median = times[len(times) // 2]
+    return {
+        "label": case.label,
+        "group": case.group,
+        "median_ms": round(median, 1),
+        "min_ms": round(times[0], 1),
+        "max_ms": round(times[-1], 1),
+        "runs": len(times),
+    }
+
+
+def print_table(results: list[dict[str, float | str | None]]) -> None:
+    current_group = None
+    print(f"\n{'Module':<45} {'Median':>8} {'Min':>8} {'Max':>8}")
+    print("-" * 71)
+    for r in results:
+        if r["group"] != current_group:
+            current_group = r["group"]
+            group_labels = {
+                "floor": "--- Unavoidable floor ---",
+                "auth": "--- Auth stack (incremental over mcp) ---",
+                "docket": "--- Docket stack (incremental over mcp) ---",
+                "other": "--- Other deps (incremental over mcp) ---",
+                "fastmcp": "--- FastMCP totals ---",
+            }
+            print(f"\n{group_labels.get(current_group, current_group)}")
+        if r["median_ms"] is not None:
+            print(
+                f"  {r['label']:<43} {r['median_ms']:>7.1f}ms"
+                f" {r['min_ms']:>7.1f}ms {r['max_ms']:>7.1f}ms"
+            )
+        else:
+            print(f"  {r['label']:<43}    error")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Benchmark fastmcp import times")
+    parser.add_argument(
+        "--runs", type=int, default=5, help="Number of runs per measurement (default 5)"
+    )
+    parser.add_argument("--json", action="store_true", help="Output results as JSON")
+    args = parser.parse_args()
+
+    print(f"Benchmarking import times ({args.runs} runs each)...")
+    print(f"Python: {sys.version.split()[0]}")
+    print(f"Executable: {sys.executable}")
+
+    results = []
+    for case in CASES:
+        r = measure(case, args.runs)
+        results.append(r)
+        if not args.json:
+            ms = f"{r['median_ms']:.1f}ms" if r["median_ms"] is not None else "error"
+            print(f"  {case.label}: {ms}")
+
+    if args.json:
+        print(json.dumps(results, indent=2))
+    else:
+        print_table(results)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/skills/fastmcp-client-cli/SKILL.md b/skills/fastmcp-client-cli/SKILL.md
new file mode 100644
index 0000000..ae66a5e
--- /dev/null
+++ b/skills/fastmcp-client-cli/SKILL.md
@@ -0,0 +1,114 @@
+---
+name: fastmcp-client-cli
+description: Query and invoke tools on MCP servers using fastmcp list and fastmcp call. Use when you need to discover what tools a server offers, call tools, or integrate MCP servers into workflows.
+---
+
+# FastMCP CLI: List and Call
+
+Use `fastmcp list` and `fastmcp call` to interact with any MCP server from the command line.
+
+## Listing Tools
+
+```bash
+# Remote server
+fastmcp list http://localhost:8000/mcp
+
+# Local Python file (runs via fastmcp run automatically)
+fastmcp list server.py
+
+# MCPConfig with multiple servers
+fastmcp list mcp.json
+
+# Stdio command (npx, uvx, etc.)
+fastmcp list --command 'npx -y @modelcontextprotocol/server-github'
+
+# Include full input/output schemas
+fastmcp list server.py --input-schema --output-schema
+
+# Machine-readable JSON
+fastmcp list server.py --json
+
+# Include resources and prompts
+fastmcp list server.py --resources --prompts
+```
+
+Default output shows tool signatures and descriptions. Use `--input-schema` or `--output-schema` to include full JSON schemas, `--json` for structured output.
+
+## Calling Tools
+
+```bash
+# Key=value arguments (auto-coerced to correct types)
+fastmcp call server.py greet name=World
+fastmcp call server.py add a=3 b=4
+
+# Single JSON object for complex/nested args
+fastmcp call server.py create_item '{"name": "Widget", "tags": ["a", "b"]}'
+
+# --input-json with key=value overrides
+fastmcp call server.py search --input-json '{"query": "hello", "limit": 5}' limit=10
+
+# JSON output for scripting
+fastmcp call server.py add a=3 b=4 --json
+```
+
+Type coercion is automatic: `limit=5` becomes an integer, `verbose=true` becomes a boolean, based on the tool's input schema.
+
+## Server Targets
+
+All commands accept the same server targets:
+
+| Target | Example |
+|--------|---------|
+| HTTP/HTTPS URL | `http://localhost:8000/mcp` |
+| Python file | `server.py` |
+| MCPConfig JSON | `mcp.json` (must have `mcpServers` key) |
+| Stdio command | `--command 'npx -y @mcp/server'` |
+| Discovered name | `weather` or `source:name` |
+
+Servers configured in editor configs (Claude Desktop, Claude Code, Cursor, Gemini CLI, Goose) or project-level `mcp.json` can be referenced by name. Use `source:name` (e.g. `claude-code:my-server`, `cursor:weather`) to target a specific source. Run `fastmcp discover` to see available names.
+
+For SSE servers, pass `--transport sse`:
+
+```bash
+fastmcp list http://localhost:8000/mcp --transport sse
+```
+
+## Auth
+
+HTTP targets automatically use OAuth (no-ops if the server doesn't require auth). Disable with `--auth none`:
+
+```bash
+fastmcp call http://server/mcp tool --auth none
+```
+
+## Discovering Configured Servers
+
+```bash
+# See all MCP servers in editor/project configs
+fastmcp discover
+
+# Filter by source
+fastmcp discover --source claude-code
+
+# JSON output
+fastmcp discover --json
+```
+
+Scans Claude Desktop, Claude Code, Cursor, Gemini CLI, Goose, and `./mcp.json`. Sources: `claude-desktop`, `claude-code`, `cursor`, `gemini`, `goose`, `project`.
+
+## Workflow Pattern
+
+Discover tools first, then call them:
+
+```bash
+# 1. See what servers are configured
+fastmcp discover
+
+# 2. See what tools a server has
+fastmcp list weather
+
+# 3. Call a tool
+fastmcp call weather get_forecast city=London
+```
+
+If you call a nonexistent tool, FastMCP suggests close matches.
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/apps/__init__.py b/tests/apps/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/apps/test_approval.py b/tests/apps/test_approval.py
new file mode 100644
index 0000000..d061286
--- /dev/null
+++ b/tests/apps/test_approval.py
@@ -0,0 +1,56 @@
+"""Tests for the Approval provider."""
+
+from fastmcp import FastMCP
+from fastmcp.apps.approval import Approval
+
+
+class TestApprovalProvider:
+    async def test_request_approval_returns_structured_content(self):
+        server = FastMCP("test", providers=[Approval()])
+
+        result = await server.call_tool(
+            "request_approval",
+            {"summary": "Delete 47 files"},
+        )
+        assert result.structured_content is not None
+
+    async def test_request_approval_with_details(self):
+        server = FastMCP("test", providers=[Approval()])
+
+        result = await server.call_tool(
+            "request_approval",
+            {"summary": "Deploy to prod", "details": "Version 3.2.0"},
+        )
+        assert result.structured_content is not None
+
+    async def test_tool_visible_to_model(self):
+        server = FastMCP("test", providers=[Approval()])
+
+        tools = await server.list_tools()
+        tool_names = [t.name for t in tools]
+        assert "request_approval" in tool_names
+
+    async def test_custom_name(self):
+        server = FastMCP("test", providers=[Approval(name="Gate")])
+
+        tools = await server.list_tools()
+        tool_names = [t.name for t in tools]
+        assert "request_approval" in tool_names
+
+    async def test_custom_button_text(self):
+        server = FastMCP(
+            "test",
+            providers=[
+                Approval(
+                    approve_text="Ship it",
+                    reject_text="Nope",
+                    title="Deploy Gate",
+                )
+            ],
+        )
+
+        result = await server.call_tool(
+            "request_approval",
+            {"summary": "Deploy v3.2"},
+        )
+        assert result.structured_content is not None
diff --git a/tests/apps/test_choice.py b/tests/apps/test_choice.py
new file mode 100644
index 0000000..2de7b0a
--- /dev/null
+++ b/tests/apps/test_choice.py
@@ -0,0 +1,50 @@
+"""Tests for the Choice provider."""
+
+from fastmcp import FastMCP
+from fastmcp.apps.choice import Choice
+
+
+class TestChoiceProvider:
+    async def test_choose_returns_structured_content(self):
+        server = FastMCP("test", providers=[Choice()])
+
+        result = await server.call_tool(
+            "choose",
+            {"prompt": "Pick one", "options": ["A", "B", "C"]},
+        )
+        assert result.structured_content is not None
+
+    async def test_tool_visible_to_model(self):
+        server = FastMCP("test", providers=[Choice()])
+
+        tools = await server.list_tools()
+        tool_names = [t.name for t in tools]
+        assert "choose" in tool_names
+
+    async def test_custom_name(self):
+        server = FastMCP("test", providers=[Choice(name="Picker")])
+
+        tools = await server.list_tools()
+        tool_names = [t.name for t in tools]
+        assert "choose" in tool_names
+
+    async def test_custom_title(self):
+        server = FastMCP("test", providers=[Choice(title="Select Strategy")])
+
+        result = await server.call_tool(
+            "choose",
+            {"prompt": "How?", "options": ["Fast", "Slow"]},
+        )
+        assert result.structured_content is not None
+
+    async def test_many_options(self):
+        server = FastMCP("test", providers=[Choice()])
+
+        result = await server.call_tool(
+            "choose",
+            {
+                "prompt": "Pick a color",
+                "options": ["Red", "Blue", "Green", "Yellow", "Purple"],
+            },
+        )
+        assert result.structured_content is not None
diff --git a/tests/apps/test_file_upload.py b/tests/apps/test_file_upload.py
new file mode 100644
index 0000000..f8b6553
--- /dev/null
+++ b/tests/apps/test_file_upload.py
@@ -0,0 +1,233 @@
+"""Tests for the FileUpload provider."""
+
+import base64
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.apps.file_upload import FileUpload, _b64_decoded_size
+from fastmcp.server.providers.addressing import hashed_backend_name
+
+
+class TestB64DecodedSize:
+    """Unit tests for the _b64_decoded_size helper."""
+
+    @pytest.mark.parametrize("size", [0, 1, 2, 3, 4, 50, 99, 100, 101, 1000])
+    def test_matches_actual_decode(self, size: int):
+        data = b"x" * size
+        b64 = base64.b64encode(data).decode()
+        assert _b64_decoded_size(b64) == size
+
+    def test_empty_string(self):
+        assert _b64_decoded_size("") == 0
+
+    def test_no_padding(self):
+        # 3 bytes → 4 base64 chars, no padding
+        assert _b64_decoded_size(base64.b64encode(b"abc").decode()) == 3
+
+    def test_one_pad(self):
+        # 2 bytes → 4 base64 chars with 1 '='
+        assert _b64_decoded_size(base64.b64encode(b"ab").decode()) == 2
+
+    def test_two_pads(self):
+        # 1 byte → 4 base64 chars with 2 '='
+        assert _b64_decoded_size(base64.b64encode(b"a").decode()) == 1
+
+
+def _make_file(
+    name: str = "test.txt",
+    content: str = "hello world",
+    mime_type: str = "text/plain",
+) -> dict:
+    data = base64.b64encode(content.encode()).decode()
+    return {
+        "name": name,
+        "size": len(content),
+        "type": mime_type,
+        "data": data,
+    }
+
+
+class TestFileUploadProvider:
+    async def test_basic_store_and_list(self):
+        server = FastMCP("test", providers=[FileUpload()])
+        files = [_make_file()]
+
+        result = await server.call_tool(
+            hashed_backend_name("Files", "store_files"), {"files": files}
+        )
+        text = result.content[0].text  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+        assert "test.txt" in text
+
+        result = await server.call_tool("list_files", {})
+        text = result.content[0].text  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+        assert "test.txt" in text
+
+    async def test_read_text_file(self):
+        server = FastMCP("test", providers=[FileUpload()])
+        files = [_make_file(content="DON'T PANIC")]
+
+        await server.call_tool(
+            hashed_backend_name("Files", "store_files"), {"files": files}
+        )
+
+        result = await server.call_tool("read_file", {"name": "test.txt"})
+        text = result.content[0].text  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+        assert "DON'T PANIC" in text
+
+    async def test_read_binary_file(self):
+        server = FastMCP("test", providers=[FileUpload()])
+        data = base64.b64encode(b"\x00\x01\x02\xff").decode()
+        files = [{"name": "image.png", "size": 4, "type": "image/png", "data": data}]
+
+        await server.call_tool(
+            hashed_backend_name("Files", "store_files"), {"files": files}
+        )
+
+        result = await server.call_tool("read_file", {"name": "image.png"})
+        text = result.content[0].text  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+        assert "content_base64" in text
+
+    async def test_read_missing_file_raises(self):
+        server = FastMCP("test", providers=[FileUpload()])
+
+        with pytest.raises(Exception, match="not found"):
+            await server.call_tool("read_file", {"name": "nope.txt"})
+
+    async def test_multiple_files(self):
+        server = FastMCP("test", providers=[FileUpload()])
+        files = [
+            _make_file("a.txt", "aaa"),
+            _make_file("b.txt", "bbb"),
+        ]
+
+        await server.call_tool(
+            hashed_backend_name("Files", "store_files"), {"files": files}
+        )
+
+        result = await server.call_tool("list_files", {})
+        text = result.content[0].text  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+        assert "a.txt" in text
+        assert "b.txt" in text
+
+    async def test_overwrite_file(self):
+        server = FastMCP("test", providers=[FileUpload()])
+
+        await server.call_tool(
+            hashed_backend_name("Files", "store_files"),
+            {"files": [_make_file(content="version 1")]},
+        )
+        await server.call_tool(
+            hashed_backend_name("Files", "store_files"),
+            {"files": [_make_file(content="version 2")]},
+        )
+
+        result = await server.call_tool("read_file", {"name": "test.txt"})
+        text = result.content[0].text  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+        assert "version 2" in text
+
+    async def test_custom_name(self):
+        server = FastMCP("test", providers=[FileUpload(name="Uploads")])
+
+        tools = await server.list_tools()
+        tool_names = [t.name for t in tools]
+        assert "file_manager" in tool_names
+
+        # The hash uses the app's actual name ("Uploads"), not the default.
+        files = [_make_file()]
+        result = await server.call_tool(
+            hashed_backend_name("Uploads", "store_files"), {"files": files}
+        )
+        text = result.content[0].text  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+        assert "test.txt" in text
+
+    async def test_ui_tool_visible_backend_hidden(self):
+        server = FastMCP("test", providers=[FileUpload()])
+
+        tools = await server.list_tools()
+        tool_names = [t.name for t in tools]
+
+        assert "file_manager" in tool_names
+        assert "list_files" in tool_names
+        assert "read_file" in tool_names
+        assert "store_files" not in tool_names
+
+    async def test_max_file_size_enforced_server_side(self):
+        server = FastMCP("test", providers=[FileUpload(max_file_size=100)])
+        big_file = _make_file(content="x" * 200)
+
+        with pytest.raises(Exception, match="exceeds max size"):
+            await server.call_tool(
+                hashed_backend_name("Files", "store_files"), {"files": [big_file]}
+            )
+
+    async def test_max_file_size_checks_actual_data_not_reported_size(self):
+        """Size limit should be enforced on actual base64 payload, not the
+        client-reported ``size`` field which can be spoofed."""
+        server = FastMCP("test", providers=[FileUpload(max_file_size=100)])
+
+        big_content = "x" * 200
+        big_b64 = base64.b64encode(big_content.encode()).decode()
+        spoofed_file = {
+            "name": "spoofed.bin",
+            "size": 1,  # lies about size
+            "type": "application/octet-stream",
+            "data": big_b64,
+        }
+
+        with pytest.raises(Exception, match="exceeds max size"):
+            await server.call_tool(
+                hashed_backend_name("Files", "store_files"), {"files": [spoofed_file]}
+            )
+
+
+class TestFileUploadSubclass:
+    async def test_custom_storage(self):
+        """Subclassing lets users provide their own persistence."""
+        stored: dict[str, dict] = {}
+
+        class MemoryUpload(FileUpload):
+            def on_store(self, files: list[dict], ctx) -> list[dict]:
+                for f in files:
+                    stored[f["name"]] = f
+                return [
+                    {
+                        "name": f["name"],
+                        "type": f["type"],
+                        "size": f["size"],
+                        "size_display": "?",
+                        "uploaded_at": "now",
+                    }
+                    for f in files
+                ]
+
+            def on_list(self, ctx) -> list[dict]:
+                return [
+                    {
+                        "name": f["name"],
+                        "type": f["type"],
+                        "size": f["size"],
+                        "size_display": "?",
+                        "uploaded_at": "now",
+                    }
+                    for f in stored.values()
+                ]
+
+            def on_read(self, name: str, ctx) -> dict:
+                if name not in stored:
+                    raise ValueError(f"Not found: {name}")
+                f = stored[name]
+                return {"name": f["name"], "content": "custom read"}
+
+        server = FastMCP("test", providers=[MemoryUpload()])
+        files = [_make_file()]
+
+        await server.call_tool(
+            hashed_backend_name("Files", "store_files"), {"files": files}
+        )
+
+        assert "test.txt" in stored
+
+        result = await server.call_tool("read_file", {"name": "test.txt"})
+        text = result.content[0].text  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+        assert "custom read" in text
diff --git a/tests/apps/test_form.py b/tests/apps/test_form.py
new file mode 100644
index 0000000..6610396
--- /dev/null
+++ b/tests/apps/test_form.py
@@ -0,0 +1,225 @@
+"""Tests for the FormInput provider."""
+
+import json
+
+import pydantic
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.apps.form import (
+    _FORM_SUPPORTS_DEFAULTS,
+    FormInput,
+    _backfill_boolean_defaults,
+)
+from fastmcp.server.providers.addressing import hashed_backend_name
+
+
+class Contact(pydantic.BaseModel):
+    name: str
+    email: str
+    phone: str | None = None
+
+
+class NoteForm(pydantic.BaseModel):
+    title: str
+    content: str
+    archived: bool = False
+
+
+class TestFormInputProvider:
+    async def test_collect_returns_structured_content(self):
+        server = FastMCP("test", providers=[FormInput(model=Contact)])
+
+        result = await server.call_tool(
+            "collect_contact",
+            {"prompt": "Enter your details"},
+        )
+        assert result.structured_content is not None
+
+    async def test_tool_name_derived_from_model(self):
+        server = FastMCP("test", providers=[FormInput(model=Contact)])
+
+        tools = await server.list_tools()
+        tool_names = [t.name for t in tools]
+        assert "collect_contact" in tool_names
+
+    async def test_custom_tool_name(self):
+        server = FastMCP(
+            "test",
+            providers=[FormInput(model=Contact, tool_name="new_contact")],
+        )
+
+        tools = await server.list_tools()
+        tool_names = [t.name for t in tools]
+        assert "new_contact" in tool_names
+
+    async def test_submit_validates_and_returns_json(self):
+        server = FastMCP("test", providers=[FormInput(model=Contact)])
+
+        result = await server.call_tool(
+            hashed_backend_name("Contact", "submit_form"),
+            {"data": {"name": "Alice", "email": "alice@example.com"}},
+        )
+        text = result.content[0].text  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+        parsed = json.loads(text)
+        assert parsed["name"] == "Alice"
+        assert parsed["email"] == "alice@example.com"
+        assert parsed["phone"] is None
+
+    async def test_submit_with_callback(self):
+        saved: list[Contact] = []
+
+        def on_submit(contact: Contact) -> str:
+            saved.append(contact)
+            return f"Saved {contact.name}"
+
+        server = FastMCP(
+            "test",
+            providers=[FormInput(model=Contact, on_submit=on_submit)],
+        )
+
+        result = await server.call_tool(
+            hashed_backend_name("Contact", "submit_form"),
+            {"data": {"name": "Bob", "email": "bob@example.com"}},
+        )
+        text = result.content[0].text  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+        assert "Saved Bob" in text
+        assert len(saved) == 1
+        assert saved[0].name == "Bob"
+
+    async def test_backend_tool_hidden(self):
+        server = FastMCP("test", providers=[FormInput(model=Contact)])
+
+        tools = await server.list_tools()
+        tool_names = [t.name for t in tools]
+        assert "_submit_form" not in tool_names
+
+    async def test_submit_boolean_false_omitted(self):
+        """Unchecked checkboxes omit the field; submit_form should still succeed."""
+        server = FastMCP("test", providers=[FormInput(model=NoteForm)])
+
+        result = await server.call_tool(
+            hashed_backend_name("NoteForm", "submit_form"),
+            {"data": {"title": "My Note", "content": "Hello"}},
+        )
+        text = result.content[0].text  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+        parsed = json.loads(text)
+        assert parsed["title"] == "My Note"
+        assert parsed["archived"] is False
+
+    async def test_submit_boolean_true_preserved(self):
+        """When a boolean field is explicitly True, it should be preserved."""
+        server = FastMCP("test", providers=[FormInput(model=NoteForm)])
+
+        result = await server.call_tool(
+            hashed_backend_name("NoteForm", "submit_form"),
+            {"data": {"title": "My Note", "content": "Hello", "archived": True}},
+        )
+        text = result.content[0].text  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+        parsed = json.loads(text)
+        assert parsed["archived"] is True
+
+    async def test_submit_no_data_does_not_crash(self):
+        """When data is omitted entirely, the tool should not raise a missing argument error."""
+        server = FastMCP("test", providers=[FormInput(model=NoteForm)])
+
+        # Should reach model validation (not crash with "missing required argument"
+        # for the data parameter itself). Pydantic will still reject missing
+        # required fields like title/content, but that's expected.
+        with pytest.raises(pydantic.ValidationError, match="title"):
+            await server.call_tool(hashed_backend_name("NoteForm", "submit_form"), {})
+
+    async def test_multiple_models(self):
+        class Address(pydantic.BaseModel):
+            street: str
+            city: str
+
+        server = FastMCP(
+            "test",
+            providers=[
+                FormInput(model=Contact),
+                FormInput(model=Address),
+            ],
+        )
+
+        tools = await server.list_tools()
+        tool_names = [t.name for t in tools]
+        assert "collect_contact" in tool_names
+        assert "collect_address" in tool_names
+
+
+class TestCollectInputDefault:
+    """The `default` arg pre-fills the form for the user to confirm/edit."""
+
+    @pytest.mark.skipif(
+        not _FORM_SUPPORTS_DEFAULTS,
+        reason="prefab-ui<0.19.1 does not support Form.from_model(defaults=...)",
+    )
+    async def test_default_prefills_form_fields(self):
+        server = FastMCP("test", providers=[FormInput(model=Contact)])
+
+        result = await server.call_tool(
+            "collect_contact",
+            {
+                "prompt": "Confirm your details",
+                "default": {"name": "Alice", "email": "alice@example.com"},
+            },
+        )
+        # The form view should serialize with the prefilled values.
+        payload = json.dumps(result.structured_content)
+        assert "Alice" in payload
+        assert "alice@example.com" in payload
+
+    async def test_default_absent_still_renders_blank_form(self):
+        """Sanity: omitting `default` keeps the existing blank-form behavior."""
+        server = FastMCP("test", providers=[FormInput(model=Contact)])
+
+        result = await server.call_tool(
+            "collect_contact",
+            {"prompt": "Enter your details"},
+        )
+        assert result.structured_content is not None
+
+    async def test_default_silent_on_older_prefab(self):
+        """When the sniff says False, `default` is accepted but no-ops.
+
+        This test's real value is that `default` is part of the tool
+        signature regardless of prefab version, so agents can always pass
+        it without runtime errors.
+        """
+        server = FastMCP("test", providers=[FormInput(model=Contact)])
+
+        result = await server.call_tool(
+            "collect_contact",
+            {
+                "prompt": "Confirm your details",
+                "default": {"name": "Bob"},
+            },
+        )
+        assert result.structured_content is not None
+
+
+class TestBackfillBooleanDefaults:
+    def test_missing_bool_with_default_gets_backfilled(self):
+        data = {"title": "Note", "content": "Body"}
+        result = _backfill_boolean_defaults(NoteForm, data)
+        assert result["archived"] is False
+
+    def test_present_bool_not_overwritten(self):
+        data = {"title": "Note", "content": "Body", "archived": True}
+        result = _backfill_boolean_defaults(NoteForm, data)
+        assert result["archived"] is True
+
+    def test_required_bool_without_default_gets_false(self):
+        class FormWithRequiredBool(pydantic.BaseModel):
+            name: str
+            active: bool
+
+        data = {"name": "Test"}
+        result = _backfill_boolean_defaults(FormWithRequiredBool, data)
+        assert result["active"] is False
+
+    def test_non_bool_fields_untouched(self):
+        data = {"title": "Note"}
+        result = _backfill_boolean_defaults(NoteForm, data)
+        assert "content" not in result
diff --git a/tests/cli/__init__.py b/tests/cli/__init__.py
new file mode 100644
index 0000000..6bfb427
--- /dev/null
+++ b/tests/cli/__init__.py
@@ -0,0 +1 @@
+"""CLI test package."""
diff --git a/tests/cli/test_cimd_cli.py b/tests/cli/test_cimd_cli.py
new file mode 100644
index 0000000..301c440
--- /dev/null
+++ b/tests/cli/test_cimd_cli.py
@@ -0,0 +1,208 @@
+"""Tests for the CIMD CLI commands (create and validate)."""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from pydantic import AnyHttpUrl
+
+from fastmcp.cli.cimd import create_command, validate_command
+from fastmcp.server.auth.cimd import CIMDDocument, CIMDFetchError, CIMDValidationError
+
+
+class TestCIMDCreateCommand:
+    """Tests for `fastmcp auth cimd create`."""
+
+    def test_minimal_output(self, capsys: pytest.CaptureFixture[str]):
+        create_command(
+            name="Test App",
+            redirect_uri=["http://localhost:*/callback"],
+        )
+        doc = json.loads(capsys.readouterr().out)
+        assert doc["client_name"] == "Test App"
+        assert doc["redirect_uris"] == ["http://localhost:*/callback"]
+        assert doc["token_endpoint_auth_method"] == "none"
+        assert doc["grant_types"] == ["authorization_code"]
+        assert doc["response_types"] == ["code"]
+        # Placeholder client_id
+        assert "YOUR-DOMAIN" in doc["client_id"]
+
+    def test_with_client_id(self, capsys: pytest.CaptureFixture[str]):
+        create_command(
+            name="Test App",
+            redirect_uri=["http://localhost:*/callback"],
+            client_id="https://myapp.example.com/client.json",
+        )
+        doc = json.loads(capsys.readouterr().out)
+        assert doc["client_id"] == "https://myapp.example.com/client.json"
+
+    def test_with_output_file(self, tmp_path):
+        output_file = tmp_path / "client.json"
+        create_command(
+            name="Test App",
+            redirect_uri=["http://localhost:*/callback"],
+            client_id="https://example.com/client.json",
+            output=str(output_file),
+        )
+        doc = json.loads(output_file.read_text())
+        assert doc["client_id"] == "https://example.com/client.json"
+        assert doc["client_name"] == "Test App"
+
+    def test_relative_path_resolved(self, tmp_path, monkeypatch):
+        """Relative paths should be resolved against cwd."""
+        monkeypatch.chdir(tmp_path)
+        create_command(
+            name="Test App",
+            redirect_uri=["http://localhost:*/callback"],
+            output="./subdir/client.json",
+        )
+        resolved = tmp_path / "subdir" / "client.json"
+        assert resolved.exists()
+        doc = json.loads(resolved.read_text())
+        assert doc["client_name"] == "Test App"
+
+    def test_with_scope(self, capsys: pytest.CaptureFixture[str]):
+        create_command(
+            name="Test App",
+            redirect_uri=["http://localhost:*/callback"],
+            scope="read write",
+        )
+        doc = json.loads(capsys.readouterr().out)
+        assert doc["scope"] == "read write"
+
+    def test_with_client_uri(self, capsys: pytest.CaptureFixture[str]):
+        create_command(
+            name="Test App",
+            redirect_uri=["http://localhost:*/callback"],
+            client_uri="https://example.com",
+        )
+        doc = json.loads(capsys.readouterr().out)
+        assert doc["client_uri"] == "https://example.com"
+
+    def test_with_logo_uri(self, capsys: pytest.CaptureFixture[str]):
+        create_command(
+            name="Test App",
+            redirect_uri=["http://localhost:*/callback"],
+            logo_uri="https://example.com/logo.png",
+        )
+        doc = json.loads(capsys.readouterr().out)
+        assert doc["logo_uri"] == "https://example.com/logo.png"
+
+    def test_multiple_redirect_uris(self, capsys: pytest.CaptureFixture[str]):
+        create_command(
+            name="Test App",
+            redirect_uri=[
+                "http://localhost:*/callback",
+                "https://myapp.example.com/callback",
+            ],
+        )
+        doc = json.loads(capsys.readouterr().out)
+        assert len(doc["redirect_uris"]) == 2
+
+    def test_no_pretty(self, capsys: pytest.CaptureFixture[str]):
+        create_command(
+            name="Test App",
+            redirect_uri=["http://localhost:*/callback"],
+            pretty=False,
+        )
+        output = capsys.readouterr().out.strip()
+        # Compact JSON has no newlines within the object
+        assert "\n" not in output
+        doc = json.loads(output)
+        assert doc["client_name"] == "Test App"
+
+    def test_placeholder_warning_on_stderr(self, capsys: pytest.CaptureFixture[str]):
+        """When outputting to stdout with no --client-id, warning goes to stderr."""
+        create_command(
+            name="Test App",
+            redirect_uri=["http://localhost:*/callback"],
+        )
+        captured = capsys.readouterr()
+        # stdout has valid JSON
+        json.loads(captured.out)
+        # stderr has the warning (Rich Console writes to stderr)
+        assert "placeholder" in captured.err
+
+    def test_no_warning_with_client_id(self, capsys: pytest.CaptureFixture[str]):
+        """No placeholder warning when --client-id is provided."""
+        create_command(
+            name="Test App",
+            redirect_uri=["http://localhost:*/callback"],
+            client_id="https://example.com/client.json",
+        )
+        captured = capsys.readouterr()
+        assert "placeholder" not in captured.err
+
+    def test_optional_fields_omitted_when_none(
+        self, capsys: pytest.CaptureFixture[str]
+    ):
+        """Optional fields like scope, client_uri, logo_uri are omitted if not given."""
+        create_command(
+            name="Test App",
+            redirect_uri=["http://localhost:*/callback"],
+        )
+        doc = json.loads(capsys.readouterr().out)
+        assert "scope" not in doc
+        assert "client_uri" not in doc
+        assert "logo_uri" not in doc
+
+
+class TestCIMDValidateCommand:
+    """Tests for `fastmcp auth cimd validate`."""
+
+    def test_invalid_url_format(self, capsys: pytest.CaptureFixture[str]):
+        with pytest.raises(SystemExit, match="1"):
+            validate_command("http://insecure.com/client.json")
+        captured = capsys.readouterr()
+        assert "Invalid CIMD URL" in captured.out
+
+    def test_root_path_rejected(self, capsys: pytest.CaptureFixture[str]):
+        with pytest.raises(SystemExit, match="1"):
+            validate_command("https://example.com/")
+        captured = capsys.readouterr()
+        assert "Invalid CIMD URL" in captured.out
+
+    def test_success(self, capsys: pytest.CaptureFixture[str]):
+        mock_doc = CIMDDocument(
+            client_id=AnyHttpUrl("https://myapp.example.com/client.json"),
+            client_name="Test App",
+            redirect_uris=["http://localhost:*/callback"],
+            token_endpoint_auth_method="none",
+            grant_types=["authorization_code"],
+            response_types=["code"],
+        )
+        with patch.object(CIMDDocument, "__init__", return_value=None):
+            pass
+        mock_fetch = AsyncMock(return_value=mock_doc)
+        with patch(
+            "fastmcp.cli.cimd.CIMDFetcher.fetch",
+            mock_fetch,
+        ):
+            validate_command("https://myapp.example.com/client.json")
+        captured = capsys.readouterr()
+        assert "Valid CIMD document" in captured.out
+        assert "Test App" in captured.out
+
+    def test_fetch_error(self, capsys: pytest.CaptureFixture[str]):
+        mock_fetch = AsyncMock(side_effect=CIMDFetchError("Connection refused"))
+        with patch(
+            "fastmcp.cli.cimd.CIMDFetcher.fetch",
+            mock_fetch,
+        ):
+            with pytest.raises(SystemExit, match="1"):
+                validate_command("https://myapp.example.com/client.json")
+        captured = capsys.readouterr()
+        assert "Failed to fetch" in captured.out
+
+    def test_validation_error(self, capsys: pytest.CaptureFixture[str]):
+        mock_fetch = AsyncMock(side_effect=CIMDValidationError("client_id mismatch"))
+        with patch(
+            "fastmcp.cli.cimd.CIMDFetcher.fetch",
+            mock_fetch,
+        ):
+            with pytest.raises(SystemExit, match="1"):
+                validate_command("https://myapp.example.com/client.json")
+        captured = capsys.readouterr()
+        assert "Validation error" in captured.out
diff --git a/tests/cli/test_cli.py b/tests/cli/test_cli.py
new file mode 100644
index 0000000..7100683
--- /dev/null
+++ b/tests/cli/test_cli.py
@@ -0,0 +1,638 @@
+import subprocess
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+import pytest
+
+from fastmcp.cli.cli import _parse_env_var, app
+
+
+class TestMainCLI:
+    """Test the main CLI application."""
+
+    def test_app_exists(self):
+        """Test that the main app is properly configured."""
+        # app.name is a tuple in cyclopts
+        assert "fastmcp" in app.name
+        assert "FastMCP" in app.help
+        # Just check that version exists, not the specific value
+        assert hasattr(app, "version")
+
+    def test_parse_env_var_valid(self):
+        """Test parsing valid environment variables."""
+        key, value = _parse_env_var("KEY=value")
+        assert key == "KEY"
+        assert value == "value"
+
+        key, value = _parse_env_var("COMPLEX_KEY=complex=value=with=equals")
+        assert key == "COMPLEX_KEY"
+        assert value == "complex=value=with=equals"
+
+    def test_parse_env_var_invalid(self):
+        """Test parsing invalid environment variables exits."""
+        with pytest.raises(SystemExit) as exc_info:
+            _parse_env_var("INVALID_FORMAT")
+        assert isinstance(exc_info.value, SystemExit)
+        assert exc_info.value.code == 1
+
+
+class TestVersionCommand:
+    """Test the version command."""
+
+    @patch("fastmcp.cli.cli.check_for_newer_version", return_value=None)
+    def test_version_command_execution(self, mock_check):
+        """Test that version command executes properly."""
+        # The version command should execute without raising SystemExit
+        command, bound, _ = app.parse_args(["version"])
+        command()  # Should not raise
+
+    def test_version_command_parsing(self):
+        """Test that the version command parses arguments correctly."""
+        command, bound, _ = app.parse_args(["version"])
+        assert callable(command)
+        assert command.__name__ == "version"  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+        # Default arguments aren't included in bound.arguments
+        assert bound.arguments == {}
+
+    def test_version_command_with_copy_flag(self):
+        """Test that the version command parses --copy flag correctly."""
+        command, bound, _ = app.parse_args(["version", "--copy"])
+        assert callable(command)
+        assert command.__name__ == "version"  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+        assert bound.arguments == {"copy": True}
+
+    @patch("fastmcp.cli.cli.pyperclip.copy")
+    @patch("fastmcp.cli.cli.console")
+    def test_version_command_copy_functionality(
+        self, mock_console, mock_pyperclip_copy
+    ):
+        """Test that the version command copies to clipboard when --copy is used."""
+        command, bound, _ = app.parse_args(["version", "--copy"])
+        command(**bound.arguments)
+
+        # Verify pyperclip.copy was called with plain text format
+        mock_pyperclip_copy.assert_called_once()
+        copied_text = mock_pyperclip_copy.call_args[0][0]
+
+        # Verify the copied text contains expected version info keys in plain text
+        assert "FastMCP version:" in copied_text
+        assert "MCP version:" in copied_text
+        assert "Python version:" in copied_text
+        assert "Platform:" in copied_text
+        assert "FastMCP root path:" in copied_text
+
+        # Verify no ANSI escape codes (terminal control characters)
+        assert "\x1b[" not in copied_text
+        mock_console.print.assert_called_with(
+            "[green]✓[/green] Version information copied to clipboard"
+        )
+
+
+class TestDevCommand:
+    """Test the dev command."""
+
+    def test_dev_inspector_command_parsing(self):
+        """Test that dev inspector command can be parsed with various options."""
+        # Test basic parsing
+        command, bound, _ = app.parse_args(["dev", "inspector", "server.py"])
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+
+        # Test with options
+        command, bound, _ = app.parse_args(
+            [
+                "dev",
+                "inspector",
+                "server.py",
+                "--with",
+                "package1",
+                "--inspector-version",
+                "1.0.0",
+                "--ui-port",
+                "3000",
+            ]
+        )
+        assert bound.arguments["with_packages"] == ["package1"]
+        assert bound.arguments["inspector_version"] == "1.0.0"
+        assert bound.arguments["ui_port"] == 3000
+
+    def test_dev_inspector_command_parsing_with_new_options(self):
+        """Test dev inspector command parsing with new uv options."""
+        command, bound, _ = app.parse_args(
+            [
+                "dev",
+                "inspector",
+                "server.py",
+                "--python",
+                "3.10",
+                "--project",
+                "/workspace",
+                "--with-requirements",
+                "dev-requirements.txt",
+                "--with",
+                "pytest",
+            ]
+        )
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        assert bound.arguments["python"] == "3.10"
+        assert bound.arguments["project"] == Path("/workspace")
+        assert bound.arguments["with_requirements"] == Path("dev-requirements.txt")
+        assert bound.arguments["with_packages"] == ["pytest"]
+
+
+class TestRunCommand:
+    """Test the run command."""
+
+    def test_run_command_parsing_basic(self):
+        """Test basic run command parsing."""
+        command, bound, _ = app.parse_args(["run", "server.py"])
+
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        # Cyclopts only includes non-default values
+        assert "transport" not in bound.arguments
+        assert "host" not in bound.arguments
+        assert "port" not in bound.arguments
+        assert "path" not in bound.arguments
+        assert "log_level" not in bound.arguments
+        assert "no_banner" not in bound.arguments
+
+    def test_run_command_parsing_with_options(self):
+        """Test run command parsing with various options."""
+        command, bound, _ = app.parse_args(
+            [
+                "run",
+                "server.py",
+                "--transport",
+                "http",
+                "--host",
+                "localhost",
+                "--port",
+                "8080",
+                "--path",
+                "/v1/mcp",
+                "--log-level",
+                "DEBUG",
+                "--no-banner",
+            ]
+        )
+
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        assert bound.arguments["transport"] == "http"
+        assert bound.arguments["host"] == "localhost"
+        assert bound.arguments["port"] == 8080
+        assert bound.arguments["path"] == "/v1/mcp"
+        assert bound.arguments["log_level"] == "DEBUG"
+        assert bound.arguments["no_banner"] is True
+
+    def test_run_command_parsing_partial_options(self):
+        """Test run command parsing with only some options."""
+        command, bound, _ = app.parse_args(
+            [
+                "run",
+                "server.py",
+                "--transport",
+                "http",
+                "--no-banner",
+            ]
+        )
+
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        assert bound.arguments["transport"] == "http"
+        assert bound.arguments["no_banner"] is True
+        # Other options should not be present
+        assert "host" not in bound.arguments
+        assert "port" not in bound.arguments
+        assert "log_level" not in bound.arguments
+        assert "path" not in bound.arguments
+
+    def test_run_command_parsing_with_new_options(self):
+        """Test run command parsing with new uv options."""
+        command, bound, _ = app.parse_args(
+            [
+                "run",
+                "server.py",
+                "--python",
+                "3.11",
+                "--with",
+                "pandas",
+                "--with",
+                "numpy",
+                "--project",
+                "/path/to/project",
+                "--with-requirements",
+                "requirements.txt",
+            ]
+        )
+
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        assert bound.arguments["python"] == "3.11"
+        assert bound.arguments["with_packages"] == ["pandas", "numpy"]
+        assert bound.arguments["project"] == Path("/path/to/project")
+        assert bound.arguments["with_requirements"] == Path("requirements.txt")
+
+    def test_run_command_transport_aliases(self):
+        """Test that both 'http' and 'streamable-http' are accepted as valid transport options."""
+        # Test with 'http' transport
+        command, bound, _ = app.parse_args(
+            [
+                "run",
+                "server.py",
+                "--transport",
+                "http",
+            ]
+        )
+        assert command is not None
+        assert bound.arguments["transport"] == "http"
+
+        # Test with 'streamable-http' transport
+        command, bound, _ = app.parse_args(
+            [
+                "run",
+                "server.py",
+                "--transport",
+                "streamable-http",
+            ]
+        )
+        assert command is not None
+        assert bound.arguments["transport"] == "streamable-http"
+
+    def test_run_command_parsing_with_server_args(self):
+        """Test run command parsing with server arguments after --."""
+        command, bound, _ = app.parse_args(
+            [
+                "run",
+                "server.py",
+                "--",
+                "--config",
+                "test.json",
+                "--debug",
+            ]
+        )
+
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        # Server args after -- are captured as positional arguments in bound.args
+        assert bound.args == ("server.py", "--config", "test.json", "--debug")
+
+    def test_run_command_parsing_with_mixed_args(self):
+        """Test run command parsing with both FastMCP options and server args."""
+        command, bound, _ = app.parse_args(
+            [
+                "run",
+                "server.py",
+                "--transport",
+                "http",
+                "--port",
+                "8080",
+                "--",
+                "--server-port",
+                "9090",
+                "--debug",
+            ]
+        )
+
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        assert bound.arguments["transport"] == "http"
+        assert bound.arguments["port"] == 8080
+        # Server args after -- are captured separately from FastMCP options
+        assert bound.args == ("server.py", "--server-port", "9090", "--debug")
+
+    def test_run_command_parsing_with_positional_server_args(self):
+        """Test run command parsing with positional server arguments."""
+        command, bound, _ = app.parse_args(
+            [
+                "run",
+                "server.py",
+                "--",
+                "arg1",
+                "arg2",
+                "--flag",
+            ]
+        )
+
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        # Positional args and flags after -- are all captured
+        assert bound.args == ("server.py", "arg1", "arg2", "--flag")
+
+    def test_run_command_parsing_server_args_require_delimiter(self):
+        """Test that server args without -- delimiter are rejected."""
+        # Should fail because --config is not a recognized FastMCP option
+        with pytest.raises(SystemExit):
+            app.parse_args(
+                [
+                    "run",
+                    "server.py",
+                    "--config",
+                    "test.json",
+                ]
+            )
+
+    def test_run_command_parsing_project_flag(self):
+        """Test run command parsing with --project flag."""
+        command, bound, _ = app.parse_args(
+            [
+                "run",
+                "server.py",
+                "--project",
+                "./test-env",
+            ]
+        )
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        assert bound.arguments["project"] == Path("./test-env")
+
+    def test_run_command_parsing_skip_source_flag(self):
+        """Test run command parsing with --skip-source flag."""
+        command, bound, _ = app.parse_args(
+            [
+                "run",
+                "server.py",
+                "--skip-source",
+            ]
+        )
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        assert bound.arguments["skip_source"] is True
+
+    def test_run_command_parsing_project_and_skip_source(self):
+        """Test run command parsing with --project and --skip-source flags."""
+        command, bound, _ = app.parse_args(
+            [
+                "run",
+                "server.py",
+                "--project",
+                "./test-env",
+                "--skip-source",
+            ]
+        )
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        assert bound.arguments["project"] == Path("./test-env")
+        assert bound.arguments["skip_source"] is True
+
+    def test_show_server_banner_setting(self):
+        """Test that show_server_banner setting works with environment variable."""
+        import os
+        from unittest import mock
+
+        from fastmcp.settings import Settings
+
+        # Test default (banner shown)
+        settings = Settings()
+        assert settings.show_server_banner is True
+
+        # Test with env var set to false (banner hidden)
+        with mock.patch.dict(os.environ, {"FASTMCP_SHOW_SERVER_BANNER": "false"}):
+            settings = Settings()
+            assert settings.show_server_banner is False
+
+        # Test CLI precedence logic (simulated)
+        with mock.patch.dict(os.environ, {"FASTMCP_SHOW_SERVER_BANNER": "true"}):
+            settings = Settings()
+            # CLI --no-banner flag would override
+            cli_no_banner = True
+            final = cli_no_banner if cli_no_banner else not settings.show_server_banner
+            assert final is True  # Banner suppressed by CLI flag
+
+
+class TestWindowsSpecific:
+    """Test Windows-specific functionality."""
+
+    @patch("subprocess.run")
+    def test_get_npx_command_windows_cmd(self, mock_run):
+        """Test npx command detection on Windows with npx.cmd."""
+        from fastmcp.cli.cli import _get_npx_command
+
+        with patch("sys.platform", "win32"):
+            # First call succeeds with npx.cmd
+            mock_run.return_value = Mock(returncode=0)
+
+            result = _get_npx_command()
+
+            assert result == "npx.cmd"
+            mock_run.assert_called_once_with(
+                ["npx.cmd", "--version"],
+                check=True,
+                capture_output=True,
+            )
+
+    @patch("subprocess.run")
+    def test_get_npx_command_windows_exe(self, mock_run):
+        """Test npx command detection on Windows with npx.exe."""
+        from fastmcp.cli.cli import _get_npx_command
+
+        with patch("sys.platform", "win32"):
+            # First call fails, second succeeds
+            mock_run.side_effect = [
+                subprocess.CalledProcessError(1, "npx.cmd"),
+                Mock(returncode=0),
+            ]
+
+            result = _get_npx_command()
+
+            assert result == "npx.exe"
+            assert mock_run.call_count == 2
+
+    @patch("subprocess.run")
+    def test_get_npx_command_windows_cmd_missing(self, mock_run):
+        """Test npx command detection continues when npx.cmd is missing."""
+        from fastmcp.cli.cli import _get_npx_command
+
+        with patch("sys.platform", "win32"):
+            # Missing npx.cmd should not abort detection
+            mock_run.side_effect = [
+                FileNotFoundError("npx.cmd not found"),
+                Mock(returncode=0),
+            ]
+
+            result = _get_npx_command()
+
+            assert result == "npx.exe"
+            assert mock_run.call_count == 2
+
+    @patch("subprocess.run")
+    def test_get_npx_command_windows_fallback(self, mock_run):
+        """Test npx command detection on Windows with plain npx."""
+        from fastmcp.cli.cli import _get_npx_command
+
+        with patch("sys.platform", "win32"):
+            # First two calls fail, third succeeds
+            mock_run.side_effect = [
+                subprocess.CalledProcessError(1, "npx.cmd"),
+                subprocess.CalledProcessError(1, "npx.exe"),
+                Mock(returncode=0),
+            ]
+
+            result = _get_npx_command()
+
+            assert result == "npx"
+            assert mock_run.call_count == 3
+
+    @patch("subprocess.run")
+    def test_get_npx_command_windows_not_found(self, mock_run):
+        """Test npx command detection on Windows when npx is not found."""
+        from fastmcp.cli.cli import _get_npx_command
+
+        with patch("sys.platform", "win32"):
+            # All calls fail
+            mock_run.side_effect = subprocess.CalledProcessError(1, "npx")
+
+            result = _get_npx_command()
+
+            assert result is None
+            assert mock_run.call_count == 3
+
+    @patch("subprocess.run")
+    def test_get_npx_command_unix(self, mock_run):
+        """Test npx command detection on Unix systems."""
+        from fastmcp.cli.cli import _get_npx_command
+
+        with patch("sys.platform", "darwin"):
+            result = _get_npx_command()
+
+            assert result == "npx"
+            mock_run.assert_not_called()
+
+    def test_windows_path_parsing_with_colon(self, tmp_path):
+        """Test parsing Windows paths with drive letters and colons."""
+        from pathlib import Path
+
+        from fastmcp.utilities.mcp_server_config.v1.sources.filesystem import (
+            FileSystemSource,
+        )
+
+        # Create a real test file to test the logic
+        test_file = tmp_path / "server.py"
+        test_file.write_text("# test server")
+
+        # Test normal file parsing (works on all platforms)
+        source = FileSystemSource(path=str(test_file))
+        assert source.entrypoint is None
+        assert Path(source.path).resolve() == test_file.resolve()
+
+        # Test file:object parsing
+        source = FileSystemSource(path=f"{test_file}:myapp")
+        assert source.entrypoint == "myapp"
+
+        # Test that the file portion resolves correctly when object is specified
+        assert Path(source.path).resolve() == test_file.resolve()
+
+
+class TestInspectCommand:
+    """Test the inspect command."""
+
+    def test_inspect_command_parsing_basic(self):
+        """Test basic inspect command parsing."""
+        command, bound, _ = app.parse_args(["inspect", "server.py"])
+
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        # Only explicitly set parameters are in bound.arguments
+        assert "output" not in bound.arguments
+
+    def test_inspect_command_parsing_with_output(self, tmp_path):
+        """Test inspect command parsing with output file."""
+        output_file = tmp_path / "output.json"
+
+        command, bound, _ = app.parse_args(
+            [
+                "inspect",
+                "server.py",
+                "--output",
+                str(output_file),
+            ]
+        )
+
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        # Output is parsed as a Path object
+        assert bound.arguments["output"] == output_file
+
+    async def test_inspect_command_text_summary(self, tmp_path, capsys):
+        """Test inspect command with no format shows text summary."""
+        # Create a real server file
+        server_file = tmp_path / "test_server.py"
+        server_file.write_text("""
+import fastmcp
+
+mcp = fastmcp.FastMCP("InspectTestServer", instructions="Test instructions", version="1.0.0")
+
+@mcp.tool
+def test_tool(x: int) -> int:
+    return x * 2
+""")
+
+        # Parse and execute the command without format or output
+        command, bound, _ = app.parse_args(
+            [
+                "inspect",
+                str(server_file),
+            ]
+        )
+
+        await command(**bound.arguments)
+
+        # Check the console output
+        captured = capsys.readouterr()
+        # Check for the table format output
+        assert "InspectTestServer" in captured.out
+        assert "Test instructions" in captured.out
+        assert "1.0.0" in captured.out
+        assert "Tools" in captured.out
+        assert "1" in captured.out  # number of tools
+        assert "FastMCP" in captured.out
+        assert "MCP" in captured.out
+        assert "Use --format [fastmcp|mcp] for complete JSON output" in captured.out
+
+    async def test_inspect_command_with_real_server(self, tmp_path):
+        """Test inspect command with a real server file."""
+        # Create a real server file
+        server_file = tmp_path / "test_server.py"
+        server_file.write_text("""
+import fastmcp
+
+mcp = fastmcp.FastMCP("InspectTestServer")
+
+@mcp.tool
+def test_tool(x: int) -> int:
+    return x * 2
+
+@mcp.prompt
+def test_prompt(name: str) -> str:
+    return f"Hello, {name}!"
+""")
+
+        output_file = tmp_path / "inspect_output.json"
+
+        # Parse and execute the command with format and output file
+        command, bound, _ = app.parse_args(
+            [
+                "inspect",
+                str(server_file),
+                "--format",
+                "fastmcp",
+                "--output",
+                str(output_file),
+            ]
+        )
+
+        await command(**bound.arguments)
+
+        # Verify the output file was created and contains expected content
+        assert output_file.exists()
+        content = output_file.read_text()
+
+        # Basic checks that the fastmcp format worked
+        import json
+
+        data = json.loads(content)
+        assert data["server"]["name"] == "InspectTestServer"
+        assert len(data["tools"]) == 1
+        assert len(data["prompts"]) == 1
diff --git a/tests/cli/test_client_commands.py b/tests/cli/test_client_commands.py
new file mode 100644
index 0000000..d2083d1
--- /dev/null
+++ b/tests/cli/test_client_commands.py
@@ -0,0 +1,582 @@
+"""Tests for fastmcp list and fastmcp call CLI commands."""
+
+import json
+from pathlib import Path
+from typing import Any
+from unittest.mock import patch
+
+import mcp_types
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.cli import client as client_module
+from fastmcp.cli.client import (
+    Client,
+    _build_client,
+    _build_stdio_from_command,
+    _format_call_result_text,
+    _is_http_target,
+    _sanitize_untrusted_text,
+    call_command,
+    coerce_value,
+    format_tool_signature,
+    list_command,
+    parse_tool_arguments,
+    resolve_server_spec,
+)
+from fastmcp.client.client import CallToolResult
+from fastmcp.client.transports.stdio import StdioTransport
+
+# ---------------------------------------------------------------------------
+# coerce_value
+# ---------------------------------------------------------------------------
+
+
+class TestCoerceValue:
+    def test_integer(self):
+        assert coerce_value("42", {"type": "integer"}) == 42
+
+    def test_integer_negative(self):
+        assert coerce_value("-7", {"type": "integer"}) == -7
+
+    def test_integer_invalid(self):
+        with pytest.raises(ValueError, match="Expected integer"):
+            coerce_value("abc", {"type": "integer"})
+
+    def test_number(self):
+        assert coerce_value("3.14", {"type": "number"}) == 3.14
+
+    def test_number_integer_value(self):
+        assert coerce_value("5", {"type": "number"}) == 5.0
+
+    def test_number_invalid(self):
+        with pytest.raises(ValueError, match="Expected number"):
+            coerce_value("xyz", {"type": "number"})
+
+    def test_boolean_true_variants(self):
+        for val in ("true", "True", "TRUE", "1", "yes"):
+            assert coerce_value(val, {"type": "boolean"}) is True
+
+    def test_boolean_false_variants(self):
+        for val in ("false", "False", "FALSE", "0", "no"):
+            assert coerce_value(val, {"type": "boolean"}) is False
+
+    def test_boolean_invalid(self):
+        with pytest.raises(ValueError, match="Expected boolean"):
+            coerce_value("maybe", {"type": "boolean"})
+
+    def test_array(self):
+        assert coerce_value("[1, 2, 3]", {"type": "array"}) == [1, 2, 3]
+
+    def test_array_invalid(self):
+        with pytest.raises(ValueError, match="Expected JSON array"):
+            coerce_value("not-json", {"type": "array"})
+
+    def test_object(self):
+        assert coerce_value('{"a": 1}', {"type": "object"}) == {"a": 1}
+
+    def test_string(self):
+        assert coerce_value("hello", {"type": "string"}) == "hello"
+
+    def test_string_default(self):
+        """Unknown or missing type treats value as string."""
+        assert coerce_value("hello", {}) == "hello"
+
+    def test_string_preserves_numeric_looking_values(self):
+        assert coerce_value("42", {"type": "string"}) == "42"
+
+
+# ---------------------------------------------------------------------------
+# parse_tool_arguments
+# ---------------------------------------------------------------------------
+
+
+class TestParseToolArguments:
+    SCHEMA: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string"},
+            "limit": {"type": "integer"},
+            "verbose": {"type": "boolean"},
+        },
+        "required": ["query"],
+    }
+
+    def test_basic_key_value(self):
+        result = parse_tool_arguments(("query=hello", "limit=10"), None, self.SCHEMA)
+        assert result == {"query": "hello", "limit": 10}
+
+    def test_input_json_only(self):
+        result = parse_tool_arguments((), '{"query": "hello", "limit": 5}', self.SCHEMA)
+        assert result == {"query": "hello", "limit": 5}
+
+    def test_key_value_overrides_input_json(self):
+        result = parse_tool_arguments(
+            ("limit=20",), '{"query": "hello", "limit": 5}', self.SCHEMA
+        )
+        assert result == {"query": "hello", "limit": 20}
+
+    def test_value_containing_equals(self):
+        result = parse_tool_arguments(("query=a=b=c",), None, self.SCHEMA)
+        assert result == {"query": "a=b=c"}
+
+    def test_invalid_arg_format_exits(self):
+        with pytest.raises(SystemExit):
+            parse_tool_arguments(("noequalssign",), None, self.SCHEMA)
+
+    def test_invalid_input_json_exits(self):
+        with pytest.raises(SystemExit):
+            parse_tool_arguments((), "not-valid-json", self.SCHEMA)
+
+    def test_input_json_non_object_exits(self):
+        with pytest.raises(SystemExit):
+            parse_tool_arguments((), "[1,2,3]", self.SCHEMA)
+
+    def test_single_json_object_as_positional(self):
+        result = parse_tool_arguments(
+            ('{"query": "hello", "limit": 5}',), None, self.SCHEMA
+        )
+        assert result == {"query": "hello", "limit": 5}
+
+    def test_json_positional_ignored_when_input_json_set(self):
+        """When --input-json is already provided, a JSON positional arg is not special."""
+        with pytest.raises(SystemExit):
+            parse_tool_arguments(('{"limit": 99}',), '{"query": "hello"}', self.SCHEMA)
+
+    def test_coercion_error_exits(self):
+        with pytest.raises(SystemExit):
+            parse_tool_arguments(("limit=abc",), None, self.SCHEMA)
+
+
+# ---------------------------------------------------------------------------
+# format_tool_signature
+# ---------------------------------------------------------------------------
+
+
+class TestFormatToolSignature:
+    def _make_tool(
+        self,
+        name: str = "my_tool",
+        properties: dict[str, Any] | None = None,
+        required: list[str] | None = None,
+        output_schema: dict[str, Any] | None = None,
+        description: str | None = None,
+    ) -> mcp_types.Tool:
+        input_schema: dict[str, Any] = {"type": "object"}
+        if properties is not None:
+            input_schema["properties"] = properties
+        if required is not None:
+            input_schema["required"] = required
+        return mcp_types.Tool(
+            name=name,
+            description=description,
+            input_schema=input_schema,
+            output_schema=output_schema,
+        )
+
+    def test_no_params(self):
+        tool = self._make_tool()
+        assert format_tool_signature(tool) == "my_tool()"
+
+    def test_required_param(self):
+        tool = self._make_tool(
+            properties={"query": {"type": "string"}},
+            required=["query"],
+        )
+        assert format_tool_signature(tool) == "my_tool(query: str)"
+
+    def test_optional_param_with_default(self):
+        tool = self._make_tool(
+            properties={"limit": {"type": "integer", "default": 10}},
+        )
+        assert format_tool_signature(tool) == "my_tool(limit: int = 10)"
+
+    def test_optional_param_without_default(self):
+        tool = self._make_tool(
+            properties={"limit": {"type": "integer"}},
+        )
+        assert format_tool_signature(tool) == "my_tool(limit: int = ...)"
+
+    def test_mixed_required_and_optional(self):
+        tool = self._make_tool(
+            properties={
+                "query": {"type": "string"},
+                "limit": {"type": "integer", "default": 10},
+            },
+            required=["query"],
+        )
+        sig = format_tool_signature(tool)
+        assert sig == "my_tool(query: str, limit: int = 10)"
+
+    def test_with_output_schema(self):
+        tool = self._make_tool(
+            properties={"q": {"type": "string"}},
+            required=["q"],
+            output_schema={"type": "object"},
+        )
+        assert format_tool_signature(tool) == "my_tool(q: str) -> dict"
+
+    def test_anyof_type(self):
+        tool = self._make_tool(
+            properties={"value": {"anyOf": [{"type": "string"}, {"type": "integer"}]}},
+            required=["value"],
+        )
+        assert format_tool_signature(tool) == "my_tool(value: str | int)"
+
+
+# ---------------------------------------------------------------------------
+# resolve_server_spec
+# ---------------------------------------------------------------------------
+
+
+class TestResolveServerSpec:
+    def test_http_url(self):
+        assert (
+            resolve_server_spec("http://localhost:8000/mcp")
+            == "http://localhost:8000/mcp"
+        )
+
+    def test_https_url(self):
+        assert (
+            resolve_server_spec("https://example.com/mcp") == "https://example.com/mcp"
+        )
+
+    def test_python_file_existing(self, tmp_path: Path):
+        py_file = tmp_path / "server.py"
+        py_file.write_text("# empty")
+        result = resolve_server_spec(str(py_file))
+        assert isinstance(result, StdioTransport)
+        assert result.command == "fastmcp"
+        assert result.args == ["run", str(py_file.resolve()), "--no-banner"]
+
+    def test_json_mcp_config(self, tmp_path: Path):
+        config_file = tmp_path / "mcp.json"
+        config = {"mcpServers": {"test": {"url": "http://localhost:8000"}}}
+        config_file.write_text(json.dumps(config))
+        result = resolve_server_spec(str(config_file))
+        assert isinstance(result, dict)
+        assert "mcpServers" in result
+
+    def test_json_fastmcp_config_exits(self, tmp_path: Path):
+        config_file = tmp_path / "fastmcp.json"
+        config_file.write_text(json.dumps({"source": {"type": "file"}}))
+        with pytest.raises(SystemExit):
+            resolve_server_spec(str(config_file))
+
+    def test_json_not_found_exits(self, tmp_path: Path):
+        with pytest.raises(SystemExit):
+            resolve_server_spec(str(tmp_path / "nonexistent.json"))
+
+    def test_directory_exits(self, tmp_path: Path):
+        """Directories should not be treated as file paths."""
+        with pytest.raises(SystemExit):
+            resolve_server_spec(str(tmp_path))
+
+    def test_unrecognised_exits(self):
+        with pytest.raises(SystemExit):
+            resolve_server_spec("some_random_thing")
+
+    def test_command_returns_stdio_transport(self):
+        result = resolve_server_spec(None, command="npx -y @mcp/server")
+        assert isinstance(result, StdioTransport)
+        assert result.command == "npx"
+        assert result.args == ["-y", "@mcp/server"]
+
+    def test_command_single_word(self):
+        result = resolve_server_spec(None, command="myserver")
+        assert isinstance(result, StdioTransport)
+        assert result.command == "myserver"
+        assert result.args == []
+
+    def test_server_spec_and_command_exits(self):
+        with pytest.raises(SystemExit):
+            resolve_server_spec("http://localhost:8000", command="npx server")
+
+    def test_neither_server_spec_nor_command_exits(self):
+        with pytest.raises(SystemExit):
+            resolve_server_spec(None)
+
+    def test_transport_sse_rewrites_url(self):
+        result = resolve_server_spec("http://localhost:8000/mcp", transport="sse")
+        assert result == "http://localhost:8000/mcp/sse"
+
+    def test_transport_sse_no_duplicate_suffix(self):
+        result = resolve_server_spec("http://localhost:8000/sse", transport="sse")
+        assert result == "http://localhost:8000/sse"
+
+    def test_transport_sse_trailing_slash(self):
+        result = resolve_server_spec("http://localhost:8000/mcp/", transport="sse")
+        assert result == "http://localhost:8000/mcp/sse"
+
+    def test_transport_http_leaves_url_unchanged(self):
+        result = resolve_server_spec("http://localhost:8000/mcp", transport="http")
+        assert result == "http://localhost:8000/mcp"
+
+
+# ---------------------------------------------------------------------------
+# _build_stdio_from_command
+# ---------------------------------------------------------------------------
+
+
+class TestBuildStdioFromCommand:
+    def test_simple_command(self):
+        transport = _build_stdio_from_command("uvx my-server")
+        assert transport.command == "uvx"
+        assert transport.args == ["my-server"]
+
+    def test_quoted_args(self):
+        transport = _build_stdio_from_command("npx -y '@scope/server'")
+        assert transport.command == "npx"
+        assert transport.args == ["-y", "@scope/server"]
+
+    def test_empty_command_exits(self):
+        with pytest.raises(SystemExit):
+            _build_stdio_from_command("")
+
+    def test_invalid_shell_syntax_exits(self):
+        with pytest.raises(SystemExit):
+            _build_stdio_from_command("npx 'unterminated")
+
+
+# ---------------------------------------------------------------------------
+# _is_http_target
+# ---------------------------------------------------------------------------
+
+
+class TestIsHttpTarget:
+    def test_http_url(self):
+        assert _is_http_target("http://localhost:8000") is True
+
+    def test_https_url(self):
+        assert _is_http_target("https://example.com/mcp") is True
+
+    def test_file_path(self):
+        assert _is_http_target("/path/to/server.py") is False
+
+    def test_stdio_transport(self):
+        assert _is_http_target(StdioTransport(command="npx", args=[])) is False
+
+    def test_mcp_config_dict(self):
+        """MCPConfig dicts are not HTTP targets — auth is per-server internally."""
+        assert _is_http_target({"mcpServers": {}}) is False
+
+
+# ---------------------------------------------------------------------------
+# _build_client
+# ---------------------------------------------------------------------------
+
+
+class TestBuildClient:
+    def test_http_target_gets_oauth_by_default(self):
+        client = _build_client("http://localhost:8000/mcp")
+        # OAuth is applied during Client init via _set_auth
+        assert client.transport.auth is not None
+
+    def test_stdio_target_no_auth(self):
+        transport = StdioTransport(command="npx", args=["-y", "@mcp/server"])
+        client = _build_client(transport)
+        # Stdio transports don't support auth — no auth should be set
+        assert not hasattr(client.transport, "auth") or client.transport.auth is None
+
+    def test_explicit_auth_none_disables_oauth(self):
+        client = _build_client("http://localhost:8000/mcp", auth="none")
+        # "none" explicitly disables auth, even for HTTP targets
+        assert client.transport.auth is None
+
+    def test_mcp_config_no_auth(self):
+        """MCPConfig dicts handle auth per-server; no top-level auth applied."""
+        client = _build_client({"mcpServers": {"test": {"url": "http://localhost"}}})
+        # MCPConfigTransport doesn't support _set_auth — no crash means success
+        assert client.transport is not None
+
+
+# ---------------------------------------------------------------------------
+# Integration tests — invoke actual CLI commands via monkeypatched _build_client
+# ---------------------------------------------------------------------------
+
+
+def _build_test_server() -> FastMCP:
+    """Create a minimal FastMCP server for integration tests."""
+    server = FastMCP("TestServer")
+
+    @server.tool
+    def greet(name: str) -> str:
+        """Say hello to someone."""
+        return f"Hello, {name}!"
+
+    @server.tool
+    def add(a: int, b: int) -> int:
+        """Add two numbers."""
+        return a + b
+
+    @server.resource("test://greeting")
+    def greeting_resource() -> str:
+        """A static greeting resource."""
+        return "Hello from resource!"
+
+    @server.prompt
+    def ask(topic: str) -> str:
+        """Ask about a topic."""
+        return f"Tell me about {topic}"
+
+    return server
+
+
+@pytest.fixture()
+def _patch_client():
+    """Patch resolve_server_spec and _build_client so CLI commands use the
+    in-process test server without needing a real transport."""
+    server = _build_test_server()
+
+    def fake_resolve(server_spec: Any, **kwargs: Any) -> str:
+        return "fake"
+
+    def fake_build_client(resolved: Any, **kwargs: Any) -> Client:
+        return Client(server)
+
+    with (
+        patch.object(client_module, "resolve_server_spec", side_effect=fake_resolve),
+        patch.object(client_module, "_build_client", side_effect=fake_build_client),
+    ):
+        yield
+
+
+class TestListCommandCLI:
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_list_tools(self, capsys: pytest.CaptureFixture[str]):
+        await list_command("fake://server")
+        captured = capsys.readouterr()
+        assert "greet" in captured.out
+        assert "add" in captured.out
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_list_json(self, capsys: pytest.CaptureFixture[str]):
+        await list_command("fake://server", json_output=True)
+        captured = capsys.readouterr()
+        data = json.loads(captured.out)
+        names = {t["name"] for t in data["tools"]}
+        assert "greet" in names
+        assert "add" in names
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_list_resources(self, capsys: pytest.CaptureFixture[str]):
+        await list_command("fake://server", resources=True)
+        captured = capsys.readouterr()
+        assert "test://greeting" in captured.out
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_list_prompts(self, capsys: pytest.CaptureFixture[str]):
+        await list_command("fake://server", prompts=True)
+        captured = capsys.readouterr()
+        assert "ask" in captured.out
+
+
+class TestCallCommandCLI:
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_call_tool(self, capsys: pytest.CaptureFixture[str]):
+        await call_command("fake://server", "greet", "name=World")
+        captured = capsys.readouterr()
+        assert "Hello, World!" in captured.out
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_call_tool_json(self, capsys: pytest.CaptureFixture[str]):
+        await call_command("fake://server", "greet", "name=World", json_output=True)
+        captured = capsys.readouterr()
+        data = json.loads(captured.out)
+        assert data["is_error"] is False
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_call_tool_not_found(self):
+        with pytest.raises(SystemExit):
+            await call_command("fake://server", "nonexistent")
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_call_tool_missing_args(self):
+        with pytest.raises(SystemExit):
+            await call_command("fake://server", "greet")
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_call_resource_by_uri(self, capsys: pytest.CaptureFixture[str]):
+        await call_command("fake://server", "test://greeting")
+        captured = capsys.readouterr()
+        assert "Hello from resource!" in captured.out
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_call_resource_json(self, capsys: pytest.CaptureFixture[str]):
+        await call_command("fake://server", "test://greeting", json_output=True)
+        captured = capsys.readouterr()
+        data = json.loads(captured.out)
+        assert isinstance(data, list)
+        assert data[0]["text"] == "Hello from resource!"
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_call_prompt(self, capsys: pytest.CaptureFixture[str]):
+        await call_command("fake://server", "ask", "topic=Python", prompt=True)
+        captured = capsys.readouterr()
+        assert "Python" in captured.out
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_call_prompt_json(self, capsys: pytest.CaptureFixture[str]):
+        await call_command(
+            "fake://server", "ask", "topic=Python", prompt=True, json_output=True
+        )
+        captured = capsys.readouterr()
+        data = json.loads(captured.out)
+        assert "messages" in data
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_call_prompt_not_found(self):
+        with pytest.raises(SystemExit):
+            await call_command("fake://server", "nonexistent", prompt=True)
+
+    async def test_call_missing_target(self):
+        with pytest.raises(SystemExit):
+            await call_command("fake://server", "")
+
+
+# ---------------------------------------------------------------------------
+# Structured content serialization
+# ---------------------------------------------------------------------------
+
+
+class TestFormatCallResult:
+    def test_structured_content_uses_dict_not_data(
+        self, capsys: pytest.CaptureFixture[str]
+    ):
+        """structured_content (raw dict) is used for display, not data (which may
+        be a non-serializable dataclass)."""
+        result = CallToolResult(
+            content=[mcp_types.TextContent(type="text", text="ok")],
+            structured_content={"key": "value"},
+            meta=None,
+            data=object(),  # non-serializable on purpose
+            is_error=False,
+        )
+        # Should not raise — uses structured_content, not data
+        _format_call_result_text(result)
+        captured = capsys.readouterr()
+        assert "value" in captured.out
+
+    def test_escapes_rich_markup_and_control_chars(
+        self, capsys: pytest.CaptureFixture[str]
+    ):
+        result = CallToolResult(
+            content=[mcp_types.TextContent(type="text", text="[red]x[/red]\x1b[2J")],
+            structured_content=None,
+            meta=None,
+            data=None,
+            is_error=False,
+        )
+
+        _format_call_result_text(result)
+        captured = capsys.readouterr()
+        assert "[red]x[/red]" in captured.out
+        assert "\\x1b" in captured.out
+        assert "\x1b" not in captured.out
+
+
+class TestSanitizeUntrustedText:
+    def test_sanitize_untrusted_text(self):
+        value = "[bold]hello[/bold]\x07"
+        sanitized = _sanitize_untrusted_text(value)
+        assert sanitized == "\\[bold]hello\\[/bold]\\x07"
diff --git a/tests/cli/test_config.py b/tests/cli/test_config.py
new file mode 100644
index 0000000..cb4dd00
--- /dev/null
+++ b/tests/cli/test_config.py
@@ -0,0 +1,461 @@
+"""Tests for FastMCP configuration file support with nested structure."""
+
+import json
+import os
+from pathlib import Path
+
+import pytest
+from pydantic import ValidationError
+
+from fastmcp.utilities.mcp_server_config import (
+    Deployment,
+    MCPServerConfig,
+)
+from fastmcp.utilities.mcp_server_config.v1.environments.uv import UVEnvironment
+from fastmcp.utilities.mcp_server_config.v1.sources.filesystem import FileSystemSource
+
+
+class TestFileSystemSource:
+    """Test FileSystemSource class."""
+
+    def test_dict_source_minimal(self):
+        """Test that dict source is converted to FileSystemSource."""
+        config = MCPServerConfig(source={"path": "server.py"})
+        # Dict is converted to FileSystemSource
+        assert isinstance(config.source, FileSystemSource)
+        assert config.source.path == "server.py"
+        assert config.source.entrypoint is None
+        assert config.source.type == "filesystem"
+
+    def test_dict_source_with_entrypoint(self):
+        """Test dict source with entrypoint field."""
+        config = MCPServerConfig(source={"path": "server.py", "entrypoint": "app"})
+        # Dict with entrypoint is converted to FileSystemSource
+        assert isinstance(config.source, FileSystemSource)
+        assert config.source.path == "server.py"
+        assert config.source.entrypoint == "app"
+        assert config.source.type == "filesystem"
+
+    def test_filesystem_source_entrypoint(self):
+        """Test FileSystemSource entrypoint format."""
+        config = MCPServerConfig(
+            source=FileSystemSource(path="src/server.py", entrypoint="mcp")
+        )
+        assert isinstance(config.source, FileSystemSource)
+        assert config.source.path == "src/server.py"
+        assert config.source.entrypoint == "mcp"
+        assert config.source.type == "filesystem"
+
+
+class TestEnvironment:
+    """Test Environment class."""
+
+    def test_environment_config_fields(self):
+        """Test all Environment fields."""
+        config = MCPServerConfig(
+            source={"path": "server.py"},
+            environment={
+                "python": "3.12",
+                "dependencies": ["requests", "numpy>=2.0"],
+                "requirements": "requirements.txt",
+                "project": ".",
+                "editable": ["../my-package"],
+            },
+        )
+
+        env = config.environment
+        assert env.python == "3.12"
+        assert env.dependencies == ["requests", "numpy>=2.0"]
+        # Paths are stored as Path objects
+        assert env.requirements == Path("requirements.txt")
+        assert env.project == Path(".")
+        assert env.editable == [Path("../my-package")]
+
+    def test_needs_uv(self):
+        """Test needs_uv() method."""
+        # No environment config - doesn't need UV
+        config = MCPServerConfig(source={"path": "server.py"})
+        assert not config.environment._must_run_with_uv()
+
+        # Empty environment - doesn't need UV
+        config = MCPServerConfig(source={"path": "server.py"}, environment={})
+        assert not config.environment._must_run_with_uv()
+
+        # With dependencies - needs UV
+        config = MCPServerConfig(
+            source={"path": "server.py"}, environment={"dependencies": ["requests"]}
+        )
+        assert config.environment._must_run_with_uv()
+
+        # With Python version - needs UV
+        config = MCPServerConfig(
+            source={"path": "server.py"}, environment={"python": "3.12"}
+        )
+        assert config.environment._must_run_with_uv()
+
+    def test_build_uv_run_command(self):
+        """Test build_uv_run_command() method."""
+        config = MCPServerConfig(
+            source={"path": "server.py"},
+            environment={
+                "python": "3.12",
+                "dependencies": ["requests", "numpy"],
+                "requirements": "requirements.txt",
+                "project": ".",
+            },
+        )
+
+        cmd = config.environment.build_command(["fastmcp", "run", "server.py"])
+
+        assert cmd[0] == "uv"
+        assert cmd[1] == "run"
+        # Python version not added when project is specified (project defines its own Python)
+        assert "--python" not in cmd
+        assert "3.12" not in cmd
+        assert "--project" in cmd
+        # Project path should be resolved to absolute path
+        project_idx = cmd.index("--project")
+        assert Path(cmd[project_idx + 1]).is_absolute()
+        assert "--with" in cmd
+        assert "requests" in cmd
+        assert "numpy" in cmd
+        assert "--with-requirements" in cmd
+        # Requirements path should be resolved to absolute path
+        req_idx = cmd.index("--with-requirements")
+        assert Path(cmd[req_idx + 1]).is_absolute()
+        # Command args should be at the end
+        assert "fastmcp" in cmd[-3:]
+        assert "run" in cmd[-2:]
+        assert "server.py" in cmd[-1:]
+
+
+class TestDeployment:
+    """Test Deployment class."""
+
+    def test_deployment_config_fields(self):
+        """Test all Deployment fields."""
+        config = MCPServerConfig(
+            source={"path": "server.py"},
+            deployment={
+                "transport": "http",
+                "host": "0.0.0.0",
+                "port": 8000,
+                "path": "/api/",
+                "log_level": "DEBUG",
+                "env": {"API_KEY": "secret"},
+                "cwd": "./work",
+                "args": ["--debug"],
+            },
+        )
+
+        deploy = config.deployment
+        assert deploy.transport == "http"
+        assert deploy.host == "0.0.0.0"
+        assert deploy.port == 8000
+        assert deploy.path == "/api/"
+        assert deploy.log_level == "DEBUG"
+        assert deploy.env == {"API_KEY": "secret"}
+        assert deploy.cwd == "./work"
+        assert deploy.args == ["--debug"]
+
+    def test_apply_runtime_settings(self, tmp_path):
+        """Test apply_runtime_settings() method."""
+        import os
+
+        # Create config with env vars and cwd
+        work_dir = tmp_path / "work"
+        work_dir.mkdir()
+
+        config = MCPServerConfig(
+            source={"path": "server.py"},
+            deployment={
+                "env": {"TEST_VAR": "test_value"},
+                "cwd": "work",
+            },
+        )
+
+        original_cwd = os.getcwd()
+        original_env = os.environ.get("TEST_VAR")
+
+        try:
+            config.deployment.apply_runtime_settings(tmp_path / "fastmcp.json")
+
+            # Check environment variable was set
+            assert os.environ["TEST_VAR"] == "test_value"
+
+            # Check working directory was changed
+            assert Path.cwd() == work_dir.resolve()
+
+        finally:
+            # Restore original state
+            os.chdir(original_cwd)
+            if original_env is None:
+                os.environ.pop("TEST_VAR", None)
+            else:
+                os.environ["TEST_VAR"] = original_env
+
+    def test_env_var_interpolation(self, tmp_path):
+        """Test environment variable interpolation in deployment env."""
+        import os
+
+        # Set up test environment variables
+        os.environ["BASE_URL"] = "example.com"
+        os.environ["ENV_NAME"] = "production"
+
+        config = MCPServerConfig(
+            source={"path": "server.py"},
+            deployment={
+                "env": {
+                    "API_URL": "https://api.${BASE_URL}/v1",
+                    "DATABASE": "postgres://${ENV_NAME}.db",
+                    "PREFIXED": "MY_${ENV_NAME}_SERVER",
+                    "MISSING": "value_${NONEXISTENT}_here",
+                    "STATIC": "no_interpolation",
+                }
+            },
+        )
+
+        original_values = {
+            key: os.environ.get(key)
+            for key in ["API_URL", "DATABASE", "PREFIXED", "MISSING", "STATIC"]
+        }
+
+        try:
+            config.deployment.apply_runtime_settings()
+
+            # Check interpolated values
+            assert os.environ["API_URL"] == "https://api.example.com/v1"
+            assert os.environ["DATABASE"] == "postgres://production.db"
+            assert os.environ["PREFIXED"] == "MY_production_SERVER"
+            # Missing variables should keep the placeholder
+            assert os.environ["MISSING"] == "value_${NONEXISTENT}_here"
+            # Static values should remain unchanged
+            assert os.environ["STATIC"] == "no_interpolation"
+
+        finally:
+            # Clean up
+            os.environ.pop("BASE_URL", None)
+            os.environ.pop("ENV_NAME", None)
+            for key, value in original_values.items():
+                if value is None:
+                    os.environ.pop(key, None)
+                else:
+                    os.environ[key] = value
+
+
+class TestMCPServerConfig:
+    """Test MCPServerConfig root configuration."""
+
+    def test_minimal_config(self):
+        """Test creating a config with only required fields."""
+        config = MCPServerConfig(source={"path": "server.py"})
+        assert isinstance(config.source, FileSystemSource)
+        assert config.source.path == "server.py"
+        assert config.source.entrypoint is None
+        # Environment and deployment are now always present but empty
+        assert isinstance(config.environment, UVEnvironment)
+        assert isinstance(config.deployment, Deployment)
+        # Check they have no values set
+        assert not config.environment._must_run_with_uv()
+        assert all(
+            getattr(config.deployment, field, None) is None
+            for field in Deployment.model_fields
+        )
+
+    def test_nested_structure(self):
+        """Test the nested configuration structure."""
+        config = MCPServerConfig(
+            source={"path": "server.py"},
+            environment={
+                "python": "3.12",
+                "dependencies": ["fastmcp"],
+            },
+            deployment={
+                "transport": "stdio",
+                "log_level": "INFO",
+            },
+        )
+
+        assert isinstance(config.source, FileSystemSource)
+        assert config.source.path == "server.py"
+        assert config.source.entrypoint is None
+        assert isinstance(config.environment, UVEnvironment)
+        assert isinstance(config.deployment, Deployment)
+
+    def test_from_file(self, tmp_path):
+        """Test loading config from JSON file with nested structure."""
+        config_data = {
+            "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+            "source": {"path": "src/server.py", "entrypoint": "app"},
+            "environment": {"python": "3.12", "dependencies": ["requests"]},
+            "deployment": {"transport": "http", "port": 8000},
+        }
+
+        config_file = tmp_path / "fastmcp.json"
+        config_file.write_text(json.dumps(config_data))
+
+        config = MCPServerConfig.from_file(config_file)
+
+        # When loaded from JSON with entrypoint format, it becomes EntrypointConfig
+        assert isinstance(config.source, FileSystemSource)
+        assert config.source.path == "src/server.py"
+        assert config.source.entrypoint == "app"
+        assert config.environment.python == "3.12"
+        assert config.environment.dependencies == ["requests"]
+        assert config.deployment.transport == "http"
+        assert config.deployment.port == 8000
+
+    def test_from_file_with_string_entrypoint(self, tmp_path):
+        """Test loading config with dict source format."""
+        config_data = {
+            "source": {"path": "server.py", "entrypoint": "mcp"},
+            "environment": {"dependencies": ["fastmcp"]},
+        }
+
+        config_file = tmp_path / "fastmcp.json"
+        config_file.write_text(json.dumps(config_data))
+
+        config = MCPServerConfig.from_file(config_file)
+        # String entrypoint with : should be converted to EntrypointConfig
+        assert isinstance(config.source, FileSystemSource)
+        assert config.source.path == "server.py"
+        assert config.source.entrypoint == "mcp"
+
+    def test_string_entrypoint_with_entrypoint_and_environment(self, tmp_path):
+        """Test that file.py:entrypoint syntax works with environment config."""
+        config_data = {
+            "source": {"path": "src/server.py", "entrypoint": "app"},
+            "environment": {"python": "3.12", "dependencies": ["fastmcp", "requests"]},
+            "deployment": {"transport": "http", "port": 8000},
+        }
+
+        config_file = tmp_path / "fastmcp.json"
+        config_file.write_text(json.dumps(config_data))
+
+        config = MCPServerConfig.from_file(config_file)
+
+        # Should be parsed into EntrypointConfig
+        assert isinstance(config.source, FileSystemSource)
+        assert config.source.path == "src/server.py"
+        assert config.source.entrypoint == "app"
+
+        # Environment config should still work
+        assert config.environment.python == "3.12"
+        assert config.environment.dependencies == ["fastmcp", "requests"]
+
+        # Deployment config should still work
+        assert config.deployment.transport == "http"
+        assert config.deployment.port == 8000
+
+    def test_find_config_in_current_dir(self, tmp_path):
+        """Test finding config in current directory."""
+        config_file = tmp_path / "fastmcp.json"
+        config_file.write_text(json.dumps({"source": {"path": "server.py"}}))
+
+        original_cwd = os.getcwd()
+        try:
+            os.chdir(tmp_path)
+            found = MCPServerConfig.find_config()
+            assert found == config_file
+        finally:
+            os.chdir(original_cwd)
+
+    def test_find_config_not_in_parent_dir(self, tmp_path):
+        """Test that config is NOT found in parent directory."""
+        config_file = tmp_path / "fastmcp.json"
+        config_file.write_text(json.dumps({"source": {"path": "server.py"}}))
+
+        subdir = tmp_path / "subdir"
+        subdir.mkdir()
+
+        # Should NOT find config in parent directory
+        found = MCPServerConfig.find_config(subdir)
+        assert found is None
+
+    def test_find_config_in_specified_dir(self, tmp_path):
+        """Test finding config in the specified directory."""
+        config_file = tmp_path / "fastmcp.json"
+        config_file.write_text(json.dumps({"source": {"path": "server.py"}}))
+
+        # Should find config when looking in the directory that contains it
+        found = MCPServerConfig.find_config(tmp_path)
+        assert found == config_file
+
+    def test_find_config_not_found(self, tmp_path):
+        """Test when config is not found."""
+        found = MCPServerConfig.find_config(tmp_path)
+        assert found is None
+
+    def test_invalid_transport(self, tmp_path):
+        """Test loading config with invalid transport value."""
+        config_data = {
+            "source": {"path": "server.py"},
+            "deployment": {"transport": "invalid_transport"},
+        }
+
+        config_file = tmp_path / "fastmcp.json"
+        config_file.write_text(json.dumps(config_data))
+
+        with pytest.raises(ValidationError):
+            MCPServerConfig.from_file(config_file)
+
+    def test_optional_sections(self):
+        """Test that all config sections are optional except source."""
+        # Only source is required
+        config = MCPServerConfig(source={"path": "server.py"})
+        assert isinstance(config.source, FileSystemSource)
+        assert config.source.path == "server.py"
+        # Environment and deployment are now always present but may be empty
+        assert isinstance(config.environment, UVEnvironment)
+        assert isinstance(config.deployment, Deployment)
+
+        # Only environment with values
+        config = MCPServerConfig(
+            source={"path": "server.py"}, environment={"python": "3.12"}
+        )
+        assert config.environment.python == "3.12"
+        assert isinstance(config.deployment, Deployment)
+        assert all(
+            getattr(config.deployment, field, None) is None
+            for field in Deployment.model_fields
+        )
+
+        # Only deployment with values
+        config = MCPServerConfig(
+            source={"path": "server.py"}, deployment={"transport": "http"}
+        )
+        assert isinstance(config.environment, UVEnvironment)
+        # Check all fields except 'type' which has a default value
+        assert all(
+            getattr(config.environment, field, None) is None
+            for field in UVEnvironment.model_fields
+            if field != "type"
+        )
+        assert config.deployment.transport == "http"
+
+
+class TestMCPServerConfigRoundtrip:
+    """Test that MCPServerConfig survives model_dump() -> reconstruct pattern.
+
+    This is used by the CLI to apply overrides immutably.
+    """
+
+    def test_roundtrip_preserves_schema(self):
+        """Ensure schema_ field survives dump/reconstruct cycle."""
+        config = MCPServerConfig(source=FileSystemSource(path="server.py"))
+        config_dict = config.model_dump()
+        reconstructed = MCPServerConfig(**config_dict)
+        assert reconstructed.schema_ == config.schema_
+
+    def test_roundtrip_with_all_fields(self):
+        """Full config survives dump/reconstruct."""
+        config = MCPServerConfig(
+            source=FileSystemSource(path="server.py", entrypoint="app"),
+            environment=UVEnvironment(python="3.11"),
+            deployment=Deployment(transport="http", port=8080),
+        )
+        config_dict = config.model_dump()
+        reconstructed = MCPServerConfig(**config_dict)
+        assert reconstructed.source.path == "server.py"
+        assert reconstructed.environment.python == "3.11"
+        assert reconstructed.deployment.port == 8080
diff --git a/tests/cli/test_cursor.py b/tests/cli/test_cursor.py
new file mode 100644
index 0000000..3996aee
--- /dev/null
+++ b/tests/cli/test_cursor.py
@@ -0,0 +1,448 @@
+import base64
+import json
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+import pytest
+
+from fastmcp.cli.install.cursor import (
+    cursor_command,
+    generate_cursor_deeplink,
+    install_cursor,
+    install_cursor_workspace,
+    open_deeplink,
+)
+from fastmcp.mcp_config import StdioMCPServer
+
+
+class TestCursorDeeplinkGeneration:
+    """Test cursor deeplink generation functionality."""
+
+    def test_generate_deeplink_basic(self):
+        """Test basic deeplink generation."""
+        server_config = StdioMCPServer(
+            command="uv",
+            args=["run", "--with", "fastmcp", "fastmcp", "run", "server.py"],
+        )
+
+        deeplink = generate_cursor_deeplink("test-server", server_config)
+
+        assert deeplink.startswith("cursor://anysphere.cursor-deeplink/mcp/install?")
+        assert "name=test-server" in deeplink
+        assert "config=" in deeplink
+
+        # Verify base64 encoding
+        config_part = deeplink.split("config=")[1]
+        decoded = base64.urlsafe_b64decode(config_part).decode()
+        config_data = json.loads(decoded)
+
+        assert config_data["command"] == "uv"
+        assert config_data["args"] == [
+            "run",
+            "--with",
+            "fastmcp",
+            "fastmcp",
+            "run",
+            "server.py",
+        ]
+
+    def test_generate_deeplink_with_env_vars(self):
+        """Test deeplink generation with environment variables."""
+        server_config = StdioMCPServer(
+            command="uv",
+            args=["run", "--with", "fastmcp", "fastmcp", "run", "server.py"],
+            env={"API_KEY": "secret123", "DEBUG": "true"},
+        )
+
+        deeplink = generate_cursor_deeplink("my-server", server_config)
+
+        # Decode and verify
+        config_part = deeplink.split("config=")[1]
+        decoded = base64.urlsafe_b64decode(config_part).decode()
+        config_data = json.loads(decoded)
+
+        assert config_data["env"] == {"API_KEY": "secret123", "DEBUG": "true"}
+
+    def test_generate_deeplink_special_characters(self):
+        """Test deeplink generation with special characters in server name."""
+        server_config = StdioMCPServer(
+            command="uv",
+            args=["run", "--with", "fastmcp", "fastmcp", "run", "server.py"],
+        )
+
+        # Test with spaces and special chars in name - should be URL encoded
+        deeplink = generate_cursor_deeplink("my server (test)", server_config)
+
+        # Spaces and parentheses must be URL-encoded
+        assert "name=my%20server%20%28test%29" in deeplink
+        # Ensure no unencoded version appears
+        assert "name=my server (test)" not in deeplink
+
+    def test_generate_deeplink_empty_config(self):
+        """Test deeplink generation with minimal config."""
+        server_config = StdioMCPServer(command="python", args=["server.py"])
+
+        deeplink = generate_cursor_deeplink("minimal", server_config)
+
+        config_part = deeplink.split("config=")[1]
+        decoded = base64.urlsafe_b64decode(config_part).decode()
+        config_data = json.loads(decoded)
+
+        assert config_data["command"] == "python"
+        assert config_data["args"] == ["server.py"]
+        assert config_data["env"] == {}  # Empty env dict is included
+
+    def test_generate_deeplink_complex_args(self):
+        """Test deeplink generation with complex arguments."""
+        server_config = StdioMCPServer(
+            command="uv",
+            args=[
+                "run",
+                "--with",
+                "fastmcp",
+                "--with",
+                "numpy>=1.20",
+                "--with-editable",
+                "/path/to/local/package",
+                "fastmcp",
+                "run",
+                "server.py:CustomServer",
+            ],
+        )
+
+        deeplink = generate_cursor_deeplink("complex-server", server_config)
+
+        config_part = deeplink.split("config=")[1]
+        decoded = base64.urlsafe_b64decode(config_part).decode()
+        config_data = json.loads(decoded)
+
+        assert "--with-editable" in config_data["args"]
+        assert "server.py:CustomServer" in config_data["args"]
+
+    def test_generate_deeplink_url_injection_protection(self):
+        """Test that special characters in server name are properly URL-encoded to prevent injection."""
+        server_config = StdioMCPServer(
+            command="python",
+            args=["server.py"],
+        )
+
+        # Test the PoC case from the security advisory
+        deeplink = generate_cursor_deeplink("test&calc", server_config)
+
+        # The & should be encoded as %26, preventing it from being interpreted as a query parameter separator
+        assert "name=test%26calc" in deeplink
+        assert "name=test&calc" not in deeplink
+
+        # Verify the URL structure is intact
+        assert deeplink.startswith("cursor://anysphere.cursor-deeplink/mcp/install?")
+        assert deeplink.count("&") == 1  # Only one & between name and config parameters
+
+        # Test other potentially dangerous characters
+        dangerous_names = [
+            ("test|calc", "test%7Ccalc"),
+            ("test;calc", "test%3Bcalc"),
+            ("test<calc", "test%3Ccalc"),
+            ("test>calc", "test%3Ecalc"),
+            ("test`calc", "test%60calc"),
+            ("test$calc", "test%24calc"),
+            ("test'calc", "test%27calc"),
+            ('test"calc', "test%22calc"),
+            ("test calc", "test%20calc"),
+            ("test#anchor", "test%23anchor"),
+            ("test?query=val", "test%3Fquery%3Dval"),
+        ]
+
+        for dangerous_name, expected_encoded in dangerous_names:
+            deeplink = generate_cursor_deeplink(dangerous_name, server_config)
+            assert f"name={expected_encoded}" in deeplink, (
+                f"Failed to encode {dangerous_name}"
+            )
+            # Ensure no unencoded special chars that could break URL structure
+            name_part = deeplink.split("name=")[1].split("&")[0]
+            assert name_part == expected_encoded
+
+
+class TestOpenDeeplink:
+    """Test deeplink opening functionality."""
+
+    @patch("subprocess.run")
+    def test_open_deeplink_macos(self, mock_run):
+        """Test opening deeplink on macOS."""
+        with patch("sys.platform", "darwin"):
+            mock_run.return_value = Mock(returncode=0)
+
+            result = open_deeplink("cursor://test")
+
+            assert result is True
+            mock_run.assert_called_once_with(
+                ["open", "cursor://test"], check=True, capture_output=True
+            )
+
+    def test_open_deeplink_windows(self):
+        """Test opening deeplink on Windows."""
+        with patch("sys.platform", "win32"):
+            with patch(
+                "fastmcp.cli.install.shared.os.startfile", create=True
+            ) as mock_startfile:
+                result = open_deeplink("cursor://test")
+
+                assert result is True
+                mock_startfile.assert_called_once_with("cursor://test")
+
+    @patch("subprocess.run")
+    def test_open_deeplink_linux(self, mock_run):
+        """Test opening deeplink on Linux."""
+        with patch("sys.platform", "linux"):
+            mock_run.return_value = Mock(returncode=0)
+
+            result = open_deeplink("cursor://test")
+
+            assert result is True
+            mock_run.assert_called_once_with(
+                ["xdg-open", "cursor://test"], check=True, capture_output=True
+            )
+
+    @patch("subprocess.run")
+    def test_open_deeplink_failure(self, mock_run):
+        """Test handling of deeplink opening failure."""
+        import subprocess
+
+        with patch("sys.platform", "darwin"):
+            mock_run.side_effect = subprocess.CalledProcessError(1, ["open"])
+
+            result = open_deeplink("cursor://test")
+
+            assert result is False
+
+    @patch("subprocess.run")
+    def test_open_deeplink_command_not_found(self, mock_run):
+        """Test handling when open command is not found."""
+        with patch("sys.platform", "darwin"):
+            mock_run.side_effect = FileNotFoundError()
+
+            result = open_deeplink("cursor://test")
+
+            assert result is False
+
+    def test_open_deeplink_invalid_scheme(self):
+        """Test that non-cursor:// URLs are rejected."""
+        result = open_deeplink("http://malicious.com")
+        assert result is False
+
+        result = open_deeplink("https://example.com")
+        assert result is False
+
+        result = open_deeplink("file:///etc/passwd")
+        assert result is False
+
+    def test_open_deeplink_valid_cursor_scheme(self):
+        """Test that cursor:// URLs are accepted."""
+        with patch("sys.platform", "darwin"):
+            with patch("subprocess.run") as mock_run:
+                mock_run.return_value = Mock(returncode=0)
+                result = open_deeplink("cursor://anysphere.cursor-deeplink/mcp/install")
+                assert result is True
+
+    def test_open_deeplink_empty_url(self):
+        """Test handling of empty URL."""
+        result = open_deeplink("")
+        assert result is False
+
+    def test_open_deeplink_windows_oserror(self):
+        """Test handling of OSError on Windows."""
+        with patch("sys.platform", "win32"):
+            with patch(
+                "fastmcp.cli.install.shared.os.startfile", create=True
+            ) as mock_startfile:
+                mock_startfile.side_effect = OSError("File not found")
+                result = open_deeplink("cursor://test")
+                assert result is False
+
+
+class TestInstallCursor:
+    """Test cursor installation functionality."""
+
+    @patch("fastmcp.cli.install.cursor.open_deeplink")
+    @patch("fastmcp.cli.install.cursor.print")
+    def test_install_cursor_success(self, mock_print, mock_open_deeplink):
+        """Test successful cursor installation."""
+        mock_open_deeplink.return_value = True
+
+        result = install_cursor(
+            file=Path("/path/to/server.py"),
+            server_object=None,
+            name="test-server",
+        )
+
+        assert result is True
+        mock_open_deeplink.assert_called_once()
+        # Verify the deeplink was generated correctly
+        call_args = mock_open_deeplink.call_args[0][0]
+        assert call_args.startswith("cursor://anysphere.cursor-deeplink/mcp/install?")
+        assert "name=test-server" in call_args
+
+    @patch("fastmcp.cli.install.cursor.open_deeplink")
+    @patch("fastmcp.cli.install.cursor.print")
+    def test_install_cursor_with_packages(self, mock_print, mock_open_deeplink):
+        """Test cursor installation with additional packages."""
+        mock_open_deeplink.return_value = True
+
+        result = install_cursor(
+            file=Path("/path/to/server.py"),
+            server_object="app",
+            name="test-server",
+            with_packages=["numpy", "pandas"],
+            env_vars={"API_KEY": "test"},
+        )
+
+        assert result is True
+        call_args = mock_open_deeplink.call_args[0][0]
+
+        # Decode the config to verify packages
+        config_part = call_args.split("config=")[1]
+        decoded = base64.urlsafe_b64decode(config_part).decode()
+        config_data = json.loads(decoded)
+
+        # Check that all packages are included
+        assert "--with" in config_data["args"]
+        assert "numpy" in config_data["args"]
+        assert "pandas" in config_data["args"]
+        assert "fastmcp" in config_data["args"]
+        assert config_data["env"] == {"API_KEY": "test"}
+
+    @patch("fastmcp.cli.install.cursor.open_deeplink")
+    @patch("fastmcp.cli.install.cursor.print")
+    def test_install_cursor_with_editable(self, mock_print, mock_open_deeplink):
+        """Test cursor installation with editable package."""
+        mock_open_deeplink.return_value = True
+
+        # Use an absolute path that works on all platforms
+        editable_path = Path.cwd() / "local" / "package"
+
+        result = install_cursor(
+            file=Path("/path/to/server.py"),
+            server_object="custom_app",
+            name="test-server",
+            with_editable=[editable_path],
+        )
+
+        assert result is True
+        call_args = mock_open_deeplink.call_args[0][0]
+
+        # Decode and verify editable path
+        config_part = call_args.split("config=")[1]
+        decoded = base64.urlsafe_b64decode(config_part).decode()
+        config_data = json.loads(decoded)
+
+        assert "--with-editable" in config_data["args"]
+        # Check that the path was resolved (should be absolute)
+        editable_idx = config_data["args"].index("--with-editable") + 1
+        resolved_path = config_data["args"][editable_idx]
+        assert Path(resolved_path).is_absolute()
+        assert "server.py:custom_app" in " ".join(config_data["args"])
+
+    @patch("fastmcp.cli.install.cursor.open_deeplink")
+    @patch("fastmcp.cli.install.cursor.print")
+    def test_install_cursor_failure(self, mock_print, mock_open_deeplink):
+        """Test cursor installation when deeplink fails to open."""
+        mock_open_deeplink.return_value = False
+
+        result = install_cursor(
+            file=Path("/path/to/server.py"),
+            server_object=None,
+            name="test-server",
+        )
+
+        assert result is False
+        # Verify failure message was printed
+        mock_print.assert_called()
+
+    def test_install_cursor_workspace_path_is_file(self, tmp_path):
+        """Test that passing a file as workspace_path returns False."""
+        file_path = tmp_path / "somefile.txt"
+        file_path.write_text("hello")
+
+        result = install_cursor_workspace(
+            file=Path("/path/to/server.py"),
+            server_object=None,
+            name="test-server",
+            workspace_path=file_path,
+        )
+
+        assert result is False
+
+    def test_install_cursor_deduplicate_packages(self):
+        """Test that duplicate packages are deduplicated."""
+        with patch("fastmcp.cli.install.cursor.open_deeplink") as mock_open:
+            mock_open.return_value = True
+
+            install_cursor(
+                file=Path("/path/to/server.py"),
+                server_object=None,
+                name="test-server",
+                with_packages=["numpy", "fastmcp", "numpy", "pandas", "fastmcp"],
+            )
+
+            call_args = mock_open.call_args[0][0]
+            config_part = call_args.split("config=")[1]
+            decoded = base64.urlsafe_b64decode(config_part).decode()
+            config_data = json.loads(decoded)
+
+            # Count occurrences of each package
+            args_str = " ".join(config_data["args"])
+            assert args_str.count("--with numpy") == 1
+            assert args_str.count("--with pandas") == 1
+            assert args_str.count("--with fastmcp") == 1
+
+
+class TestCursorCommand:
+    """Test the cursor CLI command."""
+
+    @patch("fastmcp.cli.install.cursor.install_cursor")
+    @patch("fastmcp.cli.install.cursor.process_common_args")
+    async def test_cursor_command_basic(self, mock_process_args, mock_install):
+        """Test basic cursor command execution."""
+        mock_process_args.return_value = (
+            Path("server.py"),
+            None,
+            "test-server",
+            [],
+            {},
+        )
+        mock_install.return_value = True
+
+        with patch("sys.exit") as mock_exit:
+            await cursor_command("server.py")
+
+        mock_install.assert_called_once_with(
+            file=Path("server.py"),
+            server_object=None,
+            name="test-server",
+            with_editable=[],
+            with_packages=[],
+            env_vars={},
+            python_version=None,
+            with_requirements=None,
+            project=None,
+            workspace=None,
+        )
+        mock_exit.assert_not_called()
+
+    @patch("fastmcp.cli.install.cursor.install_cursor")
+    @patch("fastmcp.cli.install.cursor.process_common_args")
+    async def test_cursor_command_failure(self, mock_process_args, mock_install):
+        """Test cursor command when installation fails."""
+        mock_process_args.return_value = (
+            Path("server.py"),
+            None,
+            "test-server",
+            [],
+            {},
+        )
+        mock_install.return_value = False
+
+        with pytest.raises(SystemExit) as exc_info:
+            await cursor_command("server.py")
+
+        assert isinstance(exc_info.value, SystemExit)
+        assert exc_info.value.code == 1
diff --git a/tests/cli/test_discovery.py b/tests/cli/test_discovery.py
new file mode 100644
index 0000000..7166943
--- /dev/null
+++ b/tests/cli/test_discovery.py
@@ -0,0 +1,668 @@
+"""Tests for MCP server discovery and name-based resolution."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+import yaml
+
+from fastmcp.cli.client import _is_http_target, resolve_server_spec
+from fastmcp.cli.discovery import (
+    DiscoveredServer,
+    _normalize_server_entry,
+    _parse_mcp_config,
+    _scan_claude_code,
+    _scan_claude_desktop,
+    _scan_cursor_workspace,
+    _scan_gemini,
+    _scan_goose,
+    _scan_project_mcp_json,
+    discover_servers,
+    resolve_name,
+)
+from fastmcp.client.transports.http import StreamableHttpTransport
+from fastmcp.client.transports.sse import SSETransport
+from fastmcp.client.transports.stdio import StdioTransport
+from fastmcp.mcp_config import RemoteMCPServer, StdioMCPServer
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_STDIO_CONFIG: dict[str, Any] = {
+    "mcpServers": {
+        "weather": {
+            "command": "npx",
+            "args": ["-y", "@mcp/weather"],
+        },
+        "github": {
+            "command": "npx",
+            "args": ["-y", "@mcp/github"],
+            "env": {"GITHUB_TOKEN": "xxx"},
+        },
+    }
+}
+
+_REMOTE_CONFIG: dict[str, Any] = {
+    "mcpServers": {
+        "api": {
+            "url": "http://localhost:8000/mcp",
+        },
+    }
+}
+
+
+def _write_config(path: Path, data: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data))
+
+
+# ---------------------------------------------------------------------------
+# DiscoveredServer properties
+# ---------------------------------------------------------------------------
+
+
+class TestDiscoveredServer:
+    def test_qualified_name(self):
+        server = DiscoveredServer(
+            name="weather",
+            source="claude-desktop",
+            config=StdioMCPServer(command="npx", args=["-y", "@mcp/weather"]),
+            config_path=Path("/fake/config.json"),
+        )
+        assert server.qualified_name == "claude-desktop:weather"
+
+    def test_transport_summary_stdio(self):
+        server = DiscoveredServer(
+            name="weather",
+            source="cursor",
+            config=StdioMCPServer(command="npx", args=["-y", "@mcp/weather"]),
+            config_path=Path("/fake/config.json"),
+        )
+        assert server.transport_summary == "stdio: npx -y @mcp/weather"
+
+    def test_transport_summary_remote(self):
+        server = DiscoveredServer(
+            name="api",
+            source="project",
+            config=RemoteMCPServer(url="http://localhost:8000/mcp"),
+            config_path=Path("/fake/config.json"),
+        )
+        assert server.transport_summary == "http: http://localhost:8000/mcp"
+
+    def test_transport_summary_remote_sse(self):
+        server = DiscoveredServer(
+            name="api",
+            source="project",
+            config=RemoteMCPServer(url="http://localhost:8000/sse", transport="sse"),
+            config_path=Path("/fake/config.json"),
+        )
+        assert server.transport_summary == "sse: http://localhost:8000/sse"
+
+
+# ---------------------------------------------------------------------------
+# _parse_mcp_config
+# ---------------------------------------------------------------------------
+
+
+class TestParseMcpConfig:
+    def test_valid_config(self, tmp_path: Path):
+        path = tmp_path / "config.json"
+        _write_config(path, _STDIO_CONFIG)
+        servers = _parse_mcp_config(path, "test-source")
+        assert len(servers) == 2
+        names = {s.name for s in servers}
+        assert names == {"weather", "github"}
+        assert all(s.source == "test-source" for s in servers)
+        assert all(s.config_path == path for s in servers)
+
+    def test_missing_file(self, tmp_path: Path):
+        path = tmp_path / "nonexistent.json"
+        servers = _parse_mcp_config(path, "test")
+        assert servers == []
+
+    def test_invalid_json(self, tmp_path: Path):
+        path = tmp_path / "bad.json"
+        path.write_text("{not json")
+        servers = _parse_mcp_config(path, "test")
+        assert servers == []
+
+    def test_no_mcp_servers_key(self, tmp_path: Path):
+        path = tmp_path / "config.json"
+        _write_config(path, {"something": "else"})
+        servers = _parse_mcp_config(path, "test")
+        assert servers == []
+
+    def test_empty_mcp_servers(self, tmp_path: Path):
+        path = tmp_path / "config.json"
+        _write_config(path, {"mcpServers": {}})
+        servers = _parse_mcp_config(path, "test")
+        assert servers == []
+
+    def test_remote_server(self, tmp_path: Path):
+        path = tmp_path / "config.json"
+        _write_config(path, _REMOTE_CONFIG)
+        servers = _parse_mcp_config(path, "test")
+        assert len(servers) == 1
+        assert isinstance(servers[0].config, RemoteMCPServer)
+        assert servers[0].config.url == "http://localhost:8000/mcp"
+
+
+# ---------------------------------------------------------------------------
+# Scanner: Claude Desktop
+# ---------------------------------------------------------------------------
+
+
+class TestScanClaudeDesktop:
+    def test_finds_config(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        config_dir = tmp_path / "Claude"
+        config_path = config_dir / "claude_desktop_config.json"
+        _write_config(config_path, _STDIO_CONFIG)
+
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+        # Force darwin for deterministic path
+        monkeypatch.setattr("fastmcp.cli.discovery.sys.platform", "darwin")
+
+        # We need to override the path construction. On macOS it's
+        # ~/Library/Application Support/Claude — create that.
+        mac_dir = tmp_path / "Library" / "Application Support" / "Claude"
+        mac_path = mac_dir / "claude_desktop_config.json"
+        _write_config(mac_path, _STDIO_CONFIG)
+
+        servers = _scan_claude_desktop()
+        assert len(servers) == 2
+        assert all(s.source == "claude-desktop" for s in servers)
+
+    def test_missing_config(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+        monkeypatch.setattr("fastmcp.cli.discovery.sys.platform", "darwin")
+        servers = _scan_claude_desktop()
+        assert servers == []
+
+
+# ---------------------------------------------------------------------------
+# Normalize server entry
+# ---------------------------------------------------------------------------
+
+
+class TestNormalizeServerEntry:
+    def test_remote_type_becomes_transport(self):
+        entry = {"url": "http://localhost:8000/sse", "type": "sse"}
+        result = _normalize_server_entry(entry)
+        assert result["transport"] == "sse"
+        assert "type" not in result
+
+    def test_remote_with_transport_unchanged(self):
+        entry = {"url": "http://localhost:8000/mcp", "transport": "http"}
+        result = _normalize_server_entry(entry)
+        assert result["transport"] == "http"
+
+    def test_stdio_type_unchanged(self):
+        """Stdio entries have ``type`` as a proper field — leave it alone."""
+        entry = {"command": "npx", "args": [], "type": "stdio"}
+        result = _normalize_server_entry(entry)
+        assert result["type"] == "stdio"
+
+    def test_gemini_http_url_becomes_url(self):
+        entry = {"httpUrl": "https://api.example.com/mcp/"}
+        result = _normalize_server_entry(entry)
+        assert result["url"] == "https://api.example.com/mcp/"
+        assert "httpUrl" not in result
+
+    def test_gemini_http_url_does_not_override_url(self):
+        entry = {"url": "http://real.com", "httpUrl": "http://other.com"}
+        result = _normalize_server_entry(entry)
+        assert result["url"] == "http://real.com"
+
+
+# ---------------------------------------------------------------------------
+# Scanner: Claude Code
+# ---------------------------------------------------------------------------
+
+
+def _claude_code_config(
+    *,
+    global_servers: dict[str, Any] | None = None,
+    project_path: str | None = None,
+    project_servers: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build a minimal ~/.claude.json structure."""
+    data: dict[str, Any] = {}
+    if global_servers is not None:
+        data["mcpServers"] = global_servers
+    if project_path and project_servers is not None:
+        data["projects"] = {project_path: {"mcpServers": project_servers}}
+    return data
+
+
+class TestScanClaudeCode:
+    def test_global_servers(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+        config_path = tmp_path / ".claude.json"
+        _write_config(
+            config_path,
+            _claude_code_config(global_servers=_STDIO_CONFIG["mcpServers"]),
+        )
+        servers = _scan_claude_code(tmp_path)
+        assert len(servers) == 2
+        assert all(s.source == "claude-code" for s in servers)
+
+    def test_project_servers(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+        project_dir = tmp_path / "my-project"
+        project_dir.mkdir()
+        config_path = tmp_path / ".claude.json"
+        _write_config(
+            config_path,
+            _claude_code_config(
+                project_path=str(project_dir),
+                project_servers={"api": {"url": "http://localhost:8000/mcp"}},
+            ),
+        )
+        servers = _scan_claude_code(project_dir)
+        assert len(servers) == 1
+        assert servers[0].name == "api"
+
+    def test_global_and_project_combined(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ):
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+        project_dir = tmp_path / "proj"
+        project_dir.mkdir()
+        config_path = tmp_path / ".claude.json"
+        _write_config(
+            config_path,
+            _claude_code_config(
+                global_servers={"global-tool": {"command": "echo", "args": ["hi"]}},
+                project_path=str(project_dir),
+                project_servers={"local-tool": {"command": "cat", "args": []}},
+            ),
+        )
+        servers = _scan_claude_code(project_dir)
+        names = {s.name for s in servers}
+        assert names == {"global-tool", "local-tool"}
+
+    def test_type_normalized_to_transport(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ):
+        """Claude Code uses ``type: sse`` — verify it becomes ``transport``."""
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+        config_path = tmp_path / ".claude.json"
+        _write_config(
+            config_path,
+            _claude_code_config(
+                global_servers={
+                    "sse-server": {
+                        "type": "sse",
+                        "url": "http://localhost:8000/sse",
+                    }
+                }
+            ),
+        )
+        servers = _scan_claude_code(tmp_path)
+        assert len(servers) == 1
+        assert isinstance(servers[0].config, RemoteMCPServer)
+        assert servers[0].config.transport == "sse"
+
+    def test_missing_file(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+        servers = _scan_claude_code(tmp_path)
+        assert servers == []
+
+    def test_no_matching_project(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+        config_path = tmp_path / ".claude.json"
+        _write_config(
+            config_path,
+            _claude_code_config(
+                project_path="/some/other/project",
+                project_servers={"tool": {"command": "echo", "args": []}},
+            ),
+        )
+        servers = _scan_claude_code(tmp_path)
+        assert servers == []
+
+
+# ---------------------------------------------------------------------------
+# Scanner: Cursor workspace
+# ---------------------------------------------------------------------------
+
+
+class TestScanCursorWorkspace:
+    def test_finds_config_in_cwd(self, tmp_path: Path):
+        cursor_path = tmp_path / ".cursor" / "mcp.json"
+        _write_config(cursor_path, _STDIO_CONFIG)
+        servers = _scan_cursor_workspace(tmp_path)
+        assert len(servers) == 2
+        assert all(s.source == "cursor" for s in servers)
+
+    def test_finds_config_in_parent(self, tmp_path: Path):
+        cursor_path = tmp_path / ".cursor" / "mcp.json"
+        _write_config(cursor_path, _STDIO_CONFIG)
+        child = tmp_path / "src" / "deep"
+        child.mkdir(parents=True)
+        servers = _scan_cursor_workspace(child)
+        assert len(servers) == 2
+
+    def test_stops_at_home(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        # Place config above home — should not be found
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+        above_home = tmp_path.parent / ".cursor" / "mcp.json"
+        _write_config(above_home, _STDIO_CONFIG)
+        child = tmp_path / "project"
+        child.mkdir()
+        servers = _scan_cursor_workspace(child)
+        assert servers == []
+
+    def test_no_config(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        # Confine walk to tmp_path so it doesn't find sibling test dirs
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+        servers = _scan_cursor_workspace(tmp_path)
+        assert servers == []
+
+
+# ---------------------------------------------------------------------------
+# Scanner: project mcp.json
+# ---------------------------------------------------------------------------
+
+
+class TestScanProjectMcpJson:
+    def test_finds_config(self, tmp_path: Path):
+        config_path = tmp_path / "mcp.json"
+        _write_config(config_path, _STDIO_CONFIG)
+        servers = _scan_project_mcp_json(tmp_path)
+        assert len(servers) == 2
+        assert all(s.source == "project" for s in servers)
+
+    def test_no_config(self, tmp_path: Path):
+        servers = _scan_project_mcp_json(tmp_path)
+        assert servers == []
+
+
+# ---------------------------------------------------------------------------
+# Scanner: Gemini CLI
+# ---------------------------------------------------------------------------
+
+
+class TestScanGemini:
+    def test_user_level_config(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+        config_path = tmp_path / ".gemini" / "settings.json"
+        _write_config(config_path, _STDIO_CONFIG)
+        servers = _scan_gemini(tmp_path)
+        assert len(servers) == 2
+        assert all(s.source == "gemini" for s in servers)
+
+    def test_project_level_config(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ):
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+        project_dir = tmp_path / "my-project"
+        project_dir.mkdir()
+        config_path = project_dir / ".gemini" / "settings.json"
+        _write_config(config_path, _STDIO_CONFIG)
+        servers = _scan_gemini(project_dir)
+        assert len(servers) == 2
+
+    def test_http_url_normalized(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        """Gemini uses ``httpUrl`` — verify it becomes ``url``."""
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+        config_path = tmp_path / ".gemini" / "settings.json"
+        _write_config(
+            config_path,
+            {
+                "mcpServers": {
+                    "api": {"httpUrl": "https://api.example.com/mcp/"},
+                }
+            },
+        )
+        servers = _scan_gemini(tmp_path)
+        assert len(servers) == 1
+        assert isinstance(servers[0].config, RemoteMCPServer)
+        assert servers[0].config.url == "https://api.example.com/mcp/"
+
+    def test_missing_config(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+        servers = _scan_gemini(tmp_path)
+        assert servers == []
+
+
+# ---------------------------------------------------------------------------
+# Scanner: Goose
+# ---------------------------------------------------------------------------
+
+_GOOSE_CONFIG = {
+    "extensions": {
+        "developer": {
+            "enabled": True,
+            "name": "developer",
+            "type": "builtin",
+        },
+        "tavily": {
+            "cmd": "npx",
+            "args": ["-y", "mcp-tavily-search"],
+            "enabled": True,
+            "envs": {"TAVILY_API_KEY": "xxx"},
+            "type": "stdio",
+        },
+        "disabled-tool": {
+            "cmd": "echo",
+            "args": ["hi"],
+            "enabled": False,
+            "type": "stdio",
+        },
+    }
+}
+
+
+class TestScanGoose:
+    def test_finds_stdio_extensions(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ):
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+        monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+        config_dir = tmp_path / ".config" / "goose"
+        config_path = config_dir / "config.yaml"
+        config_path.parent.mkdir(parents=True)
+        config_path.write_text(yaml.dump(_GOOSE_CONFIG))
+        # Force non-windows platform for path logic
+        monkeypatch.setattr("fastmcp.cli.discovery.sys.platform", "linux")
+        servers = _scan_goose()
+        assert len(servers) == 1
+        assert servers[0].name == "tavily"
+        assert servers[0].source == "goose"
+        assert isinstance(servers[0].config, StdioMCPServer)
+        assert servers[0].config.command == "npx"
+
+    def test_skips_builtin_and_disabled(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ):
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+        monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+        config_dir = tmp_path / ".config" / "goose"
+        config_path = config_dir / "config.yaml"
+        config_path.parent.mkdir(parents=True)
+        config_path.write_text(yaml.dump(_GOOSE_CONFIG))
+        monkeypatch.setattr("fastmcp.cli.discovery.sys.platform", "linux")
+        servers = _scan_goose()
+        names = {s.name for s in servers}
+        assert "developer" not in names
+        assert "disabled-tool" not in names
+
+    def test_missing_config(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+        monkeypatch.setattr("fastmcp.cli.discovery.sys.platform", "linux")
+        servers = _scan_goose()
+        assert servers == []
+
+
+# ---------------------------------------------------------------------------
+# discover_servers
+# ---------------------------------------------------------------------------
+
+
+def _suppress_user_scanners(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Suppress all scanners that read real user config files."""
+    monkeypatch.setattr("fastmcp.cli.discovery._scan_claude_desktop", lambda: [])
+    monkeypatch.setattr("fastmcp.cli.discovery._scan_claude_code", lambda start_dir: [])
+    monkeypatch.setattr("fastmcp.cli.discovery._scan_gemini", lambda start_dir: [])
+    monkeypatch.setattr("fastmcp.cli.discovery._scan_goose", lambda: [])
+
+
+class TestDiscoverServers:
+    def test_combines_sources(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        # Set up project mcp.json
+        project_config = tmp_path / "mcp.json"
+        _write_config(project_config, _STDIO_CONFIG)
+
+        # Set up cursor config
+        cursor_config = tmp_path / ".cursor" / "mcp.json"
+        _write_config(cursor_config, _REMOTE_CONFIG)
+
+        _suppress_user_scanners(monkeypatch)
+
+        servers = discover_servers(start_dir=tmp_path)
+        sources = {s.source for s in servers}
+        assert "project" in sources
+        assert "cursor" in sources
+        assert len(servers) == 3  # 2 from project + 1 from cursor
+
+    def test_preserves_duplicates(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ):
+        """Same server name in multiple sources should appear multiple times."""
+        project_config = tmp_path / "mcp.json"
+        _write_config(project_config, _STDIO_CONFIG)
+
+        cursor_config = tmp_path / ".cursor" / "mcp.json"
+        _write_config(cursor_config, _STDIO_CONFIG)
+
+        _suppress_user_scanners(monkeypatch)
+
+        servers = discover_servers(start_dir=tmp_path)
+        weather_servers = [s for s in servers if s.name == "weather"]
+        assert len(weather_servers) == 2
+        assert {s.source for s in weather_servers} == {"cursor", "project"}
+
+
+# ---------------------------------------------------------------------------
+# resolve_name
+# ---------------------------------------------------------------------------
+
+
+class TestResolveName:
+    @pytest.fixture(autouse=True)
+    def _isolate_scanners(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        """Suppress scanners that read real user configs and confine walks to tmp_path."""
+        _suppress_user_scanners(monkeypatch)
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+
+    def test_unique_match(self, tmp_path: Path):
+        config_path = tmp_path / "mcp.json"
+        _write_config(config_path, _STDIO_CONFIG)
+        transport = resolve_name("weather", start_dir=tmp_path)
+        assert isinstance(transport, StdioTransport)
+
+    def test_qualified_match(self, tmp_path: Path):
+        config_path = tmp_path / "mcp.json"
+        _write_config(config_path, _STDIO_CONFIG)
+        transport = resolve_name("project:weather", start_dir=tmp_path)
+        assert isinstance(transport, StdioTransport)
+
+    def test_not_found_with_servers(self, tmp_path: Path):
+        config_path = tmp_path / "mcp.json"
+        _write_config(config_path, _STDIO_CONFIG)
+        with pytest.raises(ValueError, match="No server named 'nope'.*Available"):
+            resolve_name("nope", start_dir=tmp_path)
+
+    def test_not_found_no_servers(self, tmp_path: Path):
+        with pytest.raises(ValueError, match="No server named 'nope'.*Searched"):
+            resolve_name("nope", start_dir=tmp_path)
+
+    def test_ambiguous_name(self, tmp_path: Path):
+        project_config = tmp_path / "mcp.json"
+        _write_config(project_config, _STDIO_CONFIG)
+        cursor_config = tmp_path / ".cursor" / "mcp.json"
+        _write_config(cursor_config, _STDIO_CONFIG)
+        with pytest.raises(ValueError, match="Ambiguous server name 'weather'"):
+            resolve_name("weather", start_dir=tmp_path)
+
+    def test_ambiguous_resolved_by_qualified(self, tmp_path: Path):
+        project_config = tmp_path / "mcp.json"
+        _write_config(project_config, _STDIO_CONFIG)
+        cursor_config = tmp_path / ".cursor" / "mcp.json"
+        _write_config(cursor_config, _STDIO_CONFIG)
+        transport = resolve_name("cursor:weather", start_dir=tmp_path)
+        assert isinstance(transport, StdioTransport)
+
+    def test_qualified_not_found(self, tmp_path: Path):
+        config_path = tmp_path / "mcp.json"
+        _write_config(config_path, _STDIO_CONFIG)
+        with pytest.raises(
+            ValueError, match="No server named 'nope' found in source 'project'"
+        ):
+            resolve_name("project:nope", start_dir=tmp_path)
+
+    def test_remote_server_resolves_to_http_transport(self, tmp_path: Path):
+        config_path = tmp_path / "mcp.json"
+        _write_config(config_path, _REMOTE_CONFIG)
+        transport = resolve_name("api", start_dir=tmp_path)
+        assert isinstance(transport, StreamableHttpTransport)
+
+
+# ---------------------------------------------------------------------------
+# Integration: resolve_server_spec falls through to name resolution
+# ---------------------------------------------------------------------------
+
+
+class TestResolveServerSpecNameFallback:
+    def test_bare_name_resolves(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        config_path = tmp_path / "mcp.json"
+        _write_config(config_path, _STDIO_CONFIG)
+        _suppress_user_scanners(monkeypatch)
+        monkeypatch.setattr("fastmcp.cli.discovery.Path.home", lambda: tmp_path)
+
+        # Monkeypatch resolve_name in client module to use our tmp_path
+        original_resolve = resolve_name
+
+        def patched_resolve(name: str, start_dir: Path | None = None) -> Any:
+            return original_resolve(name, start_dir=tmp_path)
+
+        monkeypatch.setattr("fastmcp.cli.client.resolve_name", patched_resolve)
+
+        result = resolve_server_spec("weather")
+        assert isinstance(result, StdioTransport)
+
+    def test_url_takes_priority_over_name(self):
+        """URLs should be resolved before name lookup."""
+        result = resolve_server_spec("http://localhost:8000/mcp")
+        assert result == "http://localhost:8000/mcp"
+
+
+# ---------------------------------------------------------------------------
+# Integration: _is_http_target detects transport objects
+# ---------------------------------------------------------------------------
+
+
+class TestIsHttpTargetTransports:
+    def test_streamable_http_transport(self):
+        transport = StreamableHttpTransport("http://localhost:8000/mcp")
+        assert _is_http_target(transport) is True
+
+    def test_sse_transport(self):
+        transport = SSETransport("http://localhost:8000/sse")
+        assert _is_http_target(transport) is True
+
+    def test_stdio_transport(self):
+        transport = StdioTransport(command="echo", args=["hello"])
+        assert _is_http_target(transport) is False
+
+    def test_string_url(self):
+        assert _is_http_target("http://localhost:8000") is True
+
+    def test_string_non_url(self):
+        assert _is_http_target("server.py") is False
+
+    def test_dict_config(self):
+        assert _is_http_target({"mcpServers": {}}) is False
diff --git a/tests/cli/test_fastmcp_remote.py b/tests/cli/test_fastmcp_remote.py
new file mode 100644
index 0000000..522bc01
--- /dev/null
+++ b/tests/cli/test_fastmcp_remote.py
@@ -0,0 +1,254 @@
+from pathlib import Path
+
+import pytest
+
+from fastmcp.client.auth import OAuth
+from fastmcp.client.transports import SSETransport, StreamableHttpTransport
+from fastmcp.tools import FunctionTool
+from fastmcp.utilities.versions import VersionSpec
+from fastmcp_remote.cli import (
+    IgnoreTools,
+    build_transport,
+    parse_args,
+    parse_header,
+    parse_verify,
+)
+
+
+def sample_tool() -> str:
+    return "ok"
+
+
+def test_parse_header_accepts_spaced_value():
+    assert parse_header("Authorization: Bearer token") == (
+        "Authorization",
+        "Bearer token",
+    )
+
+
+def test_parse_header_preserves_spaces_inside_value():
+    assert parse_header("X-Client-Name: My MCP Host") == (
+        "X-Client-Name",
+        "My MCP Host",
+    )
+
+
+def test_parse_header_preserves_colons_inside_value():
+    assert parse_header("X-Callback-Url: https://example.com/oauth/callback") == (
+        "X-Callback-Url",
+        "https://example.com/oauth/callback",
+    )
+
+
+def test_parse_header_expands_environment_variables_in_value(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    monkeypatch.setenv("AUTH_HEADER", "Bearer token with spaces")
+
+    assert parse_header("Authorization:${AUTH_HEADER}") == (
+        "Authorization",
+        "Bearer token with spaces",
+    )
+
+
+def test_parse_header_rejects_missing_environment_variable():
+    with pytest.raises(SystemExit):
+        parse_args(["https://example.com/mcp", "--header", "Authorization:${MISSING}"])
+
+
+def test_parse_header_accepts_unspaced_value():
+    assert parse_header("Authorization:Bearer token") == (
+        "Authorization",
+        "Bearer token",
+    )
+
+
+def test_parse_header_rejects_missing_colon():
+    with pytest.raises(SystemExit):
+        parse_args(["https://example.com/mcp", "--header", "Authorization"])
+
+
+def test_http_urls_are_allowed():
+    config = parse_args(["http://localhost:8000/mcp", "--auth", "none"])
+
+    assert config.url == "http://localhost:8000/mcp"
+
+
+def test_auth_defaults_to_oauth(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv("FASTMCP_REMOTE_CONFIG_DIR", str(tmp_path))
+    config = parse_args(["https://example.com/mcp"])
+
+    transport = build_transport(config)
+
+    assert isinstance(transport, StreamableHttpTransport)
+    assert isinstance(transport.auth, OAuth)
+
+
+def test_authorization_header_disables_oauth_by_default(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+    monkeypatch.setenv("FASTMCP_REMOTE_CONFIG_DIR", str(tmp_path))
+    config = parse_args(
+        [
+            "https://example.com/mcp",
+            "--header",
+            "Authorization: Bearer token",
+        ]
+    )
+
+    transport = build_transport(config)
+
+    assert isinstance(transport, StreamableHttpTransport)
+    assert transport.auth is None
+    assert transport.headers == {"Authorization": "Bearer token"}
+
+
+def test_explicit_oauth_keeps_oauth_with_authorization_header(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+    monkeypatch.setenv("FASTMCP_REMOTE_CONFIG_DIR", str(tmp_path))
+    config = parse_args(
+        [
+            "https://example.com/mcp",
+            "--header",
+            "Authorization: Bearer token",
+            "--auth",
+            "oauth",
+        ]
+    )
+
+    transport = build_transport(config)
+
+    assert isinstance(transport.auth, OAuth)
+
+
+def test_oauth_callback_options_pass_to_fastmcp_oauth(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+    monkeypatch.setenv("FASTMCP_REMOTE_CONFIG_DIR", str(tmp_path))
+    config = parse_args(
+        [
+            "https://example.com/mcp",
+            "8765",
+            "--host",
+            "127.0.0.1",
+            "--auth-timeout",
+            "12.5",
+        ]
+    )
+
+    transport = build_transport(config)
+
+    assert isinstance(transport.auth, OAuth)
+    assert transport.auth.context.client_metadata.redirect_uris is not None
+    assert str(transport.auth.context.client_metadata.redirect_uris[0]) == (
+        "http://127.0.0.1:8765/callback"
+    )
+    assert transport.auth._callback_timeout == 12.5
+
+
+def test_resource_isolates_token_storage(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+    monkeypatch.setenv("FASTMCP_REMOTE_CONFIG_DIR", str(tmp_path))
+    default_config = parse_args(["https://example.com/mcp"])
+    resource_config = parse_args(
+        ["https://example.com/mcp", "--resource", "linear-prod"]
+    )
+
+    assert default_config.storage_dir == tmp_path
+    assert resource_config.storage_dir.parent == tmp_path / "resources"
+    assert resource_config.storage_dir != default_config.storage_dir
+
+
+def test_sse_transport_strategy(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv("FASTMCP_REMOTE_CONFIG_DIR", str(tmp_path))
+    config = parse_args(["https://example.com/sse", "--transport", "sse"])
+
+    transport = build_transport(config)
+
+    assert isinstance(transport, SSETransport)
+
+
+@pytest.mark.parametrize("value", ["false", "False", "0", "no", "off"])
+def test_parse_verify_disables_verification(value: str):
+    assert parse_verify(value) is False
+
+
+@pytest.mark.parametrize("value", ["true", "True", "1", "yes", "on"])
+def test_parse_verify_enables_verification(value: str):
+    assert parse_verify(value) is True
+
+
+def test_parse_verify_treats_other_values_as_ca_bundle_path():
+    assert parse_verify("/etc/ssl/ca-bundle.pem") == "/etc/ssl/ca-bundle.pem"
+
+
+def test_verify_defaults_to_none(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv("FASTMCP_REMOTE_CONFIG_DIR", str(tmp_path))
+    config = parse_args(["https://example.com/mcp", "--auth", "none"])
+
+    assert config.verify is None
+    assert build_transport(config).verify is None
+
+
+def test_verify_false_disables_verification_on_transport(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+    monkeypatch.setenv("FASTMCP_REMOTE_CONFIG_DIR", str(tmp_path))
+    config = parse_args(
+        ["https://example.com/mcp", "--auth", "none", "--verify", "false"]
+    )
+
+    transport = build_transport(config)
+
+    assert config.verify is False
+    assert isinstance(transport, StreamableHttpTransport)
+    assert transport.verify is False
+
+
+def test_verify_ca_bundle_path_passes_to_transport(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+    monkeypatch.setenv("FASTMCP_REMOTE_CONFIG_DIR", str(tmp_path))
+    ca_bundle = "/etc/ssl/custom-ca.pem"
+    config = parse_args(
+        ["https://example.com/mcp", "--auth", "none", "--verify", ca_bundle]
+    )
+
+    assert build_transport(config).verify == ca_bundle
+
+
+def test_verify_passes_to_sse_transport(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+    monkeypatch.setenv("FASTMCP_REMOTE_CONFIG_DIR", str(tmp_path))
+    config = parse_args(
+        [
+            "https://example.com/sse",
+            "--transport",
+            "sse",
+            "--auth",
+            "none",
+            "--verify",
+            "false",
+        ]
+    )
+
+    transport = build_transport(config)
+
+    assert isinstance(transport, SSETransport)
+    assert transport.verify is False
+
+
+async def test_ignore_tools_transform_filters_matching_names():
+    tool = FunctionTool.from_function(sample_tool, name="delete_user")
+    transform = IgnoreTools(["delete*"])
+
+    async def call_next(
+        name: str, *, version: VersionSpec | None = None
+    ) -> FunctionTool:
+        return tool
+
+    assert await transform.list_tools([tool]) == []
+    assert await transform.get_tool("delete_user", call_next) is None
diff --git a/tests/cli/test_generate_cli.py b/tests/cli/test_generate_cli.py
new file mode 100644
index 0000000..63cd23b
--- /dev/null
+++ b/tests/cli/test_generate_cli.py
@@ -0,0 +1,918 @@
+"""Tests for fastmcp generate-cli command."""
+
+import sys
+from pathlib import Path
+from typing import Any
+from unittest.mock import patch
+
+import mcp_types
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.cli import generate as generate_module
+from fastmcp.cli.client import Client
+from fastmcp.cli.generate import (
+    _derive_server_name,
+    _param_to_cli_flag,
+    _schema_to_python_type,
+    _schema_type_label,
+    _to_python_identifier,
+    _tool_function_source,
+    generate_cli_command,
+    generate_cli_script,
+    generate_skill_content,
+    serialize_transport,
+)
+from fastmcp.client.transports.stdio import StdioTransport
+
+# ---------------------------------------------------------------------------
+# _schema_to_python_type
+# ---------------------------------------------------------------------------
+
+
+class TestSchemaToPythonType:
+    def test_simple_string(self):
+        py_type, needs_json = _schema_to_python_type({"type": "string"})
+        assert py_type == "str"
+        assert needs_json is False
+
+    def test_simple_integer(self):
+        py_type, needs_json = _schema_to_python_type({"type": "integer"})
+        assert py_type == "int"
+        assert needs_json is False
+
+    def test_simple_number(self):
+        py_type, needs_json = _schema_to_python_type({"type": "number"})
+        assert py_type == "float"
+        assert needs_json is False
+
+    def test_simple_boolean(self):
+        py_type, needs_json = _schema_to_python_type({"type": "boolean"})
+        assert py_type == "bool"
+        assert needs_json is False
+
+    def test_array_of_strings(self):
+        py_type, needs_json = _schema_to_python_type(
+            {"type": "array", "items": {"type": "string"}}
+        )
+        assert py_type == "list[str]"
+        assert needs_json is False
+
+    def test_array_of_integers(self):
+        py_type, needs_json = _schema_to_python_type(
+            {"type": "array", "items": {"type": "integer"}}
+        )
+        assert py_type == "list[int]"
+        assert needs_json is False
+
+    def test_complex_object(self):
+        py_type, needs_json = _schema_to_python_type({"type": "object"})
+        assert py_type == "str"
+        assert needs_json is True
+
+    def test_complex_nested_array(self):
+        py_type, needs_json = _schema_to_python_type(
+            {"type": "array", "items": {"type": "object"}}
+        )
+        assert py_type == "str"
+        assert needs_json is True
+
+    def test_union_of_simple_types(self):
+        py_type, needs_json = _schema_to_python_type({"type": ["string", "null"]})
+        assert py_type == "str | None"
+        assert needs_json is False
+
+
+# ---------------------------------------------------------------------------
+# _to_python_identifier
+# ---------------------------------------------------------------------------
+
+
+class TestToPythonIdentifier:
+    def test_plain_name(self):
+        assert _to_python_identifier("hello") == "hello"
+
+    def test_hyphens(self):
+        assert _to_python_identifier("get-forecast") == "get_forecast"
+
+    def test_dots_and_slashes(self):
+        assert _to_python_identifier("a.b/c") == "a_b_c"
+
+    def test_leading_digit(self):
+        assert _to_python_identifier("3d_render") == "_3d_render"
+
+    def test_spaces(self):
+        assert _to_python_identifier("my tool") == "my_tool"
+
+    def test_empty_string(self):
+        assert _to_python_identifier("") == "_unnamed"
+
+
+# ---------------------------------------------------------------------------
+# serialize_transport
+# ---------------------------------------------------------------------------
+
+
+class TestSerializeTransport:
+    def test_url_string(self):
+        code, imports = serialize_transport("http://localhost:8000/mcp")
+        assert code == "'http://localhost:8000/mcp'"
+        assert imports == set()
+
+    def test_stdio_transport_basic(self):
+        transport = StdioTransport(command="fastmcp", args=["run", "server.py"])
+        code, imports = serialize_transport(transport)
+        assert "StdioTransport" in code
+        assert "command='fastmcp'" in code
+        assert "args=['run', 'server.py']" in code
+        assert "from fastmcp.client.transports import StdioTransport" in imports
+
+    def test_stdio_transport_with_env(self):
+        transport = StdioTransport(
+            command="python", args=["-m", "myserver"], env={"KEY": "val"}
+        )
+        code, imports = serialize_transport(transport)
+        assert "env={'KEY': 'val'}" in code
+
+    def test_dict_passthrough(self):
+        d: dict[str, Any] = {"mcpServers": {"test": {"url": "http://localhost"}}}
+        code, imports = serialize_transport(d)
+        assert "mcpServers" in code
+        assert imports == set()
+
+
+# ---------------------------------------------------------------------------
+# _tool_function_source
+# ---------------------------------------------------------------------------
+
+
+class TestToolFunctionSource:
+    def test_required_param(self):
+        tool = mcp_types.Tool(
+            name="greet",
+            input_schema={
+                "properties": {"name": {"type": "string", "description": "Who"}},
+                "required": ["name"],
+            },
+        )
+        source = _tool_function_source(tool)
+        assert "async def greet(" in source
+        assert "name: Annotated[str" in source
+        assert "= None" not in source
+        assert "_call_tool('greet', {'name': name})" in source
+
+    def test_optional_param(self):
+        tool = mcp_types.Tool(
+            name="search",
+            input_schema={
+                "properties": {
+                    "query": {"type": "string", "description": "Search query"},
+                    "limit": {"type": "integer", "description": "Max results"},
+                },
+                "required": ["query"],
+            },
+        )
+        source = _tool_function_source(tool)
+        assert "query: Annotated[str" in source
+        assert "limit: Annotated[int | None" in source
+        assert "= None" in source
+
+    def test_param_with_default(self):
+        tool = mcp_types.Tool(
+            name="fetch",
+            input_schema={
+                "properties": {
+                    "url": {"type": "string", "description": "URL"},
+                    "timeout": {
+                        "type": "integer",
+                        "description": "Timeout",
+                        "default": 30,
+                    },
+                },
+                "required": ["url"],
+            },
+        )
+        source = _tool_function_source(tool)
+        assert "timeout: Annotated[int" in source
+        assert "= 30" in source
+
+    def test_no_params(self):
+        tool = mcp_types.Tool(
+            name="ping",
+            input_schema={"properties": {}},
+        )
+        source = _tool_function_source(tool)
+        assert "async def ping(" in source
+        assert "_call_tool('ping', {})" in source
+
+    def test_preserves_underscores(self):
+        tool = mcp_types.Tool(
+            name="get_forecast",
+            input_schema={
+                "properties": {"city": {"type": "string"}},
+                "required": ["city"],
+            },
+        )
+        source = _tool_function_source(tool)
+        assert "async def get_forecast(" in source
+
+    def test_sanitizes_tool_name(self):
+        tool = mcp_types.Tool(
+            name="my.tool/v2",
+            input_schema={"properties": {}},
+        )
+        source = _tool_function_source(tool)
+        assert "async def my_tool_v2(" in source
+        assert "name='my.tool/v2'" in source
+
+    def test_sanitizes_param_name(self):
+        tool = mcp_types.Tool(
+            name="fetch",
+            input_schema={
+                "properties": {"content-type": {"type": "string", "description": "CT"}},
+                "required": ["content-type"],
+            },
+        )
+        source = _tool_function_source(tool)
+        assert "content_type: Annotated[str" in source
+        assert "'content-type': content_type" in source
+
+    def test_description_in_docstring(self):
+        tool = mcp_types.Tool(
+            name="greet",
+            description="Say hello to someone.",
+            input_schema={
+                "properties": {"name": {"type": "string"}},
+                "required": ["name"],
+            },
+        )
+        source = _tool_function_source(tool)
+        assert "'''Say hello to someone.'''" in source
+
+    def test_description_with_quotes(self):
+        tool = mcp_types.Tool(
+            name="fetch",
+            description="Fetch data from 'source' API.",
+            input_schema={
+                "properties": {"url": {"type": "string"}},
+                "required": ["url"],
+            },
+        )
+        source = _tool_function_source(tool)
+        # Should escape single quotes in the description
+        assert r"Fetch data from \'source\' API." in source
+        # Generated code should compile
+        compile(source, "<test>", "exec")
+
+    def test_array_of_strings_parameter(self):
+        tool = mcp_types.Tool(
+            name="tag_items",
+            description="Tag multiple items.",
+            input_schema={
+                "properties": {
+                    "item_id": {"type": "string"},
+                    "tags": {"type": "array", "items": {"type": "string"}},
+                },
+                "required": ["item_id"],
+            },
+        )
+        source = _tool_function_source(tool)
+        # Should use list[str] type with help metadata
+        assert "tags: Annotated[list[str]" in source
+        assert "= []" in source
+        # Should not have JSON parsing for simple arrays
+        assert "json.loads" not in source
+        compile(source, "<test>", "exec")
+
+    def test_complex_object_parameter(self):
+        tool = mcp_types.Tool(
+            name="create_user",
+            description="Create a user.",
+            input_schema={
+                "properties": {
+                    "name": {"type": "string"},
+                    "metadata": {
+                        "type": "object",
+                        "properties": {
+                            "role": {"type": "string"},
+                            "dept": {"type": "string"},
+                        },
+                    },
+                },
+                "required": ["name"],
+            },
+        )
+        source = _tool_function_source(tool)
+        # Should use str type for complex object
+        assert "metadata: Annotated[str | None" in source
+        # Should include JSON schema in help (with escaped quotes)
+        assert "JSON Schema:" in source
+        assert '\\"type\\": \\"object\\"' in source
+        # Should have JSON parsing with isinstance check
+        assert (
+            "metadata_parsed = json.loads(metadata) if isinstance(metadata, str) else metadata"
+            in source
+        )
+        # Should use parsed version in call
+        assert "'metadata': metadata_parsed" in source
+        compile(source, "<test>", "exec")
+
+    def test_nested_array_parameter(self):
+        tool = mcp_types.Tool(
+            name="batch_process",
+            description="Process batches.",
+            input_schema={
+                "properties": {
+                    "batches": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {"id": {"type": "string"}},
+                        },
+                    },
+                },
+                "required": ["batches"],
+            },
+        )
+        source = _tool_function_source(tool)
+        # Nested arrays need JSON parsing
+        assert "batches: Annotated[str" in source
+        assert "JSON Schema:" in source
+        assert (
+            "batches_parsed = json.loads(batches) if isinstance(batches, str) else batches"
+            in source
+        )
+        compile(source, "<test>", "exec")
+
+    def test_complex_type_with_default(self):
+        """Test that complex types with defaults are JSON-serialized."""
+        tool = mcp_types.Tool(
+            name="configure",
+            input_schema={
+                "properties": {
+                    "options": {
+                        "type": "object",
+                        "default": {"timeout": 30, "retry": True},
+                    },
+                },
+            },
+        )
+        source = _tool_function_source(tool)
+        # Default should be JSON string, not Python dict
+        # pydantic_core.to_json produces compact JSON
+        assert '= \'{"timeout":30,"retry":true}\'' in source
+        # Should parse safely even with default
+        assert "isinstance(options, str)" in source
+        compile(source, "<test>", "exec")
+
+    def test_name_collision_detection(self):
+        """Test that parameter name collisions are detected."""
+        tool = mcp_types.Tool(
+            name="test",
+            input_schema={
+                "properties": {
+                    "content-type": {"type": "string"},
+                    "content_type": {"type": "string"},
+                },
+            },
+        )
+        # Should raise ValueError for collision
+        with pytest.raises(ValueError, match="both sanitize to 'content_type'"):
+            _tool_function_source(tool)
+
+
+# ---------------------------------------------------------------------------
+# _derive_server_name
+# ---------------------------------------------------------------------------
+
+
+class TestDeriveServerName:
+    def test_bare_name(self):
+        assert _derive_server_name("weather") == "weather"
+
+    def test_qualified_name(self):
+        assert _derive_server_name("cursor:weather") == "weather"
+
+    def test_python_file(self):
+        assert _derive_server_name("server.py") == "server"
+
+    def test_url(self):
+        assert _derive_server_name("http://localhost:8000/mcp") == "localhost"
+
+    def test_trailing_colon(self):
+        assert _derive_server_name("source:") == "source"
+
+
+# ---------------------------------------------------------------------------
+# generate_cli_script — produces compilable Python
+# ---------------------------------------------------------------------------
+
+
+class TestGenerateCliScript:
+    def _make_tools(self) -> list[mcp_types.Tool]:
+        return [
+            mcp_types.Tool(
+                name="greet",
+                description="Say hello",
+                input_schema={
+                    "properties": {
+                        "name": {"type": "string", "description": "Who to greet"},
+                    },
+                    "required": ["name"],
+                },
+            ),
+            mcp_types.Tool(
+                name="add_numbers",
+                description="Add two numbers",
+                input_schema={
+                    "properties": {
+                        "a": {"type": "integer", "description": "First number"},
+                        "b": {"type": "integer", "description": "Second number"},
+                    },
+                    "required": ["a", "b"],
+                },
+            ),
+        ]
+
+    def test_compiles(self):
+        script = generate_cli_script(
+            server_name="test",
+            server_spec="test",
+            transport_code='"http://localhost:8000/mcp"',
+            extra_imports=set(),
+            tools=self._make_tools(),
+        )
+        compile(script, "<generated>", "exec")
+
+    def test_contains_tool_functions(self):
+        script = generate_cli_script(
+            server_name="test",
+            server_spec="test",
+            transport_code='"http://localhost:8000/mcp"',
+            extra_imports=set(),
+            tools=self._make_tools(),
+        )
+        assert "async def greet(" in script
+        assert "async def add_numbers(" in script
+
+    def test_contains_generic_commands(self):
+        script = generate_cli_script(
+            server_name="test",
+            server_spec="test",
+            transport_code='"http://localhost:8000/mcp"',
+            extra_imports=set(),
+            tools=[],
+        )
+        assert "async def list_tools(" in script
+        assert "async def list_resources(" in script
+        assert "async def list_prompts(" in script
+        assert "async def read_resource(" in script
+        assert "async def get_prompt(" in script
+
+    def test_embeds_transport(self):
+        script = generate_cli_script(
+            server_name="test",
+            server_spec="test",
+            transport_code="StdioTransport(command='fastmcp', args=['run', 'x.py'])",
+            extra_imports={"from fastmcp.client.transports import StdioTransport"},
+            tools=[],
+        )
+        assert "StdioTransport(command='fastmcp'" in script
+        assert "from fastmcp.client.transports import StdioTransport" in script
+
+    def test_no_tools_still_valid(self):
+        script = generate_cli_script(
+            server_name="empty",
+            server_spec="empty",
+            transport_code='"http://localhost"',
+            extra_imports=set(),
+            tools=[],
+        )
+        compile(script, "<generated>", "exec")
+        assert "call_tool_app" in script
+
+    def test_server_name_with_quotes(self):
+        """Test that server names with quotes are properly escaped."""
+        script = generate_cli_script(
+            server_name='Test "Server" Name',
+            server_spec="test",
+            transport_code='"http://localhost"',
+            extra_imports=set(),
+            tools=[],
+        )
+        # Should compile without syntax errors
+        compile(script, "<generated>", "exec")
+        # App name should have escaped quotes
+        assert r'app = cyclopts.App(name="test-\"server\"-name"' in script
+
+    def test_compiles_with_unusual_names(self):
+        tools = [
+            mcp_types.Tool(
+                name="my.tool/v2",
+                description="A tool with dots and slashes",
+                input_schema={
+                    "properties": {
+                        "content-type": {"type": "string", "description": "CT"},
+                    },
+                    "required": ["content-type"],
+                },
+            ),
+        ]
+        script = generate_cli_script(
+            server_name="test",
+            server_spec="test",
+            transport_code='"http://localhost:8000/mcp"',
+            extra_imports=set(),
+            tools=tools,
+        )
+        compile(script, "<generated>", "exec")
+
+    def test_compiles_with_stdio_transport(self):
+        transport = StdioTransport(command="fastmcp", args=["run", "server.py"])
+        transport_code, extra_imports = serialize_transport(transport)
+        script = generate_cli_script(
+            server_name="test",
+            server_spec="server.py",
+            transport_code=transport_code,
+            extra_imports=extra_imports,
+            tools=self._make_tools(),
+        )
+        compile(script, "<generated>", "exec")
+
+
+# ---------------------------------------------------------------------------
+# generate_cli_command — integration tests
+# ---------------------------------------------------------------------------
+
+
+def _build_test_server() -> FastMCP:
+    """Create a minimal FastMCP server for integration tests."""
+    server = FastMCP("TestServer")
+
+    @server.tool
+    def greet(name: str) -> str:
+        """Say hello to someone."""
+        return f"Hello, {name}!"
+
+    @server.tool
+    def add(a: int, b: int) -> int:
+        """Add two numbers."""
+        return a + b
+
+    @server.resource("test://greeting")
+    def greeting_resource() -> str:
+        """A static greeting resource."""
+        return "Hello from resource!"
+
+    @server.prompt
+    def ask(topic: str) -> str:
+        """Ask about a topic."""
+        return f"Tell me about {topic}"
+
+    return server
+
+
+@pytest.fixture()
+def _patch_client():
+    """Patch resolve_server_spec and _build_client to use an in-process server."""
+    server = _build_test_server()
+
+    def fake_resolve(server_spec: Any, **kwargs: Any) -> str:
+        return "fake://server"
+
+    def fake_build_client(resolved: Any, **kwargs: Any) -> Client:
+        return Client(server)
+
+    with (
+        patch.object(generate_module, "resolve_server_spec", side_effect=fake_resolve),
+        patch.object(generate_module, "_build_client", side_effect=fake_build_client),
+    ):
+        yield
+
+
+class TestGenerateCliCommand:
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_writes_file(self, tmp_path: Path):
+        output = tmp_path / "cli.py"
+        await generate_cli_command("test-server", str(output))
+        assert output.exists()
+        content = output.read_text()
+        compile(content, str(output), "exec")
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_contains_tools(self, tmp_path: Path):
+        output = tmp_path / "cli.py"
+        await generate_cli_command("test-server", str(output))
+        content = output.read_text()
+        assert "async def greet(" in content
+        assert "async def add(" in content
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_default_output_path(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ):
+        monkeypatch.chdir(tmp_path)
+        await generate_cli_command("test-server")
+        assert (tmp_path / "cli.py").exists()
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_error_if_exists(self, tmp_path: Path):
+        output = tmp_path / "cli.py"
+        output.write_text("existing")
+        with pytest.raises(SystemExit):
+            await generate_cli_command("test-server", str(output))
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_force_overwrites(self, tmp_path: Path):
+        output = tmp_path / "cli.py"
+        output.write_text("existing")
+        await generate_cli_command("test-server", str(output), force=True)
+        content = output.read_text()
+        assert content != "existing"
+        assert "async def greet(" in content
+
+    @pytest.mark.skipif(
+        sys.platform == "win32", reason="Unix executable bits N/A on Windows"
+    )
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_file_is_executable(self, tmp_path: Path):
+        output = tmp_path / "cli.py"
+        await generate_cli_command("test-server", str(output))
+        assert output.stat().st_mode & 0o111
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_writes_skill_file(self, tmp_path: Path):
+        output = tmp_path / "cli.py"
+        await generate_cli_command("test-server", str(output))
+        skill_path = tmp_path / "SKILL.md"
+        assert skill_path.exists()
+        content = skill_path.read_text()
+        assert "---" in content
+        assert "name:" in content
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_skill_contains_tools(self, tmp_path: Path):
+        output = tmp_path / "cli.py"
+        await generate_cli_command("test-server", str(output))
+        content = (tmp_path / "SKILL.md").read_text()
+        assert "### greet" in content
+        assert "### add" in content
+        assert "--name" in content
+        assert "call-tool greet" in content
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_no_skill_flag(self, tmp_path: Path):
+        output = tmp_path / "cli.py"
+        await generate_cli_command("test-server", str(output), no_skill=True)
+        assert not (tmp_path / "SKILL.md").exists()
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_error_if_skill_exists(self, tmp_path: Path):
+        output = tmp_path / "cli.py"
+        (tmp_path / "SKILL.md").write_text("existing")
+        with pytest.raises(SystemExit):
+            await generate_cli_command("test-server", str(output))
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_force_overwrites_skill(self, tmp_path: Path):
+        output = tmp_path / "cli.py"
+        (tmp_path / "SKILL.md").write_text("existing")
+        await generate_cli_command("test-server", str(output), force=True)
+        content = (tmp_path / "SKILL.md").read_text()
+        assert content != "existing"
+        assert "### greet" in content
+
+    @pytest.mark.usefixtures("_patch_client")
+    async def test_skill_references_cli_filename(self, tmp_path: Path):
+        output = tmp_path / "my_weather.py"
+        await generate_cli_command("test-server", str(output))
+        content = (tmp_path / "SKILL.md").read_text()
+        assert "uv run --with fastmcp python my_weather.py" in content
+
+
+# ---------------------------------------------------------------------------
+# _param_to_cli_flag
+# ---------------------------------------------------------------------------
+
+
+class TestParamToCliFlag:
+    def test_simple_name(self):
+        assert _param_to_cli_flag("city") == "--city"
+
+    def test_underscore_name(self):
+        assert _param_to_cli_flag("max_days") == "--max-days"
+
+    def test_hyphenated_name(self):
+        # content-type → _to_python_identifier → content_type → --content-type
+        assert _param_to_cli_flag("content-type") == "--content-type"
+
+    def test_digit_prefix(self):
+        # 3d_mode → _3d_mode → --3d-mode (leading underscore stripped)
+        assert _param_to_cli_flag("3d_mode") == "--3d-mode"
+
+    def test_trailing_underscore(self):
+        # from → from_ after identifier sanitization; Cyclopts strips trailing "-"
+        assert _param_to_cli_flag("from") == "--from"
+
+    def test_camel_case(self):
+        # camelCase → camel-case (cyclopts default_name_transform)
+        assert _param_to_cli_flag("myParam") == "--my-param"
+
+    def test_pascal_case(self):
+        assert _param_to_cli_flag("MyParam") == "--my-param"
+
+
+# ---------------------------------------------------------------------------
+# _schema_type_label
+# ---------------------------------------------------------------------------
+
+
+class TestSchemaTypeLabel:
+    def test_simple_string(self):
+        assert _schema_type_label({"type": "string"}) == "string"
+
+    def test_integer(self):
+        assert _schema_type_label({"type": "integer"}) == "integer"
+
+    def test_array_of_strings(self):
+        assert (
+            _schema_type_label({"type": "array", "items": {"type": "string"}})
+            == "array[string]"
+        )
+
+    def test_union_types(self):
+        result = _schema_type_label({"type": ["string", "null"]})
+        assert "string" in result
+        assert "null" in result
+
+    def test_object(self):
+        assert _schema_type_label({"type": "object"}) == "object"
+
+    def test_missing_type(self):
+        assert _schema_type_label({}) == "string"
+
+
+# ---------------------------------------------------------------------------
+# generate_skill_content
+# ---------------------------------------------------------------------------
+
+
+class TestGenerateSkillContent:
+    def test_frontmatter(self):
+        content = generate_skill_content("weather", "cli.py", [])
+        assert content.startswith("---\n")
+        assert 'name: "weather-cli"' in content
+        assert "description:" in content
+
+    def test_no_tools(self):
+        content = generate_skill_content("weather", "cli.py", [])
+        assert "## Utility Commands" in content
+        assert "## Tool Commands" not in content
+
+    def test_tool_sections(self):
+        tools = [
+            mcp_types.Tool(
+                name="greet",
+                description="Say hello",
+                input_schema={
+                    "type": "object",
+                    "properties": {
+                        "name": {"type": "string", "description": "Who to greet"}
+                    },
+                    "required": ["name"],
+                },
+            ),
+        ]
+        content = generate_skill_content("test", "cli.py", tools)
+        assert "## Tool Commands" in content
+        assert "### greet" in content
+        assert "Say hello" in content
+        assert "call-tool greet" in content
+        assert "`--name`" in content
+        assert "| string |" in content
+        assert "| yes |" in content
+
+    def test_frontmatter_with_tools_starts_at_column_zero(self):
+        tools = [
+            mcp_types.Tool(
+                name="greet",
+                input_schema={"type": "object", "properties": {}},
+            ),
+        ]
+        content = generate_skill_content("weather", "cli.py", tools)
+        assert content.splitlines()[0] == "---"
+
+    def test_optional_param(self):
+        tools = [
+            mcp_types.Tool(
+                name="search",
+                description="Search things",
+                input_schema={
+                    "type": "object",
+                    "properties": {
+                        "query": {"type": "string"},
+                        "limit": {"type": "integer"},
+                    },
+                    "required": ["query"],
+                },
+            ),
+        ]
+        content = generate_skill_content("test", "cli.py", tools)
+        # query is required, limit is not
+        assert "| `--query` | string | yes |" in content
+        assert "| `--limit` | integer | no |" in content
+
+    def test_complex_json_param(self):
+        tools = [
+            mcp_types.Tool(
+                name="create",
+                description="Create item",
+                input_schema={
+                    "type": "object",
+                    "properties": {
+                        "data": {
+                            "type": "object",
+                            "properties": {"x": {"type": "integer"}},
+                        },
+                    },
+                    "required": ["data"],
+                },
+            ),
+        ]
+        content = generate_skill_content("test", "cli.py", tools)
+        assert "JSON string" in content
+
+    def test_no_params_tool(self):
+        tools = [
+            mcp_types.Tool(
+                name="ping",
+                description="Ping the server",
+                input_schema={"type": "object", "properties": {}},
+            ),
+        ]
+        content = generate_skill_content("test", "cli.py", tools)
+        assert "### ping" in content
+        assert "call-tool ping" in content
+        # No parameter table
+        assert "| Flag |" not in content
+
+    def test_cli_filename_in_utility_commands(self):
+        content = generate_skill_content("test", "my_cli.py", [])
+        assert "uv run --with fastmcp python my_cli.py list-tools" in content
+        assert "uv run --with fastmcp python my_cli.py list-resources" in content
+
+    def test_pipe_in_description_escaped(self):
+        tools = [
+            mcp_types.Tool(
+                name="test",
+                description="Test",
+                input_schema={
+                    "type": "object",
+                    "properties": {
+                        "mode": {"type": "string", "description": "a|b|c"},
+                    },
+                },
+            ),
+        ]
+        content = generate_skill_content("test", "cli.py", tools)
+        assert "a\\|b\\|c" in content
+
+    def test_union_type_pipes_escaped(self):
+        tools = [
+            mcp_types.Tool(
+                name="test",
+                description="Test",
+                input_schema={
+                    "type": "object",
+                    "properties": {
+                        "val": {"type": ["string", "null"]},
+                    },
+                },
+            ),
+        ]
+        content = generate_skill_content("test", "cli.py", tools)
+        # Pipes in type label must be escaped so markdown table renders correctly
+        assert "string \\| null" in content
+
+    def test_boolean_param_no_value_placeholder(self):
+        tools = [
+            mcp_types.Tool(
+                name="run",
+                description="Run something",
+                input_schema={
+                    "type": "object",
+                    "properties": {
+                        "verbose": {"type": "boolean", "description": "Verbose output"},
+                        "name": {"type": "string"},
+                    },
+                },
+            ),
+        ]
+        content = generate_skill_content("test", "cli.py", tools)
+        assert "--verbose <value>" not in content
+        assert "--name <value>" in content
+
+    def test_server_name_in_header(self):
+        content = generate_skill_content("My Weather API", "cli.py", [])
+        assert "# My Weather API CLI" in content
+        assert 'name: "my-weather-api-cli"' in content
diff --git a/tests/cli/test_goose.py b/tests/cli/test_goose.py
new file mode 100644
index 0000000..6108eef
--- /dev/null
+++ b/tests/cli/test_goose.py
@@ -0,0 +1,298 @@
+from pathlib import Path
+from unittest.mock import patch
+from urllib.parse import parse_qs, unquote, urlparse
+
+import pytest
+
+from fastmcp.cli.install.goose import (
+    _build_uvx_command,
+    _slugify,
+    generate_goose_deeplink,
+    goose_command,
+    install_goose,
+)
+
+
+class TestSlugify:
+    def test_simple_name(self):
+        assert _slugify("My Server") == "my-server"
+
+    def test_special_characters(self):
+        assert _slugify("my_server (v2.0)") == "my-server-v2-0"
+
+    def test_already_slugified(self):
+        assert _slugify("my-server") == "my-server"
+
+    def test_empty_string(self):
+        assert _slugify("") == "fastmcp-server"
+
+    def test_only_special_chars(self):
+        assert _slugify("!!!") == "fastmcp-server"
+
+    def test_consecutive_hyphens_collapsed(self):
+        assert _slugify("a---b") == "a-b"
+
+    def test_leading_trailing_stripped(self):
+        assert _slugify("--hello--") == "hello"
+
+
+class TestBuildUvxCommand:
+    def test_basic(self):
+        cmd = _build_uvx_command("server.py")
+        assert cmd == ["uvx", "fastmcp", "run", "server.py"]
+
+    def test_with_python_version(self):
+        cmd = _build_uvx_command("server.py", python_version="3.11")
+        assert cmd == [
+            "uvx",
+            "--python",
+            "3.11",
+            "fastmcp",
+            "run",
+            "server.py",
+        ]
+
+    def test_with_packages(self):
+        cmd = _build_uvx_command("server.py", with_packages=["numpy", "pandas"])
+        assert "--with" in cmd
+        assert "numpy" in cmd
+        assert "pandas" in cmd
+
+    def test_fastmcp_not_in_with(self):
+        cmd = _build_uvx_command("server.py", with_packages=["fastmcp", "numpy"])
+        # fastmcp is the command itself, so it shouldn't appear in --with
+        with_indices = [i for i, v in enumerate(cmd) if v == "--with"]
+        with_values = [cmd[i + 1] for i in with_indices]
+        assert "fastmcp" not in with_values
+
+    def test_packages_sorted_and_deduplicated(self):
+        cmd = _build_uvx_command(
+            "server.py", with_packages=["pandas", "numpy", "pandas"]
+        )
+        with_indices = [i for i, v in enumerate(cmd) if v == "--with"]
+        with_values = [cmd[i + 1] for i in with_indices]
+        assert with_values == ["numpy", "pandas"]
+
+    def test_server_spec_with_object(self):
+        cmd = _build_uvx_command("server.py:app")
+        assert cmd[-1] == "server.py:app"
+
+
+class TestGooseDeeplinkGeneration:
+    def test_basic_deeplink(self):
+        deeplink = generate_goose_deeplink(
+            name="test-server",
+            command="uvx",
+            args=["fastmcp", "run", "server.py"],
+        )
+        assert deeplink.startswith("goose://extension?")
+        parsed = urlparse(deeplink)
+        params = parse_qs(parsed.query)
+        assert params["cmd"] == ["uvx"]
+        assert params["name"] == ["test-server"]
+        assert params["id"] == ["test-server"]
+
+    def test_special_characters_in_name(self):
+        deeplink = generate_goose_deeplink(
+            name="my server (test)",
+            command="uvx",
+            args=["fastmcp", "run", "server.py"],
+        )
+        assert "name=my%20server%20%28test%29" in deeplink
+        parsed = urlparse(deeplink)
+        params = parse_qs(parsed.query)
+        assert params["id"] == ["my-server-test"]
+
+    def test_url_injection_protection(self):
+        deeplink = generate_goose_deeplink(
+            name="test&evil=true",
+            command="uvx",
+            args=["fastmcp", "run", "server.py"],
+        )
+        assert "name=test%26evil%3Dtrue" in deeplink
+        parsed = urlparse(deeplink)
+        params = parse_qs(parsed.query)
+        assert params["name"] == ["test&evil=true"]
+
+    def test_dangerous_characters_encoded(self):
+        dangerous_names = [
+            ("test|calc", "test%7Ccalc"),
+            ("test;calc", "test%3Bcalc"),
+            ("test<calc", "test%3Ccalc"),
+            ("test>calc", "test%3Ecalc"),
+            ("test`calc", "test%60calc"),
+            ("test$calc", "test%24calc"),
+            ("test'calc", "test%27calc"),
+            ('test"calc', "test%22calc"),
+            ("test calc", "test%20calc"),
+            ("test#anchor", "test%23anchor"),
+            ("test?query=val", "test%3Fquery%3Dval"),
+        ]
+        for dangerous_name, expected_encoded in dangerous_names:
+            deeplink = generate_goose_deeplink(
+                name=dangerous_name, command="uvx", args=["fastmcp", "run", "server.py"]
+            )
+            assert f"name={expected_encoded}" in deeplink, (
+                f"Failed to encode {dangerous_name}"
+            )
+
+    def test_custom_description(self):
+        deeplink = generate_goose_deeplink(
+            name="my-server",
+            command="uvx",
+            args=["fastmcp", "run", "server.py"],
+            description="My custom MCP server",
+        )
+        parsed = urlparse(deeplink)
+        params = parse_qs(parsed.query)
+        assert params["description"] == ["My custom MCP server"]
+
+    def test_args_with_special_characters(self):
+        deeplink = generate_goose_deeplink(
+            name="test",
+            command="uvx",
+            args=[
+                "--with",
+                "numpy>=1.20",
+                "fastmcp",
+                "run",
+                "server.py:MyApp",
+            ],
+        )
+        parsed = urlparse(deeplink)
+        params = parse_qs(parsed.query)
+        assert "numpy>=1.20" in params["arg"]
+        assert "server.py:MyApp" in params["arg"]
+
+    def test_empty_args(self):
+        deeplink = generate_goose_deeplink(name="simple", command="python", args=[])
+        parsed = urlparse(deeplink)
+        params = parse_qs(parsed.query)
+        assert "arg" not in params
+        assert params["cmd"] == ["python"]
+
+    def test_command_with_path(self):
+        deeplink = generate_goose_deeplink(
+            name="test",
+            command="/usr/local/bin/uvx",
+            args=["fastmcp", "run", "server.py"],
+        )
+        parsed = urlparse(deeplink)
+        params = parse_qs(parsed.query)
+        assert params["cmd"] == ["/usr/local/bin/uvx"]
+
+
+class TestInstallGoose:
+    @patch("fastmcp.cli.install.goose.open_deeplink")
+    @patch("fastmcp.cli.install.goose.print")
+    def test_success(self, mock_print, mock_open):
+        mock_open.return_value = True
+        result = install_goose(
+            file=Path("/path/to/server.py"),
+            server_object=None,
+            name="test-server",
+        )
+        assert result is True
+        mock_open.assert_called_once()
+        call_url = mock_open.call_args[0][0]
+        assert call_url.startswith("goose://extension?")
+        assert mock_open.call_args[1] == {"expected_scheme": "goose"}
+
+    @patch("fastmcp.cli.install.goose.open_deeplink")
+    @patch("fastmcp.cli.install.goose.print")
+    def test_success_uses_uvx(self, mock_print, mock_open):
+        mock_open.return_value = True
+        install_goose(
+            file=Path("/path/to/server.py"),
+            server_object=None,
+            name="test-server",
+        )
+        call_url = mock_open.call_args[0][0]
+        parsed = urlparse(call_url)
+        params = parse_qs(parsed.query)
+        assert params["cmd"] == ["uvx"]
+        assert "fastmcp" in params["arg"]
+
+    @patch("fastmcp.cli.install.goose.open_deeplink")
+    @patch("fastmcp.cli.install.goose.print")
+    def test_failure(self, mock_print, mock_open):
+        mock_open.return_value = False
+        result = install_goose(
+            file=Path("/path/to/server.py"),
+            server_object=None,
+            name="test-server",
+        )
+        assert result is False
+
+    @patch("fastmcp.cli.install.goose.open_deeplink")
+    @patch("fastmcp.cli.install.goose.print")
+    def test_with_server_object(self, mock_print, mock_open):
+        mock_open.return_value = True
+        install_goose(
+            file=Path("/path/to/server.py"),
+            server_object="app",
+            name="test-server",
+        )
+        call_url = mock_open.call_args[0][0]
+        parsed = urlparse(call_url)
+        params = parse_qs(parsed.query)
+        args = params["arg"]
+        assert any("server.py:app" in unquote(a) for a in args)
+
+    @patch("fastmcp.cli.install.goose.open_deeplink")
+    @patch("fastmcp.cli.install.goose.print")
+    def test_with_packages(self, mock_print, mock_open):
+        mock_open.return_value = True
+        install_goose(
+            file=Path("/path/to/server.py"),
+            server_object=None,
+            name="test-server",
+            with_packages=["numpy", "pandas"],
+        )
+        call_url = mock_open.call_args[0][0]
+        parsed = urlparse(call_url)
+        params = parse_qs(parsed.query)
+        args = params["arg"]
+        assert "numpy" in args
+        assert "pandas" in args
+
+    @patch("fastmcp.cli.install.goose.open_deeplink")
+    @patch("fastmcp.cli.install.goose.print")
+    def test_fallback_message_on_failure(self, mock_print, mock_open):
+        mock_open.return_value = False
+        install_goose(
+            file=Path("/path/to/server.py"),
+            server_object=None,
+            name="test-server",
+        )
+        fallback_calls = [
+            call
+            for call in mock_print.call_args_list
+            if "copy this link" in str(call).lower() or "goose://" in str(call)
+        ]
+        assert len(fallback_calls) > 0
+
+
+class TestGooseCommand:
+    @patch("fastmcp.cli.install.goose.install_goose")
+    @patch("fastmcp.cli.install.goose.process_common_args")
+    async def test_basic(self, mock_process, mock_install):
+        mock_process.return_value = (Path("server.py"), None, "test-server", [], {})
+        mock_install.return_value = True
+        await goose_command("server.py")
+        mock_install.assert_called_once_with(
+            file=Path("server.py"),
+            server_object=None,
+            name="test-server",
+            with_packages=[],
+            python_version=None,
+        )
+
+    @patch("fastmcp.cli.install.goose.install_goose")
+    @patch("fastmcp.cli.install.goose.process_common_args")
+    async def test_failure_exits(self, mock_process, mock_install):
+        mock_process.return_value = (Path("server.py"), None, "test-server", [], {})
+        mock_install.return_value = False
+        with pytest.raises(SystemExit) as exc_info:
+            await goose_command("server.py")
+        assert exc_info.value.code == 1
diff --git a/tests/cli/test_install.py b/tests/cli/test_install.py
new file mode 100644
index 0000000..9dca455
--- /dev/null
+++ b/tests/cli/test_install.py
@@ -0,0 +1,494 @@
+from pathlib import Path
+
+import pytest
+
+from fastmcp.cli.install import install_app
+from fastmcp.cli.install.shared import validate_server_name
+from fastmcp.cli.install.stdio import install_stdio
+
+
+class TestInstallApp:
+    """Test the install subapp."""
+
+    def test_install_app_exists(self):
+        """Test that the install app is properly configured."""
+        # install_app.name is a tuple in cyclopts
+        assert "install" in install_app.name
+        assert "Install MCP servers" in install_app.help
+
+    def test_install_commands_registered(self):
+        """Test that all install commands are registered."""
+        # Check that the app has the expected help text and structure
+        # This is a simpler check that doesn't rely on internal methods
+        assert hasattr(install_app, "help")
+        assert "Install MCP servers" in install_app.help
+
+        # We can test that the commands parse without errors
+        try:
+            install_app.parse_args(["claude-code", "--help"])
+            install_app.parse_args(["claude-desktop", "--help"])
+            install_app.parse_args(["cursor", "--help"])
+            install_app.parse_args(["gemini-cli", "--help"])
+            install_app.parse_args(["goose", "--help"])
+            install_app.parse_args(["mcp-json", "--help"])
+            install_app.parse_args(["stdio", "--help"])
+        except SystemExit:
+            # Help commands exit with 0, that's expected
+            pass
+
+
+class TestClaudeCodeInstall:
+    """Test claude-code install command."""
+
+    def test_claude_code_basic(self):
+        """Test basic claude-code install command parsing."""
+        # Parse command with correct parameter names
+        command, bound, _ = install_app.parse_args(
+            ["claude-code", "server.py", "--name", "test-server"]
+        )
+
+        # Verify parsing was successful
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        assert bound.arguments["server_name"] == "test-server"
+
+    def test_claude_code_with_options(self):
+        """Test claude-code install with various options."""
+        command, bound, _ = install_app.parse_args(
+            [
+                "claude-code",
+                "server.py",
+                "--name",
+                "test-server",
+                "--with",
+                "package1",
+                "--with",
+                "package2",
+                "--env",
+                "VAR1=value1",
+            ]
+        )
+
+        assert bound.arguments["with_packages"] == ["package1", "package2"]
+        assert bound.arguments["env_vars"] == ["VAR1=value1"]
+
+    def test_claude_code_with_new_options(self):
+        """Test claude-code install with new uv options."""
+        from pathlib import Path
+
+        command, bound, _ = install_app.parse_args(
+            [
+                "claude-code",
+                "server.py",
+                "--python",
+                "3.11",
+                "--project",
+                "/workspace",
+                "--with-requirements",
+                "requirements.txt",
+            ]
+        )
+
+        assert bound.arguments["python"] == "3.11"
+        assert bound.arguments["project"] == Path("/workspace")
+        assert bound.arguments["with_requirements"] == Path("requirements.txt")
+
+
+class TestClaudeDesktopInstall:
+    """Test claude-desktop install command."""
+
+    def test_claude_desktop_basic(self):
+        """Test basic claude-desktop install command parsing."""
+        command, bound, _ = install_app.parse_args(
+            ["claude-desktop", "server.py", "--name", "test-server"]
+        )
+
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        assert bound.arguments["server_name"] == "test-server"
+
+    def test_claude_desktop_with_env_vars(self):
+        """Test claude-desktop install with environment variables."""
+        command, bound, _ = install_app.parse_args(
+            [
+                "claude-desktop",
+                "server.py",
+                "--name",
+                "test-server",
+                "--env",
+                "VAR1=value1",
+                "--env",
+                "VAR2=value2",
+            ]
+        )
+
+        assert bound.arguments["env_vars"] == ["VAR1=value1", "VAR2=value2"]
+
+    def test_claude_desktop_with_new_options(self):
+        """Test claude-desktop install with new uv options."""
+        from pathlib import Path
+
+        command, bound, _ = install_app.parse_args(
+            [
+                "claude-desktop",
+                "server.py",
+                "--python",
+                "3.10",
+                "--project",
+                "/my/project",
+                "--with-requirements",
+                "reqs.txt",
+            ]
+        )
+
+        assert bound.arguments["python"] == "3.10"
+        assert bound.arguments["project"] == Path("/my/project")
+        assert bound.arguments["with_requirements"] == Path("reqs.txt")
+
+    def test_claude_desktop_with_config_path(self):
+        """Test claude-desktop install with custom config path."""
+        command, bound, _ = install_app.parse_args(
+            ["claude-desktop", "server.py", "--config-path", "/custom/path/Claude"]
+        )
+
+        assert bound.arguments["config_path"] == Path("/custom/path/Claude")
+
+    def test_claude_desktop_without_config_path(self):
+        """Test claude-desktop install without config path defaults to None."""
+        command, bound, _ = install_app.parse_args(["claude-desktop", "server.py"])
+
+        assert bound.arguments.get("config_path") is None
+
+
+class TestCursorInstall:
+    """Test cursor install command."""
+
+    def test_cursor_basic(self):
+        """Test basic cursor install command parsing."""
+        command, bound, _ = install_app.parse_args(
+            ["cursor", "server.py", "--name", "test-server"]
+        )
+
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        assert bound.arguments["server_name"] == "test-server"
+
+    def test_cursor_with_options(self):
+        """Test cursor install with options."""
+        command, bound, _ = install_app.parse_args(
+            ["cursor", "server.py", "--name", "test-server"]
+        )
+
+        assert bound.arguments["server_spec"] == "server.py"
+        assert bound.arguments["server_name"] == "test-server"
+
+
+class TestGooseInstall:
+    """Test goose install command."""
+
+    def test_goose_basic(self):
+        """Test basic goose install command parsing."""
+        command, bound, _ = install_app.parse_args(
+            ["goose", "server.py", "--name", "test-server"]
+        )
+
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        assert bound.arguments["server_name"] == "test-server"
+
+    def test_goose_with_options(self):
+        """Test goose install with various options."""
+        command, bound, _ = install_app.parse_args(
+            [
+                "goose",
+                "server.py",
+                "--name",
+                "test-server",
+                "--with",
+                "package1",
+                "--with",
+                "package2",
+                "--env",
+                "VAR1=value1",
+            ]
+        )
+
+        assert bound.arguments["with_packages"] == ["package1", "package2"]
+        assert bound.arguments["env_vars"] == ["VAR1=value1"]
+
+    def test_goose_with_python(self):
+        """Test goose install with --python option."""
+        command, bound, _ = install_app.parse_args(
+            [
+                "goose",
+                "server.py",
+                "--python",
+                "3.11",
+            ]
+        )
+
+        assert bound.arguments["python"] == "3.11"
+
+
+class TestMcpJsonInstall:
+    """Test mcp-json install command."""
+
+    def test_mcp_json_basic(self):
+        """Test basic mcp-json install command parsing."""
+        command, bound, _ = install_app.parse_args(
+            ["mcp-json", "server.py", "--name", "test-server"]
+        )
+
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        assert bound.arguments["server_name"] == "test-server"
+
+    def test_mcp_json_with_copy(self):
+        """Test mcp-json install with copy to clipboard option."""
+        command, bound, _ = install_app.parse_args(
+            ["mcp-json", "server.py", "--name", "test-server", "--copy"]
+        )
+
+        assert bound.arguments["copy"] is True
+
+
+class TestStdioInstall:
+    """Test stdio install command."""
+
+    def test_stdio_basic(self):
+        """Test basic stdio install command parsing."""
+        command, bound, _ = install_app.parse_args(["stdio", "server.py"])
+
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+
+    def test_stdio_with_copy(self):
+        """Test stdio install with copy to clipboard option."""
+        command, bound, _ = install_app.parse_args(["stdio", "server.py", "--copy"])
+
+        assert bound.arguments["copy"] is True
+
+    def test_stdio_with_packages(self):
+        """Test stdio install with additional packages."""
+        command, bound, _ = install_app.parse_args(
+            ["stdio", "server.py", "--with", "requests", "--with", "httpx"]
+        )
+
+        assert bound.arguments["with_packages"] == ["requests", "httpx"]
+
+    def test_install_stdio_generates_command(self, tmp_path: Path):
+        """Test that install_stdio produces a shell command containing fastmcp run."""
+        server_file = tmp_path / "server.py"
+        server_file.write_text("# placeholder")
+
+        # Capture stdout
+        import io
+        import sys
+
+        captured = io.StringIO()
+        old_stdout = sys.stdout
+        sys.stdout = captured
+        try:
+            result = install_stdio(file=server_file, server_object=None)
+        finally:
+            sys.stdout = old_stdout
+
+        assert result is True
+        output = captured.getvalue()
+        assert "fastmcp" in output
+        assert "run" in output
+        assert str(server_file.resolve()) in output
+
+    def test_install_stdio_with_object(self, tmp_path: Path):
+        """Test that install_stdio includes the :object suffix."""
+        server_file = tmp_path / "server.py"
+        server_file.write_text("# placeholder")
+
+        import io
+        import sys
+
+        captured = io.StringIO()
+        old_stdout = sys.stdout
+        sys.stdout = captured
+        try:
+            result = install_stdio(file=server_file, server_object="app")
+        finally:
+            sys.stdout = old_stdout
+
+        assert result is True
+        output = captured.getvalue()
+        assert f"{server_file.resolve()}:app" in output
+
+
+class TestGeminiCliInstall:
+    """Test gemini-cli install command."""
+
+    def test_gemini_cli_basic(self):
+        """Test basic gemini-cli install command parsing."""
+        # Parse command with correct parameter names
+        command, bound, _ = install_app.parse_args(
+            ["gemini-cli", "server.py", "--name", "test-server"]
+        )
+
+        # Verify parsing was successful
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+        assert bound.arguments["server_name"] == "test-server"
+
+    def test_gemini_cli_with_options(self):
+        """Test gemini-cli install with various options."""
+        command, bound, _ = install_app.parse_args(
+            [
+                "gemini-cli",
+                "server.py",
+                "--name",
+                "test-server",
+                "--with",
+                "package1",
+                "--with",
+                "package2",
+                "--env",
+                "VAR1=value1",
+            ]
+        )
+
+        assert bound.arguments["with_packages"] == ["package1", "package2"]
+        assert bound.arguments["env_vars"] == ["VAR1=value1"]
+
+    def test_gemini_cli_with_new_options(self):
+        """Test gemini-cli install with new uv options."""
+        from pathlib import Path
+
+        command, bound, _ = install_app.parse_args(
+            [
+                "gemini-cli",
+                "server.py",
+                "--python",
+                "3.11",
+                "--project",
+                "/workspace",
+                "--with-requirements",
+                "requirements.txt",
+            ]
+        )
+
+        assert bound.arguments["python"] == "3.11"
+        assert bound.arguments["project"] == Path("/workspace")
+        assert bound.arguments["with_requirements"] == Path("requirements.txt")
+
+
+class TestInstallCommandParsing:
+    """Test command parsing and error handling."""
+
+    def test_install_minimal_args(self):
+        """Test install commands with minimal required arguments."""
+        # Each command should work with just a server spec
+        commands_to_test = [
+            ["claude-code", "server.py"],
+            ["claude-desktop", "server.py"],
+            ["cursor", "server.py"],
+            ["gemini-cli", "server.py"],
+            ["goose", "server.py"],
+            ["stdio", "server.py"],
+        ]
+
+        for cmd_args in commands_to_test:
+            command, bound, _ = install_app.parse_args(cmd_args)
+            assert command is not None
+            assert bound.arguments["server_spec"] == "server.py"
+
+    def test_mcp_json_minimal(self):
+        """Test that mcp-json works with minimal arguments."""
+        # Should work with just server spec
+        command, bound, _ = install_app.parse_args(["mcp-json", "server.py"])
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+
+    def test_stdio_minimal(self):
+        """Test that stdio works with minimal arguments."""
+        command, bound, _ = install_app.parse_args(["stdio", "server.py"])
+        assert command is not None
+        assert bound.arguments["server_spec"] == "server.py"
+
+    def test_python_option(self):
+        """Test --python option for all install commands."""
+        commands_to_test = [
+            ["claude-code", "server.py", "--python", "3.11"],
+            ["claude-desktop", "server.py", "--python", "3.11"],
+            ["cursor", "server.py", "--python", "3.11"],
+            ["gemini-cli", "server.py", "--python", "3.11"],
+            ["goose", "server.py", "--python", "3.11"],
+            ["mcp-json", "server.py", "--python", "3.11"],
+            ["stdio", "server.py", "--python", "3.11"],
+        ]
+
+        for cmd_args in commands_to_test:
+            command, bound, _ = install_app.parse_args(cmd_args)
+            assert command is not None
+            assert bound.arguments["python"] == "3.11"
+
+    def test_with_requirements_option(self):
+        """Test --with-requirements option for all install commands."""
+        commands_to_test = [
+            ["claude-code", "server.py", "--with-requirements", "requirements.txt"],
+            ["claude-desktop", "server.py", "--with-requirements", "requirements.txt"],
+            ["cursor", "server.py", "--with-requirements", "requirements.txt"],
+            ["gemini-cli", "server.py", "--with-requirements", "requirements.txt"],
+            ["mcp-json", "server.py", "--with-requirements", "requirements.txt"],
+            ["stdio", "server.py", "--with-requirements", "requirements.txt"],
+        ]
+
+        for cmd_args in commands_to_test:
+            command, bound, _ = install_app.parse_args(cmd_args)
+            assert command is not None
+            assert str(bound.arguments["with_requirements"]) == "requirements.txt"
+
+    def test_project_option(self):
+        """Test --project option for all install commands."""
+        commands_to_test = [
+            ["claude-code", "server.py", "--project", "/path/to/project"],
+            ["claude-desktop", "server.py", "--project", "/path/to/project"],
+            ["cursor", "server.py", "--project", "/path/to/project"],
+            ["gemini-cli", "server.py", "--project", "/path/to/project"],
+            ["mcp-json", "server.py", "--project", "/path/to/project"],
+            ["stdio", "server.py", "--project", "/path/to/project"],
+        ]
+
+        for cmd_args in commands_to_test:
+            command, bound, _ = install_app.parse_args(cmd_args)
+            assert command is not None
+            assert str(bound.arguments["project"]) == str(Path("/path/to/project"))
+
+
+class TestServerNameValidation:
+    """Test server name validation rejects shell metacharacters."""
+
+    @pytest.mark.parametrize(
+        "name",
+        [
+            "my-server",
+            "my_server",
+            "My Server",
+            "server.v2",
+            "test123",
+        ],
+    )
+    def test_valid_names(self, name: str):
+        assert validate_server_name(name) == name
+
+    @pytest.mark.parametrize(
+        "name",
+        [
+            "test&calc",
+            "test|whoami",
+            "test;ls",
+            "test$(id)",
+            "test`id`",
+            'test"quoted',
+            "test>file",
+            "test<file",
+        ],
+    )
+    def test_rejects_shell_metacharacters(self, name: str):
+        with pytest.raises(SystemExit):
+            validate_server_name(name)
diff --git a/tests/cli/test_mcp_server_config_integration.py b/tests/cli/test_mcp_server_config_integration.py
new file mode 100644
index 0000000..5b2cfec
--- /dev/null
+++ b/tests/cli/test_mcp_server_config_integration.py
@@ -0,0 +1,293 @@
+"""Integration tests for fastmcp.json configuration system."""
+
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+from fastmcp.client import Client
+from fastmcp.utilities.mcp_server_config import MCPServerConfig
+
+
+@pytest.fixture
+def server_with_config(tmp_path):
+    """Create a complete server setup with fastmcp.json config."""
+    # Create server file
+    server_file = tmp_path / "server.py"
+    server_file.write_text("""
+from fastmcp import FastMCP
+
+mcp = FastMCP("Config Test Server")
+
+@mcp.tool
+def hello(name: str = "World") -> str:
+    '''Say hello to someone'''
+    return f"Hello, {name}!"
+
+@mcp.resource("resource://greeting")
+def get_greeting() -> str:
+    '''Get a greeting message'''
+    return "Welcome to FastMCP!"
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(mcp.run_async())
+""")
+
+    # Create config file
+    config_data = {
+        "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+        "source": {"path": "server.py"},
+        "environment": {
+            "python": sys.version.split()[0],  # Use current Python version
+            "dependencies": ["fastmcp"],
+        },
+        "deployment": {"transport": "stdio", "log_level": "INFO"},
+    }
+
+    config_file = tmp_path / "fastmcp.json"
+    config_file.write_text(json.dumps(config_data, indent=2))
+
+    return tmp_path
+
+
+class TestConfigFileDetection:
+    """Test configuration file detection patterns."""
+
+    def test_detect_standard_fastmcp_json(self, tmp_path):
+        """Test detection of standard fastmcp.json file."""
+        config_file = tmp_path / "fastmcp.json"
+        config_file.write_text(json.dumps({"source": {"path": "server.py"}}))
+
+        # Should be detected as fastmcp config
+        assert "fastmcp.json" in config_file.name
+        assert config_file.name.endswith("fastmcp.json")
+
+    def test_detect_prefixed_fastmcp_json(self, tmp_path):
+        """Test detection of prefixed fastmcp.json files."""
+        config_file = tmp_path / "my.fastmcp.json"
+        config_file.write_text(json.dumps({"source": {"path": "server.py"}}))
+
+        # Should be detected as fastmcp config
+        assert "fastmcp.json" in config_file.name
+
+    def test_detect_test_fastmcp_json(self, tmp_path):
+        """Test detection of test_fastmcp.json file."""
+        config_file = tmp_path / "test_fastmcp.json"
+        config_file.write_text(json.dumps({"source": {"path": "server.py"}}))
+
+        # Should be detected as fastmcp config
+        assert "fastmcp.json" in config_file.name
+
+
+class TestConfigWithClient:
+    """Test fastmcp.json configuration with client connections."""
+
+    async def test_config_server_with_client(self, server_with_config):
+        """Test that a server loaded from config works with a client."""
+        # Load the config
+        config_file = server_with_config / "fastmcp.json"
+        config = MCPServerConfig.from_file(config_file)
+
+        # Import the server using the source
+        import importlib.util
+        import sys
+
+        # Resolve the path from the source
+        source_path = Path(config.source.path)
+        if not source_path.is_absolute():
+            source_path = (config_file.parent / source_path).resolve()
+
+        spec = importlib.util.spec_from_file_location("test_server", str(source_path))
+        if spec is None or spec.loader is None:
+            raise RuntimeError(f"Could not load module from {source_path}")
+
+        module = importlib.util.module_from_spec(spec)
+        sys.modules["test_server"] = module
+        spec.loader.exec_module(module)
+
+        assert hasattr(module, "mcp")
+
+        server = module.mcp
+
+        # Connect client to server
+        async with Client(server) as client:
+            # Test tool
+            result = await client.call_tool("hello", {"name": "FastMCP"})
+            assert result.data == "Hello, FastMCP!"  # Use .data for string result
+
+            # Test resource
+            results = await client.read_resource("resource://greeting")
+            assert len(results) == 1
+            # Resource results should have text content
+            assert hasattr(results[0], "text") or hasattr(results[0], "contents")
+            # Get the text content from the resource
+            text = getattr(results[0], "text", None) or getattr(
+                results[0], "contents", ""
+            )
+            assert "Welcome to FastMCP!" in str(text)
+
+
+class TestEnvironmentExecution:
+    """Test environment configuration execution paths."""
+
+    def test_needs_uv_with_dependencies(self):
+        """Test that environment with dependencies needs UV."""
+        config = MCPServerConfig(
+            source={"path": "server.py"},
+            environment={"dependencies": ["requests", "numpy"]},
+        )
+
+        assert config.environment is not None
+        assert config.environment._must_run_with_uv()
+
+    def test_needs_uv_with_python_version(self):
+        """Test that environment with Python version needs UV."""
+        config = MCPServerConfig(
+            source={"path": "server.py"},
+            environment={"python": "3.12"},
+        )
+
+        assert config.environment is not None
+        assert config.environment._must_run_with_uv()
+
+    def test_no_uv_needed_without_environment(self):
+        """Test that no UV is needed without environment config."""
+        config = MCPServerConfig(source={"path": "server.py"})
+
+        # Environment is now always present but may be empty
+        assert config.environment is not None
+        assert not config.environment._must_run_with_uv()
+
+    def test_no_uv_needed_with_empty_environment(self):
+        """Test that no UV is needed with empty environment config."""
+        config = MCPServerConfig(
+            source={"path": "server.py"},
+            environment={},
+        )
+
+        assert config.environment is not None
+        assert not config.environment._must_run_with_uv()
+
+
+class TestPathResolution:
+    """Test path resolution in configurations."""
+
+    def test_source_path_resolution(self, tmp_path):
+        """Test that source paths are resolved relative to config."""
+        # Create nested directory structure
+        config_dir = tmp_path / "config"
+        config_dir.mkdir()
+        src_dir = tmp_path / "src"
+        src_dir.mkdir()
+
+        # Server is in src, config is in config
+        server_file = src_dir / "server.py"
+        server_file.write_text("# Server")
+
+        config = MCPServerConfig(source={"path": "../src/server.py"})
+
+        # The source path is resolved during load_server
+        # For now, just check that the source is created correctly
+        assert config.source.path == "../src/server.py"
+
+    def test_cwd_path_resolution(self, tmp_path):
+        """Test that working directory is resolved relative to config."""
+        import os
+
+        # Create directory structure
+        work_dir = tmp_path / "work"
+        work_dir.mkdir()
+
+        config = MCPServerConfig(
+            source={"path": "server.py"},
+            deployment={"cwd": "work"},
+        )
+
+        original_cwd = os.getcwd()
+
+        try:
+            # Apply runtime settings relative to config location
+            assert config.deployment is not None
+            config.deployment.apply_runtime_settings(tmp_path / "fastmcp.json")
+
+            # Should change to work directory
+            assert Path.cwd() == work_dir.resolve()
+
+        finally:
+            os.chdir(original_cwd)
+
+    def test_requirements_path_resolution(self, tmp_path):
+        """Test that requirements path is resolved correctly."""
+        # Create requirements file
+        reqs_file = tmp_path / "requirements.txt"
+        reqs_file.write_text("fastmcp>=2.0")
+
+        config = MCPServerConfig(
+            source={"path": "server.py"},
+            environment={"requirements": "requirements.txt"},
+        )
+
+        # Build UV command
+        assert config.environment is not None
+        uv_cmd = config.environment.build_command(["fastmcp", "run"])
+
+        # Should include requirements file with absolute path
+        assert "--with-requirements" in uv_cmd
+        req_idx = uv_cmd.index("--with-requirements") + 1
+        assert Path(uv_cmd[req_idx]).is_absolute()
+        assert Path(uv_cmd[req_idx]).name == "requirements.txt"
+
+
+class TestConfigValidation:
+    """Test configuration validation."""
+
+    def test_invalid_transport_rejected(self):
+        """Test that invalid transport values are rejected."""
+        with pytest.raises(ValueError):
+            MCPServerConfig(
+                source={"path": "server.py"},
+                deployment={"transport": "invalid_transport"},
+            )
+
+    def test_streamable_http_transport_accepted(self):
+        """Test that streamable-http transport is accepted as a valid value."""
+        config = MCPServerConfig(
+            source={"path": "server.py"},
+            deployment={"transport": "streamable-http"},
+        )
+        assert config.deployment.transport == "streamable-http"
+
+    def test_invalid_log_level_rejected(self):
+        """Test that invalid log level values are rejected."""
+        with pytest.raises(ValueError):
+            MCPServerConfig(
+                source={"path": "server.py"},
+                deployment={"log_level": "INVALID"},
+            )
+
+    def test_missing_source_rejected(self):
+        """Test that config without source is rejected."""
+        with pytest.raises(ValueError):
+            MCPServerConfig()  # type: ignore[call-arg]  # ty:ignore[no-matching-overload]
+
+    def test_valid_transport_values(self):
+        """Test that all valid transport values are accepted."""
+        for transport in ["stdio", "http", "sse"]:
+            config = MCPServerConfig(
+                source={"path": "server.py"},
+                deployment={"transport": transport},
+            )
+            assert config.deployment is not None
+            assert config.deployment.transport == transport
+
+    def test_valid_log_levels(self):
+        """Test that all valid log levels are accepted."""
+        for level in ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]:
+            config = MCPServerConfig(
+                source={"path": "server.py"},
+                deployment={"log_level": level},
+            )
+            assert config.deployment is not None
+            assert config.deployment.log_level == level
diff --git a/tests/cli/test_mcp_server_config_schema.py b/tests/cli/test_mcp_server_config_schema.py
new file mode 100644
index 0000000..2be2c69
--- /dev/null
+++ b/tests/cli/test_mcp_server_config_schema.py
@@ -0,0 +1,172 @@
+"""Test that the generated JSON schema has the correct structure."""
+
+import pytest
+
+from fastmcp.utilities.mcp_server_config.v1.mcp_server_config import (
+    Deployment,
+    generate_schema,
+)
+
+
+def test_schema_has_correct_id():
+    """Test that the schema has the correct $id field."""
+    generated_schema = generate_schema()
+
+    assert generated_schema is not None
+    assert "$id" in generated_schema
+    assert (
+        generated_schema["$id"]
+        == "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json"
+    )
+
+
+def test_schema_has_required_fields():
+    """Test that the schema specifies the required fields correctly."""
+    generated_schema = generate_schema()
+
+    assert generated_schema is not None
+    # Check that source is required
+    assert "required" in generated_schema
+    assert "source" in generated_schema["required"]
+
+    # Check that source is in properties
+    assert "properties" in generated_schema
+    assert "source" in generated_schema["properties"]
+
+
+def test_schema_nested_structure():
+    """Test that the schema has the correct nested structure."""
+    generated_schema = generate_schema()
+
+    assert generated_schema is not None
+    properties = generated_schema["properties"]
+
+    # Check environment section
+    assert "environment" in properties
+    env_schema = properties["environment"]
+    # Environment can be in anyOf or direct properties
+    if "anyOf" in env_schema:
+        # Find the UVEnvironment in anyOf
+        for option in env_schema["anyOf"]:
+            if option.get("type") == "object" and "properties" in option:
+                env_props = option["properties"]
+                assert "type" in env_props  # New type field
+                assert "python" in env_props
+                assert "dependencies" in env_props
+                assert "requirements" in env_props
+                assert "project" in env_props
+                assert "editable" in env_props
+                break
+    elif "properties" in env_schema:
+        env_props = env_schema["properties"]
+        assert "type" in env_props  # New type field
+        assert "python" in env_props
+        assert "dependencies" in env_props
+        assert "requirements" in env_props
+        assert "project" in env_props
+        assert "editable" in env_props
+
+    # Check deployment section
+    assert "deployment" in properties
+    deploy_schema = properties["deployment"]
+    if "properties" in deploy_schema:
+        deploy_props = deploy_schema["properties"]
+        assert "transport" in deploy_props
+        assert "host" in deploy_props
+        assert "port" in deploy_props
+        assert "log_level" in deploy_props
+        assert "env" in deploy_props
+        assert "cwd" in deploy_props
+        assert "args" in deploy_props
+
+
+def test_schema_transport_enum():
+    """Test that transport field has correct enum values."""
+    generated_schema = generate_schema()
+
+    assert generated_schema is not None
+    # Navigate to transport field
+    deploy_schema = generated_schema["properties"]["deployment"]
+
+    # Handle both direct properties and anyOf cases
+    if "anyOf" in deploy_schema:
+        # Find the object type in anyOf
+        for option in deploy_schema["anyOf"]:
+            if option.get("type") == "object" and "properties" in option:
+                transport_schema = option["properties"].get("transport", {})
+                if "anyOf" in transport_schema:
+                    # Look for enum in anyOf options
+                    for trans_option in transport_schema["anyOf"]:
+                        if "enum" in trans_option:
+                            valid_transports = trans_option["enum"]
+                            assert "stdio" in valid_transports
+                            assert "http" in valid_transports
+                            assert "sse" in valid_transports
+                            assert "streamable-http" in valid_transports
+                            break
+    elif "properties" in deploy_schema:
+        transport_schema = deploy_schema["properties"].get("transport", {})
+        if "anyOf" in transport_schema:
+            for option in transport_schema["anyOf"]:
+                if "enum" in option:
+                    valid_transports = option["enum"]
+                    assert "stdio" in valid_transports
+                    assert "http" in valid_transports
+                    assert "sse" in valid_transports
+                    assert "streamable-http" in valid_transports
+                    break
+
+
+def test_schema_log_level_enum():
+    """Test that log_level field has correct enum values."""
+    generated_schema = generate_schema()
+
+    assert generated_schema is not None
+    # Navigate to log_level field
+    deploy_schema = generated_schema["properties"]["deployment"]
+
+    # Handle both direct properties and anyOf cases
+    if "anyOf" in deploy_schema:
+        # Find the object type in anyOf
+        for option in deploy_schema["anyOf"]:
+            if option.get("type") == "object" and "properties" in option:
+                log_level_schema = option["properties"].get("log_level", {})
+                if "anyOf" in log_level_schema:
+                    # Look for enum in anyOf options
+                    for level_option in log_level_schema["anyOf"]:
+                        if "enum" in level_option:
+                            valid_levels = level_option["enum"]
+                            assert "DEBUG" in valid_levels
+                            assert "INFO" in valid_levels
+                            assert "WARNING" in valid_levels
+                            assert "ERROR" in valid_levels
+                            assert "CRITICAL" in valid_levels
+                            break
+    elif "properties" in deploy_schema:
+        log_level_schema = deploy_schema["properties"].get("log_level", {})
+        if "anyOf" in log_level_schema:
+            for option in log_level_schema["anyOf"]:
+                if "enum" in option:
+                    valid_levels = option["enum"]
+                    assert "DEBUG" in valid_levels
+                    assert "INFO" in valid_levels
+                    assert "WARNING" in valid_levels
+                    assert "ERROR" in valid_levels
+                    assert "CRITICAL" in valid_levels
+                    break
+
+
+@pytest.mark.parametrize(
+    "transport",
+    [
+        "streamable-http",
+        "http",
+        "stdio",
+        "sse",
+        None,
+    ],
+)
+def test_transport_values_accepted(transport):
+    """Test that all valid transport values are accepted."""
+    deployment = Deployment(transport=transport)
+    assert deployment.transport == transport
diff --git a/tests/cli/test_project_prepare.py b/tests/cli/test_project_prepare.py
new file mode 100644
index 0000000..93e37cb
--- /dev/null
+++ b/tests/cli/test_project_prepare.py
@@ -0,0 +1,306 @@
+"""Tests for the fastmcp project prepare command."""
+
+import subprocess
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from fastmcp.utilities.mcp_server_config import MCPServerConfig
+from fastmcp.utilities.mcp_server_config.v1.environments.uv import UVEnvironment
+from fastmcp.utilities.mcp_server_config.v1.sources.filesystem import FileSystemSource
+
+
+class TestMCPServerConfigPrepare:
+    """Test the MCPServerConfig.prepare() method."""
+
+    @patch(
+        "fastmcp.utilities.mcp_server_config.v1.mcp_server_config.MCPServerConfig.prepare_source",
+        new_callable=AsyncMock,
+    )
+    @patch(
+        "fastmcp.utilities.mcp_server_config.v1.mcp_server_config.MCPServerConfig.prepare_environment",
+        new_callable=AsyncMock,
+    )
+    async def test_prepare_calls_both_methods(self, mock_env, mock_src):
+        """Test that prepare() calls both prepare_environment and prepare_source."""
+        config = MCPServerConfig(
+            source=FileSystemSource(path="server.py"),
+            environment=UVEnvironment(python="3.10"),
+        )
+
+        await config.prepare()
+
+        mock_env.assert_called_once()
+        mock_src.assert_called_once()
+
+    @patch(
+        "fastmcp.utilities.mcp_server_config.v1.mcp_server_config.MCPServerConfig.prepare_source",
+        new_callable=AsyncMock,
+    )
+    @patch(
+        "fastmcp.utilities.mcp_server_config.v1.mcp_server_config.MCPServerConfig.prepare_environment",
+        new_callable=AsyncMock,
+    )
+    async def test_prepare_with_output_dir(self, mock_env, mock_src):
+        """Test that prepare() with output_dir calls prepare_environment with it."""
+        config = MCPServerConfig(
+            source=FileSystemSource(path="server.py"),
+            environment=UVEnvironment(python="3.10"),
+        )
+
+        output_path = Path("/tmp/test-env")
+        await config.prepare(skip_source=False, output_dir=output_path)
+
+        mock_env.assert_called_once_with(output_dir=output_path)
+        mock_src.assert_called_once()
+
+    @patch(
+        "fastmcp.utilities.mcp_server_config.v1.mcp_server_config.MCPServerConfig.prepare_source",
+        new_callable=AsyncMock,
+    )
+    @patch(
+        "fastmcp.utilities.mcp_server_config.v1.mcp_server_config.MCPServerConfig.prepare_environment",
+        new_callable=AsyncMock,
+    )
+    async def test_prepare_skip_source(self, mock_env, mock_src):
+        """Test that prepare() skips source when skip_source=True."""
+        config = MCPServerConfig(
+            source=FileSystemSource(path="server.py"),
+            environment=UVEnvironment(python="3.10"),
+        )
+
+        await config.prepare(skip_source=True)
+
+        mock_env.assert_called_once_with(output_dir=None)
+        mock_src.assert_not_called()
+
+    @patch(
+        "fastmcp.utilities.mcp_server_config.v1.mcp_server_config.MCPServerConfig.prepare_source",
+        new_callable=AsyncMock,
+    )
+    @patch(
+        "fastmcp.utilities.mcp_server_config.v1.environments.uv.UVEnvironment.prepare",
+        new_callable=AsyncMock,
+    )
+    async def test_prepare_no_environment_settings(self, mock_env_prepare, mock_src):
+        """Test that prepare() works with default empty environment config."""
+        config = MCPServerConfig(
+            source=FileSystemSource(path="server.py"),
+            # environment defaults to empty Environment()
+        )
+
+        await config.prepare(skip_source=False)
+
+        # Environment prepare should be called even with empty config
+        mock_env_prepare.assert_called_once_with(output_dir=None)
+        mock_src.assert_called_once()
+
+
+class TestEnvironmentPrepare:
+    """Test the Environment.prepare() method."""
+
+    @patch("shutil.which")
+    async def test_prepare_no_uv_installed(self, mock_which, tmp_path):
+        """Test that prepare() raises error when uv is not installed."""
+        mock_which.return_value = None
+
+        env = UVEnvironment(python="3.10")
+
+        with pytest.raises(RuntimeError, match="uv is not installed"):
+            await env.prepare(tmp_path / "test-env")
+
+    @patch("subprocess.run")
+    @patch("shutil.which")
+    async def test_prepare_no_settings(self, mock_which, mock_run, tmp_path):
+        """Test that prepare() does nothing when no settings are configured."""
+        mock_which.return_value = "/usr/bin/uv"
+
+        env = UVEnvironment()  # No settings
+
+        await env.prepare(tmp_path / "test-env")
+
+        # Should not run any commands
+        mock_run.assert_not_called()
+
+    @patch("subprocess.run")
+    @patch("shutil.which")
+    async def test_prepare_with_python(self, mock_which, mock_run, tmp_path):
+        """Test that prepare() runs uv with python version."""
+        mock_which.return_value = "/usr/bin/uv"
+        mock_run.return_value = MagicMock(
+            returncode=0, stdout="Environment cached", stderr=""
+        )
+
+        env = UVEnvironment(python="3.10")
+
+        await env.prepare(tmp_path / "test-env")
+
+        # Should run multiple uv commands for initializing the project
+        assert mock_run.call_count > 0
+
+        # Check the first call should be uv init
+        first_call_args = mock_run.call_args_list[0][0][0]
+        assert first_call_args[0] == "uv"
+        assert "init" in first_call_args
+
+    @patch("subprocess.run")
+    @patch("shutil.which")
+    async def test_prepare_with_dependencies(self, mock_which, mock_run, tmp_path):
+        """Test that prepare() includes dependencies."""
+        mock_which.return_value = "/usr/bin/uv"
+        mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+
+        env = UVEnvironment(dependencies=["numpy", "pandas"])
+
+        await env.prepare(tmp_path / "test-env")
+
+        # Should run multiple uv commands, one of which should be uv add
+        assert mock_run.call_count > 0
+
+        # Find the add command call
+        add_call = None
+        for call_args, _ in mock_run.call_args_list:
+            args = call_args[0]
+            if "add" in args:
+                add_call = args
+                break
+
+        assert add_call is not None, "Should have called uv add"
+        assert "numpy" in add_call
+        assert "pandas" in add_call
+        assert "fastmcp" in add_call  # Always added
+
+    @patch("subprocess.run")
+    @patch("shutil.which")
+    async def test_prepare_command_fails(self, mock_which, mock_run, tmp_path):
+        """Test that prepare() raises error when uv command fails."""
+        mock_which.return_value = "/usr/bin/uv"
+        mock_run.side_effect = subprocess.CalledProcessError(
+            1, ["uv"], stderr="Package not found"
+        )
+
+        env = UVEnvironment(python="3.10")
+
+        with pytest.raises(RuntimeError, match="Failed to initialize project"):
+            await env.prepare(tmp_path / "test-env")
+
+
+class TestProjectPrepareCommand:
+    """Test the CLI project prepare command."""
+
+    @patch("fastmcp.utilities.mcp_server_config.MCPServerConfig.from_file")
+    @patch("fastmcp.utilities.mcp_server_config.MCPServerConfig.find_config")
+    async def test_project_prepare_auto_detect(self, mock_find, mock_from_file):
+        """Test project prepare with auto-detected config."""
+        from fastmcp.cli.cli import prepare
+
+        # Setup mocks
+        mock_find.return_value = Path("fastmcp.json")
+        mock_config = AsyncMock()
+        mock_from_file.return_value = mock_config
+
+        # Run command with output_dir
+        with patch("sys.exit"):
+            with patch("fastmcp.cli.cli.console.print") as mock_print:
+                await prepare(config_path=None, output_dir="./test-env")
+
+        # Should find and load config
+        mock_find.assert_called_once()
+        mock_from_file.assert_called_once_with(Path("fastmcp.json"))
+
+        # Should call prepare with output_dir
+        mock_config.prepare.assert_called_once_with(
+            skip_source=False,
+            output_dir=Path("./test-env"),
+        )
+
+        # Should print success message
+        mock_print.assert_called()
+        success_call = mock_print.call_args_list[-1][0][0]
+        assert "Project prepared successfully" in success_call
+
+    @patch("pathlib.Path.exists")
+    @patch("fastmcp.utilities.mcp_server_config.MCPServerConfig.from_file")
+    async def test_project_prepare_explicit_path(self, mock_from_file, mock_exists):
+        """Test project prepare with explicit config path."""
+        from fastmcp.cli.cli import prepare
+
+        # Setup mocks
+        mock_exists.return_value = True
+        mock_config = AsyncMock()
+        mock_from_file.return_value = mock_config
+
+        # Run command with explicit path
+        with patch("fastmcp.cli.cli.console.print"):
+            await prepare(config_path="myconfig.json", output_dir="./test-env")
+
+        # Should load specified config
+        mock_from_file.assert_called_once_with(Path("myconfig.json"))
+
+        # Should call prepare
+        mock_config.prepare.assert_called_once_with(
+            skip_source=False,
+            output_dir=Path("./test-env"),
+        )
+
+    @patch("fastmcp.utilities.mcp_server_config.MCPServerConfig.find_config")
+    async def test_project_prepare_no_config_found(self, mock_find):
+        """Test project prepare when no config is found."""
+        from fastmcp.cli.cli import prepare
+
+        # Setup mocks
+        mock_find.return_value = None
+
+        # Run command without output_dir - should exit with error for missing output_dir
+        with pytest.raises(SystemExit) as exc_info:
+            with patch("fastmcp.cli.cli.logger.error") as mock_error:
+                await prepare(config_path=None, output_dir=None)
+
+        assert isinstance(exc_info.value, SystemExit)
+        assert exc_info.value.code == 1
+        mock_error.assert_called()
+        error_msg = mock_error.call_args[0][0]
+        assert "--output-dir parameter is required" in error_msg
+
+    @patch("pathlib.Path.exists")
+    async def test_project_prepare_config_not_exists(self, mock_exists):
+        """Test project prepare when specified config doesn't exist."""
+        from fastmcp.cli.cli import prepare
+
+        # Setup mocks
+        mock_exists.return_value = False
+
+        # Run command without output_dir - should exit with error for missing output_dir
+        with pytest.raises(SystemExit) as exc_info:
+            with patch("fastmcp.cli.cli.logger.error") as mock_error:
+                await prepare(config_path="missing.json", output_dir=None)
+
+        assert isinstance(exc_info.value, SystemExit)
+        assert exc_info.value.code == 1
+        mock_error.assert_called()
+        error_msg = mock_error.call_args[0][0]
+        assert "--output-dir parameter is required" in error_msg
+
+    @patch("pathlib.Path.exists")
+    @patch("fastmcp.utilities.mcp_server_config.MCPServerConfig.from_file")
+    async def test_project_prepare_failure(self, mock_from_file, mock_exists):
+        """Test project prepare when prepare() fails."""
+        from fastmcp.cli.cli import prepare
+
+        # Setup mocks
+        mock_exists.return_value = True
+        mock_config = AsyncMock()
+        mock_config.prepare.side_effect = RuntimeError("Preparation failed")
+        mock_from_file.return_value = mock_config
+
+        # Run command - should exit with error
+        with pytest.raises(SystemExit) as exc_info:
+            with patch("fastmcp.cli.cli.console.print") as mock_print:
+                await prepare(config_path="config.json", output_dir="./test-env")
+
+        assert isinstance(exc_info.value, SystemExit)
+        assert exc_info.value.code == 1
+        # Should print error message
+        error_call = mock_print.call_args_list[-1][0][0]
+        assert "Failed to prepare project" in error_call
diff --git a/tests/cli/test_run.py b/tests/cli/test_run.py
new file mode 100644
index 0000000..c89c87b
--- /dev/null
+++ b/tests/cli/test_run.py
@@ -0,0 +1,1257 @@
+import asyncio
+import inspect
+import json
+import subprocess
+import sys
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+from urllib.parse import parse_qs, urlsplit
+
+import pytest
+from pydantic import ValidationError
+from starlette.testclient import TestClient
+
+from fastmcp.cli.apps_dev import _make_dev_app, _MessageLog
+from fastmcp.cli.cli import apps, inspector, run
+from fastmcp.cli.run import (
+    create_mcp_config_server,
+    is_url,
+    run_module_command,
+    run_with_reload,
+)
+from fastmcp.client.client import Client
+from fastmcp.client.transports import FastMCPTransport
+from fastmcp.mcp_config import MCPConfig, StdioMCPServer
+from fastmcp.server.server import FastMCP
+from fastmcp.utilities.mcp_server_config.v1.sources.filesystem import FileSystemSource
+
+
+class TestUrlDetection:
+    """Test URL detection functionality."""
+
+    def test_is_url_valid_http(self):
+        """Test detection of valid HTTP URLs."""
+        assert is_url("http://example.com")
+        assert is_url("http://localhost:8080")
+        assert is_url("http://127.0.0.1:3000/path")
+
+    def test_is_url_valid_https(self):
+        """Test detection of valid HTTPS URLs."""
+        assert is_url("https://example.com")
+        assert is_url("https://api.example.com/mcp")
+        assert is_url("https://localhost:8443")
+
+    def test_is_url_invalid(self):
+        """Test detection of non-URLs."""
+        assert not is_url("server.py")
+        assert not is_url("/path/to/server.py")
+        assert not is_url("server.py:app")
+        assert not is_url("ftp://example.com")  # Not http/https
+        assert not is_url("file:///path/to/file")
+
+
+class TestFileSystemSource:
+    """Test FileSystemSource path parsing functionality."""
+
+    def test_parse_simple_path(self, tmp_path):
+        """Test parsing simple file path without object."""
+        test_file = tmp_path / "server.py"
+        test_file.write_text("# test server")
+
+        source = FileSystemSource(path=str(test_file))
+        assert Path(source.path).resolve() == test_file.resolve()
+        assert source.entrypoint is None
+
+    def test_parse_path_with_object(self, tmp_path):
+        """Test parsing file path with object specification."""
+        test_file = tmp_path / "server.py"
+        test_file.write_text("# test server")
+
+        source = FileSystemSource(path=f"{test_file}:app")
+        assert Path(source.path).resolve() == test_file.resolve()
+        assert source.entrypoint == "app"
+
+    def test_parse_complex_object(self, tmp_path):
+        """Test parsing file path with complex object specification."""
+        test_file = tmp_path / "server.py"
+        test_file.write_text("# test server")
+
+        # The implementation splits on the last colon, so file:module:app
+        # becomes file_path="file:module" and entrypoint="app"
+        # We need to create a file with a colon in the name for this test
+        complex_file = tmp_path / "server:module.py"
+        complex_file.write_text("# test server")
+
+        source = FileSystemSource(path=f"{complex_file}:app")
+        assert Path(source.path).resolve() == complex_file.resolve()
+        assert source.entrypoint == "app"
+
+    async def test_load_server_nonexistent(self):
+        """Test loading nonexistent file path exits."""
+        source = FileSystemSource(path="nonexistent.py")
+        with pytest.raises(SystemExit) as exc_info:
+            await source.load_server()
+        assert isinstance(exc_info.value, SystemExit)
+        assert exc_info.value.code == 1
+
+    async def test_load_server_directory(self, tmp_path):
+        """Test loading directory path exits."""
+        source = FileSystemSource(path=str(tmp_path))
+        with pytest.raises(SystemExit) as exc_info:
+            await source.load_server()
+        assert isinstance(exc_info.value, SystemExit)
+        assert exc_info.value.code == 1
+
+
+class TestMCPConfig:
+    """Test MCPConfig functionality."""
+
+    @pytest.mark.timeout(15)
+    @pytest.mark.skipif(
+        sys.platform == "win32",
+        reason="Stdio subprocess lifecycle is unreliable on Windows CI",
+    )
+    async def test_run_mcp_config(self, tmp_path: Path):
+        """Test creating a server from an MCPConfig file."""
+        server_script = inspect.cleandoc("""
+            from fastmcp import FastMCP
+
+            mcp = FastMCP()
+
+            @mcp.tool
+            def add(a: int, b: int) -> int:
+                return a + b
+
+            if __name__ == '__main__':
+                mcp.run()
+            """)
+
+        script_path: Path = tmp_path / "test.py"
+        script_path.write_text(server_script)
+
+        mcp_config_path = tmp_path / "mcp_config.json"
+
+        mcp_config = MCPConfig(
+            mcpServers={
+                "test_server": StdioMCPServer(command="python", args=[str(script_path)])
+            }
+        )
+        mcp_config.write_to_file(mcp_config_path)
+
+        server: FastMCP[None] = create_mcp_config_server(mcp_config_path)
+
+        client = Client[FastMCPTransport](server)
+
+        async with client:
+            tools = await client.list_tools()
+            assert len(tools) == 1
+
+    async def test_validate_mcp_config(self, tmp_path: Path):
+        """Test creating a server from an MCPConfig file."""
+
+        mcp_config_path = tmp_path / "mcp_config.json"
+
+        mcp_config = {"mcpServers": {"test_server": dict(x=1, y=2)}}
+        with mcp_config_path.open("w") as f:
+            json.dump(mcp_config, f)
+
+        with pytest.raises(ValidationError, match="validation errors for MCPConfig"):
+            create_mcp_config_server(mcp_config_path)
+
+
+class TestServerImport:
+    """Test server import functionality using real files."""
+
+    async def test_import_server_basic_mcp(self, tmp_path):
+        """Test importing server with basic FastMCP server."""
+        test_file = tmp_path / "server.py"
+        test_file.write_text("""
+import fastmcp
+
+mcp = fastmcp.FastMCP("TestServer")
+
+@mcp.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+""")
+
+        source = FileSystemSource(path=str(test_file))
+        server = await source.load_server()
+        assert server.name == "TestServer"
+        tools = await server.list_tools()
+        assert any(t.name == "greet" for t in tools)
+
+    async def test_import_server_with_main_block(self, tmp_path):
+        """Test importing server with if __name__ == '__main__' block."""
+        test_file = tmp_path / "server.py"
+        test_file.write_text("""
+import fastmcp
+
+app = fastmcp.FastMCP("MainServer")
+
+@app.tool
+def calculate(x: int, y: int) -> int:
+    return x + y
+
+if __name__ == "__main__":
+    app.run()
+""")
+
+        source = FileSystemSource(path=str(test_file))
+        server = await source.load_server()
+        assert server.name == "MainServer"
+        tools = await server.list_tools()
+        assert any(t.name == "calculate" for t in tools)
+
+    async def test_import_server_standard_names(self, tmp_path):
+        """Test automatic detection of standard names (mcp, server, app)."""
+        # Test with 'mcp' name
+        mcp_file = tmp_path / "mcp_server.py"
+        mcp_file.write_text("""
+import fastmcp
+mcp = fastmcp.FastMCP("MCPServer")
+""")
+
+        source = FileSystemSource(path=str(mcp_file))
+        server = await source.load_server()
+        assert server.name == "MCPServer"
+
+        # Test with 'server' name
+        server_file = tmp_path / "server_server.py"
+        server_file.write_text("""
+import fastmcp
+server = fastmcp.FastMCP("ServerServer")
+""")
+
+        source = FileSystemSource(path=str(server_file))
+        server = await source.load_server()
+        assert server.name == "ServerServer"
+
+        # Test with 'app' name
+        app_file = tmp_path / "app_server.py"
+        app_file.write_text("""
+import fastmcp
+app = fastmcp.FastMCP("AppServer")
+""")
+
+        source = FileSystemSource(path=str(app_file))
+        server = await source.load_server()
+        assert server.name == "AppServer"
+
+    async def test_import_server_nonstandard_name(self, tmp_path):
+        """Test importing server with non-standard object name."""
+        test_file = tmp_path / "server.py"
+        test_file.write_text("""
+import fastmcp
+
+my_custom_server = fastmcp.FastMCP("CustomServer")
+
+@my_custom_server.tool
+def custom_tool() -> str:
+    return "custom"
+""")
+
+        source = FileSystemSource(path=f"{test_file}:my_custom_server")
+        server = await source.load_server()
+        assert server.name == "CustomServer"
+        tools = await server.list_tools()
+        assert any(t.name == "custom_tool" for t in tools)
+
+    async def test_import_server_no_standard_names_fails(self, tmp_path):
+        """Test importing server when no standard names exist fails."""
+        test_file = tmp_path / "server.py"
+        test_file.write_text("""
+import fastmcp
+
+other_name = fastmcp.FastMCP("OtherServer")
+""")
+
+        source = FileSystemSource(path=str(test_file))
+        with pytest.raises(SystemExit) as exc_info:
+            await source.load_server()
+        assert isinstance(exc_info.value, SystemExit)
+        assert exc_info.value.code == 1
+
+    async def test_import_server_nonexistent_object_fails(self, tmp_path):
+        """Test importing nonexistent server object fails."""
+        test_file = tmp_path / "server.py"
+        test_file.write_text("""
+import fastmcp
+
+mcp = fastmcp.FastMCP("TestServer")
+""")
+
+        source = FileSystemSource(path=f"{test_file}:nonexistent")
+        with pytest.raises(SystemExit) as exc_info:
+            await source.load_server()
+
+        assert isinstance(exc_info.value, SystemExit)
+        assert exc_info.value.code == 1
+
+
+class TestV1ServerAsync:
+    """Test FastMCP 1.x server async support."""
+
+    async def test_run_v1_server_stdio(self, tmp_path):
+        """Test that v1 server uses async stdio method."""
+        from unittest.mock import AsyncMock, patch
+
+        from mcp.server.mcpserver import MCPServer as SDKServer
+
+        from fastmcp.cli.run import run_command
+
+        # Create a v1 FastMCP server file with both sync and async tools
+        test_file = tmp_path / "v1_server.py"
+        test_file.write_text("""
+from mcp.server.mcpserver import MCPServer as FastMCP
+
+mcp = FastMCP("V1Server")
+
+@mcp.tool()
+def sync_echo(text: str) -> str:
+    '''Sync tool for testing'''
+    return f"sync: {text}"
+
+@mcp.tool()
+async def async_echo(text: str) -> str:
+    '''Async tool for testing'''
+    return f"async: {text}"
+""")
+
+        # Mock the async run method
+        with patch.object(
+            SDKServer, "run_stdio_async", new_callable=AsyncMock
+        ) as run_mock:
+            await run_command(str(test_file), transport="stdio")
+            run_mock.assert_called_once()
+
+    async def test_run_v1_server_http(self, tmp_path):
+        """Test that v1 server uses async http method."""
+        from unittest.mock import AsyncMock, patch
+
+        from mcp.server.mcpserver import MCPServer as SDKServer
+
+        from fastmcp.cli.run import run_command
+
+        # Create a v1 FastMCP server file with both sync and async tools
+        test_file = tmp_path / "v1_server.py"
+        test_file.write_text("""
+from mcp.server.mcpserver import MCPServer as FastMCP
+
+mcp = FastMCP("V1Server")
+
+@mcp.tool()
+def sync_echo(text: str) -> str:
+    '''Sync tool for testing'''
+    return f"sync: {text}"
+
+@mcp.tool()
+async def async_echo(text: str) -> str:
+    '''Async tool for testing'''
+    return f"async: {text}"
+""")
+
+        # Mock the async run method
+        with patch.object(
+            SDKServer, "run_streamable_http_async", new_callable=AsyncMock
+        ) as run_mock:
+            await run_command(str(test_file), transport="http")
+            run_mock.assert_called_once()
+
+    async def test_run_v1_server_streamable_http(self, tmp_path):
+        """Test that v1 server uses async streamable-http method."""
+        from unittest.mock import AsyncMock, patch
+
+        from mcp.server.mcpserver import MCPServer as SDKServer
+
+        from fastmcp.cli.run import run_command
+
+        # Create a v1 FastMCP server file with both sync and async tools
+        test_file = tmp_path / "v1_server.py"
+        test_file.write_text("""
+from mcp.server.mcpserver import MCPServer as FastMCP
+
+mcp = FastMCP("V1Server")
+
+@mcp.tool()
+def sync_echo(text: str) -> str:
+    '''Sync tool for testing'''
+    return f"sync: {text}"
+
+@mcp.tool()
+async def async_echo(text: str) -> str:
+    '''Async tool for testing'''
+    return f"async: {text}"
+""")
+
+        # Mock the async run method
+        with patch.object(
+            SDKServer, "run_streamable_http_async", new_callable=AsyncMock
+        ) as run_mock:
+            await run_command(str(test_file), transport="streamable-http")
+            run_mock.assert_called_once()
+
+    async def test_run_v1_server_sse(self, tmp_path):
+        """Test that v1 server uses async sse method."""
+        from unittest.mock import AsyncMock, patch
+
+        from mcp.server.mcpserver import MCPServer as SDKServer
+
+        from fastmcp.cli.run import run_command
+
+        # Create a v1 FastMCP server file with both sync and async tools
+        test_file = tmp_path / "v1_server.py"
+        test_file.write_text("""
+from mcp.server.mcpserver import MCPServer as FastMCP
+
+mcp = FastMCP("V1Server")
+
+@mcp.tool()
+def sync_echo(text: str) -> str:
+    '''Sync tool for testing'''
+    return f"sync: {text}"
+
+@mcp.tool()
+async def async_echo(text: str) -> str:
+    '''Async tool for testing'''
+    return f"async: {text}"
+""")
+
+        # Mock the async run method
+        with patch.object(
+            SDKServer, "run_sse_async", new_callable=AsyncMock
+        ) as run_mock:
+            await run_command(str(test_file), transport="sse")
+            run_mock.assert_called_once()
+
+    async def test_run_v1_server_default_transport(self, tmp_path):
+        """Test that v1 server uses streamable-http by default."""
+        from unittest.mock import AsyncMock, patch
+
+        from mcp.server.mcpserver import MCPServer as SDKServer
+
+        from fastmcp.cli.run import run_command
+
+        # Create a v1 FastMCP server file with both sync and async tools
+        test_file = tmp_path / "v1_server.py"
+        test_file.write_text("""
+from mcp.server.mcpserver import MCPServer as FastMCP
+
+mcp = FastMCP("V1Server")
+
+@mcp.tool()
+def sync_echo(text: str) -> str:
+    '''Sync tool for testing'''
+    return f"sync: {text}"
+
+@mcp.tool()
+async def async_echo(text: str) -> str:
+    '''Async tool for testing'''
+    return f"async: {text}"
+""")
+
+        # Mock the async run method
+        with patch.object(
+            SDKServer, "run_streamable_http_async", new_callable=AsyncMock
+        ) as run_mock:
+            await run_command(str(test_file))
+            run_mock.assert_called_once()
+
+    async def test_run_v1_server_with_host_port(self, tmp_path):
+        """Test that v1 server receives host/port settings."""
+        from unittest.mock import AsyncMock, patch
+
+        from mcp.server.mcpserver import MCPServer as SDKServer
+
+        from fastmcp.cli.run import run_command
+
+        # Create a v1 FastMCP server file with both sync and async tools
+        test_file = tmp_path / "v1_server.py"
+        test_file.write_text("""
+from mcp.server.mcpserver import MCPServer as FastMCP
+
+mcp = FastMCP("V1Server")
+
+@mcp.tool()
+def sync_echo(text: str) -> str:
+    '''Sync tool for testing'''
+    return f"sync: {text}"
+
+@mcp.tool()
+async def async_echo(text: str) -> str:
+    '''Async tool for testing'''
+    return f"async: {text}"
+""")
+
+        # Mock the async run method
+        with patch.object(
+            SDKServer, "run_streamable_http_async", new_callable=AsyncMock
+        ) as run_mock:
+            await run_command(
+                str(test_file), transport="http", host="0.0.0.0", port=9000
+            )
+            run_mock.assert_called_once()
+
+
+class TestSkipSource:
+    """Test the --skip-source functionality."""
+
+    async def test_run_command_calls_prepare_by_default(self, tmp_path):
+        """Test that run_command calls source.prepare() by default."""
+        from unittest.mock import AsyncMock, patch
+
+        from fastmcp.cli.run import run_command
+
+        # Create a test server file
+        test_file = tmp_path / "server.py"
+        test_file.write_text("""
+import fastmcp
+mcp = fastmcp.FastMCP("TestServer")
+""")
+
+        # Create a test config file
+        config_file = tmp_path / "fastmcp.json"
+        config_data = {"source": {"path": str(test_file), "entrypoint": "mcp"}}
+        config_file.write_text(json.dumps(config_data))
+
+        # Mock the prepare method and server run
+        with (
+            patch.object(
+                FileSystemSource, "prepare", new_callable=AsyncMock
+            ) as prepare_mock,
+            patch("fastmcp.server.server.FastMCP.run_async", new_callable=AsyncMock),
+        ):
+            # Run the command
+            await run_command(str(config_file))
+
+            # Verify prepare was called
+            prepare_mock.assert_called_once()
+
+    async def test_run_command_skips_prepare_with_flag(self, tmp_path):
+        """Test that run_command skips source.prepare() when skip_source=True."""
+        from unittest.mock import AsyncMock, patch
+
+        from fastmcp.cli.run import run_command
+
+        # Create a test server file
+        test_file = tmp_path / "server.py"
+        test_file.write_text("""
+import fastmcp
+mcp = fastmcp.FastMCP("TestServer")
+""")
+
+        # Create a test config file
+        config_file = tmp_path / "fastmcp.json"
+        config_data = {"source": {"path": str(test_file), "entrypoint": "mcp"}}
+        config_file.write_text(json.dumps(config_data))
+
+        # Mock the prepare method and server run
+        with (
+            patch.object(
+                FileSystemSource, "prepare", new_callable=AsyncMock
+            ) as prepare_mock,
+            patch("fastmcp.server.server.FastMCP.run_async", new_callable=AsyncMock),
+        ):
+            # Run the command with skip_source=True
+            await run_command(str(config_file), skip_source=True)
+
+            # Verify prepare was NOT called
+            prepare_mock.assert_not_called()
+
+    async def test_filesystem_source_prepare_by_default(self, tmp_path):
+        """Test that FileSystemSource is prepared when using direct file spec."""
+        from unittest.mock import AsyncMock, patch
+
+        from fastmcp.cli.run import run_command
+        from fastmcp.utilities.mcp_server_config.v1.sources.filesystem import (
+            FileSystemSource,
+        )
+
+        # Create a test server file
+        test_file = tmp_path / "server.py"
+        test_file.write_text("""
+import fastmcp
+mcp = fastmcp.FastMCP("TestServer")
+""")
+
+        # Mock the prepare method and server run
+        with (
+            patch.object(
+                FileSystemSource, "prepare", new_callable=AsyncMock
+            ) as prepare_mock,
+            patch("fastmcp.server.server.FastMCP.run_async", new_callable=AsyncMock),
+        ):
+            # Run with direct file specification
+            await run_command(str(test_file))
+
+            # Verify prepare was called
+            prepare_mock.assert_called_once()
+
+    async def test_filesystem_source_skip_prepare_with_flag(self, tmp_path):
+        """Test that FileSystemSource.prepare() is skipped with skip_source flag."""
+        from unittest.mock import AsyncMock, patch
+
+        from fastmcp.cli.run import run_command
+        from fastmcp.utilities.mcp_server_config.v1.sources.filesystem import (
+            FileSystemSource,
+        )
+
+        # Create a test server file
+        test_file = tmp_path / "server.py"
+        test_file.write_text("""
+import fastmcp
+mcp = fastmcp.FastMCP("TestServer")
+""")
+
+        # Mock the prepare method and server run
+        with (
+            patch.object(
+                FileSystemSource, "prepare", new_callable=AsyncMock
+            ) as prepare_mock,
+            patch("fastmcp.server.server.FastMCP.run_async", new_callable=AsyncMock),
+        ):
+            # Run with direct file specification and skip_source=True
+            await run_command(str(test_file), skip_source=True)
+
+            # Verify prepare was NOT called
+            prepare_mock.assert_not_called()
+
+
+class TestReloadFunctionality:
+    """Test reload functionality."""
+
+    def test_watch_filter_accepts_watched_extensions(self):
+        """Test that watch filter accepts common source file extensions."""
+        from watchfiles import Change
+
+        from fastmcp.cli.run import _watch_filter
+
+        # Python
+        assert _watch_filter(Change.modified, "/path/to/file.py") is True
+        assert _watch_filter(Change.added, "server.py") is True
+        # JavaScript/TypeScript
+        assert _watch_filter(Change.modified, "/path/to/file.js") is True
+        assert _watch_filter(Change.modified, "/path/to/file.ts") is True
+        assert _watch_filter(Change.modified, "/path/to/file.jsx") is True
+        assert _watch_filter(Change.modified, "/path/to/file.tsx") is True
+        # Markup/Content
+        assert _watch_filter(Change.modified, "/path/to/file.html") is True
+        assert _watch_filter(Change.modified, "/path/to/file.md") is True
+        assert _watch_filter(Change.modified, "/path/to/file.txt") is True
+        # Styles
+        assert _watch_filter(Change.modified, "/path/to/file.css") is True
+        assert _watch_filter(Change.modified, "/path/to/file.scss") is True
+        # Data/Config
+        assert _watch_filter(Change.modified, "/path/to/file.json") is True
+        assert _watch_filter(Change.modified, "/path/to/file.yaml") is True
+        # Images
+        assert _watch_filter(Change.modified, "/path/to/file.png") is True
+        assert _watch_filter(Change.modified, "/path/to/file.svg") is True
+
+    def test_watch_filter_rejects_unwatched_extensions(self):
+        """Test that watch filter rejects files not in the watched set."""
+        from watchfiles import Change
+
+        from fastmcp.cli.run import _watch_filter
+
+        assert _watch_filter(Change.modified, "/path/to/file.pyc") is False
+        assert _watch_filter(Change.modified, "/path/to/file.pyo") is False
+        assert _watch_filter(Change.modified, "Dockerfile") is False
+        assert _watch_filter(Change.modified, "/path/to/file.lock") is False
+        assert _watch_filter(Change.modified, "/path/to/.gitignore") is False
+
+    def test_all_watched_extensions_are_accepted(self):
+        """Test that every extension in WATCHED_EXTENSIONS is accepted."""
+        from watchfiles import Change
+
+        from fastmcp.cli.run import WATCHED_EXTENSIONS, _watch_filter
+
+        for ext in WATCHED_EXTENSIONS:
+            path = f"/path/to/file{ext}"
+            assert _watch_filter(Change.modified, path) is True, (
+                f"Expected {ext} to be watched"
+            )
+
+    def test_watched_extensions_includes_frontend_types(self):
+        """Verify WATCHED_EXTENSIONS contains the expected frontend file types."""
+        from fastmcp.cli.run import WATCHED_EXTENSIONS
+
+        # Core frontend extensions that must be present
+        expected = {
+            # Python
+            ".py",
+            # JavaScript/TypeScript
+            ".js",
+            ".ts",
+            ".jsx",
+            ".tsx",
+            # Markup
+            ".html",
+            ".md",
+            ".mdx",
+            ".xml",
+            # Styles
+            ".css",
+            ".scss",
+            ".sass",
+            ".less",
+            # Data/Config
+            ".json",
+            ".yaml",
+            ".yml",
+            ".toml",
+            # Images
+            ".png",
+            ".jpg",
+            ".svg",
+            # Media
+            ".mp4",
+            ".mp3",
+        }
+        for ext in expected:
+            assert ext in WATCHED_EXTENSIONS, f"Expected {ext} in WATCHED_EXTENSIONS"
+
+
+class TestRunModuleCommand:
+    """Test run_module_command functionality."""
+
+    def test_runs_python_m_module(self):
+        """Test that run_module_command invokes python -m <module>."""
+        mock_result = MagicMock()
+        mock_result.returncode = 0
+
+        with (
+            patch(
+                "fastmcp.cli.run.subprocess.run", return_value=mock_result
+            ) as mock_run,
+            pytest.raises(SystemExit) as exc_info,
+        ):
+            run_module_command("my_package")
+
+        assert exc_info.value.code == 0
+        call_args = mock_run.call_args
+        cmd = call_args[0][0]
+        assert "-m" in cmd
+        assert "my_package" in cmd
+
+    def test_forwards_extra_args(self):
+        """Test that extra arguments are forwarded after the module name."""
+        mock_result = MagicMock()
+        mock_result.returncode = 0
+
+        with (
+            patch(
+                "fastmcp.cli.run.subprocess.run", return_value=mock_result
+            ) as mock_run,
+            pytest.raises(SystemExit),
+        ):
+            run_module_command("my_package", extra_args=["--host", "0.0.0.0"])
+
+        cmd = mock_run.call_args[0][0]
+        assert "--host" in cmd
+        assert "0.0.0.0" in cmd
+
+    def test_uses_env_command_builder(self):
+        """Test that env_command_builder wraps the command."""
+        mock_result = MagicMock()
+        mock_result.returncode = 0
+
+        def fake_builder(cmd: list[str]) -> list[str]:
+            return ["uv", "run", *cmd]
+
+        with (
+            patch(
+                "fastmcp.cli.run.subprocess.run", return_value=mock_result
+            ) as mock_run,
+            pytest.raises(SystemExit),
+        ):
+            run_module_command("my_package", env_command_builder=fake_builder)
+
+        cmd = mock_run.call_args[0][0]
+        assert cmd[0] == "uv"
+        assert cmd[1] == "run"
+        # Should use bare "python" (not sys.executable) so uv resolves the interpreter
+        assert cmd[2] == "python"
+        assert "-m" in cmd
+        assert "my_package" in cmd
+
+    def test_exits_with_subprocess_error_code(self):
+        """Test that non-zero exit codes from the module are propagated."""
+        with (
+            patch(
+                "fastmcp.cli.run.subprocess.run",
+                side_effect=subprocess.CalledProcessError(42, ["python", "-m", "bad"]),
+            ),
+            pytest.raises(SystemExit) as exc_info,
+        ):
+            run_module_command("bad")
+
+        assert exc_info.value.code == 42
+
+    def test_no_env_builder_runs_plain_python(self):
+        """Test that without env_command_builder, plain python is used."""
+        mock_result = MagicMock()
+        mock_result.returncode = 0
+
+        with (
+            patch(
+                "fastmcp.cli.run.subprocess.run", return_value=mock_result
+            ) as mock_run,
+            pytest.raises(SystemExit),
+        ):
+            run_module_command("my_module", env_command_builder=None)
+
+        cmd = mock_run.call_args[0][0]
+        assert cmd[0] == sys.executable
+        assert cmd[1] == "-m"
+        assert cmd[2] == "my_module"
+
+
+class TestRunModuleMode:
+    """Test the run command's module-mode branch."""
+
+    async def test_run_module_mode_requires_server_spec(self):
+        """Test that module mode exits with error when server_spec is None."""
+        with pytest.raises(SystemExit) as exc_info:
+            await run(None, module=True)
+
+        assert exc_info.value.code == 1
+
+    async def test_run_module_mode_warns_ignored_options(self, caplog):
+        """Test that ignored options produce a warning in module mode."""
+        mock_result = MagicMock()
+        mock_result.returncode = 0
+
+        with (
+            patch("fastmcp.cli.run.subprocess.run", return_value=mock_result),
+            pytest.raises(SystemExit),
+            caplog.at_level("WARNING"),
+        ):
+            await run(
+                "my_module",
+                module=True,
+                transport="sse",
+                host="0.0.0.0",
+                port=8080,
+            )
+
+        assert any("ignored in module mode" in r.message for r in caplog.records)
+
+    async def test_run_module_mode_delegates_to_run_module_command(self):
+        """Test that module mode calls run_module_command with correct args."""
+        mock_result = MagicMock()
+        mock_result.returncode = 0
+
+        with (
+            patch(
+                "fastmcp.cli.run.subprocess.run", return_value=mock_result
+            ) as mock_subprocess,
+            pytest.raises(SystemExit),
+        ):
+            await run("my_module", module=True)
+
+        cmd = mock_subprocess.call_args[0][0]
+        assert "-m" in cmd
+        assert "my_module" in cmd
+
+    async def test_run_module_mode_with_reload(self):
+        """Test that --reload in module mode delegates to run_with_reload."""
+        with patch(
+            "fastmcp.cli.run.run_with_reload", new_callable=AsyncMock
+        ) as mock_reload:
+            await run("my_module", module=True, reload=True, skip_env=True)
+
+        mock_reload.assert_called_once()
+        cmd = mock_reload.call_args[0][0]
+        assert "fastmcp" in cmd
+        assert "--module" in cmd
+        assert "--no-reload" in cmd
+        assert "my_module" in cmd
+
+
+class TestRunWithReloadWithServerArgs:
+    """Test the run command with reload(run_with_reload) with server args."""
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        "reload_cmd",
+        [
+            [
+                "fastmcp",
+                "run",
+                "my_module",
+                "--module",
+                "--no-reload",
+                "--no-banner",
+                "--",
+                "--debug",
+            ],
+            [
+                "fastmcp",
+                "run",
+                "my_module",
+                "--no-banner",
+                "--no-reload",
+                "--stateless",
+                "--",
+                "--debug",
+            ],
+            ["fastmcp", "run", "my_module", "--module", "--no-reload", "--", "--debug"],
+            [
+                "fastmcp",
+                "run",
+                "my_module",
+                "--no-reload",
+                "--stateless",
+                "--",
+                "--debug",
+            ],
+        ],
+    )
+    async def test_run_with_reload_does_not_mutate_command(self, reload_cmd, caplog):
+        """
+        Test for issue 4081:
+        Verify that run_with_reload does NOT mutate the command arguments.
+        The command used for restart must be identical to the original command
+        to ensure nothing is incorrectly appended or reordered.
+        """
+        reload_dirs = [Path(".")]
+        shutdown_event = asyncio.Event()
+        call_count = 0
+
+        async def mock_create_subprocess(*args, **kwargs):
+            nonlocal call_count
+            call_count += 1
+
+            proc = AsyncMock()
+            proc.kill = MagicMock()
+            proc.terminate = MagicMock()
+            proc.wait.return_value = 0
+            proc.pid = 99999
+            proc.returncode = None
+
+            if call_count >= 2:
+                actual_args = list(args)
+                try:
+                    # VALIDATION: reload_cmd remains UNCHANGED
+                    assert actual_args == reload_cmd, (
+                        f"Regression: Command was mutated during reload.\n"
+                        f"Expected: {reload_cmd}\n"
+                        f"Actual:   {actual_args}"
+                    )
+                finally:
+                    shutdown_event.set()
+
+            return proc
+
+        mock_watch = MagicMock()
+        mock_watch.__aiter__.return_value = iter([[("Change.modified", "server.py")]])
+
+        with (
+            patch(
+                "fastmcp.cli.run.asyncio.create_subprocess_exec",
+                side_effect=mock_create_subprocess,
+            ),
+            patch("fastmcp.cli.run.awatch", return_value=mock_watch),
+            patch("fastmcp.cli.run.asyncio.Event", return_value=shutdown_event),
+            caplog.at_level("INFO"),
+        ):
+            await run_with_reload(reload_cmd, reload_dirs=reload_dirs)
+
+        assert any("Detected changes" in record.message for record in caplog.records)
+        assert call_count == 2, f"Restart logic was not triggered for {reload_cmd}"
+
+    async def test_run_with_needs_uv_forwards_stateless_flag(self):
+        """`--stateless` should survive the uv-wrapped subprocess path."""
+        mock_config = MagicMock()
+        mock_config.deployment.transport = None
+        mock_config.deployment.host = None
+        mock_config.deployment.port = None
+        mock_config.deployment.path = None
+        mock_config.deployment.log_level = None
+        mock_config.deployment.args = ()
+        mock_config.environment.build_command = lambda cmd: ["uv", "run", *cmd]
+
+        mock_result = MagicMock()
+        mock_result.returncode = 0
+
+        with (
+            patch(
+                "fastmcp.cli.cli.load_and_merge_config",
+                return_value=(mock_config, "server.py"),
+            ),
+            patch(
+                "fastmcp.cli.cli.subprocess.run", return_value=mock_result
+            ) as mock_run,
+            pytest.raises(SystemExit) as exc_info,
+        ):
+            await run("server.py", stateless=True)
+
+        assert exc_info.value.code == 0
+        cmd = mock_run.call_args.args[0]
+        assert "--stateless" in cmd
+        assert cmd[cmd.index("--stateless") - 3 : cmd.index("--stateless") + 1] == [
+            "fastmcp",
+            "run",
+            "server.py",
+            "--stateless",
+        ]
+
+
+class TestInspectorModuleMode:
+    """Test the inspector command's module-mode handling."""
+
+    async def test_inspector_module_mode_skips_load_server(self):
+        """Test that inspector with module=True skips load_server() and forwards --module."""
+        mock_config = MagicMock()
+        mock_config.deployment.port = 8080
+        mock_config.environment.build_command = lambda cmd: cmd
+        mock_config.source.load_server = AsyncMock()
+
+        mock_process = MagicMock()
+        mock_process.returncode = 0
+
+        with (
+            patch(
+                "fastmcp.cli.cli.load_and_merge_config",
+                return_value=(mock_config, "my_module"),
+            ),
+            patch("fastmcp.cli.cli._get_npx_command", return_value="npx"),
+            patch(
+                "fastmcp.cli.cli.subprocess.run", return_value=mock_process
+            ) as mock_subprocess,
+            pytest.raises(SystemExit),
+        ):
+            await inspector("my_module", module=True)
+
+        # load_server should NOT have been called in module mode
+        mock_config.source.load_server.assert_not_called()
+
+        # --module should be in the subprocess command
+        cmd = mock_subprocess.call_args[0][0]
+        assert "--module" in cmd
+
+
+class TestRunDevApps:
+    """Test running dev apps with the run command."""
+
+    def test_launch_escapes_tool_name_in_html_contexts(self):
+        """Test /launch escapes the tool query parameter in HTML sinks."""
+        starlette_app = _make_dev_app(
+            mcp_url="http://127.0.0.1:8000/mcp",
+            app_bridge_js="// js",
+            import_map_tag="",
+            message_log=_MessageLog(),
+            log_panel=False,
+        )
+        client = TestClient(starlette_app, raise_server_exceptions=False)
+
+        payload = "</title><script>alert(1)</script><img src=x onerror=alert(2)>"
+        response = client.get("/launch", params={"tool": payload, "args": "{}"})
+
+        assert response.status_code == 200
+        assert payload not in response.text
+        assert (
+            "&lt;/title&gt;&lt;script&gt;alert(1)&lt;/script&gt;"
+            "&lt;img src=x onerror=alert(2)&gt;"
+        ) in response.text
+        assert "\\u003c/script\\u003e" in response.text
+
+    def test_launch_serializes_args_safely_inside_script(self):
+        """Test /launch escapes argument values embedded in the script element."""
+        starlette_app = _make_dev_app(
+            mcp_url="http://127.0.0.1:8000/mcp",
+            app_bridge_js="// js",
+            import_map_tag="",
+            message_log=_MessageLog(),
+            log_panel=False,
+        )
+        client = TestClient(starlette_app, raise_server_exceptions=False)
+
+        payload = {"name": "</script><script>alert(1)</script>&"}
+        response = client.get(
+            "/launch",
+            params={"tool": "safe_tool", "args": json.dumps(payload)},
+        )
+
+        assert response.status_code == 200
+        assert json.dumps(payload) not in response.text
+        assert (
+            '"\\u003c/script\\u003e\\u003cscript\\u003ealert(1)'
+            '\\u003c/script\\u003e\\u0026"'
+        ) in response.text
+
+    def test_api_launch_encodes_generated_launch_url(self):
+        """Test /api/launch encodes query parameters in the returned URL."""
+        starlette_app = _make_dev_app(
+            mcp_url="http://127.0.0.1:8000/mcp",
+            app_bridge_js="// js",
+            import_map_tag="",
+            message_log=_MessageLog(),
+            log_panel=False,
+        )
+        client = TestClient(starlette_app, raise_server_exceptions=False)
+
+        response = client.post(
+            "/api/launch",
+            json={
+                "tool": "tool&name=<script>",
+                "__json_args__": '{"value": "</script>"}',
+            },
+        )
+
+        assert response.status_code == 200
+        url = response.json()
+        query = parse_qs(urlsplit(url).query)
+        assert query["tool"] == ["tool&name=<script>"]
+        assert json.loads(query["args"][0]) == {"value": "</script>"}
+
+    @pytest.mark.parametrize(
+        "host, expected_host",
+        [
+            ("0.0.0.0", "0.0.0.0"),
+            ("127.0.0.1", "127.0.0.1"),
+        ],
+    )
+    async def test_run_dev_apps_with_host(self, host, expected_host):
+        """Test run command can run a dev app with below new options for issue 4121.
+        - host option to support binding specific address other than localhost.
+        """
+        mock_proc = MagicMock()
+        mock_proc.returncode = 0
+
+        mock_server = AsyncMock()
+        mock_server.install_signal_handlers = MagicMock()
+        mock_server.serve = AsyncMock()
+
+        mock_uvicorn = MagicMock()
+        mock_uvicorn.Config = MagicMock()
+        mock_uvicorn.Server.return_value = mock_server
+
+        mock_make_dev_app = MagicMock(return_value=MagicMock())
+        mock_webbrowser_open = MagicMock()
+
+        with (
+            patch(
+                "fastmcp.cli.apps_dev._start_user_server",
+                new_callable=AsyncMock,
+                return_value=mock_proc,
+            ),
+            patch(
+                "fastmcp.cli.apps_dev._fetch_app_bridge_bundle",
+                new_callable=AsyncMock,
+                return_value=("js_content", "{}"),
+            ),
+            patch(
+                "fastmcp.cli.apps_dev._wait_for_server",
+                new_callable=AsyncMock,
+                return_value=True,
+            ),
+            patch("fastmcp.cli.apps_dev._make_dev_app", mock_make_dev_app),
+            patch("fastmcp.cli.apps_dev.uvicorn", mock_uvicorn),
+            patch("fastmcp.cli.apps_dev.webbrowser.open", mock_webbrowser_open),
+            patch("fastmcp.cli.apps_dev.asyncio.sleep", new_callable=AsyncMock),
+            patch("socket.socket"),
+        ):
+            await apps("server.py", host=host)
+
+        make_dev_app_first_arg = mock_make_dev_app.call_args[0][0]
+        assert expected_host in make_dev_app_first_arg
+
+        webbrowser_open_first_arg = mock_webbrowser_open.call_args[0][0]
+        assert expected_host in webbrowser_open_first_arg
+
+    @pytest.mark.parametrize(
+        "log_panel, expected_log_panel",
+        [
+            (True, True),
+            (False, False),
+        ],
+    )
+    async def test_run_dev_apps_log_panel_propagation(
+        self, log_panel, expected_log_panel
+    ):
+        """Test run command can run a dev app with below new options for issue 4121.
+        - toggle log-panel option to hide log/debug message in normal cases.
+
+        The test divided into two parts:
+        - first, verify if log_panel is correctly propagated to _make_dev_app.
+        - second, verify if _make_dev_app calls _inject_log_panel only when log_panel=True
+
+        This test function implements the first part, and the second part is implemented in test_make_dev_app_log_panel_controls_inject
+        """
+
+        mock_proc = MagicMock()
+        mock_proc.returncode = 0
+
+        mock_server = AsyncMock()
+        mock_server.install_signal_handlers = MagicMock()
+        mock_server.serve = AsyncMock()
+
+        mock_uvicorn = MagicMock()
+        mock_uvicorn.Config = MagicMock()
+        mock_uvicorn.Server.return_value = mock_server
+
+        mock_make_dev_app = MagicMock(return_value=MagicMock())
+        mock_webbrowser_open = MagicMock()
+
+        with (
+            patch(
+                "fastmcp.cli.apps_dev._start_user_server",
+                new_callable=AsyncMock,
+                return_value=mock_proc,
+            ),
+            patch(
+                "fastmcp.cli.apps_dev._fetch_app_bridge_bundle",
+                new_callable=AsyncMock,
+                return_value=("js_content", "{}"),
+            ),
+            patch(
+                "fastmcp.cli.apps_dev._wait_for_server",
+                new_callable=AsyncMock,
+                return_value=True,
+            ),
+            patch("fastmcp.cli.apps_dev._make_dev_app", mock_make_dev_app),
+            patch("fastmcp.cli.apps_dev.uvicorn", mock_uvicorn),
+            patch("fastmcp.cli.apps_dev.webbrowser.open", mock_webbrowser_open),
+            patch("fastmcp.cli.apps_dev.asyncio.sleep", new_callable=AsyncMock),
+            patch("socket.socket"),
+        ):
+            await apps("server.py", log_panel=log_panel)
+
+        # log_panel is the 5th positional argument to _make_dev_app
+        actual_log_panel = mock_make_dev_app.call_args[0][4]
+        assert actual_log_panel is expected_log_panel
+
+    @pytest.mark.parametrize("log_panel", [True, False])
+    def test_make_dev_app_log_panel_controls_inject(self, log_panel):
+        """Test if _make_dev_app calls _inject_log_panel only when log_panel=True, regarding issue 4121:
+        - toggle log-panel option to hide log/debug message in normal cases.
+
+        The test divided into two parts:
+        - first, verify if log_panel is correctly propagated to _make_dev_app.
+        - second, verify if _make_dev_app calls _inject_log_panel only when log_panel=True
+
+        This test function implements the second part, and the first part is implemented in test_run_dev_apps_log_panel_propagation
+        """
+
+        mock_message_log = _MessageLog()
+
+        with patch(
+            "fastmcp.cli.apps_dev._inject_log_panel",
+            return_value="<html>injected</html>",
+        ) as mock_inject:
+            starlette_app = _make_dev_app(
+                mcp_url="http://127.0.0.1:8000/mcp",
+                app_bridge_js="// js",
+                import_map_tag="",
+                message_log=mock_message_log,
+                log_panel=log_panel,
+            )
+            client = TestClient(starlette_app, raise_server_exceptions=False)
+            client.get("/")
+
+        if log_panel:
+            mock_inject.assert_called_once()
+        else:
+            mock_inject.assert_not_called()
diff --git a/tests/cli/test_run_config.py b/tests/cli/test_run_config.py
new file mode 100644
index 0000000..4d1036a
--- /dev/null
+++ b/tests/cli/test_run_config.py
@@ -0,0 +1,312 @@
+"""Integration tests for FastMCP configuration with run command."""
+
+import json
+import os
+from pathlib import Path
+
+import pytest
+
+from fastmcp.cli.run import load_mcp_server_config
+from fastmcp.utilities.mcp_server_config import (
+    Deployment,
+    MCPServerConfig,
+)
+from fastmcp.utilities.mcp_server_config.v1.environments.uv import UVEnvironment
+from fastmcp.utilities.mcp_server_config.v1.sources.filesystem import FileSystemSource
+
+
+@pytest.fixture
+def sample_config(tmp_path):
+    """Create a sample fastmcp.json configuration file with nested structure."""
+    config_data = {
+        "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+        "source": {"path": "server.py"},
+        "environment": {"python": "3.11", "dependencies": ["requests"]},
+        "deployment": {"transport": "stdio", "env": {"TEST_VAR": "test_value"}},
+    }
+
+    config_file = tmp_path / "fastmcp.json"
+    config_file.write_text(json.dumps(config_data, indent=2))
+
+    # Create a simple server file
+    server_file = tmp_path / "server.py"
+    server_file.write_text("""
+from fastmcp import FastMCP
+
+mcp = FastMCP("Test Server")
+
+@mcp.tool
+def test_tool(message: str) -> str:
+    return f"Echo: {message}"
+""")
+
+    return config_file
+
+
+def test_load_mcp_server_config(sample_config, monkeypatch):
+    """Test loading configuration and returning config subsets."""
+
+    # Capture environment changes
+    original_env = dict(os.environ)
+
+    try:
+        config = load_mcp_server_config(sample_config)
+
+        # Check that we got the right types
+        assert isinstance(config, MCPServerConfig)
+        assert isinstance(config.source, FileSystemSource)
+        assert isinstance(config.deployment, Deployment)
+        assert isinstance(config.environment, UVEnvironment)
+
+        # Check source - path is not resolved yet, only during load_server
+        assert config.source.path == "server.py"
+        assert config.source.entrypoint is None
+
+        # Check environment config
+        assert config.environment.python == "3.11"
+        assert config.environment.dependencies == ["requests"]
+
+        # Check deployment config
+        assert config.deployment.transport == "stdio"
+        assert config.deployment.env == {"TEST_VAR": "test_value"}
+
+        # Check that environment variables were applied
+        assert os.environ.get("TEST_VAR") == "test_value"
+
+    finally:
+        # Restore original environment
+        os.environ.clear()
+        os.environ.update(original_env)
+
+
+def test_load_config_with_entrypoint_source(tmp_path):
+    """Test loading config with entrypoint-format source."""
+    config_data = {
+        "source": {"path": "src/server.py", "entrypoint": "app"},
+        "deployment": {"transport": "http", "port": 8000},
+    }
+
+    config_file = tmp_path / "fastmcp.json"
+    config_file.write_text(json.dumps(config_data))
+
+    # Create the server file in subdirectory
+    src_dir = tmp_path / "src"
+    src_dir.mkdir()
+    server_file = src_dir / "server.py"
+    server_file.write_text("# Server")
+
+    config = load_mcp_server_config(config_file)
+
+    # Check source - path is not resolved yet, only during load_server
+    assert config.source.path == "src/server.py"
+    assert config.source.entrypoint == "app"
+
+    # Check deployment
+    assert config.deployment.transport == "http"
+    assert config.deployment.port == 8000
+
+
+def test_load_config_with_cwd(tmp_path):
+    """Test that Deployment applies working directory change."""
+
+    # Create a subdirectory
+    subdir = tmp_path / "subdir"
+    subdir.mkdir()
+
+    config_data = {"source": {"path": "server.py"}, "deployment": {"cwd": "subdir"}}
+
+    config_file = tmp_path / "fastmcp.json"
+    config_file.write_text(json.dumps(config_data))
+
+    # Create server file in subdirectory
+    server_file = subdir / "server.py"
+    server_file.write_text("# Test server")
+
+    original_cwd = os.getcwd()
+
+    try:
+        config = load_mcp_server_config(config_file)  # noqa: F841
+
+        # Check that working directory was changed
+        assert Path.cwd() == subdir.resolve()
+
+    finally:
+        # Restore original working directory
+        os.chdir(original_cwd)
+
+
+def test_load_config_with_relative_cwd(tmp_path):
+    """Test configuration with relative working directory."""
+
+    # Create nested subdirectories
+    subdir1 = tmp_path / "dir1"
+    subdir2 = subdir1 / "dir2"
+    subdir2.mkdir(parents=True)
+
+    config_data = {
+        "source": {"path": "server.py"},
+        "deployment": {
+            "cwd": "../"  # Relative to config file location
+        },
+    }
+
+    config_file = subdir2 / "fastmcp.json"
+    config_file.write_text(json.dumps(config_data))
+
+    # Create server file in parent directory
+    server_file = subdir1 / "server.py"
+    server_file.write_text("# Server")
+
+    original_cwd = os.getcwd()
+
+    try:
+        config = load_mcp_server_config(config_file)  # noqa: F841
+
+        # Should change to parent directory of config file
+        assert Path.cwd() == subdir1.resolve()
+
+    finally:
+        os.chdir(original_cwd)
+
+
+def test_load_minimal_config(tmp_path):
+    """Test loading minimal configuration with only source."""
+    config_data = {"source": {"path": "server.py"}}
+
+    config_file = tmp_path / "fastmcp.json"
+    config_file.write_text(json.dumps(config_data))
+
+    # Create server file
+    server_file = tmp_path / "server.py"
+    server_file.write_text("# Server")
+
+    config = load_mcp_server_config(config_file)
+
+    # Check we got source - path is not resolved yet, only during load_server
+    assert isinstance(config.source, FileSystemSource)
+    assert config.source.path == "server.py"
+
+
+def test_load_config_with_server_args(tmp_path):
+    """Test configuration with server arguments."""
+    config_data = {
+        "source": {"path": "server.py"},
+        "deployment": {"args": ["--debug", "--config", "custom.json"]},
+    }
+
+    config_file = tmp_path / "fastmcp.json"
+    config_file.write_text(json.dumps(config_data))
+
+    # Create server file
+    server_file = tmp_path / "server.py"
+    server_file.write_text("# Server")
+
+    config = load_mcp_server_config(config_file)
+
+    assert config.deployment.args == ["--debug", "--config", "custom.json"]
+
+
+def test_load_config_with_log_level(tmp_path):
+    """Test configuration with log_level setting."""
+    config_data = {
+        "source": {"path": "server.py"},
+        "deployment": {"log_level": "DEBUG"},
+    }
+
+    config_file = tmp_path / "fastmcp.json"
+    config_file.write_text(json.dumps(config_data))
+
+    # Create server file
+    server_file = tmp_path / "server.py"
+    server_file.write_text("# Server")
+
+    config = load_mcp_server_config(config_file)
+
+    assert config.deployment.log_level == "DEBUG"
+
+
+def test_load_config_with_various_log_levels(tmp_path):
+    """Test that all valid log levels are accepted."""
+    valid_levels = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+    for level in valid_levels:
+        config_data = {
+            "source": {"path": "server.py"},
+            "deployment": {"log_level": level},
+        }
+
+        config_file = tmp_path / f"fastmcp_{level}.json"
+        config_file.write_text(json.dumps(config_data))
+
+        # Create server file
+        server_file = tmp_path / "server.py"
+        server_file.write_text("# Server")
+
+        config = load_mcp_server_config(config_file)
+
+        assert config.deployment.log_level == level
+
+
+def test_config_subset_independence(tmp_path):
+    """Test that config subsets can be used independently."""
+    config_data = {
+        "source": {"path": "server.py"},
+        "environment": {"python": "3.12", "dependencies": ["pandas"]},
+        "deployment": {"transport": "http", "host": "0.0.0.0", "port": 3000},
+    }
+
+    config_file = tmp_path / "fastmcp.json"
+    config_file.write_text(json.dumps(config_data))
+
+    # Create server file
+    server_file = tmp_path / "server.py"
+    server_file.write_text("# Server")
+
+    config = load_mcp_server_config(config_file)
+
+    # Each subset should be independently usable
+    # Path is not resolved yet, only during load_server
+    assert config.source.path == "server.py"
+    assert config.source.entrypoint is None
+
+    assert config.environment.python == "3.12"
+    assert config.environment.dependencies == ["pandas"]
+    assert config.environment._must_run_with_uv()  # Has dependencies
+
+    assert config.deployment.transport == "http"
+    assert config.deployment.host == "0.0.0.0"
+    assert config.deployment.port == 3000
+
+
+def test_environment_config_path_resolution(tmp_path):
+    """Test that paths in environment config are resolved correctly."""
+    # Create requirements file
+    reqs_file = tmp_path / "requirements.txt"
+    reqs_file.write_text("fastmcp>=2.0")
+
+    config_data = {
+        "source": {"path": "server.py"},
+        "environment": {
+            "requirements": "requirements.txt",
+            "project": ".",
+            "editable": ["../other-project"],
+        },
+    }
+
+    config_file = tmp_path / "fastmcp.json"
+    config_file.write_text(json.dumps(config_data))
+
+    # Create server file
+    server_file = tmp_path / "server.py"
+    server_file.write_text("# Server")
+
+    config = load_mcp_server_config(config_file)
+
+    # Check that UV command is built with resolved paths
+    uv_cmd = config.environment.build_command(["fastmcp", "run", "server.py"])
+
+    assert "--with-requirements" in uv_cmd
+    assert "--project" in uv_cmd
+    # Path should be resolved relative to config file
+    req_idx = uv_cmd.index("--with-requirements") + 1
+    assert Path(uv_cmd[req_idx]).is_absolute() or uv_cmd[req_idx] == "requirements.txt"
diff --git a/tests/cli/test_server_args.py b/tests/cli/test_server_args.py
new file mode 100644
index 0000000..32832e7
--- /dev/null
+++ b/tests/cli/test_server_args.py
@@ -0,0 +1,135 @@
+"""Test server argument passing functionality."""
+
+from pathlib import Path
+
+import pytest
+
+from fastmcp.utilities.mcp_server_config import MCPServerConfig
+from fastmcp.utilities.mcp_server_config.v1.sources.filesystem import FileSystemSource
+
+
+class TestServerArguments:
+    """Test passing arguments to servers."""
+
+    async def test_server_with_argparse(self, tmp_path):
+        """Test a server that uses argparse with command line arguments."""
+        server_file = tmp_path / "argparse_server.py"
+        server_file.write_text("""
+import argparse
+from fastmcp import FastMCP
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--name", default="DefaultServer")
+parser.add_argument("--port", type=int, default=8000)
+parser.add_argument("--debug", action="store_true")
+
+args = parser.parse_args()
+
+server_name = f"{args.name}:{args.port}"
+if args.debug:
+    server_name += " (Debug)"
+
+mcp = FastMCP(server_name)
+
+@mcp.tool
+def get_config() -> dict:
+    return {"name": args.name, "port": args.port, "debug": args.debug}
+""")
+
+        # Test with arguments
+        source = FileSystemSource(path=str(server_file))
+        config = MCPServerConfig(source=source)
+
+        from fastmcp.cli.cli import with_argv
+
+        # Simulate passing arguments
+        with with_argv(["--name", "TestServer", "--port", "9000", "--debug"]):
+            server = await config.source.load_server()
+
+        assert server.name == "TestServer:9000 (Debug)"
+
+        # Test the tool works and can access the parsed args
+        tools = await server.list_tools()
+        assert any(t.name == "get_config" for t in tools)
+
+    async def test_server_with_no_args(self, tmp_path):
+        """Test a server that uses argparse with no arguments (defaults)."""
+        server_file = tmp_path / "default_server.py"
+        server_file.write_text("""
+import argparse
+from fastmcp import FastMCP
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--name", default="DefaultName")
+args = parser.parse_args()
+
+mcp = FastMCP(args.name)
+""")
+
+        source = FileSystemSource(path=str(server_file))
+        config = MCPServerConfig(source=source)
+
+        from fastmcp.cli.cli import with_argv
+
+        # Test with empty args list (should use defaults)
+        with with_argv([]):
+            server = await config.source.load_server()
+
+        assert server.name == "DefaultName"
+
+    async def test_server_with_sys_argv_access(self, tmp_path):
+        """Test a server that directly accesses sys.argv."""
+        server_file = tmp_path / "sysargv_server.py"
+        server_file.write_text("""
+import sys
+from fastmcp import FastMCP
+
+# Direct sys.argv access (less common but should work)
+name = "DirectServer"
+if len(sys.argv) > 1 and sys.argv[1] == "--custom":
+    name = "CustomServer"
+
+mcp = FastMCP(name)
+""")
+
+        source = FileSystemSource(path=str(server_file))
+        config = MCPServerConfig(source=source)
+
+        from fastmcp.cli.cli import with_argv
+
+        # Test with custom argument
+        with with_argv(["--custom"]):
+            server = await config.source.load_server()
+
+        assert server.name == "CustomServer"
+
+        # Test without argument
+        with with_argv([]):
+            server = await config.source.load_server()
+
+        assert server.name == "DirectServer"
+
+    async def test_config_server_example(self):
+        """Test the actual config_server.py example."""
+        # Find the examples directory
+        examples_dir = Path(__file__).parent.parent.parent / "examples"
+        config_server = examples_dir / "config_server.py"
+
+        if not config_server.exists():
+            pytest.skip("config_server.py example not found")
+
+        source = FileSystemSource(path=str(config_server))
+        config = MCPServerConfig(source=source)
+
+        from fastmcp.cli.cli import with_argv
+
+        # Test with debug flag
+        with with_argv(["--name", "TestExample", "--debug"]):
+            server = await config.source.load_server()
+
+        assert server.name == "TestExample (Debug)"
+
+        # Verify tools are available
+        tools = await server.list_tools()
+        assert any(t.name == "get_status" for t in tools)
+        assert any(t.name == "echo_message" for t in tools)
diff --git a/tests/cli/test_shared.py b/tests/cli/test_shared.py
new file mode 100644
index 0000000..17ab19c
--- /dev/null
+++ b/tests/cli/test_shared.py
@@ -0,0 +1,39 @@
+import pytest
+
+from fastmcp.cli.cli import _parse_env_var
+from fastmcp.cli.install.shared import parse_env_var
+
+
+class TestEnvVarParsing:
+    """Test environment variable parsing functionality."""
+
+    def test_parse_env_var_simple(self):
+        """Test parsing simple environment variable."""
+        key, value = _parse_env_var("API_KEY=secret123")
+        assert key == "API_KEY"
+        assert value == "secret123"
+
+    def test_parse_env_var_with_equals_in_value(self):
+        """Test parsing env var with equals signs in the value."""
+        key, value = _parse_env_var("DATABASE_URL=postgresql://user:pass@host:5432/db")
+        assert key == "DATABASE_URL"
+        assert value == "postgresql://user:pass@host:5432/db"
+
+    def test_parse_env_var_with_spaces(self):
+        """Test parsing env var with spaces (should be stripped)."""
+        key, value = _parse_env_var("  API_KEY  =  secret with spaces  ")
+        assert key == "API_KEY"
+        assert value == "secret with spaces"
+
+    def test_parse_env_var_empty_value(self):
+        """Test parsing env var with empty value."""
+        key, value = _parse_env_var("EMPTY_VAR=")
+        assert key == "EMPTY_VAR"
+        assert value == ""
+
+    @pytest.mark.parametrize("parser", [_parse_env_var, parse_env_var])
+    def test_parse_env_var_empty_key_exits(self, parser):
+        """Environment variable names cannot be empty."""
+        with pytest.raises(SystemExit) as exc_info:
+            parser("  =value")
+        assert exc_info.value.code == 1
diff --git a/tests/cli/test_tasks.py b/tests/cli/test_tasks.py
new file mode 100644
index 0000000..8da5f80
--- /dev/null
+++ b/tests/cli/test_tasks.py
@@ -0,0 +1,51 @@
+"""Tests for the fastmcp tasks CLI."""
+
+import pytest
+
+from fastmcp.cli.tasks import check_distributed_backend, tasks_app
+from fastmcp.utilities.tests import temporary_settings
+
+
+class TestCheckDistributedBackend:
+    """Test the distributed backend checker function."""
+
+    def test_succeeds_with_redis_url(self):
+        """Test that it succeeds with Redis URL."""
+        with temporary_settings(docket__url="redis://localhost:6379/0"):
+            check_distributed_backend()
+
+    def test_exits_with_helpful_error_for_memory_url(self):
+        """Test that it exits with helpful error for memory:// URLs."""
+        with temporary_settings(docket__url="memory://test-123"):
+            with pytest.raises(SystemExit) as exc_info:
+                check_distributed_backend()
+
+            assert isinstance(exc_info.value, SystemExit)
+            assert exc_info.value.code == 1
+
+
+class TestWorkerCommand:
+    """Test the worker command."""
+
+    def test_worker_command_parsing(self):
+        """Test that worker command parses arguments correctly."""
+        command, bound, _ = tasks_app.parse_args(["worker", "server.py"])
+        assert callable(command)
+        assert command.__name__ == "worker"  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+        assert bound.arguments["server_spec"] == "server.py"
+
+
+class TestTasksAppIntegration:
+    """Test the tasks app integration."""
+
+    def test_tasks_app_exists(self):
+        """Test that the tasks app is properly configured."""
+        assert "tasks" in tasks_app.name
+        assert "Docket" in tasks_app.help
+
+    def test_tasks_app_has_commands(self):
+        """Test that all expected commands are registered."""
+        # Just verify the app exists and has the right metadata
+        # Detailed command testing is done in individual test classes
+        assert "tasks" in tasks_app.name
+        assert tasks_app.help
diff --git a/tests/cli/test_with_argv.py b/tests/cli/test_with_argv.py
new file mode 100644
index 0000000..ee9d378
--- /dev/null
+++ b/tests/cli/test_with_argv.py
@@ -0,0 +1,91 @@
+"""Test the with_argv context manager."""
+
+import sys
+from unittest.mock import patch
+
+import pytest
+
+from fastmcp.cli.cli import with_argv
+
+
+class TestWithArgv:
+    """Test the with_argv context manager."""
+
+    def test_with_argv_replaces_args(self):
+        """Test that with_argv properly replaces sys.argv."""
+        original_argv = sys.argv[:]
+        test_args = ["--name", "TestServer", "--debug"]
+
+        with with_argv(test_args):
+            # Should preserve script name and add new args
+            assert sys.argv[0] == original_argv[0]
+            assert sys.argv[1:] == test_args
+
+        # Should restore original argv after context
+        assert sys.argv == original_argv
+
+    def test_with_argv_none_does_nothing(self):
+        """Test that with_argv(None) doesn't change sys.argv."""
+        original_argv = sys.argv[:]
+
+        with with_argv(None):
+            assert sys.argv == original_argv
+
+        assert sys.argv == original_argv
+
+    def test_with_argv_empty_list(self):
+        """Test that with_argv([]) clears arguments but keeps script name."""
+        original_argv = sys.argv[:]
+
+        with with_argv([]):
+            # Should have only the script name (no additional args)
+            assert sys.argv == [original_argv[0]]
+            assert len(sys.argv) == 1
+
+        assert sys.argv == original_argv
+
+    def test_with_argv_restores_on_exception(self):
+        """Test that sys.argv is restored even if an exception occurs."""
+        original_argv = sys.argv[:]
+        test_args = ["--error"]
+
+        with pytest.raises(ValueError):
+            with with_argv(test_args):
+                assert sys.argv == [original_argv[0]] + test_args
+                raise ValueError("Test error")
+
+        # Should still restore original argv
+        assert sys.argv == original_argv
+
+    def test_with_argv_nested(self):
+        """Test nested with_argv contexts."""
+        original_argv = sys.argv[:]
+        args1 = ["--level1"]
+        args2 = ["--level2", "--debug"]
+
+        with with_argv(args1):
+            assert sys.argv == [original_argv[0]] + args1
+
+            with with_argv(args2):
+                assert sys.argv == [original_argv[0]] + args2
+
+            # Should restore to level 1
+            assert sys.argv == [original_argv[0]] + args1
+
+        # Should restore to original
+        assert sys.argv == original_argv
+
+    @patch("sys.argv", ["test_script.py", "existing", "args"])
+    def test_with_argv_with_existing_args(self):
+        """Test with_argv when sys.argv already has arguments."""
+        original_argv = sys.argv[:]
+        assert original_argv == ["test_script.py", "existing", "args"]
+
+        test_args = ["--new", "args"]
+
+        with with_argv(test_args):
+            # Should replace existing args but keep script name
+            assert sys.argv == ["test_script.py", "--new", "args"]
+
+        # Should restore original
+        assert sys.argv == original_argv
diff --git a/tests/client/__init__.py b/tests/client/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/client/auth/__init__.py b/tests/client/auth/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/client/auth/test_oauth_cimd.py b/tests/client/auth/test_oauth_cimd.py
new file mode 100644
index 0000000..04818af
--- /dev/null
+++ b/tests/client/auth/test_oauth_cimd.py
@@ -0,0 +1,164 @@
+"""Tests for CIMD (Client ID Metadata Document) support in the OAuth client."""
+
+from __future__ import annotations
+
+import warnings
+
+import httpx
+import pytest
+
+from fastmcp.client.auth import OAuth
+from fastmcp.client.transports import StreamableHttpTransport
+from fastmcp.client.transports.sse import SSETransport
+
+VALID_CIMD_URL = "https://myapp.example.com/oauth/client.json"
+MCP_SERVER_URL = "https://mcp-server.example.com/mcp"
+
+
+class TestOAuthClientMetadataURL:
+    """Tests for the client_metadata_url parameter on OAuth."""
+
+    def test_stored_on_instance(self):
+        oauth = OAuth(client_metadata_url=VALID_CIMD_URL)
+        assert oauth._client_metadata_url == VALID_CIMD_URL
+
+    def test_none_by_default(self):
+        oauth = OAuth()
+        assert oauth._client_metadata_url is None
+
+    def test_passed_to_parent_on_bind(self):
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", UserWarning)
+            oauth = OAuth(client_metadata_url=VALID_CIMD_URL)
+            oauth._bind(MCP_SERVER_URL)
+        assert oauth.context.client_metadata_url == VALID_CIMD_URL
+
+    def test_none_metadata_url_on_parent(self):
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", UserWarning)
+            oauth = OAuth(mcp_url=MCP_SERVER_URL)
+        assert oauth.context.client_metadata_url is None
+
+    def test_unbound_when_no_mcp_url(self):
+        oauth = OAuth(client_metadata_url=VALID_CIMD_URL)
+        assert oauth._bound is False
+
+    def test_bound_when_mcp_url_provided(self):
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", UserWarning)
+            oauth = OAuth(
+                mcp_url=MCP_SERVER_URL,
+                client_metadata_url=VALID_CIMD_URL,
+            )
+        assert oauth._bound is True
+
+    def test_invalid_cimd_url_rejected(self):
+        """CIMD URLs must be HTTPS with a non-root path."""
+        with pytest.raises(ValueError, match="valid HTTPS URL"):
+            OAuth(
+                mcp_url=MCP_SERVER_URL,
+                client_metadata_url="http://insecure.com/client.json",
+            )
+
+    def test_root_path_cimd_url_rejected(self):
+        with pytest.raises(ValueError, match="valid HTTPS URL"):
+            OAuth(
+                mcp_url=MCP_SERVER_URL,
+                client_metadata_url="https://example.com/",
+            )
+
+
+class TestOAuthBind:
+    """Tests for the _bind() deferred initialization."""
+
+    def test_bind_sets_bound_true(self):
+        oauth = OAuth(client_metadata_url=VALID_CIMD_URL)
+        assert oauth._bound is False
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", UserWarning)
+            oauth._bind(MCP_SERVER_URL)
+        assert oauth._bound is True
+
+    def test_bind_idempotent(self):
+        """Second call to _bind is a no-op."""
+        oauth = OAuth(client_metadata_url=VALID_CIMD_URL)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", UserWarning)
+            oauth._bind(MCP_SERVER_URL)
+            oauth._bind("https://other-server.example.com/mcp")
+        # First binding wins
+        assert oauth.mcp_url == MCP_SERVER_URL
+
+    def test_bind_sets_mcp_url(self):
+        oauth = OAuth(client_metadata_url=VALID_CIMD_URL)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", UserWarning)
+            oauth._bind(MCP_SERVER_URL + "/")
+        # Trailing slash stripped
+        assert oauth.mcp_url == MCP_SERVER_URL
+
+    def test_bind_creates_token_storage(self):
+        oauth = OAuth(client_metadata_url=VALID_CIMD_URL)
+        assert not hasattr(oauth, "token_storage_adapter")
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", UserWarning)
+            oauth._bind(MCP_SERVER_URL)
+        assert hasattr(oauth, "token_storage_adapter")
+
+    async def test_unbound_raises_runtime_error(self):
+        """async_auth_flow should fail clearly when OAuth is not bound."""
+        oauth = OAuth(client_metadata_url=VALID_CIMD_URL)
+        request = httpx.Request("GET", MCP_SERVER_URL)
+        with pytest.raises(RuntimeError, match="no server URL"):
+            async for _ in oauth.async_auth_flow(request):
+                pass
+
+    def test_scopes_forwarded_as_list(self):
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", UserWarning)
+            oauth = OAuth(
+                client_metadata_url=VALID_CIMD_URL,
+                scopes=["read", "write"],
+            )
+            oauth._bind(MCP_SERVER_URL)
+        assert oauth.context.client_metadata.scope == "read write"
+
+    def test_scopes_forwarded_as_string(self):
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", UserWarning)
+            oauth = OAuth(
+                client_metadata_url=VALID_CIMD_URL,
+                scopes="read write",
+            )
+            oauth._bind(MCP_SERVER_URL)
+        assert oauth.context.client_metadata.scope == "read write"
+
+
+class TestOAuthBindFromTransport:
+    """Tests that transports call _bind() on OAuth instances."""
+
+    def test_http_transport_binds_oauth(self):
+        oauth = OAuth(client_metadata_url=VALID_CIMD_URL)
+        assert oauth._bound is False
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", UserWarning)
+            StreamableHttpTransport(MCP_SERVER_URL, auth=oauth)
+        assert oauth._bound is True
+        assert oauth.mcp_url == MCP_SERVER_URL
+
+    def test_sse_transport_binds_oauth(self):
+        oauth = OAuth(client_metadata_url=VALID_CIMD_URL)
+        assert oauth._bound is False
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", UserWarning)
+            SSETransport(MCP_SERVER_URL, auth=oauth)
+        assert oauth._bound is True
+        assert oauth.mcp_url == MCP_SERVER_URL
+
+    def test_http_transport_oauth_string_still_works(self):
+        """auth="oauth" should still create a new OAuth instance."""
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", UserWarning)
+            transport = StreamableHttpTransport(MCP_SERVER_URL, auth="oauth")
+        assert isinstance(transport.auth, OAuth)
+        assert transport.auth._bound is True
diff --git a/tests/client/auth/test_oauth_client.py b/tests/client/auth/test_oauth_client.py
new file mode 100644
index 0000000..e069270
--- /dev/null
+++ b/tests/client/auth/test_oauth_client.py
@@ -0,0 +1,561 @@
+import socket
+import time
+from unittest.mock import patch
+from urllib.parse import urlparse
+
+import httpx
+import pytest
+from mcp import MCPError
+from mcp_types import TextResourceContents
+
+import fastmcp.client.auth.oauth as oauth_module
+import fastmcp.utilities.http as http_module
+from fastmcp.client import Client
+from fastmcp.client.auth import OAuth
+from fastmcp.client.transports import StreamableHttpTransport
+from fastmcp.server.auth.auth import ClientRegistrationOptions
+from fastmcp.server.auth.providers.in_memory import InMemoryOAuthProvider
+from fastmcp.server.server import FastMCP
+from fastmcp.utilities.http import find_available_port
+from fastmcp.utilities.tests import HeadlessOAuth, run_server_async
+
+
+def fastmcp_server(issuer_url: str):
+    """Create a FastMCP server with OAuth authentication."""
+    server = FastMCP(
+        "TestServer",
+        auth=InMemoryOAuthProvider(
+            base_url=issuer_url,
+            client_registration_options=ClientRegistrationOptions(
+                enabled=True, valid_scopes=["read", "write"]
+            ),
+        ),
+    )
+
+    @server.tool
+    def add(a: int, b: int) -> int:
+        """Add two numbers together."""
+        return a + b
+
+    @server.resource("resource://test")
+    def get_test_resource() -> str:
+        """Get a test resource."""
+        return "Hello from authenticated resource!"
+
+    return server
+
+
+@pytest.fixture
+async def streamable_http_server():
+    """Start OAuth-enabled server."""
+    port = find_available_port()
+    server = fastmcp_server(f"http://127.0.0.1:{port}")
+    async with run_server_async(server, port=port, transport="http") as url:
+        yield url
+
+
+@pytest.fixture
+def client_unauthorized(streamable_http_server: str) -> Client:
+    return Client(transport=StreamableHttpTransport(streamable_http_server))
+
+
+@pytest.fixture
+def client_with_headless_oauth(streamable_http_server: str) -> Client:
+    """Client with headless OAuth that bypasses browser interaction."""
+    return Client(
+        transport=StreamableHttpTransport(streamable_http_server),
+        auth=HeadlessOAuth(mcp_url=streamable_http_server, scopes=["read", "write"]),
+    )
+
+
+async def test_unauthorized(client_unauthorized: Client):
+    """Test that unauthenticated requests are rejected.
+
+    SDK v2 surfaces the server's 401 as an MCPError ("Server returned an error
+    response") rather than re-raising the raw httpx.HTTPStatusError.
+    """
+    with pytest.raises(MCPError, match="error response"):
+        async with client_unauthorized:
+            pass
+
+
+async def test_ping(client_with_headless_oauth: Client):
+    """Test that we can ping the server."""
+    async with client_with_headless_oauth:
+        assert await client_with_headless_oauth.ping()
+
+
+async def test_list_tools(client_with_headless_oauth: Client):
+    """Test that we can list tools."""
+    async with client_with_headless_oauth:
+        tools = await client_with_headless_oauth.list_tools()
+        tool_names = [tool.name for tool in tools]
+        assert "add" in tool_names
+
+
+async def test_call_tool(client_with_headless_oauth: Client):
+    """Test that we can call a tool."""
+    async with client_with_headless_oauth:
+        result = await client_with_headless_oauth.call_tool("add", {"a": 5, "b": 3})
+        # The add tool returns int which gets wrapped as structured output
+        # Client unwraps it and puts the actual int in the data field
+        assert result.data == 8
+
+
+async def test_list_resources(client_with_headless_oauth: Client):
+    """Test that we can list resources."""
+    async with client_with_headless_oauth:
+        resources = await client_with_headless_oauth.list_resources()
+        resource_uris = [str(resource.uri) for resource in resources]
+        assert "resource://test" in resource_uris
+
+
+async def test_read_resource(client_with_headless_oauth: Client):
+    """Test that we can read a resource."""
+    async with client_with_headless_oauth:
+        resource = await client_with_headless_oauth.read_resource("resource://test")
+        assert isinstance(resource[0], TextResourceContents)
+        assert resource[0].text == "Hello from authenticated resource!"
+
+
+async def test_oauth_server_metadata_discovery(streamable_http_server: str):
+    """Test that we can discover OAuth metadata from the running server."""
+    parsed_url = urlparse(streamable_http_server)
+    server_base_url = f"{parsed_url.scheme}://{parsed_url.netloc}"
+
+    async with httpx.AsyncClient() as client:
+        # Test OAuth discovery endpoint
+        metadata_url = f"{server_base_url}/.well-known/oauth-authorization-server"
+        response = await client.get(metadata_url)
+        assert response.status_code == 200
+
+        metadata = response.json()
+        assert "authorization_endpoint" in metadata
+        assert "token_endpoint" in metadata
+        assert "registration_endpoint" in metadata
+
+        # The endpoints should be properly formed URLs
+        assert metadata["authorization_endpoint"].startswith(server_base_url)
+        assert metadata["token_endpoint"].startswith(server_base_url)
+
+
+class TestOAuthClientUrlHandling:
+    """Tests for OAuth client URL handling (issue #2573)."""
+
+    def test_oauth_preserves_full_url_with_path(self):
+        """OAuth client should preserve the full MCP URL including path components.
+
+        This is critical for servers hosted under path-based endpoints like
+        mcp.example.com/server1/v1.0/mcp where OAuth metadata discovery needs
+        the full path to find the correct .well-known endpoints.
+        """
+        mcp_url = "https://mcp.example.com/server1/v1.0/mcp"
+        oauth = OAuth(mcp_url=mcp_url)
+
+        # The full URL should be preserved for OAuth discovery
+        assert oauth.context.server_url == mcp_url
+
+        # The stored mcp_url should match
+        assert oauth.mcp_url == mcp_url
+
+    def test_oauth_preserves_root_url(self):
+        """OAuth client should work correctly with root-level URLs."""
+        mcp_url = "https://mcp.example.com"
+        oauth = OAuth(mcp_url=mcp_url)
+
+        assert oauth.context.server_url == mcp_url
+        assert oauth.mcp_url == mcp_url
+
+    def test_oauth_normalizes_trailing_slash(self):
+        """OAuth client should normalize trailing slashes for consistency."""
+        mcp_url_with_slash = "https://mcp.example.com/api/mcp/"
+        oauth = OAuth(mcp_url=mcp_url_with_slash)
+
+        # Trailing slash should be stripped
+        expected = "https://mcp.example.com/api/mcp"
+        assert oauth.context.server_url == expected
+        assert oauth.mcp_url == expected
+
+    def test_oauth_token_storage_uses_full_url(self):
+        """Token storage should use the full URL to separate tokens per endpoint."""
+        mcp_url = "https://mcp.example.com/server1/v1.0/mcp"
+        oauth = OAuth(mcp_url=mcp_url)
+
+        # Token storage should key by the full URL, not just the host
+        assert oauth.token_storage_adapter._server_url == mcp_url
+
+    def test_oauth_uses_configured_callback_host_port_and_timeout(self):
+        oauth = OAuth(
+            mcp_url="https://example.com/mcp",
+            callback_port=8765,
+            callback_host="127.0.0.1",
+            callback_timeout=12.5,
+        )
+
+        assert oauth.context.client_metadata.redirect_uris is not None
+        assert str(oauth.context.client_metadata.redirect_uris[0]) == (
+            "http://127.0.0.1:8765/callback"
+        )
+        assert oauth._callback_timeout == 12.5
+
+    @pytest.mark.parametrize("callback_host", ["::1", "[::1]"])
+    def test_oauth_brackets_ipv6_callback_host_in_redirect_uri(
+        self, callback_host: str
+    ):
+        oauth = OAuth(
+            mcp_url="https://example.com/mcp",
+            callback_port=8765,
+            callback_host=callback_host,
+        )
+
+        assert oauth.context.client_metadata.redirect_uris is not None
+        assert str(oauth.context.client_metadata.redirect_uris[0]) == (
+            "http://[::1]:8765/callback"
+        )
+        assert oauth._callback_host == "::1"
+
+    def test_oauth_finds_available_port_on_callback_host(
+        self, monkeypatch: pytest.MonkeyPatch
+    ):
+        seen_hosts: list[str] = []
+
+        def find_available_port(host: str = "127.0.0.1") -> int:
+            seen_hosts.append(host)
+            return 8765
+
+        monkeypatch.setattr(oauth_module, "find_available_port", find_available_port)
+
+        oauth = OAuth(
+            mcp_url="https://example.com/mcp",
+            callback_host="[::1]",
+        )
+
+        assert seen_hosts == ["::1"]
+        assert oauth.redirect_port == 8765
+        assert oauth.context.client_metadata.redirect_uris is not None
+        assert str(oauth.context.client_metadata.redirect_uris[0]) == (
+            "http://[::1]:8765/callback"
+        )
+
+    @pytest.mark.parametrize(
+        ("host", "expected_family"),
+        [
+            ("localhost", socket.AF_INET),
+            ("127.0.0.1", socket.AF_INET),
+            ("::1", socket.AF_INET6),
+        ],
+    )
+    def test_available_port_uses_uvicorn_host_family(
+        self,
+        host: str,
+        expected_family: socket.AddressFamily,
+        monkeypatch: pytest.MonkeyPatch,
+    ):
+        seen: list[tuple[socket.AddressFamily, tuple[str, int]]] = []
+
+        class FakeSocket:
+            def __init__(
+                self,
+                family: socket.AddressFamily,
+                socket_type: socket.SocketKind,
+            ):
+                self.family = family
+
+            def __enter__(self):
+                return self
+
+            def __exit__(self, *args: object) -> None:
+                return None
+
+            def bind(self, address: tuple[str, int]) -> None:
+                seen.append((self.family, address))
+
+            def getsockname(self) -> tuple[str, int]:
+                return host, 8765
+
+        monkeypatch.setattr(http_module.socket, "socket", FakeSocket)
+
+        assert http_module.find_available_port(host=host) == 8765
+        assert seen == [(expected_family, (host, 0))]
+
+
+class TestOAuthGeneratorCleanup:
+    """Tests for OAuth async generator cleanup (issue #2643).
+
+    The MCP SDK's OAuthClientProvider.async_auth_flow() holds a lock via
+    `async with self.context.lock`. If the generator is not explicitly closed,
+    GC may clean it up from a different task, causing:
+    RuntimeError: The current task is not holding this lock
+    """
+
+    async def test_generator_closed_on_successful_flow(self):
+        """Verify aclose() is called on the parent generator after successful flow."""
+        oauth = OAuth(mcp_url="https://example.com")
+
+        # Track generator lifecycle using a wrapper class
+        class TrackedGenerator:
+            def __init__(self):
+                self.aclose_called = False
+                self._exhausted = False
+
+            def __aiter__(self):
+                return self
+
+            async def __anext__(self):
+                if self._exhausted:
+                    raise StopAsyncIteration
+                self._exhausted = True
+                return httpx.Request("GET", "https://example.com")
+
+            async def asend(self, value):
+                if self._exhausted:
+                    raise StopAsyncIteration
+                self._exhausted = True
+                return httpx.Request("GET", "https://example.com")
+
+            async def athrow(self, exc_type, exc_val=None, exc_tb=None):
+                raise StopAsyncIteration
+
+            async def aclose(self):
+                self.aclose_called = True
+
+        tracked_gen = TrackedGenerator()
+
+        # Patch the parent class to return our tracked generator
+        with patch.object(
+            OAuth.__bases__[0], "async_auth_flow", return_value=tracked_gen
+        ):
+            # Drive the OAuth flow
+            flow = oauth.async_auth_flow(httpx.Request("GET", "https://example.com"))
+            try:
+                # First asend(None) starts the generator per async generator protocol
+                await flow.asend(None)  # ty: ignore[invalid-argument-type]
+                try:
+                    await flow.asend(httpx.Response(200))
+                except StopAsyncIteration:
+                    pass
+            except StopAsyncIteration:
+                pass
+
+        assert tracked_gen.aclose_called, (
+            "Generator aclose() was not called after flow completion"
+        )
+
+    async def test_generator_closed_on_exception(self):
+        """Verify aclose() is called even when an exception occurs mid-flow."""
+        oauth = OAuth(mcp_url="https://example.com")
+
+        class FailingGenerator:
+            def __init__(self):
+                self.aclose_called = False
+                self._first_call = True
+
+            def __aiter__(self):
+                return self
+
+            async def __anext__(self):
+                return await self.asend(None)
+
+            async def asend(self, value):
+                if self._first_call:
+                    self._first_call = False
+                    return httpx.Request("GET", "https://example.com")
+                raise ValueError("Simulated failure")
+
+            async def athrow(self, exc_type, exc_val=None, exc_tb=None):
+                raise StopAsyncIteration
+
+            async def aclose(self):
+                self.aclose_called = True
+
+        tracked_gen = FailingGenerator()
+
+        with patch.object(
+            OAuth.__bases__[0], "async_auth_flow", return_value=tracked_gen
+        ):
+            flow = oauth.async_auth_flow(httpx.Request("GET", "https://example.com"))
+            with pytest.raises(ValueError, match="Simulated failure"):
+                await flow.asend(None)  # ty: ignore[invalid-argument-type]
+                await flow.asend(httpx.Response(200))
+
+        assert tracked_gen.aclose_called, (
+            "Generator aclose() was not called after exception"
+        )
+
+
+class TestTokenStorageTTL:
+    """Tests for client token storage TTL behavior (issue #2670).
+
+    The token storage TTL should NOT be based on access token expiry, because
+    the refresh token may be valid much longer. Using access token expiry would
+    cause both tokens to be deleted when the access token expires, preventing
+    refresh.
+    """
+
+    async def test_token_storage_uses_long_ttl(self):
+        """Token storage should use a long TTL, not access token expiry.
+
+        This is the ianw case: IdP returns expires_in=300 (5 min access token)
+        but the refresh token is valid for much longer. The entire token entry
+        should NOT be deleted after 5 minutes.
+        """
+        from key_value.aio.stores.memory import MemoryStore
+        from mcp.shared.auth import OAuthToken
+
+        from fastmcp.client.auth.oauth import TokenStorageAdapter
+
+        # Create storage adapter
+        storage = MemoryStore()
+        adapter = TokenStorageAdapter(
+            async_key_value=storage, server_url="https://test"
+        )
+
+        # Create a token with short access expiry (5 minutes)
+        token = OAuthToken(
+            access_token="test-access-token",
+            token_type="Bearer",
+            expires_in=300,  # 5 minutes - but we should NOT use this as storage TTL!
+            refresh_token="test-refresh-token",
+            scope="read write",
+        )
+
+        # Store the token
+        await adapter.set_tokens(token)
+
+        # Verify token is stored
+        stored = await adapter.get_tokens()
+        assert stored is not None
+        assert stored.access_token == "test-access-token"
+        assert stored.refresh_token == "test-refresh-token"
+
+        # The key assertion: the TTL should be 1 year (365 days), not 300 seconds
+        # We verify this by checking the raw storage entry
+        raw = await storage.get(collection="mcp-oauth-token", key="https://test/tokens")
+        assert raw is not None
+
+    async def test_token_storage_preserves_refresh_token(self):
+        """Refresh token should not be lost when access token would expire."""
+        from key_value.aio.stores.memory import MemoryStore
+        from mcp.shared.auth import OAuthToken
+
+        from fastmcp.client.auth.oauth import TokenStorageAdapter
+
+        storage = MemoryStore()
+        adapter = TokenStorageAdapter(
+            async_key_value=storage, server_url="https://test"
+        )
+
+        # Store token with short access expiry
+        token = OAuthToken(
+            access_token="access",
+            token_type="Bearer",
+            expires_in=300,
+            refresh_token="refresh-token-should-survive",
+            scope="read",
+        )
+        await adapter.set_tokens(token)
+
+        # Retrieve and verify refresh token is present
+        stored = await adapter.get_tokens()
+        assert stored is not None
+        assert stored.refresh_token == "refresh-token-should-survive"
+
+    async def test_set_tokens_stores_absolute_expiry(self):
+        """set_tokens should persist an absolute expires_at timestamp."""
+        from key_value.aio.stores.memory import MemoryStore
+        from mcp.shared.auth import OAuthToken
+
+        from fastmcp.client.auth.oauth import TokenStorageAdapter
+
+        storage = MemoryStore()
+        adapter = TokenStorageAdapter(
+            async_key_value=storage, server_url="https://test"
+        )
+
+        before = time.time()
+        token = OAuthToken(
+            access_token="a",
+            token_type="Bearer",
+            expires_in=300,
+            refresh_token="r",
+        )
+        await adapter.set_tokens(token)
+        after = time.time()
+
+        expiry = await adapter.get_token_expiry()
+        assert expiry is not None
+        assert before + 300 <= expiry <= after + 300
+
+    async def test_reload_uses_stored_expiry_not_stale_expires_in(self):
+        """On reload, _initialize should use the stored absolute expiry rather
+        than recomputing from the stale relative expires_in.
+
+        This is the core bug from #2862: a token issued with expires_in=300
+        that's reloaded an hour later should NOT appear valid for another 5
+        minutes.
+        """
+        from key_value.aio.stores.memory import MemoryStore
+        from mcp.shared.auth import OAuthToken
+
+        from fastmcp.client.auth.oauth import TokenStorageAdapter
+
+        storage = MemoryStore()
+        adapter = TokenStorageAdapter(
+            async_key_value=storage, server_url="https://test"
+        )
+
+        token = OAuthToken(
+            access_token="a",
+            token_type="Bearer",
+            expires_in=300,
+            refresh_token="r",
+        )
+        await adapter.set_tokens(token)
+
+        # Simulate time passing by overwriting the stored expiry to a past time
+        past_expiry = time.time() - 600
+        await storage.put(
+            key="https://test/token_expiry",
+            value={"expires_at": past_expiry},
+            collection="mcp-oauth-token-expiry",
+        )
+
+        reloaded = await adapter.get_token_expiry()
+        assert reloaded is not None
+        assert reloaded == pytest.approx(past_expiry)
+
+    async def test_get_token_expiry_returns_none_when_not_stored(self):
+        """get_token_expiry returns None for tokens stored before the fix."""
+        from key_value.aio.stores.memory import MemoryStore
+
+        from fastmcp.client.auth.oauth import TokenStorageAdapter
+
+        storage = MemoryStore()
+        adapter = TokenStorageAdapter(
+            async_key_value=storage, server_url="https://test"
+        )
+        assert await adapter.get_token_expiry() is None
+
+    async def test_clear_removes_token_expiry(self):
+        """clear() should also remove the stored token expiry."""
+        from key_value.aio.stores.memory import MemoryStore
+        from mcp.shared.auth import OAuthToken
+
+        from fastmcp.client.auth.oauth import TokenStorageAdapter
+
+        storage = MemoryStore()
+        adapter = TokenStorageAdapter(
+            async_key_value=storage, server_url="https://test"
+        )
+
+        token = OAuthToken(
+            access_token="a",
+            token_type="Bearer",
+            expires_in=300,
+            refresh_token="r",
+        )
+        await adapter.set_tokens(token)
+        assert await adapter.get_token_expiry() is not None
+
+        await adapter.clear()
+        assert await adapter.get_token_expiry() is None
diff --git a/tests/client/auth/test_oauth_static_client.py b/tests/client/auth/test_oauth_static_client.py
new file mode 100644
index 0000000..c9f17cd
--- /dev/null
+++ b/tests/client/auth/test_oauth_static_client.py
@@ -0,0 +1,274 @@
+"""Tests for OAuth static client registration (pre-registered client_id/client_secret)."""
+
+from unittest.mock import patch
+
+import httpx
+import pytest
+from mcp.shared.auth import OAuthClientInformationFull
+from pydantic import AnyUrl
+
+from fastmcp.client import Client
+from fastmcp.client.auth import OAuth
+from fastmcp.client.auth.oauth import ClientNotFoundError
+from fastmcp.client.transports import StreamableHttpTransport
+from fastmcp.server.auth.auth import ClientRegistrationOptions
+from fastmcp.server.auth.providers.in_memory import InMemoryOAuthProvider
+from fastmcp.server.server import FastMCP
+from fastmcp.utilities.http import find_available_port
+from fastmcp.utilities.tests import HeadlessOAuth, run_server_async
+
+
+class TestStaticClientInfoConstruction:
+    """Static client info should include full metadata from client_metadata."""
+
+    def test_static_client_info_includes_metadata(self):
+        """Static client info should include redirect_uris, grant_types, etc."""
+        oauth = OAuth(
+            mcp_url="https://example.com/mcp",
+            client_id="my-client-id",
+            client_secret="my-secret",
+            scopes=["read", "write"],
+        )
+
+        info = oauth._static_client_info
+        assert info is not None
+        assert info.client_id == "my-client-id"
+        assert info.client_secret == "my-secret"
+        # Metadata fields should be populated from client_metadata
+        assert info.redirect_uris is not None
+        assert len(info.redirect_uris) == 1
+        assert info.grant_types is not None
+        assert "authorization_code" in info.grant_types
+        assert "refresh_token" in info.grant_types
+        assert info.response_types is not None
+        assert "code" in info.response_types
+        assert info.scope == "read write"
+        assert info.token_endpoint_auth_method == "client_secret_post"
+
+    def test_static_client_info_without_secret(self):
+        """Public clients can provide client_id without client_secret."""
+        oauth = OAuth(
+            mcp_url="https://example.com/mcp",
+            client_id="public-client",
+        )
+
+        info = oauth._static_client_info
+        assert info is not None
+        assert info.client_id == "public-client"
+        assert info.client_secret is None
+        assert info.token_endpoint_auth_method == "none"
+        # Metadata should still be present
+        assert info.redirect_uris is not None
+        assert info.grant_types is not None
+
+    def test_no_static_client_info_without_client_id(self):
+        """When no client_id is provided, _static_client_info should be None."""
+        oauth = OAuth(mcp_url="https://example.com/mcp")
+        assert oauth._static_client_info is None
+
+    def test_static_client_info_includes_additional_metadata(self):
+        """Additional client metadata should be included in static client info."""
+        oauth = OAuth(
+            mcp_url="https://example.com/mcp",
+            client_id="my-client",
+            additional_client_metadata={
+                "token_endpoint_auth_method": "client_secret_post"
+            },
+        )
+
+        info = oauth._static_client_info
+        assert info is not None
+        assert info.token_endpoint_auth_method == "client_secret_post"
+
+
+class TestStaticClientInitialize:
+    """_initialize should set context.client_info and persist to storage."""
+
+    async def test_initialize_sets_context_client_info(self):
+        """_initialize should inject static client info into the auth context."""
+        oauth = OAuth(
+            mcp_url="https://example.com/mcp",
+            client_id="my-client",
+            client_secret="my-secret",
+        )
+
+        # Mock the parent _initialize since it needs a real server
+        with patch.object(OAuth.__bases__[0], "_initialize", return_value=None):
+            await oauth._initialize()
+
+        assert oauth.context.client_info is not None
+        assert oauth.context.client_info.client_id == "my-client"
+        assert oauth.context.client_info.client_secret == "my-secret"
+
+    async def test_initialize_persists_static_client_to_storage(self):
+        """Static client info should be persisted to token storage."""
+        oauth = OAuth(
+            mcp_url="https://example.com/mcp",
+            client_id="my-client",
+            client_secret="my-secret",
+        )
+
+        with patch.object(OAuth.__bases__[0], "_initialize", return_value=None):
+            await oauth._initialize()
+
+        # Verify it was persisted to storage
+        stored = await oauth.token_storage_adapter.get_client_info()
+        assert stored is not None
+        assert stored.client_id == "my-client"
+
+    async def test_initialize_without_static_creds_works(self):
+        """_initialize should not error when no static credentials are provided."""
+        oauth = OAuth(mcp_url="https://example.com/mcp")
+
+        with patch.object(OAuth.__bases__[0], "_initialize", return_value=None):
+            # This should not raise AttributeError
+            await oauth._initialize()
+
+        # context.client_info should be whatever the parent set (None by default)
+
+
+class TestStaticClientRetryBehavior:
+    """Retry-on-stale-credentials should short-circuit for static creds."""
+
+    async def test_retry_skipped_with_static_creds(self):
+        """When static creds are rejected, should raise immediately, not retry."""
+        oauth = OAuth(
+            mcp_url="https://example.com/mcp",
+            client_id="bad-client-id",
+            client_secret="bad-secret",
+        )
+
+        # Make the parent auth flow raise ClientNotFoundError
+        async def failing_auth_flow(request):
+            raise ClientNotFoundError("client not found")
+            yield  # make it a generator  # noqa: E275
+
+        with patch.object(
+            OAuth.__bases__[0], "async_auth_flow", side_effect=failing_auth_flow
+        ):
+            flow = oauth.async_auth_flow(httpx.Request("GET", "https://example.com"))
+            with pytest.raises(ClientNotFoundError, match="static client credentials"):
+                await flow.__anext__()
+
+    async def test_retry_still_works_without_static_creds(self):
+        """Without static creds, the retry behavior should be preserved."""
+        oauth = OAuth(mcp_url="https://example.com/mcp")
+
+        call_count = 0
+
+        async def auth_flow_with_retry(request):
+            nonlocal call_count
+            call_count += 1
+            if call_count == 1:
+                raise ClientNotFoundError("client not found")
+            # Second attempt succeeds
+            yield httpx.Request("GET", "https://example.com")
+
+        with patch.object(
+            OAuth.__bases__[0], "async_auth_flow", side_effect=auth_flow_with_retry
+        ):
+            flow = oauth.async_auth_flow(httpx.Request("GET", "https://example.com"))
+            request = await flow.__anext__()
+            assert request is not None
+            assert call_count == 2
+
+
+class TestStaticClientE2E:
+    """End-to-end tests with a real OAuth server using pre-registered clients."""
+
+    async def test_static_client_with_dcr_disabled(self):
+        """Static client_id should work when the server has DCR disabled."""
+        port = find_available_port()
+        callback_port = find_available_port()
+        issuer_url = f"http://127.0.0.1:{port}"
+
+        provider = InMemoryOAuthProvider(
+            base_url=issuer_url,
+            client_registration_options=ClientRegistrationOptions(
+                enabled=False,  # DCR disabled
+                valid_scopes=["read", "write"],
+            ),
+        )
+
+        server = FastMCP("TestServer", auth=provider)
+
+        @server.tool
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        # Pre-register a client directly in the provider.
+        # The redirect_uri must match what the OAuth client will use.
+        pre_registered = OAuthClientInformationFull(
+            client_id="pre-registered-client",
+            client_secret="pre-registered-secret",
+            redirect_uris=[AnyUrl(f"http://localhost:{callback_port}/callback")],
+            grant_types=["authorization_code", "refresh_token"],
+            response_types=["code"],
+            token_endpoint_auth_method="client_secret_post",
+            scope="read write",
+        )
+        await provider.register_client(pre_registered)
+
+        async with run_server_async(server, port=port, transport="http") as url:
+            oauth = HeadlessOAuth(
+                mcp_url=url,
+                client_id="pre-registered-client",
+                client_secret="pre-registered-secret",
+                scopes=["read", "write"],
+                callback_port=callback_port,
+            )
+
+            async with Client(
+                transport=StreamableHttpTransport(url),
+                auth=oauth,
+            ) as client:
+                assert await client.ping()
+                tools = await client.list_tools()
+                assert any(t.name == "greet" for t in tools)
+
+    async def test_static_client_with_dcr_enabled(self):
+        """Static client_id should also work when DCR is enabled (skips DCR)."""
+        port = find_available_port()
+        callback_port = find_available_port()
+        issuer_url = f"http://127.0.0.1:{port}"
+
+        provider = InMemoryOAuthProvider(
+            base_url=issuer_url,
+            client_registration_options=ClientRegistrationOptions(
+                enabled=True,
+                valid_scopes=["read"],
+            ),
+        )
+
+        server = FastMCP("TestServer", auth=provider)
+
+        @server.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        pre_registered = OAuthClientInformationFull(
+            client_id="my-app",
+            client_secret="my-secret",
+            redirect_uris=[AnyUrl(f"http://localhost:{callback_port}/callback")],
+            grant_types=["authorization_code", "refresh_token"],
+            response_types=["code"],
+            token_endpoint_auth_method="client_secret_post",
+            scope="read",
+        )
+        await provider.register_client(pre_registered)
+
+        async with run_server_async(server, port=port, transport="http") as url:
+            oauth = HeadlessOAuth(
+                mcp_url=url,
+                client_id="my-app",
+                client_secret="my-secret",
+                scopes=["read"],
+                callback_port=callback_port,
+            )
+
+            async with Client(
+                transport=StreamableHttpTransport(url),
+                auth=oauth,
+            ) as client:
+                result = await client.call_tool("add", {"a": 3, "b": 4})
+                assert result.data == 7
diff --git a/tests/client/client/__init__.py b/tests/client/client/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/client/client/test_auth.py b/tests/client/client/test_auth.py
new file mode 100644
index 0000000..f6b9dc0
--- /dev/null
+++ b/tests/client/client/test_auth.py
@@ -0,0 +1,82 @@
+"""Client authentication tests."""
+
+import pytest
+from mcp.client.auth import OAuthClientProvider
+
+from fastmcp.client import Client
+from fastmcp.client.auth.bearer import BearerAuth
+from fastmcp.client.transports import (
+    SSETransport,
+    StdioTransport,
+    StreamableHttpTransport,
+)
+
+
+class TestAuth:
+    def test_default_auth_is_none(self):
+        client = Client(transport=StreamableHttpTransport("http://localhost:8000"))
+        assert client.transport.auth is None
+
+    def test_stdio_doesnt_support_auth(self):
+        with pytest.raises(ValueError, match="This transport does not support auth"):
+            Client(transport=StdioTransport("echo", ["hello"]), auth="oauth")
+
+    def test_oauth_literal_sets_up_oauth_shttp(self):
+        client = Client(
+            transport=StreamableHttpTransport("http://localhost:8000"), auth="oauth"
+        )
+        assert isinstance(client.transport, StreamableHttpTransport)
+        assert isinstance(client.transport.auth, OAuthClientProvider)
+
+    def test_oauth_literal_pass_direct_to_transport(self):
+        client = Client(
+            transport=StreamableHttpTransport("http://localhost:8000", auth="oauth"),
+        )
+        assert isinstance(client.transport, StreamableHttpTransport)
+        assert isinstance(client.transport.auth, OAuthClientProvider)
+
+    def test_oauth_literal_sets_up_oauth_sse(self):
+        client = Client(transport=SSETransport("http://localhost:8000"), auth="oauth")
+        assert isinstance(client.transport, SSETransport)
+        assert isinstance(client.transport.auth, OAuthClientProvider)
+
+    def test_oauth_literal_pass_direct_to_transport_sse(self):
+        client = Client(transport=SSETransport("http://localhost:8000", auth="oauth"))
+        assert isinstance(client.transport, SSETransport)
+        assert isinstance(client.transport.auth, OAuthClientProvider)
+
+    def test_auth_string_sets_up_bearer_auth_shttp(self):
+        client = Client(
+            transport=StreamableHttpTransport("http://localhost:8000"),
+            auth="test_token",
+        )
+        assert isinstance(client.transport, StreamableHttpTransport)
+        assert isinstance(client.transport.auth, BearerAuth)
+        assert client.transport.auth.token.get_secret_value() == "test_token"
+
+    def test_auth_string_pass_direct_to_transport_shttp(self):
+        client = Client(
+            transport=StreamableHttpTransport(
+                "http://localhost:8000", auth="test_token"
+            ),
+        )
+        assert isinstance(client.transport, StreamableHttpTransport)
+        assert isinstance(client.transport.auth, BearerAuth)
+        assert client.transport.auth.token.get_secret_value() == "test_token"
+
+    def test_auth_string_sets_up_bearer_auth_sse(self):
+        client = Client(
+            transport=SSETransport("http://localhost:8000"),
+            auth="test_token",
+        )
+        assert isinstance(client.transport, SSETransport)
+        assert isinstance(client.transport.auth, BearerAuth)
+        assert client.transport.auth.token.get_secret_value() == "test_token"
+
+    def test_auth_string_pass_direct_to_transport_sse(self):
+        client = Client(
+            transport=SSETransport("http://localhost:8000", auth="test_token"),
+        )
+        assert isinstance(client.transport, SSETransport)
+        assert isinstance(client.transport.auth, BearerAuth)
+        assert client.transport.auth.token.get_secret_value() == "test_token"
diff --git a/tests/client/client/test_client.py b/tests/client/client/test_client.py
new file mode 100644
index 0000000..86355ce
--- /dev/null
+++ b/tests/client/client/test_client.py
@@ -0,0 +1,910 @@
+"""Core client functionality: tools, resources, prompts."""
+
+import asyncio
+import contextlib
+from collections.abc import AsyncIterator
+from typing import Any, cast
+
+import anyio
+import pytest
+from mcp import ClientSession, MCPError
+from mcp_types import TextContent
+from pydantic import AnyUrl
+
+import fastmcp
+from fastmcp.client import Client
+from fastmcp.client.tasks import TaskNotificationHandler
+from fastmcp.client.transports import (
+    ClientTransport,
+    FastMCPTransport,
+)
+from fastmcp.server.server import FastMCP
+
+
+async def test_list_tools(fastmcp_server):
+    """Test listing tools with InMemoryClient."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    async with client:
+        result = await client.list_tools()
+
+        # Check that our tools are available
+        assert len(result) == 3
+        assert set(tool.name for tool in result) == {"greet", "add", "sleep"}
+
+
+async def test_list_tools_mcp(fastmcp_server):
+    """Test the list_tools_mcp method that returns raw MCP protocol objects."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    async with client:
+        result = await client.list_tools_mcp()
+
+        # Check that we got the raw MCP ListToolsResult object
+        assert hasattr(result, "tools")
+        assert len(result.tools) == 3
+        assert set(tool.name for tool in result.tools) == {"greet", "add", "sleep"}
+
+
+async def test_call_tool(fastmcp_server):
+    """Test calling a tool with InMemoryClient."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    async with client:
+        result = await client.call_tool("greet", {"name": "World"})
+
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "Hello, World!"
+        assert result.structured_content == {"result": "Hello, World!"}
+        assert result.data == "Hello, World!"
+        assert result.is_error is False
+
+
+async def test_call_tool_mcp(fastmcp_server):
+    """Test the call_tool_mcp method that returns raw MCP protocol objects."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    async with client:
+        result = await client.call_tool_mcp("greet", {"name": "World"})
+
+        # Check that we got the raw MCP CallToolResult object
+        assert hasattr(result, "content")
+        assert hasattr(result, "isError")
+        assert result.is_error is False
+        # The content is a list, so we'll check the first element
+        # by properly accessing it
+        content = result.content
+        assert len(content) > 0
+        first_content = content[0]
+        content_str = str(first_content)
+        assert "Hello, World!" in content_str
+
+
+async def test_call_tool_with_meta():
+    """Test that meta parameter is properly passed from client to server."""
+    server = FastMCP("MetaTestServer")
+
+    # Create a tool that accesses the meta from the request context
+    @server.tool
+    def check_meta() -> dict[str, Any]:
+        """A tool that returns the meta from the request context."""
+        from fastmcp.server.dependencies import get_context
+
+        context = get_context()
+        assert context.request_context is not None
+        meta = context.request_context.meta
+
+        # Return the metadata as a dict. Under SDK v2 the lifted request meta
+        # is a plain dict, so custom fields are read by key.
+        if meta is not None:
+            return {
+                "has_meta": True,
+                "user_id": meta.get("user_id"),
+                "trace_id": meta.get("trace_id"),
+            }
+        return {"has_meta": False}
+
+    client = Client(transport=FastMCPTransport(server))
+
+    async with client:
+        # Test with meta parameter - verify the server receives it
+        test_meta = {"user_id": "test-123", "trace_id": "abc-def"}
+        result = await client.call_tool("check_meta", {}, meta=test_meta)
+
+        assert result.data["has_meta"] is True
+        assert result.data["user_id"] == "test-123"
+        assert result.data["trace_id"] == "abc-def"
+
+        # Test without meta parameter - verify fields are not present
+        result_no_meta = await client.call_tool("check_meta", {})
+        # When meta is not provided, custom fields should not be present
+        assert result_no_meta.data.get("user_id") is None
+        assert result_no_meta.data.get("trace_id") is None
+
+
+async def test_list_resources(fastmcp_server):
+    """Test listing resources with InMemoryClient."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    async with client:
+        result = await client.list_resources()
+
+        # Check that our resource is available
+        assert len(result) == 1
+        assert str(result[0].uri) == "data://users"
+
+
+async def test_list_resources_mcp(fastmcp_server):
+    """Test the list_resources_mcp method that returns raw MCP protocol objects."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    async with client:
+        result = await client.list_resources_mcp()
+
+        # Check that we got the raw MCP ListResourcesResult object
+        assert hasattr(result, "resources")
+        assert len(result.resources) == 1
+        assert str(result.resources[0].uri) == "data://users"
+
+
+async def test_list_prompts(fastmcp_server):
+    """Test listing prompts with InMemoryClient."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    async with client:
+        result = await client.list_prompts()
+
+        # Check that our prompt is available
+        assert len(result) == 1
+        assert result[0].name == "welcome"
+
+
+async def test_list_prompts_mcp(fastmcp_server):
+    """Test the list_prompts_mcp method that returns raw MCP protocol objects."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    async with client:
+        result = await client.list_prompts_mcp()
+
+        # Check that we got the raw MCP ListPromptsResult object
+        assert hasattr(result, "prompts")
+        assert len(result.prompts) == 1
+        assert result.prompts[0].name == "welcome"
+
+
+async def test_get_prompt(fastmcp_server):
+    """Test getting a prompt with InMemoryClient."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    async with client:
+        result = await client.get_prompt("welcome", {"name": "Developer"})
+
+        # The result should contain our welcome message
+        assert isinstance(result.messages[0].content, TextContent)
+        assert result.messages[0].content.text == "Welcome to FastMCP, Developer!"
+        assert result.description == "Example greeting prompt."
+
+
+async def test_get_prompt_mcp(fastmcp_server):
+    """Test the get_prompt_mcp method that returns raw MCP protocol objects."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    async with client:
+        result = await client.get_prompt_mcp("welcome", {"name": "Developer"})
+
+        # The result should contain our welcome message
+        assert isinstance(result.messages[0].content, TextContent)
+        assert result.messages[0].content.text == "Welcome to FastMCP, Developer!"
+        assert result.description == "Example greeting prompt."
+
+
+async def test_client_serializes_all_non_string_arguments():
+    """Test that client always serializes non-string arguments to JSON, regardless of server types."""
+    server = FastMCP("TestServer")
+
+    @server.prompt
+    def echo_args(arg1: str, arg2: str, arg3: str) -> str:
+        """Server accepts all string args but client sends mixed types."""
+        return f"arg1: {arg1}, arg2: {arg2}, arg3: {arg3}"
+
+    client = Client(transport=FastMCPTransport(server))
+
+    async with client:
+        result = await client.get_prompt(
+            "echo_args",
+            {
+                "arg1": "hello",  # string - should pass through
+                "arg2": [1, 2, 3],  # list - should be JSON serialized
+                "arg3": {"key": "value"},  # dict - should be JSON serialized
+            },
+        )
+
+        assert isinstance(result.messages[0].content, TextContent)
+        content = result.messages[0].content.text
+        assert "arg1: hello" in content
+        assert "arg2: [1,2,3]" in content  # JSON serialized list
+        assert 'arg3: {"key":"value"}' in content  # JSON serialized dict
+
+
+async def test_client_server_type_conversion_integration():
+    """Test that client serialization works with server-side type conversion."""
+    server = FastMCP("TestServer")
+
+    @server.prompt
+    def typed_prompt(numbers: list[int], config: dict[str, str]) -> str:
+        """Server expects typed args - will convert from JSON strings."""
+        return f"Got {len(numbers)} numbers and {len(config)} config items"
+
+    client = Client(transport=FastMCPTransport(server))
+
+    async with client:
+        result = await client.get_prompt(
+            "typed_prompt",
+            {"numbers": [1, 2, 3, 4], "config": {"theme": "dark", "lang": "en"}},
+        )
+
+        assert isinstance(result.messages[0].content, TextContent)
+        content = result.messages[0].content.text
+        assert "Got 4 numbers and 2 config items" in content
+
+
+async def test_client_serialization_error():
+    """Test client error when object cannot be serialized."""
+    import pydantic_core
+
+    server = FastMCP("TestServer")
+
+    @server.prompt
+    def any_prompt(data: str) -> str:
+        return f"Got: {data}"
+
+    # Create an unserializable object
+    class UnserializableClass:
+        def __init__(self):
+            self.func = lambda x: x  # functions can't be JSON serialized
+
+    client = Client(transport=FastMCPTransport(server))
+
+    async with client:
+        with pytest.raises(
+            pydantic_core.PydanticSerializationError, match="Unable to serialize"
+        ):
+            await client.get_prompt("any_prompt", {"data": UnserializableClass()})
+
+
+async def test_server_deserialization_error():
+    """Test server error when JSON string cannot be converted to expected type."""
+
+    server = FastMCP("TestServer")
+
+    @server.prompt
+    def strict_typed_prompt(numbers: list[int]) -> str:
+        """Expects list of integers but will receive invalid JSON."""
+        return f"Got {len(numbers)} numbers"
+
+    client = Client(transport=FastMCPTransport(server))
+
+    async with client:
+        with pytest.raises(MCPError, match="Could not convert argument"):
+            await client.get_prompt(
+                "strict_typed_prompt",
+                {
+                    "numbers": "not valid json"  # This will fail server-side conversion
+                },
+            )
+
+
+async def test_read_resource_invalid_uri(fastmcp_server):
+    """Test reading a resource with an invalid URI."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+    with pytest.raises(ValueError, match="Provided resource URI is invalid"):
+        await client.read_resource("invalid_uri")
+
+
+async def test_read_resource(fastmcp_server):
+    """Test reading a resource with InMemoryClient."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    async with client:
+        # Use the URI from the resource we know exists in our server
+        uri = cast(
+            AnyUrl, "data://users"
+        )  # Use cast for type hint only, the URI is valid
+        result = await client.read_resource(uri)
+
+        # The contents should include our user list
+        contents_str = str(result[0])
+        assert "Alice" in contents_str
+        assert "Bob" in contents_str
+        assert "Charlie" in contents_str
+
+
+async def test_read_resource_mcp(fastmcp_server):
+    """Test the read_resource_mcp method that returns raw MCP protocol objects."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    async with client:
+        # Use the URI from the resource we know exists in our server
+        uri = cast(
+            AnyUrl, "data://users"
+        )  # Use cast for type hint only, the URI is valid
+        result = await client.read_resource_mcp(uri)
+
+        # Check that we got the raw MCP ReadResourceResult object
+        assert hasattr(result, "contents")
+        assert len(result.contents) > 0
+        contents_str = str(result.contents[0])
+        assert "Alice" in contents_str
+        assert "Bob" in contents_str
+        assert "Charlie" in contents_str
+
+
+async def test_client_connection(fastmcp_server):
+    """Test that connect is idempotent."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    # Connect idempotently
+    async with client:
+        assert client.is_connected()
+        # Make a request to ensure connection is working
+        await client.ping()
+    assert not client.is_connected()
+
+
+async def test_initialize_called_once(fastmcp_server):
+    """Test that initialization is called once and sets initialize_result."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+    async with client:
+        # Verify that initialization succeeded by checking initialize_result
+        assert client.initialize_result is not None
+        assert client.initialize_result.server_info is not None
+
+
+async def test_initialize_result_connected(fastmcp_server):
+    """Test that initialize_result returns the correct result when connected."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    # Initialize result should be None before connection
+    assert client.initialize_result is None
+
+    async with client:
+        # Once connected, initialize_result should be available
+        result = client.initialize_result
+
+        # Verify the initialize result has expected properties
+        assert hasattr(result, "serverInfo")
+        assert result.server_info.name == "TestServer"
+        assert result.server_info.version is not None
+
+
+async def test_initialize_result_disconnected(fastmcp_server):
+    """Test that initialize_result is None when not connected."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    # Initialize result should be None before connection
+    assert client.initialize_result is None
+
+    # Connect and then disconnect
+    async with client:
+        assert client.is_connected()
+
+    # After disconnection, initialize_result should be None again
+    assert not client.is_connected()
+    assert client.initialize_result is None
+
+
+async def test_server_info_custom_version():
+    """Test that custom version is properly set in serverInfo."""
+    # Test with custom version
+    server_with_version = FastMCP("CustomVersionServer", version="1.2.3")
+    client = Client(transport=FastMCPTransport(server_with_version))
+
+    async with client:
+        result = client.initialize_result
+        assert result is not None
+        assert result.server_info.name == "CustomVersionServer"
+        assert result.server_info.version == "1.2.3"
+
+    # Test without version (backward compatibility)
+    server_without_version = FastMCP("DefaultVersionServer")
+    client = Client(transport=FastMCPTransport(server_without_version))
+
+    async with client:
+        result = client.initialize_result
+        assert result is not None
+        assert result.server_info.name == "DefaultVersionServer"
+        # Should fall back to FastMCP version
+        assert result.server_info.version == fastmcp.__version__
+
+
+class _DelayedConnectTransport(ClientTransport):
+    def __init__(
+        self,
+        inner: ClientTransport,
+        connect_started: anyio.Event,
+        allow_connect: anyio.Event,
+    ) -> None:
+        self._inner = inner
+        self._connect_started = connect_started
+        self._allow_connect = allow_connect
+
+    @contextlib.asynccontextmanager
+    async def connect_session(
+        self, **session_kwargs: Any
+    ) -> AsyncIterator[ClientSession]:
+        self._connect_started.set()
+        await self._allow_connect.wait()
+        async with self._inner.connect_session(**session_kwargs) as session:
+            yield session
+
+    async def close(self) -> None:
+        await self._inner.close()
+
+
+class _DelayedDisconnectTransport(ClientTransport):
+    def __init__(
+        self,
+        inner: ClientTransport,
+        disconnect_started: anyio.Event,
+        allow_disconnect: anyio.Event,
+    ) -> None:
+        self._inner = inner
+        self._disconnect_started = disconnect_started
+        self._allow_disconnect = allow_disconnect
+
+    @contextlib.asynccontextmanager
+    async def connect_session(
+        self, **session_kwargs: Any
+    ) -> AsyncIterator[ClientSession]:
+        async with self._inner.connect_session(**session_kwargs) as session:
+            try:
+                yield session
+            finally:
+                self._disconnect_started.set()
+                await self._allow_disconnect.wait()
+
+    async def close(self) -> None:
+        await self._inner.close()
+
+
+async def test_client_nested_context_manager(fastmcp_server):
+    """Test that the client connects and disconnects once in nested context manager."""
+
+    client = Client(fastmcp_server)
+
+    # Before connection
+    assert not client.is_connected()
+    assert client._session_state.session is None
+
+    # During connection
+    async with client:
+        assert client.is_connected()
+        assert client._session_state.session is not None
+        session = client._session_state.session
+
+        # Reuse the same session
+        async with client:
+            assert client.is_connected()
+            assert client._session_state.session is session
+
+        # Reuse the same session
+        async with client:
+            assert client.is_connected()
+            assert client._session_state.session is session
+
+    # After connection
+    assert not client.is_connected()
+    assert client._session_state.session is None
+
+
+async def test_client_context_entry_cancelled_starter_cleans_up(fastmcp_server):
+    connect_started = anyio.Event()
+    allow_connect = anyio.Event()
+
+    client = Client(
+        transport=_DelayedConnectTransport(
+            FastMCPTransport(fastmcp_server),
+            connect_started=connect_started,
+            allow_connect=allow_connect,
+        )
+    )
+
+    async def enter_and_never_reach_body() -> None:
+        async with client:
+            pytest.fail(
+                "Context body should not be reached when __aenter__ is cancelled"
+            )
+
+    task = asyncio.create_task(enter_and_never_reach_body())
+    await connect_started.wait()
+
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+
+    # Connection startup was cancelled; session state should be fully reset.
+    assert client._session_state.session_task is None
+    assert client._session_state.session is None
+    assert client._session_state.nesting_counter == 0
+
+    # A future connection attempt should work normally.
+    allow_connect.set()
+    async with client:
+        tools = await client.list_tools()
+        assert len(tools) == 3
+
+
+async def test_cancelled_context_entry_waiter_does_not_close_active_session(
+    fastmcp_server,
+):
+    connect_started = anyio.Event()
+    allow_connect = anyio.Event()
+
+    client = Client(
+        transport=_DelayedConnectTransport(
+            FastMCPTransport(fastmcp_server),
+            connect_started=connect_started,
+            allow_connect=allow_connect,
+        )
+    )
+
+    b_done = asyncio.Event()
+    b_started = asyncio.Event()
+
+    async def task_a() -> int:
+        async with client:
+            await b_done.wait()
+            tools = await client.list_tools()
+            return len(tools)
+
+    async def task_b() -> None:
+        b_started.set()
+        async with client:
+            pytest.fail("This context should never be entered due to cancellation")
+
+    a = asyncio.create_task(task_a())
+    await connect_started.wait()
+
+    b = asyncio.create_task(task_b())
+    await b_started.wait()
+    await asyncio.sleep(0)  # let task_b attempt to acquire the client lock
+
+    b.cancel()
+    allow_connect.set()
+
+    with pytest.raises(asyncio.CancelledError):
+        await b
+
+    # task_b is fully cancelled; allow task_a to exercise the connected session.
+    b_done.set()
+    assert await a == 3
+
+
+async def test_force_close_cancelled_wait_starts_fresh_session(fastmcp_server):
+    disconnect_started = anyio.Event()
+    allow_disconnect = anyio.Event()
+    client = Client(
+        transport=_DelayedDisconnectTransport(
+            FastMCPTransport(fastmcp_server),
+            disconnect_started=disconnect_started,
+            allow_disconnect=allow_disconnect,
+        )
+    )
+
+    await client._connect()
+    original_session_task = client._session_state.session_task
+    assert original_session_task is not None
+
+    close_task = asyncio.create_task(client.close())
+    await disconnect_started.wait()
+
+    close_task.cancel()
+
+    async def reconnect_and_count_tools() -> int:
+        async with client:
+            assert client._session_state.session_task is not original_session_task
+            tools = await client.list_tools()
+            return len(tools)
+
+    reconnect_task = asyncio.create_task(reconnect_and_count_tools())
+    await asyncio.sleep(0)
+    assert not reconnect_task.done()
+
+    allow_disconnect.set()
+
+    with contextlib.suppress(asyncio.CancelledError):
+        await close_task
+
+    assert await reconnect_task == 3
+    assert original_session_task.done()
+
+
+async def test_disconnect_with_hanging_transport_does_not_leak_session_task(
+    fastmcp_server, monkeypatch
+):
+    """A hung transport teardown must not leak the background session task.
+
+    Simulates the failure mode reported in
+    https://github.com/PrefectHQ/fastmcp/issues/3947: the remote HTTP server
+    has dropped the keep-alive connection, so the termination POST inside
+    the transport never returns. ``__aexit__`` must bound the wait and
+    cancel the runner so a subsequent Client can reuse the same transport
+    resources.
+    """
+    monkeypatch.setattr(fastmcp.settings, "client_disconnect_timeout", 0.2)
+
+    disconnect_started = anyio.Event()
+    never_allow_disconnect = anyio.Event()
+
+    client = Client(
+        transport=_DelayedDisconnectTransport(
+            FastMCPTransport(fastmcp_server),
+            disconnect_started=disconnect_started,
+            allow_disconnect=never_allow_disconnect,
+        )
+    )
+
+    async with client:
+        tools = await client.list_tools()
+        assert len(tools) == 3
+        session_task = client._session_state.session_task
+        assert session_task is not None
+
+    # Transport hung during teardown; the client should have bounded the
+    # wait, cancelled the runner, and cleared its own reference.
+    assert disconnect_started.is_set()
+    assert client._session_state.session_task is None
+    assert session_task.done()
+
+    # And the Client is reusable for a fresh session.
+    async with client:
+        tools = await client.list_tools()
+        assert len(tools) == 3
+
+
+async def test_concurrent_client_context_managers():
+    """
+    Test that concurrent client usage doesn't cause cross-task cancel scope issues.
+    https://github.com/PrefectHQ/fastmcp/pull/643
+    """
+    # Create a simple server
+    server = FastMCP("Test Server")
+
+    @server.tool
+    def echo(text: str) -> str:
+        """Echo tool"""
+        return text
+
+    # Create client
+    client = Client(server)
+
+    # Track results
+    results = {}
+    errors = []
+
+    async def use_client(task_id: str, delay: float = 0):
+        """Use the client with a small delay to ensure overlap"""
+        try:
+            async with client:
+                # Add a small delay to ensure contexts overlap
+                await asyncio.sleep(delay)
+                # Make an actual call to exercise the session
+                tools = await client.list_tools()
+                results[task_id] = len(tools)
+        except Exception as e:
+            errors.append((task_id, str(e)))
+
+    # Run multiple tasks concurrently
+    # The key is having them enter and exit the context at different times
+    await asyncio.gather(
+        use_client("task1", 0.0),
+        use_client("task2", 0.01),  # Slight delay to ensure overlap
+        use_client("task3", 0.02),
+        return_exceptions=False,
+    )
+
+    assert len(errors) == 0, f"Errors occurred: {errors}"
+    assert len(results) == 3
+    assert all(count == 1 for count in results.values())  # All should see 1 tool
+
+
+async def test_resource_template(fastmcp_server):
+    """Test using a resource template with InMemoryClient."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    async with client:
+        # First, list templates
+        result = await client.list_resource_templates()
+
+        # Check that our template is available
+        assert len(result) == 1
+        assert "data://user/{user_id}" in result[0].uri_template
+
+        # Now use the template with a specific user_id
+        uri = cast(AnyUrl, "data://user/123")
+        result = await client.read_resource(uri)
+
+        # Check the content matches what we expect for the provided user_id
+        content_str = str(result[0])
+        assert '"id":"123"' in content_str
+        assert '"name":"User 123"' in content_str
+        assert '"active":true' in content_str
+
+
+async def test_list_resource_templates_mcp(fastmcp_server):
+    """Test the list_resource_templates_mcp method that returns raw MCP protocol objects."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    async with client:
+        result = await client.list_resource_templates_mcp()
+
+        # Check that we got the raw MCP ListResourceTemplatesResult object
+        assert hasattr(result, "resourceTemplates")
+        assert len(result.resource_templates) == 1
+        assert "data://user/{user_id}" in result.resource_templates[0].uri_template
+
+
+async def test_mcp_resource_generation(fastmcp_server):
+    """Test that resources are properly generated in MCP format."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    async with client:
+        resources = await client.list_resources()
+        assert len(resources) == 1
+        resource = resources[0]
+
+        # Verify resource has correct MCP format
+        assert hasattr(resource, "uri")
+        assert hasattr(resource, "name")
+        assert hasattr(resource, "description")
+        assert str(resource.uri) == "data://users"
+
+
+async def test_mcp_template_generation(fastmcp_server):
+    """Test that templates are properly generated in MCP format."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    async with client:
+        templates = await client.list_resource_templates()
+        assert len(templates) == 1
+        template = templates[0]
+
+        # Verify template has correct MCP format
+        assert hasattr(template, "uriTemplate")
+        assert hasattr(template, "name")
+        assert hasattr(template, "description")
+        assert "data://user/{user_id}" in template.uri_template
+
+
+async def test_template_access_via_client(fastmcp_server):
+    """Test that templates can be accessed through a client."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    async with client:
+        # Verify template works correctly when accessed
+        uri = cast(AnyUrl, "data://user/456")
+        result = await client.read_resource(uri)
+        content_str = str(result[0])
+        assert '"id":"456"' in content_str
+
+
+async def test_tagged_resource_metadata(tagged_resources_server):
+    """Test that resource metadata is preserved in MCP format."""
+    client = Client(transport=FastMCPTransport(tagged_resources_server))
+
+    async with client:
+        resources = await client.list_resources()
+        assert len(resources) == 1
+        resource = resources[0]
+
+        # Verify resource metadata is preserved
+        assert str(resource.uri) == "data://tagged"
+        assert resource.description == "A tagged resource"
+
+
+async def test_tagged_template_metadata(tagged_resources_server):
+    """Test that template metadata is preserved in MCP format."""
+    client = Client(transport=FastMCPTransport(tagged_resources_server))
+
+    async with client:
+        templates = await client.list_resource_templates()
+        assert len(templates) == 1
+        template = templates[0]
+
+        # Verify template metadata is preserved
+        assert "template://{id}" in template.uri_template
+        assert template.description == "A tagged template"
+
+
+async def test_tagged_template_functionality(tagged_resources_server):
+    """Test that tagged templates function correctly when accessed."""
+    client = Client(transport=FastMCPTransport(tagged_resources_server))
+
+    async with client:
+        # Verify template functionality
+        uri = cast(AnyUrl, "template://123")
+        result = await client.read_resource(uri)
+        content_str = str(result[0])
+        assert '"id":"123"' in content_str
+        assert '"type":"template_data"' in content_str
+
+
+async def test_client_unwraps_result_using_meta():
+    """Client should unwrap wrapped results using _meta flag."""
+    server = FastMCP()
+
+    @server.tool
+    def list_tool() -> list[int]:
+        return [1, 2, 3]
+
+    client = Client(transport=FastMCPTransport(server))
+    async with client:
+        result = await client.call_tool("list_tool", {})
+        assert result.structured_content == {"result": [1, 2, 3]}
+        assert result.data == [1, 2, 3]
+        assert result.meta == {"fastmcp": {"wrap_result": True}}
+
+
+async def test_client_does_not_unwrap_dict_result():
+    """Client should not unwrap dict results that are not wrapped."""
+    server = FastMCP()
+
+    @server.tool
+    def dict_tool() -> dict[str, int]:
+        return {"a": 1}
+
+    client = Client(transport=FastMCPTransport(server))
+    async with client:
+        result = await client.call_tool("dict_tool", {})
+        assert result.structured_content == {"a": 1}
+        assert result.data == {"a": 1}
+        assert result.meta is None
+
+
+async def test_client_list_dict_return_type():
+    """list[dict] return type should produce list of dicts, not Root() objects (issue #3867)."""
+    server = FastMCP()
+
+    @server.tool
+    def get_temperatures() -> list[dict]:
+        """Get current temperatures for all cities"""
+        return [
+            {"city": "NYC", "temp": 72},
+            {"city": "LA", "temp": 85},
+        ]
+
+    client = Client(transport=FastMCPTransport(server))
+    async with client:
+        result = await client.call_tool("get_temperatures", {})
+        assert result.data == [{"city": "NYC", "temp": 72}, {"city": "LA", "temp": 85}]
+
+
+def test_client_new_resets_mutable_task_state(fastmcp_server):
+    """Client.new() should not share mutable task tracking structures."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    client._task_registry["task-1"] = lambda: None  # type: ignore[assignment]  # ty:ignore[invalid-assignment]
+    client._submitted_task_ids.add("task-1")
+
+    clone = client.new()
+
+    assert clone is not client
+    assert clone._task_registry == {}
+    assert clone._submitted_task_ids == set()
+    assert clone._task_registry is not client._task_registry
+    assert clone._submitted_task_ids is not client._submitted_task_ids
+
+
+def test_client_new_rebinds_default_task_notification_handler(fastmcp_server):
+    """Client.new() should bind the default task handler to the cloned client."""
+    client = Client(transport=FastMCPTransport(fastmcp_server))
+
+    handler = client._session_kwargs.get("message_handler")
+    assert isinstance(handler, TaskNotificationHandler)
+
+    clone = client.new()
+
+    clone_handler = clone._session_kwargs.get("message_handler")
+    assert isinstance(clone_handler, TaskNotificationHandler)
+    assert clone_handler is not handler
+    assert clone_handler._client_ref() is clone
diff --git a/tests/client/client/test_error_handling.py b/tests/client/client/test_error_handling.py
new file mode 100644
index 0000000..aa1ed61
--- /dev/null
+++ b/tests/client/client/test_error_handling.py
@@ -0,0 +1,442 @@
+"""Client error handling tests."""
+
+import logging
+
+import mcp_types
+import pytest
+from mcp_types import TextContent, ToolUseContent
+from pydantic import AnyUrl
+
+from fastmcp.client import Client
+from fastmcp.client.mixins.tools import _parse_call_tool_result
+from fastmcp.client.transports import FastMCPTransport
+from fastmcp.exceptions import PromptError, ResourceError, ToolError
+from fastmcp.server.sampling.run import SamplingTool, execute_tools
+from fastmcp.server.server import FastMCP
+
+
+class TestErrorHandling:
+    async def test_general_tool_exceptions_are_not_masked_by_default(self):
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        def error_tool():
+            raise ValueError("This is a test error (abc)")
+
+        client = Client(transport=FastMCPTransport(mcp))
+
+        async with client:
+            result = await client.call_tool_mcp("error_tool", {})
+            assert result.is_error
+            assert isinstance(result.content[0], TextContent)
+            assert "test error" in result.content[0].text
+            assert "abc" in result.content[0].text
+
+    async def test_general_tool_exceptions_are_masked_when_enabled(self):
+        mcp = FastMCP("TestServer", mask_error_details=True)
+
+        @mcp.tool
+        def error_tool():
+            raise ValueError("This is a test error (abc)")
+
+        client = Client(transport=FastMCPTransport(mcp))
+
+        async with client:
+            result = await client.call_tool_mcp("error_tool", {})
+            assert result.is_error
+            assert isinstance(result.content[0], TextContent)
+            assert "test error" not in result.content[0].text
+            assert "abc" not in result.content[0].text
+
+    async def test_validation_errors_are_not_masked_when_enabled(self):
+        mcp = FastMCP("TestServer", mask_error_details=True)
+
+        @mcp.tool
+        def validated_tool(x: int) -> int:
+            return x
+
+        async with Client(transport=FastMCPTransport(mcp)) as client:
+            result = await client.call_tool_mcp("validated_tool", {"x": "abc"})
+            assert result.is_error
+            # Pydantic validation error message should NOT be masked
+            assert isinstance(result.content[0], TextContent)
+            assert "Input should be a valid integer" in result.content[0].text
+
+    async def test_specific_tool_errors_are_sent_to_client(self):
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        def custom_error_tool():
+            raise ToolError("This is a test error (abc)")
+
+        client = Client(transport=FastMCPTransport(mcp))
+
+        async with client:
+            result = await client.call_tool_mcp("custom_error_tool", {})
+            assert result.is_error
+            assert isinstance(result.content[0], TextContent)
+            assert "test error" in result.content[0].text
+            assert "abc" in result.content[0].text
+
+    async def test_general_resource_exceptions_are_not_masked_by_default(self):
+        mcp = FastMCP("TestServer")
+
+        @mcp.resource(uri="exception://resource")
+        async def exception_resource():
+            raise ValueError("This is an internal error (sensitive)")
+
+        client = Client(transport=FastMCPTransport(mcp))
+
+        async with client:
+            with pytest.raises(Exception) as excinfo:
+                await client.read_resource(AnyUrl("exception://resource"))
+            assert "Error reading resource" in str(excinfo.value)
+            assert "sensitive" in str(excinfo.value)
+            assert "internal error" in str(excinfo.value)
+
+    async def test_general_resource_exceptions_are_masked_when_enabled(self):
+        mcp = FastMCP("TestServer", mask_error_details=True)
+
+        @mcp.resource(uri="exception://resource")
+        async def exception_resource():
+            raise ValueError("This is an internal error (sensitive)")
+
+        client = Client(transport=FastMCPTransport(mcp))
+
+        async with client:
+            with pytest.raises(Exception) as excinfo:
+                await client.read_resource(AnyUrl("exception://resource"))
+            assert "Error reading resource" in str(excinfo.value)
+            assert "sensitive" not in str(excinfo.value)
+            assert "internal error" not in str(excinfo.value)
+
+    async def test_resource_errors_are_sent_to_client(self):
+        mcp = FastMCP("TestServer")
+
+        @mcp.resource(uri="error://resource")
+        async def error_resource():
+            raise ResourceError("This is a resource error (xyz)")
+
+        client = Client(transport=FastMCPTransport(mcp))
+
+        async with client:
+            with pytest.raises(Exception) as excinfo:
+                await client.read_resource(AnyUrl("error://resource"))
+            assert "This is a resource error (xyz)" in str(excinfo.value)
+
+    async def test_general_template_exceptions_are_not_masked_by_default(self):
+        mcp = FastMCP("TestServer")
+
+        @mcp.resource(uri="exception://resource/{id}")
+        async def exception_resource(id: str):
+            raise ValueError("This is an internal error (sensitive)")
+
+        client = Client(transport=FastMCPTransport(mcp))
+
+        async with client:
+            with pytest.raises(Exception) as excinfo:
+                await client.read_resource(AnyUrl("exception://resource/123"))
+            assert "Error reading resource" in str(excinfo.value)
+            assert "sensitive" in str(excinfo.value)
+            assert "internal error" in str(excinfo.value)
+
+    async def test_general_template_exceptions_are_masked_when_enabled(self):
+        mcp = FastMCP("TestServer", mask_error_details=True)
+
+        @mcp.resource(uri="exception://resource/{id}")
+        async def exception_resource(id: str):
+            raise ValueError("This is an internal error (sensitive)")
+
+        client = Client(transport=FastMCPTransport(mcp))
+
+        async with client:
+            with pytest.raises(Exception) as excinfo:
+                await client.read_resource(AnyUrl("exception://resource/123"))
+            assert "Error reading resource" in str(excinfo.value)
+            assert "sensitive" not in str(excinfo.value)
+            assert "internal error" not in str(excinfo.value)
+
+    async def test_template_errors_are_sent_to_client(self):
+        mcp = FastMCP("TestServer")
+
+        @mcp.resource(uri="error://resource/{id}")
+        async def error_resource(id: str):
+            raise ResourceError("This is a resource error (xyz)")
+
+        client = Client(transport=FastMCPTransport(mcp))
+
+        async with client:
+            with pytest.raises(Exception) as excinfo:
+                await client.read_resource(AnyUrl("error://resource/123"))
+            assert "This is a resource error (xyz)" in str(excinfo.value)
+
+
+class TestCallToolRaiseOnError:
+    """Tests for call_tool error handling with raise_on_error."""
+
+    async def test_call_tool_raises_tool_error_by_default(self):
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        def failing_tool() -> str:
+            raise ValueError("something broke")
+
+        async with Client(transport=FastMCPTransport(mcp)) as client:
+            with pytest.raises(ToolError, match="something broke"):
+                await client.call_tool("failing_tool", {})
+
+    async def test_call_tool_no_raise_returns_error_result(self):
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        def failing_tool() -> str:
+            raise ValueError("something broke")
+
+        async with Client(transport=FastMCPTransport(mcp)) as client:
+            result = await client.call_tool("failing_tool", {}, raise_on_error=False)
+            assert result.is_error is True
+            assert result.data is None
+
+
+class TestParseToolResultEdgeCases:
+    """Unit tests for _parse_call_tool_result with non-standard error payloads.
+
+    These edge cases can't be triggered through the public Client API because
+    FastMCP's server always produces TextContent on errors. Testing the parser
+    directly covers defensive handling of third-party MCP servers.
+    """
+
+    async def test_error_with_empty_content_raises_with_fallback_message(self):
+        result = mcp_types.CallToolResult(content=[], is_error=True)
+
+        with pytest.raises(ToolError, match="Tool 'my_tool' returned an error"):
+            await _parse_call_tool_result(
+                name="my_tool",
+                result=result,
+                tool_output_schemas={},
+                list_tools_fn=None,
+                raise_on_error=True,
+            )
+
+    async def test_error_with_non_text_content_raises_with_fallback_message(self):
+        result = mcp_types.CallToolResult(
+            content=[
+                mcp_types.ImageContent(type="image", data="abc", mime_type="image/png")
+            ],
+            is_error=True,
+        )
+
+        with pytest.raises(ToolError, match="Tool 'my_tool' returned an error"):
+            await _parse_call_tool_result(
+                name="my_tool",
+                result=result,
+                tool_output_schemas={},
+                list_tools_fn=None,
+                raise_on_error=True,
+            )
+
+    async def test_error_with_text_content_raises_with_message(self):
+        result = mcp_types.CallToolResult(
+            content=[mcp_types.TextContent(type="text", text="custom error msg")],
+            is_error=True,
+        )
+
+        with pytest.raises(ToolError, match="custom error msg"):
+            await _parse_call_tool_result(
+                name="my_tool",
+                result=result,
+                tool_output_schemas={},
+                list_tools_fn=None,
+                raise_on_error=True,
+            )
+
+    async def test_error_with_structured_content_does_not_parse_data(self):
+        result = mcp_types.CallToolResult(
+            content=[mcp_types.TextContent(type="text", text="error happened")],
+            is_error=True,
+            structured_content={"key": "value"},
+        )
+
+        parsed = await _parse_call_tool_result(
+            name="my_tool",
+            result=result,
+            tool_output_schemas={},
+            list_tools_fn=None,
+            raise_on_error=False,
+        )
+
+        assert parsed.is_error is True
+        assert parsed.data is None
+        assert parsed.structured_content == {"key": "value"}
+
+
+class TestLogLevel:
+    async def test_tool_error_with_custom_log_level(self, caplog):
+        """ToolError with custom log_level should log at specified level."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        def custom_level_tool():
+            raise ToolError("Missing required parameter", log_level=logging.WARNING)
+
+        async with Client(transport=FastMCPTransport(mcp)) as client:
+            with caplog.at_level(logging.WARNING):
+                result = await client.call_tool_mcp("custom_level_tool", {})
+
+        assert result.is_error
+        assert isinstance(result.content[0], TextContent)
+        assert "Missing required parameter" in result.content[0].text
+        assert any(
+            "Error calling tool" in record.message and record.levelname == "WARNING"
+            for record in caplog.records
+        )
+        assert not any(
+            "Error calling tool" in record.message and record.levelname == "ERROR"
+            for record in caplog.records
+        )
+
+    async def test_regular_tool_error_logs_at_error(self, caplog):
+        """ToolError with default log_level logs at ERROR."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        def regular_error_tool():
+            raise ToolError("Something went wrong")
+
+        async with Client(transport=FastMCPTransport(mcp)) as client:
+            with caplog.at_level(logging.ERROR):
+                result = await client.call_tool_mcp("regular_error_tool", {})
+
+        assert result.is_error
+        assert isinstance(result.content[0], TextContent)
+        assert "Something went wrong" in result.content[0].text
+        assert any(
+            "Error calling tool 'regular_error_tool'" in record.message
+            and record.levelname == "ERROR"
+            for record in caplog.records
+        )
+
+    async def test_resource_error_with_custom_log_level(self, caplog):
+        """ResourceError with custom log_level should log at specified level."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.resource("test://custom")
+        def custom_level_resource():
+            raise ResourceError(
+                "Resource unavailable, try again later", log_level=logging.WARNING
+            )
+
+        async with Client(transport=FastMCPTransport(mcp)) as client:
+            with caplog.at_level(logging.WARNING):
+                with pytest.raises(Exception) as exc_info:
+                    await client.read_resource_mcp("test://custom")
+
+        assert "Resource unavailable, try again later" in str(exc_info.value)
+        assert any(
+            "Error reading resource" in record.message and record.levelname == "WARNING"
+            for record in caplog.records
+        )
+        assert not any(
+            "Error reading resource" in record.message and record.levelname == "ERROR"
+            for record in caplog.records
+        )
+
+    async def test_regular_resource_error_logs_at_error(self, caplog):
+        """ResourceError with default log_level logs at ERROR."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.resource("test://regular")
+        def regular_resource():
+            raise ResourceError("Something went wrong")
+
+        async with Client(transport=FastMCPTransport(mcp)) as client:
+            with caplog.at_level(logging.ERROR):
+                with pytest.raises(Exception) as exc_info:
+                    await client.read_resource_mcp("test://regular")
+
+        assert "Something went wrong" in str(exc_info.value)
+        assert any(
+            "Error reading resource 'test://regular'" in record.message
+            and record.levelname == "ERROR"
+            for record in caplog.records
+        )
+
+    async def test_prompt_error_with_custom_log_level(self, caplog):
+        """PromptError with custom log_level should log at specified level."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.prompt
+        def custom_level_prompt():
+            raise PromptError(
+                "Insufficient context, provide more details", log_level=logging.WARNING
+            )
+
+        async with Client(transport=FastMCPTransport(mcp)) as client:
+            with caplog.at_level(logging.WARNING):
+                with pytest.raises(Exception) as exc_info:
+                    await client.get_prompt("custom_level_prompt")
+
+        assert "Insufficient context" in str(exc_info.value)
+        assert any(
+            "Error rendering prompt" in record.message and record.levelname == "WARNING"
+            for record in caplog.records
+        )
+        assert not any(
+            "Error rendering prompt" in record.message and record.levelname == "ERROR"
+            for record in caplog.records
+        )
+
+    async def test_regular_prompt_error_logs_at_error(self, caplog):
+        """PromptError with default log_level logs at ERROR."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.prompt
+        def regular_prompt():
+            raise PromptError("Something went wrong")
+
+        async with Client(transport=FastMCPTransport(mcp)) as client:
+            with caplog.at_level(logging.ERROR):
+                with pytest.raises(Exception) as exc_info:
+                    await client.get_prompt("regular_prompt")
+
+        assert "Something went wrong" in str(exc_info.value)
+        assert any(
+            "Error rendering prompt 'regular_prompt'" in record.message
+            and record.levelname == "ERROR"
+            for record in caplog.records
+        )
+
+    async def test_sampling_tool_error_with_custom_log_level(self, caplog):
+        """ToolError with custom log_level in sampling should log at specified level."""
+
+        async def custom_level_sampling_tool(x: int) -> int:
+            raise ToolError("Expected sampling error", log_level=logging.WARNING)
+
+        tool = SamplingTool.from_function(custom_level_sampling_tool)
+        tool_use = ToolUseContent(
+            type="tool_use",
+            id="test-id",
+            name="custom_level_sampling_tool",
+            input={"x": 42},
+        )
+
+        with caplog.at_level(logging.WARNING):
+            results = await execute_tools(
+                tool_calls=[tool_use],
+                tool_map={"custom_level_sampling_tool": tool},
+                mask_error_details=False,
+            )
+
+        assert len(results) == 1
+        assert results[0].is_error
+        assert "Expected sampling error" in results[0].content[0].text  # type: ignore
+        assert any(
+            "Error calling sampling tool" in record.message
+            and record.levelname == "WARNING"
+            for record in caplog.records
+        )
+        assert not any(
+            "Error calling sampling tool" in record.message
+            and record.levelname == "ERROR"
+            for record in caplog.records
+        )
diff --git a/tests/client/client/test_initialize.py b/tests/client/client/test_initialize.py
new file mode 100644
index 0000000..7bbe3ae
--- /dev/null
+++ b/tests/client/client/test_initialize.py
@@ -0,0 +1,115 @@
+"""Client initialization tests."""
+
+from fastmcp.client import Client
+from fastmcp.server.server import FastMCP
+
+
+class TestInitialize:
+    """Tests for client initialization behavior."""
+
+    async def test_auto_initialize_default(self, fastmcp_server):
+        """Test that auto_initialize=True is the default and works automatically."""
+        client = Client(fastmcp_server)
+
+        async with client:
+            # Should be automatically initialized
+            assert client.initialize_result is not None
+            assert client.initialize_result.server_info.name == "TestServer"
+            assert client.initialize_result.instructions is None
+
+    async def test_auto_initialize_explicit_true(self, fastmcp_server):
+        """Test explicit auto_initialize=True."""
+        client = Client(fastmcp_server, auto_initialize=True)
+
+        async with client:
+            assert client.initialize_result is not None
+            assert client.initialize_result.server_info.name == "TestServer"
+
+    async def test_auto_initialize_false(self, fastmcp_server):
+        """Test that auto_initialize=False prevents automatic initialization."""
+        client = Client(fastmcp_server, auto_initialize=False)
+
+        async with client:
+            # Should not be automatically initialized
+            assert client.initialize_result is None
+
+    async def test_manual_initialize(self, fastmcp_server):
+        """Test manual initialization when auto_initialize=False."""
+        client = Client(fastmcp_server, auto_initialize=False)
+
+        async with client:
+            # Manually initialize
+            result = await client.initialize()
+
+            assert result is not None
+            assert result.server_info.name == "TestServer"
+            assert client.initialize_result is result
+
+    async def test_initialize_idempotent(self, fastmcp_server):
+        """Test that calling initialize() multiple times returns cached result."""
+        client = Client(fastmcp_server, auto_initialize=False)
+
+        async with client:
+            result1 = await client.initialize()
+            result2 = await client.initialize()
+            result3 = await client.initialize()
+
+            # All should return the same cached result
+            assert result1 is result2
+            assert result2 is result3
+
+    async def test_initialize_with_instructions(self):
+        """Test that server instructions are available via initialize_result."""
+        server = FastMCP("InstructionsServer", instructions="Use the greet tool!")
+
+        @server.tool
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        client = Client(server)
+
+        async with client:
+            result = client.initialize_result
+            assert result is not None
+            assert result.instructions == "Use the greet tool!"
+
+    async def test_initialize_timeout_custom(self, fastmcp_server):
+        """Test custom timeout for initialize()."""
+        client = Client(fastmcp_server, auto_initialize=False)
+
+        async with client:
+            # Should succeed with reasonable timeout
+            result = await client.initialize(timeout=5.0)
+            assert result is not None
+
+    async def test_initialize_property_after_auto_init(self, fastmcp_server):
+        """Test accessing initialize_result property after auto-initialization."""
+        client = Client(fastmcp_server, auto_initialize=True)
+
+        async with client:
+            # Access via property
+            result = client.initialize_result
+            assert result is not None
+            assert result.server_info.name == "TestServer"
+
+            # Call method - should return cached
+            result2 = await client.initialize()
+            assert result is result2
+
+    async def test_initialize_property_before_connect(self, fastmcp_server):
+        """Test that initialize_result property is None before connection."""
+        client = Client(fastmcp_server)
+
+        # Not yet connected
+        assert client.initialize_result is None
+
+    async def test_manual_initialize_can_call_tools(self, fastmcp_server):
+        """Test that manually initialized client can call tools."""
+        client = Client(fastmcp_server, auto_initialize=False)
+
+        async with client:
+            await client.initialize()
+
+            # Should be able to call tools after manual initialization
+            result = await client.call_tool("greet", {"name": "World"})
+            assert "Hello, World!" in str(result.content)
diff --git a/tests/client/client/test_input_required_driver.py b/tests/client/client/test_input_required_driver.py
new file mode 100644
index 0000000..e96197d
--- /dev/null
+++ b/tests/client/client/test_input_required_driver.py
@@ -0,0 +1,209 @@
+"""Client-side SEP-2322 multi-round-trip (MRTR) input-required driving.
+
+A 2026-07-28 server may answer `tools/call` / `prompts/get` / `resources/read`
+with an `InputRequiredResult` carrying embedded sampling / elicitation / roots
+requests instead of the terminal result. `fastmcp.Client` fulfils those embedded
+requests through its *existing* handler callbacks (the same table that answers
+legacy server-initiated RPCs) and retries until the call resolves.
+
+The 2026 emitter here is the SDK's own high-level `MCPServer` with declarative
+`Resolve` / `Elicit` resolvers: at 2026-07-28 the framework batches a resolver's
+`Elicit` into an `InputRequiredResult`. It is driven in-memory through a
+`fastmcp.Client` with `mode="auto"` (which negotiates 2026-07-28 over the
+dual-era stream loop), so the whole answer path runs through FastMCP's client.
+
+Server-side MRTR *emission* is a maintainer-held design surface; these tests only
+exercise the client-side *answering* path, which the spec's decisive finding says
+is era-neutral by construction once the driver is wired.
+"""
+
+from typing import Annotated, cast
+
+import pytest
+from mcp.client._input_required import (
+    DEFAULT_INPUT_REQUIRED_MAX_ROUNDS,
+    InputRequiredRoundsExceededError,
+)
+from mcp.server.mcpserver import Elicit, MCPServer, Resolve
+from pydantic import BaseModel
+
+from fastmcp import Client, FastMCP
+from fastmcp.client.elicitation import ElicitResult
+
+
+class _Name(BaseModel):
+    name: str
+
+
+def _ask_name() -> Elicit[_Name]:
+    return Elicit("What is your name?", _Name)
+
+
+class _A(BaseModel):
+    a: str
+
+
+class _B(BaseModel):
+    b: str
+
+
+def _ask_a() -> Elicit[_A]:
+    return Elicit("question A", _A)
+
+
+def _ask_b(dep: Annotated[_A, Resolve(_ask_a)]) -> Elicit[_B]:
+    """A resolver depending on another's answer — asked in a later round."""
+    return Elicit(f"question B given {dep.a}", _B)
+
+
+def _multi_round_server() -> MCPServer:
+    server = MCPServer("multi")
+
+    @server.tool()
+    def combine(x: Annotated[_B, Resolve(_ask_b)]) -> str:
+        return f"got {x.b}"
+
+    return server
+
+
+def _mrtr_server() -> MCPServer:
+    """An SDK MCPServer whose `greet` tool elicits a name via a resolver.
+
+    At 2026-07-28 the elicitation is delivered as an `InputRequiredResult`.
+    """
+    server = MCPServer("mrtr")
+
+    @server.tool()
+    def greet(who: Annotated[_Name, Resolve(_ask_name)]) -> str:
+        return f"Hello, {who.name}!"
+
+    return server
+
+
+class TestParamDefaults:
+    def test_default_max_rounds(self):
+        client = Client(FastMCP("x"))
+        assert client.input_required_max_rounds == DEFAULT_INPUT_REQUIRED_MAX_ROUNDS
+
+    def test_custom_max_rounds(self):
+        client = Client(FastMCP("x"), input_required_max_rounds=3)
+        assert client.input_required_max_rounds == 3
+
+    def test_new_preserves_max_rounds(self):
+        parent = Client(FastMCP("x"), input_required_max_rounds=4)
+        assert parent.new().input_required_max_rounds == 4
+
+
+class TestCallToolMRTR:
+    async def test_single_round_completes(self):
+        """One full MRTR round: the server asks, the client's elicitation_handler
+        answers, and the tool completes with the answered value."""
+        asked: list[str] = []
+
+        async def handler(message, response_type, params, ctx):
+            asked.append(message)
+            return ElicitResult(action="accept", content=response_type(name="Ada"))
+
+        async with Client(
+            _mrtr_server(), mode="auto", elicitation_handler=handler
+        ) as client:
+            assert client.protocol_version == "2026-07-28"
+            result = await client.call_tool("greet", {})
+
+        # The embedded elicitation was answered exactly once and the terminal
+        # result carries the answered value. The SDK MCPServer wraps scalar
+        # output as {"result": ...}, surfaced via structured_content.
+        assert asked == ["What is your name?"]
+        assert result.structured_content == {"result": "Hello, Ada!"}
+        assert result.data.result == "Hello, Ada!"
+
+    async def test_data_parsed_on_terminal_result_only(self):
+        """`.data` deserialization runs on the resolved terminal result, never on
+        the intermediate InputRequiredResult."""
+
+        async def handler(message, response_type, params, ctx):
+            return ElicitResult(action="accept", content=response_type(name="Bob"))
+
+        async with Client(
+            _mrtr_server(), mode="auto", elicitation_handler=handler
+        ) as client:
+            result = await client.call_tool("greet", {})
+
+        assert result.is_error is False
+        assert result.data.result == "Hello, Bob!"
+        assert result.structured_content == {"result": "Hello, Bob!"}
+
+    async def test_multi_round_dependent_resolvers(self):
+        """A resolver depending on another's answer is asked in a later round; the
+        driver loops until the dependent chain terminates."""
+        rounds: list[str] = []
+
+        async def handler(message, response_type, params, ctx):
+            rounds.append(message)
+            if "question A" in message:
+                return ElicitResult(action="accept", content=response_type(a="AA"))
+            return ElicitResult(action="accept", content=response_type(b="BB"))
+
+        async with Client(
+            _multi_round_server(), mode="auto", elicitation_handler=handler
+        ) as client:
+            result = await client.call_tool("combine", {})
+
+        # Two rounds: A first, then B (which the client saw carried A's answer).
+        assert rounds == ["question A", "question B given AA"]
+        assert result.structured_content == {"result": "got BB"}
+
+    async def test_max_rounds_exceeded_raises(self):
+        """A dependent chain needing two rounds under `max_rounds=1` raises."""
+
+        async def handler(message, response_type, params, ctx):
+            field = "a" if "question A" in message else "b"
+            return ElicitResult(action="accept", content=response_type(**{field: "v"}))
+
+        async with Client(
+            _multi_round_server(),
+            mode="auto",
+            elicitation_handler=handler,
+            input_required_max_rounds=1,
+        ) as client:
+            with pytest.raises(InputRequiredRoundsExceededError):
+                await client.call_tool("combine", {})
+
+
+class TestLegacyUnaffected:
+    async def test_legacy_call_tool_no_mrtr(self):
+        """A legacy FastMCP server never emits InputRequiredResult; call_tool
+        behaves byte-identically to pre-driver behavior."""
+        mcp = FastMCP("legacy")
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        async with Client(mcp, mode="legacy") as client:
+            result = await client.call_tool("add", {"a": 2, "b": 3})
+        assert result.data == 5
+        assert result.is_error is False
+
+    async def test_legacy_elicitation_still_synchronous(self):
+        """On a legacy connection, a FastMCP server's `ctx.elicit` uses the
+        synchronous server-to-client request path (not MRTR), and the same
+        elicitation_handler answers it. This proves the handler table is shared."""
+        from fastmcp import Context
+        from fastmcp.server.elicitation import AcceptedElicitation
+
+        mcp = FastMCP("legacy-elicit")
+
+        @mcp.tool
+        async def ask(ctx: Context) -> str:
+            result = await ctx.elicit("your name", response_type=_Name)
+            assert isinstance(result, AcceptedElicitation)
+            data = cast(_Name, result.data)
+            return f"Hi {data.name}"
+
+        async def handler(message, response_type, params, ctx):
+            return ElicitResult(action="accept", content=response_type(name="Zoe"))
+
+        async with Client(mcp, mode="legacy", elicitation_handler=handler) as client:
+            result = await client.call_tool("ask", {})
+        assert result.data == "Hi Zoe"
diff --git a/tests/client/client/test_mode_negotiation.py b/tests/client/client/test_mode_negotiation.py
new file mode 100644
index 0000000..fc0b14f
--- /dev/null
+++ b/tests/client/client/test_mode_negotiation.py
@@ -0,0 +1,150 @@
+"""Connect-time protocol-era negotiation on ``fastmcp.Client`` (``mode=``).
+
+FastMCP serves both protocol eras from one server object over the in-memory
+stream loop (``serve_dual_era_loop``), so a single ``fastmcp_server`` fixture can
+be driven legacy or modern by varying ``mode=`` alone:
+
+* ``mode="legacy"`` (the current default) runs the initialize handshake and
+  reports the handshake-era version, byte-identically to pre-v4 behavior.
+* ``mode="auto"`` probes ``server/discover`` and negotiates the modern era.
+* ``mode="2026-07-28"`` pins the modern version and adopts a synthesized
+  ``DiscoverResult`` without a probe.
+"""
+
+from __future__ import annotations
+
+import pytest
+from mcp_types.version import LATEST_HANDSHAKE_VERSION, LATEST_MODERN_VERSION
+
+from fastmcp import Client, FastMCP
+
+
+class TestModeValidation:
+    def test_default_mode_is_legacy(self, fastmcp_server):
+        """The conservative default is 'legacy' (see the v4 phasing note)."""
+        assert Client(fastmcp_server).mode == "legacy"
+
+    @pytest.mark.parametrize("mode", ["legacy", "auto", LATEST_MODERN_VERSION])
+    def test_valid_modes_accepted(self, fastmcp_server, mode):
+        assert Client(fastmcp_server, mode=mode).mode == mode
+
+    def test_handshake_version_pin_rejected(self, fastmcp_server):
+        """A legacy-era version string is not a valid pin; the error steers to 'legacy'."""
+        with pytest.raises(ValueError, match="use mode='legacy'"):
+            Client(fastmcp_server, mode=LATEST_HANDSHAKE_VERSION)
+
+    def test_unknown_mode_rejected(self, fastmcp_server):
+        with pytest.raises(ValueError, match="mode must be 'legacy', 'auto'"):
+            Client(fastmcp_server, mode="bogus")
+
+
+class TestLegacyMode:
+    async def test_legacy_uses_initialize_handshake(self, fastmcp_server):
+        async with Client(fastmcp_server, mode="legacy") as client:
+            assert client.protocol_version == LATEST_HANDSHAKE_VERSION
+            # Legacy negotiation still populates the InitializeResult unchanged.
+            assert client.initialize_result is not None
+            assert client.initialize_result.server_info.name == "TestServer"
+            assert client.server_capabilities is not None
+
+    async def test_default_matches_legacy(self, fastmcp_server):
+        """Omitting mode= is byte-identical to mode='legacy'."""
+        async with Client(fastmcp_server) as client:
+            assert client.protocol_version == LATEST_HANDSHAKE_VERSION
+            assert client.initialize_result is not None
+
+    async def test_legacy_call_tool(self, fastmcp_server):
+        async with Client(fastmcp_server, mode="legacy") as client:
+            result = await client.call_tool("add", {"a": 2, "b": 3})
+        assert result.data == 5
+
+
+class TestAutoMode:
+    async def test_auto_negotiates_modern_via_discover(self, fastmcp_server):
+        """auto probes server/discover and adopts the modern era in-memory."""
+        async with Client(fastmcp_server, mode="auto") as client:
+            assert client.protocol_version == LATEST_MODERN_VERSION
+            # A discover connection carries capabilities but no InitializeResult.
+            assert client.server_capabilities is not None
+            assert client.initialize_result is None
+
+    async def test_auto_call_tool(self, fastmcp_server):
+        async with Client(fastmcp_server, mode="auto") as client:
+            result = await client.call_tool("add", {"a": 4, "b": 5})
+        assert result.data == 9
+
+    async def test_auto_falls_back_to_legacy_for_handshake_only_server(self):
+        """A server that only speaks the handshake era makes auto denylist-fall-back to
+        initialize, which still populates the InitializeResult.
+
+        FastMCP always serves both eras, so this is characterized against the
+        real dual-era server: auto reaches modern here. The fallback denylist
+        itself is exercised by the SDK's own ``negotiate_auto`` suite; this cell
+        documents the FastMCP-observable outcome.
+        """
+        mcp = FastMCP("both-eras")
+
+        @mcp.tool
+        def ping() -> str:
+            return "pong"
+
+        async with Client(mcp, mode="auto") as client:
+            assert client.protocol_version == LATEST_MODERN_VERSION
+
+
+class TestPinnedMode:
+    async def test_pinned_modern_adopts_without_probe(self, fastmcp_server):
+        """Pinning the modern version adopts it directly; a synthesized
+        DiscoverResult leaves server_info empty."""
+        async with Client(fastmcp_server, mode=LATEST_MODERN_VERSION) as client:
+            assert client.protocol_version == LATEST_MODERN_VERSION
+            assert client.initialize_result is None
+
+    async def test_pinned_modern_call_tool(self, fastmcp_server):
+        async with Client(fastmcp_server, mode=LATEST_MODERN_VERSION) as client:
+            result = await client.call_tool("add", {"a": 7, "b": 8})
+        assert result.data == 15
+
+
+class TestConnectionProperties:
+    async def test_properties_none_before_connect(self, fastmcp_server):
+        client = Client(fastmcp_server, mode="auto")
+        assert client.protocol_version is None
+        assert client.server_capabilities is None
+
+    async def test_properties_none_after_disconnect(self, fastmcp_server):
+        client = Client(fastmcp_server, mode="auto")
+        async with client:
+            assert client.protocol_version is not None
+        assert client.protocol_version is None
+        assert client.server_capabilities is None
+
+
+class TestManualNegotiation:
+    async def test_manual_initialize_legacy(self, fastmcp_server):
+        """auto_initialize=False + a manual initialize() still works in legacy mode."""
+        client = Client(fastmcp_server, mode="legacy", auto_initialize=False)
+        async with client:
+            assert client.protocol_version is None
+            result = await client.initialize()
+            assert result.server_info.name == "TestServer"
+            assert client.protocol_version == LATEST_HANDSHAKE_VERSION
+
+    async def test_initialize_raises_on_modern_era(self, fastmcp_server):
+        """A modern connection has no InitializeResult, so initialize() raises with a
+        pointer to the era-neutral properties."""
+        client = Client(fastmcp_server, mode="auto", auto_initialize=False)
+        async with client:
+            with pytest.raises(RuntimeError, match="modern protocol era"):
+                await client.initialize()
+            # Negotiation still happened; the era-neutral surface is populated.
+            assert client.protocol_version == LATEST_MODERN_VERSION
+
+
+class TestNewPreservesMode:
+    async def test_new_preserves_mode(self, fastmcp_server):
+        parent = Client(fastmcp_server, mode="auto")
+        child = parent.new()
+        assert child.mode == "auto"
+        async with child:
+            assert child.protocol_version == LATEST_MODERN_VERSION
diff --git a/tests/client/client/test_response_cache.py b/tests/client/client/test_response_cache.py
new file mode 100644
index 0000000..40f5831
--- /dev/null
+++ b/tests/client/client/test_response_cache.py
@@ -0,0 +1,178 @@
+"""Client-side response caching (SEP-2549) on ``fastmcp.Client`` (``cache=``).
+
+At 2026-07-28 a server may mark a cacheable list result with a `ttlMs` freshness
+hint; a client built with `cache=` serves subsequent identical calls from an
+in-process store until the hint expires or a server notification evicts the entry.
+
+The 2026 emitter is the SDK's `MCPServer` with `cache_hints=`, which stamps a
+positive `ttlMs` onto `tools/list`. It is driven through a `fastmcp.Client` with
+`mode="auto"` (negotiating 2026-07-28), so the cache coordinator runs entirely
+through FastMCP's client.
+
+Cache *honoring of server hints* is modern-only: a FastMCP or SDK server that
+emits `ttlMs: 0` (no hint) is never cached, and legacy connections never read the
+hint. That gating lives in the SDK's `ClientResponseCache`.
+"""
+
+from __future__ import annotations
+
+import mcp_types
+import pytest
+from mcp.client.caching import CacheConfig
+from mcp.server.caching import CacheHint
+from mcp.server.mcpserver import MCPServer
+
+from fastmcp import Client, FastMCP
+
+
+def _cached_server(ttl_ms: int = 60000) -> MCPServer:
+    """An SDK MCPServer whose tools/list carries a positive ttlMs hint at 2026."""
+    server = MCPServer(
+        "cached", cache_hints={"tools/list": CacheHint(ttl_ms=ttl_ms, scope="public")}
+    )
+
+    @server.tool()
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    return server
+
+
+class TestCacheConstruction:
+    def test_cache_none_is_disabled_by_default(self):
+        """Caching is opt-in: the default `cache=None` builds no cache, so a legacy
+        connection is byte-identical to pre-v4 behavior (no handler wrapping)."""
+        from fastmcp.client.tasks import TaskNotificationHandler
+
+        client = Client(FastMCP("x"))
+        assert client._response_cache is None
+        # The message handler is the bare default, not a cache-evicting wrapper.
+        assert isinstance(
+            client._session_kwargs["message_handler"], TaskNotificationHandler
+        )
+
+    def test_cache_true_builds_default(self):
+        client = Client(FastMCP("x"), cache=True)
+        assert client._response_cache is not None
+
+    def test_cache_false_disables(self):
+        client = Client(FastMCP("x"), cache=False)
+        assert client._response_cache is None
+
+    def test_cache_config_custom(self):
+        client = Client(FastMCP("x"), cache=CacheConfig(default_ttl_ms=1000))
+        assert client._response_cache is not None
+
+    def test_custom_store_requires_target_id(self):
+        """A custom shared store cannot derive an identity from a FastMCP transport."""
+        from mcp.client.caching import InMemoryResponseCacheStore
+
+        with pytest.raises(ValueError, match="requires CacheConfig.target_id"):
+            Client(
+                FastMCP("x"),
+                cache=CacheConfig(store=InMemoryResponseCacheStore(), partition="p"),
+            )
+
+
+class TestCacheServing:
+    async def test_second_list_tools_served_from_cache(self):
+        """A cached tools/list round-trip: the second call is served from the cache
+        without a second wire request."""
+        server = _cached_server()
+        async with Client(server, mode="auto", cache=True) as client:
+            # Confirm the server actually emits the freshness hint at 2026.
+            raw = await client.session.list_tools()
+            assert raw.ttl_ms == 60000
+
+            first = await client.list_tools()
+
+            calls = {"n": 0}
+            original = client.session.list_tools
+
+            async def spy(**kwargs):
+                calls["n"] += 1
+                return await original(**kwargs)
+
+            client.session.list_tools = spy  # type: ignore[method-assign]
+            second = await client.list_tools()
+
+        assert calls["n"] == 0  # served from cache, no wire round-trip
+        assert [t.name for t in first] == [t.name for t in second] == ["add"]
+
+    async def test_bypass_skips_cache(self):
+        """`cache_mode="bypass"` always reaches the server."""
+        server = _cached_server()
+        async with Client(server, mode="auto", cache=True) as client:
+            await client.list_tools_mcp()  # warm the cache
+
+            calls = {"n": 0}
+            original = client.session.list_tools
+
+            async def spy(**kwargs):
+                calls["n"] += 1
+                return await original(**kwargs)
+
+            client.session.list_tools = spy  # type: ignore[method-assign]
+            await client.list_tools_mcp(cache_mode="bypass")
+
+        assert calls["n"] == 1
+
+
+class TestCacheEviction:
+    async def test_tool_list_changed_evicts(self):
+        """A `notifications/tools/list_changed` routed through the composed message
+        handler evicts the cached tools/list entry."""
+        server = _cached_server()
+        async with Client(server, mode="auto", cache=True) as client:
+            await client.list_tools()
+            cache = client._response_cache
+            assert cache is not None
+            assert await cache.read("tools/list", "") is not None
+
+            # Drive the notification through the installed (cache-evicting) handler,
+            # which composes eviction over FastMCP's own message handler chain.
+            handler = client._session_kwargs["message_handler"]
+            assert handler is not None
+            await handler(
+                mcp_types.ToolListChangedNotification(
+                    method="notifications/tools/list_changed"
+                )
+            )
+
+            assert await cache.read("tools/list", "") is None
+
+
+class TestEraGating:
+    async def test_legacy_does_not_honor_server_hint(self):
+        """On a legacy connection the server hint is not read, so a hinted tools/list
+        is not served from cache (the entry is never stored under the hint)."""
+        server = _cached_server()
+        async with Client(server, mode="legacy", cache=True) as client:
+            await client.list_tools()
+            cache = client._response_cache
+            assert cache is not None
+            # No modern hint honored -> nothing cached under the modern arm.
+            assert await cache.read("tools/list", "") is None
+
+    async def test_zero_ttl_server_not_cached_on_modern(self):
+        """A modern server that emits `ttlMs: 0` (no hint) is not cached even though
+        the connection is modern."""
+        server = _cached_server(ttl_ms=0)
+        async with Client(server, mode="auto", cache=True) as client:
+            await client.list_tools()
+            cache = client._response_cache
+            assert cache is not None
+            assert await cache.read("tools/list", "") is None
+
+
+class TestNewIndependentCache:
+    async def test_new_gets_independent_cache(self):
+        """`new()` clones get their own cache, not the parent's entries."""
+        parent = Client(_cached_server(), mode="auto", cache=True)
+        child = parent.new()
+        assert child._response_cache is not None
+        assert child._response_cache is not parent._response_cache
+
+    async def test_new_disabled_cache_stays_disabled(self):
+        parent = Client(FastMCP("x"), cache=False)
+        assert parent.new()._response_cache is None
diff --git a/tests/client/client/test_session.py b/tests/client/client/test_session.py
new file mode 100644
index 0000000..66b38d7
--- /dev/null
+++ b/tests/client/client/test_session.py
@@ -0,0 +1,137 @@
+"""Client session and task error propagation tests."""
+
+import asyncio
+
+import pytest
+
+from fastmcp.client import Client
+
+
+class TestSessionTaskErrorPropagation:
+    """Tests for ensuring session task errors propagate to client calls.
+
+    Regression tests for https://github.com/PrefectHQ/fastmcp/issues/2595
+    where the client would hang indefinitely when the session task failed
+    (e.g., due to HTTP 4xx/5xx errors) instead of raising an exception.
+    """
+
+    async def test_session_task_error_propagates_to_call(self, fastmcp_server):
+        """Test that errors in session task propagate to pending client calls.
+
+        When the session task fails (e.g., due to HTTP errors), pending
+        client operations should immediately receive the exception rather
+        than hanging indefinitely.
+        """
+        client = Client(fastmcp_server)
+
+        async with client:
+            original_task = client._session_state.session_task
+            assert original_task is not None
+
+            async def never_complete():
+                """A coroutine that will never complete normally."""
+                await asyncio.sleep(1000)
+
+            async def failing_session():
+                """Simulates a session task that raises an error."""
+                raise ValueError("Simulated HTTP error")
+
+            # Replace session_task with one that will fail
+            client._session_state.session_task = asyncio.create_task(failing_session())
+
+            # The monitoring should detect the session task failure
+            with pytest.raises(ValueError, match="Simulated HTTP error"):
+                await client._await_with_session_monitoring(never_complete())
+
+            # Restore original task for cleanup
+            client._session_state.session_task = original_task
+
+    async def test_session_task_already_done_with_error(self, fastmcp_server):
+        """Test that if session task is already done with error, calls fail immediately."""
+        client = Client(fastmcp_server)
+
+        async with client:
+            original_task = client._session_state.session_task
+
+            async def raise_error():
+                raise ValueError("Session failed")
+
+            # Replace session_task with one that has already failed
+            failed_task = asyncio.create_task(raise_error())
+            try:
+                await failed_task
+            except ValueError:
+                pass  # Expected
+            client._session_state.session_task = failed_task
+
+            # New calls should fail immediately with the original error
+            async def simple_coro():
+                return "should not reach"
+
+            with pytest.raises(ValueError, match="Session failed"):
+                await client._await_with_session_monitoring(simple_coro())
+
+            # Restore original task for cleanup
+            client._session_state.session_task = original_task
+
+    async def test_session_task_already_done_no_error_raises_runtime_error(
+        self, fastmcp_server
+    ):
+        """Test that if session task completes without error, raises RuntimeError."""
+        client = Client(fastmcp_server)
+
+        async with client:
+            original_task = client._session_state.session_task
+
+            # Create a task that completes normally (unexpected for session task)
+            completed_task = asyncio.create_task(asyncio.sleep(0))
+            await completed_task
+            client._session_state.session_task = completed_task
+
+            async def simple_coro():
+                return "should not reach"
+
+            with pytest.raises(
+                RuntimeError, match="Session task completed unexpectedly"
+            ):
+                await client._await_with_session_monitoring(simple_coro())
+
+            # Restore original task for cleanup
+            client._session_state.session_task = original_task
+
+    async def test_normal_operation_unaffected(self, fastmcp_server):
+        """Test that normal operation is unaffected by the monitoring."""
+        client = Client(fastmcp_server)
+
+        async with client:
+            # These should all work normally
+            tools = await client.list_tools()
+            assert len(tools) > 0
+
+            result = await client.call_tool("greet", {"name": "Test"})
+            assert "Hello, Test!" in str(result.content)
+
+            resources = await client.list_resources()
+            assert len(resources) > 0
+
+            prompts = await client.list_prompts()
+            assert len(prompts) > 0
+
+    async def test_no_session_task_falls_back_to_direct_await(self, fastmcp_server):
+        """Test that when no session task exists, it falls back to direct await."""
+        client = Client(fastmcp_server)
+
+        async with client:
+            # Temporarily remove session_task to test fallback
+            original_task = client._session_state.session_task
+            client._session_state.session_task = None
+
+            # Should work via direct await
+            async def simple_coro():
+                return "success"
+
+            result = await client._await_with_session_monitoring(simple_coro())
+            assert result == "success"
+
+            # Restore for cleanup
+            client._session_state.session_task = original_task
diff --git a/tests/client/client/test_timeout.py b/tests/client/client/test_timeout.py
new file mode 100644
index 0000000..d770aa0
--- /dev/null
+++ b/tests/client/client/test_timeout.py
@@ -0,0 +1,44 @@
+"""Client timeout tests."""
+
+import pytest
+from mcp import MCPError
+
+from fastmcp.client import Client
+from fastmcp.client.transports import FastMCPTransport
+from fastmcp.server.server import FastMCP
+
+
+class TestTimeout:
+    async def test_timeout(self, fastmcp_server: FastMCP):
+        async with Client(
+            transport=FastMCPTransport(fastmcp_server), timeout=0.05
+        ) as client:
+            with pytest.raises(
+                MCPError,
+                match="timed out",
+            ):
+                await client.call_tool("sleep", {"seconds": 0.1})
+
+    async def test_timeout_tool_call(self, fastmcp_server: FastMCP):
+        async with Client(transport=FastMCPTransport(fastmcp_server)) as client:
+            with pytest.raises(MCPError):
+                await client.call_tool("sleep", {"seconds": 0.1}, timeout=0.01)
+
+    async def test_timeout_tool_call_overrides_client_timeout(
+        self, fastmcp_server: FastMCP
+    ):
+        async with Client(
+            transport=FastMCPTransport(fastmcp_server),
+            timeout=2,
+        ) as client:
+            with pytest.raises(MCPError):
+                await client.call_tool("sleep", {"seconds": 0.1}, timeout=0.01)
+
+    async def test_timeout_tool_call_overrides_client_timeout_even_if_lower(
+        self, fastmcp_server: FastMCP
+    ):
+        async with Client(
+            transport=FastMCPTransport(fastmcp_server),
+            timeout=0.1,
+        ) as client:
+            await client.call_tool("sleep", {"seconds": 0.5}, timeout=2)
diff --git a/tests/client/client/test_transport.py b/tests/client/client/test_transport.py
new file mode 100644
index 0000000..d0d80f7
--- /dev/null
+++ b/tests/client/client/test_transport.py
@@ -0,0 +1,137 @@
+"""Client transport inference tests."""
+
+import pytest
+
+from fastmcp.client.transports import (
+    FastMCPTransport,
+    MCPConfigTransport,
+    SSETransport,
+    StdioTransport,
+    StreamableHttpTransport,
+    infer_transport,
+)
+
+
+class TestInferTransport:
+    """Tests for the infer_transport function."""
+
+    @pytest.mark.parametrize(
+        "url",
+        [
+            "http://example.com/api/sse/stream",
+            "https://localhost:8080/mcp/sse/endpoint",
+            "http://example.com/api/sse",
+            "http://example.com/api/sse/",
+            "https://localhost:8080/mcp/sse/",
+            "http://example.com/api/sse?param=value",
+            "https://localhost:8080/mcp/sse/?param=value",
+            "https://localhost:8000/mcp/sse?x=1&y=2",
+        ],
+        ids=[
+            "path_with_sse_directory",
+            "path_with_sse_subdirectory",
+            "path_ending_with_sse",
+            "path_ending_with_sse_slash",
+            "path_ending_with_sse_https",
+            "path_with_sse_and_query_params",
+            "path_with_sse_slash_and_query_params",
+            "path_with_sse_and_ampersand_param",
+        ],
+    )
+    def test_url_returns_sse_transport(self, url):
+        """Test that URLs with /sse/ pattern return SSETransport."""
+        assert isinstance(infer_transport(url), SSETransport)
+
+    @pytest.mark.parametrize(
+        "url",
+        [
+            "http://example.com/api",
+            "https://localhost:8080/mcp/",
+            "http://example.com/asset/image.jpg",
+            "https://localhost:8080/sservice/endpoint",
+            "https://example.com/assets/file",
+        ],
+        ids=[
+            "regular_http_url",
+            "regular_https_url",
+            "url_with_unrelated_path",
+            "url_with_sservice_in_path",
+            "url_with_assets_in_path",
+        ],
+    )
+    def test_url_returns_streamable_http_transport(self, url):
+        """Test that URLs without /sse/ pattern return StreamableHttpTransport."""
+        assert isinstance(infer_transport(url), StreamableHttpTransport)
+
+    def test_infer_remote_transport_from_config(self):
+        config = {
+            "mcpServers": {
+                "test_server": {
+                    "url": "http://localhost:8000/sse/",
+                    "headers": {"Authorization": "Bearer 123"},
+                },
+            }
+        }
+        transport = infer_transport(config)
+        assert isinstance(transport, MCPConfigTransport)
+        assert isinstance(transport.transport, SSETransport)
+        assert transport.transport.url == "http://localhost:8000/sse/"
+        assert transport.transport.headers == {"Authorization": "Bearer 123"}
+
+    def test_infer_local_transport_from_config(self):
+        config = {
+            "mcpServers": {
+                "test_server": {
+                    "command": "echo",
+                    "args": ["hello"],
+                },
+            }
+        }
+        transport = infer_transport(config)
+        assert isinstance(transport, MCPConfigTransport)
+        assert isinstance(transport.transport, StdioTransport)
+        assert transport.transport.command == "echo"
+        assert transport.transport.args == ["hello"]
+
+    def test_config_with_no_servers(self):
+        """Test that an empty MCPConfig raises a ValueError."""
+        config = {"mcpServers": {}}
+        with pytest.raises(ValueError, match="No MCP servers defined in the config"):
+            infer_transport(config)
+
+    def test_mcpconfigtransport_with_no_servers(self):
+        """Test that MCPConfigTransport raises a ValueError when initialized with an empty config."""
+        config = {"mcpServers": {}}
+        with pytest.raises(ValueError, match="No MCP servers defined in the config"):
+            MCPConfigTransport(config=config)
+
+    def test_infer_composite_client(self):
+        config = {
+            "mcpServers": {
+                "local": {
+                    "command": "echo",
+                    "args": ["hello"],
+                },
+                "remote": {
+                    "url": "http://localhost:8000/sse/",
+                    "headers": {"Authorization": "Bearer 123"},
+                },
+            }
+        }
+        transport = infer_transport(config)
+        assert isinstance(transport, MCPConfigTransport)
+        # Multi-server configs create composite server at connect time
+        assert len(transport.config.mcpServers) == 2
+
+    def test_infer_fastmcp_server(self, fastmcp_server):
+        """FastMCP server instances should infer to FastMCPTransport."""
+        transport = infer_transport(fastmcp_server)
+        assert isinstance(transport, FastMCPTransport)
+
+    def test_infer_fastmcp_v1_server(self):
+        """FastMCP 1.0 server instances should infer to FastMCPTransport."""
+        from mcp.server.mcpserver import MCPServer as FastMCP1
+
+        server = FastMCP1()
+        transport = infer_transport(server)
+        assert isinstance(transport, FastMCPTransport)
diff --git a/tests/client/sampling/__init__.py b/tests/client/sampling/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/client/sampling/handlers/__init__.py b/tests/client/sampling/handlers/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/client/sampling/handlers/test_anthropic_handler.py b/tests/client/sampling/handlers/test_anthropic_handler.py
new file mode 100644
index 0000000..229a1c0
--- /dev/null
+++ b/tests/client/sampling/handlers/test_anthropic_handler.py
@@ -0,0 +1,401 @@
+from typing import Any
+from unittest.mock import MagicMock
+
+import pytest
+from anthropic import AsyncAnthropic
+from anthropic.types import Message, TextBlock, ToolUseBlock, Usage
+from mcp_types import (
+    AudioContent,
+    CreateMessageResult,
+    CreateMessageResultWithTools,
+    EmbeddedResource,
+    ImageContent,
+    ModelHint,
+    ModelPreferences,
+    SamplingMessage,
+    TextContent,
+    TextResourceContents,
+    ToolResultContent,
+    ToolUseContent,
+)
+
+from fastmcp.client.sampling.handlers.anthropic import (
+    AnthropicSamplingHandler,
+    _image_content_to_anthropic_block,
+)
+
+
+def test_convert_sampling_messages_to_anthropic_messages():
+    msgs = AnthropicSamplingHandler._convert_to_anthropic_messages(
+        messages=[
+            SamplingMessage(
+                role="user", content=TextContent(type="text", text="hello")
+            ),
+            SamplingMessage(
+                role="assistant", content=TextContent(type="text", text="ok")
+            ),
+        ],
+    )
+
+    assert msgs == [
+        {"role": "user", "content": "hello"},
+        {"role": "assistant", "content": "ok"},
+    ]
+
+
+def test_image_content_to_anthropic_block():
+    block = _image_content_to_anthropic_block(
+        ImageContent(type="image", data="YWJj", mime_type="image/png")
+    )
+
+    assert block == {
+        "type": "image",
+        "source": {
+            "type": "base64",
+            "media_type": "image/png",
+            "data": "YWJj",
+        },
+    }
+
+
+def test_image_content_unsupported_mime_type_raises():
+    with pytest.raises(ValueError, match="Unsupported image MIME type"):
+        _image_content_to_anthropic_block(
+            ImageContent(type="image", data="YWJj", mime_type="image/bmp")
+        )
+
+
+def test_convert_single_image_content_to_anthropic_message():
+    msgs = AnthropicSamplingHandler._convert_to_anthropic_messages(
+        messages=[
+            SamplingMessage(
+                role="user",
+                content=ImageContent(type="image", data="YWJj", mime_type="image/png"),
+            )
+        ],
+    )
+
+    assert len(msgs) == 1
+    assert msgs[0] == {
+        "role": "user",
+        "content": [
+            {
+                "type": "image",
+                "source": {
+                    "type": "base64",
+                    "media_type": "image/png",
+                    "data": "YWJj",
+                },
+            }
+        ],
+    }
+
+
+def test_convert_single_audio_content_raises():
+    with pytest.raises(ValueError, match="AudioContent is not supported"):
+        AnthropicSamplingHandler._convert_to_anthropic_messages(
+            messages=[
+                SamplingMessage(
+                    role="user",
+                    content=AudioContent(
+                        type="audio", data="YWJj", mime_type="audio/wav"
+                    ),
+                )
+            ],
+        )
+
+
+def test_convert_list_content_with_image_and_text():
+    msgs = AnthropicSamplingHandler._convert_to_anthropic_messages(
+        messages=[
+            SamplingMessage(
+                role="user",
+                content=[
+                    TextContent(type="text", text="Describe this image"),
+                    ImageContent(type="image", data="YWJj", mime_type="image/jpeg"),
+                ],
+            )
+        ],
+    )
+
+    assert len(msgs) == 1
+    assert msgs[0] == {
+        "role": "user",
+        "content": [
+            {"type": "text", "text": "Describe this image"},
+            {
+                "type": "image",
+                "source": {
+                    "type": "base64",
+                    "media_type": "image/jpeg",
+                    "data": "YWJj",
+                },
+            },
+        ],
+    }
+
+
+def test_convert_list_content_with_audio_raises():
+    with pytest.raises(ValueError, match="AudioContent is not supported"):
+        AnthropicSamplingHandler._convert_to_anthropic_messages(
+            messages=[
+                SamplingMessage(
+                    role="user",
+                    content=[
+                        TextContent(type="text", text="Listen to this"),
+                        AudioContent(type="audio", data="YWJj", mime_type="audio/wav"),
+                    ],
+                )
+            ],
+        )
+
+
+def test_convert_image_in_assistant_message_raises():
+    with pytest.raises(ValueError, match="ImageContent is only supported in user"):
+        AnthropicSamplingHandler._convert_to_anthropic_messages(
+            messages=[
+                SamplingMessage(
+                    role="assistant",
+                    content=ImageContent(
+                        type="image", data="YWJj", mime_type="image/png"
+                    ),
+                )
+            ],
+        )
+
+
+def test_convert_list_image_in_assistant_message_raises():
+    with pytest.raises(ValueError, match="ImageContent is only supported in user"):
+        AnthropicSamplingHandler._convert_to_anthropic_messages(
+            messages=[
+                SamplingMessage(
+                    role="assistant",
+                    content=[
+                        TextContent(type="text", text="Here's the image"),
+                        ImageContent(type="image", data="YWJj", mime_type="image/png"),
+                    ],
+                )
+            ],
+        )
+
+
+@pytest.mark.parametrize(
+    "prefs,expected",
+    [
+        ("claude-3-5-sonnet-20241022", "claude-3-5-sonnet-20241022"),
+        (
+            ModelPreferences(hints=[ModelHint(name="claude-3-5-sonnet-20241022")]),
+            "claude-3-5-sonnet-20241022",
+        ),
+        (["claude-3-5-sonnet-20241022", "other"], "claude-3-5-sonnet-20241022"),
+        (None, "fallback-model"),
+        (["unknown-model"], "fallback-model"),
+    ],
+)
+def test_select_model_from_preferences(prefs: Any, expected: str) -> None:
+    mock_client = MagicMock(spec=AsyncAnthropic)
+    handler = AnthropicSamplingHandler(
+        default_model="fallback-model", client=mock_client
+    )
+    assert handler._select_model_from_preferences(prefs) == expected
+
+
+def test_message_to_create_message_result():
+    mock_client = MagicMock(spec=AsyncAnthropic)
+    handler = AnthropicSamplingHandler(
+        default_model="fallback-model", client=mock_client
+    )
+
+    message = Message(
+        id="msg_123",
+        type="message",
+        role="assistant",
+        content=[TextBlock(type="text", text="HELPFUL CONTENT FROM A VERY SMART LLM")],
+        model="claude-3-5-sonnet-20241022",
+        stop_reason="end_turn",
+        stop_sequence=None,
+        usage=Usage(input_tokens=10, output_tokens=20),
+    )
+
+    result: CreateMessageResult = handler._message_to_create_message_result(message)
+    assert result == CreateMessageResult(
+        content=TextContent(type="text", text="HELPFUL CONTENT FROM A VERY SMART LLM"),
+        role="assistant",
+        model="claude-3-5-sonnet-20241022",
+    )
+
+
+def test_message_to_result_with_tools():
+    message = Message(
+        id="msg_123",
+        type="message",
+        role="assistant",
+        content=[
+            TextBlock(type="text", text="I'll help you with that."),
+            ToolUseBlock(
+                type="tool_use",
+                id="toolu_123",
+                name="get_weather",
+                input={"location": "San Francisco"},
+            ),
+        ],
+        model="claude-3-5-sonnet-20241022",
+        stop_reason="tool_use",
+        stop_sequence=None,
+        usage=Usage(input_tokens=10, output_tokens=20),
+    )
+
+    result: CreateMessageResultWithTools = (
+        AnthropicSamplingHandler._message_to_result_with_tools(message)
+    )
+
+    assert result.role == "assistant"
+    assert result.model == "claude-3-5-sonnet-20241022"
+    assert result.stop_reason == "toolUse"
+    content = result.content_as_list
+    assert len(content) == 2
+    assert content[0] == TextContent(type="text", text="I'll help you with that.")
+    assert content[1] == ToolUseContent(
+        type="tool_use",
+        id="toolu_123",
+        name="get_weather",
+        input={"location": "San Francisco"},
+    )
+
+
+def test_convert_tool_choice_auto():
+    result = AnthropicSamplingHandler._convert_tool_choice_to_anthropic(
+        MagicMock(mode="auto")
+    )
+    assert result is not None
+    assert result["type"] == "auto"
+
+
+def test_convert_tool_choice_required():
+    result = AnthropicSamplingHandler._convert_tool_choice_to_anthropic(
+        MagicMock(mode="required")
+    )
+    assert result is not None
+    assert result["type"] == "any"
+
+
+def test_convert_tool_choice_none():
+    result = AnthropicSamplingHandler._convert_tool_choice_to_anthropic(
+        MagicMock(mode="none")
+    )
+    # Anthropic doesn't have "none", returns None to signal tools should be omitted
+    assert result is None
+
+
+def test_convert_tool_choice_unknown_raises():
+    with pytest.raises(ValueError, match="Unsupported tool_choice mode"):
+        AnthropicSamplingHandler._convert_tool_choice_to_anthropic(
+            MagicMock(mode="unknown")
+        )
+
+
+def test_convert_tools_to_anthropic():
+    from mcp_types import Tool
+
+    tools = [
+        Tool(
+            name="get_weather",
+            description="Get the current weather",
+            input_schema={
+                "type": "object",
+                "properties": {"location": {"type": "string"}},
+                "required": ["location"],
+            },
+        )
+    ]
+
+    result = AnthropicSamplingHandler._convert_tools_to_anthropic(tools)
+
+    assert len(result) == 1
+    assert result[0]["name"] == "get_weather"
+    assert result[0]["description"] == "Get the current weather"
+    assert result[0]["input_schema"] == {
+        "type": "object",
+        "properties": {"location": {"type": "string"}},
+        "required": ["location"],
+    }
+
+
+def test_convert_messages_with_tool_use_content():
+    """Test converting messages that include tool use content from assistant."""
+    msgs = AnthropicSamplingHandler._convert_to_anthropic_messages(
+        messages=[
+            SamplingMessage(
+                role="assistant",
+                content=ToolUseContent(
+                    type="tool_use",
+                    id="toolu_123",
+                    name="get_weather",
+                    input={"location": "NYC"},
+                ),
+            ),
+        ],
+    )
+
+    assert len(msgs) == 1
+    assert msgs[0]["role"] == "assistant"
+    assert msgs[0]["content"] == [
+        {
+            "type": "tool_use",
+            "id": "toolu_123",
+            "name": "get_weather",
+            "input": {"location": "NYC"},
+        }
+    ]
+
+
+def test_convert_messages_with_tool_result_content():
+    """Test converting messages that include tool result content from user."""
+    msgs = AnthropicSamplingHandler._convert_to_anthropic_messages(
+        messages=[
+            SamplingMessage(
+                role="user",
+                content=ToolResultContent(
+                    type="tool_result",
+                    tool_use_id="toolu_123",
+                    content=[TextContent(type="text", text="72F and sunny")],
+                ),
+            ),
+        ],
+    )
+
+    assert len(msgs) == 1
+    assert msgs[0]["role"] == "user"
+    assert msgs[0]["content"] == [
+        {
+            "type": "tool_result",
+            "tool_use_id": "toolu_123",
+            "content": "72F and sunny",
+            "is_error": False,
+        }
+    ]
+
+
+def test_convert_messages_raises_on_unsupported_content_type():
+    """Unsupported content types should raise ValueError.
+
+    SamplingMessage validates content against a union of known types, so
+    we use model_construct to bypass validation and simulate a future
+    SDK content type that the handler doesn't know about yet.
+    """
+    embedded = EmbeddedResource(
+        type="resource",
+        resource=TextResourceContents(
+            uri="file:///test.txt", text="hello", mime_type="text/plain"
+        ),
+    )
+    # Must be inside a list content — single-content messages hit a
+    # different check.  Use model_construct to bypass Pydantic's
+    # union validation (EmbeddedResource is not in the content union).
+    msg = SamplingMessage.model_construct(
+        role="user",
+        content=[TextContent(type="text", text="prefix"), embedded],
+    )
+
+    with pytest.raises(ValueError, match="Unsupported content type for Anthropic"):
+        AnthropicSamplingHandler._convert_to_anthropic_messages([msg])
diff --git a/tests/client/sampling/handlers/test_google_genai_handler.py b/tests/client/sampling/handlers/test_google_genai_handler.py
new file mode 100644
index 0000000..dd610c9
--- /dev/null
+++ b/tests/client/sampling/handlers/test_google_genai_handler.py
@@ -0,0 +1,601 @@
+import base64
+from unittest.mock import MagicMock
+
+import pytest
+
+try:
+    from google.genai import Client as GoogleGenaiClient
+    from google.genai.types import (
+        Candidate,
+        FunctionCall,
+        FunctionCallingConfigMode,
+        GenerateContentResponse,
+        ModelContent,
+        Part,
+        UserContent,
+    )
+    from mcp_types import (
+        AudioContent,
+        CreateMessageResult,
+        ImageContent,
+        ModelHint,
+        ModelPreferences,
+        SamplingMessage,
+        TextContent,
+        ToolChoice,
+        ToolResultContent,
+        ToolUseContent,
+    )
+
+    from fastmcp.client.sampling.handlers.google_genai import (
+        GoogleGenaiSamplingHandler,
+        _convert_messages_to_google_genai_content,
+        _convert_tool_choice_to_google_genai,
+        _response_to_create_message_result,
+        _response_to_result_with_tools,
+        _sampling_content_to_google_genai_part,
+    )
+
+    GOOGLE_GENAI_AVAILABLE = True
+except ImportError:
+    GOOGLE_GENAI_AVAILABLE = False
+
+pytestmark = pytest.mark.skipif(
+    not GOOGLE_GENAI_AVAILABLE, reason="google-genai not installed"
+)
+
+
+def test_convert_sampling_messages_to_google_genai_content():
+    msgs = _convert_messages_to_google_genai_content(
+        messages=[
+            SamplingMessage(
+                role="user", content=TextContent(type="text", text="hello")
+            ),
+            SamplingMessage(
+                role="assistant", content=TextContent(type="text", text="ok")
+            ),
+        ],
+    )
+
+    assert len(msgs) == 2
+    assert isinstance(msgs[0], UserContent)
+    assert isinstance(msgs[1], ModelContent)
+    assert msgs[0].parts[0].text == "hello"
+    assert msgs[1].parts[0].text == "ok"
+
+
+def test_convert_single_image_content_to_google_genai():
+    part = _sampling_content_to_google_genai_part(
+        ImageContent(type="image", data="YWJj", mime_type="image/png")
+    )
+
+    assert part.inline_data is not None
+    assert part.inline_data.data == base64.b64decode("YWJj")
+    assert part.inline_data.mime_type == "image/png"
+
+
+def test_convert_single_audio_content_to_google_genai():
+    part = _sampling_content_to_google_genai_part(
+        AudioContent(type="audio", data="YWJj", mime_type="audio/wav")
+    )
+
+    assert part.inline_data is not None
+    assert part.inline_data.data == base64.b64decode("YWJj")
+    assert part.inline_data.mime_type == "audio/wav"
+
+
+def test_convert_image_message_to_google_genai_content():
+    msgs = _convert_messages_to_google_genai_content(
+        messages=[
+            SamplingMessage(
+                role="user",
+                content=ImageContent(type="image", data="YWJj", mime_type="image/jpeg"),
+            )
+        ],
+    )
+
+    assert len(msgs) == 1
+    assert isinstance(msgs[0], UserContent)
+    assert msgs[0].parts[0].inline_data is not None
+    assert msgs[0].parts[0].inline_data.mime_type == "image/jpeg"
+
+
+def test_convert_audio_message_to_google_genai_content():
+    msgs = _convert_messages_to_google_genai_content(
+        messages=[
+            SamplingMessage(
+                role="user",
+                content=AudioContent(type="audio", data="YWJj", mime_type="audio/mp3"),
+            )
+        ],
+    )
+
+    assert len(msgs) == 1
+    assert isinstance(msgs[0], UserContent)
+    assert msgs[0].parts[0].inline_data is not None
+    assert msgs[0].parts[0].inline_data.mime_type == "audio/mp3"
+
+
+def test_convert_list_content_with_image_and_text():
+    msgs = _convert_messages_to_google_genai_content(
+        messages=[
+            SamplingMessage(
+                role="user",
+                content=[
+                    TextContent(type="text", text="What is in this image?"),
+                    ImageContent(type="image", data="YWJj", mime_type="image/png"),
+                ],
+            )
+        ],
+    )
+
+    assert len(msgs) == 1
+    assert isinstance(msgs[0], UserContent)
+    assert len(msgs[0].parts) == 2
+    assert msgs[0].parts[0].text == "What is in this image?"
+    assert msgs[0].parts[1].inline_data is not None
+    assert msgs[0].parts[1].inline_data.mime_type == "image/png"
+
+
+def test_convert_list_content_with_audio_and_text():
+    msgs = _convert_messages_to_google_genai_content(
+        messages=[
+            SamplingMessage(
+                role="user",
+                content=[
+                    TextContent(type="text", text="Transcribe this audio"),
+                    AudioContent(type="audio", data="YWJj", mime_type="audio/wav"),
+                ],
+            )
+        ],
+    )
+
+    assert len(msgs) == 1
+    assert isinstance(msgs[0], UserContent)
+    assert len(msgs[0].parts) == 2
+    assert msgs[0].parts[0].text == "Transcribe this audio"
+    assert msgs[0].parts[1].inline_data is not None
+    assert msgs[0].parts[1].inline_data.mime_type == "audio/wav"
+
+
+def test_get_model():
+    mock_client = MagicMock(spec=GoogleGenaiClient)
+    handler = GoogleGenaiSamplingHandler(
+        default_model="fallback-model", client=mock_client
+    )
+
+    # Test with Gemini model hint
+    prefs = ModelPreferences(hints=[ModelHint(name="gemini-2.0-flash-exp")])
+    assert handler._get_model(prefs) == "gemini-2.0-flash-exp"
+
+    # Test with None
+    assert handler._get_model(None) == "fallback-model"
+
+    # Test with empty hints
+    prefs_empty = ModelPreferences(hints=[])
+    assert handler._get_model(prefs_empty) == "fallback-model"
+
+    # Test with non-Gemini hint falls back to default
+    prefs_other = ModelPreferences(hints=[ModelHint(name="gpt-4o")])
+    assert handler._get_model(prefs_other) == "fallback-model"
+
+    # Test with mixed hints selects first Gemini model
+    prefs_mixed = ModelPreferences(
+        hints=[ModelHint(name="claude-3.5-sonnet"), ModelHint(name="gemini-2.0-flash")]
+    )
+    assert handler._get_model(prefs_mixed) == "gemini-2.0-flash"
+
+
+async def test_response_to_create_message_result():
+    # Create a mock response
+    mock_response = MagicMock(spec=GenerateContentResponse)
+    mock_response.text = "HELPFUL CONTENT FROM GEMINI"
+
+    result: CreateMessageResult = _response_to_create_message_result(
+        response=mock_response, model="gemini-2.0-flash-exp"
+    )
+    assert result == CreateMessageResult(
+        content=TextContent(type="text", text="HELPFUL CONTENT FROM GEMINI"),
+        role="assistant",
+        model="gemini-2.0-flash-exp",
+    )
+
+
+def test_convert_tool_choice_to_google_genai():
+    # Test auto mode
+    result = _convert_tool_choice_to_google_genai(ToolChoice(mode="auto"))
+    assert result.function_calling_config is not None
+    assert result.function_calling_config.mode == FunctionCallingConfigMode.AUTO
+
+    # Test required mode
+    result = _convert_tool_choice_to_google_genai(ToolChoice(mode="required"))
+    assert result.function_calling_config is not None
+    assert result.function_calling_config.mode == FunctionCallingConfigMode.ANY
+
+    # Test none mode
+    result = _convert_tool_choice_to_google_genai(ToolChoice(mode="none"))
+    assert result.function_calling_config is not None
+    assert result.function_calling_config.mode == FunctionCallingConfigMode.NONE
+
+    # Test None (defaults to auto)
+    result = _convert_tool_choice_to_google_genai(None)
+    assert result.function_calling_config is not None
+    assert result.function_calling_config.mode == FunctionCallingConfigMode.AUTO
+
+
+def test_sampling_content_to_google_genai_part_tool_use():
+    """Test converting ToolUseContent to Google GenAI Part with FunctionCall."""
+    content = ToolUseContent(
+        type="tool_use",
+        id="get_weather_abc123",
+        name="get_weather",
+        input={"city": "London"},
+    )
+
+    part = _sampling_content_to_google_genai_part(content)
+
+    assert part.function_call is not None
+    assert part.function_call.name == "get_weather"
+    assert part.function_call.args == {"city": "London"}
+
+
+def test_sampling_content_to_google_genai_part_tool_result():
+    """Test converting ToolResultContent to Google GenAI Part with FunctionResponse."""
+    content = ToolResultContent(
+        type="tool_result",
+        tool_use_id="get_weather_abc123",
+        content=[TextContent(type="text", text="Weather is sunny")],
+    )
+
+    part = _sampling_content_to_google_genai_part(content)
+
+    assert part.function_response is not None
+    # Function name is extracted from toolUseId by removing the UUID suffix
+    assert part.function_response.name == "get_weather"
+    assert part.function_response.response == {"result": "Weather is sunny"}
+
+
+def test_sampling_content_to_google_genai_part_tool_result_empty():
+    """Test converting empty ToolResultContent to Google GenAI Part."""
+    content = ToolResultContent(
+        type="tool_result",
+        tool_use_id="my_tool_xyz789",
+        content=[],
+    )
+
+    part = _sampling_content_to_google_genai_part(content)
+
+    assert part.function_response is not None
+    assert part.function_response.name == "my_tool"
+    assert part.function_response.response == {"result": ""}
+
+
+def test_sampling_content_to_google_genai_part_tool_result_no_underscore():
+    """Test ToolResultContent when toolUseId has no underscore (fallback)."""
+    content = ToolResultContent(
+        type="tool_result",
+        tool_use_id="simplefunction",
+        content=[TextContent(type="text", text="Result")],
+    )
+
+    part = _sampling_content_to_google_genai_part(content)
+
+    # When no underscore, the full ID is used as the name
+    assert part.function_response is not None
+    assert part.function_response.name == "simplefunction"
+
+
+def test_convert_messages_with_tool_use():
+    """Test converting messages containing ToolUseContent."""
+    msgs = _convert_messages_to_google_genai_content(
+        messages=[
+            SamplingMessage(
+                role="user",
+                content=TextContent(type="text", text="What's the weather?"),
+            ),
+            SamplingMessage(
+                role="assistant",
+                content=ToolUseContent(
+                    type="tool_use",
+                    id="get_weather_123",
+                    name="get_weather",
+                    input={"city": "NYC"},
+                ),
+            ),
+        ],
+    )
+
+    assert len(msgs) == 2
+    assert isinstance(msgs[0], UserContent)
+    assert isinstance(msgs[1], ModelContent)
+    assert msgs[1].parts[0].function_call is not None
+    assert msgs[1].parts[0].function_call.name == "get_weather"
+
+
+def test_convert_messages_with_tool_result():
+    """Test converting messages containing ToolResultContent."""
+    msgs = _convert_messages_to_google_genai_content(
+        messages=[
+            SamplingMessage(
+                role="user",
+                content=ToolResultContent(
+                    type="tool_result",
+                    tool_use_id="get_weather_123",
+                    content=[TextContent(type="text", text="Sunny, 72F")],
+                ),
+            ),
+        ],
+    )
+
+    assert len(msgs) == 1
+    assert isinstance(msgs[0], UserContent)
+    assert msgs[0].parts[0].function_response is not None
+    assert msgs[0].parts[0].function_response.name == "get_weather"
+
+
+def test_convert_messages_with_multiple_content_blocks():
+    """Test converting messages with multiple content blocks (list content)."""
+    msgs = _convert_messages_to_google_genai_content(
+        messages=[
+            SamplingMessage(
+                role="user",
+                content=[
+                    TextContent(type="text", text="I need weather info."),
+                    ToolResultContent(
+                        type="tool_result",
+                        tool_use_id="get_weather_xyz",
+                        content=[TextContent(type="text", text="Cloudy")],
+                    ),
+                ],
+            ),
+        ],
+    )
+
+    assert len(msgs) == 1
+    assert isinstance(msgs[0], UserContent)
+    assert len(msgs[0].parts) == 2
+    assert msgs[0].parts[0].text == "I need weather info."
+    assert msgs[0].parts[1].function_response is not None
+
+
+def test_response_to_result_with_tools_text_only():
+    """Test _response_to_result_with_tools with a text-only response."""
+    mock_candidate = MagicMock(spec=Candidate)
+    mock_candidate.content = MagicMock()
+    mock_candidate.content.parts = [Part(text="Here's the answer")]
+    mock_candidate.finish_reason = "STOP"
+
+    mock_response = MagicMock(spec=GenerateContentResponse)
+    mock_response.candidates = [mock_candidate]
+
+    result = _response_to_result_with_tools(mock_response, model="gemini-2.0-flash")
+
+    assert result.role == "assistant"
+    assert result.model == "gemini-2.0-flash"
+    assert result.stop_reason == "endTurn"
+    assert isinstance(result.content, list)
+    assert len(result.content) == 1
+    assert result.content[0].type == "text"
+    assert isinstance(result.content[0], TextContent)
+    assert result.content[0].text == "Here's the answer"
+
+
+def test_response_to_result_with_tools_function_call():
+    """Test _response_to_result_with_tools with a function call response."""
+    mock_candidate = MagicMock(spec=Candidate)
+    mock_candidate.content = MagicMock()
+    mock_candidate.content.parts = [
+        Part(function_call=FunctionCall(name="get_weather", args={"city": "Paris"}))
+    ]
+    mock_candidate.finish_reason = "STOP"
+
+    mock_response = MagicMock(spec=GenerateContentResponse)
+    mock_response.candidates = [mock_candidate]
+
+    result = _response_to_result_with_tools(mock_response, model="gemini-2.0-flash")
+
+    assert result.stop_reason == "toolUse"
+    assert isinstance(result.content, list)
+    assert len(result.content) == 1
+    tool_use = result.content[0]
+    assert isinstance(tool_use, ToolUseContent)
+    assert tool_use.type == "tool_use"
+    assert tool_use.name == "get_weather"
+    assert tool_use.input == {"city": "Paris"}
+    # ID should be in format "get_weather_{uuid}"
+    assert tool_use.id.startswith("get_weather_")
+
+
+def test_response_to_result_with_tools_mixed_content():
+    """Test _response_to_result_with_tools with text and function call."""
+    mock_candidate = MagicMock(spec=Candidate)
+    mock_candidate.content = MagicMock()
+    mock_candidate.content.parts = [
+        Part(text="Let me check that for you."),
+        Part(function_call=FunctionCall(name="search", args={"query": "test"})),
+    ]
+    mock_candidate.finish_reason = "STOP"
+
+    mock_response = MagicMock(spec=GenerateContentResponse)
+    mock_response.candidates = [mock_candidate]
+
+    result = _response_to_result_with_tools(mock_response, model="gemini-2.0-flash")
+
+    assert result.stop_reason == "toolUse"
+    assert isinstance(result.content, list)
+    assert len(result.content) == 2
+    text_content = result.content[0]
+    assert isinstance(text_content, TextContent)
+    assert text_content.type == "text"
+    assert text_content.text == "Let me check that for you."
+    tool_use = result.content[1]
+    assert isinstance(tool_use, ToolUseContent)
+    assert tool_use.type == "tool_use"
+    assert tool_use.name == "search"
+
+
+# ────────────────────────────────────────────────────────────
+# Test for title stripping (PR #3860)
+# ────────────────────────────────────────────────────────────
+
+
+def test_convert_tool_strips_titles():
+    """_convert_tool_to_google_genai should strip titles from inputSchema.
+
+    We test via compress_schema directly rather than constructing a
+    FunctionDeclaration because older google-genai versions may not
+    support the parameters_json_schema field.
+    """
+    from fastmcp.utilities.json_schema import compress_schema
+
+    input_schema = {
+        "title": "Params",
+        "type": "object",
+        "properties": {
+            "query": {"title": "Query", "type": "string"},
+        },
+    }
+
+    schema = compress_schema(input_schema, prune_titles=True)
+    assert "title" not in schema
+    assert "title" not in schema["properties"]["query"]
+    assert schema["properties"]["query"]["type"] == "string"
+
+
+# ────────────────────────────────────────────────────────────
+# Tests for thought-part filtering and improved error messages
+# (PR #3849)
+# ────────────────────────────────────────────────────────────
+
+
+def test_thought_parts_filtered_on_tool_path():
+    """Thought parts should be excluded; only the real text part should appear."""
+    mock_candidate = MagicMock(spec=Candidate)
+    mock_candidate.content = MagicMock()
+    mock_candidate.content.parts = [
+        Part(text="thinking about the problem...", thought=True),
+        Part(text="Here is the real answer"),
+    ]
+    mock_candidate.finish_reason = "STOP"
+
+    mock_response = MagicMock(spec=GenerateContentResponse)
+    mock_response.candidates = [mock_candidate]
+
+    result = _response_to_result_with_tools(mock_response, model="gemini-2.5-flash")
+
+    assert len(result.content) == 1  # ty: ignore[invalid-argument-type]
+    assert isinstance(result.content[0], TextContent)  # ty: ignore[not-subscriptable]
+    assert result.content[0].text == "Here is the real answer"  # ty: ignore[not-subscriptable]
+
+
+def test_thought_only_response_on_tool_path_raises():
+    """When the response contains ONLY thought parts the tool path should raise
+    a ValueError whose message includes the finish_reason."""
+    mock_candidate = MagicMock(spec=Candidate)
+    mock_candidate.content = MagicMock()
+    mock_candidate.content.parts = [
+        Part(text="deep thinking...", thought=True),
+    ]
+    mock_candidate.finish_reason = "STOP"
+
+    mock_response = MagicMock(spec=GenerateContentResponse)
+    mock_response.candidates = [mock_candidate]
+
+    with pytest.raises(ValueError, match="finish_reason=STOP"):
+        _response_to_result_with_tools(mock_response, model="gemini-2.5-flash")
+
+
+def test_thought_only_response_on_non_tool_path_raises():
+    """When the non-tool path receives only thoughts the error message should
+    mention 'thinking/reasoning content'."""
+    mock_candidate = MagicMock(spec=Candidate)
+    mock_candidate.content = MagicMock()
+    mock_candidate.content.parts = [
+        Part(text="internal reasoning...", thought=True),
+    ]
+    mock_candidate.finish_reason = "STOP"
+
+    mock_response = MagicMock(spec=GenerateContentResponse)
+    mock_response.text = None  # No real text available
+    mock_response.candidates = [mock_candidate]
+
+    with pytest.raises(ValueError, match="thinking/reasoning content"):
+        _response_to_create_message_result(mock_response, model="gemini-2.5-flash")
+
+
+def test_safety_filtered_response_on_tool_path_raises():
+    """A safety-filtered response (no parts) should raise with the finish_reason
+    included in the error message."""
+    mock_candidate = MagicMock(spec=Candidate)
+    mock_candidate.content = MagicMock()
+    mock_candidate.content.parts = []  # Empty parts after safety filtering
+    mock_candidate.finish_reason = "SAFETY"
+
+    mock_response = MagicMock(spec=GenerateContentResponse)
+    mock_response.candidates = [mock_candidate]
+
+    with pytest.raises(ValueError, match="finish_reason=SAFETY"):
+        _response_to_result_with_tools(mock_response, model="gemini-2.5-flash")
+
+
+def test_safety_filtered_response_on_non_tool_path_raises():
+    """A safety-filtered response on the non-tool path should include
+    finish_reason in the error."""
+    mock_candidate = MagicMock(spec=Candidate)
+    mock_candidate.content = MagicMock()
+    mock_candidate.content.parts = []
+    mock_candidate.finish_reason = "SAFETY"
+
+    mock_response = MagicMock(spec=GenerateContentResponse)
+    mock_response.text = None
+    mock_response.candidates = [mock_candidate]
+
+    with pytest.raises(ValueError, match="finish_reason=SAFETY"):
+        _response_to_create_message_result(mock_response, model="gemini-2.5-flash")
+
+
+def test_normal_response_text_and_function_call():
+    """A normal response with both real text and a function call should
+    produce both TextContent and ToolUseContent in the result."""
+    mock_candidate = MagicMock(spec=Candidate)
+    mock_candidate.content = MagicMock()
+    mock_candidate.content.parts = [
+        Part(text="Let me look that up."),
+        Part(function_call=FunctionCall(name="lookup", args={"q": "test"})),
+    ]
+    mock_candidate.finish_reason = "STOP"
+
+    mock_response = MagicMock(spec=GenerateContentResponse)
+    mock_response.candidates = [mock_candidate]
+
+    result = _response_to_result_with_tools(mock_response, model="gemini-2.5-flash")
+
+    assert len(result.content) == 2  # ty: ignore[invalid-argument-type]
+    assert isinstance(result.content[0], TextContent)  # ty: ignore[not-subscriptable]
+    assert result.content[0].text == "Let me look that up."  # ty: ignore[not-subscriptable]
+    assert isinstance(result.content[1], ToolUseContent)  # ty: ignore[not-subscriptable]
+    assert result.content[1].name == "lookup"  # ty: ignore[not-subscriptable]
+    assert result.content[1].input == {"q": "test"}  # ty: ignore[not-subscriptable]
+    assert result.stop_reason == "toolUse"
+
+
+def test_thought_with_function_call_keeps_function_call():
+    """When thinking parts accompany a function call, only the function call
+    should appear in the content (thought parts filtered out)."""
+    mock_candidate = MagicMock(spec=Candidate)
+    mock_candidate.content = MagicMock()
+    mock_candidate.content.parts = [
+        Part(text="reasoning about what tool to use...", thought=True),
+        Part(function_call=FunctionCall(name="get_weather", args={"city": "NYC"})),
+    ]
+    mock_candidate.finish_reason = "STOP"
+
+    mock_response = MagicMock(spec=GenerateContentResponse)
+    mock_response.candidates = [mock_candidate]
+
+    result = _response_to_result_with_tools(mock_response, model="gemini-2.5-flash")
+
+    assert len(result.content) == 1  # ty: ignore[invalid-argument-type]
+    assert isinstance(result.content[0], ToolUseContent)  # ty: ignore[not-subscriptable]
+    assert result.content[0].name == "get_weather"  # ty: ignore[not-subscriptable]
+    assert result.stop_reason == "toolUse"
diff --git a/tests/client/sampling/handlers/test_openai_handler.py b/tests/client/sampling/handlers/test_openai_handler.py
new file mode 100644
index 0000000..7370b68
--- /dev/null
+++ b/tests/client/sampling/handlers/test_openai_handler.py
@@ -0,0 +1,342 @@
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from mcp_types import (
+    AudioContent,
+    CreateMessageRequestParams,
+    CreateMessageResult,
+    EmbeddedResource,
+    ImageContent,
+    ModelHint,
+    ModelPreferences,
+    SamplingMessage,
+    TextContent,
+    TextResourceContents,
+    ToolUseContent,
+)
+from openai import AsyncOpenAI
+from openai.types.chat import (
+    ChatCompletion,
+    ChatCompletionAssistantMessageParam,
+    ChatCompletionContentPartImageParam,
+    ChatCompletionContentPartInputAudioParam,
+    ChatCompletionContentPartTextParam,
+    ChatCompletionMessage,
+    ChatCompletionSystemMessageParam,
+    ChatCompletionUserMessageParam,
+)
+from openai.types.chat.chat_completion import Choice
+
+from fastmcp.client.sampling.handlers.openai import (
+    OpenAISamplingHandler,
+    _audio_content_to_openai_part,
+    _image_content_to_openai_part,
+)
+
+
+def test_convert_sampling_messages_to_openai_messages():
+    msgs = OpenAISamplingHandler._convert_to_openai_messages(
+        system_prompt="sys",
+        messages=[
+            SamplingMessage(
+                role="user", content=TextContent(type="text", text="hello")
+            ),
+            SamplingMessage(
+                role="assistant", content=TextContent(type="text", text="ok")
+            ),
+        ],
+    )
+
+    assert msgs == [
+        ChatCompletionSystemMessageParam(content="sys", role="system"),
+        ChatCompletionUserMessageParam(content="hello", role="user"),
+        ChatCompletionAssistantMessageParam(content="ok", role="assistant"),
+    ]
+
+
+def test_image_content_to_openai_part():
+    part = _image_content_to_openai_part(
+        ImageContent(type="image", data="YWJj", mime_type="image/png")
+    )
+
+    assert part == ChatCompletionContentPartImageParam(
+        type="image_url",
+        image_url={"url": "data:image/png;base64,YWJj"},
+    )
+
+
+def test_audio_content_to_openai_part_wav():
+    part = _audio_content_to_openai_part(
+        AudioContent(type="audio", data="YWJj", mime_type="audio/wav")
+    )
+
+    assert part == ChatCompletionContentPartInputAudioParam(
+        type="input_audio",
+        input_audio={"data": "YWJj", "format": "wav"},
+    )
+
+
+def test_audio_content_to_openai_part_mp3():
+    part = _audio_content_to_openai_part(
+        AudioContent(type="audio", data="YWJj", mime_type="audio/mpeg")
+    )
+
+    assert part["input_audio"]["format"] == "mp3"
+
+
+def test_audio_content_to_openai_part_unsupported_raises():
+    with pytest.raises(ValueError, match="Unsupported audio MIME type"):
+        _audio_content_to_openai_part(
+            AudioContent(type="audio", data="YWJj", mime_type="audio/ogg")
+        )
+
+
+def test_image_content_to_openai_part_unsupported_raises():
+    with pytest.raises(ValueError, match="Unsupported image MIME type"):
+        _image_content_to_openai_part(
+            ImageContent(type="image", data="YWJj", mime_type="image/bmp")
+        )
+
+
+def test_convert_single_image_content_to_openai_message():
+    msgs = OpenAISamplingHandler._convert_to_openai_messages(
+        system_prompt=None,
+        messages=[
+            SamplingMessage(
+                role="user",
+                content=ImageContent(type="image", data="YWJj", mime_type="image/png"),
+            )
+        ],
+    )
+
+    assert len(msgs) == 1
+    assert msgs[0] == ChatCompletionUserMessageParam(
+        role="user",
+        content=[
+            ChatCompletionContentPartImageParam(
+                type="image_url",
+                image_url={"url": "data:image/png;base64,YWJj"},
+            )
+        ],
+    )
+
+
+def test_convert_single_audio_content_to_openai_message():
+    msgs = OpenAISamplingHandler._convert_to_openai_messages(
+        system_prompt=None,
+        messages=[
+            SamplingMessage(
+                role="user",
+                content=AudioContent(type="audio", data="YWJj", mime_type="audio/wav"),
+            )
+        ],
+    )
+
+    assert len(msgs) == 1
+    assert msgs[0] == ChatCompletionUserMessageParam(
+        role="user",
+        content=[
+            ChatCompletionContentPartInputAudioParam(
+                type="input_audio",
+                input_audio={"data": "YWJj", "format": "wav"},
+            )
+        ],
+    )
+
+
+def test_convert_list_content_with_image_and_text():
+    msgs = OpenAISamplingHandler._convert_to_openai_messages(
+        system_prompt=None,
+        messages=[
+            SamplingMessage(
+                role="user",
+                content=[
+                    TextContent(type="text", text="What is in this image?"),
+                    ImageContent(type="image", data="YWJj", mime_type="image/jpeg"),
+                ],
+            )
+        ],
+    )
+
+    assert len(msgs) == 1
+    assert msgs[0] == ChatCompletionUserMessageParam(
+        role="user",
+        content=[
+            ChatCompletionContentPartTextParam(
+                type="text", text="What is in this image?"
+            ),
+            ChatCompletionContentPartImageParam(
+                type="image_url",
+                image_url={"url": "data:image/jpeg;base64,YWJj"},
+            ),
+        ],
+    )
+
+
+def test_convert_image_in_assistant_message_raises():
+    with pytest.raises(ValueError, match="ImageContent is only supported in user"):
+        OpenAISamplingHandler._convert_to_openai_messages(
+            system_prompt=None,
+            messages=[
+                SamplingMessage(
+                    role="assistant",
+                    content=ImageContent(
+                        type="image", data="YWJj", mime_type="image/png"
+                    ),
+                )
+            ],
+        )
+
+
+def test_convert_audio_in_assistant_message_raises():
+    with pytest.raises(ValueError, match="AudioContent is only supported in user"):
+        OpenAISamplingHandler._convert_to_openai_messages(
+            system_prompt=None,
+            messages=[
+                SamplingMessage(
+                    role="assistant",
+                    content=AudioContent(
+                        type="audio", data="YWJj", mime_type="audio/wav"
+                    ),
+                )
+            ],
+        )
+
+
+def test_convert_list_image_in_assistant_message_raises():
+    """Image/audio in an assistant list-content message should raise, not silently drop."""
+    with pytest.raises(ValueError, match="only supported in user messages"):
+        OpenAISamplingHandler._convert_to_openai_messages(
+            system_prompt=None,
+            messages=[
+                SamplingMessage(
+                    role="assistant",
+                    content=[
+                        TextContent(type="text", text="Here's the image"),
+                        ImageContent(type="image", data="YWJj", mime_type="image/png"),
+                    ],
+                )
+            ],
+        )
+
+
+def test_convert_list_tool_calls_with_image_raises():
+    """Image/audio alongside tool_calls in assistant list should raise."""
+    with pytest.raises(ValueError, match="only supported in user messages"):
+        OpenAISamplingHandler._convert_to_openai_messages(
+            system_prompt=None,
+            messages=[
+                SamplingMessage(
+                    role="assistant",
+                    content=[
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_1",
+                            name="my_tool",
+                            input={"arg": "val"},
+                        ),
+                        ImageContent(type="image", data="YWJj", mime_type="image/png"),
+                    ],
+                )
+            ],
+        )
+
+
+@pytest.mark.parametrize(
+    "prefs,expected",
+    [
+        ("gpt-4o-mini", "gpt-4o-mini"),
+        (ModelPreferences(hints=[ModelHint(name="gpt-4o-mini")]), "gpt-4o-mini"),
+        (["gpt-4o-mini", "other"], "gpt-4o-mini"),
+        (None, "fallback-model"),
+        (["unknown-model"], "fallback-model"),
+    ],
+)
+def test_select_model_from_preferences(prefs: Any, expected: str) -> None:
+    mock_client = MagicMock(spec=AsyncOpenAI)
+    handler = OpenAISamplingHandler(default_model="fallback-model", client=mock_client)  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+    assert handler._select_model_from_preferences(prefs) == expected
+
+
+async def test_handler_passes_max_completion_tokens():
+    """Verify the handler uses max_completion_tokens (not max_tokens)."""
+    mock_client = MagicMock(spec=AsyncOpenAI)
+    mock_client.chat = MagicMock()
+    mock_client.chat.completions = MagicMock()
+    mock_client.chat.completions.create = AsyncMock(
+        return_value=ChatCompletion(
+            id="123",
+            created=123,
+            model="gpt-4o-mini",
+            object="chat.completion",
+            choices=[
+                Choice(
+                    message=ChatCompletionMessage(content="hi", role="assistant"),
+                    finish_reason="stop",
+                    index=0,
+                )
+            ],
+        )
+    )
+    handler = OpenAISamplingHandler(default_model="gpt-4o-mini", client=mock_client)
+    messages = [
+        SamplingMessage(role="user", content=TextContent(type="text", text="hello"))
+    ]
+    params = CreateMessageRequestParams(messages=messages, max_tokens=300)
+    await handler(messages, params, context=None)  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+
+    call_kwargs = mock_client.chat.completions.create.call_args
+    assert "max_completion_tokens" in call_kwargs.kwargs
+    assert call_kwargs.kwargs["max_completion_tokens"] == 300
+    assert "max_tokens" not in call_kwargs.kwargs
+
+
+async def test_chat_completion_to_create_message_result():
+    mock_client = MagicMock(spec=AsyncOpenAI)
+    handler = OpenAISamplingHandler(default_model="fallback-model", client=mock_client)  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+    mock_client.chat.completions.create.return_value = ChatCompletion(
+        id="123",
+        created=123,
+        model="gpt-4o-mini",
+        object="chat.completion",
+        choices=[
+            Choice(
+                message=ChatCompletionMessage(
+                    content="HELPFUL CONTENT FROM A VERY SMART LLM", role="assistant"
+                ),
+                finish_reason="stop",
+                index=0,
+            )
+        ],
+    )
+    result: CreateMessageResult = handler._chat_completion_to_create_message_result(
+        chat_completion=mock_client.chat.completions.create.return_value
+    )
+    assert result == CreateMessageResult(
+        content=TextContent(type="text", text="HELPFUL CONTENT FROM A VERY SMART LLM"),
+        role="assistant",
+        model="gpt-4o-mini",
+    )
+
+
+def test_convert_messages_raises_on_unsupported_content_type():
+    """Unsupported content types should raise ValueError.
+
+    SamplingMessage validates content against a union of known types, so
+    we use model_construct to bypass validation and simulate a future
+    SDK content type that the handler doesn't know about yet.
+    """
+    embedded = EmbeddedResource(
+        type="resource",
+        resource=TextResourceContents(
+            uri="file:///test.txt", text="hello", mime_type="text/plain"
+        ),
+    )
+    msg = SamplingMessage.model_construct(
+        role="user",
+        content=[TextContent(type="text", text="prefix"), embedded],
+    )
+
+    with pytest.raises(ValueError, match="Unsupported content type for OpenAI"):
+        OpenAISamplingHandler._convert_to_openai_messages(None, [msg])
diff --git a/tests/client/tasks/conftest.py b/tests/client/tasks/conftest.py
new file mode 100644
index 0000000..29d0c9a
--- /dev/null
+++ b/tests/client/tasks/conftest.py
@@ -0,0 +1 @@
+"""Configuration for client task tests."""
diff --git a/tests/client/tasks/test_client_prompt_tasks.py b/tests/client/tasks/test_client_prompt_tasks.py
new file mode 100644
index 0000000..57f55e0
--- /dev/null
+++ b/tests/client/tasks/test_client_prompt_tasks.py
@@ -0,0 +1,108 @@
+"""
+Tests for client-side prompt task methods.
+
+Tests the client's get_prompt_as_task method.
+"""
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.tasks import PromptTask
+
+
+@pytest.fixture
+async def prompt_server():
+    """Create a test server with background-enabled prompts."""
+    mcp = FastMCP("prompt-client-test")
+
+    @mcp.prompt(task=True)
+    async def analysis_prompt(topic: str, style: str = "formal") -> str:
+        """Generate an analysis prompt."""
+        return f"Analyze {topic} in a {style} style"
+
+    @mcp.prompt(task=True)
+    async def creative_prompt(theme: str) -> str:
+        """Generate a creative writing prompt."""
+        return f"Write a story about {theme}"
+
+    return mcp
+
+
+async def test_get_prompt_as_task_returns_prompt_task(prompt_server):
+    """get_prompt with task=True returns a PromptTask object."""
+    async with Client(prompt_server) as client:
+        task = await client.get_prompt("analysis_prompt", {"topic": "AI"}, task=True)
+
+        assert isinstance(task, PromptTask)
+        assert isinstance(task.task_id, str)
+
+
+async def test_prompt_task_server_generated_id(prompt_server):
+    """get_prompt with task=True gets server-generated task ID."""
+    async with Client(prompt_server) as client:
+        task = await client.get_prompt(
+            "creative_prompt",
+            {"theme": "future"},
+            task=True,
+        )
+
+        # Server should generate a UUID task ID
+        assert task.task_id is not None
+        assert isinstance(task.task_id, str)
+        # UUIDs have hyphens
+        assert "-" in task.task_id
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_prompt_task_result_returns_get_prompt_result(prompt_server):
+    """PromptTask.result() returns GetPromptResult."""
+    async with Client(prompt_server) as client:
+        task = await client.get_prompt(
+            "analysis_prompt", {"topic": "Robotics", "style": "casual"}, task=True
+        )
+
+        # Verify background execution
+        assert not task.returned_immediately
+
+        # Get result
+        result = await task.result()
+
+        # Result should be GetPromptResult
+        assert hasattr(result, "description")
+        assert hasattr(result, "messages")
+        # Check the rendered message content, not the description
+        assert len(result.messages) > 0
+        assert "Analyze Robotics" in result.messages[0].content.text
+
+
+async def test_prompt_task_await_syntax(prompt_server):
+    """PromptTask can be awaited directly."""
+    async with Client(prompt_server) as client:
+        task = await client.get_prompt("creative_prompt", {"theme": "ocean"}, task=True)
+
+        # Can await task directly
+        result = await task
+        assert "Write a story about ocean" in result.messages[0].content.text
+
+
+async def test_prompt_task_status_and_wait(prompt_server):
+    """PromptTask supports status() and wait() methods."""
+    async with Client(prompt_server) as client:
+        task = await client.get_prompt("analysis_prompt", {"topic": "Space"}, task=True)
+
+        # Check status
+        status = await task.status()
+        assert status.status in ["working", "completed"]
+
+        # Wait for completion
+        await task.wait(timeout=2.0)
+
+        # Get result
+        result = await task.result()
+        assert "Analyze Space" in result.messages[0].content.text
diff --git a/tests/client/tasks/test_client_resource_tasks.py b/tests/client/tasks/test_client_resource_tasks.py
new file mode 100644
index 0000000..0dda036
--- /dev/null
+++ b/tests/client/tasks/test_client_resource_tasks.py
@@ -0,0 +1,119 @@
+"""
+Tests for client-side resource task methods.
+
+Tests the client's read_resource_as_task method.
+"""
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.tasks import ResourceTask
+
+
+@pytest.fixture
+async def resource_server():
+    """Create a test server with background-enabled resources."""
+    mcp = FastMCP("resource-client-test")
+
+    @mcp.resource("file://document.txt", task=True)
+    async def document() -> str:
+        """A document resource."""
+        return "Document content here"
+
+    @mcp.resource("file://data/{id}.json", task=True)
+    async def data_file(id: str) -> str:
+        """A parameterized data resource."""
+        return f'{{"id": "{id}", "value": 42}}'
+
+    return mcp
+
+
+async def test_read_resource_as_task_returns_resource_task(resource_server):
+    """read_resource with task=True returns a ResourceTask object."""
+    async with Client(resource_server) as client:
+        task = await client.read_resource("file://document.txt", task=True)
+
+        assert isinstance(task, ResourceTask)
+        assert isinstance(task.task_id, str)
+
+
+async def test_resource_task_server_generated_id(resource_server):
+    """read_resource with task=True gets server-generated task ID."""
+    async with Client(resource_server) as client:
+        task = await client.read_resource("file://document.txt", task=True)
+
+        # Server should generate a UUID task ID
+        assert task.task_id is not None
+        assert isinstance(task.task_id, str)
+        # UUIDs have hyphens
+        assert "-" in task.task_id
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on ReadResourceRequestParams, so "
+    "resource reads cannot be submitted as background tasks over the wire and "
+    "always graceful-degrade to immediate execution (sdk-feedback #3).",
+    strict=True,
+)
+async def test_resource_task_result_returns_read_resource_result(resource_server):
+    """ResourceTask.result() returns list of ReadResourceContents."""
+    async with Client(resource_server) as client:
+        task = await client.read_resource("file://document.txt", task=True)
+
+        # Verify background execution
+        assert not task.returned_immediately
+
+        # Get result
+        result = await task.result()
+
+        # Result should be list of ReadResourceContents
+        assert isinstance(result, list)
+        assert len(result) > 0
+        assert result[0].text == "Document content here"
+
+
+async def test_resource_task_await_syntax(resource_server):
+    """ResourceTask can be awaited directly."""
+    async with Client(resource_server) as client:
+        task = await client.read_resource("file://document.txt", task=True)
+
+        # Can await task directly
+        result = await task
+        assert result[0].text == "Document content here"
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on ReadResourceRequestParams, so "
+    "resource reads cannot be submitted as background tasks over the wire and "
+    "always graceful-degrade to immediate execution (sdk-feedback #3).",
+    strict=True,
+)
+async def test_resource_template_task(resource_server):
+    """Resource templates work with task support."""
+    async with Client(resource_server) as client:
+        task = await client.read_resource("file://data/999.json", task=True)
+
+        # Verify background execution
+        assert not task.returned_immediately
+
+        # Get result
+        result = await task.result()
+        assert '"id": "999"' in result[0].text
+
+
+async def test_resource_task_status_and_wait(resource_server):
+    """ResourceTask supports status() and wait() methods."""
+    async with Client(resource_server) as client:
+        task = await client.read_resource("file://document.txt", task=True)
+
+        # Check status
+        status = await task.status()
+        assert status.status in ["working", "completed"]
+
+        # Wait for completion
+        await task.wait(timeout=2.0)
+
+        # Get result
+        result = await task.result()
+        assert "Document content" in result[0].text
diff --git a/tests/client/tasks/test_client_task_notifications.py b/tests/client/tasks/test_client_task_notifications.py
new file mode 100644
index 0000000..94f7e1d
--- /dev/null
+++ b/tests/client/tasks/test_client_task_notifications.py
@@ -0,0 +1,236 @@
+"""
+Tests for client-side handling of notifications/tasks/status (SEP-1686 lines 436-444).
+
+Verifies that Task objects receive notifications, update their cache, wake up wait() calls,
+and invoke user callbacks.
+"""
+
+import asyncio
+import time
+from datetime import datetime, timezone
+
+import pytest
+from mcp_types import GetTaskResult
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+
+
+@pytest.fixture
+async def task_notification_server():
+    """Server that sends task status notifications."""
+    mcp = FastMCP("task-notification-test")
+
+    @mcp.tool(task=True)
+    async def quick_task(value: int) -> int:
+        """Quick background task."""
+        await asyncio.sleep(0.05)
+        return value * 2
+
+    @mcp.tool(task=True)
+    async def slow_task(duration: float = 0.2) -> str:
+        """Slow background task."""
+        await asyncio.sleep(duration)
+        return "done"
+
+    @mcp.tool(task=True)
+    async def failing_task() -> str:
+        """Task that fails."""
+        raise ValueError("Intentional failure")
+
+    return mcp
+
+
+async def test_task_receives_status_notification(task_notification_server):
+    """Task object receives and processes status notifications."""
+    async with Client(task_notification_server) as client:
+        task = await client.call_tool("quick_task", {"value": 5}, task=True)
+
+        # Wait for task to complete (notification should arrive)
+        status = await task.wait(timeout=2.0)
+
+        # Verify task completed
+        assert status.status == "completed"
+
+
+async def test_status_cache_updated_by_notification(task_notification_server):
+    """Cached status is updated when notification arrives."""
+    async with Client(task_notification_server) as client:
+        task = await client.call_tool("quick_task", {"value": 10}, task=True)
+
+        # Wait for completion (notification should update cache)
+        await task.wait(timeout=2.0)
+
+        # Status should be cached (no server call needed)
+        # Call status() twice - should return same cached object
+        status1 = await task.status()
+        status2 = await task.status()
+
+        # Should be the exact same object (from cache)
+        assert status1 is status2
+        assert status1.status == "completed"
+
+
+async def test_callback_invoked_on_notification(task_notification_server):
+    """User callback is invoked when notification arrives."""
+    callback_invocations = []
+
+    def status_callback(status: GetTaskResult):
+        """Sync callback."""
+        callback_invocations.append(status)
+
+    async with Client(task_notification_server) as client:
+        task = await client.call_tool("quick_task", {"value": 7}, task=True)
+
+        # Register callback
+        task.on_status_change(status_callback)
+
+        # Wait for completion
+        await task.wait(timeout=2.0)
+
+        # Give callbacks a moment to fire
+        await asyncio.sleep(0.1)
+
+    # Callback should have been invoked at least once
+    assert len(callback_invocations) > 0
+
+    # Should have received completed status
+    completed_statuses = [s for s in callback_invocations if s.status == "completed"]
+    assert len(completed_statuses) > 0
+
+
+async def test_async_callback_invoked(task_notification_server):
+    """Async callback is invoked when notification arrives."""
+    callback_invocations = []
+
+    async def async_status_callback(status: GetTaskResult):
+        """Async callback."""
+        await asyncio.sleep(0.01)  # Simulate async work
+        callback_invocations.append(status)
+
+    async with Client(task_notification_server) as client:
+        task = await client.call_tool("quick_task", {"value": 3}, task=True)
+
+        # Register async callback
+        task.on_status_change(async_status_callback)
+
+        # Wait for completion
+        await task.wait(timeout=2.0)
+
+        # Give async callbacks time to complete
+        await asyncio.sleep(0.2)
+
+    # Async callback should have been invoked
+    assert len(callback_invocations) > 0
+
+
+async def test_multiple_callbacks_all_invoked(task_notification_server):
+    """Multiple callbacks are all invoked."""
+    callback1_calls = []
+    callback2_calls = []
+
+    def callback1(status: GetTaskResult):
+        callback1_calls.append(status.status)
+
+    def callback2(status: GetTaskResult):
+        callback2_calls.append(status.status)
+
+    async with Client(task_notification_server) as client:
+        task = await client.call_tool("quick_task", {"value": 8}, task=True)
+
+        task.on_status_change(callback1)
+        task.on_status_change(callback2)
+
+        await task.wait(timeout=2.0)
+        await asyncio.sleep(0.1)
+
+    # Both callbacks should have been invoked
+    assert len(callback1_calls) > 0
+    assert len(callback2_calls) > 0
+
+
+async def test_callback_error_doesnt_break_notification(task_notification_server):
+    """Callback errors don't prevent other callbacks from running."""
+    callback1_calls = []
+    callback2_calls = []
+
+    def failing_callback(status: GetTaskResult):
+        callback1_calls.append("called")
+        raise ValueError("Callback intentionally fails")
+
+    def working_callback(status: GetTaskResult):
+        callback2_calls.append(status.status)
+
+    async with Client(task_notification_server) as client:
+        task = await client.call_tool("quick_task", {"value": 12}, task=True)
+
+        task.on_status_change(failing_callback)
+        task.on_status_change(working_callback)
+
+        await task.wait(timeout=2.0)
+        await asyncio.sleep(0.1)
+
+    # Failing callback was called (and errored)
+    assert len(callback1_calls) > 0
+
+    # Working callback should still have been invoked
+    assert len(callback2_calls) > 0
+
+
+async def test_wait_wakes_early_on_notification(task_notification_server):
+    """wait() wakes up immediately when notification arrives, not after poll interval."""
+    async with Client(task_notification_server) as client:
+        task = await client.call_tool("quick_task", {"value": 15}, task=True)
+
+        # Record timing
+        start = time.time()
+        status = await task.wait(timeout=5.0)
+        elapsed = time.time() - start
+
+        # Should complete much faster than the fallback poll interval (500ms)
+        # With notifications, should be < 200ms for quick task
+        # Without notifications, would take 500ms+ due to polling
+        assert elapsed < 1.0  # Very generous bound
+        assert status.status == "completed"
+
+
+async def test_notification_with_failed_task(task_notification_server):
+    """Notifications work for failed tasks too."""
+    async with Client(task_notification_server) as client:
+        task = await client.call_tool("failing_task", {}, task=True)
+
+        with pytest.raises(Exception):
+            await task
+
+        # Should have cached the failed status from notification
+        status = await task.status()
+        assert status.status == "failed"
+        assert (
+            status.status_message is not None
+        )  # Error details in statusMessage per spec
+
+
+async def test_wait_returns_on_input_required(task_notification_server):
+    """wait() should return immediately when task enters input_required, not hang."""
+    async with Client(task_notification_server) as client:
+        task = await client.call_tool("quick_task", {"value": 1}, task=True)
+
+        # Directly inject an input_required status into the cache and signal the event.
+        # SDK v2 types the Task timestamps as ISO 8601 strings.
+        now = datetime.now(timezone.utc).isoformat()
+        input_required_status = GetTaskResult(
+            task_id=task._task_id,
+            status="input_required",
+            status_message="Waiting for user input",
+            created_at=now,
+            last_updated_at=now,
+            ttl=None,
+        )
+        task._status_cache = input_required_status
+        if task._status_event is None:
+            task._status_event = asyncio.Event()
+        task._status_event.set()
+
+        # Should return immediately with input_required, not hang for 300s
+        status = await task.wait(timeout=2.0)
+        assert status.status == "input_required"
diff --git a/tests/client/tasks/test_client_task_protocol.py b/tests/client/tasks/test_client_task_protocol.py
new file mode 100644
index 0000000..e8b29af
--- /dev/null
+++ b/tests/client/tasks/test_client_task_protocol.py
@@ -0,0 +1,85 @@
+"""
+Tests for client-side task protocol.
+
+Generic protocol tests that use tools as test fixtures.
+"""
+
+import asyncio
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+
+
+async def test_end_to_end_task_flow():
+    """Complete end-to-end flow: submit, poll, retrieve."""
+    start_signal = asyncio.Event()
+    complete_signal = asyncio.Event()
+
+    mcp = FastMCP("protocol-test")
+
+    @mcp.tool(task=True)
+    async def controlled_tool(message: str) -> str:
+        """Tool with controlled execution."""
+        start_signal.set()
+        await complete_signal.wait()
+        return f"Processed: {message}"
+
+    async with Client(mcp) as client:
+        # Submit task
+        task = await client.call_tool(
+            "controlled_tool", {"message": "integration test"}, task=True
+        )
+
+        # Wait for execution to start
+        await asyncio.wait_for(start_signal.wait(), timeout=2.0)
+
+        # Check status while running
+        status = await task.status()
+        assert status.status in ["working"]
+
+        # Signal completion
+        complete_signal.set()
+
+        # Wait for task to finish and retrieve result
+        result = await task.result()
+        assert result.data == "Processed: integration test"
+
+
+async def test_multiple_concurrent_tasks():
+    """Multiple tasks can run concurrently."""
+    mcp = FastMCP("concurrent-test")
+
+    @mcp.tool(task=True)
+    async def multiply(a: int, b: int) -> int:
+        return a * b
+
+    async with Client(mcp) as client:
+        # Submit multiple tasks
+        tasks = []
+        for i in range(5):
+            task = await client.call_tool("multiply", {"a": i, "b": 2}, task=True)
+            tasks.append((task, i * 2))
+
+        # Wait for all to complete and verify results
+        for task, expected in tasks:
+            result = await task.result()
+            assert result.data == expected
+
+
+async def test_task_id_auto_generation():
+    """Task IDs are auto-generated if not provided."""
+    mcp = FastMCP("id-test")
+
+    @mcp.tool(task=True)
+    async def echo(message: str) -> str:
+        return f"Echo: {message}"
+
+    async with Client(mcp) as client:
+        # Submit without custom task ID
+        task_1 = await client.call_tool("echo", {"message": "first"}, task=True)
+        task_2 = await client.call_tool("echo", {"message": "second"}, task=True)
+
+        # Should generate different IDs
+        assert task_1.task_id != task_2.task_id
+        assert len(task_1.task_id) > 0
+        assert len(task_2.task_id) > 0
diff --git a/tests/client/tasks/test_client_tool_tasks.py b/tests/client/tasks/test_client_tool_tasks.py
new file mode 100644
index 0000000..0bec286
--- /dev/null
+++ b/tests/client/tasks/test_client_tool_tasks.py
@@ -0,0 +1,156 @@
+"""
+Tests for client-side tool task methods.
+
+Tests the client's tool-specific task functionality, parallel to
+test_client_prompt_tasks.py and test_client_resource_tasks.py.
+"""
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.tasks import ToolTask
+from fastmcp.exceptions import ToolError
+
+
+@pytest.fixture
+async def tool_task_server():
+    """Create a test server with task-enabled tools."""
+    mcp = FastMCP("tool-task-test")
+
+    @mcp.tool(task=True)
+    async def echo(message: str) -> str:
+        """Echo back the message."""
+        return f"Echo: {message}"
+
+    @mcp.tool(task=True)
+    async def multiply(a: int, b: int) -> int:
+        """Multiply two numbers."""
+        return a * b
+
+    return mcp
+
+
+async def test_call_tool_as_task_returns_tool_task(tool_task_server):
+    """call_tool with task=True returns a ToolTask object."""
+    async with Client(tool_task_server) as client:
+        task = await client.call_tool("echo", {"message": "hello"}, task=True)
+
+        assert isinstance(task, ToolTask)
+        assert isinstance(task.task_id, str)
+        assert len(task.task_id) > 0
+
+
+async def test_tool_task_server_generated_id(tool_task_server):
+    """call_tool with task=True gets server-generated task ID."""
+    async with Client(tool_task_server) as client:
+        task = await client.call_tool("echo", {"message": "test"}, task=True)
+
+        # Server should generate a UUID task ID
+        assert task.task_id is not None
+        assert isinstance(task.task_id, str)
+        # UUIDs have hyphens
+        assert "-" in task.task_id
+
+
+async def test_tool_task_result_returns_call_tool_result(tool_task_server):
+    """ToolTask.result() returns CallToolResult with tool data."""
+    async with Client(tool_task_server) as client:
+        task = await client.call_tool("multiply", {"a": 6, "b": 7}, task=True)
+        assert not task.returned_immediately
+
+        result = await task.result()
+        assert result.data == 42
+
+
+async def test_tool_task_await_syntax(tool_task_server):
+    """Tool tasks can be awaited directly to get result."""
+    async with Client(tool_task_server) as client:
+        task = await client.call_tool("multiply", {"a": 7, "b": 6}, task=True)
+
+        # Can await task directly (syntactic sugar for task.result())
+        result = await task
+        assert result.data == 42
+
+
+async def test_tool_task_status_and_wait(tool_task_server):
+    """ToolTask.status() returns GetTaskResult."""
+    async with Client(tool_task_server) as client:
+        task = await client.call_tool("echo", {"message": "test"}, task=True)
+
+        status = await task.status()
+        assert status.task_id == task.task_id
+        assert status.status in ["working", "completed"]
+
+        # Wait for completion
+        await task.wait(timeout=2.0)
+        final_status = await task.status()
+        assert final_status.status == "completed"
+
+
+async def test_immediate_tool_task_respects_raise_on_error_true():
+    """Immediate task fallback should still raise ToolError when requested."""
+    mcp = FastMCP("immediate-tool-task-error")
+
+    @mcp.tool
+    def failing_tool() -> str:
+        raise ValueError("immediate task failure")
+
+    async with Client(mcp) as client:
+        task = await client.call_tool("failing_tool", task=True, raise_on_error=True)
+
+        assert task.returned_immediately
+        with pytest.raises(
+            ToolError, match="does not support task-augmented execution"
+        ):
+            await task.result()
+
+
+async def test_immediate_tool_task_respects_raise_on_error_false():
+    """Immediate task fallback should return error results when requested."""
+    mcp = FastMCP("immediate-tool-task-no-raise")
+
+    @mcp.tool
+    def failing_tool() -> str:
+        raise ValueError("immediate task failure")
+
+    async with Client(mcp) as client:
+        task = await client.call_tool("failing_tool", task=True, raise_on_error=False)
+
+        assert task.returned_immediately
+        result = await task.result()
+        assert result.is_error is True
+        assert "does not support task-augmented execution" in str(result)
+
+
+async def test_background_tool_task_respects_raise_on_error_true():
+    """Background tasks should still raise ToolError by default on errors."""
+    mcp = FastMCP("background-tool-task-error")
+
+    @mcp.tool(task=True)
+    async def failing_tool() -> str:
+        raise ValueError("background task failure")
+
+    async with Client(mcp) as client:
+        task = await client.call_tool("failing_tool", task=True, raise_on_error=True)
+
+        assert not task.returned_immediately
+        with pytest.raises(ToolError, match="background task failure"):
+            await task.result()
+
+
+async def test_background_tool_task_respects_raise_on_error_false():
+    """Background tasks should return error results when raise_on_error is disabled."""
+    mcp = FastMCP("background-tool-task-no-raise")
+
+    @mcp.tool(task=True)
+    async def failing_tool() -> str:
+        raise ValueError("background task failure")
+
+    async with Client(mcp) as client:
+        task = await client.call_tool("failing_tool", task=True, raise_on_error=False)
+
+        assert not task.returned_immediately
+        result = await task.result()
+        assert result.is_error is True
+        assert "background task failure" in str(result)
diff --git a/tests/client/tasks/test_task_context_validation.py b/tests/client/tasks/test_task_context_validation.py
new file mode 100644
index 0000000..fb4765e
--- /dev/null
+++ b/tests/client/tasks/test_task_context_validation.py
@@ -0,0 +1,222 @@
+"""
+Tests for Task client context validation.
+
+Verifies that Task methods properly validate client context and that
+cached results remain accessible outside context.
+"""
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+
+
+@pytest.fixture
+async def task_server():
+    """Create a test server with background tasks."""
+    mcp = FastMCP("context-test-server")
+
+    @mcp.tool(task=True)
+    async def background_tool(value: str) -> str:
+        """Tool that runs in background."""
+        return f"Result: {value}"
+
+    @mcp.prompt(task=True)
+    async def background_prompt(topic: str) -> str:
+        """Prompt that runs in background."""
+        return f"Prompt about {topic}"
+
+    @mcp.resource("file://background.txt", task=True)
+    async def background_resource() -> str:
+        """Resource that runs in background."""
+        return "Background resource content"
+
+    return mcp
+
+
+async def test_task_status_outside_context_raises(task_server):
+    """Calling task.status() outside client context raises error."""
+    task = None
+    async with Client(task_server) as client:
+        task = await client.call_tool("background_tool", {"value": "test"}, task=True)
+        assert not task.returned_immediately
+    # Now outside context
+
+    with pytest.raises(RuntimeError, match="outside client context"):
+        await task.status()
+
+
+async def test_task_result_outside_context_raises(task_server):
+    """Calling task.result() outside context raises error."""
+    task = None
+    async with Client(task_server) as client:
+        task = await client.call_tool("background_tool", {"value": "test"}, task=True)
+        assert not task.returned_immediately
+    # Now outside context
+
+    with pytest.raises(RuntimeError, match="outside client context"):
+        await task.result()
+
+
+async def test_task_wait_outside_context_raises(task_server):
+    """Calling task.wait() outside context raises error."""
+    task = None
+    async with Client(task_server) as client:
+        task = await client.call_tool("background_tool", {"value": "test"}, task=True)
+        assert not task.returned_immediately
+    # Now outside context
+
+    with pytest.raises(RuntimeError, match="outside client context"):
+        await task.wait()
+
+
+async def test_task_cancel_outside_context_raises(task_server):
+    """Calling task.cancel() outside context raises error."""
+    task = None
+    async with Client(task_server) as client:
+        task = await client.call_tool("background_tool", {"value": "test"}, task=True)
+        assert not task.returned_immediately
+    # Now outside context
+
+    with pytest.raises(RuntimeError, match="outside client context"):
+        await task.cancel()
+
+
+async def test_cached_tool_task_accessible_outside_context(task_server):
+    """Tool tasks with cached results work outside context."""
+    task = None
+    async with Client(task_server) as client:
+        task = await client.call_tool("background_tool", {"value": "test"}, task=True)
+        assert not task.returned_immediately
+
+        # Get result once to cache it
+        result1 = await task.result()
+        assert result1.data == "Result: test"
+    # Now outside context
+
+    # Should work because result is cached
+    result2 = await task.result()
+    assert result2 is result1  # Same object
+    assert result2.data == "Result: test"
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_cached_prompt_task_accessible_outside_context(task_server):
+    """Prompt tasks with cached results work outside context."""
+    task = None
+    async with Client(task_server) as client:
+        task = await client.get_prompt(
+            "background_prompt", {"topic": "test"}, task=True
+        )
+        assert not task.returned_immediately
+
+        # Get result once to cache it
+        result1 = await task.result()
+        assert result1.description == "Prompt that runs in background."
+    # Now outside context
+
+    # Should work because result is cached
+    result2 = await task.result()
+    assert result2 is result1  # Same object
+    assert result2.description == "Prompt that runs in background."
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_cached_resource_task_accessible_outside_context(task_server):
+    """Resource tasks with cached results work outside context."""
+    task = None
+    async with Client(task_server) as client:
+        task = await client.read_resource("file://background.txt", task=True)
+        assert not task.returned_immediately
+
+        # Get result once to cache it
+        result1 = await task.result()
+        assert len(result1) > 0
+    # Now outside context
+
+    # Should work because result is cached
+    result2 = await task.result()
+    assert result2 is result1  # Same object
+
+
+async def test_uncached_status_outside_context_raises(task_server):
+    """Even after caching result, status() still requires client context."""
+    task = None
+    async with Client(task_server) as client:
+        task = await client.call_tool("background_tool", {"value": "test"}, task=True)
+        assert not task.returned_immediately
+
+        # Cache the result
+        await task.result()
+    # Now outside context
+
+    # result() works (cached)
+    result = await task.result()
+    assert result.data == "Result: test"
+
+    # But status() still needs client connection
+    with pytest.raises(RuntimeError, match="outside client context"):
+        await task.status()
+
+
+async def test_task_await_syntax_outside_context_raises(task_server):
+    """Using await task syntax outside context raises error for background tasks."""
+    task = None
+    async with Client(task_server) as client:
+        task = await client.call_tool("background_tool", {"value": "test"}, task=True)
+        assert not task.returned_immediately
+    # Now outside context
+
+    with pytest.raises(RuntimeError, match="outside client context"):
+        await task  # Same as await task.result()
+
+
+async def test_task_await_syntax_works_for_cached_results(task_server):
+    """Using await task syntax works outside context when result is cached."""
+    task = None
+    async with Client(task_server) as client:
+        task = await client.call_tool("background_tool", {"value": "test"}, task=True)
+        result1 = await task  # Cache it
+    # Now outside context
+
+    result2 = await task  # Should work (cached)
+    assert result2 is result1
+    assert result2.data == "Result: test"
+
+
+async def test_multiple_result_calls_return_same_cached_object(task_server):
+    """Multiple result() calls return the same cached object."""
+    async with Client(task_server) as client:
+        task = await client.call_tool("background_tool", {"value": "test"}, task=True)
+
+        result1 = await task.result()
+        result2 = await task.result()
+        result3 = await task.result()
+
+        # Should all be the same object (cached)
+        assert result1 is result2
+        assert result2 is result3
+
+
+async def test_background_task_properties_accessible_outside_context(task_server):
+    """Background task properties like task_id accessible outside context."""
+    task = None
+    async with Client(task_server) as client:
+        task = await client.call_tool("background_tool", {"value": "test"}, task=True)
+        task_id_inside = task.task_id
+        assert not task.returned_immediately
+    # Now outside context
+
+    # Properties should still be accessible (they don't need client connection)
+    assert task.task_id == task_id_inside
+    assert task.returned_immediately is False
diff --git a/tests/client/tasks/test_task_result_caching.py b/tests/client/tasks/test_task_result_caching.py
new file mode 100644
index 0000000..fdb48e1
--- /dev/null
+++ b/tests/client/tasks/test_task_result_caching.py
@@ -0,0 +1,339 @@
+"""
+Tests for Task result caching behavior.
+
+Verifies that Task.result() and await task cache results properly to avoid
+redundant server calls and ensure consistent object identity.
+"""
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+
+
+async def test_tool_task_result_cached_on_first_call():
+    """First call caches result, subsequent calls return cached value."""
+    call_count = 0
+    mcp = FastMCP("test")
+
+    @mcp.tool(task=True)
+    async def counting_tool() -> int:
+        nonlocal call_count
+        call_count += 1
+        return call_count
+
+    async with Client(mcp) as client:
+        task = await client.call_tool("counting_tool", task=True)
+
+        result1 = await task.result()
+        result2 = await task.result()
+        result3 = await task.result()
+
+        # All should return 1 (first execution value)
+        assert result1.data == 1
+        assert result2.data == 1
+        assert result3.data == 1
+
+        # Verify they're the same object (cached)
+        assert result1 is result2 is result3
+
+
+async def test_prompt_task_result_cached():
+    """PromptTask caches results on first call."""
+    call_count = 0
+    mcp = FastMCP("test")
+
+    @mcp.prompt(task=True)
+    async def counting_prompt() -> str:
+        nonlocal call_count
+        call_count += 1
+        return f"Call number: {call_count}"
+
+    async with Client(mcp) as client:
+        task = await client.get_prompt("counting_prompt", task=True)
+
+        result1 = await task.result()
+        result2 = await task.result()
+        result3 = await task.result()
+
+        # All should return same content
+        assert result1.messages[0].content.text == "Call number: 1"
+        assert result2.messages[0].content.text == "Call number: 1"
+        assert result3.messages[0].content.text == "Call number: 1"
+
+        # Verify they're the same object (cached)
+        assert result1 is result2 is result3
+
+
+async def test_resource_task_result_cached():
+    """ResourceTask caches results on first call."""
+    call_count = 0
+    mcp = FastMCP("test")
+
+    @mcp.resource("file://counter.txt", task=True)
+    async def counting_resource() -> str:
+        nonlocal call_count
+        call_count += 1
+        return f"Count: {call_count}"
+
+    async with Client(mcp) as client:
+        task = await client.read_resource("file://counter.txt", task=True)
+
+        result1 = await task.result()
+        result2 = await task.result()
+        result3 = await task.result()
+
+        # All should return same content
+        assert result1[0].text == "Count: 1"
+        assert result2[0].text == "Count: 1"
+        assert result3[0].text == "Count: 1"
+
+        # Verify they're the same object (cached)
+        assert result1 is result2 is result3
+
+
+async def test_multiple_await_returns_same_object():
+    """Multiple await task calls return identical object."""
+    mcp = FastMCP("test")
+
+    @mcp.tool(task=True)
+    async def sample_tool() -> str:
+        return "result"
+
+    async with Client(mcp) as client:
+        task = await client.call_tool("sample_tool", task=True)
+
+        result1 = await task
+        result2 = await task
+        result3 = await task
+
+        # Should be exact same object in memory
+        assert result1 is result2 is result3
+        assert id(result1) == id(result2) == id(result3)
+
+
+async def test_result_and_await_share_cache():
+    """task.result() and await task share the same cache."""
+    mcp = FastMCP("test")
+
+    @mcp.tool(task=True)
+    async def sample_tool() -> str:
+        return "cached"
+
+    async with Client(mcp) as client:
+        task = await client.call_tool("sample_tool", task=True)
+
+        # Call result() first
+        result_via_method = await task.result()
+
+        # Then await directly
+        result_via_await = await task
+
+        # Should be the same cached object
+        assert result_via_method is result_via_await
+        assert id(result_via_method) == id(result_via_await)
+
+
+async def test_forbidden_mode_tool_caches_error_result():
+    """Tools with task=False (mode=forbidden) cache error results."""
+    mcp = FastMCP("test")
+
+    @mcp.tool(task=False)
+    async def non_task_tool() -> int:
+        return 1
+
+    async with Client(mcp) as client:
+        # Request as task, but mode="forbidden" will reject with error
+        task = await client.call_tool("non_task_tool", task=True, raise_on_error=False)
+
+        # Should be immediate (error returned immediately)
+        assert task.returned_immediately
+
+        result1 = await task.result()
+        result2 = await task.result()
+        result3 = await task.result()
+
+        # All should return cached error
+        assert result1.is_error
+        assert "does not support task-augmented execution" in str(result1)
+
+        # Verify they're the same object (cached)
+        assert result1 is result2 is result3
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_forbidden_mode_prompt_raises_error():
+    """Prompts with task=False (mode=forbidden) raise error."""
+    import pytest
+    from mcp.shared.exceptions import MCPError
+
+    mcp = FastMCP("test")
+
+    @mcp.prompt(task=False)
+    async def non_task_prompt() -> str:
+        return "Immediate"
+
+    async with Client(mcp) as client:
+        # Prompts with mode="forbidden" raise MCPError when called with task=True
+        with pytest.raises(MCPError):
+            await client.get_prompt("non_task_prompt", task=True)
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_forbidden_mode_resource_raises_error():
+    """Resources with task=False (mode=forbidden) raise error."""
+    import pytest
+    from mcp.shared.exceptions import MCPError
+
+    mcp = FastMCP("test")
+
+    @mcp.resource("file://immediate.txt", task=False)
+    async def non_task_resource() -> str:
+        return "Immediate"
+
+    async with Client(mcp) as client:
+        # Resources with mode="forbidden" raise MCPError when called with task=True
+        with pytest.raises(MCPError):
+            await client.read_resource("file://immediate.txt", task=True)
+
+
+async def test_immediate_task_caches_result():
+    """Immediate tasks (optional mode called without background) cache results."""
+    call_count = 0
+    mcp = FastMCP("test", tasks=True)
+
+    # Tool with task=True (optional mode) - but without docket will execute immediately
+    @mcp.tool(task=True)
+    async def task_tool() -> int:
+        nonlocal call_count
+        call_count += 1
+        return call_count
+
+    async with Client(mcp) as client:
+        # Call with task=True
+        task = await client.call_tool("task_tool", task=True)
+
+        # Get result multiple times
+        result1 = await task.result()
+        result2 = await task.result()
+        result3 = await task.result()
+
+        # All should return cached value
+        assert result1.data == 1
+        assert result2.data == 1
+        assert result3.data == 1
+
+        # Verify they're the same object (cached)
+        assert result1 is result2 is result3
+
+
+async def test_cache_persists_across_mixed_access_patterns():
+    """Cache works correctly when mixing result() and await."""
+    mcp = FastMCP("test")
+
+    @mcp.tool(task=True)
+    async def mixed_tool() -> str:
+        return "mixed"
+
+    async with Client(mcp) as client:
+        task = await client.call_tool("mixed_tool", task=True)
+
+        # Access in various orders
+        result1 = await task
+        result2 = await task.result()
+        result3 = await task
+        result4 = await task.result()
+
+        # All should be the same cached object
+        assert result1 is result2 is result3 is result4
+
+
+async def test_different_tasks_have_separate_caches():
+    """Different task instances maintain separate caches."""
+    mcp = FastMCP("test")
+
+    @mcp.tool(task=True)
+    async def separate_tool(value: str) -> str:
+        return f"Result: {value}"
+
+    async with Client(mcp) as client:
+        task1 = await client.call_tool("separate_tool", {"value": "A"}, task=True)
+        task2 = await client.call_tool("separate_tool", {"value": "B"}, task=True)
+
+        result1 = await task1.result()
+        result2 = await task2.result()
+
+        # Different results
+        assert result1.data == "Result: A"
+        assert result2.data == "Result: B"
+
+        # Not the same object
+        assert result1 is not result2
+
+        # But each task's cache works independently
+        result1_again = await task1.result()
+        result2_again = await task2.result()
+
+        assert result1 is result1_again
+        assert result2 is result2_again
+
+
+async def test_cache_survives_status_checks():
+    """Calling status() doesn't affect result caching."""
+    mcp = FastMCP("test")
+
+    @mcp.tool(task=True)
+    async def status_check_tool() -> str:
+        return "status"
+
+    async with Client(mcp) as client:
+        task = await client.call_tool("status_check_tool", task=True)
+
+        # Check status multiple times
+        await task.status()
+        await task.status()
+
+        result1 = await task.result()
+
+        # Check status again
+        await task.status()
+
+        result2 = await task.result()
+
+        # Cache should still work
+        assert result1 is result2
+
+
+async def test_cache_survives_wait_calls():
+    """Calling wait() doesn't affect result caching."""
+    mcp = FastMCP("test")
+
+    @mcp.tool(task=True)
+    async def wait_test_tool() -> str:
+        return "waited"
+
+    async with Client(mcp) as client:
+        task = await client.call_tool("wait_test_tool", task=True)
+
+        # Wait for completion
+        await task.wait()
+
+        result1 = await task.result()
+
+        # Wait again (no-op since completed)
+        await task.wait()
+
+        result2 = await task.result()
+
+        # Cache should still work
+        assert result1 is result2
diff --git a/tests/client/telemetry/__init__.py b/tests/client/telemetry/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/client/telemetry/test_client_list_tracing.py b/tests/client/telemetry/test_client_list_tracing.py
new file mode 100644
index 0000000..aaf08d0
--- /dev/null
+++ b/tests/client/telemetry/test_client_list_tracing.py
@@ -0,0 +1,185 @@
+"""Tests for client OpenTelemetry tracing on list operations."""
+
+from __future__ import annotations
+
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+from opentelemetry.trace import SpanKind
+
+from fastmcp import Client, FastMCP
+
+
+class TestClientListToolsTracing:
+    """Tests for client tools/list tracing."""
+
+    async def test_list_tools_creates_client_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        server = FastMCP("test-server")
+
+        @server.tool()
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        client = Client(server)
+        async with client:
+            tools = await client.list_tools()
+            assert len(tools) == 1
+
+        spans = trace_exporter.get_finished_spans()
+        client_spans = [
+            s
+            for s in spans
+            if s.name == "tools/list"
+            and s.attributes is not None
+            and "fastmcp.server.name" not in s.attributes
+            and "fastmcp.component.key" in s.attributes
+        ]
+        assert len(client_spans) >= 1
+
+        span = client_spans[0]
+        assert span.kind == SpanKind.CLIENT
+        assert span.attributes is not None
+        assert span.attributes["mcp.method.name"] == "tools/list"
+
+    async def test_list_tools_creates_both_client_and_server_spans(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        server = FastMCP("test-server")
+
+        @server.tool()
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        client = Client(server)
+        async with client:
+            await client.list_tools()
+
+        spans = trace_exporter.get_finished_spans()
+        tools_list_spans = [s for s in spans if s.name == "tools/list"]
+        assert len(tools_list_spans) >= 2
+
+        client_span = next(
+            (
+                s
+                for s in tools_list_spans
+                if s.attributes is not None
+                and "fastmcp.server.name" not in s.attributes
+                and "fastmcp.component.key" in s.attributes
+            ),
+            None,
+        )
+        server_span = next(
+            (
+                s
+                for s in tools_list_spans
+                if s.attributes is not None and "fastmcp.server.name" in s.attributes
+            ),
+            None,
+        )
+
+        assert client_span is not None, "Client should create a span"
+        assert server_span is not None, "Server should create a span"
+        assert client_span.kind == SpanKind.CLIENT
+        assert server_span.kind == SpanKind.SERVER
+
+
+class TestClientListResourcesTracing:
+    """Tests for client resources/list tracing."""
+
+    async def test_list_resources_creates_client_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        server = FastMCP("test-server")
+
+        @server.resource("data://config")
+        def get_config() -> str:
+            return "config"
+
+        client = Client(server)
+        async with client:
+            resources = await client.list_resources()
+            assert len(resources) >= 1
+
+        spans = trace_exporter.get_finished_spans()
+        client_spans = [
+            s
+            for s in spans
+            if s.name == "resources/list"
+            and s.attributes is not None
+            and "fastmcp.server.name" not in s.attributes
+            and "fastmcp.component.key" in s.attributes
+        ]
+        assert len(client_spans) >= 1
+
+        span = client_spans[0]
+        assert span.kind == SpanKind.CLIENT
+        assert span.attributes is not None
+        assert span.attributes["mcp.method.name"] == "resources/list"
+
+
+class TestClientListResourceTemplatesTracing:
+    """Tests for client resources/templates/list tracing."""
+
+    async def test_list_resource_templates_creates_client_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        server = FastMCP("test-server")
+
+        @server.resource("users://{user_id}/profile")
+        def get_profile(user_id: str) -> str:
+            return f"profile {user_id}"
+
+        client = Client(server)
+        async with client:
+            templates = await client.list_resource_templates()
+            assert len(templates) >= 1
+
+        spans = trace_exporter.get_finished_spans()
+        client_spans = [
+            s
+            for s in spans
+            if s.name == "resources/templates/list"
+            and s.attributes is not None
+            and "fastmcp.server.name" not in s.attributes
+            and "fastmcp.component.key" in s.attributes
+        ]
+        assert len(client_spans) >= 1
+
+        span = client_spans[0]
+        assert span.kind == SpanKind.CLIENT
+        assert span.attributes is not None
+        assert span.attributes["mcp.method.name"] == "resources/templates/list"
+
+
+class TestClientListPromptsTracing:
+    """Tests for client prompts/list tracing."""
+
+    async def test_list_prompts_creates_client_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        server = FastMCP("test-server")
+
+        @server.prompt()
+        def greeting() -> str:
+            return "Hello!"
+
+        client = Client(server)
+        async with client:
+            prompts = await client.list_prompts()
+            assert len(prompts) == 1
+
+        spans = trace_exporter.get_finished_spans()
+        client_spans = [
+            s
+            for s in spans
+            if s.name == "prompts/list"
+            and s.attributes is not None
+            and "fastmcp.server.name" not in s.attributes
+            and "fastmcp.component.key" in s.attributes
+        ]
+        assert len(client_spans) >= 1
+
+        span = client_spans[0]
+        assert span.kind == SpanKind.CLIENT
+        assert span.attributes is not None
+        assert span.attributes["mcp.method.name"] == "prompts/list"
diff --git a/tests/client/telemetry/test_client_tracing.py b/tests/client/telemetry/test_client_tracing.py
new file mode 100644
index 0000000..1180a40
--- /dev/null
+++ b/tests/client/telemetry/test_client_tracing.py
@@ -0,0 +1,704 @@
+"""Tests for client OpenTelemetry tracing."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+
+import pytest
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+from opentelemetry.trace import SpanKind, StatusCode
+
+from fastmcp import Client, FastMCP
+from fastmcp.exceptions import ToolError
+
+
+class TestClientToolTracing:
+    """Tests for client tool call tracing."""
+
+    async def test_call_tool_creates_span(self, trace_exporter: InMemorySpanExporter):
+        server = FastMCP("test-server")
+
+        @server.tool()
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        client = Client(server)
+        async with client:
+            result = await client.call_tool("greet", {"name": "World"})
+            assert "Hello, World!" in str(result)
+
+        spans = trace_exporter.get_finished_spans()
+        span_names = [s.name for s in spans]
+
+        # Client should create "tools/call greet" span
+        assert "tools/call greet" in span_names
+
+    async def test_call_tool_span_attributes(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        server = FastMCP("test-server")
+
+        @server.tool()
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        client = Client(server)
+        async with client:
+            await client.call_tool("add", {"a": 1, "b": 2})
+
+        spans = trace_exporter.get_finished_spans()
+
+        # Find client-side span (doesn't have fastmcp.server.name)
+        client_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "tools/call add"
+                and s.attributes is not None
+                and "fastmcp.server.name" not in s.attributes
+                and "fastmcp.component.key" in s.attributes
+            ),
+            None,
+        )
+        assert client_span is not None
+        assert client_span.attributes is not None
+        # Standard MCP semantic conventions
+        assert client_span.attributes["mcp.method.name"] == "tools/call"
+        # gen_ai semantic conventions
+        assert client_span.attributes["gen_ai.tool.name"] == "add"
+        # RPC attributes must NOT be present
+        assert "rpc.system" not in client_span.attributes
+        assert "rpc.method" not in client_span.attributes
+        # FastMCP-specific attributes
+        assert client_span.attributes["fastmcp.component.key"] == "add"
+
+    async def test_call_tool_error_caught_by_client_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        """Tool error should be reflected on the client span via isError check."""
+        server = FastMCP("test-server")
+
+        @server.tool()
+        def failing_tool() -> str:
+            raise ValueError("boom")
+
+        client = Client(server)
+        async with client:
+            with pytest.raises(ToolError):
+                await client.call_tool("failing_tool", {})
+
+        spans = trace_exporter.get_finished_spans()
+
+        # Find the client span (from call_tool_mcp)
+        client_spans = [
+            s
+            for s in spans
+            if s.name == "tools/call failing_tool"
+            and s.attributes is not None
+            and "fastmcp.server.name" not in s.attributes
+            and "fastmcp.component.key" in s.attributes
+        ]
+
+        # Exactly one client span should exist (no duplicate from call_tool)
+        assert len(client_spans) == 1, (
+            "There should be exactly one client span for call_tool"
+        )
+
+        error_span = client_spans[0]
+        assert error_span.status.status_code == StatusCode.ERROR
+        assert error_span.attributes is not None
+        assert error_span.attributes["error.type"] == "tool_error"
+
+
+class TestClientResourceTracing:
+    """Tests for client resource read tracing."""
+
+    async def test_read_resource_creates_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        server = FastMCP("test-server")
+
+        @server.resource("data://config")
+        def get_config() -> str:
+            return "config data"
+
+        client = Client(server)
+        async with client:
+            result = await client.read_resource("data://config")
+            assert "config data" in str(result)
+
+        spans = trace_exporter.get_finished_spans()
+        span_names = [s.name for s in spans]
+
+        # Client should create "resources/read" span (URI in attributes, not name)
+        assert "resources/read" in span_names
+
+    async def test_read_resource_span_attributes(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        server = FastMCP("test-server")
+
+        @server.resource("data://config")
+        def get_config() -> str:
+            return "config value"
+
+        client = Client(server)
+        async with client:
+            await client.read_resource("data://config")
+
+        spans = trace_exporter.get_finished_spans()
+
+        # Find client-side resource span (doesn't have fastmcp.server.name)
+        client_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "resources/read"
+                and s.attributes is not None
+                and "fastmcp.server.name" not in s.attributes
+                and "fastmcp.component.key" in s.attributes
+            ),
+            None,
+        )
+        assert client_span is not None
+        assert client_span.attributes is not None
+        # Standard MCP semantic conventions
+        assert client_span.attributes["mcp.method.name"] == "resources/read"
+        assert "data://" in str(client_span.attributes["mcp.resource.uri"])
+        # RPC attributes must NOT be present
+        assert "rpc.system" not in client_span.attributes
+        assert "rpc.method" not in client_span.attributes
+        # FastMCP-specific attributes
+        # The URI may be normalized with trailing slash
+        assert "data://" in str(client_span.attributes["fastmcp.component.key"])
+
+
+class TestClientPromptTracing:
+    """Tests for client prompt get tracing."""
+
+    async def test_get_prompt_creates_span(self, trace_exporter: InMemorySpanExporter):
+        server = FastMCP("test-server")
+
+        @server.prompt()
+        def greeting() -> str:
+            return "Hello from prompt!"
+
+        client = Client(server)
+        async with client:
+            result = await client.get_prompt("greeting")
+            assert "Hello from prompt!" in str(result)
+
+        spans = trace_exporter.get_finished_spans()
+        span_names = [s.name for s in spans]
+
+        # Client should create "prompts/get greeting" span
+        assert "prompts/get greeting" in span_names
+
+    async def test_get_prompt_span_attributes(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        server = FastMCP("test-server")
+
+        @server.prompt()
+        def welcome(name: str) -> str:
+            return f"Welcome, {name}!"
+
+        client = Client(server)
+        async with client:
+            await client.get_prompt("welcome", {"name": "Test"})
+
+        spans = trace_exporter.get_finished_spans()
+
+        # Find client-side prompt span (doesn't have fastmcp.server.name)
+        client_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "prompts/get welcome"
+                and s.attributes is not None
+                and "fastmcp.server.name" not in s.attributes
+                and "fastmcp.component.key" in s.attributes
+            ),
+            None,
+        )
+        assert client_span is not None
+        assert client_span.attributes is not None
+        # Standard MCP semantic conventions
+        assert client_span.attributes["mcp.method.name"] == "prompts/get"
+        # gen_ai semantic conventions
+        assert client_span.attributes["gen_ai.prompt.name"] == "welcome"
+        # RPC attributes must NOT be present
+        assert "rpc.system" not in client_span.attributes
+        assert "rpc.method" not in client_span.attributes
+        # FastMCP-specific attributes
+        assert client_span.attributes["fastmcp.component.key"] == "welcome"
+
+
+class TestClientServerSpanHierarchy:
+    """Tests for span relationships between client and server."""
+
+    async def test_client_and_server_spans_created(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        """Both client and server should create spans for the same operation."""
+        server = FastMCP("test-server")
+
+        @server.tool()
+        def echo(message: str) -> str:
+            return message
+
+        client = Client(server)
+        async with client:
+            await client.call_tool("echo", {"message": "test"})
+
+        spans = trace_exporter.get_finished_spans()
+
+        # Find client span (no fastmcp.server.name) and server span (has fastmcp.server.name)
+        client_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "tools/call echo"
+                and s.attributes is not None
+                and "fastmcp.server.name" not in s.attributes
+                and "fastmcp.component.key" in s.attributes
+            ),
+            None,
+        )
+        server_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "tools/call echo"
+                and s.attributes is not None
+                and "fastmcp.server.name" in s.attributes
+            ),
+            None,
+        )
+
+        # Both spans should exist
+        assert client_span is not None, "Client should create a span"
+        assert client_span.attributes is not None
+        assert server_span is not None, "Server should create a span"
+        assert server_span.attributes is not None
+
+        # Verify span kinds are correct
+        assert client_span.kind == SpanKind.CLIENT, "Client span should be CLIENT kind"
+        assert server_span.kind == SpanKind.SERVER, "Server span should be SERVER kind"
+
+        # Verify the spans have different characteristics
+        assert client_span.attributes["mcp.method.name"] == "tools/call"
+        assert server_span.attributes["fastmcp.server.name"] == "test-server"
+
+    async def test_trace_context_propagation(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        """Server span should be a child of client span via trace context propagation."""
+        server = FastMCP("test-server")
+
+        @server.tool()
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        client = Client(server)
+        async with client:
+            await client.call_tool("add", {"a": 1, "b": 2})
+
+        spans = trace_exporter.get_finished_spans()
+
+        # Find client span and server span
+        client_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "tools/call add"
+                and s.attributes is not None
+                and "fastmcp.server.name" not in s.attributes
+                and "fastmcp.component.key" in s.attributes
+            ),
+            None,
+        )
+        server_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "tools/call add"
+                and s.attributes is not None
+                and "fastmcp.server.name" in s.attributes
+            ),
+            None,
+        )
+
+        assert client_span is not None, "Client span should exist"
+        assert server_span is not None, "Server span should exist"
+
+        # Verify trace context propagation: server span should be a descendant
+        # of the client span, sharing the same trace_id. SDK v2 emits its own
+        # intermediate spans (e.g. "MCP send tools/call add") between the FastMCP
+        # client span and the server span, so the server span's parent is one of
+        # those SDK spans rather than the client span directly. Assert descendant
+        # relationship by walking the parent chain instead of a direct parent.
+        assert server_span.context.trace_id == client_span.context.trace_id, (
+            "Server and client spans should share the same trace_id"
+        )
+
+        spans_by_id = {s.context.span_id: s for s in spans}
+        assert server_span.parent is not None, "Server span should have a parent"
+        current = server_span
+        found_client_ancestor = False
+        while current.parent is not None:
+            parent = spans_by_id.get(current.parent.span_id)
+            if parent is None:
+                break
+            if parent.context.span_id == client_span.context.span_id:
+                found_client_ancestor = True
+                break
+            current = parent
+        assert found_client_ancestor, (
+            "Server span should be a descendant of the client span"
+        )
+
+
+class TestClientErrorTracing:
+    """Tests for client span creation during errors.
+
+    Note: MCP protocol errors are returned as successful responses with error content,
+    so client spans may not have ERROR status even when the operation fails. This is
+    different from server-side where exceptions happen inside the span.
+
+    The server-side span WILL have ERROR status because the exception occurs within
+    the server's span context. The client span represents the successful MCP protocol
+    round-trip, while application-level errors are communicated via the response.
+    """
+
+    async def test_call_tool_error_creates_spans(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        """Both client and server spans should be created when tool fails."""
+        server = FastMCP("test-server")
+
+        @server.tool()
+        def failing_tool() -> str:
+            raise ValueError("Something went wrong")
+
+        client = Client(server)
+        async with client:
+            with pytest.raises(ToolError):
+                await client.call_tool("failing_tool", {})
+
+        spans = trace_exporter.get_finished_spans()
+
+        # Find client-side span
+        client_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "tools/call failing_tool"
+                and s.attributes is not None
+                and "fastmcp.server.name" not in s.attributes
+                and "fastmcp.component.key" in s.attributes
+            ),
+            None,
+        )
+        # Find server-side span
+        server_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "tools/call failing_tool"
+                and s.attributes is not None
+                and "fastmcp.server.name" in s.attributes
+            ),
+            None,
+        )
+
+        # Both spans should exist
+        assert client_span is not None, "Client should create a span"
+        assert server_span is not None, "Server should create a span"
+
+        # Server span should have ERROR status (exception inside span)
+        assert server_span.status.status_code == StatusCode.ERROR
+
+    async def test_read_resource_error_creates_spans(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        """Both client and server spans should be created when resource read fails."""
+        server = FastMCP("test-server")
+
+        @server.resource("data://fail")
+        def failing_resource() -> str:
+            raise ValueError("Resource error")
+
+        client = Client(server)
+        async with client:
+            with pytest.raises(Exception):
+                await client.read_resource("data://fail")
+
+        spans = trace_exporter.get_finished_spans()
+
+        # Find client-side span
+        client_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "resources/read"
+                and s.attributes is not None
+                and "fastmcp.server.name" not in s.attributes
+                and "fastmcp.component.key" in s.attributes
+            ),
+            None,
+        )
+        # Find server-side span
+        server_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "resources/read"
+                and s.attributes is not None
+                and "fastmcp.server.name" in s.attributes
+            ),
+            None,
+        )
+
+        # Both spans should exist
+        assert client_span is not None, "Client should create a span"
+        assert server_span is not None, "Server should create a span"
+
+        # Server span should have ERROR status
+        assert server_span.status.status_code == StatusCode.ERROR
+
+    async def test_get_prompt_error_creates_spans(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        """Both client and server spans should be created when prompt get fails."""
+        server = FastMCP("test-server")
+
+        @server.prompt()
+        def failing_prompt() -> str:
+            raise ValueError("Prompt error")
+
+        client = Client(server)
+        async with client:
+            with pytest.raises(Exception):
+                await client.get_prompt("failing_prompt", {})
+
+        spans = trace_exporter.get_finished_spans()
+
+        # Find client-side span
+        client_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "prompts/get failing_prompt"
+                and s.attributes is not None
+                and "fastmcp.server.name" not in s.attributes
+                and "fastmcp.component.key" in s.attributes
+            ),
+            None,
+        )
+        # Find server-side span
+        server_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "prompts/get failing_prompt"
+                and s.attributes is not None
+                and "fastmcp.server.name" in s.attributes
+            ),
+            None,
+        )
+
+        # Both spans should exist
+        assert client_span is not None, "Client should create a span"
+        assert server_span is not None, "Server should create a span"
+
+        # Server span should have ERROR status
+        assert server_span.status.status_code == StatusCode.ERROR
+
+    async def test_call_nonexistent_tool_creates_spans(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        """Both client and server spans should be created for nonexistent tool."""
+        server = FastMCP("test-server")
+
+        client = Client(server)
+        async with client:
+            with pytest.raises(Exception):
+                await client.call_tool("nonexistent", {})
+
+        spans = trace_exporter.get_finished_spans()
+
+        # Find client-side span
+        client_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "tools/call nonexistent"
+                and s.attributes is not None
+                and "fastmcp.server.name" not in s.attributes
+                and "fastmcp.component.key" in s.attributes
+            ),
+            None,
+        )
+        # Find server-side span
+        server_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "tools/call nonexistent"
+                and s.attributes is not None
+                and "fastmcp.server.name" in s.attributes
+            ),
+            None,
+        )
+
+        # Both spans should exist
+        assert client_span is not None, "Client should create a span"
+        assert server_span is not None, "Server should create a span"
+
+        # Server span should have ERROR status
+        assert server_span.status.status_code == StatusCode.ERROR
+
+
+class TestSessionIdOnSpans:
+    """Tests for session ID capture on client and server spans.
+
+    Session IDs are only available with HTTP transport (StreamableHttp).
+    """
+
+    @pytest.fixture
+    async def http_server_url(self) -> AsyncGenerator[str, None]:
+        """Start an HTTP server and return its URL."""
+        from fastmcp.utilities.tests import run_server_async
+
+        server = FastMCP("session-test-server")
+
+        @server.tool()
+        def echo(message: str) -> str:
+            return message
+
+        async with run_server_async(server) as url:
+            yield url
+
+    async def test_client_span_includes_session_id(
+        self,
+        trace_exporter: InMemorySpanExporter,
+        http_server_url: str,
+    ):
+        """Client span should include session ID when using HTTP transport."""
+        from fastmcp.client.transports import StreamableHttpTransport
+
+        transport = StreamableHttpTransport(http_server_url)
+        client = Client(transport=transport)
+        async with client:
+            await client.call_tool("echo", {"message": "test"})
+
+        spans = trace_exporter.get_finished_spans()
+
+        # Find the FastMCP client-side span. SDK v2 emits its own native OTel
+        # spans (also lacking `fastmcp.server.name`), so select on the
+        # `fastmcp.component.key` attribute that only our client_span sets.
+        client_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "tools/call echo"
+                and s.attributes is not None
+                and "fastmcp.component.key" in s.attributes
+                and "fastmcp.server.name" not in s.attributes
+                and "fastmcp.component.key" in s.attributes
+            ),
+            None,
+        )
+
+        assert client_span is not None, "Client should create a span"
+        assert client_span.attributes is not None
+        assert "mcp.session.id" in client_span.attributes
+        assert client_span.attributes["mcp.session.id"] is not None
+
+    async def test_server_span_includes_session_id(
+        self,
+        trace_exporter: InMemorySpanExporter,
+        http_server_url: str,
+    ):
+        """Server span should include session ID when called via HTTP."""
+        from fastmcp.client.transports import StreamableHttpTransport
+
+        transport = StreamableHttpTransport(http_server_url)
+        client = Client(transport=transport)
+        async with client:
+            await client.call_tool("echo", {"message": "test"})
+
+        spans = trace_exporter.get_finished_spans()
+
+        # Find server-side span
+        server_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "tools/call echo"
+                and s.attributes is not None
+                and "fastmcp.server.name" in s.attributes
+            ),
+            None,
+        )
+
+        assert server_span is not None, "Server should create a span"
+        assert server_span.attributes is not None
+        assert "mcp.session.id" in server_span.attributes
+        assert server_span.attributes["mcp.session.id"] is not None
+
+    async def test_client_and_server_share_same_session_id(
+        self,
+        trace_exporter: InMemorySpanExporter,
+        http_server_url: str,
+    ):
+        """Client and server spans should have the same session ID."""
+        from fastmcp.client.transports import StreamableHttpTransport
+
+        transport = StreamableHttpTransport(http_server_url)
+        client = Client(transport=transport)
+        async with client:
+            await client.call_tool("echo", {"message": "test"})
+
+        spans = trace_exporter.get_finished_spans()
+
+        # Find both spans. Select the FastMCP client span on
+        # `fastmcp.component.key` to avoid matching SDK v2's native OTel span.
+        client_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "tools/call echo"
+                and s.attributes is not None
+                and "fastmcp.component.key" in s.attributes
+                and "fastmcp.server.name" not in s.attributes
+                and "fastmcp.component.key" in s.attributes
+            ),
+            None,
+        )
+        server_span = next(
+            (
+                s
+                for s in spans
+                if s.name == "tools/call echo"
+                and s.attributes is not None
+                and "fastmcp.server.name" in s.attributes
+            ),
+            None,
+        )
+
+        assert client_span is not None
+        assert client_span.attributes is not None
+        assert server_span is not None
+        assert server_span.attributes is not None
+
+        # Both should have session IDs and they should match
+        client_session = client_span.attributes.get("mcp.session.id")
+        server_session = server_span.attributes.get("mcp.session.id")
+
+        assert client_session is not None, "Client span should have session ID"
+        assert server_session is not None, "Server span should have session ID"
+        assert client_session == server_session, (
+            "Client and server should share the same session ID"
+        )
diff --git a/tests/client/test_elicitation.py b/tests/client/test_elicitation.py
new file mode 100644
index 0000000..1db3060
--- /dev/null
+++ b/tests/client/test_elicitation.py
@@ -0,0 +1,803 @@
+from dataclasses import asdict, dataclass
+from enum import Enum
+from typing import Any, Literal, cast
+
+import pytest
+from mcp_types import ElicitRequestFormParams, ElicitRequestParams
+from pydantic import BaseModel
+from typing_extensions import TypedDict
+
+from fastmcp import Context, FastMCP
+from fastmcp.client.client import Client
+from fastmcp.client.elicitation import ElicitResult
+from fastmcp.exceptions import ToolError
+from fastmcp.server.elicitation import (
+    AcceptedElicitation,
+    CancelledElicitation,
+    DeclinedElicitation,
+    validate_elicitation_json_schema,
+)
+from fastmcp.utilities.types import TypeAdapter
+
+
+@pytest.fixture
+def fastmcp_server():
+    mcp = FastMCP("TestServer")
+
+    @dataclass
+    class Person:
+        name: str
+
+    @mcp.tool
+    async def ask_for_name(context: Context) -> str:
+        result = await context.elicit(
+            message="What is your name?",
+            response_type=Person,
+        )
+        if result.action == "accept":
+            assert isinstance(result, AcceptedElicitation)
+            assert isinstance(result.data, Person)
+            return f"Hello, {result.data.name}!"
+        else:
+            return "No name provided."
+
+    @mcp.tool
+    def simple_test() -> str:
+        return "Hello!"
+
+    return mcp
+
+
+async def test_elicitation_with_no_handler(fastmcp_server):
+    """Test that elicitation works without a handler."""
+
+    async with Client(fastmcp_server) as client:
+        with pytest.raises(ToolError, match="Elicitation not supported"):
+            await client.call_tool("ask_for_name")
+
+
+async def test_elicitation_accept_content(fastmcp_server):
+    """Test basic elicitation functionality."""
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        # Mock user providing their name
+        return ElicitResult(action="accept", content=response_type(name="Alice"))
+
+    async with Client(
+        fastmcp_server, elicitation_handler=elicitation_handler
+    ) as client:
+        result = await client.call_tool("ask_for_name")
+        assert result.data == "Hello, Alice!"
+
+
+async def test_elicitation_decline(fastmcp_server):
+    """Test that elicitation handler receives correct parameters."""
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        return ElicitResult(action="decline")
+
+    async with Client(
+        fastmcp_server, elicitation_handler=elicitation_handler
+    ) as client:
+        result = await client.call_tool("ask_for_name")
+        assert result.data == "No name provided."
+
+
+async def test_elicitation_handler_parameters():
+    """Test that elicitation handler receives correct parameters."""
+    mcp = FastMCP("TestServer")
+    captured_params = {}
+
+    @mcp.tool
+    async def test_tool(context: Context) -> str:
+        await context.elicit(
+            message="Test message",
+            response_type=int,
+        )
+        return "done"
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        captured_params["message"] = message
+        captured_params["response_type"] = str(response_type)
+        captured_params["params"] = params
+        captured_params["ctx"] = ctx
+        return ElicitResult(action="accept", content={"value": 42})
+
+    async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+        await client.call_tool("test_tool", {})
+
+        assert captured_params["message"] == "Test message"
+        assert "ScalarElicitationType" in str(captured_params["response_type"])
+        assert captured_params["params"].requested_schema == {
+            "properties": {"value": {"title": "Value", "type": "integer"}},
+            "required": ["value"],
+            "title": "ScalarElicitationType",
+            "type": "object",
+        }
+        assert captured_params["ctx"] is not None
+
+
+async def test_elicitation_response_title_and_description_on_scalar():
+    """response_title and response_description customize the wrapped `value` field."""
+    mcp = FastMCP("TestServer")
+    captured_schema: dict[str, Any] = {}
+
+    @mcp.tool
+    async def confirm_purchase(context: Context) -> str:
+        result = await context.elicit(
+            message="Buy 1x Baguette?",
+            response_type=bool,
+            response_title="Confirm purchase",
+            response_description="Approve this transaction?",
+        )
+        if isinstance(result, AcceptedElicitation):
+            return "confirmed" if result.data else "rejected"
+        return "no answer"
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        captured_schema.update(params.requested_schema)
+        return ElicitResult(action="accept", content={"value": True})
+
+    async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+        await client.call_tool("confirm_purchase", {})
+
+    assert captured_schema["properties"]["value"]["title"] == "Confirm purchase"
+    assert (
+        captured_schema["properties"]["value"]["description"]
+        == "Approve this transaction?"
+    )
+    assert captured_schema["properties"]["value"]["type"] == "boolean"
+
+
+async def test_elicitation_response_title_on_dict_shorthand():
+    """response_title applies to the `value` property for dict shorthand."""
+    mcp = FastMCP("TestServer")
+    captured_schema: dict[str, Any] = {}
+
+    @mcp.tool
+    async def pick_priority(context: Context) -> str:
+        result = await context.elicit(
+            message="Priority?",
+            response_type={"low": {"title": "Low"}, "high": {"title": "High"}},
+            response_title="Priority level",
+        )
+        return "ok" if isinstance(result, AcceptedElicitation) else "none"
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        captured_schema.update(params.requested_schema)
+        return ElicitResult(action="accept", content={"value": "low"})
+
+    async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+        await client.call_tool("pick_priority", {})
+
+    assert captured_schema["properties"]["value"]["title"] == "Priority level"
+
+
+async def test_elicitation_response_title_on_list_shorthand():
+    """response_title applies to the `value` property for list shorthand."""
+    mcp = FastMCP("TestServer")
+    captured_schema: dict[str, Any] = {}
+
+    @mcp.tool
+    async def pick_color(context: Context) -> str:
+        result = await context.elicit(
+            message="Color?",
+            response_type=["red", "green", "blue"],
+            response_title="Favorite color",
+        )
+        return "ok" if isinstance(result, AcceptedElicitation) else "none"
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        captured_schema.update(params.requested_schema)
+        return ElicitResult(action="accept", content={"value": "red"})
+
+    async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+        await client.call_tool("pick_color", {})
+
+    assert captured_schema["properties"]["value"]["title"] == "Favorite color"
+
+
+async def test_elicitation_response_title_rejected_for_basemodel():
+    """response_title raises TypeError when response_type is a BaseModel."""
+    mcp = FastMCP("TestServer")
+
+    class Person(BaseModel):
+        name: str
+
+    @mcp.tool
+    async def ask(context: Context) -> str:
+        await context.elicit(
+            message="Name?",
+            response_type=Person,
+            response_title="Not allowed",
+        )
+        return "done"
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        return ElicitResult(action="accept", content={"name": "x"})
+
+    async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+        with pytest.raises(ToolError, match="response_title"):
+            await client.call_tool("ask", {})
+
+
+async def test_elicitation_response_title_rejected_for_none():
+    """response_title raises TypeError when response_type is None."""
+    mcp = FastMCP("TestServer")
+
+    @mcp.tool
+    async def ask(context: Context) -> str:
+        await context.elicit(
+            message="Confirm?",
+            response_type=None,
+            response_title="Not allowed",
+        )
+        return "done"
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        return ElicitResult(action="accept", content={})
+
+    async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+        with pytest.raises(ToolError, match="response_title"):
+            await client.call_tool("ask", {})
+
+
+async def test_elicitation_cancel_action():
+    """Test user canceling elicitation request."""
+    mcp = FastMCP("TestServer")
+
+    @mcp.tool
+    async def ask_for_optional_info(context: Context) -> str:
+        result = await context.elicit(
+            message="Optional: What's your age?", response_type=int
+        )
+        if result.action == "cancel":
+            return "Request was canceled"
+        elif result.action == "accept":
+            assert isinstance(result, AcceptedElicitation)
+            assert isinstance(result.data, int)
+            return f"Age: {result.data}"
+        else:
+            return "No response provided"
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        return ElicitResult(action="cancel")
+
+    async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+        result = await client.call_tool("ask_for_optional_info", {})
+        assert result.data == "Request was canceled"
+
+
+class TestScalarResponseTypes:
+    async def test_scalar_handler_return_is_auto_wrapped(self):
+        """Scalar handler returns are wrapped as {"value": ...} for scalar schemas."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        async def my_tool(context: Context) -> str:
+            result = await context.elicit(message="", response_type=str)
+            assert isinstance(result, AcceptedElicitation)
+            assert isinstance(result.data, str)
+            return result.data
+
+        async def elicitation_handler(message, response_type, params, ctx):
+            return ElicitResult(action="accept", content="Alice")
+
+        async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+            result = await client.call_tool("my_tool", {})
+            assert result.data == "Alice"
+
+    async def test_elicitation_no_response(self):
+        """Test elicitation with no response type."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        async def my_tool(context: Context) -> dict[str, Any]:
+            result = await context.elicit(message="", response_type=None)
+            assert isinstance(result, AcceptedElicitation)
+            assert isinstance(result.data, dict)
+            return cast(dict[str, Any], result.data)
+
+        async def elicitation_handler(
+            message, response_type, params: ElicitRequestParams, ctx
+        ):
+            assert isinstance(params, ElicitRequestFormParams)
+            assert params.requested_schema == {"type": "object", "properties": {}}
+            assert response_type is None
+            return ElicitResult(action="accept")
+
+        async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+            result = await client.call_tool("my_tool", {})
+            assert result.data is None
+
+    async def test_elicitation_empty_response(self):
+        """Test elicitation with empty response type."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        async def my_tool(context: Context) -> dict[str, Any]:
+            result = await context.elicit(message="", response_type=None)
+            assert result.action == "accept"
+            assert isinstance(result, AcceptedElicitation)
+            accepted = result
+            assert isinstance(accepted.data, dict)
+            return accepted.data
+
+        async def elicitation_handler(
+            message, response_type, params: ElicitRequestParams, ctx
+        ):
+            return ElicitResult(action="accept", content={})
+
+        async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+            result = await client.call_tool("my_tool", {})
+            assert result.data is None
+
+    async def test_elicitation_response_when_no_response_requested(self):
+        """Test elicitation with no response type."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        async def my_tool(context: Context) -> dict[str, Any]:
+            result = await context.elicit(message="", response_type=None)
+            assert result.action == "accept"
+            assert isinstance(result, AcceptedElicitation)
+            accepted = result
+            assert isinstance(accepted.data, dict)
+            return accepted.data
+
+        async def elicitation_handler(message, response_type, params, ctx):
+            return ElicitResult(action="accept", content={"value": "hello"})
+
+        async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+            with pytest.raises(
+                ToolError, match="Elicitation expected an empty response"
+            ):
+                await client.call_tool("my_tool", {})
+
+    async def test_elicitation_str_response(self):
+        """Test elicitation with string schema."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        async def my_tool(context: Context) -> str:
+            result = await context.elicit(message="", response_type=str)
+            assert isinstance(result, AcceptedElicitation)
+            assert isinstance(result.data, str)
+            return result.data
+
+        async def elicitation_handler(message, response_type, params, ctx):
+            return ElicitResult(action="accept", content={"value": "hello"})
+
+        async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+            result = await client.call_tool("my_tool", {})
+            assert result.data == "hello"
+
+    async def test_elicitation_int_response(self):
+        """Test elicitation with number schema."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        async def my_tool(context: Context) -> int:
+            result = await context.elicit(message="", response_type=int)
+            assert isinstance(result, AcceptedElicitation)
+            assert isinstance(result.data, int)
+            return result.data
+
+        async def elicitation_handler(message, response_type, params, ctx):
+            return ElicitResult(action="accept", content={"value": 42})
+
+        async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+            result = await client.call_tool("my_tool", {})
+            assert result.data == 42
+
+    async def test_elicitation_float_response(self):
+        """Test elicitation with number schema."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        async def my_tool(context: Context) -> float:
+            result = await context.elicit(message="", response_type=float)
+            assert isinstance(result, AcceptedElicitation)
+            assert isinstance(result.data, float)
+            return result.data
+
+        async def elicitation_handler(message, response_type, params, ctx):
+            return ElicitResult(action="accept", content={"value": 3.14})
+
+        async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+            result = await client.call_tool("my_tool", {})
+            assert result.data == 3.14
+
+    async def test_elicitation_bool_response(self):
+        """Test elicitation with boolean schema."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        async def my_tool(context: Context) -> bool:
+            result = await context.elicit(message="", response_type=bool)
+            assert isinstance(result, AcceptedElicitation)
+            assert isinstance(result.data, bool)
+            return result.data
+
+        async def elicitation_handler(message, response_type, params, ctx):
+            return ElicitResult(action="accept", content={"value": True})
+
+        async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+            result = await client.call_tool("my_tool", {})
+            assert result.data is True
+
+    async def test_elicitation_literal_response(self):
+        """Test elicitation with literal schema."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        async def my_tool(context: Context) -> Literal["x", "y"]:
+            # Literal types work at runtime but type checker doesn't recognize them in overloads
+            result = await context.elicit(message="", response_type=Literal["x", "y"])  # type: ignore[arg-type]  # ty:ignore[no-matching-overload]
+            assert isinstance(result, AcceptedElicitation)
+            accepted = cast(AcceptedElicitation[Literal["x", "y"]], result)
+            assert isinstance(accepted.data, str)
+            return accepted.data
+
+        async def elicitation_handler(message, response_type, params, ctx):
+            return ElicitResult(action="accept", content={"value": "x"})
+
+        async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+            result = await client.call_tool("my_tool", {})
+            assert result.data == "x"
+
+    async def test_elicitation_enum_response(self):
+        """Test elicitation with enum schema."""
+        mcp = FastMCP("TestServer")
+
+        class ResponseEnum(Enum):
+            X = "x"
+            Y = "y"
+
+        @mcp.tool
+        async def my_tool(context: Context) -> ResponseEnum:
+            result = await context.elicit(message="", response_type=ResponseEnum)
+            assert isinstance(result, AcceptedElicitation)
+            assert isinstance(result.data, ResponseEnum)
+            return result.data
+
+        async def elicitation_handler(message, response_type, params, ctx):
+            return ElicitResult(action="accept", content={"value": "x"})
+
+        async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+            result = await client.call_tool("my_tool", {})
+            assert result.data == "x"
+
+    async def test_elicitation_list_of_strings_response(self):
+        """Test elicitation with list schema."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        async def my_tool(context: Context) -> str:
+            result = await context.elicit(message="", response_type=["x", "y"])
+            assert isinstance(result, AcceptedElicitation)
+            assert isinstance(result.data, str)
+            return result.data
+
+        async def elicitation_handler(message, response_type, params, ctx):
+            return ElicitResult(action="accept", content={"value": "x"})
+
+        async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+            result = await client.call_tool("my_tool", {})
+            assert result.data == "x"
+
+
+async def test_elicitation_handler_error():
+    """Test error handling in elicitation handler."""
+    mcp = FastMCP("TestServer")
+
+    @mcp.tool
+    async def failing_elicit(context: Context) -> str:
+        try:
+            result = await context.elicit(message="This will fail", response_type=str)
+
+            assert isinstance(result, AcceptedElicitation)
+
+            assert result.action == "accept"
+            return f"Got: {result.data}"
+        except Exception as e:
+            return f"Error: {str(e)}"
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        raise ValueError("Handler failed!")
+
+    async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+        result = await client.call_tool("failing_elicit", {})
+        assert "Error:" in result.data
+
+
+async def test_elicitation_multiple_calls():
+    """Test multiple elicitation calls in sequence."""
+    mcp = FastMCP("TestServer")
+
+    @mcp.tool
+    async def multi_step_form(context: Context) -> str:
+        # First question
+        name_result = await context.elicit(
+            message="What's your name?", response_type=str
+        )
+
+        assert isinstance(name_result, AcceptedElicitation)
+
+        if name_result.action != "accept":
+            return "Form abandoned"
+
+        # Second question
+        age_result = await context.elicit(message="What's your age?", response_type=int)
+
+        assert isinstance(age_result, AcceptedElicitation)
+
+        if age_result.action != "accept":
+            return f"Hello {name_result.data}, form incomplete"
+
+        return f"Hello {name_result.data}, you are {age_result.data} years old"
+
+    call_count = 0
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        nonlocal call_count
+        call_count += 1
+        if call_count == 1:
+            return ElicitResult(action="accept", content={"value": "Bob"})
+        elif call_count == 2:
+            return ElicitResult(action="accept", content={"value": 25})
+        else:
+            raise ValueError("Unexpected call")
+
+    async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+        result = await client.call_tool("multi_step_form", {})
+        assert result.data == "Hello Bob, you are 25 years old"
+        assert call_count == 2
+
+
+@dataclass
+class UserInfo:
+    name: str
+    age: int
+
+
+class UserInfoTypedDict(TypedDict):
+    name: str
+    age: int
+
+
+class UserInfoPydantic(BaseModel):
+    name: str
+    age: int
+
+
+@pytest.mark.parametrize(
+    "structured_type", [UserInfo, UserInfoTypedDict, UserInfoPydantic]
+)
+async def test_structured_response_type(
+    structured_type: type[UserInfo | UserInfoTypedDict | UserInfoPydantic],
+):
+    """Test elicitation with dataclass response type."""
+    mcp = FastMCP("TestServer")
+
+    @mcp.tool
+    async def get_user_info(context: Context) -> str:
+        result = await context.elicit(
+            message="Please provide your information", response_type=structured_type
+        )
+
+        assert isinstance(result, AcceptedElicitation)
+
+        if result.action == "accept":
+            assert isinstance(result, AcceptedElicitation)
+            if isinstance(result.data, dict):
+                data_dict = cast(dict[str, Any], result.data)
+                name = data_dict.get("name")
+                age = data_dict.get("age")
+                assert name is not None
+                assert age is not None
+                return f"User: {name}, age: {age}"
+            else:
+                # result.data is a structured type (UserInfo, UserInfoTypedDict, or UserInfoPydantic)
+                assert hasattr(result.data, "name")
+                assert hasattr(result.data, "age")
+                return f"User: {result.data.name}, age: {result.data.age}"
+        return "No user info provided"
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        # Verify we get the dataclass type
+        assert (
+            TypeAdapter(response_type).json_schema()
+            == TypeAdapter(structured_type).json_schema()
+        )
+
+        # Verify the schema has the dataclass fields (available in params)
+        schema = params.requested_schema
+        assert schema["type"] == "object"
+        assert "name" in schema["properties"]
+        assert "age" in schema["properties"]
+        assert schema["properties"]["name"]["type"] == "string"
+        assert schema["properties"]["age"]["type"] == "integer"
+
+        return ElicitResult(action="accept", content=UserInfo(name="Alice", age=30))
+
+    async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+        result = await client.call_tool("get_user_info", {})
+        assert result.data == "User: Alice, age: 30"
+
+
+async def test_all_primitive_field_types():
+    class DataEnum(Enum):
+        X = "x"
+        Y = "y"
+
+    @dataclass
+    class Data:
+        integer: int
+        float_: float
+        number: int | float
+        boolean: bool
+        string: str
+        constant: Literal["x"]
+        union: Literal["x"] | Literal["y"]
+        choice: Literal["x", "y"]
+        enum: DataEnum
+
+    mcp = FastMCP("TestServer")
+
+    @mcp.tool
+    async def get_data(context: Context) -> Data:
+        result = await context.elicit(message="Enter data", response_type=Data)
+        assert isinstance(result, AcceptedElicitation)
+        assert isinstance(result.data, Data)
+        return result.data
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        return ElicitResult(
+            action="accept",
+            content=Data(
+                integer=1,
+                float_=1.0,
+                number=1.0,
+                boolean=True,
+                string="hello",
+                constant="x",
+                union="x",
+                choice="x",
+                enum=DataEnum.X,
+            ),
+        )
+
+    async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+        result = await client.call_tool("get_data", {})
+
+        # Now all literal/enum fields should be preserved as strings
+        result_data = asdict(result.data)
+        result_data_enum = result_data.pop("enum")
+        assert result_data_enum == "x"  # Should be a string now, not an enum
+        assert result_data == {
+            "integer": 1,
+            "float_": 1.0,
+            "number": 1.0,
+            "boolean": True,
+            "string": "hello",
+            "constant": "x",
+            "union": "x",
+            "choice": "x",
+        }
+
+
+class TestValidation:
+    async def test_schema_validation_rejects_non_object(self):
+        """Test that non-object schemas are rejected."""
+
+        with pytest.raises(TypeError, match="must be an object schema"):
+            validate_elicitation_json_schema({"type": "string"})
+
+    async def test_schema_validation_rejects_nested_objects(self):
+        """Test that nested object schemas are rejected."""
+
+        with pytest.raises(
+            TypeError, match="is an object, but nested objects are not allowed"
+        ):
+            validate_elicitation_json_schema(
+                {
+                    "type": "object",
+                    "properties": {
+                        "user": {
+                            "type": "object",
+                            "properties": {"name": {"type": "string"}},
+                        }
+                    },
+                }
+            )
+
+    async def test_schema_validation_rejects_arrays(self):
+        """Test that non-enum array schemas are rejected."""
+
+        with pytest.raises(TypeError, match="is an array, but arrays are only allowed"):
+            validate_elicitation_json_schema(
+                {
+                    "type": "object",
+                    "properties": {
+                        "users": {"type": "array", "items": {"type": "string"}}
+                    },
+                }
+            )
+
+
+class TestPatternMatching:
+    async def test_pattern_matching_accept(self):
+        """Test pattern matching with AcceptedElicitation."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        async def pattern_match_tool(context: Context) -> str:
+            result = await context.elicit("Enter your name:", response_type=str)
+
+            match result:
+                case AcceptedElicitation(data=name):
+                    return f"Hello {name}!"
+                case DeclinedElicitation():
+                    return "You declined"
+                case CancelledElicitation():
+                    return "Cancelled"
+                case _:
+                    return "Unknown result"
+
+        async def elicitation_handler(message, response_type, params, ctx):
+            return ElicitResult(action="accept", content={"value": "Alice"})
+
+        async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+            result = await client.call_tool("pattern_match_tool", {})
+            assert result.data == "Hello Alice!"
+
+    async def test_pattern_matching_decline(self):
+        """Test pattern matching with DeclinedElicitation."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        async def pattern_match_tool(context: Context) -> str:
+            result = await context.elicit("Enter your name:", response_type=str)
+
+            match result:
+                case AcceptedElicitation(data=name):
+                    return f"Hello {name}!"
+                case DeclinedElicitation():
+                    return "You declined"
+                case CancelledElicitation():
+                    return "Cancelled"
+                case _:
+                    return "Unknown result"
+
+        async def elicitation_handler(message, response_type, params, ctx):
+            return ElicitResult(action="decline")
+
+        async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+            result = await client.call_tool("pattern_match_tool", {})
+            assert result.data == "You declined"
+
+    async def test_pattern_matching_cancel(self):
+        """Test pattern matching with CancelledElicitation."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        async def pattern_match_tool(context: Context) -> str:
+            result = await context.elicit("Enter your name:", response_type=str)
+
+            match result:
+                case AcceptedElicitation(data=name):
+                    return f"Hello {name}!"
+                case DeclinedElicitation():
+                    return "You declined"
+                case CancelledElicitation():
+                    return "Cancelled"
+                case _:
+                    return "Unknown result"
+
+        async def elicitation_handler(message, response_type, params, ctx):
+            return ElicitResult(action="cancel")
+
+        async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+            result = await client.call_tool("pattern_match_tool", {})
+            assert result.data == "Cancelled"
diff --git a/tests/client/test_elicitation_enums.py b/tests/client/test_elicitation_enums.py
new file mode 100644
index 0000000..baa281e
--- /dev/null
+++ b/tests/client/test_elicitation_enums.py
@@ -0,0 +1,516 @@
+"""Tests for enum-based elicitation, multi-select, and default values."""
+
+from dataclasses import dataclass
+from enum import Enum
+
+import pytest
+from pydantic import BaseModel, Field
+
+from fastmcp import Context, FastMCP
+from fastmcp.client.client import Client
+from fastmcp.client.elicitation import ElicitResult
+from fastmcp.exceptions import ToolError
+from fastmcp.server.elicitation import (
+    AcceptedElicitation,
+    get_elicitation_schema,
+    validate_elicitation_json_schema,
+)
+
+
+@pytest.fixture
+def fastmcp_server():
+    mcp = FastMCP("TestServer")
+
+    @dataclass
+    class Person:
+        name: str
+
+    @mcp.tool
+    async def ask_for_name(context: Context) -> str:
+        result = await context.elicit(
+            message="What is your name?",
+            response_type=Person,
+        )
+        if result.action == "accept":
+            assert isinstance(result, AcceptedElicitation)
+            assert isinstance(result.data, Person)
+            return f"Hello, {result.data.name}!"
+        else:
+            return "No name provided."
+
+    @mcp.tool
+    def simple_test() -> str:
+        return "Hello!"
+
+    return mcp
+
+
+async def test_elicitation_implicit_acceptance(fastmcp_server):
+    """Test that elicitation handler can return data directly without ElicitResult wrapper."""
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        # Return data directly without wrapping in ElicitResult
+        # This should be treated as implicit acceptance
+        return response_type(name="Bob")
+
+    async with Client(
+        fastmcp_server, elicitation_handler=elicitation_handler
+    ) as client:
+        result = await client.call_tool("ask_for_name")
+        assert result.data == "Hello, Bob!"
+
+
+async def test_elicitation_implicit_acceptance_must_be_dict(fastmcp_server):
+    """Test that elicitation handler can return data directly without ElicitResult wrapper."""
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        # Return data directly without wrapping in ElicitResult
+        # This should be treated as implicit acceptance
+        return "Bob"
+
+    async with Client(
+        fastmcp_server, elicitation_handler=elicitation_handler
+    ) as client:
+        with pytest.raises(
+            ToolError,
+            match="Elicitation responses must be serializable as a JSON object",
+        ):
+            await client.call_tool("ask_for_name")
+
+
+def test_enum_elicitation_schema_inline():
+    """Test that enum schemas are generated inline without $ref/$defs for MCP compatibility."""
+
+    class Priority(Enum):
+        LOW = "low"
+        MEDIUM = "medium"
+        HIGH = "high"
+
+    @dataclass
+    class TaskRequest:
+        title: str
+        priority: Priority
+
+    # Generate elicitation schema
+    schema = get_elicitation_schema(TaskRequest)
+
+    # Verify no $defs section exists (enums should be inlined)
+    assert "$defs" not in schema, (
+        "Schema should not contain $defs - enums must be inline"
+    )
+
+    # Verify no $ref in properties
+    for prop_name, prop_schema in schema.get("properties", {}).items():
+        assert "$ref" not in prop_schema, (
+            f"Property {prop_name} contains $ref - should be inline"
+        )
+
+    # Verify the priority field has inline enum values
+    priority_schema = schema["properties"]["priority"]
+    assert "enum" in priority_schema, "Priority should have enum values inline"
+    assert priority_schema["enum"] == ["low", "medium", "high"]
+    assert priority_schema.get("type") == "string"
+
+    # Verify title field is a simple string
+    assert schema["properties"]["title"]["type"] == "string"
+
+
+def test_enum_elicitation_schema_inline_untitled():
+    """Test that enum schemas generate simple enum pattern (no automatic titles)."""
+
+    class TaskStatus(Enum):
+        NOT_STARTED = "not_started"
+        IN_PROGRESS = "in_progress"
+        COMPLETED = "completed"
+        ON_HOLD = "on_hold"
+
+    @dataclass
+    class TaskUpdate:
+        task_id: str
+        status: TaskStatus
+
+    # Generate elicitation schema
+    schema = get_elicitation_schema(TaskUpdate)
+
+    # Verify enum is inline
+    assert "$defs" not in schema
+    assert "$ref" not in str(schema)
+
+    status_schema = schema["properties"]["status"]
+    # Should generate simple enum pattern (no automatic title generation)
+    assert "enum" in status_schema
+    assert "oneOf" not in status_schema
+    assert "enumNames" not in status_schema
+    assert status_schema["enum"] == [
+        "not_started",
+        "in_progress",
+        "completed",
+        "on_hold",
+    ]
+
+
+async def test_dict_based_titled_single_select():
+    """Test dict-based titled single-select enum."""
+    mcp = FastMCP("TestServer")
+
+    @mcp.tool
+    async def my_tool(ctx: Context) -> str:
+        result = await ctx.elicit(
+            "Choose priority",
+            response_type={
+                "low": {"title": "Low Priority"},
+                "high": {"title": "High Priority"},
+            },
+        )
+        if result.action == "accept":
+            assert isinstance(result, AcceptedElicitation)
+            assert isinstance(result.data, str)
+            return result.data
+        return "declined"
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        # Verify schema follows SEP-1330 pattern with type: "string"
+        schema = params.requested_schema
+        assert schema["type"] == "object"
+        assert "value" in schema["properties"]
+        value_schema = schema["properties"]["value"]
+        assert value_schema["type"] == "string"
+        assert "oneOf" in value_schema
+        one_of = value_schema["oneOf"]
+        assert {"const": "low", "title": "Low Priority"} in one_of
+        assert {"const": "high", "title": "High Priority"} in one_of
+
+        return ElicitResult(action="accept", content={"value": "low"})
+
+    async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+        result = await client.call_tool("my_tool", {})
+        assert result.data == "low"
+
+
+async def test_list_list_multi_select_untitled():
+    """Test list[list[str]] for multi-select untitled shorthand."""
+    mcp = FastMCP("TestServer")
+
+    @mcp.tool
+    async def my_tool(ctx: Context) -> str:
+        result = await ctx.elicit(
+            "Choose tags",
+            response_type=[["bug", "feature", "documentation"]],
+        )
+        if result.action == "accept":
+            assert isinstance(result, AcceptedElicitation)
+            assert isinstance(result.data, list)
+            return ",".join(result.data)  # type: ignore[no-matching-overload]
+        return "declined"
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        # Verify schema has array with enum pattern
+        schema = params.requested_schema
+        assert schema["type"] == "object"
+        assert "value" in schema["properties"]
+        value_schema = schema["properties"]["value"]
+        assert value_schema["type"] == "array"
+        assert "enum" in value_schema["items"]
+        assert value_schema["items"]["enum"] == ["bug", "feature", "documentation"]
+
+        return ElicitResult(action="accept", content={"value": ["bug", "feature"]})
+
+    async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+        result = await client.call_tool("my_tool", {})
+        assert result.data == "bug,feature"
+
+
+async def test_list_dict_multi_select_titled():
+    """Test list[dict] for multi-select titled."""
+    mcp = FastMCP("TestServer")
+
+    @mcp.tool
+    async def my_tool(ctx: Context) -> str:
+        result = await ctx.elicit(
+            "Choose priorities",
+            response_type=[
+                {
+                    "low": {"title": "Low Priority"},
+                    "high": {"title": "High Priority"},
+                }
+            ],
+        )
+        if result.action == "accept":
+            assert isinstance(result, AcceptedElicitation)
+            assert isinstance(result.data, list)
+            return ",".join(result.data)  # type: ignore[no-matching-overload]
+        return "declined"
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        # Verify schema has array with SEP-1330 compliant items (anyOf pattern)
+        schema = params.requested_schema
+        assert schema["type"] == "object"
+        assert "value" in schema["properties"]
+        value_schema = schema["properties"]["value"]
+        assert value_schema["type"] == "array"
+        items_schema = value_schema["items"]
+        assert "anyOf" in items_schema
+        any_of = items_schema["anyOf"]
+        assert {"const": "low", "title": "Low Priority"} in any_of
+        assert {"const": "high", "title": "High Priority"} in any_of
+
+        return ElicitResult(action="accept", content={"value": ["low", "high"]})
+
+    async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+        result = await client.call_tool("my_tool", {})
+        assert result.data == "low,high"
+
+
+async def test_list_enum_multi_select():
+    """Test list[Enum] for multi-select with enum in dataclass field."""
+
+    class Priority(Enum):
+        LOW = "low"
+        MEDIUM = "medium"
+        HIGH = "high"
+
+    @dataclass
+    class TaskRequest:
+        priorities: list[Priority]
+
+    schema = get_elicitation_schema(TaskRequest)
+
+    priorities_schema = schema["properties"]["priorities"]
+    assert priorities_schema["type"] == "array"
+    assert "items" in priorities_schema
+    items_schema = priorities_schema["items"]
+    # Should have enum pattern for untitled enums
+    assert "enum" in items_schema
+    assert items_schema["enum"] == ["low", "medium", "high"]
+
+
+async def test_list_enum_multi_select_direct():
+    """Test list[Enum] type annotation passed directly to ctx.elicit()."""
+    mcp = FastMCP("TestServer")
+
+    class Priority(Enum):
+        LOW = "low"
+        MEDIUM = "medium"
+        HIGH = "high"
+
+    @mcp.tool
+    async def my_tool(ctx: Context) -> str:
+        result = await ctx.elicit(
+            "Choose priorities",
+            response_type=list[Priority],  # Type annotation for multi-select
+        )
+        if result.action == "accept":
+            assert isinstance(result, AcceptedElicitation)
+            assert isinstance(result.data, list)
+            priorities = result.data
+            return ",".join(
+                [p.value if isinstance(p, Priority) else str(p) for p in priorities]
+            )
+        return "declined"
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        # Verify schema has array with enum pattern
+        schema = params.requested_schema
+        assert schema["type"] == "object"
+        assert "value" in schema["properties"]
+        value_schema = schema["properties"]["value"]
+        assert value_schema["type"] == "array"
+        assert "enum" in value_schema["items"]
+        assert value_schema["items"]["enum"] == ["low", "medium", "high"]
+
+        return ElicitResult(action="accept", content={"value": ["low", "high"]})
+
+    async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+        result = await client.call_tool("my_tool", {})
+        assert result.data == "low,high"
+
+
+async def test_validation_allows_enum_arrays():
+    """Test validation accepts arrays with enum items."""
+    schema = {
+        "type": "object",
+        "properties": {
+            "priorities": {
+                "type": "array",
+                "items": {"enum": ["low", "medium", "high"]},
+            }
+        },
+    }
+    validate_elicitation_json_schema(schema)  # Should not raise
+
+
+async def test_validation_allows_enum_arrays_with_anyof():
+    """Test validation accepts arrays with anyOf enum pattern (SEP-1330 compliant)."""
+    schema = {
+        "type": "object",
+        "properties": {
+            "priorities": {
+                "type": "array",
+                "items": {
+                    "anyOf": [
+                        {"const": "low", "title": "Low Priority"},
+                        {"const": "high", "title": "High Priority"},
+                    ]
+                },
+            }
+        },
+    }
+    validate_elicitation_json_schema(schema)  # Should not raise
+
+
+async def test_validation_rejects_non_enum_arrays():
+    """Test validation still rejects arrays of objects."""
+    schema = {
+        "type": "object",
+        "properties": {
+            "users": {
+                "type": "array",
+                "items": {"type": "object", "properties": {"name": {"type": "string"}}},
+            }
+        },
+    }
+    with pytest.raises(TypeError, match="array of objects"):
+        validate_elicitation_json_schema(schema)
+
+
+async def test_validation_rejects_primitive_arrays():
+    """Test validation rejects arrays of primitives without enum pattern."""
+    schema = {
+        "type": "object",
+        "properties": {
+            "names": {"type": "array", "items": {"type": "string"}},
+        },
+    }
+    with pytest.raises(TypeError, match="arrays are only allowed"):
+        validate_elicitation_json_schema(schema)
+
+
+class TestElicitationDefaults:
+    """Test suite for default values in elicitation schemas."""
+
+    def test_string_default_preserved(self):
+        """Test that string defaults are preserved in the schema."""
+
+        class Model(BaseModel):
+            email: str = Field(default="[email protected]")
+
+        schema = get_elicitation_schema(Model)
+        props = schema.get("properties", {})
+
+        assert "email" in props
+        assert "default" in props["email"]
+        assert props["email"]["default"] == "[email protected]"
+        assert props["email"]["type"] == "string"
+
+    def test_integer_default_preserved(self):
+        """Test that integer defaults are preserved in the schema."""
+
+        class Model(BaseModel):
+            count: int = Field(default=50)
+
+        schema = get_elicitation_schema(Model)
+        props = schema.get("properties", {})
+
+        assert "count" in props
+        assert "default" in props["count"]
+        assert props["count"]["default"] == 50
+        assert props["count"]["type"] == "integer"
+
+    def test_number_default_preserved(self):
+        """Test that number defaults are preserved in the schema."""
+
+        class Model(BaseModel):
+            price: float = Field(default=3.14)
+
+        schema = get_elicitation_schema(Model)
+        props = schema.get("properties", {})
+
+        assert "price" in props
+        assert "default" in props["price"]
+        assert props["price"]["default"] == 3.14
+        assert props["price"]["type"] == "number"
+
+    def test_boolean_default_preserved(self):
+        """Test that boolean defaults are preserved in the schema."""
+
+        class Model(BaseModel):
+            enabled: bool = Field(default=False)
+
+        schema = get_elicitation_schema(Model)
+        props = schema.get("properties", {})
+
+        assert "enabled" in props
+        assert "default" in props["enabled"]
+        assert props["enabled"]["default"] is False
+        assert props["enabled"]["type"] == "boolean"
+
+    def test_enum_default_preserved(self):
+        """Test that enum defaults are preserved in the schema."""
+
+        class Priority(Enum):
+            LOW = "low"
+            MEDIUM = "medium"
+            HIGH = "high"
+
+        class Model(BaseModel):
+            choice: Priority = Field(default=Priority.MEDIUM)
+
+        schema = get_elicitation_schema(Model)
+        props = schema.get("properties", {})
+
+        assert "choice" in props
+        assert "default" in props["choice"]
+        assert props["choice"]["default"] == "medium"
+        assert "enum" in props["choice"]
+        assert props["choice"]["type"] == "string"
+
+    def test_all_defaults_preserved_together(self):
+        """Test that all default types are preserved when used together."""
+
+        class Priority(Enum):
+            A = "A"
+            B = "B"
+
+        class Model(BaseModel):
+            string_field: str = Field(default="[email protected]")
+            integer_field: int = Field(default=50)
+            number_field: float = Field(default=3.14)
+            boolean_field: bool = Field(default=False)
+            enum_field: Priority = Field(default=Priority.A)
+
+        schema = get_elicitation_schema(Model)
+        props = schema.get("properties", {})
+
+        assert props["string_field"]["default"] == "[email protected]"
+        assert props["integer_field"]["default"] == 50
+        assert props["number_field"]["default"] == 3.14
+        assert props["boolean_field"]["default"] is False
+        assert props["enum_field"]["default"] == "A"
+
+    def test_mixed_defaults_and_required(self):
+        """Test that fields with defaults are not in required list."""
+
+        class Model(BaseModel):
+            required_field: str = Field(description="Required field")
+            optional_with_default: int = Field(default=42)
+
+        schema = get_elicitation_schema(Model)
+        props = schema.get("properties", {})
+        required = schema.get("required", [])
+
+        assert "required_field" in required
+        assert "optional_with_default" not in required
+        assert props["optional_with_default"]["default"] == 42
+
+    def test_compress_schema_preserves_defaults(self):
+        """Test that compress_schema() doesn't strip default values."""
+
+        class Model(BaseModel):
+            string_field: str = Field(default="test")
+            integer_field: int = Field(default=42)
+
+        schema = get_elicitation_schema(Model)
+        props = schema.get("properties", {})
+
+        assert "default" in props["string_field"]
+        assert "default" in props["integer_field"]
diff --git a/tests/client/test_logs.py b/tests/client/test_logs.py
new file mode 100644
index 0000000..43b6e1d
--- /dev/null
+++ b/tests/client/test_logs.py
@@ -0,0 +1,371 @@
+import logging
+
+import pytest
+from mcp import LoggingLevel
+from mcp_types import LoggingMessageNotificationParams
+
+from fastmcp import Client, Context, FastMCP
+from fastmcp.client.logging import LogMessage, create_log_callback
+
+
+class LogHandler:
+    def __init__(self):
+        self.logs: list[LogMessage] = []
+        self.logger = logging.getLogger(__name__)
+        # Backwards-compatible way to get the log level mapping
+        if hasattr(logging, "getLevelNamesMapping"):
+            # For Python 3.11+
+            self.LOGGING_LEVEL_MAP = logging.getLevelNamesMapping()  # pyright: ignore [reportAttributeAccessIssue]
+        else:
+            # For older Python versions
+            self.LOGGING_LEVEL_MAP = logging._nameToLevel
+
+    async def handle_log(self, message: LogMessage) -> None:
+        self.logs.append(message)
+
+        level = self.LOGGING_LEVEL_MAP[message.level.upper()]
+        msg = message.data.get("msg")
+        extra = message.data.get("extra")
+        self.logger.log(level, msg, extra=extra)
+
+
+@pytest.fixture
+def fastmcp_server():
+    mcp = FastMCP()
+
+    @mcp.tool
+    async def log(context: Context) -> None:
+        await context.info(message="hello?")
+
+    @mcp.tool
+    async def echo_log(
+        message: str,
+        context: Context,
+        level: LoggingLevel | None = None,
+        logger: str | None = None,
+    ) -> None:
+        await context.log(message=message, level=level)
+
+    return mcp
+
+
+class TestClientLogs:
+    async def test_log(self, fastmcp_server: FastMCP, caplog):
+        caplog.set_level(logging.INFO, logger=__name__)
+
+        log_handler = LogHandler()
+        async with Client(fastmcp_server, log_handler=log_handler.handle_log) as client:
+            await client.call_tool("log", {})
+
+        assert len(log_handler.logs) == 1
+        assert log_handler.logs[0].data["msg"] == "hello?"
+        assert log_handler.logs[0].level == "info"
+
+        assert len(caplog.records) == 1
+        assert caplog.records[0].msg == "hello?"
+        assert caplog.records[0].levelname == "INFO"
+
+    async def test_echo_log(self, fastmcp_server: FastMCP, caplog):
+        caplog.set_level(logging.INFO, logger=__name__)
+
+        log_handler = LogHandler()
+        async with Client(fastmcp_server, log_handler=log_handler.handle_log) as client:
+            await client.call_tool("echo_log", {"message": "this is a log"})
+
+            assert len(log_handler.logs) == 1
+            assert len(caplog.records) == 1
+            await client.call_tool(
+                "echo_log", {"message": "this is a warning log", "level": "warning"}
+            )
+            assert len(log_handler.logs) == 2
+            assert len(caplog.records) == 2
+
+        assert log_handler.logs[0].data["msg"] == "this is a log"
+        assert log_handler.logs[0].level == "info"
+        assert log_handler.logs[1].data["msg"] == "this is a warning log"
+        assert log_handler.logs[1].level == "warning"
+
+        assert caplog.records[0].msg == "this is a log"
+        assert caplog.records[0].levelname == "INFO"
+        assert caplog.records[1].msg == "this is a warning log"
+        assert caplog.records[1].levelname == "WARNING"
+
+
+class TestSetLoggingLevel:
+    async def test_set_logging_level(self, fastmcp_server: FastMCP):
+        """Client can set the minimum log level and lower-level messages are suppressed."""
+        log_handler = LogHandler()
+        async with Client(fastmcp_server, log_handler=log_handler.handle_log) as client:
+            await client.set_logging_level("warning")
+            await client.call_tool(
+                "echo_log", {"message": "debug msg", "level": "debug"}
+            )
+            await client.call_tool("echo_log", {"message": "info msg", "level": "info"})
+            await client.call_tool(
+                "echo_log", {"message": "warning msg", "level": "warning"}
+            )
+            await client.call_tool(
+                "echo_log", {"message": "error msg", "level": "error"}
+            )
+
+        assert len(log_handler.logs) == 2
+        assert log_handler.logs[0].data["msg"] == "warning msg"
+        assert log_handler.logs[1].data["msg"] == "error msg"
+
+    async def test_set_logging_level_debug_allows_all(self, fastmcp_server: FastMCP):
+        """Setting level to debug allows all messages through."""
+        log_handler = LogHandler()
+        async with Client(fastmcp_server, log_handler=log_handler.handle_log) as client:
+            await client.set_logging_level("debug")
+            await client.call_tool(
+                "echo_log", {"message": "debug msg", "level": "debug"}
+            )
+            await client.call_tool("echo_log", {"message": "info msg", "level": "info"})
+
+        assert len(log_handler.logs) == 2
+
+    async def test_default_level_allows_all(self, fastmcp_server: FastMCP):
+        """Without calling set_logging_level, all messages are sent."""
+        log_handler = LogHandler()
+        async with Client(fastmcp_server, log_handler=log_handler.handle_log) as client:
+            await client.call_tool(
+                "echo_log", {"message": "debug msg", "level": "debug"}
+            )
+            await client.call_tool("echo_log", {"message": "info msg", "level": "info"})
+
+        assert len(log_handler.logs) == 2
+
+    async def test_server_default_client_log_level(self):
+        """Server-wide client_log_level filters messages for all sessions."""
+        mcp = FastMCP(client_log_level="error")
+
+        @mcp.tool
+        async def echo_log(
+            message: str, context: Context, level: LoggingLevel | None = None
+        ) -> None:
+            await context.log(message=message, level=level)
+
+        log_handler = LogHandler()
+        async with Client(mcp, log_handler=log_handler.handle_log) as client:
+            await client.call_tool("echo_log", {"message": "info msg", "level": "info"})
+            await client.call_tool(
+                "echo_log", {"message": "warning msg", "level": "warning"}
+            )
+            await client.call_tool(
+                "echo_log", {"message": "error msg", "level": "error"}
+            )
+
+        assert len(log_handler.logs) == 1
+        assert log_handler.logs[0].data["msg"] == "error msg"
+
+    async def test_session_level_overrides_server_default(self):
+        """Per-session setLevel overrides the server's client_log_level."""
+        mcp = FastMCP(client_log_level="error")
+
+        @mcp.tool
+        async def echo_log(
+            message: str, context: Context, level: LoggingLevel | None = None
+        ) -> None:
+            await context.log(message=message, level=level)
+
+        log_handler = LogHandler()
+        async with Client(mcp, log_handler=log_handler.handle_log) as client:
+            await client.set_logging_level("warning")
+            await client.call_tool("echo_log", {"message": "info msg", "level": "info"})
+            await client.call_tool(
+                "echo_log", {"message": "warning msg", "level": "warning"}
+            )
+            await client.call_tool(
+                "echo_log", {"message": "error msg", "level": "error"}
+            )
+
+        assert len(log_handler.logs) == 2
+        assert log_handler.logs[0].data["msg"] == "warning msg"
+        assert log_handler.logs[1].data["msg"] == "error msg"
+
+
+class TestDefaultLogHandler:
+    """Tests for default_log_handler with data as any JSON-serializable type."""
+
+    async def test_default_handler_routes_to_correct_levels(self):
+        """Test that default_log_handler routes server logs to appropriate Python log levels."""
+        from unittest.mock import MagicMock, patch
+
+        from mcp_types import LoggingMessageNotificationParams
+
+        from fastmcp.client.logging import default_log_handler
+
+        with patch("fastmcp.client.logging.from_server_logger") as mock_logger:
+            # Set up mock methods
+            mock_logger.debug = MagicMock()
+            mock_logger.info = MagicMock()
+            mock_logger.warning = MagicMock()
+            mock_logger.error = MagicMock()
+            mock_logger.critical = MagicMock()
+
+            # Test each log level
+            test_cases = [
+                ("debug", mock_logger.debug, "Debug message"),
+                ("info", mock_logger.info, "Info message"),
+                ("notice", mock_logger.info, "Notice message"),  # notice -> info
+                ("warning", mock_logger.warning, "Warning message"),
+                ("error", mock_logger.error, "Error message"),
+                ("critical", mock_logger.critical, "Critical message"),
+                ("alert", mock_logger.critical, "Alert message"),  # alert -> critical
+                (
+                    "emergency",
+                    mock_logger.critical,
+                    "Emergency message",
+                ),  # emergency -> critical
+            ]
+
+            for level, expected_method, msg in test_cases:
+                # Reset mocks
+                mock_logger.reset_mock()
+
+                # Create log message with data as a string
+                log_msg = LoggingMessageNotificationParams(
+                    level=level,  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+                    logger="test.logger",
+                    data=msg,
+                )
+
+                # Call handler
+                await default_log_handler(log_msg)
+
+                # Verify correct method was called
+                expected_method.assert_called_once_with(
+                    msg=f"Received {level.upper()} from server (test.logger): {msg}"
+                )
+
+    async def test_default_handler_without_logger_name(self):
+        """Test that default_log_handler works when logger name is None."""
+        from unittest.mock import MagicMock, patch
+
+        from mcp_types import LoggingMessageNotificationParams
+
+        from fastmcp.client.logging import default_log_handler
+
+        with patch("fastmcp.client.logging.from_server_logger") as mock_logger:
+            mock_logger.info = MagicMock()
+
+            log_msg = LoggingMessageNotificationParams(
+                level="info",
+                logger=None,
+                data="Message without logger",
+            )
+
+            await default_log_handler(log_msg)
+
+            mock_logger.info.assert_called_once_with(
+                msg="Received INFO from server: Message without logger"
+            )
+
+    async def test_default_handler_with_dict_data(self):
+        """Test that default_log_handler handles dict data correctly."""
+        from unittest.mock import MagicMock, patch
+
+        from mcp_types import LoggingMessageNotificationParams
+
+        from fastmcp.client.logging import default_log_handler
+
+        with patch("fastmcp.client.logging.from_server_logger") as mock_logger:
+            mock_logger.info = MagicMock()
+
+            log_msg = LoggingMessageNotificationParams(
+                level="info",
+                logger="test.logger",
+                data={"key": "value", "count": 42},
+            )
+
+            await default_log_handler(log_msg)
+
+            # Should log the entire dict as a string
+            mock_logger.info.assert_called_once()
+            call_args = mock_logger.info.call_args
+            assert "Received INFO from server (test.logger):" in call_args[1]["msg"]
+            assert "key" in call_args[1]["msg"]
+            assert "value" in call_args[1]["msg"]
+
+    async def test_default_handler_with_list_data(self):
+        """Test that default_log_handler handles list data correctly."""
+        from unittest.mock import MagicMock, patch
+
+        from mcp_types import LoggingMessageNotificationParams
+
+        from fastmcp.client.logging import default_log_handler
+
+        with patch("fastmcp.client.logging.from_server_logger") as mock_logger:
+            mock_logger.warning = MagicMock()
+
+            log_msg = LoggingMessageNotificationParams(
+                level="warning",
+                logger="test.logger",
+                data=["item1", "item2", "item3"],
+            )
+
+            await default_log_handler(log_msg)
+
+            # Should log the entire list as a string
+            mock_logger.warning.assert_called_once()
+            call_args = mock_logger.warning.call_args
+            assert "Received WARNING from server (test.logger):" in call_args[1]["msg"]
+            assert "item1" in call_args[1]["msg"]
+
+    async def test_default_handler_with_number_data(self):
+        """Test that default_log_handler handles numeric data correctly."""
+        from unittest.mock import MagicMock, patch
+
+        from mcp_types import LoggingMessageNotificationParams
+
+        from fastmcp.client.logging import default_log_handler
+
+        with patch("fastmcp.client.logging.from_server_logger") as mock_logger:
+            mock_logger.error = MagicMock()
+
+            log_msg = LoggingMessageNotificationParams(
+                level="error",
+                logger=None,
+                data=404,
+            )
+
+            await default_log_handler(log_msg)
+
+            mock_logger.error.assert_called_once_with(
+                msg="Received ERROR from server: 404"
+            )
+
+
+class TestCreateLogCallback:
+    async def test_callback_invokes_custom_handler(self):
+        seen: list[LoggingMessageNotificationParams] = []
+
+        async def handler(message: LoggingMessageNotificationParams) -> None:
+            seen.append(message)
+
+        message = LoggingMessageNotificationParams(
+            level="info",
+            logger="test.logger",
+            data={"msg": "hello"},
+        )
+        callback = create_log_callback(handler)
+
+        await callback(message)
+
+        assert seen == [message]
+
+    async def test_callback_uses_default_handler_when_none_is_provided(self, caplog):
+        caplog.set_level(logging.WARNING, logger="fastmcp.client.from_server")
+        message = LoggingMessageNotificationParams(
+            level="warning",
+            logger=None,
+            data="default",
+        )
+        callback = create_log_callback()
+
+        await callback(message)
+
+        assert len(caplog.records) == 1
+        assert caplog.records[0].name == "fastmcp.client.from_server"
+        assert caplog.records[0].levelname == "WARNING"
+        assert caplog.records[0].msg == "Received WARNING from server: default"
diff --git a/tests/client/test_notifications.py b/tests/client/test_notifications.py
new file mode 100644
index 0000000..0264c8e
--- /dev/null
+++ b/tests/client/test_notifications.py
@@ -0,0 +1,125 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+
+import mcp_types
+import pytest
+
+from fastmcp import Client, FastMCP
+from fastmcp.client.messages import MessageHandler
+from fastmcp.server.context import Context
+
+
+@dataclass
+class NotificationRecording:
+    """Record of a notification that was received."""
+
+    method: str
+    notification: mcp_types.ServerNotification
+    timestamp: datetime = field(default_factory=datetime.now)
+
+
+class RecordingMessageHandler(MessageHandler):
+    """A message handler that records all notifications."""
+
+    def __init__(self, name: str | None = None):
+        super().__init__()
+        self.notifications: list[NotificationRecording] = []
+        self.name = name
+
+    async def on_notification(self, message: mcp_types.ServerNotification) -> None:
+        """Record all notifications with timestamp."""
+        # SDK v2 delivers notifications unwrapped (no `.root` wrapper).
+        self.notifications.append(
+            NotificationRecording(method=message.method, notification=message)
+        )
+
+    def get_notifications(
+        self, method: str | None = None
+    ) -> list[NotificationRecording]:
+        """Get all recorded notifications, optionally filtered by method."""
+        if method is None:
+            return self.notifications
+        return [n for n in self.notifications if n.method == method]
+
+    def assert_notification_sent(self, method: str, times: int = 1) -> bool:
+        """Assert that a notification was sent a specific number of times."""
+        notifications = self.get_notifications(method)
+        actual_times = len(notifications)
+        assert actual_times == times, (
+            f"Expected {times} notifications for {method}, "
+            f"but received {actual_times} notifications"
+        )
+        return True
+
+    def assert_notification_not_sent(self, method: str) -> bool:
+        """Assert that a notification was not sent."""
+        notifications = self.get_notifications(method)
+        assert len(notifications) == 0, (
+            f"Expected no notifications for {method}, but received {len(notifications)}"
+        )
+        return True
+
+    def reset(self):
+        """Clear all recorded notifications."""
+        self.notifications.clear()
+
+
+@pytest.fixture
+def recording_message_handler():
+    """Fixture that provides a recording message handler instance."""
+    handler = RecordingMessageHandler(name="recording_message_handler")
+    yield handler
+
+
+class TestNotificationAPI:
+    """Test the notification API."""
+
+    async def test_send_notification_async(
+        self,
+        recording_message_handler: RecordingMessageHandler,
+    ):
+        """Test that send_notification sends immediately in async context."""
+        server = FastMCP(name="NotificationAPITestServer")
+
+        @server.tool
+        async def trigger_notification(ctx: Context) -> str:
+            """Send a notification using the async API."""
+            await ctx.send_notification(mcp_types.ToolListChangedNotification())
+            return "Notification sent"
+
+        async with Client(server, message_handler=recording_message_handler) as client:
+            recording_message_handler.reset()
+            await client.call_tool("trigger_notification", {})
+
+            recording_message_handler.assert_notification_sent(
+                "notifications/tools/list_changed", times=1
+            )
+
+    async def test_send_multiple_notifications(
+        self,
+        recording_message_handler: RecordingMessageHandler,
+    ):
+        """Test sending multiple different notification types."""
+        server = FastMCP(name="NotificationAPITestServer")
+
+        @server.tool
+        async def trigger_all_notifications(ctx: Context) -> str:
+            """Send all notification types."""
+            await ctx.send_notification(mcp_types.ToolListChangedNotification())
+            await ctx.send_notification(mcp_types.ResourceListChangedNotification())
+            await ctx.send_notification(mcp_types.PromptListChangedNotification())
+            return "All notifications sent"
+
+        async with Client(server, message_handler=recording_message_handler) as client:
+            recording_message_handler.reset()
+            await client.call_tool("trigger_all_notifications", {})
+
+            recording_message_handler.assert_notification_sent(
+                "notifications/tools/list_changed", times=1
+            )
+            recording_message_handler.assert_notification_sent(
+                "notifications/resources/list_changed", times=1
+            )
+            recording_message_handler.assert_notification_sent(
+                "notifications/prompts/list_changed", times=1
+            )
diff --git a/tests/client/test_oauth_callback_race.py b/tests/client/test_oauth_callback_race.py
new file mode 100644
index 0000000..1e1e75e
--- /dev/null
+++ b/tests/client/test_oauth_callback_race.py
@@ -0,0 +1,50 @@
+import anyio
+import httpx
+
+from fastmcp.client.oauth_callback import (
+    OAuthCallbackResult,
+    create_oauth_callback_server,
+)
+from fastmcp.utilities.http import find_available_port
+
+
+async def test_oauth_callback_result_ignores_subsequent_callbacks():
+    """Only the first callback should be captured in shared OAuth callback state."""
+    port = find_available_port()
+    result = OAuthCallbackResult()
+    result_ready = anyio.Event()
+    server = create_oauth_callback_server(
+        port=port,
+        result_container=result,
+        result_ready=result_ready,
+    )
+
+    async with anyio.create_task_group() as tg:
+        tg.start_soon(server.serve)
+
+        await anyio.sleep(0.05)
+
+        async with httpx.AsyncClient() as client:
+            first = await client.get(
+                f"http://127.0.0.1:{port}/callback?code=good&state=s1"
+            )
+            assert first.status_code == 200
+
+            await result_ready.wait()
+
+            second = await client.get(
+                f"http://127.0.0.1:{port}/callback?code=evil&state=s2"
+            )
+            assert second.status_code == 200
+
+        assert result.error is None
+        assert result.code == "good"
+        assert result.state == "s1"
+
+        tg.cancel_scope.cancel()
+
+
+def test_oauth_callback_server_uses_configured_host():
+    server = create_oauth_callback_server(port=find_available_port(), host="localhost")
+
+    assert server.config.host == "localhost"
diff --git a/tests/client/test_oauth_callback_xss.py b/tests/client/test_oauth_callback_xss.py
new file mode 100644
index 0000000..626fc77
--- /dev/null
+++ b/tests/client/test_oauth_callback_xss.py
@@ -0,0 +1,159 @@
+"""Comprehensive XSS protection tests for OAuth callback HTML rendering."""
+
+import pytest
+
+from fastmcp.client.oauth_callback import create_callback_html
+from fastmcp.utilities.ui import (
+    create_detail_box,
+    create_info_box,
+    create_page,
+    create_status_message,
+)
+
+
+def test_ui_create_page_escapes_title():
+    """Test that page title is properly escaped."""
+    xss_title = "<script>alert(1)</script>"
+    html = create_page("content", title=xss_title)
+    assert "&lt;script&gt;alert(1)&lt;/script&gt;" in html
+    assert "<script>alert(1)</script>" not in html
+
+
+def test_ui_create_status_message_escapes():
+    """Test that status messages are properly escaped."""
+    xss_message = "<img src=x onerror=alert(1)>"
+    html = create_status_message(xss_message)
+    assert "&lt;img src=x onerror=alert(1)&gt;" in html
+    assert "<img src=x onerror=alert(1)>" not in html
+
+
+def test_ui_create_info_box_escapes():
+    """Test that info box content is properly escaped."""
+    xss_content = "<iframe src=javascript:alert(1)></iframe>"
+    html = create_info_box(xss_content)
+    assert "&lt;iframe" in html
+    assert "<iframe src=javascript:alert(1)>" not in html
+
+
+def test_ui_create_detail_box_escapes():
+    """Test that detail box labels and values are properly escaped."""
+    xss_label = '<script>alert("label")</script>'
+    xss_value = '<script>alert("value")</script>'
+    html = create_detail_box([(xss_label, xss_value)])
+    assert "&lt;script&gt;" in html
+    assert '<script>alert("label")</script>' not in html
+    assert '<script>alert("value")</script>' not in html
+
+
+def test_callback_html_escapes_error_message():
+    """Test that XSS payloads in error messages are properly escaped."""
+    xss_payload = "<img/src/onerror=alert(1)>"
+    html = create_callback_html(xss_payload, is_success=False)
+
+    assert "&lt;img/src/onerror=alert(1)&gt;" in html
+    assert "<img/src/onerror=alert(1)>" not in html
+
+
+def test_callback_html_escapes_server_url():
+    """Test that XSS payloads in server_url are properly escaped."""
+    xss_payload = "<script>alert(1)</script>"
+    html = create_callback_html("Success", is_success=True, server_url=xss_payload)
+
+    assert "&lt;script&gt;alert(1)&lt;/script&gt;" in html
+    assert "<script>alert(1)</script>" not in html
+
+
+def test_callback_html_escapes_title():
+    """Test that XSS payloads in title are properly escaped."""
+    xss_payload = "<script>alert(document.domain)</script>"
+    html = create_callback_html("Success", title=xss_payload)
+
+    assert "&lt;script&gt;alert(document.domain)&lt;/script&gt;" in html
+    assert "<script>alert(document.domain)</script>" not in html
+
+
+def test_callback_html_mixed_content():
+    """Test that legitimate text mixed with XSS attempts is properly escaped."""
+    mixed_payload = "Error: <img src=x onerror=alert(1)> occurred"
+    html = create_callback_html(mixed_payload, is_success=False)
+
+    assert "&lt;img src=x onerror=alert(1)&gt;" in html
+    assert "Error:" in html
+    assert "occurred" in html
+    assert "<img src=x onerror=alert(1)>" not in html
+
+
+def test_callback_html_event_handlers():
+    """Test that event handler attributes are escaped."""
+    xss_payload = '" onload="alert(1)'
+    html = create_callback_html(xss_payload, is_success=False)
+
+    assert "&quot; onload=&quot;alert(1)" in html
+    assert '" onload="alert(1)' not in html
+
+
+def test_callback_html_special_characters():
+    """Test that special HTML characters are properly escaped."""
+    special_chars = "&<>\"'/"
+    html = create_callback_html(special_chars, is_success=False)
+
+    assert "&amp;" in html
+    assert "&lt;" in html
+    assert "&gt;" in html
+    assert "&quot;" in html
+    # Apostrophe gets escaped to &#x27; by html.escape()
+    assert "&#x27;" in html
+
+
+@pytest.mark.parametrize(
+    "xss_vector",
+    [
+        "<img src=x onerror=alert(1)>",
+        "<script>alert(document.cookie)</script>",
+        "<iframe src=javascript:alert(1)>",
+        "<svg/onload=alert(1)>",
+        "<body onload=alert(1)>",
+        "<input onfocus=alert(1) autofocus>",
+        "<select onfocus=alert(1) autofocus>",
+        "<textarea onfocus=alert(1) autofocus>",
+        "<marquee onstart=alert(1)>",
+        "<div style=background:url('javascript:alert(1)')>",
+    ],
+)
+def test_common_xss_vectors(xss_vector: str):
+    """Test that common XSS attack vectors are properly escaped."""
+    html = create_callback_html(xss_vector, is_success=False)
+
+    # Should not contain the raw XSS vector
+    assert xss_vector not in html
+
+    # Should contain escaped version (at least the < and > should be escaped)
+    assert "&lt;" in html
+    assert "&gt;" in html
+
+
+def test_legitimate_content_still_works():
+    """Ensure legitimate content is displayed correctly after escaping."""
+    legitimate_message = "Authentication failed: Invalid credentials"
+    legitimate_url = "https://example.com:8080/mcp"
+
+    # Error case
+    html = create_callback_html(legitimate_message, is_success=False)
+    assert legitimate_message in html
+    assert "Authentication failed" in html
+
+    # Success case
+    html = create_callback_html("Success", is_success=True, server_url=legitimate_url)
+    assert legitimate_url in html
+    assert "Authentication successful" in html
+
+
+def test_no_hardcoded_html_tags():
+    """Verify that there are no hardcoded HTML tags that bypass escaping."""
+    server_url = "test-server"
+    html = create_callback_html("Success", is_success=True, server_url=server_url)
+
+    # Should not have <strong> tags around the server URL
+    assert f"<strong>{server_url}</strong>" not in html
+    # Should have the server URL displayed normally (escaped)
+    assert server_url in html
diff --git a/tests/client/test_openapi.py b/tests/client/test_openapi.py
new file mode 100644
index 0000000..236e6ef
--- /dev/null
+++ b/tests/client/test_openapi.py
@@ -0,0 +1,203 @@
+import json
+
+import pytest
+from fastapi import FastAPI, Request
+from mcp_types import TextResourceContents
+
+from fastmcp import Client, FastMCP
+from fastmcp.client.transports import SSETransport, StreamableHttpTransport
+from fastmcp.server import create_proxy
+from fastmcp.server.providers.openapi import MCPType, RouteMap
+from fastmcp.utilities.tests import run_server_async
+
+
+def create_fastmcp_server_for_headers() -> FastMCP:
+    """Create a FastMCP server from FastAPI app with experimental parser."""
+    app = FastAPI()
+
+    @app.get("/headers")
+    def get_headers(request: Request):
+        return request.headers
+
+    @app.get("/headers/{header_name}")
+    def get_header_by_name(header_name: str, request: Request):
+        return request.headers[header_name]
+
+    @app.post("/headers")
+    def post_headers(request: Request):
+        return request.headers
+
+    mcp = FastMCP.from_fastapi(
+        app,
+        httpx_client_kwargs={"headers": {"x-server-header": "test-abc"}},
+        route_maps=[
+            # GET requests with path parameters go to ResourceTemplate
+            RouteMap(
+                methods=["GET"],
+                pattern=r".*\{.*\}.*",
+                mcp_type=MCPType.RESOURCE_TEMPLATE,
+            ),
+            # GET requests without path parameters go to Resource
+            RouteMap(methods=["GET"], pattern=r".*", mcp_type=MCPType.RESOURCE),
+        ],
+    )
+
+    return mcp
+
+
+@pytest.fixture
+async def shttp_server():
+    """Start a test server with StreamableHttp transport."""
+    server = create_fastmcp_server_for_headers()
+    async with run_server_async(server, transport="http") as url:
+        yield url
+
+
+@pytest.fixture
+async def sse_server():
+    """Start a test server with SSE transport."""
+    server = create_fastmcp_server_for_headers()
+    async with run_server_async(server, transport="sse") as url:
+        yield url
+
+
+@pytest.fixture
+async def proxy_server(shttp_server: str):
+    """Start a proxy server."""
+    proxy = create_proxy(StreamableHttpTransport(shttp_server))
+    async with run_server_async(proxy, transport="http") as url:
+        yield url
+
+
+async def test_fastapi_client_headers_streamable_http_resource(shttp_server: str):
+    async with Client(transport=StreamableHttpTransport(shttp_server)) as client:
+        result = await client.read_resource("resource://get_headers_headers_get")
+        assert isinstance(result[0], TextResourceContents)
+        headers = json.loads(result[0].text)
+        assert headers["x-server-header"] == "test-abc"
+
+
+async def test_fastapi_client_headers_sse_resource(sse_server: str):
+    async with Client(transport=SSETransport(sse_server)) as client:
+        result = await client.read_resource("resource://get_headers_headers_get")
+        assert isinstance(result[0], TextResourceContents)
+        headers = json.loads(result[0].text)
+        assert headers["x-server-header"] == "test-abc"
+
+
+async def test_fastapi_client_headers_streamable_http_tool(shttp_server: str):
+    async with Client(transport=StreamableHttpTransport(shttp_server)) as client:
+        result = await client.call_tool("post_headers_headers_post")
+        headers: dict[str, str] = result.data
+        assert headers["x-server-header"] == "test-abc"
+
+
+async def test_fastapi_client_headers_sse_tool(sse_server: str):
+    async with Client(transport=SSETransport(sse_server)) as client:
+        result = await client.call_tool("post_headers_headers_post")
+        headers: dict[str, str] = result.data
+        assert headers["x-server-header"] == "test-abc"
+
+
+async def test_client_headers_sse_resource(sse_server: str):
+    async with Client(
+        transport=SSETransport(sse_server, headers={"X-TEST": "test-123"})
+    ) as client:
+        result = await client.read_resource("resource://get_headers_headers_get")
+        assert isinstance(result[0], TextResourceContents)
+        headers = json.loads(result[0].text)
+        assert headers["x-test"] == "test-123"
+
+
+async def test_client_headers_shttp_resource(shttp_server: str):
+    async with Client(
+        transport=StreamableHttpTransport(shttp_server, headers={"X-TEST": "test-123"})
+    ) as client:
+        result = await client.read_resource("resource://get_headers_headers_get")
+        assert isinstance(result[0], TextResourceContents)
+        headers = json.loads(result[0].text)
+        assert headers["x-test"] == "test-123"
+
+
+async def test_client_headers_sse_resource_template(sse_server: str):
+    async with Client(
+        transport=SSETransport(sse_server, headers={"X-TEST": "test-123"})
+    ) as client:
+        result = await client.read_resource(
+            "resource://get_header_by_name_headers/x-test"
+        )
+        assert isinstance(result[0], TextResourceContents)
+        header = json.loads(result[0].text)
+        assert header == "test-123"
+
+
+async def test_client_headers_shttp_resource_template(shttp_server: str):
+    async with Client(
+        transport=StreamableHttpTransport(shttp_server, headers={"X-TEST": "test-123"})
+    ) as client:
+        result = await client.read_resource(
+            "resource://get_header_by_name_headers/x-test"
+        )
+        assert isinstance(result[0], TextResourceContents)
+        header = json.loads(result[0].text)
+        assert header == "test-123"
+
+
+async def test_client_headers_sse_tool(sse_server: str):
+    async with Client(
+        transport=SSETransport(sse_server, headers={"X-TEST": "test-123"})
+    ) as client:
+        result = await client.call_tool("post_headers_headers_post")
+        headers: dict[str, str] = result.data
+        assert headers["x-test"] == "test-123"
+
+
+async def test_client_headers_shttp_tool(shttp_server: str):
+    async with Client(
+        transport=StreamableHttpTransport(shttp_server, headers={"X-TEST": "test-123"})
+    ) as client:
+        result = await client.call_tool("post_headers_headers_post")
+        headers: dict[str, str] = result.data
+        assert headers["x-test"] == "test-123"
+
+
+async def test_client_overrides_server_headers(shttp_server: str):
+    async with Client(
+        transport=StreamableHttpTransport(
+            shttp_server, headers={"x-server-header": "test-client"}
+        )
+    ) as client:
+        result = await client.read_resource("resource://get_headers_headers_get")
+        assert isinstance(result[0], TextResourceContents)
+        headers = json.loads(result[0].text)
+        assert headers["x-server-header"] == "test-client"
+
+
+async def test_client_with_excluded_header_is_ignored(sse_server: str):
+    async with Client(
+        transport=SSETransport(
+            sse_server,
+            headers={
+                "x-server-header": "test-client",
+                "host": "1.2.3.4",
+                "not-host": "1.2.3.4",
+            },
+        )
+    ) as client:
+        result = await client.read_resource("resource://get_headers_headers_get")
+        assert isinstance(result[0], TextResourceContents)
+        headers = json.loads(result[0].text)
+        assert headers["not-host"] == "1.2.3.4"
+        assert headers["host"] == "fastapi"
+
+
+@pytest.mark.flaky(retries=2, delay=1)
+async def test_client_headers_proxy(proxy_server: str):
+    """
+    Test that client headers are passed through the proxy to the remove server.
+    """
+    async with Client(transport=StreamableHttpTransport(proxy_server)) as client:
+        result = await client.read_resource("resource://get_headers_headers_get")
+        assert isinstance(result[0], TextResourceContents)
+        headers = json.loads(result[0].text)
+        assert headers["x-server-header"] == "test-abc"
diff --git a/tests/client/test_progress.py b/tests/client/test_progress.py
new file mode 100644
index 0000000..946c5b6
--- /dev/null
+++ b/tests/client/test_progress.py
@@ -0,0 +1,76 @@
+import pytest
+
+from fastmcp import Client, Context, FastMCP
+
+PROGRESS_MESSAGES = []
+
+
+@pytest.fixture(autouse=True)
+def clear_progress_messages():
+    PROGRESS_MESSAGES.clear()
+    yield
+    PROGRESS_MESSAGES.clear()
+
+
+@pytest.fixture
+def fastmcp_server():
+    mcp = FastMCP()
+
+    @mcp.tool
+    async def progress_tool(context: Context) -> int:
+        for i in range(3):
+            await context.report_progress(
+                progress=i + 1,
+                total=3,
+                message=f"{(i + 1) / 3 * 100:.2f}% complete",
+            )
+        return 100
+
+    return mcp
+
+
+EXPECTED_PROGRESS_MESSAGES = [
+    dict(progress=1, total=3, message="33.33% complete"),
+    dict(progress=2, total=3, message="66.67% complete"),
+    dict(progress=3, total=3, message="100.00% complete"),
+]
+
+
+async def progress_handler(
+    progress: float, total: float | None, message: str | None
+) -> None:
+    PROGRESS_MESSAGES.append(dict(progress=progress, total=total, message=message))
+
+
+async def test_progress_handler(fastmcp_server: FastMCP):
+    async with Client(fastmcp_server, progress_handler=progress_handler) as client:
+        await client.call_tool("progress_tool", {})
+
+    assert PROGRESS_MESSAGES == EXPECTED_PROGRESS_MESSAGES
+
+
+async def test_progress_handler_can_be_supplied_on_tool_call(fastmcp_server: FastMCP):
+    async with Client(fastmcp_server) as client:
+        await client.call_tool("progress_tool", {}, progress_handler=progress_handler)
+
+    assert PROGRESS_MESSAGES == EXPECTED_PROGRESS_MESSAGES
+
+
+async def test_progress_handler_supplied_on_tool_call_overrides_default(
+    fastmcp_server: FastMCP,
+):
+    async def bad_progress_handler(
+        progress: float, total: float | None, message: str | None
+    ) -> None:
+        raise Exception("This should not be called")
+
+    async with Client(fastmcp_server, progress_handler=bad_progress_handler) as client:
+        await client.call_tool("progress_tool", {}, progress_handler=progress_handler)
+
+    assert PROGRESS_MESSAGES == EXPECTED_PROGRESS_MESSAGES
+
+
+async def test_default_progress_handler_handles_zero_total() -> None:
+    from fastmcp.client.progress import default_progress_handler
+
+    await default_progress_handler(progress=1, total=0, message="starting")
diff --git a/tests/client/test_roots.py b/tests/client/test_roots.py
new file mode 100644
index 0000000..d3bc7d5
--- /dev/null
+++ b/tests/client/test_roots.py
@@ -0,0 +1,44 @@
+import pytest
+
+from fastmcp import Client, Context, FastMCP
+
+
+@pytest.fixture
+def fastmcp_server():
+    mcp = FastMCP()
+
+    @mcp.tool
+    async def list_roots(context: Context) -> list[str]:
+        roots = await context.list_roots()
+        return [str(r.uri) for r in roots]
+
+    return mcp
+
+
+class TestClientRoots:
+    @pytest.mark.parametrize("roots", [["x"], ["x", "y"]])
+    async def test_invalid_roots(self, fastmcp_server: FastMCP, roots: list[str]):
+        """
+        Roots must be URIs
+        """
+        with pytest.raises(ValueError, match="Input should be a valid URL"):
+            async with Client(fastmcp_server, roots=roots):
+                pass
+
+    @pytest.mark.parametrize("roots", [["https://x.com"]])
+    async def test_invalid_urls(self, fastmcp_server: FastMCP, roots: list[str]):
+        """
+        At this time, root URIs must start with file://
+        """
+        with pytest.raises(ValueError, match="URL scheme should be 'file'"):
+            async with Client(fastmcp_server, roots=roots):
+                pass
+
+    @pytest.mark.parametrize("roots", [["file://x/y/z", "file://x/y/z"]])
+    async def test_valid_roots(self, fastmcp_server: FastMCP, roots: list[str]):
+        async with Client(fastmcp_server, roots=roots) as client:
+            result = await client.call_tool("list_roots", {})
+            assert result.data == [
+                "file://x/y/z",
+                "file://x/y/z",
+            ]
diff --git a/tests/client/test_sampling.py b/tests/client/test_sampling.py
new file mode 100644
index 0000000..2fc75e3
--- /dev/null
+++ b/tests/client/test_sampling.py
@@ -0,0 +1,346 @@
+import json
+from typing import cast
+from unittest.mock import AsyncMock
+
+import pytest
+from mcp_types import TextContent
+from pydantic_core import to_json
+
+from fastmcp import Client, Context, FastMCP
+from fastmcp.client.sampling import RequestContext, SamplingMessage, SamplingParams
+from fastmcp.server.sampling import SamplingResult, SamplingTool
+from fastmcp.utilities.types import Image
+
+
+@pytest.fixture
+def fastmcp_server():
+    mcp = FastMCP()
+
+    @mcp.tool
+    async def simple_sample(message: str, context: Context) -> str:
+        result = await context.sample("Hello, world!")
+        assert isinstance(result, SamplingResult)
+        assert result.text is not None
+        return result.text
+
+    @mcp.tool
+    async def sample_with_system_prompt(message: str, context: Context) -> str:
+        result = await context.sample("Hello, world!", system_prompt="You love FastMCP")
+        assert isinstance(result, SamplingResult)
+        assert result.text is not None
+        return result.text
+
+    @mcp.tool
+    async def sample_with_messages(message: str, context: Context) -> str:
+        result = await context.sample(
+            [
+                "Hello!",
+                SamplingMessage(
+                    content=TextContent(
+                        type="text", text="How can I assist you today?"
+                    ),
+                    role="assistant",
+                ),
+            ]
+        )
+        assert isinstance(result, SamplingResult)
+        assert result.text is not None
+        return result.text
+
+    @mcp.tool
+    async def sample_with_image(image_bytes: bytes, context: Context) -> str:
+        image = Image(data=image_bytes)
+
+        result = await context.sample(
+            [
+                SamplingMessage(
+                    content=TextContent(type="text", text="What's in this image?"),
+                    role="user",
+                ),
+                SamplingMessage(
+                    content=image.to_image_content(),
+                    role="user",
+                ),
+            ]
+        )
+        assert isinstance(result, SamplingResult)
+        assert result.text is not None
+        return result.text
+
+    return mcp
+
+
+async def test_simple_sampling(fastmcp_server: FastMCP):
+    def sampling_handler(
+        messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+    ) -> str:
+        return "This is the sample message!"
+
+    async with Client(fastmcp_server, sampling_handler=sampling_handler) as client:
+        result = await client.call_tool("simple_sample", {"message": "Hello, world!"})
+        assert result.data == "This is the sample message!"
+
+
+async def test_sampling_with_system_prompt(fastmcp_server: FastMCP):
+    def sampling_handler(
+        messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+    ) -> str:
+        assert params.system_prompt is not None
+        return params.system_prompt
+
+    async with Client(fastmcp_server, sampling_handler=sampling_handler) as client:
+        result = await client.call_tool(
+            "sample_with_system_prompt", {"message": "Hello, world!"}
+        )
+        assert result.data == "You love FastMCP"
+
+
+async def test_sampling_with_messages(fastmcp_server: FastMCP):
+    def sampling_handler(
+        messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+    ) -> str:
+        assert len(messages) == 2
+
+        assert isinstance(messages[0].content, TextContent)
+        assert messages[0].content.type == "text"
+        assert messages[0].content.text == "Hello!"
+
+        assert isinstance(messages[1].content, TextContent)
+        assert messages[1].content.type == "text"
+        assert messages[1].content.text == "How can I assist you today?"
+        return "I need to think."
+
+    async with Client(fastmcp_server, sampling_handler=sampling_handler) as client:
+        result = await client.call_tool(
+            "sample_with_messages", {"message": "Hello, world!"}
+        )
+        assert result.data == "I need to think."
+
+
+async def test_sampling_with_fallback(fastmcp_server: FastMCP):
+    openai_sampling_handler = AsyncMock(return_value="But I need to think")
+
+    fastmcp_server = FastMCP(
+        sampling_handler=openai_sampling_handler,
+    )
+
+    @fastmcp_server.tool
+    async def sample_with_fallback(context: Context) -> str:
+        sampling_result = await context.sample("Do not think.")
+        return cast(TextContent, sampling_result).text
+
+    client = Client(fastmcp_server)
+
+    async with client:
+        call_tool_result = await client.call_tool("sample_with_fallback")
+
+    assert call_tool_result.data == "But I need to think"
+
+
+async def test_sampling_with_image(fastmcp_server: FastMCP):
+    def sampling_handler(
+        messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+    ) -> str:
+        assert len(messages) == 2
+        return to_json(messages).decode()
+
+    async with Client(fastmcp_server, sampling_handler=sampling_handler) as client:
+        image_bytes = b"abc123"
+        result = await client.call_tool(
+            "sample_with_image", {"image_bytes": image_bytes}
+        )
+        assert json.loads(result.data) == [
+            {
+                "role": "user",
+                "content": {
+                    "type": "text",
+                    "text": "What's in this image?",
+                    "annotations": None,
+                    "_meta": None,
+                },
+                "_meta": None,
+            },
+            {
+                "role": "user",
+                "content": {
+                    "type": "image",
+                    "data": "YWJjMTIz",
+                    "mimeType": "image/png",
+                    "annotations": None,
+                    "_meta": None,
+                },
+                "_meta": None,
+            },
+        ]
+
+
+class TestSamplingDefaultCapabilities:
+    """Tests for default sampling capability advertisement (issue #3329)."""
+
+    async def test_default_sampling_capabilities_omit_tools(self):
+        """Default sampling capabilities should not include tools field.
+
+        When serialized with exclude_none=True (as the MCP session does),
+        the capability should produce {"sampling": {}} rather than
+        {"sampling": {"tools": {}}}, ensuring compatibility with servers
+        that don't recognize the tools sub-field (e.g. older Java MCP SDK).
+        """
+        import mcp_types
+
+        server = FastMCP()
+
+        def handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> str:
+            return "ok"
+
+        client = Client(server, sampling_handler=handler)
+        caps = client._session_kwargs["sampling_capabilities"]
+        assert isinstance(caps, mcp_types.SamplingCapability)
+        assert caps.tools is None
+
+    async def test_set_sampling_callback_default_capabilities_omit_tools(self):
+        """set_sampling_callback should also default to no tools capability."""
+        import mcp_types
+
+        server = FastMCP()
+        client = Client(server)
+        client.set_sampling_callback(lambda msgs, params, ctx: "ok")
+        caps = client._session_kwargs["sampling_capabilities"]
+        assert isinstance(caps, mcp_types.SamplingCapability)
+        assert caps.tools is None
+
+    async def test_explicit_tools_capability_is_preserved(self):
+        """Explicitly passing tools capability should be respected."""
+        import mcp_types
+
+        server = FastMCP()
+
+        def handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> str:
+            return "ok"
+
+        explicit_caps = mcp_types.SamplingCapability(
+            tools=mcp_types.SamplingToolsCapability()
+        )
+        client = Client(
+            server, sampling_handler=handler, sampling_capabilities=explicit_caps
+        )
+        caps = client._session_kwargs["sampling_capabilities"]
+        assert isinstance(caps, mcp_types.SamplingCapability)
+        assert caps.tools is not None
+
+
+class TestSamplingWithTools:
+    """Tests for sampling with tools functionality."""
+
+    async def test_sampling_with_tools_requires_capability(self):
+        """Test that sampling with tools raises error when client lacks capability."""
+        import mcp_types
+
+        from fastmcp.exceptions import ToolError
+
+        server = FastMCP()
+
+        def search(query: str) -> str:
+            """Search the web."""
+            return f"Results for: {query}"
+
+        @server.tool
+        async def sample_with_tool(context: Context) -> str:
+            # This should fail because the client doesn't advertise tools capability
+            result = await context.sample(
+                messages="Search for Python tutorials",
+                tools=[search],
+            )
+            return str(result)
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> str:
+            return "Response"
+
+        # Explicitly disable tools capability by passing SamplingCapability without tools
+        async with Client(
+            server,
+            sampling_handler=sampling_handler,
+            sampling_capabilities=mcp_types.SamplingCapability(),  # No tools
+        ) as client:
+            with pytest.raises(ToolError, match="sampling.tools capability"):
+                await client.call_tool("sample_with_tool", {})
+
+    async def test_sampling_with_tools_fallback_handler_can_return_string(self):
+        """Test that fallback handler can return a string even when tools are provided.
+
+        The LLM might choose not to use any tools and just return a text response.
+        """
+        # This handler returns a string - valid even when tools are provided
+        simple_handler = AsyncMock(return_value="Direct response without tools")
+
+        mcp = FastMCP(sampling_handler=simple_handler)
+
+        def search(query: str) -> str:
+            """Search the web."""
+            return f"Results for: {query}"
+
+        @mcp.tool
+        async def sample_with_tool(context: Context) -> str:
+            result = await context.sample(
+                messages="Search for Python tutorials",
+                tools=[search],
+            )
+            return result.text or "no text"
+
+        # Client without sampling handler - will use server's fallback
+        async with Client(mcp) as client:
+            result = await client.call_tool("sample_with_tool", {})
+
+        # Handler returned string directly, which is treated as final text response
+        assert result.data == "Direct response without tools"
+
+    def test_sampling_tool_schema(self):
+        """Test that SamplingTool generates correct schema."""
+
+        def search(query: str, limit: int = 10) -> str:
+            """Search the web for results."""
+            return f"Results for: {query}"
+
+        tool = SamplingTool.from_function(search)
+        assert tool.name == "search"
+        assert tool.description == "Search the web for results."
+        assert "query" in tool.parameters.get("properties", {})
+        assert "limit" in tool.parameters.get("properties", {})
+
+    async def test_sampling_tool_run(self):
+        """Test that SamplingTool.run() executes correctly."""
+
+        def add(a: int, b: int) -> int:
+            """Add two numbers."""
+            return a + b
+
+        tool = SamplingTool.from_function(add)
+        result = await tool.run({"a": 5, "b": 3})
+        assert result == 8
+
+    async def test_sampling_tool_run_async(self):
+        """Test that SamplingTool.run() works with async functions."""
+
+        async def async_multiply(a: int, b: int) -> int:
+            """Multiply two numbers."""
+            return a * b
+
+        tool = SamplingTool.from_function(async_multiply)
+        result = await tool.run({"a": 4, "b": 7})
+        assert result == 28
+
+    def test_tool_choice_parameter(self):
+        """Test that tool_choice parameter accepts string literals."""
+        from fastmcp.server.context import ToolChoiceOption
+
+        # Verify ToolChoiceOption type accepts the valid string values
+        choices: list[ToolChoiceOption] = ["auto", "required", "none"]
+        assert len(choices) == 3
+        assert "auto" in choices
+        assert "required" in choices
+        assert "none" in choices
diff --git a/tests/client/test_sampling_result_types.py b/tests/client/test_sampling_result_types.py
new file mode 100644
index 0000000..e581e25
--- /dev/null
+++ b/tests/client/test_sampling_result_types.py
@@ -0,0 +1,681 @@
+import pytest
+from mcp_types import CreateMessageResultWithTools, TextContent, ToolUseContent
+
+from fastmcp import Client, Context, FastMCP
+from fastmcp.client.sampling import RequestContext, SamplingMessage, SamplingParams
+
+
+class TestSamplingResultType:
+    """Tests for result_type parameter (structured output)."""
+
+    async def test_result_type_creates_final_response_tool(self):
+        """Test that result_type creates a synthetic final_response tool."""
+        from mcp_types import CreateMessageResultWithTools, ToolUseContent
+        from pydantic import BaseModel
+
+        class MathResult(BaseModel):
+            answer: int
+            explanation: str
+
+        received_tools: list = []
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> CreateMessageResultWithTools:
+            received_tools.extend(params.tools or [])
+
+            # Return the final_response tool call
+            return CreateMessageResultWithTools(
+                role="assistant",
+                content=[
+                    ToolUseContent(
+                        type="tool_use",
+                        id="call_1",
+                        name="final_response",
+                        input={"answer": 42, "explanation": "The meaning of life"},
+                    )
+                ],
+                model="test-model",
+                stop_reason="toolUse",
+            )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        @mcp.tool
+        async def math_tool(context: Context) -> str:
+            result = await context.sample(
+                messages="What is 6 * 7?",
+                result_type=MathResult,
+            )
+            # result.result should be a MathResult object
+            assert isinstance(result.result, MathResult)
+            return f"{result.result.answer}: {result.result.explanation}"
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("math_tool", {})
+
+        # Check that final_response tool was added
+        tool_names = [t.name for t in received_tools]
+        assert "final_response" in tool_names
+
+        # Check the result
+        assert result.data == "42: The meaning of life"
+
+    async def test_result_type_with_user_tools(self):
+        """Test result_type works alongside user-provided tools."""
+        from mcp_types import CreateMessageResultWithTools, ToolUseContent
+        from pydantic import BaseModel
+
+        class SearchResult(BaseModel):
+            summary: str
+            sources: list[str]
+
+        def search(query: str) -> str:
+            """Search for information."""
+            return f"Found info about: {query}"
+
+        call_count = 0
+        tool_was_called = False
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> CreateMessageResultWithTools:
+            nonlocal call_count, tool_was_called
+            call_count += 1
+
+            if call_count == 1:
+                # First call: use the search tool
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_1",
+                            name="search",
+                            input={"query": "Python tutorials"},
+                        )
+                    ],
+                    model="test-model",
+                    stop_reason="toolUse",
+                )
+            else:
+                # Second call: call final_response
+                tool_was_called = True
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_2",
+                            name="final_response",
+                            input={
+                                "summary": "Python is great",
+                                "sources": ["python.org", "docs.python.org"],
+                            },
+                        )
+                    ],
+                    model="test-model",
+                    stop_reason="toolUse",
+                )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        @mcp.tool
+        async def research(context: Context) -> str:
+            result = await context.sample(
+                messages="Research Python",
+                tools=[search],
+                result_type=SearchResult,
+            )
+            assert isinstance(result.result, SearchResult)
+            return f"{result.result.summary} - {len(result.result.sources)} sources"
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("research", {})
+
+        assert tool_was_called
+        assert result.data == "Python is great - 2 sources"
+
+    async def test_result_type_validation_error_retries(self):
+        """Test that validation errors are sent back to LLM for retry."""
+        from mcp_types import (
+            CreateMessageResultWithTools,
+            ToolResultContent,
+            ToolUseContent,
+        )
+        from pydantic import BaseModel
+
+        class StrictResult(BaseModel):
+            value: int  # Must be an int
+
+        messages_received: list[list[SamplingMessage]] = []
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> CreateMessageResultWithTools:
+            messages_received.append(list(messages))
+
+            if len(messages_received) == 1:
+                # First call: invalid type
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_1",
+                            name="final_response",
+                            input={"value": "not_an_int"},  # Wrong type
+                        )
+                    ],
+                    model="test-model",
+                    stop_reason="toolUse",
+                )
+            else:
+                # Second call: valid type after seeing error
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_2",
+                            name="final_response",
+                            input={"value": 42},  # Correct type
+                        )
+                    ],
+                    model="test-model",
+                    stop_reason="toolUse",
+                )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        @mcp.tool
+        async def validate_tool(context: Context) -> str:
+            result = await context.sample(
+                messages="Give me a number",
+                result_type=StrictResult,
+            )
+            assert isinstance(result.result, StrictResult)
+            return str(result.result.value)
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("validate_tool", {})
+
+        # Should have retried after validation error
+        assert len(messages_received) == 2
+
+        # Check that error was passed back
+        last_messages = messages_received[1]
+        # Find the tool result in list content
+        tool_result = None
+        for msg in last_messages:
+            # Tool results are now in a list
+            if isinstance(msg.content, list):
+                for item in msg.content:
+                    if isinstance(item, ToolResultContent):
+                        tool_result = item
+                        break
+            elif isinstance(msg.content, ToolResultContent):
+                tool_result = msg.content
+                break
+        assert tool_result is not None
+        assert tool_result.is_error is True
+        assert isinstance(tool_result.content[0], TextContent)
+        error_text = tool_result.content[0].text
+        assert "Validation error" in error_text
+
+        # Final result should be correct
+        assert result.data == "42"
+
+    async def test_sampling_result_has_text_and_history(self):
+        """Test that SamplingResult has text, result, and history attributes."""
+        from mcp_types import CreateMessageResultWithTools
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> CreateMessageResultWithTools:
+            return CreateMessageResultWithTools(
+                role="assistant",
+                content=[TextContent(type="text", text="Hello world")],
+                model="test-model",
+                stop_reason="endTurn",
+            )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        @mcp.tool
+        async def check_result(context: Context) -> str:
+            result = await context.sample(messages="Say hello")
+            # Check all attributes exist
+            assert result.text == "Hello world"
+            assert result.result == "Hello world"
+            assert len(result.history) >= 1
+            return "ok"
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("check_result", {})
+
+        assert result.data == "ok"
+
+
+class TestSampleStep:
+    """Tests for ctx.sample_step() - single LLM call with manual control."""
+
+    async def test_sample_step_basic(self):
+        """Test basic sample_step returns text response."""
+        from mcp_types import CreateMessageResultWithTools
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> CreateMessageResultWithTools:
+            return CreateMessageResultWithTools(
+                role="assistant",
+                content=[TextContent(type="text", text="Hello from step")],
+                model="test-model",
+                stop_reason="endTurn",
+            )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        @mcp.tool
+        async def test_step(context: Context) -> str:
+            step = await context.sample_step(messages="Hi")
+            assert not step.is_tool_use
+            assert step.text == "Hello from step"
+            return step.text or ""
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("test_step", {})
+
+        assert result.data == "Hello from step"
+
+    async def test_sample_step_with_tool_execution(self):
+        """Test sample_step executes tools by default."""
+        from mcp_types import CreateMessageResultWithTools, ToolUseContent
+
+        call_count = 0
+
+        def my_tool(x: int) -> str:
+            """A test tool."""
+            return f"result:{x}"
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> CreateMessageResultWithTools:
+            nonlocal call_count
+            call_count += 1
+
+            if call_count == 1:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_1",
+                            name="my_tool",
+                            input={"x": 42},
+                        )
+                    ],
+                    model="test-model",
+                    stop_reason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Done")],
+                    model="test-model",
+                    stop_reason="endTurn",
+                )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        @mcp.tool
+        async def test_step(context: Context) -> str:
+            messages: str | list[SamplingMessage] = "Run tool"
+
+            while True:
+                step = await context.sample_step(messages=messages, tools=[my_tool])
+
+                if not step.is_tool_use:
+                    return step.text or ""
+
+                # History should include tool results when execute_tools=True
+                messages = step.history
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("test_step", {})
+
+        assert result.data == "Done"
+        assert call_count == 2
+
+    async def test_sample_step_execute_tools_false(self):
+        """Test sample_step with execute_tools=False doesn't execute tools."""
+        from mcp_types import CreateMessageResultWithTools, ToolUseContent
+
+        tool_executed = False
+
+        def my_tool() -> str:
+            """A test tool."""
+            nonlocal tool_executed
+            tool_executed = True
+            return "executed"
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> CreateMessageResultWithTools:
+            return CreateMessageResultWithTools(
+                role="assistant",
+                content=[
+                    ToolUseContent(
+                        type="tool_use",
+                        id="call_1",
+                        name="my_tool",
+                        input={},
+                    )
+                ],
+                model="test-model",
+                stop_reason="toolUse",
+            )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        @mcp.tool
+        async def test_step(context: Context) -> str:
+            step = await context.sample_step(
+                messages="Run tool",
+                tools=[my_tool],
+                execute_tools=False,
+            )
+            assert step.is_tool_use
+            assert len(step.tool_calls) == 1
+            assert step.tool_calls[0].name == "my_tool"
+            # History should include assistant message but no tool results
+            assert len(step.history) == 2  # user + assistant
+            return "ok"
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("test_step", {})
+
+        assert result.data == "ok"
+        assert not tool_executed  # Tool should not have been executed
+
+    async def test_sample_step_history_includes_assistant_message(self):
+        """Test that history includes assistant message when execute_tools=False."""
+        from mcp_types import CreateMessageResultWithTools, ToolUseContent
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> CreateMessageResultWithTools:
+            return CreateMessageResultWithTools(
+                role="assistant",
+                content=[
+                    ToolUseContent(
+                        type="tool_use",
+                        id="call_1",
+                        name="my_tool",
+                        input={"query": "test"},
+                    )
+                ],
+                model="test-model",
+                stop_reason="toolUse",
+            )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        def my_tool(query: str) -> str:
+            return f"result for {query}"
+
+        @mcp.tool
+        async def test_step(context: Context) -> str:
+            step = await context.sample_step(
+                messages="Search",
+                tools=[my_tool],
+                execute_tools=False,
+            )
+            # History should have: user message + assistant message
+            assert len(step.history) == 2
+            assert step.history[0].role == "user"
+            assert step.history[1].role == "assistant"
+            return "ok"
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("test_step", {})
+
+        assert result.data == "ok"
+
+
+class TestTextResponseRetry:
+    """Tests for retry logic when LLM returns text instead of calling final_response."""
+
+    @staticmethod
+    def _text_reply(text: str = "some text"):
+        from mcp_types import CreateMessageResultWithTools
+
+        return CreateMessageResultWithTools(
+            role="assistant",
+            content=[TextContent(type="text", text=text)],
+            model="m",
+            stop_reason="endTurn",
+        )
+
+    @staticmethod
+    def _tool_reply(value: int):
+        from mcp_types import CreateMessageResultWithTools, ToolUseContent
+
+        return CreateMessageResultWithTools(
+            role="assistant",
+            content=[
+                ToolUseContent(
+                    type="tool_use",
+                    id="c1",
+                    name="final_response",
+                    input={"value": value},
+                )
+            ],
+            model="m",
+            stop_reason="toolUse",
+        )
+
+    async def test_text_response_then_success(self):
+        """Text on first call, final_response on second -- verify call_count == 2."""
+        from pydantic import BaseModel
+
+        class R(BaseModel):
+            value: int
+
+        call_count = 0
+
+        def handler(messages, params, ctx):
+            nonlocal call_count
+            call_count += 1
+            return self._text_reply() if call_count == 1 else self._tool_reply(42)
+
+        mcp = FastMCP(sampling_handler=handler)
+
+        @mcp.tool
+        async def t(context: Context) -> str:
+            return str((await context.sample(messages="q", result_type=R)).result.value)
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("t", {})
+
+        assert call_count == 2
+        assert result.data == "42"
+
+    async def test_text_response_exceeds_max_retries(self):
+        """Always text, never tool -- verify error after _MAX_TEXT_RESPONSE_RETRIES+1 calls."""
+        from pydantic import BaseModel
+
+        from fastmcp.exceptions import ToolError
+        from fastmcp.server.sampling.run import _MAX_TEXT_RESPONSE_RETRIES
+
+        class R(BaseModel):
+            value: int
+
+        call_count = 0
+
+        def handler(messages, params, ctx):
+            nonlocal call_count
+            call_count += 1
+            return self._text_reply()
+
+        mcp = FastMCP(sampling_handler=handler)
+
+        @mcp.tool
+        async def t(context: Context) -> str:
+            return str((await context.sample(messages="q", result_type=R)).result)
+
+        async with Client(mcp) as client:
+            with pytest.raises(ToolError, match="attempts"):
+                await client.call_tool("t", {})
+
+        assert call_count == _MAX_TEXT_RESPONSE_RETRIES + 1
+
+    async def test_no_retry_when_result_type_is_none(self):
+        """Text response with no result_type -- single call, normal return."""
+        call_count = 0
+
+        def handler(messages, params, ctx):
+            nonlocal call_count
+            call_count += 1
+            return self._text_reply("hello")
+
+        mcp = FastMCP(sampling_handler=handler)
+
+        @mcp.tool
+        async def t(context: Context) -> str:
+            return (await context.sample(messages="q")).text or ""
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("t", {})
+
+        assert call_count == 1
+        assert result.data == "hello"
+
+
+def _final_response(call_id: str, input_data: dict) -> CreateMessageResultWithTools:
+    """Build a final_response tool-use reply."""
+    return CreateMessageResultWithTools(
+        role="assistant",
+        content=[
+            ToolUseContent(
+                type="tool_use", id=call_id, name="final_response", input=input_data
+            )
+        ],
+        model="test-model",
+        stop_reason="toolUse",
+    )
+
+
+def _tool_call(
+    call_id: str, name: str, input_data: dict
+) -> CreateMessageResultWithTools:
+    """Build a regular tool-use reply."""
+    return CreateMessageResultWithTools(
+        role="assistant",
+        content=[
+            ToolUseContent(type="tool_use", id=call_id, name=name, input=input_data)
+        ],
+        model="test-model",
+        stop_reason="toolUse",
+    )
+
+
+class TestValidationRetryCap:
+    """Tests for the consecutive validation retry cap (PR #3851)."""
+
+    async def test_validation_failures_within_cap_then_success(self):
+        """Two consecutive failures followed by a valid response succeeds."""
+        from pydantic import BaseModel
+
+        class R(BaseModel):
+            value: int
+
+        call_count = 0
+
+        def handler(messages, params, ctx):
+            nonlocal call_count
+            call_count += 1
+            if call_count <= 2:
+                return _final_response(f"c{call_count}", {"value": "bad"})
+            return _final_response(f"c{call_count}", {"value": 99})
+
+        mcp = FastMCP(sampling_handler=handler)
+
+        @mcp.tool
+        async def t(context: Context) -> str:
+            r = await context.sample(messages="go", result_type=R)
+            return str(r.result.value)
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("t", {})
+
+        assert call_count == 3
+        assert result.data == "99"
+
+    async def test_consecutive_validation_failures_exceed_cap(self):
+        """Always-invalid responses raise ToolError after exceeding the cap."""
+        from pydantic import BaseModel
+
+        from fastmcp.exceptions import ToolError
+        from fastmcp.server.sampling.run import _MAX_VALIDATION_RETRIES
+
+        class R(BaseModel):
+            value: int
+
+        call_count = 0
+
+        def handler(messages, params, ctx):
+            nonlocal call_count
+            call_count += 1
+            return _final_response(f"c{call_count}", {"value": "wrong"})
+
+        mcp = FastMCP(sampling_handler=handler)
+
+        @mcp.tool
+        async def t(context: Context) -> str:
+            return str((await context.sample(messages="go", result_type=R)).result)
+
+        async with Client(mcp) as client:
+            with pytest.raises(ToolError, match="consecutive"):
+                await client.call_tool("t", {})
+
+        # 1 initial attempt + _MAX_VALIDATION_RETRIES retries
+        assert call_count == _MAX_VALIDATION_RETRIES + 1
+
+    async def test_validation_counter_resets_after_other_tool_call(self):
+        """A tool call between validation failures resets the counter."""
+        from pydantic import BaseModel
+
+        class R(BaseModel):
+            value: int
+
+        def helper_tool(x: int) -> str:
+            """A helper tool."""
+            return f"result:{x}"
+
+        call_count = 0
+
+        def handler(messages, params, ctx):
+            nonlocal call_count
+            call_count += 1
+            # fail -> other tool (resets counter) -> fail -> succeed
+            if call_count == 1:
+                return _final_response("c1", {"value": "bad"})
+            if call_count == 2:
+                return _tool_call("c2", "helper_tool", {"x": 1})
+            if call_count == 3:
+                return _final_response("c3", {"value": "bad"})
+            return _final_response("c4", {"value": 42})
+
+        mcp = FastMCP(sampling_handler=handler)
+
+        @mcp.tool
+        async def t(context: Context) -> str:
+            r = await context.sample(messages="go", tools=[helper_tool], result_type=R)
+            return str(r.result.value)
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("t", {})
+
+        assert call_count == 4
+        assert result.data == "42"
diff --git a/tests/client/test_sampling_tool_loop.py b/tests/client/test_sampling_tool_loop.py
new file mode 100644
index 0000000..809e58e
--- /dev/null
+++ b/tests/client/test_sampling_tool_loop.py
@@ -0,0 +1,769 @@
+from typing import cast
+
+from mcp_types import TextContent
+
+from fastmcp import Client, Context, FastMCP
+from fastmcp.client.sampling import RequestContext, SamplingMessage, SamplingParams
+from fastmcp.server.sampling import SamplingTool
+
+
+class TestAutomaticToolLoop:
+    """Tests for automatic tool execution loop in ctx.sample()."""
+
+    async def test_automatic_tool_loop_executes_tools(self):
+        """Test that ctx.sample() automatically executes tool calls."""
+        from mcp_types import CreateMessageResultWithTools, ToolUseContent
+
+        call_count = 0
+        tool_was_called = False
+
+        def get_weather(city: str) -> str:
+            """Get weather for a city."""
+            nonlocal tool_was_called
+            tool_was_called = True
+            return f"Weather in {city}: sunny, 72°F"
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> CreateMessageResultWithTools:
+            nonlocal call_count
+            call_count += 1
+
+            if call_count == 1:
+                # First call: return tool use
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_1",
+                            name="get_weather",
+                            input={"city": "Seattle"},
+                        )
+                    ],
+                    model="test-model",
+                    stop_reason="toolUse",
+                )
+            else:
+                # Second call: return final response
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="The weather is sunny!")],
+                    model="test-model",
+                    stop_reason="endTurn",
+                )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        @mcp.tool
+        async def weather_assistant(question: str, context: Context) -> str:
+            result = await context.sample(
+                messages=question,
+                tools=[get_weather],
+            )
+            # Get text from SamplingResult
+            return result.text or ""
+
+        async with Client(mcp) as client:
+            result = await client.call_tool(
+                "weather_assistant", {"question": "What's the weather?"}
+            )
+
+        assert tool_was_called
+        assert call_count == 2
+        assert result.data == "The weather is sunny!"
+
+    async def test_automatic_tool_loop_multiple_tools(self):
+        """Test that multiple tool calls in one response are all executed."""
+        from mcp_types import CreateMessageResultWithTools, ToolUseContent
+
+        executed_tools: list[str] = []
+
+        def tool_a(x: int) -> int:
+            """Tool A."""
+            executed_tools.append(f"tool_a({x})")
+            return x * 2
+
+        def tool_b(y: int) -> int:
+            """Tool B."""
+            executed_tools.append(f"tool_b({y})")
+            return y + 10
+
+        call_count = 0
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> CreateMessageResultWithTools:
+            nonlocal call_count
+            call_count += 1
+
+            if call_count == 1:
+                # Return multiple tool calls
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[
+                        ToolUseContent(
+                            type="tool_use", id="call_a", name="tool_a", input={"x": 5}
+                        ),
+                        ToolUseContent(
+                            type="tool_use", id="call_b", name="tool_b", input={"y": 3}
+                        ),
+                    ],
+                    model="test-model",
+                    stop_reason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Done!")],
+                    model="test-model",
+                    stop_reason="endTurn",
+                )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        @mcp.tool
+        async def multi_tool(context: Context) -> str:
+            result = await context.sample(messages="Run tools", tools=[tool_a, tool_b])
+            return result.text or ""
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("multi_tool", {})
+
+        assert executed_tools == ["tool_a(5)", "tool_b(3)"]
+        assert result.data == "Done!"
+
+    async def test_automatic_tool_loop_handles_unknown_tool(self):
+        """Test that unknown tool names result in error being passed to LLM."""
+        from mcp_types import (
+            CreateMessageResultWithTools,
+            ToolResultContent,
+            ToolUseContent,
+        )
+
+        def known_tool() -> str:
+            """A known tool."""
+            return "known result"
+
+        messages_received: list[list[SamplingMessage]] = []
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> CreateMessageResultWithTools:
+            messages_received.append(list(messages))
+
+            if len(messages_received) == 1:
+                # Request unknown tool
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_1",
+                            name="unknown_tool",
+                            input={},
+                        )
+                    ],
+                    model="test-model",
+                    stop_reason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Handled error")],
+                    model="test-model",
+                    stop_reason="endTurn",
+                )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        @mcp.tool
+        async def test_unknown(context: Context) -> str:
+            result = await context.sample(messages="Test", tools=[known_tool])
+            return result.text or ""
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("test_unknown", {})
+
+        # Check that error was passed back in messages
+        assert len(messages_received) == 2
+        last_messages = messages_received[1]
+        # Find the tool result in list content
+        tool_result = None
+        for msg in last_messages:
+            # Tool results are now in a list
+            if isinstance(msg.content, list):
+                for item in msg.content:
+                    if isinstance(item, ToolResultContent):
+                        tool_result = item
+                        break
+            elif isinstance(msg.content, ToolResultContent):
+                tool_result = msg.content
+                break
+        assert tool_result is not None
+        assert tool_result.is_error is True
+        # Content is list of TextContent objects
+        assert isinstance(tool_result.content[0], TextContent)
+        error_text = tool_result.content[0].text
+        assert "Unknown tool" in error_text
+        assert result.data == "Handled error"
+
+    async def test_automatic_tool_loop_handles_tool_exception(self):
+        """Test that tool exceptions are caught and passed to LLM as errors."""
+        from mcp_types import (
+            CreateMessageResultWithTools,
+            ToolResultContent,
+            ToolUseContent,
+        )
+
+        def failing_tool() -> str:
+            """A tool that raises an exception."""
+            raise ValueError("Tool failed intentionally")
+
+        messages_received: list[list[SamplingMessage]] = []
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> CreateMessageResultWithTools:
+            messages_received.append(list(messages))
+
+            if len(messages_received) == 1:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_1",
+                            name="failing_tool",
+                            input={},
+                        )
+                    ],
+                    model="test-model",
+                    stop_reason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Handled error")],
+                    model="test-model",
+                    stop_reason="endTurn",
+                )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        @mcp.tool
+        async def test_exception(context: Context) -> str:
+            result = await context.sample(messages="Test", tools=[failing_tool])
+            return result.text or ""
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("test_exception", {})
+
+        # Check that error was passed back
+        assert len(messages_received) == 2
+        last_messages = messages_received[1]
+        # Find the tool result in list content
+        tool_result = None
+        for msg in last_messages:
+            # Tool results are now in a list
+            if isinstance(msg.content, list):
+                for item in msg.content:
+                    if isinstance(item, ToolResultContent):
+                        tool_result = item
+                        break
+            elif isinstance(msg.content, ToolResultContent):
+                tool_result = msg.content
+                break
+        assert tool_result is not None
+        assert tool_result.is_error is True
+        # Content is list of TextContent objects
+        assert isinstance(tool_result.content[0], TextContent)
+        error_text = tool_result.content[0].text
+        assert "Tool failed intentionally" in error_text
+        assert result.data == "Handled error"
+
+    async def test_concurrent_tool_execution_default_sequential(self):
+        """Test that tools execute sequentially by default."""
+        import asyncio
+        import time
+
+        from mcp_types import CreateMessageResultWithTools, ToolUseContent
+
+        execution_order: list[tuple[str, float]] = []
+
+        async def slow_tool_a(x: int) -> int:
+            """Slow tool A."""
+            start = time.time()
+            execution_order.append(("tool_a_start", start))
+            await asyncio.sleep(0.1)
+            execution_order.append(("tool_a_end", time.time()))
+            return x * 2
+
+        async def slow_tool_b(y: int) -> int:
+            """Slow tool B."""
+            start = time.time()
+            execution_order.append(("tool_b_start", start))
+            await asyncio.sleep(0.1)
+            execution_order.append(("tool_b_end", time.time()))
+            return y + 10
+
+        call_count = 0
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> CreateMessageResultWithTools:
+            nonlocal call_count
+            call_count += 1
+
+            if call_count == 1:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_a",
+                            name="slow_tool_a",
+                            input={"x": 5},
+                        ),
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_b",
+                            name="slow_tool_b",
+                            input={"y": 3},
+                        ),
+                    ],
+                    model="test-model",
+                    stop_reason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Done!")],
+                    model="test-model",
+                    stop_reason="endTurn",
+                )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        @mcp.tool
+        async def test_tool(context: Context) -> str:
+            result = await context.sample(
+                messages="Run tools",
+                tools=[slow_tool_a, slow_tool_b],
+                # Default: tool_concurrency=None (sequential)
+            )
+            return result.text or ""
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("test_tool", {})
+
+        assert result.data == "Done!"
+        # Verify sequential execution: tool_a must complete before tool_b starts
+        events = [e[0] for e in execution_order]
+        assert events == ["tool_a_start", "tool_a_end", "tool_b_start", "tool_b_end"]
+
+    async def test_concurrent_tool_execution_unlimited(self):
+        """Test unlimited parallel tool execution with tool_concurrency=0."""
+        import asyncio
+        import time
+
+        from mcp_types import CreateMessageResultWithTools, ToolUseContent
+
+        execution_times: dict[str, dict[str, float]] = {}
+
+        async def slow_tool_a(x: int) -> int:
+            """Slow tool A."""
+            execution_times["tool_a"] = {"start": time.time()}
+            await asyncio.sleep(0.1)
+            execution_times["tool_a"]["end"] = time.time()
+            return x * 2
+
+        async def slow_tool_b(y: int) -> int:
+            """Slow tool B."""
+            execution_times["tool_b"] = {"start": time.time()}
+            await asyncio.sleep(0.1)
+            execution_times["tool_b"]["end"] = time.time()
+            return y + 10
+
+        call_count = 0
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> CreateMessageResultWithTools:
+            nonlocal call_count
+            call_count += 1
+
+            if call_count == 1:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_a",
+                            name="slow_tool_a",
+                            input={"x": 5},
+                        ),
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_b",
+                            name="slow_tool_b",
+                            input={"y": 3},
+                        ),
+                    ],
+                    model="test-model",
+                    stop_reason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Done!")],
+                    model="test-model",
+                    stop_reason="endTurn",
+                )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        @mcp.tool
+        async def test_tool(context: Context) -> str:
+            result = await context.sample(
+                messages="Run tools",
+                tools=[slow_tool_a, slow_tool_b],
+                tool_concurrency=0,  # Unlimited parallel
+            )
+            return result.text or ""
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("test_tool", {})
+
+        assert result.data == "Done!"
+        # Verify parallel execution: both tools should overlap in time
+        assert "tool_a" in execution_times
+        assert "tool_b" in execution_times
+        # tool_b should start before tool_a finishes (overlap)
+        assert execution_times["tool_b"]["start"] < execution_times["tool_a"]["end"]
+
+    async def test_concurrent_tool_execution_bounded(self):
+        """Test bounded parallel execution with tool_concurrency=2."""
+        import asyncio
+        import time
+
+        from mcp_types import CreateMessageResultWithTools, ToolUseContent
+
+        execution_order: list[tuple[str, float]] = []
+
+        async def slow_tool(name: str, duration: float = 0.1) -> str:
+            """Generic slow tool."""
+            execution_order.append((f"{name}_start", time.time()))
+            await asyncio.sleep(duration)
+            execution_order.append((f"{name}_end", time.time()))
+            return f"{name} done"
+
+        call_count = 0
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> CreateMessageResultWithTools:
+            nonlocal call_count
+            call_count += 1
+
+            if call_count == 1:
+                # Request 3 tools (with concurrency=2, first 2 run parallel, then 3rd)
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_1",
+                            name="slow_tool",
+                            input={"name": "tool_1", "duration": 0.1},
+                        ),
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_2",
+                            name="slow_tool",
+                            input={"name": "tool_2", "duration": 0.1},
+                        ),
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_3",
+                            name="slow_tool",
+                            input={"name": "tool_3", "duration": 0.05},
+                        ),
+                    ],
+                    model="test-model",
+                    stop_reason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Done!")],
+                    model="test-model",
+                    stop_reason="endTurn",
+                )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        @mcp.tool
+        async def test_tool(context: Context) -> str:
+            result = await context.sample(
+                messages="Run tools",
+                tools=[slow_tool],
+                tool_concurrency=2,  # Max 2 concurrent
+            )
+            return result.text or ""
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("test_tool", {})
+
+        assert result.data == "Done!"
+        # Verify that at most 2 tools run concurrently
+        events = [e[0] for e in execution_order]
+        # First 2 tools should start before either ends
+        assert events[0] in ["tool_1_start", "tool_2_start"]
+        assert events[1] in ["tool_1_start", "tool_2_start"]
+        # Third tool should start after at least one of the first two finishes
+        tool_3_start_idx = events.index("tool_3_start")
+        assert (
+            "tool_1_end" in events[:tool_3_start_idx]
+            or "tool_2_end" in events[:tool_3_start_idx]
+        )
+
+    async def test_sequential_tool_forces_sequential_execution(self):
+        """Test that sequential=True forces all tools to execute sequentially."""
+        import asyncio
+        import time
+
+        from mcp_types import CreateMessageResultWithTools, ToolUseContent
+
+        execution_order: list[tuple[str, float]] = []
+
+        async def normal_tool(x: int) -> int:
+            """Normal tool."""
+            execution_order.append(("normal_start", time.time()))
+            await asyncio.sleep(0.05)
+            execution_order.append(("normal_end", time.time()))
+            return x * 2
+
+        async def sequential_tool(y: int) -> int:
+            """Sequential tool."""
+            execution_order.append(("sequential_start", time.time()))
+            await asyncio.sleep(0.05)
+            execution_order.append(("sequential_end", time.time()))
+            return y + 10
+
+        call_count = 0
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> CreateMessageResultWithTools:
+            nonlocal call_count
+            call_count += 1
+
+            if call_count == 1:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_1",
+                            name="normal_tool",
+                            input={"x": 5},
+                        ),
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_2",
+                            name="sequential_tool",
+                            input={"y": 3},
+                        ),
+                    ],
+                    model="test-model",
+                    stop_reason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Done!")],
+                    model="test-model",
+                    stop_reason="endTurn",
+                )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        @mcp.tool
+        async def test_tool(context: Context) -> str:
+            # Create tools with sequential=True for one of them
+            normal = SamplingTool.from_function(normal_tool, sequential=False)
+            sequential = SamplingTool.from_function(sequential_tool, sequential=True)
+
+            result = await context.sample(
+                messages="Run tools",
+                tools=[normal, sequential],
+                tool_concurrency=0,  # Request unlimited, but sequential tool forces sequential
+            )
+            return result.text or ""
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("test_tool", {})
+
+        assert result.data == "Done!"
+        # Verify sequential execution: first tool must complete before second starts
+        events = [e[0] for e in execution_order]
+        assert events[0] in ["normal_start", "sequential_start"]
+        assert events[1] in ["normal_end", "sequential_end"]
+        # Ensure the second tool starts after the first ends
+        if events[0] == "normal_start":
+            assert events[1] == "normal_end"
+            assert events[2] == "sequential_start"
+        else:
+            assert events[1] == "sequential_end"
+            assert events[2] == "normal_start"
+
+    async def test_concurrent_tool_execution_error_handling(self):
+        """Test that errors are captured per-tool in parallel execution."""
+        from mcp_types import (
+            CreateMessageResultWithTools,
+            ToolResultContent,
+            ToolUseContent,
+        )
+
+        def good_tool() -> str:
+            return "success"
+
+        def bad_tool() -> str:
+            raise ValueError("Tool error")
+
+        messages_received: list[list[SamplingMessage]] = []
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> CreateMessageResultWithTools:
+            messages_received.append(list(messages))
+
+            if len(messages_received) == 1:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[
+                        ToolUseContent(
+                            type="tool_use", id="call_1", name="good_tool", input={}
+                        ),
+                        ToolUseContent(
+                            type="tool_use", id="call_2", name="bad_tool", input={}
+                        ),
+                    ],
+                    model="test-model",
+                    stop_reason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Handled errors")],
+                    model="test-model",
+                    stop_reason="endTurn",
+                )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        @mcp.tool
+        async def test_tool(context: Context) -> str:
+            result = await context.sample(
+                messages="Run tools",
+                tools=[good_tool, bad_tool],
+                tool_concurrency=0,  # Parallel execution
+            )
+            return result.text or ""
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("test_tool", {})
+
+        assert result.data == "Handled errors"
+        # Check that tool results include both success and error
+        tool_result_message = messages_received[1][-1]
+        assert tool_result_message.role == "user"
+        tool_results = cast(list[ToolResultContent], tool_result_message.content)
+        assert len(tool_results) == 2
+        # One should be success, one should be error
+        assert any(not r.is_error for r in tool_results)
+        assert any(r.is_error for r in tool_results)
+
+    async def test_concurrent_tool_result_order_preserved(self):
+        """Test that tool results maintain the same order as tool calls."""
+        import asyncio
+
+        from mcp_types import (
+            CreateMessageResultWithTools,
+            ToolResultContent,
+            ToolUseContent,
+        )
+
+        async def tool_with_delay(value: int, delay: float) -> int:
+            """Tool that takes variable time."""
+            await asyncio.sleep(delay)
+            return value
+
+        messages_received: list[list[SamplingMessage]] = []
+
+        def sampling_handler(
+            messages: list[SamplingMessage], params: SamplingParams, ctx: RequestContext
+        ) -> CreateMessageResultWithTools:
+            messages_received.append(list(messages))
+
+            if len(messages_received) == 1:
+                # Tools with different delays - later tools finish first
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_1",
+                            name="tool_with_delay",
+                            input={"value": 1, "delay": 0.15},
+                        ),
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_2",
+                            name="tool_with_delay",
+                            input={"value": 2, "delay": 0.05},
+                        ),
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_3",
+                            name="tool_with_delay",
+                            input={"value": 3, "delay": 0.1},
+                        ),
+                    ],
+                    model="test-model",
+                    stop_reason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Done!")],
+                    model="test-model",
+                    stop_reason="endTurn",
+                )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        @mcp.tool
+        async def test_tool(context: Context) -> str:
+            result = await context.sample(
+                messages="Run tools",
+                tools=[tool_with_delay],
+                tool_concurrency=0,  # Parallel execution
+            )
+            return result.text or ""
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("test_tool", {})
+
+        assert result.data == "Done!"
+        # Check that results are in the correct order (1, 2, 3) despite finishing order (2, 3, 1)
+        tool_result_message = messages_received[1][-1]
+        tool_results = cast(list[ToolResultContent], tool_result_message.content)
+        assert len(tool_results) == 3
+        assert tool_results[0].tool_use_id == "call_1"
+        assert tool_results[1].tool_use_id == "call_2"
+        assert tool_results[2].tool_use_id == "call_3"
+        # Check values are correct
+        result_texts = [cast(TextContent, r.content[0]).text for r in tool_results]
+        assert result_texts == ["1", "2", "3"]
diff --git a/tests/client/test_slim_package_boundaries.py b/tests/client/test_slim_package_boundaries.py
new file mode 100644
index 0000000..5f59b6b
--- /dev/null
+++ b/tests/client/test_slim_package_boundaries.py
@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import builtins
+import contextlib
+import subprocess
+import sys
+import textwrap
+import types
+from collections.abc import Mapping, Sequence
+from typing import Any, cast
+
+import pytest
+
+
+@contextlib.contextmanager
+def block_server_imports():
+    original_import = builtins.__import__
+
+    def blocked_import(
+        name: str,
+        globals: Mapping[str, object] | None = None,
+        locals: Mapping[str, object] | None = None,
+        fromlist: Sequence[str] | None = (),
+        level: int = 0,
+    ) -> types.ModuleType:
+        if level == 0 and (
+            name == "fastmcp.server" or name.startswith("fastmcp.server.")
+        ):
+            raise ImportError(f"blocked server import: {name}")
+        return original_import(name, globals, locals, fromlist, level)
+
+    cast(Any, builtins).__import__ = blocked_import
+    try:
+        yield
+    finally:
+        cast(Any, builtins).__import__ = original_import
+
+
+def test_client_http_headers_do_not_require_server() -> None:
+    from fastmcp.client.dependencies import get_http_headers
+
+    with block_server_imports():
+        assert get_http_headers(include_all=True) == {}
+
+
+@pytest.mark.asyncio
+async def test_multiserver_config_requires_server_for_now() -> None:
+    from fastmcp.client.transports import MCPConfigTransport
+
+    with block_server_imports():
+        transport = MCPConfigTransport(
+            {
+                "mcpServers": {
+                    "one": {"command": "uvx", "args": ["one"]},
+                    "two": {"command": "uvx", "args": ["two"]},
+                }
+            }
+        )
+
+        with pytest.raises(
+            ImportError, match="multiple servers require the full `fastmcp`"
+        ):
+            async with transport.connect_session():
+                pass
+
+
+def test_bare_slim_import_needs_only_mcp_types() -> None:
+    """A bare `fastmcp-slim` install ships `mcp-types` but not the full `mcp` SDK.
+
+    `mcp-types` is a core dependency (it only pulls pydantic + typing-extensions),
+    while the full `mcp` package lives in the `[mcp]` extra pulled by
+    `[client]`/`[server]`. With `mcp` absent but `mcp-types` present, `import
+    fastmcp`, `import fastmcp.settings`, and `import fastmcp.types` must all
+    succeed, while `fastmcp.FastMCP` and `fastmcp.Client` raise the friendly
+    install-hint ImportError (they need `mcp.*` from the server/client extras).
+    """
+    script = textwrap.dedent(
+        """
+        import sys
+        import importlib.abc
+
+        class BlockFullMcp(importlib.abc.MetaPathFinder):
+            # Block the full `mcp` package but leave `mcp_types` importable,
+            # exactly as a bare `fastmcp-slim` install would present.
+            def find_spec(self, name, path, target=None):
+                if name == "mcp" or name.startswith("mcp."):
+                    raise ImportError(f"blocked: {name}")
+                return None
+
+        sys.meta_path.insert(0, BlockFullMcp())
+
+        import fastmcp
+        import fastmcp.settings
+        import fastmcp.types
+
+        assert "mcp_types" in sys.modules, "mcp_types should load on a bare install"
+        assert "mcp" not in sys.modules, "full mcp must not load on a bare install"
+
+        for attr in ("FastMCP", "Client"):
+            try:
+                getattr(fastmcp, attr)
+            except ImportError:
+                pass
+            else:
+                raise AssertionError(f"fastmcp.{attr} should have raised ImportError")
+
+        print("OK")
+        """
+    )
+    result = subprocess.run(
+        [sys.executable, "-c", script],
+        capture_output=True,
+        text=True,
+    )
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip().endswith("OK")
diff --git a/tests/client/test_sse.py b/tests/client/test_sse.py
new file mode 100644
index 0000000..eb94faa
--- /dev/null
+++ b/tests/client/test_sse.py
@@ -0,0 +1,200 @@
+import asyncio
+import json
+import sys
+
+import pytest
+from mcp import MCPError
+from mcp_types import TextResourceContents
+
+from fastmcp.client import Client
+from fastmcp.client.transports import SSETransport
+from fastmcp.server.dependencies import get_http_request
+from fastmcp.server.http import create_sse_app
+from fastmcp.server.server import FastMCP
+from fastmcp.utilities.tests import run_server_async
+
+
+def create_test_server() -> FastMCP:
+    """Create a FastMCP server with tools, resources, and prompts."""
+    server = FastMCP("TestServer")
+
+    @server.tool
+    def greet(name: str) -> str:
+        """Greet someone by name."""
+        return f"Hello, {name}!"
+
+    @server.tool
+    def add(a: int, b: int) -> int:
+        """Add two numbers together."""
+        return a + b
+
+    @server.tool
+    async def sleep(seconds: float) -> str:
+        """Sleep for a given number of seconds."""
+        await asyncio.sleep(seconds)
+        return f"Slept for {seconds} seconds"
+
+    @server.resource(uri="data://users")
+    async def get_users() -> str:
+        import json
+
+        return json.dumps(["Alice", "Bob", "Charlie"])
+
+    @server.resource(uri="data://user/{user_id}")
+    async def get_user(user_id: str) -> str:
+        import json
+
+        return json.dumps({"id": user_id, "name": f"User {user_id}", "active": True})
+
+    @server.resource(uri="request://headers")
+    async def get_headers() -> str:
+        import json
+
+        request = get_http_request()
+        return json.dumps(dict(request.headers))
+
+    @server.prompt
+    def welcome(name: str) -> str:
+        """Example greeting prompt."""
+        return f"Welcome to FastMCP, {name}!"
+
+    return server
+
+
+@pytest.fixture
+async def sse_server():
+    """Start a test server with SSE transport and return its URL."""
+    server = create_test_server()
+    async with run_server_async(server, transport="sse") as url:
+        yield url
+
+
+async def test_ping(sse_server: str):
+    """Test pinging the server."""
+    async with Client(transport=SSETransport(sse_server)) as client:
+        result = await client.ping()
+        assert result is True
+
+
+async def test_http_headers(sse_server: str):
+    """Test getting HTTP headers from the server."""
+    async with Client(
+        transport=SSETransport(sse_server, headers={"X-DEMO-HEADER": "ABC"})
+    ) as client:
+        raw_result = await client.read_resource("request://headers")
+        assert isinstance(raw_result[0], TextResourceContents)
+        json_result = json.loads(raw_result[0].text)
+        assert "x-demo-header" in json_result
+        assert json_result["x-demo-header"] == "ABC"
+
+
+@pytest.fixture
+async def sse_server_custom_path():
+    """Start a test server with SSE on a custom path."""
+    server = create_test_server()
+    async with run_server_async(server, transport="sse", path="/help") as url:
+        yield url
+
+
+@pytest.fixture
+async def nested_sse_server():
+    """Test nested server mounts with SSE."""
+    import uvicorn
+    from starlette.applications import Starlette
+    from starlette.routing import Mount
+
+    from fastmcp.utilities.http import find_available_port
+
+    server = create_test_server()
+    sse_app = create_sse_app(
+        server=server, message_path="/mcp/messages", sse_path="/mcp/sse/"
+    )
+
+    # Nest the app under multiple mounts to test URL resolution
+    inner = Starlette(routes=[Mount("/nest-inner", app=sse_app)])
+    outer = Starlette(routes=[Mount("/nest-outer", app=inner)])
+
+    # Run uvicorn with the nested ASGI app
+    port = find_available_port()
+
+    config = uvicorn.Config(
+        app=outer,
+        host="127.0.0.1",
+        port=port,
+        log_level="critical",
+        ws="websockets-sansio",
+    )
+
+    uvicorn_server = uvicorn.Server(config)
+    server_task = asyncio.create_task(uvicorn_server.serve())
+    await asyncio.sleep(0.1)
+
+    try:
+        yield f"http://127.0.0.1:{port}/nest-outer/nest-inner/mcp/sse/"
+    finally:
+        # Graceful shutdown - required for uvicorn 0.39+ due to context isolation
+        uvicorn_server.should_exit = True
+        try:
+            await server_task
+        except asyncio.CancelledError:
+            pass
+
+
+async def test_run_server_on_path(sse_server_custom_path: str):
+    """Test running server on a custom path."""
+    async with Client(transport=SSETransport(sse_server_custom_path)) as client:
+        result = await client.ping()
+        assert result is True
+
+
+async def test_nested_sse_server_resolves_correctly(nested_sse_server: str):
+    """Test patch for https://github.com/modelcontextprotocol/python-sdk/pull/659"""
+    async with Client(transport=SSETransport(nested_sse_server)) as client:
+        result = await client.ping()
+        assert result is True
+
+
+@pytest.mark.skipif(
+    sys.platform == "win32",
+    reason="Timeout tests are flaky on Windows. Timeouts *are* supported but the tests are unreliable.",
+)
+class TestTimeout:
+    async def test_timeout(self, sse_server: str):
+        with pytest.raises(
+            MCPError,
+            match="timed out",
+        ):
+            async with Client(
+                transport=SSETransport(sse_server),
+                timeout=0.03,
+            ) as client:
+                await client.call_tool("sleep", {"seconds": 0.1})
+
+    async def test_timeout_tool_call(self, sse_server: str):
+        async with Client(transport=SSETransport(sse_server)) as client:
+            with pytest.raises(MCPError, match="timed out"):
+                await client.call_tool("sleep", {"seconds": 0.1}, timeout=0.03)
+
+    async def test_timeout_tool_call_overrides_client_timeout_if_lower(
+        self, sse_server: str
+    ):
+        async with Client(
+            transport=SSETransport(sse_server),
+            timeout=2,
+        ) as client:
+            with pytest.raises(MCPError, match="timed out"):
+                await client.call_tool("sleep", {"seconds": 0.1}, timeout=0.03)
+
+    async def test_timeout_client_timeout_does_not_override_tool_call_timeout_if_lower(
+        self, sse_server: str
+    ):
+        """
+        With SSE, the tool call timeout always takes precedence over the client.
+
+        Note: on Windows, the behavior appears unpredictable.
+        """
+        async with Client(
+            transport=SSETransport(sse_server),
+            timeout=0.5,
+        ) as client:
+            await client.call_tool("sleep", {"seconds": 0.8}, timeout=2)
diff --git a/tests/client/test_stdio.py b/tests/client/test_stdio.py
new file mode 100644
index 0000000..af49952
--- /dev/null
+++ b/tests/client/test_stdio.py
@@ -0,0 +1,640 @@
+import asyncio
+import gc
+import inspect
+import os
+import weakref
+
+import psutil
+import pytest
+
+from fastmcp import Client
+from fastmcp.client.transports import PythonStdioTransport, StdioTransport
+
+
+def running_under_debugger():
+    return os.environ.get("DEBUGPY_RUNNING") == "true"
+
+
+def gc_collect_harder():
+    gc.collect()
+    gc.collect()
+    gc.collect()
+    gc.collect()
+    gc.collect()
+    gc.collect()
+
+
+class TestParallelCalls:
+    @pytest.fixture
+    def stdio_script(self, tmp_path):
+        script = inspect.cleandoc('''
+            import os
+            from fastmcp import FastMCP
+
+            mcp = FastMCP()
+
+            @mcp.tool
+            def pid() -> int:
+                """Gets PID of server"""
+                return os.getpid()
+
+            if __name__ == "__main__":
+                mcp.run()
+            ''')
+        script_file = tmp_path / "stdio.py"
+        script_file.write_text(script)
+        return script_file
+
+    async def test_parallel_calls(self, stdio_script):
+        from fastmcp.server import create_proxy
+
+        backend_transport = PythonStdioTransport(script_path=stdio_script)
+        backend_client = Client(transport=backend_transport)
+
+        proxy = create_proxy(backend_client, name="PROXY")
+
+        count = 10
+
+        tasks = [proxy.list_tools() for _ in range(count)]
+
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        assert len(results) == count
+        errors = [result for result in results if isinstance(result, Exception)]
+        assert len(errors) == 0
+
+
+@pytest.mark.timeout(15)
+class TestKeepAlive:
+    # https://github.com/PrefectHQ/fastmcp/issues/581
+
+    @pytest.fixture
+    def stdio_script(self, tmp_path):
+        script = inspect.cleandoc('''
+            import os
+            from fastmcp import FastMCP
+
+            mcp = FastMCP()
+
+            @mcp.tool
+            def pid() -> int:
+                """Gets PID of server"""
+                return os.getpid()
+
+            if __name__ == "__main__":
+                mcp.run()
+            ''')
+        script_file = tmp_path / "stdio.py"
+        script_file.write_text(script)
+        return script_file
+
+    async def test_keep_alive_default_true(self):
+        client = Client(transport=StdioTransport(command="python", args=[""]))
+
+        assert client.transport.keep_alive is True
+
+    async def test_keep_alive_set_false(self):
+        client = Client(
+            transport=StdioTransport(command="python", args=[""], keep_alive=False)
+        )
+        assert client.transport.keep_alive is False
+
+    async def test_keep_alive_maintains_session_across_multiple_calls(
+        self, stdio_script
+    ):
+        client = Client(transport=PythonStdioTransport(script_path=stdio_script))
+        assert client.transport.keep_alive is True
+
+        async with client:
+            result1 = await client.call_tool("pid")
+            pid1: int = result1.data
+
+        async with client:
+            result2 = await client.call_tool("pid")
+            pid2: int = result2.data
+
+        assert pid1 == pid2
+
+    @pytest.mark.skipif(
+        running_under_debugger(), reason="Debugger holds a reference to the transport"
+    )
+    async def test_keep_alive_true_exit_scope_kills_transport(self, stdio_script):
+        transport_weak_ref: weakref.ref[PythonStdioTransport] | None = None
+
+        async def test_server():
+            transport = PythonStdioTransport(script_path=stdio_script, keep_alive=True)
+            nonlocal transport_weak_ref
+            transport_weak_ref = weakref.ref(transport)
+            async with transport.connect_session():
+                pass
+
+        await test_server()
+
+        gc_collect_harder()
+
+        # This test will fail while debugging because the debugger holds a reference to the underlying transport
+        assert transport_weak_ref
+        transport = transport_weak_ref()
+        assert transport is None
+
+    @pytest.mark.skipif(
+        running_under_debugger(), reason="Debugger holds a reference to the transport"
+    )
+    async def test_keep_alive_true_exit_scope_kills_client(self, stdio_script):
+        pid: int | None = None
+
+        async def test_server():
+            transport = PythonStdioTransport(script_path=stdio_script, keep_alive=True)
+            client = Client(transport=transport)
+
+            assert client.transport.keep_alive is True
+
+            async with client:
+                result1 = await client.call_tool("pid")
+                nonlocal pid
+                pid = result1.data
+
+        await test_server()
+
+        gc_collect_harder()
+
+        # This test may fail/hang while debugging because the debugger holds a reference to the underlying transport
+
+        with pytest.raises(psutil.NoSuchProcess):
+            while True:
+                psutil.Process(pid)
+                await asyncio.sleep(0.1)
+
+    async def test_keep_alive_false_exit_scope_kills_server(self, stdio_script):
+        pid: int | None = None
+
+        async def test_server():
+            transport = PythonStdioTransport(script_path=stdio_script, keep_alive=False)
+            client = Client(transport=transport)
+            assert client.transport.keep_alive is False
+            async with client:
+                result1 = await client.call_tool("pid")
+                nonlocal pid
+                pid = result1.data
+
+            del client
+
+        await test_server()
+
+        with pytest.raises(psutil.NoSuchProcess):
+            while True:
+                psutil.Process(pid)
+                await asyncio.sleep(0.1)
+
+    async def test_keep_alive_false_starts_new_session_across_multiple_calls(
+        self, stdio_script
+    ):
+        client = Client(
+            transport=PythonStdioTransport(script_path=stdio_script, keep_alive=False)
+        )
+        assert client.transport.keep_alive is False
+
+        async with client:
+            result1 = await client.call_tool("pid")
+            pid1: int = result1.data
+
+        async with client:
+            result2 = await client.call_tool("pid")
+            pid2: int = result2.data
+
+        assert pid1 != pid2
+
+    async def test_keep_alive_starts_new_session_if_manually_closed(self, stdio_script):
+        client = Client(transport=PythonStdioTransport(script_path=stdio_script))
+        assert client.transport.keep_alive is True
+
+        async with client:
+            result1 = await client.call_tool("pid")
+            pid1: int = result1.data
+
+        await client.close()
+
+        async with client:
+            result2 = await client.call_tool("pid")
+            pid2: int = result2.data
+
+        assert pid1 != pid2
+
+    async def test_keep_alive_maintains_session_if_reentered(self, stdio_script):
+        client = Client(transport=PythonStdioTransport(script_path=stdio_script))
+        assert client.transport.keep_alive is True
+
+        async with client:
+            result1 = await client.call_tool("pid")
+            pid1: int = result1.data
+
+            async with client:
+                result2 = await client.call_tool("pid")
+                pid2: int = result2.data
+
+            result3 = await client.call_tool("pid")
+            pid3: int = result3.data
+
+        assert pid1 == pid2 == pid3
+
+    async def test_close_session_and_try_to_use_client_raises_error(self, stdio_script):
+        client = Client(transport=PythonStdioTransport(script_path=stdio_script))
+        assert client.transport.keep_alive is True
+
+        async with client:
+            await client.close()
+            with pytest.raises(RuntimeError, match="Client is not connected"):
+                await client.call_tool("pid")
+
+    async def test_session_task_failure_raises_immediately_on_enter(self):
+        # Use a command that will fail to start
+        client = Client(
+            transport=StdioTransport(command="nonexistent_command", args=[])
+        )
+
+        # Should raise RuntimeError immediately, not defer until first use
+        with pytest.raises(RuntimeError, match="Client failed to connect"):
+            async with client:
+                pass
+
+
+@pytest.mark.timeout(15)
+class TestSubprocessCrashRecovery:
+    """Test that StdioTransport recovers after the subprocess crashes."""
+
+    # Use a short init_timeout so tests fail fast instead of hanging if
+    # stream-based dead-session detection is slow (e.g. on Windows where
+    # pipe cleanup can lag after process termination).
+    INIT_TIMEOUT = 3
+
+    @pytest.fixture
+    def stdio_script(self, tmp_path):
+        script = inspect.cleandoc('''
+            import os
+            from fastmcp import FastMCP
+
+            mcp = FastMCP()
+
+            @mcp.tool
+            def pid() -> int:
+                """Gets PID of server"""
+                return os.getpid()
+
+            if __name__ == "__main__":
+                mcp.run()
+            ''')
+        script_file = tmp_path / "stdio.py"
+        script_file.write_text(script)
+        return script_file
+
+    async def test_keep_alive_recovers_after_subprocess_crash(self, stdio_script):
+        """When keep_alive=True and the subprocess dies, the next connection should start a fresh subprocess."""
+        transport = PythonStdioTransport(script_path=stdio_script)
+        client = Client(transport=transport, init_timeout=self.INIT_TIMEOUT)
+        assert transport.keep_alive is True
+
+        # First connection: get the PID of the subprocess
+        async with client:
+            result1 = await client.call_tool("pid")
+            pid1: int = result1.data
+
+        # Kill the subprocess to simulate a crash
+        psutil.Process(pid1).kill()
+
+        # First attempt after crash fails — the stale session is
+        # detected and torn down so subsequent attempts succeed.
+        with pytest.raises(Exception):
+            async with client:
+                await client.call_tool("pid")
+
+        # Next connection starts a fresh subprocess
+        async with client:
+            result2 = await client.call_tool("pid")
+            pid2: int = result2.data
+
+        assert pid1 != pid2
+
+    async def test_keep_alive_false_recovers_after_subprocess_crash(self, stdio_script):
+        """When keep_alive=False, crash recovery works because disconnect() is always called."""
+        client = Client(
+            transport=PythonStdioTransport(script_path=stdio_script, keep_alive=False),
+            init_timeout=self.INIT_TIMEOUT,
+        )
+
+        async with client:
+            result1 = await client.call_tool("pid")
+            pid1: int = result1.data
+
+        # Process should already be dead (keep_alive=False), but kill to be sure
+        with pytest.raises(psutil.NoSuchProcess):
+            psutil.Process(pid1).kill()
+
+        # Next connection should work fine
+        async with client:
+            result2 = await client.call_tool("pid")
+            pid2: int = result2.data
+
+        assert pid1 != pid2
+
+    async def test_multiple_consecutive_crashes(self, stdio_script):
+        """Recovery works across multiple crash/reconnect cycles."""
+        client = Client(
+            transport=PythonStdioTransport(script_path=stdio_script),
+            init_timeout=self.INIT_TIMEOUT,
+        )
+        pids: list[int] = []
+
+        for _ in range(3):
+            async with client:
+                result = await client.call_tool("pid")
+                pid: int = result.data
+                pids.append(pid)
+
+            # Kill the subprocess
+            psutil.Process(pid).kill()
+
+            # Fail once to trigger cleanup
+            with pytest.raises(Exception):
+                async with client:
+                    await client.call_tool("pid")
+
+        # Each cycle should have started a new subprocess
+        assert len(set(pids)) == 3
+
+    async def test_crash_during_active_context(self, stdio_script):
+        """When subprocess dies while the client context is open, recovery works on the next attempt."""
+        client = Client(
+            transport=PythonStdioTransport(script_path=stdio_script),
+            init_timeout=self.INIT_TIMEOUT,
+        )
+        pid1: int = 0
+
+        with pytest.raises(Exception):
+            async with client:
+                result = await client.call_tool("pid")
+                pid1 = result.data
+                # Kill while the context is still open
+                psutil.Process(pid1).kill()
+                # This call hits the dead session
+                await client.call_tool("pid")
+
+        assert pid1 != 0, "First call should have succeeded before the crash"
+
+        # Recovery: next connection starts a fresh subprocess
+        async with client:
+            result = await client.call_tool("pid")
+            pid2: int = result.data
+
+        assert pid1 != pid2
+
+    async def test_proxy_recovers_after_stdio_crash(self, stdio_script):
+        """A proxy server wrapping a stdio backend recovers after the backend crashes."""
+        from fastmcp.server import create_proxy
+
+        backend_client = Client(
+            transport=PythonStdioTransport(script_path=stdio_script),
+            init_timeout=self.INIT_TIMEOUT,
+        )
+        proxy = create_proxy(target=backend_client, name="test-proxy")
+
+        # First call works
+        result1 = await proxy.call_tool("pid")
+        pid1 = int(result1.content[0].text)  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+
+        # Kill the backend subprocess
+        psutil.Process(pid1).kill()
+
+        # First call after crash fails
+        with pytest.raises(Exception):
+            await proxy.call_tool("pid")
+
+        # Second call recovers with a new subprocess
+        result2 = await proxy.call_tool("pid")
+        pid2 = int(result2.content[0].text)  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+
+        assert pid1 != pid2
+
+    async def test_concurrent_requests_during_crash(self, stdio_script):
+        """Multiple concurrent callers fail cleanly when subprocess dies, then recovery works."""
+        from fastmcp.server import create_proxy
+
+        backend_client = Client(
+            transport=PythonStdioTransport(script_path=stdio_script),
+            init_timeout=self.INIT_TIMEOUT,
+        )
+        proxy = create_proxy(target=backend_client, name="test-proxy")
+
+        # First call to get the PID
+        result = await proxy.call_tool("pid")
+        pid1 = int(result.content[0].text)  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+
+        # Kill the subprocess
+        psutil.Process(pid1).kill()
+
+        # Fire several concurrent requests — all should fail, none should hang
+        tasks = [proxy.call_tool("pid") for _ in range(5)]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        errors = [r for r in results if isinstance(r, Exception)]
+        assert len(errors) > 0
+
+        # Recovery: a subsequent request should succeed
+        result = await proxy.call_tool("pid")
+        pid2 = int(result.content[0].text)  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+        assert pid1 != pid2
+
+    async def test_clean_exit_recovers(self, tmp_path):
+        """Recovery works when the subprocess exits cleanly (exit code 0), not just crashes."""
+        script = tmp_path / "exit_script.py"
+        script.write_text(
+            inspect.cleandoc('''
+            import os, sys, threading
+            from fastmcp import FastMCP
+
+            mcp = FastMCP()
+            call_count = 0
+
+            @mcp.tool
+            def pid_then_exit() -> int:
+                """Returns PID, exits cleanly after second call."""
+                global call_count
+                call_count += 1
+                pid = os.getpid()
+                if call_count >= 2:
+                    threading.Timer(0.1, lambda: os._exit(0)).start()
+                return pid
+
+            if __name__ == "__main__":
+                mcp.run()
+        ''')
+        )
+
+        client = Client(
+            transport=PythonStdioTransport(script_path=script),
+            init_timeout=self.INIT_TIMEOUT,
+        )
+
+        async with client:
+            result1 = await client.call_tool("pid_then_exit")
+            pid1: int = result1.data
+            # Second call triggers delayed clean exit
+            await client.call_tool("pid_then_exit")
+            await asyncio.sleep(0.3)
+
+        # Recovery after clean exit
+        async with client:
+            result2 = await client.call_tool("pid_then_exit")
+            pid2: int = result2.data
+
+        assert pid1 != pid2
+
+    async def test_crash_during_initialization(self, tmp_path):
+        """Recovery works when subprocess crashes during the first connection attempt."""
+        # Script that exits immediately — crashes before init completes
+        crash_script = tmp_path / "crash_init.py"
+        crash_script.write_text(
+            inspect.cleandoc("""
+            import sys
+            sys.exit(1)
+        """)
+        )
+
+        client = Client(
+            transport=PythonStdioTransport(script_path=crash_script),
+            init_timeout=self.INIT_TIMEOUT,
+        )
+
+        with pytest.raises(Exception):
+            async with client:
+                pass
+
+        # Write a working script to the same path
+        crash_script.write_text(
+            inspect.cleandoc("""
+            import os
+            from fastmcp import FastMCP
+
+            mcp = FastMCP()
+
+            @mcp.tool
+            def pid() -> int:
+                return os.getpid()
+
+            if __name__ == "__main__":
+                mcp.run()
+        """)
+        )
+
+        # Recovery with the now-working script
+        async with client:
+            result = await client.call_tool("pid")
+            assert isinstance(result.data, int)
+
+
+class TestLogFile:
+    @pytest.fixture
+    def stdio_script_with_stderr(self, tmp_path):
+        script = inspect.cleandoc('''
+            import sys
+            from fastmcp import FastMCP
+
+            mcp = FastMCP()
+
+            @mcp.tool
+            def write_error(message: str) -> str:
+                """Writes a message to stderr and returns it"""
+                print(message, file=sys.stderr, flush=True)
+                return message
+
+            if __name__ == "__main__":
+                mcp.run()
+            ''')
+        script_file = tmp_path / "stderr_script.py"
+        script_file.write_text(script)
+        return script_file
+
+    async def test_log_file_parameter_accepted_by_stdio_transport(self, tmp_path):
+        """Test that log_file parameter can be set on StdioTransport"""
+        log_file_path = tmp_path / "errors.log"
+        transport = StdioTransport(
+            command="python", args=["script.py"], log_file=log_file_path
+        )
+        assert transport.log_file == log_file_path
+
+    async def test_log_file_parameter_accepted_by_python_stdio_transport(
+        self, tmp_path, stdio_script_with_stderr
+    ):
+        """Test that log_file parameter can be set on PythonStdioTransport"""
+        log_file_path = tmp_path / "errors.log"
+        transport = PythonStdioTransport(
+            script_path=stdio_script_with_stderr, log_file=log_file_path
+        )
+        assert transport.log_file == log_file_path
+
+    async def test_log_file_parameter_accepts_textio(self, tmp_path):
+        """Test that log_file parameter can accept a TextIO object"""
+        log_file_path = tmp_path / "errors.log"
+        with open(log_file_path, "w") as log_file:
+            transport = StdioTransport(
+                command="python", args=["script.py"], log_file=log_file
+            )
+            assert transport.log_file == log_file
+
+    async def test_log_file_captures_stderr_output_with_path(
+        self, tmp_path, stdio_script_with_stderr
+    ):
+        """Test that stderr output is written to the log_file when using Path"""
+        log_file_path = tmp_path / "errors.log"
+
+        transport = PythonStdioTransport(
+            script_path=stdio_script_with_stderr, log_file=log_file_path
+        )
+        client = Client(transport=transport)
+
+        async with client:
+            await client.call_tool("write_error", {"message": "Test error message"})
+
+        # Need to wait a bit for stderr to flush
+        await asyncio.sleep(0.1)
+
+        content = log_file_path.read_text()
+        assert "Test error message" in content
+
+    async def test_log_file_captures_stderr_output_with_textio(
+        self, tmp_path, stdio_script_with_stderr
+    ):
+        """Test that stderr output is written to the log_file when using TextIO"""
+        log_file_path = tmp_path / "errors.log"
+
+        with open(log_file_path, "w") as log_file:
+            transport = PythonStdioTransport(
+                script_path=stdio_script_with_stderr, log_file=log_file
+            )
+            client = Client(transport=transport)
+
+            async with client:
+                await client.call_tool(
+                    "write_error", {"message": "Test error with TextIO"}
+                )
+
+            # Need to wait a bit for stderr to flush
+            await asyncio.sleep(0.1)
+
+        content = log_file_path.read_text()
+        assert "Test error with TextIO" in content
+
+    async def test_log_file_none_uses_default_behavior(
+        self, tmp_path, stdio_script_with_stderr
+    ):
+        """Test that log_file=None uses default stderr handling"""
+        transport = PythonStdioTransport(
+            script_path=stdio_script_with_stderr, log_file=None
+        )
+        client = Client(transport=transport)
+
+        async with client:
+            # Should work without error even without explicit log_file
+            result = await client.call_tool(
+                "write_error", {"message": "Default stderr"}
+            )
+            assert result.data == "Default stderr"
diff --git a/tests/client/test_streamable_http.py b/tests/client/test_streamable_http.py
new file mode 100644
index 0000000..e4ea6e6
--- /dev/null
+++ b/tests/client/test_streamable_http.py
@@ -0,0 +1,291 @@
+import asyncio
+import json
+import sys
+from contextlib import suppress
+from unittest.mock import AsyncMock, call
+
+import pytest
+from mcp import MCPError
+from mcp_types import TextResourceContents
+
+from fastmcp import Context
+from fastmcp.client import Client
+from fastmcp.client.transports import StreamableHttpTransport
+from fastmcp.server.dependencies import get_http_request
+from fastmcp.server.server import FastMCP
+from fastmcp.utilities.tests import run_server_async
+
+
+def create_test_server() -> FastMCP:
+    """Create a FastMCP server with tools, resources, and prompts."""
+    server = FastMCP("TestServer")
+
+    @server.tool
+    def greet(name: str) -> str:
+        """Greet someone by name."""
+        return f"Hello, {name}!"
+
+    @server.tool
+    async def elicit(ctx: Context) -> str:
+        """Elicit a response from the user."""
+        result = await ctx.elicit("What is your name?", response_type=str)
+
+        if result.action == "accept":
+            return f"You said your name was: {result.data}!"
+        else:
+            return "No name provided"
+
+    @server.tool
+    def add(a: int, b: int) -> int:
+        """Add two numbers together."""
+        return a + b
+
+    @server.tool
+    async def sleep(seconds: float) -> str:
+        """Sleep for a given number of seconds."""
+        await asyncio.sleep(seconds)
+        return f"Slept for {seconds} seconds"
+
+    @server.tool
+    async def greet_with_progress(name: str, ctx: Context) -> str:
+        """Report progress for a greeting."""
+        await ctx.report_progress(0.5, 1.0, "Greeting in progress")
+        await ctx.report_progress(0.75, 1.0, "Almost there!")
+        return f"Hello, {name}!"
+
+    @server.resource(uri="data://users")
+    async def get_users() -> str:
+        import json
+
+        return json.dumps(["Alice", "Bob", "Charlie"])
+
+    @server.resource(uri="data://user/{user_id}")
+    async def get_user(user_id: str) -> str:
+        import json
+
+        return json.dumps({"id": user_id, "name": f"User {user_id}", "active": True})
+
+    @server.resource(uri="request://headers")
+    async def get_headers() -> str:
+        import json
+
+        request = get_http_request()
+        return json.dumps(dict(request.headers))
+
+    @server.prompt
+    def welcome(name: str) -> str:
+        """Example greeting prompt."""
+        return f"Welcome to FastMCP, {name}!"
+
+    return server
+
+
+@pytest.fixture
+async def streamable_http_server(request):
+    """Start a test server and return its URL."""
+    import fastmcp
+
+    stateless_http = getattr(request, "param", False)
+    if stateless_http:
+        fastmcp.settings.stateless_http = True
+
+    server = create_test_server()
+    async with run_server_async(server) as url:
+        yield url
+
+    if stateless_http:
+        fastmcp.settings.stateless_http = False
+
+
+@pytest.fixture
+async def streamable_http_server_with_streamable_http_alias():
+    """Test that the "streamable-http" transport alias works."""
+    server = create_test_server()
+    async with run_server_async(server, transport="streamable-http") as url:
+        yield url
+
+
+@pytest.fixture
+async def nested_server():
+    """Test nested server mounts with Starlette."""
+    import uvicorn
+    from starlette.applications import Starlette
+    from starlette.routing import Mount
+
+    from fastmcp.utilities.http import find_available_port
+
+    mcp_server = create_test_server()
+    mcp_app = mcp_server.http_app(path="/final/mcp")
+
+    # Nest the app under multiple mounts to test URL resolution
+    inner = Starlette(routes=[Mount("/nest-inner", app=mcp_app)])
+    outer = Starlette(
+        routes=[Mount("/nest-outer", app=inner)], lifespan=mcp_app.lifespan
+    )
+
+    # Run uvicorn with the nested ASGI app
+    port = find_available_port()
+
+    config = uvicorn.Config(
+        app=outer,
+        host="127.0.0.1",
+        port=port,
+        log_level="critical",
+        ws="websockets-sansio",
+        timeout_graceful_shutdown=0,
+    )
+
+    uvicorn_server = uvicorn.Server(config)
+    server_task = asyncio.create_task(uvicorn_server.serve())
+    await asyncio.sleep(0.1)
+
+    yield f"http://127.0.0.1:{port}/nest-outer/nest-inner/final/mcp"
+
+    # Graceful shutdown - required for uvicorn 0.39+ due to context isolation
+    uvicorn_server.should_exit = True
+    with suppress(asyncio.CancelledError, asyncio.TimeoutError):
+        await asyncio.wait_for(server_task, timeout=2.0)
+
+
+async def test_ping(streamable_http_server: str):
+    """Test pinging the server."""
+    async with Client(
+        transport=StreamableHttpTransport(streamable_http_server)
+    ) as client:
+        result = await client.ping()
+        assert result is True
+
+
+async def test_ping_with_streamable_http_alias(
+    streamable_http_server_with_streamable_http_alias: str,
+):
+    """Test pinging the server."""
+    async with Client(
+        transport=StreamableHttpTransport(
+            streamable_http_server_with_streamable_http_alias
+        )
+    ) as client:
+        result = await client.ping()
+        assert result is True
+
+
+async def test_http_headers(streamable_http_server: str):
+    """Test getting HTTP headers from the server."""
+    async with Client(
+        transport=StreamableHttpTransport(
+            streamable_http_server, headers={"X-DEMO-HEADER": "ABC"}
+        )
+    ) as client:
+        raw_result = await client.read_resource("request://headers")
+        assert isinstance(raw_result[0], TextResourceContents)
+        json_result = json.loads(raw_result[0].text)
+        assert "x-demo-header" in json_result
+        assert json_result["x-demo-header"] == "ABC"
+
+
+async def test_session_id_callback(streamable_http_server: str):
+    """Test getting mcp-session-id from the transport."""
+    transport = StreamableHttpTransport(streamable_http_server)
+    assert transport.get_session_id() is None
+    async with Client(transport=transport):
+        session_id = transport.get_session_id()
+        assert session_id is not None
+
+
+@pytest.mark.parametrize("streamable_http_server", [True, False], indirect=True)
+async def test_greet_with_progress_tool(streamable_http_server: str):
+    """Test calling the greet tool."""
+    progress_handler = AsyncMock(return_value=None)
+
+    async with Client(
+        transport=StreamableHttpTransport(streamable_http_server),
+        progress_handler=progress_handler,
+    ) as client:
+        result = await client.call_tool("greet_with_progress", {"name": "Alice"})
+        assert result.data == "Hello, Alice!"
+
+        progress_handler.assert_has_calls(
+            [
+                call(0.5, 1.0, "Greeting in progress"),
+                call(0.75, 1.0, "Almost there!"),
+            ]
+        )
+
+
+@pytest.mark.parametrize("streamable_http_server", [True, False], indirect=True)
+async def test_elicitation_tool(streamable_http_server: str, request):
+    """Test calling the elicitation tool in both stateless and stateful modes."""
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        return {"value": "Alice"}
+
+    stateless_http = request.node.callspec.params.get("streamable_http_server", False)
+    if stateless_http:
+        pytest.xfail("Elicitation is not supported in stateless HTTP mode")
+
+    async with Client(
+        transport=StreamableHttpTransport(streamable_http_server),
+        elicitation_handler=elicitation_handler,
+    ) as client:
+        result = await client.call_tool("elicit")
+        assert result.data == "You said your name was: Alice!"
+
+
+@pytest.mark.parametrize("streamable_http_server", [True], indirect=True)
+async def test_stateless_http_rejects_get_sse(streamable_http_server: str):
+    """Stateless servers should reject GET SSE requests with 405."""
+    import httpx
+
+    async with httpx.AsyncClient() as http_client:
+        response = await http_client.get(streamable_http_server)
+        assert response.status_code == 405
+
+
+@pytest.mark.parametrize("streamable_http_server", [True], indirect=True)
+async def test_stateless_http_still_accepts_post(streamable_http_server: str):
+    """Stateless servers should still handle POST requests normally."""
+    async with Client(
+        transport=StreamableHttpTransport(streamable_http_server)
+    ) as client:
+        result = await client.call_tool("greet", {"name": "World"})
+        assert result.data == "Hello, World!"
+
+
+async def test_nested_streamable_http_server_resolves_correctly(nested_server: str):
+    """Test patch for https://github.com/modelcontextprotocol/python-sdk/pull/659"""
+    async with Client(transport=StreamableHttpTransport(nested_server)) as client:
+        result = await client.ping()
+        assert result is True
+
+
+@pytest.mark.skipif(
+    sys.platform == "win32",
+    reason="Timeout tests are flaky on Windows. Timeouts *are* supported but the tests are unreliable.",
+)
+class TestTimeout:
+    async def test_timeout(self, streamable_http_server: str):
+        # note this transport behaves differently than others and raises
+        # MCPError from the *client* context
+        with pytest.raises(MCPError, match="timed out"):
+            async with Client(
+                transport=StreamableHttpTransport(streamable_http_server),
+                timeout=0.02,
+            ) as client:
+                await client.call_tool("sleep", {"seconds": 0.05})
+
+    async def test_timeout_tool_call(self, streamable_http_server: str):
+        async with Client(
+            transport=StreamableHttpTransport(streamable_http_server),
+        ) as client:
+            with pytest.raises(MCPError):
+                await client.call_tool("sleep", {"seconds": 0.2}, timeout=0.1)
+
+    async def test_timeout_tool_call_overrides_client_timeout(
+        self, streamable_http_server: str
+    ):
+        async with Client(
+            transport=StreamableHttpTransport(streamable_http_server),
+            timeout=2,
+        ) as client:
+            with pytest.raises(MCPError):
+                await client.call_tool("sleep", {"seconds": 0.2}, timeout=0.1)
diff --git a/tests/client/transports/__init__.py b/tests/client/transports/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/client/transports/test_memory_transport.py b/tests/client/transports/test_memory_transport.py
new file mode 100644
index 0000000..e5eab41
--- /dev/null
+++ b/tests/client/transports/test_memory_transport.py
@@ -0,0 +1,63 @@
+"""Tests for the in-memory FastMCPTransport.
+
+These tests verify transport-level behavior that affects all tests using
+Client(server) with an in-process FastMCP server.
+"""
+
+import time
+
+import pytest
+
+from fastmcp import Client, FastMCP
+from fastmcp.client.transports import FastMCPTransport
+
+
+def test_transport_repr_includes_server_name():
+    transport = FastMCPTransport(FastMCP("repr-test"))
+
+    assert repr(transport) == "<FastMCPTransport(server='repr-test')>"
+
+
+@pytest.mark.timeout(10)
+async def test_task_teardown_does_not_hang():
+    """In-memory transport must tear down in under 2 seconds after a task call.
+
+    This is a regression test for a teardown ordering bug where the Docket
+    Worker shutdown would hang for 5 seconds on every test that used
+    task=True. The root cause was the server lifespan (which owns the Docket
+    Worker) being torn down BEFORE the task group (which owns the server's
+    run() and all its pub/sub subscriptions). Fakeredis blocking operations
+    held by those subscriptions prevented the Worker's internal TaskGroup
+    from cancelling its children, causing a 5-second stall until the
+    Client's move_on_after(5) timeout fired.
+
+    The fix is to nest the task group INSIDE the lifespan context so that
+    all server tasks (and their fakeredis resources) are cancelled and
+    drained before Docket teardown begins.
+
+    If this test takes ~5 seconds, the context manager nesting in
+    FastMCPTransport.connect_session() has been reversed — the lifespan
+    must be the OUTER context and the task group must be the INNER context.
+    """
+    mcp = FastMCP("teardown-test")
+
+    @mcp.tool(task=True)
+    async def fast_tool(x: int) -> int:
+        return x * 2
+
+    t0 = time.monotonic()
+
+    async with Client(mcp) as client:
+        task = await client.call_tool("fast_tool", {"x": 21}, task=True)
+        result = await task.result()
+        assert result.data == 42
+
+    elapsed = time.monotonic() - t0
+
+    assert elapsed < 2.0, (
+        f"Client teardown took {elapsed:.1f}s — expected <2s. "
+        f"This usually means the context manager nesting in "
+        f"FastMCPTransport.connect_session() is wrong: the lifespan "
+        f"must be the OUTER context and the task group the INNER context. "
+        f"See the comment in memory.py for details."
+    )
diff --git a/tests/client/transports/test_no_redirect.py b/tests/client/transports/test_no_redirect.py
new file mode 100644
index 0000000..00af891
--- /dev/null
+++ b/tests/client/transports/test_no_redirect.py
@@ -0,0 +1,198 @@
+"""Tests verifying that client transports do not leak auth credentials on redirects.
+
+httpx automatically strips Authorization headers on cross-origin redirects via its
+_redirect_headers mechanism. These tests verify that FastMCP's transports rely on
+this behavior correctly and do not override it.
+"""
+
+import httpx
+import pytest
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import JSONResponse, RedirectResponse, Response
+from starlette.routing import Route
+
+from fastmcp.client.transports.http import StreamableHttpTransport
+from fastmcp.client.transports.sse import SSETransport
+
+
+class TestHttpxBuiltinRedirectProtection:
+    """Verify httpx's built-in cross-origin redirect auth stripping."""
+
+    async def test_httpx_strips_auth_on_cross_origin_redirect(self):
+        """httpx strips Authorization headers when redirecting to a different origin."""
+        received_headers: dict[str, str] = {}
+
+        async def target_endpoint(request: Request) -> Response:
+            received_headers.update(dict(request.headers))
+            return JSONResponse({"status": "ok"})
+
+        async def redirect_cross_origin(request: Request) -> Response:
+            return RedirectResponse(
+                url="http://other-host.example.com/target",
+                status_code=302,
+            )
+
+        app = Starlette(
+            routes=[
+                Route("/redirect", redirect_cross_origin),
+                Route("/target", target_endpoint),
+            ]
+        )
+
+        # Use an httpx client with follow_redirects=True (as MCP does)
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=app),
+            follow_redirects=True,
+        ) as client:
+            response = await client.get(
+                "http://origin-host.example.com/redirect",
+                headers={"Authorization": "Bearer secret-token"},
+            )
+
+        # httpx followed the redirect but stripped Authorization because
+        # the redirect target is a different origin
+        assert response.status_code == 200
+        assert "authorization" not in received_headers
+
+    async def test_httpx_preserves_auth_on_same_origin_redirect(self):
+        """httpx preserves Authorization headers when redirecting to the same origin."""
+        received_headers: dict[str, str] = {}
+
+        async def target_endpoint(request: Request) -> Response:
+            received_headers.update(dict(request.headers))
+            return JSONResponse({"status": "ok"})
+
+        async def redirect_same_origin(request: Request) -> Response:
+            return RedirectResponse(
+                url="http://same-host.example.com/target",
+                status_code=302,
+            )
+
+        app = Starlette(
+            routes=[
+                Route("/redirect", redirect_same_origin),
+                Route("/target", target_endpoint),
+            ]
+        )
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=app),
+            follow_redirects=True,
+        ) as client:
+            response = await client.get(
+                "http://same-host.example.com/redirect",
+                headers={"Authorization": "Bearer secret-token"},
+            )
+
+        assert response.status_code == 200
+        assert received_headers.get("authorization") == "Bearer secret-token"
+
+    @pytest.mark.parametrize(
+        "auth_header",
+        [
+            "Bearer my-secret-token",
+            "Basic dXNlcjpwYXNz",
+            "Token ghp_xxxxxxxxxxxx",
+        ],
+    )
+    async def test_various_auth_headers_stripped_on_cross_origin(
+        self, auth_header: str
+    ):
+        """Verify that different auth header formats are all stripped."""
+        received_headers: dict[str, str] = {}
+
+        async def target(request: Request) -> Response:
+            received_headers.update(dict(request.headers))
+            return JSONResponse({"status": "ok"})
+
+        async def redirect(request: Request) -> Response:
+            return RedirectResponse(
+                url="http://evil.example.com/steal",
+                status_code=307,
+            )
+
+        app = Starlette(
+            routes=[
+                Route("/api", redirect),
+                Route("/steal", target),
+            ]
+        )
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=app),
+            follow_redirects=True,
+        ) as client:
+            response = await client.get(
+                "http://legit.example.com/api",
+                headers={"Authorization": auth_header},
+            )
+
+        assert response.status_code == 200
+        assert "authorization" not in received_headers
+
+
+class TestMcpHttpClientRedirectProtection:
+    """Verify that MCP's default httpx client has redirect protection."""
+
+    async def test_create_mcp_http_client_strips_auth_on_cross_origin(self):
+        """create_mcp_http_client creates clients that strip auth on cross-origin redirects."""
+        received_headers: dict[str, str] = {}
+
+        async def target(request: Request) -> Response:
+            received_headers.update(dict(request.headers))
+            return JSONResponse({"status": "ok"})
+
+        async def redirect(request: Request) -> Response:
+            return RedirectResponse(
+                url="http://evil.example.com/steal",
+                status_code=302,
+            )
+
+        app = Starlette(
+            routes=[
+                Route("/api", redirect),
+                Route("/steal", target),
+            ]
+        )
+
+        # Use AsyncClient directly with ASGI transport rather than
+        # monkey-patching _transport on create_mcp_http_client, which
+        # breaks when proxy env vars are set.
+        client = httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=app),
+            headers={"Authorization": "Bearer secret"},
+            follow_redirects=True,
+        )
+
+        async with client:
+            response = await client.get("http://legit.example.com/api")
+
+        assert response.status_code == 200
+        assert "authorization" not in received_headers
+
+
+class TestStreamableHttpTransportFactory:
+    """Verify factory and verify-factory redirect behavior."""
+
+    def test_verify_factory_still_enables_redirects(self):
+        """The verify factory should still create clients with follow_redirects=True."""
+        transport = StreamableHttpTransport(
+            "https://example.com/mcp",
+            verify=False,
+        )
+        factory = transport._make_verify_factory()
+        assert factory is not None
+        client = factory()
+        assert client.follow_redirects is True
+
+    def test_sse_verify_factory_still_enables_redirects(self):
+        """The SSE verify factory should still create clients with follow_redirects=True."""
+        transport = SSETransport(
+            "https://example.com/sse",
+            verify=False,
+        )
+        factory = transport._make_verify_factory()
+        assert factory is not None
+        client = factory()
+        assert client.follow_redirects is True
diff --git a/tests/client/transports/test_transports.py b/tests/client/transports/test_transports.py
new file mode 100644
index 0000000..79e85ba
--- /dev/null
+++ b/tests/client/transports/test_transports.py
@@ -0,0 +1,293 @@
+import contextlib
+import ssl
+from collections.abc import AsyncIterator
+from ssl import VerifyMode
+from typing import Any, cast
+
+import httpx
+import pytest
+from mcp.shared._httpx_utils import McpHttpClientFactory
+
+from fastmcp import Client
+from fastmcp.client.auth.oauth import OAuth
+from fastmcp.client.transports import (
+    ClientTransport,
+    SSETransport,
+    StreamableHttpTransport,
+)
+
+
+class BasicTransport(ClientTransport):
+    @contextlib.asynccontextmanager
+    async def connect_session(self, **session_kwargs: Any) -> AsyncIterator[Any]:
+        raise AssertionError("BasicTransport does not create sessions")
+        yield
+
+
+class TestClientTransport:
+    def test_default_repr_uses_subclass_name(self):
+        assert repr(BasicTransport()) == "<BasicTransport>"
+
+    def test_default_session_id_is_none(self):
+        assert BasicTransport().get_session_id() is None
+
+    def test_client_rejects_auth_for_transports_without_auth_support(self):
+        with pytest.raises(ValueError, match="does not support auth"):
+            Client(BasicTransport(), auth="oauth")
+
+    def test_client_accepts_none_auth_for_transports_without_auth_support(self):
+        client = Client(BasicTransport(), auth=None)
+
+        assert isinstance(client.transport, BasicTransport)
+
+
+async def test_oauth_uses_same_client_as_transport_streamable_http():
+    transport = StreamableHttpTransport(
+        "https://some.fake.url/",
+        httpx_client_factory=lambda *args, **kwargs: httpx.AsyncClient(
+            verify=False, *args, **kwargs
+        ),
+        auth="oauth",
+    )
+
+    assert isinstance(transport.auth, OAuth)
+    async with transport.auth.httpx_client_factory() as httpx_client:
+        assert httpx_client._transport is not None
+        assert (
+            httpx_client._transport._pool._ssl_context.verify_mode  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+            == VerifyMode.CERT_NONE
+        )
+
+
+async def test_oauth_uses_same_client_as_transport_sse():
+    transport = SSETransport(
+        "https://some.fake.url/",
+        httpx_client_factory=lambda *args, **kwargs: httpx.AsyncClient(
+            verify=False, *args, **kwargs
+        ),
+        auth="oauth",
+    )
+
+    assert isinstance(transport.auth, OAuth)
+    async with transport.auth.httpx_client_factory() as httpx_client:
+        assert httpx_client._transport is not None
+        assert (
+            httpx_client._transport._pool._ssl_context.verify_mode  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+            == VerifyMode.CERT_NONE
+        )
+
+
+class TestSSLVerify:
+    def test_streamable_http_transport_stores_verify_false(self):
+        transport = StreamableHttpTransport(
+            "https://example.com/mcp",
+            verify=False,
+        )
+        assert transport.verify is False
+
+    def test_streamable_http_transport_stores_verify_ssl_context(self):
+        ctx = ssl.create_default_context()
+        transport = StreamableHttpTransport(
+            "https://example.com/mcp",
+            verify=ctx,
+        )
+        assert transport.verify is ctx
+
+    def test_streamable_http_transport_stores_verify_cert_path(self):
+        transport = StreamableHttpTransport(
+            "https://example.com/mcp",
+            verify="/path/to/cert.pem",
+        )
+        assert transport.verify == "/path/to/cert.pem"
+
+    def test_streamable_http_transport_verify_default_is_none(self):
+        transport = StreamableHttpTransport("https://example.com/mcp")
+        assert transport.verify is None
+
+    def test_sse_transport_stores_verify_false(self):
+        transport = SSETransport(
+            "https://example.com/sse",
+            verify=False,
+        )
+        assert transport.verify is False
+
+    def test_sse_transport_stores_verify_ssl_context(self):
+        ctx = ssl.create_default_context()
+        transport = SSETransport(
+            "https://example.com/sse",
+            verify=ctx,
+        )
+        assert transport.verify is ctx
+
+    def test_sse_transport_verify_default_is_none(self):
+        transport = SSETransport("https://example.com/sse")
+        assert transport.verify is None
+
+    def test_client_passes_verify_to_streamable_http_transport(self):
+        client = Client("https://example.com/mcp", verify=False)
+        assert isinstance(client.transport, StreamableHttpTransport)
+        assert client.transport.verify is False
+
+    def test_client_passes_verify_ssl_context_to_transport(self):
+        ctx = ssl.create_default_context()
+        client = Client("https://example.com/mcp", verify=ctx)
+        assert isinstance(client.transport, StreamableHttpTransport)
+        assert client.transport.verify is ctx
+
+    def test_client_passes_verify_cert_path_to_transport(self):
+        client = Client(
+            "https://example.com/mcp",
+            verify="/path/to/cert.pem",
+        )
+        assert isinstance(client.transport, StreamableHttpTransport)
+        assert client.transport.verify == "/path/to/cert.pem"
+
+    def test_client_verify_none_leaves_transport_default(self):
+        client = Client("https://example.com/mcp")
+        assert isinstance(client.transport, StreamableHttpTransport)
+        assert client.transport.verify is None
+
+    def test_client_verify_raises_for_non_http_transport(self):
+        from fastmcp import FastMCP
+
+        server = FastMCP("test")
+        with pytest.raises(
+            ValueError,
+            match="only supported for HTTP transports",
+        ):
+            Client(server, verify=False)
+
+    def test_client_passes_verify_to_sse_transport(self):
+        client = Client("https://example.com/sse", verify=False)
+        assert isinstance(client.transport, SSETransport)
+        assert client.transport.verify is False
+
+    async def test_streamable_http_verify_propagates_to_oauth(self):
+        transport = StreamableHttpTransport(
+            "https://example.com/mcp",
+            verify=False,
+            auth="oauth",
+        )
+        assert isinstance(transport.auth, OAuth)
+        async with transport.auth.httpx_client_factory() as httpx_client:
+            assert (
+                httpx_client._transport._pool._ssl_context.verify_mode  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+                == VerifyMode.CERT_NONE
+            )
+
+    async def test_sse_verify_propagates_to_oauth(self):
+        transport = SSETransport(
+            "https://example.com/sse",
+            verify=False,
+            auth="oauth",
+        )
+        assert isinstance(transport.auth, OAuth)
+        async with transport.auth.httpx_client_factory() as httpx_client:
+            assert (
+                httpx_client._transport._pool._ssl_context.verify_mode  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+                == VerifyMode.CERT_NONE
+            )
+
+    async def test_client_verify_propagates_to_oauth(self):
+        client = Client(
+            "https://example.com/mcp",
+            verify=False,
+            auth="oauth",
+        )
+        assert isinstance(client.transport, StreamableHttpTransport)
+        assert isinstance(client.transport.auth, OAuth)
+        async with client.transport.auth.httpx_client_factory() as httpx_client:
+            assert (
+                httpx_client._transport._pool._ssl_context.verify_mode  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+                == VerifyMode.CERT_NONE
+            )
+
+    async def test_verify_propagates_to_preconstructed_oauth_instance(self):
+        transport = StreamableHttpTransport(
+            "https://example.com/mcp",
+            verify=False,
+            auth=OAuth(),
+        )
+        assert isinstance(transport.auth, OAuth)
+        async with transport.auth.httpx_client_factory() as httpx_client:
+            assert (
+                httpx_client._transport._pool._ssl_context.verify_mode  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+                == VerifyMode.CERT_NONE
+            )
+
+    async def test_client_verify_resyncs_existing_oauth_on_transport(self):
+        transport = StreamableHttpTransport(
+            "https://example.com/mcp",
+            auth="oauth",
+        )
+        assert isinstance(transport.auth, OAuth)
+        # OAuth was created without verify — factory should be default
+        async with transport.auth.httpx_client_factory() as httpx_client:
+            assert (
+                httpx_client._transport._pool._ssl_context.verify_mode  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+                != VerifyMode.CERT_NONE
+            )
+
+        # Now wrap in Client with verify=False — should resync OAuth
+        client = Client(transport, verify=False)
+        assert isinstance(client.transport.auth, OAuth)
+        async with client.transport.auth.httpx_client_factory() as httpx_client:
+            assert (
+                httpx_client._transport._pool._ssl_context.verify_mode  # type: ignore[attr-defined]  # ty: ignore[unresolved-attribute]
+                == VerifyMode.CERT_NONE
+            )
+
+    async def test_client_verify_overrides_transport_verify_in_oauth(self):
+        transport = StreamableHttpTransport(
+            "https://example.com/mcp",
+            verify=False,
+            auth="oauth",
+        )
+        assert isinstance(transport.auth, OAuth)
+        # OAuth should initially have verify=False
+        async with transport.auth.httpx_client_factory() as httpx_client:
+            assert (
+                httpx_client._transport._pool._ssl_context.verify_mode  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+                == VerifyMode.CERT_NONE
+            )
+
+        # Client overrides verify to True — OAuth should update
+        client = Client(transport, verify=True)
+        assert isinstance(client.transport.auth, OAuth)
+        async with client.transport.auth.httpx_client_factory() as httpx_client:
+            assert (
+                httpx_client._transport._pool._ssl_context.verify_mode  # type: ignore[attr-defined]  # ty: ignore[unresolved-attribute]
+                != VerifyMode.CERT_NONE
+            )
+
+    async def test_oauth_custom_factory_preserved_with_verify(self):
+        custom_factory = cast(
+            McpHttpClientFactory,
+            lambda **kwargs: httpx.AsyncClient(verify=False, **kwargs),
+        )
+        auth = OAuth(httpx_client_factory=custom_factory)
+        transport = StreamableHttpTransport(
+            "https://example.com/mcp",
+            verify=True,
+            auth=auth,
+        )
+        assert isinstance(transport.auth, OAuth)
+        assert transport.auth.httpx_client_factory is custom_factory
+
+    def test_warns_when_both_factory_and_verify_provided_streamable(self):
+        factory = cast(McpHttpClientFactory, httpx.AsyncClient)
+        with pytest.warns(UserWarning, match="httpx_client_factory.*takes precedence"):
+            StreamableHttpTransport(
+                "https://example.com/mcp",
+                httpx_client_factory=factory,
+                verify=False,
+            )
+
+    def test_warns_when_both_factory_and_verify_provided_sse(self):
+        factory = cast(McpHttpClientFactory, httpx.AsyncClient)
+        with pytest.warns(UserWarning, match="httpx_client_factory.*takes precedence"):
+            SSETransport(
+                "https://example.com/sse",
+                httpx_client_factory=factory,
+                verify=False,
+            )
diff --git a/tests/client/transports/test_uv_transport.py b/tests/client/transports/test_uv_transport.py
new file mode 100644
index 0000000..8b27bab
--- /dev/null
+++ b/tests/client/transports/test_uv_transport.py
@@ -0,0 +1,120 @@
+import inspect
+import sys
+import tempfile
+from pathlib import Path
+
+import pytest
+
+import fastmcp
+from fastmcp.client import Client
+from fastmcp.client.client import CallToolResult
+from fastmcp.client.transports import StdioTransport, UvStdioTransport
+
+# Detect if running from dev install to use local source instead of PyPI
+_is_dev_install = "dev" in fastmcp.__version__
+_fastmcp_src_dir = (
+    Path(__file__).parent.parent.parent.parent if _is_dev_install else None
+)
+
+
+@pytest.mark.timeout(60)
+@pytest.mark.client_process
+@pytest.mark.skipif(
+    sys.platform == "win32",
+    reason="Windows file locking issues with uv client process cleanup",
+)
+async def test_uv_transport():
+    with tempfile.TemporaryDirectory() as tmpdir:
+        script: str = inspect.cleandoc('''
+            from fastmcp import FastMCP
+
+            mcp = FastMCP()
+
+            @mcp.tool
+            def add(x: int, y: int) -> int:
+                """Adds two numbers together"""
+                return x + y
+
+            if __name__ == "__main__":
+                mcp.run()
+            ''')
+        script_file: Path = Path(tmpdir) / "uv.py"
+        _ = script_file.write_text(script)
+
+        client: Client[UvStdioTransport] = Client(
+            transport=UvStdioTransport(command=str(script_file), keep_alive=False)
+        )
+
+        async with client:
+            result: CallToolResult = await client.call_tool("add", {"x": 1, "y": 2})
+            sum: int = result.data  # pyright: ignore[reportAny]
+
+        # Explicitly close the transport to ensure subprocess cleanup
+        await client.transport.close()
+        assert sum == 3
+
+
+@pytest.mark.timeout(60)
+@pytest.mark.client_process
+@pytest.mark.skipif(
+    sys.platform == "win32",
+    reason="Windows file locking issues with uv client process cleanup",
+)
+async def test_uv_transport_module():
+    with tempfile.TemporaryDirectory() as tmpdir:
+        module_dir = Path(tmpdir) / "my_module"
+        module_dir.mkdir()
+        module_script = inspect.cleandoc('''
+            from fastmcp import FastMCP
+
+            mcp = FastMCP()
+
+            @mcp.tool
+            def add(x: int, y: int) -> int:
+                """Adds two numbers together"""
+                return x + y
+            ''')
+        script_file: Path = module_dir / "module.py"
+        _ = script_file.write_text(module_script)
+
+        main_script: str = inspect.cleandoc("""
+            from .module import mcp
+            mcp.run()
+        """)
+        main_file = module_dir / "__main__.py"
+        _ = main_file.write_text(main_script)
+
+        # In dev installs, use --with-editable to install local source.
+        # In releases, use --with to install from PyPI.
+        if _is_dev_install and _fastmcp_src_dir:
+            transport: StdioTransport = StdioTransport(
+                command="uv",
+                args=[
+                    "run",
+                    "--directory",
+                    tmpdir,
+                    "--with-editable",
+                    f"{_fastmcp_src_dir}[server]",
+                    "--module",
+                    "my_module",
+                ],
+                keep_alive=False,
+            )
+        else:
+            transport = UvStdioTransport(
+                with_packages=["fastmcp"],
+                command="my_module",
+                module=True,
+                project_directory=Path(tmpdir),
+                keep_alive=False,
+            )
+
+        client: Client[StdioTransport] = Client(transport=transport)
+
+        async with client:
+            result: CallToolResult = await client.call_tool("add", {"x": 1, "y": 2})
+            sum: int = result.data  # pyright: ignore[reportAny]
+
+        # Explicitly close the transport to ensure subprocess cleanup
+        await client.transport.close()
+        assert sum == 3
diff --git a/tests/conformance/__init__.py b/tests/conformance/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/conformance/expected-failures.yml b/tests/conformance/expected-failures.yml
new file mode 100644
index 0000000..46b2081
--- /dev/null
+++ b/tests/conformance/expected-failures.yml
@@ -0,0 +1,6 @@
+server:
+  - completion-complete
+  - server-sse-polling
+  - resources-subscribe
+  - resources-unsubscribe
+  - dns-rebinding-protection
diff --git a/tests/conformance/server.py b/tests/conformance/server.py
new file mode 100644
index 0000000..158b094
--- /dev/null
+++ b/tests/conformance/server.py
@@ -0,0 +1,377 @@
+"""FastMCP conformance test server.
+
+Registers the exact tools, resources, and prompts expected by the
+MCP conformance test suite (https://github.com/modelcontextprotocol/conformance).
+"""
+
+import asyncio
+import base64
+import json
+import sys
+from enum import Enum as PyEnum
+
+import mcp_types
+from mcp_types import EmbeddedResource, ImageContent, TextContent
+from pydantic import BaseModel, Field
+
+from fastmcp import FastMCP
+from fastmcp.exceptions import ToolError
+from fastmcp.prompts import Message
+from fastmcp.server.context import Context
+from fastmcp.tools.function_tool import FunctionTool
+from fastmcp.utilities.types import Audio, Image
+
+# Minimal 1x1 red PNG for image tests (89 bytes)
+_1X1_PNG = base64.b64decode(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4"
+    "nGP4z8BQDwAEgAF/pooBPQAAAABJRU5ErkJggg=="
+)
+
+# Minimal valid WAV: 16-bit mono PCM, 44100 Hz, single silent sample
+_SILENT_WAV = (
+    b"RIFF"
+    + (38).to_bytes(4, "little")
+    + b"WAVEfmt "
+    + (16).to_bytes(4, "little")
+    + (1).to_bytes(2, "little")  # PCM
+    + (1).to_bytes(2, "little")  # mono
+    + (44100).to_bytes(4, "little")  # sample rate
+    + (88200).to_bytes(4, "little")  # byte rate
+    + (2).to_bytes(2, "little")  # block align
+    + (16).to_bytes(2, "little")  # bits per sample
+    + b"data"
+    + (2).to_bytes(4, "little")
+    + (0).to_bytes(2, "little")  # one silent sample
+)
+
+server = FastMCP("conformance-test-server", dereference_schemas=False)
+
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+
+@server.tool(name="test_simple_text")
+async def test_simple_text() -> str:
+    """A simple text tool for conformance testing."""
+    return "This is a simple text response for testing."
+
+
+@server.tool(name="test_image_content")
+async def test_image_content() -> Image:
+    """Returns a PNG image."""
+    return Image(data=_1X1_PNG, format="png")
+
+
+@server.tool(name="test_audio_content")
+async def test_audio_content() -> Audio:
+    """Returns WAV audio."""
+    return Audio(data=_SILENT_WAV, format="wav")
+
+
+@server.tool(name="test_embedded_resource")
+async def test_embedded_resource() -> list:
+    """Returns an embedded resource."""
+    return [
+        EmbeddedResource(
+            type="resource",
+            resource=mcp_types.TextResourceContents(
+                uri="test://embedded-resource",
+                mime_type="text/plain",
+                text="This is an embedded resource content.",
+            ),
+        )
+    ]
+
+
+@server.tool(name="test_multiple_content_types")
+async def test_multiple_content_types() -> list:
+    """Returns mixed text, image, and resource content."""
+    return [
+        TextContent(type="text", text="This is a text part of the response."),
+        ImageContent(
+            type="image",
+            data=base64.b64encode(_1X1_PNG).decode(),
+            mime_type="image/png",
+        ),
+        EmbeddedResource(
+            type="resource",
+            resource=mcp_types.TextResourceContents(
+                uri="test://mixed-content-resource",
+                mime_type="application/json",
+                text='{"test":"data","value":123}',
+            ),
+        ),
+    ]
+
+
+@server.tool(name="test_error_handling")
+async def test_error_handling() -> str:
+    """Always returns an error."""
+    raise ToolError("This tool intentionally returns an error for testing")
+
+
+@server.tool(name="test_tool_with_logging")
+async def test_tool_with_logging(ctx: Context) -> str:
+    """Sends log notifications during execution."""
+    await ctx.info("Tool execution started")
+    await asyncio.sleep(0.05)
+    await ctx.info("Tool processing data")
+    await asyncio.sleep(0.05)
+    await ctx.info("Tool execution completed")
+    return "Logging test complete."
+
+
+@server.tool(name="test_tool_with_progress")
+async def test_tool_with_progress(ctx: Context) -> str:
+    """Reports progress notifications."""
+    await ctx.report_progress(0, 100)
+    await asyncio.sleep(0.05)
+    await ctx.report_progress(50, 100)
+    await asyncio.sleep(0.05)
+    await ctx.report_progress(100, 100)
+    return "Progress test complete."
+
+
+@server.tool(name="test_sampling")
+async def test_sampling(prompt: str, ctx: Context) -> str:
+    """Requests LLM sampling via the client."""
+    result = await ctx.sample(
+        messages=[prompt],
+        result_type=str,
+    )
+    return f"Sampling result: {result}"
+
+
+class _UserInfo(BaseModel):
+    username: str
+    email: str
+
+
+@server.tool(name="test_elicitation")
+async def test_elicitation(message: str, ctx: Context) -> str:
+    """Requests user input via elicitation."""
+    result = await ctx.elicit(message, _UserInfo)
+    return f"Elicitation result: {result}"
+
+
+class _UserStatus(str, PyEnum):
+    active = "active"
+    inactive = "inactive"
+    pending = "pending"
+
+
+class _DefaultsForm(BaseModel):
+    name: str = Field(default="John Doe", description="User name")
+    age: int = Field(default=30, description="User age")
+    score: float = Field(default=95.5, description="User score")
+    status: _UserStatus = Field(default=_UserStatus.active, description="User status")
+    verified: bool = Field(default=True, description="Verification status")
+
+
+@server.tool(name="test_elicitation_sep1034_defaults")
+async def test_elicitation_sep1034_defaults(ctx: Context) -> str:
+    """Tests elicitation with default values per SEP-1034."""
+    result = await ctx.elicit(
+        "Please review and update the form fields with defaults",
+        _DefaultsForm,
+    )
+    return f"Elicitation completed: {result}"
+
+
+@server.tool(name="test_elicitation_sep1330_enums")
+async def test_elicitation_sep1330_enums(ctx: Context) -> str:
+    """Tests elicitation with enum schema improvements per SEP-1330."""
+    result = await ctx.session.elicit(
+        message="Please select options from the enum fields",
+        requested_schema={
+            "type": "object",
+            "properties": {
+                "untitledSingle": {
+                    "type": "string",
+                    "description": "Select one option",
+                    "enum": ["option1", "option2", "option3"],
+                },
+                "titledSingle": {
+                    "type": "string",
+                    "description": "Select one option with titles",
+                    "oneOf": [
+                        {"const": "value1", "title": "First Option"},
+                        {"const": "value2", "title": "Second Option"},
+                        {"const": "value3", "title": "Third Option"},
+                    ],
+                },
+                "legacyEnum": {
+                    "type": "string",
+                    "description": "Select one option (legacy)",
+                    "enum": ["opt1", "opt2", "opt3"],
+                    "enumNames": [
+                        "Option One",
+                        "Option Two",
+                        "Option Three",
+                    ],
+                },
+                "untitledMulti": {
+                    "type": "array",
+                    "description": "Select multiple options",
+                    "minItems": 1,
+                    "maxItems": 3,
+                    "items": {
+                        "type": "string",
+                        "enum": ["option1", "option2", "option3"],
+                    },
+                },
+                "titledMulti": {
+                    "type": "array",
+                    "description": "Select multiple options with titles",
+                    "minItems": 1,
+                    "maxItems": 3,
+                    "items": {
+                        "anyOf": [
+                            {"const": "value1", "title": "First Choice"},
+                            {"const": "value2", "title": "Second Choice"},
+                            {"const": "value3", "title": "Third Choice"},
+                        ]
+                    },
+                },
+            },
+            "required": [],
+        },
+        related_request_id=ctx.request_id,
+    )
+    return f"Elicitation completed: action={result.action}, content={json.dumps(result.content or {})}"
+
+
+async def _json_schema_2020_12_fn(
+    name: str | None = None,
+    address: dict | None = None,
+) -> str:
+    """Tool with JSON Schema 2020-12 features for conformance testing (SEP-1613)."""
+    return f"JSON Schema 2020-12 tool called with: name={name}, address={address}"
+
+
+server.add_tool(
+    FunctionTool(
+        fn=_json_schema_2020_12_fn,
+        name="json_schema_2020_12_tool",
+        description="Tool with JSON Schema 2020-12 features for conformance testing (SEP-1613)",
+        parameters={
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "object",
+            "$defs": {
+                "address": {
+                    "type": "object",
+                    "properties": {
+                        "street": {"type": "string"},
+                        "city": {"type": "string"},
+                    },
+                }
+            },
+            "properties": {
+                "name": {"type": "string"},
+                "address": {"$ref": "#/$defs/address"},
+            },
+            "additionalProperties": False,
+        },
+    )
+)
+
+
+# ---------------------------------------------------------------------------
+# Resources
+# ---------------------------------------------------------------------------
+
+
+@server.resource(
+    "test://static-text",
+    name="Static text resource",
+    mime_type="text/plain",
+)
+async def static_text_resource() -> str:
+    """Returns static text content."""
+    return "This is the content of the static text resource."
+
+
+@server.resource(
+    "test://static-binary",
+    name="Static binary resource",
+    mime_type="image/png",
+)
+async def static_binary_resource() -> bytes:
+    """Returns a binary PNG image."""
+    return _1X1_PNG
+
+
+@server.resource(
+    "test://template/{id}/data",
+    name="Template resource",
+    mime_type="application/json",
+)
+async def template_resource(id: str) -> str:
+    """Returns JSON data with the template parameter substituted."""
+    return json.dumps({"id": id, "templateTest": True, "data": f"Data for ID: {id}"})
+
+
+@server.resource(
+    "test://watched-resource",
+    name="Watched resource",
+    mime_type="text/plain",
+)
+async def watched_resource() -> str:
+    """A resource that supports subscriptions."""
+    return "Watched resource content."
+
+
+# ---------------------------------------------------------------------------
+# Prompts
+# ---------------------------------------------------------------------------
+
+
+@server.prompt(name="test_simple_prompt")
+async def test_simple_prompt() -> str:
+    """A simple prompt for conformance testing."""
+    return "This is a simple prompt for testing."
+
+
+@server.prompt(name="test_prompt_with_arguments")
+async def test_prompt_with_arguments(arg1: str, arg2: str) -> str:
+    """A prompt that accepts arguments."""
+    return f"Prompt with arguments: arg1='{arg1}', arg2='{arg2}'"
+
+
+@server.prompt(name="test_prompt_with_embedded_resource")
+async def test_prompt_with_embedded_resource(resourceUri: str) -> list:
+    """A prompt that returns an embedded resource."""
+    return [
+        Message(
+            EmbeddedResource(
+                type="resource",
+                resource=mcp_types.TextResourceContents(
+                    uri=resourceUri,
+                    mime_type="text/plain",
+                    text=f"Content of resource {resourceUri}",
+                ),
+            )
+        ),
+    ]
+
+
+@server.prompt(name="test_prompt_with_image")
+async def test_prompt_with_image() -> list:
+    """A prompt that returns an image."""
+    return [
+        Message(
+            ImageContent(
+                type="image",
+                data=base64.b64encode(_1X1_PNG).decode(),
+                mime_type="image/png",
+            )
+        ),
+        Message("Please analyze the image above."),
+    ]
+
+
+if __name__ == "__main__":
+    port = int(sys.argv[1]) if len(sys.argv) > 1 else 8000
+    server.run(transport="streamable-http", host="127.0.0.1", port=port)
diff --git a/tests/conformance/test_conformance.py b/tests/conformance/test_conformance.py
new file mode 100644
index 0000000..971efbf
--- /dev/null
+++ b/tests/conformance/test_conformance.py
@@ -0,0 +1,98 @@
+"""Run the MCP conformance test suite against a FastMCP server.
+
+Requires Node.js and npx to be available on PATH.
+Mark: pytest -m conformance
+"""
+
+import shutil
+import socket
+import subprocess
+import threading
+import time
+from pathlib import Path
+
+import pytest
+import uvicorn
+
+CONFORMANCE_DIR = Path(__file__).parent
+EXPECTED_FAILURES = CONFORMANCE_DIR / "expected-failures.yml"
+HOST = "127.0.0.1"
+MCP_PATH = "/mcp"
+
+
+def _get_free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        s.listen(1)
+        return s.getsockname()[1]
+
+
+@pytest.fixture(scope="module")
+def _require_npx():
+    if shutil.which("npx") is None:
+        pytest.skip("npx not found on PATH — install Node.js to run conformance tests")
+
+
+@pytest.fixture(scope="module")
+def conformance_server(_require_npx):
+    """Start the conformance test server in a background thread."""
+    from tests.conformance.server import server as mcp_server
+
+    port = _get_free_port()
+    app = mcp_server.http_app(transport="streamable-http", path=MCP_PATH)
+
+    config = uvicorn.Config(app, host=HOST, port=port, log_level="warning")
+    uv_server = uvicorn.Server(config)
+
+    thread = threading.Thread(target=uv_server.run, daemon=True)
+    thread.start()
+
+    # Wait for server to accept connections
+    url = f"http://{HOST}:{port}{MCP_PATH}"
+    deadline = time.monotonic() + 10
+    while time.monotonic() < deadline:
+        try:
+            with socket.create_connection((HOST, port), timeout=1):
+                break
+        except OSError:
+            time.sleep(0.1)
+    else:
+        pytest.fail("Conformance server did not start in time")
+
+    yield url
+
+    uv_server.should_exit = True
+    thread.join(timeout=5)
+
+
+@pytest.mark.conformance
+@pytest.mark.timeout(120)
+def test_mcp_conformance(conformance_server):
+    """Run the full MCP conformance test suite against the server."""
+    cmd = [
+        "npx",
+        "--yes",
+        "@modelcontextprotocol/conformance@latest",
+        "server",
+        "--url",
+        conformance_server,
+        "--suite",
+        "all",
+    ]
+
+    if EXPECTED_FAILURES.exists():
+        cmd.extend(["--expected-failures", str(EXPECTED_FAILURES)])
+
+    result = subprocess.run(cmd, capture_output=True, text=True, timeout=90)
+
+    # Print output for visibility in test results
+    if result.stdout:
+        print(result.stdout)
+    if result.stderr:
+        print(result.stderr)
+
+    assert result.returncode == 0, (
+        f"Conformance tests failed (exit code {result.returncode}).\n"
+        f"stdout:\n{result.stdout}\n"
+        f"stderr:\n{result.stderr}"
+    )
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 0000000..51ee2c2
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,340 @@
+import asyncio
+import logging
+import secrets
+import socket
+import sys
+from collections.abc import Callable, Generator
+from datetime import timedelta
+from pathlib import Path
+from typing import Any
+
+import pytest
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+from fastmcp.utilities.tests import temporary_settings
+
+# Use SelectorEventLoop on Windows to avoid ProactorEventLoop crashes
+# See: https://github.com/python/cpython/issues/116773
+if sys.platform == "win32":
+    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
+
+
+def make_server_request_context(
+    *,
+    method: str = "tools/list",
+    params: dict[str, Any] | None = None,
+) -> Any:
+    """Build a minimal SDK ServerRequestContext for direct handler unit tests.
+
+    The v2 SDK hands handlers a ``ServerRequestContext`` argument. Tests that
+    invoke FastMCP's ``_on_*`` handlers directly (without a live session) use
+    this to construct a stand-in context that ``bind_request_context`` accepts.
+    """
+    from unittest.mock import MagicMock
+
+    from mcp.server.context import ServerRequestContext
+
+    return ServerRequestContext(
+        session=MagicMock(),
+        lifespan_context={},
+        protocol_version="2025-06-18",
+        method=method,
+        params=params,
+        request_id=0,
+        meta=None,
+        request=None,
+    )
+
+
+def pytest_collection_modifyitems(items):
+    """Automatically mark tests in integration_tests folder with 'integration' marker."""
+    for item in items:
+        # Check if the test is in the integration_tests folder
+        if "integration_tests" in str(item.fspath):
+            item.add_marker(pytest.mark.integration)
+
+
+@pytest.fixture(autouse=True)
+def import_rich_rule():
+    # What a hack
+    import rich.rule  # noqa: F401
+
+    yield
+
+
+@pytest.fixture(autouse=True)
+def enable_fastmcp_logger_propagation(caplog):
+    """Enable propagation on FastMCP root logger so caplog captures FastMCP log messages.
+
+    FastMCP loggers have propagate=False by default, which prevents messages from
+    reaching pytest's caplog handler (attached to root logger). This fixture
+    temporarily enables propagation on the FastMCP root logger so FastMCP logs
+    are captured in tests.
+    """
+    root_logger = logging.getLogger("fastmcp")
+    original_propagate = root_logger.propagate
+    root_logger.propagate = True
+
+    yield
+
+    root_logger.propagate = original_propagate
+
+
+@pytest.fixture(autouse=True)
+def isolate_settings_home(tmp_path: Path):
+    """Ensure each test uses an isolated settings.home directory.
+
+    This prevents file locking issues when multiple tests share the same
+    storage directory in settings.home / "oauth-proxy".
+
+    Also sets a fast Docket polling interval for tests — the default 50ms
+    is fine for production but still adds ~25ms average pickup latency per
+    task. 10ms makes task tests near-instant.
+    """
+    test_home = tmp_path / "fastmcp-test-home"
+    test_home.mkdir(exist_ok=True)
+
+    with temporary_settings(
+        home=test_home,
+        docket__minimum_check_interval=timedelta(milliseconds=10),
+        docket__url=f"memory://{secrets.token_hex(4)}",
+        client_disconnect_timeout=1,
+    ):
+        yield
+
+
+def get_fn_name(fn: Callable[..., Any]) -> str:
+    return fn.__name__  # ty: ignore[unresolved-attribute]
+
+
+@pytest.fixture
+def worker_id(request):
+    """Get the xdist worker ID, or 'master' if not using xdist."""
+    return getattr(request.config, "workerinput", {}).get("workerid", "master")
+
+
+@pytest.fixture
+def free_port():
+    """Get a free port for the test to use."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        s.listen(1)
+        port = s.getsockname()[1]
+    return port
+
+
+@pytest.fixture
+def free_port_factory(worker_id):
+    """Factory to get free ports that tracks used ports per test session."""
+    used_ports = set()
+
+    def get_port():
+        while True:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.bind(("127.0.0.1", 0))
+                s.listen(1)
+                port = s.getsockname()[1]
+                if port not in used_ports:
+                    used_ports.add(port)
+                    return port
+
+    return get_port
+
+
+@pytest.fixture(scope="session")
+def otel_trace_provider() -> Generator[
+    tuple[TracerProvider, InMemorySpanExporter], None, None
+]:
+    """Configure OTEL SDK with in-memory span exporter for testing.
+
+    Session-scoped because TracerProvider can only be set once per process.
+    """
+    exporter = InMemorySpanExporter()
+    provider = TracerProvider()
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    trace.set_tracer_provider(provider)
+    yield provider, exporter
+
+
+@pytest.fixture
+def trace_exporter(
+    otel_trace_provider: tuple[TracerProvider, InMemorySpanExporter],
+) -> Generator[InMemorySpanExporter, None, None]:
+    """Get the span exporter and clear it between tests."""
+    _, exporter = otel_trace_provider
+    exporter.clear()
+    yield exporter
+    exporter.clear()
+
+
+@pytest.fixture
+def fastmcp_server():
+    """Fixture that creates a FastMCP server with tools, resources, and prompts."""
+    import asyncio
+    import json
+
+    from fastmcp import FastMCP
+
+    server = FastMCP("TestServer")
+
+    # Add a tool
+    @server.tool
+    def greet(name: str) -> str:
+        """Greet someone by name."""
+        return f"Hello, {name}!"
+
+    # Add a second tool
+    @server.tool
+    def add(a: int, b: int) -> int:
+        """Add two numbers together."""
+        return a + b
+
+    @server.tool
+    async def sleep(seconds: float) -> str:
+        """Sleep for a given number of seconds."""
+        await asyncio.sleep(seconds)
+        return f"Slept for {seconds} seconds"
+
+    # Add a resource (return JSON string for proper typing)
+    @server.resource(uri="data://users")
+    async def get_users() -> str:
+        return json.dumps(["Alice", "Bob", "Charlie"], separators=(",", ":"))
+
+    # Add a resource template (return JSON string for proper typing)
+    @server.resource(uri="data://user/{user_id}")
+    async def get_user(user_id: str) -> str:
+        return json.dumps(
+            {"id": user_id, "name": f"User {user_id}", "active": True},
+            separators=(",", ":"),
+        )
+
+    # Add a prompt
+    @server.prompt
+    def welcome(name: str) -> str:
+        """Example greeting prompt."""
+        return f"Welcome to FastMCP, {name}!"
+
+    return server
+
+
+@pytest.fixture
+def tool_server():
+    """Fixture that creates a FastMCP server with comprehensive tool set for provider tests."""
+    import base64
+
+    from mcp_types import (
+        BlobResourceContents,
+        EmbeddedResource,
+        ImageContent,
+        TextContent,
+    )
+
+    from fastmcp import FastMCP
+    from fastmcp.utilities.types import Audio, File, Image
+
+    mcp = FastMCP()
+
+    @mcp.tool
+    def add(x: int, y: int) -> int:
+        return x + y
+
+    @mcp.tool
+    def list_tool() -> list[str | int]:
+        return ["x", 2]
+
+    @mcp.tool
+    def error_tool() -> None:
+        raise ValueError("Test error")
+
+    @mcp.tool
+    def image_tool(path: str) -> Image:
+        return Image(path)
+
+    @mcp.tool
+    def audio_tool(path: str) -> Audio:
+        return Audio(path)
+
+    @mcp.tool
+    def file_tool(path: str) -> File:
+        return File(path)
+
+    @mcp.tool
+    def mixed_content_tool() -> list[TextContent | ImageContent | EmbeddedResource]:
+        return [
+            TextContent(type="text", text="Hello"),
+            ImageContent(
+                type="image", data="abc", mime_type="application/octet-stream"
+            ),
+            EmbeddedResource(
+                type="resource",
+                resource=BlobResourceContents(
+                    blob=base64.b64encode(b"abc").decode(),
+                    mime_type="application/octet-stream",
+                    uri="file:///test.bin",
+                ),
+            ),
+        ]
+
+    @mcp.tool(output_schema=None)
+    def mixed_list_fn(image_path: str) -> list:
+        return [
+            "text message",
+            Image(image_path),
+            {"key": "value"},
+            TextContent(type="text", text="direct content"),
+        ]
+
+    @mcp.tool(output_schema=None)
+    def mixed_audio_list_fn(audio_path: str) -> list:
+        return [
+            "text message",
+            Audio(audio_path),
+            {"key": "value"},
+            TextContent(type="text", text="direct content"),
+        ]
+
+    @mcp.tool(output_schema=None)
+    def mixed_file_list_fn(file_path: str) -> list:
+        return [
+            "text message",
+            File(file_path),
+            {"key": "value"},
+            TextContent(type="text", text="direct content"),
+        ]
+
+    @mcp.tool
+    def file_text_tool() -> File:
+        return File(data=b"hello world", format="plain")
+
+    return mcp
+
+
+@pytest.fixture
+def tagged_resources_server():
+    """Fixture that creates a FastMCP server with tagged resources and templates."""
+    import json
+
+    from fastmcp import FastMCP
+
+    server = FastMCP("TaggedResourcesServer")
+
+    # Add a resource with tags
+    @server.resource(
+        uri="data://tagged", tags={"test", "metadata"}, description="A tagged resource"
+    )
+    async def get_tagged_data() -> str:
+        return json.dumps({"type": "tagged_data"}, separators=(",", ":"))
+
+    # Add a resource template with tags
+    @server.resource(
+        uri="template://{id}",
+        tags={"template", "parameterized"},
+        description="A tagged template",
+    )
+    async def get_template_data(id: str) -> str:
+        return json.dumps({"id": id, "type": "template_data"}, separators=(",", ":"))
+
+    return server
diff --git a/tests/contrib/__init__.py b/tests/contrib/__init__.py
new file mode 100644
index 0000000..32113d1
--- /dev/null
+++ b/tests/contrib/__init__.py
@@ -0,0 +1 @@
+# This file makes Python treat the directory as a package.
diff --git a/tests/contrib/test_bulk_tool_caller.py b/tests/contrib/test_bulk_tool_caller.py
new file mode 100644
index 0000000..97ee6a1
--- /dev/null
+++ b/tests/contrib/test_bulk_tool_caller.py
@@ -0,0 +1,349 @@
+from typing import Any
+
+import pytest
+from inline_snapshot import snapshot
+from mcp_types import TextContent
+
+from fastmcp import FastMCP
+from fastmcp.contrib.bulk_tool_caller.bulk_tool_caller import (
+    BulkToolCaller,
+    CallToolRequest,
+    CallToolRequestResult,
+)
+from fastmcp.tools.base import Tool
+
+
+class ToolException(Exception):
+    """Custom exception for tool errors."""
+
+    pass
+
+
+async def error_tool(arg1: str) -> dict[str, Any]:
+    """A tool that raises an error for testing purposes."""
+    raise ToolException(f"Error in tool with arg1: {arg1}")
+
+
+def error_tool_result_factory(arg1: str) -> CallToolRequestResult:
+    """Generates the expected error result for error_tool."""
+    # Mimic the error message format generated by BulkToolCaller when catching ToolException
+    formatted_error_text = (
+        "Error calling tool 'error_tool': Error in tool with arg1: " + arg1
+    )
+    return CallToolRequestResult(
+        is_error=True,
+        content=[TextContent(text=formatted_error_text, type="text")],
+        tool="error_tool",
+        arguments={"arg1": arg1},
+    )
+
+
+async def echo_tool(arg1: str) -> str:
+    """A simple tool that echoes arguments or raises an error."""
+    return arg1
+
+
+def echo_tool_result_factory(arg1: str) -> CallToolRequestResult:
+    """A tool that returns a result based on the input arguments."""
+    return CallToolRequestResult(
+        is_error=False,
+        content=[TextContent(text=f"{arg1}", type="text")],
+        tool="echo_tool",
+        arguments={"arg1": arg1},
+    )
+
+
+async def no_return_tool(arg1: str) -> None:
+    """A simple tool that echoes arguments or raises an error."""
+
+
+def no_return_tool_result_factory(arg1: str) -> CallToolRequestResult:
+    """A tool that returns a result based on the input arguments."""
+    return CallToolRequestResult(
+        is_error=False,
+        content=[],
+        tool="no_return_tool",
+        arguments={"arg1": arg1},
+    )
+
+
+@pytest.fixture
+def live_server_with_tool() -> FastMCP:
+    """Fixture to create a FastMCP server instance with the echo_tool registered."""
+    server = FastMCP()
+    server.add_tool(Tool.from_function(echo_tool))
+    server.add_tool(Tool.from_function(error_tool))
+    server.add_tool(Tool.from_function(no_return_tool))
+    return server
+
+
+@pytest.fixture
+def bulk_caller_live(live_server_with_tool: FastMCP) -> BulkToolCaller:
+    """Fixture to create a BulkToolCaller instance connected to the live server."""
+    bulk_tool_caller = BulkToolCaller()
+    bulk_tool_caller.register_tools(live_server_with_tool)
+    return bulk_tool_caller
+
+
+ECHO_TOOL_NAME = "echo_tool"
+ERROR_TOOL_NAME = "error_tool"
+NO_RETURN_TOOL_NAME = "no_return_tool"
+
+
+async def test_call_tool_bulk_single_success(bulk_caller_live: BulkToolCaller):
+    """Test single successful call via call_tool_bulk using echo_tool."""
+
+    results = await bulk_caller_live.call_tool_bulk(
+        ECHO_TOOL_NAME, [{"arg1": "value1"}]
+    )
+
+    assert results == snapshot(
+        [
+            CallToolRequestResult(
+                content=[TextContent(type="text", text="value1")],
+                tool="echo_tool",
+                arguments={"arg1": "value1"},
+            )
+        ]
+    )
+
+
+async def test_call_tool_bulk_multiple_success(bulk_caller_live: BulkToolCaller):
+    """Test multiple successful calls via call_tool_bulk using echo_tool."""
+    results = await bulk_caller_live.call_tool_bulk(
+        ECHO_TOOL_NAME, [{"arg1": "value1"}, {"arg1": "value2"}]
+    )
+
+    assert results == snapshot(
+        [
+            CallToolRequestResult(
+                content=[TextContent(type="text", text="value1")],
+                tool="echo_tool",
+                arguments={"arg1": "value1"},
+            ),
+            CallToolRequestResult(
+                content=[TextContent(type="text", text="value2")],
+                tool="echo_tool",
+                arguments={"arg1": "value2"},
+            ),
+        ]
+    )
+
+
+async def test_call_tool_bulk_error_stops(bulk_caller_live: BulkToolCaller):
+    """Test call_tool_bulk stops on first error using error_tool."""
+    results = await bulk_caller_live.call_tool_bulk(
+        ERROR_TOOL_NAME,
+        [{"arg1": "error_value"}, {"arg1": "value2"}],
+        continue_on_error=False,
+    )
+
+    assert results == snapshot(
+        [
+            CallToolRequestResult(
+                content=[
+                    TextContent(
+                        type="text",
+                        text="Error calling tool 'error_tool': Error in tool with arg1: error_value",
+                    )
+                ],
+                is_error=True,
+                tool="error_tool",
+                arguments={"arg1": "error_value"},
+            )
+        ]
+    )
+
+
+async def test_call_tool_bulk_error_continues(bulk_caller_live: BulkToolCaller):
+    """Test call_tool_bulk continues on error using error_tool and echo_tool."""
+
+    tool_calls = [
+        CallToolRequest(tool=ERROR_TOOL_NAME, arguments={"arg1": "error_value"}),
+        CallToolRequest(tool=ECHO_TOOL_NAME, arguments={"arg1": "success_value"}),
+    ]
+
+    results = await bulk_caller_live.call_tools_bulk(tool_calls, continue_on_error=True)
+
+    assert results == snapshot(
+        [
+            CallToolRequestResult(
+                content=[
+                    TextContent(
+                        type="text",
+                        text="Error calling tool 'error_tool': Error in tool with arg1: error_value",
+                    )
+                ],
+                is_error=True,
+                tool="error_tool",
+                arguments={"arg1": "error_value"},
+            ),
+            CallToolRequestResult(
+                content=[TextContent(type="text", text="success_value")],
+                tool="echo_tool",
+                arguments={"arg1": "success_value"},
+            ),
+        ]
+    )
+
+
+async def test_call_tools_bulk_single_success(bulk_caller_live: BulkToolCaller):
+    """Test single successful call via call_tools_bulk using echo_tool."""
+    tool_calls = [CallToolRequest(tool=ECHO_TOOL_NAME, arguments={"arg1": "value1"})]
+
+    results = await bulk_caller_live.call_tools_bulk(tool_calls)
+
+    assert results == snapshot(
+        [
+            CallToolRequestResult(
+                content=[TextContent(type="text", text="value1")],
+                tool="echo_tool",
+                arguments={"arg1": "value1"},
+            )
+        ]
+    )
+
+
+async def test_call_tools_bulk_multiple_success(bulk_caller_live: BulkToolCaller):
+    """Test multiple successful calls via call_tools_bulk with different tools."""
+    tool_calls = [
+        CallToolRequest(tool=ECHO_TOOL_NAME, arguments={"arg1": "echo_value"}),
+        CallToolRequest(
+            tool=NO_RETURN_TOOL_NAME, arguments={"arg1": "no_return_value"}
+        ),
+    ]
+
+    results = await bulk_caller_live.call_tools_bulk(tool_calls)
+
+    assert results == snapshot(
+        [
+            CallToolRequestResult(
+                content=[TextContent(type="text", text="echo_value")],
+                tool="echo_tool",
+                arguments={"arg1": "echo_value"},
+            ),
+            CallToolRequestResult(
+                content=[], tool="no_return_tool", arguments={"arg1": "no_return_value"}
+            ),
+        ]
+    )
+
+
+async def test_call_tools_bulk_error_stops(bulk_caller_live: BulkToolCaller):
+    """Test call_tools_bulk stops on first error using error_tool."""
+    tool_calls = [
+        CallToolRequest(tool=ERROR_TOOL_NAME, arguments={"arg1": "error_value"}),
+        CallToolRequest(tool=ECHO_TOOL_NAME, arguments={"arg1": "skipped_value"}),
+    ]
+
+    results = await bulk_caller_live.call_tools_bulk(
+        tool_calls, continue_on_error=False
+    )
+
+    assert results == snapshot(
+        [
+            CallToolRequestResult(
+                content=[
+                    TextContent(
+                        type="text",
+                        text="Error calling tool 'error_tool': Error in tool with arg1: error_value",
+                    )
+                ],
+                is_error=True,
+                tool="error_tool",
+                arguments={"arg1": "error_value"},
+            )
+        ]
+    )
+
+
+async def test_call_tools_bulk_error_continues(bulk_caller_live: BulkToolCaller):
+    """Test call_tools_bulk continues on error using error_tool and echo_tool."""
+    tool_calls = [
+        CallToolRequest(tool=ERROR_TOOL_NAME, arguments={"arg1": "error_value"}),
+        CallToolRequest(tool=ECHO_TOOL_NAME, arguments={"arg1": "success_value"}),
+    ]
+
+    results = await bulk_caller_live.call_tools_bulk(tool_calls, continue_on_error=True)
+
+    assert results == snapshot(
+        [
+            CallToolRequestResult(
+                content=[
+                    TextContent(
+                        type="text",
+                        text="Error calling tool 'error_tool': Error in tool with arg1: error_value",
+                    )
+                ],
+                is_error=True,
+                tool="error_tool",
+                arguments={"arg1": "error_value"},
+            ),
+            CallToolRequestResult(
+                content=[TextContent(type="text", text="success_value")],
+                tool="echo_tool",
+                arguments={"arg1": "success_value"},
+            ),
+        ]
+    )
+
+
+async def test_call_tools_bulk_blocks_self_invocation(bulk_caller_live: BulkToolCaller):
+    """Test call_tools_bulk blocks recursive calls to bulk tools."""
+    tool_calls = [
+        CallToolRequest(tool="call_tools_bulk", arguments={"tool_calls": []}),
+        CallToolRequest(tool=ECHO_TOOL_NAME, arguments={"arg1": "success_value"}),
+    ]
+
+    results = await bulk_caller_live.call_tools_bulk(tool_calls, continue_on_error=True)
+
+    assert results == snapshot(
+        [
+            CallToolRequestResult(
+                content=[
+                    TextContent(
+                        type="text",
+                        text=(
+                            "BulkToolCaller cannot call itself. "
+                            "The tools 'call_tools_bulk' and 'call_tool_bulk' are disallowed."
+                        ),
+                    )
+                ],
+                is_error=True,
+                tool="call_tools_bulk",
+                arguments={"tool_calls": []},
+            ),
+            CallToolRequestResult(
+                content=[TextContent(type="text", text="success_value")],
+                tool="echo_tool",
+                arguments={"arg1": "success_value"},
+            ),
+        ]
+    )
+
+
+async def test_call_tool_bulk_blocks_self_invocation(bulk_caller_live: BulkToolCaller):
+    """Test call_tool_bulk blocks recursive calls to bulk tools."""
+
+    results = await bulk_caller_live.call_tool_bulk(
+        "call_tool_bulk", [{"arg1": "value1"}], continue_on_error=False
+    )
+
+    assert results == snapshot(
+        [
+            CallToolRequestResult(
+                content=[
+                    TextContent(
+                        type="text",
+                        text=(
+                            "BulkToolCaller cannot call itself. "
+                            "The tools 'call_tools_bulk' and 'call_tool_bulk' are disallowed."
+                        ),
+                    )
+                ],
+                is_error=True,
+                tool="call_tool_bulk",
+                arguments={"arg1": "value1"},
+            )
+        ]
+    )
diff --git a/tests/contrib/test_component_manager.py b/tests/contrib/test_component_manager.py
new file mode 100644
index 0000000..8acae9a
--- /dev/null
+++ b/tests/contrib/test_component_manager.py
@@ -0,0 +1,602 @@
+import pytest
+from starlette import status
+from starlette.testclient import TestClient
+
+from fastmcp import FastMCP
+from fastmcp.contrib.component_manager import set_up_component_manager
+from fastmcp.server.auth.providers.jwt import JWTVerifier, RSAKeyPair
+
+
+class TestComponentManagementRoutes:
+    """Test the component management routes for tools, resources, and prompts."""
+
+    @pytest.fixture
+    def mcp(self):
+        """Create a FastMCP server with test tools, resources, and prompts."""
+        mcp = FastMCP("TestServer")
+        set_up_component_manager(server=mcp)
+
+        # Add a test tool
+        @mcp.tool
+        def test_tool() -> str:
+            """Test tool for tool management routes."""
+            return "test_tool_result"
+
+        # Add a test resource
+        @mcp.resource("data://test_resource")
+        def test_resource() -> str:
+            """Test resource for tool management routes."""
+            return "test_resource_result"
+
+        # Add a test resource
+        @mcp.resource("data://test_resource/{id}")
+        def test_template(id: str) -> dict:
+            """Test template for tool management routes."""
+            return {"id": id, "value": "data"}
+
+        # Add a test prompt
+        @mcp.prompt
+        def test_prompt() -> str:
+            """Test prompt for tool management routes."""
+            return "test_prompt_result"
+
+        return mcp
+
+    @pytest.fixture
+    def client(self, mcp):
+        """Create a test client for the FastMCP server."""
+        return TestClient(mcp.http_app())
+
+    async def test_enable_tool_route(self, client, mcp):
+        """Test enabling a tool via the HTTP route."""
+        # First disable the tool
+        mcp.disable(names={"test_tool"}, components={"tool"})
+        tools = await mcp.list_tools()
+        assert not any(t.name == "test_tool" for t in tools)
+
+        # Enable the tool via the HTTP route
+        response = client.post("/tools/test_tool/enable")
+
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json() == {"message": "Enabled tool: test_tool"}
+
+        # Verify the tool is enabled
+        tools = await mcp.list_tools()
+        assert any(t.name == "test_tool" for t in tools)
+
+    async def test_disable_tool_route(self, client, mcp):
+        """Test disabling a tool via the HTTP route."""
+        # First ensure the tool is enabled
+        tools = await mcp.list_tools()
+        assert any(t.name == "test_tool" for t in tools)
+
+        # Disable the tool via the HTTP route
+        response = client.post("/tools/test_tool/disable")
+
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json() == {"message": "Disabled tool: test_tool"}
+
+        # Verify the tool is disabled
+        tools = await mcp.list_tools()
+        assert not any(t.name == "test_tool" for t in tools)
+
+    async def test_enable_resource_route(self, client, mcp):
+        """Test enabling a resource via the HTTP route."""
+        # First disable the resource (can use URI as name for resources)
+        mcp.disable(names={"data://test_resource"}, components={"resource"})
+        resources = await mcp.list_resources()
+        assert not any(str(r.uri) == "data://test_resource" for r in resources)
+
+        # Enable the resource via the HTTP route
+        response = client.post("/resources/data://test_resource/enable")
+
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json() == {"message": "Enabled resource: data://test_resource"}
+
+        # Verify the resource is enabled
+        resources = await mcp.list_resources()
+        assert any(str(r.uri) == "data://test_resource" for r in resources)
+
+    async def test_disable_resource_route(self, client, mcp):
+        """Test disabling a resource via the HTTP route."""
+        # First ensure the resource is enabled
+        resources = await mcp.list_resources()
+        assert any(str(r.uri) == "data://test_resource" for r in resources)
+
+        # Disable the resource via the HTTP route
+        response = client.post("/resources/data://test_resource/disable")
+
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json() == {"message": "Disabled resource: data://test_resource"}
+
+        # Verify the resource is disabled
+        resources = await mcp.list_resources()
+        assert not any(str(r.uri) == "data://test_resource" for r in resources)
+
+    async def test_enable_template_route(self, client, mcp):
+        """Test enabling a resource template via the HTTP route."""
+        key = "data://test_resource/{id}"
+        mcp.disable(names={"data://test_resource/{id}"}, components={"template"})
+        templates = await mcp.list_resource_templates()
+        assert not any(t.uri_template == key for t in templates)
+        response = client.post("/resources/data://test_resource/{id}/enable")
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json() == {
+            "message": "Enabled resource: data://test_resource/{id}"
+        }
+        templates = await mcp.list_resource_templates()
+        assert any(t.uri_template == key for t in templates)
+
+    async def test_disable_template_route(self, client, mcp):
+        """Test disabling a resource template via the HTTP route."""
+        key = "data://test_resource/{id}"
+        templates = await mcp.list_resource_templates()
+        assert any(t.uri_template == key for t in templates)
+        response = client.post("/resources/data://test_resource/{id}/disable")
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json() == {
+            "message": "Disabled resource: data://test_resource/{id}"
+        }
+        templates = await mcp.list_resource_templates()
+        assert not any(t.uri_template == key for t in templates)
+
+    async def test_enable_prompt_route(self, client, mcp):
+        """Test enabling a prompt via the HTTP route."""
+        # First disable the prompt
+        mcp.disable(names={"test_prompt"}, components={"prompt"})
+        prompts = await mcp.list_prompts()
+        assert not any(p.name == "test_prompt" for p in prompts)
+
+        # Enable the prompt via the HTTP route
+        response = client.post("/prompts/test_prompt/enable")
+
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json() == {"message": "Enabled prompt: test_prompt"}
+
+        # Verify the prompt is enabled
+        prompts = await mcp.list_prompts()
+        assert any(p.name == "test_prompt" for p in prompts)
+
+    async def test_disable_prompt_route(self, client, mcp):
+        """Test disabling a prompt via the HTTP route."""
+        # First ensure the prompt is enabled
+        prompts = await mcp.list_prompts()
+        assert any(p.name == "test_prompt" for p in prompts)
+
+        # Disable the prompt via the HTTP route
+        response = client.post("/prompts/test_prompt/disable")
+
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json() == {"message": "Disabled prompt: test_prompt"}
+
+        # Verify the prompt is disabled
+        prompts = await mcp.list_prompts()
+        assert not any(p.name == "test_prompt" for p in prompts)
+
+
+class TestAuthComponentManagementRoutes:
+    """Test the component management routes with authentication for tools, resources, and prompts."""
+
+    def setup_method(self):
+        """Set up test fixtures."""
+        # Generate a key pair and create an auth provider
+        key_pair = RSAKeyPair.generate()
+        self.auth = JWTVerifier(
+            public_key=key_pair.public_key,
+            issuer="https://dev.example.com",
+            audience="my-dev-server",
+        )
+        self.mcp = FastMCP("TestServerWithAuth", auth=self.auth)
+        set_up_component_manager(
+            server=self.mcp, required_scopes=["tool:write", "tool:read"]
+        )
+        self.token = key_pair.create_token(
+            subject="dev-user",
+            issuer="https://dev.example.com",
+            audience="my-dev-server",
+            scopes=["tool:write", "tool:read"],
+        )
+        self.token_without_scopes = key_pair.create_token(
+            subject="dev-user",
+            issuer="https://dev.example.com",
+            audience="my-dev-server",
+            scopes=["tool:read"],
+        )
+
+        # Add test components
+        @self.mcp.tool
+        def test_tool() -> str:
+            """Test tool for auth testing."""
+            return "test_tool_result"
+
+        @self.mcp.resource("data://test_resource")
+        def test_resource() -> str:
+            """Test resource for auth testing."""
+            return "test_resource_result"
+
+        @self.mcp.prompt
+        def test_prompt() -> str:
+            """Test prompt for auth testing."""
+            return "test_prompt_result"
+
+        # Create test client
+        self.client = TestClient(self.mcp.http_app())
+
+    async def test_unauthorized_enable_tool(self):
+        """Test that unauthenticated requests to enable a tool are rejected."""
+        self.mcp.disable(names={"test_tool"}, components={"tool"})
+        tools = await self.mcp.list_tools()
+        assert not any(t.name == "test_tool" for t in tools)
+
+        response = self.client.post("/tools/test_tool/enable")
+        assert response.status_code == 401
+        tools = await self.mcp.list_tools()
+        assert not any(t.name == "test_tool" for t in tools)
+
+    async def test_authorized_enable_tool(self):
+        """Test that authenticated requests to enable a tool are allowed."""
+        self.mcp.disable(names={"test_tool"}, components={"tool"})
+        tools = await self.mcp.list_tools()
+        assert not any(t.name == "test_tool" for t in tools)
+
+        response = self.client.post(
+            "/tools/test_tool/enable", headers={"Authorization": "Bearer " + self.token}
+        )
+        assert response.status_code == 200
+        assert response.json() == {"message": "Enabled tool: test_tool"}
+        tools = await self.mcp.list_tools()
+        assert any(t.name == "test_tool" for t in tools)
+
+    async def test_unauthorized_disable_tool(self):
+        """Test that unauthenticated requests to disable a tool are rejected."""
+        tools = await self.mcp.list_tools()
+        assert any(t.name == "test_tool" for t in tools)
+
+        response = self.client.post("/tools/test_tool/disable")
+        assert response.status_code == 401
+        tools = await self.mcp.list_tools()
+        assert any(t.name == "test_tool" for t in tools)
+
+    async def test_authorized_disable_tool(self):
+        """Test that authenticated requests to disable a tool are allowed."""
+        tools = await self.mcp.list_tools()
+        assert any(t.name == "test_tool" for t in tools)
+
+        response = self.client.post(
+            "/tools/test_tool/disable",
+            headers={"Authorization": "Bearer " + self.token},
+        )
+        assert response.status_code == 200
+        assert response.json() == {"message": "Disabled tool: test_tool"}
+        tools = await self.mcp.list_tools()
+        assert not any(t.name == "test_tool" for t in tools)
+
+    async def test_forbidden_enable_tool(self):
+        """Test that requests with insufficient scopes are rejected."""
+        self.mcp.disable(names={"test_tool"}, components={"tool"})
+        tools = await self.mcp.list_tools()
+        assert not any(t.name == "test_tool" for t in tools)
+
+        response = self.client.post(
+            "/tools/test_tool/enable",
+            headers={"Authorization": "Bearer " + self.token_without_scopes},
+        )
+        assert response.status_code == 403
+        tools = await self.mcp.list_tools()
+        assert not any(t.name == "test_tool" for t in tools)
+
+    async def test_authorized_enable_resource(self):
+        """Test that authenticated requests to enable a resource are allowed."""
+        self.mcp.disable(names={"data://test_resource"}, components={"resource"})
+        resources = await self.mcp.list_resources()
+        assert not any(str(r.uri) == "data://test_resource" for r in resources)
+
+        response = self.client.post(
+            "/resources/data://test_resource/enable",
+            headers={"Authorization": "Bearer " + self.token},
+        )
+        assert response.status_code == 200
+        assert response.json() == {"message": "Enabled resource: data://test_resource"}
+        resources = await self.mcp.list_resources()
+        assert any(str(r.uri) == "data://test_resource" for r in resources)
+
+    async def test_unauthorized_disable_resource(self):
+        """Test that unauthenticated requests to disable a resource are rejected."""
+        resources = await self.mcp.list_resources()
+        assert any(str(r.uri) == "data://test_resource" for r in resources)
+
+        response = self.client.post("/resources/data://test_resource/disable")
+        assert response.status_code == 401
+        resources = await self.mcp.list_resources()
+        assert any(str(r.uri) == "data://test_resource" for r in resources)
+
+    async def test_forbidden_enable_resource(self):
+        """Test that requests with insufficient scopes are rejected."""
+        self.mcp.disable(names={"data://test_resource"}, components={"resource"})
+        resources = await self.mcp.list_resources()
+        assert not any(str(r.uri) == "data://test_resource" for r in resources)
+
+        response = self.client.post(
+            "/resources/data://test_resource/disable",
+            headers={"Authorization": "Bearer " + self.token_without_scopes},
+        )
+        assert response.status_code == 403
+        resources = await self.mcp.list_resources()
+        assert not any(str(r.uri) == "data://test_resource" for r in resources)
+
+    async def test_authorized_disable_resource(self):
+        """Test that authenticated requests to disable a resource are allowed."""
+        resources = await self.mcp.list_resources()
+        assert any(str(r.uri) == "data://test_resource" for r in resources)
+
+        response = self.client.post(
+            "/resources/data://test_resource/disable",
+            headers={"Authorization": "Bearer " + self.token},
+        )
+        assert response.status_code == 200
+        assert response.json() == {"message": "Disabled resource: data://test_resource"}
+        resources = await self.mcp.list_resources()
+        assert not any(str(r.uri) == "data://test_resource" for r in resources)
+
+    async def test_unauthorized_enable_prompt(self):
+        """Test that unauthenticated requests to enable a prompt are rejected."""
+        self.mcp.disable(names={"test_prompt"}, components={"prompt"})
+        prompts = await self.mcp.list_prompts()
+        assert not any(p.name == "test_prompt" for p in prompts)
+
+        response = self.client.post("/prompts/test_prompt/enable")
+        assert response.status_code == 401
+        prompts = await self.mcp.list_prompts()
+        assert not any(p.name == "test_prompt" for p in prompts)
+
+    async def test_authorized_enable_prompt(self):
+        """Test that authenticated requests to enable a prompt are allowed."""
+        self.mcp.disable(names={"test_prompt"}, components={"prompt"})
+        prompts = await self.mcp.list_prompts()
+        assert not any(p.name == "test_prompt" for p in prompts)
+
+        response = self.client.post(
+            "/prompts/test_prompt/enable",
+            headers={"Authorization": "Bearer " + self.token},
+        )
+        assert response.status_code == 200
+        assert response.json() == {"message": "Enabled prompt: test_prompt"}
+        prompts = await self.mcp.list_prompts()
+        assert any(p.name == "test_prompt" for p in prompts)
+
+    async def test_unauthorized_disable_prompt(self):
+        """Test that unauthenticated requests to disable a prompt are rejected."""
+        prompts = await self.mcp.list_prompts()
+        assert any(p.name == "test_prompt" for p in prompts)
+
+        response = self.client.post("/prompts/test_prompt/disable")
+        assert response.status_code == 401
+        prompts = await self.mcp.list_prompts()
+        assert any(p.name == "test_prompt" for p in prompts)
+
+    async def test_forbidden_disable_prompt(self):
+        """Test that requests with insufficient scopes are rejected."""
+        prompts = await self.mcp.list_prompts()
+        assert any(p.name == "test_prompt" for p in prompts)
+
+        response = self.client.post(
+            "/prompts/test_prompt/disable",
+            headers={"Authorization": "Bearer " + self.token_without_scopes},
+        )
+        assert response.status_code == 403
+        prompts = await self.mcp.list_prompts()
+        assert any(p.name == "test_prompt" for p in prompts)
+
+    async def test_authorized_disable_prompt(self):
+        """Test that authenticated requests to disable a prompt are allowed."""
+        prompts = await self.mcp.list_prompts()
+        assert any(p.name == "test_prompt" for p in prompts)
+
+        response = self.client.post(
+            "/prompts/test_prompt/disable",
+            headers={"Authorization": "Bearer " + self.token},
+        )
+        assert response.status_code == 200
+        assert response.json() == {"message": "Disabled prompt: test_prompt"}
+        prompts = await self.mcp.list_prompts()
+        assert not any(p.name == "test_prompt" for p in prompts)
+
+
+class TestComponentManagerWithPath:
+    """Test component manager routes when mounted at a custom path."""
+
+    @pytest.fixture
+    def mcp_with_path(self):
+        mcp = FastMCP("TestServerWithPath")
+        set_up_component_manager(server=mcp, path="/test")
+
+        @mcp.tool
+        def test_tool() -> str:
+            return "test_tool_result"
+
+        @mcp.resource("data://test_resource")
+        def test_resource() -> str:
+            return "test_resource_result"
+
+        @mcp.prompt
+        def test_prompt() -> str:
+            return "test_prompt_result"
+
+        return mcp
+
+    @pytest.fixture
+    def client_with_path(self, mcp_with_path):
+        return TestClient(mcp_with_path.http_app())
+
+    async def test_enable_tool_route_with_path(self, client_with_path, mcp_with_path):
+        mcp_with_path.disable(names={"test_tool"}, components={"tool"})
+        tools = await mcp_with_path.list_tools()
+        assert not any(t.name == "test_tool" for t in tools)
+        response = client_with_path.post("/test/tools/test_tool/enable")
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json() == {"message": "Enabled tool: test_tool"}
+        tools = await mcp_with_path.list_tools()
+        assert any(t.name == "test_tool" for t in tools)
+
+    async def test_disable_resource_route_with_path(
+        self, client_with_path, mcp_with_path
+    ):
+        resources = await mcp_with_path.list_resources()
+        assert any(str(r.uri) == "data://test_resource" for r in resources)
+        response = client_with_path.post("/test/resources/data://test_resource/disable")
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json() == {"message": "Disabled resource: data://test_resource"}
+        resources = await mcp_with_path.list_resources()
+        assert not any(str(r.uri) == "data://test_resource" for r in resources)
+
+    async def test_enable_prompt_route_with_path(self, client_with_path, mcp_with_path):
+        mcp_with_path.disable(names={"test_prompt"}, components={"prompt"})
+        prompts = await mcp_with_path.list_prompts()
+        assert not any(p.name == "test_prompt" for p in prompts)
+        response = client_with_path.post("/test/prompts/test_prompt/enable")
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json() == {"message": "Enabled prompt: test_prompt"}
+        prompts = await mcp_with_path.list_prompts()
+        assert any(p.name == "test_prompt" for p in prompts)
+
+
+class TestComponentManagerWithPathAuth:
+    """Test component manager routes with auth when mounted at a custom path."""
+
+    def setup_method(self):
+        # Generate a key pair and create an auth provider
+        key_pair = RSAKeyPair.generate()
+        self.auth = JWTVerifier(
+            public_key=key_pair.public_key,
+            issuer="https://dev.example.com",
+            audience="my-dev-server",
+        )
+        self.mcp = FastMCP("TestServerWithPathAuth", auth=self.auth)
+        set_up_component_manager(
+            server=self.mcp, path="/test", required_scopes=["tool:write", "tool:read"]
+        )
+        self.token = key_pair.create_token(
+            subject="dev-user",
+            issuer="https://dev.example.com",
+            audience="my-dev-server",
+            scopes=["tool:read", "tool:write"],
+        )
+        self.token_without_scopes = key_pair.create_token(
+            subject="dev-user",
+            issuer="https://dev.example.com",
+            audience="my-dev-server",
+            scopes=[],
+        )
+
+        @self.mcp.tool
+        def test_tool() -> str:
+            return "test_tool_result"
+
+        @self.mcp.resource("data://test_resource")
+        def test_resource() -> str:
+            return "test_resource_result"
+
+        @self.mcp.prompt
+        def test_prompt() -> str:
+            return "test_prompt_result"
+
+        self.client = TestClient(self.mcp.http_app())
+
+    async def test_unauthorized_enable_tool(self):
+        self.mcp.disable(names={"test_tool"}, components={"tool"})
+        tools = await self.mcp.list_tools()
+        assert not any(t.name == "test_tool" for t in tools)
+        response = self.client.post("/test/tools/test_tool/enable")
+        assert response.status_code == 401
+        tools = await self.mcp.list_tools()
+        assert not any(t.name == "test_tool" for t in tools)
+
+    async def test_forbidden_enable_tool(self):
+        self.mcp.disable(names={"test_tool"}, components={"tool"})
+        tools = await self.mcp.list_tools()
+        assert not any(t.name == "test_tool" for t in tools)
+        response = self.client.post(
+            "/test/tools/test_tool/enable",
+            headers={"Authorization": "Bearer " + self.token_without_scopes},
+        )
+        assert response.status_code == 403
+        tools = await self.mcp.list_tools()
+        assert not any(t.name == "test_tool" for t in tools)
+
+    async def test_authorized_enable_tool(self):
+        self.mcp.disable(names={"test_tool"}, components={"tool"})
+        tools = await self.mcp.list_tools()
+        assert not any(t.name == "test_tool" for t in tools)
+        response = self.client.post(
+            "/test/tools/test_tool/enable",
+            headers={"Authorization": "Bearer " + self.token},
+        )
+        assert response.status_code == 200
+        assert response.json() == {"message": "Enabled tool: test_tool"}
+        tools = await self.mcp.list_tools()
+        assert any(t.name == "test_tool" for t in tools)
+
+    async def test_unauthorized_disable_resource(self):
+        resources = await self.mcp.list_resources()
+        assert any(str(r.uri) == "data://test_resource" for r in resources)
+        response = self.client.post("/test/resources/data://test_resource/disable")
+        assert response.status_code == 401
+        resources = await self.mcp.list_resources()
+        assert any(str(r.uri) == "data://test_resource" for r in resources)
+
+    async def test_forbidden_disable_resource(self):
+        resources = await self.mcp.list_resources()
+        assert any(str(r.uri) == "data://test_resource" for r in resources)
+        response = self.client.post(
+            "/test/resources/data://test_resource/disable",
+            headers={"Authorization": "Bearer " + self.token_without_scopes},
+        )
+        assert response.status_code == 403
+        resources = await self.mcp.list_resources()
+        assert any(str(r.uri) == "data://test_resource" for r in resources)
+
+    async def test_authorized_disable_resource(self):
+        resources = await self.mcp.list_resources()
+        assert any(str(r.uri) == "data://test_resource" for r in resources)
+        response = self.client.post(
+            "/test/resources/data://test_resource/disable",
+            headers={"Authorization": "Bearer " + self.token},
+        )
+        assert response.status_code == 200
+        assert response.json() == {"message": "Disabled resource: data://test_resource"}
+        resources = await self.mcp.list_resources()
+        assert not any(str(r.uri) == "data://test_resource" for r in resources)
+
+    async def test_unauthorized_enable_prompt(self):
+        self.mcp.disable(names={"test_prompt"}, components={"prompt"})
+        prompts = await self.mcp.list_prompts()
+        assert not any(p.name == "test_prompt" for p in prompts)
+        response = self.client.post("/test/prompts/test_prompt/enable")
+        assert response.status_code == 401
+        prompts = await self.mcp.list_prompts()
+        assert not any(p.name == "test_prompt" for p in prompts)
+
+    async def test_forbidden_enable_prompt(self):
+        self.mcp.disable(names={"test_prompt"}, components={"prompt"})
+        prompts = await self.mcp.list_prompts()
+        assert not any(p.name == "test_prompt" for p in prompts)
+        response = self.client.post(
+            "/test/prompts/test_prompt/enable",
+            headers={"Authorization": "Bearer " + self.token_without_scopes},
+        )
+        assert response.status_code == 403
+        prompts = await self.mcp.list_prompts()
+        assert not any(p.name == "test_prompt" for p in prompts)
+
+    async def test_authorized_enable_prompt(self):
+        self.mcp.disable(names={"test_prompt"}, components={"prompt"})
+        prompts = await self.mcp.list_prompts()
+        assert not any(p.name == "test_prompt" for p in prompts)
+        response = self.client.post(
+            "/test/prompts/test_prompt/enable",
+            headers={"Authorization": "Bearer " + self.token},
+        )
+        assert response.status_code == 200
+        assert response.json() == {"message": "Enabled prompt: test_prompt"}
+        prompts = await self.mcp.list_prompts()
+        assert any(p.name == "test_prompt" for p in prompts)
diff --git a/tests/contrib/test_mcp_mixin.py b/tests/contrib/test_mcp_mixin.py
new file mode 100644
index 0000000..1bce287
--- /dev/null
+++ b/tests/contrib/test_mcp_mixin.py
@@ -0,0 +1,551 @@
+"""Tests for the MCPMixin class."""
+
+import inspect
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.contrib.mcp_mixin import (
+    MCPMixin,
+    mcp_prompt,
+    mcp_resource,
+    mcp_tool,
+)
+from fastmcp.contrib.mcp_mixin.mcp_mixin import (
+    _DEFAULT_SEPARATOR_PROMPT,
+    _DEFAULT_SEPARATOR_RESOURCE,
+    _DEFAULT_SEPARATOR_TOOL,
+    _PROMPT_VALID_KWARGS,
+    _RESOURCE_VALID_KWARGS,
+    _TOOL_VALID_KWARGS,
+)
+
+
+class TestMCPMixin:
+    """Test suite for MCPMixin functionality."""
+
+    def test_initialization(self):
+        """Test that a class inheriting MCPMixin can be initialized."""
+
+        class MyMixin(MCPMixin):
+            pass
+
+        instance = MyMixin()
+        assert instance is not None
+
+    # --- Tool Registration Tests ---
+    @pytest.mark.parametrize(
+        "prefix, separator, expected_key, unexpected_key",
+        [
+            (
+                None,
+                _DEFAULT_SEPARATOR_TOOL,
+                "sample_tool",
+                f"None{_DEFAULT_SEPARATOR_TOOL}sample_tool",
+            ),
+            (
+                "pref",
+                _DEFAULT_SEPARATOR_TOOL,
+                f"pref{_DEFAULT_SEPARATOR_TOOL}sample_tool",
+                "sample_tool",
+            ),
+            (
+                "pref",
+                "-",
+                "pref-sample_tool",
+                f"pref{_DEFAULT_SEPARATOR_TOOL}sample_tool",
+            ),
+        ],
+        ids=["No prefix", "Default separator", "Custom separator"],
+    )
+    async def test_tool_registration(
+        self, prefix, separator, expected_key, unexpected_key
+    ):
+        """Test tool registration with prefix and separator variations."""
+        mcp = FastMCP()
+
+        class MyToolMixin(MCPMixin):
+            @mcp_tool()
+            def sample_tool(self):
+                pass
+
+        instance = MyToolMixin()
+        instance.register_tools(mcp, prefix=prefix, separator=separator)
+
+        registered_tools = await mcp.list_tools()
+        assert any(t.name == expected_key for t in registered_tools)
+        assert not any(t.name == unexpected_key for t in registered_tools)
+
+    @pytest.mark.parametrize(
+        "prefix, separator, expected_uri_key, expected_name, unexpected_uri_key",
+        [
+            (
+                None,
+                _DEFAULT_SEPARATOR_RESOURCE,
+                "test://resource",
+                "sample_resource",
+                f"None{_DEFAULT_SEPARATOR_RESOURCE}test://resource",
+            ),
+            (
+                "pref",
+                _DEFAULT_SEPARATOR_RESOURCE,
+                f"pref{_DEFAULT_SEPARATOR_RESOURCE}test://resource",
+                f"pref{_DEFAULT_SEPARATOR_RESOURCE}sample_resource",
+                "test://resource",
+            ),
+            (
+                "pref",
+                "fff",
+                "prefffftest://resource",
+                "preffffsample_resource",
+                f"pref{_DEFAULT_SEPARATOR_RESOURCE}test://resource",
+            ),
+        ],
+        ids=["No prefix", "Default separator", "Custom separator"],
+    )
+    async def test_resource_registration(
+        self, prefix, separator, expected_uri_key, expected_name, unexpected_uri_key
+    ):
+        """Test resource registration with prefix and separator variations."""
+        mcp = FastMCP()
+
+        class MyResourceMixin(MCPMixin):
+            @mcp_resource(uri="test://resource")
+            def sample_resource(self):
+                pass
+
+        instance = MyResourceMixin()
+        instance.register_resources(mcp, prefix=prefix, separator=separator)
+
+        registered_resources = await mcp.list_resources()
+        assert any(str(r.uri) == expected_uri_key for r in registered_resources)
+        resource = next(
+            r for r in registered_resources if str(r.uri) == expected_uri_key
+        )
+        assert resource.name == expected_name
+        assert not any(str(r.uri) == unexpected_uri_key for r in registered_resources)
+
+    @pytest.mark.parametrize(
+        "prefix, separator, expected_name, unexpected_name",
+        [
+            (
+                None,
+                _DEFAULT_SEPARATOR_PROMPT,
+                "sample_prompt",
+                f"None{_DEFAULT_SEPARATOR_PROMPT}sample_prompt",
+            ),
+            (
+                "pref",
+                _DEFAULT_SEPARATOR_PROMPT,
+                f"pref{_DEFAULT_SEPARATOR_PROMPT}sample_prompt",
+                "sample_prompt",
+            ),
+            (
+                "pref",
+                ":",
+                "pref:sample_prompt",
+                f"pref{_DEFAULT_SEPARATOR_PROMPT}sample_prompt",
+            ),
+        ],
+        ids=["No prefix", "Default separator", "Custom separator"],
+    )
+    async def test_prompt_registration(
+        self, prefix, separator, expected_name, unexpected_name
+    ):
+        """Test prompt registration with prefix and separator variations."""
+        mcp = FastMCP()
+
+        class MyPromptMixin(MCPMixin):
+            @mcp_prompt()
+            def sample_prompt(self):
+                pass
+
+        instance = MyPromptMixin()
+        instance.register_prompts(mcp, prefix=prefix, separator=separator)
+
+        prompts = await mcp.list_prompts()
+        assert any(p.name == expected_name for p in prompts)
+        assert not any(p.name == unexpected_name for p in prompts)
+
+    async def test_register_all_no_prefix(self):
+        """Test register_all method registers all types without a prefix."""
+        mcp = FastMCP()
+
+        class MyFullMixin(MCPMixin):
+            @mcp_tool()
+            def tool_all(self):
+                pass
+
+            @mcp_resource(uri="res://all")
+            def resource_all(self):
+                pass
+
+            @mcp_prompt()
+            def prompt_all(self):
+                pass
+
+        instance = MyFullMixin()
+        instance.register_all(mcp)
+
+        tools = await mcp.list_tools()
+        resources = await mcp.list_resources()
+        prompts = await mcp.list_prompts()
+
+        assert any(t.name == "tool_all" for t in tools)
+        assert any(str(r.uri) == "res://all" for r in resources)
+        assert any(p.name == "prompt_all" for p in prompts)
+
+    async def test_register_all_with_prefix_default_separators(self):
+        """Test register_all method registers all types with a prefix and default separators."""
+        mcp = FastMCP()
+
+        class MyFullMixinPrefixed(MCPMixin):
+            @mcp_tool()
+            def tool_all_p(self):
+                pass
+
+            @mcp_resource(uri="res://all_p")
+            def resource_all_p(self):
+                pass
+
+            @mcp_prompt()
+            def prompt_all_p(self):
+                pass
+
+        instance = MyFullMixinPrefixed()
+        instance.register_all(mcp, prefix="all")
+
+        tools = await mcp.list_tools()
+        resources = await mcp.list_resources()
+        prompts = await mcp.list_prompts()
+
+        assert any(t.name == f"all{_DEFAULT_SEPARATOR_TOOL}tool_all_p" for t in tools)
+        assert any(
+            str(r.uri) == f"all{_DEFAULT_SEPARATOR_RESOURCE}res://all_p"
+            for r in resources
+        )
+        assert any(
+            p.name == f"all{_DEFAULT_SEPARATOR_PROMPT}prompt_all_p" for p in prompts
+        )
+
+    async def test_register_all_with_prefix_custom_separators(self):
+        """Test register_all method registers all types with a prefix and custom separators."""
+        mcp = FastMCP()
+
+        class MyFullMixinCustomSep(MCPMixin):
+            @mcp_tool()
+            def tool_cust(self):
+                pass
+
+            @mcp_resource(uri="res://cust")
+            def resource_cust(self):
+                pass
+
+            @mcp_prompt()
+            def prompt_cust(self):
+                pass
+
+        instance = MyFullMixinCustomSep()
+        instance.register_all(
+            mcp,
+            prefix="cust",
+            tool_separator="-",
+            resource_separator="::",
+            prompt_separator=".",
+        )
+
+        tools = await mcp.list_tools()
+        resources = await mcp.list_resources()
+        prompts = await mcp.list_prompts()
+
+        assert any(t.name == "cust-tool_cust" for t in tools)
+        assert any(str(r.uri) == "cust::res://cust" for r in resources)
+        assert any(p.name == "cust.prompt_cust" for p in prompts)
+
+        # Check default separators weren't used
+        assert not any(
+            t.name == f"cust{_DEFAULT_SEPARATOR_TOOL}tool_cust" for t in tools
+        )
+        assert not any(
+            str(r.uri) == f"cust{_DEFAULT_SEPARATOR_RESOURCE}res://cust"
+            for r in resources
+        )
+        assert not any(
+            p.name == f"cust{_DEFAULT_SEPARATOR_PROMPT}prompt_cust" for p in prompts
+        )
+
+    async def test_tool_with_title_and_meta(self):
+        """Test that title (via annotations) and meta arguments are properly passed through."""
+        from mcp_types import ToolAnnotations
+
+        mcp = FastMCP()
+
+        class MyToolWithMeta(MCPMixin):
+            @mcp_tool(
+                annotations=ToolAnnotations(title="My Tool Title"),
+                meta={"version": "1.0", "author": "test"},
+            )
+            def sample_tool(self):
+                pass
+
+        instance = MyToolWithMeta()
+        instance.register_tools(mcp)
+
+        registered_tools = await mcp.list_tools()
+        tool = next(t for t in registered_tools if t.name == "sample_tool")
+
+        assert tool.annotations is not None
+        assert tool.annotations.title == "My Tool Title"
+        assert tool.meta == {"version": "1.0", "author": "test"}
+
+    async def test_resource_with_meta(self):
+        """Test that meta argument is properly passed through for resources."""
+        mcp = FastMCP()
+
+        class MyResourceWithMeta(MCPMixin):
+            @mcp_resource(
+                uri="test://resource",
+                title="My Resource Title",
+                meta={"category": "data", "internal": True},
+            )
+            def sample_resource(self):
+                pass
+
+        instance = MyResourceWithMeta()
+        instance.register_resources(mcp)
+
+        registered_resources = await mcp.list_resources()
+        resource = next(
+            r for r in registered_resources if str(r.uri) == "test://resource"
+        )
+
+        assert resource.meta == {"category": "data", "internal": True}
+        assert resource.title == "My Resource Title"
+
+    async def test_prompt_with_title_and_meta(self):
+        """Test that title and meta arguments are properly passed through for prompts."""
+        mcp = FastMCP()
+
+        class MyPromptWithMeta(MCPMixin):
+            @mcp_prompt(
+                title="My Prompt Title",
+                meta={"priority": "high", "category": "analysis"},
+            )
+            def sample_prompt(self):
+                pass
+
+        instance = MyPromptWithMeta()
+        instance.register_prompts(mcp)
+
+        prompts = await mcp.list_prompts()
+        prompt = next(p for p in prompts if p.name == "sample_prompt")
+
+        assert prompt.title == "My Prompt Title"
+        assert prompt.meta == {"priority": "high", "category": "analysis"}
+
+
+class TestMCPMixinKwargsSync:
+    """Verify that the valid-kwarg sets stay in sync with from_function signatures."""
+
+    def test_tool_valid_kwargs_match_from_function(self):
+        from fastmcp.tools.base import Tool
+
+        expected = frozenset(
+            p for p in inspect.signature(Tool.from_function).parameters if p != "fn"
+        )
+        assert _TOOL_VALID_KWARGS == expected
+
+    def test_resource_valid_kwargs_match_from_function(self):
+        from fastmcp.resources.base import Resource
+
+        expected = frozenset(
+            p
+            for p in inspect.signature(Resource.from_function).parameters
+            if p not in ("fn", "uri")
+        )
+        assert _RESOURCE_VALID_KWARGS == expected
+
+    def test_prompt_valid_kwargs_match_from_function(self):
+        from fastmcp.prompts.base import Prompt
+
+        expected = frozenset(
+            p for p in inspect.signature(Prompt.from_function).parameters if p != "fn"
+        )
+        assert _PROMPT_VALID_KWARGS == expected
+
+
+class TestMCPMixinValidation:
+    """Unknown kwargs raise TypeError at decoration time, not at registration."""
+
+    def test_mcp_tool_rejects_unknown_param(self):
+        with pytest.raises(TypeError, match="unexpected keyword argument"):
+
+            @mcp_tool(definitely_not_a_real_param="oops")
+            def my_tool(self):
+                pass
+
+    def test_mcp_resource_rejects_unknown_param(self):
+        with pytest.raises(TypeError, match="unexpected keyword argument"):
+
+            @mcp_resource(uri="test://x", definitely_not_a_real_param="oops")
+            def my_resource(self):
+                pass
+
+    def test_mcp_prompt_rejects_unknown_param(self):
+        with pytest.raises(TypeError, match="unexpected keyword argument"):
+
+            @mcp_prompt(definitely_not_a_real_param="oops")
+            def my_prompt(self):
+                pass
+
+    def test_error_raised_at_decoration_not_registration(self):
+        """The TypeError must surface when the decorator is applied, not later."""
+        with pytest.raises(TypeError):
+
+            class MyMixin(MCPMixin):
+                @mcp_tool(bad_kwarg=True)
+                def tool(self):
+                    pass
+
+
+class TestMCPMixinEnabled:
+    """enabled=False suppresses registration; enabled=True (default) registers normally."""
+
+    async def test_tool_enabled_false_skips_registration(self):
+        mcp = FastMCP()
+
+        class MyMixin(MCPMixin):
+            @mcp_tool(enabled=False)
+            def hidden_tool(self):
+                pass
+
+            @mcp_tool()
+            def visible_tool(self):
+                pass
+
+        MyMixin().register_tools(mcp)
+        tools = await mcp.list_tools()
+        names = {t.name for t in tools}
+        assert "visible_tool" in names
+        assert "hidden_tool" not in names
+
+    async def test_resource_enabled_false_skips_registration(self):
+        mcp = FastMCP()
+
+        class MyMixin(MCPMixin):
+            @mcp_resource(uri="test://hidden", enabled=False)
+            def hidden_resource(self):
+                pass
+
+            @mcp_resource(uri="test://visible")
+            def visible_resource(self):
+                pass
+
+        MyMixin().register_resources(mcp)
+        resources = await mcp.list_resources()
+        uris = {str(r.uri) for r in resources}
+        assert "test://visible" in uris
+        assert "test://hidden" not in uris
+
+    async def test_prompt_enabled_false_skips_registration(self):
+        mcp = FastMCP()
+
+        class MyMixin(MCPMixin):
+            @mcp_prompt(enabled=False)
+            def hidden_prompt(self):
+                pass
+
+            @mcp_prompt()
+            def visible_prompt(self):
+                pass
+
+        MyMixin().register_prompts(mcp)
+        prompts = await mcp.list_prompts()
+        names = {p.name for p in prompts}
+        assert "visible_prompt" in names
+        assert "hidden_prompt" not in names
+
+    async def test_tool_enabled_true_registers_normally(self):
+        mcp = FastMCP()
+
+        class MyMixin(MCPMixin):
+            @mcp_tool(enabled=True)
+            def my_tool(self):
+                pass
+
+        MyMixin().register_tools(mcp)
+        tools = await mcp.list_tools()
+        assert any(t.name == "my_tool" for t in tools)
+
+
+class TestMCPMixinNewParams:
+    """Parameters that were previously missing now work end-to-end."""
+
+    async def test_tool_auth_param_forwarded(self):
+        from fastmcp.server.auth import require_scopes
+
+        mcp = FastMCP()
+
+        class MyMixin(MCPMixin):
+            @mcp_tool(auth=require_scopes("write"))
+            def secure_tool(self):
+                return "ok"
+
+        MyMixin().register_tools(mcp)
+        # list_tools() filters by auth context; check internal provider directly
+        tools = await mcp.local_provider.list_tools()
+        assert any(t.name == "secure_tool" for t in tools)
+
+    async def test_tool_timeout_param_forwarded(self):
+        mcp = FastMCP()
+
+        class MyMixin(MCPMixin):
+            @mcp_tool(timeout=5.0)
+            def timed_tool(self):
+                return "ok"
+
+        MyMixin().register_tools(mcp)
+        tools = await mcp.list_tools()
+        assert any(t.name == "timed_tool" for t in tools)
+
+    async def test_tool_version_param_forwarded(self):
+        mcp = FastMCP()
+
+        class MyMixin(MCPMixin):
+            @mcp_tool(version="2.0")
+            def versioned_tool(self):
+                return "ok"
+
+        MyMixin().register_tools(mcp)
+        tools = await mcp.list_tools()
+        assert any(t.name == "versioned_tool" for t in tools)
+
+    async def test_resource_auth_param_forwarded(self):
+        from fastmcp.server.auth import require_scopes
+
+        mcp = FastMCP()
+
+        class MyMixin(MCPMixin):
+            @mcp_resource(uri="test://secure", auth=require_scopes("read"))
+            def secure_resource(self):
+                return "data"
+
+        MyMixin().register_resources(mcp)
+        # list_resources() filters by auth context; check internal provider directly
+        resources = await mcp.local_provider.list_resources()
+        assert any(str(r.uri) == "test://secure" for r in resources)
+
+    async def test_prompt_auth_param_forwarded(self):
+        from fastmcp.server.auth import require_scopes
+
+        mcp = FastMCP()
+
+        class MyMixin(MCPMixin):
+            @mcp_prompt(auth=require_scopes("read"))
+            def secure_prompt(self):
+                return "prompt text"
+
+        MyMixin().register_prompts(mcp)
+        # list_prompts() filters by auth context; check internal provider directly
+        prompts = await mcp.local_provider.list_prompts()
+        assert any(p.name == "secure_prompt" for p in prompts)
diff --git a/tests/deprecated/__init__.py b/tests/deprecated/__init__.py
new file mode 100644
index 0000000..b7d7878
--- /dev/null
+++ b/tests/deprecated/__init__.py
@@ -0,0 +1 @@
+# Tests for deprecated features - deprecation warnings are suppressed via conftest.py
diff --git a/tests/deprecated/conftest.py b/tests/deprecated/conftest.py
new file mode 100644
index 0000000..b9f8cf4
--- /dev/null
+++ b/tests/deprecated/conftest.py
@@ -0,0 +1,9 @@
+"""Conftest for deprecated tests - suppresses deprecation warnings."""
+
+import pytest
+
+
+def pytest_collection_modifyitems(items):
+    """Add filterwarnings marker to all tests in this directory."""
+    for item in items:
+        item.add_marker(pytest.mark.filterwarnings("ignore::DeprecationWarning"))
diff --git a/tests/deprecated/server/__init__.py b/tests/deprecated/server/__init__.py
new file mode 100644
index 0000000..9a5eaa9
--- /dev/null
+++ b/tests/deprecated/server/__init__.py
@@ -0,0 +1 @@
+"""Deprecated server tests."""
diff --git a/tests/deprecated/server/test_include_exclude_tags.py b/tests/deprecated/server/test_include_exclude_tags.py
new file mode 100644
index 0000000..70312b4
--- /dev/null
+++ b/tests/deprecated/server/test_include_exclude_tags.py
@@ -0,0 +1,25 @@
+"""Tests for removed include_tags/exclude_tags parameters."""
+
+import pytest
+
+from fastmcp import FastMCP
+
+
+class TestIncludeExcludeTagsRemoved:
+    """Test that include_tags/exclude_tags raise TypeError with migration hints."""
+
+    def test_exclude_tags_raises_type_error(self):
+        with pytest.raises(TypeError, match="no longer accepts `exclude_tags`"):
+            FastMCP(exclude_tags={"internal"})
+
+    def test_include_tags_raises_type_error(self):
+        with pytest.raises(TypeError, match="no longer accepts `include_tags`"):
+            FastMCP(include_tags={"public"})
+
+    def test_exclude_tags_error_mentions_disable(self):
+        with pytest.raises(TypeError, match="server.disable"):
+            FastMCP(exclude_tags={"internal"})
+
+    def test_include_tags_error_mentions_enable(self):
+        with pytest.raises(TypeError, match="server.enable"):
+            FastMCP(include_tags={"public"})
diff --git a/tests/deprecated/test_deprecated.py b/tests/deprecated/test_deprecated.py
new file mode 100644
index 0000000..37f33cf
--- /dev/null
+++ b/tests/deprecated/test_deprecated.py
@@ -0,0 +1,23 @@
+import pytest
+from starlette.applications import Starlette
+
+from fastmcp import FastMCP
+
+
+class TestRemovedKwargs:
+    def test_host_kwarg_raises_type_error(self):
+        with pytest.raises(TypeError, match="no longer accepts `host`"):
+            FastMCP(host="1.2.3.4")
+
+    def test_settings_property_removed(self):
+        mcp = FastMCP()
+        assert not hasattr(mcp, "_deprecated_settings")
+        with pytest.raises(AttributeError):
+            mcp.settings  # noqa: B018  # ty: ignore[unresolved-attribute]
+
+
+def test_http_app_with_sse_transport():
+    """Test that http_app with SSE transport works."""
+    server = FastMCP("TestServer")
+    app = server.http_app(transport="sse")
+    assert isinstance(app, Starlette)
diff --git a/tests/deprecated/test_elicitation.py b/tests/deprecated/test_elicitation.py
new file mode 100644
index 0000000..d86e549
--- /dev/null
+++ b/tests/deprecated/test_elicitation.py
@@ -0,0 +1,29 @@
+"""Tests for deprecated elicitation behavior."""
+
+from typing import Any, cast
+
+import pytest
+
+from fastmcp import Context, FastMCP
+from fastmcp.client.client import Client
+from fastmcp.client.elicitation import ElicitResult
+from fastmcp.exceptions import FastMCPDeprecationWarning
+from fastmcp.server.elicitation import AcceptedElicitation
+
+
+async def test_elicitation_none_response_type_warns_deprecation():
+    """Passing response_type=None is deprecated — warn at call time."""
+    mcp = FastMCP("TestServer")
+
+    @mcp.tool
+    async def my_tool(context: Context) -> dict[str, Any]:
+        with pytest.warns(FastMCPDeprecationWarning, match="response_type"):
+            result = await context.elicit(message="", response_type=None)
+        assert isinstance(result, AcceptedElicitation)
+        return cast(dict[str, Any], result.data)
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        return ElicitResult(action="accept", content={})
+
+    async with Client(mcp, elicitation_handler=elicitation_handler) as client:
+        await client.call_tool("my_tool", {})
diff --git a/tests/deprecated/test_settings.py b/tests/deprecated/test_settings.py
new file mode 100644
index 0000000..47ea661
--- /dev/null
+++ b/tests/deprecated/test_settings.py
@@ -0,0 +1,64 @@
+import pytest
+
+from fastmcp import FastMCP
+
+
+class TestRemovedServerInitKwargs:
+    """Test that removed server initialization keyword arguments raise TypeError."""
+
+    @pytest.mark.parametrize(
+        "kwarg, value, expected_message",
+        [
+            ("host", "0.0.0.0", "run_http_async"),
+            ("port", 8080, "run_http_async"),
+            ("sse_path", "/custom-sse", "FASTMCP_SSE_PATH"),
+            ("message_path", "/custom-message", "FASTMCP_MESSAGE_PATH"),
+            ("streamable_http_path", "/custom-http", "run_http_async"),
+            ("json_response", True, "run_http_async"),
+            ("stateless_http", True, "run_http_async"),
+            ("debug", True, "FASTMCP_DEBUG"),
+            ("log_level", "DEBUG", "run_http_async"),
+            ("on_duplicate_tools", "warn", "on_duplicate="),
+            ("on_duplicate_resources", "error", "on_duplicate="),
+            ("on_duplicate_prompts", "replace", "on_duplicate="),
+            ("tool_serializer", lambda x: str(x), "ToolResult"),
+            ("include_tags", {"public"}, "server.enable"),
+            ("exclude_tags", {"internal"}, "server.disable"),
+            (
+                "tool_transformations",
+                {"my_tool": {"name": "renamed"}},
+                "server.add_transform",
+            ),
+        ],
+    )
+    def test_removed_kwarg_raises_type_error(self, kwarg, value, expected_message):
+        with pytest.raises(TypeError, match=f"no longer accepts `{kwarg}`"):
+            FastMCP("TestServer", **{kwarg: value})
+
+    @pytest.mark.parametrize(
+        "kwarg, value, expected_message",
+        [
+            ("host", "0.0.0.0", "run_http_async"),
+            ("on_duplicate_tools", "warn", "on_duplicate="),
+            ("include_tags", {"public"}, "server.enable"),
+        ],
+    )
+    def test_removed_kwarg_error_includes_migration_hint(
+        self, kwarg, value, expected_message
+    ):
+        with pytest.raises(TypeError, match=expected_message):
+            FastMCP("TestServer", **{kwarg: value})
+
+    def test_unknown_kwarg_raises_standard_type_error(self):
+        with pytest.raises(TypeError, match="unexpected keyword argument"):
+            FastMCP("TestServer", **{"totally_fake_param": True})  # ty: ignore[invalid-argument-type]
+
+    def test_valid_kwargs_still_work(self):
+        server = FastMCP(
+            name="TestServer",
+            instructions="Test instructions",
+            on_duplicate="warn",
+            mask_error_details=True,
+        )
+        assert server.name == "TestServer"
+        assert server.instructions == "Test instructions"
diff --git a/tests/docs/test_doc_examples.py b/tests/docs/test_doc_examples.py
new file mode 100644
index 0000000..3d51e4e
--- /dev/null
+++ b/tests/docs/test_doc_examples.py
@@ -0,0 +1,152 @@
+"""Validate Python code examples in FastMCP documentation.
+
+Extracts code blocks from .mdx docs and checks:
+1. Syntax — every example parses as valid Python
+2. FastMCP imports — every ``from fastmcp.x import y`` resolves
+
+Supports tags in code fence prefix (for future use):
+    ```python test="skip"      — skip all checks
+    ```python lint="skip"      — skip all checks
+
+Run:
+    uv run pytest tests/docs/test_doc_examples.py -v -s
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from uuid import uuid4
+
+from pytest_examples import CodeExample
+from pytest_examples.find_examples import _extract_code_chunks
+
+DOCS_DIR = Path("docs")
+_SKIP_DIRS = {"python-sdk", "public"}
+
+# Snapshot baselines — ratchet DOWN as doc examples are fixed.
+MAX_SYNTAX_FAILURES = 0
+MAX_IMPORT_FAILURES = 0
+
+
+def _find_mdx_examples() -> list[CodeExample]:
+    """Find Python code examples in .mdx files.
+
+    pytest-examples only supports ``.md``; we call its internal
+    ``_extract_code_chunks`` directly so ``.mdx`` works without copying.
+    """
+    examples: list[CodeExample] = []
+    for mdx_file in sorted(DOCS_DIR.rglob("*.mdx")):
+        rel = mdx_file.relative_to(DOCS_DIR)
+        if rel.parts and rel.parts[0] in _SKIP_DIRS:
+            continue
+        code = mdx_file.read_text("utf-8")
+        group = uuid4()
+        examples.extend(_extract_code_chunks(mdx_file, code, group))
+    return examples
+
+
+def _should_skip(example: CodeExample) -> bool:
+    settings = example.prefix_settings()
+    return settings.get("lint") == "skip" or settings.get("test") == "skip"
+
+
+def _check_syntax(example: CodeExample) -> str | None:
+    """Return error description if syntax is invalid, else None."""
+    try:
+        ast.parse(example.source)
+        return None
+    except SyntaxError as e:
+        rel = Path(example.path).relative_to(DOCS_DIR)
+        return f"{rel}:{example.start_line}: line {e.lineno}: {e.msg}"
+
+
+def _check_fastmcp_imports(example: CodeExample) -> list[str]:
+    """Return list of broken fastmcp import descriptions."""
+    try:
+        tree = ast.parse(example.source)
+    except SyntaxError:
+        return []
+
+    errors: list[str] = []
+    rel = Path(example.path).relative_to(DOCS_DIR)
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name.startswith("fastmcp"):
+                    try:
+                        __import__(alias.name)
+                    except ImportError:
+                        errors.append(
+                            f"{rel}:{example.start_line}: cannot import '{alias.name}'"
+                        )
+        elif isinstance(node, ast.ImportFrom):
+            if node.module and node.module.startswith("fastmcp"):
+                names = [a.name for a in node.names]
+                try:
+                    mod = __import__(node.module, fromlist=names)
+                except ImportError:
+                    errors.append(
+                        f"{rel}:{example.start_line}: "
+                        f"cannot import module '{node.module}'"
+                    )
+                    continue
+                for name in names:
+                    if not hasattr(mod, name):
+                        errors.append(
+                            f"{rel}:{example.start_line}: "
+                            f"'{node.module}' has no '{name}'"
+                        )
+    return errors
+
+
+def test_doc_examples_quality():
+    """Doc examples should not regress in syntax or import correctness.
+
+    Checks every Python code block in ``docs/*.mdx`` (excluding
+    auto-generated ``python-sdk/`` and ``public/`` directories).
+    Reports all failures and asserts counts don't exceed known baselines.
+    """
+    examples = _find_mdx_examples()
+    syntax_failures: list[str] = []
+    import_failures: list[str] = []
+
+    for ex in examples:
+        if _should_skip(ex):
+            continue
+
+        err = _check_syntax(ex)
+        if err:
+            syntax_failures.append(err)
+            continue
+
+        # Frozen version snapshots (docs/v2/...) document older FastMCP releases,
+        # so their imports are validated against a package that no longer ships
+        # them. Syntax-check them above, but skip live-import validation.
+        if Path(ex.path).relative_to(DOCS_DIR).parts[0] == "v2":
+            continue
+
+        import_failures.extend(_check_fastmcp_imports(ex))
+
+    total = len(examples)
+    print(f"\nDoc examples checked: {total}")
+    print(f"Syntax failures:     {len(syntax_failures)}")
+    print(f"Import failures:     {len(import_failures)}")
+
+    if syntax_failures:
+        print("\nSyntax errors:")
+        for f in syntax_failures:
+            print(f"  {f}")
+
+    if import_failures:
+        print("\nBroken imports:")
+        for f in import_failures:
+            print(f"  {f}")
+
+    assert len(syntax_failures) <= MAX_SYNTAX_FAILURES, (
+        f"Syntax failures regressed: {len(syntax_failures)} > {MAX_SYNTAX_FAILURES}"
+    )
+    assert len(import_failures) <= MAX_IMPORT_FAILURES, (
+        f"Import failures regressed: {len(import_failures)} > {MAX_IMPORT_FAILURES}"
+    )
diff --git a/tests/experimental/README.md b/tests/experimental/README.md
new file mode 100644
index 0000000..1912e19
--- /dev/null
+++ b/tests/experimental/README.md
@@ -0,0 +1,3 @@
+# Experimental Tests
+
+Each directory in this folder tests a discrete experimental feature. The directory structure within each experiment should approximate the "normal" test directory structure to facilitate moving tests into place once/if the experiment is merged into the main codebase.
\ No newline at end of file
diff --git a/tests/experimental/__init__.py b/tests/experimental/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/experimental/transforms/test_code_mode.py b/tests/experimental/transforms/test_code_mode.py
new file mode 100644
index 0000000..557f33c
--- /dev/null
+++ b/tests/experimental/transforms/test_code_mode.py
@@ -0,0 +1,970 @@
+import asyncio
+import importlib
+import importlib.util
+import json
+from typing import Any
+
+import pytest
+from mcp_types import ImageContent, TextContent
+
+from fastmcp import Client, FastMCP
+from fastmcp.exceptions import ToolError
+from fastmcp.experimental.transforms.code_mode import (
+    _DEFAULT_LIMITS,
+    CodeMode,
+    GetSchemas,
+    GetToolCatalog,
+    MontySandboxProvider,
+    Search,
+    _ensure_async,
+)
+from fastmcp.server.context import Context
+from fastmcp.tools.base import Tool, ToolResult
+
+requires_monty = pytest.mark.skipif(
+    importlib.util.find_spec("pydantic_monty") is None,
+    reason="pydantic-monty is required for the real Monty sandbox provider",
+)
+
+# test_code_mode_monty_bare_call_returns_empty deliberately runs
+# `print(call_tool(...))` without awaiting, which orphans a `Provider.get_tool`
+# coroutine. CPython reports it as "never awaited" only when the coroutine is
+# garbage-collected, which happens asynchronously — often partway through a
+# *later* test — so a per-test filter can't reliably catch it. The suite
+# promotes that warning (and its unraisable-teardown variant) to an error via
+# `filterwarnings` in pyproject.toml, so scope the suppression to the module
+# but pin it to that exact coroutine; genuine "never awaited" leaks elsewhere
+# still surface as errors.
+pytestmark = [
+    pytest.mark.filterwarnings(
+        "ignore:coroutine 'Provider.get_tool' was never awaited:RuntimeWarning"
+    ),
+    pytest.mark.filterwarnings(
+        "ignore:Exception ignored in.*Provider.get_tool:"
+        "pytest.PytestUnraisableExceptionWarning"
+    ),
+]
+
+
+def _unwrap_result(result: ToolResult) -> Any:
+    """Extract the logical return value from a ToolResult."""
+    if result.structured_content is not None:
+        return result.structured_content
+
+    text_blocks = [
+        content.text for content in result.content if isinstance(content, TextContent)
+    ]
+    if not text_blocks:
+        return None
+
+    if len(text_blocks) == 1:
+        try:
+            return json.loads(text_blocks[0])
+        except json.JSONDecodeError:
+            return text_blocks[0]
+
+    values: list[Any] = []
+    for text in text_blocks:
+        try:
+            values.append(json.loads(text))
+        except json.JSONDecodeError:
+            values.append(text)
+    return values
+
+
+def _unwrap_string_result(result: ToolResult) -> str:
+    """Extract a string result from a ToolResult.
+
+    String results are wrapped in ``{"result": "..."}`` by the
+    structured-output convention.
+    """
+    data = _unwrap_result(result)
+    if isinstance(data, dict) and "result" in data:
+        return data["result"]
+    assert isinstance(data, str)
+    return data
+
+
+class _UnsafeTestSandboxProvider:
+    """UNSAFE: Uses exec() for testing only. Never use in production."""
+
+    async def run(
+        self,
+        code: str,
+        *,
+        inputs: dict[str, Any] | None = None,
+        external_functions: dict[str, Any] | None = None,
+    ) -> Any:
+        namespace: dict[str, Any] = {}
+        if inputs:
+            namespace.update(inputs)
+        if external_functions:
+            namespace.update(
+                {key: _ensure_async(value) for key, value in external_functions.items()}
+            )
+
+        wrapped = "async def __test_main__():\n"
+        for line in code.splitlines():
+            wrapped += f"    {line}\n"
+        if not code.strip():
+            wrapped += "    return None\n"
+
+        exec(wrapped, namespace, namespace)
+        return await namespace["__test_main__"]()
+
+
+async def _run_tool(
+    server: FastMCP, name: str, arguments: dict[str, Any]
+) -> ToolResult:
+    return await server.call_tool(name, arguments)
+
+
+# ---------------------------------------------------------------------------
+# CodeMode core tests
+# ---------------------------------------------------------------------------
+
+
+async def test_code_mode_default_tools() -> None:
+    """Default CodeMode exposes search, get_schema, and execute."""
+    mcp = FastMCP("CodeMode Default")
+
+    @mcp.tool
+    def ping() -> str:
+        return "pong"
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    listed_tools = await mcp.list_tools(run_middleware=False)
+    assert {tool.name for tool in listed_tools} == {"search", "get_schema", "execute"}
+
+
+async def test_code_mode_search_returns_lightweight_results() -> None:
+    """Default search returns tool names and descriptions, not full schemas."""
+    mcp = FastMCP("CodeMode Search")
+
+    @mcp.tool
+    def square(x: int) -> int:
+        """Compute the square of a number."""
+        return x * x
+
+    @mcp.tool
+    def greet(name: str) -> str:
+        """Say hello to someone."""
+        return f"Hello, {name}!"
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(mcp, "search", {"query": "square number"})
+    text = _unwrap_string_result(result)
+    assert "square" in text
+    assert "Compute the square" in text
+    # Should NOT contain full schema details
+    assert "inputSchema" not in text
+
+
+async def test_code_mode_get_schema_brief() -> None:
+    """get_schema with detail=brief returns names and descriptions only."""
+    mcp = FastMCP("CodeMode Schema Brief")
+
+    @mcp.tool
+    def square(x: int) -> int:
+        """Compute the square of a number."""
+        return x * x
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(
+        mcp, "get_schema", {"tools": ["square"], "detail": "brief"}
+    )
+    text = _unwrap_string_result(result)
+    assert "square" in text
+    assert "Compute the square" in text
+    # brief should NOT include parameter details
+    assert "**Parameters**" not in text
+
+
+async def test_code_mode_get_schema_detailed() -> None:
+    """get_schema with detail=detailed returns markdown with parameter info."""
+    mcp = FastMCP("CodeMode Schema Detailed")
+
+    @mcp.tool
+    def square(x: int) -> int:
+        """Compute the square of a number."""
+        return x * x
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(
+        mcp, "get_schema", {"tools": ["square"], "detail": "detailed"}
+    )
+    text = _unwrap_string_result(result)
+    assert "### square" in text
+    assert "Compute the square" in text
+    assert "**Parameters**" in text
+    assert "`x` (integer, required)" in text
+
+
+async def test_code_mode_get_schema_full() -> None:
+    """get_schema with detail=full returns JSON schema."""
+    mcp = FastMCP("CodeMode Schema Full")
+
+    @mcp.tool
+    def square(x: int) -> int:
+        """Compute the square of a number."""
+        return x * x
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(mcp, "get_schema", {"tools": ["square"], "detail": "full"})
+    text = _unwrap_string_result(result)
+    parsed = json.loads(text)
+    assert isinstance(parsed, list)
+    assert parsed[0]["name"] == "square"
+    assert "inputSchema" in parsed[0]
+
+
+async def test_code_mode_get_schema_default_is_detailed() -> None:
+    """get_schema defaults to detailed (markdown with parameters)."""
+    mcp = FastMCP("CodeMode Schema Default")
+
+    @mcp.tool
+    def square(x: int) -> int:
+        """Compute the square of a number."""
+        return x * x
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(mcp, "get_schema", {"tools": ["square"]})
+    text = _unwrap_string_result(result)
+    assert "### square" in text
+    assert "**Parameters**" in text
+
+
+async def test_code_mode_get_schema_not_found() -> None:
+    """get_schema reports tools that don't exist in the catalog."""
+    mcp = FastMCP("CodeMode Schema NotFound")
+
+    @mcp.tool
+    def ping() -> str:
+        return "pong"
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(mcp, "get_schema", {"tools": ["nonexistent"]})
+    text = _unwrap_string_result(result)
+    assert "not found" in text.lower()
+    assert "nonexistent" in text
+
+
+async def test_code_mode_get_schema_partial_match() -> None:
+    """get_schema returns schemas for found tools and reports missing ones."""
+    mcp = FastMCP("CodeMode Schema Partial")
+
+    @mcp.tool
+    def square(x: int) -> int:
+        """Compute the square."""
+        return x * x
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(mcp, "get_schema", {"tools": ["square", "nonexistent"]})
+    text = _unwrap_string_result(result)
+    assert "### square" in text
+    assert "nonexistent" in text
+
+
+async def test_code_mode_execute_works() -> None:
+    """Execute tool can call backend tools through the sandbox."""
+    mcp = FastMCP("CodeMode Execute")
+
+    @mcp.tool
+    def add(x: int, y: int) -> int:
+        return x + y
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(
+        mcp, "execute", {"code": "return await call_tool('add', {'x': 2, 'y': 3})"}
+    )
+    assert _unwrap_result(result) == {"result": 5}
+
+
+# ---------------------------------------------------------------------------
+# Tool naming and configuration
+# ---------------------------------------------------------------------------
+
+
+async def test_code_mode_custom_execute_name() -> None:
+    mcp = FastMCP("CodeMode Custom Execute")
+
+    @mcp.tool
+    def ping() -> str:
+        return "pong"
+
+    mcp.add_transform(
+        CodeMode(
+            sandbox_provider=_UnsafeTestSandboxProvider(),
+            execute_tool_name="run_code",
+        )
+    )
+
+    listed = await mcp.list_tools(run_middleware=False)
+    names = {t.name for t in listed}
+    assert "run_code" in names
+    assert "execute" not in names
+
+
+async def test_code_mode_custom_execute_description() -> None:
+    mcp = FastMCP("CodeMode Custom Desc")
+
+    @mcp.tool
+    def ping() -> str:
+        return "pong"
+
+    mcp.add_transform(
+        CodeMode(
+            sandbox_provider=_UnsafeTestSandboxProvider(),
+            execute_description="Custom execute description",
+        )
+    )
+
+    listed = await mcp.list_tools(run_middleware=False)
+    by_name = {t.name: t for t in listed}
+    assert by_name["execute"].description == "Custom execute description"
+
+
+async def test_code_mode_default_execute_description() -> None:
+    mcp = FastMCP("CodeMode Defaults")
+
+    @mcp.tool
+    def ping() -> str:
+        return "pong"
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    listed = await mcp.list_tools(run_middleware=False)
+    by_name = {t.name: t for t in listed}
+    desc = by_name["execute"].description or ""
+
+    assert "single block" in desc
+    assert "Use `return` to produce output." in desc
+    assert (
+        "Only `call_tool(tool_name: str, params: dict) -> Any` is available in scope."
+        in desc
+    )
+
+
+# ---------------------------------------------------------------------------
+# Discovery tool customization
+# ---------------------------------------------------------------------------
+
+
+async def test_code_mode_no_discovery_tools() -> None:
+    """CodeMode with empty discovery_tools exposes only execute."""
+    mcp = FastMCP("CodeMode No Discovery")
+
+    @mcp.tool
+    def ping() -> str:
+        return "pong"
+
+    mcp.add_transform(
+        CodeMode(
+            discovery_tools=[],
+            sandbox_provider=_UnsafeTestSandboxProvider(),
+        )
+    )
+
+    listed = await mcp.list_tools(run_middleware=False)
+    assert {t.name for t in listed} == {"execute"}
+
+
+async def test_code_mode_custom_discovery_tool_function() -> None:
+    """A plain function can serve as a discovery tool factory."""
+    mcp = FastMCP("CodeMode Custom Discovery")
+
+    @mcp.tool
+    def square(x: int) -> int:
+        """Compute the square."""
+        return x * x
+
+    def list_all(get_catalog: GetToolCatalog) -> Tool:
+        async def list_tools(
+            ctx: Context = None,  # type: ignore[assignment]  # ty:ignore[invalid-parameter-default]
+        ) -> str:
+            """List all available tools."""
+            tools = await get_catalog(ctx)
+            return ", ".join(t.name for t in tools)
+
+        return Tool.from_function(fn=list_tools, name="list_all")
+
+    mcp.add_transform(
+        CodeMode(
+            discovery_tools=[list_all],
+            sandbox_provider=_UnsafeTestSandboxProvider(),
+        )
+    )
+
+    listed = await mcp.list_tools(run_middleware=False)
+    assert {t.name for t in listed} == {"list_all", "execute"}
+
+    result = await _run_tool(mcp, "list_all", {})
+    text = _unwrap_string_result(result)
+    assert "square" in text
+
+
+async def test_code_mode_search_detailed() -> None:
+    """Search with detail='detailed' returns markdown with parameter info."""
+    mcp = FastMCP("CodeMode Search Detailed")
+
+    @mcp.tool
+    def square(x: int) -> int:
+        """Compute the square."""
+        return x * x
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(mcp, "search", {"query": "square", "detail": "detailed"})
+    text = _unwrap_string_result(result)
+    assert "### square" in text
+    assert "Compute the square" in text
+    assert "**Parameters**" in text
+    assert "`x` (integer, required)" in text
+
+
+async def test_code_mode_search_tool_full_detail() -> None:
+    """Search with detail='full' includes JSON schemas."""
+    mcp = FastMCP("CodeMode Search Full")
+
+    @mcp.tool
+    def square(x: int) -> int:
+        """Compute the square."""
+        return x * x
+
+    mcp.add_transform(
+        CodeMode(
+            discovery_tools=[Search(default_detail="full")],
+            sandbox_provider=_UnsafeTestSandboxProvider(),
+        )
+    )
+
+    result = await _run_tool(mcp, "search", {"query": "square"})
+    text = _unwrap_string_result(result)
+    parsed = json.loads(text)
+    assert isinstance(parsed, list)
+    assert parsed[0]["name"] == "square"
+    assert "inputSchema" in parsed[0]
+
+
+async def test_code_mode_custom_search_tool_name() -> None:
+    """Search and GetSchemas support custom names."""
+    mcp = FastMCP("CodeMode Custom Names")
+
+    @mcp.tool
+    def ping() -> str:
+        return "pong"
+
+    mcp.add_transform(
+        CodeMode(
+            discovery_tools=[
+                Search(name="find"),
+                GetSchemas(name="describe"),
+            ],
+            sandbox_provider=_UnsafeTestSandboxProvider(),
+        )
+    )
+
+    listed = await mcp.list_tools(run_middleware=False)
+    assert {t.name for t in listed} == {"find", "describe", "execute"}
+
+
+def test_code_mode_rejects_discovery_execute_name_collision() -> None:
+    """CodeMode raises ValueError when a discovery tool collides with execute."""
+    cm = CodeMode(
+        discovery_tools=[Search(name="execute")],
+        sandbox_provider=_UnsafeTestSandboxProvider(),
+    )
+    with pytest.raises(ValueError, match="collides"):
+        cm._build_discovery_tools()
+
+
+def test_code_mode_rejects_duplicate_discovery_names() -> None:
+    """CodeMode raises ValueError when discovery tools have duplicate names."""
+    cm = CodeMode(
+        discovery_tools=[Search(name="search"), Search(name="search")],
+        sandbox_provider=_UnsafeTestSandboxProvider(),
+    )
+    with pytest.raises(ValueError, match="unique"):
+        cm._build_discovery_tools()
+
+
+# ---------------------------------------------------------------------------
+# Visibility and auth
+# ---------------------------------------------------------------------------
+
+
+async def test_code_mode_execute_respects_disabled_tool_visibility() -> None:
+    mcp = FastMCP("CodeMode Disabled")
+
+    @mcp.tool
+    def secret() -> str:
+        return "nope"
+
+    mcp.disable(names={"secret"}, components={"tool"})
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    with pytest.raises(ToolError, match=r"Unknown tool"):
+        await _run_tool(
+            mcp, "execute", {"code": "return await call_tool('secret', {})"}
+        )
+
+
+async def test_code_mode_search_respects_disabled_tool_visibility() -> None:
+    mcp = FastMCP("CodeMode Disabled Search")
+
+    @mcp.tool
+    def secret() -> str:
+        """A secret tool."""
+        return "nope"
+
+    mcp.disable(names={"secret"}, components={"tool"})
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(mcp, "search", {"query": "secret"})
+    text = _unwrap_string_result(result)
+    assert "secret" not in text or "No tools" in text
+
+
+async def test_code_mode_execute_sees_mid_run_visibility_changes() -> None:
+    """Unlocking a tool mid-execution makes it callable in the same run."""
+    mcp = FastMCP("CodeMode Unlock")
+
+    @mcp.tool
+    async def unlock(ctx: Context) -> str:
+        await ctx.enable_components(names={"secret"}, components={"tool"})
+        return "unlocked"
+
+    @mcp.tool
+    async def secret() -> str:
+        return "secret-ok"
+
+    mcp.disable(names={"secret"}, components={"tool"})
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    async with Client(mcp) as client:
+        result = await client.call_tool(
+            "execute",
+            {
+                "code": "await call_tool('unlock', {})\nreturn await call_tool('secret', {})"
+            },
+        )
+        assert result.data == {"result": "secret-ok"}
+
+
+async def test_code_mode_execute_respects_tool_auth() -> None:
+    mcp = FastMCP("CodeMode Auth")
+
+    @mcp.tool(auth=lambda _ctx: False)
+    def protected() -> str:
+        return "nope"
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    with pytest.raises(ToolError, match=r"Unknown tool"):
+        await _run_tool(
+            mcp, "execute", {"code": "return await call_tool('protected', {})"}
+        )
+
+
+async def test_code_mode_search_respects_tool_auth() -> None:
+    mcp = FastMCP("CodeMode Auth Search")
+
+    @mcp.tool(auth=lambda _ctx: False)
+    def protected() -> str:
+        """A protected tool."""
+        return "nope"
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(mcp, "search", {"query": "protected"})
+    text = _unwrap_string_result(result)
+    assert "protected" not in text or "No tools" in text
+
+
+async def test_code_mode_shadows_colliding_tool_names() -> None:
+    """Backend tools with the same name as meta-tools are shadowed."""
+    mcp = FastMCP("CodeMode Collision")
+
+    @mcp.tool
+    def search() -> str:
+        return "real search"
+
+    @mcp.tool
+    def ping() -> str:
+        return "pong"
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    tools = await mcp.list_tools(run_middleware=False)
+    tool_names = {t.name for t in tools}
+    assert "execute" in tool_names
+
+    result = await _run_tool(
+        mcp, "execute", {"code": 'return await call_tool("ping", {})'}
+    )
+    assert _unwrap_result(result) == {"result": "pong"}
+
+
+# ---------------------------------------------------------------------------
+# get_tool pass-through
+# ---------------------------------------------------------------------------
+
+
+async def test_code_mode_get_tool_returns_meta_tools_and_passes_through() -> None:
+    """get_tool returns meta-tools by name and passes through backend tools."""
+    mcp = FastMCP("CodeMode GetTool")
+
+    @mcp.tool
+    def ping() -> str:
+        return "pong"
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    search_tool = await mcp.get_tool("search")
+    assert search_tool is not None
+    assert search_tool.name == "search"
+
+    schema_tool = await mcp.get_tool("get_schema")
+    assert schema_tool is not None
+    assert schema_tool.name == "get_schema"
+
+    execute_tool = await mcp.get_tool("execute")
+    assert execute_tool is not None
+    assert execute_tool.name == "execute"
+
+    ping_tool = await mcp.get_tool("ping")
+    assert ping_tool is not None
+    assert ping_tool.name == "ping"
+
+
+# ---------------------------------------------------------------------------
+# Execute edge cases
+# ---------------------------------------------------------------------------
+
+
+async def test_code_mode_execute_non_text_content_stringified() -> None:
+    mcp = FastMCP("CodeMode NonText")
+
+    @mcp.tool
+    def image_tool() -> ImageContent:
+        return ImageContent(type="image", data="base64data", mime_type="image/png")
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(
+        mcp, "execute", {"code": "return await call_tool('image_tool', {})"}
+    )
+    unwrapped = _unwrap_result(result)
+    assert isinstance(unwrapped, str)
+    assert "base64data" in unwrapped
+
+
+async def test_code_mode_execute_multi_tool_chaining() -> None:
+    """Execute block can chain multiple call_tool() calls."""
+    mcp = FastMCP("CodeMode Chaining")
+
+    @mcp.tool
+    def double(x: int) -> int:
+        return x * 2
+
+    @mcp.tool
+    def add_one(x: int) -> int:
+        return x + 1
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(
+        mcp,
+        "execute",
+        {
+            "code": (
+                "a = await call_tool('double', {'x': 3})\n"
+                "b = await call_tool('add_one', {'x': a['result']})\n"
+                "return b"
+            )
+        },
+    )
+    assert _unwrap_result(result) == {"result": 7}
+
+
+async def test_code_mode_sandbox_error_surfaces_as_tool_error() -> None:
+    mcp = FastMCP("CodeMode Errors")
+
+    @mcp.tool
+    def ping() -> str:
+        return "pong"
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    with pytest.raises(ToolError):
+        await _run_tool(mcp, "execute", {"code": "raise ValueError('boom')"})
+
+
+# ---------------------------------------------------------------------------
+# Real Monty sandbox end-to-end (issue #4263)
+#
+# Every execute test above runs through the exec-based
+# _UnsafeTestSandboxProvider, so the real MontySandboxProvider + call_tool
+# path is otherwise uncovered. These tests drive call_tool through the actual
+# pydantic-monty sandbox, the path #4263 reported as broken.
+# ---------------------------------------------------------------------------
+
+
+@requires_monty
+@pytest.mark.parametrize("async_tool", [False, True])
+async def test_code_mode_monty_execute_call_tool(async_tool: bool) -> None:
+    """call_tool resolves and returns through the real Monty sandbox.
+
+    The reported failure ("empty result") could not be reproduced on a
+    directly-registered tool: ``return await call_tool(...)`` returns the
+    value for both sync and async backend tools.
+    """
+    mcp = FastMCP("CodeMode Monty Execute")
+
+    if async_tool:
+
+        @mcp.tool
+        async def add(x: int, y: int) -> int:
+            return x + y
+    else:
+
+        @mcp.tool
+        def add(x: int, y: int) -> int:
+            return x + y
+
+    mcp.add_transform(CodeMode(sandbox_provider=MontySandboxProvider()))
+
+    result = await _run_tool(
+        mcp, "execute", {"code": "return await call_tool('add', {'x': 2, 'y': 3})"}
+    )
+    assert _unwrap_result(result) == {"result": 5}
+
+
+@requires_monty
+async def test_code_mode_monty_execute_string_result() -> None:
+    """A string-returning tool round-trips through the real Monty sandbox."""
+    mcp = FastMCP("CodeMode Monty String")
+
+    @mcp.tool
+    def greet(name: str) -> str:
+        return f"Hello, {name}!"
+
+    mcp.add_transform(CodeMode(sandbox_provider=MontySandboxProvider()))
+
+    result = await _run_tool(
+        mcp, "execute", {"code": "return await call_tool('greet', {'name': 'World'})"}
+    )
+    assert _unwrap_string_result(result) == "Hello, World!"
+
+
+@requires_monty
+async def test_code_mode_monty_execute_chaining() -> None:
+    """Multiple sequential call_tool() calls chain through the real sandbox."""
+    mcp = FastMCP("CodeMode Monty Chaining")
+
+    @mcp.tool
+    def add(x: int, y: int) -> int:
+        return x + y
+
+    mcp.add_transform(CodeMode(sandbox_provider=MontySandboxProvider()))
+
+    result = await _run_tool(
+        mcp,
+        "execute",
+        {
+            "code": (
+                "a = await call_tool('add', {'x': 1, 'y': 2})\n"
+                "b = await call_tool('add', {'x': a['result'], 'y': 10})\n"
+                "return b"
+            )
+        },
+    )
+    assert _unwrap_result(result) == {"result": 13}
+
+
+@requires_monty
+async def test_code_mode_monty_bare_call_returns_empty() -> None:
+    """Pins the reported #4263 symptom as a usage error, not a sandbox bug.
+
+    The report's code called ``call_tool`` bare — ``print(call_tool(...))``
+    without ``await`` or ``return``. ``call_tool`` is async, so a bare call
+    hands back an unawaited coroutine, and ``print`` returns ``None``; the
+    block therefore returns nothing and ``execute`` yields an empty result.
+    The accompanying "coroutine ... was never awaited" RuntimeWarning is a
+    cascading effect of that unawaited coroutine being garbage-collected, not
+    a separate defect (see the module-level ``filterwarnings`` note for why it
+    is suppressed rather than asserted).
+    """
+    mcp = FastMCP("CodeMode Monty Bare Call")
+
+    @mcp.tool
+    def greet(name: str) -> str:
+        return f"Hello, {name}!"
+
+    mcp.add_transform(CodeMode(sandbox_provider=MontySandboxProvider()))
+
+    result = await _run_tool(
+        mcp, "execute", {"code": "print(call_tool('greet', {'name': 'World'}))"}
+    )
+    assert result.content == []
+    assert result.structured_content is None
+
+
+# ---------------------------------------------------------------------------
+# Sandbox provider tests
+# ---------------------------------------------------------------------------
+
+
+async def test_monty_provider_raises_informative_error_when_missing(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    provider = MontySandboxProvider()
+    real_import_module = importlib.import_module
+
+    def _fake_import_module(name: str, package: str | None = None):
+        if name == "pydantic_monty":
+            raise ModuleNotFoundError("No module named 'pydantic_monty'")
+        return real_import_module(name, package)
+
+    monkeypatch.setattr(importlib, "import_module", _fake_import_module)
+
+    with pytest.raises(ImportError, match=r"fastmcp\[code-mode\]"):
+        await provider.run("return 1")
+
+
+async def test_monty_provider_forwards_limits() -> None:
+    provider = MontySandboxProvider(limits={"max_duration_secs": 0.1})
+
+    with pytest.raises(Exception, match="time limit exceeded"):
+        await provider.run("x = 0\nfor _ in range(10**9):\n    x += 1")
+
+
+async def test_monty_provider_applies_default_limits() -> None:
+    provider = MontySandboxProvider()
+    assert provider.limits == _DEFAULT_LIMITS
+    # Default limits are generous enough for ordinary code.
+    result = await provider.run("return 1 + 2")
+    assert result == 3
+
+
+async def test_monty_provider_explicit_none_disables_limits() -> None:
+    provider = MontySandboxProvider(limits=None)
+    assert provider.limits is None
+    result = await provider.run("return 1 + 2")
+    assert result == 3
+
+
+async def test_monty_provider_explicit_limits_override_defaults() -> None:
+    provider = MontySandboxProvider(limits={"max_duration_secs": 0.1})
+    assert provider.limits == {"max_duration_secs": 0.1}
+
+
+async def test_monty_provider_default_limits_are_not_shared_between_instances() -> None:
+    """Each default provider must own its limits dict.
+
+    `limits` is a mutable public attribute; if instances shared the
+    module-level baseline, mutating one would silently change the defaults
+    for every other default provider in the process.
+    """
+    a = MontySandboxProvider()
+    b = MontySandboxProvider()
+
+    assert a.limits is not b.limits
+    assert a.limits is not _DEFAULT_LIMITS
+
+    assert a.limits is not None
+    a.limits["max_duration_secs"] = 1
+
+    assert b.limits == {"max_duration_secs": 30.0, "max_memory": 100_000_000}
+    assert _DEFAULT_LIMITS == {"max_duration_secs": 30.0, "max_memory": 100_000_000}
+
+
+async def test_code_mode_max_tool_calls_default_is_50() -> None:
+    assert CodeMode().max_tool_calls == 50
+
+
+async def test_code_mode_max_tool_calls_enforced() -> None:
+    mcp = FastMCP("CodeMode ToolCap")
+
+    @mcp.tool
+    def ping() -> str:
+        return "pong"
+
+    mcp.add_transform(
+        CodeMode(sandbox_provider=_UnsafeTestSandboxProvider(), max_tool_calls=3)
+    )
+
+    code = "\n".join(
+        [
+            "results = []",
+            "for _ in range(5):",
+            "    results.append(await call_tool('ping', {}))",
+            "return results",
+        ]
+    )
+    with pytest.raises(ToolError, match=r"Tool call limit exceeded: at most 3"):
+        await _run_tool(mcp, "execute", {"code": code})
+
+
+async def test_code_mode_max_tool_calls_none_is_unlimited() -> None:
+    mcp = FastMCP("CodeMode ToolCapNone")
+
+    @mcp.tool
+    def ping() -> str:
+        return "pong"
+
+    mcp.add_transform(
+        CodeMode(sandbox_provider=_UnsafeTestSandboxProvider(), max_tool_calls=None)
+    )
+
+    code = "\n".join(
+        [
+            "n = 0",
+            "for _ in range(60):",
+            "    await call_tool('ping', {})",
+            "    n += 1",
+            "return n",
+        ]
+    )
+    result = await _run_tool(mcp, "execute", {"code": code})
+    assert _unwrap_result(result) == 60
+
+
+async def test_monty_provider_cancels_future_when_task_cancelled() -> None:
+    """Cancelling the awaiting task must cancel the underlying sandbox future.
+
+    Otherwise the native Monty thread keeps running to completion after a
+    client disconnects or the request times out. A subclass overrides the
+    launch seam so the cancellation handling in `run()` is exercised against
+    a controllable future rather than a live sandbox thread.
+    """
+    loop = asyncio.get_running_loop()
+    sandbox_future: asyncio.Future[Any] = loop.create_future()
+
+    class _NeverFinishingProvider(MontySandboxProvider):
+        def _run_monty(self, monty: Any, *, inputs: Any, external_functions: Any):
+            return sandbox_future
+
+    provider = _NeverFinishingProvider()
+    task = asyncio.create_task(provider.run("return 1"))
+
+    # Advance the task to `await future` (no suspension point before it).
+    for _ in range(3):
+        await asyncio.sleep(0)
+        if not task.done():
+            break
+
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+
+    assert sandbox_future.cancelled()
diff --git a/tests/experimental/transforms/test_code_mode_discovery.py b/tests/experimental/transforms/test_code_mode_discovery.py
new file mode 100644
index 0000000..932257c
--- /dev/null
+++ b/tests/experimental/transforms/test_code_mode_discovery.py
@@ -0,0 +1,604 @@
+import json
+from typing import Any
+
+from mcp_types import TextContent
+
+from fastmcp import FastMCP
+from fastmcp.experimental.transforms.code_mode import (
+    CodeMode,
+    GetTags,
+    ListTools,
+    Search,
+    _ensure_async,
+)
+from fastmcp.tools.base import ToolResult
+
+
+def _unwrap_result(result: ToolResult) -> Any:
+    """Extract the logical return value from a ToolResult."""
+    if result.structured_content is not None:
+        return result.structured_content
+
+    text_blocks = [
+        content.text for content in result.content if isinstance(content, TextContent)
+    ]
+    if not text_blocks:
+        return None
+
+    if len(text_blocks) == 1:
+        try:
+            return json.loads(text_blocks[0])
+        except json.JSONDecodeError:
+            return text_blocks[0]
+
+    values: list[Any] = []
+    for text in text_blocks:
+        try:
+            values.append(json.loads(text))
+        except json.JSONDecodeError:
+            values.append(text)
+    return values
+
+
+def _unwrap_string_result(result: ToolResult) -> str:
+    """Extract a string result from a ToolResult."""
+    data = _unwrap_result(result)
+    if isinstance(data, dict) and "result" in data:
+        return data["result"]
+    assert isinstance(data, str)
+    return data
+
+
+class _UnsafeTestSandboxProvider:
+    """UNSAFE: Uses exec() for testing only. Never use in production."""
+
+    async def run(
+        self,
+        code: str,
+        *,
+        inputs: dict[str, Any] | None = None,
+        external_functions: dict[str, Any] | None = None,
+    ) -> Any:
+        namespace: dict[str, Any] = {}
+        if inputs:
+            namespace.update(inputs)
+        if external_functions:
+            namespace.update(
+                {key: _ensure_async(value) for key, value in external_functions.items()}
+            )
+
+        wrapped = "async def __test_main__():\n"
+        for line in code.splitlines():
+            wrapped += f"    {line}\n"
+        if not code.strip():
+            wrapped += "    return None\n"
+
+        exec(wrapped, namespace, namespace)
+        return await namespace["__test_main__"]()
+
+
+async def _run_tool(
+    server: FastMCP, name: str, arguments: dict[str, Any]
+) -> ToolResult:
+    return await server.call_tool(name, arguments)
+
+
+# ---------------------------------------------------------------------------
+# Tags discovery tool
+# ---------------------------------------------------------------------------
+
+
+async def test_categories_brief_shows_tag_counts() -> None:
+    mcp = FastMCP("Tags Brief")
+
+    @mcp.tool(tags={"math"})
+    def add(x: int, y: int) -> int:
+        return x + y
+
+    @mcp.tool(tags={"math"})
+    def multiply(x: int, y: int) -> int:
+        return x * y
+
+    @mcp.tool(tags={"text"})
+    def greet(name: str) -> str:
+        return f"Hello, {name}!"
+
+    mcp.add_transform(
+        CodeMode(
+            discovery_tools=[GetTags()],
+            sandbox_provider=_UnsafeTestSandboxProvider(),
+        )
+    )
+
+    result = await _run_tool(mcp, "tags", {})
+    text = _unwrap_string_result(result)
+    assert "math (2 tools)" in text
+    assert "text (1 tool)" in text
+
+
+async def test_categories_full_lists_tools_per_tag() -> None:
+    mcp = FastMCP("Tags Full")
+
+    @mcp.tool(tags={"math"})
+    def add(x: int, y: int) -> int:
+        """Add two numbers."""
+        return x + y
+
+    @mcp.tool(tags={"text"})
+    def greet(name: str) -> str:
+        """Say hello."""
+        return f"Hello, {name}!"
+
+    mcp.add_transform(
+        CodeMode(
+            discovery_tools=[GetTags(default_detail="full")],
+            sandbox_provider=_UnsafeTestSandboxProvider(),
+        )
+    )
+
+    result = await _run_tool(mcp, "tags", {})
+    text = _unwrap_string_result(result)
+    assert "### math" in text
+    assert "- add: Add two numbers." in text
+    assert "### text" in text
+    assert "- greet: Say hello." in text
+
+
+async def test_categories_includes_untagged() -> None:
+    mcp = FastMCP("Tags Untagged")
+
+    @mcp.tool(tags={"math"})
+    def add(x: int, y: int) -> int:
+        return x + y
+
+    @mcp.tool
+    def ping() -> str:
+        return "pong"
+
+    mcp.add_transform(
+        CodeMode(
+            discovery_tools=[GetTags()],
+            sandbox_provider=_UnsafeTestSandboxProvider(),
+        )
+    )
+
+    result = await _run_tool(mcp, "tags", {})
+    text = _unwrap_string_result(result)
+    assert "math" in text
+    assert "untagged (1 tool)" in text
+
+
+async def test_categories_tool_in_multiple_tags() -> None:
+    mcp = FastMCP("Tags Multi-tag")
+
+    @mcp.tool(tags={"math", "core"})
+    def add(x: int, y: int) -> int:
+        return x + y
+
+    mcp.add_transform(
+        CodeMode(
+            discovery_tools=[GetTags(default_detail="full")],
+            sandbox_provider=_UnsafeTestSandboxProvider(),
+        )
+    )
+
+    result = await _run_tool(mcp, "tags", {})
+    text = _unwrap_string_result(result)
+    assert "### core" in text
+    assert "### math" in text
+    # Tool appears under both tags
+    assert text.count("- add") == 2
+
+
+async def test_categories_detail_override_per_call() -> None:
+    """LLM can override default_detail on a per-call basis."""
+    mcp = FastMCP("Tags Override")
+
+    @mcp.tool(tags={"math"})
+    def add(x: int, y: int) -> int:
+        """Add numbers."""
+        return x + y
+
+    mcp.add_transform(
+        CodeMode(
+            discovery_tools=[GetTags()],  # default_detail="brief"
+            sandbox_provider=_UnsafeTestSandboxProvider(),
+        )
+    )
+
+    # Override to full
+    result = await _run_tool(mcp, "tags", {"detail": "full"})
+    text = _unwrap_string_result(result)
+    assert "### math" in text
+    assert "- add: Add numbers." in text
+
+
+async def test_get_tags_empty_catalog() -> None:
+    """GetTags with no tools returns 'No tools available.'."""
+    mcp = FastMCP("CodeMode Empty Tags")
+
+    mcp.disable(names={"ping"}, components={"tool"})
+    mcp.add_transform(
+        CodeMode(
+            discovery_tools=[GetTags()],
+            sandbox_provider=_UnsafeTestSandboxProvider(),
+        )
+    )
+
+    result = await _run_tool(mcp, "tags", {})
+    text = _unwrap_string_result(result)
+    assert "No tools available" in text
+
+
+# ---------------------------------------------------------------------------
+# Search with tags filtering
+# ---------------------------------------------------------------------------
+
+
+async def test_search_with_tags_filter() -> None:
+    mcp = FastMCP("Search Tags")
+
+    @mcp.tool(tags={"math"})
+    def add(x: int, y: int) -> int:
+        """Add two numbers."""
+        return x + y
+
+    @mcp.tool(tags={"text"})
+    def greet(name: str) -> str:
+        """Say hello."""
+        return f"Hello, {name}!"
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(mcp, "search", {"query": "add hello", "tags": ["math"]})
+    text = _unwrap_string_result(result)
+    assert "add" in text
+    assert "greet" not in text
+
+
+async def test_search_with_tags_filter_no_matches() -> None:
+    mcp = FastMCP("Search Tags Empty")
+
+    @mcp.tool(tags={"math"})
+    def add(x: int, y: int) -> int:
+        """Add two numbers."""
+        return x + y
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(mcp, "search", {"query": "add", "tags": ["nonexistent"]})
+    text = _unwrap_string_result(result)
+    assert "add" not in text or "No tools" in text
+
+
+async def test_search_without_tags_returns_all() -> None:
+    """Search without tags parameter searches the full catalog."""
+    mcp = FastMCP("Search No Tags")
+
+    @mcp.tool(tags={"math"})
+    def add(x: int, y: int) -> int:
+        """Add two numbers."""
+        return x + y
+
+    @mcp.tool(tags={"text"})
+    def greet(name: str) -> str:
+        """Say hello."""
+        return f"Hello, {name}!"
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(mcp, "search", {"query": "add hello"})
+    text = _unwrap_string_result(result)
+    assert "add" in text
+    assert "greet" in text
+
+
+async def test_search_with_untagged_filter() -> None:
+    """Search with tags=["untagged"] matches tools that have no tags."""
+    mcp = FastMCP("Search Untagged")
+
+    @mcp.tool(tags={"math"})
+    def add(x: int, y: int) -> int:
+        """Add two numbers."""
+        return x + y
+
+    @mcp.tool
+    def ping() -> str:
+        """Ping."""
+        return "pong"
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(mcp, "search", {"query": "ping add", "tags": ["untagged"]})
+    text = _unwrap_string_result(result)
+    assert "ping" in text
+    assert "add" not in text
+
+
+async def test_search_default_detail_detailed_skips_get_schema() -> None:
+    """Two-stage pattern: Search(default_detail='detailed') returns schemas inline."""
+    mcp = FastMCP("CodeMode Two-Stage")
+
+    @mcp.tool
+    def square(x: int) -> int:
+        """Compute the square."""
+        return x * x
+
+    mcp.add_transform(
+        CodeMode(
+            discovery_tools=[Search(default_detail="detailed")],
+            sandbox_provider=_UnsafeTestSandboxProvider(),
+        )
+    )
+
+    result = await _run_tool(mcp, "search", {"query": "square"})
+    text = _unwrap_string_result(result)
+    assert "### square" in text
+    assert "**Parameters**" in text
+    assert "`x` (integer, required)" in text
+
+
+async def test_search_full_detail_empty_results_returns_json() -> None:
+    """Search with detail=full and no matches returns valid JSON, not plain text."""
+    mcp = FastMCP("CodeMode Empty Full")
+
+    @mcp.tool(tags={"math"})
+    def add(x: int, y: int) -> int:
+        return x + y
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(
+        mcp,
+        "search",
+        {"query": "nonexistent", "tags": ["nonexistent"], "detail": "full"},
+    )
+    text = _unwrap_string_result(result)
+    parsed = json.loads(text)
+    assert parsed == []
+
+
+async def test_get_schema_empty_tools_list() -> None:
+    """get_schema with an empty tools list returns no-match message."""
+    mcp = FastMCP("CodeMode Empty Schema")
+
+    @mcp.tool
+    def ping() -> str:
+        return "pong"
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(mcp, "get_schema", {"tools": []})
+    text = _unwrap_string_result(result)
+    assert "No tools matched" in text
+
+
+async def test_get_schema_full_partial_match_returns_valid_json() -> None:
+    """get_schema with detail=full and missing tools returns valid JSON."""
+    mcp = FastMCP("Schema Full Partial")
+
+    @mcp.tool
+    def square(x: int) -> int:
+        """Compute the square."""
+        return x * x
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(
+        mcp, "get_schema", {"tools": ["square", "nonexistent"], "detail": "full"}
+    )
+    text = _unwrap_string_result(result)
+    parsed = json.loads(text)
+    assert isinstance(parsed, list)
+    assert parsed[0]["name"] == "square"
+    assert parsed[-1] == {"not_found": ["nonexistent"]}
+
+
+# ---------------------------------------------------------------------------
+# Search catalog size annotation
+# ---------------------------------------------------------------------------
+
+
+async def test_search_shows_catalog_size_when_results_are_subset() -> None:
+    """Search annotates results with 'N of M tools' when not all tools match."""
+    mcp = FastMCP("Search Annotation")
+
+    @mcp.tool
+    def add(x: int, y: int) -> int:
+        """Add two numbers."""
+        return x + y
+
+    @mcp.tool
+    def multiply(x: int, y: int) -> int:
+        """Multiply two numbers."""
+        return x * y
+
+    @mcp.tool
+    def greet(name: str) -> str:
+        """Say hello."""
+        return f"Hello, {name}!"
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(mcp, "search", {"query": "add numbers"})
+    text = _unwrap_string_result(result)
+    # Should show partial result count out of total catalog
+    assert "of 3 tools:" in text
+
+
+async def test_search_omits_annotation_when_all_tools_returned() -> None:
+    """Search does not annotate when results include every tool."""
+    mcp = FastMCP("Search All Match")
+
+    @mcp.tool
+    def add(x: int, y: int) -> int:
+        """Add two numbers."""
+        return x + y
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(mcp, "search", {"query": "add numbers"})
+    text = _unwrap_string_result(result)
+    assert "of" not in text or "tools:" not in text
+
+
+# ---------------------------------------------------------------------------
+# Search limit
+# ---------------------------------------------------------------------------
+
+
+async def test_search_limit_caps_results() -> None:
+    """Search with limit returns at most that many results."""
+    mcp = FastMCP("Search Limit")
+
+    @mcp.tool
+    def add(x: int, y: int) -> int:
+        """Add numbers."""
+        return x + y
+
+    @mcp.tool
+    def subtract(x: int, y: int) -> int:
+        """Subtract numbers."""
+        return x - y
+
+    @mcp.tool
+    def multiply(x: int, y: int) -> int:
+        """Multiply numbers."""
+        return x * y
+
+    mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+    result = await _run_tool(mcp, "search", {"query": "numbers", "limit": 1})
+    text = _unwrap_string_result(result)
+    assert "1 of 3 tools:" in text
+    # Only one tool line (starts with "- ")
+    tool_lines = [line for line in text.splitlines() if line.startswith("- ")]
+    assert len(tool_lines) == 1
+
+
+async def test_search_default_limit_from_constructor() -> None:
+    """Search(default_limit=N) caps results by default."""
+    mcp = FastMCP("Search Default Limit")
+
+    @mcp.tool
+    def a() -> str:
+        """Tool A."""
+        return "a"
+
+    @mcp.tool
+    def b() -> str:
+        """Tool B."""
+        return "b"
+
+    @mcp.tool
+    def c() -> str:
+        """Tool C."""
+        return "c"
+
+    mcp.add_transform(
+        CodeMode(
+            discovery_tools=[Search(default_limit=2)],
+            sandbox_provider=_UnsafeTestSandboxProvider(),
+        )
+    )
+
+    result = await _run_tool(mcp, "search", {"query": "tool"})
+    text = _unwrap_string_result(result)
+    assert "2 of 3 tools:" in text
+
+
+# ---------------------------------------------------------------------------
+# ListTools discovery tool
+# ---------------------------------------------------------------------------
+
+
+async def test_list_tools_brief() -> None:
+    """ListTools at brief detail lists all tool names and descriptions."""
+    mcp = FastMCP("ListTools Brief")
+
+    @mcp.tool
+    def add(x: int, y: int) -> int:
+        """Add two numbers."""
+        return x + y
+
+    @mcp.tool
+    def multiply(x: int, y: int) -> int:
+        """Multiply two numbers."""
+        return x * y
+
+    mcp.add_transform(
+        CodeMode(
+            discovery_tools=[ListTools()],
+            sandbox_provider=_UnsafeTestSandboxProvider(),
+        )
+    )
+
+    result = await _run_tool(mcp, "list_tools", {})
+    text = _unwrap_string_result(result)
+    assert "add" in text
+    assert "multiply" in text
+    assert "Add two numbers" in text
+    # brief should not include parameter details
+    assert "**Parameters**" not in text
+
+
+async def test_list_tools_detailed() -> None:
+    """ListTools at detailed shows parameter schemas."""
+    mcp = FastMCP("ListTools Detailed")
+
+    @mcp.tool
+    def square(x: int) -> int:
+        """Compute the square."""
+        return x * x
+
+    mcp.add_transform(
+        CodeMode(
+            discovery_tools=[ListTools(default_detail="detailed")],
+            sandbox_provider=_UnsafeTestSandboxProvider(),
+        )
+    )
+
+    result = await _run_tool(mcp, "list_tools", {})
+    text = _unwrap_string_result(result)
+    assert "### square" in text
+    assert "**Parameters**" in text
+    assert "`x` (integer, required)" in text
+
+
+async def test_list_tools_full_returns_json() -> None:
+    """ListTools at full returns valid JSON with schemas."""
+    mcp = FastMCP("ListTools Full")
+
+    @mcp.tool
+    def ping() -> str:
+        """Ping."""
+        return "pong"
+
+    mcp.add_transform(
+        CodeMode(
+            discovery_tools=[ListTools()],
+            sandbox_provider=_UnsafeTestSandboxProvider(),
+        )
+    )
+
+    result = await _run_tool(mcp, "list_tools", {"detail": "full"})
+    text = _unwrap_string_result(result)
+    parsed = json.loads(text)
+    assert isinstance(parsed, list)
+    assert parsed[0]["name"] == "ping"
+
+
+async def test_list_tools_empty_catalog() -> None:
+    """ListTools with no tools returns no-match message."""
+    mcp = FastMCP("ListTools Empty")
+
+    mcp.add_transform(
+        CodeMode(
+            discovery_tools=[ListTools()],
+            sandbox_provider=_UnsafeTestSandboxProvider(),
+        )
+    )
+
+    result = await _run_tool(mcp, "list_tools", {})
+    text = _unwrap_string_result(result)
+    assert "No tools matched" in text
diff --git a/tests/experimental/transforms/test_code_mode_serialization.py b/tests/experimental/transforms/test_code_mode_serialization.py
new file mode 100644
index 0000000..a589ad7
--- /dev/null
+++ b/tests/experimental/transforms/test_code_mode_serialization.py
@@ -0,0 +1,197 @@
+from typing import Any
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.server.transforms.search.base import (
+    _schema_section,
+    _schema_type,
+    serialize_tools_for_output_markdown,
+)
+
+# ---------------------------------------------------------------------------
+# _schema_type unit tests
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "schema,expected",
+    [
+        ({"type": "string"}, "string"),
+        ({"type": "integer"}, "integer"),
+        ({"type": "boolean"}, "boolean"),
+        ({"type": "null"}, "null"),
+        ({"type": "array", "items": {"type": "string"}}, "string[]"),
+        ({"type": "array", "items": {"type": "integer"}}, "integer[]"),
+        ({"type": "array"}, "any[]"),
+        ({"$ref": "#/$defs/Foo"}, "object"),
+        ({"properties": {"x": {"type": "int"}}}, "object"),
+        ({}, "any"),
+        (None, "any"),
+        ("not a dict", "any"),
+    ],
+)
+def test_schema_type_basic(schema: Any, expected: str) -> None:
+    assert _schema_type(schema) == expected
+
+
+@pytest.mark.parametrize(
+    "schema,expected",
+    [
+        ({"anyOf": [{"type": "string"}, {"type": "null"}]}, "string?"),
+        ({"anyOf": [{"type": "string"}, {"type": "integer"}]}, "string | integer"),
+        (
+            {"anyOf": [{"type": "string"}, {"type": "integer"}, {"type": "null"}]},
+            "string | integer?",
+        ),
+        ({"anyOf": [{"type": "null"}]}, "null"),
+        ({"anyOf": []}, "any"),
+        ({"oneOf": [{"type": "string"}, {"type": "null"}]}, "string?"),
+        ({"oneOf": [{"type": "string"}, {"type": "integer"}]}, "string | integer"),
+        ({"allOf": [{"type": "object"}]}, "object"),
+        ({"allOf": [{"$ref": "#/$defs/Foo"}, {"$ref": "#/$defs/Bar"}]}, "object"),
+    ],
+)
+def test_schema_type_unions(schema: Any, expected: str) -> None:
+    assert _schema_type(schema) == expected
+
+
+# ---------------------------------------------------------------------------
+# _schema_section unit tests
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "schema,expected_lines",
+    [
+        (None, ["**Parameters**", "- `value` (any)"]),
+        ("string", ["**Parameters**", "- `value` (any)"]),
+        ({"type": "string"}, ["**Parameters**", "- `value` (string)"]),
+        (
+            {"type": "object", "properties": {}},
+            ["**Parameters**", "*(no parameters)*"],
+        ),
+    ],
+)
+def test_schema_section_fallbacks(schema: Any, expected_lines: list[str]) -> None:
+    assert _schema_section(schema, "Parameters") == expected_lines
+
+
+def test_schema_section_lists_fields_with_required_marker() -> None:
+    schema = {
+        "type": "object",
+        "properties": {
+            "name": {"type": "string"},
+            "age": {"type": "integer"},
+        },
+        "required": ["name"],
+    }
+    lines = _schema_section(schema, "Parameters")
+    assert lines[0] == "**Parameters**"
+    assert "- `name` (string, required)" in lines
+    assert "- `age` (integer)" in lines
+
+
+# ---------------------------------------------------------------------------
+# serialize_tools_for_output_markdown unit tests
+# ---------------------------------------------------------------------------
+
+
+def test_serialize_tools_for_output_markdown_empty_list() -> None:
+    assert serialize_tools_for_output_markdown([]) == "No tools matched the query."
+
+
+async def test_serialize_tools_for_output_markdown_basic_tool() -> None:
+    mcp = FastMCP("MD Basic")
+
+    @mcp.tool
+    def square(x: int) -> int:
+        """Compute the square of a number."""
+        return x * x
+
+    tools = await mcp.list_tools()
+    result = serialize_tools_for_output_markdown(tools)
+
+    assert "### square" in result
+    assert "Compute the square of a number." in result
+    assert "**Parameters**" in result
+    assert "`x` (integer, required)" in result
+
+
+async def test_serialize_tools_for_output_markdown_omits_output_section_when_no_schema() -> (
+    None
+):
+    mcp = FastMCP("MD No Output")
+
+    @mcp.tool
+    def ping() -> None:
+        pass
+
+    tools = await mcp.list_tools()
+    result = serialize_tools_for_output_markdown(tools)
+
+    assert "**Returns**" not in result
+
+
+async def test_serialize_tools_for_output_markdown_includes_output_section_when_schema_present() -> (
+    None
+):
+    mcp = FastMCP("MD With Output")
+
+    @mcp.tool
+    def double(x: int) -> int:
+        return x * 2
+
+    tools = await mcp.list_tools()
+    result = serialize_tools_for_output_markdown(tools)
+
+    assert "**Returns**" in result
+
+
+async def test_serialize_tools_for_output_markdown_omits_description_when_absent() -> (
+    None
+):
+    mcp = FastMCP("MD No Desc")
+
+    @mcp.tool
+    def ping() -> None:
+        pass
+
+    tools = await mcp.list_tools()
+    result = serialize_tools_for_output_markdown(tools)
+
+    assert "### ping" in result
+
+
+async def test_serialize_tools_for_output_markdown_optional_field_uses_question_mark() -> (
+    None
+):
+    mcp = FastMCP("MD Optional")
+
+    @mcp.tool
+    def greet(name: str, greeting: str | None = None) -> str:
+        return f"{greeting or 'Hello'}, {name}!"
+
+    tools = await mcp.list_tools()
+    result = serialize_tools_for_output_markdown(tools)
+
+    assert "`greeting` (string?)" in result
+
+
+async def test_serialize_tools_for_output_markdown_multiple_tools_separated() -> None:
+    mcp = FastMCP("MD Multi")
+
+    @mcp.tool
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    @mcp.tool
+    def subtract(a: int, b: int) -> int:
+        return a - b
+
+    tools = await mcp.list_tools()
+    result = serialize_tools_for_output_markdown(tools)
+
+    assert "### add" in result
+    assert "### subtract" in result
+    assert "\n\n" in result
diff --git a/tests/fs/test_discovery.py b/tests/fs/test_discovery.py
new file mode 100644
index 0000000..4f88bd3
--- /dev/null
+++ b/tests/fs/test_discovery.py
@@ -0,0 +1,586 @@
+"""Tests for filesystem discovery module."""
+
+import sys
+from pathlib import Path
+
+from fastmcp.prompts.base import Prompt
+from fastmcp.resources.base import Resource
+from fastmcp.resources.template import FunctionResourceTemplate, ResourceTemplate
+from fastmcp.server.providers.filesystem_discovery import (
+    discover_and_import,
+    discover_files,
+    extract_components,
+    import_module_from_file,
+)
+from fastmcp.tools import FunctionTool
+from fastmcp.tools.base import Tool
+
+
+class TestDiscoverFiles:
+    """Tests for discover_files function."""
+
+    def test_discover_files_empty_dir(self, tmp_path: Path):
+        """Should return empty list for empty directory."""
+        files = discover_files(tmp_path)
+        assert files == []
+
+    def test_discover_files_nonexistent_dir(self, tmp_path: Path):
+        """Should return empty list for nonexistent directory."""
+        nonexistent = tmp_path / "does_not_exist"
+        files = discover_files(nonexistent)
+        assert files == []
+
+    def test_discover_files_single_file(self, tmp_path: Path):
+        """Should find a single Python file."""
+        py_file = tmp_path / "test.py"
+        py_file.write_text("# test")
+
+        files = discover_files(tmp_path)
+        assert files == [py_file]
+
+    def test_discover_files_skips_init(self, tmp_path: Path):
+        """Should skip __init__.py files."""
+        init_file = tmp_path / "__init__.py"
+        init_file.write_text("# init")
+        py_file = tmp_path / "test.py"
+        py_file.write_text("# test")
+
+        files = discover_files(tmp_path)
+        assert files == [py_file]
+
+    def test_discover_files_recursive(self, tmp_path: Path):
+        """Should find files in subdirectories."""
+        subdir = tmp_path / "subdir"
+        subdir.mkdir()
+        file1 = tmp_path / "a.py"
+        file2 = subdir / "b.py"
+        file1.write_text("# a")
+        file2.write_text("# b")
+
+        files = discover_files(tmp_path)
+        assert sorted(files) == sorted([file1, file2])
+
+    def test_discover_files_skips_pycache(self, tmp_path: Path):
+        """Should skip __pycache__ directories."""
+        pycache = tmp_path / "__pycache__"
+        pycache.mkdir()
+        cache_file = pycache / "test.py"
+        cache_file.write_text("# cache")
+        py_file = tmp_path / "test.py"
+        py_file.write_text("# test")
+
+        files = discover_files(tmp_path)
+        assert files == [py_file]
+
+    def test_discover_files_sorted(self, tmp_path: Path):
+        """Files should be returned in sorted order."""
+        (tmp_path / "z.py").write_text("# z")
+        (tmp_path / "a.py").write_text("# a")
+        (tmp_path / "m.py").write_text("# m")
+
+        files = discover_files(tmp_path)
+        names = [f.name for f in files]
+        assert names == ["a.py", "m.py", "z.py"]
+
+
+class TestImportModuleFromFile:
+    """Tests for import_module_from_file function."""
+
+    def test_import_simple_module(self, tmp_path: Path):
+        """Should import a simple module."""
+        py_file = tmp_path / "simple.py"
+        py_file.write_text("VALUE = 42")
+
+        module = import_module_from_file(py_file)
+        assert module.VALUE == 42
+
+    def test_import_module_with_function(self, tmp_path: Path):
+        """Should import a module with functions."""
+        py_file = tmp_path / "funcs.py"
+        py_file.write_text(
+            """\
+def greet(name):
+    return f"Hello, {name}!"
+"""
+        )
+
+        module = import_module_from_file(py_file)
+        assert module.greet("World") == "Hello, World!"
+
+    def test_import_module_with_imports(self, tmp_path: Path):
+        """Should handle modules with standard library imports."""
+        py_file = tmp_path / "with_imports.py"
+        py_file.write_text(
+            """\
+import os
+import sys
+
+def get_cwd():
+    return os.getcwd()
+"""
+        )
+
+        module = import_module_from_file(py_file)
+        assert callable(module.get_cwd)
+
+    def test_import_as_package_with_init(self, tmp_path: Path):
+        """Should import as package when __init__.py exists."""
+        # Create package structure (use unique name to avoid module caching)
+        pkg = tmp_path / "testpkg_init"
+        pkg.mkdir()
+        (pkg / "__init__.py").write_text("PKG_VAR = 'package'")
+        module_file = pkg / "module.py"
+        module_file.write_text("MODULE_VAR = 'module'")
+
+        module = import_module_from_file(module_file)
+        assert module.MODULE_VAR == "module"
+
+    def test_import_with_relative_import(self, tmp_path: Path):
+        """Should support relative imports when in a package."""
+        # Create package with relative import (use unique name to avoid module caching)
+        pkg = tmp_path / "testpkg_relative"
+        pkg.mkdir()
+        (pkg / "__init__.py").write_text("")
+        (pkg / "helper.py").write_text("HELPER_VALUE = 123")
+        (pkg / "main.py").write_text(
+            """\
+from .helper import HELPER_VALUE
+
+MAIN_VALUE = HELPER_VALUE * 2
+"""
+        )
+
+        module = import_module_from_file(pkg / "main.py")
+        assert module.MAIN_VALUE == 246
+
+    def test_import_package_module_reload(self, tmp_path: Path):
+        """Re-importing a package module should return updated content."""
+        # Create package (use unique name to avoid conflicts)
+        pkg = tmp_path / "testpkg_reload"
+        pkg.mkdir()
+        (pkg / "__init__.py").write_text("")
+        module_file = pkg / "reloadable.py"
+        module_file.write_text("VALUE = 'original'")
+
+        # First import
+        module = import_module_from_file(module_file)
+        assert module.VALUE == "original"
+
+        # Modify the file
+        module_file.write_text("VALUE = 'updated'")
+
+        # Re-import should see the updated value
+        module = import_module_from_file(module_file)
+        assert module.VALUE == "updated"
+
+
+class TestExtractComponents:
+    """Tests for extract_components function."""
+
+    def test_extract_no_components(self, tmp_path: Path):
+        """Should return empty list for module with no components."""
+        py_file = tmp_path / "plain.py"
+        py_file.write_text(
+            """\
+def plain_function():
+    pass
+
+SOME_VAR = 42
+"""
+        )
+
+        module = import_module_from_file(py_file)
+        components = extract_components(module)
+        assert components == []
+
+    def test_extract_tool_component(self, tmp_path: Path):
+        """Should extract Tool objects."""
+        py_file = tmp_path / "tools.py"
+        py_file.write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+"""
+        )
+
+        module = import_module_from_file(py_file)
+        components = extract_components(module)
+
+        assert len(components) == 1
+        component = components[0]
+        assert isinstance(component, FunctionTool)
+        assert component.name == "greet"
+
+    def test_extract_multiple_components(self, tmp_path: Path):
+        """Should extract multiple component types."""
+        py_file = tmp_path / "multi.py"
+        py_file.write_text(
+            """\
+from fastmcp.tools import tool
+from fastmcp.resources import resource
+from fastmcp.prompts import prompt
+
+@tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+@resource("config://app")
+def get_config() -> dict:
+    return {}
+
+@prompt
+def analyze(topic: str) -> str:
+    return f"Analyze: {topic}"
+"""
+        )
+
+        module = import_module_from_file(py_file)
+        components = extract_components(module)
+
+        assert len(components) == 3
+        types = {type(c).__name__ for c in components}
+        assert types == {"FunctionTool", "FunctionResource", "FunctionPrompt"}
+
+    def test_extract_skips_private_components(self, tmp_path: Path):
+        """Should skip private components (those starting with _)."""
+        py_file = tmp_path / "private.py"
+        py_file.write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool
+def public_tool() -> str:
+    return "public"
+
+# The module attribute starts with _, so it's skipped during discovery
+@tool("private_tool_name")
+def _private_tool() -> str:
+    return "private"
+"""
+        )
+
+        module = import_module_from_file(py_file)
+        components = extract_components(module)
+
+        # Only public_tool should be found (_private_tool starts with _, so skipped)
+        assert len(components) == 1
+        component = components[0]
+        assert component.name == "public_tool"
+
+    def test_extract_resource_template(self, tmp_path: Path):
+        """Should extract ResourceTemplate objects."""
+        py_file = tmp_path / "templates.py"
+        py_file.write_text(
+            """\
+from fastmcp.resources import resource
+
+@resource("users://{user_id}/profile")
+def get_profile(user_id: str) -> dict:
+    return {"id": user_id}
+"""
+        )
+
+        module = import_module_from_file(py_file)
+        components = extract_components(module)
+
+        assert len(components) == 1
+        component = components[0]
+        assert isinstance(component, FunctionResourceTemplate)
+        assert component.uri_template == "users://{user_id}/profile"
+
+
+class TestDiscoverAndImport:
+    """Tests for discover_and_import function."""
+
+    def test_discover_and_import_empty(self, tmp_path: Path):
+        """Should return empty result for empty directory."""
+        result = discover_and_import(tmp_path)
+        assert result.components == []
+        assert result.failed_files == {}
+
+    def test_discover_and_import_with_tools(self, tmp_path: Path):
+        """Should discover and import tools."""
+        tools_dir = tmp_path / "tools"
+        tools_dir.mkdir()
+        (tools_dir / "greet.py").write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+"""
+        )
+
+        result = discover_and_import(tmp_path)
+
+        assert len(result.components) == 1
+        file_path, component = result.components[0]
+        assert file_path.name == "greet.py"
+        assert isinstance(component, FunctionTool)
+        assert component.name == "greet"
+
+    def test_discover_and_import_skips_bad_imports(self, tmp_path: Path):
+        """Should skip files that fail to import and track them."""
+        (tmp_path / "good.py").write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool
+def good_tool() -> str:
+    return "good"
+"""
+        )
+        (tmp_path / "bad.py").write_text(
+            """\
+import nonexistent_module_xyz123
+
+def bad_function():
+    pass
+"""
+        )
+
+        result = discover_and_import(tmp_path)
+
+        # Only good.py should be imported
+        assert len(result.components) == 1
+        _, component = result.components[0]
+        assert component.name == "good_tool"
+
+        # bad.py should be in failed_files
+        assert len(result.failed_files) == 1
+        failed_path = tmp_path / "bad.py"
+        assert failed_path in result.failed_files
+        assert "nonexistent_module_xyz123" in result.failed_files[failed_path]
+
+
+class TestExtractComponentsVersion:
+    """Tests for version propagation in extract_components."""
+
+    def test_extract_tool_preserves_version(self, tmp_path: Path):
+        """Tools discovered from files should have their version attribute set."""
+        tool_file = tmp_path / "versioned_tool.py"
+        tool_file.write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool(version="1.0", description="v1")
+def greet_v1(name: str) -> str:
+    return f"Hi {name}"
+
+@tool(version="2.0", description="v2")
+def greet_v2(name: str) -> str:
+    return f"Hey {name}"
+"""
+        )
+
+        module = import_module_from_file(tool_file)
+        components = extract_components(module)
+
+        tools = [c for c in components if isinstance(c, Tool)]
+        assert len(tools) == 2
+
+        versions = {t.version for t in tools}
+        assert versions == {"1.0", "2.0"}
+
+    def test_extract_resource_preserves_version(self, tmp_path: Path):
+        """Resources discovered from files should have their version attribute set."""
+        resource_file = tmp_path / "versioned_resource.py"
+        resource_file.write_text(
+            """\
+from fastmcp.resources import resource
+
+@resource("data://config", version="1.0", name="config", description="v1 config")
+def config_v1() -> str:
+    return '{"theme": "light"}'
+"""
+        )
+
+        module = import_module_from_file(resource_file)
+        components = extract_components(module)
+
+        resources = [c for c in components if isinstance(c, Resource)]
+        assert len(resources) == 1
+        assert resources[0].version == "1.0"
+
+    def test_extract_resource_template_preserves_version(self, tmp_path: Path):
+        """Resource templates discovered from files should have their version set."""
+        template_file = tmp_path / "versioned_template.py"
+        template_file.write_text(
+            """\
+from fastmcp.resources import resource
+
+@resource("users://{user_id}/profile", version="2.0", description="v2 profile")
+def get_profile(user_id: str) -> dict:
+    return {"id": user_id}
+"""
+        )
+
+        module = import_module_from_file(template_file)
+        components = extract_components(module)
+
+        templates = [c for c in components if isinstance(c, ResourceTemplate)]
+        assert len(templates) == 1
+        assert templates[0].version == "2.0"
+
+    def test_extract_prompt_preserves_version(self, tmp_path: Path):
+        """Prompts discovered from files should have their version attribute set."""
+        prompt_file = tmp_path / "versioned_prompt.py"
+        prompt_file.write_text(
+            """\
+from fastmcp.prompts import prompt
+
+@prompt(name="summarize", version="1.0", description="v1 prompt")
+def summarize_v1(text: str) -> str:
+    return f"Summarize: {text}"
+"""
+        )
+
+        module = import_module_from_file(prompt_file)
+        components = extract_components(module)
+
+        prompts = [c for c in components if isinstance(c, Prompt)]
+        assert len(prompts) == 1
+        assert prompts[0].version == "1.0"
+
+    def test_discovered_tool_meta_includes_version(self, tmp_path: Path):
+        """get_meta() should include version for tools discovered via filesystem."""
+        tool_file = tmp_path / "meta_tool.py"
+        tool_file.write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool(name="echo", version="3.0", description="Echo tool")
+def echo(msg: str) -> str:
+    return msg
+"""
+        )
+
+        module = import_module_from_file(tool_file)
+        components = extract_components(module)
+
+        tool = components[0]
+        meta = tool.get_meta()
+        assert meta["fastmcp"]["version"] == "3.0"
+
+    def test_unversioned_components_have_no_version(self, tmp_path: Path):
+        """Components without version should have version=None."""
+        tool_file = tmp_path / "no_version_tool.py"
+        tool_file.write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool(description="No version")
+def my_tool(x: str) -> str:
+    return x
+"""
+        )
+
+        module = import_module_from_file(tool_file)
+        components = extract_components(module)
+
+        assert len(components) == 1
+        assert components[0].version is None
+        meta = components[0].get_meta()
+        assert "version" not in meta["fastmcp"]
+
+
+class TestImportMachineryFixes:
+    """Tests for import machinery correctness: sys.path cleanup, sys.modules safety, package root boundary."""
+
+    def test_syspath_not_polluted_after_import(self, tmp_path: Path):
+        """sys.path should not contain the file's parent after import_module_from_file returns."""
+        (tmp_path / "mymod.py").write_text("VALUE = 1")
+        path_before = list(sys.path)
+        import_module_from_file(tmp_path / "mymod.py")
+        assert sys.path == path_before
+
+    def test_syspath_not_polluted_after_package_import(self, tmp_path: Path):
+        """sys.path should not contain the package root's parent after a package import."""
+        pkg = tmp_path / "mypkg_syspath"
+        pkg.mkdir()
+        (pkg / "__init__.py").write_text("")
+        (pkg / "mod.py").write_text("VALUE = 2")
+        path_before = list(sys.path)
+        import_module_from_file(pkg / "mod.py", provider_root=tmp_path)
+        assert sys.path == path_before
+
+    def test_stdlib_not_shadowed_by_same_named_file(self, tmp_path: Path):
+        """A provider file named json.py must not overwrite sys.modules['json']."""
+        import json as stdlib_json
+
+        saved = sys.modules["json"]
+        try:
+            (tmp_path / "json.py").write_text(
+                "from fastmcp.tools import tool\n@tool\ndef parse(): return 'provider'"
+            )
+            import_module_from_file(tmp_path / "json.py")
+            assert sys.modules.get("json") is stdlib_json
+        finally:
+            sys.modules["json"] = saved
+
+    def test_same_stem_files_get_independent_modules(self, tmp_path: Path):
+        """Two files with the same stem in different directories must not collide in sys.modules.
+
+        The first-imported file keeps the bare stem key; the second gets a private key.
+        Both modules must be independently accessible with correct content.
+        """
+        dir_a = tmp_path / "a"
+        dir_b = tmp_path / "b"
+        dir_a.mkdir()
+        dir_b.mkdir()
+        (dir_a / "helpers.py").write_text("ORIGIN = 'a'")
+        (dir_b / "helpers.py").write_text("ORIGIN = 'b'")
+
+        mod_a = import_module_from_file(dir_a / "helpers.py")
+        mod_b = import_module_from_file(dir_b / "helpers.py")
+
+        assert mod_a.ORIGIN == "a"
+        assert mod_b.ORIGIN == "b"
+        # The first module retains the bare stem key; the second uses a private key.
+        # They must be distinct objects — the second import must not have clobbered the first.
+        assert mod_a is not mod_b
+        assert sys.modules.get("helpers") is not mod_b
+
+    def test_package_root_bounded_by_provider_root(self, tmp_path: Path):
+        """When the provider root is nested inside a larger package, import_module_from_file
+        with provider_root must not escape into ancestor packages.
+
+        The generated module name should be relative to the provider root (e.g. "myprovider.tools"),
+        not to an ancestor package (e.g. "myproject.myprovider.tools"), and tmp_path (the
+        ancestor's parent) must not be added to sys.path.
+        """
+        # Use a name that won't collide with any installed package
+        project = tmp_path / "myproject"
+        project.mkdir()
+        (project / "__init__.py").write_text("")
+        provider = project / "myprovider"
+        provider.mkdir()
+        (provider / "__init__.py").write_text("")
+        (provider / "tools.py").write_text("VALUE = 42")
+
+        path_before = set(sys.path)
+        mod = import_module_from_file(provider / "tools.py", provider_root=provider)
+        path_after = set(sys.path)
+
+        # Module was correctly imported
+        assert mod.VALUE == 42
+        # sys.path should not contain tmp_path (the ancestor's grandparent);
+        # that would only happen if the package root escaped past the provider boundary
+        assert str(tmp_path) not in (path_after - path_before)
+        # The module name is bounded to the provider root, not "myproject.myprovider.tools"
+        assert mod.__name__ == "myprovider.tools"
+
+    def test_non_package_reload_returns_updated_content(self, tmp_path: Path):
+        """Re-importing a non-package file should reflect file changes (exec_module path)."""
+        f = tmp_path / "reloadable_np.py"
+        f.write_text("VALUE = 'original'")
+        mod = import_module_from_file(f)
+        assert mod.VALUE == "original"
+
+        f.write_text("VALUE = 'updated'")
+        mod2 = import_module_from_file(f)
+        assert mod2.VALUE == "updated"
diff --git a/tests/fs/test_provider.py b/tests/fs/test_provider.py
new file mode 100644
index 0000000..b115c5e
--- /dev/null
+++ b/tests/fs/test_provider.py
@@ -0,0 +1,656 @@
+"""Tests for FileSystemProvider."""
+
+import asyncio
+import time
+from pathlib import Path
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.providers import FileSystemProvider
+
+
+class TestFileSystemProvider:
+    """Tests for FileSystemProvider."""
+
+    def test_provider_empty_directory(self, tmp_path: Path):
+        """Provider should work with empty directory."""
+        provider = FileSystemProvider(tmp_path)
+        assert repr(provider).startswith("FileSystemProvider")
+
+    def test_provider_discovers_tools(self, tmp_path: Path):
+        """Provider should discover @tool decorated functions."""
+        tools_dir = tmp_path / "tools"
+        tools_dir.mkdir()
+        (tools_dir / "greet.py").write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool
+def greet(name: str) -> str:
+    '''Greet someone by name.'''
+    return f"Hello, {name}!"
+"""
+        )
+
+        provider = FileSystemProvider(tmp_path)
+
+        # Check tool was registered
+        assert len(provider._components) == 1
+
+    def test_provider_discovers_resources(self, tmp_path: Path):
+        """Provider should discover @resource decorated functions."""
+        (tmp_path / "config.py").write_text(
+            """\
+from fastmcp.resources import resource
+
+@resource("config://app")
+def get_config() -> dict:
+    '''Get app config.'''
+    return {"setting": "value"}
+"""
+        )
+
+        provider = FileSystemProvider(tmp_path)
+        assert len(provider._components) == 1
+
+    def test_provider_discovers_resource_templates(self, tmp_path: Path):
+        """Provider should discover resource templates."""
+        (tmp_path / "users.py").write_text(
+            """\
+from fastmcp.resources import resource
+
+@resource("users://{user_id}/profile")
+def get_profile(user_id: str) -> dict:
+    '''Get user profile.'''
+    return {"id": user_id}
+"""
+        )
+
+        provider = FileSystemProvider(tmp_path)
+        assert len(provider._components) == 1
+
+    def test_provider_discovers_prompts(self, tmp_path: Path):
+        """Provider should discover @prompt decorated functions."""
+        (tmp_path / "analyze.py").write_text(
+            """\
+from fastmcp.prompts import prompt
+
+@prompt
+def analyze(topic: str) -> list:
+    '''Analyze a topic.'''
+    return [{"role": "user", "content": f"Analyze: {topic}"}]
+"""
+        )
+
+        provider = FileSystemProvider(tmp_path)
+        assert len(provider._components) == 1
+
+    def test_provider_discovers_multiple_in_one_file(self, tmp_path: Path):
+        """Provider should discover multiple components in one file."""
+        (tmp_path / "multi.py").write_text(
+            """\
+from fastmcp.tools import tool
+from fastmcp.resources import resource
+
+@tool
+def tool1() -> str:
+    return "tool1"
+
+@tool
+def tool2() -> str:
+    return "tool2"
+
+@resource("config://app")
+def get_config() -> dict:
+    return {}
+"""
+        )
+
+        provider = FileSystemProvider(tmp_path)
+        assert len(provider._components) == 3
+
+    def test_provider_skips_undecorated_files(self, tmp_path: Path):
+        """Provider should skip files with no decorated functions."""
+        (tmp_path / "utils.py").write_text(
+            """\
+def helper_function():
+    return "helper"
+
+SOME_CONSTANT = 42
+"""
+        )
+        (tmp_path / "tool.py").write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool
+def my_tool() -> str:
+    return "tool"
+"""
+        )
+
+        provider = FileSystemProvider(tmp_path)
+        # Only the tool should be registered
+        assert len(provider._components) == 1
+
+
+class TestFileSystemProviderReloadMode:
+    """Tests for FileSystemProvider reload mode."""
+
+    def test_reload_false_caches_at_init(self, tmp_path: Path):
+        """With reload=False, components are cached at init."""
+        (tmp_path / "tool.py").write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool
+def original() -> str:
+    return "original"
+"""
+        )
+
+        provider = FileSystemProvider(tmp_path, reload=False)
+        assert len(provider._components) == 1
+
+        # Add another file - should NOT be picked up
+        (tmp_path / "tool2.py").write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool
+def added() -> str:
+    return "added"
+"""
+        )
+
+        # Still only one component
+        assert len(provider._components) == 1
+
+    async def test_reload_true_rescans(self, tmp_path: Path):
+        """With reload=True, components are rescanned on each request."""
+        (tmp_path / "tool.py").write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool
+def original() -> str:
+    return "original"
+"""
+        )
+
+        provider = FileSystemProvider(tmp_path, reload=True)
+
+        # Always loaded once at init (to catch errors early)
+        assert provider._loaded
+        assert len(provider._components) == 1
+
+        # Add another file - should be picked up on next read
+        (tmp_path / "tool2.py").write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool
+def added() -> str:
+    return "added"
+"""
+        )
+
+        # With reload=True, reading triggers a re-scan
+        tools = await provider._list_tools()
+        assert len(tools) == 2
+
+    async def test_warning_deduplication_same_file(self, tmp_path: Path, capsys):
+        """Warnings for the same broken file should not repeat."""
+        bad_file = tmp_path / "bad.py"
+        bad_file.write_text("1/0  # division by zero")
+
+        provider = FileSystemProvider(tmp_path, reload=True)
+
+        # First load - should warn
+        captured = capsys.readouterr()
+        # Check for warning indicator (rich may truncate long paths)
+        assert "WARNING" in captured.err and "Failed to import" in captured.err
+
+        # Second load (same file, unchanged) - should NOT warn again
+        await provider._list_tools()
+        captured = capsys.readouterr()
+        assert "Failed to import" not in captured.err
+
+    async def test_warning_on_file_change(self, tmp_path: Path, capsys):
+        """Warnings should reappear when a broken file changes."""
+        bad_file = tmp_path / "bad.py"
+        bad_file.write_text("1/0  # division by zero")
+
+        provider = FileSystemProvider(tmp_path, reload=True)
+
+        # First load - should warn
+        captured = capsys.readouterr()
+        # Check for warning indicator (rich may truncate long paths)
+        assert "WARNING" in captured.err and "Failed to import" in captured.err
+
+        # Modify the file (different error) - need to ensure mtime changes
+        time.sleep(0.01)  # Ensure mtime differs
+        bad_file.write_text("syntax error here !!!")
+
+        # Next load - should warn again (file changed)
+        await provider._list_tools()
+        captured = capsys.readouterr()
+        # Check for warning indicator (rich may truncate long paths)
+        assert "WARNING" in captured.err and "Failed to import" in captured.err
+
+    async def test_warning_cleared_when_fixed(self, tmp_path: Path, capsys):
+        """Warnings should clear when a file is fixed, and reappear if broken again."""
+        bad_file = tmp_path / "tool.py"
+        bad_file.write_text("1/0  # broken")
+
+        provider = FileSystemProvider(tmp_path, reload=True)
+
+        # First load - should warn
+        captured = capsys.readouterr()
+        # Check for warning indicator (rich may truncate long paths)
+        assert "WARNING" in captured.err and "Failed to import" in captured.err
+
+        # Fix the file
+        time.sleep(0.01)
+        bad_file.write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool
+def my_tool() -> str:
+    return "fixed"
+"""
+        )
+
+        # Load again - should NOT warn, file is fixed
+        await provider._list_tools()
+        captured = capsys.readouterr()
+        assert "Failed to import" not in captured.err
+        assert len(provider._components) == 1
+
+        # Break it again
+        time.sleep(0.01)
+        bad_file.write_text("1/0  # broken again")
+
+        # Should warn again
+        await provider._list_tools()
+        captured = capsys.readouterr()
+        # Check for warning indicator (rich may truncate long paths)
+        assert "WARNING" in captured.err and "Failed to import" in captured.err
+
+
+class TestFileSystemProviderReloadRace:
+    """Test that concurrent readers don't see empty components during reload."""
+
+    async def test_concurrent_reader_never_sees_empty(self, tmp_path: Path):
+        """A reader during reload should see either old or new components, never empty."""
+        (tmp_path / "tool.py").write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool
+def my_tool() -> str:
+    return "hello"
+"""
+        )
+
+        provider = FileSystemProvider(tmp_path, reload=True)
+        assert len(await provider._list_tools()) == 1
+
+        observed_empty = False
+
+        async def reader():
+            nonlocal observed_empty
+            for _ in range(20):
+                tools = await provider._list_tools()
+                if len(tools) == 0:
+                    observed_empty = True
+                await asyncio.sleep(0)
+
+        async def reloader():
+            for _ in range(5):
+                provider._loaded = False
+                await provider._list_tools()  # triggers reload
+                await asyncio.sleep(0)
+
+        await asyncio.gather(reader(), reloader())
+        assert not observed_empty, "Reader saw empty components during reload"
+
+
+class TestFileSystemProviderIntegration:
+    """Integration tests with FastMCP server."""
+
+    async def test_provider_with_fastmcp_server(self, tmp_path: Path):
+        """FileSystemProvider should work with FastMCP server."""
+        (tmp_path / "greet.py").write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool
+def greet(name: str) -> str:
+    '''Greet someone.'''
+    return f"Hello, {name}!"
+"""
+        )
+
+        provider = FileSystemProvider(tmp_path)
+        mcp = FastMCP("TestServer", providers=[provider])
+
+        async with Client(mcp) as client:
+            # List tools
+            tools = await client.list_tools()
+            assert len(tools) == 1
+            assert tools[0].name == "greet"
+
+            # Call tool
+            result = await client.call_tool("greet", {"name": "World"})
+            assert "Hello, World!" in str(result)
+
+    async def test_provider_with_resources(self, tmp_path: Path):
+        """FileSystemProvider should work with resources."""
+        (tmp_path / "config.py").write_text(
+            """\
+from fastmcp.resources import resource
+
+@resource("config://app")
+def get_config() -> str:
+    '''Get app config.'''
+    return '{"version": "1.0"}'
+"""
+        )
+
+        provider = FileSystemProvider(tmp_path)
+        mcp = FastMCP("TestServer", providers=[provider])
+
+        async with Client(mcp) as client:
+            # List resources
+            resources = await client.list_resources()
+            assert len(resources) == 1
+            assert str(resources[0].uri) == "config://app"
+
+            # Read resource
+            result = await client.read_resource("config://app")
+            assert "1.0" in str(result)
+
+    async def test_provider_with_resource_templates(self, tmp_path: Path):
+        """FileSystemProvider should work with resource templates."""
+        (tmp_path / "users.py").write_text(
+            """\
+from fastmcp.resources import resource
+
+@resource("users://{user_id}/profile")
+def get_profile(user_id: str) -> str:
+    '''Get user profile.'''
+    return f'{{"id": "{user_id}", "name": "User {user_id}"}}'
+"""
+        )
+
+        provider = FileSystemProvider(tmp_path)
+        mcp = FastMCP("TestServer", providers=[provider])
+
+        async with Client(mcp) as client:
+            # List templates
+            templates = await client.list_resource_templates()
+            assert len(templates) == 1
+
+            # Read with parameter
+            result = await client.read_resource("users://123/profile")
+            assert "123" in str(result)
+
+    async def test_provider_with_prompts(self, tmp_path: Path):
+        """FileSystemProvider should work with prompts."""
+        (tmp_path / "analyze.py").write_text(
+            """\
+from fastmcp.prompts import prompt
+
+@prompt
+def analyze(topic: str) -> str:
+    '''Analyze a topic.'''
+    return f"Please analyze: {topic}"
+"""
+        )
+
+        provider = FileSystemProvider(tmp_path)
+        mcp = FastMCP("TestServer", providers=[provider])
+
+        async with Client(mcp) as client:
+            # List prompts
+            prompts = await client.list_prompts()
+            assert len(prompts) == 1
+            assert prompts[0].name == "analyze"
+
+            # Get prompt
+            result = await client.get_prompt("analyze", {"topic": "Python"})
+            assert "Python" in str(result)
+
+    async def test_nested_directory_structure(self, tmp_path: Path):
+        """FileSystemProvider should work with nested directories."""
+        # Create nested structure
+        tools = tmp_path / "tools"
+        tools.mkdir()
+        (tools / "greet.py").write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+"""
+        )
+
+        payments = tools / "payments"
+        payments.mkdir()
+        (payments / "charge.py").write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool
+def charge(amount: float) -> str:
+    return f"Charged ${amount}"
+"""
+        )
+
+        provider = FileSystemProvider(tmp_path)
+        mcp = FastMCP("TestServer", providers=[provider])
+
+        async with Client(mcp) as client:
+            tools_list = await client.list_tools()
+            assert len(tools_list) == 2
+            names = {t.name for t in tools_list}
+            assert names == {"greet", "charge"}
+
+    async def test_mounted_servers_with_same_package_and_module_name(
+        self, tmp_path: Path
+    ):
+        """Two providers sharing a package/module path should not collide.
+
+        Reproduces the exact scenario from the bug report: both providers have a
+        `components/tools.py` package. Without isolation the second provider
+        reuses the first's cached module and `list_tools` returns the first
+        server's tool twice.
+        """
+        for server_name, tool_name in [
+            ("server1", "server1_tool"),
+            ("server2", "server2_tool"),
+        ]:
+            components = tmp_path / server_name / "components"
+            components.mkdir(parents=True)
+            (components / "__init__.py").write_text("")
+            (components / "tools.py").write_text(
+                f"""\
+from fastmcp.tools import tool
+
+@tool
+def {tool_name}() -> str:
+    return "{tool_name}"
+"""
+            )
+
+        server1 = FastMCP(
+            "server1",
+            providers=[FileSystemProvider(tmp_path / "server1" / "components")],
+        )
+        server2 = FastMCP(
+            "server2",
+            providers=[FileSystemProvider(tmp_path / "server2" / "components")],
+        )
+        parent = FastMCP("parent")
+        parent.mount(server1)
+        parent.mount(server2)
+
+        tools = await parent.list_tools()
+        assert {t.name for t in tools} == {"server1_tool", "server2_tool"}
+
+        result = await parent.call_tool("server2_tool", {})
+        assert "server2_tool" in str(result)
+
+    async def test_mounted_servers_with_same_package_different_module(
+        self, tmp_path: Path
+    ):
+        """Same package name but different module filenames must coexist.
+
+        The package directory name (`components`) collides while the leaf module
+        differs (`a.py` vs `b.py`). The shared package must not resolve to the
+        first provider's directory, which would drop the second provider's tool.
+        A relative import inside each module exercises that the isolated tree is
+        a real package.
+        """
+        for server_name, module_name, tool_name in [
+            ("server1", "a", "server1_tool"),
+            ("server2", "b", "server2_tool"),
+        ]:
+            components = tmp_path / server_name / "components"
+            components.mkdir(parents=True)
+            (components / "__init__.py").write_text("")
+            (components / "_shared.py").write_text(f'LABEL = "{tool_name}"\n')
+            (components / f"{module_name}.py").write_text(
+                f"""\
+from fastmcp.tools import tool
+
+from ._shared import LABEL
+
+@tool
+def {tool_name}() -> str:
+    return LABEL
+"""
+            )
+
+        server1 = FastMCP(
+            "server1",
+            providers=[FileSystemProvider(tmp_path / "server1" / "components")],
+        )
+        server2 = FastMCP(
+            "server2",
+            providers=[FileSystemProvider(tmp_path / "server2" / "components")],
+        )
+        parent = FastMCP("parent")
+        parent.mount(server1)
+        parent.mount(server2)
+
+        tools = await parent.list_tools()
+        assert {t.name for t in tools} == {"server1_tool", "server2_tool"}
+
+        result = await parent.call_tool("server2_tool", {})
+        assert "server2_tool" in str(result)
+
+
+class TestFileSystemProviderVersioning:
+    """Tests for version propagation through FileSystemProvider."""
+
+    async def test_versioned_tool_via_provider(self, tmp_path: Path):
+        """FileSystemProvider should preserve tool version in list_tools output."""
+        (tmp_path / "versioned.py").write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool(version="1.0", description="v1 greet")
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+"""
+        )
+
+        provider = FileSystemProvider(tmp_path)
+        mcp = FastMCP("TestServer", providers=[provider])
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            assert len(tools) == 1
+            assert tools[0].name == "greet"
+            meta = tools[0].meta
+            assert meta is not None
+            assert meta["fastmcp"]["version"] == "1.0"
+
+    async def test_versioned_resource_via_provider(self, tmp_path: Path):
+        """FileSystemProvider should preserve resource version."""
+        (tmp_path / "versioned_resource.py").write_text(
+            """\
+from fastmcp.resources import resource
+
+@resource("data://config", version="2.0", name="config", description="v2 config")
+def config() -> str:
+    return '{"theme": "dark"}'
+"""
+        )
+
+        provider = FileSystemProvider(tmp_path)
+        mcp = FastMCP("TestServer", providers=[provider])
+
+        async with Client(mcp) as client:
+            resources = await client.list_resources()
+            assert len(resources) == 1
+            assert resources[0].name == "config"
+            meta = resources[0].meta
+            assert meta is not None
+            assert meta["fastmcp"]["version"] == "2.0"
+
+    async def test_versioned_prompt_via_provider(self, tmp_path: Path):
+        """FileSystemProvider should preserve prompt version."""
+        (tmp_path / "versioned_prompt.py").write_text(
+            """\
+from fastmcp.prompts import prompt
+
+@prompt(name="summarize", version="1.0", description="v1 prompt")
+def summarize(text: str) -> str:
+    return f"Summarize: {text}"
+"""
+        )
+
+        provider = FileSystemProvider(tmp_path)
+        mcp = FastMCP("TestServer", providers=[provider])
+
+        async with Client(mcp) as client:
+            prompts = await client.list_prompts()
+            assert len(prompts) == 1
+            assert prompts[0].name == "summarize"
+            meta = prompts[0].meta
+            assert meta is not None
+            assert meta["fastmcp"]["version"] == "1.0"
+
+    async def test_multiple_tool_versions_via_provider(self, tmp_path: Path):
+        """FileSystemProvider should handle multiple versions of the same tool."""
+        (tmp_path / "multi_version.py").write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool(name="add", version="1.0", description="v1 add")
+def add_v1(x: int, y: int) -> int:
+    return x + y
+
+@tool(name="add", version="2.0", description="v2 add with z")
+def add_v2(x: int, y: int, z: int = 0) -> int:
+    return x + y + z
+"""
+        )
+
+        provider = FileSystemProvider(tmp_path)
+        mcp = FastMCP("TestServer", providers=[provider])
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            add_tools = [t for t in tools if t.name == "add"]
+            # list_tools deduplicates to the highest version
+            assert len(add_tools) == 1
+            meta = add_tools[0].meta
+            assert meta is not None
+            assert meta["fastmcp"]["version"] == "2.0"
+            assert meta["fastmcp"]["versions"] == ["2.0", "1.0"]
diff --git a/tests/integration_tests/__init__.py b/tests/integration_tests/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/integration_tests/auth/__init__.py b/tests/integration_tests/auth/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/integration_tests/auth/test_github_provider_integration.py b/tests/integration_tests/auth/test_github_provider_integration.py
new file mode 100644
index 0000000..990bba0
--- /dev/null
+++ b/tests/integration_tests/auth/test_github_provider_integration.py
@@ -0,0 +1,398 @@
+"""Integration tests for GitHub OAuth Provider.
+
+Tests the complete GitHub OAuth flow using HeadlessOAuth to bypass browser interaction.
+
+This test requires a GitHub OAuth app to be created at https://github.com/settings/developers
+with the following configuration:
+- Redirect URL: http://127.0.0.1:9100/auth/callback
+- Client ID and Client Secret should be set as environment variables:
+  - FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID
+  - FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET
+"""
+
+import os
+import re
+import secrets
+import time
+from collections.abc import AsyncGenerator
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import httpx
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.server.auth.oauth_proxy.models import ClientCode
+from fastmcp.server.auth.providers.github import GitHubProvider
+from fastmcp.utilities.tests import HeadlessOAuth, run_server_async
+
+FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID = os.getenv("FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID")
+FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET = os.getenv(
+    "FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET"
+)
+
+# Skip tests if no GitHub OAuth credentials are available
+pytestmark = pytest.mark.xfail(
+    not FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID
+    or not FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET,
+    reason="FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID and FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET environment variables are not set or empty",
+)
+
+
+def create_github_server(base_url: str) -> FastMCP:
+    """Create FastMCP server with GitHub OAuth protection."""
+    assert FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID is not None
+    assert FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET is not None
+
+    # Create GitHub OAuth provider
+    auth = GitHubProvider(
+        client_id=FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID,
+        client_secret=FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET,
+        base_url=base_url,
+        jwt_signing_key="test-secret",
+    )
+
+    # Create FastMCP server with GitHub authentication
+    server = FastMCP("GitHub OAuth Integration Test Server", auth=auth)
+
+    @server.tool
+    def get_protected_data() -> str:
+        """Returns protected data - requires GitHub OAuth."""
+        return "🔐 This data requires GitHub OAuth authentication!"
+
+    @server.tool
+    def get_user_info() -> str:
+        """Returns user info from OAuth context."""
+        return "📝 GitHub OAuth user authenticated successfully"
+
+    return server
+
+
+def create_github_server_with_mock_callback(base_url: str) -> FastMCP:
+    """Create FastMCP server with GitHub OAuth that mocks the callback for testing."""
+    assert FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID is not None
+    assert FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET is not None
+
+    # Create GitHub OAuth provider
+    auth = GitHubProvider(
+        client_id=FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID,
+        client_secret=FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET,
+        base_url=base_url,
+        jwt_signing_key="test-secret",
+    )
+
+    # Mock the authorize method to return a fake code instead of redirecting to GitHub
+    async def mock_authorize(client, params):
+        # Instead of redirecting to GitHub, simulate an immediate callback
+        # Generate a fake authorization code
+        fake_code = secrets.token_urlsafe(32)
+
+        # Create mock token response (simulating what GitHub would return)
+        mock_tokens = {
+            "access_token": f"gho_mock_token_{secrets.token_hex(16)}",
+            "token_type": "bearer",
+            "expires_in": 3600,
+        }
+
+        # Store the mock tokens in the proxy's code storage
+        await auth._code_store.put(
+            key=fake_code,
+            value=ClientCode(
+                code=fake_code,
+                client_id=client.client_id,
+                redirect_uri=str(params.redirect_uri),
+                code_challenge=params.code_challenge,
+                code_challenge_method=getattr(params, "code_challenge_method", "S256"),
+                scopes=params.scopes or [],
+                idp_tokens=mock_tokens,
+                expires_at=int(time.time() + 300),  # 5 minutes
+                created_at=time.time(),
+            ),
+        )
+
+        # Return the redirect to the client's callback with the fake code
+        callback_params = {
+            "code": fake_code,
+            "state": params.state,
+        }
+        separator = "&" if "?" in str(params.redirect_uri) else "?"
+        return f"{params.redirect_uri}{separator}{urlencode(callback_params)}"
+
+    auth.authorize = mock_authorize  # type: ignore[assignment]  # ty:ignore[invalid-assignment]
+
+    # Mock the token verifier to accept our fake tokens
+    original_verify_token = auth._token_validator.verify_token
+
+    async def mock_verify_token(token: str):
+        if token.startswith("gho_mock_token_"):
+            # Return a mock AccessToken for our fake tokens
+            return AccessToken(
+                token=token,
+                client_id=FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID or "test-client",
+                scopes=["user"],
+                expires_at=int(time.time() + 3600),
+            )
+        # Fall back to original verification for other tokens
+        return await original_verify_token(token)
+
+    auth._token_validator.verify_token = mock_verify_token  # type: ignore[assignment]  # ty:ignore[invalid-assignment]
+
+    # Create FastMCP server with mocked GitHub authentication
+    server = FastMCP("GitHub OAuth Integration Test Server (Mock)", auth=auth)
+
+    @server.tool
+    def get_protected_data() -> str:
+        """Returns protected data - requires GitHub OAuth."""
+        return "🔐 This data requires GitHub OAuth authentication!"
+
+    @server.tool
+    def get_user_info() -> str:
+        """Returns user info from OAuth context."""
+        return "📝 GitHub OAuth user authenticated successfully"
+
+    return server
+
+
+@pytest.fixture
+async def github_server() -> AsyncGenerator[str, None]:
+    """Start GitHub OAuth server on a random available port."""
+    from fastmcp.utilities.http import find_available_port
+
+    port = find_available_port()
+    base_url = f"http://127.0.0.1:{port}"
+    server = create_github_server(base_url)
+    async with run_server_async(server, port=port, transport="http") as url:
+        yield url
+
+
+@pytest.fixture
+async def github_server_with_mock() -> AsyncGenerator[str, None]:
+    """Start GitHub OAuth server with mocked callback on a random available port."""
+    from fastmcp.utilities.http import find_available_port
+
+    port = find_available_port()
+    base_url = f"http://127.0.0.1:{port}"
+    server = create_github_server_with_mock_callback(base_url)
+    async with run_server_async(server, port=port, transport="http") as url:
+        yield url
+
+
+@pytest.fixture
+def github_client(github_server: str) -> Client:
+    """Create FastMCP client with HeadlessOAuth for GitHub server."""
+    return Client(
+        github_server,
+        auth=HeadlessOAuth(mcp_url=github_server),
+    )
+
+
+@pytest.fixture
+def github_client_with_mock(github_server_with_mock: str) -> Client:
+    """Create FastMCP client with HeadlessOAuth for mocked GitHub server."""
+    return Client(
+        github_server_with_mock,
+        auth=HeadlessOAuth(mcp_url=github_server_with_mock),
+    )
+
+
+async def test_github_oauth_credentials_available():
+    """Test that GitHub OAuth credentials are available for testing."""
+    assert FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID is not None
+    assert FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET is not None
+    assert len(FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID) > 0
+    assert len(FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET) > 0
+
+
+async def test_github_oauth_authorization_redirect(github_server: str):
+    """Test that GitHub OAuth authorization redirects to GitHub correctly through consent flow.
+
+    Since HeadlessOAuth can't handle real GitHub redirects, we test that:
+    1. DCR client registration works
+    2. Authorization endpoint redirects to consent page
+    3. Consent approval redirects to GitHub with correct parameters
+    """
+    # Extract base URL
+    parsed = urlparse(github_server)
+    base_url = f"{parsed.scheme}://{parsed.netloc}"
+
+    async with httpx.AsyncClient() as http_client:
+        # Step 1: Register OAuth client (DCR)
+        register_response = await http_client.post(
+            f"{base_url}/register",
+            json={
+                "client_name": "Integration Test Client",
+                "redirect_uris": ["http://localhost:12345/callback"],
+                "grant_types": ["authorization_code", "refresh_token"],
+                "response_types": ["code"],
+                "token_endpoint_auth_method": "client_secret_post",
+            },
+        )
+        if register_response.status_code != 201:
+            print(f"Registration failed: {register_response.status_code}")
+            print(f"Response: {register_response.text}")
+        assert register_response.status_code == 201
+
+        client_info = register_response.json()
+        client_id = client_info["client_id"]
+        assert client_id is not None
+
+        # Step 2: Test authorization endpoint redirects to consent page
+        auth_url = f"{base_url}/authorize"
+        auth_params = {
+            "response_type": "code",
+            "client_id": client_id,
+            "redirect_uri": "http://localhost:12345/callback",
+            "state": "test-state-123",
+            "code_challenge": "test-challenge",
+            "code_challenge_method": "S256",
+        }
+
+        auth_response = await http_client.get(
+            auth_url, params=auth_params, follow_redirects=False
+        )
+
+        # Should redirect to consent page (confused deputy protection)
+        assert auth_response.status_code == 302
+        consent_location = auth_response.headers["location"]
+        assert "/consent" in consent_location
+
+        # Step 3: Visit consent page to get CSRF token
+        consent_response = await http_client.get(
+            consent_location, follow_redirects=False
+        )
+        assert consent_response.status_code == 200
+
+        # Extract CSRF token from consent page HTML
+        csrf_match = re.search(
+            r'name="csrf_token"\s+value="([^"]+)"', consent_response.text
+        )
+        assert csrf_match, "CSRF token not found in consent page"
+        csrf_token = csrf_match.group(1)
+
+        # Extract txn_id from consent URL
+        txn_id_match = re.search(r"txn_id=([^&]+)", consent_location)
+        assert txn_id_match, "txn_id not found in consent URL"
+        txn_id = txn_id_match.group(1)
+
+        # Step 4: Approve consent
+        approve_response = await http_client.post(
+            f"{base_url}/consent",
+            data={
+                "action": "approve",
+                "txn_id": txn_id,
+                "csrf_token": csrf_token,
+            },
+            cookies=consent_response.cookies,
+            follow_redirects=False,
+        )
+
+        # Should redirect to GitHub
+        assert approve_response.status_code in (302, 303)
+        redirect_location = approve_response.headers["location"]
+
+        # Parse redirect URL - should be GitHub
+        redirect_parsed = urlparse(redirect_location)
+        assert redirect_parsed.hostname == "github.com"
+        assert redirect_parsed.path == "/login/oauth/authorize"
+
+        # Check that GitHub gets the right parameters
+        github_params = parse_qs(redirect_parsed.query)
+        assert "client_id" in github_params
+        assert github_params["client_id"][0] == FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID
+        assert "redirect_uri" in github_params
+        # The redirect_uri should be our proxy's callback, not the client's
+        proxy_callback = github_params["redirect_uri"][0]
+        assert proxy_callback.startswith(base_url)
+        assert proxy_callback.endswith("/auth/callback")
+
+
+async def test_github_oauth_server_metadata(github_server: str):
+    """Test OAuth server metadata discovery."""
+    from urllib.parse import urlparse
+
+    import httpx
+
+    # Extract base URL from server URL
+    parsed = urlparse(github_server)
+    base_url = f"{parsed.scheme}://{parsed.netloc}"
+
+    async with httpx.AsyncClient() as http_client:
+        # Test OAuth authorization server metadata
+        metadata_response = await http_client.get(
+            f"{base_url}/.well-known/oauth-authorization-server"
+        )
+        assert metadata_response.status_code == 200
+
+        metadata = metadata_response.json()
+        assert "authorization_endpoint" in metadata
+        assert "token_endpoint" in metadata
+        assert "registration_endpoint" in metadata
+        assert "issuer" in metadata
+
+        # Verify endpoints are properly formed
+        assert metadata["authorization_endpoint"].startswith(base_url)
+        assert metadata["token_endpoint"].startswith(base_url)
+        assert metadata["registration_endpoint"].startswith(base_url)
+
+
+async def test_github_oauth_unauthorized_access(github_server: str):
+    """Test that unauthenticated requests are rejected.
+
+    SDK v2 surfaces the server's 401 as an MCPError ("Server returned an error
+    response") rather than re-raising the raw httpx.HTTPStatusError.
+    """
+    from mcp.shared.exceptions import MCPError
+
+    from fastmcp.client.transports import StreamableHttpTransport
+
+    # Create client without OAuth authentication
+    unauthorized_client = Client(transport=StreamableHttpTransport(github_server))
+
+    # Attempt to connect without authentication should fail
+    with pytest.raises(MCPError, match="error response"):
+        async with unauthorized_client:
+            pass
+
+
+async def test_github_oauth_with_mock(github_client_with_mock: Client):
+    """Test complete GitHub OAuth flow with mocked callback."""
+
+    async with github_client_with_mock:
+        # Test that we can ping the server (requires successful OAuth)
+        assert await github_client_with_mock.ping()
+
+        # Test that we can call protected tools
+        result = await github_client_with_mock.call_tool("get_protected_data", {})
+        assert "🔐 This data requires GitHub OAuth authentication!" in str(result.data)
+
+        # Test that we can call user info tool
+        result = await github_client_with_mock.call_tool("get_user_info", {})
+        assert "📝 GitHub OAuth user authenticated successfully" in str(result.data)
+
+
+async def test_github_oauth_mock_only_accepts_mock_tokens(github_server_with_mock: str):
+    """Test that the mock token verifier only accepts mock tokens, not real ones."""
+    from urllib.parse import urlparse
+
+    import httpx
+
+    # Extract base URL
+    parsed = urlparse(github_server_with_mock)
+    base_url = f"{parsed.scheme}://{parsed.netloc}"
+
+    async with httpx.AsyncClient() as http_client:
+        # Test that a fake "real" GitHub token is rejected
+        fake_real_token = "gho_real_token_should_be_rejected"
+
+        auth_response = await http_client.post(
+            f"{base_url}/mcp",
+            headers={
+                "Authorization": f"Bearer {fake_real_token}",
+                "Content-Type": "application/json",
+            },
+            json={"jsonrpc": "2.0", "id": 1, "method": "ping"},
+        )
+
+        # Should be unauthorized because it's not a mock token
+        assert auth_response.status_code == 401
diff --git a/tests/integration_tests/auth/test_keycloak_provider_integration.py b/tests/integration_tests/auth/test_keycloak_provider_integration.py
new file mode 100644
index 0000000..3b3a8fa
--- /dev/null
+++ b/tests/integration_tests/auth/test_keycloak_provider_integration.py
@@ -0,0 +1,360 @@
+"""Integration tests for Keycloak OAuth provider - Minimal implementation."""
+
+import os
+from unittest.mock import AsyncMock, Mock, patch
+
+import httpx
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.keycloak import KeycloakAuthProvider
+
+TEST_REALM_URL = "https://keycloak.example.com/realms/test"
+TEST_BASE_URL = "https://fastmcp.example.com"
+TEST_REQUIRED_SCOPES = ["openid", "profile", "email"]
+
+
+class TestKeycloakProviderIntegration:
+    """Integration tests for KeycloakAuthProvider with minimal implementation."""
+
+    async def test_oauth_discovery_endpoints_integration(self):
+        """Test OAuth discovery endpoints work correctly together."""
+        with patch("httpx.get") as mock_get:
+            mock_response = Mock()
+            mock_response.json.return_value = {
+                "issuer": TEST_REALM_URL,
+                "authorization_endpoint": f"{TEST_REALM_URL}/protocol/openid-connect/auth",
+                "token_endpoint": f"{TEST_REALM_URL}/protocol/openid-connect/token",
+                "jwks_uri": f"{TEST_REALM_URL}/.well-known/jwks.json",
+                "registration_endpoint": f"{TEST_REALM_URL}/clients-registrations/openid-connect",
+            }
+            mock_response.raise_for_status.return_value = None
+            mock_get.return_value = mock_response
+
+            provider = KeycloakAuthProvider(
+                realm_url=TEST_REALM_URL,
+                base_url=TEST_BASE_URL,
+                required_scopes=TEST_REQUIRED_SCOPES,
+            )
+
+            mcp = FastMCP("test-server", auth=provider)
+            mcp_http_app = mcp.http_app()
+
+            async with httpx.AsyncClient(
+                transport=httpx.ASGITransport(app=mcp_http_app),
+                base_url=TEST_BASE_URL,
+            ) as client:
+                # Test protected resource metadata
+                resource_response = await client.get(
+                    "/.well-known/oauth-protected-resource/mcp"
+                )
+                assert resource_response.status_code == 200
+                resource_data = resource_response.json()
+
+                # Verify resource server metadata
+                assert resource_data["resource"] == f"{TEST_BASE_URL}/mcp"
+                # authorization_servers points directly to the Keycloak realm
+                assert TEST_REALM_URL in [
+                    s.rstrip("/") for s in resource_data["authorization_servers"]
+                ]
+
+    async def test_no_register_proxy_route(self):
+        """Test that KeycloakAuthProvider does not expose a /register proxy route.
+
+        Keycloak 26.6.0+ handles DCR natively and correctly, so no proxy is needed.
+        MCP clients register directly with Keycloak's DCR endpoint.
+        """
+        provider = KeycloakAuthProvider(
+            realm_url=TEST_REALM_URL,
+            base_url=TEST_BASE_URL,
+            required_scopes=TEST_REQUIRED_SCOPES,
+        )
+
+        mcp = FastMCP("test-server", auth=provider)
+        mcp_http_app = mcp.http_app()
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=mcp_http_app),
+            base_url=TEST_BASE_URL,
+        ) as client:
+            response = await client.post(
+                "/register",
+                json={"client_name": "Test", "redirect_uris": ["http://localhost/cb"]},
+                headers={"Content-Type": "application/json"},
+            )
+
+            assert response.status_code == 404
+
+    @pytest.mark.skip(
+        reason="Mock conflicts with ASGI transport - verified working in production"
+    )
+    async def test_authorization_server_metadata_forwards_keycloak(self):
+        """Test that authorization server metadata is forwarded from Keycloak.
+
+        Note: This test is skipped because mocking httpx.AsyncClient conflicts with the
+        ASGI transport used by the test client. The functionality has been verified to
+        work correctly in production (see user testing logs showing successful DCR proxy).
+        """
+        with patch("httpx.get") as mock_get:
+            # Mock OIDC discovery
+            mock_discovery = Mock()
+            mock_discovery.json.return_value = {
+                "issuer": TEST_REALM_URL,
+                "authorization_endpoint": f"{TEST_REALM_URL}/protocol/openid-connect/auth",
+                "token_endpoint": f"{TEST_REALM_URL}/protocol/openid-connect/token",
+                "jwks_uri": f"{TEST_REALM_URL}/.well-known/jwks.json",
+                "registration_endpoint": f"{TEST_REALM_URL}/clients-registrations/openid-connect",
+            }
+            mock_discovery.raise_for_status.return_value = None
+            mock_get.return_value = mock_discovery
+
+            provider = KeycloakAuthProvider(
+                realm_url=TEST_REALM_URL,
+                base_url=TEST_BASE_URL,
+                required_scopes=TEST_REQUIRED_SCOPES,
+            )
+
+            mcp = FastMCP("test-server", auth=provider)
+            mcp_http_app = mcp.http_app()
+
+            # Mock the metadata forwarding request
+            with patch("httpx.AsyncClient") as mock_client_class:
+                mock_client = AsyncMock()
+                mock_client_class.return_value.__aenter__.return_value = mock_client
+
+                mock_metadata_response = Mock()
+                mock_metadata_response.status_code = 200
+                mock_metadata_response.json.return_value = {
+                    "issuer": TEST_REALM_URL,
+                    "authorization_endpoint": f"{TEST_REALM_URL}/protocol/openid-connect/auth",
+                    "token_endpoint": f"{TEST_REALM_URL}/protocol/openid-connect/token",
+                    "jwks_uri": f"{TEST_REALM_URL}/.well-known/jwks.json",
+                    "registration_endpoint": f"{TEST_REALM_URL}/clients-registrations/openid-connect",
+                    "response_types_supported": ["code"],
+                    "grant_types_supported": ["authorization_code", "refresh_token"],
+                }
+                mock_metadata_response.raise_for_status = Mock()
+                mock_client.get.return_value = mock_metadata_response
+
+                async with httpx.AsyncClient(
+                    transport=httpx.ASGITransport(app=mcp_http_app),
+                    base_url=TEST_BASE_URL,
+                ) as client:
+                    # Test authorization server metadata forwarding
+                    auth_server_response = await client.get(
+                        "/.well-known/oauth-authorization-server"
+                    )
+                    assert auth_server_response.status_code == 200
+                    auth_data = auth_server_response.json()
+
+                    # Verify metadata is forwarded from Keycloak but registration_endpoint is rewritten
+                    assert (
+                        auth_data["authorization_endpoint"]
+                        == f"{TEST_REALM_URL}/protocol/openid-connect/auth"
+                    )
+                    assert (
+                        auth_data["registration_endpoint"]
+                        == f"{TEST_BASE_URL}/register"
+                    )  # Rewritten to our DCR proxy
+                    assert auth_data["issuer"] == TEST_REALM_URL
+                    assert (
+                        auth_data["jwks_uri"]
+                        == f"{TEST_REALM_URL}/.well-known/jwks.json"
+                    )
+
+                    # Verify we called Keycloak's metadata endpoint
+                    mock_client.get.assert_called_once_with(
+                        f"{TEST_REALM_URL}/.well-known/oauth-authorization-server"
+                    )
+
+    async def test_initialization_without_network_call(self):
+        """Test that provider initialization doesn't require network call to Keycloak.
+
+        Since we use hard-coded Keycloak URL patterns, initialization succeeds
+        even if Keycloak is unavailable. Network errors only occur at runtime
+        when actually fetching metadata or registering clients.
+        """
+        # Should succeed without any network calls
+        provider = KeycloakAuthProvider(
+            realm_url=TEST_REALM_URL,
+            base_url=TEST_BASE_URL,
+        )
+
+        # Verify provider is configured with hard-coded patterns
+        assert provider.realm_url == TEST_REALM_URL
+        assert str(provider.base_url) == TEST_BASE_URL + "/"
+
+    @pytest.mark.skip(
+        reason="Mock conflicts with ASGI transport - error handling verified in code"
+    )
+    async def test_metadata_forwarding_error_handling(self):
+        """Test error handling when metadata forwarding fails.
+
+        Note: This test is skipped because mocking httpx.AsyncClient conflicts with the
+        ASGI transport. Error handling code is present and follows standard patterns.
+        """
+        with patch("httpx.get") as mock_get:
+            mock_response = Mock()
+            mock_response.json.return_value = {
+                "issuer": TEST_REALM_URL,
+                "authorization_endpoint": f"{TEST_REALM_URL}/protocol/openid-connect/auth",
+                "token_endpoint": f"{TEST_REALM_URL}/protocol/openid-connect/token",
+                "jwks_uri": f"{TEST_REALM_URL}/.well-known/jwks.json",
+            }
+            mock_response.raise_for_status.return_value = None
+            mock_get.return_value = mock_response
+
+            provider = KeycloakAuthProvider(
+                realm_url=TEST_REALM_URL,
+                base_url=TEST_BASE_URL,
+            )
+
+            mcp = FastMCP("test-server", auth=provider)
+            mcp_http_app = mcp.http_app()
+
+            with patch("httpx.AsyncClient") as mock_client_class:
+                mock_client = AsyncMock()
+                mock_client_class.return_value.__aenter__.return_value = mock_client
+
+                # Simulate Keycloak error
+                mock_client.get.side_effect = httpx.RequestError("Connection failed")
+
+                async with httpx.AsyncClient(
+                    transport=httpx.ASGITransport(app=mcp_http_app),
+                    base_url=TEST_BASE_URL,
+                ) as client:
+                    response = await client.get(
+                        "/.well-known/oauth-authorization-server"
+                    )
+
+                    # Should return 500 error with error details
+                    assert response.status_code == 500
+                    data = response.json()
+                    assert "error" in data
+                    assert data["error"] == "server_error"
+
+
+class TestKeycloakProviderEnvironmentConfiguration:
+    """Test configuration from environment variables in integration context."""
+
+    def test_provider_loads_all_settings_from_environment(self):
+        """Test that provider can be fully configured from environment."""
+        env_vars = {
+            "FASTMCP_SERVER_AUTH_KEYCLOAK_REALM_URL": TEST_REALM_URL,
+            "FASTMCP_SERVER_AUTH_KEYCLOAK_BASE_URL": TEST_BASE_URL,
+            "FASTMCP_SERVER_AUTH_KEYCLOAK_REQUIRED_SCOPES": "openid,profile,email,custom:scope",
+        }
+
+        with (
+            patch.dict(os.environ, env_vars),
+            patch("httpx.get") as mock_get,
+        ):
+            mock_response = Mock()
+            mock_response.json.return_value = {
+                "issuer": TEST_REALM_URL,
+                "authorization_endpoint": f"{TEST_REALM_URL}/protocol/openid-connect/auth",
+                "token_endpoint": f"{TEST_REALM_URL}/protocol/openid-connect/token",
+                "jwks_uri": f"{TEST_REALM_URL}/.well-known/jwks.json",
+            }
+            mock_response.raise_for_status.return_value = None
+            mock_get.return_value = mock_response
+
+            # Explicitly read from environment and pass to provider
+            provider = KeycloakAuthProvider(
+                realm_url=os.environ["FASTMCP_SERVER_AUTH_KEYCLOAK_REALM_URL"],
+                base_url=os.environ["FASTMCP_SERVER_AUTH_KEYCLOAK_BASE_URL"],
+                required_scopes=os.environ[
+                    "FASTMCP_SERVER_AUTH_KEYCLOAK_REQUIRED_SCOPES"
+                ],
+            )
+
+            assert provider.realm_url == TEST_REALM_URL
+            assert str(provider.base_url) == TEST_BASE_URL + "/"
+            assert provider.token_verifier.required_scopes == [
+                "openid",
+                "profile",
+                "email",
+                "custom:scope",
+            ]
+
+    @pytest.mark.skip(
+        reason="Mock conflicts with ASGI transport - verified working in production"
+    )
+    async def test_provider_works_in_production_like_environment(self):
+        """Test provider configuration that mimics production deployment.
+
+        Note: This test is skipped because mocking httpx.AsyncClient conflicts with the
+        ASGI transport used by the test client. The functionality has been verified to
+        work correctly in production (see user testing logs showing successful DCR proxy).
+        """
+        production_env = {
+            "FASTMCP_SERVER_AUTH_KEYCLOAK_REALM_URL": "https://auth.company.com/realms/production",
+            "FASTMCP_SERVER_AUTH_KEYCLOAK_BASE_URL": "https://api.company.com",
+            "FASTMCP_SERVER_AUTH_KEYCLOAK_REQUIRED_SCOPES": "openid,profile,email,api:read,api:write",
+        }
+
+        with (
+            patch.dict(os.environ, production_env),
+            patch("httpx.get") as mock_get,
+        ):
+            mock_response = Mock()
+            mock_response.json.return_value = {
+                "issuer": "https://auth.company.com/realms/production",
+                "authorization_endpoint": "https://auth.company.com/realms/production/protocol/openid-connect/auth",
+                "token_endpoint": "https://auth.company.com/realms/production/protocol/openid-connect/token",
+                "jwks_uri": "https://auth.company.com/realms/production/.well-known/jwks.json",
+                "registration_endpoint": "https://auth.company.com/realms/production/clients-registrations/openid-connect",
+            }
+            mock_response.raise_for_status.return_value = None
+            mock_get.return_value = mock_response
+
+            # Explicitly read from environment and pass to provider
+            provider = KeycloakAuthProvider(
+                realm_url=os.environ["FASTMCP_SERVER_AUTH_KEYCLOAK_REALM_URL"],
+                base_url=os.environ["FASTMCP_SERVER_AUTH_KEYCLOAK_BASE_URL"],
+                required_scopes=os.environ[
+                    "FASTMCP_SERVER_AUTH_KEYCLOAK_REQUIRED_SCOPES"
+                ],
+            )
+            mcp = FastMCP("production-server", auth=provider)
+            mcp_http_app = mcp.http_app()
+
+            with patch("httpx.AsyncClient") as mock_client_class:
+                mock_client = AsyncMock()
+                mock_client_class.return_value.__aenter__.return_value = mock_client
+
+                mock_metadata = Mock()
+                mock_metadata.status_code = 200
+                mock_metadata.json.return_value = {
+                    "issuer": "https://auth.company.com/realms/production",
+                    "authorization_endpoint": "https://auth.company.com/realms/production/protocol/openid-connect/auth",
+                    "token_endpoint": "https://auth.company.com/realms/production/protocol/openid-connect/token",
+                    "jwks_uri": "https://auth.company.com/realms/production/.well-known/jwks.json",
+                    "registration_endpoint": "https://auth.company.com/realms/production/clients-registrations/openid-connect",
+                }
+                mock_metadata.raise_for_status = Mock()
+                mock_client.get.return_value = mock_metadata
+
+                async with httpx.AsyncClient(
+                    transport=httpx.ASGITransport(app=mcp_http_app),
+                    base_url="https://api.company.com",
+                ) as client:
+                    # Test discovery endpoints work
+                    response = await client.get(
+                        "/.well-known/oauth-authorization-server"
+                    )
+                    assert response.status_code == 200
+                    data = response.json()
+
+                    # Minimal proxy: endpoints from Keycloak but registration_endpoint rewritten
+                    assert (
+                        data["issuer"] == "https://auth.company.com/realms/production"
+                    )
+                    assert (
+                        data["authorization_endpoint"]
+                        == "https://auth.company.com/realms/production/protocol/openid-connect/auth"
+                    )
+                    assert (
+                        data["registration_endpoint"]
+                        == "https://api.company.com/register"
+                    )  # Our DCR proxy
diff --git a/tests/integration_tests/conftest.py b/tests/integration_tests/conftest.py
new file mode 100644
index 0000000..c85b38e
--- /dev/null
+++ b/tests/integration_tests/conftest.py
@@ -0,0 +1,72 @@
+import os
+
+import pytest
+
+
+def _is_rate_limit_error(excinfo, report=None) -> bool:
+    """Check if an exception indicates a rate limit error from GitHub API.
+
+    Args:
+        excinfo: The exception info from pytest
+        report: Optional test report for additional context (captured output, longrepr)
+    """
+    if excinfo is None:
+        return False
+
+    exc = excinfo.value
+    exc_type = excinfo.typename
+    exc_str = str(exc).lower()
+
+    # BrokenResourceError typically indicates connection closed due to rate limit
+    if exc_type == "BrokenResourceError":
+        return True
+
+    # httpx.HTTPStatusError with 429 status
+    if exc_type == "HTTPStatusError":
+        try:
+            if hasattr(exc, "response") and exc.response.status_code == 429:
+                return True
+        except Exception:
+            pass
+
+    # Check for rate limit indicators in exception message
+    if "429" in exc_str or "rate limit" in exc_str or "too many requests" in exc_str:
+        return True
+
+    # Timeout exceptions may indicate rate limiting when the 429 causes asyncio
+    # shutdown issues. Check if it's a timeout and look for 429 in the captured output.
+    if "timeout" in exc_type.lower() or "timeout" in exc_str:
+        # Check captured output for 429 indicators
+        if report is not None:
+            longrepr_str = str(report.longrepr).lower() if report.longrepr else ""
+            if "429" in longrepr_str or "too many requests" in longrepr_str:
+                return True
+
+            # Check captured stdout/stderr
+            for section_name, content in getattr(report, "sections", []):
+                if "429" in content or "too many requests" in content.lower():
+                    return True
+
+    return False
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_makereport(item, call):
+    """Convert rate limit failures to skips for GitHub integration tests."""
+    outcome = yield
+    report = outcome.get_result()
+
+    # Only process actual failures during the call or teardown phase, not xfails
+    if (
+        report.when in ("call", "teardown")
+        and report.failed
+        and not hasattr(report, "wasxfail")
+        and item.module.__name__ == "tests.integration_tests.test_github_mcp_remote"
+        and _is_rate_limit_error(call.excinfo, report)
+    ):
+        report.outcome = "skipped"
+        report.longrepr = (
+            os.path.abspath(__file__),
+            None,
+            "Skipped: Skipping due to GitHub API rate limit (429)",
+        )
diff --git a/tests/integration_tests/test_github_mcp_remote.py b/tests/integration_tests/test_github_mcp_remote.py
new file mode 100644
index 0000000..b6190af
--- /dev/null
+++ b/tests/integration_tests/test_github_mcp_remote.py
@@ -0,0 +1,126 @@
+import json
+import os
+
+import pytest
+from mcp import MCPError
+from mcp_types import Resource, TextContent, Tool
+
+from fastmcp import Client
+from fastmcp.client import StreamableHttpTransport
+from fastmcp.client.auth.bearer import BearerAuth
+
+GITHUB_REMOTE_MCP_URL = "https://api.githubcopilot.com/mcp/"
+
+HEADER_AUTHORIZATION = "Authorization"
+FASTMCP_GITHUB_TOKEN = os.getenv("FASTMCP_GITHUB_TOKEN")
+
+
+# Skip tests if no GitHub token is available
+pytestmark = pytest.mark.xfail(
+    not FASTMCP_GITHUB_TOKEN,
+    reason="The FASTMCP_GITHUB_TOKEN environment variable is not set or empty",
+)
+
+
+@pytest.fixture(name="streamable_http_client")
+def fixture_streamable_http_client() -> Client[StreamableHttpTransport]:
+    assert FASTMCP_GITHUB_TOKEN is not None
+
+    return Client(
+        StreamableHttpTransport(
+            url=GITHUB_REMOTE_MCP_URL,
+            auth=BearerAuth(FASTMCP_GITHUB_TOKEN),
+        )
+    )
+
+
+class TestGithubMCPRemote:
+    async def test_connect_disconnect(
+        self,
+        streamable_http_client: Client[StreamableHttpTransport],
+    ):
+        async with streamable_http_client:
+            assert streamable_http_client.is_connected() is True
+            await streamable_http_client._disconnect()  # pylint: disable=W0212 (protected-access)
+            assert streamable_http_client.is_connected() is False
+
+    async def test_ping(self, streamable_http_client: Client[StreamableHttpTransport]):
+        """Test pinging the server."""
+        async with streamable_http_client:
+            assert streamable_http_client.is_connected() is True
+            result = await streamable_http_client.ping()
+            assert result is True
+
+    async def test_list_tools(
+        self, streamable_http_client: Client[StreamableHttpTransport]
+    ):
+        """Test listing the MCP tools"""
+        async with streamable_http_client:
+            assert streamable_http_client.is_connected()
+            tools = await streamable_http_client.list_tools()
+            assert isinstance(tools, list)
+            assert len(tools) > 0  # Ensure the tools list is non-empty
+            for tool in tools:
+                assert isinstance(tool, Tool)
+                assert len(tool.name) > 0
+                assert tool.description is not None and len(tool.description) > 0
+                assert isinstance(tool.input_schema, dict)
+                assert len(tool.input_schema) > 0
+
+    async def test_list_resources(
+        self, streamable_http_client: Client[StreamableHttpTransport]
+    ):
+        """Test listing the MCP resources"""
+        async with streamable_http_client:
+            assert streamable_http_client.is_connected()
+            resources = await streamable_http_client.list_resources()
+            assert isinstance(resources, list)
+            for resource in resources:
+                assert isinstance(resource, Resource)
+                assert resource.name
+                assert str(resource.uri)
+
+    async def test_list_prompts(
+        self, streamable_http_client: Client[StreamableHttpTransport]
+    ):
+        """Test listing the MCP prompts"""
+        async with streamable_http_client:
+            assert streamable_http_client.is_connected()
+            prompts = await streamable_http_client.list_prompts()
+            # there is at least one prompt (as of July 2025)
+            assert len(prompts) >= 1
+
+    async def test_call_tool_ko(
+        self, streamable_http_client: Client[StreamableHttpTransport]
+    ):
+        """Test calling a non-existing tool"""
+        async with streamable_http_client:
+            assert streamable_http_client.is_connected()
+            with pytest.raises(MCPError, match=r"unknown tool|tool not found"):
+                await streamable_http_client.call_tool("foo")
+
+    async def test_call_tool_list_commits(
+        self,
+        streamable_http_client: Client[StreamableHttpTransport],
+    ):
+        """Test calling a list_commit tool"""
+        async with streamable_http_client:
+            assert streamable_http_client.is_connected()
+            result = await streamable_http_client.call_tool(
+                "list_commits", {"owner": "prefecthq", "repo": "fastmcp"}
+            )
+
+            # at this time, the github server does not support structured content
+            assert result.structured_content is None
+            assert isinstance(result.content, list)
+            assert len(result.content) == 1
+            assert isinstance(result.content[0], TextContent)
+            commits = json.loads(result.content[0].text)
+            for commit in commits:
+                assert isinstance(commit, dict)
+                assert "sha" in commit
+                assert "commit" in commit
+                assert "author" in commit["commit"]
+                assert len(commit["commit"]["author"]["date"]) > 0
+                assert len(commit["commit"]["author"]["name"]) > 0
+                assert len(commit["commit"]["author"]["email"]) > 0
diff --git a/tests/integration_tests/test_timeout_fix.py b/tests/integration_tests/test_timeout_fix.py
new file mode 100644
index 0000000..27776c1
--- /dev/null
+++ b/tests/integration_tests/test_timeout_fix.py
@@ -0,0 +1,51 @@
+"""Test that verifies the timeout fix for issue #2842 and #2845."""
+
+import asyncio
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.transports import StreamableHttpTransport
+from fastmcp.utilities.tests import run_server_async
+
+
+def create_test_server() -> FastMCP:
+    """Create a FastMCP server with a slow tool."""
+    server = FastMCP("TestServer")
+
+    @server.tool
+    async def slow_tool(duration: int = 6) -> str:
+        """A tool that takes some time to complete."""
+        await asyncio.sleep(duration)
+        return f"Completed in {duration} seconds"
+
+    return server
+
+
+@pytest.fixture
+async def streamable_http_server():
+    """Start a test server and return its URL."""
+    server = create_test_server()
+    async with run_server_async(server) as url:
+        yield url
+
+
+@pytest.mark.integration
+@pytest.mark.timeout(15)
+async def test_slow_tool_with_http_transport(streamable_http_server: str):
+    """Test that tools taking >5 seconds work correctly with HTTP transport.
+
+    This test verifies the fix for:
+    - Issue #2842: Client can't get result after upgrading to 2.14.2
+    - Issue #2845: Server doesn't return results when tool takes >5 seconds
+
+    The root cause was that the httpx client was created without explicit
+    timeout configuration, defaulting to httpx's 5-second timeout.
+    """
+    async with Client(
+        transport=StreamableHttpTransport(streamable_http_server)
+    ) as client:
+        # This should NOT timeout since we fixed the default timeout
+        result = await client.call_tool("slow_tool", {"duration": 6})
+        assert result.data == "Completed in 6 seconds"
diff --git a/tests/prompts/__init__.py b/tests/prompts/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/prompts/test_prompt.py b/tests/prompts/test_prompt.py
new file mode 100644
index 0000000..201632e
--- /dev/null
+++ b/tests/prompts/test_prompt.py
@@ -0,0 +1,848 @@
+import pytest
+from mcp_types import EmbeddedResource, TextResourceContents
+
+from fastmcp.prompts.base import (
+    Message,
+    Prompt,
+    PromptResult,
+)
+
+
+class TestRenderPrompt:
+    async def test_basic_fn(self):
+        def fn() -> str:
+            return "Hello, world!"
+
+        prompt = Prompt.from_function(fn)
+        result = await prompt.render()
+        assert result.messages == [Message("Hello, world!")]
+
+    async def test_async_fn(self):
+        async def fn() -> str:
+            return "Hello, world!"
+
+        prompt = Prompt.from_function(fn)
+        result = await prompt.render()
+        assert result.messages == [Message("Hello, world!")]
+
+    async def test_fn_with_args(self):
+        async def fn(name: str, age: int = 30) -> str:
+            return f"Hello, {name}! You're {age} years old."
+
+        prompt = Prompt.from_function(fn)
+        result = await prompt.render(arguments=dict(name="World"))
+        assert result.messages == [Message("Hello, World! You're 30 years old.")]
+
+    async def test_callable_object(self):
+        class MyPrompt:
+            def __call__(self, name: str) -> str:
+                return f"Hello, {name}!"
+
+        prompt = Prompt.from_function(MyPrompt())
+        result = await prompt.render(arguments=dict(name="World"))
+        assert result.messages == [Message("Hello, World!")]
+
+    async def test_async_callable_object(self):
+        class MyPrompt:
+            async def __call__(self, name: str) -> str:
+                return f"Hello, {name}!"
+
+        prompt = Prompt.from_function(MyPrompt())
+        result = await prompt.render(arguments=dict(name="World"))
+        assert result.messages == [Message("Hello, World!")]
+
+    async def test_fn_with_invalid_kwargs(self):
+        async def fn(name: str, age: int = 30) -> str:
+            return f"Hello, {name}! You're {age} years old."
+
+        prompt = Prompt.from_function(fn)
+        with pytest.raises(ValueError):
+            await prompt.render(arguments=dict(age=40))
+
+    async def test_fn_returns_message_list(self):
+        async def fn() -> list[Message]:
+            return [Message("Hello, world!")]
+
+        prompt = Prompt.from_function(fn)
+        result = await prompt.render()
+        assert result.messages == [Message("Hello, world!")]
+
+    async def test_fn_returns_assistant_message(self):
+        async def fn() -> list[Message]:
+            return [Message("Hello, world!", role="assistant")]
+
+        prompt = Prompt.from_function(fn)
+        result = await prompt.render()
+        assert result.messages == [Message("Hello, world!", role="assistant")]
+
+    async def test_fn_returns_multiple_messages(self):
+        expected = [
+            Message("Hello, world!"),
+            Message("How can I help you today?", role="assistant"),
+            Message("I'm looking for a restaurant in the center of town."),
+        ]
+
+        async def fn() -> list[Message]:
+            return expected
+
+        prompt = Prompt.from_function(fn)
+        result = await prompt.render()
+        assert result.messages == expected
+
+    async def test_fn_returns_list_of_strings(self):
+        expected = [
+            "Hello, world!",
+            "I'm looking for a restaurant in the center of town.",
+        ]
+
+        async def fn() -> list[str]:
+            return expected
+
+        prompt = Prompt.from_function(fn)
+        result = await prompt.render()
+        assert result.messages == [Message(t) for t in expected]
+
+    async def test_fn_returns_resource_content(self):
+        """Test returning a message with resource content."""
+
+        async def fn() -> list[Message]:
+            return [
+                Message(
+                    content=EmbeddedResource(
+                        type="resource",
+                        resource=TextResourceContents(
+                            uri="file://file.txt",
+                            text="File contents",
+                            mime_type="text/plain",
+                        ),
+                    ),
+                    role="user",
+                )
+            ]
+
+        prompt = Prompt.from_function(fn)
+        result = await prompt.render()
+        assert result.messages == [
+            Message(
+                content=EmbeddedResource(
+                    type="resource",
+                    resource=TextResourceContents(
+                        uri="file://file.txt",
+                        text="File contents",
+                        mime_type="text/plain",
+                    ),
+                ),
+                role="user",
+            )
+        ]
+
+    async def test_fn_returns_mixed_content(self):
+        """Test returning messages with mixed content types."""
+
+        async def fn() -> list[Message | str]:
+            return [
+                "Please analyze this file:",
+                Message(
+                    content=EmbeddedResource(
+                        type="resource",
+                        resource=TextResourceContents(
+                            uri="file://file.txt",
+                            text="File contents",
+                            mime_type="text/plain",
+                        ),
+                    ),
+                    role="user",
+                ),
+                Message("I'll help analyze that file.", role="assistant"),
+            ]
+
+        prompt = Prompt.from_function(fn)
+        result = await prompt.render()
+        assert result.messages == [
+            Message("Please analyze this file:"),
+            Message(
+                content=EmbeddedResource(
+                    type="resource",
+                    resource=TextResourceContents(
+                        uri="file://file.txt",
+                        text="File contents",
+                        mime_type="text/plain",
+                    ),
+                ),
+                role="user",
+            ),
+            Message("I'll help analyze that file.", role="assistant"),
+        ]
+
+    async def test_fn_returns_message_with_resource(self):
+        """Test returning a message with resource content."""
+
+        async def fn() -> list[Message]:
+            return [
+                Message(
+                    content=EmbeddedResource(
+                        type="resource",
+                        resource=TextResourceContents(
+                            uri="file://file.txt",
+                            text="File contents",
+                            mime_type="text/plain",
+                        ),
+                    ),
+                    role="user",
+                )
+            ]
+
+        prompt = Prompt.from_function(fn)
+        result = await prompt.render()
+        assert result.messages == [
+            Message(
+                content=EmbeddedResource(
+                    type="resource",
+                    resource=TextResourceContents(
+                        uri="file://file.txt",
+                        text="File contents",
+                        mime_type="text/plain",
+                    ),
+                ),
+                role="user",
+            )
+        ]
+
+
+class TestPromptTypeConversion:
+    async def test_list_of_integers_as_string_args(self):
+        """Test that prompts can handle complex types passed as strings from MCP spec."""
+
+        def sum_numbers(numbers: list[int]) -> str:
+            """Calculate the sum of a list of numbers."""
+            total = sum(numbers)
+            return f"The sum is: {total}"
+
+        prompt = Prompt.from_function(sum_numbers)
+
+        # MCP spec only allows string arguments, so this should work
+        # after we implement type conversion
+        result_from_string = await prompt.render(
+            arguments={"numbers": "[1, 2, 3, 4, 5]"}
+        )
+        assert result_from_string.messages == [Message("The sum is: 15")]
+
+        # Both should work now with string conversion
+        result_from_list_string = await prompt.render(
+            arguments={"numbers": "[1, 2, 3, 4, 5]"}
+        )
+        assert result_from_list_string.messages == result_from_string.messages
+
+    async def test_various_type_conversions(self):
+        """Test type conversion for various data types."""
+
+        def process_data(
+            name: str,
+            age: int,
+            scores: list[float],
+            metadata: dict[str, str],
+            active: bool,
+        ) -> str:
+            return f"{name} ({age}): {len(scores)} scores, active={active}, metadata keys={list(metadata.keys())}"
+
+        prompt = Prompt.from_function(process_data)
+
+        # All arguments as strings (as MCP would send them)
+        result = await prompt.render(
+            arguments={
+                "name": "Alice",
+                "age": "25",
+                "scores": "[1.5, 2.0, 3.5]",
+                "metadata": '{"project": "test", "version": "1.0"}',
+                "active": "true",
+            }
+        )
+
+        expected_text = (
+            "Alice (25): 3 scores, active=True, metadata keys=['project', 'version']"
+        )
+        assert result.messages == [Message(expected_text)]
+
+    async def test_type_conversion_error_handling(self):
+        """Test that informative errors are raised for invalid type conversions."""
+        from fastmcp.exceptions import PromptError
+
+        def typed_prompt(numbers: list[int]) -> str:
+            return f"Got {len(numbers)} numbers"
+
+        prompt = Prompt.from_function(typed_prompt)
+
+        # Test with invalid JSON - should raise PromptError with type conversion details
+        with pytest.raises(PromptError) as exc_info:
+            await prompt.render(arguments={"numbers": "not valid json"})
+
+        # PromptError passes through unchanged
+        assert "Could not convert argument 'numbers'" in str(exc_info.value)
+        assert "list[int]" in str(exc_info.value)
+
+    async def test_json_parsing_fallback(self):
+        """Test that JSON parsing falls back to direct validation when needed."""
+
+        def data_prompt(value: int) -> str:
+            return f"Value: {value}"
+
+        prompt = Prompt.from_function(data_prompt)
+
+        # This should work with JSON parsing (integer as string)
+        result1 = await prompt.render(arguments={"value": "42"})
+        assert result1.messages == [Message("Value: 42")]
+
+        # This should work with direct validation (already an integer string)
+        result2 = await prompt.render(arguments={"value": "123"})
+        assert result2.messages == [Message("Value: 123")]
+
+    async def test_mixed_string_and_typed_args(self):
+        """Test mixing string args (no conversion) with typed args (conversion needed)."""
+
+        def mixed_prompt(message: str, count: int) -> str:
+            return f"{message} (repeated {count} times)"
+
+        prompt = Prompt.from_function(mixed_prompt)
+
+        result = await prompt.render(
+            arguments={
+                "message": "Hello world",  # str - no conversion needed
+                "count": "3",  # int - conversion needed
+            }
+        )
+
+        assert result.messages == [Message("Hello world (repeated 3 times)")]
+
+
+class TestPromptArgumentDescriptions:
+    def test_enhanced_descriptions_for_non_string_types(self):
+        """Test that non-string argument types get enhanced descriptions with JSON schema."""
+
+        def analyze_data(
+            name: str,
+            numbers: list[int],
+            metadata: dict[str, str],
+            threshold: float,
+            active: bool,
+        ) -> str:
+            """Analyze numerical data."""
+            return f"Analyzed {name}"
+
+        prompt = Prompt.from_function(analyze_data)
+
+        assert prompt.arguments is not None
+        # Check that string parameter has no schema enhancement
+        name_arg = next((arg for arg in prompt.arguments if arg.name == "name"), None)
+        assert name_arg is not None
+        assert name_arg.description is None  # No enhancement for string types
+
+        # Check that non-string parameters have schema enhancements
+        numbers_arg = next(
+            (arg for arg in prompt.arguments if arg.name == "numbers"), None
+        )
+        assert numbers_arg is not None
+        assert numbers_arg.description is not None
+        assert (
+            "Provide as a JSON string matching the following schema:"
+            in numbers_arg.description
+        )
+        assert '{"items":{"type":"integer"},"type":"array"}' in numbers_arg.description
+
+        metadata_arg = next(
+            (arg for arg in prompt.arguments if arg.name == "metadata"), None
+        )
+        assert metadata_arg is not None
+        assert metadata_arg.description is not None
+        assert (
+            "Provide as a JSON string matching the following schema:"
+            in metadata_arg.description
+        )
+        assert (
+            '{"additionalProperties":{"type":"string"},"type":"object"}'
+            in metadata_arg.description
+        )
+
+        threshold_arg = next(
+            (arg for arg in prompt.arguments if arg.name == "threshold"), None
+        )
+        assert threshold_arg is not None
+        assert threshold_arg.description is not None
+        assert (
+            "Provide as a JSON string matching the following schema:"
+            in threshold_arg.description
+        )
+        assert '{"type":"number"}' in threshold_arg.description
+
+        active_arg = next(
+            (arg for arg in prompt.arguments if arg.name == "active"), None
+        )
+        assert active_arg is not None
+        assert active_arg.description is not None
+        assert (
+            "Provide as a JSON string matching the following schema:"
+            in active_arg.description
+        )
+        assert '{"type":"boolean"}' in active_arg.description
+
+    def test_enhanced_descriptions_with_existing_descriptions(self):
+        """Test that existing parameter descriptions are preserved with schema appended."""
+        from typing import Annotated
+
+        from pydantic import Field
+
+        def documented_prompt(
+            numbers: Annotated[
+                list[int], Field(description="A list of integers to process")
+            ],
+        ) -> str:
+            """Process numbers."""
+            return "processed"
+
+        prompt = Prompt.from_function(documented_prompt)
+
+        assert prompt.arguments is not None
+        numbers_arg = next(
+            (arg for arg in prompt.arguments if arg.name == "numbers"), None
+        )
+        assert numbers_arg is not None
+        # Should have both the original description and the schema
+        assert numbers_arg.description is not None
+        assert "A list of integers to process" in numbers_arg.description
+        assert "\n\n" in numbers_arg.description  # Should have newline separator
+        assert (
+            "Provide as a JSON string matching the following schema:"
+            in numbers_arg.description
+        )
+
+    def test_string_parameters_no_enhancement(self):
+        """Test that string parameters don't get schema enhancement."""
+
+        def string_only_prompt(message: str, name: str) -> str:
+            return f"{message}, {name}"
+
+        prompt = Prompt.from_function(string_only_prompt)
+
+        assert prompt.arguments is not None
+        for arg in prompt.arguments:
+            # String parameters should not have schema enhancement
+            if arg.description is not None:
+                assert (
+                    "Provide as a JSON string matching the following schema:"
+                    not in arg.description
+                )
+
+    def test_docstring_populates_argument_descriptions(self):
+        """Google-style docstrings should populate PromptArgument descriptions."""
+
+        def greet(name: str, topic: str) -> str:
+            """Generate a greeting.
+
+            Args:
+                name: The person's name.
+                topic: The topic to discuss.
+            """
+            return f"Hello {name}, let's talk about {topic}"
+
+        prompt = Prompt.from_function(greet)
+
+        # Description is summary-only — Args section stripped
+        assert prompt.description == "Generate a greeting."
+
+        assert prompt.arguments is not None
+        name_arg = next(arg for arg in prompt.arguments if arg.name == "name")
+        topic_arg = next(arg for arg in prompt.arguments if arg.name == "topic")
+        assert name_arg.description == "The person's name."
+        assert topic_arg.description == "The topic to discuss."
+
+    def test_docstring_works_with_numpy_and_sphinx_styles(self):
+        def numpy_prompt(a: str) -> str:
+            """Do something.
+
+            Parameters
+            ----------
+            a
+                The first argument.
+            """
+            return a
+
+        def sphinx_prompt(a: str) -> str:
+            """Do something.
+
+            :param a: The first argument.
+            """
+            return a
+
+        numpy = Prompt.from_function(numpy_prompt)
+        sphinx = Prompt.from_function(sphinx_prompt)
+
+        for prompt in (numpy, sphinx):
+            assert prompt.description == "Do something."
+            assert prompt.arguments is not None
+            a_arg = next(arg for arg in prompt.arguments if arg.name == "a")
+            assert a_arg.description == "The first argument."
+
+    def test_explicit_field_description_overrides_docstring(self):
+        """Field(description=...) takes precedence over docstring."""
+        from typing import Annotated
+
+        from pydantic import Field
+
+        def greet(
+            name: Annotated[str, Field(description="From Field")],
+        ) -> str:
+            """Greet.
+
+            Args:
+                name: From docstring (ignored).
+            """
+            return f"Hello {name}"
+
+        prompt = Prompt.from_function(greet)
+        assert prompt.arguments is not None
+        name_arg = next(arg for arg in prompt.arguments if arg.name == "name")
+        # Field description wins over the docstring's "From docstring (ignored)".
+        # (The existing schema-hint suffix for Annotated params is appended
+        # afterwards and is unrelated to precedence.)
+        assert name_arg.description is not None
+        assert name_arg.description.startswith("From Field")
+        assert "From docstring" not in name_arg.description
+
+    def test_explicit_description_keeps_docstring_arg_descriptions(self):
+        """Overriding the prompt description does not drop docstring-sourced
+        argument descriptions — they come from separate parsing paths."""
+
+        def greet(name: str) -> str:
+            """Greet.
+
+            Args:
+                name: The person's name.
+            """
+            return f"Hello {name}"
+
+        prompt = Prompt.from_function(greet, description="Custom description")
+        assert prompt.description == "Custom description"
+        assert prompt.arguments is not None
+        name_arg = next(arg for arg in prompt.arguments if arg.name == "name")
+        assert name_arg.description == "The person's name."
+
+    def test_docstring_without_args_section(self):
+        """Summary-only docstrings produce a description with no arg descriptions."""
+
+        def greet(name: str) -> str:
+            """Just a summary."""
+            return f"Hello {name}"
+
+        prompt = Prompt.from_function(greet)
+        assert prompt.description == "Just a summary."
+        assert prompt.arguments is not None
+        name_arg = next(arg for arg in prompt.arguments if arg.name == "name")
+        assert name_arg.description is None
+
+    def test_callable_class_sources_description_from_class(self):
+        """Class docstring drives the prompt description, while __call__'s
+        Args section drives per-argument descriptions (since the arguments
+        are __call__'s, not the class's)."""
+
+        class MyPrompt:
+            """Class-level description."""
+
+            def __call__(self, name: str) -> str:
+                """Internal call doc.
+
+                Args:
+                    name: From call.
+                """
+                return f"Hello {name}"
+
+        prompt = Prompt.from_function(MyPrompt())
+        assert prompt.description == "Class-level description."
+        assert prompt.arguments is not None
+        name_arg = next(arg for arg in prompt.arguments if arg.name == "name")
+        assert name_arg.description == "From call."
+
+    def test_prompt_meta_parameter(self):
+        """Test that meta parameter is properly handled."""
+
+        def test_prompt(message: str) -> str:
+            return f"Response: {message}"
+
+        meta_data = {"version": "3.0", "type": "prompt"}
+        prompt = Prompt.from_function(test_prompt, meta=meta_data)
+
+        assert prompt.meta == meta_data
+        mcp_prompt = prompt.to_mcp_prompt()
+        # MCP prompt includes fastmcp meta, so check that our meta is included
+        assert mcp_prompt.meta is not None
+        assert meta_data.items() <= mcp_prompt.meta.items()
+
+
+class TestMessage:
+    def test_message_string_content(self):
+        """Test Message with string content."""
+        from mcp_types import TextContent
+
+        msg = Message("Hello, world!")
+        assert msg.role == "user"
+        assert isinstance(msg.content, TextContent)
+        assert msg.content.text == "Hello, world!"
+
+    def test_message_with_role(self):
+        """Test Message with explicit role."""
+        from mcp_types import TextContent
+
+        msg = Message("I can help.", role="assistant")
+        assert msg.role == "assistant"
+        assert isinstance(msg.content, TextContent)
+        assert msg.content.text == "I can help."
+
+    def test_message_auto_serializes_dict(self):
+        """Test Message auto-serializes dicts to JSON."""
+        from mcp_types import TextContent
+
+        msg = Message({"key": "value", "nested": {"a": 1}})
+        assert msg.role == "user"
+        assert isinstance(msg.content, TextContent)
+        assert '"key"' in msg.content.text
+        assert '"value"' in msg.content.text
+
+    def test_message_auto_serializes_list(self):
+        """Test Message auto-serializes lists to JSON."""
+        from mcp_types import TextContent
+
+        msg = Message(["item1", "item2", "item3"])
+        assert isinstance(msg.content, TextContent)
+        assert '["item1"' in msg.content.text
+
+    def test_message_to_mcp_prompt_message(self):
+        """Test conversion to MCP PromptMessage."""
+        from mcp_types import TextContent
+
+        msg = Message("Hello", role="assistant")
+        mcp_msg = msg.to_mcp_prompt_message()
+        assert mcp_msg.role == "assistant"
+        assert isinstance(mcp_msg.content, TextContent)
+        assert mcp_msg.content.text == "Hello"
+
+    def test_message_passthrough_image_content(self):
+        """Test Message passes through ImageContent without JSON serialization."""
+        from mcp_types import ImageContent
+
+        img = ImageContent(type="image", data="base64data", mime_type="image/png")
+        msg = Message(img, role="user")
+        assert isinstance(msg.content, ImageContent)
+        assert msg.content.data == "base64data"
+        assert msg.content.mime_type == "image/png"
+
+    def test_message_passthrough_audio_content(self):
+        """Test Message passes through AudioContent without JSON serialization."""
+        from mcp_types import AudioContent
+
+        audio = AudioContent(type="audio", data="base64audio", mime_type="audio/wav")
+        msg = Message(audio, role="user")
+        assert isinstance(msg.content, AudioContent)
+        assert msg.content.data == "base64audio"
+        assert msg.content.mime_type == "audio/wav"
+
+    def test_message_image_content_to_mcp_prompt_message(self):
+        """Test that ImageContent round-trips through to_mcp_prompt_message."""
+        from mcp_types import ImageContent
+
+        img = ImageContent(type="image", data="base64data", mime_type="image/png")
+        msg = Message(img, role="user")
+        mcp_msg = msg.to_mcp_prompt_message()
+        assert isinstance(mcp_msg.content, ImageContent)
+        assert mcp_msg.content.data == "base64data"
+
+
+class TestPromptResult:
+    def test_promptresult_from_string(self):
+        """Test PromptResult accepts string and wraps as Message."""
+        from mcp_types import TextContent
+
+        result = PromptResult("Hello!")
+        assert len(result.messages) == 1
+        assert isinstance(result.messages[0].content, TextContent)
+        assert result.messages[0].content.text == "Hello!"
+        assert result.messages[0].role == "user"
+
+    def test_promptresult_from_message_list(self):
+        """Test PromptResult accepts list of Messages."""
+        result = PromptResult(
+            [
+                Message("Question?"),
+                Message("Answer.", role="assistant"),
+            ]
+        )
+        assert len(result.messages) == 2
+        assert result.messages[0].role == "user"
+        assert result.messages[1].role == "assistant"
+
+    def test_promptresult_rejects_single_message(self):
+        """Test PromptResult rejects single Message (must be in list)."""
+        with pytest.raises(TypeError, match="must be str or list"):
+            PromptResult(Message("Hello"))  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+
+    def test_promptresult_rejects_dict(self):
+        """Test PromptResult rejects dict."""
+        with pytest.raises(TypeError, match="must be str or list"):
+            PromptResult({"key": "value"})  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+
+    def test_promptresult_with_meta(self):
+        """Test PromptResult with meta field."""
+        result = PromptResult(
+            "Hello!", meta={"priority": "high", "category": "greeting"}
+        )
+        assert result.meta == {"priority": "high", "category": "greeting"}
+
+    def test_promptresult_with_description(self):
+        """Test PromptResult with description field."""
+        result = PromptResult("Hello!", description="A greeting prompt")
+        assert result.description == "A greeting prompt"
+
+    def test_promptresult_to_mcp(self):
+        """Test conversion to MCP GetPromptResult."""
+        result = PromptResult(
+            [Message("Hello"), Message("World", role="assistant")],
+            description="Test",
+            meta={"key": "value"},
+        )
+        mcp_result = result.to_mcp_prompt_result()
+        assert len(mcp_result.messages) == 2
+        assert mcp_result.description == "Test"
+        assert mcp_result.meta == {"key": "value"}
+
+
+class TestPromptFieldDefaults:
+    """Test prompts with Field() defaults."""
+
+    async def test_field_with_default(self):
+        """Test that Field(default=...) correctly provides default values."""
+
+        from pydantic import Field
+
+        def prompt_with_defaults(
+            required: str = Field(description="Required parameter"),
+            optional: str = Field(
+                default="default_value", description="Optional parameter"
+            ),
+        ) -> str:
+            return f"required={required}, optional={optional}"
+
+        prompt = Prompt.from_function(prompt_with_defaults)
+        result = await prompt.render(arguments={"required": "test"})
+        assert result.messages == [Message("required=test, optional=default_value")]
+
+    async def test_annotated_field_with_default_in_signature(self):
+        """Test that Annotated[type, Field(...)] with default in signature works."""
+        from typing import Annotated
+
+        from pydantic import Field
+
+        def prompt_with_annotated(
+            required: Annotated[str, Field(description="Required parameter")],
+            optional: Annotated[
+                str, Field(description="Optional parameter")
+            ] = "default_value",
+        ) -> str:
+            return f"required={required}, optional={optional}"
+
+        prompt = Prompt.from_function(prompt_with_annotated)
+        result = await prompt.render(arguments={"required": "test"})
+        assert result.messages == [Message("required=test, optional=default_value")]
+
+    async def test_multiple_field_defaults(self):
+        """Test multiple parameters with Field() defaults."""
+        from pydantic import Field
+
+        def prompt_with_multiple_defaults(
+            name: str = Field(description="Name"),
+            greeting: str = Field(default="Hello", description="Greeting"),
+            punctuation: str = Field(default="!", description="Punctuation"),
+        ) -> str:
+            return f"{greeting}, {name}{punctuation}"
+
+        prompt = Prompt.from_function(prompt_with_multiple_defaults)
+
+        # Test with only required parameter
+        result1 = await prompt.render(arguments={"name": "World"})
+        assert result1.messages == [Message("Hello, World!")]
+
+        # Test overriding one default
+        result2 = await prompt.render(arguments={"name": "World", "greeting": "Hi"})
+        assert result2.messages == [Message("Hi, World!")]
+
+        # Test overriding all defaults
+        result3 = await prompt.render(
+            arguments={"name": "World", "greeting": "Greetings", "punctuation": "."}
+        )
+        assert result3.messages == [Message("Greetings, World.")]
+
+    async def test_field_defaults_with_type_conversion(self):
+        """Test Field() defaults work with type conversion for non-string types."""
+        from pydantic import Field
+
+        def prompt_with_typed_defaults(
+            count: int = Field(description="Count"),
+            multiplier: int = Field(default=2, description="Multiplier"),
+        ) -> str:
+            return f"result={count * multiplier}"
+
+        prompt = Prompt.from_function(prompt_with_typed_defaults)
+
+        # Pass count as string (MCP requirement), should use default for multiplier
+        result = await prompt.render(arguments={"count": "5"})
+        assert result.messages == [Message("result=10")]
+
+
+class TestPromptCallableAndConcurrency:
+    """Test prompts with callable objects and concurrent execution."""
+
+    async def test_callable_object_sync(self):
+        """Test that callable objects with sync __call__ work."""
+
+        class MyPrompt:
+            def __init__(self, greeting: str):
+                self.greeting = greeting
+
+            def __call__(self) -> str:
+                return f"{self.greeting}, world!"
+
+        prompt = Prompt.from_function(MyPrompt("Hello"))
+        result = await prompt.render()
+        assert result.messages == [Message("Hello, world!")]
+
+    async def test_callable_object_async(self):
+        """Test that callable objects with async __call__ work."""
+
+        class AsyncPrompt:
+            def __init__(self, greeting: str):
+                self.greeting = greeting
+
+            async def __call__(self) -> str:
+                return f"async {self.greeting}!"
+
+        prompt = Prompt.from_function(AsyncPrompt("Hello"))
+        result = await prompt.render()
+        assert result.messages == [Message("async Hello!")]
+
+    async def test_sync_prompt_runs_concurrently(self):
+        """Test that sync prompts run in threadpool and don't block each other."""
+        import asyncio
+        import threading
+
+        num_calls = 3
+        barrier = threading.Barrier(num_calls, timeout=0.5)
+
+        def concurrent_prompt() -> str:
+            barrier.wait()
+            return "done"
+
+        prompt = Prompt.from_function(concurrent_prompt)
+
+        # Run concurrent renders - will raise BrokenBarrierError if not concurrent
+        results = await asyncio.gather(
+            prompt.render(),
+            prompt.render(),
+            prompt.render(),
+        )
+        assert all(r.messages == [Message("done")] for r in results)
diff --git a/tests/prompts/test_standalone_decorator.py b/tests/prompts/test_standalone_decorator.py
new file mode 100644
index 0000000..ba5bb5e
--- /dev/null
+++ b/tests/prompts/test_standalone_decorator.py
@@ -0,0 +1,155 @@
+"""Tests for the standalone @prompt decorator.
+
+The @prompt decorator attaches metadata to functions without registering them
+to a server. Functions can be added explicitly via server.add_prompt() or
+discovered by FileSystemProvider.
+"""
+
+from typing import cast
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.prompts import prompt
+from fastmcp.prompts.function_prompt import DecoratedPrompt, PromptMeta
+
+
+class TestPromptDecorator:
+    """Tests for the @prompt decorator."""
+
+    def test_prompt_without_parens(self):
+        """@prompt without parentheses should attach metadata."""
+
+        @prompt
+        def analyze(topic: str) -> str:
+            return f"Analyze: {topic}"
+
+        decorated = cast(DecoratedPrompt, analyze)
+        assert callable(analyze)
+        assert hasattr(analyze, "__fastmcp__")
+        assert isinstance(decorated.__fastmcp__, PromptMeta)
+        assert decorated.__fastmcp__.name is None  # Uses function name by default
+
+    def test_prompt_with_empty_parens(self):
+        """@prompt() with empty parentheses should attach metadata."""
+
+        @prompt()
+        def analyze(topic: str) -> str:
+            return f"Analyze: {topic}"
+
+        decorated = cast(DecoratedPrompt, analyze)
+        assert callable(analyze)
+        assert hasattr(analyze, "__fastmcp__")
+        assert isinstance(decorated.__fastmcp__, PromptMeta)
+
+    def test_prompt_with_name_arg(self):
+        """@prompt("name") with name as first arg should work."""
+
+        @prompt("custom-analyze")
+        def analyze(topic: str) -> str:
+            return f"Analyze: {topic}"
+
+        decorated = cast(DecoratedPrompt, analyze)
+        assert callable(analyze)
+        assert hasattr(analyze, "__fastmcp__")
+        assert decorated.__fastmcp__.name == "custom-analyze"
+
+    def test_prompt_with_name_kwarg(self):
+        """@prompt(name="name") with keyword arg should work."""
+
+        @prompt(name="custom-analyze")
+        def analyze(topic: str) -> str:
+            return f"Analyze: {topic}"
+
+        decorated = cast(DecoratedPrompt, analyze)
+        assert callable(analyze)
+        assert hasattr(analyze, "__fastmcp__")
+        assert decorated.__fastmcp__.name == "custom-analyze"
+
+    def test_prompt_with_all_metadata(self):
+        """@prompt with all metadata should store it all."""
+
+        @prompt(
+            name="custom-analyze",
+            title="Analysis Prompt",
+            description="Analyzes topics",
+            tags={"analysis", "demo"},
+            meta={"custom": "value"},
+        )
+        def analyze(topic: str) -> str:
+            return f"Analyze: {topic}"
+
+        decorated = cast(DecoratedPrompt, analyze)
+        assert callable(analyze)
+        assert hasattr(analyze, "__fastmcp__")
+        assert decorated.__fastmcp__.name == "custom-analyze"
+        assert decorated.__fastmcp__.title == "Analysis Prompt"
+        assert decorated.__fastmcp__.description == "Analyzes topics"
+        assert decorated.__fastmcp__.tags == {"analysis", "demo"}
+        assert decorated.__fastmcp__.meta == {"custom": "value"}
+
+    async def test_prompt_function_still_callable(self):
+        """Decorated function should still be directly callable."""
+
+        @prompt
+        def analyze(topic: str) -> str:
+            """Analyze a topic."""
+            return f"Please analyze: {topic}"
+
+        # The function is still callable even though it has metadata
+        result = cast(DecoratedPrompt, analyze)("Python")
+        assert result == "Please analyze: Python"
+
+    async def test_staticmethod_metadata_is_available_on_unwrapped_function(self):
+        """@prompt should attach metadata where staticmethod access can find it."""
+
+        class MyClass:
+            @prompt(name="custom-static-prompt")
+            @staticmethod
+            def my_prompt() -> str:
+                return "hello"
+
+        mcp = FastMCP("Test")
+        mcp.add_prompt(MyClass.my_prompt)
+
+        async with Client(mcp) as client:
+            prompts = await client.list_prompts()
+
+        assert any(p.name == "custom-static-prompt" for p in prompts)
+
+    def test_prompt_rejects_classmethod_decorator(self):
+        """@prompt should reject classmethod-decorated functions."""
+        with pytest.raises(TypeError, match="classmethod"):
+
+            class MyClass:
+                @prompt
+                @classmethod
+                def my_prompt(cls, topic: str) -> str:
+                    return f"Analyze: {topic}"
+
+    def test_prompt_with_both_name_args_raises(self):
+        """@prompt should raise if both positional and keyword name are given."""
+        with pytest.raises(TypeError, match="Cannot specify.*both.*argument.*keyword"):
+
+            @prompt("name1", name="name2")  # type: ignore[call-overload]  # ty:ignore[invalid-argument-type]
+            def my_prompt() -> str:
+                return "hello"
+
+    async def test_prompt_added_to_server(self):
+        """Prompt created by @prompt should work when added to a server."""
+
+        @prompt
+        def analyze(topic: str) -> str:
+            """Analyze a topic."""
+            return f"Please analyze: {topic}"
+
+        mcp = FastMCP("Test")
+        mcp.add_prompt(analyze)
+
+        async with Client(mcp) as client:
+            prompts = await client.list_prompts()
+            assert any(p.name == "analyze" for p in prompts)
+
+            result = await client.get_prompt("analyze", {"topic": "FastMCP"})
+            assert "FastMCP" in str(result)
diff --git a/tests/resources/__init__.py b/tests/resources/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/resources/test_file_resources.py b/tests/resources/test_file_resources.py
new file mode 100644
index 0000000..cf8fb0c
--- /dev/null
+++ b/tests/resources/test_file_resources.py
@@ -0,0 +1,181 @@
+import os
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+
+import pytest
+from pydantic import FileUrl
+
+from fastmcp.exceptions import ResourceError
+from fastmcp.resources import FileResource
+from fastmcp.resources.base import ResourceResult
+
+
+@pytest.fixture
+def temp_file():
+    """Create a temporary file for testing.
+
+    File is automatically cleaned up after the test if it still exists.
+    """
+    content = "test content"
+    with NamedTemporaryFile(mode="w", delete=False) as f:
+        f.write(content)
+        path = Path(f.name).resolve()
+    yield path
+    try:
+        path.unlink()
+    except FileNotFoundError:
+        pass  # File was already deleted by the test
+
+
+class TestFileResource:
+    """Test FileResource functionality."""
+
+    def test_file_resource_creation(self, temp_file: Path):
+        """Test creating a FileResource."""
+        resource = FileResource(
+            uri=FileUrl(temp_file.as_uri()),
+            name="test",
+            description="test file",
+            path=temp_file,
+        )
+        assert str(resource.uri) == temp_file.as_uri()
+        assert resource.name == "test"
+        assert resource.description == "test file"
+        assert resource.mime_type == "text/plain"  # default
+        assert resource.path == temp_file
+        assert resource.is_binary is False  # default
+
+    def test_file_resource_str_path_conversion(self, temp_file: Path):
+        """Test FileResource handles string paths."""
+        resource = FileResource(
+            uri=FileUrl(f"file://{temp_file}"),
+            name="test",
+            path=Path(str(temp_file)),
+        )
+        assert isinstance(resource.path, Path)
+        assert resource.path.is_absolute()
+
+    async def test_read_text_file(self, temp_file: Path):
+        """Test reading a text file."""
+        resource = FileResource(
+            uri=FileUrl(f"file://{temp_file}"),
+            name="test",
+            path=temp_file,
+        )
+        result = await resource.read()
+        assert isinstance(result, ResourceResult)
+        assert len(result.contents) == 1
+        assert result.contents[0].content == "test content"
+        assert result.contents[0].mime_type == "text/plain"
+
+    async def test_read_binary_file(self, temp_file: Path):
+        """Test reading a file as binary."""
+        resource = FileResource(
+            uri=FileUrl(f"file://{temp_file}"),
+            name="test",
+            path=temp_file,
+            is_binary=True,
+        )
+        result = await resource.read()
+        assert isinstance(result, ResourceResult)
+        assert len(result.contents) == 1
+        assert result.contents[0].content == b"test content"
+
+    def test_relative_path_error(self):
+        """Test error on relative path."""
+        with pytest.raises(ValueError, match="Path must be absolute"):
+            FileResource(
+                uri=FileUrl("file:///test.txt"),
+                name="test",
+                path=Path("test.txt"),
+            )
+
+    async def test_missing_file_error(self, temp_file: Path):
+        """Test error when file doesn't exist."""
+        # Create path to non-existent file
+        missing = temp_file.parent / "missing.txt"
+        resource = FileResource(
+            uri=FileUrl("file:///missing.txt"),
+            name="test",
+            path=missing,
+        )
+        with pytest.raises(ResourceError, match="Error reading file"):
+            await resource.read()
+
+    @pytest.mark.skipif(
+        os.name == "nt" or (hasattr(os, "getuid") and os.getuid() == 0),
+        reason="File permissions behave differently on Windows or when running as root",
+    )
+    async def test_permission_error(self, temp_file: Path):
+        """Test reading a file without permissions."""
+        temp_file.chmod(0o000)  # Remove all permissions
+        try:
+            resource = FileResource(
+                uri=FileUrl(temp_file.as_uri()),
+                name="test",
+                path=temp_file,
+            )
+            with pytest.raises(ResourceError, match="Error reading file"):
+                await resource.read()
+        finally:
+            temp_file.chmod(0o644)  # Restore permissions
+
+    async def test_read_utf8_with_encoding(self, tmp_path: Path):
+        """FileResource should read UTF-8 files correctly when encoding is specified."""
+        content = (
+            "Smart quotes: \u201cleft\u201d and apostrophe\u2019s em-dash\u2014here"
+        )
+        file = tmp_path / "utf8_test.md"
+        file.write_text(content, encoding="utf-8")
+
+        resource = FileResource(
+            uri=FileUrl("file:///test/utf8"),
+            path=file,
+            mime_type="text/markdown",
+            encoding="utf-8",
+        )
+        result = await resource.read()
+        assert result.contents[0].content == content
+
+    async def test_default_encoding_is_utf8(self, tmp_path: Path):
+        """FileResource defaults to UTF-8, reading non-ASCII without explicit encoding."""
+        content = "Smart quotes: \u201cleft\u201d and em-dash\u2014here"
+        file = tmp_path / "default_utf8_test.txt"
+        file.write_text(content, encoding="utf-8")
+
+        resource = FileResource(
+            uri=FileUrl("file:///test/default"),
+            path=file,
+        )
+        assert resource.encoding == "utf-8"
+        result = await resource.read()
+        assert result.contents[0].content == content
+
+    async def test_encoding_ignored_for_binary(self, tmp_path: Path):
+        """Encoding field should be ignored when is_binary=True."""
+        data = b"\x00\x01\x02\xff"
+        file = tmp_path / "binary_test.bin"
+        file.write_bytes(data)
+
+        resource = FileResource(
+            uri=FileUrl("file:///test/binary"),
+            path=file,
+            mime_type="application/octet-stream",
+            encoding="utf-8",
+        )
+        result = await resource.read()
+        assert result.contents[0].content == data
+
+    async def test_read_latin1_with_encoding(self, tmp_path: Path):
+        """FileResource should read non-UTF-8 files when correct encoding is specified."""
+        content = "na\u00efve"
+        file = tmp_path / "latin1_test.txt"
+        file.write_text(content, encoding="latin-1")
+
+        resource = FileResource(
+            uri=FileUrl("file:///test/latin1"),
+            path=file,
+            encoding="latin-1",
+        )
+        result = await resource.read()
+        assert result.contents[0].content == content
diff --git a/tests/resources/test_function_resources.py b/tests/resources/test_function_resources.py
new file mode 100644
index 0000000..20561a9
--- /dev/null
+++ b/tests/resources/test_function_resources.py
@@ -0,0 +1,352 @@
+import pytest
+from pydantic import AnyUrl, BaseModel
+
+from fastmcp.resources.base import ResourceContent
+from fastmcp.resources.function_resource import FunctionResource
+
+
+class TestFunctionResource:
+    """Test FunctionResource functionality."""
+
+    def test_function_resource_creation(self):
+        """Test creating a FunctionResource."""
+
+        def my_func() -> str:
+            return "test content"
+
+        resource = FunctionResource(
+            uri=AnyUrl("fn://test"),
+            name="test",
+            description="test function",
+            fn=my_func,
+        )
+        assert str(resource.uri) == "fn://test"
+        assert resource.name == "test"
+        assert resource.description == "test function"
+        assert resource.mime_type == "text/plain"  # default
+        assert resource.fn == my_func
+
+    async def test_read_text(self):
+        """Test reading text from a FunctionResource."""
+
+        def get_data() -> str:
+            return "Hello, world!"
+
+        resource = FunctionResource(
+            uri=AnyUrl("function://test"),
+            name="test",
+            fn=get_data,
+        )
+        # read() returns raw value
+        result = await resource.read()
+        assert result == "Hello, world!"
+
+        # _read() converts to ResourceResult
+        result = await resource._read()
+        assert len(result.contents) == 1
+        assert result.contents[0].content == "Hello, world!"
+        assert result.contents[0].mime_type == "text/plain"
+
+    async def test_read_binary(self):
+        """Test reading binary data from a FunctionResource."""
+
+        def get_data() -> bytes:
+            return b"Hello, world!"
+
+        resource = FunctionResource(
+            uri=AnyUrl("function://test"),
+            name="test",
+            fn=get_data,
+        )
+        # read() returns raw value
+        result = await resource.read()
+        assert result == b"Hello, world!"
+
+        # _read() converts to ResourceResult
+        result = await resource._read()
+        assert result.contents[0].content == b"Hello, world!"
+
+    async def test_dict_return_auto_serializes(self):
+        """Returning dict from read() auto-serializes to JSON."""
+
+        def get_data() -> dict:
+            return {"key": "value"}
+
+        resource = FunctionResource(
+            uri=AnyUrl("function://test"),
+            name="test",
+            fn=get_data,
+        )
+        # read() returns raw value (no type checking at runtime)
+        result = await resource.read()
+        assert result == {"key": "value"}
+
+        # _read() auto-serializes dict to JSON text
+        resource_result = await resource._read()
+        assert len(resource_result.contents) == 1
+        assert '"key"' in str(resource_result.contents[0].content)
+
+    async def test_error_handling(self):
+        """Test error handling in FunctionResource."""
+
+        def failing_func() -> str:
+            raise ValueError("Test error")
+
+        resource = FunctionResource(
+            uri=AnyUrl("function://test"),
+            name="test",
+            fn=failing_func,
+        )
+        with pytest.raises(ValueError, match="Test error"):
+            await resource.read()
+
+    async def test_basemodel_return_raises_type_error(self):
+        """Returning BaseModel from read() raises TypeError - use ResourceResult."""
+
+        class MyModel(BaseModel):
+            name: str
+
+        resource = FunctionResource(
+            uri=AnyUrl("function://test"),
+            name="test",
+            fn=lambda: MyModel(name="test"),
+        )
+        # read() returns raw value (no type checking at runtime)
+        raw_result = await resource.read()
+        assert isinstance(raw_result, MyModel)
+
+        # _read() raises TypeError - must return str, bytes, or ResourceResult
+        with pytest.raises(TypeError, match="must be str, bytes, or list"):
+            await resource._read()
+
+    async def test_custom_type_return_raises_type_error(self):
+        """Returning custom type from read() raises TypeError - use ResourceResult."""
+
+        class CustomData:
+            def __str__(self) -> str:
+                return "custom data"
+
+        def get_data() -> CustomData:
+            return CustomData()
+
+        resource = FunctionResource(
+            uri=AnyUrl("function://test"),
+            name="test",
+            fn=get_data,
+        )
+        # read() returns raw value (no type checking at runtime)
+        raw_result = await resource.read()
+        assert isinstance(raw_result, CustomData)
+
+        # _read() raises TypeError - must return str, bytes, or ResourceResult
+        with pytest.raises(TypeError, match="must be str, bytes, or list"):
+            await resource._read()
+
+    async def test_async_read_text(self):
+        """Test reading text from async FunctionResource."""
+
+        async def get_data() -> str:
+            return "Hello, world!"
+
+        resource = FunctionResource(
+            uri=AnyUrl("function://test"),
+            name="test",
+            fn=get_data,
+        )
+        # read() returns raw value
+        result = await resource.read()
+        assert result == "Hello, world!"
+
+        # _read() converts to ResourceResult
+        result = await resource._read()
+        assert result.contents[0].content == "Hello, world!"
+        assert result.contents[0].mime_type == "text/plain"
+
+    async def test_sync_function_returning_awaitable_is_awaited(self):
+        """Test sync wrappers that return awaitables."""
+
+        async def get_data() -> str:
+            return "Hello from awaitable"
+
+        def sync_wrapper():
+            return get_data()
+
+        resource = FunctionResource(
+            uri=AnyUrl("function://test"),
+            name="test",
+            fn=sync_wrapper,
+        )
+
+        assert await resource.read() == "Hello from awaitable"
+
+    async def test_resource_content_text(self):
+        """Test returning ResourceContent with text content."""
+
+        def get_data() -> ResourceContent:
+            return ResourceContent(
+                content="Hello, world!",
+                mime_type="text/html",
+                meta={"csp": "script-src 'self'"},
+            )
+
+        resource = FunctionResource(
+            uri=AnyUrl("function://test"),
+            name="test",
+            fn=get_data,
+        )
+        result = await resource.read()
+        assert isinstance(result, ResourceContent)
+        assert result.content == "Hello, world!"
+        assert result.mime_type == "text/html"
+        assert result.meta == {"csp": "script-src 'self'"}
+
+    async def test_resource_content_binary(self):
+        """Test returning ResourceContent with binary content."""
+
+        def get_data() -> ResourceContent:
+            return ResourceContent(
+                content=b"\x00\x01\x02",
+                mime_type="application/octet-stream",
+            )
+
+        resource = FunctionResource(
+            uri=AnyUrl("function://test"),
+            name="test",
+            fn=get_data,
+        )
+        result = await resource.read()
+        assert isinstance(result, ResourceContent)
+        assert result.content == b"\x00\x01\x02"
+        assert result.mime_type == "application/octet-stream"
+        assert result.meta is None
+
+    async def test_resource_content_without_meta(self):
+        """Test that ResourceContent auto-sets mime_type defaults."""
+        content = ResourceContent(content="plain text")
+        assert content.content == "plain text"
+        assert content.mime_type == "text/plain"  # Auto-set for string content
+        assert content.meta is None
+
+    async def test_async_resource_content(self):
+        """Test async function returning ResourceContent."""
+
+        async def get_data() -> ResourceContent:
+            return ResourceContent(
+                content="async content",
+                meta={"key": "value"},
+            )
+
+        resource = FunctionResource(
+            uri=AnyUrl("function://test"),
+            name="test",
+            fn=get_data,
+        )
+        result = await resource.read()
+        assert isinstance(result, ResourceContent)
+        assert result.content == "async content"
+        assert result.meta == {"key": "value"}
+
+
+class TestResourceContentToMcp:
+    """Test ResourceContent.to_mcp_resource_contents method."""
+
+    def test_text_content_to_mcp(self):
+        """Test converting text ResourceContent to MCP type."""
+        rc = ResourceContent(
+            content="hello world",
+            mime_type="text/html",
+            meta={"csp": "script-src 'self'"},
+        )
+        mcp_content = rc.to_mcp_resource_contents("resource://test")
+
+        assert hasattr(mcp_content, "text")
+        assert mcp_content.text == "hello world"
+        assert mcp_content.mime_type == "text/html"
+        assert mcp_content.meta == {"csp": "script-src 'self'"}
+
+    def test_binary_content_to_mcp(self):
+        """Test converting binary ResourceContent to MCP type."""
+        rc = ResourceContent(
+            content=b"\x00\x01\x02",
+            mime_type="application/octet-stream",
+            meta={"encoding": "raw"},
+        )
+        mcp_content = rc.to_mcp_resource_contents("resource://test")
+
+        assert hasattr(mcp_content, "blob")
+        assert mcp_content.blob == "AAEC"  # base64 of \x00\x01\x02
+        assert mcp_content.mime_type == "application/octet-stream"
+        assert mcp_content.meta == {"encoding": "raw"}
+
+    def test_default_mime_types(self):
+        """Test default mime types are applied correctly."""
+        text_rc = ResourceContent(content="text")
+        text_mcp = text_rc.to_mcp_resource_contents("resource://test")
+        assert text_mcp.mime_type == "text/plain"
+
+        binary_rc = ResourceContent(content=b"binary")
+        binary_mcp = binary_rc.to_mcp_resource_contents("resource://test")
+        assert binary_mcp.mime_type == "application/octet-stream"
+
+    def test_none_meta(self):
+        """Test that None meta is handled correctly."""
+        rc = ResourceContent(content="no meta")
+        mcp_content = rc.to_mcp_resource_contents("resource://test")
+
+        assert mcp_content.meta is None
+
+
+class TestFunctionResourceCallable:
+    """Test FunctionResource with callable objects."""
+
+    async def test_callable_object_sync(self):
+        """Test that callable objects with sync __call__ work."""
+
+        class MyResource:
+            def __init__(self, value: str):
+                self.value = value
+
+            def __call__(self) -> str:
+                return f"value: {self.value}"
+
+        resource = FunctionResource.from_function(MyResource("test"), uri="fn://test")
+        result = await resource.read()
+        assert result == "value: test"
+
+    async def test_callable_object_async(self):
+        """Test that callable objects with async __call__ work."""
+
+        class AsyncResource:
+            def __init__(self, value: str):
+                self.value = value
+
+            async def __call__(self) -> str:
+                return f"async value: {self.value}"
+
+        resource = FunctionResource.from_function(
+            AsyncResource("test"), uri="fn://test"
+        )
+        result = await resource.read()
+        assert result == "async value: test"
+
+    async def test_sync_resource_runs_concurrently(self):
+        """Test that sync resources run in threadpool and don't block each other."""
+        import asyncio
+        import threading
+
+        num_calls = 3
+        barrier = threading.Barrier(num_calls, timeout=0.5)
+
+        def concurrent_resource() -> str:
+            barrier.wait()
+            return "done"
+
+        resource = FunctionResource.from_function(concurrent_resource, uri="fn://test")
+
+        # Run concurrent reads - will raise BrokenBarrierError if not concurrent
+        results = await asyncio.gather(
+            resource.read(),
+            resource.read(),
+            resource.read(),
+        )
+        assert results == ["done", "done", "done"]
diff --git a/tests/resources/test_resource_template.py b/tests/resources/test_resource_template.py
new file mode 100644
index 0000000..d4238cd
--- /dev/null
+++ b/tests/resources/test_resource_template.py
@@ -0,0 +1,1016 @@
+import functools
+from urllib.parse import quote
+
+import pytest
+from pydantic import BaseModel
+
+from fastmcp import Context, FastMCP
+from fastmcp.resources import ResourceTemplate
+from fastmcp.resources.function_resource import FunctionResource
+from fastmcp.resources.template import (
+    build_regex,
+    expand_uri_template,
+    match_uri_template,
+)
+
+
+class TestResourceTemplate:
+    """Test ResourceTemplate functionality."""
+
+    def test_template_creation(self):
+        """Test creating a template from a function."""
+
+        def my_func(key: str, value: int) -> dict:
+            return {"key": key, "value": value}
+
+        template = ResourceTemplate.from_function(
+            fn=my_func,
+            uri_template="test://{key}/{value}",
+            name="test",
+        )
+        assert template.uri_template == "test://{key}/{value}"
+        assert template.name == "test"
+        assert template.mime_type == "text/plain"  # default
+
+        assert template.fn(key="test", value=42) == my_func(key="test", value=42)
+
+    def test_template_matches(self):
+        """Test matching URIs against a template."""
+
+        def my_func(key: str, value: int) -> dict:
+            return {"key": key, "value": value}
+
+        template = ResourceTemplate.from_function(
+            fn=my_func,
+            uri_template="test://{key}/{value}",
+            name="test",
+        )
+
+        # Valid match
+        params = template.matches("test://foo/123")
+        assert params == {"key": "foo", "value": "123"}
+
+        # No match
+        assert template.matches("test://foo") is None
+        assert template.matches("other://foo/123") is None
+
+    def test_template_matches_with_prefix(self):
+        """Test matching URIs against a template with a prefix."""
+
+        def my_func(key: str, value: int) -> dict:
+            return {"key": key, "value": value}
+
+        template = ResourceTemplate.from_function(
+            fn=my_func,
+            uri_template="app+test://{key}/{value}",
+            name="test",
+        )
+
+        # Valid match
+        params = template.matches("app+test://foo/123")
+        assert params == {"key": "foo", "value": "123"}
+
+        # No match
+        assert template.matches("test://foo/123") is None
+        assert template.matches("test://foo") is None
+        assert template.matches("other://foo/123") is None
+
+    def test_template_uri_validation(self):
+        """Test validation rule: URI template must have at least one parameter."""
+
+        def my_func() -> dict:
+            return {"data": "value"}
+
+        with pytest.raises(
+            ValueError, match="URI template must contain at least one parameter"
+        ):
+            ResourceTemplate.from_function(
+                fn=my_func,
+                uri_template="test://no-params",
+                name="test",
+            )
+
+    def test_template_uri_params_subset_of_function_params(self):
+        """Test validation rule: URI parameters must be a subset of function parameters."""
+
+        def my_func(key: str, value: int) -> dict:
+            return {"key": key, "value": value}
+
+        # This should work - URI params are a subset of function params
+        template = ResourceTemplate.from_function(
+            fn=my_func,
+            uri_template="test://{key}/{value}",
+            name="test",
+        )
+        assert template.uri_template == "test://{key}/{value}"
+
+        # This should fail - 'unknown' is not a function parameter
+        with pytest.raises(
+            ValueError,
+            match="Required function arguments .* must be a subset of the URI path parameters",
+        ):
+            ResourceTemplate.from_function(
+                fn=my_func,
+                uri_template="test://{key}/{unknown}",
+                name="test",
+            )
+
+    def test_required_params_subset_of_uri_params(self):
+        """Test validation rule: Required function parameters must be in URI parameters."""
+
+        # Function with required parameters
+        def func_with_required(
+            required_param: str, optional_param: str = "default"
+        ) -> dict:
+            return {"required": required_param, "optional": optional_param}
+
+        # This should work - required param is in URI
+        template = ResourceTemplate.from_function(
+            fn=func_with_required,
+            uri_template="test://{required_param}",
+            name="test",
+        )
+        assert template.uri_template == "test://{required_param}"
+
+        # This should fail - required param is not in URI
+        with pytest.raises(
+            ValueError,
+            match="Required function arguments .* must be a subset of the URI path parameters",
+        ):
+            ResourceTemplate.from_function(
+                fn=func_with_required,
+                uri_template="test://{optional_param}",
+                name="test",
+            )
+
+    def test_multiple_required_params(self):
+        """Test validation with multiple required parameters."""
+
+        def multi_required(param1: str, param2: int, optional: str = "default") -> dict:
+            return {"p1": param1, "p2": param2, "opt": optional}
+
+        # This works - all required params in URI
+        template = ResourceTemplate.from_function(
+            fn=multi_required,
+            uri_template="test://{param1}/{param2}",
+            name="test",
+        )
+        assert template.uri_template == "test://{param1}/{param2}"
+
+        # This fails - missing one required param
+        with pytest.raises(
+            ValueError,
+            match="Required function arguments .* must be a subset of the URI path parameters",
+        ):
+            ResourceTemplate.from_function(
+                fn=multi_required,
+                uri_template="test://{param1}",
+                name="test",
+            )
+
+    async def test_create_resource(self):
+        """Test creating a resource from a template."""
+
+        def my_func(key: str, value: int) -> str:
+            return f"key={key}, value={value}"
+
+        template = ResourceTemplate.from_function(
+            fn=my_func,
+            uri_template="test://{key}/{value}",
+            name="test",
+        )
+
+        resource = await template.create_resource(
+            "test://foo/123",
+            {"key": "foo", "value": 123},
+        )
+
+        assert isinstance(resource, FunctionResource)
+        # read() returns raw value from function
+        result = await resource.read()
+        assert result == "key=foo, value=123"
+
+        # _read() wraps in ResourceResult
+        resource_result = await resource._read()
+        assert len(resource_result.contents) == 1
+        assert resource_result.contents[0].content == "key=foo, value=123"
+
+    async def test_async_text_resource(self):
+        """Test creating a text resource from async function."""
+
+        async def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        template = ResourceTemplate.from_function(
+            fn=greet,
+            uri_template="greet://{name}",
+            name="greeter",
+        )
+
+        resource = await template.create_resource(
+            "greet://world",
+            {"name": "world"},
+        )
+
+        assert isinstance(resource, FunctionResource)
+        # read() returns raw value
+        result = await resource.read()
+        assert result == "Hello, world!"
+
+    async def test_async_binary_resource(self):
+        """Test creating a binary resource from async function."""
+
+        async def get_bytes(value: str) -> bytes:
+            return value.encode()
+
+        template = ResourceTemplate.from_function(
+            fn=get_bytes,
+            uri_template="bytes://{value}",
+            name="bytes",
+        )
+
+        resource = await template.create_resource(
+            "bytes://test",
+            {"value": "test"},
+        )
+
+        assert isinstance(resource, FunctionResource)
+        # read() returns raw bytes
+        result = await resource.read()
+        assert result == b"test"
+
+    async def test_basemodel_conversion(self):
+        """Test handling of BaseModel types."""
+
+        class MyModel(BaseModel):
+            key: str
+            value: int
+
+        def get_data(key: str, value: int) -> MyModel:
+            return MyModel(key=key, value=value)
+
+        template = ResourceTemplate.from_function(
+            fn=get_data,
+            uri_template="test://{key}/{value}",
+            name="test",
+        )
+
+        resource = await template.create_resource(
+            "test://foo/123",
+            {"key": "foo", "value": 123},
+        )
+
+        assert isinstance(resource, FunctionResource)
+        # read() returns raw BaseModel
+        result = await resource.read()
+        assert isinstance(result, MyModel)
+        data = result.model_dump()
+        assert data == {"key": "foo", "value": 123}
+
+    async def test_custom_type_conversion(self):
+        """Test handling of custom types."""
+
+        class CustomData:
+            def __init__(self, value: str):
+                self.value = value
+
+            def __str__(self) -> str:
+                return self.value
+
+        def get_data(value: str) -> CustomData:
+            return CustomData(value)
+
+        template = ResourceTemplate.from_function(
+            fn=get_data,
+            uri_template="test://{value}",
+            name="test",
+        )
+
+        resource = await template.create_resource(
+            "test://hello",
+            {"value": "hello"},
+        )
+
+        assert isinstance(resource, FunctionResource)
+        # read() returns raw CustomData object
+        result = await resource.read()
+        assert isinstance(result, CustomData)
+        assert str(result) == "hello"
+
+    async def test_wildcard_param_can_create_resource(self):
+        """Test that wildcard parameters are valid."""
+
+        def identity(path: str) -> str:
+            return path
+
+        template = ResourceTemplate.from_function(
+            fn=identity,
+            uri_template="test://{path*}.py",
+            name="test",
+        )
+
+        assert await template.create_resource(
+            "test://path/to/test.py",
+            {"path": "path/to/test.py"},
+        )
+
+    async def test_wildcard_param_matches(self):
+        def identify(path: str) -> str:
+            return path
+
+        template = ResourceTemplate.from_function(
+            fn=identify,
+            uri_template="test://src/{path*}.py",
+            name="test",
+        )
+        # Valid match
+        params = template.matches("test://src/path/to/test.py")
+        assert params == {"path": "path/to/test"}
+
+    async def test_multiple_wildcard_params(self):
+        """Test that multiple wildcard parameters are valid."""
+
+        def identity(path: str, path2: str) -> str:
+            return f"{path}/{path2}"
+
+        template = ResourceTemplate.from_function(
+            fn=identity,
+            uri_template="test://{path*}/xyz/{path2*}",
+            name="test",
+        )
+
+        params = template.matches("test://path/to/xyz/abc")
+        assert params == {"path": "path/to", "path2": "abc"}
+
+    async def test_wildcard_param_with_regular_param(self):
+        """Test that a wildcard parameter can be used with a regular parameter."""
+
+        def identity(prefix: str, path: str) -> str:
+            return f"{prefix}/{path}"
+
+        template = ResourceTemplate.from_function(
+            fn=identity,
+            uri_template="test://{prefix}/{path*}",
+            name="test",
+        )
+
+        params = template.matches("test://src/path/to/test.py")
+        assert params == {"prefix": "src", "path": "path/to/test.py"}
+
+    async def test_function_with_varargs_not_allowed(self):
+        def func(x: int, *args: int) -> int:
+            return x + sum(args)
+
+        with pytest.raises(
+            ValueError,
+            match=r"Functions with \*args are not supported as resource templates",
+        ):
+            ResourceTemplate.from_function(
+                fn=func,
+                uri_template="test://{x}/{args*}",
+                name="test",
+            )
+
+    async def test_function_with_varkwargs_ok(self):
+        def func(x: int, **kwargs: int) -> int:
+            return x + sum(kwargs.values())
+
+        template = ResourceTemplate.from_function(
+            fn=func,
+            uri_template="test://{x}/{y}/{z}",
+            name="test",
+        )
+        assert template.uri_template == "test://{x}/{y}/{z}"
+
+    async def test_callable_object_as_template(self):
+        """Test that a callable object can be used as a template."""
+
+        class MyTemplate:
+            """This is my template"""
+
+            def __call__(self, x: str) -> str:
+                """ignore this"""
+                return f"X was {x}"
+
+        template = ResourceTemplate.from_function(
+            fn=MyTemplate(),
+            uri_template="test://{x}",
+            name="test",
+        )
+
+        resource = await template.create_resource(
+            "test://foo",
+            {"x": "foo"},
+        )
+
+        assert isinstance(resource, FunctionResource)
+        # read() returns raw string from __call__
+        result = await resource.read()
+        assert result == "X was foo"
+
+
+class TestMatchUriTemplate:
+    """Test match_uri_template function."""
+
+    @pytest.mark.parametrize(
+        "uri, expected_params",
+        [
+            ("test://a/b", None),
+            ("test://a/b/c", None),
+            ("test://a/x/b", {"x": "x"}),
+            ("test://a/x/y/b", None),
+            ("test://a/1-2/b", {"x": "1-2"}),
+        ],
+    )
+    def test_match_uri_template_single_param(
+        self, uri: str, expected_params: dict[str, str]
+    ):
+        """Test that match_uri_template uses the slash delimiter."""
+        uri_template = "test://a/{x}/b"
+        result = match_uri_template(uri=uri, uri_template=uri_template)
+        assert result == expected_params
+
+    @pytest.mark.parametrize(
+        "uri, expected_params",
+        [
+            ("test://foo/123", {"x": "foo", "y": "123"}),
+            ("test://bar/456", {"x": "bar", "y": "456"}),
+            ("test://foo/bar", {"x": "foo", "y": "bar"}),
+            ("test://foo/bar/baz", None),
+            ("test://foo/email@domain.com", {"x": "foo", "y": "email@domain.com"}),
+            ("test://two words/foo", {"x": "two words", "y": "foo"}),
+            ("test://two.words/foo+bar", {"x": "two.words", "y": "foo+bar"}),
+            (
+                f"test://escaped{quote('/', safe='')}word/bar",
+                {"x": "escaped/word", "y": "bar"},
+            ),
+            (
+                f"test://escaped{quote('{', safe='')}x{quote('}', safe='')}word/bar",
+                {"x": "escaped{x}word", "y": "bar"},
+            ),
+            ("prefix+test://foo/123", None),
+            ("test://foo", None),
+            ("other://foo/123", None),
+            ("t.est://foo/bar", None),
+        ],
+    )
+    def test_match_uri_template_simple_params(
+        self, uri: str, expected_params: dict[str, str] | None
+    ):
+        """Test matching URIs against a template with simple parameters."""
+        uri_template = "test://{x}/{y}"
+        result = match_uri_template(uri=uri, uri_template=uri_template)
+        assert result == expected_params
+
+    @pytest.mark.parametrize(
+        "uri, expected_params",
+        [
+            ("test://a/b/foo/c/d/123", {"x": "foo", "y": "123"}),
+            ("test://a/b/bar/c/d/456", {"x": "bar", "y": "456"}),
+            ("prefix+test://a/b/foo/c/d/123", None),
+            ("test://a/b/foo", None),
+            ("other://a/b/foo/c/d/123", None),
+        ],
+    )
+    def test_match_uri_template_params_and_literal_segments(
+        self, uri: str, expected_params: dict[str, str] | None
+    ):
+        """Test matching URIs against a template with parameters and literal segments."""
+        uri_template = "test://a/b/{x}/c/d/{y}"
+        result = match_uri_template(uri=uri, uri_template=uri_template)
+        assert result == expected_params
+
+    @pytest.mark.parametrize(
+        "uri, expected_params",
+        [
+            ("prefix+test://foo/test/123", {"x": "foo", "y": "123"}),
+            ("prefix+test://bar/test/456", {"x": "bar", "y": "456"}),
+            ("test://foo/test/123", None),
+            ("other.prefix+test://foo/test/123", None),
+            ("other+prefix+test://foo/test/123", None),
+        ],
+    )
+    def test_match_uri_template_with_prefix(
+        self, uri: str, expected_params: dict[str, str] | None
+    ):
+        """Test matching URIs against a template with a prefix."""
+        uri_template = "prefix+test://{x}/test/{y}"
+        result = match_uri_template(uri=uri, uri_template=uri_template)
+        assert result == expected_params
+
+    def test_match_uri_template_quoted_params(self):
+        uri_template = "user://{name}/{email}"
+        quoted_name = quote("John Doe", safe="")
+        quoted_email = quote("john@example.com", safe="")
+        uri = f"user://{quoted_name}/{quoted_email}"
+        result = match_uri_template(uri=uri, uri_template=uri_template)
+        assert result == {"name": "John Doe", "email": "john@example.com"}
+
+    @pytest.mark.parametrize(
+        "uri, expected_params",
+        [
+            ("test://a/b", None),
+            ("test://a/b/c", None),
+            ("test://a/x/b", {"x": "x"}),
+            ("test://a/x/y/b", {"x": "x/y"}),
+            ("bad-prefix://a/x/y/b", None),
+            ("test://a/x/y/z", None),
+        ],
+    )
+    def test_match_uri_template_wildcard_param(
+        self, uri: str, expected_params: dict[str, str]
+    ):
+        """Test that match_uri_template uses the slash delimiter."""
+        uri_template = "test://a/{x*}/b"
+        result = match_uri_template(uri=uri, uri_template=uri_template)
+        assert result == expected_params
+
+    @pytest.mark.parametrize(
+        "uri, expected_params",
+        [
+            ("test://a/x/y/b/c/d", {"x": "x/y", "y": "c/d"}),
+            ("bad-prefix://a/x/y/b/c/d", None),
+            ("test://a/x/y/c/d", None),
+            ("test://a/x/b/y", {"x": "x", "y": "y"}),
+        ],
+    )
+    def test_match_uri_template_multiple_wildcard_params(
+        self, uri: str, expected_params: dict[str, str]
+    ):
+        """Test that match_uri_template uses the slash delimiter."""
+        uri_template = "test://a/{x*}/b/{y*}"
+        result = match_uri_template(uri=uri, uri_template=uri_template)
+        assert result == expected_params
+
+    def test_match_uri_template_wildcard_and_literal_param(self):
+        """Test that match_uri_template uses the slash delimiter."""
+        uri = "test://a/x/y/b"
+        uri_template = "test://a/{x*}/{y}"
+        result = match_uri_template(uri=uri, uri_template=uri_template)
+        assert result == {"x": "x/y", "y": "b"}
+
+    def test_match_consecutive_params(self):
+        """Test that consecutive parameters without a / are not matched."""
+        uri = "test://a/x/y"
+        uri_template = "test://a/{x}{y}"
+        result = match_uri_template(uri=uri, uri_template=uri_template)
+        assert result is None
+
+    @pytest.mark.parametrize(
+        "uri, expected_params",
+        [
+            ("file://abc/xyz.py", {"path": "xyz"}),
+            ("file://abc/x/y/z.py", {"path": "x/y/z"}),
+            ("file://abc/x/y/z/.py", {"path": "x/y/z/"}),
+            ("file://abc/x/y/z.md", None),
+            ("file://x/y/z.txt", None),
+        ],
+    )
+    def test_match_uri_template_with_non_slash_suffix(
+        self, uri: str, expected_params: dict[str, str]
+    ):
+        uri_template = "file://abc/{path*}.py"
+        result = match_uri_template(uri=uri, uri_template=uri_template)
+        assert result == expected_params
+
+    @pytest.mark.parametrize(
+        "uri, expected_params",
+        [
+            ("resource://test_foo", {"x": "foo"}),
+            ("resource://test_bar", {"x": "bar"}),
+            ("resource://test_hello", {"x": "hello"}),
+            ("resource://test_with_underscores", {"x": "with_underscores"}),
+            ("resource://test_", None),  # Empty parameter not matched
+            ("resource://test", None),  # Missing parameter delimiter
+            ("resource://other_foo", None),  # Wrong prefix
+            ("other://test_foo", None),  # Wrong scheme
+        ],
+    )
+    def test_match_uri_template_embedded_param(
+        self, uri: str, expected_params: dict[str, str] | None
+    ):
+        """Test matching URIs where parameter is embedded within a word segment."""
+        uri_template = "resource://test_{x}"
+        result = match_uri_template(uri=uri, uri_template=uri_template)
+        assert result == expected_params
+
+    @pytest.mark.parametrize(
+        "uri, expected_params",
+        [
+            ("resource://prefix_foo_suffix", {"x": "foo"}),
+            ("resource://prefix_bar_suffix", {"x": "bar"}),
+            ("resource://prefix_hello_world_suffix", {"x": "hello_world"}),
+            ("resource://prefix__suffix", None),  # Empty parameter not matched
+            ("resource://prefix_suffix", None),  # Missing parameter delimiter
+            ("resource://other_foo_suffix", None),  # Wrong prefix
+            ("resource://prefix_foo_other", None),  # Wrong suffix
+        ],
+    )
+    def test_match_uri_template_embedded_param_with_prefix_and_suffix(
+        self, uri: str, expected_params: dict[str, str] | None
+    ):
+        """Test matching URIs where parameter has both prefix and suffix."""
+        uri_template = "resource://prefix_{x}_suffix"
+        result = match_uri_template(uri=uri, uri_template=uri_template)
+        assert result == expected_params
+
+
+class TestContextHandling:
+    """Test context handling in resource templates."""
+
+    def test_context_parameter_detection(self):
+        """Test that context parameters are properly detected in
+        ResourceTemplate.from_function()."""
+
+        def template_with_context(x: int, ctx: Context) -> str:
+            return str(x)
+
+        ResourceTemplate.from_function(
+            fn=template_with_context,
+            uri_template="test://{x}",
+            name="test",
+        )
+
+        def template_without_context(x: int) -> str:
+            return str(x)
+
+        ResourceTemplate.from_function(
+            fn=template_without_context,
+            uri_template="test://{x}",
+            name="test",
+        )
+
+    def test_parameterized_context_parameter_detection(self):
+        """Test that parameterized context parameters are properly detected in
+        ResourceTemplate.from_function()."""
+
+        def template_with_context(x: int, ctx: Context) -> str:
+            return str(x)
+
+        ResourceTemplate.from_function(
+            fn=template_with_context,
+            uri_template="test://{x}",
+            name="test",
+        )
+
+    def test_parameterized_union_context_parameter_detection(self):
+        """Test that context parameters in a union are properly detected in
+        ResourceTemplate.from_function()."""
+
+        def template_with_context(x: int, ctx: Context | None) -> str:
+            return str(x)
+
+        ResourceTemplate.from_function(
+            fn=template_with_context,
+            uri_template="test://{x}",
+            name="test",
+        )
+
+    async def test_context_injection(self):
+        """Test that context is properly injected during resource creation."""
+
+        def resource_with_context(x: int, ctx: Context) -> str:
+            assert isinstance(ctx, Context)
+            return str(x)
+
+        template = ResourceTemplate.from_function(
+            fn=resource_with_context,
+            uri_template="test://{x}",
+            name="test",
+        )
+
+        from fastmcp import FastMCP
+
+        mcp = FastMCP()
+        context = Context(fastmcp=mcp)
+
+        async with context:
+            resource = await template.create_resource(
+                "test://42",
+                {"x": 42},
+            )
+
+            assert isinstance(resource, FunctionResource)
+            # read() returns the raw value
+            result = await resource.read()
+            assert result == "42"
+
+    async def test_context_optional(self):
+        """Test that context is optional when creating resources."""
+
+        def resource_with_context(x: int, ctx: Context | None = None) -> str:
+            return str(x)
+
+        template = ResourceTemplate.from_function(
+            fn=resource_with_context,
+            uri_template="test://{x}",
+            name="test",
+        )
+
+        # Even for optional context, we need to provide a context
+        mcp = FastMCP()
+        context = Context(fastmcp=mcp)
+
+        async with context:
+            resource = await template.create_resource(
+                "test://42",
+                {"x": 42},
+            )
+
+            assert isinstance(resource, FunctionResource)
+            # read() returns the raw value
+            result = await resource.read()
+            assert result == "42"
+
+    async def test_context_with_functools_wraps_decorator(self):
+        """Regression test for #2524: decorated templates with Context should work."""
+
+        def custom_decorator(func):
+            @functools.wraps(func)
+            async def wrapper(*args, **kwargs):
+                return await func(*args, **kwargs)
+
+            return wrapper
+
+        @custom_decorator
+        async def decorated_template(ctx: Context, item_id: int) -> str:
+            assert isinstance(ctx, Context)
+            return f"item: {item_id}"
+
+        template = ResourceTemplate.from_function(
+            fn=decorated_template,
+            uri_template="test://{item_id}",
+            name="test",
+        )
+
+        mcp = FastMCP()
+        context = Context(fastmcp=mcp)
+
+        async with context:
+            resource = await template.create_resource("test://42", {"item_id": 42})
+            # read() returns the raw value
+            result = await resource.read()
+            assert result == "item: 42"
+
+
+class TestMalformedURITemplates:
+    """Test that malformed URI templates from remote servers don't crash."""
+
+    @pytest.mark.parametrize(
+        "template",
+        [
+            "test://{1leading}/path",
+            "test://{123}/path",
+        ],
+        ids=[
+            "leading_digit",
+            "all_digits",
+        ],
+    )
+    def test_build_regex_returns_none_for_invalid_group_names(self, template: str):
+        assert build_regex(template) is None
+
+    def test_build_regex_normalizes_hyphens(self):
+        """Hyphens in param names produce valid regex with underscored groups."""
+        regex = build_regex("test://{user-id}/path")
+        assert regex is not None
+        match = regex.match("test://alice/path")
+        assert match is not None
+        assert match.group("user_id") == "alice"
+
+    def test_build_regex_returns_none_for_duplicate_group_names(self):
+        assert build_regex("test://{a}/{a}/path") is None
+
+    @pytest.mark.parametrize(
+        "template",
+        [
+            "test://{a}/{a}/path",
+            "test://{1leading}/path",
+        ],
+        ids=[
+            "duplicate_groups",
+            "leading_digit",
+        ],
+    )
+    def test_match_uri_template_returns_none_for_malformed_templates(
+        self, template: str
+    ):
+        assert match_uri_template("test://anything/path", template) is None
+
+    def test_match_uri_template_normalizes_hyphens(self):
+        """Hyphenated params match and return underscored keys."""
+        result = match_uri_template("test://alice/path", "test://{user-id}/path")
+        assert result == {"user_id": "alice"}
+
+    def test_resource_template_matches_with_hyphenated_params(self):
+        template = ResourceTemplate(
+            uri_template="test://{user-id}/path",
+            name="test",
+            parameters={},
+        )
+        result = template.matches("test://alice/path")
+        assert result == {"user_id": "alice"}
+
+    async def test_hyphenated_template_end_to_end(self):
+        """Register and read a resource with hyphenated URI param names."""
+        from fastmcp import FastMCP
+
+        mcp = FastMCP("test")
+
+        @mcp.resource("data://{user-id}/profile")
+        def get_profile(user_id: str) -> str:
+            return f"profile for {user_id}"
+
+        templates = await mcp.list_resource_templates()
+        assert len(templates) == 1
+        assert templates[0].uri_template == "data://{user-id}/profile"
+
+        result = await mcp.read_resource("data://alice/profile")
+        assert "profile for alice" in str(result)
+
+    def test_build_regex_normalizes_wildcard_hyphens(self):
+        """Wildcard params with hyphens also get underscored groups."""
+        regex = build_regex("files://{file-path*}")
+        assert regex is not None
+        match = regex.match("files://a/b/c")
+        assert match is not None
+        assert match.group("file_path") == "a/b/c"
+
+    def test_expand_uri_template_with_hyphens(self):
+        """expand_uri_template maps underscored params to hyphenated placeholders."""
+        result = expand_uri_template("data://{user-id}/profile", {"user_id": "alice"})
+        assert result == "data://alice/profile"
+
+    def test_query_param_does_not_clobber_path_param(self):
+        """If path and query have the same normalized name, path wins."""
+        result = match_uri_template(
+            "test://alice?user-id=bob", "test://{user-id}{?user-id}"
+        )
+        # path param should be 'alice', not clobbered by query 'bob'
+        assert result is not None
+        assert result["user_id"] == "alice"
+
+    def test_query_param_with_blank_value_is_preserved(self):
+        """Regression for #4056: blank query values (e.g. ?format=) should
+        not be silently dropped. parse_qs without keep_blank_values=True
+        elides empty values, which loses caller intent."""
+        result = match_uri_template(
+            "resource://data/42?format=", "resource://data/{id}{?format}"
+        )
+        assert result is not None
+        assert result == {"id": "42", "format": ""}
+
+    def test_query_param_with_blank_and_present_values(self):
+        """Mix of blank and non-blank query values are both surfaced."""
+        result = match_uri_template(
+            "resource://data/42?format=&verbose=true",
+            "resource://data/{id}{?format,verbose}",
+        )
+        assert result is not None
+        assert result == {"id": "42", "format": "", "verbose": "true"}
+
+    def test_from_function_rejects_hyphen_underscore_collision(self):
+        """Two raw param names that normalize to the same key are rejected."""
+
+        def handler(user_id: str) -> str:
+            return user_id
+
+        with pytest.raises(ValueError, match="both normalize to 'user_id'"):
+            ResourceTemplate.from_function(
+                fn=handler,
+                uri_template="test://{user-id}/{user_id}",
+                name="collision",
+            )
+
+    def test_build_regex_still_works_for_valid_templates(self):
+        regex = build_regex("test://{name}/{id}")
+        assert regex is not None
+        match = regex.match("test://foo/123")
+        assert match is not None
+        assert match.group("name") == "foo"
+        assert match.group("id") == "123"
+
+
+class TestExpandUriTemplate:
+    """Test expand_uri_template — the inverse of match_uri_template."""
+
+    @pytest.mark.parametrize(
+        "template, params, expected",
+        [
+            ("test://{x}", {"x": "foo"}, "test://foo"),
+            ("test://{x}/{y}", {"x": "foo", "y": "bar"}, "test://foo/bar"),
+            ("test://a/{x}/b", {"x": "mid"}, "test://a/mid/b"),
+        ],
+    )
+    def test_expand_simple_params(
+        self, template: str, params: dict[str, str], expected: str
+    ):
+        assert expand_uri_template(template, params) == expected
+
+    @pytest.mark.parametrize(
+        "template, params, expected",
+        [
+            ("test://{path*}", {"path": "a/b/c"}, "test://a/b/c"),
+            ("test://{path*}", {"path": "single"}, "test://single"),
+            ("test://pre/{rest*}", {"rest": "x/y"}, "test://pre/x/y"),
+            (
+                "test://{a*}/mid/{b*}",
+                {"a": "x/y", "b": "p/q"},
+                "test://x/y/mid/p/q",
+            ),
+            ("test://{x}/{path*}", {"x": "foo", "path": "a/b"}, "test://foo/a/b"),
+        ],
+    )
+    def test_expand_wildcard_params(
+        self, template: str, params: dict[str, str], expected: str
+    ):
+        assert expand_uri_template(template, params) == expected
+
+    def test_expand_query_params(self):
+        result = expand_uri_template(
+            "test://data{?format,verbose}",
+            {"format": "json", "verbose": "true"},
+        )
+        assert result in (
+            "test://data?format=json&verbose=true",
+            "test://data?verbose=true&format=json",
+        )
+
+    def test_expand_query_params_partial(self):
+        result = expand_uri_template(
+            "test://data{?format,verbose}",
+            {"format": "json"},
+        )
+        assert result == "test://data?format=json"
+
+    def test_expand_query_params_none(self):
+        result = expand_uri_template("test://data{?format,verbose}", {})
+        assert result == "test://data"
+
+    def test_expand_ignores_extra_params(self):
+        result = expand_uri_template("test://{x}", {"x": "foo", "unused": "bar"})
+        assert result == "test://foo"
+
+    @pytest.mark.parametrize(
+        "template, params, expected",
+        [
+            # Simple {var} matches a single segment, so "/" must be encoded.
+            (
+                "data://{path}/info",
+                {"path": "hello/world"},
+                "data://hello%2Fworld/info",
+            ),
+            ("test://{x}", {"x": "a b"}, "test://a%20b"),
+            ("test://{x}", {"x": "a?b"}, "test://a%3Fb"),
+            ("test://{x}", {"x": "a#b"}, "test://a%23b"),
+            # Wildcard {var*} may span segments, so "/" is preserved but other
+            # reserved characters are still encoded.
+            ("test://{path*}", {"path": "a/b/c"}, "test://a/b/c"),
+            ("test://{path*}", {"path": "a b/c"}, "test://a%20b/c"),
+        ],
+    )
+    def test_expand_encodes_reserved_characters(
+        self, template: str, params: dict[str, str], expected: str
+    ):
+        """Path values are percent-encoded so the result round-trips through match."""
+        assert expand_uri_template(template, params) == expected
+
+
+class TestMatchExpandRoundTrip:
+    """match_uri_template and expand_uri_template must agree on the template grammar."""
+
+    @pytest.mark.parametrize(
+        "template, uri",
+        [
+            ("test://{x}", "test://foo"),
+            ("test://{x}/{y}", "test://foo/bar"),
+            ("test://a/{x}/b", "test://a/mid/b"),
+            ("test://{path*}", "test://a/b/c"),
+            ("test://{path*}", "test://single"),
+            ("test://pre/{rest*}", "test://pre/x/y/z"),
+            ("test://{x}/{path*}", "test://foo/a/b/c"),
+        ],
+    )
+    def test_expand_then_match_is_identity(self, template: str, uri: str):
+        """Extracting params from a URI and expanding them back reproduces the URI."""
+        params = match_uri_template(uri, template)
+        assert params is not None
+        assert expand_uri_template(template, params) == uri
+
+    @pytest.mark.parametrize(
+        "template, params",
+        [
+            ("data://{path}/info", {"path": "hello/world"}),
+            ("test://{x}", {"x": "a b c"}),
+            ("test://{x}", {"x": "100%"}),
+            ("test://{x}/{y}", {"x": "a/b", "y": "c?d"}),
+            ("test://{path*}", {"path": "a/b/c"}),
+            ("test://pre/{rest*}", {"rest": "x y/z"}),
+        ],
+    )
+    def test_match_then_expand_recovers_params(
+        self, template: str, params: dict[str, str]
+    ):
+        """Expanding params and matching them back reproduces the original values."""
+        uri = expand_uri_template(template, params)
+        assert match_uri_template(uri, template) == params
diff --git a/tests/resources/test_resource_template_meta.py b/tests/resources/test_resource_template_meta.py
new file mode 100644
index 0000000..3b65f9c
--- /dev/null
+++ b/tests/resources/test_resource_template_meta.py
@@ -0,0 +1,115 @@
+from mcp_types import Annotations, Icon
+
+from fastmcp import FastMCP
+from fastmcp.resources import ResourceTemplate
+from fastmcp.server.providers.fastmcp_provider import (
+    FastMCPProvider,
+    FastMCPProviderResourceTemplate,
+)
+
+
+class TestResourceTemplateMeta:
+    """Test ResourceTemplate meta functionality."""
+
+    def test_template_meta_parameter(self):
+        """Test that meta parameter is properly handled."""
+
+        def template_func(param: str) -> str:
+            return f"Result: {param}"
+
+        meta_data = {"version": "2.0", "template": "test"}
+        template = ResourceTemplate.from_function(
+            fn=template_func,
+            uri_template="test://{param}",
+            name="test_template",
+            meta=meta_data,
+        )
+
+        assert template.meta == meta_data
+        mcp_template = template.to_mcp_template()
+        # MCP template includes fastmcp meta, so check that our meta is included
+        assert mcp_template.meta is not None
+        assert meta_data.items() <= mcp_template.meta.items()
+
+
+class TestResourceTemplateFieldPreservation:
+    """Regression for #4061: annotations/meta/title/icons must survive
+    materialization of a Resource from a ResourceTemplate."""
+
+    def _template(self) -> ResourceTemplate:
+        def fn(param: str) -> str:
+            return f"value-{param}"
+
+        return ResourceTemplate.from_function(
+            fn=fn,
+            uri_template="data://{param}",
+            name="t",
+            title="Human Title",
+            meta={"owner": "team-a"},
+            icons=[Icon(src="https://example.com/icon.png", mime_type="image/png")],
+            annotations=Annotations(priority=0.5, audience=["user"]),
+        )
+
+    async def test_function_template_create_resource_preserves_all_fields(self):
+        template = self._template()
+        resource = await template.create_resource("data://x", {"param": "x"})
+
+        assert resource.title == "Human Title"
+        assert resource.meta == {"owner": "team-a"}
+        assert resource.annotations is not None
+        assert resource.annotations.priority == 0.5
+        assert resource.annotations.audience == ["user"]
+        assert resource.icons is not None
+        assert len(resource.icons) == 1
+        assert str(resource.icons[0].src) == "https://example.com/icon.png"
+
+    async def test_created_resource_meta_is_not_aliased_to_template(self):
+        """Mutating the materialized resource's meta must not bleed back into
+        the template (each materialization must be independent)."""
+        template = self._template()
+        resource = await template.create_resource("data://x", {"param": "x"})
+
+        assert resource.meta is not None
+        resource.meta["mutated"] = True
+        assert "mutated" not in (template.meta or {})
+
+    async def test_fastmcp_provider_template_preserves_fields_without_double_wrap(
+        self,
+    ):
+        """The FastMCPProvider path wraps template.get_meta() (already
+        namespaced). Re-materializing must not nest fastmcp under fastmcp."""
+        sub = FastMCP("sub")
+
+        @sub.resource(
+            "data://{param}",
+            title="Sub Title",
+            meta={"owner": "team-b"},
+            icons=[Icon(src="https://example.com/s.png", mime_type="image/png")],
+            annotations=Annotations(priority=0.9),
+            tags={"alpha"},
+        )
+        def fn(param: str) -> str:
+            return f"sub-{param}"
+
+        provider = FastMCPProvider(sub)
+        templates = await provider._list_resource_templates()
+        assert len(templates) == 1
+        wrapped = templates[0]
+        assert isinstance(wrapped, FastMCPProviderResourceTemplate)
+
+        resource = await wrapped.create_resource("data://x", {"param": "x"})
+
+        assert resource.title == "Sub Title"
+        assert resource.annotations is not None
+        assert resource.annotations.priority == 0.9
+        assert resource.icons is not None and len(resource.icons) == 1
+
+        mcp_resource = resource.to_mcp_resource()
+        assert mcp_resource.meta is not None
+        # User meta survives end-to-end.
+        assert mcp_resource.meta.get("owner") == "team-b"
+        # Exactly one fastmcp namespace, and it is NOT double-wrapped.
+        fastmcp_ns = mcp_resource.meta.get("fastmcp")
+        assert isinstance(fastmcp_ns, dict)
+        assert "fastmcp" not in fastmcp_ns
+        assert "alpha" in fastmcp_ns.get("tags", [])
diff --git a/tests/resources/test_resource_template_query_params.py b/tests/resources/test_resource_template_query_params.py
new file mode 100644
index 0000000..9d7f86b
--- /dev/null
+++ b/tests/resources/test_resource_template_query_params.py
@@ -0,0 +1,410 @@
+import pytest
+
+from fastmcp.resources import ResourceTemplate
+
+
+class TestQueryParameterExtraction:
+    """Test basic query parameter extraction from URIs."""
+
+    async def test_single_query_param(self):
+        """Test resource template with single query parameter."""
+
+        def get_data(id: str, format: str = "json") -> str:
+            return f"Data {id} in {format}"
+
+        template = ResourceTemplate.from_function(
+            fn=get_data,
+            uri_template="data://{id}{?format}",
+            name="test",
+        )
+
+        # Match without query param (uses default)
+        params = template.matches("data://123")
+        assert params == {"id": "123"}
+
+        # Match with query param
+        params = template.matches("data://123?format=xml")
+        assert params == {"id": "123", "format": "xml"}
+
+    async def test_multiple_query_params(self):
+        """Test resource template with multiple query parameters."""
+
+        def get_items(category: str, page: int = 1, limit: int = 10) -> str:
+            return f"Category {category}, page {page}, limit {limit}"
+
+        template = ResourceTemplate.from_function(
+            fn=get_items,
+            uri_template="items://{category}{?page,limit}",
+            name="test",
+        )
+
+        # No query params
+        params = template.matches("items://books")
+        assert params == {"category": "books"}
+
+        # One query param
+        params = template.matches("items://books?page=2")
+        assert params == {"category": "books", "page": "2"}
+
+        # Both query params
+        params = template.matches("items://books?page=2&limit=20")
+        assert params == {"category": "books", "page": "2", "limit": "20"}
+
+
+class TestQueryParameterTypeCoercion:
+    """Test type coercion for query parameters."""
+
+    async def test_int_coercion(self):
+        """Test integer type coercion for query parameters."""
+
+        def get_page(resource: str, page: int = 1) -> dict:
+            return {"resource": resource, "page": page, "type": type(page).__name__}
+
+        template = ResourceTemplate.from_function(
+            fn=get_page,
+            uri_template="resource://{resource}{?page}",
+            name="test",
+        )
+
+        # Create resource with string query param
+        resource = await template.create_resource(
+            "resource://docs?page=5",
+            {"resource": "docs", "page": "5"},
+        )
+
+        # read() returns raw dict
+        result = await resource.read()
+        assert isinstance(result, dict)
+        assert result["page"] == 5
+        assert result["type"] == "int"
+
+    async def test_bool_coercion(self):
+        """Test boolean type coercion for query parameters."""
+
+        def get_config(name: str, enabled: bool = False) -> dict:
+            return {"name": name, "enabled": enabled, "type": type(enabled).__name__}
+
+        template = ResourceTemplate.from_function(
+            fn=get_config,
+            uri_template="config://{name}{?enabled}",
+            name="test",
+        )
+
+        # Test true value
+        resource = await template.create_resource(
+            "config://feature?enabled=true",
+            {"name": "feature", "enabled": "true"},
+        )
+        # read() returns raw dict
+        result = await resource.read()
+        assert isinstance(result, dict)
+        assert result["enabled"] is True
+
+        # Test false value
+        resource = await template.create_resource(
+            "config://feature?enabled=false",
+            {"name": "feature", "enabled": "false"},
+        )
+        result = await resource.read()
+        assert isinstance(result, dict)
+        assert result["enabled"] is False
+
+    async def test_float_coercion(self):
+        """Test float type coercion for query parameters."""
+
+        def get_metrics(service: str, threshold: float = 0.5) -> dict:
+            return {
+                "service": service,
+                "threshold": threshold,
+                "type": type(threshold).__name__,
+            }
+
+        template = ResourceTemplate.from_function(
+            fn=get_metrics,
+            uri_template="metrics://{service}{?threshold}",
+            name="test",
+        )
+
+        resource = await template.create_resource(
+            "metrics://api?threshold=0.95",
+            {"service": "api", "threshold": "0.95"},
+        )
+
+        # read() returns raw dict
+        result = await resource.read()
+        assert isinstance(result, dict)
+        assert result["threshold"] == 0.95
+        assert result["type"] == "float"
+
+
+class TestQueryParameterValidation:
+    """Test validation rules for query parameters."""
+
+    def test_query_params_must_be_optional(self):
+        """Test that query parameters must have default values."""
+
+        def invalid_func(id: str, format: str) -> str:
+            return f"Data {id} in {format}"
+
+        with pytest.raises(
+            ValueError,
+            match="Query parameters .* must be optional function parameters with default values",
+        ):
+            ResourceTemplate.from_function(
+                fn=invalid_func,
+                uri_template="data://{id}{?format}",
+                name="test",
+            )
+
+    def test_required_params_in_path(self):
+        """Test that required parameters must be in path."""
+
+        def valid_func(id: str, format: str = "json") -> str:
+            return f"Data {id} in {format}"
+
+        # This should work - required param in path, optional in query
+        template = ResourceTemplate.from_function(
+            fn=valid_func,
+            uri_template="data://{id}{?format}",
+            name="test",
+        )
+        assert template.uri_template == "data://{id}{?format}"
+
+
+class TestQueryParameterWithDefaults:
+    """Test that missing query parameters use default values."""
+
+    async def test_missing_query_param_uses_default(self):
+        """Test that missing query parameters fall back to defaults."""
+
+        def get_data(id: str, format: str = "json", verbose: bool = False) -> dict:
+            return {"id": id, "format": format, "verbose": verbose}
+
+        template = ResourceTemplate.from_function(
+            fn=get_data,
+            uri_template="data://{id}{?format,verbose}",
+            name="test",
+        )
+
+        # No query params - should use defaults
+        resource = await template.create_resource(
+            "data://123",
+            {"id": "123"},
+        )
+
+        # read() returns raw dict
+        result = await resource.read()
+        assert isinstance(result, dict)
+        assert result["format"] == "json"
+        assert result["verbose"] is False
+
+    async def test_partial_query_params(self):
+        """Test providing only some query parameters."""
+
+        def get_data(
+            id: str, format: str = "json", limit: int = 10, offset: int = 0
+        ) -> dict:
+            return {"id": id, "format": format, "limit": limit, "offset": offset}
+
+        template = ResourceTemplate.from_function(
+            fn=get_data,
+            uri_template="data://{id}{?format,limit,offset}",
+            name="test",
+        )
+
+        # Provide only some query params
+        resource = await template.create_resource(
+            "data://123?limit=20",
+            {"id": "123", "limit": "20"},
+        )
+
+        # read() returns raw dict
+        result = await resource.read()
+        assert isinstance(result, dict)
+        assert result["format"] == "json"  # default
+        assert result["limit"] == 20  # provided
+        assert result["offset"] == 0  # default
+
+
+class TestQueryParameterWithWildcards:
+    """Test query parameters combined with wildcard path parameters."""
+
+    async def test_wildcard_with_query_params(self):
+        """Test combining wildcard path params with query params."""
+
+        def get_file(path: str, encoding: str = "utf-8", lines: int = 100) -> dict:
+            return {"path": path, "encoding": encoding, "lines": lines}
+
+        template = ResourceTemplate.from_function(
+            fn=get_file,
+            uri_template="files://{path*}{?encoding,lines}",
+            name="test",
+        )
+
+        # Match path with query params
+        params = template.matches("files://src/test/data.txt?encoding=ascii&lines=50")
+        assert params == {
+            "path": "src/test/data.txt",
+            "encoding": "ascii",
+            "lines": "50",
+        }
+
+        # Create resource
+        resource = await template.create_resource(
+            "files://src/test/data.txt?lines=50",
+            {"path": "src/test/data.txt", "lines": "50"},
+        )
+
+        # read() returns raw dict
+        result = await resource.read()
+        assert isinstance(result, dict)
+        assert result["path"] == "src/test/data.txt"
+        assert result["encoding"] == "utf-8"  # default
+        assert result["lines"] == 50  # provided
+
+
+class TestBooleanQueryParameterValidation:
+    """Test that invalid boolean query parameter values raise errors."""
+
+    async def _make_template(self):
+        def get_config(name: str, enabled: bool = False) -> dict:
+            return {"name": name, "enabled": enabled}
+
+        return ResourceTemplate.from_function(
+            fn=get_config,
+            uri_template="config://{name}{?enabled}",
+            name="test",
+        )
+
+    async def test_invalid_boolean_value_raises_error(self):
+        """Test that nonsense boolean values like 'banana' raise ValueError."""
+        template = await self._make_template()
+
+        with pytest.raises(ValueError, match="Invalid boolean value for enabled"):
+            resource = await template.create_resource(
+                "config://feature?enabled=banana",
+                {"name": "feature", "enabled": "banana"},
+            )
+            await resource.read()
+
+    @pytest.mark.parametrize(
+        "value", ["true", "True", "TRUE", "1", "yes", "Yes", "YES"]
+    )
+    async def test_valid_true_values(self, value: str):
+        """Test that all accepted truthy string values coerce to True."""
+        template = await self._make_template()
+
+        resource = await template.create_resource(
+            f"config://feature?enabled={value}",
+            {"name": "feature", "enabled": value},
+        )
+        result = await resource.read()
+        assert isinstance(result, dict)
+        assert result["enabled"] is True
+
+    @pytest.mark.parametrize(
+        "value", ["false", "False", "FALSE", "0", "no", "No", "NO"]
+    )
+    async def test_valid_false_values(self, value: str):
+        """Test that all accepted falsy string values coerce to False."""
+        template = await self._make_template()
+
+        resource = await template.create_resource(
+            f"config://feature?enabled={value}",
+            {"name": "feature", "enabled": value},
+        )
+        result = await resource.read()
+        assert isinstance(result, dict)
+        assert result["enabled"] is False
+
+    @pytest.mark.parametrize("value", ["banana", "nope", "2", "truee", ""])
+    async def test_various_invalid_boolean_values(self, value: str):
+        """Test that various invalid boolean strings raise ValueError."""
+        template = await self._make_template()
+
+        with pytest.raises(ValueError, match="Invalid boolean value for enabled"):
+            resource = await template.create_resource(
+                f"config://feature?enabled={value}",
+                {"name": "feature", "enabled": value},
+            )
+            await resource.read()
+
+
+class TestResourceTemplateFieldDefaults:
+    """Test resource templates with Field() defaults."""
+
+    async def test_field_with_default(self):
+        """Test that Field(default=...) correctly provides default values in resource templates."""
+        from pydantic import Field
+
+        def get_data(
+            id: str = Field(description="Resource ID"),
+            format: str = Field(default="json", description="Output format"),
+        ) -> str:
+            return f"id={id}, format={format}"
+
+        template = ResourceTemplate.from_function(
+            fn=get_data,
+            uri_template="data://{id}{?format}",
+            name="test",
+        )
+
+        # Test with only required parameter
+        resource = await template.create_resource("data://123", {"id": "123"})
+        result = await resource.read()
+        assert result == "id=123, format=json"
+
+        # Test with override
+        resource = await template.create_resource(
+            "data://123?format=xml", {"id": "123", "format": "xml"}
+        )
+        result = await resource.read()
+        assert result == "id=123, format=xml"
+
+    async def test_multiple_field_defaults(self):
+        """Test multiple query parameters with Field() defaults."""
+        from typing import Any
+
+        from pydantic import Field
+
+        def fetch_data(
+            resource_id: str = Field(description="Resource ID"),
+            limit: int = Field(default=10, description="Result limit"),
+            offset: int = Field(default=0, description="Result offset"),
+            format: str = Field(default="json", description="Output format"),
+        ) -> dict[str, Any]:
+            return {
+                "resource_id": resource_id,
+                "limit": limit,
+                "offset": offset,
+                "format": format,
+            }
+
+        template = ResourceTemplate.from_function(
+            fn=fetch_data,
+            uri_template="api://{resource_id}{?limit,offset,format}",
+            name="test",
+        )
+
+        # Test with only required parameter - all defaults should apply
+        resource1 = await template.create_resource(
+            "api://user123", {"resource_id": "user123"}
+        )
+        result1 = await resource1.read()
+        assert isinstance(result1, dict)
+        assert result1["resource_id"] == "user123"
+        assert result1["limit"] == 10
+        assert result1["offset"] == 0
+        assert result1["format"] == "json"
+
+        # Test with some overrides
+        resource2 = await template.create_resource(
+            "api://user123?limit=50&format=xml",
+            {"resource_id": "user123", "limit": "50", "format": "xml"},
+        )
+        result2 = await resource2.read()
+        assert isinstance(result2, dict)
+        assert result2["resource_id"] == "user123"
+        assert result2["limit"] == 50  # overridden
+        assert result2["offset"] == 0  # default
+        assert result2["format"] == "xml"  # overridden
diff --git a/tests/resources/test_resources.py b/tests/resources/test_resources.py
new file mode 100644
index 0000000..ad72b61
--- /dev/null
+++ b/tests/resources/test_resources.py
@@ -0,0 +1,372 @@
+import mcp_types
+import pytest
+from pydantic import AnyUrl, BaseModel
+
+from fastmcp import Client, FastMCP
+from fastmcp.resources import Resource, ResourceContent, ResourceResult
+from fastmcp.resources.function_resource import FunctionResource
+
+
+class TestResourceValidation:
+    """Test base Resource validation."""
+
+    def test_resource_uri_validation(self):
+        """Test URI validation."""
+
+        def dummy_func() -> str:
+            return "data"
+
+        # Valid URI
+        resource = FunctionResource(
+            uri=AnyUrl("http://example.com/data"),
+            name="test",
+            fn=dummy_func,
+        )
+        assert str(resource.uri) == "http://example.com/data"
+
+        # Missing protocol
+        with pytest.raises(ValueError, match="Input should be a valid URL"):
+            FunctionResource(
+                uri=AnyUrl("invalid"),
+                name="test",
+                fn=dummy_func,
+            )
+
+        # Missing host
+        with pytest.raises(ValueError, match="Input should be a valid URL"):
+            FunctionResource(
+                uri=AnyUrl("http://"),
+                name="test",
+                fn=dummy_func,
+            )
+
+    def test_resource_name_from_uri(self):
+        """Test name is extracted from URI if not provided."""
+
+        def dummy_func() -> str:
+            return "data"
+
+        resource = FunctionResource(
+            uri=AnyUrl("resource://my-resource"),
+            fn=dummy_func,
+        )
+        assert resource.name == "resource://my-resource"
+
+    def test_provided_name_takes_precedence_over_uri(self):
+        """Test that provided name takes precedence over URI."""
+
+        def dummy_func() -> str:
+            return "data"
+
+        # Explicit name takes precedence over URI
+        resource = FunctionResource(
+            uri=AnyUrl("resource://uri-name"),
+            name="explicit-name",
+            fn=dummy_func,
+        )
+        assert resource.name == "explicit-name"
+
+    def test_resource_mime_type(self):
+        """Test mime type handling."""
+
+        def dummy_func() -> str:
+            return "data"
+
+        # Default mime type
+        resource = FunctionResource(
+            uri=AnyUrl("resource://test"),
+            fn=dummy_func,
+        )
+        assert resource.mime_type == "text/plain"
+
+        # Custom mime type
+        resource = FunctionResource(
+            uri=AnyUrl("resource://test"),
+            fn=dummy_func,
+            mime_type="application/json",
+        )
+        assert resource.mime_type == "application/json"
+
+    async def test_resource_read_not_implemented(self):
+        """Test that Resource.read() raises NotImplementedError."""
+
+        class ConcreteResource(Resource):
+            pass
+
+        resource = ConcreteResource(uri=AnyUrl("test://test"), name="test")
+        with pytest.raises(NotImplementedError, match="Subclasses must implement read"):
+            await resource.read()
+
+    def test_resource_meta_parameter(self):
+        """Test that meta parameter is properly handled."""
+
+        def resource_func() -> str:
+            return "test content"
+
+        meta_data = {"version": "1.0", "category": "test"}
+        resource = Resource.from_function(
+            fn=resource_func,
+            uri="resource://test",
+            name="test_resource",
+            meta=meta_data,
+        )
+
+        assert resource.meta == meta_data
+        mcp_resource = resource.to_mcp_resource()
+        # MCP resource includes fastmcp meta, so check that our meta is included
+        assert mcp_resource.meta is not None
+        assert meta_data.items() <= mcp_resource.meta.items()
+
+
+class TestResourceContent:
+    """Test ResourceContent creation and conversion."""
+
+    def test_string_content(self):
+        """String input creates text content with text/plain mime type."""
+        content = ResourceContent("hello world")
+        assert content.content == "hello world"
+        assert content.mime_type == "text/plain"
+        assert content.meta is None
+
+    def test_bytes_content(self):
+        """Bytes input creates binary content with octet-stream mime type."""
+        content = ResourceContent(b"\x00\x01\x02")
+        assert content.content == b"\x00\x01\x02"
+        assert content.mime_type == "application/octet-stream"
+        assert content.meta is None
+
+    def test_dict_serialized_to_json(self):
+        """Dict input is JSON-serialized with application/json mime type."""
+        content = ResourceContent({"key": "value", "count": 42})
+        assert content.content == '{"key":"value","count":42}'
+        assert content.mime_type == "application/json"
+
+    def test_list_serialized_to_json(self):
+        """List input is JSON-serialized."""
+        content = ResourceContent([1, 2, 3])
+        assert content.content == "[1,2,3]"
+        assert content.mime_type == "application/json"
+
+    def test_pydantic_model_serialized_to_json(self):
+        """Pydantic model is JSON-serialized."""
+
+        class Item(BaseModel):
+            name: str
+            price: float
+
+        content = ResourceContent(Item(name="Widget", price=9.99))
+        assert content.content == '{"name":"Widget","price":9.99}'
+        assert content.mime_type == "application/json"
+
+    def test_custom_mime_type(self):
+        """Custom mime type overrides default."""
+        content = ResourceContent("test", mime_type="text/html")
+        assert content.mime_type == "text/html"
+
+    def test_with_meta(self):
+        """Meta is passed through to content."""
+        content = ResourceContent("test", meta={"version": "1.0"})
+        assert content.meta == {"version": "1.0"}
+
+    def test_to_mcp_text_contents(self):
+        """Text content converts to TextResourceContents."""
+        content = ResourceContent(
+            content="hello", mime_type="text/plain", meta={"k": "v"}
+        )
+        mcp_content = content.to_mcp_resource_contents("resource://test")
+        assert isinstance(mcp_content, mcp_types.TextResourceContents)
+        assert mcp_content.text == "hello"
+        assert mcp_content.mime_type == "text/plain"
+        assert str(mcp_content.uri) == "resource://test"
+        assert mcp_content.meta == {"k": "v"}
+
+    def test_to_mcp_blob_contents(self):
+        """Binary content converts to BlobResourceContents with base64."""
+        content = ResourceContent(
+            content=b"\x00\x01\x02", mime_type="application/octet-stream"
+        )
+        mcp_content = content.to_mcp_resource_contents("resource://binary")
+        assert isinstance(mcp_content, mcp_types.BlobResourceContents)
+        assert mcp_content.blob == "AAEC"  # base64 of \x00\x01\x02
+        assert mcp_content.mime_type == "application/octet-stream"
+
+
+class TestResourceResult:
+    """Test ResourceResult initialization and conversion."""
+
+    def test_init_from_string(self):
+        """String input is normalized to list[ResourceContent]."""
+        result = ResourceResult("hello world")
+        assert len(result.contents) == 1
+        assert result.contents[0].content == "hello world"
+        assert result.contents[0].mime_type == "text/plain"
+
+    def test_init_from_bytes(self):
+        """Bytes input is normalized to list[ResourceContent]."""
+        result = ResourceResult(b"\xff\xfe")
+        assert len(result.contents) == 1
+        assert result.contents[0].content == b"\xff\xfe"
+        assert result.contents[0].mime_type == "application/octet-stream"
+
+    def test_init_from_dict_auto_serializes(self):
+        """Dict input is auto-serialized to JSON text."""
+        result = ResourceResult({"page": 1, "total": 100})  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+        assert len(result.contents) == 1
+        text = str(result.contents[0].content)
+        assert '"page"' in text
+        assert '"total"' in text
+
+    def test_init_from_single_resource_content_raises_type_error(self):
+        """Single ResourceContent raises TypeError - must be in a list."""
+        content = ResourceContent(content="test", mime_type="text/html")
+        with pytest.raises(TypeError, match="must be str, bytes, or list"):
+            ResourceResult(content)  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+
+    def test_init_from_list_of_resource_content(self):
+        """List of ResourceContent is used directly."""
+        contents = [
+            ResourceContent(content="one", mime_type="text/plain"),
+            ResourceContent(content="two", mime_type="text/plain"),
+        ]
+        result = ResourceResult(contents)
+        assert len(result.contents) == 2
+        assert result.contents[0].content == "one"
+        assert result.contents[1].content == "two"
+
+    def test_init_from_mixed_list_raises_type_error(self):
+        """Mixed list items raise TypeError - all items must be ResourceContent."""
+        with pytest.raises(TypeError, match=r"contents\[0\] must be ResourceContent"):
+            ResourceResult(["text", b"bytes", {"key": "value"}])  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+
+    def test_init_preserves_meta(self):
+        """Meta is preserved on ResourceResult."""
+        result = ResourceResult("test", meta={"version": "2.0"})
+        assert result.meta == {"version": "2.0"}
+
+    def test_to_mcp_result(self):
+        """Converts to MCP ReadResourceResult with proper structure."""
+        result = ResourceResult(
+            contents=[ResourceContent(content="hello", mime_type="text/plain")],
+            meta={"source": "test"},
+        )
+        mcp_result = result.to_mcp_result("resource://test")
+        assert isinstance(mcp_result, mcp_types.ReadResourceResult)
+        assert len(mcp_result.contents) == 1
+        assert isinstance(mcp_result.contents[0], mcp_types.TextResourceContents)
+        assert mcp_result.contents[0].text == "hello"
+        assert str(mcp_result.contents[0].uri) == "resource://test"
+        assert mcp_result.meta == {"source": "test"}
+
+    def test_to_mcp_result_multiple_contents(self):
+        """Multiple contents all get same URI."""
+        result = ResourceResult(
+            [
+                ResourceContent("one"),
+                ResourceContent("two"),
+                ResourceContent("three"),
+            ]
+        )
+        mcp_result = result.to_mcp_result("resource://multi")
+        assert len(mcp_result.contents) == 3
+        for item in mcp_result.contents:
+            assert str(item.uri) == "resource://multi"
+
+
+class TestResourceConvertResult:
+    """Test Resource.convert_result() method."""
+
+    def test_passthrough_resource_result(self):
+        """ResourceResult input is returned unchanged."""
+
+        def fn() -> str:
+            return "test"
+
+        resource = FunctionResource(uri=AnyUrl("test://test"), name="test", fn=fn)
+        original = ResourceResult("test", meta={"original": True})
+        result = resource.convert_result(original)
+        assert result is original
+
+    def test_converts_raw_value(self):
+        """Raw values are converted to ResourceResult."""
+
+        def fn() -> str:
+            return "test"
+
+        resource = FunctionResource(uri=AnyUrl("test://test"), name="test", fn=fn)
+        result = resource.convert_result("hello")
+        assert isinstance(result, ResourceResult)
+        assert len(result.contents) == 1
+        assert result.contents[0].content == "hello"
+
+    async def test_read_returns_resource_result(self):
+        """_read() returns ResourceResult after conversion."""
+
+        def fn() -> str:
+            return "hello world"
+
+        resource = FunctionResource(uri=AnyUrl("test://test"), name="test", fn=fn)
+        result = await resource._read()
+        assert len(result.contents) == 1
+        assert result.contents[0].content == "hello world"
+
+
+class TestResourceMetaPropagation:
+    """Test that meta is properly propagated through the full MCP flow."""
+
+    async def test_resource_result_meta_received_by_client(self):
+        """Meta set on ResourceResult is received by MCP client."""
+        mcp = FastMCP()
+
+        @mcp.resource("test://with-meta")
+        def resource_with_meta() -> ResourceResult:
+            return ResourceResult("hello", meta={"version": "2.0", "source": "test"})
+
+        async with Client(mcp) as client:
+            result = await client.read_resource_mcp("test://with-meta")
+            assert result.meta == {"version": "2.0", "source": "test"}
+
+    async def test_resource_content_meta_received_by_client(self):
+        """Meta set on ResourceContent is received by MCP client."""
+        mcp = FastMCP()
+
+        @mcp.resource("test://content-meta")
+        def resource_with_content_meta() -> ResourceResult:
+            return ResourceResult(
+                [ResourceContent(content="data", meta={"item_version": "1.0"})]
+            )
+
+        async with Client(mcp) as client:
+            result = await client.read_resource_mcp("test://content-meta")
+            assert len(result.contents) == 1
+            assert result.contents[0].meta == {"item_version": "1.0"}
+
+    async def test_both_result_and_content_meta(self):
+        """Both result-level and content-level meta are propagated."""
+        mcp = FastMCP()
+
+        @mcp.resource("test://both-meta")
+        def resource_both_meta() -> ResourceResult:
+            return ResourceResult(
+                contents=[
+                    ResourceContent(content="item", meta={"item_key": "item_val"})
+                ],
+                meta={"result_key": "result_val"},
+            )
+
+        async with Client(mcp) as client:
+            result = await client.read_resource_mcp("test://both-meta")
+            assert result.meta == {"result_key": "result_val"}
+            assert result.contents[0].meta == {"item_key": "item_val"}
+
+    async def test_json_native_return_preserves_component_meta(self):
+        """JSON-native returns should propagate component-level meta to content."""
+        mcp = FastMCP()
+
+        @mcp.resource("test://json-meta", meta={"csp": "default-src 'none'"})
+        def json_resource() -> dict[str, str]:
+            return {"hello": "world"}
+
+        async with Client(mcp) as client:
+            result = await client.read_resource_mcp("test://json-meta")
+            assert len(result.contents) == 1
+            assert result.contents[0].meta == {"csp": "default-src 'none'"}
diff --git a/tests/resources/test_standalone_decorator.py b/tests/resources/test_standalone_decorator.py
new file mode 100644
index 0000000..ba555f7
--- /dev/null
+++ b/tests/resources/test_standalone_decorator.py
@@ -0,0 +1,171 @@
+"""Tests for the standalone @resource decorator.
+
+The @resource decorator attaches metadata to functions without registering them
+to a server. Functions can be added explicitly via server.add_resource() /
+server.add_template() or discovered by FileSystemProvider.
+"""
+
+from typing import cast
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.resources import resource
+from fastmcp.resources.function_resource import DecoratedResource, ResourceMeta
+
+
+class TestResourceDecorator:
+    """Tests for the @resource decorator."""
+
+    def test_resource_requires_uri(self):
+        """@resource should require a URI argument."""
+        with pytest.raises(TypeError, match="requires a URI|was used incorrectly"):
+
+            @resource  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+            def get_config() -> str:
+                return "{}"
+
+    def test_resource_with_uri(self):
+        """@resource("uri") should attach metadata."""
+
+        @resource("config://app")
+        def get_config() -> dict:
+            return {"setting": "value"}
+
+        decorated = cast(DecoratedResource, get_config)
+        assert callable(get_config)
+        assert hasattr(get_config, "__fastmcp__")
+        assert isinstance(decorated.__fastmcp__, ResourceMeta)
+        assert decorated.__fastmcp__.uri == "config://app"
+
+    def test_resource_with_template_uri(self):
+        """@resource with template URI should attach metadata."""
+
+        @resource("users://{user_id}/profile")
+        def get_profile(user_id: str) -> dict:
+            return {"id": user_id}
+
+        decorated = cast(DecoratedResource, get_profile)
+        assert callable(get_profile)
+        assert hasattr(get_profile, "__fastmcp__")
+        assert decorated.__fastmcp__.uri == "users://{user_id}/profile"
+
+    def test_resource_with_function_params_becomes_template(self):
+        """@resource with function params should attach metadata."""
+
+        @resource("data://items/{category}")
+        def get_items(category: str, limit: int = 10) -> list:
+            return list(range(limit))
+
+        decorated = cast(DecoratedResource, get_items)
+        assert callable(get_items)
+        assert hasattr(get_items, "__fastmcp__")
+        assert decorated.__fastmcp__.uri == "data://items/{category}"
+
+    def test_resource_with_all_metadata(self):
+        """@resource with all metadata should store it all."""
+
+        @resource(
+            "config://app",
+            name="app-config",
+            title="Application Config",
+            description="Gets app configuration",
+            mime_type="application/json",
+            tags={"config"},
+            meta={"custom": "value"},
+        )
+        def get_config() -> dict:
+            return {"setting": "value"}
+
+        decorated = cast(DecoratedResource, get_config)
+        assert callable(get_config)
+        assert hasattr(get_config, "__fastmcp__")
+        assert decorated.__fastmcp__.uri == "config://app"
+        assert decorated.__fastmcp__.name == "app-config"
+        assert decorated.__fastmcp__.title == "Application Config"
+        assert decorated.__fastmcp__.description == "Gets app configuration"
+        assert decorated.__fastmcp__.mime_type == "application/json"
+        assert decorated.__fastmcp__.tags == {"config"}
+        assert decorated.__fastmcp__.meta == {"custom": "value"}
+
+    async def test_resource_function_still_callable(self):
+        """Decorated function should still be directly callable."""
+
+        @resource("config://app")
+        def get_config() -> dict:
+            """Get config."""
+            return {"setting": "value"}
+
+        # The function is still callable even though it has metadata
+        result = cast(DecoratedResource, get_config)()
+        assert result == {"setting": "value"}
+
+    async def test_staticmethod_metadata_is_available_on_unwrapped_function(self):
+        """@resource should attach metadata where staticmethod access can find it."""
+
+        class MyClass:
+            @resource("config://static")
+            @staticmethod
+            def get_config() -> str:
+                return "hello"
+
+        mcp = FastMCP("Test")
+        mcp.add_resource(MyClass.get_config)
+
+        async with Client(mcp) as client:
+            resources = await client.list_resources()
+
+        assert any(str(r.uri) == "config://static" for r in resources)
+
+    def test_resource_rejects_classmethod_decorator(self):
+        """@resource should reject classmethod-decorated functions."""
+
+        # Note: This now happens when added to server, not at decoration time
+        @resource("config://app")
+        def standalone() -> str:
+            return "{}"
+
+        # Should not raise at decoration
+        assert callable(standalone)
+
+    async def test_resource_added_to_server(self):
+        """Resource created by @resource should work when added to a server."""
+
+        @resource("config://app")
+        def get_config() -> str:
+            """Get config."""
+            return '{"version": "1.0"}'
+
+        assert callable(get_config)
+
+        mcp = FastMCP("Test")
+        mcp.add_resource(get_config)
+
+        async with Client(mcp) as client:
+            resources = await client.list_resources()
+            assert any(str(r.uri) == "config://app" for r in resources)
+
+            result = await client.read_resource("config://app")
+            assert "1.0" in str(result)
+
+    async def test_template_added_to_server(self):
+        """Template created by @resource should work when added to a server."""
+
+        @resource("users://{user_id}/profile")
+        def get_profile(user_id: str) -> str:
+            """Get user profile."""
+            return f'{{"id": "{user_id}"}}'
+
+        assert callable(get_profile)
+
+        mcp = FastMCP("Test")
+        # add_resource handles both resources and templates based on metadata
+        mcp.add_resource(get_profile)
+
+        async with Client(mcp) as client:
+            templates = await client.list_resource_templates()
+            assert any(t.uri_template == "users://{user_id}/profile" for t in templates)
+
+            result = await client.read_resource("users://123/profile")
+            assert "123" in str(result)
diff --git a/tests/scripts/test_auto_close_needs_mre.py b/tests/scripts/test_auto_close_needs_mre.py
new file mode 100644
index 0000000..8a4f089
--- /dev/null
+++ b/tests/scripts/test_auto_close_needs_mre.py
@@ -0,0 +1,68 @@
+from datetime import datetime, timedelta, timezone
+
+import pytest
+
+from scripts.auto_close_needs_mre import Comment, Issue, should_close_as_needs_mre
+
+
+def make_issue(author_association: str = "NONE") -> Issue:
+    return Issue(
+        number=1,
+        title="Bug report",
+        state="open",
+        created_at="2026-01-01T00:00:00Z",
+        user_id=123,
+        user_login="octocat",
+        body="Something is broken",
+        author_association=author_association,
+    )
+
+
+@pytest.mark.parametrize(
+    "author_association",
+    ["OWNER", "MEMBER", "COLLABORATOR"],
+)
+def test_should_not_close_maintainer_issues(author_association: str):
+    label_date = datetime.now(timezone.utc) - timedelta(days=8)
+
+    should_close = should_close_as_needs_mre(
+        issue=make_issue(author_association),
+        label_date=label_date,
+        comments=[],
+        timeline=[],
+    )
+
+    assert should_close is False
+
+
+def test_should_close_non_maintainer_issue_without_author_activity():
+    label_date = datetime.now(timezone.utc) - timedelta(days=8)
+
+    should_close = should_close_as_needs_mre(
+        issue=make_issue("CONTRIBUTOR"),
+        label_date=label_date,
+        comments=[],
+        timeline=[],
+    )
+
+    assert should_close is True
+
+
+def test_should_not_close_non_maintainer_issue_with_author_activity():
+    label_date = datetime.now(timezone.utc) - timedelta(days=8)
+    comment = Comment(
+        id=1,
+        body="Here's the MRE",
+        created_at=(label_date + timedelta(days=1)).isoformat(),
+        user_id=123,
+        user_login="octocat",
+    )
+
+    should_close = should_close_as_needs_mre(
+        issue=make_issue("CONTRIBUTOR"),
+        label_date=label_date,
+        comments=[comment],
+        timeline=[],
+    )
+
+    assert should_close is False
diff --git a/tests/server/__init__.py b/tests/server/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/server/auth/__init__.py b/tests/server/auth/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/server/auth/oauth_proxy/__init__.py b/tests/server/auth/oauth_proxy/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/server/auth/oauth_proxy/conftest.py b/tests/server/auth/oauth_proxy/conftest.py
new file mode 100644
index 0000000..4e402ad
--- /dev/null
+++ b/tests/server/auth/oauth_proxy/conftest.py
@@ -0,0 +1,312 @@
+"""Shared fixtures and helpers for OAuth proxy tests."""
+
+import asyncio
+import secrets
+import time
+from unittest.mock import Mock
+from urllib.parse import urlencode
+
+import pytest
+from mcp.server.auth.provider import AccessToken
+from starlette.applications import Starlette
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from fastmcp.server.auth.auth import TokenVerifier
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+
+class MockOAuthProvider:
+    """Mock OAuth provider for testing OAuth proxy E2E flows.
+
+    This provider simulates a complete OAuth server without requiring:
+    - Real authentication credentials
+    - Browser automation
+    - Network calls to external services
+    """
+
+    def __init__(self, port: int = 0):
+        self.port = port
+        self.base_url = f"http://localhost:{port}"
+        self.app = None
+        self.server = None
+
+        # Storage for OAuth state
+        self.authorization_codes = {}
+        self.access_tokens = {}
+        self.refresh_tokens = {}
+        self.revoked_tokens = set()
+
+        # Tracking for assertions
+        self.authorize_called = False
+        self.token_called = False
+        self.refresh_called = False
+        self.revoke_called = False
+
+        # Configuration
+        self.require_pkce = False
+        self.token_endpoint_auth_method = "client_secret_basic"
+
+    @property
+    def authorize_endpoint(self) -> str:
+        return f"{self.base_url}/authorize"
+
+    @property
+    def token_endpoint(self) -> str:
+        return f"{self.base_url}/token"
+
+    @property
+    def revocation_endpoint(self) -> str:
+        return f"{self.base_url}/revoke"
+
+    def create_app(self) -> Starlette:
+        """Create the mock OAuth server application."""
+        return Starlette(
+            routes=[
+                Route("/authorize", self.handle_authorize),
+                Route("/token", self.handle_token, methods=["POST"]),
+                Route("/revoke", self.handle_revoke, methods=["POST"]),
+            ]
+        )
+
+    async def handle_authorize(self, request):
+        """Handle authorization requests."""
+        self.authorize_called = True
+        query = dict(request.query_params)
+
+        # Validate PKCE if required
+        if self.require_pkce and "code_challenge" not in query:
+            return JSONResponse(
+                {"error": "invalid_request", "error_description": "PKCE required"},
+                status_code=400,
+            )
+
+        # Generate authorization code
+        code = secrets.token_urlsafe(32)
+        self.authorization_codes[code] = {
+            "client_id": query.get("client_id"),
+            "redirect_uri": query.get("redirect_uri"),
+            "state": query.get("state"),
+            "code_challenge": query.get("code_challenge"),
+            "code_challenge_method": query.get("code_challenge_method", "S256"),
+            "scope": query.get("scope"),
+            "created_at": time.time(),
+        }
+
+        # Redirect back to callback
+        redirect_uri = query["redirect_uri"]
+        params = {"code": code}
+        if query.get("state"):
+            params["state"] = query["state"]
+
+        redirect_url = f"{redirect_uri}?{urlencode(params)}"
+        return JSONResponse(
+            content={}, status_code=302, headers={"Location": redirect_url}
+        )
+
+    async def handle_token(self, request):
+        """Handle token requests."""
+        self.token_called = True
+        form = await request.form()
+        grant_type = form.get("grant_type")
+
+        if grant_type == "authorization_code":
+            code = form.get("code")
+            if code not in self.authorization_codes:
+                return JSONResponse(
+                    {"error": "invalid_grant", "error_description": "Invalid code"},
+                    status_code=400,
+                )
+
+            # Validate PKCE if it was used
+            auth_data = self.authorization_codes[code]
+            if auth_data.get("code_challenge"):
+                verifier = form.get("code_verifier")
+                if not verifier:
+                    return JSONResponse(
+                        {
+                            "error": "invalid_request",
+                            "error_description": "Missing code_verifier",
+                        },
+                        status_code=400,
+                    )
+                # In a real implementation, we'd validate the verifier
+
+            # Generate tokens
+            access_token = f"mock_access_{secrets.token_hex(16)}"
+            refresh_token = f"mock_refresh_{secrets.token_hex(16)}"
+
+            self.access_tokens[access_token] = {
+                "client_id": auth_data["client_id"],
+                "scope": auth_data.get("scope"),
+                "expires_at": time.time() + 3600,
+            }
+            self.refresh_tokens[refresh_token] = {
+                "client_id": auth_data["client_id"],
+                "scope": auth_data.get("scope"),
+            }
+
+            # Clean up used code
+            del self.authorization_codes[code]
+
+            return JSONResponse(
+                {
+                    "access_token": access_token,
+                    "token_type": "Bearer",
+                    "expires_in": 3600,
+                    "refresh_token": refresh_token,
+                    "scope": auth_data.get("scope"),
+                }
+            )
+
+        elif grant_type == "refresh_token":
+            self.refresh_called = True
+            refresh_token = form.get("refresh_token")
+
+            if refresh_token not in self.refresh_tokens:
+                return JSONResponse(
+                    {
+                        "error": "invalid_grant",
+                        "error_description": "Invalid refresh token",
+                    },
+                    status_code=400,
+                )
+
+            # Generate new access token
+            new_access = f"mock_access_{secrets.token_hex(16)}"
+            token_data = self.refresh_tokens[refresh_token]
+
+            self.access_tokens[new_access] = {
+                "client_id": token_data["client_id"],
+                "scope": token_data.get("scope"),
+                "expires_at": time.time() + 3600,
+            }
+
+            return JSONResponse(
+                {
+                    "access_token": new_access,
+                    "token_type": "Bearer",
+                    "expires_in": 3600,
+                    "refresh_token": refresh_token,  # Same refresh token
+                    "scope": token_data.get("scope"),
+                }
+            )
+
+        return JSONResponse({"error": "unsupported_grant_type"}, status_code=400)
+
+    async def handle_revoke(self, request):
+        """Handle token revocation."""
+        self.revoke_called = True
+        form = await request.form()
+        token = form.get("token")
+
+        if token:
+            self.revoked_tokens.add(token)
+            # Remove from active tokens
+            self.access_tokens.pop(token, None)
+            self.refresh_tokens.pop(token, None)
+
+        return JSONResponse({})
+
+    async def start(self):
+        """Start the mock OAuth server."""
+        import socket
+
+        from uvicorn import Config, Server
+
+        self.app = self.create_app()
+
+        # If port is 0, find an available port
+        if self.port == 0:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.bind(("127.0.0.1", 0))
+                s.listen(1)
+                self.port = s.getsockname()[1]
+
+        self.base_url = f"http://localhost:{self.port}"
+        config = Config(
+            self.app,
+            host="localhost",
+            port=self.port,
+            log_level="error",
+            ws="websockets-sansio",
+        )
+        self.server = Server(config)
+
+        # Start server in background
+        asyncio.create_task(self.server.serve())
+
+        # Wait for server to be ready
+        await asyncio.sleep(0.05)
+
+    async def stop(self):
+        """Stop the mock OAuth server."""
+        if self.server:
+            self.server.should_exit = True
+            await asyncio.sleep(0.01)
+
+    def reset(self):
+        """Reset all state for next test."""
+        self.authorization_codes.clear()
+        self.access_tokens.clear()
+        self.refresh_tokens.clear()
+        self.revoked_tokens.clear()
+        self.authorize_called = False
+        self.token_called = False
+        self.refresh_called = False
+        self.revoke_called = False
+
+
+class MockTokenVerifier(TokenVerifier):
+    """Mock token verifier for testing."""
+
+    def __init__(self, required_scopes=None):
+        self.required_scopes = required_scopes or ["read", "write"]
+        self.verify_called = False
+
+    async def verify_token(self, token: str) -> AccessToken | None:  # type: ignore[override]  # ty:ignore[invalid-method-override]
+        """Mock token verification."""
+        self.verify_called = True
+        return AccessToken(
+            token=token,
+            client_id="mock-client",
+            scopes=self.required_scopes,
+            expires_at=int(time.time() + 3600),
+        )
+
+
+@pytest.fixture
+def jwt_verifier():
+    """Create a mock JWT verifier for testing."""
+    verifier = Mock(spec=JWTVerifier)
+    verifier.required_scopes = ["read", "write"]
+    verifier.verify_token = Mock(return_value=None)
+    return verifier
+
+
+@pytest.fixture
+def oauth_proxy(jwt_verifier):
+    """Create a standard OAuthProxy instance for testing."""
+    from key_value.aio.stores.memory import MemoryStore
+
+    return OAuthProxy(
+        upstream_authorization_endpoint="https://github.com/login/oauth/authorize",
+        upstream_token_endpoint="https://github.com/login/oauth/access_token",
+        upstream_client_id="test-client-id",
+        upstream_client_secret="test-client-secret",
+        token_verifier=jwt_verifier,
+        base_url="https://myserver.com",
+        redirect_path="/auth/callback",
+        jwt_signing_key="test-secret",
+        client_storage=MemoryStore(),
+    )
+
+
+@pytest.fixture
+async def mock_oauth_provider():
+    """Create and start a mock OAuth provider."""
+    provider = MockOAuthProvider()
+    await provider.start()
+    yield provider
+    await provider.stop()
diff --git a/tests/server/auth/oauth_proxy/test_authorization.py b/tests/server/auth/oauth_proxy/test_authorization.py
new file mode 100644
index 0000000..791ffba
--- /dev/null
+++ b/tests/server/auth/oauth_proxy/test_authorization.py
@@ -0,0 +1,200 @@
+"""Tests for OAuth proxy authorization flow."""
+
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+from key_value.aio.stores.memory import MemoryStore
+from mcp.server.auth.provider import AuthorizationParams
+from mcp.shared.auth import OAuthClientInformationFull
+from pydantic import AnyUrl
+
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+
+
+class TestOAuthProxyAuthorization:
+    """Tests for OAuth proxy authorization flow."""
+
+    async def test_authorize_creates_transaction(self, oauth_proxy):
+        """Test that authorize creates transaction and redirects to consent."""
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:54321/callback")],
+            jwt_signing_key="test-secret",  # type: ignore[call-arg]  # Optional field in MCP SDK  # ty:ignore[unknown-argument]
+        )
+
+        # Register client first (required for consent flow)
+        await oauth_proxy.register_client(client)
+
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:54321/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="client-state-123",
+            code_challenge="challenge-abc",
+            scopes=["read", "write"],
+        )
+
+        redirect_url = await oauth_proxy.authorize(client, params)
+
+        # Parse the redirect URL
+        parsed = urlparse(redirect_url)
+        query_params = parse_qs(parsed.query)
+
+        # Should redirect to consent page
+        assert "/consent" in redirect_url
+        assert "txn_id" in query_params
+
+        # Verify transaction was stored with correct data
+        txn_id = query_params["txn_id"][0]
+        transaction = await oauth_proxy._transaction_store.get(key=txn_id)
+        assert transaction is not None
+        assert transaction.client_id == "test-client"
+        assert transaction.code_challenge == "challenge-abc"
+        assert transaction.client_state == "client-state-123"
+        assert transaction.scopes == ["read", "write"]
+
+
+class TestOAuthProxyPKCE:
+    """Tests for OAuth proxy PKCE forwarding."""
+
+    @pytest.fixture
+    def proxy_with_pkce(self, jwt_verifier):
+        return OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            forward_pkce=True,
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+    @pytest.fixture
+    def proxy_without_pkce(self, jwt_verifier):
+        from fastmcp.server.auth.oauth_proxy import OAuthProxy
+
+        return OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            forward_pkce=False,
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+    async def test_pkce_forwarding_enabled(self, proxy_with_pkce):
+        """Test that proxy generates and forwards its own PKCE."""
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        # Register client first
+        await proxy_with_pkce.register_client(client)
+
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="client-state",
+            code_challenge="client_challenge",
+            scopes=["read"],
+        )
+
+        redirect_url = await proxy_with_pkce.authorize(client, params)
+        query_params = parse_qs(urlparse(redirect_url).query)
+
+        # Should redirect to consent page
+        assert "/consent" in redirect_url
+        assert "txn_id" in query_params
+
+        # Transaction should store both challenges
+        txn_id = query_params["txn_id"][0]
+        transaction = await proxy_with_pkce._transaction_store.get(key=txn_id)
+        assert transaction is not None
+        assert transaction.code_challenge == "client_challenge"  # Client's
+        assert transaction.proxy_code_verifier is not None  # Proxy's verifier
+        # Proxy code challenge is computed from verifier when building upstream URL
+        # Just verify the verifier exists and is different from client's challenge
+        assert len(transaction.proxy_code_verifier) > 0
+
+    async def test_pkce_forwarding_disabled(self, proxy_without_pkce):
+        """Test that PKCE is not forwarded when disabled."""
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        # Register client first
+        await proxy_without_pkce.register_client(client)
+
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="client-state",
+            code_challenge="client_challenge",
+            scopes=["read"],
+        )
+
+        redirect_url = await proxy_without_pkce.authorize(client, params)
+        query_params = parse_qs(urlparse(redirect_url).query)
+
+        # Should redirect to consent page
+        assert "/consent" in redirect_url
+        assert "txn_id" in query_params
+
+        # Client's challenge still stored, but no proxy PKCE
+        txn_id = query_params["txn_id"][0]
+        transaction = await proxy_without_pkce._transaction_store.get(key=txn_id)
+        assert transaction is not None
+        assert transaction.code_challenge == "client_challenge"
+        assert transaction.proxy_code_verifier is None  # No proxy PKCE when disabled
+
+
+class TestParameterForwarding:
+    """Tests for parameter forwarding in OAuth proxy."""
+
+    async def test_extra_authorize_params_forwarded(self, jwt_verifier):
+        """Test that extra authorize parameters are forwarded to upstream."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret",
+            extra_authorize_params={
+                "audience": "https://api.example.com",
+                "prompt": "consent",
+                "max_age": "3600",
+            },
+            client_storage=MemoryStore(),
+        )
+
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        await proxy.register_client(client)
+
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="client-state",
+            code_challenge="challenge",
+            scopes=["read"],
+            # No resource parameter
+        )
+
+        # Should succeed (no resource check needed)
+        redirect_url = await proxy.authorize(client, params)
+        assert "/consent" in redirect_url
diff --git a/tests/server/auth/oauth_proxy/test_client_registration.py b/tests/server/auth/oauth_proxy/test_client_registration.py
new file mode 100644
index 0000000..a074c75
--- /dev/null
+++ b/tests/server/auth/oauth_proxy/test_client_registration.py
@@ -0,0 +1,283 @@
+"""Tests for OAuth proxy client registration (DCR)."""
+
+import httpx
+import pytest
+from mcp.server.auth.provider import RegistrationError
+from mcp.shared.auth import OAuthClientInformationFull
+from pydantic import AnyUrl
+from starlette.applications import Starlette
+
+from fastmcp.server.auth.oauth_proxy.models import InvalidRedirectUriError
+
+
+class TestOAuthProxyClientRegistration:
+    """Tests for OAuth proxy client registration (DCR)."""
+
+    async def test_register_client(self, oauth_proxy):
+        """Test client registration creates ProxyDCRClient."""
+        client_info = OAuthClientInformationFull(
+            client_id="original-client",
+            client_secret="original-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        await oauth_proxy.register_client(client_info)
+
+        # Client should be retrievable with original credentials
+        stored = await oauth_proxy.get_client("original-client")
+        assert stored is not None
+        assert stored.client_id == "original-client"
+        # Proxy uses token_endpoint_auth_method="none", so client_secret is not stored
+        assert stored.client_secret is None
+
+    async def test_register_client_allows_external_https_by_default(self, oauth_proxy):
+        """Default DCR registration accepts ordinary external HTTPS callbacks."""
+        client_info = OAuthClientInformationFull(
+            client_id="https-client",
+            client_secret="original-secret",
+            redirect_uris=[AnyUrl("https://client.example.com/callback")],
+        )
+
+        await oauth_proxy.register_client(client_info)
+
+        stored = await oauth_proxy.get_client("https-client")
+        assert stored is not None
+        assert stored.redirect_uris == [AnyUrl("https://client.example.com/callback")]
+
+    async def test_register_client_rejects_unsafe_redirect_scheme_by_default(
+        self, oauth_proxy
+    ):
+        """Default DCR registration rejects active browser redirect schemes."""
+        client_info = OAuthClientInformationFull(
+            client_id="javascript-client",
+            client_secret="original-secret",
+            redirect_uris=[AnyUrl("javascript:alert(document.cookie)//")],
+        )
+
+        with pytest.raises(RegistrationError, match="invalid_redirect_uri"):
+            await oauth_proxy.register_client(client_info)
+
+    async def test_register_client_without_redirect_uris_defers_allowlist_validation(
+        self, oauth_proxy
+    ):
+        """DCR clients may omit redirect_uris until the authorization request."""
+        oauth_proxy._allowed_client_redirect_uris = ["https://client.example/*"]
+        client_info = OAuthClientInformationFull(
+            client_id="deferred-client",
+            client_secret="original-secret",
+            redirect_uris=None,
+        )
+
+        await oauth_proxy.register_client(client_info)
+
+        stored = await oauth_proxy.get_client("deferred-client")
+        assert stored is not None
+        assert stored.redirect_uris is not None
+        assert str(stored.redirect_uris[0]).rstrip("/") == "http://localhost"
+
+        redirect_uri = stored.validate_redirect_uri(
+            AnyUrl("https://client.example/callback")
+        )
+        assert str(redirect_uri) == "https://client.example/callback"
+
+        with pytest.raises(InvalidRedirectUriError):
+            stored.validate_redirect_uri(None)
+
+    async def test_get_registered_client(self, oauth_proxy):
+        """Test retrieving a registered client."""
+        client_info = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:8080/callback")],
+        )
+        await oauth_proxy.register_client(client_info)
+
+        retrieved = await oauth_proxy.get_client("test-client")
+        assert retrieved is not None
+        assert retrieved.client_id == "test-client"
+
+    async def test_get_unregistered_client_returns_none(self, oauth_proxy):
+        """Test that unregistered clients return None."""
+        client = await oauth_proxy.get_client("unknown-client")
+        assert client is None
+
+    async def test_dcr_client_rejects_unregistered_redirect_uri(self, oauth_proxy):
+        """DCR clients honor their registered redirect_uris by default."""
+        client_info = OAuthClientInformationFull(
+            client_id="original-client",
+            client_secret="original-secret",
+            redirect_uris=[AnyUrl("http://localhost:6274/oauth/callback")],
+        )
+
+        await oauth_proxy.register_client(client_info)
+
+        retrieved = await oauth_proxy.get_client("original-client")
+        assert retrieved is not None
+
+        with pytest.raises(InvalidRedirectUriError):
+            retrieved.validate_redirect_uri(AnyUrl("http://evil.com/anything"))
+        with pytest.raises(InvalidRedirectUriError):
+            retrieved.validate_redirect_uri(AnyUrl("http://localhost:6274/other"))
+
+        uri = retrieved.validate_redirect_uri(
+            AnyUrl("http://localhost:51353/oauth/callback")
+        )
+        assert str(uri) == "http://localhost:51353/oauth/callback"
+
+    async def test_dcr_client_accepts_registered_external_redirect_uri(
+        self, oauth_proxy
+    ):
+        """Open DCR still accepts arbitrary redirect URIs that clients register."""
+        client_info = OAuthClientInformationFull(
+            client_id="external-client",
+            client_secret="external-secret",
+            redirect_uris=[AnyUrl("https://client.example.com/oauth/callback")],
+        )
+
+        await oauth_proxy.register_client(client_info)
+
+        retrieved = await oauth_proxy.get_client("external-client")
+        assert retrieved is not None
+
+        uri = retrieved.validate_redirect_uri(
+            AnyUrl("https://client.example.com/oauth/callback")
+        )
+        assert str(uri) == "https://client.example.com/oauth/callback"
+
+    async def test_enforcing_allowed_redirect_uris(self, oauth_proxy):
+        """Test enforcing allowed redirect uris configuration."""
+
+        oauth_proxy._allowed_client_redirect_uris = ["http://localhost:12345/callback"]
+
+        client_info = OAuthClientInformationFull(
+            client_id="original-client",
+            client_secret="original-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        await oauth_proxy.register_client(client_info)
+        retrieved = await oauth_proxy.get_client("original-client")
+        assert retrieved.allowed_redirect_uri_patterns == [
+            "http://localhost:12345/callback"
+        ]
+
+        oauth_proxy._allowed_client_redirect_uris = [
+            "http://localhost:12345/updated_callback"
+        ]
+
+        retrieved = await oauth_proxy.get_client("original-client")
+        assert retrieved.allowed_redirect_uri_patterns == [
+            "http://localhost:12345/updated_callback"
+        ]
+
+    async def test_update_default_scopes_applies_to_dcr_registration(self, oauth_proxy):
+        """DCR clients without scope should receive the updated default scopes."""
+        oauth_proxy.update_default_scopes(["read", "write", "calendar"])
+
+        app = Starlette(routes=oauth_proxy.get_routes())
+        transport = httpx.ASGITransport(app=app)
+
+        async with httpx.AsyncClient(
+            transport=transport,
+            base_url="https://myserver.com",
+        ) as client:
+            response = await client.post(
+                "/register",
+                json={
+                    "redirect_uris": ["https://client.example.com/callback"],
+                    "client_name": "Test Client",
+                },
+            )
+
+        assert response.status_code == 201
+        client_info = response.json()
+        assert client_info["scope"] == "read write calendar"
+
+        registered_client = await oauth_proxy.get_client(client_info["client_id"])
+        assert registered_client is not None
+        assert registered_client.scope == "read write calendar"
+
+
+class TestUpstreamClientIdFallback:
+    """Tests for clients that skip DCR and use the upstream client_id directly."""
+
+    async def test_upstream_client_id_returns_synthetic_client(self, oauth_proxy):
+        """Clients that skip DCR and use upstream client_id directly are accepted."""
+        # oauth_proxy fixture uses "test-client-id" as upstream_client_id
+        client = await oauth_proxy.get_client("test-client-id")
+        assert client is not None
+        assert client.client_id == "test-client-id"
+        assert client.client_secret is None
+        assert client.token_endpoint_auth_method == "none"
+
+    async def test_upstream_client_id_inherits_allowed_redirect_uris(self, oauth_proxy):
+        """Synthetic upstream client respects the proxy's redirect URI restrictions."""
+        oauth_proxy._allowed_client_redirect_uris = ["http://localhost:*"]
+        client = await oauth_proxy.get_client("test-client-id")
+        assert client is not None
+        assert client.allowed_redirect_uri_patterns == ["http://localhost:*"]
+
+    async def test_unknown_client_id_still_returns_none(self, oauth_proxy):
+        """Non-upstream, unregistered IDs still return None."""
+        client = await oauth_proxy.get_client("some-random-client-id")
+        assert client is None
+
+    async def test_redirect_uri_allowed_when_no_pattern_restriction(self, oauth_proxy):
+        """Ordinary redirect URIs are accepted when allowed_client_redirect_uris is None."""
+        assert oauth_proxy._allowed_client_redirect_uris is None
+        client = await oauth_proxy.get_client("test-client-id")
+        assert client is not None
+        uri = client.validate_redirect_uri(AnyUrl("https://claude.ai/oauth/callback"))
+        assert str(uri) == "https://claude.ai/oauth/callback"
+        uri = client.validate_redirect_uri(
+            AnyUrl("cursor://anysphere.cursor-mcp/oauth/callback")
+        )
+        assert str(uri) == "cursor://anysphere.cursor-mcp/oauth/callback"
+
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("javascript:alert(document.cookie)//"))
+
+    async def test_redirect_uri_validated_against_patterns(self, oauth_proxy):
+        """Redirect URI validation honours allowed_client_redirect_uris when set."""
+        oauth_proxy._allowed_client_redirect_uris = ["http://localhost:*"]
+        client = await oauth_proxy.get_client("test-client-id")
+        assert client is not None
+
+        # Allowed URI passes
+        uri = client.validate_redirect_uri(AnyUrl("http://localhost:12345/callback"))
+        assert str(uri) == "http://localhost:12345/callback"
+
+        # Disallowed URI raises
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("https://evil.example.com/callback"))
+
+    async def test_redirect_uri_blocked_when_empty_allowlist(self, oauth_proxy):
+        """Empty allowed_client_redirect_uris blocks all redirect URIs, including localhost."""
+        oauth_proxy._allowed_client_redirect_uris = []
+        client = await oauth_proxy.get_client("test-client-id")
+        assert client is not None
+
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("http://localhost/callback"))
+
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("https://claude.ai/oauth/callback"))
+
+    async def test_none_redirect_uri_validated_against_patterns(self, oauth_proxy):
+        """redirect_uri=None resolves to the placeholder then validates against patterns."""
+        # Placeholder is http://localhost — a pattern that can't match it forces rejection.
+        oauth_proxy._allowed_client_redirect_uris = ["https://myapp.example.com/*"]
+        client = await oauth_proxy.get_client("test-client-id")
+        assert client is not None
+
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(None)
+
+    async def test_none_redirect_uri_rejected_when_empty_allowlist(self, oauth_proxy):
+        """redirect_uri=None is rejected when allowlist is empty ([] blocks the resolved URI too)."""
+        oauth_proxy._allowed_client_redirect_uris = []
+        client = await oauth_proxy.get_client("test-client-id")
+        assert client is not None
+
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(None)
diff --git a/tests/server/auth/oauth_proxy/test_config.py b/tests/server/auth/oauth_proxy/test_config.py
new file mode 100644
index 0000000..a69330a
--- /dev/null
+++ b/tests/server/auth/oauth_proxy/test_config.py
@@ -0,0 +1,491 @@
+"""Tests for OAuth proxy configuration and validation."""
+
+import pytest
+from key_value.aio.stores.memory import MemoryStore
+from mcp.server.auth.provider import AuthorizationParams, AuthorizeError
+from mcp.shared.auth import OAuthClientInformationFull
+from pydantic import AnyHttpUrl, AnyUrl
+
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.server.auth.oauth_proxy.proxy import (
+    _normalize_resource_url,
+    _server_url_has_query,
+)
+
+
+class TestNormalizeResourceUrl:
+    """Unit tests for the _normalize_resource_url helper function."""
+
+    @pytest.mark.parametrize(
+        "url,expected",
+        [
+            # Basic URL unchanged
+            ("https://example.com/mcp", "https://example.com/mcp"),
+            # Query parameters stripped
+            ("https://example.com/mcp?foo=bar", "https://example.com/mcp"),
+            ("https://example.com/mcp?a=1&b=2", "https://example.com/mcp"),
+            # Fragments stripped
+            ("https://example.com/mcp#section", "https://example.com/mcp"),
+            # Both query and fragment stripped
+            ("https://example.com/mcp?foo=bar#section", "https://example.com/mcp"),
+            # Trailing slash stripped
+            ("https://example.com/mcp/", "https://example.com/mcp"),
+            # Trailing slash with query params
+            ("https://example.com/mcp/?foo=bar", "https://example.com/mcp"),
+            # Preserves path structure
+            (
+                "https://example.com/api/v2/mcp?kb_name=test",
+                "https://example.com/api/v2/mcp",
+            ),
+            # Preserves port
+            ("https://example.com:8080/mcp?foo=bar", "https://example.com:8080/mcp"),
+            # Root path
+            ("https://example.com/?foo=bar", "https://example.com"),
+            ("https://example.com/", "https://example.com"),
+        ],
+    )
+    def test_normalizes_urls_correctly(self, url: str, expected: str):
+        """Test that URLs are normalized by stripping query params, fragments, and trailing slashes."""
+        assert _normalize_resource_url(url) == expected
+
+    @pytest.mark.parametrize(
+        "url,has_query",
+        [
+            ("https://example.com/mcp", False),
+            ("https://example.com/mcp?foo=bar", True),
+            ("https://example.com/mcp?", False),  # Empty query string
+            ("https://example.com/mcp#fragment", False),
+            ("https://example.com/mcp?a=1&b=2", True),
+        ],
+    )
+    def test_server_url_has_query(self, url: str, has_query: bool):
+        """Test detection of query parameters in server URLs."""
+        assert _server_url_has_query(url) == has_query
+
+
+class TestResourceURLValidation:
+    """Tests for OAuth Proxy resource URL validation (GHSA-5h2m-4q8j-pqpj fix)."""
+
+    @pytest.fixture
+    def proxy_with_resource_url(self, jwt_verifier):
+        """Create an OAuthProxy with set_mcp_path called."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+        # Use non-default path to prove fix isn't relying on old hardcoded /mcp
+        proxy.set_mcp_path("/api/v2/mcp")
+        return proxy
+
+    async def test_authorize_rejects_mismatched_resource(self, proxy_with_resource_url):
+        """Test that authorization rejects requests with mismatched resource."""
+
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        await proxy_with_resource_url.register_client(client)
+
+        # Client requests a different resource than the server's
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="client-state",
+            code_challenge="challenge",
+            scopes=["read"],
+            resource="https://malicious-server.com/mcp",  # Wrong resource
+        )
+
+        with pytest.raises(AuthorizeError) as exc_info:
+            await proxy_with_resource_url.authorize(client, params)
+
+        assert exc_info.value.error == "invalid_target"
+        assert exc_info.value.error_description is not None
+        assert "Resource does not match" in exc_info.value.error_description
+
+    async def test_authorize_accepts_matching_resource(self, proxy_with_resource_url):
+        """Test that authorization accepts requests with matching resource."""
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        await proxy_with_resource_url.register_client(client)
+
+        # Client requests the correct resource (must match /api/v2/mcp path)
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="client-state",
+            code_challenge="challenge",
+            scopes=["read"],
+            resource="https://proxy.example.com/api/v2/mcp",  # Correct resource
+        )
+
+        # Should succeed (redirect to consent page)
+        redirect_url = await proxy_with_resource_url.authorize(client, params)
+        assert "/consent" in redirect_url
+
+    async def test_authorize_rejects_old_hardcoded_mcp_path(
+        self, proxy_with_resource_url
+    ):
+        """Test that old hardcoded /mcp path is rejected when server uses different path."""
+
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        await proxy_with_resource_url.register_client(client)
+
+        # Client requests the old hardcoded /mcp path (would have worked before fix)
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="client-state",
+            code_challenge="challenge",
+            scopes=["read"],
+            resource="https://proxy.example.com/mcp",  # Old hardcoded path
+        )
+
+        # Should fail because server is at /api/v2/mcp, not /mcp
+        with pytest.raises(AuthorizeError) as exc_info:
+            await proxy_with_resource_url.authorize(client, params)
+
+        assert exc_info.value.error == "invalid_target"
+
+    async def test_authorize_accepts_no_resource(self, proxy_with_resource_url):
+        """Test that authorization accepts requests without resource parameter."""
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        await proxy_with_resource_url.register_client(client)
+
+        # Client doesn't specify resource
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="client-state",
+            code_challenge="challenge",
+            scopes=["read"],
+            # No resource parameter
+        )
+
+        # Should succeed (no resource check needed)
+        redirect_url = await proxy_with_resource_url.authorize(client, params)
+        assert "/consent" in redirect_url
+
+    async def test_authorize_accepts_resource_with_query_params(
+        self, proxy_with_resource_url
+    ):
+        """Test that authorization accepts resource URLs with query parameters.
+
+        Per RFC 8707, clients may include query parameters in resource URLs.
+        ChatGPT sends resource URLs like ?kb_name=X, which should match the
+        server's resource URL that doesn't include query params.
+        """
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        await proxy_with_resource_url.register_client(client)
+
+        # Client requests resource with query params (like ChatGPT does)
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="client-state",
+            code_challenge="challenge",
+            scopes=["read"],
+            resource="https://proxy.example.com/api/v2/mcp?kb_name=test",
+        )
+
+        # Should succeed - base URL matches, query params are normalized away
+        redirect_url = await proxy_with_resource_url.authorize(client, params)
+        assert "/consent" in redirect_url
+
+    async def test_authorize_rejects_different_path_with_query_params(
+        self, proxy_with_resource_url
+    ):
+        """Test that query param normalization doesn't bypass path validation."""
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        await proxy_with_resource_url.register_client(client)
+
+        # Client requests wrong path but with query params
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="client-state",
+            code_challenge="challenge",
+            scopes=["read"],
+            resource="https://proxy.example.com/wrong/path?kb_name=test",
+        )
+
+        # Should fail - path doesn't match even after normalizing query params
+        with pytest.raises(AuthorizeError) as exc_info:
+            await proxy_with_resource_url.authorize(client, params)
+
+        assert exc_info.value.error == "invalid_target"
+
+    async def test_authorize_requires_exact_match_when_server_has_query_params(
+        self, jwt_verifier
+    ):
+        """Test that when server URL has query params, exact match is required.
+
+        If a server configures its resource URL with query params (e.g., for
+        multi-tenant or per-KB scoping), clients must provide the exact same
+        query params. This prevents bypassing tenant isolation.
+        """
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+        proxy.set_mcp_path("/mcp")
+        # Simulate server configured with query params for tenant scoping
+        proxy._resource_url = AnyHttpUrl("https://proxy.example.com/mcp?tenant=acme")
+
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+        await proxy.register_client(client)
+
+        # Client requests with DIFFERENT query params - should fail
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="client-state",
+            code_challenge="challenge",
+            scopes=["read"],
+            resource="https://proxy.example.com/mcp?tenant=other",  # Wrong tenant!
+        )
+
+        with pytest.raises(AuthorizeError) as exc_info:
+            await proxy.authorize(client, params)
+
+        assert exc_info.value.error == "invalid_target"
+
+    async def test_authorize_accepts_exact_match_when_server_has_query_params(
+        self, jwt_verifier
+    ):
+        """Test that exact query param match succeeds when server has query params."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+        proxy.set_mcp_path("/mcp")
+        # Simulate server configured with query params for tenant scoping
+        proxy._resource_url = AnyHttpUrl("https://proxy.example.com/mcp?tenant=acme")
+
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+        await proxy.register_client(client)
+
+        # Client requests with SAME query params - should succeed
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="client-state",
+            code_challenge="challenge",
+            scopes=["read"],
+            resource="https://proxy.example.com/mcp?tenant=acme",  # Exact match
+        )
+
+        redirect_url = await proxy.authorize(client, params)
+        assert "/consent" in redirect_url
+
+    async def test_authorize_rejects_no_query_when_server_has_query_params(
+        self, jwt_verifier
+    ):
+        """Test that missing query params are rejected when server requires them."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+        proxy.set_mcp_path("/mcp")
+        # Simulate server configured with query params for tenant scoping
+        proxy._resource_url = AnyHttpUrl("https://proxy.example.com/mcp?tenant=acme")
+
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+        await proxy.register_client(client)
+
+        # Client requests WITHOUT query params - should fail
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="client-state",
+            code_challenge="challenge",
+            scopes=["read"],
+            resource="https://proxy.example.com/mcp",  # Missing tenant param!
+        )
+
+        with pytest.raises(AuthorizeError) as exc_info:
+            await proxy.authorize(client, params)
+
+        assert exc_info.value.error == "invalid_target"
+
+    def test_set_mcp_path_creates_jwt_issuer_with_correct_audience(self, jwt_verifier):
+        """Test that set_mcp_path creates JWTIssuer with correct audience."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        # Before set_mcp_path, _jwt_issuer is None
+        assert proxy._jwt_issuer is None
+
+        # Call set_mcp_path with custom path
+        proxy.set_mcp_path("/custom/mcp")
+
+        # After set_mcp_path, _jwt_issuer should be created
+        assert proxy._jwt_issuer is not None
+        assert proxy.jwt_issuer.audience == "https://proxy.example.com/custom/mcp"
+        assert proxy.jwt_issuer.issuer == "https://proxy.example.com/"
+
+    def test_set_mcp_path_uses_base_url_if_no_path(self, jwt_verifier):
+        """Test that set_mcp_path uses base_url as audience if no path provided."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        proxy.set_mcp_path(None)
+
+        assert proxy.jwt_issuer.audience == "https://proxy.example.com/"
+
+    def test_set_mcp_path_uses_resource_base_url_for_audience(self, jwt_verifier):
+        """Test that resource_base_url controls the protected resource audience."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com/oauth",
+            resource_base_url="https://api.example.com",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        proxy.set_mcp_path("/mcp")
+
+        assert proxy.jwt_issuer.issuer == "https://proxy.example.com/oauth"
+        assert proxy.jwt_issuer.audience == "https://api.example.com/mcp"
+
+    def test_set_mcp_path_none_uses_resource_base_url_for_audience(self, jwt_verifier):
+        """Test that resource_base_url is used as audience when mcp_path is None."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com/oauth",
+            resource_base_url="https://api.example.com",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        proxy.set_mcp_path(None)
+
+        assert proxy.jwt_issuer.issuer == "https://proxy.example.com/oauth"
+        assert proxy.jwt_issuer.audience == "https://api.example.com/"
+
+    def test_jwt_issuer_property_raises_if_not_initialized(self, jwt_verifier):
+        """Test that jwt_issuer property raises if set_mcp_path not called."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        with pytest.raises(RuntimeError) as exc_info:
+            _ = proxy.jwt_issuer
+
+        assert "JWT issuer not initialized" in str(exc_info.value)
+
+    def test_get_routes_calls_set_mcp_path(self, jwt_verifier):
+        """Test that get_routes() calls set_mcp_path() to initialize JWT issuer."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        # Before get_routes, _jwt_issuer is None
+        assert proxy._jwt_issuer is None
+
+        # get_routes should call set_mcp_path internally
+        proxy.get_routes("/api/mcp")
+
+        # After get_routes, _jwt_issuer should be created with correct audience
+        assert proxy._jwt_issuer is not None
+        assert proxy.jwt_issuer.audience == "https://proxy.example.com/api/mcp"
diff --git a/tests/server/auth/oauth_proxy/test_e2e.py b/tests/server/auth/oauth_proxy/test_e2e.py
new file mode 100644
index 0000000..39c4592
--- /dev/null
+++ b/tests/server/auth/oauth_proxy/test_e2e.py
@@ -0,0 +1,244 @@
+"""End-to-end tests for OAuth proxy using mock provider."""
+
+import time
+from unittest.mock import AsyncMock, patch
+from urllib.parse import parse_qs, urlparse
+
+import httpx
+from key_value.aio.stores.memory import MemoryStore
+from mcp.server.auth.provider import AuthorizationCode, AuthorizationParams
+from mcp.shared.auth import OAuthClientInformationFull
+from pydantic import AnyUrl
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.auth import RefreshToken
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.server.auth.oauth_proxy.models import ClientCode
+from tests.server.auth.oauth_proxy.conftest import MockTokenVerifier
+
+
+class TestOAuthProxyE2E:
+    """End-to-end tests using mock OAuth provider."""
+
+    async def test_full_oauth_flow_with_mock_provider(self, mock_oauth_provider):
+        """Test complete OAuth flow with mock provider."""
+        # Create proxy pointing to mock provider
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint=mock_oauth_provider.authorize_endpoint,
+            upstream_token_endpoint=mock_oauth_provider.token_endpoint,
+            upstream_client_id="mock-client",
+            upstream_client_secret="mock-secret",
+            token_verifier=MockTokenVerifier(),
+            base_url="http://localhost:8000",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        # Create FastMCP server with proxy
+        server = FastMCP("Test Server", auth=proxy)
+
+        @server.tool
+        def protected_tool() -> str:
+            return "Protected data"
+
+        # Start authorization flow
+        client_info = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        # Register client first
+        await proxy.register_client(client_info)
+
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="client-state",
+            code_challenge="",  # Empty string for no PKCE
+            scopes=["read"],
+        )
+
+        # Get authorization URL (now returns consent redirect)
+        auth_url = await proxy.authorize(client_info, params)
+
+        # Should redirect to consent page
+        assert "/consent" in auth_url
+        query_params = parse_qs(urlparse(auth_url).query)
+        assert "txn_id" in query_params
+
+        # Verify transaction was created with correct configuration
+        txn_id = query_params["txn_id"][0]
+        transaction = await proxy._transaction_store.get(key=txn_id)
+        assert transaction is not None
+        assert transaction.client_id == "test-client"
+        assert transaction.scopes == ["read"]
+        # Transaction ID itself is used as upstream state parameter
+        assert transaction.txn_id == txn_id
+
+    async def test_token_refresh_with_mock_provider(self, mock_oauth_provider):
+        """Test token refresh flow with mock provider."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint=mock_oauth_provider.authorize_endpoint,
+            upstream_token_endpoint=mock_oauth_provider.token_endpoint,
+            upstream_client_id="mock-client",
+            upstream_client_secret="mock-secret",
+            token_verifier=MockTokenVerifier(),
+            base_url="http://localhost:8000",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        # Initialize JWT issuer before token operations
+        proxy.set_mcp_path("/mcp")
+
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        # Register client first
+        await proxy.register_client(client)
+
+        # Set up initial upstream tokens in mock provider
+        upstream_refresh_token = "mock_refresh_initial"
+        mock_oauth_provider.refresh_tokens[upstream_refresh_token] = {
+            "client_id": "mock-client",
+            "scope": "read write",
+        }
+
+        with patch(
+            "fastmcp.server.auth.oauth_proxy.proxy.AsyncOAuth2Client"
+        ) as MockClient:
+            mock_client = AsyncMock()
+
+            # Mock initial token exchange to get FastMCP tokens
+            mock_client.fetch_token = AsyncMock(
+                return_value={
+                    "access_token": "upstream-access-initial",
+                    "refresh_token": upstream_refresh_token,
+                    "expires_in": 3600,
+                    "token_type": "Bearer",
+                }
+            )
+
+            # Configure mock to call real provider for refresh
+            async def mock_refresh(*args, **kwargs):
+                async with httpx.AsyncClient() as http:
+                    response = await http.post(
+                        mock_oauth_provider.token_endpoint,
+                        data={
+                            "grant_type": "refresh_token",
+                            "refresh_token": upstream_refresh_token,
+                        },
+                    )
+                    return response.json()
+
+            mock_client.refresh_token = mock_refresh
+            MockClient.return_value = mock_client
+
+            # Store client code that would be created during OAuth callback
+            client_code = ClientCode(
+                code="test-auth-code",
+                client_id="test-client",
+                redirect_uri="http://localhost:12345/callback",
+                code_challenge="",
+                code_challenge_method="S256",
+                scopes=["read", "write"],
+                idp_tokens={
+                    "access_token": "upstream-access-initial",
+                    "refresh_token": upstream_refresh_token,
+                    "expires_in": 3600,
+                    "token_type": "Bearer",
+                },
+                expires_at=time.time() + 300,
+                created_at=time.time(),
+            )
+            await proxy._code_store.put(key=client_code.code, value=client_code)
+
+            # Exchange authorization code to get FastMCP tokens
+            auth_code = AuthorizationCode(
+                code="test-auth-code",
+                scopes=["read", "write"],
+                expires_at=time.time() + 300,
+                client_id="test-client",
+                code_challenge="",
+                redirect_uri=AnyUrl("http://localhost:12345/callback"),
+                redirect_uri_provided_explicitly=True,
+            )
+            initial_result = await proxy.exchange_authorization_code(
+                client=client,
+                authorization_code=auth_code,
+            )
+
+            # Now test refresh with the valid FastMCP refresh token
+            assert initial_result.refresh_token is not None
+            fastmcp_refresh = RefreshToken(
+                token=initial_result.refresh_token,
+                client_id="test-client",
+                scopes=["read"],
+                expires_at=None,
+            )
+
+            result = await proxy.exchange_refresh_token(
+                client, fastmcp_refresh, ["read"]
+            )
+
+            # Should return new FastMCP tokens (not upstream tokens)
+            assert result.access_token != "upstream-access-initial"
+            # FastMCP tokens are JWTs (have 3 segments)
+            assert len(result.access_token.split(".")) == 3
+            assert mock_oauth_provider.refresh_called
+
+    async def test_pkce_validation_with_mock_provider(self, mock_oauth_provider):
+        """Test PKCE validation with mock provider."""
+        mock_oauth_provider.require_pkce = True
+
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint=mock_oauth_provider.authorize_endpoint,
+            upstream_token_endpoint=mock_oauth_provider.token_endpoint,
+            upstream_client_id="mock-client",
+            upstream_client_secret="mock-secret",
+            token_verifier=MockTokenVerifier(),
+            base_url="http://localhost:8000",
+            forward_pkce=True,  # Enable PKCE forwarding
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        # Register client first
+        await proxy.register_client(client)
+
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="client-state",
+            code_challenge="client_challenge_value",
+            scopes=["read"],
+        )
+
+        # Start authorization with PKCE
+        auth_url = await proxy.authorize(client, params)
+        query_params = parse_qs(urlparse(auth_url).query)
+
+        # Should redirect to consent page
+        assert "/consent" in auth_url
+        assert "txn_id" in query_params
+
+        # Transaction should have proxy's PKCE verifier (different from client's)
+        txn_id = query_params["txn_id"][0]
+        transaction = await proxy._transaction_store.get(key=txn_id)
+        assert transaction is not None
+        assert (
+            transaction.code_challenge == "client_challenge_value"
+        )  # Client's challenge
+        assert transaction.proxy_code_verifier is not None  # Proxy generated its own
+        # Proxy code challenge is computed from verifier when needed
+        assert len(transaction.proxy_code_verifier) > 0
diff --git a/tests/server/auth/oauth_proxy/test_oauth_proxy.py b/tests/server/auth/oauth_proxy/test_oauth_proxy.py
new file mode 100644
index 0000000..b221f3c
--- /dev/null
+++ b/tests/server/auth/oauth_proxy/test_oauth_proxy.py
@@ -0,0 +1,414 @@
+"""Tests for OAuth proxy initialization and configuration."""
+
+import time
+from urllib.parse import parse_qs, urlparse
+
+import httpx
+import pytest
+from authlib.integrations.httpx_client import AsyncOAuth2Client
+from key_value.aio.stores.memory import MemoryStore
+from starlette.applications import Starlette
+
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.server.auth.oauth_proxy.models import OAuthTransaction
+
+
+class TestOAuthProxyInitialization:
+    """Tests for OAuth proxy initialization and configuration."""
+
+    def test_basic_initialization(self, jwt_verifier):
+        """Test basic proxy initialization with required parameters."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="client-123",
+            upstream_client_secret="secret-456",
+            token_verifier=jwt_verifier,
+            base_url="https://api.example.com",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        assert (
+            proxy._upstream_authorization_endpoint
+            == "https://auth.example.com/authorize"
+        )
+        assert proxy._upstream_token_endpoint == "https://auth.example.com/token"
+        assert proxy._upstream_client_id == "client-123"
+        assert proxy._upstream_client_secret is not None
+        assert proxy._upstream_client_secret.get_secret_value() == "secret-456"
+        assert str(proxy.base_url) == "https://api.example.com/"
+
+    def test_all_optional_parameters(self, jwt_verifier):
+        """Test initialization with all optional parameters."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="client-123",
+            upstream_client_secret="secret-456",
+            upstream_revocation_endpoint="https://auth.example.com/revoke",
+            token_verifier=jwt_verifier,
+            base_url="https://api.example.com",
+            redirect_path="/custom/callback",
+            issuer_url="https://issuer.example.com",
+            service_documentation_url="https://docs.example.com",
+            allowed_client_redirect_uris=["http://localhost:*"],
+            valid_scopes=["custom", "scopes"],
+            forward_pkce=False,
+            token_endpoint_auth_method="client_secret_post",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        assert proxy._upstream_revocation_endpoint == "https://auth.example.com/revoke"
+        assert proxy._redirect_path == "/custom/callback"
+        assert proxy._forward_pkce is False
+        assert proxy._token_endpoint_auth_method == "client_secret_post"
+        assert proxy.client_registration_options is not None
+        assert proxy.client_registration_options.valid_scopes == ["custom", "scopes"]
+        assert proxy.client_registration_options.default_scopes == ["custom", "scopes"]
+
+    def test_default_scope_str_prefers_valid_scopes(self, jwt_verifier):
+        """When valid_scopes is provided, _default_scope_str should use it
+        instead of required_scopes. This ensures CIMD clients (which bypass
+        RegistrationHandler) get registered with the full set of valid scopes."""
+        jwt_verifier.required_scopes = ["openid"]
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="client-123",
+            upstream_client_secret="secret-456",
+            token_verifier=jwt_verifier,
+            base_url="https://api.example.com",
+            valid_scopes=["openid", "email", "calendar"],
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+        assert proxy._default_scope_str == "openid email calendar"
+
+    def test_default_scope_str_falls_back_to_required_scopes(self, jwt_verifier):
+        """Without valid_scopes, _default_scope_str falls back to required_scopes."""
+        jwt_verifier.required_scopes = ["openid"]
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="client-123",
+            upstream_client_secret="secret-456",
+            token_verifier=jwt_verifier,
+            base_url="https://api.example.com",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+        assert proxy._default_scope_str == "openid"
+
+    def test_update_default_scopes_updates_scope_str(self, jwt_verifier):
+        """update_default_scopes should update the internal default scope string."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="client-123",
+            upstream_client_secret="secret-456",
+            token_verifier=jwt_verifier,
+            base_url="https://api.example.com",
+            valid_scopes=["openid"],
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+        assert proxy._default_scope_str == "openid"
+
+        proxy.update_default_scopes(["openid", "email", "calendar"])
+        assert proxy._default_scope_str == "openid email calendar"
+
+    def test_update_default_scopes_updates_cimd_manager(self, jwt_verifier):
+        """update_default_scopes should update CIMD manager's default_scope."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="client-123",
+            upstream_client_secret="secret-456",
+            token_verifier=jwt_verifier,
+            base_url="https://api.example.com",
+            valid_scopes=["openid"],
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+            enable_cimd=True,
+        )
+        assert proxy._cimd_manager is not None
+        assert proxy._cimd_manager.default_scope == "openid"
+
+        proxy.update_default_scopes(["openid", "email", "drive"])
+        assert proxy._cimd_manager.default_scope == "openid email drive"
+
+    def test_update_default_scopes_updates_registration_options(self, jwt_verifier):
+        """update_default_scopes should update client registration scope options."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="client-123",
+            upstream_client_secret="secret-456",
+            token_verifier=jwt_verifier,
+            base_url="https://api.example.com",
+            valid_scopes=["openid"],
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+        assert proxy.client_registration_options is not None
+        assert proxy.client_registration_options.valid_scopes == ["openid"]
+        assert proxy.client_registration_options.default_scopes == ["openid"]
+
+        scopes = ["openid", "email", "calendar"]
+        proxy.update_default_scopes(scopes)
+        scopes.append("drive")
+
+        assert proxy.client_registration_options.valid_scopes == [
+            "openid",
+            "email",
+            "calendar",
+        ]
+        assert proxy.client_registration_options.default_scopes == [
+            "openid",
+            "email",
+            "calendar",
+        ]
+
+    def test_update_default_scopes_no_cimd_manager(self, jwt_verifier):
+        """update_default_scopes should work when CIMD is disabled (no manager)."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="client-123",
+            upstream_client_secret="secret-456",
+            token_verifier=jwt_verifier,
+            base_url="https://api.example.com",
+            valid_scopes=["openid"],
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+            enable_cimd=False,
+        )
+        assert proxy._cimd_manager is None
+
+        # Should not raise
+        proxy.update_default_scopes(["openid", "email"])
+        assert proxy._default_scope_str == "openid email"
+
+    def test_redirect_path_normalization(self, jwt_verifier):
+        """Test that redirect_path is normalized with leading slash."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.com/authorize",
+            upstream_token_endpoint="https://auth.com/token",
+            upstream_client_id="client",
+            upstream_client_secret="secret",
+            token_verifier=jwt_verifier,
+            base_url="https://api.com",
+            redirect_path="auth/callback",  # No leading slash
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+        assert proxy._redirect_path == "/auth/callback"
+
+    async def test_metadata_advertises_cimd_support(self, jwt_verifier):
+        """OAuth metadata should advertise CIMD and public-client auth support."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="client-123",
+            upstream_client_secret="secret-456",
+            token_verifier=jwt_verifier,
+            base_url="https://api.example.com",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+            enable_cimd=True,
+        )
+
+        app = Starlette(routes=proxy.get_routes())
+        transport = httpx.ASGITransport(app=app)
+
+        async with httpx.AsyncClient(
+            transport=transport, base_url="https://api.example.com"
+        ) as client:
+            response = await client.get("/.well-known/oauth-authorization-server")
+
+        assert response.status_code == 200
+        metadata = response.json()
+        assert metadata.get("client_id_metadata_document_supported") is True
+        assert set(metadata.get("token_endpoint_auth_methods_supported")) == {
+            "client_secret_post",
+            "client_secret_basic",
+            "private_key_jwt",
+            "none",
+        }
+
+
+class TestOptionalClientSecret:
+    """Tests for OAuthProxy without upstream_client_secret."""
+
+    def test_no_secret_requires_jwt_signing_key(self, jwt_verifier):
+        """OAuthProxy requires jwt_signing_key when client_secret is omitted."""
+        with pytest.raises(ValueError, match="jwt_signing_key is required"):
+            OAuthProxy(
+                upstream_authorization_endpoint="https://auth.example.com/authorize",
+                upstream_token_endpoint="https://auth.example.com/token",
+                upstream_client_id="client-123",
+                token_verifier=jwt_verifier,
+                base_url="https://api.example.com",
+                client_storage=MemoryStore(),
+            )
+
+    def test_no_secret_with_jwt_key_succeeds(self, jwt_verifier):
+        """OAuthProxy initializes successfully without client_secret when jwt_signing_key is given."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="client-123",
+            token_verifier=jwt_verifier,
+            base_url="https://api.example.com",
+            jwt_signing_key=b"a" * 32,
+            client_storage=MemoryStore(),
+        )
+        assert proxy._upstream_client_secret is None
+        assert proxy._upstream_client_id == "client-123"
+
+    def test_factory_method_without_secret(self, jwt_verifier):
+        """_create_upstream_oauth_client works when no secret is configured."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="client-123",
+            token_verifier=jwt_verifier,
+            base_url="https://api.example.com",
+            jwt_signing_key=b"a" * 32,
+            client_storage=MemoryStore(),
+        )
+        client = proxy._create_upstream_oauth_client()
+        assert isinstance(client, AsyncOAuth2Client)
+        assert client.client_id == "client-123"
+
+    def test_factory_method_with_secret(self, jwt_verifier):
+        """_create_upstream_oauth_client includes the secret when configured."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="client-123",
+            upstream_client_secret="secret-456",
+            token_verifier=jwt_verifier,
+            base_url="https://api.example.com",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+        client = proxy._create_upstream_oauth_client()
+        assert isinstance(client, AsyncOAuth2Client)
+        assert client.client_secret == "secret-456"
+
+    def test_consent_cookies_work_without_secret(self, jwt_verifier):
+        """Cookie signing/verification works using JWT key when no secret is configured."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="client-123",
+            token_verifier=jwt_verifier,
+            base_url="https://api.example.com",
+            jwt_signing_key=b"a" * 32,
+            client_storage=MemoryStore(),
+        )
+        signed = proxy._sign_cookie("test-payload")
+        assert proxy._verify_cookie(signed) == "test-payload"
+        assert proxy._verify_cookie("tampered.payload") is None
+
+
+class TestIdpCallbackErrorForwarding:
+    """Tests for error forwarding in the IdP callback."""
+
+    async def test_error_with_valid_transaction_redirects_to_client(self, oauth_proxy):
+        """When the IdP returns an error and the transaction exists, the proxy
+        must forward the error to the client's redirect_uri rather than showing
+        an HTML error page."""
+        txn_id = "test-txn-123"
+        client_redirect_uri = "http://localhost:12345/callback"
+        client_state = "client-state-abc"
+
+        transaction = OAuthTransaction(
+            txn_id=txn_id,
+            client_id="test-client",
+            client_redirect_uri=client_redirect_uri,
+            client_state=client_state,
+            code_challenge=None,
+            code_challenge_method="S256",
+            scopes=["read"],
+            created_at=time.time(),
+        )
+        await oauth_proxy._transaction_store.put(key=txn_id, value=transaction)
+
+        app = Starlette(routes=oauth_proxy.get_routes())
+        transport = httpx.ASGITransport(app=app)
+
+        async with httpx.AsyncClient(
+            transport=transport,
+            base_url="https://myserver.com",
+            follow_redirects=False,
+        ) as client:
+            response = await client.get(
+                f"/auth/callback?error=access_denied&error_description=User+denied+access&state={txn_id}"
+            )
+
+        assert response.status_code == 302
+        location = response.headers["location"]
+        parsed = urlparse(location)
+        assert (
+            parsed.scheme + "://" + parsed.netloc + parsed.path == client_redirect_uri
+        )
+        params = parse_qs(parsed.query)
+        assert params["error"] == ["access_denied"]
+        assert params["error_description"] == ["User denied access"]
+        assert params["state"] == [client_state]
+
+    async def test_error_with_unsafe_transaction_redirect_returns_html_error(
+        self, oauth_proxy
+    ):
+        """IdP errors must not redirect to unsafe stored callback URIs."""
+        txn_id = "test-txn-unsafe"
+
+        transaction = OAuthTransaction(
+            txn_id=txn_id,
+            client_id="test-client",
+            client_redirect_uri="javascript:alert(document.cookie)//",
+            client_state="client-state-abc",
+            code_challenge=None,
+            code_challenge_method="S256",
+            scopes=["read"],
+            created_at=time.time(),
+        )
+        await oauth_proxy._transaction_store.put(key=txn_id, value=transaction)
+
+        app = Starlette(routes=oauth_proxy.get_routes())
+        transport = httpx.ASGITransport(app=app)
+
+        async with httpx.AsyncClient(
+            transport=transport,
+            base_url="https://myserver.com",
+            follow_redirects=False,
+        ) as client:
+            response = await client.get(
+                f"/auth/callback?error=access_denied&state={txn_id}"
+            )
+
+        assert response.status_code == 400
+        assert "location" not in response.headers
+        assert "Invalid redirect URI" in response.text
+
+    async def test_error_with_missing_transaction_returns_html_error(self, oauth_proxy):
+        """When the IdP returns an error but the transaction is missing or
+        expired, the proxy must return a local HTML error page — there is no
+        trusted client redirect_uri to forward to."""
+        app = Starlette(routes=oauth_proxy.get_routes())
+        transport = httpx.ASGITransport(app=app)
+
+        async with httpx.AsyncClient(
+            transport=transport,
+            base_url="https://myserver.com",
+            follow_redirects=False,
+        ) as client:
+            response = await client.get(
+                "/auth/callback?error=access_denied&state=nonexistent-txn"
+            )
+
+        assert response.status_code == 400
diff --git a/tests/server/auth/oauth_proxy/test_tokens.py b/tests/server/auth/oauth_proxy/test_tokens.py
new file mode 100644
index 0000000..0ecb42a
--- /dev/null
+++ b/tests/server/auth/oauth_proxy/test_tokens.py
@@ -0,0 +1,1958 @@
+"""Tests for OAuth proxy token endpoint and handling."""
+
+import logging
+import time
+from unittest.mock import AsyncMock, Mock, patch
+
+import pytest
+from key_value.aio.stores.memory import MemoryStore
+from mcp.server.auth.handlers.token import TokenErrorResponse
+from mcp.server.auth.handlers.token import TokenHandler as SDKTokenHandler
+from mcp.server.auth.provider import AuthorizationCode
+from mcp.shared.auth import OAuthClientInformationFull
+from pydantic import AnyUrl
+
+from fastmcp.server.auth.auth import (
+    AccessToken,
+    RefreshToken,
+    TokenHandler,
+    TokenVerifier,
+)
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.server.auth.oauth_proxy.models import (
+    DEFAULT_ACCESS_TOKEN_EXPIRY_NO_REFRESH_SECONDS,
+    DEFAULT_ACCESS_TOKEN_EXPIRY_SECONDS,
+    DEFAULT_REFRESH_TOKEN_EXPIRY_SECONDS,
+    ClientCode,
+    JTIMapping,
+    OAuthTransaction,
+    RefreshTokenMetadata,
+    UpstreamTokenSet,
+    _hash_token,
+)
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+
+class TestOAuthProxyTokenEndpointAuth:
+    """Tests for token endpoint authentication methods."""
+
+    def test_token_auth_method_initialization(self, jwt_verifier):
+        """Test different token endpoint auth methods."""
+        # client_secret_post
+        proxy_post = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="client",
+            upstream_client_secret="secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            token_endpoint_auth_method="client_secret_post",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+        assert proxy_post._token_endpoint_auth_method == "client_secret_post"
+
+        # client_secret_basic (default)
+        proxy_basic = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="client",
+            upstream_client_secret="secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            token_endpoint_auth_method="client_secret_basic",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+        assert proxy_basic._token_endpoint_auth_method == "client_secret_basic"
+
+        # None (use authlib default)
+        proxy_default = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="client",
+            upstream_client_secret="secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+        assert proxy_default._token_endpoint_auth_method is None
+
+    async def test_token_auth_method_passed_to_client(self, jwt_verifier):
+        """Test that auth method is passed to AsyncOAuth2Client."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="client-id",
+            upstream_client_secret="client-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            token_endpoint_auth_method="client_secret_post",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        # Initialize JWT issuer before token operations
+        proxy.set_mcp_path("/mcp")
+
+        # First, create a valid FastMCP token via full OAuth flow
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        # Mock the upstream OAuth provider response
+        with patch(
+            "fastmcp.server.auth.oauth_proxy.proxy.AsyncOAuth2Client"
+        ) as MockClient:
+            mock_client = AsyncMock()
+
+            # Mock initial token exchange (authorization code flow)
+            mock_client.fetch_token = AsyncMock(
+                return_value={
+                    "access_token": "upstream-access-token",
+                    "refresh_token": "upstream-refresh-token",
+                    "expires_in": 3600,
+                    "token_type": "Bearer",
+                }
+            )
+
+            # Mock token refresh
+            mock_client.refresh_token = AsyncMock(
+                return_value={
+                    "access_token": "new-upstream-token",
+                    "refresh_token": "new-upstream-refresh",
+                    "expires_in": 3600,
+                    "token_type": "Bearer",
+                }
+            )
+            MockClient.return_value = mock_client
+
+            # Register client and do initial OAuth flow to get valid FastMCP tokens
+            await proxy.register_client(client)
+
+            # Store client code that would be created during OAuth callback
+            client_code = ClientCode(
+                code="test-auth-code",
+                client_id="test-client",
+                redirect_uri="http://localhost:12345/callback",
+                code_challenge="",
+                code_challenge_method="S256",
+                scopes=["read"],
+                idp_tokens={
+                    "access_token": "upstream-access-token",
+                    "refresh_token": "upstream-refresh-token",
+                    "expires_in": 3600,
+                    "token_type": "Bearer",
+                },
+                expires_at=time.time() + 300,
+                created_at=time.time(),
+            )
+            await proxy._code_store.put(key=client_code.code, value=client_code)
+
+            # Exchange authorization code to get FastMCP tokens
+            auth_code = AuthorizationCode(
+                code="test-auth-code",
+                scopes=["read"],
+                expires_at=time.time() + 300,
+                client_id="test-client",
+                code_challenge="",
+                redirect_uri=AnyUrl("http://localhost:12345/callback"),
+                redirect_uri_provided_explicitly=True,
+            )
+            result = await proxy.exchange_authorization_code(
+                client=client,
+                authorization_code=auth_code,
+            )
+
+            # Now test refresh with the valid FastMCP refresh token
+            assert result.refresh_token is not None
+            fastmcp_refresh = RefreshToken(
+                token=result.refresh_token,
+                client_id="test-client",
+                scopes=["read"],
+                expires_at=None,
+            )
+
+            # Reset mock to check refresh call
+            MockClient.reset_mock()
+            mock_client.refresh_token = AsyncMock(
+                return_value={
+                    "access_token": "new-upstream-token-2",
+                    "refresh_token": "new-upstream-refresh-2",
+                    "expires_in": 3600,
+                    "token_type": "Bearer",
+                }
+            )
+            MockClient.return_value = mock_client
+
+            await proxy.exchange_refresh_token(client, fastmcp_refresh, ["read"])
+
+            # Verify auth method was passed to OAuth client
+            MockClient.assert_called_with(
+                client_id="client-id",
+                client_secret="client-secret",
+                token_endpoint_auth_method="client_secret_post",
+                timeout=30.0,
+            )
+            mock_client.aclose.assert_awaited_once()
+
+    async def test_callback_closes_upstream_oauth_client(self, jwt_verifier):
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="client-id",
+            upstream_client_secret="client-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            require_authorization_consent=False,
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        await proxy._transaction_store.put(
+            key="txn-id",
+            value=OAuthTransaction(
+                txn_id="txn-id",
+                client_id="test-client",
+                client_redirect_uri="http://localhost:12345/callback",
+                client_state="client-state",
+                code_challenge="",
+                code_challenge_method="S256",
+                scopes=["read"],
+                created_at=time.time(),
+            ),
+        )
+
+        mock_request = Mock()
+        mock_request.query_params = {"code": "idp-code", "state": "txn-id"}
+        mock_request.cookies = {}
+
+        mock_client = AsyncMock()
+        mock_client.fetch_token = AsyncMock(
+            return_value={
+                "access_token": "upstream-access-token",
+                "refresh_token": "upstream-refresh-token",
+                "expires_in": 3600,
+                "token_type": "Bearer",
+            }
+        )
+
+        with patch.object(
+            proxy, "_create_upstream_oauth_client", return_value=mock_client
+        ):
+            response = await proxy._handle_idp_callback(mock_request)
+
+        assert response.status_code == 302
+        mock_client.fetch_token.assert_awaited_once()
+        mock_client.aclose.assert_awaited_once()
+
+    async def test_callback_rejects_unsafe_transaction_redirect(self, jwt_verifier):
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="client-id",
+            upstream_client_secret="client-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            require_authorization_consent=False,
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        await proxy._transaction_store.put(
+            key="txn-id",
+            value=OAuthTransaction(
+                txn_id="txn-id",
+                client_id="test-client",
+                client_redirect_uri="javascript:alert(document.cookie)//",
+                client_state="client-state",
+                code_challenge="",
+                code_challenge_method="S256",
+                scopes=["read"],
+                created_at=time.time(),
+            ),
+        )
+
+        mock_request = Mock()
+        mock_request.query_params = {"code": "idp-code", "state": "txn-id"}
+        mock_request.cookies = {}
+
+        mock_client = AsyncMock()
+        mock_client.fetch_token = AsyncMock()
+
+        with patch.object(
+            proxy, "_create_upstream_oauth_client", return_value=mock_client
+        ) as create_upstream_oauth_client:
+            response = await proxy._handle_idp_callback(mock_request)
+
+        assert response.status_code == 400
+        assert "location" not in response.headers
+        assert "Invalid redirect URI" in bytes(response.body).decode()
+        create_upstream_oauth_client.assert_not_called()
+        mock_client.fetch_token.assert_not_called()
+
+
+class TestTokenHandlerErrorTransformation:
+    """Tests for TokenHandler's OAuth 2.1 compliant error transformation."""
+
+    async def test_transforms_client_auth_failure_to_invalid_client_401(self):
+        """Test that client authentication failures return invalid_client with 401."""
+        handler = TokenHandler(provider=Mock(), client_authenticator=Mock())
+
+        # Create a mock 401 response like the SDK returns for auth failures
+        mock_response = Mock()
+        mock_response.status_code = 401
+        mock_response.body = (
+            b'{"error":"unauthorized_client","error_description":"Invalid client_id"}'
+        )
+
+        # Patch the parent class's handle() to return our mock response
+        with patch.object(
+            SDKTokenHandler,
+            "handle",
+            new_callable=AsyncMock,
+            return_value=mock_response,
+        ):
+            response = await handler.handle(Mock())
+
+        # Should transform to OAuth 2.1 compliant response
+        assert response.status_code == 401
+        assert b'"error":"invalid_client"' in response.body
+        assert b'"error_description":"Invalid client_id"' in response.body
+
+    def test_does_not_transform_grant_type_unauthorized_to_invalid_client(self):
+        """Test that grant type authorization errors stay as unauthorized_client with 400."""
+        handler = TokenHandler(provider=Mock(), client_authenticator=Mock())
+
+        # Simulate error from grant_type not in client_info.grant_types
+        error_response = TokenErrorResponse(
+            error="unauthorized_client",
+            error_description="Client not authorized for this grant type",
+        )
+
+        response = handler.response(error_response)
+
+        # Should NOT transform - keep as 400 unauthorized_client
+        assert response.status_code == 400
+        assert b'"error":"unauthorized_client"' in response.body
+
+    async def test_transforms_invalid_grant_to_401(self):
+        """Test that invalid_grant errors return 401 per MCP spec.
+
+        Per MCP spec: "Invalid or expired tokens MUST receive a HTTP 401 response."
+        The SDK incorrectly returns 400 for all TokenErrorResponse including invalid_grant.
+        """
+        handler = TokenHandler(provider=Mock(), client_authenticator=Mock())
+
+        # Create a mock 400 response like the SDK returns for invalid_grant
+        mock_response = Mock()
+        mock_response.status_code = 400
+        mock_response.body = (
+            b'{"error":"invalid_grant","error_description":"refresh token has expired"}'
+        )
+
+        # Patch the parent class's handle() to return our mock response
+        with patch.object(
+            SDKTokenHandler,
+            "handle",
+            new_callable=AsyncMock,
+            return_value=mock_response,
+        ):
+            response = await handler.handle(Mock())
+
+        # Should transform to MCP-compliant 401 response
+        assert response.status_code == 401
+        assert b'"error":"invalid_grant"' in response.body
+        assert b'"error_description":"refresh token has expired"' in response.body
+
+    def test_does_not_transform_other_400_errors(self):
+        """Test that non-invalid_grant 400 errors pass through unchanged."""
+        handler = TokenHandler(provider=Mock(), client_authenticator=Mock())
+
+        # Test with invalid_request error (should stay 400)
+        error_response = TokenErrorResponse(
+            error="invalid_request",
+            error_description="Missing required parameter",
+        )
+
+        response = handler.response(error_response)
+
+        # Should pass through unchanged as 400
+        assert response.status_code == 400
+        assert b'"error":"invalid_request"' in response.body
+
+
+class TestFallbackAccessTokenExpiry:
+    """Test fallback access token expiry constants and configuration."""
+
+    def test_default_constants(self):
+        """Verify the default expiry constants are set correctly."""
+        assert DEFAULT_ACCESS_TOKEN_EXPIRY_SECONDS == 60 * 60  # 1 hour
+        assert (
+            DEFAULT_ACCESS_TOKEN_EXPIRY_NO_REFRESH_SECONDS == 60 * 60 * 24 * 365
+        )  # 1 year
+
+    def test_fallback_parameter_stored(self):
+        """Verify fallback_access_token_expiry_seconds is stored on provider."""
+        provider = OAuthProxy(
+            upstream_authorization_endpoint="https://idp.example.com/authorize",
+            upstream_token_endpoint="https://idp.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=JWTVerifier(
+                jwks_uri="https://idp.example.com/.well-known/jwks.json",
+                issuer="https://idp.example.com",
+            ),
+            base_url="http://localhost:8000",
+            jwt_signing_key="test-signing-key",
+            fallback_access_token_expiry_seconds=86400,
+            client_storage=MemoryStore(),
+        )
+
+        assert provider._fallback_access_token_expiry_seconds == 86400
+
+    def test_fallback_parameter_defaults_to_none(self):
+        """Verify fallback defaults to None (enabling smart defaults)."""
+        provider = OAuthProxy(
+            upstream_authorization_endpoint="https://idp.example.com/authorize",
+            upstream_token_endpoint="https://idp.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=JWTVerifier(
+                jwks_uri="https://idp.example.com/.well-known/jwks.json",
+                issuer="https://idp.example.com",
+            ),
+            base_url="http://localhost:8000",
+            jwt_signing_key="test-signing-key",
+            client_storage=MemoryStore(),
+        )
+
+        assert provider._fallback_access_token_expiry_seconds is None
+
+
+class TestFallbackRefreshTokenExpiry:
+    """Tests for fallback_refresh_token_expiry_seconds (issue #3987).
+
+    When upstream omits `refresh_expires_in`, the FastMCP refresh JWT and the
+    JTI mapping must use the configured fallback (default 1 year), not a
+    hardcoded 30-day value. The FastMCP refresh JWT is a signed pointer; the
+    real upstream refresh remains the source of truth.
+    """
+
+    @pytest.fixture
+    def jwt_verifier(self):
+        verifier = Mock(spec=TokenVerifier)
+        verifier.required_scopes = ["read", "write"]
+        verifier.verify_token = AsyncMock(return_value=None)
+        return verifier
+
+    def test_default_constant(self):
+        assert DEFAULT_REFRESH_TOKEN_EXPIRY_SECONDS == 60 * 60 * 24 * 365  # 1 year
+
+    def test_fallback_defaults_to_one_year(self, jwt_verifier):
+        provider = OAuthProxy(
+            upstream_authorization_endpoint="https://idp.example.com/authorize",
+            upstream_token_endpoint="https://idp.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=jwt_verifier,
+            base_url="http://localhost:8000",
+            jwt_signing_key="test-signing-key",
+            client_storage=MemoryStore(),
+        )
+        assert (
+            provider._fallback_refresh_token_expiry_seconds
+            == DEFAULT_REFRESH_TOKEN_EXPIRY_SECONDS
+        )
+
+    def test_fallback_parameter_stored(self, jwt_verifier):
+        provider = OAuthProxy(
+            upstream_authorization_endpoint="https://idp.example.com/authorize",
+            upstream_token_endpoint="https://idp.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=jwt_verifier,
+            base_url="http://localhost:8000",
+            jwt_signing_key="test-signing-key",
+            fallback_refresh_token_expiry_seconds=7 * 24 * 60 * 60,  # 7 days
+            client_storage=MemoryStore(),
+        )
+        assert provider._fallback_refresh_token_expiry_seconds == 7 * 24 * 60 * 60
+
+    async def test_initial_exchange_jti_mapping_aligned_with_refresh_expiry(
+        self, jwt_verifier
+    ):
+        """Bug 1: JTI mapping TTL must align with refresh_expires_in.
+
+        Previously hardcoded to 30 days, which silently expired the mapping
+        early when upstream returned a longer refresh lifetime.
+        """
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://idp.example.com/authorize",
+            upstream_token_endpoint="https://idp.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret-key",
+            client_storage=MemoryStore(),
+        )
+        proxy.set_mcp_path("/mcp")
+
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+        await proxy.register_client(client)
+
+        # Upstream returns 1-year refresh expiry — well past the old 30d default
+        one_year = 60 * 60 * 24 * 365
+        client_code = ClientCode(
+            code="long-refresh-code",
+            client_id="test-client",
+            redirect_uri="http://localhost:12345/callback",
+            code_challenge="test-challenge",
+            code_challenge_method="S256",
+            scopes=["read", "write"],
+            idp_tokens={
+                "access_token": "upstream-access",
+                "refresh_token": "upstream-refresh",
+                "expires_in": 3600,
+                "refresh_expires_in": one_year,
+                "token_type": "Bearer",
+            },
+            expires_at=time.time() + 300,
+            created_at=time.time(),
+        )
+        await proxy._code_store.put(key=client_code.code, value=client_code)
+
+        result = await proxy.exchange_authorization_code(
+            client=client,
+            authorization_code=AuthorizationCode(
+                code="long-refresh-code",
+                scopes=["read", "write"],
+                expires_at=time.time() + 300,
+                client_id="test-client",
+                code_challenge="test-challenge",
+                redirect_uri=AnyUrl("http://localhost:12345/callback"),
+                redirect_uri_provided_explicitly=True,
+            ),
+        )
+        assert result.refresh_token is not None
+
+        # The refresh JWT exp claim should reflect the 1-year upstream lifetime
+        refresh_payload = proxy.jwt_issuer.verify_token(
+            result.refresh_token, expected_token_use="refresh"
+        )
+        # exp - iat should be approximately one_year (allow small clock skew)
+        assert refresh_payload["exp"] - refresh_payload["iat"] == pytest.approx(
+            one_year, abs=5
+        )
+
+    async def test_initial_exchange_uses_fallback_when_upstream_silent(
+        self, jwt_verifier
+    ):
+        """When upstream omits refresh_expires_in, fall back to configured value.
+
+        Default is 1 year (was previously 30 days, ignoring user config).
+        """
+        custom_fallback = 60 * 60 * 24 * 90  # 90 days
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://idp.example.com/authorize",
+            upstream_token_endpoint="https://idp.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret-key",
+            fallback_refresh_token_expiry_seconds=custom_fallback,
+            client_storage=MemoryStore(),
+        )
+        proxy.set_mcp_path("/mcp")
+
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+        await proxy.register_client(client)
+
+        client_code = ClientCode(
+            code="silent-refresh-code",
+            client_id="test-client",
+            redirect_uri="http://localhost:12345/callback",
+            code_challenge="test-challenge",
+            code_challenge_method="S256",
+            scopes=["read", "write"],
+            idp_tokens={
+                "access_token": "upstream-access",
+                "refresh_token": "upstream-refresh",
+                "expires_in": 3600,
+                # no refresh_expires_in — upstream is silent
+                "token_type": "Bearer",
+            },
+            expires_at=time.time() + 300,
+            created_at=time.time(),
+        )
+        await proxy._code_store.put(key=client_code.code, value=client_code)
+
+        result = await proxy.exchange_authorization_code(
+            client=client,
+            authorization_code=AuthorizationCode(
+                code="silent-refresh-code",
+                scopes=["read", "write"],
+                expires_at=time.time() + 300,
+                client_id="test-client",
+                code_challenge="test-challenge",
+                redirect_uri=AnyUrl("http://localhost:12345/callback"),
+                redirect_uri_provided_explicitly=True,
+            ),
+        )
+        assert result.refresh_token is not None
+
+        refresh_payload = proxy.jwt_issuer.verify_token(
+            result.refresh_token, expected_token_use="refresh"
+        )
+        assert refresh_payload["exp"] - refresh_payload["iat"] == pytest.approx(
+            custom_fallback, abs=5
+        )
+
+    async def test_refresh_jwt_exp_aligned_when_upstream_omits_refresh_token(
+        self, jwt_verifier
+    ):
+        """Bug 2: JWT exp must align with storage TTL when upstream omits refresh_token.
+
+        Cognito does NOT return a refresh_token on refresh. Previously the new
+        FastMCP refresh JWT was issued with hardcoded 30-day exp, while the
+        storage TTL correctly used the existing upstream refresh lifetime —
+        forcing re-login at day 30 even when the upstream refresh was valid
+        for much longer.
+        """
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://idp.example.com/authorize",
+            upstream_token_endpoint="https://idp.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret-key",
+            client_storage=MemoryStore(),
+        )
+        proxy.set_mcp_path("/mcp")
+
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+        await proxy.register_client(client)
+
+        # Seed an upstream session whose refresh token has 6 months left
+        now = time.time()
+        upstream_refresh_expires_at = now + (60 * 60 * 24 * 180)
+        upstream_token_id = "upstream-id-cognito"
+        upstream_token_set = UpstreamTokenSet(
+            upstream_token_id=upstream_token_id,
+            access_token="upstream-access-old",
+            refresh_token="upstream-refresh-tok",
+            refresh_token_expires_at=upstream_refresh_expires_at,
+            expires_at=now + 60,  # access nearly expired (irrelevant here)
+            token_type="Bearer",
+            scope="read write",
+            client_id="test-client",
+            created_at=now,
+            raw_token_data={},
+        )
+        await proxy._upstream_token_store.put(
+            key=upstream_token_id,
+            value=upstream_token_set,
+            ttl=int(upstream_refresh_expires_at - now),
+        )
+
+        # Issue a FastMCP refresh JWT pointing at this session
+        old_refresh_jti = "old-refresh-jti"
+        old_refresh_jwt = proxy.jwt_issuer.issue_refresh_token(
+            client_id="test-client",
+            scopes=["read", "write"],
+            jti=old_refresh_jti,
+            expires_in=int(upstream_refresh_expires_at - now),
+        )
+        await proxy._jti_mapping_store.put(
+            key=old_refresh_jti,
+            value=JTIMapping(
+                jti=old_refresh_jti,
+                upstream_token_id=upstream_token_id,
+                created_at=now,
+            ),
+            ttl=int(upstream_refresh_expires_at - now),
+        )
+        await proxy._refresh_token_store.put(
+            key=_hash_token(old_refresh_jwt),
+            value=RefreshTokenMetadata(
+                client_id="test-client",
+                scopes=["read", "write"],
+                expires_at=int(upstream_refresh_expires_at),
+                created_at=now,
+            ),
+            ttl=int(upstream_refresh_expires_at - now),
+        )
+
+        # Mock the upstream refresh response — Cognito-style: NO refresh_token
+        async def fake_refresh(url, refresh_token, scope=None, **kwargs):
+            return {
+                "access_token": "upstream-access-new",
+                "expires_in": 3600,
+                "token_type": "Bearer",
+                # NO refresh_token, NO refresh_expires_in
+            }
+
+        oauth_client_mock = Mock()
+        oauth_client_mock.refresh_token = AsyncMock(side_effect=fake_refresh)
+        oauth_client_mock.aclose = AsyncMock()
+        with patch.object(
+            proxy,
+            "_create_upstream_oauth_client",
+            return_value=oauth_client_mock,
+        ):
+            new_token = await proxy.exchange_refresh_token(
+                client=client,
+                refresh_token=RefreshToken(
+                    token=old_refresh_jwt,
+                    client_id="test-client",
+                    scopes=["read", "write"],
+                    expires_at=int(upstream_refresh_expires_at),
+                ),
+                scopes=["read", "write"],
+            )
+
+        assert new_token.refresh_token is not None
+        # New refresh JWT exp must reflect remaining upstream refresh lifetime
+        # (~6 months), not a hardcoded 30 days
+        new_refresh_payload = proxy.jwt_issuer.verify_token(
+            new_token.refresh_token, expected_token_use="refresh"
+        )
+        ttl_remaining = new_refresh_payload["exp"] - new_refresh_payload["iat"]
+        # Should be close to 180 days, well above the old 30-day cliff
+        assert ttl_remaining > 60 * 60 * 24 * 90  # at least 90 days
+
+
+class TestFastMCPAccessTokenExpiry:
+    """Tests for fastmcp_access_token_expiry_seconds (issue #4252).
+
+    The FastMCP-issued access token is a reference into FastMCP storage; its
+    lifetime can be decoupled from the upstream provider's short `expires_in`
+    so MCP clients that don't refresh gracefully (e.g. mcp-remote) aren't forced
+    through a full re-auth on every idle period. The upstream token's real expiry
+    is preserved internally to drive transparent refresh.
+    """
+
+    @pytest.fixture
+    def jwt_verifier(self):
+        verifier = Mock(spec=TokenVerifier)
+        verifier.required_scopes = ["read", "write"]
+        verifier.verify_token = AsyncMock(return_value=None)
+        return verifier
+
+    def _make_proxy(self, jwt_verifier, **kwargs):
+        return OAuthProxy(
+            upstream_authorization_endpoint="https://idp.example.com/authorize",
+            upstream_token_endpoint="https://idp.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret-key",
+            client_storage=MemoryStore(),
+            **kwargs,
+        )
+
+    def test_parameter_stored(self, jwt_verifier):
+        proxy = self._make_proxy(
+            jwt_verifier, fastmcp_access_token_expiry_seconds=86400
+        )
+        assert proxy._fastmcp_access_token_expiry_seconds == 86400
+
+    def test_parameter_defaults_to_none(self, jwt_verifier):
+        proxy = self._make_proxy(jwt_verifier)
+        assert proxy._fastmcp_access_token_expiry_seconds is None
+
+    async def _exchange(self, proxy, code="test-code", **idp_token_overrides):
+        proxy.set_mcp_path("/mcp")
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+        await proxy.register_client(client)
+
+        idp_tokens = {
+            "access_token": "upstream-access",
+            "refresh_token": "upstream-refresh",
+            "expires_in": 3600,
+            "token_type": "Bearer",
+            **idp_token_overrides,
+        }
+        # Allow callers to drop a default key by overriding it with None
+        # (e.g. refresh_token=None to simulate a provider that issues none).
+        idp_tokens = {k: v for k, v in idp_tokens.items() if v is not None}
+        client_code = ClientCode(
+            code=code,
+            client_id="test-client",
+            redirect_uri="http://localhost:12345/callback",
+            code_challenge="test-challenge",
+            code_challenge_method="S256",
+            scopes=["read", "write"],
+            idp_tokens=idp_tokens,
+            expires_at=time.time() + 300,
+            created_at=time.time(),
+        )
+        await proxy._code_store.put(key=client_code.code, value=client_code)
+
+        return client, await proxy.exchange_authorization_code(
+            client=client,
+            authorization_code=AuthorizationCode(
+                code=code,
+                scopes=["read", "write"],
+                expires_at=time.time() + 300,
+                client_id="test-client",
+                code_challenge="test-challenge",
+                redirect_uri=AnyUrl("http://localhost:12345/callback"),
+                redirect_uri_provided_explicitly=True,
+            ),
+        )
+
+    async def test_initial_exchange_decouples_access_token_from_upstream(
+        self, jwt_verifier
+    ):
+        """A long FastMCP TTL applies even though upstream returns expires_in=3600."""
+        one_day = 60 * 60 * 24
+        proxy = self._make_proxy(
+            jwt_verifier, fastmcp_access_token_expiry_seconds=one_day
+        )
+
+        _, result = await self._exchange(proxy)
+
+        # Response and JWT exp reflect the configured FastMCP lifetime, not 3600
+        assert result.expires_in == one_day
+        access_payload = proxy.jwt_issuer.verify_token(result.access_token)
+        assert access_payload["exp"] - access_payload["iat"] == pytest.approx(
+            one_day, abs=5
+        )
+
+    async def test_upstream_token_expiry_preserved_for_transparent_refresh(
+        self, jwt_verifier
+    ):
+        """Decoupling must not corrupt the upstream token's real expiry.
+
+        The stored upstream token still expires at ~upstream expires_in so that
+        transparent refresh fires; only the FastMCP-issued token lives longer.
+        """
+        one_day = 60 * 60 * 24
+        proxy = self._make_proxy(
+            jwt_verifier, fastmcp_access_token_expiry_seconds=one_day
+        )
+
+        _, result = await self._exchange(proxy)
+
+        access_jti = proxy.jwt_issuer.verify_token(result.access_token)["jti"]
+        jti_mapping = await proxy._jti_mapping_store.get(key=access_jti)
+        assert jti_mapping is not None
+        stored = await proxy._upstream_token_store.get(
+            key=jti_mapping.upstream_token_id
+        )
+        assert stored is not None
+        # Upstream access token expiry tracks the upstream lifetime (~3600s),
+        # NOT the 1-day FastMCP token lifetime.
+        assert stored.expires_at - time.time() == pytest.approx(3600, abs=30)
+
+    async def test_access_jti_mapping_ttl_matches_configured_lifetime(
+        self, jwt_verifier
+    ):
+        """The access JTI mapping must outlive the upstream access token.
+
+        The JWT exp and the JTI mapping TTL are set from the same value, so a
+        drift between them would let the JWT verify while its storage lookup has
+        already expired — silently breaking long-idle sessions. Guard the TTL
+        passed to storage directly, since wall-clock expiry can't be exercised
+        in a fast unit test.
+        """
+        one_week = 60 * 60 * 24 * 7
+        proxy = self._make_proxy(
+            jwt_verifier, fastmcp_access_token_expiry_seconds=one_week
+        )
+
+        original_put = proxy._jti_mapping_store.put
+        calls: list[dict] = []
+
+        async def spy(**kwargs):
+            calls.append(kwargs)
+            return await original_put(**kwargs)
+
+        with patch.object(proxy._jti_mapping_store, "put", side_effect=spy):
+            _, result = await self._exchange(proxy)
+
+        access_jti = proxy.jwt_issuer.verify_token(result.access_token)["jti"]
+        access_call = next(c for c in calls if c["value"].jti == access_jti)
+        assert access_call["ttl"] == one_week
+
+    @pytest.mark.parametrize(
+        "configured, expected",
+        [
+            (60 * 60 * 24 * 7, 3600),  # configured > upstream -> capped at upstream
+            (600, 600),  # configured < upstream -> honored (still <= upstream)
+        ],
+    )
+    async def test_no_refresh_token_does_not_extend_past_upstream(
+        self, jwt_verifier, configured, expected
+    ):
+        """Without an upstream refresh token, the FastMCP token can't be renewed.
+
+        Issuing a token that claims to outlive the upstream access token would be
+        a lie — there's no way to transparently refresh it — so the lifetime is
+        capped at the upstream `expires_in` when no refresh token is present.
+        """
+        proxy = self._make_proxy(
+            jwt_verifier, fastmcp_access_token_expiry_seconds=configured
+        )
+
+        _, result = await self._exchange(proxy, refresh_token=None)
+
+        assert result.expires_in == expected
+        access_payload = proxy.jwt_issuer.verify_token(result.access_token)
+        assert access_payload["exp"] - access_payload["iat"] == pytest.approx(
+            expected, abs=5
+        )
+
+    async def test_extended_token_survives_upstream_expiry_via_refresh(self):
+        """End-to-end: a long-lived FastMCP token keeps working after the upstream
+        access token expires, by transparently refreshing underneath.
+
+        Proves the pieces integrate: the long-exp JWT still verifies, its JTI
+        mapping still resolves, and an expired upstream token triggers transparent
+        refresh rather than a 401.
+        """
+        one_week = 60 * 60 * 24 * 7
+
+        verifier = Mock(spec=TokenVerifier)
+        verifier.required_scopes = ["read", "write"]
+
+        async def verify(token: str) -> AccessToken | None:
+            if token.startswith("refreshed-"):
+                return AccessToken(
+                    token=token,
+                    client_id="test-client",
+                    scopes=["read", "write"],
+                    expires_at=int(time.time() + 3600),
+                )
+            return None  # original upstream token is treated as invalid/expired
+
+        verifier.verify_token = AsyncMock(side_effect=verify)
+        proxy = self._make_proxy(verifier, fastmcp_access_token_expiry_seconds=one_week)
+
+        _, result = await self._exchange(proxy)
+
+        # Force the stored upstream access token to be expired.
+        access_jti = proxy.jwt_issuer.verify_token(result.access_token)["jti"]
+        jti_mapping = await proxy._jti_mapping_store.get(key=access_jti)
+        assert jti_mapping is not None
+        stored = await proxy._upstream_token_store.get(
+            key=jti_mapping.upstream_token_id
+        )
+        assert stored is not None
+        stored.expires_at = time.time() - 60
+        await proxy._upstream_token_store.put(
+            key=jti_mapping.upstream_token_id, value=stored, ttl=one_week
+        )
+
+        mock_oauth_client = AsyncMock()
+        mock_oauth_client.refresh_token = AsyncMock(
+            return_value={
+                "access_token": "refreshed-upstream-access",
+                "token_type": "Bearer",
+                "expires_in": 3600,
+                "refresh_token": "upstream-refresh",
+                "scope": "read write",
+            }
+        )
+
+        with patch.object(
+            proxy, "_create_upstream_oauth_client", return_value=mock_oauth_client
+        ):
+            loaded = await proxy.load_access_token(result.access_token)
+
+        assert loaded is not None
+        assert loaded.token == "refreshed-upstream-access"
+        mock_oauth_client.refresh_token.assert_called_once()
+
+    async def test_initial_exchange_default_mirrors_upstream(self, jwt_verifier):
+        """With the param unset, the FastMCP access token mirrors upstream."""
+        proxy = self._make_proxy(jwt_verifier)
+
+        _, result = await self._exchange(proxy)
+
+        assert result.expires_in == 3600
+        access_payload = proxy.jwt_issuer.verify_token(result.access_token)
+        assert access_payload["exp"] - access_payload["iat"] == pytest.approx(
+            3600, abs=5
+        )
+
+    async def test_refresh_exchange_decouples_access_token(self, jwt_verifier):
+        """Re-issued access tokens on refresh also honor the configured lifetime."""
+        one_day = 60 * 60 * 24
+        proxy = self._make_proxy(
+            jwt_verifier, fastmcp_access_token_expiry_seconds=one_day
+        )
+
+        client, result = await self._exchange(proxy)
+        assert result.refresh_token is not None
+
+        mock_oauth_client = AsyncMock()
+        mock_oauth_client.refresh_token = AsyncMock(
+            return_value={
+                "access_token": "refreshed-upstream-access",
+                "token_type": "Bearer",
+                "expires_in": 3600,
+                "refresh_token": "upstream-refresh",
+                "scope": "read write",
+            }
+        )
+
+        with patch.object(
+            proxy, "_create_upstream_oauth_client", return_value=mock_oauth_client
+        ):
+            refreshed = await proxy.exchange_refresh_token(
+                client=client,
+                refresh_token=RefreshToken(
+                    token=result.refresh_token,
+                    client_id="test-client",
+                    scopes=["read", "write"],
+                ),
+                scopes=["read", "write"],
+            )
+
+        assert refreshed.expires_in == one_day
+        access_payload = proxy.jwt_issuer.verify_token(refreshed.access_token)
+        assert access_payload["exp"] - access_payload["iat"] == pytest.approx(
+            one_day, abs=5
+        )
+
+
+class TestUpstreamTokenStorageTTL:
+    """Tests for upstream token storage TTL calculation (issue #2670).
+
+    The TTL should use max(refresh_expires_in, expires_in) to handle cases where
+    the refresh token has a shorter lifetime than the access token (e.g., Keycloak
+    with sliding session windows).
+    """
+
+    @pytest.fixture
+    def jwt_verifier(self):
+        """Create a mock JWT verifier."""
+        verifier = Mock(spec=TokenVerifier)
+        verifier.required_scopes = ["read", "write"]
+        verifier.verify_token = AsyncMock(return_value=None)
+        return verifier
+
+    @pytest.fixture
+    def proxy(self, jwt_verifier):
+        """Create an OAuth proxy for testing."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://idp.example.com/authorize",
+            upstream_token_endpoint="https://idp.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret-key",
+            client_storage=MemoryStore(),
+        )
+        proxy.set_mcp_path("/mcp")
+        return proxy
+
+    async def test_ttl_uses_max_when_refresh_shorter_than_access(self, proxy):
+        """TTL should use access token expiry when refresh is shorter.
+
+        This is the xsreality case: Keycloak returns refresh_expires_in=120 (2 min)
+        but expires_in=28800 (8 hours). The upstream tokens should persist for
+        8 hours (the access token lifetime), not 2 minutes.
+        """
+        # Register client
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+        await proxy.register_client(client)
+
+        # Simulate xsreality's Keycloak setup: short refresh, long access
+        client_code = ClientCode(
+            code="test-auth-code",
+            client_id="test-client",
+            redirect_uri="http://localhost:12345/callback",
+            code_challenge="test-challenge",
+            code_challenge_method="S256",
+            scopes=["read", "write"],
+            idp_tokens={
+                "access_token": "upstream-access-token",
+                "refresh_token": "upstream-refresh-token",
+                "expires_in": 28800,  # 8 hours (access token)
+                "refresh_expires_in": 120,  # 2 minutes (refresh token) - SHORTER!
+                "token_type": "Bearer",
+            },
+            expires_at=time.time() + 300,
+            created_at=time.time(),
+        )
+        await proxy._code_store.put(key=client_code.code, value=client_code)
+
+        # Exchange the code
+        auth_code = AuthorizationCode(
+            code="test-auth-code",
+            scopes=["read", "write"],
+            expires_at=time.time() + 300,
+            client_id="test-client",
+            code_challenge="test-challenge",
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+        )
+
+        result = await proxy.exchange_authorization_code(
+            client=client,
+            authorization_code=auth_code,
+        )
+
+        # Verify tokens were issued
+        assert result.access_token is not None
+        assert result.refresh_token is not None
+
+        # The key test: verify upstream tokens are stored with TTL=max(120, 28800)=28800
+        # We can verify this by checking the tokens are still accessible after 2 minutes
+        # would have passed (if TTL was incorrectly set to 120)
+        #
+        # Since we can't easily time-travel in tests, we verify the storage directly
+        # by checking that we can still look up the tokens for refresh purposes.
+        #
+        # Extract the JTI from the refresh token to look up the mapping
+        refresh_payload = proxy.jwt_issuer.verify_token(
+            result.refresh_token, expected_token_use="refresh"
+        )
+        refresh_jti = refresh_payload["jti"]
+
+        # The JTI mapping should exist
+        jti_mapping = await proxy._jti_mapping_store.get(key=refresh_jti)
+        assert jti_mapping is not None
+
+        # The upstream tokens should exist
+        upstream_tokens = await proxy._upstream_token_store.get(
+            key=jti_mapping.upstream_token_id
+        )
+        assert upstream_tokens is not None
+        assert upstream_tokens.access_token == "upstream-access-token"
+        assert upstream_tokens.refresh_token == "upstream-refresh-token"
+
+    async def test_ttl_uses_refresh_when_refresh_longer_than_access(self, proxy):
+        """TTL should use refresh token expiry when refresh is longer.
+
+        This is the ianw case: IdP returns expires_in=300 (5 min) but
+        refresh_expires_in=32318 (9 hours). The upstream tokens should persist
+        for 9 hours (the refresh token lifetime).
+        """
+        # Register client
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+        await proxy.register_client(client)
+
+        # Simulate ianw's setup: short access, long refresh (typical)
+        client_code = ClientCode(
+            code="test-auth-code-2",
+            client_id="test-client",
+            redirect_uri="http://localhost:12345/callback",
+            code_challenge="test-challenge",
+            code_challenge_method="S256",
+            scopes=["read", "write"],
+            idp_tokens={
+                "access_token": "upstream-access-token-2",
+                "refresh_token": "upstream-refresh-token-2",
+                "expires_in": 300,  # 5 minutes (access token)
+                "refresh_expires_in": 32318,  # 9 hours (refresh token) - LONGER
+                "token_type": "Bearer",
+            },
+            expires_at=time.time() + 300,
+            created_at=time.time(),
+        )
+        await proxy._code_store.put(key=client_code.code, value=client_code)
+
+        # Exchange the code
+        auth_code = AuthorizationCode(
+            code="test-auth-code-2",
+            scopes=["read", "write"],
+            expires_at=time.time() + 300,
+            client_id="test-client",
+            code_challenge="test-challenge",
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+        )
+
+        result = await proxy.exchange_authorization_code(
+            client=client,
+            authorization_code=auth_code,
+        )
+
+        # Verify tokens were issued
+        assert result.access_token is not None
+        assert result.refresh_token is not None
+
+        # Verify upstream tokens are accessible
+        refresh_payload = proxy.jwt_issuer.verify_token(
+            result.refresh_token, expected_token_use="refresh"
+        )
+        refresh_jti = refresh_payload["jti"]
+
+        jti_mapping = await proxy._jti_mapping_store.get(key=refresh_jti)
+        assert jti_mapping is not None
+
+        upstream_tokens = await proxy._upstream_token_store.get(
+            key=jti_mapping.upstream_token_id
+        )
+        assert upstream_tokens is not None
+
+    async def test_refresh_expires_in_zero_issues_refresh_token(self, proxy):
+        """refresh_expires_in=0 should fall back to the configured default.
+
+        Keycloak returns refresh_expires_in=0 for offline tokens (offline_access scope),
+        meaning "no fixed time-based expiry". The proxy should still issue a PROXY_RT.
+        """
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+        await proxy.register_client(client)
+
+        client_code = ClientCode(
+            code="test-auth-code-keycloak-offline",
+            client_id="test-client",
+            redirect_uri="http://localhost:12345/callback",
+            code_challenge="test-challenge",
+            code_challenge_method="S256",
+            scopes=["read", "write"],
+            idp_tokens={
+                "access_token": "upstream-access-token-kc",
+                "refresh_token": "upstream-refresh-token-kc",
+                "expires_in": 3600,
+                "refresh_expires_in": 0,  # Keycloak offline token convention
+                "token_type": "Bearer",
+            },
+            expires_at=time.time() + 300,
+            created_at=time.time(),
+        )
+        await proxy._code_store.put(key=client_code.code, value=client_code)
+
+        auth_code = AuthorizationCode(
+            code="test-auth-code-keycloak-offline",
+            scopes=["read", "write"],
+            expires_at=time.time() + 300,
+            client_id="test-client",
+            code_challenge="test-challenge",
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+        )
+
+        result = await proxy.exchange_authorization_code(
+            client=client,
+            authorization_code=auth_code,
+        )
+
+        # refresh_expires_in=0 must NOT prevent refresh token issuance
+        assert result.access_token is not None
+        assert result.refresh_token is not None
+
+        # Verify refresh token metadata was stored
+        refresh_meta = await proxy._refresh_token_store.get(
+            key=_hash_token(result.refresh_token)
+        )
+        assert refresh_meta is not None
+
+
+class TestTransparentUpstreamRefresh:
+    """Tests for transparent upstream token refresh in load_access_token.
+
+    When the upstream token expires but a refresh token is available, the proxy
+    should transparently refresh the upstream token rather than returning a 401
+    that forces the client into a full re-authentication flow.
+    """
+
+    @pytest.fixture
+    def mock_verifier(self):
+        """Token verifier that rejects expired tokens, accepts refreshed ones."""
+        verifier = Mock(spec=TokenVerifier)
+        verifier.required_scopes = ["read"]
+
+        # Cache tokens to test mutation of returned objects
+        cache: dict[str, AccessToken] = {}
+
+        async def verify(token: str) -> AccessToken | None:
+            if token in cache:
+                return cache[token]
+
+            if token.startswith("refreshed-") or token.startswith("valid-"):
+                t = AccessToken(
+                    token=token,
+                    client_id="test-client",
+                    scopes=["read"],
+                    expires_at=int(time.time() + 3600),
+                )
+                cache[token] = t
+                return t
+            return None
+
+        verifier.verify_token = AsyncMock(side_effect=verify)
+        return verifier
+
+    @pytest.fixture
+    def proxy(self, mock_verifier):
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://idp.example.com/authorize",
+            upstream_token_endpoint="https://idp.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=mock_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret-key",
+            client_storage=MemoryStore(),
+        )
+        proxy.set_mcp_path("/mcp")
+        return proxy
+
+    async def _setup_expired_session(
+        self,
+        proxy: OAuthProxy,
+        *,
+        upstream_refresh_token: str | None = "upstream-refresh-tok",
+    ) -> str:
+        """Set up a proxy JWT pointing at an expired upstream token.
+
+        Returns the proxy JWT (access token) that can be passed to
+        load_access_token.
+        """
+        upstream_token_id = "upstream-tok-id"
+        access_jti = "test-access-jti"
+
+        upstream_token_set = UpstreamTokenSet(
+            upstream_token_id=upstream_token_id,
+            access_token="expired-upstream-access",
+            refresh_token=upstream_refresh_token,
+            refresh_token_expires_at=time.time() + 86400
+            if upstream_refresh_token
+            else None,
+            expires_at=time.time() - 60,  # expired 1 minute ago
+            token_type="Bearer",
+            scope="read",
+            client_id="test-client",
+            created_at=time.time() - 3600,
+        )
+        await proxy._upstream_token_store.put(
+            key=upstream_token_id,
+            value=upstream_token_set,
+            ttl=86400,
+        )
+
+        await proxy._jti_mapping_store.put(
+            key=access_jti,
+            value=JTIMapping(
+                jti=access_jti,
+                upstream_token_id=upstream_token_id,
+                created_at=time.time(),
+            ),
+            ttl=3600,
+        )
+
+        fastmcp_jwt = proxy.jwt_issuer.issue_access_token(
+            client_id="test-client",
+            scopes=["read"],
+            jti=access_jti,
+            expires_in=3600,
+        )
+        return fastmcp_jwt
+
+    async def _setup_session_with_claims(self, proxy, *, upstream_claims=None):
+        """Set up a proxy JWT pointing at a valid upstream token, with optional upstream_claims."""
+        upstream_token_id = "upstream-tok-id"
+        access_jti = "test-claims-jti"
+
+        upstream_token_set = UpstreamTokenSet(
+            upstream_token_id=upstream_token_id,
+            access_token="valid-upstream-access",
+            refresh_token=None,
+            refresh_token_expires_at=None,
+            expires_at=time.time() + 3600,
+            token_type="Bearer",
+            scope="read",
+            client_id="test-client",
+            created_at=time.time(),
+        )
+        await proxy._upstream_token_store.put(
+            key=upstream_token_id,
+            value=upstream_token_set,
+            ttl=3600,
+        )
+        await proxy._jti_mapping_store.put(
+            key=access_jti,
+            value=JTIMapping(
+                jti=access_jti,
+                upstream_token_id=upstream_token_id,
+                created_at=time.time(),
+            ),
+            ttl=3600,
+        )
+        return proxy.jwt_issuer.issue_access_token(
+            client_id="test-client",
+            scopes=["read"],
+            jti=access_jti,
+            expires_in=3600,
+            upstream_claims=upstream_claims,
+        )
+
+    async def test_transparent_refresh_on_expired_upstream(self, proxy):
+        """load_access_token refreshes upstream token when validation fails."""
+        fastmcp_jwt = await self._setup_expired_session(proxy)
+
+        mock_oauth_client = AsyncMock()
+        mock_oauth_client.refresh_token = AsyncMock(
+            return_value={
+                "access_token": "refreshed-upstream-access",
+                "token_type": "Bearer",
+                "expires_in": 3600,
+                "refresh_token": "upstream-refresh-tok",
+                "scope": "read",
+            }
+        )
+
+        with patch.object(
+            proxy, "_create_upstream_oauth_client", return_value=mock_oauth_client
+        ):
+            result = await proxy.load_access_token(fastmcp_jwt)
+
+        assert result is not None
+        assert result.token == "refreshed-upstream-access"
+        mock_oauth_client.refresh_token.assert_called_once()
+        mock_oauth_client.aclose.assert_awaited_once()
+
+    async def test_transparent_refresh_updates_stored_token(self, proxy):
+        """After transparent refresh, the stored upstream token is updated."""
+        fastmcp_jwt = await self._setup_expired_session(proxy)
+
+        mock_oauth_client = AsyncMock()
+        mock_oauth_client.refresh_token = AsyncMock(
+            return_value={
+                "access_token": "refreshed-upstream-access",
+                "token_type": "Bearer",
+                "expires_in": 7200,
+                "refresh_token": "upstream-refresh-tok",
+                "scope": "read",
+            }
+        )
+
+        with patch.object(
+            proxy, "_create_upstream_oauth_client", return_value=mock_oauth_client
+        ):
+            await proxy.load_access_token(fastmcp_jwt)
+
+        stored = await proxy._upstream_token_store.get(key="upstream-tok-id")
+        assert stored is not None
+        assert stored.access_token == "refreshed-upstream-access"
+        assert stored.expires_at > time.time()
+
+    async def test_no_refresh_without_refresh_token(self, proxy):
+        """Without a refresh token, load_access_token returns None immediately."""
+        fastmcp_jwt = await self._setup_expired_session(
+            proxy, upstream_refresh_token=None
+        )
+
+        result = await proxy.load_access_token(fastmcp_jwt)
+
+        assert result is None
+
+    async def test_returns_none_when_refresh_fails(self, proxy):
+        """If the upstream refresh call fails, load_access_token returns None."""
+        fastmcp_jwt = await self._setup_expired_session(proxy)
+
+        mock_oauth_client = AsyncMock()
+        mock_oauth_client.refresh_token = AsyncMock(
+            side_effect=Exception("upstream refused refresh")
+        )
+
+        with patch.object(
+            proxy, "_create_upstream_oauth_client", return_value=mock_oauth_client
+        ):
+            result = await proxy.load_access_token(fastmcp_jwt)
+
+        assert result is None
+
+    async def test_returns_none_when_refreshed_token_still_invalid(self, proxy):
+        """If the refreshed token also fails validation, returns None."""
+        fastmcp_jwt = await self._setup_expired_session(proxy)
+
+        mock_oauth_client = AsyncMock()
+        mock_oauth_client.refresh_token = AsyncMock(
+            return_value={
+                "access_token": "still-bad-token",
+                "token_type": "Bearer",
+                "expires_in": 3600,
+                "scope": "read",
+            }
+        )
+
+        with patch.object(
+            proxy, "_create_upstream_oauth_client", return_value=mock_oauth_client
+        ):
+            result = await proxy.load_access_token(fastmcp_jwt)
+
+        # "still-bad-token" doesn't start with "refreshed-" so verifier rejects it
+        assert result is None
+
+    async def test_no_refresh_when_token_not_expired(self, proxy):
+        """Non-expiry validation failures (e.g. revocation) should not trigger refresh."""
+        upstream_token_id = "upstream-tok-id"
+        access_jti = "test-access-jti"
+
+        # Token is NOT expired — verification failure is for another reason
+        upstream_token_set = UpstreamTokenSet(
+            upstream_token_id=upstream_token_id,
+            access_token="revoked-upstream-access",
+            refresh_token="upstream-refresh-tok",
+            refresh_token_expires_at=time.time() + 86400,
+            expires_at=time.time() + 3600,  # still valid for 1 hour
+            token_type="Bearer",
+            scope="read",
+            client_id="test-client",
+            created_at=time.time() - 60,
+        )
+        await proxy._upstream_token_store.put(
+            key=upstream_token_id,
+            value=upstream_token_set,
+            ttl=86400,
+        )
+        await proxy._jti_mapping_store.put(
+            key=access_jti,
+            value=JTIMapping(
+                jti=access_jti,
+                upstream_token_id=upstream_token_id,
+                created_at=time.time(),
+            ),
+            ttl=3600,
+        )
+        fastmcp_jwt = proxy.jwt_issuer.issue_access_token(
+            client_id="test-client",
+            scopes=["read"],
+            jti=access_jti,
+            expires_in=3600,
+        )
+
+        mock_oauth_client = AsyncMock()
+        mock_oauth_client.refresh_token = AsyncMock()
+
+        with patch.object(
+            proxy, "_create_upstream_oauth_client", return_value=mock_oauth_client
+        ):
+            result = await proxy.load_access_token(fastmcp_jwt)
+
+        assert result is None
+        # Refresh should NOT have been attempted
+        mock_oauth_client.refresh_token.assert_not_called()
+
+    async def test_reload_from_storage_after_refresh_failure(self, proxy):
+        """If refresh fails, re-read from storage in case another worker refreshed."""
+        fastmcp_jwt = await self._setup_expired_session(proxy)
+
+        # Simulate: refresh fails (stale refresh token), but another worker
+        # already wrote a fresh upstream token to storage.
+        refreshed_token_set = UpstreamTokenSet(
+            upstream_token_id="upstream-tok-id",
+            access_token="refreshed-upstream-access",
+            refresh_token="new-refresh-tok",
+            refresh_token_expires_at=time.time() + 86400,
+            expires_at=time.time() + 3600,
+            token_type="Bearer",
+            scope="read",
+            client_id="test-client",
+            created_at=time.time(),
+        )
+
+        # The store is read three times:
+        # 1. Initial lookup in load_access_token
+        # 2. Re-read inside the advisory lock
+        # 3. Re-read after refresh failure (recovery path)
+        original_get = proxy._upstream_token_store.get
+        call_count = 0
+
+        async def mock_get(key: str) -> UpstreamTokenSet | None:
+            nonlocal call_count
+            call_count += 1
+            if call_count <= 2:
+                return await original_get(key)
+            # After refresh failure, return the "other worker's" refreshed token
+            return refreshed_token_set
+
+        mock_oauth_client = AsyncMock()
+        mock_oauth_client.refresh_token = AsyncMock(
+            side_effect=Exception("refresh token rotated by another worker")
+        )
+
+        with (
+            patch.object(
+                proxy, "_create_upstream_oauth_client", return_value=mock_oauth_client
+            ),
+            patch.object(proxy._upstream_token_store, "get", side_effect=mock_get),
+        ):
+            result = await proxy.load_access_token(fastmcp_jwt)
+
+        assert result is not None
+        assert result.token == "refreshed-upstream-access"
+
+    def test_refresh_lock_cache_bounded(self, proxy, monkeypatch):
+        """_get_refresh_lock never grows beyond _REFRESH_LOCK_CACHE_SIZE."""
+        monkeypatch.setattr(
+            "fastmcp.server.auth.oauth_proxy.proxy._REFRESH_LOCK_CACHE_SIZE", 3
+        )
+        for i in range(10):
+            proxy._get_refresh_lock(f"token-{i}")
+        assert len(proxy._refresh_locks) == 3
+
+    def test_refresh_lock_lru_evicts_least_recently_used(self, proxy, monkeypatch):
+        """Touching an entry promotes it; eviction removes the oldest untouched entry."""
+        monkeypatch.setattr(
+            "fastmcp.server.auth.oauth_proxy.proxy._REFRESH_LOCK_CACHE_SIZE", 3
+        )
+        proxy._get_refresh_lock("a")
+        proxy._get_refresh_lock("b")
+        proxy._get_refresh_lock("c")
+        # Touch "a" to move it to MRU position
+        proxy._get_refresh_lock("a")
+        # Adding "d" should evict "b" (oldest untouched)
+        proxy._get_refresh_lock("d")
+        assert "b" not in proxy._refresh_locks
+        assert "a" in proxy._refresh_locks
+        assert "c" in proxy._refresh_locks
+        assert "d" in proxy._refresh_locks
+
+    def test_refresh_lock_same_token_returns_same_lock(self, proxy):
+        """Requesting the same token ID twice returns the same lock object."""
+        lock1 = proxy._get_refresh_lock("tok")
+        lock2 = proxy._get_refresh_lock("tok")
+        assert lock1 is lock2
+
+    async def test_upstream_claims_propagated(self, proxy):
+        jwt = await self._setup_session_with_claims(
+            proxy, upstream_claims={"sub": "user-123"}
+        )
+        result = await proxy.load_access_token(jwt)
+        assert result is not None
+        assert result.claims["upstream_claims"] == {"sub": "user-123"}
+
+    async def test_upstream_claims_not_mutated_on_cached_token(
+        self, proxy, mock_verifier
+    ):
+        jwt = await self._setup_session_with_claims(
+            proxy, upstream_claims={"sub": "user-123"}
+        )
+        result = await proxy.load_access_token(jwt)
+        assert result is not None
+        assert result.claims["upstream_claims"] == {"sub": "user-123"}
+        # Original verifier result must not be mutated
+        for call in list(mock_verifier.verify_token.call_args_list):
+            returned = await mock_verifier.verify_token(call.args[0])
+            if returned:
+                assert "upstream_claims" not in returned.claims
+
+    async def test_transparent_refresh_triggered_by_threshold(self, mock_verifier):
+        """Token within expiry threshold is treated as expired and refreshed."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://idp.example.com/authorize",
+            upstream_token_endpoint="https://idp.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=mock_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret-key",
+            client_storage=MemoryStore(),
+            token_expiry_threshold_seconds=60,
+        )
+        proxy.set_mcp_path("/mcp")
+
+        upstream_token_id = "upstream-tok-threshold"
+        access_jti = "test-threshold-jti"
+
+        upstream_token_set = UpstreamTokenSet(
+            upstream_token_id=upstream_token_id,
+            access_token="almost-expired-upstream-access",
+            refresh_token="upstream-refresh-tok",
+            refresh_token_expires_at=time.time() + 86400,
+            expires_at=time.time() + 30,  # expires in 30s, within 60s threshold
+            token_type="Bearer",
+            scope="read",
+            client_id="test-client",
+            created_at=time.time() - 3600,
+        )
+        await proxy._upstream_token_store.put(
+            key=upstream_token_id,
+            value=upstream_token_set,
+            ttl=86400,
+        )
+        await proxy._jti_mapping_store.put(
+            key=access_jti,
+            value=JTIMapping(
+                jti=access_jti,
+                upstream_token_id=upstream_token_id,
+                created_at=time.time(),
+            ),
+            ttl=3600,
+        )
+        fastmcp_jwt = proxy.jwt_issuer.issue_access_token(
+            client_id="test-client",
+            scopes=["read"],
+            jti=access_jti,
+            expires_in=3600,
+        )
+
+        mock_oauth_client = AsyncMock()
+        mock_oauth_client.refresh_token = AsyncMock(
+            return_value={
+                "access_token": "refreshed-upstream-access",
+                "token_type": "Bearer",
+                "expires_in": 3600,
+                "refresh_token": "upstream-refresh-tok",
+                "scope": "read",
+            }
+        )
+
+        with patch.object(
+            proxy, "_create_upstream_oauth_client", return_value=mock_oauth_client
+        ):
+            result = await proxy.load_access_token(fastmcp_jwt)
+
+        assert result is not None
+        assert result.token == "refreshed-upstream-access"
+        mock_oauth_client.refresh_token.assert_called_once()
+
+    async def test_no_refresh_when_within_threshold_but_no_refresh_token(
+        self, mock_verifier
+    ):
+        """Token within threshold but without refresh token is not refreshed."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://idp.example.com/authorize",
+            upstream_token_endpoint="https://idp.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=mock_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret-key",
+            client_storage=MemoryStore(),
+            token_expiry_threshold_seconds=60,
+        )
+        proxy.set_mcp_path("/mcp")
+
+        upstream_token_id = "upstream-tok-no-refresh"
+        access_jti = "test-no-refresh-jti"
+
+        upstream_token_set = UpstreamTokenSet(
+            upstream_token_id=upstream_token_id,
+            access_token="valid-upstream-access",
+            refresh_token=None,
+            refresh_token_expires_at=None,
+            expires_at=time.time() + 30,  # expires in 30s, within 60s threshold
+            token_type="Bearer",
+            scope="read",
+            client_id="test-client",
+            created_at=time.time() - 3600,
+        )
+        await proxy._upstream_token_store.put(
+            key=upstream_token_id,
+            value=upstream_token_set,
+            ttl=86400,
+        )
+        await proxy._jti_mapping_store.put(
+            key=access_jti,
+            value=JTIMapping(
+                jti=access_jti,
+                upstream_token_id=upstream_token_id,
+                created_at=time.time(),
+            ),
+            ttl=3600,
+        )
+        fastmcp_jwt = proxy.jwt_issuer.issue_access_token(
+            client_id="test-client",
+            scopes=["read"],
+            jti=access_jti,
+            expires_in=3600,
+        )
+
+        result = await proxy.load_access_token(fastmcp_jwt)
+
+        # Token validates via the verifier (starts with "valid-"), so even though
+        # it's within threshold, no refresh is attempted without a refresh token.
+        assert result is not None
+        assert result.token == "valid-upstream-access"
+
+    async def test_zero_threshold_only_refreshes_on_actual_expiry(self, mock_verifier):
+        """With threshold=0, token that's not yet expired is not refreshed."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://idp.example.com/authorize",
+            upstream_token_endpoint="https://idp.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=mock_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret-key",
+            client_storage=MemoryStore(),
+            token_expiry_threshold_seconds=0,
+        )
+        proxy.set_mcp_path("/mcp")
+
+        upstream_token_id = "upstream-tok-zero-threshold"
+        access_jti = "test-zero-threshold-jti"
+
+        upstream_token_set = UpstreamTokenSet(
+            upstream_token_id=upstream_token_id,
+            access_token="valid-upstream-access",
+            refresh_token="upstream-refresh-tok",
+            refresh_token_expires_at=time.time() + 86400,
+            expires_at=time.time() + 30,  # expires in 30s, but threshold is 0
+            token_type="Bearer",
+            scope="read",
+            client_id="test-client",
+            created_at=time.time() - 3600,
+        )
+        await proxy._upstream_token_store.put(
+            key=upstream_token_id,
+            value=upstream_token_set,
+            ttl=86400,
+        )
+        await proxy._jti_mapping_store.put(
+            key=access_jti,
+            value=JTIMapping(
+                jti=access_jti,
+                upstream_token_id=upstream_token_id,
+                created_at=time.time(),
+            ),
+            ttl=3600,
+        )
+        fastmcp_jwt = proxy.jwt_issuer.issue_access_token(
+            client_id="test-client",
+            scopes=["read"],
+            jti=access_jti,
+            expires_in=3600,
+        )
+
+        result = await proxy.load_access_token(fastmcp_jwt)
+
+        # With threshold=0, token with 30s remaining is still valid
+        assert result is not None
+        assert result.token == "valid-upstream-access"
+
+    async def test_proactive_refresh_when_validated_but_within_threshold(
+        self, mock_verifier
+    ):
+        """Token that passes validation but is within threshold gets proactively refreshed."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://idp.example.com/authorize",
+            upstream_token_endpoint="https://idp.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=mock_verifier,
+            base_url="https://proxy.example.com",
+            jwt_signing_key="test-secret-key",
+            client_storage=MemoryStore(),
+            token_expiry_threshold_seconds=60,
+        )
+        proxy.set_mcp_path("/mcp")
+
+        upstream_token_id = "upstream-tok-proactive"
+        access_jti = "test-proactive-jti"
+
+        # Token starts with "valid-" so the mock verifier accepts it,
+        # but it expires in 30s which is within the 60s threshold.
+        upstream_token_set = UpstreamTokenSet(
+            upstream_token_id=upstream_token_id,
+            access_token="valid-but-near-expiry",
+            refresh_token="upstream-refresh-tok",
+            refresh_token_expires_at=time.time() + 86400,
+            expires_at=time.time() + 30,
+            token_type="Bearer",
+            scope="read",
+            client_id="test-client",
+            created_at=time.time() - 3600,
+        )
+        await proxy._upstream_token_store.put(
+            key=upstream_token_id,
+            value=upstream_token_set,
+            ttl=86400,
+        )
+        await proxy._jti_mapping_store.put(
+            key=access_jti,
+            value=JTIMapping(
+                jti=access_jti,
+                upstream_token_id=upstream_token_id,
+                created_at=time.time(),
+            ),
+            ttl=3600,
+        )
+        fastmcp_jwt = proxy.jwt_issuer.issue_access_token(
+            client_id="test-client",
+            scopes=["read"],
+            jti=access_jti,
+            expires_in=3600,
+        )
+
+        mock_oauth_client = AsyncMock()
+        mock_oauth_client.refresh_token = AsyncMock(
+            return_value={
+                "access_token": "refreshed-upstream-access",
+                "token_type": "Bearer",
+                "expires_in": 3600,
+                "refresh_token": "upstream-refresh-tok",
+                "scope": "read",
+            }
+        )
+
+        with patch.object(
+            proxy, "_create_upstream_oauth_client", return_value=mock_oauth_client
+        ):
+            result = await proxy.load_access_token(fastmcp_jwt)
+
+        assert result is not None
+        assert result.token == "refreshed-upstream-access"
+        mock_oauth_client.refresh_token.assert_called_once()
+
+
+class TestRefreshTokenMissLogging:
+    """A refresh-token miss forces a user-visible reconnect, so it must not be silent."""
+
+    async def test_unknown_refresh_token_logs_warning(self, oauth_proxy, caplog):
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        proxy_logger = logging.getLogger("fastmcp.server.auth.oauth_proxy.proxy")
+        caplog.set_level(logging.WARNING)
+        proxy_logger.addHandler(caplog.handler)
+        try:
+            result = await oauth_proxy.load_refresh_token(client, "nonexistent-token")
+        finally:
+            proxy_logger.removeHandler(caplog.handler)
+
+        assert result is None
+        assert any(
+            record.levelno == logging.WARNING
+            and "Refresh token not found" in record.getMessage()
+            and "test-client" in record.getMessage()
+            for record in caplog.records
+        )
diff --git a/tests/server/auth/oauth_proxy/test_ui.py b/tests/server/auth/oauth_proxy/test_ui.py
new file mode 100644
index 0000000..6f174ae
--- /dev/null
+++ b/tests/server/auth/oauth_proxy/test_ui.py
@@ -0,0 +1,119 @@
+"""Tests for OAuth proxy UI and error page rendering."""
+
+from unittest.mock import Mock
+
+from key_value.aio.stores.memory import MemoryStore
+from starlette.requests import Request
+from starlette.responses import HTMLResponse
+
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.server.auth.oauth_proxy.ui import create_consent_html, create_error_html
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+
+class TestErrorPageRendering:
+    """Test error page rendering for OAuth callback errors."""
+
+    def test_create_error_html_basic(self):
+        """Test basic error page generation."""
+
+        html = create_error_html(
+            error_title="Test Error",
+            error_message="This is a test error message",
+        )
+
+        # Verify it's valid HTML
+        assert "<!DOCTYPE html>" in html
+        assert "<title>Test Error</title>" in html
+        assert "This is a test error message" in html
+        assert 'class="info-box error"' in html
+
+    def test_create_error_html_with_details(self):
+        """Test error page with error details."""
+
+        html = create_error_html(
+            error_title="OAuth Error",
+            error_message="Authentication failed",
+            error_details={
+                "Error Code": "invalid_scope",
+                "Description": "Requested scope does not exist",
+            },
+        )
+
+        # Verify error details are included
+        assert "Error Details" in html
+        assert "Error Code" in html
+        assert "invalid_scope" in html
+        assert "Description" in html
+        assert "Requested scope does not exist" in html
+
+    def test_create_error_html_escapes_user_input(self):
+        """Test that error page properly escapes HTML in user input."""
+
+        html = create_error_html(
+            error_title="Error <script>alert('xss')</script>",
+            error_message="Message with <b>HTML</b> tags",
+            error_details={"Key<script>": "Value<img>"},
+        )
+
+        # Verify HTML is escaped
+        assert "<script>alert('xss')</script>" not in html
+        assert "&lt;script&gt;" in html
+        assert "<b>HTML</b>" not in html
+        assert "&lt;b&gt;HTML&lt;/b&gt;" in html
+
+    async def test_callback_error_returns_html_page(self):
+        """Test that OAuth callback errors return styled HTML instead of data: URLs."""
+        # Create a minimal OAuth proxy
+        provider = OAuthProxy(
+            upstream_authorization_endpoint="https://idp.example.com/authorize",
+            upstream_token_endpoint="https://idp.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=JWTVerifier(
+                jwks_uri="https://idp.example.com/.well-known/jwks.json",
+                issuer="https://idp.example.com",
+                audience="test-client",
+            ),
+            base_url="http://localhost:8000",
+            jwt_signing_key="test-signing-key",
+            client_storage=MemoryStore(),
+        )
+
+        # Mock a request with an error from the IdP
+        mock_request = Mock(spec=Request)
+        mock_request.query_params = {
+            "error": "invalid_scope",
+            "error_description": "The application asked for scope 'read' that doesn't exist",
+            "state": "test-state",
+        }
+
+        # Call the callback handler
+        response = await provider._handle_idp_callback(mock_request)
+
+        # Verify we get an HTMLResponse, not a RedirectResponse
+        assert isinstance(response, HTMLResponse)
+        assert response.status_code == 400
+
+        # Verify the response contains the error message
+        assert b"invalid_scope" in response.body
+        assert b"doesn&#x27;t exist" in response.body  # HTML-escaped apostrophe
+        assert b"OAuth Error" in response.body
+
+
+class TestConsentPageRendering:
+    """Test consent page rendering and escaping."""
+
+    def test_create_consent_html_escapes_client_id_in_details(self):
+        """Test that Application ID is escaped in advanced details."""
+
+        html = create_consent_html(
+            client_id='evil<img src=x onerror=alert("xss")>',
+            redirect_uri="https://example.com/callback",
+            scopes=["read"],
+            txn_id="txn",
+            csrf_token="csrf",
+        )
+
+        assert 'evil<img src=x onerror=alert("xss")>' not in html
+        assert "evil&lt;img src=x onerror=alert(&quot;xss&quot;)&gt;" in html
diff --git a/tests/server/auth/providers/__init__.py b/tests/server/auth/providers/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/server/auth/providers/test_auth0.py b/tests/server/auth/providers/test_auth0.py
new file mode 100644
index 0000000..2c8cb1b
--- /dev/null
+++ b/tests/server/auth/providers/test_auth0.py
@@ -0,0 +1,99 @@
+"""Unit tests for Auth0 OAuth provider."""
+
+from unittest.mock import patch
+
+import pytest
+
+from fastmcp.server.auth.oidc_proxy import OIDCConfiguration
+from fastmcp.server.auth.providers.auth0 import Auth0Provider
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+TEST_CONFIG_URL = "https://example.com/.well-known/openid-configuration"
+TEST_CLIENT_ID = "test-client-id"
+TEST_CLIENT_SECRET = "test-client-secret"
+TEST_AUDIENCE = "test-audience"
+TEST_BASE_URL = "https://example.com:8000/"
+TEST_REDIRECT_PATH = "/test/callback"
+TEST_REQUIRED_SCOPES = ["openid", "email"]
+
+
+@pytest.fixture
+def valid_oidc_configuration_dict():
+    """Create a valid OIDC configuration dict for testing."""
+    return {
+        "issuer": "https://example.com",
+        "authorization_endpoint": "https://example.com/authorize",
+        "token_endpoint": "https://example.com/oauth/token",
+        "jwks_uri": "https://example.com/.well-known/jwks.json",
+        "response_types_supported": ["code"],
+        "subject_types_supported": ["public"],
+        "id_token_signing_alg_values_supported": ["RS256"],
+    }
+
+
+class TestAuth0Provider:
+    """Test Auth0Provider initialization."""
+
+    def test_init_with_explicit_params(self, valid_oidc_configuration_dict):
+        """Test initialization with explicit parameters."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            provider = Auth0Provider(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                audience=TEST_AUDIENCE,
+                base_url=TEST_BASE_URL,
+                redirect_path=TEST_REDIRECT_PATH,
+                required_scopes=TEST_REQUIRED_SCOPES,
+                jwt_signing_key="test-secret",
+            )
+
+            mock_get.assert_called_once()
+
+            call_args = mock_get.call_args
+            assert str(call_args[0][0]) == TEST_CONFIG_URL
+
+            assert provider._upstream_client_id == TEST_CLIENT_ID
+            assert provider._upstream_client_secret is not None
+            assert (
+                provider._upstream_client_secret.get_secret_value()
+                == TEST_CLIENT_SECRET
+            )
+
+            assert isinstance(provider._token_validator, JWTVerifier)
+            assert provider._token_validator.audience == TEST_AUDIENCE
+
+            assert str(provider.base_url) == TEST_BASE_URL
+            assert provider._redirect_path == TEST_REDIRECT_PATH
+            assert provider._token_validator.required_scopes == TEST_REQUIRED_SCOPES
+
+    def test_init_defaults(self, valid_oidc_configuration_dict):
+        """Test that default values are applied correctly."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            provider = Auth0Provider(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                audience=TEST_AUDIENCE,
+                base_url=TEST_BASE_URL,
+                jwt_signing_key="test-secret",
+            )
+
+            # Check defaults
+            assert str(provider.base_url) == TEST_BASE_URL
+            assert provider._redirect_path == "/auth/callback"
+            assert provider._token_validator.required_scopes == ["openid"]
diff --git a/tests/server/auth/providers/test_aws.py b/tests/server/auth/providers/test_aws.py
new file mode 100644
index 0000000..4f5232b
--- /dev/null
+++ b/tests/server/auth/providers/test_aws.py
@@ -0,0 +1,140 @@
+"""Unit tests for AWS Cognito OAuth provider."""
+
+from contextlib import contextmanager
+from unittest.mock import patch
+
+from fastmcp.server.auth.providers.aws import (
+    AWSCognitoProvider,
+)
+
+
+@contextmanager
+def mock_cognito_oidc_discovery():
+    """Context manager to mock AWS Cognito OIDC discovery endpoint."""
+    mock_oidc_config = {
+        "issuer": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXXXXXX",
+        "authorization_endpoint": "https://test.auth.us-east-1.amazoncognito.com/oauth2/authorize",
+        "token_endpoint": "https://test.auth.us-east-1.amazoncognito.com/oauth2/token",
+        "jwks_uri": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXXXXXX/.well-known/jwks.json",
+        "userinfo_endpoint": "https://test.auth.us-east-1.amazoncognito.com/oauth2/userInfo",
+        "response_types_supported": ["code", "token"],
+        "subject_types_supported": ["public"],
+        "id_token_signing_alg_values_supported": ["RS256"],
+        "scopes_supported": ["openid", "email", "phone", "profile"],
+        "token_endpoint_auth_methods_supported": [
+            "client_secret_basic",
+            "client_secret_post",
+        ],
+    }
+
+    with patch("httpx.get") as mock_get:
+        mock_response = mock_get.return_value
+        mock_response.raise_for_status.return_value = None
+        mock_response.json.return_value = mock_oidc_config
+        yield
+
+
+class TestAWSCognitoProvider:
+    """Test AWSCognitoProvider initialization."""
+
+    def test_init_with_explicit_params(self):
+        """Test initialization with explicit parameters."""
+        with mock_cognito_oidc_discovery():
+            provider = AWSCognitoProvider(
+                user_pool_id="us-east-1_XXXXXXXXX",
+                aws_region="us-east-1",
+                client_id="test_client",
+                client_secret="test_secret",
+                base_url="https://example.com",
+                redirect_path="/custom/callback",
+                required_scopes=["openid", "email"],
+                jwt_signing_key="test-secret",
+            )
+
+            # Check that the provider was initialized correctly
+            assert provider._upstream_client_id == "test_client"
+            assert provider._upstream_client_secret is not None
+            assert provider._upstream_client_secret.get_secret_value() == "test_secret"
+            assert (
+                str(provider.base_url) == "https://example.com/"
+            )  # URLs get normalized with trailing slash
+            assert provider._redirect_path == "/custom/callback"
+            # OIDC provider should have discovered the endpoints automatically
+            assert (
+                provider._upstream_authorization_endpoint
+                == "https://test.auth.us-east-1.amazoncognito.com/oauth2/authorize"
+            )
+            assert (
+                provider._upstream_token_endpoint
+                == "https://test.auth.us-east-1.amazoncognito.com/oauth2/token"
+            )
+
+    def test_init_defaults(self):
+        """Test that default values are applied correctly."""
+        with mock_cognito_oidc_discovery():
+            provider = AWSCognitoProvider(
+                user_pool_id="us-east-1_XXXXXXXXX",
+                client_id="test_client",
+                client_secret="test_secret",
+                base_url="https://example.com",
+                jwt_signing_key="test-secret",
+            )
+
+            # Check defaults
+            assert str(provider.base_url) == "https://example.com/"
+            assert provider._redirect_path == "/auth/callback"
+            assert provider._token_validator.required_scopes == ["openid"]
+            assert provider.aws_region == "eu-central-1"
+
+    def test_oidc_discovery_integration(self):
+        """Test that OIDC discovery endpoints are used correctly."""
+        with mock_cognito_oidc_discovery():
+            provider = AWSCognitoProvider(
+                user_pool_id="us-west-2_YYYYYYYY",
+                aws_region="us-west-2",
+                client_id="test_client",
+                client_secret="test_secret",
+                base_url="https://example.com",
+                jwt_signing_key="test-secret",
+            )
+
+            # OIDC discovery should have configured the endpoints automatically
+            assert provider._upstream_authorization_endpoint is not None
+            assert provider._upstream_token_endpoint is not None
+            assert "amazoncognito.com" in provider._upstream_authorization_endpoint
+
+    def test_token_verifier_checks_client_id_not_aud(self):
+        """Cognito verifier should check client_id claim, not aud."""
+        with mock_cognito_oidc_discovery():
+            provider = AWSCognitoProvider(
+                user_pool_id="us-east-1_XXXXXXXXX",
+                client_id="test_client",
+                client_secret="test_secret",
+                base_url="https://example.com",
+                jwt_signing_key="test-secret",
+            )
+
+            verifier = provider.get_token_verifier()
+
+            assert verifier._expected_client_id == "test_client"
+            assert verifier.audience is None
+
+    def test_token_verifier_supports_audience_override(self):
+        """Audience param maps to client_id validation in Cognito verifier."""
+        with mock_cognito_oidc_discovery():
+            provider = AWSCognitoProvider(
+                user_pool_id="us-east-1_XXXXXXXXX",
+                client_id="test_client",
+                client_secret="test_secret",
+                base_url="https://example.com",
+                jwt_signing_key="test-secret",
+            )
+
+            verifier = provider.get_token_verifier(audience="custom-audience")
+
+            assert verifier._expected_client_id == "custom-audience"
+            assert verifier.audience is None
+
+
+# Token verification functionality is now tested as part of the OIDC provider integration
+# The CognitoTokenVerifier class is an internal implementation detail
diff --git a/tests/server/auth/providers/test_azure.py b/tests/server/auth/providers/test_azure.py
new file mode 100644
index 0000000..1bca397
--- /dev/null
+++ b/tests/server/auth/providers/test_azure.py
@@ -0,0 +1,1492 @@
+"""Tests for Azure (Microsoft Entra) OAuth provider."""
+
+import time
+from unittest.mock import AsyncMock, patch
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+from key_value.aio.stores.memory import MemoryStore
+from mcp.server.auth.provider import (
+    AuthorizationCode,
+    AuthorizationParams,
+    RefreshToken,
+)
+from mcp.shared.auth import OAuthClientInformationFull
+from pydantic import AnyUrl
+
+from fastmcp.server.auth.oauth_proxy.models import ClientCode, UpstreamTokenSet
+from fastmcp.server.auth.providers.azure import AzureProvider
+from fastmcp.server.auth.providers.jwt import JWTVerifier, RSAKeyPair
+
+
+@pytest.fixture
+def memory_storage() -> MemoryStore:
+    """Provide a MemoryStore for tests to avoid SQLite initialization on Windows."""
+    return MemoryStore()
+
+
+class TestAzureProvider:
+    """Test Azure OAuth provider functionality."""
+
+    def test_init_with_explicit_params(self, memory_storage: MemoryStore):
+        """Test AzureProvider initialization with explicit parameters."""
+        provider = AzureProvider(
+            client_id="12345678-1234-1234-1234-123456789012",
+            client_secret="azure_secret_123",
+            tenant_id="87654321-4321-4321-4321-210987654321",
+            base_url="https://myserver.com",
+            required_scopes=["read", "write"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert provider._upstream_client_id == "12345678-1234-1234-1234-123456789012"
+        assert provider._upstream_client_secret is not None
+        assert provider._upstream_client_secret.get_secret_value() == "azure_secret_123"
+        assert str(provider.base_url) == "https://myserver.com/"
+        # Check tenant is in the endpoints
+        parsed_auth = urlparse(provider._upstream_authorization_endpoint)
+        assert "87654321-4321-4321-4321-210987654321" in parsed_auth.path
+        parsed_token = urlparse(provider._upstream_token_endpoint)
+        assert "87654321-4321-4321-4321-210987654321" in parsed_token.path
+
+    def test_init_defaults(self, memory_storage: MemoryStore):
+        """Test that default values are applied correctly."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Check defaults
+        assert provider._redirect_path == "/auth/callback"
+        # Azure provider defaults are set but we can't easily verify them without accessing internals
+
+    def test_offline_access_automatically_included(self, memory_storage: MemoryStore):
+        """Test that offline_access is automatically added to get refresh tokens."""
+        # Without specifying offline_access
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert "offline_access" in provider.additional_authorize_scopes
+
+    def test_offline_access_not_duplicated(self, memory_storage: MemoryStore):
+        """Test that offline_access is not duplicated if already specified."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            additional_authorize_scopes=["User.Read", "offline_access"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Should appear exactly once
+        assert provider.additional_authorize_scopes.count("offline_access") == 1
+        assert "User.Read" in provider.additional_authorize_scopes
+
+    def test_oauth_endpoints_configured_correctly(self, memory_storage: MemoryStore):
+        """Test that OAuth endpoints are configured correctly."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="my-tenant-id",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            jwt_signing_key="test_secret",
+            client_storage=memory_storage,
+        )
+
+        # Check that endpoints use the correct Azure OAuth2 v2.0 endpoints with tenant
+        assert (
+            provider._upstream_authorization_endpoint
+            == "https://login.microsoftonline.com/my-tenant-id/oauth2/v2.0/authorize"
+        )
+        assert (
+            provider._upstream_token_endpoint
+            == "https://login.microsoftonline.com/my-tenant-id/oauth2/v2.0/token"
+        )
+        assert (
+            provider._upstream_revocation_endpoint is None
+        )  # Azure doesn't support revocation
+
+    def test_special_tenant_values(self, memory_storage: MemoryStore):
+        """Test that special tenant values are accepted."""
+        # Test with "organizations"
+        provider1 = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="organizations",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+        parsed = urlparse(provider1._upstream_authorization_endpoint)
+        assert "/organizations/" in parsed.path
+
+        # Test with "consumers"
+        provider2 = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="consumers",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+        parsed = urlparse(provider2._upstream_authorization_endpoint)
+        assert "/consumers/" in parsed.path
+
+    def test_azure_specific_scopes(self, memory_storage: MemoryStore):
+        """Test handling of custom API scope formats."""
+        # Test that the provider accepts custom API scopes without error
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            required_scopes=[
+                "read",
+                "write",
+                "admin",
+            ],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Provider should initialize successfully with these scopes
+        assert provider is not None
+        # Scopes are stored unprefixed for token validation
+        # (Azure returns unprefixed scopes in JWT tokens)
+        assert provider._token_validator.required_scopes == [
+            "read",
+            "write",
+            "admin",
+        ]
+
+    def test_init_does_not_require_api_client_id_anymore(
+        self, memory_storage: MemoryStore
+    ):
+        """API client ID is no longer required; audience is client_id."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+        assert provider is not None
+
+    def test_init_with_custom_audience_uses_jwt_verifier(
+        self, memory_storage: MemoryStore
+    ):
+        """When audience is provided, JWTVerifier is configured with JWKS and issuer."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="my-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=[".default"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert provider._token_validator is not None
+        assert isinstance(provider._token_validator, JWTVerifier)
+        verifier = provider._token_validator
+        assert verifier.jwks_uri is not None
+        assert verifier.jwks_uri.startswith(
+            "https://login.microsoftonline.com/my-tenant/discovery/v2.0/keys"
+        )
+        assert verifier.issuer == "https://login.microsoftonline.com/my-tenant/v2.0"
+        assert verifier.audience == ["test_client", "api://my-api"]
+        # Scopes are stored unprefixed for token validation
+        # (Azure returns unprefixed scopes like ".default" in JWT tokens)
+        assert verifier.required_scopes == [".default"]
+
+    async def test_token_accepted_with_client_id_audience(
+        self, memory_storage: MemoryStore
+    ):
+        """Azure AD v2 tokens use the bare client_id as aud — must be accepted."""
+        key_pair = RSAKeyPair.generate()
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="my-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert isinstance(provider._token_validator, JWTVerifier)
+        verifier = provider._token_validator
+        verifier.public_key = key_pair.public_key
+        verifier.jwks_uri = None
+
+        token = key_pair.create_token(
+            subject="test-user",
+            issuer="https://login.microsoftonline.com/my-tenant/v2.0",
+            audience="test_client",
+            additional_claims={"scp": "read"},
+        )
+        result = await verifier.load_access_token(token)
+        assert result is not None
+
+    async def test_token_accepted_with_identifier_uri_audience(
+        self, memory_storage: MemoryStore
+    ):
+        """Azure AD v1 tokens use the identifier_uri as aud — must be accepted."""
+        key_pair = RSAKeyPair.generate()
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="my-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert isinstance(provider._token_validator, JWTVerifier)
+        verifier = provider._token_validator
+        verifier.public_key = key_pair.public_key
+        verifier.jwks_uri = None
+
+        token = key_pair.create_token(
+            subject="test-user",
+            issuer="https://login.microsoftonline.com/my-tenant/v2.0",
+            audience="api://my-api",
+            additional_claims={"scp": "read"},
+        )
+        result = await verifier.load_access_token(token)
+        assert result is not None
+
+    async def test_token_rejected_with_wrong_audience(
+        self, memory_storage: MemoryStore
+    ):
+        """Tokens for a different application must be rejected."""
+        key_pair = RSAKeyPair.generate()
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="my-tenant",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert isinstance(provider._token_validator, JWTVerifier)
+        verifier = provider._token_validator
+        verifier.public_key = key_pair.public_key
+        verifier.jwks_uri = None
+
+        token = key_pair.create_token(
+            subject="test-user",
+            issuer="https://login.microsoftonline.com/my-tenant/v2.0",
+            audience="wrong-app-id",
+            additional_claims={"scp": "read"},
+        )
+        result = await verifier.load_access_token(token)
+        assert result is None
+
+    async def test_authorize_filters_resource_and_stores_unprefixed_scopes(
+        self, memory_storage: MemoryStore
+    ):
+        """authorize() should drop resource parameter and store unprefixed scopes for MCP clients."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="common",
+            identifier_uri="api://my-api",
+            required_scopes=["read", "write"],
+            base_url="https://srv.example",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        await provider.register_client(
+            OAuthClientInformationFull(
+                client_id="dummy",
+                client_secret="secret",
+                redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+            )
+        )
+
+        client = OAuthClientInformationFull(
+            client_id="dummy",
+            client_secret="secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+            scopes=[
+                "read",
+                "write",
+            ],  # Client sends unprefixed scopes (from PRM which advertises unprefixed)
+            state="abc",
+            code_challenge="xyz",
+            resource="https://should.be.ignored",
+        )
+
+        url = await provider.authorize(client, params)
+
+        # Extract transaction ID from consent redirect
+        parsed = urlparse(url)
+        qs = parse_qs(parsed.query)
+        assert "txn_id" in qs, "Should redirect to consent page with transaction ID"
+        txn_id = qs["txn_id"][0]
+
+        # Verify transaction stores UNPREFIXED scopes for MCP clients
+        transaction = await provider._transaction_store.get(key=txn_id)
+        assert transaction is not None
+        assert "read" in transaction.scopes
+        assert "write" in transaction.scopes
+        # Azure provider filters resource parameter (not stored in transaction)
+        assert transaction.resource is None
+
+        # Verify the upstream Azure URL will have PREFIXED scopes
+        upstream_url = provider._build_upstream_authorize_url(
+            txn_id, transaction.model_dump()
+        )
+        assert (
+            "api%3A%2F%2Fmy-api%2Fread" in upstream_url
+            or "api://my-api/read" in upstream_url
+        )
+        assert (
+            "api%3A%2F%2Fmy-api%2Fwrite" in upstream_url
+            or "api://my-api/write" in upstream_url
+        )
+
+    async def test_authorize_appends_additional_scopes(
+        self, memory_storage: MemoryStore
+    ):
+        """authorize() should append additional_authorize_scopes to the authorization request."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="common",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            base_url="https://srv.example",
+            additional_authorize_scopes=["Mail.Read", "User.Read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        await provider.register_client(
+            OAuthClientInformationFull(
+                client_id="dummy",
+                client_secret="secret",
+                redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+            )
+        )
+
+        client = OAuthClientInformationFull(
+            client_id="dummy",
+            client_secret="secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+            scopes=["read"],  # Client sends unprefixed scopes
+            state="abc",
+            code_challenge="xyz",
+        )
+
+        url = await provider.authorize(client, params)
+
+        # Extract transaction ID from consent redirect
+        parsed = urlparse(url)
+        qs = parse_qs(parsed.query)
+        assert "txn_id" in qs, "Should redirect to consent page with transaction ID"
+        txn_id = qs["txn_id"][0]
+
+        # Verify transaction stores ONLY MCP scopes (unprefixed)
+        # additional_authorize_scopes are NOT stored in transaction
+        transaction = await provider._transaction_store.get(key=txn_id)
+        assert transaction is not None
+        assert "read" in transaction.scopes
+        assert "Mail.Read" not in transaction.scopes  # Not in transaction
+        assert "User.Read" not in transaction.scopes  # Not in transaction
+
+        # Verify upstream URL includes both MCP scopes (prefixed) AND additional Graph scopes
+        upstream_url = provider._build_upstream_authorize_url(
+            txn_id, transaction.model_dump()
+        )
+        assert (
+            "api%3A%2F%2Fmy-api%2Fread" in upstream_url
+            or "api://my-api/read" in upstream_url
+        )
+        assert "Mail.Read" in upstream_url
+        assert "User.Read" in upstream_url
+
+    def test_prepare_scopes_for_token_exchange_falls_back_to_required_scopes(
+        self, memory_storage: MemoryStore
+    ):
+        """Clients may omit scope; Azure still needs an API scope with offline_access."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        result = provider._prepare_scopes_for_token_exchange([])
+
+        assert result == ["api://my-api/read", "offline_access"]
+
+    def test_base_authority_defaults_to_public_cloud(self, memory_storage: MemoryStore):
+        """Test that base_authority defaults to login.microsoftonline.com."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert (
+            provider._upstream_authorization_endpoint
+            == "https://login.microsoftonline.com/test-tenant/oauth2/v2.0/authorize"
+        )
+        assert (
+            provider._upstream_token_endpoint
+            == "https://login.microsoftonline.com/test-tenant/oauth2/v2.0/token"
+        )
+        assert isinstance(provider._token_validator, JWTVerifier)
+        assert (
+            provider._token_validator.issuer
+            == "https://login.microsoftonline.com/test-tenant/v2.0"
+        )
+        assert (
+            provider._token_validator.jwks_uri
+            == "https://login.microsoftonline.com/test-tenant/discovery/v2.0/keys"
+        )
+
+    def test_base_authority_azure_government(self, memory_storage: MemoryStore):
+        """Test Azure Government endpoints with login.microsoftonline.us."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="gov-tenant-id",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            base_authority="login.microsoftonline.us",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert (
+            provider._upstream_authorization_endpoint
+            == "https://login.microsoftonline.us/gov-tenant-id/oauth2/v2.0/authorize"
+        )
+        assert (
+            provider._upstream_token_endpoint
+            == "https://login.microsoftonline.us/gov-tenant-id/oauth2/v2.0/token"
+        )
+        assert isinstance(provider._token_validator, JWTVerifier)
+        assert (
+            provider._token_validator.issuer
+            == "https://login.microsoftonline.us/gov-tenant-id/v2.0"
+        )
+        assert (
+            provider._token_validator.jwks_uri
+            == "https://login.microsoftonline.us/gov-tenant-id/discovery/v2.0/keys"
+        )
+
+    def test_base_authority_from_parameter(self, memory_storage: MemoryStore):
+        """Test that base_authority can be set via parameter."""
+        provider = AzureProvider(
+            client_id="env-client-id",
+            client_secret="env-secret",
+            tenant_id="env-tenant-id",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            base_authority="login.microsoftonline.us",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert (
+            provider._upstream_authorization_endpoint
+            == "https://login.microsoftonline.us/env-tenant-id/oauth2/v2.0/authorize"
+        )
+        assert (
+            provider._upstream_token_endpoint
+            == "https://login.microsoftonline.us/env-tenant-id/oauth2/v2.0/token"
+        )
+        assert isinstance(provider._token_validator, JWTVerifier)
+        assert (
+            provider._token_validator.issuer
+            == "https://login.microsoftonline.us/env-tenant-id/v2.0"
+        )
+        assert (
+            provider._token_validator.jwks_uri
+            == "https://login.microsoftonline.us/env-tenant-id/discovery/v2.0/keys"
+        )
+
+    def test_base_authority_with_special_tenant_values(
+        self, memory_storage: MemoryStore
+    ):
+        """Test that base_authority works with special tenant values like 'organizations'."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="organizations",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            base_authority="login.microsoftonline.us",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        parsed = urlparse(provider._upstream_authorization_endpoint)
+        assert parsed.netloc == "login.microsoftonline.us"
+        assert "/organizations/" in parsed.path
+
+    def test_prepare_scopes_for_upstream_refresh_basic_prefixing(
+        self, memory_storage: MemoryStore
+    ):
+        """Test that unprefixed scopes are correctly prefixed for Azure token refresh."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read", "write"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Unprefixed scopes from storage should be prefixed
+        result = provider._prepare_scopes_for_upstream_refresh(["read", "write"])
+
+        assert "api://my-api/read" in result
+        assert "api://my-api/write" in result
+        assert "offline_access" in result  # Auto-included for refresh tokens
+        assert len(result) == 3
+
+    def test_prepare_scopes_for_upstream_refresh_already_prefixed(
+        self, memory_storage: MemoryStore
+    ):
+        """Test that already-prefixed scopes remain unchanged."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Already prefixed scopes should pass through unchanged
+        result = provider._prepare_scopes_for_upstream_refresh(
+            ["api://my-api/read", "api://other-api/admin"]
+        )
+
+        assert "api://my-api/read" in result
+        assert "api://other-api/admin" in result
+        assert "offline_access" in result  # Auto-included for refresh tokens
+        assert len(result) == 3
+
+    def test_prepare_scopes_for_upstream_refresh_with_additional_scopes(
+        self, memory_storage: MemoryStore
+    ):
+        """Test that only OIDC scopes from additional_authorize_scopes are added.
+
+        Azure only allows ONE resource per token request (AADSTS28000), so
+        non-OIDC scopes like User.Read are excluded from refresh requests.
+        """
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            additional_authorize_scopes=[
+                "User.Read",  # Not OIDC - excluded
+                "openid",
+                "profile",
+                "offline_access",
+            ],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Base scopes should be prefixed, only OIDC scopes appended
+        result = provider._prepare_scopes_for_upstream_refresh(["read", "write"])
+
+        assert "api://my-api/read" in result
+        assert "api://my-api/write" in result
+        assert "User.Read" not in result  # Not OIDC, excluded
+        assert "openid" in result
+        assert "profile" in result
+        assert "offline_access" in result
+        assert len(result) == 5
+
+    def test_prepare_scopes_for_upstream_refresh_filters_duplicate_additional_scopes(
+        self,
+        memory_storage: MemoryStore,
+    ):
+        """Test that accidentally stored additional_authorize_scopes are filtered out."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            additional_authorize_scopes=["User.Read", "openid"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # If additional scopes were accidentally stored, they should be filtered
+        # User.Read is not OIDC so won't be added
+        result = provider._prepare_scopes_for_upstream_refresh(
+            ["read", "User.Read", "openid"]
+        )
+
+        # Should have: api://my-api/read (prefixed) + openid + offline_access (OIDC scopes)
+        # User.Read is filtered from storage AND not added (not OIDC)
+        assert "api://my-api/read" in result
+        assert "User.Read" not in result  # Not OIDC
+        assert result.count("openid") == 1
+        assert "offline_access" in result  # Auto-included and is OIDC
+        assert len(result) == 3
+
+    def test_prepare_scopes_for_upstream_refresh_mixed_scopes(
+        self, memory_storage: MemoryStore
+    ):
+        """Test mixed scenario with both prefixed and unprefixed scopes."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            additional_authorize_scopes=["openid"],  # OIDC scope
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Mix of prefixed and unprefixed scopes
+        result = provider._prepare_scopes_for_upstream_refresh(
+            ["read", "api://other-api/admin", "write"]
+        )
+
+        assert "api://my-api/read" in result
+        assert "api://other-api/admin" in result  # Already prefixed, unchanged
+        assert "api://my-api/write" in result
+        assert "openid" in result
+        assert "offline_access" in result  # Auto-included
+        assert len(result) == 5
+
+    def test_prepare_scopes_for_upstream_refresh_scope_with_slash(
+        self, memory_storage: MemoryStore
+    ):
+        """Test that scopes containing '/' are not prefixed."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Scopes with "/" should not be prefixed (already fully qualified)
+        result = provider._prepare_scopes_for_upstream_refresh(
+            ["read", "https://graph.microsoft.com/.default"]
+        )
+
+        assert "api://my-api/read" in result
+        assert (
+            "https://graph.microsoft.com/.default" in result
+        )  # Not prefixed (contains ://)
+
+    def test_prepare_scopes_for_upstream_refresh_empty_scopes_falls_back_to_required(
+        self, memory_storage: MemoryStore
+    ):
+        """Clients may omit scope; refresh should still request the configured API scope."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            additional_authorize_scopes=["User.Read", "openid"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        result = provider._prepare_scopes_for_upstream_refresh([])
+
+        assert "api://my-api/read" in result
+        assert "User.Read" not in result  # Not OIDC
+        assert "openid" in result
+        assert "offline_access" in result  # Auto-included
+        assert len(result) == 3
+
+    def test_prepare_scopes_for_upstream_refresh_no_additional_scopes(
+        self, memory_storage: MemoryStore
+    ):
+        """Test behavior when no additional_authorize_scopes are configured."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Should prefix base scopes, plus auto-added offline_access
+        result = provider._prepare_scopes_for_upstream_refresh(["read", "write"])
+
+        assert "api://my-api/read" in result
+        assert "api://my-api/write" in result
+        assert "offline_access" in result  # Auto-included
+        assert len(result) == 3
+
+    def test_prepare_scopes_for_upstream_refresh_deduplicates_scopes(
+        self, memory_storage: MemoryStore
+    ):
+        """Test that duplicate scopes are deduplicated while preserving order."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            additional_authorize_scopes=["openid", "profile"],  # OIDC scopes only
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Test with duplicate base scopes
+        result = provider._prepare_scopes_for_upstream_refresh(
+            ["read", "write", "read", "openid"]
+        )
+
+        # Should have deduplicated results in order (OIDC scopes added, offline_access auto-added)
+        assert result == [
+            "api://my-api/read",
+            "api://my-api/write",
+            "openid",
+            "profile",
+            "offline_access",
+        ]
+        assert len(result) == 5
+
+    def test_prepare_scopes_for_upstream_refresh_deduplicates_prefixed_variants(
+        self, memory_storage: MemoryStore
+    ):
+        """Test that both prefixed and unprefixed variants are deduplicated."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Test with both prefixed and unprefixed variants of same scope
+        result = provider._prepare_scopes_for_upstream_refresh(
+            ["read", "api://my-api/read", "write"]
+        )
+
+        # Should deduplicate - first occurrence wins (api://my-api/read from "read")
+        assert "api://my-api/read" in result
+        assert "api://my-api/write" in result
+        assert "offline_access" in result  # Auto-included
+        # Should have 3 items (read deduplicated, plus offline_access)
+        assert len(result) == 3
+        assert result.count("api://my-api/read") == 1
+
+
+class TestAzureProviderTokenIssuer:
+    """Tests for the token_issuer parameter on AzureProvider."""
+
+    def test_default_issuer_is_derived(self, memory_storage: MemoryStore):
+        """Without token_issuer, the issuer is derived from base_authority/tenant_id."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="my-tenant",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert isinstance(provider._token_validator, JWTVerifier)
+        assert (
+            provider._token_validator.issuer
+            == "https://login.microsoftonline.com/my-tenant/v2.0"
+        )
+
+    def test_explicit_token_issuer_is_used(self, memory_storage: MemoryStore):
+        """An explicit token_issuer string is passed to the verifier."""
+        custom_issuer = "https://custom.issuer.com/v2.0"
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="my-tenant",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            token_issuer=custom_issuer,
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert isinstance(provider._token_validator, JWTVerifier)
+        assert provider._token_validator.issuer == custom_issuer
+
+    async def test_explicit_issuer_enforced(self, memory_storage: MemoryStore):
+        """With an explicit token_issuer, wrong issuers are rejected."""
+        key_pair = RSAKeyPair.generate()
+        expected = "https://expected.issuer.com/v2.0"
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="my-tenant",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            token_issuer=expected,
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert isinstance(provider._token_validator, JWTVerifier)
+        verifier = provider._token_validator
+        verifier.public_key = key_pair.public_key
+        verifier.jwks_uri = None
+
+        good_token = key_pair.create_token(
+            subject="test-user",
+            issuer=expected,
+            audience="test_client",
+            additional_claims={"scp": "read"},
+        )
+        assert await verifier.load_access_token(good_token) is not None
+
+        bad_token = key_pair.create_token(
+            subject="test-user",
+            issuer="https://wrong.issuer.com/v2.0",
+            audience="test_client",
+            additional_claims={"scp": "read"},
+        )
+        assert await verifier.load_access_token(bad_token) is None
+
+
+class TestAzureProviderFromB2C:
+    """Tests for the AzureProvider.from_b2c() classmethod factory."""
+
+    def test_b2c_endpoints_derived_correctly(self, memory_storage: MemoryStore):
+        """from_b2c() produces correct B2C authority and tenant path."""
+        provider = AzureProvider.from_b2c(
+            tenant_name="mytenant",
+            policy_name="B2C_1_susi",
+            client_id="client-id",
+            client_secret="secret",
+            required_scopes=["mcp-access"],
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert provider._upstream_authorization_endpoint == (
+            "https://mytenant.b2clogin.com"
+            "/mytenant.onmicrosoft.com/B2C_1_susi"
+            "/oauth2/v2.0/authorize"
+        )
+        assert provider._upstream_token_endpoint == (
+            "https://mytenant.b2clogin.com"
+            "/mytenant.onmicrosoft.com/B2C_1_susi"
+            "/oauth2/v2.0/token"
+        )
+
+    def test_b2c_identifier_uri_uses_https(self, memory_storage: MemoryStore):
+        """from_b2c() sets identifier_uri with https:// scheme, not api://."""
+        provider = AzureProvider.from_b2c(
+            tenant_name="mytenant",
+            policy_name="B2C_1_susi",
+            client_id="00000000-0000-0000-0000-000000000001",
+            client_secret="secret",
+            required_scopes=["mcp-access"],
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert provider.identifier_uri == (
+            "https://mytenant.onmicrosoft.com/00000000-0000-0000-0000-000000000001"
+        )
+        assert provider.identifier_uri.startswith("https://")
+        assert not provider.identifier_uri.startswith("api://")
+
+    def test_b2c_issuer_disabled_by_default(self, memory_storage: MemoryStore):
+        """from_b2c() disables issuer validation by default (token_issuer=None)."""
+        provider = AzureProvider.from_b2c(
+            tenant_name="mytenant",
+            policy_name="B2C_1_susi",
+            client_id="client-id",
+            client_secret="secret",
+            required_scopes=["mcp-access"],
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert isinstance(provider._token_validator, JWTVerifier)
+        assert provider._token_validator.issuer is None
+
+    def test_b2c_explicit_token_issuer(self, memory_storage: MemoryStore):
+        """from_b2c() forwards an explicit token_issuer to the verifier."""
+        explicit_issuer = (
+            "https://mytenant.b2clogin.com/11111111-2222-3333-4444-555555555555/v2.0/"
+        )
+        provider = AzureProvider.from_b2c(
+            tenant_name="mytenant",
+            policy_name="B2C_1_susi",
+            client_id="client-id",
+            client_secret="secret",
+            required_scopes=["mcp-access"],
+            base_url="https://myserver.com",
+            token_issuer=explicit_issuer,
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert isinstance(provider._token_validator, JWTVerifier)
+        assert provider._token_validator.issuer == explicit_issuer
+
+    def test_b2c_custom_domain(self, memory_storage: MemoryStore):
+        """from_b2c() uses custom_domain in place of {tenant}.b2clogin.com."""
+        provider = AzureProvider.from_b2c(
+            tenant_name="mytenant",
+            policy_name="B2C_1_susi",
+            client_id="client-id",
+            client_secret="secret",
+            required_scopes=["mcp-access"],
+            base_url="https://myserver.com",
+            custom_domain="auth.mycompany.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert "auth.mycompany.com" in provider._upstream_authorization_endpoint
+        assert "auth.mycompany.com" in provider._upstream_token_endpoint
+        assert "mytenant.b2clogin.com" not in provider._upstream_authorization_endpoint
+
+    def test_b2c_custom_domain_with_scheme_normalized(
+        self, memory_storage: MemoryStore
+    ):
+        """from_b2c() strips scheme and trailing slash from custom_domain."""
+        provider = AzureProvider.from_b2c(
+            tenant_name="mytenant",
+            policy_name="B2C_1_susi",
+            client_id="client-id",
+            client_secret="secret",
+            required_scopes=["mcp-access"],
+            base_url="https://myserver.com",
+            custom_domain="https://auth.mycompany.com/",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert "auth.mycompany.com" in provider._upstream_authorization_endpoint
+        assert "https://https://" not in provider._upstream_authorization_endpoint
+
+    def test_b2c_custom_identifier_uri(self, memory_storage: MemoryStore):
+        """from_b2c() respects an explicit identifier_uri override."""
+        custom_uri = "https://mycompany.com/api/mcp"
+        provider = AzureProvider.from_b2c(
+            tenant_name="mytenant",
+            policy_name="B2C_1_susi",
+            client_id="client-id",
+            client_secret="secret",
+            required_scopes=["mcp-access"],
+            base_url="https://myserver.com",
+            identifier_uri=custom_uri,
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert provider.identifier_uri == custom_uri
+
+    def test_b2c_scope_prefix_uses_https(self, memory_storage: MemoryStore):
+        """from_b2c() scopes are prefixed with the https:// identifier URI."""
+        provider = AzureProvider.from_b2c(
+            tenant_name="mytenant",
+            policy_name="B2C_1_susi",
+            client_id="aabbccdd",
+            client_secret="secret",
+            required_scopes=["mcp-access"],
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        result = provider._prefix_scopes_for_azure(["mcp-access"])
+        assert result == ["https://mytenant.onmicrosoft.com/aabbccdd/mcp-access"]
+
+    def test_b2c_returns_azure_provider_instance(self, memory_storage: MemoryStore):
+        """from_b2c() returns an AzureProvider, not a subclass."""
+        provider = AzureProvider.from_b2c(
+            tenant_name="mytenant",
+            policy_name="B2C_1_susi",
+            client_id="client-id",
+            client_secret="secret",
+            required_scopes=["mcp-access"],
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert type(provider) is AzureProvider
+
+    def test_b2c_custom_policy_name(self, memory_storage: MemoryStore):
+        """from_b2c() accepts custom policy names (B2C_1A_*)."""
+        provider = AzureProvider.from_b2c(
+            tenant_name="mytenant",
+            policy_name="B2C_1A_SIGNUP_SIGNIN",
+            client_id="client-id",
+            client_secret="secret",
+            required_scopes=["mcp-access"],
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert "B2C_1A_SIGNUP_SIGNIN" in provider._upstream_authorization_endpoint
+        assert "B2C_1A_SIGNUP_SIGNIN" in provider._upstream_token_endpoint
+
+    async def test_b2c_token_accepted_with_any_issuer(
+        self, memory_storage: MemoryStore
+    ):
+        """B2C provider (issuer=None) accepts tokens from any issuer."""
+        key_pair = RSAKeyPair.generate()
+        provider = AzureProvider.from_b2c(
+            tenant_name="mytenant",
+            policy_name="B2C_1_susi",
+            client_id="my-client-id",
+            client_secret="secret",
+            required_scopes=["mcp-access"],
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert isinstance(provider._token_validator, JWTVerifier)
+        verifier = provider._token_validator
+        verifier.public_key = key_pair.public_key
+        verifier.jwks_uri = None
+
+        token = key_pair.create_token(
+            subject="test-user",
+            issuer="https://mytenant.b2clogin.com/11111111-guid/v2.0/",
+            audience="my-client-id",
+            additional_claims={"scp": "mcp-access"},
+        )
+        result = await verifier.load_access_token(token)
+        assert result is not None
+
+    async def test_b2c_token_rejected_with_wrong_audience(
+        self, memory_storage: MemoryStore
+    ):
+        """B2C provider still rejects tokens with wrong audience."""
+        key_pair = RSAKeyPair.generate()
+        provider = AzureProvider.from_b2c(
+            tenant_name="mytenant",
+            policy_name="B2C_1_susi",
+            client_id="my-client-id",
+            client_secret="secret",
+            required_scopes=["mcp-access"],
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert isinstance(provider._token_validator, JWTVerifier)
+        verifier = provider._token_validator
+        verifier.public_key = key_pair.public_key
+        verifier.jwks_uri = None
+
+        token = key_pair.create_token(
+            subject="test-user",
+            issuer="https://mytenant.b2clogin.com/11111111-guid/v2.0/",
+            audience="wrong-app-id",
+            additional_claims={"scp": "mcp-access"},
+        )
+        result = await verifier.load_access_token(token)
+        assert result is None
+
+    async def test_b2c_obo_raises_not_implemented(self, memory_storage: MemoryStore):
+        """from_b2c() providers must reject OBO calls with NotImplementedError."""
+        provider = AzureProvider.from_b2c(
+            tenant_name="mytenant",
+            policy_name="B2C_1_susi",
+            client_id="client-id",
+            client_secret="secret",
+            required_scopes=["mcp-access"],
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        with pytest.raises(NotImplementedError, match="OBO"):
+            await provider.get_obo_credential(user_assertion="fake-token")
+
+
+class TestAzureProviderFromB2CInputValidation:
+    """Input validation for from_b2c() parameters."""
+
+    @pytest.mark.parametrize(
+        "tenant_name",
+        [
+            "mytenant.onmicrosoft.com",
+            "my.onmicrosoft.com.tenant",
+        ],
+    )
+    def test_tenant_name_with_onmicrosoft_suffix_rejected(
+        self, memory_storage: MemoryStore, tenant_name: str
+    ):
+        with pytest.raises(ValueError, match="onmicrosoft.com"):
+            AzureProvider.from_b2c(
+                tenant_name=tenant_name,
+                policy_name="B2C_1_susi",
+                client_id="client-id",
+                client_secret="secret",
+                required_scopes=["mcp-access"],
+                base_url="https://myserver.com",
+                jwt_signing_key="test-secret",
+                client_storage=memory_storage,
+            )
+
+
+class TestAzureScopeRoundTrip:
+    """Azure echoes ``api://{client_id}/<scope>`` back in its token response's
+    ``scope`` field, but MCP clients request and recognize the unprefixed form
+    advertised on ``/.well-known/oauth-authorization-server``. Without
+    translation, strict clients (e.g. ChatGPT) compare requested vs. granted
+    and surface a "permissions not granted" warning even though the token is
+    fully valid.
+    """
+
+    CLIENT_ID = "dummy"
+    REDIRECT_URI = "http://localhost:12345/callback"
+
+    async def _register_and_store_code(
+        self,
+        provider: AzureProvider,
+        *,
+        code: str,
+        idp_tokens: dict,
+    ) -> tuple[OAuthClientInformationFull, AuthorizationCode]:
+        # set_mcp_path() is what initializes the JWT issuer used during the
+        # token exchange. Normally get_routes() does this; for a unit test we
+        # call it directly.
+        provider.set_mcp_path("/mcp")
+
+        client = OAuthClientInformationFull(
+            client_id=self.CLIENT_ID,
+            client_secret="secret",
+            redirect_uris=[AnyUrl(self.REDIRECT_URI)],
+        )
+        await provider.register_client(client)
+
+        await provider._code_store.put(
+            key=code,
+            value=ClientCode(
+                code=code,
+                client_id=self.CLIENT_ID,
+                redirect_uri=self.REDIRECT_URI,
+                code_challenge="",
+                code_challenge_method="S256",
+                scopes=["read", "write"],
+                idp_tokens=idp_tokens,
+                expires_at=time.time() + 300,
+                created_at=time.time(),
+            ),
+        )
+
+        auth_code = AuthorizationCode(
+            code=code,
+            scopes=["read", "write"],
+            expires_at=time.time() + 300,
+            client_id=self.CLIENT_ID,
+            code_challenge="",
+            redirect_uri=AnyUrl(self.REDIRECT_URI),
+            redirect_uri_provided_explicitly=True,
+        )
+        return client, auth_code
+
+    async def test_exchange_authorization_code_unprefixes_echoed_scopes(
+        self, memory_storage: MemoryStore
+    ):
+        """OAuthToken.scope returned to the client must use the unprefixed form
+        advertised on /.well-known, not the prefixed form Azure echoes back.
+        """
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="common",
+            identifier_uri="api://my-api",
+            required_scopes=["read", "write"],
+            base_url="https://srv.example",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        client, auth_code = await self._register_and_store_code(
+            provider,
+            code="test-auth-code",
+            idp_tokens={
+                "access_token": "upstream-access-token",
+                "refresh_token": "upstream-refresh-token",
+                "expires_in": 3600,
+                "token_type": "Bearer",
+                # This is what Azure actually returns — the prefixed form.
+                "scope": "api://my-api/read api://my-api/write",
+            },
+        )
+
+        result = await provider.exchange_authorization_code(client, auth_code)
+
+        assert result.scope is not None
+        granted = set(result.scope.split())
+        assert granted == {"read", "write"}, (
+            f"Expected unprefixed scopes echoed to client, got {result.scope!r}"
+        )
+
+    async def test_exchange_authorization_code_preserves_external_scopes(
+        self, memory_storage: MemoryStore
+    ):
+        """External resource URIs (e.g. Microsoft Graph) and OIDC scopes don't
+        carry the identifier_uri prefix, so the translation must leave them
+        alone."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="common",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            base_url="https://srv.example",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        client, auth_code = await self._register_and_store_code(
+            provider,
+            code="test-auth-code-mixed",
+            idp_tokens={
+                "access_token": "upstream-access-token",
+                "refresh_token": "upstream-refresh-token",
+                "expires_in": 3600,
+                "token_type": "Bearer",
+                "scope": (
+                    "api://my-api/read https://graph.microsoft.com/User.Read openid"
+                ),
+            },
+        )
+
+        result = await provider.exchange_authorization_code(client, auth_code)
+
+        assert result.scope is not None
+        granted = set(result.scope.split())
+        assert granted == {
+            "read",
+            "https://graph.microsoft.com/User.Read",
+            "openid",
+        }
+
+    async def test_exchange_refresh_token_unprefixes_echoed_scopes(
+        self, memory_storage: MemoryStore
+    ):
+        """The same translation must apply on refresh — otherwise the cosmetic
+        scope mismatch reappears after the first refresh."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="common",
+            identifier_uri="api://my-api",
+            required_scopes=["read", "write"],
+            base_url="https://srv.example",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        with patch(
+            "fastmcp.server.auth.oauth_proxy.proxy.AsyncOAuth2Client"
+        ) as MockClient:
+            mock_client = AsyncMock()
+            mock_client.fetch_token = AsyncMock(
+                return_value={
+                    "access_token": "upstream-access-token",
+                    "refresh_token": "upstream-refresh-token",
+                    "expires_in": 3600,
+                    "token_type": "Bearer",
+                    "scope": "api://my-api/read api://my-api/write",
+                }
+            )
+            MockClient.return_value = mock_client
+
+            client, auth_code = await self._register_and_store_code(
+                provider,
+                code="test-auth-code-refresh",
+                idp_tokens={
+                    "access_token": "upstream-access-token",
+                    "refresh_token": "upstream-refresh-token",
+                    "expires_in": 3600,
+                    "token_type": "Bearer",
+                    "scope": "api://my-api/read api://my-api/write",
+                },
+            )
+            initial = await provider.exchange_authorization_code(client, auth_code)
+
+            assert initial.refresh_token is not None
+            fastmcp_refresh = RefreshToken(
+                token=initial.refresh_token,
+                client_id=self.CLIENT_ID,
+                scopes=["read", "write"],
+                expires_at=None,
+            )
+
+            # Simulate Azure echoing prefixed scopes on the refresh response too.
+            mock_client.refresh_token = AsyncMock(
+                return_value={
+                    "access_token": "rotated-upstream-token",
+                    "refresh_token": "rotated-upstream-refresh",
+                    "expires_in": 3600,
+                    "token_type": "Bearer",
+                    "scope": "api://my-api/read api://my-api/write",
+                }
+            )
+
+            refreshed = await provider.exchange_refresh_token(
+                client, fastmcp_refresh, ["read", "write"]
+            )
+
+        assert refreshed.scope is not None
+        granted = set(refreshed.scope.split())
+        assert granted == {"read", "write"}, (
+            f"Expected unprefixed scopes after refresh, got {refreshed.scope!r}"
+        )
+
+    async def test_transparent_refresh_unprefixes_echoed_scopes(
+        self, memory_storage: MemoryStore
+    ):
+        """Transparent refresh stores client-facing scopes too.
+
+        Otherwise the scope mismatch can reappear when an expired upstream token
+        is refreshed during access-token validation.
+        """
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="common",
+            identifier_uri="api://my-api",
+            required_scopes=["read", "write"],
+            base_url="https://srv.example",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        upstream_token_set = UpstreamTokenSet(
+            upstream_token_id="upstream-token-id",
+            access_token="expired-upstream-token",
+            refresh_token="refresh-token",
+            refresh_token_expires_at=time.time() + 3600,
+            expires_at=time.time() - 60,
+            token_type="Bearer",
+            scope="read write",
+            client_id=self.CLIENT_ID,
+            created_at=time.time() - 3600,
+        )
+
+        mock_oauth_client = AsyncMock()
+        mock_oauth_client.refresh_token = AsyncMock(
+            return_value={
+                "access_token": "rotated-upstream-token",
+                "refresh_token": "rotated-refresh-token",
+                "expires_in": 3600,
+                "token_type": "Bearer",
+                "scope": "api://my-api/read api://my-api/write",
+            }
+        )
+
+        with patch.object(
+            provider, "_create_upstream_oauth_client", return_value=mock_oauth_client
+        ):
+            refreshed = await provider._try_transparent_refresh(upstream_token_set)
+
+        assert refreshed.scope == "read write"
+
+    def test_translate_scopes_from_idp_is_inverse_of_prefix(
+        self, memory_storage: MemoryStore
+    ):
+        """The new hook should be the exact inverse of _prefix_scopes_for_azure
+        for any input the provider would have sent upstream."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="common",
+            identifier_uri="api://my-api",
+            required_scopes=["read", "write"],
+            base_url="https://srv.example",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        original = ["read", "write", "openid", "https://graph.microsoft.com/User.Read"]
+        round_tripped = provider._translate_scopes_from_idp(
+            provider._prefix_scopes_for_azure(original)
+        )
+        assert round_tripped == original
diff --git a/tests/server/auth/providers/test_azure_scopes.py b/tests/server/auth/providers/test_azure_scopes.py
new file mode 100644
index 0000000..5f1bb6b
--- /dev/null
+++ b/tests/server/auth/providers/test_azure_scopes.py
@@ -0,0 +1,839 @@
+"""Tests for Azure provider scope handling, JWT verifier, and OBO integration."""
+
+import pytest
+from key_value.aio.stores.memory import MemoryStore
+
+from fastmcp.server.auth.auth import MultiAuth
+from fastmcp.server.auth.providers.azure import (
+    OIDC_SCOPES,
+    AzureJWTVerifier,
+    AzureProvider,
+    _find_azure_provider,
+)
+from fastmcp.server.auth.providers.jwt import RSAKeyPair, StaticTokenVerifier
+
+# Import the optional azure-identity SDK once, at collection time. The OBO
+# tests mock it via patch("azure.identity.aio.OnBehalfOfCredential"), but the
+# provider imports it lazily — so without this the heavy SDK import lands
+# inside the first OBO test's 5s pytest-timeout window and flakes on cold
+# Windows runners (#4175). importorskip also skips cleanly if the optional
+# `azure` extra is absent, instead of hard-failing at runtime.
+pytest.importorskip("azure.identity.aio")
+
+
+@pytest.fixture
+def memory_storage() -> MemoryStore:
+    """Provide a MemoryStore for tests to avoid SQLite initialization on Windows."""
+    return MemoryStore()
+
+
+class TestOIDCScopeHandling:
+    """Tests for OIDC scope handling in Azure provider.
+
+    Azure access tokens do NOT include OIDC scopes (openid, profile, email,
+    offline_access) in the `scp` claim - they're only used during authorization.
+    These tests verify that:
+    1. OIDC scopes are never prefixed with identifier_uri
+    2. OIDC scopes are filtered from token validation
+    3. OIDC scopes are still advertised to clients via valid_scopes
+    """
+
+    def test_oidc_scopes_constant(self, memory_storage: MemoryStore):
+        """Verify OIDC_SCOPES contains the standard OIDC scopes."""
+        assert OIDC_SCOPES == {"openid", "profile", "email", "offline_access"}
+
+    def test_prefix_scopes_does_not_prefix_oidc_scopes(
+        self, memory_storage: MemoryStore
+    ):
+        """Test that _prefix_scopes_for_azure never prefixes OIDC scopes."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # All OIDC scopes should pass through unchanged
+        result = provider._prefix_scopes_for_azure(
+            ["openid", "profile", "email", "offline_access"]
+        )
+
+        assert result == ["openid", "profile", "email", "offline_access"]
+
+    def test_prefix_scopes_mixed_oidc_and_custom(self, memory_storage: MemoryStore):
+        """Test prefixing with a mix of OIDC and custom scopes."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        result = provider._prefix_scopes_for_azure(
+            ["read", "openid", "write", "profile"]
+        )
+
+        # Custom scopes should be prefixed, OIDC scopes should not
+        assert "api://my-api/read" in result
+        assert "api://my-api/write" in result
+        assert "openid" in result
+        assert "profile" in result
+        # Verify OIDC scopes are NOT prefixed
+        assert "api://my-api/openid" not in result
+        assert "api://my-api/profile" not in result
+
+    def test_prefix_scopes_dot_notation_gets_prefixed(
+        self, memory_storage: MemoryStore
+    ):
+        """Test that dot-notation scopes get prefixed (use additional_authorize_scopes for Graph)."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Dot-notation scopes ARE prefixed - use additional_authorize_scopes for Graph
+        # or fully-qualified format like https://graph.microsoft.com/User.Read
+        result = provider._prefix_scopes_for_azure(["my.scope", "admin.read"])
+
+        assert result == ["api://my-api/my.scope", "api://my-api/admin.read"]
+
+    def test_prefix_scopes_fully_qualified_graph_not_prefixed(
+        self, memory_storage: MemoryStore
+    ):
+        """Test that fully-qualified Graph scopes are not prefixed."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        result = provider._prefix_scopes_for_azure(
+            [
+                "https://graph.microsoft.com/User.Read",
+                "https://graph.microsoft.com/Mail.Send",
+            ]
+        )
+
+        # Fully-qualified URIs pass through unchanged
+        assert result == [
+            "https://graph.microsoft.com/User.Read",
+            "https://graph.microsoft.com/Mail.Send",
+        ]
+
+    def test_required_scopes_with_oidc_filters_validation(
+        self, memory_storage: MemoryStore
+    ):
+        """Test that OIDC scopes in required_scopes are filtered from token validation."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read", "openid", "profile"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Token validator should only require non-OIDC scopes
+        assert provider._token_validator.required_scopes == ["read"]
+
+    def test_required_scopes_all_oidc_raises_value_error(
+        self, memory_storage: MemoryStore
+    ):
+        """Test that providing only OIDC scopes raises ValueError."""
+        with pytest.raises(ValueError, match="at least one non-OIDC scope"):
+            AzureProvider(
+                client_id="test_client",
+                client_secret="test_secret",
+                tenant_id="test-tenant",
+                base_url="https://myserver.com",
+                identifier_uri="api://my-api",
+                required_scopes=["openid", "profile"],
+                jwt_signing_key="test-secret",
+                client_storage=memory_storage,
+            )
+
+    def test_empty_required_scopes_raises_value_error(
+        self, memory_storage: MemoryStore
+    ):
+        """Test that providing empty required_scopes raises ValueError."""
+        with pytest.raises(ValueError, match="at least one non-OIDC scope"):
+            AzureProvider(
+                client_id="test_client",
+                client_secret="test_secret",
+                tenant_id="test-tenant",
+                base_url="https://myserver.com",
+                identifier_uri="api://my-api",
+                required_scopes=[],
+                jwt_signing_key="test-secret",
+                client_storage=memory_storage,
+            )
+
+    @pytest.mark.parametrize(
+        "scopes",
+        [
+            ["offline_access"],
+            ["openid", "email", "profile", "offline_access"],
+            ["email"],
+        ],
+    )
+    def test_only_oidc_scopes_raises_value_error(
+        self, memory_storage: MemoryStore, scopes: list[str]
+    ):
+        """Test that various OIDC-only scope combinations raise ValueError."""
+        with pytest.raises(ValueError, match="at least one non-OIDC scope"):
+            AzureProvider(
+                client_id="test_client",
+                client_secret="test_secret",
+                tenant_id="test-tenant",
+                base_url="https://myserver.com",
+                required_scopes=scopes,
+                jwt_signing_key="test-secret",
+                client_storage=memory_storage,
+            )
+
+    def test_valid_scopes_includes_oidc_scopes(self, memory_storage: MemoryStore):
+        """Test that valid_scopes advertises OIDC scopes to clients."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read", "openid", "profile"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # required_scopes (used for validation) excludes OIDC scopes
+        assert provider.required_scopes == ["read"]
+        # But valid_scopes (advertised to clients) includes all scopes
+        assert provider.client_registration_options is not None
+        assert provider.client_registration_options.valid_scopes == [
+            "read",
+            "openid",
+            "profile",
+        ]
+
+    def test_prepare_scopes_for_refresh_handles_oidc_scopes(
+        self, memory_storage: MemoryStore
+    ):
+        """Test that token refresh correctly handles OIDC scopes."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Simulate stored scopes that include OIDC scopes
+        result = provider._prepare_scopes_for_upstream_refresh(
+            ["read", "openid", "profile"]
+        )
+
+        # Custom scope should be prefixed, OIDC scopes should not
+        assert "api://my-api/read" in result
+        assert "openid" in result
+        assert "profile" in result
+        assert "api://my-api/openid" not in result
+        assert "api://my-api/profile" not in result
+
+
+class TestAzureTokenExchangeScopes:
+    """Tests for Azure provider's token exchange scope handling.
+
+    Azure requires scopes to be sent during the authorization code exchange.
+    The provider overrides _prepare_scopes_for_token_exchange to return
+    properly prefixed scopes.
+    """
+
+    def test_prepare_scopes_returns_prefixed_scopes(self, memory_storage: MemoryStore):
+        """Test that _prepare_scopes_for_token_exchange returns prefixed scopes."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read", "write"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        scopes = provider._prepare_scopes_for_token_exchange(["read", "write"])
+        assert len(scopes) > 0
+        assert "api://my-api/read" in scopes
+        assert "api://my-api/write" in scopes
+
+    def test_prepare_scopes_includes_additional_oidc_scopes(
+        self, memory_storage: MemoryStore
+    ):
+        """Test that _prepare_scopes_for_token_exchange includes OIDC scopes."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            additional_authorize_scopes=["openid", "profile", "offline_access"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        scopes = provider._prepare_scopes_for_token_exchange(["read"])
+        assert len(scopes) > 0
+        assert "api://my-api/read" in scopes
+        assert "openid" in scopes
+        assert "profile" in scopes
+        assert "offline_access" in scopes
+
+    def test_prepare_scopes_excludes_other_api_scopes(
+        self, memory_storage: MemoryStore
+    ):
+        """Test token exchange excludes other API scopes (Azure AADSTS28000).
+
+        Azure only allows ONE resource per token exchange. Other API scopes
+        are requested during authorization but excluded from token exchange.
+        """
+        provider = AzureProvider(
+            client_id="00000000-1111-2222-3333-444444444444",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            required_scopes=["user_impersonation"],
+            additional_authorize_scopes=[
+                "openid",
+                "profile",
+                "offline_access",
+                "api://aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/user_impersonation",
+                "api://11111111-2222-3333-4444-555555555555/user_impersonation",
+            ],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        scopes = provider._prepare_scopes_for_token_exchange(["user_impersonation"])
+        assert len(scopes) > 0
+        # Primary API scope should be prefixed with the provider's identifier_uri
+        assert "api://00000000-1111-2222-3333-444444444444/user_impersonation" in scopes
+        # OIDC scopes should be included
+        assert "openid" in scopes
+        assert "profile" in scopes
+        assert "offline_access" in scopes
+        # Other API scopes should NOT be included (Azure multi-resource limitation)
+        assert not any("api://aaaaaaaa" in s for s in scopes)
+        assert not any("api://11111111" in s for s in scopes)
+
+    def test_prepare_scopes_deduplicates_scopes(self, memory_storage: MemoryStore):
+        """Test that duplicate scopes are deduplicated."""
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read"],
+            additional_authorize_scopes=["api://my-api/read", "openid"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Pass a scope that will be prefixed to match one in additional_authorize_scopes
+        scopes = provider._prepare_scopes_for_token_exchange(["read"])
+        assert len(scopes) > 0
+        # Should be deduplicated - api://my-api/read appears only once
+        assert scopes.count("api://my-api/read") == 1
+        assert "openid" in scopes
+
+    def test_extra_token_params_does_not_contain_scope(
+        self, memory_storage: MemoryStore
+    ):
+        """Test that extra_token_params doesn't contain scope to avoid TypeError.
+
+        Previously, Azure provider set extra_token_params={"scope": ...} during init.
+        This caused a TypeError in exchange_refresh_token because it passes both
+        scope=... AND **self._extra_token_params, resulting in:
+        "got multiple values for keyword argument 'scope'"
+
+        The fix uses the _prepare_scopes_for_token_exchange hook instead.
+        """
+        provider = AzureProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            tenant_id="test-tenant",
+            base_url="https://myserver.com",
+            identifier_uri="api://my-api",
+            required_scopes=["read", "write"],
+            additional_authorize_scopes=["openid", "profile", "offline_access"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # extra_token_params should NOT contain "scope" to avoid TypeError during refresh
+        assert "scope" not in provider._extra_token_params
+
+        # Instead, scopes should be provided via the hook methods
+        exchange_scopes = provider._prepare_scopes_for_token_exchange(["read", "write"])
+        assert len(exchange_scopes) > 0
+
+        refresh_scopes = provider._prepare_scopes_for_upstream_refresh(
+            ["read", "write"]
+        )
+        assert len(refresh_scopes) > 0
+
+
+class TestAzureJWTVerifier:
+    """Tests for AzureJWTVerifier pre-configured JWT verifier."""
+
+    def test_auto_configures_from_client_and_tenant(self):
+        verifier = AzureJWTVerifier(
+            client_id="my-client-id",
+            tenant_id="my-tenant-id",
+            required_scopes=["access_as_user"],
+        )
+        assert (
+            verifier.jwks_uri
+            == "https://login.microsoftonline.com/my-tenant-id/discovery/v2.0/keys"
+        )
+        assert verifier.issuer == "https://login.microsoftonline.com/my-tenant-id/v2.0"
+        assert verifier.audience == ["my-client-id", "api://my-client-id"]
+        assert verifier.algorithm == "RS256"
+        assert verifier.required_scopes == ["access_as_user"]
+
+    async def test_validates_short_form_scopes(self):
+        key_pair = RSAKeyPair.generate()
+        verifier = AzureJWTVerifier(
+            client_id="my-client-id",
+            tenant_id="my-tenant-id",
+            required_scopes=["access_as_user"],
+        )
+        # Override to use our test key instead of JWKS
+        verifier.public_key = key_pair.public_key
+        verifier.jwks_uri = None
+
+        token = key_pair.create_token(
+            subject="test-user",
+            issuer="https://login.microsoftonline.com/my-tenant-id/v2.0",
+            audience="api://my-client-id",
+            additional_claims={"scp": "access_as_user"},
+        )
+        result = await verifier.load_access_token(token)
+        assert result is not None
+        assert "access_as_user" in result.scopes
+
+    async def test_validates_token_with_client_id_audience(self):
+        """Azure AD v2 tokens use the bare client_id GUID as audience."""
+        key_pair = RSAKeyPair.generate()
+        verifier = AzureJWTVerifier(
+            client_id="my-client-id",
+            tenant_id="my-tenant-id",
+            required_scopes=["access_as_user"],
+        )
+        verifier.public_key = key_pair.public_key
+        verifier.jwks_uri = None
+
+        token = key_pair.create_token(
+            subject="test-user",
+            issuer="https://login.microsoftonline.com/my-tenant-id/v2.0",
+            audience="my-client-id",
+            additional_claims={"scp": "access_as_user"},
+        )
+        result = await verifier.load_access_token(token)
+        assert result is not None
+        assert "access_as_user" in result.scopes
+
+    async def test_validates_token_with_custom_identifier_uri_audience(self):
+        """Custom identifier_uri (e.g. Bicep deployments) accepted as audience."""
+        key_pair = RSAKeyPair.generate()
+        verifier = AzureJWTVerifier(
+            client_id="my-client-id",
+            tenant_id="my-tenant-id",
+            required_scopes=["read"],
+            identifier_uri="api://my-app-name",
+        )
+        verifier.public_key = key_pair.public_key
+        verifier.jwks_uri = None
+
+        token = key_pair.create_token(
+            subject="test-user",
+            issuer="https://login.microsoftonline.com/my-tenant-id/v2.0",
+            audience="api://my-app-name",
+            additional_claims={"scp": "read"},
+        )
+        result = await verifier.load_access_token(token)
+        assert result is not None
+        assert "read" in result.scopes
+
+    async def test_rejects_token_with_wrong_audience(self):
+        """Tokens for a different application must be rejected."""
+        key_pair = RSAKeyPair.generate()
+        verifier = AzureJWTVerifier(
+            client_id="my-client-id",
+            tenant_id="my-tenant-id",
+            required_scopes=["read"],
+        )
+        verifier.public_key = key_pair.public_key
+        verifier.jwks_uri = None
+
+        token = key_pair.create_token(
+            subject="test-user",
+            issuer="https://login.microsoftonline.com/my-tenant-id/v2.0",
+            audience="some-other-app-id",
+            additional_claims={"scp": "read"},
+        )
+        result = await verifier.load_access_token(token)
+        assert result is None
+
+    def test_scopes_supported_returns_prefixed_form(self):
+        verifier = AzureJWTVerifier(
+            client_id="my-client-id",
+            tenant_id="my-tenant-id",
+            required_scopes=["read", "write"],
+        )
+        assert verifier.scopes_supported == [
+            "api://my-client-id/read",
+            "api://my-client-id/write",
+        ]
+
+    def test_already_prefixed_scopes_pass_through(self):
+        verifier = AzureJWTVerifier(
+            client_id="my-client-id",
+            tenant_id="my-tenant-id",
+            required_scopes=["api://my-client-id/read"],
+        )
+        assert verifier.scopes_supported == ["api://my-client-id/read"]
+
+    def test_oidc_scopes_not_prefixed(self):
+        verifier = AzureJWTVerifier(
+            client_id="my-client-id",
+            tenant_id="my-tenant-id",
+            required_scopes=["openid", "read"],
+        )
+        assert verifier.scopes_supported == ["openid", "api://my-client-id/read"]
+
+    def test_custom_identifier_uri(self):
+        verifier = AzureJWTVerifier(
+            client_id="my-client-id",
+            tenant_id="my-tenant-id",
+            required_scopes=["read"],
+            identifier_uri="api://custom-uri",
+        )
+        assert verifier.scopes_supported == ["api://custom-uri/read"]
+
+    def test_custom_base_authority_for_gov_cloud(self):
+        verifier = AzureJWTVerifier(
+            client_id="my-client-id",
+            tenant_id="my-tenant-id",
+            required_scopes=["read"],
+            base_authority="login.microsoftonline.us",
+        )
+        assert (
+            verifier.jwks_uri
+            == "https://login.microsoftonline.us/my-tenant-id/discovery/v2.0/keys"
+        )
+        assert verifier.issuer == "https://login.microsoftonline.us/my-tenant-id/v2.0"
+
+    def test_scopes_supported_empty_when_no_required_scopes(self):
+        verifier = AzureJWTVerifier(
+            client_id="my-client-id",
+            tenant_id="my-tenant-id",
+        )
+        assert verifier.scopes_supported == []
+
+    def test_default_identifier_uri_uses_client_id(self):
+        verifier = AzureJWTVerifier(
+            client_id="abc-123",
+            tenant_id="my-tenant-id",
+            required_scopes=["read"],
+        )
+        assert verifier.scopes_supported == ["api://abc-123/read"]
+
+    def test_multi_tenant_organizations_skips_issuer(self):
+        verifier = AzureJWTVerifier(
+            client_id="my-client-id",
+            tenant_id="organizations",
+        )
+        assert verifier.issuer is None
+
+    def test_multi_tenant_consumers_skips_issuer(self):
+        verifier = AzureJWTVerifier(
+            client_id="my-client-id",
+            tenant_id="consumers",
+        )
+        assert verifier.issuer is None
+
+    def test_multi_tenant_common_skips_issuer(self):
+        verifier = AzureJWTVerifier(
+            client_id="my-client-id",
+            tenant_id="common",
+        )
+        assert verifier.issuer is None
+
+    def test_specific_tenant_sets_issuer(self):
+        verifier = AzureJWTVerifier(
+            client_id="my-client-id",
+            tenant_id="12345678-1234-1234-1234-123456789012",
+        )
+        assert (
+            verifier.issuer
+            == "https://login.microsoftonline.com/12345678-1234-1234-1234-123456789012/v2.0"
+        )
+
+
+class TestAzureOBOIntegration:
+    """Tests for azure.identity OBO integration (get_obo_credential, EntraOBOToken)."""
+
+    async def test_get_obo_credential_returns_configured_credential(self):
+        """Test that get_obo_credential returns a properly configured credential."""
+        from unittest.mock import MagicMock, patch
+
+        provider = AzureProvider(
+            client_id="test-client-id",
+            client_secret="test-client-secret",
+            tenant_id="test-tenant-id",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+        )
+
+        mock_credential = MagicMock()
+        with patch(
+            "azure.identity.aio.OnBehalfOfCredential", return_value=mock_credential
+        ) as mock_class:
+            credential = await provider.get_obo_credential(
+                user_assertion="user-token-123"
+            )
+
+            mock_class.assert_called_once_with(
+                tenant_id="test-tenant-id",
+                client_id="test-client-id",
+                client_secret="test-client-secret",
+                user_assertion="user-token-123",
+                authority="https://login.microsoftonline.com",
+            )
+            assert credential is mock_credential
+
+    async def test_get_obo_credential_caches_by_assertion(self):
+        """Test that the same assertion returns the cached credential."""
+        from unittest.mock import MagicMock, patch
+
+        provider = AzureProvider(
+            client_id="test-client-id",
+            client_secret="test-client-secret",
+            tenant_id="test-tenant-id",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+        )
+
+        mock_credential = MagicMock()
+        with patch(
+            "azure.identity.aio.OnBehalfOfCredential", return_value=mock_credential
+        ) as mock_class:
+            first = await provider.get_obo_credential(user_assertion="same-token")
+            second = await provider.get_obo_credential(user_assertion="same-token")
+
+            assert first is second
+            mock_class.assert_called_once()
+
+    async def test_get_obo_credential_different_assertions_get_different_credentials(
+        self,
+    ):
+        """Test that different assertions produce different credentials."""
+        from unittest.mock import MagicMock, patch
+
+        provider = AzureProvider(
+            client_id="test-client-id",
+            client_secret="test-client-secret",
+            tenant_id="test-tenant-id",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+        )
+
+        creds = [MagicMock(), MagicMock()]
+        with patch("azure.identity.aio.OnBehalfOfCredential", side_effect=creds):
+            first = await provider.get_obo_credential(user_assertion="token-a")
+            second = await provider.get_obo_credential(user_assertion="token-b")
+
+            assert first is not second
+            assert first is creds[0]
+            assert second is creds[1]
+
+    async def test_get_obo_credential_evicts_oldest_when_over_capacity(self):
+        """Test that credentials are evicted LRU-style when cache is full."""
+        from unittest.mock import AsyncMock, MagicMock, patch
+
+        provider = AzureProvider(
+            client_id="test-client-id",
+            client_secret="test-client-secret",
+            tenant_id="test-tenant-id",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+        )
+        provider._obo_max_credentials = 2
+
+        creds = [MagicMock(close=AsyncMock()) for _ in range(3)]
+        with patch("azure.identity.aio.OnBehalfOfCredential", side_effect=creds):
+            await provider.get_obo_credential(user_assertion="token-1")
+            await provider.get_obo_credential(user_assertion="token-2")
+            await provider.get_obo_credential(user_assertion="token-3")
+
+            assert len(provider._obo_credentials) == 2
+            creds[0].close.assert_awaited_once()
+            # token-1's credential was evicted
+            assert (
+                await provider.get_obo_credential(user_assertion="token-2") is creds[1]
+            )
+            assert (
+                await provider.get_obo_credential(user_assertion="token-3") is creds[2]
+            )
+
+    async def test_close_obo_credentials(self):
+        """Test that close_obo_credentials closes all cached credentials."""
+        from unittest.mock import AsyncMock, MagicMock, patch
+
+        provider = AzureProvider(
+            client_id="test-client-id",
+            client_secret="test-client-secret",
+            tenant_id="test-tenant-id",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            jwt_signing_key="test-secret",
+        )
+
+        creds = [MagicMock(close=AsyncMock()) for _ in range(2)]
+        with patch("azure.identity.aio.OnBehalfOfCredential", side_effect=creds):
+            await provider.get_obo_credential(user_assertion="token-a")
+            await provider.get_obo_credential(user_assertion="token-b")
+
+        await provider.close_obo_credentials()
+
+        assert len(provider._obo_credentials) == 0
+        for cred in creds:
+            cred.close.assert_awaited_once()
+
+    async def test_get_obo_credential_with_custom_authority(self):
+        """Test that get_obo_credential uses custom base_authority."""
+        from unittest.mock import MagicMock, patch
+
+        provider = AzureProvider(
+            client_id="test-client-id",
+            client_secret="test-client-secret",
+            tenant_id="gov-tenant-id",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            base_authority="login.microsoftonline.us",
+            jwt_signing_key="test-secret",
+        )
+
+        mock_credential = MagicMock()
+        with patch(
+            "azure.identity.aio.OnBehalfOfCredential", return_value=mock_credential
+        ) as mock_class:
+            await provider.get_obo_credential(user_assertion="user-token")
+
+            call_kwargs = mock_class.call_args[1]
+            assert call_kwargs["authority"] == "https://login.microsoftonline.us"
+
+    def test_tenant_and_authority_stored_as_attributes(self):
+        """Test that tenant_id and base_authority are stored for OBO credential creation."""
+        provider = AzureProvider(
+            client_id="test-client-id",
+            client_secret="test-client-secret",
+            tenant_id="my-tenant",
+            base_url="https://myserver.com",
+            required_scopes=["read"],
+            base_authority="login.microsoftonline.us",
+            jwt_signing_key="test-secret",
+        )
+
+        assert provider._tenant_id == "my-tenant"
+        assert provider._base_authority == "login.microsoftonline.us"
+
+    def test_entra_obo_token_is_importable(self):
+        """Test that EntraOBOToken can be imported."""
+        from fastmcp.server.auth.providers.azure import EntraOBOToken
+
+        assert EntraOBOToken is not None
+
+    def test_entra_obo_token_creates_dependency(self):
+        """Test that EntraOBOToken creates a dependency with scopes."""
+        from fastmcp.server.auth.providers.azure import EntraOBOToken, _EntraOBOToken
+
+        dep = EntraOBOToken(["https://graph.microsoft.com/User.Read"])
+        assert isinstance(dep, _EntraOBOToken)
+        assert dep.scopes == ["https://graph.microsoft.com/User.Read"]
+
+    def test_entra_obo_token_is_dependency_instance(self):
+        """Test that EntraOBOToken is a Dependency instance."""
+        from fastmcp.dependencies import Dependency
+        from fastmcp.server.auth.providers.azure import _EntraOBOToken
+
+        dep = _EntraOBOToken(["scope"])
+        assert isinstance(dep, Dependency)
+
+
+class TestFindAzureProvider:
+    """Tests for _find_azure_provider helper used by EntraOBOToken."""
+
+    def test_returns_azure_provider_directly(self, memory_storage):
+        """When auth is an AzureProvider, return it directly."""
+        provider = AzureProvider(
+            tenant_id="test-tenant",
+            client_id="test-client",
+            client_secret="test-secret",
+            client_storage=memory_storage,
+            base_url="https://example.com",
+            required_scopes=["read"],
+        )
+        assert _find_azure_provider(provider) is provider
+
+    def test_unwraps_multiauth_with_azure_server(self, memory_storage):
+        """When auth is a MultiAuth wrapping an AzureProvider, return the inner provider."""
+        provider = AzureProvider(
+            tenant_id="test-tenant",
+            client_id="test-client",
+            client_secret="test-secret",
+            client_storage=memory_storage,
+            base_url="https://example.com",
+            required_scopes=["read"],
+        )
+        multi = MultiAuth(server=provider)
+        assert _find_azure_provider(multi) is provider
+
+    def test_returns_none_for_no_auth(self):
+        """When auth is None, return None."""
+        assert _find_azure_provider(None) is None
+
+    def test_returns_none_for_multiauth_without_azure_server(self):
+        """When MultiAuth has no server or a non-Azure server, return None."""
+        verifier = StaticTokenVerifier(tokens={"t": {"client_id": "c", "scopes": []}})
+        multi = MultiAuth(verifiers=[verifier])
+        assert _find_azure_provider(multi) is None
diff --git a/tests/server/auth/providers/test_clerk.py b/tests/server/auth/providers/test_clerk.py
new file mode 100644
index 0000000..323b365
--- /dev/null
+++ b/tests/server/auth/providers/test_clerk.py
@@ -0,0 +1,572 @@
+"""Tests for Clerk OAuth provider."""
+
+import re
+
+import httpx
+import pytest
+from key_value.aio.stores.memory import MemoryStore
+from pytest_httpx import HTTPXMock
+
+from fastmcp.server.auth.providers.clerk import ClerkProvider, ClerkTokenVerifier
+
+CLERK_DOMAIN = "test-instance.clerk.accounts.dev"
+
+_USERINFO_RE = re.compile(rf"https://{re.escape(CLERK_DOMAIN)}/oauth/userinfo")
+_INTROSPECTION_RE = re.compile(rf"https://{re.escape(CLERK_DOMAIN)}/oauth/token_info")
+
+
+@pytest.fixture
+def memory_storage() -> MemoryStore:
+    """Provide a MemoryStore for tests to avoid SQLite initialization on Windows."""
+    return MemoryStore()
+
+
+class TestClerkProvider:
+    """Test Clerk OAuth provider functionality."""
+
+    def test_init_with_explicit_params(self, memory_storage: MemoryStore):
+        """Test ClerkProvider initialization with explicit parameters."""
+        provider = ClerkProvider(
+            domain=CLERK_DOMAIN,
+            client_id="clerk-client-id",
+            client_secret="clerk-client-secret",
+            base_url="https://myserver.com",
+            required_scopes=["openid", "email", "profile"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert provider._upstream_client_id == "clerk-client-id"
+        assert provider._upstream_client_secret is not None
+        assert (
+            provider._upstream_client_secret.get_secret_value() == "clerk-client-secret"
+        )
+        assert str(provider.base_url) == "https://myserver.com/"
+
+    def test_init_defaults(self, memory_storage: MemoryStore):
+        """Test that default values are applied correctly."""
+        provider = ClerkProvider(
+            domain=CLERK_DOMAIN,
+            client_id="clerk-client-id",
+            client_secret="clerk-client-secret",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert provider._redirect_path == "/auth/callback"
+
+    def test_oauth_endpoints_configured_correctly(self, memory_storage: MemoryStore):
+        """Test that OAuth endpoints are derived from the domain."""
+        provider = ClerkProvider(
+            domain=CLERK_DOMAIN,
+            client_id="clerk-client-id",
+            client_secret="clerk-client-secret",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert (
+            provider._upstream_authorization_endpoint
+            == f"https://{CLERK_DOMAIN}/oauth/authorize"
+        )
+        assert (
+            provider._upstream_token_endpoint == f"https://{CLERK_DOMAIN}/oauth/token"
+        )
+        assert provider._upstream_revocation_endpoint is None
+
+    def test_domain_trailing_slash_stripped(self, memory_storage: MemoryStore):
+        """Test that trailing slashes are stripped from the domain."""
+        provider = ClerkProvider(
+            domain=f"{CLERK_DOMAIN}/",
+            client_id="clerk-client-id",
+            client_secret="clerk-client-secret",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert (
+            provider._upstream_authorization_endpoint
+            == f"https://{CLERK_DOMAIN}/oauth/authorize"
+        )
+
+    def test_default_scopes(self, memory_storage: MemoryStore):
+        """Test that default required scopes are openid, email, profile."""
+        provider = ClerkProvider(
+            domain=CLERK_DOMAIN,
+            client_id="clerk-client-id",
+            client_secret="clerk-client-secret",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert provider is not None
+
+    def test_custom_scopes(self, memory_storage: MemoryStore):
+        """Test that custom scopes are accepted."""
+        provider = ClerkProvider(
+            domain=CLERK_DOMAIN,
+            client_id="clerk-client-id",
+            client_secret="clerk-client-secret",
+            base_url="https://myserver.com",
+            required_scopes=["openid", "email", "profile", "public_metadata"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert provider is not None
+
+    def test_no_extra_authorize_params_by_default(self, memory_storage: MemoryStore):
+        """Test that no extra authorize params are set by default."""
+        provider = ClerkProvider(
+            domain=CLERK_DOMAIN,
+            client_id="clerk-client-id",
+            client_secret="clerk-client-secret",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert provider._extra_authorize_params in (None, {})
+
+    def test_extra_authorize_params_passed_through(self, memory_storage: MemoryStore):
+        """Test that extra authorize params are forwarded."""
+        provider = ClerkProvider(
+            domain=CLERK_DOMAIN,
+            client_id="clerk-client-id",
+            client_secret="clerk-client-secret",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            extra_authorize_params={"prompt": "login"},
+            client_storage=memory_storage,
+        )
+
+        assert provider._extra_authorize_params == {"prompt": "login"}
+
+    def test_valid_scopes_passed_through(self, memory_storage: MemoryStore):
+        """Test that valid_scopes is passed to OAuthProxy."""
+        provider = ClerkProvider(
+            domain=CLERK_DOMAIN,
+            client_id="clerk-client-id",
+            client_secret="clerk-client-secret",
+            base_url="https://myserver.com",
+            required_scopes=["openid"],
+            valid_scopes=["openid", "email", "profile", "public_metadata"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        reg_options = provider.client_registration_options
+        assert reg_options is not None
+        assert reg_options.valid_scopes is not None
+        assert set(reg_options.valid_scopes) == {
+            "openid",
+            "email",
+            "profile",
+            "public_metadata",
+        }
+
+    def test_issuer_url_defaults_to_base_url(self, memory_storage: MemoryStore):
+        """Test that issuer_url defaults to base_url when not provided."""
+        provider = ClerkProvider(
+            domain=CLERK_DOMAIN,
+            client_id="clerk-client-id",
+            client_secret="clerk-client-secret",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert str(provider.issuer_url) == "https://myserver.com/"
+
+    def test_custom_issuer_url(self, memory_storage: MemoryStore):
+        """Test that a custom issuer_url is used when provided."""
+        provider = ClerkProvider(
+            domain=CLERK_DOMAIN,
+            client_id="clerk-client-id",
+            client_secret="clerk-client-secret",
+            base_url="https://myserver.com/mcp",
+            issuer_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert str(provider.issuer_url) == "https://myserver.com/"
+
+
+class TestClerkTokenVerifier:
+    """Test ClerkTokenVerifier.verify_token() using introspection + userinfo."""
+
+    async def test_valid_token_basic(self, httpx_mock: HTTPXMock):
+        """A valid token returns an AccessToken with user claims from userinfo."""
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={
+                "sub": "user_abc123",
+                "email": "user@example.com",
+                "email_verified": True,
+                "name": "Test User",
+                "picture": "https://img.clerk.com/photo.jpg",
+                "given_name": "Test",
+                "family_name": "User",
+                "preferred_username": "testuser",
+                "iss": f"https://{CLERK_DOMAIN}",
+            },
+        )
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            json={
+                "active": True,
+                "scope": "openid email profile",
+                "aud": "clerk-client-id",
+                "exp": 9999999999,
+            },
+        )
+
+        verifier = ClerkTokenVerifier(
+            domain=CLERK_DOMAIN,
+            client_id="clerk-client-id",
+            client_secret="clerk-client-secret",
+        )
+        result = await verifier.verify_token("valid-token")
+
+        assert result is not None
+        assert result.client_id == "clerk-client-id"
+        assert result.scopes == ["openid", "email", "profile"]
+        assert result.expires_at == 9999999999
+        assert result.claims["sub"] == "user_abc123"
+        assert result.claims["email"] == "user@example.com"
+        assert result.claims["name"] == "Test User"
+        assert result.claims["picture"] == "https://img.clerk.com/photo.jpg"
+        assert result.claims["given_name"] == "Test"
+        assert result.claims["family_name"] == "User"
+        assert result.claims["preferred_username"] == "testuser"
+        assert result.claims["aud"] == "clerk-client-id"
+
+    async def test_invalid_token_returns_none(self, httpx_mock: HTTPXMock):
+        """Token marked inactive by introspection is rejected."""
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            json={"active": False},
+        )
+
+        verifier = ClerkTokenVerifier(domain=CLERK_DOMAIN)
+        result = await verifier.verify_token("expired-token")
+
+        assert result is None
+
+    async def test_missing_sub_returns_none(self, httpx_mock: HTTPXMock):
+        """Token with no 'sub' in introspection or userinfo is rejected."""
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            json={"active": True},
+        )
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={"email": "user@example.com"},
+        )
+
+        verifier = ClerkTokenVerifier(domain=CLERK_DOMAIN)
+        result = await verifier.verify_token("token-without-sub")
+
+        assert result is None
+
+    async def test_introspection_inactive_token_returns_none(
+        self, httpx_mock: HTTPXMock
+    ):
+        """Token marked inactive by introspection is rejected before userinfo."""
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            json={"active": False},
+        )
+
+        verifier = ClerkTokenVerifier(
+            domain=CLERK_DOMAIN,
+            client_id="clerk-client-id",
+            client_secret="clerk-client-secret",
+        )
+        result = await verifier.verify_token("inactive-token")
+
+        assert result is None
+
+    async def test_introspection_missing_active_field_returns_none(
+        self, httpx_mock: HTTPXMock
+    ):
+        """RFC 7662 requires the 'active' field; a missing field is malformed and rejected."""
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            json={"scope": "openid email profile", "aud": "clerk-client-id"},
+        )
+
+        verifier = ClerkTokenVerifier(
+            domain=CLERK_DOMAIN,
+            client_id="clerk-client-id",
+            client_secret="clerk-client-secret",
+        )
+        result = await verifier.verify_token("token-malformed-response")
+
+        assert result is None
+
+    async def test_introspection_failure_rejects_when_scopes_required(
+        self, httpx_mock: HTTPXMock
+    ):
+        """When introspection fails (non-200), token is rejected regardless of scopes."""
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            status_code=500,
+            json={"error": "internal_server_error"},
+        )
+
+        verifier = ClerkTokenVerifier(
+            domain=CLERK_DOMAIN,
+            required_scopes=["openid", "email"],
+        )
+        result = await verifier.verify_token("valid-token")
+
+        assert result is None
+
+    async def test_empty_scopes_rejects_when_required(self, httpx_mock: HTTPXMock):
+        """When introspection returns no scopes and required_scopes are set, token is rejected."""
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            json={"active": True, "scope": ""},
+        )
+
+        verifier = ClerkTokenVerifier(
+            domain=CLERK_DOMAIN,
+            required_scopes=["openid", "email", "profile"],
+        )
+        result = await verifier.verify_token("valid-token")
+
+        assert result is None
+
+    async def test_required_scopes_not_satisfied_returns_none(
+        self, httpx_mock: HTTPXMock
+    ):
+        """Token without required scopes is rejected before userinfo."""
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            json={"active": True, "scope": "openid"},
+        )
+
+        verifier = ClerkTokenVerifier(
+            domain=CLERK_DOMAIN,
+            required_scopes=["openid", "email", "profile"],
+        )
+        result = await verifier.verify_token("token-missing-scopes")
+
+        assert result is None
+
+    async def test_uses_bearer_header_for_userinfo(self, httpx_mock: HTTPXMock):
+        """verify_token sends the token as a Bearer header to userinfo."""
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            json={"active": True, "scope": "openid", "sub": "user_abc123"},
+        )
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={"sub": "user_abc123"},
+        )
+
+        verifier = ClerkTokenVerifier(domain=CLERK_DOMAIN)
+        await verifier.verify_token("my-access-token")
+
+        requests = httpx_mock.get_requests()
+        userinfo_req = requests[1]
+        assert userinfo_req.headers["Authorization"] == "Bearer my-access-token"
+
+    async def test_introspection_sends_client_credentials(self, httpx_mock: HTTPXMock):
+        """Introspection request sends credentials via HTTP Basic Auth when both are set."""
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            json={"active": True, "scope": "openid", "aud": "clerk-client-id"},
+        )
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={"sub": "user_abc123"},
+        )
+
+        verifier = ClerkTokenVerifier(
+            domain=CLERK_DOMAIN,
+            client_id="clerk-client-id",
+            client_secret="clerk-client-secret",
+        )
+        await verifier.verify_token("my-access-token")
+
+        requests = httpx_mock.get_requests()
+        introspect_req = requests[0]
+        body = introspect_req.content.decode()
+        assert "token=my-access-token" in body
+        assert introspect_req.headers.get("Authorization", "").startswith("Basic ")
+
+    async def test_expires_at_from_introspection(self, httpx_mock: HTTPXMock):
+        """expires_at is set from the 'exp' claim in the introspection response."""
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={"sub": "user_abc123"},
+        )
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            json={"active": True, "scope": "openid", "exp": 1700000000},
+        )
+
+        verifier = ClerkTokenVerifier(domain=CLERK_DOMAIN)
+        result = await verifier.verify_token("valid-token")
+
+        assert result is not None
+        assert result.expires_at == 1700000000
+
+    async def test_client_id_falls_back_to_sub(self, httpx_mock: HTTPXMock):
+        """When introspection has no aud/client_id, client_id falls back to sub."""
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={"sub": "user_abc123"},
+        )
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            json={"active": True, "scope": "openid"},
+        )
+
+        verifier = ClerkTokenVerifier(domain=CLERK_DOMAIN)
+        result = await verifier.verify_token("valid-token")
+
+        assert result is not None
+        assert result.client_id == "user_abc123"
+
+    async def test_aud_from_introspection_client_id_field(self, httpx_mock: HTTPXMock):
+        """When introspection returns client_id but not aud, client_id is used."""
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={"sub": "user_abc123"},
+        )
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            json={"active": True, "scope": "openid", "client_id": "my-app-id"},
+        )
+
+        verifier = ClerkTokenVerifier(domain=CLERK_DOMAIN)
+        result = await verifier.verify_token("valid-token")
+
+        assert result is not None
+        assert result.client_id == "my-app-id"
+        assert result.claims["aud"] == "my-app-id"
+
+    async def test_no_required_scopes_accepts_any(self, httpx_mock: HTTPXMock):
+        """When no required_scopes are set, any valid token is accepted."""
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={"sub": "user_abc123"},
+        )
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            json={"active": True, "scope": "openid custom_scope"},
+        )
+
+        verifier = ClerkTokenVerifier(domain=CLERK_DOMAIN)
+        result = await verifier.verify_token("valid-token")
+
+        assert result is not None
+        assert result.scopes == ["openid", "custom_scope"]
+
+    async def test_clerk_user_data_in_claims(self, httpx_mock: HTTPXMock):
+        """The full userinfo response is stored in clerk_user_data claim."""
+        user_data = {
+            "sub": "user_abc123",
+            "email": "user@example.com",
+            "name": "Test User",
+        }
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json=user_data,
+        )
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            json={"active": True},
+        )
+
+        verifier = ClerkTokenVerifier(domain=CLERK_DOMAIN)
+        result = await verifier.verify_token("valid-token")
+
+        assert result is not None
+        assert result.claims["clerk_user_data"] == user_data
+
+    async def test_network_error_returns_none(self, httpx_mock: HTTPXMock):
+        """Network errors during introspection return None instead of raising."""
+        httpx_mock.add_exception(
+            httpx.ConnectError("Connection refused"),
+            url=_INTROSPECTION_RE,
+        )
+
+        verifier = ClerkTokenVerifier(domain=CLERK_DOMAIN)
+        result = await verifier.verify_token("valid-token")
+
+        assert result is None
+
+    async def test_introspection_failure_rejects_without_required_scopes(
+        self, httpx_mock: HTTPXMock
+    ):
+        """Introspection failure (non-200) rejects the token even without required_scopes."""
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            status_code=500,
+            json={"error": "internal_server_error"},
+        )
+
+        verifier = ClerkTokenVerifier(domain=CLERK_DOMAIN)
+        result = await verifier.verify_token("valid-token")
+
+        assert result is None
+
+    async def test_audience_mismatch_returns_none(self, httpx_mock: HTTPXMock):
+        """Token with wrong audience is rejected before userinfo is called."""
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            json={"active": True, "scope": "openid", "aud": "wrong-client-id"},
+        )
+
+        verifier = ClerkTokenVerifier(
+            domain=CLERK_DOMAIN,
+            client_id="my-client-id",
+            client_secret="my-client-secret",
+        )
+        result = await verifier.verify_token("valid-token")
+
+        assert result is None
+
+    async def test_audience_missing_returns_none_when_client_id_set(
+        self, httpx_mock: HTTPXMock
+    ):
+        """Token without audience is rejected before userinfo is called."""
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            json={"active": True, "scope": "openid"},
+        )
+
+        verifier = ClerkTokenVerifier(
+            domain=CLERK_DOMAIN,
+            client_id="my-client-id",
+            client_secret="my-client-secret",
+        )
+        result = await verifier.verify_token("valid-token")
+
+        assert result is None
+
+    async def test_audience_not_checked_without_client_id(self, httpx_mock: HTTPXMock):
+        """Without client_id configured, any audience is accepted."""
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={"sub": "user_abc123"},
+        )
+        httpx_mock.add_response(
+            url=_INTROSPECTION_RE,
+            json={"active": True, "scope": "openid", "aud": "some-other-id"},
+        )
+
+        verifier = ClerkTokenVerifier(domain=CLERK_DOMAIN)
+        result = await verifier.verify_token("valid-token")
+
+        assert result is not None
+        assert result.claims["aud"] == "some-other-id"
diff --git a/tests/server/auth/providers/test_debug.py b/tests/server/auth/providers/test_debug.py
new file mode 100644
index 0000000..1bb9f29
--- /dev/null
+++ b/tests/server/auth/providers/test_debug.py
@@ -0,0 +1,37 @@
+import pytest
+
+from fastmcp.server.auth.providers.debug import DebugTokenVerifier
+
+
+class TestDebugTokenVerifier:
+    async def test_default_validator_accepts_non_empty_tokens(self):
+        verifier = DebugTokenVerifier(client_id="client-1", scopes=["read"])
+
+        token = await verifier.verify_token("token-123")
+
+        assert token is not None
+        assert token.token == "token-123"
+        assert token.client_id == "client-1"
+        assert token.scopes == ["read"]
+        assert token.claims == {"token": "token-123"}
+
+    @pytest.mark.parametrize("token", ["", "   "])
+    async def test_rejects_empty_tokens(self, token):
+        verifier = DebugTokenVerifier()
+
+        assert await verifier.verify_token(token) is None
+
+    async def test_sync_validator_can_reject_tokens(self):
+        verifier = DebugTokenVerifier(validate=lambda token: token.startswith("valid-"))
+
+        assert await verifier.verify_token("invalid") is None
+        assert await verifier.verify_token("valid-token") is not None
+
+    async def test_async_validator_is_awaited(self):
+        async def validate(token: str) -> bool:
+            return token == "allowed"
+
+        verifier = DebugTokenVerifier(validate=validate)
+
+        assert await verifier.verify_token("denied") is None
+        assert await verifier.verify_token("allowed") is not None
diff --git a/tests/server/auth/providers/test_descope.py b/tests/server/auth/providers/test_descope.py
new file mode 100644
index 0000000..8a149c9
--- /dev/null
+++ b/tests/server/auth/providers/test_descope.py
@@ -0,0 +1,237 @@
+"""Tests for Descope OAuth provider."""
+
+import os
+from unittest.mock import patch
+
+import pytest
+from mcp import MCPError
+
+from fastmcp import Client, FastMCP
+from fastmcp.client.transports import StreamableHttpTransport
+from fastmcp.server.auth.providers.descope import DescopeProvider
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.utilities.tests import HeadlessOAuth, run_server_async
+
+
+class TestDescopeProvider:
+    """Test Descope OAuth provider functionality."""
+
+    def test_init_with_explicit_params(self):
+        """Test DescopeProvider initialization with explicit parameters."""
+        provider = DescopeProvider(
+            config_url="https://api.descope.com/v1/apps/agentic/P2abc123/M123/.well-known/openid-configuration",
+            base_url="https://myserver.com",
+        )
+
+        assert provider.project_id == "P2abc123"
+        assert str(provider.base_url) == "https://myserver.com/"
+        assert str(provider.descope_base_url) == "https://api.descope.com"
+
+    def test_environment_variable_loading(self):
+        """Test that environment variables are loaded correctly."""
+        # This test verifies that the provider can be created with environment variables
+        provider = DescopeProvider(
+            config_url="https://api.descope.com/v1/apps/agentic/P2env123/M123/.well-known/openid-configuration",
+            base_url="http://env-server.com",
+        )
+
+        # Should have loaded from environment
+        assert provider.project_id == "P2env123"
+        assert str(provider.base_url) == "http://env-server.com/"
+        assert str(provider.descope_base_url) == "https://api.descope.com"
+
+    def test_config_url_parsing(self):
+        """Test that config_url is parsed correctly to extract base URL and project ID."""
+        # Standard HTTPS URL
+        provider1 = DescopeProvider(
+            config_url="https://api.descope.com/v1/apps/agentic/P2abc123/M123/.well-known/openid-configuration",
+            base_url="https://myserver.com",
+        )
+        assert str(provider1.descope_base_url) == "https://api.descope.com"
+        assert provider1.project_id == "P2abc123"
+
+        # HTTP URL (for local testing)
+        provider2 = DescopeProvider(
+            config_url="http://localhost:8080/v1/apps/agentic/P2abc123/M123/.well-known/openid-configuration",
+            base_url="https://myserver.com",
+        )
+        assert str(provider2.descope_base_url) == "http://localhost:8080"
+        assert provider2.project_id == "P2abc123"
+
+        # URL without .well-known/openid-configuration suffix
+        provider3 = DescopeProvider(
+            config_url="https://api.descope.com/v1/apps/agentic/P2abc123/M123",
+            base_url="https://myserver.com",
+        )
+        assert str(provider3.descope_base_url) == "https://api.descope.com"
+        assert provider3.project_id == "P2abc123"
+
+    def test_requires_config_url_or_project_id_and_descope_base_url(self):
+        """Test that either config_url or both project_id and descope_base_url are required."""
+        # Should raise error when neither API is provided
+        with pytest.raises(ValueError, match="Either config_url"):
+            DescopeProvider(
+                base_url="https://myserver.com",
+            )
+
+    def test_backwards_compatibility_with_project_id_and_descope_base_url(self):
+        """Test backwards compatibility with old API using project_id and descope_base_url."""
+        provider = DescopeProvider(
+            project_id="P2abc123",
+            descope_base_url="https://api.descope.com",
+            base_url="https://myserver.com",
+        )
+
+        assert provider.project_id == "P2abc123"
+        assert str(provider.descope_base_url) == "https://api.descope.com"
+        assert str(provider.base_url) == "https://myserver.com/"
+
+        # Check that JWT verifier uses the old issuer format
+        assert isinstance(provider.token_verifier, JWTVerifier)
+        assert (
+            provider.token_verifier.issuer == "https://api.descope.com/v1/apps/P2abc123"
+        )
+        assert (
+            provider.token_verifier.jwks_uri
+            == "https://api.descope.com/P2abc123/.well-known/jwks.json"
+        )
+
+    def test_backwards_compatibility_descope_base_url_without_scheme(self):
+        """Test that descope_base_url without scheme gets https:// prefix added."""
+        provider = DescopeProvider(
+            project_id="P2abc123",
+            descope_base_url="api.descope.com",
+            base_url="https://myserver.com",
+        )
+
+        assert str(provider.descope_base_url) == "https://api.descope.com"
+        assert isinstance(provider.token_verifier, JWTVerifier)
+        assert (
+            provider.token_verifier.issuer == "https://api.descope.com/v1/apps/P2abc123"
+        )
+
+    def test_config_url_takes_precedence_over_old_api(self):
+        """Test that config_url takes precedence when both APIs are provided."""
+        provider = DescopeProvider(
+            config_url="https://api.descope.com/v1/apps/agentic/P2new123/M123/.well-known/openid-configuration",
+            project_id="P2old123",  # Should be ignored
+            descope_base_url="https://old.descope.com",  # Should be ignored
+            base_url="https://myserver.com",
+        )
+
+        # Should use values from config_url, not the old API
+        assert provider.project_id == "P2new123"
+        assert str(provider.descope_base_url) == "https://api.descope.com"
+        assert isinstance(provider.token_verifier, JWTVerifier)
+        assert (
+            provider.token_verifier.issuer
+            == "https://api.descope.com/v1/apps/agentic/P2new123/M123"
+        )
+
+    def test_jwt_verifier_configured_correctly(self):
+        """Test that JWT verifier is configured correctly."""
+        config_url = "https://api.descope.com/v1/apps/agentic/P2abc123/M123/.well-known/openid-configuration"
+        issuer_url = "https://api.descope.com/v1/apps/agentic/P2abc123/M123"
+
+        provider = DescopeProvider(
+            config_url=config_url,
+            base_url="https://myserver.com",
+        )
+
+        # Check that JWT verifier uses the correct endpoints
+        assert isinstance(provider.token_verifier, JWTVerifier)
+        assert (
+            provider.token_verifier.jwks_uri
+            == "https://api.descope.com/P2abc123/.well-known/jwks.json"
+        )
+        assert provider.token_verifier.issuer == issuer_url
+        assert isinstance(provider.token_verifier, JWTVerifier)
+        assert provider.token_verifier.audience == "P2abc123"
+
+    def test_required_scopes_support(self):
+        """Test that required_scopes are supported and passed to JWT verifier."""
+        provider = DescopeProvider(
+            config_url="https://api.descope.com/v1/apps/agentic/P2abc123/M123/.well-known/openid-configuration",
+            base_url="https://myserver.com",
+            required_scopes=["read", "write"],
+        )
+
+        # Check that required_scopes are set on the token verifier
+        assert isinstance(provider.token_verifier, JWTVerifier)
+        assert provider.token_verifier.required_scopes == ["read", "write"]
+
+    def test_required_scopes_with_old_api(self):
+        """Test that required_scopes work with the old API (project_id + descope_base_url)."""
+        provider = DescopeProvider(
+            project_id="P2abc123",
+            descope_base_url="https://api.descope.com",
+            base_url="https://myserver.com",
+            required_scopes=["openid", "email"],
+        )
+
+        # Check that required_scopes are set on the token verifier
+        assert isinstance(provider.token_verifier, JWTVerifier)
+        assert provider.token_verifier.required_scopes == ["openid", "email"]
+
+    def test_required_scopes_from_env(self):
+        """Test that required_scopes can be set via environment variable."""
+        with patch.dict(
+            os.environ,
+            {
+                "FASTMCP_SERVER_AUTH_DESCOPEPROVIDER_CONFIG_URL": "https://api.descope.com/v1/apps/agentic/P2env123/M123/.well-known/openid-configuration",
+                "FASTMCP_SERVER_AUTH_DESCOPEPROVIDER_BASE_URL": "https://envserver.com",
+                "FASTMCP_SERVER_AUTH_DESCOPEPROVIDER_REQUIRED_SCOPES": "read,write",
+            },
+        ):
+            provider = DescopeProvider(
+                config_url="https://api.descope.com/v1/apps/agentic/P2env123/M123/.well-known/openid-configuration",
+                base_url="https://envserver.com",
+                required_scopes=["read", "write"],
+            )
+
+            assert isinstance(provider.token_verifier, JWTVerifier)
+            assert provider.token_verifier.required_scopes == ["read", "write"]
+
+
+@pytest.fixture
+async def mcp_server_url():
+    """Start Descope server."""
+    mcp = FastMCP(
+        auth=DescopeProvider(
+            config_url="https://api.descope.com/v1/apps/agentic/P2test123/M123/.well-known/openid-configuration",
+            base_url="http://localhost:4321",
+        )
+    )
+
+    @mcp.tool
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    async with run_server_async(mcp, transport="http") as url:
+        yield url
+
+
+@pytest.fixture
+def client_with_headless_oauth(mcp_server_url: str) -> Client:
+    """Client with headless OAuth that bypasses browser interaction."""
+    return Client(
+        transport=StreamableHttpTransport(mcp_server_url),
+        auth=HeadlessOAuth(mcp_url=mcp_server_url),
+    )
+
+
+class TestDescopeProviderIntegration:
+    async def test_unauthorized_access(self, mcp_server_url: str):
+        # SDK v2 surfaces the server's 401 as a generic MCPError at the client
+        # boundary rather than re-raising httpx.HTTPStatusError.
+        with pytest.raises(MCPError):
+            async with Client(mcp_server_url) as client:
+                tools = await client.list_tools()  # noqa: F841
+        assert "tools" not in locals()
+
+    # async def test_authorized_access(self, client_with_headless_oauth: Client):
+    #     async with client_with_headless_oauth:
+    #         tools = await client_with_headless_oauth.list_tools()
+    #     assert tools is not None
+    #     assert len(tools) > 0
+    #     assert "add" in tools
diff --git a/tests/server/auth/providers/test_discord.py b/tests/server/auth/providers/test_discord.py
new file mode 100644
index 0000000..edf3ffd
--- /dev/null
+++ b/tests/server/auth/providers/test_discord.py
@@ -0,0 +1,128 @@
+"""Tests for Discord OAuth provider."""
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from key_value.aio.stores.memory import MemoryStore
+
+from fastmcp.server.auth.providers.discord import DiscordProvider, DiscordTokenVerifier
+
+
+@pytest.fixture
+def memory_storage() -> MemoryStore:
+    """Provide a MemoryStore for tests to avoid SQLite initialization on Windows."""
+    return MemoryStore()
+
+
+class TestDiscordProvider:
+    """Test Discord OAuth provider functionality."""
+
+    def test_init_with_explicit_params(self, memory_storage: MemoryStore):
+        """Test DiscordProvider initialization with explicit parameters."""
+        provider = DiscordProvider(
+            client_id="env_client_id",
+            client_secret="GOCSPX-test123",
+            base_url="https://myserver.com",
+            required_scopes=["email", "identify"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert provider._upstream_client_id == "env_client_id"
+        assert provider._upstream_client_secret is not None
+        assert provider._upstream_client_secret.get_secret_value() == "GOCSPX-test123"
+        assert str(provider.base_url) == "https://myserver.com/"
+
+    def test_init_defaults(self, memory_storage: MemoryStore):
+        """Test that default values are applied correctly."""
+        provider = DiscordProvider(
+            client_id="env_client_id",
+            client_secret="GOCSPX-test123",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Check defaults
+        assert provider._redirect_path == "/auth/callback"
+
+    def test_oauth_endpoints_configured_correctly(self, memory_storage: MemoryStore):
+        """Test that OAuth endpoints are configured correctly."""
+        provider = DiscordProvider(
+            client_id="env_client_id",
+            client_secret="GOCSPX-test123",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Check that endpoints use Discord's OAuth2 endpoints
+        assert (
+            provider._upstream_authorization_endpoint
+            == "https://discord.com/oauth2/authorize"
+        )
+        assert (
+            provider._upstream_token_endpoint == "https://discord.com/api/oauth2/token"
+        )
+        # Discord provider doesn't currently set a revocation endpoint
+        assert provider._upstream_revocation_endpoint is None
+
+    def test_discord_specific_scopes(self, memory_storage: MemoryStore):
+        """Test handling of Discord-specific scope formats."""
+        # Just test that the provider accepts Discord-specific scopes without error
+        provider = DiscordProvider(
+            client_id="env_client_id",
+            client_secret="GOCSPX-test123",
+            base_url="https://myserver.com",
+            required_scopes=[
+                "identify",
+                "email",
+            ],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Provider should initialize successfully with these scopes
+        assert provider is not None
+
+    def test_token_verifier_is_bound_to_provider_client_id(
+        self, memory_storage: MemoryStore
+    ):
+        """Test DiscordProvider binds token verifier to the configured client ID."""
+        provider = DiscordProvider(
+            client_id="expected-client-id",
+            client_secret="GOCSPX-test123",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        verifier = provider._token_validator
+        assert isinstance(verifier, DiscordTokenVerifier)
+        assert verifier.expected_client_id == "expected-client-id"
+
+
+class TestDiscordTokenVerifier:
+    """Test DiscordTokenVerifier behavior."""
+
+    async def test_rejects_token_from_different_discord_application(self):
+        """Token must be bound to configured Discord client_id."""
+        verifier = DiscordTokenVerifier(expected_client_id="expected-app-id")
+
+        mock_client = AsyncMock()
+        token_info_response = MagicMock()
+        token_info_response.status_code = 200
+        token_info_response.json.return_value = {
+            "application": {"id": "different-app-id"},
+            "user": {"id": "123"},
+            "scopes": ["identify"],
+        }
+        mock_client.get.return_value = token_info_response
+
+        with patch(
+            "fastmcp.server.auth.providers.discord.httpx.AsyncClient"
+        ) as mock_client_class:
+            mock_client_class.return_value.__aenter__.return_value = mock_client
+            result = await verifier.verify_token("token")
+
+        assert result is None
diff --git a/tests/server/auth/providers/test_github.py b/tests/server/auth/providers/test_github.py
new file mode 100644
index 0000000..a0cc4b9
--- /dev/null
+++ b/tests/server/auth/providers/test_github.py
@@ -0,0 +1,326 @@
+"""Unit tests for GitHub OAuth provider."""
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from key_value.aio.stores.memory import MemoryStore
+
+from fastmcp.server.auth.providers.github import (
+    GitHubProvider,
+    GitHubTokenVerifier,
+)
+
+
+@pytest.fixture
+def memory_storage() -> MemoryStore:
+    """Provide a MemoryStore for tests to avoid SQLite initialization on Windows."""
+    return MemoryStore()
+
+
+class TestGitHubProvider:
+    """Test GitHubProvider initialization."""
+
+    def test_init_with_explicit_params(self, memory_storage: MemoryStore):
+        """Test initialization with explicit parameters."""
+        provider = GitHubProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            base_url="https://example.com",
+            redirect_path="/custom/callback",
+            required_scopes=["user", "repo"],
+            timeout_seconds=30,
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Check that the provider was initialized correctly
+        assert provider._upstream_client_id == "test_client"
+        assert provider._upstream_client_secret is not None
+        assert provider._upstream_client_secret.get_secret_value() == "test_secret"
+        assert (
+            str(provider.base_url) == "https://example.com/"
+        )  # URLs get normalized with trailing slash
+        assert provider._redirect_path == "/custom/callback"
+
+    def test_init_defaults(self, memory_storage: MemoryStore):
+        """Test that default values are applied correctly."""
+        provider = GitHubProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            base_url="https://example.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Check defaults
+        assert provider._redirect_path == "/auth/callback"
+        # The required_scopes should be passed to the token verifier
+        assert provider._token_validator.required_scopes == ["user"]
+
+    def test_init_with_resource_base_url(self, memory_storage: MemoryStore):
+        """Test that resource_base_url overrides the advertised protected resource."""
+        provider = GitHubProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            base_url="https://auth.example.com/proxy",
+            resource_base_url="https://api.example.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        provider.set_mcp_path("/mcp")
+
+        assert str(provider.base_url) == "https://auth.example.com/proxy"
+        assert str(provider.resource_base_url) == "https://api.example.com/"
+        assert provider.jwt_issuer.audience == "https://api.example.com/mcp"
+
+
+class TestGitHubTokenVerifier:
+    """Test GitHubTokenVerifier."""
+
+    def test_init_with_custom_scopes(self, memory_storage: MemoryStore):
+        """Test initialization with custom required scopes."""
+        verifier = GitHubTokenVerifier(
+            required_scopes=["user", "repo"],
+            timeout_seconds=30,
+        )
+
+        assert verifier.required_scopes == ["user", "repo"]
+        assert verifier.timeout_seconds == 30
+
+    def test_init_defaults(self, memory_storage: MemoryStore):
+        """Test initialization with defaults."""
+        verifier = GitHubTokenVerifier()
+
+        assert (
+            verifier.required_scopes == []
+        )  # Parent TokenVerifier sets empty list as default
+        assert verifier.timeout_seconds == 10
+
+    async def test_verify_token_github_api_failure(self):
+        """Test token verification when GitHub API returns error."""
+        verifier = GitHubTokenVerifier()
+
+        # Mock httpx.AsyncClient to simulate GitHub API failure
+        with patch("httpx.AsyncClient") as mock_client_class:
+            mock_client = MagicMock()
+            mock_client_class.return_value.__aenter__.return_value = mock_client
+
+            # Simulate 401 response from GitHub
+            mock_response = MagicMock()
+            mock_response.status_code = 401
+            mock_response.text = "Bad credentials"
+            mock_client.get.return_value = mock_response
+
+            result = await verifier.verify_token("invalid_token")
+            assert result is None
+
+    async def test_verify_token_success(self):
+        """Test successful token verification."""
+        verifier = GitHubTokenVerifier(required_scopes=["user"])
+
+        # Mock the httpx.AsyncClient directly
+        mock_client = AsyncMock()
+
+        # Mock successful user API response
+        user_response = MagicMock()
+        user_response.status_code = 200
+        user_response.json.return_value = {
+            "id": 12345,
+            "login": "testuser",
+            "name": "Test User",
+            "email": "test@example.com",
+            "avatar_url": "https://github.com/testuser.png",
+        }
+
+        # Mock successful scopes API response
+        scopes_response = MagicMock()
+        scopes_response.headers = {"x-oauth-scopes": "user,repo"}
+
+        # Set up the mock client to return our responses
+        mock_client.get.side_effect = [user_response, scopes_response]
+
+        # Patch the AsyncClient context manager
+        with patch(
+            "fastmcp.server.auth.providers.github.httpx.AsyncClient"
+        ) as mock_client_class:
+            mock_client_class.return_value.__aenter__.return_value = mock_client
+
+            result = await verifier.verify_token("valid_token")
+
+            assert result is not None
+            assert result.token == "valid_token"
+            assert result.client_id == "12345"
+            assert result.scopes == ["user", "repo"]
+            assert result.claims["login"] == "testuser"
+            assert result.claims["name"] == "Test User"
+
+
+def _mock_github_success(mock_client: AsyncMock) -> None:
+    """Configure *mock_client* to return a successful GitHub user + scopes response."""
+    user_response = MagicMock()
+    user_response.status_code = 200
+    user_response.json.return_value = {
+        "id": 12345,
+        "login": "testuser",
+        "name": "Test User",
+        "email": "test@example.com",
+        "avatar_url": "https://github.com/testuser.png",
+    }
+
+    scopes_response = MagicMock()
+    scopes_response.status_code = 200
+    scopes_response.headers = {"x-oauth-scopes": "user,repo"}
+
+    mock_client.get.side_effect = [user_response, scopes_response]
+
+
+def _mock_github_failure(mock_client: AsyncMock) -> None:
+    """Configure *mock_client* to return a 401 GitHub response."""
+    fail_response = MagicMock()
+    fail_response.status_code = 401
+    fail_response.text = "Bad credentials"
+    mock_client.get.return_value = fail_response
+
+
+class TestGitHubTokenVerifierCaching:
+    """Test caching behaviour on GitHubTokenVerifier."""
+
+    def test_cache_disabled_by_default(self):
+        verifier = GitHubTokenVerifier()
+        assert not verifier._cache.enabled
+
+    def test_cache_enabled_with_ttl(self):
+        verifier = GitHubTokenVerifier(cache_ttl_seconds=300)
+        assert verifier._cache.enabled
+
+    async def test_cache_hit_avoids_second_api_call(self):
+        verifier = GitHubTokenVerifier(
+            required_scopes=["user"],
+            cache_ttl_seconds=300,
+        )
+
+        mock_client = AsyncMock()
+
+        with patch(
+            "fastmcp.server.auth.providers.github.httpx.AsyncClient"
+        ) as mock_cls:
+            mock_cls.return_value.__aenter__.return_value = mock_client
+
+            _mock_github_success(mock_client)
+            result1 = await verifier.verify_token("tok-1")
+            assert result1 is not None
+            assert mock_client.get.call_count == 2  # /user + /user/repos
+
+            result2 = await verifier.verify_token("tok-1")
+            assert result2 is not None
+            assert result2.client_id == result1.client_id
+            assert mock_client.get.call_count == 2  # no additional calls
+
+    async def test_cache_disabled_makes_every_call(self):
+        verifier = GitHubTokenVerifier(
+            required_scopes=["user"],
+            cache_ttl_seconds=0,
+        )
+
+        mock_client = AsyncMock()
+
+        with patch(
+            "fastmcp.server.auth.providers.github.httpx.AsyncClient"
+        ) as mock_cls:
+            mock_cls.return_value.__aenter__.return_value = mock_client
+
+            _mock_github_success(mock_client)
+            await verifier.verify_token("tok-1")
+            assert mock_client.get.call_count == 2
+
+            _mock_github_success(mock_client)
+            await verifier.verify_token("tok-1")
+            assert mock_client.get.call_count == 4
+
+    async def test_failures_are_not_cached(self):
+        verifier = GitHubTokenVerifier(cache_ttl_seconds=300)
+
+        mock_client = AsyncMock()
+
+        with patch(
+            "fastmcp.server.auth.providers.github.httpx.AsyncClient"
+        ) as mock_cls:
+            mock_cls.return_value.__aenter__.return_value = mock_client
+
+            _mock_github_failure(mock_client)
+            result1 = await verifier.verify_token("bad-tok")
+            assert result1 is None
+
+            _mock_github_success(mock_client)
+            result2 = await verifier.verify_token("bad-tok")
+            assert result2 is not None
+
+    async def test_cached_result_is_defensive_copy(self):
+        verifier = GitHubTokenVerifier(
+            required_scopes=["user"],
+            cache_ttl_seconds=300,
+        )
+
+        mock_client = AsyncMock()
+
+        with patch(
+            "fastmcp.server.auth.providers.github.httpx.AsyncClient"
+        ) as mock_cls:
+            mock_cls.return_value.__aenter__.return_value = mock_client
+
+            _mock_github_success(mock_client)
+            result1 = await verifier.verify_token("tok-1")
+            assert result1 is not None
+            result1.claims["login"] = "MUTATED"
+
+            result2 = await verifier.verify_token("tok-1")
+            assert result2 is not None
+            assert result2.claims["login"] == "testuser"
+
+    async def test_scope_failure_skips_cache(self):
+        """Token verified with fallback scopes (scope API failed) should not be cached."""
+        verifier = GitHubTokenVerifier(cache_ttl_seconds=300)
+
+        mock_client = AsyncMock()
+
+        user_response = MagicMock()
+        user_response.status_code = 200
+        user_response.json.return_value = {
+            "id": 12345,
+            "login": "testuser",
+            "name": "Test User",
+            "email": "test@example.com",
+            "avatar_url": "https://github.com/testuser.png",
+        }
+
+        scopes_response = MagicMock()
+        scopes_response.status_code = 500
+        scopes_response.headers = {}
+
+        with patch(
+            "fastmcp.server.auth.providers.github.httpx.AsyncClient"
+        ) as mock_cls:
+            mock_cls.return_value.__aenter__.return_value = mock_client
+
+            mock_client.get.side_effect = [user_response, scopes_response]
+            result = await verifier.verify_token("tok-1")
+            assert result is not None
+            # Should NOT be cached because scope response was not 200
+            assert not verifier._cache.enabled or len(verifier._cache._entries) == 0
+
+    def test_provider_passes_cache_params(self, memory_storage: MemoryStore):
+        provider = GitHubProvider(
+            client_id="cid",
+            client_secret="csec",
+            base_url="https://example.com",
+            cache_ttl_seconds=120,
+            max_cache_size=500,
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+        verifier = provider._token_validator
+        assert isinstance(verifier, GitHubTokenVerifier)
+        assert verifier._cache.enabled
+        assert verifier._cache._ttl == 120
+        assert verifier._cache._max_size == 500
diff --git a/tests/server/auth/providers/test_google.py b/tests/server/auth/providers/test_google.py
new file mode 100644
index 0000000..229f04a
--- /dev/null
+++ b/tests/server/auth/providers/test_google.py
@@ -0,0 +1,536 @@
+"""Tests for Google OAuth provider."""
+
+import re
+import time
+
+import pytest
+from key_value.aio.stores.memory import MemoryStore
+from pytest_httpx import HTTPXMock
+
+from fastmcp.server.auth.providers.google import (
+    GOOGLE_SCOPE_ALIASES,
+    GoogleProvider,
+    GoogleTokenVerifier,
+    _normalize_google_scope,
+)
+
+
+@pytest.fixture
+def memory_storage() -> MemoryStore:
+    """Provide a MemoryStore for tests to avoid SQLite initialization on Windows."""
+    return MemoryStore()
+
+
+class TestGoogleProvider:
+    """Test Google OAuth provider functionality."""
+
+    def test_init_with_explicit_params(self, memory_storage: MemoryStore):
+        """Test GoogleProvider initialization with explicit parameters."""
+        provider = GoogleProvider(
+            client_id="123456789.apps.googleusercontent.com",
+            client_secret="GOCSPX-test123",
+            base_url="https://myserver.com",
+            required_scopes=["openid", "email", "profile"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert provider._upstream_client_id == "123456789.apps.googleusercontent.com"
+        assert provider._upstream_client_secret is not None
+        assert provider._upstream_client_secret.get_secret_value() == "GOCSPX-test123"
+        assert str(provider.base_url) == "https://myserver.com/"
+
+    def test_init_defaults(self, memory_storage: MemoryStore):
+        """Test that default values are applied correctly."""
+        provider = GoogleProvider(
+            client_id="123456789.apps.googleusercontent.com",
+            client_secret="GOCSPX-test123",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Check defaults
+        assert provider._redirect_path == "/auth/callback"
+        # Google provider has ["openid"] as default but we can't easily verify without accessing internals
+
+    def test_oauth_endpoints_configured_correctly(self, memory_storage: MemoryStore):
+        """Test that OAuth endpoints are configured correctly."""
+        provider = GoogleProvider(
+            client_id="123456789.apps.googleusercontent.com",
+            client_secret="GOCSPX-test123",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Check that endpoints use Google's OAuth2 endpoints
+        assert (
+            provider._upstream_authorization_endpoint
+            == "https://accounts.google.com/o/oauth2/v2/auth"
+        )
+        assert (
+            provider._upstream_token_endpoint == "https://oauth2.googleapis.com/token"
+        )
+        # Google provider doesn't currently set a revocation endpoint
+        assert provider._upstream_revocation_endpoint is None
+
+    def test_google_specific_scopes(self, memory_storage: MemoryStore):
+        """Test handling of Google-specific scope formats."""
+        # Just test that the provider accepts Google-specific scopes without error
+        provider = GoogleProvider(
+            client_id="123456789.apps.googleusercontent.com",
+            client_secret="GOCSPX-test123",
+            base_url="https://myserver.com",
+            required_scopes=[
+                "openid",
+                "https://www.googleapis.com/auth/userinfo.email",
+                "https://www.googleapis.com/auth/userinfo.profile",
+            ],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Provider should initialize successfully with these scopes
+        assert provider is not None
+
+    def test_extra_authorize_params_defaults(self, memory_storage: MemoryStore):
+        """Test that Google-specific defaults are set for refresh token support."""
+        provider = GoogleProvider(
+            client_id="123456789.apps.googleusercontent.com",
+            client_secret="GOCSPX-test123",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Should have Google-specific defaults for refresh token support
+        assert provider._extra_authorize_params == {
+            "access_type": "offline",
+            "prompt": "consent",
+        }
+
+    def test_extra_authorize_params_override_defaults(
+        self, memory_storage: MemoryStore
+    ):
+        """Test that user can override default extra authorize params."""
+        provider = GoogleProvider(
+            client_id="123456789.apps.googleusercontent.com",
+            client_secret="GOCSPX-test123",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            extra_authorize_params={"prompt": "select_account"},
+            client_storage=memory_storage,
+        )
+
+        # User override should replace the default
+        assert provider._extra_authorize_params["prompt"] == "select_account"
+        # But other defaults should remain
+        assert provider._extra_authorize_params["access_type"] == "offline"
+
+    def test_extra_authorize_params_add_new_params(self, memory_storage: MemoryStore):
+        """Test that user can add additional authorize params."""
+        provider = GoogleProvider(
+            client_id="123456789.apps.googleusercontent.com",
+            client_secret="GOCSPX-test123",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            extra_authorize_params={"login_hint": "user@example.com"},
+            client_storage=memory_storage,
+        )
+
+        # New param should be added
+        assert provider._extra_authorize_params["login_hint"] == "user@example.com"
+        # Defaults should still be present
+        assert provider._extra_authorize_params["access_type"] == "offline"
+        assert provider._extra_authorize_params["prompt"] == "consent"
+
+    def test_valid_scopes_passed_through(self, memory_storage: MemoryStore):
+        """Test that valid_scopes is passed to OAuthProxy."""
+        provider = GoogleProvider(
+            client_id="123456789.apps.googleusercontent.com",
+            client_secret="GOCSPX-test123",
+            base_url="https://myserver.com",
+            required_scopes=["openid"],
+            valid_scopes=["openid", "email", "profile"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        reg_options = provider.client_registration_options
+        assert reg_options is not None
+        assert reg_options.valid_scopes is not None
+        # Shorthands should be normalized to full URIs
+        assert set(reg_options.valid_scopes) == {
+            "openid",
+            "https://www.googleapis.com/auth/userinfo.email",
+            "https://www.googleapis.com/auth/userinfo.profile",
+        }
+
+    def test_valid_scopes_defaults_to_required(self, memory_storage: MemoryStore):
+        """Test that valid_scopes defaults to required_scopes when not provided."""
+        provider = GoogleProvider(
+            client_id="123456789.apps.googleusercontent.com",
+            client_secret="GOCSPX-test123",
+            base_url="https://myserver.com",
+            required_scopes=["openid", "email"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        reg_options = provider.client_registration_options
+        assert reg_options is not None
+        assert reg_options.valid_scopes is not None
+        # Should fall back to the (normalized) required_scopes
+        assert set(reg_options.valid_scopes) == {
+            "openid",
+            "https://www.googleapis.com/auth/userinfo.email",
+        }
+
+
+class TestGoogleScopeNormalization:
+    """Test Google scope shorthand normalization."""
+
+    @pytest.mark.parametrize(
+        "shorthand, expected",
+        [
+            ("email", "https://www.googleapis.com/auth/userinfo.email"),
+            ("profile", "https://www.googleapis.com/auth/userinfo.profile"),
+            ("openid", "openid"),
+            (
+                "https://www.googleapis.com/auth/userinfo.email",
+                "https://www.googleapis.com/auth/userinfo.email",
+            ),
+            (
+                "https://www.googleapis.com/auth/calendar",
+                "https://www.googleapis.com/auth/calendar",
+            ),
+        ],
+    )
+    def test_normalize_google_scope(self, shorthand: str, expected: str):
+        assert _normalize_google_scope(shorthand) == expected
+
+    def test_verifier_normalizes_required_scopes(self):
+        """GoogleTokenVerifier should normalize shorthands in required_scopes."""
+        verifier = GoogleTokenVerifier(
+            required_scopes=["openid", "email", "profile"],
+        )
+
+        assert set(verifier.required_scopes) == {
+            "openid",
+            "https://www.googleapis.com/auth/userinfo.email",
+            "https://www.googleapis.com/auth/userinfo.profile",
+        }
+
+    def test_verifier_full_uris_unchanged(self):
+        """Full URIs should pass through normalization unchanged."""
+        scopes = [
+            "openid",
+            "https://www.googleapis.com/auth/userinfo.email",
+        ]
+        verifier = GoogleTokenVerifier(required_scopes=scopes)
+        assert verifier.required_scopes == scopes
+
+    def test_alias_map_is_bidirectional(self):
+        """Verify the alias map covers the known Google shorthands."""
+        assert "email" in GOOGLE_SCOPE_ALIASES
+        assert "profile" in GOOGLE_SCOPE_ALIASES
+
+
+# Regex patterns for URL matching (tokeninfo uses query params)
+_TOKENINFO_RE = re.compile(r"https://oauth2\.googleapis\.com/tokeninfo")
+_USERINFO_RE = re.compile(r"https://www\.googleapis\.com/oauth2/v2/userinfo")
+
+
+class TestGoogleTokenVerifier:
+    """Test GoogleTokenVerifier.verify_token() using the tokeninfo endpoint."""
+
+    TOKENINFO_URL = "https://oauth2.googleapis.com/tokeninfo"
+    USERINFO_URL = "https://www.googleapis.com/oauth2/v2/userinfo"
+
+    async def test_valid_token_openid_only(self, httpx_mock: HTTPXMock):
+        """A token with only openid scope is accepted; client_id comes from 'sub'."""
+        httpx_mock.add_response(
+            url=_TOKENINFO_RE,
+            json={
+                "aud": "123.apps.googleusercontent.com",
+                "sub": "12345",
+                "scope": "openid",
+                "expires_in": "3600",
+            },
+        )
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={"sub": "12345"},
+        )
+
+        verifier = GoogleTokenVerifier()
+        result = await verifier.verify_token("valid-token")
+
+        assert result is not None
+        assert result.client_id == "12345"
+        assert result.scopes == ["openid"]
+        assert result.expires_at is not None
+        assert result.claims["sub"] == "12345"
+        assert result.claims["aud"] == "123.apps.googleusercontent.com"
+
+    async def test_valid_token_with_email_and_profile(self, httpx_mock: HTTPXMock):
+        """A token with email+profile scope returns correct scopes and profile claims."""
+        httpx_mock.add_response(
+            url=_TOKENINFO_RE,
+            json={
+                "aud": "123.apps.googleusercontent.com",
+                "sub": "12345",
+                "email": "user@example.com",
+                "email_verified": "true",
+                "scope": "openid https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile",
+                "expires_in": "3600",
+            },
+        )
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={
+                "sub": "12345",
+                "email": "user@example.com",
+                "verified_email": True,
+                "name": "Test User",
+                "picture": "https://example.com/photo.jpg",
+                "given_name": "Test",
+                "family_name": "User",
+                "locale": "en",
+            },
+        )
+
+        verifier = GoogleTokenVerifier()
+        result = await verifier.verify_token("valid-token")
+
+        assert result is not None
+        assert result.client_id == "12345"
+        assert "openid" in result.scopes
+        assert "https://www.googleapis.com/auth/userinfo.email" in result.scopes
+        assert "https://www.googleapis.com/auth/userinfo.profile" in result.scopes
+        assert result.claims["email"] == "user@example.com"
+        assert result.claims["name"] == "Test User"
+        assert result.claims["picture"] == "https://example.com/photo.jpg"
+
+    async def test_expired_or_invalid_token_returns_none(self, httpx_mock: HTTPXMock):
+        """HTTP 400 from tokeninfo endpoint causes verify_token to return None."""
+        httpx_mock.add_response(
+            url=_TOKENINFO_RE,
+            status_code=400,
+            json={
+                "error": "invalid_token",
+                "error_description": "Token has been expired or revoked.",
+            },
+        )
+
+        verifier = GoogleTokenVerifier()
+        result = await verifier.verify_token("expired-token")
+
+        assert result is None
+
+    async def test_missing_aud_returns_none(self, httpx_mock: HTTPXMock):
+        """A 200 response without 'aud' is rejected."""
+        httpx_mock.add_response(
+            url=_TOKENINFO_RE,
+            json={"sub": "12345", "scope": "openid", "expires_in": "3600"},
+        )
+
+        verifier = GoogleTokenVerifier()
+        result = await verifier.verify_token("token-without-aud")
+
+        assert result is None
+
+    async def test_missing_sub_returns_none(self, httpx_mock: HTTPXMock):
+        """A 200 response without 'sub' is rejected."""
+        httpx_mock.add_response(
+            url=_TOKENINFO_RE,
+            json={
+                "aud": "123.apps.googleusercontent.com",
+                "scope": "openid",
+                "expires_in": "3600",
+            },
+        )
+
+        verifier = GoogleTokenVerifier()
+        result = await verifier.verify_token("token-without-sub")
+
+        assert result is None
+
+    async def test_required_scopes_satisfied(self, httpx_mock: HTTPXMock):
+        """Token with required scopes passes the scope check."""
+        httpx_mock.add_response(
+            url=_TOKENINFO_RE,
+            json={
+                "aud": "123.apps.googleusercontent.com",
+                "sub": "12345",
+                "email": "user@example.com",
+                "scope": "openid https://www.googleapis.com/auth/userinfo.email",
+                "expires_in": "3600",
+            },
+        )
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={"sub": "12345", "email": "user@example.com"},
+        )
+
+        verifier = GoogleTokenVerifier(
+            required_scopes=["openid", "email"],
+        )
+        result = await verifier.verify_token("valid-token")
+
+        assert result is not None
+
+    async def test_required_scopes_not_satisfied_returns_none(
+        self, httpx_mock: HTTPXMock
+    ):
+        """Token without required scopes is rejected."""
+        httpx_mock.add_response(
+            url=_TOKENINFO_RE,
+            json={
+                "aud": "123.apps.googleusercontent.com",
+                "sub": "12345",
+                "scope": "openid",
+                "expires_in": "3600",
+            },
+        )
+
+        verifier = GoogleTokenVerifier(
+            required_scopes=[
+                "openid",
+                "https://www.googleapis.com/auth/userinfo.email",
+            ],
+        )
+        result = await verifier.verify_token("token-missing-email-scope")
+
+        assert result is None
+
+    async def test_uses_query_param_not_bearer_header(self, httpx_mock: HTTPXMock):
+        """verify_token sends the token as a query parameter to tokeninfo, not a Bearer header."""
+        httpx_mock.add_response(
+            url=_TOKENINFO_RE,
+            json={
+                "aud": "123.apps.googleusercontent.com",
+                "sub": "12345",
+                "scope": "openid",
+                "expires_in": "3600",
+            },
+        )
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={"sub": "12345"},
+        )
+
+        verifier = GoogleTokenVerifier()
+        await verifier.verify_token("my-access-token")
+
+        requests = httpx_mock.get_requests()
+        tokeninfo_req = requests[0]
+        assert "access_token=my-access-token" in str(tokeninfo_req.url)
+        assert "Authorization" not in tokeninfo_req.headers
+
+    async def test_calls_tokeninfo_endpoint(self, httpx_mock: HTTPXMock):
+        """verify_token calls the tokeninfo endpoint, not the userinfo endpoint, for verification."""
+        httpx_mock.add_response(
+            url=_TOKENINFO_RE,
+            json={
+                "aud": "123.apps.googleusercontent.com",
+                "sub": "12345",
+                "scope": "openid",
+                "expires_in": "3600",
+            },
+        )
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={"sub": "12345"},
+        )
+
+        verifier = GoogleTokenVerifier()
+        await verifier.verify_token("valid-token")
+
+        requests = httpx_mock.get_requests()
+        assert len(requests) >= 1
+        assert "tokeninfo" in str(requests[0].url)
+        assert "oauth2.googleapis.com" in str(requests[0].url)
+
+    async def test_expires_at_computed_from_expires_in(self, httpx_mock: HTTPXMock):
+        """expires_at is set from expires_in returned by tokeninfo."""
+        httpx_mock.add_response(
+            url=_TOKENINFO_RE,
+            json={
+                "aud": "123.apps.googleusercontent.com",
+                "sub": "12345",
+                "scope": "openid",
+                "expires_in": "3600",
+            },
+        )
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={"sub": "12345"},
+        )
+
+        before = int(time.time())
+        verifier = GoogleTokenVerifier()
+        result = await verifier.verify_token("valid-token")
+        after = int(time.time())
+
+        assert result is not None
+        assert result.expires_at is not None
+        assert before + 3600 <= result.expires_at <= after + 3600
+
+    async def test_profile_data_fetched_from_userinfo(self, httpx_mock: HTTPXMock):
+        """Profile data (name, picture, locale) comes from the v2 userinfo endpoint."""
+        httpx_mock.add_response(
+            url=_TOKENINFO_RE,
+            json={
+                "aud": "123.apps.googleusercontent.com",
+                "sub": "12345",
+                "scope": "openid https://www.googleapis.com/auth/userinfo.profile",
+                "expires_in": "3600",
+            },
+        )
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={
+                "sub": "12345",
+                "name": "Test User",
+                "picture": "https://example.com/photo.jpg",
+                "given_name": "Test",
+                "family_name": "User",
+                "locale": "en",
+            },
+        )
+
+        verifier = GoogleTokenVerifier()
+        result = await verifier.verify_token("valid-token")
+
+        assert result is not None
+        assert result.claims["name"] == "Test User"
+        assert result.claims["picture"] == "https://example.com/photo.jpg"
+        assert result.claims["given_name"] == "Test"
+        assert result.claims["family_name"] == "User"
+        assert result.claims["locale"] == "en"
+
+    async def test_non_openid_scopes_checked_correctly(self, httpx_mock: HTTPXMock):
+        """Calendar scope is correctly checked from the tokeninfo scope string."""
+        httpx_mock.add_response(
+            url=_TOKENINFO_RE,
+            json={
+                "aud": "123.apps.googleusercontent.com",
+                "sub": "12345",
+                "scope": "openid https://www.googleapis.com/auth/calendar",
+                "expires_in": "3600",
+            },
+        )
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={"sub": "12345"},
+        )
+
+        verifier = GoogleTokenVerifier(
+            required_scopes=["openid", "https://www.googleapis.com/auth/calendar"],
+        )
+        result = await verifier.verify_token("valid-token")
+
+        assert result is not None
+        assert "https://www.googleapis.com/auth/calendar" in result.scopes
diff --git a/tests/server/auth/providers/test_http_client.py b/tests/server/auth/providers/test_http_client.py
new file mode 100644
index 0000000..1fc9b62
--- /dev/null
+++ b/tests/server/auth/providers/test_http_client.py
@@ -0,0 +1,367 @@
+"""Tests for http_client parameter on token verifiers.
+
+Verifies that all token verifiers accept an optional httpx.AsyncClient for
+connection pooling (issues #3287 and #3293).
+"""
+
+import time
+
+import httpx
+import pytest
+from joserfc import jwk
+from pytest_httpx import HTTPXMock
+
+from fastmcp.server.auth.providers.introspection import IntrospectionTokenVerifier
+from fastmcp.server.auth.providers.jwt import JWTVerifier, RSAKeyPair
+
+
+class TestIntrospectionHttpClient:
+    """Test http_client parameter on IntrospectionTokenVerifier."""
+
+    @pytest.fixture
+    def shared_client(self) -> httpx.AsyncClient:
+        return httpx.AsyncClient(timeout=30)
+
+    def test_stores_http_client(self, shared_client: httpx.AsyncClient):
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/introspect",
+            client_id="test",
+            client_secret="secret",
+            http_client=shared_client,
+        )
+        assert verifier._http_client is shared_client
+
+    def test_default_http_client_is_none(self):
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/introspect",
+            client_id="test",
+            client_secret="secret",
+        )
+        assert verifier._http_client is None
+
+    async def test_uses_provided_client(
+        self, shared_client: httpx.AsyncClient, httpx_mock: HTTPXMock
+    ):
+        """When http_client is provided, it should be used for requests."""
+        httpx_mock.add_response(
+            url="https://auth.example.com/introspect",
+            method="POST",
+            json={
+                "active": True,
+                "client_id": "user-1",
+                "scope": "read",
+                "exp": int(time.time()) + 3600,
+            },
+        )
+
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/introspect",
+            client_id="test",
+            client_secret="secret",
+            http_client=shared_client,
+        )
+
+        result = await verifier.verify_token("tok")
+        assert result is not None
+        assert result.client_id == "user-1"
+
+    async def test_client_not_closed_after_call(
+        self, shared_client: httpx.AsyncClient, httpx_mock: HTTPXMock
+    ):
+        """User-provided client must not be closed by the verifier."""
+        httpx_mock.add_response(
+            url="https://auth.example.com/introspect",
+            method="POST",
+            json={
+                "active": True,
+                "client_id": "user-1",
+                "scope": "read",
+                "exp": int(time.time()) + 3600,
+            },
+        )
+
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/introspect",
+            client_id="test",
+            client_secret="secret",
+            http_client=shared_client,
+        )
+
+        await verifier.verify_token("tok")
+        # Client should still be open — not closed by the verifier
+        assert not shared_client.is_closed
+
+    async def test_reuses_client_across_calls(
+        self, shared_client: httpx.AsyncClient, httpx_mock: HTTPXMock
+    ):
+        """Same client instance should be reused across multiple verify_token calls."""
+        for _ in range(3):
+            httpx_mock.add_response(
+                url="https://auth.example.com/introspect",
+                method="POST",
+                json={
+                    "active": True,
+                    "client_id": "user-1",
+                    "scope": "read",
+                    "exp": int(time.time()) + 3600,
+                },
+            )
+
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/introspect",
+            client_id="test",
+            client_secret="secret",
+            http_client=shared_client,
+        )
+
+        for _ in range(3):
+            result = await verifier.verify_token("tok")
+            assert result is not None
+
+        assert not shared_client.is_closed
+
+
+class TestJWTVerifierHttpClient:
+    """Test http_client parameter on JWTVerifier."""
+
+    @pytest.fixture(scope="class")
+    def rsa_key_pair(self) -> RSAKeyPair:
+        return RSAKeyPair.generate()
+
+    @pytest.fixture
+    def shared_client(self) -> httpx.AsyncClient:
+        return httpx.AsyncClient(timeout=30)
+
+    def test_stores_http_client(self, shared_client: httpx.AsyncClient):
+        verifier = JWTVerifier(
+            jwks_uri="https://auth.example.com/.well-known/jwks.json",
+            http_client=shared_client,
+        )
+        assert verifier._http_client is shared_client
+
+    def test_default_http_client_is_none(self):
+        verifier = JWTVerifier(
+            jwks_uri="https://auth.example.com/.well-known/jwks.json",
+        )
+        assert verifier._http_client is None
+
+    async def test_jwks_fetch_uses_provided_client(
+        self,
+        rsa_key_pair: RSAKeyPair,
+        shared_client: httpx.AsyncClient,
+        httpx_mock: HTTPXMock,
+    ):
+        """When http_client is provided, JWKS fetches should use it."""
+        # Build a JWKS response from the RSA key pair
+        public_key_obj = jwk.import_key(rsa_key_pair.public_key, "RSA")
+        jwk_dict = dict(public_key_obj.as_dict())
+        jwk_dict["kid"] = "test-key-1"
+        jwk_dict["use"] = "sig"
+        jwk_dict["alg"] = "RS256"
+
+        httpx_mock.add_response(
+            url="https://auth.example.com/.well-known/jwks.json",
+            json={"keys": [jwk_dict]},
+        )
+
+        verifier = JWTVerifier(
+            jwks_uri="https://auth.example.com/.well-known/jwks.json",
+            issuer="https://auth.example.com",
+            http_client=shared_client,
+        )
+
+        token = rsa_key_pair.create_token(
+            issuer="https://auth.example.com",
+            kid="test-key-1",
+        )
+
+        result = await verifier.verify_token(token)
+        assert result is not None
+        assert not shared_client.is_closed
+
+    def test_ssrf_safe_rejects_http_client_with_jwks(
+        self,
+        shared_client: httpx.AsyncClient,
+    ):
+        """ssrf_safe=True and http_client cannot be used together with JWKS."""
+        with pytest.raises(ValueError, match="cannot be used with ssrf_safe=True"):
+            JWTVerifier(
+                jwks_uri="https://auth.example.com/.well-known/jwks.json",
+                ssrf_safe=True,
+                http_client=shared_client,
+            )
+
+    def test_ssrf_safe_allows_http_client_with_static_key(
+        self,
+        rsa_key_pair: RSAKeyPair,
+        shared_client: httpx.AsyncClient,
+    ):
+        """ssrf_safe with http_client is allowed when using static public_key (no HTTP)."""
+        # This should NOT raise — static key means no JWKS fetching
+        verifier = JWTVerifier(
+            public_key=rsa_key_pair.public_key,
+            ssrf_safe=True,
+            http_client=shared_client,
+        )
+        assert verifier._http_client is shared_client
+        assert verifier.ssrf_safe is True
+
+
+class TestGitHubHttpClient:
+    """Test http_client parameter on GitHubTokenVerifier."""
+
+    def test_stores_http_client(self):
+        from fastmcp.server.auth.providers.github import GitHubTokenVerifier
+
+        client = httpx.AsyncClient()
+        verifier = GitHubTokenVerifier(http_client=client)
+        assert verifier._http_client is client
+
+    async def test_uses_provided_client(self, httpx_mock: HTTPXMock):
+        from fastmcp.server.auth.providers.github import GitHubTokenVerifier
+
+        client = httpx.AsyncClient()
+        httpx_mock.add_response(
+            url="https://api.github.com/user",
+            json={"id": 123, "login": "testuser"},
+        )
+        httpx_mock.add_response(
+            url="https://api.github.com/user/repos",
+            headers={"x-oauth-scopes": "user,repo"},
+            json=[],
+        )
+
+        verifier = GitHubTokenVerifier(http_client=client)
+        result = await verifier.verify_token("ghp_test")
+        assert result is not None
+        assert not client.is_closed
+
+
+class TestDiscordHttpClient:
+    """Test http_client parameter on DiscordTokenVerifier."""
+
+    def test_stores_http_client(self):
+        from fastmcp.server.auth.providers.discord import DiscordTokenVerifier
+
+        client = httpx.AsyncClient()
+        verifier = DiscordTokenVerifier(
+            expected_client_id="test-client-id",
+            http_client=client,
+        )
+        assert verifier._http_client is client
+
+
+class TestGoogleHttpClient:
+    """Test http_client parameter on GoogleTokenVerifier."""
+
+    def test_stores_http_client(self):
+        from fastmcp.server.auth.providers.google import GoogleTokenVerifier
+
+        client = httpx.AsyncClient()
+        verifier = GoogleTokenVerifier(http_client=client)
+        assert verifier._http_client is client
+
+
+class TestWorkOSHttpClient:
+    """Test http_client parameter on WorkOSTokenVerifier."""
+
+    def test_stores_http_client(self):
+        from fastmcp.server.auth.providers.workos import WorkOSTokenVerifier
+
+        client = httpx.AsyncClient()
+        verifier = WorkOSTokenVerifier(
+            authkit_domain="https://test.authkit.app",
+            http_client=client,
+        )
+        assert verifier._http_client is client
+
+
+class TestProviderHttpClientPassthrough:
+    """Test that convenience providers pass http_client to their verifiers."""
+
+    def test_github_provider_threads_http_client(self):
+        from fastmcp.server.auth.providers.github import (
+            GitHubProvider,
+            GitHubTokenVerifier,
+        )
+
+        client = httpx.AsyncClient()
+        provider = GitHubProvider(
+            client_id="test",
+            client_secret="secret",
+            base_url="https://example.com",
+            http_client=client,
+        )
+        # OAuthProxy stores token verifier as _token_validator
+        verifier = provider._token_validator
+        assert isinstance(verifier, GitHubTokenVerifier)
+        assert verifier._http_client is client
+
+    def test_discord_provider_threads_http_client(self):
+        from fastmcp.server.auth.providers.discord import (
+            DiscordProvider,
+            DiscordTokenVerifier,
+        )
+
+        client = httpx.AsyncClient()
+        provider = DiscordProvider(
+            client_id="test",
+            client_secret="secret",
+            base_url="https://example.com",
+            http_client=client,
+        )
+        verifier = provider._token_validator
+        assert isinstance(verifier, DiscordTokenVerifier)
+        assert verifier._http_client is client
+
+    def test_google_provider_threads_http_client(self):
+        from fastmcp.server.auth.providers.google import (
+            GoogleProvider,
+            GoogleTokenVerifier,
+        )
+
+        client = httpx.AsyncClient()
+        provider = GoogleProvider(
+            client_id="test",
+            client_secret="secret",
+            base_url="https://example.com",
+            http_client=client,
+        )
+        verifier = provider._token_validator
+        assert isinstance(verifier, GoogleTokenVerifier)
+        assert verifier._http_client is client
+
+    def test_workos_provider_threads_http_client(self):
+        from fastmcp.server.auth.providers.workos import (
+            WorkOSProvider,
+            WorkOSTokenVerifier,
+        )
+
+        client = httpx.AsyncClient()
+        provider = WorkOSProvider(
+            client_id="test",
+            client_secret="secret",
+            authkit_domain="https://test.authkit.app",
+            base_url="https://example.com",
+            http_client=client,
+        )
+        verifier = provider._token_validator
+        assert isinstance(verifier, WorkOSTokenVerifier)
+        assert verifier._http_client is client
+
+    def test_azure_provider_threads_http_client(self):
+        from fastmcp.server.auth.providers.azure import AzureProvider
+        from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+        client = httpx.AsyncClient()
+        provider = AzureProvider(
+            client_id="test-client-id",
+            client_secret="secret",
+            tenant_id="test-tenant-id",
+            required_scopes=["read"],
+            base_url="https://example.com",
+            http_client=client,
+        )
+        verifier = provider._token_validator
+        assert isinstance(verifier, JWTVerifier)
+        assert verifier._http_client is client
diff --git a/tests/server/auth/providers/test_huggingface.py b/tests/server/auth/providers/test_huggingface.py
new file mode 100644
index 0000000..4f5808d
--- /dev/null
+++ b/tests/server/auth/providers/test_huggingface.py
@@ -0,0 +1,236 @@
+"""Tests for Hugging Face OAuth provider."""
+
+import re
+
+import pytest
+from key_value.aio.stores.memory import MemoryStore
+from pytest_httpx import HTTPXMock
+
+from fastmcp.server.auth.providers.huggingface import (
+    DEFAULT_HUGGINGFACE_SCOPES,
+    HUGGINGFACE_AUTHORIZATION_ENDPOINT,
+    HUGGINGFACE_TOKEN_ENDPOINT,
+    HUGGINGFACE_USERINFO_ENDPOINT,
+    HUGGINGFACE_WHOAMI_ENDPOINT,
+    HuggingFaceProvider,
+    HuggingFaceTokenVerifier,
+)
+
+
+@pytest.fixture
+def memory_storage() -> MemoryStore:
+    """Provide a MemoryStore for tests to avoid SQLite initialization on Windows."""
+    return MemoryStore()
+
+
+_USERINFO_RE = re.compile(re.escape(HUGGINGFACE_USERINFO_ENDPOINT))
+_WHOAMI_RE = re.compile(re.escape(HUGGINGFACE_WHOAMI_ENDPOINT))
+
+
+class TestHuggingFaceProvider:
+    """Test HuggingFaceProvider functionality."""
+
+    def test_init_with_explicit_params(self, memory_storage: MemoryStore):
+        provider = HuggingFaceProvider(
+            client_id="hf-client-id",
+            client_secret="hf-client-secret",
+            base_url="https://myserver.com",
+            required_scopes=["openid", "profile", "inference-api"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert provider._upstream_client_id == "hf-client-id"
+        assert provider._upstream_client_secret is not None
+        assert provider._upstream_client_secret.get_secret_value() == "hf-client-secret"
+        assert str(provider.base_url) == "https://myserver.com/"
+
+    def test_init_defaults(self, memory_storage: MemoryStore):
+        provider = HuggingFaceProvider(
+            client_id="hf-client-id",
+            client_secret="hf-client-secret",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert provider._redirect_path == "/auth/callback"
+        assert provider.required_scopes == DEFAULT_HUGGINGFACE_SCOPES
+        assert provider._token_validator.required_scopes == []
+
+    def test_oauth_endpoints_configured_correctly(self, memory_storage: MemoryStore):
+        provider = HuggingFaceProvider(
+            client_id="hf-client-id",
+            client_secret="hf-client-secret",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert (
+            provider._upstream_authorization_endpoint
+            == HUGGINGFACE_AUTHORIZATION_ENDPOINT
+        )
+        assert provider._upstream_token_endpoint == HUGGINGFACE_TOKEN_ENDPOINT
+        assert provider._upstream_revocation_endpoint is None
+
+    def test_public_pkce_app_uses_none_token_auth(self, memory_storage: MemoryStore):
+        provider = HuggingFaceProvider(
+            client_id="https://client.example.com/.well-known/oauth-cimd",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert provider._upstream_client_secret is None
+        assert provider._token_endpoint_auth_method == "none"
+
+    def test_uses_upstream_token_response_scopes(self, memory_storage: MemoryStore):
+        provider = HuggingFaceProvider(
+            client_id="hf-client-id",
+            client_secret="hf-client-secret",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert provider._uses_alternate_verification() is True
+
+    def test_valid_scopes_passed_through(self, memory_storage: MemoryStore):
+        provider = HuggingFaceProvider(
+            client_id="hf-client-id",
+            client_secret="hf-client-secret",
+            base_url="https://myserver.com",
+            required_scopes=["openid", "profile"],
+            valid_scopes=["openid", "profile", "inference-api", "jobs"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        reg_options = provider.client_registration_options
+        assert reg_options is not None
+        assert reg_options.valid_scopes == [
+            "openid",
+            "profile",
+            "inference-api",
+            "jobs",
+        ]
+
+
+class TestHuggingFaceTokenVerifier:
+    """Test HuggingFaceTokenVerifier.verify_token()."""
+
+    async def test_valid_token_with_userinfo_scopes(self, httpx_mock: HTTPXMock):
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={
+                "sub": "user-123",
+                "preferred_username": "alice",
+                "name": "Alice",
+                "email": "alice@example.com",
+                "email_verified": True,
+                "picture": "https://huggingface.co/alice.png",
+                "scope": "openid profile email",
+            },
+        )
+
+        verifier = HuggingFaceTokenVerifier(required_scopes=["openid", "email"])
+        result = await verifier.verify_token("hf_oauth_token")
+
+        assert result is not None
+        assert result.client_id == "user-123"
+        assert result.scopes == ["openid", "profile", "email"]
+        assert result.claims["sub"] == "user-123"
+        assert result.claims["preferred_username"] == "alice"
+        assert result.claims["email"] == "alice@example.com"
+
+    async def test_valid_token_with_whoami_scopes(self, httpx_mock: HTTPXMock):
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={
+                "sub": "user-123",
+                "preferred_username": "alice",
+                "scope": "openid profile",
+            },
+        )
+        httpx_mock.add_response(
+            url=_WHOAMI_RE,
+            json={
+                "name": "alice",
+                "auth": {
+                    "accessToken": {"scopes": ["openid", "profile", "inference-api"]}
+                },
+            },
+        )
+
+        verifier = HuggingFaceTokenVerifier(required_scopes=["openid", "inference-api"])
+        result = await verifier.verify_token("hf_oauth_token")
+
+        assert result is not None
+        assert result.scopes == ["openid", "profile", "inference-api"]
+        assert result.claims["huggingface_whoami"] is not None
+
+    async def test_defaults_scopes_when_userinfo_has_no_scope(
+        self, httpx_mock: HTTPXMock
+    ):
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={"sub": "user-123", "preferred_username": "alice"},
+        )
+        httpx_mock.add_response(url=_WHOAMI_RE, status_code=404)
+
+        verifier = HuggingFaceTokenVerifier()
+        result = await verifier.verify_token("hf_oauth_token")
+
+        assert result is not None
+        assert result.scopes == DEFAULT_HUGGINGFACE_SCOPES
+
+    async def test_missing_required_scope_returns_none(self, httpx_mock: HTTPXMock):
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={
+                "sub": "user-123",
+                "scope": "openid profile",
+            },
+        )
+        httpx_mock.add_response(url=_WHOAMI_RE, json={"name": "alice"})
+
+        verifier = HuggingFaceTokenVerifier(required_scopes=["inference-api"])
+        result = await verifier.verify_token("hf_oauth_token")
+
+        assert result is None
+
+    async def test_invalid_token_returns_none(self, httpx_mock: HTTPXMock):
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            status_code=401,
+            json={"error": "invalid_token"},
+        )
+
+        verifier = HuggingFaceTokenVerifier()
+        result = await verifier.verify_token("invalid")
+
+        assert result is None
+
+    async def test_missing_sub_returns_none(self, httpx_mock: HTTPXMock):
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={"preferred_username": "alice"},
+        )
+
+        verifier = HuggingFaceTokenVerifier()
+        result = await verifier.verify_token("token-without-sub")
+
+        assert result is None
+
+    async def test_sends_bearer_token_to_userinfo(self, httpx_mock: HTTPXMock):
+        httpx_mock.add_response(
+            url=_USERINFO_RE,
+            json={"sub": "user-123", "scope": "openid profile"},
+        )
+
+        verifier = HuggingFaceTokenVerifier()
+        await verifier.verify_token("hf_oauth_token")
+
+        request = httpx_mock.get_requests()[0]
+        assert request.headers["Authorization"] == "Bearer hf_oauth_token"
diff --git a/tests/server/auth/providers/test_introspection.py b/tests/server/auth/providers/test_introspection.py
new file mode 100644
index 0000000..46dcd2f
--- /dev/null
+++ b/tests/server/auth/providers/test_introspection.py
@@ -0,0 +1,977 @@
+"""Tests for OAuth 2.0 Token Introspection verifier (RFC 7662)."""
+
+import base64
+import time
+from typing import Any
+
+import pytest
+from pytest_httpx import HTTPXMock
+
+from fastmcp.server.auth.providers.introspection import (
+    IntrospectionTokenVerifier,
+)
+
+
+class TestIntrospectionTokenVerifier:
+    """Test core token verification logic."""
+
+    @pytest.fixture
+    def verifier(self) -> IntrospectionTokenVerifier:
+        """Create a basic introspection verifier for testing."""
+        return IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="test-client",
+            client_secret="test-secret",
+            timeout_seconds=5,
+        )
+
+    @pytest.fixture
+    def verifier_with_required_scopes(self) -> IntrospectionTokenVerifier:
+        """Create verifier with required scopes."""
+        return IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="test-client",
+            client_secret="test-secret",
+            required_scopes=["read", "write"],
+        )
+
+    def test_initialization(self):
+        """Test verifier initialization."""
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="test-client",
+            client_secret="test-secret",
+        )
+
+        assert verifier.introspection_url == "https://auth.example.com/oauth/introspect"
+        assert verifier.client_id == "test-client"
+        assert verifier.client_secret == "test-secret"
+        assert verifier.timeout_seconds == 10
+        assert verifier.client_auth_method == "client_secret_basic"
+
+    def test_initialization_requires_introspection_url(self):
+        """Test that introspection_url is required."""
+        with pytest.raises(TypeError):
+            IntrospectionTokenVerifier(  # ty: ignore[missing-argument]
+                client_id="test-client",
+                client_secret="test-secret",
+            )
+
+    def test_initialization_requires_client_id(self):
+        """Test that client_id is required."""
+        with pytest.raises(TypeError):
+            IntrospectionTokenVerifier(  # ty: ignore[missing-argument]
+                introspection_url="https://auth.example.com/oauth/introspect",
+                client_secret="test-secret",
+            )
+
+    def test_initialization_requires_client_secret(self):
+        """Test that client_secret is required."""
+        with pytest.raises(TypeError):
+            IntrospectionTokenVerifier(  # ty: ignore[missing-argument]
+                introspection_url="https://auth.example.com/oauth/introspect",
+                client_id="test-client",
+            )
+
+    def test_create_basic_auth_header(self, verifier: IntrospectionTokenVerifier):
+        """Test HTTP Basic Auth header creation."""
+        auth_header = verifier._create_basic_auth_header()
+
+        # Decode and verify
+        assert auth_header.startswith("Basic ")
+        encoded = auth_header[6:]
+        decoded = base64.b64decode(encoded).decode("utf-8")
+        assert decoded == "test-client:test-secret"
+
+    def test_extract_scopes_from_string(self, verifier: IntrospectionTokenVerifier):
+        """Test scope extraction from space-separated string."""
+        response = {"scope": "read write admin"}
+        scopes = verifier._extract_scopes(response)
+
+        assert scopes == ["read", "write", "admin"]
+
+    def test_extract_scopes_from_array(self, verifier: IntrospectionTokenVerifier):
+        """Test scope extraction from array."""
+        response = {"scope": ["read", "write", "admin"]}
+        scopes = verifier._extract_scopes(response)
+
+        assert scopes == ["read", "write", "admin"]
+
+    def test_extract_scopes_missing(self, verifier: IntrospectionTokenVerifier):
+        """Test scope extraction when scope field is missing."""
+        response: dict[str, Any] = {}
+        scopes = verifier._extract_scopes(response)
+
+        assert scopes == []
+
+    def test_extract_scopes_with_extra_whitespace(
+        self, verifier: IntrospectionTokenVerifier
+    ):
+        """Test scope extraction handles extra whitespace."""
+        response = {"scope": "  read   write  admin  "}
+        scopes = verifier._extract_scopes(response)
+
+        assert scopes == ["read", "write", "admin"]
+
+    async def test_valid_token_verification(
+        self, verifier: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test successful token verification."""
+        # Mock introspection endpoint
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={
+                "active": True,
+                "client_id": "user-123",
+                "scope": "read write",
+                "exp": int(time.time()) + 3600,
+                "iat": int(time.time()),
+                "sub": "user-123",
+                "username": "testuser",
+            },
+        )
+
+        access_token = await verifier.verify_token("test-token")
+
+        assert access_token is not None
+        assert access_token.client_id == "user-123"
+        assert access_token.scopes == ["read", "write"]
+        assert access_token.expires_at is not None
+        assert access_token.claims["active"] is True
+        assert access_token.claims["username"] == "testuser"
+
+    async def test_inactive_token_returns_none(
+        self, verifier: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that inactive tokens return None."""
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={"active": False},
+        )
+
+        access_token = await verifier.verify_token("expired-token")
+
+        assert access_token is None
+
+    async def test_expired_token_returns_none(
+        self, verifier: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that expired tokens return None."""
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={
+                "active": True,
+                "client_id": "user-123",
+                "scope": "read",
+                "exp": int(time.time()) - 3600,  # Expired 1 hour ago
+            },
+        )
+
+        access_token = await verifier.verify_token("expired-token")
+
+        assert access_token is None
+
+    async def test_token_without_expiration(
+        self, verifier: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test token without expiration field."""
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={
+                "active": True,
+                "client_id": "user-123",
+                "scope": "read",
+            },
+        )
+
+        access_token = await verifier.verify_token("test-token")
+
+        assert access_token is not None
+        assert access_token.expires_at is None
+
+    async def test_token_without_scopes(
+        self, verifier: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test token without scope field."""
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={
+                "active": True,
+                "client_id": "user-123",
+            },
+        )
+
+        access_token = await verifier.verify_token("test-token")
+
+        assert access_token is not None
+        assert access_token.scopes == []
+
+    async def test_required_scopes_validation(
+        self,
+        verifier_with_required_scopes: IntrospectionTokenVerifier,
+        httpx_mock: HTTPXMock,
+    ):
+        """Test that required scopes are validated."""
+        # Token with insufficient scopes
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={
+                "active": True,
+                "client_id": "user-123",
+                "scope": "read",  # Missing 'write'
+            },
+        )
+
+        access_token = await verifier_with_required_scopes.verify_token("test-token")
+
+        assert access_token is None
+
+    async def test_required_scopes_validation_success(
+        self,
+        verifier_with_required_scopes: IntrospectionTokenVerifier,
+        httpx_mock: HTTPXMock,
+    ):
+        """Test successful validation with required scopes."""
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={
+                "active": True,
+                "client_id": "user-123",
+                "scope": "read write admin",  # Has all required scopes
+            },
+        )
+
+        access_token = await verifier_with_required_scopes.verify_token("test-token")
+
+        assert access_token is not None
+        assert set(access_token.scopes) >= {"read", "write"}
+
+    async def test_http_error_returns_none(
+        self, verifier: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that HTTP errors return None."""
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            status_code=500,
+            text="Internal Server Error",
+        )
+
+        access_token = await verifier.verify_token("test-token")
+
+        assert access_token is None
+
+    async def test_authentication_failure_returns_none(
+        self, verifier: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that authentication failures return None."""
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            status_code=401,
+            text="Unauthorized",
+        )
+
+        access_token = await verifier.verify_token("test-token")
+
+        assert access_token is None
+
+    async def test_timeout_returns_none(
+        self, verifier: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that timeouts return None."""
+        from httpx import TimeoutException
+
+        httpx_mock.add_exception(
+            TimeoutException("Request timed out"),
+            url="https://auth.example.com/oauth/introspect",
+        )
+
+        access_token = await verifier.verify_token("test-token")
+
+        assert access_token is None
+
+    async def test_malformed_json_returns_none(
+        self, verifier: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that malformed JSON responses return None."""
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            status_code=200,
+            text="not json",
+        )
+
+        access_token = await verifier.verify_token("test-token")
+
+        assert access_token is None
+
+    async def test_request_includes_correct_headers(
+        self, verifier: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that the request includes correct headers and auth."""
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={"active": True, "client_id": "user-123"},
+        )
+
+        await verifier.verify_token("test-token")
+
+        # Verify request was made with correct parameters
+        request = httpx_mock.get_request()
+        assert request is not None
+        assert request.method == "POST"
+        assert "Authorization" in request.headers
+        assert request.headers["Authorization"].startswith("Basic ")
+        assert request.headers["Content-Type"] == "application/x-www-form-urlencoded"
+        assert request.headers["Accept"] == "application/json"
+
+    async def test_request_includes_token_and_hint(
+        self, verifier: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that the request includes token and token_type_hint."""
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={"active": True, "client_id": "user-123"},
+        )
+
+        await verifier.verify_token("my-test-token")
+
+        request = httpx_mock.get_request()
+        assert request is not None
+
+        # Parse form data
+        body = request.content.decode("utf-8")
+        assert "token=my-test-token" in body
+        assert "token_type_hint=access_token" in body
+
+    async def test_client_id_fallback_to_sub(
+        self, verifier: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that client_id falls back to sub if not present."""
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={
+                "active": True,
+                "sub": "user-456",
+                "scope": "read",
+            },
+        )
+
+        access_token = await verifier.verify_token("test-token")
+
+        assert access_token is not None
+        assert access_token.client_id == "user-456"
+
+    async def test_client_id_defaults_to_unknown(
+        self, verifier: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that client_id defaults to 'unknown' if neither client_id nor sub present."""
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={
+                "active": True,
+                "scope": "read",
+            },
+        )
+
+        access_token = await verifier.verify_token("test-token")
+
+        assert access_token is not None
+        assert access_token.client_id == "unknown"
+
+    def test_initialization_with_client_secret_post(self):
+        """Test verifier initialization with client_secret_post method."""
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="test-client",
+            client_secret="test-secret",
+            client_auth_method="client_secret_post",
+        )
+
+        assert verifier.client_auth_method == "client_secret_post"
+        assert verifier.introspection_url == "https://auth.example.com/oauth/introspect"
+        assert verifier.client_id == "test-client"
+        assert verifier.client_secret == "test-secret"
+
+    def test_initialization_defaults_to_client_secret_basic(self):
+        """Test that client_secret_basic is the default auth method."""
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="test-client",
+            client_secret="test-secret",
+        )
+
+        assert verifier.client_auth_method == "client_secret_basic"
+
+    def test_initialization_rejects_invalid_client_auth_method(self):
+        """Test that invalid client_auth_method values are rejected."""
+        # Test typo with trailing space
+        with pytest.raises(ValueError) as exc_info:
+            IntrospectionTokenVerifier(
+                introspection_url="https://auth.example.com/oauth/introspect",
+                client_id="test-client",
+                client_secret="test-secret",
+                client_auth_method="client_secret_basic ",  # ty: ignore[invalid-argument-type]
+            )
+        assert "Invalid client_auth_method" in str(exc_info.value)
+        assert "client_secret_basic " in str(exc_info.value)
+
+        # Test completely invalid value
+        with pytest.raises(ValueError) as exc_info:
+            IntrospectionTokenVerifier(
+                introspection_url="https://auth.example.com/oauth/introspect",
+                client_id="test-client",
+                client_secret="test-secret",
+                client_auth_method="basic",  # ty: ignore[invalid-argument-type]
+            )
+        assert "Invalid client_auth_method" in str(exc_info.value)
+        assert "basic" in str(exc_info.value)
+
+    async def test_client_secret_post_includes_credentials_in_body(
+        self, httpx_mock: HTTPXMock
+    ):
+        """Test that client_secret_post includes credentials in POST body."""
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="test-client",
+            client_secret="test-secret",
+            client_auth_method="client_secret_post",
+        )
+
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={"active": True, "client_id": "user-123"},
+        )
+
+        await verifier.verify_token("test-token")
+
+        # Verify request was made with credentials in body, not header
+        request = httpx_mock.get_request()
+        assert request is not None
+        assert request.method == "POST"
+        assert "Authorization" not in request.headers
+        assert request.headers["Content-Type"] == "application/x-www-form-urlencoded"
+        assert request.headers["Accept"] == "application/json"
+
+        # Parse form data
+        body = request.content.decode("utf-8")
+        assert "token=test-token" in body
+        assert "token_type_hint=access_token" in body
+        assert "client_id=test-client" in body
+        assert "client_secret=test-secret" in body
+
+    async def test_client_secret_post_verification_success(self, httpx_mock: HTTPXMock):
+        """Test successful token verification with client_secret_post."""
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="test-client",
+            client_secret="test-secret",
+            client_auth_method="client_secret_post",
+        )
+
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={
+                "active": True,
+                "client_id": "user-123",
+                "scope": "read write",
+                "exp": int(time.time()) + 3600,
+            },
+        )
+
+        access_token = await verifier.verify_token("test-token")
+
+        assert access_token is not None
+        assert access_token.client_id == "user-123"
+        assert access_token.scopes == ["read", "write"]
+
+    async def test_client_secret_basic_still_works(
+        self, verifier: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that client_secret_basic continues to work unchanged."""
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={"active": True, "client_id": "user-123"},
+        )
+
+        await verifier.verify_token("test-token")
+
+        # Verify request was made with Basic Auth header
+        request = httpx_mock.get_request()
+        assert request is not None
+        assert "Authorization" in request.headers
+        assert request.headers["Authorization"].startswith("Basic ")
+
+        # Verify credentials are NOT in body
+        body = request.content.decode("utf-8")
+        assert "client_id=" not in body
+        assert "client_secret=" not in body
+
+
+class TestIntrospectionCaching:
+    """Test in-memory caching for token introspection."""
+
+    @pytest.fixture
+    def verifier_with_cache(self) -> IntrospectionTokenVerifier:
+        """Create verifier with caching enabled."""
+        return IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="test-client",
+            client_secret="test-secret",
+            cache_ttl_seconds=300,  # 5 minutes
+            max_cache_size=100,
+        )
+
+    @pytest.fixture
+    def verifier_no_cache(self) -> IntrospectionTokenVerifier:
+        """Create verifier with caching disabled."""
+        return IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="test-client",
+            client_secret="test-secret",
+            cache_ttl_seconds=0,  # Disabled
+        )
+
+    def test_default_cache_settings(self):
+        """Test that caching is disabled by default."""
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="test-client",
+            client_secret="test-secret",
+        )
+        assert not verifier._cache.enabled
+
+    def test_custom_cache_settings(self):
+        """Test that cache settings can be customized."""
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="test-client",
+            client_secret="test-secret",
+            cache_ttl_seconds=60,
+            max_cache_size=500,
+        )
+        assert verifier._cache._ttl == 60
+        assert verifier._cache._max_size == 500
+
+    def test_cache_disabled_with_zero_ttl(self):
+        """Test that cache is disabled when TTL is 0 or None."""
+        # Explicit 0
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="test-client",
+            client_secret="test-secret",
+            cache_ttl_seconds=0,
+        )
+        assert not verifier._cache.enabled
+
+        # Explicit None (same as default)
+        verifier2 = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="test-client",
+            client_secret="test-secret",
+            cache_ttl_seconds=None,
+        )
+        assert not verifier2._cache.enabled
+
+    async def test_cache_disabled_with_zero_max_size(self, httpx_mock: HTTPXMock):
+        """Test that cache is disabled when max_cache_size is 0."""
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={
+                "active": True,
+                "client_id": "user-123",
+                "scope": "read",
+            },
+        )
+
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="test-client",
+            client_secret="test-secret",
+            cache_ttl_seconds=300,
+            max_cache_size=0,
+        )
+        result = await verifier.verify_token("test-token")
+        assert result is not None
+        assert result.client_id == "user-123"
+
+    def test_negative_max_cache_size_raises(self):
+        """Negative max_cache_size is a caller bug and should raise."""
+        with pytest.raises(ValueError, match="max_cache_size must be non-negative"):
+            IntrospectionTokenVerifier(
+                introspection_url="https://auth.example.com/oauth/introspect",
+                client_id="test-client",
+                client_secret="test-secret",
+                cache_ttl_seconds=300,
+                max_cache_size=-1,
+            )
+
+    async def test_cache_hit_returns_cached_result(
+        self, verifier_with_cache: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that cached valid tokens are returned without introspection call."""
+        # First call - introspection endpoint called
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={
+                "active": True,
+                "client_id": "user-123",
+                "scope": "read write",
+                "exp": int(time.time()) + 3600,
+            },
+        )
+
+        # First verification
+        result1 = await verifier_with_cache.verify_token("test-token")
+        assert result1 is not None
+        assert result1.client_id == "user-123"
+
+        # Verify one request was made
+        requests = httpx_mock.get_requests()
+        assert len(requests) == 1
+
+        # Second verification - should use cache, no new request
+        result2 = await verifier_with_cache.verify_token("test-token")
+        assert result2 is not None
+        assert result2.client_id == "user-123"
+
+        # Still only one request
+        requests = httpx_mock.get_requests()
+        assert len(requests) == 1
+
+    async def test_cache_returns_defensive_copy(
+        self, verifier_with_cache: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that cached tokens are defensive copies (mutations don't leak)."""
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={
+                "active": True,
+                "client_id": "user-123",
+                "scope": "read write",
+                "exp": int(time.time()) + 3600,
+                "custom_claim": "original",
+            },
+        )
+
+        # First verification
+        result1 = await verifier_with_cache.verify_token("test-token")
+        assert result1 is not None
+        assert result1.claims["custom_claim"] == "original"
+
+        # Mutate the result (simulating request-path code adding derived claims)
+        result1.claims["custom_claim"] = "mutated"
+        result1.claims["new_claim"] = "injected"
+        result1.scopes.append("admin")
+
+        # Second verification - should get clean copy, not mutated one
+        result2 = await verifier_with_cache.verify_token("test-token")
+        assert result2 is not None
+        assert result2.claims["custom_claim"] == "original"
+        assert "new_claim" not in result2.claims
+        assert "admin" not in result2.scopes
+
+        # Verify they are different object instances
+        assert result1 is not result2
+
+    async def test_inactive_tokens_not_cached(
+        self, verifier_with_cache: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that inactive tokens are NOT cached (may become valid later)."""
+        # Add two responses - inactive tokens should trigger re-introspection
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={"active": False},
+        )
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={"active": False},
+        )
+
+        # First verification
+        result1 = await verifier_with_cache.verify_token("inactive-token")
+        assert result1 is None
+
+        # Verify one request was made
+        requests = httpx_mock.get_requests()
+        assert len(requests) == 1
+
+        # Second verification - should NOT use cache, makes another request
+        result2 = await verifier_with_cache.verify_token("inactive-token")
+        assert result2 is None
+
+        # Two requests made (inactive tokens not cached)
+        requests = httpx_mock.get_requests()
+        assert len(requests) == 2
+
+    async def test_cache_disabled_makes_every_call(
+        self, verifier_no_cache: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that with caching disabled, every call makes a request."""
+        # Add multiple responses for the same token
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={"active": True, "client_id": "user-123"},
+        )
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={"active": True, "client_id": "user-123"},
+        )
+
+        # First call
+        await verifier_no_cache.verify_token("test-token")
+
+        # Second call - should also make a request
+        await verifier_no_cache.verify_token("test-token")
+
+        # Two requests were made
+        requests = httpx_mock.get_requests()
+        assert len(requests) == 2
+
+    async def test_different_tokens_are_cached_separately(
+        self, verifier_with_cache: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that different tokens have separate cache entries."""
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={"active": True, "client_id": "user-1"},
+        )
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={"active": True, "client_id": "user-2"},
+        )
+
+        # Verify two different tokens
+        result1 = await verifier_with_cache.verify_token("token-1")
+        result2 = await verifier_with_cache.verify_token("token-2")
+
+        assert result1 is not None
+        assert result1.client_id == "user-1"
+        assert result2 is not None
+        assert result2.client_id == "user-2"
+
+        # Two requests were made
+        requests = httpx_mock.get_requests()
+        assert len(requests) == 2
+
+        # Verify both again - no new requests
+        await verifier_with_cache.verify_token("token-1")
+        await verifier_with_cache.verify_token("token-2")
+
+        requests = httpx_mock.get_requests()
+        assert len(requests) == 2
+
+    async def test_http_errors_are_not_cached(
+        self, verifier_with_cache: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that HTTP errors are not cached (transient failures)."""
+        # First call - HTTP error
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            status_code=500,
+            text="Internal Server Error",
+        )
+        # Second call - success
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={"active": True, "client_id": "user-123"},
+        )
+
+        # First verification - fails
+        result1 = await verifier_with_cache.verify_token("test-token")
+        assert result1 is None
+
+        # Second verification - should retry since error wasn't cached
+        result2 = await verifier_with_cache.verify_token("test-token")
+        assert result2 is not None
+        assert result2.client_id == "user-123"
+
+        # Two requests were made
+        requests = httpx_mock.get_requests()
+        assert len(requests) == 2
+
+    async def test_timeout_errors_are_not_cached(
+        self, verifier_with_cache: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that timeout errors are not cached (transient failures)."""
+        from httpx import TimeoutException
+
+        # First call - timeout
+        httpx_mock.add_exception(
+            TimeoutException("Request timed out"),
+            url="https://auth.example.com/oauth/introspect",
+        )
+        # Second call - success
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={"active": True, "client_id": "user-123"},
+        )
+
+        # First verification - times out
+        result1 = await verifier_with_cache.verify_token("test-token")
+        assert result1 is None
+
+        # Second verification - should retry since timeout wasn't cached
+        result2 = await verifier_with_cache.verify_token("test-token")
+        assert result2 is not None
+
+        # Two requests were made
+        requests = httpx_mock.get_requests()
+        assert len(requests) == 2
+
+    def test_token_hashing(self, verifier_with_cache: IntrospectionTokenVerifier):
+        """Test that tokens are hashed consistently."""
+        hash1 = verifier_with_cache._cache._hash_token("test-token")
+        hash2 = verifier_with_cache._cache._hash_token("test-token")
+        hash3 = verifier_with_cache._cache._hash_token("different-token")
+
+        # Same token produces same hash
+        assert hash1 == hash2
+        # Different tokens produce different hashes
+        assert hash1 != hash3
+        # Hash is a hex string (SHA-256 = 64 chars)
+        assert len(hash1) == 64
+
+    async def test_cache_respects_token_expiration(
+        self, verifier_with_cache: IntrospectionTokenVerifier, httpx_mock: HTTPXMock
+    ):
+        """Test that cache respects token's exp claim for TTL."""
+        # Token expiring in 60 seconds (shorter than cache TTL of 300)
+        short_exp = int(time.time()) + 60
+
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={
+                "active": True,
+                "client_id": "user-123",
+                "exp": short_exp,
+            },
+        )
+
+        await verifier_with_cache.verify_token("test-token")
+
+        # Check that cache entry uses the shorter expiration
+        cache_key = verifier_with_cache._cache._hash_token("test-token")
+        entry = verifier_with_cache._cache._entries[cache_key]
+        # Cache expiration should be at or before token expiration
+        assert entry.expires_at <= short_exp
+
+    async def test_expired_cache_entry_triggers_new_introspection(
+        self, httpx_mock: HTTPXMock
+    ):
+        """Test that expired cache entries are evicted and a new call is made."""
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="test-client",
+            client_secret="test-secret",
+            cache_ttl_seconds=1,  # 1 second TTL
+        )
+
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={"active": True, "client_id": "user-123"},
+        )
+        httpx_mock.add_response(
+            url="https://auth.example.com/oauth/introspect",
+            method="POST",
+            json={"active": True, "client_id": "user-123"},
+        )
+
+        # First call — caches the result
+        await verifier.verify_token("test-token")
+        assert len(httpx_mock.get_requests()) == 1
+
+        # Expire the cache entry manually
+        cache_key = verifier._cache._hash_token("test-token")
+        verifier._cache._entries[cache_key].expires_at = time.time() - 1
+
+        # Second call — cache miss, new introspection
+        await verifier.verify_token("test-token")
+        assert len(httpx_mock.get_requests()) == 2
+
+    async def test_cache_eviction_at_max_size(self, httpx_mock: HTTPXMock):
+        """Test that cache evicts entries when max size is reached."""
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="test-client",
+            client_secret="test-secret",
+            cache_ttl_seconds=300,
+            max_cache_size=2,
+        )
+
+        for i in range(3):
+            httpx_mock.add_response(
+                url="https://auth.example.com/oauth/introspect",
+                method="POST",
+                json={"active": True, "client_id": f"user-{i}"},
+            )
+
+        # Fill cache to capacity
+        await verifier.verify_token("token-0")
+        await verifier.verify_token("token-1")
+        assert len(verifier._cache._entries) == 2
+
+        # Third token should evict the oldest entry
+        await verifier.verify_token("token-2")
+        assert len(verifier._cache._entries) == 2
+
+        # token-0 should have been evicted (FIFO)
+        hash_0 = verifier._cache._hash_token("token-0")
+        assert hash_0 not in verifier._cache._entries
+
+
+class TestIntrospectionTokenVerifierIntegration:
+    """Integration tests with FastMCP server."""
+
+    async def test_verifier_used_by_fastmcp(self):
+        """Test that IntrospectionTokenVerifier can be used as FastMCP auth."""
+        from fastmcp import FastMCP
+
+        # Create verifier
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="test-client",
+            client_secret="test-secret",
+        )
+
+        # Create protected server - should work without errors
+        mcp = FastMCP("Test Server", auth=verifier)
+
+        @mcp.tool()
+        def greet(name: str) -> str:
+            """Greet someone."""
+            return f"Hello, {name}!"
+
+        # Verify the auth is set correctly
+        assert mcp.auth is verifier
+        tools = await mcp.list_tools()
+        assert len(list(tools)) == 1
diff --git a/tests/server/auth/providers/test_keycloak.py b/tests/server/auth/providers/test_keycloak.py
new file mode 100644
index 0000000..4312e01
--- /dev/null
+++ b/tests/server/auth/providers/test_keycloak.py
@@ -0,0 +1,135 @@
+"""Unit tests for Keycloak OAuth provider."""
+
+import pytest
+
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.server.auth.providers.keycloak import KeycloakAuthProvider
+
+TEST_REALM_URL = "https://keycloak.example.com/realms/test"
+TEST_BASE_URL = "https://example.com:8000"
+TEST_REQUIRED_SCOPES = ["openid", "profile"]
+
+
+class TestKeycloakAuthProvider:
+    """Test KeycloakAuthProvider initialization."""
+
+    def test_init_with_explicit_params(self):
+        """Test initialization with explicit parameters."""
+        provider = KeycloakAuthProvider(
+            realm_url=TEST_REALM_URL,
+            base_url=TEST_BASE_URL,
+            required_scopes=TEST_REQUIRED_SCOPES,
+        )
+
+        assert provider.realm_url == TEST_REALM_URL
+        assert str(provider.base_url) == TEST_BASE_URL + "/"
+        assert isinstance(provider.token_verifier, JWTVerifier)
+        assert provider.token_verifier.required_scopes == TEST_REQUIRED_SCOPES
+        jwt_verifier = provider.token_verifier
+        assert isinstance(jwt_verifier, JWTVerifier)
+        assert (
+            jwt_verifier.jwks_uri == f"{TEST_REALM_URL}/protocol/openid-connect/certs"
+        )
+        assert jwt_verifier.issuer == TEST_REALM_URL
+
+    def test_init_with_string_scopes(self):
+        """Test initialization with scopes as comma-separated string."""
+        provider = KeycloakAuthProvider(
+            realm_url=TEST_REALM_URL,
+            base_url=TEST_BASE_URL,
+            required_scopes="openid,profile,email",
+        )
+
+        assert provider.token_verifier.required_scopes == ["openid", "profile", "email"]
+
+    def test_init_with_custom_token_verifier(self):
+        """Test initialization with custom token verifier."""
+        custom_verifier = JWTVerifier(
+            jwks_uri=f"{TEST_REALM_URL}/protocol/openid-connect/certs",
+            issuer=TEST_REALM_URL,
+            audience="custom-client-id",
+            required_scopes=["custom:scope"],
+        )
+
+        provider = KeycloakAuthProvider(
+            realm_url=TEST_REALM_URL,
+            base_url=TEST_BASE_URL,
+            token_verifier=custom_verifier,
+        )
+
+        assert provider.token_verifier is custom_verifier
+        assert provider.token_verifier.audience == "custom-client-id"
+        assert provider.token_verifier.required_scopes == ["custom:scope"]
+
+    def test_authorization_servers_point_to_keycloak(self):
+        """Test that authorization_servers points directly to the Keycloak realm."""
+        provider = KeycloakAuthProvider(
+            realm_url=TEST_REALM_URL,
+            base_url=TEST_BASE_URL,
+        )
+
+        assert len(provider.authorization_servers) == 1
+        assert str(provider.authorization_servers[0]).rstrip("/") == TEST_REALM_URL
+
+
+class TestKeycloakHardCodedEndpoints:
+    """Test hard-coded Keycloak endpoint patterns."""
+
+    def test_uses_standard_keycloak_url_patterns(self):
+        """Test that provider uses Keycloak-specific URL patterns."""
+        provider = KeycloakAuthProvider(
+            realm_url=TEST_REALM_URL,
+            base_url=TEST_BASE_URL,
+        )
+
+        jwt_verifier = provider.token_verifier
+        assert isinstance(jwt_verifier, JWTVerifier)
+        assert (
+            jwt_verifier.jwks_uri == f"{TEST_REALM_URL}/protocol/openid-connect/certs"
+        )
+        assert jwt_verifier.issuer == TEST_REALM_URL
+
+
+class TestKeycloakRoutes:
+    """Test Keycloak auth provider routes."""
+
+    @pytest.fixture
+    def keycloak_provider(self):
+        """Create a KeycloakAuthProvider for testing."""
+        return KeycloakAuthProvider(
+            realm_url=TEST_REALM_URL,
+            base_url=TEST_BASE_URL,
+            required_scopes=TEST_REQUIRED_SCOPES,
+        )
+
+    def test_get_routes(self, keycloak_provider):
+        """Test that get_routes returns only protected resource metadata (no proxy routes)."""
+        routes = keycloak_provider.get_routes()
+
+        paths = [route.path for route in routes]
+        assert "/.well-known/oauth-protected-resource" in paths
+        assert "/register" not in paths
+        assert "/authorize" not in paths
+
+
+class TestKeycloakEdgeCases:
+    """Test edge cases for KeycloakAuthProvider."""
+
+    def test_empty_required_scopes_handling(self):
+        """Test handling of empty required scopes."""
+        provider = KeycloakAuthProvider(
+            realm_url=TEST_REALM_URL,
+            base_url=TEST_BASE_URL,
+            required_scopes=[],
+        )
+
+        assert provider.token_verifier.required_scopes == []
+
+    def test_realm_url_with_trailing_slash(self):
+        """Test handling of realm URL with trailing slash."""
+        provider = KeycloakAuthProvider(
+            realm_url=TEST_REALM_URL + "/",
+            base_url=TEST_BASE_URL,
+        )
+
+        assert provider.realm_url == TEST_REALM_URL
diff --git a/tests/server/auth/providers/test_oci.py b/tests/server/auth/providers/test_oci.py
new file mode 100644
index 0000000..7ad1346
--- /dev/null
+++ b/tests/server/auth/providers/test_oci.py
@@ -0,0 +1,87 @@
+"""Unit tests for OCI OAuth provider."""
+
+from unittest.mock import patch
+
+import pytest
+from key_value.aio.stores.memory import MemoryStore
+
+from fastmcp.server.auth.oidc_proxy import OIDCConfiguration
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.server.auth.providers.oci import OCIProvider
+
+TEST_DOMAIN = "idcs-test.identity.oraclecloud.com"
+TEST_CONFIG_URL = f"https://{TEST_DOMAIN}/.well-known/openid-configuration"
+TEST_CLIENT_ID = "test-client-id"
+TEST_CLIENT_SECRET = "test-client-secret"
+TEST_AUDIENCE = "test-audience"
+TEST_BASE_URL = "https://example.com:8000/"
+TEST_REDIRECT_PATH = "/test/callback"
+TEST_REQUIRED_SCOPES = ["openid", "profile", "email"]
+
+
+@pytest.fixture
+def valid_oidc_configuration_dict():
+    """Create a valid OCI OIDC configuration dict for testing."""
+    return {
+        "issuer": "https://identity.oraclecloud.com/",
+        "authorization_endpoint": f"https://{TEST_DOMAIN}/oauth2/v1/authorize",
+        "token_endpoint": f"https://{TEST_DOMAIN}/oauth2/v1/token",
+        "jwks_uri": f"https://{TEST_DOMAIN}/admin/v1/SigningCert/jwk",
+        "response_types_supported": ["code"],
+        "subject_types_supported": ["public"],
+        "id_token_signing_alg_values_supported": ["RS256"],
+    }
+
+
+class TestOCIProvider:
+    """Test OCIProvider initialization."""
+
+    def test_init_with_explicit_params(self, valid_oidc_configuration_dict):
+        """Test initialization with explicit parameters."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            provider = OCIProvider(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                audience=TEST_AUDIENCE,
+                base_url=TEST_BASE_URL,
+                redirect_path=TEST_REDIRECT_PATH,
+                required_scopes=TEST_REQUIRED_SCOPES,
+                client_storage=MemoryStore(),
+                jwt_signing_key="test-secret-key",
+            )
+
+            mock_get.assert_called_once()
+
+            call_args = mock_get.call_args
+            assert str(call_args[0][0]) == TEST_CONFIG_URL
+
+            assert provider._upstream_client_id == TEST_CLIENT_ID
+            assert provider._upstream_client_secret is not None
+            assert (
+                provider._upstream_client_secret.get_secret_value()
+                == TEST_CLIENT_SECRET
+            )
+
+            assert (
+                provider._upstream_authorization_endpoint
+                == f"https://{TEST_DOMAIN}/oauth2/v1/authorize"
+            )
+            assert (
+                provider._upstream_token_endpoint
+                == f"https://{TEST_DOMAIN}/oauth2/v1/token"
+            )
+
+            assert isinstance(provider._token_validator, JWTVerifier)
+            assert provider._token_validator.audience == TEST_AUDIENCE
+
+            assert str(provider.base_url) == TEST_BASE_URL
+            assert provider._redirect_path == TEST_REDIRECT_PATH
+            assert provider._token_validator.required_scopes == TEST_REQUIRED_SCOPES
diff --git a/tests/server/auth/providers/test_propelauth.py b/tests/server/auth/providers/test_propelauth.py
new file mode 100644
index 0000000..2a254d5
--- /dev/null
+++ b/tests/server/auth/providers/test_propelauth.py
@@ -0,0 +1,336 @@
+"""Tests for PropelAuthProvider."""
+
+from typing import cast
+from unittest.mock import AsyncMock
+
+import httpx
+import pytest
+from mcp import MCPError
+from pydantic import SecretStr
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.auth import AccessToken
+from fastmcp.server.auth.providers.introspection import IntrospectionTokenVerifier
+from fastmcp.server.auth.providers.propelauth import (
+    PropelAuthProvider,
+    PropelAuthTokenIntrospectionOverrides,
+)
+from fastmcp.utilities.tests import run_server_async
+
+
+class TestPropelAuthProvider:
+    """Test PropelAuth's auth provider."""
+
+    def test_init_with_only_required_params(self):
+        """Test PropelAuthProvider initialization with only required params."""
+        provider = PropelAuthProvider(
+            auth_url="https://auth.example.com",
+            introspection_client_id="client_id_123",
+            introspection_client_secret="client_secret_123",
+            base_url="https://example.com",
+        )
+
+        # Verify the provider is configured correctly
+        assert len(provider.authorization_servers) == 1
+        assert (
+            str(provider.authorization_servers[0])
+            == "https://auth.example.com/oauth/2.1"
+        )
+        assert str(provider.base_url) == "https://example.com/"
+
+        # Verify token verifier is configured correctly
+        assert isinstance(provider.token_verifier, IntrospectionTokenVerifier)
+        assert (
+            provider.token_verifier.introspection_url
+            == "https://auth.example.com/oauth/2.1/introspect"
+        )
+        assert provider.token_verifier.client_id == "client_id_123"
+        assert provider.token_verifier.client_secret == "client_secret_123"
+
+    def test_auth_url_trailing_slash_normalization(self):
+        """Test that trailing slash on auth_url is stripped before building URLs."""
+        provider = PropelAuthProvider(
+            auth_url="https://auth.example.com/",
+            introspection_client_id="client_id_123",
+            introspection_client_secret="client_secret_123",
+            base_url="https://example.com",
+        )
+
+        assert isinstance(provider.token_verifier, IntrospectionTokenVerifier)
+        assert len(provider.authorization_servers) == 1
+        assert (
+            str(provider.authorization_servers[0])
+            == "https://auth.example.com/oauth/2.1"
+        )
+        assert (
+            provider.token_verifier.introspection_url
+            == "https://auth.example.com/oauth/2.1/introspect"
+        )
+
+    def test_required_scopes_passed_to_verifier(self):
+        """Test that required_scopes are passed through to the token verifier."""
+        provider = PropelAuthProvider(
+            auth_url="https://auth.example.com",
+            introspection_client_id="client_id_123",
+            introspection_client_secret="client_secret_123",
+            base_url="https://example.com",
+            required_scopes=["read", "write"],
+        )
+
+        assert isinstance(provider.token_verifier, IntrospectionTokenVerifier)
+        assert provider.token_verifier.required_scopes == ["read", "write"]
+
+    def test_introspection_client_secret_as_secret_str(self):
+        """Test that SecretStr client_secret is unwrapped correctly."""
+        provider = PropelAuthProvider(
+            auth_url="https://auth.example.com",
+            introspection_client_id="client_id_123",
+            introspection_client_secret=SecretStr("my_secret"),
+            base_url="https://example.com",
+        )
+
+        assert isinstance(provider.token_verifier, IntrospectionTokenVerifier)
+        assert provider.token_verifier.client_secret == "my_secret"
+
+    def test_authorization_servers_configuration(self):
+        """Test that authorization_servers contains the correct PropelAuth URL."""
+        provider = PropelAuthProvider(
+            auth_url="https://auth.propelauth.com",
+            introspection_client_id="client_id_123",
+            introspection_client_secret="client_secret_123",
+            base_url="https://example.com",
+        )
+
+        assert len(provider.authorization_servers) == 1
+        assert (
+            str(provider.authorization_servers[0])
+            == "https://auth.propelauth.com/oauth/2.1"
+        )
+
+    def test_token_introspection_overrides_timeout(self):
+        """Test that timeout_seconds override is passed to the verifier."""
+        provider = PropelAuthProvider(
+            auth_url="https://auth.example.com",
+            introspection_client_id="client_id_123",
+            introspection_client_secret="client_secret_123",
+            base_url="https://example.com",
+            token_introspection_overrides={"timeout_seconds": 30},
+        )
+
+        assert isinstance(provider.token_verifier, IntrospectionTokenVerifier)
+        assert provider.token_verifier.timeout_seconds == 30
+
+    def test_token_introspection_overrides_cache(self):
+        """Test that cache overrides are passed to the verifier."""
+        provider = PropelAuthProvider(
+            auth_url="https://auth.example.com",
+            introspection_client_id="client_id_123",
+            introspection_client_secret="client_secret_123",
+            base_url="https://example.com",
+            token_introspection_overrides={
+                "cache_ttl_seconds": 300,
+                "max_cache_size": 500,
+            },
+        )
+
+        assert isinstance(provider.token_verifier, IntrospectionTokenVerifier)
+        assert provider.token_verifier._cache._ttl == 300
+        assert provider.token_verifier._cache._max_size == 500
+
+    def test_token_introspection_overrides_http_client(self):
+        """Test that http_client override is passed to the verifier."""
+        client = httpx.AsyncClient()
+        provider = PropelAuthProvider(
+            auth_url="https://auth.example.com",
+            introspection_client_id="client_id_123",
+            introspection_client_secret="client_secret_123",
+            base_url="https://example.com",
+            token_introspection_overrides={"http_client": client},
+        )
+
+        assert isinstance(provider.token_verifier, IntrospectionTokenVerifier)
+        assert provider.token_verifier._http_client is client
+
+    def test_token_introspection_overrides_ignores_unknown_keys(self):
+        """Test that unknown override keys are silently ignored."""
+        provider = PropelAuthProvider(
+            auth_url="https://auth.example.com",
+            introspection_client_id="client_id_123",
+            introspection_client_secret="client_secret_123",
+            base_url="https://example.com",
+            # This won't typecheck without casting, since it shouldn't be allowed
+            token_introspection_overrides=cast(
+                PropelAuthTokenIntrospectionOverrides, {"unknown_key": "value"}
+            ),
+        )
+
+        assert isinstance(provider.token_verifier, IntrospectionTokenVerifier)
+        assert provider.token_verifier.timeout_seconds == 10
+
+    def test_token_introspection_overrides_ignores_disallowed_known_keys(self):
+        """Test that known IntrospectionTokenVerifier keys not in the allow list are ignored."""
+        provider = PropelAuthProvider(
+            auth_url="https://auth.example.com",
+            introspection_client_id="client_id_123",
+            introspection_client_secret="client_secret_123",
+            base_url="https://example.com",
+            # This won't typecheck without casting, since it shouldn't be allowed
+            token_introspection_overrides=cast(
+                PropelAuthTokenIntrospectionOverrides, {"client_id": "sneaky_override"}
+            ),
+        )
+
+        assert isinstance(provider.token_verifier, IntrospectionTokenVerifier)
+        assert provider.token_verifier.client_id == "client_id_123"
+
+
+class TestPropelAuthResourceChecking:
+    """Test audience (aud) checking when resource is configured."""
+
+    def _make_provider(self, resource: str | None = None) -> PropelAuthProvider:
+        return PropelAuthProvider(
+            auth_url="https://auth.example.com",
+            introspection_client_id="client_id_123",
+            introspection_client_secret="client_secret_123",
+            base_url="https://example.com",
+            resource=resource,
+        )
+
+    def _make_access_token(self, aud: str) -> AccessToken:
+        return AccessToken(
+            token="test-token",
+            client_id="client_id_123",
+            scopes=[],
+            claims={"active": True, "sub": "user-1", "aud": aud},
+        )
+
+    async def test_no_resource_skips_aud_check(self, monkeypatch: pytest.MonkeyPatch):
+        """When resource is not configured, tokens are accepted without aud checking."""
+        provider = self._make_provider(resource=None)
+        token = self._make_access_token(aud="https://anything.example.com")
+        monkeypatch.setattr(
+            provider.token_verifier, "verify_token", AsyncMock(return_value=token)
+        )
+
+        result = await provider.verify_token("test-token")
+        assert result is token
+
+    async def test_aud_matches_resource(self, monkeypatch: pytest.MonkeyPatch):
+        """Token is accepted when aud matches the configured resource."""
+        provider = self._make_provider(resource="https://api.example.com/mcp")
+        token = self._make_access_token(aud="https://api.example.com/mcp")
+        monkeypatch.setattr(
+            provider.token_verifier, "verify_token", AsyncMock(return_value=token)
+        )
+
+        result = await provider.verify_token("test-token")
+        assert result is token
+
+    async def test_aud_does_not_match_resource(self, monkeypatch: pytest.MonkeyPatch):
+        """Token is rejected when aud doesn't match the configured resource."""
+        provider = self._make_provider(resource="https://api.example.com/mcp")
+        token = self._make_access_token(aud="https://other-server.example.com/mcp")
+        monkeypatch.setattr(
+            provider.token_verifier, "verify_token", AsyncMock(return_value=token)
+        )
+
+        result = await provider.verify_token("test-token")
+        assert result is None
+
+    async def test_inner_verifier_returns_none(self, monkeypatch: pytest.MonkeyPatch):
+        """When the inner verifier rejects the token, None is returned without aud checking."""
+        provider = self._make_provider(resource="https://api.example.com/mcp")
+        monkeypatch.setattr(
+            provider.token_verifier, "verify_token", AsyncMock(return_value=None)
+        )
+
+        result = await provider.verify_token("test-token")
+        assert result is None
+
+
+@pytest.fixture
+async def mcp_server_url():
+    """Start MCP server with PropelAuth authentication."""
+    mcp = FastMCP(
+        auth=PropelAuthProvider(
+            auth_url="https://auth.example.com",
+            introspection_client_id="client_id_123",
+            introspection_client_secret="client_secret_123",
+            base_url="http://localhost:4321",
+        )
+    )
+
+    @mcp.tool
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    async with run_server_async(mcp, transport="http") as url:
+        yield url
+
+
+class TestPropelAuthProviderIntegration:
+    async def test_unauthorized_access(self, mcp_server_url: str):
+        # SDK v2 surfaces the server's 401 as a generic MCPError at the client
+        # boundary rather than re-raising httpx.HTTPStatusError.
+        with pytest.raises(MCPError):
+            async with Client(mcp_server_url) as client:
+                tools = await client.list_tools()  # noqa: F841
+        assert "tools" not in locals()
+
+    async def test_metadata_route_forwards_propelauth_response(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+        mcp_server_url: str,
+    ) -> None:
+        """Ensure PropelAuth metadata route proxies upstream JSON."""
+
+        metadata_payload = {
+            "issuer": "https://auth.example.com",
+            "token_endpoint": "https://auth.example.com/oauth/2.1/token",
+            "authorization_endpoint": "https://auth.example.com/oauth/2.1/authorize",
+        }
+
+        class DummyResponse:
+            status_code = 200
+
+            def __init__(self, data: dict[str, str]):
+                self._data = data
+
+            def json(self):
+                return self._data
+
+            def raise_for_status(self):
+                return None
+
+        class DummyAsyncClient:
+            last_url: str | None = None
+
+            async def __aenter__(self):
+                return self
+
+            async def __aexit__(self, exc_type, exc, tb):
+                return False
+
+            async def get(self, url: str):
+                DummyAsyncClient.last_url = url
+                return DummyResponse(metadata_payload)
+
+        real_httpx_client = httpx.AsyncClient
+
+        monkeypatch.setattr(
+            "fastmcp.server.auth.providers.propelauth.httpx.AsyncClient",
+            DummyAsyncClient,
+        )
+
+        base_url = mcp_server_url.rsplit("/mcp", 1)[0]
+        async with real_httpx_client() as client:
+            response = await client.get(
+                f"{base_url}/.well-known/oauth-authorization-server"
+            )
+
+        assert response.status_code == 200
+        assert response.json() == metadata_payload
+        assert (
+            DummyAsyncClient.last_url
+            == "https://auth.example.com/.well-known/oauth-authorization-server/oauth/2.1"
+        )
diff --git a/tests/server/auth/providers/test_scalekit.py b/tests/server/auth/providers/test_scalekit.py
new file mode 100644
index 0000000..ad1a085
--- /dev/null
+++ b/tests/server/auth/providers/test_scalekit.py
@@ -0,0 +1,220 @@
+"""Tests for Scalekit OAuth provider."""
+
+import httpx
+import pytest
+from mcp import MCPError
+
+from fastmcp import Client, FastMCP
+from fastmcp.client.transports import StreamableHttpTransport
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.server.auth.providers.scalekit import ScalekitProvider
+from fastmcp.utilities.tests import HeadlessOAuth, run_server_async
+
+
+class TestScalekitProvider:
+    """Test Scalekit OAuth provider functionality."""
+
+    def test_init_with_explicit_params(self):
+        """Test ScalekitProvider initialization with explicit parameters."""
+        provider = ScalekitProvider(
+            environment_url="https://my-env.scalekit.com",
+            resource_id="sk_resource_456",
+            base_url="https://myserver.com/",
+            required_scopes=["read"],
+        )
+
+        assert provider.environment_url == "https://my-env.scalekit.com"
+        assert provider.resource_id == "sk_resource_456"
+        assert str(provider.base_url) == "https://myserver.com/"
+        assert provider.required_scopes == ["read"]
+
+    def test_init_with_mcp_url_only(self):
+        """Allow legacy mcp_url parameter as base_url."""
+        provider = ScalekitProvider(
+            environment_url="https://legacy.scalekit.com",
+            resource_id="sk_resource_legacy",
+            mcp_url="https://legacy-app.com/",
+        )
+
+        assert str(provider.base_url) == "https://legacy-app.com/"
+
+    def test_init_prefers_base_url_over_mcp_url(self):
+        """mcp_url should take precedence over base_url when both provided."""
+        provider = ScalekitProvider(
+            environment_url="https://my-env.scalekit.com",
+            resource_id="sk_resource_456",
+            base_url="https://preferred-base.com/",
+            mcp_url="https://unused-base.com/",
+        )
+
+        assert str(provider.base_url) == "https://preferred-base.com/"
+
+    def test_environment_variable_loading(self):
+        """Test that environment variables are loaded correctly."""
+        provider = ScalekitProvider(
+            environment_url="https://test-env.scalekit.com",
+            resource_id="sk_resource_test_456",
+            base_url="http://test-server.com",
+        )
+
+        assert provider.environment_url == "https://test-env.scalekit.com"
+        assert provider.resource_id == "sk_resource_test_456"
+        assert str(provider.base_url) == "http://test-server.com/"
+
+    def test_accepts_client_id_argument(self):
+        """client_id parameter should be accepted but ignored."""
+        provider = ScalekitProvider(
+            environment_url="https://my-env.scalekit.com",
+            resource_id="sk_resource_456",
+            base_url="https://myserver.com/",
+            client_id="client_123",
+        )
+
+        assert str(provider.base_url) == "https://myserver.com/"
+
+    def test_url_trailing_slash_handling(self):
+        """Test that URLs handle trailing slashes correctly."""
+        provider = ScalekitProvider(
+            environment_url="https://my-env.scalekit.com/",
+            resource_id="sk_resource_456",
+            base_url="https://myserver.com/",
+        )
+
+        assert provider.environment_url == "https://my-env.scalekit.com"
+        assert str(provider.base_url) == "https://myserver.com/"
+
+    def test_jwt_verifier_configured_correctly(self):
+        """Test that JWT verifier is configured correctly."""
+        provider = ScalekitProvider(
+            environment_url="https://my-env.scalekit.com",
+            resource_id="sk_resource_456",
+            base_url="https://myserver.com/",
+        )
+
+        # Check that JWT verifier uses the correct endpoints
+        assert isinstance(provider.token_verifier, JWTVerifier)
+        assert provider.token_verifier.jwks_uri == "https://my-env.scalekit.com/keys"
+        assert provider.token_verifier.issuer == "https://my-env.scalekit.com"
+        assert provider.token_verifier.audience == "sk_resource_456"
+
+    def test_required_scopes_hooks_into_verifier(self):
+        """Token verifier should enforce required scopes when provided."""
+        provider = ScalekitProvider(
+            environment_url="https://my-env.scalekit.com",
+            resource_id="sk_resource_456",
+            base_url="https://myserver.com/",
+            required_scopes=["read"],
+        )
+
+        assert isinstance(provider.token_verifier, JWTVerifier)
+        assert provider.token_verifier.required_scopes == ["read"]
+
+    def test_authorization_servers_configuration(self):
+        """Test that authorization servers are configured correctly."""
+        provider = ScalekitProvider(
+            environment_url="https://my-env.scalekit.com",
+            resource_id="sk_resource_456",
+            base_url="https://myserver.com/",
+        )
+
+        assert len(provider.authorization_servers) == 1
+        assert (
+            str(provider.authorization_servers[0])
+            == "https://my-env.scalekit.com/resources/sk_resource_456"
+        )
+
+
+@pytest.fixture
+async def mcp_server_url():
+    """Start Scalekit server."""
+    mcp = FastMCP(
+        auth=ScalekitProvider(
+            environment_url="https://test-env.scalekit.com",
+            resource_id="sk_resource_test_456",
+            base_url="http://localhost:4321",
+        )
+    )
+
+    @mcp.tool
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    async with run_server_async(mcp, transport="http") as url:
+        yield url
+
+
+@pytest.fixture
+def client_with_headless_oauth(mcp_server_url: str) -> Client:
+    """Client with headless OAuth that bypasses browser interaction."""
+    return Client(
+        transport=StreamableHttpTransport(mcp_server_url),
+        auth=HeadlessOAuth(mcp_url=mcp_server_url),
+    )
+
+
+class TestScalekitProviderIntegration:
+    async def test_unauthorized_access(self, mcp_server_url: str):
+        # SDK v2 surfaces the server's 401 as a generic MCPError at the client
+        # boundary rather than re-raising httpx.HTTPStatusError.
+        with pytest.raises(MCPError):
+            async with Client(mcp_server_url) as client:
+                tools = await client.list_tools()  # noqa: F841
+        assert "tools" not in locals()
+
+    async def test_metadata_route_forwards_scalekit_response(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+        mcp_server_url: str,
+    ) -> None:
+        """Ensure Scalekit metadata route proxies upstream JSON."""
+
+        metadata_payload = {
+            "issuer": "https://test-env.scalekit.com",
+            "token_endpoint": "https://test-env.scalekit.com/token",
+            "authorization_endpoint": "https://test-env.scalekit.com/authorize",
+        }
+
+        class DummyResponse:
+            status_code = 200
+
+            def __init__(self, data: dict[str, str]):
+                self._data = data
+
+            def json(self):
+                return self._data
+
+            def raise_for_status(self):
+                return None
+
+        class DummyAsyncClient:
+            last_url: str | None = None
+
+            async def __aenter__(self):
+                return self
+
+            async def __aexit__(self, exc_type, exc, tb):
+                return False
+
+            async def get(self, url: str):
+                DummyAsyncClient.last_url = url
+                return DummyResponse(metadata_payload)
+
+        real_httpx_client = httpx.AsyncClient
+
+        monkeypatch.setattr(
+            "fastmcp.server.auth.providers.scalekit.httpx.AsyncClient",
+            DummyAsyncClient,
+        )
+
+        base_url = mcp_server_url.rsplit("/mcp", 1)[0]
+        async with real_httpx_client() as client:
+            response = await client.get(
+                f"{base_url}/.well-known/oauth-authorization-server"
+            )
+
+        assert response.status_code == 200
+        assert response.json() == metadata_payload
+        assert (
+            DummyAsyncClient.last_url
+            == "https://test-env.scalekit.com/.well-known/oauth-authorization-server/resources/sk_resource_test_456"
+        )
diff --git a/tests/server/auth/providers/test_supabase.py b/tests/server/auth/providers/test_supabase.py
new file mode 100644
index 0000000..b15c613
--- /dev/null
+++ b/tests/server/auth/providers/test_supabase.py
@@ -0,0 +1,210 @@
+"""Tests for Supabase Auth provider."""
+
+from collections.abc import Generator
+
+import pytest
+from mcp import MCPError
+
+from fastmcp import Client, FastMCP
+from fastmcp.client.transports import StreamableHttpTransport
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.server.auth.providers.supabase import SupabaseProvider
+from fastmcp.utilities.tests import HeadlessOAuth, run_server_in_process
+
+
+class TestSupabaseProvider:
+    """Test Supabase Auth provider functionality."""
+
+    def test_init_with_explicit_params(self):
+        """Test SupabaseProvider initialization with explicit parameters."""
+        provider = SupabaseProvider(
+            project_url="https://abc123.supabase.co",
+            base_url="https://myserver.com",
+        )
+
+        assert provider.project_url == "https://abc123.supabase.co"
+        assert str(provider.base_url) == "https://myserver.com/"
+
+    def test_environment_variable_loading(self):
+        """Test that environment variables are loaded correctly."""
+        provider = SupabaseProvider(
+            project_url="https://env123.supabase.co",
+            base_url="http://env-server.com",
+        )
+
+        assert provider.project_url == "https://env123.supabase.co"
+        assert str(provider.base_url) == "http://env-server.com/"
+
+    def test_project_url_normalization(self):
+        """Test that project_url handles trailing slashes correctly."""
+        # Without trailing slash
+        provider1 = SupabaseProvider(
+            project_url="https://abc123.supabase.co",
+            base_url="https://myserver.com",
+        )
+        assert provider1.project_url == "https://abc123.supabase.co"
+
+        # With trailing slash - should be stripped
+        provider2 = SupabaseProvider(
+            project_url="https://abc123.supabase.co/",
+            base_url="https://myserver.com",
+        )
+        assert provider2.project_url == "https://abc123.supabase.co"
+
+    def test_jwt_verifier_configured_correctly(self):
+        """Test that JWT verifier is configured correctly."""
+        provider = SupabaseProvider(
+            project_url="https://abc123.supabase.co",
+            base_url="https://myserver.com",
+        )
+
+        # Check that JWT verifier uses the correct endpoints (default auth_route)
+        assert isinstance(provider.token_verifier, JWTVerifier)
+        assert (
+            provider.token_verifier.jwks_uri
+            == "https://abc123.supabase.co/auth/v1/.well-known/jwks.json"
+        )
+        assert provider.token_verifier.issuer == "https://abc123.supabase.co/auth/v1"
+        assert provider.token_verifier.algorithm == "ES256"
+
+    def test_jwt_verifier_with_required_scopes(self):
+        """Test that JWT verifier respects required_scopes."""
+        provider = SupabaseProvider(
+            project_url="https://abc123.supabase.co",
+            base_url="https://myserver.com",
+            required_scopes=["openid", "email"],
+        )
+
+        assert isinstance(provider.token_verifier, JWTVerifier)
+        assert provider.token_verifier.required_scopes == ["openid", "email"]
+
+    def test_authorization_servers_configured(self):
+        """Test that authorization servers list is configured correctly."""
+        provider = SupabaseProvider(
+            project_url="https://abc123.supabase.co",
+            base_url="https://myserver.com",
+        )
+
+        assert len(provider.authorization_servers) == 1
+        assert (
+            str(provider.authorization_servers[0])
+            == "https://abc123.supabase.co/auth/v1"
+        )
+
+    @pytest.mark.parametrize(
+        "algorithm",
+        ["RS256", "ES256"],
+    )
+    def test_algorithm_configuration(self, algorithm):
+        """Test that algorithm can be configured for different JWT signing methods."""
+        provider = SupabaseProvider(
+            project_url="https://abc123.supabase.co",
+            base_url="https://myserver.com",
+            algorithm=algorithm,
+        )
+
+        assert isinstance(provider.token_verifier, JWTVerifier)
+        assert provider.token_verifier.algorithm == algorithm
+
+    def test_algorithm_rejects_hs256(self):
+        """Test that HS256 is rejected for Supabase's JWKS-based verifier."""
+        with pytest.raises(ValueError, match="cannot be used with jwks_uri"):
+            SupabaseProvider(
+                project_url="https://abc123.supabase.co",
+                base_url="https://myserver.com",
+                algorithm="HS256",  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+            )
+
+    def test_algorithm_default_es256(self):
+        """Test that algorithm defaults to ES256 when not specified."""
+        provider = SupabaseProvider(
+            project_url="https://abc123.supabase.co",
+            base_url="https://myserver.com",
+        )
+
+        assert isinstance(provider.token_verifier, JWTVerifier)
+        assert provider.token_verifier.algorithm == "ES256"
+
+    def test_algorithm_from_parameter(self):
+        """Test that algorithm can be configured via parameter."""
+        provider = SupabaseProvider(
+            project_url="https://env123.supabase.co",
+            base_url="https://envserver.com",
+            algorithm="RS256",
+        )
+
+        assert isinstance(provider.token_verifier, JWTVerifier)
+        assert provider.token_verifier.algorithm == "RS256"
+
+    def test_custom_auth_route(self):
+        provider = SupabaseProvider(
+            project_url="https://abc123.supabase.co",
+            base_url="https://myserver.com",
+            auth_route="/custom/auth/route",
+        )
+
+        assert provider.auth_route == "custom/auth/route"
+        assert isinstance(provider.token_verifier, JWTVerifier)
+        assert (
+            provider.token_verifier.jwks_uri
+            == "https://abc123.supabase.co/custom/auth/route/.well-known/jwks.json"
+        )
+
+    def test_custom_auth_route_trailing_slash(self):
+        provider = SupabaseProvider(
+            project_url="https://abc123.supabase.co",
+            base_url="https://myserver.com",
+            auth_route="/custom/auth/route/",
+        )
+
+        assert provider.auth_route == "custom/auth/route"
+
+
+def run_mcp_server(host: str, port: int) -> None:
+    mcp = FastMCP(
+        auth=SupabaseProvider(
+            project_url="https://test123.supabase.co",
+            base_url="http://localhost:4321",
+        )
+    )
+
+    @mcp.tool
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    mcp.run(host=host, port=port, transport="http")
+
+
+@pytest.fixture
+def mcp_server_url() -> Generator[str]:
+    with run_server_in_process(run_mcp_server) as url:
+        yield f"{url}/mcp"
+
+
+@pytest.fixture()
+def client_with_headless_oauth(
+    mcp_server_url: str,
+) -> Generator[Client, None, None]:
+    """Client with headless OAuth that bypasses browser interaction."""
+    client = Client(
+        transport=StreamableHttpTransport(mcp_server_url),
+        auth=HeadlessOAuth(mcp_url=mcp_server_url),
+    )
+    yield client
+
+
+class TestSupabaseProviderIntegration:
+    async def test_unauthorized_access(self, mcp_server_url: str):
+        # SDK v2 surfaces the server's 401 as a generic MCPError at the client
+        # boundary rather than re-raising httpx.HTTPStatusError.
+        with pytest.raises(MCPError):
+            async with Client(mcp_server_url) as client:
+                tools = await client.list_tools()  # noqa: F841
+        assert "tools" not in locals()
+
+    # async def test_authorized_access(self, client_with_headless_oauth: Client):
+    #     async with client_with_headless_oauth:
+    #         tools = await client_with_headless_oauth.list_tools()
+    #     assert tools is not None
+    #     assert len(tools) > 0
+    #     assert "add" in tools
diff --git a/tests/server/auth/providers/test_workos.py b/tests/server/auth/providers/test_workos.py
new file mode 100644
index 0000000..2cdc866
--- /dev/null
+++ b/tests/server/auth/providers/test_workos.py
@@ -0,0 +1,386 @@
+"""Tests for WorkOS OAuth provider."""
+
+from urllib.parse import urlparse
+
+import pytest
+from key_value.aio.stores.memory import MemoryStore
+from mcp import MCPError
+from pytest_httpx import HTTPXMock
+
+from fastmcp import Client, FastMCP
+from fastmcp.client.transports import StreamableHttpTransport
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.server.auth.providers.workos import (
+    AuthKitProvider,
+    WorkOSProvider,
+    WorkOSTokenVerifier,
+)
+from fastmcp.utilities.tests import HeadlessOAuth, run_server_async
+
+
+@pytest.fixture
+def memory_storage() -> MemoryStore:
+    """Provide a MemoryStore for tests to avoid SQLite initialization on Windows."""
+    return MemoryStore()
+
+
+class TestWorkOSProvider:
+    """Test WorkOS OAuth provider functionality."""
+
+    def test_init_with_explicit_params(self, memory_storage: MemoryStore):
+        """Test WorkOSProvider initialization with explicit parameters."""
+        provider = WorkOSProvider(
+            client_id="client_test123",
+            client_secret="secret_test456",
+            authkit_domain="https://test.authkit.app",
+            base_url="https://myserver.com",
+            required_scopes=["openid", "profile"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert provider._upstream_client_id == "client_test123"
+        assert provider._upstream_client_secret is not None
+        assert provider._upstream_client_secret.get_secret_value() == "secret_test456"
+        assert str(provider.base_url) == "https://myserver.com/"
+
+    def test_authkit_domain_https_prefix_handling(self, memory_storage: MemoryStore):
+        """Test that authkit_domain handles missing https:// prefix."""
+        # Without https:// - should add it
+        provider1 = WorkOSProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            authkit_domain="test.authkit.app",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+        parsed = urlparse(provider1._upstream_authorization_endpoint)
+        assert parsed.scheme == "https"
+        assert parsed.netloc == "test.authkit.app"
+        assert parsed.path == "/oauth2/authorize"
+
+        # With https:// - should keep it
+        provider2 = WorkOSProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            authkit_domain="https://test.authkit.app",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+        parsed = urlparse(provider2._upstream_authorization_endpoint)
+        assert parsed.scheme == "https"
+        assert parsed.netloc == "test.authkit.app"
+        assert parsed.path == "/oauth2/authorize"
+
+        # With http:// - should be preserved
+        provider3 = WorkOSProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            authkit_domain="http://localhost:8080",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+        parsed = urlparse(provider3._upstream_authorization_endpoint)
+        assert parsed.scheme == "http"
+        assert parsed.netloc == "localhost:8080"
+        assert parsed.path == "/oauth2/authorize"
+
+    def test_init_defaults(self, memory_storage: MemoryStore):
+        """Test that default values are applied correctly."""
+        provider = WorkOSProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            authkit_domain="https://test.authkit.app",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Check defaults
+        assert provider._redirect_path == "/auth/callback"
+        # WorkOS provider has no default scopes but we can't easily verify without accessing internals
+
+    def test_extra_authorize_params_default_none(self, memory_storage: MemoryStore):
+        """WorkOS doesn't set provider-specific defaults — empty unless caller opts in."""
+        provider = WorkOSProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            authkit_domain="https://test.authkit.app",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        assert provider._extra_authorize_params == {}
+
+    def test_extra_authorize_params_passed_through(self, memory_storage: MemoryStore):
+        """Caller-supplied params are forwarded to the upstream authorize URL.
+
+        Common use case: force `offline_access` into the scope so WorkOS issues
+        a refresh token.
+        """
+        provider = WorkOSProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            authkit_domain="https://test.authkit.app",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+            extra_authorize_params={
+                "scope": "openid profile email offline_access",
+            },
+        )
+
+        assert provider._extra_authorize_params == {
+            "scope": "openid profile email offline_access",
+        }
+
+    def test_valid_scopes_passed_through(self, memory_storage: MemoryStore):
+        """valid_scopes is forwarded to OAuthProxy and advertised via DCR."""
+        provider = WorkOSProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            authkit_domain="https://test.authkit.app",
+            base_url="https://myserver.com",
+            required_scopes=["openid"],
+            valid_scopes=["openid", "profile", "email", "offline_access"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        reg_options = provider.client_registration_options
+        assert reg_options is not None
+        assert reg_options.valid_scopes is not None
+        assert set(reg_options.valid_scopes) == {
+            "openid",
+            "profile",
+            "email",
+            "offline_access",
+        }
+
+    def test_valid_scopes_defaults_to_required(self, memory_storage: MemoryStore):
+        """When valid_scopes is omitted, the OAuthProxy falls back to required_scopes."""
+        provider = WorkOSProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            authkit_domain="https://test.authkit.app",
+            base_url="https://myserver.com",
+            required_scopes=["openid", "profile"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        reg_options = provider.client_registration_options
+        assert reg_options is not None
+        assert reg_options.valid_scopes is not None
+        assert set(reg_options.valid_scopes) == {"openid", "profile"}
+
+    def test_oauth_endpoints_configured_correctly(self, memory_storage: MemoryStore):
+        """Test that OAuth endpoints are configured correctly."""
+        provider = WorkOSProvider(
+            client_id="test_client",
+            client_secret="test_secret",
+            authkit_domain="https://test.authkit.app",
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Check that endpoints use the authkit domain
+        assert (
+            provider._upstream_authorization_endpoint
+            == "https://test.authkit.app/oauth2/authorize"
+        )
+        assert (
+            provider._upstream_token_endpoint == "https://test.authkit.app/oauth2/token"
+        )
+        assert (
+            provider._upstream_revocation_endpoint is None
+        )  # WorkOS doesn't support revocation
+
+
+@pytest.fixture
+async def mcp_server_url():
+    """Start AuthKit server."""
+    mcp = FastMCP(
+        auth=AuthKitProvider(
+            authkit_domain="https://respectful-lullaby-34-staging.authkit.app",
+            base_url="http://localhost:4321",
+        )
+    )
+
+    @mcp.tool
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    async with run_server_async(mcp, transport="http") as url:
+        yield url
+
+
+@pytest.fixture
+def client_with_headless_oauth(mcp_server_url: str) -> Client:
+    """Client with headless OAuth that bypasses browser interaction."""
+    return Client(
+        transport=StreamableHttpTransport(mcp_server_url),
+        auth=HeadlessOAuth(mcp_url=mcp_server_url),
+    )
+
+
+class TestAuthKitProvider:
+    async def test_unauthorized_access(
+        self, memory_storage: MemoryStore, mcp_server_url: str
+    ):
+        # SDK v2 surfaces the server's 401 as a generic MCPError at the client
+        # boundary rather than re-raising httpx.HTTPStatusError.
+        with pytest.raises(MCPError):
+            async with Client(mcp_server_url) as client:
+                tools = await client.list_tools()  # noqa: F841
+        assert "tools" not in locals()
+
+    # async def test_authorized_access(self, client_with_headless_oauth: Client):
+    #     async with client_with_headless_oauth:
+    #         tools = await client_with_headless_oauth.list_tools()
+    #     assert tools is not None
+    #     assert len(tools) > 0
+    #     assert "add" in tools
+
+
+class TestAuthKitAudienceBinding:
+    """RFC 8707 resource-indicator audience binding.
+
+    AuthKit mints tokens with ``aud`` equal to the resource URL the client
+    requested — which must equal the URL FastMCP advertises in its protected
+    resource metadata. AuthKitProvider auto-wires that equality: once the
+    MCP mount path is known, ``JWTVerifier.audience`` is set to
+    ``_get_resource_url(mcp_path)``.
+    """
+
+    def test_audience_binds_to_resource_url_on_set_mcp_path(self):
+        provider = AuthKitProvider(
+            authkit_domain="https://test.authkit.app",
+            base_url="http://127.0.0.1:8000",
+        )
+
+        verifier = provider.token_verifier
+        assert isinstance(verifier, JWTVerifier)
+        # Audience unset before the path is known — provider has no way to
+        # compute the resource URL yet.
+        assert verifier.audience is None
+
+        provider.set_mcp_path("/mcp")
+
+        expected = str(provider._get_resource_url("/mcp"))
+        assert verifier.audience == expected
+        assert expected == "http://127.0.0.1:8000/mcp"
+
+    def test_set_mcp_path_none_binds_to_base_url(self):
+        """When no MCP path is provided, the resource URL is ``base_url``
+        itself (an MCP-at-root server) and the audience binds to that."""
+        provider = AuthKitProvider(
+            authkit_domain="https://test.authkit.app",
+            base_url="http://127.0.0.1:8000",
+        )
+
+        provider.set_mcp_path(None)
+
+        verifier = provider.token_verifier
+        assert isinstance(verifier, JWTVerifier)
+        # Matches _get_resource_url(None) which returns base_url unchanged.
+        assert verifier.audience == "http://127.0.0.1:8000/"
+
+    def test_audience_respects_resource_base_url(self):
+        """When ``resource_base_url`` differs from ``base_url``, the audience
+        follows the advertised resource URL, not the OAuth-surface URL."""
+        provider = AuthKitProvider(
+            authkit_domain="https://test.authkit.app",
+            base_url="https://oauth.example.com",
+            resource_base_url="https://api.example.com",
+        )
+        provider.set_mcp_path("/mcp")
+
+        verifier = provider.token_verifier
+        assert isinstance(verifier, JWTVerifier)
+        assert verifier.audience == "https://api.example.com/mcp"
+
+    def test_custom_token_verifier_audience_not_overwritten(self):
+        """If the caller supplies their own verifier, we treat its audience
+        as intentional and do not touch it."""
+        custom_audience = "https://some-other-resource.example.com"
+        custom = JWTVerifier(
+            jwks_uri="https://test.authkit.app/oauth2/jwks",
+            issuer="https://test.authkit.app",
+            audience=custom_audience,
+        )
+        provider = AuthKitProvider(
+            authkit_domain="https://test.authkit.app",
+            base_url="http://127.0.0.1:8000",
+            token_verifier=custom,
+        )
+        provider.set_mcp_path("/mcp")
+
+        assert provider.token_verifier is custom
+        assert custom.audience == custom_audience
+
+    def test_audience_binds_through_http_app(self):
+        """End-to-end: mounting a FastMCP server triggers the lifecycle hook
+        that populates ``JWTVerifier.audience``."""
+        auth = AuthKitProvider(
+            authkit_domain="https://test.authkit.app",
+            base_url="http://127.0.0.1:8000",
+        )
+        mcp = FastMCP("test", auth=auth)
+        mcp.http_app(path="/mcp")
+
+        verifier = auth.token_verifier
+        assert isinstance(verifier, JWTVerifier)
+        assert verifier.audience == "http://127.0.0.1:8000/mcp"
+
+
+class TestWorkOSTokenVerifierScopes:
+    async def test_verify_token_rejects_missing_required_scopes(
+        self, httpx_mock: HTTPXMock
+    ):
+        httpx_mock.add_response(
+            url="https://test.authkit.app/oauth2/userinfo",
+            status_code=200,
+            json={
+                "sub": "user_123",
+                "email": "user@example.com",
+                "scope": "openid profile",
+            },
+        )
+
+        verifier = WorkOSTokenVerifier(
+            authkit_domain="https://test.authkit.app",
+            required_scopes=["read:secrets"],
+        )
+
+        result = await verifier.verify_token("token")
+
+        assert result is None
+
+    async def test_verify_token_returns_actual_token_scopes(
+        self, httpx_mock: HTTPXMock
+    ):
+        httpx_mock.add_response(
+            url="https://test.authkit.app/oauth2/userinfo",
+            status_code=200,
+            json={
+                "sub": "user_123",
+                "email": "user@example.com",
+                "scope": "openid profile read:secrets",
+            },
+        )
+
+        verifier = WorkOSTokenVerifier(
+            authkit_domain="https://test.authkit.app",
+            required_scopes=["read:secrets"],
+        )
+
+        result = await verifier.verify_token("token")
+
+        assert result is not None
+        assert result.scopes == ["openid", "profile", "read:secrets"]
diff --git a/tests/server/auth/test_auth_provider.py b/tests/server/auth/test_auth_provider.py
new file mode 100644
index 0000000..22f98e0
--- /dev/null
+++ b/tests/server/auth/test_auth_provider.py
@@ -0,0 +1,128 @@
+import re
+
+import httpx
+import pytest
+from pydantic import AnyHttpUrl
+
+from fastmcp import FastMCP
+from fastmcp.server.auth import RemoteAuthProvider, TokenVerifier
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.server.auth.providers.jwt import StaticTokenVerifier
+
+
+class LegacyTokenVerifier(TokenVerifier):
+    """Mimics custom verifiers that still call the old positional super().__init__."""
+
+    def __init__(
+        self,
+        base_url: AnyHttpUrl | str | None = None,
+        required_scopes: list[str] | None = None,
+    ):
+        super().__init__(base_url, required_scopes)
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        return None
+
+
+class TestAuthProviderBase:
+    """Test suite for base AuthProvider behaviors that apply to all auth providers."""
+
+    def test_token_verifier_preserves_legacy_positional_required_scopes(self):
+        """Legacy positional super().__init__(base_url, required_scopes) should keep working."""
+        verifier = LegacyTokenVerifier("https://my-server.com", ["read"])
+
+        assert verifier.base_url == AnyHttpUrl("https://my-server.com/")
+        assert verifier.required_scopes == ["read"]
+        assert verifier.resource_base_url is None
+
+    @pytest.fixture
+    def basic_remote_provider(self):
+        """Basic RemoteAuthProvider fixture for testing base AuthProvider behaviors."""
+        # Create a static token verifier with a test token
+        tokens = {
+            "test_token": {
+                "client_id": "test-client",
+                "scopes": ["read", "write"],
+            }
+        }
+        token_verifier = StaticTokenVerifier(tokens=tokens)
+        return RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://my-server.com",
+        )
+
+    async def test_www_authenticate_header_points_to_base_url(
+        self, basic_remote_provider
+    ):
+        """Test that WWW-Authenticate header points to RFC 9728-compliant metadata URL.
+
+        The WWW-Authenticate header includes the resource path per RFC 9728,
+        so clients can discover where the metadata is actually registered.
+        """
+        mcp = FastMCP("test-server", auth=basic_remote_provider)
+        # Mount MCP at a non-root path
+        mcp_http_app = mcp.http_app(path="/api/v1/mcp")
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=mcp_http_app),
+            base_url="https://my-server.com",
+        ) as client:
+            # Make unauthorized request to MCP endpoint
+            response = await client.get("/api/v1/mcp")
+            assert response.status_code == 401
+
+            www_auth = response.headers.get("www-authenticate", "")
+            assert "resource_metadata=" in www_auth
+
+            # Extract the metadata URL from the header
+            match = re.search(r'resource_metadata="([^"]+)"', www_auth)
+            assert match is not None
+            metadata_url = match.group(1)
+
+            # The metadata URL includes the resource path per RFC 9728
+            assert (
+                metadata_url
+                == "https://my-server.com/.well-known/oauth-protected-resource/api/v1/mcp"
+            )
+
+    async def test_automatic_resource_url_capture(self, basic_remote_provider):
+        """Test that resource URL is automatically captured from MCP path.
+
+        This test verifies PR #1682 functionality where the resource URL
+        should be automatically set based on the MCP endpoint path.
+        """
+        mcp = FastMCP("test-server", auth=basic_remote_provider)
+        # Mount MCP at a specific path
+        mcp_http_app = mcp.http_app(path="/mcp")
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=mcp_http_app),
+            base_url="https://my-server.com",
+        ) as client:
+            # The .well-known metadata is at a path-aware location per RFC 9728
+            response = await client.get("/.well-known/oauth-protected-resource/mcp")
+            assert response.status_code == 200
+
+            data = response.json()
+            # The resource URL should be automatically set to the MCP path
+            assert data.get("resource") == "https://my-server.com/mcp"
+
+    async def test_automatic_resource_url_with_nested_path(self, basic_remote_provider):
+        """Test automatic resource URL capture with deeply nested MCP path."""
+        mcp = FastMCP("test-server", auth=basic_remote_provider)
+        mcp_http_app = mcp.http_app(path="/api/v2/services/mcp")
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=mcp_http_app),
+            base_url="https://my-server.com",
+        ) as client:
+            # The .well-known metadata includes the resource path per RFC 9728
+            response = await client.get(
+                "/.well-known/oauth-protected-resource/api/v2/services/mcp"
+            )
+            assert response.status_code == 200
+
+            data = response.json()
+            # Should automatically capture the nested path
+            assert data.get("resource") == "https://my-server.com/api/v2/services/mcp"
diff --git a/tests/server/auth/test_authorization.py b/tests/server/auth/test_authorization.py
new file mode 100644
index 0000000..5d18705
--- /dev/null
+++ b/tests/server/auth/test_authorization.py
@@ -0,0 +1,999 @@
+"""Tests for authorization checks and AuthMiddleware."""
+
+from unittest.mock import Mock
+
+import pytest
+from mcp.server.auth.middleware.auth_context import auth_context_var
+from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.exceptions import AuthorizationError
+from fastmcp.server.auth import (
+    AccessToken,
+    AuthContext,
+    require_scopes,
+    restrict_tag,
+    run_auth_checks,
+)
+from fastmcp.server.middleware import AuthMiddleware
+from fastmcp.server.transforms import ToolTransform
+from fastmcp.tools.tool_transform import ToolTransformConfig, TransformedTool
+from fastmcp.utilities.versions import VersionSpec
+
+# =============================================================================
+# Test helpers
+# =============================================================================
+
+
+def make_token(scopes: list[str] | None = None) -> AccessToken:
+    """Create a test access token."""
+    return AccessToken(
+        token="test-token",
+        client_id="test-client",
+        scopes=scopes or [],
+        expires_at=None,
+        claims={},
+    )
+
+
+def make_tool() -> Mock:
+    """Create a mock tool for testing."""
+    tool = Mock()
+    tool.tags = set()
+    return tool
+
+
+def make_restricted_tag_server() -> FastMCP:
+    return FastMCP(
+        middleware=[AuthMiddleware(auth=restrict_tag("admin", scopes=["admin"]))]
+    )
+
+
+# =============================================================================
+# Tests for require_scopes
+# =============================================================================
+
+
+class TestRequireScopes:
+    def test_returns_true_with_matching_scope(self):
+        token = make_token(scopes=["admin"])
+        ctx = AuthContext(token=token, component=make_tool())
+        check = require_scopes("admin")
+        assert check(ctx) is True
+
+    def test_returns_true_with_all_required_scopes(self):
+        token = make_token(scopes=["read", "write", "admin"])
+        ctx = AuthContext(token=token, component=make_tool())
+        check = require_scopes("read", "write")
+        assert check(ctx) is True
+
+    def test_returns_false_with_missing_scope(self):
+        token = make_token(scopes=["read"])
+        ctx = AuthContext(token=token, component=make_tool())
+        check = require_scopes("admin")
+        assert check(ctx) is False
+
+    def test_returns_false_with_partial_scopes(self):
+        token = make_token(scopes=["read"])
+        ctx = AuthContext(token=token, component=make_tool())
+        check = require_scopes("read", "write")
+        assert check(ctx) is False
+
+    def test_returns_false_without_token(self):
+        ctx = AuthContext(token=None, component=make_tool())
+        check = require_scopes("admin")
+        assert check(ctx) is False
+
+
+# =============================================================================
+# Tests for restrict_tag
+# =============================================================================
+
+
+class TestRestrictTag:
+    def test_allows_access_when_tag_not_present(self):
+        tool = make_tool()
+        tool.tags = {"other"}
+        ctx = AuthContext(token=None, component=tool)
+        check = restrict_tag("admin", scopes=["admin"])
+        assert check(ctx) is True
+
+    def test_blocks_access_when_tag_present_without_token(self):
+        tool = make_tool()
+        tool.tags = {"admin"}
+        ctx = AuthContext(token=None, component=tool)
+        check = restrict_tag("admin", scopes=["admin"])
+        assert check(ctx) is False
+
+    def test_blocks_access_when_tag_present_without_scope(self):
+        tool = make_tool()
+        tool.tags = {"admin"}
+        token = make_token(scopes=["read"])
+        ctx = AuthContext(token=token, component=tool)
+        check = restrict_tag("admin", scopes=["admin"])
+        assert check(ctx) is False
+
+    def test_allows_access_when_tag_present_with_scope(self):
+        tool = make_tool()
+        tool.tags = {"admin"}
+        token = make_token(scopes=["admin"])
+        ctx = AuthContext(token=token, component=tool)
+        check = restrict_tag("admin", scopes=["admin"])
+        assert check(ctx) is True
+
+
+# =============================================================================
+# Tests for run_auth_checks
+# =============================================================================
+
+
+class TestRunAuthChecks:
+    async def test_single_check_passes(self):
+        ctx = AuthContext(token=make_token(scopes=["test"]), component=make_tool())
+        assert await run_auth_checks(require_scopes("test"), ctx) is True
+
+    async def test_single_check_fails(self):
+        ctx = AuthContext(token=None, component=make_tool())
+        assert await run_auth_checks(require_scopes("test"), ctx) is False
+
+    async def test_multiple_checks_all_pass(self):
+        token = make_token(scopes=["test", "admin"])
+        ctx = AuthContext(token=token, component=make_tool())
+        checks = [require_scopes("test"), require_scopes("admin")]
+        assert await run_auth_checks(checks, ctx) is True
+
+    async def test_multiple_checks_one_fails(self):
+        token = make_token(scopes=["read"])
+        ctx = AuthContext(token=token, component=make_tool())
+        checks = [require_scopes("read"), require_scopes("admin")]
+        assert await run_auth_checks(checks, ctx) is False
+
+    async def test_empty_list_passes(self):
+        ctx = AuthContext(token=None, component=make_tool())
+        assert await run_auth_checks([], ctx) is True
+
+    async def test_custom_lambda_check(self):
+        token = make_token()
+        token.claims = {"level": 5}
+        ctx = AuthContext(token=token, component=make_tool())
+
+        def check(ctx: AuthContext) -> bool:
+            return ctx.token is not None and ctx.token.claims.get("level", 0) >= 3
+
+        assert await run_auth_checks(check, ctx) is True
+
+    async def test_authorization_error_propagates(self):
+        """AuthorizationError from auth check should propagate with custom message."""
+
+        def custom_auth_check(ctx: AuthContext) -> bool:
+            raise AuthorizationError("Custom denial reason")
+
+        ctx = AuthContext(token=make_token(), component=make_tool())
+        with pytest.raises(AuthorizationError, match="Custom denial reason"):
+            await run_auth_checks(custom_auth_check, ctx)
+
+    async def test_generic_exception_is_masked(self):
+        """Generic exceptions from auth checks should be masked (return False)."""
+
+        def buggy_auth_check(ctx: AuthContext) -> bool:
+            raise ValueError("Unexpected internal error")
+
+        ctx = AuthContext(token=make_token(), component=make_tool())
+        # Should return False, not raise the ValueError
+        assert await run_auth_checks(buggy_auth_check, ctx) is False
+
+    async def test_authorization_error_stops_chain(self):
+        """AuthorizationError should stop the check chain and propagate."""
+        call_order = []
+
+        def check_1(ctx: AuthContext) -> bool:
+            call_order.append(1)
+            return True
+
+        def check_2(ctx: AuthContext) -> bool:
+            call_order.append(2)
+            raise AuthorizationError("Explicit denial")
+
+        def check_3(ctx: AuthContext) -> bool:
+            call_order.append(3)
+            return True
+
+        ctx = AuthContext(token=make_token(), component=make_tool())
+        with pytest.raises(AuthorizationError, match="Explicit denial"):
+            await run_auth_checks([check_1, check_2, check_3], ctx)
+
+        # Check 3 should not be called
+        assert call_order == [1, 2]
+
+    async def test_async_check_passes(self):
+        """Async auth check functions should be awaited."""
+
+        async def async_check(ctx: AuthContext) -> bool:
+            return ctx.token is not None
+
+        ctx = AuthContext(token=make_token(), component=make_tool())
+        assert await run_auth_checks(async_check, ctx) is True
+
+    async def test_async_check_fails(self):
+        """Async auth check that returns False should deny access."""
+
+        async def async_check(ctx: AuthContext) -> bool:
+            return False
+
+        ctx = AuthContext(token=make_token(), component=make_tool())
+        assert await run_auth_checks(async_check, ctx) is False
+
+    async def test_mixed_sync_and_async_checks(self):
+        """A mix of sync and async checks should all be evaluated."""
+
+        def sync_check(ctx: AuthContext) -> bool:
+            return True
+
+        async def async_check(ctx: AuthContext) -> bool:
+            return ctx.token is not None
+
+        ctx = AuthContext(token=make_token(scopes=["test"]), component=make_tool())
+        checks = [sync_check, async_check, require_scopes("test")]
+        assert await run_auth_checks(checks, ctx) is True
+
+    async def test_async_check_exception_is_masked(self):
+        """Async checks that raise non-AuthorizationError should be masked."""
+
+        async def buggy_async_check(ctx: AuthContext) -> bool:
+            raise ValueError("async error")
+
+        ctx = AuthContext(token=make_token(), component=make_tool())
+        assert await run_auth_checks(buggy_async_check, ctx) is False
+
+    async def test_async_check_authorization_error_propagates(self):
+        """Async checks that raise AuthorizationError should propagate."""
+
+        async def async_denial(ctx: AuthContext) -> bool:
+            raise AuthorizationError("Async denial")
+
+        ctx = AuthContext(token=make_token(), component=make_tool())
+        with pytest.raises(AuthorizationError, match="Async denial"):
+            await run_auth_checks(async_denial, ctx)
+
+
+# =============================================================================
+# Tests for tool-level auth with FastMCP
+# =============================================================================
+
+
+def set_token(token: AccessToken | None):
+    """Set the access token in the auth context var."""
+    if token is None:
+        return auth_context_var.set(None)
+    return auth_context_var.set(AuthenticatedUser(token))
+
+
+class TestToolLevelAuth:
+    async def test_tool_without_auth_is_visible(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def public_tool() -> str:
+            return "public"
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+        assert tools[0].name == "public_tool"
+
+    async def test_tool_with_auth_hidden_without_token(self):
+        mcp = FastMCP()
+
+        @mcp.tool(auth=require_scopes("test"))
+        def protected_tool() -> str:
+            return "protected"
+
+        # No token set - tool should be hidden
+        tools = await mcp.list_tools()
+        assert len(tools) == 0
+
+    async def test_tool_with_auth_visible_with_token(self):
+        mcp = FastMCP()
+
+        @mcp.tool(auth=require_scopes("test"))
+        def protected_tool() -> str:
+            return "protected"
+
+        # Set token in context
+        token = make_token(scopes=["test"])
+        tok = set_token(token)
+        try:
+            tools = await mcp.list_tools()
+            assert len(tools) == 1
+            assert tools[0].name == "protected_tool"
+        finally:
+            auth_context_var.reset(tok)
+
+    async def test_tool_with_scope_auth_hidden_without_scope(self):
+        mcp = FastMCP()
+
+        @mcp.tool(auth=require_scopes("admin"))
+        def admin_tool() -> str:
+            return "admin"
+
+        # Token without admin scope
+        token = make_token(scopes=["read"])
+        tok = set_token(token)
+        try:
+            tools = await mcp.list_tools()
+            assert len(tools) == 0
+        finally:
+            auth_context_var.reset(tok)
+
+    async def test_tool_with_scope_auth_visible_with_scope(self):
+        mcp = FastMCP()
+
+        @mcp.tool(auth=require_scopes("admin"))
+        def admin_tool() -> str:
+            return "admin"
+
+        # Token with admin scope
+        token = make_token(scopes=["admin"])
+        tok = set_token(token)
+        try:
+            tools = await mcp.list_tools()
+            assert len(tools) == 1
+            assert tools[0].name == "admin_tool"
+        finally:
+            auth_context_var.reset(tok)
+
+    async def test_get_tool_returns_none_without_auth(self):
+        """get_tool() returns None for unauthorized tools (consistent with list filtering)."""
+        mcp = FastMCP()
+
+        @mcp.tool(auth=require_scopes("test"))
+        def protected_tool() -> str:
+            return "protected"
+
+        # get_tool() returns None for unauthorized tools
+        tool = await mcp.get_tool("protected_tool")
+        assert tool is None
+
+    async def test_get_tool_returns_tool_with_auth(self):
+        mcp = FastMCP()
+
+        @mcp.tool(auth=require_scopes("test"))
+        def protected_tool() -> str:
+            return "protected"
+
+        token = make_token(scopes=["test"])
+        tok = set_token(token)
+        try:
+            tool = await mcp.get_tool("protected_tool")
+            assert tool is not None
+            assert tool.name == "protected_tool"
+        finally:
+            auth_context_var.reset(tok)
+
+
+# =============================================================================
+# Tests for AuthMiddleware
+# =============================================================================
+
+
+class TestAuthMiddleware:
+    """Tests for middleware filtering via the MCP handler layer.
+
+    These tests drive an in-memory client so the middleware runs in the dispatch
+    chain, exactly as it does when a real client calls list_tools over MCP.
+    """
+
+    async def test_middleware_filters_tools_without_token(self):
+        mcp = FastMCP(middleware=[AuthMiddleware(auth=require_scopes("test"))])
+
+        @mcp.tool
+        def public_tool() -> str:
+            return "public"
+
+        # No token - all tools filtered by middleware
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+        assert len(tools) == 0
+
+    async def test_middleware_allows_tools_with_token(self):
+        mcp = FastMCP(middleware=[AuthMiddleware(auth=require_scopes("test"))])
+
+        @mcp.tool
+        def public_tool() -> str:
+            return "public"
+
+        token = make_token(scopes=["test"])
+        tok = set_token(token)
+        try:
+            async with Client(mcp) as client:
+                tools = await client.list_tools()
+            assert len(tools) == 1
+        finally:
+            auth_context_var.reset(tok)
+
+    async def test_middleware_with_scope_check(self):
+        mcp = FastMCP(middleware=[AuthMiddleware(auth=require_scopes("api"))])
+
+        @mcp.tool
+        def api_tool() -> str:
+            return "api"
+
+        # Token without api scope
+        token = make_token(scopes=["read"])
+        tok = set_token(token)
+        try:
+            async with Client(mcp) as client:
+                tools = await client.list_tools()
+            assert len(tools) == 0
+        finally:
+            auth_context_var.reset(tok)
+
+        # Token with api scope
+        token = make_token(scopes=["api"])
+        tok = set_token(token)
+        try:
+            async with Client(mcp) as client:
+                tools = await client.list_tools()
+            assert len(tools) == 1
+        finally:
+            auth_context_var.reset(tok)
+
+    async def test_middleware_with_restrict_tag(self):
+        mcp = FastMCP(
+            middleware=[AuthMiddleware(auth=restrict_tag("admin", scopes=["admin"]))]
+        )
+
+        @mcp.tool
+        def public_tool() -> str:
+            return "public"
+
+        @mcp.tool(tags={"admin"})
+        def admin_tool() -> str:
+            return "admin"
+
+        # No token - public tool allowed, admin tool blocked
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+        assert len(tools) == 1
+        assert tools[0].name == "public_tool"
+
+        # Token with admin scope - both allowed
+        token = make_token(scopes=["admin"])
+        tok = set_token(token)
+        try:
+            async with Client(mcp) as client:
+                tools = await client.list_tools()
+            assert len(tools) == 2
+        finally:
+            auth_context_var.reset(tok)
+
+    async def test_middleware_skips_tool_on_authorization_error(self):
+        def deny_blocked_tool(ctx: AuthContext) -> bool:
+            if ctx.component.name == "blocked_tool":
+                raise AuthorizationError(f"deny {ctx.component.name}")
+            return True
+
+        mcp = FastMCP(middleware=[AuthMiddleware(auth=deny_blocked_tool)])
+
+        @mcp.tool
+        def blocked_tool() -> str:
+            return "blocked"
+
+        @mcp.tool
+        def allowed_tool() -> str:
+            return "allowed"
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+        assert [tool.name for tool in tools] == ["allowed_tool"]
+
+    async def test_middleware_skips_resource_on_authorization_error(self):
+        def deny_blocked_resource(ctx: AuthContext) -> bool:
+            if ctx.component.name == "blocked_resource":
+                raise AuthorizationError(f"deny {ctx.component.name}")
+            return True
+
+        mcp = FastMCP(middleware=[AuthMiddleware(auth=deny_blocked_resource)])
+
+        @mcp.resource("resource://blocked")
+        def blocked_resource() -> str:
+            return "blocked"
+
+        @mcp.resource("resource://allowed")
+        def allowed_resource() -> str:
+            return "allowed"
+
+        async with Client(mcp) as client:
+            resources = await client.list_resources()
+        assert [str(resource.uri) for resource in resources] == ["resource://allowed"]
+
+    async def test_middleware_skips_resource_template_on_authorization_error(self):
+        def deny_blocked_resource_template(ctx: AuthContext) -> bool:
+            if ctx.component.name == "blocked_resource_template":
+                raise AuthorizationError(f"deny {ctx.component.name}")
+            return True
+
+        mcp = FastMCP(middleware=[AuthMiddleware(auth=deny_blocked_resource_template)])
+
+        @mcp.resource("resource://blocked/{item}")
+        def blocked_resource_template(item: str) -> str:
+            return item
+
+        @mcp.resource("resource://allowed/{item}")
+        def allowed_resource_template(item: str) -> str:
+            return item
+
+        async with Client(mcp) as client:
+            templates = await client.list_resource_templates()
+        assert [template.uri_template for template in templates] == [
+            "resource://allowed/{item}"
+        ]
+
+    async def test_middleware_skips_prompt_on_authorization_error(self):
+        def deny_blocked_prompt(ctx: AuthContext) -> bool:
+            if ctx.component.name == "blocked_prompt":
+                raise AuthorizationError(f"deny {ctx.component.name}")
+            return True
+
+        mcp = FastMCP(middleware=[AuthMiddleware(auth=deny_blocked_prompt)])
+
+        @mcp.prompt
+        def blocked_prompt() -> str:
+            return "blocked"
+
+        @mcp.prompt
+        def allowed_prompt() -> str:
+            return "allowed"
+
+        async with Client(mcp) as client:
+            prompts = await client.list_prompts()
+        assert [prompt.name for prompt in prompts] == ["allowed_prompt"]
+
+
+# =============================================================================
+# Integration tests with Client
+# =============================================================================
+
+
+class TestAuthIntegration:
+    async def test_client_only_sees_authorized_tools(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def public_tool() -> str:
+            return "public"
+
+        @mcp.tool(auth=require_scopes("test"))
+        def protected_tool() -> str:
+            return "protected"
+
+        async with Client(mcp) as client:
+            # No token - only public tool visible
+            tools = await client.list_tools()
+            assert len(tools) == 1
+            assert tools[0].name == "public_tool"
+
+    async def test_client_with_token_sees_all_authorized_tools(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def public_tool() -> str:
+            return "public"
+
+        @mcp.tool(auth=require_scopes("test"))
+        def protected_tool() -> str:
+            return "protected"
+
+        # Set token before creating client
+        token = make_token(scopes=["test"])
+        tok = set_token(token)
+        try:
+            async with Client(mcp) as client:
+                tools = await client.list_tools()
+                tool_names = [t.name for t in tools]
+                # With token, both tools should be visible
+                assert "public_tool" in tool_names
+                assert "protected_tool" in tool_names
+        finally:
+            auth_context_var.reset(tok)
+
+
+# =============================================================================
+# Integration tests with async auth checks
+# =============================================================================
+
+
+class TestAsyncAuthIntegration:
+    async def test_async_auth_check_filters_tool_listing(self):
+        """Async auth checks should work for filtering tool lists."""
+        mcp = FastMCP()
+
+        async def check_claims(ctx: AuthContext) -> bool:
+            return ctx.token is not None and ctx.token.claims.get("role") == "admin"
+
+        @mcp.tool(auth=check_claims)
+        def admin_tool() -> str:
+            return "admin"
+
+        @mcp.tool
+        def public_tool() -> str:
+            return "public"
+
+        # Without token, only public tool visible
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+        assert tools[0].name == "public_tool"
+
+        # With correct claims, both visible
+        token = make_token()
+        token.claims = {"role": "admin"}
+        tok = set_token(token)
+        try:
+            tools = await mcp.list_tools()
+            assert len(tools) == 2
+        finally:
+            auth_context_var.reset(tok)
+
+    async def test_async_auth_check_on_tool_call(self):
+        """Async auth checks should work for tool execution via client."""
+        mcp = FastMCP()
+
+        async def check_claims(ctx: AuthContext) -> bool:
+            return ctx.token is not None and ctx.token.claims.get("role") == "admin"
+
+        @mcp.tool(auth=check_claims)
+        def admin_tool() -> str:
+            return "secret"
+
+        token = make_token()
+        token.claims = {"role": "admin"}
+        tok = set_token(token)
+        try:
+            async with Client(mcp) as client:
+                result = await client.call_tool("admin_tool", {})
+                assert result.content[0].text == "secret"
+        finally:
+            auth_context_var.reset(tok)
+
+    async def test_async_auth_middleware(self):
+        """Async auth checks should work with AuthMiddleware."""
+
+        async def async_scope_check(ctx: AuthContext) -> bool:
+            return ctx.token is not None and "api" in ctx.token.scopes
+
+        mcp = FastMCP(middleware=[AuthMiddleware(auth=async_scope_check)])
+
+        @mcp.tool
+        def api_tool() -> str:
+            return "api"
+
+        # Without token, tool is hidden
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+        assert len(tools) == 0
+
+        # With token containing "api" scope, tool is visible
+        token = make_token(scopes=["api"])
+        tok = set_token(token)
+        try:
+            async with Client(mcp) as client:
+                tools = await client.list_tools()
+            assert len(tools) == 1
+        finally:
+            auth_context_var.reset(tok)
+
+
+# =============================================================================
+# Tests for transformed tools preserving auth
+# =============================================================================
+
+
+class TestTransformedToolAuth:
+    async def test_transformed_tool_preserves_auth(self):
+        """Transformed tools should inherit auth from parent."""
+        mcp = FastMCP()
+
+        @mcp.tool(auth=require_scopes("test"))
+        def protected_tool(x: int) -> str:
+            return str(x)
+
+        # Get the tool and transform it
+        tools = await mcp._local_provider.list_tools()
+        original_tool = tools[0]
+        assert original_tool.auth is not None
+
+        # Transform the tool
+        transformed = TransformedTool.from_tool(
+            original_tool,
+            name="transformed_protected",
+        )
+
+        # Auth should be preserved
+        assert transformed.auth is not None
+        assert transformed.auth == original_tool.auth
+
+    async def test_transformed_tool_filtered_without_token(self):
+        """Transformed tools with auth should be filtered without token."""
+        mcp = FastMCP()
+
+        @mcp.tool(auth=require_scopes("test"))
+        def protected_tool(x: int) -> str:
+            return str(x)
+
+        # Add transformation
+        mcp.add_transform(
+            ToolTransform(
+                {"protected_tool": ToolTransformConfig(name="renamed_protected")}
+            )
+        )
+
+        # Without token, transformed tool should not be visible
+        tools = await mcp.list_tools()
+        assert len(tools) == 0
+
+    async def test_transformed_tool_visible_with_token(self):
+        """Transformed tools with auth should be visible with token."""
+        mcp = FastMCP()
+
+        @mcp.tool(auth=require_scopes("test"))
+        def protected_tool(x: int) -> str:
+            return str(x)
+
+        # Add transformation
+        mcp.add_transform(
+            ToolTransform(
+                {"protected_tool": ToolTransformConfig(name="renamed_protected")}
+            )
+        )
+
+        # With token, transformed tool should be visible
+        token = make_token(scopes=["test"])
+        tok = set_token(token)
+        try:
+            tools = await mcp.list_tools()
+            assert len(tools) == 1
+            assert tools[0].name == "renamed_protected"
+        finally:
+            auth_context_var.reset(tok)
+
+
+# =============================================================================
+# Tests for AuthMiddleware on_call_tool enforcement
+# =============================================================================
+
+
+class TestAuthMiddlewareCallTool:
+    async def test_middleware_blocks_call_without_auth(self):
+        """AuthMiddleware should raise AuthorizationError on unauthorized call."""
+
+        mcp = FastMCP(middleware=[AuthMiddleware(auth=require_scopes("test"))])
+
+        @mcp.tool
+        def my_tool() -> str:
+            return "result"
+
+        # Without token, calling the tool should raise AuthorizationError
+        async with Client(mcp) as client:
+            with pytest.raises(Exception) as exc_info:
+                await client.call_tool("my_tool", {})
+            # The error message should indicate authorization failure
+            assert (
+                "authorization" in str(exc_info.value).lower()
+                or "insufficient" in str(exc_info.value).lower()
+            )
+
+    async def test_middleware_allows_call_with_auth(self):
+        """AuthMiddleware should allow tool call with valid token."""
+        mcp = FastMCP(middleware=[AuthMiddleware(auth=require_scopes("test"))])
+
+        @mcp.tool
+        def my_tool() -> str:
+            return "result"
+
+        # With token, calling the tool should succeed
+        token = make_token(scopes=["test"])
+        tok = set_token(token)
+        try:
+            async with Client(mcp) as client:
+                result = await client.call_tool("my_tool", {})
+                assert result.content[0].text == "result"
+        finally:
+            auth_context_var.reset(tok)
+
+    async def test_middleware_blocks_call_with_wrong_scope(self):
+        """AuthMiddleware should block calls when scope requirements aren't met."""
+
+        mcp = FastMCP(middleware=[AuthMiddleware(auth=require_scopes("admin"))])
+
+        @mcp.tool
+        def admin_tool() -> str:
+            return "admin result"
+
+        # With token that lacks admin scope
+        token = make_token(scopes=["read"])
+        tok = set_token(token)
+        try:
+            async with Client(mcp) as client:
+                with pytest.raises(Exception) as exc_info:
+                    await client.call_tool("admin_tool", {})
+                assert (
+                    "authorization" in str(exc_info.value).lower()
+                    or "insufficient" in str(exc_info.value).lower()
+                )
+        finally:
+            auth_context_var.reset(tok)
+
+
+class TestAuthMiddlewareVersionedRequests:
+    async def test_middleware_blocks_explicit_restricted_tool_version(self):
+        """AuthMiddleware should check the requested tool version."""
+        mcp = make_restricted_tag_server()
+
+        @mcp.tool(name="calc", version="1.0", tags={"admin"})
+        def calc_v1() -> str:
+            return "restricted"
+
+        @mcp.tool(name="calc", version="2.0")
+        def calc_v2() -> str:
+            return "public"
+
+        tok = set_token(make_token(scopes=["read"]))
+        try:
+            async with Client(mcp) as client:
+                with pytest.raises(Exception, match="authorization|insufficient"):
+                    await client.call_tool("calc", {}, version="1.0")
+        finally:
+            auth_context_var.reset(tok)
+
+    async def test_middleware_blocks_restricted_tool_version_selected_by_range(self):
+        """AuthMiddleware should check non-exact direct server version specs."""
+        mcp = make_restricted_tag_server()
+
+        @mcp.tool(name="calc", version="1.0", tags={"admin"})
+        def calc_v1() -> str:
+            return "restricted"
+
+        @mcp.tool(name="calc", version="2.0")
+        def calc_v2() -> str:
+            return "public"
+
+        tok = set_token(make_token(scopes=["read"]))
+        try:
+            with pytest.raises(AuthorizationError):
+                await mcp.call_tool("calc", {}, version=VersionSpec(lt="2.0"))
+        finally:
+            auth_context_var.reset(tok)
+
+    async def test_middleware_blocks_explicit_restricted_resource_version(self):
+        """AuthMiddleware should check the requested resource version."""
+        mcp = make_restricted_tag_server()
+
+        @mcp.resource("data://info", version="1.0", tags={"admin"})
+        def info_v1() -> str:
+            return "restricted"
+
+        @mcp.resource("data://info", version="2.0")
+        def info_v2() -> str:
+            return "public"
+
+        tok = set_token(make_token(scopes=["read"]))
+        try:
+            async with Client(mcp) as client:
+                with pytest.raises(Exception, match="authorization|insufficient"):
+                    await client.read_resource("data://info", version="1.0")
+        finally:
+            auth_context_var.reset(tok)
+
+    async def test_middleware_blocks_explicit_restricted_template_version(self):
+        """AuthMiddleware should check the requested resource template version."""
+        mcp = make_restricted_tag_server()
+
+        @mcp.resource("data://items/{item_id}", version="1.0", tags={"admin"})
+        def item_v1(item_id: str) -> str:
+            return f"restricted {item_id}"
+
+        @mcp.resource("data://items/{item_id}", version="2.0")
+        def item_v2(item_id: str) -> str:
+            return f"public {item_id}"
+
+        tok = set_token(make_token(scopes=["read"]))
+        try:
+            async with Client(mcp) as client:
+                with pytest.raises(Exception, match="authorization|insufficient"):
+                    await client.read_resource("data://items/123", version="1.0")
+        finally:
+            auth_context_var.reset(tok)
+
+    async def test_middleware_blocks_explicit_restricted_prompt_version(self):
+        """AuthMiddleware should check the requested prompt version."""
+        mcp = make_restricted_tag_server()
+
+        @mcp.prompt(name="greet", version="1.0", tags={"admin"})
+        def greet_v1() -> str:
+            return "restricted"
+
+        @mcp.prompt(name="greet", version="2.0")
+        def greet_v2() -> str:
+            return "public"
+
+        tok = set_token(make_token(scopes=["read"]))
+        try:
+            async with Client(mcp) as client:
+                with pytest.raises(Exception, match="authorization|insufficient"):
+                    await client.get_prompt("greet", version="1.0")
+        finally:
+            auth_context_var.reset(tok)
+
+
+# =============================================================================
+# Tests for component-level auth denial messaging (issue #4054 bug 1)
+# =============================================================================
+
+
+def _allow_all(ctx: AuthContext) -> bool:
+    """Global auth check that always passes (component-level auth still applies)."""
+    return True
+
+
+class TestComponentAuthDenialMessage:
+    """When component-level auth denies access, get_tool/get_resource/get_prompt
+    return None, so the middleware cannot distinguish "missing" from "denied".
+
+    The message must stay ambiguous ("not found or not authorized") rather than
+    asserting the component does not exist (misleading) or that it exists but is
+    forbidden (leaks existence to unauthorized callers).
+    """
+
+    async def test_call_tool_denied_by_component_auth(self):
+        mcp = FastMCP(middleware=[AuthMiddleware(auth=_allow_all)])
+
+        @mcp.tool(auth=require_scopes("admin"))
+        def secret_tool() -> str:
+            return "secret"
+
+        token = make_token(scopes=["read"])
+        tok = set_token(token)
+        try:
+            async with Client(mcp) as client:
+                with pytest.raises(Exception) as exc_info:
+                    await client.call_tool("secret_tool", {})
+            message = str(exc_info.value)
+            assert "not found or not authorized" in message
+        finally:
+            auth_context_var.reset(tok)
+
+    async def test_read_resource_denied_by_component_auth(self):
+        mcp = FastMCP(middleware=[AuthMiddleware(auth=_allow_all)])
+
+        @mcp.resource("data://secret", auth=require_scopes("admin"))
+        def secret_resource() -> str:
+            return "secret"
+
+        token = make_token(scopes=["read"])
+        tok = set_token(token)
+        try:
+            async with Client(mcp) as client:
+                with pytest.raises(Exception) as exc_info:
+                    await client.read_resource("data://secret")
+            message = str(exc_info.value)
+            assert "not found or not authorized" in message
+        finally:
+            auth_context_var.reset(tok)
+
+    async def test_get_prompt_denied_by_component_auth(self):
+        mcp = FastMCP(middleware=[AuthMiddleware(auth=_allow_all)])
+
+        @mcp.prompt(auth=require_scopes("admin"))
+        def secret_prompt() -> str:
+            return "secret"
+
+        token = make_token(scopes=["read"])
+        tok = set_token(token)
+        try:
+            async with Client(mcp) as client:
+                with pytest.raises(Exception) as exc_info:
+                    await client.get_prompt("secret_prompt")
+            message = str(exc_info.value)
+            assert "not found or not authorized" in message
+        finally:
+            auth_context_var.reset(tok)
diff --git a/tests/server/auth/test_cimd.py b/tests/server/auth/test_cimd.py
new file mode 100644
index 0000000..3cd05c2
--- /dev/null
+++ b/tests/server/auth/test_cimd.py
@@ -0,0 +1,552 @@
+"""Unit tests for CIMD (Client ID Metadata Document) functionality."""
+
+from __future__ import annotations
+
+import time
+from unittest.mock import patch
+
+import pytest
+from pydantic import AnyHttpUrl, ValidationError
+
+from fastmcp.server.auth.cimd import (
+    CIMDDocument,
+    CIMDFetcher,
+    CIMDFetchError,
+    CIMDValidationError,
+)
+
+# Standard public IP used for DNS mocking in tests
+TEST_PUBLIC_IP = "93.184.216.34"
+
+
+class TestCIMDDocument:
+    """Tests for CIMDDocument model validation."""
+
+    def test_valid_minimal_document(self):
+        """Test that minimal valid document passes validation."""
+        doc = CIMDDocument(
+            client_id=AnyHttpUrl("https://example.com/client.json"),
+            redirect_uris=["http://localhost:3000/callback"],
+        )
+        assert str(doc.client_id) == "https://example.com/client.json"
+        assert doc.token_endpoint_auth_method == "none"
+        assert doc.grant_types == ["authorization_code"]
+        assert doc.response_types == ["code"]
+
+    def test_valid_full_document(self):
+        """Test that full document passes validation."""
+        doc = CIMDDocument(
+            client_id=AnyHttpUrl("https://example.com/client.json"),
+            client_name="My App",
+            client_uri=AnyHttpUrl("https://example.com"),
+            logo_uri=AnyHttpUrl("https://example.com/logo.png"),
+            redirect_uris=["http://localhost:3000/callback"],
+            token_endpoint_auth_method="none",
+            grant_types=["authorization_code", "refresh_token"],
+            response_types=["code"],
+            scope="read write",
+        )
+        assert doc.client_name == "My App"
+        assert doc.scope == "read write"
+
+    def test_private_key_jwt_auth_method_allowed(self):
+        """Test that private_key_jwt is allowed for CIMD."""
+        doc = CIMDDocument(
+            client_id=AnyHttpUrl("https://example.com/client.json"),
+            redirect_uris=["http://localhost:3000/callback"],
+            token_endpoint_auth_method="private_key_jwt",
+            jwks_uri=AnyHttpUrl("https://example.com/.well-known/jwks.json"),
+        )
+        assert doc.token_endpoint_auth_method == "private_key_jwt"
+
+    def test_client_secret_basic_rejected(self):
+        """Test that client_secret_basic is rejected for CIMD."""
+        with pytest.raises(ValidationError) as exc_info:
+            CIMDDocument(
+                client_id=AnyHttpUrl("https://example.com/client.json"),
+                redirect_uris=["http://localhost:3000/callback"],
+                token_endpoint_auth_method="client_secret_basic",  # type: ignore[arg-type] - testing invalid value  # ty:ignore[invalid-argument-type]
+            )
+        # Literal type rejects invalid values before custom validator
+        assert "token_endpoint_auth_method" in str(exc_info.value)
+
+    def test_client_secret_post_rejected(self):
+        """Test that client_secret_post is rejected for CIMD."""
+        with pytest.raises(ValidationError) as exc_info:
+            CIMDDocument(
+                client_id=AnyHttpUrl("https://example.com/client.json"),
+                redirect_uris=["http://localhost:3000/callback"],
+                token_endpoint_auth_method="client_secret_post",  # type: ignore[arg-type] - testing invalid value  # ty:ignore[invalid-argument-type]
+            )
+        assert "token_endpoint_auth_method" in str(exc_info.value)
+
+    def test_client_secret_jwt_rejected(self):
+        """Test that client_secret_jwt is rejected for CIMD."""
+        with pytest.raises(ValidationError) as exc_info:
+            CIMDDocument(
+                client_id=AnyHttpUrl("https://example.com/client.json"),
+                redirect_uris=["http://localhost:3000/callback"],
+                token_endpoint_auth_method="client_secret_jwt",  # type: ignore[arg-type] - testing invalid value  # ty:ignore[invalid-argument-type]
+            )
+        assert "token_endpoint_auth_method" in str(exc_info.value)
+
+    def test_missing_redirect_uris_rejected(self):
+        """Test that redirect_uris is required for CIMD."""
+        with pytest.raises(ValidationError) as exc_info:
+            CIMDDocument(client_id=AnyHttpUrl("https://example.com/client.json"))
+        assert "redirect_uris" in str(exc_info.value)
+
+    def test_empty_redirect_uris_rejected(self):
+        """Test that empty redirect_uris is rejected."""
+        with pytest.raises(ValidationError) as exc_info:
+            CIMDDocument(
+                client_id=AnyHttpUrl("https://example.com/client.json"),
+                redirect_uris=[],
+            )
+        assert "redirect_uris" in str(exc_info.value)
+
+    def test_redirect_uri_without_scheme_rejected(self):
+        """Test that redirect_uris without a scheme are rejected."""
+        with pytest.raises(ValidationError, match="must have a scheme"):
+            CIMDDocument(
+                client_id=AnyHttpUrl("https://example.com/client.json"),
+                redirect_uris=["/just/a/path"],
+            )
+
+    def test_redirect_uri_without_host_rejected(self):
+        """Test that redirect_uris without a host are rejected."""
+        with pytest.raises(ValidationError, match="must have a host"):
+            CIMDDocument(
+                client_id=AnyHttpUrl("https://example.com/client.json"),
+                redirect_uris=["http://"],
+            )
+
+    def test_redirect_uri_whitespace_only_rejected(self):
+        """Test that whitespace-only redirect_uris are rejected."""
+        with pytest.raises(ValidationError, match="non-empty"):
+            CIMDDocument(
+                client_id=AnyHttpUrl("https://example.com/client.json"),
+                redirect_uris=["   "],
+            )
+
+
+class TestCIMDFetcher:
+    """Tests for CIMDFetcher."""
+
+    @pytest.fixture
+    def fetcher(self):
+        """Create a CIMDFetcher for testing."""
+        return CIMDFetcher()
+
+    def test_is_cimd_client_id_valid_urls(self, fetcher: CIMDFetcher):
+        """Test is_cimd_client_id accepts valid CIMD URLs."""
+        assert fetcher.is_cimd_client_id("https://example.com/client.json")
+        assert fetcher.is_cimd_client_id("https://example.com/path/to/client")
+        assert fetcher.is_cimd_client_id("https://sub.example.com/cimd.json")
+
+    def test_is_cimd_client_id_rejects_http(self, fetcher: CIMDFetcher):
+        """Test is_cimd_client_id rejects HTTP URLs."""
+        assert not fetcher.is_cimd_client_id("http://example.com/client.json")
+
+    def test_is_cimd_client_id_rejects_root_path(self, fetcher: CIMDFetcher):
+        """Test is_cimd_client_id rejects URLs with no path."""
+        assert not fetcher.is_cimd_client_id("https://example.com/")
+        assert not fetcher.is_cimd_client_id("https://example.com")
+
+    def test_is_cimd_client_id_rejects_non_url(self, fetcher: CIMDFetcher):
+        """Test is_cimd_client_id rejects non-URL strings."""
+        assert not fetcher.is_cimd_client_id("client-123")
+        assert not fetcher.is_cimd_client_id("my-client")
+        assert not fetcher.is_cimd_client_id("")
+        assert not fetcher.is_cimd_client_id("not a url")
+
+    def test_validate_redirect_uri_exact_match(self, fetcher: CIMDFetcher):
+        """Test redirect_uri validation with exact match."""
+        doc = CIMDDocument(
+            client_id=AnyHttpUrl("https://example.com/client.json"),
+            redirect_uris=["http://localhost:3000/callback"],
+        )
+        assert fetcher.validate_redirect_uri(doc, "http://localhost:3000/callback")
+        assert not fetcher.validate_redirect_uri(doc, "http://localhost:4000/callback")
+
+    def test_validate_redirect_uri_wildcard_match(self, fetcher: CIMDFetcher):
+        """Test redirect_uri validation with wildcard port."""
+        doc = CIMDDocument(
+            client_id=AnyHttpUrl("https://example.com/client.json"),
+            redirect_uris=["http://localhost:*/callback"],
+        )
+        assert fetcher.validate_redirect_uri(doc, "http://localhost:3000/callback")
+        assert fetcher.validate_redirect_uri(doc, "http://localhost:8080/callback")
+        assert not fetcher.validate_redirect_uri(doc, "http://localhost:3000/other")
+
+    def test_validate_redirect_uri_loopback_no_port(self, fetcher: CIMDFetcher):
+        """RFC 8252 §7.3: loopback URI without port should match any port."""
+        doc = CIMDDocument(
+            client_id=AnyHttpUrl("https://example.com/client.json"),
+            redirect_uris=["http://localhost/callback", "http://127.0.0.1/callback"],
+        )
+        assert fetcher.validate_redirect_uri(doc, "http://localhost:51353/callback")
+        assert fetcher.validate_redirect_uri(doc, "http://127.0.0.1:3000/callback")
+        assert not fetcher.validate_redirect_uri(doc, "http://localhost:51353/other")
+
+
+class TestCIMDFetcherHTTP:
+    """Tests for CIMDFetcher HTTP fetching (using httpx mock).
+
+    Note: With SSRF protection and DNS pinning, HTTP requests go to the resolved IP
+    instead of the hostname. These tests mock DNS resolution to return a public IP
+    and configure httpx_mock to expect the IP-based URL.
+    """
+
+    @pytest.fixture
+    def fetcher(self):
+        """Create a CIMDFetcher for testing."""
+        return CIMDFetcher()
+
+    @pytest.fixture
+    def mock_dns(self):
+        """Mock DNS resolution to return test public IP."""
+        with patch(
+            "fastmcp.server.auth.ssrf.resolve_hostname",
+            return_value=[TEST_PUBLIC_IP],
+        ):
+            yield
+
+    async def test_fetch_success(self, fetcher: CIMDFetcher, httpx_mock, mock_dns):
+        """Test successful CIMD document fetch."""
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "client_name": "Test App",
+            "redirect_uris": ["http://localhost:3000/callback"],
+            "token_endpoint_auth_method": "none",
+        }
+
+        # With DNS pinning, request goes to IP. Match any URL.
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={
+                "content-type": "application/json",
+                "content-length": "200",
+            },
+        )
+
+        doc = await fetcher.fetch(url)
+        assert str(doc.client_id) == url
+        assert doc.client_name == "Test App"
+
+    async def test_fetch_ttl_cache(self, fetcher: CIMDFetcher, httpx_mock, mock_dns):
+        """Test that fetched documents are cached and served from cache within TTL."""
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "client_name": "Test App",
+            "redirect_uris": ["http://localhost:3000/callback"],
+            "token_endpoint_auth_method": "none",
+        }
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={"content-length": "200"},
+        )
+
+        first = await fetcher.fetch(url)
+        second = await fetcher.fetch(url)
+
+        assert first.client_id == second.client_id
+        assert len(httpx_mock.get_requests()) == 1
+
+    async def test_fetch_cache_control_max_age(
+        self, fetcher: CIMDFetcher, httpx_mock, mock_dns
+    ):
+        """Cache-Control max-age should prevent refetch before expiry."""
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "client_name": "Max-Age App",
+            "redirect_uris": ["http://localhost:3000/callback"],
+            "token_endpoint_auth_method": "none",
+        }
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={"cache-control": "max-age=60", "content-length": "200"},
+        )
+
+        first = await fetcher.fetch(url)
+        second = await fetcher.fetch(url)
+
+        assert first.client_name == second.client_name
+        assert len(httpx_mock.get_requests()) == 1
+
+    async def test_fetch_etag_revalidation_304(
+        self, fetcher: CIMDFetcher, httpx_mock, mock_dns
+    ):
+        """Expired cache should revalidate with ETag and accept 304."""
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "client_name": "ETag App",
+            "redirect_uris": ["http://localhost:3000/callback"],
+            "token_endpoint_auth_method": "none",
+        }
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={
+                "cache-control": "max-age=0",
+                "etag": '"v1"',
+                "content-length": "200",
+            },
+        )
+        httpx_mock.add_response(
+            status_code=304,
+            headers={
+                "cache-control": "max-age=120",
+                "etag": '"v1"',
+                "content-length": "0",
+            },
+        )
+
+        first = await fetcher.fetch(url)
+        second = await fetcher.fetch(url)
+        requests = httpx_mock.get_requests()
+
+        assert first.client_name == "ETag App"
+        assert second.client_name == "ETag App"
+        assert len(requests) == 2
+        assert requests[1].headers.get("if-none-match") == '"v1"'
+
+    async def test_fetch_last_modified_revalidation_304(
+        self, fetcher: CIMDFetcher, httpx_mock, mock_dns
+    ):
+        """Expired cache should revalidate with Last-Modified and accept 304."""
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "client_name": "Last-Modified App",
+            "redirect_uris": ["http://localhost:3000/callback"],
+            "token_endpoint_auth_method": "none",
+        }
+        last_modified = "Wed, 21 Oct 2015 07:28:00 GMT"
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={
+                "cache-control": "max-age=0",
+                "last-modified": last_modified,
+                "content-length": "200",
+            },
+        )
+        httpx_mock.add_response(
+            status_code=304,
+            headers={"cache-control": "max-age=120", "content-length": "0"},
+        )
+
+        first = await fetcher.fetch(url)
+        second = await fetcher.fetch(url)
+        requests = httpx_mock.get_requests()
+
+        assert first.client_name == "Last-Modified App"
+        assert second.client_name == "Last-Modified App"
+        assert len(requests) == 2
+        assert requests[1].headers.get("if-modified-since") == last_modified
+
+    async def test_fetch_cache_control_no_store(
+        self, fetcher: CIMDFetcher, httpx_mock, mock_dns
+    ):
+        """Cache-Control no-store should prevent storing CIMD documents."""
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "client_name": "No-Store App",
+            "redirect_uris": ["http://localhost:3000/callback"],
+            "token_endpoint_auth_method": "none",
+        }
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={"cache-control": "no-store", "content-length": "200"},
+        )
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={"cache-control": "no-store", "content-length": "200"},
+        )
+
+        first = await fetcher.fetch(url)
+        second = await fetcher.fetch(url)
+
+        assert first.client_name == second.client_name
+        assert len(httpx_mock.get_requests()) == 2
+
+    async def test_fetch_cache_control_no_cache(
+        self, fetcher: CIMDFetcher, httpx_mock, mock_dns
+    ):
+        """Cache-Control no-cache should force revalidation on each fetch."""
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "client_name": "No-Cache App",
+            "redirect_uris": ["http://localhost:3000/callback"],
+            "token_endpoint_auth_method": "none",
+        }
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={
+                "cache-control": "no-cache",
+                "etag": '"v2"',
+                "content-length": "200",
+            },
+        )
+        httpx_mock.add_response(
+            status_code=304,
+            headers={
+                "cache-control": "no-cache",
+                "etag": '"v2"',
+                "content-length": "0",
+            },
+        )
+
+        first = await fetcher.fetch(url)
+        second = await fetcher.fetch(url)
+        requests = httpx_mock.get_requests()
+
+        assert first.client_name == "No-Cache App"
+        assert second.client_name == "No-Cache App"
+        assert len(requests) == 2
+        assert requests[1].headers.get("if-none-match") == '"v2"'
+
+    async def test_fetch_304_without_cache_headers_preserves_policy(
+        self, fetcher: CIMDFetcher, httpx_mock, mock_dns
+    ):
+        """304 responses without cache headers should not reset cached policy."""
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "client_name": "No-Header-304 App",
+            "redirect_uris": ["http://localhost:3000/callback"],
+            "token_endpoint_auth_method": "none",
+        }
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={
+                "cache-control": "no-cache",
+                "etag": '"v3"',
+                "content-length": "200",
+            },
+        )
+        # Intentionally omit cache-control/expires on 304.
+        httpx_mock.add_response(
+            status_code=304,
+            headers={"content-length": "0"},
+        )
+        httpx_mock.add_response(
+            status_code=304,
+            headers={"content-length": "0"},
+        )
+
+        first = await fetcher.fetch(url)
+        second = await fetcher.fetch(url)
+        third = await fetcher.fetch(url)
+        requests = httpx_mock.get_requests()
+
+        assert first.client_name == "No-Header-304 App"
+        assert second.client_name == "No-Header-304 App"
+        assert third.client_name == "No-Header-304 App"
+        assert len(requests) == 3
+        assert requests[1].headers.get("if-none-match") == '"v3"'
+        assert requests[2].headers.get("if-none-match") == '"v3"'
+
+    async def test_fetch_304_without_cache_headers_refreshes_cached_freshness(
+        self, fetcher: CIMDFetcher, httpx_mock, mock_dns
+    ):
+        """A header-less 304 should renew freshness using cached lifetime."""
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "client_name": "Headerless 304 Freshness App",
+            "redirect_uris": ["http://localhost:3000/callback"],
+            "token_endpoint_auth_method": "none",
+        }
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={
+                "cache-control": "max-age=60",
+                "etag": '"v4"',
+                "content-length": "200",
+            },
+        )
+        httpx_mock.add_response(
+            status_code=304,
+            headers={"content-length": "0"},
+        )
+
+        first = await fetcher.fetch(url)
+
+        # Simulate cache expiry so the next request triggers revalidation.
+        cached_entry = fetcher._cache[url]
+        cached_entry.expires_at = time.time() - 1
+
+        second = await fetcher.fetch(url)
+        third = await fetcher.fetch(url)
+        requests = httpx_mock.get_requests()
+
+        assert first.client_name == "Headerless 304 Freshness App"
+        assert second.client_name == "Headerless 304 Freshness App"
+        assert third.client_name == "Headerless 304 Freshness App"
+        assert len(requests) == 2
+        assert requests[1].headers.get("if-none-match") == '"v4"'
+
+    async def test_fetch_client_id_mismatch(
+        self, fetcher: CIMDFetcher, httpx_mock, mock_dns
+    ):
+        """Test that client_id mismatch is rejected."""
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": "https://other.com/client.json",  # Different URL
+            "client_name": "Test App",
+            "redirect_uris": ["http://localhost:3000/callback"],
+        }
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={"content-length": "100"},
+        )
+
+        with pytest.raises(CIMDValidationError) as exc_info:
+            await fetcher.fetch(url)
+        assert "mismatch" in str(exc_info.value).lower()
+
+    async def test_fetch_http_error(self, fetcher: CIMDFetcher, httpx_mock, mock_dns):
+        """Test handling of HTTP errors."""
+        url = "https://example.com/client.json"
+        httpx_mock.add_response(status_code=404)
+
+        with pytest.raises(CIMDFetchError) as exc_info:
+            await fetcher.fetch(url)
+        assert "404" in str(exc_info.value)
+
+    async def test_fetch_invalid_json(self, fetcher: CIMDFetcher, httpx_mock, mock_dns):
+        """Test handling of invalid JSON response."""
+        url = "https://example.com/client.json"
+        httpx_mock.add_response(
+            content=b"not json",
+            headers={"content-length": "10"},
+        )
+
+        with pytest.raises(CIMDValidationError) as exc_info:
+            await fetcher.fetch(url)
+        assert "JSON" in str(exc_info.value)
+
+    async def test_fetch_invalid_document(
+        self, fetcher: CIMDFetcher, httpx_mock, mock_dns
+    ):
+        """Test handling of invalid CIMD document."""
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "redirect_uris": ["http://localhost:3000/callback"],
+            "token_endpoint_auth_method": "client_secret_basic",  # Not allowed
+        }
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={"content-length": "100"},
+        )
+
+        with pytest.raises(CIMDValidationError) as exc_info:
+            await fetcher.fetch(url)
+        assert "Invalid CIMD document" in str(exc_info.value)
diff --git a/tests/server/auth/test_cimd_validators.py b/tests/server/auth/test_cimd_validators.py
new file mode 100644
index 0000000..995854b
--- /dev/null
+++ b/tests/server/auth/test_cimd_validators.py
@@ -0,0 +1,682 @@
+"""Unit tests for CIMD assertion validators, client manager, and redirect URI enforcement."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from pydantic import AnyHttpUrl
+
+from fastmcp.server.auth.cimd import (
+    CIMDAssertionValidator,
+    CIMDClientManager,
+    CIMDDocument,
+)
+from fastmcp.server.auth.oauth_proxy.models import ProxyDCRClient
+
+# Standard public IP used for DNS mocking in tests
+TEST_PUBLIC_IP = "93.184.216.34"
+
+
+class TestCIMDAssertionValidator:
+    """Tests for CIMDAssertionValidator (private_key_jwt support)."""
+
+    @pytest.fixture
+    def validator(self):
+        """Create a CIMDAssertionValidator for testing."""
+        return CIMDAssertionValidator()
+
+    @pytest.fixture
+    def key_pair(self):
+        """Generate RSA key pair for testing."""
+        from fastmcp.server.auth.providers.jwt import RSAKeyPair
+
+        return RSAKeyPair.generate()
+
+    @pytest.fixture
+    def jwks(self, key_pair):
+        """Create JWKS from key pair."""
+        import base64
+
+        from cryptography.hazmat.backends import default_backend
+        from cryptography.hazmat.primitives import serialization
+
+        # Load public key
+        public_key = serialization.load_pem_public_key(
+            key_pair.public_key.encode(), backend=default_backend()
+        )
+
+        # Get RSA public numbers
+        from cryptography.hazmat.primitives.asymmetric import rsa
+
+        if isinstance(public_key, rsa.RSAPublicKey):
+            numbers = public_key.public_numbers()
+
+            # Convert to JWK format
+            return {
+                "keys": [
+                    {
+                        "kty": "RSA",
+                        "kid": "test-key-1",
+                        "use": "sig",
+                        "alg": "RS256",
+                        "n": base64.urlsafe_b64encode(
+                            numbers.n.to_bytes((numbers.n.bit_length() + 7) // 8, "big")
+                        )
+                        .rstrip(b"=")
+                        .decode(),
+                        "e": base64.urlsafe_b64encode(
+                            numbers.e.to_bytes((numbers.e.bit_length() + 7) // 8, "big")
+                        )
+                        .rstrip(b"=")
+                        .decode(),
+                    }
+                ]
+            }
+
+    @pytest.fixture
+    def cimd_doc_with_jwks_uri(self):
+        """Create CIMD document with jwks_uri."""
+        return CIMDDocument(
+            client_id=AnyHttpUrl("https://example.com/client.json"),
+            redirect_uris=["http://localhost:3000/callback"],
+            token_endpoint_auth_method="private_key_jwt",
+            jwks_uri=AnyHttpUrl("https://example.com/.well-known/jwks.json"),
+        )
+
+    @pytest.fixture
+    def cimd_doc_with_inline_jwks(self, jwks):
+        """Create CIMD document with inline JWKS."""
+        return CIMDDocument(
+            client_id=AnyHttpUrl("https://example.com/client.json"),
+            redirect_uris=["http://localhost:3000/callback"],
+            token_endpoint_auth_method="private_key_jwt",
+            jwks=jwks,
+        )
+
+    async def test_valid_assertion_with_jwks_uri(
+        self, validator, key_pair, cimd_doc_with_jwks_uri, httpx_mock
+    ):
+        """Test that valid JWT assertion passes validation (jwks_uri)."""
+        client_id = "https://example.com/client.json"
+        token_endpoint = "https://oauth.example.com/token"
+
+        # Mock JWKS endpoint
+        import base64
+
+        from cryptography.hazmat.backends import default_backend
+        from cryptography.hazmat.primitives import serialization
+
+        public_key = serialization.load_pem_public_key(
+            key_pair.public_key.encode(), backend=default_backend()
+        )
+        from cryptography.hazmat.primitives.asymmetric import rsa
+
+        assert isinstance(public_key, rsa.RSAPublicKey)
+        numbers = public_key.public_numbers()
+
+        jwks = {
+            "keys": [
+                {
+                    "kty": "RSA",
+                    "kid": "test-key-1",
+                    "use": "sig",
+                    "alg": "RS256",
+                    "n": base64.urlsafe_b64encode(
+                        numbers.n.to_bytes((numbers.n.bit_length() + 7) // 8, "big")
+                    )
+                    .rstrip(b"=")
+                    .decode(),
+                    "e": base64.urlsafe_b64encode(
+                        numbers.e.to_bytes((numbers.e.bit_length() + 7) // 8, "big")
+                    )
+                    .rstrip(b"=")
+                    .decode(),
+                }
+            ]
+        }
+
+        # Mock DNS resolution for SSRF-safe fetch
+        with patch(
+            "fastmcp.server.auth.ssrf.resolve_hostname",
+            return_value=[TEST_PUBLIC_IP],
+        ):
+            httpx_mock.add_response(json=jwks)
+
+            # Create valid assertion (use short lifetime for security compliance)
+            assertion = key_pair.create_token(
+                subject=client_id,
+                issuer=client_id,
+                audience=token_endpoint,
+                additional_claims={"jti": "unique-jti-123"},
+                expires_in_seconds=60,  # 1 minute (max allowed is 300s)
+                kid="test-key-1",
+            )
+
+            # Should validate successfully
+            assert await validator.validate_assertion(
+                assertion, client_id, token_endpoint, cimd_doc_with_jwks_uri
+            )
+
+    async def test_valid_assertion_with_inline_jwks(
+        self, validator, key_pair, cimd_doc_with_inline_jwks
+    ):
+        """Test that valid JWT assertion passes validation (inline JWKS)."""
+        client_id = "https://example.com/client.json"
+        token_endpoint = "https://oauth.example.com/token"
+
+        # Create valid assertion (use short lifetime for security compliance)
+        assertion = key_pair.create_token(
+            subject=client_id,
+            issuer=client_id,
+            audience=token_endpoint,
+            additional_claims={"jti": "unique-jti-456"},
+            expires_in_seconds=60,  # 1 minute (max allowed is 300s)
+            kid="test-key-1",
+        )
+
+        # Should validate successfully
+        assert await validator.validate_assertion(
+            assertion, client_id, token_endpoint, cimd_doc_with_inline_jwks
+        )
+
+    async def test_rejects_wrong_issuer(
+        self, validator, key_pair, cimd_doc_with_inline_jwks
+    ):
+        """Test that wrong issuer is rejected."""
+        client_id = "https://example.com/client.json"
+        token_endpoint = "https://oauth.example.com/token"
+
+        # Create assertion with wrong issuer
+        assertion = key_pair.create_token(
+            subject=client_id,
+            issuer="https://attacker.com",  # Wrong!
+            audience=token_endpoint,
+            additional_claims={"jti": "unique-jti-789"},
+            expires_in_seconds=60,
+            kid="test-key-1",
+        )
+
+        with pytest.raises(ValueError) as exc_info:
+            await validator.validate_assertion(
+                assertion, client_id, token_endpoint, cimd_doc_with_inline_jwks
+            )
+        assert "Invalid JWT assertion" in str(exc_info.value)
+
+    async def test_rejects_wrong_audience(
+        self, validator, key_pair, cimd_doc_with_inline_jwks
+    ):
+        """Test that wrong audience is rejected."""
+        client_id = "https://example.com/client.json"
+        token_endpoint = "https://oauth.example.com/token"
+
+        # Create assertion with wrong audience
+        assertion = key_pair.create_token(
+            subject=client_id,
+            issuer=client_id,
+            audience="https://wrong-endpoint.com/token",  # Wrong!
+            additional_claims={"jti": "unique-jti-abc"},
+            expires_in_seconds=60,
+            kid="test-key-1",
+        )
+
+        with pytest.raises(ValueError) as exc_info:
+            await validator.validate_assertion(
+                assertion, client_id, token_endpoint, cimd_doc_with_inline_jwks
+            )
+        assert "Invalid JWT assertion" in str(exc_info.value)
+
+    async def test_rejects_wrong_subject(
+        self, validator, key_pair, cimd_doc_with_inline_jwks
+    ):
+        """Test that wrong subject claim is rejected."""
+        client_id = "https://example.com/client.json"
+        token_endpoint = "https://oauth.example.com/token"
+
+        # Create assertion with wrong subject
+        assertion = key_pair.create_token(
+            subject="https://different-client.com",  # Wrong!
+            issuer=client_id,
+            audience=token_endpoint,
+            additional_claims={"jti": "unique-jti-def"},
+            expires_in_seconds=60,
+            kid="test-key-1",
+        )
+
+        with pytest.raises(ValueError) as exc_info:
+            await validator.validate_assertion(
+                assertion, client_id, token_endpoint, cimd_doc_with_inline_jwks
+            )
+        assert "sub claim must be" in str(exc_info.value)
+
+    async def test_rejects_missing_jti(
+        self, validator, key_pair, cimd_doc_with_inline_jwks
+    ):
+        """Test that missing jti claim is rejected."""
+        client_id = "https://example.com/client.json"
+        token_endpoint = "https://oauth.example.com/token"
+
+        # Create assertion without jti
+        assertion = key_pair.create_token(
+            subject=client_id,
+            issuer=client_id,
+            audience=token_endpoint,
+            # No jti!
+            expires_in_seconds=60,
+            kid="test-key-1",
+        )
+
+        with pytest.raises(ValueError) as exc_info:
+            await validator.validate_assertion(
+                assertion, client_id, token_endpoint, cimd_doc_with_inline_jwks
+            )
+        assert "jti claim" in str(exc_info.value)
+
+    async def test_rejects_replayed_jti(
+        self, validator, key_pair, cimd_doc_with_inline_jwks
+    ):
+        """Test that replayed JTI is detected and rejected."""
+        client_id = "https://example.com/client.json"
+        token_endpoint = "https://oauth.example.com/token"
+
+        # Create assertion
+        assertion = key_pair.create_token(
+            subject=client_id,
+            issuer=client_id,
+            audience=token_endpoint,
+            additional_claims={"jti": "replayed-jti"},
+            expires_in_seconds=60,
+            kid="test-key-1",
+        )
+
+        # First use should succeed
+        assert await validator.validate_assertion(
+            assertion, client_id, token_endpoint, cimd_doc_with_inline_jwks
+        )
+
+        # Second use with same jti should fail (replay attack)
+        with pytest.raises(ValueError) as exc_info:
+            await validator.validate_assertion(
+                assertion, client_id, token_endpoint, cimd_doc_with_inline_jwks
+            )
+        assert "replay" in str(exc_info.value).lower()
+
+    async def test_rejects_expired_token(
+        self, validator, key_pair, cimd_doc_with_inline_jwks
+    ):
+        """Test that expired tokens are rejected."""
+        client_id = "https://example.com/client.json"
+        token_endpoint = "https://oauth.example.com/token"
+
+        # Create expired assertion (expired 1 hour ago)
+        assertion = key_pair.create_token(
+            subject=client_id,
+            issuer=client_id,
+            audience=token_endpoint,
+            additional_claims={"jti": "expired-jti"},
+            expires_in_seconds=-3600,  # Negative = expired
+            kid="test-key-1",
+        )
+
+        with pytest.raises(ValueError) as exc_info:
+            await validator.validate_assertion(
+                assertion, client_id, token_endpoint, cimd_doc_with_inline_jwks
+            )
+        assert "Invalid JWT assertion" in str(exc_info.value)
+
+
+class TestCIMDClientManager:
+    """Tests for CIMDClientManager."""
+
+    @pytest.fixture
+    def manager(self):
+        """Create a CIMDClientManager for testing."""
+        return CIMDClientManager(enable_cimd=True)
+
+    @pytest.fixture
+    def disabled_manager(self):
+        """Create a disabled CIMDClientManager for testing."""
+        return CIMDClientManager(enable_cimd=False)
+
+    @pytest.fixture
+    def mock_dns(self):
+        """Mock DNS resolution to return test public IP."""
+        with patch(
+            "fastmcp.server.auth.ssrf.resolve_hostname",
+            return_value=[TEST_PUBLIC_IP],
+        ):
+            yield
+
+    def test_is_cimd_client_id_enabled(self, manager):
+        """Test CIMD URL detection when enabled."""
+        assert manager.is_cimd_client_id("https://example.com/client.json")
+        assert not manager.is_cimd_client_id("regular-client-id")
+
+    def test_is_cimd_client_id_disabled(self, disabled_manager):
+        """Test CIMD URL detection when disabled."""
+        assert not disabled_manager.is_cimd_client_id("https://example.com/client.json")
+        assert not disabled_manager.is_cimd_client_id("regular-client-id")
+
+    async def test_get_client_success(self, manager, httpx_mock, mock_dns):
+        """Test successful CIMD client creation."""
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "client_name": "Test App",
+            "redirect_uris": ["http://localhost:3000/callback"],
+            "token_endpoint_auth_method": "none",
+        }
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={"content-length": "200"},
+        )
+
+        client = await manager.get_client(url)
+        assert client is not None
+        assert client.client_id == url
+        assert client.client_name == "Test App"
+        # Verify it uses proxy's patterns (None by default), not document's redirect_uris
+        assert client.allowed_redirect_uri_patterns is None
+
+    async def test_get_client_disabled(self, disabled_manager):
+        """Test that get_client returns None when disabled."""
+        client = await disabled_manager.get_client("https://example.com/client.json")
+        assert client is None
+
+    async def test_get_client_fetch_failure(self, manager, httpx_mock, mock_dns):
+        """Test that get_client returns None on fetch failure."""
+        url = "https://example.com/client.json"
+        httpx_mock.add_response(status_code=404)
+
+        client = await manager.get_client(url)
+        assert client is None
+
+    # Trust policy and consent bypass tests removed - functionality removed from CIMD
+
+
+class TestCIMDClientManagerGetClientOptions:
+    """Tests for CIMDClientManager.get_client with default_scope and allowed patterns."""
+
+    @pytest.fixture
+    def mock_dns(self):
+        """Mock DNS resolution to return test public IP."""
+        with patch(
+            "fastmcp.server.auth.ssrf.resolve_hostname",
+            return_value=[TEST_PUBLIC_IP],
+        ):
+            yield
+
+    async def test_default_scope_applied_when_doc_has_no_scope(
+        self, httpx_mock, mock_dns
+    ):
+        """When the CIMD document omits scope, the manager's default_scope is used."""
+
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "client_name": "Test App",
+            "redirect_uris": ["http://localhost:3000/callback"],
+            "token_endpoint_auth_method": "none",
+            # No scope field
+        }
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={"content-length": "200"},
+        )
+
+        manager = CIMDClientManager(
+            enable_cimd=True,
+            default_scope="read write admin",
+        )
+        client = await manager.get_client(url)
+        assert client is not None
+        assert client.scope == "read write admin"
+
+    async def test_doc_scope_takes_precedence_over_default(self, httpx_mock, mock_dns):
+        """When the CIMD document specifies scope, it wins over the default."""
+
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "client_name": "Test App",
+            "redirect_uris": ["http://localhost:3000/callback"],
+            "token_endpoint_auth_method": "none",
+            "scope": "custom-scope",
+        }
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={"content-length": "200"},
+        )
+
+        manager = CIMDClientManager(
+            enable_cimd=True,
+            default_scope="default-scope",
+        )
+        client = await manager.get_client(url)
+        assert client is not None
+        assert client.scope == "custom-scope"
+
+    async def test_allowed_redirect_uri_patterns_stored_on_client(
+        self, httpx_mock, mock_dns
+    ):
+        """Proxy's allowed_redirect_uri_patterns are forwarded to the created client."""
+
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "client_name": "Test App",
+            "redirect_uris": ["http://localhost:*/callback"],
+            "token_endpoint_auth_method": "none",
+        }
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={"content-length": "200"},
+        )
+
+        patterns = ["http://localhost:*", "https://app.example.com/*"]
+        manager = CIMDClientManager(
+            enable_cimd=True,
+            allowed_redirect_uri_patterns=patterns,
+        )
+        client = await manager.get_client(url)
+        assert client is not None
+        assert client.allowed_redirect_uri_patterns == patterns
+
+    async def test_cimd_document_attached_to_client(self, httpx_mock, mock_dns):
+        """The fetched CIMDDocument is attached to the created client."""
+
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "client_name": "Attached Doc App",
+            "redirect_uris": ["http://localhost:3000/callback"],
+            "token_endpoint_auth_method": "none",
+        }
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={"content-length": "200"},
+        )
+
+        manager = CIMDClientManager(enable_cimd=True)
+        client = await manager.get_client(url)
+        assert client is not None
+        assert client.cimd_document is not None
+        assert client.cimd_document.client_name == "Attached Doc App"
+        assert str(client.cimd_document.client_id) == url
+
+
+class TestCIMDClientManagerValidatePrivateKeyJwt:
+    """Tests for CIMDClientManager.validate_private_key_jwt wrapper."""
+
+    @pytest.fixture
+    def manager(self):
+        return CIMDClientManager(enable_cimd=True)
+
+    async def test_missing_cimd_document_raises(self, manager):
+        """validate_private_key_jwt raises ValueError if client has no cimd_document."""
+
+        client = ProxyDCRClient(
+            client_id="https://example.com/client.json",
+            client_secret=None,
+            redirect_uris=None,
+            cimd_document=None,
+        )
+        with pytest.raises(ValueError, match="must have CIMD document"):
+            await manager.validate_private_key_jwt(
+                "fake.jwt.token",
+                client,
+                "https://oauth.example.com/token",
+            )
+
+    async def test_wrong_auth_method_raises(self, manager):
+        """validate_private_key_jwt raises ValueError if auth method is not private_key_jwt."""
+
+        cimd_doc = CIMDDocument(
+            client_id=AnyHttpUrl("https://example.com/client.json"),
+            redirect_uris=["http://localhost:3000/callback"],
+            token_endpoint_auth_method="none",  # Not private_key_jwt
+        )
+        client = ProxyDCRClient(
+            client_id="https://example.com/client.json",
+            client_secret=None,
+            redirect_uris=None,
+            cimd_document=cimd_doc,
+        )
+        with pytest.raises(ValueError, match="private_key_jwt"):
+            await manager.validate_private_key_jwt(
+                "fake.jwt.token",
+                client,
+                "https://oauth.example.com/token",
+            )
+
+    async def test_success_delegates_to_assertion_validator(self, manager):
+        """On success, validate_private_key_jwt delegates to the assertion validator."""
+
+        cimd_doc = CIMDDocument(
+            client_id=AnyHttpUrl("https://example.com/client.json"),
+            redirect_uris=["http://localhost:3000/callback"],
+            token_endpoint_auth_method="private_key_jwt",
+            jwks_uri=AnyHttpUrl("https://example.com/.well-known/jwks.json"),
+        )
+        client = ProxyDCRClient(
+            client_id="https://example.com/client.json",
+            client_secret=None,
+            redirect_uris=None,
+            cimd_document=cimd_doc,
+        )
+
+        manager._assertion_validator.validate_assertion = AsyncMock(return_value=True)
+
+        result = await manager.validate_private_key_jwt(
+            "test.jwt.assertion",
+            client,
+            "https://oauth.example.com/token",
+        )
+        assert result is True
+        manager._assertion_validator.validate_assertion.assert_awaited_once_with(
+            "test.jwt.assertion",
+            "https://example.com/client.json",
+            "https://oauth.example.com/token",
+            cimd_doc,
+        )
+
+
+class TestCIMDRedirectUriEnforcement:
+    """Tests for CIMD redirect_uri validation security.
+
+    Verifies that CIMD clients enforce BOTH:
+    1. CIMD document's redirect_uris
+    2. Proxy's allowed_redirect_uri_patterns
+    """
+
+    @pytest.fixture
+    def mock_dns(self):
+        """Mock DNS resolution to return test public IP."""
+        with patch(
+            "fastmcp.server.auth.ssrf.resolve_hostname",
+            return_value=[TEST_PUBLIC_IP],
+        ):
+            yield
+
+    async def test_cimd_redirect_uris_enforced(self, httpx_mock, mock_dns):
+        """Test that CIMD document redirect_uris are enforced.
+
+        Even if proxy patterns allow http://localhost:*, a CIMD client
+        should only accept URIs declared in its document.
+        """
+        from mcp.shared.auth import InvalidRedirectUriError
+        from pydantic import AnyUrl
+
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "client_name": "Test App",
+            # CIMD only declares port 3000
+            "redirect_uris": ["http://localhost:3000/callback"],
+            "token_endpoint_auth_method": "none",
+        }
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={"content-length": "200"},
+        )
+
+        # Proxy allows any localhost port
+        manager = CIMDClientManager(
+            enable_cimd=True,
+            allowed_redirect_uri_patterns=["http://localhost:*"],
+        )
+        client = await manager.get_client(url)
+        assert client is not None
+
+        # Declared URI should work
+        validated = client.validate_redirect_uri(
+            AnyUrl("http://localhost:3000/callback")
+        )
+        assert str(validated) == "http://localhost:3000/callback"
+
+        # Different port should fail (not in CIMD redirect_uris)
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("http://localhost:4000/callback"))
+
+    async def test_proxy_patterns_also_checked(self, httpx_mock, mock_dns):
+        """Test that proxy patterns are checked even for CIMD clients.
+
+        A CIMD client should not be able to use a redirect_uri that's
+        in its document but not allowed by proxy patterns.
+        """
+        from mcp.shared.auth import InvalidRedirectUriError
+        from pydantic import AnyUrl
+
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "client_name": "Test App",
+            # CIMD declares both localhost and external URI
+            "redirect_uris": [
+                "http://localhost:3000/callback",
+                "https://evil.com/callback",
+            ],
+            "token_endpoint_auth_method": "none",
+        }
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={"content-length": "200"},
+        )
+
+        # Proxy only allows localhost
+        manager = CIMDClientManager(
+            enable_cimd=True,
+            allowed_redirect_uri_patterns=["http://localhost:*"],
+        )
+        client = await manager.get_client(url)
+        assert client is not None
+
+        # Localhost should work (in CIMD and matches pattern)
+        validated = client.validate_redirect_uri(
+            AnyUrl("http://localhost:3000/callback")
+        )
+        assert str(validated) == "http://localhost:3000/callback"
+
+        # Evil.com should fail (in CIMD but doesn't match proxy patterns)
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("https://evil.com/callback"))
diff --git a/tests/server/auth/test_debug_verifier.py b/tests/server/auth/test_debug_verifier.py
new file mode 100644
index 0000000..4cf2c6e
--- /dev/null
+++ b/tests/server/auth/test_debug_verifier.py
@@ -0,0 +1,169 @@
+"""Unit tests for DebugTokenVerifier."""
+
+import re
+
+from fastmcp.server.auth.providers.debug import DebugTokenVerifier
+
+
+class TestDebugTokenVerifier:
+    """Test DebugTokenVerifier initialization and validation."""
+
+    def test_init_defaults(self):
+        """Test initialization with default parameters."""
+        verifier = DebugTokenVerifier()
+
+        assert verifier.client_id == "debug-client"
+        assert verifier.scopes == []
+        assert verifier.required_scopes == []
+        assert callable(verifier.validate)
+
+    def test_init_custom_parameters(self):
+        """Test initialization with custom parameters."""
+        verifier = DebugTokenVerifier(
+            validate=lambda t: t.startswith("valid-"),
+            client_id="custom-client",
+            scopes=["read", "write"],
+            required_scopes=["admin"],
+        )
+
+        assert verifier.client_id == "custom-client"
+        assert verifier.scopes == ["read", "write"]
+        assert verifier.required_scopes == ["admin"]
+
+    async def test_verify_token_default_accepts_all(self):
+        """Test that default verifier accepts all non-empty tokens."""
+        verifier = DebugTokenVerifier()
+
+        result = await verifier.verify_token("any-token")
+
+        assert result is not None
+        assert result.token == "any-token"
+        assert result.client_id == "debug-client"
+        assert result.scopes == []
+        assert result.expires_at is None
+        assert result.claims == {"token": "any-token"}
+
+    async def test_verify_token_rejects_empty(self):
+        """Test that empty tokens are rejected even with default verifier."""
+        verifier = DebugTokenVerifier()
+
+        # Empty string
+        assert await verifier.verify_token("") is None
+
+        # Whitespace only
+        assert await verifier.verify_token("   ") is None
+
+    async def test_verify_token_sync_callable_success(self):
+        """Test token verification with custom sync callable that passes."""
+        verifier = DebugTokenVerifier(
+            validate=lambda t: t.startswith("valid-"),
+            client_id="test-client",
+            scopes=["read"],
+        )
+
+        result = await verifier.verify_token("valid-token-123")
+
+        assert result is not None
+        assert result.token == "valid-token-123"
+        assert result.client_id == "test-client"
+        assert result.scopes == ["read"]
+        assert result.expires_at is None
+        assert result.claims == {"token": "valid-token-123"}
+
+    async def test_verify_token_sync_callable_failure(self):
+        """Test token verification with custom sync callable that fails."""
+        verifier = DebugTokenVerifier(validate=lambda t: t.startswith("valid-"))
+
+        result = await verifier.verify_token("invalid-token")
+
+        assert result is None
+
+    async def test_verify_token_async_callable_success(self):
+        """Test token verification with custom async callable that passes."""
+
+        async def async_validator(token: str) -> bool:
+            # Simulate async operation (e.g., database check)
+            return token in {"token1", "token2", "token3"}
+
+        verifier = DebugTokenVerifier(
+            validate=async_validator,
+            client_id="async-client",
+            scopes=["admin"],
+        )
+
+        result = await verifier.verify_token("token2")
+
+        assert result is not None
+        assert result.token == "token2"
+        assert result.client_id == "async-client"
+        assert result.scopes == ["admin"]
+
+    async def test_verify_token_async_callable_failure(self):
+        """Test token verification with custom async callable that fails."""
+
+        async def async_validator(token: str) -> bool:
+            return token in {"token1", "token2", "token3"}
+
+        verifier = DebugTokenVerifier(validate=async_validator)
+
+        result = await verifier.verify_token("token99")
+
+        assert result is None
+
+    async def test_verify_token_callable_exception(self):
+        """Test that exceptions in validate callable are handled gracefully."""
+
+        def failing_validator(token: str) -> bool:
+            raise ValueError("Something went wrong")
+
+        verifier = DebugTokenVerifier(validate=failing_validator)
+
+        result = await verifier.verify_token("any-token")
+
+        assert result is None
+
+    async def test_verify_token_async_callable_exception(self):
+        """Test that exceptions in async validate callable are handled gracefully."""
+
+        async def failing_async_validator(token: str) -> bool:
+            raise ValueError("Async validation failed")
+
+        verifier = DebugTokenVerifier(validate=failing_async_validator)
+
+        result = await verifier.verify_token("any-token")
+
+        assert result is None
+
+    async def test_verify_token_whitelist_pattern(self):
+        """Test using verifier with a whitelist of allowed tokens."""
+        allowed_tokens = {"secret-token-1", "secret-token-2", "admin-token"}
+
+        verifier = DebugTokenVerifier(validate=lambda t: t in allowed_tokens)
+
+        # Allowed tokens
+        assert await verifier.verify_token("secret-token-1") is not None
+        assert await verifier.verify_token("admin-token") is not None
+
+        # Disallowed tokens
+        assert await verifier.verify_token("unknown-token") is None
+        assert await verifier.verify_token("hacker-token") is None
+
+    async def test_verify_token_pattern_matching(self):
+        """Test using verifier with regex-like pattern matching."""
+
+        pattern = re.compile(r"^[A-Z]{3}-\d{4}-[a-z]{2}$")
+
+        verifier = DebugTokenVerifier(
+            validate=lambda t: bool(pattern.match(t)),
+            client_id="pattern-client",
+        )
+
+        # Valid patterns
+        result = await verifier.verify_token("ABC-1234-xy")
+        assert result is not None
+        assert result.client_id == "pattern-client"
+
+        # Invalid patterns
+        assert await verifier.verify_token("abc-1234-xy") is None  # Wrong case
+        assert await verifier.verify_token("ABC-123-xy") is None  # Wrong digits
+        assert await verifier.verify_token("ABC-1234-xyz") is None  # Too many chars
diff --git a/tests/server/auth/test_enhanced_error_responses.py b/tests/server/auth/test_enhanced_error_responses.py
new file mode 100644
index 0000000..4d7a2ac
--- /dev/null
+++ b/tests/server/auth/test_enhanced_error_responses.py
@@ -0,0 +1,403 @@
+"""Tests for enhanced OAuth error responses.
+
+This test suite covers:
+1. Enhanced authorization handler (HTML and JSON error pages)
+2. Enhanced middleware (better error messages)
+3. Content negotiation
+4. Server branding in error pages
+"""
+
+import pytest
+from mcp.shared.auth import OAuthClientInformationFull
+from pydantic import AnyUrl
+from starlette.applications import Starlette
+from starlette.testclient import TestClient
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.server.auth.providers.jwt import JWTVerifier, RSAKeyPair
+
+
+class TestEnhancedAuthorizationHandler:
+    """Tests for enhanced authorization handler error responses."""
+
+    @pytest.fixture
+    def rsa_key_pair(self) -> RSAKeyPair:
+        """Generate RSA key pair for testing."""
+        return RSAKeyPair.generate()
+
+    @pytest.fixture
+    def oauth_proxy(self, rsa_key_pair):
+        """Create OAuth proxy for testing."""
+        from key_value.aio.stores.memory import MemoryStore
+
+        return OAuthProxy(
+            upstream_authorization_endpoint="https://github.com/login/oauth/authorize",
+            upstream_token_endpoint="https://github.com/login/oauth/access_token",
+            upstream_client_id="test-client-id",
+            upstream_client_secret="test-client-secret",
+            token_verifier=JWTVerifier(
+                public_key=rsa_key_pair.public_key,
+                issuer="https://test.com",
+                audience="https://test.com",
+                base_url="https://test.com",
+            ),
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+    def test_unregistered_client_returns_html_for_browser(self, oauth_proxy):
+        """Test that unregistered client returns styled HTML for browser requests."""
+        app = Starlette(routes=oauth_proxy.get_routes())
+
+        with TestClient(app) as client:
+            response = client.get(
+                "/authorize",
+                params={
+                    "client_id": "unregistered-client-id",
+                    "redirect_uri": "http://localhost:12345/callback",
+                    "response_type": "code",
+                    "code_challenge": "test-challenge",
+                    "state": "test-state",
+                },
+                headers={"Accept": "text/html"},
+            )
+
+            # Should return 400 with HTML content
+            assert response.status_code == 400
+            assert "text/html" in response.headers["content-type"]
+
+            # HTML should contain error message
+            html = response.text
+            assert "Client Not Registered" in html
+            assert "unregistered-client-id" in html
+            assert "To fix this" in html
+            assert "Close this browser window" in html
+            assert "Clear authentication tokens" in html
+
+            # Should have Link header for registration endpoint
+            assert "Link" in response.headers
+            assert "/register" in response.headers["Link"]
+
+    def test_unregistered_client_returns_json_for_api(self, oauth_proxy):
+        """Test that unregistered client returns enhanced JSON for API clients."""
+        app = Starlette(routes=oauth_proxy.get_routes())
+
+        with TestClient(app) as client:
+            response = client.get(
+                "/authorize",
+                params={
+                    "client_id": "unregistered-client-id",
+                    "redirect_uri": "http://localhost:12345/callback",
+                    "response_type": "code",
+                    "code_challenge": "test-challenge",
+                    "state": "test-state",
+                },
+                headers={"Accept": "application/json"},
+            )
+
+            # Should return 400 with JSON content
+            assert response.status_code == 400
+            assert "application/json" in response.headers["content-type"]
+
+            # JSON should have enhanced error response
+            data = response.json()
+            assert data["error"] == "invalid_request"
+            assert "unregistered-client-id" in data["error_description"]
+            assert data["state"] == "test-state"
+
+            # Should include registration endpoint hints
+            assert "registration_endpoint" in data
+            assert data["registration_endpoint"] == "https://myserver.com/register"
+            assert "authorization_server_metadata" in data
+
+            # Should have Link header
+            assert "Link" in response.headers
+            assert "/register" in response.headers["Link"]
+
+    def test_successful_authorization_not_enhanced(self, oauth_proxy):
+        """Test that successful authorizations are not modified by enhancement."""
+        app = Starlette(routes=oauth_proxy.get_routes())
+
+        # Register a valid client first
+        client_info = OAuthClientInformationFull(
+            client_id="valid-client",
+            client_secret="valid-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        # Need to register synchronously
+        import asyncio
+
+        asyncio.run(oauth_proxy.register_client(client_info))
+
+        with TestClient(app) as client:
+            response = client.get(
+                "/authorize",
+                params={
+                    "client_id": "valid-client",
+                    "redirect_uri": "http://localhost:12345/callback",
+                    "response_type": "code",
+                    "code_challenge": "test-challenge",
+                    "state": "test-state",
+                },
+                headers={"Accept": "text/html"},
+                follow_redirects=False,
+            )
+
+            # Should redirect to consent page (302), not return error
+            assert response.status_code == 302
+            assert "/consent" in response.headers["location"]
+
+    def test_html_error_includes_server_branding(self, oauth_proxy):
+        """Test that HTML error page includes server branding from FastMCP instance."""
+        from mcp_types import Icon
+
+        # Create FastMCP server with custom branding
+        mcp = FastMCP(
+            "My Custom Server",
+            icons=[Icon(src="https://example.com/icon.png", mime_type="image/png")],
+        )
+
+        # Create app with OAuth routes
+        app = Starlette(routes=oauth_proxy.get_routes())
+        # Attach FastMCP instance to app state (same as done in http.py)
+        app.state.fastmcp_server = mcp
+
+        with TestClient(app) as client:
+            response = client.get(
+                "/authorize",
+                params={
+                    "client_id": "unregistered-client-id",
+                    "redirect_uri": "http://localhost:12345/callback",
+                    "response_type": "code",
+                    "code_challenge": "test-challenge",
+                },
+                headers={"Accept": "text/html"},
+            )
+
+            assert response.status_code == 400
+            html = response.text
+
+            # Should include custom server icon
+            assert "https://example.com/icon.png" in html
+
+
+class TestEnhancedRequireAuthMiddleware:
+    """Tests for enhanced authentication middleware error messages."""
+
+    @pytest.fixture
+    def rsa_key_pair(self) -> RSAKeyPair:
+        """Generate RSA key pair for testing."""
+        return RSAKeyPair.generate()
+
+    @pytest.fixture
+    def jwt_verifier(self, rsa_key_pair):
+        """Create JWT verifier for testing."""
+        return JWTVerifier(
+            public_key=rsa_key_pair.public_key,
+            issuer="https://test.com",
+            audience="https://test.com",
+            base_url="https://test.com",
+        )
+
+    def test_missing_auth_no_error_attribute(self, jwt_verifier):
+        """Test that missing auth returns 401 without error attribute (RFC 6750 §3.1)."""
+        from fastmcp.server.http import create_streamable_http_app
+
+        server = FastMCP("Test Server")
+
+        @server.tool
+        def test_tool() -> str:
+            return "test"
+
+        app = create_streamable_http_app(
+            server=server,
+            streamable_http_path="/mcp",
+            auth=jwt_verifier,
+        )
+
+        with TestClient(app) as client:
+            # Request without Authorization header
+            response = client.post("/mcp")
+
+            assert response.status_code == 401
+            assert "www-authenticate" in response.headers
+
+            # Per RFC 6750 §3.1: no error attribute when auth is missing
+            www_auth = response.headers["www-authenticate"]
+            assert "error=" not in www_auth
+            assert response.content == b""
+
+    def test_invalid_token_enhanced_error_message(self, jwt_verifier):
+        """Test that invalid_token errors have enhanced error messages."""
+        from fastmcp.server.http import create_streamable_http_app
+
+        server = FastMCP("Test Server")
+
+        @server.tool
+        def test_tool() -> str:
+            return "test"
+
+        app = create_streamable_http_app(
+            server=server,
+            streamable_http_path="/mcp",
+            auth=jwt_verifier,
+        )
+
+        with TestClient(app) as client:
+            # Request WITH an invalid Authorization header
+            response = client.post(
+                "/mcp", headers={"Authorization": "Bearer invalid-token"}
+            )
+
+            assert response.status_code == 401
+            assert "www-authenticate" in response.headers
+
+            # Check enhanced error message
+            data = response.json()
+            assert data["error"] == "invalid_token"
+            # Should have enhanced description with resolution steps
+            assert "clear authentication tokens" in data["error_description"]
+            assert "automatically re-register" in data["error_description"]
+
+    def test_invalid_token_www_authenticate_header_format(self, jwt_verifier):
+        """Test that invalid token WWW-Authenticate header includes error attribute."""
+        from fastmcp.server.http import create_streamable_http_app
+
+        server = FastMCP("Test Server")
+        app = create_streamable_http_app(
+            server=server,
+            streamable_http_path="/mcp",
+            auth=jwt_verifier,
+        )
+
+        with TestClient(app) as client:
+            # Request WITH an invalid token
+            response = client.post(
+                "/mcp", headers={"Authorization": "Bearer invalid-token"}
+            )
+
+            assert response.status_code == 401
+            www_auth = response.headers["www-authenticate"]
+
+            # Should follow Bearer challenge format with error
+            assert www_auth.startswith("Bearer ")
+            assert 'error="invalid_token"' in www_auth
+            assert "error_description=" in www_auth
+
+    def test_insufficient_scope_not_enhanced(self, rsa_key_pair):
+        """Test that insufficient_scope errors are not modified."""
+        # Create a valid token with wrong scopes
+        from fastmcp.server.http import create_streamable_http_app
+
+        jwt_verifier = JWTVerifier(
+            public_key=rsa_key_pair.public_key,
+            issuer="https://test.com",
+            audience="https://test.com",
+            base_url="https://test.com",
+        )
+
+        server = FastMCP("Test Server")
+
+        @server.tool
+        def test_tool() -> str:
+            return "test"
+
+        app = create_streamable_http_app(
+            server=server,
+            streamable_http_path="/mcp",
+            auth=jwt_verifier,
+        )
+
+        # Note: Testing insufficient_scope would require mocking the verifier
+        # to return a token with wrong scopes. For now, we verify the middleware
+        # is properly in place by checking it rejects unauthenticated requests.
+        with TestClient(app) as client:
+            response = client.post("/mcp")
+            # Without a valid token, we get invalid_token
+            assert response.status_code == 401
+
+
+class TestContentNegotiation:
+    """Tests for content negotiation in error responses."""
+
+    @pytest.fixture
+    def oauth_proxy(self):
+        """Create OAuth proxy for testing."""
+        from key_value.aio.stores.memory import MemoryStore
+
+        return OAuthProxy(
+            upstream_authorization_endpoint="https://github.com/login/oauth/authorize",
+            upstream_token_endpoint="https://github.com/login/oauth/access_token",
+            upstream_client_id="test-client-id",
+            upstream_client_secret="test-client-secret",
+            token_verifier=JWTVerifier(
+                public_key=RSAKeyPair.generate().public_key,
+                issuer="https://test.com",
+                audience="https://test.com",
+                base_url="https://test.com",
+            ),
+            base_url="https://myserver.com",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+    def test_html_preferred_when_both_accepted(self, oauth_proxy):
+        """Test that HTML is preferred when both text/html and application/json are accepted."""
+        app = Starlette(routes=oauth_proxy.get_routes())
+
+        with TestClient(app) as client:
+            response = client.get(
+                "/authorize",
+                params={
+                    "client_id": "unregistered-client-id",
+                    "redirect_uri": "http://localhost:12345/callback",
+                    "response_type": "code",
+                    "code_challenge": "test-challenge",
+                },
+                headers={"Accept": "text/html,application/json"},
+            )
+
+            # Should prefer HTML
+            assert response.status_code == 400
+            assert "text/html" in response.headers["content-type"]
+
+    def test_json_when_only_json_accepted(self, oauth_proxy):
+        """Test that JSON is returned when only application/json is accepted."""
+        app = Starlette(routes=oauth_proxy.get_routes())
+
+        with TestClient(app) as client:
+            response = client.get(
+                "/authorize",
+                params={
+                    "client_id": "unregistered-client-id",
+                    "redirect_uri": "http://localhost:12345/callback",
+                    "response_type": "code",
+                    "code_challenge": "test-challenge",
+                },
+                headers={"Accept": "application/json"},
+            )
+
+            assert response.status_code == 400
+            assert "application/json" in response.headers["content-type"]
+
+    def test_json_when_no_accept_header(self, oauth_proxy):
+        """Test that JSON is returned when no Accept header is provided."""
+        app = Starlette(routes=oauth_proxy.get_routes())
+
+        with TestClient(app) as client:
+            response = client.get(
+                "/authorize",
+                params={
+                    "client_id": "unregistered-client-id",
+                    "redirect_uri": "http://localhost:12345/callback",
+                    "response_type": "code",
+                    "code_challenge": "test-challenge",
+                },
+            )
+
+            # Without Accept header, should return JSON (API default)
+            assert response.status_code == 400
+            assert "application/json" in response.headers["content-type"]
diff --git a/tests/server/auth/test_jwt_issuer.py b/tests/server/auth/test_jwt_issuer.py
new file mode 100644
index 0000000..1f1b8d3
--- /dev/null
+++ b/tests/server/auth/test_jwt_issuer.py
@@ -0,0 +1,310 @@
+"""Unit tests for JWT issuer and token encryption."""
+
+import base64
+import time
+
+import pytest
+from joserfc.errors import JoseError
+
+from fastmcp.server.auth.jwt_issuer import (
+    JWTIssuer,
+    derive_jwt_key,
+)
+
+
+class TestKeyDerivation:
+    """Tests for HKDF key derivation functions."""
+
+    def test_derive_jwt_key_produces_32_bytes(self):
+        """Test that JWT key derivation produces 32-byte key."""
+        key = derive_jwt_key(high_entropy_material="test-secret", salt="test-salt")
+        assert len(key) == 44
+        assert isinstance(key, bytes)
+
+        # base64 decode and make sure its 32 bytes
+        key_bytes = base64.urlsafe_b64decode(key)
+        assert len(key_bytes) == 32
+
+        key = derive_jwt_key(low_entropy_material="test-secret", salt="test-salt")
+        assert len(key) == 44
+        assert isinstance(key, bytes)
+
+        # base64 decode and make sure its 32 bytes
+        key_bytes = base64.urlsafe_b64decode(key)
+        assert len(key_bytes) == 32
+
+    def test_derive_jwt_key_with_different_secrets_produces_different_keys(self):
+        """Test that different secrets produce different keys."""
+        key1 = derive_jwt_key(high_entropy_material="secret1", salt="salt")
+        key2 = derive_jwt_key(high_entropy_material="secret2", salt="salt")
+        assert key1 != key2
+
+        key1 = derive_jwt_key(low_entropy_material="secret1", salt="salt")
+        key2 = derive_jwt_key(low_entropy_material="secret2", salt="salt")
+        assert key1 != key2
+
+    def test_derive_jwt_key_with_different_salts_produces_different_keys(self):
+        """Test that different salts produce different keys."""
+        key1 = derive_jwt_key(high_entropy_material="secret", salt="salt1")
+        key2 = derive_jwt_key(high_entropy_material="secret", salt="salt2")
+        assert key1 != key2
+
+        key1 = derive_jwt_key(low_entropy_material="secret", salt="salt1")
+        key2 = derive_jwt_key(low_entropy_material="secret", salt="salt2")
+        assert key1 != key2
+
+    def test_derive_jwt_key_is_deterministic(self):
+        """Test that same inputs always produce same key."""
+        key1 = derive_jwt_key(high_entropy_material="secret", salt="salt")
+        key2 = derive_jwt_key(high_entropy_material="secret", salt="salt")
+        assert key1 == key2
+
+        key1 = derive_jwt_key(low_entropy_material="secret", salt="salt")
+        key2 = derive_jwt_key(low_entropy_material="secret", salt="salt")
+        assert key1 == key2
+
+
+class TestJWTIssuer:
+    """Tests for JWT token issuance and verification."""
+
+    @pytest.fixture
+    def issuer(self):
+        """Create a JWT issuer for testing."""
+        signing_key = derive_jwt_key(
+            low_entropy_material="test-secret", salt="test-salt"
+        )
+        return JWTIssuer(
+            issuer="https://test-server.com",
+            audience="https://test-server.com/mcp",
+            signing_key=signing_key,
+        )
+
+    def test_issue_access_token_creates_valid_jwt(self, issuer):
+        """Test that access token is a minimal JWT with correct structure."""
+        token = issuer.issue_access_token(
+            client_id="client-abc",
+            scopes=["read", "write"],
+            jti="token-id-123",
+            expires_in=3600,
+        )
+
+        # Should be a JWT with 3 segments
+        assert len(token.split(".")) == 3
+
+        # Should be verifiable
+        payload = issuer.verify_token(token)
+        # Minimal token should only have required claims
+        assert payload["client_id"] == "client-abc"
+        assert payload["scope"] == "read write"
+        assert payload["jti"] == "token-id-123"
+        assert payload["iss"] == "https://test-server.com"
+        assert payload["aud"] == "https://test-server.com/mcp"
+        # Should NOT have user identity claims
+        assert "sub" not in payload
+        assert "azp" not in payload
+
+    def test_minimal_token_has_no_user_identity(self, issuer):
+        """Test that minimal tokens contain no user identity or custom claims."""
+        token = issuer.issue_access_token(
+            client_id="client-abc",
+            scopes=["read"],
+            jti="token-id",
+            expires_in=3600,
+        )
+
+        payload = issuer.verify_token(token)
+        # Should only have minimal required claims
+        assert "sub" not in payload
+        assert "azp" not in payload
+        assert "groups" not in payload
+        assert "roles" not in payload
+        assert "email" not in payload
+        # Should have exactly these claims
+        expected_keys = {"iss", "aud", "client_id", "scope", "exp", "iat", "jti"}
+        assert set(payload.keys()) == expected_keys
+
+    def test_issue_refresh_token_creates_valid_jwt(self, issuer):
+        """Test that refresh token is a minimal JWT with token_use claim."""
+        token = issuer.issue_refresh_token(
+            client_id="client-abc",
+            scopes=["read"],
+            jti="refresh-token-id",
+            expires_in=60 * 60 * 24 * 30,  # 30 days
+        )
+
+        payload = issuer.verify_token(token, expected_token_use="refresh")
+        assert payload["client_id"] == "client-abc"
+        assert payload["token_use"] == "refresh"
+        assert payload["jti"] == "refresh-token-id"
+        # Should NOT have user identity
+        assert "sub" not in payload
+
+    def test_verify_token_validates_signature(self, issuer):
+        """Test that token verification fails with wrong signing key."""
+        # Create token with one issuer
+        token = issuer.issue_access_token(
+            client_id="client-abc",
+            scopes=["read"],
+            jti="token-id",
+        )
+
+        # Try to verify with different issuer (different key)
+        other_key = derive_jwt_key(
+            low_entropy_material="different-secret", salt="different-salt"
+        )
+        other_issuer = JWTIssuer(
+            issuer="https://test-server.com",
+            audience="https://test-server.com/mcp",
+            signing_key=other_key,
+        )
+
+        with pytest.raises(JoseError):
+            other_issuer.verify_token(token)
+
+    def test_verify_token_validates_expiration(self, issuer):
+        """Test that expired tokens are rejected."""
+        # Create token that expires in 1 second
+        token = issuer.issue_access_token(
+            client_id="client-abc",
+            scopes=["read"],
+            jti="token-id",
+            expires_in=1,
+        )
+
+        # Should be valid immediately
+        payload = issuer.verify_token(token)
+        assert payload["client_id"] == "client-abc"
+
+        # Wait for token to expire
+        time.sleep(1.1)
+
+        # Should be rejected
+        with pytest.raises(JoseError, match="expired"):
+            issuer.verify_token(token)
+
+    def test_verify_token_validates_issuer(self, issuer):
+        """Test that tokens from different issuers are rejected."""
+        token = issuer.issue_access_token(
+            client_id="client-abc",
+            scopes=["read"],
+            jti="token-id",
+        )
+
+        # Create issuer with different issuer URL but same key
+        other_issuer = JWTIssuer(
+            issuer="https://other-server.com",  # Different issuer
+            audience="https://test-server.com/mcp",
+            signing_key=issuer._signing_key,  # Same key
+        )
+
+        with pytest.raises(JoseError, match="issuer"):
+            other_issuer.verify_token(token)
+
+    def test_verify_token_validates_audience(self, issuer):
+        """Test that tokens for different audiences are rejected."""
+        token = issuer.issue_access_token(
+            client_id="client-abc",
+            scopes=["read"],
+            jti="token-id",
+        )
+
+        # Create issuer with different audience but same key
+        other_issuer = JWTIssuer(
+            issuer="https://test-server.com",
+            audience="https://other-server.com/mcp",  # Different audience
+            signing_key=issuer._signing_key,  # Same key
+        )
+
+        with pytest.raises(JoseError, match="audience"):
+            other_issuer.verify_token(token)
+
+    def test_verify_token_rejects_malformed_tokens(self, issuer):
+        """Test that malformed tokens are rejected."""
+        with pytest.raises(JoseError):
+            issuer.verify_token("not-a-jwt")
+
+        with pytest.raises(JoseError):
+            issuer.verify_token("too.few.segments")
+
+        with pytest.raises(JoseError):
+            issuer.verify_token("header.payload")  # Missing signature
+
+    def test_issue_access_token_with_upstream_claims(self, issuer):
+        """Test that upstream claims are included when provided."""
+        upstream_claims = {
+            "sub": "user-123",
+            "oid": "object-id-456",
+            "name": "Test User",
+            "email": "test@example.com",
+            "roles": ["Admin", "Reader"],
+        }
+        token = issuer.issue_access_token(
+            client_id="client-abc",
+            scopes=["read", "write"],
+            jti="token-id-123",
+            expires_in=3600,
+            upstream_claims=upstream_claims,
+        )
+
+        payload = issuer.verify_token(token)
+        assert "upstream_claims" in payload
+        assert payload["upstream_claims"]["sub"] == "user-123"
+        assert payload["upstream_claims"]["oid"] == "object-id-456"
+        assert payload["upstream_claims"]["name"] == "Test User"
+        assert payload["upstream_claims"]["email"] == "test@example.com"
+        assert payload["upstream_claims"]["roles"] == ["Admin", "Reader"]
+
+    def test_issue_access_token_without_upstream_claims(self, issuer):
+        """Test that upstream_claims is not present when not provided."""
+        token = issuer.issue_access_token(
+            client_id="client-abc",
+            scopes=["read"],
+            jti="token-id-123",
+            expires_in=3600,
+        )
+
+        payload = issuer.verify_token(token)
+        assert "upstream_claims" not in payload
+
+    def test_issue_refresh_token_with_upstream_claims(self, issuer):
+        """Test that refresh tokens also include upstream claims when provided."""
+        upstream_claims = {
+            "sub": "user-123",
+            "name": "Test User",
+        }
+        token = issuer.issue_refresh_token(
+            client_id="client-abc",
+            scopes=["read"],
+            jti="refresh-token-id",
+            expires_in=60 * 60 * 24 * 30,
+            upstream_claims=upstream_claims,
+        )
+
+        payload = issuer.verify_token(token, expected_token_use="refresh")
+        assert "upstream_claims" in payload
+        assert payload["upstream_claims"]["sub"] == "user-123"
+        assert payload["upstream_claims"]["name"] == "Test User"
+        assert payload["token_use"] == "refresh"
+
+    def test_verify_token_rejects_refresh_token_as_access(self, issuer):
+        """Refresh tokens must not be accepted when expecting access tokens."""
+        token = issuer.issue_refresh_token(
+            client_id="client-abc",
+            scopes=["read"],
+            jti="refresh-token-id",
+            expires_in=60 * 60 * 24 * 30,
+        )
+
+        with pytest.raises(JoseError, match="Token type mismatch"):
+            issuer.verify_token(token)
+
+    def test_verify_token_rejects_access_token_as_refresh(self, issuer):
+        """Access tokens must not be accepted when expecting refresh tokens."""
+        token = issuer.issue_access_token(
+            client_id="client-abc",
+            scopes=["read"],
+            jti="token-id",
+        )
+
+        with pytest.raises(JoseError, match="Token type mismatch"):
+            issuer.verify_token(token, expected_token_use="refresh")
diff --git a/tests/server/auth/test_jwt_provider.py b/tests/server/auth/test_jwt_provider.py
new file mode 100644
index 0000000..8ccb1f3
--- /dev/null
+++ b/tests/server/auth/test_jwt_provider.py
@@ -0,0 +1,688 @@
+import time
+from collections.abc import AsyncGenerator
+from typing import Any
+from unittest.mock import patch
+
+import pytest
+from joserfc import jwk as jose_jwk
+from joserfc import jwt
+from joserfc.jws import JWSRegistry
+from joserfc.registry import HeaderParameter
+from pytest_httpx import HTTPXMock
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.jwt import JWKData, JWKSData, JWTVerifier, RSAKeyPair
+from fastmcp.utilities.tests import run_server_async
+
+# Standard public IP used for DNS mocking in tests
+TEST_PUBLIC_IP = "93.184.216.34"
+
+
+class SymmetricKeyHelper:
+    """Helper class for generating symmetric key JWT tokens for testing."""
+
+    def __init__(self, secret: str):
+        """Initialize with a secret key."""
+        self.secret = secret
+
+    def create_token(
+        self,
+        subject: str = "fastmcp-user",
+        issuer: str = "https://fastmcp.example.com",
+        audience: str | list[str] | None = None,
+        scopes: list[str] | None = None,
+        expires_in_seconds: int = 3600,
+        additional_claims: dict[str, Any] | None = None,
+        algorithm: str = "HS256",
+    ) -> str:
+        """
+        Generate a test JWT token using symmetric key for testing purposes.
+
+        Args:
+            subject: Subject claim (usually user ID)
+            issuer: Issuer claim
+            audience: Audience claim - can be a string or list of strings (optional)
+            scopes: List of scopes to include
+            expires_in_seconds: Token expiration time in seconds
+            additional_claims: Any additional claims to include
+            algorithm: JWT signing algorithm (HS256, HS384, or HS512)
+        """
+        # Create header
+        header = {"alg": algorithm}
+
+        # Create payload
+        payload: dict[str, str | int | list[str]] = {
+            "sub": subject,
+            "iss": issuer,
+            "iat": int(time.time()),
+            "exp": int(time.time()) + expires_in_seconds,
+        }
+
+        if audience:
+            payload["aud"] = audience
+
+        if scopes:
+            payload["scope"] = " ".join(scopes)
+
+        if additional_claims:
+            payload.update(additional_claims)
+
+        # Create JWT
+        signing_key = jose_jwk.import_key(self.secret, "oct")
+        token = jwt.encode(header, payload, signing_key, algorithms=[algorithm])
+
+        return token
+
+
+@pytest.fixture(scope="module")
+def rsa_key_pair() -> RSAKeyPair:
+    return RSAKeyPair.generate()
+
+
+@pytest.fixture(scope="module")
+def symmetric_key_helper() -> SymmetricKeyHelper:
+    """Generate a symmetric key helper for testing."""
+    return SymmetricKeyHelper("test-secret-key-for-hmac-signing")
+
+
+@pytest.fixture(scope="module")
+def bearer_token(rsa_key_pair: RSAKeyPair) -> str:
+    return rsa_key_pair.create_token(
+        subject="test-user",
+        issuer="https://test.example.com",
+        audience="https://api.example.com",
+    )
+
+
+@pytest.fixture
+def bearer_provider(rsa_key_pair: RSAKeyPair) -> JWTVerifier:
+    return JWTVerifier(
+        public_key=rsa_key_pair.public_key,
+        issuer="https://test.example.com",
+        audience="https://api.example.com",
+    )
+
+
+@pytest.fixture
+def symmetric_provider(symmetric_key_helper: SymmetricKeyHelper) -> JWTVerifier:
+    """Create JWTVerifier configured for symmetric key verification."""
+    return JWTVerifier(
+        public_key=symmetric_key_helper.secret,
+        issuer="https://test.example.com",
+        audience="https://api.example.com",
+        algorithm="HS256",
+    )
+
+
+def create_mcp_server(
+    public_key: str,
+    auth_kwargs: dict[str, Any] | None = None,
+) -> FastMCP:
+    mcp = FastMCP(
+        auth=JWTVerifier(
+            public_key=public_key,
+            **auth_kwargs or {},
+        )
+    )
+
+    @mcp.tool
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    return mcp
+
+
+@pytest.fixture
+async def mcp_server_url(rsa_key_pair: RSAKeyPair) -> AsyncGenerator[str, None]:
+    server = create_mcp_server(
+        public_key=rsa_key_pair.public_key,
+        auth_kwargs=dict(
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+        ),
+    )
+    async with run_server_async(server, transport="http") as url:
+        yield url
+
+
+class TestRSAKeyPair:
+    def test_generate_key_pair(self):
+        """Test RSA key pair generation."""
+        key_pair = RSAKeyPair.generate()
+
+        assert key_pair.private_key is not None
+        assert key_pair.public_key is not None
+
+        # Check that keys are in PEM format
+        private_pem = key_pair.private_key.get_secret_value()
+        public_pem = key_pair.public_key
+
+        assert "-----BEGIN PRIVATE KEY-----" in private_pem
+        assert "-----END PRIVATE KEY-----" in private_pem
+        assert "-----BEGIN PUBLIC KEY-----" in public_pem
+        assert "-----END PUBLIC KEY-----" in public_pem
+
+    def test_create_basic_token(self, rsa_key_pair: RSAKeyPair):
+        """Test basic token creation."""
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+        )
+
+        assert isinstance(token, str)
+        assert len(token.split(".")) == 3  # JWT has 3 parts
+
+    def test_create_token_with_scopes(self, rsa_key_pair: RSAKeyPair):
+        """Test token creation with scopes."""
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            scopes=["read", "write"],
+        )
+
+        assert isinstance(token, str)
+        # We'll validate the scopes in the BearerToken tests
+
+
+class TestJWTVerifierHeaders:
+    async def test_non_critical_private_header_is_allowed(
+        self, rsa_key_pair: RSAKeyPair
+    ):
+        signing_key = jose_jwk.import_key(
+            rsa_key_pair.private_key.get_secret_value(),
+            "RSA",
+        )
+        token = jwt.encode(
+            {
+                "alg": "RS256",
+                "cat": "cl_example",
+            },
+            {
+                "sub": "test-user",
+                "iss": "https://test.example.com",
+                "exp": int(time.time()) + 3600,
+            },
+            signing_key,
+            algorithms=["RS256"],
+            registry=JWSRegistry(strict_check_header=False),
+        )
+        verifier = JWTVerifier(
+            public_key=rsa_key_pair.public_key,
+            issuer="https://test.example.com",
+        )
+
+        access_token = await verifier.verify_token(token)
+
+        assert access_token is not None
+        assert access_token.client_id == "test-user"
+
+    async def test_critical_private_header_is_rejected(self, rsa_key_pair: RSAKeyPair):
+        signing_key = jose_jwk.import_key(
+            rsa_key_pair.private_key.get_secret_value(),
+            "RSA",
+        )
+        token = jwt.encode(
+            {
+                "alg": "RS256",
+                "crit": ["cat"],
+                "cat": "cl_example",
+            },
+            {
+                "sub": "test-user",
+                "iss": "https://test.example.com",
+                "exp": int(time.time()) + 3600,
+            },
+            signing_key,
+            algorithms=["RS256"],
+            registry=JWSRegistry(
+                header_registry={
+                    "cat": HeaderParameter("Custom private header", "str")
+                },
+                strict_check_header=False,
+            ),
+        )
+        verifier = JWTVerifier(
+            public_key=rsa_key_pair.public_key,
+            issuer="https://test.example.com",
+        )
+
+        access_token = await verifier.verify_token(token)
+
+        assert access_token is None
+
+
+class TestSymmetricKeyJWT:
+    """Tests for JWT verification using symmetric keys (HMAC algorithms)."""
+
+    def test_initialization_with_symmetric_key(
+        self, symmetric_key_helper: SymmetricKeyHelper
+    ):
+        """Test JWTVerifier initialization with symmetric key."""
+        provider = JWTVerifier(
+            public_key=symmetric_key_helper.secret,
+            issuer="https://test.example.com",
+            algorithm="HS256",
+        )
+
+        assert provider.issuer == "https://test.example.com"
+        assert provider.public_key == symmetric_key_helper.secret
+        assert provider.algorithm == "HS256"
+        assert provider.jwks_uri is None
+
+    def test_initialization_rejects_hs_algorithm_with_jwks_uri(self):
+        """Test that HMAC algorithms cannot be used with JWKS URI."""
+        with pytest.raises(ValueError, match="cannot be used with jwks_uri"):
+            JWTVerifier(
+                jwks_uri="https://test.example.com/.well-known/jwks.json",
+                issuer="https://test.example.com",
+                algorithm="HS256",
+            )
+
+    def test_initialization_with_different_symmetric_algorithms(
+        self, symmetric_key_helper: SymmetricKeyHelper
+    ):
+        """Test JWTVerifier initialization with different HMAC algorithms."""
+        algorithms = ["HS256", "HS384", "HS512"]
+
+        for algorithm in algorithms:
+            provider = JWTVerifier(
+                public_key=symmetric_key_helper.secret,
+                issuer="https://test.example.com",
+                algorithm=algorithm,
+            )
+            assert provider.algorithm == algorithm
+
+    def test_symmetric_algorithm_rejects_jwks_uri(self):
+        """HS* algorithms must not be configured with JWKS/public key endpoints."""
+        with pytest.raises(ValueError, match="cannot be used with jwks_uri"):
+            JWTVerifier(
+                jwks_uri="https://test.example.com/.well-known/jwks.json",
+                issuer="https://test.example.com",
+                algorithm="HS256",
+            )
+
+    def test_symmetric_algorithm_rejects_pem_public_key(self, rsa_key_pair: RSAKeyPair):
+        """HS* algorithms must use a shared secret, not PEM public key material."""
+        with pytest.raises(ValueError, match="require a shared secret"):
+            JWTVerifier(
+                public_key=rsa_key_pair.public_key,
+                issuer="https://test.example.com",
+                algorithm="HS256",
+            )
+
+    def test_symmetric_algorithm_accepts_bytes_secret(self):
+        """HS* algorithms accept bytes secrets without TypeError."""
+        verifier = JWTVerifier(
+            public_key=b"secret",
+            algorithm="HS256",
+        )
+        assert verifier.algorithm == "HS256"
+
+    async def test_valid_symmetric_token_validation(
+        self, symmetric_key_helper: SymmetricKeyHelper, symmetric_provider: JWTVerifier
+    ):
+        """Test validation of a valid token signed with symmetric key."""
+        token = symmetric_key_helper.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            scopes=["read", "write"],
+            algorithm="HS256",
+        )
+
+        access_token = await symmetric_provider.load_access_token(token)
+
+        assert access_token is not None
+        assert access_token.client_id == "test-user"
+        assert "read" in access_token.scopes
+        assert "write" in access_token.scopes
+        assert access_token.expires_at is not None
+
+    async def test_symmetric_token_with_different_algorithms(
+        self, symmetric_key_helper: SymmetricKeyHelper
+    ):
+        """Test that different HMAC algorithms work correctly."""
+        algorithms = ["HS256", "HS384", "HS512"]
+
+        for algorithm in algorithms:
+            provider = JWTVerifier(
+                public_key=symmetric_key_helper.secret,
+                issuer="https://test.example.com",
+                algorithm=algorithm,
+            )
+
+            token = symmetric_key_helper.create_token(
+                subject="test-user",
+                issuer="https://test.example.com",
+                algorithm=algorithm,
+            )
+
+            access_token = await provider.load_access_token(token)
+            assert access_token is not None
+            assert access_token.client_id == "test-user"
+
+    async def test_symmetric_token_issuer_validation(
+        self, symmetric_key_helper: SymmetricKeyHelper, symmetric_provider: JWTVerifier
+    ):
+        """Test issuer validation with symmetric key tokens."""
+        # Valid issuer
+        valid_token = symmetric_key_helper.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+        )
+        access_token = await symmetric_provider.load_access_token(valid_token)
+        assert access_token is not None
+
+        # Invalid issuer
+        invalid_token = symmetric_key_helper.create_token(
+            subject="test-user",
+            issuer="https://evil.example.com",
+            audience="https://api.example.com",
+        )
+        access_token = await symmetric_provider.load_access_token(invalid_token)
+        assert access_token is None
+
+    async def test_symmetric_token_audience_validation(
+        self, symmetric_key_helper: SymmetricKeyHelper, symmetric_provider: JWTVerifier
+    ):
+        """Test audience validation with symmetric key tokens."""
+        # Valid audience
+        valid_token = symmetric_key_helper.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+        )
+        access_token = await symmetric_provider.load_access_token(valid_token)
+        assert access_token is not None
+
+        # Invalid audience
+        invalid_token = symmetric_key_helper.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://wrong-api.example.com",
+        )
+        access_token = await symmetric_provider.load_access_token(invalid_token)
+        assert access_token is None
+
+    async def test_symmetric_token_scope_extraction(
+        self, symmetric_key_helper: SymmetricKeyHelper, symmetric_provider: JWTVerifier
+    ):
+        """Test scope extraction from symmetric key tokens."""
+        token = symmetric_key_helper.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            scopes=["read", "write", "admin"],
+        )
+
+        access_token = await symmetric_provider.load_access_token(token)
+        assert access_token is not None
+        assert set(access_token.scopes) == {"read", "write", "admin"}
+
+    async def test_symmetric_token_expiration(
+        self, symmetric_key_helper: SymmetricKeyHelper, symmetric_provider: JWTVerifier
+    ):
+        """Test expiration validation with symmetric key tokens."""
+        # Valid token
+        valid_token = symmetric_key_helper.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            expires_in_seconds=3600,  # 1 hour from now
+        )
+        access_token = await symmetric_provider.load_access_token(valid_token)
+        assert access_token is not None
+
+        # Expired token
+        expired_token = symmetric_key_helper.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            expires_in_seconds=-3600,  # 1 hour ago
+        )
+        access_token = await symmetric_provider.load_access_token(expired_token)
+        assert access_token is None
+
+    async def test_symmetric_token_invalid_signature(
+        self, symmetric_key_helper: SymmetricKeyHelper, symmetric_provider: JWTVerifier
+    ):
+        """Test rejection of tokens with invalid signatures."""
+        # Create a token with a different secret
+        other_helper = SymmetricKeyHelper("different-secret-key")
+        token = other_helper.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+        )
+
+        access_token = await symmetric_provider.load_access_token(token)
+        assert access_token is None
+
+    async def test_symmetric_token_algorithm_mismatch(
+        self, symmetric_key_helper: SymmetricKeyHelper
+    ):
+        """Test that tokens with mismatched algorithms are rejected."""
+        # Create provider expecting HS256
+        provider = JWTVerifier(
+            public_key=symmetric_key_helper.secret,
+            issuer="https://test.example.com",
+            algorithm="HS256",
+        )
+
+        # Create token with HS512
+        token = symmetric_key_helper.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            algorithm="HS512",
+        )
+
+        # Should fail because provider expects HS256
+        access_token = await provider.load_access_token(token)
+        assert access_token is None
+
+
+class TestBearerTokenJWKS:
+    """Tests for JWKS URI functionality.
+
+    Note: With SSRF protection, JWKS fetches validate DNS and connect to the
+    resolved IP. Tests mock DNS resolution to return a public IP.
+    """
+
+    @pytest.fixture
+    def jwks_provider(self, rsa_key_pair: RSAKeyPair) -> JWTVerifier:
+        """Provider configured with JWKS URI."""
+        return JWTVerifier(
+            jwks_uri="https://test.example.com/.well-known/jwks.json",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+        )
+
+    @pytest.fixture
+    def mock_jwks_data(self, rsa_key_pair: RSAKeyPair) -> JWKSData:
+        """Create mock JWKS data from RSA key pair."""
+        # Create JWK from the RSA public key
+        public_key = jose_jwk.import_key(rsa_key_pair.public_key, "RSA")
+        public_key_data = public_key.as_dict()
+        kty = public_key_data["kty"]
+        n = public_key_data["n"]
+        e = public_key_data["e"]
+        assert isinstance(kty, str)
+        assert isinstance(n, str)
+        assert isinstance(e, str)
+        jwk_data = JWKData(
+            kty=kty,
+            n=n,
+            e=e,
+            kid="test-key-1",
+            alg="RS256",
+        )
+
+        return {"keys": [jwk_data]}
+
+    @pytest.fixture
+    def mock_dns(self):
+        """Mock DNS resolution to return test public IP."""
+        with patch(
+            "fastmcp.server.auth.ssrf.resolve_hostname",
+            return_value=[TEST_PUBLIC_IP],
+        ):
+            yield
+
+    async def test_jwks_token_validation(
+        self,
+        rsa_key_pair: RSAKeyPair,
+        jwks_provider: JWTVerifier,
+        mock_jwks_data: JWKSData,
+        httpx_mock: HTTPXMock,
+        mock_dns,
+    ):
+        """Test token validation using JWKS URI."""
+        httpx_mock.add_response(json=mock_jwks_data)
+
+        username = "test-user"
+        issuer = "https://test.example.com"
+        audience = "https://api.example.com"
+
+        token = rsa_key_pair.create_token(
+            subject=username,
+            issuer=issuer,
+            audience=audience,
+        )
+
+        access_token = await jwks_provider.load_access_token(token)
+        assert access_token is not None
+        assert access_token.client_id == username
+
+        # ensure the raw claims are present - #1398
+        assert access_token.claims.get("sub") == username
+        assert access_token.claims.get("iss") == issuer
+        assert access_token.claims.get("aud") == audience
+
+    async def test_jwks_token_validation_with_invalid_key(
+        self,
+        rsa_key_pair: RSAKeyPair,
+        jwks_provider: JWTVerifier,
+        mock_jwks_data: JWKSData,
+        httpx_mock: HTTPXMock,
+        mock_dns,
+    ):
+        httpx_mock.add_response(json=mock_jwks_data)
+        token = RSAKeyPair.generate().create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+        )
+
+        access_token = await jwks_provider.load_access_token(token)
+        assert access_token is None
+
+    async def test_jwks_token_validation_with_kid(
+        self,
+        rsa_key_pair: RSAKeyPair,
+        jwks_provider: JWTVerifier,
+        mock_jwks_data: JWKSData,
+        httpx_mock: HTTPXMock,
+        mock_dns,
+    ):
+        mock_jwks_data["keys"][0]["kid"] = "test-key-1"
+        httpx_mock.add_response(json=mock_jwks_data)
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            kid="test-key-1",
+        )
+
+        access_token = await jwks_provider.load_access_token(token)
+        assert access_token is not None
+        assert access_token.client_id == "test-user"
+
+    async def test_jwks_token_validation_with_kid_and_no_kid_in_token(
+        self,
+        rsa_key_pair: RSAKeyPair,
+        jwks_provider: JWTVerifier,
+        mock_jwks_data: JWKSData,
+        httpx_mock: HTTPXMock,
+        mock_dns,
+    ):
+        mock_jwks_data["keys"][0]["kid"] = "test-key-1"
+        httpx_mock.add_response(json=mock_jwks_data)
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+        )
+
+        access_token = await jwks_provider.load_access_token(token)
+        assert access_token is not None
+        assert access_token.client_id == "test-user"
+
+    async def test_jwks_token_validation_with_no_kid_and_kid_in_jwks(
+        self,
+        rsa_key_pair: RSAKeyPair,
+        jwks_provider: JWTVerifier,
+        mock_jwks_data: JWKSData,
+        httpx_mock: HTTPXMock,
+        mock_dns,
+    ):
+        mock_jwks_data["keys"][0]["kid"] = "test-key-1"
+        httpx_mock.add_response(json=mock_jwks_data)
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+        )
+
+        access_token = await jwks_provider.load_access_token(token)
+        assert access_token is not None
+        assert access_token.client_id == "test-user"
+
+    async def test_jwks_token_validation_with_kid_mismatch(
+        self,
+        rsa_key_pair: RSAKeyPair,
+        jwks_provider: JWTVerifier,
+        mock_jwks_data: JWKSData,
+        httpx_mock: HTTPXMock,
+        mock_dns,
+    ):
+        mock_jwks_data["keys"][0]["kid"] = "test-key-1"
+        httpx_mock.add_response(json=mock_jwks_data)
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            kid="test-key-2",
+        )
+
+        access_token = await jwks_provider.load_access_token(token)
+        assert access_token is None
+
+    async def test_jwks_token_validation_with_multiple_keys_and_no_kid_in_token(
+        self,
+        rsa_key_pair: RSAKeyPair,
+        jwks_provider: JWTVerifier,
+        mock_jwks_data: JWKSData,
+        httpx_mock: HTTPXMock,
+        mock_dns,
+    ):
+        mock_jwks_data["keys"] = [
+            {
+                "kid": "test-key-1",
+                "alg": "RS256",
+            },
+            {
+                "kid": "test-key-2",
+                "alg": "RS256",
+            },
+        ]
+
+        httpx_mock.add_response(json=mock_jwks_data)
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+        )
+
+        access_token = await jwks_provider.load_access_token(token)
+        assert access_token is None
diff --git a/tests/server/auth/test_jwt_provider_bearer.py b/tests/server/auth/test_jwt_provider_bearer.py
new file mode 100644
index 0000000..eb72227
--- /dev/null
+++ b/tests/server/auth/test_jwt_provider_bearer.py
@@ -0,0 +1,601 @@
+from collections.abc import AsyncGenerator
+from typing import Any
+
+import pytest
+from mcp import MCPError
+
+from fastmcp import Client, FastMCP
+from fastmcp.client.auth.bearer import BearerAuth
+from fastmcp.server.auth.providers.jwt import JWTVerifier, RSAKeyPair
+from fastmcp.utilities.tests import run_server_async
+
+# Standard public IP used for DNS mocking in tests
+TEST_PUBLIC_IP = "93.184.216.34"
+
+
+@pytest.fixture(scope="module")
+def rsa_key_pair() -> RSAKeyPair:
+    return RSAKeyPair.generate()
+
+
+@pytest.fixture(scope="module")
+def bearer_token(rsa_key_pair: RSAKeyPair) -> str:
+    return rsa_key_pair.create_token(
+        subject="test-user",
+        issuer="https://test.example.com",
+        audience="https://api.example.com",
+    )
+
+
+@pytest.fixture
+def bearer_provider(rsa_key_pair: RSAKeyPair) -> JWTVerifier:
+    return JWTVerifier(
+        public_key=rsa_key_pair.public_key,
+        issuer="https://test.example.com",
+        audience="https://api.example.com",
+    )
+
+
+def create_mcp_server(
+    public_key: str,
+    auth_kwargs: dict[str, Any] | None = None,
+) -> FastMCP:
+    mcp = FastMCP(
+        auth=JWTVerifier(
+            public_key=public_key,
+            **auth_kwargs or {},
+        )
+    )
+
+    @mcp.tool
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    return mcp
+
+
+@pytest.fixture
+async def mcp_server_url(rsa_key_pair: RSAKeyPair) -> AsyncGenerator[str, None]:
+    server = create_mcp_server(
+        public_key=rsa_key_pair.public_key,
+        auth_kwargs=dict(
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+        ),
+    )
+    async with run_server_async(server, transport="http") as url:
+        yield url
+
+
+class TestBearerToken:
+    def test_initialization_with_public_key(self, rsa_key_pair: RSAKeyPair):
+        """Test provider initialization with public key."""
+        provider = JWTVerifier(
+            public_key=rsa_key_pair.public_key, issuer="https://test.example.com"
+        )
+
+        assert provider.issuer == "https://test.example.com"
+        assert provider.public_key is not None
+        assert provider.jwks_uri is None
+
+    def test_initialization_with_jwks_uri(self):
+        """Test provider initialization with JWKS URI."""
+        provider = JWTVerifier(
+            jwks_uri="https://test.example.com/.well-known/jwks.json",
+            issuer="https://test.example.com",
+        )
+
+        assert provider.issuer == "https://test.example.com"
+        assert provider.jwks_uri == "https://test.example.com/.well-known/jwks.json"
+        assert provider.public_key is None
+
+    def test_initialization_requires_key_or_uri(self):
+        """Test that either public_key or jwks_uri is required."""
+        with pytest.raises(
+            ValueError, match="Either public_key or jwks_uri must be provided"
+        ):
+            JWTVerifier(issuer="https://test.example.com")
+
+    def test_initialization_rejects_both_key_and_uri(self, rsa_key_pair: RSAKeyPair):
+        """Test that both public_key and jwks_uri cannot be provided."""
+        with pytest.raises(
+            ValueError, match="Provide either public_key or jwks_uri, not both"
+        ):
+            JWTVerifier(
+                public_key=rsa_key_pair.public_key,
+                jwks_uri="https://test.example.com/.well-known/jwks.json",
+                issuer="https://test.example.com",
+            )
+
+    async def test_valid_token_validation(
+        self, rsa_key_pair: RSAKeyPair, bearer_provider: JWTVerifier
+    ):
+        """Test validation of a valid token."""
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            scopes=["read", "write"],
+        )
+
+        access_token = await bearer_provider.load_access_token(token)
+
+        assert access_token is not None
+        assert access_token.client_id == "test-user"
+        assert "read" in access_token.scopes
+        assert "write" in access_token.scopes
+        assert access_token.expires_at is not None
+
+    async def test_expired_token_rejection(
+        self, rsa_key_pair: RSAKeyPair, bearer_provider: JWTVerifier
+    ):
+        """Test rejection of expired tokens."""
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            expires_in_seconds=-3600,  # Expired 1 hour ago
+        )
+
+        access_token = await bearer_provider.load_access_token(token)
+        assert access_token is None
+
+    async def test_invalid_issuer_rejection(
+        self, rsa_key_pair: RSAKeyPair, bearer_provider: JWTVerifier
+    ):
+        """Test rejection of tokens with invalid issuer."""
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://evil.example.com",  # Wrong issuer
+            audience="https://api.example.com",
+        )
+
+        access_token = await bearer_provider.load_access_token(token)
+        assert access_token is None
+
+    async def test_invalid_audience_rejection(
+        self, rsa_key_pair: RSAKeyPair, bearer_provider: JWTVerifier
+    ):
+        """Test rejection of tokens with invalid audience."""
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://wrong-api.example.com",  # Wrong audience
+        )
+
+        access_token = await bearer_provider.load_access_token(token)
+        assert access_token is None
+
+    async def test_no_issuer_validation_when_none(self, rsa_key_pair: RSAKeyPair):
+        """Test that issuer validation is skipped when provider has no issuer configured."""
+        provider = JWTVerifier(
+            public_key=rsa_key_pair.public_key,
+            issuer=None,  # No issuer validation
+        )
+
+        token = rsa_key_pair.create_token(
+            subject="test-user", issuer="https://any.example.com"
+        )
+
+        access_token = await provider.load_access_token(token)
+        assert access_token is not None
+
+    async def test_no_audience_validation_when_none(self, rsa_key_pair: RSAKeyPair):
+        """Test that audience validation is skipped when provider has no audience configured."""
+        provider = JWTVerifier(
+            public_key=rsa_key_pair.public_key,
+            issuer="https://test.example.com",
+            audience=None,  # No audience validation
+        )
+
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://any-api.example.com",
+        )
+
+        access_token = await provider.load_access_token(token)
+        assert access_token is not None
+
+    async def test_multiple_audiences_validation(self, rsa_key_pair: RSAKeyPair):
+        """Test validation with multiple audiences in token."""
+        provider = JWTVerifier(
+            public_key=rsa_key_pair.public_key,
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+        )
+
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            additional_claims={
+                "aud": ["https://api.example.com", "https://other-api.example.com"]
+            },
+        )
+
+        access_token = await provider.load_access_token(token)
+        assert access_token is not None
+
+    async def test_provider_with_multiple_expected_audiences(
+        self, rsa_key_pair: RSAKeyPair
+    ):
+        """Test provider configured with multiple expected audiences."""
+        provider = JWTVerifier(
+            public_key=rsa_key_pair.public_key,
+            issuer="https://test.example.com",
+            audience=["https://api.example.com", "https://other-api.example.com"],
+        )
+
+        # Token with single audience that matches one of the expected
+        token1 = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+        )
+        access_token1 = await provider.load_access_token(token1)
+        assert access_token1 is not None
+
+        # Token with multiple audiences, one of which matches
+        token2 = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            additional_claims={
+                "aud": ["https://api.example.com", "https://third-party.example.com"]
+            },
+        )
+        access_token2 = await provider.load_access_token(token2)
+        assert access_token2 is not None
+
+        # Token with audience that doesn't match any expected
+        token3 = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://wrong-api.example.com",
+        )
+        access_token3 = await provider.load_access_token(token3)
+        assert access_token3 is None
+
+    @pytest.mark.parametrize(
+        ("iss", "expected"),
+        [
+            ("https://test.example.com", True),
+            ("https://other-issuer.example.com", True),
+            ("https://wrong-issuer.example.com", False),
+        ],
+    )
+    async def test_provider_with_multiple_expected_issuers(
+        self, rsa_key_pair: RSAKeyPair, iss: str, expected: bool
+    ):
+        """Provider accepts any issuer from the configured list."""
+        provider = JWTVerifier(
+            public_key=rsa_key_pair.public_key,
+            issuer=["https://test.example.com", "https://other-issuer.example.com"],
+            audience="https://api.example.com",
+        )
+        token = rsa_key_pair.create_token(
+            subject="test-user", issuer=iss, audience="https://api.example.com"
+        )
+        access_token = await provider.load_access_token(token)
+        assert (access_token is not None) is expected
+
+    async def test_scope_extraction_string(
+        self, rsa_key_pair: RSAKeyPair, bearer_provider: JWTVerifier
+    ):
+        """Test scope extraction from space-separated string."""
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            scopes=["read", "write", "admin"],
+        )
+
+        access_token = await bearer_provider.load_access_token(token)
+
+        assert access_token is not None
+        assert set(access_token.scopes) == {"read", "write", "admin"}
+
+    async def test_scope_extraction_list(
+        self, rsa_key_pair: RSAKeyPair, bearer_provider: JWTVerifier
+    ):
+        """Test scope extraction from list format."""
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            additional_claims={"scope": ["read", "write"]},  # List format
+        )
+
+        access_token = await bearer_provider.load_access_token(token)
+
+        assert access_token is not None
+        assert set(access_token.scopes) == {"read", "write"}
+
+    async def test_no_scopes(
+        self, rsa_key_pair: RSAKeyPair, bearer_provider: JWTVerifier
+    ):
+        """Test token with no scopes."""
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            # No scopes
+        )
+
+        access_token = await bearer_provider.load_access_token(token)
+
+        assert access_token is not None
+        assert access_token.scopes == []
+
+    async def test_scp_claim_extraction_string(
+        self, rsa_key_pair: RSAKeyPair, bearer_provider: JWTVerifier
+    ):
+        """Test scope extraction from 'scp' claim with space-separated string."""
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            additional_claims={"scp": "read write admin"},  # 'scp' claim as string
+        )
+
+        access_token = await bearer_provider.load_access_token(token)
+
+        assert access_token is not None
+        assert set(access_token.scopes) == {"read", "write", "admin"}
+
+    async def test_scp_claim_extraction_list(
+        self, rsa_key_pair: RSAKeyPair, bearer_provider: JWTVerifier
+    ):
+        """Test scope extraction from 'scp' claim with list format."""
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            additional_claims={
+                "scp": ["read", "write", "admin"]
+            },  # 'scp' claim as list
+        )
+
+        access_token = await bearer_provider.load_access_token(token)
+
+        assert access_token is not None
+        assert set(access_token.scopes) == {"read", "write", "admin"}
+
+    async def test_scope_precedence_over_scp(
+        self, rsa_key_pair: RSAKeyPair, bearer_provider: JWTVerifier
+    ):
+        """Test that 'scope' claim takes precedence over 'scp' claim when both are present."""
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            additional_claims={
+                "scope": "read write",  # Standard OAuth2 claim
+                "scp": "admin delete",  # Should be ignored when 'scope' is present
+            },
+        )
+
+        access_token = await bearer_provider.load_access_token(token)
+
+        assert access_token is not None
+        assert set(access_token.scopes) == {"read", "write"}  # Only 'scope' claim used
+
+    async def test_malformed_token_rejection(self, bearer_provider: JWTVerifier):
+        """Test rejection of malformed tokens."""
+        malformed_tokens = [
+            "not.a.jwt",
+            "too.many.parts.here.invalid",
+            "invalid-token",
+            "",
+            "header.body",  # Missing signature
+        ]
+
+        for token in malformed_tokens:
+            access_token = await bearer_provider.load_access_token(token)
+            assert access_token is None
+
+    async def test_invalid_signature_rejection(
+        self, rsa_key_pair: RSAKeyPair, bearer_provider: JWTVerifier
+    ):
+        """Test rejection of tokens with invalid signatures."""
+        # Create a token with a different key pair
+        other_key_pair = RSAKeyPair.generate()
+        token = other_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+        )
+
+        access_token = await bearer_provider.load_access_token(token)
+        assert access_token is None
+
+    async def test_client_id_fallback(
+        self, rsa_key_pair: RSAKeyPair, bearer_provider: JWTVerifier
+    ):
+        """Test client_id extraction with fallback logic."""
+        # Test with explicit client_id claim
+        token = rsa_key_pair.create_token(
+            subject="user123",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            additional_claims={"client_id": "app456"},
+        )
+
+        access_token = await bearer_provider.load_access_token(token)
+        assert access_token is not None
+        assert access_token.client_id == "app456"  # Should prefer client_id over sub
+
+    async def test_string_issuer_validation(self, rsa_key_pair: RSAKeyPair):
+        """Test that string (non-URL) issuers are supported per RFC 7519."""
+        # Create provider with string issuer
+        provider = JWTVerifier(
+            public_key=rsa_key_pair.public_key,
+            issuer="my-service",  # String issuer, not a URL
+        )
+
+        # Create token with matching string issuer
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="my-service",  # Same string issuer
+        )
+
+        access_token = await provider.load_access_token(token)
+        assert access_token is not None
+        assert access_token.client_id == "test-user"
+
+    async def test_string_issuer_mismatch_rejection(self, rsa_key_pair: RSAKeyPair):
+        """Test that mismatched string issuers are rejected."""
+        # Create provider with one string issuer
+        provider = JWTVerifier(
+            public_key=rsa_key_pair.public_key,
+            issuer="my-service",
+        )
+
+        # Create token with different string issuer
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="other-service",  # Different string issuer
+        )
+
+        access_token = await provider.load_access_token(token)
+        assert access_token is None
+
+    async def test_url_issuer_still_works(self, rsa_key_pair: RSAKeyPair):
+        """Test that URL issuers still work after the fix."""
+        # Create provider with URL issuer
+        provider = JWTVerifier(
+            public_key=rsa_key_pair.public_key,
+            issuer="https://my-auth-server.com",  # URL issuer
+        )
+
+        # Create token with matching URL issuer
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://my-auth-server.com",  # Same URL issuer
+        )
+
+        access_token = await provider.load_access_token(token)
+        assert access_token is not None
+        assert access_token.client_id == "test-user"
+
+
+class TestFastMCPBearerAuth:
+    def test_bearer_auth(self):
+        mcp = FastMCP(
+            auth=JWTVerifier(issuer="https://test.example.com", public_key="abc")
+        )
+        assert isinstance(mcp.auth, JWTVerifier)
+
+    async def test_unauthorized_access(self, mcp_server_url: str):
+        # SDK v2 masks the server's 401 behind a generic MCPError at the client
+        # boundary rather than re-raising httpx.HTTPStatusError.
+        with pytest.raises(MCPError):
+            async with Client(mcp_server_url) as client:
+                tools = await client.list_tools()  # noqa: F841
+        assert "tools" not in locals()
+
+    async def test_authorized_access(self, mcp_server_url: str, bearer_token):
+        async with Client(mcp_server_url, auth=BearerAuth(bearer_token)) as client:
+            tools = await client.list_tools()  # noqa: F841
+        assert tools
+
+    async def test_invalid_token_raises_401(self, mcp_server_url: str):
+        with pytest.raises(MCPError):
+            async with Client(mcp_server_url, auth=BearerAuth("invalid")) as client:
+                tools = await client.list_tools()  # noqa: F841
+        assert "tools" not in locals()
+
+    async def test_expired_token(self, mcp_server_url: str, rsa_key_pair: RSAKeyPair):
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            expires_in_seconds=-3600,
+        )
+
+        with pytest.raises(MCPError):
+            async with Client(mcp_server_url, auth=BearerAuth(token)) as client:
+                tools = await client.list_tools()  # noqa: F841
+        assert "tools" not in locals()
+
+    async def test_token_with_bad_signature(self, mcp_server_url: str):
+        rsa_key_pair = RSAKeyPair.generate()
+        token = rsa_key_pair.create_token()
+
+        with pytest.raises(MCPError):
+            async with Client(mcp_server_url, auth=BearerAuth(token)) as client:
+                tools = await client.list_tools()  # noqa: F841
+        assert "tools" not in locals()
+
+    async def test_token_with_insufficient_scopes(self, rsa_key_pair: RSAKeyPair):
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            scopes=["read"],
+        )
+
+        server = create_mcp_server(
+            public_key=rsa_key_pair.public_key,
+            auth_kwargs=dict(required_scopes=["read", "write"]),
+        )
+
+        async with run_server_async(server, transport="http") as mcp_server_url:
+            # JWTVerifier rejects the token (verify_token returns None); SDK v2
+            # surfaces the resulting 401 as a generic MCPError at the client.
+            with pytest.raises(MCPError):
+                async with Client(mcp_server_url, auth=BearerAuth(token)) as client:
+                    tools = await client.list_tools()  # noqa: F841
+            assert "tools" not in locals()
+
+    async def test_token_with_sufficient_scopes(self, rsa_key_pair: RSAKeyPair):
+        token = rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            scopes=["read", "write"],
+        )
+
+        server = create_mcp_server(
+            public_key=rsa_key_pair.public_key,
+            auth_kwargs=dict(required_scopes=["read", "write"]),
+        )
+
+        async with run_server_async(server, transport="http") as mcp_server_url:
+            async with Client(mcp_server_url, auth=BearerAuth(token)) as client:
+                tools = await client.list_tools()
+            assert tools
+
+
+class TestJWTVerifierImport:
+    """Test JWT token verifier can be imported and created."""
+
+    def test_jwt_verifier_requires_pyjwt(self):
+        """Test that JWTVerifier raises helpful error without PyJWT."""
+        # Since PyJWT is likely installed in test environment, we'll just test construction
+        from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+        # This should work if PyJWT is available
+        try:
+            verifier = JWTVerifier(public_key="dummy-key")
+            assert verifier.public_key == "dummy-key"
+            assert verifier.algorithm == "RS256"
+        except ImportError as e:
+            # If PyJWT not available, should get helpful error
+            assert "PyJWT is required" in str(e)
+
+
+class TestScopesSupported:
+    """Tests for the scopes_supported property on TokenVerifier."""
+
+    def test_defaults_to_required_scopes(self, rsa_key_pair: RSAKeyPair):
+        provider = JWTVerifier(
+            public_key=rsa_key_pair.public_key,
+            required_scopes=["read", "write"],
+        )
+        assert provider.scopes_supported == ["read", "write"]
+
+    def test_empty_when_no_required_scopes(self, rsa_key_pair: RSAKeyPair):
+        provider = JWTVerifier(
+            public_key=rsa_key_pair.public_key,
+        )
+        assert provider.scopes_supported == []
diff --git a/tests/server/auth/test_multi_auth.py b/tests/server/auth/test_multi_auth.py
new file mode 100644
index 0000000..727158d
--- /dev/null
+++ b/tests/server/auth/test_multi_auth.py
@@ -0,0 +1,494 @@
+import httpx
+import pytest
+from pydantic import AnyHttpUrl
+
+from fastmcp import FastMCP
+from fastmcp.server.auth import MultiAuth, RemoteAuthProvider, TokenVerifier
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.server.auth.providers.jwt import StaticTokenVerifier
+
+
+class RaisingVerifier(TokenVerifier):
+    """A verifier that always raises, for testing exception resilience."""
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        raise RuntimeError("simulated failure")
+
+
+class TestMultiAuthInit:
+    """Test MultiAuth initialization and validation."""
+
+    def test_requires_server_or_verifiers(self):
+        """MultiAuth with neither server nor verifiers raises ValueError."""
+        with pytest.raises(ValueError, match="at least a server or one verifier"):
+            MultiAuth()
+
+    def test_server_only(self):
+        verifier = StaticTokenVerifier(tokens={"t": {"client_id": "c", "scopes": []}})
+        provider = RemoteAuthProvider(
+            token_verifier=verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+        auth = MultiAuth(server=provider)
+        assert auth.server is provider
+        assert auth.verifiers == []
+
+    def test_verifiers_only(self):
+        v = StaticTokenVerifier(tokens={"t": {"client_id": "c", "scopes": []}})
+        auth = MultiAuth(verifiers=[v])
+        assert auth.server is None
+        assert auth.verifiers == [v]
+
+    def test_single_verifier_not_in_list(self):
+        """A single TokenVerifier (not in a list) is accepted."""
+        v = StaticTokenVerifier(tokens={"t": {"client_id": "c", "scopes": []}})
+        auth = MultiAuth(verifiers=v)
+        assert auth.verifiers == [v]
+
+    def test_base_url_from_server(self):
+        verifier = StaticTokenVerifier(tokens={"t": {"client_id": "c", "scopes": []}})
+        provider = RemoteAuthProvider(
+            token_verifier=verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+        auth = MultiAuth(server=provider)
+        assert auth.base_url == AnyHttpUrl("https://api.example.com/")
+
+    def test_base_url_override(self):
+        verifier = StaticTokenVerifier(tokens={"t": {"client_id": "c", "scopes": []}})
+        provider = RemoteAuthProvider(
+            token_verifier=verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+        auth = MultiAuth(server=provider, base_url="https://override.example.com")
+        assert auth.base_url == AnyHttpUrl("https://override.example.com/")
+
+    def test_resource_base_url_from_server(self):
+        verifier = StaticTokenVerifier(tokens={"t": {"client_id": "c", "scopes": []}})
+        provider = RemoteAuthProvider(
+            token_verifier=verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://auth.example.com/proxy",
+            resource_base_url="https://api.example.com",
+        )
+        auth = MultiAuth(server=provider)
+        assert auth.resource_base_url == AnyHttpUrl("https://api.example.com/")
+
+    def test_resource_base_url_override(self):
+        verifier = StaticTokenVerifier(tokens={"t": {"client_id": "c", "scopes": []}})
+        provider = RemoteAuthProvider(
+            token_verifier=verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://auth.example.com/proxy",
+            resource_base_url="https://api.example.com",
+        )
+        auth = MultiAuth(
+            server=provider,
+            resource_base_url="https://override.example.com",
+        )
+        assert auth.resource_base_url == AnyHttpUrl("https://override.example.com/")
+        # Override must propagate to the wrapped server so get_routes()
+        # serves metadata consistent with the outer auth challenge URL.
+        assert provider.resource_base_url == AnyHttpUrl("https://override.example.com/")
+
+    def test_required_scopes_from_server(self):
+        verifier = StaticTokenVerifier(
+            tokens={"t": {"client_id": "c", "scopes": ["read"]}},
+            required_scopes=["read"],
+        )
+        provider = RemoteAuthProvider(
+            token_verifier=verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+        auth = MultiAuth(server=provider)
+        assert auth.required_scopes == ["read"]
+
+
+class TestMultiAuthVerifyToken:
+    """Test MultiAuth token verification chain."""
+
+    async def test_server_verified_first(self):
+        """Server's verify_token is tried before verifiers."""
+        server_verifier = StaticTokenVerifier(
+            tokens={"server_token": {"client_id": "server-client", "scopes": []}}
+        )
+        server = RemoteAuthProvider(
+            token_verifier=server_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+        extra = StaticTokenVerifier(
+            tokens={"extra_token": {"client_id": "extra-client", "scopes": []}}
+        )
+
+        auth = MultiAuth(server=server, verifiers=[extra])
+
+        result = await auth.verify_token("server_token")
+        assert result is not None
+        assert result.client_id == "server-client"
+
+    async def test_falls_back_to_verifiers(self):
+        """When server rejects a token, verifiers are tried."""
+        server_verifier = StaticTokenVerifier(
+            tokens={"server_token": {"client_id": "server-client", "scopes": []}}
+        )
+        server = RemoteAuthProvider(
+            token_verifier=server_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+        extra = StaticTokenVerifier(
+            tokens={"m2m_token": {"client_id": "m2m-service", "scopes": []}}
+        )
+
+        auth = MultiAuth(server=server, verifiers=[extra])
+
+        result = await auth.verify_token("m2m_token")
+        assert result is not None
+        assert result.client_id == "m2m-service"
+
+    async def test_verifier_order_matters(self):
+        """Verifiers are tried in order; first match wins."""
+        v1 = StaticTokenVerifier(
+            tokens={"shared_token": {"client_id": "first", "scopes": []}}
+        )
+        v2 = StaticTokenVerifier(
+            tokens={"shared_token": {"client_id": "second", "scopes": []}}
+        )
+
+        auth = MultiAuth(verifiers=[v1, v2])
+        result = await auth.verify_token("shared_token")
+        assert result is not None
+        assert result.client_id == "first"
+
+    async def test_no_match_returns_none(self):
+        """When no server or verifier accepts the token, returns None."""
+        v = StaticTokenVerifier(tokens={"known": {"client_id": "c", "scopes": []}})
+        auth = MultiAuth(verifiers=[v])
+        result = await auth.verify_token("unknown")
+        assert result is None
+
+    async def test_verifiers_only_no_server(self):
+        """MultiAuth with only verifiers (no server) works."""
+        v1 = StaticTokenVerifier(tokens={"token_a": {"client_id": "a", "scopes": []}})
+        v2 = StaticTokenVerifier(tokens={"token_b": {"client_id": "b", "scopes": []}})
+
+        auth = MultiAuth(verifiers=[v1, v2])
+
+        result_a = await auth.verify_token("token_a")
+        assert result_a is not None
+        assert result_a.client_id == "a"
+
+        result_b = await auth.verify_token("token_b")
+        assert result_b is not None
+        assert result_b.client_id == "b"
+
+    async def test_raising_verifier_does_not_break_chain(self):
+        """If a verifier raises, the chain continues to the next source."""
+        good = StaticTokenVerifier(
+            tokens={"valid": {"client_id": "good-client", "scopes": []}}
+        )
+        auth = MultiAuth(verifiers=[RaisingVerifier(), good])
+
+        result = await auth.verify_token("valid")
+        assert result is not None
+        assert result.client_id == "good-client"
+
+    async def test_raising_server_does_not_break_chain(self):
+        """If the server raises, verifiers are still tried."""
+        good = StaticTokenVerifier(
+            tokens={"valid": {"client_id": "fallback", "scopes": []}}
+        )
+        auth = MultiAuth(server=RaisingVerifier(), verifiers=[good])
+
+        result = await auth.verify_token("valid")
+        assert result is not None
+        assert result.client_id == "fallback"
+
+    async def test_all_raising_returns_none(self):
+        """If every source raises, verify_token returns None."""
+        auth = MultiAuth(verifiers=[RaisingVerifier(), RaisingVerifier()])
+        result = await auth.verify_token("anything")
+        assert result is None
+
+    async def test_server_match_short_circuits(self):
+        """When the server matches, verifiers are not consulted."""
+        # Both server and verifier know the same token with different client_ids
+        server_verifier = StaticTokenVerifier(
+            tokens={"token": {"client_id": "from-server", "scopes": []}}
+        )
+        server = RemoteAuthProvider(
+            token_verifier=server_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+        extra = StaticTokenVerifier(
+            tokens={"token": {"client_id": "from-verifier", "scopes": []}}
+        )
+
+        auth = MultiAuth(server=server, verifiers=[extra])
+        result = await auth.verify_token("token")
+        assert result is not None
+        assert result.client_id == "from-server"
+
+
+class TestMultiAuthRoutes:
+    """Test that routes delegate to the server."""
+
+    def test_routes_from_server(self):
+        verifier = StaticTokenVerifier(tokens={"t": {"client_id": "c", "scopes": []}})
+        server = RemoteAuthProvider(
+            token_verifier=verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+        auth = MultiAuth(server=server)
+        routes = auth.get_routes(mcp_path="/mcp")
+        # RemoteAuthProvider creates a protected resource metadata route
+        assert len(routes) >= 1
+
+    def test_no_routes_without_server(self):
+        v = StaticTokenVerifier(tokens={"t": {"client_id": "c", "scopes": []}})
+        auth = MultiAuth(verifiers=[v])
+        assert auth.get_routes() == []
+
+    def test_well_known_routes_delegate_to_server(self):
+        """get_well_known_routes delegates to the server's implementation."""
+        verifier = StaticTokenVerifier(tokens={"t": {"client_id": "c", "scopes": []}})
+        server = RemoteAuthProvider(
+            token_verifier=verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+        auth = MultiAuth(server=server)
+        well_known = auth.get_well_known_routes(mcp_path="/mcp")
+        server_well_known = server.get_well_known_routes(mcp_path="/mcp")
+        # MultiAuth should produce the same well-known routes as the server
+        assert len(well_known) == len(server_well_known)
+        assert [r.path for r in well_known] == [r.path for r in server_well_known]
+
+    def test_well_known_routes_empty_without_server(self):
+        v = StaticTokenVerifier(tokens={"t": {"client_id": "c", "scopes": []}})
+        auth = MultiAuth(verifiers=[v])
+        assert auth.get_well_known_routes() == []
+
+    def test_required_scopes_explicit_empty_list(self):
+        """Passing required_scopes=[] explicitly clears inherited scopes."""
+        verifier = StaticTokenVerifier(
+            tokens={"t": {"client_id": "c", "scopes": ["read"]}},
+            required_scopes=["read"],
+        )
+        server = RemoteAuthProvider(
+            token_verifier=verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+        # Server has required_scopes=["read"], but we explicitly clear them
+        auth = MultiAuth(server=server, required_scopes=[])
+        assert auth.required_scopes == []
+
+
+class TestMultiAuthIntegration:
+    """Integration tests: MultiAuth with a real FastMCP HTTP app."""
+
+    async def test_multi_auth_rejects_bad_tokens(self):
+        """End-to-end: MultiAuth rejects unknown tokens at the HTTP layer."""
+        oauth_tokens = StaticTokenVerifier(
+            tokens={
+                "oauth_token": {
+                    "client_id": "interactive-client",
+                    "scopes": ["read"],
+                }
+            }
+        )
+        m2m_tokens = StaticTokenVerifier(
+            tokens={
+                "m2m_token": {
+                    "client_id": "backend-service",
+                    "scopes": ["read"],
+                }
+            }
+        )
+
+        auth = MultiAuth(verifiers=[oauth_tokens, m2m_tokens])
+        mcp = FastMCP("test", auth=auth)
+        app = mcp.http_app(path="/mcp")
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=app),
+            base_url="http://localhost",
+        ) as client:
+            # No token → 401
+            response = await client.get("/mcp")
+            assert response.status_code == 401
+
+            # Bad token → 401
+            response = await client.get(
+                "/mcp", headers={"Authorization": "Bearer bad_token"}
+            )
+            assert response.status_code == 401
+
+    async def test_multi_auth_with_server_provides_routes(self):
+        """MultiAuth with a server exposes the server's metadata routes."""
+        verifier = StaticTokenVerifier(tokens={"t": {"client_id": "c", "scopes": []}})
+        server = RemoteAuthProvider(
+            token_verifier=verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+        extra = StaticTokenVerifier(tokens={"m2m": {"client_id": "svc", "scopes": []}})
+
+        auth = MultiAuth(server=server, verifiers=[extra])
+        mcp = FastMCP("test", auth=auth)
+        app = mcp.http_app(path="/mcp")
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=app),
+            base_url="https://api.example.com",
+        ) as client:
+            # Protected resource metadata should be available
+            response = await client.get("/.well-known/oauth-protected-resource/mcp")
+            assert response.status_code == 200
+            data = response.json()
+            assert data["resource"] == "https://api.example.com/mcp"
+
+    async def test_multi_auth_uses_server_resource_base_url_in_auth_challenge(self):
+        """Auth challenges should advertise resource metadata from resource_base_url."""
+        verifier = StaticTokenVerifier(tokens={"t": {"client_id": "c", "scopes": []}})
+        server = RemoteAuthProvider(
+            token_verifier=verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://auth.example.com/proxy",
+            resource_base_url="https://api.example.com",
+        )
+
+        auth = MultiAuth(server=server)
+        mcp = FastMCP("test", auth=auth)
+        app = mcp.http_app(path="/mcp")
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=app),
+            base_url="http://localhost",
+        ) as client:
+            response = await client.get("/mcp")
+            assert response.status_code == 401
+            assert (
+                'resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp"'
+                in response.headers["www-authenticate"]
+            )
+
+    async def test_multi_auth_override_propagates_to_served_metadata(self):
+        """Override on MultiAuth must propagate so served metadata matches the challenge."""
+        verifier = StaticTokenVerifier(tokens={"t": {"client_id": "c", "scopes": []}})
+        server = RemoteAuthProvider(
+            token_verifier=verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://auth.example.com/proxy",
+        )
+
+        auth = MultiAuth(server=server, resource_base_url="https://api.example.com")
+        mcp = FastMCP("test", auth=auth)
+        app = mcp.http_app(path="/mcp")
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=app),
+            base_url="http://localhost",
+        ) as client:
+            response = await client.get("/mcp")
+            assert response.status_code == 401
+            assert (
+                'resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp"'
+                in response.headers["www-authenticate"]
+            )
+
+            metadata_response = await client.get(
+                "/.well-known/oauth-protected-resource/mcp"
+            )
+            assert metadata_response.status_code == 200
+            assert metadata_response.json()["resource"] == "https://api.example.com/mcp"
+            old_path_response = await client.get(
+                "/.well-known/oauth-protected-resource/proxy/mcp"
+            )
+            assert old_path_response.status_code == 404
+
+    async def test_multi_auth_accepts_valid_verifier_token(self):
+        """MultiAuth accepts tokens from verifiers (not just the server).
+
+        Verifies that both server and verifier tokens pass the HTTP auth
+        middleware. We use GET /mcp to check: 401 means auth rejected,
+        any other status means auth accepted and the request reached the
+        MCP session layer.
+        """
+        interactive_tokens = StaticTokenVerifier(
+            tokens={
+                "interactive_token": {
+                    "client_id": "interactive-client",
+                    "scopes": [],
+                }
+            }
+        )
+        m2m_tokens = StaticTokenVerifier(
+            tokens={
+                "m2m_token": {
+                    "client_id": "backend-service",
+                    "scopes": [],
+                }
+            }
+        )
+
+        auth = MultiAuth(verifiers=[interactive_tokens, m2m_tokens])
+        mcp = FastMCP("test", auth=auth)
+        app = mcp.http_app(path="/mcp")
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=app, raise_app_exceptions=False),
+            base_url="http://localhost",
+        ) as client:
+            # No token → 401
+            response = await client.get("/mcp")
+            assert response.status_code == 401
+
+            # Interactive token passes auth (non-401 means auth accepted)
+            response = await client.get(
+                "/mcp", headers={"Authorization": "Bearer interactive_token"}
+            )
+            assert response.status_code != 401
+
+            # M2M token also passes auth
+            response = await client.get(
+                "/mcp", headers={"Authorization": "Bearer m2m_token"}
+            )
+            assert response.status_code != 401
+
+            # Bad token → 401
+            response = await client.get(
+                "/mcp", headers={"Authorization": "Bearer bad_token"}
+            )
+            assert response.status_code == 401
+
+
+class TestMultiAuthSetMcpPath:
+    """Test that set_mcp_path propagates to server and verifiers."""
+
+    def test_propagates_to_server(self):
+        verifier = StaticTokenVerifier(tokens={"t": {"client_id": "c", "scopes": []}})
+        server = RemoteAuthProvider(
+            token_verifier=verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+        auth = MultiAuth(server=server)
+        auth.set_mcp_path("/mcp")
+        assert server._mcp_path == "/mcp"
+
+    def test_propagates_to_verifiers(self):
+        v1 = StaticTokenVerifier(tokens={"t": {"client_id": "c", "scopes": []}})
+        v2 = StaticTokenVerifier(tokens={"t2": {"client_id": "c2", "scopes": []}})
+        auth = MultiAuth(verifiers=[v1, v2])
+        auth.set_mcp_path("/mcp")
+        assert v1._mcp_path == "/mcp"
+        assert v2._mcp_path == "/mcp"
diff --git a/tests/server/auth/test_oauth_consent_flow.py b/tests/server/auth/test_oauth_consent_flow.py
new file mode 100644
index 0000000..ed756c0
--- /dev/null
+++ b/tests/server/auth/test_oauth_consent_flow.py
@@ -0,0 +1,895 @@
+"""Tests for OAuth Proxy consent flow with server-side storage.
+
+This test suite verifies:
+1. OAuth transactions are stored in server-side storage (not in-memory)
+2. Authorization codes are stored in server-side storage
+3. Consent flow redirects correctly through /consent endpoint
+4. CSRF protection works with cookies
+5. State persists across storage backends
+6. Security headers (X-Frame-Options) are set correctly
+7. Cookie signing and tampering detection
+8. Auto-approve behavior with valid cookies
+9. Consent binding cookie prevents confused deputy attacks (GHSA-rww4-4w9c-7733)
+"""
+
+import re
+import secrets
+import time
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+from key_value.aio.stores.memory import MemoryStore
+from mcp.server.auth.provider import AuthorizationParams
+from mcp.shared.auth import OAuthClientInformationFull
+from pydantic import AnyUrl
+from starlette.applications import Starlette
+from starlette.testclient import TestClient
+
+from fastmcp.server.auth.auth import AccessToken, TokenVerifier
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.server.auth.oauth_proxy.models import OAuthTransaction
+
+
+class MockTokenVerifier(TokenVerifier):
+    """Mock token verifier for testing."""
+
+    def __init__(self):
+        self.required_scopes = ["read", "write"]
+
+    async def verify_token(self, token: str):
+        """Mock token verification."""
+        return AccessToken(
+            token=token,
+            client_id="mock-client",
+            scopes=self.required_scopes,
+            expires_at=int(time.time() + 3600),
+        )
+
+
+class _Verifier(TokenVerifier):
+    """Minimal token verifier for security tests."""
+
+    def __init__(self):
+        self.required_scopes = ["read"]
+
+    async def verify_token(self, token: str):
+        return AccessToken(
+            token=token, client_id="c", scopes=self.required_scopes, expires_at=None
+        )
+
+
+@pytest.fixture
+def storage():
+    """Create a fresh in-memory storage for each test."""
+    return MemoryStore()
+
+
+@pytest.fixture
+def oauth_proxy_with_storage(storage):
+    """Create OAuth proxy with explicit storage backend."""
+    return OAuthProxy(
+        upstream_authorization_endpoint="https://github.com/login/oauth/authorize",
+        upstream_token_endpoint="https://github.com/login/oauth/access_token",
+        upstream_client_id="test-upstream-client",
+        upstream_client_secret="test-upstream-secret",
+        token_verifier=MockTokenVerifier(),
+        base_url="https://myserver.com",
+        redirect_path="/auth/callback",
+        client_storage=storage,  # Use our test storage
+        jwt_signing_key="test-secret",
+    )
+
+
+@pytest.fixture
+def oauth_proxy_https():
+    """OAuthProxy configured with HTTPS base_url for __Host- cookies."""
+    return OAuthProxy(
+        upstream_authorization_endpoint="https://github.com/login/oauth/authorize",
+        upstream_token_endpoint="https://github.com/login/oauth/access_token",
+        upstream_client_id="client-id",
+        upstream_client_secret="client-secret",
+        token_verifier=_Verifier(),
+        base_url="https://myserver.example",
+        client_storage=MemoryStore(),
+        jwt_signing_key="test-secret",
+    )
+
+
+@pytest.fixture
+def oauth_proxy_https_remember():
+    """OAuthProxy in 'remember' mode for silent-consent cookie tests."""
+    return OAuthProxy(
+        upstream_authorization_endpoint="https://github.com/login/oauth/authorize",
+        upstream_token_endpoint="https://github.com/login/oauth/access_token",
+        upstream_client_id="client-id",
+        upstream_client_secret="client-secret",
+        token_verifier=_Verifier(),
+        base_url="https://myserver.example",
+        client_storage=MemoryStore(),
+        jwt_signing_key="test-secret",
+        require_authorization_consent="remember",
+    )
+
+
+async def _start_flow(
+    proxy: OAuthProxy, client_id: str, redirect: str
+) -> tuple[str, str]:
+    """Register client and start auth; returns (txn_id, consent_url)."""
+    await proxy.register_client(
+        OAuthClientInformationFull(
+            client_id=client_id,
+            client_secret="s",
+            redirect_uris=[AnyUrl(redirect)],
+        )
+    )
+    params = AuthorizationParams(
+        redirect_uri=AnyUrl(redirect),
+        redirect_uri_provided_explicitly=True,
+        state="client-state-xyz",
+        code_challenge="challenge",
+        scopes=["read"],
+    )
+    consent_url = await proxy.authorize(
+        OAuthClientInformationFull(
+            client_id=client_id,
+            client_secret="s",
+            redirect_uris=[AnyUrl(redirect)],
+        ),
+        params,
+    )
+    qs = parse_qs(urlparse(consent_url).query)
+    return qs["txn_id"][0], consent_url
+
+
+def _extract_csrf(html: str) -> str | None:
+    """Extract CSRF token from HTML form."""
+    m = re.search(r"name=\"csrf_token\"\s+value=\"([^\"]+)\"", html)
+    return m.group(1) if m else None
+
+
+class TestServerSideStorage:
+    """Tests verifying OAuth state is stored in AsyncKeyValue storage."""
+
+    async def test_transaction_stored_in_storage_not_memory(
+        self, oauth_proxy_with_storage, storage
+    ):
+        """Verify OAuth transactions are stored in AsyncKeyValue, not in-memory dict."""
+        # Register client
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:54321/callback")],
+        )
+        await oauth_proxy_with_storage.register_client(client)
+
+        # Start authorization flow
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:54321/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="client-state-123",
+            code_challenge="challenge-abc",
+            scopes=["read", "write"],
+        )
+
+        redirect_url = await oauth_proxy_with_storage.authorize(client, params)
+
+        # Extract transaction ID from consent redirect
+        parsed = urlparse(redirect_url)
+        assert "/consent" in parsed.path, "Should redirect to consent page"
+
+        query_params = parse_qs(parsed.query)
+        txn_id = query_params["txn_id"][0]
+
+        # Verify transaction is NOT in the old in-memory dict
+        # (the attribute should not exist or should be empty)
+        assert (
+            not hasattr(oauth_proxy_with_storage, "_oauth_transactions")
+            or len(getattr(oauth_proxy_with_storage, "_oauth_transactions", {})) == 0
+        )
+
+        # Verify transaction IS in storage backend
+        transaction = await storage.get(collection="mcp-oauth-transactions", key=txn_id)
+        assert transaction is not None, "Transaction should be in storage"
+
+        # Verify transaction has expected structure
+        assert transaction["client_id"] == "test-client"
+        assert transaction["client_redirect_uri"] == "http://localhost:54321/callback"
+        assert transaction["client_state"] == "client-state-123"
+        assert transaction["code_challenge"] == "challenge-abc"
+        assert transaction["scopes"] == ["read", "write"]
+
+    async def test_authorization_code_stored_in_storage(
+        self, oauth_proxy_with_storage, storage
+    ):
+        """Verify authorization codes are stored in AsyncKeyValue storage."""
+        # Register client
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:54321/callback")],
+        )
+        await oauth_proxy_with_storage.register_client(client)
+
+        # Create a test app with OAuth routes
+        app = Starlette(routes=oauth_proxy_with_storage.get_routes())
+
+        with TestClient(app) as test_client:
+            # Start authorization flow
+            params = AuthorizationParams(
+                redirect_uri=AnyUrl("http://localhost:54321/callback"),
+                redirect_uri_provided_explicitly=True,
+                state="client-state",
+                code_challenge="challenge-xyz",
+                scopes=["read"],
+            )
+
+            redirect_url = await oauth_proxy_with_storage.authorize(client, params)
+
+            # Extract txn_id from consent redirect
+            parsed = urlparse(redirect_url)
+            query_params = parse_qs(parsed.query)
+            txn_id = query_params["txn_id"][0]
+
+            # Simulate consent approval
+            # First, get the consent page to establish CSRF cookie
+            consent_response = test_client.get(
+                f"/consent?txn_id={txn_id}", follow_redirects=False
+            )
+
+            # Extract CSRF token from response (it's in the HTML form)
+            csrf_token = None
+            if consent_response.status_code == 200:
+                # For this test, we'll generate a CSRF token manually
+                # In production, this comes from the consent page HTML
+                csrf_token = secrets.token_urlsafe(32)
+
+            # Approve consent with CSRF token
+            # Set cookies on client instance to avoid deprecation warning
+            for k, v in consent_response.cookies.items():
+                test_client.cookies.set(k, v)
+            approval_response = test_client.post(
+                "/consent",
+                data={
+                    "action": "approve",
+                    "txn_id": txn_id,
+                    "csrf_token": csrf_token if csrf_token else "",
+                },
+                follow_redirects=False,
+            )
+
+            # After approval, authorization code should be in storage
+            # The code is returned in the redirect URL
+            if approval_response.status_code in (302, 303):
+                location = approval_response.headers.get("location", "")
+                callback_params = parse_qs(urlparse(location).query)
+
+                if "code" in callback_params:
+                    auth_code = callback_params["code"][0]
+
+                    # Verify code is NOT in old in-memory dict
+                    assert (
+                        not hasattr(oauth_proxy_with_storage, "_client_codes")
+                        or len(getattr(oauth_proxy_with_storage, "_client_codes", {}))
+                        == 0
+                    )
+
+                    # Verify code IS in storage
+                    code_data = await storage.get(
+                        collection="mcp-authorization-codes", key=auth_code
+                    )
+                    assert code_data is not None, (
+                        "Authorization code should be in storage"
+                    )
+                    assert code_data["client_id"] == "test-client"
+                    assert code_data["scopes"] == ["read"]
+
+    async def test_storage_collections_are_isolated(self, oauth_proxy_with_storage):
+        """Verify that transactions, codes, and clients use separate collections."""
+        # Register a client
+        client = OAuthClientInformationFull(
+            client_id="isolation-test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+        await oauth_proxy_with_storage.register_client(client)
+
+        # Start authorization to create transaction
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:12345/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="test-state",
+            code_challenge="test-challenge",
+            scopes=["read"],
+        )
+
+        await oauth_proxy_with_storage.authorize(client, params)
+
+        # Get all collections from storage
+        storage = oauth_proxy_with_storage._client_storage
+
+        # Verify client is in client collection
+        client_data = await storage.get(
+            collection="mcp-oauth-proxy-clients", key="isolation-test-client"
+        )
+        assert client_data is not None
+
+        # Verify we can list transactions separately
+        # (This tests that collections are properly namespaced)
+        transactions = await storage.keys(collection="mcp-oauth-transactions")
+
+        assert len(transactions) > 0, "Should have at least one transaction"
+
+        # Verify transaction keys don't collide with client keys
+        for txn_key in transactions:
+            assert txn_key != "isolation-test-client"
+
+
+class TestConsentFlowRedirects:
+    """Tests for consent flow redirect behavior."""
+
+    async def test_authorize_redirects_to_consent_page(self, oauth_proxy_with_storage):
+        """Verify authorize() redirects to /consent instead of upstream."""
+        client = OAuthClientInformationFull(
+            client_id="consent-test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:8080/callback")],
+        )
+        await oauth_proxy_with_storage.register_client(client)
+
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:8080/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="test-state",
+            code_challenge="",
+            scopes=["read"],
+        )
+
+        redirect_url = await oauth_proxy_with_storage.authorize(client, params)
+
+        # Should redirect to consent page, not upstream
+        assert "/consent" in redirect_url
+        assert "github.com" not in redirect_url
+        assert "?txn_id=" in redirect_url
+
+    async def test_consent_page_contains_transaction_id(self, oauth_proxy_with_storage):
+        """Verify consent page receives and displays transaction ID."""
+        client = OAuthClientInformationFull(
+            client_id="txn-test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:9090/callback")],
+        )
+        await oauth_proxy_with_storage.register_client(client)
+
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:9090/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="test-state",
+            code_challenge="test-challenge",
+            scopes=["read", "write"],
+        )
+
+        redirect_url = await oauth_proxy_with_storage.authorize(client, params)
+
+        # Extract txn_id parameter
+        parsed = urlparse(redirect_url)
+        query = parse_qs(parsed.query)
+
+        assert "txn_id" in query
+        txn_id = query["txn_id"][0]
+        assert len(txn_id) > 0
+
+        # Create test client
+        app = Starlette(routes=oauth_proxy_with_storage.get_routes())
+
+        with TestClient(app) as test_client:
+            # Request consent page
+            response = test_client.get(
+                f"/consent?txn_id={txn_id}", follow_redirects=False
+            )
+
+            assert response.status_code == 200
+            # Consent page should contain transaction reference
+            assert txn_id.encode() in response.content or b"consent" in response.content
+
+
+class TestCSRFProtection:
+    """Tests for CSRF protection in consent flow."""
+
+    async def test_consent_requires_csrf_token(self, oauth_proxy_with_storage):
+        """Verify consent submission requires valid CSRF token."""
+        client = OAuthClientInformationFull(
+            client_id="csrf-test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:7070/callback")],
+        )
+        await oauth_proxy_with_storage.register_client(client)
+
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:7070/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="test-state",
+            code_challenge="",
+            scopes=["read"],
+        )
+
+        redirect_url = await oauth_proxy_with_storage.authorize(client, params)
+        parsed = urlparse(redirect_url)
+        query = parse_qs(parsed.query)
+        txn_id = query["txn_id"][0]
+
+        app = Starlette(routes=oauth_proxy_with_storage.get_routes())
+
+        with TestClient(app) as test_client:
+            # Try to submit consent WITHOUT CSRF token
+            response = test_client.post(
+                "/consent",
+                data={"action": "approve", "txn_id": txn_id},
+                # No CSRF token!
+                follow_redirects=False,
+            )
+
+            # Should reject or require CSRF
+            # (Implementation may vary - checking for error response)
+            assert response.status_code in (
+                400,
+                403,
+                302,
+            )  # Error or redirect to error
+
+    async def test_consent_cookie_established_on_page_visit(
+        self, oauth_proxy_with_storage
+    ):
+        """Verify consent page establishes CSRF cookie."""
+        client = OAuthClientInformationFull(
+            client_id="cookie-test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:6060/callback")],
+        )
+        await oauth_proxy_with_storage.register_client(client)
+
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:6060/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="test-state",
+            code_challenge="",
+            scopes=["read"],
+        )
+
+        redirect_url = await oauth_proxy_with_storage.authorize(client, params)
+        parsed = urlparse(redirect_url)
+        query = parse_qs(parsed.query)
+        txn_id = query["txn_id"][0]
+
+        app = Starlette(routes=oauth_proxy_with_storage.get_routes())
+
+        with TestClient(app) as test_client:
+            # Visit consent page
+            response = test_client.get(
+                f"/consent?txn_id={txn_id}", follow_redirects=False
+            )
+
+            # Should set cookies for CSRF protection
+            assert response.status_code == 200
+            # Cookie may be set via Set-Cookie header
+            cookies = response.cookies
+            # Look for any CSRF-related cookie (implementation dependent)
+            assert len(cookies) > 0 or "csrf" in response.text.lower(), (
+                "Consent page should establish CSRF protection"
+            )
+
+
+class TestCSRFDoubleSubmit:
+    """Tests for CSRF double-submit cookie validation (GHSA-rww4-4w9c-7733 bypass)."""
+
+    async def test_consent_rejected_without_csrf_cookie(self, oauth_proxy_with_storage):
+        """Submitting a valid CSRF token without the matching cookie should be rejected.
+
+        This prevents an attacker from using their own tx_id/csrf_token to CSRF
+        the victim's browser into approving consent.
+        """
+        txn_id, _ = await _start_flow(
+            oauth_proxy_with_storage,
+            "csrf-double-submit-client",
+            "http://localhost:9090/callback",
+        )
+
+        app = Starlette(routes=oauth_proxy_with_storage.get_routes())
+        with TestClient(app) as test_client:
+            # Visit consent page to populate the transaction with a CSRF token
+            consent_resp = test_client.get(f"/consent?txn_id={txn_id}")
+            assert consent_resp.status_code == 200
+            csrf_token = _extract_csrf(consent_resp.text)
+            assert csrf_token
+
+        # Simulate the attack: use a FRESH client (no cookies from the consent
+        # page) to submit the form with a valid CSRF token — as if the attacker
+        # tricked the victim's browser into POSTing their tx_id/csrf_token.
+        with TestClient(app) as attacker_client:
+            response = attacker_client.post(
+                "/consent",
+                data={
+                    "action": "approve",
+                    "txn_id": txn_id,
+                    "csrf_token": csrf_token,
+                },
+                follow_redirects=False,
+            )
+            assert response.status_code == 403
+
+
+class TestStoragePersistence:
+    """Tests for state persistence across storage backends."""
+
+    async def test_transaction_persists_after_retrieval(self, oauth_proxy_with_storage):
+        """Verify transaction can be retrieved multiple times (until deleted)."""
+        client = OAuthClientInformationFull(
+            client_id="persist-test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:5050/callback")],
+        )
+        await oauth_proxy_with_storage.register_client(client)
+
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:5050/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="persist-state",
+            code_challenge="persist-challenge",
+            scopes=["read"],
+        )
+
+        redirect_url = await oauth_proxy_with_storage.authorize(client, params)
+        parsed = urlparse(redirect_url)
+        query = parse_qs(parsed.query)
+        txn_id = query["txn_id"][0]
+
+        storage = oauth_proxy_with_storage._client_storage
+
+        # Retrieve transaction multiple times
+        txn1 = await storage.get(collection="mcp-oauth-transactions", key=txn_id)
+        assert txn1 is not None
+
+        txn2 = await storage.get(collection="mcp-oauth-transactions", key=txn_id)
+        assert txn2 is not None
+
+        # Should be the same data
+        assert txn1["client_id"] == txn2["client_id"]
+        assert txn1["client_state"] == txn2["client_state"]
+
+    async def test_storage_uses_pydantic_adapter(self, oauth_proxy_with_storage):
+        """Verify that PydanticAdapter serializes/deserializes correctly."""
+        client = OAuthClientInformationFull(
+            client_id="pydantic-test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:4040/callback")],
+        )
+        await oauth_proxy_with_storage.register_client(client)
+
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl("http://localhost:4040/callback"),
+            redirect_uri_provided_explicitly=True,
+            state="pydantic-state",
+            code_challenge="pydantic-challenge",
+            scopes=["read", "write"],
+        )
+
+        redirect_url = await oauth_proxy_with_storage.authorize(client, params)
+        parsed = urlparse(redirect_url)
+        query = parse_qs(parsed.query)
+        txn_id = query["txn_id"][0]
+
+        # Retrieve using PydanticAdapter (which is what the proxy uses)
+        transaction_store = oauth_proxy_with_storage._transaction_store
+        txn_model = await transaction_store.get(key=txn_id)
+
+        # Should be a Pydantic model instance
+        assert isinstance(txn_model, OAuthTransaction)
+        assert txn_model.client_id == "pydantic-test-client"
+        assert txn_model.client_state == "pydantic-state"
+        assert txn_model.code_challenge == "pydantic-challenge"
+        assert txn_model.scopes == ["read", "write"]
+
+
+class TestConsentSecurity:
+    """Tests for consent page security features."""
+
+    async def test_consent_sets_xfo_header(self, oauth_proxy_https):
+        """Verify consent page sets X-Frame-Options header to prevent clickjacking."""
+        txn_id, _ = await _start_flow(
+            oauth_proxy_https, "client-a", "http://localhost:5001/callback"
+        )
+        app = Starlette(routes=oauth_proxy_https.get_routes())
+        with TestClient(app) as c:
+            r = c.get(f"/consent?txn_id={txn_id}")
+            assert r.status_code == 200
+            assert r.headers.get("X-Frame-Options") == "DENY"
+
+    async def test_deny_sets_cookie_and_redirects_with_error(
+        self, oauth_proxy_https_remember
+    ):
+        """Verify denying consent in 'remember' mode sets signed cookie and redirects with error."""
+        client_redirect = "http://localhost:5002/callback"
+        txn_id, _ = await _start_flow(
+            oauth_proxy_https_remember, "client-b", client_redirect
+        )
+        app = Starlette(routes=oauth_proxy_https_remember.get_routes())
+        with TestClient(app) as c:
+            consent = c.get(f"/consent?txn_id={txn_id}")
+            csrf = _extract_csrf(consent.text)
+            assert csrf
+            # Persist consent page cookies on client instance to avoid per-request deprecation
+            for k, v in consent.cookies.items():
+                c.cookies.set(k, v)
+            r = c.post(
+                "/consent",
+                data={"action": "deny", "txn_id": txn_id, "csrf_token": csrf},
+                follow_redirects=False,
+            )
+            assert r.status_code in (302, 303)
+            loc = r.headers.get("location", "")
+            parsed = urlparse(loc)
+            assert parsed.scheme == "http" and parsed.netloc.startswith("localhost")
+            q = parse_qs(parsed.query)
+            assert q.get("error") == ["access_denied"]
+            assert q.get("state") == ["client-state-xyz"]
+            # Signed denied cookie should be set
+            assert "MCP_DENIED_CLIENTS" in ";\n".join(
+                r.headers.get("set-cookie", "").splitlines()
+            )
+
+    async def test_approve_sets_cookie_and_redirects_to_upstream(
+        self, oauth_proxy_https_remember
+    ):
+        """Verify approving consent in 'remember' mode sets signed cookie and redirects to upstream."""
+        txn_id, _ = await _start_flow(
+            oauth_proxy_https_remember, "client-c", "http://localhost:5003/callback"
+        )
+        app = Starlette(routes=oauth_proxy_https_remember.get_routes())
+        with TestClient(app) as c:
+            consent = c.get(f"/consent?txn_id={txn_id}")
+            csrf = _extract_csrf(consent.text)
+            assert csrf
+            for k, v in consent.cookies.items():
+                c.cookies.set(k, v)
+            r = c.post(
+                "/consent",
+                data={"action": "approve", "txn_id": txn_id, "csrf_token": csrf},
+                follow_redirects=False,
+            )
+            assert r.status_code in (302, 303)
+            loc = r.headers.get("location", "")
+            assert loc.startswith("https://github.com/login/oauth/authorize")
+            assert f"state={txn_id}" in loc
+            # Signed approved cookie should be set with __Host- prefix for HTTPS
+            set_cookie = ";\n".join(r.headers.get("set-cookie", "").splitlines())
+            assert "__Host-MCP_APPROVED_CLIENTS" in set_cookie
+
+    async def test_tampered_cookie_is_ignored(self, oauth_proxy_https_remember):
+        """Verify tampered approval cookie is ignored and consent page shown."""
+        txn_id, _ = await _start_flow(
+            oauth_proxy_https_remember, "client-d", "http://localhost:5004/callback"
+        )
+        app = Starlette(routes=oauth_proxy_https_remember.get_routes())
+        with TestClient(app) as c:
+            # Create a tampered cookie (invalid signature)
+            # Value format: payload.signature; using wrong signature to force failure
+            tampered_value = "W10=.invalidsig"
+            c.cookies.set("__Host-MCP_APPROVED_CLIENTS", tampered_value)
+            r = c.get(
+                f"/consent?txn_id={txn_id}",
+                headers={"Sec-Fetch-Site": "none"},
+                follow_redirects=False,
+            )
+            # Should not auto-redirect to upstream; should show consent page
+            assert r.status_code == 200
+            # httpx returns a URL object; compare path or stringify
+            assert urlparse(str(r.request.url)).path == "/consent"
+
+    async def test_autoapprove_cookie_skips_consent(self, oauth_proxy_https_remember):
+        """Verify valid approval cookie auto-approves and redirects to upstream in 'remember' mode."""
+        client_id = "client-e"
+        redirect = "http://localhost:5005/callback"
+        txn_id, _ = await _start_flow(oauth_proxy_https_remember, client_id, redirect)
+        app = Starlette(routes=oauth_proxy_https_remember.get_routes())
+        with TestClient(app) as c:
+            # Approve once to set approved cookie
+            consent = c.get(f"/consent?txn_id={txn_id}")
+            csrf = _extract_csrf(consent.text)
+            for k, v in consent.cookies.items():
+                c.cookies.set(k, v)
+            r = c.post(
+                "/consent",
+                data={
+                    "action": "approve",
+                    "txn_id": txn_id,
+                    "csrf_token": csrf if csrf else "",
+                },
+                follow_redirects=False,
+            )
+            # Extract approved cookie value
+            set_cookie = ";\n".join(r.headers.get("set-cookie", "").splitlines())
+            m = re.search(r"__Host-MCP_APPROVED_CLIENTS=([^;]+)", set_cookie)
+            assert m, "approved cookie should be set in 'remember' mode"
+            approved_cookie = m.group(1)
+
+            # Start a new flow for the same client and redirect
+            new_txn, _ = await _start_flow(
+                oauth_proxy_https_remember, client_id, redirect
+            )
+            # Should auto-redirect to upstream when visiting consent due to cookie
+            # (requires a safe Sec-Fetch-Site value — "none" simulates a direct
+            # client-initiated navigation like an MCP host opening the browser).
+            c.cookies.set("__Host-MCP_APPROVED_CLIENTS", approved_cookie)
+            r2 = c.get(
+                f"/consent?txn_id={new_txn}",
+                headers={"Sec-Fetch-Site": "none"},
+                follow_redirects=False,
+            )
+            assert r2.status_code in (302, 303)
+            assert r2.headers.get("location", "").startswith(
+                "https://github.com/login/oauth/authorize"
+            )
+
+
+class TestConsentModes:
+    """Tests for the three consent modes: True (always), 'remember' (silent), 'external'.
+
+    Covers the default behavior where True no longer silently approves return
+    visits, and 'remember' mode gates silent consent on Sec-Fetch-Site to
+    block AS-in-the-middle attacks.
+    """
+
+    async def test_default_mode_does_not_set_approval_cookie(self, oauth_proxy_https):
+        """Approving in default (True) mode must NOT set a long-lived approval cookie.
+
+        In 'always prompt' mode there's no reason to remember approvals, and
+        writing the cookie would only create a no-op attack surface.
+        """
+        txn_id, _ = await _start_flow(
+            oauth_proxy_https, "client-default", "http://localhost:7001/callback"
+        )
+        app = Starlette(routes=oauth_proxy_https.get_routes())
+        with TestClient(app) as c:
+            consent = c.get(f"/consent?txn_id={txn_id}")
+            csrf = _extract_csrf(consent.text)
+            assert csrf
+            for k, v in consent.cookies.items():
+                c.cookies.set(k, v)
+            r = c.post(
+                "/consent",
+                data={"action": "approve", "txn_id": txn_id, "csrf_token": csrf},
+                follow_redirects=False,
+            )
+            assert r.status_code in (302, 303)
+            set_cookie = ";\n".join(r.headers.get("set-cookie", "").splitlines())
+            # Consent binding cookie still set for the in-flight transaction
+            assert "__Host-MCP_CONSENT_BINDING" in set_cookie
+            # But no remembered-approval cookie
+            assert "MCP_APPROVED_CLIENTS" not in set_cookie
+
+    async def test_default_mode_ignores_existing_approval_cookie(
+        self, oauth_proxy_https_remember, oauth_proxy_https
+    ):
+        """A valid approval cookie is ignored in default (True) mode — always prompts.
+
+        Uses the 'remember' proxy to generate a legitimately-signed cookie, then
+        replays it against a default-mode proxy (same jwt_signing_key) to confirm
+        the consent page is still shown.
+        """
+        # Both fixtures use the same signing key, so cookies generated by one
+        # verify against the other.
+        client_id = "client-xmode"
+        redirect = "http://localhost:7002/callback"
+        txn_id, _ = await _start_flow(oauth_proxy_https_remember, client_id, redirect)
+        app_remember = Starlette(routes=oauth_proxy_https_remember.get_routes())
+        with TestClient(app_remember) as c:
+            consent = c.get(f"/consent?txn_id={txn_id}")
+            csrf = _extract_csrf(consent.text)
+            assert csrf
+            for k, v in consent.cookies.items():
+                c.cookies.set(k, v)
+            r = c.post(
+                "/consent",
+                data={"action": "approve", "txn_id": txn_id, "csrf_token": csrf},
+                follow_redirects=False,
+            )
+            set_cookie_remember = ";\n".join(
+                r.headers.get("set-cookie", "").splitlines()
+            )
+            m = re.search(r"__Host-MCP_APPROVED_CLIENTS=([^;]+)", set_cookie_remember)
+            assert m, "remember-mode proxy should have set approval cookie"
+            approved_cookie = m.group(1)
+
+        # Now replay against the default-mode proxy for the same client/redirect.
+        new_txn, _ = await _start_flow(oauth_proxy_https, client_id, redirect)
+        app_default = Starlette(routes=oauth_proxy_https.get_routes())
+        with TestClient(app_default) as c:
+            c.cookies.set("__Host-MCP_APPROVED_CLIENTS", approved_cookie)
+            r = c.get(
+                f"/consent?txn_id={new_txn}",
+                headers={"Sec-Fetch-Site": "none"},
+                follow_redirects=False,
+            )
+            # Default mode: HTML consent page, no silent redirect to upstream.
+            assert r.status_code == 200
+            assert "text/html" in r.headers.get("content-type", "")
+
+    async def test_remember_mode_cross_site_forces_prompt(
+        self, oauth_proxy_https_remember
+    ):
+        """Sec-Fetch-Site=cross-site must skip silent consent even with valid cookie.
+
+        Blocks the AS-in-the-middle scenario: attacker redirects the victim's
+        browser to /authorize from a third-party origin, which browsers mark
+        cross-site. Legit local-host flows are Sec-Fetch-Site=none.
+        """
+        client_id = "client-cross"
+        redirect = "http://localhost:7003/callback"
+        txn_id, _ = await _start_flow(oauth_proxy_https_remember, client_id, redirect)
+        app = Starlette(routes=oauth_proxy_https_remember.get_routes())
+        with TestClient(app) as c:
+            # Seed a valid approval cookie via the normal consent flow.
+            consent = c.get(f"/consent?txn_id={txn_id}")
+            csrf = _extract_csrf(consent.text)
+            assert csrf
+            for k, v in consent.cookies.items():
+                c.cookies.set(k, v)
+            r = c.post(
+                "/consent",
+                data={"action": "approve", "txn_id": txn_id, "csrf_token": csrf},
+                follow_redirects=False,
+            )
+            set_cookie = ";\n".join(r.headers.get("set-cookie", "").splitlines())
+            m = re.search(r"__Host-MCP_APPROVED_CLIENTS=([^;]+)", set_cookie)
+            assert m
+            approved_cookie = m.group(1)
+
+            # Start a new flow and simulate a cross-site navigation.
+            new_txn, _ = await _start_flow(
+                oauth_proxy_https_remember, client_id, redirect
+            )
+            c.cookies.set("__Host-MCP_APPROVED_CLIENTS", approved_cookie)
+            r2 = c.get(
+                f"/consent?txn_id={new_txn}",
+                headers={"Sec-Fetch-Site": "cross-site"},
+                follow_redirects=False,
+            )
+            # Silent consent skipped; HTML prompt shown.
+            assert r2.status_code == 200
+            assert "text/html" in r2.headers.get("content-type", "")
+
+    async def test_remember_mode_missing_sec_fetch_site_fails_closed(
+        self, oauth_proxy_https_remember
+    ):
+        """Missing Sec-Fetch-Site header must fall back to the explicit prompt.
+
+        Legacy clients that don't send the header degrade to the safer behavior
+        rather than granting silent consent.
+        """
+        client_id = "client-nofetch"
+        redirect = "http://localhost:7004/callback"
+        txn_id, _ = await _start_flow(oauth_proxy_https_remember, client_id, redirect)
+        app = Starlette(routes=oauth_proxy_https_remember.get_routes())
+        with TestClient(app) as c:
+            consent = c.get(f"/consent?txn_id={txn_id}")
+            csrf = _extract_csrf(consent.text)
+            assert csrf
+            for k, v in consent.cookies.items():
+                c.cookies.set(k, v)
+            r = c.post(
+                "/consent",
+                data={"action": "approve", "txn_id": txn_id, "csrf_token": csrf},
+                follow_redirects=False,
+            )
+            set_cookie = ";\n".join(r.headers.get("set-cookie", "").splitlines())
+            m = re.search(r"__Host-MCP_APPROVED_CLIENTS=([^;]+)", set_cookie)
+            assert m
+            approved_cookie = m.group(1)
+
+            new_txn, _ = await _start_flow(
+                oauth_proxy_https_remember, client_id, redirect
+            )
+            c.cookies.set("__Host-MCP_APPROVED_CLIENTS", approved_cookie)
+            # No Sec-Fetch-Site header at all.
+            r2 = c.get(f"/consent?txn_id={new_txn}", follow_redirects=False)
+            assert r2.status_code == 200
+            assert "text/html" in r2.headers.get("content-type", "")
diff --git a/tests/server/auth/test_oauth_consent_page.py b/tests/server/auth/test_oauth_consent_page.py
new file mode 100644
index 0000000..1cab951
--- /dev/null
+++ b/tests/server/auth/test_oauth_consent_page.py
@@ -0,0 +1,754 @@
+"""Tests for OAuth Proxy consent page display, CSP policy, and consent binding cookie."""
+
+import re
+import secrets
+import time
+from unittest.mock import Mock
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+from key_value.aio.stores.memory import MemoryStore
+from mcp.server.auth.provider import AuthorizationParams
+from mcp.shared.auth import OAuthClientInformationFull
+from mcp_types import Icon
+from pydantic import AnyUrl
+from starlette.applications import Starlette
+from starlette.testclient import TestClient
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.auth import AccessToken, TokenVerifier
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.server.auth.oauth_proxy.models import OAuthTransaction
+
+
+class _Verifier(TokenVerifier):
+    """Minimal token verifier for security tests."""
+
+    def __init__(self):
+        self.required_scopes = ["read"]
+
+    async def verify_token(self, token: str):
+        return AccessToken(
+            token=token, client_id="c", scopes=self.required_scopes, expires_at=None
+        )
+
+
+@pytest.fixture
+def oauth_proxy_https():
+    """OAuthProxy configured with HTTPS base_url for __Host- cookies."""
+    return OAuthProxy(
+        upstream_authorization_endpoint="https://github.com/login/oauth/authorize",
+        upstream_token_endpoint="https://github.com/login/oauth/access_token",
+        upstream_client_id="client-id",
+        upstream_client_secret="client-secret",
+        token_verifier=_Verifier(),
+        base_url="https://myserver.example",
+        client_storage=MemoryStore(),
+        jwt_signing_key="test-secret",
+    )
+
+
+@pytest.fixture
+def oauth_proxy_https_remember():
+    """OAuthProxy in 'remember' mode for silent-consent cookie tests."""
+    return OAuthProxy(
+        upstream_authorization_endpoint="https://github.com/login/oauth/authorize",
+        upstream_token_endpoint="https://github.com/login/oauth/access_token",
+        upstream_client_id="client-id",
+        upstream_client_secret="client-secret",
+        token_verifier=_Verifier(),
+        base_url="https://myserver.example",
+        client_storage=MemoryStore(),
+        jwt_signing_key="test-secret",
+        require_authorization_consent="remember",
+    )
+
+
+async def _start_flow(
+    proxy: OAuthProxy, client_id: str, redirect: str
+) -> tuple[str, str]:
+    """Register client and start auth; returns (txn_id, consent_url)."""
+    await proxy.register_client(
+        OAuthClientInformationFull(
+            client_id=client_id,
+            client_secret="s",
+            redirect_uris=[AnyUrl(redirect)],
+        )
+    )
+    params = AuthorizationParams(
+        redirect_uri=AnyUrl(redirect),
+        redirect_uri_provided_explicitly=True,
+        state="client-state-xyz",
+        code_challenge="challenge",
+        scopes=["read"],
+    )
+    consent_url = await proxy.authorize(
+        OAuthClientInformationFull(
+            client_id=client_id,
+            client_secret="s",
+            redirect_uris=[AnyUrl(redirect)],
+        ),
+        params,
+    )
+    qs = parse_qs(urlparse(consent_url).query)
+    return qs["txn_id"][0], consent_url
+
+
+def _extract_csrf(html: str) -> str | None:
+    """Extract CSRF token from HTML form."""
+    m = re.search(r"name=\"csrf_token\"\s+value=\"([^\"]+)\"", html)
+    return m.group(1) if m else None
+
+
+class TestConsentPageServerIcon:
+    """Tests for server icon display in OAuth consent screen."""
+
+    async def test_consent_screen_displays_server_icon(self):
+        """Test that consent screen shows server's custom icon when available."""
+
+        # Create mock JWT verifier
+        verifier = Mock(spec=TokenVerifier)
+        verifier.required_scopes = ["read"]
+        verifier.verify_token = Mock(return_value=None)
+
+        # Create OAuthProxy
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=verifier,
+            base_url="https://proxy.example.com",
+            client_storage=MemoryStore(),
+            jwt_signing_key="test-secret",
+        )
+
+        # Create FastMCP server with custom icon
+
+        server = FastMCP(
+            name="My Custom Server",
+            auth=proxy,
+            icons=[Icon(src="https://example.com/custom-icon.png")],
+            website_url="https://example.com",
+        )
+
+        # Create HTTP app
+        app = server.http_app()
+
+        # Register a test client with the proxy
+        client_info = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+        await proxy.register_client(client_info)
+
+        # Create a transaction manually
+
+        txn_id = "test-txn-id"
+        transaction = OAuthTransaction(
+            txn_id=txn_id,
+            client_id="test-client",
+            client_redirect_uri="http://localhost:12345/callback",
+            client_state="client-state",
+            code_challenge="challenge",
+            code_challenge_method="S256",
+            scopes=["read"],
+            created_at=time.time(),
+        )
+        await proxy._transaction_store.put(key=txn_id, value=transaction)
+
+        # Make request to consent page
+        with TestClient(app) as client:
+            response = client.get(f"/consent?txn_id={txn_id}")
+
+            # Check that response is successful
+            assert response.status_code == 200
+
+            # Check that HTML contains custom icon
+            assert "https://example.com/custom-icon.png" in response.text
+
+            # Check that server name is used as alt text
+            assert 'alt="My Custom Server"' in response.text
+
+    async def test_consent_screen_falls_back_to_fastmcp_logo(self):
+        """Test that consent screen shows FastMCP logo when no server icon provided."""
+
+        # Create mock JWT verifier
+        verifier = Mock(spec=TokenVerifier)
+        verifier.required_scopes = ["read"]
+        verifier.verify_token = Mock(return_value=None)
+
+        # Create OAuthProxy
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=verifier,
+            base_url="https://proxy.example.com",
+            client_storage=MemoryStore(),
+            jwt_signing_key="test-secret",
+        )
+
+        # Create FastMCP server without icon
+        server = FastMCP(name="Server Without Icon", auth=proxy)
+
+        # Create HTTP app
+        app = server.http_app()
+
+        # Register a test client
+        client_info = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+        await proxy.register_client(client_info)
+
+        # Create a transaction
+
+        txn_id = "test-txn-id"
+        transaction = OAuthTransaction(
+            txn_id=txn_id,
+            client_id="test-client",
+            client_redirect_uri="http://localhost:12345/callback",
+            client_state="client-state",
+            code_challenge="challenge",
+            code_challenge_method="S256",
+            scopes=["read"],
+            created_at=time.time(),
+        )
+        await proxy._transaction_store.put(key=txn_id, value=transaction)
+
+        # Make request to consent page
+        with TestClient(app) as client:
+            response = client.get(f"/consent?txn_id={txn_id}")
+
+            # Check that response is successful
+            assert response.status_code == 200
+
+            # Check that HTML contains FastMCP logo
+            assert "gofastmcp.com/assets/brand/blue-logo.png" in response.text
+
+            # Check that alt text is still the server name
+            assert 'alt="Server Without Icon"' in response.text
+
+    async def test_consent_screen_escapes_server_name(self):
+        """Test that server name is properly HTML-escaped."""
+
+        # Create mock JWT verifier
+        verifier = Mock(spec=TokenVerifier)
+        verifier.required_scopes = ["read"]
+        verifier.verify_token = Mock(return_value=None)
+
+        # Create OAuthProxy
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=verifier,
+            base_url="https://proxy.example.com",
+            client_storage=MemoryStore(),
+            jwt_signing_key="test-secret",
+        )
+
+        # Create FastMCP server with special characters in name
+        server = FastMCP(
+            name='<script>alert("xss")</script>Server',
+            auth=proxy,
+            icons=[Icon(src="https://example.com/icon.png")],
+        )
+
+        # Create HTTP app
+        app = server.http_app()
+
+        # Register a test client
+        client_info = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+        await proxy.register_client(client_info)
+
+        # Create a transaction
+
+        txn_id = "test-txn-id"
+        transaction = OAuthTransaction(
+            txn_id=txn_id,
+            client_id="test-client",
+            client_redirect_uri="http://localhost:12345/callback",
+            client_state="client-state",
+            code_challenge="challenge",
+            code_challenge_method="S256",
+            scopes=["read"],
+            created_at=time.time(),
+        )
+        await proxy._transaction_store.put(key=txn_id, value=transaction)
+
+        # Make request to consent page
+        with TestClient(app) as client:
+            response = client.get(f"/consent?txn_id={txn_id}")
+
+            # Check that response is successful
+            assert response.status_code == 200
+
+            # Check that script tag is escaped
+            assert "<script>" not in response.text
+            assert "&lt;script&gt;" in response.text
+            assert (
+                'alt="&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;Server"'
+                in response.text
+            )
+
+
+class TestConsentCSPPolicy:
+    """Tests for Content Security Policy customization on consent page."""
+
+    async def test_default_csp_omits_form_action(self):
+        """Test that default CSP omits form-action to avoid Chrome redirect chain issues."""
+
+        verifier = Mock(spec=TokenVerifier)
+        verifier.required_scopes = ["read"]
+        verifier.verify_token = Mock(return_value=None)
+
+        # Create OAuthProxy with default CSP (no custom CSP)
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=verifier,
+            base_url="https://proxy.example.com",
+            client_storage=MemoryStore(),
+            jwt_signing_key="test-secret",
+        )
+
+        server = FastMCP(name="Test Server", auth=proxy)
+        app = server.http_app()
+
+        client_info = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+        await proxy.register_client(client_info)
+
+        txn_id = "test-txn-id"
+        transaction = OAuthTransaction(
+            txn_id=txn_id,
+            client_id="test-client",
+            client_redirect_uri="http://localhost:12345/callback",
+            client_state="client-state",
+            code_challenge="challenge",
+            code_challenge_method="S256",
+            scopes=["read"],
+            created_at=time.time(),
+        )
+        await proxy._transaction_store.put(key=txn_id, value=transaction)
+
+        with TestClient(app) as client:
+            response = client.get(f"/consent?txn_id={txn_id}")
+
+            assert response.status_code == 200
+            # Default CSP should be present but WITHOUT form-action
+            assert 'http-equiv="Content-Security-Policy"' in response.text
+            assert "form-action" not in response.text
+
+    async def test_empty_csp_disables_csp_meta_tag(self):
+        """Test that empty string CSP disables CSP meta tag entirely."""
+
+        verifier = Mock(spec=TokenVerifier)
+        verifier.required_scopes = ["read"]
+        verifier.verify_token = Mock(return_value=None)
+
+        # Create OAuthProxy with empty CSP to disable it
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=verifier,
+            base_url="https://proxy.example.com",
+            client_storage=MemoryStore(),
+            jwt_signing_key="test-secret",
+            consent_csp_policy="",  # Empty string disables CSP
+        )
+
+        server = FastMCP(name="Test Server", auth=proxy)
+        app = server.http_app()
+
+        client_info = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+        await proxy.register_client(client_info)
+
+        txn_id = "test-txn-id"
+        transaction = OAuthTransaction(
+            txn_id=txn_id,
+            client_id="test-client",
+            client_redirect_uri="http://localhost:12345/callback",
+            client_state="client-state",
+            code_challenge="challenge",
+            code_challenge_method="S256",
+            scopes=["read"],
+            created_at=time.time(),
+        )
+        await proxy._transaction_store.put(key=txn_id, value=transaction)
+
+        with TestClient(app) as client:
+            response = client.get(f"/consent?txn_id={txn_id}")
+
+            assert response.status_code == 200
+            # CSP meta tag should NOT be present
+            assert 'http-equiv="Content-Security-Policy"' not in response.text
+
+    async def test_custom_csp_policy_is_used(self):
+        """Test that custom CSP policy is applied to consent page."""
+
+        verifier = Mock(spec=TokenVerifier)
+        verifier.required_scopes = ["read"]
+        verifier.verify_token = Mock(return_value=None)
+
+        # Create OAuthProxy with custom CSP policy
+        custom_csp = "default-src 'self'; script-src 'none'"
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://oauth.example.com/authorize",
+            upstream_token_endpoint="https://oauth.example.com/token",
+            upstream_client_id="upstream-client",
+            upstream_client_secret="upstream-secret",
+            token_verifier=verifier,
+            base_url="https://proxy.example.com",
+            client_storage=MemoryStore(),
+            jwt_signing_key="test-secret",
+            consent_csp_policy=custom_csp,
+        )
+
+        server = FastMCP(name="Test Server", auth=proxy)
+        app = server.http_app()
+
+        client_info = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+        await proxy.register_client(client_info)
+
+        txn_id = "test-txn-id"
+        transaction = OAuthTransaction(
+            txn_id=txn_id,
+            client_id="test-client",
+            client_redirect_uri="http://localhost:12345/callback",
+            client_state="client-state",
+            code_challenge="challenge",
+            code_challenge_method="S256",
+            scopes=["read"],
+            created_at=time.time(),
+        )
+        await proxy._transaction_store.put(key=txn_id, value=transaction)
+
+        with TestClient(app) as client:
+            response = client.get(f"/consent?txn_id={txn_id}")
+
+            assert response.status_code == 200
+            # Custom CSP should be present (HTML-escaped)
+            assert 'http-equiv="Content-Security-Policy"' in response.text
+            # Check for the HTML-escaped version (single quotes become &#x27;)
+            import html
+
+            assert html.escape(custom_csp, quote=True) in response.text
+            # Default form-action should NOT be present (we're using custom)
+            assert "form-action" not in response.text
+
+
+class TestConsentBindingCookie:
+    """Tests for consent binding cookie that prevents confused deputy attacks.
+
+    GHSA-rww4-4w9c-7733: Without browser-binding between consent approval and
+    the IdP callback, an attacker can intercept the upstream authorization URL
+    and send it to a victim whose browser completes the flow.
+    """
+
+    async def test_deny_does_not_redirect_to_unsafe_stored_uri(self, oauth_proxy_https):
+        """Consent denial must not redirect to an unsafe stored callback URI."""
+        txn_id = "test-deny-javascript"
+        transaction = OAuthTransaction(
+            txn_id=txn_id,
+            client_id="test-client",
+            client_redirect_uri="javascript:alert(document.cookie)//",
+            client_state="client-state",
+            code_challenge="challenge",
+            code_challenge_method="S256",
+            scopes=["read"],
+            created_at=time.time(),
+        )
+        await oauth_proxy_https._transaction_store.put(key=txn_id, value=transaction)
+
+        app = Starlette(routes=oauth_proxy_https.get_routes())
+        with TestClient(app) as c:
+            consent = c.get(f"/consent?txn_id={txn_id}")
+            csrf = _extract_csrf(consent.text)
+            assert csrf
+            for k, v in consent.cookies.items():
+                c.cookies.set(k, v)
+
+            response = c.post(
+                "/consent",
+                data={"action": "deny", "txn_id": txn_id, "csrf_token": csrf},
+                follow_redirects=False,
+            )
+
+        assert response.status_code == 400
+        assert "location" not in response.headers
+        assert "Invalid redirect URI" in response.text
+
+    async def test_approve_sets_consent_binding_cookie(self, oauth_proxy_https):
+        """Approving consent must set a signed consent binding cookie."""
+        txn_id, _ = await _start_flow(
+            oauth_proxy_https, "client-binding", "http://localhost:6001/callback"
+        )
+        app = Starlette(routes=oauth_proxy_https.get_routes())
+        with TestClient(app) as c:
+            consent = c.get(f"/consent?txn_id={txn_id}")
+            csrf = _extract_csrf(consent.text)
+            assert csrf
+            for k, v in consent.cookies.items():
+                c.cookies.set(k, v)
+            r = c.post(
+                "/consent",
+                data={"action": "approve", "txn_id": txn_id, "csrf_token": csrf},
+                follow_redirects=False,
+            )
+            assert r.status_code in (302, 303)
+            set_cookie_header = r.headers.get("set-cookie", "")
+            assert "__Host-MCP_CONSENT_BINDING" in set_cookie_header
+
+    async def test_auto_approve_sets_consent_binding_cookie(
+        self, oauth_proxy_https_remember
+    ):
+        """Auto-approve path (previously approved client in 'remember' mode) must also set the binding cookie."""
+        client_id = "client-autobinding"
+        redirect = "http://localhost:6002/callback"
+        txn_id, _ = await _start_flow(oauth_proxy_https_remember, client_id, redirect)
+        app = Starlette(routes=oauth_proxy_https_remember.get_routes())
+        with TestClient(app) as c:
+            # First: approve manually to get the approved cookie
+            consent = c.get(f"/consent?txn_id={txn_id}")
+            csrf = _extract_csrf(consent.text)
+            assert csrf
+            for k, v in consent.cookies.items():
+                c.cookies.set(k, v)
+            r = c.post(
+                "/consent",
+                data={"action": "approve", "txn_id": txn_id, "csrf_token": csrf},
+                follow_redirects=False,
+            )
+            # Extract approved cookie
+            m = re.search(
+                r"__Host-MCP_APPROVED_CLIENTS=([^;]+)",
+                r.headers.get("set-cookie", ""),
+            )
+            assert m
+            approved_cookie = m.group(1)
+
+            # Second: start new flow, auto-approve should set binding cookie
+            # (Sec-Fetch-Site=none simulates a direct client-initiated navigation.)
+            new_txn, _ = await _start_flow(
+                oauth_proxy_https_remember, client_id, redirect
+            )
+            c.cookies.set("__Host-MCP_APPROVED_CLIENTS", approved_cookie)
+            r2 = c.get(
+                f"/consent?txn_id={new_txn}",
+                headers={"Sec-Fetch-Site": "none"},
+                follow_redirects=False,
+            )
+            assert r2.status_code in (302, 303)
+            set_cookie_header = r2.headers.get("set-cookie", "")
+            assert "__Host-MCP_CONSENT_BINDING" in set_cookie_header
+
+    async def test_parallel_flows_do_not_interfere(self, oauth_proxy_https):
+        """Multiple concurrent consent flows in the same browser must not clobber each other.
+
+        Uses two different clients so the second flow also shows a consent form
+        (auto-approve only kicks in for the same client+redirect pair).
+        """
+        txn1, _ = await _start_flow(
+            oauth_proxy_https, "client-par-a", "http://localhost:6010/callback"
+        )
+        txn2, _ = await _start_flow(
+            oauth_proxy_https, "client-par-b", "http://localhost:6011/callback"
+        )
+        app = Starlette(routes=oauth_proxy_https.get_routes())
+        with TestClient(app) as c:
+            # Approve first flow
+            consent1 = c.get(f"/consent?txn_id={txn1}")
+            csrf1 = _extract_csrf(consent1.text)
+            assert csrf1
+            for k, v in consent1.cookies.items():
+                c.cookies.set(k, v)
+            r1 = c.post(
+                "/consent",
+                data={"action": "approve", "txn_id": txn1, "csrf_token": csrf1},
+                follow_redirects=False,
+            )
+            assert r1.status_code in (302, 303)
+            for k, v in r1.cookies.items():
+                c.cookies.set(k, v)
+
+            # Approve second flow (different client, so consent form is shown)
+            consent2 = c.get(f"/consent?txn_id={txn2}")
+            csrf2 = _extract_csrf(consent2.text)
+            assert csrf2
+            for k, v in consent2.cookies.items():
+                c.cookies.set(k, v)
+            r2 = c.post(
+                "/consent",
+                data={"action": "approve", "txn_id": txn2, "csrf_token": csrf2},
+                follow_redirects=False,
+            )
+            assert r2.status_code in (302, 303)
+            for k, v in r2.cookies.items():
+                c.cookies.set(k, v)
+
+            # Both transactions should have consent tokens
+            txn1_model = await oauth_proxy_https._transaction_store.get(key=txn1)
+            txn2_model = await oauth_proxy_https._transaction_store.get(key=txn2)
+            assert txn1_model is not None and txn1_model.consent_token
+            assert txn2_model is not None and txn2_model.consent_token
+
+            # First flow's callback should still work (cookie has both bindings)
+            r_cb1 = c.get(
+                f"/auth/callback?code=fake&state={txn1}", follow_redirects=False
+            )
+            # Should NOT be 403 — the binding for txn1 should still be in the cookie.
+            # It will fail at token exchange (500) but not at consent verification.
+            assert r_cb1.status_code != 403
+
+    async def test_idp_callback_rejects_missing_consent_cookie(self, oauth_proxy_https):
+        """IdP callback must reject requests without the consent binding cookie.
+
+        This is the core confused deputy scenario: a different browser (the victim)
+        hits the callback without the cookie that was set on the attacker's browser.
+        """
+        txn_id, _ = await _start_flow(
+            oauth_proxy_https, "client-nocd", "http://localhost:6003/callback"
+        )
+        # Manually set consent_token on transaction (simulating consent approval)
+        txn_model = await oauth_proxy_https._transaction_store.get(key=txn_id)
+        assert txn_model is not None
+        txn_model.consent_token = secrets.token_urlsafe(32)
+        await oauth_proxy_https._transaction_store.put(
+            key=txn_id, value=txn_model, ttl=15 * 60
+        )
+
+        app = Starlette(routes=oauth_proxy_https.get_routes())
+        with TestClient(app) as c:
+            # Hit callback WITHOUT the consent binding cookie
+            r = c.get(
+                f"/auth/callback?code=fake-code&state={txn_id}",
+                follow_redirects=False,
+            )
+            assert r.status_code == 403
+            assert (
+                "session mismatch" in r.text.lower() or "Authorization Error" in r.text
+            )
+
+    async def test_idp_callback_rejects_wrong_consent_cookie(self, oauth_proxy_https):
+        """IdP callback must reject requests with a tampered consent binding cookie."""
+        txn_id, _ = await _start_flow(
+            oauth_proxy_https, "client-wrongcd", "http://localhost:6004/callback"
+        )
+        txn_model = await oauth_proxy_https._transaction_store.get(key=txn_id)
+        assert txn_model is not None
+        txn_model.consent_token = secrets.token_urlsafe(32)
+        await oauth_proxy_https._transaction_store.put(
+            key=txn_id, value=txn_model, ttl=15 * 60
+        )
+
+        app = Starlette(routes=oauth_proxy_https.get_routes())
+        with TestClient(app) as c:
+            # Set a wrong/tampered consent binding cookie
+            c.cookies.set("__Host-MCP_CONSENT_BINDING", "wrong-token.invalidsig")
+            r = c.get(
+                f"/auth/callback?code=fake-code&state={txn_id}",
+                follow_redirects=False,
+            )
+            assert r.status_code == 403
+
+    async def test_idp_callback_rejects_missing_consent_token_on_transaction(
+        self, oauth_proxy_https
+    ):
+        """IdP callback must reject when transaction has no consent_token set."""
+        txn_id, _ = await _start_flow(
+            oauth_proxy_https, "client-notxntoken", "http://localhost:6005/callback"
+        )
+        # Transaction exists but consent_token is None (consent was never completed)
+        app = Starlette(routes=oauth_proxy_https.get_routes())
+        with TestClient(app) as c:
+            r = c.get(
+                f"/auth/callback?code=fake-code&state={txn_id}",
+                follow_redirects=False,
+            )
+            assert r.status_code == 403
+
+    async def test_consent_disabled_skips_binding_check(self):
+        """When require_authorization_consent=False, the binding check is skipped."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://github.com/login/oauth/authorize",
+            upstream_token_endpoint="https://github.com/login/oauth/access_token",
+            upstream_client_id="client-id",
+            upstream_client_secret="client-secret",
+            token_verifier=_Verifier(),
+            base_url="https://myserver.example",
+            client_storage=MemoryStore(),
+            jwt_signing_key="test-secret",
+            require_authorization_consent=False,
+        )
+        client_id = "client-noconsent"
+        redirect = "http://localhost:6006/callback"
+        await proxy.register_client(
+            OAuthClientInformationFull(
+                client_id=client_id,
+                client_secret="s",
+                redirect_uris=[AnyUrl(redirect)],
+            )
+        )
+        params = AuthorizationParams(
+            redirect_uri=AnyUrl(redirect),
+            redirect_uri_provided_explicitly=True,
+            state="st",
+            code_challenge="ch",
+            scopes=["read"],
+        )
+        upstream_url = await proxy.authorize(
+            OAuthClientInformationFull(
+                client_id=client_id,
+                client_secret="s",
+                redirect_uris=[AnyUrl(redirect)],
+            ),
+            params,
+        )
+        # With consent disabled, authorize returns upstream URL directly
+        assert upstream_url.startswith("https://github.com/login/oauth/authorize")
+        qs = parse_qs(urlparse(upstream_url).query)
+        txn_id = qs["state"][0]
+
+        # The transaction should have no consent_token
+        txn_model = await proxy._transaction_store.get(key=txn_id)
+        assert txn_model is not None
+        assert txn_model.consent_token is None
+
+        # IdP callback should NOT reject due to missing consent cookie
+        # (it will fail at token exchange, but not at the consent check)
+        app = Starlette(routes=proxy.get_routes())
+        with TestClient(app) as c:
+            r = c.get(
+                f"/auth/callback?code=fake-code&state={txn_id}",
+                follow_redirects=False,
+            )
+            # Should NOT be 403 (consent binding rejection)
+            # It will be 500 because the fake code can't be exchanged with GitHub,
+            # but that's fine — we're verifying the consent check was skipped.
+            assert r.status_code != 403
diff --git a/tests/server/auth/test_oauth_mounting.py b/tests/server/auth/test_oauth_mounting.py
new file mode 100644
index 0000000..2959423
--- /dev/null
+++ b/tests/server/auth/test_oauth_mounting.py
@@ -0,0 +1,483 @@
+"""Tests for OAuth .well-known routes when FastMCP apps are mounted in parent ASGI apps.
+
+This test file validates the fix for issue #2077 where .well-known/oauth-protected-resource
+returns 404 at root level when a FastMCP app is mounted under a path prefix.
+
+The fix uses MCP SDK 1.17+ which implements RFC 9728 path-scoped well-known URLs.
+"""
+
+import httpx
+import pytest
+from key_value.aio.stores.memory import MemoryStore
+from pydantic import AnyHttpUrl
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+from fastmcp import FastMCP
+from fastmcp.server.auth import RemoteAuthProvider
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.server.auth.providers.jwt import StaticTokenVerifier
+
+
+@pytest.fixture
+def test_tokens():
+    """Standard test tokens fixture."""
+    return {
+        "test_token": {
+            "client_id": "test-client",
+            "scopes": ["read", "write"],
+        }
+    }
+
+
+class TestOAuthMounting:
+    """Test OAuth .well-known routes with mounted FastMCP apps."""
+
+    async def test_well_known_with_direct_deployment(self, test_tokens):
+        """Test that .well-known routes work when app is deployed directly (not mounted).
+
+        This is the baseline - it should work as expected.
+        Per RFC 9728, if the resource is at /mcp, the well-known endpoint is at
+        /.well-known/oauth-protected-resource/mcp (path-scoped).
+        """
+        token_verifier = StaticTokenVerifier(tokens=test_tokens)
+        auth_provider = RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+
+        mcp = FastMCP("test-server", auth=auth_provider)
+        mcp_app = mcp.http_app()
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=mcp_app),
+            base_url="https://api.example.com",
+        ) as client:
+            # RFC 9728: path-scoped well-known URL
+            # Resource is at /mcp, so well-known should be at /.well-known/oauth-protected-resource/mcp
+            response = await client.get("/.well-known/oauth-protected-resource/mcp")
+            assert response.status_code == 200
+
+            data = response.json()
+            assert data["resource"] == "https://api.example.com/mcp"
+            assert data["authorization_servers"] == ["https://auth.example.com/"]
+
+    async def test_well_known_with_mounted_app(self, test_tokens):
+        """Test that .well-known routes work when explicitly mounted at root.
+
+        This test uses the CANONICAL pattern for mounting:
+        - base_url includes the mount prefix ("/api")
+        - mcp_path is just the internal MCP path ("/mcp")
+        - These combine: base_url + mcp_path = actual URL
+
+        The well-known routes are mounted at root level for RFC 9728 compliance.
+        """
+        token_verifier = StaticTokenVerifier(tokens=test_tokens)
+        # CANONICAL PATTERN: base_url includes the mount prefix
+        auth_provider = RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com/api",  # Includes /api mount prefix
+        )
+
+        mcp = FastMCP("test-server", auth=auth_provider)
+        mcp_app = mcp.http_app(path="/mcp")
+
+        # Pass just the internal mcp_path, NOT the full mount path
+        # The auth provider will combine base_url + mcp_path internally
+        well_known_routes = auth_provider.get_well_known_routes(mcp_path="/mcp")
+
+        parent_app = Starlette(
+            routes=[
+                *well_known_routes,  # Well-known routes at root level
+                Mount("/api", app=mcp_app),  # MCP app under /api
+            ],
+            lifespan=mcp_app.lifespan,
+        )
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=parent_app),
+            base_url="https://api.example.com",
+        ) as client:
+            # The CORRECT RFC 9728 path-scoped well-known URL at root
+            # Resource is at /api/mcp, so well-known is at /.well-known/oauth-protected-resource/api/mcp
+            response = await client.get("/.well-known/oauth-protected-resource/api/mcp")
+            assert response.status_code == 200
+
+            data = response.json()
+            assert data["resource"] == "https://api.example.com/api/mcp"
+            assert data["authorization_servers"] == ["https://auth.example.com/"]
+
+            # There will also be an extra route at /api/.well-known/oauth-protected-resource/mcp
+            # (from the mounted MCP app), but we don't care about that as long as the correct one exists
+
+    async def test_mcp_endpoint_with_mounted_app(self, test_tokens):
+        """Test that MCP endpoint works correctly when mounted.
+
+        This confirms the MCP functionality itself works with mounting.
+        """
+        token_verifier = StaticTokenVerifier(tokens=test_tokens)
+        auth_provider = RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+
+        mcp = FastMCP("test-server", auth=auth_provider)
+
+        @mcp.tool
+        def test_tool(message: str) -> str:
+            return f"Echo: {message}"
+
+        mcp_app = mcp.http_app(path="/mcp")
+
+        # Mount the MCP app under /api prefix
+        parent_app = Starlette(
+            routes=[
+                Mount("/api", app=mcp_app),
+            ],
+            lifespan=mcp_app.lifespan,
+        )
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=parent_app),
+            base_url="https://api.example.com",
+        ) as client:
+            # The MCP endpoint should work at /api/mcp (mounted correctly)
+            # This is a basic connectivity test
+            response = await client.get("/api/mcp")
+
+            # We expect either 200 (if no auth required for GET) or 401 (if auth required)
+            # The key is that it's NOT 404
+            assert response.status_code in [200, 401, 405]
+
+    async def test_nested_mounting(self, test_tokens):
+        """Test .well-known routes with deeply nested mounts.
+
+        Uses CANONICAL pattern: base_url includes all mount prefixes.
+        """
+        token_verifier = StaticTokenVerifier(tokens=test_tokens)
+        # CANONICAL PATTERN: base_url includes full mount path /outer/inner
+        auth_provider = RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com/outer/inner",  # Includes nested mount path
+        )
+
+        mcp = FastMCP("test-server", auth=auth_provider)
+        mcp_app = mcp.http_app(path="/mcp")
+
+        # Pass just the internal mcp_path
+        well_known_routes = auth_provider.get_well_known_routes(mcp_path="/mcp")
+
+        # Create nested mounts
+        inner_app = Starlette(
+            routes=[Mount("/inner", app=mcp_app)],
+        )
+        outer_app = Starlette(
+            routes=[
+                *well_known_routes,  # Well-known routes at root level
+                Mount("/outer", app=inner_app),
+            ],
+            lifespan=mcp_app.lifespan,
+        )
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=outer_app),
+            base_url="https://api.example.com",
+        ) as client:
+            # RFC 9728: path-scoped well-known URL for nested mounting
+            # Resource is at /outer/inner/mcp, so well-known is at /.well-known/oauth-protected-resource/outer/inner/mcp
+            response = await client.get(
+                "/.well-known/oauth-protected-resource/outer/inner/mcp"
+            )
+            assert response.status_code == 200
+
+            data = response.json()
+            assert data["resource"] == "https://api.example.com/outer/inner/mcp"
+
+    async def test_oauth_authorization_server_metadata_with_base_url_and_issuer_url(
+        self, test_tokens
+    ):
+        """Test OAuth authorization server metadata when base_url and issuer_url differ.
+
+        This validates the fix for issue #2287 where operational OAuth endpoints
+        (/authorize, /token) should be declared at base_url in the metadata,
+        not at issuer_url.
+
+        Scenario: FastMCP server mounted at /api prefix
+        - issuer_url: https://api.example.com (root level)
+        - base_url: https://api.example.com/api (includes mount prefix)
+        - Expected: metadata declares endpoints at base_url
+        """
+        # Create OAuth proxy with different base_url and issuer_url
+        token_verifier = StaticTokenVerifier(tokens=test_tokens)
+        auth_provider = OAuthProxy(
+            upstream_authorization_endpoint="https://upstream.example.com/authorize",
+            upstream_token_endpoint="https://upstream.example.com/token",
+            upstream_client_id="test-client-id",
+            upstream_client_secret="test-client-secret",
+            token_verifier=token_verifier,
+            base_url="https://api.example.com/api",  # Includes mount prefix
+            issuer_url="https://api.example.com",  # Root level
+            client_storage=MemoryStore(),
+        )
+
+        mcp = FastMCP("test-server", auth=auth_provider)
+        mcp_app = mcp.http_app(path="/mcp")
+
+        # Get well-known routes for mounting at root
+        well_known_routes = auth_provider.get_well_known_routes(mcp_path="/mcp")
+
+        # Mount the app under /api prefix
+        parent_app = Starlette(
+            routes=[
+                *well_known_routes,  # Well-known routes at root level
+                Mount("/api", app=mcp_app),  # MCP app under /api
+            ],
+            lifespan=mcp_app.lifespan,
+        )
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=parent_app),
+            base_url="https://api.example.com",
+        ) as client:
+            # Fetch the authorization server metadata
+            response = await client.get("/.well-known/oauth-authorization-server")
+            assert response.status_code == 200
+
+            metadata = response.json()
+
+            # CRITICAL: The metadata should declare endpoints at base_url,
+            # not issuer_url, because that's where they're actually mounted
+            assert (
+                metadata["authorization_endpoint"]
+                == "https://api.example.com/api/authorize"
+            )
+            assert metadata["token_endpoint"] == "https://api.example.com/api/token"
+            assert (
+                metadata["registration_endpoint"]
+                == "https://api.example.com/api/register"
+            )
+
+            # The issuer field should use base_url (where the server is actually running)
+            # Note: MCP SDK may or may not add a trailing slash
+            assert metadata["issuer"] in [
+                "https://api.example.com/api",
+                "https://api.example.com/api/",
+            ]
+
+    async def test_oauth_authorization_server_metadata_path_aware_discovery(
+        self, test_tokens
+    ):
+        """Test RFC 8414 path-aware discovery when issuer_url has a path.
+
+        This validates the fix for issue #2527 where authorization server metadata
+        should be exposed at a path-aware URL when issuer_url has a path component.
+
+        When issuer_url defaults to base_url (e.g., http://example.com/api), the
+        authorization server metadata should be at:
+        /.well-known/oauth-authorization-server/api
+
+        This is consistent with how protected resource metadata already works
+        (RFC 9728) and complies with RFC 8414 path-aware discovery.
+        """
+        # Create OAuth proxy where issuer_url defaults to base_url (which has a path)
+        token_verifier = StaticTokenVerifier(tokens=test_tokens)
+        auth_provider = OAuthProxy(
+            upstream_authorization_endpoint="https://upstream.example.com/authorize",
+            upstream_token_endpoint="https://upstream.example.com/token",
+            upstream_client_id="test-client-id",
+            upstream_client_secret="test-client-secret",
+            token_verifier=token_verifier,
+            base_url="https://api.example.com/api",  # Has path, no explicit issuer_url
+            client_storage=MemoryStore(),
+        )
+
+        mcp = FastMCP("test-server", auth=auth_provider)
+        mcp_app = mcp.http_app(path="/mcp")
+
+        # Get well-known routes - should include path-aware authorization server metadata
+        well_known_routes = auth_provider.get_well_known_routes(mcp_path="/mcp")
+
+        # Find the authorization server metadata route
+        auth_server_routes = [
+            r for r in well_known_routes if "oauth-authorization-server" in r.path
+        ]
+        assert len(auth_server_routes) == 1
+
+        # The route should be path-aware (RFC 8414)
+        assert (
+            auth_server_routes[0].path == "/.well-known/oauth-authorization-server/api"
+        )
+
+        # Find the protected resource metadata route for comparison
+        protected_resource_routes = [
+            r for r in well_known_routes if "oauth-protected-resource" in r.path
+        ]
+        assert len(protected_resource_routes) == 1
+        # Protected resource should also be path-aware (RFC 9728)
+        assert (
+            protected_resource_routes[0].path
+            == "/.well-known/oauth-protected-resource/api/mcp"
+        )
+
+        # Mount the app and verify the routes are accessible
+        parent_app = Starlette(
+            routes=[
+                *well_known_routes,
+                Mount("/api", app=mcp_app),
+            ],
+            lifespan=mcp_app.lifespan,
+        )
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=parent_app),
+            base_url="https://api.example.com",
+        ) as client:
+            # Path-aware authorization server metadata should be accessible
+            response = await client.get("/.well-known/oauth-authorization-server/api")
+            assert response.status_code == 200
+
+            metadata = response.json()
+            assert (
+                metadata["authorization_endpoint"]
+                == "https://api.example.com/api/authorize"
+            )
+            assert metadata["token_endpoint"] == "https://api.example.com/api/token"
+
+            # Path-aware protected resource metadata should also work
+            response = await client.get("/.well-known/oauth-protected-resource/api/mcp")
+            assert response.status_code == 200
+
+    async def test_oauth_authorization_server_metadata_root_issuer(self, test_tokens):
+        """Test that root-level issuer_url still uses root discovery path.
+
+        When issuer_url is explicitly set to root (no path), the authorization
+        server metadata should remain at the root path:
+        /.well-known/oauth-authorization-server
+
+        This maintains backwards compatibility with the documented mounting pattern.
+        """
+        token_verifier = StaticTokenVerifier(tokens=test_tokens)
+        auth_provider = OAuthProxy(
+            upstream_authorization_endpoint="https://upstream.example.com/authorize",
+            upstream_token_endpoint="https://upstream.example.com/token",
+            upstream_client_id="test-client-id",
+            upstream_client_secret="test-client-secret",
+            token_verifier=token_verifier,
+            base_url="https://api.example.com/api",
+            issuer_url="https://api.example.com",  # Explicitly root
+            client_storage=MemoryStore(),
+        )
+
+        well_known_routes = auth_provider.get_well_known_routes(mcp_path="/mcp")
+
+        # Find the authorization server metadata route
+        auth_server_routes = [
+            r for r in well_known_routes if "oauth-authorization-server" in r.path
+        ]
+        assert len(auth_server_routes) == 1
+
+        # Should be at root (no path suffix) when issuer_url is root
+        assert auth_server_routes[0].path == "/.well-known/oauth-authorization-server"
+
+    async def test_oidc_discovery_alias_path_aware(self, test_tokens):
+        """Test that /.well-known/openid-configuration aliases are added for path-aware issuers.
+
+        RFC 8414 §5 allows servers to expose OAuth metadata at the OIDC discovery path.
+        The MCP SDK client probes both paths; fastmcp must respond to either.
+
+        For a path-aware issuer (e.g. https://api.example.com/api) two OIDC paths
+        are registered:
+        - /.well-known/openid-configuration/api  (RFC 8414 §5, path-aware)
+        - /.well-known/openid-configuration      (OIDC 1.0 / reverse-proxy compat)
+        """
+        token_verifier = StaticTokenVerifier(tokens=test_tokens)
+        auth_provider = OAuthProxy(
+            upstream_authorization_endpoint="https://upstream.example.com/authorize",
+            upstream_token_endpoint="https://upstream.example.com/token",
+            upstream_client_id="test-client-id",
+            upstream_client_secret="test-client-secret",
+            token_verifier=token_verifier,
+            base_url="https://api.example.com/api",
+            client_storage=MemoryStore(),
+        )
+
+        well_known_routes = auth_provider.get_well_known_routes(mcp_path="/mcp")
+
+        oidc_routes = [r for r in well_known_routes if "openid-configuration" in r.path]
+        oidc_paths = {r.path for r in oidc_routes}
+
+        assert "/.well-known/openid-configuration/api" in oidc_paths  # RFC 8414 §5
+        assert (
+            "/.well-known/openid-configuration" in oidc_paths
+        )  # OIDC 1.0 / proxy compat
+
+    async def test_oidc_discovery_alias_root(self, test_tokens):
+        """Test that /.well-known/openid-configuration alias is added for root issuers."""
+        token_verifier = StaticTokenVerifier(tokens=test_tokens)
+        auth_provider = OAuthProxy(
+            upstream_authorization_endpoint="https://upstream.example.com/authorize",
+            upstream_token_endpoint="https://upstream.example.com/token",
+            upstream_client_id="test-client-id",
+            upstream_client_secret="test-client-secret",
+            token_verifier=token_verifier,
+            base_url="https://api.example.com/api",
+            issuer_url="https://api.example.com",
+            client_storage=MemoryStore(),
+        )
+
+        well_known_routes = auth_provider.get_well_known_routes(mcp_path="/mcp")
+
+        oidc_routes = [r for r in well_known_routes if "openid-configuration" in r.path]
+        assert len(oidc_routes) == 1
+        assert oidc_routes[0].path == "/.well-known/openid-configuration"
+
+    async def test_oidc_discovery_returns_auth_server_metadata(self, test_tokens):
+        """Test that /.well-known/openid-configuration returns valid OAuth server metadata.
+
+        The response must include the core RFC 8414 fields so that OIDC-aware
+        clients (e.g. Claude Desktop backend) can discover the authorization endpoint.
+        """
+        token_verifier = StaticTokenVerifier(tokens=test_tokens)
+        auth_provider = OAuthProxy(
+            upstream_authorization_endpoint="https://upstream.example.com/authorize",
+            upstream_token_endpoint="https://upstream.example.com/token",
+            upstream_client_id="test-client-id",
+            upstream_client_secret="test-client-secret",
+            token_verifier=token_verifier,
+            base_url="https://api.example.com/api",
+            client_storage=MemoryStore(),
+        )
+
+        mcp = FastMCP("test-server", auth=auth_provider)
+        mcp_app = mcp.http_app(path="/mcp")
+        well_known_routes = auth_provider.get_well_known_routes(mcp_path="/mcp")
+
+        parent_app = Starlette(
+            routes=[
+                *well_known_routes,
+                Mount("/api", app=mcp_app),
+            ],
+            lifespan=mcp_app.lifespan,
+        )
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=parent_app),
+            base_url="https://api.example.com",
+        ) as client:
+            # Path-aware OIDC discovery (RFC 8414 §5)
+            response = await client.get("/.well-known/openid-configuration/api")
+            assert response.status_code == 200
+            metadata = response.json()
+            assert "authorization_endpoint" in metadata
+            assert "token_endpoint" in metadata
+
+            # Root OIDC discovery (OIDC 1.0 / reverse-proxy compat)
+            response = await client.get("/.well-known/openid-configuration")
+            assert response.status_code == 200
+            metadata = response.json()
+            assert "authorization_endpoint" in metadata
+            assert "token_endpoint" in metadata
diff --git a/tests/server/auth/test_oauth_proxy_redirect_validation.py b/tests/server/auth/test_oauth_proxy_redirect_validation.py
new file mode 100644
index 0000000..15f2f8d
--- /dev/null
+++ b/tests/server/auth/test_oauth_proxy_redirect_validation.py
@@ -0,0 +1,494 @@
+"""Tests for OAuth proxy redirect URI validation."""
+
+from unittest.mock import patch
+
+import pytest
+from key_value.aio.stores.memory import MemoryStore
+from mcp.shared.auth import InvalidRedirectUriError
+from pydantic import AnyHttpUrl, AnyUrl
+
+from fastmcp.server.auth.auth import TokenVerifier
+from fastmcp.server.auth.cimd import CIMDDocument
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.server.auth.oauth_proxy.models import ProxyDCRClient
+
+# Standard public IP used for DNS mocking in tests
+TEST_PUBLIC_IP = "93.184.216.34"
+
+
+class MockTokenVerifier(TokenVerifier):
+    """Mock token verifier for testing."""
+
+    def __init__(self):
+        self.required_scopes = []
+
+    async def verify_token(self, token: str) -> dict | None:  # type: ignore[override]  # ty:ignore[invalid-method-override]
+        return {"sub": "test-user"}
+
+
+class TestProxyDCRClient:
+    """Test ProxyDCRClient redirect URI validation."""
+
+    def test_default_uses_registered_redirect_uris_with_loopback_port_flexibility(self):
+        """Default DCR clients allow registered loopback callbacks to vary ports."""
+        client = ProxyDCRClient(
+            client_id="test",
+            client_secret="secret",
+            redirect_uris=[AnyUrl("http://localhost:3000/callback")],
+        )
+
+        assert client.validate_redirect_uri(
+            AnyUrl("http://localhost:3000/callback")
+        ) == AnyUrl("http://localhost:3000/callback")
+        assert client.validate_redirect_uri(
+            AnyUrl("http://localhost:8080/callback")
+        ) == AnyUrl("http://localhost:8080/callback")
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("http://localhost:8080/other"))
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("http://127.0.0.1:3000/callback"))
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("http://example.com/callback"))
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(
+                AnyUrl("https://claude.ai/api/mcp/auth_callback")
+            )
+
+    def test_default_uses_exact_registered_external_redirect_uri(self):
+        """Default DCR clients require exact matches for non-loopback callbacks."""
+        client = ProxyDCRClient(
+            client_id="test",
+            client_secret="secret",
+            redirect_uris=[AnyUrl("https://client.example.com/oauth/callback")],
+        )
+
+        assert client.validate_redirect_uri(
+            AnyUrl("https://client.example.com/oauth/callback")
+        ) == AnyUrl("https://client.example.com/oauth/callback")
+
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(
+                AnyUrl("https://client.example.com:8443/oauth/callback")
+            )
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("https://evil.example.com/callback"))
+
+    def test_synthetic_client_can_allow_unregistered_redirect_uris(self):
+        """Synthetic clients can opt in to broad redirect URI compatibility."""
+        client = ProxyDCRClient(
+            client_id="test",
+            client_secret="secret",
+            redirect_uris=[AnyUrl("http://localhost")],
+            allow_unregistered_redirect_uris=True,
+        )
+
+        assert client.validate_redirect_uri(AnyUrl("http://localhost:8080")) == AnyUrl(
+            "http://localhost:8080"
+        )
+        assert client.validate_redirect_uri(
+            AnyUrl("https://claude.ai/api/mcp/auth_callback")
+        ) == AnyUrl("https://claude.ai/api/mcp/auth_callback")
+
+    def test_default_rejects_unsafe_registered_redirect_scheme(self):
+        """Stored DCR metadata cannot preserve unsafe browser schemes."""
+        client = ProxyDCRClient(
+            client_id="test",
+            client_secret="secret",
+            redirect_uris=[AnyUrl("javascript:alert(document.cookie)//")],
+        )
+
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("javascript:alert(document.cookie)//"))
+
+    def test_custom_patterns(self):
+        """Test custom redirect URI patterns."""
+        client = ProxyDCRClient(
+            client_id="test",
+            client_secret="secret",
+            redirect_uris=[AnyUrl("http://localhost:3000")],
+            allowed_redirect_uri_patterns=[
+                "http://localhost:*",
+                "https://app.example.com/*",
+            ],
+        )
+
+        # Allowed by patterns
+        assert client.validate_redirect_uri(AnyUrl("http://localhost:3000"))
+        assert client.validate_redirect_uri(AnyUrl("https://app.example.com/callback"))
+
+        # Not allowed by patterns
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("http://127.0.0.1:3000"))
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(
+                AnyUrl("cursor://anysphere.cursor-mcp/oauth/callback")
+            )
+
+    def test_default_not_applied_when_custom_patterns_supplied(self):
+        """Test that default validation is not applied when custom patterns are supplied."""
+        allowed_patterns = [
+            "cursor://anysphere.cursor-mcp/oauth/callback",
+            "https://app.example.com/*",
+        ]
+
+        client = ProxyDCRClient(
+            client_id="test",
+            client_secret="secret",
+            redirect_uris=[AnyUrl("http://localhost:3000")],
+            allowed_redirect_uri_patterns=allowed_patterns,
+        )
+
+        assert client.validate_redirect_uri(
+            AnyUrl("https://app.example.com/oauth/callback")
+        )
+        assert client.validate_redirect_uri(
+            AnyUrl("cursor://anysphere.cursor-mcp/oauth/callback")
+        )
+
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("http://localhost:3000"))
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("http://127.0.0.1:3000"))
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("https://example.com"))
+
+    def test_empty_list_blocks_all(self):
+        """Empty allowed_redirect_uri_patterns blocks all redirect URIs, including pre-registered ones."""
+        client = ProxyDCRClient(
+            client_id="test",
+            client_secret="secret",
+            redirect_uris=[AnyUrl("http://localhost:3000")],
+            allowed_redirect_uri_patterns=[],
+        )
+
+        # All URIs must be rejected — [] means "block all", not "fall back to redirect_uris"
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("http://localhost:3000"))
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("http://example.com"))
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("https://anywhere.com:9999/path"))
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("http://localhost:5000"))
+
+    def test_none_redirect_uri(self):
+        """Test that None redirect URI uses default behavior."""
+        client = ProxyDCRClient(
+            client_id="test",
+            client_secret="secret",
+            redirect_uris=[AnyUrl("http://localhost:3000")],
+        )
+
+        # None should use the first registered URI
+        result = client.validate_redirect_uri(None)
+        assert result == AnyUrl("http://localhost:3000")
+
+    def test_none_redirect_uri_with_matching_patterns(self):
+        """DCR client with single URI and patterns: None resolves and validates against patterns."""
+        client = ProxyDCRClient(
+            client_id="test",
+            client_secret="secret",
+            redirect_uris=[AnyUrl("http://localhost:3000")],
+            allowed_redirect_uri_patterns=["http://localhost:*"],
+        )
+
+        # Resolves to registered URI which matches the pattern — should succeed
+        result = client.validate_redirect_uri(None)
+        assert result == AnyUrl("http://localhost:3000")
+
+    def test_none_redirect_uri_with_nonmatching_patterns(self):
+        """DCR client with single URI and patterns: None raises if resolved URI doesn't match."""
+        client = ProxyDCRClient(
+            client_id="test",
+            client_secret="secret",
+            redirect_uris=[AnyUrl("http://localhost:3000")],
+            allowed_redirect_uri_patterns=["https://myapp.example.com/*"],
+        )
+
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(None)
+
+    def test_cimd_none_redirect_uri_single_exact(self):
+        """CIMD clients may omit redirect_uri only when a single exact URI exists."""
+        cimd_doc = CIMDDocument(
+            client_id=AnyHttpUrl("https://example.com/client.json"),
+            redirect_uris=["http://localhost:3000/callback"],
+        )
+        client = ProxyDCRClient(
+            client_id="https://example.com/client.json",
+            client_secret=None,
+            redirect_uris=None,
+            cimd_document=cimd_doc,
+        )
+
+        result = client.validate_redirect_uri(None)
+        assert result == AnyUrl("http://localhost:3000/callback")
+
+    def test_cimd_none_redirect_uri_respects_proxy_patterns(self):
+        """CIMD fallback redirect_uri must still satisfy proxy allowlist patterns."""
+        cimd_doc = CIMDDocument(
+            client_id=AnyHttpUrl("https://example.com/client.json"),
+            redirect_uris=["https://evil.com/callback"],
+        )
+        client = ProxyDCRClient(
+            client_id="https://example.com/client.json",
+            client_secret=None,
+            redirect_uris=None,
+            cimd_document=cimd_doc,
+            allowed_redirect_uri_patterns=["http://localhost:*"],
+        )
+
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(None)
+
+    def test_cimd_none_redirect_uri_wildcard_rejected(self):
+        """CIMD clients must specify redirect_uri when only wildcard patterns exist."""
+        cimd_doc = CIMDDocument(
+            client_id=AnyHttpUrl("https://example.com/client.json"),
+            redirect_uris=["http://localhost:*/callback"],
+        )
+        client = ProxyDCRClient(
+            client_id="https://example.com/client.json",
+            client_secret=None,
+            redirect_uris=None,
+            cimd_document=cimd_doc,
+        )
+
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(None)
+
+    def test_cimd_loopback_no_port_matches_dynamic_port(self):
+        """RFC 8252 §7.3: CIMD redirect_uris without port match any loopback port."""
+        cimd_doc = CIMDDocument(
+            client_id=AnyHttpUrl("https://example.com/client.json"),
+            redirect_uris=[
+                "http://localhost/callback",
+                "http://127.0.0.1/callback",
+            ],
+        )
+        client = ProxyDCRClient(
+            client_id="https://example.com/client.json",
+            client_secret=None,
+            redirect_uris=None,
+            cimd_document=cimd_doc,
+        )
+
+        # Dynamic ports should be accepted per RFC 8252 §7.3
+        assert client.validate_redirect_uri(AnyUrl("http://localhost:51353/callback"))
+        assert client.validate_redirect_uri(AnyUrl("http://127.0.0.1:3000/callback"))
+
+        # Wrong path should still be rejected
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("http://localhost:51353/other"))
+
+    def test_cimd_empty_proxy_allowlist_rejects_redirect_uri(self):
+        """An explicit empty proxy allowlist should reject all CIMD redirect URIs."""
+        cimd_doc = CIMDDocument(
+            client_id=AnyHttpUrl("https://example.com/client.json"),
+            redirect_uris=["http://localhost:3000/callback"],
+        )
+        client = ProxyDCRClient(
+            client_id="https://example.com/client.json",
+            client_secret=None,
+            redirect_uris=None,
+            cimd_document=cimd_doc,
+            allowed_redirect_uri_patterns=[],
+        )
+
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("http://localhost:3000/callback"))
+
+
+class TestOAuthProxyRedirectValidation:
+    """Test OAuth proxy with redirect URI validation."""
+
+    def test_proxy_default_has_no_server_redirect_pattern_restriction(self):
+        """OAuth proxy defaults to no server-level redirect URI pattern restriction."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=MockTokenVerifier(),
+            base_url="http://localhost:8000",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        # The proxy stores None when no server-level pattern restriction is configured.
+        assert proxy._allowed_client_redirect_uris is None
+
+    def test_proxy_custom_patterns(self):
+        """Test OAuth proxy with custom redirect patterns."""
+        custom_patterns = ["http://localhost:*", "https://*.myapp.com/*"]
+
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=MockTokenVerifier(),
+            base_url="http://localhost:8000",
+            allowed_client_redirect_uris=custom_patterns,
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        assert proxy._allowed_client_redirect_uris == custom_patterns
+
+    def test_proxy_empty_list_validation(self):
+        """Test OAuth proxy with empty list (allow none)."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=MockTokenVerifier(),
+            base_url="http://localhost:8000",
+            allowed_client_redirect_uris=[],
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        assert proxy._allowed_client_redirect_uris == []
+
+    async def test_proxy_register_client_uses_patterns(self):
+        """Test that registered clients use the configured patterns."""
+        custom_patterns = ["https://app.example.com/*"]
+
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=MockTokenVerifier(),
+            base_url="http://localhost:8000",
+            allowed_client_redirect_uris=custom_patterns,
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        # Register a client
+        from mcp.shared.auth import OAuthClientInformationFull
+
+        client_info = OAuthClientInformationFull(
+            client_id="new-client",
+            client_secret="new-secret",
+            redirect_uris=[AnyUrl("https://app.example.com/callback")],
+        )
+
+        await proxy.register_client(client_info)
+
+        # Get the registered client
+        registered = await proxy.get_client(
+            "new-client"
+        )  # Use the client ID we registered
+        assert isinstance(registered, ProxyDCRClient)
+        assert registered.allowed_redirect_uri_patterns == custom_patterns
+
+    async def test_proxy_unregistered_client_returns_none(self):
+        """Test that unregistered clients return None."""
+        custom_patterns = ["http://localhost:*", "http://127.0.0.1:*"]
+
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=MockTokenVerifier(),
+            base_url="http://localhost:8000",
+            allowed_client_redirect_uris=custom_patterns,
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        # Get an unregistered client
+        client = await proxy.get_client("unknown-client")
+        assert client is None
+
+
+class TestOAuthProxyCIMDClient:
+    """Test that CIMD clients obtained via proxy carry their document and apply dual validation."""
+
+    @pytest.fixture
+    def mock_dns(self):
+        """Mock DNS resolution to return test public IP."""
+        with patch(
+            "fastmcp.server.auth.ssrf.resolve_hostname",
+            return_value=[TEST_PUBLIC_IP],
+        ):
+            yield
+
+    async def test_proxy_get_client_returns_cimd_client(self, httpx_mock, mock_dns):
+        """CIMD client obtained via proxy's get_client has cimd_document attached."""
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "client_name": "CIMD App",
+            "redirect_uris": ["http://localhost:*/callback"],
+            "token_endpoint_auth_method": "none",
+        }
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={"content-length": "200"},
+        )
+
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=MockTokenVerifier(),
+            base_url="http://localhost:8000",
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        client = await proxy.get_client(url)
+        assert isinstance(client, ProxyDCRClient)
+        assert client.cimd_document is not None
+        assert client.cimd_document.client_name == "CIMD App"
+        assert client.client_id == url
+
+    async def test_proxy_cimd_dual_redirect_validation(self, httpx_mock, mock_dns):
+        """CIMD client from proxy enforces both CIMD redirect_uris and proxy patterns."""
+        url = "https://example.com/client.json"
+        doc_data = {
+            "client_id": url,
+            "client_name": "Dual Validation App",
+            "redirect_uris": [
+                "http://localhost:3000/callback",
+                "https://evil.com/callback",
+            ],
+            "token_endpoint_auth_method": "none",
+        }
+        httpx_mock.add_response(
+            json=doc_data,
+            headers={"content-length": "200"},
+        )
+
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://auth.example.com/authorize",
+            upstream_token_endpoint="https://auth.example.com/token",
+            upstream_client_id="test-client",
+            upstream_client_secret="test-secret",
+            token_verifier=MockTokenVerifier(),
+            base_url="http://localhost:8000",
+            allowed_client_redirect_uris=["http://localhost:*"],
+            jwt_signing_key="test-secret",
+            client_storage=MemoryStore(),
+        )
+
+        client = await proxy.get_client(url)
+        assert client is not None
+
+        # In CIMD AND matches proxy pattern → accepted
+        assert client.validate_redirect_uri(AnyUrl("http://localhost:3000/callback"))
+
+        # In CIMD but NOT in proxy pattern → rejected
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("https://evil.com/callback"))
+
+        # NOT in CIMD but matches proxy pattern → rejected
+        with pytest.raises(InvalidRedirectUriError):
+            client.validate_redirect_uri(AnyUrl("http://localhost:9999/other"))
diff --git a/tests/server/auth/test_oauth_proxy_storage.py b/tests/server/auth/test_oauth_proxy_storage.py
new file mode 100644
index 0000000..2cdac80
--- /dev/null
+++ b/tests/server/auth/test_oauth_proxy_storage.py
@@ -0,0 +1,214 @@
+"""Tests for OAuth proxy with persistent storage."""
+
+import tempfile
+import warnings
+from collections.abc import AsyncGenerator
+from pathlib import Path
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from inline_snapshot import snapshot
+from key_value.aio.protocols import AsyncKeyValue
+from key_value.aio.stores.filetree import FileTreeStore
+from key_value.aio.stores.memory import MemoryStore
+from mcp.shared.auth import OAuthClientInformationFull
+from pydantic import AnyUrl
+
+from fastmcp.server.auth.auth import TokenVerifier
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+
+
+class TestOAuthProxyStorage:
+    """Tests for OAuth proxy client storage functionality."""
+
+    @pytest.fixture
+    def jwt_verifier(self):
+        """Create a mock JWT verifier."""
+        verifier = Mock()
+        verifier.required_scopes = ["read", "write"]
+        verifier.verify_token = AsyncMock(return_value=None)
+        return verifier
+
+    @pytest.fixture
+    async def temp_storage(self) -> AsyncGenerator[FileTreeStore, None]:
+        """Create file-based storage for testing."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore", UserWarning)
+                yield FileTreeStore(data_directory=Path(temp_dir))
+
+    @pytest.fixture
+    def memory_storage(self) -> MemoryStore:
+        """Create in-memory storage for testing."""
+        return MemoryStore()
+
+    def create_proxy(
+        self, jwt_verifier: TokenVerifier, storage: AsyncKeyValue | None = None
+    ) -> OAuthProxy:
+        """Create an OAuth proxy with specified storage."""
+        return OAuthProxy(
+            upstream_authorization_endpoint="https://github.com/login/oauth/authorize",
+            upstream_token_endpoint="https://github.com/login/oauth/access_token",
+            upstream_client_id="test-client-id",
+            upstream_client_secret="test-client-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://myserver.com",
+            redirect_path="/auth/callback",
+            client_storage=storage,
+            jwt_signing_key="test-secret",
+        )
+
+    async def test_register_and_get_client(self, jwt_verifier, temp_storage):
+        """Test registering and retrieving a client."""
+        proxy = self.create_proxy(jwt_verifier, storage=temp_storage)
+
+        # Register client
+        client_info = OAuthClientInformationFull(
+            client_id="test-client-123",
+            client_secret="secret-456",
+            redirect_uris=[AnyUrl("http://localhost:8080/callback")],
+            grant_types=["authorization_code", "refresh_token"],
+            scope="read write",
+        )
+        await proxy.register_client(client_info)
+
+        # Get client back
+        client = await proxy.get_client("test-client-123")
+        assert client is not None
+        assert client.client_id == "test-client-123"
+        # Proxy uses token_endpoint_auth_method="none", so client_secret is not stored
+        assert client.client_secret is None
+        assert client.scope == "read write"
+
+    async def test_client_persists_across_proxy_instances(
+        self, jwt_verifier: TokenVerifier, temp_storage: AsyncKeyValue
+    ):
+        """Test that clients persist when proxy is recreated."""
+        # First proxy registers client
+        proxy1 = self.create_proxy(jwt_verifier, storage=temp_storage)
+        client_info = OAuthClientInformationFull(
+            client_id="persistent-client",
+            client_secret="persistent-secret",
+            redirect_uris=[AnyUrl("http://localhost:9999/callback")],
+            scope="openid profile",
+        )
+        await proxy1.register_client(client_info)
+
+        # Second proxy can retrieve it
+        proxy2 = self.create_proxy(jwt_verifier, storage=temp_storage)
+        client = await proxy2.get_client("persistent-client")
+        assert client is not None
+        # Proxy uses token_endpoint_auth_method="none", so client_secret is not stored
+        assert client.client_secret is None
+        assert client.scope == "openid profile"
+
+    async def test_nonexistent_client_returns_none(
+        self, jwt_verifier: TokenVerifier, temp_storage: AsyncKeyValue
+    ):
+        """Test that requesting non-existent client returns None."""
+        proxy = self.create_proxy(jwt_verifier, storage=temp_storage)
+        client = await proxy.get_client("does-not-exist")
+        assert client is None
+
+    async def test_proxy_dcr_client_redirect_validation(
+        self, jwt_verifier: TokenVerifier, temp_storage: AsyncKeyValue
+    ):
+        """Test that OAuthProxyClient is created with redirect URI patterns."""
+        proxy = OAuthProxy(
+            upstream_authorization_endpoint="https://github.com/login/oauth/authorize",
+            upstream_token_endpoint="https://github.com/login/oauth/access_token",
+            upstream_client_id="test-client-id",
+            upstream_client_secret="test-client-secret",
+            token_verifier=jwt_verifier,
+            base_url="https://myserver.com",
+            allowed_client_redirect_uris=["http://localhost:*"],
+            client_storage=temp_storage,
+            jwt_signing_key="test-secret",
+        )
+
+        client_info = OAuthClientInformationFull(
+            client_id="test-proxy-client",
+            client_secret="secret",
+            redirect_uris=[AnyUrl("http://localhost:8080/callback")],
+        )
+        await proxy.register_client(client_info)
+
+        # Get client back - should be OAuthProxyClient
+        client = await proxy.get_client("test-proxy-client")
+        assert client is not None
+
+        # OAuthProxyClient should validate dynamic localhost ports
+        validated = client.validate_redirect_uri(
+            AnyUrl("http://localhost:12345/callback")
+        )
+        assert validated is not None
+
+    async def test_in_memory_storage_option(self, jwt_verifier):
+        """Test using in-memory storage explicitly."""
+        storage = MemoryStore()
+        proxy = self.create_proxy(jwt_verifier, storage=storage)
+
+        client_info = OAuthClientInformationFull(
+            client_id="memory-client",
+            client_secret="memory-secret",
+            redirect_uris=[AnyUrl("http://localhost:8080/callback")],
+        )
+        await proxy.register_client(client_info)
+
+        client = await proxy.get_client("memory-client")
+        assert client is not None
+
+        # Create new proxy with same storage instance
+        proxy2 = self.create_proxy(jwt_verifier, storage=storage)
+        client2 = await proxy2.get_client("memory-client")
+        assert client2 is not None
+
+        # But new storage instance won't have it
+        proxy3 = self.create_proxy(jwt_verifier, storage=MemoryStore())
+        client3 = await proxy3.get_client("memory-client")
+        assert client3 is None
+
+    async def test_storage_data_structure(self, jwt_verifier, temp_storage):
+        """Test that storage uses proper structured format."""
+        proxy = self.create_proxy(jwt_verifier, storage=temp_storage)
+
+        client_info = OAuthClientInformationFull(
+            client_id="structured-client",
+            client_secret="secret",
+            redirect_uris=[AnyUrl("http://localhost:8080/callback")],
+        )
+        await proxy.register_client(client_info)
+
+        # Check raw storage data
+        raw_data = await temp_storage.get(
+            collection="mcp-oauth-proxy-clients", key="structured-client"
+        )
+        assert raw_data is not None
+        assert raw_data == snapshot(
+            {
+                "redirect_uris": ["http://localhost:8080/callback"],
+                "token_endpoint_auth_method": "none",
+                "grant_types": ["authorization_code", "refresh_token"],
+                "response_types": ["code"],
+                "scope": "read write",
+                "client_name": None,
+                "client_uri": None,
+                "logo_uri": None,
+                "contacts": None,
+                "tos_uri": None,
+                "policy_uri": None,
+                "jwks_uri": None,
+                "jwks": None,
+                "software_id": None,
+                "software_version": None,
+                "application_type": "native",
+                "issuer": None,
+                "client_id": "structured-client",
+                "client_secret": None,
+                "client_id_issued_at": None,
+                "client_secret_expires_at": None,
+                "allowed_redirect_uri_patterns": None,
+                "cimd_document": None,
+                "cimd_fetched_at": None,
+            }
+        )
diff --git a/tests/server/auth/test_oidc_proxy.py b/tests/server/auth/test_oidc_proxy.py
new file mode 100644
index 0000000..acbe6ef
--- /dev/null
+++ b/tests/server/auth/test_oidc_proxy.py
@@ -0,0 +1,984 @@
+"""Comprehensive tests for OIDC Proxy Provider functionality."""
+
+import json
+from unittest.mock import MagicMock, patch
+
+import pytest
+from httpx import Response
+from pydantic import AnyHttpUrl
+
+from fastmcp.server.auth.oidc_proxy import OIDCConfiguration, OIDCProxy
+from fastmcp.server.auth.providers.introspection import IntrospectionTokenVerifier
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+TEST_ISSUER = "https://example.com"
+TEST_AUTHORIZATION_ENDPOINT = "https://example.com/authorize"
+TEST_TOKEN_ENDPOINT = "https://example.com/oauth/token"
+
+TEST_CONFIG_URL = AnyHttpUrl("https://example.com/.well-known/openid-configuration")
+TEST_CLIENT_ID = "test-client-id"
+TEST_CLIENT_SECRET = "test-client-secret"
+TEST_BASE_URL = AnyHttpUrl("https://example.com:8000/")
+
+
+# =============================================================================
+# Test Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def valid_oidc_configuration_dict():
+    """Create a valid OIDC configuration dict for testing."""
+    return {
+        "issuer": TEST_ISSUER,
+        "authorization_endpoint": TEST_AUTHORIZATION_ENDPOINT,
+        "token_endpoint": TEST_TOKEN_ENDPOINT,
+        "jwks_uri": "https://example.com/.well-known/jwks.json",
+        "response_types_supported": ["code"],
+        "subject_types_supported": ["public"],
+        "id_token_signing_alg_values_supported": ["RS256"],
+    }
+
+
+@pytest.fixture
+def invalid_oidc_configuration_dict():
+    """Create an invalid OIDC configuration dict for testing."""
+    return {
+        "issuer": TEST_ISSUER,
+        "authorization_endpoint": TEST_AUTHORIZATION_ENDPOINT,
+        "token_endpoint": TEST_TOKEN_ENDPOINT,
+        "jwks_uri": "https://example.com/.well-known/jwks.json",
+    }
+
+
+@pytest.fixture
+def valid_google_oidc_configuration_dict():
+    """Create a valid Google OIDC configuration dict for testing.
+
+    See: https://accounts.google.com/.well-known/openid-configuration
+    """
+    google_config_str = """
+    {
+      "issuer": "https://accounts.google.com",
+      "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
+      "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
+      "token_endpoint": "https://oauth2.googleapis.com/token",
+      "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
+      "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
+      "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
+      "response_types_supported": [
+        "code",
+        "token",
+        "id_token",
+        "code token",
+        "code id_token",
+        "token id_token",
+        "code token id_token",
+        "none"
+      ],
+      "response_modes_supported": [
+        "query",
+        "fragment",
+        "form_post"
+      ],
+      "subject_types_supported": [
+        "public"
+      ],
+      "id_token_signing_alg_values_supported": [
+        "RS256"
+      ],
+      "scopes_supported": [
+        "openid",
+        "email",
+        "profile"
+      ],
+      "token_endpoint_auth_methods_supported": [
+        "client_secret_post",
+        "client_secret_basic"
+      ],
+      "claims_supported": [
+        "aud",
+        "email",
+        "email_verified",
+        "exp",
+        "family_name",
+        "given_name",
+        "iat",
+        "iss",
+        "name",
+        "picture",
+        "sub"
+      ],
+      "code_challenge_methods_supported": [
+        "plain",
+        "S256"
+      ],
+      "grant_types_supported": [
+        "authorization_code",
+        "refresh_token",
+        "urn:ietf:params:oauth:grant-type:device_code",
+        "urn:ietf:params:oauth:grant-type:jwt-bearer"
+      ]
+    }
+    """
+
+    return json.loads(google_config_str)
+
+
+@pytest.fixture
+def valid_auth0_oidc_configuration_dict():
+    """Create a valid Auth0 OIDC configuration dict for testing.
+
+    See: https://<tenant>.us.auth0.com/.well-known/openid-configuration
+    """
+    auth0_config_str = """
+    {
+      "issuer": "https://example.us.auth0.com/",
+      "authorization_endpoint": "https://example.us.auth0.com/authorize",
+      "token_endpoint": "https://example.us.auth0.com/oauth/token",
+      "device_authorization_endpoint": "https://example.us.auth0.com/oauth/device/code",
+      "userinfo_endpoint": "https://example.us.auth0.com/userinfo",
+      "mfa_challenge_endpoint": "https://example.us.auth0.com/mfa/challenge",
+      "jwks_uri": "https://example.us.auth0.com/.well-known/jwks.json",
+      "registration_endpoint": "https://example.us.auth0.com/oidc/register",
+      "revocation_endpoint": "https://example.us.auth0.com/oauth/revoke",
+      "scopes_supported": [
+        "openid",
+        "profile",
+        "offline_access",
+        "name",
+        "given_name",
+        "family_name",
+        "nickname",
+        "email",
+        "email_verified",
+        "picture",
+        "created_at",
+        "identities",
+        "phone",
+        "address"
+      ],
+      "response_types_supported": [
+        "code",
+        "token",
+        "id_token",
+        "code token",
+        "code id_token",
+        "token id_token",
+        "code token id_token"
+      ],
+      "code_challenge_methods_supported": [
+        "S256",
+        "plain"
+      ],
+      "response_modes_supported": [
+        "query",
+        "fragment",
+        "form_post"
+      ],
+      "subject_types_supported": [
+        "public"
+      ],
+      "token_endpoint_auth_methods_supported": [
+        "client_secret_basic",
+        "client_secret_post",
+        "private_key_jwt",
+        "tls_client_auth",
+        "self_signed_tls_client_auth"
+      ],
+      "token_endpoint_auth_signing_alg_values_supported": [
+        "RS256",
+        "RS384",
+        "PS256"
+      ],
+      "claims_supported": [
+        "aud",
+        "auth_time",
+        "created_at",
+        "email",
+        "email_verified",
+        "exp",
+        "family_name",
+        "given_name",
+        "iat",
+        "identities",
+        "iss",
+        "name",
+        "nickname",
+        "phone_number",
+        "picture",
+        "sub"
+      ],
+      "request_uri_parameter_supported": false,
+      "request_parameter_supported": true,
+      "id_token_signing_alg_values_supported": [
+        "HS256",
+        "RS256",
+        "PS256"
+      ],
+      "tls_client_certificate_bound_access_tokens": true,
+      "request_object_signing_alg_values_supported": [
+        "RS256",
+        "RS384",
+        "PS256"
+      ],
+      "backchannel_logout_supported": true,
+      "backchannel_logout_session_supported": true,
+      "end_session_endpoint": "https://example.us.auth0.com/oidc/logout",
+      "backchannel_authentication_endpoint": "https://example.us.auth0.com/bc-authorize",
+      "backchannel_token_delivery_modes_supported": [
+        "poll"
+      ],
+      "global_token_revocation_endpoint": "https://example.us.auth0.com/oauth/global-token-revocation/connection/{connectionName}",
+      "global_token_revocation_endpoint_auth_methods_supported": [
+        "global-token-revocation+jwt"
+      ]
+    }
+    """
+
+    return json.loads(auth0_config_str)
+
+
+# =============================================================================
+# Test Classes
+# =============================================================================
+
+
+def validate_config(config, source_dict):
+    """Validate an OIDC configuration against the source dict."""
+    for source_key, source_value in source_dict.items():
+        config_value = getattr(config, source_key, None)
+        if not hasattr(config, source_key):
+            continue
+
+        config_value = getattr(config, source_key, None)
+        if isinstance(config_value, AnyHttpUrl):
+            config_value = str(config_value)
+
+        assert config_value == source_value
+
+
+class TestOIDCConfiguration:
+    """Tests for OIDC configuration."""
+
+    def test_default_configuration(self, valid_oidc_configuration_dict):
+        """Test default configuration with valid dict."""
+        config = OIDCConfiguration.model_validate(valid_oidc_configuration_dict)
+        validate_config(config, valid_oidc_configuration_dict)
+
+    def test_default_configuration_with_issuer_trailing_slash(
+        self, valid_oidc_configuration_dict
+    ):
+        """Test default configuration with valid dict and issuer trailing slash."""
+        valid_oidc_configuration_dict["issuer"] += "/"
+        config = OIDCConfiguration.model_validate(valid_oidc_configuration_dict)
+        validate_config(config, valid_oidc_configuration_dict)
+
+    def test_explicit_strict_configuration(self, valid_oidc_configuration_dict):
+        """Test default configuration with explicit True strict setting and valid dict."""
+        valid_oidc_configuration_dict["strict"] = True
+        config = OIDCConfiguration.model_validate(valid_oidc_configuration_dict)
+        validate_config(config, valid_oidc_configuration_dict)
+
+    def test_explicit_strict_configuration_with_issuer_trailing_slash(
+        self, valid_oidc_configuration_dict
+    ):
+        """Test default configuration with explicit True strict setting, valid dict and issuer trailing slash."""
+        valid_oidc_configuration_dict["issuer"] += "/"
+        config = OIDCConfiguration.model_validate(valid_oidc_configuration_dict)
+        validate_config(config, valid_oidc_configuration_dict)
+
+    def test_default_configuration_raises_error(self, invalid_oidc_configuration_dict):
+        """Test default configuration with invalid dict."""
+        with pytest.raises(ValueError, match="Missing required configuration metadata"):
+            OIDCConfiguration.model_validate(invalid_oidc_configuration_dict)
+
+    def test_explicit_strict_configuration_raises_error(
+        self, invalid_oidc_configuration_dict
+    ):
+        """Test default configuration with explicit True strict setting and invalid dict."""
+        invalid_oidc_configuration_dict["strict"] = True
+        with pytest.raises(ValueError, match="Missing required configuration metadata"):
+            OIDCConfiguration.model_validate(invalid_oidc_configuration_dict)
+
+    def test_bad_url_raises_error(self, valid_oidc_configuration_dict):
+        """Test default configuration with bad URL setting."""
+        valid_oidc_configuration_dict["issuer"] = "not-a-URL"
+        with pytest.raises(ValueError, match="Invalid URL for configuration metadata"):
+            OIDCConfiguration.model_validate(valid_oidc_configuration_dict)
+
+    def test_explicit_strict_with_bad_url_raises_error(
+        self, valid_oidc_configuration_dict
+    ):
+        """Test default configuration with explicit True strict setting and bad URL setting."""
+        valid_oidc_configuration_dict["strict"] = True
+        valid_oidc_configuration_dict["issuer"] = "not-a-URL"
+        with pytest.raises(ValueError, match="Invalid URL for configuration metadata"):
+            OIDCConfiguration.model_validate(valid_oidc_configuration_dict)
+
+    def test_not_strict_configuration(self):
+        """Test default configuration with explicit False strict setting."""
+        config = OIDCConfiguration.model_validate({"strict": False})
+
+        assert config.issuer is None
+        assert config.authorization_endpoint is None
+        assert config.token_endpoint is None
+        assert config.jwks_uri is None
+        assert config.response_types_supported is None
+        assert config.subject_types_supported is None
+        assert config.id_token_signing_alg_values_supported is None
+
+    def test_not_strict_configuration_with_invalid_config(
+        self, invalid_oidc_configuration_dict
+    ):
+        """Test default configuration with explicit False strict setting."""
+        invalid_oidc_configuration_dict["strict"] = False
+        config = OIDCConfiguration.model_validate(invalid_oidc_configuration_dict)
+
+        validate_config(config, invalid_oidc_configuration_dict)
+
+    def test_not_strict_configuration_with_bad_url(self, valid_oidc_configuration_dict):
+        """Test default configuration with explicit False strict setting."""
+        valid_oidc_configuration_dict["strict"] = False
+        valid_oidc_configuration_dict["issuer"] = "not-a-url"
+        config = OIDCConfiguration.model_validate(valid_oidc_configuration_dict)
+
+        validate_config(config, valid_oidc_configuration_dict)
+
+    def test_google_configuration(self, valid_google_oidc_configuration_dict):
+        """Test Google configuration."""
+        config = OIDCConfiguration.model_validate(valid_google_oidc_configuration_dict)
+
+        validate_config(config, valid_google_oidc_configuration_dict)
+
+    def test_auth0_configuration(self, valid_auth0_oidc_configuration_dict):
+        """Test Auth0 configuration."""
+        config = OIDCConfiguration.model_validate(valid_auth0_oidc_configuration_dict)
+
+        validate_config(config, valid_auth0_oidc_configuration_dict)
+
+
+def validate_get_oidc_configuration(oidc_configuration, strict, timeout_seconds):
+    """Validate get_oidc_configuration call."""
+    with patch("httpx.get") as mock_get:
+        mock_response = MagicMock(spec=Response)
+        mock_response.json.return_value = oidc_configuration
+        mock_get.return_value = mock_response
+
+        config = OIDCConfiguration.get_oidc_configuration(
+            config_url=TEST_CONFIG_URL,
+            strict=strict,
+            timeout_seconds=timeout_seconds,
+        )
+
+        validate_config(config, oidc_configuration)
+
+        mock_get.assert_called_once()
+
+        call_args = mock_get.call_args
+        assert str(call_args[0][0]) == str(TEST_CONFIG_URL)
+
+        return call_args
+
+
+class TestGetOIDCConfiguration:
+    """Tests for getting OIDC configuration."""
+
+    def test_get_oidc_configuration(self, valid_oidc_configuration_dict):
+        """Test with valid response and explicit timeout."""
+        call_args = validate_get_oidc_configuration(
+            valid_oidc_configuration_dict, True, 10
+        )
+        assert call_args[1]["timeout"] == 10
+
+    def test_get_oidc_configuration_no_timeout(self, valid_oidc_configuration_dict):
+        """Test with valid response and no timeout."""
+        call_args = validate_get_oidc_configuration(
+            valid_oidc_configuration_dict, True, None
+        )
+        assert "timeout" not in call_args[1]
+
+    def test_get_oidc_configuration_raises_error(
+        self, invalid_oidc_configuration_dict
+    ) -> None:
+        """Test with invalid response."""
+        with pytest.raises(ValueError, match="Missing required configuration metadata"):
+            validate_get_oidc_configuration(invalid_oidc_configuration_dict, True, 10)
+
+    def test_get_oidc_configuration_not_strict(
+        self, invalid_oidc_configuration_dict
+    ) -> None:
+        """Test with invalid response and strict set to False."""
+        with patch("httpx.get") as mock_get:
+            mock_response = MagicMock(spec=Response)
+            mock_response.json.return_value = invalid_oidc_configuration_dict
+            mock_get.return_value = mock_response
+
+            OIDCConfiguration.get_oidc_configuration(
+                config_url=TEST_CONFIG_URL,
+                strict=False,
+                timeout_seconds=10,
+            )
+
+            mock_get.assert_called_once()
+
+            call_args = mock_get.call_args
+            assert str(call_args[0][0]) == str(TEST_CONFIG_URL)
+
+
+def validate_proxy(mock_get, proxy, oidc_config):
+    """Validate OIDC proxy."""
+    mock_get.assert_called_once()
+
+    call_args = mock_get.call_args
+    assert str(call_args[0][0]) == str(TEST_CONFIG_URL)
+
+    assert proxy._upstream_authorization_endpoint == TEST_AUTHORIZATION_ENDPOINT
+    assert proxy._upstream_token_endpoint == TEST_TOKEN_ENDPOINT
+    assert proxy._upstream_client_id == TEST_CLIENT_ID
+    assert proxy._upstream_client_secret is not None
+    assert proxy._upstream_client_secret.get_secret_value() == TEST_CLIENT_SECRET
+    assert str(proxy.base_url) == str(TEST_BASE_URL)
+    assert proxy.oidc_config == oidc_config
+
+
+class TestOIDCProxyInitialization:
+    """Tests for OIDC proxy initialization."""
+
+    def test_default_initialization(self, valid_oidc_configuration_dict):
+        """Test default initialization."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                jwt_signing_key="test-secret",
+            )
+
+            validate_proxy(mock_get, proxy, oidc_config)
+
+    def test_timeout_seconds_initialization(self, valid_oidc_configuration_dict):
+        """Test timeout seconds initialization."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                timeout_seconds=12,
+                jwt_signing_key="test-secret",
+            )
+
+            validate_proxy(mock_get, proxy, oidc_config)
+
+            call_args = mock_get.call_args
+            assert call_args[1]["timeout_seconds"] == 12
+
+    def test_token_verifier_initialization(self, valid_oidc_configuration_dict):
+        """Test token verifier initialization."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                algorithm="RS256",
+                audience="oidc-proxy-test-audience",
+                required_scopes=["required", "scopes"],
+                jwt_signing_key="test-secret",
+            )
+
+            validate_proxy(mock_get, proxy, oidc_config)
+
+            assert isinstance(proxy._token_validator, JWTVerifier)
+
+            assert proxy._token_validator.algorithm == "RS256"
+            assert proxy._token_validator.audience == "oidc-proxy-test-audience"
+            assert proxy._token_validator.required_scopes == ["required", "scopes"]
+
+    def test_extra_parameters_initialization(self, valid_oidc_configuration_dict):
+        """Test other parameters initialization."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                audience="oidc-proxy-test-audience",
+                jwt_signing_key="test-secret",
+            )
+
+            validate_proxy(mock_get, proxy, oidc_config)
+
+            assert proxy._extra_authorize_params == {
+                "audience": "oidc-proxy-test-audience"
+            }
+            assert proxy._extra_token_params == {"audience": "oidc-proxy-test-audience"}
+
+    def test_other_parameters_initialization(self, valid_oidc_configuration_dict):
+        """Test other parameters initialization."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                redirect_path="/oidc/proxy",
+                allowed_client_redirect_uris=["http://localhost:*"],
+                token_endpoint_auth_method="client_secret_post",
+                jwt_signing_key="test-secret",
+            )
+
+            validate_proxy(mock_get, proxy, oidc_config)
+
+            assert proxy._redirect_path == "/oidc/proxy"
+            assert proxy._allowed_client_redirect_uris == ["http://localhost:*"]
+            assert proxy._token_endpoint_auth_method == "client_secret_post"
+
+    def test_no_config_url_initialization_raises_error(
+        self, valid_oidc_configuration_dict
+    ):
+        """Test no config URL initialization."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            with pytest.raises(ValueError, match="Missing required config URL"):
+                OIDCProxy(
+                    config_url=None,  # type: ignore
+                    client_id=TEST_CLIENT_ID,
+                    client_secret=TEST_CLIENT_SECRET,
+                    base_url=TEST_BASE_URL,
+                    jwt_signing_key="test-secret",
+                )
+
+    def test_no_client_id_initialization_raises_error(
+        self, valid_oidc_configuration_dict
+    ):
+        """Test no client id initialization."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            with pytest.raises(ValueError, match="Missing required client id"):
+                OIDCProxy(
+                    config_url=TEST_CONFIG_URL,
+                    client_id=None,  # type: ignore
+                    client_secret=TEST_CLIENT_SECRET,
+                    base_url=TEST_BASE_URL,
+                )
+
+    def test_no_client_secret_initialization_raises_error(
+        self, valid_oidc_configuration_dict
+    ):
+        """Test no client secret initialization."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            with pytest.raises(
+                ValueError,
+                match="Either client_secret or jwt_signing_key must be provided",
+            ):
+                OIDCProxy(
+                    config_url=TEST_CONFIG_URL,
+                    client_id=TEST_CLIENT_ID,
+                    client_secret=None,
+                    base_url=TEST_BASE_URL,
+                )
+
+    def test_no_base_url_initialization_raises_error(
+        self, valid_oidc_configuration_dict
+    ):
+        """Test no base URL initialization."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            with pytest.raises(ValueError, match="Missing required base URL"):
+                OIDCProxy(
+                    config_url=TEST_CONFIG_URL,
+                    client_id=TEST_CLIENT_ID,
+                    client_secret=TEST_CLIENT_SECRET,
+                    base_url=None,  # type: ignore
+                )
+
+    def test_custom_token_verifier_initialization(self, valid_oidc_configuration_dict):
+        """Test initialization with custom token verifier."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            # Create custom verifier for opaque tokens
+            custom_verifier = IntrospectionTokenVerifier(
+                introspection_url="https://example.com/oauth/introspect",
+                client_id="introspection-client",
+                client_secret="introspection-secret",
+                required_scopes=["custom", "scopes"],
+            )
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                token_verifier=custom_verifier,
+                jwt_signing_key="test-secret",
+            )
+
+            validate_proxy(mock_get, proxy, oidc_config)
+
+            # Verify the custom verifier is used
+            assert proxy._token_validator is custom_verifier
+            assert isinstance(proxy._token_validator, IntrospectionTokenVerifier)
+
+            # Verify required_scopes are properly loaded from the custom verifier
+            assert proxy.required_scopes == ["custom", "scopes"]
+
+    def test_custom_token_verifier_with_algorithm_raises_error(
+        self, valid_oidc_configuration_dict
+    ):
+        """Test that providing algorithm with custom verifier raises error."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            custom_verifier = IntrospectionTokenVerifier(
+                introspection_url="https://example.com/oauth/introspect",
+                client_id="introspection-client",
+                client_secret="introspection-secret",
+            )
+
+            with pytest.raises(
+                ValueError,
+                match="Cannot specify 'algorithm' when providing a custom token_verifier",
+            ):
+                OIDCProxy(
+                    config_url=TEST_CONFIG_URL,
+                    client_id=TEST_CLIENT_ID,
+                    client_secret=TEST_CLIENT_SECRET,
+                    base_url=TEST_BASE_URL,
+                    token_verifier=custom_verifier,
+                    algorithm="RS256",  # This should cause an error
+                    jwt_signing_key="test-secret",
+                )
+
+    def test_custom_token_verifier_with_required_scopes_raises_error(
+        self, valid_oidc_configuration_dict
+    ):
+        """Test that providing required_scopes with custom verifier raises error."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            custom_verifier = IntrospectionTokenVerifier(
+                introspection_url="https://example.com/oauth/introspect",
+                client_id="introspection-client",
+                client_secret="introspection-secret",
+            )
+
+            with pytest.raises(
+                ValueError,
+                match="Cannot specify 'required_scopes' when providing a custom token_verifier",
+            ):
+                OIDCProxy(
+                    config_url=TEST_CONFIG_URL,
+                    client_id=TEST_CLIENT_ID,
+                    client_secret=TEST_CLIENT_SECRET,
+                    base_url=TEST_BASE_URL,
+                    token_verifier=custom_verifier,
+                    required_scopes=["read", "write"],  # This should cause an error
+                    jwt_signing_key="test-secret",
+                )
+
+    def test_custom_token_verifier_with_audience_allowed(
+        self, valid_oidc_configuration_dict
+    ):
+        """Test that providing audience with custom verifier is allowed (for OAuth flow)."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            custom_verifier = IntrospectionTokenVerifier(
+                introspection_url="https://example.com/oauth/introspect",
+                client_id="introspection-client",
+                client_secret="introspection-secret",
+            )
+
+            # This should NOT raise an error - audience is for OAuth flow
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                token_verifier=custom_verifier,
+                audience="test-audience",  # Should be allowed for OAuth flow
+                jwt_signing_key="test-secret",
+            )
+
+            validate_proxy(mock_get, proxy, oidc_config)
+            assert proxy._extra_authorize_params == {"audience": "test-audience"}
+            assert proxy._extra_token_params == {"audience": "test-audience"}
+
+    def test_extra_authorize_params_initialization(self, valid_oidc_configuration_dict):
+        """Test extra authorize params initialization."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                jwt_signing_key="test-secret",
+                extra_authorize_params={
+                    "prompt": "consent",
+                    "access_type": "offline",
+                },
+            )
+
+            validate_proxy(mock_get, proxy, oidc_config)
+
+            assert proxy._extra_authorize_params == {
+                "prompt": "consent",
+                "access_type": "offline",
+            }
+            # Token params should be empty since we didn't set them
+            assert proxy._extra_token_params == {}
+
+    def test_extra_token_params_initialization(self, valid_oidc_configuration_dict):
+        """Test extra token params initialization."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                jwt_signing_key="test-secret",
+                extra_token_params={"custom_param": "custom_value"},
+            )
+
+            validate_proxy(mock_get, proxy, oidc_config)
+
+            # Authorize params should be empty since we didn't set them
+            assert proxy._extra_authorize_params == {}
+            assert proxy._extra_token_params == {"custom_param": "custom_value"}
+
+    def test_extra_params_merge_with_audience(self, valid_oidc_configuration_dict):
+        """Test that extra params merge with audience, with user params taking precedence."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                audience="original-audience",
+                jwt_signing_key="test-secret",
+                extra_authorize_params={
+                    "prompt": "consent",
+                    "audience": "overridden-audience",  # Should override the audience param
+                },
+                extra_token_params={"custom": "value"},
+            )
+
+            validate_proxy(mock_get, proxy, oidc_config)
+
+            # User's extra_authorize_params should override audience
+            assert proxy._extra_authorize_params == {
+                "audience": "overridden-audience",
+                "prompt": "consent",
+            }
+            # Token params should have both audience (from audience param) and custom
+            assert proxy._extra_token_params == {
+                "audience": "original-audience",
+                "custom": "value",
+            }
+
+
+class TestDiscoveryTimeout:
+    """Discovery timeout defaults and propagation (#4353, #4365)."""
+
+    def _construct_and_capture_timeout(self, valid_oidc_configuration_dict, construct):
+        """Construct a provider with mocked discovery, returning the timeout used."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            mock_get.return_value = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            construct()
+            mock_get.assert_called_once()
+            return mock_get.call_args.kwargs["timeout_seconds"]
+
+    def test_oidc_proxy_defaults_to_bounded_timeout(
+        self, valid_oidc_configuration_dict
+    ):
+        """OIDCProxy applies a bounded discovery timeout when none is given."""
+        timeout = self._construct_and_capture_timeout(
+            valid_oidc_configuration_dict,
+            lambda: OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                jwt_signing_key="test-secret",
+            ),
+        )
+        assert timeout == 10
+
+    @pytest.mark.parametrize("timeout_seconds", [3, None])
+    def test_oidc_proxy_forwards_explicit_timeout(
+        self, valid_oidc_configuration_dict, timeout_seconds
+    ):
+        """An explicit timeout (including None as an escape hatch) is forwarded."""
+        timeout = self._construct_and_capture_timeout(
+            valid_oidc_configuration_dict,
+            lambda: OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                jwt_signing_key="test-secret",
+                timeout_seconds=timeout_seconds,
+            ),
+        )
+        assert timeout == timeout_seconds
+
+    def test_auth0_provider_defaults_to_bounded_timeout(
+        self, valid_oidc_configuration_dict
+    ):
+        """Auth0Provider exposes and defaults the discovery timeout."""
+        from fastmcp.server.auth.providers.auth0 import Auth0Provider
+
+        timeout = self._construct_and_capture_timeout(
+            valid_oidc_configuration_dict,
+            lambda: Auth0Provider(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                audience="test-audience",
+                base_url=TEST_BASE_URL,
+            ),
+        )
+        assert timeout == 10
+
+    def test_aws_cognito_provider_defaults_to_bounded_timeout(
+        self, valid_oidc_configuration_dict
+    ):
+        """AWSCognitoProvider exposes and defaults the discovery timeout."""
+        from fastmcp.server.auth.providers.aws import AWSCognitoProvider
+
+        timeout = self._construct_and_capture_timeout(
+            valid_oidc_configuration_dict,
+            lambda: AWSCognitoProvider(
+                user_pool_id="eu-central-1_XXXXXXXXX",
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+            ),
+        )
+        assert timeout == 10
+
+    def test_oci_provider_defaults_to_bounded_timeout(
+        self, valid_oidc_configuration_dict
+    ):
+        """OCIProvider exposes and defaults the discovery timeout."""
+        from fastmcp.server.auth.providers.oci import OCIProvider
+
+        timeout = self._construct_and_capture_timeout(
+            valid_oidc_configuration_dict,
+            lambda: OCIProvider(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+            ),
+        )
+        assert timeout == 10
diff --git a/tests/server/auth/test_oidc_proxy_token.py b/tests/server/auth/test_oidc_proxy_token.py
new file mode 100644
index 0000000..c261fb0
--- /dev/null
+++ b/tests/server/auth/test_oidc_proxy_token.py
@@ -0,0 +1,425 @@
+"""Tests for OIDC Proxy verify_id_token functionality."""
+
+from unittest.mock import patch
+
+import pytest
+from pydantic import AnyHttpUrl
+
+from fastmcp.server.auth.oauth_proxy.models import UpstreamTokenSet
+from fastmcp.server.auth.oidc_proxy import OIDCConfiguration, OIDCProxy
+from fastmcp.server.auth.providers.introspection import IntrospectionTokenVerifier
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+TEST_ISSUER = "https://example.com"
+TEST_AUTHORIZATION_ENDPOINT = "https://example.com/authorize"
+TEST_TOKEN_ENDPOINT = "https://example.com/oauth/token"
+
+TEST_CONFIG_URL = AnyHttpUrl("https://example.com/.well-known/openid-configuration")
+TEST_CLIENT_ID = "test-client-id"
+TEST_CLIENT_SECRET = "test-client-secret"
+TEST_BASE_URL = AnyHttpUrl("https://example.com:8000/")
+
+
+# =============================================================================
+# Shared Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def valid_oidc_configuration_dict():
+    """Create a valid OIDC configuration dict for testing."""
+    return {
+        "issuer": TEST_ISSUER,
+        "authorization_endpoint": TEST_AUTHORIZATION_ENDPOINT,
+        "token_endpoint": TEST_TOKEN_ENDPOINT,
+        "jwks_uri": "https://example.com/.well-known/jwks.json",
+        "response_types_supported": ["code"],
+        "subject_types_supported": ["public"],
+        "id_token_signing_alg_values_supported": ["RS256"],
+    }
+
+
+# =============================================================================
+# Test Helpers
+# =============================================================================
+
+
+def _make_upstream_token_set(*, id_token: str | None = None) -> UpstreamTokenSet:
+    """Create an UpstreamTokenSet with optional id_token."""
+    raw_token_data: dict[str, str] = {"access_token": "opaque-access-token"}
+    if id_token is not None:
+        raw_token_data["id_token"] = id_token
+    return UpstreamTokenSet(
+        upstream_token_id="test-id",
+        access_token="opaque-access-token",
+        refresh_token=None,
+        refresh_token_expires_at=None,
+        expires_at=9999999999.0,
+        token_type="Bearer",
+        scope="openid",
+        client_id="test-client",
+        created_at=1000000000.0,
+        raw_token_data=raw_token_data,
+    )
+
+
+# =============================================================================
+# Test Classes
+# =============================================================================
+
+
+class TestVerifyIdToken:
+    """Tests for verify_id_token functionality."""
+
+    def test_verify_id_token_disabled_by_default(self, valid_oidc_configuration_dict):
+        """Default behavior: verify the access_token."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                jwt_signing_key="test-secret",
+            )
+            token_set = _make_upstream_token_set(id_token="jwt-id-token")
+
+            assert proxy._get_verification_token(token_set) == "opaque-access-token"
+
+    def test_verify_id_token_returns_id_token(self, valid_oidc_configuration_dict):
+        """When enabled, verify the id_token instead of access_token."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                jwt_signing_key="test-secret",
+                verify_id_token=True,
+            )
+            token_set = _make_upstream_token_set(id_token="jwt-id-token")
+
+            assert proxy._get_verification_token(token_set) == "jwt-id-token"
+
+    def test_verify_id_token_returns_none_when_missing(
+        self, valid_oidc_configuration_dict
+    ):
+        """When enabled but id_token is absent, return None."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                jwt_signing_key="test-secret",
+                verify_id_token=True,
+            )
+            token_set = _make_upstream_token_set(id_token=None)
+
+            assert proxy._get_verification_token(token_set) is None
+
+    def test_verify_id_token_works_with_custom_verifier(
+        self, valid_oidc_configuration_dict
+    ):
+        """verify_id_token can be combined with a custom token_verifier."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            custom_verifier = IntrospectionTokenVerifier(
+                introspection_url="https://example.com/oauth/introspect",
+                client_id="introspection-client",
+                client_secret="introspection-secret",
+            )
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                jwt_signing_key="test-secret",
+                verify_id_token=True,
+                token_verifier=custom_verifier,
+            )
+            token_set = _make_upstream_token_set(id_token="jwt-id-token")
+
+            assert proxy._get_verification_token(token_set) == "jwt-id-token"
+            assert proxy._token_validator is custom_verifier
+
+    def test_verify_id_token_survives_refresh_without_id_token(
+        self, valid_oidc_configuration_dict
+    ):
+        """id_token from original auth is preserved when refresh omits it."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                jwt_signing_key="test-secret",
+                verify_id_token=True,
+            )
+
+            token_set = _make_upstream_token_set(id_token="original-id-token")
+
+            # Simulate a refresh response that omits id_token —
+            # the merge in exchange_refresh_token should preserve it
+            refresh_response = {
+                "access_token": "new-access-token",
+                "token_type": "Bearer",
+            }
+            token_set.raw_token_data = {**token_set.raw_token_data, **refresh_response}
+            token_set.access_token = "new-access-token"
+
+            assert proxy._get_verification_token(token_set) == "original-id-token"
+
+    def test_verify_id_token_updated_when_refresh_includes_it(
+        self, valid_oidc_configuration_dict
+    ):
+        """id_token is updated when refresh response includes a new one."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                jwt_signing_key="test-secret",
+                verify_id_token=True,
+            )
+
+            token_set = _make_upstream_token_set(id_token="original-id-token")
+
+            # Simulate a refresh response that includes a new id_token
+            refresh_response = {
+                "access_token": "new-access-token",
+                "id_token": "refreshed-id-token",
+            }
+            token_set.raw_token_data = {**token_set.raw_token_data, **refresh_response}
+            token_set.access_token = "new-access-token"
+
+            assert proxy._get_verification_token(token_set) == "refreshed-id-token"
+
+    def test_verify_id_token_uses_client_id_as_verifier_audience(
+        self, valid_oidc_configuration_dict
+    ):
+        """When verify_id_token is enabled, the verifier audience should be
+        client_id (matching id_token.aud), not the API audience parameter."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                jwt_signing_key="test-secret",
+                audience="https://api.example.com",
+                verify_id_token=True,
+            )
+
+            assert isinstance(proxy._token_validator, JWTVerifier)
+            assert proxy._token_validator.audience == TEST_CLIENT_ID
+
+            # The API audience should still be sent upstream
+            assert (
+                proxy._extra_authorize_params["audience"] == "https://api.example.com"
+            )
+            assert proxy._extra_token_params["audience"] == "https://api.example.com"
+
+    def test_verify_id_token_without_audience_uses_client_id(
+        self, valid_oidc_configuration_dict
+    ):
+        """When verify_id_token is enabled without an audience param,
+        the verifier audience should still be client_id."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                jwt_signing_key="test-secret",
+                verify_id_token=True,
+            )
+
+            assert isinstance(proxy._token_validator, JWTVerifier)
+            assert proxy._token_validator.audience == TEST_CLIENT_ID
+
+    def test_verify_id_token_does_not_enforce_scopes_on_verifier(
+        self, valid_oidc_configuration_dict
+    ):
+        """When verify_id_token is enabled, required_scopes should not be
+        passed to the JWTVerifier since id_tokens don't carry scope claims."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                jwt_signing_key="test-secret",
+                required_scopes=["read", "write"],
+                verify_id_token=True,
+            )
+
+            assert isinstance(proxy._token_validator, JWTVerifier)
+            assert proxy._token_validator.required_scopes == []
+
+            # Scopes should still be advertised via the proxy's required_scopes
+            assert proxy.required_scopes == ["read", "write"]
+
+            # Derived scope state should also be recomputed
+            assert proxy._default_scope_str == "read write"
+            assert proxy.client_registration_options is not None
+            assert proxy.client_registration_options.valid_scopes == [
+                "read",
+                "write",
+            ]
+
+
+class TestUsesAlternateVerification:
+    """Tests for _uses_alternate_verification intent-based flag."""
+
+    def test_disabled_by_default(self, valid_oidc_configuration_dict):
+        """OIDCProxy without verify_id_token returns False."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                jwt_signing_key="test-secret",
+            )
+
+            assert proxy._uses_alternate_verification() is False
+
+    def test_enabled_with_verify_id_token(self, valid_oidc_configuration_dict):
+        """OIDCProxy with verify_id_token=True returns True."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                jwt_signing_key="test-secret",
+                verify_id_token=True,
+            )
+
+            assert proxy._uses_alternate_verification() is True
+
+    def test_scope_patch_applied_when_tokens_identical(
+        self, valid_oidc_configuration_dict
+    ):
+        """Regression test: scopes must be patched even when id_token and
+        access_token carry the same JWT value (fixes #3461)."""
+        with patch(
+            "fastmcp.server.auth.oidc_proxy.OIDCConfiguration.get_oidc_configuration"
+        ) as mock_get:
+            oidc_config = OIDCConfiguration.model_validate(
+                valid_oidc_configuration_dict
+            )
+            mock_get.return_value = oidc_config
+
+            proxy = OIDCProxy(
+                config_url=TEST_CONFIG_URL,
+                client_id=TEST_CLIENT_ID,
+                client_secret=TEST_CLIENT_SECRET,
+                base_url=TEST_BASE_URL,
+                jwt_signing_key="test-secret",
+                verify_id_token=True,
+            )
+
+            # Same JWT for both access_token and id_token — the scenario
+            # that triggered the bug.
+            same_jwt = "eyJhbGciOiJSUzI1NiJ9.identical-token"
+            token_set = UpstreamTokenSet(
+                upstream_token_id="test-id",
+                access_token=same_jwt,
+                refresh_token=None,
+                refresh_token_expires_at=None,
+                expires_at=9999999999.0,
+                token_type="Bearer",
+                scope="openid offline_access",
+                client_id="test-client",
+                created_at=1000000000.0,
+                raw_token_data={
+                    "access_token": same_jwt,
+                    "id_token": same_jwt,
+                },
+            )
+
+            # _uses_alternate_verification should be True regardless of
+            # token value equality
+            assert proxy._uses_alternate_verification() is True
+            # _get_verification_token returns the id_token (same value)
+            assert proxy._get_verification_token(token_set) == same_jwt
+            # The key point: even though the tokens are equal, the intent
+            # flag ensures load_access_token will patch scopes
diff --git a/tests/server/auth/test_redirect_validation.py b/tests/server/auth/test_redirect_validation.py
new file mode 100644
index 0000000..58bb295
--- /dev/null
+++ b/tests/server/auth/test_redirect_validation.py
@@ -0,0 +1,354 @@
+"""Tests for redirect URI validation in OAuth flows."""
+
+import pytest
+from pydantic import AnyUrl
+
+from fastmcp.server.auth.redirect_validation import (
+    DEFAULT_LOCALHOST_PATTERNS,
+    matches_allowed_pattern,
+    validate_redirect_uri,
+)
+
+
+class TestMatchesAllowedPattern:
+    """Test wildcard pattern matching for redirect URIs."""
+
+    def test_exact_match(self):
+        """Test exact URI matching without wildcards."""
+        assert matches_allowed_pattern(
+            "http://localhost:3000/callback", "http://localhost:3000/callback"
+        )
+        assert not matches_allowed_pattern(
+            "http://localhost:3000/callback", "http://localhost:3001/callback"
+        )
+
+    def test_port_wildcard(self):
+        """Test wildcard matching for ports."""
+        pattern = "http://localhost:*/callback"
+        assert matches_allowed_pattern("http://localhost:3000/callback", pattern)
+        assert matches_allowed_pattern("http://localhost:54321/callback", pattern)
+        assert not matches_allowed_pattern("http://example.com:3000/callback", pattern)
+
+    def test_path_wildcard(self):
+        """Test wildcard matching for paths."""
+        pattern = "http://localhost:3000/*"
+        assert matches_allowed_pattern("http://localhost:3000/callback", pattern)
+        assert matches_allowed_pattern("http://localhost:3000/auth/callback", pattern)
+        assert not matches_allowed_pattern("http://localhost:3001/callback", pattern)
+
+    def test_subdomain_wildcard(self):
+        """Test wildcard matching for subdomains."""
+        pattern = "https://*.example.com/callback"
+        assert matches_allowed_pattern("https://app.example.com/callback", pattern)
+        assert matches_allowed_pattern("https://api.example.com/callback", pattern)
+        assert not matches_allowed_pattern("https://example.com/callback", pattern)
+        assert not matches_allowed_pattern("http://app.example.com/callback", pattern)
+
+    def test_multiple_wildcards(self):
+        """Test patterns with multiple wildcards."""
+        pattern = "https://*.example.com:*/auth/*"
+        assert matches_allowed_pattern(
+            "https://app.example.com:8080/auth/callback", pattern
+        )
+        assert matches_allowed_pattern(
+            "https://api.example.com:3000/auth/redirect", pattern
+        )
+        assert not matches_allowed_pattern(
+            "http://app.example.com:8080/auth/callback", pattern
+        )
+
+
+class TestValidateRedirectUri:
+    """Test redirect URI validation with pattern lists."""
+
+    def test_none_redirect_uri_allowed(self):
+        """Test that None redirect URI is always allowed."""
+        assert validate_redirect_uri(None, None)
+        assert validate_redirect_uri(None, [])
+        assert validate_redirect_uri(None, ["http://localhost:*"])
+
+    @pytest.mark.parametrize(
+        "uri",
+        [
+            "http://localhost:3000",
+            "http://127.0.0.1:8080",
+            "http://example.com",
+            "https://app.example.com",
+            "https://claude.ai/api/mcp/auth_callback",
+            "cursor://anysphere.cursor-mcp/oauth/callback",
+        ],
+    )
+    def test_default_allows_dcr_compatible_redirects(self, uri: str):
+        """None preserves broad DCR compatibility for ordinary redirect URIs."""
+        assert validate_redirect_uri(uri, None)
+
+    @pytest.mark.parametrize(
+        "uri",
+        [
+            "javascript:alert(document.cookie)//",
+            "JaVaScRiPt:alert(document.cookie)//",
+            "data:text/html,<script>alert(1)</script>",
+            "file:///tmp/callback",
+            "vbscript:msgbox(1)",
+        ],
+    )
+    def test_default_rejects_unsafe_browser_schemes(self, uri: str):
+        """Default DCR compatibility must not allow active browser schemes."""
+        assert not validate_redirect_uri(uri, None)
+
+    @pytest.mark.parametrize(
+        "uri,pattern",
+        [
+            ("javascript:alert(document.cookie)//", "javascript:*"),
+            ("data:text/html,<script>alert(1)</script>", "data:*"),
+            ("file:///tmp/callback", "file:///*"),
+            ("vbscript:msgbox(1)", "vbscript:*"),
+        ],
+    )
+    def test_custom_patterns_cannot_allow_unsafe_browser_schemes(
+        self, uri: str, pattern: str
+    ):
+        """Unsafe browser schemes stay blocked even if a pattern names them."""
+        assert not validate_redirect_uri(uri, [pattern])
+
+    def test_empty_list_allows_none(self):
+        """Test that empty list allows no redirect URIs."""
+        assert not validate_redirect_uri("http://localhost:3000", [])
+        assert not validate_redirect_uri("http://example.com", [])
+        assert not validate_redirect_uri("https://anywhere.com:9999/path", [])
+
+    def test_custom_patterns(self):
+        """Test validation with custom pattern list."""
+        patterns = [
+            "http://localhost:*",
+            "https://app.example.com/*",
+            "https://*.trusted.io/*",
+        ]
+
+        # Allowed URIs
+        assert validate_redirect_uri("http://localhost:3000", patterns)
+        assert validate_redirect_uri("https://app.example.com/callback", patterns)
+        assert validate_redirect_uri("https://api.trusted.io/auth", patterns)
+
+        # Rejected URIs
+        assert not validate_redirect_uri("http://127.0.0.1:3000", patterns)
+        assert not validate_redirect_uri("https://other.example.com/callback", patterns)
+        assert not validate_redirect_uri("http://app.example.com/callback", patterns)
+
+    def test_anyurl_conversion(self):
+        """Test that AnyUrl objects are properly converted to strings."""
+        patterns = ["http://localhost:*"]
+        uri = AnyUrl("http://localhost:3000/callback")
+        assert validate_redirect_uri(uri, patterns)
+
+        uri = AnyUrl("http://example.com/callback")
+        assert not validate_redirect_uri(uri, patterns)
+
+
+class TestSecurityBypass:
+    """Test protection against redirect URI security bypass attacks."""
+
+    def test_userinfo_bypass_blocked(self):
+        """Test that userinfo-style bypasses are blocked.
+
+        Attack: http://localhost@evil.com/callback would match http://localhost:*
+        with naive string matching, but actually points to evil.com.
+        """
+        pattern = "http://localhost:*"
+
+        # These should be blocked - the "host" is actually in the userinfo
+        assert not matches_allowed_pattern(
+            "http://localhost@evil.com/callback", pattern
+        )
+        assert not matches_allowed_pattern(
+            "http://localhost:3000@malicious.io/callback", pattern
+        )
+        assert not matches_allowed_pattern(
+            "http://user:pass@localhost:3000/callback", pattern
+        )
+
+    def test_userinfo_bypass_with_subdomain_pattern(self):
+        """Test userinfo bypass with subdomain wildcard patterns."""
+        pattern = "https://*.example.com/callback"
+
+        # Blocked: userinfo tricks
+        assert not matches_allowed_pattern(
+            "https://app.example.com@attacker.com/callback", pattern
+        )
+        assert not matches_allowed_pattern(
+            "https://user:pass@app.example.com/callback", pattern
+        )
+
+    def test_legitimate_uris_still_work(self):
+        """Test that legitimate URIs work after security hardening."""
+        pattern = "http://localhost:*"
+        assert matches_allowed_pattern("http://localhost:3000/callback", pattern)
+        assert matches_allowed_pattern("http://localhost:8080/auth", pattern)
+
+        pattern = "https://*.example.com/callback"
+        assert matches_allowed_pattern("https://app.example.com/callback", pattern)
+
+    def test_scheme_mismatch_blocked(self):
+        """Test that scheme mismatches are blocked."""
+        assert not matches_allowed_pattern(
+            "http://localhost:3000/callback", "https://localhost:*"
+        )
+        assert not matches_allowed_pattern(
+            "https://localhost:3000/callback", "http://localhost:*"
+        )
+
+    def test_host_mismatch_blocked(self):
+        """Test that host mismatches are blocked even with wildcards."""
+        pattern = "http://localhost:*"
+        assert not matches_allowed_pattern("http://127.0.0.1:3000/callback", pattern)
+        assert not matches_allowed_pattern("http://example.com:3000/callback", pattern)
+
+
+class TestDotSegmentBypass:
+    """Tests for dot-segment bypass of path allowlists.
+
+    A pattern like `/oauth/callback/*` would otherwise match
+    `/oauth/callback/../../steal` via `fnmatch`, because `*` matches across
+    `/`. Browsers resolve the dot-segments on redirect, landing at a path
+    outside the allowlist prefix. The validator rejects dot-segments (raw
+    and percent-encoded) up front.
+    """
+
+    def test_traversal_segments_rejected(self):
+        pattern = "https://app.example.com/oauth/callback/*"
+        assert not matches_allowed_pattern(
+            "https://app.example.com/oauth/callback/../../steal", pattern
+        )
+
+    def test_percent_encoded_traversal_rejected(self):
+        pattern = "https://app.example.com/oauth/callback/*"
+        for encoded in ("%2e%2e", "%2E%2E", "%2e%2E"):
+            assert not matches_allowed_pattern(
+                f"https://app.example.com/oauth/callback/{encoded}/{encoded}/steal",
+                pattern,
+            )
+
+    def test_single_dot_segment_rejected(self):
+        pattern = "https://app.example.com/oauth/callback/*"
+        assert not matches_allowed_pattern(
+            "https://app.example.com/oauth/callback/./foo", pattern
+        )
+
+    def test_trailing_dotdot_rejected(self):
+        pattern = "https://app.example.com/oauth/callback/*"
+        assert not matches_allowed_pattern(
+            "https://app.example.com/oauth/callback/foo/..", pattern
+        )
+
+    def test_percent_encoded_single_dot_rejected(self):
+        pattern = "https://app.example.com/oauth/callback/*"
+        assert not matches_allowed_pattern(
+            "https://app.example.com/oauth/callback/%2e/foo", pattern
+        )
+
+    def test_mixed_raw_and_encoded_rejected(self):
+        pattern = "https://app.example.com/oauth/callback/*"
+        assert not matches_allowed_pattern(
+            "https://app.example.com/oauth/callback/..%2fsteal", pattern
+        )
+
+    def test_legitimate_nested_paths_still_match(self):
+        """Paths that happen to contain dots in segment names must still match."""
+        pattern = "https://app.example.com/oauth/callback/*"
+        for uri in (
+            "https://app.example.com/oauth/callback/foo",
+            "https://app.example.com/oauth/callback/deeply/nested/path",
+            "https://app.example.com/oauth/callback/file.ext",
+            "https://app.example.com/oauth/callback/v1.2.3/item",
+        ):
+            assert matches_allowed_pattern(uri, pattern), uri
+
+
+class TestLoopbackPortMatching:
+    """Test RFC 8252 §7.3: loopback URIs with no port in pattern match any port."""
+
+    def test_localhost_no_port_matches_any_port(self):
+        """Pattern http://localhost/callback should match any port on localhost."""
+        pattern = "http://localhost/callback"
+        assert matches_allowed_pattern("http://localhost:51353/callback", pattern)
+        assert matches_allowed_pattern("http://localhost:3000/callback", pattern)
+        assert matches_allowed_pattern("http://localhost:80/callback", pattern)
+
+    def test_localhost_no_port_no_path_matches_any_port(self):
+        """Pattern http://localhost should match any port on localhost."""
+        pattern = "http://localhost"
+        assert matches_allowed_pattern("http://localhost:51353", pattern)
+        assert matches_allowed_pattern("http://localhost:3000/callback", pattern)
+
+    def test_127_0_0_1_no_port_matches_any_port(self):
+        """Pattern http://127.0.0.1/callback should match any port on 127.0.0.1."""
+        pattern = "http://127.0.0.1/callback"
+        assert matches_allowed_pattern("http://127.0.0.1:51353/callback", pattern)
+        assert matches_allowed_pattern("http://127.0.0.1:3000/callback", pattern)
+
+    def test_ipv6_loopback_no_port_matches_any_port(self):
+        """Pattern http://[::1]/callback should match any port on [::1]."""
+        pattern = "http://[::1]/callback"
+        assert matches_allowed_pattern("http://[::1]:51353/callback", pattern)
+        assert matches_allowed_pattern("http://[::1]:3000/callback", pattern)
+
+    def test_non_loopback_no_port_requires_default_port(self):
+        """Non-loopback patterns without port should still require default port."""
+        pattern = "http://example.com/callback"
+        # Should only match port 80 (default for HTTP)
+        assert matches_allowed_pattern("http://example.com/callback", pattern)
+        assert matches_allowed_pattern("http://example.com:80/callback", pattern)
+        assert not matches_allowed_pattern("http://example.com:3000/callback", pattern)
+
+    def test_loopback_explicit_port_requires_exact_match(self):
+        """Loopback patterns with an explicit port should still require exact match."""
+        pattern = "http://localhost:8080/callback"
+        assert matches_allowed_pattern("http://localhost:8080/callback", pattern)
+        assert not matches_allowed_pattern("http://localhost:3000/callback", pattern)
+
+    def test_loopback_no_port_still_checks_scheme(self):
+        """Scheme must still match even for loopback URIs."""
+        pattern = "http://localhost/callback"
+        assert not matches_allowed_pattern("https://localhost:3000/callback", pattern)
+
+    def test_loopback_no_port_still_checks_host(self):
+        """Host must still match even for loopback URIs."""
+        pattern = "http://localhost/callback"
+        assert not matches_allowed_pattern("http://example.com:3000/callback", pattern)
+
+    def test_loopback_no_port_still_checks_path(self):
+        """Path must still match even for loopback URIs."""
+        pattern = "http://localhost/callback"
+        assert not matches_allowed_pattern("http://localhost:3000/other", pattern)
+
+
+class TestDefaultPatterns:
+    """Test the default localhost patterns constant."""
+
+    def test_default_patterns_exist(self):
+        """Test that default patterns are defined."""
+        assert DEFAULT_LOCALHOST_PATTERNS is not None
+        assert len(DEFAULT_LOCALHOST_PATTERNS) > 0
+
+    def test_default_patterns_include_localhost(self):
+        """Test that default patterns include localhost variations."""
+        assert "http://localhost:*" in DEFAULT_LOCALHOST_PATTERNS
+        assert "http://127.0.0.1:*" in DEFAULT_LOCALHOST_PATTERNS
+
+    def test_explicit_localhost_patterns(self):
+        """Test that explicitly passing DEFAULT_LOCALHOST_PATTERNS restricts to localhost."""
+        # Localhost patterns should be allowed
+        assert validate_redirect_uri(
+            "http://localhost:3000", DEFAULT_LOCALHOST_PATTERNS
+        )
+        assert validate_redirect_uri(
+            "http://127.0.0.1:8080", DEFAULT_LOCALHOST_PATTERNS
+        )
+
+        # Non-localhost should be rejected
+        assert not validate_redirect_uri(
+            "http://example.com", DEFAULT_LOCALHOST_PATTERNS
+        )
+        assert not validate_redirect_uri(
+            "https://claude.ai/api/mcp/auth_callback", DEFAULT_LOCALHOST_PATTERNS
+        )
diff --git a/tests/server/auth/test_remote_auth_provider.py b/tests/server/auth/test_remote_auth_provider.py
new file mode 100644
index 0000000..bc37dec
--- /dev/null
+++ b/tests/server/auth/test_remote_auth_provider.py
@@ -0,0 +1,572 @@
+import httpx
+import pytest
+from pydantic import AnyHttpUrl
+
+from fastmcp import FastMCP
+from fastmcp.server.auth import RemoteAuthProvider
+from fastmcp.server.auth.providers.jwt import StaticTokenVerifier
+
+
+@pytest.fixture
+def test_tokens():
+    """Standard test tokens fixture for all auth tests."""
+    return {
+        "test_token": {
+            "client_id": "test-client",
+            "scopes": ["read", "write"],
+        }
+    }
+
+
+class TestRemoteAuthProvider:
+    """Test suite for RemoteAuthProvider."""
+
+    def test_init(self, test_tokens):
+        """Test RemoteAuthProvider initialization."""
+        token_verifier = StaticTokenVerifier(tokens=test_tokens)
+        auth_servers = [AnyHttpUrl("https://auth.example.com")]
+
+        provider = RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=auth_servers,
+            base_url="https://api.example.com",
+        )
+
+        assert provider.token_verifier is token_verifier
+        assert provider.authorization_servers == auth_servers
+        assert provider.base_url == AnyHttpUrl("https://api.example.com/")
+
+    async def test_verify_token_delegates_to_verifier(self, test_tokens):
+        """Test that verify_token delegates to the token verifier."""
+        # Use a different token for this specific test
+        tokens = {
+            "valid_token": {
+                "client_id": "test-client",
+                "scopes": [],
+            }
+        }
+        token_verifier = StaticTokenVerifier(tokens=tokens)
+
+        provider = RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+
+        # Valid token
+        result = await provider.verify_token("valid_token")
+        assert result is not None
+        assert result.token == "valid_token"
+        assert result.client_id == "test-client"
+
+        # Invalid token
+        result = await provider.verify_token("invalid_token")
+        assert result is None
+
+    def test_get_routes_creates_protected_resource_routes(self, test_tokens):
+        """Test that get_routes creates protected resource routes."""
+        token_verifier = StaticTokenVerifier(tokens=test_tokens)
+        auth_servers = [AnyHttpUrl("https://auth.example.com")]
+
+        provider = RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=auth_servers,
+            base_url="https://api.example.com",
+        )
+
+        routes = provider.get_routes()
+        assert len(routes) == 1
+
+        # Check that the route is the OAuth protected resource metadata endpoint
+        # When called without mcp_path, it creates route at /.well-known/oauth-protected-resource
+        route = routes[0]
+        assert route.path == "/.well-known/oauth-protected-resource"
+        assert route.methods is not None
+        assert "GET" in route.methods
+
+    def test_get_resource_url_with_well_known_path(self):
+        """Test _get_resource_url returns correct URL for .well-known path."""
+        tokens = {
+            "test_token": {
+                "client_id": "test-client",
+                "scopes": ["read"],
+            }
+        }
+        token_verifier = StaticTokenVerifier(tokens=tokens)
+        provider = RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+
+        metadata_url = provider._get_resource_url(
+            "/.well-known/oauth-protected-resource/mcp"
+        )
+        assert metadata_url == AnyHttpUrl(
+            "https://api.example.com/.well-known/oauth-protected-resource/mcp"
+        )
+
+    def test_get_resource_url_with_nested_base_url(self):
+        """Test _get_resource_url returns correct URL for .well-known path with nested base_url."""
+        tokens = {
+            "test_token": {
+                "client_id": "test-client",
+                "scopes": ["read"],
+            }
+        }
+        token_verifier = StaticTokenVerifier(tokens=tokens)
+        provider = RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com/v1/",
+        )
+
+        metadata_url = provider._get_resource_url(
+            "/.well-known/oauth-protected-resource/mcp"
+        )
+        assert metadata_url == AnyHttpUrl(
+            "https://api.example.com/v1/.well-known/oauth-protected-resource/mcp"
+        )
+
+    def test_get_resource_url_handles_trailing_slash(self):
+        """Test _get_resource_url handles trailing slash correctly."""
+        tokens = {
+            "test_token": {
+                "client_id": "test-client",
+                "scopes": ["read"],
+            }
+        }
+        token_verifier = StaticTokenVerifier(tokens=tokens)
+        provider = RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com/",
+        )
+
+        metadata_url = provider._get_resource_url(
+            "/.well-known/oauth-protected-resource/mcp"
+        )
+        assert metadata_url == AnyHttpUrl(
+            "https://api.example.com/.well-known/oauth-protected-resource/mcp"
+        )
+
+    def test_get_resource_url_uses_resource_base_url_when_provided(self, test_tokens):
+        """Test protected resource URLs are derived from resource_base_url when provided."""
+        token_verifier = StaticTokenVerifier(tokens=test_tokens)
+        provider = RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://auth.example.com/proxy",
+            resource_base_url="https://api.example.com",
+        )
+
+        assert provider._get_resource_url("/mcp") == AnyHttpUrl(
+            "https://api.example.com/mcp"
+        )
+
+    def test_init_preserves_legacy_positional_scopes_supported_slot(self, test_tokens):
+        """Legacy positional scopes_supported should not bind to resource_base_url."""
+        token_verifier = StaticTokenVerifier(tokens=test_tokens)
+        provider = RemoteAuthProvider(
+            token_verifier,
+            [AnyHttpUrl("https://auth.example.com")],
+            "https://api.example.com",
+            ["read"],
+        )
+
+        assert provider._scopes_supported == ["read"]
+        assert provider.resource_base_url is None
+        assert provider._get_resource_url("/mcp") == AnyHttpUrl(
+            "https://api.example.com/mcp"
+        )
+
+
+class TestRemoteAuthProviderIntegration:
+    """Integration tests for RemoteAuthProvider with FastMCP server."""
+
+    @pytest.fixture
+    def basic_auth_provider(self, test_tokens):
+        """Basic RemoteAuthProvider fixture for testing."""
+        token_verifier = StaticTokenVerifier(tokens=test_tokens)
+        return RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+
+    def _create_test_auth_provider(
+        self, base_url="https://api.example.com", test_tokens=None, **kwargs
+    ):
+        """Helper to create a test RemoteAuthProvider with StaticTokenVerifier."""
+        tokens = kwargs.get(
+            "tokens",
+            test_tokens
+            or {
+                "test_token": {
+                    "client_id": "test-client",
+                    "scopes": ["read", "write"],
+                }
+            },
+        )
+        token_verifier = StaticTokenVerifier(tokens=tokens)
+        return RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url=base_url,
+        )
+
+    async def test_protected_resource_metadata_endpoint_status_code(
+        self, basic_auth_provider
+    ):
+        """Test that the protected resource metadata endpoint returns 200."""
+        mcp = FastMCP("test-server", auth=basic_auth_provider)
+        mcp_http_app = mcp.http_app()
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=mcp_http_app),
+            base_url="https://api.example.com",
+        ) as client:
+            # The metadata URL is path-aware per RFC 9728
+            response = await client.get("/.well-known/oauth-protected-resource/mcp")
+            assert response.status_code == 200
+
+    async def test_protected_resource_metadata_endpoint_resource_field(self):
+        """Test that the protected resource metadata endpoint returns correct resource field."""
+        auth_provider = self._create_test_auth_provider()
+
+        mcp = FastMCP("test-server", auth=auth_provider)
+        mcp_http_app = mcp.http_app()
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=mcp_http_app),
+            base_url="https://api.example.com",
+        ) as client:
+            # The metadata URL is path-aware per RFC 9728
+            response = await client.get("/.well-known/oauth-protected-resource/mcp")
+            data = response.json()
+
+            # This is the key test - ensure resource field contains the full MCP URL
+            assert data["resource"] == "https://api.example.com/mcp"
+
+    async def test_protected_resource_metadata_endpoint_authorization_servers_field(
+        self,
+    ):
+        """Test that the protected resource metadata endpoint returns correct authorization_servers field."""
+        auth_provider = self._create_test_auth_provider()
+
+        mcp = FastMCP("test-server", auth=auth_provider)
+        mcp_http_app = mcp.http_app()
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=mcp_http_app),
+            base_url="https://api.example.com",
+        ) as client:
+            # The metadata URL is path-aware per RFC 9728
+            response = await client.get("/.well-known/oauth-protected-resource/mcp")
+            data = response.json()
+
+            assert data["authorization_servers"] == ["https://auth.example.com/"]
+
+    @pytest.mark.parametrize(
+        "base_url,expected_resource",
+        [
+            ("https://api.example.com", "https://api.example.com/mcp"),
+            ("https://api.example.com/", "https://api.example.com/mcp"),
+            ("https://api.example.com/v1/", "https://api.example.com/v1/mcp"),
+        ],
+    )
+    async def test_base_url_configurations(self, base_url: str, expected_resource: str):
+        """Test different base_url configurations."""
+        from urllib.parse import urlparse
+
+        auth_provider = self._create_test_auth_provider(base_url=base_url)
+        mcp = FastMCP("test-server", auth=auth_provider)
+        mcp_http_app = mcp.http_app()
+
+        # Extract the path from the expected resource to construct metadata URL
+        resource_parsed = urlparse(expected_resource)
+        # Remove leading slash if present to avoid double slashes
+        resource_path = resource_parsed.path.lstrip("/")
+        metadata_path = f"/.well-known/oauth-protected-resource/{resource_path}"
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=mcp_http_app),
+            base_url="https://test.example.com",
+        ) as client:
+            # The metadata URL is path-aware per RFC 9728
+            response = await client.get(metadata_path)
+
+            assert response.status_code == 200
+            data = response.json()
+            assert data["resource"] == expected_resource
+
+    async def test_multiple_authorization_servers_resource_field(self):
+        """Test resource field with multiple authorization servers."""
+        auth_servers = [
+            AnyHttpUrl("https://auth1.example.com"),
+            AnyHttpUrl("https://auth2.example.com"),
+        ]
+
+        auth_provider = self._create_test_auth_provider()
+        # Override the authorization servers
+        auth_provider.authorization_servers = auth_servers
+
+        mcp = FastMCP("test-server", auth=auth_provider)
+        mcp_http_app = mcp.http_app()
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=mcp_http_app),
+            base_url="https://api.example.com",
+        ) as client:
+            # The metadata URL is path-aware per RFC 9728
+            response = await client.get("/.well-known/oauth-protected-resource/mcp")
+
+            data = response.json()
+            assert data["resource"] == "https://api.example.com/mcp"
+
+    async def test_multiple_authorization_servers_list(self):
+        """Test authorization_servers field with multiple authorization servers."""
+        auth_servers = [
+            AnyHttpUrl("https://auth1.example.com"),
+            AnyHttpUrl("https://auth2.example.com"),
+        ]
+
+        auth_provider = self._create_test_auth_provider()
+        # Override the authorization servers
+        auth_provider.authorization_servers = auth_servers
+
+        mcp = FastMCP("test-server", auth=auth_provider)
+        mcp_http_app = mcp.http_app()
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=mcp_http_app),
+            base_url="https://api.example.com",
+        ) as client:
+            # The metadata URL is path-aware per RFC 9728
+            response = await client.get("/.well-known/oauth-protected-resource/mcp")
+
+            data = response.json()
+            assert set(data["authorization_servers"]) == {
+                "https://auth1.example.com/",
+                "https://auth2.example.com/",
+            }
+
+    async def test_token_verification_with_valid_auth_succeeds(self):
+        """Test that requests with valid auth token succeed."""
+        # Note: This test focuses on HTTP-level authentication behavior
+        # For the RemoteAuthProvider, the key test is that the OAuth discovery
+        # endpoint correctly reports the resource server URL, which is tested above
+
+        # This is primarily testing that the token verifier integration works
+        tokens = {
+            "valid_token": {
+                "client_id": "test-client",
+                "scopes": [],
+            }
+        }
+        token_verifier = StaticTokenVerifier(tokens=tokens)
+
+        provider = RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+
+        # Test that the provider correctly delegates to the token verifier
+        result = await provider.verify_token("valid_token")
+        assert result is not None
+        assert result.token == "valid_token"
+        assert result.client_id == "test-client"
+
+        result = await provider.verify_token("invalid_token")
+        assert result is None
+
+    async def test_token_verification_with_invalid_auth_fails(self):
+        """Test that the provider correctly rejects invalid tokens."""
+        tokens = {
+            "valid_token": {
+                "client_id": "test-client",
+                "scopes": [],
+            }
+        }
+        token_verifier = StaticTokenVerifier(tokens=tokens)
+
+        provider = RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://api.example.com",
+        )
+
+        # Test that invalid tokens are rejected
+        result = await provider.verify_token("invalid_token")
+        assert result is None
+
+    async def test_issue_1348_oauth_discovery_returns_correct_url(self):
+        """Test that RemoteAuthProvider correctly returns the full MCP endpoint URL.
+
+        This test confirms that RemoteAuthProvider works correctly and returns
+        the resource URL with the MCP path appended to the base URL.
+        """
+        tokens = {
+            "test_token": {
+                "client_id": "test-client",
+                "scopes": ["read"],
+            }
+        }
+        token_verifier = StaticTokenVerifier(tokens=tokens)
+        auth_provider = RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://accounts.google.com")],
+            base_url="https://my-server.com",
+        )
+
+        mcp = FastMCP("test-server", auth=auth_provider)
+        mcp_http_app = mcp.http_app()
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=mcp_http_app),
+            base_url="https://my-server.com",
+        ) as client:
+            # The metadata URL is path-aware per RFC 9728
+            response = await client.get("/.well-known/oauth-protected-resource/mcp")
+
+            assert response.status_code == 200
+            data = response.json()
+
+            # The RemoteAuthProvider correctly returns the full MCP endpoint URL
+            assert data["resource"] == "https://my-server.com/mcp"
+            assert data["authorization_servers"] == ["https://accounts.google.com/"]
+
+    async def test_resource_name_field(self):
+        """Test that RemoteAuthProvider correctly returns the resource_name.
+
+        This test confirms that RemoteAuthProvider works correctly and returns
+        the exact resource_name specified.
+        """
+        tokens = {
+            "test_token": {
+                "client_id": "test-client",
+                "scopes": ["read"],
+            }
+        }
+        token_verifier = StaticTokenVerifier(tokens=tokens)
+        auth_provider = RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://accounts.google.com")],
+            base_url="https://my-server.com",
+            resource_name="My Test Resource",
+        )
+
+        mcp = FastMCP("test-server", auth=auth_provider)
+        mcp_http_app = mcp.http_app()
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=mcp_http_app),
+            base_url="https://my-server.com",
+        ) as client:
+            # The metadata URL is path-aware per RFC 9728
+            response = await client.get("/.well-known/oauth-protected-resource/mcp")
+
+            assert response.status_code == 200
+            data = response.json()
+
+            # The RemoteAuthProvider correctly returns the resource_name
+            assert data["resource_name"] == "My Test Resource"
+
+    async def test_resource_documentation_field(self):
+        """Test that RemoteAuthProvider correctly returns the resource_documentation.
+
+        This test confirms that RemoteAuthProvider works correctly and returns
+        the exact resource_documentation specified.
+        """
+        tokens = {
+            "test_token": {
+                "client_id": "test-client",
+                "scopes": ["read"],
+            }
+        }
+        token_verifier = StaticTokenVerifier(tokens=tokens)
+        auth_provider = RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://accounts.google.com")],
+            base_url="https://my-server.com",
+            resource_documentation=AnyHttpUrl(
+                "https://doc.my-server.com/resource-docs"
+            ),
+        )
+
+        mcp = FastMCP("test-server", auth=auth_provider)
+        mcp_http_app = mcp.http_app()
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=mcp_http_app),
+            base_url="https://my-server.com",
+        ) as client:
+            # The metadata URL is path-aware per RFC 9728
+            response = await client.get("/.well-known/oauth-protected-resource/mcp")
+
+            assert response.status_code == 200
+            data = response.json()
+
+            # The RemoteAuthProvider correctly returns the resource_documentation
+            assert (
+                data["resource_documentation"]
+                == "https://doc.my-server.com/resource-docs"
+            )
+
+    async def test_scopes_supported_overrides_metadata(self):
+        """Test that scopes_supported parameter overrides what's in metadata."""
+        token_verifier = StaticTokenVerifier(
+            tokens={
+                "test": {"client_id": "c", "scopes": ["read"]},
+            },
+            required_scopes=["read"],
+        )
+
+        provider = RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://my-server.com",
+            scopes_supported=["api://my-api/read"],
+        )
+
+        mcp = FastMCP("test-server", auth=provider)
+        mcp_http_app = mcp.http_app()
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=mcp_http_app),
+            base_url="https://my-server.com",
+        ) as client:
+            response = await client.get("/.well-known/oauth-protected-resource/mcp")
+
+            assert response.status_code == 200
+            data = response.json()
+            assert data["scopes_supported"] == ["api://my-api/read"]
+
+    async def test_scopes_supported_defaults_to_verifier(self):
+        """Test that metadata uses verifier scopes_supported when parameter not set."""
+        token_verifier = StaticTokenVerifier(
+            tokens={
+                "test": {"client_id": "c", "scopes": ["read"]},
+            },
+            required_scopes=["read"],
+        )
+
+        provider = RemoteAuthProvider(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl("https://auth.example.com")],
+            base_url="https://my-server.com",
+        )
+
+        mcp = FastMCP("test-server", auth=provider)
+        mcp_http_app = mcp.http_app()
+
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=mcp_http_app),
+            base_url="https://my-server.com",
+        ) as client:
+            response = await client.get("/.well-known/oauth-protected-resource/mcp")
+
+            assert response.status_code == 200
+            data = response.json()
+            assert data["scopes_supported"] == ["read"]
diff --git a/tests/server/auth/test_ssrf_protection.py b/tests/server/auth/test_ssrf_protection.py
new file mode 100644
index 0000000..0236942
--- /dev/null
+++ b/tests/server/auth/test_ssrf_protection.py
@@ -0,0 +1,508 @@
+"""Tests for SSRF-safe HTTP utilities.
+
+This module tests the ssrf.py module which provides SSRF-protected HTTP fetching.
+"""
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import httpx
+import pytest
+
+from fastmcp.server.auth.ssrf import (
+    SSRFError,
+    SSRFFetchError,
+    is_ip_allowed,
+    ssrf_safe_fetch,
+    validate_url,
+)
+
+
+class TestIsIPAllowed:
+    """Tests for is_ip_allowed function."""
+
+    def test_public_ipv4_allowed(self):
+        """Public IPv4 addresses should be allowed."""
+        assert is_ip_allowed("8.8.8.8") is True
+        assert is_ip_allowed("1.1.1.1") is True
+        assert is_ip_allowed("93.184.216.34") is True
+
+    def test_private_ipv4_blocked(self):
+        """Private IPv4 addresses should be blocked."""
+        assert is_ip_allowed("192.168.1.1") is False
+        assert is_ip_allowed("10.0.0.1") is False
+        assert is_ip_allowed("172.16.0.1") is False
+
+    def test_loopback_blocked(self):
+        """Loopback addresses should be blocked."""
+        assert is_ip_allowed("127.0.0.1") is False
+        assert is_ip_allowed("::1") is False
+
+    def test_link_local_blocked(self):
+        """Link-local addresses (AWS metadata) should be blocked."""
+        assert is_ip_allowed("169.254.169.254") is False
+
+    def test_rfc6598_cgnat_blocked(self):
+        """RFC6598 Carrier-Grade NAT addresses should be blocked."""
+        assert is_ip_allowed("100.64.0.1") is False
+        assert is_ip_allowed("100.100.100.100") is False
+
+    def test_ipv4_mapped_ipv6_blocked_if_private(self):
+        """IPv4-mapped IPv6 addresses should check the embedded IPv4."""
+        assert is_ip_allowed("::ffff:127.0.0.1") is False
+        assert is_ip_allowed("::ffff:192.168.1.1") is False
+
+    @pytest.mark.parametrize(
+        "address",
+        [
+            pytest.param("64:ff9b::7f00:1", id="nat64-loopback"),
+            pytest.param("64:ff9b::0a00:1", id="nat64-private"),
+            pytest.param("64:ff9b::a9fe:a9fe", id="nat64-link-local"),
+            pytest.param("64:ff9b::6440:1", id="nat64-cgnat"),
+            pytest.param("64:ff9b:1::a9fe:a9fe", id="nat64-local-use-low32"),
+            pytest.param("64:ff9b:1:a9fe:a9:fe00::", id="nat64-local-use-48"),
+            pytest.param("::ffff:0:7f00:1", id="ipv4-translated-loopback"),
+            pytest.param("::ffff:0:0a00:1", id="ipv4-translated-private"),
+            pytest.param("::ffff:0:a9fe:a9fe", id="ipv4-translated-link-local"),
+            pytest.param("::ffff:0:6440:1", id="ipv4-translated-cgnat"),
+            pytest.param("::7f00:1", id="ipv4-compatible-loopback"),
+            pytest.param("::0a00:1", id="ipv4-compatible-private"),
+            pytest.param("::a9fe:a9fe", id="ipv4-compatible-link-local"),
+            pytest.param("::6440:1", id="ipv4-compatible-cgnat"),
+            pytest.param("2002:a9fe:a9fe::1", id="6to4-link-local"),
+            pytest.param("2606:4700::5efe:192.168.1.1", id="isatap-private"),
+            pytest.param(
+                "2606:4700::200:5efe:169.254.169.254",
+                id="isatap-link-local",
+            ),
+        ],
+    )
+    def test_ipv6_transition_blocked_if_embedded_ipv4_blocked(self, address: str):
+        """IPv6 transition addresses should check the embedded IPv4."""
+        assert is_ip_allowed(address) is False
+
+    @pytest.mark.parametrize(
+        "address",
+        [
+            pytest.param("64:ff9b::0808:0808", id="nat64"),
+            pytest.param("::ffff:0:0808:0808", id="ipv4-translated"),
+            pytest.param("::0808:0808", id="ipv4-compatible"),
+            pytest.param("2606:4700::5efe:8.8.8.8", id="isatap"),
+        ],
+    )
+    def test_ipv6_transition_allowed_if_embedded_ipv4_allowed(self, address: str):
+        """IPv6 transition addresses should allow public embedded IPv4."""
+        assert is_ip_allowed(address) is True
+
+
+class TestValidateURL:
+    """Tests for validate_url function."""
+
+    async def test_http_rejected(self):
+        """HTTP URLs should be rejected (HTTPS required)."""
+        with pytest.raises(SSRFError, match="must use HTTPS"):
+            await validate_url("http://example.com/path")
+
+    async def test_missing_host_rejected(self):
+        """URLs without host should be rejected."""
+        with pytest.raises(SSRFError, match="must have a host"):
+            await validate_url("https:///path")
+
+    async def test_root_path_rejected_when_required(self):
+        """Root paths should be rejected when require_path=True."""
+        with patch(
+            "fastmcp.server.auth.ssrf.resolve_hostname",
+            return_value=["93.184.216.34"],
+        ):
+            with pytest.raises(SSRFError, match="non-root path"):
+                await validate_url("https://example.com/", require_path=True)
+
+    async def test_private_ip_rejected(self):
+        """URLs resolving to private IPs should be rejected."""
+        with patch(
+            "fastmcp.server.auth.ssrf.resolve_hostname",
+            return_value=["192.168.1.1"],
+        ):
+            with pytest.raises(SSRFError, match="blocked IP"):
+                await validate_url("https://example.com/path")
+
+    @pytest.mark.parametrize(
+        "address",
+        [
+            pytest.param("64:ff9b::0a00:1", id="nat64"),
+            pytest.param("64:ff9b:1:a9fe:a9:fe00::", id="nat64-local-use"),
+            pytest.param("::ffff:0:a9fe:a9fe", id="ipv4-translated"),
+            pytest.param("::a9fe:a9fe", id="ipv4-compatible"),
+            pytest.param("2606:4700::5efe:169.254.169.254", id="isatap"),
+        ],
+    )
+    async def test_ipv6_transition_private_ip_rejected(self, address: str):
+        """URLs resolving to IPv6-wrapped private IPs should be rejected."""
+        with patch(
+            "fastmcp.server.auth.ssrf.resolve_hostname",
+            return_value=[address],
+        ):
+            with pytest.raises(SSRFError, match="blocked IP"):
+                await validate_url("https://example.com/path")
+
+
+class TestSSRFSafeFetch:
+    """Tests for ssrf_safe_fetch function."""
+
+    async def test_private_ip_blocked(self):
+        """Fetch to private IP should be blocked."""
+        with patch(
+            "fastmcp.server.auth.ssrf.resolve_hostname",
+            return_value=["192.168.1.1"],
+        ):
+            with pytest.raises(SSRFError, match="blocked IP"):
+                await ssrf_safe_fetch("https://internal.example.com/api")
+
+    async def test_cgnat_blocked(self):
+        """Fetch to RFC6598 CGNAT IP should be blocked."""
+        with patch(
+            "fastmcp.server.auth.ssrf.resolve_hostname",
+            return_value=["100.64.0.1"],
+        ):
+            with pytest.raises(SSRFError, match="blocked IP"):
+                await ssrf_safe_fetch("https://cgnat.example.com/api")
+
+    async def test_connects_to_pinned_ip(self):
+        """Verify connection uses pinned IP, not re-resolved DNS."""
+        resolved_ip = "93.184.216.34"
+
+        with (
+            patch(
+                "fastmcp.server.auth.ssrf.resolve_hostname",
+                return_value=[resolved_ip],
+            ),
+            patch("httpx.AsyncClient") as mock_client_class,
+        ):
+            mock_stream = MagicMock()
+            mock_stream.status_code = 200
+            mock_stream.headers = {"content-length": "15"}
+            mock_stream.__aenter__ = AsyncMock(return_value=mock_stream)
+            mock_stream.__aexit__ = AsyncMock(return_value=None)
+
+            async def aiter_bytes():
+                yield b'{"data": "test"}'
+
+            mock_stream.aiter_bytes = aiter_bytes
+
+            mock_client = AsyncMock()
+            mock_client.stream = MagicMock(return_value=mock_stream)
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__ = AsyncMock(return_value=None)
+            mock_client_class.return_value = mock_client
+
+            await ssrf_safe_fetch("https://example.com/api")
+
+            # Verify URL contains pinned IP
+            call_args = mock_client.stream.call_args
+            url_called = call_args[0][1]
+            assert resolved_ip in url_called
+
+    async def test_fallback_to_second_ip(self):
+        """If the first IP fails, the next resolved IP should be tried."""
+        resolved_ips = ["2001:4860:4860::8888", "93.184.216.34"]
+
+        with (
+            patch(
+                "fastmcp.server.auth.ssrf.resolve_hostname",
+                return_value=resolved_ips,
+            ),
+            patch("httpx.AsyncClient") as mock_client_class,
+        ):
+            request = httpx.Request("GET", "https://example.com/api")
+
+            first_client = AsyncMock()
+            first_client.stream = MagicMock(
+                side_effect=httpx.RequestError("boom", request=request)
+            )
+            first_client.__aenter__.return_value = first_client
+            first_client.__aexit__ = AsyncMock(return_value=None)
+
+            mock_stream = MagicMock()
+            mock_stream.status_code = 200
+            mock_stream.headers = {"content-length": "2"}
+            mock_stream.__aenter__ = AsyncMock(return_value=mock_stream)
+            mock_stream.__aexit__ = AsyncMock(return_value=None)
+
+            async def aiter_bytes():
+                yield b"ok"
+
+            mock_stream.aiter_bytes = aiter_bytes
+
+            second_client = AsyncMock()
+            second_client.stream = MagicMock(return_value=mock_stream)
+            second_client.__aenter__.return_value = second_client
+            second_client.__aexit__ = AsyncMock(return_value=None)
+
+            mock_client_class.side_effect = [first_client, second_client]
+
+            content = await ssrf_safe_fetch("https://example.com/api")
+            assert content == b"ok"
+
+            call_args = second_client.stream.call_args
+            url_called = call_args[0][1]
+            assert resolved_ips[1] in url_called
+
+    async def test_host_header_set(self):
+        """Verify Host header is set to original hostname."""
+        resolved_ip = "93.184.216.34"
+        original_host = "example.com"
+
+        with (
+            patch(
+                "fastmcp.server.auth.ssrf.resolve_hostname",
+                return_value=[resolved_ip],
+            ),
+            patch("httpx.AsyncClient") as mock_client_class,
+        ):
+            mock_stream = MagicMock()
+            mock_stream.status_code = 200
+            mock_stream.headers = {"content-length": "15"}
+            mock_stream.__aenter__ = AsyncMock(return_value=mock_stream)
+            mock_stream.__aexit__ = AsyncMock(return_value=None)
+
+            async def aiter_bytes():
+                yield b'{"data": "test"}'
+
+            mock_stream.aiter_bytes = aiter_bytes
+
+            mock_client = AsyncMock()
+            mock_client.stream = MagicMock(return_value=mock_stream)
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__ = AsyncMock(return_value=None)
+            mock_client_class.return_value = mock_client
+
+            await ssrf_safe_fetch(f"https://{original_host}/api")
+
+            # Verify Host header
+            call_kwargs = mock_client.stream.call_args[1]
+            assert call_kwargs["headers"]["Host"] == original_host
+
+    async def test_response_size_limit(self):
+        """Verify response size limit is enforced via streaming."""
+        with (
+            patch(
+                "fastmcp.server.auth.ssrf.resolve_hostname",
+                return_value=["93.184.216.34"],
+            ),
+            patch("httpx.AsyncClient") as mock_client_class,
+        ):
+            # Response larger than default 5KB (no Content-Length, so streaming enforces)
+            mock_stream = MagicMock()
+            mock_stream.status_code = 200
+            mock_stream.headers = {}  # No Content-Length to force streaming check
+            mock_stream.__aenter__ = AsyncMock(return_value=mock_stream)
+            mock_stream.__aexit__ = AsyncMock(return_value=None)
+
+            async def aiter_bytes():
+                # Yield 10KB total
+                for _ in range(10):
+                    yield b"x" * 1024
+
+            mock_stream.aiter_bytes = aiter_bytes
+
+            mock_client = AsyncMock()
+            mock_client.stream = MagicMock(return_value=mock_stream)
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__ = AsyncMock(return_value=None)
+            mock_client_class.return_value = mock_client
+
+            with pytest.raises(SSRFFetchError, match="too large"):
+                await ssrf_safe_fetch("https://example.com/api")
+
+
+class TestJWKSSSRFProtection:
+    """Tests for SSRF protection in JWTVerifier JWKS fetching."""
+
+    async def test_jwks_private_ip_blocked(self):
+        """JWKS fetch to private IP should be blocked."""
+        from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+        verifier = JWTVerifier(
+            jwks_uri="https://internal.example.com/.well-known/jwks.json",
+            issuer="https://issuer.example.com",
+            ssrf_safe=True,
+        )
+
+        with patch(
+            "fastmcp.server.auth.ssrf.resolve_hostname",
+            return_value=["192.168.1.1"],
+        ):
+            with pytest.raises(ValueError, match="Failed to fetch JWKS"):
+                # Create a dummy token to trigger JWKS fetch
+                await verifier._get_jwks_key("test-kid")
+
+    async def test_jwks_cgnat_blocked(self):
+        """JWKS fetch to RFC6598 CGNAT IP should be blocked."""
+        from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+        verifier = JWTVerifier(
+            jwks_uri="https://cgnat.example.com/.well-known/jwks.json",
+            issuer="https://issuer.example.com",
+            ssrf_safe=True,
+        )
+
+        with patch(
+            "fastmcp.server.auth.ssrf.resolve_hostname",
+            return_value=["100.64.0.1"],
+        ):
+            with pytest.raises(ValueError, match="Failed to fetch JWKS"):
+                await verifier._get_jwks_key("test-kid")
+
+    async def test_jwks_loopback_blocked(self):
+        """JWKS fetch to loopback should be blocked."""
+        from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+        verifier = JWTVerifier(
+            jwks_uri="https://localhost/.well-known/jwks.json",
+            issuer="https://issuer.example.com",
+            ssrf_safe=True,
+        )
+
+        with patch(
+            "fastmcp.server.auth.ssrf.resolve_hostname",
+            return_value=["127.0.0.1"],
+        ):
+            with pytest.raises(ValueError, match="Failed to fetch JWKS"):
+                await verifier._get_jwks_key("test-kid")
+
+
+class TestIPv6URLFormatting:
+    """Tests for proper IPv6 address bracketing in URLs."""
+
+    def test_format_ip_for_url_ipv4(self):
+        """IPv4 addresses should not be bracketed."""
+        from fastmcp.server.auth.ssrf import format_ip_for_url
+
+        assert format_ip_for_url("8.8.8.8") == "8.8.8.8"
+        assert format_ip_for_url("192.168.1.1") == "192.168.1.1"
+
+    def test_format_ip_for_url_ipv6(self):
+        """IPv6 addresses should be bracketed for URL use."""
+        from fastmcp.server.auth.ssrf import format_ip_for_url
+
+        assert format_ip_for_url("2001:db8::1") == "[2001:db8::1]"
+        assert format_ip_for_url("::1") == "[::1]"
+        assert format_ip_for_url("fe80::1") == "[fe80::1]"
+
+    def test_format_ip_for_url_invalid(self):
+        """Invalid IP strings should be returned unchanged."""
+        from fastmcp.server.auth.ssrf import format_ip_for_url
+
+        assert format_ip_for_url("not-an-ip") == "not-an-ip"
+        assert format_ip_for_url("") == ""
+
+    async def test_ipv6_pinned_url_is_valid(self):
+        """Verify IPv6 addresses are properly bracketed in pinned URLs."""
+        resolved_ipv6 = "2001:4860:4860::8888"
+
+        with (
+            patch(
+                "fastmcp.server.auth.ssrf.resolve_hostname",
+                return_value=[resolved_ipv6],
+            ),
+            patch("httpx.AsyncClient") as mock_client_class,
+        ):
+            mock_stream = MagicMock()
+            mock_stream.status_code = 200
+            mock_stream.headers = {"content-length": "10"}
+            mock_stream.__aenter__ = AsyncMock(return_value=mock_stream)
+            mock_stream.__aexit__ = AsyncMock(return_value=None)
+
+            async def aiter_bytes():
+                yield b'{"key": 1}'
+
+            mock_stream.aiter_bytes = aiter_bytes
+
+            mock_client = AsyncMock()
+            mock_client.stream = MagicMock(return_value=mock_stream)
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__ = AsyncMock(return_value=None)
+            mock_client_class.return_value = mock_client
+
+            await ssrf_safe_fetch("https://example.com/api")
+
+            # Verify the URL contains bracketed IPv6 address
+            call_args = mock_client.stream.call_args
+            url_called = call_args[0][1]
+
+            # IPv6 should be bracketed: https://[2001:4860:4860::8888]:443/path
+            assert f"[{resolved_ipv6}]" in url_called, (
+                f"Expected bracketed IPv6 [{resolved_ipv6}] in URL, got {url_called}"
+            )
+
+
+class TestStreamingResponseSizeLimit:
+    """Tests for streaming-based response size enforcement."""
+
+    async def test_size_limit_enforced_during_streaming(self):
+        """Verify that size limit is enforced as chunks are received, not after."""
+        with (
+            patch(
+                "fastmcp.server.auth.ssrf.resolve_hostname",
+                return_value=["93.184.216.34"],
+            ),
+            patch("httpx.AsyncClient") as mock_client_class,
+        ):
+            chunks_yielded = []
+
+            async def aiter_bytes():
+                # Yield chunks that exceed the limit
+                for i in range(10):
+                    chunk = b"x" * 1024  # 1KB per chunk
+                    chunks_yielded.append(chunk)
+                    yield chunk
+
+            mock_stream = MagicMock()
+            mock_stream.status_code = 200
+            mock_stream.headers = {}  # No content-length to force streaming check
+            mock_stream.__aenter__ = AsyncMock(return_value=mock_stream)
+            mock_stream.__aexit__ = AsyncMock(return_value=None)
+            mock_stream.aiter_bytes = aiter_bytes
+
+            mock_client = AsyncMock()
+            mock_client.stream = MagicMock(return_value=mock_stream)
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__ = AsyncMock(return_value=None)
+            mock_client_class.return_value = mock_client
+
+            with pytest.raises(SSRFFetchError, match="too large"):
+                await ssrf_safe_fetch("https://example.com/api", max_size=5120)
+
+            # Verify we stopped after exceeding the limit (should be ~6 chunks for 5KB limit)
+            # This confirms we're enforcing during streaming, not after downloading all
+            assert len(chunks_yielded) <= 7, (
+                f"Downloaded {len(chunks_yielded)} chunks (expected <=7 for streaming enforcement)"
+            )
+
+    async def test_content_length_header_checked_first(self):
+        """Verify Content-Length header is checked before streaming."""
+        with (
+            patch(
+                "fastmcp.server.auth.ssrf.resolve_hostname",
+                return_value=["93.184.216.34"],
+            ),
+            patch("httpx.AsyncClient") as mock_client_class,
+        ):
+            mock_stream = MagicMock()
+            mock_stream.status_code = 200
+            mock_stream.headers = {"content-length": "10240"}  # 10KB
+            mock_stream.__aenter__ = AsyncMock(return_value=mock_stream)
+            mock_stream.__aexit__ = AsyncMock(return_value=None)
+
+            # aiter_bytes should never be called if Content-Length is checked
+            mock_stream.aiter_bytes = MagicMock(
+                side_effect=AssertionError("Should not stream")
+            )
+
+            mock_client = AsyncMock()
+            mock_client.stream = MagicMock(return_value=mock_stream)
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__ = AsyncMock(return_value=None)
+            mock_client_class.return_value = mock_client
+
+            with pytest.raises(SSRFFetchError, match="too large"):
+                await ssrf_safe_fetch("https://example.com/api", max_size=5120)
diff --git a/tests/server/auth/test_static_token_verifier.py b/tests/server/auth/test_static_token_verifier.py
new file mode 100644
index 0000000..2f07a67
--- /dev/null
+++ b/tests/server/auth/test_static_token_verifier.py
@@ -0,0 +1,112 @@
+"""Tests for StaticTokenVerifier integration with FastMCP."""
+
+import httpx
+
+from fastmcp.server import FastMCP
+from fastmcp.server.auth import AccessToken
+from fastmcp.server.auth.providers.jwt import StaticTokenVerifier
+
+
+class TestStaticTokenVerifier:
+    """Test StaticTokenVerifier integration with FastMCP server."""
+
+    def test_static_token_verifier_creation(self):
+        """Test creating a FastMCP server with StaticTokenVerifier."""
+        verifier = StaticTokenVerifier(
+            {"test-token": {"client_id": "test-client", "scopes": ["read", "write"]}}
+        )
+
+        server = FastMCP("TestServer", auth=verifier)
+        assert server.auth is verifier
+
+    async def test_static_token_verifier_verify_token(self):
+        """Test StaticTokenVerifier token verification."""
+        verifier = StaticTokenVerifier(
+            {
+                "valid-token": {
+                    "client_id": "test-client",
+                    "scopes": ["read", "write"],
+                    "expires_at": None,
+                },
+                "scoped-token": {"client_id": "limited-client", "scopes": ["read"]},
+            }
+        )
+
+        # Test valid token
+        result = await verifier.verify_token("valid-token")
+        assert isinstance(result, AccessToken)
+        assert result.client_id == "test-client"
+        assert result.scopes == ["read", "write"]
+        assert result.token == "valid-token"
+        assert result.expires_at is None
+
+        # Test token with different scopes
+        result = await verifier.verify_token("scoped-token")
+        assert isinstance(result, AccessToken)
+        assert result.client_id == "limited-client"
+        assert result.scopes == ["read"]
+
+        # Test invalid token
+        result = await verifier.verify_token("invalid-token")
+        assert result is None
+
+    async def test_server_with_token_verifier_http_app(self):
+        """Test that FastMCP server works with StaticTokenVerifier for HTTP requests."""
+        verifier = StaticTokenVerifier(
+            {"test-token": {"client_id": "test-client", "scopes": ["read", "write"]}}
+        )
+
+        server = FastMCP("TestServer", auth=verifier)
+
+        @server.tool
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        # Create HTTP app
+        app = server.http_app(transport="http")
+
+        # Test unauthenticated request gets 401 (use exact path match to avoid redirect)
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=app), base_url="http://test"
+        ) as client:
+            response = await client.post("/mcp")
+            assert response.status_code == 401
+            assert "WWW-Authenticate" in response.headers
+
+    async def test_server_with_token_verifier_redirect_behavior(self):
+        """Test that FastMCP server redirects non-matching paths correctly."""
+        verifier = StaticTokenVerifier(
+            {"test-token": {"client_id": "test-client", "scopes": ["read", "write"]}}
+        )
+
+        server = FastMCP("TestServer", auth=verifier)
+
+        @server.tool
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        # Create HTTP app (default path is /mcp)
+        app = server.http_app(transport="http")
+
+        # Test that non-matching path gets 307 redirect
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=app), base_url="http://test"
+        ) as client:
+            response = await client.post("/mcp/", follow_redirects=False)
+            assert response.status_code == 307
+            assert response.headers["location"] == "http://test/mcp"
+
+    def test_server_rejects_both_oauth_and_token_verifier(self):
+        """Test that server raises error when both OAuth and TokenVerifier provided."""
+        from fastmcp.server.auth.providers.in_memory import InMemoryOAuthProvider
+
+        oauth_provider = InMemoryOAuthProvider("http://test.com")
+        token_verifier = StaticTokenVerifier({"token": {"client_id": "test"}})
+
+        # This should work - OAuth provider
+        server1 = FastMCP("Test1", auth=oauth_provider)
+        assert server1.auth is oauth_provider
+
+        # This should work - TokenVerifier
+        server2 = FastMCP("Test2", auth=token_verifier)
+        assert server2.auth is token_verifier
diff --git a/tests/server/http/__init__.py b/tests/server/http/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/server/http/test_bearer_auth_backend.py b/tests/server/http/test_bearer_auth_backend.py
new file mode 100644
index 0000000..58d1036
--- /dev/null
+++ b/tests/server/http/test_bearer_auth_backend.py
@@ -0,0 +1,179 @@
+"""Tests for BearerAuthBackend integration with TokenVerifier."""
+
+import pytest
+from mcp.server.auth.middleware.bearer_auth import BearerAuthBackend
+from starlette.requests import HTTPConnection
+
+from fastmcp.server.auth import AccessToken, TokenVerifier
+from fastmcp.server.auth.providers.jwt import JWTVerifier, RSAKeyPair
+
+
+class TestBearerAuthBackendTokenVerifierIntegration:
+    """Test BearerAuthBackend works with TokenVerifier protocol."""
+
+    @pytest.fixture
+    def rsa_key_pair(self) -> RSAKeyPair:
+        """Generate RSA key pair for testing."""
+        return RSAKeyPair.generate()
+
+    @pytest.fixture
+    def jwt_verifier(self, rsa_key_pair: RSAKeyPair) -> JWTVerifier:
+        """Create JWTVerifier for testing."""
+        return JWTVerifier(
+            public_key=rsa_key_pair.public_key,
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+        )
+
+    @pytest.fixture
+    def valid_token(self, rsa_key_pair: RSAKeyPair) -> str:
+        """Create a valid test token."""
+        return rsa_key_pair.create_token(
+            subject="test-user",
+            issuer="https://test.example.com",
+            audience="https://api.example.com",
+            scopes=["read", "write"],
+        )
+
+    def test_bearer_auth_backend_constructor_accepts_token_verifier(
+        self, jwt_verifier: JWTVerifier
+    ):
+        """Test that BearerAuthBackend constructor accepts TokenVerifier."""
+        # This should not raise an error
+        backend = BearerAuthBackend(jwt_verifier)
+        assert isinstance(backend.token_verifier, TokenVerifier)
+        assert backend.token_verifier is jwt_verifier
+
+    async def test_bearer_auth_backend_authenticate_with_valid_token(
+        self, jwt_verifier: JWTVerifier, valid_token: str
+    ):
+        """Test BearerAuthBackend authentication with valid token."""
+        backend = BearerAuthBackend(jwt_verifier)
+
+        # Create mock HTTPConnection with Authorization header
+        scope = {
+            "type": "http",
+            "headers": [(b"authorization", f"Bearer {valid_token}".encode())],
+        }
+        conn = HTTPConnection(scope)
+
+        result = await backend.authenticate(conn)
+
+        assert result is not None
+        credentials, user = result
+        assert credentials.scopes == ["read", "write"]
+        assert user.username == "test-user"
+        assert hasattr(user, "access_token")
+        assert user.access_token.token == valid_token
+
+    async def test_bearer_auth_backend_authenticate_with_invalid_token(
+        self, jwt_verifier: JWTVerifier
+    ):
+        """Test BearerAuthBackend authentication with invalid token."""
+        backend = BearerAuthBackend(jwt_verifier)
+
+        # Create mock HTTPConnection with invalid Authorization header
+        scope = {
+            "type": "http",
+            "headers": [(b"authorization", b"Bearer invalid-token")],
+        }
+        conn = HTTPConnection(scope)
+
+        result = await backend.authenticate(conn)
+        assert result is None
+
+    async def test_bearer_auth_backend_authenticate_with_no_header(
+        self, jwt_verifier: JWTVerifier
+    ):
+        """Test BearerAuthBackend authentication with no Authorization header."""
+        backend = BearerAuthBackend(jwt_verifier)
+
+        # Create mock HTTPConnection without Authorization header
+        scope = {
+            "type": "http",
+            "headers": [],
+        }
+        conn = HTTPConnection(scope)
+
+        result = await backend.authenticate(conn)
+        assert result is None
+
+    async def test_bearer_auth_backend_authenticate_with_non_bearer_token(
+        self, jwt_verifier: JWTVerifier
+    ):
+        """Test BearerAuthBackend authentication with non-Bearer token."""
+        backend = BearerAuthBackend(jwt_verifier)
+
+        # Create mock HTTPConnection with Basic auth header
+        scope = {
+            "type": "http",
+            "headers": [(b"authorization", b"Basic dXNlcjpwYXNz")],
+        }
+        conn = HTTPConnection(scope)
+
+        result = await backend.authenticate(conn)
+        assert result is None
+
+
+class MockTokenVerifier:
+    """Mock TokenVerifier for testing backend integration."""
+
+    def __init__(self, return_value: AccessToken | None = None):
+        self.return_value = return_value
+        self.verify_token_calls = []
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Mock verify_token method."""
+        self.verify_token_calls.append(token)
+        return self.return_value
+
+
+class TestBearerAuthBackendWithMockVerifier:
+    """Test BearerAuthBackend with mock TokenVerifier."""
+
+    async def test_backend_calls_verify_token_method(self):
+        """Test that BearerAuthBackend calls verify_token on the verifier."""
+        mock_access_token = AccessToken(
+            token="test-token",
+            client_id="test-client",
+            scopes=["read"],
+            expires_at=None,
+        )
+        mock_verifier = MockTokenVerifier(return_value=mock_access_token)
+        backend = BearerAuthBackend(mock_verifier)
+
+        scope = {
+            "type": "http",
+            "headers": [(b"authorization", b"Bearer test-token")],
+        }
+        conn = HTTPConnection(scope)
+
+        result = await backend.authenticate(conn)
+
+        # Should have called verify_token with the token
+        assert mock_verifier.verify_token_calls == ["test-token"]
+
+        # Should return authentication result
+        assert result is not None
+        credentials, user = result
+        assert credentials.scopes == ["read"]
+        assert user.username == "test-client"
+
+    async def test_backend_handles_verify_token_none_result(self):
+        """Test that BearerAuthBackend handles None result from verify_token."""
+        mock_verifier = MockTokenVerifier(return_value=None)
+        backend = BearerAuthBackend(mock_verifier)
+
+        scope = {
+            "type": "http",
+            "headers": [(b"authorization", b"Bearer invalid-token")],
+        }
+        conn = HTTPConnection(scope)
+
+        result = await backend.authenticate(conn)
+
+        # Should have called verify_token
+        assert mock_verifier.verify_token_calls == ["invalid-token"]
+
+        # Should return None for authentication failure
+        assert result is None
diff --git a/tests/server/http/test_custom_routes.py b/tests/server/http/test_custom_routes.py
new file mode 100644
index 0000000..d0a757b
--- /dev/null
+++ b/tests/server/http/test_custom_routes.py
@@ -0,0 +1,105 @@
+import pytest
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from fastmcp import FastMCP
+from fastmcp.server.http import create_sse_app, create_streamable_http_app
+
+
+class TestCustomRoutes:
+    @pytest.fixture
+    def server_with_custom_route(self):
+        """Create a FastMCP server with a custom route."""
+        server = FastMCP()
+
+        @server.custom_route("/custom-route", methods=["GET"])
+        async def custom_route(request: Request):
+            return JSONResponse({"message": "custom route"})
+
+        return server
+
+    def test_custom_routes_apply_filtering_http_app(self, server_with_custom_route):
+        """Test that custom routes are included when using server.http_app()."""
+        # Get the app via server.http_app()
+        app = server_with_custom_route.http_app()
+
+        # Verify that the custom route is included
+        custom_route_found = False
+        for route in app.routes:
+            if isinstance(route, Route) and route.path == "/custom-route":
+                custom_route_found = True
+                break
+
+        assert custom_route_found, "Custom route was not found in app routes"
+
+    def test_custom_routes_via_streamable_http_app_direct(
+        self, server_with_custom_route
+    ):
+        """Test that custom routes are included when using create_streamable_http_app directly."""
+        # Create the app by calling the constructor function directly
+        app = create_streamable_http_app(
+            server=server_with_custom_route, streamable_http_path="/api"
+        )
+
+        # Verify that the custom route is included
+        custom_route_found = False
+        for route in app.routes:
+            if isinstance(route, Route) and route.path == "/custom-route":
+                custom_route_found = True
+                break
+
+        assert custom_route_found, "Custom route was not found in app routes"
+
+    def test_custom_routes_via_sse_app_direct(self, server_with_custom_route):
+        """Test that custom routes are included when using create_sse_app directly."""
+        # Create the app by calling the constructor function directly
+        app = create_sse_app(
+            server=server_with_custom_route, message_path="/message", sse_path="/sse/"
+        )
+
+        # Verify that the custom route is included
+        custom_route_found = False
+        for route in app.routes:
+            if isinstance(route, Route) and route.path == "/custom-route":
+                custom_route_found = True
+                break
+
+        assert custom_route_found, "Custom route was not found in app routes"
+
+    def test_multiple_custom_routes(
+        self,
+    ):
+        """Test that multiple custom routes are included in both methods."""
+        server = FastMCP()
+
+        custom_paths = ["/route1", "/route2", "/route3"]
+
+        # Add multiple custom routes
+        for path in custom_paths:
+
+            @server.custom_route(path, methods=["GET"])
+            async def custom_route(request: Request):
+                return JSONResponse({"message": f"route {path}"})
+
+        # Test with server.http_app()
+        app1 = server.http_app()
+
+        # Test with direct constructor call
+        app2 = create_streamable_http_app(server=server, streamable_http_path="/api")
+
+        # Check all routes are in both apps
+        for path in custom_paths:
+            # Check in app1
+            route_in_app1 = any(
+                isinstance(route, Route) and route.path == path for route in app1.routes
+            )
+            assert route_in_app1, f"Route {path} not found in server.http_app()"
+
+            # Check in app2
+            route_in_app2 = any(
+                isinstance(route, Route) and route.path == path for route in app2.routes
+            )
+            assert route_in_app2, (
+                f"Route {path} not found in create_streamable_http_app()"
+            )
diff --git a/tests/server/http/test_http_auth_middleware.py b/tests/server/http/test_http_auth_middleware.py
new file mode 100644
index 0000000..6a2340f
--- /dev/null
+++ b/tests/server/http/test_http_auth_middleware.py
@@ -0,0 +1,444 @@
+from collections.abc import MutableMapping
+from typing import Any, Literal
+
+import pytest
+from mcp.server.auth.middleware.bearer_auth import RequireAuthMiddleware
+from starlette.responses import Response
+from starlette.routing import Route
+from starlette.testclient import TestClient
+from starlette.types import Receive, Scope, Send
+
+from fastmcp.server import FastMCP
+from fastmcp.server.auth.providers.jwt import JWTVerifier, RSAKeyPair
+from fastmcp.server.http import HostOriginGuardMiddleware, create_streamable_http_app
+
+INITIALIZE_REQUEST = {
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "initialize",
+    "params": {
+        "protocolVersion": "2024-11-05",
+        "capabilities": {},
+        "clientInfo": {"name": "attacker", "version": "0.1"},
+    },
+}
+
+
+async def _ok_app(scope: Scope, receive: Receive, send: Send) -> None:
+    response = Response("OK")
+    await response(scope, receive, send)
+
+
+async def _empty_receive() -> dict[str, Any]:
+    return {"type": "http.request", "body": b"", "more_body": False}
+
+
+async def _guard_status(
+    *,
+    host: str,
+    origin: str | None = None,
+    server: tuple[str, int] | None = None,
+    mode: Literal["auto", "strict"] = "auto",
+    allowed_hosts: list[str] | None = None,
+    allowed_origins: list[str] | None = None,
+) -> int:
+    app = HostOriginGuardMiddleware(
+        _ok_app,
+        allowed_hosts=allowed_hosts,
+        allowed_origins=allowed_origins,
+        mode=mode,
+    )
+    headers = [(b"host", host.encode())]
+    if origin is not None:
+        headers.append((b"origin", origin.encode()))
+
+    scope: Scope = {
+        "type": "http",
+        "asgi": {"version": "3.0"},
+        "http_version": "1.1",
+        "method": "POST",
+        "scheme": "https",
+        "path": "/mcp",
+        "raw_path": b"/mcp",
+        "query_string": b"",
+        "headers": headers,
+        "client": ("127.0.0.1", 12345),
+        "server": server,
+    }
+    sent_messages: list[MutableMapping[str, Any]] = []
+
+    async def send(message: MutableMapping[str, Any]) -> None:
+        sent_messages.append(message)
+
+    await app(scope, _empty_receive, send)
+    response_start = next(
+        message for message in sent_messages if message["type"] == "http.response.start"
+    )
+    return response_start["status"]
+
+
+class TestStreamableHTTPAppResourceMetadataURL:
+    """Test resource_metadata_url logic in create_streamable_http_app."""
+
+    @pytest.fixture
+    def rsa_key_pair(self) -> RSAKeyPair:
+        """Generate RSA key pair for testing."""
+        return RSAKeyPair.generate()
+
+    @pytest.fixture
+    def bearer_auth_provider(self, rsa_key_pair):
+        provider = JWTVerifier(
+            public_key=rsa_key_pair.public_key,
+            issuer="https://issuer",
+            audience="https://audience",
+            base_url="https://resource.example.com",
+        )
+        return provider
+
+    def test_auth_endpoint_wrapped_with_require_auth_middleware(
+        self, bearer_auth_provider
+    ):
+        """Test that auth-protected endpoints use RequireAuthMiddleware."""
+        server = FastMCP(name="TestServer")
+
+        app = create_streamable_http_app(
+            server=server,
+            streamable_http_path="/mcp",
+            auth=bearer_auth_provider,
+        )
+
+        route = next(r for r in app.routes if isinstance(r, Route) and r.path == "/mcp")
+
+        # When auth is enabled, endpoint should use RequireAuthMiddleware
+        assert isinstance(route.endpoint, RequireAuthMiddleware)
+
+    def test_auth_endpoint_has_correct_methods(self, rsa_key_pair):
+        """Test that auth-protected endpoints have correct HTTP methods."""
+        provider = JWTVerifier(
+            public_key=rsa_key_pair.public_key,
+            issuer="https://issuer",
+            audience="https://audience",
+            base_url="https://resource.example.com/",
+        )
+        server = FastMCP(name="TestServer")
+        app = create_streamable_http_app(
+            server=server,
+            streamable_http_path="/mcp",
+            auth=provider,
+        )
+        route = next(r for r in app.routes if isinstance(r, Route) and r.path == "/mcp")
+
+        # Verify RequireAuthMiddleware is applied
+        assert isinstance(route.endpoint, RequireAuthMiddleware)
+        # Verify methods include GET, POST, DELETE for streamable-http
+        expected_methods = {"GET", "POST", "DELETE"}
+        assert route.methods is not None
+        assert expected_methods.issubset(set(route.methods))
+
+    def test_no_auth_provider_mounts_without_middleware(self, rsa_key_pair):
+        """Test that endpoints without auth are not wrapped with middleware."""
+        server = FastMCP(name="TestServer")
+        app = create_streamable_http_app(
+            server=server,
+            streamable_http_path="/mcp",
+            auth=None,
+        )
+        route = next(r for r in app.routes if isinstance(r, Route) and r.path == "/mcp")
+        # Without auth, no RequireAuthMiddleware should be applied
+        assert not isinstance(route.endpoint, RequireAuthMiddleware)
+
+    def test_authenticated_requests_still_require_auth(self, bearer_auth_provider):
+        """Test that actual requests (not OPTIONS) still require authentication."""
+        server = FastMCP(name="TestServer")
+        app = create_streamable_http_app(
+            server=server,
+            streamable_http_path="/mcp",
+            auth=bearer_auth_provider,
+        )
+
+        # Test POST request without auth - should fail with 401
+        with TestClient(app) as client:
+            response = client.post("/mcp")
+            assert response.status_code == 401
+            assert "www-authenticate" in response.headers
+
+
+class TestStreamableHTTPHostOriginProtection:
+    """Test host and origin validation for streamable HTTP apps."""
+
+    def test_default_allows_untrusted_host_for_compatibility(self):
+        server = FastMCP(name="TestServer")
+        app = create_streamable_http_app(
+            server=server,
+            streamable_http_path="/mcp",
+            allowed_hosts=["apps.example.com"],
+        )
+
+        with TestClient(app, base_url="http://127.0.0.1") as client:
+            response = client.post(
+                "/mcp",
+                headers={
+                    "accept": "application/json, text/event-stream",
+                    "host": "internal-upstream",
+                    "x-forwarded-host": "apps.example.com",
+                },
+                json=INITIALIZE_REQUEST,
+            )
+
+        assert response.status_code == 200
+        assert "mcp-session-id" in response.headers
+
+    async def test_auto_allows_public_host_when_server_scope_is_ambiguous(self):
+        status = await _guard_status(
+            host="mcp.example.com",
+            origin="https://app.example.com",
+            server=None,
+        )
+
+        assert status == 200
+
+    async def test_auto_rejects_untrusted_host_when_server_scope_is_loopback(self):
+        status = await _guard_status(
+            host="attacker.example",
+            origin="https://attacker.example",
+            server=("127.0.0.1", 8000),
+        )
+
+        assert status == 421
+
+    async def test_strict_rejects_public_host_when_server_scope_is_ambiguous(self):
+        status = await _guard_status(
+            host="mcp.example.com",
+            origin="https://app.example.com",
+            server=None,
+            mode="strict",
+        )
+
+        assert status == 421
+
+    async def test_auto_rejects_same_origin_fallback_without_trusted_host_boundary(
+        self,
+    ):
+        status = await _guard_status(
+            host="attacker.example",
+            origin="https://attacker.example",
+            server=None,
+            allowed_origins=["https://app.example.com"],
+        )
+
+        assert status == 403
+
+    async def test_auto_allows_configured_origin_without_trusted_host_boundary(self):
+        status = await _guard_status(
+            host="mcp.example.com",
+            origin="https://app.example.com",
+            server=None,
+            allowed_origins=["https://app.example.com"],
+        )
+
+        assert status == 200
+
+    def test_auto_rejects_untrusted_host_before_session_initialization(self):
+        server = FastMCP(name="TestServer")
+        app = create_streamable_http_app(
+            server=server,
+            streamable_http_path="/mcp",
+            host_origin_protection="auto",
+        )
+
+        with TestClient(app, base_url="http://127.0.0.1") as client:
+            response = client.post(
+                "/mcp",
+                headers={
+                    "accept": "application/json, text/event-stream",
+                    "host": "attacker.example",
+                },
+                json=INITIALIZE_REQUEST,
+            )
+
+        assert response.status_code == 421
+        assert "mcp-session-id" not in response.headers
+
+    def test_auto_rejects_untrusted_origin_before_session_initialization(self):
+        server = FastMCP(name="TestServer")
+        app = create_streamable_http_app(
+            server=server,
+            streamable_http_path="/mcp",
+            host_origin_protection="auto",
+        )
+
+        with TestClient(app, base_url="http://127.0.0.1") as client:
+            response = client.post(
+                "/mcp",
+                headers={
+                    "accept": "application/json, text/event-stream",
+                    "origin": "https://attacker.example",
+                },
+                json=INITIALIZE_REQUEST,
+            )
+
+        assert response.status_code == 403
+        assert "mcp-session-id" not in response.headers
+
+    def test_allows_configured_host_and_origin(self):
+        server = FastMCP(name="TestServer")
+        app = create_streamable_http_app(
+            server=server,
+            streamable_http_path="/mcp",
+            host_origin_protection="auto",
+            allowed_hosts=["mcp.example.com"],
+            allowed_origins=["https://app.example.com"],
+        )
+
+        with TestClient(app, base_url="http://127.0.0.1") as client:
+            response = client.post(
+                "/mcp",
+                headers={
+                    "accept": "application/json, text/event-stream",
+                    "host": "mcp.example.com",
+                    "origin": "https://app.example.com",
+                },
+                json=INITIALIZE_REQUEST,
+            )
+
+        assert response.status_code == 200
+        assert "mcp-session-id" in response.headers
+
+    def test_allows_same_request_origin(self):
+        server = FastMCP(name="TestServer")
+        app = create_streamable_http_app(
+            server=server,
+            streamable_http_path="/mcp",
+            host_origin_protection="auto",
+            allowed_hosts=["mcp.example.com"],
+        )
+
+        with TestClient(app, base_url="https://mcp.example.com") as client:
+            response = client.post(
+                "/mcp",
+                headers={
+                    "accept": "application/json, text/event-stream",
+                    "origin": "https://mcp.example.com",
+                },
+                json=INITIALIZE_REQUEST,
+            )
+
+        assert response.status_code == 200
+        assert "mcp-session-id" in response.headers
+
+    def test_allows_loopback_origin_for_loopback_host(self):
+        server = FastMCP(name="TestServer")
+        app = create_streamable_http_app(
+            server=server,
+            streamable_http_path="/mcp",
+            host_origin_protection="auto",
+        )
+
+        with TestClient(app, base_url="http://127.0.0.1") as client:
+            response = client.post(
+                "/mcp",
+                headers={
+                    "accept": "application/json, text/event-stream",
+                    "origin": "http://localhost:3000",
+                },
+                json=INITIALIZE_REQUEST,
+            )
+
+        assert response.status_code == 200
+        assert "mcp-session-id" in response.headers
+
+    def test_rejects_loopback_origin_for_public_host(self):
+        server = FastMCP(name="TestServer")
+        app = create_streamable_http_app(
+            server=server,
+            streamable_http_path="/mcp",
+            host_origin_protection="auto",
+            allowed_hosts=["mcp.example.com"],
+        )
+
+        with TestClient(app, base_url="https://mcp.example.com") as client:
+            response = client.post(
+                "/mcp",
+                headers={
+                    "accept": "application/json, text/event-stream",
+                    "origin": "http://localhost:3000",
+                },
+                json=INITIALIZE_REQUEST,
+            )
+
+        assert response.status_code == 403
+        assert "mcp-session-id" not in response.headers
+
+    def test_allows_configured_loopback_origin_for_public_host(self):
+        server = FastMCP(name="TestServer")
+        app = create_streamable_http_app(
+            server=server,
+            streamable_http_path="/mcp",
+            host_origin_protection="auto",
+            allowed_hosts=["mcp.example.com"],
+            allowed_origins=["http://localhost:3000"],
+        )
+
+        with TestClient(app, base_url="https://mcp.example.com") as client:
+            response = client.post(
+                "/mcp",
+                headers={
+                    "accept": "application/json, text/event-stream",
+                    "origin": "http://localhost:3000",
+                },
+                json=INITIALIZE_REQUEST,
+            )
+
+        assert response.status_code == 200
+        assert "mcp-session-id" in response.headers
+
+    @pytest.mark.parametrize(
+        "origin",
+        [
+            "http://mcp.example.com",
+            "https://mcp.example.com:3000",
+        ],
+    )
+    def test_rejects_same_host_different_origin(self, origin: str):
+        server = FastMCP(name="TestServer")
+        app = create_streamable_http_app(
+            server=server,
+            streamable_http_path="/mcp",
+            host_origin_protection="auto",
+            allowed_hosts=["mcp.example.com"],
+        )
+
+        with TestClient(app, base_url="https://mcp.example.com") as client:
+            response = client.post(
+                "/mcp",
+                headers={
+                    "accept": "application/json, text/event-stream",
+                    "origin": origin,
+                },
+                json=INITIALIZE_REQUEST,
+            )
+
+        assert response.status_code == 403
+        assert "mcp-session-id" not in response.headers
+
+    def test_can_disable_host_origin_protection(self):
+        server = FastMCP(name="TestServer")
+        app = create_streamable_http_app(
+            server=server,
+            streamable_http_path="/mcp",
+            host_origin_protection=False,
+        )
+
+        with TestClient(app, base_url="http://127.0.0.1") as client:
+            response = client.post(
+                "/mcp",
+                headers={
+                    "accept": "application/json, text/event-stream",
+                    "host": "attacker.example",
+                    "origin": "https://attacker.example",
+                },
+                json=INITIALIZE_REQUEST,
+            )
+
+        assert response.status_code == 200
+        assert "mcp-session-id" in response.headers
diff --git a/tests/server/http/test_http_dependencies.py b/tests/server/http/test_http_dependencies.py
new file mode 100644
index 0000000..a2cd497
--- /dev/null
+++ b/tests/server/http/test_http_dependencies.py
@@ -0,0 +1,219 @@
+import json
+
+import pytest
+from mcp_types import TextContent, TextResourceContents
+from starlette.requests import Request
+
+from fastmcp.client import Client
+from fastmcp.client.transports import SSETransport, StreamableHttpTransport
+from fastmcp.server.dependencies import CurrentHeaders, CurrentRequest, get_http_request
+from fastmcp.server.server import FastMCP
+from fastmcp.utilities.tests import run_server_async
+
+
+def fastmcp_server():
+    server = FastMCP()
+
+    # Add a tool
+    @server.tool
+    def get_headers_tool() -> dict[str, str]:
+        """Get the HTTP headers from the request."""
+        request = get_http_request()
+
+        return dict(request.headers)
+
+    @server.resource(uri="request://headers")
+    async def get_headers_resource() -> str:
+        import json
+
+        request = get_http_request()
+        return json.dumps(dict(request.headers))
+
+    # Add a prompt
+    @server.prompt
+    def get_headers_prompt() -> str:
+        """Get the HTTP headers from the request."""
+        request = get_http_request()
+
+        return json.dumps(dict(request.headers))
+
+    return server
+
+
+@pytest.fixture
+async def shttp_server():
+    """Start a test server with StreamableHttp transport."""
+    server = fastmcp_server()
+    async with run_server_async(server, transport="http") as url:
+        yield url
+
+
+@pytest.fixture
+async def sse_server():
+    """Start a test server with SSE transport."""
+    server = fastmcp_server()
+    async with run_server_async(server, transport="sse") as url:
+        yield url
+
+
+async def test_http_headers_resource_shttp(shttp_server: str):
+    """Test getting HTTP headers from the server."""
+    async with Client(
+        transport=StreamableHttpTransport(
+            shttp_server, headers={"X-DEMO-HEADER": "ABC"}
+        )
+    ) as client:
+        raw_result = await client.read_resource("request://headers")
+        assert isinstance(raw_result[0], TextResourceContents)
+        json_result = json.loads(raw_result[0].text)
+        assert "x-demo-header" in json_result
+        assert json_result["x-demo-header"] == "ABC"
+
+
+async def test_http_headers_resource_sse(sse_server: str):
+    """Test getting HTTP headers from the server."""
+    async with Client(
+        transport=SSETransport(sse_server, headers={"X-DEMO-HEADER": "ABC"})
+    ) as client:
+        raw_result = await client.read_resource("request://headers")
+        assert isinstance(raw_result[0], TextResourceContents)
+        json_result = json.loads(raw_result[0].text)
+        assert "x-demo-header" in json_result
+        assert json_result["x-demo-header"] == "ABC"
+
+
+async def test_http_headers_tool_shttp(shttp_server: str):
+    """Test getting HTTP headers from the server."""
+    async with Client(
+        transport=StreamableHttpTransport(
+            shttp_server, headers={"X-DEMO-HEADER": "ABC"}
+        )
+    ) as client:
+        result = await client.call_tool("get_headers_tool")
+        assert "x-demo-header" in result.data
+        assert result.data["x-demo-header"] == "ABC"
+
+
+async def test_http_headers_tool_sse(sse_server: str):
+    async with Client(
+        transport=SSETransport(sse_server, headers={"X-DEMO-HEADER": "ABC"})
+    ) as client:
+        result = await client.call_tool("get_headers_tool")
+        assert "x-demo-header" in result.data
+        assert result.data["x-demo-header"] == "ABC"
+
+
+async def test_http_headers_prompt_shttp(shttp_server: str):
+    """Test getting HTTP headers from the server."""
+    async with Client(
+        transport=StreamableHttpTransport(
+            shttp_server, headers={"X-DEMO-HEADER": "ABC"}
+        )
+    ) as client:
+        result = await client.get_prompt("get_headers_prompt")
+        assert isinstance(result.messages[0].content, TextContent)
+        json_result = json.loads(result.messages[0].content.text)
+        assert "x-demo-header" in json_result
+        assert json_result["x-demo-header"] == "ABC"
+
+
+async def test_http_headers_prompt_sse(sse_server: str):
+    """Test getting HTTP headers from the server."""
+    async with Client(
+        transport=SSETransport(sse_server, headers={"X-DEMO-HEADER": "ABC"})
+    ) as client:
+        result = await client.get_prompt("get_headers_prompt")
+        assert isinstance(result.messages[0].content, TextContent)
+        json_result = json.loads(result.messages[0].content.text)
+        assert "x-demo-header" in json_result
+        assert json_result["x-demo-header"] == "ABC"
+
+
+async def test_get_http_headers_excludes_content_type(sse_server: str):
+    """Test that get_http_headers() excludes content-type header (issue #3097).
+
+    This prevents HTTP 415 errors when forwarding headers to downstream APIs
+    that require specific Content-Type headers (e.g., application/vnd.api+json).
+    """
+    from fastmcp.server.dependencies import get_http_headers
+
+    server = FastMCP()
+
+    @server.tool
+    def check_excluded_headers() -> dict[str, str]:
+        """Check that problematic headers are excluded from get_http_headers()."""
+        return get_http_headers()
+
+    async with run_server_async(server, transport="sse") as url:
+        async with Client(
+            transport=SSETransport(
+                url,
+                headers={
+                    "Content-Type": "application/json",
+                    "Accept": "application/json",
+                    "X-Custom-Header": "should-be-included",
+                },
+            )
+        ) as client:
+            result = await client.call_tool("check_excluded_headers")
+            headers = result.data
+
+            # These headers should be excluded
+            assert "content-type" not in headers
+            assert "accept" not in headers
+            assert "host" not in headers
+            assert "content-length" not in headers
+
+            # Custom headers should be included
+            assert "x-custom-header" in headers
+            assert headers["x-custom-header"] == "should-be-included"
+
+
+async def test_background_task_can_read_snapshotted_request_headers():
+    """Background tools can still access request headers via get_http_request()."""
+    server = FastMCP()
+
+    @server.tool(task=True)
+    async def check_request_header() -> str:
+        request = get_http_request()
+        return request.headers.get("x-tenant-id", "missing")
+
+    async with run_server_async(server, transport="sse") as url:
+        async with Client(
+            transport=SSETransport(url, headers={"X-Tenant-ID": "tenant-123"})
+        ) as client:
+            task = await client.call_tool("check_request_header", task=True)
+            result = await task.result()
+            assert result.data == "tenant-123"
+
+
+async def test_background_task_current_http_dependencies_restore_headers():
+    """CurrentHeaders/CurrentRequest work in task workers without explicit Context."""
+    server = FastMCP()
+
+    @server.tool(task=True)
+    async def check_headers(
+        headers: dict[str, str] = CurrentHeaders(),
+        request: Request = CurrentRequest(),
+    ) -> dict[str, str]:
+        return {
+            "authorization": headers.get("authorization", "missing"),
+            "tenant": request.headers.get("x-tenant-id", "missing"),
+        }
+
+    async with run_server_async(server, transport="sse") as url:
+        async with Client(
+            transport=SSETransport(
+                url,
+                headers={
+                    "Authorization": "Bearer tenant-token",
+                    "X-Tenant-ID": "tenant-456",
+                },
+            )
+        ) as client:
+            task = await client.call_tool("check_headers", task=True)
+            result = await task.result()
+            assert result.data == {
+                "authorization": "Bearer tenant-token",
+                "tenant": "tenant-456",
+            }
diff --git a/tests/server/http/test_http_middleware.py b/tests/server/http/test_http_middleware.py
new file mode 100644
index 0000000..94b263d
--- /dev/null
+++ b/tests/server/http/test_http_middleware.py
@@ -0,0 +1,229 @@
+"""Tests for middleware in HTTP apps."""
+
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+from httpx import ASGITransport
+from starlette.middleware import Middleware
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.routing import BaseRoute, Route
+from starlette.types import ASGIApp
+
+from fastmcp.server import FastMCP
+from fastmcp.server.http import create_sse_app, create_streamable_http_app
+
+
+class HeaderMiddleware(BaseHTTPMiddleware):
+    """Simple middleware that adds a custom header to responses."""
+
+    def __init__(self, app: ASGIApp, header_name: str, header_value: str):
+        super().__init__(app)
+        self.header_name = header_name
+        self.header_value = header_value
+
+    async def dispatch(self, request: Request, call_next: Callable):
+        response = await call_next(request)
+        response.headers[self.header_name] = self.header_value
+        return response
+
+
+class RequestModifierMiddleware(BaseHTTPMiddleware):
+    """Middleware that adds a value to request state."""
+
+    def __init__(self, app: ASGIApp, key: str, value: Any):
+        super().__init__(app)
+        self.key = key
+        self.value = value
+
+    async def dispatch(self, request: Request, call_next: Callable):
+        request.state.custom_value = {self.key: self.value}
+        return await call_next(request)
+
+
+async def endpoint_handler(request: Request):
+    """Endpoint that returns request state or headers."""
+    if hasattr(request.state, "custom_value"):
+        return JSONResponse({"state": request.state.custom_value})
+    return JSONResponse({"message": "Hello, world!"})
+
+
+async def test_sse_app_with_custom_middleware():
+    """Test that custom middleware works with SSE app."""
+    server = FastMCP(name="TestServer")
+
+    # Create custom middleware
+    custom_middleware = [
+        Middleware(
+            HeaderMiddleware,  # type: ignore[arg-type]
+            header_name="X-Custom-Header",
+            header_value="test-value",
+        )
+    ]
+
+    # Add a test route to server's additional routes
+    routes: list[BaseRoute] = [Route("/test", endpoint_handler)]
+    server._additional_http_routes = routes
+
+    # Create the app with custom middleware
+    app = server.http_app(transport="sse", middleware=custom_middleware)
+
+    # Create a test client
+    transport = ASGITransport(app=app)
+    async with httpx.AsyncClient(
+        transport=transport, base_url="http://testserver"
+    ) as client:
+        response = await client.get("/test")
+
+        # Verify middleware was applied
+        assert response.status_code == 200
+        assert response.headers["X-Custom-Header"] == "test-value"
+
+
+async def test_streamable_http_app_with_custom_middleware():
+    """Test that custom middleware works with StreamableHTTP app."""
+    server = FastMCP(name="TestServer")
+
+    # Create custom middleware
+    custom_middleware = [
+        Middleware(
+            HeaderMiddleware,  # type: ignore[arg-type]
+            header_name="X-Custom-Header",
+            header_value="test-value",
+        )
+    ]
+
+    # Add a test route to server's additional routes
+    routes: list[BaseRoute] = [Route("/test", endpoint_handler)]
+    server._additional_http_routes = routes
+
+    # Create the app with custom middleware
+    app = server.http_app(transport="http", middleware=custom_middleware)
+
+    # Create a test client
+    transport = ASGITransport(app=app)
+    async with httpx.AsyncClient(
+        transport=transport, base_url="http://testserver"
+    ) as client:
+        response = await client.get("/test")
+
+        # Verify middleware was applied
+        assert response.status_code == 200
+        assert response.headers["X-Custom-Header"] == "test-value"
+
+
+async def test_create_sse_app_with_custom_middleware():
+    """Test that custom middleware works with create_sse_app function."""
+    server = FastMCP(name="TestServer")
+
+    # Create custom middleware
+    custom_middleware = [
+        Middleware(
+            RequestModifierMiddleware,  # type: ignore[arg-type]
+            key="modified_by",
+            value="middleware",
+        )
+    ]
+
+    # Add a test route
+    additional_routes: list[BaseRoute] = [Route("/test", endpoint_handler)]
+
+    # Create the app with custom middleware
+    app = create_sse_app(
+        server=server,
+        message_path="/message",
+        sse_path="/sse/",
+        middleware=custom_middleware,
+        routes=additional_routes,
+    )
+
+    # Create a test client
+    transport = ASGITransport(app=app)
+    async with httpx.AsyncClient(
+        transport=transport, base_url="http://testserver"
+    ) as client:
+        response = await client.get("/test")
+
+        # Verify middleware was applied
+        assert response.status_code == 200
+        data = response.json()
+        assert "state" in data
+        assert data["state"]["modified_by"] == "middleware"
+
+
+async def test_create_streamable_http_app_with_custom_middleware():
+    """Test that custom middleware works with create_streamable_http_app function."""
+    server = FastMCP(name="TestServer")
+
+    # Create custom middleware
+    custom_middleware = [
+        Middleware(
+            RequestModifierMiddleware,  # type: ignore[arg-type]
+            key="modified_by",
+            value="middleware",
+        )
+    ]
+
+    # Add a test route
+    additional_routes: list[BaseRoute] = [Route("/test", endpoint_handler)]
+
+    # Create the app with custom middleware
+    app = create_streamable_http_app(
+        server=server,
+        streamable_http_path="/streamable",
+        middleware=custom_middleware,
+        routes=additional_routes,
+    )
+
+    # Create a test client
+    transport = ASGITransport(app=app)
+    async with httpx.AsyncClient(
+        transport=transport, base_url="http://testserver"
+    ) as client:
+        response = await client.get("/test")
+
+        # Verify middleware was applied
+        assert response.status_code == 200
+        data = response.json()
+        assert "state" in data
+        assert data["state"]["modified_by"] == "middleware"
+
+
+async def test_multiple_middleware_ordering():
+    """Test that multiple middleware are applied in the correct order."""
+    server = FastMCP(name="TestServer")
+
+    # Create multiple middleware
+    custom_middleware = [
+        Middleware(
+            HeaderMiddleware,  # type: ignore[arg-type]
+            header_name="X-First-Header",
+            header_value="first",
+        ),
+        Middleware(
+            HeaderMiddleware,  # type: ignore[arg-type]
+            header_name="X-Second-Header",
+            header_value="second",
+        ),
+    ]
+
+    # Add a test route to server's additional routes
+    routes: list[BaseRoute] = [Route("/test", endpoint_handler)]
+    server._additional_http_routes = routes
+
+    # Create the app with custom middleware
+    app = server.http_app(transport="sse", middleware=custom_middleware)
+
+    # Create a test client
+    transport = ASGITransport(app=app)
+    async with httpx.AsyncClient(
+        transport=transport, base_url="http://testserver"
+    ) as client:
+        response = await client.get("/test")
+
+        # Verify both middleware were applied
+        assert response.status_code == 200
+        assert response.headers["X-First-Header"] == "first"
+        assert response.headers["X-Second-Header"] == "second"
diff --git a/tests/server/http/test_lifespan_once_per_process.py b/tests/server/http/test_lifespan_once_per_process.py
new file mode 100644
index 0000000..07a1a8c
--- /dev/null
+++ b/tests/server/http/test_lifespan_once_per_process.py
@@ -0,0 +1,67 @@
+"""Regression test for driving the FastMCP lifespan through the SDK session manager.
+
+Before FastMCP handed its lifespan to the SDK lowlevel Server (PR #4446), the
+SDK v1 lifespan was effectively session-scoped and FastMCP worked around it by
+driving its own ``_lifespan_manager`` beside the session manager. The SDK v2
+``StreamableHTTPSessionManager`` now enters ``app.lifespan(app)`` exactly once
+for the manager's lifetime, so the user lifespan must fire once per process and
+persist across multiple HTTP client sessions -- not once per session.
+"""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastmcp import Client, FastMCP
+from fastmcp.client.transports import StreamableHttpTransport
+from fastmcp.utilities.tests import run_server_async
+
+
+async def test_http_user_lifespan_fires_once_across_sessions():
+    """The user lifespan must be entered exactly once for the server process,
+    even when several independent HTTP client sessions connect and disconnect.
+    """
+    enter_count = 0
+    exit_count = 0
+
+    @asynccontextmanager
+    async def counting_lifespan(mcp: FastMCP) -> AsyncIterator[dict[str, Any]]:
+        nonlocal enter_count, exit_count
+        enter_count += 1
+        try:
+            yield {"initialized": True}
+        finally:
+            exit_count += 1
+
+    server = FastMCP("LifespanOnceServer", lifespan=counting_lifespan)
+
+    @server.tool
+    def ping() -> str:
+        return "pong"
+
+    async with run_server_async(server, transport="http") as mcp_url:
+        # `run_server_async` yields a URL that already includes the `/mcp` path.
+        # Three separate, sequential client sessions against the same process.
+        for _ in range(3):
+            async with Client(StreamableHttpTransport(mcp_url)) as client:
+                result = await client.call_tool("ping", {})
+                assert result.data == "pong"
+            # The lifespan must not have exited when a session closed -- it is
+            # owned by the session manager for the whole process lifetime.
+            assert enter_count == 1
+            assert exit_count == 0
+
+        # Overlapping sessions must also observe a single, still-open lifespan.
+        async with (
+            Client(StreamableHttpTransport(mcp_url)) as c1,
+            Client(StreamableHttpTransport(mcp_url)) as c2,
+        ):
+            assert (await c1.call_tool("ping", {})).data == "pong"
+            assert (await c2.call_tool("ping", {})).data == "pong"
+            assert enter_count == 1
+            assert exit_count == 0
+
+    # After the server process task is torn down, the lifespan has exited once.
+    # (A spurious re-entry during teardown would re-exit, so this also guards
+    # that the lifespan was entered exactly once.)
+    assert exit_count == 1
diff --git a/tests/server/http/test_session_idle_timeout.py b/tests/server/http/test_session_idle_timeout.py
new file mode 100644
index 0000000..6b35587
--- /dev/null
+++ b/tests/server/http/test_session_idle_timeout.py
@@ -0,0 +1,79 @@
+"""Tests for the streamable-HTTP ``session_idle_timeout`` setting.
+
+An idle session is terminated after ``session_idle_timeout`` seconds of
+inactivity. The deadline is reset on every request. This is the SDK's
+behavior, surfaced through FastMCP's ``http_session_idle_timeout`` setting.
+"""
+
+import time
+
+from starlette.testclient import TestClient
+
+from fastmcp.server import FastMCP
+from fastmcp.server.http import (
+    StarletteWithLifespan,
+    StreamableHTTPASGIApp,
+    create_streamable_http_app,
+)
+
+INITIALIZE_REQUEST = {
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "initialize",
+    "params": {
+        "protocolVersion": "2024-11-05",
+        "capabilities": {},
+        "clientInfo": {"name": "client", "version": "0.1"},
+    },
+}
+
+MCP_HEADERS = {"accept": "application/json, text/event-stream"}
+
+
+def _find_session_manager(app: StarletteWithLifespan):
+    for route in app.router.routes:
+        endpoint = getattr(route, "endpoint", None)
+        if isinstance(endpoint, StreamableHTTPASGIApp):
+            return endpoint.session_manager
+    return None
+
+
+def test_idle_session_is_terminated_after_timeout():
+    server = FastMCP(name="IdleTimeoutServer")
+    app = create_streamable_http_app(
+        server=server,
+        streamable_http_path="/mcp",
+        session_idle_timeout=0.2,
+    )
+
+    with TestClient(app, base_url="http://127.0.0.1") as client:
+        response = client.post("/mcp", headers=MCP_HEADERS, json=INITIALIZE_REQUEST)
+        assert response.status_code == 200
+        session_id = response.headers.get("mcp-session-id")
+        assert session_id is not None
+
+        sm = _find_session_manager(app)
+        assert sm is not None
+        assert session_id in sm._server_instances
+
+        # Wait past the idle deadline; the SDK's idle cancel scope fires and
+        # removes the session from the active instances. Poll to stay fast.
+        deadline = time.monotonic() + 3.0
+        while time.monotonic() < deadline:
+            if session_id not in sm._server_instances:
+                break
+            time.sleep(0.05)
+
+        assert session_id not in sm._server_instances
+
+        # The now-expired session id is rejected with 404.
+        response = client.post(
+            "/mcp",
+            headers={
+                **MCP_HEADERS,
+                "mcp-session-id": session_id,
+                "mcp-protocol-version": "2024-11-05",
+            },
+            json={"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}},
+        )
+        assert response.status_code == 404
diff --git a/tests/server/http/test_session_owner_enforcement.py b/tests/server/http/test_session_owner_enforcement.py
new file mode 100644
index 0000000..f1fdf5f
--- /dev/null
+++ b/tests/server/http/test_session_owner_enforcement.py
@@ -0,0 +1,109 @@
+"""End-to-end tests for session-owner credential enforcement.
+
+A streamable-HTTP session is bound to the credential that created it. A request
+that presents a different credential for the same ``Mcp-Session-Id`` is rejected
+with 404, exactly as if the session did not exist. This closes a gap where a
+leaked session id was usable by any bearer.
+
+Enforcement lives in the SDK's ``StreamableHTTPSessionManager`` (the
+``_session_owners`` map). It is active on FastMCP's stateful HTTP path because
+the session manager owns the server lifecycle (its ``run()`` drives our
+lifespan through ``_lifespan_proxy``).
+"""
+
+from starlette.testclient import TestClient
+
+from fastmcp.server import FastMCP
+from fastmcp.server.auth.providers.jwt import StaticTokenVerifier
+from fastmcp.server.http import StarletteWithLifespan, create_streamable_http_app
+
+INITIALIZE_REQUEST = {
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "initialize",
+    "params": {
+        "protocolVersion": "2024-11-05",
+        "capabilities": {},
+        "clientInfo": {"name": "client", "version": "0.1"},
+    },
+}
+
+TOOLS_LIST_REQUEST = {
+    "jsonrpc": "2.0",
+    "id": 2,
+    "method": "tools/list",
+    "params": {},
+}
+
+TOKEN_A = "token-a"
+TOKEN_B = "token-b"
+
+MCP_HEADERS = {"accept": "application/json, text/event-stream"}
+
+
+def _make_app() -> StarletteWithLifespan:
+    verifier = StaticTokenVerifier(
+        tokens={
+            TOKEN_A: {"client_id": "client-a", "scopes": []},
+            TOKEN_B: {"client_id": "client-b", "scopes": []},
+        }
+    )
+    server = FastMCP(name="OwnerEnforcementServer", auth=verifier)
+    return create_streamable_http_app(
+        server=server,
+        streamable_http_path="/mcp",
+        auth=verifier,
+    )
+
+
+def _initialize(client: TestClient, token: str) -> str:
+    """Create a session with the given token and return its session id."""
+    response = client.post(
+        "/mcp",
+        headers={**MCP_HEADERS, "authorization": f"Bearer {token}"},
+        json=INITIALIZE_REQUEST,
+    )
+    assert response.status_code == 200
+    session_id = response.headers.get("mcp-session-id")
+    assert session_id is not None
+    return session_id
+
+
+def test_session_reuse_with_creating_credential_succeeds():
+    app = _make_app()
+    with TestClient(app, base_url="http://127.0.0.1") as client:
+        session_id = _initialize(client, TOKEN_A)
+
+        response = client.post(
+            "/mcp",
+            headers={
+                **MCP_HEADERS,
+                "authorization": f"Bearer {TOKEN_A}",
+                "mcp-session-id": session_id,
+                "mcp-protocol-version": "2024-11-05",
+            },
+            json=TOOLS_LIST_REQUEST,
+        )
+
+        assert response.status_code == 200
+
+
+def test_session_reuse_with_different_credential_returns_404():
+    """A session created with credential A must not be usable with credential B."""
+    app = _make_app()
+    with TestClient(app, base_url="http://127.0.0.1") as client:
+        session_id = _initialize(client, TOKEN_A)
+
+        response = client.post(
+            "/mcp",
+            headers={
+                **MCP_HEADERS,
+                "authorization": f"Bearer {TOKEN_B}",
+                "mcp-session-id": session_id,
+                "mcp-protocol-version": "2024-11-05",
+            },
+            json=TOOLS_LIST_REQUEST,
+        )
+
+        # Responds exactly as if the session did not exist.
+        assert response.status_code == 404
diff --git a/tests/server/http/test_stale_access_token.py b/tests/server/http/test_stale_access_token.py
new file mode 100644
index 0000000..c2cf191
--- /dev/null
+++ b/tests/server/http/test_stale_access_token.py
@@ -0,0 +1,168 @@
+"""
+Test for issue #1863: get_access_token() returns stale token after OAuth refresh.
+
+This test demonstrates the bug where auth_context_var holds a stale token,
+but the current HTTP request (via request_ctx) has a fresh token.
+
+The test should FAIL with the current implementation and PASS after the fix.
+"""
+
+from unittest.mock import MagicMock
+
+from mcp.server.auth.middleware.auth_context import auth_context_var
+from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser
+from starlette.requests import Request
+
+from fastmcp.server.auth import AccessToken
+from fastmcp.server.dependencies import (
+    FastMCPRequestContext,
+    fastmcp_request_ctx,
+    get_access_token,
+)
+
+
+def _make_ctx(request: Request | None) -> FastMCPRequestContext:
+    return FastMCPRequestContext(
+        session=MagicMock(),
+        request_id="0",
+        meta=None,
+        request=request,
+        protocol_version="2025-06-18",
+        close_sse_stream=None,
+        lifespan_context=MagicMock(),
+        _srctx=MagicMock(meta=None),
+    )
+
+
+class TestStaleAccessToken:
+    """Test that get_access_token returns fresh token from request scope."""
+
+    def test_get_access_token_prefers_request_scope_over_stale_context_var(self):
+        """
+        Regression test for issue #1863.
+
+        Scenario:
+        - auth_context_var has a STALE token (set at HTTP middleware level)
+        - request_ctx.request.scope["user"] has a FRESH token (per MCP message)
+        - get_access_token() should return the FRESH token
+
+        This simulates the case where:
+        1. A Streamable HTTP session was established with token A
+        2. auth_context_var was set to token A during session setup
+        3. Token expired, client refreshed, got token B
+        4. New MCP message arrives with token B in the request
+        5. get_access_token() should return token B, not stale token A
+        """
+        # Create STALE token (in auth_context_var)
+        # Using FastMCP's AccessToken to avoid conversion issues
+        stale_token = AccessToken(
+            token="stale-token-from-initial-auth",
+            client_id="test-client",
+            scopes=["read"],
+        )
+        stale_user = AuthenticatedUser(stale_token)
+
+        # Create FRESH token (in request.scope["user"])
+        fresh_token = AccessToken(
+            token="fresh-token-after-refresh",
+            client_id="test-client",
+            scopes=["read"],
+        )
+        fresh_user = AuthenticatedUser(fresh_token)
+
+        # Create a mock request with fresh token in scope
+        scope = {
+            "type": "http",
+            "user": fresh_user,
+            "auth": MagicMock(),
+        }
+        mock_request = Request(scope)
+
+        # Set up the context vars:
+        # - auth_context_var has STALE token
+        # - fastmcp_request_ctx has request with FRESH token
+        auth_token = auth_context_var.set(stale_user)
+        request_token = fastmcp_request_ctx.set(_make_ctx(mock_request))
+
+        try:
+            # Call get_access_token - should return FRESH token
+            result = get_access_token()
+
+            # Assert we get the FRESH token, not the stale one
+            assert result is not None, "Expected an access token but got None"
+            assert result.token == "fresh-token-after-refresh", (
+                f"Expected fresh token 'fresh-token-after-refresh' but got '{result.token}'. "
+                "get_access_token() is returning the stale token from auth_context_var "
+                "instead of the fresh token from request.scope['user']."
+            )
+        finally:
+            # Clean up context vars
+            auth_context_var.reset(auth_token)
+            fastmcp_request_ctx.reset(request_token)
+
+    def test_get_access_token_falls_back_to_context_var_when_no_request(self):
+        """
+        Verify that get_access_token falls back to auth_context_var
+        when there's no HTTP request available.
+        """
+        # Create token in auth_context_var using FastMCP's AccessToken
+        token = AccessToken(
+            token="context-var-token",
+            client_id="test-client",
+            scopes=["read"],
+        )
+        user = AuthenticatedUser(token)
+
+        # Set up auth_context_var but NOT request_ctx
+        auth_token = auth_context_var.set(user)
+
+        try:
+            result = get_access_token()
+
+            assert result is not None
+            assert result.token == "context-var-token"
+        finally:
+            auth_context_var.reset(auth_token)
+
+    def test_get_access_token_returns_none_when_no_auth(self):
+        """
+        Verify that get_access_token returns None when there's no
+        authenticated user anywhere.
+        """
+        result = get_access_token()
+        assert result is None
+
+    def test_get_access_token_falls_back_when_scope_user_is_not_authenticated(self):
+        """
+        Verify that get_access_token falls back to auth_context_var when
+        scope["user"] exists but is not an AuthenticatedUser (e.g., UnauthenticatedUser).
+        """
+        from starlette.authentication import UnauthenticatedUser
+
+        # Create token in auth_context_var
+        token = AccessToken(
+            token="context-var-token",
+            client_id="test-client",
+            scopes=["read"],
+        )
+        user = AuthenticatedUser(token)
+
+        # Create request with UnauthenticatedUser in scope
+        scope = {
+            "type": "http",
+            "user": UnauthenticatedUser(),
+        }
+        mock_request = Request(scope)
+
+        auth_token = auth_context_var.set(user)
+        request_token = fastmcp_request_ctx.set(_make_ctx(mock_request))
+
+        try:
+            result = get_access_token()
+
+            # Should fall back to auth_context_var since scope user is unauthenticated
+            assert result is not None
+            assert result.token == "context-var-token"
+        finally:
+            auth_context_var.reset(auth_token)
+            fastmcp_request_ctx.reset(request_token)
diff --git a/tests/server/http/test_streamable_http_shutdown.py b/tests/server/http/test_streamable_http_shutdown.py
new file mode 100644
index 0000000..ae32376
--- /dev/null
+++ b/tests/server/http/test_streamable_http_shutdown.py
@@ -0,0 +1,36 @@
+"""Regression tests for graceful streamable-HTTP shutdown (issue #3025)."""
+
+from unittest.mock import AsyncMock
+
+from fastmcp.server import FastMCP
+
+
+async def test_lifespan_terminates_active_transports_before_task_group_cancel():
+    """Active streamable-HTTP transports must be terminated during lifespan
+    shutdown so streaming responses end cleanly instead of being aborted by
+    the session manager's task-group cancel.
+
+    See PrefectHQ/fastmcp#3025: without graceful termination, Uvicorn logs
+    "ASGI callable returned without completing response." on CTRL+C while a
+    client holds an SSE GET stream open.
+    """
+    server = FastMCP(name="ShutdownTest")
+    app = server.http_app(path="/mcp")
+
+    fake_transport = AsyncMock()
+    fake_transport.terminate = AsyncMock()
+
+    async with app.router.lifespan_context(app):
+        # The session manager is constructed inside the lifespan; once it has
+        # started, register a fake active transport as if a client were
+        # holding an SSE stream open.
+        sm = None
+        for route in app.router.routes:
+            endpoint = getattr(route, "endpoint", None)
+            sm = getattr(endpoint, "session_manager", None)
+            if sm is not None:
+                break
+        assert sm is not None, "streamable-http session manager not initialised"
+        sm._server_instances["fake-session"] = fake_transport
+
+    fake_transport.terminate.assert_awaited_once()
diff --git a/tests/server/middleware/__init__.py b/tests/server/middleware/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/server/middleware/test_caching.py b/tests/server/middleware/test_caching.py
new file mode 100644
index 0000000..8169dbd
--- /dev/null
+++ b/tests/server/middleware/test_caching.py
@@ -0,0 +1,848 @@
+"""Tests for response caching middleware."""
+
+import sys
+import tempfile
+import warnings
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock
+
+import mcp_types
+import pytest
+from inline_snapshot import snapshot
+from key_value.aio.stores.filetree import (
+    FileTreeStore,
+    FileTreeV1CollectionSanitizationStrategy,
+    FileTreeV1KeySanitizationStrategy,
+)
+from key_value.aio.stores.memory import MemoryStore
+from key_value.aio.wrappers.statistics.wrapper import (
+    GetStatistics,
+    KVStoreCollectionStatistics,
+    PutStatistics,
+)
+from mcp.server.lowlevel.helper_types import ReadResourceContents
+from mcp_types import TextContent, TextResourceContents
+from pydantic import AnyUrl, BaseModel
+
+from fastmcp import Context, FastMCP
+from fastmcp.client.client import CallToolResult, Client
+from fastmcp.client.transports import FastMCPTransport
+from fastmcp.prompts.base import Message, Prompt
+from fastmcp.prompts.function_prompt import FunctionPrompt
+from fastmcp.resources.base import Resource
+from fastmcp.server.middleware.caching import (
+    ANONYMOUS_AUTH_KEY,
+    CachableToolResult,
+    CallToolSettings,
+    ResponseCachingMiddleware,
+    ResponseCachingStatistics,
+    _make_call_tool_cache_key,
+    _make_get_prompt_cache_key,
+    _make_read_resource_cache_key,
+)
+from fastmcp.server.middleware.middleware import CallNext, MiddlewareContext
+from fastmcp.tools.base import Tool, ToolResult
+
+TEST_URI = AnyUrl("https://test_uri")
+
+SAMPLE_READ_RESOURCE_CONTENTS = ReadResourceContents(
+    content="test_text",
+    mime_type="text/plain",
+)
+
+
+def sample_resource_fn() -> list[ReadResourceContents]:
+    return [SAMPLE_READ_RESOURCE_CONTENTS]
+
+
+def sample_prompt_fn() -> Message:
+    return Message("test_text")
+
+
+SAMPLE_RESOURCE = Resource.from_function(
+    fn=sample_resource_fn, uri=TEST_URI, name="test_resource"
+)
+
+SAMPLE_PROMPT = Prompt.from_function(fn=sample_prompt_fn, name="test_prompt")
+SAMPLE_GET_PROMPT_RESULT = mcp_types.GetPromptResult(
+    messages=[Message("test_text").to_mcp_prompt_message()]
+)
+SAMPLE_TOOL = Tool(name="test_tool", parameters={"param1": "value1", "param2": 42})
+SAMPLE_TOOL_RESULT = ToolResult(
+    content=[TextContent(type="text", text="test_text")],
+    structured_content={"result": "test_result"},
+)
+SAMPLE_TOOL_RESULT_LARGE = ToolResult(
+    content=[TextContent(type="text", text="test_text" * 100)],
+    structured_content={"result": "test_result"},
+)
+
+
+class CrazyModel(BaseModel):
+    a: int
+    b: int
+    c: str
+    d: float
+    e: bool
+    f: list[int]
+    g: dict[str, int]
+    h: list[dict[str, int]]
+    i: dict[str, list[int]]
+
+
+@pytest.fixture
+def crazy_model() -> CrazyModel:
+    return CrazyModel(
+        a=5,
+        b=10,
+        c="test",
+        d=1.0,
+        e=True,
+        f=[1, 2, 3],
+        g={"a": 1, "b": 2},
+        h=[{"a": 1, "b": 2}],
+        i={"a": [1, 2]},
+    )
+
+
+class TrackingCalculator:
+    add_calls: int
+    multiply_calls: int
+    crazy_calls: int
+    very_large_response_calls: int
+
+    def __init__(self):
+        self.add_calls = 0
+        self.multiply_calls = 0
+        self.crazy_calls = 0
+        self.very_large_response_calls = 0
+
+    def add(self, a: int, b: int) -> int:
+        self.add_calls += 1
+        return a + b
+
+    def multiply(self, a: int, b: int) -> int:
+        self.multiply_calls += 1
+        return a * b
+
+    def very_large_response(self) -> str:
+        self.very_large_response_calls += 1
+        return "istenchars" * 100000  # 1,000,000 characters, 1mb
+
+    def crazy(self, a: CrazyModel) -> CrazyModel:
+        self.crazy_calls += 1
+        return a
+
+    def how_to_calculate(self, a: int, b: int) -> str:
+        return f"To calculate {a} + {b}, you need to add {a} and {b} together."
+
+    def get_add_calls(self) -> str:
+        return str(self.add_calls)
+
+    def get_multiply_calls(self) -> str:
+        return str(self.multiply_calls)
+
+    def get_crazy_calls(self) -> str:
+        return str(self.crazy_calls)
+
+    async def update_tool_list(self, context: Context):
+        import mcp_types
+
+        await context.send_notification(mcp_types.ToolListChangedNotification())
+
+    def add_tools(self, fastmcp: FastMCP, prefix: str = ""):
+        _ = fastmcp.add_tool(tool=Tool.from_function(fn=self.add, name=f"{prefix}add"))
+        _ = fastmcp.add_tool(
+            tool=Tool.from_function(fn=self.multiply, name=f"{prefix}multiply")
+        )
+        _ = fastmcp.add_tool(
+            tool=Tool.from_function(fn=self.crazy, name=f"{prefix}crazy")
+        )
+        _ = fastmcp.add_tool(
+            tool=Tool.from_function(
+                fn=self.very_large_response, name=f"{prefix}very_large_response"
+            )
+        )
+        _ = fastmcp.add_tool(
+            tool=Tool.from_function(
+                fn=self.update_tool_list, name=f"{prefix}update_tool_list"
+            )
+        )
+
+    def add_prompts(self, fastmcp: FastMCP, prefix: str = ""):
+        _ = fastmcp.add_prompt(
+            prompt=FunctionPrompt.from_function(
+                fn=self.how_to_calculate, name=f"{prefix}how_to_calculate"
+            )
+        )
+
+    def add_resources(self, fastmcp: FastMCP, prefix: str = ""):
+        _ = fastmcp.add_resource(
+            resource=Resource.from_function(
+                fn=self.get_add_calls,
+                uri="resource://add_calls",
+                name=f"{prefix}add_calls",
+            )
+        )
+        _ = fastmcp.add_resource(
+            resource=Resource.from_function(
+                fn=self.get_multiply_calls,
+                uri="resource://multiply_calls",
+                name=f"{prefix}multiply_calls",
+            )
+        )
+        _ = fastmcp.add_resource(
+            resource=Resource.from_function(
+                fn=self.get_crazy_calls,
+                uri="resource://crazy_calls",
+                name=f"{prefix}crazy_calls",
+            )
+        )
+
+
+@pytest.fixture
+def tracking_calculator() -> TrackingCalculator:
+    return TrackingCalculator()
+
+
+@pytest.fixture
+def mock_context() -> MiddlewareContext[mcp_types.CallToolRequestParams]:
+    """Create a mock middleware context for tool calls."""
+    context = MagicMock(spec=MiddlewareContext[mcp_types.CallToolRequestParams])
+    context.message = mcp_types.CallToolRequestParams(
+        name="test_tool", arguments={"param1": "value1", "param2": 42}
+    )
+    context.method = "tools/call"
+    return context
+
+
+@pytest.fixture
+def mock_call_next() -> CallNext[mcp_types.CallToolRequestParams, ToolResult]:
+    """Create a mock call_next function."""
+    return AsyncMock(
+        return_value=ToolResult(
+            content=[TextContent(type="text", text="test result")],
+            structured_content={"result": "success", "value": 123},
+        )
+    )
+
+
+@pytest.fixture
+def sample_tool_result() -> ToolResult:
+    """Create a sample tool result for testing."""
+    return ToolResult(
+        content=[TextContent(type="text", text="cached result")],
+        structured_content={"cached": True, "data": "test"},
+    )
+
+
+class TestResponseCachingMiddleware:
+    """Test ResponseCachingMiddleware functionality."""
+
+    def test_initialization(self):
+        """Test middleware initialization."""
+        assert ResponseCachingMiddleware(
+            call_tool_settings=CallToolSettings(
+                included_tools=["tool1"],
+                excluded_tools=["tool2"],
+            ),
+        )
+
+    @pytest.mark.parametrize(
+        ("tool_name", "included_tools", "excluded_tools", "result"),
+        [
+            ("tool", ["tool", "tool2"], [], True),
+            ("tool", ["second tool", "third tool"], [], False),
+            ("tool", [], ["tool"], False),
+            ("tool", [], ["second tool"], True),
+            ("tool", ["tool", "second tool"], ["tool"], False),
+            ("tool", ["tool", "second tool"], ["second tool"], True),
+        ],
+        ids=[
+            "tool is included",
+            "tool is not included",
+            "tool is excluded",
+            "tool is not excluded",
+            "tool is included and excluded (excluded takes precedence)",
+            "tool is included and not excluded",
+        ],
+    )
+    def test_tool_call_filtering(
+        self,
+        tool_name: str,
+        included_tools: list[str],
+        excluded_tools: list[str],
+        result: bool,
+    ):
+        """Test tool filtering logic."""
+
+        middleware1 = ResponseCachingMiddleware(
+            call_tool_settings=CallToolSettings(
+                included_tools=included_tools, excluded_tools=excluded_tools
+            ),
+        )
+        assert middleware1._matches_tool_cache_settings(tool_name=tool_name) is result
+
+
+@pytest.mark.skipif(
+    sys.platform == "win32",
+    reason="SQLite caching tests are flaky on Windows due to temp directory issues.",
+)
+class TestResponseCachingMiddlewareIntegration:
+    """Integration tests with real FastMCP server."""
+
+    @pytest.fixture(params=["memory", "filetree"])
+    async def caching_server(
+        self,
+        tracking_calculator: TrackingCalculator,
+        request: pytest.FixtureRequest,
+    ):
+        """Create a FastMCP server for caching tests."""
+        mcp = FastMCP("CachingTestServer", dereference_schemas=False)
+
+        with tempfile.TemporaryDirectory(ignore_cleanup_errors=True) as temp_dir:
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore", UserWarning)
+                file_store = FileTreeStore(
+                    data_directory=Path(temp_dir),
+                    key_sanitization_strategy=FileTreeV1KeySanitizationStrategy(
+                        Path(temp_dir)
+                    ),
+                    collection_sanitization_strategy=FileTreeV1CollectionSanitizationStrategy(
+                        Path(temp_dir)
+                    ),
+                )
+            response_caching_middleware = ResponseCachingMiddleware(
+                cache_storage=file_store
+                if request.param == "filetree"
+                else MemoryStore(),
+            )
+
+            mcp.add_middleware(middleware=response_caching_middleware)
+
+            tracking_calculator.add_tools(fastmcp=mcp)
+            tracking_calculator.add_resources(fastmcp=mcp)
+            tracking_calculator.add_prompts(fastmcp=mcp)
+
+            yield mcp
+
+    @pytest.fixture
+    def non_caching_server(self, tracking_calculator: TrackingCalculator):
+        """Create a FastMCP server for non-caching tests."""
+        mcp = FastMCP("NonCachingTestServer")
+        tracking_calculator.add_tools(fastmcp=mcp)
+        return mcp
+
+    async def test_list_tools(
+        self, caching_server: FastMCP, tracking_calculator: TrackingCalculator
+    ):
+        """Test that tool list caching works with a real FastMCP server."""
+
+        async with Client(caching_server) as client:
+            pre_tool_list: list[mcp_types.Tool] = await client.list_tools()
+            assert len(pre_tool_list) == 5
+
+            # Add a tool and make sure it's missing from the list tool response
+            _ = caching_server.add_tool(
+                tool=Tool.from_function(fn=tracking_calculator.add, name="add_2")
+            )
+
+            post_tool_list: list[mcp_types.Tool] = await client.list_tools()
+            assert len(post_tool_list) == 5
+
+            assert pre_tool_list == post_tool_list
+
+    async def test_call_tool(
+        self,
+        caching_server: FastMCP,
+        tracking_calculator: TrackingCalculator,
+    ):
+        """Test that caching works with a real FastMCP server."""
+        tracking_calculator.add_tools(fastmcp=caching_server)
+
+        async with Client[FastMCPTransport](transport=caching_server) as client:
+            call_tool_result_one: CallToolResult = await client.call_tool(
+                "add", {"a": 5, "b": 3}
+            )
+
+            assert tracking_calculator.add_calls == 1
+            call_tool_result_two: CallToolResult = await client.call_tool(
+                "add", {"a": 5, "b": 3}
+            )
+            assert call_tool_result_one == call_tool_result_two
+
+    async def test_call_tool_very_large_value(
+        self,
+        caching_server: FastMCP,
+        tracking_calculator: TrackingCalculator,
+    ):
+        """Test that caching works with a real FastMCP server."""
+        tracking_calculator.add_tools(fastmcp=caching_server)
+
+        async with Client[FastMCPTransport](transport=caching_server) as client:
+            call_tool_result_one: CallToolResult = await client.call_tool(
+                "very_large_response", {}
+            )
+
+            assert tracking_calculator.very_large_response_calls == 1
+            call_tool_result_two: CallToolResult = await client.call_tool(
+                "very_large_response", {}
+            )
+            assert call_tool_result_one == call_tool_result_two
+            assert tracking_calculator.very_large_response_calls == 2
+
+    async def test_call_tool_crazy_value(
+        self,
+        caching_server: FastMCP,
+        tracking_calculator: TrackingCalculator,
+        crazy_model: CrazyModel,
+    ):
+        """Test that caching works with a real FastMCP server."""
+        tracking_calculator.add_tools(fastmcp=caching_server)
+
+        async with Client[FastMCPTransport](transport=caching_server) as client:
+            call_tool_result_one: CallToolResult = await client.call_tool(
+                "crazy", {"a": crazy_model}
+            )
+
+            assert tracking_calculator.crazy_calls == 1
+            call_tool_result_two: CallToolResult = await client.call_tool(
+                "crazy", {"a": crazy_model}
+            )
+            assert call_tool_result_one == call_tool_result_two
+            assert tracking_calculator.crazy_calls == 1
+
+    async def test_list_resources(
+        self, caching_server: FastMCP, tracking_calculator: TrackingCalculator
+    ):
+        """Test that list resources caching works with a real FastMCP server."""
+        async with Client[FastMCPTransport](transport=caching_server) as client:
+            pre_resource_list: list[mcp_types.Resource] = await client.list_resources()
+
+            assert len(pre_resource_list) == 3
+
+            tracking_calculator.add_resources(fastmcp=caching_server)
+
+            post_resource_list: list[mcp_types.Resource] = await client.list_resources()
+            assert len(post_resource_list) == 3
+
+            assert pre_resource_list == post_resource_list
+
+    async def test_read_resource(
+        self, caching_server: FastMCP, tracking_calculator: TrackingCalculator
+    ):
+        """Test that get resources caching works with a real FastMCP server."""
+        async with Client[FastMCPTransport](transport=caching_server) as client:
+            pre_resource = await client.read_resource(uri="resource://add_calls")
+            assert isinstance(pre_resource[0], TextResourceContents)
+            assert pre_resource[0].text == "0"
+
+            tracking_calculator.add_calls = 1
+
+            post_resource = await client.read_resource(uri="resource://add_calls")
+            assert isinstance(post_resource[0], TextResourceContents)
+            assert post_resource[0].text == "0"
+            assert pre_resource == post_resource
+
+    async def test_list_prompts(
+        self, caching_server: FastMCP, tracking_calculator: TrackingCalculator
+    ):
+        """Test that list prompts caching works with a real FastMCP server."""
+        async with Client[FastMCPTransport](transport=caching_server) as client:
+            pre_prompt_list: list[mcp_types.Prompt] = await client.list_prompts()
+
+            assert len(pre_prompt_list) == 1
+
+            tracking_calculator.add_prompts(fastmcp=caching_server)
+
+            post_prompt_list: list[mcp_types.Prompt] = await client.list_prompts()
+
+            assert len(post_prompt_list) == 1
+
+            assert pre_prompt_list == post_prompt_list
+
+    async def test_get_prompts(
+        self, caching_server: FastMCP, tracking_calculator: TrackingCalculator
+    ):
+        """Test that get prompts caching works with a real FastMCP server."""
+        async with Client[FastMCPTransport](transport=caching_server) as client:
+            pre_prompt = await client.get_prompt(
+                name="how_to_calculate", arguments={"a": 5, "b": 3}
+            )
+
+            pre_prompt_content = pre_prompt.messages[0].content
+            assert isinstance(pre_prompt_content, TextContent)
+            assert (
+                pre_prompt_content.text
+                == "To calculate 5 + 3, you need to add 5 and 3 together."
+            )
+
+            tracking_calculator.add_prompts(fastmcp=caching_server)
+
+            post_prompt = await client.get_prompt(
+                name="how_to_calculate", arguments={"a": 5, "b": 3}
+            )
+
+            assert pre_prompt == post_prompt
+
+    async def test_statistics(
+        self,
+        caching_server: FastMCP,
+    ):
+        """Test that statistics are collected correctly."""
+        caching_middleware = caching_server.middleware[0]
+        assert isinstance(caching_middleware, ResponseCachingMiddleware)
+
+        async with Client[FastMCPTransport](transport=caching_server) as client:
+            statistics = caching_middleware.statistics()
+            assert statistics == snapshot(ResponseCachingStatistics())
+
+            _ = await client.call_tool("add", {"a": 5, "b": 3})
+
+            statistics = caching_middleware.statistics()
+            assert statistics == snapshot(
+                ResponseCachingStatistics(
+                    list_tools=KVStoreCollectionStatistics(
+                        get=GetStatistics(count=1, hit=0, miss=1),
+                        put=PutStatistics(count=1),
+                    ),
+                    call_tool=KVStoreCollectionStatistics(
+                        get=GetStatistics(count=1, miss=1), put=PutStatistics(count=1)
+                    ),
+                )
+            )
+
+            _ = await client.call_tool("add", {"a": 5, "b": 3})
+
+            statistics = caching_middleware.statistics()
+            assert statistics == snapshot(
+                ResponseCachingStatistics(
+                    list_tools=KVStoreCollectionStatistics(
+                        get=GetStatistics(count=1, hit=0, miss=1),
+                        put=PutStatistics(count=1),
+                    ),
+                    call_tool=KVStoreCollectionStatistics(
+                        get=GetStatistics(count=2, hit=1, miss=1),
+                        put=PutStatistics(count=1),
+                    ),
+                )
+            )
+
+
+class TestCachableToolResult:
+    def test_wrap_and_unwrap(self):
+        tool_result = ToolResult(
+            "unstructured content",
+            structured_content={"structured": "content"},
+            meta={"meta": "data"},
+        )
+
+        cached_tool_result = CachableToolResult.wrap(tool_result).unwrap()
+
+        assert cached_tool_result.content == tool_result.content
+        assert cached_tool_result.structured_content == tool_result.structured_content
+        assert cached_tool_result.meta == tool_result.meta
+
+    def test_wrap_and_unwrap_preserves_is_error(self):
+        tool_result = ToolResult("boom", is_error=True)
+
+        cached_tool_result = CachableToolResult.wrap(tool_result).unwrap()
+
+        assert cached_tool_result.is_error is True
+
+
+class TestCachingWithImportedServerPrefixes:
+    """Test that caching preserves prefixes from imported servers.
+
+    Regression tests for issue #2300: ResponseCachingMiddleware was losing
+    prefix information when caching components from imported servers.
+    """
+
+    @pytest.fixture
+    async def parent_with_imported_child(self, tracking_calculator: TrackingCalculator):
+        """Create a parent server with an imported child server (prefixed)."""
+        child = FastMCP("child")
+        tracking_calculator.add_tools(fastmcp=child)
+        tracking_calculator.add_resources(fastmcp=child)
+        tracking_calculator.add_prompts(fastmcp=child)
+
+        parent = FastMCP("parent")
+        parent.add_middleware(ResponseCachingMiddleware())
+        parent.mount(child, namespace="child")
+
+        return parent
+
+    async def test_tool_prefixes_preserved_after_cache_hit(
+        self, parent_with_imported_child: FastMCP
+    ):
+        """Tool names should retain prefix after being served from cache."""
+        async with Client(parent_with_imported_child) as client:
+            # First call populates cache
+            tools_first = await client.list_tools()
+            tool_names_first = [t.name for t in tools_first]
+
+            # Second call should come from cache
+            tools_cached = await client.list_tools()
+            tool_names_cached = [t.name for t in tools_cached]
+
+            # All tools should have prefix in both calls
+            assert all(name.startswith("child_") for name in tool_names_first)
+            assert all(name.startswith("child_") for name in tool_names_cached)
+            assert tool_names_first == tool_names_cached
+
+    async def test_resource_prefixes_preserved_after_cache_hit(
+        self, parent_with_imported_child: FastMCP
+    ):
+        """Resource URIs should retain prefix after being served from cache."""
+        async with Client(parent_with_imported_child) as client:
+            # First call populates cache
+            resources_first = await client.list_resources()
+            resource_uris_first = [str(r.uri) for r in resources_first]
+
+            # Second call should come from cache
+            resources_cached = await client.list_resources()
+            resource_uris_cached = [str(r.uri) for r in resources_cached]
+
+            # All resources should have prefix in URI path in both calls
+            # Resources get path-style prefix: resource://child/path
+            assert all("://child/" in uri for uri in resource_uris_first)
+            assert all("://child/" in uri for uri in resource_uris_cached)
+            assert resource_uris_first == resource_uris_cached
+
+    async def test_prompt_prefixes_preserved_after_cache_hit(
+        self, parent_with_imported_child: FastMCP
+    ):
+        """Prompt names should retain prefix after being served from cache."""
+        async with Client(parent_with_imported_child) as client:
+            # First call populates cache
+            prompts_first = await client.list_prompts()
+            prompt_names_first = [p.name for p in prompts_first]
+
+            # Second call should come from cache
+            prompts_cached = await client.list_prompts()
+            prompt_names_cached = [p.name for p in prompts_cached]
+
+            # All prompts should have prefix in both calls
+            assert all(name.startswith("child_") for name in prompt_names_first)
+            assert all(name.startswith("child_") for name in prompt_names_cached)
+            assert prompt_names_first == prompt_names_cached
+
+    async def test_prefixed_tool_callable_after_cache_hit(
+        self,
+        parent_with_imported_child: FastMCP,
+        tracking_calculator: TrackingCalculator,
+    ):
+        """Prefixed tools should be callable after cache populates."""
+        async with Client(parent_with_imported_child) as client:
+            # Trigger cache population
+            await client.list_tools()
+            await client.list_tools()  # From cache
+
+            # Tool should be callable with prefixed name
+            result = await client.call_tool("child_add", {"a": 5, "b": 3})
+            assert not result.is_error
+            assert tracking_calculator.add_calls == 1
+
+
+class TestCacheKeyGeneration:
+    def test_call_tool_key_is_hashed_and_does_not_include_raw_input(self):
+        msg = mcp_types.CallToolRequestParams(
+            name="toolX",
+            arguments={"password": "secret", "path": "../../etc/passwd"},
+        )
+
+        key = _make_call_tool_cache_key(msg)
+
+        assert len(key) == 64
+        assert "secret" not in key
+        assert "../../etc/passwd" not in key
+
+    def test_read_resource_key_is_hashed_and_does_not_include_raw_uri(self):
+        msg = mcp_types.ReadResourceRequestParams(
+            uri="file:///tmp/../../etc/shadow?token=abcd"
+        )
+
+        key = _make_read_resource_cache_key(msg)
+
+        assert len(key) == 64
+        assert "shadow" not in key
+        assert "token=abcd" not in key
+
+    def test_get_prompt_key_is_hashed_and_stable(self):
+        msg = mcp_types.GetPromptRequestParams(
+            name="promptY",
+            arguments={"api_key": "ABC123", "scope": "admin"},
+        )
+
+        key = _make_get_prompt_cache_key(msg)
+
+        assert len(key) == 64
+        assert "ABC123" not in key
+        assert key == _make_get_prompt_cache_key(msg)
+
+    def test_call_tool_key_partitions_by_auth(self):
+        msg = mcp_types.CallToolRequestParams(name="t", arguments={"a": 1})
+
+        anon = _make_call_tool_cache_key(msg)
+        user_a = _make_call_tool_cache_key(msg, auth_key="user_a")
+        user_b = _make_call_tool_cache_key(msg, auth_key="user_b")
+
+        assert anon == _make_call_tool_cache_key(msg, auth_key=ANONYMOUS_AUTH_KEY)
+        assert user_a != user_b
+        assert user_a != anon
+
+    def test_read_resource_key_partitions_by_auth(self):
+        msg = mcp_types.ReadResourceRequestParams(uri="file:///tmp/x")
+
+        user_a = _make_read_resource_cache_key(msg, auth_key="user_a")
+        user_b = _make_read_resource_cache_key(msg, auth_key="user_b")
+
+        assert user_a != user_b
+
+    def test_get_prompt_key_partitions_by_auth(self):
+        msg = mcp_types.GetPromptRequestParams(name="p", arguments={"a": "1"})
+
+        user_a = _make_get_prompt_cache_key(msg, auth_key="user_a")
+        user_b = _make_get_prompt_cache_key(msg, auth_key="user_b")
+
+        assert user_a != user_b
+
+
+class TestAuthAwareCaching:
+    """Cached responses must not leak across users with different auth tokens.
+
+    Regression tests for issue #4037: ResponseCachingMiddleware was caching
+    list/call responses with a global key, so a list filtered by per-component
+    auth checks for one user was served back to other users.
+    """
+
+    @staticmethod
+    def _make_token(scopes: list[str]):
+        from fastmcp.server.auth import AccessToken
+
+        return AccessToken(
+            token=f"token-{'-'.join(scopes) or 'none'}",
+            client_id="test-client",
+            scopes=scopes,
+            expires_at=None,
+            claims={},
+        )
+
+    @staticmethod
+    def _set_token(token):
+        from mcp.server.auth.middleware.auth_context import auth_context_var
+        from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser
+
+        if token is None:
+            return auth_context_var.set(None)
+        return auth_context_var.set(AuthenticatedUser(token))
+
+    async def test_list_tools_cache_does_not_leak_across_tokens(self):
+        from fastmcp.server.auth import require_scopes
+
+        mcp_server = FastMCP("test")
+        mcp_server.add_middleware(ResponseCachingMiddleware())
+
+        @mcp_server.tool(auth=require_scopes("read"))
+        def reader() -> str:
+            return "ok"
+
+        @mcp_server.tool(auth=require_scopes("read", "write"))
+        def writer() -> str:
+            return "ok"
+
+        from mcp.server.auth.middleware.auth_context import auth_context_var
+
+        # Privileged user lists tools first - both visible, gets cached.
+        privileged = self._make_token(["read", "write"])
+        tok = self._set_token(privileged)
+        try:
+            tools = await mcp_server.list_tools()
+            names = {t.name for t in tools}
+            assert names == {"reader", "writer"}
+        finally:
+            auth_context_var.reset(tok)
+
+        # Lower-privileged user must not see the cached privileged list.
+        limited = self._make_token(["read"])
+        tok = self._set_token(limited)
+        try:
+            tools = await mcp_server.list_tools()
+            names = {t.name for t in tools}
+            assert names == {"reader"}
+        finally:
+            auth_context_var.reset(tok)
+
+        # And same-token repeats still hit the cache (sanity check).
+        tok = self._set_token(limited)
+        try:
+            tools = await mcp_server.list_tools()
+            assert {t.name for t in tools} == {"reader"}
+        finally:
+            auth_context_var.reset(tok)
+
+    async def test_list_resources_cache_does_not_leak_across_tokens(self):
+        from fastmcp.server.auth import require_scopes
+
+        mcp_server = FastMCP("test")
+        mcp_server.add_middleware(ResponseCachingMiddleware())
+
+        @mcp_server.resource("data://public", auth=require_scopes("read"))
+        def public() -> str:
+            return "public"
+
+        @mcp_server.resource("data://secret", auth=require_scopes("read", "admin"))
+        def secret() -> str:
+            return "secret"
+
+        from mcp.server.auth.middleware.auth_context import auth_context_var
+
+        privileged = self._make_token(["read", "admin"])
+        tok = self._set_token(privileged)
+        try:
+            resources = await mcp_server.list_resources()
+            uris = {str(r.uri) for r in resources}
+            assert uris == {"data://public", "data://secret"}
+        finally:
+            auth_context_var.reset(tok)
+
+        limited = self._make_token(["read"])
+        tok = self._set_token(limited)
+        try:
+            resources = await mcp_server.list_resources()
+            uris = {str(r.uri) for r in resources}
+            assert uris == {"data://public"}
+        finally:
+            auth_context_var.reset(tok)
+
+    async def test_list_prompts_cache_does_not_leak_across_tokens(self):
+        from fastmcp.server.auth import require_scopes
+
+        mcp_server = FastMCP("test")
+        mcp_server.add_middleware(ResponseCachingMiddleware())
+
+        @mcp_server.prompt(auth=require_scopes("read"))
+        def public_prompt() -> str:
+            return "public"
+
+        @mcp_server.prompt(auth=require_scopes("read", "admin"))
+        def admin_prompt() -> str:
+            return "admin"
+
+        from mcp.server.auth.middleware.auth_context import auth_context_var
+
+        privileged = self._make_token(["read", "admin"])
+        tok = self._set_token(privileged)
+        try:
+            prompts = await mcp_server.list_prompts()
+            assert {p.name for p in prompts} == {"public_prompt", "admin_prompt"}
+        finally:
+            auth_context_var.reset(tok)
+
+        limited = self._make_token(["read"])
+        tok = self._set_token(limited)
+        try:
+            prompts = await mcp_server.list_prompts()
+            assert {p.name for p in prompts} == {"public_prompt"}
+        finally:
+            auth_context_var.reset(tok)
diff --git a/tests/server/middleware/test_dereference.py b/tests/server/middleware/test_dereference.py
new file mode 100644
index 0000000..ce4b369
--- /dev/null
+++ b/tests/server/middleware/test_dereference.py
@@ -0,0 +1,136 @@
+"""Tests for DereferenceRefsMiddleware."""
+
+from enum import Enum
+
+import pydantic
+
+from fastmcp import Client, FastMCP
+
+
+class Color(Enum):
+    RED = "red"
+    GREEN = "green"
+    BLUE = "blue"
+
+
+class PaintRequest(pydantic.BaseModel):
+    color: Color
+    opacity: float = 1.0
+
+
+class TestDereferenceRefsMiddleware:
+    """End-to-end tests for the dereference_schemas server kwarg."""
+
+    async def test_dereference_schemas_true_inlines_refs(self):
+        """With dereference_schemas=True (default), tool schemas have $ref inlined."""
+        mcp = FastMCP("test", dereference_schemas=True)
+
+        @mcp.tool
+        def paint(request: PaintRequest) -> str:
+            return "ok"
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+
+        schema = tools[0].input_schema
+        # $defs should be removed — everything inlined
+        assert "$defs" not in schema
+        # The Color enum should be inlined into the request property
+        assert "$ref" not in str(schema)
+
+    async def test_dereference_schemas_false_preserves_refs(self):
+        """With dereference_schemas=False, $ref and $defs are preserved."""
+        mcp = FastMCP("test", dereference_schemas=False)
+
+        @mcp.tool
+        def paint(request: PaintRequest) -> str:
+            return "ok"
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+
+        schema = tools[0].input_schema
+        # $defs should still be present
+        assert "$defs" in schema
+
+    async def test_default_is_true(self):
+        """Default behavior dereferences $ref."""
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def paint(request: PaintRequest) -> str:
+            return "ok"
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+
+        schema = tools[0].input_schema
+        assert "$defs" not in schema
+
+    async def test_does_not_mutate_original_tool(self):
+        """Middleware should not mutate the shared Tool object."""
+        mcp = FastMCP("test", dereference_schemas=True)
+
+        @mcp.tool
+        def paint(request: PaintRequest) -> str:
+            return "ok"
+
+        # Get the original tool's parameters before middleware runs
+        original_tools = await mcp._local_provider._list_tools()
+        assert "$defs" in original_tools[0].parameters
+
+        # List tools through the client (triggers middleware)
+        async with Client(mcp) as client:
+            await client.list_tools()
+
+        # The original tool stored in the server should still have $defs
+        tools_after = await mcp._local_provider._list_tools()
+        assert "$defs" in tools_after[0].parameters
+
+    async def test_output_schema_dereferenced(self):
+        """Middleware also dereferences output_schema when present."""
+        mcp = FastMCP("test", dereference_schemas=True)
+
+        @mcp.tool
+        def paint(request: PaintRequest) -> PaintRequest:
+            return request
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+
+        tool = tools[0]
+        # Both input and output schemas should be dereferenced
+        assert "$defs" not in tool.input_schema
+        if tool.output_schema is not None:
+            assert "$defs" not in tool.output_schema
+
+    async def test_resource_templates_dereferenced(self):
+        """Middleware dereferences resource template schemas."""
+        mcp = FastMCP("test", dereference_schemas=True)
+
+        @mcp.resource("paint://{color}")
+        def get_paint(color: Color) -> str:
+            return f"paint: {color}"
+
+        async with Client(mcp) as client:
+            templates = await client.list_resource_templates()
+
+        # Resource templates also get their schemas dereferenced
+        # (only if the template parameters have $ref)
+        assert len(templates) == 1
+
+    async def test_no_ref_schemas_unchanged(self):
+        """Tools without $ref should pass through unmodified."""
+        mcp = FastMCP("test", dereference_schemas=True)
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+
+        schema = tools[0].input_schema
+        # Simple schema should not have $defs regardless
+        assert "$defs" not in schema
+        assert schema["properties"]["a"]["type"] == "integer"
diff --git a/tests/server/middleware/test_error_handling.py b/tests/server/middleware/test_error_handling.py
new file mode 100644
index 0000000..773bb7d
--- /dev/null
+++ b/tests/server/middleware/test_error_handling.py
@@ -0,0 +1,656 @@
+"""Tests for error handling middleware."""
+
+import logging
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from mcp import MCPError
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.exceptions import NotFoundError, ToolError
+from fastmcp.server.middleware.error_handling import (
+    ErrorHandlingMiddleware,
+    RetryMiddleware,
+)
+from fastmcp.server.middleware.middleware import MiddlewareContext
+
+
+@pytest.fixture
+def mock_context():
+    """Create a mock middleware context."""
+    context = MagicMock(spec=MiddlewareContext)
+    context.method = "test_method"
+    return context
+
+
+@pytest.fixture
+def mock_call_next():
+    """Create a mock call_next function."""
+    return AsyncMock(return_value="test_result")
+
+
+class TestErrorHandlingMiddleware:
+    """Test error handling middleware functionality."""
+
+    def test_init_default(self):
+        """Test default initialization."""
+        middleware = ErrorHandlingMiddleware()
+        assert middleware.logger.name == "fastmcp.errors"
+        assert middleware.include_traceback is False
+        assert middleware.error_callback is None
+        assert middleware.transform_errors is True
+        assert middleware.error_counts == {}
+
+    def test_init_custom(self):
+        """Test custom initialization."""
+        logger = logging.getLogger("custom")
+        callback = MagicMock()
+
+        middleware = ErrorHandlingMiddleware(
+            logger=logger,
+            include_traceback=True,
+            error_callback=callback,
+            transform_errors=False,
+        )
+        assert middleware.logger is logger
+        assert middleware.include_traceback is True
+        assert middleware.error_callback is callback
+        assert middleware.transform_errors is False
+
+    def test_log_error_basic(self, mock_context, caplog):
+        """Test basic error logging."""
+        middleware = ErrorHandlingMiddleware()
+        error = ValueError("test error")
+
+        with caplog.at_level(logging.ERROR):
+            middleware._log_error(error, mock_context)
+
+        assert "Error in test_method: ValueError: test error" in caplog.text
+        assert "ValueError:test_method" in middleware.error_counts
+        assert middleware.error_counts["ValueError:test_method"] == 1
+
+    def test_log_error_with_traceback(self, mock_context, caplog):
+        """Test error logging with traceback."""
+        middleware = ErrorHandlingMiddleware(include_traceback=True)
+        error = ValueError("test error")
+
+        with caplog.at_level(logging.ERROR):
+            middleware._log_error(error, mock_context)
+
+        assert "Error in test_method: ValueError: test error" in caplog.text
+        # The traceback is added to the log message
+        assert "Error in test_method: ValueError: test error" in caplog.text
+
+    def test_log_error_with_callback(self, mock_context):
+        """Test error logging with callback."""
+        callback = MagicMock()
+        middleware = ErrorHandlingMiddleware(error_callback=callback)
+        error = ValueError("test error")
+
+        middleware._log_error(error, mock_context)
+
+        callback.assert_called_once_with(error, mock_context)
+
+    def test_log_error_callback_exception(self, mock_context, caplog):
+        """Test error logging when callback raises exception."""
+        callback = MagicMock(side_effect=RuntimeError("callback error"))
+        middleware = ErrorHandlingMiddleware(error_callback=callback)
+        error = ValueError("test error")
+
+        with caplog.at_level(logging.ERROR):
+            middleware._log_error(error, mock_context)
+
+        assert "Error in error callback: callback error" in caplog.text
+
+    def test_transform_error_mcp_error(self, mock_context):
+        """Test that MCP errors are not transformed."""
+        middleware = ErrorHandlingMiddleware()
+
+        error = MCPError(code=-32001, message="test error")
+
+        result = middleware._transform_error(error, mock_context)
+
+        assert result is error
+
+    def test_transform_error_disabled(self, mock_context):
+        """Test error transformation when disabled."""
+        middleware = ErrorHandlingMiddleware(transform_errors=False)
+        error = ValueError("test error")
+
+        result = middleware._transform_error(error, mock_context)
+
+        assert result is error
+
+    def test_transform_error_value_error(self, mock_context):
+        """Test transforming ValueError."""
+        middleware = ErrorHandlingMiddleware()
+        error = ValueError("test error")
+
+        result = middleware._transform_error(error, mock_context)
+
+        assert isinstance(result, MCPError)
+        assert result.error.code == -32602
+        assert "Invalid params: test error" in result.error.message
+
+    def test_transform_error_not_found_for_resource_method(self):
+        """Test that not-found errors use -32002 for resource methods."""
+        middleware = ErrorHandlingMiddleware()
+        resource_context = MagicMock(spec=MiddlewareContext)
+        resource_context.method = "resources/read"
+
+        for error in [
+            FileNotFoundError("test error"),
+            NotFoundError("test error"),
+        ]:
+            result = middleware._transform_error(error, resource_context)
+
+            assert isinstance(result, MCPError)
+            assert result.error.code == -32002
+            assert "Resource not found: test error" in result.error.message
+
+    def test_transform_error_not_found_for_non_resource_method(self, mock_context):
+        """Test that not-found errors use -32001 for non-resource methods."""
+        middleware = ErrorHandlingMiddleware()
+
+        for error in [
+            FileNotFoundError("test error"),
+            NotFoundError("test error"),
+        ]:
+            result = middleware._transform_error(error, mock_context)
+
+            assert isinstance(result, MCPError)
+            assert result.error.code == -32001
+            assert "Not found: test error" in result.error.message
+
+    def test_transform_error_permission_error(self, mock_context):
+        """Test transforming PermissionError."""
+        middleware = ErrorHandlingMiddleware()
+        error = PermissionError("test error")
+
+        result = middleware._transform_error(error, mock_context)
+
+        assert isinstance(result, MCPError)
+        assert result.error.code == -32000
+        assert "Permission denied: test error" in result.error.message
+
+    def test_transform_error_timeout_error(self, mock_context):
+        """Test transforming TimeoutError."""
+        middleware = ErrorHandlingMiddleware()
+        error = TimeoutError("test error")
+
+        result = middleware._transform_error(error, mock_context)
+
+        assert isinstance(result, MCPError)
+        assert result.error.code == -32000
+        assert "Request timeout: test error" in result.error.message
+
+    def test_transform_error_generic(self, mock_context):
+        """Test transforming generic error."""
+        middleware = ErrorHandlingMiddleware()
+        error = RuntimeError("test error")
+
+        result = middleware._transform_error(error, mock_context)
+
+        assert isinstance(result, MCPError)
+        assert result.error.code == -32603
+        assert "Internal error: test error" in result.error.message
+
+    async def test_on_message_success(self, mock_context, mock_call_next):
+        """Test successful message handling."""
+        middleware = ErrorHandlingMiddleware()
+
+        result = await middleware.on_message(mock_context, mock_call_next)
+
+        assert result == "test_result"
+        assert mock_call_next.called
+
+    async def test_on_message_error_transform(self, mock_context, caplog):
+        """Test error handling with transformation."""
+        middleware = ErrorHandlingMiddleware()
+        mock_call_next = AsyncMock(side_effect=ValueError("test error"))
+
+        with caplog.at_level(logging.ERROR):
+            with pytest.raises(MCPError) as exc_info:
+                await middleware.on_message(mock_context, mock_call_next)
+
+        assert isinstance(exc_info.value, MCPError)
+        assert exc_info.value.error.code == -32602
+        assert "Invalid params: test error" in exc_info.value.error.message
+        assert "Error in test_method: ValueError: test error" in caplog.text
+
+    async def test_on_message_error_transform_tool_error(self, mock_context, caplog):
+        """Test error handling with transformation and cause type."""
+        middleware = ErrorHandlingMiddleware()
+        tool_error = ToolError("test error")
+        tool_error.__cause__ = ValueError()
+        mock_call_next = AsyncMock(side_effect=tool_error)
+
+        with caplog.at_level(logging.ERROR):
+            with pytest.raises(MCPError) as exc_info:
+                await middleware.on_message(mock_context, mock_call_next)
+
+        assert isinstance(exc_info.value, MCPError)
+        assert exc_info.value.error.code == -32602
+        assert "Invalid params: test error" in exc_info.value.error.message
+        assert "Error in test_method: ToolError: test error" in caplog.text
+
+    def test_get_error_stats(self, mock_context):
+        """Test getting error statistics."""
+        middleware = ErrorHandlingMiddleware()
+        error1 = ValueError("error1")
+        error2 = ValueError("error2")
+        error3 = RuntimeError("error3")
+
+        middleware._log_error(error1, mock_context)
+        middleware._log_error(error2, mock_context)
+        middleware._log_error(error3, mock_context)
+
+        stats = middleware.get_error_stats()
+        assert stats["ValueError:test_method"] == 2
+        assert stats["RuntimeError:test_method"] == 1
+
+
+class TestRetryMiddleware:
+    """Test retry middleware functionality."""
+
+    def test_init_default(self):
+        """Test default initialization."""
+        middleware = RetryMiddleware()
+        assert middleware.max_retries == 3
+        assert middleware.base_delay == 1.0
+        assert middleware.max_delay == 60.0
+        assert middleware.backoff_multiplier == 2.0
+        assert middleware.retry_exceptions == (ConnectionError, TimeoutError)
+        assert middleware.logger.name == "fastmcp.retry"
+
+    def test_init_custom(self):
+        """Test custom initialization."""
+        logger = logging.getLogger("custom")
+        middleware = RetryMiddleware(
+            max_retries=5,
+            base_delay=2.0,
+            max_delay=120.0,
+            backoff_multiplier=3.0,
+            retry_exceptions=(ValueError, RuntimeError),
+            logger=logger,
+        )
+        assert middleware.max_retries == 5
+        assert middleware.base_delay == 2.0
+        assert middleware.max_delay == 120.0
+        assert middleware.backoff_multiplier == 3.0
+        assert middleware.retry_exceptions == (ValueError, RuntimeError)
+        assert middleware.logger is logger
+
+    def test_should_retry_true(self):
+        """Test retry decision for retryable errors."""
+        middleware = RetryMiddleware()
+
+        assert middleware._should_retry(ConnectionError()) is True
+        assert middleware._should_retry(TimeoutError()) is True
+
+    def test_should_retry_false(self):
+        """Test retry decision for non-retryable errors."""
+        middleware = RetryMiddleware()
+
+        assert middleware._should_retry(ValueError()) is False
+        assert middleware._should_retry(RuntimeError()) is False
+
+    def test_should_retry_checks_cause_chain(self):
+        """Retry should match on __cause__ since FastMCP wraps tool errors.
+
+        When a tool raises ConnectionError, FastMCP catches it and raises
+        ToolError(...) from ConnectionError.  The middleware must check
+        __cause__ to detect the retryable original exception.
+        """
+        middleware = RetryMiddleware(retry_exceptions=(ConnectionError,))
+
+        # Direct ConnectionError — should retry
+        assert middleware._should_retry(ConnectionError()) is True
+
+        # ToolError wrapping ConnectionError — should also retry
+        wrapped = ToolError("Error calling tool")
+        wrapped.__cause__ = ConnectionError("conn refused")
+        assert middleware._should_retry(wrapped) is True
+
+        # ToolError wrapping ValueError — should NOT retry
+        wrong_cause = ToolError("Error calling tool")
+        wrong_cause.__cause__ = ValueError("bad input")
+        assert middleware._should_retry(wrong_cause) is False
+
+        # ToolError with no cause — should NOT retry
+        no_cause = ToolError("Error calling tool")
+        assert middleware._should_retry(no_cause) is False
+
+    def test_calculate_delay(self):
+        """Test delay calculation."""
+        middleware = RetryMiddleware(
+            base_delay=1.0, backoff_multiplier=2.0, max_delay=10.0
+        )
+
+        assert middleware._calculate_delay(0) == 1.0
+        assert middleware._calculate_delay(1) == 2.0
+        assert middleware._calculate_delay(2) == 4.0
+        assert middleware._calculate_delay(3) == 8.0
+        assert middleware._calculate_delay(4) == 10.0  # capped at max_delay
+
+    async def test_on_request_success_first_try(self, mock_context, mock_call_next):
+        """Test successful request on first try."""
+        middleware = RetryMiddleware()
+
+        result = await middleware.on_request(mock_context, mock_call_next)
+
+        assert result == "test_result"
+        assert mock_call_next.call_count == 1
+
+    async def test_on_request_success_after_retries(self, mock_context, caplog):
+        """Test successful request after retries."""
+        middleware = RetryMiddleware(base_delay=0.01)  # Fast retry for testing
+
+        # Fail first two attempts, succeed on third
+        mock_call_next = AsyncMock(
+            side_effect=[
+                ConnectionError("connection failed"),
+                ConnectionError("connection failed"),
+                "test_result",
+            ]
+        )
+
+        with caplog.at_level(logging.WARNING):
+            result = await middleware.on_request(mock_context, mock_call_next)
+
+        assert result == "test_result"
+        assert mock_call_next.call_count == 3
+        assert "Retrying in" in caplog.text
+
+    async def test_on_request_max_retries_exceeded(self, mock_context, caplog):
+        """Test request failing after max retries."""
+        middleware = RetryMiddleware(max_retries=2, base_delay=0.01)
+
+        # Fail all attempts
+        mock_call_next = AsyncMock(side_effect=ConnectionError("connection failed"))
+
+        with caplog.at_level(logging.WARNING):
+            with pytest.raises(ConnectionError):
+                await middleware.on_request(mock_context, mock_call_next)
+
+        assert mock_call_next.call_count == 3  # initial + 2 retries
+        assert "Retrying in" in caplog.text
+
+    async def test_on_request_non_retryable_error(self, mock_context):
+        """Test non-retryable error is not retried."""
+        middleware = RetryMiddleware()
+        mock_call_next = AsyncMock(side_effect=ValueError("non-retryable"))
+
+        with pytest.raises(ValueError):
+            await middleware.on_request(mock_context, mock_call_next)
+
+        assert mock_call_next.call_count == 1  # No retries
+
+
+@pytest.fixture
+def error_handling_server():
+    """Create a FastMCP server specifically for error handling middleware tests."""
+    mcp = FastMCP("ErrorHandlingTestServer")
+
+    @mcp.tool
+    def reliable_operation(data: str) -> str:
+        """A reliable operation that always succeeds."""
+        return f"Success: {data}"
+
+    @mcp.tool
+    def failing_operation(error_type: str = "value") -> str:
+        """An operation that fails with different error types."""
+        if error_type == "value":
+            raise ValueError("Value error occurred")
+        elif error_type == "file":
+            raise FileNotFoundError("File not found")
+        elif error_type == "permission":
+            raise PermissionError("Permission denied")
+        elif error_type == "timeout":
+            raise TimeoutError("Operation timed out")
+        elif error_type == "generic":
+            raise RuntimeError("Generic runtime error")
+        else:
+            return "Operation completed"
+
+    @mcp.tool
+    def intermittent_operation(fail_rate: float = 0.5) -> str:
+        """An operation that fails intermittently."""
+        import random
+
+        if random.random() < fail_rate:
+            raise ConnectionError("Random connection failure")
+        return "Operation succeeded"
+
+    @mcp.tool
+    def retryable_operation(attempt_count: int = 0) -> str:
+        """An operation that succeeds after a few attempts."""
+        # This is a simple way to simulate retry behavior
+        # In a real scenario, you might use external state
+        if attempt_count < 2:
+            raise ConnectionError("Temporary connection error")
+        return "Operation succeeded after retries"
+
+    return mcp
+
+
+class TestErrorHandlingMiddlewareIntegration:
+    """Integration tests for error handling middleware with real FastMCP server."""
+
+    async def test_error_handling_middleware_logs_real_errors(
+        self, error_handling_server, caplog
+    ):
+        """Test that error handling middleware logs real errors from tools."""
+        error_handling_server.add_middleware(ErrorHandlingMiddleware())
+
+        with caplog.at_level(logging.ERROR):
+            async with Client(error_handling_server) as client:
+                # Test different types of errors
+                with pytest.raises(Exception):
+                    await client.call_tool("failing_operation", {"error_type": "value"})
+
+                with pytest.raises(Exception):
+                    await client.call_tool("failing_operation", {"error_type": "file"})
+
+        log_text = caplog.text
+
+        # Should have error logs for both failures
+        assert "Error in tools/call: ToolError:" in log_text
+        # Should have captured both error instances
+        error_count = log_text.count("Error in tools/call:")
+        assert error_count == 2
+
+    async def test_error_handling_middleware_tracks_error_statistics(
+        self, error_handling_server
+    ):
+        """Test that error handling middleware accurately tracks error statistics."""
+        error_middleware = ErrorHandlingMiddleware()
+        error_handling_server.add_middleware(error_middleware)
+
+        async with Client(error_handling_server) as client:
+            # Generate different types of errors
+            for _ in range(3):
+                with pytest.raises(Exception):
+                    await client.call_tool("failing_operation", {"error_type": "value"})
+
+            for _ in range(2):
+                with pytest.raises(Exception):
+                    await client.call_tool("failing_operation", {"error_type": "file"})
+
+        # Try some intermittent operations (some may succeed)
+        for _ in range(5):
+            try:
+                await client.call_tool("intermittent_operation", {"fail_rate": 0.8})
+            except Exception:
+                pass  # Expected failures
+
+        # Check error statistics
+        stats = error_middleware.get_error_stats()
+
+        # Should have tracked the ToolError wrapper
+        assert "ToolError:tools/call" in stats
+        assert stats["ToolError:tools/call"] >= 5  # At least the 5 deliberate failures
+
+    async def test_error_handling_middleware_with_success_and_failure(
+        self, error_handling_server, caplog
+    ):
+        """Test error handling middleware with mix of successful and failed operations."""
+        error_handling_server.add_middleware(ErrorHandlingMiddleware())
+
+        with caplog.at_level(logging.ERROR):
+            async with Client(error_handling_server) as client:
+                # Successful operation (should not generate error logs)
+                await client.call_tool("reliable_operation", {"data": "test"})
+
+                # Failed operation (should generate error log)
+                with pytest.raises(Exception):
+                    await client.call_tool("failing_operation", {"error_type": "value"})
+
+                # Another successful operation
+                await client.call_tool("reliable_operation", {"data": "test2"})
+
+        log_text = caplog.text
+
+        # Should only have one error log (for the failed operation)
+        error_count = log_text.count("Error in tools/call:")
+        assert error_count == 1
+
+    async def test_error_handling_middleware_custom_callback(
+        self, error_handling_server
+    ):
+        """Test error handling middleware with custom error callback."""
+        captured_errors = []
+
+        def error_callback(error, context):
+            captured_errors.append(
+                {
+                    "error_type": type(error).__name__,
+                    "message": str(error),
+                    "method": context.method,
+                }
+            )
+
+        error_handling_server.add_middleware(
+            ErrorHandlingMiddleware(error_callback=error_callback)
+        )
+
+        async with Client(error_handling_server) as client:
+            # Generate some errors
+            with pytest.raises(Exception):
+                await client.call_tool("failing_operation", {"error_type": "value"})
+
+            with pytest.raises(Exception):
+                await client.call_tool("failing_operation", {"error_type": "timeout"})
+
+        # Check that callback was called
+        assert len(captured_errors) == 2
+        assert captured_errors[0]["error_type"] == "ToolError"
+        assert captured_errors[1]["error_type"] == "ToolError"
+        assert all(error["method"] == "tools/call" for error in captured_errors)
+
+    async def test_error_handling_middleware_transform_errors(
+        self, error_handling_server
+    ):
+        """Test error transformation functionality."""
+        error_handling_server.add_middleware(
+            ErrorHandlingMiddleware(transform_errors=True)
+        )
+
+        async with Client(error_handling_server) as client:
+            # All errors should still be raised, but potentially transformed
+            with pytest.raises(Exception) as exc_info:
+                await client.call_tool("failing_operation", {"error_type": "value"})
+
+        # Error should still exist (may be wrapped by FastMCP)
+        assert exc_info.value is not None
+
+
+class TestRetryMiddlewareIntegration:
+    """Integration tests for retry middleware with real FastMCP server."""
+
+    async def test_retry_actually_retries_through_server_pipeline(self):
+        """Retry middleware should retry tool calls that raise retryable errors.
+
+        FastMCP wraps tool exceptions as ToolError(...) from <original>,
+        so the middleware must check __cause__ to detect retryable errors.
+        This test verifies the full pipeline works by counting call attempts.
+        """
+        call_count = 0
+        server = FastMCP("RetryTest")
+        server.add_middleware(
+            RetryMiddleware(
+                max_retries=3,
+                base_delay=0.01,
+                retry_exceptions=(ConnectionError,),
+            )
+        )
+
+        @server.tool
+        def fails_then_succeeds() -> str:
+            nonlocal call_count
+            call_count += 1
+            if call_count < 3:
+                raise ConnectionError("transient failure")
+            return "success"
+
+        async with Client(server) as client:
+            result = await client.call_tool("fails_then_succeeds")
+            assert result.data == "success"
+
+        # Tool should have been called 3 times: 2 failures + 1 success
+        assert call_count == 3
+
+    async def test_retry_middleware_with_permanent_failures(self):
+        """A tool error whose cause is not in ``retry_exceptions`` should
+        fail on the first attempt — no retries."""
+        call_count = 0
+        server = FastMCP("RetryPermanentFailuresTest")
+        server.add_middleware(
+            RetryMiddleware(
+                max_retries=3, base_delay=0.01, retry_exceptions=(ConnectionError,)
+            )
+        )
+
+        @server.tool
+        def always_fails() -> str:
+            nonlocal call_count
+            call_count += 1
+            raise ValueError("permanent failure")
+
+        async with Client(server) as client:
+            with pytest.raises(Exception):
+                await client.call_tool("always_fails", {})
+
+        assert call_count == 1
+
+        # Should fail immediately without retries
+
+    async def test_combined_error_handling_and_retry_middleware(
+        self, error_handling_server, caplog
+    ):
+        """Test error handling and retry middleware working together."""
+        # Add both middleware
+        error_handling_server.add_middleware(ErrorHandlingMiddleware())
+        error_handling_server.add_middleware(
+            RetryMiddleware(
+                max_retries=2, base_delay=0.01, retry_exceptions=(ConnectionError,)
+            )
+        )
+
+        with caplog.at_level(logging.ERROR):
+            async with Client(error_handling_server) as client:
+                # Try intermittent operation
+                try:
+                    await client.call_tool("intermittent_operation", {"fail_rate": 0.9})
+                except Exception:
+                    pass  # May still fail even with retries
+
+                # Try permanent failure
+                with pytest.raises(Exception):
+                    await client.call_tool("failing_operation", {"error_type": "value"})
+
+        log_text = caplog.text
+
+        # Should have error logs from error handling middleware
+        assert "Error in tools/call:" in log_text
diff --git a/tests/server/middleware/test_initialization_middleware.py b/tests/server/middleware/test_initialization_middleware.py
new file mode 100644
index 0000000..3a077b3
--- /dev/null
+++ b/tests/server/middleware/test_initialization_middleware.py
@@ -0,0 +1,428 @@
+"""Tests for middleware support during initialization."""
+
+from collections.abc import Sequence
+from typing import Any
+
+import mcp_types as mt
+import pytest
+from mcp import MCPError
+from mcp_types import TextContent
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.tools.base import Tool
+
+
+class InitializationMiddleware(Middleware):
+    """Middleware that captures initialization details.
+
+    Note: Session state is NOT available during on_initialize because
+    the MCP session has not been established yet. Use instance variables
+    to store data that needs to persist across the session.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.initialized = False
+        self.client_info = None
+        self.session_data = {}
+
+    async def on_initialize(
+        self,
+        context: MiddlewareContext[mt.InitializeRequest],
+        call_next: CallNext[mt.InitializeRequest, mt.InitializeResult | None],
+    ) -> mt.InitializeResult | None:
+        """Capture initialization details."""
+        self.initialized = True
+
+        # Extract client info from the initialize params
+        if hasattr(context.message, "params") and hasattr(
+            context.message.params, "clientInfo"
+        ):
+            self.client_info = context.message.params.client_info
+
+        # Store in instance for cross-request access
+        # (session state is not available during on_initialize)
+        self.session_data["client_initialized"] = True
+        if self.client_info:
+            self.session_data["client_name"] = getattr(
+                self.client_info, "name", "unknown"
+            )
+
+        return await call_next(context)
+
+
+class ClientDetectionMiddleware(Middleware):
+    """Middleware that detects specific clients and modifies behavior.
+
+    This demonstrates storing data in the middleware instance itself
+    for cross-request access, since context state is request-scoped.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.is_test_client = False
+        self.tools_modified = False
+        self.initialization_called = False
+
+    async def on_initialize(
+        self,
+        context: MiddlewareContext[mt.InitializeRequest],
+        call_next: CallNext[mt.InitializeRequest, mt.InitializeResult | None],
+    ) -> mt.InitializeResult | None:
+        """Detect test client during initialization."""
+        self.initialization_called = True
+
+        # For testing purposes, always set it to true
+        # Store in instance variable for cross-request access
+        self.is_test_client = True
+
+        return await call_next(context)
+
+    async def on_list_tools(
+        self,
+        context: MiddlewareContext[mt.ListToolsRequest],
+        call_next: CallNext[mt.ListToolsRequest, Sequence[Tool]],
+    ) -> Sequence[Tool]:
+        """Modify tools based on client detection."""
+        tools = await call_next(context)
+
+        # Use the instance variable set during initialization
+        if self.is_test_client:
+            # Add a special annotation to tools for test clients
+            for tool in tools:
+                if not hasattr(tool, "annotations"):
+                    tool.annotations = mt.ToolAnnotations()
+                if tool.annotations is None:
+                    tool.annotations = mt.ToolAnnotations()
+                # Mark as read-only for test clients
+                tool.annotations.read_only_hint = True
+            self.tools_modified = True
+
+        return tools
+
+
+async def test_simple_initialization_hook():
+    """Test that the on_initialize hook is called."""
+    server = FastMCP("TestServer")
+
+    class SimpleInitMiddleware(Middleware):
+        def __init__(self):
+            super().__init__()
+            self.called = False
+
+        async def on_initialize(
+            self,
+            context: MiddlewareContext[mt.InitializeRequest],
+            call_next: CallNext[mt.InitializeRequest, mt.InitializeResult | None],
+        ) -> mt.InitializeResult | None:
+            self.called = True
+            return await call_next(context)
+
+    middleware = SimpleInitMiddleware()
+    server.add_middleware(middleware)
+
+    # Connect client
+    async with Client(server):
+        # Middleware should have been called
+        assert middleware.called is True, "on_initialize was not called"
+
+
+async def test_middleware_receives_initialization():
+    """Test that middleware can intercept initialization requests."""
+    server = FastMCP("TestServer")
+    middleware = InitializationMiddleware()
+    server.add_middleware(middleware)
+
+    @server.tool
+    def test_tool(x: int) -> str:
+        return f"Result: {x}"
+
+    # Connect client
+    async with Client(server) as client:
+        # Middleware should have been called during initialization
+        assert middleware.initialized is True
+
+        # Test that the tool still works
+        result = await client.call_tool("test_tool", {"x": 42})
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "Result: 42"
+
+
+async def test_client_detection_middleware():
+    """Test middleware that detects specific clients and modifies behavior."""
+    server = FastMCP("TestServer")
+    middleware = ClientDetectionMiddleware()
+    server.add_middleware(middleware)
+
+    @server.tool
+    def example_tool() -> str:
+        return "example"
+
+    # Connect with a client
+    async with Client(server) as client:
+        # Middleware should have been called during initialization
+        assert middleware.initialization_called is True
+        assert middleware.is_test_client is True
+
+        # List tools to trigger modification
+        tools = await client.list_tools()
+        assert len(tools) == 1
+        assert middleware.tools_modified is True
+
+        # Check that the tool has the modified annotation
+        tool = tools[0]
+        assert tool.annotations is not None
+        assert tool.annotations.read_only_hint is True
+
+
+async def test_multiple_middleware_initialization():
+    """Test that multiple middleware can handle initialization."""
+    server = FastMCP("TestServer")
+
+    init_mw = InitializationMiddleware()
+    detect_mw = ClientDetectionMiddleware()
+
+    server.add_middleware(init_mw)
+    server.add_middleware(detect_mw)
+
+    @server.tool
+    def test_tool() -> str:
+        return "test"
+
+    async with Client(server) as client:
+        # Both middleware should have processed initialization
+        assert init_mw.initialized is True
+        assert detect_mw.initialization_called is True
+        assert detect_mw.is_test_client is True
+
+        # List tools to check detection worked
+        await client.list_tools()
+        assert detect_mw.tools_modified is True
+
+
+async def test_session_state_persists_across_tool_calls():
+    """Test that session-scoped state persists across multiple tool calls.
+
+    Session state is only available after the session is established,
+    so it can't be set during on_initialize. This test shows state set
+    during one tool call is accessible in subsequent tool calls.
+    """
+    server = FastMCP("TestServer")
+
+    class StateTrackingMiddleware(Middleware):
+        def __init__(self):
+            super().__init__()
+            self.call_count = 0
+            self.state_values = []
+
+        async def on_call_tool(
+            self,
+            context: MiddlewareContext[mt.CallToolRequestParams],
+            call_next: CallNext[mt.CallToolRequestParams, Any],
+        ) -> Any:
+            self.call_count += 1
+
+            if context.fastmcp_context:
+                # Read existing state
+                counter = await context.fastmcp_context.get_state("call_counter")
+                self.state_values.append(counter)
+
+                # Increment and save
+                new_counter = (counter or 0) + 1
+                await context.fastmcp_context.set_state("call_counter", new_counter)
+
+            return await call_next(context)
+
+    middleware = StateTrackingMiddleware()
+    server.add_middleware(middleware)
+
+    @server.tool
+    def test_tool() -> str:
+        return "success"
+
+    async with Client(server) as client:
+        # First call - state should be None initially
+        result = await client.call_tool("test_tool", {})
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "success"
+
+        # Second call - state should show previous value (1)
+        result = await client.call_tool("test_tool", {})
+        assert isinstance(result.content[0], TextContent)
+
+        # Third call - state should show previous value (2)
+        result = await client.call_tool("test_tool", {})
+        assert isinstance(result.content[0], TextContent)
+
+        # Verify state persisted across calls within the session
+        assert middleware.call_count == 3
+        # First call saw None, second saw 1, third saw 2
+        assert middleware.state_values == [None, 1, 2]
+
+
+async def test_middleware_can_access_initialize_result():
+    """Test that middleware can access the InitializeResult from call_next().
+
+    This verifies that the initialize response is returned through the middleware
+    chain, not just sent directly via the responder (fixes #2504).
+    """
+    server = FastMCP("TestServer")
+
+    class ResponseCapturingMiddleware(Middleware):
+        def __init__(self):
+            super().__init__()
+            self.initialize_result: mt.InitializeResult | None = None
+
+        async def on_initialize(
+            self,
+            context: MiddlewareContext[mt.InitializeRequest],
+            call_next: CallNext[mt.InitializeRequest, mt.InitializeResult | None],
+        ) -> mt.InitializeResult | None:
+            # Call next and capture the result
+            result = await call_next(context)
+            self.initialize_result = result
+            return result
+
+    middleware = ResponseCapturingMiddleware()
+    server.add_middleware(middleware)
+
+    async with Client(server):
+        # Middleware should have captured the InitializeResult
+        assert middleware.initialize_result is not None
+        assert isinstance(middleware.initialize_result, mt.InitializeResult)
+
+        # Verify the result contains expected server info
+        assert middleware.initialize_result.server_info.name == "TestServer"
+        assert middleware.initialize_result.protocol_version is not None
+        assert middleware.initialize_result.capabilities is not None
+
+
+async def test_middleware_mcp_error_during_initialization():
+    """Test that MCPError raised in middleware during initialization is sent to client."""
+    server = FastMCP("TestServer")
+
+    class ErrorThrowingMiddleware(Middleware):
+        async def on_initialize(
+            self,
+            context: MiddlewareContext[mt.InitializeRequest],
+            call_next: CallNext[mt.InitializeRequest, mt.InitializeResult | None],
+        ) -> mt.InitializeResult | None:
+            raise MCPError(
+                code=mt.INVALID_PARAMS, message="Invalid initialization parameters"
+            )
+
+    server.add_middleware(ErrorThrowingMiddleware())
+
+    with pytest.raises(MCPError) as exc_info:
+        async with Client(server):
+            pass
+
+    assert exc_info.value.error.message == "Invalid initialization parameters"
+    assert exc_info.value.error.code == mt.INVALID_PARAMS
+
+
+async def test_middleware_mcp_error_before_call_next():
+    """Test MCPError raised before calling next middleware."""
+    server = FastMCP("TestServer")
+
+    class EarlyErrorMiddleware(Middleware):
+        async def on_initialize(
+            self,
+            context: MiddlewareContext[mt.InitializeRequest],
+            call_next: CallNext[mt.InitializeRequest, mt.InitializeResult | None],
+        ) -> mt.InitializeResult | None:
+            raise MCPError(code=mt.INVALID_REQUEST, message="Request validation failed")
+
+    server.add_middleware(EarlyErrorMiddleware())
+
+    with pytest.raises(MCPError) as exc_info:
+        async with Client(server):
+            pass
+
+    assert exc_info.value.error.message == "Request validation failed"
+    assert exc_info.value.error.code == mt.INVALID_REQUEST
+
+
+async def test_middleware_mcp_error_after_call_next():
+    """Test that MCPError raised after call_next doesn't break the connection.
+
+    When an error is raised after call_next, the responder has already completed,
+    so the error is caught but not sent to the responder (checked via _completed flag).
+    """
+    server = FastMCP("TestServer")
+
+    class PostProcessingErrorMiddleware(Middleware):
+        def __init__(self):
+            super().__init__()
+            self.error_raised = False
+
+        async def on_initialize(
+            self,
+            context: MiddlewareContext[mt.InitializeRequest],
+            call_next: CallNext[mt.InitializeRequest, mt.InitializeResult | None],
+        ) -> mt.InitializeResult | None:
+            await call_next(context)
+            self.error_raised = True
+            raise MCPError(code=mt.INTERNAL_ERROR, message="Post-processing failed")
+
+    middleware = PostProcessingErrorMiddleware()
+    server.add_middleware(middleware)
+
+    # Error is logged but not re-raised to prevent duplicate response
+    async with Client(server):
+        pass
+
+    assert middleware.error_raised is True
+
+
+async def test_state_isolation_between_streamable_http_clients():
+    """Test that different HTTP clients have isolated session state.
+
+    Each client should have its own session ID and isolated state.
+    """
+    from fastmcp.client.transports import StreamableHttpTransport
+    from fastmcp.server.context import Context
+    from fastmcp.utilities.tests import run_server_async
+
+    server = FastMCP("TestServer")
+
+    @server.tool
+    async def store_and_read(value: str, ctx: Context) -> dict:
+        """Store a value and return session info."""
+        existing = await ctx.get_state("client_value")
+        await ctx.set_state("client_value", value)
+        return {
+            "existing": existing,
+            "stored": value,
+            "session_id": ctx.session_id,
+        }
+
+    async with run_server_async(server, transport="streamable-http") as url:
+        import json
+
+        # Client 1 stores its value
+        transport1 = StreamableHttpTransport(url=url)
+        async with Client(transport=transport1) as client1:
+            result1 = await client1.call_tool(
+                "store_and_read", {"value": "client1-value"}
+            )
+            data1 = json.loads(result1.content[0].text)
+            assert data1["existing"] is None
+            assert data1["stored"] == "client1-value"
+            session_id_1 = data1["session_id"]
+
+        # Client 2 should have completely isolated state
+        transport2 = StreamableHttpTransport(url=url)
+        async with Client(transport=transport2) as client2:
+            result2 = await client2.call_tool(
+                "store_and_read", {"value": "client2-value"}
+            )
+            data2 = json.loads(result2.content[0].text)
+            # Should NOT see client1's value
+            assert data2["existing"] is None
+            assert data2["stored"] == "client2-value"
+            session_id_2 = data2["session_id"]
+
+        # Session IDs should be different
+        assert session_id_1 != session_id_2
diff --git a/tests/server/middleware/test_logging.py b/tests/server/middleware/test_logging.py
new file mode 100644
index 0000000..cb191dd
--- /dev/null
+++ b/tests/server/middleware/test_logging.py
@@ -0,0 +1,652 @@
+"""Tests for logging middleware."""
+
+import datetime
+import logging
+from collections.abc import Generator
+from typing import Any, Literal, TypeVar
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import mcp_types
+import pytest
+from inline_snapshot import snapshot
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.middleware.logging import (
+    LoggingMiddleware,
+    StructuredLoggingMiddleware,
+)
+from fastmcp.server.middleware.middleware import CallNext, MiddlewareContext
+
+FIXED_DATE = datetime.datetime(2023, 1, 1, tzinfo=datetime.timezone.utc)
+
+T = TypeVar("T")
+
+
+def get_log_lines(
+    caplog: pytest.LogCaptureFixture, module: str | None = None
+) -> list[str]:
+    """Get log lines from a caplog fixture."""
+    return [
+        record.message
+        for record in caplog.records
+        if (module or "logging") in record.name
+    ]
+
+
+def new_mock_context(
+    message: T,
+    method: str | None = None,
+    source: Literal["server", "client"] | None = None,
+    type: Literal["request", "notification"] | None = None,
+) -> MiddlewareContext[T]:
+    """Create a new mock middleware context."""
+    context = MagicMock(spec=MiddlewareContext[T])
+    context.method = method or "test_method"
+    context.source = source or "client"
+    context.type = type or "request"
+    context.message = message
+    context.timestamp = FIXED_DATE
+    return context
+
+
+@pytest.fixture(autouse=True)
+def mock_duration_ms() -> Generator[float, None]:
+    """Mock duration_ms."""
+    patched = patch(
+        "fastmcp.server.middleware.logging._get_duration_ms", return_value=0.02
+    )
+    patched.start()
+    yield  # ty:ignore[invalid-yield]
+    patched.stop()
+
+
+@pytest.fixture
+def mock_context():
+    """Create a mock middleware context."""
+
+    return new_mock_context(
+        message=mcp_types.CallToolRequest(
+            method="tools/call",
+            params=mcp_types.CallToolRequestParams(
+                name="test_method",
+                arguments={"param": "value"},
+            ),
+        )
+    )
+
+
+@pytest.fixture
+def mock_call_next() -> AsyncMock:
+    """Create a mock call_next function."""
+    return AsyncMock(return_value="test_result")
+
+
+class TestStructuredLoggingMiddleware:
+    """Test structured logging middleware functionality."""
+
+    def test_init_default(self):
+        """Test default initialization."""
+        middleware = StructuredLoggingMiddleware()
+
+        assert middleware.logger.name == "fastmcp.middleware.structured_logging"
+        assert middleware.log_level == logging.INFO
+        assert middleware.include_payloads is False
+        assert middleware.include_payload_length is False
+        assert middleware.estimate_payload_tokens is False
+        assert middleware.structured_logging is True
+
+    def test_init_custom(self):
+        """Test custom initialization."""
+        logger = logging.getLogger("custom")
+        middleware = StructuredLoggingMiddleware(
+            logger=logger,
+            log_level=logging.DEBUG,
+            include_payloads=True,
+            include_payload_length=False,
+            estimate_payload_tokens=True,
+        )
+        assert middleware.logger is logger
+        assert middleware.log_level == logging.DEBUG
+        assert middleware.include_payloads is True
+        assert middleware.include_payload_length is False
+        assert middleware.estimate_payload_tokens is True
+
+    class TestHelperMethods:
+        def test_create_before_message(self, mock_context: MiddlewareContext[Any]):
+            """Test message formatting without payloads."""
+            middleware = StructuredLoggingMiddleware()
+
+            message = middleware._create_before_message(mock_context)
+
+            assert message == snapshot(
+                {
+                    "event": "request_start",
+                    "source": "client",
+                    "method": "test_method",
+                }
+            )
+
+        def test_create_message_with_payloads(
+            self, mock_context: MiddlewareContext[Any]
+        ):
+            """Test message formatting with payloads."""
+            middleware = StructuredLoggingMiddleware(include_payloads=True)
+
+            message = middleware._create_before_message(mock_context)
+
+            assert message == snapshot(
+                {
+                    "event": "request_start",
+                    "source": "client",
+                    "method": "test_method",
+                    "payload": '{"method":"tools/call","params":{"_meta":null,"inputResponses":null,"requestState":null,"name":"test_method","arguments":{"param":"value"},"task":null}}',
+                    "payload_type": "CallToolRequest",
+                }
+            )
+
+        def test_calculate_response_size(self, mock_context: MiddlewareContext[Any]):
+            """Test response size calculation."""
+            middleware = StructuredLoggingMiddleware(include_payload_length=True)
+            message = middleware._create_before_message(mock_context)
+
+            assert message == snapshot(
+                {
+                    "event": "request_start",
+                    "source": "client",
+                    "method": "test_method",
+                    "payload_length": 152,
+                }
+            )
+
+        def test_calculate_response_size_with_token_estimation(
+            self, mock_context: MiddlewareContext[Any]
+        ):
+            """Test response size calculation with token estimation."""
+            middleware = StructuredLoggingMiddleware(
+                include_payload_length=True, estimate_payload_tokens=True
+            )
+            message = middleware._create_before_message(mock_context)
+
+            assert message == snapshot(
+                {
+                    "event": "request_start",
+                    "source": "client",
+                    "method": "test_method",
+                    "payload_tokens": 38,
+                    "payload_length": 152,
+                }
+            )
+
+    async def test_on_message_success(
+        self,
+        mock_context: MiddlewareContext[Any],
+        caplog: pytest.LogCaptureFixture,
+    ):
+        """Test logging successful messages."""
+        middleware = StructuredLoggingMiddleware()
+        mock_call_next = AsyncMock(return_value="test_result")
+
+        result = await middleware.on_message(mock_context, mock_call_next)
+
+        assert result == "test_result"
+        assert mock_call_next.called
+
+        assert get_log_lines(caplog) == snapshot(
+            [
+                '{"event": "request_start", "method": "test_method", "source": "client"}',
+                '{"event": "request_success", "method": "test_method", "source": "client", "duration_ms": 0.02}',
+            ]
+        )
+
+    async def test_on_message_failure(
+        self, mock_context: MiddlewareContext[Any], caplog: pytest.LogCaptureFixture
+    ):
+        """Test logging failed messages."""
+        middleware = StructuredLoggingMiddleware()
+        mock_call_next = AsyncMock(side_effect=ValueError("test error"))
+
+        with pytest.raises(ValueError):
+            await middleware.on_message(mock_context, mock_call_next)
+
+        assert get_log_lines(caplog) == snapshot(
+            [
+                '{"event": "request_start", "method": "test_method", "source": "client"}',
+                '{"event": "request_error", "method": "test_method", "source": "client", "duration_ms": 0.02, "error": "test error"}',
+            ]
+        )
+
+
+class TestLoggingMiddleware:
+    """Test structured logging middleware functionality."""
+
+    def test_init_default(self):
+        """Test default initialization."""
+        middleware = LoggingMiddleware()
+        assert middleware.logger.name == "fastmcp.middleware.logging"
+        assert middleware.log_level == logging.INFO
+        assert middleware.include_payloads is False
+        assert middleware.include_payload_length is False
+        assert middleware.estimate_payload_tokens is False
+
+    def test_format_message(self, mock_context: MiddlewareContext[Any]):
+        """Test message formatting."""
+        middleware = LoggingMiddleware()
+        message = middleware._create_before_message(mock_context)
+        formatted = middleware._format_message(message)
+
+        assert formatted == snapshot(
+            "event=request_start method=test_method source=client"
+        )
+
+    def test_create_before_message_long_payload(
+        self, mock_context: MiddlewareContext[Any]
+    ):
+        """Test message formatting with long payload truncation."""
+        middleware = LoggingMiddleware(include_payloads=True, max_payload_length=10)
+
+        message = middleware._create_before_message(mock_context)
+
+        formatted = middleware._format_message(message)
+
+        assert formatted == snapshot(
+            'event=request_start method=test_method source=client payload={"method":... payload_type=CallToolRequest'
+        )
+
+    async def test_on_message_failure(
+        self, mock_context: MiddlewareContext[Any], caplog: pytest.LogCaptureFixture
+    ):
+        """Test structured logging of failed messages."""
+        middleware = StructuredLoggingMiddleware()
+        mock_call_next = AsyncMock(side_effect=ValueError("test error"))
+
+        with pytest.raises(ValueError):
+            await middleware.on_message(mock_context, mock_call_next)
+
+        # Check that we have structured JSON logs
+        assert get_log_lines(caplog) == snapshot(
+            [
+                '{"event": "request_start", "method": "test_method", "source": "client"}',
+                '{"event": "request_error", "method": "test_method", "source": "client", "duration_ms": 0.02, "error": "test error"}',
+            ]
+        )
+
+    async def test_on_message_with_pydantic_types_in_payload(
+        self,
+        mock_call_next: CallNext[Any, Any],
+        caplog: pytest.LogCaptureFixture,
+    ):
+        """Ensure Pydantic AnyUrl in payload serializes correctly when include_payloads=True."""
+
+        mock_context = new_mock_context(
+            message=mcp_types.ReadResourceRequest(
+                method="resources/read",
+                params=mcp_types.ReadResourceRequestParams(
+                    uri="test://example/1",
+                ),
+            )
+        )
+
+        middleware = StructuredLoggingMiddleware(include_payloads=True)
+
+        result = await middleware.on_message(mock_context, mock_call_next)
+
+        assert result == "test_result"
+
+        assert get_log_lines(caplog) == snapshot(
+            [
+                '{"event": "request_start", "method": "test_method", "source": "client", "payload": "{\\"method\\":\\"resources/read\\",\\"params\\":{\\"_meta\\":null,\\"inputResponses\\":null,\\"requestState\\":null,\\"uri\\":\\"test://example/1\\"}}", "payload_type": "ReadResourceRequest"}',
+                '{"event": "request_success", "method": "test_method", "source": "client", "duration_ms": 0.02}',
+            ]
+        )
+
+    async def test_on_message_with_resource_template_in_payload(
+        self,
+        mock_call_next: CallNext[Any, Any],
+        caplog: pytest.LogCaptureFixture,
+    ):
+        """Ensure ResourceTemplate in payload serializes via pydantic conversion without errors."""
+
+        mock_context = new_mock_context(
+            message=ResourceTemplate(
+                name="tmpl",
+                uri_template="tmpl://{id}",
+                parameters={"id": {"type": "string"}},
+            )
+        )
+
+        middleware = StructuredLoggingMiddleware(include_payloads=True)
+
+        result = await middleware.on_message(mock_context, mock_call_next)
+
+        assert result == "test_result"
+
+        assert get_log_lines(caplog) == snapshot(
+            [
+                '{"event": "request_start", "method": "test_method", "source": "client", "payload": "{\\"name\\":\\"tmpl\\",\\"version\\":null,\\"title\\":null,\\"description\\":null,\\"icons\\":null,\\"tags\\":[],\\"meta\\":null,\\"task_config\\":{\\"mode\\":\\"forbidden\\",\\"poll_interval\\":\\"PT5S\\"},\\"uri_template\\":\\"tmpl://{id}\\",\\"mime_type\\":\\"text/plain\\",\\"parameters\\":{\\"id\\":{\\"type\\":\\"string\\"}},\\"annotations\\":null}", "payload_type": "ResourceTemplate"}',
+                '{"event": "request_success", "method": "test_method", "source": "client", "duration_ms": 0.02}',
+            ]
+        )
+
+    async def test_on_message_with_nonserializable_payload_falls_back_to_str(
+        self, mock_call_next: CallNext[Any, Any], caplog: pytest.LogCaptureFixture
+    ):
+        """Ensure non-JSONable objects fall back to string serialization in payload."""
+
+        class NonSerializable:
+            def __str__(self) -> str:
+                return "NON_SERIALIZABLE"
+
+        mock_context = new_mock_context(
+            message=mcp_types.CallToolRequest(
+                method="tools/call",
+                params=mcp_types.CallToolRequestParams(
+                    name="test_method",
+                    arguments={"obj": NonSerializable()},
+                ),
+            )
+        )
+
+        middleware = StructuredLoggingMiddleware(include_payloads=True)
+
+        result = await middleware.on_message(mock_context, mock_call_next)
+
+        assert result == "test_result"
+
+        assert get_log_lines(caplog) == snapshot(
+            [
+                '{"event": "request_start", "method": "test_method", "source": "client", "payload": "{\\"method\\":\\"tools/call\\",\\"params\\":{\\"_meta\\":null,\\"inputResponses\\":null,\\"requestState\\":null,\\"name\\":\\"test_method\\",\\"arguments\\":{\\"obj\\":\\"NON_SERIALIZABLE\\"},\\"task\\":null}}", "payload_type": "CallToolRequest"}',
+                '{"event": "request_success", "method": "test_method", "source": "client", "duration_ms": 0.02}',
+            ]
+        )
+
+    async def test_on_message_with_custom_serializer_applied(
+        self, mock_call_next: CallNext[Any, Any], caplog: pytest.LogCaptureFixture
+    ):
+        """Ensure a custom serializer is used for non-JSONable payloads."""
+
+        # Provide a serializer that replaces entire payload with a fixed string
+        def custom_serializer(_: Any) -> str:
+            return "CUSTOM_PAYLOAD"
+
+        mock_context = new_mock_context(
+            message=mcp_types.CallToolRequest(
+                method="tools/call",
+                params=mcp_types.CallToolRequestParams(
+                    name="test_method",
+                    arguments={"obj": "OBJECT"},
+                ),
+            )
+        )
+
+        middleware = StructuredLoggingMiddleware(
+            include_payloads=True, payload_serializer=custom_serializer
+        )
+
+        result = await middleware.on_message(mock_context, mock_call_next)
+
+        assert result == "test_result"
+
+        assert get_log_lines(caplog) == snapshot(
+            [
+                '{"event": "request_start", "method": "test_method", "source": "client", "payload": "CUSTOM_PAYLOAD", "payload_type": "CallToolRequest"}',
+                '{"event": "request_success", "method": "test_method", "source": "client", "duration_ms": 0.02}',
+            ]
+        )
+
+
+@pytest.fixture
+def logging_server():
+    """Create a FastMCP server specifically for logging middleware tests."""
+    from fastmcp import FastMCP
+
+    mcp = FastMCP("LoggingTestServer")
+
+    @mcp.tool
+    def simple_operation(data: str) -> str:
+        """A simple operation for testing logging."""
+        return f"Processed: {data}"
+
+    @mcp.tool
+    def complex_operation(items: list[str], mode: str = "default") -> dict:
+        """A complex operation with structured data."""
+        return {"processed_items": len(items), "mode": mode, "result": "success"}
+
+    @mcp.tool
+    def operation_with_error(should_fail: bool = False) -> str:
+        """An operation that can be made to fail."""
+        if should_fail:
+            raise ValueError("Operation failed intentionally")
+        return "Operation completed successfully"
+
+    @mcp.resource("log://test")
+    def test_resource() -> str:
+        """A test resource for logging."""
+        return "Test resource content"
+
+    @mcp.prompt
+    def test_prompt() -> str:
+        """A test prompt for logging."""
+        return "Test prompt content"
+
+    return mcp
+
+
+class TestLoggingMiddlewareIntegration:
+    """Integration tests for logging middleware with real FastMCP server."""
+
+    @pytest.fixture
+    def logging_server(self):
+        """Create a FastMCP server specifically for logging middleware tests."""
+        mcp = FastMCP("LoggingTestServer")
+
+        @mcp.tool
+        def simple_operation(data: str) -> str:
+            """A simple operation for testing logging."""
+            return f"Processed: {data}"
+
+        @mcp.tool
+        def complex_operation(items: list[str], mode: str = "default") -> dict:
+            """A complex operation with structured data."""
+            return {"processed_items": len(items), "mode": mode, "result": "success"}
+
+        @mcp.tool
+        def operation_with_error(should_fail: bool = False) -> str:
+            """An operation that can be made to fail."""
+            if should_fail:
+                raise ValueError("Operation failed intentionally")
+            return "Operation completed successfully"
+
+        @mcp.resource("log://test")
+        def test_resource() -> str:
+            """A test resource for logging."""
+            return "Test resource content"
+
+        @mcp.prompt
+        def test_prompt() -> str:
+            """A test prompt for logging."""
+            return "Test prompt content"
+
+        return mcp
+
+    async def test_logging_middleware_logs_successful_operations(
+        self, logging_server: FastMCP, caplog: pytest.LogCaptureFixture
+    ):
+        """Test that logging middleware captures successful operations."""
+        logging_middleware = LoggingMiddleware(methods=["tools/call"])
+
+        logging_server.add_middleware(logging_middleware)
+
+        with caplog.at_level(logging.INFO):
+            async with Client(logging_server) as client:
+                await client.call_tool(
+                    name="simple_operation", arguments={"data": "test_data"}
+                )
+                await client.call_tool(
+                    name="complex_operation",
+                    arguments={"items": ["a", "b", "c"], "mode": "batch"},
+                )
+
+        # Should have processing and completion logs for both operations
+        assert get_log_lines(caplog) == snapshot(
+            [
+                "event=request_start method=tools/call source=client",
+                "event=request_success method=tools/call source=client duration_ms=0.02",
+                "event=request_start method=tools/call source=client",
+                "event=request_success method=tools/call source=client duration_ms=0.02",
+            ]
+        )
+
+    async def test_logging_middleware_logs_failures(
+        self, logging_server: FastMCP, caplog: pytest.LogCaptureFixture
+    ):
+        """Test that logging middleware captures failed operations."""
+        logging_server.add_middleware(LoggingMiddleware(methods=["tools/call"]))
+
+        async with Client(logging_server) as client:
+            # This should fail and be logged
+            with pytest.raises(Exception):
+                await client.call_tool("operation_with_error", {"should_fail": True})
+
+        log_text = caplog.text
+
+        # Should have processing and failure logs
+        assert log_text.splitlines()[-1] == snapshot(
+            "ERROR    fastmcp.middleware.logging:logging.py:122 event=request_error method=tools/call source=client duration_ms=0.02 error=Error calling tool 'operation_with_error': Operation failed intentionally"
+        )
+
+    async def test_logging_middleware_with_payloads(
+        self, logging_server: FastMCP, caplog: pytest.LogCaptureFixture
+    ):
+        """Test logging middleware when configured to include payloads."""
+
+        middleware = LoggingMiddleware(
+            include_payloads=True, max_payload_length=500, methods=["tools/call"]
+        )
+        logging_server.add_middleware(middleware)
+
+        async with Client(logging_server) as client:
+            await client.call_tool("simple_operation", {"data": "payload_test"})
+
+        assert get_log_lines(caplog) == snapshot(
+            [
+                'event=request_start method=tools/call source=client payload={"_meta":null,"inputResponses":null,"requestState":null,"name":"simple_operation","arguments":{"data":"payload_test"},"task":null} payload_type=CallToolRequestParams',
+                "event=request_success method=tools/call source=client duration_ms=0.02",
+            ]
+        )
+
+    async def test_structured_logging_middleware_produces_json(
+        self, logging_server: FastMCP, caplog: pytest.LogCaptureFixture
+    ):
+        """Test that structured logging middleware produces parseable JSON logs."""
+
+        logging_middleware = StructuredLoggingMiddleware(
+            include_payloads=True, methods=["tools/call"]
+        )
+
+        logging_server.add_middleware(logging_middleware)
+
+        async with Client(logging_server) as client:
+            await client.call_tool(
+                name="simple_operation", arguments={"data": "json_test"}
+            )
+
+        assert get_log_lines(caplog) == snapshot(
+            [
+                '{"event": "request_start", "method": "tools/call", "source": "client", "payload": "{\\"_meta\\":null,\\"inputResponses\\":null,\\"requestState\\":null,\\"name\\":\\"simple_operation\\",\\"arguments\\":{\\"data\\":\\"json_test\\"},\\"task\\":null}", "payload_type": "CallToolRequestParams"}',
+                '{"event": "request_success", "method": "tools/call", "source": "client", "duration_ms": 0.02}',
+            ]
+        )
+
+    async def test_structured_logging_middleware_handles_errors(
+        self, logging_server: FastMCP, caplog: pytest.LogCaptureFixture
+    ):
+        """Test structured logging of errors with JSON format."""
+
+        logging_middleware = StructuredLoggingMiddleware(methods=["tools/call"])
+
+        logging_server.add_middleware(logging_middleware)
+
+        with caplog.at_level(logging.INFO):
+            async with Client(logging_server) as client:
+                with pytest.raises(Exception):
+                    await client.call_tool(
+                        "operation_with_error", {"should_fail": True}
+                    )
+
+        assert get_log_lines(caplog) == snapshot(
+            [
+                '{"event": "request_start", "method": "tools/call", "source": "client"}',
+                '{"event": "request_error", "method": "tools/call", "source": "client", "duration_ms": 0.02, "error": "Error calling tool \'operation_with_error\': Operation failed intentionally"}',
+            ]
+        )
+
+    async def test_logging_middleware_with_different_operations(
+        self, logging_server: FastMCP, caplog: pytest.LogCaptureFixture
+    ):
+        """Test logging middleware with various MCP operations."""
+
+        logging_server.add_middleware(
+            LoggingMiddleware(
+                methods=[
+                    "tools/call",
+                    "resources/list",
+                    "prompts/get",
+                    "resources/read",
+                ]
+            )
+        )
+
+        async with Client(logging_server) as client:
+            # Test different operation types
+            await client.call_tool("simple_operation", {"data": "test"})
+            await client.read_resource("log://test")
+            await client.get_prompt("test_prompt")
+            await client.list_resources()
+
+        assert get_log_lines(caplog) == snapshot(
+            [
+                "event=request_start method=tools/call source=client",
+                "event=request_success method=tools/call source=client duration_ms=0.02",
+                "event=request_start method=resources/read source=client",
+                "event=request_success method=resources/read source=client duration_ms=0.02",
+                "event=request_start method=prompts/get source=client",
+                "event=request_success method=prompts/get source=client duration_ms=0.02",
+                "event=request_start method=resources/list source=client",
+                "event=request_success method=resources/list source=client duration_ms=0.02",
+            ]
+        )
+
+    async def test_logging_middleware_custom_configuration(
+        self, logging_server: FastMCP
+    ):
+        """Test logging middleware with custom logger configuration."""
+        import io
+        import logging
+
+        # Create custom logger
+        log_buffer = io.StringIO()
+        handler = logging.StreamHandler(log_buffer)
+        custom_logger = logging.getLogger("custom_logging_test")
+        custom_logger.addHandler(handler)
+        custom_logger.setLevel(logging.DEBUG)
+
+        logging_server.add_middleware(
+            LoggingMiddleware(
+                logger=custom_logger,
+                log_level=logging.DEBUG,
+                include_payloads=True,
+                methods=["tools/call"],
+            )
+        )
+
+        async with Client(logging_server) as client:
+            await client.call_tool("simple_operation", {"data": "custom_test"})
+
+        # Check that our custom logger captured the logs
+        log_output = log_buffer.getvalue()
+        assert log_output == snapshot("""\
+event=request_start method=tools/call source=client payload={"_meta":null,"inputResponses":null,"requestState":null,"name":"simple_operation","arguments":{"data":"custom_test"},"task":null} payload_type=CallToolRequestParams
+event=request_success method=tools/call source=client duration_ms=0.02
+""")
diff --git a/tests/server/middleware/test_middleware.py b/tests/server/middleware/test_middleware.py
new file mode 100644
index 0000000..f587364
--- /dev/null
+++ b/tests/server/middleware/test_middleware.py
@@ -0,0 +1,625 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+import mcp_types
+import pytest
+from mcp.server.context import ServerRequestContext
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.context import Context
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.tools.base import ToolResult
+
+
+@dataclass
+class Recording:
+    # the hook is the name of the hook that was called, e.g. "on_list_tools"
+    hook: str
+    context: MiddlewareContext
+    result: mcp_types.ServerResult | None
+
+
+class RecordingMiddleware(Middleware):
+    """A middleware that automatically records all method calls."""
+
+    def __init__(self, name: str | None = None):
+        super().__init__()
+        self.calls: list[Recording] = []
+        self.name = name
+
+    def __getattribute__(self, name: str) -> Callable:
+        """Dynamically create recording methods for any on_* method."""
+        if name.startswith("on_"):
+
+            async def record_and_call(
+                context: MiddlewareContext, call_next: Callable
+            ) -> Any:
+                result = await call_next(context)
+
+                self.calls.append(Recording(hook=name, context=context, result=result))
+
+                return result
+
+            return record_and_call
+
+        return super().__getattribute__(name)
+
+    def get_calls(
+        self, method: str | None = None, hook: str | None = None
+    ) -> list[Recording]:
+        """
+        Get all recorded calls for a specific method or hook.
+        Args:
+            method: The method to filter by (e.g. "tools/list")
+            hook: The hook to filter by (e.g. "on_list_tools")
+        Returns:
+            A list of recorded calls.
+        """
+        calls = []
+        for recording in self.calls:
+            if method and hook:
+                if recording.context.method == method and recording.hook == hook:
+                    calls.append(recording)
+            elif method:
+                if recording.context.method == method:
+                    calls.append(recording)
+            elif hook:
+                if recording.hook == hook:
+                    calls.append(recording)
+            else:
+                calls.append(recording)
+        return calls
+
+    def assert_called(
+        self,
+        hook: str | None = None,
+        method: str | None = None,
+        times: int | None = None,
+        at_least: int | None = None,
+    ) -> bool:
+        """Assert that a hook was called a specific number of times."""
+
+        if times is not None and at_least is not None:
+            raise ValueError("Cannot specify both times and at_least")
+        elif times is None and at_least is None:
+            times = 1
+
+        calls = self.get_calls(hook=hook, method=method)
+        actual_times = len(calls)
+        identifier = dict(hook=hook, method=method)
+
+        if times is not None:
+            assert actual_times == times, (
+                f"Expected {times} calls for {identifier}, "
+                f"but was called {actual_times} times"
+            )
+        elif at_least is not None:
+            assert actual_times >= at_least, (
+                f"Expected at least {at_least} calls for {identifier}, "
+                f"but was called {actual_times} times"
+            )
+        return True
+
+    def assert_not_called(self, hook: str | None = None, method: str | None = None):
+        """Assert that a hook was not called."""
+        calls = self.get_calls(hook=hook, method=method)
+        assert len(calls) == 0, f"Expected {hook!r} to not be called"
+        return True
+
+    def reset(self):
+        """Clear all recorded calls."""
+        self.calls.clear()
+
+
+@pytest.fixture
+def recording_middleware():
+    """Fixture that provides a recording middleware instance."""
+    middleware = RecordingMiddleware(name="recording_middleware")
+    yield middleware
+
+
+@pytest.fixture
+def mcp_server(recording_middleware):
+    mcp = FastMCP()
+
+    @mcp.tool(tags={"add-tool"})
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    @mcp.resource("resource://test")
+    def test_resource() -> str:
+        return "test resource"
+
+    @mcp.resource("resource://test-template/{x}")
+    def test_resource_with_path(x: int) -> str:
+        return f"test resource with {x}"
+
+    @mcp.prompt
+    def test_prompt(x: str) -> str:
+        return f"test prompt with {x}"
+
+    @mcp.tool
+    async def progress_tool(context: Context) -> None:
+        await context.report_progress(progress=1, total=10, message="test")
+
+    @mcp.tool
+    async def log_tool(context: Context) -> None:
+        await context.info(message="test log")
+
+    @mcp.tool
+    async def sample_tool(context: Context) -> None:
+        await context.sample("hello")
+
+    mcp.add_middleware(recording_middleware)
+
+    # Register a progress notification handler (v2 API: (ctx, params)).
+    async def handle_progress(
+        _ctx: ServerRequestContext,
+        _params: mcp_types.ProgressNotificationParams,
+    ) -> None:
+        pass
+
+    mcp._mcp_server.add_notification_handler(
+        "notifications/progress",
+        mcp_types.ProgressNotificationParams,
+        handle_progress,
+    )
+
+    return mcp
+
+
+class TestMiddlewareHooks:
+    async def test_call_tool(
+        self, mcp_server: FastMCP, recording_middleware: RecordingMiddleware
+    ):
+        async with Client(mcp_server) as client:
+            await client.call_tool("add", {"a": 1, "b": 2})
+
+        assert recording_middleware.assert_called(at_least=9)
+        assert recording_middleware.assert_called(method="tools/call", at_least=3)
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(hook="on_call_tool", at_least=1)
+
+    async def test_read_resource(
+        self, mcp_server: FastMCP, recording_middleware: RecordingMiddleware
+    ):
+        async with Client(mcp_server) as client:
+            await client.read_resource("resource://test")
+
+        assert recording_middleware.assert_called(at_least=3)
+        assert recording_middleware.assert_called(method="resources/read", at_least=3)
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(hook="on_read_resource", at_least=1)
+
+    async def test_read_resource_template(
+        self, mcp_server: FastMCP, recording_middleware: RecordingMiddleware
+    ):
+        async with Client(mcp_server) as client:
+            await client.read_resource("resource://test-template/1")
+
+        assert recording_middleware.assert_called(at_least=3)
+        assert recording_middleware.assert_called(method="resources/read", at_least=3)
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(hook="on_read_resource", at_least=1)
+
+    async def test_get_prompt(
+        self, mcp_server: FastMCP, recording_middleware: RecordingMiddleware
+    ):
+        async with Client(mcp_server) as client:
+            await client.get_prompt("test_prompt", {"x": "test"})
+
+        assert recording_middleware.assert_called(at_least=3)
+        assert recording_middleware.assert_called(method="prompts/get", at_least=3)
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(hook="on_get_prompt", at_least=1)
+
+    async def test_list_tools(
+        self, mcp_server: FastMCP, recording_middleware: RecordingMiddleware
+    ):
+        async with Client(mcp_server) as client:
+            await client.list_tools()
+
+        assert recording_middleware.assert_called(at_least=3)
+        assert recording_middleware.assert_called(method="tools/list", at_least=3)
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(hook="on_list_tools", at_least=1)
+
+        # Verify the middleware receives a list of tools
+        list_tools_calls = recording_middleware.get_calls(hook="on_list_tools")
+        assert len(list_tools_calls) > 0
+        result = list_tools_calls[0].result
+        assert isinstance(result, list)
+
+    async def test_list_resources(
+        self, mcp_server: FastMCP, recording_middleware: RecordingMiddleware
+    ):
+        async with Client(mcp_server) as client:
+            await client.list_resources()
+
+        assert recording_middleware.assert_called(at_least=3)
+        assert recording_middleware.assert_called(method="resources/list", at_least=3)
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(hook="on_list_resources", at_least=1)
+
+        # Verify the middleware receives a list of resources
+        list_resources_calls = recording_middleware.get_calls(hook="on_list_resources")
+        assert len(list_resources_calls) > 0
+        result = list_resources_calls[0].result
+        assert isinstance(result, list)
+
+    async def test_list_resource_templates(
+        self, mcp_server: FastMCP, recording_middleware: RecordingMiddleware
+    ):
+        async with Client(mcp_server) as client:
+            await client.list_resource_templates()
+
+        assert recording_middleware.assert_called(at_least=3)
+        assert recording_middleware.assert_called(
+            method="resources/templates/list", at_least=3
+        )
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(
+            hook="on_list_resource_templates", at_least=1
+        )
+
+        # Verify the middleware receives a list of resource templates
+        list_templates_calls = recording_middleware.get_calls(
+            hook="on_list_resource_templates"
+        )
+        assert len(list_templates_calls) > 0
+        result = list_templates_calls[0].result
+        assert isinstance(result, list)
+
+    async def test_list_prompts(
+        self, mcp_server: FastMCP, recording_middleware: RecordingMiddleware
+    ):
+        async with Client(mcp_server) as client:
+            await client.list_prompts()
+
+        assert recording_middleware.assert_called(at_least=3)
+        assert recording_middleware.assert_called(method="prompts/list", at_least=3)
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(hook="on_list_prompts", at_least=1)
+
+        # Verify the middleware receives a list of prompts
+        list_prompts_calls = recording_middleware.get_calls(hook="on_list_prompts")
+        assert len(list_prompts_calls) > 0
+        result = list_prompts_calls[0].result
+        assert isinstance(result, list)
+
+    async def test_initialize(
+        self, mcp_server: FastMCP, recording_middleware: RecordingMiddleware
+    ):
+        async with Client(mcp_server) as client:
+            await client.ping()
+
+        assert recording_middleware.assert_called(at_least=1)
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(hook="on_initialize", at_least=1)
+
+    async def test_list_tools_filtering_middleware(self):
+        """Test that middleware can filter tools."""
+
+        class FilteringMiddleware(Middleware):
+            async def on_list_tools(self, context: MiddlewareContext, call_next):
+                result = await call_next(context)
+                # Filter out tools with "private" tag - simple list filtering
+                filtered_tools = [tool for tool in result if "private" not in tool.tags]
+                return filtered_tools
+
+        server = FastMCP("TestServer")
+
+        @server.tool
+        def public_tool(name: str) -> str:
+            return f"Hello {name}"
+
+        @server.tool(tags={"private"})
+        def private_tool(secret: str) -> str:
+            return f"Secret: {secret}"
+
+        server.add_middleware(FilteringMiddleware())
+
+        async with Client(server) as client:
+            tools = await client.list_tools()
+
+        assert len(tools) == 1
+        assert tools[0].name == "public_tool"
+
+    async def test_list_resources_filtering_middleware(self):
+        """Test that middleware can filter resources."""
+
+        class FilteringMiddleware(Middleware):
+            async def on_list_resources(self, context: MiddlewareContext, call_next):
+                result = await call_next(context)
+                # Filter out resources with "private" tag
+                filtered_resources = [
+                    resource for resource in result if "private" not in resource.tags
+                ]
+                return filtered_resources
+
+        server = FastMCP("TestServer")
+
+        @server.resource("resource://public")
+        def public_resource() -> str:
+            return "public data"
+
+        @server.resource("resource://private", tags={"private"})
+        def private_resource() -> str:
+            return "private data"
+
+        server.add_middleware(FilteringMiddleware())
+
+        async with Client(server) as client:
+            resources = await client.list_resources()
+
+        assert len(resources) == 1
+        assert str(resources[0].uri) == "resource://public"
+
+    async def test_list_resource_templates_filtering_middleware(self):
+        """Test that middleware can filter resource templates."""
+
+        class FilteringMiddleware(Middleware):
+            async def on_list_resource_templates(
+                self, context: MiddlewareContext, call_next
+            ):
+                result = await call_next(context)
+                # Filter out templates with "private" tag
+                filtered_templates = [
+                    template for template in result if "private" not in template.tags
+                ]
+                return filtered_templates
+
+        server = FastMCP("TestServer")
+
+        @server.resource("resource://public/{x}")
+        def public_template(x: str) -> str:
+            return f"public {x}"
+
+        @server.resource("resource://private/{x}", tags={"private"})
+        def private_template(x: str) -> str:
+            return f"private {x}"
+
+        server.add_middleware(FilteringMiddleware())
+
+        async with Client(server) as client:
+            templates = await client.list_resource_templates()
+
+        assert len(templates) == 1
+        assert str(templates[0].uri_template) == "resource://public/{x}"
+
+    async def test_list_prompts_filtering_middleware(self):
+        """Test that middleware can filter prompts."""
+
+        class FilteringMiddleware(Middleware):
+            async def on_list_prompts(self, context: MiddlewareContext, call_next):
+                result = await call_next(context)
+                # Filter out prompts with "private" tag
+                filtered_prompts = [
+                    prompt for prompt in result if "private" not in prompt.tags
+                ]
+                return filtered_prompts
+
+        server = FastMCP("TestServer")
+
+        @server.prompt
+        def public_prompt(name: str) -> str:
+            return f"Hello {name}"
+
+        @server.prompt(tags={"private"})
+        def private_prompt(secret: str) -> str:
+            return f"Secret: {secret}"
+
+        server.add_middleware(FilteringMiddleware())
+
+        async with Client(server) as client:
+            prompts = await client.list_prompts()
+
+        assert len(prompts) == 1
+        assert prompts[0].name == "public_prompt"
+
+    async def test_call_tool_middleware(self):
+        server = FastMCP()
+
+        @server.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        class CallToolMiddleware(Middleware):
+            async def on_call_tool(
+                self,
+                context: MiddlewareContext[mcp_types.CallToolRequestParams],
+                call_next: CallNext[mcp_types.CallToolRequestParams, ToolResult],
+            ):
+                # modify argument
+                if context.message.name == "add":
+                    assert context.message.arguments is not None
+                    args = context.message.arguments
+                    assert isinstance(args["a"], int)
+                    args["a"] += 100
+
+                result = await call_next(context)
+
+                # modify result
+                if context.message.name == "add":
+                    assert result.structured_content is not None
+                    content = result.structured_content
+                    assert isinstance(content["result"], int)
+                    content["result"] += 5
+
+                return result
+
+        server.add_middleware(CallToolMiddleware())
+
+        async with Client(server) as client:
+            result = await client.call_tool("add", {"a": 1, "b": 2})
+
+        assert isinstance(result.structured_content["result"], int)
+        assert result.structured_content["result"] == 108
+
+
+class TestApplyMiddlewareParameter:
+    """Tests for run_middleware parameter on execution methods."""
+
+    async def test_call_tool_with_run_middleware_true(self):
+        """Middleware is applied when run_middleware=True (default)."""
+        recording = RecordingMiddleware()
+        server = FastMCP()
+
+        @server.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        server.add_middleware(recording)
+
+        result = await server.call_tool("add", {"a": 1, "b": 2})
+
+        assert result.structured_content["result"] == 3  # type: ignore[union-attr,index]  # ty:ignore[not-subscriptable]
+        assert recording.assert_called(hook="on_call_tool", times=1)
+
+    async def test_call_tool_with_run_middleware_false(self):
+        """Middleware is NOT applied when run_middleware=False."""
+        recording = RecordingMiddleware()
+        server = FastMCP()
+
+        @server.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        server.add_middleware(recording)
+
+        result = await server.call_tool("add", {"a": 1, "b": 2}, run_middleware=False)
+
+        assert result.structured_content["result"] == 3  # type: ignore[union-attr,index]  # ty:ignore[not-subscriptable]
+        # Middleware should not have been called
+        assert len(recording.calls) == 0
+
+    async def test_read_resource_with_run_middleware_true(self):
+        """Middleware is applied when run_middleware=True (default)."""
+        recording = RecordingMiddleware()
+        server = FastMCP()
+
+        @server.resource("resource://test")
+        def test_resource() -> str:
+            return "test content"
+
+        server.add_middleware(recording)
+
+        result = await server.read_resource("resource://test")
+
+        assert len(result.contents) == 1
+        assert result.contents[0].content == "test content"
+        assert recording.assert_called(hook="on_read_resource", times=1)
+
+    async def test_read_resource_with_run_middleware_false(self):
+        """Middleware is NOT applied when run_middleware=False."""
+        recording = RecordingMiddleware()
+        server = FastMCP()
+
+        @server.resource("resource://test")
+        def test_resource() -> str:
+            return "test content"
+
+        server.add_middleware(recording)
+
+        result = await server.read_resource("resource://test", run_middleware=False)
+
+        assert len(result.contents) == 1
+        assert result.contents[0].content == "test content"
+        # Middleware should not have been called
+        assert len(recording.calls) == 0
+
+    async def test_read_resource_template_with_run_middleware_false(self):
+        """Templates also skip middleware when run_middleware=False."""
+        recording = RecordingMiddleware()
+        server = FastMCP()
+
+        @server.resource("resource://items/{item_id}")
+        def get_item(item_id: int) -> str:
+            return f"item {item_id}"
+
+        server.add_middleware(recording)
+
+        result = await server.read_resource("resource://items/42", run_middleware=False)
+
+        assert len(result.contents) == 1
+        assert result.contents[0].content == "item 42"
+        assert len(recording.calls) == 0
+
+    async def test_render_prompt_with_run_middleware_true(self):
+        """Middleware is applied when run_middleware=True (default)."""
+        recording = RecordingMiddleware()
+        server = FastMCP()
+
+        @server.prompt
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        server.add_middleware(recording)
+
+        result = await server.render_prompt("greet", {"name": "World"})
+
+        assert len(result.messages) == 1
+        # content is TextContent | EmbeddedResource, but we know it's TextContent from the test
+        assert isinstance(result.messages[0].content, mcp_types.TextContent)
+        assert result.messages[0].content.text == "Hello, World!"
+        assert recording.assert_called(hook="on_get_prompt", times=1)
+
+    async def test_render_prompt_with_run_middleware_false(self):
+        """Middleware is NOT applied when run_middleware=False."""
+        recording = RecordingMiddleware()
+        server = FastMCP()
+
+        @server.prompt
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        server.add_middleware(recording)
+
+        result = await server.render_prompt(
+            "greet", {"name": "World"}, run_middleware=False
+        )
+
+        assert len(result.messages) == 1
+        # content is TextContent | EmbeddedResource, but we know it's TextContent from the test
+        assert isinstance(result.messages[0].content, mcp_types.TextContent)
+        assert result.messages[0].content.text == "Hello, World!"
+        # Middleware should not have been called
+        assert len(recording.calls) == 0
+
+    async def test_middleware_modification_skipped_when_run_middleware_false(self):
+        """Middleware that modifies args/results is skipped."""
+
+        class ModifyingMiddleware(Middleware):
+            async def on_call_tool(self, context: MiddlewareContext, call_next):
+                # Double the 'a' argument
+                assert context.message.arguments is not None
+                context.message.arguments["a"] *= 2
+                return await call_next(context)
+
+        server = FastMCP()
+
+        @server.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        server.add_middleware(ModifyingMiddleware())
+
+        # With middleware: a=5 becomes a=10, result = 10 + 3 = 13
+        result_with = await server.call_tool("add", {"a": 5, "b": 3})
+        assert result_with.structured_content["result"] == 13  # type: ignore[union-attr,index]  # ty:ignore[not-subscriptable]
+
+        # Without middleware: a=5 stays a=5, result = 5 + 3 = 8
+        result_without = await server.call_tool(
+            "add", {"a": 5, "b": 3}, run_middleware=False
+        )
+        assert result_without.structured_content["result"] == 8  # type: ignore[union-attr,index]  # ty:ignore[not-subscriptable]
diff --git a/tests/server/middleware/test_middleware_nested.py b/tests/server/middleware/test_middleware_nested.py
new file mode 100644
index 0000000..cc2eea6
--- /dev/null
+++ b/tests/server/middleware/test_middleware_nested.py
@@ -0,0 +1,678 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+import mcp_types
+import pytest
+from mcp.server.context import ServerRequestContext
+
+from fastmcp import Client, FastMCP
+from fastmcp.exceptions import ToolError
+from fastmcp.server import create_proxy
+from fastmcp.server.context import Context
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.tools.base import ToolResult
+
+
+@dataclass
+class Recording:
+    # the hook is the name of the hook that was called, e.g. "on_list_tools"
+    hook: str
+    context: MiddlewareContext
+    result: mcp_types.ServerResult | None
+
+
+class RecordingMiddleware(Middleware):
+    """A middleware that automatically records all method calls."""
+
+    def __init__(self, name: str | None = None):
+        super().__init__()
+        self.calls: list[Recording] = []
+        self.name = name
+
+    def __getattribute__(self, name: str) -> Callable:
+        """Dynamically create recording methods for any on_* method."""
+        if name.startswith("on_"):
+
+            async def record_and_call(
+                context: MiddlewareContext, call_next: Callable
+            ) -> Any:
+                result = await call_next(context)
+
+                self.calls.append(Recording(hook=name, context=context, result=result))
+
+                return result
+
+            return record_and_call
+
+        return super().__getattribute__(name)
+
+    def get_calls(
+        self, method: str | None = None, hook: str | None = None
+    ) -> list[Recording]:
+        """
+        Get all recorded calls for a specific method or hook.
+        Args:
+            method: The method to filter by (e.g. "tools/list")
+            hook: The hook to filter by (e.g. "on_list_tools")
+        Returns:
+            A list of recorded calls.
+        """
+        calls = []
+        for recording in self.calls:
+            if method and hook:
+                if recording.context.method == method and recording.hook == hook:
+                    calls.append(recording)
+            elif method:
+                if recording.context.method == method:
+                    calls.append(recording)
+            elif hook:
+                if recording.hook == hook:
+                    calls.append(recording)
+            else:
+                calls.append(recording)
+        return calls
+
+    def assert_called(
+        self,
+        hook: str | None = None,
+        method: str | None = None,
+        times: int | None = None,
+        at_least: int | None = None,
+    ) -> bool:
+        """Assert that a hook was called a specific number of times."""
+
+        if times is not None and at_least is not None:
+            raise ValueError("Cannot specify both times and at_least")
+        elif times is None and at_least is None:
+            times = 1
+
+        calls = self.get_calls(hook=hook, method=method)
+        actual_times = len(calls)
+        identifier = dict(hook=hook, method=method)
+
+        if times is not None:
+            assert actual_times == times, (
+                f"Expected {times} calls for {identifier}, "
+                f"but was called {actual_times} times"
+            )
+        elif at_least is not None:
+            assert actual_times >= at_least, (
+                f"Expected at least {at_least} calls for {identifier}, "
+                f"but was called {actual_times} times"
+            )
+        return True
+
+    def assert_not_called(self, hook: str | None = None, method: str | None = None):
+        """Assert that a hook was not called."""
+        calls = self.get_calls(hook=hook, method=method)
+        assert len(calls) == 0, f"Expected {hook!r} to not be called"
+        return True
+
+    def reset(self):
+        """Clear all recorded calls."""
+        self.calls.clear()
+
+
+@pytest.fixture
+def recording_middleware():
+    """Fixture that provides a recording middleware instance."""
+    middleware = RecordingMiddleware(name="recording_middleware")
+    yield middleware
+
+
+@pytest.fixture
+def mcp_server(recording_middleware):
+    mcp = FastMCP()
+
+    @mcp.tool(tags={"add-tool"})
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    @mcp.resource("resource://test")
+    def test_resource() -> str:
+        return "test resource"
+
+    @mcp.resource("resource://test-template/{x}")
+    def test_resource_with_path(x: int) -> str:
+        return f"test resource with {x}"
+
+    @mcp.prompt
+    def test_prompt(x: str) -> str:
+        return f"test prompt with {x}"
+
+    @mcp.tool
+    async def progress_tool(context: Context) -> None:
+        await context.report_progress(progress=1, total=10, message="test")
+
+    @mcp.tool
+    async def log_tool(context: Context) -> None:
+        await context.info(message="test log")
+
+    @mcp.tool
+    async def sample_tool(context: Context) -> None:
+        await context.sample("hello")
+
+    mcp.add_middleware(recording_middleware)
+
+    # Register a progress notification handler (v2 API: (ctx, params)).
+    async def handle_progress(
+        _ctx: ServerRequestContext,
+        _params: mcp_types.ProgressNotificationParams,
+    ) -> None:
+        pass
+
+    mcp._mcp_server.add_notification_handler(
+        "notifications/progress",
+        mcp_types.ProgressNotificationParams,
+        handle_progress,
+    )
+
+    return mcp
+
+
+class TestNestedMiddlewareHooks:
+    @pytest.fixture
+    @staticmethod
+    def nested_middleware():
+        return RecordingMiddleware(name="nested_middleware")
+
+    @pytest.fixture
+    def nested_mcp_server(self, nested_middleware: RecordingMiddleware):
+        mcp = FastMCP(name="Nested MCP")
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        @mcp.resource("resource://test")
+        def test_resource() -> str:
+            return "test resource"
+
+        @mcp.resource("resource://test-template/{x}")
+        def test_resource_with_path(x: int) -> str:
+            return f"test resource with {x}"
+
+        @mcp.prompt
+        def test_prompt(x: str) -> str:
+            return f"test prompt with {x}"
+
+        @mcp.tool
+        async def progress_tool(context: Context) -> None:
+            await context.report_progress(progress=1, total=10, message="test")
+
+        @mcp.tool
+        async def log_tool(context: Context) -> None:
+            await context.info(message="test log")
+
+        @mcp.tool
+        async def sample_tool(context: Context) -> None:
+            await context.sample("hello")
+
+        mcp.add_middleware(nested_middleware)
+
+        return mcp
+
+    async def test_call_tool_on_parent_server(
+        self,
+        mcp_server: FastMCP,
+        nested_mcp_server: FastMCP,
+        recording_middleware: RecordingMiddleware,
+        nested_middleware: RecordingMiddleware,
+    ):
+        mcp_server.mount(nested_mcp_server, namespace="nested")
+
+        async with Client(mcp_server) as client:
+            await client.call_tool("add", {"a": 1, "b": 2})
+
+        assert recording_middleware.assert_called(at_least=3)
+        assert recording_middleware.assert_called(method="tools/call", at_least=3)
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(hook="on_call_tool", at_least=1)
+
+        assert nested_middleware.assert_called(method="tools/call", times=0)
+
+    async def test_call_tool_on_nested_server(
+        self,
+        mcp_server: FastMCP,
+        nested_mcp_server: FastMCP,
+        recording_middleware: RecordingMiddleware,
+        nested_middleware: RecordingMiddleware,
+    ):
+        mcp_server.mount(nested_mcp_server, namespace="nested")
+
+        async with Client(mcp_server) as client:
+            await client.call_tool("nested_add", {"a": 1, "b": 2})
+
+        assert recording_middleware.assert_called(at_least=3)
+        assert recording_middleware.assert_called(method="tools/call", at_least=3)
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(hook="on_call_tool", at_least=1)
+
+        assert nested_middleware.assert_called(at_least=3)
+        assert nested_middleware.assert_called(method="tools/call", at_least=3)
+        assert nested_middleware.assert_called(hook="on_message", at_least=1)
+        assert nested_middleware.assert_called(hook="on_request", at_least=1)
+        assert nested_middleware.assert_called(hook="on_call_tool", at_least=1)
+
+    async def test_read_resource_on_parent_server(
+        self,
+        mcp_server: FastMCP,
+        nested_mcp_server: FastMCP,
+        recording_middleware: RecordingMiddleware,
+        nested_middleware: RecordingMiddleware,
+    ):
+        mcp_server.mount(nested_mcp_server, namespace="nested")
+
+        async with Client(mcp_server) as client:
+            await client.read_resource("resource://test")
+
+        assert recording_middleware.assert_called(at_least=3)
+        assert recording_middleware.assert_called(method="resources/read", at_least=3)
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(hook="on_read_resource", at_least=1)
+
+        assert nested_middleware.assert_called(times=0)
+
+    async def test_read_resource_on_nested_server(
+        self,
+        mcp_server: FastMCP,
+        nested_mcp_server: FastMCP,
+        recording_middleware: RecordingMiddleware,
+        nested_middleware: RecordingMiddleware,
+    ):
+        mcp_server.mount(nested_mcp_server, namespace="nested")
+
+        async with Client(mcp_server) as client:
+            await client.read_resource("resource://nested/test")
+
+        assert recording_middleware.assert_called(at_least=3)
+        assert recording_middleware.assert_called(method="resources/read", at_least=3)
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(hook="on_read_resource", at_least=1)
+
+        assert nested_middleware.assert_called(at_least=3)
+        assert nested_middleware.assert_called(method="resources/read", at_least=3)
+        assert nested_middleware.assert_called(hook="on_message", at_least=1)
+        assert nested_middleware.assert_called(hook="on_request", at_least=1)
+        assert nested_middleware.assert_called(hook="on_read_resource", at_least=1)
+
+    async def test_read_resource_template_on_parent_server(
+        self,
+        mcp_server: FastMCP,
+        nested_mcp_server: FastMCP,
+        recording_middleware: RecordingMiddleware,
+        nested_middleware: RecordingMiddleware,
+    ):
+        mcp_server.mount(nested_mcp_server, namespace="nested")
+
+        async with Client(mcp_server) as client:
+            await client.read_resource("resource://test-template/1")
+
+        assert recording_middleware.assert_called(at_least=3)
+        assert recording_middleware.assert_called(method="resources/read", at_least=3)
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(hook="on_read_resource", at_least=1)
+
+        assert nested_middleware.assert_called(times=0)
+
+    async def test_read_resource_template_on_nested_server(
+        self,
+        mcp_server: FastMCP,
+        nested_mcp_server: FastMCP,
+        recording_middleware: RecordingMiddleware,
+        nested_middleware: RecordingMiddleware,
+    ):
+        mcp_server.mount(nested_mcp_server, namespace="nested")
+
+        async with Client(mcp_server) as client:
+            await client.read_resource("resource://nested/test-template/1")
+
+        assert recording_middleware.assert_called(at_least=3)
+        assert recording_middleware.assert_called(method="resources/read", at_least=3)
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(hook="on_read_resource", at_least=1)
+
+        assert nested_middleware.assert_called(at_least=3)
+        assert nested_middleware.assert_called(method="resources/read", at_least=3)
+        assert nested_middleware.assert_called(hook="on_message", at_least=1)
+        assert nested_middleware.assert_called(hook="on_request", at_least=1)
+        assert nested_middleware.assert_called(hook="on_read_resource", at_least=1)
+
+    async def test_get_prompt_on_parent_server(
+        self,
+        mcp_server: FastMCP,
+        nested_mcp_server: FastMCP,
+        recording_middleware: RecordingMiddleware,
+        nested_middleware: RecordingMiddleware,
+    ):
+        mcp_server.mount(nested_mcp_server, namespace="nested")
+
+        async with Client(mcp_server) as client:
+            await client.get_prompt("test_prompt", {"x": "test"})
+
+        assert recording_middleware.assert_called(at_least=3)
+        assert recording_middleware.assert_called(method="prompts/get", at_least=3)
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(hook="on_get_prompt", at_least=1)
+
+        assert nested_middleware.assert_called(times=0)
+
+    async def test_get_prompt_on_nested_server(
+        self,
+        mcp_server: FastMCP,
+        nested_mcp_server: FastMCP,
+        recording_middleware: RecordingMiddleware,
+        nested_middleware: RecordingMiddleware,
+    ):
+        mcp_server.mount(nested_mcp_server, namespace="nested")
+
+        async with Client(mcp_server) as client:
+            await client.get_prompt("nested_test_prompt", {"x": "test"})
+
+        assert recording_middleware.assert_called(at_least=3)
+        assert recording_middleware.assert_called(method="prompts/get", at_least=3)
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(hook="on_get_prompt", at_least=1)
+
+        assert nested_middleware.assert_called(at_least=3)
+        assert nested_middleware.assert_called(method="prompts/get", at_least=3)
+        assert nested_middleware.assert_called(hook="on_message", at_least=1)
+        assert nested_middleware.assert_called(hook="on_request", at_least=1)
+        assert nested_middleware.assert_called(hook="on_get_prompt", at_least=1)
+
+    async def test_list_tools_on_nested_server(
+        self,
+        mcp_server: FastMCP,
+        nested_mcp_server: FastMCP,
+        recording_middleware: RecordingMiddleware,
+        nested_middleware: RecordingMiddleware,
+    ):
+        mcp_server.mount(nested_mcp_server, namespace="nested")
+
+        async with Client(mcp_server) as client:
+            await client.list_tools()
+
+        assert recording_middleware.assert_called(at_least=3)
+        assert recording_middleware.assert_called(method="tools/list", at_least=3)
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(hook="on_list_tools", at_least=1)
+
+        assert nested_middleware.assert_called(at_least=3)
+        assert nested_middleware.assert_called(method="tools/list", at_least=3)
+        assert nested_middleware.assert_called(hook="on_message", at_least=1)
+        assert nested_middleware.assert_called(hook="on_request", at_least=1)
+        assert nested_middleware.assert_called(hook="on_list_tools", at_least=1)
+
+    async def test_list_resources_on_nested_server(
+        self,
+        mcp_server: FastMCP,
+        nested_mcp_server: FastMCP,
+        recording_middleware: RecordingMiddleware,
+        nested_middleware: RecordingMiddleware,
+    ):
+        mcp_server.mount(nested_mcp_server, namespace="nested")
+
+        async with Client(mcp_server) as client:
+            await client.list_resources()
+
+        assert recording_middleware.assert_called(at_least=3)
+        assert recording_middleware.assert_called(method="resources/list", at_least=3)
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(hook="on_list_resources", at_least=1)
+
+        assert nested_middleware.assert_called(at_least=3)
+        assert nested_middleware.assert_called(method="resources/list", at_least=3)
+        assert nested_middleware.assert_called(hook="on_message", at_least=1)
+        assert nested_middleware.assert_called(hook="on_request", at_least=1)
+        assert nested_middleware.assert_called(hook="on_list_resources", at_least=1)
+
+    async def test_list_resource_templates_on_nested_server(
+        self,
+        mcp_server: FastMCP,
+        nested_mcp_server: FastMCP,
+        recording_middleware: RecordingMiddleware,
+        nested_middleware: RecordingMiddleware,
+    ):
+        mcp_server.mount(nested_mcp_server, namespace="nested")
+
+        async with Client(mcp_server) as client:
+            await client.list_resource_templates()
+
+        assert recording_middleware.assert_called(at_least=3)
+        assert recording_middleware.assert_called(
+            method="resources/templates/list", at_least=3
+        )
+        assert recording_middleware.assert_called(hook="on_message", at_least=1)
+        assert recording_middleware.assert_called(hook="on_request", at_least=1)
+        assert recording_middleware.assert_called(
+            hook="on_list_resource_templates", at_least=1
+        )
+
+        assert nested_middleware.assert_called(at_least=3)
+        assert nested_middleware.assert_called(
+            method="resources/templates/list", at_least=3
+        )
+        assert nested_middleware.assert_called(hook="on_message", at_least=1)
+        assert nested_middleware.assert_called(hook="on_request", at_least=1)
+        assert nested_middleware.assert_called(
+            hook="on_list_resource_templates", at_least=1
+        )
+
+
+class TestProxyServer:
+    async def test_call_tool(
+        self, mcp_server: FastMCP, recording_middleware: RecordingMiddleware
+    ):
+        # proxy server will have its tools listed as well as called in order to
+        # apply transforms and filters prior to the call.
+        proxy_server = create_proxy(mcp_server, name="Proxy Server")
+        async with Client(proxy_server) as client:
+            await client.call_tool("add", {"a": 1, "b": 2})
+
+        assert recording_middleware.assert_called(at_least=6)
+        assert recording_middleware.assert_called(method="tools/call", at_least=3)
+        assert recording_middleware.assert_called(method="tools/list", at_least=3)
+        assert recording_middleware.assert_called(hook="on_message", at_least=2)
+        assert recording_middleware.assert_called(hook="on_request", at_least=2)
+        assert recording_middleware.assert_called(hook="on_call_tool", at_least=1)
+        assert recording_middleware.assert_called(hook="on_list_tools", at_least=1)
+
+    async def test_proxied_tags_are_visible_to_middleware(
+        self, mcp_server: FastMCP, recording_middleware: RecordingMiddleware
+    ):
+        """Tests that tags on remote FastMCP servers are visible to middleware
+        via proxy. See https://github.com/PrefectHQ/fastmcp/issues/1300"""
+        proxy_server = create_proxy(mcp_server, name="Proxy Server")
+
+        TAGS = []
+
+        class TagMiddleware(Middleware):
+            async def on_list_tools(self, context: MiddlewareContext, call_next):
+                nonlocal TAGS
+                result = await call_next(context)
+                for tool in result:
+                    TAGS.append(tool.tags)
+                return result
+
+        proxy_server.add_middleware(TagMiddleware())
+
+        async with Client(proxy_server) as client:
+            await client.list_tools()
+
+        assert TAGS == [{"add-tool"}, set(), set(), set()]
+
+
+class TestToolCallDenial:
+    """Test denying tool calls in middleware using ToolError."""
+
+    async def test_deny_tool_call_with_tool_error(self):
+        """Test that middleware can deny tool calls by raising ToolError."""
+
+        class AuthMiddleware(Middleware):
+            async def on_call_tool(
+                self,
+                context: MiddlewareContext[mcp_types.CallToolRequestParams],
+                call_next: CallNext[mcp_types.CallToolRequestParams, ToolResult],
+            ) -> ToolResult:
+                tool_name = context.message.name
+                if tool_name.lower() == "restricted_tool":
+                    raise ToolError("Access denied: tool is disabled")
+                return await call_next(context)
+
+        server = FastMCP("TestServer")
+
+        @server.tool
+        def allowed_tool(x: int) -> int:
+            """This tool is allowed."""
+            return x * 2
+
+        @server.tool
+        def restricted_tool(x: int) -> int:
+            """This tool should be denied by middleware."""
+            return x * 3
+
+        server.add_middleware(AuthMiddleware())
+
+        async with Client(server) as client:
+            # Allowed tool should work normally
+            result = await client.call_tool("allowed_tool", {"x": 5})
+            assert result.structured_content is not None
+            assert result.structured_content["result"] == 10
+
+            # Restricted tool should raise ToolError
+            with pytest.raises(ToolError) as exc_info:
+                await client.call_tool("restricted_tool", {"x": 5})
+
+            # Verify the error message is preserved
+            assert "Access denied: tool is disabled" in str(exc_info.value)
+
+    async def test_middleware_can_selectively_deny_tools(self):
+        """Test that middleware can deny specific tools while allowing others."""
+
+        denied_tools = set()
+
+        class SelectiveAuthMiddleware(Middleware):
+            async def on_call_tool(
+                self,
+                context: MiddlewareContext[mcp_types.CallToolRequestParams],
+                call_next: CallNext[mcp_types.CallToolRequestParams, ToolResult],
+            ) -> ToolResult:
+                tool_name = context.message.name
+
+                # Deny tools that start with "admin_"
+                if tool_name.startswith("admin_"):
+                    denied_tools.add(tool_name)
+                    raise ToolError(
+                        f"Access denied: {tool_name} requires admin privileges"
+                    )
+
+                return await call_next(context)
+
+        server = FastMCP("TestServer")
+
+        @server.tool
+        def public_tool(x: int) -> int:
+            """Public tool available to all."""
+            return x + 1
+
+        @server.tool
+        def admin_delete(item_id: str) -> str:
+            """Admin tool that should be denied."""
+            return f"Deleted {item_id}"
+
+        @server.tool
+        def admin_config(setting: str, value: str) -> str:
+            """Another admin tool that should be denied."""
+            return f"Set {setting} to {value}"
+
+        server.add_middleware(SelectiveAuthMiddleware())
+
+        async with Client(server) as client:
+            # Public tool should work
+            result = await client.call_tool("public_tool", {"x": 10})
+            assert result.structured_content is not None
+            assert result.structured_content["result"] == 11
+
+            # Admin tools should be denied
+            with pytest.raises(ToolError) as exc_info:
+                await client.call_tool("admin_delete", {"item_id": "test123"})
+            assert "requires admin privileges" in str(exc_info.value)
+
+            with pytest.raises(ToolError) as exc_info:
+                await client.call_tool(
+                    "admin_config", {"setting": "debug", "value": "true"}
+                )
+            assert "requires admin privileges" in str(exc_info.value)
+
+        # Verify both admin tools were denied
+        assert denied_tools == {"admin_delete", "admin_config"}
+
+
+class TestMiddlewareRequestState:
+    """Non-serializable state set in middleware must be visible to tools/resources.
+
+    Regression test for https://github.com/PrefectHQ/fastmcp/issues/3228.
+    """
+
+    async def test_non_serializable_state_from_middleware_visible_in_tool(self):
+        server = FastMCP("test")
+
+        sentinel = object()
+
+        class StateMiddleware(Middleware):
+            async def on_call_tool(
+                self, context: MiddlewareContext, call_next: CallNext
+            ) -> Any:
+                assert context.fastmcp_context is not None
+                await context.fastmcp_context.set_state(
+                    "obj", sentinel, serializable=False
+                )
+                return await call_next(context)
+
+        server.add_middleware(StateMiddleware())
+
+        @server.tool()
+        async def read_it(ctx: Context) -> str:
+            val = await ctx.get_state("obj")
+            return "found" if val is sentinel else "missing"
+
+        async with Client(server) as client:
+            result = await client.call_tool("read_it")
+            assert result.content[0].text == "found"
+
+    async def test_non_serializable_state_from_middleware_visible_in_resource(self):
+        server = FastMCP("test")
+
+        sentinel = object()
+
+        class StateMiddleware(Middleware):
+            async def on_read_resource(
+                self, context: MiddlewareContext, call_next: CallNext
+            ) -> Any:
+                assert context.fastmcp_context is not None
+                await context.fastmcp_context.set_state(
+                    "obj", sentinel, serializable=False
+                )
+                return await call_next(context)
+
+        server.add_middleware(StateMiddleware())
+
+        @server.resource("test://data")
+        async def read_it(ctx: Context) -> str:
+            val = await ctx.get_state("obj")
+            return "found" if val is sentinel else "missing"
+
+        async with Client(server) as client:
+            result = await client.read_resource("test://data")
+            assert result[0].text == "found"
diff --git a/tests/server/middleware/test_ping.py b/tests/server/middleware/test_ping.py
new file mode 100644
index 0000000..b35616f
--- /dev/null
+++ b/tests/server/middleware/test_ping.py
@@ -0,0 +1,226 @@
+"""Tests for ping middleware."""
+
+from unittest.mock import AsyncMock, MagicMock
+
+import anyio
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.middleware.ping import PingMiddleware
+
+
+class TestPingMiddlewareInit:
+    """Test PingMiddleware initialization."""
+
+    def test_init_default(self):
+        """Test default initialization."""
+        middleware = PingMiddleware()
+        assert middleware.interval_ms == 30000
+        assert middleware._active_sessions == set()
+
+    def test_init_custom(self):
+        """Test custom interval initialization."""
+        middleware = PingMiddleware(interval_ms=5000)
+        assert middleware.interval_ms == 5000
+
+    def test_init_invalid_interval_zero(self):
+        """Test that zero interval raises ValueError."""
+        with pytest.raises(ValueError, match="interval_ms must be positive"):
+            PingMiddleware(interval_ms=0)
+
+    def test_init_invalid_interval_negative(self):
+        """Test that negative interval raises ValueError."""
+        with pytest.raises(ValueError, match="interval_ms must be positive"):
+            PingMiddleware(interval_ms=-1000)
+
+
+class TestPingMiddlewareOnMessage:
+    """Test on_message hook behavior."""
+
+    def _mock_session(self):
+        """Build a mock session with a stable per-connection Connection.
+
+        SDK v2 constructs a ServerSession per request; PingMiddleware keys the
+        keepalive loop off the underlying Connection (and registers cleanup on
+        its exit stack), so tests supply a connection with an exit_stack.
+        """
+        connection = MagicMock()
+        connection.exit_stack = MagicMock()
+        connection.exit_stack.push_async_callback = MagicMock()
+        session = MagicMock()
+        session._connection = connection
+        session.send_ping = AsyncMock()
+        return session, connection
+
+    async def test_starts_ping_task_on_first_message(self):
+        """Test that a ping task is started on first message from a connection."""
+        middleware = PingMiddleware(interval_ms=1000)
+
+        mock_session, connection = self._mock_session()
+        mock_context = MagicMock()
+        mock_context.fastmcp_context.session = mock_session
+
+        mock_call_next = AsyncMock(return_value="result")
+
+        result = await middleware.on_message(mock_context, mock_call_next)
+
+        assert result == "result"
+        assert id(connection) in middleware._active_sessions
+        connection.exit_stack.push_async_callback.assert_called_once()
+
+    async def test_does_not_start_duplicate_task(self):
+        """Test that duplicate messages from same connection don't spawn duplicates."""
+        middleware = PingMiddleware(interval_ms=1000)
+
+        mock_session, connection = self._mock_session()
+        mock_context = MagicMock()
+        mock_context.fastmcp_context.session = mock_session
+
+        mock_call_next = AsyncMock(return_value="result")
+
+        # Three messages from the same connection
+        await middleware.on_message(mock_context, mock_call_next)
+        await middleware.on_message(mock_context, mock_call_next)
+        await middleware.on_message(mock_context, mock_call_next)
+
+        # Cleanup registered only once
+        assert connection.exit_stack.push_async_callback.call_count == 1
+        assert len(middleware._active_sessions) == 1
+
+    async def test_starts_separate_task_per_session(self):
+        """Test that different connections get separate ping tasks."""
+        middleware = PingMiddleware(interval_ms=1000)
+
+        mock_session1, connection1 = self._mock_session()
+        mock_session2, connection2 = self._mock_session()
+
+        mock_context1 = MagicMock()
+        mock_context1.fastmcp_context.session = mock_session1
+
+        mock_context2 = MagicMock()
+        mock_context2.fastmcp_context.session = mock_session2
+
+        mock_call_next = AsyncMock(return_value="result")
+
+        await middleware.on_message(mock_context1, mock_call_next)
+        await middleware.on_message(mock_context2, mock_call_next)
+
+        connection1.exit_stack.push_async_callback.assert_called_once()
+        connection2.exit_stack.push_async_callback.assert_called_once()
+        assert len(middleware._active_sessions) == 2
+
+    async def test_skips_when_fastmcp_context_is_none(self):
+        """Test that middleware passes through when fastmcp_context is None."""
+        middleware = PingMiddleware(interval_ms=1000)
+
+        mock_context = MagicMock()
+        mock_context.fastmcp_context = None
+
+        mock_call_next = AsyncMock(return_value="result")
+
+        result = await middleware.on_message(mock_context, mock_call_next)
+
+        assert result == "result"
+        assert len(middleware._active_sessions) == 0
+
+    async def test_skips_when_request_context_is_none(self):
+        """Test that middleware passes through when request_context is None."""
+        middleware = PingMiddleware(interval_ms=1000)
+
+        mock_context = MagicMock()
+        mock_context.fastmcp_context = MagicMock()
+        mock_context.fastmcp_context.request_context = None
+
+        mock_call_next = AsyncMock(return_value="result")
+
+        result = await middleware.on_message(mock_context, mock_call_next)
+
+        assert result == "result"
+        assert len(middleware._active_sessions) == 0
+
+
+class TestPingLoop:
+    """Test the ping loop behavior."""
+
+    async def test_ping_loop_sends_pings_at_interval(self):
+        """Test that ping loop sends pings at configured interval."""
+        middleware = PingMiddleware(interval_ms=50)
+
+        mock_session = MagicMock()
+        mock_session.send_ping = AsyncMock()
+
+        session_id = id(mock_session)
+        middleware._active_sessions.add(session_id)
+
+        # Run ping loop for a short time then cancel
+        with anyio.move_on_after(0.35):
+            await middleware._ping_loop(mock_session, session_id)
+
+        # Should have sent at least 2 pings in 350ms with 50ms interval
+        assert mock_session.send_ping.call_count >= 2
+
+    async def test_ping_loop_cleans_up_on_cancellation(self):
+        """Test that session is removed from active sessions on cancellation."""
+        middleware = PingMiddleware(interval_ms=50)
+
+        mock_session = MagicMock()
+        mock_session.send_ping = AsyncMock()
+
+        session_id = 12345
+        middleware._active_sessions.add(session_id)
+
+        # Run and cancel the ping loop
+        with anyio.move_on_after(0.1):
+            await middleware._ping_loop(mock_session, session_id)
+
+        # Session should be cleaned up after cancellation
+        assert session_id not in middleware._active_sessions
+
+
+class TestPingMiddlewareIntegration:
+    """Integration tests for PingMiddleware with real FastMCP server."""
+
+    async def test_ping_middleware_registers_session(self):
+        """Test that PingMiddleware registers sessions on first request."""
+        mcp = FastMCP("PingTestServer")
+        middleware = PingMiddleware(interval_ms=50)
+        mcp.add_middleware(middleware)
+
+        @mcp.tool
+        def hello() -> str:
+            return "Hello!"
+
+        assert len(middleware._active_sessions) == 0
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("hello")
+            assert result.content[0].text == "Hello!"
+
+            # Should have registered the session
+            assert len(middleware._active_sessions) == 1
+
+            # Make another request - should not add duplicate
+            await client.call_tool("hello")
+            assert len(middleware._active_sessions) == 1
+
+    async def test_ping_task_cancelled_on_disconnect(self):
+        """Test that ping task is properly cancelled when client disconnects."""
+        mcp = FastMCP("PingTestServer")
+        middleware = PingMiddleware(interval_ms=50)
+        mcp.add_middleware(middleware)
+
+        @mcp.tool
+        def hello() -> str:
+            return "Hello!"
+
+        async with Client(mcp) as client:
+            await client.call_tool("hello")
+            # Should have one active session
+            assert len(middleware._active_sessions) == 1
+
+        # After disconnect, give a moment for cleanup
+        await anyio.sleep(0.01)
+
+        # Session should be cleaned up
+        assert len(middleware._active_sessions) == 0
diff --git a/tests/server/middleware/test_rate_limiting.py b/tests/server/middleware/test_rate_limiting.py
new file mode 100644
index 0000000..4ae5ae1
--- /dev/null
+++ b/tests/server/middleware/test_rate_limiting.py
@@ -0,0 +1,555 @@
+"""Tests for rate limiting middleware."""
+
+import asyncio
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from mcp import MCPError
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.middleware.middleware import MiddlewareContext
+from fastmcp.server.middleware.rate_limiting import (
+    RateLimitError,
+    RateLimitingMiddleware,
+    SlidingWindowRateLimiter,
+    SlidingWindowRateLimitingMiddleware,
+    TokenBucketRateLimiter,
+)
+
+
+@pytest.fixture
+def mock_context():
+    """Create a mock middleware context."""
+    context = MagicMock(spec=MiddlewareContext)
+    context.method = "test_method"
+    return context
+
+
+@pytest.fixture
+def mock_call_next():
+    """Create a mock call_next function."""
+    return AsyncMock(return_value="test_result")
+
+
+class TestTokenBucketRateLimiter:
+    """Test token bucket rate limiter."""
+
+    def test_init(self):
+        """Test initialization."""
+        limiter = TokenBucketRateLimiter(capacity=10, refill_rate=5.0)
+        assert limiter.capacity == 10
+        assert limiter.refill_rate == 5.0
+        assert limiter.tokens == 10
+
+    async def test_consume_success(self):
+        """Test successful token consumption."""
+        limiter = TokenBucketRateLimiter(capacity=10, refill_rate=5.0)
+
+        # Should be able to consume tokens initially
+        assert await limiter.consume(5) is True
+        assert await limiter.consume(3) is True
+
+    async def test_consume_failure(self):
+        """Test failed token consumption."""
+        limiter = TokenBucketRateLimiter(capacity=5, refill_rate=1.0)
+
+        # Consume all tokens
+        assert await limiter.consume(5) is True
+
+        # Should fail to consume more
+        assert await limiter.consume(1) is False
+
+    async def test_refill(self):
+        """Test token refill over time."""
+        limiter = TokenBucketRateLimiter(
+            capacity=10, refill_rate=10.0
+        )  # 10 tokens per second
+
+        # Consume all tokens
+        assert await limiter.consume(10) is True
+        assert await limiter.consume(1) is False
+
+        # Wait for refill (0.2 seconds = 2 tokens at 10/sec)
+        await asyncio.sleep(0.2)
+        assert await limiter.consume(2) is True
+
+    async def test_denied_consumes_do_not_freeze_clock(self):
+        """Regression for #4056: a client that retries quickly after being
+        denied must not be able to bypass the configured refill rate.
+
+        last_refill must advance on every consume() call (success or failure).
+        If it only advanced on success, the elapsed window would be re-counted
+        on each retry, letting a client refill faster than `refill_rate`.
+        """
+        limiter = TokenBucketRateLimiter(capacity=10, refill_rate=10.0)
+
+        # Drain the bucket.
+        assert await limiter.consume(10) is True
+
+        # Hammer with denied requests over ~0.2s. With the correct
+        # implementation, last_refill advances on each call, so total
+        # accumulated tokens after 0.2s is ~2 (10/s * 0.2s).
+        for _ in range(20):
+            await limiter.consume(1)
+            await asyncio.sleep(0.01)
+
+        # We should NOT be able to consume more than the configured rate
+        # would allow over the elapsed window. Allow a small slack for
+        # timing jitter, but stay well below `capacity`.
+        assert await limiter.consume(5) is False, (
+            "denied retries should not silently accrue extra tokens"
+        )
+
+
+class TestSlidingWindowRateLimiter:
+    """Test sliding window rate limiter."""
+
+    def test_init(self):
+        """Test initialization."""
+        limiter = SlidingWindowRateLimiter(max_requests=10, window_seconds=60)
+        assert limiter.max_requests == 10
+        assert limiter.window_seconds == 60
+        assert len(limiter.requests) == 0
+
+    async def test_is_allowed_success(self):
+        """Test allowing requests within limit."""
+        limiter = SlidingWindowRateLimiter(max_requests=3, window_seconds=60)
+
+        # Should allow requests up to the limit
+        assert await limiter.is_allowed() is True
+        assert await limiter.is_allowed() is True
+        assert await limiter.is_allowed() is True
+
+    async def test_is_allowed_failure(self):
+        """Test rejecting requests over limit."""
+        limiter = SlidingWindowRateLimiter(max_requests=2, window_seconds=60)
+
+        # Should allow up to limit
+        assert await limiter.is_allowed() is True
+        assert await limiter.is_allowed() is True
+
+        # Should reject over limit
+        assert await limiter.is_allowed() is False
+
+    async def test_sliding_window(self):
+        """Test sliding window behavior."""
+        limiter = SlidingWindowRateLimiter(max_requests=2, window_seconds=1)
+
+        # Use up requests
+        assert await limiter.is_allowed() is True
+        assert await limiter.is_allowed() is True
+        assert await limiter.is_allowed() is False
+
+        # Wait for window to pass
+        await asyncio.sleep(1.1)
+
+        # Should be able to make requests again
+        assert await limiter.is_allowed() is True
+
+
+class TestRateLimitingMiddleware:
+    """Test rate limiting middleware."""
+
+    def test_init_default(self):
+        """Test default initialization."""
+        middleware = RateLimitingMiddleware()
+        assert middleware.max_requests_per_second == 10.0
+        assert middleware.burst_capacity == 20
+        assert middleware.get_client_id is None
+        assert middleware.global_limit is False
+
+    def test_init_custom(self):
+        """Test custom initialization."""
+
+        def get_client_id(ctx):
+            return "test_client"
+
+        middleware = RateLimitingMiddleware(
+            max_requests_per_second=5.0,
+            burst_capacity=10,
+            get_client_id=get_client_id,
+            global_limit=True,
+        )
+        assert middleware.max_requests_per_second == 5.0
+        assert middleware.burst_capacity == 10
+        assert middleware.get_client_id is get_client_id
+        assert middleware.global_limit is True
+
+    async def test_get_client_identifier_default(self, mock_context):
+        """Test default client identifier."""
+        middleware = RateLimitingMiddleware()
+        assert await middleware._get_client_identifier(mock_context) == "global"
+
+    async def test_get_client_identifier_custom(self, mock_context):
+        """Test custom client identifier."""
+
+        def get_client_id(ctx):
+            return "custom_client"
+
+        middleware = RateLimitingMiddleware(get_client_id=get_client_id)
+        assert await middleware._get_client_identifier(mock_context) == "custom_client"
+
+    async def test_get_client_identifier_async_custom(self, mock_context):
+        """Test custom async client identifier."""
+
+        async def get_client_id(ctx):
+            return "async_client"
+
+        middleware = RateLimitingMiddleware(get_client_id=get_client_id)
+        assert await middleware._get_client_identifier(mock_context) == "async_client"
+
+    async def test_on_request_success(self, mock_context, mock_call_next):
+        """Test successful request within rate limit."""
+        middleware = RateLimitingMiddleware(max_requests_per_second=100.0)  # High limit
+
+        result = await middleware.on_request(mock_context, mock_call_next)
+
+        assert result == "test_result"
+        assert mock_call_next.called
+
+    async def test_on_request_rate_limited(self, mock_context, mock_call_next):
+        """Test request rejection due to rate limiting."""
+        middleware = RateLimitingMiddleware(
+            max_requests_per_second=1.0, burst_capacity=1
+        )
+
+        # First request should succeed
+        await middleware.on_request(mock_context, mock_call_next)
+
+        # Second request should be rate limited
+        with pytest.raises(RateLimitError, match="Rate limit exceeded"):
+            await middleware.on_request(mock_context, mock_call_next)
+
+    async def test_global_rate_limiting(self, mock_context, mock_call_next):
+        """Test global rate limiting."""
+        middleware = RateLimitingMiddleware(
+            max_requests_per_second=1.0, burst_capacity=1, global_limit=True
+        )
+
+        # First request should succeed
+        await middleware.on_request(mock_context, mock_call_next)
+
+        # Second request should be rate limited
+        with pytest.raises(RateLimitError, match="Global rate limit exceeded"):
+            await middleware.on_request(mock_context, mock_call_next)
+
+    async def test_on_request_async_get_client_id(self, mock_context, mock_call_next):
+        """Test per-client rate limiting with an async get_client_id."""
+
+        async def get_client_id(ctx):
+            return "async_client"
+
+        middleware = RateLimitingMiddleware(
+            max_requests_per_second=1.0, burst_capacity=1, get_client_id=get_client_id
+        )
+
+        # First request should succeed
+        await middleware.on_request(mock_context, mock_call_next)
+
+        # Second request should be rate limited for the async-resolved client
+        with pytest.raises(
+            RateLimitError, match="Rate limit exceeded for client: async_client"
+        ):
+            await middleware.on_request(mock_context, mock_call_next)
+
+
+class TestSlidingWindowRateLimitingMiddleware:
+    """Test sliding window rate limiting middleware."""
+
+    def test_init_default(self):
+        """Test default initialization."""
+        middleware = SlidingWindowRateLimitingMiddleware(max_requests=100)
+        assert middleware.max_requests == 100
+        assert middleware.window_seconds == 60
+        assert middleware.get_client_id is None
+
+    def test_init_custom(self):
+        """Test custom initialization."""
+
+        def get_client_id(ctx):
+            return "test_client"
+
+        middleware = SlidingWindowRateLimitingMiddleware(
+            max_requests=50, window_minutes=5, get_client_id=get_client_id
+        )
+        assert middleware.max_requests == 50
+        assert middleware.window_seconds == 300  # 5 minutes
+        assert middleware.get_client_id is get_client_id
+
+    async def test_on_request_success(self, mock_context, mock_call_next):
+        """Test successful request within rate limit."""
+        middleware = SlidingWindowRateLimitingMiddleware(max_requests=100)
+
+        result = await middleware.on_request(mock_context, mock_call_next)
+
+        assert result == "test_result"
+        assert mock_call_next.called
+
+    async def test_on_request_rate_limited(self, mock_context, mock_call_next):
+        """Test request rejection due to rate limiting."""
+        middleware = SlidingWindowRateLimitingMiddleware(max_requests=1)
+
+        # First request should succeed
+        await middleware.on_request(mock_context, mock_call_next)
+
+        # Second request should be rate limited
+        with pytest.raises(RateLimitError, match="Rate limit exceeded"):
+            await middleware.on_request(mock_context, mock_call_next)
+
+    async def test_on_request_async_get_client_id(self, mock_context, mock_call_next):
+        """Test sliding window rate limiting with an async get_client_id."""
+
+        async def get_client_id(ctx):
+            return "async_client"
+
+        middleware = SlidingWindowRateLimitingMiddleware(
+            max_requests=1, get_client_id=get_client_id
+        )
+
+        # First request should succeed
+        await middleware.on_request(mock_context, mock_call_next)
+
+        # Second request should be rate limited for the async-resolved client
+        with pytest.raises(RateLimitError, match="client: async_client"):
+            await middleware.on_request(mock_context, mock_call_next)
+
+
+class TestRateLimitError:
+    """Test rate limit error."""
+
+    def test_init_default(self):
+        """Test default initialization."""
+        error = RateLimitError()
+        assert error.error.code == -32000
+        assert error.error.message == "Rate limit exceeded"
+
+    def test_init_custom(self):
+        """Test custom initialization."""
+        error = RateLimitError("Custom message")
+        assert error.error.code == -32000
+        assert error.error.message == "Custom message"
+
+
+@pytest.fixture
+def rate_limit_server():
+    """Create a FastMCP server specifically for rate limiting tests."""
+    mcp = FastMCP("RateLimitTestServer")
+
+    @mcp.tool
+    def quick_action(message: str) -> str:
+        """A quick action for testing rate limits."""
+        return f"Processed: {message}"
+
+    @mcp.tool
+    def batch_process(items: list[str]) -> str:
+        """Process multiple items."""
+        return f"Processed {len(items)} items"
+
+    @mcp.tool
+    def heavy_computation() -> str:
+        """A heavy computation that might need rate limiting."""
+        # Simulate some work
+        import time
+
+        time.sleep(0.01)  # Very short delay
+        return "Heavy computation complete"
+
+    return mcp
+
+
+class TestRateLimitingMiddlewareIntegration:
+    """Integration tests for rate limiting middleware with real FastMCP server."""
+
+    async def test_rate_limiting_allows_normal_usage(self, rate_limit_server):
+        """Test that normal usage patterns are allowed through rate limiting."""
+        # Generous rate limit
+        rate_limit_server.add_middleware(
+            RateLimitingMiddleware(max_requests_per_second=50.0, burst_capacity=10)
+        )
+
+        async with Client(rate_limit_server) as client:
+            # Normal usage should be fine
+            for i in range(5):
+                result = await client.call_tool(
+                    "quick_action", {"message": f"task_{i}"}
+                )
+                assert f"Processed: task_{i}" in str(result)
+
+    async def test_rate_limiting_blocks_rapid_requests(self, rate_limit_server):
+        """Test that rate limiting blocks rapid successive requests."""
+        # Use a generous burst but near-zero refill rate so tokens never
+        # replenish.  The MCP SDK sends internal messages (initialize,
+        # notifications, list_tools for validation) whose exact count
+        # varies, so we give enough burst for init + several calls, then
+        # keep firing until we hit the limit.
+        rate_limit_server.add_middleware(
+            RateLimitingMiddleware(max_requests_per_second=0.001, burst_capacity=20)
+        )
+
+        async with Client(rate_limit_server) as client:
+            # Fire enough calls to exhaust the burst.  With near-zero
+            # refill, we must eventually hit the limit.
+            hit_limit = False
+            for i in range(30):
+                try:
+                    await client.call_tool("quick_action", {"message": str(i)})
+                except MCPError as exc:
+                    assert "Rate limit exceeded" in str(exc)
+                    hit_limit = True
+                    break
+            assert hit_limit, "Rate limit was never triggered"
+
+    async def test_rate_limiting_with_concurrent_requests(self, rate_limit_server):
+        """Test rate limiting behavior with concurrent requests."""
+        rate_limit_server.add_middleware(
+            RateLimitingMiddleware(max_requests_per_second=15.0, burst_capacity=8)
+        )
+
+        async with Client(rate_limit_server) as client:
+            # Fire off many concurrent requests
+            tasks = []
+            for i in range(8):
+                task = asyncio.create_task(
+                    client.call_tool("quick_action", {"message": f"concurrent_{i}"})
+                )
+                tasks.append(task)
+
+            # Gather results, allowing exceptions
+            results = await asyncio.gather(*tasks, return_exceptions=True)
+
+            # With extra list_tools calls, the exact behavior is unpredictable
+            # Just verify that rate limiting is working (not all succeed)
+            successes = [r for r in results if not isinstance(r, Exception)]
+            failures = [r for r in results if isinstance(r, Exception)]
+
+            total_results = len(successes) + len(failures)
+            assert total_results == 8, f"Expected 8 results, got {total_results}"
+
+            # With the unpredictable list_tools calls, we just verify that the system
+            # is working (all requests should either succeed or fail with some exception)
+            assert 0 <= len(successes) <= 8, "Should have between 0-8 successes"
+            assert 0 <= len(failures) <= 8, "Should have between 0-8 failures"
+
+    async def test_sliding_window_rate_limiting(self, rate_limit_server):
+        """Test sliding window rate limiting implementation."""
+        # A tight window; the SDK's internal init/list_tools requests count
+        # against it too, so fire tool calls until the limit is hit rather than
+        # hard-coding the exact request count (which differs across SDK versions).
+        rate_limit_server.add_middleware(
+            SlidingWindowRateLimitingMiddleware(
+                max_requests=6,
+                window_minutes=1,
+            )
+        )
+
+        async with Client(rate_limit_server) as client:
+            hit_limit = False
+            for i in range(10):
+                try:
+                    await client.call_tool("quick_action", {"message": str(i)})
+                except MCPError as exc:
+                    assert "Rate limit exceeded" in str(exc)
+                    hit_limit = True
+                    break
+            assert hit_limit, "Rate limit was never triggered"
+
+    async def test_rate_limiting_with_different_operations(self, rate_limit_server):
+        """Test that rate limiting applies to all types of operations."""
+        rate_limit_server.add_middleware(
+            RateLimitingMiddleware(max_requests_per_second=0.001, burst_capacity=5)
+        )
+
+        async with Client(rate_limit_server) as client:
+            # Mix different operations; with near-zero refill the shared bucket
+            # is exhausted regardless of which operation trips it.
+            operations = [
+                ("quick_action", {"message": "test"}),
+                ("heavy_computation", {}),
+                ("batch_process", {"items": ["a", "b", "c"]}),
+                ("quick_action", {"message": "again"}),
+                ("heavy_computation", {}),
+                ("batch_process", {"items": ["x"]}),
+            ]
+            hit_limit = False
+            for name, args in operations:
+                try:
+                    await client.call_tool(name, args)
+                except MCPError as exc:
+                    assert "Rate limit exceeded" in str(exc)
+                    hit_limit = True
+                    break
+            assert hit_limit, "Rate limit was never triggered"
+
+    async def test_custom_client_identification(self, rate_limit_server):
+        """Test rate limiting with custom client identification."""
+
+        def get_client_id(context):
+            # In a real scenario, this might extract from headers or context
+            return "test_client_123"
+
+        rate_limit_server.add_middleware(
+            RateLimitingMiddleware(
+                max_requests_per_second=0.001,  # near-zero refill so tokens never replenish
+                burst_capacity=4,
+                get_client_id=get_client_id,
+            )
+        )
+
+        async with Client(rate_limit_server) as client:
+            # Fire calls until the per-client bucket is exhausted; the exact
+            # burst count depends on the SDK's internal request volume.
+            exc_message = None
+            for i in range(10):
+                try:
+                    await client.call_tool("quick_action", {"message": str(i)})
+                except MCPError as exc:
+                    exc_message = str(exc)
+                    break
+            assert exc_message is not None, "Rate limit was never triggered"
+            assert "Rate limit exceeded for client: test_client_123" in exc_message
+
+    async def test_global_rate_limiting(self, rate_limit_server):
+        """Test global rate limiting across all clients."""
+        middleware = RateLimitingMiddleware(
+            max_requests_per_second=0.001,
+            burst_capacity=1000,
+            global_limit=True,
+        )
+        rate_limit_server.add_middleware(middleware)
+
+        async with Client(rate_limit_server) as client:
+            await client.call_tool("quick_action", {"message": "1"})
+
+            middleware.global_limiter.tokens = 0
+
+            with pytest.raises(MCPError, match="Global rate limit exceeded"):
+                await client.call_tool("quick_action", {"message": "blocked"})
+
+    async def test_rate_limiting_recovery_over_time(self, rate_limit_server):
+        """Test that rate limiting allows requests again after time passes."""
+        rate_limit_server.add_middleware(
+            RateLimitingMiddleware(
+                max_requests_per_second=10.0,  # 10 per second = 1 every 100ms
+                burst_capacity=4,
+            )
+        )
+
+        async with Client(rate_limit_server) as client:
+            # Exhaust the burst; the exact number of internal requests before the
+            # limit trips varies across SDK versions, so fire until it blocks.
+            hit_limit = False
+            for i in range(10):
+                try:
+                    await client.call_tool("quick_action", {"message": str(i)})
+                except MCPError:
+                    hit_limit = True
+                    break
+            assert hit_limit, "Rate limit was never triggered"
+
+            # Wait for token bucket to refill (150ms should be enough for ~1.5 tokens)
+            await asyncio.sleep(0.15)
+
+            # Should be able to make another request
+            result = await client.call_tool("quick_action", {"message": "after_wait"})
+            assert "after_wait" in str(result)
diff --git a/tests/server/middleware/test_response_limiting.py b/tests/server/middleware/test_response_limiting.py
new file mode 100644
index 0000000..b1586a7
--- /dev/null
+++ b/tests/server/middleware/test_response_limiting.py
@@ -0,0 +1,181 @@
+"""Tests for ResponseLimitingMiddleware."""
+
+import pytest
+from mcp_types import ImageContent, TextContent
+from pydantic import BaseModel
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.middleware.response_limiting import ResponseLimitingMiddleware
+from fastmcp.tools.base import ToolResult
+
+
+# Regression test model for #3717
+class Answer(BaseModel):
+    text: str
+
+
+class TestResponseLimitingMiddleware:
+    """Tests for ResponseLimitingMiddleware."""
+
+    @pytest.fixture
+    def mcp_server(self) -> FastMCP:
+        """Create a basic MCP server for testing."""
+        return FastMCP("test-server")
+
+    async def test_response_under_limit_passes_unchanged(self, mcp_server: FastMCP):
+        """Test that responses under the limit pass through unchanged."""
+        mcp_server.add_middleware(ResponseLimitingMiddleware(max_size=1_000_000))
+
+        @mcp_server.tool()
+        def small_tool() -> ToolResult:
+            return ToolResult(content=[TextContent(type="text", text="hello world")])
+
+        async with Client(mcp_server) as client:
+            result = await client.call_tool("small_tool", {})
+            assert len(result.content) == 1
+            assert result.content[0].text == "hello world"
+
+    async def test_response_over_limit_is_truncated(self, mcp_server: FastMCP):
+        """Test that responses over the limit are truncated."""
+        mcp_server.add_middleware(ResponseLimitingMiddleware(max_size=500))
+
+        @mcp_server.tool()
+        def large_tool() -> ToolResult:
+            return ToolResult(content=[TextContent(type="text", text="x" * 10_000)])
+
+        async with Client(mcp_server) as client:
+            result = await client.call_tool("large_tool", {})
+            assert len(result.content) == 1
+            assert "[Response truncated due to size limit]" in result.content[0].text
+            # Verify truncated result fits within limit
+            assert len(result.content[0].text.encode("utf-8")) < 500
+
+    async def test_tool_filtering(self, mcp_server: FastMCP):
+        """Test that tool filtering only applies to specified tools."""
+        mcp_server.add_middleware(
+            ResponseLimitingMiddleware(max_size=100, tools=["limited_tool"])
+        )
+
+        @mcp_server.tool()
+        def limited_tool() -> ToolResult:
+            return ToolResult(content=[TextContent(type="text", text="x" * 10_000)])
+
+        @mcp_server.tool()
+        def unlimited_tool() -> ToolResult:
+            return ToolResult(content=[TextContent(type="text", text="y" * 10_000)])
+
+        async with Client(mcp_server) as client:
+            # Limited tool should be truncated
+            result = await client.call_tool("limited_tool", {})
+            assert "[Response truncated" in result.content[0].text
+
+            # Unlimited tool should pass through
+            result = await client.call_tool("unlimited_tool", {})
+            assert "y" * 100 in result.content[0].text
+
+    async def test_empty_tools_list_limits_nothing(self, mcp_server: FastMCP):
+        """Test that empty tools list means no tools are limited."""
+        mcp_server.add_middleware(ResponseLimitingMiddleware(max_size=100, tools=[]))
+
+        @mcp_server.tool()
+        def any_tool() -> ToolResult:
+            return ToolResult(content=[TextContent(type="text", text="x" * 10_000)])
+
+        async with Client(mcp_server) as client:
+            result = await client.call_tool("any_tool", {})
+            # Should NOT be truncated
+            assert "[Response truncated" not in result.content[0].text
+
+    async def test_custom_truncation_suffix(self, mcp_server: FastMCP):
+        """Test that custom truncation suffix is applied."""
+        mcp_server.add_middleware(
+            ResponseLimitingMiddleware(max_size=200, truncation_suffix="\n[CUT]")
+        )
+
+        @mcp_server.tool()
+        def large_tool() -> ToolResult:
+            return ToolResult(content=[TextContent(type="text", text="x" * 10_000)])
+
+        async with Client(mcp_server) as client:
+            result = await client.call_tool("large_tool", {})
+            assert "[CUT]" in result.content[0].text
+
+    async def test_multiple_text_blocks_combined(self, mcp_server: FastMCP):
+        """Test that multiple text blocks are combined when truncating."""
+        mcp_server.add_middleware(ResponseLimitingMiddleware(max_size=300))
+
+        @mcp_server.tool()
+        def multi_block() -> ToolResult:
+            return ToolResult(
+                content=[
+                    TextContent(type="text", text="First: " + "a" * 500),
+                    TextContent(type="text", text="Second: " + "b" * 500),
+                ]
+            )
+
+        async with Client(mcp_server) as client:
+            result = await client.call_tool("multi_block", {})
+            # Both blocks should be joined and truncated
+            assert len(result.content) == 1
+            assert "[Response truncated" in result.content[0].text
+
+    async def test_binary_only_content_serialized(self, mcp_server: FastMCP):
+        """Test that binary-only responses fall back to serialized content."""
+        mcp_server.add_middleware(ResponseLimitingMiddleware(max_size=200))
+
+        @mcp_server.tool()
+        def binary_tool() -> ToolResult:
+            return ToolResult(
+                content=[
+                    ImageContent(type="image", data="x" * 10_000, mime_type="image/png")
+                ]
+            )
+
+        async with Client(mcp_server) as client:
+            result = await client.call_tool("binary_tool", {})
+            # Should be truncated (using serialized fallback)
+            assert len(result.content) == 1
+            assert "[Response truncated" in result.content[0].text
+
+    async def test_default_max_size_is_1mb(self):
+        """Test that the default max size is 1MB."""
+        middleware = ResponseLimitingMiddleware()
+        assert middleware.max_size == 1_000_000
+
+    def test_invalid_max_size_raises(self):
+        """Test that zero or negative max_size raises ValueError."""
+        with pytest.raises(ValueError, match="max_size must be positive"):
+            ResponseLimitingMiddleware(max_size=0)
+        with pytest.raises(ValueError, match="max_size must be positive"):
+            ResponseLimitingMiddleware(max_size=-100)
+
+    async def test_truncation_does_not_break_output_schema_tools(
+        self, mcp_server: FastMCP
+    ):
+        """Truncating a tool with outputSchema must not cause validation errors.
+
+        Regression test for #3717: the MCP SDK rejects truncated results
+        from tools with outputSchema because structured_content is dropped.
+        We verify the server returns a successful (non-error) truncated result.
+        """
+        mcp_server.add_middleware(ResponseLimitingMiddleware(max_size=1_000))
+
+        @mcp_server.tool()
+        def big_answer() -> Answer:
+            return Answer(text="x" * 2_000)
+
+        result = await mcp_server.call_tool("big_answer", {})
+        first = result.content[0]
+        assert isinstance(first, TextContent)
+        assert "[Response truncated" in first.text
+
+    def test_utf8_truncation_preserves_characters(self):
+        """Test that UTF-8 truncation doesn't break multi-byte characters."""
+        middleware = ResponseLimitingMiddleware(max_size=100)
+        # Text with multi-byte characters (emoji)
+        text = "Hello 🌍 World 🎉 Test " * 100
+        result = middleware._truncate_to_result(text)
+        # Should not raise and should be valid UTF-8
+        content = result.content[0]
+        assert isinstance(content, TextContent)
+        content.text.encode("utf-8")
diff --git a/tests/server/middleware/test_timing.py b/tests/server/middleware/test_timing.py
new file mode 100644
index 0000000..f219698
--- /dev/null
+++ b/tests/server/middleware/test_timing.py
@@ -0,0 +1,305 @@
+"""Tests for timing middleware."""
+
+import asyncio
+import logging
+import time
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.middleware.middleware import MiddlewareContext
+from fastmcp.server.middleware.timing import DetailedTimingMiddleware, TimingMiddleware
+
+
+@pytest.fixture
+def mock_context():
+    """Create a mock middleware context."""
+    context = MagicMock(spec=MiddlewareContext)
+    context.method = "test_method"
+    return context
+
+
+@pytest.fixture
+def mock_call_next():
+    """Create a mock call_next function."""
+    return AsyncMock(return_value="test_result")
+
+
+class TestTimingMiddleware:
+    """Test timing middleware functionality."""
+
+    def test_init_default(self):
+        """Test default initialization."""
+        middleware = TimingMiddleware()
+        assert middleware.logger.name == "fastmcp.timing"
+        assert middleware.log_level == logging.INFO
+
+    def test_init_custom(self):
+        """Test custom initialization."""
+        logger = logging.getLogger("custom")
+        middleware = TimingMiddleware(logger=logger, log_level=logging.DEBUG)
+        assert middleware.logger is logger
+        assert middleware.log_level == logging.DEBUG
+
+    async def test_on_request_success(self, mock_context, mock_call_next, caplog):
+        """Test timing successful requests."""
+        middleware = TimingMiddleware()
+
+        result = await middleware.on_request(mock_context, mock_call_next)
+
+        assert result == "test_result"
+        assert mock_call_next.called
+        assert "Request test_method completed in" in caplog.text
+        assert "ms" in caplog.text
+
+    async def test_on_request_failure(self, mock_context, caplog):
+        """Test timing failed requests."""
+        middleware = TimingMiddleware()
+        mock_call_next = AsyncMock(side_effect=ValueError("test error"))
+
+        with pytest.raises(ValueError):
+            await middleware.on_request(mock_context, mock_call_next)
+
+        assert "Request test_method failed after" in caplog.text
+        assert "ms: test error" in caplog.text
+
+
+class TestDetailedTimingMiddleware:
+    """Test detailed timing middleware functionality."""
+
+    def test_init_default(self):
+        """Test default initialization."""
+        middleware = DetailedTimingMiddleware()
+        assert middleware.logger.name == "fastmcp.timing.detailed"
+        assert middleware.log_level == logging.INFO
+
+    async def test_on_call_tool(self, caplog):
+        """Test timing tool calls."""
+        middleware = DetailedTimingMiddleware()
+        context = MagicMock()
+        context.message.name = "test_tool"
+        mock_call_next = AsyncMock(return_value="tool_result")
+
+        result = await middleware.on_call_tool(context, mock_call_next)
+
+        assert result == "tool_result"
+        assert "Tool 'test_tool' completed in" in caplog.text
+
+    async def test_on_read_resource(self, caplog):
+        """Test timing resource reads."""
+        middleware = DetailedTimingMiddleware()
+        context = MagicMock()
+        context.message.uri = "test://resource"
+        mock_call_next = AsyncMock(return_value="resource_result")
+
+        result = await middleware.on_read_resource(context, mock_call_next)
+
+        assert result == "resource_result"
+        assert "Resource 'test://resource' completed in" in caplog.text
+
+    async def test_on_get_prompt(self, caplog):
+        """Test timing prompt retrieval."""
+        middleware = DetailedTimingMiddleware()
+        context = MagicMock()
+        context.message.name = "test_prompt"
+        mock_call_next = AsyncMock(return_value="prompt_result")
+
+        result = await middleware.on_get_prompt(context, mock_call_next)
+
+        assert result == "prompt_result"
+        assert "Prompt 'test_prompt' completed in" in caplog.text
+
+    async def test_on_list_tools(self, caplog):
+        """Test timing tool listing."""
+        middleware = DetailedTimingMiddleware()
+        context = MagicMock()
+        mock_call_next = AsyncMock(return_value="tools_result")
+
+        result = await middleware.on_list_tools(context, mock_call_next)
+
+        assert result == "tools_result"
+        assert "List tools completed in" in caplog.text
+
+    async def test_operation_failure(self, caplog):
+        """Test timing failed operations."""
+        middleware = DetailedTimingMiddleware()
+        context = MagicMock()
+        context.message.name = "failing_tool"
+        mock_call_next = AsyncMock(side_effect=RuntimeError("operation failed"))
+
+        with pytest.raises(RuntimeError):
+            await middleware.on_call_tool(context, mock_call_next)
+
+        assert "Tool 'failing_tool' failed after" in caplog.text
+        assert "ms: operation failed" in caplog.text
+
+
+@pytest.fixture
+def timing_server():
+    """Create a FastMCP server specifically for timing middleware tests."""
+    mcp = FastMCP("TimingTestServer")
+
+    @mcp.tool
+    def instant_task() -> str:
+        """A task that completes instantly."""
+        return "Done instantly"
+
+    @mcp.tool
+    def short_task() -> str:
+        """A task that takes 0.01 seconds."""
+        time.sleep(0.01)
+        return "Done after 0.01 seconds"
+
+    @mcp.tool
+    def medium_task() -> str:
+        """A task that takes 0.02 seconds."""
+        time.sleep(0.02)
+        return "Done after 0.02 seconds"
+
+    @mcp.tool
+    def failing_task() -> str:
+        """A task that always fails."""
+        raise ValueError("Task failed as expected")
+
+    @mcp.resource("timer://test")
+    def test_resource() -> str:
+        """A resource that takes time to read."""
+        time.sleep(0.005)
+        return "Resource content after 0.005 seconds"
+
+    @mcp.prompt
+    def test_prompt() -> str:
+        """A prompt that takes time to generate."""
+        time.sleep(0.008)
+        return "Prompt content after 0.008 seconds"
+
+    return mcp
+
+
+class TestTimingMiddlewareIntegration:
+    """Integration tests for timing middleware with real FastMCP server."""
+
+    async def test_timing_middleware_measures_tool_execution(
+        self, timing_server, caplog
+    ):
+        """Test that timing middleware accurately measures tool execution times."""
+        timing_server.add_middleware(TimingMiddleware())
+
+        async with Client(timing_server) as client:
+            # Test instant task
+            await client.call_tool("instant_task")
+
+            # Test short task (0.1s)
+            await client.call_tool("short_task")
+
+            # Test medium task (0.15s)
+            await client.call_tool("medium_task")
+
+        log_text = caplog.text
+
+        # Should have timing logs for all three calls (plus any extra list_tools calls)
+        timing_logs = [
+            line
+            for line in log_text.split("\n")
+            if "completed in" in line and "ms" in line
+        ]
+        assert (
+            len(timing_logs) >= 3
+        )  # At least 3 tool calls, may have additional list_tools calls
+
+        # Verify that longer tasks show longer timing (roughly)
+        assert "tools/call completed in" in log_text
+        assert "ms" in log_text
+
+    async def test_timing_middleware_handles_failures(self, timing_server, caplog):
+        """Test that timing middleware measures time even for failed operations."""
+        timing_server.add_middleware(TimingMiddleware())
+
+        async with Client(timing_server) as client:
+            # This should fail but still be timed
+            with pytest.raises(Exception):
+                await client.call_tool("failing_task")
+
+        # Should log the failure with timing
+        assert "tools/call failed after" in caplog.text
+        assert "ms:" in caplog.text
+
+    async def test_detailed_timing_middleware_per_operation(
+        self, timing_server, caplog
+    ):
+        """Test that detailed timing middleware provides operation-specific timing."""
+        timing_server.add_middleware(DetailedTimingMiddleware())
+
+        async with Client(timing_server) as client:
+            # Test tool call
+            await client.call_tool("short_task")
+
+            # Test resource read
+            await client.read_resource("timer://test")
+
+            # Test prompt
+            await client.get_prompt("test_prompt")
+
+            # Test listing operations
+            await client.list_tools()
+            await client.list_resources()
+            await client.list_prompts()
+
+        log_text = caplog.text
+
+        # Should have specific timing logs for each operation type
+        assert "Tool 'short_task' completed in" in log_text
+        assert "Resource 'timer://test' completed in" in log_text
+        assert "Prompt 'test_prompt' completed in" in log_text
+        assert "List tools completed in" in log_text
+        assert "List resources completed in" in log_text
+        assert "List prompts completed in" in log_text
+
+    async def test_timing_middleware_concurrent_operations(self, timing_server, caplog):
+        """Test timing middleware with concurrent operations."""
+        timing_server.add_middleware(TimingMiddleware())
+
+        async with Client(timing_server) as client:
+            # Run multiple operations concurrently
+            tasks = [
+                client.call_tool("instant_task"),
+                client.call_tool("short_task"),
+                client.call_tool("instant_task"),
+            ]
+
+            await asyncio.gather(*tasks)
+
+        log_text = caplog.text
+
+        # Should have timing logs for all concurrent operations (including extra list_tools calls)
+        timing_logs = [line for line in log_text.split("\n") if "completed in" in line]
+        assert (
+            len(timing_logs) >= 3
+        )  # At least 3 tool calls, may have additional list_tools calls
+
+    async def test_timing_middleware_custom_logger(self, timing_server, caplog):
+        """Test timing middleware with custom logger configuration."""
+        import io
+        import logging
+
+        # Create a custom logger that writes to a string buffer
+        log_buffer = io.StringIO()
+        handler = logging.StreamHandler(log_buffer)
+        custom_logger = logging.getLogger("custom_timing")
+        custom_logger.addHandler(handler)
+        custom_logger.setLevel(logging.DEBUG)
+
+        # Use custom logger and log level
+        timing_server.add_middleware(
+            TimingMiddleware(logger=custom_logger, log_level=logging.DEBUG)
+        )
+
+        async with Client(timing_server) as client:
+            await client.call_tool("instant_task")
+
+        # Check that our custom logger was used
+        log_output = log_buffer.getvalue()
+        assert "tools/call completed in" in log_output
+        assert "ms" in log_output
diff --git a/tests/server/middleware/test_tool_injection.py b/tests/server/middleware/test_tool_injection.py
new file mode 100644
index 0000000..9837364
--- /dev/null
+++ b/tests/server/middleware/test_tool_injection.py
@@ -0,0 +1,276 @@
+"""Tests for tool injection middleware."""
+
+import math
+
+import pytest
+from inline_snapshot import snapshot
+from mcp_types import Tool as SDKTool
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.client import CallToolResult
+from fastmcp.client.transports import FastMCPTransport
+from fastmcp.server.middleware.tool_injection import (
+    ToolInjectionMiddleware,
+)
+from fastmcp.tools.base import Tool
+from fastmcp.tools.function_tool import FunctionTool
+
+
+def multiply_fn(a: int, b: int) -> int:
+    """Multiply two numbers."""
+    return a * b
+
+
+def divide_fn(a: int, b: int) -> float:
+    """Divide two numbers."""
+    if b == 0:
+        raise ValueError("Cannot divide by zero")
+    return a / b
+
+
+multiply_tool = Tool.from_function(fn=multiply_fn, name="multiply", tags={"math"})
+divide_tool = Tool.from_function(fn=divide_fn, name="divide", tags={"math"})
+
+
+class TestToolInjectionMiddleware:
+    """Tests with real FastMCP server."""
+
+    @pytest.fixture
+    def base_server(self):
+        """Create a base FastMCP server."""
+        mcp = FastMCP("BaseServer")
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            """Add two numbers."""
+            return a + b
+
+        @mcp.tool
+        def subtract(a: int, b: int) -> int:
+            """Subtract two numbers."""
+            return a - b
+
+        return mcp
+
+    async def test_list_tools_includes_injected_tools(self, base_server: FastMCP):
+        """Test that list_tools returns both base and injected tools."""
+
+        injected_tools: list[FunctionTool] = [
+            multiply_tool,
+            divide_tool,
+        ]
+        middleware: ToolInjectionMiddleware = ToolInjectionMiddleware(
+            tools=injected_tools
+        )
+        base_server.add_middleware(middleware)
+
+        async with Client[FastMCPTransport](base_server) as client:
+            tools: list[SDKTool] = await client.list_tools()
+
+        # Should have all tools: multiply, divide, add, subtract
+        assert len(tools) == 4
+        tool_names: list[str] = [tool.name for tool in tools]
+        assert "multiply" in tool_names
+        assert "divide" in tool_names
+        assert "add" in tool_names
+        assert "subtract" in tool_names
+
+    async def test_call_injected_tool(self, base_server: FastMCP):
+        """Test that injected tools can be called successfully."""
+
+        injected_tools: list[FunctionTool] = [multiply_tool]
+        middleware: ToolInjectionMiddleware = ToolInjectionMiddleware(
+            tools=injected_tools
+        )
+        base_server.add_middleware(middleware)
+
+        async with Client[FastMCPTransport](base_server) as client:
+            result: CallToolResult = await client.call_tool(
+                name="multiply", arguments={"a": 7, "b": 6}
+            )
+
+        assert result.structured_content is not None
+        assert isinstance(result.structured_content, dict)
+        assert result.structured_content["result"] == 42
+
+    async def test_call_base_tool_still_works(self, base_server: FastMCP):
+        """Test that base server tools still work after injecting tools."""
+
+        injected_tools: list[FunctionTool] = [multiply_tool]
+        middleware: ToolInjectionMiddleware = ToolInjectionMiddleware(
+            tools=injected_tools
+        )
+        base_server.add_middleware(middleware)
+
+        async with Client[FastMCPTransport](base_server) as client:
+            result: CallToolResult = await client.call_tool(
+                name="add", arguments={"a": 10, "b": 5}
+            )
+
+        assert result.structured_content is not None
+        assert isinstance(result.structured_content, dict)
+        assert result.structured_content["result"] == 15
+
+    async def test_injected_tool_error_handling(self, base_server: FastMCP):
+        """Test that errors in injected tools are properly handled."""
+
+        injected_tools: list[FunctionTool] = [divide_tool]
+        middleware: ToolInjectionMiddleware = ToolInjectionMiddleware(
+            tools=injected_tools
+        )
+        base_server.add_middleware(middleware)
+
+        async with Client[FastMCPTransport](base_server) as client:
+            with pytest.raises(Exception, match="Cannot divide by zero"):
+                _ = await client.call_tool(name="divide", arguments={"a": 10, "b": 0})
+
+    async def test_multiple_tool_injections(self, base_server: FastMCP):
+        """Test multiple tool injection middlewares can be stacked."""
+
+        def power(a: int, b: int) -> int:
+            """Raise a to the power of b."""
+            return int(math.pow(float(a), float(b)))
+
+        def modulo(a: int, b: int) -> int:
+            """Calculate a modulo b."""
+            return a % b
+
+        middleware1 = ToolInjectionMiddleware(
+            tools=[Tool.from_function(fn=power, name="power")]
+        )
+        middleware2 = ToolInjectionMiddleware(
+            tools=[Tool.from_function(fn=modulo, name="modulo")]
+        )
+
+        base_server.add_middleware(middleware1)
+        base_server.add_middleware(middleware2)
+
+        async with Client(base_server) as client:
+            tools = await client.list_tools()
+
+        # Should have all tools
+        assert len(tools) == 4
+        tool_names = [tool.name for tool in tools]
+        assert "power" in tool_names
+        assert "modulo" in tool_names
+        assert "add" in tool_names
+        assert "subtract" in tool_names
+
+        # Test that both injected tools work
+        async with Client(base_server) as client:
+            power_result = await client.call_tool("power", {"a": 2, "b": 3})
+            assert power_result.structured_content is not None
+            assert isinstance(power_result.structured_content, dict)
+            assert power_result.structured_content["result"] == 8
+
+            modulo_result = await client.call_tool("modulo", {"a": 10, "b": 3})
+            assert modulo_result.structured_content is not None
+            assert isinstance(modulo_result.structured_content, dict)
+            assert modulo_result.structured_content["result"] == 1
+
+    async def test_injected_tool_with_complex_return_type(self, base_server: FastMCP):
+        """Test injected tools with complex return types."""
+
+        def calculate_stats(numbers: list[int]) -> dict[str, int | float]:
+            """Calculate statistics for a list of numbers."""
+            return {
+                "sum": sum(numbers),
+                "average": sum(numbers) / len(numbers),
+                "min": min(numbers),
+                "max": max(numbers),
+                "count": len(numbers),
+            }
+
+        middleware = ToolInjectionMiddleware(
+            tools=[Tool.from_function(fn=calculate_stats, name="calculate_stats")]
+        )
+        base_server.add_middleware(middleware)
+
+        async with Client(base_server) as client:
+            result = await client.call_tool(
+                "calculate_stats", {"numbers": [1, 2, 3, 4, 5]}
+            )
+
+        assert result.structured_content is not None
+
+        assert isinstance(result.structured_content, dict)
+
+        assert result.structured_content == snapshot(
+            {"sum": 15, "average": 3.0, "min": 1, "max": 5, "count": 5}
+        )
+
+    async def test_injected_tool_metadata_preserved(self, base_server: FastMCP):
+        """Test that injected tool metadata is preserved."""
+
+        def multiply(a: int, b: int) -> int:
+            """Multiply two numbers."""
+            return a * b
+
+        injected_tools = [Tool.from_function(fn=multiply, name="multiply")]
+        middleware = ToolInjectionMiddleware(tools=injected_tools)
+        base_server.add_middleware(middleware)
+
+        async with Client(base_server) as client:
+            tools = await client.list_tools()
+
+        multiply_tool = next(t for t in tools if t.name == "multiply")
+        assert multiply_tool.description == "Multiply two numbers."
+        assert "a" in multiply_tool.input_schema["properties"]
+        assert "b" in multiply_tool.input_schema["properties"]
+
+    async def test_injected_tool_does_not_conflict_with_base_tool(
+        self, base_server: FastMCP
+    ):
+        """Test that injected tools with same name as base tools are called correctly."""
+
+        def add(a: int, b: int) -> int:
+            """Injected add that multiplies instead."""
+            return a * b
+
+        middleware: ToolInjectionMiddleware = ToolInjectionMiddleware(
+            tools=[Tool.from_function(fn=add, name="add")]
+        )
+        base_server.add_middleware(middleware)
+
+        async with Client[FastMCPTransport](base_server) as client:
+            result: CallToolResult = await client.call_tool(
+                name="add", arguments={"a": 5, "b": 3}
+            )
+
+        # Should use the injected tool (multiply behavior)
+        assert result.structured_content is not None
+        assert result.structured_content["result"] == 15
+
+    async def test_injected_tool_bypass_filtering(self, base_server: FastMCP):
+        """Test that injected tools bypass filtering."""
+        middleware: ToolInjectionMiddleware = ToolInjectionMiddleware(
+            tools=[multiply_tool]
+        )
+        base_server.add_middleware(middleware)
+        base_server.disable(tags={"math"})
+
+        async with Client[FastMCPTransport](base_server) as client:
+            tools: list[SDKTool] = await client.list_tools()
+            tool_names: list[str] = [tool.name for tool in tools]
+            assert "multiply" in tool_names
+
+    async def test_empty_tool_injection(self, base_server: FastMCP):
+        """Test that middleware with no tools doesn't affect behavior."""
+        middleware: ToolInjectionMiddleware = ToolInjectionMiddleware(tools=[])
+        base_server.add_middleware(middleware)
+
+        async with Client[FastMCPTransport](base_server) as client:
+            tools: list[SDKTool] = await client.list_tools()
+            result: CallToolResult = await client.call_tool(
+                name="add", arguments={"a": 3, "b": 4}
+            )
+
+        # Should only have the base tools
+        assert len(tools) == 2
+        tool_names: list[str] = [tool.name for tool in tools]
+        assert "add" in tool_names
+        assert "subtract" in tool_names
+        assert result.structured_content is not None
+        assert isinstance(result.structured_content, dict)
+        assert result.structured_content["result"] == 7
diff --git a/tests/server/mount/__init__.py b/tests/server/mount/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/server/mount/test_advanced.py b/tests/server/mount/test_advanced.py
new file mode 100644
index 0000000..5daeb65
--- /dev/null
+++ b/tests/server/mount/test_advanced.py
@@ -0,0 +1,711 @@
+"""Advanced mounting scenarios."""
+
+import pytest
+from mcp_types import TextContent
+from starlette.routing import Route
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.providers import FastMCPProvider
+from fastmcp.server.providers.wrapped_provider import _WrappedProvider
+
+
+class TestDynamicChanges:
+    """Test that changes to mounted servers are reflected dynamically."""
+
+    async def test_adding_tool_after_mounting(self):
+        """Test that tools added after mounting are accessible."""
+        main_app = FastMCP("MainApp")
+        sub_app = FastMCP("SubApp")
+
+        # Mount the sub-app before adding any tools
+        main_app.mount(sub_app, "sub")
+
+        # Initially, there should be no tools from sub_app
+        tools = await main_app.list_tools()
+        assert not any(t.name.startswith("sub_") for t in tools)
+
+        # Add a tool to the sub-app after mounting
+        @sub_app.tool
+        def dynamic_tool() -> str:
+            return "Added after mounting"
+
+        # The tool should be accessible through the main app
+        tools = await main_app.list_tools()
+        assert any(t.name == "sub_dynamic_tool" for t in tools)
+
+        # Call the dynamically added tool
+        result = await main_app.call_tool("sub_dynamic_tool", {})
+        assert result.structured_content == {"result": "Added after mounting"}
+
+    async def test_removing_tool_after_mounting(self):
+        """Test that tools removed from mounted servers are no longer accessible."""
+        main_app = FastMCP("MainApp")
+        sub_app = FastMCP("SubApp")
+
+        @sub_app.tool
+        def temp_tool() -> str:
+            return "Temporary tool"
+
+        # Mount the sub-app
+        main_app.mount(sub_app, "sub")
+
+        # Initially, the tool should be accessible
+        tools = await main_app.list_tools()
+        assert any(t.name == "sub_temp_tool" for t in tools)
+
+        # Remove the tool from sub_app
+        sub_app.local_provider.remove_tool("temp_tool")
+
+        # The tool should no longer be accessible
+        tools = await main_app.list_tools()
+        assert not any(t.name == "sub_temp_tool" for t in tools)
+
+
+class TestCustomRouteForwarding:
+    """Test that custom HTTP routes from mounted servers are forwarded."""
+
+    async def test_get_additional_http_routes_empty(self):
+        """Test _get_additional_http_routes returns empty list for server with no routes."""
+        server = FastMCP("TestServer")
+        routes = server._get_additional_http_routes()
+        assert routes == []
+
+    async def test_get_additional_http_routes_with_custom_route(self):
+        """Test _get_additional_http_routes returns server's own routes."""
+        server = FastMCP("TestServer")
+
+        @server.custom_route("/test", methods=["GET"])
+        async def test_route(request):
+            from starlette.responses import JSONResponse
+
+            return JSONResponse({"message": "test"})
+
+        routes = server._get_additional_http_routes()
+        assert len(routes) == 1
+        assert isinstance(routes[0], Route)
+        assert routes[0].path == "/test"
+
+    async def test_mounted_servers_tracking(self):
+        """Test that providers list tracks mounted servers correctly."""
+        from fastmcp.server.providers.local_provider import LocalProvider
+
+        main_server = FastMCP("MainServer")
+        sub_server1 = FastMCP("SubServer1")
+        sub_server2 = FastMCP("SubServer2")
+
+        @sub_server1.tool
+        def tool1() -> str:
+            return "1"
+
+        @sub_server2.tool
+        def tool2() -> str:
+            return "2"
+
+        # Initially only LocalProvider
+        assert len(main_server.providers) == 1
+        assert isinstance(main_server.providers[0], LocalProvider)
+
+        # Mount first server
+        main_server.mount(sub_server1, "sub1")
+        assert len(main_server.providers) == 2
+        # LocalProvider is at index 0, mounted provider (wrapped) at index 1
+        provider1 = main_server.providers[1]
+        assert isinstance(provider1, _WrappedProvider)
+        assert isinstance(provider1._inner, FastMCPProvider)
+        assert provider1._inner.server == sub_server1
+
+        # Mount second server
+        main_server.mount(sub_server2, "sub2")
+        assert len(main_server.providers) == 3
+        provider2 = main_server.providers[2]
+        assert isinstance(provider2, _WrappedProvider)
+        assert isinstance(provider2._inner, FastMCPProvider)
+        assert provider2._inner.server == sub_server2
+
+        # Verify namespacing is applied by checking tool names
+        tools = await main_server.list_tools()
+        tool_names = {t.name for t in tools}
+        assert tool_names == {"sub1_tool1", "sub2_tool2"}
+
+    async def test_multiple_routes_same_server(self):
+        """Test that multiple custom routes from same server are all included."""
+        server = FastMCP("TestServer")
+
+        @server.custom_route("/route1", methods=["GET"])
+        async def route1(request):
+            from starlette.responses import JSONResponse
+
+            return JSONResponse({"message": "route1"})
+
+        @server.custom_route("/route2", methods=["POST"])
+        async def route2(request):
+            from starlette.responses import JSONResponse
+
+            return JSONResponse({"message": "route2"})
+
+        routes = server._get_additional_http_routes()
+        assert len(routes) == 2
+        route_paths = [route.path for route in routes if isinstance(route, Route)]
+        assert "/route1" in route_paths
+        assert "/route2" in route_paths
+
+    async def test_mounted_server_custom_routes_forwarded(self):
+        """Test that custom routes from a mounted server appear in the parent.
+
+        Regression test for https://github.com/PrefectHQ/fastmcp/issues/3457
+        where custom_route endpoints defined on a child server were silently
+        dropped when the child was mounted onto a parent, resulting in 404s.
+        """
+        parent = FastMCP("Parent")
+        child = FastMCP("Child")
+
+        @child.custom_route("/readyz", methods=["GET"])
+        async def readiness_check(request):
+            from starlette.responses import JSONResponse
+
+            return JSONResponse({"status": "ok"})
+
+        parent.mount(child)
+
+        routes = parent._get_additional_http_routes()
+        assert len(routes) == 1
+        assert isinstance(routes[0], Route)
+        assert routes[0].path == "/readyz"
+
+    async def test_mounted_server_custom_routes_with_namespace(self):
+        """Test that custom routes from a namespaced mount are forwarded."""
+        parent = FastMCP("Parent")
+        child = FastMCP("Child")
+
+        @child.custom_route("/health", methods=["GET"])
+        async def health(request):
+            from starlette.responses import JSONResponse
+
+            return JSONResponse({"status": "ok"})
+
+        parent.mount(child, namespace="child")
+
+        routes = parent._get_additional_http_routes()
+        assert len(routes) == 1
+        assert isinstance(routes[0], Route)
+        assert routes[0].path == "/health"
+
+    async def test_deeply_nested_custom_routes_forwarded(self):
+        """Test that custom routes from deeply nested mounts are collected."""
+        root = FastMCP("Root")
+        middle = FastMCP("Middle")
+        leaf = FastMCP("Leaf")
+
+        @leaf.custom_route("/leaf-health", methods=["GET"])
+        async def leaf_health(request):
+            from starlette.responses import JSONResponse
+
+            return JSONResponse({"status": "ok"})
+
+        @middle.custom_route("/middle-health", methods=["GET"])
+        async def middle_health(request):
+            from starlette.responses import JSONResponse
+
+            return JSONResponse({"status": "ok"})
+
+        middle.mount(leaf)
+        root.mount(middle)
+
+        routes = root._get_additional_http_routes()
+        route_paths = [r.path for r in routes if isinstance(r, Route)]
+        assert "/leaf-health" in route_paths
+        assert "/middle-health" in route_paths
+        assert len(route_paths) == 2
+
+    async def test_mounted_custom_routes_http_app_integration(self):
+        """End-to-end: custom routes from mounted servers are reachable via http_app.
+
+        This reproduces the exact scenario from issue #3457.
+        """
+        from starlette.testclient import TestClient
+
+        parent = FastMCP("Parent")
+        child = FastMCP("Child")
+
+        @child.custom_route("/readyz", methods=["GET"])
+        async def readiness_check(request):
+            from starlette.responses import JSONResponse
+
+            return JSONResponse({"status": "ok"})
+
+        parent.mount(child)
+
+        app = parent.http_app()
+        client = TestClient(app)
+        response = client.get("/readyz")
+        assert response.status_code == 200
+        assert response.json() == {"status": "ok"}
+
+
+class TestDeeplyNestedMount:
+    """Test deeply nested mount scenarios (3+ levels deep).
+
+    This tests the fix for https://github.com/PrefectHQ/fastmcp/issues/2583
+    where tools/resources/prompts mounted more than 2 levels deep would fail
+    to invoke even though they were correctly listed.
+    """
+
+    async def test_three_level_nested_tool_invocation(self):
+        """Test invoking tools from servers mounted 3 levels deep."""
+        root = FastMCP("root")
+        middle = FastMCP("middle")
+        leaf = FastMCP("leaf")
+
+        @leaf.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        @middle.tool
+        def multiply(a: int, b: int) -> int:
+            return a * b
+
+        middle.mount(leaf, namespace="leaf")
+        root.mount(middle, namespace="middle")
+
+        # Tool at level 2 should work
+        result = await root.call_tool("middle_multiply", {"a": 3, "b": 4})
+        assert result.structured_content == {"result": 12}
+
+        # Tool at level 3 should also work (this was the bug)
+        result = await root.call_tool("middle_leaf_add", {"a": 5, "b": 7})
+        assert result.structured_content == {"result": 12}
+
+    async def test_three_level_nested_resource_invocation(self):
+        """Test reading resources from servers mounted 3 levels deep."""
+        root = FastMCP("root")
+        middle = FastMCP("middle")
+        leaf = FastMCP("leaf")
+
+        @leaf.resource("leaf://data")
+        def leaf_data() -> str:
+            return "leaf data"
+
+        @middle.resource("middle://data")
+        def middle_data() -> str:
+            return "middle data"
+
+        middle.mount(leaf, namespace="leaf")
+        root.mount(middle, namespace="middle")
+
+        # Resource at level 2 should work
+        result = await root.read_resource("middle://middle/data")
+        assert result.contents[0].content == "middle data"
+
+        # Resource at level 3 should also work
+        result = await root.read_resource("leaf://middle/leaf/data")
+        assert result.contents[0].content == "leaf data"
+
+    async def test_three_level_nested_resource_template_invocation(self):
+        """Test reading resource templates from servers mounted 3 levels deep."""
+        root = FastMCP("root")
+        middle = FastMCP("middle")
+        leaf = FastMCP("leaf")
+
+        @leaf.resource("leaf://item/{id}")
+        def leaf_item(id: str) -> str:
+            return f"leaf item {id}"
+
+        @middle.resource("middle://item/{id}")
+        def middle_item(id: str) -> str:
+            return f"middle item {id}"
+
+        middle.mount(leaf, namespace="leaf")
+        root.mount(middle, namespace="middle")
+
+        # Resource template at level 2 should work
+        result = await root.read_resource("middle://middle/item/42")
+        assert result.contents[0].content == "middle item 42"
+
+        # Resource template at level 3 should also work
+        result = await root.read_resource("leaf://middle/leaf/item/99")
+        assert result.contents[0].content == "leaf item 99"
+
+    async def test_three_level_nested_prompt_invocation(self):
+        """Test getting prompts from servers mounted 3 levels deep."""
+        root = FastMCP("root")
+        middle = FastMCP("middle")
+        leaf = FastMCP("leaf")
+
+        @leaf.prompt
+        def leaf_prompt(name: str) -> str:
+            return f"Hello from leaf: {name}"
+
+        @middle.prompt
+        def middle_prompt(name: str) -> str:
+            return f"Hello from middle: {name}"
+
+        middle.mount(leaf, namespace="leaf")
+        root.mount(middle, namespace="middle")
+
+        # Prompt at level 2 should work
+        result = await root.render_prompt("middle_middle_prompt", {"name": "World"})
+        assert isinstance(result.messages[0].content, TextContent)
+        assert "Hello from middle: World" in result.messages[0].content.text
+
+        # Prompt at level 3 should also work
+        result = await root.render_prompt("middle_leaf_leaf_prompt", {"name": "Test"})
+        assert isinstance(result.messages[0].content, TextContent)
+        assert "Hello from leaf: Test" in result.messages[0].content.text
+
+    async def test_four_level_nested_tool_invocation(self):
+        """Test invoking tools from servers mounted 4 levels deep."""
+        root = FastMCP("root")
+        level1 = FastMCP("level1")
+        level2 = FastMCP("level2")
+        level3 = FastMCP("level3")
+
+        @level3.tool
+        def deep_tool() -> str:
+            return "very deep"
+
+        level2.mount(level3, namespace="l3")
+        level1.mount(level2, namespace="l2")
+        root.mount(level1, namespace="l1")
+
+        # Verify tool is listed
+        tools = await root.list_tools()
+        tool_names = [t.name for t in tools]
+        assert "l1_l2_l3_deep_tool" in tool_names
+
+        # Tool at level 4 should work
+        result = await root.call_tool("l1_l2_l3_deep_tool", {})
+        assert result.structured_content == {"result": "very deep"}
+
+
+class TestToolNameOverrides:
+    """Test tool and prompt name overrides in mount() (issue #2596)."""
+
+    async def test_tool_names_override_via_transforms(self):
+        """Test that tool_names renames tools via ToolTransform layer.
+
+        Tool renames are applied first, then namespace prefixing.
+        So original_tool → custom_name → prefix_custom_name.
+        """
+        sub = FastMCP("Sub")
+
+        @sub.tool
+        def original_tool() -> str:
+            return "test"
+
+        main = FastMCP("Main")
+        # tool_names renames first, then namespace is applied
+        main.mount(
+            sub,
+            namespace="prefix",
+            tool_names={"original_tool": "custom_name"},
+        )
+
+        # Server introspection shows renamed + namespaced names
+        tools = await main.list_tools()
+        tool_names = [t.name for t in tools]
+        assert "prefix_custom_name" in tool_names
+        assert "original_tool" not in tool_names
+        assert "prefix_original_tool" not in tool_names
+        assert "custom_name" not in tool_names
+
+    async def test_tool_names_override_applied_in_list_tools(self):
+        """Test that tool_names override is reflected in list_tools()."""
+        sub = FastMCP("Sub")
+
+        @sub.tool
+        def original_tool() -> str:
+            return "test"
+
+        main = FastMCP("Main")
+        main.mount(
+            sub,
+            namespace="prefix",
+            tool_names={"original_tool": "custom_name"},
+        )
+
+        tools = await main.list_tools()
+        tool_names = [t.name for t in tools]
+        assert "prefix_custom_name" in tool_names
+        assert "prefix_original_tool" not in tool_names
+
+    async def test_tool_call_with_overridden_name(self):
+        """Test that overridden tool can be called by its new name."""
+        sub = FastMCP("Sub")
+
+        @sub.tool
+        def original_tool() -> str:
+            return "success"
+
+        main = FastMCP("Main")
+        main.mount(
+            sub,
+            namespace="prefix",
+            tool_names={"original_tool": "renamed"},
+        )
+
+        # Tool is renamed then namespaced: original_tool → renamed → prefix_renamed
+        result = await main.call_tool("prefix_renamed", {})
+        assert result.structured_content == {"result": "success"}
+
+    def test_duplicate_tool_rename_targets_raises_error(self):
+        """Test that duplicate target names in tool_renames raises ValueError."""
+        sub = FastMCP("Sub")
+        main = FastMCP("Main")
+
+        with pytest.raises(ValueError, match="duplicate target name"):
+            main.mount(
+                sub,
+                tool_names={"tool_a": "same_name", "tool_b": "same_name"},
+            )
+
+
+class TestMountedServerLifespanContext:
+    """Regression tests for mounted server lifespan_context resolution.
+
+    A mounted server's tools should see *their own* lifespan context via
+    ``ctx.lifespan_context``, not the parent's. Previously the result yielded
+    by a mounted server's lifespan was discarded and ``ctx.lifespan_context``
+    fell through to the parent's MCP-session lifespan context.
+    """
+
+    async def test_mounted_child_sees_own_lifespan_context(self):
+        """A tool on a mounted child reads its own lifespan result."""
+        from collections.abc import AsyncIterator
+        from contextlib import asynccontextmanager
+
+        from fastmcp.server.context import Context
+
+        @asynccontextmanager
+        async def parent_lifespan(_mcp: FastMCP) -> AsyncIterator[dict]:
+            yield {"who": "parent", "parent_only": "P"}
+
+        @asynccontextmanager
+        async def child_lifespan(_mcp: FastMCP) -> AsyncIterator[dict]:
+            yield {"who": "child", "child_only": "C"}
+
+        parent = FastMCP("Parent", lifespan=parent_lifespan)
+        child = FastMCP("Child", lifespan=child_lifespan)
+
+        @child.tool
+        def whoami(ctx: Context) -> dict:
+            return ctx.lifespan_context
+
+        parent.mount(child, "child")
+
+        async with Client(parent) as client:
+            result = await client.call_tool("child_whoami", {})
+
+        assert result.data == {"who": "child", "child_only": "C"}
+
+    async def test_independent_sibling_servers_each_get_own_lifecycle(self):
+        """Two unrelated servers entered in the same async context are not nested.
+
+        Each must run its own ``_docket_lifespan_root`` and establish its own
+        Docket / server-context — they are not in a parent/child relationship,
+        only the same async stack.
+        """
+        from contextlib import AsyncExitStack
+
+        from fastmcp.server.dependencies import _current_server
+
+        server_a = FastMCP("A")
+        server_b = FastMCP("B")
+
+        async with AsyncExitStack() as stack:
+            await stack.enter_async_context(server_a._lifespan_manager())
+            # While only A is active, _current_server resolves to A.
+            ref = _current_server.get()
+            assert ref is not None and ref() is server_a
+
+            await stack.enter_async_context(server_b._lifespan_manager())
+            # B established its own lifecycle; _current_server now resolves to B.
+            ref = _current_server.get()
+            assert ref is not None and ref() is server_b
+
+    async def test_unrelated_server_after_parent_with_mount(self):
+        """A parent with a mounted child must not contaminate later entries.
+
+        ``FastMCPProvider`` sets ``_lifespan_root_active`` while entering the
+        wrapped child. The flag must be cleared by the time the parent's
+        ``_lifespan_manager`` yields, otherwise an unrelated server entered
+        later in the same task would see the flag and skip its own root setup.
+        """
+        from contextlib import AsyncExitStack
+
+        from fastmcp.server.dependencies import _current_server
+
+        parent = FastMCP("Parent")
+        child = FastMCP("Child")
+        parent.mount(child, "child")
+
+        unrelated = FastMCP("Unrelated")
+
+        async with AsyncExitStack() as stack:
+            await stack.enter_async_context(parent._lifespan_manager())
+            # Parent's mount has run FastMCPProvider.lifespan; the flag set
+            # during child entry must have been reset by now.
+            await stack.enter_async_context(unrelated._lifespan_manager())
+            # Unrelated established its own lifecycle.
+            ref = _current_server.get()
+            assert ref is not None and ref() is unrelated
+
+    async def test_nested_grandchild_lifespan_runs(self):
+        """A grandchild's lifespan is entered exactly once and visible to its tools."""
+        from collections.abc import AsyncIterator
+        from contextlib import asynccontextmanager
+
+        from fastmcp.server.context import Context
+
+        events: list[str] = []
+
+        @asynccontextmanager
+        async def grandchild_lifespan(_mcp: FastMCP) -> AsyncIterator[dict]:
+            events.append("enter")
+            try:
+                yield {"who": "grandchild"}
+            finally:
+                events.append("exit")
+
+        parent = FastMCP("Parent")
+        child = FastMCP("Child")
+        grandchild = FastMCP("Grandchild", lifespan=grandchild_lifespan)
+
+        @grandchild.tool
+        def whoami(ctx: Context) -> dict:
+            return ctx.lifespan_context
+
+        child.mount(grandchild, "g")
+        parent.mount(child, "c")
+
+        async with Client(parent) as client:
+            result1 = await client.call_tool("c_g_whoami", {})
+            result2 = await client.call_tool("c_g_whoami", {})
+
+        assert result1.data == {"who": "grandchild"}
+        assert result2.data == {"who": "grandchild"}
+        # Lifespan is entered once at startup and exited once at teardown,
+        # not per-call and not per-mount level.
+        assert events == ["enter", "exit"]
+
+
+class TestMountedServerDocketBehavior:
+    """Regression tests for mounted server lifecycle behavior.
+
+    These tests guard against architectural changes that could accidentally
+    start Docket instances for mounted servers. Mounted servers should only
+    run their user-defined lifespan, not the full _lifespan_manager which
+    includes Docket creation.
+    """
+
+    async def test_mounted_server_does_not_have_docket(self):
+        """Test that a mounted server doesn't create its own Docket.
+
+        MountedProvider.lifespan() should call only the server's _lifespan
+        (user-defined lifespan), not _lifespan_manager (which includes Docket).
+        """
+        main_app = FastMCP("MainApp")
+        sub_app = FastMCP("SubApp")
+
+        # Need a task-enabled component to trigger Docket initialization
+        @main_app.tool(task=True)
+        async def _trigger_docket() -> str:
+            return "trigger"
+
+        @sub_app.tool
+        def my_tool() -> str:
+            return "test"
+
+        main_app.mount(sub_app, "sub")
+
+        # After running the main app's lifespan, the sub app should not have
+        # its own Docket instance
+        async with Client(main_app) as client:
+            # The main app should have a docket (created by _lifespan_manager)
+            # because it has a task-enabled component
+            assert main_app.docket is not None
+
+            # The mounted sub app should NOT have its own docket
+            # It uses the parent's docket for background tasks
+            assert sub_app.docket is None
+
+            # But the tool should still work (prefixed as sub_my_tool)
+            result = await client.call_tool("sub_my_tool", {})
+            assert result.data == "test"
+
+
+class TestComponentServicePrefixLess:
+    """Test that enable/disable works with prefix-less mounted servers."""
+
+    async def test_enable_tool_prefixless_mount(self):
+        """Test enabling a tool on a prefix-less mounted server."""
+        main_app = FastMCP("MainApp")
+        sub_app = FastMCP("SubApp")
+
+        @sub_app.tool
+        def my_tool() -> str:
+            return "test"
+
+        # Mount without prefix
+        main_app.mount(sub_app)
+
+        # Initially the tool is enabled
+        tools = await main_app.list_tools()
+        assert any(t.name == "my_tool" for t in tools)
+
+        # Disable and re-enable
+        main_app.disable(names={"my_tool"}, components={"tool"})
+        # Verify tool is now disabled
+        tools = await main_app.list_tools()
+        assert not any(t.name == "my_tool" for t in tools)
+
+        main_app.enable(names={"my_tool"}, components={"tool"})
+        # Verify tool is now enabled
+        tools = await main_app.list_tools()
+        assert any(t.name == "my_tool" for t in tools)
+
+    async def test_enable_resource_prefixless_mount(self):
+        """Test enabling a resource on a prefix-less mounted server."""
+        main_app = FastMCP("MainApp")
+        sub_app = FastMCP("SubApp")
+
+        @sub_app.resource(uri="data://test")
+        def my_resource() -> str:
+            return "test data"
+
+        # Mount without prefix
+        main_app.mount(sub_app)
+
+        # Disable and re-enable
+        main_app.disable(names={"data://test"}, components={"resource"})
+        # Verify resource is now disabled
+        resources = await main_app.list_resources()
+        assert not any(str(r.uri) == "data://test" for r in resources)
+
+        main_app.enable(names={"data://test"}, components={"resource"})
+        # Verify resource is now enabled
+        resources = await main_app.list_resources()
+        assert any(str(r.uri) == "data://test" for r in resources)
+
+    async def test_enable_prompt_prefixless_mount(self):
+        """Test enabling a prompt on a prefix-less mounted server."""
+        main_app = FastMCP("MainApp")
+        sub_app = FastMCP("SubApp")
+
+        @sub_app.prompt
+        def my_prompt() -> str:
+            return "test prompt"
+
+        # Mount without prefix
+        main_app.mount(sub_app)
+
+        # Disable and re-enable
+        main_app.disable(names={"my_prompt"}, components={"prompt"})
+        # Verify prompt is now disabled
+        prompts = await main_app.list_prompts()
+        assert not any(p.name == "my_prompt" for p in prompts)
+
+        main_app.enable(names={"my_prompt"}, components={"prompt"})
+        # Verify prompt is now enabled
+        prompts = await main_app.list_prompts()
+        assert any(p.name == "my_prompt" for p in prompts)
diff --git a/tests/server/mount/test_filtering.py b/tests/server/mount/test_filtering.py
new file mode 100644
index 0000000..376db4c
--- /dev/null
+++ b/tests/server/mount/test_filtering.py
@@ -0,0 +1,101 @@
+"""Tests for tag filtering in mounted servers."""
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.exceptions import NotFoundError
+
+
+class TestParentTagFiltering:
+    """Test that parent server tag filters apply recursively to mounted servers."""
+
+    async def test_parent_include_tags_filters_mounted_tools(self):
+        """Test that parent include_tags filters out non-matching mounted tools."""
+        parent = FastMCP("Parent")
+        parent.enable(tags={"allowed"}, only=True)
+        mounted = FastMCP("Mounted")
+
+        @mounted.tool(tags={"allowed"})
+        def allowed_tool() -> str:
+            return "allowed"
+
+        @mounted.tool(tags={"blocked"})
+        def blocked_tool() -> str:
+            return "blocked"
+
+        parent.mount(mounted)
+
+        tools = await parent.list_tools()
+        tool_names = {t.name for t in tools}
+        assert "allowed_tool" in tool_names
+        assert "blocked_tool" not in tool_names
+
+        # Verify execution also respects filters
+        result = await parent.call_tool("allowed_tool", {})
+        assert result.structured_content == {"result": "allowed"}
+
+        with pytest.raises(NotFoundError, match="Unknown tool"):
+            await parent.call_tool("blocked_tool", {})
+
+    async def test_parent_exclude_tags_filters_mounted_tools(self):
+        """Test that parent exclude_tags filters out matching mounted tools."""
+        parent = FastMCP("Parent")
+        parent.disable(tags={"blocked"})
+        mounted = FastMCP("Mounted")
+
+        @mounted.tool(tags={"production"})
+        def production_tool() -> str:
+            return "production"
+
+        @mounted.tool(tags={"blocked"})
+        def blocked_tool() -> str:
+            return "blocked"
+
+        parent.mount(mounted)
+
+        tools = await parent.list_tools()
+        tool_names = {t.name for t in tools}
+        assert "production_tool" in tool_names
+        assert "blocked_tool" not in tool_names
+
+    async def test_parent_filters_apply_to_mounted_resources(self):
+        """Test that parent tag filters apply to mounted resources."""
+        parent = FastMCP("Parent")
+        parent.enable(tags={"allowed"}, only=True)
+        mounted = FastMCP("Mounted")
+
+        @mounted.resource("resource://allowed", tags={"allowed"})
+        def allowed_resource() -> str:
+            return "allowed"
+
+        @mounted.resource("resource://blocked", tags={"blocked"})
+        def blocked_resource() -> str:
+            return "blocked"
+
+        parent.mount(mounted)
+
+        resources = await parent.list_resources()
+        resource_uris = {str(r.uri) for r in resources}
+        assert "resource://allowed" in resource_uris
+        assert "resource://blocked" not in resource_uris
+
+    async def test_parent_filters_apply_to_mounted_prompts(self):
+        """Test that parent tag filters apply to mounted prompts."""
+        parent = FastMCP("Parent")
+        parent.disable(tags={"blocked"})
+        mounted = FastMCP("Mounted")
+
+        @mounted.prompt(tags={"allowed"})
+        def allowed_prompt() -> str:
+            return "allowed"
+
+        @mounted.prompt(tags={"blocked"})
+        def blocked_prompt() -> str:
+            return "blocked"
+
+        parent.mount(mounted)
+
+        prompts = await parent.list_prompts()
+        prompt_names = {p.name for p in prompts}
+        assert "allowed_prompt" in prompt_names
+        assert "blocked_prompt" not in prompt_names
diff --git a/tests/server/mount/test_mount.py b/tests/server/mount/test_mount.py
new file mode 100644
index 0000000..5f099a3
--- /dev/null
+++ b/tests/server/mount/test_mount.py
@@ -0,0 +1,636 @@
+"""Basic mounting functionality tests."""
+
+import logging
+import sys
+
+import pytest
+from mcp_types import TextContent
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.transports import SSETransport
+from fastmcp.server import create_proxy
+from fastmcp.tools.base import Tool
+from fastmcp.tools.tool_transform import TransformedTool
+
+
+class TestBasicMount:
+    """Test basic mounting functionality."""
+
+    async def test_mount_simple_server(self):
+        """Test mounting a simple server and accessing its tool."""
+        # Create main app and sub-app
+        main_app = FastMCP("MainApp")
+
+        # Add a tool to the sub-app
+        def tool() -> str:
+            return "This is from the sub app"
+
+        sub_tool = Tool.from_function(tool)
+
+        transformed_tool = TransformedTool.from_tool(
+            name="transformed_tool", tool=sub_tool
+        )
+
+        sub_app = FastMCP("SubApp", tools=[transformed_tool, sub_tool])
+
+        # Mount the sub-app to the main app
+        main_app.mount(sub_app, "sub")
+
+        # Get tools from main app, should include sub_app's tools
+        tools = await main_app.list_tools()
+        assert any(t.name == "sub_tool" for t in tools)
+        assert any(t.name == "sub_transformed_tool" for t in tools)
+
+        result = await main_app.call_tool("sub_tool", {})
+        assert result.structured_content == {"result": "This is from the sub app"}
+
+    async def test_mount_with_custom_separator(self):
+        """Test mounting with a custom tool separator (deprecated but still supported)."""
+        main_app = FastMCP("MainApp")
+        sub_app = FastMCP("SubApp")
+
+        @sub_app.tool
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        # Mount without custom separator - custom separators are deprecated
+        main_app.mount(sub_app, "sub")
+
+        # Tool should be accessible with the default separator
+        tools = await main_app.list_tools()
+        assert any(t.name == "sub_greet" for t in tools)
+
+        # Call the tool
+        result = await main_app.call_tool("sub_greet", {"name": "World"})
+        assert result.structured_content == {"result": "Hello, World!"}
+
+    @pytest.mark.parametrize("prefix", ["", None])
+    async def test_mount_with_no_prefix(self, prefix):
+        main_app = FastMCP("MainApp")
+        sub_app = FastMCP("SubApp")
+
+        @sub_app.tool
+        def sub_tool() -> str:
+            return "This is from the sub app"
+
+        # Mount with empty prefix but without deprecated separators
+        main_app.mount(sub_app, namespace=prefix)
+
+        tools = await main_app.list_tools()
+        # With empty prefix, the tool should keep its original name
+        assert any(t.name == "sub_tool" for t in tools)
+
+    async def test_mount_with_no_prefix_provided(self):
+        """Test mounting without providing a prefix at all."""
+        main_app = FastMCP("MainApp")
+        sub_app = FastMCP("SubApp")
+
+        @sub_app.tool
+        def sub_tool() -> str:
+            return "This is from the sub app"
+
+        # Mount without providing a prefix (should be None)
+        main_app.mount(sub_app)
+
+        tools = await main_app.list_tools()
+        # Without prefix, the tool should keep its original name
+        assert any(t.name == "sub_tool" for t in tools)
+
+        # Call the tool to verify it works
+        result = await main_app.call_tool("sub_tool", {})
+        assert result.structured_content == {"result": "This is from the sub app"}
+
+    async def test_mount_tools_no_prefix(self):
+        """Test mounting a server with tools without prefix."""
+        main_app = FastMCP("MainApp")
+        sub_app = FastMCP("SubApp")
+
+        @sub_app.tool
+        def sub_tool() -> str:
+            return "Sub tool result"
+
+        # Mount without prefix
+        main_app.mount(sub_app)
+
+        # Verify tool is accessible with original name
+        tools = await main_app.list_tools()
+        assert any(t.name == "sub_tool" for t in tools)
+
+        # Test actual functionality
+        tool_result = await main_app.call_tool("sub_tool", {})
+        assert tool_result.structured_content == {"result": "Sub tool result"}
+
+    async def test_mount_resources_no_prefix(self):
+        """Test mounting a server with resources without prefix."""
+        main_app = FastMCP("MainApp")
+        sub_app = FastMCP("SubApp")
+
+        @sub_app.resource(uri="data://config")
+        def sub_resource():
+            return "Sub resource data"
+
+        # Mount without prefix
+        main_app.mount(sub_app)
+
+        # Verify resource is accessible with original URI
+        resources = await main_app.list_resources()
+        assert any(str(r.uri) == "data://config" for r in resources)
+
+        # Test actual functionality
+        resource_result = await main_app.read_resource("data://config")
+        assert resource_result.contents[0].content == "Sub resource data"
+
+    async def test_mount_resource_templates_no_prefix(self):
+        """Test mounting a server with resource templates without prefix."""
+        main_app = FastMCP("MainApp")
+        sub_app = FastMCP("SubApp")
+
+        @sub_app.resource(uri="users://{user_id}/info")
+        def sub_template(user_id: str):
+            return f"Sub template for user {user_id}"
+
+        # Mount without prefix
+        main_app.mount(sub_app)
+
+        # Verify template is accessible with original URI template
+        templates = await main_app.list_resource_templates()
+        assert any(t.uri_template == "users://{user_id}/info" for t in templates)
+
+        # Test actual functionality
+        template_result = await main_app.read_resource("users://123/info")
+        assert template_result.contents[0].content == "Sub template for user 123"
+
+    async def test_mount_prompts_no_prefix(self):
+        """Test mounting a server with prompts without prefix."""
+        main_app = FastMCP("MainApp")
+        sub_app = FastMCP("SubApp")
+
+        @sub_app.prompt
+        def sub_prompt() -> str:
+            return "Sub prompt content"
+
+        # Mount without prefix
+        main_app.mount(sub_app)
+
+        # Verify prompt is accessible with original name
+        prompts = await main_app.list_prompts()
+        assert any(p.name == "sub_prompt" for p in prompts)
+
+        # Test actual functionality
+        prompt_result = await main_app.render_prompt("sub_prompt")
+        assert prompt_result.messages is not None
+
+
+class TestMultipleServerMount:
+    """Test mounting multiple servers simultaneously."""
+
+    async def test_mount_multiple_servers(self):
+        """Test mounting multiple servers with different prefixes."""
+        main_app = FastMCP("MainApp")
+        weather_app = FastMCP("WeatherApp")
+        news_app = FastMCP("NewsApp")
+
+        @weather_app.tool
+        def get_forecast() -> str:
+            return "Weather forecast"
+
+        @news_app.tool
+        def get_headlines() -> str:
+            return "News headlines"
+
+        # Mount both apps
+        main_app.mount(weather_app, "weather")
+        main_app.mount(news_app, "news")
+
+        # Check both are accessible
+        tools = await main_app.list_tools()
+        assert any(t.name == "weather_get_forecast" for t in tools)
+        assert any(t.name == "news_get_headlines" for t in tools)
+
+        # Call tools from both mounted servers
+        result1 = await main_app.call_tool("weather_get_forecast", {})
+        assert result1.structured_content == {"result": "Weather forecast"}
+        result2 = await main_app.call_tool("news_get_headlines", {})
+        assert result2.structured_content == {"result": "News headlines"}
+
+    async def test_mount_same_prefix(self):
+        """Test that mounting with the same prefix replaces the previous mount."""
+        main_app = FastMCP("MainApp")
+        first_app = FastMCP("FirstApp")
+        second_app = FastMCP("SecondApp")
+
+        @first_app.tool
+        def first_tool() -> str:
+            return "First app tool"
+
+        @second_app.tool
+        def second_tool() -> str:
+            return "Second app tool"
+
+        # Mount first app
+        main_app.mount(first_app, "api")
+        tools = await main_app.list_tools()
+        assert any(t.name == "api_first_tool" for t in tools)
+
+        # Mount second app with same prefix
+        main_app.mount(second_app, "api")
+        tools = await main_app.list_tools()
+
+        # Both apps' tools should be accessible (new behavior)
+        assert any(t.name == "api_first_tool" for t in tools)
+        assert any(t.name == "api_second_tool" for t in tools)
+
+    @pytest.mark.skipif(
+        sys.platform == "win32", reason="Windows asyncio networking timeouts."
+    )
+    async def test_mount_with_unreachable_proxy_servers(self, caplog):
+        """Test graceful handling when multiple mounted servers fail to connect."""
+        caplog.set_level(logging.DEBUG, logger="fastmcp")
+
+        main_app = FastMCP("MainApp")
+        working_app = FastMCP("WorkingApp")
+
+        @working_app.tool
+        def working_tool() -> str:
+            return "Working tool"
+
+        @working_app.resource(uri="working://data")
+        def working_resource():
+            return "Working resource"
+
+        @working_app.prompt
+        def working_prompt() -> str:
+            return "Working prompt"
+
+        # Mount the working server
+        main_app.mount(working_app, "working")
+
+        # Use an unreachable port
+        unreachable_client = Client(
+            transport=SSETransport("http://127.0.0.1:9999/sse/"),
+            name="unreachable_client",
+        )
+
+        # Create a proxy server that will fail to connect
+        unreachable_proxy = create_proxy(unreachable_client, name="unreachable_proxy")
+
+        # Mount the unreachable proxy
+        main_app.mount(unreachable_proxy, "unreachable")
+
+        # All object types should work from working server despite unreachable proxy
+        async with Client(main_app, name="main_app_client") as client:
+            # Test tools
+            tools = await client.list_tools()
+            tool_names = [tool.name for tool in tools]
+            assert "working_working_tool" in tool_names
+
+            # Test calling a tool
+            result = await client.call_tool("working_working_tool", {})
+            assert result.data == "Working tool"
+
+            # Test resources
+            resources = await client.list_resources()
+            resource_uris = [str(resource.uri) for resource in resources]
+            assert "working://working/data" in resource_uris
+
+            # Test prompts
+            prompts = await client.list_prompts()
+            prompt_names = [prompt.name for prompt in prompts]
+            assert "working_working_prompt" in prompt_names
+
+        # Verify that errors were logged for the unreachable provider (at WARNING level)
+        warning_messages = [
+            record.message for record in caplog.records if record.levelname == "WARNING"
+        ]
+        assert any(
+            "Error during list_tools from provider" in msg for msg in warning_messages
+        )
+        assert any(
+            "Error during list_resources from provider" in msg
+            for msg in warning_messages
+        )
+        assert any(
+            "Error during list_prompts from provider" in msg for msg in warning_messages
+        )
+
+
+class TestPrefixConflictResolution:
+    """Test that first registered provider wins when there are conflicts.
+
+    Provider semantics: 'Providers are queried in registration order; first non-None wins'
+    """
+
+    async def test_first_server_wins_tools_no_prefix(self):
+        """Test that first mounted server wins for tools when no prefix is used."""
+        main_app = FastMCP("MainApp")
+        first_app = FastMCP("FirstApp")
+        second_app = FastMCP("SecondApp")
+
+        @first_app.tool(name="shared_tool")
+        def first_shared_tool() -> str:
+            return "First app tool"
+
+        @second_app.tool(name="shared_tool")
+        def second_shared_tool() -> str:
+            return "Second app tool"
+
+        # Mount both apps without prefix
+        main_app.mount(first_app)
+        main_app.mount(second_app)
+
+        # list_tools returns all components; execution uses first match
+        tools = await main_app.list_tools()
+        tool_names = [t.name for t in tools]
+        assert "shared_tool" in tool_names
+
+        # Test that calling the tool uses the first server's implementation
+        result = await main_app.call_tool("shared_tool", {})
+        assert result.structured_content == {"result": "First app tool"}
+
+    async def test_first_server_wins_tools_same_prefix(self):
+        """Test that first mounted server wins for tools when same prefix is used."""
+        main_app = FastMCP("MainApp")
+        first_app = FastMCP("FirstApp")
+        second_app = FastMCP("SecondApp")
+
+        @first_app.tool(name="shared_tool")
+        def first_shared_tool() -> str:
+            return "First app tool"
+
+        @second_app.tool(name="shared_tool")
+        def second_shared_tool() -> str:
+            return "Second app tool"
+
+        # Mount both apps with same prefix
+        main_app.mount(first_app, "api")
+        main_app.mount(second_app, "api")
+
+        # list_tools returns all components; execution uses first match
+        tools = await main_app.list_tools()
+        tool_names = [t.name for t in tools]
+        assert "api_shared_tool" in tool_names
+
+        # Test that calling the tool uses the first server's implementation
+        result = await main_app.call_tool("api_shared_tool", {})
+        assert result.structured_content == {"result": "First app tool"}
+
+    async def test_first_server_wins_resources_no_prefix(self):
+        """Test that first mounted server wins for resources when no prefix is used."""
+        main_app = FastMCP("MainApp")
+        first_app = FastMCP("FirstApp")
+        second_app = FastMCP("SecondApp")
+
+        @first_app.resource(uri="shared://data")
+        def first_resource():
+            return "First app data"
+
+        @second_app.resource(uri="shared://data")
+        def second_resource():
+            return "Second app data"
+
+        # Mount both apps without prefix
+        main_app.mount(first_app)
+        main_app.mount(second_app)
+
+        # list_resources returns all components; execution uses first match
+        resources = await main_app.list_resources()
+        resource_uris = [str(r.uri) for r in resources]
+        assert "shared://data" in resource_uris
+
+        # Test that reading the resource uses the first server's implementation
+        result = await main_app.read_resource("shared://data")
+        assert result.contents[0].content == "First app data"
+
+    async def test_first_server_wins_resources_same_prefix(self):
+        """Test that first mounted server wins for resources when same prefix is used."""
+        main_app = FastMCP("MainApp")
+        first_app = FastMCP("FirstApp")
+        second_app = FastMCP("SecondApp")
+
+        @first_app.resource(uri="shared://data")
+        def first_resource():
+            return "First app data"
+
+        @second_app.resource(uri="shared://data")
+        def second_resource():
+            return "Second app data"
+
+        # Mount both apps with same prefix
+        main_app.mount(first_app, "api")
+        main_app.mount(second_app, "api")
+
+        # list_resources returns all components; execution uses first match
+        resources = await main_app.list_resources()
+        resource_uris = [str(r.uri) for r in resources]
+        assert "shared://api/data" in resource_uris
+
+        # Test that reading the resource uses the first server's implementation
+        result = await main_app.read_resource("shared://api/data")
+        assert result.contents[0].content == "First app data"
+
+    async def test_first_server_wins_resource_templates_no_prefix(self):
+        """Test that first mounted server wins for resource templates when no prefix is used."""
+        main_app = FastMCP("MainApp")
+        first_app = FastMCP("FirstApp")
+        second_app = FastMCP("SecondApp")
+
+        @first_app.resource(uri="users://{user_id}/profile")
+        def first_template(user_id: str):
+            return f"First app user {user_id}"
+
+        @second_app.resource(uri="users://{user_id}/profile")
+        def second_template(user_id: str):
+            return f"Second app user {user_id}"
+
+        # Mount both apps without prefix
+        main_app.mount(first_app)
+        main_app.mount(second_app)
+
+        # list_resource_templates returns all components; execution uses first match
+        templates = await main_app.list_resource_templates()
+        template_uris = [t.uri_template for t in templates]
+        assert "users://{user_id}/profile" in template_uris
+
+        # Test that reading the resource uses the first server's implementation
+        result = await main_app.read_resource("users://123/profile")
+        assert result.contents[0].content == "First app user 123"
+
+    async def test_first_server_wins_resource_templates_same_prefix(self):
+        """Test that first mounted server wins for resource templates when same prefix is used."""
+        main_app = FastMCP("MainApp")
+        first_app = FastMCP("FirstApp")
+        second_app = FastMCP("SecondApp")
+
+        @first_app.resource(uri="users://{user_id}/profile")
+        def first_template(user_id: str):
+            return f"First app user {user_id}"
+
+        @second_app.resource(uri="users://{user_id}/profile")
+        def second_template(user_id: str):
+            return f"Second app user {user_id}"
+
+        # Mount both apps with same prefix
+        main_app.mount(first_app, "api")
+        main_app.mount(second_app, "api")
+
+        # list_resource_templates returns all components; execution uses first match
+        templates = await main_app.list_resource_templates()
+        template_uris = [t.uri_template for t in templates]
+        assert "users://api/{user_id}/profile" in template_uris
+
+        # Test that reading the resource uses the first server's implementation
+        result = await main_app.read_resource("users://api/123/profile")
+        assert result.contents[0].content == "First app user 123"
+
+    async def test_first_server_wins_prompts_no_prefix(self):
+        """Test that first mounted server wins for prompts when no prefix is used."""
+        main_app = FastMCP("MainApp")
+        first_app = FastMCP("FirstApp")
+        second_app = FastMCP("SecondApp")
+
+        @first_app.prompt(name="shared_prompt")
+        def first_shared_prompt() -> str:
+            return "First app prompt"
+
+        @second_app.prompt(name="shared_prompt")
+        def second_shared_prompt() -> str:
+            return "Second app prompt"
+
+        # Mount both apps without prefix
+        main_app.mount(first_app)
+        main_app.mount(second_app)
+
+        # list_prompts returns all components; execution uses first match
+        prompts = await main_app.list_prompts()
+        prompt_names = [p.name for p in prompts]
+        assert "shared_prompt" in prompt_names
+
+        # Test that getting the prompt uses the first server's implementation
+        result = await main_app.render_prompt("shared_prompt")
+        assert result.messages is not None
+        assert isinstance(result.messages[0].content, TextContent)
+        assert result.messages[0].content.text == "First app prompt"
+
+    async def test_first_server_wins_prompts_same_prefix(self):
+        """Test that first mounted server wins for prompts when same prefix is used."""
+        main_app = FastMCP("MainApp")
+        first_app = FastMCP("FirstApp")
+        second_app = FastMCP("SecondApp")
+
+        @first_app.prompt(name="shared_prompt")
+        def first_shared_prompt() -> str:
+            return "First app prompt"
+
+        @second_app.prompt(name="shared_prompt")
+        def second_shared_prompt() -> str:
+            return "Second app prompt"
+
+        # Mount both apps with same prefix
+        main_app.mount(first_app, "api")
+        main_app.mount(second_app, "api")
+
+        # list_prompts returns all components; execution uses first match
+        prompts = await main_app.list_prompts()
+        prompt_names = [p.name for p in prompts]
+        assert "api_shared_prompt" in prompt_names
+
+        # Test that getting the prompt uses the first server's implementation
+        result = await main_app.render_prompt("api_shared_prompt")
+        assert result.messages is not None
+        assert isinstance(result.messages[0].content, TextContent)
+        assert result.messages[0].content.text == "First app prompt"
+
+
+class TestCrossProviderDuplicateDetection:
+    """Cross-provider collisions always log a warning — diagnostic signal only.
+
+    `on_duplicate` is a registration-time setting for LocalProvider (two
+    decorators on the same server), not a knob for AggregateProvider
+    composition. Mounted-provider collisions happen at runtime (sometimes
+    dynamically), so an error mode would give the author no way to react.
+    """
+
+    async def test_cross_provider_duplicate_warns(self, caplog):
+        """Two mounted providers exposing the same tool identity log a warning."""
+        main = FastMCP("Main")
+        sub1 = FastMCP("Sub1")
+        sub2 = FastMCP("Sub2")
+
+        @sub1.tool(name="greet")
+        def greet_w1() -> str:
+            return "from sub1"
+
+        @sub2.tool(name="greet")
+        def greet_w2() -> str:
+            return "from sub2"
+
+        main.mount(sub1, "ns")
+        main.mount(sub2, "ns")
+
+        caplog.set_level(logging.WARNING, logger="fastmcp")
+        tools = await main.list_tools()
+        assert len([t for t in tools if t.name == "ns_greet"]) == 2
+        assert any("Duplicate" in r.message for r in caplog.records)
+
+    async def test_no_false_positive_for_different_names(self):
+        """Different tool names in the same namespace don't trigger a warning."""
+        main = FastMCP("Main")
+        sub1 = FastMCP("Sub1")
+        sub2 = FastMCP("Sub2")
+
+        @sub1.tool
+        def tool_a() -> str:
+            return "a"
+
+        @sub2.tool
+        def tool_b() -> str:
+            return "b"
+
+        main.mount(sub1, "ns")
+        main.mount(sub2, "ns")
+
+        tools = await main.list_tools()
+        assert len(tools) == 2
+
+
+class TestMaskErrorDetailsMismatchWarning:
+    """Test that mismatched mask_error_details is warned about at mount time."""
+
+    async def test_warns_when_parent_masked_child_not(self, caplog):
+        """Mounting an unmasked child into a masked parent logs a warning."""
+        caplog.set_level(logging.WARNING, logger="fastmcp")
+        parent = FastMCP("parent", mask_error_details=True)
+        child = FastMCP("child")
+
+        @child.tool
+        def my_tool() -> str:
+            return "ok"
+
+        parent.mount(child, "ns")
+        assert any("mask_error_details" in r.message for r in caplog.records)
+
+    async def test_no_warning_when_both_masked(self, caplog):
+        """No warning when both parent and child have masking enabled."""
+        caplog.set_level(logging.WARNING, logger="fastmcp")
+        parent = FastMCP("parent", mask_error_details=True)
+        child = FastMCP("child", mask_error_details=True)
+
+        @child.tool
+        def my_tool() -> str:
+            return "ok"
+
+        parent.mount(child, "ns")
+        assert not any("mask_error_details" in r.message for r in caplog.records)
+
+    async def test_child_not_mutated_by_mount(self):
+        """Mounting should not mutate the child server's mask setting."""
+        parent = FastMCP("parent", mask_error_details=True)
+        child = FastMCP("child")
+
+        @child.tool
+        def my_tool() -> str:
+            return "ok"
+
+        parent.mount(child, "ns")
+        assert child._mask_error_details is False
diff --git a/tests/server/mount/test_prompts.py b/tests/server/mount/test_prompts.py
new file mode 100644
index 0000000..9760cab
--- /dev/null
+++ b/tests/server/mount/test_prompts.py
@@ -0,0 +1,50 @@
+"""Tests for prompt mounting."""
+
+from fastmcp import FastMCP
+
+
+class TestPrompts:
+    """Test mounting with prompts."""
+
+    async def test_mount_with_prompts(self):
+        """Test mounting a server with prompts."""
+        main_app = FastMCP("MainApp")
+        assistant_app = FastMCP("AssistantApp")
+
+        @assistant_app.prompt
+        def greeting(name: str) -> str:
+            return f"Hello, {name}!"
+
+        # Mount the assistant app
+        main_app.mount(assistant_app, "assistant")
+
+        # Prompt should be accessible through main app
+        prompts = await main_app.list_prompts()
+        assert any(p.name == "assistant_greeting" for p in prompts)
+
+        # Render the prompt
+        result = await main_app.render_prompt("assistant_greeting", {"name": "World"})
+        assert result.messages is not None
+        # The message should contain our greeting text
+
+    async def test_adding_prompt_after_mounting(self):
+        """Test adding a prompt after mounting."""
+        main_app = FastMCP("MainApp")
+        assistant_app = FastMCP("AssistantApp")
+
+        # Mount the assistant app before adding prompts
+        main_app.mount(assistant_app, "assistant")
+
+        # Add a prompt after mounting
+        @assistant_app.prompt
+        def farewell(name: str) -> str:
+            return f"Goodbye, {name}!"
+
+        # Prompt should be accessible through main app
+        prompts = await main_app.list_prompts()
+        assert any(p.name == "assistant_farewell" for p in prompts)
+
+        # Render the prompt
+        result = await main_app.render_prompt("assistant_farewell", {"name": "World"})
+        assert result.messages is not None
+        # The message should contain our farewell text
diff --git a/tests/server/mount/test_proxy.py b/tests/server/mount/test_proxy.py
new file mode 100644
index 0000000..e514a5f
--- /dev/null
+++ b/tests/server/mount/test_proxy.py
@@ -0,0 +1,225 @@
+"""Tests for proxy server mounting."""
+
+import json
+from contextlib import asynccontextmanager
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.transports import FastMCPTransport
+from fastmcp.server import create_proxy
+from fastmcp.server.providers import FastMCPProvider
+from fastmcp.server.providers.wrapped_provider import _WrappedProvider
+from fastmcp.server.transforms import Namespace
+
+
+class TestProxyServer:
+    """Test mounting a proxy server."""
+
+    async def test_mount_proxy_server(self):
+        """Test mounting a proxy server."""
+        # Create original server
+        original_server = FastMCP("OriginalServer")
+
+        @original_server.tool
+        def get_data(query: str) -> str:
+            return f"Data for {query}"
+
+        # Create proxy server
+        proxy_server = create_proxy(FastMCPTransport(original_server))
+
+        # Mount proxy server
+        main_app = FastMCP("MainApp")
+        main_app.mount(proxy_server, "proxy")
+
+        # Tool should be accessible through main app
+        tools = await main_app.list_tools()
+        assert any(t.name == "proxy_get_data" for t in tools)
+
+        # Call the tool
+        result = await main_app.call_tool("proxy_get_data", {"query": "test"})
+        assert result.structured_content == {"result": "Data for test"}
+
+    async def test_dynamically_adding_to_proxied_server(self):
+        """Test that changes to the original server are reflected in the mounted proxy."""
+        # Create original server
+        original_server = FastMCP("OriginalServer")
+
+        # Create proxy server
+        proxy_server = create_proxy(FastMCPTransport(original_server))
+
+        # Mount proxy server
+        main_app = FastMCP("MainApp")
+        main_app.mount(proxy_server, "proxy")
+
+        # Add a tool to the original server
+        @original_server.tool
+        def dynamic_data() -> str:
+            return "Dynamic data"
+
+        # Tool should be accessible through main app via proxy
+        tools = await main_app.list_tools()
+        assert any(t.name == "proxy_dynamic_data" for t in tools)
+
+        # Call the tool
+        result = await main_app.call_tool("proxy_dynamic_data", {})
+        assert result.structured_content == {"result": "Dynamic data"}
+
+    async def test_proxy_server_with_resources(self):
+        """Test mounting a proxy server with resources."""
+        # Create original server
+        original_server = FastMCP("OriginalServer")
+
+        @original_server.resource(uri="config://settings")
+        def get_config() -> str:
+            return json.dumps({"api_key": "12345"})
+
+        # Create proxy server
+        proxy_server = create_proxy(FastMCPTransport(original_server))
+
+        # Mount proxy server
+        main_app = FastMCP("MainApp")
+        main_app.mount(proxy_server, "proxy")
+
+        # Resource should be accessible through main app
+        result = await main_app.read_resource("config://proxy/settings")
+        assert len(result.contents) == 1
+        config = json.loads(result.contents[0].content)
+        assert config["api_key"] == "12345"
+
+    async def test_proxy_server_with_prompts(self):
+        """Test mounting a proxy server with prompts."""
+        # Create original server
+        original_server = FastMCP("OriginalServer")
+
+        @original_server.prompt
+        def welcome(name: str) -> str:
+            return f"Welcome, {name}!"
+
+        # Create proxy server
+        proxy_server = create_proxy(FastMCPTransport(original_server))
+
+        # Mount proxy server
+        main_app = FastMCP("MainApp")
+        main_app.mount(proxy_server, "proxy")
+
+        # Prompt should be accessible through main app
+        result = await main_app.render_prompt("proxy_welcome", {"name": "World"})
+        assert result.messages is not None
+        # The message should contain our welcome text
+
+
+class TestMountProviderStructure:
+    """Test the provider structure produced by mounting."""
+
+    async def test_mount_wraps_in_fastmcp_provider(self):
+        mcp = FastMCP("Main")
+        sub = FastMCP("Sub")
+
+        @sub.tool
+        def sub_tool() -> str:
+            return "test"
+
+        mcp.mount(sub, "sub")
+        # Index 1 because LocalProvider is at index 0
+        provider = mcp.providers[1]
+        # Provider is wrapped with Namespace transform
+        assert isinstance(provider, _WrappedProvider)
+        assert len(provider._transforms) == 1
+        assert isinstance(provider._transforms[0], Namespace)
+        # Inner provider is FastMCPProvider
+        assert isinstance(provider._inner, FastMCPProvider)
+        assert provider._inner.server is sub
+        # Verify namespace is applied
+        tools = await mcp.list_tools()
+        assert {t.name for t in tools} == {"sub_sub_tool"}
+
+    async def test_lifespan_server_mounted_directly(self):
+        """Test that servers with lifespan are mounted directly (not auto-proxied).
+
+        Since FastMCPProvider now handles lifespan via the provider lifespan interface,
+        there's no need to auto-convert to a proxy. The server is mounted directly.
+        """
+
+        @asynccontextmanager
+        async def server_lifespan(mcp: FastMCP):
+            yield
+
+        mcp = FastMCP("Main")
+        sub = FastMCP("Sub", lifespan=server_lifespan)
+
+        @sub.tool
+        def sub_tool() -> str:
+            return "test"
+
+        mcp.mount(sub, "sub")
+
+        # Server should be mounted directly without auto-proxying
+        # Index 1 because LocalProvider is at index 0
+        provider = mcp.providers[1]
+        # Provider is wrapped with Namespace transform
+        assert isinstance(provider, _WrappedProvider)
+        assert len(provider._transforms) == 1
+        assert isinstance(provider._transforms[0], Namespace)
+        # Inner provider is FastMCPProvider
+        assert isinstance(provider._inner, FastMCPProvider)
+        assert provider._inner.server is sub
+        # Verify namespace is applied
+        tools = await mcp.list_tools()
+        assert {t.name for t in tools} == {"sub_sub_tool"}
+
+    async def test_mounting_a_proxy_preserves_the_proxy(self):
+        mcp = FastMCP("Main")
+        sub = FastMCP("Sub")
+        sub_proxy = create_proxy(FastMCPTransport(sub))
+
+        mcp.mount(sub_proxy, "sub")
+
+        # Index 1 because LocalProvider is at index 0
+        provider = mcp.providers[1]
+        # Provider is wrapped with Namespace transform
+        assert isinstance(provider, _WrappedProvider)
+        assert len(provider._transforms) == 1
+        assert isinstance(provider._transforms[0], Namespace)
+        # Inner provider is FastMCPProvider
+        assert isinstance(provider._inner, FastMCPProvider)
+        assert provider._inner.server is sub_proxy
+
+    async def test_mounts_have_live_link(self):
+        mcp = FastMCP("Main")
+        sub = FastMCP("Sub")
+
+        mcp.mount(sub, "sub")
+
+        assert len(await mcp.list_tools()) == 0
+
+        @sub.tool
+        def hello():
+            return "hi"
+
+        assert len(await mcp.list_tools()) == 1
+
+    async def test_sub_lifespan_is_executed(self):
+        lifespan_check = []
+
+        @asynccontextmanager
+        async def lifespan(mcp: FastMCP):
+            lifespan_check.append("start")
+            yield
+
+        mcp = FastMCP("Main")
+        sub = FastMCP("Sub", lifespan=lifespan)
+
+        @sub.tool
+        def hello():
+            return "hi"
+
+        mcp.mount(sub)
+
+        assert lifespan_check == []
+
+        async with Client(mcp) as client:
+            await client.call_tool("hello", {})
+
+        # Lifespan is executed at least once (may be multiple times for proxy connections)
+        assert len(lifespan_check) >= 1
+        assert all(x == "start" for x in lifespan_check)
diff --git a/tests/server/mount/test_resources.py b/tests/server/mount/test_resources.py
new file mode 100644
index 0000000..06e2ce5
--- /dev/null
+++ b/tests/server/mount/test_resources.py
@@ -0,0 +1,215 @@
+"""Tests for resource and template mounting."""
+
+import json
+
+from fastmcp import FastMCP
+
+
+class TestResourcesAndTemplates:
+    """Test mounting with resources and resource templates."""
+
+    async def test_mount_with_resources(self):
+        """Test mounting a server with resources."""
+        main_app = FastMCP("MainApp")
+        data_app = FastMCP("DataApp")
+
+        @data_app.resource(uri="data://users")
+        async def get_users() -> str:
+            return "user1, user2"
+
+        # Mount the data app
+        main_app.mount(data_app, "data")
+
+        # Resource should be accessible through main app
+        resources = await main_app.list_resources()
+        assert any(str(r.uri) == "data://data/users" for r in resources)
+
+        # Check that resource can be accessed
+        result = await main_app.read_resource("data://data/users")
+        assert len(result.contents) == 1
+        # Note: The function returns "user1, user2" which is not valid JSON
+        # This test should be updated to return proper JSON or check the string directly
+        assert result.contents[0].content == "user1, user2"
+
+    async def test_mount_with_resource_templates(self):
+        """Test mounting a server with resource templates."""
+        main_app = FastMCP("MainApp")
+        user_app = FastMCP("UserApp")
+
+        @user_app.resource(uri="users://{user_id}/profile")
+        def get_user_profile(user_id: str) -> str:
+            return json.dumps({"id": user_id, "name": f"User {user_id}"})
+
+        # Mount the user app
+        main_app.mount(user_app, "api")
+
+        # Template should be accessible through main app
+        templates = await main_app.list_resource_templates()
+        assert any(t.uri_template == "users://api/{user_id}/profile" for t in templates)
+
+        # Check template instantiation
+        result = await main_app.read_resource("users://api/123/profile")
+        assert len(result.contents) == 1
+        profile = json.loads(result.contents[0].content)
+        assert profile["id"] == "123"
+        assert profile["name"] == "User 123"
+
+    async def test_mount_with_wildcard_resource_template(self):
+        """Wildcard `{name*}` params must survive round-trip through a namespaced mount."""
+        main_app = FastMCP("MainApp")
+        sub_app = FastMCP("SubApp")
+
+        @sub_app.resource("resource://multi/{extra*}")
+        def multi(extra: str) -> str:
+            return extra
+
+        main_app.mount(sub_app, namespace="sub")
+
+        result = await main_app.read_resource("resource://sub/multi/abc/def")
+        assert result.contents[0].content == "abc/def"
+
+        result = await main_app.read_resource("resource://sub/multi/abc")
+        assert result.contents[0].content == "abc"
+
+    async def test_adding_resource_after_mounting(self):
+        """Test adding a resource after mounting."""
+        main_app = FastMCP("MainApp")
+        data_app = FastMCP("DataApp")
+
+        # Mount the data app before adding resources
+        main_app.mount(data_app, "data")
+
+        # Add a resource after mounting
+        @data_app.resource(uri="data://config")
+        def get_config() -> str:
+            return json.dumps({"version": "1.0"})
+
+        # Resource should be accessible through main app
+        resources = await main_app.list_resources()
+        assert any(str(r.uri) == "data://data/config" for r in resources)
+
+        # Check access to the resource
+        result = await main_app.read_resource("data://data/config")
+        assert len(result.contents) == 1
+        config = json.loads(result.contents[0].content)
+        assert config["version"] == "1.0"
+
+
+class TestResourceUriPrefixing:
+    """Test that resource and resource template URIs get prefixed when mounted (names are NOT prefixed)."""
+
+    async def test_resource_uri_prefixing(self):
+        """Test that resource URIs are prefixed when mounted (names are NOT prefixed)."""
+
+        # Create a sub-app with a resource
+        sub_app = FastMCP("SubApp")
+
+        @sub_app.resource("resource://my_resource")
+        def my_resource() -> str:
+            return "Resource content"
+
+        # Create main app and mount sub-app with prefix
+        main_app = FastMCP("MainApp")
+        main_app.mount(sub_app, "prefix")
+
+        # Get resources from main app
+        resources = await main_app.list_resources()
+
+        # Should have prefixed key (using path format: resource://prefix/resource_name)
+        assert any(str(r.uri) == "resource://prefix/my_resource" for r in resources)
+
+        # The resource name should NOT be prefixed (only URI is prefixed)
+        resource = next(
+            r for r in resources if str(r.uri) == "resource://prefix/my_resource"
+        )
+        assert resource.name == "my_resource"
+
+    async def test_resource_template_uri_prefixing(self):
+        """Test that resource template URIs are prefixed when mounted (names are NOT prefixed)."""
+
+        # Create a sub-app with a resource template
+        sub_app = FastMCP("SubApp")
+
+        @sub_app.resource("resource://user/{user_id}")
+        def user_template(user_id: str) -> str:
+            return f"User {user_id} data"
+
+        # Create main app and mount sub-app with prefix
+        main_app = FastMCP("MainApp")
+        main_app.mount(sub_app, "prefix")
+
+        # Get resource templates from main app
+        templates = await main_app.list_resource_templates()
+
+        # Should have prefixed key (using path format: resource://prefix/template_uri)
+        assert any(
+            t.uri_template == "resource://prefix/user/{user_id}" for t in templates
+        )
+
+        # The template name should NOT be prefixed (only URI template is prefixed)
+        template = next(
+            t for t in templates if t.uri_template == "resource://prefix/user/{user_id}"
+        )
+        assert template.name == "user_template"
+
+
+class TestMountedResourceTemplateQueryParams:
+    """Test that resource templates with query params work on mounted servers."""
+
+    async def test_mounted_template_with_query_param(self):
+        """Query params in resource templates should work through mount."""
+        sub = FastMCP("Sub")
+
+        @sub.resource("resource://greet{?name}")
+        def greet(name: str = "World") -> str:
+            return f"Hello, {name}!"
+
+        main = FastMCP("Main")
+        main.mount(sub, "sub")
+
+        result = await main.read_resource("resource://sub/greet?name=Alice")
+        assert result.contents[0].content == "Hello, Alice!"
+
+    async def test_mounted_template_with_query_param_default(self):
+        """Missing query params should use defaults through mount."""
+        sub = FastMCP("Sub")
+
+        @sub.resource("resource://greet{?name}")
+        def greet(name: str = "World") -> str:
+            return f"Hello, {name}!"
+
+        main = FastMCP("Main")
+        main.mount(sub, "sub")
+
+        result = await main.read_resource("resource://sub/greet")
+        assert result.contents[0].content == "Hello, World!"
+
+    async def test_mounted_template_with_multiple_query_params(self):
+        """Multiple query params should all pass through mount correctly."""
+        sub = FastMCP("Sub")
+
+        @sub.resource("resource://data/{id}{?format,verbose}")
+        def get_data(id: str, format: str = "json", verbose: bool = False) -> str:
+            return f"id={id} format={format} verbose={verbose}"
+
+        main = FastMCP("Main")
+        main.mount(sub, "api")
+
+        result = await main.read_resource(
+            "resource://api/data/42?format=xml&verbose=true"
+        )
+        assert result.contents[0].content == "id=42 format=xml verbose=True"
+
+    async def test_mounted_template_with_partial_query_params(self):
+        """Providing only some query params should use defaults for the rest."""
+        sub = FastMCP("Sub")
+
+        @sub.resource("resource://data/{id}{?format,limit}")
+        def get_data(id: str, format: str = "json", limit: int = 10) -> str:
+            return f"id={id} format={format} limit={limit}"
+
+        main = FastMCP("Main")
+        main.mount(sub, "api")
+
+        result = await main.read_resource("resource://api/data/42?limit=5")
+        assert result.contents[0].content == "id=42 format=json limit=5"
diff --git a/tests/server/providers/__init__.py b/tests/server/providers/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/server/providers/local_provider_tools/__init__.py b/tests/server/providers/local_provider_tools/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/server/providers/local_provider_tools/test_context.py b/tests/server/providers/local_provider_tools/test_context.py
new file mode 100644
index 0000000..2bd84c3
--- /dev/null
+++ b/tests/server/providers/local_provider_tools/test_context.py
@@ -0,0 +1,162 @@
+"""Tests for tool context injection."""
+
+import functools
+from dataclasses import dataclass
+
+from pydantic import BaseModel
+from typing_extensions import TypedDict
+
+from fastmcp import Context, FastMCP
+from fastmcp.tools.base import Tool
+
+
+def _normalize_anyof_order(schema):
+    """Normalize the order of items in anyOf arrays for consistent comparison."""
+    if isinstance(schema, dict):
+        if "anyOf" in schema:
+            schema = schema.copy()
+            schema["anyOf"] = sorted(schema["anyOf"], key=str)
+        return {k: _normalize_anyof_order(v) for k, v in schema.items()}
+    elif isinstance(schema, list):
+        return [_normalize_anyof_order(item) for item in schema]
+    return schema
+
+
+class PersonTypedDict(TypedDict):
+    name: str
+    age: int
+
+
+class PersonModel(BaseModel):
+    name: str
+    age: int
+
+
+@dataclass
+class PersonDataclass:
+    name: str
+    age: int
+
+
+class TestToolContextInjection:
+    """Test context injection in tools."""
+
+    async def test_context_detection(self):
+        """Test that context parameters are properly detected and excluded from schema."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def tool_with_context(x: int, ctx: Context) -> str:
+            return f"Request: {x}"
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+        assert tools[0].name == "tool_with_context"
+        # Context param should not appear in schema
+        assert "ctx" not in tools[0].parameters.get("properties", {})
+
+    async def test_context_injection_basic(self):
+        """Test that context is properly injected into tool calls."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def tool_with_context(x: int, ctx: Context) -> str:
+            assert isinstance(ctx, Context)
+            return f"Got context with x={x}"
+
+        result = await mcp.call_tool("tool_with_context", {"x": 42})
+        assert result.structured_content == {"result": "Got context with x=42"}
+
+    async def test_async_context(self):
+        """Test that context works in async functions."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        async def async_tool(x: int, ctx: Context) -> str:
+            assert isinstance(ctx, Context)
+            return f"Async with x={x}"
+
+        result = await mcp.call_tool("async_tool", {"x": 42})
+        assert result.structured_content == {"result": "Async with x=42"}
+
+    async def test_optional_context(self):
+        """Test that context is optional."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def no_context(x: int) -> int:
+            return x * 2
+
+        result = await mcp.call_tool("no_context", {"x": 21})
+        assert result.structured_content == {"result": 42}
+
+    async def test_context_resource_access(self):
+        """Test that context can access resources."""
+        mcp = FastMCP()
+
+        @mcp.resource("test://data")
+        def test_resource() -> str:
+            return "resource data"
+
+        @mcp.tool
+        async def tool_with_resource(ctx: Context) -> str:
+            result = await ctx.read_resource("test://data")
+            assert len(result.contents) == 1
+            r = result.contents[0]
+            return f"Read resource: {r.content} with mime type {r.mime_type}"
+
+        result = await mcp.call_tool("tool_with_resource", {})
+        assert result.structured_content == {
+            "result": "Read resource: resource data with mime type text/plain"
+        }
+
+    async def test_tool_decorator_with_tags(self):
+        """Test that the tool decorator properly sets tags."""
+        mcp = FastMCP()
+
+        @mcp.tool(tags={"example", "test-tag"})
+        def sample_tool(x: int) -> int:
+            return x * 2
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+        assert tools[0].tags == {"example", "test-tag"}
+
+    async def test_callable_object_with_context(self):
+        """Test that a callable object can be used as a tool with context."""
+        mcp = FastMCP()
+
+        class MyTool:
+            async def __call__(self, x: int, ctx: Context) -> int:
+                assert isinstance(ctx, Context)
+                return x + 1
+
+        mcp.add_tool(Tool.from_function(MyTool(), name="MyTool"))
+
+        result = await mcp.call_tool("MyTool", {"x": 2})
+        assert result.structured_content == {"result": 3}
+
+    async def test_decorated_tool_with_functools_wraps(self):
+        """Regression test for #2524: @mcp.tool with functools.wraps decorator."""
+
+        def custom_decorator(func):
+            @functools.wraps(func)
+            async def wrapper(*args, **kwargs):
+                return await func(*args, **kwargs)
+
+            return wrapper
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        @custom_decorator
+        async def decorated_tool(ctx: Context, query: str) -> str:
+            assert isinstance(ctx, Context)
+            return f"query: {query}"
+
+        tools = await mcp.list_tools()
+        tool = next(t for t in tools if t.name == "decorated_tool")
+        assert "ctx" not in tool.parameters.get("properties", {})
+
+        result = await mcp.call_tool("decorated_tool", {"query": "test"})
+        assert result.structured_content == {"result": "query: test"}
diff --git a/tests/server/providers/local_provider_tools/test_decorator.py b/tests/server/providers/local_provider_tools/test_decorator.py
new file mode 100644
index 0000000..3bf490d
--- /dev/null
+++ b/tests/server/providers/local_provider_tools/test_decorator.py
@@ -0,0 +1,341 @@
+"""Tests for tool decorator patterns."""
+
+from dataclasses import dataclass
+from typing import Annotated
+
+import pytest
+from pydantic import BaseModel, Field
+from typing_extensions import TypedDict
+
+from fastmcp import FastMCP
+from fastmcp.exceptions import NotFoundError
+from fastmcp.tools.base import Tool
+
+
+def _normalize_anyof_order(schema):
+    """Normalize the order of items in anyOf arrays for consistent comparison."""
+    if isinstance(schema, dict):
+        if "anyOf" in schema:
+            schema = schema.copy()
+            schema["anyOf"] = sorted(schema["anyOf"], key=str)
+        return {k: _normalize_anyof_order(v) for k, v in schema.items()}
+    elif isinstance(schema, list):
+        return [_normalize_anyof_order(item) for item in schema]
+    return schema
+
+
+class PersonTypedDict(TypedDict):
+    name: str
+    age: int
+
+
+class PersonModel(BaseModel):
+    name: str
+    age: int
+
+
+@dataclass
+class PersonDataclass:
+    name: str
+    age: int
+
+
+class TestToolDecorator:
+    async def test_no_tools_before_decorator(self):
+        mcp = FastMCP()
+
+        with pytest.raises(NotFoundError, match="Unknown tool: 'add'"):
+            await mcp.call_tool("add", {"x": 1, "y": 2})
+
+    async def test_tool_decorator(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def add(x: int, y: int) -> int:
+            return x + y
+
+        result = await mcp.call_tool("add", {"x": 1, "y": 2})
+        assert result.structured_content == {"result": 3}
+
+    async def test_tool_decorator_without_parentheses(self):
+        """Test that @tool decorator works without parentheses."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def add(x: int, y: int) -> int:
+            return x + y
+
+        tools = await mcp.list_tools()
+        assert any(t.name == "add" for t in tools)
+
+        result = await mcp.call_tool("add", {"x": 1, "y": 2})
+        assert result.structured_content == {"result": 3}
+
+    async def test_tool_decorator_with_name(self):
+        mcp = FastMCP()
+
+        @mcp.tool(name="custom-add")
+        def add(x: int, y: int) -> int:
+            return x + y
+
+        result = await mcp.call_tool("custom-add", {"x": 1, "y": 2})
+        assert result.structured_content == {"result": 3}
+
+    async def test_tool_decorator_with_description(self):
+        mcp = FastMCP()
+
+        @mcp.tool(description="Add two numbers")
+        def add(x: int, y: int) -> int:
+            return x + y
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+        tool = tools[0]
+        assert tool.description == "Add two numbers"
+
+    async def test_tool_decorator_instance_method(self):
+        mcp = FastMCP()
+
+        class MyClass:
+            def __init__(self, x: int):
+                self.x = x
+
+            def add(self, y: int) -> int:
+                return self.x + y
+
+        obj = MyClass(10)
+        mcp.add_tool(Tool.from_function(obj.add))
+        result = await mcp.call_tool("add", {"y": 2})
+        assert result.structured_content == {"result": 12}
+
+    async def test_tool_decorator_classmethod(self):
+        mcp = FastMCP()
+
+        class MyClass:
+            x: int = 10
+
+            @classmethod
+            def add(cls, y: int) -> int:
+                return cls.x + y
+
+        mcp.add_tool(Tool.from_function(MyClass.add))
+        result = await mcp.call_tool("add", {"y": 2})
+        assert result.structured_content == {"result": 12}
+
+    async def test_tool_decorator_staticmethod(self):
+        mcp = FastMCP()
+
+        class MyClass:
+            @mcp.tool
+            @staticmethod
+            def add(x: int, y: int) -> int:
+                return x + y
+
+        result = await mcp.call_tool("add", {"x": 1, "y": 2})
+        assert result.structured_content == {"result": 3}
+
+    async def test_tool_decorator_async_function(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        async def add(x: int, y: int) -> int:
+            return x + y
+
+        result = await mcp.call_tool("add", {"x": 1, "y": 2})
+        assert result.structured_content == {"result": 3}
+
+    async def test_tool_decorator_classmethod_error(self):
+        mcp = FastMCP()
+
+        with pytest.raises(TypeError, match="classmethod"):
+
+            class MyClass:
+                @mcp.tool
+                @classmethod
+                def add(cls, y: int) -> None:
+                    pass
+
+    async def test_tool_decorator_classmethod_async_function(self):
+        mcp = FastMCP()
+
+        class MyClass:
+            x = 10
+
+            @classmethod
+            async def add(cls, y: int) -> int:
+                return cls.x + y
+
+        mcp.add_tool(Tool.from_function(MyClass.add))
+        result = await mcp.call_tool("add", {"y": 2})
+        assert result.structured_content == {"result": 12}
+
+    async def test_tool_decorator_staticmethod_async_function(self):
+        mcp = FastMCP()
+
+        class MyClass:
+            @staticmethod
+            async def add(x: int, y: int) -> int:
+                return x + y
+
+        mcp.add_tool(Tool.from_function(MyClass.add))
+        result = await mcp.call_tool("add", {"x": 1, "y": 2})
+        assert result.structured_content == {"result": 3}
+
+    async def test_tool_decorator_staticmethod_order(self):
+        """Test that the recommended decorator order works for static methods"""
+        mcp = FastMCP()
+
+        class MyClass:
+            @mcp.tool
+            @staticmethod
+            def add_v1(x: int, y: int) -> int:
+                return x + y
+
+        result = await mcp.call_tool("add_v1", {"x": 1, "y": 2})
+        assert result.structured_content == {"result": 3}
+
+    async def test_tool_decorator_with_tags(self):
+        """Test that the tool decorator properly sets tags."""
+        mcp = FastMCP()
+
+        @mcp.tool(tags={"example", "test-tag"})
+        def sample_tool(x: int) -> int:
+            return x * 2
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+        assert tools[0].tags == {"example", "test-tag"}
+
+    async def test_add_tool_with_custom_name(self):
+        """Test adding a tool with a custom name using server.add_tool()."""
+        mcp = FastMCP()
+
+        def multiply(a: int, b: int) -> int:
+            """Multiply two numbers."""
+            return a * b
+
+        mcp.add_tool(Tool.from_function(multiply, name="custom_multiply"))
+
+        tools = await mcp.list_tools()
+        assert any(t.name == "custom_multiply" for t in tools)
+
+        result = await mcp.call_tool("custom_multiply", {"a": 5, "b": 3})
+        assert result.structured_content == {"result": 15}
+
+        assert not any(t.name == "multiply" for t in tools)
+
+    async def test_tool_with_annotated_arguments(self):
+        """Test that tools with annotated arguments work correctly."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def add(
+            x: Annotated[int, Field(description="x is an int")],
+            y: Annotated[str, Field(description="y is not an int")],
+        ) -> None:
+            pass
+
+        tools = await mcp.list_tools()
+        tool = next(t for t in tools if t.name == "add")
+        assert tool.parameters["properties"]["x"]["description"] == "x is an int"
+        assert tool.parameters["properties"]["y"]["description"] == "y is not an int"
+
+    async def test_tool_with_field_defaults(self):
+        """Test that tools with annotated arguments work correctly."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def add(
+            x: int = Field(description="x is an int"),
+            y: str = Field(description="y is not an int"),
+        ) -> None:
+            pass
+
+        tools = await mcp.list_tools()
+        tool = next(t for t in tools if t.name == "add")
+        assert tool.parameters["properties"]["x"]["description"] == "x is an int"
+        assert tool.parameters["properties"]["y"]["description"] == "y is not an int"
+
+    async def test_tool_direct_function_call(self):
+        """Test that tools can be registered via direct function call."""
+        from typing import cast
+
+        from fastmcp.tools.function_tool import DecoratedTool
+
+        mcp = FastMCP()
+
+        def standalone_function(x: int, y: int) -> int:
+            """A standalone function to be registered."""
+            return x + y
+
+        result_fn = mcp.tool(standalone_function, name="direct_call_tool")
+
+        # In new decorator mode, returns the function with metadata
+        decorated = cast(DecoratedTool, result_fn)
+        assert hasattr(result_fn, "__fastmcp__")
+        assert decorated.__fastmcp__.name == "direct_call_tool"
+        assert result_fn is standalone_function
+
+        tools = await mcp.list_tools()
+        tool = next(t for t in tools if t.name == "direct_call_tool")
+        # Tool is registered separately, not same object as decorated function
+        assert tool.name == "direct_call_tool"
+
+        result = await mcp.call_tool("direct_call_tool", {"x": 5, "y": 3})
+        assert result.structured_content == {"result": 8}
+
+    async def test_tool_decorator_with_string_name(self):
+        """Test that @tool("custom_name") syntax works correctly."""
+        mcp = FastMCP()
+
+        @mcp.tool("string_named_tool")
+        def my_function(x: int) -> str:
+            """A function with a string name."""
+            return f"Result: {x}"
+
+        tools = await mcp.list_tools()
+        assert any(t.name == "string_named_tool" for t in tools)
+        assert not any(t.name == "my_function" for t in tools)
+
+        result = await mcp.call_tool("string_named_tool", {"x": 42})
+        assert result.structured_content == {"result": "Result: 42"}
+
+    async def test_tool_decorator_conflicting_names_error(self):
+        """Test that providing both positional and keyword name raises an error."""
+        mcp = FastMCP()
+
+        with pytest.raises(
+            TypeError,
+            match="Cannot specify both a name as first argument and as keyword argument",
+        ):
+
+            @mcp.tool("positional_name", name="keyword_name")
+            def my_function(x: int) -> str:
+                return f"Result: {x}"
+
+    async def test_tool_decorator_with_output_schema(self):
+        mcp = FastMCP()
+
+        with pytest.raises(
+            ValueError, match="Output schemas must represent object types"
+        ):
+
+            @mcp.tool(output_schema={"type": "integer"})
+            def my_function(x: int) -> str:
+                return f"Result: {x}"
+
+    async def test_tool_decorator_with_meta(self):
+        """Test that meta parameter is passed through the tool decorator."""
+        mcp = FastMCP()
+
+        meta_data = {"version": "1.0", "author": "test"}
+
+        @mcp.tool(meta=meta_data)
+        def multiply(a: int, b: int) -> int:
+            """Multiply two numbers."""
+            return a * b
+
+        tools = await mcp.list_tools()
+        tool = next(t for t in tools if t.name == "multiply")
+
+        assert tool.meta == meta_data
diff --git a/tests/server/providers/local_provider_tools/test_enabled.py b/tests/server/providers/local_provider_tools/test_enabled.py
new file mode 100644
index 0000000..aee0c4b
--- /dev/null
+++ b/tests/server/providers/local_provider_tools/test_enabled.py
@@ -0,0 +1,132 @@
+"""Tests for tool enabled/disabled state."""
+
+from dataclasses import dataclass
+
+import pytest
+from pydantic import BaseModel
+from typing_extensions import TypedDict
+
+from fastmcp import FastMCP
+from fastmcp.exceptions import NotFoundError
+
+
+def _normalize_anyof_order(schema):
+    """Normalize the order of items in anyOf arrays for consistent comparison."""
+    if isinstance(schema, dict):
+        if "anyOf" in schema:
+            schema = schema.copy()
+            schema["anyOf"] = sorted(schema["anyOf"], key=str)
+        return {k: _normalize_anyof_order(v) for k, v in schema.items()}
+    elif isinstance(schema, list):
+        return [_normalize_anyof_order(item) for item in schema]
+    return schema
+
+
+class PersonTypedDict(TypedDict):
+    name: str
+    age: int
+
+
+class PersonModel(BaseModel):
+    name: str
+    age: int
+
+
+@dataclass
+class PersonDataclass:
+    name: str
+    age: int
+
+
+class TestToolEnabled:
+    async def test_toggle_enabled(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def sample_tool(x: int) -> int:
+            return x * 2
+
+        # Tool is enabled by default
+        tools = await mcp.list_tools()
+        assert any(t.name == "sample_tool" for t in tools)
+
+        # Disable via server
+        mcp.disable(names={"sample_tool"}, components={"tool"})
+
+        # Tool should not be in list when disabled
+        tools = await mcp.list_tools()
+        assert not any(t.name == "sample_tool" for t in tools)
+
+        # Re-enable via server
+        mcp.enable(names={"sample_tool"}, components={"tool"})
+        tools = await mcp.list_tools()
+        assert any(t.name == "sample_tool" for t in tools)
+
+    async def test_tool_disabled_via_server(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def sample_tool(x: int) -> int:
+            return x * 2
+
+        mcp.disable(names={"sample_tool"}, components={"tool"})
+        tools = await mcp.list_tools()
+        assert len(tools) == 0
+
+        with pytest.raises(NotFoundError, match="Unknown tool"):
+            await mcp.call_tool("sample_tool", {"x": 5})
+
+    async def test_tool_toggle_enabled(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def sample_tool(x: int) -> int:
+            return x * 2
+
+        mcp.disable(names={"sample_tool"}, components={"tool"})
+        mcp.enable(names={"sample_tool"}, components={"tool"})
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+
+    async def test_tool_toggle_disabled(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def sample_tool(x: int) -> int:
+            return x * 2
+
+        mcp.disable(names={"sample_tool"}, components={"tool"})
+        tools = await mcp.list_tools()
+        assert len(tools) == 0
+
+        with pytest.raises(NotFoundError, match="Unknown tool"):
+            await mcp.call_tool("sample_tool", {"x": 5})
+
+    async def test_get_tool_and_disable(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def sample_tool(x: int) -> int:
+            return x * 2
+
+        tool = await mcp.get_tool("sample_tool")
+        assert tool is not None
+
+        mcp.disable(names={"sample_tool"}, components={"tool"})
+        tools = await mcp.list_tools()
+        assert len(tools) == 0
+
+        with pytest.raises(NotFoundError, match="Unknown tool"):
+            await mcp.call_tool("sample_tool", {"x": 5})
+
+    async def test_cant_call_disabled_tool(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def sample_tool(x: int) -> int:
+            return x * 2
+
+        mcp.disable(names={"sample_tool"}, components={"tool"})
+
+        with pytest.raises(NotFoundError, match="Unknown tool"):
+            await mcp.call_tool("sample_tool", {"x": 5})
diff --git a/tests/server/providers/local_provider_tools/test_local_provider_tools.py b/tests/server/providers/local_provider_tools/test_local_provider_tools.py
new file mode 100644
index 0000000..c42f80c
--- /dev/null
+++ b/tests/server/providers/local_provider_tools/test_local_provider_tools.py
@@ -0,0 +1,276 @@
+"""Core tool return types and serialization tests."""
+
+import base64
+import datetime
+import json
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+
+from mcp_types import (
+    AudioContent,
+    EmbeddedResource,
+    ImageContent,
+    TextContent,
+)
+from pydantic import BaseModel
+from typing_extensions import TypedDict
+
+from fastmcp import FastMCP
+from fastmcp.utilities.types import Audio, File, Image
+
+
+def _normalize_anyof_order(schema):
+    """Normalize the order of items in anyOf arrays for consistent comparison."""
+    if isinstance(schema, dict):
+        if "anyOf" in schema:
+            schema = schema.copy()
+            schema["anyOf"] = sorted(schema["anyOf"], key=str)
+        return {k: _normalize_anyof_order(v) for k, v in schema.items()}
+    elif isinstance(schema, list):
+        return [_normalize_anyof_order(item) for item in schema]
+    return schema
+
+
+class PersonTypedDict(TypedDict):
+    name: str
+    age: int
+
+
+class PersonModel(BaseModel):
+    name: str
+    age: int
+
+
+@dataclass
+class PersonDataclass:
+    name: str
+    age: int
+
+
+class TestToolReturnTypes:
+    async def test_string(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def string_tool() -> str:
+            return "Hello, world!"
+
+        result = await mcp.call_tool("string_tool", {})
+        assert result.structured_content == {"result": "Hello, world!"}
+
+    async def test_bytes(self, tmp_path: Path):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def bytes_tool() -> bytes:
+            return b"Hello, world!"
+
+        result = await mcp.call_tool("bytes_tool", {})
+        # bytes can't be represented as structured JSON, so no structured_content
+        assert result.structured_content is None
+        assert result.content[0].text == "Hello, world!"  # ty:ignore[unresolved-attribute]
+
+    async def test_uuid(self):
+        mcp = FastMCP()
+
+        test_uuid = uuid.uuid4()
+
+        @mcp.tool
+        def uuid_tool() -> uuid.UUID:
+            return test_uuid
+
+        result = await mcp.call_tool("uuid_tool", {})
+        assert result.structured_content == {"result": str(test_uuid)}
+
+    async def test_path(self):
+        mcp = FastMCP()
+
+        test_path = Path("/tmp/test.txt")
+
+        @mcp.tool
+        def path_tool() -> Path:
+            return test_path
+
+        result = await mcp.call_tool("path_tool", {})
+        assert result.structured_content == {"result": str(test_path)}
+
+    async def test_datetime(self):
+        mcp = FastMCP()
+
+        dt = datetime.datetime(2025, 4, 25, 1, 2, 3)
+
+        @mcp.tool
+        def datetime_tool() -> datetime.datetime:
+            return dt
+
+        result = await mcp.call_tool("datetime_tool", {})
+        assert result.structured_content == {"result": dt.isoformat()}
+
+    async def test_image(self, tmp_path: Path):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def image_tool(path: str) -> Image:
+            return Image(path)
+
+        image_path = tmp_path / "test.png"
+        image_path.write_bytes(b"fake png data")
+
+        result = await mcp.call_tool("image_tool", {"path": str(image_path)})
+        assert result.structured_content is None
+        assert isinstance(result.content, list)
+        content = result.content[0]
+        assert isinstance(content, ImageContent)
+        assert content.type == "image"
+        assert content.mime_type == "image/png"
+        decoded = base64.b64decode(content.data)
+        assert decoded == b"fake png data"
+
+    async def test_audio(self, tmp_path: Path):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def audio_tool(path: str) -> Audio:
+            return Audio(path)
+
+        audio_path = tmp_path / "test.wav"
+        audio_path.write_bytes(b"fake wav data")
+
+        result = await mcp.call_tool("audio_tool", {"path": str(audio_path)})
+        assert isinstance(result.content, list)
+        content = result.content[0]
+        assert isinstance(content, AudioContent)
+        assert content.type == "audio"
+        assert content.mime_type == "audio/wav"
+        decoded = base64.b64decode(content.data)
+        assert decoded == b"fake wav data"
+
+    async def test_file(self, tmp_path: Path):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def file_tool(path: str) -> File:
+            return File(path)
+
+        file_path = tmp_path / "test.bin"
+        file_path.write_bytes(b"test file data")
+
+        result = await mcp.call_tool("file_tool", {"path": str(file_path)})
+        assert isinstance(result.content, list)
+        content = result.content[0]
+        assert isinstance(content, EmbeddedResource)
+        assert content.type == "resource"
+        resource = content.resource
+        assert resource.mime_type == "application/octet-stream"
+        assert hasattr(resource, "blob")
+        blob_data = getattr(resource, "blob")
+        decoded = base64.b64decode(blob_data)
+        assert decoded == b"test file data"
+        assert str(resource.uri) == file_path.resolve().as_uri()
+
+    async def test_tool_mixed_content(self, tool_server: FastMCP):
+        result = await tool_server.call_tool("mixed_content_tool", {})
+        assert isinstance(result.content, list)
+        assert len(result.content) == 3
+        content1 = result.content[0]
+        content2 = result.content[1]
+        content3 = result.content[2]
+        assert isinstance(content1, TextContent)
+        assert content1.text == "Hello"
+        assert isinstance(content2, ImageContent)
+        assert content2.mime_type == "application/octet-stream"
+        assert content2.data == "abc"
+        assert isinstance(content3, EmbeddedResource)
+        assert content3.type == "resource"
+        resource = content3.resource
+        assert resource.mime_type == "application/octet-stream"
+        assert hasattr(resource, "blob")
+        blob_data = getattr(resource, "blob")
+        decoded = base64.b64decode(blob_data)
+        assert decoded == b"abc"
+
+    async def test_tool_mixed_list_with_image(
+        self, tool_server: FastMCP, tmp_path: Path
+    ):
+        """Test that lists containing Image objects and other types are handled
+        correctly. Items now preserve their original order."""
+        image_path = tmp_path / "test.png"
+        image_path.write_bytes(b"test image data")
+
+        result = await tool_server.call_tool(
+            "mixed_list_fn", {"image_path": str(image_path)}
+        )
+        assert isinstance(result.content, list)
+        assert len(result.content) == 4
+        content1 = result.content[0]
+        assert isinstance(content1, TextContent)
+        assert content1.text == "text message"
+        content2 = result.content[1]
+        assert isinstance(content2, ImageContent)
+        assert content2.mime_type == "image/png"
+        assert base64.b64decode(content2.data) == b"test image data"
+        content3 = result.content[2]
+        assert isinstance(content3, TextContent)
+        assert json.loads(content3.text) == {"key": "value"}
+        content4 = result.content[3]
+        assert isinstance(content4, TextContent)
+        assert content4.text == "direct content"
+
+    async def test_tool_mixed_list_with_audio(
+        self, tool_server: FastMCP, tmp_path: Path
+    ):
+        """Test that lists containing Audio objects and other types are handled
+        correctly. Items now preserve their original order."""
+        audio_path = tmp_path / "test.wav"
+        audio_path.write_bytes(b"test audio data")
+
+        result = await tool_server.call_tool(
+            "mixed_audio_list_fn", {"audio_path": str(audio_path)}
+        )
+        assert isinstance(result.content, list)
+        assert len(result.content) == 4
+        content1 = result.content[0]
+        assert isinstance(content1, TextContent)
+        assert content1.text == "text message"
+        content2 = result.content[1]
+        assert isinstance(content2, AudioContent)
+        assert content2.mime_type == "audio/wav"
+        assert base64.b64decode(content2.data) == b"test audio data"
+        content3 = result.content[2]
+        assert isinstance(content3, TextContent)
+        assert json.loads(content3.text) == {"key": "value"}
+        content4 = result.content[3]
+        assert isinstance(content4, TextContent)
+        assert content4.text == "direct content"
+
+    async def test_tool_mixed_list_with_file(
+        self, tool_server: FastMCP, tmp_path: Path
+    ):
+        """Test that lists containing File objects and other types are handled
+        correctly. Items now preserve their original order."""
+        file_path = tmp_path / "test.bin"
+        file_path.write_bytes(b"test file data")
+
+        result = await tool_server.call_tool(
+            "mixed_file_list_fn", {"file_path": str(file_path)}
+        )
+        assert isinstance(result.content, list)
+        assert len(result.content) == 4
+        content1 = result.content[0]
+        assert isinstance(content1, TextContent)
+        assert content1.text == "text message"
+        content2 = result.content[1]
+        assert isinstance(content2, EmbeddedResource)
+        assert content2.type == "resource"
+        resource = content2.resource
+        assert resource.mime_type == "application/octet-stream"
+        assert hasattr(resource, "blob")
+        blob_data = getattr(resource, "blob")
+        assert base64.b64decode(blob_data) == b"test file data"
+        content3 = result.content[2]
+        assert isinstance(content3, TextContent)
+        assert json.loads(content3.text) == {"key": "value"}
+        content4 = result.content[3]
+        assert isinstance(content4, TextContent)
+        assert content4.text == "direct content"
diff --git a/tests/server/providers/local_provider_tools/test_output_schema.py b/tests/server/providers/local_provider_tools/test_output_schema.py
new file mode 100644
index 0000000..a5f87d4
--- /dev/null
+++ b/tests/server/providers/local_provider_tools/test_output_schema.py
@@ -0,0 +1,405 @@
+"""Tests for tool output schemas."""
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import pytest
+from mcp_types import (
+    TextContent,
+)
+from pydantic import AnyUrl, BaseModel, TypeAdapter
+from typing_extensions import TypeAliasType, TypedDict
+
+from fastmcp import FastMCP
+from fastmcp.tools.base import ToolResult
+from fastmcp.tools.function_parsing import _is_object_schema
+from fastmcp.utilities.json_schema import compress_schema
+
+
+def _normalize_anyof_order(schema):
+    """Normalize the order of items in anyOf arrays for consistent comparison."""
+    if isinstance(schema, dict):
+        if "anyOf" in schema:
+            schema = schema.copy()
+            schema["anyOf"] = sorted(schema["anyOf"], key=str)
+        return {k: _normalize_anyof_order(v) for k, v in schema.items()}
+    elif isinstance(schema, list):
+        return [_normalize_anyof_order(item) for item in schema]
+    return schema
+
+
+class PersonTypedDict(TypedDict):
+    name: str
+    age: int
+
+
+class PersonModel(BaseModel):
+    name: str
+    age: int
+
+
+@dataclass
+class PersonDataclass:
+    name: str
+    age: int
+
+
+class TestToolOutputSchema:
+    @pytest.mark.parametrize("annotation", [str, int, float, bool, list, AnyUrl])
+    async def test_simple_output_schema(self, annotation):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def f() -> annotation:
+            return "hello"
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+
+        type_schema = TypeAdapter(annotation).json_schema()
+        type_schema = compress_schema(type_schema, prune_titles=True)
+        assert tools[0].output_schema == {
+            "type": "object",
+            "properties": {"result": type_schema},
+            "required": ["result"],
+            "x-fastmcp-wrap-result": True,
+        }
+
+    @pytest.mark.parametrize(
+        "annotation",
+        [dict[str, int | str], PersonTypedDict, PersonModel, PersonDataclass],
+    )
+    async def test_structured_output_schema(self, annotation):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def f() -> annotation:
+            return {"name": "John", "age": 30}
+
+        tools = await mcp.list_tools()
+
+        type_schema = compress_schema(
+            TypeAdapter(annotation).json_schema(), prune_titles=True
+        )
+        assert len(tools) == 1
+
+        actual_schema = _normalize_anyof_order(tools[0].output_schema)
+        expected_schema = _normalize_anyof_order(type_schema)
+        assert actual_schema == expected_schema
+
+    async def test_disabled_output_schema_no_structured_content(self):
+        mcp = FastMCP()
+
+        @mcp.tool(output_schema=None)
+        def f() -> int:
+            return 42
+
+        result = await mcp.call_tool("f", {})
+        assert isinstance(result.content, list)
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "42"
+        assert result.structured_content is None
+
+    async def test_manual_structured_content(self):
+        from typing import cast
+
+        from fastmcp.tools.function_tool import DecoratedTool
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def f() -> ToolResult:
+            return ToolResult(
+                content="Hello, world!", structured_content={"message": "Hello, world!"}
+            )
+
+        # In new decorator mode, check metadata instead of attributes
+        from fastmcp.utilities.types import NotSet
+
+        decorated = cast(DecoratedTool, f)
+        assert hasattr(f, "__fastmcp__")
+        assert decorated.__fastmcp__.output_schema is NotSet
+
+        result = await mcp.call_tool("f", {})
+        assert isinstance(result.content, list)
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "Hello, world!"
+        assert result.structured_content == {"message": "Hello, world!"}
+
+    async def test_output_schema_none(self):
+        """Test that output_schema=None works correctly."""
+        mcp = FastMCP()
+
+        @mcp.tool(output_schema=None)
+        def simple_tool() -> int:
+            return 42
+
+        tools = await mcp.list_tools()
+        tool = next(t for t in tools if t.name == "simple_tool")
+        assert tool.output_schema is None
+
+        result = await mcp.call_tool("simple_tool", {})
+        assert result.structured_content is None
+        assert isinstance(result.content, list)
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "42"
+
+    async def test_output_schema_explicit_object(self):
+        """Test explicit object output schema."""
+        mcp = FastMCP()
+
+        @mcp.tool(
+            output_schema={
+                "type": "object",
+                "properties": {
+                    "greeting": {"type": "string"},
+                    "count": {"type": "integer"},
+                },
+                "required": ["greeting"],
+            }
+        )
+        def explicit_tool() -> dict[str, Any]:
+            return {"greeting": "Hello", "count": 42}
+
+        tools = await mcp.list_tools()
+        tool = next(t for t in tools if t.name == "explicit_tool")
+        expected_schema = {
+            "type": "object",
+            "properties": {
+                "greeting": {"type": "string"},
+                "count": {"type": "integer"},
+            },
+            "required": ["greeting"],
+        }
+        assert tool.output_schema == expected_schema
+
+        result = await mcp.call_tool("explicit_tool", {})
+        assert result.structured_content == {"greeting": "Hello", "count": 42}
+
+    async def test_output_schema_wrapped_primitive(self):
+        """Test wrapped primitive output schema."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def primitive_tool() -> str:
+            return "Hello, primitives!"
+
+        tools = await mcp.list_tools()
+        tool = next(t for t in tools if t.name == "primitive_tool")
+        expected_schema = {
+            "type": "object",
+            "properties": {"result": {"type": "string"}},
+            "required": ["result"],
+            "x-fastmcp-wrap-result": True,
+        }
+        assert tool.output_schema == expected_schema
+
+        result = await mcp.call_tool("primitive_tool", {})
+        assert result.structured_content == {"result": "Hello, primitives!"}
+
+    async def test_output_schema_complex_type(self):
+        """Test complex type output schema."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def complex_tool() -> list[dict[str, int]]:
+            return [{"a": 1, "b": 2}, {"c": 3, "d": 4}]
+
+        tools = await mcp.list_tools()
+        tool = next(t for t in tools if t.name == "complex_tool")
+        expected_inner_schema = compress_schema(
+            TypeAdapter(list[dict[str, int]]).json_schema(), prune_titles=True
+        )
+        expected_schema = {
+            "type": "object",
+            "properties": {"result": expected_inner_schema},
+            "required": ["result"],
+            "x-fastmcp-wrap-result": True,
+        }
+        assert tool.output_schema == expected_schema
+
+        result = await mcp.call_tool("complex_tool", {})
+        expected_data = [{"a": 1, "b": 2}, {"c": 3, "d": 4}]
+        assert result.structured_content == {"result": expected_data}
+
+    async def test_output_schema_dataclass(self):
+        """Test dataclass output schema."""
+        mcp = FastMCP()
+
+        @dataclass
+        class User:
+            name: str
+            age: int
+
+        @mcp.tool
+        def dataclass_tool() -> User:
+            return User(name="Alice", age=30)
+
+        tools = await mcp.list_tools()
+        tool = next(t for t in tools if t.name == "dataclass_tool")
+        expected_schema = compress_schema(
+            TypeAdapter(User).json_schema(), prune_titles=True
+        )
+        assert tool.output_schema == expected_schema
+        assert tool.output_schema and "x-fastmcp-wrap-result" not in tool.output_schema
+
+        result = await mcp.call_tool("dataclass_tool", {})
+        assert result.structured_content == {"name": "Alice", "age": 30}
+
+    async def test_output_schema_mixed_content_types(self):
+        """Test tools with mixed content and output schemas."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def mixed_output() -> list[Any]:
+            return [
+                "text message",
+                {"structured": "data"},
+                TextContent(type="text", text="direct MCP content"),
+            ]
+
+        result = await mcp.call_tool("mixed_output", {})
+        assert isinstance(result.content, list)
+        assert len(result.content) == 3
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "text message"
+        assert isinstance(result.content[1], TextContent)
+        assert result.content[1].text == '{"structured":"data"}'
+        assert isinstance(result.content[2], TextContent)
+        assert result.content[2].text == "direct MCP content"
+
+    async def test_wrapped_result_includes_meta_flag(self):
+        """Wrapped results include wrap_result in meta."""
+        server = FastMCP()
+
+        @server.tool
+        def list_tool() -> list[dict]:
+            return [{"a": 1}]
+
+        result = await server.call_tool("list_tool", {})
+        assert result.structured_content == {"result": [{"a": 1}]}
+        assert result.meta == {"fastmcp": {"wrap_result": True}}
+
+    async def test_unwrapped_result_has_no_meta_flag(self):
+        """Unwrapped dict results do not include wrap_result in meta."""
+        server = FastMCP()
+
+        @server.tool
+        def dict_tool() -> dict[str, int]:
+            return {"value": 42}
+
+        result = await server.call_tool("dict_tool", {})
+        assert result.structured_content == {"value": 42}
+        assert result.meta is None
+
+    async def test_output_schema_serialization_edge_cases(self):
+        """Test edge cases in output schema serialization."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def edge_case_tool() -> tuple[int, str]:
+            return (42, "hello")
+
+        tools = await mcp.list_tools()
+        tool = next(t for t in tools if t.name == "edge_case_tool")
+
+        assert tool.output_schema and "x-fastmcp-wrap-result" in tool.output_schema
+
+        result = await mcp.call_tool("edge_case_tool", {})
+        assert result.structured_content == {"result": [42, "hello"]}
+
+    async def test_output_schema_wraps_non_object_ref_schema(self):
+        """Root $ref schemas should only skip wrapping when they resolve to objects."""
+        mcp = FastMCP()
+        AliasType = TypeAliasType("AliasType", Literal["foo", "bar"])
+
+        @mcp.tool
+        def alias_tool() -> AliasType:
+            return "foo"
+
+        tools = await mcp.list_tools()
+        tool = next(t for t in tools if t.name == "alias_tool")
+
+        expected_inner_schema = compress_schema(
+            TypeAdapter(AliasType).json_schema(mode="serialization"),
+            prune_titles=True,
+        )
+        assert tool.output_schema == {
+            "type": "object",
+            "properties": {"result": expected_inner_schema},
+            "required": ["result"],
+            "x-fastmcp-wrap-result": True,
+        }
+
+        result = await mcp.call_tool("alias_tool", {})
+        assert result.structured_content == {"result": "foo"}
+
+
+class TestIsObjectSchemaRefResolution:
+    """Tests for $ref resolution in _is_object_schema, including JSON Pointer
+    escaping and nested $defs paths."""
+
+    def test_simple_ref_to_object(self):
+        schema = {
+            "$ref": "#/$defs/MyModel",
+            "$defs": {
+                "MyModel": {"type": "object", "properties": {"x": {"type": "int"}}}
+            },
+        }
+        assert _is_object_schema(schema) is True
+
+    def test_simple_ref_to_non_object(self):
+        schema = {
+            "$ref": "#/$defs/MyEnum",
+            "$defs": {"MyEnum": {"enum": ["a", "b"]}},
+        }
+        assert _is_object_schema(schema) is False
+
+    def test_nested_defs_path(self):
+        """Refs like #/$defs/Outer/$defs/Inner should walk into nested dicts."""
+        schema = {
+            "$ref": "#/$defs/Outer/$defs/Inner",
+            "$defs": {
+                "Outer": {
+                    "$defs": {
+                        "Inner": {
+                            "type": "object",
+                            "properties": {"y": {"type": "string"}},
+                        },
+                    },
+                },
+            },
+        }
+        assert _is_object_schema(schema) is True
+
+    def test_nested_defs_non_object(self):
+        schema = {
+            "$ref": "#/$defs/Outer/$defs/Inner",
+            "$defs": {
+                "Outer": {
+                    "$defs": {
+                        "Inner": {"type": "string"},
+                    },
+                },
+            },
+        }
+        assert _is_object_schema(schema) is False
+
+    def test_json_pointer_tilde_escape(self):
+        """~0 should unescape to ~ and ~1 should unescape to /."""
+        schema = {
+            "$ref": "#/$defs/has~1slash~0tilde",
+            "$defs": {"has/slash~tilde": {"type": "object", "properties": {}}},
+        }
+        assert _is_object_schema(schema) is True
+
+    def test_missing_nested_segment_returns_false(self):
+        schema = {
+            "$ref": "#/$defs/Outer/$defs/Missing",
+            "$defs": {
+                "Outer": {
+                    "$defs": {},
+                },
+            },
+        }
+        assert _is_object_schema(schema) is False
diff --git a/tests/server/providers/local_provider_tools/test_parameters.py b/tests/server/providers/local_provider_tools/test_parameters.py
new file mode 100644
index 0000000..13e5e06
--- /dev/null
+++ b/tests/server/providers/local_provider_tools/test_parameters.py
@@ -0,0 +1,416 @@
+"""Tests for tool parameters and validation."""
+
+import base64
+import datetime
+import uuid
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Annotated, Literal
+
+import pytest
+from mcp_types import (
+    ImageContent,
+)
+from pydantic import BaseModel, Field
+from typing_extensions import TypedDict
+
+from fastmcp import FastMCP
+from fastmcp.utilities.types import Image
+
+
+def _normalize_anyof_order(schema):
+    """Normalize the order of items in anyOf arrays for consistent comparison."""
+    if isinstance(schema, dict):
+        if "anyOf" in schema:
+            schema = schema.copy()
+            schema["anyOf"] = sorted(schema["anyOf"], key=str)
+        return {k: _normalize_anyof_order(v) for k, v in schema.items()}
+    elif isinstance(schema, list):
+        return [_normalize_anyof_order(item) for item in schema]
+    return schema
+
+
+class PersonTypedDict(TypedDict):
+    name: str
+    age: int
+
+
+class PersonModel(BaseModel):
+    name: str
+    age: int
+
+
+@dataclass
+class PersonDataclass:
+    name: str
+    age: int
+
+
+class TestToolParameters:
+    async def test_parameter_descriptions_with_field_annotations(self):
+        mcp = FastMCP("Test Server")
+
+        @mcp.tool
+        def greet(
+            name: Annotated[str, Field(description="The name to greet")],
+            title: Annotated[str, Field(description="Optional title", default="")],
+        ) -> str:
+            """A greeting tool"""
+            return f"Hello {title} {name}"
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+        tool = tools[0]
+
+        properties = tool.parameters["properties"]
+        assert "name" in properties
+        assert properties["name"]["description"] == "The name to greet"
+        assert "title" in properties
+        assert properties["title"]["description"] == "Optional title"
+        assert properties["title"]["default"] == ""
+        assert tool.parameters["required"] == ["name"]
+
+    async def test_parameter_descriptions_with_field_defaults(self):
+        mcp = FastMCP("Test Server")
+
+        @mcp.tool
+        def greet(
+            name: str = Field(description="The name to greet"),
+            title: str = Field(description="Optional title", default=""),
+        ) -> str:
+            """A greeting tool"""
+            return f"Hello {title} {name}"
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+        tool = tools[0]
+
+        properties = tool.parameters["properties"]
+        assert "name" in properties
+        assert properties["name"]["description"] == "The name to greet"
+        assert "title" in properties
+        assert properties["title"]["description"] == "Optional title"
+        assert properties["title"]["default"] == ""
+        assert tool.parameters["required"] == ["name"]
+
+    async def test_tool_with_bytes_input(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def process_image(image: bytes) -> Image:
+            return Image(data=image)
+
+        result = await mcp.call_tool("process_image", {"image": b"fake png data"})
+        assert result.structured_content is None
+        assert isinstance(result.content, list)
+        assert isinstance(result.content[0], ImageContent)
+        assert result.content[0].mime_type == "image/png"
+        assert result.content[0].data == base64.b64encode(b"fake png data").decode()
+
+    async def test_tool_with_invalid_input(self):
+        from fastmcp.exceptions import ValidationError
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def my_tool(x: int) -> int:
+            return x + 1
+
+        with pytest.raises(
+            ValidationError,
+            match="Input should be a valid integer",
+        ):
+            await mcp.call_tool("my_tool", {"x": "not an int"})
+
+    async def test_tool_int_coercion(self):
+        """Test that string ints are coerced by default."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def add_one(x: int) -> int:
+            return x + 1
+
+        result = await mcp.call_tool("add_one", {"x": "42"})
+        assert result.structured_content == {"result": 43}
+
+    async def test_tool_bool_coercion(self):
+        """Test that string bools are coerced by default."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def toggle(flag: bool) -> bool:
+            return not flag
+
+        result = await mcp.call_tool("toggle", {"flag": "true"})
+        assert result.structured_content == {"result": False}
+
+        result = await mcp.call_tool("toggle", {"flag": "false"})
+        assert result.structured_content == {"result": True}
+
+    async def test_annotated_field_validation(self):
+        from fastmcp.exceptions import ValidationError
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def analyze(x: Annotated[int, Field(ge=1)]) -> None:
+            pass
+
+        with pytest.raises(
+            ValidationError,
+            match="Input should be greater than or equal to 1",
+        ):
+            await mcp.call_tool("analyze", {"x": 0})
+
+    async def test_default_field_validation(self):
+        from fastmcp.exceptions import ValidationError
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def analyze(x: int = Field(ge=1)) -> None:
+            pass
+
+        with pytest.raises(
+            ValidationError,
+            match="Input should be greater than or equal to 1",
+        ):
+            await mcp.call_tool("analyze", {"x": 0})
+
+    async def test_default_field_is_still_required_if_no_default_specified(self):
+        from fastmcp.exceptions import ValidationError
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def analyze(x: int = Field()) -> None:
+            pass
+
+        with pytest.raises(ValidationError, match="missing"):
+            await mcp.call_tool("analyze", {})
+
+    async def test_literal_type_validation_error(self):
+        from fastmcp.exceptions import ValidationError
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def analyze(x: Literal["a", "b"]) -> None:
+            pass
+
+        with pytest.raises(
+            ValidationError,
+            match="Input should be 'a' or 'b'",
+        ):
+            await mcp.call_tool("analyze", {"x": "c"})
+
+    async def test_literal_type_validation_success(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def analyze(x: Literal["a", "b"]) -> str:
+            return x
+
+        result = await mcp.call_tool("analyze", {"x": "a"})
+        assert result.structured_content == {"result": "a"}
+
+    async def test_enum_type_validation_error(self):
+        from fastmcp.exceptions import ValidationError
+
+        mcp = FastMCP()
+
+        class MyEnum(Enum):
+            RED = "red"
+            GREEN = "green"
+            BLUE = "blue"
+
+        @mcp.tool
+        def analyze(x: MyEnum) -> str:
+            return x.value
+
+        with pytest.raises(
+            ValidationError,
+            match="Input should be 'red', 'green' or 'blue'",
+        ):
+            await mcp.call_tool("analyze", {"x": "some-color"})
+
+    async def test_enum_type_validation_success(self):
+        mcp = FastMCP()
+
+        class MyEnum(Enum):
+            RED = "red"
+            GREEN = "green"
+            BLUE = "blue"
+
+        @mcp.tool
+        def analyze(x: MyEnum) -> str:
+            return x.value
+
+        result = await mcp.call_tool("analyze", {"x": "red"})
+        assert result.structured_content == {"result": "red"}
+
+    async def test_union_type_validation(self):
+        from fastmcp.exceptions import ValidationError
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def analyze(x: int | float) -> str:
+            return str(x)
+
+        result = await mcp.call_tool("analyze", {"x": 1})
+        assert result.structured_content == {"result": "1"}
+
+        result = await mcp.call_tool("analyze", {"x": 1.0})
+        assert result.structured_content == {"result": "1.0"}
+
+        with pytest.raises(
+            ValidationError,
+            match="Input should be a valid",
+        ):
+            await mcp.call_tool("analyze", {"x": "not a number"})
+
+    async def test_path_type(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def send_path(path: Path) -> str:
+            assert isinstance(path, Path)
+            return str(path)
+
+        test_path = Path("tmp") / "test.txt"
+
+        result = await mcp.call_tool("send_path", {"path": str(test_path)})
+        assert result.structured_content == {"result": str(test_path)}
+
+    async def test_path_type_error(self):
+        from fastmcp.exceptions import ValidationError
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def send_path(path: Path) -> str:
+            return str(path)
+
+        with pytest.raises(ValidationError, match="Input is not a valid path"):
+            await mcp.call_tool("send_path", {"path": 1})
+
+    async def test_uuid_type(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def send_uuid(x: uuid.UUID) -> str:
+            assert isinstance(x, uuid.UUID)
+            return str(x)
+
+        test_uuid = uuid.uuid4()
+
+        result = await mcp.call_tool("send_uuid", {"x": test_uuid})
+        assert result.structured_content == {"result": str(test_uuid)}
+
+    async def test_uuid_type_error(self):
+        from fastmcp.exceptions import ValidationError
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def send_uuid(x: uuid.UUID) -> str:
+            return str(x)
+
+        with pytest.raises(ValidationError, match="Input should be a valid UUID"):
+            await mcp.call_tool("send_uuid", {"x": "not a uuid"})
+
+    async def test_datetime_type(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def send_datetime(x: datetime.datetime) -> str:
+            return x.isoformat()
+
+        dt = datetime.datetime(2025, 4, 25, 1, 2, 3)
+
+        result = await mcp.call_tool("send_datetime", {"x": dt})
+        assert result.structured_content == {"result": dt.isoformat()}
+
+    async def test_datetime_type_parse_string(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def send_datetime(x: datetime.datetime) -> str:
+            return x.isoformat()
+
+        result = await mcp.call_tool("send_datetime", {"x": "2021-01-01T00:00:00"})
+        assert result.structured_content == {"result": "2021-01-01T00:00:00"}
+
+    async def test_datetime_type_error(self):
+        from fastmcp.exceptions import ValidationError
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def send_datetime(x: datetime.datetime) -> str:
+            return x.isoformat()
+
+        with pytest.raises(ValidationError, match="Input should be a valid datetime"):
+            await mcp.call_tool("send_datetime", {"x": "not a datetime"})
+
+    async def test_date_type(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def send_date(x: datetime.date) -> str:
+            return x.isoformat()
+
+        result = await mcp.call_tool("send_date", {"x": datetime.date.today()})
+        assert result.structured_content == {
+            "result": datetime.date.today().isoformat()
+        }
+
+    async def test_date_type_parse_string(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def send_date(x: datetime.date) -> str:
+            return x.isoformat()
+
+        result = await mcp.call_tool("send_date", {"x": "2021-01-01"})
+        assert result.structured_content == {"result": "2021-01-01"}
+
+    async def test_timedelta_type(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def send_timedelta(x: datetime.timedelta) -> str:
+            return str(x)
+
+        result = await mcp.call_tool(
+            "send_timedelta", {"x": datetime.timedelta(days=1)}
+        )
+        assert result.structured_content == {"result": "1 day, 0:00:00"}
+
+    async def test_timedelta_type_parse_int(self):
+        """Test that int input is coerced to timedelta (seconds)."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def send_timedelta(x: datetime.timedelta) -> str:
+            return str(x)
+
+        result = await mcp.call_tool("send_timedelta", {"x": 1000})
+        assert result.structured_content is not None
+        result_str = result.structured_content["result"]
+        assert (
+            "0:16:40" in result_str or "16:40" in result_str
+        )  # 1000 seconds = 16 minutes 40 seconds
+
+    async def test_annotated_string_description(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def f(x: Annotated[int, "A number"]):
+            return x
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+        assert tools[0].parameters["properties"]["x"]["description"] == "A number"
diff --git a/tests/server/providers/local_provider_tools/test_tags.py b/tests/server/providers/local_provider_tools/test_tags.py
new file mode 100644
index 0000000..fb32e35
--- /dev/null
+++ b/tests/server/providers/local_provider_tools/test_tags.py
@@ -0,0 +1,99 @@
+"""Tests for tool tags."""
+
+from dataclasses import dataclass
+
+import pytest
+from pydantic import BaseModel
+from typing_extensions import TypedDict
+
+from fastmcp import FastMCP
+from fastmcp.exceptions import NotFoundError
+
+
+def _normalize_anyof_order(schema):
+    """Normalize the order of items in anyOf arrays for consistent comparison."""
+    if isinstance(schema, dict):
+        if "anyOf" in schema:
+            schema = schema.copy()
+            schema["anyOf"] = sorted(schema["anyOf"], key=str)
+        return {k: _normalize_anyof_order(v) for k, v in schema.items()}
+    elif isinstance(schema, list):
+        return [_normalize_anyof_order(item) for item in schema]
+    return schema
+
+
+class PersonTypedDict(TypedDict):
+    name: str
+    age: int
+
+
+class PersonModel(BaseModel):
+    name: str
+    age: int
+
+
+@dataclass
+class PersonDataclass:
+    name: str
+    age: int
+
+
+class TestToolTags:
+    def create_server(self, include_tags=None, exclude_tags=None):
+        mcp = FastMCP()
+
+        @mcp.tool(tags={"a", "b"})
+        def tool_1() -> int:
+            return 1
+
+        @mcp.tool(tags={"b", "c"})
+        def tool_2() -> int:
+            return 2
+
+        if include_tags:
+            mcp.enable(tags=include_tags, only=True)
+        if exclude_tags:
+            mcp.disable(tags=exclude_tags)
+
+        return mcp
+
+    async def test_include_tags_all_tools(self):
+        mcp = self.create_server(include_tags={"a", "b"})
+        tools = await mcp.list_tools()
+        assert {t.name for t in tools} == {"tool_1", "tool_2"}
+
+    async def test_include_tags_some_tools(self):
+        mcp = self.create_server(include_tags={"a", "z"})
+        tools = await mcp.list_tools()
+        assert {t.name for t in tools} == {"tool_1"}
+
+    async def test_exclude_tags_all_tools(self):
+        mcp = self.create_server(exclude_tags={"a", "b"})
+        tools = await mcp.list_tools()
+        assert {t.name for t in tools} == set()
+
+    async def test_exclude_tags_some_tools(self):
+        mcp = self.create_server(exclude_tags={"a", "z"})
+        tools = await mcp.list_tools()
+        assert {t.name for t in tools} == {"tool_2"}
+
+    async def test_exclude_precedence(self):
+        mcp = self.create_server(exclude_tags={"a"}, include_tags={"b"})
+        tools = await mcp.list_tools()
+        assert {t.name for t in tools} == {"tool_2"}
+
+    async def test_call_included_tool(self):
+        mcp = self.create_server(include_tags={"a"})
+        result_1 = await mcp.call_tool("tool_1", {})
+        assert result_1.structured_content == {"result": 1}
+
+        with pytest.raises(NotFoundError, match="Unknown tool"):
+            await mcp.call_tool("tool_2", {})
+
+    async def test_call_excluded_tool(self):
+        mcp = self.create_server(exclude_tags={"a"})
+        with pytest.raises(NotFoundError, match="Unknown tool"):
+            await mcp.call_tool("tool_1", {})
+
+        result_2 = await mcp.call_tool("tool_2", {})
+        assert result_2.structured_content == {"result": 2}
diff --git a/tests/server/providers/openapi/__init__.py b/tests/server/providers/openapi/__init__.py
new file mode 100644
index 0000000..b862f61
--- /dev/null
+++ b/tests/server/providers/openapi/__init__.py
@@ -0,0 +1 @@
+"""Tests for openapi_new server components."""
diff --git a/tests/server/providers/openapi/test_comprehensive.py b/tests/server/providers/openapi/test_comprehensive.py
new file mode 100644
index 0000000..31a54c4
--- /dev/null
+++ b/tests/server/providers/openapi/test_comprehensive.py
@@ -0,0 +1,962 @@
+"""Comprehensive tests for OpenAPIProvider implementation."""
+
+import json
+from unittest.mock import AsyncMock, Mock
+
+import httpx
+import pytest
+from httpx import Response
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.providers.openapi import OpenAPIProvider
+
+
+def create_openapi_server(
+    openapi_spec: dict,
+    client,
+    name: str = "OpenAPI Server",
+) -> FastMCP:
+    """Helper to create a FastMCP server with OpenAPIProvider."""
+    provider = OpenAPIProvider(openapi_spec=openapi_spec, client=client)
+    mcp = FastMCP(name)
+    mcp.add_provider(provider)
+    return mcp
+
+
+class TestOpenAPIComprehensive:
+    """Comprehensive tests ensuring no functionality is lost."""
+
+    @pytest.fixture
+    def comprehensive_openapi_spec(self):
+        """Comprehensive OpenAPI spec covering all major features."""
+        return {
+            "openapi": "3.0.0",
+            "info": {"title": "Comprehensive API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com"}],
+            "components": {
+                "schemas": {
+                    "User": {
+                        "type": "object",
+                        "properties": {
+                            "id": {"type": "integer"},
+                            "name": {"type": "string"},
+                            "email": {"type": "string", "format": "email"},
+                            "age": {"type": "integer", "minimum": 0},
+                        },
+                        "required": ["name", "email"],
+                    },
+                    "Error": {
+                        "type": "object",
+                        "properties": {
+                            "code": {"type": "integer"},
+                            "message": {"type": "string"},
+                        },
+                    },
+                },
+                "parameters": {
+                    "UserId": {
+                        "name": "id",
+                        "in": "path",
+                        "required": True,
+                        "schema": {"type": "integer"},
+                        "description": "User identifier",
+                    }
+                },
+            },
+            "paths": {
+                # Basic CRUD operations
+                "/users": {
+                    "get": {
+                        "operationId": "list_users",
+                        "summary": "List all users",
+                        "parameters": [
+                            {
+                                "name": "limit",
+                                "in": "query",
+                                "schema": {
+                                    "type": "integer",
+                                    "default": 10,
+                                    "minimum": 1,
+                                    "maximum": 100,
+                                },
+                                "description": "Number of users to return",
+                            },
+                            {
+                                "name": "offset",
+                                "in": "query",
+                                "schema": {
+                                    "type": "integer",
+                                    "default": 0,
+                                    "minimum": 0,
+                                },
+                                "description": "Number of users to skip",
+                            },
+                            {
+                                "name": "sort",
+                                "in": "query",
+                                "schema": {
+                                    "type": "string",
+                                    "enum": ["name", "email", "age"],
+                                },
+                                "description": "Sort field",
+                            },
+                        ],
+                        "responses": {
+                            "200": {
+                                "description": "List of users",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "array",
+                                            "items": {
+                                                "$ref": "#/components/schemas/User"
+                                            },
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    },
+                    "post": {
+                        "operationId": "create_user",
+                        "summary": "Create a new user",
+                        "requestBody": {
+                            "required": True,
+                            "content": {
+                                "application/json": {
+                                    "schema": {"$ref": "#/components/schemas/User"}
+                                }
+                            },
+                        },
+                        "responses": {
+                            "201": {
+                                "description": "User created",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {"$ref": "#/components/schemas/User"}
+                                    }
+                                },
+                            },
+                            "400": {
+                                "description": "Invalid input",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {"$ref": "#/components/schemas/Error"}
+                                    }
+                                },
+                            },
+                        },
+                    },
+                },
+                "/users/{id}": {
+                    "parameters": [{"$ref": "#/components/parameters/UserId"}],
+                    "get": {
+                        "operationId": "get_user",
+                        "summary": "Get user by ID",
+                        "responses": {
+                            "200": {
+                                "description": "User details",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {"$ref": "#/components/schemas/User"}
+                                    }
+                                },
+                            },
+                            "404": {
+                                "description": "User not found",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {"$ref": "#/components/schemas/Error"}
+                                    }
+                                },
+                            },
+                        },
+                    },
+                    "put": {
+                        "operationId": "update_user",
+                        "summary": "Update user",
+                        "requestBody": {
+                            "required": True,
+                            "content": {
+                                "application/json": {
+                                    "schema": {"$ref": "#/components/schemas/User"}
+                                }
+                            },
+                        },
+                        "responses": {
+                            "200": {
+                                "description": "User updated",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {"$ref": "#/components/schemas/User"}
+                                    }
+                                },
+                            },
+                        },
+                    },
+                    "delete": {
+                        "operationId": "delete_user",
+                        "summary": "Delete user",
+                        "responses": {
+                            "204": {"description": "User deleted"},
+                            "404": {
+                                "description": "User not found",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {"$ref": "#/components/schemas/Error"}
+                                    }
+                                },
+                            },
+                        },
+                    },
+                },
+                # Complex parameter scenarios
+                "/search": {
+                    "get": {
+                        "operationId": "search_users",
+                        "summary": "Search users with complex filters",
+                        "parameters": [
+                            {
+                                "name": "q",
+                                "in": "query",
+                                "required": True,
+                                "schema": {"type": "string"},
+                                "description": "Search query",
+                            },
+                            {
+                                "name": "filter",
+                                "in": "query",
+                                "style": "deepObject",
+                                "explode": True,
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "age": {
+                                            "type": "object",
+                                            "properties": {
+                                                "min": {"type": "integer"},
+                                                "max": {"type": "integer"},
+                                            },
+                                        },
+                                        "name": {"type": "string"},
+                                        "active": {"type": "boolean"},
+                                    },
+                                },
+                            },
+                            {
+                                "name": "X-Request-ID",
+                                "in": "header",
+                                "schema": {"type": "string"},
+                                "description": "Request identifier for tracing",
+                            },
+                        ],
+                        "responses": {
+                            "200": {
+                                "description": "Search results",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "results": {
+                                                    "type": "array",
+                                                    "items": {
+                                                        "$ref": "#/components/schemas/User"
+                                                    },
+                                                },
+                                                "total": {"type": "integer"},
+                                                "page": {"type": "integer"},
+                                            },
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                },
+                # Parameter collision scenario
+                "/collision/{id}": {
+                    "patch": {
+                        "operationId": "collision_test",
+                        "summary": "Test parameter collision handling",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "string"},
+                                "description": "Resource ID",
+                            },
+                            {
+                                "name": "version",
+                                "in": "query",
+                                "schema": {"type": "integer", "default": 1},
+                            },
+                            {
+                                "name": "version",
+                                "in": "header",
+                                "schema": {"type": "string"},
+                            },
+                        ],
+                        "requestBody": {
+                            "required": True,
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "properties": {
+                                            "id": {
+                                                "type": "integer",
+                                                "description": "Internal ID",
+                                            },
+                                            "version": {
+                                                "type": "string",
+                                                "description": "Data version",
+                                            },
+                                            "data": {"type": "object"},
+                                        },
+                                    }
+                                }
+                            },
+                        },
+                        "responses": {"200": {"description": "Updated"}},
+                    }
+                },
+            },
+        }
+
+    @pytest.fixture
+    def openapi_31_spec(self):
+        """OpenAPI 3.1 spec to test compatibility."""
+        return {
+            "openapi": "3.1.0",
+            "info": {"title": "OpenAPI 3.1 Test", "version": "1.0.0"},
+            "paths": {
+                "/items/{id}": {
+                    "get": {
+                        "operationId": "get_item_31",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "string"},
+                            }
+                        ],
+                        "responses": {
+                            "200": {
+                                "description": "Item details",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "id": {"type": "string"},
+                                                "name": {"type": "string"},
+                                            },
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                }
+            },
+        }
+
+    async def test_comprehensive_server_initialization(
+        self, comprehensive_openapi_spec
+    ):
+        """Test server initialization with comprehensive spec."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            provider = OpenAPIProvider(
+                openapi_spec=comprehensive_openapi_spec,
+                client=client,
+            )
+            server = FastMCP("Comprehensive Test Server")
+            server.add_provider(provider)
+
+            # Should initialize successfully
+            assert server.name == "Comprehensive Test Server"
+            assert hasattr(provider, "_director")
+            assert hasattr(provider, "_spec")
+
+            # Test with in-memory client
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                # Should have created tools for all operations
+                tool_names = {tool.name for tool in tools}
+                expected_operations = {
+                    "list_users",
+                    "create_user",
+                    "get_user",
+                    "update_user",
+                    "delete_user",
+                    "search_users",
+                    "collision_test",
+                }
+
+                assert tool_names == expected_operations
+
+    async def test_openapi_31_compatibility(self, openapi_31_spec):
+        """Test that OpenAPI 3.1 specs work correctly."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=openapi_31_spec,
+                client=client,
+                name="OpenAPI 3.1 Test",
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                assert len(tools) == 1
+                tool = tools[0]
+                assert tool.name == "get_item_31"
+
+    async def test_parameter_collision_handling(self, comprehensive_openapi_spec):
+        """Test that parameter collisions are handled correctly."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=comprehensive_openapi_spec,
+                client=client,
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                collision_tool = next(
+                    tool for tool in tools if tool.name == "collision_test"
+                )
+                schema = collision_tool.input_schema
+                properties = schema["properties"]
+
+                # Should have unique parameter names for colliding parameters
+                param_names = list(properties.keys())
+
+                # Should have some form of id parameters (path and body)
+                id_params = [name for name in param_names if "id" in name]
+                assert len(id_params) >= 2
+
+                # Should have some form of version parameters (query, header, body)
+                version_params = [name for name in param_names if "version" in name]
+                assert len(version_params) >= 3
+
+                # Should have other parameters
+                assert "data" in param_names
+
+    async def test_deep_object_parameters(self, comprehensive_openapi_spec):
+        """Test deepObject parameter handling."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=comprehensive_openapi_spec,
+                client=client,
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                search_tool = next(
+                    tool for tool in tools if tool.name == "search_users"
+                )
+                schema = search_tool.input_schema
+                properties = schema["properties"]
+
+                # Should have flattened deepObject parameters
+                # The exact flattening depends on implementation
+                assert "q" in properties  # Regular query parameter
+
+                # Should have some form of filter parameters
+                filter_params = [name for name in properties.keys() if "filter" in name]
+                assert len(filter_params) > 0
+
+    async def test_request_building_and_execution(self, comprehensive_openapi_spec):
+        """Test that requests are built and executed correctly."""
+        # Create a mock client that tracks requests
+        mock_client = Mock(spec=httpx.AsyncClient)
+        mock_client.base_url = "https://api.example.com"
+        mock_client.headers = None
+
+        # Mock successful response
+        mock_response = Mock(spec=Response)
+        mock_response.status_code = 200
+        mock_response.json.return_value = {
+            "id": 123,
+            "name": "Test User",
+            "email": "test@example.com",
+        }
+        mock_response.text = json.dumps(
+            {"id": 123, "name": "Test User", "email": "test@example.com"}
+        )
+        mock_response.raise_for_status = Mock()
+
+        mock_client.send = AsyncMock(return_value=mock_response)
+
+        server = create_openapi_server(
+            openapi_spec=comprehensive_openapi_spec,
+            client=mock_client,
+        )
+
+        async with Client(server) as mcp_client:
+            # Test GET request with path parameter
+            await mcp_client.call_tool("get_user", {"id": 123})
+
+            # Should have made a request
+            mock_client.send.assert_called_once()
+            request = mock_client.send.call_args[0][0]
+
+            # Verify request details
+            assert request.method == "GET"
+            assert "123" in str(request.url)
+            assert "users/123" in str(request.url)
+
+    async def test_request_uses_localhost_fallback_when_no_base_url(
+        self, comprehensive_openapi_spec
+    ):
+        """Test that tool uses localhost fallback when client has no base_url."""
+        mock_client = Mock(spec=httpx.AsyncClient)
+        mock_client.base_url = httpx.URL("")  # Empty URL, same as httpx default
+        mock_client.headers = None
+
+        mock_response = Mock(spec=Response)
+        mock_response.status_code = 200
+        mock_response.json.return_value = {
+            "id": 123,
+            "name": "Test User",
+            "email": "test@example.com",
+        }
+        mock_response.raise_for_status = Mock()
+
+        mock_client.send = AsyncMock(return_value=mock_response)
+
+        server = create_openapi_server(
+            openapi_spec=comprehensive_openapi_spec,
+            client=mock_client,
+        )
+
+        async with Client(server) as mcp_client:
+            await mcp_client.call_tool("get_user", {"id": 123})
+
+        # Verify request was made to localhost fallback
+        mock_client.send.assert_called_once()
+        request = mock_client.send.call_args[0][0]
+        assert str(request.url).startswith("http://localhost")
+
+    async def test_complex_request_with_body_and_parameters(
+        self, comprehensive_openapi_spec
+    ):
+        """Test complex request with both parameters and body."""
+        mock_client = Mock(spec=httpx.AsyncClient)
+        mock_client.base_url = "https://api.example.com"
+        mock_client.headers = None
+
+        mock_response = Mock(spec=Response)
+        mock_response.status_code = 201
+        mock_response.json.return_value = {
+            "id": 456,
+            "name": "New User",
+            "email": "new@example.com",
+        }
+        mock_response.raise_for_status = Mock()
+
+        mock_client.send = AsyncMock(return_value=mock_response)
+
+        server = create_openapi_server(
+            openapi_spec=comprehensive_openapi_spec,
+            client=mock_client,
+        )
+
+        async with Client(server) as mcp_client:
+            # Test POST request with body
+            await mcp_client.call_tool(
+                "create_user",
+                {
+                    "name": "New User",
+                    "email": "new@example.com",
+                    "age": 25,
+                },
+            )
+
+            # Should have made a request
+            mock_client.send.assert_called_once()
+            request = mock_client.send.call_args[0][0]
+
+            # Verify request details
+            assert request.method == "POST"
+            assert "users" in str(request.url)
+
+            # Should have JSON body
+            assert request.content is not None
+            body_data = json.loads(request.content)
+            assert body_data["name"] == "New User"
+            assert body_data["email"] == "new@example.com"
+            assert body_data["age"] == 25
+
+    async def test_query_parameters(self, comprehensive_openapi_spec):
+        """Test query parameter handling."""
+        mock_client = Mock(spec=httpx.AsyncClient)
+        mock_client.base_url = "https://api.example.com"
+        mock_client.headers = None
+
+        mock_response = Mock(spec=Response)
+        mock_response.status_code = 200
+        mock_response.json.return_value = []
+        mock_response.raise_for_status = Mock()
+
+        mock_client.send = AsyncMock(return_value=mock_response)
+
+        server = create_openapi_server(
+            openapi_spec=comprehensive_openapi_spec,
+            client=mock_client,
+        )
+
+        async with Client(server) as mcp_client:
+            # Test GET request with query parameters
+            await mcp_client.call_tool(
+                "list_users",
+                {
+                    "limit": 20,
+                    "offset": 10,
+                    "sort": "name",
+                },
+            )
+
+            mock_client.send.assert_called_once()
+            request = mock_client.send.call_args[0][0]
+
+            # Verify query parameters in URL
+            url_str = str(request.url)
+            assert "limit=20" in url_str
+            assert "offset=10" in url_str
+            assert "sort=name" in url_str
+
+    async def test_error_handling(self, comprehensive_openapi_spec):
+        """Test error handling for HTTP errors."""
+        mock_client = Mock(spec=httpx.AsyncClient)
+        mock_client.base_url = "https://api.example.com"
+        mock_client.headers = None
+
+        # Mock HTTP error response
+        mock_response = Mock(spec=Response)
+        mock_response.status_code = 404
+        mock_response.reason_phrase = "Not Found"
+        mock_response.json.return_value = {"code": 404, "message": "User not found"}
+        mock_response.text = json.dumps({"code": 404, "message": "User not found"})
+
+        # Configure raise_for_status to raise HTTPStatusError
+        def raise_for_status():
+            raise httpx.HTTPStatusError(
+                "404 Not Found", request=Mock(), response=mock_response
+            )
+
+        mock_response.raise_for_status = raise_for_status
+        mock_client.send = AsyncMock(return_value=mock_response)
+
+        server = create_openapi_server(
+            openapi_spec=comprehensive_openapi_spec,
+            client=mock_client,
+        )
+
+        async with Client(server) as mcp_client:
+            # Should handle HTTP errors gracefully
+            with pytest.raises(Exception) as exc_info:
+                await mcp_client.call_tool("get_user", {"id": 999})
+
+            # Error should be wrapped appropriately
+            error_message = str(exc_info.value)
+            assert "404" in error_message
+
+    async def test_schema_refs_resolution(self, comprehensive_openapi_spec):
+        """Test that schema references are resolved correctly."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=comprehensive_openapi_spec,
+                client=client,
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                # Find create_user tool which uses schema refs
+                create_tool = next(tool for tool in tools if tool.name == "create_user")
+                schema = create_tool.input_schema
+                properties = schema["properties"]
+
+                # Should have resolved User schema properties
+                assert "name" in properties
+                assert "email" in properties
+                # May also have id and age depending on implementation
+
+    async def test_optional_vs_required_parameters(self, comprehensive_openapi_spec):
+        """Test handling of optional vs required parameters."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=comprehensive_openapi_spec,
+                client=client,
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                # Check list_users tool - has optional query parameters
+                list_tool = next(tool for tool in tools if tool.name == "list_users")
+                schema = list_tool.input_schema
+                # Query parameters should be optional
+                # (may not appear in required list)
+                # This test just ensures the schema is well-formed
+                assert "properties" in schema
+
+                # Check search_users tool - has required query parameter
+                search_tool = next(
+                    tool for tool in tools if tool.name == "search_users"
+                )
+                search_schema = search_tool.input_schema
+                # Should have some required parameters
+                assert len(search_schema["properties"]) > 0
+
+    async def test_server_performance_no_latency(self, comprehensive_openapi_spec):
+        """Test that server initialization is fast (no code generation latency)."""
+        import time
+
+        # Time the provider creation
+        start_time = time.time()
+
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            provider = OpenAPIProvider(
+                openapi_spec=comprehensive_openapi_spec,
+                client=client,
+            )
+
+        end_time = time.time()
+
+        # Should be fast (no code generation). Use generous threshold for slow
+        # CI runners (Windows); the intent is to catch obvious regressions
+        # (e.g., accidentally re-introducing code generation), not to benchmark.
+        initialization_time = end_time - start_time
+        assert initialization_time < 1.0
+
+        # Verify provider was created correctly
+        assert provider is not None
+        assert hasattr(provider, "_director")
+        assert hasattr(provider, "_spec")
+
+    async def test_timeout_error_produces_useful_message(
+        self, comprehensive_openapi_spec
+    ):
+        """ReadTimeout should surface a clear error, not an empty string."""
+        mock_client = Mock(spec=httpx.AsyncClient)
+        mock_client.base_url = "https://api.example.com"
+        mock_client.headers = None
+
+        # httpx internally raises ReadTimeout with an empty message
+        mock_client.send = AsyncMock(side_effect=httpx.ReadTimeout(""))
+
+        server = create_openapi_server(
+            openapi_spec=comprehensive_openapi_spec,
+            client=mock_client,
+        )
+
+        async with Client(server) as mcp_client:
+            with pytest.raises(Exception) as exc_info:
+                await mcp_client.call_tool("get_user", {"id": 1})
+
+            error_message = str(exc_info.value)
+            assert "timed out" in error_message
+            assert "ReadTimeout" in error_message
+
+
+class TestOpenAPIPostEdgeCases:
+    """Tests for POST request edge cases that could cause unhandled errors."""
+
+    @pytest.fixture
+    def post_spec_with_empty_content_schema(self):
+        """OpenAPI spec where a POST endpoint has an empty content_schema."""
+        return {
+            "openapi": "3.0.0",
+            "info": {"title": "Test API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com"}],
+            "paths": {
+                "/items": {
+                    "post": {
+                        "operationId": "create_item",
+                        "summary": "Create an item",
+                        "requestBody": {
+                            "required": True,
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "properties": {
+                                            "name": {"type": "string"},
+                                            "value": {"type": "integer"},
+                                        },
+                                        "required": ["name"],
+                                    }
+                                }
+                            },
+                        },
+                        "responses": {
+                            "201": {
+                                "description": "Created",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "id": {"type": "integer"},
+                                                "name": {"type": "string"},
+                                            },
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                },
+                "/items/{item_id}": {
+                    "post": {
+                        "operationId": "update_item",
+                        "summary": "Update an item",
+                        "parameters": [
+                            {
+                                "name": "item_id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "integer"},
+                            }
+                        ],
+                        "requestBody": {
+                            "required": True,
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "properties": {
+                                            "name": {"type": "string"},
+                                            "value": {"type": "integer"},
+                                        },
+                                    }
+                                }
+                            },
+                        },
+                        "responses": {
+                            "200": {
+                                "description": "Updated",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "id": {"type": "integer"},
+                                                "name": {"type": "string"},
+                                            },
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                },
+            },
+        }
+
+    async def test_post_with_body_params(self, post_spec_with_empty_content_schema):
+        """POST with body parameters should build the request correctly."""
+        mock_client = Mock(spec=httpx.AsyncClient)
+        mock_client.base_url = "https://api.example.com"
+        mock_client.headers = None
+
+        mock_response = Mock(spec=Response)
+        mock_response.status_code = 201
+        mock_response.json.return_value = {"id": 1, "name": "Test"}
+        mock_response.raise_for_status = Mock()
+        mock_client.send = AsyncMock(return_value=mock_response)
+
+        server = create_openapi_server(
+            openapi_spec=post_spec_with_empty_content_schema,
+            client=mock_client,
+        )
+
+        async with Client(server) as mcp_client:
+            result = await mcp_client.call_tool(
+                "create_item", {"name": "Test", "value": 42}
+            )
+
+        mock_client.send.assert_called_once()
+        request = mock_client.send.call_args[0][0]
+        assert request.method == "POST"
+        body_data = json.loads(request.content)
+        assert body_data["name"] == "Test"
+        assert body_data["value"] == 42
+        assert result is not None
+
+    async def test_post_with_path_params_and_body(
+        self, post_spec_with_empty_content_schema
+    ):
+        """POST with both path parameters and body should route args correctly."""
+        mock_client = Mock(spec=httpx.AsyncClient)
+        mock_client.base_url = "https://api.example.com"
+        mock_client.headers = None
+
+        mock_response = Mock(spec=Response)
+        mock_response.status_code = 200
+        mock_response.json.return_value = {"id": 5, "name": "Updated"}
+        mock_response.raise_for_status = Mock()
+        mock_client.send = AsyncMock(return_value=mock_response)
+
+        server = create_openapi_server(
+            openapi_spec=post_spec_with_empty_content_schema,
+            client=mock_client,
+        )
+
+        async with Client(server) as mcp_client:
+            result = await mcp_client.call_tool(
+                "update_item",
+                {"item_id": 5, "name": "Updated", "value": 99},
+            )
+
+        mock_client.send.assert_called_once()
+        request = mock_client.send.call_args[0][0]
+        assert request.method == "POST"
+        assert "/items/5" in str(request.url)
+        body_data = json.loads(request.content)
+        assert body_data["name"] == "Updated"
+        assert body_data["value"] == 99
+        assert "item_id" not in body_data
+        assert result is not None
+
+    async def test_unexpected_error_in_request_building_gives_useful_message(self):
+        """Unexpected exceptions during request building should produce useful errors."""
+        from fastmcp.server.providers.openapi.components import OpenAPITool
+        from fastmcp.utilities.openapi.director import RequestDirector
+        from fastmcp.utilities.openapi.models import HTTPRoute
+
+        mock_client = Mock(spec=httpx.AsyncClient)
+        mock_client.base_url = "https://api.example.com"
+        mock_client.headers = None
+
+        route = HTTPRoute(
+            path="/test",
+            method="POST",
+            operation_id="test_op",
+            parameters=[],
+            responses={},
+            response_schemas={},
+        )
+
+        mock_director = Mock(spec=RequestDirector)
+        mock_director.build.side_effect = KeyError("missing_param")
+
+        tool = OpenAPITool(
+            client=mock_client,
+            route=route,
+            director=mock_director,
+            name="test_tool",
+            description="test",
+            parameters={},
+        )
+
+        with pytest.raises(ValueError, match="Error building request for POST /test"):
+            await tool.run({"some_arg": "value"})
diff --git a/tests/server/providers/openapi/test_deepobject_style.py b/tests/server/providers/openapi/test_deepobject_style.py
new file mode 100644
index 0000000..29564f3
--- /dev/null
+++ b/tests/server/providers/openapi/test_deepobject_style.py
@@ -0,0 +1,346 @@
+"""Tests for deepObject style parameter handling in OpenAPIProvider."""
+
+import httpx
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.providers.openapi import OpenAPIProvider
+
+
+def create_openapi_server(
+    openapi_spec: dict,
+    client,
+    name: str = "OpenAPI Server",
+) -> FastMCP:
+    """Helper to create a FastMCP server with OpenAPIProvider."""
+    provider = OpenAPIProvider(openapi_spec=openapi_spec, client=client)
+    mcp = FastMCP(name)
+    mcp.add_provider(provider)
+    return mcp
+
+
+class TestDeepObjectStyle:
+    """Test deepObject style parameter handling in openapi_new."""
+
+    @pytest.fixture
+    def deepobject_spec(self):
+        """OpenAPI spec with deepObject style parameters."""
+        return {
+            "openapi": "3.0.0",
+            "info": {"title": "DeepObject Test API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com"}],
+            "paths": {
+                "/surveys": {
+                    "get": {
+                        "operationId": "get_surveys",
+                        "summary": "Get surveys with deepObject filtering",
+                        "parameters": [
+                            {
+                                "name": "target",
+                                "in": "query",
+                                "required": False,
+                                "style": "deepObject",
+                                "explode": True,
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "id": {
+                                            "type": "string",
+                                            "description": "Target ID",
+                                        },
+                                        "type": {
+                                            "type": "string",
+                                            "enum": ["location", "organisation"],
+                                            "description": "Target type",
+                                        },
+                                    },
+                                    "required": ["type", "id"],
+                                },
+                                "description": "Target object for filtering",
+                            },
+                            {
+                                "name": "filters",
+                                "in": "query",
+                                "required": False,
+                                "style": "deepObject",
+                                "explode": True,
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "status": {"type": "string"},
+                                        "category": {"type": "string"},
+                                        "priority": {"type": "integer"},
+                                    },
+                                },
+                                "description": "Additional filters",
+                            },
+                            {
+                                "name": "compact",
+                                "in": "query",
+                                "required": False,
+                                "style": "deepObject",
+                                "explode": False,
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "format": {"type": "string"},
+                                        "level": {"type": "integer"},
+                                    },
+                                },
+                                "description": "Compact format options (explode=false)",
+                            },
+                        ],
+                        "responses": {
+                            "200": {
+                                "description": "Survey list",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "surveys": {
+                                                    "type": "array",
+                                                    "items": {"type": "object"},
+                                                },
+                                                "total": {"type": "integer"},
+                                            },
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                },
+                "/users/{id}/preferences": {
+                    "patch": {
+                        "operationId": "update_preferences",
+                        "summary": "Update user preferences with deepObject in body",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "integer"},
+                            }
+                        ],
+                        "requestBody": {
+                            "required": True,
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "properties": {
+                                            "preferences": {
+                                                "type": "object",
+                                                "properties": {
+                                                    "theme": {"type": "string"},
+                                                    "notifications": {
+                                                        "type": "object",
+                                                        "properties": {
+                                                            "email": {
+                                                                "type": "boolean"
+                                                            },
+                                                            "push": {"type": "boolean"},
+                                                            "frequency": {
+                                                                "type": "string"
+                                                            },
+                                                        },
+                                                    },
+                                                    "privacy": {
+                                                        "type": "object",
+                                                        "properties": {
+                                                            "profile_visible": {
+                                                                "type": "boolean"
+                                                            },
+                                                            "analytics": {
+                                                                "type": "boolean"
+                                                            },
+                                                        },
+                                                    },
+                                                },
+                                                "description": "Nested preference object",
+                                            }
+                                        },
+                                        "required": ["preferences"],
+                                    }
+                                }
+                            },
+                        },
+                        "responses": {
+                            "200": {
+                                "description": "Preferences updated",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "success": {"type": "boolean"}
+                                            },
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                },
+            },
+        }
+
+    async def test_deepobject_style_parsing_from_spec(self, deepobject_spec):
+        """Test that deepObject style parameters are correctly parsed from OpenAPI spec."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=deepobject_spec,
+                client=client,
+                name="DeepObject Test Server",
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                # Find the surveys tool
+                surveys_tool = next(
+                    tool for tool in tools if tool.name == "get_surveys"
+                )
+                assert surveys_tool is not None
+
+                # Check that deepObject parameters are included in schema
+                params = surveys_tool.input_schema
+                properties = params["properties"]
+
+                # Should have the deepObject parameters
+                assert "target" in properties
+                assert "filters" in properties
+                assert "compact" in properties
+
+                # Check that target parameter is present
+                # (Exact schema structure may vary based on implementation)
+                target_param = properties["target"]
+                # Should have some structure, exact format may vary
+                assert target_param is not None
+
+    async def test_deepobject_explode_true_handling(self, deepobject_spec):
+        """Test deepObject with explode=true parameter handling."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=deepobject_spec,
+                client=client,
+                name="DeepObject Test Server",
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+                surveys_tool = next(
+                    tool for tool in tools if tool.name == "get_surveys"
+                )
+
+                # Check that explode=true parameters are properly structured
+                params = surveys_tool.input_schema
+                properties = params["properties"]
+
+                # Target parameter with explode=true should allow individual property access
+                target_properties = properties["target"]["properties"]
+                assert "id" in target_properties
+                assert "type" in target_properties
+                assert target_properties["type"]["enum"] == ["location", "organisation"]
+
+    async def test_deepobject_explode_false_handling(self, deepobject_spec):
+        """Test deepObject with explode=false parameter handling."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=deepobject_spec,
+                client=client,
+                name="DeepObject Test Server",
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+                surveys_tool = next(
+                    tool for tool in tools if tool.name == "get_surveys"
+                )
+
+                # Check that explode=false parameters are handled
+                params = surveys_tool.input_schema
+                properties = params["properties"]
+
+                # Compact parameter with explode=false should still be present and valid
+                assert "compact" in properties
+                compact_param = properties["compact"]
+                # Check that it's a valid parameter (exact structure may vary)
+                assert compact_param is not None
+                # If it has a type, it should be object
+                if "type" in compact_param:
+                    assert compact_param["type"] == "object"
+
+    async def test_nested_object_structure_in_request_body(self, deepobject_spec):
+        """Test nested object structures in request body are preserved."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=deepobject_spec,
+                client=client,
+                name="DeepObject Test Server",
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                # Find the preferences tool
+                prefs_tool = next(
+                    tool for tool in tools if tool.name == "update_preferences"
+                )
+                assert prefs_tool is not None
+
+                # Check that nested object structure is preserved
+                params = prefs_tool.input_schema
+                properties = params["properties"]
+
+                # Should have path parameter
+                assert "id" in properties
+
+                # Should have preferences object
+                assert "preferences" in properties
+                prefs_param = properties["preferences"]
+                assert prefs_param["type"] == "object"
+
+                # Check nested structure
+                prefs_props = prefs_param["properties"]
+                assert "theme" in prefs_props
+                assert "notifications" in prefs_props
+                assert "privacy" in prefs_props
+
+                # Check deeply nested objects
+                notifications = prefs_props["notifications"]
+                assert notifications["type"] == "object"
+                notif_props = notifications["properties"]
+                assert "email" in notif_props
+                assert "push" in notif_props
+                assert "frequency" in notif_props
+
+    async def test_deepobject_tool_functionality(self, deepobject_spec):
+        """Test that tools with deepObject parameters maintain basic functionality."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=deepobject_spec,
+                client=client,
+                name="DeepObject Test Server",
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                # Should successfully create tools with deepObject parameters
+                assert len(tools) == 2
+
+                tool_names = {tool.name for tool in tools}
+                assert "get_surveys" in tool_names
+                assert "update_preferences" in tool_names
+
+                # All tools should have valid schemas
+                for tool in tools:
+                    assert tool.input_schema is not None
+                    assert tool.input_schema["type"] == "object"
+                    assert "properties" in tool.input_schema
+
+                    # Should have some properties
+                    assert len(tool.input_schema["properties"]) > 0
diff --git a/tests/server/providers/openapi/test_end_to_end_compatibility.py b/tests/server/providers/openapi/test_end_to_end_compatibility.py
new file mode 100644
index 0000000..29f15a6
--- /dev/null
+++ b/tests/server/providers/openapi/test_end_to_end_compatibility.py
@@ -0,0 +1,221 @@
+"""End-to-end tests for OpenAPIProvider implementation."""
+
+import httpx
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.providers.openapi import OpenAPIProvider
+
+
+def create_openapi_server(
+    openapi_spec: dict,
+    client,
+    name: str = "OpenAPI Server",
+) -> FastMCP:
+    """Helper to create a FastMCP server with OpenAPIProvider."""
+    provider = OpenAPIProvider(openapi_spec=openapi_spec, client=client)
+    mcp = FastMCP(name)
+    mcp.add_provider(provider)
+    return mcp
+
+
+class TestEndToEndFunctionality:
+    """Test end-to-end functionality of OpenAPIProvider."""
+
+    @pytest.fixture
+    def simple_spec(self):
+        """Simple OpenAPI spec for testing."""
+        return {
+            "openapi": "3.0.0",
+            "info": {"title": "Test API", "version": "1.0.0"},
+            "paths": {
+                "/users/{id}": {
+                    "get": {
+                        "operationId": "get_user",
+                        "summary": "Get user by ID",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "integer"},
+                            },
+                            {
+                                "name": "include_details",
+                                "in": "query",
+                                "required": False,
+                                "schema": {"type": "boolean"},
+                            },
+                        ],
+                        "responses": {"200": {"description": "User found"}},
+                    }
+                }
+            },
+        }
+
+    @pytest.fixture
+    def collision_spec(self):
+        """OpenAPI spec with parameter collisions."""
+        return {
+            "openapi": "3.0.0",
+            "info": {"title": "Collision API", "version": "1.0.0"},
+            "paths": {
+                "/users/{id}": {
+                    "put": {
+                        "operationId": "update_user",
+                        "summary": "Update user",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "integer"},
+                            }
+                        ],
+                        "requestBody": {
+                            "required": True,
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "properties": {
+                                            "id": {"type": "integer"},
+                                            "name": {"type": "string"},
+                                        },
+                                        "required": ["name"],
+                                    }
+                                }
+                            },
+                        },
+                        "responses": {"200": {"description": "User updated"}},
+                    }
+                }
+            },
+        }
+
+    async def test_tool_schema_generation(self, simple_spec):
+        """Test that tools have correct input schemas."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=simple_spec,
+                client=client,
+                name="Test Server",
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                # Should have one tool
+                assert len(tools) == 1
+
+                tool = tools[0]
+                assert tool.name == "get_user"
+                assert tool.description
+
+                # Check schema structure
+                schema = tool.input_schema
+                assert schema["type"] == "object"
+
+                properties = schema.get("properties", {})
+                assert "id" in properties
+                assert "include_details" in properties
+
+                # Required fields should include path parameter
+                required = schema.get("required", [])
+                assert "id" in required
+
+    async def test_collision_handling(self, collision_spec):
+        """Test that parameter collision handling works correctly."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=collision_spec,
+                client=client,
+                name="Collision Test Server",
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                # Should have one tool
+                assert len(tools) == 1
+
+                tool = tools[0]
+                schema = tool.input_schema
+
+                # Both should have collision-resolved parameters
+                properties = schema.get("properties", {})
+
+                # Should have: id__path (path param), id (body param), name (body param)
+                expected_props = {"id__path", "id", "name"}
+                assert set(properties.keys()) == expected_props
+
+                # Required should include path param and required body params
+                required = set(schema.get("required", []))
+                assert "id__path" in required
+                assert "name" in required
+
+                # Path parameter should have integer type
+                assert properties["id__path"]["type"] == "integer"
+
+                # Body parameters should match
+                assert properties["id"]["type"] == "integer"
+                assert properties["name"]["type"] == "string"
+
+    async def test_tool_execution_parameter_mapping(self, collision_spec):
+        """Test that tool execution with collisions works correctly."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=collision_spec,
+                client=client,
+                name="Test Server",
+            )
+
+            # Test arguments that should work with collision resolution
+            test_args = {
+                "id__path": 123,  # Path parameter (suffixed)
+                "id": 456,  # Body parameter (not suffixed)
+                "name": "John Doe",  # Body parameter
+            }
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+                tool_name = tools[0].name
+
+                # Should fail at HTTP level (not argument validation)
+                # since we don't have an actual server
+                with pytest.raises(Exception) as exc_info:
+                    await mcp_client.call_tool(tool_name, test_args)
+
+                # Should fail at HTTP level, not schema validation
+                error_msg = str(exc_info.value).lower()
+                assert "schema" not in error_msg
+                assert "validation" not in error_msg
+
+    async def test_optional_parameter_handling(self, simple_spec):
+        """Test that optional parameters are handled correctly."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=simple_spec,
+                client=client,
+                name="Test Server",
+            )
+
+            # Test with optional parameter omitted
+            test_args_minimal = {"id": 123}
+
+            # Test with optional parameter included
+            test_args_full = {"id": 123, "include_details": True}
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+                tool_name = tools[0].name
+
+                # Both should fail at HTTP level (not argument validation)
+                for test_args in [test_args_minimal, test_args_full]:
+                    with pytest.raises(Exception) as exc_info:
+                        await mcp_client.call_tool(tool_name, test_args)
+
+                    error_msg = str(exc_info.value).lower()
+                    assert "schema" not in error_msg
+                    assert "validation" not in error_msg
diff --git a/tests/server/providers/openapi/test_openapi_features.py b/tests/server/providers/openapi/test_openapi_features.py
new file mode 100644
index 0000000..95c7f1a
--- /dev/null
+++ b/tests/server/providers/openapi/test_openapi_features.py
@@ -0,0 +1,1339 @@
+"""Tests for OpenAPI feature support in OpenAPIProvider."""
+
+from typing import Any
+from unittest.mock import AsyncMock, Mock
+
+import httpx
+import pytest
+from httpx import Response
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.providers.openapi import OpenAPIProvider
+from fastmcp.server.providers.openapi.components import (
+    _extract_mime_type_from_route,
+    _redact_headers,
+)
+from fastmcp.server.providers.openapi.routing import MCPType, RouteMap
+from fastmcp.utilities.openapi.models import HTTPRoute, ResponseInfo
+
+
+def create_openapi_server(
+    openapi_spec: dict,
+    client,
+    name: str = "OpenAPI Server",
+) -> FastMCP:
+    """Helper to create a FastMCP server with OpenAPIProvider."""
+    provider = OpenAPIProvider(openapi_spec=openapi_spec, client=client)
+    mcp = FastMCP(name)
+    mcp.add_provider(provider)
+    return mcp
+
+
+class TestParameterHandling:
+    """Test OpenAPI parameter handling features."""
+
+    @pytest.fixture
+    def parameter_spec(self):
+        """OpenAPI spec with various parameter types."""
+        return {
+            "openapi": "3.0.0",
+            "info": {"title": "Parameter Test API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com"}],
+            "paths": {
+                "/search": {
+                    "get": {
+                        "operationId": "search_items",
+                        "summary": "Search items",
+                        "parameters": [
+                            {
+                                "name": "query",
+                                "in": "query",
+                                "required": True,
+                                "schema": {"type": "string"},
+                                "description": "Search query",
+                            },
+                            {
+                                "name": "limit",
+                                "in": "query",
+                                "required": False,
+                                "schema": {
+                                    "type": "integer",
+                                    "minimum": 1,
+                                    "maximum": 100,
+                                },
+                                "description": "Maximum number of results",
+                            },
+                            {
+                                "name": "tags",
+                                "in": "query",
+                                "required": False,
+                                "schema": {
+                                    "type": "array",
+                                    "items": {"type": "string"},
+                                },
+                                "style": "form",
+                                "explode": True,
+                                "description": "Filter by tags",
+                            },
+                            {
+                                "name": "X-API-Key",
+                                "in": "header",
+                                "required": True,
+                                "schema": {"type": "string"},
+                                "description": "API key for authentication",
+                            },
+                        ],
+                        "responses": {
+                            "200": {
+                                "description": "Search results",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "items": {
+                                                    "type": "array",
+                                                    "items": {"type": "object"},
+                                                },
+                                                "total": {"type": "integer"},
+                                            },
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                },
+                "/users/{id}/posts/{post_id}": {
+                    "get": {
+                        "operationId": "get_user_post",
+                        "summary": "Get specific user post",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "integer"},
+                                "description": "User ID",
+                            },
+                            {
+                                "name": "post_id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "integer"},
+                                "description": "Post ID",
+                            },
+                        ],
+                        "responses": {
+                            "200": {
+                                "description": "User post",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "id": {"type": "integer"},
+                                                "title": {"type": "string"},
+                                                "content": {"type": "string"},
+                                            },
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                },
+            },
+        }
+
+    async def test_query_parameters_in_tools(self, parameter_spec):
+        """Test that query parameters are properly included in tool parameters."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=parameter_spec, client=client, name="Parameter Test Server"
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                # Find the search tool
+                search_tool = next(
+                    tool for tool in tools if tool.name == "search_items"
+                )
+                assert search_tool is not None
+
+                # Check that parameters are included in the tool's input schema
+                params = search_tool.input_schema
+                assert params["type"] == "object"
+
+                properties = params["properties"]
+
+                # Check that key parameters are present
+                # (Schema details may vary based on implementation)
+                assert "query" in properties
+                assert "limit" in properties
+                assert "tags" in properties
+                assert "X-API-Key" in properties
+
+                # Check that parameter descriptions are included
+                assert "description" in properties["query"], (
+                    "Query parameter should have description"
+                )
+                assert properties["query"]["description"] == "Search query"
+                assert "description" in properties["limit"], (
+                    "Limit parameter should have description"
+                )
+                assert properties["limit"]["description"] == "Maximum number of results"
+                assert "description" in properties["tags"], (
+                    "Tags parameter should have description"
+                )
+                assert properties["tags"]["description"] == "Filter by tags"
+
+                # Check that required parameters are marked as required
+                required = params.get("required", [])
+                assert "query" in required
+                assert "X-API-Key" in required
+
+    async def test_path_parameters_in_tools(self, parameter_spec):
+        """Test that path parameters are properly included in tool parameters."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=parameter_spec, client=client, name="Parameter Test Server"
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                # Find the user post tool
+                user_post_tool = next(
+                    tool for tool in tools if tool.name == "get_user_post"
+                )
+                assert user_post_tool is not None
+
+                # Check that path parameters are included
+                params = user_post_tool.input_schema
+                properties = params["properties"]
+
+                # Check that path parameters are present
+                assert "id" in properties
+                assert "post_id" in properties
+
+                # Path parameters should be required
+                required = params.get("required", [])
+                assert "id" in required
+                assert "post_id" in required
+
+
+class TestRequestBodyHandling:
+    """Test OpenAPI request body handling."""
+
+    @pytest.fixture
+    def request_body_spec(self):
+        """OpenAPI spec with request body."""
+        return {
+            "openapi": "3.0.0",
+            "info": {"title": "Request Body Test API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com"}],
+            "paths": {
+                "/users": {
+                    "post": {
+                        "operationId": "create_user",
+                        "summary": "Create a user",
+                        "requestBody": {
+                            "required": True,
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "properties": {
+                                            "name": {
+                                                "type": "string",
+                                                "description": "User's full name",
+                                            },
+                                            "email": {
+                                                "type": "string",
+                                                "format": "email",
+                                                "description": "User's email address",
+                                            },
+                                            "age": {
+                                                "type": "integer",
+                                                "minimum": 0,
+                                                "maximum": 150,
+                                                "description": "User's age",
+                                            },
+                                            "preferences": {
+                                                "type": "object",
+                                                "properties": {
+                                                    "theme": {"type": "string"},
+                                                    "notifications": {
+                                                        "type": "boolean"
+                                                    },
+                                                },
+                                                "description": "User preferences",
+                                            },
+                                        },
+                                        "required": ["name", "email"],
+                                    }
+                                }
+                            },
+                        },
+                        "responses": {
+                            "201": {
+                                "description": "User created",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "id": {"type": "integer"},
+                                                "name": {"type": "string"},
+                                                "email": {"type": "string"},
+                                            },
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                }
+            },
+        }
+
+    async def test_request_body_properties_in_tool(self, request_body_spec):
+        """Test that request body properties are included in tool parameters."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=request_body_spec,
+                client=client,
+                name="Request Body Test Server",
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                # Find the create user tool
+                create_tool = next(tool for tool in tools if tool.name == "create_user")
+                assert create_tool is not None
+
+                # Check that request body properties are included
+                params = create_tool.input_schema
+                properties = params["properties"]
+
+                # Check that request body properties are present
+                assert "name" in properties
+                assert "email" in properties
+                assert "age" in properties
+                assert "preferences" in properties
+
+                # Check required fields from request body
+                required = params.get("required", [])
+                assert "name" in required
+                assert "email" in required
+
+
+class TestResponseSchemas:
+    """Test OpenAPI response schema handling."""
+
+    @pytest.fixture
+    def response_schema_spec(self):
+        """OpenAPI spec with detailed response schemas."""
+        return {
+            "openapi": "3.0.0",
+            "info": {"title": "Response Schema Test API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com"}],
+            "paths": {
+                "/users/{id}": {
+                    "get": {
+                        "operationId": "get_user",
+                        "summary": "Get user details",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "integer"},
+                            }
+                        ],
+                        "responses": {
+                            "200": {
+                                "description": "User details retrieved successfully",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "id": {"type": "integer"},
+                                                "name": {"type": "string"},
+                                                "email": {"type": "string"},
+                                                "profile": {
+                                                    "type": "object",
+                                                    "properties": {
+                                                        "bio": {"type": "string"},
+                                                        "avatar_url": {
+                                                            "type": "string"
+                                                        },
+                                                    },
+                                                },
+                                            },
+                                            "required": ["id", "name", "email"],
+                                        }
+                                    }
+                                },
+                            },
+                            "404": {
+                                "description": "User not found",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "error": {"type": "string"},
+                                                "code": {"type": "integer"},
+                                            },
+                                        }
+                                    }
+                                },
+                            },
+                        },
+                    }
+                }
+            },
+        }
+
+    async def test_tool_has_output_schema(self, response_schema_spec):
+        """Test that tools have output schemas from response definitions."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=response_schema_spec,
+                client=client,
+                name="Response Schema Test Server",
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                # Find the get user tool
+                get_user_tool = next(tool for tool in tools if tool.name == "get_user")
+                assert get_user_tool is not None
+
+                # Check that the tool has an output schema
+                # Note: output schema might be None if not extracted properly
+                # Let's just check the tool exists and has basic properties
+                assert get_user_tool.description is not None
+                assert get_user_tool.name == "get_user"
+
+
+class TestMimeTypeExtraction:
+    """Test MIME type extraction from route responses."""
+
+    def test_json_response(self):
+        """JSON content type is correctly extracted."""
+        route = HTTPRoute(
+            path="/items",
+            method="GET",
+            responses={
+                "200": ResponseInfo(
+                    content_schema={"application/json": {"type": "object"}}
+                )
+            },
+        )
+        assert _extract_mime_type_from_route(route) == "application/json"
+
+    def test_text_plain_response(self):
+        """Plain text content type is correctly extracted."""
+        route = HTTPRoute(
+            path="/health",
+            method="GET",
+            responses={
+                "200": ResponseInfo(content_schema={"text/plain": {"type": "string"}})
+            },
+        )
+        assert _extract_mime_type_from_route(route) == "text/plain"
+
+    def test_text_html_response(self):
+        """HTML content type is correctly extracted."""
+        route = HTTPRoute(
+            path="/page",
+            method="GET",
+            responses={
+                "200": ResponseInfo(content_schema={"text/html": {"type": "string"}})
+            },
+        )
+        assert _extract_mime_type_from_route(route) == "text/html"
+
+    def test_image_response(self):
+        """Image content type is correctly extracted."""
+        route = HTTPRoute(
+            path="/avatar",
+            method="GET",
+            responses={
+                "200": ResponseInfo(
+                    content_schema={"image/png": {"type": "string", "format": "binary"}}
+                )
+            },
+        )
+        assert _extract_mime_type_from_route(route) == "image/png"
+
+    def test_no_responses_defaults_to_json(self):
+        """Empty responses default to application/json."""
+        route = HTTPRoute(path="/items", method="GET", responses={})
+        assert _extract_mime_type_from_route(route) == "application/json"
+
+    def test_no_content_schema_defaults_to_json(self):
+        """Response without content_schema defaults to application/json."""
+        route = HTTPRoute(
+            path="/items",
+            method="GET",
+            responses={"204": ResponseInfo(description="No content")},
+        )
+        assert _extract_mime_type_from_route(route) == "application/json"
+
+    def test_prefers_json_when_multiple_types(self):
+        """When both JSON and other types exist, JSON is preferred."""
+        route = HTTPRoute(
+            path="/items",
+            method="GET",
+            responses={
+                "200": ResponseInfo(
+                    content_schema={
+                        "text/html": {"type": "string"},
+                        "application/json": {"type": "object"},
+                    }
+                )
+            },
+        )
+        assert _extract_mime_type_from_route(route) == "application/json"
+
+    def test_non_standard_2xx_code(self):
+        """Falls back to any 2xx status code when standard ones are missing."""
+        route = HTTPRoute(
+            path="/items",
+            method="GET",
+            responses={
+                "206": ResponseInfo(
+                    content_schema={
+                        "application/octet-stream": {
+                            "type": "string",
+                            "format": "binary",
+                        }
+                    }
+                )
+            },
+        )
+        assert _extract_mime_type_from_route(route) == "application/octet-stream"
+
+    def test_ignores_error_responses(self):
+        """Only error responses (no 2xx) results in default."""
+        route = HTTPRoute(
+            path="/items",
+            method="GET",
+            responses={
+                "404": ResponseInfo(
+                    content_schema={"application/json": {"type": "object"}}
+                )
+            },
+        )
+        assert _extract_mime_type_from_route(route) == "application/json"
+
+    def test_201_response(self):
+        """201 Created response content type is extracted."""
+        route = HTTPRoute(
+            path="/items",
+            method="POST",
+            responses={
+                "201": ResponseInfo(content_schema={"text/plain": {"type": "string"}})
+            },
+        )
+        assert _extract_mime_type_from_route(route) == "text/plain"
+
+    def test_media_type_without_schema(self):
+        """Media type declared without a schema still infers MIME type."""
+        route = HTTPRoute(
+            path="/health",
+            method="GET",
+            responses={"200": ResponseInfo(content_schema={"text/plain": {}})},
+        )
+        assert _extract_mime_type_from_route(route) == "text/plain"
+
+
+class TestResourceTemplateMimeType:
+    """Test that OpenAPIResourceTemplate uses inferred MIME types."""
+
+    @pytest.fixture
+    def text_plain_spec(self):
+        """OpenAPI spec with a text/plain resource template endpoint."""
+        return {
+            "openapi": "3.0.0",
+            "info": {"title": "Text API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com"}],
+            "paths": {
+                "/documents/{id}": {
+                    "get": {
+                        "operationId": "get_document",
+                        "summary": "Get document content",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "string"},
+                            }
+                        ],
+                        "responses": {
+                            "200": {
+                                "description": "Document content",
+                                "content": {
+                                    "text/plain": {"schema": {"type": "string"}}
+                                },
+                            }
+                        },
+                    }
+                }
+            },
+        }
+
+    @pytest.fixture
+    def html_spec(self):
+        """OpenAPI spec with a text/html resource endpoint."""
+        return {
+            "openapi": "3.0.0",
+            "info": {"title": "HTML API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com"}],
+            "paths": {
+                "/pages/{slug}": {
+                    "get": {
+                        "operationId": "get_page",
+                        "summary": "Get HTML page",
+                        "parameters": [
+                            {
+                                "name": "slug",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "string"},
+                            }
+                        ],
+                        "responses": {
+                            "200": {
+                                "description": "HTML page",
+                                "content": {
+                                    "text/html": {"schema": {"type": "string"}}
+                                },
+                            }
+                        },
+                    }
+                }
+            },
+        }
+
+    async def test_resource_template_text_plain_mime_type(self, text_plain_spec):
+        """Resource template should reflect text/plain from OpenAPI spec."""
+        route_maps = [RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE_TEMPLATE)]
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            provider = OpenAPIProvider(
+                openapi_spec=text_plain_spec, client=client, route_maps=route_maps
+            )
+            mcp = FastMCP("Test")
+            mcp.add_provider(provider)
+            async with Client(mcp) as mcp_client:
+                templates = await mcp_client.list_resource_templates()
+                assert len(templates) == 1
+                assert templates[0].mime_type == "text/plain"
+
+    async def test_resource_template_html_mime_type(self, html_spec):
+        """Resource template should reflect text/html from OpenAPI spec."""
+        route_maps = [RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE_TEMPLATE)]
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            provider = OpenAPIProvider(
+                openapi_spec=html_spec, client=client, route_maps=route_maps
+            )
+            mcp = FastMCP("Test")
+            mcp.add_provider(provider)
+            async with Client(mcp) as mcp_client:
+                templates = await mcp_client.list_resource_templates()
+                assert len(templates) == 1
+                assert templates[0].mime_type == "text/html"
+
+    async def test_resource_template_defaults_json_mime_type(self):
+        """Resource template defaults to application/json for JSON responses."""
+        spec = {
+            "openapi": "3.0.0",
+            "info": {"title": "JSON API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com"}],
+            "paths": {
+                "/users/{id}": {
+                    "get": {
+                        "operationId": "get_user",
+                        "summary": "Get user",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "integer"},
+                            }
+                        ],
+                        "responses": {
+                            "200": {
+                                "description": "User data",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "id": {"type": "integer"},
+                                                "name": {"type": "string"},
+                                            },
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                }
+            },
+        }
+        route_maps = [RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE_TEMPLATE)]
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            provider = OpenAPIProvider(
+                openapi_spec=spec, client=client, route_maps=route_maps
+            )
+            mcp = FastMCP("Test")
+            mcp.add_provider(provider)
+            async with Client(mcp) as mcp_client:
+                templates = await mcp_client.list_resource_templates()
+                assert len(templates) == 1
+                assert templates[0].mime_type == "application/json"
+
+
+class TestResourceTemplateRequestBuilding:
+    @pytest.fixture
+    def path_param_spec(self) -> dict[str, Any]:
+        return {
+            "openapi": "3.0.0",
+            "info": {"title": "User API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com/api/v1"}],
+            "paths": {
+                "/users/{id}": {
+                    "get": {
+                        "operationId": "get_user",
+                        "summary": "Get user",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "string"},
+                            }
+                        ],
+                        "responses": {
+                            "200": {
+                                "description": "User data",
+                                "content": {
+                                    "application/json": {"schema": {"type": "object"}}
+                                },
+                            }
+                        },
+                    }
+                }
+            },
+        }
+
+    async def test_resource_template_encodes_matched_path_params(
+        self, path_param_spec: dict[str, Any]
+    ):
+        seen_urls: list[httpx.URL] = []
+
+        async def handler(request: httpx.Request) -> httpx.Response:
+            seen_urls.append(request.url)
+            return httpx.Response(200, json={"ok": True})
+
+        route_maps = [RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE_TEMPLATE)]
+        async with httpx.AsyncClient(
+            base_url="https://api.example.com/api/v1",
+            transport=httpx.MockTransport(handler),
+        ) as client:
+            provider = OpenAPIProvider(
+                openapi_spec=path_param_spec,
+                client=client,
+                route_maps=route_maps,
+            )
+            mcp = FastMCP("Test")
+            mcp.add_provider(provider)
+
+            async with Client(mcp) as mcp_client:
+                await mcp_client.read_resource(
+                    "resource://get_user/..%2F..%2Fadmin%2Fsecret"
+                )
+
+        assert seen_urls == [
+            httpx.URL(
+                "https://api.example.com/api/v1/users/%2E%2E%2F%2E%2E%2Fadmin%2Fsecret"
+            )
+        ]
+
+    async def test_resource_template_ignores_unmatched_query_string(
+        self, path_param_spec: dict[str, Any]
+    ):
+        seen_urls: list[httpx.URL] = []
+
+        async def handler(request: httpx.Request) -> httpx.Response:
+            seen_urls.append(request.url)
+            return httpx.Response(200, json={"ok": True})
+
+        route_maps = [RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE_TEMPLATE)]
+        async with httpx.AsyncClient(
+            base_url="https://api.example.com/api/v1",
+            transport=httpx.MockTransport(handler),
+        ) as client:
+            provider = OpenAPIProvider(
+                openapi_spec=path_param_spec,
+                client=client,
+                route_maps=route_maps,
+            )
+            mcp = FastMCP("Test")
+            mcp.add_provider(provider)
+
+            async with Client(mcp) as mcp_client:
+                await mcp_client.read_resource("resource://get_user/alice?admin=true")
+
+        assert seen_urls == [httpx.URL("https://api.example.com/api/v1/users/alice")]
+
+    async def test_resource_template_preserves_hyphenated_path_params(self):
+        seen_urls: list[httpx.URL] = []
+
+        async def handler(request: httpx.Request) -> httpx.Response:
+            seen_urls.append(request.url)
+            return httpx.Response(200, json={"ok": True})
+
+        spec = {
+            "openapi": "3.0.0",
+            "info": {"title": "User API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com/api/v1"}],
+            "paths": {
+                "/users/{user-id}": {
+                    "get": {
+                        "operationId": "get_user",
+                        "parameters": [
+                            {
+                                "name": "user-id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "string"},
+                            }
+                        ],
+                        "responses": {
+                            "200": {
+                                "description": "User data",
+                                "content": {
+                                    "application/json": {"schema": {"type": "object"}}
+                                },
+                            }
+                        },
+                    }
+                }
+            },
+        }
+
+        route_maps = [RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE_TEMPLATE)]
+        async with httpx.AsyncClient(
+            base_url="https://api.example.com/api/v1",
+            transport=httpx.MockTransport(handler),
+        ) as client:
+            provider = OpenAPIProvider(
+                openapi_spec=spec,
+                client=client,
+                route_maps=route_maps,
+            )
+            mcp = FastMCP("Test")
+            mcp.add_provider(provider)
+
+            async with Client(mcp) as mcp_client:
+                await mcp_client.read_resource("resource://get_user/abc")
+
+        assert seen_urls == [httpx.URL("https://api.example.com/api/v1/users/abc")]
+
+    async def test_resource_template_preserves_client_defaults(
+        self, path_param_spec: dict[str, Any]
+    ):
+        seen_requests: list[httpx.Request] = []
+
+        async def handler(request: httpx.Request) -> httpx.Response:
+            seen_requests.append(request)
+            return httpx.Response(200, json={"ok": True})
+
+        route_maps = [RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE_TEMPLATE)]
+        async with httpx.AsyncClient(
+            base_url="https://api.example.com/api/v1",
+            params={"api-version": "2026-06-29"},
+            cookies={"session": "abc123"},
+            transport=httpx.MockTransport(handler),
+        ) as client:
+            provider = OpenAPIProvider(
+                openapi_spec=path_param_spec,
+                client=client,
+                route_maps=route_maps,
+            )
+            mcp = FastMCP("Test")
+            mcp.add_provider(provider)
+
+            async with Client(mcp) as mcp_client:
+                await mcp_client.read_resource("resource://get_user/alice")
+
+        assert seen_requests[0].url == httpx.URL(
+            "https://api.example.com/api/v1/users/alice?api-version=2026-06-29"
+        )
+        assert seen_requests[0].headers["cookie"] == "session=abc123"
+
+    async def test_resource_template_uses_mapped_path_argument_names(self):
+        seen_urls: list[httpx.URL] = []
+
+        async def handler(request: httpx.Request) -> httpx.Response:
+            seen_urls.append(request.url)
+            return httpx.Response(200, json={"ok": True})
+
+        spec = {
+            "openapi": "3.0.0",
+            "info": {"title": "User API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com/api/v1"}],
+            "paths": {
+                "/users/{id}": {
+                    "get": {
+                        "operationId": "get_user",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "string"},
+                            }
+                        ],
+                        "requestBody": {
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "properties": {
+                                            "id": {"type": "string"},
+                                            "name": {"type": "string"},
+                                        },
+                                    }
+                                }
+                            }
+                        },
+                        "responses": {
+                            "200": {
+                                "description": "User data",
+                                "content": {
+                                    "application/json": {"schema": {"type": "object"}}
+                                },
+                            }
+                        },
+                    }
+                }
+            },
+        }
+
+        route_maps = [RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE_TEMPLATE)]
+        async with httpx.AsyncClient(
+            base_url="https://api.example.com/api/v1",
+            transport=httpx.MockTransport(handler),
+        ) as client:
+            provider = OpenAPIProvider(
+                openapi_spec=spec,
+                client=client,
+                route_maps=route_maps,
+            )
+            mcp = FastMCP("Test")
+            mcp.add_provider(provider)
+
+            async with Client(mcp) as mcp_client:
+                await mcp_client.read_resource("resource://get_user/abc")
+
+        assert seen_urls == [httpx.URL("https://api.example.com/api/v1/users/abc")]
+
+    async def test_resource_template_uses_path_arg_when_query_param_has_same_name(
+        self,
+    ):
+        seen_urls: list[httpx.URL] = []
+
+        async def handler(request: httpx.Request) -> httpx.Response:
+            seen_urls.append(request.url)
+            return httpx.Response(200, json={"ok": True})
+
+        spec = {
+            "openapi": "3.0.0",
+            "info": {"title": "User API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com/api/v1"}],
+            "paths": {
+                "/users/{id}": {
+                    "get": {
+                        "operationId": "get_user",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "string"},
+                            },
+                            {
+                                "name": "id",
+                                "in": "query",
+                                "required": False,
+                                "schema": {"type": "string"},
+                            },
+                        ],
+                        "responses": {
+                            "200": {
+                                "description": "User data",
+                                "content": {
+                                    "application/json": {"schema": {"type": "object"}}
+                                },
+                            }
+                        },
+                    }
+                }
+            },
+        }
+
+        route_maps = [RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE_TEMPLATE)]
+        async with httpx.AsyncClient(
+            base_url="https://api.example.com/api/v1",
+            transport=httpx.MockTransport(handler),
+        ) as client:
+            provider = OpenAPIProvider(
+                openapi_spec=spec,
+                client=client,
+                route_maps=route_maps,
+            )
+            mcp = FastMCP("Test")
+            mcp.add_provider(provider)
+
+            async with Client(mcp) as mcp_client:
+                await mcp_client.read_resource("resource://get_user/abc")
+
+        assert seen_urls == [httpx.URL("https://api.example.com/api/v1/users/abc")]
+
+
+class TestResourceMimeType:
+    """Test that OpenAPIResource uses inferred MIME types."""
+
+    async def test_resource_text_plain_mime_type(self):
+        """Static resource should reflect text/plain from OpenAPI spec."""
+        spec = {
+            "openapi": "3.0.0",
+            "info": {"title": "Health API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com"}],
+            "paths": {
+                "/health": {
+                    "get": {
+                        "operationId": "healthcheck",
+                        "summary": "Health check",
+                        "responses": {
+                            "200": {
+                                "description": "Health status",
+                                "content": {
+                                    "text/plain": {"schema": {"type": "string"}}
+                                },
+                            }
+                        },
+                    }
+                }
+            },
+        }
+        route_maps = [RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE)]
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            provider = OpenAPIProvider(
+                openapi_spec=spec, client=client, route_maps=route_maps
+            )
+            mcp = FastMCP("Test")
+            mcp.add_provider(provider)
+            async with Client(mcp) as mcp_client:
+                resources = await mcp_client.list_resources()
+                assert len(resources) == 1
+                assert resources[0].mime_type == "text/plain"
+
+    async def test_resource_mime_type_without_schema(self):
+        """Resource with media type but no schema still infers MIME type."""
+        spec = {
+            "openapi": "3.0.0",
+            "info": {"title": "Health API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com"}],
+            "paths": {
+                "/health": {
+                    "get": {
+                        "operationId": "healthcheck",
+                        "summary": "Health check",
+                        "responses": {
+                            "200": {
+                                "description": "Health status",
+                                "content": {"text/plain": {}},
+                            }
+                        },
+                    }
+                }
+            },
+        }
+        route_maps = [RouteMap(methods=["GET"], mcp_type=MCPType.RESOURCE)]
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            provider = OpenAPIProvider(
+                openapi_spec=spec, client=client, route_maps=route_maps
+            )
+            mcp = FastMCP("Test")
+            mcp.add_provider(provider)
+            async with Client(mcp) as mcp_client:
+                resources = await mcp_client.list_resources()
+                assert len(resources) == 1
+                assert resources[0].mime_type == "text/plain"
+
+
+class TestValidateOutput:
+    """Tests for the validate_output option on OpenAPIProvider."""
+
+    @pytest.fixture
+    def spec_with_output_schema(self):
+        return {
+            "openapi": "3.0.0",
+            "info": {"title": "Test API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com"}],
+            "paths": {
+                "/users/{id}": {
+                    "get": {
+                        "operationId": "get_user",
+                        "summary": "Get a user",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "integer"},
+                            }
+                        ],
+                        "responses": {
+                            "200": {
+                                "description": "A user",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "id": {"type": "integer"},
+                                                "name": {"type": "string"},
+                                                "email": {"type": "string"},
+                                            },
+                                            "required": ["id", "name"],
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                },
+                "/items": {
+                    "get": {
+                        "operationId": "list_items",
+                        "summary": "List items",
+                        "responses": {
+                            "200": {
+                                "description": "An array of items",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "array",
+                                            "items": {
+                                                "type": "object",
+                                                "properties": {
+                                                    "name": {"type": "string"}
+                                                },
+                                            },
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                },
+            },
+        }
+
+    async def test_validate_output_true_preserves_extracted_schema(
+        self, spec_with_output_schema
+    ):
+        """Default validate_output=True uses the real extracted schema."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            provider = OpenAPIProvider(
+                openapi_spec=spec_with_output_schema,
+                client=client,
+            )
+
+            tool = provider._tools["get_user"]
+            assert tool.output_schema is not None
+            assert tool.output_schema.get("type") == "object"
+            assert "properties" in tool.output_schema
+            assert "id" in tool.output_schema["properties"]
+
+    async def test_validate_output_false_uses_permissive_schema(
+        self, spec_with_output_schema
+    ):
+        """validate_output=False replaces the schema with a permissive one."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            provider = OpenAPIProvider(
+                openapi_spec=spec_with_output_schema,
+                client=client,
+                validate_output=False,
+            )
+
+            tool = provider._tools["get_user"]
+            assert tool.output_schema is not None
+            assert tool.output_schema == {
+                "type": "object",
+                "additionalProperties": True,
+            }
+
+    async def test_validate_output_false_preserves_wrap_result_flag(
+        self, spec_with_output_schema
+    ):
+        """validate_output=False preserves x-fastmcp-wrap-result for array responses."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            provider = OpenAPIProvider(
+                openapi_spec=spec_with_output_schema,
+                client=client,
+                validate_output=False,
+            )
+
+            # The list_items endpoint returns an array, so the extracted schema
+            # would have had x-fastmcp-wrap-result=True
+            tool = provider._tools["list_items"]
+            assert tool.output_schema is not None
+            assert tool.output_schema.get("x-fastmcp-wrap-result") is True
+            assert tool.output_schema.get("additionalProperties") is True
+
+    async def test_validate_output_false_allows_nonconforming_response(
+        self, spec_with_output_schema
+    ):
+        """With validate_output=False, responses that don't match the spec succeed."""
+        mock_client = Mock(spec=httpx.AsyncClient)
+        mock_client.base_url = "https://api.example.com"
+        mock_client.headers = None
+
+        # Return extra fields not in the schema
+        mock_response = Mock(spec=Response)
+        mock_response.status_code = 200
+        mock_response.json.return_value = {
+            "id": 1,
+            "name": "Alice",
+            "email": "alice@example.com",
+            "unexpected_field": "surprise",
+            "nested": {"deep": True},
+        }
+        mock_response.raise_for_status = Mock()
+        mock_client.send = AsyncMock(return_value=mock_response)
+
+        provider = OpenAPIProvider(
+            openapi_spec=spec_with_output_schema,
+            client=mock_client,
+            validate_output=False,
+        )
+        mcp = FastMCP("Test")
+        mcp.add_provider(provider)
+
+        async with Client(mcp) as mcp_client:
+            result = await mcp_client.call_tool("get_user", {"id": 1})
+            assert result is not None
+            # Structured content should have the full response including extra fields
+            assert result.structured_content is not None
+            assert result.structured_content["unexpected_field"] == "surprise"
+
+    async def test_validate_output_false_wraps_non_dict_response(
+        self, spec_with_output_schema
+    ):
+        """Non-dict responses are wrapped even when schema says object and validate_output=False."""
+        mock_client = Mock(spec=httpx.AsyncClient)
+        mock_client.base_url = "https://api.example.com"
+        mock_client.headers = None
+
+        # Backend returns an array even though schema says object
+        mock_response = Mock(spec=Response)
+        mock_response.status_code = 200
+        mock_response.json.return_value = [{"id": 1}, {"id": 2}]
+        mock_response.raise_for_status = Mock()
+        mock_client.send = AsyncMock(return_value=mock_response)
+
+        provider = OpenAPIProvider(
+            openapi_spec=spec_with_output_schema,
+            client=mock_client,
+            validate_output=False,
+        )
+        mcp = FastMCP("Test")
+        mcp.add_provider(provider)
+
+        async with Client(mcp) as mcp_client:
+            result = await mcp_client.call_tool("get_user", {"id": 1})
+            assert result is not None
+            # Non-dict should be wrapped so structured_content is always a dict
+            assert result.structured_content is not None
+            assert isinstance(result.structured_content, dict)
+            assert result.structured_content["result"] == [{"id": 1}, {"id": 2}]
+
+    async def test_from_openapi_threads_validate_output(self, spec_with_output_schema):
+        """FastMCP.from_openapi() correctly passes validate_output to the provider."""
+        mock_client = Mock(spec=httpx.AsyncClient)
+        mock_client.base_url = "https://api.example.com"
+        mock_client.headers = None
+
+        server = FastMCP.from_openapi(
+            openapi_spec=spec_with_output_schema,
+            client=mock_client,
+            validate_output=False,
+        )
+
+        async with Client(server) as mcp_client:
+            tools = await mcp_client.list_tools()
+            get_user = next(t for t in tools if t.name == "get_user")
+            # With validate_output=False, the outputSchema should be permissive
+            assert get_user.output_schema is not None
+            assert get_user.output_schema.get("additionalProperties") is True
+            # Should NOT have specific properties from the original schema
+            assert "properties" not in get_user.output_schema
+
+
+class TestRedactHeaders:
+    """Test that non-safe headers are redacted in debug logging."""
+
+    def test_known_sensitive_headers_are_redacted(self):
+        headers = httpx.Headers(
+            {
+                "Authorization": "Bearer secret-token",
+                "X-API-Key": "my-api-key",
+                "Cookie": "session=abc123",
+                "Proxy-Authorization": "Basic creds",
+                "Content-Type": "application/json",
+                "Accept": "text/html",
+            }
+        )
+        redacted = _redact_headers(headers)
+        assert redacted["authorization"] == "***"
+        assert redacted["x-api-key"] == "***"
+        assert redacted["cookie"] == "***"
+        assert redacted["proxy-authorization"] == "***"
+        assert redacted["content-type"] == "application/json"
+        assert redacted["accept"] == "text/html"
+
+    def test_arbitrary_auth_headers_are_redacted(self):
+        """Arbitrary header names (e.g. OpenAPI apiKey-in-header) are redacted."""
+        headers = httpx.Headers(
+            {
+                "X-Custom-Token": "secret",
+                "X-My-Service-Key": "also-secret",
+                "Content-Type": "application/json",
+            }
+        )
+        redacted = _redact_headers(headers)
+        assert redacted["x-custom-token"] == "***"
+        assert redacted["x-my-service-key"] == "***"
+        assert redacted["content-type"] == "application/json"
+
+    def test_safe_only_headers(self):
+        headers = httpx.Headers({"Content-Type": "application/json"})
+        redacted = _redact_headers(headers)
+        assert redacted == {"content-type": "application/json"}
diff --git a/tests/server/providers/openapi/test_openapi_performance.py b/tests/server/providers/openapi/test_openapi_performance.py
new file mode 100644
index 0000000..c09a3ff
--- /dev/null
+++ b/tests/server/providers/openapi/test_openapi_performance.py
@@ -0,0 +1,137 @@
+"""Performance regression tests for OpenAPI parsing.
+
+These tests ensure that large OpenAPI schemas (like GitHub's API) parse quickly
+and don't regress to the slow performance we had before optimization.
+"""
+
+import time
+from typing import Any
+
+import httpx
+import pytest
+
+from fastmcp import FastMCP
+
+
+class TestOpenAPIPerformance:
+    """Performance tests for OpenAPI parsing with real-world large schemas."""
+
+    # 10 second maximum timeout for this test no matter what
+    @pytest.mark.integration
+    @pytest.mark.timeout(10)
+    async def test_github_api_schema_performance(self):
+        """
+        Test that GitHub's full API schema parses quickly.
+
+        This is a regression test to ensure our performance optimizations
+        (eliminating deepcopy, single-pass optimization, smart union adjustment)
+        continue to work. Without these optimizations, this test would take
+        multiple minutes to parse.
+
+        On a local machine, this tests passes in ~2 seconds, but in GHA CI we see
+        times as high as 6-7 seconds, so the test is asserted to pass in under
+        10. Given that, this isn't intended to be a strict performance test, but
+        rather a canary to ensure we don't regress significantly.
+        """
+
+        # Download the full GitHub API schema (typically ~10MB)
+        response = httpx.get(
+            "https://raw.githubusercontent.com/github/rest-api-description/refs/heads/main/descriptions-next/ghes-3.17/ghes-3.17.json",
+            timeout=30.0,  # Allow time for download
+        )
+        response.raise_for_status()
+        schema = response.json()
+
+        # Time the parsing operation
+        start_time = time.time()
+
+        # This should complete quickly with our optimizations
+        mcp_server = FastMCP.from_openapi(schema, httpx.AsyncClient())
+
+        elapsed_time = time.time() - start_time
+
+        print(f"OpenAPI parsing took {elapsed_time:.2f}s")
+
+        # Verify the server was created successfully
+        assert mcp_server is not None
+
+        # Performance regression test: should complete in under 10 seconds
+        assert elapsed_time < 10.0, (
+            f"OpenAPI parsing took {elapsed_time:.2f}s, exceeding 10s limit. "
+            f"This suggests a performance regression."
+        )
+
+        # Verify server and tools were created successfully
+        tools = await mcp_server.list_tools()
+        assert len(tools) > 500
+
+    def test_medium_schema_performance(self):
+        """
+        Test parsing performance with a smaller synthetic schema.
+
+        This test doesn't require network access and provides a baseline
+        for performance testing in CI environments.
+        """
+        # Create a medium-sized synthetic schema
+        schema: dict[str, Any] = {
+            "openapi": "3.0.0",
+            "info": {"title": "Test API", "version": "1.0.0"},
+            "paths": {},
+        }
+
+        # Generate multiple paths to create a reasonably sized schema
+        for i in range(100):
+            path = f"/test/{i}"
+            schema["paths"][path] = {
+                "get": {
+                    "operationId": f"test_{i}",
+                    "parameters": [
+                        {"name": "param1", "in": "query", "schema": {"type": "string"}}
+                    ],
+                    "responses": {
+                        "200": {
+                            "description": "Success",
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "properties": {
+                                            "id": {"type": "integer"},
+                                            "name": {"type": "string"},
+                                            "data": {
+                                                "type": "object",
+                                                "additionalProperties": False,
+                                                "properties": {
+                                                    "value": {"type": "string"},
+                                                    "metadata": {
+                                                        "type": "object",
+                                                        "properties": {
+                                                            "created": {
+                                                                "type": "string"
+                                                            },
+                                                            "updated": {
+                                                                "type": "string"
+                                                            },
+                                                        },
+                                                    },
+                                                },
+                                            },
+                                        },
+                                    }
+                                }
+                            },
+                        }
+                    },
+                }
+            }
+
+        # Time the parsing
+        start_time = time.time()
+        mcp_server = FastMCP.from_openapi(schema, httpx.AsyncClient())
+        elapsed_time = time.time() - start_time
+
+        # Should be very fast for medium schemas (well under 1 second)
+        assert elapsed_time < 1.0, (
+            f"Medium schema parsing took {elapsed_time:.3f}s, expected <1s"
+        )
+        assert mcp_server is not None
diff --git a/tests/server/providers/openapi/test_parameter_collisions.py b/tests/server/providers/openapi/test_parameter_collisions.py
new file mode 100644
index 0000000..104d663
--- /dev/null
+++ b/tests/server/providers/openapi/test_parameter_collisions.py
@@ -0,0 +1,225 @@
+"""Tests for parameter collision handling in OpenAPIProvider."""
+
+import httpx
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.providers.openapi import OpenAPIProvider
+
+
+def create_openapi_server(
+    openapi_spec: dict,
+    client,
+    name: str = "OpenAPI Server",
+) -> FastMCP:
+    """Helper to create a FastMCP server with OpenAPIProvider."""
+    provider = OpenAPIProvider(openapi_spec=openapi_spec, client=client)
+    mcp = FastMCP(name)
+    mcp.add_provider(provider)
+    return mcp
+
+
+class TestParameterCollisions:
+    """Test parameter name collisions between different locations (path, query, body)."""
+
+    @pytest.fixture
+    def collision_spec(self):
+        """OpenAPI spec with parameter name collisions."""
+        return {
+            "openapi": "3.0.0",
+            "info": {"title": "Collision Test API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com"}],
+            "paths": {
+                "/users/{id}": {
+                    "put": {
+                        "operationId": "update_user",
+                        "summary": "Update user with collision between path and body",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "integer"},
+                                "description": "User ID in path",
+                            }
+                        ],
+                        "requestBody": {
+                            "required": True,
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "properties": {
+                                            "id": {
+                                                "type": "integer",
+                                                "description": "User ID in body (different from path)",
+                                            },
+                                            "name": {
+                                                "type": "string",
+                                                "description": "User name",
+                                            },
+                                            "email": {
+                                                "type": "string",
+                                                "description": "User email",
+                                            },
+                                        },
+                                        "required": ["name", "email"],
+                                    }
+                                }
+                            },
+                        },
+                        "responses": {
+                            "200": {
+                                "description": "User updated",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "id": {"type": "integer"},
+                                                "name": {"type": "string"},
+                                                "email": {"type": "string"},
+                                            },
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                },
+                "/search": {
+                    "get": {
+                        "operationId": "search_with_collision",
+                        "summary": "Search with query and header collision",
+                        "parameters": [
+                            {
+                                "name": "query",
+                                "in": "query",
+                                "required": True,
+                                "schema": {"type": "string"},
+                                "description": "Search query parameter",
+                            },
+                            {
+                                "name": "query",
+                                "in": "header",
+                                "required": False,
+                                "schema": {"type": "string"},
+                                "description": "Search query in header",
+                            },
+                        ],
+                        "responses": {
+                            "200": {
+                                "description": "Search results",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "results": {
+                                                    "type": "array",
+                                                    "items": {"type": "object"},
+                                                }
+                                            },
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                },
+            },
+        }
+
+    async def test_path_body_collision_handling(self, collision_spec):
+        """Test that path and body parameters with same name are handled correctly."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=collision_spec, client=client, name="Collision Test Server"
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                # Find the update user tool
+                update_tool = next(tool for tool in tools if tool.name == "update_user")
+                assert update_tool is not None
+
+                # Check that both path and body 'id' parameters are included
+                params = update_tool.input_schema
+                properties = params["properties"]
+
+                # Should have both path ID and body ID (with potential suffixing)
+                # The implementation should handle this collision by suffixing one of them
+                assert "id" in properties  # One version of id
+
+                # Check for suffixed versions or verify both exist somehow
+                # The exact handling depends on implementation, but both should be accessible
+                param_names = list(properties.keys())
+                id_params = [name for name in param_names if "id" in name]
+                assert len(id_params) >= 1  # At least one id parameter
+
+                # Should also have other body parameters
+                assert "name" in properties
+                assert "email" in properties
+
+                # Required fields should include path parameter and required body fields
+                required = params.get("required", [])
+                assert "name" in required
+                assert "email" in required
+                # Path parameter should be required (may be suffixed)
+                id_required = any("id" in req for req in required)
+                assert id_required
+
+    async def test_query_header_collision_handling(self, collision_spec):
+        """Test that query and header parameters with same name are handled correctly."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=collision_spec, client=client, name="Collision Test Server"
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                # Find the search tool
+                search_tool = next(
+                    tool for tool in tools if tool.name == "search_with_collision"
+                )
+                assert search_tool is not None
+
+                # Check that both query and header 'query' parameters are handled
+                params = search_tool.input_schema
+                properties = params["properties"]
+
+                # Should handle the collision somehow (suffixing or other mechanism)
+                param_names = list(properties.keys())
+                query_params = [name for name in param_names if "query" in name]
+                assert len(query_params) >= 1  # At least one query parameter
+
+                # Required should include the required query parameter
+                required = params.get("required", [])
+                query_required = any("query" in req for req in required)
+                assert query_required
+
+    async def test_collision_resolution_maintains_functionality(self, collision_spec):
+        """Test that collision resolution doesn't break basic tool functionality."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            server = create_openapi_server(
+                openapi_spec=collision_spec, client=client, name="Collision Test Server"
+            )
+
+            async with Client(server) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                # Should successfully create tools despite collisions
+                assert len(tools) == 2
+
+                tool_names = {tool.name for tool in tools}
+                assert "update_user" in tool_names
+                assert "search_with_collision" in tool_names
+
+                # Tools should have valid schemas
+                for tool in tools:
+                    assert tool.input_schema is not None
+                    assert tool.input_schema["type"] == "object"
+                    assert "properties" in tool.input_schema
diff --git a/tests/server/providers/openapi/test_performance_comparison.py b/tests/server/providers/openapi/test_performance_comparison.py
new file mode 100644
index 0000000..66f55bd
--- /dev/null
+++ b/tests/server/providers/openapi/test_performance_comparison.py
@@ -0,0 +1,286 @@
+"""Performance tests for OpenAPIProvider implementation."""
+
+import gc
+import time
+
+import httpx
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.server.providers.openapi import OpenAPIProvider
+
+
+def create_openapi_server(
+    openapi_spec: dict,
+    client,
+    name: str = "OpenAPI Server",
+) -> FastMCP:
+    """Helper to create a FastMCP server with OpenAPIProvider."""
+    provider = OpenAPIProvider(openapi_spec=openapi_spec, client=client)
+    mcp = FastMCP(name)
+    mcp.add_provider(provider)
+    return mcp
+
+
+class TestPerformance:
+    """Test performance of OpenAPIProvider implementation."""
+
+    @pytest.fixture
+    def comprehensive_spec(self):
+        """Comprehensive OpenAPI spec for performance testing."""
+        return {
+            "openapi": "3.0.0",
+            "info": {"title": "Performance Test API", "version": "1.0.0"},
+            "paths": {
+                "/users": {
+                    "get": {
+                        "operationId": "list_users",
+                        "summary": "List users",
+                        "parameters": [
+                            {
+                                "name": "limit",
+                                "in": "query",
+                                "required": False,
+                                "schema": {"type": "integer", "default": 10},
+                            },
+                            {
+                                "name": "offset",
+                                "in": "query",
+                                "required": False,
+                                "schema": {"type": "integer", "default": 0},
+                            },
+                        ],
+                        "responses": {"200": {"description": "Users listed"}},
+                    },
+                    "post": {
+                        "operationId": "create_user",
+                        "summary": "Create user",
+                        "requestBody": {
+                            "required": True,
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "properties": {
+                                            "name": {"type": "string"},
+                                            "email": {"type": "string"},
+                                            "age": {"type": "integer"},
+                                        },
+                                        "required": ["name", "email"],
+                                    }
+                                }
+                            },
+                        },
+                        "responses": {"201": {"description": "User created"}},
+                    },
+                },
+                "/users/{id}": {
+                    "get": {
+                        "operationId": "get_user",
+                        "summary": "Get user",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "integer"},
+                            }
+                        ],
+                        "responses": {"200": {"description": "User found"}},
+                    },
+                    "put": {
+                        "operationId": "update_user",
+                        "summary": "Update user",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "integer"},
+                            }
+                        ],
+                        "requestBody": {
+                            "required": True,
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "properties": {
+                                            "name": {"type": "string"},
+                                            "email": {"type": "string"},
+                                            "age": {"type": "integer"},
+                                        },
+                                    }
+                                }
+                            },
+                        },
+                        "responses": {"200": {"description": "User updated"}},
+                    },
+                    "delete": {
+                        "operationId": "delete_user",
+                        "summary": "Delete user",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "integer"},
+                            }
+                        ],
+                        "responses": {"204": {"description": "User deleted"}},
+                    },
+                },
+                "/search": {
+                    "get": {
+                        "operationId": "search_users",
+                        "summary": "Search users",
+                        "parameters": [
+                            {
+                                "name": "q",
+                                "in": "query",
+                                "required": True,
+                                "schema": {"type": "string"},
+                            },
+                            {
+                                "name": "filters",
+                                "in": "query",
+                                "required": False,
+                                "style": "deepObject",
+                                "explode": True,
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "age_min": {"type": "integer"},
+                                        "age_max": {"type": "integer"},
+                                        "status": {
+                                            "type": "string",
+                                            "enum": ["active", "inactive"],
+                                        },
+                                    },
+                                },
+                            },
+                        ],
+                        "responses": {"200": {"description": "Search results"}},
+                    }
+                },
+            },
+        }
+
+    def test_provider_initialization_performance(self, comprehensive_spec):
+        """Test that provider initialization is fast (serverless requirement)."""
+        num_iterations = 5
+
+        # Measure provider initialization
+        times = []
+        for _ in range(num_iterations):
+            client = httpx.AsyncClient(base_url="https://api.example.com")
+            start_time = time.time()
+            provider = OpenAPIProvider(
+                openapi_spec=comprehensive_spec,
+                client=client,
+            )
+            # Ensure provider is fully initialized
+            assert provider is not None
+            end_time = time.time()
+            times.append(end_time - start_time)
+
+        avg_time = sum(times) / len(times)
+        max_acceptable_time = 0.2  # 200ms (Windows CI runners regularly clip 100ms)
+
+        print(f"Average initialization time: {avg_time:.4f}s")
+        print(f"Performance: {'✓' if avg_time < max_acceptable_time else '✗'}")
+
+        # Should initialize in under 200ms for serverless requirements
+        assert avg_time < max_acceptable_time, (
+            f"Provider should initialize in under 200ms, got {avg_time:.4f}s"
+        )
+
+    def test_server_initialization_performance(self, comprehensive_spec):
+        """Test that full server initialization is fast."""
+        num_iterations = 5
+
+        times = []
+        for _ in range(num_iterations):
+            client = httpx.AsyncClient(base_url="https://api.example.com")
+            start_time = time.time()
+            server = create_openapi_server(
+                openapi_spec=comprehensive_spec,
+                client=client,
+                name="Performance Test",
+            )
+            # Ensure server is fully initialized
+            assert server is not None
+            end_time = time.time()
+            times.append(end_time - start_time)
+
+        avg_time = sum(times) / len(times)
+        max_acceptable_time = 0.2  # 200ms (Windows CI runners regularly clip 100ms)
+
+        print(f"Average server initialization time: {avg_time:.4f}s")
+
+        assert avg_time < max_acceptable_time, (
+            f"Server should initialize in under 200ms, got {avg_time:.4f}s"
+        )
+
+    async def test_functionality_after_optimization(self, comprehensive_spec):
+        """Verify that performance optimization doesn't break functionality."""
+        client = httpx.AsyncClient(base_url="https://api.example.com")
+
+        server = create_openapi_server(
+            openapi_spec=comprehensive_spec,
+            client=client,
+            name="Test Server",
+        )
+
+        # Get tools from the server via public API
+        tools = await server.list_tools()
+
+        # Should have 6 operations in the spec
+        assert len(tools) == 6
+
+        # Expected operations
+        expected_operations = {
+            "list_users",
+            "create_user",
+            "get_user",
+            "update_user",
+            "delete_user",
+            "search_users",
+        }
+        assert {t.name for t in tools} == expected_operations
+
+    def test_memory_efficiency(self, comprehensive_spec):
+        """Test that implementation doesn't significantly increase memory usage."""
+
+        # Helper to count total tools across all providers
+        def count_provider_tools(server):
+            total = 0
+            for provider in server.providers:
+                if hasattr(provider, "_tools"):
+                    total += len(provider._tools)
+            return total
+
+        gc.collect()  # Clean up before baseline
+        baseline_refs = len(gc.get_objects())
+
+        servers = []
+        for i in range(10):
+            client = httpx.AsyncClient(base_url="https://api.example.com")
+            server = create_openapi_server(
+                openapi_spec=comprehensive_spec,
+                client=client,
+                name=f"Memory Test Server {i}",
+            )
+            servers.append(server)
+
+        # Servers should all be functional
+        assert len(servers) == 10
+        assert all(count_provider_tools(s) == 6 for s in servers)
+
+        # Memory usage shouldn't explode
+        gc.collect()
+        current_refs = len(gc.get_objects())
+        growth_ratio = current_refs / max(baseline_refs, 1)
+        assert growth_ratio < 3.0, (
+            f"Memory usage grew by {growth_ratio}x, which seems excessive"
+        )
diff --git a/tests/server/providers/openapi/test_server.py b/tests/server/providers/openapi/test_server.py
new file mode 100644
index 0000000..994e3b9
--- /dev/null
+++ b/tests/server/providers/openapi/test_server.py
@@ -0,0 +1,363 @@
+"""Unit tests for OpenAPIProvider."""
+
+import httpx
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.providers.openapi import OpenAPIProvider
+from fastmcp.server.providers.openapi.provider import DEFAULT_TIMEOUT
+
+
+class TestOpenAPIProviderServerVariables:
+    """Test that OpenAPIProvider resolves OpenAPI 3.x server variables."""
+
+    def test_server_variables_substituted_with_defaults(self):
+        spec = {
+            "openapi": "3.0.0",
+            "info": {"title": "Test API", "version": "1.0.0"},
+            "servers": [
+                {
+                    "url": "https://{region}.api.example.com/v1",
+                    "variables": {
+                        "region": {
+                            "default": "us",
+                            "enum": ["us", "eu", "apac"],
+                        }
+                    },
+                }
+            ],
+            "paths": {},
+        }
+        client = OpenAPIProvider._create_default_client(spec)
+        assert str(client.base_url) == "https://us.api.example.com/v1/"
+
+    def test_multiple_server_variables_substituted(self):
+        spec = {
+            "openapi": "3.0.0",
+            "info": {"title": "Test API", "version": "1.0.0"},
+            "servers": [
+                {
+                    "url": "{scheme}://{host}/v1",
+                    "variables": {
+                        "scheme": {"default": "https"},
+                        "host": {"default": "api.example.com"},
+                    },
+                }
+            ],
+            "paths": {},
+        }
+        client = OpenAPIProvider._create_default_client(spec)
+        assert str(client.base_url) == "https://api.example.com/v1/"
+
+    def test_static_server_url_unaffected(self):
+        spec = {
+            "openapi": "3.0.0",
+            "info": {"title": "Test API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com"}],
+            "paths": {},
+        }
+        client = OpenAPIProvider._create_default_client(spec)
+        assert str(client.base_url) == "https://api.example.com"
+
+
+class TestOpenAPIProviderBasicFunctionality:
+    """Test basic OpenAPIProvider functionality."""
+
+    @pytest.fixture
+    def simple_openapi_spec(self):
+        """Simple OpenAPI spec for testing."""
+        return {
+            "openapi": "3.0.0",
+            "info": {"title": "Test API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com"}],
+            "paths": {
+                "/users/{id}": {
+                    "get": {
+                        "operationId": "get_user",
+                        "summary": "Get user by ID",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "integer"},
+                            }
+                        ],
+                        "responses": {
+                            "200": {
+                                "description": "User retrieved successfully",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "id": {"type": "integer"},
+                                                "name": {"type": "string"},
+                                                "email": {"type": "string"},
+                                            },
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                },
+                "/users": {
+                    "post": {
+                        "operationId": "create_user",
+                        "summary": "Create a new user",
+                        "requestBody": {
+                            "required": True,
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "properties": {
+                                            "name": {"type": "string"},
+                                            "email": {"type": "string"},
+                                        },
+                                        "required": ["name", "email"],
+                                    }
+                                }
+                            },
+                        },
+                        "responses": {
+                            "201": {
+                                "description": "User created successfully",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "id": {"type": "integer"},
+                                                "name": {"type": "string"},
+                                                "email": {"type": "string"},
+                                            },
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                },
+            },
+        }
+
+    def test_provider_initialization(self, simple_openapi_spec):
+        """Test provider initialization with OpenAPI spec."""
+        client = httpx.AsyncClient(base_url="https://api.example.com")
+        provider = OpenAPIProvider(openapi_spec=simple_openapi_spec, client=client)
+
+        # Should have initialized RequestDirector successfully
+        assert hasattr(provider, "_director")
+        assert hasattr(provider, "_spec")
+
+    def test_server_with_provider(self, simple_openapi_spec):
+        """Test server initialization with OpenAPIProvider."""
+        client = httpx.AsyncClient(base_url="https://api.example.com")
+        provider = OpenAPIProvider(openapi_spec=simple_openapi_spec, client=client)
+
+        mcp = FastMCP("Test Server")
+        mcp.add_provider(provider)
+
+        assert mcp.name == "Test Server"
+
+    async def test_provider_creates_tools_from_spec(self, simple_openapi_spec):
+        """Test that provider creates tools from OpenAPI spec."""
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            provider = OpenAPIProvider(openapi_spec=simple_openapi_spec, client=client)
+
+            mcp = FastMCP("Test Server")
+            mcp.add_provider(provider)
+
+            async with Client(mcp) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                # Should have created tools for both operations
+                assert len(tools) == 2
+
+                tool_names = {tool.name for tool in tools}
+                assert "get_user" in tool_names
+                assert "create_user" in tool_names
+
+    async def test_provider_tool_execution(self, simple_openapi_spec):
+        """Test tool execution uses RequestDirector."""
+        mock_client = httpx.AsyncClient()
+        provider = OpenAPIProvider(openapi_spec=simple_openapi_spec, client=mock_client)
+
+        mcp = FastMCP("Test Server")
+        mcp.add_provider(provider)
+
+        async with Client(mcp) as mcp_client:
+            tools = await mcp_client.list_tools()
+
+            # Should have tools using RequestDirector
+            assert len(tools) == 2
+
+            get_user_tool = next(tool for tool in tools if tool.name == "get_user")
+            assert get_user_tool is not None
+            assert get_user_tool.description is not None
+
+    def test_provider_creates_default_client_from_spec(self, simple_openapi_spec):
+        """Test that omitting client creates one from the spec's servers URL."""
+        provider = OpenAPIProvider(openapi_spec=simple_openapi_spec)
+        assert str(provider._client.base_url).rstrip("/") == "https://api.example.com"
+        assert provider._client.timeout == httpx.Timeout(DEFAULT_TIMEOUT)
+
+    def test_provider_default_client_requires_servers(self):
+        """Test that omitting client without servers in spec raises."""
+        spec = {
+            "openapi": "3.0.0",
+            "info": {"title": "No Servers", "version": "1.0.0"},
+            "paths": {},
+        }
+        with pytest.raises(ValueError, match="No server URL"):
+            OpenAPIProvider(openapi_spec=spec)
+
+    def test_provider_with_empty_spec(self):
+        """Test provider with minimal OpenAPI spec."""
+        minimal_spec = {
+            "openapi": "3.0.0",
+            "info": {"title": "Empty API", "version": "1.0.0"},
+            "paths": {},
+        }
+
+        client = httpx.AsyncClient(base_url="https://api.example.com")
+        provider = OpenAPIProvider(openapi_spec=minimal_spec, client=client)
+
+        # Should handle empty paths gracefully
+        assert hasattr(provider, "_director")
+        assert hasattr(provider, "_spec")
+
+    async def test_clean_schema_output_no_unused_defs(self):
+        """Test that unused schema definitions are removed from tool schemas."""
+        spec_with_unused_defs = {
+            "openapi": "3.0.0",
+            "info": {"title": "Test API", "version": "1.0.0"},
+            "servers": [{"url": "https://api.example.com"}],
+            "paths": {
+                "/users": {
+                    "post": {
+                        "operationId": "create_user",
+                        "summary": "Create a new user",
+                        "requestBody": {
+                            "required": True,
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "properties": {
+                                            "name": {"type": "string", "title": "Name"},
+                                            "active": {
+                                                "type": "boolean",
+                                                "title": "Active",
+                                            },
+                                        },
+                                        "required": ["name", "active"],
+                                    }
+                                }
+                            },
+                        },
+                        "responses": {
+                            "200": {
+                                "description": "User created successfully",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "id": {
+                                                    "type": "integer",
+                                                    "title": "Id",
+                                                },
+                                                "name": {
+                                                    "type": "string",
+                                                    "title": "Name",
+                                                },
+                                                "active": {
+                                                    "type": "boolean",
+                                                    "title": "Active",
+                                                },
+                                            },
+                                            "required": ["id", "name", "active"],
+                                            "title": "User",
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                }
+            },
+            "components": {
+                "schemas": {
+                    "HTTPValidationError": {
+                        "properties": {
+                            "detail": {
+                                "items": {
+                                    "$ref": "#/components/schemas/ValidationError"
+                                },
+                                "title": "Detail",
+                                "type": "array",
+                            }
+                        },
+                        "title": "HTTPValidationError",
+                        "type": "object",
+                    },
+                    "ValidationError": {
+                        "properties": {
+                            "loc": {
+                                "items": {
+                                    "anyOf": [{"type": "string"}, {"type": "integer"}]
+                                },
+                                "title": "Location",
+                                "type": "array",
+                            },
+                            "msg": {"title": "Message", "type": "string"},
+                            "type": {"title": "Error Type", "type": "string"},
+                        },
+                        "required": ["loc", "msg", "type"],
+                        "title": "ValidationError",
+                        "type": "object",
+                    },
+                }
+            },
+        }
+
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            provider = OpenAPIProvider(
+                openapi_spec=spec_with_unused_defs, client=client
+            )
+            mcp = FastMCP("Test Server")
+            mcp.add_provider(provider)
+
+            async with Client(mcp) as mcp_client:
+                tools = await mcp_client.list_tools()
+
+                assert len(tools) == 1
+                tool = tools[0]
+
+                assert tool.name == "create_user"
+
+                expected_input_schema = {
+                    "type": "object",
+                    "properties": {
+                        "name": {"type": "string", "title": "Name"},
+                        "active": {"type": "boolean", "title": "Active"},
+                    },
+                    "required": ["name", "active"],
+                }
+                assert tool.input_schema == expected_input_schema
+
+                expected_output_schema = {
+                    "type": "object",
+                    "properties": {
+                        "id": {"type": "integer", "title": "Id"},
+                        "name": {"type": "string", "title": "Name"},
+                        "active": {"type": "boolean", "title": "Active"},
+                    },
+                    "required": ["id", "name", "active"],
+                    "title": "User",
+                }
+                assert tool.output_schema == expected_output_schema
diff --git a/tests/server/providers/proxy/__init__.py b/tests/server/providers/proxy/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/server/providers/proxy/test_proxy_client.py b/tests/server/providers/proxy/test_proxy_client.py
new file mode 100644
index 0000000..216d283
--- /dev/null
+++ b/tests/server/providers/proxy/test_proxy_client.py
@@ -0,0 +1,527 @@
+from dataclasses import dataclass
+
+import pytest
+from anyio import create_task_group
+from mcp_types import (
+    ElicitRequestFormParams,
+    LoggingLevel,
+    ModelHint,
+    ModelPreferences,
+    TextContent,
+)
+from pydantic import BaseModel, Field
+
+from fastmcp import Client, Context, FastMCP
+from fastmcp.client.elicitation import ElicitRequestParams, ElicitResult
+from fastmcp.client.logging import LogMessage
+from fastmcp.client.sampling import RequestContext, SamplingMessage, SamplingParams
+from fastmcp.exceptions import ToolError
+from fastmcp.server import create_proxy
+from fastmcp.server.elicitation import AcceptedElicitation
+from fastmcp.server.providers.proxy import ProxyClient, _create_client_factory
+
+
+@pytest.fixture
+def fastmcp_server():
+    mcp = FastMCP("TestServer")
+
+    @mcp.tool(tags={"echo"})
+    def echo(message: str) -> str:
+        return f"echo: {message}"
+
+    @mcp.tool
+    async def list_roots(context: Context) -> list[str]:
+        roots = await context.list_roots()
+        return [str(r.uri) for r in roots]
+
+    @mcp.tool
+    async def sampling(
+        context: Context,
+    ) -> str:
+        result = await context.sample(
+            "Hello, world!",
+            system_prompt="You love FastMCP",
+            temperature=0.5,
+            max_tokens=100,
+            model_preferences="gpt-4o",
+        )
+        return result.text or ""
+
+    @dataclass
+    class Person:
+        name: str
+
+    @mcp.tool
+    async def elicit(context: Context) -> str:
+        result = await context.elicit(
+            message="What is your name?",
+            response_type=Person,
+        )
+
+        if result.action == "accept":
+            assert isinstance(result, AcceptedElicitation)
+            assert isinstance(result.data, Person)
+            return f"Hello, {result.data.name}!"
+        else:
+            return "No name provided."
+
+    @mcp.tool
+    async def log(
+        message: str, level: LoggingLevel, logger: str, context: Context
+    ) -> None:
+        await context.log(message=message, level=level, logger_name=logger)
+
+    @mcp.tool
+    async def report_progress(context: Context) -> int:
+        for i in range(3):
+            await context.report_progress(
+                progress=i + 1,
+                total=3,
+                message=f"{(i + 1) / 3 * 100:.2f}% complete",
+            )
+        return 100
+
+    return mcp
+
+
+@pytest.fixture
+async def proxy_server(fastmcp_server: FastMCP):
+    """
+    A proxy server that forwards interactions with the proxy client to the given fastmcp server.
+    """
+    return create_proxy(ProxyClient(fastmcp_server))
+
+
+class TestProxyClient:
+    async def test_forward_tool_meta(self, proxy_server: FastMCP):
+        """
+        Test that the proxy client correctly forwards the `echo` tool meta.
+        """
+        async with Client(proxy_server) as client:
+            tools = await client.list_tools()
+            echo_tool = next(t for t in tools if t.name == "echo")
+            assert echo_tool.meta == {"fastmcp": {"tags": ["echo"]}}
+
+    async def test_forward_error_response(self, proxy_server: FastMCP):
+        """
+        Test that the proxy client correctly forwards an error response.
+        """
+        async with Client(proxy_server) as client:
+            with pytest.raises(ToolError, match="Elicitation not supported"):
+                await client.call_tool("elicit", {})
+
+    async def test_forward_list_roots_request(self, proxy_server: FastMCP):
+        """
+        Test that the proxy client correctly forwards the `list_roots` request.
+        """
+        roots_handler_called = False
+
+        async def roots_handler(ctx: RequestContext):
+            nonlocal roots_handler_called
+            roots_handler_called = True
+            return []
+
+        async with Client(proxy_server, roots=roots_handler) as client:
+            await client.call_tool("list_roots", {})
+
+        assert roots_handler_called
+
+    async def test_forward_list_roots_response(self, proxy_server: FastMCP):
+        """
+        Test that the proxy client correctly forwards the `list_roots` response.
+        """
+        async with Client(proxy_server, roots=["file://x/y/z"]) as client:
+            result = await client.call_tool("list_roots", {})
+            assert result.data == ["file://x/y/z"]
+
+    async def test_forward_sampling_request(self, proxy_server: FastMCP):
+        """
+        Test that the proxy client correctly forwards the `sampling` request.
+        """
+        sampling_handler_called = False
+
+        def sampling_handler(
+            messages: list[SamplingMessage],
+            params: SamplingParams,
+            ctx: RequestContext,
+        ) -> str:
+            nonlocal sampling_handler_called
+            sampling_handler_called = True
+            assert messages == [
+                SamplingMessage(
+                    role="user",
+                    content=TextContent(type="text", text="Hello, world!"),
+                )
+            ]
+            assert params.system_prompt == "You love FastMCP"
+            assert params.temperature == 0.5
+            assert params.max_tokens == 100
+            assert params.model_preferences == ModelPreferences(
+                hints=[ModelHint(name="gpt-4o")]
+            )
+            return ""
+
+        async with Client(proxy_server, sampling_handler=sampling_handler) as client:
+            await client.call_tool("sampling", {})
+
+        assert sampling_handler_called
+
+    async def test_forward_sampling_response(self, proxy_server: FastMCP):
+        """
+        Test that the proxy client correctly forwards the `sampling` response.
+        """
+        async with Client(
+            proxy_server, sampling_handler=lambda *args: "I love FastMCP"
+        ) as client:
+            result = await client.call_tool("sampling", {})
+            assert result.data == "I love FastMCP"
+
+    async def test_elicit_request(self, proxy_server: FastMCP):
+        """
+        Test that the proxy client correctly forwards the `elicit` request.
+        """
+        elicitation_handler_called = False
+
+        async def elicitation_handler(
+            message, response_type, params: ElicitRequestParams, ctx
+        ):
+            nonlocal elicitation_handler_called
+            elicitation_handler_called = True
+            assert message == "What is your name?"
+            assert "Person" in str(response_type)
+            assert isinstance(params, ElicitRequestFormParams)
+            assert params.requested_schema == {
+                "title": "Person",
+                "type": "object",
+                "properties": {"name": {"title": "Name", "type": "string"}},
+                "required": ["name"],
+            }
+            return ElicitResult(action="accept", content=response_type(name="Alice"))
+
+        async with Client(
+            proxy_server, elicitation_handler=elicitation_handler
+        ) as client:
+            await client.call_tool("elicit", {})
+
+        assert elicitation_handler_called
+
+    async def test_elicit_accept_response(self, proxy_server: FastMCP):
+        """
+        Test that the proxy client correctly forwards the `elicit` accept response.
+        """
+
+        async def elicitation_handler(
+            message, response_type, params: ElicitRequestParams, ctx
+        ):
+            return ElicitResult(action="accept", content=response_type(name="Alice"))
+
+        async with Client(
+            proxy_server,
+            elicitation_handler=elicitation_handler,
+        ) as client:
+            result = await client.call_tool("elicit", {})
+            assert result.data == "Hello, Alice!"
+
+    async def test_elicit_decline_response(self, proxy_server: FastMCP):
+        """
+        Test that the proxy client correctly forwards the `elicit` decline response.
+        """
+
+        async def elicitation_handler(
+            message, response_type, params: ElicitRequestParams, ctx
+        ):
+            return ElicitResult(action="decline")
+
+        async with Client(
+            proxy_server, elicitation_handler=elicitation_handler
+        ) as client:
+            result = await client.call_tool("elicit", {})
+            assert result.data == "No name provided."
+
+    async def test_log_request(self, proxy_server: FastMCP):
+        """
+        Test that the proxy client correctly forwards the `log` request.
+        """
+        log_handler_called = False
+
+        async def log_handler(message: LogMessage) -> None:
+            nonlocal log_handler_called
+            log_handler_called = True
+            assert message.data == "Hello, world!"
+            assert message.level == "info"
+            assert message.logger == "test"
+
+        async with Client(proxy_server, log_handler=log_handler) as client:
+            await client.call_tool(
+                "log", {"message": "Hello, world!", "level": "info", "logger": "test"}
+            )
+
+        assert log_handler_called
+
+    async def test_report_progress_request(self, proxy_server: FastMCP):
+        """
+        Test that the proxy client correctly forwards the `report_progress` request.
+        """
+
+        EXPECTED_PROGRESS_MESSAGES = [
+            dict(progress=1, total=3, message="33.33% complete"),
+            dict(progress=2, total=3, message="66.67% complete"),
+            dict(progress=3, total=3, message="100.00% complete"),
+        ]
+        PROGRESS_MESSAGES = []
+
+        async def progress_handler(
+            progress: float, total: float | None, message: str | None
+        ) -> None:
+            PROGRESS_MESSAGES.append(
+                dict(progress=progress, total=total, message=message)
+            )
+
+        async with Client(proxy_server, progress_handler=progress_handler) as client:
+            await client.call_tool("report_progress", {})
+
+        assert PROGRESS_MESSAGES == EXPECTED_PROGRESS_MESSAGES
+
+    async def test_concurrent_log_requests_no_mixing(self, proxy_server: FastMCP):
+        """Test that concurrent log requests don't mix handlers (fixes #1068)."""
+        results: dict[str, LogMessage] = {}
+
+        async def log_handler_a(message: LogMessage) -> None:
+            results["logger_a"] = message
+
+        async def log_handler_b(message: LogMessage) -> None:
+            results["logger_b"] = message
+
+        async with (
+            Client(proxy_server, log_handler=log_handler_a) as client_a,
+            Client(proxy_server, log_handler=log_handler_b) as client_b,
+        ):
+            async with create_task_group() as tg:
+                tg.start_soon(
+                    client_a.call_tool,
+                    "log",
+                    {"message": "Hello, world!", "level": "info", "logger": "a"},
+                )
+                tg.start_soon(
+                    client_b.call_tool,
+                    "log",
+                    {"message": "Hello, world!", "level": "info", "logger": "b"},
+                )
+
+        assert results["logger_a"].logger == "a"
+        assert results["logger_b"].logger == "b"
+
+    async def test_concurrent_elicitation_no_mixing(self, proxy_server: FastMCP):
+        """Test that concurrent elicitation requests don't mix handlers (fixes #1068)."""
+        results = {}
+
+        async def elicitation_handler_a(
+            message: str,
+            response_type: type,
+            params: ElicitRequestParams,
+            ctx: RequestContext,
+        ) -> ElicitResult:
+            return ElicitResult(action="accept", content=response_type(name="Alice"))
+
+        async def elicitation_handler_b(
+            message: str,
+            response_type: type,
+            params: ElicitRequestParams,
+            ctx: RequestContext,
+        ) -> ElicitResult:
+            return ElicitResult(action="accept", content=response_type(name="Bob"))
+
+        async def get_and_store(name, coro):
+            result = await coro
+            results[name] = result.data
+
+        async with (
+            Client(proxy_server, elicitation_handler=elicitation_handler_a) as client_a,
+            Client(proxy_server, elicitation_handler=elicitation_handler_b) as client_b,
+        ):
+            async with create_task_group() as tg:
+                tg.start_soon(
+                    get_and_store,
+                    "elicitation_a",
+                    client_a.call_tool("elicit", {}),
+                )
+                tg.start_soon(
+                    get_and_store,
+                    "elicitation_b",
+                    client_b.call_tool("elicit", {}),
+                )
+
+        assert results["elicitation_a"] == "Hello, Alice!"
+        assert results["elicitation_b"] == "Hello, Bob!"
+
+    async def test_elicit_with_default_values(self, fastmcp_server: FastMCP):
+        """
+        Test that the proxy client correctly handles elicitation with default values (fixes #1167).
+        """
+
+        @fastmcp_server.tool
+        async def elicit_with_defaults(context: Context) -> str:
+            class TestModel(BaseModel):
+                content: str = Field(description="Your reply content")
+                acknowledge: bool = Field(
+                    default=False, description="Send immediately or save as draft"
+                )
+
+            result = await context.elicit(
+                "Please provide input:", response_type=TestModel
+            )
+
+            if result.action == "accept":
+                assert isinstance(result, AcceptedElicitation)
+                assert isinstance(result.data, TestModel)
+                return f"Content: {result.data.content}, Acknowledge: {result.data.acknowledge}"
+            else:
+                return f"Elicitation {result.action}"
+
+        proxy_server = create_proxy(ProxyClient(fastmcp_server))
+
+        # Test that elicitation works correctly through the proxy
+        async def elicitation_handler(
+            message: str,
+            response_type: type,
+            params: ElicitRequestParams,
+            ctx: RequestContext,
+        ):
+            # Verify the schema is correct - acknowledge should have default=False, not be nullable
+            assert isinstance(params, ElicitRequestFormParams)
+            schema = params.requested_schema
+            assert schema["properties"]["acknowledge"]["type"] == "boolean"
+            assert schema["properties"]["acknowledge"]["default"] is False
+
+            return {"content": "Test content", "acknowledge": True}
+
+        async with Client(
+            proxy_server, elicitation_handler=elicitation_handler
+        ) as client:
+            result = await client.call_tool("elicit_with_defaults", {})
+            assert result.data == "Content: Test content, Acknowledge: True"
+
+    async def test_client_factory_creates_fresh_sessions(self, fastmcp_server: FastMCP):
+        """Test that the client factory pattern creates fresh sessions for each request."""
+        from fastmcp.server.providers.proxy import FastMCPProxy
+
+        # Create a disconnected client (should use fresh sessions per request)
+        base_client = Client(fastmcp_server)
+
+        # Test both create_proxy convenience function and direct client_factory usage
+        proxy_via_create_proxy = create_proxy(base_client)
+        proxy_via_factory = FastMCPProxy(client_factory=base_client.new)
+
+        # Verify the proxies are created successfully - this tests the client factory pattern
+        assert proxy_via_create_proxy is not None
+        assert proxy_via_factory is not None
+
+        # Verify they have the expected client factory behavior
+        assert hasattr(proxy_via_create_proxy, "_local_provider")
+        assert hasattr(proxy_via_factory, "_local_provider")
+
+    async def test_connected_proxy_client_uses_fresh_sessions(
+        self, fastmcp_server: FastMCP
+    ):
+        """Connected ProxyClient targets should create fresh sessions to avoid stale context."""
+        async with ProxyClient(fastmcp_server) as connected_client:
+            factory = _create_client_factory(connected_client)
+
+            client_a = factory()
+            client_b = factory()
+
+            assert isinstance(client_a, Client)
+            assert isinstance(client_b, Client)
+            assert client_a is not connected_client
+            assert client_b is not connected_client
+            assert client_a is not client_b
+            assert not client_a.is_connected()
+            assert not client_b.is_connected()
+
+
+@pytest.fixture
+def roots_backend_server():
+    """A backend server whose resource, template, and prompt all issue a
+    server-initiated `list_roots` request via the request context."""
+    mcp = FastMCP("RootsBackend")
+
+    @mcp.resource("data://roots")
+    async def roots_resource(context: Context) -> list[str]:
+        roots = await context.list_roots()
+        return [str(r.uri) for r in roots]
+
+    @mcp.resource("data://roots/{key}")
+    async def roots_template(key: str, context: Context) -> str:
+        roots = await context.list_roots()
+        return ", ".join(f"{key}:{r.uri}" for r in roots)
+
+    @mcp.prompt
+    async def roots_prompt(context: Context) -> str:
+        roots = await context.list_roots()
+        return ", ".join(str(r.uri) for r in roots)
+
+    return mcp
+
+
+@pytest.fixture
+async def roots_proxy_server(roots_backend_server: FastMCP):
+    return create_proxy(ProxyClient(roots_backend_server))
+
+
+class TestProxyServerInitiatedForwardingNonTool:
+    """Regression tests: a proxied resource/template/prompt whose backend issues
+    a server-initiated request (list_roots) must reach the proxy client's roots
+    handler instead of hanging until the test timeout.
+
+    Before the fix, only ProxyTool.run stashed the proxy's request context, so
+    resources/templates/prompts forwarded the request into the backend's own
+    context and deadlocked.
+    """
+
+    async def test_proxied_resource_forwards_list_roots(
+        self, roots_proxy_server: FastMCP
+    ):
+        roots_handler_called = False
+
+        async def roots_handler(ctx: RequestContext):
+            nonlocal roots_handler_called
+            roots_handler_called = True
+            return ["file://from/client"]
+
+        async with Client(roots_proxy_server, roots=roots_handler) as client:
+            result = await client.read_resource("data://roots")
+
+        assert roots_handler_called
+        assert result[0].text == '["file://from/client"]'
+
+    async def test_proxied_template_forwards_list_roots(
+        self, roots_proxy_server: FastMCP
+    ):
+        roots_handler_called = False
+
+        async def roots_handler(ctx: RequestContext):
+            nonlocal roots_handler_called
+            roots_handler_called = True
+            return ["file://from/client"]
+
+        async with Client(roots_proxy_server, roots=roots_handler) as client:
+            result = await client.read_resource("data://roots/abc")
+
+        assert roots_handler_called
+        assert result[0].text == "abc:file://from/client"
+
+    async def test_proxied_prompt_forwards_list_roots(
+        self, roots_proxy_server: FastMCP
+    ):
+        roots_handler_called = False
+
+        async def roots_handler(ctx: RequestContext):
+            nonlocal roots_handler_called
+            roots_handler_called = True
+            return ["file://from/client"]
+
+        async with Client(roots_proxy_server, roots=roots_handler) as client:
+            result = await client.get_prompt("roots_prompt")
+
+        assert roots_handler_called
+        assert result.messages[0].content.text == "file://from/client"
diff --git a/tests/server/providers/proxy/test_proxy_server.py b/tests/server/providers/proxy/test_proxy_server.py
new file mode 100644
index 0000000..762a09a
--- /dev/null
+++ b/tests/server/providers/proxy/test_proxy_server.py
@@ -0,0 +1,1124 @@
+import inspect
+import json
+import time
+from typing import Any, cast
+from unittest.mock import AsyncMock, patch
+
+import mcp_types
+import pytest
+from anyio import create_task_group
+from dirty_equals import Contains
+from mcp import MCPError
+from mcp_types import Icon, TextContent, TextResourceContents
+from pydantic import AnyUrl
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.transports import FastMCPTransport, StreamableHttpTransport
+from fastmcp.exceptions import ToolError
+from fastmcp.resources import ResourceContent, ResourceResult
+from fastmcp.server import create_proxy
+from fastmcp.server.providers.proxy import (
+    FastMCPProxy,
+    ProxyClient,
+    ProxyProvider,
+)
+from fastmcp.tools.base import ToolResult
+from fastmcp.tools.tool_transform import (
+    ToolTransformConfig,
+)
+from fastmcp.utilities.http import find_available_port
+from fastmcp.utilities.tests import run_server_async
+
+USERS = [
+    {"id": "1", "name": "Alice", "active": True},
+    {"id": "2", "name": "Bob", "active": True},
+    {"id": "3", "name": "Charlie", "active": False},
+]
+
+
+@pytest.fixture
+def fastmcp_server():
+    server = FastMCP("TestServer")
+
+    # --- Tools ---
+
+    @server.tool(
+        tags={"greet"},
+        title="Greet",
+        icons=[Icon(src="https://example.com/greet-icon.png")],
+    )
+    def greet(name: str) -> str:
+        """Greet someone by name."""
+        return f"Hello, {name}!"
+
+    @server.tool
+    def tool_without_description() -> str:
+        return "Hello?"
+
+    @server.tool
+    def add(a: int, b: int) -> int:
+        """Add two numbers together."""
+        return a + b
+
+    @server.tool
+    def error_tool():
+        """This tool always raises an error."""
+        raise ValueError("This is a test error")
+
+    # --- Resources ---
+
+    @server.resource(
+        uri="resource://wave",
+        tags={"wave"},
+        title="Wave",
+        icons=[Icon(src="https://example.com/wave-icon.png")],
+    )
+    def wave() -> str:
+        return "👋"
+
+    @server.resource(uri="data://users")
+    async def get_users() -> str:
+        import json
+
+        return json.dumps(USERS, separators=(",", ":"))
+
+    @server.resource(
+        uri="data://user/{user_id}",
+        tags={"users"},
+        title="User Template",
+        icons=[Icon(src="https://example.com/user-icon.png")],
+    )
+    async def get_user(user_id: str) -> str:
+        import json
+
+        user = next((user for user in USERS if user["id"] == user_id), None)
+        return json.dumps(user, separators=(",", ":")) if user else "null"
+
+    @server.resource(uri="data://multi")
+    def get_multi_content() -> ResourceResult:
+        """Resource that returns multiple content items."""
+        return ResourceResult(
+            contents=[
+                ResourceContent(content="First item", mime_type="text/plain"),
+                ResourceContent(
+                    content='{"key": "value"}', mime_type="application/json"
+                ),
+                ResourceContent(
+                    content="# Markdown\nContent", mime_type="text/markdown"
+                ),
+            ],
+            meta={"count": 3},
+        )
+
+    @server.resource(uri="data://multi/{id}")
+    def get_multi_template(id: str) -> ResourceResult:
+        """Resource template that returns multiple content items."""
+        return ResourceResult(
+            contents=[
+                ResourceContent(content=f"Item {id} - First", mime_type="text/plain"),
+                ResourceContent(
+                    content=f'{{"id": "{id}", "status": "active"}}',
+                    mime_type="application/json",
+                ),
+            ],
+            meta={"id": id},
+        )
+
+    # --- Prompts ---
+
+    @server.prompt(
+        tags={"welcome"},
+        title="Welcome",
+        icons=[Icon(src="https://example.com/welcome-icon.png")],
+    )
+    def welcome(name: str) -> str:
+        return f"Welcome to FastMCP, {name}!"
+
+    @server.prompt
+    def image_prompt():
+        """A prompt that returns an image."""
+        from fastmcp.prompts.base import Message, PromptResult
+
+        return PromptResult(
+            messages=[
+                Message("Here is an image:"),
+                Message(
+                    content=mcp_types.ImageContent(
+                        type="image",
+                        data="iVBORw0KGgoAAAANSUhEUg==",
+                        mime_type="image/png",
+                    ),
+                    role="user",
+                ),
+            ]
+        )
+
+    return server
+
+
+@pytest.fixture
+async def proxy_server(fastmcp_server):
+    """Fixture that creates a FastMCP proxy server."""
+    return create_proxy(ProxyClient(transport=FastMCPTransport(fastmcp_server)))
+
+
+async def test_create_proxy_with_client(fastmcp_server):
+    """Test create_proxy with a Client."""
+    client = ProxyClient(transport=FastMCPTransport(fastmcp_server))
+    server = create_proxy(client)
+
+    assert isinstance(server, FastMCPProxy)
+    assert isinstance(server, FastMCP)
+    assert server.name.startswith("FastMCPProxy-")
+
+
+async def test_create_proxy_with_server(fastmcp_server):
+    """create_proxy should accept a FastMCP instance."""
+    proxy = create_proxy(fastmcp_server)
+    async with Client(proxy) as client:
+        result = await client.call_tool("greet", {"name": "Test"})
+        assert result.data == "Hello, Test!"
+
+
+async def test_create_proxy_with_transport(fastmcp_server):
+    """create_proxy should accept a ClientTransport."""
+    proxy = create_proxy(FastMCPTransport(fastmcp_server))
+    async with Client(proxy) as client:
+        result = await client.call_tool("greet", {"name": "Test"})
+        assert result.data == "Hello, Test!"
+
+
+def test_create_proxy_with_url():
+    """create_proxy should accept a URL without connecting."""
+    proxy = create_proxy("http://example.com/mcp/")
+    assert isinstance(proxy, FastMCPProxy)
+    client = cast(Client, proxy.client_factory())
+    assert isinstance(client.transport, StreamableHttpTransport)
+    assert client.transport.url == "http://example.com/mcp/"
+
+
+async def test_proxy_with_async_client_factory():
+    """FastMCPProxy should accept an async client_factory."""
+
+    async def async_factory():
+        return Client("http://example.com/mcp/")
+
+    proxy = FastMCPProxy(client_factory=async_factory)
+    assert isinstance(proxy, FastMCPProxy)
+    assert inspect.iscoroutinefunction(proxy.client_factory)
+    client = proxy.client_factory()
+    if inspect.isawaitable(client):
+        client = await client
+    assert isinstance(client, Client)
+    assert isinstance(client.transport, StreamableHttpTransport)
+    assert client.transport.url == "http://example.com/mcp/"
+
+
+async def test_proxy_ping_forwards_to_remote_server(fastmcp_server):
+    proxy = create_proxy(fastmcp_server)
+
+    async with Client(proxy) as client:
+        assert await client.ping() is True
+
+
+async def test_proxy_ping_surfaces_wrong_remote_path():
+    remote = FastMCP("remote")
+    async with run_server_async(remote, transport="http") as url:
+        proxy = create_proxy(StreamableHttpTransport(url.removesuffix("/mcp")))
+
+        # SDK v2 surfaces a wrong remote path as an HTTP "Not Found" rather than
+        # the v1 "Session terminated" message.
+        with pytest.raises(MCPError, match="Not Found"):
+            async with Client(proxy):
+                pass
+
+
+async def test_proxy_initialize_forwards_remote_connection_error():
+    port = find_available_port()
+    proxy = create_proxy(
+        StreamableHttpTransport(f"http://127.0.0.1:{port}/mcp"),
+        provider_error_strategy="raise",
+    )
+
+    with pytest.raises(MCPError, match="Client failed to connect"):
+        async with Client(proxy):
+            pass
+
+
+async def test_proxy_list_tools_surfaces_remote_connection_error():
+    port = find_available_port()
+    proxy = create_proxy(
+        StreamableHttpTransport(f"http://127.0.0.1:{port}/mcp"),
+        provider_error_strategy="raise",
+    )
+
+    with pytest.raises(RuntimeError, match="Client failed to connect"):
+        await proxy.list_tools()
+
+
+async def test_proxy_list_tools_client_surfaces_remote_connection_error():
+    port = find_available_port()
+    proxy = create_proxy(
+        StreamableHttpTransport(f"http://127.0.0.1:{port}/mcp"),
+        provider_error_strategy="raise",
+    )
+
+    with pytest.raises(MCPError, match="Client failed to connect"):
+        async with Client(proxy) as client:
+            await client.list_tools()
+
+
+class TestTools:
+    async def test_get_tools(self, proxy_server):
+        tools = await proxy_server.list_tools()
+        assert any(t.name == "greet" for t in tools)
+        assert any(t.name == "add" for t in tools)
+        assert any(t.name == "error_tool" for t in tools)
+        assert any(t.name == "tool_without_description" for t in tools)
+
+    async def test_get_tools_meta(self, proxy_server):
+        tools = await proxy_server.list_tools()
+        greet_tool = next(t for t in tools if t.name == "greet")
+        assert greet_tool.title == "Greet"
+        assert greet_tool.meta == {"fastmcp": {"tags": ["greet"]}}
+        assert greet_tool.icons == [Icon(src="https://example.com/greet-icon.png")]
+
+    async def test_get_transformed_tools(self):
+        """Test that tool transformations are applied to proxied tools."""
+        from fastmcp.server.transforms import ToolTransform
+
+        # Create server with transformation
+        server = FastMCP("TestServer")
+
+        @server.tool
+        def add(a: int, b: int) -> int:
+            """Add two numbers together."""
+            return a + b
+
+        server.add_transform(
+            ToolTransform({"add": ToolTransformConfig(name="add_transformed")})
+        )
+
+        proxy = create_proxy(server)
+        tools = await proxy.list_tools()
+        assert any(t.name == "add_transformed" for t in tools)
+        assert not any(t.name == "add" for t in tools)
+
+    async def test_call_transformed_tools(self):
+        """Test calling a transformed tool through a proxy."""
+        from fastmcp.server.transforms import ToolTransform
+
+        # Create server with transformation
+        server = FastMCP("TestServer")
+
+        @server.tool
+        def add(a: int, b: int) -> int:
+            """Add two numbers together."""
+            return a + b
+
+        server.add_transform(
+            ToolTransform({"add": ToolTransformConfig(name="add_transformed")})
+        )
+
+        proxy = create_proxy(server)
+        async with Client(proxy) as client:
+            result = await client.call_tool("add_transformed", {"a": 1, "b": 2})
+        assert result.data == 3
+
+    async def test_tool_without_description(self, proxy_server):
+        tools = await proxy_server.list_tools()
+        tool = next(t for t in tools if t.name == "tool_without_description")
+        assert tool.description is None
+
+    async def test_list_tools_same_as_original(self, fastmcp_server, proxy_server):
+        async with Client(fastmcp_server) as original_client:
+            original = await original_client.list_tools()
+        async with Client(proxy_server) as proxy_client:
+            proxied = await proxy_client.list_tools()
+        assert proxied == original
+
+    async def test_call_tool_result_same_as_original(
+        self, fastmcp_server: FastMCP, proxy_server: FastMCPProxy
+    ):
+        async with Client(fastmcp_server) as original_client:
+            result = await original_client.call_tool("greet", {"name": "Alice"})
+        async with Client(proxy_server) as proxy_client:
+            proxy_result = await proxy_client.call_tool("greet", {"name": "Alice"})
+
+        assert result.content == proxy_result.content
+        assert result.data == proxy_result.data
+
+    async def test_call_tool_calls_tool(self, proxy_server):
+        async with Client(proxy_server) as client:
+            proxy_result = await client.call_tool("add", {"a": 1, "b": 2})
+        assert proxy_result.data == 3
+
+    async def test_error_tool_raises_error(self, proxy_server):
+        with pytest.raises(ToolError, match="This is a test error"):
+            async with Client(proxy_server) as client:
+                await client.call_tool("error_tool", {})
+
+    async def test_error_tool_with_image_content(self, proxy_server):
+        """Non-TextContent error responses should not crash with AttributeError."""
+        error_result = mcp_types.CallToolResult(
+            content=[
+                mcp_types.ImageContent(
+                    type="image", data="abc123", mime_type="image/png"
+                )
+            ],
+            is_error=True,
+        )
+        with patch.object(
+            Client, "call_tool_mcp", new_callable=AsyncMock, return_value=error_result
+        ):
+            with pytest.raises(ToolError):
+                async with Client(proxy_server) as client:
+                    await client.call_tool("error_tool", {})
+
+    async def test_error_tool_with_empty_content(self, proxy_server):
+        """Error responses with empty content should not crash."""
+        error_result = mcp_types.CallToolResult(
+            content=[],
+            is_error=True,
+        )
+        with patch.object(
+            Client, "call_tool_mcp", new_callable=AsyncMock, return_value=error_result
+        ):
+            with pytest.raises(ToolError):
+                async with Client(proxy_server) as client:
+                    await client.call_tool("error_tool", {})
+
+    async def test_error_tool_passthrough_preserves_content(self, proxy_server):
+        """Upstream error results pass through with content intact, not flattened."""
+        error_result = mcp_types.CallToolResult(
+            content=[
+                mcp_types.ImageContent(
+                    type="image", data="abc123", mime_type="image/png"
+                )
+            ],
+            structured_content={"detail": "boom"},
+            is_error=True,
+        )
+        with patch.object(
+            Client, "call_tool_mcp", new_callable=AsyncMock, return_value=error_result
+        ):
+            async with Client(proxy_server) as client:
+                result = await client.call_tool("error_tool", {}, raise_on_error=False)
+
+        assert result.is_error is True
+        assert isinstance(result.content[0], mcp_types.ImageContent)
+        assert result.content[0].data == "abc123"
+        assert result.structured_content == {"detail": "boom"}
+
+    async def test_call_tool_forwards_meta(self, fastmcp_server, proxy_server):
+        """Test that metadata from proxied tool results is properly forwarded."""
+
+        @fastmcp_server.tool
+        def tool_with_meta(value: str) -> ToolResult:
+            """A tool that returns metadata in its result."""
+            return ToolResult(
+                content=f"Result: {value}",
+                meta={"custom_key": "custom_value", "processed": True},
+            )
+
+        async with Client(proxy_server) as client:
+            result = await client.call_tool("tool_with_meta", {"value": "test"})
+
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "Result: test"
+        assert result.meta == {"custom_key": "custom_value", "processed": True}
+
+    async def test_proxy_can_overwrite_proxied_tool(self, proxy_server):
+        """
+        Test that a tool defined on the proxy can overwrite the proxied tool with the same name.
+        """
+
+        @proxy_server.tool
+        def greet(name: str, extra: str = "extra") -> str:
+            return f"Overwritten, {name}! {extra}"
+
+        async with Client(proxy_server) as client:
+            result = await client.call_tool("greet", {"name": "Marvin", "extra": "abc"})
+        assert result.data == "Overwritten, Marvin! abc"
+
+    async def test_proxy_can_list_overwritten_tool(self, proxy_server):
+        """
+        Test that a tool defined on the proxy is listed instead of the proxied tool
+        """
+
+        @proxy_server.tool
+        def greet(name: str, extra: str = "extra") -> str:
+            return f"Overwritten, {name}! {extra}"
+
+        async with Client(proxy_server) as client:
+            tools = await client.list_tools()
+            greet_tool = next(t for t in tools if t.name == "greet")
+            assert "extra" in greet_tool.input_schema["properties"]
+
+
+class TestResources:
+    async def test_get_resources(self, proxy_server):
+        resources = await proxy_server.list_resources()
+        assert [r.uri for r in resources] == Contains(
+            AnyUrl("data://users"),
+            AnyUrl("resource://wave"),
+        )
+        assert [r.name for r in resources] == Contains("get_users", "wave")
+
+    async def test_get_resources_meta(self, proxy_server):
+        resources = await proxy_server.list_resources()
+        wave_resource = next(r for r in resources if str(r.uri) == "resource://wave")
+        assert wave_resource.title == "Wave"
+        assert wave_resource.meta == {"fastmcp": {"tags": ["wave"]}}
+        assert wave_resource.icons == [Icon(src="https://example.com/wave-icon.png")]
+
+    async def test_list_resources_same_as_original(self, fastmcp_server, proxy_server):
+        async with Client(fastmcp_server) as original_client:
+            original = await original_client.list_resources()
+        async with Client(proxy_server) as proxy_client:
+            proxied = await proxy_client.list_resources()
+        assert proxied == original
+
+    async def test_read_resource(self, proxy_server: FastMCPProxy):
+        async with Client(proxy_server) as client:
+            result = await client.read_resource("resource://wave")
+        assert isinstance(result[0], TextResourceContents)
+        assert result[0].text == "👋"
+
+    async def test_read_resource_same_as_original(self, fastmcp_server, proxy_server):
+        async with Client(fastmcp_server) as client:
+            result = await client.read_resource("resource://wave")
+        async with Client(proxy_server) as client:
+            proxy_result = await client.read_resource("resource://wave")
+        assert proxy_result == result
+
+    async def test_read_json_resource(self, proxy_server: FastMCPProxy):
+        async with Client(proxy_server) as client:
+            result = await client.read_resource("data://users")
+        assert len(result) == 1
+        assert isinstance(result[0], TextResourceContents)
+        # The resource returns all users serialized as JSON
+        users = json.loads(result[0].text)
+        assert users == USERS
+
+    async def test_proxy_returns_all_resource_contents(
+        self, fastmcp_server, proxy_server
+    ):
+        """Test that proxy correctly returns all resource contents, not just the first one."""
+        # Read from original server
+        async with Client(fastmcp_server) as client:
+            original_result = await client.read_resource("data://multi")
+
+        # Read from proxy server
+        async with Client(proxy_server) as client:
+            proxy_result = await client.read_resource("data://multi")
+
+        # Both should return the same number of contents
+        assert len(original_result) == len(proxy_result)
+        assert len(original_result) == 3
+
+        # Verify all contents match
+        for i, (original, proxied) in enumerate(zip(original_result, proxy_result)):
+            assert isinstance(original, TextResourceContents)
+            assert isinstance(proxied, TextResourceContents)
+            assert original.text == proxied.text, f"Content {i} text mismatch"
+            assert original.mime_type == proxied.mime_type, (
+                f"Content {i} mimeType mismatch"
+            )
+            assert original.meta == proxied.meta, f"Content {i} meta mismatch"
+
+        # Verify the contents are what we expect
+        assert original_result[0].text == "First item"
+        assert original_result[0].mime_type == "text/plain"
+        assert original_result[1].text == '{"key": "value"}'
+        assert original_result[1].mime_type == "application/json"
+        assert original_result[2].text == "# Markdown\nContent"
+        assert original_result[2].mime_type == "text/markdown"
+
+    async def test_read_resource_returns_none_if_not_found(self, proxy_server):
+        with pytest.raises(
+            MCPError, match="Resource not found: 'resource://nonexistent'"
+        ):
+            async with Client(proxy_server) as client:
+                await client.read_resource("resource://nonexistent")
+
+    async def test_proxy_can_overwrite_proxied_resource(self, proxy_server):
+        """
+        Test that a resource defined on the proxy can overwrite the proxied resource with the same URI.
+        """
+
+        @proxy_server.resource(uri="resource://wave")
+        def overwritten_wave() -> str:
+            return "Overwritten wave! 🌊"
+
+        async with Client(proxy_server) as client:
+            result = await client.read_resource("resource://wave")
+        assert isinstance(result[0], TextResourceContents)
+        assert result[0].text == "Overwritten wave! 🌊"
+
+    async def test_proxy_can_list_overwritten_resource(self, proxy_server):
+        """
+        Test that a resource defined on the proxy is listed instead of the proxied resource
+        """
+
+        @proxy_server.resource(uri="resource://wave", name="overwritten_wave")
+        def overwritten_wave() -> str:
+            return "Overwritten wave! 🌊"
+
+        async with Client(proxy_server) as client:
+            resources = await client.list_resources()
+            wave_resource = next(
+                r for r in resources if str(r.uri) == "resource://wave"
+            )
+            assert wave_resource.name == "overwritten_wave"
+
+
+class TestResourceTemplates:
+    async def test_get_resource_templates(self, proxy_server):
+        templates = await proxy_server.list_resource_templates()
+        assert [t.name for t in templates] == Contains("get_user")
+
+    async def test_get_resource_templates_meta(self, proxy_server):
+        templates = await proxy_server.list_resource_templates()
+        get_user_template = next(
+            t for t in templates if t.uri_template == "data://user/{user_id}"
+        )
+        assert get_user_template.title == "User Template"
+        assert get_user_template.meta == {"fastmcp": {"tags": ["users"]}}
+        assert get_user_template.icons == [
+            Icon(src="https://example.com/user-icon.png")
+        ]
+
+    async def test_list_resource_templates_same_as_original(
+        self, fastmcp_server, proxy_server
+    ):
+        async with Client(fastmcp_server) as original_client:
+            result = await original_client.list_resource_templates()
+        async with Client(proxy_server) as proxy_client:
+            proxy_result = await proxy_client.list_resource_templates()
+        assert proxy_result == result
+
+    @pytest.mark.parametrize("id", [1, 2, 3])
+    async def test_read_resource_template(self, proxy_server: FastMCPProxy, id: int):
+        async with Client(proxy_server) as client:
+            result = await client.read_resource(f"data://user/{id}")
+        assert isinstance(result[0], TextResourceContents)
+        assert json.loads(result[0].text) == USERS[id - 1]
+
+    async def test_read_resource_template_same_as_original(
+        self, fastmcp_server, proxy_server
+    ):
+        async with Client(fastmcp_server) as client:
+            result = await client.read_resource("data://user/1")
+        async with Client(proxy_server) as client:
+            proxy_result = await client.read_resource("data://user/1")
+        assert proxy_result == result
+
+    async def test_proxy_template_returns_all_resource_contents(
+        self, fastmcp_server, proxy_server
+    ):
+        """Test that proxy template correctly returns all resource contents."""
+        # Read from original server
+        async with Client(fastmcp_server) as client:
+            original_result = await client.read_resource("data://multi/test123")
+
+        # Read from proxy server
+        async with Client(proxy_server) as client:
+            proxy_result = await client.read_resource("data://multi/test123")
+
+        # Both should return the same number of contents
+        assert len(original_result) == len(proxy_result)
+        assert len(original_result) == 2
+
+        # Verify all contents match
+        for i, (original, proxied) in enumerate(zip(original_result, proxy_result)):
+            assert isinstance(original, TextResourceContents)
+            assert isinstance(proxied, TextResourceContents)
+            assert original.text == proxied.text, f"Content {i} text mismatch"
+            assert original.mime_type == proxied.mime_type, (
+                f"Content {i} mimeType mismatch"
+            )
+
+        # Verify the contents are what we expect
+        assert original_result[0].text == "Item test123 - First"
+        assert original_result[0].mime_type == "text/plain"
+        assert original_result[1].text == '{"id": "test123", "status": "active"}'
+        assert original_result[1].mime_type == "application/json"
+
+    async def test_proxy_can_overwrite_proxied_resource_template(self, proxy_server):
+        """
+        Test that a resource template defined on the proxy can overwrite the proxied template with the same URI template.
+        """
+
+        @proxy_server.resource(uri="data://user/{user_id}", name="overwritten_get_user")
+        def overwritten_get_user(user_id: str) -> str:
+            return json.dumps(
+                {
+                    "id": user_id,
+                    "name": "Overwritten User",
+                    "active": True,
+                    "extra": "data",
+                }
+            )
+
+        async with Client(proxy_server) as client:
+            result = await client.read_resource("data://user/1")
+        assert isinstance(result[0], TextResourceContents)
+        user_data = json.loads(result[0].text)
+        assert user_data["name"] == "Overwritten User"
+        assert user_data["extra"] == "data"
+
+    async def test_proxy_can_list_overwritten_resource_template(self, proxy_server):
+        """
+        Test that a resource template defined on the proxy is listed instead of the proxied template
+        """
+
+        @proxy_server.resource(uri="data://user/{user_id}", name="overwritten_get_user")
+        def overwritten_get_user(user_id: str) -> dict[str, Any]:
+            return {"id": user_id, "name": "Overwritten User", "active": True}
+
+        async with Client(proxy_server) as client:
+            templates = await client.list_resource_templates()
+            user_template = next(
+                t for t in templates if t.uri_template == "data://user/{user_id}"
+            )
+            assert user_template.name == "overwritten_get_user"
+
+
+class TestResourceTemplateQueryParams:
+    """Resource templates with RFC 6570 {?param} query params work through proxy."""
+
+    async def test_query_param_forwarded(self):
+        remote = FastMCP("Remote")
+
+        @remote.resource("data://{id}{?format}")
+        def get_data(id: str, format: str = "json") -> str:
+            return f"id={id} format={format}"
+
+        proxy = create_proxy(Client(remote))
+        async with Client(proxy) as client:
+            result = await client.read_resource("data://123?format=xml")
+        assert isinstance(result[0], TextResourceContents)
+        assert result[0].text == "id=123 format=xml"
+
+    async def test_query_param_default_used_when_omitted(self):
+        remote = FastMCP("Remote")
+
+        @remote.resource("data://{id}{?format}")
+        def get_data(id: str, format: str = "json") -> str:
+            return f"id={id} format={format}"
+
+        proxy = create_proxy(Client(remote))
+        async with Client(proxy) as client:
+            result = await client.read_resource("data://123")
+        assert isinstance(result[0], TextResourceContents)
+        assert result[0].text == "id=123 format=json"
+
+    async def test_multiple_query_params_forwarded(self):
+        remote = FastMCP("Remote")
+
+        @remote.resource("data://{id}{?limit,offset}")
+        def get_data(id: str, limit: int = 10, offset: int = 0) -> str:
+            return f"id={id} limit={limit} offset={offset}"
+
+        proxy = create_proxy(Client(remote))
+        async with Client(proxy) as client:
+            result = await client.read_resource("data://abc?limit=5&offset=20")
+        assert isinstance(result[0], TextResourceContents)
+        assert result[0].text == "id=abc limit=5 offset=20"
+
+    async def test_encoded_path_param_preserved(self):
+        remote = FastMCP("Remote")
+
+        @remote.resource("data://{id}")
+        def get_data(id: str) -> str:
+            return f"id={id}"
+
+        proxy = create_proxy(Client(remote))
+        async with Client(proxy) as client:
+            result = await client.read_resource("data://a%2Fb")
+        assert isinstance(result[0], TextResourceContents)
+        assert result[0].text == "id=a/b"
+
+    async def test_hyphenated_query_param_forwarded(self):
+        remote = FastMCP("Remote")
+
+        @remote.resource("data://{id}{?api-version}")
+        def get_data(id: str, api_version: str = "v1") -> str:
+            return f"id={id} api_version={api_version}"
+
+        proxy = create_proxy(Client(remote))
+        async with Client(proxy) as client:
+            result = await client.read_resource("data://123?api-version=v2")
+        assert isinstance(result[0], TextResourceContents)
+        assert result[0].text == "id=123 api_version=v2"
+
+    def test_same_name_in_path_and_query_is_rejected(self):
+        remote = FastMCP("Remote")
+        with pytest.raises(ValueError, match="must be optional"):
+
+            @remote.resource("data://{id}{?id}")
+            def get_data(id: str) -> str:
+                return id
+
+    async def test_hyphenated_query_param_not_double_encoded(self):
+        remote = FastMCP("Remote")
+
+        @remote.resource("data://{id}{?api-version}")
+        def get_data(id: str, api_version: str = "v1") -> str:
+            return f"id={id} api_version={api_version}"
+
+        proxy = create_proxy(Client(remote))
+        async with Client(proxy) as client:
+            result = await client.read_resource("data://123?api-version=a%2Fb")
+        assert isinstance(result[0], TextResourceContents)
+        assert result[0].text == "id=123 api_version=a/b"
+
+
+class TestPrompts:
+    async def test_get_prompts_server_method(self, proxy_server: FastMCPProxy):
+        prompts = await proxy_server.list_prompts()
+        assert [p.name for p in prompts] == Contains("welcome")
+
+    async def test_get_prompts_meta(self, proxy_server):
+        prompts = await proxy_server.list_prompts()
+        welcome_prompt = next(p for p in prompts if p.name == "welcome")
+        assert welcome_prompt.title == "Welcome"
+        assert welcome_prompt.meta == {"fastmcp": {"tags": ["welcome"]}}
+        assert welcome_prompt.icons == [
+            Icon(src="https://example.com/welcome-icon.png")
+        ]
+
+    async def test_list_prompts_same_as_original(self, fastmcp_server, proxy_server):
+        async with Client(fastmcp_server) as client:
+            result = await client.list_prompts()
+        async with Client(proxy_server) as client:
+            proxy_result = await client.list_prompts()
+        assert proxy_result == result
+
+    async def test_render_prompt_same_as_original(
+        self, fastmcp_server: FastMCP, proxy_server: FastMCPProxy
+    ):
+        async with Client(fastmcp_server) as client:
+            result = await client.get_prompt("welcome", {"name": "Alice"})
+        async with Client(proxy_server) as client:
+            proxy_result = await client.get_prompt("welcome", {"name": "Alice"})
+        assert proxy_result == result
+
+    async def test_render_prompt_calls_prompt(self, proxy_server):
+        async with Client(proxy_server) as client:
+            result = await client.get_prompt("welcome", {"name": "Alice"})
+        assert result.messages[0].role == "user"
+        assert isinstance(result.messages[0].content, TextContent)
+        assert result.messages[0].content.text == "Welcome to FastMCP, Alice!"
+
+    async def test_proxy_can_overwrite_proxied_prompt(self, proxy_server):
+        """
+        Test that a prompt defined on the proxy can overwrite the proxied prompt with the same name.
+        """
+
+        @proxy_server.prompt
+        def welcome(name: str, extra: str = "friend") -> str:
+            return f"Overwritten welcome, {name}! You are my {extra}."
+
+        async with Client(proxy_server) as client:
+            result = await client.get_prompt(
+                "welcome", {"name": "Alice", "extra": "colleague"}
+            )
+        assert result.messages[0].role == "user"
+        assert isinstance(result.messages[0].content, TextContent)
+        assert (
+            result.messages[0].content.text
+            == "Overwritten welcome, Alice! You are my colleague."
+        )
+
+    async def test_proxy_can_list_overwritten_prompt(self, proxy_server):
+        """
+        Test that a prompt defined on the proxy is listed instead of the proxied prompt
+        """
+
+        @proxy_server.prompt
+        def welcome(name: str, extra: str = "friend") -> str:
+            return f"Overwritten welcome, {name}! You are my {extra}."
+
+        async with Client(proxy_server) as client:
+            prompts = await client.list_prompts()
+            welcome_prompt = next(p for p in prompts if p.name == "welcome")
+            # Check that the overwritten prompt has the additional 'extra' parameter
+            param_names = [arg.name for arg in welcome_prompt.arguments or []]
+            assert "extra" in param_names
+
+    async def test_proxy_prompt_preserves_image_content(
+        self, fastmcp_server: FastMCP, proxy_server: FastMCPProxy
+    ):
+        """Test that ProxyPrompt preserves ImageContent without lossy conversion."""
+        async with Client(fastmcp_server) as client:
+            result = await client.get_prompt("image_prompt")
+        async with Client(proxy_server) as client:
+            proxy_result = await client.get_prompt("image_prompt")
+
+        # The proxy result should match the original exactly
+        assert proxy_result == result
+        # Verify the image content is preserved as ImageContent, not JSON text
+        assert isinstance(proxy_result.messages[1].content, mcp_types.ImageContent)
+        assert proxy_result.messages[1].content.data == "iVBORw0KGgoAAAANSUhEUg=="
+        assert proxy_result.messages[1].content.mime_type == "image/png"
+
+
+async def test_proxy_handles_multiple_concurrent_tasks_correctly(
+    proxy_server: FastMCPProxy,
+):
+    results = {}
+
+    async def get_and_store(name, coro):
+        results[name] = await coro()
+
+    async with create_task_group() as tg:
+        tg.start_soon(get_and_store, "prompts", proxy_server.list_prompts)
+        tg.start_soon(get_and_store, "resources", proxy_server.list_resources)
+        tg.start_soon(get_and_store, "tools", proxy_server.list_tools)
+
+    assert list(results) == Contains("resources", "prompts", "tools")
+    assert [p.name for p in results["prompts"]] == Contains("welcome")
+    assert [r.uri for r in results["resources"]] == Contains(
+        AnyUrl("data://users"),
+        AnyUrl("resource://wave"),
+    )
+    assert [r.name for r in results["resources"]] == Contains("get_users", "wave")
+    assert [t.name for t in results["tools"]] == Contains(
+        "greet", "add", "error_tool", "tool_without_description"
+    )
+
+
+class TestProxyComponentEnableDisable:
+    """Test that enable/disable on proxy components guides users to server-level methods."""
+
+    async def test_proxy_tool_enable_raises_not_implemented(self, proxy_server):
+        """Test that enable() on proxy tools raises NotImplementedError."""
+        tools = await proxy_server.list_tools()
+        tool = next(t for t in tools if t.name == "greet")
+
+        with pytest.raises(NotImplementedError, match="server.enable"):
+            tool.enable()
+
+    async def test_proxy_tool_disable_raises_not_implemented(self, proxy_server):
+        """Test that disable() on proxy tools raises NotImplementedError."""
+        tools = await proxy_server.list_tools()
+        tool = next(t for t in tools if t.name == "greet")
+
+        with pytest.raises(NotImplementedError, match="server.disable"):
+            tool.disable()
+
+    async def test_proxy_resource_enable_raises_not_implemented(self, proxy_server):
+        """Test that enable() on proxy resources raises NotImplementedError."""
+        resources = await proxy_server.list_resources()
+        resource = next(r for r in resources if str(r.uri) == "resource://wave")
+
+        with pytest.raises(NotImplementedError, match="server.enable"):
+            resource.enable()
+
+    async def test_proxy_resource_disable_raises_not_implemented(self, proxy_server):
+        """Test that disable() on proxy resources raises NotImplementedError."""
+        resources = await proxy_server.list_resources()
+        resource = next(r for r in resources if str(r.uri) == "resource://wave")
+
+        with pytest.raises(NotImplementedError, match="server.disable"):
+            resource.disable()
+
+    async def test_proxy_prompt_enable_raises_not_implemented(self, proxy_server):
+        """Test that enable() on proxy prompts raises NotImplementedError."""
+        prompts = await proxy_server.list_prompts()
+        prompt = next(p for p in prompts if p.name == "welcome")
+
+        with pytest.raises(NotImplementedError, match="server.enable"):
+            prompt.enable()
+
+    async def test_proxy_prompt_disable_raises_not_implemented(self, proxy_server):
+        """Test that disable() on proxy prompts raises NotImplementedError."""
+        prompts = await proxy_server.list_prompts()
+        prompt = next(p for p in prompts if p.name == "welcome")
+
+        with pytest.raises(NotImplementedError, match="server.disable"):
+            prompt.disable()
+
+
+class TestProxyProviderCache:
+    """Tests for the ProxyProvider component list caching."""
+
+    async def test_get_tool_uses_cached_list(self, fastmcp_server):
+        """Calling call_tool should resolve from cache after an initial list."""
+        provider = ProxyProvider(
+            lambda: ProxyClient(FastMCPTransport(fastmcp_server)),
+        )
+        # Warm the cache via list
+        tools = await provider.list_tools()
+        assert any(t.name == "greet" for t in tools)
+
+        # _get_tool should resolve from cache without calling _list_tools again
+        with patch.object(
+            provider, "_get_client", new_callable=AsyncMock
+        ) as mock_client:
+            tool = await provider._get_tool("greet")
+            assert tool is not None
+            assert tool.name == "greet"
+            mock_client.assert_not_called()
+
+    async def test_get_tool_fetches_on_cold_cache(self, fastmcp_server):
+        """First _get_tool with no prior list should populate the cache."""
+        provider = ProxyProvider(
+            lambda: ProxyClient(FastMCPTransport(fastmcp_server)),
+        )
+        assert provider._tools_cache is None
+        tool = await provider._get_tool("greet")
+        assert tool is not None
+        assert provider._tools_cache is not None
+
+    async def test_cache_expires_after_ttl(self, fastmcp_server):
+        """After TTL expires, _get_tool should re-fetch from the backend."""
+        provider = ProxyProvider(
+            lambda: ProxyClient(FastMCPTransport(fastmcp_server)),
+            cache_ttl=0.0,
+        )
+        # Warm the cache
+        await provider._list_tools()
+        # With ttl=0 the cache is immediately stale, so _get_tool must re-fetch
+        assert provider._tools_cache is not None
+        original_ts = provider._tools_cache.timestamp
+
+        time.sleep(0.05)
+
+        await provider._get_tool("greet")
+        assert provider._tools_cache.timestamp > original_ts
+
+    async def test_list_tools_refreshes_cache(self, fastmcp_server):
+        """Explicit list_tools always refreshes the cache timestamp."""
+        provider = ProxyProvider(
+            lambda: ProxyClient(FastMCPTransport(fastmcp_server)),
+        )
+        await provider._list_tools()
+        first_ts = provider._tools_cache.timestamp  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+
+        # Tiny sleep so monotonic clock advances
+        time.sleep(0.05)
+
+        await provider._list_tools()
+        assert provider._tools_cache.timestamp > first_ts  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+
+    async def test_cache_ttl_zero_disables_caching(self, fastmcp_server):
+        """With cache_ttl=0, every _get_tool call should re-fetch."""
+        provider = ProxyProvider(
+            lambda: ProxyClient(FastMCPTransport(fastmcp_server)),
+            cache_ttl=0.0,
+        )
+        # Each _get_tool call should trigger a fresh _list_tools
+        call_count = 0
+        original_list = provider._list_tools
+
+        async def counting_list():
+            nonlocal call_count
+            call_count += 1
+            return await original_list()
+
+        with patch.object(provider, "_list_tools", side_effect=counting_list):
+            await provider._get_tool("greet")
+            await provider._get_tool("add")
+        assert call_count == 2
+
+    async def test_get_resource_uses_cache(self, fastmcp_server):
+        """Resource lookups should also use the cache."""
+        provider = ProxyProvider(
+            lambda: ProxyClient(FastMCPTransport(fastmcp_server)),
+        )
+        await provider._list_resources()
+        with patch.object(
+            provider, "_get_client", new_callable=AsyncMock
+        ) as mock_client:
+            # Even if no resources match, the cache is used (no backend call)
+            await provider._get_resource("config://app")
+            mock_client.assert_not_called()
+
+    async def test_call_tool_through_server_uses_cache(self, fastmcp_server):
+        """End-to-end: calling a tool on a proxy server should only connect
+        for the actual tool execution, not for tool resolution."""
+        proxy = create_proxy(fastmcp_server)
+        # Warm the cache by listing
+        await proxy.list_tools()
+
+        # Now call a tool — the provider's _list_tools should NOT be called
+        # because the cache is warm. The connection happens only in ProxyTool.run.
+        proxy_provider = next(
+            p for p in proxy.providers if isinstance(p, ProxyProvider)
+        )
+        with patch.object(
+            proxy_provider, "_list_tools", wraps=proxy_provider._list_tools
+        ) as mock_list:
+            result = await proxy.call_tool("greet", {"name": "Alice"})
+            mock_list.assert_not_called()
+        assert result.content[0].text == "Hello, Alice!"  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+
+
+class TestProxySpanAttributes:
+    """Regression tests for span attributes on un-renamed proxy components.
+
+    A proxy component's private ``_backend_*`` field is only populated when
+    the component is renamed via ``model_copy``. For un-renamed components it
+    stays ``None``, so ``get_span_attributes()`` would emit ``None`` for the
+    ``fastmcp.proxy.backend_*`` keys — which OpenTelemetry rejects with
+    ``Invalid type NoneType for attribute ... value`` and drops, producing
+    log spam on every proxied call.
+    """
+
+    async def test_proxy_tool_span_attributes_fall_back_to_name(self, proxy_server):
+        proxy_provider = next(
+            p for p in proxy_server.providers if isinstance(p, ProxyProvider)
+        )
+        tools = await proxy_provider._list_tools()
+        assert tools, "expected the fixture to expose at least one tool"
+        for tool in tools:
+            attrs = tool.get_span_attributes()
+            assert attrs["fastmcp.proxy.backend_name"] == tool.name
+            assert all(v is not None for v in attrs.values()), (
+                f"OpenTelemetry rejects None attribute values; got {attrs!r}"
+            )
+
+    async def test_proxy_resource_span_attributes_fall_back_to_uri(self, proxy_server):
+        proxy_provider = next(
+            p for p in proxy_server.providers if isinstance(p, ProxyProvider)
+        )
+        resources = await proxy_provider._list_resources()
+        assert resources, "expected the fixture to expose at least one resource"
+        for resource in resources:
+            attrs = resource.get_span_attributes()
+            assert attrs["fastmcp.proxy.backend_uri"] == str(resource.uri)
+            assert all(v is not None for v in attrs.values()), (
+                f"OpenTelemetry rejects None attribute values; got {attrs!r}"
+            )
+
+    async def test_proxy_template_span_attributes_fall_back_to_uri_template(
+        self, proxy_server
+    ):
+        proxy_provider = next(
+            p for p in proxy_server.providers if isinstance(p, ProxyProvider)
+        )
+        templates = await proxy_provider._list_resource_templates()
+        assert templates, "expected the fixture to expose at least one template"
+        for template in templates:
+            attrs = template.get_span_attributes()
+            assert attrs["fastmcp.proxy.backend_uri_template"] == template.uri_template
+            assert all(v is not None for v in attrs.values()), (
+                f"OpenTelemetry rejects None attribute values; got {attrs!r}"
+            )
+
+    async def test_proxy_prompt_span_attributes_fall_back_to_name(self, proxy_server):
+        proxy_provider = next(
+            p for p in proxy_server.providers if isinstance(p, ProxyProvider)
+        )
+        prompts = await proxy_provider._list_prompts()
+        assert prompts, "expected the fixture to expose at least one prompt"
+        for prompt in prompts:
+            attrs = prompt.get_span_attributes()
+            assert attrs["fastmcp.proxy.backend_name"] == prompt.name
+            assert all(v is not None for v in attrs.values()), (
+                f"OpenTelemetry rejects None attribute values; got {attrs!r}"
+            )
diff --git a/tests/server/providers/proxy/test_stateful_proxy_client.py b/tests/server/providers/proxy/test_stateful_proxy_client.py
new file mode 100644
index 0000000..3ebb9d5
--- /dev/null
+++ b/tests/server/providers/proxy/test_stateful_proxy_client.py
@@ -0,0 +1,285 @@
+import asyncio
+import weakref
+from dataclasses import dataclass
+from unittest.mock import MagicMock
+
+import pytest
+from anyio import create_task_group
+from mcp_types import LoggingLevel
+
+from fastmcp import Client, Context, FastMCP
+from fastmcp.client.elicitation import ElicitResult
+from fastmcp.client.logging import LogMessage
+from fastmcp.client.transports import FastMCPTransport
+from fastmcp.exceptions import ToolError
+from fastmcp.server.context import _current_context
+from fastmcp.server.dependencies import fastmcp_request_ctx, get_server
+from fastmcp.server.elicitation import AcceptedElicitation
+from fastmcp.server.providers.proxy import (
+    FastMCPProxy,
+    StatefulProxyClient,
+    _restore_request_context,
+)
+from fastmcp.utilities.tests import find_available_port, run_server_async
+
+
+@pytest.fixture
+def fastmcp_server():
+    mcp = FastMCP("TestServer")
+
+    states: dict[str, int] = {}
+
+    @mcp.tool
+    async def log(
+        message: str, level: LoggingLevel, logger: str, context: Context
+    ) -> None:
+        await context.log(message=message, level=level, logger_name=logger)
+
+    @mcp.tool
+    async def stateful_put(value: int, context: Context) -> None:
+        """put a value associated with the server session"""
+        # SDK v2 constructs a ServerSession per request, so `id(context.session)`
+        # is not a stable per-connection key. Use the connection-scoped
+        # `session_id` to share state across calls on the same client session.
+        key = context.session_id
+        states[key] = value
+
+    @mcp.tool
+    async def stateful_get(context: Context) -> int:
+        """get the value associated with the server session"""
+        key = context.session_id
+        try:
+            return states[key]
+        except KeyError:
+            raise ToolError("Value not found")
+
+    return mcp
+
+
+@pytest.fixture
+async def stateful_proxy_server(fastmcp_server: FastMCP):
+    client = StatefulProxyClient(transport=FastMCPTransport(fastmcp_server))
+    return FastMCPProxy(client_factory=client.new_stateful)
+
+
+@pytest.fixture
+async def stateless_server(stateful_proxy_server: FastMCP):
+    port = find_available_port()
+    url = f"http://127.0.0.1:{port}/mcp/"
+
+    task = asyncio.create_task(
+        stateful_proxy_server.run_http_async(
+            host="127.0.0.1", port=port, stateless_http=True
+        )
+    )
+    await stateful_proxy_server._started.wait()
+    yield url
+    task.cancel()
+    try:
+        await task
+    except asyncio.CancelledError:
+        pass
+
+
+class TestStatefulProxyClient:
+    async def test_concurrent_log_requests_no_mixing(
+        self, stateful_proxy_server: FastMCP
+    ):
+        """Test that concurrent log requests don't mix handlers (fixes #1068)."""
+        results: dict[str, LogMessage] = {}
+
+        async def log_handler_a(message: LogMessage) -> None:
+            results["logger_a"] = message
+
+        async def log_handler_b(message: LogMessage) -> None:
+            results["logger_b"] = message
+
+        async with (
+            Client(stateful_proxy_server, log_handler=log_handler_a) as client_a,
+            Client(stateful_proxy_server, log_handler=log_handler_b) as client_b,
+        ):
+            async with create_task_group() as tg:
+                tg.start_soon(
+                    client_a.call_tool,
+                    "log",
+                    {"message": "Hello, world!", "level": "info", "logger": "a"},
+                )
+                tg.start_soon(
+                    client_b.call_tool,
+                    "log",
+                    {"message": "Hello, world!", "level": "info", "logger": "b"},
+                )
+
+        assert results["logger_a"].logger == "a"
+        assert results["logger_b"].logger == "b"
+
+    async def test_stateful_proxy(self, stateful_proxy_server: FastMCP):
+        """Test that the state shared across multiple calls for the same client (fixes #959)."""
+        async with Client(stateful_proxy_server) as client:
+            with pytest.raises(ToolError, match="Value not found"):
+                await client.call_tool("stateful_get", {})
+
+            await client.call_tool("stateful_put", {"value": 1})
+            result = await client.call_tool("stateful_get", {})
+            assert result.data == 1
+
+    async def test_stateless_proxy(self, stateless_server: str):
+        """Test that the state will not be shared across different calls,
+        even if they are from the same client."""
+        async with Client(stateless_server) as client:
+            await client.call_tool("stateful_put", {"value": 1})
+
+            with pytest.raises(ToolError, match="Value not found"):
+                await client.call_tool("stateful_get", {})
+
+    async def test_multi_proxies_no_mixing(self):
+        """Test that the stateful proxy client won't be mixed in multi-proxies sessions."""
+        mcp_a, mcp_b = FastMCP(), FastMCP()
+
+        @mcp_a.tool
+        def tool_a() -> str:
+            return "a"
+
+        @mcp_b.tool
+        def tool_b() -> str:
+            return "b"
+
+        proxy_mcp_a = FastMCPProxy(
+            client_factory=StatefulProxyClient(mcp_a).new_stateful
+        )
+        proxy_mcp_b = FastMCPProxy(
+            client_factory=StatefulProxyClient(mcp_b).new_stateful
+        )
+        multi_proxy_mcp = FastMCP()
+        multi_proxy_mcp.mount(proxy_mcp_a, namespace="a")
+        multi_proxy_mcp.mount(proxy_mcp_b, namespace="b")
+
+        async with Client(multi_proxy_mcp) as client:
+            result_a = await client.call_tool("a_tool_a", {})
+            result_b = await client.call_tool("b_tool_b", {})
+            assert result_a.data == "a"
+            assert result_b.data == "b"
+
+    @pytest.mark.timeout(10)
+    async def test_stateful_proxy_elicitation_over_http(self):
+        """Elicitation through a stateful proxy over HTTP must not hang.
+
+        When StatefulProxyClient reuses a session, the receive-loop task
+        inherits a stale request_ctx ContextVar from the first request.
+        The streamable-HTTP transport uses related_request_id to route
+        server-initiated messages (like elicitation) back to the correct
+        HTTP response stream.  A stale request_id routes to a closed
+        stream, causing the elicitation to hang forever.
+
+        This test runs the proxy over HTTP (not in-process) so the
+        transport's related_request_id routing is exercised.
+        """
+
+        @dataclass
+        class Person:
+            name: str
+
+        backend = FastMCP("backend")
+
+        @backend.tool
+        async def ask_name(ctx: Context) -> str:
+            result = await ctx.elicit("What is your name?", response_type=Person)
+            if isinstance(result, AcceptedElicitation):
+                assert isinstance(result.data, Person)
+                return f"Hello, {result.data.name}!"
+            return "declined"
+
+        stateful_client = StatefulProxyClient(backend)
+        proxy = FastMCPProxy(
+            client_factory=stateful_client.new_stateful,
+            name="proxy",
+        )
+
+        async def elicitation_handler(message, response_type, params, ctx):
+            return ElicitResult(action="accept", content=response_type(name="Alice"))
+
+        # Run the proxy over HTTP so the transport uses
+        # related_request_id routing for server-initiated messages.
+        async with run_server_async(proxy) as proxy_url:
+            async with Client(
+                proxy_url, elicitation_handler=elicitation_handler
+            ) as client:
+                result1 = await client.call_tool("ask_name", {})
+                assert result1.data == "Hello, Alice!"
+                # Second call reuses the stateful session — this is the
+                # one that would hang without the fix.
+                result2 = await client.call_tool("ask_name", {})
+                assert result2.data == "Hello, Alice!"
+
+
+class TestRestoreRequestContextCurrentServer:
+    """Regression tests for `_restore_request_context` (refs #4054, Bug 4).
+
+    The receive-loop repair must also restore `_current_server`, so handlers
+    that resolve the server via dependency injection (e.g. `get_server()`)
+    work. It must do so set-only — without opening a `Context` context-manager
+    scope — since this patches a long-lived task's ContextVars in place.
+    """
+
+    async def _run_in_child_context(self, fn):
+        # Run in a child task so contextvar writes are isolated from the test
+        # task and `fastmcp_request_ctx` is genuinely unset (defaults to None).
+        return await asyncio.create_task(fn())
+
+    async def test_lookup_error_branch_restores_current_server(self):
+        fastmcp = FastMCP("restore-test")
+        rc = MagicMock()
+        rc.session = MagicMock()
+        rc.request_id = "req-1"
+        rc_ref: list = [(rc, weakref.ref(fastmcp))]
+
+        async def body():
+            assert fastmcp_request_ctx.get() is None
+            _restore_request_context(rc_ref)
+
+            # The actual Bug 4 fix: get_server() now resolves.
+            assert get_server() is fastmcp
+            assert fastmcp_request_ctx.get() is rc
+
+            ctx = _current_context.get()
+            assert ctx is not None
+            assert ctx.fastmcp is fastmcp
+            # Set-only: no context-manager scope was opened, so __aenter__'s
+            # token bookkeeping never ran.
+            assert ctx._tokens == []
+            assert not hasattr(ctx, "_shared_context")
+
+        await self._run_in_child_context(body)
+
+    async def test_stale_override_branch_restores_current_server(self):
+        fastmcp = FastMCP("restore-test")
+        session = MagicMock()
+
+        stale_rc = MagicMock()
+        stale_rc.session = session
+        stale_rc.request_id = "old"
+
+        fresh_rc = MagicMock()
+        fresh_rc.session = session
+        fresh_rc.request_id = "new"
+
+        rc_ref: list = [(fresh_rc, weakref.ref(fastmcp))]
+
+        async def body():
+            fastmcp_request_ctx.set(stale_rc)
+            _restore_request_context(rc_ref)
+
+            assert fastmcp_request_ctx.get() is fresh_rc
+            assert get_server() is fastmcp
+
+        await self._run_in_child_context(body)
+
+    async def test_no_stash_is_noop(self):
+        rc_ref: list = [None]
+
+        async def body():
+            # No stash: nothing restored, no error.
+            _restore_request_context(rc_ref)
+            assert fastmcp_request_ctx.get() is None
+
+        await self._run_in_child_context(body)
diff --git a/tests/server/providers/test_addressing.py b/tests/server/providers/test_addressing.py
new file mode 100644
index 0000000..ed34840
--- /dev/null
+++ b/tests/server/providers/test_addressing.py
@@ -0,0 +1,66 @@
+"""Tests for the tool hashing primitives."""
+
+from __future__ import annotations
+
+from fastmcp.server.providers.addressing import (
+    HASH_LENGTH,
+    hash_tool,
+    hashed_backend_name,
+    hashed_resource_uri,
+    parse_hashed_backend_name,
+    parse_hashed_resource_uri,
+)
+
+
+class TestHashFunction:
+    def test_hash_is_fixed_length_hex(self):
+        h = hash_tool("myapp", "greet")
+        assert len(h) == HASH_LENGTH
+        assert all(c in "0123456789abcdef" for c in h)
+
+    def test_same_inputs_same_hash(self):
+        a = hash_tool("app", "submit_form")
+        b = hash_tool("app", "submit_form")
+        assert a == b
+
+    def test_different_app_names_different_hash(self):
+        a = hash_tool("contacts", "save")
+        b = hash_tool("billing", "save")
+        assert a != b
+
+    def test_different_tool_names_different_hash(self):
+        a = hash_tool("app", "save")
+        b = hash_tool("app", "delete")
+        assert a != b
+
+
+class TestBackendNameRoundtrip:
+    def test_format_and_parse(self):
+        name = hashed_backend_name("contacts", "submit_form")
+        parsed = parse_hashed_backend_name(name)
+        assert parsed is not None
+        digest, local = parsed
+        assert digest == hash_tool("contacts", "submit_form")
+        assert local == "submit_form"
+
+    def test_parse_rejects_short_strings(self):
+        assert parse_hashed_backend_name("foo") is None
+
+    def test_parse_rejects_non_hex_prefix(self):
+        assert parse_hashed_backend_name("zzzzzzzzzzzz_save") is None
+
+    def test_parse_rejects_missing_separator(self):
+        assert parse_hashed_backend_name("abcdef012345save") is None
+
+
+class TestResourceUriRoundtrip:
+    def test_format_and_parse(self):
+        uri = hashed_resource_uri("dashboard", "show")
+        h = parse_hashed_resource_uri(uri)
+        assert h == hash_tool("dashboard", "show")
+
+    def test_parse_rejects_unrelated_uri(self):
+        assert parse_hashed_resource_uri("file:///etc/passwd") is None
+
+    def test_parse_rejects_wrong_length_hash(self):
+        assert parse_hashed_resource_uri("ui://prefab/tool/abc/renderer.html") is None
diff --git a/tests/server/providers/test_base_provider.py b/tests/server/providers/test_base_provider.py
new file mode 100644
index 0000000..38db55e
--- /dev/null
+++ b/tests/server/providers/test_base_provider.py
@@ -0,0 +1,115 @@
+"""Tests for base Provider class behavior."""
+
+from typing import Any
+
+import pytest
+
+from fastmcp.server.providers.aggregate import AggregateProvider
+from fastmcp.server.providers.base import Provider
+from fastmcp.server.tasks.config import TaskConfig
+from fastmcp.server.transforms import Namespace
+from fastmcp.tools.base import Tool, ToolResult
+
+
+class CustomTool(Tool):
+    """A custom Tool subclass (not FunctionTool) with task support."""
+
+    task_config: TaskConfig = TaskConfig(mode="optional")
+    parameters: dict[str, Any] = {"type": "object", "properties": {}}
+
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
+        return ToolResult(content="custom result")
+
+
+class SimpleProvider(Provider):
+    """Minimal provider that returns custom components from list methods."""
+
+    def __init__(self, tools: list[Tool] | None = None):
+        super().__init__()
+        self._tools = tools or []
+
+    async def _list_tools(self) -> list[Tool]:
+        return self._tools
+
+
+class FailingProvider(Provider):
+    async def _list_tools(self) -> list[Tool]:
+        raise RuntimeError("provider unavailable")
+
+
+class TestBaseProviderGetTasks:
+    """Tests for Provider.get_tasks() base implementation."""
+
+    async def test_get_tasks_includes_custom_tool_subclasses(self):
+        """Base Provider.get_tasks() should include custom Tool subclasses."""
+        custom_tool = CustomTool(name="custom", description="A custom tool")
+        provider = SimpleProvider(tools=[custom_tool])
+
+        tasks = await provider.get_tasks()
+
+        assert len(tasks) == 1
+        assert tasks[0].name == "custom"
+        assert tasks[0] is custom_tool
+
+    async def test_get_tasks_filters_forbidden_custom_tools(self):
+        """Base Provider.get_tasks() should exclude tools with forbidden task mode."""
+
+        class ForbiddenTool(Tool):
+            task_config: TaskConfig = TaskConfig(mode="forbidden")
+            parameters: dict[str, Any] = {"type": "object", "properties": {}}
+
+            async def run(self, arguments: dict[str, Any]) -> ToolResult:
+                return ToolResult(content="forbidden")
+
+        forbidden_tool = ForbiddenTool(name="forbidden", description="Forbidden tool")
+        provider = SimpleProvider(tools=[forbidden_tool])
+
+        tasks = await provider.get_tasks()
+
+        assert len(tasks) == 0
+
+    async def test_get_tasks_mixed_custom_and_forbidden(self):
+        """Base Provider.get_tasks() filters correctly with mixed task modes."""
+
+        class ForbiddenTool(Tool):
+            task_config: TaskConfig = TaskConfig(mode="forbidden")
+            parameters: dict[str, Any] = {"type": "object", "properties": {}}
+
+            async def run(self, arguments: dict[str, Any]) -> ToolResult:
+                return ToolResult(content="forbidden")
+
+        enabled_tool = CustomTool(name="enabled", description="Task enabled")
+        forbidden_tool = ForbiddenTool(name="forbidden", description="Task forbidden")
+        provider = SimpleProvider(tools=[enabled_tool, forbidden_tool])
+
+        tasks = await provider.get_tasks()
+
+        assert len(tasks) == 1
+        assert tasks[0].name == "enabled"
+
+    async def test_get_tasks_applies_transforms(self):
+        """get_tasks should apply provider transforms to component names."""
+        tool = CustomTool(name="my_tool", description="A tool")
+        provider = SimpleProvider(tools=[tool])
+        provider.add_transform(Namespace("api"))
+
+        tasks = await provider.get_tasks()
+
+        assert len(tasks) == 1
+        assert tasks[0].name == "api_my_tool"
+
+
+class TestAggregateProviderErrors:
+    async def test_provider_errors_warn_by_default(self):
+        aggregate = AggregateProvider([FailingProvider()])
+
+        assert await aggregate.list_tools() == []
+
+    async def test_provider_errors_can_raise(self):
+        aggregate = AggregateProvider(
+            [FailingProvider()],
+            provider_error_strategy="raise",
+        )
+
+        with pytest.raises(RuntimeError, match="provider unavailable"):
+            await aggregate.list_tools()
diff --git a/tests/server/providers/test_fastmcp_provider.py b/tests/server/providers/test_fastmcp_provider.py
new file mode 100644
index 0000000..08b616d
--- /dev/null
+++ b/tests/server/providers/test_fastmcp_provider.py
@@ -0,0 +1,446 @@
+"""Tests for FastMCPProvider."""
+
+import mcp_types as mt
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.prompts.base import PromptResult
+from fastmcp.resources.base import ResourceResult
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.server.providers import FastMCPProvider
+from fastmcp.tools.base import ToolResult
+
+
+class ToolTracingMiddleware(Middleware):
+    """Middleware that traces tool calls."""
+
+    def __init__(self, name: str, calls: list[str]):
+        super().__init__()
+        self._name = name
+        self._calls = calls
+
+    async def on_call_tool(
+        self,
+        context: MiddlewareContext[mt.CallToolRequestParams],
+        call_next: CallNext[mt.CallToolRequestParams, ToolResult],
+    ) -> ToolResult:
+        self._calls.append(f"{self._name}:before")
+        result = await call_next(context)
+        self._calls.append(f"{self._name}:after")
+        return result
+
+
+class ResourceTracingMiddleware(Middleware):
+    """Middleware that traces resource reads."""
+
+    def __init__(self, name: str, calls: list[str]):
+        super().__init__()
+        self._name = name
+        self._calls = calls
+
+    async def on_read_resource(
+        self,
+        context: MiddlewareContext[mt.ReadResourceRequestParams],
+        call_next: CallNext[mt.ReadResourceRequestParams, ResourceResult],
+    ) -> ResourceResult:
+        self._calls.append(f"{self._name}:before")
+        result = await call_next(context)
+        self._calls.append(f"{self._name}:after")
+        return result
+
+
+class PromptTracingMiddleware(Middleware):
+    """Middleware that traces prompt gets."""
+
+    def __init__(self, name: str, calls: list[str]):
+        super().__init__()
+        self._name = name
+        self._calls = calls
+
+    async def on_get_prompt(
+        self,
+        context: MiddlewareContext[mt.GetPromptRequestParams],
+        call_next: CallNext[mt.GetPromptRequestParams, PromptResult],
+    ) -> PromptResult:
+        self._calls.append(f"{self._name}:before")
+        result = await call_next(context)
+        self._calls.append(f"{self._name}:after")
+        return result
+
+
+class TestToolOperations:
+    """Test tool operations through FastMCPProvider."""
+
+    async def test_list_tools(self):
+        """Test listing tools from wrapped server."""
+        server = FastMCP("Test")
+
+        @server.tool
+        def tool_one() -> str:
+            return "one"
+
+        @server.tool
+        def tool_two() -> str:
+            return "two"
+
+        provider = FastMCPProvider(server)
+        tools = await provider.list_tools()
+
+        assert len(tools) == 2
+        names = {t.name for t in tools}
+        assert names == {"tool_one", "tool_two"}
+
+    async def test_get_tool(self):
+        """Test getting a specific tool by name."""
+        server = FastMCP("Test")
+
+        @server.tool
+        def my_tool() -> str:
+            return "result"
+
+        provider = FastMCPProvider(server)
+        tool = await provider.get_tool("my_tool")
+
+        assert tool is not None
+        assert tool.name == "my_tool"
+
+    async def test_get_nonexistent_tool_returns_none(self):
+        """Test that getting a nonexistent tool returns None."""
+        server = FastMCP("Test")
+        provider = FastMCPProvider(server)
+
+        tool = await provider.get_tool("nonexistent")
+        assert tool is None
+
+    async def test_call_tool_via_client(self):
+        """Test calling a tool through a server using the provider."""
+        sub = FastMCP("Sub")
+
+        @sub.tool
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        main = FastMCP("Main")
+        main.add_provider(FastMCPProvider(sub))
+
+        async with Client(main) as client:
+            result = await client.call_tool("greet", {"name": "World"})
+            assert result.data == "Hello, World!"
+
+
+class TestResourceOperations:
+    """Test resource operations through FastMCPProvider."""
+
+    async def test_list_resources(self):
+        """Test listing resources from wrapped server."""
+        server = FastMCP("Test")
+
+        @server.resource("resource://one")
+        def resource_one() -> str:
+            return "one"
+
+        @server.resource("resource://two")
+        def resource_two() -> str:
+            return "two"
+
+        provider = FastMCPProvider(server)
+        resources = await provider.list_resources()
+
+        assert len(resources) == 2
+        uris = {str(r.uri) for r in resources}
+        assert uris == {"resource://one", "resource://two"}
+
+    async def test_get_resource(self):
+        """Test getting a specific resource by URI."""
+        server = FastMCP("Test")
+
+        @server.resource("resource://data")
+        def my_resource() -> str:
+            return "content"
+
+        provider = FastMCPProvider(server)
+        resource = await provider.get_resource("resource://data")
+
+        assert resource is not None
+        assert str(resource.uri) == "resource://data"
+
+    async def test_read_resource_via_client(self):
+        """Test reading a resource through a server using the provider."""
+        sub = FastMCP("Sub")
+
+        @sub.resource("resource://data")
+        def my_resource() -> str:
+            return "content"
+
+        main = FastMCP("Main")
+        main.add_provider(FastMCPProvider(sub))
+
+        async with Client(main) as client:
+            result = await client.read_resource("resource://data")
+            assert isinstance(result[0], mt.TextResourceContents)
+            assert result[0].text == "content"
+
+
+class TestResourceTemplateOperations:
+    """Test resource template operations through FastMCPProvider."""
+
+    async def test_list_resource_templates(self):
+        """Test listing resource templates from wrapped server."""
+        server = FastMCP("Test")
+
+        @server.resource("resource://{id}/data")
+        def my_template(id: str) -> str:
+            return f"data for {id}"
+
+        provider = FastMCPProvider(server)
+        templates = await provider.list_resource_templates()
+
+        assert len(templates) == 1
+        assert templates[0].uri_template == "resource://{id}/data"
+
+    async def test_get_resource_template(self):
+        """Test getting a template that matches a URI."""
+        server = FastMCP("Test")
+
+        @server.resource("resource://{id}/data")
+        def my_template(id: str) -> str:
+            return f"data for {id}"
+
+        provider = FastMCPProvider(server)
+        template = await provider.get_resource_template("resource://123/data")
+
+        assert template is not None
+
+    async def test_read_resource_template_via_client(self):
+        """Test reading a resource via template through a server using the provider."""
+        sub = FastMCP("Sub")
+
+        @sub.resource("resource://{id}/data")
+        def my_template(id: str) -> str:
+            return f"data for {id}"
+
+        main = FastMCP("Main")
+        main.add_provider(FastMCPProvider(sub))
+
+        async with Client(main) as client:
+            result = await client.read_resource("resource://123/data")
+            assert isinstance(result[0], mt.TextResourceContents)
+            assert result[0].text == "data for 123"
+
+
+class TestPromptOperations:
+    """Test prompt operations through FastMCPProvider."""
+
+    async def test_list_prompts(self):
+        """Test listing prompts from wrapped server."""
+        server = FastMCP("Test")
+
+        @server.prompt
+        def prompt_one() -> str:
+            return "one"
+
+        @server.prompt
+        def prompt_two() -> str:
+            return "two"
+
+        provider = FastMCPProvider(server)
+        prompts = await provider.list_prompts()
+
+        assert len(prompts) == 2
+        names = {p.name for p in prompts}
+        assert names == {"prompt_one", "prompt_two"}
+
+    async def test_get_prompt(self):
+        """Test getting a specific prompt by name."""
+        server = FastMCP("Test")
+
+        @server.prompt
+        def my_prompt() -> str:
+            return "content"
+
+        provider = FastMCPProvider(server)
+        prompt = await provider.get_prompt("my_prompt")
+
+        assert prompt is not None
+        assert prompt.name == "my_prompt"
+
+    async def test_render_prompt_via_client(self):
+        """Test rendering a prompt through a server using the provider."""
+        sub = FastMCP("Sub")
+
+        @sub.prompt
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        main = FastMCP("Main")
+        main.add_provider(FastMCPProvider(sub))
+
+        async with Client(main) as client:
+            result = await client.get_prompt("greet", {"name": "World"})
+            assert isinstance(result.messages[0].content, mt.TextContent)
+            assert result.messages[0].content.text == "Hello, World!"
+
+
+class TestServerReference:
+    """Test that provider maintains reference to wrapped server."""
+
+    def test_server_attribute(self):
+        """Test that provider exposes the wrapped server."""
+        server = FastMCP("Test")
+        provider = FastMCPProvider(server)
+
+        assert provider.server is server
+
+    def test_server_name_accessible(self):
+        """Test that server name is accessible through provider."""
+        server = FastMCP("MyServer")
+        provider = FastMCPProvider(server)
+
+        assert provider.server.name == "MyServer"
+
+
+class TestMiddlewareChain:
+    """Test that middleware runs at each level of mounted servers."""
+
+    async def test_tool_middleware_three_levels(self):
+        """Middleware runs at parent, child, and grandchild levels for tools."""
+        calls: list[str] = []
+
+        grandchild = FastMCP("Grandchild")
+
+        @grandchild.tool
+        async def compute(x: int) -> int:
+            calls.append("grandchild:tool")
+            return x * 2
+
+        grandchild.add_middleware(ToolTracingMiddleware("grandchild", calls))
+
+        child = FastMCP("Child")
+        child.mount(grandchild, namespace="gc")
+        child.add_middleware(ToolTracingMiddleware("child", calls))
+
+        parent = FastMCP("Parent")
+        parent.mount(child, namespace="c")
+        parent.add_middleware(ToolTracingMiddleware("parent", calls))
+
+        async with Client(parent) as client:
+            result = await client.call_tool("c_gc_compute", {"x": 5})
+            assert result.data == 10
+
+        assert calls == [
+            "parent:before",
+            "child:before",
+            "grandchild:before",
+            "grandchild:tool",
+            "grandchild:after",
+            "child:after",
+            "parent:after",
+        ]
+
+    async def test_resource_middleware_three_levels(self):
+        """Middleware runs at parent, child, and grandchild levels for resources."""
+        calls: list[str] = []
+
+        grandchild = FastMCP("Grandchild")
+
+        @grandchild.resource("data://value")
+        async def get_data() -> str:
+            calls.append("grandchild:resource")
+            return "result"
+
+        grandchild.add_middleware(ResourceTracingMiddleware("grandchild", calls))
+
+        child = FastMCP("Child")
+        child.mount(grandchild, namespace="gc")
+        child.add_middleware(ResourceTracingMiddleware("child", calls))
+
+        parent = FastMCP("Parent")
+        parent.mount(child, namespace="c")
+        parent.add_middleware(ResourceTracingMiddleware("parent", calls))
+
+        async with Client(parent) as client:
+            result = await client.read_resource("data://c/gc/value")
+            assert isinstance(result[0], mt.TextResourceContents)
+            assert result[0].text == "result"
+
+        assert calls == [
+            "parent:before",
+            "child:before",
+            "grandchild:before",
+            "grandchild:resource",
+            "grandchild:after",
+            "child:after",
+            "parent:after",
+        ]
+
+    async def test_prompt_middleware_three_levels(self):
+        """Middleware runs at parent, child, and grandchild levels for prompts."""
+        calls: list[str] = []
+
+        grandchild = FastMCP("Grandchild")
+
+        @grandchild.prompt
+        async def greet(name: str) -> str:
+            calls.append("grandchild:prompt")
+            return f"Hello, {name}!"
+
+        grandchild.add_middleware(PromptTracingMiddleware("grandchild", calls))
+
+        child = FastMCP("Child")
+        child.mount(grandchild, namespace="gc")
+        child.add_middleware(PromptTracingMiddleware("child", calls))
+
+        parent = FastMCP("Parent")
+        parent.mount(child, namespace="c")
+        parent.add_middleware(PromptTracingMiddleware("parent", calls))
+
+        async with Client(parent) as client:
+            result = await client.get_prompt("c_gc_greet", {"name": "World"})
+            assert isinstance(result.messages[0].content, mt.TextContent)
+            assert result.messages[0].content.text == "Hello, World!"
+
+        assert calls == [
+            "parent:before",
+            "child:before",
+            "grandchild:before",
+            "grandchild:prompt",
+            "grandchild:after",
+            "child:after",
+            "parent:after",
+        ]
+
+    async def test_resource_template_middleware_three_levels(self):
+        """Middleware runs at all levels for resource templates."""
+        calls: list[str] = []
+
+        grandchild = FastMCP("Grandchild")
+
+        @grandchild.resource("item://{id}")
+        async def get_item(id: str) -> str:
+            calls.append("grandchild:template")
+            return f"item-{id}"
+
+        grandchild.add_middleware(ResourceTracingMiddleware("grandchild", calls))
+
+        child = FastMCP("Child")
+        child.mount(grandchild, namespace="gc")
+        child.add_middleware(ResourceTracingMiddleware("child", calls))
+
+        parent = FastMCP("Parent")
+        parent.mount(child, namespace="c")
+        parent.add_middleware(ResourceTracingMiddleware("parent", calls))
+
+        async with Client(parent) as client:
+            result = await client.read_resource("item://c/gc/42")
+            assert isinstance(result[0], mt.TextResourceContents)
+            assert result[0].text == "item-42"
+
+        assert calls == [
+            "parent:before",
+            "child:before",
+            "grandchild:before",
+            "grandchild:template",
+            "grandchild:after",
+            "child:after",
+            "parent:after",
+        ]
diff --git a/tests/server/providers/test_local_provider.py b/tests/server/providers/test_local_provider.py
new file mode 100644
index 0000000..ebc74f9
--- /dev/null
+++ b/tests/server/providers/test_local_provider.py
@@ -0,0 +1,834 @@
+"""Comprehensive tests for LocalProvider.
+
+Tests cover:
+- Storage operations (add/remove tools, resources, templates, prompts)
+- Provider interface (list/get operations)
+- Decorator patterns (all calling styles)
+- Tool transformations
+- Standalone usage (provider attached to multiple servers)
+- Task registration
+"""
+
+from typing import Any
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.prompts.base import Prompt
+from fastmcp.server.providers.local_provider import LocalProvider
+from fastmcp.server.tasks import TaskConfig
+from fastmcp.tools.base import Tool, ToolResult
+
+
+class TestLocalProviderStorage:
+    """Tests for LocalProvider storage operations."""
+
+    def test_add_tool(self):
+        """Test adding a tool to LocalProvider."""
+        provider = LocalProvider()
+
+        tool = Tool(
+            name="test_tool",
+            description="A test tool",
+            parameters={"type": "object", "properties": {}},
+        )
+        provider.add_tool(tool)
+
+        assert "tool:test_tool@" in provider._components
+        assert provider._components["tool:test_tool@"] is tool
+
+    def test_add_multiple_tools(self):
+        """Test adding multiple tools."""
+        provider = LocalProvider()
+
+        tool1 = Tool(
+            name="tool1",
+            description="First tool",
+            parameters={"type": "object", "properties": {}},
+        )
+        tool2 = Tool(
+            name="tool2",
+            description="Second tool",
+            parameters={"type": "object", "properties": {}},
+        )
+        provider.add_tool(tool1)
+        provider.add_tool(tool2)
+
+        assert "tool:tool1@" in provider._components
+        assert "tool:tool2@" in provider._components
+
+    def test_remove_tool(self):
+        """Test removing a tool from LocalProvider."""
+        provider = LocalProvider()
+
+        tool = Tool(
+            name="test_tool",
+            description="A test tool",
+            parameters={"type": "object", "properties": {}},
+        )
+        provider.add_tool(tool)
+        provider.remove_tool("test_tool")
+
+        assert "tool:test_tool@" not in provider._components
+
+    def test_remove_nonexistent_tool_raises(self):
+        """Test that removing a nonexistent tool raises KeyError."""
+        provider = LocalProvider()
+
+        with pytest.raises(KeyError):
+            provider.remove_tool("nonexistent")
+
+    def test_add_resource(self):
+        """Test adding a resource to LocalProvider."""
+        provider = LocalProvider()
+
+        @provider.resource("resource://test")
+        def test_resource() -> str:
+            return "content"
+
+        assert "resource:resource://test@" in provider._components
+
+    def test_remove_resource(self):
+        """Test removing a resource from LocalProvider."""
+        provider = LocalProvider()
+
+        @provider.resource("resource://test")
+        def test_resource() -> str:
+            return "content"
+
+        provider.remove_resource("resource://test")
+
+        assert "resource:resource://test@" not in provider._components
+
+    def test_add_template(self):
+        """Test adding a resource template to LocalProvider."""
+        provider = LocalProvider()
+
+        @provider.resource("resource://{id}")
+        def template_fn(id: str) -> str:
+            return f"Resource {id}"
+
+        assert "template:resource://{id}@" in provider._components
+
+    def test_remove_template(self):
+        """Test removing a resource template from LocalProvider."""
+        provider = LocalProvider()
+
+        @provider.resource("resource://{id}")
+        def template_fn(id: str) -> str:
+            return f"Resource {id}"
+
+        provider.remove_template("resource://{id}")
+
+        assert "template:resource://{id}@" not in provider._components
+
+    def test_add_prompt(self):
+        """Test adding a prompt to LocalProvider."""
+        provider = LocalProvider()
+
+        prompt = Prompt(
+            name="test_prompt",
+            description="A test prompt",
+        )
+        provider.add_prompt(prompt)
+
+        assert "prompt:test_prompt@" in provider._components
+
+    def test_remove_prompt(self):
+        """Test removing a prompt from LocalProvider."""
+        provider = LocalProvider()
+
+        prompt = Prompt(
+            name="test_prompt",
+            description="A test prompt",
+        )
+        provider.add_prompt(prompt)
+        provider.remove_prompt("test_prompt")
+
+        assert "prompt:test_prompt@" not in provider._components
+
+
+class TestLocalProviderInterface:
+    """Tests for LocalProvider's Provider interface."""
+
+    async def test_list_tools_empty(self):
+        """Test listing tools when empty."""
+        provider = LocalProvider()
+        tools = await provider.list_tools()
+        assert tools == []
+
+    async def test_list_tools(self):
+        """Test listing tools returns all stored tools."""
+        provider = LocalProvider()
+
+        tool1 = Tool(name="tool1", description="First", parameters={"type": "object"})
+        tool2 = Tool(name="tool2", description="Second", parameters={"type": "object"})
+        provider.add_tool(tool1)
+        provider.add_tool(tool2)
+
+        tools = await provider.list_tools()
+        assert len(tools) == 2
+        names = {t.name for t in tools}
+        assert names == {"tool1", "tool2"}
+
+    async def test_get_tool_found(self):
+        """Test getting a tool that exists."""
+        provider = LocalProvider()
+
+        tool = Tool(
+            name="test_tool",
+            description="A test tool",
+            parameters={"type": "object"},
+        )
+        provider.add_tool(tool)
+
+        result = await provider.get_tool("test_tool")
+        assert result is not None
+        assert result.name == "test_tool"
+
+    async def test_get_tool_not_found(self):
+        """Test getting a tool that doesn't exist returns None."""
+        provider = LocalProvider()
+        result = await provider.get_tool("nonexistent")
+        assert result is None
+
+    async def test_list_resources(self):
+        """Test listing resources."""
+        provider = LocalProvider()
+
+        @provider.resource("resource://test")
+        def test_resource() -> str:
+            return "content"
+
+        resources = await provider.list_resources()
+        assert len(resources) == 1
+        assert str(resources[0].uri) == "resource://test"
+
+    async def test_get_resource_found(self):
+        """Test getting a resource that exists."""
+        provider = LocalProvider()
+
+        @provider.resource("resource://test")
+        def test_resource() -> str:
+            return "content"
+
+        result = await provider.get_resource("resource://test")
+        assert result is not None
+        assert str(result.uri) == "resource://test"
+
+    async def test_get_resource_not_found(self):
+        """Test getting a resource that doesn't exist returns None."""
+        provider = LocalProvider()
+        result = await provider.get_resource("resource://nonexistent")
+        assert result is None
+
+    async def test_list_resource_templates(self):
+        """Test listing resource templates."""
+        provider = LocalProvider()
+
+        @provider.resource("resource://{id}")
+        def template_fn(id: str) -> str:
+            return f"Resource {id}"
+
+        templates = await provider.list_resource_templates()
+        assert len(templates) == 1
+        assert templates[0].uri_template == "resource://{id}"
+
+    async def test_get_resource_template_match(self):
+        """Test getting a template that matches a URI."""
+        provider = LocalProvider()
+
+        @provider.resource("resource://{id}")
+        def template_fn(id: str) -> str:
+            return f"Resource {id}"
+
+        result = await provider.get_resource_template("resource://123")
+        assert result is not None
+        assert result.uri_template == "resource://{id}"
+
+    async def test_get_resource_template_no_match(self):
+        """Test getting a template with no match returns None."""
+        provider = LocalProvider()
+
+        @provider.resource("resource://{id}")
+        def template_fn(id: str) -> str:
+            return f"Resource {id}"
+
+        result = await provider.get_resource_template("other://123")
+        assert result is None
+
+    async def test_list_prompts(self):
+        """Test listing prompts."""
+        provider = LocalProvider()
+
+        prompt = Prompt(
+            name="test_prompt",
+            description="A test prompt",
+        )
+        provider.add_prompt(prompt)
+
+        prompts = await provider.list_prompts()
+        assert len(prompts) == 1
+        assert prompts[0].name == "test_prompt"
+
+    async def test_get_prompt_found(self):
+        """Test getting a prompt that exists."""
+        provider = LocalProvider()
+
+        prompt = Prompt(
+            name="test_prompt",
+            description="A test prompt",
+        )
+        provider.add_prompt(prompt)
+
+        result = await provider.get_prompt("test_prompt")
+        assert result is not None
+        assert result.name == "test_prompt"
+
+    async def test_get_prompt_not_found(self):
+        """Test getting a prompt that doesn't exist returns None."""
+        provider = LocalProvider()
+        result = await provider.get_prompt("nonexistent")
+        assert result is None
+
+
+class TestLocalProviderDecorators:
+    """Tests for LocalProvider decorator registration.
+
+    Note: Decorator calling patterns and metadata are tested in the standalone
+    decorator tests (tests/tools/test_standalone_decorator.py, etc.). These tests
+    focus on LocalProvider-specific behavior: registration into _components,
+    the enabled flag, and round-trip execution via Client.
+    """
+
+    def test_tool_decorator_registers(self):
+        """Tool decorator should register in _components."""
+        provider = LocalProvider()
+
+        @provider.tool
+        def my_tool(x: int) -> int:
+            return x * 2
+
+        assert "tool:my_tool@" in provider._components
+        assert provider._components["tool:my_tool@"].name == "my_tool"
+
+    def test_tool_decorator_with_custom_name_registers(self):
+        """Tool with custom name should register under that name."""
+        provider = LocalProvider()
+
+        @provider.tool(name="custom_name")
+        def my_tool(x: int) -> int:
+            return x * 2
+
+        assert "tool:custom_name@" in provider._components
+        assert "tool:my_tool@" not in provider._components
+
+    def test_tool_direct_call(self):
+        """provider.tool(fn) should register the function."""
+        provider = LocalProvider()
+
+        def my_tool(x: int) -> int:
+            return x * 2
+
+        provider.tool(my_tool, name="direct_tool")
+
+        assert "tool:direct_tool@" in provider._components
+
+    def test_tool_enabled_false(self):
+        """Tool with enabled=False should add a Visibility transform."""
+        provider = LocalProvider()
+
+        @provider.tool(enabled=False)
+        def disabled_tool() -> str:
+            return "should be disabled"
+
+        assert "tool:disabled_tool@" in provider._components
+        # enabled=False adds a Visibility transform to disable the tool
+        from fastmcp.server.transforms.visibility import Visibility
+
+        enabled_transforms = [
+            t for t in provider.transforms if isinstance(t, Visibility)
+        ]
+        assert len(enabled_transforms) == 1
+        assert enabled_transforms[0]._enabled is False
+        assert enabled_transforms[0].keys == {"tool:disabled_tool@"}
+
+    async def test_tool_enabled_false_not_listed(self):
+        """Disabled tool should not appear in get_tools (filtering happens at server level)."""
+        provider = LocalProvider()
+
+        @provider.tool(enabled=False)
+        def disabled_tool() -> str:
+            return "should be disabled"
+
+        @provider.tool
+        def enabled_tool() -> str:
+            return "should be enabled"
+
+        # Filtering happens at the server level, not provider level
+        server = FastMCP("Test", providers=[provider])
+        tools = await server.list_tools()
+        names = {t.name for t in tools}
+        assert "enabled_tool" in names
+        assert "disabled_tool" not in names
+
+    async def test_server_enable_overrides_provider_disable(self):
+        """Server-level enable should override provider-level disable."""
+        provider = LocalProvider()
+
+        @provider.tool(enabled=False)
+        def my_tool() -> str:
+            return "result"
+
+        server = FastMCP("Test", providers=[provider])
+
+        # Tool is disabled at provider level
+        assert await server.get_tool("my_tool") is None
+
+        # Server-level enable overrides it
+        server.enable(names={"my_tool"})
+        tool = await server.get_tool("my_tool")
+        assert tool is not None
+        assert tool.name == "my_tool"
+
+    async def test_tool_roundtrip(self):
+        """Tool should execute correctly via Client."""
+        provider = LocalProvider()
+
+        @provider.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        server = FastMCP("Test", providers=[provider])
+
+        async with Client(server) as client:
+            result = await client.call_tool("add", {"a": 2, "b": 3})
+            assert result.data == 5
+
+    def test_resource_decorator_registers(self):
+        """Resource decorator should register in _components."""
+        provider = LocalProvider()
+
+        @provider.resource("resource://test")
+        def my_resource() -> str:
+            return "test content"
+
+        assert "resource:resource://test@" in provider._components
+
+    def test_resource_with_custom_name_registers(self):
+        """Resource with custom name should register with that name."""
+        provider = LocalProvider()
+
+        @provider.resource("resource://test", name="custom_name")
+        def my_resource() -> str:
+            return "test content"
+
+        assert provider._components["resource:resource://test@"].name == "custom_name"
+
+    def test_resource_enabled_false(self):
+        """Resource with enabled=False should add a Visibility transform."""
+        provider = LocalProvider()
+
+        @provider.resource("resource://test", enabled=False)
+        def disabled_resource() -> str:
+            return "should be disabled"
+
+        assert "resource:resource://test@" in provider._components
+        # enabled=False adds a Visibility transform to disable the resource
+        from fastmcp.server.transforms.visibility import Visibility
+
+        enabled_transforms = [
+            t for t in provider.transforms if isinstance(t, Visibility)
+        ]
+        assert len(enabled_transforms) == 1
+        assert enabled_transforms[0]._enabled is False
+        assert enabled_transforms[0].keys == {"resource:resource://test@"}
+
+    async def test_resource_enabled_false_not_listed(self):
+        """Disabled resource should not appear in get_resources (filtering at server level)."""
+        provider = LocalProvider()
+
+        @provider.resource("resource://disabled", enabled=False)
+        def disabled_resource() -> str:
+            return "should be disabled"
+
+        @provider.resource("resource://enabled")
+        def enabled_resource() -> str:
+            return "should be enabled"
+
+        # Filtering happens at the server level, not provider level
+        server = FastMCP("Test", providers=[provider])
+        resources = await server.list_resources()
+        uris = {str(r.uri) for r in resources}
+        assert "resource://enabled" in uris
+        assert "resource://disabled" not in uris
+
+    def test_template_enabled_false(self):
+        """Template with enabled=False should add a Visibility transform."""
+        provider = LocalProvider()
+
+        @provider.resource("data://{id}", enabled=False)
+        def disabled_template(id: str) -> str:
+            return f"Data {id}"
+
+        assert "template:data://{id}@" in provider._components
+        # enabled=False adds a Visibility transform to disable the template
+        from fastmcp.server.transforms.visibility import Visibility
+
+        enabled_transforms = [
+            t for t in provider.transforms if isinstance(t, Visibility)
+        ]
+        assert len(enabled_transforms) == 1
+        assert enabled_transforms[0]._enabled is False
+        assert enabled_transforms[0].keys == {"template:data://{id}@"}
+
+    async def test_template_enabled_false_not_listed(self):
+        """Disabled template should not appear in get_resource_templates (filtering at server level)."""
+        provider = LocalProvider()
+
+        @provider.resource("data://{id}", enabled=False)
+        def disabled_template(id: str) -> str:
+            return f"Data {id}"
+
+        @provider.resource("items://{id}")
+        def enabled_template(id: str) -> str:
+            return f"Item {id}"
+
+        # Filtering happens at the server level, not provider level
+        server = FastMCP("Test", providers=[provider])
+        templates = await server.list_resource_templates()
+        uris = {t.uri_template for t in templates}
+        assert "items://{id}" in uris
+        assert "data://{id}" not in uris
+
+    async def test_resource_roundtrip(self):
+        """Resource should execute correctly via Client."""
+        provider = LocalProvider()
+
+        @provider.resource("resource://greeting")
+        def greeting() -> str:
+            return "Hello, World!"
+
+        server = FastMCP("Test", providers=[provider])
+
+        async with Client(server) as client:
+            result = await client.read_resource("resource://greeting")
+            assert "Hello, World!" in str(result)
+
+    def test_prompt_decorator_registers(self):
+        """Prompt decorator should register in _components."""
+        provider = LocalProvider()
+
+        @provider.prompt
+        def my_prompt() -> str:
+            return "A prompt"
+
+        assert "prompt:my_prompt@" in provider._components
+
+    def test_prompt_with_custom_name_registers(self):
+        """Prompt with custom name should register under that name."""
+        provider = LocalProvider()
+
+        @provider.prompt(name="custom_prompt")
+        def my_prompt() -> str:
+            return "A prompt"
+
+        assert "prompt:custom_prompt@" in provider._components
+        assert "prompt:my_prompt@" not in provider._components
+
+    def test_prompt_enabled_false(self):
+        """Prompt with enabled=False should add a Visibility transform."""
+        provider = LocalProvider()
+
+        @provider.prompt(enabled=False)
+        def disabled_prompt() -> str:
+            return "should be disabled"
+
+        assert "prompt:disabled_prompt@" in provider._components
+        # enabled=False adds a Visibility transform to disable the prompt
+        from fastmcp.server.transforms.visibility import Visibility
+
+        enabled_transforms = [
+            t for t in provider.transforms if isinstance(t, Visibility)
+        ]
+        assert len(enabled_transforms) == 1
+        assert enabled_transforms[0]._enabled is False
+        assert enabled_transforms[0].keys == {"prompt:disabled_prompt@"}
+
+    async def test_prompt_enabled_false_not_listed(self):
+        """Disabled prompt should not appear in get_prompts (filtering at server level)."""
+        provider = LocalProvider()
+
+        @provider.prompt(enabled=False)
+        def disabled_prompt() -> str:
+            return "should be disabled"
+
+        @provider.prompt
+        def enabled_prompt() -> str:
+            return "should be enabled"
+
+        # Filtering happens at the server level, not provider level
+        server = FastMCP("Test", providers=[provider])
+        prompts = await server.list_prompts()
+        names = {p.name for p in prompts}
+        assert "enabled_prompt" in names
+        assert "disabled_prompt" not in names
+
+    async def test_prompt_roundtrip(self):
+        """Prompt should execute correctly via Client."""
+        provider = LocalProvider()
+
+        @provider.prompt
+        def greeting(name: str) -> str:
+            return f"Hello, {name}!"
+
+        server = FastMCP("Test", providers=[provider])
+
+        async with Client(server) as client:
+            result = await client.get_prompt("greeting", {"name": "World"})
+            assert "Hello, World!" in str(result)
+
+
+class TestProviderToolTransformations:
+    """Tests for tool transformations via add_transform()."""
+
+    async def test_add_transform_applies_tool_transforms(self):
+        """Test that add_transform with ToolTransform applies tool transformations."""
+        from fastmcp.server.transforms import ToolTransform
+        from fastmcp.tools.tool_transform import ToolTransformConfig
+
+        provider = LocalProvider()
+
+        @provider.tool
+        def my_tool(x: int) -> int:
+            return x
+
+        # Add transform layer
+        layer = ToolTransform({"my_tool": ToolTransformConfig(name="renamed_tool")})
+        provider.add_transform(layer)
+
+        # Get tools and pass directly to transform
+        tools = await provider.list_tools()
+        transformed_tools = await layer.list_tools(tools)
+        assert len(transformed_tools) == 1
+        assert transformed_tools[0].name == "renamed_tool"
+
+    async def test_transform_layer_get_tool(self):
+        """Test that ToolTransform.get_tool works correctly."""
+        from fastmcp.server.transforms import ToolTransform
+        from fastmcp.tools.tool_transform import ToolTransformConfig
+
+        provider = LocalProvider()
+
+        @provider.tool
+        def original_tool(x: int) -> int:
+            return x
+
+        layer = ToolTransform(
+            {"original_tool": ToolTransformConfig(name="transformed_tool")}
+        )
+
+        # Get tool through layer with call_next
+        async def get_tool(name: str, version=None):
+            return await provider._get_tool(name, version)
+
+        tool = await layer.get_tool("transformed_tool", get_tool)
+        assert tool is not None
+        assert tool.name == "transformed_tool"
+
+        # Original name should not work
+        tool = await layer.get_tool("original_tool", get_tool)
+        assert tool is None
+
+    async def test_transform_layer_description_change(self):
+        """Test that ToolTransform can change description."""
+        from fastmcp.server.transforms import ToolTransform
+        from fastmcp.tools.tool_transform import ToolTransformConfig
+
+        provider = LocalProvider()
+
+        @provider.tool
+        def my_tool(x: int) -> int:
+            return x
+
+        layer = ToolTransform(
+            {"my_tool": ToolTransformConfig(description="New description")}
+        )
+
+        async def get_tool(name: str, version=None):
+            return await provider._get_tool(name, version)
+
+        tool = await layer.get_tool("my_tool", get_tool)
+        assert tool is not None
+        assert tool.description == "New description"
+
+    async def test_provider_unaffected_by_transforms(self):
+        """Test that provider's own tools are unchanged by layers stored on it."""
+        from fastmcp.server.transforms import ToolTransform
+        from fastmcp.tools.tool_transform import ToolTransformConfig
+
+        provider = LocalProvider()
+
+        @provider.tool
+        def my_tool(x: int) -> int:
+            return x
+
+        # Add layer to provider (layers are applied by server, not _list_tools)
+        layer = ToolTransform({"my_tool": ToolTransformConfig(name="renamed")})
+        provider.add_transform(layer)
+
+        # Provider's _list_tools returns raw tools (transforms applied when queried via list_tools)
+        original_tools = await provider._list_tools()
+        assert original_tools[0].name == "my_tool"
+
+        # Transform modifies them when applied directly
+        transformed_tools = await layer.list_tools(original_tools)
+        assert transformed_tools[0].name == "renamed"
+
+    def test_transform_layer_duplicate_target_name_raises_error(self):
+        """Test that ToolTransform with duplicate target names raises ValueError."""
+        from fastmcp.server.transforms import ToolTransform
+        from fastmcp.tools.tool_transform import ToolTransformConfig
+
+        with pytest.raises(ValueError, match="duplicate target name"):
+            ToolTransform(
+                {
+                    "tool_a": ToolTransformConfig(name="same_name"),
+                    "tool_b": ToolTransformConfig(name="same_name"),
+                }
+            )
+
+
+class TestLocalProviderTaskRegistration:
+    """Tests for task registration in LocalProvider."""
+
+    async def test_get_tasks_returns_task_eligible_tools(self):
+        """Test that get_tasks returns tools with task support."""
+        provider = LocalProvider()
+
+        @provider.tool(task=True)
+        async def background_tool(x: int) -> int:
+            return x
+
+        tasks = await provider.get_tasks()
+        assert len(tasks) == 1
+        assert tasks[0].name == "background_tool"
+
+    async def test_get_tasks_filters_forbidden_tools(self):
+        """Test that get_tasks excludes tools with forbidden task mode."""
+        provider = LocalProvider()
+
+        @provider.tool(task=False)
+        def sync_only_tool(x: int) -> int:
+            return x
+
+        tasks = await provider.get_tasks()
+        assert len(tasks) == 0
+
+    async def test_get_tasks_includes_custom_tool_subclasses(self):
+        """Test that custom Tool subclasses are included in get_tasks."""
+
+        class CustomTool(Tool):
+            task_config: TaskConfig = TaskConfig(mode="optional")
+            parameters: dict[str, Any] = {"type": "object", "properties": {}}
+
+            async def run(self, arguments: dict[str, Any]) -> ToolResult:
+                return ToolResult(content="custom")
+
+        provider = LocalProvider()
+        provider.add_tool(CustomTool(name="custom", description="Custom tool"))
+
+        tasks = await provider.get_tasks()
+        assert len(tasks) == 1
+        assert tasks[0].name == "custom"
+
+
+class TestLocalProviderStandaloneUsage:
+    """Tests for standalone LocalProvider usage patterns."""
+
+    async def test_attach_provider_to_server(self):
+        """Test that LocalProvider can be attached to a server."""
+        provider = LocalProvider()
+
+        @provider.tool
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        server = FastMCP("Test", providers=[provider])
+
+        async with Client(server) as client:
+            tools = await client.list_tools()
+            assert any(t.name == "greet" for t in tools)
+
+    async def test_attach_provider_to_multiple_servers(self):
+        """Test that same provider can be attached to multiple servers."""
+        provider = LocalProvider()
+
+        @provider.tool
+        def shared_tool() -> str:
+            return "shared"
+
+        server1 = FastMCP("Server1", providers=[provider])
+        server2 = FastMCP("Server2", providers=[provider])
+
+        async with Client(server1) as client1:
+            tools1 = await client1.list_tools()
+            assert any(t.name == "shared_tool" for t in tools1)
+
+        async with Client(server2) as client2:
+            tools2 = await client2.list_tools()
+            assert any(t.name == "shared_tool" for t in tools2)
+
+    async def test_tools_visible_via_server_get_tools(self):
+        """Test that provider tools are visible via server.list_tools()."""
+        provider = LocalProvider()
+
+        @provider.tool
+        def provider_tool() -> str:
+            return "from provider"
+
+        server = FastMCP("Test", providers=[provider])
+
+        tools = await server.list_tools()
+        assert any(t.name == "provider_tool" for t in tools)
+
+    async def test_server_decorator_and_provider_tools_coexist(self):
+        """Test that server decorators and provider tools coexist."""
+        provider = LocalProvider()
+
+        @provider.tool
+        def provider_tool() -> str:
+            return "from provider"
+
+        server = FastMCP("Test", providers=[provider])
+
+        @server.tool
+        def server_tool() -> str:
+            return "from server"
+
+        tools = await server.list_tools()
+        assert any(t.name == "provider_tool" for t in tools)
+        assert any(t.name == "server_tool" for t in tools)
+
+    async def test_local_provider_first_wins_duplicates(self):
+        """Test that LocalProvider tools take precedence over added providers."""
+        provider = LocalProvider()
+
+        @provider.tool
+        def duplicate_tool() -> str:
+            return "from added provider"
+
+        server = FastMCP("Test", providers=[provider])
+
+        @server.tool
+        def duplicate_tool() -> str:  # noqa: F811
+            return "from server"
+
+        # Server's LocalProvider is first, so its tool wins
+        tools = await server.list_tools()
+        assert any(t.name == "duplicate_tool" for t in tools)
+
+        async with Client(server) as client:
+            result = await client.call_tool("duplicate_tool", {})
+            assert result.data == "from server"
diff --git a/tests/server/providers/test_local_provider_prompts.py b/tests/server/providers/test_local_provider_prompts.py
new file mode 100644
index 0000000..bc19919
--- /dev/null
+++ b/tests/server/providers/test_local_provider_prompts.py
@@ -0,0 +1,484 @@
+"""Tests for prompt behavior in LocalProvider.
+
+Tests cover:
+- Prompt context injection
+- Prompt decorator patterns
+"""
+
+import pytest
+from mcp_types import TextContent
+
+from fastmcp import Client, Context, FastMCP
+from fastmcp.prompts.base import Prompt, PromptResult
+
+
+class TestPromptContext:
+    async def test_prompt_context(self):
+        mcp = FastMCP()
+
+        @mcp.prompt
+        def prompt_fn(name: str, ctx: Context) -> str:
+            assert isinstance(ctx, Context)
+            return f"Hello, {name}! {ctx.request_id}"
+
+        async with Client(mcp) as client:
+            result = await client.get_prompt("prompt_fn", {"name": "World"})
+            assert len(result.messages) == 1
+            message = result.messages[0]
+            assert message.role == "user"
+
+    async def test_prompt_context_with_callable_object(self):
+        mcp = FastMCP()
+
+        class MyPrompt:
+            def __call__(self, name: str, ctx: Context) -> str:
+                return f"Hello, {name}! {ctx.request_id}"
+
+        mcp.add_prompt(Prompt.from_function(MyPrompt(), name="my_prompt"))
+
+        async with Client(mcp) as client:
+            result = await client.get_prompt("my_prompt", {"name": "World"})
+            assert len(result.messages) == 1
+            message = result.messages[0]
+            assert message.role == "user"
+            assert isinstance(message.content, TextContent)
+            # The exact request_id is an SDK-internal counter value; assert that
+            # the callable object received a context and rendered it, not the
+            # specific counter (which depends on session bootstrap requests).
+            assert message.content.text.startswith("Hello, World! ")
+
+
+class TestPromptDecorator:
+    async def test_prompt_decorator(self):
+        mcp = FastMCP()
+
+        @mcp.prompt
+        def fn() -> str:
+            return "Hello, world!"
+
+        prompts = await mcp.list_prompts()
+        assert len(prompts) == 1
+        prompt = next(p for p in prompts if p.name == "fn")
+        assert prompt.name == "fn"
+        content = await prompt.render()
+        assert isinstance(content, PromptResult)
+        assert isinstance(content.messages[0].content, TextContent)
+        assert content.messages[0].content.text == "Hello, world!"
+
+    async def test_prompt_decorator_without_parentheses(self):
+        mcp = FastMCP()
+
+        @mcp.prompt
+        def fn() -> str:
+            return "Hello, world!"
+
+        prompts = await mcp.list_prompts()
+        assert any(p.name == "fn" for p in prompts)
+
+        result = await mcp.render_prompt("fn")
+        assert len(result.messages) == 1
+        assert isinstance(result.messages[0].content, TextContent)
+        assert result.messages[0].content.text == "Hello, world!"
+
+    async def test_prompt_decorator_with_name(self):
+        mcp = FastMCP()
+
+        @mcp.prompt(name="custom_name")
+        def fn() -> str:
+            return "Hello, world!"
+
+        prompts_list = await mcp.list_prompts()
+        assert len(prompts_list) == 1
+        prompt = next(p for p in prompts_list if p.name == "custom_name")
+        assert prompt.name == "custom_name"
+        content = await prompt.render()
+        assert isinstance(content, PromptResult)
+        assert isinstance(content.messages[0].content, TextContent)
+        assert content.messages[0].content.text == "Hello, world!"
+
+    async def test_prompt_decorator_with_description(self):
+        mcp = FastMCP()
+
+        @mcp.prompt(description="A custom description")
+        def fn() -> str:
+            return "Hello, world!"
+
+        prompts_list = await mcp.list_prompts()
+        assert len(prompts_list) == 1
+        prompt = next(p for p in prompts_list if p.name == "fn")
+        assert prompt.description == "A custom description"
+        content = await prompt.render()
+        assert isinstance(content, PromptResult)
+        assert isinstance(content.messages[0].content, TextContent)
+        assert content.messages[0].content.text == "Hello, world!"
+
+    async def test_prompt_decorator_with_parameters(self):
+        mcp = FastMCP()
+
+        @mcp.prompt
+        def test_prompt(name: str, greeting: str = "Hello") -> str:
+            return f"{greeting}, {name}!"
+
+        prompts = await mcp.list_prompts()
+        assert len(prompts) == 1
+        prompt = next(p for p in prompts if p.name == "test_prompt")
+        assert prompt.arguments is not None
+        assert len(prompt.arguments) == 2
+        assert prompt.arguments[0].name == "name"
+        assert prompt.arguments[0].required is True
+        assert prompt.arguments[1].name == "greeting"
+        assert prompt.arguments[1].required is False
+
+        result = await mcp.render_prompt("test_prompt", {"name": "World"})
+        assert len(result.messages) == 1
+        message = result.messages[0]
+        assert isinstance(message.content, TextContent)
+        assert message.content.text == "Hello, World!"
+
+        result = await mcp.render_prompt(
+            "test_prompt", {"name": "World", "greeting": "Hi"}
+        )
+        assert len(result.messages) == 1
+        message = result.messages[0]
+        assert isinstance(message.content, TextContent)
+        assert message.content.text == "Hi, World!"
+
+    async def test_prompt_decorator_instance_method(self):
+        mcp = FastMCP()
+
+        class MyClass:
+            def __init__(self, prefix: str):
+                self.prefix = prefix
+
+            def test_prompt(self) -> str:
+                return f"{self.prefix} Hello, world!"
+
+        obj = MyClass("My prefix:")
+        mcp.add_prompt(Prompt.from_function(obj.test_prompt, name="test_prompt"))
+
+        result = await mcp.render_prompt("test_prompt")
+        assert len(result.messages) == 1
+        message = result.messages[0]
+        assert isinstance(message.content, TextContent)
+        assert message.content.text == "My prefix: Hello, world!"
+
+    async def test_prompt_decorator_classmethod(self):
+        mcp = FastMCP()
+
+        class MyClass:
+            prefix = "Class prefix:"
+
+            @classmethod
+            def test_prompt(cls) -> str:
+                return f"{cls.prefix} Hello, world!"
+
+        mcp.add_prompt(Prompt.from_function(MyClass.test_prompt, name="test_prompt"))
+
+        result = await mcp.render_prompt("test_prompt")
+        assert len(result.messages) == 1
+        message = result.messages[0]
+        assert isinstance(message.content, TextContent)
+        assert message.content.text == "Class prefix: Hello, world!"
+
+    async def test_prompt_decorator_classmethod_error(self):
+        mcp = FastMCP()
+
+        with pytest.raises(TypeError, match="classmethod"):
+
+            class MyClass:
+                @mcp.prompt
+                @classmethod
+                def test_prompt(cls) -> None:
+                    pass
+
+    async def test_prompt_decorator_staticmethod(self):
+        mcp = FastMCP()
+
+        class MyClass:
+            @mcp.prompt
+            @staticmethod
+            def test_prompt() -> str:
+                return "Static Hello, world!"
+
+        result = await mcp.render_prompt("test_prompt")
+        assert len(result.messages) == 1
+        message = result.messages[0]
+        assert isinstance(message.content, TextContent)
+        assert message.content.text == "Static Hello, world!"
+
+    async def test_prompt_decorator_async_function(self):
+        mcp = FastMCP()
+
+        @mcp.prompt
+        async def test_prompt() -> str:
+            return "Async Hello, world!"
+
+        result = await mcp.render_prompt("test_prompt")
+        assert len(result.messages) == 1
+        message = result.messages[0]
+        assert isinstance(message.content, TextContent)
+        assert message.content.text == "Async Hello, world!"
+
+    async def test_prompt_decorator_with_tags(self):
+        """Test that the prompt decorator properly sets tags."""
+        mcp = FastMCP()
+
+        @mcp.prompt(tags={"example", "test-tag"})
+        def sample_prompt() -> str:
+            return "Hello, world!"
+
+        prompts = await mcp.list_prompts()
+        assert len(prompts) == 1
+        prompt = next(p for p in prompts if p.name == "sample_prompt")
+        assert prompt.tags == {"example", "test-tag"}
+
+    async def test_prompt_decorator_with_string_name(self):
+        """Test that @prompt(\"custom_name\") syntax works correctly."""
+        mcp = FastMCP()
+
+        @mcp.prompt("string_named_prompt")
+        def my_function() -> str:
+            """A function with a string name."""
+            return "Hello from string named prompt!"
+
+        prompts = await mcp.list_prompts()
+        assert any(p.name == "string_named_prompt" for p in prompts)
+        assert not any(p.name == "my_function" for p in prompts)
+
+        result = await mcp.render_prompt("string_named_prompt")
+        assert len(result.messages) == 1
+        assert isinstance(result.messages[0].content, TextContent)
+        assert result.messages[0].content.text == "Hello from string named prompt!"
+
+    async def test_prompt_direct_function_call(self):
+        """Test that prompts can be registered via direct function call."""
+        from typing import cast
+
+        from fastmcp.prompts.function_prompt import DecoratedPrompt
+
+        mcp = FastMCP()
+
+        def standalone_function() -> str:
+            """A standalone function to be registered."""
+            return "Hello from direct call!"
+
+        result_fn = mcp.prompt(standalone_function, name="direct_call_prompt")
+
+        # In new decorator mode, returns the function with metadata
+        decorated = cast(DecoratedPrompt, result_fn)
+        assert hasattr(result_fn, "__fastmcp__")
+        assert decorated.__fastmcp__.name == "direct_call_prompt"
+        assert result_fn is standalone_function
+
+        prompts = await mcp.list_prompts()
+        prompt = next(p for p in prompts if p.name == "direct_call_prompt")
+        # Prompt is registered separately, not same object as decorated function
+        assert prompt.name == "direct_call_prompt"
+
+        result = await mcp.render_prompt("direct_call_prompt")
+        assert len(result.messages) == 1
+        assert isinstance(result.messages[0].content, TextContent)
+        assert result.messages[0].content.text == "Hello from direct call!"
+
+    async def test_prompt_decorator_conflicting_names_error(self):
+        """Test that providing both positional and keyword names raises an error."""
+        mcp = FastMCP()
+
+        with pytest.raises(
+            TypeError,
+            match="Cannot specify both a name as first argument and as keyword argument",
+        ):
+
+            @mcp.prompt("positional_name", name="keyword_name")
+            def my_function() -> str:
+                return "Hello, world!"
+
+    async def test_prompt_decorator_staticmethod_order(self):
+        """Test that both decorator orders work for static methods"""
+        mcp = FastMCP()
+
+        class MyClass:
+            @mcp.prompt
+            @staticmethod
+            def test_prompt() -> str:
+                return "Static Hello, world!"
+
+        result = await mcp.render_prompt("test_prompt")
+        assert len(result.messages) == 1
+        message = result.messages[0]
+        assert isinstance(message.content, TextContent)
+        assert message.content.text == "Static Hello, world!"
+
+    async def test_prompt_decorator_with_meta(self):
+        """Test that meta parameter is passed through the prompt decorator."""
+        mcp = FastMCP()
+
+        meta_data = {"version": "3.0", "type": "prompt"}
+
+        @mcp.prompt(meta=meta_data)
+        def test_prompt(message: str) -> str:
+            return f"Response: {message}"
+
+        prompts = await mcp.list_prompts()
+        prompt = next(p for p in prompts if p.name == "test_prompt")
+
+        assert prompt.meta == meta_data
+
+
+class TestPromptEnabled:
+    async def test_toggle_enabled(self):
+        mcp = FastMCP()
+
+        @mcp.prompt
+        def sample_prompt() -> str:
+            return "Hello, world!"
+
+        prompts = await mcp.list_prompts()
+        assert any(p.name == "sample_prompt" for p in prompts)
+
+        mcp.disable(names={"sample_prompt"}, components={"prompt"})
+
+        prompts = await mcp.list_prompts()
+        assert not any(p.name == "sample_prompt" for p in prompts)
+
+        mcp.enable(names={"sample_prompt"}, components={"prompt"})
+
+        prompts = await mcp.list_prompts()
+        assert any(p.name == "sample_prompt" for p in prompts)
+
+    async def test_prompt_disabled(self):
+        mcp = FastMCP()
+
+        @mcp.prompt
+        def sample_prompt() -> str:
+            return "Hello, world!"
+
+        mcp.disable(names={"sample_prompt"}, components={"prompt"})
+        prompts = await mcp.list_prompts()
+        assert len(prompts) == 0
+
+    async def test_prompt_toggle_enabled(self):
+        mcp = FastMCP()
+
+        @mcp.prompt
+        def sample_prompt() -> str:
+            return "Hello, world!"
+
+        mcp.disable(names={"sample_prompt"}, components={"prompt"})
+        prompts = await mcp.list_prompts()
+        assert not any(p.name == "sample_prompt" for p in prompts)
+
+        mcp.enable(names={"sample_prompt"}, components={"prompt"})
+        prompts = await mcp.list_prompts()
+        assert len(prompts) == 1
+
+    async def test_prompt_toggle_disabled(self):
+        mcp = FastMCP()
+
+        @mcp.prompt
+        def sample_prompt() -> str:
+            return "Hello, world!"
+
+        mcp.disable(names={"sample_prompt"}, components={"prompt"})
+        prompts = await mcp.list_prompts()
+        assert len(prompts) == 0
+
+        # get_prompt() applies enabled transform, returns None for disabled
+        prompt = await mcp.get_prompt("sample_prompt")
+        assert prompt is None
+
+    async def test_get_prompt_and_disable(self):
+        mcp = FastMCP()
+
+        @mcp.prompt
+        def sample_prompt() -> str:
+            return "Hello, world!"
+
+        prompt = await mcp.get_prompt("sample_prompt")
+        assert prompt is not None
+
+        mcp.disable(names={"sample_prompt"}, components={"prompt"})
+        prompts = await mcp.list_prompts()
+        assert len(prompts) == 0
+
+        # get_prompt() applies enabled transform, returns None for disabled
+        prompt = await mcp.get_prompt("sample_prompt")
+        assert prompt is None
+
+    async def test_cant_get_disabled_prompt(self):
+        mcp = FastMCP()
+
+        @mcp.prompt
+        def sample_prompt() -> str:
+            return "Hello, world!"
+
+        mcp.disable(names={"sample_prompt"}, components={"prompt"})
+
+        # get_prompt() applies enabled transform, returns None for disabled
+        prompt = await mcp.get_prompt("sample_prompt")
+        assert prompt is None
+
+
+class TestPromptTags:
+    def create_server(self, include_tags=None, exclude_tags=None):
+        mcp = FastMCP()
+
+        @mcp.prompt(tags={"a", "b"})
+        def prompt_1() -> str:
+            return "1"
+
+        @mcp.prompt(tags={"b", "c"})
+        def prompt_2() -> str:
+            return "2"
+
+        if include_tags:
+            mcp.enable(tags=include_tags, only=True)
+        if exclude_tags:
+            mcp.disable(tags=exclude_tags)
+
+        return mcp
+
+    async def test_include_tags_all_prompts(self):
+        mcp = self.create_server(include_tags={"a", "b"})
+        prompts = await mcp.list_prompts()
+        assert {p.name for p in prompts} == {"prompt_1", "prompt_2"}
+
+    async def test_include_tags_some_prompts(self):
+        mcp = self.create_server(include_tags={"a"})
+        prompts = await mcp.list_prompts()
+        assert {p.name for p in prompts} == {"prompt_1"}
+
+    async def test_exclude_tags_all_prompts(self):
+        mcp = self.create_server(exclude_tags={"a", "b"})
+        prompts = await mcp.list_prompts()
+        assert {p.name for p in prompts} == set()
+
+    async def test_exclude_tags_some_prompts(self):
+        mcp = self.create_server(exclude_tags={"a"})
+        prompts = await mcp.list_prompts()
+        assert {p.name for p in prompts} == {"prompt_2"}
+
+    async def test_exclude_takes_precedence_over_include(self):
+        mcp = self.create_server(exclude_tags={"a"}, include_tags={"b"})
+        prompts = await mcp.list_prompts()
+        assert {p.name for p in prompts} == {"prompt_2"}
+
+    async def test_read_prompt_includes_tags(self):
+        mcp = self.create_server(include_tags={"a"})
+        # _get_prompt applies enabled transform (tag filtering)
+        prompt = await mcp._get_prompt("prompt_1")
+        result = await prompt.render({})
+        assert result.messages[0].content.text == "1"
+
+        prompt = await mcp.get_prompt("prompt_2")
+        assert prompt is None
+
+    async def test_read_prompt_excludes_tags(self):
+        mcp = self.create_server(exclude_tags={"a"})
+        # get_prompt applies enabled transform (tag filtering)
+        prompt = await mcp.get_prompt("prompt_1")
+        assert prompt is None
+
+        prompt = await mcp.get_prompt("prompt_2")
+        result = await prompt.render({})
+        assert result.messages[0].content.text == "2"
diff --git a/tests/server/providers/test_local_provider_resources.py b/tests/server/providers/test_local_provider_resources.py
new file mode 100644
index 0000000..0853f4c
--- /dev/null
+++ b/tests/server/providers/test_local_provider_resources.py
@@ -0,0 +1,993 @@
+"""Tests for resource and template behavior in LocalProvider.
+
+Tests cover:
+- Resource context injection
+- Resource templates and URI parsing
+- Resource template context injection
+- Resource decorator patterns
+- Template decorator patterns
+"""
+
+import pytest
+from mcp_types import TextResourceContents
+from pydantic import AnyUrl
+
+from fastmcp import Client, Context, FastMCP
+from fastmcp.exceptions import NotFoundError
+from fastmcp.resources import (
+    Resource,
+    ResourceContent,
+    ResourceResult,
+    ResourceTemplate,
+)
+
+
+class TestResourceContext:
+    async def test_resource_with_context_annotation_gets_context(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://test")
+        def resource_with_context(ctx: Context) -> str:
+            assert isinstance(ctx, Context)
+            return ctx.request_id
+
+        async with Client(mcp) as client:
+            result = await client.read_resource(AnyUrl("resource://test"))
+            assert isinstance(result[0], TextResourceContents)
+            # The exact request_id value depends on the SDK's internal request
+            # sequence; assert only that a request_id was injected into context.
+            assert result[0].text != ""
+
+
+class TestResourceTemplates:
+    async def test_resource_with_params_not_in_uri(self):
+        """Test that a resource with function parameters raises an error if the URI
+        parameters don't match"""
+        mcp = FastMCP()
+
+        with pytest.raises(
+            ValueError,
+            match="URI template must contain at least one parameter",
+        ):
+
+            @mcp.resource("resource://data")
+            def get_data_fn(param: str) -> str:
+                return f"Data: {param}"
+
+    async def test_resource_with_uri_params_without_args(self):
+        """Test that a resource with URI parameters is automatically a template"""
+        mcp = FastMCP()
+
+        with pytest.raises(
+            ValueError,
+            match="URI parameters .* must be a subset of the function arguments",
+        ):
+
+            @mcp.resource("resource://{param}")
+            def get_data() -> str:
+                return "Data"
+
+    async def test_resource_with_untyped_params(self):
+        """Test that a resource with untyped parameters raises an error"""
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{param}")
+        def get_data(param) -> str:
+            return "Data"
+
+    async def test_resource_matching_params(self):
+        """Test that a resource with matching URI and function parameters works"""
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{name}/data")
+        def get_data(name: str) -> str:
+            return f"Data for {name}"
+
+        result = await mcp.read_resource("resource://test/data")
+        assert result.contents[0].content == "Data for test"
+
+    async def test_resource_mismatched_params(self):
+        """Test that mismatched parameters raise an error"""
+        mcp = FastMCP()
+
+        with pytest.raises(
+            ValueError,
+            match="Required function arguments .* must be a subset of the URI path parameters",
+        ):
+
+            @mcp.resource("resource://{name}/data")
+            def get_data(user: str) -> str:
+                return f"Data for {user}"
+
+    async def test_resource_multiple_params(self):
+        """Test that multiple parameters work correctly"""
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{org}/{repo}/data")
+        def get_data(org: str, repo: str) -> str:
+            return f"Data for {org}/{repo}"
+
+        result = await mcp.read_resource("resource://cursor/fastmcp/data")
+        assert result.contents[0].content == "Data for cursor/fastmcp"
+
+    async def test_resource_multiple_mismatched_params(self):
+        """Test that mismatched parameters raise an error"""
+        mcp = FastMCP()
+
+        with pytest.raises(
+            ValueError,
+            match="Required function arguments .* must be a subset of the URI path parameters",
+        ):
+
+            @mcp.resource("resource://{org}/{repo}/data")
+            def get_data_mismatched(org: str, repo_2: str) -> str:
+                return f"Data for {org}"
+
+    async def test_template_with_varkwargs(self):
+        """Test that a template can have **kwargs."""
+        mcp = FastMCP()
+
+        @mcp.resource("test://{x}/{y}/{z}")
+        def func(**kwargs: int) -> str:
+            return str(sum(int(v) for v in kwargs.values()))
+
+        result = await mcp.read_resource("test://1/2/3")
+        assert result.contents[0].content == "6"
+
+    async def test_template_with_default_params(self):
+        """Test that a template can have default parameters."""
+        mcp = FastMCP()
+
+        @mcp.resource("math://add/{x}")
+        def add(x: int, y: int = 10) -> str:
+            return str(int(x) + y)
+
+        templates = await mcp.list_resource_templates()
+        assert len(templates) == 1
+        assert templates[0].uri_template == "math://add/{x}"
+
+        result = await mcp.read_resource("math://add/5")
+        assert result.contents[0].content == "15"
+
+        result2 = await mcp.read_resource("math://add/7")
+        assert result2.contents[0].content == "17"
+
+    async def test_template_to_resource_conversion(self):
+        """Test that a template can be converted to a resource."""
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{name}/data")
+        def get_data(name: str) -> str:
+            return f"Data for {name}"
+
+        templates = await mcp.list_resource_templates()
+        assert len(templates) == 1
+        assert templates[0].uri_template == "resource://{name}/data"
+
+        result = await mcp.read_resource("resource://test/data")
+        assert result.contents[0].content == "Data for test"
+
+    async def test_template_decorator_with_tags(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{param}", tags={"template", "test-tag"})
+        def template_resource(param: str) -> str:
+            return f"Template resource: {param}"
+
+        templates = await mcp.list_resource_templates()
+        template = next(t for t in templates if t.uri_template == "resource://{param}")
+        assert template.tags == {"template", "test-tag"}
+
+    async def test_template_decorator_wildcard_param(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{param*}")
+        def template_resource(param: str) -> str:
+            return f"Template resource: {param}"
+
+        result = await mcp.read_resource("resource://test/data")
+        assert result.contents[0].content == "Template resource: test/data"
+
+    async def test_template_with_query_params(self):
+        """Test RFC 6570 query parameters in resource templates."""
+        mcp = FastMCP()
+
+        @mcp.resource("data://{id}{?format,limit}")
+        def get_data(id: str, format: str = "json", limit: int = 10) -> str:
+            return f"id={id}, format={format}, limit={limit}"
+
+        result = await mcp.read_resource("data://123")
+        assert result.contents[0].content == "id=123, format=json, limit=10"
+
+        result = await mcp.read_resource("data://123?format=xml")
+        assert result.contents[0].content == "id=123, format=xml, limit=10"
+
+        result = await mcp.read_resource("data://123?format=csv&limit=50")
+        assert result.contents[0].content == "id=123, format=csv, limit=50"
+
+    async def test_templates_match_in_order_of_definition(self):
+        """If a wildcard template is defined first, it will take priority."""
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{param*}")
+        def template_resource(param: str) -> str:
+            return f"Template resource 1: {param}"
+
+        @mcp.resource("resource://{x}/{y}")
+        def template_resource_with_params(x: str, y: str) -> str:
+            return f"Template resource 2: {x}/{y}"
+
+        result = await mcp.read_resource("resource://a/b/c")
+        assert result.contents[0].content == "Template resource 1: a/b/c"
+
+        result = await mcp.read_resource("resource://a/b")
+        assert result.contents[0].content == "Template resource 1: a/b"
+
+    async def test_templates_shadow_each_other_reorder(self):
+        """If a wildcard template is defined second, it will *not* take priority."""
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{x}/{y}")
+        def template_resource_with_params(x: str, y: str) -> str:
+            return f"Template resource 1: {x}/{y}"
+
+        @mcp.resource("resource://{param*}")
+        def template_resource(param: str) -> str:
+            return f"Template resource 2: {param}"
+
+        result = await mcp.read_resource("resource://a/b/c")
+        assert result.contents[0].content == "Template resource 2: a/b/c"
+
+        result = await mcp.read_resource("resource://a/b")
+        assert result.contents[0].content == "Template resource 1: a/b"
+
+    async def test_resource_template_with_annotations(self):
+        """Test that resource template annotations are visible.
+
+        SDK v2's `Annotations` model is strict (audience/priority/last_modified);
+        arbitrary keys are no longer retained, so annotations are exercised with
+        the spec-defined fields.
+        """
+        mcp = FastMCP()
+
+        @mcp.resource(
+            "api://users/{user_id}",
+            annotations={"audience": ["user"], "priority": 0.5},
+        )
+        def get_user(user_id: str) -> str:
+            return f"User {user_id} data"
+
+        templates = await mcp.list_resource_templates()
+        assert len(templates) == 1
+
+        template = templates[0]
+        assert template.uri_template == "api://users/{user_id}"
+
+        assert template.annotations is not None
+        assert template.annotations.audience == ["user"]
+        assert template.annotations.priority == 0.5
+
+
+class TestResourceTemplateContext:
+    async def test_resource_template_context(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{param}")
+        def resource_template(param: str, ctx: Context) -> str:
+            assert isinstance(ctx, Context)
+            return f"Resource template: {param} {ctx.request_id}"
+
+        async with Client(mcp) as client:
+            result = await client.read_resource(AnyUrl("resource://test"))
+            assert isinstance(result[0], TextResourceContents)
+            # The exact request_id depends on the SDK's internal request
+            # sequence; assert context injection produced the templated value.
+            assert result[0].text.startswith("Resource template: test ")
+
+    async def test_resource_template_context_with_callable_object(self):
+        mcp = FastMCP()
+
+        class MyResource:
+            def __call__(self, param: str, ctx: Context) -> str:
+                return f"Resource template: {param} {ctx.request_id}"
+
+        template = ResourceTemplate.from_function(
+            MyResource(), uri_template="resource://{param}"
+        )
+        mcp.add_template(template)
+
+        async with Client(mcp) as client:
+            result = await client.read_resource(AnyUrl("resource://test"))
+            assert isinstance(result[0], TextResourceContents)
+            # The exact request_id depends on the SDK's internal request
+            # sequence; assert context injection produced the templated value.
+            assert result[0].text.startswith("Resource template: test ")
+
+
+class TestResourceDecorator:
+    async def test_no_resources_before_decorator(self):
+        mcp = FastMCP()
+
+        with pytest.raises(NotFoundError, match="Unknown resource"):
+            await mcp.read_resource("resource://data")
+
+    async def test_resource_decorator(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://data")
+        def get_data() -> str:
+            return "Hello, world!"
+
+        result = await mcp.read_resource("resource://data")
+        assert result.contents[0].content == "Hello, world!"
+
+    async def test_resource_decorator_incorrect_usage(self):
+        mcp = FastMCP()
+
+        with pytest.raises(
+            TypeError, match="The @resource decorator was used incorrectly"
+        ):
+
+            @mcp.resource  # Missing parentheses #type: ignore
+            def get_data() -> str:
+                return "Hello, world!"
+
+    async def test_resource_decorator_with_name(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://data", name="custom-data")
+        def get_data() -> str:
+            return "Hello, world!"
+
+        resources = await mcp.list_resources()
+        assert len(resources) == 1
+        assert resources[0].name == "custom-data"
+
+        result = await mcp.read_resource("resource://data")
+        assert result.contents[0].content == "Hello, world!"
+
+    async def test_resource_decorator_with_description(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://data", description="Data resource")
+        def get_data() -> str:
+            return "Hello, world!"
+
+        resources = await mcp.list_resources()
+        assert len(resources) == 1
+        assert resources[0].description == "Data resource"
+
+    async def test_resource_decorator_with_tags(self):
+        """Test that the resource decorator properly sets tags."""
+        mcp = FastMCP()
+
+        @mcp.resource("resource://data", tags={"example", "test-tag"})
+        def get_data() -> str:
+            return "Hello, world!"
+
+        resources = await mcp.list_resources()
+        assert len(resources) == 1
+        assert resources[0].tags == {"example", "test-tag"}
+
+    async def test_resource_decorator_instance_method(self):
+        mcp = FastMCP()
+
+        class MyClass:
+            def __init__(self, prefix: str):
+                self.prefix = prefix
+
+            def get_data(self) -> str:
+                return f"{self.prefix} Hello, world!"
+
+        obj = MyClass("My prefix:")
+
+        mcp.add_resource(
+            Resource.from_function(
+                obj.get_data, uri="resource://data", name="instance-resource"
+            )
+        )
+
+        result = await mcp.read_resource("resource://data")
+        assert result.contents[0].content == "My prefix: Hello, world!"
+
+    async def test_resource_decorator_classmethod(self):
+        mcp = FastMCP()
+
+        class MyClass:
+            prefix = "Class prefix:"
+
+            @classmethod
+            def get_data(cls) -> str:
+                return f"{cls.prefix} Hello, world!"
+
+        mcp.add_resource(
+            Resource.from_function(
+                MyClass.get_data, uri="resource://data", name="class-resource"
+            )
+        )
+
+        result = await mcp.read_resource("resource://data")
+        assert result.contents[0].content == "Class prefix: Hello, world!"
+
+    async def test_resource_decorator_classmethod_error(self):
+        mcp = FastMCP()
+
+        with pytest.raises(TypeError, match="classmethod"):
+
+            class MyClass:
+                @mcp.resource("resource://data")
+                @classmethod
+                def get_data(cls) -> None:
+                    pass
+
+    async def test_resource_decorator_staticmethod(self):
+        mcp = FastMCP()
+
+        class MyClass:
+            @mcp.resource("resource://data")
+            @staticmethod
+            def get_data() -> str:
+                return "Static Hello, world!"
+
+        result = await mcp.read_resource("resource://data")
+        assert result.contents[0].content == "Static Hello, world!"
+
+    async def test_resource_decorator_async_function(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://data")
+        async def get_data() -> str:
+            return "Async Hello, world!"
+
+        result = await mcp.read_resource("resource://data")
+        assert result.contents[0].content == "Async Hello, world!"
+
+    async def test_resource_decorator_staticmethod_order(self):
+        """Test that both decorator orders work for static methods"""
+        mcp = FastMCP()
+
+        class MyClass:
+            @mcp.resource("resource://data")
+            @staticmethod
+            def get_data() -> str:
+                return "Static Hello, world!"
+
+        result = await mcp.read_resource("resource://data")
+        assert result.contents[0].content == "Static Hello, world!"
+
+    async def test_resource_decorator_with_meta(self):
+        """Test that meta parameter is passed through the resource decorator."""
+        mcp = FastMCP()
+
+        meta_data = {"version": "1.0", "author": "test"}
+
+        @mcp.resource("resource://data", meta=meta_data)
+        def get_data() -> str:
+            return "Hello, world!"
+
+        resources = await mcp.list_resources()
+        resource = next(r for r in resources if str(r.uri) == "resource://data")
+
+        assert resource.meta == meta_data
+
+    async def test_resource_content_with_meta_in_response(self):
+        """Test that ResourceContent meta is passed through."""
+        mcp = FastMCP()
+
+        @mcp.resource("resource://widget")
+        def get_widget() -> ResourceResult:
+            return ResourceResult(
+                [
+                    ResourceContent(
+                        content="<widget>content</widget>",
+                        mime_type="text/html",
+                        meta={"csp": "script-src 'self'", "version": "1.0"},
+                    )
+                ]
+            )
+
+        result = await mcp.read_resource("resource://widget")
+        assert len(result.contents) == 1
+        assert result.contents[0].content == "<widget>content</widget>"
+        assert result.contents[0].mime_type == "text/html"
+        assert result.contents[0].meta == {"csp": "script-src 'self'", "version": "1.0"}
+
+    async def test_resource_content_binary_with_meta(self):
+        """Test that ResourceContent with binary content and meta works."""
+        mcp = FastMCP()
+
+        @mcp.resource("resource://binary")
+        def get_binary() -> ResourceResult:
+            return ResourceResult(
+                [
+                    ResourceContent(
+                        content=b"\x00\x01\x02",
+                        meta={"encoding": "raw"},
+                    )
+                ]
+            )
+
+        result = await mcp.read_resource("resource://binary")
+        assert len(result.contents) == 1
+        assert result.contents[0].content == b"\x00\x01\x02"
+        assert result.contents[0].meta == {"encoding": "raw"}
+
+    async def test_resource_content_without_meta(self):
+        """Test that ResourceContent without meta works (meta is None)."""
+        mcp = FastMCP()
+
+        @mcp.resource("resource://plain")
+        def get_plain() -> ResourceResult:
+            return ResourceResult([ResourceContent(content="plain content")])
+
+        result = await mcp.read_resource("resource://plain")
+        assert len(result.contents) == 1
+        assert result.contents[0].content == "plain content"
+        assert result.contents[0].meta is None
+
+
+class TestTemplateDecorator:
+    async def test_template_decorator(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{name}/data")
+        def get_data(name: str) -> str:
+            return f"Data for {name}"
+
+        templates = await mcp.list_resource_templates()
+        assert len(templates) == 1
+        assert templates[0].name == "get_data"
+        assert templates[0].uri_template == "resource://{name}/data"
+
+        result = await mcp.read_resource("resource://test/data")
+        assert result.contents[0].content == "Data for test"
+
+    async def test_template_decorator_incorrect_usage(self):
+        mcp = FastMCP()
+
+        with pytest.raises(
+            TypeError, match="The @resource decorator was used incorrectly"
+        ):
+
+            @mcp.resource  # Missing parentheses #type: ignore
+            def get_data(name: str) -> str:
+                return f"Data for {name}"
+
+    async def test_template_decorator_with_name(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{name}/data", name="custom-template")
+        def get_data(name: str) -> str:
+            return f"Data for {name}"
+
+        templates = await mcp.list_resource_templates()
+        assert len(templates) == 1
+        assert templates[0].name == "custom-template"
+
+        result = await mcp.read_resource("resource://test/data")
+        assert result.contents[0].content == "Data for test"
+
+    async def test_template_decorator_with_description(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{name}/data", description="Template description")
+        def get_data(name: str) -> str:
+            return f"Data for {name}"
+
+        templates = await mcp.list_resource_templates()
+        assert len(templates) == 1
+        assert templates[0].description == "Template description"
+
+    async def test_template_decorator_instance_method(self):
+        mcp = FastMCP()
+
+        class MyClass:
+            def __init__(self, prefix: str):
+                self.prefix = prefix
+
+            def get_data(self, name: str) -> str:
+                return f"{self.prefix} Data for {name}"
+
+        obj = MyClass("My prefix:")
+        template = ResourceTemplate.from_function(
+            obj.get_data,
+            uri_template="resource://{name}/data",
+            name="instance-template",
+        )
+        mcp.add_template(template)
+
+        result = await mcp.read_resource("resource://test/data")
+        assert result.contents[0].content == "My prefix: Data for test"
+
+    async def test_template_decorator_classmethod(self):
+        mcp = FastMCP()
+
+        class MyClass:
+            prefix = "Class prefix:"
+
+            @classmethod
+            def get_data(cls, name: str) -> str:
+                return f"{cls.prefix} Data for {name}"
+
+        template = ResourceTemplate.from_function(
+            MyClass.get_data,
+            uri_template="resource://{name}/data",
+            name="class-template",
+        )
+        mcp.add_template(template)
+
+        result = await mcp.read_resource("resource://test/data")
+        assert result.contents[0].content == "Class prefix: Data for test"
+
+    async def test_template_decorator_staticmethod(self):
+        mcp = FastMCP()
+
+        class MyClass:
+            @mcp.resource("resource://{name}/data")
+            @staticmethod
+            def get_data(name: str) -> str:
+                return f"Static Data for {name}"
+
+        result = await mcp.read_resource("resource://test/data")
+        assert result.contents[0].content == "Static Data for test"
+
+    async def test_template_decorator_async_function(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{name}/data")
+        async def get_data(name: str) -> str:
+            return f"Async Data for {name}"
+
+        result = await mcp.read_resource("resource://test/data")
+        assert result.contents[0].content == "Async Data for test"
+
+    async def test_template_decorator_with_tags(self):
+        """Test that the template decorator properly sets tags."""
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{param}", tags={"template", "test-tag"})
+        def template_resource(param: str) -> str:
+            return f"Template resource: {param}"
+
+        templates = await mcp.list_resource_templates()
+        template = next(t for t in templates if t.uri_template == "resource://{param}")
+        assert template.tags == {"template", "test-tag"}
+
+    async def test_template_decorator_wildcard_param(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{param*}")
+        def template_resource(param: str) -> str:
+            return f"Template resource: {param}"
+
+        templates = await mcp.list_resource_templates()
+        template = next(t for t in templates if t.uri_template == "resource://{param*}")
+        assert template.uri_template == "resource://{param*}"
+        assert template.name == "template_resource"
+
+    async def test_template_decorator_with_meta(self):
+        """Test that meta parameter is passed through the template decorator."""
+        mcp = FastMCP()
+
+        meta_data = {"version": "2.0", "template": "test"}
+
+        @mcp.resource("resource://{param}/data", meta=meta_data)
+        def get_template_data(param: str) -> str:
+            return f"Data for {param}"
+
+        templates = await mcp.list_resource_templates()
+        template = next(
+            t for t in templates if t.uri_template == "resource://{param}/data"
+        )
+
+        assert template.meta == meta_data
+
+
+class TestResourceTags:
+    def create_server(self, include_tags=None, exclude_tags=None):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://1", tags={"a", "b"})
+        def resource_1() -> str:
+            return "1"
+
+        @mcp.resource("resource://2", tags={"b", "c"})
+        def resource_2() -> str:
+            return "2"
+
+        if include_tags:
+            mcp.enable(tags=include_tags, only=True)
+        if exclude_tags:
+            mcp.disable(tags=exclude_tags)
+
+        return mcp
+
+    async def test_include_tags_all_resources(self):
+        mcp = self.create_server(include_tags={"a", "b"})
+        resources = await mcp.list_resources()
+        assert {r.name for r in resources} == {"resource_1", "resource_2"}
+
+    async def test_include_tags_some_resources(self):
+        mcp = self.create_server(include_tags={"a", "z"})
+        resources = await mcp.list_resources()
+        assert {r.name for r in resources} == {"resource_1"}
+
+    async def test_exclude_tags_all_resources(self):
+        mcp = self.create_server(exclude_tags={"a", "b"})
+        resources = await mcp.list_resources()
+        assert {r.name for r in resources} == set()
+
+    async def test_exclude_tags_some_resources(self):
+        mcp = self.create_server(exclude_tags={"a"})
+        resources = await mcp.list_resources()
+        assert {r.name for r in resources} == {"resource_2"}
+
+    async def test_exclude_precedence(self):
+        mcp = self.create_server(exclude_tags={"a"}, include_tags={"b"})
+        resources = await mcp.list_resources()
+        assert {r.name for r in resources} == {"resource_2"}
+
+    async def test_read_included_resource(self):
+        mcp = self.create_server(include_tags={"a"})
+        result = await mcp.read_resource("resource://1")
+        assert result.contents[0].content == "1"
+
+        with pytest.raises(NotFoundError, match="Unknown resource"):
+            await mcp.read_resource("resource://2")
+
+    async def test_read_excluded_resource(self):
+        mcp = self.create_server(exclude_tags={"a"})
+        with pytest.raises(NotFoundError, match="Unknown resource"):
+            await mcp.read_resource("resource://1")
+
+
+class TestResourceEnabled:
+    async def test_toggle_enabled(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://data")
+        def sample_resource() -> str:
+            return "Hello, world!"
+
+        resources = await mcp.list_resources()
+        assert any(str(r.uri) == "resource://data" for r in resources)
+
+        mcp.disable(names={"resource://data"}, components={"resource"})
+
+        resources = await mcp.list_resources()
+        assert not any(str(r.uri) == "resource://data" for r in resources)
+
+        mcp.enable(names={"resource://data"}, components={"resource"})
+
+        resources = await mcp.list_resources()
+        assert any(str(r.uri) == "resource://data" for r in resources)
+
+    async def test_resource_disabled(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://data")
+        def sample_resource() -> str:
+            return "Hello, world!"
+
+        mcp.disable(names={"resource://data"}, components={"resource"})
+        resources = await mcp.list_resources()
+        assert len(resources) == 0
+
+        with pytest.raises(NotFoundError, match="Unknown resource"):
+            await mcp.read_resource("resource://data")
+
+    async def test_resource_toggle_enabled(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://data")
+        def sample_resource() -> str:
+            return "Hello, world!"
+
+        mcp.disable(names={"resource://data"}, components={"resource"})
+        resources = await mcp.list_resources()
+        assert not any(str(r.uri) == "resource://data" for r in resources)
+
+        mcp.enable(names={"resource://data"}, components={"resource"})
+        resources = await mcp.list_resources()
+        assert len(resources) == 1
+
+    async def test_resource_toggle_disabled(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://data")
+        def sample_resource() -> str:
+            return "Hello, world!"
+
+        mcp.disable(names={"resource://data"}, components={"resource"})
+        resources = await mcp.list_resources()
+        assert len(resources) == 0
+
+        with pytest.raises(NotFoundError, match="Unknown resource"):
+            await mcp.read_resource("resource://data")
+
+    async def test_get_resource_and_disable(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://data")
+        def sample_resource() -> str:
+            return "Hello, world!"
+
+        resource = await mcp.get_resource("resource://data")
+        assert resource is not None
+
+        mcp.disable(names={"resource://data"}, components={"resource"})
+        resources = await mcp.list_resources()
+        assert len(resources) == 0
+
+        with pytest.raises(NotFoundError, match="Unknown resource"):
+            await mcp.read_resource("resource://data")
+
+    async def test_cant_read_disabled_resource(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://data")
+        def sample_resource() -> str:
+            return "Hello, world!"
+
+        mcp.disable(names={"resource://data"}, components={"resource"})
+
+        with pytest.raises(NotFoundError, match="Unknown resource"):
+            await mcp.read_resource("resource://data")
+
+
+class TestResourceTemplatesTags:
+    def create_server(self, include_tags=None, exclude_tags=None):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://1/{param}", tags={"a", "b"})
+        def template_resource_1(param: str) -> str:
+            return f"Template resource 1: {param}"
+
+        @mcp.resource("resource://2/{param}", tags={"b", "c"})
+        def template_resource_2(param: str) -> str:
+            return f"Template resource 2: {param}"
+
+        if include_tags:
+            mcp.enable(tags=include_tags, only=True)
+        if exclude_tags:
+            mcp.disable(tags=exclude_tags)
+
+        return mcp
+
+    async def test_include_tags_all_resources(self):
+        mcp = self.create_server(include_tags={"a", "b"})
+        templates = await mcp.list_resource_templates()
+        assert {t.name for t in templates} == {
+            "template_resource_1",
+            "template_resource_2",
+        }
+
+    async def test_include_tags_some_resources(self):
+        mcp = self.create_server(include_tags={"a"})
+        templates = await mcp.list_resource_templates()
+        assert {t.name for t in templates} == {"template_resource_1"}
+
+    async def test_exclude_tags_all_resources(self):
+        mcp = self.create_server(exclude_tags={"a", "b"})
+        templates = await mcp.list_resource_templates()
+        assert {t.name for t in templates} == set()
+
+    async def test_exclude_tags_some_resources(self):
+        mcp = self.create_server(exclude_tags={"a"})
+        templates = await mcp.list_resource_templates()
+        assert {t.name for t in templates} == {"template_resource_2"}
+
+    async def test_exclude_takes_precedence_over_include(self):
+        mcp = self.create_server(exclude_tags={"a"}, include_tags={"b"})
+        templates = await mcp.list_resource_templates()
+        assert {t.name for t in templates} == {"template_resource_2"}
+
+    async def test_read_resource_template_includes_tags(self):
+        mcp = self.create_server(include_tags={"a"})
+        result = await mcp.read_resource("resource://1/x")
+        assert result.contents[0].content == "Template resource 1: x"
+
+        with pytest.raises(NotFoundError, match="Unknown resource"):
+            await mcp.read_resource("resource://2/x")
+
+    async def test_read_resource_template_excludes_tags(self):
+        mcp = self.create_server(exclude_tags={"a"})
+        with pytest.raises(NotFoundError, match="Unknown resource"):
+            await mcp.read_resource("resource://1/x")
+
+        result = await mcp.read_resource("resource://2/x")
+        assert result.contents[0].content == "Template resource 2: x"
+
+
+class TestResourceTemplateEnabled:
+    async def test_toggle_enabled(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{param}")
+        def sample_template(param: str) -> str:
+            return f"Template: {param}"
+
+        templates = await mcp.list_resource_templates()
+        assert any(t.uri_template == "resource://{param}" for t in templates)
+
+        mcp.disable(names={"resource://{param}"}, components={"template"})
+
+        templates = await mcp.list_resource_templates()
+        assert not any(t.uri_template == "resource://{param}" for t in templates)
+
+        mcp.enable(names={"resource://{param}"}, components={"template"})
+
+        templates = await mcp.list_resource_templates()
+        assert any(t.uri_template == "resource://{param}" for t in templates)
+
+    async def test_template_disabled(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{param}")
+        def sample_template(param: str) -> str:
+            return f"Template: {param}"
+
+        mcp.disable(names={"resource://{param}"}, components={"template"})
+        templates = await mcp.list_resource_templates()
+        assert len(templates) == 0
+
+        with pytest.raises(NotFoundError, match="Unknown resource"):
+            await mcp.read_resource("resource://test")
+
+    async def test_template_toggle_enabled(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{param}")
+        def sample_template(param: str) -> str:
+            return f"Template: {param}"
+
+        mcp.disable(names={"resource://{param}"}, components={"template"})
+        templates = await mcp.list_resource_templates()
+        assert not any(t.uri_template == "resource://{param}" for t in templates)
+
+        mcp.enable(names={"resource://{param}"}, components={"template"})
+        templates = await mcp.list_resource_templates()
+        assert len(templates) == 1
+
+    async def test_template_toggle_disabled(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{param}")
+        def sample_template(param: str) -> str:
+            return f"Template: {param}"
+
+        mcp.disable(names={"resource://{param}"}, components={"template"})
+        templates = await mcp.list_resource_templates()
+        assert len(templates) == 0
+
+        with pytest.raises(NotFoundError, match="Unknown resource"):
+            await mcp.read_resource("resource://test")
+
+    async def test_get_template_and_disable(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{param}")
+        def sample_template(param: str) -> str:
+            return f"Template: {param}"
+
+        template = await mcp.get_resource_template("resource://{param}")
+        assert template is not None
+
+        mcp.disable(names={"resource://{param}"}, components={"template"})
+        templates = await mcp.list_resource_templates()
+        assert len(templates) == 0
+
+        with pytest.raises(NotFoundError, match="Unknown resource"):
+            await mcp.read_resource("resource://test")
+
+    async def test_cant_read_disabled_template(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://{param}")
+        def sample_template(param: str) -> str:
+            return f"Template: {param}"
+
+        mcp.disable(names={"resource://{param}"}, components={"template"})
+
+        with pytest.raises(NotFoundError, match="Unknown resource"):
+            await mcp.read_resource("resource://test")
diff --git a/tests/server/providers/test_prefab_roundtrip.py b/tests/server/providers/test_prefab_roundtrip.py
new file mode 100644
index 0000000..7294691
--- /dev/null
+++ b/tests/server/providers/test_prefab_roundtrip.py
@@ -0,0 +1,185 @@
+"""End-to-end round-trip tests for Prefab peer-tool references.
+
+These simulate what a real host does: call the UI tool, extract the
+hashed backend-tool name from structured_content, call back with
+that name, and verify the backend tool actually executes. Covers
+single-server, namespaced mounts, and cross-server mounts.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from fastmcp import FastMCP, FastMCPApp
+from fastmcp.server.providers.addressing import hashed_backend_name
+
+prefab_ui = pytest.importorskip("prefab_ui")
+from prefab_ui.actions.mcp import CallTool  # noqa: E402
+from prefab_ui.components import Button, Column, Text  # noqa: E402
+
+
+class TestSingleServerRoundTrip:
+    async def test_ui_tool_serializes_hashed_peer_reference(self):
+        """The resolver converts a CallTool string reference to a hashed
+        name that appears in the tool result's structured_content."""
+        app = FastMCPApp("contacts")
+
+        @app.tool()
+        def save_contact(name: str) -> str:
+            return f"saved {name}"
+
+        @app.ui()
+        def contact_form() -> Column:
+            return Column(
+                children=[Button(label="Save", on_click=CallTool(tool="save_contact"))]
+            )
+
+        server = FastMCP("Platform")
+        server.add_provider(app)
+
+        result = await server.call_tool("contact_form", {})
+        assert result.structured_content is not None
+
+        # The hashed name should appear somewhere in the serialized output.
+        sc_json = json.dumps(result.structured_content)
+        expected_hash = hashed_backend_name("contacts", "save_contact")
+        assert expected_hash in sc_json, (
+            f"Expected {expected_hash!r} in structured_content but got: {sc_json[:200]}"
+        )
+
+    async def test_hashed_name_from_result_is_callable(self):
+        """The hashed name that appears in structured_content actually
+        resolves when called back — the full round-trip works."""
+        app = FastMCPApp("contacts")
+
+        @app.tool()
+        def save_contact(name: str) -> str:
+            return f"saved {name}"
+
+        @app.ui()
+        def contact_form() -> Column:
+            return Column(
+                children=[Button(label="Save", on_click=CallTool(tool="save_contact"))]
+            )
+
+        server = FastMCP("Platform")
+        server.add_provider(app)
+
+        # Step 1: call UI tool, get structured_content with hashed ref
+        await server.call_tool("contact_form", {})
+
+        # Step 2: call the backend tool by its hashed name
+        hashed_name = hashed_backend_name("contacts", "save_contact")
+        backend_result = await server.call_tool(hashed_name, {"name": "Alice"})
+        assert backend_result.content[0].text == "saved Alice"  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+
+
+class TestNamespacedMountRoundTrip:
+    async def test_namespaced_app_backend_tool_round_trip(self):
+        """A FastMCPApp mounted with a namespace: the UI tool is called
+        by its namespaced display name, the backend tool is called by
+        its hashed name — both work."""
+        app = FastMCPApp("crm")
+
+        @app.tool()
+        def save(name: str) -> str:
+            return f"saved {name}"
+
+        @app.ui()
+        def form() -> Text:
+            return Text(content="Enter details")
+
+        server = FastMCP("Platform")
+        server.add_provider(app, namespace="crm")
+
+        # UI tool visible under namespace
+        result = await server.call_tool("crm_form", {})
+        assert result.structured_content is not None
+
+        # Backend tool reachable via hash
+        hashed_name = hashed_backend_name("crm", "save")
+        backend_result = await server.call_tool(hashed_name, {"name": "Bob"})
+        assert backend_result.content[0].text == "saved Bob"  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+
+
+class TestMountedServerRoundTrip:
+    async def test_backend_tool_reachable_through_mounted_server(self):
+        """A FastMCPApp inside a mounted FastMCP server: the outer
+        server's dispatcher walks through FastMCPProvider to find
+        the backend tool by hash."""
+        app = FastMCPApp("contacts")
+
+        @app.tool()
+        def save(name: str) -> str:
+            return f"saved {name}"
+
+        @app.ui()
+        def form() -> Text:
+            return Text(content="Form")
+
+        inner = FastMCP("Inner")
+        inner.add_provider(app)
+
+        outer = FastMCP("Outer")
+        outer.mount(inner, namespace="inner")
+
+        # Backend tool callable through the mount via hash dispatch
+        hashed_name = hashed_backend_name("contacts", "save")
+        result = await outer.call_tool(hashed_name, {"name": "Carol"})
+        assert result.content[0].text == "saved Carol"  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+
+
+class TestDynamicToolAdd:
+    async def test_tool_added_after_first_call_is_reachable(self):
+        """Tools added to an already-mounted app after the first call
+        are still reachable via their hashed name — get_tool_by_hash
+        does a live walk, not a cached lookup."""
+        app = FastMCPApp("contacts")
+
+        server = FastMCP("Platform")
+        server.add_provider(app)
+
+        # First call — nothing to call yet, just prime any caches.
+        tools = await server.list_tools()
+        assert len(tools) == 0
+
+        # Now add a backend tool dynamically.
+        @app.tool()
+        def save(name: str) -> str:
+            return f"saved {name}"
+
+        # The dynamically-added tool should be reachable.
+        hashed_name = hashed_backend_name("contacts", "save")
+        result = await server.call_tool(hashed_name, {"name": "Dan"})
+        assert result.content[0].text == "saved Dan"  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+
+
+class TestCollision:
+    async def test_same_app_name_same_tool_name_first_wins(self):
+        """Two apps with the same name and same tool name: the hash is
+        identical, so get_tool_by_hash returns the first match. This is
+        the same first-match behavior the old get_app_tool had."""
+        app_a = FastMCPApp("shared")
+        app_b = FastMCPApp("shared")
+
+        @app_a.tool()
+        def save(name: str) -> str:
+            return f"from A: {name}"
+
+        @app_b.tool()
+        def save_b(name: str) -> str:
+            return f"from B: {name}"
+
+        # Register under a different local tool name to avoid
+        # actual collision at the provider level. The hash collision
+        # only happens when both app name AND tool name match.
+        # This test just verifies one app's tool is reachable.
+        server = FastMCP("Platform")
+        server.add_provider(app_a)
+        server.add_provider(app_b)
+
+        hashed_name = hashed_backend_name("shared", "save")
+        result = await server.call_tool(hashed_name, {"name": "Eve"})
+        assert result.content[0].text == "from A: Eve"  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
diff --git a/tests/server/providers/test_prefab_synthesis.py b/tests/server/providers/test_prefab_synthesis.py
new file mode 100644
index 0000000..1a84ac0
--- /dev/null
+++ b/tests/server/providers/test_prefab_synthesis.py
@@ -0,0 +1,198 @@
+"""End-to-end tests for the on-demand Prefab renderer synthesis.
+
+The whole architecture exists to fix #3735 / PR #3754: a user passing a
+``PrefabAppConfig(csp=ResourceCSP(frame_domains=[...]))`` should see
+their ``frame_domains`` actually arrive on the renderer resource's CSP,
+and CSP should NOT leak into the tool's wire metadata. These tests
+exercise the synthesis path directly through the public server API.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from fastmcp import FastMCP, FastMCPApp
+
+prefab_ui = pytest.importorskip("prefab_ui")
+from fastmcp.apps.config import PrefabAppConfig, ResourceCSP  # noqa: E402
+
+
+class TestUserCSPReachesResource:
+    """The original bug: user CSP must land on the resource, not vanish."""
+
+    async def test_frame_domains_reach_resource(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool(
+            app=PrefabAppConfig(
+                csp=ResourceCSP(frame_domains=["https://example1234.com"])
+            )
+        )
+        def show_widget() -> str:
+            return "widget"
+
+        # Find the synthesized prefab resource for this tool.
+        resources = list(await mcp.list_resources())
+        renderer = next((r for r in resources if "prefab/tool" in str(r.uri)), None)
+        assert renderer is not None, "no prefab resource was synthesized"
+        assert renderer.meta is not None
+
+        csp = renderer.meta["ui"]["csp"]
+        assert "https://example1234.com" in csp.get("frameDomains", []), (
+            f"frame_domains missing from resource CSP: {csp}"
+        )
+
+    async def test_all_four_domain_fields_preserved(self):
+        """The old singleton silently dropped frame_domains and
+        base_uri_domains; the synthesizer covers all four fields."""
+        mcp = FastMCP("test")
+
+        @mcp.tool(
+            app=PrefabAppConfig(
+                csp=ResourceCSP(
+                    connect_domains=["https://api.example.com"],
+                    resource_domains=["https://cdn.example.com"],
+                    frame_domains=["https://embed.example.com"],
+                    base_uri_domains=["https://base.example.com"],
+                )
+            )
+        )
+        def widget() -> str:
+            return "x"
+
+        resources = list(await mcp.list_resources())
+        renderer = next(r for r in resources if "prefab/tool" in str(r.uri))
+        assert renderer.meta is not None
+        csp = renderer.meta["ui"]["csp"]
+
+        assert "https://api.example.com" in csp.get("connectDomains", [])
+        assert "https://cdn.example.com" in csp.get("resourceDomains", [])
+        assert "https://embed.example.com" in csp.get("frameDomains", [])
+        assert "https://base.example.com" in csp.get("baseUriDomains", [])
+
+
+class TestCSPStrippedFromToolMeta:
+    """CSP belongs on the resource, not the tool. The wire format that
+    clients see for tools must not contain it."""
+
+    async def test_csp_not_in_listed_tool_meta(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool(
+            app=PrefabAppConfig(csp=ResourceCSP(frame_domains=["https://example.com"]))
+        )
+        def show_widget() -> str:
+            return "widget"
+
+        tools = list(await mcp.list_tools())
+        tool = next(t for t in tools if t.name == "show_widget")
+        assert tool.meta is not None
+        ui = tool.meta["ui"]
+        assert "csp" not in ui, f"csp leaked into tool meta: {ui}"
+        assert "permissions" not in ui
+
+
+class TestPerToolURIs:
+    """Each prefab tool gets its own URI — distinct CSP per tool becomes
+    possible because no two tools share a renderer resource."""
+
+    async def test_two_tools_get_distinct_uris(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool(app=True)
+        def tool_a() -> str:
+            return "a"
+
+        @mcp.tool(app=True)
+        def tool_b() -> str:
+            return "b"
+
+        tools = list(await mcp.list_tools())
+        a = next(t for t in tools if t.name == "tool_a")
+        b = next(t for t in tools if t.name == "tool_b")
+        assert a.meta is not None
+        assert b.meta is not None
+        uri_a = a.meta["ui"]["resourceUri"]
+        uri_b = b.meta["ui"]["resourceUri"]
+        assert uri_a != uri_b
+        assert uri_a.startswith("ui://prefab/tool/")
+        assert uri_b.startswith("ui://prefab/tool/")
+
+
+class TestFastMCPAppMounts:
+    """Tools inside FastMCPApps get URIs derived from the app's mount address."""
+
+    async def test_app_tool_uri_uses_address(self):
+        app = FastMCPApp("dashboard")
+
+        @app.ui()
+        def show() -> str:
+            return "rendered"
+
+        mcp = FastMCP("Platform")
+        mcp.add_provider(app)
+
+        resources = list(await mcp.list_resources())
+        prefab = [r for r in resources if "prefab/tool" in str(r.uri)]
+        assert len(prefab) == 1
+
+    async def test_namespaced_mount_still_synthesizes_resource(self):
+        app = FastMCPApp("crm")
+
+        @app.ui()
+        def contact_form() -> str:
+            return "form"
+
+        mcp = FastMCP("Platform")
+        mcp.add_provider(app, namespace="customers")
+
+        resources = list(await mcp.list_resources())
+        prefab = [r for r in resources if "prefab/tool" in str(r.uri)]
+        assert len(prefab) == 1
+
+
+class TestReadResource:
+    """The synthesized resources are actually fetchable via read_resource."""
+
+    async def test_read_resource_returns_renderer_html(self):
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool(app=True)
+        def my_tool() -> str:
+            return "hi"
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            uri = next(t for t in tools if t.name == "my_tool").meta["ui"][
+                "resourceUri"
+            ]
+            contents = await client.read_resource(uri)
+
+        assert len(contents) > 0
+        text = contents[0].text if hasattr(contents[0], "text") else ""
+        assert "<html" in text.lower() or "<!doctype" in text.lower()
+
+
+class TestNonPrefabToolsUntouched:
+    async def test_plain_tool_has_no_ui_meta(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def greet(name: str) -> str:
+            return name
+
+        tools = list(await mcp.list_tools())
+        tool = next(t for t in tools if t.name == "greet")
+        assert not tool.meta or "ui" not in (tool.meta or {})
+
+    async def test_plain_server_has_no_synthesized_resources(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def greet(name: str) -> str:
+            return name
+
+        resources = list(await mcp.list_resources())
+        assert not any("prefab/tool" in str(r.uri) for r in resources)
diff --git a/tests/server/providers/test_skills_provider.py b/tests/server/providers/test_skills_provider.py
new file mode 100644
index 0000000..f57d481
--- /dev/null
+++ b/tests/server/providers/test_skills_provider.py
@@ -0,0 +1,819 @@
+"""Tests for SkillProvider, SkillsDirectoryProvider, and ClaudeSkillsProvider."""
+
+import json
+from pathlib import Path
+
+import pytest
+from mcp_types import TextResourceContents
+from pydantic import AnyUrl
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.providers.skills import (
+    ClaudeSkillsProvider,
+    SkillProvider,
+    SkillsDirectoryProvider,
+    SkillsProvider,
+)
+from fastmcp.server.providers.skills._common import parse_frontmatter
+from fastmcp.server.providers.skills.skill_provider import SkillFileResource
+
+
+class TestParseFrontmatter:
+    def test_no_frontmatter(self):
+        content = "# Just markdown\n\nSome content."
+        frontmatter, body = parse_frontmatter(content)
+        assert frontmatter == {}
+        assert body == content
+
+    def test_basic_frontmatter(self):
+        content = """---
+description: A test skill
+version: "1.0.0"
+---
+
+# Skill Content
+"""
+        frontmatter, body = parse_frontmatter(content)
+        assert frontmatter["description"] == "A test skill"
+        assert frontmatter["version"] == "1.0.0"
+        assert body.strip().startswith("# Skill Content")
+
+    def test_frontmatter_with_tags_list(self):
+        content = """---
+description: Test
+tags: [tag1, tag2, tag3]
+---
+
+Content
+"""
+        frontmatter, body = parse_frontmatter(content)
+        assert frontmatter["tags"] == ["tag1", "tag2", "tag3"]
+
+    def test_frontmatter_with_quoted_strings(self):
+        content = """---
+description: "A skill with quotes"
+version: '2.0.0'
+---
+
+Content
+"""
+        frontmatter, body = parse_frontmatter(content)
+        assert frontmatter["description"] == "A skill with quotes"
+        assert frontmatter["version"] == "2.0.0"
+
+
+class TestSkillProvider:
+    """Tests for SkillProvider - single skill folder."""
+
+    @pytest.fixture
+    def single_skill_dir(self, tmp_path: Path) -> Path:
+        """Create a single skill directory with files."""
+        skill_dir = tmp_path / "my-skill"
+        skill_dir.mkdir()
+        (skill_dir / "SKILL.md").write_text(
+            """---
+description: A test skill
+version: "1.0.0"
+---
+
+# My Skill
+
+This is my skill content.
+"""
+        )
+        (skill_dir / "reference.md").write_text("# Reference\n\nExtra docs.")
+        (skill_dir / "scripts").mkdir()
+        (skill_dir / "scripts" / "helper.py").write_text('print("helper")')
+        return skill_dir
+
+    def test_loads_skill_at_init(self, single_skill_dir: Path):
+        provider = SkillProvider(skill_path=single_skill_dir)
+        assert provider.skill_info.name == "my-skill"
+        assert provider.skill_info.description == "A test skill"
+        assert len(provider.skill_info.files) == 3
+
+    def test_raises_if_directory_missing(self, tmp_path: Path):
+        with pytest.raises(FileNotFoundError, match="Skill directory not found"):
+            SkillProvider(skill_path=tmp_path / "nonexistent")
+
+    def test_raises_if_main_file_missing(self, tmp_path: Path):
+        skill_dir = tmp_path / "no-main"
+        skill_dir.mkdir()
+        with pytest.raises(FileNotFoundError, match="Main skill file not found"):
+            SkillProvider(skill_path=skill_dir)
+
+    async def test_list_resources_default_template_mode(self, single_skill_dir: Path):
+        """In template mode (default), only main file and manifest are resources."""
+        provider = SkillProvider(skill_path=single_skill_dir)
+        resources = await provider.list_resources()
+
+        assert len(resources) == 2
+        names = {r.name for r in resources}
+        assert "my-skill/SKILL.md" in names
+        assert "my-skill/_manifest" in names
+
+    async def test_list_resources_supporting_files_as_resources(
+        self, single_skill_dir: Path
+    ):
+        """In resources mode, supporting files are also exposed as resources."""
+        provider = SkillProvider(
+            skill_path=single_skill_dir, supporting_files="resources"
+        )
+        resources = await provider.list_resources()
+
+        # 2 standard + 2 supporting files
+        assert len(resources) == 4
+        names = {r.name for r in resources}
+        assert "my-skill/SKILL.md" in names
+        assert "my-skill/_manifest" in names
+        assert "my-skill/reference.md" in names
+        assert "my-skill/scripts/helper.py" in names
+
+    async def test_list_templates_default_mode(self, single_skill_dir: Path):
+        """In template mode (default), one template is exposed."""
+        provider = SkillProvider(skill_path=single_skill_dir)
+        templates = await provider.list_resource_templates()
+
+        assert len(templates) == 1
+        assert templates[0].name == "my-skill_files"
+
+    async def test_list_templates_resources_mode(self, single_skill_dir: Path):
+        """In resources mode, no templates are exposed."""
+        provider = SkillProvider(
+            skill_path=single_skill_dir, supporting_files="resources"
+        )
+        templates = await provider.list_resource_templates()
+
+        assert templates == []
+
+    async def test_read_main_file(self, single_skill_dir: Path):
+        mcp = FastMCP("Test")
+        mcp.add_provider(SkillProvider(skill_path=single_skill_dir))
+
+        async with Client(mcp) as client:
+            result = await client.read_resource(AnyUrl("skill://my-skill/SKILL.md"))
+            assert len(result) == 1
+            assert isinstance(result[0], TextResourceContents)
+            assert "# My Skill" in result[0].text
+
+    async def test_read_manifest(self, single_skill_dir: Path):
+        mcp = FastMCP("Test")
+        mcp.add_provider(SkillProvider(skill_path=single_skill_dir))
+
+        async with Client(mcp) as client:
+            result = await client.read_resource(AnyUrl("skill://my-skill/_manifest"))
+            manifest = json.loads(result[0].text)
+            assert manifest["skill"] == "my-skill"
+            assert len(manifest["files"]) == 3
+            paths = {f["path"] for f in manifest["files"]}
+            assert "SKILL.md" in paths
+            assert "reference.md" in paths
+            assert "scripts/helper.py" in paths
+
+    async def test_manifest_ignores_symlink_target_outside_skill(self, tmp_path: Path):
+        skill_dir = tmp_path / "symlinked-skill"
+        skill_dir.mkdir()
+        (skill_dir / "SKILL.md").write_text("# Skill\n")
+
+        outside_file = tmp_path / "outside.txt"
+        outside_file.write_text("secret")
+        (skill_dir / "leak.txt").symlink_to(outside_file)
+
+        mcp = FastMCP("Test")
+        mcp.add_provider(SkillProvider(skill_path=skill_dir))
+
+        async with Client(mcp) as client:
+            result = await client.read_resource(
+                AnyUrl("skill://symlinked-skill/_manifest")
+            )
+            manifest = json.loads(result[0].text)
+
+        paths = {f["path"] for f in manifest["files"]}
+        assert "SKILL.md" in paths
+        assert "leak.txt" not in paths
+
+    async def test_read_supporting_file_via_template(self, single_skill_dir: Path):
+        mcp = FastMCP("Test")
+        mcp.add_provider(SkillProvider(skill_path=single_skill_dir))
+
+        async with Client(mcp) as client:
+            result = await client.read_resource(AnyUrl("skill://my-skill/reference.md"))
+            assert "# Reference" in result[0].text
+
+    async def test_read_supporting_file_via_resource_mode(self, single_skill_dir: Path):
+        mcp = FastMCP("Test")
+        mcp.add_provider(
+            SkillProvider(skill_path=single_skill_dir, supporting_files="resources")
+        )
+
+        async with Client(mcp) as client:
+            result = await client.read_resource(AnyUrl("skill://my-skill/reference.md"))
+            assert "# Reference" in result[0].text
+
+    async def test_skill_resource_meta(self, single_skill_dir: Path):
+        """SkillResource populates meta with skill name and is_manifest."""
+        provider = SkillProvider(skill_path=single_skill_dir)
+        resources = await provider.list_resources()
+
+        by_name = {r.name: r for r in resources}
+
+        main_meta = by_name["my-skill/SKILL.md"].get_meta()
+        assert main_meta["fastmcp"]["skill"] == {
+            "name": "my-skill",
+            "is_manifest": False,
+        }
+
+        manifest_meta = by_name["my-skill/_manifest"].get_meta()
+        assert manifest_meta["fastmcp"]["skill"] == {
+            "name": "my-skill",
+            "is_manifest": True,
+        }
+
+    async def test_skill_file_resource_meta(self, single_skill_dir: Path):
+        """SkillFileResource populates meta with skill name."""
+        provider = SkillProvider(
+            skill_path=single_skill_dir, supporting_files="resources"
+        )
+        resources = await provider.list_resources()
+
+        by_name = {r.name: r for r in resources}
+        file_meta = by_name["my-skill/reference.md"].get_meta()
+        assert file_meta["fastmcp"]["skill"] == {"name": "my-skill"}
+
+    async def test_skill_meta_survives_mounting(self, single_skill_dir: Path):
+        """Skill metadata in _meta is preserved when accessed through a mounted server."""
+        child = FastMCP("child")
+        child.add_provider(SkillProvider(skill_path=single_skill_dir))
+
+        parent = FastMCP("parent")
+        parent.mount(child, "skills")
+
+        resources = await parent.list_resources()
+        by_name = {r.name: r for r in resources}
+
+        main_meta = by_name["my-skill/SKILL.md"].get_meta()
+        assert main_meta["fastmcp"]["skill"] == {
+            "name": "my-skill",
+            "is_manifest": False,
+        }
+
+        manifest_meta = by_name["my-skill/_manifest"].get_meta()
+        assert manifest_meta["fastmcp"]["skill"] == {
+            "name": "my-skill",
+            "is_manifest": True,
+        }
+
+
+class TestSkillsDirectoryProvider:
+    """Tests for SkillsDirectoryProvider - scans directory for skill folders."""
+
+    @pytest.fixture
+    def skills_dir(self, tmp_path: Path) -> Path:
+        """Create a test skills directory with sample skills."""
+        skills_root = tmp_path / "skills"
+        skills_root.mkdir()
+
+        # Create a simple skill
+        simple_skill = skills_root / "simple-skill"
+        simple_skill.mkdir()
+        (simple_skill / "SKILL.md").write_text(
+            """---
+description: A simple test skill
+version: "1.0.0"
+---
+
+# Simple Skill
+
+This is a simple skill for testing.
+"""
+        )
+
+        # Create a skill with supporting files
+        complex_skill = skills_root / "complex-skill"
+        complex_skill.mkdir()
+        (complex_skill / "SKILL.md").write_text(
+            """---
+description: A complex skill with supporting files
+---
+
+# Complex Skill
+
+See [reference](reference.md) for more details.
+"""
+        )
+        (complex_skill / "reference.md").write_text(
+            """# Reference
+
+Additional documentation.
+"""
+        )
+        (complex_skill / "scripts").mkdir()
+        (complex_skill / "scripts" / "helper.py").write_text(
+            'print("Hello from helper")'
+        )
+
+        return skills_root
+
+    async def test_list_resources_discovers_skills(self, skills_dir: Path):
+        provider = SkillsDirectoryProvider(roots=skills_dir)
+        resources = await provider.list_resources()
+
+        # Should have 2 resources per skill (main file + manifest)
+        assert len(resources) == 4
+
+        # Check resource names
+        resource_names = {r.name for r in resources}
+        assert "simple-skill/SKILL.md" in resource_names
+        assert "simple-skill/_manifest" in resource_names
+        assert "complex-skill/SKILL.md" in resource_names
+        assert "complex-skill/_manifest" in resource_names
+
+    async def test_list_resources_includes_descriptions(self, skills_dir: Path):
+        provider = SkillsDirectoryProvider(roots=skills_dir)
+        resources = await provider.list_resources()
+
+        # Find the simple-skill main resource
+        simple_skill = next(r for r in resources if r.name == "simple-skill/SKILL.md")
+        assert simple_skill.description == "A simple test skill"
+
+    async def test_read_main_skill_file(self, skills_dir: Path):
+        mcp = FastMCP("Test")
+        mcp.add_provider(SkillsDirectoryProvider(roots=skills_dir))
+
+        async with Client(mcp) as client:
+            result = await client.read_resource(AnyUrl("skill://simple-skill/SKILL.md"))
+            assert len(result) == 1
+            assert isinstance(result[0], TextResourceContents)
+            assert "# Simple Skill" in result[0].text
+
+    async def test_read_manifest(self, skills_dir: Path):
+        mcp = FastMCP("Test")
+        mcp.add_provider(SkillsDirectoryProvider(roots=skills_dir))
+
+        async with Client(mcp) as client:
+            result = await client.read_resource(
+                AnyUrl("skill://complex-skill/_manifest")
+            )
+            assert len(result) == 1
+            assert isinstance(result[0], TextResourceContents)
+
+            manifest = json.loads(result[0].text)
+            assert manifest["skill"] == "complex-skill"
+            assert len(manifest["files"]) == 3  # SKILL.md, reference.md, helper.py
+
+            # Check file paths
+            paths = {f["path"] for f in manifest["files"]}
+            assert "SKILL.md" in paths
+            assert "reference.md" in paths
+            assert "scripts/helper.py" in paths
+
+            # Check hashes are present
+            for file_info in manifest["files"]:
+                assert file_info["hash"].startswith("sha256:")
+                assert file_info["size"] > 0
+
+    async def test_list_resource_templates(self, skills_dir: Path):
+        provider = SkillsDirectoryProvider(roots=skills_dir)
+        templates = await provider.list_resource_templates()
+
+        # One template per skill
+        assert len(templates) == 2
+
+        template_names = {t.name for t in templates}
+        assert "simple-skill_files" in template_names
+        assert "complex-skill_files" in template_names
+
+    async def test_read_supporting_file_via_template(self, skills_dir: Path):
+        mcp = FastMCP("Test")
+        mcp.add_provider(SkillsDirectoryProvider(roots=skills_dir))
+
+        async with Client(mcp) as client:
+            result = await client.read_resource(
+                AnyUrl("skill://complex-skill/reference.md")
+            )
+            assert len(result) == 1
+            assert isinstance(result[0], TextResourceContents)
+            assert "# Reference" in result[0].text
+
+    async def test_read_nested_file_via_template(self, skills_dir: Path):
+        mcp = FastMCP("Test")
+        mcp.add_provider(SkillsDirectoryProvider(roots=skills_dir))
+
+        async with Client(mcp) as client:
+            result = await client.read_resource(
+                AnyUrl("skill://complex-skill/scripts/helper.py")
+            )
+            assert len(result) == 1
+            assert isinstance(result[0], TextResourceContents)
+            assert "Hello from helper" in result[0].text
+
+    async def test_empty_skills_directory(self, tmp_path: Path):
+        empty_dir = tmp_path / "empty"
+        empty_dir.mkdir()
+
+        provider = SkillsDirectoryProvider(roots=empty_dir)
+        resources = await provider.list_resources()
+        assert resources == []
+
+        templates = await provider.list_resource_templates()
+        assert templates == []
+
+    async def test_nonexistent_skills_directory(self, tmp_path: Path):
+        nonexistent = tmp_path / "does-not-exist"
+        provider = SkillsDirectoryProvider(roots=nonexistent)
+
+        resources = await provider.list_resources()
+        assert resources == []
+
+    async def test_reload_mode(self, skills_dir: Path):
+        provider = SkillsDirectoryProvider(roots=skills_dir, reload=True)
+
+        # Initial load
+        resources = await provider.list_resources()
+        assert len(resources) == 4
+
+        # Add a new skill
+        new_skill = skills_dir / "new-skill"
+        new_skill.mkdir()
+        (new_skill / "SKILL.md").write_text(
+            """---
+description: A new skill
+---
+
+# New Skill
+"""
+        )
+
+        # Reload should pick up the new skill
+        resources = await provider.list_resources()
+        assert len(resources) == 6
+
+    async def test_skill_without_frontmatter_uses_header_as_description(
+        self, tmp_path: Path
+    ):
+        skills_dir = tmp_path / "skills"
+        skills_dir.mkdir()
+        skill = skills_dir / "no-frontmatter"
+        skill.mkdir()
+        (skill / "SKILL.md").write_text("# My Skill Title\n\nSome content.")
+
+        provider = SkillsDirectoryProvider(roots=skills_dir)
+        resources = await provider.list_resources()
+
+        main_resource = next(
+            r for r in resources if r.name == "no-frontmatter/SKILL.md"
+        )
+        assert main_resource.description == "My Skill Title"
+
+    async def test_supporting_files_as_resources(self, skills_dir: Path):
+        """Test that supporting_files='resources' shows all files."""
+        provider = SkillsDirectoryProvider(
+            roots=skills_dir, supporting_files="resources"
+        )
+        resources = await provider.list_resources()
+
+        # 2 skills * 2 standard resources + complex skill has 2 supporting files
+        # simple-skill: SKILL.md, _manifest (2)
+        # complex-skill: SKILL.md, _manifest, reference.md, scripts/helper.py (4)
+        assert len(resources) == 6
+
+        names = {r.name for r in resources}
+        assert "complex-skill/reference.md" in names
+        assert "complex-skill/scripts/helper.py" in names
+
+    async def test_supporting_files_as_resources_no_templates(self, skills_dir: Path):
+        """In resources mode, no templates should be exposed."""
+        provider = SkillsDirectoryProvider(
+            roots=skills_dir, supporting_files="resources"
+        )
+        templates = await provider.list_resource_templates()
+        assert templates == []
+
+
+class TestMultiDirectoryProvider:
+    """Tests for multi-directory support in SkillsDirectoryProvider."""
+
+    @pytest.fixture
+    def multi_skills_dirs(self, tmp_path: Path) -> tuple[Path, Path]:
+        """Create two separate skills directories."""
+        root1 = tmp_path / "skills1"
+        root1.mkdir()
+        skill1 = root1 / "skill-a"
+        skill1.mkdir()
+        (skill1 / "SKILL.md").write_text(
+            """---
+description: Skill A from root 1
+---
+# Skill A
+"""
+        )
+
+        root2 = tmp_path / "skills2"
+        root2.mkdir()
+        skill2 = root2 / "skill-b"
+        skill2.mkdir()
+        (skill2 / "SKILL.md").write_text(
+            """---
+description: Skill B from root 2
+---
+# Skill B
+"""
+        )
+
+        return root1, root2
+
+    async def test_multiple_roots_discover_all_skills(self, multi_skills_dirs):
+        """Test that skills from multiple roots are all discovered."""
+        root1, root2 = multi_skills_dirs
+        provider = SkillsDirectoryProvider(roots=[root1, root2])
+
+        resources = await provider.list_resources()
+        # 2 skills * 2 resources each = 4 total
+        assert len(resources) == 4
+
+        resource_names = {r.name for r in resources}
+        assert "skill-a/SKILL.md" in resource_names
+        assert "skill-a/_manifest" in resource_names
+        assert "skill-b/SKILL.md" in resource_names
+        assert "skill-b/_manifest" in resource_names
+
+    async def test_duplicate_skill_names_first_wins(self, tmp_path: Path):
+        """Test that if a skill appears in multiple roots, first one wins."""
+        root1 = tmp_path / "root1"
+        root1.mkdir()
+        skill1 = root1 / "duplicate-skill"
+        skill1.mkdir()
+        (skill1 / "SKILL.md").write_text(
+            """---
+description: First occurrence
+---
+# First
+"""
+        )
+
+        root2 = tmp_path / "root2"
+        root2.mkdir()
+        skill2 = root2 / "duplicate-skill"
+        skill2.mkdir()
+        (skill2 / "SKILL.md").write_text(
+            """---
+description: Second occurrence
+---
+# Second
+"""
+        )
+
+        provider = SkillsDirectoryProvider(roots=[root1, root2])
+        resources = await provider.list_resources()
+
+        # Should only have one skill (first one)
+        assert len(resources) == 2  # SKILL.md + _manifest
+
+        # Should be the first one
+        main_resource = next(
+            r for r in resources if r.name == "duplicate-skill/SKILL.md"
+        )
+        assert main_resource.description == "First occurrence"
+
+    async def test_single_path_as_list(self, multi_skills_dirs):
+        """Test that single path can be passed as a list."""
+        root1, _ = multi_skills_dirs
+        provider = SkillsDirectoryProvider(roots=[root1])
+
+        resources = await provider.list_resources()
+        assert len(resources) == 2  # skill-a has 2 resources
+
+    async def test_single_path_as_string(self, multi_skills_dirs):
+        """Test that single path can be passed as string."""
+        root1, _ = multi_skills_dirs
+        provider = SkillsDirectoryProvider(roots=str(root1))
+
+        resources = await provider.list_resources()
+        assert len(resources) == 2
+
+    async def test_nonexistent_roots_handled_gracefully(self, tmp_path: Path):
+        """Test that non-existent roots don't cause errors."""
+        existent = tmp_path / "exists"
+        existent.mkdir()
+        skill = existent / "test-skill"
+        skill.mkdir()
+        (skill / "SKILL.md").write_text("# Test\n\nContent")
+
+        nonexistent = tmp_path / "does-not-exist"
+
+        provider = SkillsDirectoryProvider(roots=[existent, nonexistent])
+        resources = await provider.list_resources()
+
+        # Should still find skills from existing root
+        assert len(resources) == 2
+
+    async def test_empty_roots_list(self, tmp_path: Path):
+        """Test that empty roots list results in no skills."""
+        provider = SkillsDirectoryProvider(roots=[])
+        resources = await provider.list_resources()
+        assert resources == []
+
+
+class TestSkillsProviderAlias:
+    """Test that SkillsProvider is a backwards-compatible alias."""
+
+    def test_skills_provider_is_alias(self):
+        assert SkillsProvider is SkillsDirectoryProvider
+
+
+class TestClaudeSkillsProvider:
+    def test_default_root_is_claude_skills_dir(self, tmp_path: Path, monkeypatch):
+        # Mock Path.home() to return a temp path (use tmp_path for cross-platform compatibility)
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+
+        provider = ClaudeSkillsProvider()
+        assert provider._roots == [tmp_path / ".claude" / "skills"]
+
+    def test_main_file_name_is_skill_md(self):
+        provider = ClaudeSkillsProvider()
+        assert provider._main_file_name == "SKILL.md"
+
+    def test_supporting_files_parameter(self):
+        provider = ClaudeSkillsProvider(supporting_files="resources")
+        assert provider._supporting_files == "resources"
+
+
+class TestPathTraversalPrevention:
+    async def test_path_traversal_blocked(self, tmp_path: Path):
+        skills_dir = tmp_path / "skills"
+        skills_dir.mkdir()
+        skill = skills_dir / "test-skill"
+        skill.mkdir()
+        (skill / "SKILL.md").write_text("# Test\n\nContent")
+
+        # Create a file outside the skill directory
+        secret_file = tmp_path / "secret.txt"
+        secret_file.write_text("SECRET DATA")
+
+        mcp = FastMCP("Test")
+        mcp.add_provider(SkillsDirectoryProvider(roots=skills_dir))
+
+        async with Client(mcp) as client:
+            # Path traversal attempts should fail — the secret must never be returned
+            with pytest.raises(Exception):
+                await client.read_resource(
+                    AnyUrl("skill://test-skill/../../../secret.txt")
+                )
+
+
+# Attack corpus mirroring the shapes exercised by the SDK's
+# mcp.shared.path_security tests: dot-dot traversal (bare, nested,
+# trailing), absolute-path injection (POSIX and Windows drive forms),
+# and null-byte injection. Each must be rejected before any filesystem
+# access, regardless of which skill surface receives it.
+SKILL_PATH_ESCAPES = [
+    "..",
+    "../secret.txt",
+    "../../../etc/passwd",
+    "sub/../../secret.txt",
+    "nested/../../outside.txt",
+    "/etc/passwd",
+    "/absolute/injection.txt",
+    "C:\\Windows\\system32",
+    "C:relative.txt",
+    "good\x00/../../../etc/passwd",
+    "file\x00.txt",
+]
+
+
+class TestPathSafetyAttackCorpus:
+    """Pin path-safety guards against the SDK's attack-shape corpus.
+
+    Every skill file surface routes user-supplied path parameters through
+    the SDK's ``safe_join``. These tests assert the whole corpus is
+    rejected with a clear error before the filesystem is touched, and
+    that legitimate nested paths continue to resolve.
+    """
+
+    @pytest.fixture
+    def skill_with_secret(self, tmp_path: Path) -> Path:
+        """A skill dir containing a nested file, with a secret one level up."""
+        skill_dir = tmp_path / "corpus-skill"
+        skill_dir.mkdir()
+        (skill_dir / "SKILL.md").write_text("# Corpus\n\nContent")
+        (skill_dir / "docs").mkdir()
+        (skill_dir / "docs" / "nested.txt").write_text("NESTED OK")
+        (tmp_path / "secret.txt").write_text("SECRET DATA")
+        return skill_dir
+
+    async def _template(self, skill_dir: Path):
+        provider = SkillProvider(skill_path=skill_dir)
+        templates = await provider.list_resource_templates()
+        return templates[0]
+
+    @pytest.mark.parametrize("attack", SKILL_PATH_ESCAPES)
+    async def test_template_read_rejects_escape(
+        self, skill_with_secret: Path, attack: str
+    ):
+        template = await self._template(skill_with_secret)
+        with pytest.raises(ValueError, match="Invalid path"):
+            await template.read(arguments={"path": attack})
+
+    @pytest.mark.parametrize("attack", SKILL_PATH_ESCAPES)
+    async def test_template_create_resource_rejects_escape(
+        self, skill_with_secret: Path, attack: str
+    ):
+        template = await self._template(skill_with_secret)
+        with pytest.raises(ValueError, match="Invalid path"):
+            await template.create_resource(
+                uri=f"skill://corpus-skill/{attack}", params={"path": attack}
+            )
+
+    @pytest.mark.parametrize("attack", SKILL_PATH_ESCAPES)
+    async def test_file_resource_read_rejects_escape(
+        self, skill_with_secret: Path, attack: str
+    ):
+        provider = SkillProvider(
+            skill_path=skill_with_secret, supporting_files="resources"
+        )
+        resource = SkillFileResource(
+            uri=AnyUrl("skill://corpus-skill/x"),
+            name="corpus-skill/x",
+            mime_type="text/plain",
+            skill_info=provider.skill_info,
+            file_path=attack,
+        )
+        with pytest.raises(ValueError, match="Invalid path"):
+            await resource.read()
+
+    async def test_template_read_allows_nested_path(self, skill_with_secret: Path):
+        template = await self._template(skill_with_secret)
+        result = await template.read(arguments={"path": "docs/nested.txt"})
+        assert result == "NESTED OK"
+
+    async def test_template_read_allows_within_bounds_dotdot(
+        self, skill_with_secret: Path
+    ):
+        template = await self._template(skill_with_secret)
+        result = await template.read(arguments={"path": "docs/../docs/nested.txt"})
+        assert result == "NESTED OK"
+
+    async def test_file_resource_read_allows_nested_path(self, skill_with_secret: Path):
+        provider = SkillProvider(
+            skill_path=skill_with_secret, supporting_files="resources"
+        )
+        resource = SkillFileResource(
+            uri=AnyUrl("skill://corpus-skill/docs/nested.txt"),
+            name="corpus-skill/docs/nested.txt",
+            mime_type="text/plain",
+            skill_info=provider.skill_info,
+            file_path="docs/nested.txt",
+        )
+        assert await resource.read() == "NESTED OK"
+
+
+async def test_skill_provider_loads_and_serves_utf8_skill_md(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """SKILL.md and its supporting text files must be read as utf-8.
+
+    Regression test for #4084. On Windows the default encoding is cp1252,
+    so a bare ``read_text()`` call fails to decode UTF-8 content with
+    ``UnicodeDecodeError: 'charmap' codec can't decode byte ...``. The fix
+    passes ``encoding="utf-8"`` explicitly at every read site: skill load,
+    main-file resource read, and supporting-file template/resource reads.
+    This test simulates the Windows behavior on any platform by failing
+    every text read that doesn't pass ``encoding="utf-8"``.
+    """
+    skill_dir = tmp_path / "test-skill"
+    skill_dir.mkdir()
+    (skill_dir / "SKILL.md").write_text(
+        "---\n"
+        "name: test-skill\n"
+        "description: Test skill with UTF-8 characters\n"
+        "---\n"
+        "# Test Skill 🎯\n"
+        "- ✅ Success indicator\n",
+        encoding="utf-8",
+    )
+    (skill_dir / "reference.md").write_text(
+        "# Reference\n- ✨ utf-8 supporting file\n", encoding="utf-8"
+    )
+
+    original_read_text = Path.read_text
+
+    def strict_read_text(self: Path, *args, **kwargs):
+        if kwargs.get("encoding") != "utf-8":
+            raise UnicodeDecodeError(
+                "charmap", b"\x9d", 0, 1, "simulated cp1252 default"
+            )
+        return original_read_text(self, *args, **kwargs)
+
+    monkeypatch.setattr(Path, "read_text", strict_read_text)
+
+    mcp = FastMCP("Test")
+    mcp.add_provider(SkillProvider(skill_path=skill_dir))
+
+    async with Client(mcp) as client:
+        main = await client.read_resource(AnyUrl("skill://test-skill/SKILL.md"))
+        assert isinstance(main[0], TextResourceContents)
+        assert "🎯" in main[0].text
+
+        ref = await client.read_resource(AnyUrl("skill://test-skill/reference.md"))
+        assert isinstance(ref[0], TextResourceContents)
+        assert "✨" in ref[0].text
diff --git a/tests/server/providers/test_skills_vendor_providers.py b/tests/server/providers/test_skills_vendor_providers.py
new file mode 100644
index 0000000..65959ef
--- /dev/null
+++ b/tests/server/providers/test_skills_vendor_providers.py
@@ -0,0 +1,201 @@
+"""Tests for vendor-specific skills providers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastmcp.server.providers.skills import (
+    ClaudeSkillsProvider,
+    CodexSkillsProvider,
+    CopilotSkillsProvider,
+    CursorSkillsProvider,
+    GeminiSkillsProvider,
+    GooseSkillsProvider,
+    OpenCodeSkillsProvider,
+    VSCodeSkillsProvider,
+)
+
+
+class TestVendorProviders:
+    """Tests for vendor-specific skills providers."""
+
+    def test_cursor_skills_provider_path(self, tmp_path: Path, monkeypatch):
+        """Test CursorSkillsProvider uses correct path."""
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+
+        provider = CursorSkillsProvider()
+        assert provider._roots == [tmp_path / ".cursor" / "skills"]
+
+    def test_vscode_skills_provider_path(self, tmp_path: Path, monkeypatch):
+        """Test VSCodeSkillsProvider uses correct path."""
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+
+        provider = VSCodeSkillsProvider()
+        assert provider._roots == [tmp_path / ".copilot" / "skills"]
+
+    def test_codex_skills_provider_paths(self, tmp_path: Path, monkeypatch):
+        """Test CodexSkillsProvider uses both system and user paths."""
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+
+        provider = CodexSkillsProvider()
+        # Path.resolve() may add /private on macOS, so compare resolved paths
+        expected_roots = [
+            Path("/etc/codex/skills").resolve(),
+            (tmp_path / ".codex" / "skills").resolve(),
+        ]
+        assert provider._roots == expected_roots
+
+    def test_gemini_skills_provider_path(self, tmp_path: Path, monkeypatch):
+        """Test GeminiSkillsProvider uses correct path."""
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+
+        provider = GeminiSkillsProvider()
+        assert provider._roots == [tmp_path / ".gemini" / "skills"]
+
+    def test_goose_skills_provider_path(self, tmp_path: Path, monkeypatch):
+        """Test GooseSkillsProvider uses correct path."""
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+
+        provider = GooseSkillsProvider()
+        assert provider._roots == [tmp_path / ".config" / "agents" / "skills"]
+
+    def test_copilot_skills_provider_path(self, tmp_path: Path, monkeypatch):
+        """Test CopilotSkillsProvider uses correct path."""
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+
+        provider = CopilotSkillsProvider()
+        assert provider._roots == [tmp_path / ".copilot" / "skills"]
+
+    def test_opencode_skills_provider_path(self, tmp_path: Path, monkeypatch):
+        """Test OpenCodeSkillsProvider uses correct path."""
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+
+        provider = OpenCodeSkillsProvider()
+        assert provider._roots == [tmp_path / ".config" / "opencode" / "skills"]
+
+    def test_claude_skills_provider_path(self, tmp_path: Path, monkeypatch):
+        """Test ClaudeSkillsProvider uses correct path."""
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+
+        provider = ClaudeSkillsProvider()
+        assert provider._roots == [tmp_path / ".claude" / "skills"]
+
+    def test_all_providers_instantiable(self):
+        """Test that all vendor providers can be instantiated."""
+        providers = [
+            ClaudeSkillsProvider(),
+            CursorSkillsProvider(),
+            VSCodeSkillsProvider(),
+            CodexSkillsProvider(),
+            GeminiSkillsProvider(),
+            GooseSkillsProvider(),
+            CopilotSkillsProvider(),
+            OpenCodeSkillsProvider(),
+        ]
+
+        for provider in providers:
+            assert provider is not None
+            assert provider._main_file_name == "SKILL.md"
+
+    def test_all_providers_support_reload(self):
+        """Test that all providers support reload parameter."""
+        providers = [
+            ClaudeSkillsProvider(reload=True),
+            CursorSkillsProvider(reload=True),
+            VSCodeSkillsProvider(reload=True),
+            CodexSkillsProvider(reload=True),
+            GeminiSkillsProvider(reload=True),
+            GooseSkillsProvider(reload=True),
+            CopilotSkillsProvider(reload=True),
+            OpenCodeSkillsProvider(reload=True),
+        ]
+
+        for provider in providers:
+            assert provider._reload is True
+
+    def test_all_providers_support_supporting_files(self):
+        """Test that all providers support supporting_files parameter."""
+        providers = [
+            ClaudeSkillsProvider(supporting_files="resources"),
+            CursorSkillsProvider(supporting_files="resources"),
+            VSCodeSkillsProvider(supporting_files="resources"),
+            CodexSkillsProvider(supporting_files="resources"),
+            GeminiSkillsProvider(supporting_files="resources"),
+            GooseSkillsProvider(supporting_files="resources"),
+            CopilotSkillsProvider(supporting_files="resources"),
+            OpenCodeSkillsProvider(supporting_files="resources"),
+        ]
+
+        for provider in providers:
+            assert provider._supporting_files == "resources"
+
+    async def test_codex_scans_both_paths(self, tmp_path: Path, monkeypatch):
+        """Test that CodexSkillsProvider scans both system and user paths."""
+        # Mock system path
+        system_skills = tmp_path / "etc" / "codex" / "skills"
+        system_skills.mkdir(parents=True)
+        system_skill = system_skills / "system-skill"
+        system_skill.mkdir()
+        (system_skill / "SKILL.md").write_text(
+            """---
+description: System skill
+---
+# System
+"""
+        )
+
+        # Mock user path
+        fake_home = tmp_path / "home" / "user"
+        fake_home.mkdir(parents=True)
+        monkeypatch.setattr(Path, "home", lambda: fake_home)
+
+        user_skills = fake_home / ".codex" / "skills"
+        user_skills.mkdir(parents=True)
+        user_skill = user_skills / "user-skill"
+        user_skill.mkdir()
+        (user_skill / "SKILL.md").write_text(
+            """---
+description: User skill
+---
+# User
+"""
+        )
+
+        # Create provider with mocked paths
+        # Override roots before discovery
+        provider = CodexSkillsProvider()
+        provider._roots = [system_skills, user_skills]
+        # Trigger re-discovery with new roots
+        provider._discover_skills()
+
+        resources = await provider.list_resources()
+        # Should find both skills
+        assert len(resources) == 4  # 2 skills * 2 resources each
+
+        resource_names = {r.name for r in resources}
+        assert "system-skill/SKILL.md" in resource_names
+        assert "user-skill/SKILL.md" in resource_names
+
+    async def test_nonexistent_paths_handled_gracefully(
+        self, tmp_path: Path, monkeypatch
+    ):
+        """Test that non-existent paths don't cause errors."""
+        # Use a path that definitely doesn't exist
+        nonexistent_home = tmp_path / "nonexistent" / "home"
+        monkeypatch.setattr(Path, "home", lambda: nonexistent_home)
+
+        # All providers should handle non-existent paths gracefully
+        providers = [
+            ClaudeSkillsProvider(),
+            CursorSkillsProvider(),
+            VSCodeSkillsProvider(),
+            GeminiSkillsProvider(),
+            GooseSkillsProvider(),
+            CopilotSkillsProvider(),
+            OpenCodeSkillsProvider(),
+        ]
+
+        for provider in providers:
+            resources = await provider.list_resources()
+            # Should return empty list, not raise exception
+            assert isinstance(resources, list)
diff --git a/tests/server/providers/test_transforming_provider.py b/tests/server/providers/test_transforming_provider.py
new file mode 100644
index 0000000..ce7acd2
--- /dev/null
+++ b/tests/server/providers/test_transforming_provider.py
@@ -0,0 +1,299 @@
+"""Tests for Namespace and ToolTransform."""
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.providers import FastMCPProvider
+from fastmcp.server.transforms import Namespace, ToolTransform
+from fastmcp.tools.tool_transform import ToolTransformConfig
+
+
+class TestNamespaceTransform:
+    """Test Namespace transform transformations."""
+
+    async def test_namespace_prefixes_tool_names(self):
+        """Test that namespace is applied as prefix to tool names."""
+        server = FastMCP("Test")
+
+        @server.tool
+        def my_tool() -> str:
+            return "result"
+
+        provider = FastMCPProvider(server)
+        layer = Namespace("ns")
+
+        # Get tools and pass directly to transform
+        tools = await provider.list_tools()
+        transformed_tools = await layer.list_tools(tools)
+
+        assert len(transformed_tools) == 1
+        assert transformed_tools[0].name == "ns_my_tool"
+
+    async def test_namespace_prefixes_prompt_names(self):
+        """Test that namespace is applied as prefix to prompt names."""
+        server = FastMCP("Test")
+
+        @server.prompt
+        def my_prompt() -> str:
+            return "prompt content"
+
+        provider = FastMCPProvider(server)
+        layer = Namespace("ns")
+
+        prompts = await provider.list_prompts()
+        transformed_prompts = await layer.list_prompts(prompts)
+
+        assert len(transformed_prompts) == 1
+        assert transformed_prompts[0].name == "ns_my_prompt"
+
+    async def test_namespace_prefixes_resource_uris(self):
+        """Test that namespace is inserted into resource URIs."""
+        server = FastMCP("Test")
+
+        @server.resource("resource://data")
+        def my_resource() -> str:
+            return "content"
+
+        provider = FastMCPProvider(server)
+        layer = Namespace("ns")
+
+        resources = await provider.list_resources()
+        transformed_resources = await layer.list_resources(resources)
+
+        assert len(transformed_resources) == 1
+        assert str(transformed_resources[0].uri) == "resource://ns/data"
+
+    async def test_namespace_prefixes_template_uris(self):
+        """Test that namespace is inserted into resource template URIs."""
+        server = FastMCP("Test")
+
+        @server.resource("resource://{name}/data")
+        def my_template(name: str) -> str:
+            return f"content for {name}"
+
+        provider = FastMCPProvider(server)
+        layer = Namespace("ns")
+
+        templates = await provider.list_resource_templates()
+        transformed_templates = await layer.list_resource_templates(templates)
+
+        assert len(transformed_templates) == 1
+        assert transformed_templates[0].uri_template == "resource://ns/{name}/data"
+
+
+class TestToolTransformRenames:
+    """Test ToolTransform renaming functionality."""
+
+    async def test_tool_rename(self):
+        """Test tool renaming with ToolTransform."""
+        server = FastMCP("Test")
+
+        @server.tool
+        def verbose_tool_name() -> str:
+            return "result"
+
+        provider = FastMCPProvider(server)
+        layer = ToolTransform({"verbose_tool_name": ToolTransformConfig(name="short")})
+
+        tools = await provider.list_tools()
+        transformed_tools = await layer.list_tools(tools)
+
+        assert len(transformed_tools) == 1
+        assert transformed_tools[0].name == "short"
+
+    async def test_renamed_tool_is_callable_via_mount(self):
+        """Test that renamed tools can be called by new name via mount."""
+        sub = FastMCP("Sub")
+
+        @sub.tool
+        def original() -> str:
+            return "success"
+
+        main = FastMCP("Main")
+        # Add provider with transform layer
+        provider = FastMCPProvider(sub)
+        provider.add_transform(
+            ToolTransform({"original": ToolTransformConfig(name="renamed")})
+        )
+        main.add_provider(provider)
+
+        async with Client(main) as client:
+            result = await client.call_tool("renamed", {})
+            assert result.data == "success"
+
+    def test_duplicate_rename_targets_raises_error(self):
+        """Test that duplicate target names in ToolTransform raises ValueError."""
+        with pytest.raises(ValueError, match="duplicate target name"):
+            ToolTransform(
+                {
+                    "tool_a": ToolTransformConfig(name="same"),
+                    "tool_b": ToolTransformConfig(name="same"),
+                }
+            )
+
+
+class TestTransformReverseLookup:
+    """Test reverse lookups for routing."""
+
+    async def test_namespace_get_tool(self):
+        """Test that tools can be looked up by transformed name."""
+        server = FastMCP("Test")
+
+        @server.tool
+        def my_tool() -> str:
+            return "result"
+
+        provider = FastMCPProvider(server)
+        layer = Namespace("ns")
+
+        # Create call_next that delegates to provider
+        async def get_tool(name: str, version=None):
+            return await provider._get_tool(name, version)
+
+        tool = await layer.get_tool("ns_my_tool", get_tool)
+
+        assert tool is not None
+        assert tool.name == "ns_my_tool"
+
+    async def test_transform_layer_get_tool(self):
+        """Test that renamed tools can be looked up by new name."""
+        server = FastMCP("Test")
+
+        @server.tool
+        def original() -> str:
+            return "result"
+
+        provider = FastMCPProvider(server)
+        layer = ToolTransform({"original": ToolTransformConfig(name="renamed")})
+
+        async def get_tool(name: str, version=None):
+            return await provider._get_tool(name, version)
+
+        tool = await layer.get_tool("renamed", get_tool)
+
+        assert tool is not None
+        assert tool.name == "renamed"
+
+    async def test_namespace_get_resource(self):
+        """Test that resources can be looked up by transformed URI."""
+        server = FastMCP("Test")
+
+        @server.resource("resource://data")
+        def my_resource() -> str:
+            return "content"
+
+        provider = FastMCPProvider(server)
+        layer = Namespace("ns")
+
+        async def get_resource(uri: str, version=None):
+            return await provider._get_resource(uri, version)
+
+        resource = await layer.get_resource("resource://ns/data", get_resource)
+
+        assert resource is not None
+        assert str(resource.uri) == "resource://ns/data"
+
+    async def test_nonmatching_namespace_returns_none(self):
+        """Test that lookups with wrong namespace return None."""
+        server = FastMCP("Test")
+
+        @server.tool
+        def my_tool() -> str:
+            return "result"
+
+        provider = FastMCPProvider(server)
+        layer = Namespace("ns")
+
+        async def get_tool(name: str, version=None):
+            return await provider._get_tool(name, version)
+
+        # Wrong namespace prefix
+        assert await layer.get_tool("wrong_my_tool", get_tool) is None
+        # No prefix at all
+        assert await layer.get_tool("my_tool", get_tool) is None
+
+
+class TestTransformStacking:
+    """Test stacking multiple transforms via provider add_transform."""
+
+    async def test_stacked_namespaces_compose(self):
+        """Test that stacked namespaces are applied in order."""
+        server = FastMCP("Test")
+
+        @server.tool
+        def my_tool() -> str:
+            return "result"
+
+        provider = FastMCPProvider(server)
+        inner_layer = Namespace("inner")
+        outer_layer = Namespace("outer")
+
+        # Apply transforms sequentially: base -> inner -> outer
+        tools = await provider.list_tools()
+        tools = await inner_layer.list_tools(tools)
+        tools = await outer_layer.list_tools(tools)
+
+        assert len(tools) == 1
+        assert tools[0].name == "outer_inner_my_tool"
+
+    async def test_stacked_transforms_are_callable(self):
+        """Test that stacked transforms still allow tool calls."""
+        sub = FastMCP("Sub")
+
+        @sub.tool
+        def my_tool() -> str:
+            return "success"
+
+        main = FastMCP("Main")
+        provider = FastMCPProvider(sub)
+        # Add namespace layer then rename layer
+        provider.add_transform(Namespace("ns"))
+        provider.add_transform(
+            ToolTransform({"ns_my_tool": ToolTransformConfig(name="short")})
+        )
+        main.add_provider(provider)
+
+        async with Client(main) as client:
+            result = await client.call_tool("short", {})
+            assert result.data == "success"
+
+
+class TestNoTransformation:
+    """Test behavior when no transformations are applied."""
+
+    async def test_transform_passthrough(self):
+        """Test that base Transform passes through unchanged."""
+        from fastmcp.server.transforms import Transform
+
+        server = FastMCP("Test")
+
+        @server.tool
+        def my_tool() -> str:
+            return "result"
+
+        provider = FastMCPProvider(server)
+        transform = Transform()
+
+        tools = await provider.list_tools()
+        transformed_tools = await transform.list_tools(tools)
+
+        assert len(transformed_tools) == 1
+        assert transformed_tools[0].name == "my_tool"
+
+    async def test_empty_transform_layer_passthrough(self):
+        """Test that empty ToolTransform has no effect."""
+        server = FastMCP("Test")
+
+        @server.tool
+        def my_tool() -> str:
+            return "result"
+
+        provider = FastMCPProvider(server)
+        layer = ToolTransform({})
+
+        tools = await provider.list_tools()
+        transformed_tools = await layer.list_tools(tools)
+
+        assert len(transformed_tools) == 1
+        assert transformed_tools[0].name == "my_tool"
diff --git a/tests/server/sampling/__init__.py b/tests/server/sampling/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/server/sampling/test_prepare_tools.py b/tests/server/sampling/test_prepare_tools.py
new file mode 100644
index 0000000..b0639b4
--- /dev/null
+++ b/tests/server/sampling/test_prepare_tools.py
@@ -0,0 +1,111 @@
+"""Tests for prepare_tools helper function."""
+
+import pytest
+
+from fastmcp.server.sampling.run import prepare_tools
+from fastmcp.server.sampling.sampling_tool import SamplingTool
+from fastmcp.tools.function_tool import FunctionTool
+from fastmcp.tools.tool_transform import ArgTransform, TransformedTool
+
+
+class TestPrepareTools:
+    """Tests for prepare_tools()."""
+
+    def test_prepare_tools_with_none(self):
+        """Test that None returns None."""
+        result = prepare_tools(None)
+        assert result is None
+
+    def test_prepare_tools_with_sampling_tool(self):
+        """Test that SamplingTool instances pass through."""
+
+        def search(query: str) -> str:
+            return f"Results: {query}"
+
+        sampling_tool = SamplingTool.from_function(search)
+        result = prepare_tools([sampling_tool])
+
+        assert result is not None
+        assert len(result) == 1
+        assert result[0] is sampling_tool
+
+    def test_prepare_tools_with_function(self):
+        """Test that plain functions are converted."""
+
+        def search(query: str) -> str:
+            """Search function."""
+            return f"Results: {query}"
+
+        result = prepare_tools([search])
+
+        assert result is not None
+        assert len(result) == 1
+        assert isinstance(result[0], SamplingTool)
+        assert result[0].name == "search"
+
+    def test_prepare_tools_with_function_tool(self):
+        """Test that FunctionTool instances are converted."""
+
+        def search(query: str) -> str:
+            """Search the web."""
+            return f"Results: {query}"
+
+        function_tool = FunctionTool.from_function(search)
+        result = prepare_tools([function_tool])
+
+        assert result is not None
+        assert len(result) == 1
+        assert isinstance(result[0], SamplingTool)
+        assert result[0].name == "search"
+        assert result[0].description == "Search the web."
+
+    def test_prepare_tools_with_transformed_tool(self):
+        """Test that TransformedTool instances are converted."""
+
+        def original(query: str) -> str:
+            """Original tool."""
+            return f"Results: {query}"
+
+        function_tool = FunctionTool.from_function(original)
+        transformed_tool = TransformedTool.from_tool(
+            function_tool,
+            name="search_v2",
+            transform_args={"query": ArgTransform(name="q")},
+        )
+
+        result = prepare_tools([transformed_tool])
+
+        assert result is not None
+        assert len(result) == 1
+        assert isinstance(result[0], SamplingTool)
+        assert result[0].name == "search_v2"
+        assert "q" in result[0].parameters.get("properties", {})
+
+    def test_prepare_tools_with_mixed_types(self):
+        """Test that mixed tool types are all converted."""
+
+        def plain_fn(x: int) -> int:
+            return x * 2
+
+        def fn_for_tool(y: int) -> int:
+            return y * 3
+
+        function_tool = FunctionTool.from_function(fn_for_tool)
+        sampling_tool = SamplingTool.from_function(lambda z: z * 4, name="lambda_tool")
+
+        result = prepare_tools([plain_fn, function_tool, sampling_tool])
+
+        assert result is not None
+        assert len(result) == 3
+        assert all(isinstance(t, SamplingTool) for t in result)
+
+    def test_prepare_tools_with_invalid_type(self):
+        """Test that invalid types raise TypeError."""
+
+        with pytest.raises(TypeError, match="Expected SamplingTool, FunctionTool"):
+            prepare_tools(["not a tool"])  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+
+    def test_prepare_tools_empty_list(self):
+        """Test that empty list returns None."""
+        result = prepare_tools([])
+        assert result is None
diff --git a/tests/server/sampling/test_sampling_tool.py b/tests/server/sampling/test_sampling_tool.py
new file mode 100644
index 0000000..792161e
--- /dev/null
+++ b/tests/server/sampling/test_sampling_tool.py
@@ -0,0 +1,440 @@
+"""Tests for SamplingTool."""
+
+import pytest
+from mcp.server.auth.middleware.auth_context import auth_context_var
+from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser
+
+from fastmcp.exceptions import AuthorizationError
+from fastmcp.server.auth import AccessToken, require_scopes
+from fastmcp.server.context import _current_transport
+from fastmcp.server.sampling import SamplingTool
+from fastmcp.tools.function_tool import FunctionTool
+from fastmcp.tools.tool_transform import ArgTransform, TransformedTool
+
+
+class TestSamplingToolFromFunction:
+    """Tests for SamplingTool.from_function()."""
+
+    def test_from_simple_function(self):
+        def search(query: str) -> str:
+            """Search the web."""
+            return f"Results for: {query}"
+
+        tool = SamplingTool.from_function(search)
+
+        assert tool.name == "search"
+        assert tool.description == "Search the web."
+        assert "query" in tool.parameters.get("properties", {})
+        assert tool.fn is search
+
+    def test_from_function_with_overrides(self):
+        def search(query: str) -> str:
+            return f"Results for: {query}"
+
+        tool = SamplingTool.from_function(
+            search,
+            name="web_search",
+            description="Search the internet",
+        )
+
+        assert tool.name == "web_search"
+        assert tool.description == "Search the internet"
+
+    def test_from_lambda_requires_name(self):
+        with pytest.raises(ValueError, match="must provide a name for lambda"):
+            SamplingTool.from_function(lambda x: x)
+
+    def test_from_lambda_with_name(self):
+        tool = SamplingTool.from_function(lambda x: x * 2, name="double")
+
+        assert tool.name == "double"
+
+    def test_from_async_function(self):
+        async def async_search(query: str) -> str:
+            """Async search."""
+            return f"Async results for: {query}"
+
+        tool = SamplingTool.from_function(async_search)
+
+        assert tool.name == "async_search"
+        assert tool.description == "Async search."
+
+    def test_multiple_parameters(self):
+        def search(query: str, limit: int = 10, include_images: bool = False) -> str:
+            """Search with options."""
+            return f"Results for: {query}"
+
+        tool = SamplingTool.from_function(search)
+        props = tool.parameters.get("properties", {})
+
+        assert "query" in props
+        assert "limit" in props
+        assert "include_images" in props
+
+
+class TestSamplingToolRun:
+    """Tests for SamplingTool.run()."""
+
+    async def test_run_sync_function(self):
+        def add(a: int, b: int) -> int:
+            """Add two numbers."""
+            return a + b
+
+        tool = SamplingTool.from_function(add)
+        result = await tool.run({"a": 2, "b": 3})
+        assert result == 5
+
+    async def test_run_async_function(self):
+        async def async_add(a: int, b: int) -> int:
+            """Add two numbers asynchronously."""
+            return a + b
+
+        tool = SamplingTool.from_function(async_add)
+        result = await tool.run({"a": 2, "b": 3})
+        assert result == 5
+
+    async def test_run_with_no_arguments(self):
+        def get_value() -> str:
+            """Return a fixed value."""
+            return "hello"
+
+        tool = SamplingTool.from_function(get_value)
+        result = await tool.run()
+        assert result == "hello"
+
+    async def test_run_with_none_arguments(self):
+        def get_value() -> str:
+            """Return a fixed value."""
+            return "hello"
+
+        tool = SamplingTool.from_function(get_value)
+        result = await tool.run(None)
+        assert result == "hello"
+
+
+class TestSamplingToolSDKConversion:
+    """Tests for SamplingTool._to_sdk_tool() internal method."""
+
+    def test_to_sdk_tool(self):
+        def search(query: str) -> str:
+            """Search the web."""
+            return f"Results for: {query}"
+
+        tool = SamplingTool.from_function(search)
+        sdk_tool = tool._to_sdk_tool()
+
+        assert sdk_tool.name == "search"
+        assert sdk_tool.description == "Search the web."
+        assert "query" in sdk_tool.input_schema.get("properties", {})
+
+
+class TestSamplingToolFromCallableTool:
+    """Tests for SamplingTool.from_callable_tool()."""
+
+    def test_from_function_tool(self):
+        """Test converting a FunctionTool to SamplingTool."""
+
+        def search(query: str) -> str:
+            """Search the web."""
+            return f"Results for: {query}"
+
+        function_tool = FunctionTool.from_function(search)
+        sampling_tool = SamplingTool.from_callable_tool(function_tool)
+
+        assert sampling_tool.name == "search"
+        assert sampling_tool.description == "Search the web."
+        assert "query" in sampling_tool.parameters.get("properties", {})
+        # fn is now a wrapper that calls tool.run() for proper result processing
+        assert callable(sampling_tool.fn)
+
+    def test_from_function_tool_with_overrides(self):
+        """Test converting FunctionTool with name/description overrides."""
+
+        def search(query: str) -> str:
+            """Search the web."""
+            return f"Results for: {query}"
+
+        function_tool = FunctionTool.from_function(search)
+        sampling_tool = SamplingTool.from_callable_tool(
+            function_tool,
+            name="web_search",
+            description="Search the internet",
+        )
+
+        assert sampling_tool.name == "web_search"
+        assert sampling_tool.description == "Search the internet"
+
+    def test_from_transformed_tool(self):
+        """Test converting a TransformedTool to SamplingTool."""
+
+        def original(query: str, limit: int) -> str:
+            """Original tool."""
+            return f"Results for: {query} (limit: {limit})"
+
+        function_tool = FunctionTool.from_function(original)
+        transformed_tool = TransformedTool.from_tool(
+            function_tool,
+            name="search_transformed",
+            transform_args={"query": ArgTransform(name="q")},
+        )
+
+        sampling_tool = SamplingTool.from_callable_tool(transformed_tool)
+
+        assert sampling_tool.name == "search_transformed"
+        assert sampling_tool.description == "Original tool."
+        # The transformed tool should have 'q' instead of 'query'
+        assert "q" in sampling_tool.parameters.get("properties", {})
+        assert "limit" in sampling_tool.parameters.get("properties", {})
+
+    async def test_from_function_tool_execution(self):
+        """Test that converted FunctionTool executes correctly."""
+
+        def add(a: int, b: int) -> int:
+            """Add two numbers."""
+            return a + b
+
+        function_tool = FunctionTool.from_function(add)
+        sampling_tool = SamplingTool.from_callable_tool(function_tool)
+
+        result = await sampling_tool.run({"a": 2, "b": 3})
+        assert result == 5
+
+    async def test_from_transformed_tool_execution(self):
+        """Test that converted TransformedTool executes correctly."""
+
+        def multiply(x: int, y: int) -> int:
+            """Multiply two numbers."""
+            return x * y
+
+        function_tool = FunctionTool.from_function(multiply)
+        transformed_tool = TransformedTool.from_tool(
+            function_tool,
+            transform_args={"x": ArgTransform(name="a"), "y": ArgTransform(name="b")},
+        )
+
+        sampling_tool = SamplingTool.from_callable_tool(transformed_tool)
+
+        # Use the transformed parameter names
+        result = await sampling_tool.run({"a": 3, "b": 4})
+        # Result should be unwrapped from ToolResult
+        assert result == 12
+
+    def test_from_invalid_tool_type(self):
+        """Test that from_callable_tool rejects non-tool objects."""
+
+        class NotATool:
+            pass
+
+        with pytest.raises(
+            TypeError,
+            match="Expected FunctionTool or TransformedTool",
+        ):
+            SamplingTool.from_callable_tool(NotATool())  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+
+    def test_from_plain_function_fails(self):
+        """Test that plain functions are rejected by from_callable_tool."""
+
+        def my_function():
+            pass
+
+        with pytest.raises(TypeError, match="Expected FunctionTool or TransformedTool"):
+            SamplingTool.from_callable_tool(my_function)  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+
+    async def test_from_function_tool_with_output_schema(self):
+        """Test that FunctionTool with output_schema is handled correctly."""
+
+        def search(query: str) -> dict:
+            """Search for something."""
+            return {"results": ["item1", "item2"], "count": 2}
+
+        # Create FunctionTool with x-fastmcp-wrap-result
+        function_tool = FunctionTool.from_function(
+            search,
+            output_schema={
+                "type": "object",
+                "properties": {
+                    "results": {"type": "array"},
+                    "count": {"type": "integer"},
+                },
+                "x-fastmcp-wrap-result": True,
+            },
+        )
+
+        sampling_tool = SamplingTool.from_callable_tool(function_tool)
+
+        # Run the tool - should unwrap the {"result": {...}} wrapper
+        result = await sampling_tool.run({"query": "test"})
+
+        # Should get the unwrapped dict, not ToolResult
+        assert isinstance(result, dict)
+        assert result == {"results": ["item1", "item2"], "count": 2}
+
+    async def test_from_function_tool_without_wrap_result(self):
+        """Test that FunctionTool without x-fastmcp-wrap-result is handled correctly."""
+
+        def get_data() -> dict:
+            """Get some data."""
+            return {"status": "ok", "value": 42}
+
+        # Create FunctionTool with output_schema but no wrap-result flag
+        function_tool = FunctionTool.from_function(
+            get_data,
+            output_schema={
+                "type": "object",
+                "properties": {
+                    "status": {"type": "string"},
+                    "value": {"type": "integer"},
+                },
+            },
+        )
+
+        sampling_tool = SamplingTool.from_callable_tool(function_tool)
+
+        # Run the tool - should return structured_content directly
+        result = await sampling_tool.run({})
+
+        assert isinstance(result, dict)
+        assert result == {"status": "ok", "value": 42}
+
+
+class TestSamplingToolAuthEnforcement:
+    """Tests that auth-protected tools enforce auth when used via sampling."""
+
+    async def test_auth_protected_tool_blocked_without_token(self):
+        """An auth-protected tool wrapped as SamplingTool must reject
+        calls when no valid token is present in a non-stdio transport."""
+
+        def secret_action() -> str:
+            """Do something privileged."""
+            return "secret"
+
+        function_tool = FunctionTool.from_function(
+            secret_action,
+            auth=require_scopes("admin"),
+        )
+        sampling_tool = SamplingTool.from_callable_tool(function_tool)
+
+        transport_token = _current_transport.set("streamable-http")
+        try:
+            with pytest.raises(AuthorizationError, match="insufficient permissions"):
+                await sampling_tool.run({})
+        finally:
+            _current_transport.reset(transport_token)
+
+    async def test_auth_protected_tool_blocked_with_wrong_scopes(self):
+        """An auth-protected tool rejects calls when the token lacks
+        the required scopes."""
+
+        def secret_action() -> str:
+            """Do something privileged."""
+            return "secret"
+
+        function_tool = FunctionTool.from_function(
+            secret_action,
+            auth=require_scopes("admin"),
+        )
+        sampling_tool = SamplingTool.from_callable_tool(function_tool)
+
+        token = AccessToken(
+            token="test",
+            client_id="c",
+            scopes=["read"],
+            expires_at=None,
+            claims={},
+        )
+        transport_token = _current_transport.set("streamable-http")
+        auth_token = auth_context_var.set(AuthenticatedUser(token))
+        try:
+            with pytest.raises(AuthorizationError, match="insufficient permissions"):
+                await sampling_tool.run({})
+        finally:
+            auth_context_var.reset(auth_token)
+            _current_transport.reset(transport_token)
+
+    async def test_auth_protected_tool_allowed_with_correct_scopes(self):
+        """An auth-protected tool succeeds when the token has the
+        required scopes."""
+
+        def secret_action() -> str:
+            """Do something privileged."""
+            return "secret"
+
+        function_tool = FunctionTool.from_function(
+            secret_action,
+            auth=require_scopes("admin"),
+        )
+        sampling_tool = SamplingTool.from_callable_tool(function_tool)
+
+        token = AccessToken(
+            token="test",
+            client_id="c",
+            scopes=["admin"],
+            expires_at=None,
+            claims={},
+        )
+        transport_token = _current_transport.set("streamable-http")
+        auth_token = auth_context_var.set(AuthenticatedUser(token))
+        try:
+            result = await sampling_tool.run({})
+            assert result == "secret"
+        finally:
+            auth_context_var.reset(auth_token)
+            _current_transport.reset(transport_token)
+
+    async def test_auth_protected_tool_skipped_on_stdio(self):
+        """Auth checks are skipped for stdio transport, matching
+        server dispatcher behavior."""
+
+        def secret_action() -> str:
+            """Do something privileged."""
+            return "secret"
+
+        function_tool = FunctionTool.from_function(
+            secret_action,
+            auth=require_scopes("admin"),
+        )
+        sampling_tool = SamplingTool.from_callable_tool(function_tool)
+
+        transport_token = _current_transport.set("stdio")
+        try:
+            result = await sampling_tool.run({})
+            assert result == "secret"
+        finally:
+            _current_transport.reset(transport_token)
+
+    async def test_tool_without_auth_runs_normally(self):
+        """Tools without auth still run without any auth context."""
+
+        def public_action() -> str:
+            """Do something public."""
+            return "public"
+
+        function_tool = FunctionTool.from_function(public_action)
+        sampling_tool = SamplingTool.from_callable_tool(function_tool)
+
+        result = await sampling_tool.run({})
+        assert result == "public"
+
+    async def test_auth_protected_transformed_tool_blocked(self):
+        """Auth checks also apply to TransformedTools with auth."""
+
+        def secret_action(x: int) -> int:
+            """Privileged computation."""
+            return x * 2
+
+        function_tool = FunctionTool.from_function(
+            secret_action,
+            auth=require_scopes("compute"),
+        )
+        transformed_tool = TransformedTool.from_tool(
+            function_tool,
+            transform_args={"x": ArgTransform(name="value")},
+        )
+        sampling_tool = SamplingTool.from_callable_tool(transformed_tool)
+
+        transport_token = _current_transport.set("streamable-http")
+        try:
+            with pytest.raises(AuthorizationError, match="insufficient permissions"):
+                await sampling_tool.run({"value": 5})
+        finally:
+            _current_transport.reset(transport_token)
diff --git a/tests/server/tasks/__init__.py b/tests/server/tasks/__init__.py
new file mode 100644
index 0000000..84d43c0
--- /dev/null
+++ b/tests/server/tasks/__init__.py
@@ -0,0 +1 @@
+"""Tests for MCP SEP-1686 background tasks."""
diff --git a/tests/server/tasks/conftest.py b/tests/server/tasks/conftest.py
new file mode 100644
index 0000000..496053b
--- /dev/null
+++ b/tests/server/tasks/conftest.py
@@ -0,0 +1 @@
+"""Configuration for server task tests."""
diff --git a/tests/server/tasks/test_concurrent_dependencies.py b/tests/server/tasks/test_concurrent_dependencies.py
new file mode 100644
index 0000000..eb5af1b
--- /dev/null
+++ b/tests/server/tasks/test_concurrent_dependencies.py
@@ -0,0 +1,213 @@
+"""Tests for concurrent dependency resolution in foreground and background tasks.
+
+Regression tests for:
+- #3654: ValueError when concurrent Docket tasks share a Dependency instance
+         that stores a ContextVar token on `self`
+- #3656: Progress raises AssertionError when concurrent tasks share `_impl`
+"""
+
+import asyncio
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.dependencies import Progress
+from fastmcp.server.context import Context
+from fastmcp.server.dependencies import (
+    get_access_token,
+    get_http_headers,
+)
+
+
+async def test_concurrent_foreground_tools_with_context():
+    """Multiple concurrent tool calls sharing the same CurrentContext() default
+    should not raise ValueError from ContextVar token resets (#3654)."""
+    mcp = FastMCP("test")
+    results: list[str] = []
+
+    @mcp.tool()
+    async def slow_tool(name: str, ctx: Context) -> str:
+        await asyncio.sleep(0.05)
+        results.append(name)
+        return f"done:{name}"
+
+    async with Client(mcp) as client:
+        tasks = [client.call_tool("slow_tool", {"name": f"task-{i}"}) for i in range(4)]
+        outcomes = await asyncio.gather(*tasks)
+
+    assert len(outcomes) == 4
+    for outcome in outcomes:
+        assert outcome.content[0].text.startswith("done:")
+
+
+async def test_concurrent_foreground_tools_with_progress():
+    """Multiple concurrent tool calls sharing the same Progress() default
+    should not raise AssertionError from _impl being None (#3656)."""
+    mcp = FastMCP("test")
+
+    @mcp.tool()
+    async def variable_tool(
+        name: str, delay: float, progress: Progress = Progress()
+    ) -> str:
+        await progress.set_total(3)
+        await progress.increment()
+        await asyncio.sleep(delay)
+        await progress.increment()
+        await progress.set_message(f"finishing {name}")
+        await progress.increment()
+        return f"done:{name}"
+
+    async with Client(mcp) as client:
+        tasks = [
+            client.call_tool(
+                "variable_tool", {"name": f"t-{i}", "delay": 0.01 * (i + 1)}
+            )
+            for i in range(4)
+        ]
+        outcomes = await asyncio.gather(*tasks)
+
+    assert len(outcomes) == 4
+    for outcome in outcomes:
+        assert outcome.content[0].text.startswith("done:")
+
+
+async def test_concurrent_background_tasks_with_context():
+    """Multiple concurrent background tasks sharing _CurrentContext() should
+    not raise ValueError from ContextVar token resets (#3654)."""
+    mcp = FastMCP("test")
+
+    @mcp.tool(task=True)
+    async def bg_tool(name: str, ctx: Context) -> str:
+        await asyncio.sleep(0.05)
+        return f"bg:{name}"
+
+    async with Client(mcp) as client:
+        task_handles = [
+            await client.call_tool("bg_tool", {"name": f"bg-{i}"}, task=True)
+            for i in range(4)
+        ]
+        results = await asyncio.gather(*[t.result() for t in task_handles])
+
+    assert len(results) == 4
+    for result in results:
+        assert result.content[0].text.startswith("bg:")
+
+
+async def test_concurrent_background_tasks_with_progress():
+    """Multiple concurrent background tasks sharing Progress() should
+    not raise AssertionError from _impl being None (#3656)."""
+    mcp = FastMCP("test")
+
+    @mcp.tool(task=True)
+    async def bg_progress_tool(
+        name: str, delay: float, progress: Progress = Progress()
+    ) -> str:
+        await progress.set_total(3)
+        await progress.increment()
+        await asyncio.sleep(delay)
+        await progress.increment()
+        await progress.set_message(f"bg finishing {name}")
+        await progress.increment()
+        return f"bg:{name}"
+
+    async with Client(mcp) as client:
+        task_handles = [
+            await client.call_tool(
+                "bg_progress_tool",
+                {"name": f"bg-{i}", "delay": 0.01 * (i + 1)},
+                task=True,
+            )
+            for i in range(4)
+        ]
+        results = await asyncio.gather(*[t.result() for t in task_handles])
+
+    assert len(results) == 4
+    for result in results:
+        assert result.content[0].text.startswith("bg:")
+
+
+async def test_dependency_aenter_returns_fresh_instances():
+    """Verify that Dependency.__aenter__ returns independent per-invocation
+    objects, not the shared default."""
+    mcp = FastMCP("test")
+
+    instances: list[Context] = []
+
+    @mcp.tool()
+    async def capture_context(ctx: Context) -> str:
+        instances.append(ctx)
+        return "ok"
+
+    async with Client(mcp) as client:
+        await asyncio.gather(
+            client.call_tool("capture_context", {}),
+            client.call_tool("capture_context", {}),
+        )
+
+    assert len(instances) == 2
+    assert instances[0] is not instances[1]
+
+
+async def test_progress_aenter_returns_fresh_instances():
+    """Verify that Progress.__aenter__ returns independent per-invocation
+    objects, not the shared default."""
+    progress_instances: list[Progress] = []
+
+    mcp = FastMCP("test")
+
+    @mcp.tool()
+    async def capture_progress(progress: Progress = Progress()) -> str:
+        progress_instances.append(progress)
+        await progress.set_total(1)
+        await progress.increment()
+        return "ok"
+
+    async with Client(mcp) as client:
+        await asyncio.gather(
+            client.call_tool("capture_progress", {}),
+            client.call_tool("capture_progress", {}),
+        )
+
+    assert len(progress_instances) == 2
+    assert progress_instances[0] is not progress_instances[1]
+    assert progress_instances[0]._impl is not progress_instances[1]._impl
+
+
+async def test_sync_context_functions_work_in_background_without_deps():
+    """Sync functions like get_http_request() should work in background tasks
+    even when the tool declares no Context or CurrentRequest dependency.
+
+    This exercises the sync Redis fallback path (_get_task_snapshot_sync →
+    _load_snapshot_sync_redis) which must work with both memory:// (fakeredis)
+    and real Redis backends.
+    """
+    mcp = FastMCP("test")
+
+    @mcp.tool(task=True)
+    async def bare_sync_access() -> dict[str, str]:
+        headers = get_http_headers()
+        return {"has_headers": str(bool(headers))}
+
+    async with Client(mcp) as client:
+        task = await client.call_tool("bare_sync_access", {}, task=True)
+        result = await task.result()
+        assert result.data == {"has_headers": "False"}
+
+
+async def test_sync_context_functions_work_in_background_with_context():
+    """Sync functions work via ContextVar when _CurrentContext loads the snapshot."""
+    mcp = FastMCP("test")
+
+    @mcp.tool(task=True)
+    async def context_sync_access(ctx: Context) -> dict[str, str]:
+        headers = get_http_headers()
+        token = get_access_token()
+        return {
+            "has_headers": str(bool(headers)),
+            "has_token": str(token is not None),
+            "is_background": str(ctx.is_background_task),
+        }
+
+    async with Client(mcp) as client:
+        task = await client.call_tool("context_sync_access", {}, task=True)
+        result = await task.result()
+        assert result.data["is_background"] == "True"
diff --git a/tests/server/tasks/test_context_background_task.py b/tests/server/tasks/test_context_background_task.py
new file mode 100644
index 0000000..e0b8b3d
--- /dev/null
+++ b/tests/server/tasks/test_context_background_task.py
@@ -0,0 +1,656 @@
+"""Tests for Context background task support (SEP-1686).
+
+Tests Context API surface (unit) and background task elicitation (integration).
+Integration tests use Client(mcp) with the real memory:// Docket backend —
+no mocking of Redis, Docket, or session internals.
+"""
+
+import asyncio
+import json
+from datetime import datetime, timezone
+from typing import Any, cast
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from mcp import ServerSession
+from mcp.server.auth.middleware.auth_context import auth_context_var
+from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser
+from mcp_types import (
+    ClientCapabilities,
+    CreateMessageResult,
+    Implementation,
+    InitializeRequestParams,
+    TextContent,
+)
+from pydantic import BaseModel
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.elicitation import ElicitResult
+from fastmcp.dependencies import CurrentDocket
+from fastmcp.server.auth import AccessToken
+from fastmcp.server.context import Context
+from fastmcp.server.dependencies import get_access_token
+from fastmcp.server.elicitation import (
+    AcceptedElicitation,
+    CancelledElicitation,
+    DeclinedElicitation,
+)
+from fastmcp.server.tasks.context import (
+    TaskContextInfo,
+    TaskContextSnapshot,
+    _remember_snapshot,
+    get_task_scope,
+)
+from fastmcp.server.tasks.elicitation import handle_task_input
+from fastmcp.server.tasks.keys import (
+    task_redis_prefix,
+)
+
+# =============================================================================
+# Unit tests: Context API surface (no Redis/Docket needed)
+# =============================================================================
+
+
+class TestContextBackgroundTaskSupport:
+    """Tests for Context.is_background_task and related functionality."""
+
+    def test_context_not_background_task_by_default(self):
+        """Context should not be a background task by default."""
+        mcp = FastMCP("test")
+        ctx = Context(mcp)
+        assert ctx.is_background_task is False
+        assert ctx.task_id is None
+
+    def test_context_is_background_task_when_task_id_provided(self):
+        """Context should be a background task when task_id is provided."""
+        mcp = FastMCP("test")
+        ctx = Context(mcp, task_id="test-task-123")
+        assert ctx.is_background_task is True
+        assert ctx.task_id == "test-task-123"
+
+    def test_context_task_id_is_readonly(self):
+        """task_id should be a read-only property."""
+        mcp = FastMCP("test")
+        ctx = Context(mcp, task_id="test-task-123")
+        with pytest.raises(AttributeError):
+            setattr(ctx, "task_id", "new-id")
+
+
+class TestContextSessionProperty:
+    """Tests for Context.session property in different modes."""
+
+    def test_session_raises_when_no_session_available(self):
+        """session should raise RuntimeError when no session is available."""
+        mcp = FastMCP("test")
+        ctx = Context(mcp)  # No session, not a background task
+
+        with pytest.raises(RuntimeError, match="session is not available"):
+            _ = ctx.session
+
+    def test_session_uses_stored_session_in_background_task(self):
+        """session should use _session in background task mode."""
+        mcp = FastMCP("test")
+
+        class MockSession:
+            _fastmcp_state_prefix = "test-session"
+
+        mock_session = MockSession()
+        ctx = Context(
+            mcp, session=cast(ServerSession, mock_session), task_id="test-task-123"
+        )
+
+        assert ctx.session is mock_session
+
+    def test_session_uses_stored_session_during_on_initialize(self):
+        """session should use _session during on_initialize (no request context)."""
+        mcp = FastMCP("test")
+
+        class MockSession:
+            _fastmcp_state_prefix = "test-session"
+
+        mock_session = MockSession()
+        ctx = Context(mcp, session=cast(ServerSession, mock_session))
+
+        assert ctx.session is mock_session
+
+
+class TestContextBackgroundTaskLogging:
+    """Tests for per-session log gating in background task mode."""
+
+    def _make_task_context(
+        self, mcp: FastMCP, session_id: str
+    ) -> tuple[Context, AsyncMock]:
+        send_log_message = AsyncMock()
+
+        class MockConnection:
+            def __init__(self, session_id: str) -> None:
+                self.session_id = session_id
+
+        class MockSession:
+            def __init__(self, session_id: str) -> None:
+                self._connection = MockConnection(session_id)
+                self._fastmcp_state_prefix = session_id
+                self.send_log_message = send_log_message
+
+        session = MockSession(session_id)
+        ctx = Context(
+            mcp, session=cast(ServerSession, session), task_id="test-task-123"
+        )
+        return ctx, send_log_message
+
+    async def test_background_task_honors_session_level(self):
+        """A background task has a session but no request context; the
+        per-session minimum registered via logging/setLevel must still gate
+        its logs, so sub-threshold messages are not sent to the client."""
+        mcp = FastMCP("test")
+        session_id = "session-abc"
+        mcp._client_log_levels[session_id] = "error"
+
+        ctx, send_log_message = self._make_task_context(mcp, session_id)
+        assert ctx.is_background_task is True
+        assert ctx.request_context is None
+
+        await ctx.info("info msg")
+        send_log_message.assert_not_called()
+
+        await ctx.error("error msg")
+        send_log_message.assert_called_once()
+
+    async def test_background_task_without_session_level_sends_all(self):
+        """When no per-session level is registered, background-task logs fall
+        back to the server default (which allows everything by default)."""
+        mcp = FastMCP("test")
+        ctx, send_log_message = self._make_task_context(mcp, "session-xyz")
+
+        await ctx.info("info msg")
+        send_log_message.assert_called_once()
+
+
+class TestContextClientExtensionBackgroundTask:
+    """Tests for Context.client_supports_extension() in background task mode.
+
+    A background task has a live snapshot session but no request context. The
+    client's advertised capabilities are preserved on the snapshot session's
+    ``client_params``, so extension detection must read from the session rather
+    than gating on ``request_context``.
+    """
+
+    def _make_task_context(
+        self, mcp: FastMCP, extensions: dict[str, dict[str, Any]] | None
+    ) -> Context:
+        capabilities = ClientCapabilities(extensions=extensions)
+        client_params = InitializeRequestParams(
+            protocol_version="2025-06-18",
+            capabilities=capabilities,
+            client_info=Implementation(name="test-client", version="1.0"),
+        )
+
+        class MockSession:
+            _fastmcp_state_prefix = "session-ext"
+
+            def __init__(self) -> None:
+                self.client_params = client_params
+
+        session = MockSession()
+        return Context(
+            mcp, session=cast(ServerSession, session), task_id="test-task-ext"
+        )
+
+    def test_background_task_detects_advertised_extension(self):
+        """The snapshot session preserves the client's initialize params, so an
+        advertised extension is detected even with no request context."""
+        mcp = FastMCP("test")
+        ctx = self._make_task_context(mcp, {"ext-abc": {}})
+
+        assert ctx.is_background_task is True
+        assert ctx.request_context is None
+        assert ctx.client_supports_extension("ext-abc") is True
+        assert ctx.client_supports_extension("ext-missing") is False
+
+    def test_background_task_no_extensions_returns_false(self):
+        """When the client advertised no extensions, detection returns False."""
+        mcp = FastMCP("test")
+        ctx = self._make_task_context(mcp, None)
+
+        assert ctx.client_supports_extension("ext-abc") is False
+
+    def test_no_session_returns_false(self):
+        """With no session available at all (e.g. distributed worker), the
+        method degrades to False rather than raising."""
+        mcp = FastMCP("test")
+        ctx = Context(mcp, task_id="test-task-ext")
+
+        assert ctx.client_supports_extension("ext-abc") is False
+
+
+class TestContextElicitBackgroundTask:
+    """Tests for Context.elicit() in background task mode."""
+
+    async def test_elicit_raises_when_background_task_but_no_docket(self):
+        """elicit() should raise when in background task mode but Docket unavailable."""
+        mcp = FastMCP("test")
+        ctx = Context(mcp, task_id="test-task-123")
+
+        class MockSession:
+            _fastmcp_state_prefix = "test-session"
+
+        ctx._session = cast(ServerSession, MockSession())
+
+        with pytest.raises(RuntimeError, match="Docket"):
+            await ctx.elicit("Need input", str)
+
+
+class TestElicitFailFast:
+    """Tests for elicit_for_task fail-fast on notification push failure."""
+
+    async def test_elicit_returns_cancel_when_notification_push_fails(self):
+        """elicit_for_task should return cancel immediately when push_notification fails.
+
+        If the client can't receive the input_required notification, waiting
+        for a response that will never come would block for up to 1 hour.
+        Instead, we return cancel immediately (fail-fast).
+
+        This test patches ONLY push_notification — all other components
+        (Docket, Redis, session) are real via the memory:// backend.
+        """
+        mcp = FastMCP("failfast-test")
+        elicit_started = asyncio.Event()
+        captured: dict[str, object] = {}
+
+        @mcp.tool(task=True)
+        async def failfast_tool(ctx: Context) -> str:
+            elicit_started.set()
+            result = await ctx.elicit("This notification will fail", str)
+            captured["result_type"] = type(result).__name__
+            captured["is_cancelled"] = isinstance(result, CancelledElicitation)
+            return "done"
+
+        # Patch push_notification BEFORE starting client so it's active
+        # when the tool runs in the Docket worker
+        with patch(
+            "fastmcp.server.tasks.notifications.push_notification",
+            side_effect=ConnectionError("Redis queue unavailable"),
+        ):
+            async with Client(mcp) as client:
+                task = await client.call_tool("failfast_tool", {}, task=True)
+                await asyncio.wait_for(elicit_started.wait(), timeout=5.0)
+                await task.wait(timeout=10.0)
+                result = await task.result()
+                assert result.data == "done"
+
+        # The tool should have received CancelledElicitation (fail-fast)
+        assert captured["is_cancelled"] is True
+        assert captured["result_type"] == "CancelledElicitation"
+
+
+class TestContextDocumentation:
+    """Tests to verify Context documentation and API surface."""
+
+    def test_is_background_task_has_docstring(self):
+        """is_background_task property should have documentation."""
+        assert Context.is_background_task.__doc__ is not None
+        assert "background task" in Context.is_background_task.__doc__.lower()
+
+    def test_task_id_has_docstring(self):
+        """task_id property should have documentation."""
+        assert Context.task_id.fget.__doc__ is not None
+        assert "task ID" in Context.task_id.fget.__doc__
+
+    def test_session_has_docstring(self):
+        """session property should document background task support."""
+        assert Context.session.fget.__doc__ is not None
+        assert "background task" in Context.session.fget.__doc__.lower()
+
+
+# =============================================================================
+# Integration tests: Client(mcp) + memory:// Docket backend
+# =============================================================================
+
+
+class TestBackgroundTaskIntegration:
+    """Integration tests for background task context using real Docket memory backend.
+
+    These tests use Client(mcp) with the memory:// broker — no mocking.
+    The memory:// backend provides a fully functional in-memory Redis store
+    that Docket uses automatically when running tests.
+    """
+
+    async def test_report_progress_in_background_task(self):
+        """report_progress() should complete without error in a background task."""
+        mcp = FastMCP("progress-test")
+        progress_reported = asyncio.Event()
+
+        @mcp.tool(task=True)
+        async def progress_tool(ctx: Context) -> str:
+            await ctx.report_progress(0, 100, "Starting...")
+            await ctx.report_progress(50, 100, "Half done")
+            await ctx.report_progress(100, 100, "Complete")
+            progress_reported.set()
+            return "done"
+
+        async with Client(mcp) as client:
+            task = await client.call_tool("progress_tool", {}, task=True)
+            await asyncio.wait_for(progress_reported.wait(), timeout=5.0)
+            await task.wait(timeout=5.0)
+            result = await task.result()
+            assert result.data == "done"
+
+    async def test_context_wiring_in_background_task(self):
+        """Context should be properly wired with task_id and session_id."""
+        mcp = FastMCP("wiring-test")
+        task_completed = asyncio.Event()
+        captured: dict[str, object] = {}
+
+        @mcp.tool(task=True)
+        async def verify_wiring(ctx: Context) -> str:
+            captured["task_id"] = ctx.task_id
+            captured["session_id"] = ctx.session_id
+            captured["is_background"] = ctx.is_background_task
+            task_completed.set()
+            return "ok"
+
+        async with Client(mcp) as client:
+            task = await client.call_tool("verify_wiring", {}, task=True)
+            await asyncio.wait_for(task_completed.wait(), timeout=5.0)
+            await task.wait(timeout=5.0)
+            result = await task.result()
+            assert result.data == "ok"
+
+        assert captured["task_id"] is not None
+        assert captured["session_id"] is not None
+        assert captured["is_background"] is True
+
+    async def test_origin_request_id_round_trips_through_background_task(self):
+        """E2E: origin_request_id captured at submit time is restored in worker.
+
+        We validate this by comparing ctx.origin_request_id with the value
+        stored in Docket's Redis for this task.
+        """
+
+        mcp = FastMCP("origin-request-id-roundtrip")
+
+        @mcp.tool(task=True)
+        async def check_origin_request_id(ctx: Context, docket=CurrentDocket()) -> str:
+            assert ctx.is_background_task is True
+            assert ctx.request_context is None
+            assert ctx.task_id is not None
+
+            origin = ctx.origin_request_id
+            assert origin is not None
+            assert isinstance(origin, str)
+            assert origin != ""
+
+            # Verify the snapshot in Redis contains the same value
+            task_scope = get_task_scope()
+            key = docket.key(f"{task_redis_prefix(task_scope)}:{ctx.task_id}:snapshot")
+            async with docket.redis() as redis:
+                raw = await redis.get(key)
+
+            assert raw is not None
+            if isinstance(raw, bytes):
+                raw = raw.decode()
+            snapshot = json.loads(raw)
+            assert snapshot["origin_request_id"] == origin
+            return "ok"
+
+        async with Client(mcp) as client:
+            task = await client.call_tool("check_origin_request_id", {}, task=True)
+            result = await task.result()
+            assert result.data == "ok"
+
+    @pytest.mark.xfail(
+        reason="Background-task sampling has no back-channel under SDK v2: the "
+        "per-request ServerSession that would carry sampling/createMessage is "
+        "gone once the submitting request completes, so ctx.sample() from a "
+        "worker raises NoBackChannelError. Needs a relay like elicit() "
+        "(context.py TODO); tracked in sdk-feedback.",
+        strict=True,
+    )
+    async def test_sample_uses_origin_request_id_in_background_task(self):
+        """E2E: ctx.sample() works in a task without an active request context."""
+        mcp = FastMCP("sample-background-test")
+        captured: dict[str, object] = {}
+
+        @mcp.tool(task=True)
+        async def ask_client(ctx: Context) -> str:
+            assert ctx.is_background_task is True
+            assert ctx.request_context is None
+            assert ctx.origin_request_id is not None
+            result = await ctx.sample("Say hello")
+            return result.text or ""
+
+        def sampling_handler(messages, params, ctx):
+            captured["called"] = True
+            return CreateMessageResult(
+                role="assistant",
+                content=TextContent(type="text", text="hello from background"),
+                model="test-model",
+                stop_reason="endTurn",
+            )
+
+        async with Client(mcp, sampling_handler=sampling_handler) as client:
+            task = await client.call_tool("ask_client", {}, task=True)
+            result = await task.result()
+
+        assert result.data == "hello from background"
+        assert captured["called"] is True
+
+    async def test_elicit_accept_flow(self):
+        """E2E: tool elicits input, client accepts via elicitation_handler."""
+        mcp = FastMCP("elicit-accept-test")
+
+        @mcp.tool(task=True)
+        async def ask_name(ctx: Context) -> str:
+            result = await ctx.elicit("What is your name?", str)
+            if isinstance(result, AcceptedElicitation):
+                return f"Hello, {result.data}!"
+            return "No name provided"
+
+        async def handler(message, response_type, params, ctx):
+            return ElicitResult(action="accept", content={"value": "Bob"})
+
+        async with Client(mcp, elicitation_handler=handler) as client:
+            task = await client.call_tool("ask_name", {}, task=True)
+            await task.wait(timeout=10.0)
+            result = await task.result()
+            assert result.data == "Hello, Bob!"
+
+    async def test_elicit_decline_flow(self):
+        """E2E: tool elicits input, client declines via elicitation_handler."""
+        mcp = FastMCP("elicit-decline-test")
+
+        @mcp.tool(task=True)
+        async def optional_input(ctx: Context) -> str:
+            result = await ctx.elicit("Want to provide a name?", str)
+            if isinstance(result, DeclinedElicitation):
+                return "User declined"
+            if isinstance(result, AcceptedElicitation):
+                return f"Got: {result.data}"
+            return "Cancelled"
+
+        async def handler(message, response_type, params, ctx):
+            return ElicitResult(action="decline")
+
+        async with Client(mcp, elicitation_handler=handler) as client:
+            task = await client.call_tool("optional_input", {}, task=True)
+            await task.wait(timeout=10.0)
+            result = await task.result()
+            assert result.data == "User declined"
+
+    async def test_elicit_with_pydantic_model(self):
+        """E2E: tool elicits structured Pydantic input via elicitation_handler."""
+
+        class UserInfo(BaseModel):
+            name: str
+            age: int
+
+        mcp = FastMCP("elicit-pydantic-test")
+
+        @mcp.tool(task=True)
+        async def get_user_info(ctx: Context) -> str:
+            result = await ctx.elicit("Provide user info", UserInfo)
+            if isinstance(result, AcceptedElicitation):
+                assert isinstance(result.data, UserInfo)
+                return f"{result.data.name} is {result.data.age}"
+            return "No info"
+
+        async def handler(message, response_type, params, ctx):
+            return ElicitResult(action="accept", content={"name": "Alice", "age": 30})
+
+        async with Client(mcp, elicitation_handler=handler) as client:
+            task = await client.call_tool("get_user_info", {}, task=True)
+            await task.wait(timeout=10.0)
+            result = await task.result()
+            assert result.data == "Alice is 30"
+
+    async def test_handle_task_input_rejects_when_not_waiting(self):
+        """handle_task_input returns False when no task is waiting for input."""
+        mcp = FastMCP("reject-test")
+
+        @mcp.tool(task=True)
+        async def simple_tool() -> str:
+            return "done"
+
+        async with Client(mcp) as client:
+            task = await client.call_tool("simple_tool", {}, task=True)
+            await task.wait(timeout=5.0)
+
+            # Task already completed — no elicitation waiting
+            success = await handle_task_input(
+                task_id=task.task_id,
+                task_scope="nonexistent-scope",
+                action="accept",
+                content={"value": "too late"},
+                fastmcp=mcp,
+            )
+            assert success is False
+
+
+class TestAccessTokenInBackgroundTasks:
+    """Tests for access token availability in background tasks (#3095).
+
+    Integration tests use Client(mcp) with the real memory:// Docket backend.
+    The token snapshot/restore round-trip flows through actual Redis (fakeredis).
+
+    Note: async tests run in isolated asyncio tasks, so ContextVar changes
+    are automatically scoped — no cleanup required.
+    """
+
+    async def test_token_round_trips_through_background_task(self):
+        """E2E: token set at submit time is available inside the worker."""
+        mcp = FastMCP("token-roundtrip")
+
+        @mcp.tool(task=True)
+        async def check_token(ctx: Context) -> str:
+            token = get_access_token()
+            if token is None:
+                return "no-token"
+            return f"{token.token}|{token.client_id}"
+
+        test_token = AccessToken(
+            token="roundtrip-jwt",
+            client_id="test-client",
+            scopes=["read"],
+            claims={"sub": "user-1"},
+        )
+        auth_context_var.set(AuthenticatedUser(test_token))
+
+        async with Client(mcp) as client:
+            task = await client.call_tool("check_token", {}, task=True)
+            result = await task.result()
+            assert result.data == "roundtrip-jwt|test-client"
+
+    async def test_no_token_when_unauthenticated(self):
+        """E2E: background task gets no token when nothing was set."""
+        mcp = FastMCP("no-auth")
+
+        @mcp.tool(task=True)
+        async def check_token(ctx: Context) -> str:
+            token = get_access_token()
+            return "no-token" if token is None else token.token
+
+        async with Client(mcp) as client:
+            task = await client.call_tool("check_token", {}, task=True)
+            result = await task.result()
+            assert result.data == "no-token"
+
+    async def test_expired_token_returns_none(self):
+        """get_access_token() returns None when task token has expired."""
+        expired = AccessToken(
+            token="expired-jwt",
+            client_id="test-client",
+            scopes=["read"],
+            expires_at=int(datetime.now(timezone.utc).timestamp()) - 3600,
+        )
+        _remember_snapshot(
+            "test-task",
+            TaskContextSnapshot(access_token_json=expired.model_dump_json()),
+        )
+        fake_ctx = TaskContextInfo(task_id="test-task", task_scope="s")
+        with patch(
+            "fastmcp.server.dependencies.get_task_context", return_value=fake_ctx
+        ):
+            assert get_access_token() is None
+
+    async def test_valid_token_with_future_expiry(self):
+        """get_access_token() returns token when expiry is in the future."""
+        valid = AccessToken(
+            token="valid-jwt",
+            client_id="test-client",
+            scopes=["read"],
+            expires_at=int(datetime.now(timezone.utc).timestamp()) + 3600,
+        )
+        _remember_snapshot(
+            "test-task",
+            TaskContextSnapshot(access_token_json=valid.model_dump_json()),
+        )
+        fake_ctx = TaskContextInfo(task_id="test-task", task_scope="s")
+        with patch(
+            "fastmcp.server.dependencies.get_task_context", return_value=fake_ctx
+        ):
+            result = get_access_token()
+            assert result is not None
+            assert result.token == "valid-jwt"
+
+    async def test_token_without_expiry_always_valid(self):
+        """get_access_token() returns token when no expires_at is set."""
+        no_expiry = AccessToken(
+            token="eternal-jwt",
+            client_id="test-client",
+            scopes=["read"],
+        )
+        _remember_snapshot(
+            "test-task",
+            TaskContextSnapshot(access_token_json=no_expiry.model_dump_json()),
+        )
+        fake_ctx = TaskContextInfo(task_id="test-task", task_scope="s")
+        with patch(
+            "fastmcp.server.dependencies.get_task_context", return_value=fake_ctx
+        ):
+            result = get_access_token()
+            assert result is not None
+            assert result.token == "eternal-jwt"
+
+
+class TestLifespanContextInBackgroundTasks:
+    """Tests for lifespan_context availability in background tasks (#3095)."""
+
+    def test_lifespan_context_falls_back_to_server_result(self):
+        """lifespan_context reads from server when request_context is None."""
+        mcp = FastMCP("test")
+        mcp._lifespan_result = {"db": "mock-db-connection", "cache": "mock-cache"}
+
+        ctx = Context(mcp, task_id="test-task")
+        assert ctx.request_context is None
+        assert ctx.lifespan_context == {
+            "db": "mock-db-connection",
+            "cache": "mock-cache",
+        }
+
+    def test_lifespan_context_returns_empty_dict_when_no_lifespan(self):
+        """lifespan_context returns {} when no lifespan is configured."""
+        mcp = FastMCP("test")
+        ctx = Context(mcp, task_id="test-task")
+        assert ctx.request_context is None
+        assert ctx.lifespan_context == {}
diff --git a/tests/server/tasks/test_custom_subclass_tasks.py b/tests/server/tasks/test_custom_subclass_tasks.py
new file mode 100644
index 0000000..2077e06
--- /dev/null
+++ b/tests/server/tasks/test_custom_subclass_tasks.py
@@ -0,0 +1,184 @@
+"""Tests for custom component subclasses with task support.
+
+Verifies that custom Tool, Resource, and Prompt subclasses can use
+background task execution by setting task_config.
+"""
+
+import asyncio
+from typing import Any
+from unittest.mock import MagicMock
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.tasks import TaskConfig
+from fastmcp.tools.base import Tool, ToolResult
+from fastmcp.utilities.components import FastMCPComponent
+
+
+class CustomTool(Tool):
+    """A custom tool subclass with task support."""
+
+    task_config: TaskConfig = TaskConfig(mode="optional")
+    parameters: dict[str, Any] = {"type": "object", "properties": {}}
+
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
+        return ToolResult(content=f"Custom tool executed with {arguments}")
+
+
+class CustomToolWithLogic(Tool):
+    """A custom tool with actual async work."""
+
+    task_config: TaskConfig = TaskConfig(mode="optional")
+    parameters: dict[str, Any] = {
+        "type": "object",
+        "properties": {"duration": {"type": "integer"}},
+    }
+
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
+        duration = arguments.get("duration", 0)
+        await asyncio.sleep(duration * 0.01)  # Short sleep for testing
+        return ToolResult(content=f"Completed after {duration} units")
+
+
+class CustomToolForbidden(Tool):
+    """A custom tool with task_config forbidden (default)."""
+
+    parameters: dict[str, Any] = {"type": "object", "properties": {}}
+
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
+        return ToolResult(content="Sync only")
+
+
+@pytest.fixture
+def custom_tool_server():
+    """Create a server with custom tool subclasses."""
+    mcp = FastMCP("custom-tool-server")
+    mcp.add_tool(CustomTool(name="custom_tool", description="A custom tool"))
+    mcp.add_tool(
+        CustomToolWithLogic(name="custom_logic", description="Custom tool with logic")
+    )
+    mcp.add_tool(
+        CustomToolForbidden(name="custom_forbidden", description="No task support")
+    )
+    return mcp
+
+
+async def test_custom_tool_sync_execution(custom_tool_server):
+    """Custom tool executes synchronously when no task metadata."""
+    async with Client(custom_tool_server) as client:
+        result = await client.call_tool("custom_tool", {})
+        assert "Custom tool executed" in str(result)
+
+
+async def test_custom_tool_background_execution(custom_tool_server):
+    """Custom tool executes as background task when task=True."""
+    async with Client(custom_tool_server) as client:
+        task = await client.call_tool("custom_tool", {}, task=True)
+
+        assert task is not None
+        assert not task.returned_immediately
+        assert task.task_id is not None
+
+        # Wait for result
+        result = await task.result()
+        assert "Custom tool executed" in str(result)
+
+
+async def test_custom_tool_with_arguments(custom_tool_server):
+    """Custom tool receives arguments correctly in background execution."""
+    async with Client(custom_tool_server) as client:
+        task = await client.call_tool("custom_logic", {"duration": 1}, task=True)
+
+        assert task is not None
+        result = await task.result()
+        assert "Completed after 1 units" in str(result)
+
+
+async def test_custom_tool_forbidden_sync_only(custom_tool_server):
+    """Custom tool with forbidden mode executes sync only."""
+    async with Client(custom_tool_server) as client:
+        # Sync execution works
+        result = await client.call_tool("custom_forbidden", {})
+        assert "Sync only" in str(result)
+
+
+async def test_custom_tool_forbidden_rejects_task(custom_tool_server):
+    """Custom tool with forbidden mode returns error for task request."""
+    async with Client(custom_tool_server) as client:
+        task = await client.call_tool("custom_forbidden", {}, task=True)
+
+        # Should return immediately with error
+        assert task.returned_immediately
+
+
+async def test_custom_tool_registers_with_docket():
+    """Verify custom tool's register_with_docket is called during server startup."""
+    from unittest.mock import MagicMock
+
+    tool = CustomTool(name="test", description="test")
+    mock_docket = MagicMock()
+
+    tool.register_with_docket(mock_docket)
+
+    # Should register self.run with docket using prefixed key
+    mock_docket.register.assert_called_once()
+    call_args = mock_docket.register.call_args
+    assert call_args[1]["names"] == ["tool:test@"]
+
+
+async def test_custom_tool_forbidden_does_not_register():
+    """Verify custom tool with forbidden mode doesn't register with docket."""
+    tool = CustomToolForbidden(name="test", description="test")
+    mock_docket = MagicMock()
+
+    tool.register_with_docket(mock_docket)
+
+    # Should NOT register
+    mock_docket.register.assert_not_called()
+
+
+# ==============================================================================
+# Base FastMCPComponent Tests
+# ==============================================================================
+
+
+class TestFastMCPComponentDocketMethods:
+    """Tests for base FastMCPComponent docket integration."""
+
+    def test_default_task_config_is_forbidden(self):
+        """Base component defaults to task_config mode='forbidden'."""
+        component = FastMCPComponent(name="test")
+        assert component.task_config.mode == "forbidden"
+
+    def test_register_with_docket_is_noop(self):
+        """Base register_with_docket does nothing (subclasses override)."""
+        component = FastMCPComponent(name="test")
+        mock_docket = MagicMock()
+
+        # Should not raise, just no-op
+        component.register_with_docket(mock_docket)
+
+        # Should not have called any docket methods
+        mock_docket.register.assert_not_called()
+
+    async def test_add_to_docket_raises_when_forbidden(self):
+        """Base add_to_docket raises RuntimeError when mode is 'forbidden'."""
+        component = FastMCPComponent(name="test")
+        mock_docket = MagicMock()
+
+        with pytest.raises(RuntimeError, match="task execution not supported"):
+            await component.add_to_docket(mock_docket)
+
+    async def test_add_to_docket_raises_not_implemented_when_allowed(self):
+        """Base add_to_docket raises NotImplementedError when not forbidden."""
+        component = FastMCPComponent(
+            name="test", task_config=TaskConfig(mode="optional")
+        )
+        mock_docket = MagicMock()
+
+        with pytest.raises(
+            NotImplementedError, match="does not implement add_to_docket"
+        ):
+            await component.add_to_docket(mock_docket)
diff --git a/tests/server/tasks/test_notifications.py b/tests/server/tasks/test_notifications.py
new file mode 100644
index 0000000..ca7abfe
--- /dev/null
+++ b/tests/server/tasks/test_notifications.py
@@ -0,0 +1,130 @@
+"""Tests for distributed notification queue (SEP-1686).
+
+Integration tests verify that the notification queue works end-to-end
+using Client(mcp) with the real memory:// Docket backend.
+No mocking of Redis, sessions, or Docket internals.
+"""
+
+import asyncio
+
+import mcp_types
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.elicitation import ElicitResult
+from fastmcp.server.context import Context
+from fastmcp.server.elicitation import AcceptedElicitation
+from fastmcp.server.tasks.notifications import (
+    get_subscriber_count,
+)
+
+
+class TestNotificationIntegration:
+    """Integration tests for the notification queue using real Docket memory backend.
+
+    The elicitation flow validates the full notification pipeline:
+    1. Tool calls ctx.elicit() -> stores request in Redis -> pushes notification
+    2. Subscriber picks up notification -> sends MCP notification to client
+    3. Subscriber relays elicitation/create to client -> handler responds
+    4. Relay pushes response to Redis -> BLPOP wakes tool
+    """
+
+    async def test_notification_delivered_during_elicitation(self):
+        """Full E2E: notification queue delivers input_required metadata to client.
+
+        SDK v2 does not carry `notifications/tasks/status` in any protocol
+        version's core notification tables, so it is delivered through the
+        client's task-status notification binding (routed to Task objects) rather
+        than the message_handler. We observe it via `on_status_change`, whose
+        GetTaskResult carries the notification's `_meta`.
+        """
+        mcp = FastMCP("notification-test")
+        captured: list[mcp_types.GetTaskResult] = []
+
+        @mcp.tool(task=True)
+        async def elicit_tool(ctx: Context) -> str:
+            result = await ctx.elicit("Enter value", str)
+            if isinstance(result, AcceptedElicitation):
+                return f"got: {result.data}"
+            return "no value"
+
+        async def elicitation_handler(message, response_type, params, ctx):
+            return ElicitResult(action="accept", content={"value": "hello"})
+
+        async with Client(
+            mcp,
+            elicitation_handler=elicitation_handler,
+        ) as client:
+            task = await client.call_tool("elicit_tool", {}, task=True)
+            task.on_status_change(captured.append)
+
+            await task.wait(timeout=10.0)
+            result = await task.result()
+            assert result.data == "got: hello"
+
+            # Verify the input_required notification was delivered with metadata
+            notification: mcp_types.GetTaskResult | None = None
+            for candidate in reversed(captured):
+                candidate_meta = candidate.meta
+                related_task = (
+                    candidate_meta.get("io.modelcontextprotocol/related-task")
+                    if isinstance(candidate_meta, dict)
+                    else None
+                )
+                if (
+                    isinstance(related_task, dict)
+                    and related_task.get("status") == "input_required"
+                ):
+                    notification = candidate
+                    break
+
+            assert notification is not None, "expected notifications/tasks/status"
+            task_meta = notification.meta
+            assert isinstance(task_meta, dict)
+
+            related_task = task_meta.get("io.modelcontextprotocol/related-task")
+            assert isinstance(related_task, dict)
+            assert related_task.get("taskId") == task.task_id
+            assert related_task.get("status") == "input_required"
+
+            elicitation = related_task.get("elicitation")
+            assert isinstance(elicitation, dict)
+            assert elicitation.get("message") == "Enter value"
+            assert isinstance(elicitation.get("requestId"), str)
+            assert isinstance(elicitation.get("requestedSchema"), dict)
+
+    async def test_subscriber_started_and_cleaned_up(self):
+        """Subscriber starts during background task and stops when client disconnects."""
+        mcp = FastMCP("subscriber-test")
+        tool_started = asyncio.Event()
+        tool_continue = asyncio.Event()
+
+        @mcp.tool(task=True)
+        async def lifecycle_tool(ctx: Context) -> str:
+            tool_started.set()
+            await asyncio.wait_for(tool_continue.wait(), timeout=10.0)
+            return "done"
+
+        count_before = get_subscriber_count()
+
+        async with Client(mcp) as client:
+            task = await client.call_tool("lifecycle_tool", {}, task=True)
+            await asyncio.wait_for(tool_started.wait(), timeout=5.0)
+
+            # While a background task is running, subscriber should be active
+            count_during = get_subscriber_count()
+            assert count_during > count_before
+
+            # Let the tool complete
+            tool_continue.set()
+            await task.wait(timeout=5.0)
+            result = await task.result()
+            assert result.data == "done"
+
+        # After client disconnects, subscriber should be cleaned up
+        # Allow brief time for async cleanup
+        for _ in range(20):
+            if get_subscriber_count() == count_before:
+                break
+            await asyncio.sleep(0.05)
+        assert get_subscriber_count() == count_before
diff --git a/tests/server/tasks/test_progress_dependency.py b/tests/server/tasks/test_progress_dependency.py
new file mode 100644
index 0000000..6cc3599
--- /dev/null
+++ b/tests/server/tasks/test_progress_dependency.py
@@ -0,0 +1,155 @@
+"""Tests for FastMCP Progress dependency."""
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.dependencies import Progress
+
+
+async def test_progress_in_immediate_execution():
+    """Test Progress dependency when calling tool immediately with Docket enabled."""
+    mcp = FastMCP("test")
+
+    @mcp.tool()
+    async def test_tool(progress: Progress = Progress()) -> str:
+        await progress.set_total(10)
+        await progress.increment()
+        await progress.set_message("Testing")
+        return "done"
+
+    async with Client(mcp) as client:
+        result = await client.call_tool("test_tool", {})
+        from mcp_types import TextContent
+
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "done"
+
+
+async def test_progress_in_background_task():
+    """Test Progress dependency in background task execution."""
+    mcp = FastMCP("test")
+
+    @mcp.tool(task=True)
+    async def test_task(progress: Progress = Progress()) -> str:
+        await progress.set_total(5)
+        await progress.increment()
+        await progress.set_message("Step 1")
+        return "done"
+
+    async with Client(mcp) as client:
+        task = await client.call_tool("test_task", {}, task=True)
+        result = await task.result()
+        from mcp_types import TextContent
+
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "done"
+
+
+async def test_progress_tracks_multiple_increments():
+    """Test that Progress correctly tracks multiple increment calls."""
+    mcp = FastMCP("test")
+
+    @mcp.tool()
+    async def count_to_ten(progress: Progress = Progress()) -> str:
+        await progress.set_total(10)
+        for i in range(10):
+            await progress.increment()
+        return "counted"
+
+    async with Client(mcp) as client:
+        result = await client.call_tool("count_to_ten", {})
+        from mcp_types import TextContent
+
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "counted"
+
+
+async def test_progress_status_message_in_background_task():
+    """Regression test: TaskStatusResponse must include statusMessage field."""
+    import asyncio
+
+    mcp = FastMCP("test")
+    step_started = asyncio.Event()
+
+    @mcp.tool(task=True)
+    async def task_with_progress(progress: Progress = Progress()) -> str:
+        await progress.set_total(3)
+        await progress.set_message("Step 1 of 3")
+        await progress.increment()
+        step_started.set()
+
+        # Give test time to poll status
+        await asyncio.sleep(0.2)
+
+        await progress.set_message("Step 2 of 3")
+        await progress.increment()
+        await progress.set_message("Step 3 of 3")
+        await progress.increment()
+        return "done"
+
+    async with Client(mcp) as client:
+        task = await client.call_tool("task_with_progress", {}, task=True)
+
+        # Wait for first step to start
+        await step_started.wait()
+
+        # Get status and verify progress message
+        status = await task.status()
+
+        # Verify statusMessage field is accessible and contains progress info
+        # Should not raise AttributeError
+        msg = status.status_message
+        assert msg is None or msg.startswith("Step")
+
+        # Wait for completion
+        result = await task.result()
+        from mcp_types import TextContent
+
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "done"
+
+
+async def test_inmemory_progress_state():
+    """Test that in-memory progress stores and returns state correctly."""
+    mcp = FastMCP("test")
+
+    @mcp.tool()
+    async def test_tool(progress: Progress = Progress()) -> dict:
+        # Initial state
+        assert progress.current is None
+        assert progress.total == 1
+        assert progress.message is None
+
+        # Set total
+        await progress.set_total(10)
+        assert progress.total == 10
+
+        # Increment
+        await progress.increment()
+        assert progress.current == 1
+
+        # Increment again
+        await progress.increment(2)
+        assert progress.current == 3
+
+        # Set message
+        await progress.set_message("Testing")
+        assert progress.message == "Testing"
+
+        return {
+            "current": progress.current,
+            "total": progress.total,
+            "message": progress.message,
+        }
+
+    async with Client(mcp) as client:
+        result = await client.call_tool("test_tool", {})
+        from mcp_types import TextContent
+
+        assert isinstance(result.content[0], TextContent)
+        # The tool returns a dict showing the final state
+        import json
+
+        state = json.loads(result.content[0].text)
+        assert state["current"] == 3
+        assert state["total"] == 10
+        assert state["message"] == "Testing"
diff --git a/tests/server/tasks/test_resource_task_meta_parameter.py b/tests/server/tasks/test_resource_task_meta_parameter.py
new file mode 100644
index 0000000..86d36b3
--- /dev/null
+++ b/tests/server/tasks/test_resource_task_meta_parameter.py
@@ -0,0 +1,287 @@
+"""
+Tests for the explicit task_meta parameter on FastMCP.read_resource().
+
+These tests verify that the task_meta parameter provides explicit control
+over sync vs task execution for resources and resource templates.
+"""
+
+import pytest
+from mcp.shared.exceptions import MCPError
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.resources.base import Resource
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.tasks.config import TaskMeta
+
+
+class TestResourceTaskMetaParameter:
+    """Tests for task_meta parameter on FastMCP.read_resource()."""
+
+    async def test_task_meta_none_returns_resource_result(self):
+        """With task_meta=None (default), read_resource returns ResourceResult."""
+        server = FastMCP("test")
+
+        @server.resource("data://test")
+        async def simple_resource() -> str:
+            return "hello world"
+
+        result = await server.read_resource("data://test")
+
+        assert result.contents[0].content == "hello world"
+
+    async def test_task_meta_none_on_task_enabled_resource_still_returns_result(self):
+        """Even for task=True resources, task_meta=None returns ResourceResult."""
+        server = FastMCP("test")
+
+        @server.resource("data://test", task=True)
+        async def task_enabled_resource() -> str:
+            return "hello world"
+
+        # Without task_meta, should execute synchronously
+        result = await server.read_resource("data://test")
+
+        assert result.contents[0].content == "hello world"
+
+    async def test_task_meta_on_forbidden_resource_raises_error(self):
+        """Providing task_meta to a task=False resource raises MCPError."""
+        server = FastMCP("test")
+
+        @server.resource("data://test", task=False)
+        async def sync_only_resource() -> str:
+            return "hello"
+
+        with pytest.raises(MCPError) as exc_info:
+            await server.read_resource("data://test", task_meta=TaskMeta())
+
+        assert "does not support task-augmented execution" in str(exc_info.value)
+
+    async def test_task_meta_fn_key_enrichment_for_resource(self):
+        """Verify that fn_key enrichment uses Resource.make_key()."""
+        resource_uri = "data://my-resource"
+        expected_key = Resource.make_key(resource_uri)
+
+        assert expected_key == "resource:data://my-resource"
+
+    async def test_task_meta_fn_key_enrichment_for_template(self):
+        """Verify that fn_key enrichment uses ResourceTemplate.make_key()."""
+        template_pattern = "data://{id}"
+        expected_key = ResourceTemplate.make_key(template_pattern)
+
+        assert expected_key == "template:data://{id}"
+
+
+class TestResourceTemplateTaslMeta:
+    """Tests for task_meta with resource templates."""
+
+    async def test_template_task_meta_none_returns_resource_result(self):
+        """With task_meta=None, template read returns ResourceResult."""
+        server = FastMCP("test")
+
+        @server.resource("item://{id}")
+        async def get_item(id: str) -> str:
+            return f"Item {id}"
+
+        result = await server.read_resource("item://42")
+
+        assert result.contents[0].content == "Item 42"
+
+    async def test_template_task_meta_on_task_enabled_template_returns_result(self):
+        """Even for task=True templates, task_meta=None returns ResourceResult."""
+        server = FastMCP("test")
+
+        @server.resource("item://{id}", task=True)
+        async def get_item(id: str) -> str:
+            return f"Item {id}"
+
+        # Without task_meta, should execute synchronously
+        result = await server.read_resource("item://42")
+
+        assert result.contents[0].content == "Item 42"
+
+    async def test_template_task_meta_on_forbidden_template_raises_error(self):
+        """Providing task_meta to a task=False template raises MCPError."""
+        server = FastMCP("test")
+
+        @server.resource("item://{id}", task=False)
+        async def sync_only_template(id: str) -> str:
+            return f"Item {id}"
+
+        with pytest.raises(MCPError) as exc_info:
+            await server.read_resource("item://42", task_meta=TaskMeta())
+
+        assert "does not support task-augmented execution" in str(exc_info.value)
+
+
+class TestResourceTaskMetaClientIntegration:
+    """Tests that task_meta works correctly with the Client for resources."""
+
+    async def test_client_read_resource_without_task_gets_immediate_result(self):
+        """Client without task=True gets immediate result."""
+        server = FastMCP("test")
+
+        @server.resource("data://test", task=True)
+        async def immediate_resource() -> str:
+            return "hello"
+
+        async with Client(server) as client:
+            result = await client.read_resource("data://test")
+
+            # Should get ReadResourceResult directly
+            assert "hello" in str(result)
+
+    async def test_client_read_resource_with_task_creates_task(self):
+        """Client with task=True creates a background task."""
+        server = FastMCP("test")
+
+        @server.resource("data://test", task=True)
+        async def task_resource() -> str:
+            return "hello"
+
+        async with Client(server) as client:
+            from fastmcp.client.tasks import ResourceTask
+
+            task = await client.read_resource("data://test", task=True)
+
+            assert isinstance(task, ResourceTask)
+
+            # Wait for result
+            result = await task.result()
+            assert "hello" in str(result)
+
+    async def test_client_read_template_with_task_creates_task(self):
+        """Client with task=True on template creates a background task."""
+        server = FastMCP("test")
+
+        @server.resource("item://{id}", task=True)
+        async def get_item(id: str) -> str:
+            return f"Item {id}"
+
+        async with Client(server) as client:
+            from fastmcp.client.tasks import ResourceTask
+
+            task = await client.read_resource("item://42", task=True)
+
+            assert isinstance(task, ResourceTask)
+
+            # Wait for result
+            result = await task.result()
+            assert "Item 42" in str(result)
+
+
+class TestResourceTaskMetaDirectServerCall:
+    """Tests for direct server read_resource calls with task_meta."""
+
+    async def test_resource_can_read_another_resource_with_task(self):
+        """A resource can read another resource as a background task."""
+        server = FastMCP("test")
+
+        @server.resource("data://inner", task=True)
+        async def inner_resource() -> str:
+            return "inner data"
+
+        @server.tool
+        async def outer_tool() -> str:
+            # Read inner resource as background task
+            result = await server.read_resource("data://inner", task_meta=TaskMeta())
+            # Should get CreateTaskResult since we provided task_meta
+            return f"Created task: {result.task.task_id}"
+
+        async with Client(server) as client:
+            result = await client.call_tool("outer_tool", {})
+            assert "Created task:" in str(result)
+
+    async def test_resource_can_read_another_resource_synchronously(self):
+        """A resource can read another resource synchronously (no task_meta)."""
+        server = FastMCP("test")
+
+        @server.resource("data://inner", task=True)
+        async def inner_resource() -> str:
+            return "inner data"
+
+        @server.tool
+        async def outer_tool() -> str:
+            # Read inner resource synchronously (no task_meta)
+            result = await server.read_resource("data://inner")
+            # Should get ResourceResult directly
+            return f"Got result: {result.contents[0].content}"
+
+        async with Client(server) as client:
+            result = await client.call_tool("outer_tool", {})
+            assert "Got result: inner data" in str(result)
+
+    async def test_resource_can_read_template_with_task(self):
+        """A tool can read a resource template as a background task."""
+        server = FastMCP("test")
+
+        @server.resource("item://{id}", task=True)
+        async def get_item(id: str) -> str:
+            return f"Item {id}"
+
+        @server.tool
+        async def outer_tool() -> str:
+            result = await server.read_resource("item://99", task_meta=TaskMeta())
+            return f"Created task: {result.task.task_id}"
+
+        async with Client(server) as client:
+            result = await client.call_tool("outer_tool", {})
+            assert "Created task:" in str(result)
+
+    async def test_resource_can_read_with_custom_ttl(self):
+        """A tool can read a resource as a background task with custom TTL."""
+        server = FastMCP("test")
+
+        @server.resource("data://inner", task=True)
+        async def inner_resource() -> str:
+            return "inner data"
+
+        @server.tool
+        async def outer_tool() -> str:
+            custom_ttl = 45000  # 45 seconds
+            result = await server.read_resource(
+                "data://inner", task_meta=TaskMeta(ttl=custom_ttl)
+            )
+            return f"Task TTL: {result.task.ttl}"
+
+        async with Client(server) as client:
+            result = await client.call_tool("outer_tool", {})
+            assert "Task TTL: 45000" in str(result)
+
+
+class TestResourceTaskMetaTypeNarrowing:
+    """Tests for type narrowing based on task_meta parameter."""
+
+    async def test_read_resource_without_task_meta_type_is_resource_result(self):
+        """Calling read_resource without task_meta returns ResourceResult type."""
+        server = FastMCP("test")
+
+        @server.resource("data://test")
+        async def simple_resource() -> str:
+            return "hello"
+
+        # This should type-check as ResourceResult, not the union type
+        result = await server.read_resource("data://test")
+
+        # No isinstance check needed - type is narrowed by overload
+        content = result.contents[0].content
+        assert content == "hello"
+
+    async def test_read_resource_with_task_meta_type_is_create_task_result(self):
+        """Calling read_resource with task_meta returns CreateTaskResult type."""
+        server = FastMCP("test")
+
+        @server.resource("data://test", task=True)
+        async def task_resource() -> str:
+            return "hello"
+
+        async with Client(server) as client:
+            # Need to use client to get full task infrastructure
+            from fastmcp.client.tasks import ResourceTask
+
+            task = await client.read_resource("data://test", task=True)
+            assert isinstance(task, ResourceTask)
+
+            # For direct server call, we need the Client context for Docket
+            # This test verifies the overload works via client integration
+            result = await task.result()
+            assert "hello" in str(result)
diff --git a/tests/server/tasks/test_server_tasks_parameter.py b/tests/server/tasks/test_server_tasks_parameter.py
new file mode 100644
index 0000000..acb3081
--- /dev/null
+++ b/tests/server/tasks/test_server_tasks_parameter.py
@@ -0,0 +1,441 @@
+"""
+Tests for server `tasks` parameter default inheritance.
+
+Verifies that the server's `tasks` parameter correctly sets defaults for all
+components (tools, prompts, resources), and that explicit component-level
+settings properly override the server default.
+"""
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+
+
+@pytest.mark.timeout(10)
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_server_tasks_true_defaults_all_components():
+    """Server with tasks=True makes all components default to supporting tasks."""
+    mcp = FastMCP("test", tasks=True)
+
+    @mcp.tool()
+    async def my_tool() -> str:
+        return "tool result"
+
+    @mcp.prompt()
+    async def my_prompt() -> str:
+        return "prompt result"
+
+    @mcp.resource("test://resource")
+    async def my_resource() -> str:
+        return "resource result"
+
+    async with Client(mcp) as client:
+        # Verify all task-enabled components are registered with docket
+        # Components use prefixed keys: tool:name, prompt:name, resource:uri
+        docket = mcp.docket
+        assert docket is not None
+        assert "tool:my_tool@" in docket.tasks
+        assert "prompt:my_prompt@" in docket.tasks
+        assert "resource:test://resource@" in docket.tasks
+
+        # Tool should support background execution
+        tool_task = await client.call_tool("my_tool", task=True)
+        assert not tool_task.returned_immediately
+
+        # Prompt should support background execution
+        prompt_task = await client.get_prompt("my_prompt", task=True)
+        assert not prompt_task.returned_immediately
+
+        # Resource should support background execution
+        resource_task = await client.read_resource("test://resource", task=True)
+        assert not resource_task.returned_immediately
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_server_tasks_false_defaults_all_components():
+    """Server with tasks=False makes all components default to mode=forbidden."""
+    import pytest
+    from mcp.shared.exceptions import MCPError
+
+    mcp = FastMCP("test", tasks=False)
+
+    @mcp.tool()
+    async def my_tool() -> str:
+        return "tool result"
+
+    @mcp.prompt()
+    async def my_prompt() -> str:
+        return "prompt result"
+
+    @mcp.resource("test://resource")
+    async def my_resource() -> str:
+        return "resource result"
+
+    async with Client(mcp) as client:
+        # Tool with mode="forbidden" returns error when called with task=True
+        tool_task = await client.call_tool("my_tool", task=True, raise_on_error=False)
+        assert tool_task.returned_immediately
+        result = await tool_task.result()
+        assert result.is_error
+        assert "does not support task-augmented execution" in str(result)
+
+        # Prompt with mode="forbidden" raises MCPError when called with task=True
+        with pytest.raises(MCPError):
+            await client.get_prompt("my_prompt", task=True)
+
+        # Resource with mode="forbidden" raises MCPError when called with task=True
+        with pytest.raises(MCPError):
+            await client.read_resource("test://resource", task=True)
+
+
+async def test_server_tasks_none_defaults_to_false():
+    """Server with tasks=None (or omitted) defaults to False."""
+    mcp = FastMCP("test")  # tasks=None, defaults to False
+
+    @mcp.tool()
+    async def my_tool() -> str:
+        return "tool result"
+
+    async with Client(mcp) as client:
+        # Tool should NOT support background execution (mode="forbidden" from default)
+        tool_task = await client.call_tool("my_tool", task=True, raise_on_error=False)
+        assert tool_task.returned_immediately
+        result = await tool_task.result()
+        assert result.is_error
+        assert "does not support task-augmented execution" in str(result)
+
+
+async def test_component_explicit_false_overrides_server_true():
+    """Component with task=False overrides server default of tasks=True."""
+    mcp = FastMCP("test", tasks=True)
+
+    @mcp.tool(task=False)
+    async def no_task_tool() -> str:
+        return "immediate result"
+
+    @mcp.tool()
+    async def default_tool() -> str:
+        return "background result"
+
+    async with Client(mcp) as client:
+        # Verify docket registration matches task settings (prefixed keys)
+        docket = mcp.docket
+        assert docket is not None
+        assert (
+            "tool:no_task_tool@" not in docket.tasks
+        )  # task=False means not registered
+        assert "tool:default_tool@" in docket.tasks  # Inherits tasks=True
+
+        # Explicit False (mode="forbidden") returns error when called with task=True
+        no_task = await client.call_tool(
+            "no_task_tool", task=True, raise_on_error=False
+        )
+        assert no_task.returned_immediately
+        result = await no_task.result()
+        assert result.is_error
+        assert "does not support task-augmented execution" in str(result)
+
+        # Default should support background execution
+        default_task = await client.call_tool("default_tool", task=True)
+        assert not default_task.returned_immediately
+
+
+async def test_component_explicit_true_overrides_server_false():
+    """Component with task=True overrides server default of tasks=False."""
+    mcp = FastMCP("test", tasks=False)
+
+    @mcp.tool(task=True)
+    async def task_tool() -> str:
+        return "background result"
+
+    @mcp.tool()
+    async def default_tool() -> str:
+        return "immediate result"
+
+    async with Client(mcp) as client:
+        # Verify docket registration matches task settings (prefixed keys)
+        docket = mcp.docket
+        assert docket is not None
+        assert "tool:task_tool@" in docket.tasks  # task=True means registered
+        assert "tool:default_tool@" not in docket.tasks  # Inherits tasks=False
+
+        # Explicit True should support background execution despite server default
+        task = await client.call_tool("task_tool", task=True)
+        assert not task.returned_immediately
+
+        # Default (mode="forbidden") returns error when called with task=True
+        default = await client.call_tool(
+            "default_tool", task=True, raise_on_error=False
+        )
+        assert default.returned_immediately
+        result = await default.result()
+        assert result.is_error
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_mixed_explicit_and_inherited():
+    """Mix of explicit True/False/None on different components."""
+    import pytest
+    from mcp.shared.exceptions import MCPError
+
+    mcp = FastMCP("test", tasks=True)  # Server default is True
+
+    @mcp.tool()
+    async def inherited_tool() -> str:
+        return "inherits True"
+
+    @mcp.tool(task=True)
+    async def explicit_true_tool() -> str:
+        return "explicit True"
+
+    @mcp.tool(task=False)
+    async def explicit_false_tool() -> str:
+        return "explicit False"
+
+    @mcp.prompt()
+    async def inherited_prompt() -> str:
+        return "inherits True"
+
+    @mcp.prompt(task=False)
+    async def explicit_false_prompt() -> str:
+        return "explicit False"
+
+    @mcp.resource("test://inherited")
+    async def inherited_resource() -> str:
+        return "inherits True"
+
+    @mcp.resource("test://explicit_false", task=False)
+    async def explicit_false_resource() -> str:
+        return "explicit False"
+
+    async with Client(mcp) as client:
+        # Verify docket registration matches task settings
+        # Components use prefixed keys: tool:name, prompt:name, resource:uri
+        docket = mcp.docket
+        assert docket is not None
+        # task=True (explicit or inherited) means registered (with prefixed keys)
+        assert "tool:inherited_tool@" in docket.tasks
+        assert "tool:explicit_true_tool@" in docket.tasks
+        assert "prompt:inherited_prompt@" in docket.tasks
+        assert "resource:test://inherited@" in docket.tasks
+        # task=False means NOT registered
+        assert "tool:explicit_false_tool@" not in docket.tasks
+        assert "prompt:explicit_false_prompt@" not in docket.tasks
+        assert "resource:test://explicit_false@" not in docket.tasks
+
+        # Tools
+        inherited = await client.call_tool("inherited_tool", task=True)
+        assert not inherited.returned_immediately
+
+        explicit_true = await client.call_tool("explicit_true_tool", task=True)
+        assert not explicit_true.returned_immediately
+
+        # Explicit False (mode="forbidden") returns error
+        explicit_false = await client.call_tool(
+            "explicit_false_tool", task=True, raise_on_error=False
+        )
+        assert explicit_false.returned_immediately
+        result = await explicit_false.result()
+        assert result.is_error
+
+        # Prompts
+        inherited_prompt_task = await client.get_prompt("inherited_prompt", task=True)
+        assert not inherited_prompt_task.returned_immediately
+
+        # Explicit False prompt (mode="forbidden") raises MCPError
+        with pytest.raises(MCPError):
+            await client.get_prompt("explicit_false_prompt", task=True)
+
+        # Resources
+        inherited_resource_task = await client.read_resource(
+            "test://inherited", task=True
+        )
+        assert not inherited_resource_task.returned_immediately
+
+        # Explicit False resource (mode="forbidden") raises MCPError
+        with pytest.raises(MCPError):
+            await client.read_resource("test://explicit_false", task=True)
+
+
+async def test_server_tasks_parameter_sets_component_defaults():
+    """Server tasks parameter sets component defaults."""
+    # Server tasks=True sets component defaults
+    mcp = FastMCP("test", tasks=True)
+
+    @mcp.tool()
+    async def tool_inherits_true() -> str:
+        return "tool result"
+
+    async with Client(mcp) as client:
+        # Tool inherits tasks=True from server
+        tool_task = await client.call_tool("tool_inherits_true", task=True)
+        assert not tool_task.returned_immediately
+
+    # Server tasks=False sets component defaults
+    mcp2 = FastMCP("test2", tasks=False)
+
+    @mcp2.tool()
+    async def tool_inherits_false() -> str:
+        return "tool result"
+
+    async with Client(mcp2) as client:
+        # Tool inherits tasks=False (mode="forbidden") - returns error
+        tool_task = await client.call_tool(
+            "tool_inherits_false", task=True, raise_on_error=False
+        )
+        assert tool_task.returned_immediately
+        result = await tool_task.result()
+        assert result.is_error
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_resource_template_inherits_server_tasks_default():
+    """Resource templates inherit server tasks default."""
+    mcp = FastMCP("test", tasks=True)
+
+    @mcp.resource("test://{item_id}")
+    async def templated_resource(item_id: str) -> str:
+        return f"resource {item_id}"
+
+    async with Client(mcp) as client:
+        # Template should support background execution
+        resource_task = await client.read_resource("test://123", task=True)
+        assert not resource_task.returned_immediately
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_multiple_components_same_name_different_tasks():
+    """Different component types with same name can have different task settings."""
+    import pytest
+    from mcp.shared.exceptions import MCPError
+
+    mcp = FastMCP("test", tasks=False)
+
+    @mcp.tool(task=True)
+    async def shared_name() -> str:
+        return "tool result"
+
+    @mcp.prompt()
+    async def shared_name_prompt() -> str:
+        return "prompt result"
+
+    async with Client(mcp) as client:
+        # Tool with explicit True should support background execution
+        tool_task = await client.call_tool("shared_name", task=True)
+        assert not tool_task.returned_immediately
+
+        # Prompt inheriting False (mode="forbidden") raises MCPError
+        with pytest.raises(MCPError):
+            await client.get_prompt("shared_name_prompt", task=True)
+
+
+async def test_task_with_custom_tool_name():
+    """Tools with custom names work correctly as tasks (issue #2642).
+
+    When a tool is registered with a custom name different from the function
+    name, task execution should use the custom name for Docket lookup.
+    """
+    mcp = FastMCP("test", tasks=True)
+
+    async def my_function() -> str:
+        return "result from custom-named tool"
+
+    mcp.tool(my_function, name="custom-tool-name")
+
+    async with Client(mcp) as client:
+        # Verify the tool is registered with its custom name in Docket (prefixed key)
+        docket = mcp.docket
+        assert docket is not None
+        assert "tool:custom-tool-name@" in docket.tasks
+
+        # Call the tool as a task using its custom name
+        task = await client.call_tool("custom-tool-name", task=True)
+        assert not task.returned_immediately
+        result = await task
+        assert result.data == "result from custom-named tool"
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_task_with_custom_resource_name():
+    """Resources with custom names work correctly as tasks.
+
+    Resources are registered/looked up by their .key (URI), not their name.
+    """
+    mcp = FastMCP("test", tasks=True)
+
+    @mcp.resource("test://resource", name="custom-resource-name")
+    async def my_resource_func() -> str:
+        return "result from custom-named resource"
+
+    async with Client(mcp) as client:
+        # Verify the resource is registered with its key (prefixed URI) in Docket
+        docket = mcp.docket
+        assert docket is not None
+        assert "resource:test://resource@" in docket.tasks
+
+        # Call the resource as a task
+        task = await client.read_resource("test://resource", task=True)
+        assert not task.returned_immediately
+        result = await task.result()
+        assert result[0].text == "result from custom-named resource"
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_task_with_custom_template_name():
+    """Resource templates with custom names work correctly as tasks.
+
+    Templates are registered/looked up by their .key (uri_template), not their name.
+    """
+    mcp = FastMCP("test", tasks=True)
+
+    @mcp.resource("test://{item_id}", name="custom-template-name")
+    async def my_template_func(item_id: str) -> str:
+        return f"result for {item_id}"
+
+    async with Client(mcp) as client:
+        # Verify the template is registered with its key (prefixed uri_template) in Docket
+        docket = mcp.docket
+        assert docket is not None
+        assert "template:test://{item_id}@" in docket.tasks
+
+        # Call the template as a task
+        task = await client.read_resource("test://123", task=True)
+        assert not task.returned_immediately
+        result = await task.result()
+        assert result[0].text == "result for 123"
diff --git a/tests/server/tasks/test_snapshot_restore.py b/tests/server/tasks/test_snapshot_restore.py
new file mode 100644
index 0000000..946e1bf
--- /dev/null
+++ b/tests/server/tasks/test_snapshot_restore.py
@@ -0,0 +1,108 @@
+"""Tests for ``restore_task_snapshot`` — the worker-level Docket dependency
+that restores the task-context snapshot into the ``_task_snapshot``
+ContextVar before each task runs.
+
+With the snapshot restored up front, sync helpers (``get_access_token``,
+``get_http_request``, etc.) never need to hit Redis themselves.  These
+tests exercise the restore path end-to-end (via in-memory Docket) and
+the edge cases around non-fastmcp keys and failed restores.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+from mcp.server.auth.middleware.auth_context import auth_context_var
+from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.auth import AccessToken
+from fastmcp.server.dependencies import get_access_token
+from fastmcp.server.tasks.context import (
+    TaskContextSnapshot,
+    _recall_snapshot,
+    get_task_context,
+    restore_task_snapshot,
+)
+
+
+async def test_snapshot_restored_before_user_code_runs():
+    """A tool with no declared deps finds the snapshot already cached."""
+    mcp = FastMCP("snapshot-restore-test")
+    seen_cached: list[bool] = []
+
+    @mcp.tool(task=True)
+    async def bare_tool() -> str:
+        info = get_task_context()
+        assert info is not None
+        seen_cached.append(_recall_snapshot(info.task_id) is not None)
+        return "ok"
+
+    async with Client(mcp) as client:
+        task = await client.call_tool("bare_tool", {}, task=True)
+        await task.result()
+
+    assert seen_cached == [True]
+
+
+async def test_get_access_token_in_bg_task_without_context_dep():
+    """Issue #3897 repro: get_access_token() works in a bg task that does
+    not declare Context as a dependency."""
+    mcp = FastMCP("access-token-test")
+    seen_tokens: list[str | None] = []
+
+    @mcp.tool(task=True)
+    async def bare_tool() -> str:
+        token = get_access_token()
+        seen_tokens.append(token.token if token else None)
+        return "ok"
+
+    test_token = AccessToken(
+        token="jwt-3897",
+        client_id="test-client",
+        scopes=["read"],
+        claims={"sub": "user-x"},
+    )
+    auth_context_var.set(AuthenticatedUser(test_token))
+
+    async with Client(mcp) as client:
+        task = await client.call_tool("bare_tool", {}, task=True)
+        await task.result()
+
+    assert seen_tokens == ["jwt-3897"]
+
+
+async def test_restore_failure_is_nonfatal():
+    """If deserialization blows up, the task still runs to completion and
+    the snapshot cache stays empty."""
+    mcp = FastMCP("restore-failure-test")
+    seen_cached: list[bool] = []
+
+    @mcp.tool(task=True)
+    async def bare_tool() -> str:
+        info = get_task_context()
+        assert info is not None
+        seen_cached.append(_recall_snapshot(info.task_id) is not None)
+        return "ok"
+
+    def boom(*_args, **_kwargs):
+        raise RuntimeError("simulated deserialization failure")
+
+    async with Client(mcp) as client:
+        with patch.object(TaskContextSnapshot, "from_json", boom):
+            task = await client.call_tool("bare_tool", {}, task=True)
+            result = await task.result()
+
+    assert result.data == "ok"
+    assert seen_cached == [False]
+
+
+async def test_restore_skipped_for_non_fastmcp_task_keys():
+    """The restore dep returns cleanly for keys it doesn't recognize and
+    writes nothing to the snapshot cache."""
+    # Direct calls bypass the worker, so Redis/Docket never gets involved
+    # — any attempt to touch them would raise.
+    await restore_task_snapshot(key="not-a-fastmcp-key")
+    await restore_task_snapshot(key="weird:client-a:task-1:tool:my_tool")
+    await restore_task_snapshot(key="")
diff --git a/tests/server/tasks/test_sync_function_task_disabled.py b/tests/server/tasks/test_sync_function_task_disabled.py
new file mode 100644
index 0000000..c5255b0
--- /dev/null
+++ b/tests/server/tasks/test_sync_function_task_disabled.py
@@ -0,0 +1,229 @@
+"""
+Tests that synchronous functions cannot be used as background tasks.
+
+Docket requires async functions for background execution. FastMCP raises
+ValueError when task=True is used with a sync function.
+"""
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.prompts.function_prompt import FunctionPrompt
+from fastmcp.resources.function_resource import FunctionResource
+from fastmcp.tools.function_tool import FunctionTool
+
+
+async def test_sync_tool_with_explicit_task_true_raises():
+    """Sync tool with task=True raises ValueError."""
+    mcp = FastMCP("test")
+
+    with pytest.raises(
+        ValueError, match="uses a sync function but has task execution enabled"
+    ):
+
+        @mcp.tool(task=True)
+        def sync_tool(x: int) -> int:
+            """A synchronous tool."""
+            return x * 2
+
+
+async def test_sync_tool_with_inherited_task_true_raises():
+    """Sync tool inheriting task=True from server raises ValueError."""
+    mcp = FastMCP("test", tasks=True)
+
+    with pytest.raises(
+        ValueError, match="uses a sync function but has task execution enabled"
+    ):
+
+        @mcp.tool()  # Inherits task=True from server
+        def sync_tool(x: int) -> int:
+            """A synchronous tool."""
+            return x * 2
+
+
+async def test_sync_prompt_with_explicit_task_true_raises():
+    """Sync prompt with task=True raises ValueError."""
+    mcp = FastMCP("test")
+
+    with pytest.raises(
+        ValueError, match="uses a sync function but has task execution enabled"
+    ):
+
+        @mcp.prompt(task=True)
+        def sync_prompt() -> str:
+            """A synchronous prompt."""
+            return "Hello"
+
+
+async def test_sync_prompt_with_inherited_task_true_raises():
+    """Sync prompt inheriting task=True from server raises ValueError."""
+    mcp = FastMCP("test", tasks=True)
+
+    with pytest.raises(
+        ValueError, match="uses a sync function but has task execution enabled"
+    ):
+
+        @mcp.prompt()  # Inherits task=True from server
+        def sync_prompt() -> str:
+            """A synchronous prompt."""
+            return "Hello"
+
+
+async def test_sync_resource_with_explicit_task_true_raises():
+    """Sync resource with task=True raises ValueError."""
+    mcp = FastMCP("test")
+
+    with pytest.raises(
+        ValueError, match="uses a sync function but has task execution enabled"
+    ):
+
+        @mcp.resource("test://sync", task=True)
+        def sync_resource() -> str:
+            """A synchronous resource."""
+            return "data"
+
+
+async def test_sync_resource_with_inherited_task_true_raises():
+    """Sync resource inheriting task=True from server raises ValueError."""
+    mcp = FastMCP("test", tasks=True)
+
+    with pytest.raises(
+        ValueError, match="uses a sync function but has task execution enabled"
+    ):
+
+        @mcp.resource("test://sync")  # Inherits task=True from server
+        def sync_resource() -> str:
+            """A synchronous resource."""
+            return "data"
+
+
+async def test_async_tool_with_task_true_remains_enabled():
+    """Async tools with task=True keep task support enabled."""
+    mcp = FastMCP("test")
+
+    @mcp.tool(task=True)
+    async def async_tool(x: int) -> int:
+        """An async tool."""
+        return x * 2
+
+    # Tool should have task mode="optional" and be a FunctionTool
+    tool = await mcp.get_tool("async_tool")
+    assert isinstance(tool, FunctionTool)
+    assert tool.task_config.mode == "optional"
+
+
+async def test_async_prompt_with_task_true_remains_enabled():
+    """Async prompts with task=True keep task support enabled."""
+    mcp = FastMCP("test")
+
+    @mcp.prompt(task=True)
+    async def async_prompt() -> str:
+        """An async prompt."""
+        return "Hello"
+
+    # Prompt should have task mode="optional" and be a FunctionPrompt
+    prompt = await mcp.get_prompt("async_prompt")
+    assert isinstance(prompt, FunctionPrompt)
+    assert prompt.task_config.mode == "optional"
+
+
+async def test_async_resource_with_task_true_remains_enabled():
+    """Async resources with task=True keep task support enabled."""
+    mcp = FastMCP("test")
+
+    @mcp.resource("test://async", task=True)
+    async def async_resource() -> str:
+        """An async resource."""
+        return "data"
+
+    # Resource should have task mode="optional" and be a FunctionResource
+    resource = await mcp.get_resource("test://async")
+    assert isinstance(resource, FunctionResource)
+    assert resource.task_config.mode == "optional"
+
+
+async def test_sync_tool_with_task_false_works():
+    """Sync tool with explicit task=False works (no error)."""
+    mcp = FastMCP("test", tasks=True)
+
+    @mcp.tool(task=False)  # Explicitly disable
+    def sync_tool(x: int) -> int:
+        """A synchronous tool."""
+        return x * 2
+
+    tool = await mcp.get_tool("sync_tool")
+    assert isinstance(tool, FunctionTool)
+    assert tool.task_config.mode == "forbidden"
+
+
+async def test_sync_prompt_with_task_false_works():
+    """Sync prompt with explicit task=False works (no error)."""
+    mcp = FastMCP("test", tasks=True)
+
+    @mcp.prompt(task=False)  # Explicitly disable
+    def sync_prompt() -> str:
+        """A synchronous prompt."""
+        return "Hello"
+
+    prompt = await mcp.get_prompt("sync_prompt")
+    assert isinstance(prompt, FunctionPrompt)
+    assert prompt.task_config.mode == "forbidden"
+
+
+async def test_sync_resource_with_task_false_works():
+    """Sync resource with explicit task=False works (no error)."""
+    mcp = FastMCP("test", tasks=True)
+
+    @mcp.resource("test://sync", task=False)  # Explicitly disable
+    def sync_resource() -> str:
+        """A synchronous resource."""
+        return "data"
+
+    resource = await mcp.get_resource("test://sync")
+    assert isinstance(resource, FunctionResource)
+    assert resource.task_config.mode == "forbidden"
+
+
+# =============================================================================
+# Callable classes and staticmethods with async __call__
+# =============================================================================
+
+
+async def test_async_callable_class_tool_with_task_true_works():
+    """Callable class with async __call__ and task=True should work."""
+    from fastmcp.tools import Tool
+
+    class AsyncCallableTool:
+        async def __call__(self, x: int) -> int:
+            return x * 2
+
+    # Callable classes use Tool.from_function() directly
+    tool = Tool.from_function(AsyncCallableTool(), task=True)
+    assert tool.task_config.mode == "optional"
+
+
+async def test_async_callable_class_prompt_with_task_true_works():
+    """Callable class with async __call__ and task=True should work."""
+    from fastmcp.prompts import Prompt
+
+    class AsyncCallablePrompt:
+        async def __call__(self) -> str:
+            return "Hello"
+
+    # Callable classes use Prompt.from_function() directly
+    prompt = Prompt.from_function(AsyncCallablePrompt(), task=True)
+    assert prompt.task_config.mode == "optional"
+
+
+async def test_sync_callable_class_tool_with_task_true_raises():
+    """Callable class with sync __call__ and task=True should raise."""
+    from fastmcp.tools import Tool
+
+    class SyncCallableTool:
+        def __call__(self, x: int) -> int:
+            return x * 2
+
+    with pytest.raises(
+        ValueError, match="uses a sync function but has task execution enabled"
+    ):
+        Tool.from_function(SyncCallableTool(), task=True)
diff --git a/tests/server/tasks/test_task_capabilities.py b/tests/server/tasks/test_task_capabilities.py
new file mode 100644
index 0000000..3999c5d
--- /dev/null
+++ b/tests/server/tasks/test_task_capabilities.py
@@ -0,0 +1,91 @@
+"""
+Tests for SEP-1686 task capabilities declaration.
+
+Verifies that the server correctly advertises task support.
+Task protocol is now always enabled.
+"""
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.tasks import get_task_capabilities
+
+
+async def test_capabilities_include_tasks():
+    """Server capabilities always include tasks in first-class field (SEP-1686)."""
+    mcp = FastMCP("capability-test")
+
+    @mcp.tool()
+    async def test_tool() -> str:
+        return "test"
+
+    async with Client(mcp) as client:
+        # Get server initialization result which includes capabilities
+        init_result = client.initialize_result
+
+        # Verify tasks capability is present as a first-class field (not experimental)
+        assert init_result.capabilities.tasks is not None
+        assert init_result.capabilities.tasks == get_task_capabilities()
+        # Verify it's NOT in experimental
+        assert "tasks" not in (init_result.capabilities.experimental or {})
+
+
+def test_only_tools_advertise_task_support():
+    """Task requests advertise tools only, not prompts/resources (sdk-feedback #3).
+
+    SDK v2 b1 ``ReadResourceRequestParams`` / ``GetPromptRequestParams`` have no
+    ``task`` field, so resource/prompt task submissions always graceful-degrade
+    to synchronous execution. Advertising those capabilities would mislead
+    clients into sending task-augmented reads/gets, so the honest contract is
+    tools-only.
+    """
+    capabilities = get_task_capabilities()
+    assert capabilities is not None
+    requests = capabilities.requests
+    assert requests is not None
+    assert requests.tools is not None
+    assert requests.tools.call is not None
+    # No prompt/resource task capability of any form is advertised.
+    assert getattr(requests, "prompts", None) is None
+    assert getattr(requests, "resources", None) is None
+    dumped = requests.model_dump(exclude_none=True)
+    assert set(dumped) == {"tools"}
+
+
+async def test_client_uses_task_capable_session():
+    """Client uses task-capable initialization."""
+    mcp = FastMCP("client-cap-test")
+
+    @mcp.tool()
+    async def test_tool() -> str:
+        return "test"
+
+    async with Client(mcp) as client:
+        # Client should have connected successfully with task capabilities
+        assert client.initialize_result is not None
+        # Session should be a ClientSession (task-capable init uses standard session)
+        assert type(client.session).__name__ == "ClientSession"
+
+
+def test_capabilities_hidden_when_pydocket_too_old(monkeypatch):
+    """Capability advertisement and handler registration must agree.
+
+    If ``is_docket_available()`` returns False (e.g. an old transitive
+    pydocket), the server skips registering task handlers — so it must
+    also stop advertising task capabilities, or clients would discover
+    task support and then hit "method not found" at runtime.
+    """
+    import importlib.metadata
+
+    from fastmcp.server import dependencies
+
+    original_version = importlib.metadata.version
+
+    def fake_version(name: str) -> str:
+        if name == "pydocket":
+            return "0.16.6"
+        return original_version(name)
+
+    monkeypatch.setattr(dependencies, "_DOCKET_AVAILABLE", None)
+    monkeypatch.setattr(importlib.metadata, "version", fake_version)
+
+    assert get_task_capabilities() is None
diff --git a/tests/server/tasks/test_task_config.py b/tests/server/tasks/test_task_config.py
new file mode 100644
index 0000000..d6e0955
--- /dev/null
+++ b/tests/server/tasks/test_task_config.py
@@ -0,0 +1,407 @@
+"""Tests for TaskConfig (SEP-1686).
+
+Tests for TaskConfig:
+- Mode enforcement (forbidden, optional, required)
+- Poll interval configuration
+"""
+
+from datetime import timedelta
+
+import pytest
+from mcp.shared.exceptions import MCPError
+from mcp_types import TextContent, ToolExecution
+from mcp_types import Tool as MCPTool
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.exceptions import ToolError
+from fastmcp.server.tasks import TaskConfig
+from fastmcp.tools.base import Tool
+
+
+class TestTaskConfigNormalization:
+    """Test that boolean task values normalize correctly to TaskConfig."""
+
+    async def test_task_true_normalizes_to_optional(self):
+        """task=True should normalize to TaskConfig(mode='optional')."""
+        mcp = FastMCP("test", tasks=False)  # Disable default task support
+
+        @mcp.tool(task=True)
+        async def my_tool() -> str:
+            return "ok"
+
+        tool = await mcp.get_tool("my_tool")
+        assert isinstance(tool, Tool)
+        assert tool.task_config.mode == "optional"
+
+    async def test_task_false_normalizes_to_forbidden(self):
+        """task=False should normalize to TaskConfig(mode='forbidden')."""
+        mcp = FastMCP("test", tasks=False)
+
+        @mcp.tool(task=False)
+        async def my_tool() -> str:
+            return "ok"
+
+        tool = await mcp.get_tool("my_tool")
+        assert isinstance(tool, Tool)
+        assert tool.task_config.mode == "forbidden"
+
+    async def test_task_config_passed_directly(self):
+        """TaskConfig should be preserved when passed directly."""
+        mcp = FastMCP("test", tasks=False)
+
+        @mcp.tool(task=TaskConfig(mode="required"))
+        async def my_tool() -> str:
+            return "ok"
+
+        tool = await mcp.get_tool("my_tool")
+        assert isinstance(tool, Tool)
+        assert tool.task_config.mode == "required"
+
+    async def test_default_task_inherits_server_default(self):
+        """Default task value should inherit from server default."""
+        # Server with tasks disabled
+        mcp_no_tasks = FastMCP("test", tasks=False)
+
+        @mcp_no_tasks.tool()
+        def my_tool_sync() -> str:
+            return "ok"
+
+        tool = await mcp_no_tasks.get_tool("my_tool_sync")
+        assert isinstance(tool, Tool)
+        assert tool.task_config.mode == "forbidden"
+
+        # Server with tasks enabled
+        mcp_tasks = FastMCP("test", tasks=True)
+
+        @mcp_tasks.tool()
+        async def my_tool_async() -> str:
+            return "ok"
+
+        tool2 = await mcp_tasks.get_tool("my_tool_async")
+        assert isinstance(tool2, Tool)
+        assert tool2.task_config.mode == "optional"
+
+
+class TestToolModeEnforcement:
+    """Test mode enforcement for tools."""
+
+    @pytest.fixture
+    def server(self):
+        """Create server with tools in different modes."""
+        mcp = FastMCP("test", tasks=False)
+
+        @mcp.tool(task=TaskConfig(mode="required"))
+        async def required_tool() -> str:
+            """Tool that requires task execution."""
+            return "required result"
+
+        @mcp.tool(task=TaskConfig(mode="forbidden"))
+        async def forbidden_tool() -> str:
+            """Tool that forbids task execution."""
+            return "forbidden result"
+
+        @mcp.tool(task=TaskConfig(mode="optional"))
+        async def optional_tool() -> str:
+            """Tool that supports both modes."""
+            return "optional result"
+
+        return mcp
+
+    async def test_required_mode_without_task_returns_error(self, server):
+        """Required mode raises error when called without task metadata."""
+        async with Client(server) as client:
+            with pytest.raises(ToolError) as exc_info:
+                await client.call_tool("required_tool", {})
+
+            assert "requires task-augmented execution" in str(exc_info.value)
+
+    async def test_required_mode_with_task_succeeds(self, server):
+        """Required mode succeeds when called with task metadata."""
+        async with Client(server) as client:
+            task = await client.call_tool("required_tool", {}, task=True)
+            assert task is not None
+            result = await task.result()
+            assert result.data == "required result"
+
+    async def test_forbidden_mode_with_task_returns_error(self, server):
+        """Forbidden mode returns error when called with task metadata."""
+        async with Client(server) as client:
+            # Call with task=True should fail
+            task = await client.call_tool(
+                "forbidden_tool", {}, task=True, raise_on_error=False
+            )
+            assert task is not None
+            # The task should have returned immediately with an error
+            assert task.returned_immediately
+            result = await task.result()
+            # Check for error in the result
+            assert result.is_error
+
+    async def test_forbidden_mode_without_task_succeeds(self, server):
+        """Forbidden mode succeeds when called without task metadata."""
+        async with Client(server) as client:
+            result = await client.call_tool("forbidden_tool", {})
+            assert "forbidden result" in str(result)
+
+    async def test_optional_mode_without_task_succeeds(self, server):
+        """Optional mode succeeds when called without task metadata."""
+        async with Client(server) as client:
+            result = await client.call_tool("optional_tool", {})
+            assert "optional result" in str(result)
+
+    async def test_optional_mode_with_task_succeeds(self, server):
+        """Optional mode succeeds when called with task metadata."""
+        async with Client(server) as client:
+            task = await client.call_tool("optional_tool", {}, task=True)
+            assert task is not None
+            result = await task.result()
+            assert result.data == "optional result"
+
+
+class TestResourceModeEnforcement:
+    """Test mode enforcement for resources."""
+
+    @pytest.fixture
+    def server(self):
+        """Create server with resources in different modes."""
+        mcp = FastMCP("test", tasks=False)
+
+        @mcp.resource("resource://required", task=TaskConfig(mode="required"))
+        async def required_resource() -> str:
+            """Resource that requires task execution."""
+            return "required content"
+
+        @mcp.resource("resource://forbidden", task=TaskConfig(mode="forbidden"))
+        async def forbidden_resource() -> str:
+            """Resource that forbids task execution."""
+            return "forbidden content"
+
+        @mcp.resource("resource://optional", task=TaskConfig(mode="optional"))
+        async def optional_resource() -> str:
+            """Resource that supports both modes."""
+            return "optional content"
+
+        return mcp
+
+    async def test_required_resource_without_task_returns_error(self, server):
+        """Required mode returns error when read without task metadata."""
+        from mcp_types import METHOD_NOT_FOUND
+
+        async with Client(server) as client:
+            with pytest.raises(MCPError) as exc_info:
+                await client.read_resource("resource://required")
+
+            assert exc_info.value.error.code == METHOD_NOT_FOUND
+            assert "requires task-augmented execution" in exc_info.value.error.message
+
+    @pytest.mark.xfail(
+        reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+        "ReadResourceRequestParams; prompt/resource task submission is not "
+        "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+        strict=True,
+    )
+    async def test_required_resource_with_task_succeeds(self, server):
+        """Required mode succeeds when read with task metadata."""
+        async with Client(server) as client:
+            task = await client.read_resource("resource://required", task=True)
+            assert task is not None
+            result = await task.result()
+            # Result is a list of resource contents
+            assert "required content" in str(result)
+
+    async def test_forbidden_resource_without_task_succeeds(self, server):
+        """Forbidden mode succeeds when read without task metadata."""
+        async with Client(server) as client:
+            result = await client.read_resource("resource://forbidden")
+            assert "forbidden content" in str(result)
+
+
+class TestPromptModeEnforcement:
+    """Test mode enforcement for prompts."""
+
+    @pytest.fixture
+    def server(self):
+        """Create server with prompts in different modes."""
+        mcp = FastMCP("test", tasks=False)
+
+        @mcp.prompt(task=TaskConfig(mode="required"))
+        async def required_prompt() -> str:
+            """Prompt that requires task execution."""
+            return "required message"
+
+        @mcp.prompt(task=TaskConfig(mode="forbidden"))
+        async def forbidden_prompt() -> str:
+            """Prompt that forbids task execution."""
+            return "forbidden message"
+
+        @mcp.prompt(task=TaskConfig(mode="optional"))
+        async def optional_prompt() -> str:
+            """Prompt that supports both modes."""
+            return "optional message"
+
+        return mcp
+
+    async def test_required_prompt_without_task_returns_error(self, server):
+        """Required mode returns error when called without task metadata."""
+        from mcp_types import METHOD_NOT_FOUND
+
+        async with Client(server) as client:
+            with pytest.raises(MCPError) as exc_info:
+                await client.get_prompt("required_prompt")
+
+            assert exc_info.value.error.code == METHOD_NOT_FOUND
+            assert "requires task-augmented execution" in exc_info.value.error.message
+
+    @pytest.mark.xfail(
+        reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+        "ReadResourceRequestParams; prompt/resource task submission is not "
+        "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+        strict=True,
+    )
+    async def test_required_prompt_with_task_succeeds(self, server):
+        """Required mode succeeds when called with task metadata."""
+        async with Client(server) as client:
+            task = await client.get_prompt("required_prompt", task=True)
+            assert task is not None
+            result = await task.result()
+            # Result contains the prompt messages
+            assert "required message" in str(result)
+
+    async def test_forbidden_prompt_without_task_succeeds(self, server):
+        """Forbidden mode succeeds when called without task metadata."""
+        async with Client(server) as client:
+            result = await client.get_prompt("forbidden_prompt")
+            assert isinstance(result.messages[0].content, TextContent)
+            assert "forbidden message" in str(result.messages[0].content)
+
+
+class TestToolExecutionMetadata:
+    """Test that ToolExecution.task_support is set correctly in tool metadata."""
+
+    async def test_optional_tool_exposes_task_support(self):
+        """Tools with task enabled should expose taskSupport in metadata."""
+        mcp = FastMCP("test", tasks=False)
+
+        @mcp.tool(task=TaskConfig(mode="optional"))
+        async def my_tool() -> str:
+            return "ok"
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            tool = next(t for t in tools if t.name == "my_tool")
+            assert isinstance(tool, MCPTool)
+            assert isinstance(tool.execution, ToolExecution)
+            assert tool.execution.task_support == "optional"
+
+    async def test_required_tool_exposes_task_support(self):
+        """Tools with mode=required should expose task_support='required'."""
+        mcp = FastMCP("test", tasks=False)
+
+        @mcp.tool(task=TaskConfig(mode="required"))
+        async def my_tool() -> str:
+            return "ok"
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            tool = next(t for t in tools if t.name == "my_tool")
+            assert isinstance(tool, MCPTool)
+            assert isinstance(tool.execution, ToolExecution)
+            assert tool.execution.task_support == "required"
+
+    async def test_forbidden_tool_has_no_execution(self):
+        """Tools with mode=forbidden should not expose execution metadata."""
+        mcp = FastMCP("test", tasks=False)
+
+        @mcp.tool(task=TaskConfig(mode="forbidden"))
+        async def my_tool() -> str:
+            return "ok"
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            tool = next(t for t in tools if t.name == "my_tool")
+            assert tool.execution is None
+
+
+class TestSyncFunctionValidation:
+    """Test that sync functions cannot have task execution enabled."""
+
+    def test_sync_function_with_task_true_raises(self):
+        """Sync functions should raise ValueError when task=True."""
+        mcp = FastMCP("test", tasks=False)
+
+        with pytest.raises(ValueError, match="sync function"):
+
+            @mcp.tool(task=True)
+            def sync_tool() -> str:
+                return "ok"
+
+    def test_sync_function_with_required_mode_raises(self):
+        """Sync functions should raise ValueError with mode='required'."""
+        mcp = FastMCP("test", tasks=False)
+
+        with pytest.raises(ValueError, match="sync function"):
+
+            @mcp.tool(task=TaskConfig(mode="required"))
+            def sync_tool() -> str:
+                return "ok"
+
+    def test_sync_function_with_optional_mode_raises(self):
+        """Sync functions should raise ValueError with mode='optional'."""
+        mcp = FastMCP("test", tasks=False)
+
+        with pytest.raises(ValueError, match="sync function"):
+
+            @mcp.tool(task=TaskConfig(mode="optional"))
+            def sync_tool() -> str:
+                return "ok"
+
+    async def test_sync_function_with_forbidden_mode_ok(self):
+        """Sync functions should work fine with mode='forbidden'."""
+        mcp = FastMCP("test", tasks=False)
+
+        @mcp.tool(task=TaskConfig(mode="forbidden"))
+        def sync_tool() -> str:
+            return "ok"
+
+        tool = await mcp.get_tool("sync_tool")
+        assert isinstance(tool, Tool)
+        assert tool.task_config.mode == "forbidden"
+
+
+class TestPollIntervalConfiguration:
+    """Test poll_interval configuration in TaskConfig."""
+
+    async def test_default_poll_interval_is_5_seconds(self):
+        """Default poll_interval should be 5 seconds."""
+        config = TaskConfig()
+        assert config.poll_interval == timedelta(seconds=5)
+
+    async def test_custom_poll_interval_preserved(self):
+        """Custom poll_interval should be preserved in TaskConfig."""
+        config = TaskConfig(poll_interval=timedelta(seconds=10))
+        assert config.poll_interval == timedelta(seconds=10)
+
+    async def test_tool_inherits_poll_interval(self):
+        """Tool should inherit poll_interval from TaskConfig."""
+        mcp = FastMCP("test", tasks=False)
+
+        @mcp.tool(task=TaskConfig(mode="optional", poll_interval=timedelta(seconds=2)))
+        async def my_tool() -> str:
+            return "ok"
+
+        tool = await mcp.get_tool("my_tool")
+        assert isinstance(tool, Tool)
+        assert tool.task_config.poll_interval == timedelta(seconds=2)
+
+    async def test_task_true_uses_default_poll_interval(self):
+        """task=True should use default 5 second poll_interval."""
+        mcp = FastMCP("test", tasks=False)
+
+        @mcp.tool(task=True)
+        async def my_tool() -> str:
+            return "ok"
+
+        tool = await mcp.get_tool("my_tool")
+        assert isinstance(tool, Tool)
+        assert tool.task_config.poll_interval == timedelta(seconds=5)
diff --git a/tests/server/tasks/test_task_dependencies.py b/tests/server/tasks/test_task_dependencies.py
new file mode 100644
index 0000000..0aef545
--- /dev/null
+++ b/tests/server/tasks/test_task_dependencies.py
@@ -0,0 +1,284 @@
+"""Tests for dependency injection in background tasks.
+
+These tests verify that Docket's dependency system works correctly when
+user functions are queued as background tasks. Dependencies like CurrentDocket(),
+CurrentFastMCP(), and Depends() should be resolved in the worker context.
+"""
+
+from contextlib import asynccontextmanager
+from typing import Any, cast
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.dependencies import CurrentDocket, CurrentFastMCP, Depends
+from fastmcp.exceptions import ToolError
+
+
+@pytest.fixture
+async def dependency_server():
+    """Create a FastMCP server with dependency-using background tasks."""
+    mcp = FastMCP("dependency-test-server")
+
+    # Track dependency injection
+    injected_values = []
+
+    @mcp.tool(task=True)
+    async def tool_with_docket_dependency(docket=CurrentDocket()) -> str:
+        """Background tool that uses CurrentDocket dependency."""
+        injected_values.append(("docket", docket))
+        return f"Docket: {docket is not None}"
+
+    @mcp.tool(task=True)
+    async def tool_with_server_dependency(server=CurrentFastMCP()) -> str:
+        """Background tool that uses CurrentFastMCP dependency."""
+        injected_values.append(("server", server))
+        return f"Server: {server.name}"
+
+    @mcp.tool(task=True)
+    async def tool_with_custom_dependency(
+        value: int, multiplier: int = Depends(lambda: 10)
+    ) -> int:
+        """Background tool with custom Depends()."""
+        injected_values.append(("multiplier", multiplier))
+        return value * multiplier
+
+    @mcp.tool(task=True)
+    async def tool_with_multiple_dependencies(
+        name: str,
+        docket=CurrentDocket(),
+        server=CurrentFastMCP(),
+    ) -> str:
+        """Background tool with multiple dependencies."""
+        injected_values.append(("multi_docket", docket))
+        injected_values.append(("multi_server", server))
+        return f"{name} on {server.name}"
+
+    @mcp.prompt(task=True)
+    async def prompt_with_server_dependency(topic: str, server=CurrentFastMCP()) -> str:
+        """Background prompt that uses CurrentFastMCP dependency."""
+        injected_values.append(("prompt_server", server))
+        return f"Prompt from {server.name} about {topic}"
+
+    @mcp.resource("file://data.txt", task=True)
+    async def resource_with_docket_dependency(docket=CurrentDocket()) -> str:
+        """Background resource that uses CurrentDocket dependency."""
+        injected_values.append(("resource_docket", docket))
+        return f"Resource via Docket: {docket is not None}"
+
+    # Expose for test assertions
+    mcp._injected_values = injected_values  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+
+    return mcp
+
+
+async def test_background_tool_receives_docket_dependency(dependency_server):
+    """Background tools can use CurrentDocket() and it resolves correctly."""
+    async with Client(dependency_server) as client:
+        task = await client.call_tool("tool_with_docket_dependency", {}, task=True)
+
+        # Verify it's background
+        assert not task.returned_immediately
+
+        # Get result - will execute in Docket worker
+        result = await task
+
+        # Verify dependency was injected
+        assert len(dependency_server._injected_values) == 1
+        dep_type, dep_value = dependency_server._injected_values[0]
+        assert dep_type == "docket"
+        assert dep_value is not None
+        assert "Docket: True" in result.data
+
+
+async def test_background_tool_receives_server_dependency(dependency_server):
+    """Background tools can use CurrentFastMCP() and get the actual FastMCP server."""
+    dependency_server._injected_values.clear()
+
+    async with Client(dependency_server) as client:
+        task = await client.call_tool("tool_with_server_dependency", {}, task=True)
+
+        # Verify background execution
+        assert not task.returned_immediately
+
+        result = await task
+
+        # Check the server instance was injected
+        assert len(dependency_server._injected_values) == 1
+        dep_type, dep_value = dependency_server._injected_values[0]
+        assert dep_type == "server"
+        assert dep_value is dependency_server  # Same instance!
+        assert f"Server: {dependency_server.name}" in result.data
+
+
+async def test_background_tool_receives_custom_depends(dependency_server):
+    """Background tools can use Depends() with custom functions."""
+    dependency_server._injected_values.clear()
+
+    async with Client(dependency_server) as client:
+        task = await client.call_tool(
+            "tool_with_custom_dependency", {"value": 5}, task=True
+        )
+
+        assert not task.returned_immediately
+
+        result = await task
+
+        # Check dependency was resolved
+        assert len(dependency_server._injected_values) == 1
+        dep_type, dep_value = dependency_server._injected_values[0]
+        assert dep_type == "multiplier"
+        assert dep_value == 10
+        assert result.data == 50  # 5 * 10
+
+
+async def test_background_tool_with_multiple_dependencies(dependency_server):
+    """Background tools can have multiple dependencies injected simultaneously."""
+    dependency_server._injected_values.clear()
+
+    async with Client(dependency_server) as client:
+        task = await client.call_tool(
+            "tool_with_multiple_dependencies", {"name": "test"}, task=True
+        )
+
+        assert not task.returned_immediately
+
+        await task
+
+        # Both dependencies should be injected
+        assert len(dependency_server._injected_values) == 2
+
+        dep_types = {item[0] for item in dependency_server._injected_values}
+        assert "multi_docket" in dep_types
+        assert "multi_server" in dep_types
+
+        # Verify values
+        server_dep = next(
+            v for t, v in dependency_server._injected_values if t == "multi_server"
+        )
+        assert server_dep is dependency_server
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_background_prompt_receives_dependencies(dependency_server):
+    """Background prompts can use dependency injection."""
+    dependency_server._injected_values.clear()
+
+    async with Client(dependency_server) as client:
+        task = await client.get_prompt(
+            "prompt_with_server_dependency", {"topic": "AI"}, task=True
+        )
+
+        assert not task.returned_immediately
+
+        await task
+
+        # Check dependency was injected
+        assert len(dependency_server._injected_values) == 1
+        dep_type, dep_value = dependency_server._injected_values[0]
+        assert dep_type == "prompt_server"
+        assert dep_value is dependency_server
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_background_resource_receives_dependencies(dependency_server):
+    """Background resources can use dependency injection."""
+    dependency_server._injected_values.clear()
+
+    async with Client(dependency_server) as client:
+        task = await client.read_resource("file://data.txt", task=True)
+
+        assert not task.returned_immediately
+
+        await task
+
+        # Check dependency was injected
+        assert len(dependency_server._injected_values) == 1
+        dep_type, dep_value = dependency_server._injected_values[0]
+        assert dep_type == "resource_docket"
+        assert dep_value is not None
+
+
+async def test_foreground_tool_dependencies_unaffected(dependency_server):
+    """Synchronous tools (task=False) still get dependencies as before."""
+    dependency_server._injected_values.clear()
+
+    @dependency_server.tool()  # task=False
+    async def sync_tool(server=CurrentFastMCP()) -> str:
+        dependency_server._injected_values.append(("sync_server", server))
+        return f"Sync: {server.name}"
+
+    async with Client(dependency_server) as client:
+        await client.call_tool("sync_tool", {})
+
+        # Should execute immediately
+        assert len(dependency_server._injected_values) == 1
+        assert dependency_server._injected_values[0][1] is dependency_server
+
+
+async def test_dependency_context_managers_cleaned_up_in_background():
+    """Context manager dependencies are properly cleaned up after background task."""
+    cleanup_called = []
+
+    mcp = FastMCP("cleanup-test")
+
+    @asynccontextmanager
+    async def tracked_connection():
+        try:
+            cleanup_called.append("enter")
+            yield "connection"
+        finally:
+            cleanup_called.append("exit")
+
+    @mcp.tool(task=True)
+    async def use_connection(name: str, conn: str = Depends(tracked_connection)) -> str:
+        assert conn == "connection"
+        assert "enter" in cleanup_called
+        assert "exit" not in cleanup_called  # Still open during execution
+        return f"Used: {conn}"
+
+    async with Client(mcp) as client:
+        task = await client.call_tool("use_connection", {"name": "test"}, task=True)
+        result = await task
+
+        # After task completes, cleanup should have been called
+        assert cleanup_called == ["enter", "exit"]
+        assert "Used: connection" in result.data
+
+
+async def test_dependency_errors_propagate_to_task_failure():
+    """If dependency resolution fails, the background task should fail."""
+    mcp = FastMCP("error-test")
+
+    async def failing_dependency():
+        raise ValueError("Dependency failed!")
+
+    @mcp.tool(task=True)
+    async def tool_with_failing_dep(
+        value: str, dep: str = cast(Any, Depends(failing_dependency))
+    ) -> str:
+        return f"Got: {dep}"
+
+    async with Client(mcp) as client:
+        task = await client.call_tool(
+            "tool_with_failing_dep", {"value": "test"}, task=True
+        )
+
+        # Task should fail due to dependency error
+        with pytest.raises(ToolError, match="Failed to resolve dependencies"):
+            await task.result()
+
+        # Verify it reached failed state
+        status = await task.status()
+        assert status.status == "failed"
diff --git a/tests/server/tasks/test_task_elicitation_relay.py b/tests/server/tasks/test_task_elicitation_relay.py
new file mode 100644
index 0000000..42362ed
--- /dev/null
+++ b/tests/server/tasks/test_task_elicitation_relay.py
@@ -0,0 +1,191 @@
+"""Tests for background task elicitation relay (notifications.py).
+
+The relay bridges distributed background tasks to clients via the standard
+MCP elicitation/create protocol. When a worker calls ctx.elicit(), the
+notification subscriber detects the input_required notification and sends
+an elicitation/create request to the client session. The client's
+elicitation_handler fires, and the relay pushes the response to Redis
+for the blocked worker.
+
+These tests use Client(mcp) with the real memory:// Docket backend.
+"""
+
+import asyncio
+from dataclasses import dataclass
+
+from pydantic import BaseModel
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.elicitation import ElicitResult
+from fastmcp.server.context import Context
+from fastmcp.server.elicitation import (
+    AcceptedElicitation,
+    CancelledElicitation,
+    DeclinedElicitation,
+)
+
+
+class TestElicitationRelay:
+    """E2E tests for elicitation flowing through the standard MCP protocol."""
+
+    async def test_accept_via_elicitation_handler(self):
+        """Tool elicits, client handler accepts, tool gets the value."""
+        mcp = FastMCP("relay-accept")
+
+        @mcp.tool(task=True)
+        async def ask_name(ctx: Context) -> str:
+            result = await ctx.elicit("What is your name?", str)
+            if isinstance(result, AcceptedElicitation):
+                return f"Hello, {result.data}!"
+            return "No name"
+
+        async def handler(message, response_type, params, ctx):
+            assert message == "What is your name?"
+            return ElicitResult(action="accept", content={"value": "Alice"})
+
+        async with Client(mcp, elicitation_handler=handler) as client:
+            task = await client.call_tool("ask_name", {}, task=True)
+            result = await task.result()
+            assert result.data == "Hello, Alice!"
+
+    async def test_decline_via_elicitation_handler(self):
+        """Tool elicits, client handler declines, tool gets DeclinedElicitation."""
+        mcp = FastMCP("relay-decline")
+
+        @mcp.tool(task=True)
+        async def optional_input(ctx: Context) -> str:
+            result = await ctx.elicit("Provide a name?", str)
+            if isinstance(result, DeclinedElicitation):
+                return "User declined"
+            if isinstance(result, AcceptedElicitation):
+                return f"Got: {result.data}"
+            return "Cancelled"
+
+        async def handler(message, response_type, params, ctx):
+            return ElicitResult(action="decline")
+
+        async with Client(mcp, elicitation_handler=handler) as client:
+            task = await client.call_tool("optional_input", {}, task=True)
+            result = await task.result()
+            assert result.data == "User declined"
+
+    async def test_cancel_via_elicitation_handler(self):
+        """Tool elicits, client handler cancels, tool gets CancelledElicitation."""
+        mcp = FastMCP("relay-cancel")
+
+        @mcp.tool(task=True)
+        async def cancellable(ctx: Context) -> str:
+            result = await ctx.elicit("Input?", str)
+            if isinstance(result, CancelledElicitation):
+                return "Cancelled"
+            return "Not cancelled"
+
+        async def handler(message, response_type, params, ctx):
+            return ElicitResult(action="cancel")
+
+        async with Client(mcp, elicitation_handler=handler) as client:
+            task = await client.call_tool("cancellable", {}, task=True)
+            result = await task.result()
+            assert result.data == "Cancelled"
+
+    async def test_dataclass_round_trips_through_relay(self):
+        """Structured dataclass type round-trips through the relay."""
+        mcp = FastMCP("relay-dataclass")
+
+        @dataclass
+        class UserInfo:
+            name: str
+            age: int
+
+        @mcp.tool(task=True)
+        async def get_user(ctx: Context) -> str:
+            result = await ctx.elicit("Provide user info", UserInfo)
+            if isinstance(result, AcceptedElicitation):
+                assert isinstance(result.data, UserInfo)
+                return f"{result.data.name} is {result.data.age}"
+            return "No info"
+
+        async def handler(message, response_type, params, ctx):
+            return ElicitResult(action="accept", content={"name": "Bob", "age": 30})
+
+        async with Client(mcp, elicitation_handler=handler) as client:
+            task = await client.call_tool("get_user", {}, task=True)
+            result = await task.result()
+            assert result.data == "Bob is 30"
+
+    async def test_pydantic_model_round_trips_through_relay(self):
+        """Structured Pydantic model round-trips through the relay."""
+        mcp = FastMCP("relay-pydantic")
+
+        class Config(BaseModel):
+            host: str
+            port: int
+
+        @mcp.tool(task=True)
+        async def get_config(ctx: Context) -> str:
+            result = await ctx.elicit("Server config?", Config)
+            if isinstance(result, AcceptedElicitation):
+                assert isinstance(result.data, Config)
+                return f"{result.data.host}:{result.data.port}"
+            return "No config"
+
+        async def handler(message, response_type, params, ctx):
+            return ElicitResult(
+                action="accept", content={"host": "localhost", "port": 8080}
+            )
+
+        async with Client(mcp, elicitation_handler=handler) as client:
+            task = await client.call_tool("get_config", {}, task=True)
+            result = await task.result()
+            assert result.data == "localhost:8080"
+
+    async def test_multiple_sequential_elicitations(self):
+        """Tool calls ctx.elicit() twice, both go through the relay."""
+        mcp = FastMCP("relay-multi")
+
+        @mcp.tool(task=True)
+        async def two_questions(ctx: Context) -> str:
+            r1 = await ctx.elicit("First name?", str)
+            r2 = await ctx.elicit("Last name?", str)
+            if isinstance(r1, AcceptedElicitation) and isinstance(
+                r2, AcceptedElicitation
+            ):
+                return f"{r1.data} {r2.data}"
+            return "Incomplete"
+
+        call_count = 0
+
+        async def handler(message, response_type, params, ctx):
+            nonlocal call_count
+            call_count += 1
+            if call_count == 1:
+                assert message == "First name?"
+                return ElicitResult(action="accept", content={"value": "Jane"})
+            else:
+                assert message == "Last name?"
+                return ElicitResult(action="accept", content={"value": "Doe"})
+
+        async with Client(mcp, elicitation_handler=handler) as client:
+            task = await client.call_tool("two_questions", {}, task=True)
+            result = await task.result()
+            assert result.data == "Jane Doe"
+            assert call_count == 2
+
+    async def test_no_elicitation_handler_returns_cancel(self):
+        """Without an elicitation_handler, the relay fails and task gets cancel."""
+        mcp = FastMCP("relay-no-handler")
+
+        @mcp.tool(task=True)
+        async def needs_input(ctx: Context) -> str:
+            result = await ctx.elicit("Input?", str)
+            if isinstance(result, CancelledElicitation):
+                return "Cancelled as expected"
+            if isinstance(result, AcceptedElicitation):
+                return f"Got: {result.data}"
+            return "Other"
+
+        async with Client(mcp) as client:
+            task = await client.call_tool("needs_input", {}, task=True)
+            result = await asyncio.wait_for(task.result(), timeout=15.0)
+            assert result.data == "Cancelled as expected"
diff --git a/tests/server/tasks/test_task_keys.py b/tests/server/tasks/test_task_keys.py
new file mode 100644
index 0000000..06a64f8
--- /dev/null
+++ b/tests/server/tasks/test_task_keys.py
@@ -0,0 +1,170 @@
+"""Tests for ``fastmcp.server.tasks.keys`` — the encoding boundary that
+separates authenticated and anonymous task keyspaces.
+
+Cross-scope isolation depends on these encodings being unambiguous and
+round-trippable, so the tests cover: tag dispatch (``auth``/``anon``),
+the ``None`` ⇄ anonymous round trip, encoding of values that contain the
+``:`` delimiter, error paths for malformed keys, and the parity between
+the Docket-key prefix and the Redis-key prefix.
+"""
+
+import pytest
+
+from fastmcp.server.tasks.keys import (
+    build_task_key,
+    get_client_task_id_from_key,
+    parse_task_key,
+    task_redis_prefix,
+)
+
+ROUND_TRIP_CASES = [
+    ("client-a", "task-1", "tool", "my_tool"),
+    (None, "task-1", "tool", "my_tool"),
+    ("client-a", "task-1", "resource", "file://data.txt"),
+    (None, "task-1", "resource", "file://data.txt"),
+    ("client-a", "task-1", "template", "users://{id}"),
+    ("client-a", "task-1", "prompt", "greet@1.0.0"),
+    # Scope contains the inner separator used by get_task_scope (client_id|sub).
+    ("client|sub-42", "task-1", "tool", "my_tool"),
+    # Adversarial: scope is literally the anon tag — must not collide.
+    ("anon", "task-1", "tool", "my_tool"),
+    # Adversarial: scope is literally the legacy "_" sentinel.
+    ("_", "task-1", "tool", "my_tool"),
+    # Scope contains every delimiter we care about.
+    ("a:b/c d%e|f", "task-1", "tool", "my_tool"),
+    # Component identifier with colons, slashes, percent, spaces.
+    ("client-a", "task-1", "resource", "https://x/y?z=1&q=a b"),
+    # UUID-shaped task id (the realistic case).
+    ("client-a", "0c3e9b14-3a3f-4b3a-9b1a-1d8d6e6e0c11", "tool", "t"),
+]
+
+
+@pytest.mark.parametrize(
+    ("scope", "task_id", "task_type", "identifier"), ROUND_TRIP_CASES
+)
+def test_round_trip_preserves_all_fields(
+    scope: str | None, task_id: str, task_type: str, identifier: str
+):
+    key = build_task_key(scope, task_id, task_type, identifier)
+    parsed = parse_task_key(key)
+    assert parsed == {
+        "task_scope": scope,
+        "client_task_id": task_id,
+        "task_type": task_type,
+        "component_identifier": identifier,
+    }
+
+
+@pytest.mark.parametrize(
+    ("scope", "task_id", "task_type", "identifier"), ROUND_TRIP_CASES
+)
+def test_get_client_task_id_round_trip(
+    scope: str | None, task_id: str, task_type: str, identifier: str
+):
+    key = build_task_key(scope, task_id, task_type, identifier)
+    assert get_client_task_id_from_key(key) == task_id
+
+
+def test_authenticated_key_uses_auth_tag():
+    key = build_task_key("client-a", "task-1", "tool", "my_tool")
+    assert key.startswith("auth:")
+    assert key == "auth:client-a:task-1:tool:my_tool"
+
+
+def test_anonymous_key_uses_anon_tag():
+    key = build_task_key(None, "task-1", "tool", "my_tool")
+    assert key.startswith("anon:")
+    assert key == "anon:task-1:tool:my_tool"
+
+
+def test_anonymous_and_literal_anon_scope_have_disjoint_keyspaces():
+    """A real anonymous task and a (hostile) authenticated task whose scope
+    literally equals "anon" must not collide."""
+    anon_key = build_task_key(None, "task-1", "tool", "x")
+    impostor_key = build_task_key("anon", "task-1", "tool", "x")
+    assert anon_key != impostor_key
+    assert parse_task_key(anon_key)["task_scope"] is None
+    assert parse_task_key(impostor_key)["task_scope"] == "anon"
+
+
+def test_legacy_underscore_scope_is_just_a_string_now():
+    """Belt-and-suspenders: a client_id of "_" no longer aliases anonymous."""
+    underscore_key = build_task_key("_", "task-1", "tool", "x")
+    anon_key = build_task_key(None, "task-1", "tool", "x")
+    assert underscore_key != anon_key
+    assert parse_task_key(underscore_key)["task_scope"] == "_"
+
+
+def test_component_identifier_with_colons_is_recovered():
+    key = build_task_key("client-a", "task-1", "resource", "file://data:special.txt")
+    assert parse_task_key(key)["component_identifier"] == "file://data:special.txt"
+
+
+def test_scope_with_colons_is_recovered():
+    key = build_task_key("a:b:c", "task-1", "tool", "t")
+    parsed = parse_task_key(key)
+    assert parsed["task_scope"] == "a:b:c"
+    assert parsed["client_task_id"] == "task-1"
+
+
+def test_scope_pipe_separator_is_preserved():
+    """``get_task_scope`` composes ``client_id|sub`` — the ``|`` must survive."""
+    key = build_task_key("client-a|user-42", "task-1", "tool", "t")
+    assert parse_task_key(key)["task_scope"] == "client-a|user-42"
+
+
+@pytest.mark.parametrize(
+    "bad_key",
+    [
+        "",
+        "client-a:task-1:tool:my_tool",  # legacy untagged format
+        "weird:client-a:task-1:tool:my_tool",  # unknown tag
+        "auth:client-a:task-1:tool",  # missing identifier
+        "auth:client-a",  # truncated
+        "anon:task-1:tool",  # truncated anon
+        "anon",  # tag only
+        "auth",  # tag only
+        ":task-1:tool:t",  # empty tag
+    ],
+)
+def test_parse_rejects_malformed_keys(bad_key: str):
+    with pytest.raises(ValueError):
+        parse_task_key(bad_key)
+
+
+def test_redis_prefix_authenticated():
+    assert task_redis_prefix("client-a") == "fastmcp:task:auth:client-a"
+
+
+def test_redis_prefix_anonymous():
+    assert task_redis_prefix(None) == "fastmcp:task:anon"
+
+
+def test_redis_prefix_disjoint_for_anon_vs_literal_anon_scope():
+    assert task_redis_prefix(None) != task_redis_prefix("anon")
+
+
+def test_redis_prefix_disjoint_for_anon_vs_literal_underscore_scope():
+    assert task_redis_prefix(None) != task_redis_prefix("_")
+
+
+def test_redis_prefix_encodes_special_characters():
+    # Colons, slashes, pipes in the scope must not break the prefix shape.
+    prefix = task_redis_prefix("client:a/b|sub")
+    assert prefix.startswith("fastmcp:task:auth:")
+    # Exactly four ":" delimiters: fastmcp / task / auth / encoded-scope.
+    assert prefix.count(":") == 3
+
+
+def test_docket_and_redis_prefixes_agree_on_partition():
+    """The Docket key tag and the Redis prefix tag must always match — that is
+    the load-bearing invariant for cross-scope isolation."""
+    auth_docket = build_task_key("client-a", "task-1", "tool", "x")
+    auth_redis = task_redis_prefix("client-a")
+    assert auth_docket.split(":", 1)[0] == "auth"
+    assert ":auth:" in auth_redis
+
+    anon_docket = build_task_key(None, "task-1", "tool", "x")
+    anon_redis = task_redis_prefix(None)
+    assert anon_docket.split(":", 1)[0] == "anon"
+    assert anon_redis.endswith(":anon")
diff --git a/tests/server/tasks/test_task_meta_parameter.py b/tests/server/tasks/test_task_meta_parameter.py
new file mode 100644
index 0000000..e769306
--- /dev/null
+++ b/tests/server/tasks/test_task_meta_parameter.py
@@ -0,0 +1,314 @@
+"""
+Tests for the explicit task_meta parameter on FastMCP.call_tool().
+
+These tests verify that the task_meta parameter provides explicit control
+over sync vs task execution, replacing implicit contextvar-based behavior.
+"""
+
+import mcp_types
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.exceptions import ToolError
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.server.tasks.config import TaskMeta
+from fastmcp.tools.base import Tool, ToolResult
+
+
+class TestTaskMetaParameter:
+    """Tests for task_meta parameter on FastMCP.call_tool()."""
+
+    async def test_task_meta_none_returns_tool_result(self):
+        """With task_meta=None (default), call_tool returns ToolResult."""
+        server = FastMCP("test")
+
+        @server.tool
+        async def simple_tool(x: int) -> int:
+            return x * 2
+
+        result = await server.call_tool("simple_tool", {"x": 5})
+
+        first_content = result.content[0]
+        assert isinstance(first_content, mcp_types.TextContent)
+        assert first_content.text == "10"
+
+    async def test_task_meta_none_on_task_enabled_tool_still_returns_tool_result(self):
+        """Even for task=True tools, task_meta=None returns ToolResult synchronously."""
+        server = FastMCP("test")
+
+        @server.tool(task=True)
+        async def task_enabled_tool(x: int) -> int:
+            return x * 2
+
+        # Without task_meta, should execute synchronously
+        result = await server.call_tool("task_enabled_tool", {"x": 5})
+
+        first_content = result.content[0]
+        assert isinstance(first_content, mcp_types.TextContent)
+        assert first_content.text == "10"
+
+    async def test_task_meta_on_forbidden_tool_raises_error(self):
+        """Providing task_meta to a task=False tool raises ToolError."""
+        server = FastMCP("test")
+
+        @server.tool(task=False)
+        async def sync_only_tool(x: int) -> int:
+            return x * 2
+
+        # Error is raised before docket is needed (MCPError wrapped as ToolError)
+        with pytest.raises(ToolError) as exc_info:
+            await server.call_tool("sync_only_tool", {"x": 5}, task_meta=TaskMeta())
+
+        assert "does not support task-augmented execution" in str(exc_info.value)
+
+    async def test_task_meta_fn_key_auto_populated_in_call_tool(self):
+        """fn_key is auto-populated from tool name in call_tool()."""
+        server = FastMCP("test")
+
+        @server.tool(task=True)
+        async def auto_key_tool() -> str:
+            return "done"
+
+        # Verify fn_key starts as None
+        task_meta = TaskMeta()
+        assert task_meta.fn_key is None
+
+        # call_tool enriches the task_meta before passing to _run
+        # We test this via the client integration path
+        async with Client(server) as client:
+            result = await client.call_tool("auto_key_tool", {}, task=True)
+            # Should succeed because fn_key was auto-populated
+            from fastmcp.client.tasks import ToolTask
+
+            assert isinstance(result, ToolTask)
+
+    async def test_task_meta_fn_key_enrichment_logic(self):
+        """Verify that fn_key enrichment uses Tool.make_key()."""
+        # Direct test of the enrichment logic
+        tool_name = "my_tool"
+        expected_key = Tool.make_key(tool_name)
+
+        assert expected_key == "tool:my_tool"
+
+
+class TestTaskMetaTTL:
+    """Tests for task_meta.ttl behavior."""
+
+    async def test_task_with_custom_ttl_creates_task(self):
+        """task_meta.ttl is passed through when creating tasks."""
+        server = FastMCP("test")
+
+        @server.tool(task=True)
+        async def ttl_tool() -> str:
+            return "done"
+
+        custom_ttl_ms = 30000  # 30 seconds
+
+        async with Client(server) as client:
+            # Use client.call_tool with task=True and ttl
+            task = await client.call_tool("ttl_tool", {}, task=True, ttl=custom_ttl_ms)
+
+            from fastmcp.client.tasks import ToolTask
+
+            assert isinstance(task, ToolTask)
+
+            # Verify task completes successfully
+            result = await task.result()
+            assert "done" in str(result)
+
+    async def test_task_without_ttl_uses_default(self):
+        """task_meta.ttl=None uses docket.execution_ttl default."""
+        server = FastMCP("test")
+
+        @server.tool(task=True)
+        async def default_ttl_tool() -> str:
+            return "done"
+
+        async with Client(server) as client:
+            # Use client.call_tool with task=True, default ttl
+            task = await client.call_tool("default_ttl_tool", {}, task=True)
+
+            from fastmcp.client.tasks import ToolTask
+
+            assert isinstance(task, ToolTask)
+
+            # Verify task completes successfully
+            result = await task.result()
+            assert "done" in str(result)
+
+
+class TrackingMiddleware(Middleware):
+    """Middleware that tracks tool calls."""
+
+    def __init__(self, calls: list[str]):
+        super().__init__()
+        self._calls = calls
+
+    async def on_call_tool(
+        self,
+        context: MiddlewareContext[mcp_types.CallToolRequestParams],
+        call_next: CallNext[mcp_types.CallToolRequestParams, ToolResult],
+    ) -> ToolResult:
+        if context.method:
+            self._calls.append(context.method)
+        return await call_next(context)
+
+
+class TestTaskMetaMiddleware:
+    """Tests that task_meta is properly propagated through middleware."""
+
+    async def test_task_meta_propagated_through_middleware(self):
+        """task_meta is passed through middleware chain."""
+        server = FastMCP("test")
+        middleware_saw_request: list[str] = []
+
+        @server.tool(task=True)
+        async def middleware_test_tool() -> str:
+            return "done"
+
+        server.add_middleware(TrackingMiddleware(middleware_saw_request))
+
+        async with Client(server) as client:
+            # Use client to trigger the middleware chain
+            task = await client.call_tool("middleware_test_tool", {}, task=True)
+
+            # Middleware should have run
+            assert "tools/call" in middleware_saw_request
+
+            # And task should have been created
+            from fastmcp.client.tasks import ToolTask
+
+            assert isinstance(task, ToolTask)
+
+
+class TestTaskMetaClientIntegration:
+    """Tests that task_meta works correctly with the Client."""
+
+    async def test_client_task_true_maps_to_task_meta(self):
+        """Client's task=True creates proper task_meta on server."""
+        server = FastMCP("test")
+
+        @server.tool(task=True)
+        async def client_test_tool(x: int) -> int:
+            return x * 2
+
+        async with Client(server) as client:
+            # Client passes task=True, server receives as task_meta
+            task = await client.call_tool("client_test_tool", {"x": 5}, task=True)
+
+            # Should get back a ToolTask (client wrapper)
+            from fastmcp.client.tasks import ToolTask
+
+            assert isinstance(task, ToolTask)
+
+            # Wait for result
+            result = await task.result()
+            assert "10" in str(result)
+
+    async def test_client_without_task_gets_immediate_result(self):
+        """Client without task=True gets immediate result."""
+        server = FastMCP("test")
+
+        @server.tool(task=True)
+        async def immediate_tool(x: int) -> int:
+            return x * 2
+
+        async with Client(server) as client:
+            # No task=True, should execute synchronously
+            result = await client.call_tool("immediate_tool", {"x": 5})
+
+            # Should get CallToolResult directly
+            assert "10" in str(result)
+
+    async def test_client_task_with_custom_ttl(self):
+        """Client can pass custom TTL for task execution."""
+        server = FastMCP("test")
+
+        @server.tool(task=True)
+        async def custom_ttl_tool() -> str:
+            return "done"
+
+        custom_ttl_ms = 60000  # 60 seconds
+
+        async with Client(server) as client:
+            task = await client.call_tool(
+                "custom_ttl_tool", {}, task=True, ttl=custom_ttl_ms
+            )
+
+            from fastmcp.client.tasks import ToolTask
+
+            assert isinstance(task, ToolTask)
+
+            # Verify task completes successfully
+            result = await task.result()
+            assert "done" in str(result)
+
+
+class TestTaskMetaDirectServerCall:
+    """Tests for direct server calls (tool calling another tool)."""
+
+    async def test_tool_can_call_another_tool_with_task(self):
+        """A tool can call another tool as a background task."""
+        server = FastMCP("test")
+
+        @server.tool(task=True)
+        async def inner_tool(x: int) -> int:
+            return x * 2
+
+        @server.tool
+        async def outer_tool(x: int) -> str:
+            # Call inner tool as background task
+            result = await server.call_tool(
+                "inner_tool", {"x": x}, task_meta=TaskMeta()
+            )
+            # Should get CreateTaskResult since we're in server context
+            return f"Created task: {result.task.task_id}"
+
+        async with Client(server) as client:
+            # Call outer_tool which internally calls inner_tool with task_meta
+            result = await client.call_tool("outer_tool", {"x": 5})
+            # The outer tool should have successfully created a background task
+            assert "Created task:" in str(result)
+
+    async def test_tool_can_call_another_tool_synchronously(self):
+        """A tool can call another tool synchronously (no task_meta)."""
+        server = FastMCP("test")
+
+        @server.tool(task=True)
+        async def inner_tool(x: int) -> int:
+            return x * 2
+
+        @server.tool
+        async def outer_tool(x: int) -> str:
+            # Call inner tool synchronously (no task_meta)
+            result = await server.call_tool("inner_tool", {"x": x})
+            # Should get ToolResult directly
+            first_content = result.content[0]
+            assert isinstance(first_content, mcp_types.TextContent)
+            return f"Got result: {first_content.text}"
+
+        async with Client(server) as client:
+            result = await client.call_tool("outer_tool", {"x": 5})
+            assert "Got result: 10" in str(result)
+
+    async def test_tool_can_call_another_tool_with_custom_ttl(self):
+        """A tool can call another tool as a background task with custom TTL."""
+        server = FastMCP("test")
+
+        @server.tool(task=True)
+        async def inner_tool(x: int) -> int:
+            return x * 2
+
+        @server.tool
+        async def outer_tool(x: int) -> str:
+            custom_ttl = 45000  # 45 seconds
+            result = await server.call_tool(
+                "inner_tool", {"x": x}, task_meta=TaskMeta(ttl=custom_ttl)
+            )
+            return f"Task TTL: {result.task.ttl}"
+
+        async with Client(server) as client:
+            result = await client.call_tool("outer_tool", {"x": 5})
+            # The inner tool task should have the custom TTL
+            assert "Task TTL: 45000" in str(result)
diff --git a/tests/server/tasks/test_task_metadata.py b/tests/server/tasks/test_task_metadata.py
new file mode 100644
index 0000000..0d8935d
--- /dev/null
+++ b/tests/server/tasks/test_task_metadata.py
@@ -0,0 +1,63 @@
+"""
+Tests for SEP-1686 related-task metadata in protocol responses.
+
+Per the spec, all task-related responses MUST include
+io.modelcontextprotocol/related-task in _meta.
+"""
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+
+
+@pytest.fixture
+async def metadata_server():
+    """Create a server for testing metadata."""
+    mcp = FastMCP("metadata-test")
+
+    @mcp.tool(task=True)
+    async def test_tool(value: int) -> int:
+        return value * 2
+
+    return mcp
+
+
+async def test_tasks_get_includes_related_task_metadata(metadata_server: FastMCP):
+    """tasks/get response includes io.modelcontextprotocol/related-task in _meta."""
+    async with Client(metadata_server) as client:
+        # Submit a task
+        task = await client.call_tool("test_tool", {"value": 5}, task=True)
+        task_id = task.task_id
+
+        # Get status via client (which uses protocol properly)
+        status = await client.get_task_status(task_id)
+
+        # GetTaskResult is returned from response with metadata
+        # Verify the protocol included related-task metadata by checking the response worked
+        assert status.task_id == task_id
+        assert status.status in ["working", "completed"]
+
+
+async def test_tasks_result_includes_related_task_metadata(metadata_server: FastMCP):
+    """tasks/result response includes io.modelcontextprotocol/related-task in _meta."""
+    async with Client(metadata_server) as client:
+        # Submit and complete a task
+        task = await client.call_tool("test_tool", {"value": 7}, task=True)
+        result = await task.result()
+
+        # Result should have metadata (added by task.result() or protocol)
+        # Just verify the result is valid and contains the expected value
+        assert result.content
+        assert result.data == 14  # 7 * 2
+
+
+async def test_tasks_list_includes_related_task_metadata(metadata_server: FastMCP):
+    """tasks/list response includes io.modelcontextprotocol/related-task in _meta."""
+    async with Client(metadata_server) as client:
+        # List tasks via client (which uses protocol properly)
+        result = await client.list_tasks()
+
+        # Verify list_tasks works and returns proper structure
+        assert "tasks" in result
+        assert isinstance(result["tasks"], list)
diff --git a/tests/server/tasks/test_task_methods.py b/tests/server/tasks/test_task_methods.py
new file mode 100644
index 0000000..493bc91
--- /dev/null
+++ b/tests/server/tasks/test_task_methods.py
@@ -0,0 +1,218 @@
+"""
+Tests for task protocol methods.
+
+Tests the tasks/get, tasks/result, and tasks/list JSON-RPC protocol methods.
+"""
+
+import asyncio
+
+import pytest
+from mcp.shared.exceptions import MCPError
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+
+
+@pytest.fixture
+async def endpoint_server():
+    """Create a server with background tasks and HTTP transport."""
+    mcp = FastMCP("endpoint-test-server")
+
+    @mcp.tool(task=True)  # Enable background execution
+    async def quick_tool(value: int) -> int:
+        """Returns the value immediately."""
+        return value * 2
+
+    @mcp.tool(task=True)  # Enable background execution
+    async def error_tool() -> str:
+        """Always raises an error."""
+        raise RuntimeError("Task failed!")
+
+    @mcp.tool(task=True)  # Enable background execution
+    async def slow_tool() -> str:
+        """A slow tool for testing cancellation."""
+        await asyncio.sleep(10)
+        return "done"
+
+    return mcp
+
+
+async def test_tasks_get_endpoint_returns_status(endpoint_server):
+    """POST /tasks/get returns task status."""
+    async with Client(endpoint_server) as client:
+        # Submit a task
+        task = await client.call_tool("quick_tool", {"value": 21}, task=True)
+
+        # Check status immediately - should be submitted or working
+        status = await task.status()
+        assert status.task_id == task.task_id
+        assert status.status in ["working", "completed"]
+
+        # Wait for completion
+        await task.wait(timeout=2.0)
+
+        # Check again - should be completed
+        status = await task.status()
+        assert status.status == "completed"
+
+
+async def test_tasks_get_endpoint_includes_poll_interval(endpoint_server):
+    """Task status includes pollFrequency hint."""
+    async with Client(endpoint_server) as client:
+        task = await client.call_tool("quick_tool", {"value": 42}, task=True)
+
+        status = await task.status()
+        assert status.poll_interval is not None
+        assert isinstance(status.poll_interval, int)
+
+
+async def test_tasks_result_endpoint_returns_result_when_completed(endpoint_server):
+    """POST /tasks/result returns the tool result when completed."""
+    async with Client(endpoint_server) as client:
+        task = await client.call_tool("quick_tool", {"value": 21}, task=True)
+
+        # Wait for completion and get result
+        result = await task.result()
+        assert result.data == 42  # 21 * 2
+
+
+async def test_tasks_result_endpoint_errors_if_not_completed(endpoint_server):
+    """POST /tasks/result returns error if task not completed yet."""
+    # Create a task that won't complete until signaled
+    completion_signal = asyncio.Event()
+
+    @endpoint_server.tool(task=True)  # Enable background execution
+    async def blocked_tool() -> str:
+        await completion_signal.wait()
+        return "done"
+
+    async with Client(endpoint_server) as client:
+        task = await client.call_tool("blocked_tool", task=True)
+
+        # Try to get result immediately (task still running)
+        with pytest.raises(Exception):  # Should raise or return error
+            await client.get_task_result(task.task_id)
+
+        # Cleanup - signal completion
+        completion_signal.set()
+
+
+async def test_tasks_result_endpoint_errors_if_task_not_found(endpoint_server):
+    """POST /tasks/result returns error for non-existent task."""
+    async with Client(endpoint_server) as client:
+        # Try to get result for non-existent task
+        with pytest.raises(Exception):
+            await client.get_task_result("non-existent-task-id")
+
+
+async def test_tasks_result_endpoint_returns_error_for_failed_task(endpoint_server):
+    """POST /tasks/result returns error information for failed tasks."""
+    async with Client(endpoint_server) as client:
+        task = await client.call_tool("error_tool", task=True)
+
+        # Wait for task to fail
+        await task.wait(state="failed", timeout=2.0)
+
+        # Getting result should raise or return error info
+        with pytest.raises(Exception) as exc_info:
+            await task.result()
+
+        assert (
+            "failed" in str(exc_info.value).lower()
+            or "error" in str(exc_info.value).lower()
+        )
+
+
+async def test_tasks_list_endpoint_session_isolation(endpoint_server):
+    """list_tasks returns only tasks submitted by this client."""
+    # Since client tracks tasks locally, this tests client-side tracking
+    async with Client(endpoint_server) as client:
+        # Submit multiple tasks (server generates IDs)
+        tasks = []
+        for i in range(3):
+            task = await client.call_tool("quick_tool", {"value": i}, task=True)
+            tasks.append(task)
+
+        # Wait for all to complete
+        for task in tasks:
+            await task.wait(timeout=2.0)
+
+        # List tasks - should see all 3
+        response = await client.list_tasks()
+        returned_ids = [t["taskId"] for t in response["tasks"]]
+        task_ids = [t.task_id for t in tasks]
+        assert len(returned_ids) == 3
+        assert all(tid in task_ids for tid in returned_ids)
+
+
+async def test_get_status_nonexistent_task_raises_error(endpoint_server):
+    """Getting status for nonexistent task raises MCP error (per SEP-1686 SDK behavior)."""
+    async with Client(endpoint_server) as client:
+        # Try to get status for task that was never created
+        # Per SDK implementation: raises ValueError which becomes JSON-RPC error
+        with pytest.raises(MCPError, match="Task nonexistent-task-id not found"):
+            await client.get_task_status("nonexistent-task-id")
+
+
+async def test_task_cancellation_workflow(endpoint_server):
+    """Task can be cancelled, transitioning to cancelled state."""
+    async with Client(endpoint_server) as client:
+        # Submit slow task
+        task = await client.call_tool("slow_tool", {}, task=True)
+
+        # Give it a moment to start
+        await asyncio.sleep(0.1)
+
+        # Cancel the task
+        await task.cancel()
+
+        # Give cancellation a moment to process
+        await asyncio.sleep(0.1)
+
+        # Task should be in cancelled state
+        status = await task.status()
+        assert status.status == "cancelled"
+
+
+@pytest.mark.timeout(10)
+async def test_task_cancellation_interrupts_running_coroutine(endpoint_server):
+    """Task cancellation actually interrupts the running coroutine.
+
+    This verifies that when a task is cancelled, the underlying asyncio
+    coroutine receives CancelledError rather than continuing to completion.
+    Requires pydocket >= 0.16.2.
+
+    See: https://github.com/PrefectHQ/fastmcp/issues/2679
+    """
+    started = asyncio.Event()
+    was_interrupted = asyncio.Event()
+    completed_normally = asyncio.Event()
+
+    @endpoint_server.tool(task=True)
+    async def interruptible_tool() -> str:
+        started.set()
+        try:
+            await asyncio.sleep(60)
+            completed_normally.set()
+            return "completed"
+        except asyncio.CancelledError:
+            was_interrupted.set()
+            raise
+
+    async with Client(endpoint_server) as client:
+        task = await client.call_tool("interruptible_tool", {}, task=True)
+
+        # Wait for the tool to actually start executing
+        await asyncio.wait_for(started.wait(), timeout=5.0)
+
+        # Cancel the task
+        await task.cancel()
+
+        # Wait for cancellation to propagate
+        await asyncio.wait_for(was_interrupted.wait(), timeout=5.0)
+
+        # The coroutine should have been interrupted, not completed normally
+        assert was_interrupted.is_set(), "Task was not interrupted by cancellation"
+        assert not completed_normally.is_set(), (
+            "Task completed instead of being cancelled"
+        )
diff --git a/tests/server/tasks/test_task_mount.py b/tests/server/tasks/test_task_mount.py
new file mode 100644
index 0000000..0401259
--- /dev/null
+++ b/tests/server/tasks/test_task_mount.py
@@ -0,0 +1,1124 @@
+"""
+Tests for MCP SEP-1686 task protocol support through mounted servers.
+
+Verifies that tasks work seamlessly when calling tools/prompts/resources
+on mounted child servers through a parent server.
+"""
+
+import asyncio
+
+import mcp_types as mt
+import pytest
+from docket import Docket
+from mcp_types import Tool as MCPTool
+from mcp_types import ToolExecution
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.prompts.base import PromptResult
+from fastmcp.resources.base import ResourceResult
+from fastmcp.server.dependencies import CurrentDocket, CurrentFastMCP
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.server.providers.proxy import ProxyTool
+from fastmcp.server.tasks import TaskConfig
+from fastmcp.tools.base import ToolResult
+
+
+@pytest.fixture(autouse=True)
+def reset_docket_memory_server():
+    """Reset the shared Docket memory server between tests.
+
+    Docket uses a class-level FakeServer instance for memory:// URLs which
+    persists between tests, causing test isolation issues. This fixture
+    clears that shared state before each test.
+    """
+    # Clear the shared FakeServer before each test
+    if hasattr(Docket, "_memory_server"):
+        delattr(Docket, "_memory_server")
+    yield
+    # Clean up after test as well
+    if hasattr(Docket, "_memory_server"):
+        delattr(Docket, "_memory_server")
+
+
+@pytest.fixture
+def child_server():
+    """Create a child server with task-enabled components."""
+    mcp = FastMCP("child-server")
+
+    @mcp.tool(task=True)
+    async def multiply(a: int, b: int) -> int:
+        """Multiply two numbers."""
+        return a * b
+
+    @mcp.tool(task=True)
+    async def slow_child_tool(duration: float = 0.1) -> str:
+        """A child tool that takes time to execute."""
+        await asyncio.sleep(duration)
+        return "child completed"
+
+    @mcp.tool(task=False)
+    async def sync_child_tool(message: str) -> str:
+        """Child tool that only supports synchronous execution."""
+        return f"child sync: {message}"
+
+    @mcp.prompt(task=True)
+    async def child_prompt(topic: str) -> str:
+        """A child prompt that can execute as a task."""
+        return f"Here is information about {topic} from the child server."
+
+    @mcp.resource("child://data.txt", task=True)
+    async def child_resource() -> str:
+        """A child resource that can be read as a task."""
+        return "Data from child server"
+
+    @mcp.resource("child://item/{item_id}.json", task=True)
+    async def child_item_resource(item_id: str) -> str:
+        """A child resource template that can execute as a task."""
+        return f'{{"itemId": "{item_id}", "source": "child"}}'
+
+    return mcp
+
+
+@pytest.fixture
+def parent_server(child_server):
+    """Create a parent server with the child mounted."""
+    parent = FastMCP("parent-server")
+
+    @parent.tool(task=True)
+    async def parent_tool(value: int) -> int:
+        """A tool on the parent server."""
+        return value * 10
+
+    # Mount child with prefix
+    parent.mount(child_server, namespace="child")
+
+    return parent
+
+
+@pytest.fixture
+def parent_server_no_prefix(child_server):
+    """Create a parent server with child mounted without prefix."""
+    parent = FastMCP("parent-no-prefix")
+    parent.mount(child_server)  # No prefix
+    return parent
+
+
+class TestMountedToolTasks:
+    """Test task execution for mounted tools."""
+
+    async def test_mounted_tool_task_returns_task_object(self, parent_server):
+        """Mounted tool called with task=True returns a task object."""
+        async with Client(parent_server) as client:
+            # Tool name is prefixed: child_multiply
+            task = await client.call_tool("child_multiply", {"a": 6, "b": 7}, task=True)
+
+            assert task is not None
+            assert hasattr(task, "task_id")
+            assert isinstance(task.task_id, str)
+            assert len(task.task_id) > 0
+
+    async def test_mounted_tool_task_executes_in_background(self, parent_server):
+        """Mounted tool task executes in background."""
+        async with Client(parent_server) as client:
+            task = await client.call_tool("child_multiply", {"a": 3, "b": 4}, task=True)
+
+            # Should execute in background
+            assert not task.returned_immediately
+
+    async def test_mounted_tool_task_returns_correct_result(
+        self, parent_server: FastMCP
+    ):
+        """Mounted tool task returns correct result."""
+        async with Client(parent_server) as client:
+            task = await client.call_tool("child_multiply", {"a": 8, "b": 9}, task=True)
+
+            result = await task.result()
+            assert result.data == 72
+
+    async def test_mounted_tool_task_status(self, parent_server):
+        """Can poll task status for mounted tool."""
+        async with Client(parent_server) as client:
+            task = await client.call_tool(
+                "child_slow_child_tool", {"duration": 0.5}, task=True
+            )
+
+            # Check status while running
+            status = await task.status()
+            assert status.status in ["working", "completed"]
+
+            # Wait for completion
+            await task.wait(timeout=2.0)
+
+            # Check status after completion
+            status = await task.status()
+            assert status.status == "completed"
+
+    @pytest.mark.timeout(10)
+    async def test_mounted_tool_task_cancellation(self, parent_server):
+        """Can cancel a mounted tool task."""
+        async with Client(parent_server) as client:
+            task = await client.call_tool(
+                "child_slow_child_tool", {"duration": 10.0}, task=True
+            )
+
+            # Let it start
+            await asyncio.sleep(0.1)
+
+            # Cancel the task
+            await task.cancel()
+
+            # Check status
+            status = await task.status()
+            assert status.status == "cancelled"
+
+    async def test_graceful_degradation_sync_mounted_tool(self, parent_server):
+        """Sync-only mounted tool returns error with task=True."""
+        async with Client(parent_server) as client:
+            task = await client.call_tool(
+                "child_sync_child_tool",
+                {"message": "hello"},
+                task=True,
+                raise_on_error=False,
+            )
+
+            # Should return immediately with an error
+            assert task.returned_immediately
+
+            result = await task.result()
+            assert result.is_error
+
+    async def test_parent_and_mounted_tools_both_work(self, parent_server):
+        """Both parent and mounted tools work as tasks."""
+        async with Client(parent_server) as client:
+            # Parent tool
+            parent_task = await client.call_tool("parent_tool", {"value": 5}, task=True)
+            # Mounted tool
+            child_task = await client.call_tool(
+                "child_multiply", {"a": 2, "b": 3}, task=True
+            )
+
+            parent_result = await parent_task.result()
+            child_result = await child_task.result()
+
+            assert parent_result.data == 50
+            assert child_result.data == 6
+
+
+class TestMountedToolTasksNoPrefix:
+    """Test task execution for mounted tools without prefix."""
+
+    async def test_mounted_tool_without_prefix_task_works(
+        self, parent_server_no_prefix
+    ):
+        """Mounted tool without prefix works as task."""
+        async with Client(parent_server_no_prefix) as client:
+            # No prefix, so tool keeps original name
+            task = await client.call_tool("multiply", {"a": 5, "b": 6}, task=True)
+
+            assert not task.returned_immediately
+
+            result = await task.result()
+            assert result.data == 30
+
+
+class TestMountedPromptTasks:
+    """Test task execution for mounted prompts."""
+
+    async def test_mounted_prompt_task_returns_task_object(self, parent_server):
+        """Mounted prompt called with task=True returns a task object."""
+        async with Client(parent_server) as client:
+            # Prompt name is prefixed: child_child_prompt
+            task = await client.get_prompt(
+                "child_child_prompt", {"topic": "FastMCP"}, task=True
+            )
+
+            assert task is not None
+            assert hasattr(task, "task_id")
+            assert isinstance(task.task_id, str)
+
+    @pytest.mark.xfail(
+        reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+        "ReadResourceRequestParams; prompt/resource task submission is not "
+        "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+        strict=True,
+    )
+    async def test_mounted_prompt_task_executes_in_background(self, parent_server):
+        """Mounted prompt task executes in background."""
+        async with Client(parent_server) as client:
+            task = await client.get_prompt(
+                "child_child_prompt", {"topic": "testing"}, task=True
+            )
+
+            assert not task.returned_immediately
+
+    async def test_mounted_prompt_task_returns_correct_result(
+        self, parent_server: FastMCP
+    ):
+        """Mounted prompt task returns correct result."""
+        async with Client(parent_server) as client:
+            task = await client.get_prompt(
+                "child_child_prompt", {"topic": "MCP protocol"}, task=True
+            )
+
+            result = await task.result()
+            assert "MCP protocol" in result.messages[0].content.text
+            assert "child server" in result.messages[0].content.text
+
+
+class TestMountedResourceTasks:
+    """Test task execution for mounted resources."""
+
+    async def test_mounted_resource_task_returns_task_object(self, parent_server):
+        """Mounted resource read with task=True returns a task object."""
+        async with Client(parent_server) as client:
+            # Resource URI is prefixed: child://child/data.txt
+            task = await client.read_resource("child://child/data.txt", task=True)
+
+            assert task is not None
+            assert hasattr(task, "task_id")
+            assert isinstance(task.task_id, str)
+
+    @pytest.mark.xfail(
+        reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+        "ReadResourceRequestParams; prompt/resource task submission is not "
+        "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+        strict=True,
+    )
+    async def test_mounted_resource_task_executes_in_background(self, parent_server):
+        """Mounted resource task executes in background."""
+        async with Client(parent_server) as client:
+            task = await client.read_resource("child://child/data.txt", task=True)
+
+            assert not task.returned_immediately
+
+    async def test_mounted_resource_task_returns_correct_result(self, parent_server):
+        """Mounted resource task returns correct result."""
+        async with Client(parent_server) as client:
+            task = await client.read_resource("child://child/data.txt", task=True)
+
+            result = await task.result()
+            assert len(result) > 0
+            assert "Data from child server" in result[0].text
+
+    @pytest.mark.xfail(
+        reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+        "ReadResourceRequestParams; prompt/resource task submission is not "
+        "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+        strict=True,
+    )
+    async def test_mounted_resource_template_task(self, parent_server):
+        """Mounted resource template with task=True works."""
+        async with Client(parent_server) as client:
+            task = await client.read_resource("child://child/item/99.json", task=True)
+
+            assert not task.returned_immediately
+
+            result = await task.result()
+            assert '"itemId": "99"' in result[0].text
+            assert '"source": "child"' in result[0].text
+
+
+class TestMountedTaskDependencies:
+    """Test that dependencies work correctly in mounted task execution."""
+
+    async def test_mounted_task_receives_docket_dependency(self):
+        """Mounted tool task receives CurrentDocket dependency."""
+        child = FastMCP("dep-child")
+        received_docket = []
+
+        @child.tool(task=True)
+        async def tool_with_docket(docket: CurrentDocket = CurrentDocket()) -> str:  # type: ignore[invalid-type-form]  # ty:ignore[invalid-type-form]
+            received_docket.append(docket)
+            return f"docket available: {docket is not None}"
+
+        parent = FastMCP("dep-parent")
+        parent.mount(child, namespace="child")
+
+        async with Client(parent) as client:
+            task = await client.call_tool("child_tool_with_docket", {}, task=True)
+            result = await task.result()
+
+            assert "docket available: True" in str(result)
+            assert len(received_docket) == 1
+            assert received_docket[0] is not None
+
+    async def test_mounted_task_receives_server_dependency(self):
+        """Mounted tool task receives CurrentFastMCP dependency."""
+        child = FastMCP("server-dep-child")
+        received_server = []
+
+        @child.tool(task=True)
+        async def tool_with_server(server: CurrentFastMCP = CurrentFastMCP()) -> str:  # type: ignore[invalid-type-form]  # ty:ignore[invalid-type-form]
+            received_server.append(server)
+            return f"server name: {server.name}"
+
+        parent = FastMCP("server-dep-parent")
+        parent.mount(child, namespace="child")
+
+        async with Client(parent) as client:
+            task = await client.call_tool("child_tool_with_server", {}, task=True)
+            await task.result()
+
+            assert len(received_server) == 1
+            assert received_server[0].name == "server-dep-child"
+
+
+class TestMountedTaskServerContext:
+    """Test that background tasks on mounted servers resolve to the child server (#3571)."""
+
+    async def test_current_fastmcp_resolves_to_child_server(self):
+        """CurrentFastMCP() inside a mounted background task returns the child server."""
+        child = FastMCP("child")
+        received_server: list[FastMCP] = []
+
+        @child.tool(task=True)
+        async def whoami(server: CurrentFastMCP = CurrentFastMCP()) -> str:  # type: ignore[invalid-type-form]  # ty:ignore[invalid-type-form]
+            received_server.append(server)
+            return f"server name: {server.name}"
+
+        parent = FastMCP("parent")
+        parent.mount(child, namespace="child")
+
+        async with Client(parent) as client:
+            task = await client.call_tool("child_whoami", {}, task=True)
+            result = await task.result()
+
+        assert len(received_server) == 1
+        assert received_server[0].name == "child"
+        assert "server name: child" in str(result)
+
+    async def test_context_fastmcp_resolves_to_child_server(self):
+        """ctx.fastmcp inside a mounted background task returns the child server."""
+        from fastmcp import Context
+
+        child = FastMCP("child")
+        received_server: list[FastMCP] = []
+
+        @child.tool(task=True)
+        async def whoami_ctx(ctx: Context) -> str:
+            received_server.append(ctx.fastmcp)
+            return f"context server: {ctx.fastmcp.name}"
+
+        parent = FastMCP("parent")
+        parent.mount(child, namespace="child")
+
+        async with Client(parent) as client:
+            task = await client.call_tool("child_whoami_ctx", {}, task=True)
+            result = await task.result()
+
+        assert len(received_server) == 1
+        assert received_server[0].name == "child"
+        assert "context server: child" in str(result)
+
+    async def test_nested_mount_resolves_to_innermost_server(self):
+        """Doubly-nested mounts resolve to the innermost child server."""
+        grandchild = FastMCP("grandchild")
+        received_server: list[FastMCP] = []
+
+        @grandchild.tool(task=True)
+        async def deep_whoami(server: CurrentFastMCP = CurrentFastMCP()) -> str:  # type: ignore[invalid-type-form]  # ty:ignore[invalid-type-form]
+            received_server.append(server)
+            return f"server name: {server.name}"
+
+        child = FastMCP("child")
+        child.mount(grandchild, namespace="gc")
+
+        parent = FastMCP("parent")
+        parent.mount(child, namespace="child")
+
+        async with Client(parent) as client:
+            task = await client.call_tool("child_gc_deep_whoami", {}, task=True)
+            result = await task.result()
+
+        assert len(received_server) == 1
+        assert received_server[0].name == "grandchild"
+        assert "server name: grandchild" in str(result)
+
+
+class TestMultipleMounts:
+    """Test tasks with multiple mounted servers."""
+
+    async def test_tasks_work_with_multiple_mounts(self):
+        """Tasks work correctly with multiple mounted servers."""
+        child1 = FastMCP("child1")
+        child2 = FastMCP("child2")
+
+        @child1.tool(task=True)
+        async def add(a: int, b: int) -> int:
+            return a + b
+
+        @child2.tool(task=True)
+        async def subtract(a: int, b: int) -> int:
+            return a - b
+
+        parent = FastMCP("multi-parent")
+        parent.mount(child1, namespace="math1")
+        parent.mount(child2, namespace="math2")
+
+        async with Client(parent) as client:
+            task1 = await client.call_tool("math1_add", {"a": 10, "b": 5}, task=True)
+            task2 = await client.call_tool(
+                "math2_subtract", {"a": 10, "b": 5}, task=True
+            )
+
+            result1 = await task1.result()
+            result2 = await task2.result()
+
+            assert result1.data == 15
+            assert result2.data == 5
+
+
+class TestMountedFunctionNameCollisions:
+    """Test task execution when mounted servers have identically-named functions."""
+
+    async def test_multiple_mounts_with_same_function_names(self):
+        """Two mounted servers with identically-named functions don't collide."""
+        child1 = FastMCP("child1")
+        child2 = FastMCP("child2")
+
+        @child1.tool(task=True)
+        async def process(value: int) -> int:
+            return value * 2  # Double
+
+        @child2.tool(task=True)
+        async def process(value: int) -> int:  # noqa: F811
+            return value * 3  # Triple
+
+        parent = FastMCP("parent")
+        parent.mount(child1, namespace="c1")
+        parent.mount(child2, namespace="c2")
+
+        async with Client(parent) as client:
+            # Both should execute their own implementation
+            task1 = await client.call_tool("c1_process", {"value": 10}, task=True)
+            task2 = await client.call_tool("c2_process", {"value": 10}, task=True)
+
+            result1 = await task1.result()
+            result2 = await task2.result()
+
+            assert result1.data == 20  # child1's process (doubles)
+            assert result2.data == 30  # child2's process (triples)
+
+    async def test_no_prefix_mount_collision(self):
+        """No-prefix mounts with same tool name - last mount wins."""
+        child1 = FastMCP("child1")
+        child2 = FastMCP("child2")
+
+        @child1.tool(task=True)
+        async def process(value: int) -> int:
+            return value * 2
+
+        @child2.tool(task=True)
+        async def process(value: int) -> int:  # noqa: F811
+            return value * 3
+
+        parent = FastMCP("parent")
+        parent.mount(child1)  # No prefix
+        parent.mount(child2)  # No prefix - overwrites child1's "process"
+
+        async with Client(parent) as client:
+            # Last mount wins - child2's process should execute
+            task = await client.call_tool("process", {"value": 10}, task=True)
+            result = await task.result()
+            assert result.data == 30  # child2's process (triples)
+
+    async def test_nested_mount_prefix_accumulation(self):
+        """Nested mounts accumulate prefixes correctly for tasks."""
+        grandchild = FastMCP("gc")
+        child = FastMCP("child")
+        parent = FastMCP("parent")
+
+        @grandchild.tool(task=True)
+        async def deep_tool() -> str:
+            return "deep"
+
+        child.mount(grandchild, namespace="gc")
+        parent.mount(child, namespace="child")
+
+        async with Client(parent) as client:
+            # Tool should be accessible and execute correctly
+            task = await client.call_tool("child_gc_deep_tool", {}, task=True)
+            result = await task.result()
+            assert result.data == "deep"
+
+
+class TestMountedTaskList:
+    """Test task listing with mounted servers."""
+
+    async def test_list_tasks_includes_mounted_tasks(self, parent_server):
+        """Task list includes tasks from mounted server tools."""
+        async with Client(parent_server) as client:
+            # Create tasks on both parent and mounted tools
+            parent_task = await client.call_tool("parent_tool", {"value": 1}, task=True)
+            child_task = await client.call_tool(
+                "child_multiply", {"a": 2, "b": 2}, task=True
+            )
+
+            # Wait for completion
+            await parent_task.wait(timeout=2.0)
+            await child_task.wait(timeout=2.0)
+
+            # List all tasks - returns dict with "tasks" key
+            tasks_response = await client.list_tasks()
+
+            task_ids = [t["taskId"] for t in tasks_response["tasks"]]
+            assert parent_task.task_id in task_ids
+            assert child_task.task_id in task_ids
+
+
+class TestMountedTaskMetadata:
+    """Test task metadata exposure for mounted tools."""
+
+    async def test_mounted_tool_list_preserves_task_support_metadata(self):
+        """Mounted tools should preserve execution.task_support in tools/list."""
+        child = FastMCP("child")
+
+        @child.tool(task=True)
+        async def foo() -> dict[str, bool]:
+            return {"ok": True}
+
+        parent = FastMCP("parent")
+        parent.mount(child)
+
+        child_tools = await child.list_tools()
+        parent_tools = await parent.list_tools()
+
+        child_tool = next(t for t in child_tools if t.name == "foo")
+        parent_tool = next(t for t in parent_tools if t.name == "foo")
+
+        child_mcp_tool = child_tool.to_mcp_tool(name=child_tool.name)
+        parent_mcp_tool = parent_tool.to_mcp_tool(name=parent_tool.name)
+
+        assert child_mcp_tool.execution is not None
+        assert parent_mcp_tool.execution is not None
+        assert child_mcp_tool.execution.task_support == "optional"
+        assert parent_mcp_tool.execution.task_support == "optional"
+
+    async def test_proxy_tool_preserves_execution_metadata(self):
+        """ProxyTool.from_mcp_tool should propagate execution.task_support (#3569)."""
+        mcp_tool = MCPTool(
+            name="remote_task_tool",
+            description="A remote tool that supports tasks",
+            input_schema={"type": "object", "properties": {}},
+            execution=ToolExecution(task_support="optional"),
+        )
+
+        proxy = ProxyTool.from_mcp_tool(lambda: None, mcp_tool)  # ty: ignore[invalid-argument-type]
+        result = proxy.to_mcp_tool(name=proxy.name)
+
+        assert result.execution is not None
+        assert result.execution.task_support == "optional"
+
+
+class TestMountedTaskConfigModes:
+    """Test TaskConfig mode enforcement for mounted tools."""
+
+    @pytest.fixture
+    def child_with_modes(self):
+        """Create a child server with tools in all three TaskConfig modes."""
+        mcp = FastMCP("child-modes", tasks=False)
+
+        @mcp.tool(task=TaskConfig(mode="optional"))
+        async def optional_tool() -> str:
+            """Tool that supports both sync and task execution."""
+            return "optional result"
+
+        @mcp.tool(task=TaskConfig(mode="required"))
+        async def required_tool() -> str:
+            """Tool that requires task execution."""
+            return "required result"
+
+        @mcp.tool(task=TaskConfig(mode="forbidden"))
+        async def forbidden_tool() -> str:
+            """Tool that forbids task execution."""
+            return "forbidden result"
+
+        return mcp
+
+    @pytest.fixture
+    def parent_with_modes(self, child_with_modes):
+        """Create a parent server with the child mounted."""
+        parent = FastMCP("parent-modes")
+        parent.mount(child_with_modes, namespace="child")
+        return parent
+
+    async def test_optional_mode_sync_through_mount(self, parent_with_modes):
+        """Optional mode tool works without task through mount."""
+        async with Client(parent_with_modes) as client:
+            result = await client.call_tool("child_optional_tool", {})
+            assert "optional result" in str(result)
+
+    async def test_optional_mode_task_through_mount(self, parent_with_modes):
+        """Optional mode tool works with task through mount."""
+        async with Client(parent_with_modes) as client:
+            task = await client.call_tool("child_optional_tool", {}, task=True)
+            assert task is not None
+            result = await task.result()
+            assert result.data == "optional result"
+
+    async def test_required_mode_with_task_through_mount(self, parent_with_modes):
+        """Required mode tool succeeds with task through mount."""
+        async with Client(parent_with_modes) as client:
+            task = await client.call_tool("child_required_tool", {}, task=True)
+            assert task is not None
+            result = await task.result()
+            assert result.data == "required result"
+
+    async def test_required_mode_without_task_through_mount(self, parent_with_modes):
+        """Required mode tool errors without task through mount."""
+        from fastmcp.exceptions import ToolError
+
+        async with Client(parent_with_modes) as client:
+            with pytest.raises(ToolError) as exc_info:
+                await client.call_tool("child_required_tool", {})
+
+            assert "requires task-augmented execution" in str(exc_info.value)
+
+    async def test_forbidden_mode_sync_through_mount(self, parent_with_modes):
+        """Forbidden mode tool works without task through mount."""
+        async with Client(parent_with_modes) as client:
+            result = await client.call_tool("child_forbidden_tool", {})
+            assert "forbidden result" in str(result)
+
+    async def test_forbidden_mode_with_task_through_mount(self, parent_with_modes):
+        """Forbidden mode tool degrades gracefully with task through mount."""
+        async with Client(parent_with_modes) as client:
+            task = await client.call_tool(
+                "child_forbidden_tool", {}, task=True, raise_on_error=False
+            )
+
+            # Should return immediately (graceful degradation)
+            assert task.returned_immediately
+
+            result = await task.result()
+            # Result is available but may indicate error or sync execution
+            assert result is not None
+
+
+# -----------------------------------------------------------------------------
+# Middleware classes for tracing tests
+# -----------------------------------------------------------------------------
+
+
+class ToolTracingMiddleware(Middleware):
+    """Middleware that traces tool calls."""
+
+    def __init__(self, name: str, calls: list[str]):
+        super().__init__()
+        self._name = name
+        self._calls = calls
+
+    async def on_call_tool(
+        self,
+        context: MiddlewareContext[mt.CallToolRequestParams],
+        call_next: CallNext[mt.CallToolRequestParams, ToolResult],
+    ) -> ToolResult:
+        self._calls.append(f"{self._name}:before")
+        result = await call_next(context)
+        self._calls.append(f"{self._name}:after")
+        return result
+
+
+class ResourceTracingMiddleware(Middleware):
+    """Middleware that traces resource reads."""
+
+    def __init__(self, name: str, calls: list[str]):
+        super().__init__()
+        self._name = name
+        self._calls = calls
+
+    async def on_read_resource(
+        self,
+        context: MiddlewareContext[mt.ReadResourceRequestParams],
+        call_next: CallNext[mt.ReadResourceRequestParams, ResourceResult],
+    ) -> ResourceResult:
+        self._calls.append(f"{self._name}:before")
+        result = await call_next(context)
+        self._calls.append(f"{self._name}:after")
+        return result
+
+
+class PromptTracingMiddleware(Middleware):
+    """Middleware that traces prompt gets."""
+
+    def __init__(self, name: str, calls: list[str]):
+        super().__init__()
+        self._name = name
+        self._calls = calls
+
+    async def on_get_prompt(
+        self,
+        context: MiddlewareContext[mt.GetPromptRequestParams],
+        call_next: CallNext[mt.GetPromptRequestParams, PromptResult],
+    ) -> PromptResult:
+        self._calls.append(f"{self._name}:before")
+        result = await call_next(context)
+        self._calls.append(f"{self._name}:after")
+        return result
+
+
+class TestMiddlewareWithMountedTasks:
+    """Test that middleware runs at all levels when executing background tasks.
+
+    For background tasks, middleware runs during task submission (wrapping the MCP
+    request handling that queues to Docket). The actual function execution happens
+    later in the Docket worker, after the middleware chain completes.
+    """
+
+    async def test_tool_middleware_runs_with_background_task(self):
+        """Middleware runs at parent, child, and grandchild levels for tool tasks."""
+        calls: list[str] = []
+
+        grandchild = FastMCP("Grandchild")
+
+        @grandchild.tool(task=True)
+        async def compute(x: int) -> int:
+            calls.append("grandchild:tool")
+            return x * 2
+
+        grandchild.add_middleware(ToolTracingMiddleware("grandchild", calls))
+
+        child = FastMCP("Child")
+        child.mount(grandchild, namespace="gc")
+        child.add_middleware(ToolTracingMiddleware("child", calls))
+
+        parent = FastMCP("Parent")
+        parent.mount(child, namespace="c")
+        parent.add_middleware(ToolTracingMiddleware("parent", calls))
+
+        async with Client(parent) as client:
+            task = await client.call_tool("c_gc_compute", {"x": 5}, task=True)
+            result = await task.result()
+            assert result.data == 10
+
+        # Middleware runs during task submission (before/after queuing to Docket)
+        # Function executes later in Docket worker
+        assert calls == [
+            "parent:before",
+            "child:before",
+            "grandchild:before",
+            "grandchild:after",
+            "child:after",
+            "parent:after",
+            "grandchild:tool",  # Executes in Docket after middleware completes
+        ]
+
+    @pytest.mark.xfail(
+        reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+        "ReadResourceRequestParams; prompt/resource task submission is not "
+        "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+        strict=True,
+    )
+    async def test_resource_middleware_runs_with_background_task(self):
+        """Middleware runs at parent, child, and grandchild levels for resource tasks."""
+        calls: list[str] = []
+
+        grandchild = FastMCP("Grandchild")
+
+        @grandchild.resource("data://value", task=True)
+        async def get_data() -> str:
+            calls.append("grandchild:resource")
+            return "result"
+
+        grandchild.add_middleware(ResourceTracingMiddleware("grandchild", calls))
+
+        child = FastMCP("Child")
+        child.mount(grandchild, namespace="gc")
+        child.add_middleware(ResourceTracingMiddleware("child", calls))
+
+        parent = FastMCP("Parent")
+        parent.mount(child, namespace="c")
+        parent.add_middleware(ResourceTracingMiddleware("parent", calls))
+
+        async with Client(parent) as client:
+            task = await client.read_resource("data://c/gc/value", task=True)
+            result = await task.result()
+            assert result[0].text == "result"
+
+        # Middleware runs during task submission, function in Docket
+        assert calls == [
+            "parent:before",
+            "child:before",
+            "grandchild:before",
+            "grandchild:after",
+            "child:after",
+            "parent:after",
+            "grandchild:resource",
+        ]
+
+    @pytest.mark.xfail(
+        reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+        "ReadResourceRequestParams; prompt/resource task submission is not "
+        "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+        strict=True,
+    )
+    async def test_prompt_middleware_runs_with_background_task(self):
+        """Middleware runs at parent, child, and grandchild levels for prompt tasks."""
+        calls: list[str] = []
+
+        grandchild = FastMCP("Grandchild")
+
+        @grandchild.prompt(task=True)
+        async def greet(name: str) -> str:
+            calls.append("grandchild:prompt")
+            return f"Hello, {name}!"
+
+        grandchild.add_middleware(PromptTracingMiddleware("grandchild", calls))
+
+        child = FastMCP("Child")
+        child.mount(grandchild, namespace="gc")
+        child.add_middleware(PromptTracingMiddleware("child", calls))
+
+        parent = FastMCP("Parent")
+        parent.mount(child, namespace="c")
+        parent.add_middleware(PromptTracingMiddleware("parent", calls))
+
+        async with Client(parent) as client:
+            task = await client.get_prompt("c_gc_greet", {"name": "World"}, task=True)
+            result = await task.result()
+            assert result.messages[0].content.text == "Hello, World!"
+
+        # Middleware runs during task submission, function in Docket
+        assert calls == [
+            "parent:before",
+            "child:before",
+            "grandchild:before",
+            "grandchild:after",
+            "child:after",
+            "parent:after",
+            "grandchild:prompt",
+        ]
+
+    @pytest.mark.xfail(
+        reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+        "ReadResourceRequestParams; prompt/resource task submission is not "
+        "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+        strict=True,
+    )
+    async def test_resource_template_middleware_runs_with_background_task(self):
+        """Middleware runs at all levels for resource template tasks."""
+        calls: list[str] = []
+
+        grandchild = FastMCP("Grandchild")
+
+        @grandchild.resource("item://{id}", task=True)
+        async def get_item(id: str) -> str:
+            calls.append("grandchild:template")
+            return f"item-{id}"
+
+        grandchild.add_middleware(ResourceTracingMiddleware("grandchild", calls))
+
+        child = FastMCP("Child")
+        child.mount(grandchild, namespace="gc")
+        child.add_middleware(ResourceTracingMiddleware("child", calls))
+
+        parent = FastMCP("Parent")
+        parent.mount(child, namespace="c")
+        parent.add_middleware(ResourceTracingMiddleware("parent", calls))
+
+        async with Client(parent) as client:
+            task = await client.read_resource("item://c/gc/42", task=True)
+            result = await task.result()
+            assert result[0].text == "item-42"
+
+        # Middleware runs during task submission, function in Docket
+        assert calls == [
+            "parent:before",
+            "child:before",
+            "grandchild:before",
+            "grandchild:after",
+            "child:after",
+            "parent:after",
+            "grandchild:template",
+        ]
+
+
+class TestMountedTasksWithTaskMetaParameter:
+    """Test mounted components called directly with task_meta parameter.
+
+    These tests verify the programmatic API where server.call_tool() or
+    server.read_resource() is called with an explicit task_meta parameter,
+    as opposed to using the Client with task=True.
+
+    Direct server calls require a running server context, so we use an outer
+    tool that makes the direct call internally.
+    """
+
+    async def test_mounted_tool_with_task_meta_creates_task(self):
+        """Mounted tool called with task_meta returns CreateTaskResult."""
+        from fastmcp.server.tasks.config import TaskMeta
+
+        child = FastMCP("Child")
+
+        @child.tool(task=True)
+        async def add(a: int, b: int) -> int:
+            return a + b
+
+        parent = FastMCP("Parent")
+        parent.mount(child, namespace="child")
+
+        @parent.tool
+        async def outer() -> str:
+            # Direct call with task_meta from within server context
+            result = await parent.call_tool(
+                "child_add", {"a": 2, "b": 3}, task_meta=TaskMeta(ttl=300)
+            )
+            return f"task:{result.task.task_id}"
+
+        async with Client(parent) as client:
+            result = await client.call_tool("outer", {})
+            assert "task:" in str(result)
+
+    async def test_mounted_resource_with_task_meta_creates_task(self):
+        """Mounted resource called with task_meta returns CreateTaskResult."""
+        from fastmcp.server.tasks.config import TaskMeta
+
+        child = FastMCP("Child")
+
+        @child.resource("data://info", task=True)
+        async def get_info() -> str:
+            return "child info"
+
+        parent = FastMCP("Parent")
+        parent.mount(child, namespace="child")
+
+        @parent.tool
+        async def outer() -> str:
+            result = await parent.read_resource(
+                "data://child/info", task_meta=TaskMeta(ttl=300)
+            )
+            return f"task:{result.task.task_id}"
+
+        async with Client(parent) as client:
+            result = await client.call_tool("outer", {})
+            assert "task:" in str(result)
+
+    async def test_mounted_template_with_task_meta_creates_task(self):
+        """Mounted resource template with task_meta returns CreateTaskResult."""
+        from fastmcp.server.tasks.config import TaskMeta
+
+        child = FastMCP("Child")
+
+        @child.resource("item://{id}", task=True)
+        async def get_item(id: str) -> str:
+            return f"item-{id}"
+
+        parent = FastMCP("Parent")
+        parent.mount(child, namespace="child")
+
+        @parent.tool
+        async def outer() -> str:
+            result = await parent.read_resource(
+                "item://child/42", task_meta=TaskMeta(ttl=300)
+            )
+            return f"task:{result.task.task_id}"
+
+        async with Client(parent) as client:
+            result = await client.call_tool("outer", {})
+            assert "task:" in str(result)
+
+    async def test_deeply_nested_tool_with_task_meta(self):
+        """Three-level nested tool works with task_meta."""
+        from fastmcp.server.tasks.config import TaskMeta
+
+        grandchild = FastMCP("Grandchild")
+
+        @grandchild.tool(task=True)
+        async def compute(n: int) -> int:
+            return n * 3
+
+        child = FastMCP("Child")
+        child.mount(grandchild, namespace="gc")
+
+        parent = FastMCP("Parent")
+        parent.mount(child, namespace="c")
+
+        @parent.tool
+        async def outer() -> str:
+            result = await parent.call_tool(
+                "c_gc_compute", {"n": 7}, task_meta=TaskMeta(ttl=300)
+            )
+            return f"task:{result.task.task_id}"
+
+        async with Client(parent) as client:
+            result = await client.call_tool("outer", {})
+            assert "task:" in str(result)
+
+    async def test_deeply_nested_template_with_task_meta(self):
+        """Three-level nested template works with task_meta."""
+        from fastmcp.server.tasks.config import TaskMeta
+
+        grandchild = FastMCP("Grandchild")
+
+        @grandchild.resource("doc://{name}", task=True)
+        async def get_doc(name: str) -> str:
+            return f"doc: {name}"
+
+        child = FastMCP("Child")
+        child.mount(grandchild, namespace="gc")
+
+        parent = FastMCP("Parent")
+        parent.mount(child, namespace="c")
+
+        @parent.tool
+        async def outer() -> str:
+            result = await parent.read_resource(
+                "doc://c/gc/readme", task_meta=TaskMeta(ttl=300)
+            )
+            return f"task:{result.task.task_id}"
+
+        async with Client(parent) as client:
+            result = await client.call_tool("outer", {})
+            assert "task:" in str(result)
+
+    async def test_mounted_prompt_with_task_meta_creates_task(self):
+        """Mounted prompt called with task_meta returns CreateTaskResult."""
+        from fastmcp.server.tasks.config import TaskMeta
+
+        child = FastMCP("Child")
+
+        @child.prompt(task=True)
+        async def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        parent = FastMCP("Parent")
+        parent.mount(child, namespace="child")
+
+        @parent.tool
+        async def outer() -> str:
+            result = await parent.render_prompt(
+                "child_greet", {"name": "World"}, task_meta=TaskMeta(ttl=300)
+            )
+            return f"task:{result.task.task_id}"
+
+        async with Client(parent) as client:
+            result = await client.call_tool("outer", {})
+            assert "task:" in str(result)
+
+    async def test_deeply_nested_prompt_with_task_meta(self):
+        """Three-level nested prompt works with task_meta."""
+        from fastmcp.server.tasks.config import TaskMeta
+
+        grandchild = FastMCP("Grandchild")
+
+        @grandchild.prompt(task=True)
+        async def describe(topic: str) -> str:
+            return f"Information about {topic}"
+
+        child = FastMCP("Child")
+        child.mount(grandchild, namespace="gc")
+
+        parent = FastMCP("Parent")
+        parent.mount(child, namespace="c")
+
+        @parent.tool
+        async def outer() -> str:
+            result = await parent.render_prompt(
+                "c_gc_describe", {"topic": "FastMCP"}, task_meta=TaskMeta(ttl=300)
+            )
+            return f"task:{result.task.task_id}"
+
+        async with Client(parent) as client:
+            result = await client.call_tool("outer", {})
+            assert "task:" in str(result)
diff --git a/tests/server/tasks/test_task_prompts.py b/tests/server/tasks/test_task_prompts.py
new file mode 100644
index 0000000..ca62a3a
--- /dev/null
+++ b/tests/server/tasks/test_task_prompts.py
@@ -0,0 +1,103 @@
+"""
+Tests for SEP-1686 background task support for prompts.
+
+Tests that prompts with task=True can execute in background.
+"""
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.tasks import PromptTask
+
+
+@pytest.fixture
+async def prompt_server():
+    """Create a FastMCP server with task-enabled prompts."""
+    mcp = FastMCP("prompt-test-server")
+
+    @mcp.prompt()
+    async def simple_prompt(topic: str) -> str:
+        """A simple prompt template."""
+        return f"Write about: {topic}"
+
+    @mcp.prompt(task=True)
+    async def background_prompt(topic: str, depth: str = "detailed") -> str:
+        """A prompt that can execute in background."""
+        return f"Write a {depth} analysis of: {topic}"
+
+    return mcp
+
+
+async def test_synchronous_prompt_unchanged(prompt_server):
+    """Prompts without task metadata execute synchronously as before."""
+    async with Client(prompt_server) as client:
+        # Regular call without task metadata
+        result = await client.get_prompt("simple_prompt", {"topic": "AI"})
+
+        # Should execute immediately and return result
+        assert "Write about: AI" in str(result)
+
+
+async def test_prompt_with_task_metadata_returns_immediately(prompt_server):
+    """Prompts with task metadata return immediately with PromptTask object."""
+    async with Client(prompt_server) as client:
+        # Call with task metadata
+        task = await client.get_prompt("background_prompt", {"topic": "AI"}, task=True)
+
+        # Should return a PromptTask object immediately
+        assert isinstance(task, PromptTask)
+        assert isinstance(task.task_id, str)
+        assert len(task.task_id) > 0
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_prompt_task_executes_in_background(prompt_server):
+    """Prompt task executes via Docket in background."""
+    async with Client(prompt_server) as client:
+        task = await client.get_prompt(
+            "background_prompt",
+            {"topic": "Machine Learning", "depth": "comprehensive"},
+            task=True,
+        )
+
+        # Verify background execution
+        assert not task.returned_immediately
+
+        # Get the result
+        result = await task.result()
+        assert "comprehensive" in result.messages[0].content.text.lower()
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_forbidden_mode_prompt_rejects_task_calls(prompt_server):
+    """Prompts with task=False (mode=forbidden) reject task-augmented calls."""
+    from mcp.shared.exceptions import MCPError
+    from mcp_types import METHOD_NOT_FOUND
+
+    @prompt_server.prompt(task=False)  # Explicitly disable task support
+    async def sync_only_prompt(topic: str) -> str:
+        return f"Sync prompt: {topic}"
+
+    async with Client(prompt_server) as client:
+        # Calling with task=True when task=False should raise MCPError
+        import pytest
+
+        with pytest.raises(MCPError) as exc_info:
+            await client.get_prompt("sync_only_prompt", {"topic": "test"}, task=True)
+
+        # New behavior: mode="forbidden" returns METHOD_NOT_FOUND error
+        assert exc_info.value.error.code == METHOD_NOT_FOUND
+        assert (
+            "does not support task-augmented execution" in exc_info.value.error.message
+        )
diff --git a/tests/server/tasks/test_task_protocol.py b/tests/server/tasks/test_task_protocol.py
new file mode 100644
index 0000000..9fd2fd7
--- /dev/null
+++ b/tests/server/tasks/test_task_protocol.py
@@ -0,0 +1,81 @@
+"""
+Tests for SEP-1686 protocol-level task handling.
+
+Generic protocol tests that use tools as test fixtures.
+Tests metadata, notifications, and error handling at the protocol level.
+"""
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+
+
+@pytest.fixture
+async def task_enabled_server():
+    """Create a FastMCP server with task-enabled tools."""
+    mcp = FastMCP("task-test-server")
+
+    @mcp.tool(task=True)
+    async def simple_tool(message: str) -> str:
+        """A simple tool for testing."""
+        return f"Processed: {message}"
+
+    @mcp.tool(task=True)
+    async def failing_tool() -> str:
+        """A tool that always fails."""
+        raise ValueError("This tool always fails")
+
+    return mcp
+
+
+async def test_task_metadata_includes_task_id_and_ttl(task_enabled_server):
+    """Task metadata properly includes server-generated taskId and ttl."""
+    async with Client(task_enabled_server) as client:
+        # Submit with specific ttl (server generates task ID)
+        task = await client.call_tool(
+            "simple_tool",
+            {"message": "test"},
+            task=True,
+            ttl=30000,
+        )
+        assert task
+        assert not task.returned_immediately
+
+        # Server should have generated a task ID
+        assert task.task_id is not None
+        assert isinstance(task.task_id, str)
+
+
+async def test_task_notification_sent_after_submission(task_enabled_server):
+    """Server sends an initial task status notification after submission."""
+
+    @task_enabled_server.tool(task=True)
+    async def background_tool(message: str) -> str:
+        return f"Processed: {message}"
+
+    async with Client(task_enabled_server) as client:
+        task = await client.call_tool("background_tool", {"message": "test"}, task=True)
+        assert task
+        assert not task.returned_immediately
+
+        # Verify we can query the task
+        status = await task.status()
+        assert status.task_id == task.task_id
+
+
+async def test_failed_task_stores_error(task_enabled_server):
+    """Failed tasks store the error in results."""
+
+    @task_enabled_server.tool(task=True)
+    async def failing_task_tool() -> str:
+        raise ValueError("This tool always fails")
+
+    async with Client(task_enabled_server) as client:
+        task = await client.call_tool("failing_task_tool", task=True)
+        assert task
+        assert not task.returned_immediately
+
+        # Wait for task to fail
+        status = await task.wait(state="failed", timeout=2.0)
+        assert status.status == "failed"
diff --git a/tests/server/tasks/test_task_proxy.py b/tests/server/tasks/test_task_proxy.py
new file mode 100644
index 0000000..c272a44
--- /dev/null
+++ b/tests/server/tasks/test_task_proxy.py
@@ -0,0 +1,192 @@
+"""
+Tests for MCP SEP-1686 task protocol behavior through proxy servers.
+
+Proxy servers explicitly forbid task-augmented execution. All proxy components
+(tools, prompts, resources) have task_config.mode="forbidden".
+
+Clients connecting through proxies can:
+- Execute tools/prompts/resources normally (sync execution)
+- NOT use task-augmented execution (task=True fails gracefully for tools,
+  raises MCPError for prompts/resources)
+"""
+
+import pytest
+from mcp.shared.exceptions import MCPError
+from mcp_types import TextContent, TextResourceContents
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.transports import FastMCPTransport
+from fastmcp.server import create_proxy
+
+
+@pytest.fixture
+def backend_server() -> FastMCP:
+    """Create a backend server with task-enabled components.
+
+    The backend has tasks enabled, but the proxy should NOT forward
+    task execution - it should treat all components as forbidden.
+    """
+    mcp = FastMCP("backend-server")
+
+    @mcp.tool(task=True)
+    async def add_numbers(a: int, b: int) -> int:
+        """Add two numbers together."""
+        return a + b
+
+    @mcp.tool(task=False)
+    async def sync_only_tool(message: str) -> str:
+        """Tool that only supports synchronous execution."""
+        return f"sync: {message}"
+
+    @mcp.prompt(task=True)
+    async def greeting_prompt(name: str) -> str:
+        """A prompt that can execute as a task."""
+        return f"Hello, {name}! Welcome to the system."
+
+    @mcp.resource("data://info.txt", task=True)
+    async def info_resource() -> str:
+        """A resource that can be read as a task."""
+        return "Important information from the backend"
+
+    @mcp.resource("data://user/{user_id}.json", task=True)
+    async def user_resource(user_id: str) -> str:
+        """A resource template that can execute as a task."""
+        return f'{{"id": "{user_id}", "name": "User {user_id}"}}'
+
+    return mcp
+
+
+@pytest.fixture
+def proxy_server(backend_server: FastMCP) -> FastMCP:
+    """Create a proxy server that forwards to the backend."""
+    return create_proxy(FastMCPTransport(backend_server))
+
+
+class TestProxyToolsSyncExecution:
+    """Test that tools work normally through proxy (sync execution)."""
+
+    async def test_tool_sync_execution_works(self, proxy_server: FastMCP):
+        """Tool called without task=True works through proxy."""
+        async with Client(proxy_server) as client:
+            result = await client.call_tool("add_numbers", {"a": 5, "b": 3})
+            assert "8" in str(result)
+
+    async def test_sync_only_tool_works(self, proxy_server: FastMCP):
+        """Sync-only tool works through proxy."""
+        async with Client(proxy_server) as client:
+            result = await client.call_tool("sync_only_tool", {"message": "test"})
+            assert "sync: test" in str(result)
+
+
+class TestProxyToolsTaskForbidden:
+    """Test that tools with task=True are forbidden through proxy."""
+
+    async def test_tool_task_returns_error_immediately(self, proxy_server: FastMCP):
+        """Tool called with task=True through proxy returns error immediately."""
+        async with Client(proxy_server) as client:
+            task = await client.call_tool(
+                "add_numbers", {"a": 5, "b": 3}, task=True, raise_on_error=False
+            )
+
+            # Should return immediately (forbidden behavior)
+            assert task.returned_immediately
+
+            # Result should be an error
+            result = await task.result()
+            assert result.is_error
+
+    async def test_sync_only_tool_task_returns_error_immediately(
+        self, proxy_server: FastMCP
+    ):
+        """Sync-only tool with task=True also returns error immediately."""
+        async with Client(proxy_server) as client:
+            task = await client.call_tool(
+                "sync_only_tool",
+                {"message": "test"},
+                task=True,
+                raise_on_error=False,
+            )
+
+            assert task.returned_immediately
+            result = await task.result()
+            assert result.is_error
+
+
+class TestProxyPromptsSyncExecution:
+    """Test that prompts work normally through proxy (sync execution)."""
+
+    async def test_prompt_sync_execution_works(self, proxy_server: FastMCP):
+        """Prompt called without task=True works through proxy."""
+        async with Client(proxy_server) as client:
+            result = await client.get_prompt("greeting_prompt", {"name": "Alice"})
+            assert isinstance(result.messages[0].content, TextContent)
+            assert "Hello, Alice!" in result.messages[0].content.text
+
+
+class TestProxyPromptsTaskForbidden:
+    """Test that prompts with task=True are forbidden through proxy."""
+
+    @pytest.mark.xfail(
+        reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+        "ReadResourceRequestParams; prompt/resource task submission is not "
+        "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+        strict=True,
+    )
+    async def test_prompt_task_raises_mcp_error(self, proxy_server: FastMCP):
+        """Prompt called with task=True through proxy raises MCPError."""
+        async with Client(proxy_server) as client:
+            with pytest.raises(MCPError) as exc_info:
+                await client.get_prompt("greeting_prompt", {"name": "Alice"}, task=True)
+
+            assert "does not support task-augmented execution" in str(exc_info.value)
+
+
+class TestProxyResourcesSyncExecution:
+    """Test that resources work normally through proxy (sync execution)."""
+
+    async def test_resource_sync_execution_works(self, proxy_server: FastMCP):
+        """Resource read without task=True works through proxy."""
+        async with Client(proxy_server) as client:
+            result = await client.read_resource("data://info.txt")
+            assert isinstance(result[0], TextResourceContents)
+            assert "Important information from the backend" in result[0].text
+
+    async def test_resource_template_sync_execution_works(self, proxy_server: FastMCP):
+        """Resource template without task=True works through proxy."""
+        async with Client(proxy_server) as client:
+            result = await client.read_resource("data://user/42.json")
+            assert isinstance(result[0], TextResourceContents)
+            assert '"id": "42"' in result[0].text
+
+
+class TestProxyResourcesTaskForbidden:
+    """Test that resources with task=True are forbidden through proxy."""
+
+    @pytest.mark.xfail(
+        reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+        "ReadResourceRequestParams; prompt/resource task submission is not "
+        "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+        strict=True,
+    )
+    async def test_resource_task_raises_mcp_error(self, proxy_server: FastMCP):
+        """Resource read with task=True through proxy raises MCPError."""
+        async with Client(proxy_server) as client:
+            with pytest.raises(MCPError) as exc_info:
+                await client.read_resource("data://info.txt", task=True)
+
+            assert "does not support task-augmented execution" in str(exc_info.value)
+
+    @pytest.mark.xfail(
+        reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+        "ReadResourceRequestParams; prompt/resource task submission is not "
+        "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+        strict=True,
+    )
+    async def test_resource_template_task_raises_mcp_error(self, proxy_server: FastMCP):
+        """Resource template with task=True through proxy raises MCPError."""
+        async with Client(proxy_server) as client:
+            with pytest.raises(MCPError) as exc_info:
+                await client.read_resource("data://user/42.json", task=True)
+
+            assert "does not support task-augmented execution" in str(exc_info.value)
diff --git a/tests/server/tasks/test_task_resources.py b/tests/server/tasks/test_task_resources.py
new file mode 100644
index 0000000..f7768ad
--- /dev/null
+++ b/tests/server/tasks/test_task_resources.py
@@ -0,0 +1,125 @@
+"""
+Tests for SEP-1686 background task support for resources.
+
+Tests that resources with task=True can execute in background.
+"""
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.tasks import ResourceTask
+
+
+@pytest.fixture
+async def resource_server():
+    """Create a FastMCP server with task-enabled resources."""
+    mcp = FastMCP("resource-test-server")
+
+    @mcp.resource("file://data.txt")
+    async def simple_resource() -> str:
+        """A simple resource."""
+        return "Simple content"
+
+    @mcp.resource("file://large.txt", task=True)
+    async def background_resource() -> str:
+        """A resource that can execute in background."""
+        return "Large file content that takes time to load"
+
+    @mcp.resource("file://user/{user_id}/data.json", task=True)
+    async def template_resource(user_id: str) -> str:
+        """A resource template that can execute in background."""
+        return f'{{"userId": "{user_id}", "data": "value"}}'
+
+    return mcp
+
+
+async def test_synchronous_resource_unchanged(resource_server):
+    """Resources without task metadata execute synchronously as before."""
+    async with Client(resource_server) as client:
+        # Regular call without task metadata
+        result = await client.read_resource("file://data.txt")
+
+        # Should execute immediately and return result
+        assert "Simple content" in str(result)
+
+
+async def test_resource_with_task_metadata_returns_immediately(resource_server):
+    """Resources with task metadata return immediately with ResourceTask object."""
+    async with Client(resource_server) as client:
+        # Call with task metadata
+        task = await client.read_resource("file://large.txt", task=True)
+
+        # Should return a ResourceTask object immediately
+        assert isinstance(task, ResourceTask)
+        assert isinstance(task.task_id, str)
+        assert len(task.task_id) > 0
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_resource_task_executes_in_background(resource_server):
+    """Resource task executes via Docket in background."""
+    async with Client(resource_server) as client:
+        task = await client.read_resource("file://large.txt", task=True)
+
+        # Verify background execution
+        assert not task.returned_immediately
+
+        # Get the result
+        result = await task.result()
+        assert len(result) > 0
+        assert result[0].text == "Large file content that takes time to load"
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_resource_template_with_task(resource_server):
+    """Resource templates with task=True execute in background."""
+    async with Client(resource_server) as client:
+        task = await client.read_resource("file://user/123/data.json", task=True)
+
+        # Verify background execution
+        assert not task.returned_immediately
+
+        # Get the result
+        result = await task.result()
+        assert '"userId": "123"' in result[0].text
+
+
+@pytest.mark.xfail(
+    reason="SDK v2 has no `task` field on GetPromptRequestParams / "
+    "ReadResourceRequestParams; prompt/resource task submission is not "
+    "wire-expressible and always graceful-degrades (sdk-feedback #3).",
+    strict=True,
+)
+async def test_forbidden_mode_resource_rejects_task_calls(resource_server):
+    """Resources with task=False (mode=forbidden) reject task-augmented calls."""
+    import pytest
+    from mcp.shared.exceptions import MCPError
+    from mcp_types import METHOD_NOT_FOUND
+
+    @resource_server.resource(
+        "file://sync.txt/", task=False
+    )  # Explicitly disable task support
+    async def sync_only_resource() -> str:
+        return "Sync content"
+
+    async with Client(resource_server) as client:
+        # Calling with task=True when task=False should raise MCPError
+        with pytest.raises(MCPError) as exc_info:
+            await client.read_resource("file://sync.txt", task=True)
+
+        # New behavior: mode="forbidden" returns METHOD_NOT_FOUND error
+        assert exc_info.value.error.code == METHOD_NOT_FOUND
+        assert (
+            "does not support task-augmented execution" in exc_info.value.error.message
+        )
diff --git a/tests/server/tasks/test_task_return_types.py b/tests/server/tasks/test_task_return_types.py
new file mode 100644
index 0000000..15452c7
--- /dev/null
+++ b/tests/server/tasks/test_task_return_types.py
@@ -0,0 +1,669 @@
+"""
+Tests to verify all return types work identically with task=True.
+
+These tests ensure that enabling background task support doesn't break
+existing functionality - any tool/prompt/resource should work exactly
+the same whether task=True or task=False.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+import pytest
+from pydantic import BaseModel
+from typing_extensions import TypedDict
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.utilities.types import Audio, File, Image
+
+
+class UserData(BaseModel):
+    """Example structured output."""
+
+    name: str
+    age: int
+    active: bool
+
+
+@pytest.fixture
+async def return_type_server():
+    """Server with tools that return various types."""
+    mcp = FastMCP("return-type-test")
+
+    # String return
+    @mcp.tool(task=True)
+    async def return_string() -> str:
+        return "Hello, World!"
+
+    # Integer return
+    @mcp.tool(task=True)
+    async def return_int() -> int:
+        return 42
+
+    # Float return
+    @mcp.tool(task=True)
+    async def return_float() -> float:
+        return 3.14159
+
+    # Boolean return
+    @mcp.tool(task=True)
+    async def return_bool() -> bool:
+        return True
+
+    # Dict return
+    @mcp.tool(task=True)
+    async def return_dict() -> dict[str, int]:
+        return {"count": 100, "total": 500}
+
+    # List return
+    @mcp.tool(task=True)
+    async def return_list() -> list[str]:
+        return ["apple", "banana", "cherry"]
+
+    # BaseModel return (structured output)
+    @mcp.tool(task=True)
+    async def return_model() -> UserData:
+        return UserData(name="Alice", age=30, active=True)
+
+    # None/null return
+    @mcp.tool(task=True)
+    async def return_none() -> None:
+        return None
+
+    return mcp
+
+
+@pytest.mark.parametrize(
+    "tool_name,expected_type,expected_value",
+    [
+        ("return_string", str, "Hello, World!"),
+        ("return_int", int, 42),
+        ("return_float", float, 3.14159),
+        ("return_bool", bool, True),
+        ("return_dict", dict, {"count": 100, "total": 500}),
+        ("return_list", list, ["apple", "banana", "cherry"]),
+        ("return_none", type(None), None),
+    ],
+)
+async def test_task_basic_types(
+    return_type_server: FastMCP,
+    tool_name: str,
+    expected_type: type,
+    expected_value: Any,
+):
+    """Task mode returns basic types correctly."""
+    async with Client(return_type_server) as client:
+        task = await client.call_tool(tool_name, task=True)
+        result = await task
+        assert isinstance(result.data, expected_type)
+        assert result.data == expected_value
+
+
+async def test_task_model_return(return_type_server):
+    """Task mode returns same BaseModel (as dict) as immediate mode."""
+    async with Client(return_type_server) as client:
+        task = await client.call_tool("return_model", task=True)
+        result = await task
+
+        # Client deserializes to dynamic class (type name lost with title pruning)
+        assert result.data.__class__.__name__ == "Root"
+        assert result.data.name == "Alice"
+        assert result.data.age == 30
+        assert result.data.active is True
+
+
+async def test_task_vs_immediate_equivalence(return_type_server):
+    """Verify task mode and immediate mode return identical results."""
+    async with Client(return_type_server) as client:
+        # Test a few types to verify equivalence
+        tools_to_test = ["return_string", "return_int", "return_dict"]
+
+        for tool_name in tools_to_test:
+            # Call as task
+            task = await client.call_tool(tool_name, task=True)
+            task_result = await task
+
+            # Call immediately (server should decline background execution when no task meta)
+            immediate_result = await client.call_tool(tool_name)
+
+            # Results should be identical
+            assert task_result.data == immediate_result.data, (
+                f"Mismatch for {tool_name}"
+            )
+
+
+@pytest.fixture
+async def prompt_return_server():
+    """Server with prompts that return various message structures."""
+    mcp = FastMCP("prompt-return-test")
+
+    @mcp.prompt(task=True)
+    async def single_message_prompt() -> str:
+        """Return a single string message."""
+        return "Single message content"
+
+    @mcp.prompt(task=True)
+    async def multi_message_prompt() -> list[str]:
+        """Return multiple messages."""
+        return [
+            "First message",
+            "Second message",
+            "Third message",
+        ]
+
+    return mcp
+
+
+async def test_prompt_task_single_message(prompt_return_server):
+    """Prompt task returns single message correctly."""
+    async with Client(prompt_return_server) as client:
+        task = await client.get_prompt("single_message_prompt", task=True)
+        result = await task
+
+        assert len(result.messages) == 1
+        assert result.messages[0].content.text == "Single message content"
+
+
+async def test_prompt_task_multiple_messages(prompt_return_server):
+    """Prompt task returns multiple messages correctly."""
+    async with Client(prompt_return_server) as client:
+        task = await client.get_prompt("multi_message_prompt", task=True)
+        result = await task
+
+        assert len(result.messages) == 3
+        assert result.messages[0].content.text == "First message"
+        assert result.messages[1].content.text == "Second message"
+        assert result.messages[2].content.text == "Third message"
+
+
+@pytest.fixture
+async def resource_return_server():
+    """Server with resources that return various content types."""
+    mcp = FastMCP("resource-return-test")
+
+    @mcp.resource("text://simple", task=True)
+    async def simple_text() -> str:
+        """Return simple text content."""
+        return "Simple text resource"
+
+    @mcp.resource("data://json", task=True)
+    async def json_data() -> str:
+        """Return JSON-like data."""
+        import json
+
+        return json.dumps({"key": "value", "count": 123})
+
+    return mcp
+
+
+async def test_resource_task_text_content(resource_return_server):
+    """Resource task returns text content correctly."""
+    async with Client(resource_return_server) as client:
+        task = await client.read_resource("text://simple", task=True)
+        contents = await task
+
+        assert len(contents) == 1
+        assert contents[0].text == "Simple text resource"
+
+
+async def test_resource_task_json_content(resource_return_server):
+    """Resource task returns structured content correctly."""
+    async with Client(resource_return_server) as client:
+        task = await client.read_resource("data://json", task=True)
+        contents = await task
+
+        # Content should be JSON serialized
+        assert len(contents) == 1
+        import json
+
+        data = json.loads(contents[0].text)
+        assert data == {"key": "value", "count": 123}
+
+
+# ==============================================================================
+# Binary & Special Types
+# ==============================================================================
+
+
+@pytest.fixture
+async def binary_type_server():
+    """Server with tools returning binary and special types."""
+    mcp = FastMCP("binary-test")
+
+    @mcp.tool(task=True)
+    async def return_bytes() -> bytes:
+        return b"Hello bytes!"
+
+    @mcp.tool(task=True)
+    async def return_uuid() -> UUID:
+        return UUID("12345678-1234-5678-1234-567812345678")
+
+    @mcp.tool(task=True)
+    async def return_path() -> Path:
+        return Path("/tmp/test.txt")
+
+    @mcp.tool(task=True)
+    async def return_datetime() -> datetime:
+        return datetime(2025, 11, 5, 12, 30, 45)
+
+    return mcp
+
+
+@pytest.mark.parametrize(
+    "tool_name,expected_type,assertion_fn",
+    [
+        (
+            "return_bytes",
+            type(None),
+            lambda r: (
+                r.data is None and any("Hello bytes!" in c.text for c in r.content)
+            ),
+        ),
+        (
+            "return_uuid",
+            str,
+            lambda r: r.data == "12345678-1234-5678-1234-567812345678",
+        ),
+        (
+            "return_path",
+            str,
+            lambda r: "tmp" in r.data and "test.txt" in r.data,
+        ),
+        (
+            "return_datetime",
+            datetime,
+            lambda r: r.data == datetime(2025, 11, 5, 12, 30, 45),
+        ),
+    ],
+)
+async def test_task_binary_types(
+    binary_type_server: FastMCP,
+    tool_name: str,
+    expected_type: type,
+    assertion_fn: Any,
+):
+    """Task mode handles binary and special types."""
+    async with Client(binary_type_server) as client:
+        task = await client.call_tool(tool_name, task=True)
+        result = await task
+        assert isinstance(result.data, expected_type)
+        assert assertion_fn(result)
+
+
+# ==============================================================================
+# Collection Varieties
+# ==============================================================================
+
+
+@pytest.fixture
+async def collection_server():
+    """Server with tools returning various collection types."""
+    mcp = FastMCP("collection-test")
+
+    @mcp.tool(task=True)
+    async def return_tuple() -> tuple[int, str, bool]:
+        return (42, "hello", True)
+
+    @mcp.tool(task=True)
+    async def return_set() -> set[int]:
+        return {1, 2, 3}
+
+    @mcp.tool(task=True)
+    async def return_empty_list() -> list[str]:
+        return []
+
+    @mcp.tool(task=True)
+    async def return_empty_dict() -> dict[str, Any]:
+        return {}
+
+    return mcp
+
+
+@pytest.mark.parametrize(
+    "tool_name,expected_type,expected_value",
+    [
+        ("return_tuple", list, [42, "hello", True]),
+        ("return_set", set, {1, 2, 3}),
+        ("return_empty_list", list, []),
+    ],
+)
+async def test_task_collection_types(
+    collection_server: FastMCP,
+    tool_name: str,
+    expected_type: type,
+    expected_value: Any,
+):
+    """Task mode handles collection types."""
+    async with Client(collection_server) as client:
+        task = await client.call_tool(tool_name, task=True)
+        result = await task
+        assert isinstance(result.data, expected_type)
+        assert result.data == expected_value
+
+
+async def test_task_empty_dict_return(collection_server):
+    """Task mode handles empty dict return."""
+    async with Client(collection_server) as client:
+        task = await client.call_tool("return_empty_dict", task=True)
+        result = await task
+        # Empty structured content becomes None in data
+        assert result.data is None
+        # But structured content is still {}
+        assert result.structured_content == {}
+
+
+# ==============================================================================
+# Media Types (Image, Audio, File)
+# ==============================================================================
+
+
+@pytest.fixture
+async def media_server(tmp_path):
+    """Server with tools returning media types."""
+    mcp = FastMCP("media-test")
+
+    # Create test files
+    test_image = tmp_path / "test.png"
+    test_image.write_bytes(b"\x89PNG\r\n\x1a\n" + b"fake png data")
+
+    test_audio = tmp_path / "test.mp3"
+    test_audio.write_bytes(b"ID3" + b"fake mp3 data")
+
+    test_file = tmp_path / "test.txt"
+    test_file.write_text("test file content")
+
+    @mcp.tool(task=True)
+    async def return_image_path() -> Image:
+        return Image(path=str(test_image))
+
+    @mcp.tool(task=True)
+    async def return_image_data() -> Image:
+        return Image(data=test_image.read_bytes(), format="png")
+
+    @mcp.tool(task=True)
+    async def return_audio() -> Audio:
+        return Audio(path=str(test_audio))
+
+    @mcp.tool(task=True)
+    async def return_file() -> File:
+        return File(path=str(test_file))
+
+    return mcp
+
+
+@pytest.mark.parametrize(
+    "tool_name,assertion_fn",
+    [
+        (
+            "return_image_path",
+            lambda r: len(r.content) == 1 and r.content[0].type == "image",
+        ),
+        (
+            "return_image_data",
+            lambda r: (
+                len(r.content) == 1
+                and r.content[0].type == "image"
+                and r.content[0].mime_type == "image/png"
+            ),
+        ),
+        (
+            "return_audio",
+            lambda r: len(r.content) == 1 and r.content[0].type in ["text", "audio"],
+        ),
+        (
+            "return_file",
+            lambda r: len(r.content) == 1 and r.content[0].type == "resource",
+        ),
+    ],
+)
+async def test_task_media_types(
+    media_server: FastMCP,
+    tool_name: str,
+    assertion_fn: Any,
+):
+    """Task mode handles media types (Image, Audio, File)."""
+    async with Client(media_server) as client:
+        task = await client.call_tool(tool_name, task=True)
+        result = await task
+        assert assertion_fn(result)
+
+
+# ==============================================================================
+# Structured Types (TypedDict, dataclass, unions)
+# ==============================================================================
+
+
+class PersonTypedDict(TypedDict):
+    """Example TypedDict."""
+
+    name: str
+    age: int
+
+
+@dataclass
+class PersonDataclass:
+    """Example dataclass."""
+
+    name: str
+    age: int
+
+
+@pytest.fixture
+async def structured_type_server():
+    """Server with tools returning structured types."""
+    mcp = FastMCP("structured-test")
+
+    @mcp.tool(task=True)
+    async def return_typeddict() -> PersonTypedDict:
+        return {"name": "Bob", "age": 25}
+
+    @mcp.tool(task=True)
+    async def return_dataclass() -> PersonDataclass:
+        return PersonDataclass(name="Charlie", age=35)
+
+    @mcp.tool(task=True)
+    async def return_union() -> str | int:
+        return "string value"
+
+    @mcp.tool(task=True)
+    async def return_union_int() -> str | int:
+        return 123
+
+    @mcp.tool(task=True)
+    async def return_optional() -> str | None:
+        return "has value"
+
+    @mcp.tool(task=True)
+    async def return_optional_none() -> str | None:
+        return None
+
+    return mcp
+
+
+@pytest.mark.parametrize(
+    "tool_name,expected_name,expected_age",
+    [
+        ("return_typeddict", "Bob", 25),
+        ("return_dataclass", "Charlie", 35),
+    ],
+)
+async def test_task_structured_dict_types(
+    structured_type_server: FastMCP,
+    tool_name: str,
+    expected_name: str,
+    expected_age: int,
+):
+    """Task mode handles TypedDict and dataclass returns."""
+    async with Client(structured_type_server) as client:
+        task = await client.call_tool(tool_name, task=True)
+        result = await task
+        # Both deserialize to dynamic Root class
+        assert result.data.name == expected_name
+        assert result.data.age == expected_age
+
+
+@pytest.mark.parametrize(
+    "tool_name,expected_type,expected_value",
+    [
+        ("return_union", str, "string value"),
+        ("return_union_int", int, 123),
+    ],
+)
+async def test_task_union_types(
+    structured_type_server: FastMCP,
+    tool_name: str,
+    expected_type: type,
+    expected_value: Any,
+):
+    """Task mode handles union type branches."""
+    async with Client(structured_type_server) as client:
+        task = await client.call_tool(tool_name, task=True)
+        result = await task
+        assert isinstance(result.data, expected_type)
+        assert result.data == expected_value
+
+
+@pytest.mark.parametrize(
+    "tool_name,expected_type,expected_value",
+    [
+        ("return_optional", str, "has value"),
+        ("return_optional_none", type(None), None),
+    ],
+)
+async def test_task_optional_types(
+    structured_type_server: FastMCP,
+    tool_name: str,
+    expected_type: type,
+    expected_value: Any,
+):
+    """Task mode handles Optional types."""
+    async with Client(structured_type_server) as client:
+        task = await client.call_tool(tool_name, task=True)
+        result = await task
+        assert isinstance(result.data, expected_type)
+        assert result.data == expected_value
+
+
+# ==============================================================================
+# MCP Content Blocks
+# ==============================================================================
+
+
+@pytest.fixture
+async def mcp_content_server(tmp_path):
+    """Server with tools returning MCP content blocks."""
+    import base64
+
+    from mcp_types import (
+        EmbeddedResource,
+        ImageContent,
+        ResourceLink,
+        TextContent,
+        TextResourceContents,
+    )
+
+    mcp = FastMCP("content-test")
+
+    test_image = tmp_path / "content.png"
+    test_image.write_bytes(b"\x89PNG\r\n\x1a\n" + b"content")
+
+    @mcp.tool(task=True)
+    async def return_text_content() -> TextContent:
+        return TextContent(type="text", text="Direct text content")
+
+    @mcp.tool(task=True)
+    async def return_image_content() -> ImageContent:
+        return ImageContent(
+            type="image",
+            data=base64.b64encode(test_image.read_bytes()).decode(),
+            mime_type="image/png",
+        )
+
+    @mcp.tool(task=True)
+    async def return_embedded_resource() -> EmbeddedResource:
+        return EmbeddedResource(
+            type="resource",
+            resource=TextResourceContents(uri="test://resource", text="embedded"),
+        )
+
+    @mcp.tool(task=True)
+    async def return_resource_link() -> ResourceLink:
+        return ResourceLink(
+            type="resource_link", uri="test://linked", name="Test Resource"
+        )
+
+    @mcp.tool(task=True)
+    async def return_mixed_content() -> list[TextContent | ImageContent]:
+        return [
+            TextContent(type="text", text="First block"),
+            ImageContent(
+                type="image",
+                data=base64.b64encode(test_image.read_bytes()).decode(),
+                mime_type="image/png",
+            ),
+            TextContent(type="text", text="Third block"),
+        ]
+
+    return mcp
+
+
+@pytest.mark.parametrize(
+    "tool_name,assertion_fn",
+    [
+        (
+            "return_text_content",
+            lambda r: (
+                len(r.content) == 1
+                and r.content[0].type == "text"
+                and r.content[0].text == "Direct text content"
+            ),
+        ),
+        (
+            "return_image_content",
+            lambda r: (
+                len(r.content) == 1
+                and r.content[0].type == "image"
+                and r.content[0].mime_type == "image/png"
+            ),
+        ),
+        (
+            "return_embedded_resource",
+            lambda r: len(r.content) == 1 and r.content[0].type == "resource",
+        ),
+        (
+            "return_resource_link",
+            lambda r: (
+                len(r.content) == 1
+                and r.content[0].type == "resource_link"
+                and str(r.content[0].uri) == "test://linked"
+            ),
+        ),
+    ],
+)
+async def test_task_mcp_content_types(
+    mcp_content_server: FastMCP,
+    tool_name: str,
+    assertion_fn: Any,
+):
+    """Task mode handles MCP content block types."""
+    async with Client(mcp_content_server) as client:
+        task = await client.call_tool(tool_name, task=True)
+        result = await task
+        assert assertion_fn(result)
+
+
+async def test_task_mixed_content_return(mcp_content_server):
+    """Task mode handles mixed content list return."""
+    async with Client(mcp_content_server) as client:
+        task = await client.call_tool("return_mixed_content", task=True)
+        result = await task
+        assert len(result.content) == 3
+        assert result.content[0].type == "text"
+        assert result.content[0].text == "First block"
+        assert result.content[1].type == "image"
+        assert result.content[2].type == "text"
+        assert result.content[2].text == "Third block"
diff --git a/tests/server/tasks/test_task_security.py b/tests/server/tasks/test_task_security.py
new file mode 100644
index 0000000..5d3b16f
--- /dev/null
+++ b/tests/server/tasks/test_task_security.py
@@ -0,0 +1,149 @@
+"""
+Tests for authorization-based task isolation (CRITICAL SECURITY).
+
+Ensures that tasks are properly scoped to authorization identity and clients
+cannot access each other's tasks.
+"""
+
+import pytest
+from mcp.server.auth.middleware.auth_context import (
+    auth_context_var,
+)
+from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.auth import AccessToken
+
+
+@pytest.fixture
+def task_server():
+    """Create a server with background tasks enabled."""
+    mcp = FastMCP("security-test-server")
+
+    @mcp.tool(task=True)
+    async def secret_tool(data: str) -> str:
+        """A tool that processes sensitive data."""
+        return f"Secret result: {data}"
+
+    return mcp
+
+
+async def test_same_client_can_access_all_its_tasks(task_server: FastMCP):
+    """A single authenticated client can access all tasks it created."""
+    token = AccessToken(
+        token="token-a",
+        client_id="client-a",
+        scopes=["read"],
+    )
+    reset = auth_context_var.set(AuthenticatedUser(token))
+    try:
+        async with Client(task_server) as client:
+            task1 = await client.call_tool(
+                "secret_tool", {"data": "first"}, task=True, task_id="task-1"
+            )
+            task2 = await client.call_tool(
+                "secret_tool", {"data": "second"}, task=True, task_id="task-2"
+            )
+
+            await task1.wait(timeout=2.0)
+            await task2.wait(timeout=2.0)
+
+            result1 = await task1.result()
+            result2 = await task2.result()
+
+            assert "first" in str(result1.data)
+            assert "second" in str(result2.data)
+    finally:
+        auth_context_var.reset(reset)
+
+
+async def test_unauthenticated_client_can_access_its_tasks(task_server: FastMCP):
+    """An unauthenticated client can access tasks it created (by task ID)."""
+    async with Client(task_server) as client:
+        task = await client.call_tool(
+            "secret_tool", {"data": "hello"}, task=True, task_id="my-task"
+        )
+        await task.wait(timeout=2.0)
+        result = await task.result()
+        assert "hello" in str(result.data)
+
+
+def _set_auth(client_id: str, sub: str | None = None):
+    """Install an auth context for a given client_id/sub. Returns the reset token."""
+    claims = {"sub": sub} if sub else {}
+    token = AccessToken(
+        token=f"token-{client_id}-{sub or ''}",
+        client_id=client_id,
+        scopes=["read"],
+        claims=claims,
+    )
+    return auth_context_var.set(AuthenticatedUser(token))
+
+
+async def _submit_task_id(client: Client, data: str) -> str:
+    """Submit a background task and return its server-assigned task id."""
+    task = await client.call_tool("secret_tool", {"data": data}, task=True)
+    await task.wait(timeout=2.0)
+    return task.task_id
+
+
+async def test_distinct_clients_cannot_access_each_others_tasks(
+    task_server: FastMCP,
+):
+    """Two distinct authenticated clients live in disjoint scopes — looking up
+    a peer's task id returns 'not found'."""
+    reset = _set_auth("client-a")
+    try:
+        async with Client(task_server) as client_a:
+            task_id = await _submit_task_id(client_a, "client-a-secret")
+    finally:
+        auth_context_var.reset(reset)
+
+    reset = _set_auth("client-b")
+    try:
+        async with Client(task_server) as client_b:
+            with pytest.raises(Exception, match="not found"):
+                await client_b.get_task_status(task_id)
+    finally:
+        auth_context_var.reset(reset)
+
+
+async def test_distinct_subs_same_client_id_cannot_access_each_others_tasks(
+    task_server: FastMCP,
+):
+    """Fixed-OAuth case: two users share a client_id but have distinct ``sub``
+    claims.  The ``sub``-aware scope must still isolate them."""
+    shared_client = "shared-oauth-app"
+
+    reset = _set_auth(shared_client, sub="user-alice")
+    try:
+        async with Client(task_server) as alice:
+            task_id = await _submit_task_id(alice, "alice-secret")
+    finally:
+        auth_context_var.reset(reset)
+
+    reset = _set_auth(shared_client, sub="user-bob")
+    try:
+        async with Client(task_server) as bob:
+            with pytest.raises(Exception, match="not found"):
+                await bob.get_task_status(task_id)
+    finally:
+        auth_context_var.reset(reset)
+
+
+async def test_authenticated_and_anonymous_keyspaces_are_disjoint(
+    task_server: FastMCP,
+):
+    """An anonymous client must not be able to read an authenticated client's
+    tasks (and vice versa) even when colliding on task id."""
+    reset = _set_auth("client-a")
+    try:
+        async with Client(task_server) as authed:
+            authed_task_id = await _submit_task_id(authed, "authed-secret")
+    finally:
+        auth_context_var.reset(reset)
+
+    async with Client(task_server) as anon:
+        with pytest.raises(Exception, match="not found"):
+            await anon.get_task_status(authed_task_id)
diff --git a/tests/server/tasks/test_task_status_notifications.py b/tests/server/tasks/test_task_status_notifications.py
new file mode 100644
index 0000000..98d333c
--- /dev/null
+++ b/tests/server/tasks/test_task_status_notifications.py
@@ -0,0 +1,160 @@
+"""
+Tests for notifications/tasks/status subscription mechanism (SEP-1686 lines 436-444).
+
+Per the spec, servers MAY send notifications/tasks/status when task state changes.
+This is an optional optimization that reduces client polling frequency.
+
+These tests verify that the subscription mechanism works correctly without breaking
+existing functionality. Notification delivery is best-effort and clients MUST NOT
+rely on receiving them.
+"""
+
+import asyncio
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+
+
+@pytest.fixture
+async def notification_server():
+    """Create a server for testing task status notifications."""
+    mcp = FastMCP("notification-test")
+
+    @mcp.tool(task=True)
+    async def quick_task(value: int) -> int:
+        """Quick task that completes immediately."""
+        return value * 2
+
+    @mcp.tool(task=True)
+    async def slow_task(duration: float = 0.1) -> str:
+        """Slow task for testing working status."""
+        await asyncio.sleep(duration)
+        return "completed"
+
+    @mcp.tool(task=True)
+    async def failing_task() -> str:
+        """Task that always fails."""
+        raise ValueError("Task failed intentionally")
+
+    @mcp.prompt(task=True)
+    async def test_prompt(name: str) -> str:
+        """Test prompt for background execution."""
+        await asyncio.sleep(0.05)
+        return f"Hello, {name}!"
+
+    @mcp.resource("test://resource", task=True)
+    async def test_resource() -> str:
+        """Test resource for background execution."""
+        await asyncio.sleep(0.05)
+        return "resource content"
+
+    return mcp
+
+
+async def test_subscription_spawned_for_tool_task(notification_server: FastMCP):
+    """Subscription task is spawned when tool task is created."""
+    async with Client(notification_server) as client:
+        # Create task - should spawn subscription
+        task = await client.call_tool("quick_task", {"value": 5}, task=True)
+
+        # Task should complete normally
+        result = await task
+        assert result.data == 10
+
+        # Subscription should clean up automatically
+        # (No way to directly test, but shouldn't cause issues)
+
+
+async def test_subscription_handles_task_completion(notification_server: FastMCP):
+    """Subscription properly handles task completion and cleanup."""
+    async with Client(notification_server) as client:
+        # Multiple tasks should each get their own subscription
+        task1 = await client.call_tool("quick_task", {"value": 1}, task=True)
+        task2 = await client.call_tool("quick_task", {"value": 2}, task=True)
+        task3 = await client.call_tool("quick_task", {"value": 3}, task=True)
+
+        # All should complete successfully
+        result1 = await task1
+        result2 = await task2
+        result3 = await task3
+
+        assert result1.data == 2
+        assert result2.data == 4
+        assert result3.data == 6
+
+        # Subscriptions should all clean up
+        # Give them a moment
+        await asyncio.sleep(0.1)
+
+
+async def test_subscription_handles_task_failure(notification_server: FastMCP):
+    """Subscription properly handles task failure."""
+    async with Client(notification_server) as client:
+        task = await client.call_tool("failing_task", {}, task=True)
+
+        # Task should fail
+        with pytest.raises(Exception):
+            await task
+
+        # Subscription should handle failure and clean up
+        await asyncio.sleep(0.1)
+
+
+async def test_subscription_for_prompt_tasks(notification_server: FastMCP):
+    """Subscriptions work for prompt tasks."""
+    async with Client(notification_server) as client:
+        task = await client.get_prompt("test_prompt", {"name": "World"}, task=True)
+
+        result = await task
+        # Prompt result has messages
+        assert result
+
+        # Subscription should clean up
+        await asyncio.sleep(0.1)
+
+
+async def test_subscription_for_resource_tasks(notification_server: FastMCP):
+    """Subscriptions work for resource tasks."""
+    async with Client(notification_server) as client:
+        task = await client.read_resource("test://resource", task=True)
+
+        result = await task
+        assert result  # Resource contents
+
+        # Subscription should clean up
+        await asyncio.sleep(0.1)
+
+
+async def test_subscriptions_cleanup_on_session_disconnect(
+    notification_server: FastMCP,
+):
+    """Subscriptions are cleaned up when session disconnects."""
+    # Start session and create task
+    async with Client(notification_server) as client:
+        task = await client.call_tool("slow_task", {"duration": 1.0}, task=True)
+        task_id = task.task_id
+        # Disconnect before task completes (session __aexit__ cancels subscriptions)
+
+    # Session is now closed, subscription should be cancelled
+    # Task continues in Docket but notification subscription is gone
+    # This test passing means no crash occurred during cleanup
+    assert task_id  # Task was created
+
+
+async def test_multiple_concurrent_subscriptions(notification_server: FastMCP):
+    """Multiple concurrent tasks each have their own subscription."""
+    async with Client(notification_server) as client:
+        # Start many tasks concurrently
+        tasks = []
+        for i in range(10):
+            task = await client.call_tool("quick_task", {"value": i}, task=True)
+            tasks.append(task)
+
+        # All should complete
+        results = await asyncio.gather(*tasks)
+        assert len(results) == 10
+
+        # All subscriptions should clean up
+        await asyncio.sleep(0.1)
diff --git a/tests/server/tasks/test_task_tools.py b/tests/server/tasks/test_task_tools.py
new file mode 100644
index 0000000..1515504
--- /dev/null
+++ b/tests/server/tasks/test_task_tools.py
@@ -0,0 +1,243 @@
+"""
+Tests for server-side tool task behavior.
+
+Tests tool-specific task handling, parallel to test_task_prompts.py
+and test_task_resources.py.
+"""
+
+import asyncio
+import functools
+
+import mcp_types
+import pytest
+from pydantic import BaseModel
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.messages import MessageHandler
+from fastmcp.client.tasks import ToolTask
+from fastmcp.exceptions import ToolError
+from fastmcp.tools.function_tool import _resolve_param_hints
+
+
+@pytest.fixture
+async def tool_server():
+    """Create a FastMCP server with task-enabled tools."""
+    mcp = FastMCP("tool-task-server")
+
+    @mcp.tool(task=True)
+    async def simple_tool(message: str) -> str:
+        """A simple tool for testing."""
+        return f"Processed: {message}"
+
+    @mcp.tool(task=False)
+    async def sync_only_tool(message: str) -> str:
+        """Tool with task=False."""
+        return f"Sync: {message}"
+
+    return mcp
+
+
+class _Item(BaseModel):
+    value: str
+
+
+async def test_task_tool_validates_model_arguments():
+    """Model-typed args are coerced to model instances for task calls (#4349).
+
+    The synchronous path validates arguments through the function's
+    TypeAdapter, so a parameter typed as a Pydantic model arrives as a model
+    instance. The task path must coerce the same way rather than passing the
+    raw dict through to the function.
+    """
+    mcp = FastMCP("tool-task-validation-server")
+
+    @mcp.tool(task=True)
+    async def inspect_items(item: _Item, items: list[_Item]) -> dict[str, str]:
+        return {"item": type(item).__name__, "element": type(items[0]).__name__}
+
+    arguments = {"item": {"value": "a"}, "items": [{"value": "b"}]}
+    expected = {"item": "_Item", "element": "_Item"}
+
+    async with Client(mcp) as client:
+        sync_result = await client.call_tool("inspect_items", arguments)
+        task = await client.call_tool("inspect_items", arguments, task=True)
+        task_result = await task.result()
+
+    assert sync_result.data == expected
+    assert task_result.data == expected
+
+
+async def test_task_tool_invalid_arguments_fail_before_task_state():
+    """Invalid task arguments are rejected before any task state is created.
+
+    Coercion runs up front in submit_to_docket, so a validation failure surfaces
+    before the task's Redis metadata and initial "working" status notification
+    are written. Otherwise an invalid input would orphan a task the client had
+    already observed via that notification.
+    """
+
+    class _Recorder(MessageHandler):
+        def __init__(self):
+            super().__init__()
+            self.methods: list[str] = []
+
+        async def on_notification(self, message: mcp_types.ServerNotification) -> None:
+            self.methods.append(message.method)
+
+    server = FastMCP("tool-task-invalid-args-server")
+
+    @server.tool(task=True)
+    async def needs_item(item: _Item) -> str:
+        return item.value
+
+    recorder = _Recorder()
+    async with Client(server, message_handler=recorder) as client:
+        # `item` is missing its required `value` field.
+        task = await client.call_tool("needs_item", {"item": {}}, task=True)
+        assert task.returned_immediately
+        with pytest.raises(ToolError):
+            await task.result()
+
+    assert "notifications/tasks/status" not in recorder.methods
+
+
+async def test_task_submission_honors_strict_input_validation():
+    """Strict input validation applies to task submissions, not just sync calls.
+
+    With ``strict_input_validation=True``, a lax coercion like ``{"n": "1"}``
+    for an ``int`` parameter is rejected on the synchronous path. The task
+    submission path must reject it identically rather than silently coercing
+    and queueing it — otherwise ``task=True`` would bypass the strict flag.
+    """
+
+    class _Recorder(MessageHandler):
+        def __init__(self):
+            super().__init__()
+            self.methods: list[str] = []
+
+        async def on_notification(self, message: mcp_types.ServerNotification) -> None:
+            self.methods.append(message.method)
+
+    server = FastMCP("strict-task-server", strict_input_validation=True)
+
+    @server.tool(task=True)
+    async def square(n: int) -> int:
+        return n * n
+
+    recorder = _Recorder()
+    async with Client(server, message_handler=recorder) as client:
+        # Sync path rejects the string-for-int coercion under strict validation.
+        with pytest.raises(ToolError):
+            await client.call_tool("square", {"n": "1"})
+
+        # Task path must reject it too, before any task state is created — so no
+        # status notification is emitted for the orphaned submission.
+        task = await client.call_tool("square", {"n": "1"}, task=True)
+        assert task.returned_immediately
+        with pytest.raises(ToolError):
+            await task.result()
+
+    assert "notifications/tasks/status" not in recorder.methods
+
+
+async def test_task_submission_valid_argument_under_strict_validation():
+    """A well-typed argument still submits fine when strict validation is on."""
+    server = FastMCP("strict-task-valid-server", strict_input_validation=True)
+
+    @server.tool(task=True)
+    async def square(n: int) -> int:
+        return n * n
+
+    async with Client(server) as client:
+        task = await client.call_tool("square", {"n": 4}, task=True)
+        assert not task.returned_immediately
+        result = await task.result()
+        assert result.data == 16
+
+
+def test_resolve_param_hints_handles_partials():
+    """Partials aren't introspectable by get_type_hints; resolve via the func.
+
+    Argument coercion must not raise for partial-wrapped callables — it should
+    resolve hints for the still-unbound parameters.
+    """
+
+    async def base(prefix: str, items: list[_Item]) -> str:
+        return prefix
+
+    partial_fn = functools.partial(base, "bound")
+    hints = _resolve_param_hints(partial_fn)
+
+    assert hints["items"] == list[_Item]
+
+
+async def test_synchronous_tool_call_unchanged(tool_server):
+    """Tools without task metadata execute synchronously as before."""
+    async with Client(tool_server) as client:
+        # Regular call without task metadata
+        result = await client.call_tool("simple_tool", {"message": "hello"})
+
+        # Should execute immediately and return result
+        assert "Processed: hello" in str(result)
+
+
+async def test_tool_with_task_metadata_returns_immediately(tool_server):
+    """Tools with task metadata return immediately with ToolTask object."""
+    async with Client(tool_server) as client:
+        # Call with task metadata
+        task = await client.call_tool("simple_tool", {"message": "test"}, task=True)
+        assert task
+        assert not task.returned_immediately
+
+        assert isinstance(task, ToolTask)
+        assert isinstance(task.task_id, str)
+        assert len(task.task_id) > 0
+
+
+async def test_tool_task_executes_in_background(tool_server):
+    """Tool task is submitted to Docket and executes in background."""
+    execution_started = asyncio.Event()
+    execution_completed = asyncio.Event()
+
+    @tool_server.tool(task=True)
+    async def coordinated_tool() -> str:
+        """Tool with coordination points."""
+        execution_started.set()
+        await execution_completed.wait()
+        return "completed"
+
+    async with Client(tool_server) as client:
+        task = await client.call_tool("coordinated_tool", task=True)
+        assert task
+        assert not task.returned_immediately
+
+        # Wait for execution to start
+        await asyncio.wait_for(execution_started.wait(), timeout=2.0)
+
+        # Task should still be working
+        status = await task.status()
+        assert status.status in ["working"]
+
+        # Signal completion
+        execution_completed.set()
+        await task.wait(timeout=2.0)
+
+        result = await task.result()
+        assert result.data == "completed"
+
+
+async def test_forbidden_mode_tool_rejects_task_calls(tool_server):
+    """Tools with task=False (mode=forbidden) reject task-augmented calls."""
+    async with Client(tool_server) as client:
+        # Calling with task=True when task=False should return error
+        task = await client.call_tool(
+            "sync_only_tool", {"message": "test"}, task=True, raise_on_error=False
+        )
+        assert task
+        assert task.returned_immediately
+
+        result = await task.result()
+        # New behavior: mode="forbidden" returns an error
+        assert result.is_error
+        assert "does not support task-augmented execution" in str(result)
diff --git a/tests/server/tasks/test_task_ttl.py b/tests/server/tasks/test_task_ttl.py
new file mode 100644
index 0000000..769faff
--- /dev/null
+++ b/tests/server/tasks/test_task_ttl.py
@@ -0,0 +1,87 @@
+"""
+Tests for SEP-1686 ttl parameter handling.
+
+Per the spec, servers MUST return ttl in all tasks/get responses,
+and results should be retained for ttl milliseconds after completion.
+"""
+
+import asyncio
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+
+
+@pytest.fixture
+async def keepalive_server():
+    """Create a server for testing ttl behavior."""
+    mcp = FastMCP("keepalive-test")
+
+    @mcp.tool(task=True)
+    async def quick_task(value: int) -> int:
+        return value * 2
+
+    @mcp.tool(task=True)
+    async def slow_task() -> str:
+        await asyncio.sleep(1)
+        return "done"
+
+    return mcp
+
+
+async def test_keepalive_returned_in_submitted_state(keepalive_server: FastMCP):
+    """ttl is returned in tasks/get even when task is submitted/working."""
+    async with Client(keepalive_server) as client:
+        # Submit task with explicit ttl
+        task = await client.call_tool(
+            "slow_task",
+            {},
+            task=True,
+            ttl=30000,  # 30 seconds (client-requested)
+        )
+
+        # Check status immediately - should be submitted or working
+        status = await task.status()
+        assert status.status in ["working"]
+
+        # ttl should be present per spec (MUST return in all responses)
+        # TODO: Docket uses a global execution_ttl for all tasks, not per-task TTLs.
+        # The spec allows servers to override client-requested TTL (line 431).
+        # FastMCP returns the server's actual global TTL (60000ms default from Docket).
+        # If Docket gains per-task TTL support, update this to verify client-requested TTL is respected.
+        assert status.ttl == 60000  # Server's global TTL, not client-requested 30000
+
+
+async def test_keepalive_returned_in_completed_state(keepalive_server: FastMCP):
+    """ttl is returned in tasks/get after task completes."""
+    async with Client(keepalive_server) as client:
+        # Submit and complete task
+        task = await client.call_tool(
+            "quick_task",
+            {"value": 5},
+            task=True,
+            ttl=45000,  # Client-requested TTL
+        )
+        await task.wait(timeout=2.0)
+
+        # Check status - should be completed
+        status = await task.status()
+        assert status.status == "completed"
+
+        # TODO: Docket uses global execution_ttl, not per-task TTLs.
+        # Server returns its global TTL (60000ms), not the client-requested 45000ms.
+        # This is spec-compliant - servers MAY override requested TTL (spec line 431).
+        assert status.ttl == 60000  # Server's global TTL, not client-requested 45000
+
+
+async def test_default_keepalive_when_not_specified(keepalive_server: FastMCP):
+    """Default ttl is used when client doesn't specify."""
+    async with Client(keepalive_server) as client:
+        # Submit without explicit ttl
+        task = await client.call_tool("quick_task", {"value": 3}, task=True)
+        await task.wait(timeout=2.0)
+
+        status = await task.status()
+        # Should have default ttl (60000ms = 60 seconds)
+        assert status.ttl == 60000
diff --git a/tests/server/telemetry/__init__.py b/tests/server/telemetry/__init__.py
new file mode 100644
index 0000000..bdcf541
--- /dev/null
+++ b/tests/server/telemetry/__init__.py
@@ -0,0 +1 @@
+"""Tests for FastMCP server telemetry."""
diff --git a/tests/server/telemetry/test_delegate_method.py b/tests/server/telemetry/test_delegate_method.py
new file mode 100644
index 0000000..8722775
--- /dev/null
+++ b/tests/server/telemetry/test_delegate_method.py
@@ -0,0 +1,80 @@
+"""Tests for mcp.method.name attribute on delegate spans."""
+
+from __future__ import annotations
+
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+from fastmcp import FastMCP
+
+
+class TestDelegateSpanMethod:
+    """Tests that delegate spans include mcp.method.name."""
+
+    async def test_mounted_tool_delegate_has_method(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        child = FastMCP("child-server")
+
+        @child.tool()
+        def child_tool() -> str:
+            return "result"
+
+        parent = FastMCP("parent-server")
+        parent.mount(child, namespace="child")
+
+        await parent.call_tool("child_child_tool", {})
+
+        spans = trace_exporter.get_finished_spans()
+        delegate_span = next(
+            (s for s in spans if s.name == "delegate child_tool"), None
+        )
+        assert delegate_span is not None
+        assert delegate_span.attributes is not None
+        assert delegate_span.attributes["mcp.method.name"] == "tools/call"
+
+    async def test_mounted_resource_delegate_has_method(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        child = FastMCP("child-server")
+
+        @child.resource("data://config")
+        def child_config() -> str:
+            return "config data"
+
+        parent = FastMCP("parent-server")
+        parent.mount(child, namespace="child")
+
+        await parent.read_resource("data://child/config")
+
+        spans = trace_exporter.get_finished_spans()
+        delegate_spans = [
+            s
+            for s in spans
+            if s.name.startswith("delegate") and "data://config" in s.name
+        ]
+        assert len(delegate_spans) >= 1
+        span = delegate_spans[0]
+        assert span.attributes is not None
+        assert span.attributes["mcp.method.name"] == "resources/read"
+
+    async def test_mounted_prompt_delegate_has_method(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        child = FastMCP("child-server")
+
+        @child.prompt()
+        def child_prompt() -> str:
+            return "Hello from child!"
+
+        parent = FastMCP("parent-server")
+        parent.mount(child, namespace="child")
+
+        await parent.render_prompt("child_child_prompt", {})
+
+        spans = trace_exporter.get_finished_spans()
+        delegate_span = next(
+            (s for s in spans if s.name == "delegate child_prompt"), None
+        )
+        assert delegate_span is not None
+        assert delegate_span.attributes is not None
+        assert delegate_span.attributes["mcp.method.name"] == "prompts/get"
diff --git a/tests/server/telemetry/test_list_tracing.py b/tests/server/telemetry/test_list_tracing.py
new file mode 100644
index 0000000..92ff4f7
--- /dev/null
+++ b/tests/server/telemetry/test_list_tracing.py
@@ -0,0 +1,130 @@
+"""Tests for server-level OpenTelemetry tracing on list operations."""
+
+from __future__ import annotations
+
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+from opentelemetry.trace import SpanKind
+
+from fastmcp import FastMCP
+
+
+class TestListToolsTracing:
+    async def test_list_tools_creates_span(self, trace_exporter: InMemorySpanExporter):
+        mcp = FastMCP("test-server")
+
+        @mcp.tool()
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+
+        spans = trace_exporter.get_finished_spans()
+        list_spans = [s for s in spans if s.name == "tools/list"]
+        assert len(list_spans) >= 1
+
+        span = list_spans[0]
+        assert span.kind == SpanKind.SERVER
+        assert span.attributes is not None
+        assert span.attributes["mcp.method.name"] == "tools/list"
+        assert span.attributes["fastmcp.server.name"] == "test-server"
+        assert span.attributes["fastmcp.component.type"] == "tool"
+
+    async def test_list_tools_empty_creates_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 0
+
+        spans = trace_exporter.get_finished_spans()
+        list_spans = [s for s in spans if s.name == "tools/list"]
+        assert len(list_spans) >= 1
+
+
+class TestListResourcesTracing:
+    async def test_list_resources_creates_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        @mcp.resource("config://app")
+        def get_config() -> str:
+            return "config"
+
+        resources = await mcp.list_resources()
+        assert len(resources) >= 1
+
+        spans = trace_exporter.get_finished_spans()
+        list_spans = [s for s in spans if s.name == "resources/list"]
+        assert len(list_spans) >= 1
+
+        span = list_spans[0]
+        assert span.kind == SpanKind.SERVER
+        assert span.attributes is not None
+        assert span.attributes["mcp.method.name"] == "resources/list"
+        assert span.attributes["fastmcp.server.name"] == "test-server"
+        assert span.attributes["fastmcp.component.type"] == "resource"
+
+
+class TestListResourceTemplatesTracing:
+    async def test_list_resource_templates_creates_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        @mcp.resource("users://{user_id}/profile")
+        def get_profile(user_id: str) -> str:
+            return f"profile {user_id}"
+
+        templates = await mcp.list_resource_templates()
+        assert len(templates) >= 1
+
+        spans = trace_exporter.get_finished_spans()
+        list_spans = [s for s in spans if s.name == "resources/templates/list"]
+        assert len(list_spans) >= 1
+
+        span = list_spans[0]
+        assert span.kind == SpanKind.SERVER
+        assert span.attributes is not None
+        assert span.attributes["mcp.method.name"] == "resources/templates/list"
+        assert span.attributes["fastmcp.server.name"] == "test-server"
+        assert span.attributes["fastmcp.component.type"] == "resource_template"
+
+
+class TestListPromptsTracing:
+    async def test_list_prompts_creates_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        @mcp.prompt()
+        def greeting(name: str) -> str:
+            return f"Hello, {name}!"
+
+        prompts = await mcp.list_prompts()
+        assert len(prompts) == 1
+
+        spans = trace_exporter.get_finished_spans()
+        list_spans = [s for s in spans if s.name == "prompts/list"]
+        assert len(list_spans) >= 1
+
+        span = list_spans[0]
+        assert span.kind == SpanKind.SERVER
+        assert span.attributes is not None
+        assert span.attributes["mcp.method.name"] == "prompts/list"
+        assert span.attributes["fastmcp.server.name"] == "test-server"
+        assert span.attributes["fastmcp.component.type"] == "prompt"
+
+    async def test_list_prompts_empty_creates_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        prompts = await mcp.list_prompts()
+        assert len(prompts) == 0
+
+        spans = trace_exporter.get_finished_spans()
+        list_spans = [s for s in spans if s.name == "prompts/list"]
+        assert len(list_spans) >= 1
diff --git a/tests/server/telemetry/test_provider_tracing.py b/tests/server/telemetry/test_provider_tracing.py
new file mode 100644
index 0000000..7118044
--- /dev/null
+++ b/tests/server/telemetry/test_provider_tracing.py
@@ -0,0 +1,133 @@
+"""Tests for provider-level OpenTelemetry tracing."""
+
+from __future__ import annotations
+
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+from fastmcp import FastMCP
+
+
+class TestFastMCPProviderTracing:
+    """Tests for FastMCPProvider delegation tracing."""
+
+    async def test_mounted_tool_creates_delegate_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        # Create a child server with a tool
+        child = FastMCP("child-server")
+
+        @child.tool()
+        def child_tool() -> str:
+            return "child result"
+
+        # Create parent server and mount child with namespace
+        parent = FastMCP("parent-server")
+        parent.mount(child, namespace="child")
+
+        # Call the tool through the parent (namespace uses underscore, not slash)
+        result = await parent.call_tool("child_child_tool", {})
+        assert "child result" in str(result)
+
+        # Check spans: should have parent tool span, delegate span, and child tool span
+        spans = trace_exporter.get_finished_spans()
+        span_names = [s.name for s in spans]
+
+        # Parent server creates "tools/call child_child_tool"
+        assert "tools/call child_child_tool" in span_names
+        # FastMCPProvider creates "delegate child_tool"
+        assert "delegate child_tool" in span_names
+        # Child server creates "tools/call child_tool"
+        assert "tools/call child_tool" in span_names
+
+        # Verify delegate span has correct attributes
+        delegate_span = next(s for s in spans if s.name == "delegate child_tool")
+        assert delegate_span.attributes is not None
+        assert delegate_span.attributes["fastmcp.provider.type"] == "FastMCPProvider"
+        assert delegate_span.attributes["fastmcp.component.key"] == "child_tool"
+
+    async def test_mounted_resource_creates_delegate_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        # Create a child server with a resource
+        child = FastMCP("child-server")
+
+        @child.resource("data://config")
+        def child_config() -> str:
+            return "config data"
+
+        # Create parent server and mount child with namespace
+        parent = FastMCP("parent-server")
+        parent.mount(child, namespace="child")
+
+        # Read the resource through the parent (namespace is in the URI path)
+        result = await parent.read_resource("data://child/config")
+        assert "config data" in str(result)
+
+        spans = trace_exporter.get_finished_spans()
+        span_names = [s.name for s in spans]
+
+        # Should have delegate span for resource
+        assert any(
+            "delegate" in name and "data://config" in name for name in span_names
+        )
+
+    async def test_mounted_prompt_creates_delegate_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        # Create a child server with a prompt
+        child = FastMCP("child-server")
+
+        @child.prompt()
+        def child_prompt() -> str:
+            return "Hello from child!"
+
+        # Create parent server and mount child with namespace
+        parent = FastMCP("parent-server")
+        parent.mount(child, namespace="child")
+
+        # Render the prompt through the parent (namespace uses underscore)
+        result = await parent.render_prompt("child_child_prompt", {})
+        assert "Hello from child!" in str(result)
+
+        spans = trace_exporter.get_finished_spans()
+        span_names = [s.name for s in spans]
+
+        # Should have delegate span for prompt
+        assert "delegate child_prompt" in span_names
+
+        # Verify delegate span has correct attributes
+        delegate_span = next(s for s in spans if s.name == "delegate child_prompt")
+        assert delegate_span.attributes is not None
+        assert delegate_span.attributes["fastmcp.provider.type"] == "FastMCPProvider"
+
+
+class TestProviderSpanHierarchy:
+    """Tests for span parent-child relationships in mounted servers."""
+
+    async def test_delegate_span_is_child_of_server_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        # Create nested server structure
+        child = FastMCP("child")
+
+        @child.tool()
+        def greet() -> str:
+            return "Hello"
+
+        parent = FastMCP("parent")
+        parent.mount(child, namespace="ns")
+
+        await parent.call_tool("ns_greet", {})
+
+        spans = trace_exporter.get_finished_spans()
+
+        # Find the spans
+        parent_span = next(s for s in spans if s.name == "tools/call ns_greet")
+        delegate_span = next(s for s in spans if s.name == "delegate greet")
+        child_span = next(s for s in spans if s.name == "tools/call greet")
+
+        # Verify parent-child relationships
+        assert delegate_span.parent is not None
+        assert child_span.parent is not None
+        assert delegate_span.parent.span_id == parent_span.context.span_id
+        assert child_span.parent.span_id == delegate_span.context.span_id
diff --git a/tests/server/telemetry/test_sampling_tracing.py b/tests/server/telemetry/test_sampling_tracing.py
new file mode 100644
index 0000000..db02b13
--- /dev/null
+++ b/tests/server/telemetry/test_sampling_tracing.py
@@ -0,0 +1,152 @@
+"""Tracing coverage for sampling create_message and tool-execution spans.
+
+Regression focus: the `sampling create_message` span is created with
+`record_exception=False, set_status_on_exception=False` and records the
+exception manually in its `except` block. A failed sampling call must
+therefore produce exactly ONE exception event, not two.
+"""
+
+from __future__ import annotations
+
+import pytest
+from mcp_types import TextContent
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+from opentelemetry.trace import StatusCode
+
+from fastmcp import Client, Context, FastMCP
+from fastmcp.client.sampling import RequestContext, SamplingMessage, SamplingParams
+
+
+def _spans_named(exporter: InMemorySpanExporter, name: str):
+    return [s for s in exporter.get_finished_spans() if s.name == name]
+
+
+def _exception_events(span):
+    return [e for e in span.events if e.name == "exception"]
+
+
+class TestSamplingCreateMessageSpan:
+    async def test_success_creates_span_with_attributes(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        def sampling_handler(
+            messages: list[SamplingMessage],
+            params: SamplingParams,
+            ctx: RequestContext,
+        ) -> str:
+            return "sampled-text"
+
+        mcp = FastMCP("sampling-server")
+
+        @mcp.tool
+        async def ask(question: str, context: Context) -> str:
+            result = await context.sample(messages=question)
+            return result.text or ""
+
+        async with Client(mcp, sampling_handler=sampling_handler) as client:
+            await client.call_tool("ask", {"question": "hi"})
+
+        spans = _spans_named(trace_exporter, "sampling create_message")
+        assert len(spans) == 1
+        span = spans[0]
+        assert span.attributes is not None
+        assert span.attributes["mcp.method.name"] == "sampling/createMessage"
+        assert span.attributes["fastmcp.server.name"] == "sampling-server"
+        # Success path must not record any exception.
+        assert _exception_events(span) == []
+        assert span.status.status_code != StatusCode.ERROR
+
+    async def test_failure_records_exception_exactly_once(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        """Regression: span created with record_exception=False so the manual
+        record_exception in the except block fires exactly once (no duplicate
+        exception events from OTel auto-recording on `with` exit)."""
+
+        def sampling_handler(
+            messages: list[SamplingMessage],
+            params: SamplingParams,
+            ctx: RequestContext,
+        ) -> str:
+            raise RuntimeError("sampling boom")
+
+        mcp = FastMCP("sampling-server")
+
+        @mcp.tool
+        async def ask(question: str, context: Context) -> str:
+            result = await context.sample(messages=question)
+            return result.text or ""
+
+        with pytest.raises(Exception):
+            async with Client(mcp, sampling_handler=sampling_handler) as client:
+                await client.call_tool("ask", {"question": "hi"})
+
+        spans = _spans_named(trace_exporter, "sampling create_message")
+        assert len(spans) == 1
+        span = spans[0]
+        assert span.status.status_code == StatusCode.ERROR
+        assert span.attributes is not None
+        assert "error.type" in span.attributes
+        # The whole point of the fix: exactly one exception event.
+        assert len(_exception_events(span)) == 1
+
+
+class TestSamplingToolSpan:
+    async def test_tool_error_span_records_exception_once(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        from mcp_types import CreateMessageResultWithTools, ToolUseContent
+
+        call_count = 0
+
+        def boom_tool() -> str:
+            raise ValueError("tool exploded")
+
+        def sampling_handler(
+            messages: list[SamplingMessage],
+            params: SamplingParams,
+            ctx: RequestContext,
+        ) -> CreateMessageResultWithTools:
+            nonlocal call_count
+            call_count += 1
+            if call_count == 1:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[
+                        ToolUseContent(
+                            type="tool_use",
+                            id="call_1",
+                            name="boom_tool",
+                            input={},
+                        )
+                    ],
+                    model="test-model",
+                    stop_reason="toolUse",
+                )
+            return CreateMessageResultWithTools(
+                role="assistant",
+                content=[TextContent(type="text", text="done")],
+                model="test-model",
+                stop_reason="endTurn",
+            )
+
+        mcp = FastMCP(sampling_handler=sampling_handler)
+
+        @mcp.tool
+        async def driver(context: Context) -> str:
+            result = await context.sample(messages="go", tools=[boom_tool])
+            return result.text or ""
+
+        async with Client(mcp) as client:
+            await client.call_tool("driver", {})
+
+        spans = _spans_named(trace_exporter, "sampling tool boom_tool")
+        assert len(spans) == 1
+        span = spans[0]
+        assert span.status.status_code == StatusCode.ERROR
+        assert span.attributes is not None
+        assert span.attributes["gen_ai.tool.name"] == "boom_tool"
+        assert "error.type" in span.attributes
+        # Tool spans catch-and-convert (no re-raise), so OTel auto-recording
+        # never fires; the manual record_exception must fire exactly once.
+        assert len(_exception_events(span)) == 1
diff --git a/tests/server/telemetry/test_server_tracing.py b/tests/server/telemetry/test_server_tracing.py
new file mode 100644
index 0000000..c04f49f
--- /dev/null
+++ b/tests/server/telemetry/test_server_tracing.py
@@ -0,0 +1,577 @@
+"""Tests for server-level OpenTelemetry tracing."""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+import pytest
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+from opentelemetry.trace import SpanKind, StatusCode
+
+from fastmcp import Client, FastMCP
+from fastmcp.exceptions import NotFoundError, ToolError
+from fastmcp.server.auth import AccessToken
+from fastmcp.server.middleware.middleware import CallNext, Middleware, MiddlewareContext
+
+
+class TestToolTracing:
+    async def test_call_tool_creates_span(self, trace_exporter: InMemorySpanExporter):
+        mcp = FastMCP("test-server")
+
+        @mcp.tool()
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        result = await mcp.call_tool("greet", {"name": "World"})
+        assert "Hello, World!" in str(result)
+
+        spans = trace_exporter.get_finished_spans()
+        assert len(spans) == 1
+
+        span = spans[0]
+        assert span.name == "tools/call greet"
+        assert span.kind == SpanKind.SERVER
+        assert span.attributes is not None
+        # Standard MCP semantic conventions
+        assert span.attributes["mcp.method.name"] == "tools/call"
+        # gen_ai semantic conventions
+        assert span.attributes["gen_ai.tool.name"] == "greet"
+        # RPC attributes must NOT be present
+        assert "rpc.system" not in span.attributes
+        assert "rpc.service" not in span.attributes
+        assert "rpc.method" not in span.attributes
+        # FastMCP-specific attributes
+        assert span.attributes["fastmcp.server.name"] == "test-server"
+        assert span.attributes["fastmcp.component.type"] == "tool"
+        assert span.attributes["fastmcp.component.key"] == "tool:greet@"
+
+    async def test_call_tool_with_error_sets_status(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        @mcp.tool()
+        def failing_tool() -> str:
+            raise ValueError("Something went wrong")
+
+        with pytest.raises(ToolError):
+            await mcp.call_tool("failing_tool", {})
+
+        spans = trace_exporter.get_finished_spans()
+        assert len(spans) == 1
+
+        span = spans[0]
+        assert span.name == "tools/call failing_tool"
+        assert span.status.status_code == StatusCode.ERROR
+        assert span.status.description is not None
+        assert "Something went wrong" in span.status.description
+        assert span.attributes is not None
+        assert span.attributes["error.type"] == "tool_error"
+        assert len(span.events) > 0  # Exception recorded
+
+    async def test_call_nonexistent_tool_sets_error(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        with pytest.raises(NotFoundError):
+            await mcp.call_tool("nonexistent", {})
+
+        spans = trace_exporter.get_finished_spans()
+        assert len(spans) == 1
+
+        span = spans[0]
+        assert span.name == "tools/call nonexistent"
+        assert span.status.status_code == StatusCode.ERROR
+        assert span.attributes is not None
+        # NotFoundError is not a ToolError, so uses class name as fallback
+        assert span.attributes["error.type"] == "NotFoundError"
+
+
+class TestResourceTracing:
+    async def test_read_resource_creates_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        @mcp.resource("config://app")
+        def get_config() -> str:
+            return "app_config_data"
+
+        result = await mcp.read_resource("config://app")
+        assert "app_config_data" in str(result)
+
+        spans = trace_exporter.get_finished_spans()
+        assert len(spans) == 1
+
+        span = spans[0]
+        assert span.name == "resources/read"
+        assert span.kind == SpanKind.SERVER
+        assert span.attributes is not None
+        # Standard MCP semantic conventions
+        assert span.attributes["mcp.method.name"] == "resources/read"
+        assert span.attributes["mcp.resource.uri"] == "config://app"
+        # RPC attributes must NOT be present
+        assert "rpc.system" not in span.attributes
+        assert "rpc.service" not in span.attributes
+        assert "rpc.method" not in span.attributes
+        # FastMCP-specific attributes
+        assert span.attributes["fastmcp.server.name"] == "test-server"
+        assert span.attributes["fastmcp.component.type"] == "resource"
+        assert span.attributes["fastmcp.component.key"] == "resource:config://app@"
+
+    async def test_read_resource_template_creates_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        @mcp.resource("users://{user_id}/profile")
+        def get_user_profile(user_id: str) -> str:
+            return f"profile for {user_id}"
+
+        result = await mcp.read_resource("users://123/profile")
+        assert "profile for 123" in str(result)
+
+        spans = trace_exporter.get_finished_spans()
+        assert len(spans) == 1
+
+        span = spans[0]
+        assert span.name == "resources/read"
+        assert span.kind == SpanKind.SERVER
+        assert span.attributes is not None
+        # Standard MCP semantic conventions
+        assert span.attributes["mcp.method.name"] == "resources/read"
+        assert span.attributes["mcp.resource.uri"] == "users://123/profile"
+        # RPC attributes must NOT be present
+        assert "rpc.system" not in span.attributes
+        assert "rpc.method" not in span.attributes
+        # Template component type is set by get_span_attributes
+        assert span.attributes["fastmcp.component.type"] == "resource_template"
+        assert (
+            span.attributes["fastmcp.component.key"]
+            == "template:users://{user_id}/profile@"
+        )
+
+    async def test_read_nonexistent_resource_sets_error(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        with pytest.raises(NotFoundError):
+            await mcp.read_resource("nonexistent://resource")
+
+        spans = trace_exporter.get_finished_spans()
+        assert len(spans) == 1
+
+        span = spans[0]
+        assert span.name == "resources/read"
+        assert span.status.status_code == StatusCode.ERROR
+
+
+class TestPromptTracing:
+    async def test_render_prompt_creates_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        @mcp.prompt()
+        def greeting(name: str) -> str:
+            return f"Hello, {name}!"
+
+        result = await mcp.render_prompt("greeting", {"name": "World"})
+        assert "Hello, World!" in str(result)
+
+        spans = trace_exporter.get_finished_spans()
+        assert len(spans) == 1
+
+        span = spans[0]
+        assert span.name == "prompts/get greeting"
+        assert span.kind == SpanKind.SERVER
+        assert span.attributes is not None
+        # Standard MCP semantic conventions
+        assert span.attributes["mcp.method.name"] == "prompts/get"
+        # gen_ai semantic conventions
+        assert span.attributes["gen_ai.prompt.name"] == "greeting"
+        # RPC attributes must NOT be present
+        assert "rpc.system" not in span.attributes
+        assert "rpc.service" not in span.attributes
+        assert "rpc.method" not in span.attributes
+        # FastMCP-specific attributes
+        assert span.attributes["fastmcp.server.name"] == "test-server"
+        assert span.attributes["fastmcp.component.type"] == "prompt"
+        assert span.attributes["fastmcp.component.key"] == "prompt:greeting@"
+
+    async def test_render_nonexistent_prompt_sets_error(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        with pytest.raises(NotFoundError):
+            await mcp.render_prompt("nonexistent", {})
+
+        spans = trace_exporter.get_finished_spans()
+        assert len(spans) == 1
+
+        span = spans[0]
+        assert span.name == "prompts/get nonexistent"
+        assert span.status.status_code == StatusCode.ERROR
+
+
+class TestAuthAttributesOnSpans:
+    async def test_tool_span_includes_auth_attributes_when_authenticated(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        @mcp.tool()
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        test_token = AccessToken(
+            token="test-token",
+            client_id="test-client-123",
+            scopes=["read", "write"],
+        )
+
+        with patch(
+            "fastmcp.server.dependencies.get_access_token", return_value=test_token
+        ):
+            await mcp.call_tool("greet", {"name": "World"})
+
+        spans = trace_exporter.get_finished_spans()
+        assert len(spans) == 1
+
+        span = spans[0]
+        assert span.attributes is not None
+        assert span.attributes["enduser.id"] == "test-client-123"
+        assert span.attributes["enduser.scope"] == "read write"
+
+    async def test_resource_span_includes_auth_attributes_when_authenticated(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        @mcp.resource("config://app")
+        def get_config() -> str:
+            return "config_data"
+
+        test_token = AccessToken(
+            token="test-token",
+            client_id="user-456",
+            scopes=["config:read"],
+        )
+
+        with patch(
+            "fastmcp.server.dependencies.get_access_token", return_value=test_token
+        ):
+            await mcp.read_resource("config://app")
+
+        spans = trace_exporter.get_finished_spans()
+        assert len(spans) == 1
+
+        span = spans[0]
+        assert span.attributes is not None
+        assert span.attributes["enduser.id"] == "user-456"
+        assert span.attributes["enduser.scope"] == "config:read"
+
+    async def test_prompt_span_includes_auth_attributes_when_authenticated(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        @mcp.prompt()
+        def greeting(name: str) -> str:
+            return f"Hello, {name}!"
+
+        test_token = AccessToken(
+            token="test-token",
+            client_id="prompt-user",
+            scopes=["prompts"],
+        )
+
+        with patch(
+            "fastmcp.server.dependencies.get_access_token", return_value=test_token
+        ):
+            await mcp.render_prompt("greeting", {"name": "World"})
+
+        spans = trace_exporter.get_finished_spans()
+        assert len(spans) == 1
+
+        span = spans[0]
+        assert span.attributes is not None
+        assert span.attributes["enduser.id"] == "prompt-user"
+        assert span.attributes["enduser.scope"] == "prompts"
+
+    async def test_span_omits_auth_attributes_when_not_authenticated(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        @mcp.tool()
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        # No mock - get_access_token returns None by default (no auth context)
+        await mcp.call_tool("greet", {"name": "World"})
+
+        spans = trace_exporter.get_finished_spans()
+        assert len(spans) == 1
+
+        span = spans[0]
+        assert span.attributes is not None
+        # Auth attributes should not be present
+        assert "enduser.id" not in span.attributes
+        assert "enduser.scope" not in span.attributes
+
+    async def test_span_omits_scope_when_no_scopes(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        @mcp.tool()
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        test_token = AccessToken(
+            token="test-token",
+            client_id="client-no-scopes",
+            scopes=[],  # Empty scopes
+        )
+
+        with patch(
+            "fastmcp.server.dependencies.get_access_token", return_value=test_token
+        ):
+            await mcp.call_tool("greet", {"name": "World"})
+
+        spans = trace_exporter.get_finished_spans()
+        assert len(spans) == 1
+
+        span = spans[0]
+        assert span.attributes is not None
+        assert span.attributes["enduser.id"] == "client-no-scopes"
+        # Scope attribute should not be present when scopes list is empty
+        assert "enduser.scope" not in span.attributes
+
+
+class TestSingleServerSpan:
+    """Full-dispatch tests guarding against duplicate SERVER spans.
+
+    The SDK seeds its own `OpenTelemetryMiddleware` into every lowlevel server,
+    which would emit a second SERVER span per request alongside FastMCP's. These
+    tests exercise the real request path (through a `Client`) so a regression
+    that re-enables the SDK middleware would surface as an extra SERVER span.
+    Note the in-process `mcp.call_tool` tests above bypass the dispatcher and so
+    cannot catch this.
+    """
+
+    async def test_tool_call_emits_single_server_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        @mcp.tool()
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        async with Client(mcp) as client:
+            await client.call_tool("greet", {"name": "World"})
+
+        spans = trace_exporter.get_finished_spans()
+        # Exactly one SERVER span for the tools/call request. Match by method name
+        # (not just the "tools/call greet" name) so a seam-level span accidentally
+        # opened for this high-level method — which would be named "tools/call" —
+        # is also counted and would trip the assertion.
+        tool_call_server_spans = [
+            s
+            for s in spans
+            if s.kind == SpanKind.SERVER
+            and s.attributes is not None
+            and s.attributes.get("mcp.method.name") == "tools/call"
+        ]
+        assert len(tool_call_server_spans) == 1
+        span = tool_call_server_spans[0]
+        assert span.name == "tools/call greet"
+        # The single span carries the rich component attributes that the
+        # high-level path enriches the seam span with (attribute parity: the
+        # enrichment must not lose the component context by opening a second
+        # span or by leaving the seam span bare).
+        assert span.attributes is not None
+        assert span.attributes["fastmcp.component.key"] == "tool:greet@"
+        assert span.attributes["gen_ai.tool.name"] == "greet"
+        assert span.attributes["fastmcp.component.type"] == "tool"
+
+    async def test_server_span_shares_client_trace(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        """FastMCP extracts inbound W3C trace context from `_meta`, so the single
+        SERVER span must still join the client's distributed trace."""
+        mcp = FastMCP("test-server")
+
+        @mcp.tool()
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        async with Client(mcp) as client:
+            await client.call_tool("greet", {"name": "World"})
+
+        spans = trace_exporter.get_finished_spans()
+        server_span = next(
+            s
+            for s in spans
+            if s.kind == SpanKind.SERVER and s.name == "tools/call greet"
+        )
+        client_span = next(
+            s
+            for s in spans
+            if s.kind == SpanKind.CLIENT and s.name == "MCP send tools/call greet"
+        )
+        assert server_span.context is not None
+        assert client_span.context is not None
+        assert server_span.context.trace_id == client_span.context.trace_id
+        assert server_span.parent is not None
+
+
+class TestSeamServerSpan:
+    """SERVER spans for methods outside the high-level tool/resource/prompt path.
+
+    FastMCP's rich SERVER spans are created deep in the high-level path, so
+    methods like `logging/setLevel`, `tasks/*`, `ping`, and `initialize` — which
+    never reach that code — would have no span at all once the SDK's
+    `OpenTelemetryMiddleware` is removed. The FastMCP middleware seam
+    (`FastMCPServerMiddleware`) emits a span for exactly those methods, so every
+    request method carries a SERVER span again.
+    """
+
+    async def test_set_logging_level_emits_seam_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        mcp = FastMCP("test-server")
+
+        async with Client(mcp) as client:
+            await client.set_logging_level("info")
+
+        spans = trace_exporter.get_finished_spans()
+        seam_spans = [
+            s
+            for s in spans
+            if s.kind == SpanKind.SERVER and s.name == "logging/setLevel"
+        ]
+        assert len(seam_spans) == 1
+        span = seam_spans[0]
+        assert span.attributes is not None
+        assert span.attributes["mcp.method.name"] == "logging/setLevel"
+        assert span.attributes["fastmcp.server.name"] == "test-server"
+
+    async def test_seam_method_emits_single_server_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        """A seam-spanned method must produce exactly one SERVER span, not two."""
+        mcp = FastMCP("test-server")
+
+        async with Client(mcp) as client:
+            await client.set_logging_level("info")
+
+        spans = trace_exporter.get_finished_spans()
+        set_level_server_spans = [
+            s
+            for s in spans
+            if s.kind == SpanKind.SERVER
+            and s.attributes is not None
+            and s.attributes.get("mcp.method.name") == "logging/setLevel"
+        ]
+        assert len(set_level_server_spans) == 1
+
+
+class TestFailurePathServerSpan:
+    """A tools/call rejected before the high-level handler must still be traced.
+
+    The rich SERVER span for tools/call is created deep in the high-level path,
+    after FastMCP middleware runs. A request rejected *before* that point (a
+    raising middleware, a not-found tool) never reaches it, so without the seam
+    span such failures would produce no SERVER span at all — the failure-path
+    observability regression this guards against. The seam span opened by
+    `FastMCPServerMiddleware` wraps the whole request, so every tools/call
+    carries a SERVER span with `mcp.method.name=tools/call`, and an exception
+    that propagates past the handler marks that span's status as an error.
+    """
+
+    async def test_middleware_error_before_handler_emits_error_span(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        """An unexpected error raised in FastMCP middleware, before the
+        high-level path, propagates to the seam span, which records it as an
+        error — where previously this method produced no SERVER span at all."""
+
+        class RaisingMiddleware(Middleware):
+            async def on_call_tool(
+                self,
+                context: MiddlewareContext,
+                call_next: CallNext,
+            ):
+                raise RuntimeError("rejected before handler")
+
+        mcp = FastMCP("test-server", middleware=[RaisingMiddleware()])
+
+        @mcp.tool()
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        async with Client(mcp) as client:
+            with pytest.raises(Exception):
+                await client.call_tool("greet", {"name": "World"})
+
+        spans = trace_exporter.get_finished_spans()
+        tool_call_server_spans = [
+            s
+            for s in spans
+            if s.kind == SpanKind.SERVER
+            and s.attributes is not None
+            and s.attributes.get("mcp.method.name") == "tools/call"
+        ]
+        assert len(tool_call_server_spans) == 1
+        span = tool_call_server_spans[0]
+        assert span.status.status_code == StatusCode.ERROR
+        assert span.attributes is not None
+        assert span.attributes["mcp.method.name"] == "tools/call"
+        assert span.attributes["error.type"] == "RuntimeError"
+        assert len(span.events) > 0  # exception recorded
+
+    async def test_tool_visible_rejection_before_handler_still_spans(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        """A tool-visible error raised in middleware is returned as an error
+        result (correct MCP semantics, so the span status is unset), but the
+        seam span still guarantees exactly one SERVER span for the tools/call —
+        the request is no longer invisible to tracing."""
+
+        class RejectingMiddleware(Middleware):
+            async def on_call_tool(
+                self,
+                context: MiddlewareContext,
+                call_next: CallNext,
+            ):
+                raise ToolError("rejected before handler")
+
+        mcp = FastMCP("test-server", middleware=[RejectingMiddleware()])
+
+        @mcp.tool()
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        async with Client(mcp) as client:
+            with pytest.raises(ToolError):
+                await client.call_tool("greet", {"name": "World"})
+
+        spans = trace_exporter.get_finished_spans()
+        tool_call_server_spans = [
+            s
+            for s in spans
+            if s.kind == SpanKind.SERVER
+            and s.attributes is not None
+            and s.attributes.get("mcp.method.name") == "tools/call"
+        ]
+        assert len(tool_call_server_spans) == 1
+        assert (
+            tool_call_server_spans[0].attributes is not None
+            and tool_call_server_spans[0].attributes["mcp.method.name"] == "tools/call"
+        )
diff --git a/tests/server/test_app_state.py b/tests/server/test_app_state.py
new file mode 100644
index 0000000..eeccd6f
--- /dev/null
+++ b/tests/server/test_app_state.py
@@ -0,0 +1,26 @@
+from fastmcp.server import FastMCP
+from fastmcp.server.http import create_sse_app, create_streamable_http_app
+
+
+def test_http_app_sets_mcp_server_state():
+    server = FastMCP(name="StateTest")
+    app = server.http_app()
+    assert app.state.fastmcp_server is server
+
+
+def test_http_app_sse_sets_mcp_server_state():
+    server = FastMCP(name="StateTest")
+    app = server.http_app(transport="sse")
+    assert app.state.fastmcp_server is server
+
+
+def test_create_streamable_http_app_sets_state():
+    server = FastMCP(name="StateTest")
+    app = create_streamable_http_app(server, "/mcp/")
+    assert app.state.fastmcp_server is server
+
+
+def test_create_sse_app_sets_state():
+    server = FastMCP(name="StateTest")
+    app = create_sse_app(server, message_path="/message", sse_path="/sse/")
+    assert app.state.fastmcp_server is server
diff --git a/tests/server/test_auth_integration.py b/tests/server/test_auth_integration.py
new file mode 100644
index 0000000..2b13173
--- /dev/null
+++ b/tests/server/test_auth_integration.py
@@ -0,0 +1,974 @@
+import base64
+import hashlib
+import secrets
+import time
+import unittest.mock
+from urllib.parse import parse_qs, urlparse
+
+import httpx
+import pytest
+from mcp.server.auth.provider import (
+    AccessToken,
+    AuthorizationCode,
+    AuthorizationParams,
+    OAuthAuthorizationServerProvider,
+    RefreshToken,
+    construct_redirect_uri,
+)
+from mcp.server.auth.routes import (
+    create_auth_routes,
+)
+from mcp.server.auth.settings import (
+    ClientRegistrationOptions,
+    RevocationOptions,
+)
+from mcp.shared.auth import (
+    OAuthClientInformationFull,
+    OAuthToken,
+)
+from pydantic import AnyHttpUrl
+from starlette.applications import Starlette
+
+
+# Mock OAuth provider for testing
+class MockOAuthProvider(OAuthAuthorizationServerProvider):
+    def __init__(self):
+        self.clients = {}
+        self.auth_codes = {}  # code -> {client_id, code_challenge, redirect_uri}
+        self.tokens = {}  # token -> {client_id, scopes, expires_at}
+        self.refresh_tokens = {}  # refresh_token -> access_token
+
+    async def get_client(self, client_id: str) -> OAuthClientInformationFull | None:
+        return self.clients.get(client_id)
+
+    async def register_client(self, client_info: OAuthClientInformationFull):
+        self.clients[client_info.client_id] = client_info
+
+    async def authorize(
+        self, client: OAuthClientInformationFull, params: AuthorizationParams
+    ) -> str:
+        # toy authorize implementation which just immediately generates an authorization
+        # code and completes the redirect
+        if client.client_id is None:
+            raise ValueError("client_id is required")
+        code = AuthorizationCode(
+            code=f"code_{int(time.time())}",
+            client_id=client.client_id,
+            code_challenge=params.code_challenge,
+            redirect_uri=params.redirect_uri,
+            redirect_uri_provided_explicitly=params.redirect_uri_provided_explicitly,
+            expires_at=time.time() + 300,
+            scopes=params.scopes or ["read", "write"],
+        )
+        self.auth_codes[code.code] = code
+
+        return construct_redirect_uri(
+            str(params.redirect_uri), code=code.code, state=params.state
+        )
+
+    async def load_authorization_code(
+        self, client: OAuthClientInformationFull, authorization_code: str
+    ) -> AuthorizationCode | None:
+        return self.auth_codes.get(authorization_code)
+
+    async def exchange_authorization_code(
+        self, client: OAuthClientInformationFull, authorization_code: AuthorizationCode
+    ) -> OAuthToken:
+        assert authorization_code.code in self.auth_codes
+
+        # Generate an access token and refresh token
+        access_token = f"access_{secrets.token_hex(32)}"
+        refresh_token = f"refresh_{secrets.token_hex(32)}"
+
+        # Store the tokens
+        if client.client_id is None:
+            raise ValueError("client_id is required")
+        self.tokens[access_token] = AccessToken(
+            token=access_token,
+            client_id=client.client_id,
+            scopes=authorization_code.scopes,
+            expires_at=int(time.time()) + 3600,
+        )
+
+        self.refresh_tokens[refresh_token] = access_token
+
+        # Remove the used code
+        del self.auth_codes[authorization_code.code]
+
+        return OAuthToken(
+            access_token=access_token,
+            token_type="Bearer",
+            expires_in=3600,
+            scope="read write",
+            refresh_token=refresh_token,
+        )
+
+    async def load_refresh_token(
+        self, client: OAuthClientInformationFull, refresh_token: str
+    ) -> RefreshToken | None:
+        old_access_token = self.refresh_tokens.get(refresh_token)
+        if old_access_token is None:
+            return None
+        token_info = self.tokens.get(old_access_token)
+        if token_info is None:
+            return None
+
+        # Create a RefreshToken object that matches what is expected in later code
+        refresh_obj = RefreshToken(
+            token=refresh_token,
+            client_id=token_info.client_id,
+            scopes=token_info.scopes,
+            expires_at=token_info.expires_at,
+        )
+
+        return refresh_obj
+
+    async def exchange_refresh_token(
+        self,
+        client: OAuthClientInformationFull,
+        refresh_token: RefreshToken,
+        scopes: list[str],
+    ) -> OAuthToken:
+        # Check if refresh token exists
+        assert refresh_token.token in self.refresh_tokens
+
+        old_access_token = self.refresh_tokens[refresh_token.token]
+
+        # Check if the access token exists
+        assert old_access_token in self.tokens
+
+        # Check if the token was issued to this client
+        token_info = self.tokens[old_access_token]
+        assert token_info.client_id == client.client_id
+
+        # Generate a new access token and refresh token
+        new_access_token = f"access_{secrets.token_hex(32)}"
+        new_refresh_token = f"refresh_{secrets.token_hex(32)}"
+
+        # Store the new tokens
+        if client.client_id is None:
+            raise ValueError("client_id is required")
+        self.tokens[new_access_token] = AccessToken(
+            token=new_access_token,
+            client_id=client.client_id,
+            scopes=scopes or token_info.scopes,
+            expires_at=int(time.time()) + 3600,
+        )
+
+        self.refresh_tokens[new_refresh_token] = new_access_token
+
+        # Remove the old tokens
+        del self.refresh_tokens[refresh_token.token]
+        del self.tokens[old_access_token]
+
+        return OAuthToken(
+            access_token=new_access_token,
+            token_type="Bearer",
+            expires_in=3600,
+            scope=" ".join(scopes) if scopes else " ".join(token_info.scopes),
+            refresh_token=new_refresh_token,
+        )
+
+    async def load_access_token(self, token: str) -> AccessToken | None:
+        token_info = self.tokens.get(token)
+
+        # Check if token is expired
+        # if token_info.expires_at < int(time.time()):
+        #     raise InvalidTokenError("Access token has expired")
+
+        return token_info and AccessToken(
+            token=token,
+            client_id=token_info.client_id,
+            scopes=token_info.scopes,
+            expires_at=token_info.expires_at,
+        )
+
+    async def revoke_token(self, token: AccessToken | RefreshToken) -> None:
+        match token:
+            case RefreshToken():
+                # Remove the refresh token
+                del self.refresh_tokens[token.token]
+
+            case AccessToken():
+                # Remove the access token
+                del self.tokens[token.token]
+
+                # Also remove any refresh tokens that point to this access token
+                for refresh_token, access_token in list(self.refresh_tokens.items()):
+                    if access_token == token.token:
+                        del self.refresh_tokens[refresh_token]
+
+
+@pytest.fixture
+def mock_oauth_provider():
+    return MockOAuthProvider()
+
+
+@pytest.fixture
+def auth_app(mock_oauth_provider):
+    # Create auth router
+    auth_routes = create_auth_routes(
+        mock_oauth_provider,
+        AnyHttpUrl("https://auth.example.com"),
+        AnyHttpUrl("https://docs.example.com"),
+        client_registration_options=ClientRegistrationOptions(
+            enabled=True,
+            valid_scopes=["read", "write", "profile"],
+            default_scopes=["read", "write"],
+        ),
+        revocation_options=RevocationOptions(enabled=True),
+    )
+
+    # Create Starlette app
+    app = Starlette(routes=auth_routes)
+
+    return app
+
+
+@pytest.fixture
+async def test_client(auth_app):
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=auth_app), base_url="https://mcptest.com"
+    ) as client:
+        yield client
+
+
+@pytest.fixture
+async def registered_client(test_client: httpx.AsyncClient, request):
+    """Create and register a test client.
+
+    Parameters can be customized via indirect parameterization:
+    @pytest.mark.parametrize("registered_client",
+                            [{"grant_types": ["authorization_code"]}],
+                            indirect=True)
+    """
+    # Default client metadata
+    client_metadata = {
+        "redirect_uris": ["https://client.example.com/callback"],
+        "client_name": "Test Client",
+        "grant_types": ["authorization_code", "refresh_token"],
+    }
+
+    # Override with any parameters from the test
+    if hasattr(request, "param") and request.param:
+        client_metadata.update(request.param)
+
+    response = await test_client.post("/register", json=client_metadata)
+    assert response.status_code == 201, f"Failed to register client: {response.content}"
+
+    client_info = response.json()
+    return client_info
+
+
+@pytest.fixture
+def pkce_challenge():
+    """Create a PKCE challenge with code_verifier and code_challenge."""
+    code_verifier = "some_random_verifier_string"
+    code_challenge = (
+        base64.urlsafe_b64encode(hashlib.sha256(code_verifier.encode()).digest())
+        .decode()
+        .rstrip("=")
+    )
+
+    return {"code_verifier": code_verifier, "code_challenge": code_challenge}
+
+
+@pytest.fixture
+async def auth_code(test_client, registered_client, pkce_challenge, request):
+    """Get an authorization code.
+
+    Parameters can be customized via indirect parameterization:
+    @pytest.mark.parametrize("auth_code",
+                            [{"redirect_uri": "https://client.example.com/other-callback"}],
+                            indirect=True)
+    """
+    # Default authorize params
+    auth_params = {
+        "response_type": "code",
+        "client_id": registered_client["client_id"],
+        "redirect_uri": "https://client.example.com/callback",
+        "code_challenge": pkce_challenge["code_challenge"],
+        "code_challenge_method": "S256",
+        "state": "test_state",
+    }
+
+    # Override with any parameters from the test
+    if hasattr(request, "param") and request.param:
+        auth_params.update(request.param)
+
+    response = await test_client.get("/authorize", params=auth_params)
+    assert response.status_code == 302, f"Failed to get auth code: {response.content}"
+
+    # Extract the authorization code
+    redirect_url = response.headers["location"]
+    parsed_url = urlparse(redirect_url)
+    query_params = parse_qs(parsed_url.query)
+
+    assert "code" in query_params, f"No code in response: {query_params}"
+    auth_code = query_params["code"][0]
+
+    return {
+        "code": auth_code,
+        "redirect_uri": auth_params["redirect_uri"],
+        "state": query_params.get("state", [None])[0],
+    }
+
+
+@pytest.fixture
+async def tokens(test_client, registered_client, auth_code, pkce_challenge, request):
+    """Exchange authorization code for tokens.
+
+    Parameters can be customized via indirect parameterization:
+    @pytest.mark.parametrize("tokens",
+                            [{"code_verifier": "wrong_verifier"}],
+                            indirect=True)
+    """
+    # Default token request params
+    token_params = {
+        "grant_type": "authorization_code",
+        "client_id": registered_client["client_id"],
+        "client_secret": registered_client["client_secret"],
+        "code": auth_code["code"],
+        "code_verifier": pkce_challenge["code_verifier"],
+        "redirect_uri": auth_code["redirect_uri"],
+    }
+
+    # Override with any parameters from the test
+    if hasattr(request, "param") and request.param:
+        token_params.update(request.param)
+
+    response = await test_client.post("/token", data=token_params)
+
+    # Don't assert success here since some tests will intentionally cause errors
+    return {
+        "response": response,
+        "params": token_params,
+    }
+
+
+class TestAuthEndpoints:
+    async def test_metadata_endpoint(self, test_client: httpx.AsyncClient):
+        """Test the OAuth 2.1 metadata endpoint."""
+        print("Sending request to metadata endpoint")
+        response = await test_client.get("/.well-known/oauth-authorization-server")
+        print(f"Got response: {response.status_code}")
+        if response.status_code != 200:
+            print(f"Response content: {response.content}")
+        assert response.status_code == 200
+
+        metadata = response.json()
+        assert metadata["issuer"] == "https://auth.example.com/"
+        assert (
+            metadata["authorization_endpoint"] == "https://auth.example.com/authorize"
+        )
+        assert metadata["token_endpoint"] == "https://auth.example.com/token"
+        assert metadata["registration_endpoint"] == "https://auth.example.com/register"
+        assert metadata["revocation_endpoint"] == "https://auth.example.com/revoke"
+        assert metadata["response_types_supported"] == ["code"]
+        assert metadata["code_challenge_methods_supported"] == ["S256"]
+        assert set(metadata["token_endpoint_auth_methods_supported"]) == {
+            "client_secret_post",
+            "client_secret_basic",
+        }
+        assert metadata["grant_types_supported"] == [
+            "authorization_code",
+            "refresh_token",
+        ]
+        assert metadata["service_documentation"] == "https://docs.example.com/"
+
+    async def test_token_validation_error(self, test_client: httpx.AsyncClient):
+        """Test token endpoint error - missing client_id returns auth error."""
+        # Missing required fields - SDK validates client_id first
+        response = await test_client.post(
+            "/token",
+            data={
+                "grant_type": "authorization_code",
+                # Missing code, code_verifier, client_id, etc.
+            },
+        )
+        error_response = response.json()
+        # The SDK authenticates the client before validating other fields; a
+        # missing/failed client authentication returns invalid_client (401).
+        # `unauthorized_client` is now reserved for an authenticated client
+        # using a grant type it isn't allowed to use.
+        assert error_response["error"] == "invalid_client"
+        assert "error_description" in error_response
+
+    async def test_token_invalid_auth_code(
+        self, test_client, registered_client, pkce_challenge
+    ):
+        """Test token endpoint error - authorization code does not exist."""
+        # Try to use a non-existent authorization code
+        response = await test_client.post(
+            "/token",
+            data={
+                "grant_type": "authorization_code",
+                "client_id": registered_client["client_id"],
+                "client_secret": registered_client["client_secret"],
+                "code": "non_existent_auth_code",
+                "code_verifier": pkce_challenge["code_verifier"],
+                "redirect_uri": "https://client.example.com/callback",
+            },
+        )
+        print(f"Status code: {response.status_code}")
+        print(f"Response body: {response.content}")
+        print(f"Response JSON: {response.json()}")
+        assert response.status_code == 400
+        error_response = response.json()
+        assert error_response["error"] == "invalid_grant"
+        assert (
+            "authorization code does not exist" in error_response["error_description"]
+        )
+
+    async def test_token_expired_auth_code(
+        self,
+        test_client,
+        registered_client,
+        auth_code,
+        pkce_challenge,
+        mock_oauth_provider,
+    ):
+        """Test token endpoint error - authorization code has expired."""
+        # Get the current time for our time mocking
+        current_time = time.time()
+
+        # Find the auth code object
+        code_value = auth_code["code"]
+        found_code = None
+        for code_obj in mock_oauth_provider.auth_codes.values():
+            if code_obj.code == code_value:
+                found_code = code_obj
+                break
+
+        assert found_code is not None
+
+        # Authorization codes are typically short-lived (5 minutes = 300 seconds)
+        # So we'll mock time to be 10 minutes (600 seconds) in the future
+        with unittest.mock.patch("time.time", return_value=current_time + 600):
+            # Try to use the expired authorization code
+            response = await test_client.post(
+                "/token",
+                data={
+                    "grant_type": "authorization_code",
+                    "client_id": registered_client["client_id"],
+                    "client_secret": registered_client["client_secret"],
+                    "code": code_value,
+                    "code_verifier": pkce_challenge["code_verifier"],
+                    "redirect_uri": auth_code["redirect_uri"],
+                },
+            )
+            assert response.status_code == 400
+            error_response = response.json()
+            assert error_response["error"] == "invalid_grant"
+            assert (
+                "authorization code has expired" in error_response["error_description"]
+            )
+
+    @pytest.mark.parametrize(
+        "registered_client",
+        [
+            {
+                "redirect_uris": [
+                    "https://client.example.com/callback",
+                    "https://client.example.com/other-callback",
+                ]
+            }
+        ],
+        indirect=True,
+    )
+    async def test_token_redirect_uri_mismatch(
+        self, test_client, registered_client, auth_code, pkce_challenge
+    ):
+        """Test token endpoint error - redirect URI mismatch."""
+        # Try to use the code with a different redirect URI
+        response = await test_client.post(
+            "/token",
+            data={
+                "grant_type": "authorization_code",
+                "client_id": registered_client["client_id"],
+                "client_secret": registered_client["client_secret"],
+                "code": auth_code["code"],
+                "code_verifier": pkce_challenge["code_verifier"],
+                # Different from the one used in /authorize
+                "redirect_uri": "https://client.example.com/other-callback",
+            },
+        )
+        assert response.status_code == 400
+        error_response = response.json()
+        assert error_response["error"] == "invalid_request"
+        assert "redirect_uri did not match" in error_response["error_description"]
+
+    async def test_token_code_verifier_mismatch(
+        self, test_client, registered_client, auth_code
+    ):
+        """Test token endpoint error - PKCE code verifier mismatch."""
+        # Try to use the code with an incorrect code verifier
+        response = await test_client.post(
+            "/token",
+            data={
+                "grant_type": "authorization_code",
+                "client_id": registered_client["client_id"],
+                "client_secret": registered_client["client_secret"],
+                "code": auth_code["code"],
+                # Different from the one used to create challenge
+                "code_verifier": "incorrect_code_verifier",
+                "redirect_uri": auth_code["redirect_uri"],
+            },
+        )
+        assert response.status_code == 400
+        error_response = response.json()
+        assert error_response["error"] == "invalid_grant"
+        assert "incorrect code_verifier" in error_response["error_description"]
+
+    async def test_token_invalid_refresh_token(self, test_client, registered_client):
+        """Test token endpoint error - refresh token does not exist."""
+        # Try to use a non-existent refresh token
+        response = await test_client.post(
+            "/token",
+            data={
+                "grant_type": "refresh_token",
+                "client_id": registered_client["client_id"],
+                "client_secret": registered_client["client_secret"],
+                "refresh_token": "non_existent_refresh_token",
+            },
+        )
+        assert response.status_code == 400
+        error_response = response.json()
+        assert error_response["error"] == "invalid_grant"
+        assert "refresh token does not exist" in error_response["error_description"]
+
+    async def test_token_expired_refresh_token(
+        self,
+        test_client,
+        registered_client,
+        auth_code,
+        pkce_challenge,
+        mock_oauth_provider,
+    ):
+        """Test token endpoint error - refresh token has expired."""
+        # Step 1: First, let's create a token and refresh token at the current time
+        current_time = time.time()
+
+        # Exchange authorization code for tokens normally
+        token_response = await test_client.post(
+            "/token",
+            data={
+                "grant_type": "authorization_code",
+                "client_id": registered_client["client_id"],
+                "client_secret": registered_client["client_secret"],
+                "code": auth_code["code"],
+                "code_verifier": pkce_challenge["code_verifier"],
+                "redirect_uri": auth_code["redirect_uri"],
+            },
+        )
+        assert token_response.status_code == 200
+        tokens = token_response.json()
+        refresh_token = tokens["refresh_token"]
+
+        # Step 2: Time travel forward 4 hours (tokens expire in 1 hour by default)
+        # Mock the time.time() function to return a value 4 hours in the future
+        with unittest.mock.patch(
+            "time.time", return_value=current_time + 14400
+        ):  # 4 hours = 14400 seconds
+            # Try to use the refresh token which should now be considered expired
+            response = await test_client.post(
+                "/token",
+                data={
+                    "grant_type": "refresh_token",
+                    "client_id": registered_client["client_id"],
+                    "client_secret": registered_client["client_secret"],
+                    "refresh_token": refresh_token,
+                },
+            )
+
+            # In the "future", the token should be considered expired
+            assert response.status_code == 400
+            error_response = response.json()
+            assert error_response["error"] == "invalid_grant"
+            assert "refresh token has expired" in error_response["error_description"]
+
+    async def test_token_invalid_scope(
+        self, test_client, registered_client, auth_code, pkce_challenge
+    ):
+        """Test token endpoint error - invalid scope in refresh token request."""
+        # Exchange authorization code for tokens
+        token_response = await test_client.post(
+            "/token",
+            data={
+                "grant_type": "authorization_code",
+                "client_id": registered_client["client_id"],
+                "client_secret": registered_client["client_secret"],
+                "code": auth_code["code"],
+                "code_verifier": pkce_challenge["code_verifier"],
+                "redirect_uri": auth_code["redirect_uri"],
+            },
+        )
+        assert token_response.status_code == 200
+
+        tokens = token_response.json()
+        refresh_token = tokens["refresh_token"]
+
+        # Try to use refresh token with an invalid scope
+        response = await test_client.post(
+            "/token",
+            data={
+                "grant_type": "refresh_token",
+                "client_id": registered_client["client_id"],
+                "client_secret": registered_client["client_secret"],
+                "refresh_token": refresh_token,
+                "scope": "read write invalid_scope",  # Adding an invalid scope
+            },
+        )
+        assert response.status_code == 400
+        error_response = response.json()
+        assert error_response["error"] == "invalid_scope"
+        assert "cannot request scope" in error_response["error_description"]
+
+    async def test_client_registration(
+        self, test_client: httpx.AsyncClient, mock_oauth_provider: MockOAuthProvider
+    ):
+        """Test client registration."""
+        client_metadata = {
+            "redirect_uris": ["https://client.example.com/callback"],
+            "client_name": "Test Client",
+            "client_uri": "https://client.example.com",
+        }
+
+        response = await test_client.post(
+            "/register",
+            json=client_metadata,
+        )
+        assert response.status_code == 201, response.content
+
+        client_info = response.json()
+        assert "client_id" in client_info
+        assert "client_secret" in client_info
+        assert client_info["client_name"] == "Test Client"
+        assert client_info["redirect_uris"] == ["https://client.example.com/callback"]
+
+        # Verify that the client was registered
+        # assert await mock_oauth_provider.clients_store.get_client(
+        #     client_info["client_id"]
+        # ) is not None
+
+    async def test_client_registration_missing_required_fields(
+        self, test_client: httpx.AsyncClient
+    ):
+        """Test client registration with missing required fields."""
+        # Missing redirect_uris which is a required field
+        client_metadata = {
+            "client_name": "Test Client",
+            "client_uri": "https://client.example.com",
+        }
+
+        response = await test_client.post(
+            "/register",
+            json=client_metadata,
+        )
+        assert response.status_code == 400
+        error_data = response.json()
+        assert "error" in error_data
+        assert error_data["error"] == "invalid_client_metadata"
+        assert error_data["error_description"] == "redirect_uris: Field required"
+
+    async def test_client_registration_invalid_uri(
+        self, test_client: httpx.AsyncClient
+    ):
+        """Test client registration with invalid URIs."""
+        # Invalid redirect_uri format
+        client_metadata = {
+            "redirect_uris": ["not-a-valid-uri"],
+            "client_name": "Test Client",
+        }
+
+        response = await test_client.post(
+            "/register",
+            json=client_metadata,
+        )
+        assert response.status_code == 400
+        error_data = response.json()
+        assert "error" in error_data
+        assert error_data["error"] == "invalid_client_metadata"
+        assert error_data["error_description"] == (
+            "redirect_uris.0: Input should be a valid URL, relative URL without a base"
+        )
+
+    async def test_client_registration_empty_redirect_uris(
+        self, test_client: httpx.AsyncClient
+    ):
+        """Test client registration with empty redirect_uris array."""
+        client_metadata = {
+            "redirect_uris": [],  # Empty array
+            "client_name": "Test Client",
+        }
+
+        response = await test_client.post(
+            "/register",
+            json=client_metadata,
+        )
+        assert response.status_code == 400
+        error_data = response.json()
+        assert "error" in error_data
+        assert error_data["error"] == "invalid_client_metadata"
+        assert (
+            error_data["error_description"]
+            == "redirect_uris: List should have at least 1 item after validation, not 0"
+        )
+
+    async def test_authorize_form_post(
+        self,
+        test_client: httpx.AsyncClient,
+        mock_oauth_provider: MockOAuthProvider,
+        pkce_challenge,
+    ):
+        """Test the authorization endpoint using POST with form-encoded data."""
+        # Register a client
+        client_metadata = {
+            "redirect_uris": ["https://client.example.com/callback"],
+            "client_name": "Test Client",
+            "grant_types": ["authorization_code", "refresh_token"],
+        }
+
+        response = await test_client.post(
+            "/register",
+            json=client_metadata,
+        )
+        assert response.status_code == 201
+        client_info = response.json()
+
+        # Use POST with form-encoded data for authorization
+        response = await test_client.post(
+            "/authorize",
+            data={
+                "response_type": "code",
+                "client_id": client_info["client_id"],
+                "redirect_uri": "https://client.example.com/callback",
+                "code_challenge": pkce_challenge["code_challenge"],
+                "code_challenge_method": "S256",
+                "state": "test_form_state",
+            },
+        )
+        assert response.status_code == 302
+
+        # Extract the authorization code from the redirect URL
+        redirect_url = response.headers["location"]
+        parsed_url = urlparse(redirect_url)
+        query_params = parse_qs(parsed_url.query)
+
+        assert "code" in query_params
+        assert query_params["state"][0] == "test_form_state"
+
+    async def test_authorization_get(
+        self,
+        test_client: httpx.AsyncClient,
+        mock_oauth_provider: MockOAuthProvider,
+        pkce_challenge,
+    ):
+        """Test the full authorization flow."""
+        # 1. Register a client
+        client_metadata = {
+            "redirect_uris": ["https://client.example.com/callback"],
+            "client_name": "Test Client",
+            "grant_types": ["authorization_code", "refresh_token"],
+        }
+
+        response = await test_client.post(
+            "/register",
+            json=client_metadata,
+        )
+        assert response.status_code == 201
+        client_info = response.json()
+
+        # 2. Request authorization using GET with query params
+        response = await test_client.get(
+            "/authorize",
+            params={
+                "response_type": "code",
+                "client_id": client_info["client_id"],
+                "redirect_uri": "https://client.example.com/callback",
+                "code_challenge": pkce_challenge["code_challenge"],
+                "code_challenge_method": "S256",
+                "state": "test_state",
+            },
+        )
+        assert response.status_code == 302
+
+        # 3. Extract the authorization code from the redirect URL
+        redirect_url = response.headers["location"]
+        parsed_url = urlparse(redirect_url)
+        query_params = parse_qs(parsed_url.query)
+
+        assert "code" in query_params
+        assert query_params["state"][0] == "test_state"
+        auth_code = query_params["code"][0]
+
+        # 4. Exchange the authorization code for tokens
+        response = await test_client.post(
+            "/token",
+            data={
+                "grant_type": "authorization_code",
+                "client_id": client_info["client_id"],
+                "client_secret": client_info["client_secret"],
+                "code": auth_code,
+                "code_verifier": pkce_challenge["code_verifier"],
+                "redirect_uri": "https://client.example.com/callback",
+            },
+        )
+        assert response.status_code == 200
+
+        token_response = response.json()
+        assert "access_token" in token_response
+        assert "token_type" in token_response
+        assert "refresh_token" in token_response
+        assert "expires_in" in token_response
+        assert token_response["token_type"] == "Bearer"
+
+        # 5. Verify the access token
+        access_token = token_response["access_token"]
+        refresh_token = token_response["refresh_token"]
+
+        # Create a test client with the token
+        auth_info = await mock_oauth_provider.load_access_token(access_token)
+        assert auth_info
+        assert auth_info.client_id == client_info["client_id"]
+        assert "read" in auth_info.scopes
+        assert "write" in auth_info.scopes
+
+        # 6. Refresh the token
+        response = await test_client.post(
+            "/token",
+            data={
+                "grant_type": "refresh_token",
+                "client_id": client_info["client_id"],
+                "client_secret": client_info["client_secret"],
+                "refresh_token": refresh_token,
+                "redirect_uri": "https://client.example.com/callback",
+            },
+        )
+        assert response.status_code == 200
+
+        new_token_response = response.json()
+        assert "access_token" in new_token_response
+        assert "refresh_token" in new_token_response
+        assert new_token_response["access_token"] != access_token
+        assert new_token_response["refresh_token"] != refresh_token
+
+        # 7. Revoke the token
+        response = await test_client.post(
+            "/revoke",
+            data={
+                "client_id": client_info["client_id"],
+                "client_secret": client_info["client_secret"],
+                "token": new_token_response["access_token"],
+            },
+        )
+        assert response.status_code == 200
+
+        # Verify that the token was revoked
+        assert (
+            await mock_oauth_provider.load_access_token(
+                new_token_response["access_token"]
+            )
+            is None
+        )
+
+    async def test_revoke_invalid_token(self, test_client, registered_client):
+        """Test revoking an invalid token."""
+        response = await test_client.post(
+            "/revoke",
+            data={
+                "client_id": registered_client["client_id"],
+                "client_secret": registered_client["client_secret"],
+                "token": "invalid_token",
+            },
+        )
+        # per RFC, this should return 200 even if the token is invalid
+        assert response.status_code == 200
+
+    async def test_revoke_with_malformed_token(self, test_client, registered_client):
+        response = await test_client.post(
+            "/revoke",
+            data={
+                "client_id": registered_client["client_id"],
+                "client_secret": registered_client["client_secret"],
+                "token": 123,
+                "token_type_hint": "asdf",
+            },
+        )
+        assert response.status_code == 400
+        error_response = response.json()
+        assert error_response["error"] == "invalid_request"
+        assert "token_type_hint" in error_response["error_description"]
+
+    async def test_client_registration_disallowed_scopes(
+        self, test_client: httpx.AsyncClient
+    ):
+        """Test client registration with scopes that are not allowed."""
+        client_metadata = {
+            "redirect_uris": ["https://client.example.com/callback"],
+            "client_name": "Test Client",
+            "scope": "read write profile admin",  # 'admin' is not in valid_scopes
+        }
+
+        response = await test_client.post(
+            "/register",
+            json=client_metadata,
+        )
+        assert response.status_code == 400
+        error_data = response.json()
+        assert "error" in error_data
+        assert error_data["error"] == "invalid_client_metadata"
+        assert "scope" in error_data["error_description"]
+        assert "admin" in error_data["error_description"]
+
+    async def test_client_registration_default_scopes(
+        self, test_client: httpx.AsyncClient, mock_oauth_provider: MockOAuthProvider
+    ):
+        client_metadata = {
+            "redirect_uris": ["https://client.example.com/callback"],
+            "client_name": "Test Client",
+            # No scope specified
+        }
+
+        response = await test_client.post(
+            "/register",
+            json=client_metadata,
+        )
+        assert response.status_code == 201
+        client_info = response.json()
+
+        # Verify client was registered successfully
+        assert client_info["scope"] == "read write"
+
+        # Retrieve the client from the store to verify default scopes
+        registered_client = await mock_oauth_provider.get_client(
+            client_info["client_id"]
+        )
+        assert registered_client is not None
+
+        # Check that default scopes were applied
+        assert registered_client.scope == "read write"
+
+    async def test_client_registration_invalid_grant_type(
+        self, test_client: httpx.AsyncClient
+    ):
+        # The SDK requires `authorization_code` to be present in grant_types;
+        # a set that omits it is rejected. (`refresh_token` alone is invalid.)
+        client_metadata = {
+            "redirect_uris": ["https://client.example.com/callback"],
+            "client_name": "Test Client",
+            "grant_types": ["refresh_token"],
+        }
+
+        response = await test_client.post(
+            "/register",
+            json=client_metadata,
+        )
+        assert response.status_code == 400
+        error_data = response.json()
+        assert "error" in error_data
+        assert error_data["error"] == "invalid_client_metadata"
+        assert (
+            error_data["error_description"]
+            == "grant_types must include 'authorization_code'"
+        )
diff --git a/tests/server/test_auth_integration_errors.py b/tests/server/test_auth_integration_errors.py
new file mode 100644
index 0000000..1967011
--- /dev/null
+++ b/tests/server/test_auth_integration_errors.py
@@ -0,0 +1,539 @@
+import base64
+import hashlib
+import secrets
+import time
+from urllib.parse import parse_qs, urlparse
+
+import httpx
+import pytest
+from mcp.server.auth.provider import (
+    AccessToken,
+    AuthorizationCode,
+    AuthorizationParams,
+    OAuthAuthorizationServerProvider,
+    RefreshToken,
+    construct_redirect_uri,
+)
+from mcp.server.auth.routes import (
+    create_auth_routes,
+)
+from mcp.server.auth.settings import (
+    ClientRegistrationOptions,
+    RevocationOptions,
+)
+from mcp.shared.auth import (
+    OAuthClientInformationFull,
+    OAuthToken,
+)
+from pydantic import AnyHttpUrl
+from starlette.applications import Starlette
+
+
+# Mock OAuth provider for testing
+class MockOAuthProvider(OAuthAuthorizationServerProvider):
+    def __init__(self):
+        self.clients = {}
+        self.auth_codes = {}  # code -> {client_id, code_challenge, redirect_uri}
+        self.tokens = {}  # token -> {client_id, scopes, expires_at}
+        self.refresh_tokens = {}  # refresh_token -> access_token
+
+    async def get_client(self, client_id: str) -> OAuthClientInformationFull | None:
+        return self.clients.get(client_id)
+
+    async def register_client(self, client_info: OAuthClientInformationFull):
+        self.clients[client_info.client_id] = client_info
+
+    async def authorize(
+        self, client: OAuthClientInformationFull, params: AuthorizationParams
+    ) -> str:
+        # toy authorize implementation which just immediately generates an authorization
+        # code and completes the redirect
+        if client.client_id is None:
+            raise ValueError("client_id is required")
+        code = AuthorizationCode(
+            code=f"code_{int(time.time())}",
+            client_id=client.client_id,
+            code_challenge=params.code_challenge,
+            redirect_uri=params.redirect_uri,
+            redirect_uri_provided_explicitly=params.redirect_uri_provided_explicitly,
+            expires_at=time.time() + 300,
+            scopes=params.scopes or ["read", "write"],
+        )
+        self.auth_codes[code.code] = code
+
+        return construct_redirect_uri(
+            str(params.redirect_uri), code=code.code, state=params.state
+        )
+
+    async def load_authorization_code(
+        self, client: OAuthClientInformationFull, authorization_code: str
+    ) -> AuthorizationCode | None:
+        return self.auth_codes.get(authorization_code)
+
+    async def exchange_authorization_code(
+        self, client: OAuthClientInformationFull, authorization_code: AuthorizationCode
+    ) -> OAuthToken:
+        assert authorization_code.code in self.auth_codes
+
+        # Generate an access token and refresh token
+        access_token = f"access_{secrets.token_hex(32)}"
+        refresh_token = f"refresh_{secrets.token_hex(32)}"
+
+        # Store the tokens
+        if client.client_id is None:
+            raise ValueError("client_id is required")
+        self.tokens[access_token] = AccessToken(
+            token=access_token,
+            client_id=client.client_id,
+            scopes=authorization_code.scopes,
+            expires_at=int(time.time()) + 3600,
+        )
+
+        self.refresh_tokens[refresh_token] = access_token
+
+        # Remove the used code
+        del self.auth_codes[authorization_code.code]
+
+        return OAuthToken(
+            access_token=access_token,
+            token_type="Bearer",
+            expires_in=3600,
+            scope="read write",
+            refresh_token=refresh_token,
+        )
+
+    async def load_refresh_token(
+        self, client: OAuthClientInformationFull, refresh_token: str
+    ) -> RefreshToken | None:
+        old_access_token = self.refresh_tokens.get(refresh_token)
+        if old_access_token is None:
+            return None
+        token_info = self.tokens.get(old_access_token)
+        if token_info is None:
+            return None
+
+        # Create a RefreshToken object that matches what is expected in later code
+        refresh_obj = RefreshToken(
+            token=refresh_token,
+            client_id=token_info.client_id,
+            scopes=token_info.scopes,
+            expires_at=token_info.expires_at,
+        )
+
+        return refresh_obj
+
+    async def exchange_refresh_token(
+        self,
+        client: OAuthClientInformationFull,
+        refresh_token: RefreshToken,
+        scopes: list[str],
+    ) -> OAuthToken:
+        # Check if refresh token exists
+        assert refresh_token.token in self.refresh_tokens
+
+        old_access_token = self.refresh_tokens[refresh_token.token]
+
+        # Check if the access token exists
+        assert old_access_token in self.tokens
+
+        # Check if the token was issued to this client
+        token_info = self.tokens[old_access_token]
+        assert token_info.client_id == client.client_id
+
+        # Generate a new access token and refresh token
+        new_access_token = f"access_{secrets.token_hex(32)}"
+        new_refresh_token = f"refresh_{secrets.token_hex(32)}"
+
+        # Store the new tokens
+        if client.client_id is None:
+            raise ValueError("client_id is required")
+        self.tokens[new_access_token] = AccessToken(
+            token=new_access_token,
+            client_id=client.client_id,
+            scopes=scopes or token_info.scopes,
+            expires_at=int(time.time()) + 3600,
+        )
+
+        self.refresh_tokens[new_refresh_token] = new_access_token
+
+        # Remove the old tokens
+        del self.refresh_tokens[refresh_token.token]
+        del self.tokens[old_access_token]
+
+        return OAuthToken(
+            access_token=new_access_token,
+            token_type="Bearer",
+            expires_in=3600,
+            scope=" ".join(scopes) if scopes else " ".join(token_info.scopes),
+            refresh_token=new_refresh_token,
+        )
+
+    async def load_access_token(self, token: str) -> AccessToken | None:
+        token_info = self.tokens.get(token)
+
+        return token_info and AccessToken(
+            token=token,
+            client_id=token_info.client_id,
+            scopes=token_info.scopes,
+            expires_at=token_info.expires_at,
+        )
+
+    async def revoke_token(self, token: AccessToken | RefreshToken) -> None:
+        match token:
+            case RefreshToken():
+                # Remove the refresh token
+                del self.refresh_tokens[token.token]
+
+            case AccessToken():
+                # Remove the access token
+                del self.tokens[token.token]
+
+                # Also remove any refresh tokens that point to this access token
+                for refresh_token, access_token in list(self.refresh_tokens.items()):
+                    if access_token == token.token:
+                        del self.refresh_tokens[refresh_token]
+
+
+@pytest.fixture
+def mock_oauth_provider():
+    return MockOAuthProvider()
+
+
+@pytest.fixture
+def auth_app(mock_oauth_provider):
+    # Create auth router
+    auth_routes = create_auth_routes(
+        mock_oauth_provider,
+        AnyHttpUrl("https://auth.example.com"),
+        AnyHttpUrl("https://docs.example.com"),
+        client_registration_options=ClientRegistrationOptions(
+            enabled=True,
+            valid_scopes=["read", "write", "profile"],
+            default_scopes=["read", "write"],
+        ),
+        revocation_options=RevocationOptions(enabled=True),
+    )
+
+    # Create Starlette app
+    app = Starlette(routes=auth_routes)
+
+    return app
+
+
+@pytest.fixture
+async def test_client(auth_app):
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=auth_app), base_url="https://mcptest.com"
+    ) as client:
+        yield client
+
+
+@pytest.fixture
+async def registered_client(test_client: httpx.AsyncClient, request):
+    """Create and register a test client.
+
+    Parameters can be customized via indirect parameterization:
+    @pytest.mark.parametrize("registered_client",
+                            [{"grant_types": ["authorization_code"]}],
+                            indirect=True)
+    """
+    # Default client metadata
+    client_metadata = {
+        "redirect_uris": ["https://client.example.com/callback"],
+        "client_name": "Test Client",
+        "grant_types": ["authorization_code", "refresh_token"],
+    }
+
+    # Override with any parameters from the test
+    if hasattr(request, "param") and request.param:
+        client_metadata.update(request.param)
+
+    response = await test_client.post("/register", json=client_metadata)
+    assert response.status_code == 201, f"Failed to register client: {response.content}"
+
+    client_info = response.json()
+    return client_info
+
+
+@pytest.fixture
+def pkce_challenge():
+    """Create a PKCE challenge with code_verifier and code_challenge."""
+    code_verifier = "some_random_verifier_string"
+    code_challenge = (
+        base64.urlsafe_b64encode(hashlib.sha256(code_verifier.encode()).digest())
+        .decode()
+        .rstrip("=")
+    )
+
+    return {"code_verifier": code_verifier, "code_challenge": code_challenge}
+
+
+class TestAuthorizeEndpointErrors:
+    """Test error handling in the OAuth authorization endpoint."""
+
+    async def test_authorize_missing_client_id(
+        self, test_client: httpx.AsyncClient, pkce_challenge
+    ):
+        """Test authorization endpoint with missing client_id.
+
+        According to the OAuth2.0 spec, if client_id is missing, the server should
+        inform the resource owner and NOT redirect.
+        """
+        response = await test_client.get(
+            "/authorize",
+            params={
+                "response_type": "code",
+                # Missing client_id
+                "redirect_uri": "https://client.example.com/callback",
+                "state": "test_state",
+                "code_challenge": pkce_challenge["code_challenge"],
+                "code_challenge_method": "S256",
+            },
+        )
+
+        # Should NOT redirect, should show an error page
+        assert response.status_code == 400
+        # The response should include an error message about missing client_id
+        assert "client_id" in response.text.lower()
+
+    async def test_authorize_invalid_client_id(
+        self, test_client: httpx.AsyncClient, pkce_challenge
+    ):
+        """Test authorization endpoint with invalid client_id.
+
+        According to the OAuth2.0 spec, if client_id is invalid, the server should
+        inform the resource owner and NOT redirect.
+        """
+        response = await test_client.get(
+            "/authorize",
+            params={
+                "response_type": "code",
+                "client_id": "invalid_client_id_that_does_not_exist",
+                "redirect_uri": "https://client.example.com/callback",
+                "state": "test_state",
+                "code_challenge": pkce_challenge["code_challenge"],
+                "code_challenge_method": "S256",
+            },
+        )
+
+        # Should NOT redirect, should show an error page
+        assert response.status_code == 400
+        # The response should include an error message about invalid client_id
+        assert "client" in response.text.lower()
+
+    async def test_authorize_missing_redirect_uri(
+        self, test_client: httpx.AsyncClient, registered_client, pkce_challenge
+    ):
+        """Test authorization endpoint with missing redirect_uri.
+
+        If client has only one registered redirect_uri, it can be omitted.
+        """
+
+        response = await test_client.get(
+            "/authorize",
+            params={
+                "response_type": "code",
+                "client_id": registered_client["client_id"],
+                # Missing redirect_uri
+                "code_challenge": pkce_challenge["code_challenge"],
+                "code_challenge_method": "S256",
+                "state": "test_state",
+            },
+        )
+
+        # Should redirect to the registered redirect_uri
+        assert response.status_code == 302, response.content
+        redirect_url = response.headers["location"]
+        assert redirect_url.startswith("https://client.example.com/callback")
+
+    async def test_authorize_invalid_redirect_uri(
+        self, test_client: httpx.AsyncClient, registered_client, pkce_challenge
+    ):
+        """Test authorization endpoint with invalid redirect_uri.
+
+        According to the OAuth2.0 spec, if redirect_uri is invalid or doesn't match,
+        the server should inform the resource owner and NOT redirect.
+        """
+
+        response = await test_client.get(
+            "/authorize",
+            params={
+                "response_type": "code",
+                "client_id": registered_client["client_id"],
+                # Non-matching URI
+                "redirect_uri": "https://attacker.example.com/callback",
+                "code_challenge": pkce_challenge["code_challenge"],
+                "code_challenge_method": "S256",
+                "state": "test_state",
+            },
+        )
+
+        # Should NOT redirect, should show an error page
+        assert response.status_code == 400, response.content
+        # The response should include an error message about redirect_uri mismatch
+        assert "redirect" in response.text.lower()
+
+    @pytest.mark.parametrize(
+        "registered_client",
+        [
+            {
+                "redirect_uris": [
+                    "https://client.example.com/callback",
+                    "https://client.example.com/other-callback",
+                ]
+            }
+        ],
+        indirect=True,
+    )
+    async def test_authorize_missing_redirect_uri_multiple_registered(
+        self, test_client: httpx.AsyncClient, registered_client, pkce_challenge
+    ):
+        """Test endpoint with missing redirect_uri with multiple registered URIs.
+
+        If client has multiple registered redirect_uris, redirect_uri must be provided.
+        """
+
+        response = await test_client.get(
+            "/authorize",
+            params={
+                "response_type": "code",
+                "client_id": registered_client["client_id"],
+                # Missing redirect_uri
+                "code_challenge": pkce_challenge["code_challenge"],
+                "code_challenge_method": "S256",
+                "state": "test_state",
+            },
+        )
+
+        # Should NOT redirect, should return a 400 error
+        assert response.status_code == 400
+        # The response should include an error message about missing redirect_uri
+        assert "redirect_uri" in response.text.lower()
+
+    async def test_authorize_unsupported_response_type(
+        self, test_client: httpx.AsyncClient, registered_client, pkce_challenge
+    ):
+        """Test authorization endpoint with unsupported response_type.
+
+        According to the OAuth2.0 spec, for other errors like unsupported_response_type,
+        the server should redirect with error parameters.
+        """
+
+        response = await test_client.get(
+            "/authorize",
+            params={
+                "response_type": "token",  # Unsupported (we only support "code")
+                "client_id": registered_client["client_id"],
+                "redirect_uri": "https://client.example.com/callback",
+                "code_challenge": pkce_challenge["code_challenge"],
+                "code_challenge_method": "S256",
+                "state": "test_state",
+            },
+        )
+
+        # Should redirect with error parameters
+        assert response.status_code == 302
+        redirect_url = response.headers["location"]
+        parsed_url = urlparse(redirect_url)
+        query_params = parse_qs(parsed_url.query)
+
+        assert "error" in query_params
+        assert query_params["error"][0] == "unsupported_response_type"
+        # State should be preserved
+        assert "state" in query_params
+        assert query_params["state"][0] == "test_state"
+
+    async def test_authorize_missing_response_type(
+        self, test_client: httpx.AsyncClient, registered_client, pkce_challenge
+    ):
+        """Test authorization endpoint with missing response_type.
+
+        Missing required parameter should result in invalid_request error.
+        """
+
+        response = await test_client.get(
+            "/authorize",
+            params={
+                # Missing response_type
+                "client_id": registered_client["client_id"],
+                "redirect_uri": "https://client.example.com/callback",
+                "code_challenge": pkce_challenge["code_challenge"],
+                "code_challenge_method": "S256",
+                "state": "test_state",
+            },
+        )
+
+        # Should redirect with error parameters
+        assert response.status_code == 302
+        redirect_url = response.headers["location"]
+        parsed_url = urlparse(redirect_url)
+        query_params = parse_qs(parsed_url.query)
+
+        assert "error" in query_params
+        assert query_params["error"][0] == "invalid_request"
+        # State should be preserved
+        assert "state" in query_params
+        assert query_params["state"][0] == "test_state"
+
+    async def test_authorize_missing_pkce_challenge(
+        self, test_client: httpx.AsyncClient, registered_client
+    ):
+        """Test authorization endpoint with missing PKCE code_challenge.
+
+        Missing PKCE parameters should result in invalid_request error.
+        """
+        response = await test_client.get(
+            "/authorize",
+            params={
+                "response_type": "code",
+                "client_id": registered_client["client_id"],
+                # Missing code_challenge
+                "state": "test_state",
+                # using default URL
+            },
+        )
+
+        # Should redirect with error parameters
+        assert response.status_code == 302
+        redirect_url = response.headers["location"]
+        parsed_url = urlparse(redirect_url)
+        query_params = parse_qs(parsed_url.query)
+
+        assert "error" in query_params
+        assert query_params["error"][0] == "invalid_request"
+        # State should be preserved
+        assert "state" in query_params
+        assert query_params["state"][0] == "test_state"
+
+    async def test_authorize_invalid_scope(
+        self, test_client: httpx.AsyncClient, registered_client, pkce_challenge
+    ):
+        """Test authorization endpoint with invalid scope.
+
+        Invalid scope should redirect with invalid_scope error.
+        """
+
+        response = await test_client.get(
+            "/authorize",
+            params={
+                "response_type": "code",
+                "client_id": registered_client["client_id"],
+                "redirect_uri": "https://client.example.com/callback",
+                "code_challenge": pkce_challenge["code_challenge"],
+                "code_challenge_method": "S256",
+                "scope": "invalid_scope_that_does_not_exist",
+                "state": "test_state",
+            },
+        )
+
+        # Should redirect with error parameters
+        assert response.status_code == 302
+        redirect_url = response.headers["location"]
+        parsed_url = urlparse(redirect_url)
+        query_params = parse_qs(parsed_url.query)
+
+        assert "error" in query_params
+        assert query_params["error"][0] == "invalid_scope"
+        # State should be preserved
+        assert "state" in query_params
+        assert query_params["state"][0] == "test_state"
diff --git a/tests/server/test_cache_hints.py b/tests/server/test_cache_hints.py
new file mode 100644
index 0000000..c477c19
--- /dev/null
+++ b/tests/server/test_cache_hints.py
@@ -0,0 +1,219 @@
+"""Server-level cache hints (SEP-2549) on the FastMCP constructor.
+
+A FastMCP server opts every SDK-cacheable result it emits into client-side
+caching with `cache_ttl` (seconds) and an optional `cache_scope`. The hint is
+uniform by construction — one server-level value applies to `tools/list`,
+`prompts/list`, `resources/list`, `resources/templates/list`, `resources/read`,
+and `server/discover` alike. FastMCP passes the hint through to the SDK
+low-level `Server(cache_hints=...)`, whose runner fills `ttlMs`/`cacheScope` on
+every cacheable result; FastMCP never hand-sets the wire fields.
+
+The end-to-end tests drive a FastMCP server through a `fastmcp.Client(cache=True)`
+negotiating `2026-07-28`, proving the server-emitted hint and the client cache
+interoperate — the server half of the feature whose client half is exercised in
+`tests/client/client/test_response_cache.py`.
+"""
+
+from __future__ import annotations
+
+import pytest
+from mcp_types.methods import CACHEABLE_METHODS
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.caching import build_cache_hints
+
+
+class TestBuildCacheHints:
+    def test_none_when_no_hint_set(self):
+        assert build_cache_hints(None, None) is None
+
+    def test_covers_every_cacheable_method(self):
+        hints = build_cache_hints(60, "public")
+        assert hints is not None
+        assert set(hints) == set(CACHEABLE_METHODS)
+
+    def test_seconds_converted_to_ms(self):
+        hints = build_cache_hints(60, "public")
+        assert hints is not None
+        hint = hints["tools/list"]
+        assert hint.ttl_ms == 60000
+        assert hint.scope == "public"
+
+    def test_scope_defaults_to_private(self):
+        hints = build_cache_hints(30, None)
+        assert hints is not None
+        assert hints["tools/list"].scope == "private"
+
+    @pytest.mark.parametrize("cache_ttl", [0, -1])
+    def test_non_positive_ttl_rejected(self, cache_ttl):
+        with pytest.raises(ValueError, match="cache_ttl must be a positive integer"):
+            build_cache_hints(cache_ttl, None)
+
+    @pytest.mark.parametrize("scope", ["public", "private"])
+    def test_scope_without_ttl_rejected(self, scope):
+        with pytest.raises(ValueError, match="cache_scope requires cache_ttl"):
+            build_cache_hints(None, scope)
+
+
+class TestConstructorValidation:
+    @pytest.mark.parametrize("cache_ttl", [0, -5])
+    def test_non_positive_ttl_raises(self, cache_ttl):
+        with pytest.raises(ValueError, match="cache_ttl must be a positive integer"):
+            FastMCP("x", cache_ttl=cache_ttl)
+
+    def test_scope_without_ttl_raises(self):
+        with pytest.raises(ValueError, match="cache_scope requires cache_ttl"):
+            FastMCP("x", cache_scope="public")
+
+    def test_no_cache_params_is_valid(self):
+        # A server with no cache params constructs cleanly and emits no hint.
+        FastMCP("x")
+
+
+class TestServerEmitsHints:
+    """A hinted server sets the wire fields the SDK client cache reads."""
+
+    async def test_tools_list_carries_hint(self):
+        mcp = FastMCP("x", cache_ttl=60, cache_scope="public")
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        async with Client(mcp, mode="auto") as client:
+            result = await client.session.list_tools()
+
+        assert result.ttl_ms == 60000
+        assert result.cache_scope == "public"
+
+    async def test_prompts_list_carries_hint(self):
+        mcp = FastMCP("x", cache_ttl=45, cache_scope="public")
+
+        @mcp.prompt
+        def greet(name: str) -> str:
+            return f"Hello, {name}"
+
+        async with Client(mcp, mode="auto") as client:
+            result = await client.session.list_prompts()
+
+        assert result.ttl_ms == 45000
+        assert result.cache_scope == "public"
+
+    async def test_resources_list_and_read_carry_hint(self):
+        mcp = FastMCP("x", cache_ttl=120, cache_scope="public")
+
+        @mcp.resource("data://config")
+        def config() -> str:
+            return "value"
+
+        async with Client(mcp, mode="auto") as client:
+            listing = await client.session.list_resources()
+            read = await client.session.read_resource("data://config")
+
+        assert listing.ttl_ms == 120000
+        assert listing.cache_scope == "public"
+        assert read.ttl_ms == 120000
+        assert read.cache_scope == "public"
+
+    async def test_resource_templates_list_carries_hint(self):
+        mcp = FastMCP("x", cache_ttl=90)
+
+        @mcp.resource("data://{key}/value")
+        def item(key: str) -> str:
+            return key
+
+        async with Client(mcp, mode="auto") as client:
+            listing = await client.session.list_resource_templates()
+
+        assert listing.ttl_ms == 90000
+
+    async def test_scope_defaults_to_private(self):
+        mcp = FastMCP("x", cache_ttl=30)
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        async with Client(mcp, mode="auto") as client:
+            result = await client.session.list_tools()
+
+        assert result.ttl_ms == 30000
+        assert result.cache_scope == "private"
+
+
+class TestEndToEndInterop:
+    """A FastMCP server + `fastmcp.Client(cache=True)`: a hinted listing serves
+    from the cache with no second wire request, an unhinted one does not."""
+
+    async def test_hinted_list_tools_served_from_cache(self):
+        mcp = FastMCP("x", cache_ttl=60, cache_scope="public")
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        async with Client(mcp, mode="auto", cache=True) as client:
+            await client.list_tools()
+
+            calls = {"n": 0}
+            original = client.session.list_tools
+
+            async def spy(**kwargs):
+                calls["n"] += 1
+                return await original(**kwargs)
+
+            client.session.list_tools = spy  # type: ignore[method-assign]
+            second = await client.list_tools()
+
+        assert calls["n"] == 0  # served from cache, no second wire request
+        assert [t.name for t in second] == ["add"]
+
+    async def test_unhinted_server_not_cached(self):
+        mcp = FastMCP("x")
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        async with Client(mcp, mode="auto", cache=True) as client:
+            await client.list_tools()
+
+            calls = {"n": 0}
+            original = client.session.list_tools
+
+            async def spy(**kwargs):
+                calls["n"] += 1
+                return await original(**kwargs)
+
+            client.session.list_tools = spy  # type: ignore[method-assign]
+            await client.list_tools()
+
+        assert calls["n"] == 1  # nothing cached, a second wire request happens
+
+    async def test_private_scope_respected(self):
+        mcp = FastMCP("x", cache_ttl=60, cache_scope="private")
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        async with Client(mcp, mode="auto") as client:
+            result = await client.session.list_tools()
+
+        assert result.ttl_ms == 60000
+        assert result.cache_scope == "private"
+
+    async def test_hinted_read_resource_carries_cacheable_fields(self):
+        """The server sets the wire fields the SDK client cache reads on a
+        `resources/read` result, so a cache-capable client can reuse it."""
+        mcp = FastMCP("x", cache_ttl=120, cache_scope="public")
+
+        @mcp.resource("data://config")
+        def config() -> str:
+            return "value"
+
+        async with Client(mcp, mode="auto", cache=True) as client:
+            result = await client.session.read_resource("data://config")
+
+        assert result.ttl_ms == 120000
+        assert result.cache_scope == "public"
diff --git a/tests/server/test_context.py b/tests/server/test_context.py
new file mode 100644
index 0000000..142287b
--- /dev/null
+++ b/tests/server/test_context.py
@@ -0,0 +1,519 @@
+from unittest.mock import MagicMock
+
+import pytest
+from mcp_types import ModelPreferences
+
+from fastmcp.server.context import (
+    Context,
+    reset_transport,
+    set_transport,
+)
+from fastmcp.server.sampling.run import _parse_model_preferences
+from fastmcp.server.server import FastMCP
+
+
+@pytest.fixture
+def context():
+    return Context(fastmcp=FastMCP())
+
+
+class TestParseModelPreferences:
+    def test_parse_model_preferences_string(self, context):
+        mp = _parse_model_preferences("claude-haiku-4-5")
+        assert isinstance(mp, ModelPreferences)
+        assert mp.hints is not None
+        assert mp.hints[0].name == "claude-haiku-4-5"
+
+    def test_parse_model_preferences_list(self, context):
+        mp = _parse_model_preferences(["claude-haiku-4-5", "claude"])
+        assert isinstance(mp, ModelPreferences)
+        assert mp.hints is not None
+        assert [h.name for h in mp.hints] == ["claude-haiku-4-5", "claude"]
+
+    def test_parse_model_preferences_object(self, context):
+        obj = ModelPreferences(hints=[])
+        assert _parse_model_preferences(obj) is obj
+
+    def test_parse_model_preferences_invalid_type(self, context):
+        with pytest.raises(ValueError):
+            _parse_model_preferences(model_preferences=123)  # pyright: ignore[reportArgumentType] # type: ignore[invalid-argument-type]  # ty:ignore[invalid-argument-type]
+
+
+class TestSessionId:
+    def test_session_id_with_http_headers(self, context):
+        """Test that session_id returns the value from mcp-session-id header."""
+        from fastmcp.server.dependencies import (
+            FastMCPRequestContext,
+            fastmcp_request_ctx,
+        )
+
+        mock_headers = {"mcp-session-id": "test-session-123"}
+
+        token = fastmcp_request_ctx.set(
+            FastMCPRequestContext(
+                session=MagicMock(wraps={}),
+                request_id="0",
+                meta=None,
+                request=MagicMock(headers=mock_headers),
+                protocol_version="2025-06-18",
+                close_sse_stream=None,
+                lifespan_context=MagicMock(),
+                _srctx=MagicMock(meta=None),
+            )
+        )
+
+        try:
+            assert context.session_id == "test-session-123"
+        finally:
+            fastmcp_request_ctx.reset(token)
+
+    def test_session_id_without_http_headers(self, context):
+        """Test that session_id returns a UUID when no HTTP headers are available.
+
+        For STDIO/SSE/in-memory transports, we generate a UUID and cache it
+        on the session for consistency with state operations.
+        """
+        import uuid
+
+        from fastmcp.server.dependencies import (
+            FastMCPRequestContext,
+            fastmcp_request_ctx,
+        )
+
+        mock_session = MagicMock(wraps={})
+        token = fastmcp_request_ctx.set(
+            FastMCPRequestContext(
+                session=mock_session,
+                request_id="0",
+                meta=None,
+                request=None,
+                protocol_version="2025-06-18",
+                close_sse_stream=None,
+                lifespan_context=MagicMock(),
+                _srctx=MagicMock(meta=None),
+            )
+        )
+
+        try:
+            # session_id should be a valid UUID for non-HTTP transports
+            session_id = context.session_id
+            assert uuid.UUID(session_id)  # Valid UUID format
+            # Should be cached on session
+            assert mock_session._fastmcp_state_prefix == session_id
+        finally:
+            fastmcp_request_ctx.reset(token)
+
+
+class TestContextState:
+    """Test suite for Context state functionality."""
+
+    async def test_context_state_basic(self):
+        """Test basic get/set/delete state operations."""
+        server = FastMCP("test")
+        mock_session = MagicMock()  # Use same session for consistent id()
+
+        async with Context(fastmcp=server, session=mock_session) as context:
+            # Initially empty
+            assert await context.get_state("test1") is None
+            assert await context.get_state("test2") is None
+
+            # Set values
+            await context.set_state("test1", "value")
+            await context.set_state("test2", 2)
+
+            # Retrieve values
+            assert await context.get_state("test1") == "value"
+            assert await context.get_state("test2") == 2
+
+            # Update value
+            await context.set_state("test1", "new_value")
+            assert await context.get_state("test1") == "new_value"
+
+            # Delete value
+            await context.delete_state("test1")
+            assert await context.get_state("test1") is None
+
+    async def test_context_state_session_isolation(self):
+        """Test that different sessions have isolated state."""
+        server = FastMCP("test")
+        session_a = MagicMock()
+        session_b = MagicMock()
+
+        async with Context(fastmcp=server, session=session_a) as context1:
+            await context1.set_state("key", "value-from-A")
+
+        async with Context(fastmcp=server, session=session_b) as context2:
+            # Session B should not see session A's state
+            assert await context2.get_state("key") is None
+            await context2.set_state("key", "value-from-B")
+            assert await context2.get_state("key") == "value-from-B"
+
+        # Verify session A's state is still intact
+        async with Context(fastmcp=server, session=session_a) as context3:
+            assert await context3.get_state("key") == "value-from-A"
+
+    async def test_context_state_persists_across_requests(self):
+        """Test that state persists across multiple context instances (requests)."""
+        server = FastMCP("test")
+        mock_session = MagicMock()  # Same session = same id()
+
+        # First request sets state
+        async with Context(fastmcp=server, session=mock_session) as context1:
+            await context1.set_state("counter", 1)
+
+        # Second request in same session sees the state
+        async with Context(fastmcp=server, session=mock_session) as context2:
+            counter = await context2.get_state("counter")
+            assert counter == 1
+            await context2.set_state("counter", counter + 1)
+
+        # Third request sees updated state
+        async with Context(fastmcp=server, session=mock_session) as context3:
+            assert await context3.get_state("counter") == 2
+
+    async def test_context_state_nested_contexts_share_state(self):
+        """Test that nested contexts within the same session share state."""
+        server = FastMCP("test")
+        mock_session = MagicMock()
+
+        async with Context(fastmcp=server, session=mock_session) as context1:
+            await context1.set_state("key", "outer-value")
+
+            async with Context(fastmcp=server, session=mock_session) as context2:
+                # Nested context sees same state (same session)
+                assert await context2.get_state("key") == "outer-value"
+
+                # Nested context can modify shared state
+                await context2.set_state("key", "inner-value")
+
+            # Outer context sees the modification
+            assert await context1.get_state("key") == "inner-value"
+
+    async def test_two_clients_same_key_isolated_by_session(self):
+        """Test that two different clients can store the same key independently.
+
+        Each client gets an auto-generated session ID, and their state is isolated.
+        """
+        import json
+
+        from fastmcp import Client
+
+        server = FastMCP("test")
+        stored_session_ids: list[str] = []
+
+        @server.tool
+        async def store_and_read(value: str, ctx: Context) -> dict:
+            """Store a value and return all state info."""
+            stored_session_ids.append(ctx.session_id)
+            existing = await ctx.get_state("shared_key")
+            await ctx.set_state("shared_key", value)
+            new_value = await ctx.get_state("shared_key")
+            return {
+                "session_id": ctx.session_id,
+                "existing_value": existing,
+                "new_value": new_value,
+            }
+
+        # Client 1 stores "value-from-client-1"
+        async with Client(server) as client1:
+            result1 = await client1.call_tool(
+                "store_and_read", {"value": "value-from-client-1"}
+            )
+            data1 = json.loads(result1.content[0].text)
+            assert data1["existing_value"] is None  # First write
+            assert data1["new_value"] == "value-from-client-1"
+            session_id_1 = data1["session_id"]
+
+        # Client 2 stores "value-from-client-2" with the SAME key
+        async with Client(server) as client2:
+            result2 = await client2.call_tool(
+                "store_and_read", {"value": "value-from-client-2"}
+            )
+            data2 = json.loads(result2.content[0].text)
+            # Client 2 should NOT see client 1's value (different session)
+            assert data2["existing_value"] is None
+            assert data2["new_value"] == "value-from-client-2"
+            session_id_2 = data2["session_id"]
+
+        # Verify session IDs were auto-generated and are different
+        assert session_id_1 is not None
+        assert session_id_2 is not None
+        assert session_id_1 != session_id_2
+
+        # Client 1 reconnects and should still see their value
+        async with Client(server) as client1_again:
+            # But this is a NEW session (new connection = new session ID)
+            result3 = await client1_again.call_tool(
+                "store_and_read", {"value": "value-from-client-1-again"}
+            )
+            data3 = json.loads(result3.content[0].text)
+            # New session, so existing value is None
+            assert data3["existing_value"] is None
+            assert data3["session_id"] != session_id_1  # Different session
+
+
+class TestContextStateSerializable:
+    """Tests for the serializable parameter on set_state."""
+
+    async def test_set_state_serializable_false_stores_arbitrary_objects(self):
+        """Non-serializable objects can be stored with serializable=False."""
+        server = FastMCP("test")
+        mock_session = MagicMock()
+
+        class MyClient:
+            def __init__(self):
+                self.connected = True
+
+        client = MyClient()
+
+        async with Context(fastmcp=server, session=mock_session) as context:
+            await context.set_state("client", client, serializable=False)
+            result = await context.get_state("client")
+            assert result is client
+            assert result.connected is True
+
+    async def test_set_state_serializable_false_does_not_persist_across_requests(self):
+        """Non-serializable state is request-scoped and gone in a new context."""
+        server = FastMCP("test")
+        mock_session = MagicMock()
+
+        async with Context(fastmcp=server, session=mock_session) as context:
+            await context.set_state("key", object(), serializable=False)
+            assert await context.get_state("key") is not None
+
+        async with Context(fastmcp=server, session=mock_session) as context:
+            assert await context.get_state("key") is None
+
+    async def test_set_state_serializable_true_rejects_non_serializable(self):
+        """Default set_state raises TypeError for non-serializable values."""
+        server = FastMCP("test")
+        mock_session = MagicMock()
+
+        async with Context(fastmcp=server, session=mock_session) as context:
+            with pytest.raises(TypeError, match="serializable=False"):
+                await context.set_state("key", object())
+
+    async def test_set_state_serializable_false_shadows_session_state(self):
+        """Request-scoped state shadows session-scoped state for the same key."""
+        server = FastMCP("test")
+        mock_session = MagicMock()
+
+        async with Context(fastmcp=server, session=mock_session) as context:
+            await context.set_state("key", "session-value")
+            assert await context.get_state("key") == "session-value"
+
+            await context.set_state("key", "request-value", serializable=False)
+            assert await context.get_state("key") == "request-value"
+
+    async def test_delete_state_removes_from_both_stores(self):
+        """delete_state clears both request-scoped and session-scoped values."""
+        server = FastMCP("test")
+        mock_session = MagicMock()
+
+        async with Context(fastmcp=server, session=mock_session) as context:
+            await context.set_state("key", "session-value")
+            await context.set_state("key", "request-value", serializable=False)
+            assert await context.get_state("key") == "request-value"
+
+            await context.delete_state("key")
+            assert await context.get_state("key") is None
+
+    async def test_serializable_state_still_persists_across_requests(self):
+        """Serializable state (default) still persists across requests."""
+        server = FastMCP("test")
+        mock_session = MagicMock()
+
+        async with Context(fastmcp=server, session=mock_session) as context:
+            await context.set_state("key", "persistent")
+
+        async with Context(fastmcp=server, session=mock_session) as context:
+            assert await context.get_state("key") == "persistent"
+
+    async def test_serializable_write_clears_request_scoped_shadow(self):
+        """Writing serializable state clears any request-scoped shadow for the same key."""
+        server = FastMCP("test")
+        mock_session = MagicMock()
+
+        async with Context(fastmcp=server, session=mock_session) as context:
+            await context.set_state("key", "request-value", serializable=False)
+            assert await context.get_state("key") == "request-value"
+
+            # Serializable write should clear the shadow
+            await context.set_state("key", "session-value")
+            assert await context.get_state("key") == "session-value"
+
+
+class TestContextMeta:
+    """Test suite for Context meta functionality."""
+
+    def test_request_context_meta_access(self, context):
+        """Test that the lifted _meta dict is accessible from request context.
+
+        In the v2 SDK port the wrapper's ``meta`` is the raw ``_meta`` block
+        lifted from the request params (a dict), not a typed object.
+        """
+        from fastmcp.server.dependencies import (
+            FastMCPRequestContext,
+            fastmcp_request_ctx,
+        )
+
+        meta_dict = {
+            "user_id": "user-123",
+            "trace_id": "trace-456",
+            "custom_field": "custom-value",
+        }
+
+        token = fastmcp_request_ctx.set(
+            FastMCPRequestContext(
+                session=MagicMock(wraps={}),
+                request_id="0",
+                meta=meta_dict,
+                request=None,
+                protocol_version="2025-06-18",
+                close_sse_stream=None,
+                lifespan_context=MagicMock(),
+                _srctx=MagicMock(meta=None),
+            )
+        )
+
+        retrieved_meta = context.request_context.meta
+        assert retrieved_meta is not None
+        assert retrieved_meta["user_id"] == "user-123"
+        assert retrieved_meta["trace_id"] == "trace-456"
+        assert retrieved_meta["custom_field"] == "custom-value"
+
+        fastmcp_request_ctx.reset(token)
+
+    def test_request_context_meta_none(self, context):
+        """Test that context handles None meta gracefully."""
+        from fastmcp.server.dependencies import (
+            FastMCPRequestContext,
+            fastmcp_request_ctx,
+        )
+
+        token = fastmcp_request_ctx.set(
+            FastMCPRequestContext(
+                session=MagicMock(wraps={}),
+                request_id="0",
+                meta=None,
+                request=None,
+                protocol_version="2025-06-18",
+                close_sse_stream=None,
+                lifespan_context=MagicMock(),
+                _srctx=MagicMock(meta=None),
+            )
+        )
+
+        retrieved_meta = context.request_context.meta
+        assert retrieved_meta is None
+
+        fastmcp_request_ctx.reset(token)
+
+
+class TestTransport:
+    """Test suite for Context transport property."""
+
+    def test_transport_returns_none_outside_server_context(self, context):
+        """Test that transport returns None when not in a server context."""
+        assert context.transport is None
+
+    def test_transport_returns_stdio(self, context):
+        """Test that transport returns 'stdio' when set."""
+        token = set_transport("stdio")
+        try:
+            assert context.transport == "stdio"
+        finally:
+            reset_transport(token)
+
+    def test_transport_returns_sse(self, context):
+        """Test that transport returns 'sse' when set."""
+        token = set_transport("sse")
+        try:
+            assert context.transport == "sse"
+        finally:
+            reset_transport(token)
+
+    def test_transport_returns_streamable_http(self, context):
+        """Test that transport returns 'streamable-http' when set."""
+        token = set_transport("streamable-http")
+        try:
+            assert context.transport == "streamable-http"
+        finally:
+            reset_transport(token)
+
+    def test_transport_reset(self, context):
+        """Test that transport resets correctly."""
+        assert context.transport is None
+        token = set_transport("stdio")
+        assert context.transport == "stdio"
+        reset_transport(token)
+        assert context.transport is None
+
+
+class TestTransportIntegration:
+    """Integration tests for transport property with actual server/client."""
+
+    async def test_transport_in_tool_via_client(self):
+        """Test that transport is accessible from within a tool via Client."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+        observed_transport = None
+
+        @mcp.tool
+        def get_transport(ctx: Context) -> str:
+            nonlocal observed_transport
+            observed_transport = ctx.transport
+            return observed_transport or "none"
+
+        # Client uses in-memory transport which doesn't set transport type
+        # so we expect None here (the transport is only set by run_* methods)
+        async with Client(mcp) as client:
+            result = await client.call_tool("get_transport", {})
+            assert observed_transport is None
+            assert result.data == "none"
+
+    async def test_transport_set_manually_is_visible_in_tool(self):
+        """Test that manually set transport is visible from within a tool."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+        observed_transport = None
+
+        @mcp.tool
+        def get_transport(ctx: Context) -> str:
+            nonlocal observed_transport
+            observed_transport = ctx.transport
+            return observed_transport or "none"
+
+        # Manually set transport before running
+        token = set_transport("stdio")
+        try:
+            async with Client(mcp) as client:
+                result = await client.call_tool("get_transport", {})
+                assert observed_transport == "stdio"
+                assert result.data == "stdio"
+        finally:
+            reset_transport(token)
+
+    async def test_transport_set_via_http_middleware(self):
+        """Test that transport is set per-request via HTTP middleware."""
+        from fastmcp import Client
+        from fastmcp.client.transports import StreamableHttpTransport
+        from fastmcp.utilities.tests import run_server_async
+
+        mcp = FastMCP("test")
+        observed_transport = None
+
+        @mcp.tool
+        def get_transport(ctx: Context) -> str:
+            nonlocal observed_transport
+            observed_transport = ctx.transport
+            return observed_transport or "none"
+
+        async with run_server_async(mcp, transport="streamable-http") as url:
+            transport = StreamableHttpTransport(url=url)
+            async with Client(transport=transport) as client:
+                result = await client.call_tool("get_transport", {})
+                assert observed_transport == "streamable-http"
+                assert result.data == "streamable-http"
diff --git a/tests/server/test_dependencies.py b/tests/server/test_dependencies.py
new file mode 100644
index 0000000..818cbac
--- /dev/null
+++ b/tests/server/test_dependencies.py
@@ -0,0 +1,1236 @@
+"""Tests for Docket-style dependency injection in FastMCP."""
+
+from contextlib import asynccontextmanager, contextmanager
+
+import pytest
+from mcp_types import TextContent, TextResourceContents
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.dependencies import CurrentContext, Depends, Shared
+from fastmcp.server.context import Context
+from fastmcp.server.dependencies import is_docket_available
+from tests.conftest import make_server_request_context
+
+HUZZAH = "huzzah!"
+
+
+class Connection:
+    """Test connection that tracks whether it's currently open."""
+
+    def __init__(self):
+        self.is_open = False
+
+    async def __aenter__(self):
+        self.is_open = True
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        self.is_open = False
+
+
+@asynccontextmanager
+async def get_connection():
+    """Dependency that provides an open connection."""
+    async with Connection() as conn:
+        yield conn
+
+
+@pytest.fixture
+def mcp():
+    """Create a FastMCP server for testing."""
+    return FastMCP("test-server")
+
+
+async def test_depends_with_sync_function(mcp: FastMCP):
+    """Test that Depends works with sync dependency functions."""
+
+    def get_config() -> dict[str, str]:
+        return {"api_key": "secret123", "endpoint": "https://api.example.com"}
+
+    @mcp.tool()
+    def fetch_data(query: str, config: dict[str, str] = Depends(get_config)) -> str:
+        return (
+            f"Fetching '{query}' from {config['endpoint']} with key {config['api_key']}"
+        )
+
+    result = await mcp.call_tool("fetch_data", {"query": "users"})
+    assert result.structured_content is not None
+    text = result.structured_content["result"]
+    assert "Fetching 'users' from https://api.example.com" in text
+    assert "secret123" in text
+
+
+async def test_depends_with_async_function(mcp: FastMCP):
+    """Test that Depends works with async dependency functions."""
+
+    async def get_user_id() -> int:
+        return 42
+
+    @mcp.tool()
+    async def greet_user(name: str, user_id: int = Depends(get_user_id)) -> str:
+        return f"Hello {name}, your ID is {user_id}"
+
+    result = await mcp.call_tool("greet_user", {"name": "Alice"})
+    assert result.structured_content is not None
+    assert result.structured_content["result"] == "Hello Alice, your ID is 42"
+
+
+async def test_depends_with_async_context_manager(mcp: FastMCP):
+    """Test that Depends works with async context managers for resource management."""
+    cleanup_called = False
+
+    @asynccontextmanager
+    async def get_database():
+        db = "db_connection"
+        try:
+            yield db
+        finally:
+            nonlocal cleanup_called
+            cleanup_called = True
+
+    @mcp.tool()
+    async def query_db(sql: str, db: str = Depends(get_database)) -> str:
+        return f"Executing '{sql}' on {db}"
+
+    result = await mcp.call_tool("query_db", {"sql": "SELECT * FROM users"})
+    assert result.structured_content is not None
+    assert (
+        "Executing 'SELECT * FROM users' on db_connection"
+        in result.structured_content["result"]
+    )
+    assert cleanup_called
+
+
+async def test_nested_dependencies(mcp: FastMCP):
+    """Test that dependencies can depend on other dependencies."""
+
+    def get_base_url() -> str:
+        return "https://api.example.com"
+
+    def get_api_client(base_url: str = Depends(get_base_url)) -> dict[str, str]:
+        return {"base_url": base_url, "version": "v1"}
+
+    @mcp.tool()
+    async def call_api(
+        endpoint: str, client: dict[str, str] = Depends(get_api_client)
+    ) -> str:
+        return f"Calling {client['base_url']}/{client['version']}/{endpoint}"
+
+    result = await mcp.call_tool("call_api", {"endpoint": "users"})
+    assert result.structured_content is not None
+    assert (
+        result.structured_content["result"]
+        == "Calling https://api.example.com/v1/users"
+    )
+
+
+async def test_dependencies_excluded_from_schema(mcp: FastMCP):
+    """Test that dependency parameters don't appear in the tool schema."""
+
+    def get_config() -> dict[str, str]:
+        return {"key": "value"}
+
+    @mcp.tool()
+    async def my_tool(
+        name: str, age: int, config: dict[str, str] = Depends(get_config)
+    ) -> str:
+        return f"{name} is {age} years old"
+
+    result = await mcp._on_list_tools(make_server_request_context(), None)
+    tool = next(t for t in result.tools if t.name == "my_tool")
+
+    assert "name" in tool.input_schema["properties"]
+    assert "age" in tool.input_schema["properties"]
+    assert "config" not in tool.input_schema["properties"]
+    assert len(tool.input_schema["properties"]) == 2
+
+
+async def test_current_context_dependency(mcp: FastMCP):
+    """Test that CurrentContext dependency provides access to FastMCP Context."""
+
+    @mcp.tool()
+    def use_context(ctx: Context = CurrentContext()) -> str:
+        assert isinstance(ctx, Context)
+        return HUZZAH
+
+    result = await mcp.call_tool("use_context", {})
+    assert result.structured_content is not None
+    assert result.structured_content["result"] == HUZZAH
+
+
+async def test_current_context_and_legacy_context_coexist(mcp: FastMCP):
+    """Test that CurrentContext dependency and legacy Context injection work together."""
+
+    @mcp.tool()
+    def use_both_contexts(
+        legacy_ctx: Context,
+        dep_ctx: Context = CurrentContext(),
+    ) -> str:
+        assert isinstance(legacy_ctx, Context)
+        assert isinstance(dep_ctx, Context)
+        assert legacy_ctx is dep_ctx
+        return HUZZAH
+
+    result = await mcp.call_tool("use_both_contexts", {})
+    assert result.structured_content is not None
+    assert result.structured_content["result"] == HUZZAH
+
+
+async def test_backward_compat_context_still_works(mcp: FastMCP):
+    """Test that existing Context injection via type annotation still works."""
+
+    @mcp.tool()
+    async def get_request_id(ctx: Context) -> str:
+        return ctx.request_id
+
+    async with Client(mcp) as client:
+        result = await client.call_tool("get_request_id", {})
+        assert len(result.content) == 1
+        content = result.content[0]
+        assert isinstance(content, TextContent)
+        assert len(content.text) > 0
+
+
+async def test_sync_tool_with_async_dependency(mcp: FastMCP):
+    """Test that sync tools work with async dependencies."""
+
+    async def fetch_config() -> str:
+        return "loaded_config"
+
+    @mcp.tool()
+    def process_data(value: int, config: str = Depends(fetch_config)) -> str:
+        return f"Processing {value} with {config}"
+
+    result = await mcp.call_tool("process_data", {"value": 100})
+    assert result.structured_content is not None
+    assert result.structured_content["result"] == "Processing 100 with loaded_config"
+
+
+async def test_dependency_caching(mcp: FastMCP):
+    """Test that dependencies are cached within a single tool call."""
+    call_count = 0
+
+    def expensive_dependency() -> int:
+        nonlocal call_count
+        call_count += 1
+        return 42
+
+    @mcp.tool()
+    async def tool_with_cached_dep(
+        dep1: int = Depends(expensive_dependency),
+        dep2: int = Depends(expensive_dependency),
+    ) -> str:
+        return f"{dep1} + {dep2} = {dep1 + dep2}"
+
+    result = await mcp.call_tool("tool_with_cached_dep", {})
+    assert result.structured_content is not None
+    assert result.structured_content["result"] == "42 + 42 = 84"
+    assert call_count == 1
+
+
+async def test_context_and_depends_together(mcp: FastMCP):
+    """Test that Context type injection and Depends can be used together."""
+
+    def get_multiplier() -> int:
+        return 10
+
+    @mcp.tool()
+    async def mixed_deps(
+        value: int, ctx: Context, multiplier: int = Depends(get_multiplier)
+    ) -> str:
+        assert isinstance(ctx, Context)
+        assert ctx.request_id
+        assert len(ctx.request_id) > 0
+        return (
+            f"Request {ctx.request_id}: {value} * {multiplier} = {value * multiplier}"
+        )
+
+    async with Client(mcp) as client:
+        result = await client.call_tool("mixed_deps", {"value": 5})
+        assert len(result.content) == 1
+        content = result.content[0]
+        assert isinstance(content, TextContent)
+        assert "5 * 10 = 50" in content.text
+        assert "Request " in content.text
+
+
+async def test_resource_with_dependency(mcp: FastMCP):
+    """Test that resources support dependency injection."""
+
+    def get_storage_path() -> str:
+        return "/data/config"
+
+    @mcp.resource("config://settings")
+    async def get_settings(storage: str = Depends(get_storage_path)) -> str:
+        return f"Settings loaded from {storage}"
+
+    result = await mcp.read_resource("config://settings")
+    assert len(result.contents) == 1
+    assert result.contents[0].content == "Settings loaded from /data/config"
+
+
+async def test_resource_with_context_and_dependency(mcp: FastMCP):
+    """Test that resources can use both Context and Depends."""
+
+    def get_prefix() -> str:
+        return "DATA"
+
+    @mcp.resource("config://info")
+    async def get_info(ctx: Context, prefix: str = Depends(get_prefix)) -> str:
+        return f"{prefix}: Request {ctx.request_id}"
+
+    async with Client(mcp) as client:
+        result = await client.read_resource("config://info")
+        assert len(result) == 1
+        content = result[0]
+        assert isinstance(content, TextResourceContents)
+        assert "DATA: Request " in content.text
+        assert len(content.text.split("Request ")[1]) > 0
+
+
+async def test_prompt_with_dependency(mcp: FastMCP):
+    """Test that prompts support dependency injection."""
+
+    def get_tone() -> str:
+        return "friendly and helpful"
+
+    @mcp.prompt()
+    async def custom_prompt(topic: str, tone: str = Depends(get_tone)) -> str:
+        return f"Write about {topic} in a {tone} tone"
+
+    result = await mcp.render_prompt("custom_prompt", {"topic": "Python"})
+    assert len(result.messages) == 1
+    message = result.messages[0]
+    content = message.content
+    assert isinstance(content, TextContent)
+    assert content.text == "Write about Python in a friendly and helpful tone"
+
+
+async def test_prompt_with_context_and_dependency(mcp: FastMCP):
+    """Test that prompts can use both Context and Depends."""
+
+    def get_style() -> str:
+        return "concise"
+
+    @mcp.prompt()
+    async def styled_prompt(
+        query: str, ctx: Context, style: str = Depends(get_style)
+    ) -> str:
+        assert isinstance(ctx, Context)
+        assert ctx.request_id
+        return f"Answer '{query}' in a {style} style"
+
+    async with Client(mcp) as client:
+        result = await client.get_prompt("styled_prompt", {"query": "What is MCP?"})
+        assert len(result.messages) == 1
+        message = result.messages[0]
+        content = message.content
+        assert isinstance(content, TextContent)
+        assert content.text == "Answer 'What is MCP?' in a concise style"
+
+
+async def test_resource_template_with_dependency(mcp: FastMCP):
+    """Test that resource templates support dependency injection."""
+
+    def get_base_path() -> str:
+        return "/var/data"
+
+    @mcp.resource("data://{filename}")
+    async def get_file(filename: str, base_path: str = Depends(get_base_path)) -> str:
+        return f"Reading {base_path}/{filename}"
+
+    result = await mcp.read_resource("data://config.txt")
+    assert len(result.contents) == 1
+    assert result.contents[0].content == "Reading /var/data/config.txt"
+
+
+async def test_resource_template_with_context_and_dependency(mcp: FastMCP):
+    """Test that resource templates can use both Context and Depends."""
+
+    def get_version() -> str:
+        return "v2"
+
+    @mcp.resource("api://{endpoint}")
+    async def call_endpoint(
+        endpoint: str, ctx: Context, version: str = Depends(get_version)
+    ) -> str:
+        assert isinstance(ctx, Context)
+        assert ctx.request_id
+        return f"Calling {version}/{endpoint}"
+
+    async with Client(mcp) as client:
+        result = await client.read_resource("api://users")
+        assert len(result) == 1
+        content = result[0]
+        assert isinstance(content, TextResourceContents)
+        assert content.text == "Calling v2/users"
+
+
+async def test_async_tool_context_manager_stays_open(mcp: FastMCP):
+    """Test that context manager dependencies stay open during async tool execution.
+
+    Context managers must remain open while the async function executes, not just
+    while it's being called (which only returns a coroutine).
+    """
+
+    @mcp.tool()
+    async def query_data(
+        query: str,
+        connection: Connection = Depends(get_connection),
+    ) -> str:
+        assert connection.is_open
+        return f"open={connection.is_open}"
+
+    result = await mcp.call_tool("query_data", {"query": "test"})
+    assert result.structured_content is not None
+    assert result.structured_content["result"] == "open=True"
+
+
+async def test_async_resource_context_manager_stays_open(mcp: FastMCP):
+    """Test that context manager dependencies stay open during async resource execution."""
+
+    @mcp.resource("data://config")
+    async def load_config(connection: Connection = Depends(get_connection)) -> str:
+        assert connection.is_open
+        return f"open={connection.is_open}"
+
+    result = await mcp.read_resource("data://config")
+    assert result.contents[0].content == "open=True"
+
+
+async def test_async_resource_template_context_manager_stays_open(mcp: FastMCP):
+    """Test that context manager dependencies stay open during async resource template execution."""
+
+    @mcp.resource("user://{user_id}")
+    async def get_user(
+        user_id: str,
+        connection: Connection = Depends(get_connection),
+    ) -> str:
+        assert connection.is_open
+        return f"open={connection.is_open},user={user_id}"
+
+    result = await mcp.read_resource("user://123")
+    assert isinstance(result.contents[0].content, str)
+    assert "open=True" in result.contents[0].content
+
+
+async def test_async_prompt_context_manager_stays_open(mcp: FastMCP):
+    """Test that context manager dependencies stay open during async prompt execution."""
+
+    @mcp.prompt()
+    async def research_prompt(
+        topic: str,
+        connection: Connection = Depends(get_connection),
+    ) -> str:
+        assert connection.is_open
+        return f"open={connection.is_open},topic={topic}"
+
+    result = await mcp.render_prompt("research_prompt", {"topic": "AI"})
+    message = result.messages[0]
+    content = message.content
+    assert isinstance(content, TextContent)
+    assert "open=True" in content.text
+
+
+async def test_argument_validation_with_dependencies(mcp: FastMCP):
+    """Test that user arguments are still validated when dependencies are present."""
+
+    def get_config() -> dict[str, str]:
+        return {"key": "value"}
+
+    @mcp.tool()
+    async def validated_tool(
+        age: int,  # Should validate type
+        config: dict[str, str] = Depends(get_config),
+    ) -> str:
+        return f"age={age}"
+
+    # Valid argument
+    result = await mcp.call_tool("validated_tool", {"age": 25})
+    assert result.structured_content is not None
+    assert result.structured_content["result"] == "age=25"
+
+    # Invalid argument type should fail validation. Argument-validation errors
+    # surface as fastmcp's ValidationError (see #4128), not raw pydantic.
+    from fastmcp.exceptions import ValidationError
+
+    with pytest.raises(ValidationError):
+        await mcp.call_tool("validated_tool", {"age": "not a number"})
+
+
+async def test_connection_dependency_excluded_from_tool_schema(mcp: FastMCP):
+    """Test that Connection dependency parameter is excluded from tool schema."""
+
+    @mcp.tool()
+    async def with_connection(
+        name: str,
+        connection: Connection = Depends(get_connection),
+    ) -> str:
+        return name
+
+    result = await mcp._on_list_tools(make_server_request_context(), None)
+    tool = next(t for t in result.tools if t.name == "with_connection")
+
+    assert "name" in tool.input_schema["properties"]
+    assert "connection" not in tool.input_schema["properties"]
+
+
+async def test_sync_tool_context_manager_stays_open(mcp: FastMCP):
+    """Test that sync context manager dependencies work with tools."""
+    conn = Connection()
+
+    @contextmanager
+    def get_sync_connection():
+        conn.is_open = True
+        try:
+            yield conn
+        finally:
+            conn.is_open = False
+
+    @mcp.tool()
+    async def query_sync(
+        query: str,
+        connection: Connection = Depends(get_sync_connection),
+    ) -> str:
+        assert connection.is_open
+        return f"open={connection.is_open}"
+
+    result = await mcp.call_tool("query_sync", {"query": "test"})
+    assert result.structured_content is not None
+    assert result.structured_content["result"] == "open=True"
+    assert not conn.is_open
+
+
+async def test_sync_resource_context_manager_stays_open(mcp: FastMCP):
+    """Test that sync context manager dependencies work with resources."""
+    conn = Connection()
+
+    @contextmanager
+    def get_sync_connection():
+        conn.is_open = True
+        try:
+            yield conn
+        finally:
+            conn.is_open = False
+
+    @mcp.resource("data://sync")
+    async def load_sync(connection: Connection = Depends(get_sync_connection)) -> str:
+        assert connection.is_open
+        return f"open={connection.is_open}"
+
+    result = await mcp.read_resource("data://sync")
+    assert result.contents[0].content == "open=True"
+    assert not conn.is_open
+
+
+async def test_sync_resource_template_context_manager_stays_open(mcp: FastMCP):
+    """Test that sync context manager dependencies work with resource templates."""
+    conn = Connection()
+
+    @contextmanager
+    def get_sync_connection():
+        conn.is_open = True
+        try:
+            yield conn
+        finally:
+            conn.is_open = False
+
+    @mcp.resource("item://{item_id}")
+    async def get_item(
+        item_id: str,
+        connection: Connection = Depends(get_sync_connection),
+    ) -> str:
+        assert connection.is_open
+        return f"open={connection.is_open},item={item_id}"
+
+    result = await mcp.read_resource("item://456")
+    assert isinstance(result.contents[0].content, str)
+    assert "open=True" in result.contents[0].content
+    assert not conn.is_open
+
+
+async def test_sync_prompt_context_manager_stays_open(mcp: FastMCP):
+    """Test that sync context manager dependencies work with prompts."""
+    conn = Connection()
+
+    @contextmanager
+    def get_sync_connection():
+        conn.is_open = True
+        try:
+            yield conn
+        finally:
+            conn.is_open = False
+
+    @mcp.prompt()
+    async def sync_prompt(
+        topic: str,
+        connection: Connection = Depends(get_sync_connection),
+    ) -> str:
+        assert connection.is_open
+        return f"open={connection.is_open},topic={topic}"
+
+    result = await mcp.render_prompt("sync_prompt", {"topic": "test"})
+    message = result.messages[0]
+    content = message.content
+    assert isinstance(content, TextContent)
+    assert "open=True" in content.text
+    assert not conn.is_open
+
+
+async def test_external_user_cannot_override_dependency(mcp: FastMCP):
+    """Test that external MCP clients cannot override dependency parameters."""
+
+    def get_admin_status() -> str:
+        return "not_admin"
+
+    @mcp.tool()
+    async def check_permission(
+        action: str, admin: str = Depends(get_admin_status)
+    ) -> str:
+        return f"action={action},admin={admin}"
+
+    # Verify dependency is NOT in the schema
+    result = await mcp._on_list_tools(make_server_request_context(), None)
+    tool = next(t for t in result.tools if t.name == "check_permission")
+    assert "admin" not in tool.input_schema["properties"]
+
+    # Normal call - dependency is resolved
+    result = await mcp.call_tool("check_permission", {"action": "read"})
+    assert result.structured_content is not None
+    assert "admin=not_admin" in result.structured_content["result"]
+
+    # Try to override dependency - rejected (not in schema). The rejection is an
+    # argument-validation error, so it surfaces as fastmcp's ValidationError
+    # (see #4128).
+    from fastmcp.exceptions import ValidationError
+
+    with pytest.raises(ValidationError):
+        await mcp.call_tool("check_permission", {"action": "read", "admin": "hacker"})
+
+
+async def test_prompt_dependency_cannot_be_overridden_externally(mcp: FastMCP):
+    """Test that external callers cannot override prompt dependencies.
+
+    This is a security test - dependencies should NEVER be overridable from
+    outside the server, even for prompts which don't validate against strict schemas.
+    """
+
+    def get_secret() -> str:
+        return "real_secret"
+
+    @mcp.prompt()
+    async def secure_prompt(topic: str, secret: str = Depends(get_secret)) -> str:
+        return f"Topic: {topic}, Secret: {secret}"
+
+    # Normal call - should use dependency
+    result = await mcp.render_prompt("secure_prompt", {"topic": "test"})
+    message = result.messages[0]
+    content = message.content
+    assert isinstance(content, TextContent)
+    assert "Secret: real_secret" in content.text
+
+    # Try to override dependency - should be ignored/rejected
+    result = await mcp.render_prompt(
+        "secure_prompt",
+        {"topic": "test", "secret": "HACKED"},  # Attempt override
+    )
+    message = result.messages[0]
+    content = message.content
+    assert isinstance(content, TextContent)
+    # Should still use real dependency, not hacked value
+    assert "Secret: real_secret" in content.text
+    assert "HACKED" not in content.text
+
+
+async def test_resource_dependency_cannot_be_overridden_externally(mcp: FastMCP):
+    """Test that external callers cannot override resource dependencies."""
+
+    def get_api_key() -> str:
+        return "real_api_key"
+
+    @mcp.resource("data://config")
+    async def get_config(api_key: str = Depends(get_api_key)) -> str:
+        return f"API Key: {api_key}"
+
+    # Normal call
+    result = await mcp.read_resource("data://config")
+    assert isinstance(result.contents[0].content, str)
+    assert "API Key: real_api_key" in result.contents[0].content
+
+    # Resources don't accept arguments from clients (static URI)
+    # so this scenario is less of a concern, but documenting it
+
+
+async def test_resource_template_dependency_cannot_be_overridden_externally(
+    mcp: FastMCP,
+):
+    """Test that external callers cannot override resource template dependencies.
+
+    Resource templates extract parameters from the URI path, so there's a risk
+    that a dependency parameter name could match a URI parameter.
+    """
+
+    def get_auth_token() -> str:
+        return "real_token"
+
+    @mcp.resource("user://{user_id}")
+    async def get_user(user_id: str, token: str = Depends(get_auth_token)) -> str:
+        return f"User: {user_id}, Token: {token}"
+
+    # Normal call
+    result = await mcp.read_resource("user://123")
+    assert isinstance(result.contents[0].content, str)
+    assert "User: 123, Token: real_token" in result.contents[0].content
+
+    # Try to inject token via URI (shouldn't be possible with this pattern)
+    # But if URI was user://{token}, it could extract it
+
+
+async def test_resource_template_uri_cannot_match_dependency_name(mcp: FastMCP):
+    """Test that URI parameters cannot have the same name as dependencies.
+
+    If a URI template tries to use a parameter name that's also a dependency,
+    the template creation should fail because the dependency is excluded from
+    the user-facing signature.
+    """
+
+    def get_token() -> str:
+        return "real_token"
+
+    # This should fail - {token} in URI but token is a dependency parameter
+    with pytest.raises(ValueError, match="URI parameters.*must be a subset"):
+
+        @mcp.resource("auth://{token}/validate")
+        async def validate(token: str = Depends(get_token)) -> str:
+            return f"Validating with: {token}"
+
+
+async def test_toolerror_propagates_from_dependency(mcp: FastMCP):
+    """ToolError raised in a dependency should propagate unchanged (issue #2633).
+
+    When a dependency raises ToolError, it should not be wrapped in RuntimeError.
+    This allows developers to use ToolError for validation in dependencies.
+    """
+    from fastmcp.exceptions import ToolError
+
+    def validate_client_id() -> str:
+        raise ToolError("Client ID is required - select a client first")
+
+    @mcp.tool()
+    async def my_tool(client_id: str = Depends(validate_client_id)) -> str:
+        return f"Working with client: {client_id}"
+
+    async with Client(mcp) as client:
+        # ToolError is converted to an error result by the server
+        result = await client.call_tool("my_tool", {}, raise_on_error=False)
+        assert result.is_error
+        # The original error message should be preserved (not wrapped in RuntimeError)
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "Client ID is required - select a client first"
+
+
+async def test_validation_error_propagates_from_dependency(mcp: FastMCP):
+    """ValidationError raised in a dependency should propagate unchanged."""
+    from fastmcp.exceptions import ValidationError
+
+    def validate_input() -> str:
+        raise ValidationError("Invalid input format")
+
+    @mcp.tool()
+    async def tool_with_validation(val: str = Depends(validate_input)) -> str:
+        return val
+
+    async with Client(mcp) as client:
+        # ValidationError is re-raised by the server and becomes an error result
+        # The original error message should be preserved (not wrapped in RuntimeError)
+        result = await client.call_tool(
+            "tool_with_validation", {}, raise_on_error=False
+        )
+        assert result.is_error
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "Invalid input format"
+
+
+class TestDependencyInjection:
+    """Tests for the uncalled-for DI engine."""
+
+    def test_is_docket_available(self):
+        """Test is_docket_available returns True when docket is installed."""
+        from fastmcp.server.dependencies import is_docket_available
+
+        assert is_docket_available() is True
+
+    def test_is_docket_available_false_when_pydocket_too_old(self, monkeypatch):
+        """``is_docket_available()`` must treat pre-0.19.0 pydocket as unavailable.
+
+        Older pydocket versions (e.g. 0.16.x, pulled in transitively by
+        packages like prefect) import cleanly but lack the APIs fastmcp
+        uses (``docket.dependencies.current_execution``, etc.). Without a
+        version floor, the check would report available and then crash at
+        runtime. Simulate by forcing ``importlib.metadata`` to report an
+        old version.
+        """
+        import importlib.metadata
+
+        from fastmcp.server import dependencies
+
+        original_version = importlib.metadata.version
+
+        def fake_version(name: str) -> str:
+            if name == "pydocket":
+                return "0.16.6"
+            return original_version(name)
+
+        monkeypatch.setattr(dependencies, "_DOCKET_AVAILABLE", None)
+        monkeypatch.setattr(importlib.metadata, "version", fake_version)
+
+        assert dependencies.is_docket_available() is False
+        # The wrapper that actually failed in #3803 must now return None
+        # instead of raising ImportError on the inner import.
+        assert dependencies.get_task_context() is None
+
+    def test_is_docket_available_false_when_pydocket_not_installed(self, monkeypatch):
+        """``is_docket_available()`` returns False when pydocket is absent."""
+        import importlib.metadata
+
+        from fastmcp.server import dependencies
+
+        original_version = importlib.metadata.version
+
+        def fake_version(name: str) -> str:
+            if name == "pydocket":
+                raise importlib.metadata.PackageNotFoundError(name)
+            return original_version(name)
+
+        monkeypatch.setattr(dependencies, "_DOCKET_AVAILABLE", None)
+        monkeypatch.setattr(importlib.metadata, "version", fake_version)
+
+        assert dependencies.is_docket_available() is False
+
+    def test_is_docket_available_false_when_import_broken(self, monkeypatch):
+        """Metadata says installed but ``import docket`` fails — treat as unavailable.
+
+        Catches the broken/partial-install case where ``importlib.metadata``
+        still reports a usable version but the package itself isn't actually
+        importable (corrupted wheel, sys.path weirdness, etc.). Without the
+        import probe, fastmcp would later crash on its first ``from docket
+        ...`` instead of falling back gracefully.
+        """
+        import builtins
+
+        from fastmcp.server import dependencies
+
+        original_import = builtins.__import__
+
+        def fake_import(name, *args, **kwargs):
+            if name == "docket" or name.startswith("docket."):
+                raise ImportError("simulated broken docket install")
+            return original_import(name, *args, **kwargs)
+
+        monkeypatch.setattr(dependencies, "_DOCKET_AVAILABLE", None)
+        monkeypatch.setattr(builtins, "__import__", fake_import)
+
+        assert dependencies.is_docket_available() is False
+
+    def test_require_docket_passes_when_installed(self):
+        """Test require_docket doesn't raise when docket is installed."""
+        from fastmcp.server.dependencies import require_docket
+
+        require_docket("test feature")
+
+    def test_require_docket_error_mentions_version_when_too_old(self, monkeypatch):
+        """``require_docket()`` distinguishes "missing" from "too old".
+
+        When pydocket is installed but pinned below the floor, the install
+        instructions in the error must point at upgrading pydocket — not at
+        installing the ``tasks`` extra (which the resolver will treat as a
+        no-op as long as the lower pin is held by another package).
+        """
+        import importlib.metadata
+
+        from fastmcp.server import dependencies
+
+        original_version = importlib.metadata.version
+
+        def fake_version(name: str) -> str:
+            if name == "pydocket":
+                return "0.16.6"
+            return original_version(name)
+
+        monkeypatch.setattr(dependencies, "_DOCKET_AVAILABLE", None)
+        monkeypatch.setattr(importlib.metadata, "version", fake_version)
+
+        with pytest.raises(ImportError, match="pydocket 0.16.6 is installed"):
+            dependencies.require_docket("CurrentDocket()")
+
+    def test_dependency_class_exists(self):
+        """Test Dependency and Depends are importable from fastmcp."""
+        from fastmcp.dependencies import Dependency, Depends
+
+        assert Dependency is not None
+        assert Depends is not None
+
+    def test_depends_works(self):
+        """Test Depends() creates proper dependency wrapper."""
+        from uncalled_for.resolution import _Depends
+
+        from fastmcp.dependencies import Depends
+
+        def get_value() -> str:
+            return "test_value"
+
+        dep = Depends(get_value)
+        assert isinstance(dep, _Depends)
+        assert dep.factory is get_value
+
+    async def test_depends_import_from_fastmcp(self):
+        """Test that Depends can be imported from fastmcp.dependencies."""
+        from fastmcp.dependencies import Depends
+
+        def get_config() -> dict:
+            return {"key": "value"}
+
+        dep = Depends(get_config)
+        assert dep is not None
+
+    def test_get_dependency_parameters(self):
+        """Test get_dependency_parameters finds dependency defaults."""
+        from uncalled_for import get_dependency_parameters
+        from uncalled_for.resolution import _Depends
+
+        from fastmcp.dependencies import Depends
+
+        def get_db() -> str:
+            return "database"
+
+        def my_func(name: str, db: str = Depends(get_db)) -> str:
+            return f"{name}: {db}"
+
+        deps = get_dependency_parameters(my_func)
+        assert "db" in deps
+        db_dep = deps["db"]
+        assert isinstance(db_dep, _Depends)
+        assert db_dep.factory is get_db
+
+
+class TestAuthDependencies:
+    """Tests for authentication dependencies (CurrentAccessToken, TokenClaim)."""
+
+    def test_current_access_token_is_importable(self):
+        """Test that CurrentAccessToken can be imported."""
+        from fastmcp.server.dependencies import CurrentAccessToken
+
+        assert CurrentAccessToken is not None
+
+    def test_token_claim_is_importable(self):
+        """Test that TokenClaim can be imported."""
+        from fastmcp.server.dependencies import TokenClaim
+
+        assert TokenClaim is not None
+
+    def test_current_access_token_is_dependency(self):
+        """Test that CurrentAccessToken is a Dependency instance."""
+        from fastmcp.dependencies import Dependency
+        from fastmcp.server.dependencies import _CurrentAccessToken
+
+        dep = _CurrentAccessToken()
+        assert isinstance(dep, Dependency)
+
+    def test_token_claim_creates_dependency(self):
+        """Test that TokenClaim creates a Dependency instance."""
+        from fastmcp.dependencies import Dependency
+        from fastmcp.server.dependencies import TokenClaim, _TokenClaim
+
+        dep = TokenClaim("oid")
+        assert isinstance(dep, _TokenClaim)
+        assert isinstance(dep, Dependency)
+        assert dep.claim_name == "oid"
+
+    async def test_current_access_token_raises_without_token(self):
+        """Test that CurrentAccessToken raises when no token is available."""
+        from fastmcp.server.dependencies import _CurrentAccessToken
+
+        dep = _CurrentAccessToken()
+        with pytest.raises(RuntimeError, match="No access token found"):
+            await dep.__aenter__()
+
+    async def test_token_claim_raises_without_token(self):
+        """Test that TokenClaim raises when no token is available."""
+        from fastmcp.server.dependencies import _TokenClaim
+
+        dep = _TokenClaim("oid")
+        with pytest.raises(RuntimeError, match="No access token available"):
+            await dep.__aenter__()
+
+    async def test_current_access_token_excluded_from_tool_schema(self, mcp: FastMCP):
+        """Test that CurrentAccessToken dependency is excluded from tool schema."""
+
+        from fastmcp.server.auth import AccessToken
+        from fastmcp.server.dependencies import CurrentAccessToken
+
+        @mcp.tool()
+        async def tool_with_token(
+            name: str,
+            token: AccessToken = CurrentAccessToken(),
+        ) -> str:
+            return name
+
+        result = await mcp._on_list_tools(make_server_request_context(), None)
+        tool = next(t for t in result.tools if t.name == "tool_with_token")
+
+        assert "name" in tool.input_schema["properties"]
+        assert "token" not in tool.input_schema["properties"]
+
+    async def test_token_claim_excluded_from_tool_schema(self, mcp: FastMCP):
+        """Test that TokenClaim dependency is excluded from tool schema."""
+
+        from fastmcp.server.dependencies import TokenClaim
+
+        @mcp.tool()
+        async def tool_with_claim(
+            name: str,
+            user_id: str = TokenClaim("oid"),
+        ) -> str:
+            return name
+
+        result = await mcp._on_list_tools(make_server_request_context(), None)
+        tool = next(t for t in result.tools if t.name == "tool_with_claim")
+
+        assert "name" in tool.input_schema["properties"]
+        assert "user_id" not in tool.input_schema["properties"]
+
+    def test_current_access_token_exported_from_all(self):
+        """Test that CurrentAccessToken is exported from __all__."""
+        from fastmcp.server import dependencies
+
+        assert "CurrentAccessToken" in dependencies.__all__
+
+    def test_token_claim_exported_from_all(self):
+        """Test that TokenClaim is exported from __all__."""
+        from fastmcp.server import dependencies
+
+        assert "TokenClaim" in dependencies.__all__
+
+
+class TestSharedDependencies:
+    """Tests for Shared() dependencies that resolve once and are reused."""
+
+    async def test_shared_sync_function(self, mcp: FastMCP):
+        """Shared dependency from a sync function resolves and is reused."""
+
+        call_count = 0
+
+        def get_config() -> dict[str, str]:
+            nonlocal call_count
+            call_count += 1
+            return {"key": "value"}
+
+        @mcp.tool()
+        async def tool_a(config: dict[str, str] = Shared(get_config)) -> str:
+            return config["key"]
+
+        @mcp.tool()
+        async def tool_b(config: dict[str, str] = Shared(get_config)) -> str:
+            return config["key"]
+
+        async with Client(mcp) as client:
+            result_a = await client.call_tool("tool_a", {})
+            result_b = await client.call_tool("tool_b", {})
+
+        assert result_a.content[0].text == "value"
+        assert result_b.content[0].text == "value"
+        assert call_count == 1
+
+    async def test_shared_async_function(self, mcp: FastMCP):
+        """Shared dependency from an async function resolves and is reused."""
+
+        call_count = 0
+
+        async def get_session() -> str:
+            nonlocal call_count
+            call_count += 1
+            return "session-abc"
+
+        @mcp.tool()
+        async def tool_a(session: str = Shared(get_session)) -> str:
+            return session
+
+        @mcp.tool()
+        async def tool_b(session: str = Shared(get_session)) -> str:
+            return session
+
+        async with Client(mcp) as client:
+            result_a = await client.call_tool("tool_a", {})
+            result_b = await client.call_tool("tool_b", {})
+
+        assert result_a.content[0].text == "session-abc"
+        assert result_b.content[0].text == "session-abc"
+        assert call_count == 1
+
+    async def test_shared_async_context_manager(self, mcp: FastMCP):
+        """Shared dependency from an async context manager stays open across calls."""
+
+        enter_count = 0
+
+        @asynccontextmanager
+        async def get_connection():
+            nonlocal enter_count
+            enter_count += 1
+            conn = Connection()
+            async with conn:
+                yield conn
+
+        @mcp.tool()
+        async def tool_a(conn: Connection = Shared(get_connection)) -> bool:
+            return conn.is_open
+
+        @mcp.tool()
+        async def tool_b(conn: Connection = Shared(get_connection)) -> bool:
+            return conn.is_open
+
+        async with Client(mcp) as client:
+            result_a = await client.call_tool("tool_a", {})
+            result_b = await client.call_tool("tool_b", {})
+
+        assert result_a.content[0].text == "true"
+        assert result_b.content[0].text == "true"
+        assert enter_count == 1
+
+    async def test_shared_with_depends(self, mcp: FastMCP):
+        """Shared and Depends can coexist in the same tool."""
+
+        shared_calls = 0
+        depends_calls = 0
+
+        def get_config() -> str:
+            nonlocal shared_calls
+            shared_calls += 1
+            return "shared-config"
+
+        def get_request_id() -> str:
+            nonlocal depends_calls
+            depends_calls += 1
+            return "request-123"
+
+        @mcp.tool()
+        async def my_tool(
+            config: str = Shared(get_config),
+            request_id: str = Depends(get_request_id),
+        ) -> str:
+            return f"{config}/{request_id}"
+
+        async with Client(mcp) as client:
+            result1 = await client.call_tool("my_tool", {})
+            result2 = await client.call_tool("my_tool", {})
+
+        assert result1.content[0].text == "shared-config/request-123"
+        assert result2.content[0].text == "shared-config/request-123"
+        assert shared_calls == 1
+        assert depends_calls == 2
+
+    async def test_shared_excluded_from_schema(self, mcp: FastMCP):
+        """Shared dependencies are not exposed in the tool schema."""
+
+        def get_db() -> str:
+            return "db"
+
+        @mcp.tool()
+        async def my_tool(name: str, db: str = Shared(get_db)) -> str:
+            return name
+
+        result = await mcp._on_list_tools(make_server_request_context(), None)
+        tool = next(t for t in result.tools if t.name == "my_tool")
+
+        assert "name" in tool.input_schema["properties"]
+        assert "db" not in tool.input_schema["properties"]
+
+    async def test_shared_in_resource(self, mcp: FastMCP):
+        """Shared dependencies work in resource functions."""
+
+        call_count = 0
+
+        def get_config() -> str:
+            nonlocal call_count
+            call_count += 1
+            return "resource-config"
+
+        @mcp.resource("test://config")
+        async def config_resource(config: str = Shared(get_config)) -> str:
+            return config
+
+        async with Client(mcp) as client:
+            result = await client.read_resource("test://config")
+            assert result[0].text == "resource-config"
+
+            result = await client.read_resource("test://config")
+            assert result[0].text == "resource-config"
+            assert call_count == 1
+
+    async def test_shared_in_prompt(self, mcp: FastMCP):
+        """Shared dependencies work in prompt functions."""
+
+        call_count = 0
+
+        def get_system_prompt() -> str:
+            nonlocal call_count
+            call_count += 1
+            return "You are a helpful assistant."
+
+        @mcp.prompt()
+        async def my_prompt(topic: str, system: str = Shared(get_system_prompt)) -> str:
+            return f"{system} Talk about {topic}."
+
+        async with Client(mcp) as client:
+            result = await client.get_prompt("my_prompt", {"topic": "dogs"})
+            assert (
+                "You are a helpful assistant. Talk about dogs."
+                in result.messages[0].content.text
+            )
+
+            result = await client.get_prompt("my_prompt", {"topic": "cats"})
+            assert (
+                "You are a helpful assistant. Talk about cats."
+                in result.messages[0].content.text
+            )
+            assert call_count == 1
+
+    @pytest.mark.skipif(
+        not is_docket_available(),
+        reason="requires pydocket for the Docket/Worker lifespan path",
+    )
+    async def test_shared_resolves_on_task_capable_server(self):
+        """Shared() dependencies resolve on a normal request even when the server
+        has task-enabled components.
+
+        When pydocket is installed AND a task-enabled component exists, the
+        lifespan takes the Docket/Worker branch. That branch must still capture
+        the app-scoped SharedContext snapshot so FastMCPServerMiddleware can
+        re-apply it per request; otherwise Shared() dependencies fail to resolve
+        on ordinary (non-task) calls.
+        """
+        mcp = FastMCP("task-capable-server")
+
+        call_count = 0
+
+        def get_config() -> dict[str, str]:
+            nonlocal call_count
+            call_count += 1
+            return {"key": "value"}
+
+        @mcp.tool(task=True)
+        async def background_tool(x: int) -> int:
+            return x
+
+        @mcp.tool()
+        async def normal_tool(config: dict[str, str] = Shared(get_config)) -> str:
+            return config["key"]
+
+        async with Client(mcp) as client:
+            result_a = await client.call_tool("normal_tool", {})
+            result_b = await client.call_tool("normal_tool", {})
+
+        assert result_a.content[0].text == "value"
+        assert result_b.content[0].text == "value"
+        # App-scoped: resolved once and reused across requests.
+        assert call_count == 1
diff --git a/tests/server/test_dependencies_advanced.py b/tests/server/test_dependencies_advanced.py
new file mode 100644
index 0000000..0657aad
--- /dev/null
+++ b/tests/server/test_dependencies_advanced.py
@@ -0,0 +1,286 @@
+"""Advanced tests for dependency injection in FastMCP: context annotations, vendored DI, and auth dependencies."""
+
+import inspect
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.dependencies import CurrentContext
+from fastmcp.server.context import Context
+from tests.conftest import make_server_request_context
+
+
+class Connection:
+    """Test connection that tracks whether it's currently open."""
+
+    def __init__(self):
+        self.is_open = False
+
+    async def __aenter__(self):
+        self.is_open = True
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        self.is_open = False
+
+
+@pytest.fixture
+def mcp():
+    """Create a FastMCP server for testing."""
+    return FastMCP("test-server")
+
+
+class TestTransformContextAnnotations:
+    """Tests for the transform_context_annotations function."""
+
+    async def test_optional_context_degrades_to_none_without_active_context(self):
+        """Optional Context should resolve to None when no context is active."""
+        from fastmcp.server.dependencies import transform_context_annotations
+
+        async def fn_with_optional_ctx(name: str, ctx: Context | None = None) -> str:
+            return name
+
+        transform_context_annotations(fn_with_optional_ctx)
+        sig = inspect.signature(fn_with_optional_ctx)
+        ctx_dependency = sig.parameters["ctx"].default
+
+        resolved_ctx = await ctx_dependency.__aenter__()
+        try:
+            assert resolved_ctx is None
+        finally:
+            await ctx_dependency.__aexit__(None, None, None)
+
+    async def test_optional_context_still_injected_in_foreground_requests(
+        self, mcp: FastMCP
+    ):
+        """Optional Context should still be injected for normal MCP requests."""
+
+        @mcp.tool()
+        async def tool_with_optional_context(
+            name: str, ctx: Context | None = None
+        ) -> str:
+            if ctx is None:
+                return f"missing:{name}"
+            return f"present:{ctx.session_id}:{name}"
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("tool_with_optional_context", {"name": "x"})
+            assert result.content[0].text.startswith("present:")
+
+    async def test_basic_context_transformation(self, mcp: FastMCP):
+        """Test basic Context type annotation is transformed."""
+
+        @mcp.tool()
+        async def tool_with_context(name: str, ctx: Context) -> str:
+            return f"session={ctx.session_id}, name={name}"
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("tool_with_context", {"name": "test"})
+            assert "session=" in result.content[0].text
+            assert "name=test" in result.content[0].text
+
+    async def test_transform_with_var_params(self):
+        """Test transform_context_annotations handles *args and **kwargs correctly."""
+        from fastmcp.server.dependencies import transform_context_annotations
+
+        # This function can't be a tool (FastMCP doesn't support *args/**kwargs),
+        # but transform should handle it gracefully for signature inspection
+        async def fn_with_var_params(
+            first: str, ctx: Context, *args: str, **kwargs: str
+        ) -> str:
+            return f"first={first}"
+
+        transform_context_annotations(fn_with_var_params)
+        sig = inspect.signature(fn_with_var_params)
+
+        # Verify structure is preserved
+        param_kinds = {p.name: p.kind for p in sig.parameters.values()}
+        assert param_kinds["first"] == inspect.Parameter.POSITIONAL_OR_KEYWORD
+        assert param_kinds["ctx"] == inspect.Parameter.POSITIONAL_OR_KEYWORD
+        assert param_kinds["args"] == inspect.Parameter.VAR_POSITIONAL
+        assert param_kinds["kwargs"] == inspect.Parameter.VAR_KEYWORD
+
+        # ctx should now have a default
+        assert sig.parameters["ctx"].default is not inspect.Parameter.empty
+
+    async def test_context_keyword_only(self, mcp: FastMCP):
+        """Test Context transformation preserves keyword-only parameter semantics."""
+        from fastmcp.server.dependencies import transform_context_annotations
+
+        # Define function with keyword-only Context param
+        async def fn_with_kw_only(a: str, *, ctx: Context, b: str = "default") -> str:
+            return f"a={a}, b={b}"
+
+        # Transform and check signature structure
+        transform_context_annotations(fn_with_kw_only)
+        sig = inspect.signature(fn_with_kw_only)
+        params = list(sig.parameters.values())
+
+        # 'a' should be POSITIONAL_OR_KEYWORD
+        assert params[0].name == "a"
+        assert params[0].kind == inspect.Parameter.POSITIONAL_OR_KEYWORD
+
+        # 'ctx' should still be KEYWORD_ONLY (after transformation)
+        ctx_param = sig.parameters["ctx"]
+        assert ctx_param.kind == inspect.Parameter.KEYWORD_ONLY
+
+        # 'b' should still be KEYWORD_ONLY
+        b_param = sig.parameters["b"]
+        assert b_param.kind == inspect.Parameter.KEYWORD_ONLY
+
+    async def test_context_with_annotated(self, mcp: FastMCP):
+        """Test Context with Annotated type is transformed."""
+        from typing import Annotated
+
+        @mcp.tool()
+        async def tool_with_annotated_ctx(
+            name: str, ctx: Annotated[Context, "custom annotation"]
+        ) -> str:
+            return f"session={ctx.session_id}"
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("tool_with_annotated_ctx", {"name": "test"})
+            assert "session=" in result.content[0].text
+
+    async def test_context_already_has_dependency_default(self, mcp: FastMCP):
+        """Test that Context with existing Depends default is not re-transformed."""
+
+        @mcp.tool()
+        async def tool_with_explicit_context(
+            name: str, ctx: Context = CurrentContext()
+        ) -> str:
+            return f"session={ctx.session_id}"
+
+        async with Client(mcp) as client:
+            result = await client.call_tool(
+                "tool_with_explicit_context", {"name": "test"}
+            )
+            assert "session=" in result.content[0].text
+
+    async def test_multiple_context_params(self, mcp: FastMCP):
+        """Test multiple Context-typed parameters are all transformed."""
+
+        @mcp.tool()
+        async def tool_with_multiple_ctx(
+            name: str, ctx1: Context, ctx2: Context
+        ) -> str:
+            # Both should refer to same context
+            assert ctx1.session_id == ctx2.session_id
+            return f"same={ctx1 is ctx2}"
+
+        # Both ctx params should be excluded from schema
+        result = await mcp._on_list_tools(make_server_request_context(), None)
+        tool = next(t for t in result.tools if t.name == "tool_with_multiple_ctx")
+        assert "name" in tool.input_schema["properties"]
+        assert "ctx1" not in tool.input_schema["properties"]
+        assert "ctx2" not in tool.input_schema["properties"]
+
+    async def test_context_in_class_method(self, mcp: FastMCP):
+        """Test Context transformation works with bound methods."""
+
+        class MyTools:
+            def __init__(self, prefix: str):
+                self.prefix = prefix
+
+            async def greet(self, name: str, ctx: Context) -> str:
+                return f"{self.prefix} {name}, session={ctx.session_id}"
+
+        tools = MyTools("Hello")
+        mcp.tool()(tools.greet)
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("greet", {"name": "World"})
+            assert "Hello World" in result.content[0].text
+            assert "session=" in result.content[0].text
+
+    async def test_context_in_static_method(self, mcp: FastMCP):
+        """Test Context transformation works with static methods."""
+
+        class MyTools:
+            @staticmethod
+            async def static_tool(name: str, ctx: Context) -> str:
+                return f"name={name}, session={ctx.session_id}"
+
+        mcp.tool()(MyTools.static_tool)
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("static_tool", {"name": "test"})
+            assert "name=test" in result.content[0].text
+            assert "session=" in result.content[0].text
+
+    async def test_context_in_callable_class(self, mcp: FastMCP):
+        """Test Context transformation works with callable class instances."""
+        from fastmcp.tools import Tool
+
+        class CallableTool:
+            def __init__(self, multiplier: int):
+                self.multiplier = multiplier
+
+            async def __call__(self, x: int, ctx: Context) -> str:
+                return f"result={x * self.multiplier}, session={ctx.session_id}"
+
+        # Use Tool.from_function directly (mcp.tool() decorator doesn't support callable instances)
+        tool = Tool.from_function(CallableTool(3))
+        mcp.add_tool(tool)
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("CallableTool", {"x": 5})
+            assert "result=15" in result.content[0].text
+            assert "session=" in result.content[0].text
+
+    async def test_context_param_reordering(self, mcp: FastMCP):
+        """Test that Context params are reordered correctly to maintain valid signature."""
+        from fastmcp.server.dependencies import transform_context_annotations
+
+        # Context in middle without default - should be moved after non-default params
+        async def fn_with_middle_ctx(a: str, ctx: Context, b: str) -> str:
+            return f"{a},{b}"
+
+        transform_context_annotations(fn_with_middle_ctx)
+        sig = inspect.signature(fn_with_middle_ctx)
+        params = list(sig.parameters.values())
+
+        # After transform: a, b should come before ctx (which now has default)
+        param_names = [p.name for p in params]
+        assert param_names == ["a", "b", "ctx"]
+
+        # ctx should have a default now
+        assert sig.parameters["ctx"].default is not inspect.Parameter.empty
+
+    async def test_context_resource(self, mcp: FastMCP):
+        """Test Context transformation works with resources."""
+
+        @mcp.resource("data://test")
+        async def resource_with_ctx(ctx: Context) -> str:
+            return f"session={ctx.session_id}"
+
+        async with Client(mcp) as client:
+            result = await client.read_resource("data://test")
+            assert len(result) == 1
+            assert "session=" in result[0].text
+
+    async def test_context_resource_template(self, mcp: FastMCP):
+        """Test Context transformation works with resource templates."""
+
+        @mcp.resource("item://{item_id}")
+        async def template_with_ctx(item_id: str, ctx: Context) -> str:
+            return f"item={item_id}, session={ctx.session_id}"
+
+        async with Client(mcp) as client:
+            result = await client.read_resource("item://123")
+            assert len(result) == 1
+            assert "item=123" in result[0].text
+            assert "session=" in result[0].text
+
+    async def test_context_prompt(self, mcp: FastMCP):
+        """Test Context transformation works with prompts."""
+
+        @mcp.prompt()
+        async def prompt_with_ctx(topic: str, ctx: Context) -> str:
+            return f"Write about {topic} (session: {ctx.session_id})"
+
+        async with Client(mcp) as client:
+            result = await client.get_prompt("prompt_with_ctx", {"topic": "AI"})
+            assert "Write about AI" in result.messages[0].content.text
+            assert "session:" in result.messages[0].content.text
diff --git a/tests/server/test_event_store.py b/tests/server/test_event_store.py
new file mode 100644
index 0000000..edb00b5
--- /dev/null
+++ b/tests/server/test_event_store.py
@@ -0,0 +1,301 @@
+"""Tests for the EventStore implementation."""
+
+import pytest
+from mcp.server.streamable_http import EventMessage
+from mcp_types import JSONRPCRequest
+
+from fastmcp.server.event_store import (
+    EventEntry,
+    EventStore,
+    SessionScopedEventStore,
+    StreamEventList,
+)
+from fastmcp.server.http import FastMCPStreamableHTTPSessionManager
+
+
+class TestEventEntry:
+    def test_event_entry_with_message(self):
+        entry = EventEntry(
+            event_id="event-1",
+            stream_id="stream-1",
+            message={"jsonrpc": "2.0", "method": "test", "id": 1},
+        )
+        assert entry.event_id == "event-1"
+        assert entry.stream_id == "stream-1"
+        assert entry.message == {"jsonrpc": "2.0", "method": "test", "id": 1}
+
+    def test_event_entry_without_message(self):
+        entry = EventEntry(
+            event_id="event-1",
+            stream_id="stream-1",
+            message=None,
+        )
+        assert entry.message is None
+
+
+class TestStreamEventList:
+    def test_stream_event_list(self):
+        stream_list = StreamEventList(event_ids=["event-1", "event-2", "event-3"])
+        assert stream_list.event_ids == ["event-1", "event-2", "event-3"]
+
+    def test_stream_event_list_empty(self):
+        stream_list = StreamEventList(event_ids=[])
+        assert stream_list.event_ids == []
+
+
+class TestEventStore:
+    @pytest.fixture
+    def event_store(self):
+        return EventStore(max_events_per_stream=5, ttl=3600)
+
+    @pytest.fixture
+    def sample_message(self):
+        return JSONRPCRequest(jsonrpc="2.0", method="test", id=1)
+
+    async def test_store_event_returns_event_id(self, event_store, sample_message):
+        event_id = await event_store.store_event("stream-1", sample_message)
+        assert event_id is not None
+        assert isinstance(event_id, str)
+        assert len(event_id) > 0
+
+    async def test_store_event_priming_event(self, event_store):
+        """Test storing a priming event (message=None)."""
+        event_id = await event_store.store_event("stream-1", None)
+        assert event_id is not None
+
+    async def test_store_multiple_events(self, event_store, sample_message):
+        event_ids = []
+        for _ in range(3):
+            event_id = await event_store.store_event("stream-1", sample_message)
+            event_ids.append(event_id)
+
+        # All event IDs should be unique
+        assert len(set(event_ids)) == 3
+
+    async def test_replay_events_after_returns_stream_id(
+        self, event_store, sample_message
+    ):
+        # Store some events
+        first_event_id = await event_store.store_event("stream-1", sample_message)
+        second_event_id = await event_store.store_event("stream-1", sample_message)
+
+        # Replay events after the first one
+        replayed_events: list[EventMessage] = []
+
+        async def callback(event: EventMessage):
+            replayed_events.append(event)
+
+        stream_id = await event_store.replay_events_after(first_event_id, callback)
+        assert stream_id == "stream-1"
+        assert len(replayed_events) == 1
+        assert replayed_events[0].event_id == second_event_id
+        replayed_message = replayed_events[0].message
+        assert isinstance(replayed_message, JSONRPCRequest)
+        assert replayed_message.method == "test"
+
+    async def test_replay_events_after_skips_priming_events(self, event_store):
+        """Priming events (message=None) should not be replayed."""
+        # Store a priming event
+        priming_id = await event_store.store_event("stream-1", None)
+
+        # Store a real event
+        real_message = JSONRPCRequest(jsonrpc="2.0", method="test", id=1)
+        await event_store.store_event("stream-1", real_message)
+
+        # Replay after priming event
+        replayed_events: list[EventMessage] = []
+
+        async def callback(event: EventMessage):
+            replayed_events.append(event)
+
+        await event_store.replay_events_after(priming_id, callback)
+
+        # Only the real event should be replayed
+        assert len(replayed_events) == 1
+
+    async def test_replay_events_after_unknown_event_id(self, event_store):
+        replayed_events: list[EventMessage] = []
+
+        async def callback(event: EventMessage):
+            replayed_events.append(event)
+
+        result = await event_store.replay_events_after("unknown-event-id", callback)
+        assert result is None
+        assert len(replayed_events) == 0
+
+    async def test_max_events_per_stream_trims_old_events(self, event_store):
+        """Test that old events are trimmed when max_events_per_stream is exceeded."""
+        # Store more events than the limit
+        event_ids = []
+        for i in range(7):
+            msg = JSONRPCRequest(jsonrpc="2.0", method=f"test-{i}", id=i)
+            event_id = await event_store.store_event("stream-1", msg)
+            event_ids.append(event_id)
+
+        # The first 2 events should have been trimmed (7 - 5 = 2)
+        # Trying to replay from the first event should fail
+        replayed_events: list[EventMessage] = []
+
+        async def callback(event: EventMessage):
+            replayed_events.append(event)
+
+        result = await event_store.replay_events_after(event_ids[0], callback)
+        assert result is None  # First event was trimmed
+
+        # But replaying from a more recent event should work
+        result = await event_store.replay_events_after(event_ids[3], callback)
+        assert result == "stream-1"
+
+    async def test_multiple_streams_are_isolated(self, event_store):
+        """Events from different streams should not interfere with each other."""
+        msg1 = JSONRPCRequest(jsonrpc="2.0", method="stream1-test", id=1)
+        msg2 = JSONRPCRequest(jsonrpc="2.0", method="stream2-test", id=2)
+
+        stream1_event = await event_store.store_event("stream-1", msg1)
+        await event_store.store_event("stream-1", msg1)
+
+        stream2_event = await event_store.store_event("stream-2", msg2)
+        await event_store.store_event("stream-2", msg2)
+
+        # Replay stream 1
+        stream1_replayed: list[EventMessage] = []
+
+        async def callback1(event: EventMessage):
+            stream1_replayed.append(event)
+
+        stream_id = await event_store.replay_events_after(stream1_event, callback1)
+        assert stream_id == "stream-1"
+        assert len(stream1_replayed) == 1
+
+        # Replay stream 2
+        stream2_replayed: list[EventMessage] = []
+
+        async def callback2(event: EventMessage):
+            stream2_replayed.append(event)
+
+        stream_id = await event_store.replay_events_after(stream2_event, callback2)
+        assert stream_id == "stream-2"
+        assert len(stream2_replayed) == 1
+
+    @pytest.mark.parametrize("stream_id", ["_GET_stream", "1"])
+    async def test_session_scoped_stores_isolate_overlapping_stream_ids(
+        self, event_store, stream_id
+    ):
+        session_a_store = SessionScopedEventStore(event_store, "session-a")
+        session_b_store = SessionScopedEventStore(event_store, "session-b")
+        msg_a1 = JSONRPCRequest(jsonrpc="2.0", method="session-a-1", id=1)
+        msg_a2 = JSONRPCRequest(jsonrpc="2.0", method="session-a-2", id=2)
+        msg_b = JSONRPCRequest(jsonrpc="2.0", method="session-b", id=3)
+
+        session_a_event = await session_a_store.store_event(stream_id, msg_a1)
+        await session_b_store.store_event(stream_id, msg_b)
+        session_a_second_event = await session_a_store.store_event(stream_id, msg_a2)
+
+        replayed_events: list[EventMessage] = []
+
+        async def callback(event: EventMessage):
+            replayed_events.append(event)
+
+        replayed_stream_id = await session_a_store.replay_events_after(
+            session_a_event, callback
+        )
+
+        assert replayed_stream_id == stream_id
+        assert [event.event_id for event in replayed_events] == [session_a_second_event]
+        replayed_message = replayed_events[0].message
+        assert isinstance(replayed_message, JSONRPCRequest)
+        assert replayed_message.method == "session-a-2"
+
+    async def test_session_scoped_replay_rejects_foreign_last_event_id(
+        self, event_store
+    ):
+        session_a_store = SessionScopedEventStore(event_store, "session-a")
+        session_b_store = SessionScopedEventStore(event_store, "session-b")
+        msg_b1 = JSONRPCRequest(jsonrpc="2.0", method="session-b-1", id=1)
+        msg_b2 = JSONRPCRequest(jsonrpc="2.0", method="session-b-2", id=2)
+
+        foreign_event_id = await session_b_store.store_event("_GET_stream", msg_b1)
+        await session_b_store.store_event("_GET_stream", msg_b2)
+
+        replayed_events: list[EventMessage] = []
+
+        async def callback(event: EventMessage):
+            replayed_events.append(event)
+
+        replayed_stream_id = await session_a_store.replay_events_after(
+            foreign_event_id, callback
+        )
+
+        assert replayed_stream_id is None
+        assert replayed_events == []
+
+    def test_session_manager_returns_scoped_event_stores(self, event_store):
+        session_manager = FastMCPStreamableHTTPSessionManager(
+            app=object(), event_store=event_store
+        )
+
+        first_transport_store = session_manager.event_store
+        second_transport_store = session_manager.event_store
+
+        assert isinstance(first_transport_store, SessionScopedEventStore)
+        assert isinstance(second_transport_store, SessionScopedEventStore)
+        assert first_transport_store is not second_transport_store
+
+    async def test_default_storage_is_memory(self):
+        """Test that EventStore defaults to in-memory storage."""
+        event_store = EventStore()
+        msg = JSONRPCRequest(jsonrpc="2.0", method="test", id=1)
+
+        event_id = await event_store.store_event("stream-1", msg)
+        assert event_id is not None
+
+        replayed: list[EventMessage] = []
+
+        async def callback(event: EventMessage):
+            replayed.append(event)
+
+        # Store another event and replay
+        await event_store.store_event("stream-1", msg)
+        await event_store.replay_events_after(event_id, callback)
+        assert len(replayed) == 1
+
+
+class TestEventStoreIntegration:
+    """Integration tests for EventStore with actual message types."""
+
+    async def test_roundtrip_jsonrpc_message(self):
+        event_store = EventStore()
+
+        # Create a realistic JSON-RPC request wrapped in JSONRPCMessage
+        original_msg = JSONRPCRequest(
+            jsonrpc="2.0",
+            method="tools/call",
+            id="request-123",
+            params={"name": "my_tool", "arguments": {"x": 1, "y": 2}},
+        )
+
+        # Store it
+        event_id = await event_store.store_event("stream-1", original_msg)
+
+        # Store another event so we have something to replay
+        second_msg = JSONRPCRequest(
+            jsonrpc="2.0",
+            method="tools/call",
+            id="request-456",
+            params={"name": "my_tool", "arguments": {"x": 3, "y": 4}},
+        )
+        await event_store.store_event("stream-1", second_msg)
+
+        # Replay and verify the message content
+        replayed: list[EventMessage] = []
+
+        async def callback(event: EventMessage):
+            replayed.append(event)
+
+        await event_store.replay_events_after(event_id, callback)
+
+        assert len(replayed) == 1
+        assert replayed[0].event_id is not None
+        assert isinstance(replayed[0].message, JSONRPCRequest)
+        assert replayed[0].message.method == "tools/call"
+        assert replayed[0].message.id == "request-456"
diff --git a/tests/server/test_fastapi_testclient_compat.py b/tests/server/test_fastapi_testclient_compat.py
new file mode 100644
index 0000000..b2f55cc
--- /dev/null
+++ b/tests/server/test_fastapi_testclient_compat.py
@@ -0,0 +1,57 @@
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from fastmcp import FastMCP
+
+
+def test_fastapi_testclient_multiple_runs():
+    """Test that TestClient can be used multiple times with a mounted FastMCP app.
+
+    This verifies that the StreamableHTTPSessionManager is correctly recreated
+    for each lifespan cycle.
+    """
+    mcp = FastMCP("test")
+    mcp_app = mcp.http_app(path="/mcp")
+
+    @mcp.tool
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    @asynccontextmanager
+    async def combined_lifespan(app: FastAPI):
+        # Trigger the sub-app's lifespan
+        async with mcp_app.router.lifespan_context(mcp_app):
+            yield
+
+    app = FastAPI(lifespan=combined_lifespan)
+    app.mount("/analytics", mcp_app)
+
+    # First test run
+    with TestClient(app) as client:
+        # We use analytics prefix since it's mounted there
+        client.get("/analytics/mcp")  # Would raise RuntimeError before fix
+
+    # Second test run - this would fail before the fix
+    with TestClient(app) as client:
+        client.get("/analytics/mcp")
+
+
+def test_fastapi_testclient_nested_lifespan():
+    """Test that TestClient works with custom combined lifespans and multiple iterations."""
+    mcp = FastMCP("test")
+    mcp_app = mcp.http_app(path="/mcp")
+
+    @asynccontextmanager
+    async def combined_lifespan(app: FastAPI):
+        async with mcp_app.router.lifespan_context(mcp_app):
+            yield
+
+    app = FastAPI(lifespan=combined_lifespan)
+    app.mount("/analytics", mcp_app)
+
+    # Multiple runs with custom lifespan
+    for _ in range(3):
+        with TestClient(app) as client:
+            client.get("/analytics/mcp")
diff --git a/tests/server/test_file_server.py b/tests/server/test_file_server.py
new file mode 100644
index 0000000..f8b86ad
--- /dev/null
+++ b/tests/server/test_file_server.py
@@ -0,0 +1,150 @@
+from pathlib import Path
+
+import mcp_types
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.resources import ResourceContent, ResourceResult
+from tests.conftest import make_server_request_context
+
+
+@pytest.fixture()
+def test_dir(tmp_path_factory) -> Path:
+    """Create a temporary directory with test files."""
+    tmp = tmp_path_factory.mktemp("test_files")
+
+    # Create test files
+    (tmp / "example.py").write_text("print('hello world')")
+    (tmp / "readme.md").write_text("# Test Directory\nThis is a test.")
+    (tmp / "config.json").write_text('{"test": true}')
+
+    return tmp
+
+
+@pytest.fixture
+def mcp() -> FastMCP:
+    mcp = FastMCP()
+
+    return mcp
+
+
+@pytest.fixture(autouse=True)
+def resources(mcp: FastMCP, test_dir: Path) -> FastMCP:
+    @mcp.resource("dir://test_dir")
+    def list_test_dir() -> ResourceResult:
+        """List the files in the test directory"""
+        files = [str(f) for f in test_dir.iterdir()]
+        return ResourceResult([ResourceContent(f) for f in files])
+
+    @mcp.resource("file://test_dir/example.py")
+    def read_example_py() -> str:
+        """Read the example.py file"""
+        try:
+            return (test_dir / "example.py").read_text()
+        except FileNotFoundError:
+            return "File not found"
+
+    @mcp.resource("file://test_dir/readme.md")
+    def read_readme_md() -> str:
+        """Read the readme.md file"""
+        try:
+            return (test_dir / "readme.md").read_text()
+        except FileNotFoundError:
+            return "File not found"
+
+    @mcp.resource("file://test_dir/config.json")
+    def read_config_json() -> str:
+        """Read the config.json file"""
+        try:
+            return (test_dir / "config.json").read_text()
+        except FileNotFoundError:
+            return "File not found"
+
+    return mcp
+
+
+@pytest.fixture(autouse=True)
+def tools(mcp: FastMCP, test_dir: Path) -> FastMCP:
+    @mcp.tool
+    def delete_file(path: str) -> bool:
+        # ensure path is in test_dir
+        if Path(path).resolve().parent != test_dir:
+            raise ValueError(f"Path must be in test_dir: {path}")
+        Path(path).unlink()
+        return True
+
+    return mcp
+
+
+async def test_list_resources(mcp: FastMCP):
+    result = await mcp._on_list_resources(make_server_request_context(), None)
+    assert len(result.resources) == 4
+
+    assert [str(r.uri) for r in result.resources] == [
+        "dir://test_dir",
+        "file://test_dir/example.py",
+        "file://test_dir/readme.md",
+        "file://test_dir/config.json",
+    ]
+
+
+async def test_read_resource_dir(mcp: FastMCP):
+    res_result = await mcp._on_read_resource(
+        make_server_request_context(),
+        mcp_types.ReadResourceRequestParams(uri="dir://test_dir"),
+    )
+    assert isinstance(res_result, mcp_types.ReadResourceResult)
+    # ResourceResult splits lists into multiple contents (one per file path)
+    assert len(res_result.contents) == 3
+    # Extract file paths from each content
+    files = [
+        item.text
+        for item in res_result.contents
+        if isinstance(item, mcp_types.TextResourceContents)
+    ]
+
+    assert sorted([Path(f).name for f in files]) == [
+        "config.json",
+        "example.py",
+        "readme.md",
+    ]
+
+
+async def test_read_resource_file(mcp: FastMCP):
+    res_result = await mcp._on_read_resource(
+        make_server_request_context(),
+        mcp_types.ReadResourceRequestParams(uri="file://test_dir/example.py"),
+    )
+    assert isinstance(res_result, mcp_types.ReadResourceResult)
+    assert len(res_result.contents) == 1
+    res = res_result.contents[0]
+    assert isinstance(res, mcp_types.TextResourceContents)
+    assert res.text == "print('hello world')"
+
+
+async def test_delete_file(mcp: FastMCP, test_dir: Path):
+    await mcp._on_call_tool(
+        make_server_request_context(),
+        mcp_types.CallToolRequestParams(
+            name="delete_file", arguments=dict(path=str(test_dir / "example.py"))
+        ),
+    )
+    assert not (test_dir / "example.py").exists()
+
+
+async def test_delete_file_and_check_resources(mcp: FastMCP, test_dir: Path):
+    await mcp._on_call_tool(
+        make_server_request_context(),
+        mcp_types.CallToolRequestParams(
+            name="delete_file", arguments=dict(path=str(test_dir / "example.py"))
+        ),
+    )
+    res_result = await mcp._on_read_resource(
+        make_server_request_context(),
+        mcp_types.ReadResourceRequestParams(uri="file://test_dir/example.py"),
+    )
+    assert isinstance(res_result, mcp_types.ReadResourceResult)
+    assert len(res_result.contents) == 1
+    res = res_result.contents[0]
+    assert isinstance(res, mcp_types.TextResourceContents)
+    assert res.text == "File not found"
diff --git a/tests/server/test_icons.py b/tests/server/test_icons.py
new file mode 100644
index 0000000..9fba37b
--- /dev/null
+++ b/tests/server/test_icons.py
@@ -0,0 +1,342 @@
+"""Tests for icon support across all MCP object types."""
+
+from mcp_types import Icon
+
+from fastmcp import Client, FastMCP
+from fastmcp.prompts import Message, Prompt
+from fastmcp.resources import Resource
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.tools import Tool
+
+
+class TestServerIcons:
+    """Test icon support at the server/implementation level."""
+
+    async def test_server_with_icons_and_website_url(self):
+        """Test that server accepts icons and websiteUrl in constructor."""
+        icons = [
+            Icon(
+                src="https://example.com/icon.png",
+                mime_type="image/png",
+                sizes=["48x48"],
+            ),
+            Icon(
+                src="data:image/svg+xml;base64,PHN2Zz48L3N2Zz4=",
+                mime_type="image/svg+xml",
+                sizes=["any"],
+            ),
+        ]
+
+        mcp = FastMCP(
+            name="TestServer",
+            version="1.0.0",
+            website_url="https://example.com",
+            icons=icons,
+        )
+
+        # Verify that icons and website_url are passed to the underlying server
+        async with Client(mcp) as client:
+            server_info = client.initialize_result.server_info
+            assert server_info.website_url == "https://example.com"
+            assert server_info.icons == icons
+
+    async def test_server_without_icons_and_website_url(self):
+        """Test that server works without icons and websiteUrl."""
+        mcp = FastMCP(name="TestServer")
+
+        async with Client(mcp) as client:
+            server_info = client.initialize_result.server_info
+            assert server_info.website_url is None
+            assert server_info.icons is None
+
+
+class TestToolIcons:
+    """Test icon support for tools."""
+
+    async def test_tool_with_icons(self):
+        """Test that tools can have icons."""
+        mcp = FastMCP("TestServer")
+
+        icons = [
+            Icon(src="https://example.com/tool-icon.png", mime_type="image/png"),
+        ]
+
+        @mcp.tool(icons=icons)
+        def my_tool(name: str) -> str:
+            """A tool with an icon."""
+            return f"Hello, {name}!"
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            assert len(tools) == 1
+            tool = tools[0]
+            assert tool.icons == icons
+
+    async def test_tool_from_function_with_icons(self):
+        """Test creating a tool from a function with icons."""
+        icons = [Icon(src="https://example.com/icon.png")]
+
+        def my_function(x: int) -> int:
+            """A function."""
+            return x * 2
+
+        tool = Tool.from_function(my_function, icons=icons)
+        assert tool.icons == icons
+
+        # Verify it converts to MCP tool correctly
+        mcp_tool = tool.to_mcp_tool()
+        assert mcp_tool.icons == icons
+
+    async def test_tool_without_icons(self):
+        """Test that tools work without icons."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        def my_tool(name: str) -> str:
+            """A tool without an icon."""
+            return f"Hello, {name}!"
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            assert len(tools) == 1
+            tool = tools[0]
+            assert tool.icons is None
+
+
+class TestResourceIcons:
+    """Test icon support for resources."""
+
+    async def test_resource_with_icons(self):
+        """Test that resources can have icons."""
+        mcp = FastMCP("TestServer")
+
+        icons = [Icon(src="https://example.com/resource-icon.png")]
+
+        @mcp.resource("test://resource", icons=icons)
+        def my_resource() -> str:
+            """A resource with an icon."""
+            return "Resource content"
+
+        async with Client(mcp) as client:
+            resources = await client.list_resources()
+            assert len(resources) == 1
+            resource = resources[0]
+            assert resource.icons == icons
+
+    async def test_resource_from_function_with_icons(self):
+        """Test creating a resource from a function with icons."""
+        icons = [Icon(src="https://example.com/icon.png")]
+
+        def my_function() -> str:
+            """A function."""
+            return "content"
+
+        resource = Resource.from_function(
+            my_function,
+            uri="test://resource",
+            icons=icons,
+        )
+        assert resource.icons == icons
+
+        # Verify it converts to MCP resource correctly
+        mcp_resource = resource.to_mcp_resource()
+        assert mcp_resource.icons == icons
+
+    async def test_resource_without_icons(self):
+        """Test that resources work without icons."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.resource("test://resource")
+        def my_resource() -> str:
+            """A resource without an icon."""
+            return "Resource content"
+
+        async with Client(mcp) as client:
+            resources = await client.list_resources()
+            assert len(resources) == 1
+            resource = resources[0]
+            assert resource.icons is None
+
+
+class TestResourceTemplateIcons:
+    """Test icon support for resource templates."""
+
+    async def test_resource_template_with_icons(self):
+        """Test that resource templates can have icons."""
+        mcp = FastMCP("TestServer")
+
+        icons = [Icon(src="https://example.com/template-icon.png")]
+
+        @mcp.resource("test://resource/{id}", icons=icons)
+        def my_template(id: str) -> str:
+            """A resource template with an icon."""
+            return f"Resource {id}"
+
+        async with Client(mcp) as client:
+            templates = await client.list_resource_templates()
+            assert len(templates) == 1
+            template = templates[0]
+            assert template.icons == icons
+
+    async def test_resource_template_from_function_with_icons(self):
+        """Test creating a resource template from a function with icons."""
+        icons = [Icon(src="https://example.com/icon.png")]
+
+        def my_function(id: str) -> str:
+            """A function."""
+            return f"content-{id}"
+
+        template = ResourceTemplate.from_function(
+            my_function,
+            uri_template="test://resource/{id}",
+            icons=icons,
+        )
+        assert template.icons == icons
+
+        # Verify it converts to MCP template correctly
+        mcp_template = template.to_mcp_template()
+        assert mcp_template.icons == icons
+
+    async def test_resource_template_without_icons(self):
+        """Test that resource templates work without icons."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.resource("test://resource/{id}")
+        def my_template(id: str) -> str:
+            """A resource template without an icon."""
+            return f"Resource {id}"
+
+        async with Client(mcp) as client:
+            templates = await client.list_resource_templates()
+            assert len(templates) == 1
+            template = templates[0]
+            assert template.icons is None
+
+
+class TestPromptIcons:
+    """Test icon support for prompts."""
+
+    async def test_prompt_with_icons(self):
+        """Test that prompts can have icons."""
+        mcp = FastMCP("TestServer")
+
+        icons = [Icon(src="https://example.com/prompt-icon.png")]
+
+        @mcp.prompt(icons=icons)
+        def my_prompt(name: str):
+            """A prompt with an icon."""
+            return Message(f"Hello, {name}!")
+
+        async with Client(mcp) as client:
+            prompts = await client.list_prompts()
+            assert len(prompts) == 1
+            prompt = prompts[0]
+            assert prompt.icons == icons
+
+    async def test_prompt_from_function_with_icons(self):
+        """Test creating a prompt from a function with icons."""
+        icons = [Icon(src="https://example.com/icon.png")]
+
+        def my_function(topic: str):
+            """A function."""
+            return Message(f"Tell me about {topic}")
+
+        prompt = Prompt.from_function(my_function, icons=icons)
+        assert prompt.icons == icons
+
+        # Verify it converts to MCP prompt correctly
+        mcp_prompt = prompt.to_mcp_prompt()
+        assert mcp_prompt.icons == icons
+
+    async def test_prompt_without_icons(self):
+        """Test that prompts work without icons."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.prompt
+        def my_prompt(name: str):
+            """A prompt without an icon."""
+            return Message(f"Hello, {name}!")
+
+        async with Client(mcp) as client:
+            prompts = await client.list_prompts()
+            assert len(prompts) == 1
+            prompt = prompts[0]
+            assert prompt.icons is None
+
+
+class TestIconTypes:
+    """Test different types of icon data."""
+
+    async def test_multiple_icon_sizes(self):
+        """Test that multiple icon sizes can be specified."""
+        icons = [
+            Icon(
+                src="https://example.com/icon-48.png",
+                mime_type="image/png",
+                sizes=["48x48"],
+            ),
+            Icon(
+                src="https://example.com/icon-96.png",
+                mime_type="image/png",
+                sizes=["96x96"],
+            ),
+            Icon(
+                src="https://example.com/icon.svg",
+                mime_type="image/svg+xml",
+                sizes=["any"],
+            ),
+        ]
+
+        mcp = FastMCP("TestServer", icons=icons)
+
+        async with Client(mcp) as client:
+            server_info = client.initialize_result.server_info
+            assert len(server_info.icons) == 3
+            assert server_info.icons == icons
+
+    async def test_data_uri_icon(self):
+        """Test using data URIs for icons."""
+        # Simple SVG data URI
+        data_uri = "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCI+PHBhdGggZD0iTTEyIDJDNi40OCAyIDIgNi40OCAyIDEyczQuNDggMTAgMTAgMTAgMTAtNC40OCAxMC0xMFMxNy41MiAyIDEyIDJ6Ii8+PC9zdmc+"
+
+        icons = [Icon(src=data_uri, mime_type="image/svg+xml")]
+
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool(icons=icons)
+        def my_tool() -> str:
+            """A tool with a data URI icon."""
+            return "result"
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            assert tools[0].icons[0].src == data_uri
+
+    async def test_icon_without_optional_fields(self):
+        """Test that icons work with only the src field."""
+        icons = [Icon(src="https://example.com/icon.png")]
+
+        mcp = FastMCP("TestServer", icons=icons)
+
+        async with Client(mcp) as client:
+            server_info = client.initialize_result.server_info
+            assert server_info.icons[0].src == "https://example.com/icon.png"
+            assert server_info.icons[0].mime_type is None
+            assert server_info.icons[0].sizes is None
+
+
+class TestIconImport:
+    """Test that Icon must be imported from mcp_types."""
+
+    def test_icon_import(self):
+        """Test that Icon must be imported from mcp.types, not fastmcp."""
+        # Icon should NOT be available from fastmcp
+        import fastmcp
+
+        assert not hasattr(fastmcp, "Icon")
+
+        # Icon should be imported from mcp.types
+        from mcp_types import Icon as MCPIcon
+
+        icon = MCPIcon(src="https://example.com/icon.png")
+        assert icon.src == "https://example.com/icon.png"
diff --git a/tests/server/test_input_validation.py b/tests/server/test_input_validation.py
new file mode 100644
index 0000000..777574d
--- /dev/null
+++ b/tests/server/test_input_validation.py
@@ -0,0 +1,419 @@
+"""
+Tests for input validation behavior with strict_input_validation setting.
+
+This module tests the difference between strict JSON schema validation (when
+strict_input_validation=True) and Pydantic-based coercion (when
+strict_input_validation=False, the default).
+"""
+
+import json
+
+import pytest
+from mcp_types import TextContent
+from pydantic import BaseModel
+
+from fastmcp import Client, FastMCP
+from fastmcp.exceptions import ToolError
+
+
+class UserProfile(BaseModel):
+    """A test model for validating Pydantic model arguments."""
+
+    name: str
+    age: int
+    email: str
+
+
+class TestStringToIntegerCoercion:
+    """Test string-to-integer coercion behavior."""
+
+    async def test_string_integer_with_strict_validation(self):
+        """With strict validation, string integers should raise an error."""
+        mcp = FastMCP("TestServer", strict_input_validation=True)
+
+        @mcp.tool
+        def add_numbers(a: int, b: int) -> int:
+            """Add two numbers together."""
+            return a + b
+
+        async with Client(mcp) as client:
+            # String integers should fail with strict validation
+            with pytest.raises(Exception) as exc_info:
+                await client.call_tool("add_numbers", {"a": "10", "b": "20"})
+
+            # Verify it's a validation error
+            error_msg = str(exc_info.value).lower()
+            assert (
+                "validation" in error_msg
+                or "invalid" in error_msg
+                or "type" in error_msg
+            )
+
+    async def test_string_integer_without_strict_validation(self):
+        """Without strict validation, string integers should be coerced."""
+        mcp = FastMCP("TestServer", strict_input_validation=False)
+
+        @mcp.tool
+        def add_numbers(a: int, b: int) -> int:
+            """Add two numbers together."""
+            return a + b
+
+        async with Client(mcp) as client:
+            # String integers should be coerced to integers
+            result = await client.call_tool("add_numbers", {"a": "10", "b": "20"})
+            assert isinstance(result.content[0], TextContent)
+            assert result.content[0].text == "30"
+
+    async def test_default_is_not_strict(self):
+        """By default, strict_input_validation should be False."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        def multiply(x: int, y: int) -> int:
+            """Multiply two numbers."""
+            return x * y
+
+        async with Client(mcp) as client:
+            # Should work with string integers by default
+            result = await client.call_tool("multiply", {"x": "5", "y": "3"})
+            assert isinstance(result.content[0], TextContent)
+            assert result.content[0].text == "15"
+
+    async def test_string_float_coercion(self):
+        """Test that string floats are also coerced."""
+        mcp = FastMCP("TestServer", strict_input_validation=False)
+
+        @mcp.tool
+        def calculate_area(length: float, width: float) -> float:
+            """Calculate rectangle area."""
+            return length * width
+
+        async with Client(mcp) as client:
+            result = await client.call_tool(
+                "calculate_area", {"length": "10.5", "width": "20.0"}
+            )
+            assert isinstance(result.content[0], TextContent)
+            assert result.content[0].text == "210.0"
+
+    async def test_invalid_coercion_still_fails(self):
+        """Even without strict validation, truly invalid inputs should fail."""
+        mcp = FastMCP("TestServer", strict_input_validation=False)
+
+        @mcp.tool
+        def square(n: int) -> int:
+            """Square a number."""
+            return n * n
+
+        async with Client(mcp) as client:
+            # Non-numeric strings should still fail
+            with pytest.raises(Exception):
+                await client.call_tool("square", {"n": "not-a-number"})
+
+
+class TestPydanticModelArguments:
+    """Test validation of Pydantic model arguments."""
+
+    async def test_pydantic_model_with_dict_no_strict(self):
+        """Pydantic models should accept dict arguments without strict validation."""
+        mcp = FastMCP("TestServer", strict_input_validation=False)
+
+        @mcp.tool
+        def create_user(profile: UserProfile) -> str:
+            """Create a user from a profile."""
+            return f"Created user {profile.name}, age {profile.age}"
+
+        async with Client(mcp) as client:
+            result = await client.call_tool(
+                "create_user",
+                {"profile": {"name": "Alice", "age": 30, "email": "alice@example.com"}},
+            )
+            assert isinstance(result.content[0], TextContent)
+            assert "Alice" in result.content[0].text
+            assert "30" in result.content[0].text
+
+    async def test_stringified_json_not_auto_parsed_for_pydantic_models(self):
+        """Stringified JSON is rejected for Pydantic model parameters.
+
+        Some LLM clients send stringified JSON (a JSON string containing a
+        JSON object) instead of a proper JSON object.  FastMCP does not
+        auto-parse these; callers get a validation error.
+        """
+        mcp = FastMCP("TestServer", strict_input_validation=False)
+
+        @mcp.tool
+        def create_user(profile: UserProfile) -> str:
+            """Create a user from a profile."""
+            return f"Created user {profile.name}, age {profile.age}"
+
+        async with Client(mcp) as client:
+            stringified = json.dumps(
+                {"name": "Bob", "age": 25, "email": "bob@example.com"}
+            )
+
+            with pytest.raises(ToolError, match="validation"):
+                await client.call_tool("create_user", {"profile": stringified})
+
+    async def test_pydantic_model_with_coercion(self):
+        """Pydantic models should benefit from coercion without strict validation."""
+        mcp = FastMCP("TestServer", strict_input_validation=False)
+
+        @mcp.tool
+        def create_user(profile: UserProfile) -> str:
+            """Create a user from a profile."""
+            return f"Created user {profile.name}, age {profile.age}"
+
+        async with Client(mcp) as client:
+            # Age as string should be coerced
+            result = await client.call_tool(
+                "create_user",
+                {
+                    "profile": {
+                        "name": "Charlie",
+                        "age": "35",  # String instead of int
+                        "email": "charlie@example.com",
+                    }
+                },
+            )
+            assert isinstance(result.content[0], TextContent)
+            assert "Charlie" in result.content[0].text
+            assert "35" in result.content[0].text
+
+    async def test_pydantic_model_strict_validation(self):
+        """With strict validation, Pydantic models should enforce exact types."""
+        mcp = FastMCP("TestServer", strict_input_validation=True)
+
+        @mcp.tool
+        def create_user(profile: UserProfile) -> str:
+            """Create a user from a profile."""
+            return f"Created user {profile.name}, age {profile.age}"
+
+        async with Client(mcp) as client:
+            # Age as string should fail with strict validation
+            with pytest.raises(Exception):
+                await client.call_tool(
+                    "create_user",
+                    {
+                        "profile": {
+                            "name": "Dave",
+                            "age": "40",  # String instead of int
+                            "email": "dave@example.com",
+                        }
+                    },
+                )
+
+
+class TestValidationErrorMessages:
+    """Test the quality of validation error messages."""
+
+    async def test_error_message_quality_strict(self):
+        """Capture error message with strict validation."""
+        mcp = FastMCP("TestServer", strict_input_validation=True)
+
+        @mcp.tool
+        def process_data(count: int, name: str) -> str:
+            """Process some data."""
+            return f"Processed {count} items for {name}"
+
+        async with Client(mcp) as client:
+            with pytest.raises(Exception) as exc_info:
+                await client.call_tool(
+                    "process_data", {"count": "not-a-number", "name": "test"}
+                )
+
+            error_msg = str(exc_info.value)
+            # Strict validation error message
+            # Should mention validation or type error
+            assert (
+                "validation" in error_msg.lower()
+                or "invalid" in error_msg.lower()
+                or "type" in error_msg.lower()
+            )
+
+    async def test_error_message_quality_pydantic(self):
+        """Capture error message with Pydantic validation."""
+        mcp = FastMCP("TestServer", strict_input_validation=False)
+
+        @mcp.tool
+        def process_data(count: int, name: str) -> str:
+            """Process some data."""
+            return f"Processed {count} items for {name}"
+
+        async with Client(mcp) as client:
+            with pytest.raises(Exception) as exc_info:
+                await client.call_tool(
+                    "process_data", {"count": "not-a-number", "name": "test"}
+                )
+
+            error_msg = str(exc_info.value)
+            # Pydantic validation error message
+            # Should be more detailed and mention validation
+            assert "validation" in error_msg.lower() or "invalid" in error_msg.lower()
+
+    async def test_missing_required_field_error(self):
+        """Test error message for missing required fields."""
+        mcp = FastMCP("TestServer", strict_input_validation=False)
+
+        @mcp.tool
+        def greet(name: str, age: int) -> str:
+            """Greet a person."""
+            return f"Hello {name}, you are {age} years old"
+
+        async with Client(mcp) as client:
+            with pytest.raises(Exception) as exc_info:
+                # Missing 'age' parameter
+                await client.call_tool("greet", {"name": "Alice"})
+
+            error_msg = str(exc_info.value)
+            # Should mention the missing field
+            assert "age" in error_msg.lower() or "required" in error_msg.lower()
+
+
+class TestEdgeCases:
+    """Test edge cases and boundary conditions."""
+
+    async def test_optional_parameters_with_coercion(self):
+        """Optional parameters should work with coercion."""
+        mcp = FastMCP("TestServer", strict_input_validation=False)
+
+        @mcp.tool
+        def format_message(text: str, repeat: int = 1) -> str:
+            """Format a message with optional repetition."""
+            return text * repeat
+
+        async with Client(mcp) as client:
+            # String for optional int parameter
+            result = await client.call_tool(
+                "format_message", {"text": "hi", "repeat": "3"}
+            )
+            assert isinstance(result.content[0], TextContent)
+            assert result.content[0].text == "hihihi"
+
+    async def test_none_values(self):
+        """Test handling of None values."""
+        mcp = FastMCP("TestServer", strict_input_validation=False)
+
+        @mcp.tool
+        def process_optional(value: int | None) -> str:
+            """Process an optional value."""
+            return f"Value: {value}"
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("process_optional", {"value": None})
+            assert isinstance(result.content[0], TextContent)
+            assert "None" in result.content[0].text
+
+    async def test_empty_string_to_int(self):
+        """Empty strings should fail conversion to int."""
+        mcp = FastMCP("TestServer", strict_input_validation=False)
+
+        @mcp.tool
+        def square(n: int) -> int:
+            """Square a number."""
+            return n * n
+
+        async with Client(mcp) as client:
+            with pytest.raises(Exception):
+                await client.call_tool("square", {"n": ""})
+
+    async def test_boolean_coercion(self):
+        """Test boolean value coercion."""
+        mcp = FastMCP("TestServer", strict_input_validation=False)
+
+        @mcp.tool
+        def toggle(enabled: bool) -> str:
+            """Toggle a feature."""
+            return f"Feature is {'enabled' if enabled else 'disabled'}"
+
+        async with Client(mcp) as client:
+            # String "true" should be coerced to boolean
+            result = await client.call_tool("toggle", {"enabled": "true"})
+            assert isinstance(result.content[0], TextContent)
+            assert "enabled" in result.content[0].text.lower()
+
+            # String "false" should be coerced to boolean
+            result = await client.call_tool("toggle", {"enabled": "false"})
+            assert isinstance(result.content[0], TextContent)
+            assert "disabled" in result.content[0].text.lower()
+
+    async def test_list_of_integers_with_string_elements(self):
+        """Test lists containing string representations of integers."""
+        mcp = FastMCP("TestServer", strict_input_validation=False)
+
+        @mcp.tool
+        def sum_numbers(numbers: list[int]) -> int:
+            """Sum a list of numbers."""
+            return sum(numbers)
+
+        async with Client(mcp) as client:
+            # List with string integers
+            result = await client.call_tool("sum_numbers", {"numbers": ["1", "2", "3"]})
+            assert isinstance(result.content[0], TextContent)
+            assert result.content[0].text == "6"
+
+
+class TestExpectedToolFailureLogging:
+    async def test_validation_error_logs_warning_without_traceback(self, caplog):
+        mcp = FastMCP("TestServer", strict_input_validation=False)
+
+        @mcp.tool
+        def create_user(profile: UserProfile) -> str:
+            return profile.name
+
+        with caplog.at_level("DEBUG", logger="fastmcp.server.server"):
+            async with Client(mcp) as client:
+                with pytest.raises(ToolError):
+                    await client.call_tool(
+                        "create_user",
+                        {"profile": {"name": "x", "age": "nope", "email": "e"}},
+                    )
+
+        records = [
+            r for r in caplog.records if "Invalid arguments for tool" in r.getMessage()
+        ]
+        assert records, "expected a single 'Invalid arguments' warning"
+        assert records[0].levelname == "WARNING"
+        assert records[0].exc_info is None
+        assert "int_parsing" in records[0].getMessage()
+        assert "errors.pydantic.dev" not in records[0].getMessage()
+
+    async def test_tool_raised_tool_error_logs_without_traceback(self, caplog):
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        def do_thing() -> str:
+            raise ToolError("structured failure payload")
+
+        with caplog.at_level("DEBUG", logger="fastmcp.server.server"):
+            async with Client(mcp) as client:
+                with pytest.raises(ToolError):
+                    await client.call_tool("do_thing", {})
+
+        records = [
+            r
+            for r in caplog.records
+            if r.getMessage() == "Error calling tool 'do_thing'"
+        ]
+        assert records, "expected an 'Error calling tool' log without traceback"
+        assert records[0].levelname == "ERROR"
+        assert not records[0].exc_info
+
+    async def test_unexpected_exception_still_logs_with_traceback(self, caplog):
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        def do_thing() -> str:
+            raise RuntimeError("actual bug")
+
+        with caplog.at_level("DEBUG", logger="fastmcp.server.server"):
+            async with Client(mcp) as client:
+                with pytest.raises(ToolError):
+                    await client.call_tool("do_thing", {})
+
+        records = [
+            r
+            for r in caplog.records
+            if r.getMessage() == "Error calling tool 'do_thing'"
+        ]
+        assert records, "expected an 'Error calling tool' exception log"
+        assert records[0].levelname == "ERROR"
+        assert records[0].exc_info is not None
diff --git a/tests/server/test_log_level.py b/tests/server/test_log_level.py
new file mode 100644
index 0000000..4d0bda6
--- /dev/null
+++ b/tests/server/test_log_level.py
@@ -0,0 +1,111 @@
+"""Test log_level parameter support in FastMCP server."""
+
+import asyncio
+import socket
+from unittest.mock import AsyncMock, patch
+
+from fastmcp import FastMCP
+
+
+class TestLogLevelParameter:
+    """Test that log_level parameter is properly accepted by run methods."""
+
+    async def test_run_stdio_accepts_log_level(self):
+        """Test that run_stdio_async accepts log_level parameter."""
+        server = FastMCP("TestServer")
+
+        # Mock the stdio_server to avoid actual stdio operations
+        with patch("fastmcp.server.mixins.transport.stdio_server") as mock_stdio:
+            mock_stdio.return_value.__aenter__ = AsyncMock(
+                return_value=(AsyncMock(), AsyncMock())
+            )
+            mock_stdio.return_value.__aexit__ = AsyncMock()
+
+            # Mock the underlying MCP server run method
+            with patch.object(server._mcp_server, "run", new_callable=AsyncMock):
+                try:
+                    # This should accept the log_level parameter without error
+                    await asyncio.wait_for(
+                        server.run_stdio_async(log_level="DEBUG", show_banner=False),
+                        timeout=0.1,
+                    )
+                except asyncio.TimeoutError:
+                    pass  # Expected since we're mocking
+
+    async def test_run_http_accepts_log_level(self):
+        """Test that run_http_async accepts log_level parameter."""
+        server = FastMCP("TestServer")
+
+        # Mock uvicorn to avoid actual server start
+        with patch(
+            "fastmcp.server.mixins.transport.uvicorn.Server"
+        ) as mock_server_class:
+            mock_instance = mock_server_class.return_value
+            mock_instance.serve = AsyncMock()
+
+            # This should accept the log_level parameter without error
+            await server.run_http_async(
+                log_level="INFO", show_banner=False, host="127.0.0.1", port=8000
+            )
+
+            # Verify serve was called
+            mock_instance.serve.assert_called_once()
+
+    async def test_run_http_passes_sockets_to_uvicorn(self):
+        """Test that run_http_async forwards pre-bound sockets to Uvicorn."""
+        server = FastMCP("TestServer")
+
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            with patch(
+                "fastmcp.server.mixins.transport.uvicorn.Server"
+            ) as mock_server_class:
+                mock_instance = mock_server_class.return_value
+                mock_instance.serve = AsyncMock()
+
+                await server.run_http_async(
+                    show_banner=False,
+                    host="127.0.0.1",
+                    port=8000,
+                    sockets=[sock],
+                )
+
+                mock_instance.serve.assert_called_once_with(sockets=[sock])
+
+    async def test_run_async_passes_log_level(self):
+        """Test that run_async passes log_level to transport methods."""
+        server = FastMCP("TestServer")
+
+        # Test stdio transport
+        with patch.object(
+            server, "run_stdio_async", new_callable=AsyncMock
+        ) as mock_stdio:
+            await server.run_async(transport="stdio", log_level="WARNING")
+            mock_stdio.assert_called_once_with(show_banner=True, log_level="WARNING")
+
+        # Test http transport
+        with patch.object(
+            server, "run_http_async", new_callable=AsyncMock
+        ) as mock_http:
+            await server.run_async(transport="http", log_level="ERROR")
+            mock_http.assert_called_once_with(
+                transport="http", show_banner=True, log_level="ERROR"
+            )
+
+    def test_sync_run_accepts_log_level(self):
+        """Test that the synchronous run method accepts log_level."""
+        server = FastMCP("TestServer")
+
+        with patch.object(server, "run_async", new_callable=AsyncMock):
+            # Mock anyio.run to avoid actual async execution
+            with patch("anyio.run") as mock_anyio_run:
+                server.run(transport="stdio", log_level="CRITICAL")
+
+                # Verify anyio.run was called
+                mock_anyio_run.assert_called_once()
+
+                # Get the function that was passed to anyio.run
+                called_func = mock_anyio_run.call_args[0][0]
+
+                # The function should be a partial that includes log_level
+                assert hasattr(called_func, "keywords")
+                assert called_func.keywords.get("log_level") == "CRITICAL"
diff --git a/tests/server/test_logging.py b/tests/server/test_logging.py
new file mode 100644
index 0000000..b8d1237
--- /dev/null
+++ b/tests/server/test_logging.py
@@ -0,0 +1,192 @@
+import asyncio
+import logging
+from unittest.mock import AsyncMock, Mock, patch
+
+import anyio
+import pytest
+
+from fastmcp.server.server import FastMCP
+
+
+class CustomLogFormatterForTest(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        return f"TEST_FORMAT::{record.levelname}::{record.name}::{record.getMessage()}"
+
+
+@pytest.fixture
+def mcp_server() -> FastMCP:
+    return FastMCP(name="TestLogServer")
+
+
+@patch("fastmcp.server.mixins.transport.uvicorn.Server")
+@patch("fastmcp.server.mixins.transport.uvicorn.Config")
+async def test_uvicorn_logging_default_level(
+    mock_uvicorn_config_constructor: Mock,
+    mock_uvicorn_server_constructor: Mock,
+    mcp_server: FastMCP,
+):
+    """Tests that FastMCP passes log_level to uvicorn.Config if no log_config is given."""
+    mock_server_instance = AsyncMock()
+    mock_uvicorn_server_constructor.return_value = mock_server_instance
+    serve_finished_event = anyio.Event()
+    mock_server_instance.serve.side_effect = serve_finished_event.wait
+
+    test_log_level = "warning"
+
+    server_task = asyncio.create_task(
+        mcp_server.run_http_async(log_level=test_log_level, port=8003)
+    )
+    await mcp_server._started.wait()
+
+    mock_uvicorn_config_constructor.assert_called_once()
+    _, kwargs_config = mock_uvicorn_config_constructor.call_args
+
+    assert kwargs_config.get("log_level") == test_log_level.lower()
+    assert "log_config" not in kwargs_config
+
+    mock_uvicorn_server_constructor.assert_called_once_with(
+        mock_uvicorn_config_constructor.return_value
+    )
+    mock_server_instance.serve.assert_awaited_once()
+
+    # Signal the mock to finish and cancel with timeout
+    # Required for uvicorn 0.39+ due to context isolation
+    serve_finished_event.set()
+    server_task.cancel()
+    try:
+        await asyncio.wait_for(server_task, timeout=2.0)
+    except (asyncio.CancelledError, asyncio.TimeoutError):
+        pass
+
+
+@patch("fastmcp.server.mixins.transport.uvicorn.Server")
+@patch("fastmcp.server.mixins.transport.uvicorn.Config")
+async def test_uvicorn_logging_with_custom_log_config(
+    mock_uvicorn_config_constructor: Mock,
+    mock_uvicorn_server_constructor: Mock,
+    mcp_server: FastMCP,
+):
+    """Tests that FastMCP passes log_config to uvicorn.Config and not log_level."""
+    mock_server_instance = AsyncMock()
+    mock_uvicorn_server_constructor.return_value = mock_server_instance
+    serve_finished_event = anyio.Event()
+    mock_server_instance.serve.side_effect = serve_finished_event.wait
+
+    sample_log_config = {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "formatters": {
+            "test_formatter": {
+                "()": "tests.server.test_logging.CustomLogFormatterForTest"
+            }
+        },
+        "handlers": {
+            "test_handler": {
+                "formatter": "test_formatter",
+                "class": "logging.StreamHandler",
+                "stream": "ext://sys.stdout",
+            }
+        },
+        "loggers": {
+            "uvicorn.error": {
+                "handlers": ["test_handler"],
+                "level": "INFO",
+                "propagate": False,
+            }
+        },
+    }
+
+    server_task = asyncio.create_task(
+        mcp_server.run_http_async(
+            uvicorn_config={"log_config": sample_log_config}, port=8004
+        )
+    )
+    await mcp_server._started.wait()
+
+    mock_uvicorn_config_constructor.assert_called_once()
+    _, kwargs_config = mock_uvicorn_config_constructor.call_args
+
+    assert kwargs_config.get("log_config") == sample_log_config
+    assert "log_level" not in kwargs_config
+
+    mock_uvicorn_server_constructor.assert_called_once_with(
+        mock_uvicorn_config_constructor.return_value
+    )
+    mock_server_instance.serve.assert_awaited_once()
+
+    # Signal the mock to finish and cancel with timeout
+    # Required for uvicorn 0.39+ due to context isolation
+    serve_finished_event.set()
+    server_task.cancel()
+    try:
+        await asyncio.wait_for(server_task, timeout=2.0)
+    except (asyncio.CancelledError, asyncio.TimeoutError):
+        pass
+
+
+@patch("fastmcp.server.mixins.transport.uvicorn.Server")
+@patch("fastmcp.server.mixins.transport.uvicorn.Config")
+async def test_uvicorn_logging_custom_log_config_overrides_log_level_param(
+    mock_uvicorn_config_constructor: Mock,
+    mock_uvicorn_server_constructor: Mock,
+    mcp_server: FastMCP,
+):
+    """Tests log_config precedence if log_level is also passed to run_http_async."""
+    mock_server_instance = AsyncMock()
+    mock_uvicorn_server_constructor.return_value = mock_server_instance
+    serve_finished_event = anyio.Event()
+    mock_server_instance.serve.side_effect = serve_finished_event.wait
+
+    sample_log_config = {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "formatters": {
+            "test_formatter": {
+                "()": "tests.server.test_logging.CustomLogFormatterForTest"
+            }
+        },
+        "handlers": {
+            "test_handler": {
+                "formatter": "test_formatter",
+                "class": "logging.StreamHandler",
+                "stream": "ext://sys.stdout",
+            }
+        },
+        "loggers": {
+            "uvicorn.error": {
+                "handlers": ["test_handler"],
+                "level": "INFO",
+                "propagate": False,
+            }
+        },
+    }
+    explicit_log_level = "debug"
+
+    server_task = asyncio.create_task(
+        mcp_server.run_http_async(
+            log_level=explicit_log_level,
+            uvicorn_config={"log_config": sample_log_config},
+            port=8005,
+        )
+    )
+    await mcp_server._started.wait()
+
+    mock_uvicorn_config_constructor.assert_called_once()
+    _, kwargs_config = mock_uvicorn_config_constructor.call_args
+
+    assert kwargs_config.get("log_config") == sample_log_config
+    assert "log_level" not in kwargs_config
+
+    mock_uvicorn_server_constructor.assert_called_once_with(
+        mock_uvicorn_config_constructor.return_value
+    )
+    mock_server_instance.serve.assert_awaited_once()
+
+    # Signal the mock to finish and cancel with timeout
+    # Required for uvicorn 0.39+ due to context isolation
+    serve_finished_event.set()
+    server_task.cancel()
+    try:
+        await asyncio.wait_for(server_task, timeout=2.0)
+    except (asyncio.CancelledError, asyncio.TimeoutError):
+        pass
diff --git a/tests/server/test_pagination.py b/tests/server/test_pagination.py
new file mode 100644
index 0000000..89d3ec7
--- /dev/null
+++ b/tests/server/test_pagination.py
@@ -0,0 +1,526 @@
+"""Tests for MCP pagination support."""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+import mcp_types
+import pytest
+from mcp.shared.exceptions import MCPError
+
+from fastmcp import Client, FastMCP
+from fastmcp.utilities.pagination import CursorState, paginate_sequence
+
+
+class TestCursorEncoding:
+    """Tests for cursor encoding/decoding."""
+
+    def test_encode_decode_roundtrip(self) -> None:
+        """Cursor should survive encode/decode roundtrip."""
+        state = CursorState(offset=100)
+        encoded = state.encode()
+        decoded = CursorState.decode(encoded)
+        assert decoded.offset == 100
+
+    def test_encode_produces_string(self) -> None:
+        """Encoded cursor should be a string."""
+        state = CursorState(offset=50)
+        encoded = state.encode()
+        assert isinstance(encoded, str)
+        assert len(encoded) > 0
+
+    def test_decode_invalid_base64_raises(self) -> None:
+        """Invalid base64 should raise ValueError."""
+        with pytest.raises(ValueError, match="Invalid cursor"):
+            CursorState.decode("not-valid-base64!!!")
+
+    def test_decode_invalid_json_raises(self) -> None:
+        """Valid base64 but invalid JSON should raise ValueError."""
+        import base64
+
+        invalid = base64.urlsafe_b64encode(b"not json").decode()
+        with pytest.raises(ValueError, match="Invalid cursor"):
+            CursorState.decode(invalid)
+
+    def test_decode_missing_offset_raises(self) -> None:
+        """JSON missing the offset key should raise ValueError."""
+        import base64
+        import json
+
+        invalid = base64.urlsafe_b64encode(json.dumps({"x": 1}).encode()).decode()
+        with pytest.raises(ValueError, match="Invalid cursor"):
+            CursorState.decode(invalid)
+
+
+class TestPaginateSequence:
+    """Tests for the paginate_sequence helper."""
+
+    def test_first_page_no_cursor(self) -> None:
+        """First page should start from beginning."""
+        items = list(range(25))
+        page, cursor = paginate_sequence(items, None, 10)
+        assert page == list(range(10))
+        assert cursor is not None
+
+    def test_second_page_with_cursor(self) -> None:
+        """Second page should continue from cursor."""
+        items = list(range(25))
+        _, cursor = paginate_sequence(items, None, 10)
+        page, next_cursor = paginate_sequence(items, cursor, 10)
+        assert page == list(range(10, 20))
+        assert next_cursor is not None
+
+    def test_last_page_returns_none_cursor(self) -> None:
+        """Last page should return None cursor."""
+        items = list(range(25))
+        _, c1 = paginate_sequence(items, None, 10)
+        _, c2 = paginate_sequence(items, c1, 10)
+        page, next_cursor = paginate_sequence(items, c2, 10)
+        assert page == list(range(20, 25))
+        assert next_cursor is None
+
+    def test_empty_list(self) -> None:
+        """Empty list should return empty page and no cursor."""
+        page, cursor = paginate_sequence([], None, 10)
+        assert page == []
+        assert cursor is None
+
+    def test_exact_page_size(self) -> None:
+        """List exactly matching page size should return no cursor."""
+        items = list(range(10))
+        page, cursor = paginate_sequence(items, None, 10)
+        assert page == items
+        assert cursor is None
+
+    def test_smaller_than_page_size(self) -> None:
+        """List smaller than page size should return all items."""
+        items = list(range(5))
+        page, cursor = paginate_sequence(items, None, 10)
+        assert page == items
+        assert cursor is None
+
+    def test_invalid_cursor_raises(self) -> None:
+        """Invalid cursor should raise ValueError."""
+        with pytest.raises(ValueError, match="Invalid cursor"):
+            paginate_sequence([1, 2, 3], "invalid!", 10)
+
+
+class TestServerPagination:
+    """Integration tests for server pagination."""
+
+    async def test_tools_pagination_returns_all_tools(self) -> None:
+        """Client should receive all tools across paginated requests."""
+        server = FastMCP(list_page_size=10)
+
+        for i in range(25):
+
+            @server.tool(name=f"tool_{i}")
+            def make_tool() -> str:
+                return "ok"
+
+        async with Client(server) as client:
+            tools = await client.list_tools()
+            assert len(tools) == 25
+            tool_names = {t.name for t in tools}
+            assert tool_names == {f"tool_{i}" for i in range(25)}
+
+    async def test_resources_pagination_returns_all_resources(self) -> None:
+        """Client should receive all resources across paginated requests."""
+        server = FastMCP(list_page_size=10)
+
+        for i in range(25):
+
+            @server.resource(f"test://resource_{i}")
+            def make_resource() -> str:
+                return "data"
+
+        async with Client(server) as client:
+            resources = await client.list_resources()
+            assert len(resources) == 25
+
+    async def test_prompts_pagination_returns_all_prompts(self) -> None:
+        """Client should receive all prompts across paginated requests."""
+        server = FastMCP(list_page_size=10)
+
+        for i in range(25):
+
+            @server.prompt(name=f"prompt_{i}")
+            def make_prompt() -> str:
+                return "text"
+
+        async with Client(server) as client:
+            prompts = await client.list_prompts()
+            assert len(prompts) == 25
+
+    async def test_manual_pagination(self) -> None:
+        """Client can manually paginate using cursor."""
+        server = FastMCP(list_page_size=10)
+
+        for i in range(25):
+
+            @server.tool(name=f"tool_{i}")
+            def make_tool() -> str:
+                return "ok"
+
+        async with Client(server) as client:
+            # First page
+            result = await client.list_tools_mcp()
+            assert len(result.tools) == 10
+            assert result.next_cursor is not None
+
+            # Second page
+            result2 = await client.list_tools_mcp(cursor=result.next_cursor)
+            assert len(result2.tools) == 10
+            assert result2.next_cursor is not None
+
+            # Third (last) page
+            result3 = await client.list_tools_mcp(cursor=result2.next_cursor)
+            assert len(result3.tools) == 5
+            assert result3.next_cursor is None
+
+    async def test_invalid_cursor_returns_error(self) -> None:
+        """Server should return MCP error for invalid cursor."""
+        server = FastMCP(list_page_size=10)
+
+        @server.tool
+        def my_tool() -> str:
+            return "ok"
+
+        async with Client(server) as client:
+            with pytest.raises(MCPError) as exc:
+                await client.list_tools_mcp(cursor="invalid!")
+            assert exc.value.error.code == -32602
+
+    async def test_no_pagination_when_disabled(self) -> None:
+        """Without list_page_size, all items returned at once."""
+        server = FastMCP()  # No pagination
+
+        for i in range(25):
+
+            @server.tool(name=f"tool_{i}")
+            def make_tool() -> str:
+                return "ok"
+
+        async with Client(server) as client:
+            result = await client.list_tools_mcp()
+            assert len(result.tools) == 25
+            assert result.next_cursor is None
+
+    async def test_pagination_exact_page_boundary(self) -> None:
+        """Test pagination at exact page boundaries."""
+        server = FastMCP(list_page_size=10)
+
+        for i in range(20):  # Exactly 2 pages
+
+            @server.tool(name=f"tool_{i}")
+            def make_tool() -> str:
+                return "ok"
+
+        async with Client(server) as client:
+            # First page
+            result = await client.list_tools_mcp()
+            assert len(result.tools) == 10
+            assert result.next_cursor is not None
+
+            # Second (last) page
+            result2 = await client.list_tools_mcp(cursor=result.next_cursor)
+            assert len(result2.tools) == 10
+            assert result2.next_cursor is None
+
+
+class TestPageSizeValidation:
+    """Tests for list_page_size validation."""
+
+    def test_zero_page_size_raises(self) -> None:
+        """Zero page size should raise ValueError."""
+        with pytest.raises(
+            ValueError, match="list_page_size must be a positive integer"
+        ):
+            FastMCP(list_page_size=0)
+
+    def test_negative_page_size_raises(self) -> None:
+        """Negative page size should raise ValueError."""
+        with pytest.raises(
+            ValueError, match="list_page_size must be a positive integer"
+        ):
+            FastMCP(list_page_size=-1)
+
+
+class TestPaginationCycleDetection:
+    """Tests that auto-pagination terminates when the server returns cycling cursors."""
+
+    async def test_tools_constant_cursor_terminates(self) -> None:
+        """list_tools should stop if the server always returns the same cursor."""
+        server = FastMCP()
+
+        @server.tool
+        def my_tool() -> str:
+            return "ok"
+
+        async with Client(server) as client:
+            original = client.list_tools_mcp
+
+            async def returning_constant_cursor(
+                *,
+                cursor: str | None = None,
+            ) -> mcp_types.ListToolsResult:
+                result = await original(cursor=cursor)
+                result.next_cursor = "stuck"
+                return result
+
+            with patch.object(
+                client, "list_tools_mcp", side_effect=returning_constant_cursor
+            ):
+                tools = await client.list_tools()
+
+            # Should get tools from first page + one duplicate (the retry before
+            # detecting the cycle), then stop.
+            assert len(tools) == 2
+            assert all(t.name == "my_tool" for t in tools)
+
+    async def test_prompts_constant_cursor_terminates(self) -> None:
+        """list_prompts should stop if the server always returns the same cursor."""
+        server = FastMCP()
+
+        @server.prompt
+        def my_prompt() -> str:
+            return "text"
+
+        async with Client(server) as client:
+            original = client.list_prompts_mcp
+
+            async def returning_constant_cursor(
+                *,
+                cursor: str | None = None,
+            ) -> mcp_types.ListPromptsResult:
+                result = await original(cursor=cursor)
+                result.next_cursor = "stuck"
+                return result
+
+            with patch.object(
+                client, "list_prompts_mcp", side_effect=returning_constant_cursor
+            ):
+                prompts = await client.list_prompts()
+
+            assert len(prompts) == 2
+            assert all(p.name == "my_prompt" for p in prompts)
+
+    async def test_resources_constant_cursor_terminates(self) -> None:
+        """list_resources should stop if the server always returns the same cursor."""
+        server = FastMCP()
+
+        @server.resource("test://r")
+        def my_resource() -> str:
+            return "data"
+
+        async with Client(server) as client:
+            original = client.list_resources_mcp
+
+            async def returning_constant_cursor(
+                *,
+                cursor: str | None = None,
+            ) -> mcp_types.ListResourcesResult:
+                result = await original(cursor=cursor)
+                result.next_cursor = "stuck"
+                return result
+
+            with patch.object(
+                client, "list_resources_mcp", side_effect=returning_constant_cursor
+            ):
+                resources = await client.list_resources()
+
+            assert len(resources) == 2
+            assert all(r.name == "my_resource" for r in resources)
+
+    async def test_resource_templates_constant_cursor_terminates(self) -> None:
+        """list_resource_templates should stop if the server always returns the same cursor."""
+        server = FastMCP()
+
+        @server.resource("test://items/{item_id}")
+        def my_template(item_id: str) -> str:
+            return item_id
+
+        async with Client(server) as client:
+            original = client.list_resource_templates_mcp
+
+            async def returning_constant_cursor(
+                *,
+                cursor: str | None = None,
+            ) -> mcp_types.ListResourceTemplatesResult:
+                result = await original(cursor=cursor)
+                result.next_cursor = "stuck"
+                return result
+
+            with patch.object(
+                client,
+                "list_resource_templates_mcp",
+                side_effect=returning_constant_cursor,
+            ):
+                templates = await client.list_resource_templates()
+
+            assert len(templates) == 2
+
+    async def test_cycling_cursors_terminates(self) -> None:
+        """list_tools should stop if the server cycles through a set of cursors."""
+        server = FastMCP()
+
+        @server.tool
+        def my_tool() -> str:
+            return "ok"
+
+        async with Client(server) as client:
+            call_count = 0
+            original = client.list_tools_mcp
+
+            async def returning_cycling_cursor(
+                *,
+                cursor: str | None = None,
+            ) -> mcp_types.ListToolsResult:
+                nonlocal call_count
+                result = await original(cursor=cursor)
+                # Cycle through A -> B -> C -> A
+                cursors = ["A", "B", "C"]
+                result.next_cursor = cursors[call_count % 3]
+                call_count += 1
+                return result
+
+            with patch.object(
+                client, "list_tools_mcp", side_effect=returning_cycling_cursor
+            ):
+                tools = await client.list_tools()
+
+            # A, B, C seen, then A is a duplicate → 4 calls total
+            assert call_count == 4
+            assert len(tools) == 4
+
+    async def test_empty_string_cursor_terminates(self) -> None:
+        """list_tools should stop if the server returns an empty string cursor."""
+        server = FastMCP()
+
+        @server.tool
+        def my_tool() -> str:
+            return "ok"
+
+        async with Client(server) as client:
+            original = client.list_tools_mcp
+
+            async def returning_empty_cursor(
+                *,
+                cursor: str | None = None,
+            ) -> mcp_types.ListToolsResult:
+                result = await original(cursor=cursor)
+                result.next_cursor = ""
+                return result
+
+            with patch.object(
+                client, "list_tools_mcp", side_effect=returning_empty_cursor
+            ):
+                tools = await client.list_tools()
+
+            assert len(tools) == 1
+            assert tools[0].name == "my_tool"
+
+    async def test_tools_raises_on_auto_pagination_limit(self) -> None:
+        """list_tools should raise RuntimeError after exceeding max_pages."""
+        server = FastMCP()
+
+        @server.tool
+        def my_tool() -> str:
+            return "ok"
+
+        async with Client(server) as client:
+            original = client.list_tools_mcp
+            call_count = 0
+
+            async def returning_unique_cursor(
+                *,
+                cursor: str | None = None,
+            ) -> mcp_types.ListToolsResult:
+                nonlocal call_count
+                result = await original(cursor=cursor)
+                call_count += 1
+                result.next_cursor = f"cursor-{call_count}"
+                return result
+
+            with (
+                patch.object(
+                    client, "list_tools_mcp", side_effect=returning_unique_cursor
+                ),
+                pytest.raises(RuntimeError, match="auto-pagination limit"),
+            ):
+                await client.list_tools(max_pages=5)
+
+    async def test_resources_raises_on_auto_pagination_limit(self) -> None:
+        """list_resources should raise RuntimeError after exceeding max_pages."""
+        server = FastMCP()
+
+        @server.resource("test://r")
+        def my_resource() -> str:
+            return "data"
+
+        async with Client(server) as client:
+            original = client.list_resources_mcp
+            call_count = 0
+
+            async def returning_unique_cursor(
+                *,
+                cursor: str | None = None,
+            ) -> mcp_types.ListResourcesResult:
+                nonlocal call_count
+                result = await original(cursor=cursor)
+                call_count += 1
+                result.next_cursor = f"cursor-{call_count}"
+                return result
+
+            with (
+                patch.object(
+                    client, "list_resources_mcp", side_effect=returning_unique_cursor
+                ),
+                pytest.raises(RuntimeError, match="auto-pagination limit"),
+            ):
+                await client.list_resources(max_pages=5)
+
+    async def test_prompts_raises_on_auto_pagination_limit(self) -> None:
+        """list_prompts should raise RuntimeError after exceeding max_pages."""
+        server = FastMCP()
+
+        @server.prompt
+        def my_prompt() -> str:
+            return "text"
+
+        async with Client(server) as client:
+            original = client.list_prompts_mcp
+            call_count = 0
+
+            async def returning_unique_cursor(
+                *,
+                cursor: str | None = None,
+            ) -> mcp_types.ListPromptsResult:
+                nonlocal call_count
+                result = await original(cursor=cursor)
+                call_count += 1
+                result.next_cursor = f"cursor-{call_count}"
+                return result
+
+            with (
+                patch.object(
+                    client, "list_prompts_mcp", side_effect=returning_unique_cursor
+                ),
+                pytest.raises(RuntimeError, match="auto-pagination limit"),
+            ):
+                await client.list_prompts(max_pages=5)
+
+    async def test_normal_pagination_unaffected(self) -> None:
+        """Cycle detection should not interfere with normal pagination."""
+        server = FastMCP(list_page_size=10)
+
+        for i in range(25):
+
+            @server.tool(name=f"tool_{i}")
+            def make_tool() -> str:
+                return "ok"
+
+        async with Client(server) as client:
+            tools = await client.list_tools()
+            assert len(tools) == 25
+            assert len({t.name for t in tools}) == 25
diff --git a/tests/server/test_protocol_eras.py b/tests/server/test_protocol_eras.py
new file mode 100644
index 0000000..ca9a8ac
--- /dev/null
+++ b/tests/server/test_protocol_eras.py
@@ -0,0 +1,734 @@
+"""Dual-era protocol matrix: one FastMCP server served over both MCP protocol eras.
+
+FastMCP must serve the legacy (initialize-handshake, 2025-11-25) era and the
+modern (server/discover, 2026-07-28) era from the same server object. The test
+harness is the v2 SDK's own first-class client, ``mcp.client.Client``, which
+resolves an in-process ``Server`` directly:
+
+* ``mode='legacy'`` forces the initialize handshake (2025-11-25 in-memory).
+* ``mode='auto'`` probes ``server/discover`` and negotiates 2026-07-28.
+* ``mode='2026-07-28'`` pins the modern version and adopts a synthesized
+  ``DiscoverResult`` (no probe).
+
+A FastMCP server exposes its lowlevel ``Server`` as ``fastmcp_server._mcp_server``;
+that is what we hand to the SDK client, mirroring how
+``mcp.client._memory.InMemoryTransport`` unwraps servers.
+
+Several cells characterize behavior that is a verified SDK-era contract rather
+than a FastMCP choice; those are flagged inline and cross-referenced to the
+migration feedback dossier (``<scratchpad>/specs/sdk-feedback.md``).
+"""
+
+from __future__ import annotations
+
+import mcp_types as types
+import pytest
+from mcp.client import Client as SDKClient
+from mcp.client.session import ClientRequestContext
+from mcp.server import Server as LowLevelServer
+from mcp.shared.exceptions import MCPError
+from mcp_types import methods
+from mcp_types.version import (
+    HANDSHAKE_PROTOCOL_VERSIONS,
+    MODERN_PROTOCOL_VERSIONS,
+)
+from pydantic import FileUrl
+
+from fastmcp import Client as FastMCPClient
+from fastmcp import Context, FastMCP, settings
+from fastmcp.server.elicitation import AcceptedElicitation
+from fastmcp.server.middleware import Middleware
+
+# Modes that reach the modern (2026-07-28) era via the SDK client.
+MODERN_MODES = ["auto", "2026-07-28"]
+# Both eras, for cells that must produce identical semantics on each.
+ALL_MODES = ["legacy", *MODERN_MODES]
+
+
+@pytest.fixture
+def dual_era_server() -> FastMCP:
+    """A single FastMCP server exercising every core MCP object type.
+
+    Deliberately minimal and side-effect free so the same instance can be
+    driven concurrently by legacy and modern clients within one test.
+    """
+    mcp = FastMCP("dual-era")
+
+    @mcp.tool
+    def add(a: int, b: int) -> int:
+        """Structured-output tool (returns a scalar wrapped as {"result": ...})."""
+        return a + b
+
+    @mcp.resource("data://config")
+    def config() -> dict:
+        return {"version": 1}
+
+    @mcp.resource("data://item/{item_id}")
+    def item(item_id: str) -> str:
+        return f"item-{item_id}"
+
+    @mcp.prompt
+    def summarize(topic: str) -> str:
+        return f"Summarize {topic}"
+
+    return mcp
+
+
+def _server(mcp: FastMCP) -> LowLevelServer:
+    """The lowlevel Server the SDK client connects to in-process."""
+    return mcp._mcp_server
+
+
+def _texts(blocks) -> list[str]:
+    """Text from CallToolResult.content blocks (TextContent)."""
+    return [b.text for b in blocks if isinstance(b, types.TextContent)]
+
+
+def _resource_texts(blocks) -> list[str]:
+    """Text from ReadResourceResult.contents blocks (TextResourceContents)."""
+    return [b.text for b in blocks if isinstance(b, types.TextResourceContents)]
+
+
+# ---------------------------------------------------------------------------
+# 1. Core operations produce identical semantics on BOTH eras
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize("mode", ALL_MODES)
+async def test_list_tools_both_eras(dual_era_server, mode):
+    async with SDKClient(_server(dual_era_server), mode=mode) as client:
+        result = await client.list_tools()
+    assert [t.name for t in result.tools] == ["add"]
+
+
+@pytest.mark.parametrize("mode", ALL_MODES)
+async def test_call_tool_structured_output_both_eras(dual_era_server, mode):
+    async with SDKClient(_server(dual_era_server), mode=mode) as client:
+        result = await client.call_tool("add", {"a": 2, "b": 3})
+    assert result.is_error is False
+    assert result.structured_content == {"result": 5}
+    assert _texts(result.content) == ["5"]
+
+
+@pytest.mark.parametrize("mode", ALL_MODES)
+async def test_list_resources_both_eras(dual_era_server, mode):
+    async with SDKClient(_server(dual_era_server), mode=mode) as client:
+        result = await client.list_resources()
+    assert [str(r.uri) for r in result.resources] == ["data://config"]
+
+
+@pytest.mark.parametrize("mode", ALL_MODES)
+async def test_read_resource_both_eras(dual_era_server, mode):
+    async with SDKClient(_server(dual_era_server), mode=mode) as client:
+        result = await client.read_resource("data://config")
+    assert _resource_texts(result.contents) == ['{"version": 1}']
+
+
+@pytest.mark.parametrize("mode", ALL_MODES)
+async def test_read_resource_template_both_eras(dual_era_server, mode):
+    async with SDKClient(_server(dual_era_server), mode=mode) as client:
+        result = await client.read_resource("data://item/42")
+    assert _resource_texts(result.contents) == ["item-42"]
+
+
+@pytest.mark.parametrize("mode", ALL_MODES)
+async def test_list_prompts_both_eras(dual_era_server, mode):
+    async with SDKClient(_server(dual_era_server), mode=mode) as client:
+        result = await client.list_prompts()
+    assert [p.name for p in result.prompts] == ["summarize"]
+
+
+@pytest.mark.parametrize("mode", ALL_MODES)
+async def test_get_prompt_both_eras(dual_era_server, mode):
+    async with SDKClient(_server(dual_era_server), mode=mode) as client:
+        result = await client.get_prompt("summarize", {"topic": "cats"})
+    rendered = [
+        m.content.text
+        for m in result.messages
+        if isinstance(m.content, types.TextContent)
+    ]
+    assert rendered == ["Summarize cats"]
+
+
+@pytest.mark.parametrize("mode", ALL_MODES)
+async def test_complete_parity_both_eras(dual_era_server, mode):
+    """FastMCP registers no completion handler, so `completion/complete` is
+    method-not-found. The point of this cell is parity: the *same* -32601
+    surfaces on both eras (2026 did not change the unsupported-method contract).
+    """
+    async with SDKClient(_server(dual_era_server), mode=mode) as client:
+        with pytest.raises(MCPError) as excinfo:
+            await client.complete(
+                types.PromptReference(name="summarize"),
+                {"name": "topic", "value": "c"},
+            )
+    assert excinfo.value.code == types.METHOD_NOT_FOUND
+
+
+# ---------------------------------------------------------------------------
+# 2. Discovery / identity: which negotiation path each mode takes
+# ---------------------------------------------------------------------------
+
+
+async def test_legacy_uses_initialize_handshake(dual_era_server):
+    """Legacy mode runs the initialize handshake and reports a handshake-era
+    protocol version with server_info carried in the InitializeResult.
+    """
+    async with SDKClient(_server(dual_era_server), mode="legacy") as client:
+        assert client.protocol_version == "2025-11-25"
+        assert client.server_info.name == "dual-era"
+
+
+async def test_auto_negotiates_modern_via_discover(dual_era_server):
+    """`mode='auto'` probes server/discover and adopts 2026-07-28, populating
+    server_info/capabilities from the DiscoverResult.
+    """
+    async with SDKClient(_server(dual_era_server), mode="auto") as client:
+        assert client.protocol_version == "2026-07-28"
+        # server/discover carries identity, unlike the synthesized pin below.
+        assert client.server_info.name == "dual-era"
+        assert client.server_capabilities is not None
+
+
+async def test_pinned_modern_adopts_without_probe(dual_era_server):
+    """Pinning `mode='2026-07-28'` adopts the version directly. With no
+    `prior_discover`, the SDK synthesizes a minimal DiscoverResult, so
+    server_info is empty even though the protocol version is modern.
+
+    Characterization of the SDK's synthesize-discover path (mcp.client.client
+    `_synthesize_discover`): a pin without prior_discover trades identity for
+    skipping the probe round-trip.
+    """
+    async with SDKClient(_server(dual_era_server), mode="2026-07-28") as client:
+        assert client.protocol_version == "2026-07-28"
+        assert client.server_info.name == ""
+
+
+# ---------------------------------------------------------------------------
+# 3. Push-feature degradation on 2026 vs. working callbacks on legacy
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def push_server() -> FastMCP:
+    mcp = FastMCP("push")
+
+    @mcp.tool
+    async def do_elicit(ctx: Context) -> str:
+        result = await ctx.elicit("pick a value", response_type=int)
+        assert isinstance(result, AcceptedElicitation)
+        return f"elicited {result.data}"
+
+    @mcp.tool
+    async def do_sample(ctx: Context) -> str:
+        result = await ctx.sample("hello")
+        return f"sampled {result.text}"
+
+    @mcp.tool
+    async def do_list_roots(ctx: Context) -> str:
+        roots = await ctx.list_roots()
+        return f"roots {[str(r.uri) for r in roots]}"
+
+    @mcp.tool
+    async def do_log(ctx: Context) -> str:
+        await ctx.info("a log line")
+        return "logged"
+
+    return mcp
+
+
+async def _accept_elicit(
+    context: ClientRequestContext, params: types.ElicitRequestParams
+) -> types.ElicitResult:
+    return types.ElicitResult(action="accept", content={"value": 7})
+
+
+async def _sampling_cb(
+    context: ClientRequestContext, params: types.CreateMessageRequestParams
+) -> types.CreateMessageResult:
+    return types.CreateMessageResult(
+        role="assistant",
+        content=types.TextContent(type="text", text="sampled-text"),
+        model="test-model",
+    )
+
+
+async def _roots_cb(context: ClientRequestContext) -> types.ListRootsResult:
+    return types.ListRootsResult(
+        roots=[types.Root(uri=FileUrl("file:///tmp"), name="tmp")]
+    )
+
+
+async def test_elicit_works_on_legacy(push_server):
+    async with SDKClient(
+        _server(push_server), mode="legacy", elicitation_callback=_accept_elicit
+    ) as client:
+        result = await client.call_tool("do_elicit", {})
+    assert result.is_error is False
+    assert _texts(result.content) == ["elicited 7"]
+
+
+async def test_sample_works_on_legacy(push_server):
+    async with SDKClient(
+        _server(push_server), mode="legacy", sampling_callback=_sampling_cb
+    ) as client:
+        result = await client.call_tool("do_sample", {})
+    assert result.is_error is False
+    assert _texts(result.content) == ["sampled sampled-text"]
+
+
+async def test_list_roots_works_on_legacy(push_server):
+    async with SDKClient(
+        _server(push_server), mode="legacy", list_roots_callback=_roots_cb
+    ) as client:
+        result = await client.call_tool("do_list_roots", {})
+    assert result.is_error is False
+    assert _texts(result.content) == ["roots ['file:///tmp']"]
+
+
+@pytest.mark.parametrize("mode", MODERN_MODES)
+@pytest.mark.parametrize("tool", ["do_elicit", "do_sample", "do_list_roots"])
+async def test_push_features_degrade_on_modern(push_server, mode, tool):
+    """Server-initiated requests (elicitation/sampling/roots) are removed at
+    2026-07-28 (SEP-2577), so a tool that uses them must degrade to a surfaced
+    error rather than hang or crash the connection. This asserts the
+    degradation happens and reaches the caller as an isError result.
+    """
+    async with SDKClient(
+        _server(push_server),
+        mode=mode,
+        elicitation_callback=_accept_elicit,
+        sampling_callback=_sampling_cb,
+        list_roots_callback=_roots_cb,
+    ) as client:
+        result = await client.call_tool(tool, {})
+        assert result.is_error is True
+        # A subsequent normal call still works: the connection survived the
+        # per-request failure rather than tearing down the whole session.
+        log_result = await client.call_tool("do_log", {})
+        assert log_result.is_error is False
+
+
+async def test_list_roots_degradation_message_is_clear_on_modern(push_server):
+    """`ctx.list_roots()` sends with no related_request_id, so the SDK selects
+    the connection's no-back-channel outbound and raises the self-explanatory
+    NoBackChannelError. This is the *good* degradation message and we assert it.
+    """
+    async with SDKClient(_server(push_server), mode="2026-07-28") as client:
+        result = await client.call_tool("do_list_roots", {})
+    assert result.is_error is True
+    message = " ".join(_texts(result.content)).lower()
+    assert "back-channel" in message and "server-initiated" in message
+
+
+@pytest.mark.parametrize("tool", ["do_elicit", "do_sample"])
+async def test_elicit_sample_degradation_message_is_clear_on_modern(push_server, tool):
+    """FastMCP era-gates elicit/sample: on a 2026-07-28 connection they raise a
+    clear, era-aware error before hitting the wire, instead of the SDK's opaque
+    'Method not found' (sdk-feedback.md #10). Both messages name the removed
+    server-initiated capability so the caller knows why the request degraded.
+    """
+    async with SDKClient(
+        _server(push_server),
+        mode="2026-07-28",
+        elicitation_callback=_accept_elicit,
+        sampling_callback=_sampling_cb,
+    ) as client:
+        result = await client.call_tool(tool, {})
+    assert result.is_error is True
+    message = " ".join(_texts(result.content)).lower()
+    assert "server-initiated" in message
+
+
+# ---------------------------------------------------------------------------
+# 3a-bis. Server-configured sampling handler answers WITHOUT the client
+# back-channel, so ctx.sample()/ctx.sample_step() must keep working on modern
+# connections. The era-gate only fires when nothing can serve the request.
+# ---------------------------------------------------------------------------
+
+
+def _handler_server(behavior) -> FastMCP:
+    """A server whose sampling is answered by a server-side handler."""
+
+    def sampling_handler(messages, params, ctx) -> str:
+        return "handler-answer"
+
+    mcp = FastMCP("handler", sampling_handler=sampling_handler)
+    if behavior is not None:
+        mcp.sampling_handler_behavior = behavior
+
+    @mcp.tool
+    async def do_sample(ctx: Context) -> str:
+        result = await ctx.sample("hello")
+        return f"sampled {result.text}"
+
+    @mcp.tool
+    async def do_sample_step(ctx: Context) -> str:
+        step = await ctx.sample_step("hello")
+        return f"stepped {step.text}"
+
+    return mcp
+
+
+@pytest.mark.parametrize("mode", MODERN_MODES)
+@pytest.mark.parametrize("behavior", ["always", "fallback"])
+@pytest.mark.parametrize("method", ["do_sample", "do_sample_step"])
+async def test_server_sampling_handler_works_on_modern(mode, behavior, method):
+    """A server-side sampling handler answers entirely server-side, so it works
+    on modern (2026-07-28) connections regardless of behavior. The era-gate must
+    NOT block these — nothing touches the removed client back-channel. Crucially,
+    'fallback' must go straight to the handler (no bare client-attempt failure)."""
+    server = _handler_server(behavior)
+    async with SDKClient(_server(server), mode=mode) as client:
+        result = await client.call_tool(method, {})
+    assert result.is_error is False
+    assert "handler-answer" in " ".join(_texts(result.content))
+
+
+@pytest.mark.parametrize("behavior", ["always", "fallback"])
+@pytest.mark.parametrize("method", ["do_sample", "do_sample_step"])
+async def test_server_sampling_handler_works_on_legacy(behavior, method):
+    """Handshake-era behavior is unchanged: the server-side handler still answers
+    on legacy connections."""
+    server = _handler_server(behavior)
+    async with SDKClient(_server(server), mode="legacy") as client:
+        result = await client.call_tool(method, {})
+    assert result.is_error is False
+    assert "handler-answer" in " ".join(_texts(result.content))
+
+
+@pytest.mark.parametrize("mode", MODERN_MODES)
+@pytest.mark.parametrize("method", ["do_sample", "do_sample_step"])
+async def test_sampling_without_handler_still_era_gated_on_modern(
+    push_server, mode, method
+):
+    """With no server-side handler configured, the request would hit the removed
+    client back-channel, so the clear era error still fires on modern."""
+    # push_server only defines do_sample; add a do_sample_step twin inline.
+    mcp = FastMCP("no-handler")
+
+    @mcp.tool
+    async def do_sample(ctx: Context) -> str:
+        result = await ctx.sample("hello")
+        return f"sampled {result.text}"
+
+    @mcp.tool
+    async def do_sample_step(ctx: Context) -> str:
+        step = await ctx.sample_step("hello")
+        return f"stepped {step.text}"
+
+    async with SDKClient(
+        _server(mcp), mode=mode, sampling_callback=_sampling_cb
+    ) as client:
+        result = await client.call_tool(method, {})
+    assert result.is_error is True
+    assert "server-initiated" in " ".join(_texts(result.content)).lower()
+
+
+# ---------------------------------------------------------------------------
+# 3b. Sampling deprecation warning (SEP-2577): ctx.sample/ctx.sample_step warn
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def reset_sample_warn_flag():
+    """Reset the process-wide warn-once flag so a warning can be observed."""
+    import fastmcp.server.context as context_module
+
+    original = set(context_module._sample_deprecation_warned)
+    context_module._sample_deprecation_warned.clear()
+    try:
+        yield
+    finally:
+        context_module._sample_deprecation_warned.clear()
+        context_module._sample_deprecation_warned.update(original)
+
+
+@pytest.mark.parametrize("method", ["do_sample", "do_sample_step"])
+async def test_sampling_emits_deprecation_warning(reset_sample_warn_flag, method):
+    """`ctx.sample()` and `ctx.sample_step()` emit a FastMCPDeprecationWarning
+    naming SEP-2577 and the server-side-LLM migration path."""
+    from fastmcp.exceptions import FastMCPDeprecationWarning
+
+    mcp = FastMCP("warn")
+
+    @mcp.tool
+    async def do_sample(ctx: Context) -> str:
+        await ctx.sample("hello")
+        return "ok"
+
+    @mcp.tool
+    async def do_sample_step(ctx: Context) -> str:
+        await ctx.sample_step("hello")
+        return "ok"
+
+    with pytest.warns(FastMCPDeprecationWarning, match="SEP-2577"):
+        async with SDKClient(
+            _server(mcp), mode="legacy", sampling_callback=_sampling_cb
+        ) as client:
+            await client.call_tool(method, {})
+
+
+async def test_sampling_deprecation_warning_fires_once_per_process(
+    reset_sample_warn_flag,
+):
+    """The deprecation warning is warn-once: a second sample call in the same
+    process does not re-warn."""
+    from fastmcp.exceptions import FastMCPDeprecationWarning
+
+    mcp = FastMCP("warn-once")
+
+    @mcp.tool
+    async def do_sample(ctx: Context) -> str:
+        await ctx.sample("hello")
+        return "ok"
+
+    with pytest.warns(FastMCPDeprecationWarning):
+        async with SDKClient(
+            _server(mcp), mode="legacy", sampling_callback=_sampling_cb
+        ) as client:
+            await client.call_tool("do_sample", {})
+
+    import warnings as _warnings
+
+    with _warnings.catch_warnings():
+        _warnings.simplefilter("error", FastMCPDeprecationWarning)
+        async with SDKClient(
+            _server(mcp), mode="legacy", sampling_callback=_sampling_cb
+        ) as client:
+            result = await client.call_tool("do_sample", {})
+    assert result.is_error is False
+
+
+async def test_sampling_deprecation_warning_suppressible_via_settings(
+    reset_sample_warn_flag, monkeypatch
+):
+    """Setting `deprecation_warnings=False` suppresses the sampling warning,
+    matching the house pattern for every other FastMCP deprecation."""
+    import warnings as _warnings
+
+    from fastmcp.exceptions import FastMCPDeprecationWarning
+
+    monkeypatch.setattr(settings, "deprecation_warnings", False)
+
+    mcp = FastMCP("no-warn")
+
+    @mcp.tool
+    async def do_sample(ctx: Context) -> str:
+        await ctx.sample("hello")
+        return "ok"
+
+    with _warnings.catch_warnings():
+        _warnings.simplefilter("error", FastMCPDeprecationWarning)
+        async with SDKClient(
+            _server(mcp), mode="legacy", sampling_callback=_sampling_cb
+        ) as client:
+            result = await client.call_tool("do_sample", {})
+    assert result.is_error is False
+
+
+@pytest.mark.parametrize("mode", MODERN_MODES)
+async def test_logging_notification_still_flows_on_modern(push_server, mode):
+    """`ctx.info` is a server->client *notification*, not a request. Unlike the
+    removed server-initiated requests, notifications still flow over the modern
+    direct-dispatcher path, so the tool completes successfully.
+
+    Characterization: current behavior is silent success (the log is emitted,
+    the tool returns normally); we assert that rather than an error.
+    """
+    async with SDKClient(_server(push_server), mode=mode) as client:
+        result = await client.call_tool("do_log", {})
+    assert result.is_error is False
+    assert _texts(result.content) == ["logged"]
+
+
+# ---------------------------------------------------------------------------
+# 4. Tasks: submission + tasks/get across the eras the _sdk_patches shim covers
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def task_server() -> FastMCP:
+    mcp = FastMCP("tasks")
+
+    @mcp.tool(task=True)
+    async def slow_add(a: int, b: int) -> int:
+        return a + b
+
+    return mcp
+
+
+async def test_task_submission_and_get_on_legacy_latest(task_server):
+    """Legacy-latest (2025-11-25): a task-augmented tools/call returns a
+    CreateTaskResult and tasks/get resolves it. This exercises the
+    _sdk_patches registry-widening shim at the 2025-11-25 tools/call surface.
+
+    Driven with the FastMCP client because the v2 SDK client's call_tool has no
+    `task=` parameter (verified: mcp.client.session.ClientSession.call_tool
+    exposes no task metadata arg) — see item below.
+    """
+    async with FastMCPClient(task_server) as client:
+        assert client.initialize_result is not None
+        assert client.initialize_result.protocol_version == "2025-11-25"
+
+        task = await client.call_tool("slow_add", {"a": 2, "b": 3}, task=True)
+        assert task.task_id
+        assert not task.returned_immediately
+
+        await task.wait(timeout=3.0)
+        result = await task.result()
+        assert result.data == 5
+
+
+@pytest.mark.xfail(
+    strict=True,
+    reason=(
+        "The v2 SDK high-level client (mcp.client.Client) and ClientSession "
+        "expose no `task=` parameter on call_tool, so a task-augmented "
+        "tools/call cannot be submitted through it at any era; a hand-built "
+        "raw CallToolRequest does not drive FastMCP's task path either. On "
+        "2026-07-28 tasks moved to the io.modelcontextprotocol/tasks extension "
+        "and CreateTaskResult is not part of the tools/call union, so the "
+        "_sdk_patches shim intentionally does not widen the modern row "
+        "(sdk-feedback.md #1). Remove once the SDK client supports task "
+        "submission."
+    ),
+)
+async def test_task_submission_on_modern(task_server):
+    async with SDKClient(_server(task_server), mode="2026-07-28") as client:
+        params = types.CallToolRequestParams(
+            name="slow_add",
+            arguments={"a": 1, "b": 2},
+            task=types.TaskMetadata(ttl=60000),
+        )
+        result = await client.session.send_request(
+            types.CallToolRequest(params=params), types.CreateTaskResult
+        )
+        assert isinstance(result, types.CreateTaskResult)
+
+
+# ---------------------------------------------------------------------------
+# 4b. _sdk_patches registry gating: the SEP-1686 task shim widens ONLY the
+# handshake-era rows and leaves the 2026-07-28 (extension-era) rows untouched.
+# ---------------------------------------------------------------------------
+
+
+def test_task_shim_widens_handshake_tools_call_rows():
+    """Every handshake-era tools/call row gains a CreateTaskResult arm."""
+    from fastmcp._sdk_patches import get_union_arms
+
+    for version in HANDSHAKE_PROTOCOL_VERSIONS:
+        row = methods.SERVER_RESULTS[("tools/call", version)]
+        assert types.CreateTaskResult in get_union_arms(row), version
+
+
+def test_task_shim_does_not_touch_modern_tools_call_row():
+    """The 2026-07-28 tools/call row stays the unpatched MRTR union: tasks are
+    the io.modelcontextprotocol/tasks extension there, so CreateTaskResult must
+    not be injected."""
+    from fastmcp._sdk_patches import get_union_arms
+
+    row = methods.SERVER_RESULTS[("tools/call", "2026-07-28")]
+    arms = get_union_arms(row)
+    assert types.CreateTaskResult not in arms
+    # Unchanged from the SDK default: the 2026 mutually-recursive tool result
+    # (CallToolResult | InputRequiredResult), keyed by the version-specific types.
+    arm_names = {arm.__name__ for arm in arms}
+    assert arm_names == {"CallToolResult", "InputRequiredResult"}
+
+
+@pytest.mark.parametrize(
+    "task_method",
+    ["tasks/get", "tasks/result", "tasks/list", "tasks/cancel"],
+)
+def test_task_shim_registers_tasks_rows_only_for_handshake_eras(task_method):
+    """tasks/* result rows exist for handshake-era versions and are absent for
+    the modern (extension) era."""
+    for version in HANDSHAKE_PROTOCOL_VERSIONS:
+        assert (task_method, version) in methods.SERVER_RESULTS, (task_method, version)
+    for version in MODERN_PROTOCOL_VERSIONS:
+        assert (task_method, version) not in methods.SERVER_RESULTS, (
+            task_method,
+            version,
+        )
+
+
+# ---------------------------------------------------------------------------
+# 5. Sessionless safety: session-id-keyed paths must not crash on 2026 in-memory
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def sessionless_server() -> FastMCP:
+    mcp = FastMCP("sessionless")
+
+    @mcp.tool
+    async def read_session_id(ctx: Context) -> str:
+        # In-memory/HTTP-less connections have no HTTP session id; FastMCP must
+        # synthesize a stable one rather than raise.
+        return ctx.session_id
+
+    return mcp
+
+
+@pytest.mark.parametrize("mode", MODERN_MODES)
+async def test_session_id_access_does_not_crash_on_modern(sessionless_server, mode):
+    async with SDKClient(_server(sessionless_server), mode=mode) as client:
+        result = await client.call_tool("read_session_id", {})
+    assert result.is_error is False
+    # A non-empty synthesized id was returned.
+    assert _texts(result.content)[0]
+
+
+@pytest.mark.parametrize("mode", MODERN_MODES)
+async def test_set_logging_level_does_not_crash_on_modern(sessionless_server, mode):
+    """logging/setLevel is a session-id-keyed, deprecated-at-2026 operation.
+    On a sessionless modern in-memory connection it must degrade cleanly (either
+    succeed as a no-op or raise a surfaced MCPError) rather than crash the
+    connection. Characterization: capture whichever the current contract is.
+    """
+    async with SDKClient(_server(sessionless_server), mode=mode) as client:
+        outcome: str
+        try:
+            await client.set_logging_level("debug")  # ty: ignore[deprecated]
+            outcome = "ok"
+        except MCPError:
+            outcome = "mcperror"
+        # Either way the connection is still usable afterward.
+        result = await client.call_tool("read_session_id", {})
+    assert result.is_error is False
+    assert outcome in {"ok", "mcperror"}
+
+
+# ---------------------------------------------------------------------------
+# 6. FastMCP middleware runs on both eras
+# ---------------------------------------------------------------------------
+
+
+class _CallToolCounter(Middleware):
+    def __init__(self) -> None:
+        super().__init__()
+        self.count = 0
+
+    async def on_call_tool(self, context, call_next):
+        self.count += 1
+        return await call_next(context)
+
+
+async def test_middleware_runs_on_both_eras():
+    counter = _CallToolCounter()
+    mcp = FastMCP("mw")
+    mcp.add_middleware(counter)
+
+    @mcp.tool
+    def ping() -> str:
+        return "pong"
+
+    for mode in ("legacy", "2026-07-28"):
+        async with SDKClient(mcp._mcp_server, mode=mode) as client:
+            result = await client.call_tool("ping", {})
+        assert result.is_error is False
+        assert _texts(result.content) == ["pong"]
+
+    # One invocation observed from each era.
+    assert counter.count == 2
diff --git a/tests/server/test_providers.py b/tests/server/test_providers.py
new file mode 100644
index 0000000..4961272
--- /dev/null
+++ b/tests/server/test_providers.py
@@ -0,0 +1,452 @@
+"""Tests for providers."""
+
+from collections.abc import Sequence
+from typing import Any
+
+import pytest
+from mcp_types import TextContent
+from pydantic import AnyUrl
+
+from fastmcp import FastMCP
+from fastmcp.prompts.base import Prompt
+from fastmcp.prompts.function_prompt import FunctionPrompt
+from fastmcp.resources.base import Resource
+from fastmcp.resources.function_resource import FunctionResource
+from fastmcp.resources.template import FunctionResourceTemplate, ResourceTemplate
+from fastmcp.server.providers import Provider
+from fastmcp.tools.base import Tool, ToolResult
+from fastmcp.utilities.versions import VersionSpec
+
+
+class SimpleTool(Tool):
+    """A simple tool for testing that performs a configured operation."""
+
+    operation: str
+    value: int = 0
+
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
+        a = arguments.get("a", 0)
+        b = arguments.get("b", 0)
+
+        if self.operation == "add":
+            result = a + b + self.value
+        elif self.operation == "multiply":
+            result = a * b + self.value
+        else:
+            result = a + b
+
+        return ToolResult(
+            structured_content={"result": result, "operation": self.operation}
+        )
+
+
+class SimpleToolProvider(Provider):
+    """A simple provider that returns a configurable list of tools."""
+
+    def __init__(self, tools: Sequence[Tool] | None = None):
+        super().__init__()
+        self._tools = list(tools) if tools else []
+        self.list_tools_call_count = 0
+        self.get_tool_call_count = 0
+
+    async def _list_tools(self) -> list[Tool]:
+        self.list_tools_call_count += 1
+        return self._tools
+
+    async def _get_tool(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Tool | None:
+        self.get_tool_call_count += 1
+        matching = [t for t in self._tools if t.name == name]
+        if not matching:
+            return None
+        if version is None:
+            return matching[0]  # Return first (for testing simplicity)
+        matching = [t for t in matching if version.matches(t.version)]
+        return matching[0] if matching else None
+
+
+class ListOnlyProvider(Provider):
+    """A provider that only implements list_tools (uses default get_tool)."""
+
+    def __init__(self, tools: Sequence[Tool]):
+        super().__init__()
+        self._tools = list(tools)
+        self.list_tools_call_count = 0
+
+    async def _list_tools(self) -> list[Tool]:
+        self.list_tools_call_count += 1
+        return self._tools
+
+
+class TestProvider:
+    """Tests for Provider."""
+
+    @pytest.fixture
+    def base_server(self):
+        """Create a base FastMCP server with static tools."""
+        mcp = FastMCP("BaseServer")
+
+        @mcp.tool
+        def static_add(a: int, b: int) -> int:
+            """Add two numbers (static tool)."""
+            return a + b
+
+        @mcp.tool
+        def static_subtract(a: int, b: int) -> int:
+            """Subtract two numbers (static tool)."""
+            return a - b
+
+        return mcp
+
+    @pytest.fixture
+    def dynamic_tools(self) -> list[Tool]:
+        """Create dynamic tools for testing."""
+        return [
+            SimpleTool(
+                name="dynamic_multiply",
+                description="Multiply two numbers",
+                parameters={
+                    "type": "object",
+                    "properties": {
+                        "a": {"type": "integer"},
+                        "b": {"type": "integer"},
+                    },
+                },
+                operation="multiply",
+            ),
+            SimpleTool(
+                name="dynamic_add",
+                description="Add two numbers with offset",
+                parameters={
+                    "type": "object",
+                    "properties": {
+                        "a": {"type": "integer"},
+                        "b": {"type": "integer"},
+                    },
+                },
+                operation="add",
+                value=100,
+            ),
+        ]
+
+    async def test_list_tools_includes_dynamic_tools(
+        self, base_server: FastMCP, dynamic_tools: list[Tool]
+    ):
+        """Test that list_tools returns both static and dynamic tools."""
+        provider = SimpleToolProvider(tools=dynamic_tools)
+        base_server.add_provider(provider)
+
+        tools = await base_server.list_tools()
+
+        # Should have all tools: 2 static + 2 dynamic
+        assert len(tools) == 4
+        tool_names = [tool.name for tool in tools]
+        assert "static_add" in tool_names
+        assert "static_subtract" in tool_names
+        assert "dynamic_multiply" in tool_names
+        assert "dynamic_add" in tool_names
+
+    async def test_list_tools_calls_provider_each_time(
+        self, base_server: FastMCP, dynamic_tools: list[Tool]
+    ):
+        """Test that provider.list_tools() is called on every list_tools request."""
+        provider = SimpleToolProvider(tools=dynamic_tools)
+        base_server.add_provider(provider)
+
+        # Call get_tools multiple times
+        await base_server.list_tools()
+        await base_server.list_tools()
+        await base_server.list_tools()
+
+        # Provider should have been called 3 times (once per get_tools call)
+        assert provider.list_tools_call_count == 3
+
+    async def test_call_dynamic_tool(
+        self, base_server: FastMCP, dynamic_tools: list[Tool]
+    ):
+        """Test that dynamic tools can be called successfully."""
+        provider = SimpleToolProvider(tools=dynamic_tools)
+        base_server.add_provider(provider)
+
+        result = await base_server.call_tool(
+            name="dynamic_multiply", arguments={"a": 7, "b": 6}
+        )
+
+        assert result.structured_content is not None
+        assert isinstance(result.structured_content, dict)
+        assert result.structured_content["result"] == 42
+        assert result.structured_content["operation"] == "multiply"
+
+    async def test_call_dynamic_tool_with_config(
+        self, base_server: FastMCP, dynamic_tools: list[Tool]
+    ):
+        """Test that dynamic tool config (like value offset) is used."""
+        provider = SimpleToolProvider(tools=dynamic_tools)
+        base_server.add_provider(provider)
+
+        result = await base_server.call_tool(
+            name="dynamic_add", arguments={"a": 5, "b": 3}
+        )
+
+        assert result.structured_content is not None
+        # 5 + 3 + 100 (value offset) = 108
+        assert isinstance(result.structured_content, dict)
+        assert result.structured_content["result"] == 108
+
+    async def test_call_static_tool_still_works(
+        self, base_server: FastMCP, dynamic_tools: list[Tool]
+    ):
+        """Test that static tools still work after adding dynamic tools."""
+        provider = SimpleToolProvider(tools=dynamic_tools)
+        base_server.add_provider(provider)
+
+        result = await base_server.call_tool(
+            name="static_add", arguments={"a": 10, "b": 5}
+        )
+
+        assert result.structured_content is not None
+        assert isinstance(result.structured_content, dict)
+        assert result.structured_content["result"] == 15
+
+    async def test_call_tool_uses_get_tool_for_efficient_lookup(
+        self, base_server: FastMCP, dynamic_tools: list[Tool]
+    ):
+        """Test that call_tool uses get_tool() (not list_tools) for lookup."""
+        provider = SimpleToolProvider(tools=dynamic_tools)
+        base_server.add_provider(provider)
+
+        await base_server.call_tool(name="dynamic_multiply", arguments={"a": 2, "b": 3})
+
+        # get_tool may be called more than once — once for the initial
+        # resolution and once again by the dispatcher's reverse-lookup to
+        # find the tool's owning provider for Context.mount_path. Both
+        # are bounded by provider count, much cheaper than list_tools.
+        # The key invariant: list_tools is NOT called during dispatch.
+        assert provider.get_tool_call_count >= 1
+        assert provider.list_tools_call_count == 0
+
+    async def test_default_get_tool_falls_back_to_list(self, base_server: FastMCP):
+        """Test that BaseToolProvider's default get_tool calls list_tools."""
+        tools = [
+            SimpleTool(
+                name="test_tool",
+                description="A test tool",
+                parameters={"type": "object", "properties": {}},
+                operation="add",
+            ),
+        ]
+        provider = ListOnlyProvider(tools=tools)
+        base_server.add_provider(provider)
+
+        result = await base_server.call_tool(
+            name="test_tool", arguments={"a": 1, "b": 2}
+        )
+
+        assert result.structured_content is not None
+        # Default get_tool should have called list_tools
+        assert provider.list_tools_call_count >= 1
+
+    async def test_local_tools_come_first(
+        self, base_server: FastMCP, dynamic_tools: list[Tool]
+    ):
+        """Test that local tools (from LocalProvider) appear before other provider tools."""
+        provider = SimpleToolProvider(tools=dynamic_tools)
+        base_server.add_provider(provider)
+
+        tools = await base_server.list_tools()
+
+        tool_names = [tool.name for tool in tools]
+        # Local tools should come first (LocalProvider is first in _providers)
+        assert tool_names[:2] == ["static_add", "static_subtract"]
+
+    async def test_empty_provider(self, base_server: FastMCP):
+        """Test that empty provider doesn't affect behavior."""
+        provider = SimpleToolProvider(tools=[])
+        base_server.add_provider(provider)
+
+        tools = await base_server.list_tools()
+
+        # Should only have static tools
+        assert len(tools) == 2
+
+    async def test_tool_not_found_falls_through_to_static(
+        self, base_server: FastMCP, dynamic_tools: list[Tool]
+    ):
+        """Test that unknown tool name falls through to static tools."""
+        provider = SimpleToolProvider(tools=dynamic_tools)
+        base_server.add_provider(provider)
+
+        # This tool is static, not in the dynamic provider
+        result = await base_server.call_tool(
+            name="static_subtract", arguments={"a": 10, "b": 3}
+        )
+
+        assert result.structured_content is not None
+        assert isinstance(result.structured_content, dict)
+        assert result.structured_content["result"] == 7
+
+
+class TestProviderClass:
+    """Tests for the Provider class."""
+
+    async def test_subclass_is_instance(self):
+        """Test that subclasses are instances of Provider."""
+        provider = SimpleToolProvider(tools=[])
+        assert isinstance(provider, Provider)
+
+    async def test_default_get_tool_works(self):
+        """Test that the default get_tool implementation works."""
+        tool = SimpleTool(
+            name="test",
+            description="Test",
+            parameters={"type": "object", "properties": {}},
+            operation="add",
+        )
+        provider = ListOnlyProvider(tools=[tool])
+
+        # Default get_tool should find by name
+        found = await provider.get_tool("test")
+        assert found is not None
+        assert found.name == "test"
+
+        # Should return None for unknown names
+        not_found = await provider.get_tool("unknown")
+        assert not_found is None
+
+
+class TestDynamicToolUpdates:
+    """Tests demonstrating dynamic tool updates without restart."""
+
+    async def test_tools_update_without_restart(self):
+        """Test that tools can be updated dynamically."""
+        mcp = FastMCP("DynamicServer")
+
+        # Start with one tool
+        initial_tools = [
+            SimpleTool(
+                name="tool_v1",
+                description="Version 1",
+                parameters={"type": "object", "properties": {}},
+                operation="add",
+            ),
+        ]
+        provider = SimpleToolProvider(tools=initial_tools)
+        mcp.add_provider(provider)
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+        assert tools[0].name == "tool_v1"
+
+        # Update the provider's tools (simulating DB update)
+        provider._tools = [
+            SimpleTool(
+                name="tool_v2",
+                description="Version 2",
+                parameters={"type": "object", "properties": {}},
+                operation="multiply",
+            ),
+            SimpleTool(
+                name="tool_v3",
+                description="Version 3",
+                parameters={"type": "object", "properties": {}},
+                operation="add",
+            ),
+        ]
+
+        # List tools again - should see new tools
+        tools = await mcp.list_tools()
+        assert len(tools) == 2
+        tool_names = [t.name for t in tools]
+        assert "tool_v1" not in tool_names
+        assert "tool_v2" in tool_names
+        assert "tool_v3" in tool_names
+
+
+class TestProviderExecutionMethods:
+    """Tests for Provider execution methods (call_tool, read_resource, render_prompt)."""
+
+    async def test_call_tool_default_implementation(self):
+        """Test that default call_tool uses get_tool and runs the tool."""
+        tool = SimpleTool(
+            name="test_tool",
+            description="Test",
+            parameters={"type": "object", "properties": {"a": {}, "b": {}}},
+            operation="add",
+        )
+        provider = SimpleToolProvider(tools=[tool])
+        mcp = FastMCP("TestServer")
+        mcp.add_provider(provider)
+
+        result = await mcp.call_tool("test_tool", {"a": 1, "b": 2})
+
+        assert result.structured_content is not None
+        assert isinstance(result.structured_content, dict)
+        assert result.structured_content["result"] == 3
+
+    async def test_read_resource_default_implementation(self):
+        """Test that default read_resource uses get_resource and reads it."""
+
+        class ResourceProvider(Provider):
+            async def _list_resources(self) -> Sequence[Resource]:
+                return [
+                    FunctionResource(
+                        uri=AnyUrl("test://data"),
+                        name="Test Data",
+                        fn=lambda: "hello world",
+                    )
+                ]
+
+        provider = ResourceProvider()
+        mcp = FastMCP("TestServer")
+        mcp.add_provider(provider)
+
+        result = await mcp.read_resource("test://data")
+
+        assert len(result.contents) == 1
+        assert result.contents[0].content == "hello world"
+
+    async def test_read_resource_template_default(self):
+        """Test that read_resource_template handles template-based resources."""
+
+        class TemplateProvider(Provider):
+            async def _list_resource_templates(self) -> Sequence[ResourceTemplate]:
+                return [
+                    FunctionResourceTemplate.from_function(
+                        fn=lambda name: f"content of {name}",
+                        uri_template="data://files/{name}",
+                        name="Data Template",
+                    )
+                ]
+
+        provider = TemplateProvider()
+        mcp = FastMCP("TestServer")
+        mcp.add_provider(provider)
+
+        result = await mcp.read_resource("data://files/test.txt")
+
+        assert len(result.contents) == 1
+        assert result.contents[0].content == "content of test.txt"
+
+    async def test_render_prompt_default_implementation(self):
+        """Test that default render_prompt uses get_prompt and renders it."""
+
+        class PromptProvider(Provider):
+            async def _list_prompts(self) -> Sequence[Prompt]:
+                return [
+                    FunctionPrompt.from_function(
+                        fn=lambda name: f"Hello, {name}!",
+                        name="greeting",
+                        description="Greet someone",
+                    )
+                ]
+
+        provider = PromptProvider()
+        mcp = FastMCP("TestServer")
+        mcp.add_provider(provider)
+
+        result = await mcp.render_prompt("greeting", {"name": "World"})
+
+        assert len(result.messages) == 1
+        assert isinstance(result.messages[0].content, TextContent)
+        assert result.messages[0].content.text == "Hello, World!"
diff --git a/tests/server/test_server.py b/tests/server/test_server.py
new file mode 100644
index 0000000..d1aae62
--- /dev/null
+++ b/tests/server/test_server.py
@@ -0,0 +1,404 @@
+import os
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from textwrap import dedent
+from unittest import mock
+
+from mcp_types import TextContent, TextResourceContents
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.providers import LocalProvider
+from fastmcp.tools import FunctionTool
+from fastmcp.tools.base import Tool
+from fastmcp.utilities.tests import temporary_settings
+
+
+class TestCreateServer:
+    async def test_create_server(self):
+        mcp = FastMCP(instructions="Server instructions")
+        assert mcp.name.startswith("FastMCP-")
+        assert mcp.instructions == "Server instructions"
+
+    async def test_change_instruction(self):
+        mcp = FastMCP(instructions="Server instructions")
+        assert mcp.instructions == "Server instructions"
+        mcp.instructions = "New instructions"
+        assert mcp.instructions == "New instructions"
+
+    async def test_non_ascii_description(self):
+        """Test that FastMCP handles non-ASCII characters in descriptions correctly"""
+        mcp = FastMCP()
+
+        @mcp.tool(
+            description=(
+                "🌟 This tool uses emojis and UTF-8 characters: á é í ó ú ñ 漢字 🎉"
+            )
+        )
+        def hello_world(name: str = "世界") -> str:
+            return f"¡Hola, {name}! 👋"
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            assert len(tools) == 1
+            tool = tools[0]
+            assert tool.description is not None
+            assert "🌟" in tool.description
+            assert "漢字" in tool.description
+            assert "🎉" in tool.description
+
+            result = await client.call_tool("hello_world", {})
+            assert result.data == "¡Hola, 世界! 👋"
+
+
+class TestServerDelegation:
+    """Test that FastMCP properly delegates to LocalProvider."""
+
+    async def test_tool_decorator_delegates_to_local_provider(self):
+        """Test that @mcp.tool registers with the local provider."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def my_tool() -> str:
+            return "result"
+
+        # Verify the tool is in the local provider
+        tool = await mcp._local_provider.get_tool("my_tool")
+        assert tool is not None
+        assert tool.name == "my_tool"
+
+    async def test_resource_decorator_delegates_to_local_provider(self):
+        """Test that @mcp.resource registers with the local provider."""
+        mcp = FastMCP()
+
+        @mcp.resource("resource://test")
+        def my_resource() -> str:
+            return "content"
+
+        # Verify the resource is in the local provider
+        resource = await mcp._local_provider.get_resource("resource://test")
+        assert resource is not None
+
+    async def test_prompt_decorator_delegates_to_local_provider(self):
+        """Test that @mcp.prompt registers with the local provider."""
+        mcp = FastMCP()
+
+        @mcp.prompt
+        def my_prompt() -> str:
+            return "prompt content"
+
+        # Verify the prompt is in the local provider
+        prompt = await mcp._local_provider.get_prompt("my_prompt")
+        assert prompt is not None
+        assert prompt.name == "my_prompt"
+
+    async def test_add_tool_delegates_to_local_provider(self):
+        """Test that mcp.add_tool() registers with the local provider."""
+        mcp = FastMCP()
+
+        def standalone_tool() -> str:
+            return "result"
+
+        mcp.add_tool(FunctionTool.from_function(standalone_tool))
+
+        # Verify the tool is in the local provider
+        tool = await mcp._local_provider.get_tool("standalone_tool")
+        assert tool is not None
+        assert tool.name == "standalone_tool"
+
+    async def test_get_tools_includes_local_provider_tools(self):
+        """Test that get_tools() returns tools from local provider."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def local_tool() -> str:
+            return "local"
+
+        tools = await mcp.list_tools()
+        assert any(t.name == "local_tool" for t in tools)
+
+
+class TestLocalProviderProperty:
+    """Test the public local_provider property."""
+
+    async def test_local_provider_returns_local_provider(self):
+        mcp = FastMCP()
+        assert isinstance(mcp.local_provider, LocalProvider)
+        assert mcp.local_provider is mcp._local_provider
+
+    async def test_remove_tool_via_local_provider(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def my_tool() -> str:
+            return "result"
+
+        assert await mcp.local_provider.get_tool("my_tool") is not None
+        mcp.local_provider.remove_tool("my_tool")
+        tools = await mcp.list_tools()
+        assert not any(t.name == "my_tool" for t in tools)
+
+    async def test_remove_resource_via_local_provider(self):
+        mcp = FastMCP()
+
+        @mcp.resource("resource://test")
+        def my_resource() -> str:
+            return "data"
+
+        mcp.local_provider.remove_resource("resource://test")
+        resources = await mcp.list_resources()
+        assert not any(r.uri == "resource://test" for r in resources)
+
+    async def test_remove_prompt_via_local_provider(self):
+        mcp = FastMCP()
+
+        @mcp.prompt
+        def my_prompt() -> str:
+            return "hello"
+
+        mcp.local_provider.remove_prompt("my_prompt")
+        prompts = await mcp.list_prompts()
+        assert not any(p.name == "my_prompt" for p in prompts)
+
+
+class TestResourcePrefixMounting:
+    """Test resource prefixing in mounted servers."""
+
+    async def test_mounted_server_resource_prefixing(self):
+        """Test that resources in mounted servers use the correct prefix format."""
+        # Create a server with resources
+        server = FastMCP(name="ResourceServer")
+
+        @server.resource("resource://test-resource")
+        def get_resource():
+            return "Resource content"
+
+        @server.resource("resource:///absolute/path")
+        def get_absolute_resource():
+            return "Absolute resource content"
+
+        @server.resource("resource://{param}/template")
+        def get_template_resource(param: str):
+            return f"Template resource with {param}"
+
+        # Create a main server and mount the resource server
+        main_server = FastMCP(name="MainServer")
+        main_server.mount(server, "prefix")
+
+        # Check that the resources are mounted with the correct prefixes
+        resources = await main_server.list_resources()
+        templates = await main_server.list_resource_templates()
+
+        assert any(str(r.uri) == "resource://prefix/test-resource" for r in resources)
+        assert any(str(r.uri) == "resource://prefix//absolute/path" for r in resources)
+        assert any(
+            t.uri_template == "resource://prefix/{param}/template" for t in templates
+        )
+
+        # Test that prefixed resources can be accessed
+        async with Client(main_server) as client:
+            # Regular resource
+            result = await client.read_resource("resource://prefix/test-resource")
+            assert isinstance(result[0], TextResourceContents)
+            assert result[0].text == "Resource content"
+
+            # Absolute path resource
+            result = await client.read_resource("resource://prefix//absolute/path")
+            assert isinstance(result[0], TextResourceContents)
+            assert result[0].text == "Absolute resource content"
+
+            # Template resource
+            result = await client.read_resource(
+                "resource://prefix/param-value/template"
+            )
+            assert isinstance(result[0], TextResourceContents)
+            assert result[0].text == "Template resource with param-value"
+
+
+class TestSettingsFromEnvironment:
+    async def test_server_starts_without_auth(self):
+        """Test that server starts without auth configured."""
+        from fastmcp.client.transports import PythonStdioTransport
+
+        script = dedent("""
+        import fastmcp
+        
+        mcp = fastmcp.FastMCP("TestServer")
+
+        mcp.run()
+        """)
+
+        with TemporaryDirectory() as temp_dir:
+            server_file = Path(temp_dir) / "server.py"
+            server_file.write_text(script)
+
+            transport: PythonStdioTransport = PythonStdioTransport(
+                script_path=server_file
+            )
+
+            async with Client[PythonStdioTransport](transport=transport) as client:
+                tools = await client.list_tools()
+
+                assert tools == []
+
+
+class TestAbstractCollectionTypes:
+    """Test that FastMCP accepts abstract collection types from collections.abc."""
+
+    async def test_fastmcp_init_with_tuples(self):
+        """Test FastMCP accepts tuples for sequence parameters."""
+
+        def dummy_tool() -> str:
+            return "test"
+
+        # Test with tuples and other abstract types
+        mcp = FastMCP(
+            "test",
+            middleware=(),  # Empty tuple
+            tools=(Tool.from_function(dummy_tool),),  # Tuple of tools
+        )
+        mcp.enable(tags={"tag1", "tag2"}, only=True)
+        mcp.disable(tags={"tag3"})
+        assert mcp is not None
+        assert mcp.name == "test"
+        assert isinstance(mcp.middleware, list)  # Should be converted to list
+
+    async def test_fastmcp_works_with_abstract_types(self):
+        """Test that abstract types work end-to-end with a client."""
+
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        # Create server with tuple of tools
+        mcp = FastMCP("test", tools=(Tool.from_function(greet),))
+
+        # Verify it works with a client
+        async with Client(mcp) as client:
+            result = await client.call_tool("greet", {"name": "World"})
+            assert isinstance(result.content[0], TextContent)
+            assert result.content[0].text == "Hello, World!"
+
+
+class TestMeta:
+    """Test that fastmcp key is always present in meta."""
+
+    async def test_tool_tags_in_meta(self):
+        """Test that tool tags appear in meta under fastmcp key."""
+        mcp = FastMCP()
+
+        @mcp.tool(tags={"tool-example", "test-tool-tag"})
+        def sample_tool(x: int) -> int:
+            """A sample tool."""
+            return x * 2
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            tool = next(t for t in tools if t.name == "sample_tool")
+            assert tool.meta is not None
+            assert set(tool.meta["fastmcp"]["tags"]) == {
+                "tool-example",
+                "test-tool-tag",
+            }
+
+    async def test_resource_tags_in_meta(self):
+        """Test that resource tags appear in meta under fastmcp key."""
+        mcp = FastMCP()
+
+        @mcp.resource(
+            uri="test://resource", tags={"resource-example", "test-resource-tag"}
+        )
+        def sample_resource() -> str:
+            """A sample resource."""
+            return "resource content"
+
+        async with Client(mcp) as client:
+            resources = await client.list_resources()
+            resource = next(r for r in resources if str(r.uri) == "test://resource")
+            assert resource.meta is not None
+            assert set(resource.meta["fastmcp"]["tags"]) == {
+                "resource-example",
+                "test-resource-tag",
+            }
+
+    async def test_resource_template_tags_in_meta(self):
+        """Test that resource template tags appear in meta under fastmcp key."""
+        mcp = FastMCP()
+
+        @mcp.resource(
+            "test://template/{id}", tags={"template-example", "test-template-tag"}
+        )
+        def sample_template(id: str) -> str:
+            """A sample resource template."""
+            return f"template content for {id}"
+
+        async with Client(mcp) as client:
+            templates = await client.list_resource_templates()
+            template = next(
+                t for t in templates if t.uri_template == "test://template/{id}"
+            )
+            assert template.meta is not None
+            assert set(template.meta["fastmcp"]["tags"]) == {
+                "template-example",
+                "test-template-tag",
+            }
+
+    async def test_prompt_tags_in_meta(self):
+        """Test that prompt tags appear in meta under fastmcp key."""
+        mcp = FastMCP()
+
+        @mcp.prompt(tags={"example", "test-tag"})
+        def sample_prompt() -> str:
+            return "Hello, world!"
+
+        async with Client(mcp) as client:
+            prompts = await client.list_prompts()
+            prompt = next(p for p in prompts if p.name == "sample_prompt")
+            assert prompt.meta is not None
+            assert set(prompt.meta["fastmcp"]["tags"]) == {"example", "test-tag"}
+
+
+class TestShowServerBannerSetting:
+    """Test that show_server_banner setting controls banner display."""
+
+    async def test_show_banner_defaults_to_setting_true(self):
+        """Test that show_banner=None uses the setting (default True)."""
+        mcp = FastMCP()
+
+        with mock.patch.object(mcp, "run_stdio_async") as mock_run:
+            mock_run.return_value = None
+            await mcp.run_async(transport="stdio")
+            mock_run.assert_called_once()
+            assert mock_run.call_args.kwargs["show_banner"] is True
+
+    async def test_show_banner_respects_setting_false(self):
+        """Test that show_banner=None uses the setting when False."""
+        mcp = FastMCP()
+
+        with mock.patch.dict(os.environ, {"FASTMCP_SHOW_SERVER_BANNER": "false"}):
+            with temporary_settings(show_server_banner=False):
+                with mock.patch.object(mcp, "run_stdio_async") as mock_run:
+                    mock_run.return_value = None
+                    await mcp.run_async(transport="stdio")
+                    mock_run.assert_called_once()
+                    assert mock_run.call_args.kwargs["show_banner"] is False
+
+    async def test_show_banner_explicit_true_overrides_setting(self):
+        """Test that explicit show_banner=True overrides False setting."""
+        mcp = FastMCP()
+
+        with temporary_settings(show_server_banner=False):
+            with mock.patch.object(mcp, "run_stdio_async") as mock_run:
+                mock_run.return_value = None
+                await mcp.run_async(transport="stdio", show_banner=True)
+                mock_run.assert_called_once()
+                assert mock_run.call_args.kwargs["show_banner"] is True
+
+    async def test_show_banner_explicit_false_overrides_setting(self):
+        """Test that explicit show_banner=False overrides True setting."""
+        mcp = FastMCP()
+
+        with temporary_settings(show_server_banner=True):
+            with mock.patch.object(mcp, "run_stdio_async") as mock_run:
+                mock_run.return_value = None
+                await mcp.run_async(transport="stdio", show_banner=False)
+                mock_run.assert_called_once()
+                assert mock_run.call_args.kwargs["show_banner"] is False
diff --git a/tests/server/test_server_docket.py b/tests/server/test_server_docket.py
new file mode 100644
index 0000000..7d0b7f5
--- /dev/null
+++ b/tests/server/test_server_docket.py
@@ -0,0 +1,227 @@
+"""Tests for Docket integration in FastMCP."""
+
+import asyncio
+from contextlib import asynccontextmanager
+
+from docket import Docket
+from docket.worker import Worker
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.dependencies import CurrentDocket, CurrentWorker
+from fastmcp.server.dependencies import get_context
+
+HUZZAH = "huzzah!"
+
+
+async def test_docket_not_initialized_without_task_components():
+    """Docket is only initialized when task-enabled components exist."""
+    mcp = FastMCP("test-server")
+
+    @mcp.tool()
+    def regular_tool() -> str:
+        return "no docket needed"
+
+    async with Client(mcp) as client:
+        # Docket should not be initialized
+        assert mcp._docket is None
+
+        # Regular tools still work
+        result = await client.call_tool("regular_tool", {})
+        assert result.data == "no docket needed"
+
+
+async def test_current_docket():
+    """CurrentDocket dependency provides access to Docket instance."""
+    mcp = FastMCP("test-server")
+
+    # Need a task-enabled component to trigger Docket initialization
+    @mcp.tool(task=True)
+    async def _trigger_docket() -> str:
+        return "trigger"
+
+    @mcp.tool()
+    def check_docket(docket: Docket = CurrentDocket()) -> str:
+        assert isinstance(docket, Docket)
+        return HUZZAH
+
+    async with Client(mcp) as client:
+        result = await client.call_tool("check_docket", {})
+        assert HUZZAH in str(result)
+
+
+async def test_current_worker():
+    """CurrentWorker dependency provides access to Worker instance."""
+    mcp = FastMCP("test-server")
+
+    # Need a task-enabled component to trigger Docket initialization
+    @mcp.tool(task=True)
+    async def _trigger_docket() -> str:
+        return "trigger"
+
+    @mcp.tool()
+    def check_worker(
+        worker: Worker = CurrentWorker(),
+        docket: Docket = CurrentDocket(),
+    ) -> str:
+        assert isinstance(worker, Worker)
+        assert worker.docket is docket
+        return HUZZAH
+
+    async with Client(mcp) as client:
+        result = await client.call_tool("check_worker", {})
+        assert HUZZAH in str(result)
+
+
+async def test_worker_executes_background_tasks():
+    """Verify that the Docket Worker is running and executes tasks."""
+    task_completed = asyncio.Event()
+    mcp = FastMCP("test-server")
+
+    # Need a task-enabled component to trigger Docket initialization
+    @mcp.tool(task=True)
+    async def _trigger_docket() -> str:
+        return "trigger"
+
+    @mcp.tool()
+    async def schedule_work(
+        task_name: str,
+        docket: Docket = CurrentDocket(),
+    ) -> str:
+        """Schedule a background task."""
+
+        async def background_task(name: str):
+            """Simple background task that signals completion."""
+            task_completed.set()
+
+        # Schedule the task (Worker running in background will execute it)
+        await docket.add(background_task)(task_name)
+
+        return f"Scheduled {task_name}"
+
+    async with Client(mcp) as client:
+        result = await client.call_tool("schedule_work", {"task_name": "test-task"})
+        assert "Scheduled test-task" in str(result)
+
+        # Wait for background task to execute (max 2 seconds)
+        await asyncio.wait_for(task_completed.wait(), timeout=2.0)
+
+
+async def test_current_docket_in_resource():
+    """CurrentDocket works in resources."""
+    mcp = FastMCP("test-server")
+
+    # Need a task-enabled component to trigger Docket initialization
+    @mcp.tool(task=True)
+    async def _trigger_docket() -> str:
+        return "trigger"
+
+    @mcp.resource("docket://info")
+    def get_docket_info(docket: Docket = CurrentDocket()) -> str:
+        assert isinstance(docket, Docket)
+        return HUZZAH
+
+    async with Client(mcp) as client:
+        result = await client.read_resource("docket://info")
+        assert HUZZAH in str(result)
+
+
+async def test_current_docket_in_prompt():
+    """CurrentDocket works in prompts."""
+    mcp = FastMCP("test-server")
+
+    # Need a task-enabled component to trigger Docket initialization
+    @mcp.tool(task=True)
+    async def _trigger_docket() -> str:
+        return "trigger"
+
+    @mcp.prompt()
+    def task_prompt(task_type: str, docket: Docket = CurrentDocket()) -> str:
+        assert isinstance(docket, Docket)
+        return HUZZAH
+
+    async with Client(mcp) as client:
+        result = await client.get_prompt("task_prompt", {"task_type": "background"})
+        assert HUZZAH in str(result)
+
+
+async def test_current_docket_in_resource_template():
+    """CurrentDocket works in resource templates."""
+    mcp = FastMCP("test-server")
+
+    # Need a task-enabled component to trigger Docket initialization
+    @mcp.tool(task=True)
+    async def _trigger_docket() -> str:
+        return "trigger"
+
+    @mcp.resource("docket://tasks/{task_id}")
+    def get_task_status(task_id: str, docket: Docket = CurrentDocket()) -> str:
+        assert isinstance(docket, Docket)
+        return HUZZAH
+
+    async with Client(mcp) as client:
+        result = await client.read_resource("docket://tasks/123")
+        assert HUZZAH in str(result)
+
+
+async def test_concurrent_calls_maintain_isolation():
+    """Multiple concurrent calls each get the same Docket instance."""
+    mcp = FastMCP("test-server")
+    docket_ids = []
+
+    # Need a task-enabled component to trigger Docket initialization
+    @mcp.tool(task=True)
+    async def _trigger_docket() -> str:
+        return "trigger"
+
+    @mcp.tool()
+    def capture_docket_id(call_num: int, docket: Docket = CurrentDocket()) -> str:
+        docket_ids.append((call_num, id(docket)))
+        return HUZZAH
+
+    async with Client(mcp) as client:
+        results = await asyncio.gather(
+            client.call_tool("capture_docket_id", {"call_num": 1}),
+            client.call_tool("capture_docket_id", {"call_num": 2}),
+            client.call_tool("capture_docket_id", {"call_num": 3}),
+        )
+
+        for result in results:
+            assert HUZZAH in str(result)
+
+        # All calls should see the same Docket instance
+        assert len(docket_ids) == 3
+        first_id = docket_ids[0][1]
+        assert all(docket_id == first_id for _, docket_id in docket_ids)
+
+
+async def test_user_lifespan_still_works_with_docket():
+    """User-provided lifespan works correctly alongside Docket."""
+    lifespan_entered = False
+
+    @asynccontextmanager
+    async def custom_lifespan(server: FastMCP):
+        nonlocal lifespan_entered
+        lifespan_entered = True
+        yield {"custom_data": "test_value"}
+
+    mcp = FastMCP("test-server", lifespan=custom_lifespan)
+
+    # Need a task-enabled component to trigger Docket initialization
+    @mcp.tool(task=True)
+    async def _trigger_docket() -> str:
+        return "trigger"
+
+    @mcp.tool()
+    def check_both(docket: Docket = CurrentDocket()) -> str:
+        assert isinstance(docket, Docket)
+        ctx = get_context()
+        assert ctx.request_context is not None
+        lifespan_data = ctx.request_context.lifespan_context
+        assert lifespan_data.get("custom_data") == "test_value"
+        return HUZZAH
+
+    async with Client(mcp) as client:
+        assert lifespan_entered
+        result = await client.call_tool("check_both", {})
+        assert HUZZAH in str(result)
diff --git a/tests/server/test_server_lifespan.py b/tests/server/test_server_lifespan.py
new file mode 100644
index 0000000..0a5c6f2
--- /dev/null
+++ b/tests/server/test_server_lifespan.py
@@ -0,0 +1,662 @@
+"""Tests for server_lifespan and session_lifespan behavior."""
+
+import asyncio
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+import anyio
+import pytest
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.context import Context
+from fastmcp.server.lifespan import ContextManagerLifespan, lifespan
+from fastmcp.server.providers import Provider
+from fastmcp.utilities.lifespan import combine_lifespans
+
+
+class TestServerLifespan:
+    """Test server_lifespan functionality."""
+
+    async def test_server_lifespan_basic(self):
+        """Test that server_lifespan is entered once and persists across sessions."""
+        lifespan_events: list[str] = []
+
+        @asynccontextmanager
+        async def server_lifespan(mcp: FastMCP) -> AsyncIterator[dict[str, Any]]:
+            lifespan_events.append("enter")
+            try:
+                yield {"initialized": True}
+            finally:
+                lifespan_events.append("exit")
+
+        mcp = FastMCP("TestServer", lifespan=server_lifespan)
+
+        @mcp.tool
+        def get_value() -> str:
+            return "test"
+
+        # Server lifespan should be entered when run_async starts
+        assert lifespan_events == []
+
+        # Connect first client session
+        async with Client(mcp) as client1:
+            result1 = await client1.call_tool("get_value", {})
+            assert result1.data == "test"
+            # Server lifespan should have been entered once
+            assert lifespan_events == ["enter"]
+
+            # Connect second client session while first is still active
+            async with Client(mcp) as client2:
+                result2 = await client2.call_tool("get_value", {})
+                assert result2.data == "test"
+                # Server lifespan should still only have been entered once
+                assert lifespan_events == ["enter"]
+
+        # Because we're using a fastmcptransport, the server lifespan should be exited
+        # when the client session closes
+        assert lifespan_events == ["enter", "exit"]
+
+    async def test_server_lifespan_overlapping_sessions(self):
+        """Test that overlapping sessions keep lifespan active until all sessions close."""
+        lifespan_events: list[str] = []
+
+        resource_state = "missing"
+
+        @asynccontextmanager
+        async def server_lifespan(mcp: FastMCP) -> AsyncIterator[dict[str, Any]]:
+            nonlocal resource_state
+            lifespan_events.append("enter")
+            resource_state = "open"
+            try:
+                yield {"initialized": True}
+            finally:
+                resource_state = "closed"
+                lifespan_events.append("exit")
+
+        mcp = FastMCP("TestServer", lifespan=server_lifespan)
+
+        @mcp.tool
+        def get_resource_state() -> str:
+            return resource_state
+
+        async with Client(mcp) as client1:
+            result1 = await client1.call_tool("get_resource_state", {})
+            assert result1.data == "open"
+
+            async with Client(mcp) as client2:
+                result2 = await client2.call_tool("get_resource_state", {})
+                assert result2.data == "open"
+
+            # client2 exited while client1 is still active; lifespan should remain open
+            result3 = await client1.call_tool("get_resource_state", {})
+            assert result3.data == "open"
+            assert lifespan_events == ["enter"]
+
+        assert lifespan_events == ["enter", "exit"]
+
+    async def test_server_lifespan_context_available(self):
+        """Test that server_lifespan context is available to tools."""
+
+        @asynccontextmanager
+        async def server_lifespan(mcp: FastMCP) -> AsyncIterator[dict]:
+            yield {"db_connection": "mock_db"}
+
+        mcp = FastMCP("TestServer", lifespan=server_lifespan)
+
+        @mcp.tool
+        def get_db_info(ctx: Context) -> str:
+            # Access the server lifespan context
+            assert ctx.request_context is not None  # type narrowing for type checker
+            lifespan_context = ctx.request_context.lifespan_context
+            return lifespan_context.get("db_connection", "no_db")
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("get_db_info", {})
+            assert result.data == "mock_db"
+
+
+class TestComposableLifespans:
+    """Test composable lifespan functionality."""
+
+    async def test_lifespan_decorator_basic(self):
+        """Test that the @lifespan decorator works like @asynccontextmanager."""
+        events: list[str] = []
+
+        @lifespan
+        async def my_lifespan(server: FastMCP) -> AsyncIterator[dict[str, Any]]:
+            events.append("enter")
+            try:
+                yield {"key": "value"}
+            finally:
+                events.append("exit")
+
+        mcp = FastMCP("TestServer", lifespan=my_lifespan)
+
+        @mcp.tool
+        def get_info(ctx: Context) -> str:
+            assert ctx.request_context is not None
+            lifespan_context = ctx.request_context.lifespan_context
+            return lifespan_context.get("key", "missing")
+
+        assert events == []
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("get_info", {})
+            assert result.data == "value"
+            assert events == ["enter"]
+
+        assert events == ["enter", "exit"]
+
+    async def test_lifespan_composition_two(self):
+        """Test composing two lifespans with |."""
+        events: list[str] = []
+
+        @lifespan
+        async def first_lifespan(server: FastMCP) -> AsyncIterator[dict[str, Any]]:
+            events.append("first_enter")
+            try:
+                yield {"first": "a"}
+            finally:
+                events.append("first_exit")
+
+        @lifespan
+        async def second_lifespan(server: FastMCP) -> AsyncIterator[dict[str, Any]]:
+            events.append("second_enter")
+            try:
+                yield {"second": "b"}
+            finally:
+                events.append("second_exit")
+
+        composed = first_lifespan | second_lifespan
+        mcp = FastMCP("TestServer", lifespan=composed)
+
+        @mcp.tool
+        def get_both(ctx: Context) -> dict:
+            assert ctx.request_context is not None
+            return dict(ctx.request_context.lifespan_context)
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("get_both", {})
+            # Results should be merged
+            assert result.data == {"first": "a", "second": "b"}
+            # Should enter in order
+            assert events == ["first_enter", "second_enter"]
+
+        # Should exit in reverse order (LIFO)
+        assert events == ["first_enter", "second_enter", "second_exit", "first_exit"]
+
+    async def test_lifespan_composition_three(self):
+        """Test composing three lifespans with |."""
+        events: list[str] = []
+
+        @lifespan
+        async def ls_a(server: FastMCP) -> AsyncIterator[dict[str, Any]]:
+            events.append("a_enter")
+            try:
+                yield {"a": 1}
+            finally:
+                events.append("a_exit")
+
+        @lifespan
+        async def ls_b(server: FastMCP) -> AsyncIterator[dict[str, Any]]:
+            events.append("b_enter")
+            try:
+                yield {"b": 2}
+            finally:
+                events.append("b_exit")
+
+        @lifespan
+        async def ls_c(server: FastMCP) -> AsyncIterator[dict[str, Any]]:
+            events.append("c_enter")
+            try:
+                yield {"c": 3}
+            finally:
+                events.append("c_exit")
+
+        composed = ls_a | ls_b | ls_c
+        mcp = FastMCP("TestServer", lifespan=composed)
+
+        @mcp.tool
+        def get_all(ctx: Context) -> dict:
+            assert ctx.request_context is not None
+            return dict(ctx.request_context.lifespan_context)
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("get_all", {})
+            assert result.data == {"a": 1, "b": 2, "c": 3}
+            assert events == ["a_enter", "b_enter", "c_enter"]
+
+        assert events == [
+            "a_enter",
+            "b_enter",
+            "c_enter",
+            "c_exit",
+            "b_exit",
+            "a_exit",
+        ]
+
+    async def test_lifespan_result_merge_later_wins(self):
+        """Test that later lifespans overwrite earlier ones on key conflict."""
+
+        @lifespan
+        async def first(server: FastMCP) -> AsyncIterator[dict[str, Any]]:
+            yield {"key": "first", "only_first": "yes"}
+
+        @lifespan
+        async def second(server: FastMCP) -> AsyncIterator[dict[str, Any]]:
+            yield {"key": "second", "only_second": "yes"}
+
+        composed = first | second
+        mcp = FastMCP("TestServer", lifespan=composed)
+
+        @mcp.tool
+        def get_context(ctx: Context) -> dict:
+            assert ctx.request_context is not None
+            return dict(ctx.request_context.lifespan_context)
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("get_context", {})
+            # "key" should be overwritten by second
+            assert result.data == {
+                "key": "second",
+                "only_first": "yes",
+                "only_second": "yes",
+            }
+
+    async def test_lifespan_composition_with_context_manager_lifespan(self):
+        """Test composing with ContextManagerLifespan for @asynccontextmanager functions."""
+        events: list[str] = []
+
+        @asynccontextmanager
+        async def legacy_lifespan(server: FastMCP) -> AsyncIterator[dict[str, Any]]:
+            events.append("legacy_enter")
+            try:
+                yield {"legacy": True}
+            finally:
+                events.append("legacy_exit")
+
+        @lifespan
+        async def new_lifespan(server: FastMCP) -> AsyncIterator[dict[str, Any]]:
+            events.append("new_enter")
+            try:
+                yield {"new": True}
+            finally:
+                events.append("new_exit")
+
+        # Wrap the @asynccontextmanager function explicitly
+        composed = ContextManagerLifespan(legacy_lifespan) | new_lifespan
+        mcp = FastMCP("TestServer", lifespan=composed)
+
+        @mcp.tool
+        def get_context(ctx: Context) -> dict:
+            assert ctx.request_context is not None
+            return dict(ctx.request_context.lifespan_context)
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("get_context", {})
+            assert result.data == {"legacy": True, "new": True}
+
+        assert events == [
+            "legacy_enter",
+            "new_enter",
+            "new_exit",
+            "legacy_exit",
+        ]
+
+    async def test_backwards_compatibility_asynccontextmanager(self):
+        """Test that existing @asynccontextmanager lifespans still work."""
+
+        @asynccontextmanager
+        async def old_style_lifespan(server: FastMCP) -> AsyncIterator[dict[str, Any]]:
+            yield {"old_style": True}
+
+        mcp = FastMCP("TestServer", lifespan=old_style_lifespan)
+
+        @mcp.tool
+        def get_context(ctx: Context) -> dict:
+            assert ctx.request_context is not None
+            return dict(ctx.request_context.lifespan_context)
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("get_context", {})
+            assert result.data == {"old_style": True}
+
+    async def test_lifespan_or_requires_lifespan_instance(self):
+        """Test that | operator requires Lifespan instances and gives helpful error."""
+
+        @lifespan
+        async def my_lifespan(server: FastMCP) -> AsyncIterator[dict[str, Any]]:
+            yield {"key": "value"}
+
+        @asynccontextmanager
+        async def regular_lifespan(server: FastMCP) -> AsyncIterator[dict[str, Any]]:
+            yield {"regular": True}
+
+        # Composing with non-Lifespan should raise TypeError with helpful message
+        with pytest.raises(TypeError) as exc_info:
+            my_lifespan | regular_lifespan  # type: ignore[operator]  # ty:ignore[unsupported-operator]
+
+        assert "ContextManagerLifespan" in str(exc_info.value)
+
+
+class TestCombineLifespans:
+    """Test combine_lifespans utility function."""
+
+    async def test_combine_lifespans_fastapi_style(self):
+        """Test combining lifespans that yield None (FastAPI-style)."""
+        events: list[str] = []
+
+        @asynccontextmanager
+        async def first_lifespan(app: Any) -> AsyncIterator[None]:
+            events.append("first_enter")
+            try:
+                yield
+            finally:
+                events.append("first_exit")
+
+        @asynccontextmanager
+        async def second_lifespan(app: Any) -> AsyncIterator[None]:
+            events.append("second_enter")
+            try:
+                yield
+            finally:
+                events.append("second_exit")
+
+        combined = combine_lifespans(first_lifespan, second_lifespan)
+
+        async with combined("mock_app") as result:
+            assert result == {}  # Empty dict when lifespans yield None
+            assert events == ["first_enter", "second_enter"]
+
+        # LIFO exit order
+        assert events == ["first_enter", "second_enter", "second_exit", "first_exit"]
+
+    async def test_combine_lifespans_fastmcp_style(self):
+        """Test combining lifespans that yield dicts (FastMCP-style)."""
+        events: list[str] = []
+
+        @asynccontextmanager
+        async def db_lifespan(app: Any) -> AsyncIterator[dict[str, Any]]:
+            events.append("db_enter")
+            try:
+                yield {"db": "connected"}
+            finally:
+                events.append("db_exit")
+
+        @asynccontextmanager
+        async def cache_lifespan(app: Any) -> AsyncIterator[dict[str, Any]]:
+            events.append("cache_enter")
+            try:
+                yield {"cache": "ready"}
+            finally:
+                events.append("cache_exit")
+
+        combined = combine_lifespans(db_lifespan, cache_lifespan)
+
+        async with combined("mock_app") as result:
+            assert result == {"db": "connected", "cache": "ready"}
+            assert events == ["db_enter", "cache_enter"]
+
+        assert events == ["db_enter", "cache_enter", "cache_exit", "db_exit"]
+
+    async def test_combine_lifespans_mixed_styles(self):
+        """Test combining FastAPI-style (yield None) and FastMCP-style (yield dict)."""
+        events: list[str] = []
+
+        @asynccontextmanager
+        async def fastapi_lifespan(app: Any) -> AsyncIterator[None]:
+            events.append("fastapi_enter")
+            try:
+                yield  # FastAPI-style: yield None
+            finally:
+                events.append("fastapi_exit")
+
+        @asynccontextmanager
+        async def fastmcp_lifespan(app: Any) -> AsyncIterator[dict[str, Any]]:
+            events.append("fastmcp_enter")
+            try:
+                yield {"mcp": "initialized"}  # FastMCP-style: yield dict
+            finally:
+                events.append("fastmcp_exit")
+
+        combined = combine_lifespans(fastapi_lifespan, fastmcp_lifespan)
+
+        async with combined("mock_app") as result:
+            # Only the dict from fastmcp_lifespan should be present
+            assert result == {"mcp": "initialized"}
+            assert events == ["fastapi_enter", "fastmcp_enter"]
+
+        assert events == [
+            "fastapi_enter",
+            "fastmcp_enter",
+            "fastmcp_exit",
+            "fastapi_exit",
+        ]
+
+    async def test_combine_lifespans_result_merge_later_wins(self):
+        """Test that later lifespans overwrite earlier ones on key conflict."""
+
+        @asynccontextmanager
+        async def first(app: Any) -> AsyncIterator[dict[str, Any]]:
+            yield {"key": "first", "only_first": "yes"}
+
+        @asynccontextmanager
+        async def second(app: Any) -> AsyncIterator[dict[str, Any]]:
+            yield {"key": "second", "only_second": "yes"}
+
+        combined = combine_lifespans(first, second)
+
+        async with combined("mock_app") as result:
+            assert result == {
+                "key": "second",  # Overwritten by later lifespan
+                "only_first": "yes",
+                "only_second": "yes",
+            }
+
+    async def test_combine_lifespans_three(self):
+        """Test combining three lifespans."""
+        events: list[str] = []
+
+        @asynccontextmanager
+        async def ls_a(app: Any) -> AsyncIterator[dict[str, Any]]:
+            events.append("a_enter")
+            try:
+                yield {"a": 1}
+            finally:
+                events.append("a_exit")
+
+        @asynccontextmanager
+        async def ls_b(app: Any) -> AsyncIterator[dict[str, Any]]:
+            events.append("b_enter")
+            try:
+                yield {"b": 2}
+            finally:
+                events.append("b_exit")
+
+        @asynccontextmanager
+        async def ls_c(app: Any) -> AsyncIterator[dict[str, Any]]:
+            events.append("c_enter")
+            try:
+                yield {"c": 3}
+            finally:
+                events.append("c_exit")
+
+        combined = combine_lifespans(ls_a, ls_b, ls_c)
+
+        async with combined("mock_app") as result:
+            assert result == {"a": 1, "b": 2, "c": 3}
+            assert events == ["a_enter", "b_enter", "c_enter"]
+
+        assert events == [
+            "a_enter",
+            "b_enter",
+            "c_enter",
+            "c_exit",
+            "b_exit",
+            "a_exit",
+        ]
+
+    async def test_combine_lifespans_empty(self):
+        """Test combining zero lifespans."""
+        combined = combine_lifespans()
+
+        async with combined("mock_app") as result:
+            assert result == {}
+
+    async def test_combine_lifespans_with_mapping_return_type(self):
+        """Test combining lifespans that return Mapping (like Starlette's Lifespan).
+
+        This verifies that combine_lifespans accepts lifespans returning Mapping[str, Any],
+        which is the type that Starlette's Lifespan uses, not just dict[str, Any].
+        """
+        from collections.abc import Mapping
+
+        events: list[str] = []
+
+        @asynccontextmanager
+        async def mapping_lifespan(app: Any) -> AsyncIterator[Mapping[str, Any]]:
+            """Simulates a Starlette-style lifespan that yields a Mapping."""
+            events.append("mapping_enter")
+            try:
+                yield {"starlette_state": "initialized"}
+            finally:
+                events.append("mapping_exit")
+
+        @asynccontextmanager
+        async def dict_lifespan(app: Any) -> AsyncIterator[dict[str, Any]]:
+            events.append("dict_enter")
+            try:
+                yield {"fastmcp_state": "ready"}
+            finally:
+                events.append("dict_exit")
+
+        combined = combine_lifespans(mapping_lifespan, dict_lifespan)
+
+        async with combined("mock_app") as result:
+            assert result == {
+                "starlette_state": "initialized",
+                "fastmcp_state": "ready",
+            }
+            assert events == ["mapping_enter", "dict_enter"]
+
+        assert events == [
+            "mapping_enter",
+            "dict_enter",
+            "dict_exit",
+            "mapping_exit",
+        ]
+
+
+class TestLifespanTeardownShielding:
+    """Test that async operations in lifespan teardown complete under cancellation.
+
+    When a server shuts down (e.g. Ctrl-C), the cancel scope becomes active.
+    Lifespan teardown must be shielded from cancellation so that async cleanup
+    (closing DB connections, flushing buffers, etc.) can actually run.
+    """
+
+    async def test_server_lifespan_async_teardown_under_cancellation(self):
+        """Async operations in server lifespan finally block complete even when cancelled."""
+        events: list[str] = []
+
+        @asynccontextmanager
+        async def server_lifespan(mcp: FastMCP) -> AsyncIterator[dict[str, Any]]:
+            events.append("setup")
+            try:
+                yield {}
+            finally:
+                events.append("teardown_start")
+                await asyncio.sleep(0)
+                events.append("teardown_complete")
+
+        mcp = FastMCP("TestServer", lifespan=server_lifespan)
+
+        async with anyio.create_task_group() as tg:
+
+            async def run_and_cancel() -> None:
+                async with mcp._lifespan_manager():
+                    tg.cancel_scope.cancel()
+
+            tg.start_soon(run_and_cancel)
+
+        assert "setup" in events
+        assert "teardown_start" in events
+        assert "teardown_complete" in events
+
+    async def test_provider_lifespan_async_teardown_under_cancellation(self):
+        """Async operations in provider lifespan finally block complete when cancelled."""
+        events: list[str] = []
+
+        class TestProvider(Provider):
+            @asynccontextmanager
+            async def lifespan(self) -> AsyncIterator[None]:
+                events.append("provider_setup")
+                try:
+                    yield
+                finally:
+                    events.append("provider_teardown_start")
+                    await asyncio.sleep(0)
+                    events.append("provider_teardown_complete")
+
+        mcp = FastMCP("TestServer", providers=[TestProvider()])
+
+        async with anyio.create_task_group() as tg:
+
+            async def run_and_cancel() -> None:
+                async with mcp._lifespan_manager():
+                    tg.cancel_scope.cancel()
+
+            tg.start_soon(run_and_cancel)
+
+        assert "provider_setup" in events
+        assert "provider_teardown_start" in events
+        assert "provider_teardown_complete" in events
+
+    async def test_composed_lifespans_async_teardown_under_cancellation(self):
+        """Both server and provider async teardown completes under cancellation."""
+        events: list[str] = []
+
+        @asynccontextmanager
+        async def server_lifespan(mcp: FastMCP) -> AsyncIterator[dict[str, Any]]:
+            events.append("server_setup")
+            try:
+                yield {}
+            finally:
+                events.append("server_teardown_start")
+                await asyncio.sleep(0)
+                events.append("server_teardown_complete")
+
+        class TestProvider(Provider):
+            @asynccontextmanager
+            async def lifespan(self) -> AsyncIterator[None]:
+                events.append("provider_setup")
+                try:
+                    yield
+                finally:
+                    events.append("provider_teardown_start")
+                    await asyncio.sleep(0)
+                    events.append("provider_teardown_complete")
+
+        mcp = FastMCP(
+            "TestServer",
+            lifespan=server_lifespan,
+            providers=[TestProvider()],
+        )
+
+        async with anyio.create_task_group() as tg:
+
+            async def run_and_cancel() -> None:
+                async with mcp._lifespan_manager():
+                    tg.cancel_scope.cancel()
+
+            tg.start_soon(run_and_cancel)
+
+        assert events == [
+            "server_setup",
+            "provider_setup",
+            "provider_teardown_start",
+            "provider_teardown_complete",
+            "server_teardown_start",
+            "server_teardown_complete",
+        ]
diff --git a/tests/server/test_server_safety.py b/tests/server/test_server_safety.py
new file mode 100644
index 0000000..2d85b09
--- /dev/null
+++ b/tests/server/test_server_safety.py
@@ -0,0 +1,10 @@
+import pytest
+
+from fastmcp import FastMCP
+
+
+class TestMountSafety:
+    def test_self_mount_raises(self):
+        mcp = FastMCP("test")
+        with pytest.raises(ValueError, match="Cannot mount a server onto itself"):
+            mcp.mount(mcp)
diff --git a/tests/server/test_session_visibility.py b/tests/server/test_session_visibility.py
new file mode 100644
index 0000000..d98a0d7
--- /dev/null
+++ b/tests/server/test_session_visibility.py
@@ -0,0 +1,769 @@
+"""Tests for session-specific visibility control via Context."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+import anyio
+import mcp_types
+
+from fastmcp.client.messages import MessageHandler
+from fastmcp.server.context import Context
+from fastmcp.server.server import FastMCP
+
+
+@dataclass
+class NotificationRecording:
+    """Record of a notification that was received."""
+
+    method: str
+    notification: mcp_types.ServerNotification
+    timestamp: datetime = field(default_factory=datetime.now)
+
+
+class RecordingMessageHandler(MessageHandler):
+    """A message handler that records all notifications."""
+
+    def __init__(self):
+        super().__init__()
+        self.notifications: list[NotificationRecording] = []
+
+    async def on_notification(self, message: mcp_types.ServerNotification) -> None:
+        """Record all notifications with timestamp."""
+        # SDK v2 delivers notifications unwrapped (no `.root` wrapper).
+        self.notifications.append(
+            NotificationRecording(method=message.method, notification=message)
+        )
+
+    def get_notifications(
+        self, method: str | None = None
+    ) -> list[NotificationRecording]:
+        """Get all recorded notifications, optionally filtered by method."""
+        if method is None:
+            return self.notifications
+        return [n for n in self.notifications if n.method == method]
+
+    def reset(self):
+        """Clear all recorded notifications."""
+        self.notifications.clear()
+
+
+class TestSessionVisibility:
+    """Test session-specific visibility control via Context."""
+
+    async def test_enable_components_stores_rule_dict(self):
+        """Test that enable_components stores a rule dict in session state."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool(tags={"finance"})
+        def finance_tool() -> str:
+            return "finance"
+
+        @mcp.tool
+        async def activate_finance(ctx: Context) -> str:
+            await ctx.enable_components(tags={"finance"})
+            # Check that the rule was stored
+            rules = await ctx._get_visibility_rules()
+            assert len(rules) == 1
+            assert rules[0]["enabled"] is True
+            assert rules[0]["tags"] == ["finance"]
+            return "activated"
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("activate_finance", {})
+            assert result.data == "activated"
+
+    async def test_disable_components_stores_rule_dict(self):
+        """Test that disable_components stores a rule dict in session state."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool(tags={"internal"})
+        def internal_tool() -> str:
+            return "internal"
+
+        @mcp.tool
+        async def deactivate_internal(ctx: Context) -> str:
+            await ctx.disable_components(tags={"internal"})
+            # Check that the rule was stored
+            rules = await ctx._get_visibility_rules()
+            assert len(rules) == 1
+            assert rules[0]["enabled"] is False
+            assert rules[0]["tags"] == ["internal"]
+            return "deactivated"
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("deactivate_internal", {})
+            assert result.data == "deactivated"
+
+    async def test_session_rules_override_global_disables(self):
+        """Test that session enable rules override global disable transforms."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool(tags={"finance"})
+        def finance_tool() -> str:
+            return "finance"
+
+        @mcp.tool
+        async def activate_finance(ctx: Context) -> str:
+            await ctx.enable_components(tags={"finance"})
+            return "activated"
+
+        # Globally disable finance tools
+        mcp.disable(tags={"finance"})
+
+        async with Client(mcp) as client:
+            # Before activation, finance tool should not be visible
+            tools_before = await client.list_tools()
+            assert not any(t.name == "finance_tool" for t in tools_before)
+
+            # Activate finance for this session
+            await client.call_tool("activate_finance", {})
+
+            # After activation, finance tool should be visible in this session
+            tools_after = await client.list_tools()
+            assert any(t.name == "finance_tool" for t in tools_after)
+
+    async def test_rules_persist_across_requests(self):
+        """Test that session rules persist across multiple requests."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool(tags={"finance"})
+        def finance_tool() -> str:
+            return "finance"
+
+        @mcp.tool
+        async def activate_finance(ctx: Context) -> str:
+            await ctx.enable_components(tags={"finance"})
+            return "activated"
+
+        @mcp.tool
+        async def check_rules(ctx: Context) -> int:
+            rules = await ctx._get_visibility_rules()
+            return len(rules)
+
+        # Globally disable finance tools
+        mcp.disable(tags={"finance"})
+
+        async with Client(mcp) as client:
+            # Activate finance
+            await client.call_tool("activate_finance", {})
+
+            # In a subsequent request, rules should still be there
+            result = await client.call_tool("check_rules", {})
+            assert result.data == 1
+
+            # And finance tool should still be visible
+            tools = await client.list_tools()
+            assert any(t.name == "finance_tool" for t in tools)
+
+    async def test_rules_isolated_between_sessions(self):
+        """Test that session rules are isolated between different sessions."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool(tags={"finance"})
+        def finance_tool() -> str:
+            return "finance"
+
+        @mcp.tool
+        async def activate_finance(ctx: Context) -> str:
+            await ctx.enable_components(tags={"finance"})
+            return "activated"
+
+        # Globally disable finance tools
+        mcp.disable(tags={"finance"})
+
+        # Session A activates finance
+        async with Client(mcp) as client_a:
+            await client_a.call_tool("activate_finance", {})
+            tools_a = await client_a.list_tools()
+            assert any(t.name == "finance_tool" for t in tools_a)
+
+        # Session B should not see finance tool (different session)
+        async with Client(mcp) as client_b:
+            tools_b = await client_b.list_tools()
+            assert not any(t.name == "finance_tool" for t in tools_b)
+
+    async def test_version_spec_serialization(self):
+        """Test that VersionSpec is serialized/deserialized correctly."""
+        from fastmcp import Client
+        from fastmcp.utilities.versions import VersionSpec
+
+        mcp = FastMCP("test")
+
+        @mcp.tool(version="1.0.0")
+        def old_tool() -> str:
+            return "old"
+
+        @mcp.tool(version="2.0.0")
+        def new_tool() -> str:
+            return "new"
+
+        @mcp.tool
+        async def enable_v2_only(ctx: Context) -> str:
+            await ctx.enable_components(version=VersionSpec(gte="2.0.0"))
+            # Check serialization - version is stored as a dict
+            rules = await ctx._get_visibility_rules()
+            assert rules[0]["version"]["gte"] == "2.0.0"
+            assert rules[0]["version"]["lt"] is None
+            assert rules[0]["version"]["eq"] is None
+            return "enabled"
+
+        # Globally disable all versioned tools
+        mcp.disable(names={"old_tool", "new_tool"})
+
+        async with Client(mcp) as client:
+            # Enable v2 tools
+            await client.call_tool("enable_v2_only", {})
+
+            # Should see new_tool (v2.0.0) but not old_tool (v1.0.0)
+            tools = await client.list_tools()
+            assert any(t.name == "new_tool" for t in tools)
+            assert not any(t.name == "old_tool" for t in tools)
+
+    async def test_clear_visibility_rules(self):
+        """Test that reset_visibility removes all session rules."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool(tags={"finance"})
+        def finance_tool() -> str:
+            return "finance"
+
+        @mcp.tool
+        async def activate_finance(ctx: Context) -> str:
+            await ctx.enable_components(tags={"finance"})
+            return "activated"
+
+        @mcp.tool
+        async def clear_rules(ctx: Context) -> str:
+            await ctx.reset_visibility()
+            rules = await ctx._get_visibility_rules()
+            assert len(rules) == 0
+            return "cleared"
+
+        # Globally disable finance tools
+        mcp.disable(tags={"finance"})
+
+        async with Client(mcp) as client:
+            # Activate finance
+            await client.call_tool("activate_finance", {})
+            tools_after_activate = await client.list_tools()
+            assert any(t.name == "finance_tool" for t in tools_after_activate)
+
+            # Clear rules
+            await client.call_tool("clear_rules", {})
+
+            # Finance tool should no longer be visible (back to global disable)
+            tools_after_clear = await client.list_tools()
+            assert not any(t.name == "finance_tool" for t in tools_after_clear)
+
+    async def test_multiple_rules_accumulate(self):
+        """Test that multiple enable/disable calls accumulate rules."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool(tags={"finance"})
+        def finance_tool() -> str:
+            return "finance"
+
+        @mcp.tool(tags={"admin"})
+        def admin_tool() -> str:
+            return "admin"
+
+        @mcp.tool
+        async def activate_multiple(ctx: Context) -> str:
+            await ctx.enable_components(tags={"finance"})
+            await ctx.enable_components(tags={"admin"})
+            rules = await ctx._get_visibility_rules()
+            assert len(rules) == 2
+            return "activated"
+
+        # Globally disable finance and admin tools
+        mcp.disable(tags={"finance", "admin"})
+
+        async with Client(mcp) as client:
+            # Activate both
+            await client.call_tool("activate_multiple", {})
+
+            # Both should be visible
+            tools = await client.list_tools()
+            assert any(t.name == "finance_tool" for t in tools)
+            assert any(t.name == "admin_tool" for t in tools)
+
+    async def test_later_rules_override_earlier_rules(self):
+        """Test that later session rules override earlier ones (mark semantics)."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool(tags={"test"})
+        def test_tool() -> str:
+            return "test"
+
+        @mcp.tool
+        async def toggle_test(ctx: Context) -> str:
+            # First enable, then disable
+            await ctx.enable_components(tags={"test"})
+            await ctx.disable_components(tags={"test"})
+            return "toggled"
+
+        async with Client(mcp) as client:
+            # Toggle (enable then disable)
+            await client.call_tool("toggle_test", {})
+
+            # The disable should win (later mark overrides earlier)
+            tools = await client.list_tools()
+            assert not any(t.name == "test_tool" for t in tools)
+
+    async def test_session_transforms_apply_to_resources(self):
+        """Test that session transforms apply to resources too."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.resource("resource://finance", tags={"finance"})
+        def finance_resource() -> str:
+            return "finance data"
+
+        @mcp.tool
+        async def activate_finance(ctx: Context) -> str:
+            await ctx.enable_components(tags={"finance"})
+            return "activated"
+
+        # Globally disable finance resources
+        mcp.disable(tags={"finance"})
+
+        async with Client(mcp) as client:
+            # Before activation, finance resource should not be visible
+            resources_before = await client.list_resources()
+            assert not any(str(r.uri) == "resource://finance" for r in resources_before)
+
+            # Activate finance for this session
+            await client.call_tool("activate_finance", {})
+
+            # After activation, finance resource should be visible
+            resources_after = await client.list_resources()
+            assert any(str(r.uri) == "resource://finance" for r in resources_after)
+
+    async def test_session_transforms_apply_to_prompts(self):
+        """Test that session transforms apply to prompts too."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.prompt(tags={"finance"})
+        def finance_prompt() -> str:
+            return "finance prompt"
+
+        @mcp.tool
+        async def activate_finance(ctx: Context) -> str:
+            await ctx.enable_components(tags={"finance"})
+            return "activated"
+
+        # Globally disable finance prompts
+        mcp.disable(tags={"finance"})
+
+        async with Client(mcp) as client:
+            # Before activation, finance prompt should not be visible
+            prompts_before = await client.list_prompts()
+            assert not any(p.name == "finance_prompt" for p in prompts_before)
+
+            # Activate finance for this session
+            await client.call_tool("activate_finance", {})
+
+            # After activation, finance prompt should be visible
+            prompts_after = await client.list_prompts()
+            assert any(p.name == "finance_prompt" for p in prompts_after)
+
+
+class TestSessionVisibilityNotifications:
+    """Test that notifications are sent when session visibility changes."""
+
+    async def test_enable_components_sends_notifications(self):
+        """Test that enable_components sends all three notification types."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        async def activate(ctx: Context) -> str:
+            await ctx.enable_components(tags={"finance"})
+            return "activated"
+
+        handler = RecordingMessageHandler()
+        async with Client(mcp, message_handler=handler) as client:
+            handler.reset()
+            await client.call_tool("activate", {})
+
+            # Should receive all three notifications
+            tool_notifications = handler.get_notifications(
+                "notifications/tools/list_changed"
+            )
+            resource_notifications = handler.get_notifications(
+                "notifications/resources/list_changed"
+            )
+            prompt_notifications = handler.get_notifications(
+                "notifications/prompts/list_changed"
+            )
+            assert len(tool_notifications) == 1
+            assert len(resource_notifications) == 1
+            assert len(prompt_notifications) == 1
+
+    async def test_disable_components_sends_notifications(self):
+        """Test that disable_components sends all three notification types."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        async def deactivate(ctx: Context) -> str:
+            await ctx.disable_components(tags={"finance"})
+            return "deactivated"
+
+        handler = RecordingMessageHandler()
+        async with Client(mcp, message_handler=handler) as client:
+            handler.reset()
+            await client.call_tool("deactivate", {})
+
+            # Should receive all three notifications
+            assert (
+                len(handler.get_notifications("notifications/tools/list_changed")) == 1
+            )
+            assert (
+                len(handler.get_notifications("notifications/resources/list_changed"))
+                == 1
+            )
+            assert (
+                len(handler.get_notifications("notifications/prompts/list_changed"))
+                == 1
+            )
+
+    async def test_clear_visibility_rules_sends_notifications(self):
+        """Test that reset_visibility sends notifications."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        async def clear(ctx: Context) -> str:
+            await ctx.reset_visibility()
+            return "cleared"
+
+        handler = RecordingMessageHandler()
+        async with Client(mcp, message_handler=handler) as client:
+            handler.reset()
+            await client.call_tool("clear", {})
+
+            # Should receive all three notifications
+            assert (
+                len(handler.get_notifications("notifications/tools/list_changed")) == 1
+            )
+            assert (
+                len(handler.get_notifications("notifications/resources/list_changed"))
+                == 1
+            )
+            assert (
+                len(handler.get_notifications("notifications/prompts/list_changed"))
+                == 1
+            )
+
+    async def test_components_hint_limits_notifications(self):
+        """Test that the components hint limits which notifications are sent."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        async def activate_tools_only(ctx: Context) -> str:
+            # Only specify tool components - should only send tool notification
+            await ctx.enable_components(tags={"finance"}, components={"tool"})
+            return "activated"
+
+        handler = RecordingMessageHandler()
+        async with Client(mcp, message_handler=handler) as client:
+            handler.reset()
+            await client.call_tool("activate_tools_only", {})
+
+            # Should only receive tool notification
+            assert (
+                len(handler.get_notifications("notifications/tools/list_changed")) == 1
+            )
+            assert (
+                len(handler.get_notifications("notifications/resources/list_changed"))
+                == 0
+            )
+            assert (
+                len(handler.get_notifications("notifications/prompts/list_changed"))
+                == 0
+            )
+
+
+class TestConcurrentSessionIsolation:
+    """Test that concurrent sessions don't leak visibility transforms."""
+
+    async def test_concurrent_sessions_isolated(self):
+        """Test that two concurrent clients don't leak session transforms."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool(tags={"finance"})
+        def finance_tool() -> str:
+            return "finance"
+
+        @mcp.tool
+        async def activate_finance(ctx: Context) -> str:
+            await ctx.enable_components(tags={"finance"})
+            return "activated"
+
+        # Globally disable finance tools
+        mcp.disable(tags={"finance"})
+
+        # Track what each session sees
+        session_a_sees_finance = False
+        session_b_sees_finance = False
+        ready_event = anyio.Event()
+
+        async def session_a():
+            nonlocal session_a_sees_finance
+            async with Client(mcp) as client:
+                # Activate finance for this session
+                await client.call_tool("activate_finance", {})
+
+                # Signal that session A has activated
+                ready_event.set()
+
+                # Check that session A sees finance tool
+                tools = await client.list_tools()
+                session_a_sees_finance = any(t.name == "finance_tool" for t in tools)
+
+                # Keep session A alive while session B checks
+                await anyio.sleep(0.2)
+
+        async def session_b():
+            nonlocal session_b_sees_finance
+            # Wait for session A to activate
+            await ready_event.wait()
+
+            async with Client(mcp) as client:
+                # Session B should NOT see finance tool
+                tools = await client.list_tools()
+                session_b_sees_finance = any(t.name == "finance_tool" for t in tools)
+
+        async with anyio.create_task_group() as tg:
+            tg.start_soon(session_a)
+            tg.start_soon(session_b)
+
+        # Session A should see finance, session B should not
+        assert session_a_sees_finance is True, "Session A should see finance tool"
+        assert session_b_sees_finance is False, "Session B should NOT see finance tool"
+
+    async def test_many_concurrent_sessions_isolated(self):
+        """Test that many concurrent sessions remain properly isolated."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool(tags={"premium"})
+        def premium_tool() -> str:
+            return "premium"
+
+        @mcp.tool
+        async def activate_premium(ctx: Context) -> str:
+            await ctx.enable_components(tags={"premium"})
+            return "activated"
+
+        # Globally disable premium tools
+        mcp.disable(tags={"premium"})
+
+        results: dict[str, bool] = {}
+
+        async def activated_session(session_id: str):
+            async with Client(mcp) as client:
+                await client.call_tool("activate_premium", {})
+                tools = await client.list_tools()
+                results[session_id] = any(t.name == "premium_tool" for t in tools)
+
+        async def non_activated_session(session_id: str):
+            async with Client(mcp) as client:
+                tools = await client.list_tools()
+                results[session_id] = any(t.name == "premium_tool" for t in tools)
+
+        async with anyio.create_task_group() as tg:
+            # Start 5 activated sessions
+            for i in range(5):
+                tg.start_soon(activated_session, f"activated_{i}")
+            # Start 5 non-activated sessions
+            for i in range(5):
+                tg.start_soon(non_activated_session, f"non_activated_{i}")
+
+        # All activated sessions should see premium tool
+        for i in range(5):
+            assert results[f"activated_{i}"] is True, (
+                f"Activated session {i} should see premium tool"
+            )
+
+        # All non-activated sessions should NOT see premium tool
+        for i in range(5):
+            assert results[f"non_activated_{i}"] is False, (
+                f"Non-activated session {i} should NOT see premium tool"
+            )
+
+
+class TestSessionVisibilityResetBug:
+    """Regression tests for #3034: visibility marks leak via shared component mutation."""
+
+    async def test_disable_then_reset_restores_tools(self):
+        """After disable + reset within the same session, tools should reappear."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool(tags={"system"})
+        def my_tool() -> str:
+            return "hello"
+
+        @mcp.tool(tags={"env"})
+        async def enter_env(ctx: Context) -> str:
+            await ctx.disable_components(tags={"system"})
+            return "entered"
+
+        @mcp.tool(tags={"env"})
+        async def exit_env(ctx: Context) -> str:
+            await ctx.reset_visibility()
+            return "exited"
+
+        async with Client(mcp) as client:
+            # Tool visible initially
+            tools = await client.list_tools()
+            assert any(t.name == "my_tool" for t in tools)
+
+            # Disable it
+            await client.call_tool("enter_env", {})
+            tools = await client.list_tools()
+            assert not any(t.name == "my_tool" for t in tools)
+
+            # Reset — tool should come back
+            await client.call_tool("exit_env", {})
+            tools = await client.list_tools()
+            assert any(t.name == "my_tool" for t in tools), (
+                "Tool should be visible again after reset_visibility"
+            )
+
+    async def test_disable_reset_loop(self):
+        """Repeated disable/reset cycles should work every time (the exact bug from #3034)."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool(tags={"system"})
+        def create_project() -> str:
+            return "created"
+
+        @mcp.tool(tags={"env"})
+        async def enter_env(ctx: Context) -> str:
+            await ctx.disable_components(tags={"system"})
+            return "entered"
+
+        @mcp.tool(tags={"env"})
+        async def exit_env(ctx: Context) -> str:
+            await ctx.reset_visibility()
+            return "exited"
+
+        async with Client(mcp) as client:
+            for i in range(3):
+                # create_project should be visible
+                tools = await client.list_tools()
+                assert any(t.name == "create_project" for t in tools), (
+                    f"Iteration {i}: create_project should be visible before enter_env"
+                )
+
+                # Enter env — disables system tools
+                await client.call_tool("enter_env", {})
+                tools = await client.list_tools()
+                assert not any(t.name == "create_project" for t in tools), (
+                    f"Iteration {i}: create_project should be hidden after enter_env"
+                )
+
+                # Exit env — reset
+                await client.call_tool("exit_env", {})
+
+    async def test_session_disable_does_not_leak_to_concurrent_session(self):
+        """Disabling tools in one session must not affect a concurrent session."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool(tags={"system"})
+        def shared_tool() -> str:
+            return "shared"
+
+        @mcp.tool
+        async def disable_system(ctx: Context) -> str:
+            await ctx.disable_components(tags={"system"})
+            return "disabled"
+
+        session_b_sees_tool = False
+        ready = anyio.Event()
+        check_done = anyio.Event()
+
+        async def session_a():
+            async with Client(mcp) as client:
+                await client.call_tool("disable_system", {})
+                ready.set()
+                await check_done.wait()
+
+        async def session_b():
+            nonlocal session_b_sees_tool
+            await ready.wait()
+            async with Client(mcp) as client:
+                tools = await client.list_tools()
+                session_b_sees_tool = any(t.name == "shared_tool" for t in tools)
+                check_done.set()
+
+        async with anyio.create_task_group() as tg:
+            tg.start_soon(session_a)
+            tg.start_soon(session_b)
+
+        assert session_b_sees_tool is True, (
+            "Session B should still see shared_tool despite Session A disabling it"
+        )
+
+    async def test_session_disable_does_not_leak_to_sequential_session(self):
+        """Disabling tools in one session must not affect a later session."""
+        from fastmcp import Client
+
+        mcp = FastMCP("test")
+
+        @mcp.tool(tags={"system"})
+        def shared_tool() -> str:
+            return "shared"
+
+        @mcp.tool
+        async def disable_system(ctx: Context) -> str:
+            await ctx.disable_components(tags={"system"})
+            return "disabled"
+
+        # Session A disables the tool (no reset)
+        async with Client(mcp) as client_a:
+            await client_a.call_tool("disable_system", {})
+            tools = await client_a.list_tools()
+            assert not any(t.name == "shared_tool" for t in tools)
+
+        # Session B should see it fresh
+        async with Client(mcp) as client_b:
+            tools = await client_b.list_tools()
+            assert any(t.name == "shared_tool" for t in tools), (
+                "New session should see shared_tool regardless of previous session"
+            )
diff --git a/tests/server/test_streamable_http_no_redirect.py b/tests/server/test_streamable_http_no_redirect.py
new file mode 100644
index 0000000..cd40a28
--- /dev/null
+++ b/tests/server/test_streamable_http_no_redirect.py
@@ -0,0 +1,85 @@
+"""Test that streamable HTTP routes avoid 307 redirects."""
+
+import httpx
+import pytest
+from starlette.routing import Route
+
+from fastmcp import FastMCP
+
+
+@pytest.mark.parametrize(
+    "server_path",
+    ["/mcp", "/mcp/"],
+)
+def test_streamable_http_route_structure(server_path: str):
+    """Test that streamable HTTP routes use Route objects with correct paths."""
+    mcp = FastMCP("TestServer")
+
+    @mcp.tool
+    def greet(name: str) -> str:
+        return f"Hello, {name}!"
+
+    # Create HTTP app with specific path
+    app = mcp.http_app(transport="http", path=server_path)
+
+    # Find the streamable HTTP route
+    streamable_routes = [
+        r
+        for r in app.routes
+        if isinstance(r, Route) and hasattr(r, "path") and r.path == server_path
+    ]
+
+    # Verify route exists and uses Route (not Mount)
+    assert len(streamable_routes) == 1, (
+        f"Should have one streamable route for path {server_path}"
+    )
+    assert isinstance(streamable_routes[0], Route), "Should use Route, not Mount"
+    assert streamable_routes[0].path == server_path, (
+        f"Route path should match {server_path}"
+    )
+
+
+async def test_streamable_http_redirect_behavior():
+    """Test that non-matching paths get redirected correctly."""
+    mcp = FastMCP("TestServer")
+
+    @mcp.tool
+    def greet(name: str) -> str:
+        return f"Hello, {name}!"
+
+    # Create HTTP app with /mcp path (no trailing slash)
+    app = mcp.http_app(transport="http", path="/mcp")
+
+    # Test that /mcp/ gets redirected to /mcp
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        response = await client.get("/mcp/", follow_redirects=False)
+        assert response.status_code == 307
+        assert response.headers["location"] == "http://test/mcp"
+
+
+async def test_streamable_http_no_mount_routes():
+    """Test that streamable HTTP app creates Route objects, not Mount objects."""
+    mcp = FastMCP("TestServer")
+    app = mcp.http_app(transport="http")
+
+    # Should not find any Mount routes for the streamable HTTP path
+    from starlette.routing import Mount
+
+    mount_routes = [
+        r
+        for r in app.routes
+        if isinstance(r, Mount) and hasattr(r, "path") and r.path == "/mcp"
+    ]
+
+    assert len(mount_routes) == 0, "Should not have Mount routes for streamable HTTP"
+
+    # Should find Route objects instead
+    route_routes = [
+        r
+        for r in app.routes
+        if isinstance(r, Route) and hasattr(r, "path") and r.path == "/mcp"
+    ]
+
+    assert len(route_routes) == 1, "Should have exactly one Route for streamable HTTP"
diff --git a/tests/server/test_tool_annotations.py b/tests/server/test_tool_annotations.py
new file mode 100644
index 0000000..096fd45
--- /dev/null
+++ b/tests/server/test_tool_annotations.py
@@ -0,0 +1,255 @@
+from typing import Any
+
+from mcp_types import Tool as MCPTool
+from mcp_types import ToolAnnotations, ToolExecution
+
+from fastmcp import Client, FastMCP
+from fastmcp.tools.base import Tool
+from tests.conftest import make_server_request_context
+
+
+async def test_tool_annotations_in_tool_manager():
+    """Test that tool annotations are correctly stored in the tool manager."""
+    mcp = FastMCP("Test Server")
+
+    @mcp.tool(
+        annotations=ToolAnnotations(
+            title="Echo Tool",
+            read_only_hint=True,
+            open_world_hint=False,
+        )
+    )
+    def echo(message: str) -> str:
+        """Echo back the message provided."""
+        return message
+
+    # Check internal tool objects directly
+    tools = await mcp.list_tools()
+    assert len(tools) == 1
+    assert tools[0].annotations is not None
+    assert tools[0].annotations.title == "Echo Tool"
+    assert tools[0].annotations.read_only_hint is True
+    assert tools[0].annotations.open_world_hint is False
+
+
+async def test_tool_annotations_in_mcp_protocol():
+    """Test that tool annotations are correctly propagated to MCP tools list."""
+    mcp = FastMCP("Test Server")
+
+    @mcp.tool(
+        annotations=ToolAnnotations(
+            title="Echo Tool",
+            read_only_hint=True,
+            open_world_hint=False,
+        )
+    )
+    def echo(message: str) -> str:
+        """Echo back the message provided."""
+        return message
+
+    # Check via MCP protocol
+    result = await mcp._on_list_tools(make_server_request_context(), None)
+    assert len(result.tools) == 1
+    assert result.tools[0].annotations is not None
+    assert result.tools[0].annotations.title == "Echo Tool"
+    assert result.tools[0].annotations.read_only_hint is True
+    assert result.tools[0].annotations.open_world_hint is False
+
+
+async def test_tool_annotations_in_client_api():
+    """Test that tool annotations are correctly accessible via client API."""
+    mcp = FastMCP("Test Server")
+
+    @mcp.tool(
+        annotations=ToolAnnotations(
+            title="Echo Tool",
+            read_only_hint=True,
+            open_world_hint=False,
+        )
+    )
+    def echo(message: str) -> str:
+        """Echo back the message provided."""
+        return message
+
+    # Check via client API
+    async with Client(mcp) as client:
+        tools_result = await client.list_tools()
+        assert len(tools_result) == 1
+        assert tools_result[0].name == "echo"
+        assert tools_result[0].annotations is not None
+        assert tools_result[0].annotations.title == "Echo Tool"
+        assert tools_result[0].annotations.read_only_hint is True
+        assert tools_result[0].annotations.open_world_hint is False
+
+
+async def test_provide_tool_annotations_as_dict_to_decorator():
+    """Test that tool annotations are correctly accessible via client API."""
+    mcp = FastMCP("Test Server")
+
+    @mcp.tool(
+        annotations={
+            "title": "Echo Tool",
+            "readOnlyHint": True,
+            "openWorldHint": False,
+        }
+    )
+    def echo(message: str) -> str:
+        """Echo back the message provided."""
+        return message
+
+    # Check via client API
+    async with Client(mcp) as client:
+        tools_result = await client.list_tools()
+        assert len(tools_result) == 1
+        assert tools_result[0].name == "echo"
+        assert tools_result[0].annotations is not None
+        assert tools_result[0].annotations.title == "Echo Tool"
+        assert tools_result[0].annotations.read_only_hint is True
+        assert tools_result[0].annotations.open_world_hint is False
+
+
+async def test_direct_tool_annotations_in_tool_manager():
+    """Test direct ToolAnnotations object is correctly stored in tool manager."""
+    mcp = FastMCP("Test Server")
+
+    annotations = ToolAnnotations(
+        title="Direct Tool",
+        read_only_hint=False,
+        destructive_hint=True,
+        idempotent_hint=False,
+        open_world_hint=True,
+    )
+
+    @mcp.tool(annotations=annotations)
+    def modify(data: dict[str, Any]) -> dict[str, Any]:
+        """Modify the data provided."""
+        return {"modified": True, **data}
+
+    # Check internal tool objects directly
+    tools = await mcp.list_tools()
+    assert len(tools) == 1
+    assert tools[0].annotations is not None
+    assert tools[0].annotations.title == "Direct Tool"
+    assert tools[0].annotations.read_only_hint is False
+    assert tools[0].annotations.destructive_hint is True
+    assert tools[0].annotations.idempotent_hint is False
+    assert tools[0].annotations.open_world_hint is True
+
+
+async def test_direct_tool_annotations_in_client_api():
+    """Test direct ToolAnnotations object is correctly accessible via client API."""
+    mcp = FastMCP("Test Server")
+
+    annotations = ToolAnnotations(
+        title="Direct Tool",
+        read_only_hint=False,
+        destructive_hint=True,
+        idempotent_hint=False,
+        open_world_hint=True,
+    )
+
+    @mcp.tool(annotations=annotations)
+    def modify(data: dict[str, Any]) -> dict[str, Any]:
+        """Modify the data provided."""
+        return {"modified": True, **data}
+
+    # Check via client API
+    async with Client(mcp) as client:
+        tools_result = await client.list_tools()
+        assert len(tools_result) == 1
+        assert tools_result[0].name == "modify"
+        assert tools_result[0].annotations is not None
+        assert tools_result[0].annotations.title == "Direct Tool"
+        assert tools_result[0].annotations.read_only_hint is False
+        assert tools_result[0].annotations.destructive_hint is True
+
+
+async def test_add_tool_method_annotations():
+    """Test that tool annotations work with add_tool method."""
+    mcp = FastMCP("Test Server")
+
+    def create_item(name: str, value: int) -> dict[str, Any]:
+        """Create a new item."""
+        return {"name": name, "value": value}
+
+    tool = Tool.from_function(
+        create_item,
+        name="create_item",
+        annotations=ToolAnnotations(
+            title="Create Item",
+            read_only_hint=False,
+            destructive_hint=False,
+        ),
+    )
+
+    mcp.add_tool(tool)
+
+    # Check internal tool objects directly
+    tools = await mcp.list_tools()
+    assert len(tools) == 1
+    assert tools[0].annotations is not None
+    assert tools[0].annotations.title == "Create Item"
+    assert tools[0].annotations.read_only_hint is False
+    assert tools[0].annotations.destructive_hint is False
+
+
+async def test_tool_functionality_with_annotations():
+    """Test that tool functionality is preserved when using annotations."""
+    mcp = FastMCP("Test Server")
+
+    def create_item(name: str, value: int) -> dict[str, Any]:
+        """Create a new item."""
+        return {"name": name, "value": value}
+
+    tool = Tool.from_function(
+        create_item,
+        name="create_item",
+        annotations=ToolAnnotations(
+            title="Create Item",
+            read_only_hint=False,
+            destructive_hint=False,
+        ),
+    )
+    mcp.add_tool(tool)
+
+    # Use the tool to verify functionality is preserved
+    async with Client(mcp) as client:
+        result = await client.call_tool(
+            "create_item", {"name": "test_item", "value": 42}
+        )
+        assert result.data == {"name": "test_item", "value": 42}
+
+
+async def test_task_execution_auto_populated_for_task_enabled_tool():
+    """Test that execution.task_support is automatically set when tool has task=True."""
+    mcp = FastMCP("Test Server")
+
+    @mcp.tool(task=True)
+    async def background_tool(data: str) -> str:
+        """A tool that runs in background."""
+        return f"Processed: {data}"
+
+    async with Client(mcp) as client:
+        tools_result = await client.list_tools()
+        assert len(tools_result) == 1
+        assert tools_result[0].name == "background_tool"
+        assert isinstance(tools_result[0], MCPTool)
+        assert isinstance(tools_result[0].execution, ToolExecution)
+        assert tools_result[0].execution.task_support == "optional"
+
+
+async def test_task_execution_omitted_for_task_disabled_tool():
+    """Test that execution is not set when tool has task=False or default."""
+    mcp = FastMCP("Test Server")
+
+    @mcp.tool(task=False)
+    def sync_tool(data: str) -> str:
+        """A synchronous tool."""
+        return f"Processed: {data}"
+
+    async with Client(mcp) as client:
+        tools_result = await client.list_tools()
+        assert len(tools_result) == 1
+        assert tools_result[0].name == "sync_tool"
+        # execution should be None for non-task tools (default is False, omitted)
+        assert tools_result[0].execution is None
diff --git a/tests/server/test_tool_transformation.py b/tests/server/test_tool_transformation.py
new file mode 100644
index 0000000..1379e54
--- /dev/null
+++ b/tests/server/test_tool_transformation.py
@@ -0,0 +1,285 @@
+import httpx
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.transforms import ToolTransform
+from fastmcp.tools.tool_transform import (
+    ArgTransformConfig,
+    ToolTransformConfig,
+)
+
+
+async def test_tool_transformation_via_layer():
+    """Test that tool transformations work via add_transform(ToolTransform(...))."""
+    mcp = FastMCP("Test Server")
+
+    @mcp.tool()
+    def echo(message: str) -> str:
+        """Echo back the message provided."""
+        return message
+
+    mcp.add_transform(
+        ToolTransform({"echo": ToolTransformConfig(name="echo_transformed")})
+    )
+
+    tools = await mcp.list_tools()
+    assert len(tools) == 1
+    assert any(t.name == "echo_transformed" for t in tools)
+    tool = next(t for t in tools if t.name == "echo_transformed")
+    assert tool.name == "echo_transformed"
+
+
+async def test_transformed_tool_filtering():
+    """Test that tool transformations add tags that affect filtering."""
+    mcp = FastMCP("Test Server")
+
+    @mcp.tool()
+    def echo(message: str) -> str:
+        """Echo back the message provided."""
+        return message
+
+    # Add transformation that adds tags
+    mcp.add_transform(
+        ToolTransform(
+            {
+                "echo": ToolTransformConfig(
+                    name="echo_transformed", tags={"enabled_tools"}
+                )
+            }
+        )
+    )
+    # Enable only tools with the enabled_tools tag
+    mcp.enable(tags={"enabled_tools"}, only=True)
+
+    tools = await mcp.list_tools()
+    # With transformation applied, the tool now has the enabled_tools tag
+    assert len(tools) == 1
+
+
+async def test_transformed_tool_structured_output_without_annotation():
+    """Test that transformed tools generate structured output when original tool has no return annotation.
+
+    Ref: https://github.com/PrefectHQ/fastmcp/issues/1369
+    """
+    from fastmcp.client import Client
+
+    mcp = FastMCP("Test Server")
+
+    @mcp.tool()
+    def tool_without_annotation(message: str):  # No return annotation
+        """A tool without return type annotation."""
+        return {"result": "processed", "input": message}
+
+    mcp.add_transform(
+        ToolTransform(
+            {"tool_without_annotation": ToolTransformConfig(name="transformed_tool")}
+        )
+    )
+
+    # Test with client to verify structured output is populated
+    async with Client(mcp) as client:
+        result = await client.call_tool("transformed_tool", {"message": "test"})
+
+        # Structured output should be populated even without return annotation
+        assert result.data is not None
+        assert result.data == {"result": "processed", "input": "test"}
+
+
+async def test_layer_based_transforms():
+    """Test that ToolTransform layer works after tool registration."""
+    mcp = FastMCP("Test Server")
+
+    @mcp.tool()
+    def my_tool() -> str:
+        return "hello"
+
+    # Add transform after tool registration
+    mcp.add_transform(
+        ToolTransform({"my_tool": ToolTransformConfig(name="renamed_tool")})
+    )
+
+    tools = await mcp.list_tools()
+    assert len(tools) == 1
+    assert tools[0].name == "renamed_tool"
+
+
+async def test_server_level_transforms_apply_to_mounted_servers():
+    """Test that server-level transforms apply to tools from mounted servers."""
+    main = FastMCP("Main")
+    sub = FastMCP("Sub")
+
+    @sub.tool()
+    def sub_tool() -> str:
+        return "hello from sub"
+
+    main.mount(sub)
+
+    # Add transform for the mounted tool at server level
+    main.add_transform(
+        ToolTransform({"sub_tool": ToolTransformConfig(name="renamed_sub_tool")})
+    )
+
+    tools = await main.list_tools()
+    tool_names = [t.name for t in tools]
+
+    assert "renamed_sub_tool" in tool_names
+    assert "sub_tool" not in tool_names
+
+
+async def test_tool_transform_config_enabled_false_hides_tool():
+    """Test that ToolTransformConfig with enabled=False hides the tool from list_tools."""
+    mcp = FastMCP("Test Server")
+
+    @mcp.tool()
+    def visible_tool() -> str:
+        return "visible"
+
+    @mcp.tool()
+    def hidden_tool() -> str:
+        return "hidden"
+
+    # Disable one tool via transformation
+    mcp.add_transform(
+        ToolTransform({"hidden_tool": ToolTransformConfig(enabled=False)})
+    )
+
+    tools = await mcp.list_tools()
+    tool_names = [t.name for t in tools]
+
+    assert "visible_tool" in tool_names
+    assert "hidden_tool" not in tool_names
+
+
+async def test_tool_transform_config_enabled_false_with_rename():
+    """Test that enabled=False works together with other transformations like rename."""
+    mcp = FastMCP("Test Server")
+
+    @mcp.tool()
+    def my_tool() -> str:
+        return "result"
+
+    # Rename AND disable
+    mcp.add_transform(
+        ToolTransform(
+            {"my_tool": ToolTransformConfig(name="renamed_and_disabled", enabled=False)}
+        )
+    )
+
+    tools = await mcp.list_tools()
+    tool_names = [t.name for t in tools]
+
+    # Tool should be hidden regardless of rename
+    assert "my_tool" not in tool_names
+    assert "renamed_and_disabled" not in tool_names
+
+
+async def test_tool_transform_config_enabled_true_keeps_tool_visible():
+    """Test that ToolTransformConfig with enabled=True (explicit) keeps the tool visible."""
+    mcp = FastMCP("Test Server")
+
+    @mcp.tool()
+    def my_tool() -> str:
+        return "result"
+
+    # Explicitly set enabled=True (should be same as default)
+    mcp.add_transform(ToolTransform({"my_tool": ToolTransformConfig(enabled=True)}))
+
+    tools = await mcp.list_tools()
+    tool_names = [t.name for t in tools]
+
+    assert "my_tool" in tool_names
+
+
+async def test_tool_transform_config_enabled_true_overrides_earlier_disable():
+    """Test that ToolTransformConfig with enabled=True can re-enable a previously disabled tool."""
+    mcp = FastMCP("Test Server")
+
+    @mcp.tool()
+    def my_tool() -> str:
+        return "result"
+
+    # Disable the tool first
+    mcp.disable(names={"my_tool"})
+
+    # Verify tool is initially hidden
+    tools = await mcp.list_tools()
+    assert "my_tool" not in [t.name for t in tools]
+
+    # Re-enable via transformation (later transforms win)
+    mcp.add_transform(ToolTransform({"my_tool": ToolTransformConfig(enabled=True)}))
+
+    tools = await mcp.list_tools()
+    tool_names = [t.name for t in tools]
+
+    # Tool should now be visible
+    assert "my_tool" in tool_names
+
+
+async def test_openapi_path_params_not_duplicated_in_description():
+    """Path parameter details should live in inputSchema, not the description.
+
+    Regression test for https://github.com/PrefectHQ/fastmcp/issues/3130 — hiding
+    a path param via ToolTransform left stale references in the description
+    because the description was generated before transforms ran. The fix is to
+    keep parameter docs in inputSchema only, where transforms can control them.
+    """
+    spec = {
+        "openapi": "3.1.0",
+        "info": {"title": "Test", "version": "0.1.0"},
+        "paths": {
+            "/api/{version}/users/{user_id}": {
+                "get": {
+                    "operationId": "my_endpoint",
+                    "summary": "My endpoint",
+                    "parameters": [
+                        {
+                            "name": "version",
+                            "in": "path",
+                            "required": True,
+                            "description": "API version",
+                            "schema": {"type": "string"},
+                        },
+                        {
+                            "name": "user_id",
+                            "in": "path",
+                            "required": True,
+                            "description": "The user ID",
+                            "schema": {"type": "string"},
+                        },
+                    ],
+                    "responses": {"200": {"description": "OK"}},
+                },
+            },
+        },
+    }
+
+    async with httpx.AsyncClient(base_url="http://localhost") as http_client:
+        mcp = FastMCP.from_openapi(openapi_spec=spec, client=http_client)
+
+        # Hide one of the two path params
+        mcp.add_transform(
+            ToolTransform(
+                {
+                    "my_endpoint": ToolTransformConfig(
+                        arguments={
+                            "version": ArgTransformConfig(hide=True, default="v1"),
+                        }
+                    )
+                }
+            )
+        )
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            tool = tools[0]
+
+            # Description should be the summary only — no parameter details
+            assert tool.description == "My endpoint"
+
+            # Hidden param gone from schema, visible param still present
+            assert "version" not in tool.input_schema.get("properties", {})
+            assert "user_id" in tool.input_schema["properties"]
+            assert (
+                tool.input_schema["properties"]["user_id"]["description"]
+                == "The user ID"
+            )
diff --git a/tests/server/test_transport.py b/tests/server/test_transport.py
new file mode 100644
index 0000000..8f18861
--- /dev/null
+++ b/tests/server/test_transport.py
@@ -0,0 +1,50 @@
+import pytest
+
+from fastmcp.server.mixins.transport import (
+    _format_host_for_url,
+    _resolve_allowed_hosts_for_run,
+)
+
+
+@pytest.mark.parametrize(
+    "host, expected",
+    [
+        ("127.0.0.1", "127.0.0.1"),
+        ("localhost", "localhost"),
+        ("0.0.0.0", "0.0.0.0"),
+        ("::1", "[::1]"),
+        ("::", "[::]"),
+        ("fe80::1", "[fe80::1]"),
+        ("[::1]", "[::1]"),
+    ],
+)
+def test_format_host_for_url(host: str, expected: str):
+    """IPv6 hosts are bracketed for use in a URL; everything else is unchanged."""
+    assert _format_host_for_url(host) == expected
+
+
+def test_resolve_allowed_hosts_for_run_merges_configured_hosts_with_loopback_host():
+    assert _resolve_allowed_hosts_for_run(
+        host="127.0.0.1",
+        host_origin_protection="auto",
+        allowed_hosts=None,
+        configured_allowed_hosts=["mcp.example.com"],
+    ) == ["mcp.example.com", "127.0.0.1"]
+
+
+def test_resolve_allowed_hosts_for_run_preserves_configured_hosts_when_disabled():
+    assert _resolve_allowed_hosts_for_run(
+        host="127.0.0.1",
+        host_origin_protection=False,
+        allowed_hosts=None,
+        configured_allowed_hosts=["mcp.example.com"],
+    ) == ["mcp.example.com"]
+
+
+def test_resolve_allowed_hosts_for_run_preserves_explicit_hosts():
+    assert _resolve_allowed_hosts_for_run(
+        host="127.0.0.1",
+        host_origin_protection="auto",
+        allowed_hosts=["mcp.example.com"],
+        configured_allowed_hosts=["settings.example.com"],
+    ) == ["mcp.example.com"]
diff --git a/tests/server/transforms/test_catalog.py b/tests/server/transforms/test_catalog.py
new file mode 100644
index 0000000..6d5f982
--- /dev/null
+++ b/tests/server/transforms/test_catalog.py
@@ -0,0 +1,258 @@
+"""Tests for CatalogTransform base class."""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Sequence
+
+from mcp_types import TextContent
+
+from fastmcp import FastMCP
+from fastmcp.server.context import Context
+from fastmcp.server.transforms import GetToolNext
+from fastmcp.server.transforms.catalog import CatalogTransform
+from fastmcp.server.transforms.version_filter import VersionFilter
+from fastmcp.tools.base import Tool
+from fastmcp.utilities.versions import VersionSpec
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_versioned_tool(name: str, version: str) -> Tool:
+    """Create a tool with a specific version for testing."""
+
+    async def _fn() -> str:
+        return f"{name}@{version}"
+
+    return Tool.from_function(fn=_fn, name=name, version=version)
+
+
+class CatalogReader(CatalogTransform):
+    """Minimal CatalogTransform that exposes get_tool_catalog via a tool.
+
+    After calling the ``read_catalog`` tool, the full catalog is available
+    on ``self.last_catalog`` for assertions beyond tool names.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.last_catalog: Sequence[Tool] = []
+
+    async def transform_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        return [self._make_reader_tool()]
+
+    async def get_tool(
+        self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
+    ) -> Tool | None:
+        if name == "read_catalog":
+            return self._make_reader_tool()
+        return await call_next(name, version=version)
+
+    def _make_reader_tool(self) -> Tool:
+        transform = self
+
+        async def read_catalog(ctx: Context = None) -> list[str]:  # type: ignore[assignment]  # ty:ignore[invalid-parameter-default]
+            """Return names of tools visible in the catalog."""
+            transform.last_catalog = await transform.get_tool_catalog(ctx)
+            return [t.name for t in transform.last_catalog]
+
+        return Tool.from_function(fn=read_catalog, name="read_catalog")
+
+
+class ReplacingTransform(CatalogTransform):
+    """Minimal subclass that replaces tools with a synthetic tool.
+
+    Uses ``get_tool_catalog()`` to read the real catalog inside the
+    synthetic tool's handler, verifying that the bypass mechanism works.
+    """
+
+    async def transform_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        return [self._make_synthetic_tool()]
+
+    async def get_tool(
+        self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
+    ) -> Tool | None:
+        if name == "count_tools":
+            return self._make_synthetic_tool()
+        return await call_next(name, version=version)
+
+    def _make_synthetic_tool(self) -> Tool:
+        transform = self
+
+        async def count_tools(ctx: Context = None) -> int:  # type: ignore[assignment]  # ty:ignore[invalid-parameter-default]
+            """Return the number of real tools in the catalog."""
+            catalog = await transform.get_tool_catalog(ctx)
+            return len(catalog)
+
+        return Tool.from_function(fn=count_tools, name="count_tools")
+
+
+class TestCatalogTransformBypass:
+    async def test_list_tools_replaced_by_subclass(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        @mcp.tool
+        def multiply(x: float, y: float) -> float:
+            return x * y
+
+        mcp.add_transform(ReplacingTransform())
+        tools = await mcp.list_tools()
+        names = {t.name for t in tools}
+        assert names == {"count_tools"}
+
+    async def test_get_tool_catalog_returns_real_tools(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        @mcp.tool
+        def multiply(x: float, y: float) -> float:
+            return x * y
+
+        mcp.add_transform(ReplacingTransform())
+        result = await mcp.call_tool("count_tools", {})
+        assert any("2" in c.text for c in result.content if isinstance(c, TextContent))
+
+    async def test_multiple_instances_have_independent_bypass(self):
+        """Each CatalogTransform instance has its own bypass ContextVar."""
+        t1 = ReplacingTransform()
+        t2 = ReplacingTransform()
+        assert t1._instance_id != t2._instance_id
+        assert t1._bypass is not t2._bypass
+
+
+class TestCatalogDeduplication:
+    """get_tool_catalog() deduplicates versioned tools, keeping only the highest."""
+
+    async def test_returns_highest_version_only(self):
+        mcp = FastMCP("test")
+        mcp.add_tool(_make_versioned_tool("greet", "1"))
+        mcp.add_tool(_make_versioned_tool("greet", "2"))
+        mcp.add_tool(_make_versioned_tool("greet", "3"))
+
+        reader = CatalogReader()
+        mcp.add_transform(reader)
+
+        result = await mcp.call_tool("read_catalog", {})
+        names = _extract_result(result)
+        assert names == ["greet"]
+
+    async def test_version_metadata_injected(self):
+        """Highest-version tool has meta.fastmcp.versions listing all available."""
+        mcp = FastMCP("test")
+        mcp.add_tool(_make_versioned_tool("greet", "1"))
+        mcp.add_tool(_make_versioned_tool("greet", "3"))
+
+        reader = CatalogReader()
+        mcp.add_transform(reader)
+
+        await mcp.call_tool("read_catalog", {})
+        assert len(reader.last_catalog) == 1
+        tool = reader.last_catalog[0]
+        assert tool.name == "greet"
+        assert tool.version == "3"
+        assert tool.meta is not None
+        versions = tool.meta["fastmcp"]["versions"]
+        assert versions == ["3", "1"]
+
+    async def test_mixed_versioned_and_unversioned(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def standalone() -> str:
+            return "hi"
+
+        mcp.add_tool(_make_versioned_tool("greet", "1"))
+        mcp.add_tool(_make_versioned_tool("greet", "2"))
+
+        reader = CatalogReader()
+        mcp.add_transform(reader)
+
+        result = await mcp.call_tool("read_catalog", {})
+        names = sorted(_extract_result(result))
+        assert names == ["greet", "standalone"]
+
+    async def test_version_filter_applied_before_catalog(self):
+        """A VersionFilter added before the CatalogTransform restricts what the catalog sees."""
+        mcp = FastMCP("test")
+        mcp.add_tool(_make_versioned_tool("greet", "1"))
+        mcp.add_tool(_make_versioned_tool("greet", "2"))
+        mcp.add_tool(_make_versioned_tool("greet", "3"))
+
+        # Filter keeps only versions < 3 — so v1 and v2 survive, v3 is excluded.
+        mcp.add_transform(VersionFilter(version_lt="3"))
+
+        reader = CatalogReader()
+        mcp.add_transform(reader)
+
+        await mcp.call_tool("read_catalog", {})
+        assert len(reader.last_catalog) == 1
+        tool = reader.last_catalog[0]
+        assert tool.name == "greet"
+        assert tool.version == "2"
+
+
+class TestCatalogVisibility:
+    """get_tool_catalog() respects visibility (disabled tools are excluded)."""
+
+    async def test_disabled_tool_excluded(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def public() -> str:
+            return "visible"
+
+        @mcp.tool
+        def secret() -> str:
+            return "hidden"
+
+        mcp.disable(names={"secret"}, components={"tool"})
+        reader = CatalogReader()
+        mcp.add_transform(reader)
+
+        result = await mcp.call_tool("read_catalog", {})
+        names = _extract_result(result)
+        assert names == ["public"]
+
+
+class TestCatalogAuth:
+    """get_tool_catalog() respects tool-level auth filtering."""
+
+    async def test_auth_rejected_tool_excluded(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def public() -> str:
+            return "visible"
+
+        @mcp.tool(auth=lambda _ctx: False)
+        def protected() -> str:
+            return "hidden"
+
+        reader = CatalogReader()
+        mcp.add_transform(reader)
+
+        result = await mcp.call_tool("read_catalog", {})
+        names = _extract_result(result)
+        assert names == ["public"]
+
+
+# ---------------------------------------------------------------------------
+# Test helpers
+# ---------------------------------------------------------------------------
+
+
+def _extract_result(result: object) -> list[str]:
+    """Extract the list of names from a call_tool ToolResult."""
+    for c in result.content:  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+        if isinstance(c, TextContent):
+            return ast.literal_eval(c.text)
+    raise AssertionError("No text content found")
diff --git a/tests/server/transforms/test_prompts_as_tools.py b/tests/server/transforms/test_prompts_as_tools.py
new file mode 100644
index 0000000..1583d3b
--- /dev/null
+++ b/tests/server/transforms/test_prompts_as_tools.py
@@ -0,0 +1,210 @@
+"""Tests for PromptsAsTools transform."""
+
+import json
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.transforms import PromptsAsTools
+
+
+class TestPromptsAsToolsBasic:
+    """Test basic PromptsAsTools functionality."""
+
+    async def test_adds_list_prompts_tool(self):
+        """Transform adds list_prompts tool."""
+        mcp = FastMCP("Test")
+        mcp.add_transform(PromptsAsTools(mcp))
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            tool_names = {t.name for t in tools}
+            assert "list_prompts" in tool_names
+
+    async def test_adds_get_prompt_tool(self):
+        """Transform adds get_prompt tool."""
+        mcp = FastMCP("Test")
+        mcp.add_transform(PromptsAsTools(mcp))
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            tool_names = {t.name for t in tools}
+            assert "get_prompt" in tool_names
+
+    async def test_preserves_existing_tools(self):
+        """Transform preserves existing tools."""
+        mcp = FastMCP("Test")
+
+        @mcp.tool
+        def my_tool() -> str:
+            return "result"
+
+        mcp.add_transform(PromptsAsTools(mcp))
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            tool_names = {t.name for t in tools}
+            assert "my_tool" in tool_names
+            assert "list_prompts" in tool_names
+            assert "get_prompt" in tool_names
+
+
+class TestListPromptsTool:
+    """Test the list_prompts tool."""
+
+    async def test_lists_prompts(self):
+        """list_prompts returns prompt metadata."""
+        mcp = FastMCP("Test")
+
+        @mcp.prompt
+        def analyze_code() -> str:
+            """Analyze code for issues."""
+            return "Analyze this code"
+
+        mcp.add_transform(PromptsAsTools(mcp))
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("list_prompts", {})
+            prompts = json.loads(result.data)
+
+            assert len(prompts) == 1
+            assert prompts[0]["name"] == "analyze_code"
+            assert prompts[0]["description"] == "Analyze code for issues."
+
+    async def test_lists_prompt_with_arguments(self):
+        """list_prompts includes argument metadata."""
+        mcp = FastMCP("Test")
+
+        @mcp.prompt
+        def analyze_code(code: str, language: str = "python") -> str:
+            """Analyze code for issues."""
+            return f"Analyze this {language} code:\n{code}"
+
+        mcp.add_transform(PromptsAsTools(mcp))
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("list_prompts", {})
+            prompts = json.loads(result.data)
+
+            assert len(prompts) == 1
+            args = prompts[0]["arguments"]
+            assert len(args) == 2
+
+            # Check required arg
+            code_arg = next(a for a in args if a["name"] == "code")
+            assert code_arg["required"] is True
+
+            # Check optional arg
+            lang_arg = next(a for a in args if a["name"] == "language")
+            assert lang_arg["required"] is False
+
+    async def test_empty_when_no_prompts(self):
+        """list_prompts returns empty list when no prompts exist."""
+        mcp = FastMCP("Test")
+        mcp.add_transform(PromptsAsTools(mcp))
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("list_prompts", {})
+            assert json.loads(result.data) == []
+
+
+class TestGetPromptTool:
+    """Test the get_prompt tool."""
+
+    async def test_gets_prompt_without_arguments(self):
+        """get_prompt gets a prompt with no arguments."""
+        mcp = FastMCP("Test")
+
+        @mcp.prompt
+        def simple_prompt() -> str:
+            """A simple prompt."""
+            return "Hello, world!"
+
+        mcp.add_transform(PromptsAsTools(mcp))
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("get_prompt", {"name": "simple_prompt"})
+            response = json.loads(result.data)
+
+            assert "messages" in response
+            assert len(response["messages"]) == 1
+            assert response["messages"][0]["role"] == "user"
+            assert "Hello, world!" in response["messages"][0]["content"]
+
+    async def test_gets_prompt_with_arguments(self):
+        """get_prompt gets a prompt with arguments."""
+        mcp = FastMCP("Test")
+
+        @mcp.prompt
+        def analyze_code(code: str, language: str = "python") -> str:
+            """Analyze code."""
+            return f"Analyze this {language} code:\n{code}"
+
+        mcp.add_transform(PromptsAsTools(mcp))
+
+        async with Client(mcp) as client:
+            result = await client.call_tool(
+                "get_prompt",
+                {
+                    "name": "analyze_code",
+                    "arguments": {"code": "x = 1", "language": "python"},
+                },
+            )
+            response = json.loads(result.data)
+
+            assert "messages" in response
+            content = response["messages"][0]["content"]
+            assert "python" in content
+            assert "x = 1" in content
+
+    async def test_error_on_unknown_prompt(self):
+        """get_prompt raises error for unknown prompt name."""
+        from fastmcp.exceptions import ToolError
+
+        mcp = FastMCP("Test")
+        mcp.add_transform(PromptsAsTools(mcp))
+
+        async with Client(mcp) as client:
+            with pytest.raises(ToolError, match="Unknown prompt"):
+                await client.call_tool("get_prompt", {"name": "unknown_prompt"})
+
+
+class TestPromptsAsToolsWithNamespace:
+    """Test PromptsAsTools combined with other transforms."""
+
+    async def test_works_with_namespace_on_provider(self):
+        """PromptsAsTools works when provider has Namespace transform."""
+        from fastmcp.server.providers import FastMCPProvider
+        from fastmcp.server.transforms import Namespace
+
+        sub = FastMCP("Sub")
+
+        @sub.prompt
+        def my_prompt() -> str:
+            """A prompt."""
+            return "Hello"
+
+        main = FastMCP("Main")
+        provider = FastMCPProvider(sub)
+        provider.add_transform(Namespace("sub"))
+        main.add_provider(provider)
+        main.add_transform(PromptsAsTools(main))
+
+        async with Client(main) as client:
+            result = await client.call_tool("list_prompts", {})
+            prompts = json.loads(result.data)
+
+            # Prompt should have namespaced name
+            assert len(prompts) == 1
+            assert prompts[0]["name"] == "sub_my_prompt"
+
+
+class TestPromptsAsToolsRepr:
+    """Test PromptsAsTools repr."""
+
+    def test_repr(self):
+        """Transform has useful repr."""
+        mcp = FastMCP("Test")
+        transform = PromptsAsTools(mcp)
+        assert "PromptsAsTools" in repr(transform)
diff --git a/tests/server/transforms/test_resources_as_tools.py b/tests/server/transforms/test_resources_as_tools.py
new file mode 100644
index 0000000..620a87c
--- /dev/null
+++ b/tests/server/transforms/test_resources_as_tools.py
@@ -0,0 +1,358 @@
+"""Tests for ResourcesAsTools transform."""
+
+import base64
+import json
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.exceptions import ToolError
+from fastmcp.server.auth import AuthContext
+from fastmcp.server.transforms import ResourcesAsTools
+
+
+class TestResourcesAsToolsBasic:
+    """Test basic ResourcesAsTools functionality."""
+
+    async def test_adds_list_resources_tool(self):
+        """Transform adds list_resources tool."""
+        mcp = FastMCP("Test")
+        mcp.add_transform(ResourcesAsTools(mcp))
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            tool_names = {t.name for t in tools}
+            assert "list_resources" in tool_names
+
+    async def test_adds_read_resource_tool(self):
+        """Transform adds read_resource tool."""
+        mcp = FastMCP("Test")
+        mcp.add_transform(ResourcesAsTools(mcp))
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            tool_names = {t.name for t in tools}
+            assert "read_resource" in tool_names
+
+    async def test_preserves_existing_tools(self):
+        """Transform preserves existing tools."""
+        mcp = FastMCP("Test")
+
+        @mcp.tool
+        def my_tool() -> str:
+            return "result"
+
+        mcp.add_transform(ResourcesAsTools(mcp))
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            tool_names = {t.name for t in tools}
+            assert "my_tool" in tool_names
+            assert "list_resources" in tool_names
+            assert "read_resource" in tool_names
+
+
+class TestListResourcesTool:
+    """Test the list_resources tool."""
+
+    async def test_lists_static_resources(self):
+        """list_resources returns static resources with uri."""
+        mcp = FastMCP("Test")
+
+        @mcp.resource("config://app")
+        def app_config() -> str:
+            return "config data"
+
+        mcp.add_transform(ResourcesAsTools(mcp))
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("list_resources", {})
+            resources = json.loads(result.data)
+
+            assert len(resources) == 1
+            assert resources[0]["uri"] == "config://app"
+            assert resources[0]["name"] == "app_config"
+
+    async def test_lists_resource_templates(self):
+        """list_resources returns templates with uri_template."""
+        mcp = FastMCP("Test")
+
+        @mcp.resource("file://{path}")
+        def read_file(path: str) -> str:
+            return f"content of {path}"
+
+        mcp.add_transform(ResourcesAsTools(mcp))
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("list_resources", {})
+            resources = json.loads(result.data)
+
+            assert len(resources) == 1
+            assert resources[0]["uri_template"] == "file://{path}"
+            assert "uri" not in resources[0]
+
+    async def test_lists_both_resources_and_templates(self):
+        """list_resources returns both static and templated resources."""
+        mcp = FastMCP("Test")
+
+        @mcp.resource("config://app")
+        def app_config() -> str:
+            return "config"
+
+        @mcp.resource("file://{path}")
+        def read_file(path: str) -> str:
+            return f"content of {path}"
+
+        mcp.add_transform(ResourcesAsTools(mcp))
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("list_resources", {})
+            resources = json.loads(result.data)
+
+            assert len(resources) == 2
+            # One has uri, one has uri_template
+            uris = [r.get("uri") for r in resources if r.get("uri")]
+            templates = [
+                r.get("uri_template") for r in resources if r.get("uri_template")
+            ]
+            assert uris == ["config://app"]
+            assert templates == ["file://{path}"]
+
+    async def test_empty_when_no_resources(self):
+        """list_resources returns empty list when no resources exist."""
+        mcp = FastMCP("Test")
+        mcp.add_transform(ResourcesAsTools(mcp))
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("list_resources", {})
+            assert json.loads(result.data) == []
+
+
+class TestReadResourceTool:
+    """Test the read_resource tool."""
+
+    async def test_reads_static_resource(self):
+        """read_resource reads a static resource by URI."""
+        mcp = FastMCP("Test")
+
+        @mcp.resource("config://app")
+        def app_config() -> str:
+            return "my config data"
+
+        mcp.add_transform(ResourcesAsTools(mcp))
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("read_resource", {"uri": "config://app"})
+            assert result.data == "my config data"
+
+    async def test_reads_templated_resource(self):
+        """read_resource reads a templated resource with parameters."""
+        mcp = FastMCP("Test")
+
+        @mcp.resource("user://{user_id}/profile")
+        def user_profile(user_id: str) -> str:
+            return f"Profile for user {user_id}"
+
+        mcp.add_transform(ResourcesAsTools(mcp))
+
+        async with Client(mcp) as client:
+            result = await client.call_tool(
+                "read_resource", {"uri": "user://123/profile"}
+            )
+            assert result.data == "Profile for user 123"
+
+    async def test_error_on_unknown_resource(self):
+        """read_resource raises error for unknown URI."""
+        from fastmcp.exceptions import ToolError
+
+        mcp = FastMCP("Test")
+        mcp.add_transform(ResourcesAsTools(mcp))
+
+        async with Client(mcp) as client:
+            with pytest.raises(ToolError, match="Unknown resource"):
+                await client.call_tool("read_resource", {"uri": "unknown://resource"})
+
+    async def test_reads_binary_as_base64(self):
+        """read_resource returns binary content as base64."""
+        mcp = FastMCP("Test")
+
+        @mcp.resource("data://binary", mime_type="application/octet-stream")
+        def binary_data() -> bytes:
+            return b"\x00\x01\x02\x03"
+
+        mcp.add_transform(ResourcesAsTools(mcp))
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("read_resource", {"uri": "data://binary"})
+            # Should be base64 encoded
+            decoded = base64.b64decode(result.data)
+            assert decoded == b"\x00\x01\x02\x03"
+
+
+class TestResourcesAsToolsWithNamespace:
+    """Test ResourcesAsTools combined with other transforms."""
+
+    async def test_works_with_namespace_on_provider(self):
+        """ResourcesAsTools works when provider has Namespace transform."""
+        from fastmcp.server.providers import FastMCPProvider
+        from fastmcp.server.transforms import Namespace
+
+        sub = FastMCP("Sub")
+
+        @sub.resource("config://app")
+        def app_config() -> str:
+            return "sub config"
+
+        main = FastMCP("Main")
+        provider = FastMCPProvider(sub)
+        provider.add_transform(Namespace("sub"))
+        main.add_provider(provider)
+        main.add_transform(ResourcesAsTools(main))
+
+        async with Client(main) as client:
+            result = await client.call_tool("list_resources", {})
+            resources = json.loads(result.data)
+
+            # Resource should have namespaced URI
+            assert len(resources) == 1
+            assert resources[0]["uri"] == "config://sub/app"
+
+
+class TestResourcesAsToolsRepr:
+    """Test ResourcesAsTools repr."""
+
+    def test_repr(self):
+        """Transform has useful repr."""
+        mcp = FastMCP("Test")
+        transform = ResourcesAsTools(mcp)
+        assert "ResourcesAsTools" in repr(transform)
+
+
+class TestResourcesAsToolsAnnotations:
+    """Test ToolAnnotations on generated resource tools."""
+
+    async def test_list_resources_is_read_only(self):
+        """list_resources is annotated as read-only by default."""
+        mcp = FastMCP("Test")
+        mcp.add_transform(ResourcesAsTools(mcp))
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            tool = next(t for t in tools if t.name == "list_resources")
+            assert tool.annotations is not None
+            assert tool.annotations.read_only_hint is True
+
+    async def test_read_resource_is_read_only(self):
+        """read_resource is annotated as read-only by default."""
+        mcp = FastMCP("Test")
+        mcp.add_transform(ResourcesAsTools(mcp))
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            tool = next(t for t in tools if t.name == "read_resource")
+            assert tool.annotations is not None
+            assert tool.annotations.read_only_hint is True
+
+
+def _deny_all(ctx: AuthContext) -> bool:
+    """Auth check that always denies access."""
+    return False
+
+
+class TestResourcesAsToolsAuthOnServer:
+    """Auth checks work when using ResourcesAsTools on a FastMCP server."""
+
+    async def test_auth_protected_resources_hidden_from_list(self):
+        """Auth-protected resources are filtered from list_resources tool."""
+        mcp = FastMCP("Test")
+
+        @mcp.resource("test://open")
+        def open_resource() -> str:
+            return "open content"
+
+        @mcp.resource("test://protected", auth=_deny_all)
+        def protected_resource() -> str:
+            return "protected content"
+
+        mcp.add_transform(ResourcesAsTools(mcp))
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("list_resources", {})
+            items = json.loads(result.data)
+            uris = [r.get("uri") for r in items if r.get("uri")]
+            assert "test://open" in uris
+            assert "test://protected" not in uris
+
+    async def test_auth_protected_resource_cannot_be_read(self):
+        """Auth-protected resources cannot be read via read_resource tool."""
+        mcp = FastMCP("Test")
+
+        @mcp.resource("test://protected", auth=_deny_all)
+        def protected_resource() -> str:
+            return "protected content"
+
+        mcp.add_transform(ResourcesAsTools(mcp))
+
+        async with Client(mcp) as client:
+            with pytest.raises(ToolError):
+                await client.call_tool("read_resource", {"uri": "test://protected"})
+
+    async def test_open_resource_still_accessible(self):
+        """Non-auth-protected resources can still be read."""
+        mcp = FastMCP("Test")
+
+        @mcp.resource("test://open")
+        def open_resource() -> str:
+            return "open content"
+
+        @mcp.resource("test://protected", auth=_deny_all)
+        def protected_resource() -> str:
+            return "protected content"
+
+        mcp.add_transform(ResourcesAsTools(mcp))
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("read_resource", {"uri": "test://open"})
+            assert result.data == "open content"
+
+
+class TestResourcesAsToolsVisibilityOnServer:
+    """Visibility filtering works when using ResourcesAsTools on a server."""
+
+    async def test_disabled_resources_hidden_from_list(self):
+        """Disabled resources are not listed via list_resources tool."""
+        mcp = FastMCP("Test")
+
+        @mcp.resource("test://public")
+        def public_resource() -> str:
+            return "public content"
+
+        @mcp.resource("test://secret")
+        def secret_resource() -> str:
+            return "secret content"
+
+        mcp.disable(names={"test://secret"})
+        mcp.add_transform(ResourcesAsTools(mcp))
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("list_resources", {})
+            items = json.loads(result.data)
+            uris = [r.get("uri") for r in items if r.get("uri")]
+            assert "test://public" in uris
+            assert "test://secret" not in uris
+
+    async def test_disabled_resource_cannot_be_read(self):
+        """Disabled resources cannot be read via read_resource tool."""
+        mcp = FastMCP("Test")
+
+        @mcp.resource("test://secret")
+        def secret_resource() -> str:
+            return "secret content"
+
+        mcp.disable(names={"test://secret"})
+        mcp.add_transform(ResourcesAsTools(mcp))
+
+        async with Client(mcp) as client:
+            with pytest.raises(ToolError):
+                await client.call_tool("read_resource", {"uri": "test://secret"})
diff --git a/tests/server/transforms/test_search.py b/tests/server/transforms/test_search.py
new file mode 100644
index 0000000..981d044
--- /dev/null
+++ b/tests/server/transforms/test_search.py
@@ -0,0 +1,482 @@
+"""Tests for search transforms."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+from unittest.mock import MagicMock
+
+import mcp_types
+import pytest
+from mcp_types import TextContent
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.context import Context
+from fastmcp.server.middleware.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.server.transforms import Visibility
+from fastmcp.server.transforms.search.bm25 import (
+    BM25SearchTransform,
+    _BM25Index,
+    _catalog_hash,
+)
+from fastmcp.server.transforms.search.regex import RegexSearchTransform
+from fastmcp.tools.base import Tool, ToolResult
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_tool_result(result: ToolResult) -> list[dict[str, Any]]:
+    """Extract tool list from a ToolResult's structured content."""
+    assert result.structured_content is not None
+    return result.structured_content["result"]
+
+
+def _make_server_with_tools() -> FastMCP:
+    mcp = FastMCP("test")
+
+    @mcp.tool
+    def add(a: int, b: int) -> int:
+        """Add two numbers together."""
+        return a + b
+
+    @mcp.tool
+    def multiply(x: float, y: float) -> float:
+        """Multiply two numbers."""
+        return x * y
+
+    @mcp.tool
+    def search_database(query: str, limit: int = 10) -> str:
+        """Search the database for records matching the query."""
+        return f"results for {query}"
+
+    @mcp.tool
+    def delete_record(record_id: str) -> str:
+        """Delete a record from the database by its ID."""
+        return f"deleted {record_id}"
+
+    @mcp.tool
+    def send_email(to: str, subject: str, body: str) -> str:
+        """Send an email to the given recipient."""
+        return "sent"
+
+    return mcp
+
+
+# ---------------------------------------------------------------------------
+# Shared behavior tests (parameterized across both transforms)
+# ---------------------------------------------------------------------------
+
+
+class TestBaseTransformBehavior:
+    """Tests for behavior shared by all search transforms."""
+
+    async def test_list_tools_hides_tools_regex(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(RegexSearchTransform())
+        tools = await mcp.list_tools()
+        names = {t.name for t in tools}
+        assert names == {"search_tools", "call_tool"}
+
+    async def test_list_tools_hides_tools_bm25(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(BM25SearchTransform())
+        tools = await mcp.list_tools()
+        names = {t.name for t in tools}
+        assert names == {"search_tools", "call_tool"}
+
+    async def test_always_visible_pins_tools(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(RegexSearchTransform(always_visible=["add"]))
+        tools = await mcp.list_tools()
+        names = {t.name for t in tools}
+        assert "add" in names
+        assert "search_tools" in names
+        assert "call_tool" in names
+        assert "multiply" not in names
+
+    async def test_get_tool_returns_synthetic(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(RegexSearchTransform())
+        search = await mcp.get_tool("search_tools")
+        assert search is not None
+        assert search.name == "search_tools"
+        call = await mcp.get_tool("call_tool")
+        assert call is not None
+        assert call.name == "call_tool"
+
+    async def test_get_tool_passes_through_hidden(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(RegexSearchTransform())
+        tool = await mcp.get_tool("add")
+        assert tool is not None
+        assert tool.name == "add"
+
+    async def test_call_tool_proxy_executes(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(RegexSearchTransform())
+        # Need to call list_tools to populate catalog
+        await mcp.list_tools()
+        result = await mcp.call_tool(
+            "call_tool", {"name": "add", "arguments": {"a": 2, "b": 3}}
+        )
+        assert any("5" in c.text for c in result.content if isinstance(c, TextContent))
+
+    async def test_custom_tool_names(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(
+            RegexSearchTransform(
+                search_tool_name="find_tools",
+                call_tool_name="run_tool",
+            )
+        )
+        tools = await mcp.list_tools()
+        names = {t.name for t in tools}
+        assert names == {"find_tools", "run_tool"}
+        assert await mcp.get_tool("find_tools") is not None
+        assert await mcp.get_tool("run_tool") is not None
+
+    async def test_search_respects_visibility_filtering(self):
+        """Tools disabled via Visibility transform should not appear in search."""
+        mcp = _make_server_with_tools()
+        mcp.add_transform(Visibility(False, names={"delete_record"}))
+        mcp.add_transform(RegexSearchTransform())
+
+        tools = await mcp.list_tools()
+        names = {t.name for t in tools}
+        assert "delete_record" not in names
+
+        result = await mcp.call_tool("search_tools", {"pattern": "delete"})
+        found = _parse_tool_result(result)
+        assert not any(t["name"] == "delete_record" for t in found)
+
+    async def test_search_respects_auth_middleware(self):
+        """Tools filtered by auth middleware should not appear in search."""
+
+        class BlockAdminTools(Middleware):
+            async def on_list_tools(
+                self,
+                context: MiddlewareContext[mcp_types.ListToolsRequest],
+                call_next: CallNext[mcp_types.ListToolsRequest, Sequence[Tool]],
+            ) -> Sequence[Tool]:
+                tools = await call_next(context)
+                return [t for t in tools if t.name != "delete_record"]
+
+        mcp = _make_server_with_tools()
+        mcp.add_middleware(BlockAdminTools())
+        mcp.add_transform(RegexSearchTransform())
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            names = {t.name for t in tools}
+            assert "delete_record" not in names
+            assert "search_tools" in names
+
+            result = await client.call_tool("search_tools", {"pattern": "delete"})
+            found = _parse_tool_result(result)
+            assert not any(t["name"] == "delete_record" for t in found)
+
+    async def test_search_respects_session_visibility(self):
+        """Tools disabled via session visibility should not appear in search."""
+        mcp = _make_server_with_tools()
+        mcp.add_transform(RegexSearchTransform())
+
+        @mcp.tool
+        async def disable_delete(ctx: Context) -> str:
+            """Helper tool to disable delete_record for this session."""
+            await ctx.disable_components(names={"delete_record"})
+            return "disabled"
+
+        async with Client(mcp) as client:
+            # Before disabling, search should find delete_record
+            result = await client.call_tool("search_tools", {"pattern": "delete"})
+            found = _parse_tool_result(result)
+            assert any(t["name"] == "delete_record" for t in found)
+
+            # Disable via session visibility
+            await client.call_tool("disable_delete", {})
+
+            # After disabling, search should NOT find it
+            result = await client.call_tool("search_tools", {"pattern": "delete"})
+            found = _parse_tool_result(result)
+            assert not any(t["name"] == "delete_record" for t in found)
+
+
+# ---------------------------------------------------------------------------
+# Regex-specific tests
+# ---------------------------------------------------------------------------
+
+
+class TestRegexSearch:
+    async def test_search_by_name(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(RegexSearchTransform())
+        await mcp.list_tools()
+        result = await mcp.call_tool("search_tools", {"pattern": "add"})
+        tools = _parse_tool_result(result)
+        assert any(t["name"] == "add" for t in tools)
+
+    async def test_search_by_description(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(RegexSearchTransform())
+        await mcp.list_tools()
+        result = await mcp.call_tool("search_tools", {"pattern": "email"})
+        tools = _parse_tool_result(result)
+        assert any(t["name"] == "send_email" for t in tools)
+
+    async def test_search_by_param_name(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(RegexSearchTransform())
+        await mcp.list_tools()
+        result = await mcp.call_tool("search_tools", {"pattern": "record_id"})
+        tools = _parse_tool_result(result)
+        assert any(t["name"] == "delete_record" for t in tools)
+
+    async def test_search_by_param_description(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(RegexSearchTransform())
+        await mcp.list_tools()
+        result = await mcp.call_tool("search_tools", {"pattern": "recipient"})
+        tools = _parse_tool_result(result)
+        assert any(t["name"] == "send_email" for t in tools)
+
+    async def test_search_or_pattern(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(RegexSearchTransform(max_results=10))
+        await mcp.list_tools()
+        result = await mcp.call_tool("search_tools", {"pattern": "add|multiply"})
+        tools = _parse_tool_result(result)
+        names = {t["name"] for t in tools}
+        assert "add" in names
+        assert "multiply" in names
+
+    async def test_search_case_insensitive(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(RegexSearchTransform())
+        await mcp.list_tools()
+        result = await mcp.call_tool("search_tools", {"pattern": "ADD"})
+        tools = _parse_tool_result(result)
+        assert any(t["name"] == "add" for t in tools)
+
+    async def test_search_invalid_pattern(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(RegexSearchTransform())
+        await mcp.list_tools()
+        result = await mcp.call_tool("search_tools", {"pattern": "[invalid"})
+        tools = _parse_tool_result(result)
+        assert tools == []
+
+    async def test_search_max_results(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(RegexSearchTransform(max_results=2))
+        await mcp.list_tools()
+        # Match everything
+        result = await mcp.call_tool("search_tools", {"pattern": ".*"})
+        tools = _parse_tool_result(result)
+        assert len(tools) == 2
+
+    async def test_search_no_matches(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(RegexSearchTransform())
+        await mcp.list_tools()
+        result = await mcp.call_tool("search_tools", {"pattern": "zzz_nonexistent"})
+        tools = _parse_tool_result(result)
+        assert tools == []
+
+    async def test_search_returns_full_schema(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(RegexSearchTransform())
+        await mcp.list_tools()
+        result = await mcp.call_tool("search_tools", {"pattern": "add"})
+        tools = _parse_tool_result(result)
+        add_tool = next(t for t in tools if t["name"] == "add")
+        assert "inputSchema" in add_tool
+        assert "properties" in add_tool["inputSchema"]
+
+
+# ---------------------------------------------------------------------------
+# BM25-specific tests
+# ---------------------------------------------------------------------------
+
+
+class TestBM25Search:
+    async def test_search_relevance(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(BM25SearchTransform())
+        await mcp.list_tools()
+        result = await mcp.call_tool("search_tools", {"query": "database"})
+        tools = _parse_tool_result(result)
+        # Database tools should rank highest
+        assert len(tools) > 0
+        names = {t["name"] for t in tools}
+        assert "search_database" in names
+
+    async def test_search_database_tools(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(BM25SearchTransform())
+        await mcp.list_tools()
+        result = await mcp.call_tool(
+            "search_tools", {"query": "delete records from database"}
+        )
+        tools = _parse_tool_result(result)
+        assert len(tools) > 0
+        # delete_record should be highly relevant
+        assert tools[0]["name"] == "delete_record"
+
+    async def test_search_max_results(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(BM25SearchTransform(max_results=2))
+        await mcp.list_tools()
+        result = await mcp.call_tool("search_tools", {"query": "number"})
+        tools = _parse_tool_result(result)
+        assert len(tools) <= 2
+
+    async def test_search_no_matches(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(BM25SearchTransform())
+        await mcp.list_tools()
+        result = await mcp.call_tool("search_tools", {"query": "zzz_nonexistent_xyz"})
+        tools = _parse_tool_result(result)
+        assert tools == []
+
+    async def test_index_rebuilds_on_catalog_change(self):
+        """When a new tool is added, the next list_tools + search sees it."""
+        mcp = _make_server_with_tools()
+        mcp.add_transform(BM25SearchTransform())
+        await mcp.list_tools()
+
+        # Search before adding tool
+        result = await mcp.call_tool("search_tools", {"query": "weather forecast"})
+        tools = _parse_tool_result(result)
+        assert not any(t["name"] == "get_weather" for t in tools)
+
+        # Add a new tool
+        @mcp.tool
+        def get_weather(city: str) -> str:
+            """Get the weather forecast for a city."""
+            return f"sunny in {city}"
+
+        # Must call list_tools to refresh the catalog cache
+        await mcp.list_tools()
+
+        result = await mcp.call_tool("search_tools", {"query": "weather forecast"})
+        tools = _parse_tool_result(result)
+        assert any(t["name"] == "get_weather" for t in tools)
+
+    async def test_search_empty_query(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(BM25SearchTransform())
+        await mcp.list_tools()
+        result = await mcp.call_tool("search_tools", {"query": ""})
+        tools = _parse_tool_result(result)
+        assert tools == []
+
+    async def test_search_returns_full_schema(self):
+        mcp = _make_server_with_tools()
+        mcp.add_transform(BM25SearchTransform())
+        await mcp.list_tools()
+        result = await mcp.call_tool("search_tools", {"query": "add numbers"})
+        tools = _parse_tool_result(result)
+        add_tool = next(t for t in tools if t["name"] == "add")
+        assert "inputSchema" in add_tool
+        assert "properties" in add_tool["inputSchema"]
+
+
+# ---------------------------------------------------------------------------
+# BM25 index unit tests
+# ---------------------------------------------------------------------------
+
+
+class TestBM25Index:
+    def test_basic_ranking(self):
+        index = _BM25Index()
+        index.build(
+            [
+                "search database query records",
+                "add two numbers together",
+                "send email recipient subject",
+            ]
+        )
+        results = index.query("database records", 3)
+        assert results[0] == 0  # Database doc should rank first
+
+    def test_empty_corpus(self):
+        index = _BM25Index()
+        index.build([])
+        assert index.query("anything", 5) == []
+
+    def test_no_matching_tokens(self):
+        index = _BM25Index()
+        index.build(["alpha beta gamma"])
+        assert index.query("zzz", 5) == []
+
+
+# ---------------------------------------------------------------------------
+# call_tool self-reference guard
+# ---------------------------------------------------------------------------
+
+
+class TestCallToolGuard:
+    async def test_call_tool_proxy_rejects_itself(self):
+        """Calling call_tool(name='call_tool') must not recurse infinitely."""
+        mcp = _make_server_with_tools()
+        mcp.add_transform(RegexSearchTransform())
+
+        async with Client(mcp) as client:
+            with pytest.raises(Exception):
+                await client.call_tool(
+                    "call_tool", {"name": "call_tool", "arguments": {}}
+                )
+
+    async def test_call_tool_proxy_rejects_search_tool(self):
+        """Calling call_tool(name='search_tools') must be rejected."""
+        mcp = _make_server_with_tools()
+        mcp.add_transform(RegexSearchTransform())
+
+        async with Client(mcp) as client:
+            with pytest.raises(Exception):
+                await client.call_tool(
+                    "call_tool",
+                    {"name": "search_tools", "arguments": {"pattern": "add"}},
+                )
+
+    async def test_call_tool_proxy_rejects_custom_names(self):
+        """Guard works when synthetic tools have custom names."""
+        mcp = _make_server_with_tools()
+        mcp.add_transform(
+            RegexSearchTransform(
+                search_tool_name="find_tools", call_tool_name="run_tool"
+            )
+        )
+
+        async with Client(mcp) as client:
+            with pytest.raises(Exception):
+                await client.call_tool(
+                    "run_tool", {"name": "run_tool", "arguments": {}}
+                )
+            with pytest.raises(Exception):
+                await client.call_tool(
+                    "run_tool", {"name": "find_tools", "arguments": {"pattern": "add"}}
+                )
+
+
+# ---------------------------------------------------------------------------
+# catalog hash staleness
+# ---------------------------------------------------------------------------
+
+
+class TestCatalogHash:
+    def test_hash_differs_for_same_name_different_description(self):
+        """Hash must change when a tool's description changes, not just its name."""
+        tool_a = MagicMock()
+        tool_a.name = "search"
+        tool_a.description = "find records in the database"
+        tool_a.parameters = {}
+
+        tool_b = MagicMock()
+        tool_b.name = "search"
+        tool_b.description = "send an email to a recipient"
+        tool_b.parameters = {}
+
+        assert _catalog_hash([tool_a]) != _catalog_hash([tool_b])
diff --git a/tests/server/transforms/test_visibility.py b/tests/server/transforms/test_visibility.py
new file mode 100644
index 0000000..d3434cc
--- /dev/null
+++ b/tests/server/transforms/test_visibility.py
@@ -0,0 +1,275 @@
+"""Tests for Visibility transform."""
+
+import pytest
+
+from fastmcp.server.transforms.visibility import Visibility, is_enabled
+from fastmcp.tools.base import Tool
+from fastmcp.utilities.versions import VersionSpec
+
+
+class TestMatching:
+    """Test component matching logic."""
+
+    def test_empty_criteria_matches_nothing(self):
+        """Empty criteria is a safe default - matches nothing."""
+        t = Visibility(False)
+        assert t._matches(Tool(name="anything", parameters={})) is False
+
+    def test_match_all_matches_everything(self):
+        """match_all=True matches all components."""
+        t = Visibility(False, match_all=True)
+        assert t._matches(Tool(name="anything", parameters={})) is True
+
+    def test_match_by_name(self):
+        """Matches component by name."""
+        t = Visibility(False, names={"foo"})
+        assert t._matches(Tool(name="foo", parameters={})) is True
+        assert t._matches(Tool(name="bar", parameters={})) is False
+
+    def test_match_by_version(self):
+        """Matches component by version."""
+        t = Visibility(False, version=VersionSpec(eq="v1"))
+        assert t._matches(Tool(name="foo", version="v1", parameters={})) is True
+        assert t._matches(Tool(name="foo", version="v2", parameters={})) is False
+
+    def test_match_by_version_spec_exact(self):
+        """VersionSpec(eq="v1") matches v1 only."""
+        t = Visibility(False, version=VersionSpec(eq="v1"))
+        assert t._matches(Tool(name="foo", version="v1", parameters={})) is True
+        assert t._matches(Tool(name="foo", version="v2", parameters={})) is False
+        assert t._matches(Tool(name="foo", version="v0", parameters={})) is False
+
+    def test_match_by_version_spec_gte(self):
+        """VersionSpec(gte="v2") matches v2, v3, but not v1."""
+        t = Visibility(False, version=VersionSpec(gte="v2"))
+        assert t._matches(Tool(name="foo", version="v1", parameters={})) is False
+        assert t._matches(Tool(name="foo", version="v2", parameters={})) is True
+        assert t._matches(Tool(name="foo", version="v3", parameters={})) is True
+
+    def test_match_by_version_spec_range(self):
+        """VersionSpec(gte="v1", lt="v3") matches v1, v2, but not v3."""
+        t = Visibility(False, version=VersionSpec(gte="v1", lt="v3"))
+        assert t._matches(Tool(name="foo", version="v0", parameters={})) is False
+        assert t._matches(Tool(name="foo", version="v1", parameters={})) is True
+        assert t._matches(Tool(name="foo", version="v2", parameters={})) is True
+        assert t._matches(Tool(name="foo", version="v3", parameters={})) is False
+        assert t._matches(Tool(name="foo", version="v4", parameters={})) is False
+
+    def test_unversioned_does_not_match_version_spec(self):
+        """Unversioned components (version=None) don't match a VersionSpec."""
+        t = Visibility(False, version=VersionSpec(eq="v1"))
+        assert t._matches(Tool(name="foo", parameters={})) is False
+
+        t2 = Visibility(False, version=VersionSpec(gte="v1"))
+        assert t2._matches(Tool(name="foo", parameters={})) is False
+
+    def test_match_by_tag(self):
+        """Matches if component has any of the specified tags."""
+        t = Visibility(False, tags=set({"internal", "deprecated"}))
+        assert t._matches(Tool(name="foo", parameters={}, tags={"internal"})) is True
+        assert t._matches(Tool(name="foo", parameters={}, tags={"public"})) is False
+
+    def test_match_by_component_type(self):
+        """Only matches specified component types."""
+        t = Visibility(False, names={"foo"}, components={"prompt"})
+        # Tool has key "tool:foo@", not "prompt:foo@"
+        assert t._matches(Tool(name="foo", parameters={})) is False
+
+    def test_all_criteria_must_match(self):
+        """Multiple criteria use AND logic - all must match."""
+        t = Visibility(
+            False,
+            names={"foo"},
+            version=VersionSpec(eq="v1"),
+            tags=set({"internal"}),
+        )
+        # All match
+        assert (
+            t._matches(Tool(name="foo", version="v1", parameters={}, tags={"internal"}))
+            is True
+        )
+        # Version doesn't match
+        assert (
+            t._matches(Tool(name="foo", version="v2", parameters={}, tags={"internal"}))
+            is False
+        )
+
+
+class TestMarking:
+    """Test visibility state marking."""
+
+    def test_disable_marks_as_disabled(self):
+        """Visibility(False, ...) marks matching components as disabled."""
+        tool = Tool(name="foo", parameters={})
+        marked = Visibility(False, names={"foo"})._mark_component(tool)
+        assert is_enabled(marked) is False
+
+    def test_enable_marks_as_enabled(self):
+        """Visibility(True, ...) marks matching components as enabled."""
+        tool = Tool(name="foo", parameters={})
+        marked = Visibility(True, names={"foo"})._mark_component(tool)
+        assert is_enabled(marked) is True
+        assert marked.meta is not None
+        assert marked.meta["fastmcp"]["_internal"]["visibility"] is True
+
+    def test_non_matching_unchanged(self):
+        """Non-matching components are not modified."""
+        tool = Tool(name="bar", parameters={})
+        result = Visibility(False, names={"foo"})._mark_component(tool)
+        # No _internal key added
+        assert result.meta is None or "_internal" not in result.meta.get("fastmcp", {})
+        assert is_enabled(result) is True
+
+    def test_returns_copy_for_matching(self):
+        """Marking returns a copy to avoid mutating shared provider objects."""
+        tool = Tool(name="foo", parameters={})
+        result = Visibility(False, names={"foo"})._mark_component(tool)
+        assert result is not tool
+        assert is_enabled(result) is False
+        # Original is untouched
+        assert is_enabled(tool) is True
+
+    def test_disable_all(self):
+        """match_all=True disables all components."""
+        tool = Tool(name="anything", parameters={})
+        marked = Visibility(False, match_all=True)._mark_component(tool)
+        assert is_enabled(marked) is False
+
+
+class TestOverride:
+    """Test that later marks override earlier ones."""
+
+    def test_enable_overrides_disable(self):
+        """An enable after disable results in enabled."""
+        tool = Tool(name="foo", parameters={})
+        marked = Visibility(False, names={"foo"})._mark_component(tool)
+        assert is_enabled(marked) is False
+
+        marked = Visibility(True, names={"foo"})._mark_component(marked)
+        assert is_enabled(marked) is True
+
+    def test_disable_overrides_enable(self):
+        """A disable after enable results in disabled."""
+        tool = Tool(name="foo", parameters={})
+        marked = Visibility(True, names={"foo"})._mark_component(tool)
+        assert is_enabled(marked) is True
+
+        marked = Visibility(False, names={"foo"})._mark_component(marked)
+        assert is_enabled(marked) is False
+
+
+class TestHelperFunctions:
+    """Test is_enabled helper."""
+
+    def test_unmarked_is_enabled(self):
+        """Components without marks are enabled by default."""
+        tool = Tool(name="foo", parameters={})
+        assert is_enabled(tool) is True
+
+    def test_filtering_pattern(self):
+        """Common pattern: filter list with is_enabled."""
+        tools = [
+            Tool(name="enabled", parameters={}),
+            Tool(name="disabled", parameters={}),
+        ]
+        vis = Visibility(False, names={"disabled"})
+        marked_tools = [vis._mark_component(t) for t in tools]
+
+        visible = [t for t in marked_tools if is_enabled(t)]
+        assert [t.name for t in visible] == ["enabled"]
+
+
+class TestMetadata:
+    """Test metadata handling."""
+
+    def test_internal_metadata_stripped_by_get_meta(self):
+        """Internal metadata is stripped when calling get_meta()."""
+        tool = Tool(name="foo", parameters={})
+        marked = Visibility(True, names={"foo"})._mark_component(tool)
+
+        # Raw meta has _internal
+        assert marked.meta is not None
+        assert "_internal" in marked.meta.get("fastmcp", {})
+
+        # get_meta() strips it
+        output = marked.get_meta()
+        assert "_internal" not in output.get("fastmcp", {})
+
+    def test_user_metadata_preserved(self):
+        """User-provided metadata is not affected."""
+        tool = Tool(name="foo", parameters={}, meta={"custom": "value"})
+        marked = Visibility(False, names={"foo"})._mark_component(tool)
+
+        assert marked.meta is not None
+        assert marked.meta["custom"] == "value"
+
+
+class TestRepr:
+    """Test string representation."""
+
+    def test_repr_disable(self):
+        """Repr shows disable action and criteria."""
+        t = Visibility(False, names={"foo"})
+        r = repr(t)
+        assert "disable" in r
+        assert "foo" in r
+
+    def test_repr_enable(self):
+        """Repr shows enable action."""
+        t = Visibility(True, names={"foo"})
+        assert "enable" in repr(t)
+
+    def test_repr_match_all(self):
+        """Repr shows match_all."""
+        t = Visibility(False, match_all=True)
+        assert "match_all=True" in repr(t)
+
+
+class TestTransformChain:
+    """Test Visibility in async transform chains."""
+
+    @pytest.fixture
+    def tools(self):
+        return [
+            Tool(name="public", parameters={}, tags={"public"}),
+            Tool(name="internal", parameters={}, tags={"internal"}),
+            Tool(name="safe_internal", parameters={}, tags={"internal", "safe"}),
+        ]
+
+    async def test_list_tools_marks_matching(self, tools):
+        """list_tools applies marks to matching components."""
+        disable_internal = Visibility(False, tags=set({"internal"}))
+
+        result = await disable_internal.list_tools(tools)
+
+        assert len(result) == 3
+        assert is_enabled(result[0])  # public
+        assert not is_enabled(result[1])  # internal
+        assert not is_enabled(result[2])  # safe_internal
+
+    async def test_later_transform_overrides(self, tools):
+        """Later transforms in chain override earlier ones."""
+        disable_internal = Visibility(False, tags=set({"internal"}))
+        enable_safe = Visibility(True, tags=set({"safe"}))
+
+        # Apply transforms sequentially
+        after_disable = await disable_internal.list_tools(tools)
+        result = await enable_safe.list_tools(after_disable)
+        enabled = [t for t in result if is_enabled(t)]
+
+        # public: never disabled
+        # internal: disabled, stays disabled
+        # safe_internal: disabled then re-enabled
+        assert {t.name for t in enabled} == {"public", "safe_internal"}
+
+    async def test_allowlist_pattern(self, tools):
+        """Disable all, then enable specific = allowlist."""
+        disable_all = Visibility(False, match_all=True)
+        enable_public = Visibility(True, tags=set({"public"}))
+
+        # Apply transforms sequentially
+        after_disable = await disable_all.list_tools(tools)
+        result = await enable_public.list_tools(after_disable)
+        enabled = [t for t in result if is_enabled(t)]
+
+        assert [t.name for t in enabled] == ["public"]
diff --git a/tests/server/versioning/__init__.py b/tests/server/versioning/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/server/versioning/test_calls.py b/tests/server/versioning/test_calls.py
new file mode 100644
index 0000000..01f1175
--- /dev/null
+++ b/tests/server/versioning/test_calls.py
@@ -0,0 +1,361 @@
+"""Tests for versioned calls and client version selection."""
+# ruff: noqa: F811  # Intentional function redefinition for version testing
+
+from __future__ import annotations
+
+from mcp_types import TextContent
+
+from fastmcp import FastMCP
+from fastmcp.utilities.versions import (
+    VersionSpec,
+)
+
+
+class TestVersionMixingValidation:
+    """Tests for versioned/unversioned mixing prevention."""
+
+    async def test_resource_mixing_rejected(self):
+        """Cannot mix versioned and unversioned resources with the same URI."""
+        import pytest
+
+        mcp = FastMCP()
+
+        @mcp.resource("file:///config", version="1.0")
+        def config_v1() -> str:
+            return "v1"
+
+        with pytest.raises(ValueError, match="unversioned.*versioned"):
+
+            @mcp.resource("file:///config")
+            def config_unversioned() -> str:
+                return "unversioned"
+
+    async def test_prompt_mixing_rejected(self):
+        """Cannot mix versioned and unversioned prompts with the same name."""
+        import pytest
+
+        mcp = FastMCP()
+
+        @mcp.prompt
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        with pytest.raises(ValueError, match="versioned.*unversioned"):
+
+            @mcp.prompt(version="1.0")
+            def greet(name: str) -> str:
+                return f"Hi, {name}!"
+
+    async def test_multiple_versions_allowed(self):
+        """Multiple versioned components with same name are allowed."""
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0")
+        def calc() -> int:
+            return 1
+
+        @mcp.tool(version="2.0")
+        def calc() -> int:
+            return 2
+
+        @mcp.tool(version="3.0")
+        def calc() -> int:
+            return 3
+
+        # All versioned - list_tools returns all
+        tools = await mcp.list_tools()
+        assert len(tools) == 3
+        versions = {t.version for t in tools}
+        assert versions == {"1.0", "2.0", "3.0"}
+
+        # get_tool returns highest
+        tool = await mcp.get_tool("calc")
+        assert tool is not None
+        assert tool.version == "3.0"
+
+
+class TestVersionValidation:
+    """Tests for version string validation."""
+
+    async def test_version_with_at_symbol_rejected(self):
+        """Version strings containing '@' should be rejected."""
+        import pytest
+        from pydantic import ValidationError
+
+        mcp = FastMCP()
+
+        with pytest.raises(ValidationError, match="cannot contain '@'"):
+
+            @mcp.tool(version="1.0@beta")
+            def my_tool() -> str:
+                return "test"
+
+
+class TestVersionMetadata:
+    """Tests for version metadata exposure in list operations."""
+
+    async def test_tool_versions_in_meta(self):
+        """Each version has its own version in metadata."""
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0")
+        def add(x: int, y: int) -> int:  # noqa: F811
+            return x + y
+
+        @mcp.tool(version="2.0")
+        def add(x: int, y: int) -> int:  # noqa: F811
+            return x + y
+
+        # list_tools returns all versions
+        tools = await mcp.list_tools()
+        assert len(tools) == 2
+
+        # Each version has its own version in metadata
+        by_version = {t.version: t for t in tools}
+        assert by_version["1.0"].get_meta()["fastmcp"]["version"] == "1.0"
+        assert by_version["2.0"].get_meta()["fastmcp"]["version"] == "2.0"
+
+    async def test_resource_versions_in_meta(self):
+        """Each version has its own version in metadata."""
+        mcp = FastMCP()
+
+        @mcp.resource("data://config", version="1.0")
+        def config_v1() -> str:  # noqa: F811
+            return "v1"
+
+        @mcp.resource("data://config", version="2.0")
+        def config_v2() -> str:  # noqa: F811
+            return "v2"
+
+        # list_resources returns all versions
+        resources = await mcp.list_resources()
+        assert len(resources) == 2
+
+        # Each version has its own version in metadata
+        by_version = {r.version: r for r in resources}
+        assert by_version["1.0"].get_meta()["fastmcp"]["version"] == "1.0"
+        assert by_version["2.0"].get_meta()["fastmcp"]["version"] == "2.0"
+
+    async def test_prompt_versions_in_meta(self):
+        """Each version has its own version in metadata."""
+        mcp = FastMCP()
+
+        @mcp.prompt(version="1.0")
+        def greet() -> str:  # noqa: F811
+            return "Hello v1"
+
+        @mcp.prompt(version="2.0")
+        def greet() -> str:  # noqa: F811
+            return "Hello v2"
+
+        # list_prompts returns all versions
+        prompts = await mcp.list_prompts()
+        assert len(prompts) == 2
+
+        # Each version has its own version in metadata
+        by_version = {p.version: p for p in prompts}
+        assert by_version["1.0"].get_meta()["fastmcp"]["version"] == "1.0"
+        assert by_version["2.0"].get_meta()["fastmcp"]["version"] == "2.0"
+
+    async def test_unversioned_no_versions_list(self):
+        """Unversioned components should not have versions list in meta."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def simple() -> str:
+            return "simple"
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+
+        tool = tools[0]
+        meta = tool.get_meta()
+        assert "versions" not in meta.get("fastmcp", {})
+
+
+class TestVersionedCalls:
+    """Tests for calling specific component versions."""
+
+    async def test_call_tool_with_version(self):
+        """call_tool should use specified version."""
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0")
+        def calculate(x: int, y: int) -> int:  # noqa: F811
+            return x + y
+
+        @mcp.tool(version="2.0")
+        def calculate(x: int, y: int) -> int:  # noqa: F811
+            return x * y
+
+        # Default: highest version (2.0, multiplication)
+        result = await mcp.call_tool("calculate", {"x": 3, "y": 4})
+        assert result.structured_content is not None
+        assert result.structured_content["result"] == 12
+
+        # Explicit v1.0 (addition)
+        result = await mcp.call_tool(
+            "calculate", {"x": 3, "y": 4}, version=VersionSpec(eq="1.0")
+        )
+        assert result.structured_content is not None
+        assert result.structured_content["result"] == 7
+
+        # Explicit v2.0 (multiplication)
+        result = await mcp.call_tool(
+            "calculate", {"x": 3, "y": 4}, version=VersionSpec(eq="2.0")
+        )
+        assert result.structured_content is not None
+        assert result.structured_content["result"] == 12
+
+    async def test_read_resource_with_version(self):
+        """read_resource should use specified version."""
+        mcp = FastMCP()
+
+        @mcp.resource("data://config", version="1.0")
+        def config() -> str:  # noqa: F811
+            return "config v1"
+
+        @mcp.resource("data://config", version="2.0")
+        def config() -> str:  # noqa: F811
+            return "config v2"
+
+        # Default: highest version
+        result = await mcp.read_resource("data://config")
+        assert result.contents[0].content == "config v2"
+
+        # Explicit v1.0
+        result = await mcp.read_resource("data://config", version=VersionSpec(eq="1.0"))
+        assert result.contents[0].content == "config v1"
+
+    async def test_render_prompt_with_version(self):
+        """render_prompt should use specified version."""
+        mcp = FastMCP()
+
+        @mcp.prompt(version="1.0")
+        def greet() -> str:  # noqa: F811
+            return "Hello from v1"
+
+        @mcp.prompt(version="2.0")
+        def greet() -> str:  # noqa: F811
+            return "Hello from v2"
+
+        # Default: highest version
+        result = await mcp.render_prompt("greet")
+        content = result.messages[0].content
+        assert isinstance(content, TextContent) and content.text == "Hello from v2"
+
+        # Explicit v1.0
+        result = await mcp.render_prompt("greet", version=VersionSpec(eq="1.0"))
+        content = result.messages[0].content
+        assert isinstance(content, TextContent) and content.text == "Hello from v1"
+
+    async def test_call_tool_invalid_version_not_found(self):
+        """Calling with non-existent version should raise NotFoundError."""
+        import pytest
+
+        from fastmcp.exceptions import NotFoundError
+
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0")
+        def mytool() -> str:
+            return "v1"
+
+        with pytest.raises(NotFoundError):
+            await mcp.call_tool("mytool", {}, version=VersionSpec(eq="999.0"))
+
+
+class TestClientVersionSelection:
+    """Tests for client-side version selection via the version parameter.
+
+    Version selection flows through request-level _meta, not arguments.
+    """
+
+    import pytest
+
+    @pytest.mark.parametrize(
+        "version,expected",
+        [
+            (None, 10),  # Default: highest version (2.0) -> 5 * 2
+            ("1.0", 6),  # v1.0 -> 5 + 1
+            ("2.0", 10),  # v2.0 -> 5 * 2
+        ],
+    )
+    async def test_call_tool_version_selection(
+        self, version: str | None, expected: int
+    ):
+        """Client.call_tool routes to correct version via request meta."""
+        from fastmcp import Client
+
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0")
+        def calc(x: int) -> int:  # noqa: F811
+            return x + 1
+
+        @mcp.tool(version="2.0")
+        def calc(x: int) -> int:  # noqa: F811
+            return x * 2
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("calc", {"x": 5}, version=version)
+            assert result.data == expected
+
+    @pytest.mark.parametrize(
+        "version,expected",
+        [
+            (None, "Hello world from v2"),  # Default: highest version
+            ("1.0", "Hello world from v1"),
+            ("2.0", "Hello world from v2"),
+        ],
+    )
+    async def test_get_prompt_version_selection(
+        self, version: str | None, expected: str
+    ):
+        """Client.get_prompt routes to correct version via request meta."""
+        from fastmcp import Client
+
+        mcp = FastMCP()
+
+        @mcp.prompt(version="1.0")
+        def greet(name: str) -> str:  # noqa: F811
+            return f"Hello {name} from v1"
+
+        @mcp.prompt(version="2.0")
+        def greet(name: str) -> str:  # noqa: F811
+            return f"Hello {name} from v2"
+
+        async with Client(mcp) as client:
+            result = await client.get_prompt(
+                "greet", {"name": "world"}, version=version
+            )
+            content = result.messages[0].content
+            assert isinstance(content, TextContent) and content.text == expected
+
+    @pytest.mark.parametrize(
+        "version,expected",
+        [
+            (None, "v2 data"),  # Default: highest version
+            ("1.0", "v1 data"),
+            ("2.0", "v2 data"),
+        ],
+    )
+    async def test_read_resource_version_selection(
+        self, version: str | None, expected: str
+    ):
+        """Client.read_resource routes to correct version via request meta."""
+        from fastmcp import Client
+
+        mcp = FastMCP()
+
+        @mcp.resource("data://info", version="1.0")
+        def info_v1() -> str:  # noqa: F811
+            return "v1 data"
+
+        @mcp.resource("data://info", version="2.0")
+        def info_v2() -> str:  # noqa: F811
+            return "v2 data"
+
+        async with Client(mcp) as client:
+            result = await client.read_resource("data://info", version=version)
+            assert result[0].text == expected
diff --git a/tests/server/versioning/test_filtering.py b/tests/server/versioning/test_filtering.py
new file mode 100644
index 0000000..c68cf16
--- /dev/null
+++ b/tests/server/versioning/test_filtering.py
@@ -0,0 +1,614 @@
+"""Tests for version filtering functionality."""
+# ruff: noqa: F811  # Intentional function redefinition for version testing
+
+from __future__ import annotations
+
+from fastmcp import FastMCP
+from fastmcp.server.transforms import VersionFilter
+from fastmcp.utilities.versions import (
+    VersionSpec,
+)
+
+
+class TestVersionFilter:
+    """Tests for VersionFilter transform."""
+
+    async def test_version_lt_filters_high_versions(self):
+        """VersionFilter(version_lt='3.0') hides v3+, shows v1 and v2."""
+        from fastmcp.server.transforms import VersionFilter
+
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0")
+        def calc() -> int:
+            return 1
+
+        @mcp.tool(version="2.0")
+        def calc() -> int:
+            return 2
+
+        @mcp.tool(version="3.0")
+        def calc() -> int:
+            return 3
+
+        # Without filter, list_tools returns all versions
+        tools = await mcp.list_tools()
+        versions = {t.version for t in tools}
+        assert versions == {"1.0", "2.0", "3.0"}
+
+        # With filter, only v1 and v2 are visible
+        mcp.add_transform(VersionFilter(version_lt="3.0"))
+        tools = await mcp.list_tools()
+        versions = {t.version for t in tools}
+        assert versions == {"1.0", "2.0"}
+
+        # get_tool returns highest matching version
+        tool = await mcp.get_tool("calc")
+        assert tool is not None
+        assert tool.version == "2.0"
+
+    async def test_version_gte_filters_low_versions(self):
+        """VersionFilter(version_gte='2.0') hides v1, shows v2 and v3."""
+        from fastmcp.server.transforms import VersionFilter
+
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0")
+        def add(x: int) -> int:
+            return x + 1
+
+        @mcp.tool(version="2.0")
+        def add(x: int) -> int:
+            return x + 2
+
+        @mcp.tool(version="3.0")
+        def add(x: int) -> int:
+            return x + 3
+
+        mcp.add_transform(VersionFilter(version_gte="2.0"))
+
+        # list_tools shows all matching versions (v2 and v3)
+        tools = await mcp.list_tools()
+        versions = {t.version for t in tools}
+        assert versions == {"2.0", "3.0"}
+
+        # get_tool returns highest matching version
+        tool = await mcp.get_tool("add")
+        assert tool is not None
+        assert tool.version == "3.0"
+
+        # Can request specific versions in range
+        tool_v2 = await mcp.get_tool("add", VersionSpec(eq="2.0"))
+        assert tool_v2 is not None
+        assert tool_v2.version == "2.0"
+
+        # Cannot request version outside range - returns None
+        assert await mcp.get_tool("add", VersionSpec(eq="1.0")) is None
+
+    async def test_version_range(self):
+        """VersionFilter(version_gte='2.0', version_lt='3.0') shows only v2.x."""
+        from fastmcp.server.transforms import VersionFilter
+
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0")
+        def calc() -> int:
+            return 1
+
+        @mcp.tool(version="2.0")
+        def calc() -> int:
+            return 2
+
+        @mcp.tool(version="2.5")
+        def calc() -> int:
+            return 25
+
+        @mcp.tool(version="3.0")
+        def calc() -> int:
+            return 3
+
+        mcp.add_transform(VersionFilter(version_gte="2.0", version_lt="3.0"))
+
+        # list_tools shows all versions in range
+        tools = await mcp.list_tools()
+        versions = {t.version for t in tools}
+        assert versions == {"2.0", "2.5"}
+
+        # get_tool returns highest in range
+        tool = await mcp.get_tool("calc")
+        assert tool is not None
+        assert tool.version == "2.5"
+
+        # Can request specific versions in range
+        tool_v2 = await mcp.get_tool("calc", VersionSpec(eq="2.0"))
+        assert tool_v2 is not None
+        assert tool_v2.version == "2.0"
+
+        # Versions outside range are not accessible - return None
+        assert await mcp.get_tool("calc", VersionSpec(eq="1.0")) is None
+        assert await mcp.get_tool("calc", VersionSpec(eq="3.0")) is None
+
+    async def test_unversioned_always_passes(self):
+        """Unversioned components pass through any filter."""
+        from fastmcp.server.transforms import VersionFilter
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def unversioned_tool() -> str:
+            return "unversioned"
+
+        @mcp.tool(version="5.0")
+        def versioned_tool() -> str:
+            return "v5"
+
+        # Filter that would exclude v5.0
+        mcp.add_transform(VersionFilter(version_lt="3.0"))
+
+        tools = await mcp.list_tools()
+        names = [t.name for t in tools]
+        assert "unversioned_tool" in names
+        assert "versioned_tool" not in names
+
+    async def test_include_unversioned_false_excludes_unversioned_tools(self):
+        """Setting include_unversioned=False hides unversioned tools."""
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def unversioned_tool() -> str:
+            return "unversioned"
+
+        @mcp.tool(version="2.0")
+        def included_versioned_tool() -> str:
+            return "v2"
+
+        @mcp.tool(version="5.0")
+        def excluded_versioned_tool() -> str:
+            return "v5"
+
+        mcp.add_transform(VersionFilter(version_lt="3.0", include_unversioned=False))
+
+        tools = await mcp.list_tools()
+        assert [tool.name for tool in tools] == ["included_versioned_tool"]
+
+    async def test_date_versions(self):
+        """Works with date-based versions like '2025-01-15'."""
+        from fastmcp.server.transforms import VersionFilter
+
+        mcp = FastMCP()
+
+        @mcp.tool(version="2025-01-01")
+        def report() -> str:
+            return "jan"
+
+        @mcp.tool(version="2025-06-01")
+        def report() -> str:
+            return "jun"
+
+        @mcp.tool(version="2025-12-01")
+        def report() -> str:
+            return "dec"
+
+        # Q1 API: before April
+        mcp.add_transform(VersionFilter(version_lt="2025-04-01"))
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+        assert tools[0].version == "2025-01-01"
+
+    async def test_get_tool_respects_filter(self):
+        """get_tool() returns None if highest version is filtered out."""
+
+        from fastmcp.server.transforms import VersionFilter
+
+        mcp = FastMCP()
+
+        @mcp.tool(version="5.0")
+        def only_v5() -> str:
+            return "v5"
+
+        mcp.add_transform(VersionFilter(version_lt="3.0"))
+
+        # Tool exists but is filtered out - returns None (use get_tool to apply transforms)
+        assert await mcp.get_tool("only_v5") is None
+
+    async def test_must_specify_at_least_one(self):
+        """VersionFilter() with no args raises ValueError."""
+        import pytest
+
+        from fastmcp.server.transforms import VersionFilter
+
+        with pytest.raises(ValueError, match="At least one of"):
+            VersionFilter()
+
+    async def test_resources_filtered(self):
+        """Resources are filtered by version."""
+        from fastmcp.server.transforms import VersionFilter
+
+        mcp = FastMCP()
+
+        @mcp.resource("file:///config", version="1.0")
+        def config_v1() -> str:
+            return "v1"
+
+        @mcp.resource("file:///config", version="2.0")
+        def config_v2() -> str:
+            return "v2"
+
+        mcp.add_transform(VersionFilter(version_lt="2.0"))
+
+        resources = await mcp.list_resources()
+        assert len(resources) == 1
+        assert resources[0].version == "1.0"
+
+    async def test_include_unversioned_false_excludes_unversioned_resources(self):
+        """Setting include_unversioned=False hides unversioned resources."""
+
+        mcp = FastMCP()
+
+        @mcp.resource("file:///unversioned")
+        def unversioned_resource() -> str:
+            return "unversioned"
+
+        @mcp.resource("file:///included_versioned", version="1.0")
+        def included_versioned_resource() -> str:
+            return "v1"
+
+        @mcp.resource("file:///excluded_versioned", version="5.0")
+        def excluded_versioned_resource() -> str:
+            return "v5"
+
+        mcp.add_transform(VersionFilter(version_lt="2.0", include_unversioned=False))
+
+        resources = await mcp.list_resources()
+        assert [str(resource.uri) for resource in resources] == [
+            "file:///included_versioned"
+        ]
+
+    async def test_include_unversioned_false_excludes_unversioned_resource_templates(
+        self,
+    ):
+        """Setting include_unversioned=False hides unversioned resource templates."""
+        mcp = FastMCP()
+
+        @mcp.resource("resource://unversioned/{name}")
+        def unversioned_template(name: str) -> str:
+            return f"unversioned:{name}"
+
+        @mcp.resource("resource://included_versioned/{name}", version="1.0")
+        def included_versioned_template(name: str) -> str:
+            return f"versioned:{name}"
+
+        @mcp.resource("resource://excluded_versioned/{name}", version="5.0")
+        def excluded_versioned_template(name: str) -> str:
+            return f"excluded:{name}"
+
+        mcp.add_transform(VersionFilter(version_lt="2.0", include_unversioned=False))
+
+        templates = await mcp.list_resource_templates()
+        assert [template.uri_template for template in templates] == [
+            "resource://included_versioned/{name}"
+        ]
+
+    async def test_prompts_filtered(self):
+        """Prompts are filtered by version."""
+        from fastmcp.server.transforms import VersionFilter
+
+        mcp = FastMCP()
+
+        @mcp.prompt(version="1.0")
+        def greet(name: str) -> str:
+            return f"Hi {name}"
+
+        @mcp.prompt(version="2.0")
+        def greet(name: str) -> str:
+            return f"Hello {name}"
+
+        mcp.add_transform(VersionFilter(version_lt="2.0"))
+
+        prompts = await mcp.list_prompts()
+        assert len(prompts) == 1
+        assert prompts[0].version == "1.0"
+
+    async def test_include_unversioned_false_excludes_unversioned_prompts(self):
+        """Setting include_unversioned=False hides unversioned prompts."""
+        mcp = FastMCP()
+
+        @mcp.prompt
+        def unversioned_prompt(name: str) -> str:
+            return f"Unversioned: {name}"
+
+        @mcp.prompt(version="1.0")
+        def included_versioned_prompt(name: str) -> str:
+            return f"Versioned: {name}"
+
+        @mcp.prompt(version="5.0")
+        def excluded_versioned_prompt(name: str) -> str:
+            return f"Excluded: {name}"
+
+        mcp.add_transform(VersionFilter(version_lt="2.0", include_unversioned=False))
+
+        prompts = await mcp.list_prompts()
+        assert [prompt.name for prompt in prompts] == ["included_versioned_prompt"]
+
+    async def test_repr(self):
+        """Test VersionFilter string representation."""
+        from fastmcp.server.transforms import VersionFilter
+
+        f1 = VersionFilter(version_lt="3.0")
+        assert repr(f1) == "VersionFilter(version_lt='3.0')"
+
+        f2 = VersionFilter(version_gte="2.0", version_lt="3.0")
+        assert repr(f2) == "VersionFilter(version_gte='2.0', version_lt='3.0')"
+
+        f3 = VersionFilter(version_gte="1.0")
+        assert repr(f3) == "VersionFilter(version_gte='1.0')"
+
+        f4 = VersionFilter(version_lt="3.0", include_unversioned=False)
+        assert repr(f4) == "VersionFilter(version_lt='3.0', include_unversioned=False)"
+
+
+class TestMountedVersionFiltering:
+    """Tests for version filtering with mounted servers (FastMCPProvider).
+
+    Note: For mounted servers, list_* methods show what the child exposes (already
+    deduplicated to highest version). get_* methods support range filtering via
+    VersionSpec propagation to FastMCPProvider.
+    """
+
+    async def test_mounted_get_tool_with_range_filter(self):
+        """FastMCPProvider.get_tool applies range filtering from VersionSpec."""
+        from fastmcp.server.providers.fastmcp_provider import FastMCPProvider
+        from fastmcp.utilities.versions import VersionSpec
+
+        child = FastMCP("Child")
+
+        @child.tool(version="2.0")
+        def calc() -> int:
+            return 2
+
+        provider = FastMCPProvider(child)
+
+        # Without range spec, should return the tool
+        tool = await provider.get_tool("calc")
+        assert tool is not None
+        assert tool.version == "2.0"
+
+        # With range spec that excludes v2.0, should return None
+        tool = await provider.get_tool("calc", version=VersionSpec(lt="2.0"))
+        assert tool is None
+
+        # With range spec that includes v2.0, should return the tool
+        tool = await provider.get_tool("calc", version=VersionSpec(gte="2.0"))
+        assert tool is not None
+        assert tool.version == "2.0"
+
+    async def test_mounted_get_resource_with_range_filter(self):
+        """FastMCPProvider.get_resource applies range filtering from VersionSpec."""
+        from fastmcp.server.providers.fastmcp_provider import FastMCPProvider
+        from fastmcp.utilities.versions import VersionSpec
+
+        child = FastMCP("Child")
+
+        @child.resource("file://data/", version="2.0")
+        def data() -> str:
+            return "data"
+
+        provider = FastMCPProvider(child)
+
+        # Without range spec, should return the resource
+        resource = await provider.get_resource("file://data/")
+        assert resource is not None
+        assert resource.version == "2.0"
+
+        # With range spec that excludes v2.0, should return None
+        resource = await provider.get_resource(
+            "file://data/", version=VersionSpec(lt="2.0")
+        )
+        assert resource is None
+
+    async def test_mounted_get_prompt_with_range_filter(self):
+        """FastMCPProvider.get_prompt applies range filtering from VersionSpec."""
+        from fastmcp.server.providers.fastmcp_provider import FastMCPProvider
+        from fastmcp.utilities.versions import VersionSpec
+
+        child = FastMCP("Child")
+
+        @child.prompt(version="2.0")
+        def greet(name: str) -> str:
+            return f"Hello {name}"
+
+        provider = FastMCPProvider(child)
+
+        # Without range spec, should return the prompt
+        prompt = await provider.get_prompt("greet")
+        assert prompt is not None
+        assert prompt.version == "2.0"
+
+        # With range spec that excludes v2.0, should return None
+        prompt = await provider.get_prompt("greet", version=VersionSpec(lt="2.0"))
+        assert prompt is None
+
+    async def test_mounted_unversioned_passes_version_filter(self):
+        """Unversioned components in mounted servers pass through version filters."""
+        from fastmcp.server.transforms import VersionFilter
+
+        child = FastMCP("Child")
+
+        @child.tool
+        def unversioned_tool() -> str:
+            return "unversioned"
+
+        parent = FastMCP("Parent")
+        parent.mount(child, "child")
+        parent.add_transform(VersionFilter(version_lt="3.0"))
+
+        # Unversioned should pass through
+        tools = await parent.list_tools()
+        assert len(tools) == 1
+        assert tools[0].name == "child_unversioned_tool"
+        assert tools[0].version is None
+
+    async def test_mounted_include_unversioned_false_excludes_unversioned_tools(self):
+        """Mounted unversioned tools can be excluded with include_unversioned=False."""
+
+        child = FastMCP("Child")
+
+        @child.tool
+        def unversioned_tool() -> str:
+            return "unversioned"
+
+        @child.tool(version="2.0")
+        def included_versioned_tool() -> str:
+            return "versioned"
+
+        @child.tool(version="0.5")
+        def excluded_versioned_tool() -> str:
+            return "excluded-versioned"
+
+        parent = FastMCP("Parent")
+        parent.mount(child, "child")
+        parent.add_transform(
+            VersionFilter(version_gte="1.0", include_unversioned=False)
+        )
+
+        tools = await parent.list_tools()
+        assert [tool.name for tool in tools] == ["child_included_versioned_tool"]
+
+    async def test_version_filter_filters_out_high_mounted_version(self):
+        """VersionFilter hides mounted components outside the range."""
+        from fastmcp.server.transforms import VersionFilter
+
+        child = FastMCP("Child")
+
+        @child.tool(version="5.0")
+        def high_version_tool() -> int:
+            return 5
+
+        parent = FastMCP("Parent")
+        parent.mount(child, "child")
+        parent.add_transform(VersionFilter(version_lt="3.0"))
+
+        # v5.0 is outside the filter range, so it should be hidden
+        tools = await parent.list_tools()
+        assert len(tools) == 0
+
+        # get_tool should also return None (respects filter, applies transforms)
+        assert await parent.get_tool("child_high_version_tool") is None
+
+
+class TestMountedRangeFiltering:
+    """Tests for version range filtering with mounted servers."""
+
+    async def test_mounted_lower_version_selected_by_filter(self):
+        """When parent has filter <2.0 and child has v1.0+v3.0, should get v1.0."""
+        from fastmcp.server.transforms import VersionFilter
+
+        child = FastMCP("Child")
+
+        @child.tool(version="1.0")
+        def calc() -> int:
+            return 1
+
+        @child.tool(version="3.0")
+        def calc() -> int:
+            return 3
+
+        parent = FastMCP("Parent")
+        parent.mount(child, "child")
+        parent.add_transform(VersionFilter(version_lt="2.0"))
+
+        # Should return v1.0 (the highest version that matches <2.0)
+        # Use get_tool to apply transforms
+        tool = await parent.get_tool("child_calc")
+        assert tool is not None
+        assert tool.version == "1.0"
+
+    async def test_explicit_version_honored_within_filter_range(self):
+        """Explicit version="1.0" request should work within filter range."""
+        from fastmcp.server.transforms import VersionFilter
+
+        child = FastMCP("Child")
+
+        @child.tool(version="1.0")
+        def calc() -> int:
+            return 1
+
+        @child.tool(version="2.0")
+        def calc() -> int:
+            return 2
+
+        @child.tool(version="3.0")
+        def calc() -> int:
+            return 3
+
+        parent = FastMCP("Parent")
+        parent.mount(child, "child")
+        parent.add_transform(VersionFilter(version_gte="1.0", version_lt="3.0"))
+
+        # Request specific version within range (use get_tool to apply transforms)
+        tool = await parent.get_tool("child_calc", VersionSpec(eq="1.0"))
+        assert tool is not None
+        assert tool.version == "1.0"
+
+        # Request version outside range should return None
+        result = await parent.get_tool("child_calc", VersionSpec(eq="3.0"))
+        assert result is None
+
+
+class TestUnversionedExemption:
+    """Tests confirming unversioned components bypass version filters."""
+
+    async def test_unversioned_bypasses_version_filter(self):
+        """Unversioned components pass through any VersionFilter - by design."""
+        from fastmcp.server.transforms import VersionFilter
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def unversioned_tool() -> str:
+            return "unversioned"
+
+        @mcp.tool(version="5.0")
+        def versioned_tool() -> str:
+            return "v5"
+
+        # Filter that would exclude v5.0
+        mcp.add_transform(VersionFilter(version_lt="3.0"))
+
+        tools = await mcp.list_tools()
+        names = [t.name for t in tools]
+
+        # Unversioned passes through (exempt from filtering)
+        assert "unversioned_tool" in names
+        # Versioned is filtered out
+        assert "versioned_tool" not in names
+
+    async def test_unversioned_returned_for_exact_version_request(self):
+        """Requesting exact version of unversioned tool returns the tool."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def my_tool() -> str:
+            return "unversioned"
+
+        # Even with explicit version request, unversioned tool is returned
+        # (it's the only version that exists, and unversioned matches any spec)
+        tool = await mcp.get_tool("my_tool", VersionSpec(eq="1.0"))
+        assert tool is not None
+        assert tool.version is None
+
+    async def test_unversioned_matches_any_version_spec(self):
+        """VersionSpec.matches(None) returns True for any spec."""
+        from fastmcp.utilities.versions import VersionSpec
+
+        # Unversioned matches exact version specs
+        assert VersionSpec(eq="1.0").matches(None) is True
+
+        # Unversioned matches range specs
+        assert VersionSpec(gte="1.0", lt="3.0").matches(None) is True
+
+        # Unversioned matches open specs
+        assert VersionSpec(lt="5.0").matches(None) is True
+        assert VersionSpec(gte="1.0").matches(None) is True
diff --git a/tests/server/versioning/test_mounting.py b/tests/server/versioning/test_mounting.py
new file mode 100644
index 0000000..f0bea35
--- /dev/null
+++ b/tests/server/versioning/test_mounting.py
@@ -0,0 +1,343 @@
+"""Tests for versioning in mounted servers."""
+# ruff: noqa: F811  # Intentional function redefinition for version testing
+
+from __future__ import annotations
+
+from mcp_types import TextContent
+
+from fastmcp import FastMCP
+from fastmcp.utilities.versions import (
+    VersionSpec,
+)
+
+
+class TestVersionSorting:
+    """Tests for version sorting behavior."""
+
+    async def test_semantic_version_sorting(self):
+        """Versions should sort semantically, not lexicographically."""
+        mcp = FastMCP()
+
+        # Add versions out of order
+        @mcp.tool(version="1")
+        def count() -> int:
+            return 1
+
+        @mcp.tool(version="10")
+        def count() -> int:
+            return 10
+
+        @mcp.tool(version="2")
+        def count() -> int:
+            return 2
+
+        # list_tools returns all versions
+        tools = await mcp.list_tools()
+        assert len(tools) == 3
+        versions = {t.version for t in tools}
+        assert versions == {"1", "2", "10"}
+
+        # get_tool returns highest (semantic: 10 > 2 > 1)
+        tool = await mcp.get_tool("count")
+        assert tool is not None
+        assert tool.version == "10"
+
+        # call_tool uses highest version
+        result = await mcp.call_tool("count", {})
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "10"
+
+    async def test_semver_sorting(self):
+        """Full semver versions should sort correctly."""
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.2.3")
+        def info() -> str:
+            return "1.2.3"
+
+        @mcp.tool(version="1.2.10")
+        def info() -> str:
+            return "1.2.10"
+
+        @mcp.tool(version="1.10.1")
+        def info() -> str:
+            return "1.10.1"
+
+        # list_tools returns all versions
+        tools = await mcp.list_tools()
+        assert len(tools) == 3
+        versions = {t.version for t in tools}
+        assert versions == {"1.2.3", "1.2.10", "1.10.1"}
+
+        # get_tool returns highest: 1.10.1 > 1.2.10 > 1.2.3 (semantic)
+        tool = await mcp.get_tool("info")
+        assert tool is not None
+        assert tool.version == "1.10.1"
+
+    async def test_v_prefix_normalized(self):
+        """Versions with 'v' prefix should compare correctly."""
+        mcp = FastMCP()
+
+        @mcp.tool(version="v1.0")
+        def calc() -> int:
+            return 1
+
+        @mcp.tool(version="v2.0")
+        def calc() -> int:
+            return 2
+
+        # list_tools returns all versions
+        tools = await mcp.list_tools()
+        assert len(tools) == 2
+        versions = {t.version for t in tools}
+        assert versions == {"v1.0", "v2.0"}
+
+        # get_tool returns highest
+        tool = await mcp.get_tool("calc")
+        assert tool is not None
+        assert tool.version == "v2.0"
+
+
+class TestMountedServerVersioning:
+    """Tests for versioning in mounted servers (FastMCPProvider)."""
+
+    async def test_mounted_tool_preserves_version(self):
+        """Mounted tools should preserve their version info."""
+        child = FastMCP("Child")
+
+        @child.tool(version="2.0")
+        def add(x: int, y: int) -> int:
+            return x + y
+
+        parent = FastMCP("Parent")
+        parent.mount(child, "child")
+
+        tools = await parent.list_tools()
+        assert len(tools) == 1
+        assert tools[0].name == "child_add"
+        assert tools[0].version == "2.0"
+
+    async def test_mounted_resource_preserves_version(self):
+        """Mounted resources should preserve their version info."""
+        child = FastMCP("Child")
+
+        @child.resource("file:///config", version="1.5")
+        def config() -> str:
+            return "config data"
+
+        parent = FastMCP("Parent")
+        parent.mount(child, "child")
+
+        resources = await parent.list_resources()
+        assert len(resources) == 1
+        assert resources[0].version == "1.5"
+
+    async def test_mounted_prompt_preserves_version(self):
+        """Mounted prompts should preserve their version info."""
+        child = FastMCP("Child")
+
+        @child.prompt(version="3.0")
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        parent = FastMCP("Parent")
+        parent.mount(child, "child")
+
+        prompts = await parent.list_prompts()
+        assert len(prompts) == 1
+        assert prompts[0].name == "child_greet"
+        assert prompts[0].version == "3.0"
+
+    async def test_mounted_get_tool_with_version(self):
+        """Should be able to get specific version from mounted server."""
+        child = FastMCP("Child")
+
+        @child.tool(version="1.0")
+        def calc() -> int:
+            return 1
+
+        @child.tool(version="2.0")
+        def calc() -> int:
+            return 2
+
+        parent = FastMCP("Parent")
+        parent.mount(child, "child")
+
+        # Get highest version (default)
+        tool = await parent.get_tool("child_calc")
+        assert tool is not None
+        assert tool.version == "2.0"
+
+        # Get specific version
+        tool_v1 = await parent.get_tool("child_calc", VersionSpec(eq="1.0"))
+        assert tool_v1 is not None
+        assert tool_v1.version == "1.0"
+
+    async def test_mounted_multiple_versions_all_returned(self):
+        """Mounted server with multiple versions should show all versions."""
+        child = FastMCP("Child")
+
+        @child.tool(version="1.0")
+        def my_tool() -> str:
+            return "v1"
+
+        @child.tool(version="3.0")
+        def my_tool() -> str:
+            return "v3"
+
+        @child.tool(version="2.0")
+        def my_tool() -> str:
+            return "v2"
+
+        parent = FastMCP("Parent")
+        parent.mount(child, "child")
+
+        # list_tools returns all versions
+        tools = await parent.list_tools()
+        assert len(tools) == 3
+        versions = {t.version for t in tools}
+        assert versions == {"1.0", "2.0", "3.0"}
+
+        # get_tool returns highest
+        tool = await parent.get_tool("child_my_tool")
+        assert tool is not None
+        assert tool.version == "3.0"
+
+    async def test_mounted_call_tool_uses_highest_version(self):
+        """Calling mounted tool should use highest version."""
+        child = FastMCP("Child")
+
+        @child.tool(version="1.0")
+        def double(x: int) -> int:
+            return x * 2
+
+        @child.tool(version="2.0")
+        def double(x: int) -> int:
+            return x * 2 + 100  # Different behavior
+
+        parent = FastMCP("Parent")
+        parent.mount(child, "child")
+
+        result = await parent.call_tool("child_double", {"x": 5})
+        # Should use v2.0 which adds 100
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "110"
+
+    async def test_mounted_tool_wrapper_executes_correct_version(self):
+        """Calling a specific versioned tool wrapper should execute that version."""
+        child = FastMCP("Child")
+
+        @child.tool(version="1.0")
+        def calc(x: int) -> int:
+            return x * 10  # v1.0 multiplies by 10
+
+        @child.tool(version="2.0")
+        def calc(x: int) -> int:
+            return x * 100  # v2.0 multiplies by 100
+
+        parent = FastMCP("Parent")
+        parent.mount(child, "child")
+
+        # Get the v1.0 wrapper specifically
+        tools = await parent.list_tools()
+        v1_tool = next(
+            t for t in tools if t.name == "child_calc" and t.version == "1.0"
+        )
+
+        # Calling the v1.0 wrapper should execute v1.0's logic
+        result = await v1_tool.run({"x": 5})
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "50"  # 5 * 10, not 5 * 100
+
+    async def test_mounted_resource_wrapper_reads_correct_version(self):
+        """Reading a specific versioned resource should read that version."""
+        from fastmcp.utilities.versions import VersionSpec
+
+        child = FastMCP("Child")
+
+        @child.resource("data:///config", version="1.0")
+        def config_v1() -> str:
+            return "config-v1-content"
+
+        @child.resource("data:///config", version="2.0")
+        def config_v2() -> str:
+            return "config-v2-content"
+
+        parent = FastMCP("Parent")
+        parent.mount(child, "child")
+
+        # Reading with version=1.0 should read v1.0's content
+        result = await parent.read_resource(
+            "data://child//config", version=VersionSpec(eq="1.0")
+        )
+        assert result.contents[0].content == "config-v1-content"
+
+        # Reading with version=2.0 should read v2.0's content
+        result = await parent.read_resource(
+            "data://child//config", version=VersionSpec(eq="2.0")
+        )
+        assert result.contents[0].content == "config-v2-content"
+
+    async def test_mounted_prompt_wrapper_renders_correct_version(self):
+        """Rendering a specific versioned prompt should render that version."""
+        from fastmcp.utilities.versions import VersionSpec
+
+        child = FastMCP("Child")
+
+        @child.prompt(version="1.0")
+        def greeting(name: str) -> str:
+            return f"Hello, {name}!"  # v1.0 says Hello
+
+        @child.prompt(version="2.0")
+        def greeting(name: str) -> str:
+            return f"Greetings, {name}!"  # v2.0 says Greetings
+
+        parent = FastMCP("Parent")
+        parent.mount(child, "child")
+
+        # Rendering with version=1.0 should render v1.0's content
+        result = await parent.render_prompt(
+            "child_greeting", {"name": "World"}, version=VersionSpec(eq="1.0")
+        )
+        content = result.messages[0].content
+        assert isinstance(content, TextContent) and "Hello, World!" in content.text
+
+        # Rendering with version=2.0 should render v2.0's content
+        result = await parent.render_prompt(
+            "child_greeting", {"name": "World"}, version=VersionSpec(eq="2.0")
+        )
+        content = result.messages[0].content
+        assert isinstance(content, TextContent) and "Greetings, World!" in content.text
+
+    async def test_deeply_nested_version_forwarding(self):
+        """Verify version is correctly forwarded through multiple mount levels."""
+        level3 = FastMCP("Level3")
+
+        @level3.tool(version="1.0")
+        def calc(x: int) -> int:
+            return x * 10  # v1.0 multiplies by 10
+
+        @level3.tool(version="2.0")
+        def calc(x: int) -> int:
+            return x * 100  # v2.0 multiplies by 100
+
+        level2 = FastMCP("Level2")
+        level2.mount(level3, "l3")
+
+        level1 = FastMCP("Level1")
+        level1.mount(level2, "l2")
+
+        # All versions should be visible through two levels of mounting
+        tools = await level1.list_tools()
+        calc_tools = [t for t in tools if "calc" in t.name]
+        assert len(calc_tools) == 2
+        versions = {t.version for t in calc_tools}
+        assert versions == {"1.0", "2.0"}
+
+        # Get v1.0 wrapper through two levels of mounting
+        v1_tool = next(t for t in tools if "calc" in t.name and t.version == "1.0")
+
+        # Should execute v1.0 logic, not v2.0
+        result = await v1_tool.run({"x": 5})
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "50"  # 5 * 10, not 5 * 100
diff --git a/tests/server/versioning/test_versioning.py b/tests/server/versioning/test_versioning.py
new file mode 100644
index 0000000..3e2355a
--- /dev/null
+++ b/tests/server/versioning/test_versioning.py
@@ -0,0 +1,417 @@
+"""Core versioning functionality: VersionKey, utilities, and components."""
+# ruff: noqa: F811  # Intentional function redefinition for version testing
+
+from __future__ import annotations
+
+from typing import cast
+
+import pytest
+from mcp_types import TextContent
+
+from fastmcp import FastMCP
+from fastmcp.tools import Tool
+from fastmcp.utilities.versions import (
+    VersionKey,
+    VersionSpec,
+    compare_versions,
+    is_version_greater,
+    version_sort_key,
+)
+
+
+class TestVersionKey:
+    """Tests for VersionKey comparison class."""
+
+    def test_none_sorts_lowest(self):
+        """None (unversioned) should sort lower than any version."""
+        assert VersionKey(None) < VersionKey("1.0")
+        assert VersionKey(None) < VersionKey("0.1")
+        assert VersionKey(None) < VersionKey("anything")
+
+    def test_none_equals_none(self):
+        """Two None versions should be equal."""
+        assert VersionKey(None) == VersionKey(None)
+        assert not (VersionKey(None) < VersionKey(None))
+        assert not (VersionKey(None) > VersionKey(None))
+
+    def test_pep440_versions_compared_semantically(self):
+        """Valid PEP 440 versions should compare semantically."""
+        assert VersionKey("1.0") < VersionKey("2.0")
+        assert VersionKey("1.0") < VersionKey("1.1")
+        assert VersionKey("1.9") < VersionKey("1.10")  # Semantic, not string
+        assert VersionKey("2") < VersionKey("10")  # Semantic, not string
+
+    def test_v_prefix_stripped(self):
+        """Versions with 'v' prefix should be handled correctly."""
+        assert VersionKey("v1.0") == VersionKey("1.0")
+        assert VersionKey("v2.0") > VersionKey("v1.0")
+
+    def test_string_fallback_for_invalid_versions(self):
+        """Invalid PEP 440 versions should fall back to string comparison."""
+        # Dates are not valid PEP 440
+        assert VersionKey("2024-01-01") < VersionKey("2025-01-01")
+        # String comparison (lexicographic)
+        assert VersionKey("alpha") < VersionKey("beta")
+
+    def test_pep440_sorts_before_strings(self):
+        """PEP 440 versions sort before invalid string versions."""
+        # "1.0" is valid PEP 440, "not-semver" is not
+        assert VersionKey("1.0") < VersionKey("not-semver")
+        assert VersionKey("999.0") < VersionKey("aaa")  # PEP 440 < string
+
+    def test_repr(self):
+        """Test string representation."""
+        assert repr(VersionKey("1.0")) == "VersionKey('1.0')"
+        assert repr(VersionKey(None)) == "VersionKey(None)"
+
+
+class TestVersionFunctions:
+    """Tests for version comparison functions."""
+
+    def test_compare_versions(self):
+        """Test compare_versions function."""
+        assert compare_versions("1.0", "2.0") == -1
+        assert compare_versions("2.0", "1.0") == 1
+        assert compare_versions("1.0", "1.0") == 0
+        assert compare_versions(None, "1.0") == -1
+        assert compare_versions("1.0", None) == 1
+        assert compare_versions(None, None) == 0
+
+    def test_is_version_greater(self):
+        """Test is_version_greater function."""
+        assert is_version_greater("2.0", "1.0")
+        assert not is_version_greater("1.0", "2.0")
+        assert not is_version_greater("1.0", "1.0")
+        assert is_version_greater("1.0", None)
+        assert not is_version_greater(None, "1.0")
+
+
+def _tool(version: str | None) -> Tool:
+    """Build a real Tool component (a FastMCPComponent) with a version."""
+    return Tool.from_function(lambda: None, name="t", version=version)
+
+
+class TestVersionSpecEq:
+    """Tests for VersionSpec(eq=...) matching semantics."""
+
+    def test_exact_string_match(self):
+        assert VersionSpec(eq="1.0").matches("1.0")
+        assert not VersionSpec(eq="1.0").matches("2.0")
+
+    def test_v_prefix_insensitive_both_directions(self):
+        # Spec has v-prefix, component does not
+        assert VersionSpec(eq="v1.0").matches("1.0")
+        # Component has v-prefix, spec does not
+        assert VersionSpec(eq="1.0").matches("v1.0")
+        assert VersionSpec(eq="v2.3").matches("v2.3")
+
+    def test_pep440_equivalent_spellings_match(self):
+        """PEP 440 treats 1, 1.0, 1.0.0 as the same version."""
+        assert VersionSpec(eq="1.0").matches("1")
+        assert VersionSpec(eq="1").matches("1.0")
+        assert VersionSpec(eq="1.0").matches("1.0.0")
+        assert not VersionSpec(eq="1.0").matches("1.0.1")
+
+    def test_malformed_versions_use_exact_string_equality(self):
+        """Non-PEP 440 strings compare exactly (no normalization, no crash)."""
+        assert VersionSpec(eq="latest").matches("latest")
+        assert not VersionSpec(eq="latest").matches("LATEST")
+        assert VersionSpec(eq="2024-01-01").matches("2024-01-01")
+        assert not VersionSpec(eq="2024-01-01").matches("2024-01-02")
+
+    def test_eq_does_not_match_none_when_match_none_false(self):
+        assert VersionSpec(eq="1.0").matches(None, match_none=False) is False
+        assert VersionSpec(eq="1.0").matches(None, match_none=True) is True
+
+
+class TestVersionSelectionDeterminism:
+    """Selection among PEP 440-equivalent spellings must be deterministic.
+
+    Regression: previously `max(matching, key=version_sort_key)` returned the
+    first element on a tie, so registering both "1" and "1.0" made selection
+    depend on registration order. version_sort_key now has a raw tie-breaker.
+    """
+
+    def test_version_sort_key_is_total_ordering_tuple(self):
+        # PEP 440-equivalent but distinct spellings tie on VersionKey;
+        # the raw string breaks the tie deterministically.
+        k1 = version_sort_key(_tool("1"))
+        k10 = version_sort_key(_tool("1.0"))
+        assert k1[0] == k10[0]  # same VersionKey (PEP 440 equal)
+        assert k1 != k10  # but distinct sort keys
+        assert k10 > k1  # deterministic order ("1.0" > "1")
+
+    def test_unversioned_components_do_not_crash_tiebreak(self):
+        # Two unversioned components: raw tie-breaker is "" for both,
+        # must compare equal without raising (None < None would).
+        a = version_sort_key(_tool(None))
+        b = version_sort_key(_tool(None))
+        assert a == b
+
+    def test_distinct_versions_unaffected_by_tiebreak(self):
+        # Primary ordering still wins; raw tie-breaker never overrides it.
+        # "1.9" < "1.10" semantically even though "1.9" > "1.10" as strings.
+        k19 = version_sort_key(_tool("1.9"))
+        k110 = version_sort_key(_tool("1.10"))
+        assert k110 > k19
+
+    async def test_selection_is_registration_order_independent(self):
+        """End-to-end: registering two PEP 440-equivalent spellings of the
+        same tool must select the same one regardless of registration order
+        (exercises the real `max(..., key=version_sort_key)` selection path)."""
+
+        forward = FastMCP()
+
+        @forward.tool(name="add", version="1")
+        def add_a(x: int) -> int:
+            return x
+
+        @forward.tool(name="add", version="1.0")
+        def add_b(x: int) -> int:
+            return x
+
+        reverse = FastMCP()
+
+        @reverse.tool(name="add", version="1.0")
+        def add_c(x: int) -> int:
+            return x
+
+        @reverse.tool(name="add", version="1")
+        def add_d(x: int) -> int:
+            return x
+
+        fwd = await forward.get_tool("add")
+        rev = await reverse.get_tool("add")
+        assert fwd is not None and rev is not None
+        # Deterministic regardless of order (previously order-dependent).
+        assert fwd.version == rev.version == "1.0"
+
+
+class TestComponentVersioning:
+    """Tests for versioning in FastMCP components."""
+
+    async def test_tool_with_version(self):
+        """Tool version should be reflected in key."""
+        mcp = FastMCP()
+
+        @mcp.tool(version="2.0")
+        def my_tool(x: int) -> int:
+            return x * 2
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+        assert tools[0].name == "my_tool"
+        assert tools[0].version == "2.0"
+        assert tools[0].key == "tool:my_tool@2.0"
+
+    async def test_tool_without_version(self):
+        """Tool without version should have @ sentinel in key but empty version."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def my_tool(x: int) -> int:
+            return x * 2
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+        assert tools[0].version is None
+        # Keys always have @ sentinel for unambiguous parsing
+        assert tools[0].key == "tool:my_tool@"
+
+    async def test_tool_version_as_int(self):
+        """Tool version as int should be coerced to string."""
+        mcp = FastMCP()
+
+        @mcp.tool(version=2)
+        def my_tool(x: int) -> int:
+            return x * 2
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+        assert tools[0].version == "2"
+        assert tools[0].key == "tool:my_tool@2"
+
+    async def test_tool_version_zero_is_truthy(self):
+        """Version 0 should become "0" (truthy string), not empty."""
+        mcp = FastMCP()
+
+        @mcp.tool(version=0)
+        def my_tool(x: int) -> int:
+            return x * 2
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+        assert tools[0].version == "0"
+        assert tools[0].key == "tool:my_tool@0"  # Not "tool:my_tool@"
+
+    async def test_multiple_tool_versions_all_returned(self):
+        """list_tools returns all versions; get_tool returns highest."""
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0")
+        def add(x: int, y: int) -> int:
+            return x + y
+
+        @mcp.tool(version="2.0")
+        def add(x: int, y: int, z: int = 0) -> int:
+            return x + y + z
+
+        # list_tools returns all versions
+        tools = await mcp.list_tools()
+        assert len(tools) == 2
+        versions = {t.version for t in tools}
+        assert versions == {"1.0", "2.0"}
+
+        # get_tool returns highest version
+        tool = await mcp.get_tool("add")
+        assert tool is not None
+        assert tool.version == "2.0"
+
+    async def test_call_tool_invokes_highest_version(self):
+        """Calling a tool by name should invoke the highest version."""
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0")
+        def add(x: int, y: int) -> int:
+            return x + y
+
+        @mcp.tool(version="2.0")
+        def add(x: int, y: int) -> int:
+            return (x + y) * 10  # Different behavior to distinguish
+
+        result = await mcp.call_tool("add", {"x": 1, "y": 2})
+        # Should invoke v2.0 which multiplies by 10
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "30"
+
+    async def test_mixing_versioned_and_unversioned_rejected(self):
+        """Cannot mix versioned and unversioned tools with the same name."""
+        import pytest
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def my_tool() -> str:
+            return "unversioned"
+
+        # Adding versioned tool when unversioned exists should fail
+        with pytest.raises(ValueError, match="versioned.*unversioned"):
+
+            @mcp.tool(version="1.0")
+            def my_tool() -> str:
+                return "v1.0"
+
+    async def test_mixing_unversioned_after_versioned_rejected(self):
+        """Cannot add unversioned tool when versioned exists."""
+        import pytest
+
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0")
+        def my_tool() -> str:
+            return "v1.0"
+
+        # Adding unversioned tool when versioned exists should fail
+        with pytest.raises(ValueError, match="unversioned.*versioned"):
+
+            @mcp.tool
+            def my_tool() -> str:
+                return "unversioned"
+
+    async def test_resource_with_version(self):
+        """Resource version should work like tool version."""
+        mcp = FastMCP()
+
+        @mcp.resource("file:///config", version="1.0")
+        def config_v1() -> str:
+            return "config v1"
+
+        @mcp.resource("file:///config", version="2.0")
+        def config_v2() -> str:
+            return "config v2"
+
+        # list_resources returns all versions
+        resources = await mcp.list_resources()
+        assert len(resources) == 2
+        versions = {r.version for r in resources}
+        assert versions == {"1.0", "2.0"}
+
+        # get_resource returns highest version
+        resource = await mcp.get_resource("file:///config")
+        assert resource is not None
+        assert resource.version == "2.0"
+
+    async def test_prompt_with_version(self):
+        """Prompt version should work like tool version."""
+        mcp = FastMCP()
+
+        @mcp.prompt(version="1.0")
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        @mcp.prompt(version="2.0")
+        def greet(name: str) -> str:
+            return f"Greetings, {name}!"
+
+        # list_prompts returns all versions
+        prompts = await mcp.list_prompts()
+        assert len(prompts) == 2
+        versions = {p.version for p in prompts}
+        assert versions == {"1.0", "2.0"}
+
+        # get_prompt returns highest version
+        prompt = await mcp.get_prompt("greet")
+        assert prompt is not None
+        assert prompt.version == "2.0"
+
+
+class TestVersionValidation:
+    """Tests for version type validation in components and server."""
+
+    async def test_fastmcp_version_int_coerced(self):
+        """FastMCP(version=42) should coerce to string '42'."""
+        mcp = FastMCP(version=42)
+        assert mcp._mcp_server.version == "42"
+
+    async def test_fastmcp_version_float_coerced(self):
+        """FastMCP(version=1.5) should coerce to string."""
+        mcp = FastMCP(version=1.5)
+        assert mcp._mcp_server.version == "1.5"
+
+    async def test_tool_version_list_rejected(self):
+        """Tool with version=[1, 2] should raise TypeError."""
+        with pytest.raises(TypeError, match="Version must be a string"):
+            Tool(
+                name="t",
+                version=cast(str, [1, 2]),
+                parameters={"type": "object"},
+            )
+
+    async def test_tool_version_dict_rejected(self):
+        """Tool with version={'major': 1} should raise TypeError."""
+        with pytest.raises(TypeError, match="Version must be a string"):
+            Tool(
+                name="t",
+                version=cast(str, {"major": 1}),
+                parameters={"type": "object"},
+            )
+
+    async def test_fastmcp_version_list_rejected(self):
+        """FastMCP(version=[1, 2]) should raise TypeError."""
+        with pytest.raises(TypeError, match="Version must be a string"):
+            FastMCP(version=cast(str, [1, 2]))
+
+    async def test_fastmcp_version_dict_rejected(self):
+        """FastMCP(version={'v': 1}) should raise TypeError."""
+        with pytest.raises(TypeError, match="Version must be a string"):
+            FastMCP(version=cast(str, {"v": 1}))
+
+    async def test_fastmcp_version_true_rejected(self):
+        """FastMCP(version=True) should raise TypeError, not coerce to 'True'."""
+        with pytest.raises(TypeError, match="got bool"):
+            FastMCP(version=cast(str, True))
+
+    async def test_fastmcp_version_false_rejected(self):
+        """FastMCP(version=False) should raise TypeError, not coerce to 'False'."""
+        with pytest.raises(TypeError, match="got bool"):
+            FastMCP(version=cast(str, False))
diff --git a/tests/server/versioning/test_visibility_version_fallback.py b/tests/server/versioning/test_visibility_version_fallback.py
new file mode 100644
index 0000000..2511839
--- /dev/null
+++ b/tests/server/versioning/test_visibility_version_fallback.py
@@ -0,0 +1,376 @@
+"""Tests for version fallback when the highest version is disabled via visibility.
+
+Regression tests for https://github.com/jlowin/fastmcp/issues/3421:
+When the latest version of a component is disabled, get_* methods should
+fall back to the next-highest enabled version instead of returning None.
+"""
+# ruff: noqa: F811  # Intentional function redefinition for version testing
+
+from __future__ import annotations
+
+from mcp.server.auth.middleware.auth_context import auth_context_var
+from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser
+from mcp_types import TextContent
+
+from fastmcp import FastMCP
+from fastmcp.server.auth import AccessToken, require_scopes
+from fastmcp.utilities.versions import VersionSpec
+
+
+def _make_token(scopes: list[str] | None = None) -> AccessToken:
+    """Create a test access token."""
+    return AccessToken(
+        token="test-token",
+        client_id="test-client",
+        scopes=scopes or [],
+        expires_at=None,
+        claims={},
+    )
+
+
+def _set_token(token: AccessToken | None):
+    """Set the access token in the auth context var."""
+    if token is None:
+        return auth_context_var.set(None)
+    return auth_context_var.set(AuthenticatedUser(token))
+
+
+class TestToolVersionFallback:
+    """Test that disabling the latest tool version falls back correctly."""
+
+    async def test_list_tools_shows_v1_when_v2_disabled(self):
+        """list_tools should show v1 when v2 is disabled."""
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0")
+        def calc() -> int:
+            return 1
+
+        @mcp.tool(version="2.0")
+        def calc() -> int:
+            return 2
+
+        mcp.disable(version=VersionSpec(eq="2.0"))
+
+        tools = await mcp.list_tools()
+        assert len(tools) == 1
+        assert tools[0].name == "calc"
+        assert tools[0].version == "1.0"
+
+    async def test_get_tool_returns_v1_when_v2_disabled(self):
+        """get_tool should return v1 when v2 is disabled (core bug)."""
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0")
+        def calc() -> int:
+            return 1
+
+        @mcp.tool(version="2.0")
+        def calc() -> int:
+            return 2
+
+        mcp.disable(version=VersionSpec(eq="2.0"))
+
+        tool = await mcp.get_tool("calc")
+        assert tool is not None
+        assert tool.version == "1.0"
+
+    async def test_call_tool_uses_v1_when_v2_disabled(self):
+        """call_tool should invoke v1 when v2 is disabled."""
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0")
+        def calc() -> int:
+            return 1
+
+        @mcp.tool(version="2.0")
+        def calc() -> int:
+            return 2
+
+        mcp.disable(version=VersionSpec(eq="2.0"))
+
+        result = await mcp.call_tool("calc", {})
+        first = result.content[0]
+        assert isinstance(first, TextContent)
+        assert first.text == "1"
+
+    async def test_get_tool_explicit_disabled_version_returns_none(self):
+        """Requesting a specific disabled version should return None."""
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0")
+        def calc() -> int:
+            return 1
+
+        @mcp.tool(version="2.0")
+        def calc() -> int:
+            return 2
+
+        mcp.disable(version=VersionSpec(eq="2.0"))
+
+        tool = await mcp.get_tool("calc", VersionSpec(eq="2.0"))
+        assert tool is None
+
+    async def test_get_tool_all_versions_disabled_returns_none(self):
+        """When all versions are disabled, get_tool returns None."""
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0")
+        def calc() -> int:
+            return 1
+
+        @mcp.tool(version="2.0")
+        def calc() -> int:
+            return 2
+
+        mcp.disable(names={"calc"})
+
+        tool = await mcp.get_tool("calc")
+        assert tool is None
+
+    async def test_get_tool_middle_version_fallback(self):
+        """Disabling v3 should fall back to v2, not v1."""
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0")
+        def calc() -> int:
+            return 1
+
+        @mcp.tool(version="2.0")
+        def calc() -> int:
+            return 2
+
+        @mcp.tool(version="3.0")
+        def calc() -> int:
+            return 3
+
+        mcp.disable(version=VersionSpec(eq="3.0"))
+
+        tool = await mcp.get_tool("calc")
+        assert tool is not None
+        assert tool.version == "2.0"
+
+
+class TestResourceVersionFallback:
+    """Test that disabling the latest resource version falls back correctly."""
+
+    async def test_get_resource_returns_v1_when_v2_disabled(self):
+        """get_resource should return v1 when v2 is disabled."""
+        mcp = FastMCP()
+
+        @mcp.resource("data://info", version="1.0")
+        def info() -> str:
+            return "v1"
+
+        @mcp.resource("data://info", version="2.0")
+        def info() -> str:
+            return "v2"
+
+        mcp.disable(version=VersionSpec(eq="2.0"))
+
+        resource = await mcp.get_resource("data://info")
+        assert resource is not None
+        assert resource.version == "1.0"
+
+    async def test_get_resource_explicit_disabled_version_returns_none(self):
+        """Requesting a specific disabled resource version should return None."""
+        mcp = FastMCP()
+
+        @mcp.resource("data://info", version="1.0")
+        def info() -> str:
+            return "v1"
+
+        @mcp.resource("data://info", version="2.0")
+        def info() -> str:
+            return "v2"
+
+        mcp.disable(version=VersionSpec(eq="2.0"))
+
+        resource = await mcp.get_resource("data://info", VersionSpec(eq="2.0"))
+        assert resource is None
+
+
+class TestResourceTemplateVersionFallback:
+    """Test that disabling the latest template version falls back correctly."""
+
+    async def test_get_resource_template_returns_v1_when_v2_disabled(self):
+        """get_resource_template should return v1 when v2 is disabled."""
+        mcp = FastMCP()
+
+        @mcp.resource("data://items/{id}", version="1.0")
+        def item(id: str) -> str:
+            return f"v1-{id}"
+
+        @mcp.resource("data://items/{id}", version="2.0")
+        def item(id: str) -> str:
+            return f"v2-{id}"
+
+        mcp.disable(version=VersionSpec(eq="2.0"))
+
+        template = await mcp.get_resource_template("data://items/{id}")
+        assert template is not None
+        assert template.version == "1.0"
+
+
+class TestPromptVersionFallback:
+    """Test that disabling the latest prompt version falls back correctly."""
+
+    async def test_get_prompt_returns_v1_when_v2_disabled(self):
+        """get_prompt should return v1 when v2 is disabled."""
+        mcp = FastMCP()
+
+        @mcp.prompt(version="1.0")
+        def greet() -> str:
+            return "hello v1"
+
+        @mcp.prompt(version="2.0")
+        def greet() -> str:
+            return "hello v2"
+
+        mcp.disable(version=VersionSpec(eq="2.0"))
+
+        prompt = await mcp.get_prompt("greet")
+        assert prompt is not None
+        assert prompt.version == "1.0"
+
+    async def test_get_prompt_explicit_disabled_version_returns_none(self):
+        """Requesting a specific disabled prompt version should return None."""
+        mcp = FastMCP()
+
+        @mcp.prompt(version="1.0")
+        def greet() -> str:
+            return "hello v1"
+
+        @mcp.prompt(version="2.0")
+        def greet() -> str:
+            return "hello v2"
+
+        mcp.disable(version=VersionSpec(eq="2.0"))
+
+        prompt = await mcp.get_prompt("greet", VersionSpec(eq="2.0"))
+        assert prompt is None
+
+
+class TestFallbackRespectsAuth:
+    """Fallback to older versions must enforce auth checks.
+
+    When the highest version is disabled and the code falls back to older
+    versions, those candidates must go through auth filtering. Otherwise
+    a protected v1 could be exposed to unauthenticated users when a
+    public v2 is disabled.
+    """
+
+    async def test_tool_fallback_respects_auth(self):
+        """Disabling v2 should not expose auth-protected v1 to unauthorized users."""
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0", auth=require_scopes("admin"))
+        def calc() -> int:
+            return 1
+
+        @mcp.tool(version="2.0")
+        def calc() -> int:
+            return 2
+
+        mcp.disable(version=VersionSpec(eq="2.0"))
+
+        # Without an admin token, v1 should NOT be returned
+        tool = await mcp.get_tool("calc")
+        assert tool is None
+
+    async def test_tool_fallback_allows_authorized_user(self):
+        """Fallback should return auth-protected v1 to authorized users."""
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0", auth=require_scopes("admin"))
+        def calc() -> int:
+            return 1
+
+        @mcp.tool(version="2.0")
+        def calc() -> int:
+            return 2
+
+        mcp.disable(version=VersionSpec(eq="2.0"))
+
+        token = _make_token(scopes=["admin"])
+        tok = _set_token(token)
+        try:
+            tool = await mcp.get_tool("calc")
+            assert tool is not None
+            assert tool.version == "1.0"
+        finally:
+            auth_context_var.reset(tok)
+
+    async def test_resource_fallback_respects_auth(self):
+        """Disabling v2 should not expose auth-protected v1 resource."""
+        mcp = FastMCP()
+
+        @mcp.resource("data://info", version="1.0", auth=require_scopes("admin"))
+        def info() -> str:
+            return "v1"
+
+        @mcp.resource("data://info", version="2.0")
+        def info() -> str:
+            return "v2"
+
+        mcp.disable(version=VersionSpec(eq="2.0"))
+
+        resource = await mcp.get_resource("data://info")
+        assert resource is None
+
+    async def test_resource_template_fallback_respects_auth(self):
+        """Disabling v2 should not expose auth-protected v1 template."""
+        mcp = FastMCP()
+
+        @mcp.resource("data://items/{id}", version="1.0", auth=require_scopes("admin"))
+        def item(id: str) -> str:
+            return f"v1-{id}"
+
+        @mcp.resource("data://items/{id}", version="2.0")
+        def item(id: str) -> str:
+            return f"v2-{id}"
+
+        mcp.disable(version=VersionSpec(eq="2.0"))
+
+        template = await mcp.get_resource_template("data://items/{id}")
+        assert template is None
+
+    async def test_prompt_fallback_respects_auth(self):
+        """Disabling v2 should not expose auth-protected v1 prompt."""
+        mcp = FastMCP()
+
+        @mcp.prompt(version="1.0", auth=require_scopes("admin"))
+        def greet() -> str:
+            return "hello v1"
+
+        @mcp.prompt(version="2.0")
+        def greet() -> str:
+            return "hello v2"
+
+        mcp.disable(version=VersionSpec(eq="2.0"))
+
+        prompt = await mcp.get_prompt("greet")
+        assert prompt is None
+
+    async def test_fallback_skips_unauthorized_picks_next(self):
+        """When multiple fallback candidates exist, skip unauthorized ones."""
+        mcp = FastMCP()
+
+        @mcp.tool(version="1.0")
+        def calc() -> int:
+            return 1
+
+        @mcp.tool(version="2.0", auth=require_scopes("admin"))
+        def calc() -> int:
+            return 2
+
+        @mcp.tool(version="3.0")
+        def calc() -> int:
+            return 3
+
+        mcp.disable(version=VersionSpec(eq="3.0"))
+
+        # v2 requires admin, so unauthorized user should get v1
+        tool = await mcp.get_tool("calc")
+        assert tool is not None
+        assert tool.version == "1.0"
diff --git a/tests/telemetry/__init__.py b/tests/telemetry/__init__.py
new file mode 100644
index 0000000..11b900e
--- /dev/null
+++ b/tests/telemetry/__init__.py
@@ -0,0 +1 @@
+"""Tests for FastMCP telemetry module."""
diff --git a/tests/telemetry/test_module.py b/tests/telemetry/test_module.py
new file mode 100644
index 0000000..c760af5
--- /dev/null
+++ b/tests/telemetry/test_module.py
@@ -0,0 +1,83 @@
+"""Tests for the core telemetry module."""
+
+from __future__ import annotations
+
+from opentelemetry import trace
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+from fastmcp.server.telemetry import get_auth_span_attributes
+from fastmcp.telemetry import (
+    INSTRUMENTATION_NAME,
+    TRACE_PARENT_KEY,
+    extract_trace_context,
+    get_tracer,
+    inject_trace_context,
+)
+
+
+class TestGetTracer:
+    def test_tracer_uses_instrumentation_name(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        tracer = get_tracer()
+        with tracer.start_as_current_span("test-span"):
+            pass
+
+        spans = trace_exporter.get_finished_spans()
+        assert len(spans) == 1
+        scope = spans[0].instrumentation_scope
+        assert scope is not None
+        assert scope.name == INSTRUMENTATION_NAME
+
+
+class TestGetAuthSpanAttributes:
+    def test_returns_empty_dict_when_no_context(self):
+        attrs = get_auth_span_attributes()
+        assert attrs == {}
+
+
+VALID_TRACEPARENT = "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"
+VALID_TRACESTATE = "congo=t61rcWkgMzE"
+
+
+class TestInjectTraceContext:
+    def test_injects_bare_keys(self, trace_exporter: InMemorySpanExporter):
+        tracer = get_tracer()
+        with tracer.start_as_current_span("test"):
+            meta = inject_trace_context()
+
+        assert meta is not None
+        assert TRACE_PARENT_KEY in meta
+        assert meta[TRACE_PARENT_KEY].startswith("00-")
+
+
+class TestExtractTraceContext:
+    def test_bare_traceparent(self, trace_exporter: InMemorySpanExporter):
+        ctx = extract_trace_context({"traceparent": VALID_TRACEPARENT})
+        span_ctx = trace.get_current_span(ctx).get_span_context()
+        assert span_ctx.is_valid
+        assert format(span_ctx.trace_id, "032x") == "0af7651916cd43dd8448eb211c80319c"
+
+    def test_bare_tracestate(self, trace_exporter: InMemorySpanExporter):
+        ctx = extract_trace_context(
+            {
+                "traceparent": VALID_TRACEPARENT,
+                "tracestate": VALID_TRACESTATE,
+            }
+        )
+        span_ctx = trace.get_current_span(ctx).get_span_context()
+        assert span_ctx.is_valid
+        assert span_ctx.trace_state.get("congo") == "t61rcWkgMzE"
+
+    def test_none_meta_returns_current_context(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        ctx = extract_trace_context(None)
+        assert ctx is not None
+
+    def test_empty_meta_returns_current_context(
+        self, trace_exporter: InMemorySpanExporter
+    ):
+        ctx = extract_trace_context({})
+        span_ctx = trace.get_current_span(ctx).get_span_context()
+        assert not span_ctx.is_valid
diff --git a/tests/test_apps.py b/tests/test_apps.py
new file mode 100644
index 0000000..dac7276
--- /dev/null
+++ b/tests/test_apps.py
@@ -0,0 +1,738 @@
+"""Tests for MCP Apps Phase 1 — SDK compatibility.
+
+Covers app config models, tool/resource registration with ``app=``,
+extension negotiation, and the ``Context.client_supports_extension`` method.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+from mcp_types import (
+    ClientCapabilities,
+    Implementation,
+    InitializeRequestParams,
+)
+
+from fastmcp import Client, FastMCP
+from fastmcp.apps import (
+    UI_EXTENSION_ID,
+    UI_MIME_TYPE,
+    AppConfig,
+    ResourceCSP,
+    ResourcePermissions,
+    app_config_to_meta_dict,
+)
+from fastmcp.server.context import Context
+from fastmcp.server.low_level import client_supports_extension
+
+# ---------------------------------------------------------------------------
+# Model serialization
+# ---------------------------------------------------------------------------
+
+
+class TestAppConfig:
+    def test_serializes_with_aliases(self):
+        cfg = AppConfig(resource_uri="ui://my-app/view.html", visibility=["app"])
+        d = cfg.model_dump(by_alias=True, exclude_none=True)
+        assert d == {"resourceUri": "ui://my-app/view.html", "visibility": ["app"]}
+
+    def test_excludes_none_fields(self):
+        cfg = AppConfig(resource_uri="ui://foo")
+        d = cfg.model_dump(by_alias=True, exclude_none=True)
+        assert d == {"resourceUri": "ui://foo"}
+
+    def test_all_fields(self):
+        cfg = AppConfig(
+            resource_uri="ui://app",
+            visibility=["app", "model"],
+            csp=ResourceCSP(resource_domains=["https://cdn.example.com"]),
+            permissions=ResourcePermissions(camera={}, clipboard_write={}),
+            domain="example.com",
+            prefers_border=True,
+        )
+        d = cfg.model_dump(by_alias=True, exclude_none=True)
+        assert d == {
+            "resourceUri": "ui://app",
+            "visibility": ["app", "model"],
+            "csp": {"resourceDomains": ["https://cdn.example.com"]},
+            "permissions": {"camera": {}, "clipboardWrite": {}},
+            "domain": "example.com",
+            "prefersBorder": True,
+        }
+
+    def test_populate_by_name(self):
+        cfg = AppConfig(resource_uri="ui://app")
+        assert cfg.resource_uri == "ui://app"
+
+
+class TestResourceCSP:
+    def test_serializes_with_aliases(self):
+        csp = ResourceCSP(
+            connect_domains=["https://api.example.com"],
+            resource_domains=["https://cdn.example.com"],
+        )
+        d = csp.model_dump(by_alias=True, exclude_none=True)
+        assert d == {
+            "connectDomains": ["https://api.example.com"],
+            "resourceDomains": ["https://cdn.example.com"],
+        }
+
+    def test_excludes_none_fields(self):
+        csp = ResourceCSP(resource_domains=["https://unpkg.com"])
+        d = csp.model_dump(by_alias=True, exclude_none=True)
+        assert d == {"resourceDomains": ["https://unpkg.com"]}
+
+    def test_all_fields(self):
+        csp = ResourceCSP(
+            connect_domains=["https://api.example.com"],
+            resource_domains=["https://cdn.example.com"],
+            frame_domains=["https://embed.example.com"],
+            base_uri_domains=["https://base.example.com"],
+        )
+        d = csp.model_dump(by_alias=True, exclude_none=True)
+        assert d == {
+            "connectDomains": ["https://api.example.com"],
+            "resourceDomains": ["https://cdn.example.com"],
+            "frameDomains": ["https://embed.example.com"],
+            "baseUriDomains": ["https://base.example.com"],
+        }
+
+    def test_populate_by_name(self):
+        csp = ResourceCSP(connect_domains=["https://api.example.com"])
+        assert csp.connect_domains == ["https://api.example.com"]
+
+    def test_empty(self):
+        csp = ResourceCSP()
+        d = csp.model_dump(by_alias=True, exclude_none=True)
+        assert d == {}
+
+    def test_extra_fields_preserved(self):
+        """Unknown CSP directives from future spec versions pass through."""
+        csp = ResourceCSP(
+            resource_domains=["https://cdn.example.com"],
+            **{"workerDomains": ["https://worker.example.com"]},
+        )
+        d = csp.model_dump(by_alias=True, exclude_none=True)
+        assert d["resourceDomains"] == ["https://cdn.example.com"]
+        assert d["workerDomains"] == ["https://worker.example.com"]
+
+
+class TestResourcePermissions:
+    def test_serializes_with_aliases(self):
+        perms = ResourcePermissions(microphone={}, clipboard_write={})
+        d = perms.model_dump(by_alias=True, exclude_none=True)
+        assert d == {"microphone": {}, "clipboardWrite": {}}
+
+    def test_excludes_none_fields(self):
+        perms = ResourcePermissions(camera={})
+        d = perms.model_dump(by_alias=True, exclude_none=True)
+        assert d == {"camera": {}}
+
+    def test_all_fields(self):
+        perms = ResourcePermissions(
+            camera={}, microphone={}, geolocation={}, clipboard_write={}
+        )
+        d = perms.model_dump(by_alias=True, exclude_none=True)
+        assert d == {
+            "camera": {},
+            "microphone": {},
+            "geolocation": {},
+            "clipboardWrite": {},
+        }
+
+    def test_populate_by_name(self):
+        perms = ResourcePermissions(clipboard_write={})
+        assert perms.clipboard_write == {}
+
+    def test_extra_fields_preserved(self):
+        """Unknown permissions from future spec versions pass through."""
+        perms = ResourcePermissions(camera={}, **{"midi": {}})
+        d = perms.model_dump(by_alias=True, exclude_none=True)
+        assert d["camera"] == {}
+        assert d["midi"] == {}
+
+    def test_empty(self):
+        perms = ResourcePermissions()
+        d = perms.model_dump(by_alias=True, exclude_none=True)
+        assert d == {}
+
+
+class TestAppConfigForResources:
+    """AppConfig without resource_uri/visibility — for use on resources."""
+
+    def test_serializes_with_aliases(self):
+        cfg = AppConfig(
+            prefers_border=True,
+            csp=ResourceCSP(resource_domains=["https://cdn.example.com"]),
+        )
+        d = cfg.model_dump(by_alias=True, exclude_none=True)
+        assert d == {
+            "prefersBorder": True,
+            "csp": {"resourceDomains": ["https://cdn.example.com"]},
+        }
+
+    def test_excludes_none_fields(self):
+        cfg = AppConfig()
+        d = cfg.model_dump(by_alias=True, exclude_none=True)
+        assert d == {}
+
+    def test_with_permissions(self):
+        cfg = AppConfig(
+            permissions=ResourcePermissions(microphone={}, clipboard_write={}),
+        )
+        d = cfg.model_dump(by_alias=True, exclude_none=True)
+        assert d == {
+            "permissions": {"microphone": {}, "clipboardWrite": {}},
+        }
+
+
+class TestAppConfigToMetaDict:
+    def test_from_app_config_with_tool_fields(self):
+        cfg = AppConfig(resource_uri="ui://app", visibility=["app"])
+        result = app_config_to_meta_dict(cfg)
+        assert result["resourceUri"] == "ui://app"
+        assert result["visibility"] == ["app"]
+
+    def test_from_app_config_resource_fields_only(self):
+        cfg = AppConfig(prefers_border=False)
+        result = app_config_to_meta_dict(cfg)
+        assert result == {"prefersBorder": False}
+
+    def test_passthrough_for_dict(self):
+        raw: dict[str, Any] = {"resourceUri": "ui://app", "custom": "value"}
+        result = app_config_to_meta_dict(raw)
+        assert result is raw
+
+
+# ---------------------------------------------------------------------------
+# Tool registration with app=
+# ---------------------------------------------------------------------------
+
+
+class TestToolRegistrationWithApp:
+    async def test_app_config_model(self):
+        server = FastMCP("test")
+
+        @server.tool(app=AppConfig(resource_uri="ui://my-app/view.html"))
+        def my_tool() -> str:
+            return "hello"
+
+        tools = list(await server.list_tools())
+        assert len(tools) == 1
+        assert tools[0].meta is not None
+        assert tools[0].meta["ui"]["resourceUri"] == "ui://my-app/view.html"
+
+    async def test_app_dict(self):
+        server = FastMCP("test")
+
+        @server.tool(app={"resourceUri": "ui://foo", "visibility": ["app"]})
+        def my_tool() -> str:
+            return "hello"
+
+        # app-only tools declared directly on the server are looked up normally.
+        # Filtering them out is the responsibility of the host.
+        tools = list(await server.list_tools())
+        assert len(tools) == 1
+
+        tool = await server._get_tool("my_tool")
+        assert tool is not None
+        assert tool.meta is not None
+        assert tool.meta["ui"]["resourceUri"] == "ui://foo"
+        assert tool.meta["ui"]["visibility"] == ["app"]
+
+    async def test_app_merges_with_existing_meta(self):
+        server = FastMCP("test")
+
+        @server.tool(meta={"custom": "data"}, app=AppConfig(resource_uri="ui://app"))
+        def my_tool() -> str:
+            return "hello"
+
+        tools = list(await server.list_tools())
+        meta = tools[0].meta
+        assert meta is not None
+        assert meta["custom"] == "data"
+        assert meta["ui"]["resourceUri"] == "ui://app"
+
+    async def test_app_in_mcp_wire_format(self):
+        server = FastMCP("test")
+
+        @server.tool(app=AppConfig(resource_uri="ui://app", visibility=["app"]))
+        def my_tool() -> str:
+            return "hello"
+
+        tools = list(await server.list_tools())
+        assert len(tools) == 1
+
+        mcp_tool = tools[0].to_mcp_tool()
+        assert mcp_tool.meta is not None
+        assert mcp_tool.meta["ui"]["resourceUri"] == "ui://app"
+        assert mcp_tool.meta["ui"]["visibility"] == ["app"]
+
+    async def test_tool_without_app_has_no_ui_meta(self):
+        server = FastMCP("test")
+
+        @server.tool
+        def my_tool() -> str:
+            return "hello"
+
+        tools = list(await server.list_tools())
+        meta = tools[0].meta
+        assert meta is None or "ui" not in meta
+
+
+# ---------------------------------------------------------------------------
+# Resource registration with ui:// and app=
+# ---------------------------------------------------------------------------
+
+
+class TestResourceWithApp:
+    async def test_ui_scheme_defaults_mime_type(self):
+        server = FastMCP("test")
+
+        @server.resource("ui://my-app/view.html")
+        def app_html() -> str:
+            return "<html>hello</html>"
+
+        resources = list(await server.list_resources())
+        assert len(resources) == 1
+        assert resources[0].mime_type == UI_MIME_TYPE
+
+    async def test_explicit_mime_type_overrides_ui_default(self):
+        server = FastMCP("test")
+
+        @server.resource("ui://my-app/view.html", mime_type="text/html")
+        def app_html() -> str:
+            return "<html>hello</html>"
+
+        resources = list(await server.list_resources())
+        assert resources[0].mime_type == "text/html"
+
+    async def test_resource_app_metadata(self):
+        server = FastMCP("test")
+
+        @server.resource(
+            "ui://my-app/view.html",
+            app=AppConfig(prefers_border=True),
+        )
+        def app_html() -> str:
+            return "<html>hello</html>"
+
+        resources = list(await server.list_resources())
+        assert resources[0].meta is not None
+        assert resources[0].meta["ui"]["prefersBorder"] is True
+
+    async def test_non_ui_scheme_no_mime_default(self):
+        server = FastMCP("test")
+
+        @server.resource("resource://data")
+        def data() -> str:
+            return "data"
+
+        resources = list(await server.list_resources())
+        assert resources[0].mime_type != UI_MIME_TYPE
+
+    async def test_standalone_decorator_ui_scheme_defaults_mime_type(self):
+        """The standalone @resource decorator also applies ui:// MIME default."""
+        from fastmcp.resources import resource
+
+        @resource("ui://standalone-app/view.html")
+        def standalone_app() -> str:
+            return "<html>standalone</html>"
+
+        server = FastMCP("test")
+        server.add_resource(standalone_app)
+
+        resources = list(await server.list_resources())
+        assert len(resources) == 1
+        assert resources[0].mime_type == UI_MIME_TYPE
+
+    async def test_resource_template_ui_scheme_defaults_mime_type(self):
+        """Resource templates also apply ui:// MIME default."""
+        server = FastMCP("test")
+
+        @server.resource("ui://template-app/{view}")
+        def template_app(view: str) -> str:
+            return f"<html>{view}</html>"
+
+        templates = list(await server.list_resource_templates())
+        assert len(templates) == 1
+        assert templates[0].mime_type == UI_MIME_TYPE
+
+    async def test_resource_rejects_resource_uri(self):
+        """AppConfig with resource_uri raises ValueError on resources."""
+        server = FastMCP("test")
+        with pytest.raises(ValueError, match="resource_uri cannot be set on resources"):
+
+            @server.resource(
+                "ui://my-app/view.html",
+                app=AppConfig(resource_uri="ui://other"),
+            )
+            def app_html() -> str:
+                return "<html>hello</html>"
+
+    async def test_resource_rejects_visibility(self):
+        """AppConfig with visibility raises ValueError on resources."""
+        server = FastMCP("test")
+        with pytest.raises(ValueError, match="visibility cannot be set on resources"):
+
+            @server.resource(
+                "ui://my-app/view.html",
+                app=AppConfig(visibility=["app"]),
+            )
+            def app_html() -> str:
+                return "<html>hello</html>"
+
+
+# ---------------------------------------------------------------------------
+# Extension advertisement
+# ---------------------------------------------------------------------------
+
+
+class TestExtensionAdvertisement:
+    @pytest.mark.xfail(
+        reason="SDK v2 strips capabilities.extensions at the negotiated "
+        "(pre-2026) handshake version, so the SEP-2133 UI extension is not "
+        "advertised to the client (sdk-feedback #2).",
+        strict=True,
+    )
+    async def test_capabilities_include_ui_extension(self):
+        server = FastMCP("test")
+
+        @server.tool
+        def my_tool() -> str:
+            return "hello"
+
+        async with Client(server) as client:
+            init_result = client.initialize_result
+            extras = init_result.capabilities.model_extra or {}
+            extensions = extras.get("extensions", {})
+            assert UI_EXTENSION_ID in extensions
+
+    async def test_experimental_capabilities_in_initialize_result(self):
+        server = FastMCP(
+            "test",
+            experimental_capabilities={"file_exchange": {"version": "0.3"}},
+        )
+
+        async with Client(server) as client:
+            experimental = client.initialize_result.capabilities.experimental or {}
+            assert experimental.get("file_exchange") == {"version": "0.3"}
+
+    async def test_experimental_capabilities_default_empty(self):
+        server = FastMCP("test")
+
+        async with Client(server) as client:
+            experimental = client.initialize_result.capabilities.experimental
+            assert not experimental
+
+
+# ---------------------------------------------------------------------------
+# Context.client_supports_extension
+# ---------------------------------------------------------------------------
+
+
+class TestContextClientSupportsExtension:
+    async def test_returns_false_when_no_session(self):
+        server = FastMCP("test")
+        async with Context(fastmcp=server) as ctx:
+            assert ctx.client_supports_extension(UI_EXTENSION_ID) is False
+
+
+class TestClientSupportsExtension:
+    """Tests for the low-level ``client_supports_extension`` helper.
+
+    SDK v2 declares ``extensions`` as a real field on ``ClientCapabilities``, so
+    a client sending ``ClientCapabilities(extensions={...})`` populates the field
+    directly (``model_extra`` stays ``None``). The helper must read the real
+    field, not only ``model_extra``.
+    """
+
+    @staticmethod
+    def _session_with_capabilities(
+        capabilities: ClientCapabilities | None,
+    ) -> Any:
+        params: InitializeRequestParams | None = None
+        if capabilities is not None:
+            params = InitializeRequestParams(
+                protocol_version="2026-07-28",
+                capabilities=capabilities,
+                client_info=Implementation(name="test-client", version="1.0"),
+            )
+        return SimpleNamespace(client_params=params)
+
+    def test_real_extensions_field(self):
+        """A client that sets the real `extensions` field is detected."""
+        caps = ClientCapabilities(extensions={UI_EXTENSION_ID: {}})
+        # Guard: the regression this covers is the field being populated while
+        # model_extra stays empty.
+        assert caps.model_extra in (None, {})
+        session = self._session_with_capabilities(caps)
+        assert client_supports_extension(session, UI_EXTENSION_ID) is True
+
+    def test_real_extensions_field_without_target_extension(self):
+        caps = ClientCapabilities(extensions={"other/extension": {}})
+        session = self._session_with_capabilities(caps)
+        assert client_supports_extension(session, UI_EXTENSION_ID) is False
+
+    def test_legacy_model_extra_fallback(self):
+        """Defensive fallback: capabilities whose real `extensions` field is None
+        but which carry `extensions` in `model_extra` are still detected.
+
+        SDK v2 always routes `extensions` to the real field, so this branch is
+        only reachable by a capabilities object serialized under an older schema;
+        we exercise it with a stand-in that mimics that shape.
+        """
+        fake_caps = SimpleNamespace(
+            extensions=None,
+            model_extra={"extensions": {UI_EXTENSION_ID: {}}},
+        )
+        session: Any = SimpleNamespace(
+            client_params=SimpleNamespace(capabilities=fake_caps)
+        )
+        assert client_supports_extension(session, UI_EXTENSION_ID) is True
+
+    def test_no_extensions(self):
+        caps = ClientCapabilities()
+        session = self._session_with_capabilities(caps)
+        assert client_supports_extension(session, UI_EXTENSION_ID) is False
+
+    def test_no_capabilities(self):
+        session = self._session_with_capabilities(None)
+        assert client_supports_extension(session, UI_EXTENSION_ID) is False
+
+
+# ---------------------------------------------------------------------------
+# Integration — full client↔server round-trip
+# ---------------------------------------------------------------------------
+
+
+class TestIntegration:
+    async def test_tool_with_app_roundtrip(self):
+        """App metadata flows through to clients — no server-side stripping."""
+        server = FastMCP("test")
+
+        @server.tool(
+            app=AppConfig(
+                resource_uri="ui://app/view.html", visibility=["app", "model"]
+            )
+        )
+        async def my_tool() -> dict[str, str]:
+            return {"result": "ok"}
+
+        async with Client(server) as client:
+            tools = await client.list_tools()
+            assert len(tools) == 1
+            meta = tools[0].meta
+            assert meta is not None
+            assert meta["ui"]["resourceUri"] == "ui://app/view.html"
+            assert meta["ui"]["visibility"] == ["app", "model"]
+
+    async def test_resource_with_ui_scheme_roundtrip(self):
+        server = FastMCP("test")
+
+        @server.resource("ui://my-app/view.html")
+        def app_html() -> str:
+            return "<html><body>Hello</body></html>"
+
+        async with Client(server) as client:
+            resources = await client.list_resources()
+            assert len(resources) == 1
+            assert str(resources[0].uri) == "ui://my-app/view.html"
+            assert resources[0].mime_type == UI_MIME_TYPE
+
+    async def test_ui_resource_read_preserves_mime_type(self):
+        """Reading a ui:// resource returns content with the correct MIME type."""
+        server = FastMCP("test")
+
+        @server.resource("ui://my-app/view.html")
+        def app_html() -> str:
+            return "<html><body>Hello</body></html>"
+
+        async with Client(server) as client:
+            result = await client.read_resource_mcp("ui://my-app/view.html")
+            assert len(result.contents) == 1
+            assert result.contents[0].mime_type == UI_MIME_TYPE
+
+    async def test_app_tool_callable(self):
+        """A tool registered with app= is still callable normally."""
+        server = FastMCP("test")
+
+        @server.tool(app=AppConfig(resource_uri="ui://app"))
+        async def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        async with Client(server) as client:
+            result = await client.call_tool("greet", {"name": "Alice"})
+            assert any("Hello, Alice!" in str(c) for c in result.content)
+
+    async def test_app_backend_tool_callable(self):
+        """A tool registered with AppConfig(visibility=["app"]) is callable."""
+        server = FastMCP("test")
+
+        @server.tool(app=AppConfig(visibility=["app"]))
+        async def backend_greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        async with Client(server) as client:
+            result = await client.call_tool("backend_greet", {"name": "Alice"})
+            assert any("Hello, Alice!" in str(c) for c in result.content)
+
+    @pytest.mark.xfail(
+        reason="SDK v2 strips capabilities.extensions at the negotiated "
+        "(pre-2026) handshake version, so the SEP-2133 UI extension is not "
+        "advertised to the client (sdk-feedback #2).",
+        strict=True,
+    )
+    async def test_extension_and_tool_together(self):
+        """Server advertises extension AND tool has app meta."""
+        server = FastMCP("test")
+
+        @server.tool(
+            app=AppConfig(resource_uri="ui://dashboard", visibility=["app", "model"])
+        )
+        def dashboard() -> str:
+            return "data"
+
+        tools = list(await server.list_tools())
+        assert tools[0].meta is not None
+        assert tools[0].meta["ui"]["resourceUri"] == "ui://dashboard"
+
+        async with Client(server) as client:
+            extras = client.initialize_result.capabilities.model_extra or {}
+            assert UI_EXTENSION_ID in extras.get("extensions", {})
+
+    async def test_csp_and_permissions_roundtrip(self):
+        """CSP and permissions metadata flows through to clients correctly."""
+        server = FastMCP("test")
+
+        @server.resource(
+            "ui://secure-app/view.html",
+            app=AppConfig(
+                csp=ResourceCSP(
+                    resource_domains=["https://unpkg.com"],
+                    connect_domains=["https://api.example.com"],
+                ),
+                permissions=ResourcePermissions(microphone={}, clipboard_write={}),
+            ),
+        )
+        def secure_app() -> str:
+            return "<html>secure</html>"
+
+        @server.tool(
+            app=AppConfig(
+                resource_uri="ui://secure-app/view.html",
+                csp=ResourceCSP(resource_domains=["https://cdn.example.com"]),
+                permissions=ResourcePermissions(camera={}),
+            )
+        )
+        def secure_tool() -> str:
+            return "result"
+
+        async with Client(server) as client:
+            # Verify resource metadata
+            resources = await client.list_resources()
+            assert len(resources) == 1
+            meta = resources[0].meta
+            assert meta is not None
+            assert meta["ui"]["csp"]["resourceDomains"] == ["https://unpkg.com"]
+            assert meta["ui"]["csp"]["connectDomains"] == ["https://api.example.com"]
+            assert meta["ui"]["permissions"]["microphone"] == {}
+            assert meta["ui"]["permissions"]["clipboardWrite"] == {}
+
+            # Verify tool metadata
+            tools = await client.list_tools()
+            assert len(tools) == 1
+            tool_meta = tools[0].meta
+            assert tool_meta is not None
+            assert tool_meta["ui"]["csp"]["resourceDomains"] == [
+                "https://cdn.example.com"
+            ]
+            assert tool_meta["ui"]["permissions"]["camera"] == {}
+
+    async def test_resource_read_propagates_meta_to_content_items(self):
+        """resources/read must include _meta on content items so hosts can read CSP."""
+        server = FastMCP("test")
+
+        @server.resource(
+            "ui://csp-app/view.html",
+            app=AppConfig(
+                csp=ResourceCSP(resource_domains=["https://unpkg.com"]),
+            ),
+        )
+        def app_view() -> str:
+            return "<html>app</html>"
+
+        async with Client(server) as client:
+            read_result = await client.read_resource_mcp("ui://csp-app/view.html")
+            content_item = read_result.contents[0]
+            assert content_item.meta is not None
+            assert content_item.meta["ui"]["csp"]["resourceDomains"] == [
+                "https://unpkg.com"
+            ]
+
+
+# ---------------------------------------------------------------------------
+# PrefabAppConfig
+# ---------------------------------------------------------------------------
+
+
+class TestPrefabAppConfig:
+    def test_default_sets_renderer_uri(self):
+        from fastmcp.apps import PrefabAppConfig
+
+        config = PrefabAppConfig()
+        assert config.resource_uri == "ui://prefab/renderer.html"
+
+    def test_merges_renderer_csp_with_user_csp(self):
+        from fastmcp.apps import PrefabAppConfig
+
+        config = PrefabAppConfig(
+            csp=ResourceCSP(frame_domains=["https://example.com"]),
+        )
+        assert config.resource_uri == "ui://prefab/renderer.html"
+        assert config.csp is not None
+        assert config.csp.frame_domains == ["https://example.com"]
+
+    async def test_auto_synthesizes_renderer_resource(self):
+        """Each prefab tool gets a per-tool renderer resource on demand."""
+        from fastmcp.apps import PrefabAppConfig
+
+        server = FastMCP("test")
+
+        @server.tool(app=PrefabAppConfig())
+        def my_tool() -> str:
+            return "hello"
+
+        resources = list(await server.list_resources())
+        prefab = [r for r in resources if "prefab/tool" in str(r.uri)]
+        assert len(prefab) == 1
+
+    async def test_equivalent_to_app_true(self):
+        """PrefabAppConfig() and app=True both synthesize a per-tool renderer."""
+        from fastmcp.apps import PrefabAppConfig
+
+        server1 = FastMCP("test1")
+        server2 = FastMCP("test2")
+
+        @server1.tool(app=True)
+        def tool_a() -> str:
+            return "a"
+
+        @server2.tool(app=PrefabAppConfig())
+        def tool_b() -> str:
+            return "b"
+
+        tools1 = list(await server1.list_tools())
+        tools2 = list(await server2.list_tools())
+
+        assert tools1[0].meta is not None
+        ui1 = tools1[0].meta.get("ui", {})
+        assert tools2[0].meta is not None
+        ui2 = tools2[0].meta.get("ui", {})
+
+        # Both produce per-tool URIs in the prefab/tool/<hash>/ form.
+        assert ui1.get("resourceUri", "").startswith("ui://prefab/tool/")
+        assert ui2.get("resourceUri", "").startswith("ui://prefab/tool/")
diff --git a/tests/test_apps_prefab.py b/tests/test_apps_prefab.py
new file mode 100644
index 0000000..f864ab7
--- /dev/null
+++ b/tests/test_apps_prefab.py
@@ -0,0 +1,452 @@
+"""Tests for MCP Apps Phase 2 — Prefab integration.
+
+Covers ``convert_result`` for PrefabApp/Component, ``app=True`` auto-wiring,
+return-type inference, output-schema suppression, and end-to-end round trips.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from mcp_types import TextContent
+from prefab_ui.app import PROTOCOL_VERSION, PrefabApp
+from prefab_ui.components import Column, Heading, Text
+from prefab_ui.components.base import Component
+
+from fastmcp import Client, FastMCP
+from fastmcp.apps import UI_MIME_TYPE, AppConfig
+from fastmcp.resources.types import TextResource
+from fastmcp.server.providers.local_provider.decorators.tools import (
+    PREFAB_RENDERER_URI,
+)
+from fastmcp.tools.base import Tool, ToolResult
+
+# ---------------------------------------------------------------------------
+# convert_result
+# ---------------------------------------------------------------------------
+
+
+class TestConvertResult:
+    def test_prefab_app(self):
+        with Column() as view:
+            Heading("Hello")
+        app = PrefabApp(view=view, state={"name": "Alice"})
+
+        tool = Tool(name="t", parameters={})
+        result = tool.convert_result(app)
+
+        assert isinstance(result, ToolResult)
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "[Rendered Prefab UI]"
+        assert result.structured_content is not None
+        assert result.structured_content["$prefab"]["version"] == PROTOCOL_VERSION
+        assert result.structured_content["state"] == {"name": "Alice"}
+        # PrefabApp wraps view in a pf-app-root Div
+        root = result.structured_content["view"]
+        assert root["type"] == "Div"
+        assert root["cssClass"] == "pf-app-root"
+        assert root["children"][0]["type"] == "Column"
+
+    def test_bare_component(self):
+        heading = Heading("World")
+
+        tool = Tool(name="t", parameters={})
+        result = tool.convert_result(heading)
+
+        assert isinstance(result, ToolResult)
+        assert result.structured_content is not None
+        assert result.structured_content["$prefab"]["version"] == PROTOCOL_VERSION
+        assert result.structured_content["view"]["type"] == "Div"
+        assert result.structured_content["view"]["children"][0]["type"] == "Heading"
+
+    def test_tool_result_with_prefab_structured_content(self):
+        """ToolResult with PrefabApp as structured_content preserves custom text."""
+        app = PrefabApp(view=Heading("Hello"), state={"x": 1})
+
+        tool = Tool(name="t", parameters={})
+        result = tool.convert_result(
+            ToolResult(content="Custom fallback text", structured_content=app)
+        )
+
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "Custom fallback text"
+        assert result.structured_content is not None
+        assert result.structured_content["$prefab"]["version"] == PROTOCOL_VERSION
+        assert result.structured_content["view"]["type"] == "Div"
+        assert result.structured_content["view"]["children"][0]["type"] == "Heading"
+
+    def test_tool_result_with_component_structured_content(self):
+        """ToolResult with bare Component as structured_content."""
+        tool = Tool(name="t", parameters={})
+        result = tool.convert_result(
+            ToolResult(content="My text", structured_content=Heading("Hi"))
+        )
+
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "My text"
+        assert result.structured_content is not None
+        assert result.structured_content["$prefab"]["version"] == PROTOCOL_VERSION
+        assert result.structured_content["view"]["type"] == "Div"
+        assert result.structured_content["view"]["children"][0]["type"] == "Heading"
+
+    def test_tool_result_passthrough(self):
+        """ToolResult without prefab structured_content passes through unchanged."""
+        original = ToolResult(content="hello")
+        tool = Tool(name="t", parameters={})
+        assert tool.convert_result(original) is original
+
+
+# ---------------------------------------------------------------------------
+# app=True auto-wiring
+# ---------------------------------------------------------------------------
+
+
+class TestAppTrue:
+    def test_app_true_sets_meta(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool(app=True)
+        def my_tool() -> str:
+            return "hello"
+
+        tools = mcp._local_provider._components
+        tool = next(
+            v
+            for v in tools.values()
+            if hasattr(v, "parameters") and v.name == "my_tool"
+        )
+        assert tool.meta is not None
+        assert "ui" in tool.meta
+        assert tool.meta["ui"]["resourceUri"] == PREFAB_RENDERER_URI
+
+    async def test_app_true_synthesizes_renderer_resource(self):
+        """Each prefab tool gets a per-tool renderer resource synthesized
+        on demand at list_resources time. Resources don't live on any
+        provider's storage — they're computed from the registry walk."""
+        mcp = FastMCP("test")
+
+        @mcp.tool(app=True)
+        def my_tool() -> str:
+            return "hello"
+
+        resources = list(await mcp.list_resources())
+        prefab_resources = [r for r in resources if "prefab/tool" in str(r.uri)]
+        assert len(prefab_resources) == 1
+        assert "renderer.html" in str(prefab_resources[0].uri)
+
+    async def test_renderer_resource_has_correct_mime_type(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool(app=True)
+        def my_tool() -> str:
+            return "hello"
+
+        resources = list(await mcp.list_resources())
+        renderer = next(r for r in resources if "prefab/tool" in str(r.uri))
+        assert isinstance(renderer, TextResource)
+        assert renderer.mime_type == UI_MIME_TYPE
+
+    async def test_renderer_resource_has_csp(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool(app=True)
+        def my_tool() -> str:
+            return "hello"
+
+        resources = list(await mcp.list_resources())
+        renderer = next(r for r in resources if "prefab/tool" in str(r.uri))
+        assert renderer.meta is not None
+        assert "ui" in renderer.meta
+        assert "csp" in renderer.meta["ui"]
+
+    async def test_multiple_tools_get_dedicated_resources(self):
+        """Each prefab tool gets its own resource at a distinct hashed
+        URI — no shared singleton, so per-tool CSP becomes possible."""
+        mcp = FastMCP("test")
+
+        @mcp.tool(app=True)
+        def tool_a() -> str:
+            return "a"
+
+        @mcp.tool(app=True)
+        def tool_b() -> str:
+            return "b"
+
+        resources = list(await mcp.list_resources())
+        prefab_uris = {str(r.uri) for r in resources if "prefab/tool" in str(r.uri)}
+        assert len(prefab_uris) == 2
+
+    def test_explicit_app_config_not_overridden(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool(app=AppConfig(resource_uri="ui://custom/app.html"))
+        def my_tool() -> PrefabApp:
+            return PrefabApp(view=Heading("hi"))
+
+        tools = mcp._local_provider._components
+        tool = next(
+            v
+            for v in tools.values()
+            if hasattr(v, "parameters") and v.name == "my_tool"
+        )
+        assert tool.meta is not None
+        assert tool.meta["ui"]["resourceUri"] == "ui://custom/app.html"
+
+
+# ---------------------------------------------------------------------------
+# Return type inference
+# ---------------------------------------------------------------------------
+
+
+class TestInference:
+    def test_prefab_app_annotation_inferred(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def my_tool() -> PrefabApp:
+            return PrefabApp(view=Heading("hi"))
+
+        tools = mcp._local_provider._components
+        tool = next(
+            v
+            for v in tools.values()
+            if hasattr(v, "parameters") and v.name == "my_tool"
+        )
+        assert tool.meta is not None
+        assert tool.meta["ui"]["resourceUri"] == PREFAB_RENDERER_URI
+
+    def test_component_annotation_inferred(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def my_tool() -> Component:
+            return Heading("hi")
+
+        tools = mcp._local_provider._components
+        tool = next(
+            v
+            for v in tools.values()
+            if hasattr(v, "parameters") and v.name == "my_tool"
+        )
+        assert tool.meta is not None
+        assert tool.meta["ui"]["resourceUri"] == PREFAB_RENDERER_URI
+
+    def test_no_annotation_no_inference(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def my_tool():
+            return "hello"
+
+        tools = mcp._local_provider._components
+        tool = next(
+            v
+            for v in tools.values()
+            if hasattr(v, "parameters") and v.name == "my_tool"
+        )
+        assert tool.meta is None or "ui" not in (tool.meta or {})
+
+    def test_non_prefab_annotation_no_inference(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def my_tool() -> str:
+            return "hello"
+
+        tools = mcp._local_provider._components
+        tool = next(
+            v
+            for v in tools.values()
+            if hasattr(v, "parameters") and v.name == "my_tool"
+        )
+        assert tool.meta is None or "ui" not in (tool.meta or {})
+
+    def test_optional_prefab_app_inferred(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def my_tool() -> PrefabApp | None:
+            return None
+
+        tools = mcp._local_provider._components
+        tool = next(
+            v
+            for v in tools.values()
+            if hasattr(v, "parameters") and v.name == "my_tool"
+        )
+        assert tool.meta is not None
+        assert tool.meta["ui"]["resourceUri"] == PREFAB_RENDERER_URI
+
+    def test_annotated_prefab_app_inferred(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def my_tool() -> Annotated[PrefabApp | None, "some metadata"]:
+            return None
+
+        tools = mcp._local_provider._components
+        tool = next(
+            v
+            for v in tools.values()
+            if hasattr(v, "parameters") and v.name == "my_tool"
+        )
+        assert tool.meta is not None
+        assert tool.meta["ui"]["resourceUri"] == PREFAB_RENDERER_URI
+
+    def test_component_subclass_union_inferred(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def my_tool() -> Column | None:
+            return None
+
+        tools = mcp._local_provider._components
+        tool = next(
+            v
+            for v in tools.values()
+            if hasattr(v, "parameters") and v.name == "my_tool"
+        )
+        assert tool.meta is not None
+        assert tool.meta["ui"]["resourceUri"] == PREFAB_RENDERER_URI
+
+
+# ---------------------------------------------------------------------------
+# Output schema suppression
+# ---------------------------------------------------------------------------
+
+
+class TestOutputSchema:
+    def test_prefab_app_return_no_output_schema(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def my_tool() -> PrefabApp:
+            return PrefabApp(view=Heading("hi"))
+
+        tools = mcp._local_provider._components
+        tool: Tool = next(
+            v for v in tools.values() if isinstance(v, Tool) and v.name == "my_tool"
+        )
+        assert tool.output_schema is None
+
+    def test_component_return_no_output_schema(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def my_tool() -> Column:
+            with Column() as view:
+                Heading("hi")
+            return view
+
+        tools = mcp._local_provider._components
+        tool: Tool = next(
+            v for v in tools.values() if isinstance(v, Tool) and v.name == "my_tool"
+        )
+        assert tool.output_schema is None
+
+    def test_optional_component_no_output_schema(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def my_tool() -> Column | None:
+            return None
+
+        tools = mcp._local_provider._components
+        tool: Tool = next(
+            v for v in tools.values() if isinstance(v, Tool) and v.name == "my_tool"
+        )
+        assert tool.output_schema is None
+
+    def test_annotated_prefab_app_no_output_schema(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def my_tool() -> Annotated[PrefabApp | None, "metadata"]:
+            return None
+
+        tools = mcp._local_provider._components
+        tool: Tool = next(
+            v for v in tools.values() if isinstance(v, Tool) and v.name == "my_tool"
+        )
+        assert tool.output_schema is None
+
+
+# ---------------------------------------------------------------------------
+# Integration — client-server round trip
+# ---------------------------------------------------------------------------
+
+
+class TestIntegration:
+    async def test_tool_call_returns_prefab_structured_content(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool(app=True)
+        def greet(name: str) -> PrefabApp:
+            with Column() as view:
+                Heading("Hello")
+                Text(f"Welcome, {name}!")
+            return PrefabApp(view=view, state={"name": name})
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("greet", {"name": "Alice"})
+
+        assert result.structured_content is not None
+        assert result.structured_content["$prefab"]["version"] == PROTOCOL_VERSION
+        assert result.structured_content["state"] == {"name": "Alice"}
+
+    async def test_tool_call_with_custom_text(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool(app=True)
+        def greet(name: str) -> ToolResult:
+            app = PrefabApp(view=Heading(f"Hello {name}"))
+            return ToolResult(
+                content=f"Greeting for {name}",
+                structured_content=app,
+            )
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("greet", {"name": "Alice"})
+
+        assert any(
+            "Greeting for Alice" in c.text for c in result.content if hasattr(c, "text")
+        )
+        assert result.structured_content is not None
+        assert result.structured_content["$prefab"]["version"] == PROTOCOL_VERSION
+
+    async def test_tools_list_includes_app_meta(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool(app=True)
+        def my_tool() -> PrefabApp:
+            return PrefabApp(view=Heading("hi"))
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+
+        tool = next(t for t in tools if t.name == "my_tool")
+        meta = tool.meta or {}
+        assert "ui" in meta
+        # URI is the per-tool hashed form, not the singleton.
+        assert meta["ui"]["resourceUri"].startswith("ui://prefab/tool/")
+        assert meta["ui"]["resourceUri"].endswith("/renderer.html")
+
+    async def test_renderer_resource_readable(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool(app=True)
+        def my_tool() -> str:
+            return "hello"
+
+        async with Client(mcp) as client:
+            # Look up the URI by listing first — the hash isn't
+            # computable from outside without the address registry.
+            tools = await client.list_tools()
+            uri = next(t for t in tools if t.name == "my_tool").meta["ui"][
+                "resourceUri"
+            ]
+            contents = await client.read_resource(uri)
+
+        assert len(contents) > 0
+        text = contents[0].text if hasattr(contents[0], "text") else ""
+        assert "<html" in text.lower() or "<!doctype" in text.lower()
diff --git a/tests/test_compat.py b/tests/test_compat.py
new file mode 100644
index 0000000..bb2c123
--- /dev/null
+++ b/tests/test_compat.py
@@ -0,0 +1,243 @@
+"""Tests for the MCP SDK v2 camelCase compatibility bridge (fastmcp._compat)."""
+
+import datetime
+import warnings
+
+import mcp_types
+import pytest
+from mcp import MCPError as SDKMCPError
+
+import fastmcp
+import fastmcp._compat as _compat
+from fastmcp import Client, FastMCP
+from fastmcp.client.transports import FastMCPTransport
+from fastmcp.exceptions import FastMCPDeprecationWarning, MCPError, McpError
+
+
+def _reset_warn_once() -> None:
+    """Reinstall the shims so every property's warn-once flag starts fresh.
+
+    Each bridged property closes over its own `warned` flag which persists for
+    the life of the process. Rebuilding the properties gives tests a clean slate
+    without leaking warning state across tests.
+    """
+    for cls, mapping in _compat._ALIASES.items():
+        for camel in mapping:
+            attr = cls.__dict__.get(camel)
+            if isinstance(attr, property):
+                delattr(cls, camel)
+    _compat._installed = False
+    _compat.install()
+
+
+@pytest.fixture(autouse=True)
+def fresh_shims():
+    _reset_warn_once()
+    yield
+
+
+class TestCamelCaseBridge:
+    def test_tool_input_schema_bridged(self):
+        tool = mcp_types.Tool(name="t", input_schema={"type": "object"})
+        with pytest.warns(FastMCPDeprecationWarning):
+            assert tool.inputSchema == {"type": "object"}  # ty: ignore[unresolved-attribute]
+
+    def test_tool_output_schema_bridged(self):
+        tool = mcp_types.Tool(
+            name="t",
+            input_schema={"type": "object"},
+            output_schema={"type": "string"},
+        )
+        with pytest.warns(FastMCPDeprecationWarning):
+            assert tool.outputSchema == {"type": "string"}  # ty: ignore[unresolved-attribute]
+
+    def test_call_tool_result_is_error_bridged(self):
+        result = mcp_types.CallToolResult(content=[], is_error=True)
+        with pytest.warns(FastMCPDeprecationWarning):
+            assert result.isError is True  # ty: ignore[unresolved-attribute]
+
+    def test_call_tool_result_structured_content_bridged(self):
+        result = mcp_types.CallToolResult(content=[], structured_content={"a": 1})
+        with pytest.warns(FastMCPDeprecationWarning):
+            assert result.structuredContent == {"a": 1}  # ty: ignore[unresolved-attribute]
+
+    def test_resource_mime_type_bridged(self):
+        resource = mcp_types.Resource(name="r", uri="file:///x", mime_type="text/plain")
+        with pytest.warns(FastMCPDeprecationWarning):
+            assert resource.mimeType == "text/plain"  # ty: ignore[unresolved-attribute]
+
+    def test_resource_template_uri_template_bridged(self):
+        template = mcp_types.ResourceTemplate(name="rt", uri_template="file:///{id}")
+        with pytest.warns(FastMCPDeprecationWarning):
+            assert template.uriTemplate == "file:///{id}"  # ty: ignore[unresolved-attribute]
+
+    def test_completion_has_more_bridged(self):
+        completion = mcp_types.Completion(values=["a"], has_more=True)
+        with pytest.warns(FastMCPDeprecationWarning):
+            assert completion.hasMore is True  # ty: ignore[unresolved-attribute]
+
+    def test_list_tools_result_next_cursor_bridged(self):
+        result = mcp_types.ListToolsResult(tools=[], next_cursor="abc")
+        with pytest.warns(FastMCPDeprecationWarning):
+            assert result.nextCursor == "abc"  # ty: ignore[unresolved-attribute]
+
+    def test_sampling_params_max_tokens_bridged(self):
+        params = mcp_types.CreateMessageRequestParams(messages=[], max_tokens=100)
+        with pytest.warns(FastMCPDeprecationWarning):
+            assert params.maxTokens == 100  # ty: ignore[unresolved-attribute]
+
+    def test_elicit_form_params_requested_schema_bridged(self):
+        params = mcp_types.ElicitRequestFormParams(
+            message="hi", requested_schema={"type": "object", "properties": {}}
+        )
+        with pytest.warns(FastMCPDeprecationWarning):
+            assert params.requestedSchema == {"type": "object", "properties": {}}  # ty: ignore[unresolved-attribute]
+
+
+class TestWarnOnce:
+    def test_warns_exactly_once_per_class_name(self):
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            t1 = mcp_types.Tool(name="a", input_schema={"type": "object"})
+            t2 = mcp_types.Tool(name="b", input_schema={"type": "string"})
+            _ = t1.inputSchema  # ty: ignore[unresolved-attribute]
+            _ = t2.inputSchema  # ty: ignore[unresolved-attribute]
+            _ = t1.inputSchema  # ty: ignore[unresolved-attribute]
+        deprecations = [
+            w for w in caught if issubclass(w.category, FastMCPDeprecationWarning)
+        ]
+        assert len(deprecations) == 1
+
+    def test_distinct_names_warn_independently(self):
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            tool = mcp_types.Tool(
+                name="a",
+                input_schema={"type": "object"},
+                output_schema={"type": "string"},
+            )
+            _ = tool.inputSchema  # ty: ignore[unresolved-attribute]
+            _ = tool.outputSchema  # ty: ignore[unresolved-attribute]
+        deprecations = [
+            w for w in caught if issubclass(w.category, FastMCPDeprecationWarning)
+        ]
+        assert len(deprecations) == 2
+
+
+class TestModelRoundTrip:
+    def test_survives_model_copy(self):
+        tool = mcp_types.Tool(name="t", input_schema={"type": "object"})
+        copied = tool.model_copy()
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            assert copied.inputSchema == {"type": "object"}  # ty: ignore[unresolved-attribute]
+
+    def test_survives_model_validate(self):
+        tool = mcp_types.Tool.model_validate(
+            {"name": "t", "inputSchema": {"type": "object"}}
+        )
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            assert tool.inputSchema == {"type": "object"}  # ty: ignore[unresolved-attribute]
+            assert tool.input_schema == {"type": "object"}
+
+
+class TestGuards:
+    def test_does_not_shadow_existing_snake_field(self):
+        # The real snake_case field must always resolve without warning.
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            tool = mcp_types.Tool(name="t", input_schema={"type": "object"})
+            assert tool.input_schema == {"type": "object"}
+        assert not caught
+
+    def test_install_is_idempotent(self):
+        _compat.install()
+        _compat.install()
+        tool = mcp_types.Tool(name="t", input_schema={"type": "object"})
+        with pytest.warns(FastMCPDeprecationWarning):
+            assert tool.inputSchema == {"type": "object"}  # ty: ignore[unresolved-attribute]
+
+
+class TestSettingOff:
+    def test_setting_off_raises_attribute_error(self, monkeypatch):
+        # The property stays installed, but with the setting disabled the getter
+        # raises AttributeError as if the camelCase name never existed.
+        monkeypatch.setattr(fastmcp.settings, "mcp_camelcase_compat", False)
+        tool = mcp_types.Tool(name="t", input_schema={"type": "object"})
+        with pytest.raises(AttributeError):
+            _ = tool.inputSchema  # ty: ignore[unresolved-attribute]
+
+    def test_setting_off_attribute_error_message(self, monkeypatch):
+        monkeypatch.setattr(fastmcp.settings, "mcp_camelcase_compat", False)
+        tool = mcp_types.Tool(name="t", input_schema={"type": "object"})
+        with pytest.raises(
+            AttributeError,
+            match=r"'Tool' object has no attribute 'inputSchema'",
+        ):
+            _ = tool.inputSchema  # ty: ignore[unresolved-attribute]
+
+    def test_runtime_toggle_on_off_on(self, monkeypatch):
+        # The bridge honours the live setting on every read: on -> off -> on.
+        tool = mcp_types.Tool(name="t", input_schema={"type": "object"})
+
+        # On (default): bridged read works and warns.
+        with pytest.warns(FastMCPDeprecationWarning):
+            assert tool.inputSchema == {"type": "object"}  # ty: ignore[unresolved-attribute]
+
+        # Off: same attribute now raises.
+        monkeypatch.setattr(fastmcp.settings, "mcp_camelcase_compat", False)
+        with pytest.raises(AttributeError):
+            _ = tool.inputSchema  # ty: ignore[unresolved-attribute]
+
+        # Back on: resolves again (warn-once may have fired already, so ignore).
+        monkeypatch.setattr(fastmcp.settings, "mcp_camelcase_compat", True)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            assert tool.inputSchema == {"type": "object"}  # ty: ignore[unresolved-attribute]
+
+
+class TestExceptionAlias:
+    def test_mcp_error_is_alias(self):
+        assert McpError is MCPError
+        assert McpError is SDKMCPError
+
+    def test_except_mcp_error_catches_sdk_raised(self):
+        with pytest.raises(McpError):
+            raise SDKMCPError(code=-32000, message="boom")
+
+
+class TestClientBehaviorCompat:
+    """Behavior compat checklist (design decision D)."""
+
+    @pytest.fixture
+    def server(self):
+        srv = FastMCP("BehaviorServer")
+
+        @srv.tool
+        def echo(x: str) -> str:
+            return x
+
+        return srv
+
+    @pytest.mark.parametrize(
+        "timeout",
+        [5, 5.0, datetime.timedelta(seconds=5), None],
+    )
+    async def test_client_accepts_timedelta_or_float_timeout(self, server, timeout):
+        client = Client(transport=FastMCPTransport(server), timeout=timeout)
+        async with client:
+            result = await client.call_tool("echo", {"x": "hi"})
+        assert result.data == "hi"
+
+    async def test_ping_returns_bool(self, server):
+        client = Client(transport=FastMCPTransport(server))
+        async with client:
+            result = await client.ping()
+        assert result is True
+
+    async def test_session_id_none_safe(self, server):
+        # In-memory transport has no HTTP session id; must return None, not raise.
+        client = Client(transport=FastMCPTransport(server))
+        async with client:
+            assert client.transport.get_session_id() is None
diff --git a/tests/test_exceptions.py b/tests/test_exceptions.py
new file mode 100644
index 0000000..d85ea03
--- /dev/null
+++ b/tests/test_exceptions.py
@@ -0,0 +1,82 @@
+"""Tests for FastMCP's exception-to-wire-error translation."""
+
+from __future__ import annotations
+
+import pytest
+from mcp import MCPError
+from mcp_types import INTERNAL_ERROR, INVALID_PARAMS
+
+from fastmcp import Client, FastMCP
+from fastmcp.exceptions import (
+    DisabledError,
+    NotFoundError,
+    PromptError,
+    ResourceError,
+    ToolError,
+    ValidationError,
+    to_mcp_error,
+)
+
+
+class TestToMcpError:
+    @pytest.mark.parametrize(
+        "exc",
+        [NotFoundError("missing"), DisabledError("off"), ValidationError("bad")],
+    )
+    def test_invalid_params_mapping(self, exc: Exception):
+        """Not-found, disabled, and validation errors map to INVALID_PARAMS.
+
+        SEP-2164 defines a request naming a nonexistent (or disabled) component
+        as an invalid-params error, matching the SDK's own mcpserver mapping.
+        """
+        result = to_mcp_error(exc)
+        assert isinstance(result, MCPError)
+        assert result.error.code == INVALID_PARAMS
+        assert result.error.message == str(exc)
+
+    @pytest.mark.parametrize(
+        "exc",
+        [ResourceError("boom"), PromptError("boom"), ToolError("boom")],
+    )
+    def test_default_code_for_unmapped_errors(self, exc: Exception):
+        """Operation errors without a dedicated mapping use the default code."""
+        assert to_mcp_error(exc).error.code == INTERNAL_ERROR
+
+    def test_custom_default_code(self):
+        assert (
+            to_mcp_error(ResourceError("x"), default_code=-32000).error.code == -32000
+        )
+
+    def test_existing_mcp_error_passes_through(self):
+        """An MCPError chosen upstream survives translation unchanged."""
+        existing = MCPError(code=-32000, message="explicit")
+        assert to_mcp_error(existing) is existing
+
+
+class TestWireErrorCodes:
+    """The core request-handler adapters must emit spec-correct wire codes."""
+
+    async def test_resource_not_found_uses_invalid_params(self):
+        """Resource-not-found is INVALID_PARAMS (-32602), not -32002.
+
+        SEP-2164 corrected this: the SDK's mcpserver maps ResourceNotFoundError
+        to INVALID_PARAMS. FastMCP previously deviated with -32002.
+        """
+        mcp = FastMCP("test-server")
+
+        async with Client(mcp) as client:
+            with pytest.raises(MCPError) as exc_info:
+                await client.read_resource_mcp("config://missing")
+
+        assert exc_info.value.error.code == INVALID_PARAMS
+        assert "Resource not found" in exc_info.value.error.message
+
+    async def test_prompt_not_found_uses_invalid_params(self):
+        mcp = FastMCP("test-server")
+
+        async with Client(mcp) as client:
+            with pytest.raises(MCPError) as exc_info:
+                await client.get_prompt("missing", {})
+
+        assert exc_info.value.error.code == INVALID_PARAMS
+        assert "Unknown prompt" in exc_info.value.error.message
diff --git a/tests/test_fastmcp_app.py b/tests/test_fastmcp_app.py
new file mode 100644
index 0000000..86f9eae
--- /dev/null
+++ b/tests/test_fastmcp_app.py
@@ -0,0 +1,896 @@
+"""Tests for FastMCPApp — the composable application provider.
+
+Covers:
+- @app.tool() decorator (visibility, calling patterns)
+- @app.ui() decorator (model visibility, CSP auto-wiring)
+- get_app_tool routing through provider chain
+- Callable resolver (_resolve_tool_ref)
+- Composition with namespaced servers
+- Provider interface delegation
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock
+
+import pytest
+from prefab_ui.app import ResolvedTool
+from prefab_ui.components import Text
+
+from fastmcp import Client, FastMCP
+from fastmcp.apps.app import (
+    FastMCPApp,
+    _make_resolver,
+)
+from fastmcp.tools.base import Tool
+
+# ---------------------------------------------------------------------------
+# @app.tool() decorator
+# ---------------------------------------------------------------------------
+
+
+class TestFastMCPAppInit:
+    def test_app_name_with_underscores_ok(self):
+        # The old `___` separator is gone — backend tool routing now uses
+        # a hashed positional address rather than a name-based prefix, so
+        # any character is fine inside an app name.
+        FastMCPApp("my_app")
+        FastMCPApp("my__app")
+        FastMCPApp("my___app")
+
+
+class TestAppTool:
+    def test_tool_bare_decorator(self):
+        app = FastMCPApp("test")
+
+        @app.tool
+        def save(name: str) -> str:
+            return name
+
+        assert save("alice") == "alice"
+
+    def test_tool_empty_parens(self):
+        app = FastMCPApp("test")
+
+        @app.tool()
+        def save(name: str) -> str:
+            return name
+
+        assert save("alice") == "alice"
+
+    def test_tool_custom_name(self):
+        app = FastMCPApp("test")
+
+        @app.tool("custom_save")
+        def save(name: str) -> str:
+            return name
+
+        assert save("alice") == "alice"
+
+    def test_tool_name_kwarg(self):
+        app = FastMCPApp("test")
+
+        @app.tool(name="my_tool")
+        def save(name: str) -> str:
+            return name
+
+        assert save("alice") == "alice"
+
+    def test_tool_name_conflict_raises(self):
+        app = FastMCPApp("test")
+
+        with pytest.raises(TypeError):
+
+            @app.tool("x", name="y")
+            def save() -> str:
+                return ""
+
+    async def test_tool_registers_in_provider(self):
+        app = FastMCPApp("test")
+
+        @app.tool()
+        def save(name: str) -> str:
+            return name
+
+        tools = await app._list_tools()
+        assert len(tools) == 1
+        assert tools[0].name == "save"
+
+    async def test_tool_custom_name_in_provider(self):
+        app = FastMCPApp("test")
+
+        @app.tool("custom_save")
+        def save(name: str) -> str:
+            return name
+
+        tools = await app._list_tools()
+        assert len(tools) == 1
+        assert tools[0].name == "custom_save"
+
+    async def test_tool_has_app_name_in_meta(self):
+        app = FastMCPApp("contacts")
+
+        @app.tool()
+        def save(name: str) -> str:
+            return name
+
+        tools = await app._list_tools()
+        meta = tools[0].meta
+        assert meta is not None
+        assert meta["fastmcp"]["app"] == "contacts"
+
+    async def test_tool_default_visibility_app_only(self):
+        app = FastMCPApp("test")
+
+        @app.tool()
+        def save(name: str) -> str:
+            return name
+
+        tools = await app._list_tools()
+        meta = tools[0].meta
+        assert meta is not None
+        assert meta["ui"]["visibility"] == ["app"]
+
+    async def test_tool_model_visibility(self):
+        app = FastMCPApp("test")
+
+        @app.tool(model=True)
+        def query(search: str) -> list:
+            return []
+
+        tools = await app._list_tools()
+        meta = tools[0].meta
+        assert meta is not None
+        assert meta["ui"]["visibility"] == ["app", "model"]
+
+    def test_tool_with_description(self):
+        app = FastMCPApp("test")
+
+        @app.tool(description="Save a contact")
+        def save(name: str) -> str:
+            return name
+
+    def test_tool_with_auth(self):
+        app = FastMCPApp("test")
+        check = AsyncMock(return_value=True)
+
+        @app.tool(auth=check)
+        def save(name: str) -> str:
+            return name
+
+    def test_tool_with_timeout(self):
+        app = FastMCPApp("test")
+
+        @app.tool(timeout=30.0)
+        def slow_save(name: str) -> str:
+            return name
+
+
+# ---------------------------------------------------------------------------
+# @app.ui() decorator
+# ---------------------------------------------------------------------------
+
+
+class TestAppUI:
+    def test_ui_bare_decorator(self):
+        app = FastMCPApp("test")
+
+        @app.ui
+        def dashboard() -> str:
+            return "hi"
+
+        assert dashboard() == "hi"
+
+    def test_ui_empty_parens(self):
+        app = FastMCPApp("test")
+
+        @app.ui()
+        def dashboard() -> str:
+            return "hi"
+
+        assert dashboard() == "hi"
+
+    def test_ui_custom_name(self):
+        app = FastMCPApp("test")
+
+        @app.ui("my_dashboard")
+        def dashboard() -> str:
+            return "hi"
+
+        assert dashboard() == "hi"
+
+    async def test_ui_registers_in_provider(self):
+        app = FastMCPApp("test")
+
+        @app.ui()
+        def dashboard() -> str:
+            return "dashboard"
+
+        tools = await app._list_tools()
+        assert len(tools) == 1
+        assert tools[0].name == "dashboard"
+
+    async def test_ui_visibility_model_only(self):
+        app = FastMCPApp("test")
+
+        @app.ui()
+        def dashboard() -> str:
+            return "dashboard"
+
+        tools = await app._list_tools()
+        meta = tools[0].meta
+        assert meta is not None
+        assert meta["ui"]["visibility"] == ["model"]
+
+    async def test_ui_has_app_name_in_meta(self):
+        app = FastMCPApp("test")
+
+        @app.ui()
+        def dashboard() -> str:
+            return "dashboard"
+
+        tools = await app._list_tools()
+        meta = tools[0].meta
+        assert meta is not None
+        assert meta["fastmcp"]["app"] == "test"
+
+    async def test_ui_has_resource_uri(self):
+        app = FastMCPApp("test")
+
+        @app.ui()
+        def dashboard() -> str:
+            return "dashboard"
+
+        tools = await app._list_tools()
+        meta = tools[0].meta
+        assert meta is not None
+        assert meta["ui"]["resourceUri"] == "ui://prefab/renderer.html"
+
+    async def test_ui_tool_has_no_csp(self):
+        """CSP belongs on the UI resource, not the tool (per MCP Apps spec)."""
+        app = FastMCPApp("test")
+
+        @app.ui()
+        def dashboard() -> str:
+            return "dashboard"
+
+        tools = await app._list_tools()
+        meta = tools[0].meta
+        assert meta is not None
+        assert "csp" not in meta["ui"]
+
+    async def test_ui_with_title_and_description(self):
+        app = FastMCPApp("test")
+
+        @app.ui(title="My Dashboard", description="Shows data")
+        def dashboard() -> str:
+            return "dashboard"
+
+        tools = await app._list_tools()
+        assert tools[0].title == "My Dashboard"
+        assert tools[0].description == "Shows data"
+
+    async def test_ui_with_tags(self):
+        app = FastMCPApp("test")
+
+        @app.ui(tags={"dashboard", "main"})
+        def dashboard() -> str:
+            return "dashboard"
+
+        tools = await app._list_tools()
+        assert tools[0].tags == {"dashboard", "main"}
+
+
+# ---------------------------------------------------------------------------
+# Callable resolver
+# ---------------------------------------------------------------------------
+
+
+class TestResolveToolRef:
+    def test_resolve_string_no_context(self):
+        """Without a running Context the resolver returns bare names."""
+        result = _make_resolver()("save_contact")
+        assert isinstance(result, ResolvedTool)
+        assert result.name == "save_contact"
+
+    def test_resolve_string_with_app_name(self):
+        """With an app name the resolver produces a hashed backend name."""
+        from fastmcp.server.providers.addressing import hashed_backend_name
+
+        result = _make_resolver("contacts")("save_contact")
+        assert isinstance(result, ResolvedTool)
+        assert result.name == hashed_backend_name("contacts", "save_contact")
+
+    def test_resolve_callable_no_context(self):
+        """Without context, callables resolve to their bare __name__."""
+
+        def my_tool():
+            pass
+
+        result = _make_resolver()(my_tool)
+        assert isinstance(result, ResolvedTool)
+        assert result.name == "my_tool"
+
+    def test_resolve_unresolvable_raises(self):
+        with pytest.raises(ValueError):
+            _make_resolver()(42)
+
+
+# ---------------------------------------------------------------------------
+# get_app_tool — provider chain routing
+# ---------------------------------------------------------------------------
+
+
+class TestGetAppTool:
+    async def test_direct_lookup(self):
+        """FastMCPApp.get_app_tool finds tools by app name + tool name."""
+        app = FastMCPApp("contacts")
+
+        @app.tool()
+        def save(name: str) -> str:
+            return name
+
+        tool = await app.get_app_tool("contacts", "save")
+        assert tool is not None
+        assert tool.name == "save"
+
+    async def test_wrong_app_returns_none(self):
+        app = FastMCPApp("contacts")
+
+        @app.tool()
+        def save(name: str) -> str:
+            return name
+
+        assert await app.get_app_tool("billing", "save") is None
+
+    async def test_wrong_tool_returns_none(self):
+        app = FastMCPApp("contacts")
+
+        @app.tool()
+        def save(name: str) -> str:
+            return name
+
+        assert await app.get_app_tool("contacts", "missing") is None
+
+    async def test_two_apps_no_collision(self):
+        """Two apps with the same tool name are disambiguated."""
+        app1 = FastMCPApp("contacts")
+        app2 = FastMCPApp("billing")
+
+        @app1.tool()
+        def save(name: str) -> str:
+            return f"contact: {name}"
+
+        @app2.tool("save")
+        def save_billing(amount: int) -> str:
+            return f"invoice: {amount}"
+
+        server = FastMCP("Platform")
+        server.add_provider(app1)
+        server.add_provider(app2)
+
+        t1 = await server.get_app_tool("contacts", "save")
+        t2 = await server.get_app_tool("billing", "save")
+        assert t1 is not None
+        assert t2 is not None
+        assert t1 is not t2
+
+    async def test_survives_namespace_transform(self):
+        """get_app_tool bypasses namespace transforms."""
+        app = FastMCPApp("crm")
+
+        @app.tool()
+        def save_contact(name: str) -> str:
+            return name
+
+        server = FastMCP("Platform")
+        server.add_provider(app, namespace="crm")
+
+        # Normal get_tool with untransformed name fails
+        tool = await server.get_tool("save_contact")
+        assert tool is None
+
+        # get_app_tool bypasses transforms
+        tool = await server.get_app_tool("crm", "save_contact")
+        assert tool is not None
+        assert tool.name == "save_contact"
+
+    async def test_ui_tool_not_findable_via_get_app_tool(self):
+        """@app.ui() tools have model visibility and should NOT be
+        returned by get_app_tool (only app-visible tools are)."""
+        app = FastMCPApp("dashboard")
+
+        @app.ui()
+        def show() -> str:
+            return "ui"
+
+        tool = await app.get_app_tool("dashboard", "show")
+        assert tool is None
+
+    async def test_model_visible_tool_findable(self):
+        """@app.tool(model=True) has app visibility and IS findable."""
+        app = FastMCPApp("test")
+
+        @app.tool(model=True)
+        def query(q: str) -> str:
+            return q
+
+        tool = await app.get_app_tool("test", "query")
+        assert tool is not None
+
+
+# ---------------------------------------------------------------------------
+# Provider interface
+# ---------------------------------------------------------------------------
+
+
+class TestProviderInterface:
+    async def test_list_tools_empty(self):
+        app = FastMCPApp("test")
+        assert await app._list_tools() == []
+
+    async def test_list_resources_empty(self):
+        app = FastMCPApp("test")
+        assert list(await app._list_resources()) == []
+
+    async def test_get_tool_by_name(self):
+        app = FastMCPApp("test")
+
+        @app.tool()
+        def save(name: str) -> str:
+            return name
+
+        tool = await app._get_tool("save")
+        assert tool is not None
+        assert tool.name == "save"
+
+    async def test_get_tool_missing_returns_none(self):
+        app = FastMCPApp("test")
+        assert await app._get_tool("missing") is None
+
+
+# ---------------------------------------------------------------------------
+# call_tool with app_name routing
+# ---------------------------------------------------------------------------
+
+
+class TestCallToolAppRouting:
+    async def test_call_tool_with_hashed_name(self):
+        """A backend tool with visibility=['app'] is callable via its
+        hashed-name address — the same form a Prefab UI's resolver would
+        produce when serializing a peer reference."""
+        from fastmcp.server.providers.addressing import hashed_backend_name
+
+        app = FastMCPApp("contacts")
+
+        @app.tool()
+        def save(name: str) -> str:
+            return f"saved {name}"
+
+        server = FastMCP("Platform")
+        server.add_provider(app)
+
+        result = await server.call_tool(
+            hashed_backend_name("contacts", "save"), {"name": "alice"}
+        )
+        assert result.content[0].text == "saved alice"  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+
+    async def test_call_tool_model_visible_uses_display_name(self):
+        """Tools with visibility=['app','model'] are callable by display name."""
+        app = FastMCPApp("test")
+
+        @app.tool(model=True)
+        def save(name: str) -> str:
+            return f"saved {name}"
+
+        server = FastMCP("Platform")
+        server.add_provider(app)
+
+        result = await server.call_tool("save", {"name": "bob"})
+        assert result.content[0].text == "saved bob"  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+
+    async def test_hashed_name_survives_namespace_mount(self):
+        """The hashed-name path bypasses display-layer transforms entirely.
+        A FastMCPApp mounted under a Namespace transform still has its
+        backend tools reachable via the same hash."""
+        from fastmcp.server.providers.addressing import hashed_backend_name
+
+        app = FastMCPApp("crm")
+
+        @app.tool()
+        def save_contact(name: str) -> str:
+            return f"saved {name}"
+
+        server = FastMCP("Platform")
+        server.add_provider(app, namespace="crm")
+
+        result = await server.call_tool(
+            hashed_backend_name("crm", "save_contact"), {"name": "alice"}
+        )
+        assert result.content[0].text == "saved alice"  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+
+    async def test_namespaced_display_name_also_works(self):
+        """Model-visible tools still resolve through Namespace as before."""
+        app = FastMCPApp("crm")
+
+        @app.tool(model=True)
+        def save_contact(name: str) -> str:
+            return f"saved {name}"
+
+        server = FastMCP("Platform")
+        server.add_provider(app, namespace="crm")
+
+        result = await server.call_tool("crm_save_contact", {"name": "bob"})
+        assert result.content[0].text == "saved bob"  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+
+    async def test_hashed_name_auth_blocks_unauthorized(self):
+        """Auth checks run on the hashed-name dispatch path too."""
+        from fastmcp.exceptions import NotFoundError
+        from fastmcp.server.context import _current_transport
+        from fastmcp.server.providers.addressing import hashed_backend_name
+
+        app = FastMCPApp("test")
+        deny_all = AsyncMock(return_value=False)
+
+        @app.tool(auth=deny_all)
+        def secret() -> str:
+            return "classified"
+
+        server = FastMCP("Platform")
+        server.add_provider(app)
+
+        token = _current_transport.set("streamable-http")
+        try:
+            with pytest.raises(NotFoundError):
+                await server.call_tool(hashed_backend_name("test", "secret"), {})
+        finally:
+            _current_transport.reset(token)
+
+    async def test_two_apps_same_tool_name_routed_by_address(self):
+        """Two FastMCPApps each with a `save` tool live at distinct
+        addresses, so they hash differently and the dispatcher routes
+        each call to the right app without name collisions."""
+        from fastmcp.server.providers.addressing import hashed_backend_name
+
+        contacts = FastMCPApp("contacts")
+        billing = FastMCPApp("billing")
+
+        @contacts.tool()
+        def save(name: str) -> str:
+            return f"contact: {name}"
+
+        @billing.tool("save")
+        def save_billing(amount: str) -> str:
+            return f"invoice: {amount}"
+
+        server = FastMCP("Platform")
+        server.add_provider(contacts)  # → address (0,)
+        server.add_provider(billing)  # → address (1,)
+
+        r1 = await server.call_tool(
+            hashed_backend_name("contacts", "save"), {"name": "alice"}
+        )
+        r2 = await server.call_tool(
+            hashed_backend_name("billing", "save"), {"amount": "100"}
+        )
+
+        assert r1.content[0].text == "contact: alice"  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+        assert r2.content[0].text == "invoice: 100"  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+
+
+# ---------------------------------------------------------------------------
+# App-only tool filtering from server list_tools / get_tool
+# ---------------------------------------------------------------------------
+
+
+class TestAppOnlyToolFiltering:
+    async def test_app_only_tool_hidden_from_list_tools(self):
+        """@app.tool() (visibility=["app"]) should not appear in server.list_tools()."""
+        app = FastMCPApp("crm")
+
+        @app.tool()
+        def save_contact(name: str) -> str:
+            return name
+
+        server = FastMCP("Platform")
+        server.add_provider(app)
+
+        tools = await server.list_tools()
+        names = [t.name for t in tools]
+        assert "save_contact" not in names
+
+    async def test_model_visible_tool_in_list_tools(self):
+        """@app.tool(model=True) (visibility=["app","model"]) appears in list_tools."""
+        app = FastMCPApp("crm")
+
+        @app.tool(model=True)
+        def query(search: str) -> list[str]:
+            return [search]
+
+        server = FastMCP("Platform")
+        server.add_provider(app)
+
+        tools = await server.list_tools()
+        names = [t.name for t in tools]
+        assert "query" in names
+
+    async def test_ui_tool_in_list_tools(self):
+        """@app.ui() (visibility=["model"]) appears in list_tools."""
+        app = FastMCPApp("dashboard")
+
+        @app.ui()
+        def show_dashboard() -> str:
+            return "dashboard"
+
+        server = FastMCP("Platform")
+        server.add_provider(app)
+
+        tools = await server.list_tools()
+        names = [t.name for t in tools]
+        assert "show_dashboard" in names
+
+    async def test_app_only_tool_still_callable_via_app_name(self):
+        """Even though filtered from list_tools, app-only tools are callable via call_tool with app_name."""
+        app = FastMCPApp("contacts")
+
+        @app.tool()
+        def save(name: str) -> str:
+            return f"saved {name}"
+
+        server = FastMCP("Platform")
+        server.add_provider(app)
+
+        # Verify it's hidden from list_tools
+        tools = await server.list_tools()
+        names = [t.name for t in tools]
+        assert "save" not in names
+
+        # But still callable via the hashed-address routing path.
+        from fastmcp.server.providers.addressing import hashed_backend_name
+
+        result = await server.call_tool(
+            hashed_backend_name("contacts", "save"), {"name": "alice"}
+        )
+        assert result.content[0].text == "saved alice"  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+
+    async def test_app_only_tool_hidden_from_get_tool(self):
+        """server.get_tool() returns None for app-only tools."""
+        app = FastMCPApp("crm")
+
+        @app.tool()
+        def save_contact(name: str) -> str:
+            return name
+
+        server = FastMCP("Platform")
+        server.add_provider(app)
+
+        tool = await server.get_tool("save_contact")
+        assert tool is None
+
+    async def test_app_only_tool_hidden_with_namespace(self):
+        """App-only tools hidden even when accessed through a namespace."""
+        app = FastMCPApp("crm")
+
+        @app.tool()
+        def save(name: str) -> str:
+            return name
+
+        server = FastMCP("Platform")
+        server.add_provider(app, namespace="crm")
+
+        tools = await server.list_tools()
+        names = [t.name for t in tools]
+        assert "crm_save" not in names
+
+
+# ---------------------------------------------------------------------------
+# End-to-end via Client
+# ---------------------------------------------------------------------------
+
+
+class TestEndToEnd:
+    async def test_ui_tool_visible_to_client(self):
+        app = FastMCPApp("test")
+
+        @app.ui()
+        def dashboard() -> str:
+            return "dashboard"
+
+        server = FastMCP("Platform")
+        server.add_provider(app)
+
+        async with Client(server) as client:
+            tools = await client.list_tools()
+            names = [t.name for t in tools]
+            assert "dashboard" in names
+
+    async def test_app_tool_model_true_visible(self):
+        app = FastMCPApp("test")
+
+        @app.tool(model=True)
+        def query(search: str) -> list:
+            return [search]
+
+        server = FastMCP("Platform")
+        server.add_provider(app)
+
+        async with Client(server) as client:
+            tools = await client.list_tools()
+            names = [t.name for t in tools]
+            assert "query" in names
+
+
+# ---------------------------------------------------------------------------
+# .run() convenience
+# ---------------------------------------------------------------------------
+
+
+class TestRun:
+    def test_repr(self):
+        app = FastMCPApp("Dashboard")
+        assert repr(app) == "FastMCPApp('Dashboard')"
+
+
+# ---------------------------------------------------------------------------
+# add_tool programmatic
+# ---------------------------------------------------------------------------
+
+
+class TestAddTool:
+    async def test_add_tool_from_function(self):
+        app = FastMCPApp("test")
+
+        def save(name: str) -> str:
+            return name
+
+        tool = app.add_tool(save)
+        assert tool.name == "save"
+
+        tools = await app._list_tools()
+        assert len(tools) == 1
+
+    async def test_add_tool_tagged_with_app_name(self):
+        app = FastMCPApp("myapp")
+
+        def save(name: str) -> str:
+            return name
+
+        tool = app.add_tool(save)
+        assert tool.meta is not None
+        assert tool.meta["fastmcp"]["app"] == "myapp"
+
+    async def test_add_tool_findable_via_get_app_tool(self):
+        app = FastMCPApp("myapp")
+
+        def save(name: str) -> str:
+            return name
+
+        app.add_tool(save)
+        tool = await app.get_app_tool("myapp", "save")
+        assert tool is not None
+
+    async def test_add_tool_object(self):
+        app = FastMCPApp("test")
+        tool = Tool.from_function(lambda x: x, name="my_tool")
+        added = app.add_tool(tool)
+        assert added.name == "my_tool"
+
+        tools = await app._list_tools()
+        assert len(tools) == 1
+
+
+# ---------------------------------------------------------------------------
+# Composition
+# ---------------------------------------------------------------------------
+
+
+class TestComposition:
+    async def test_multiple_apps_on_one_server(self):
+        crm = FastMCPApp("CRM")
+        billing = FastMCPApp("Billing")
+
+        @crm.tool()
+        def save_contact(name: str) -> str:
+            return name
+
+        @billing.tool()
+        def create_invoice(amount: int) -> int:
+            return amount
+
+        server = FastMCP("Platform")
+        server.add_provider(crm, namespace="crm")
+        server.add_provider(billing, namespace="billing")
+
+        from fastmcp.server.providers.addressing import hashed_backend_name
+
+        # CRM is at address (0,), billing at (1,) — registration order.
+        r1 = await server.call_tool(
+            hashed_backend_name("CRM", "save_contact"), {"name": "alice"}
+        )
+        r2 = await server.call_tool(
+            hashed_backend_name("Billing", "create_invoice"), {"amount": 100}
+        )
+
+        assert r1.content[0].text == "alice"  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+        assert r2.content[0].text == "100"  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+
+    async def test_ui_and_tool_on_same_app(self):
+        app = FastMCPApp("test")
+
+        @app.ui()
+        def dashboard() -> str:
+            return "ui"
+
+        @app.tool()
+        def save(name: str) -> str:
+            return name
+
+        tools = await app._list_tools()
+        assert len(tools) == 2
+        names = {t.name for t in tools}
+        assert names == {"dashboard", "save"}
+
+    async def test_ui_synthesizes_per_tool_renderer_resource(self):
+        """Each @app.ui() tool gets its own renderer resource synthesized
+        on demand from the server's address registry."""
+        app = FastMCPApp("test")
+
+        @app.ui()
+        def dashboard() -> str:
+            return "ui"
+
+        server = FastMCP("Platform")
+        server.add_provider(app)
+
+        resources = list(await server.list_resources())
+        prefab = [r for r in resources if "prefab/tool" in str(r.uri)]
+        assert len(prefab) == 1
+
+
+# ---------------------------------------------------------------------------
+# Integration: full end-to-end with client, namespacing, and structured content
+# ---------------------------------------------------------------------------
+
+
+class TestAppIntegration:
+    async def test_full_app_lifecycle_through_client(self):
+        """End-to-end: mount an app on a namespaced server, call UI tool
+        through a client (verifying structured_content is returned), then
+        call the backend tool via its hashed-address name."""
+        from fastmcp.server.providers.addressing import hashed_backend_name
+
+        app = FastMCPApp("contacts")
+
+        @app.ui()
+        def contact_form() -> Text:
+            return Text(content="Enter contact details")
+
+        @app.tool()
+        def save_contact(name: str, email: str) -> dict[str, str]:
+            return {"name": name, "email": email}
+
+        server = FastMCP("Platform")
+        server.add_provider(app, namespace="crm")
+
+        # The @app.ui() tool should be visible (namespaced) to the client.
+        # The @app.tool() backend tool should NOT appear.
+        async with Client(server) as client:
+            tools = await client.list_tools()
+            tool_names = [t.name for t in tools]
+            assert "crm_contact_form" in tool_names
+            assert "crm_save_contact" not in tool_names
+
+            # Call the UI tool through the client and check structured_content
+            result = await client.call_tool_mcp("crm_contact_form", {})
+            sc = result.structured_content
+            assert sc is not None
+
+        # Call the backend tool via its hashed address — bypasses namespace
+        # transforms and visibility filtering by going through the registry.
+        backend_result = await server.call_tool(
+            hashed_backend_name("contacts", "save_contact"),
+            {"name": "Alice", "email": "alice@example.com"},
+        )
+        result_text = backend_result.content[0].text  # type: ignore[union-attr]  # ty:ignore[unresolved-attribute]
+        assert "Alice" in result_text
+        assert "alice@example.com" in result_text
diff --git a/tests/test_json_schema_generation.py b/tests/test_json_schema_generation.py
new file mode 100644
index 0000000..5fdd9ae
--- /dev/null
+++ b/tests/test_json_schema_generation.py
@@ -0,0 +1,231 @@
+"""Tests for JSON schema generation from FastMCP BaseModel classes.
+
+Validates that callable fields are properly excluded from generated schemas
+using SkipJsonSchema annotations.
+"""
+
+from fastmcp.prompts.function_prompt import FunctionPrompt
+from fastmcp.resources.function_resource import FunctionResource
+from fastmcp.resources.template import FunctionResourceTemplate
+from fastmcp.tools.base import Tool
+from fastmcp.tools.function_tool import FunctionTool
+from fastmcp.tools.tool_transform import TransformedTool
+
+
+class TestToolJsonSchema:
+    """Test JSON schema generation for Tool classes."""
+
+    def test_tool_json_schema_generation(self):
+        """Verify Tool.model_json_schema() works without errors."""
+        # This should not raise an error
+        schema = Tool.model_json_schema()
+
+        # Verify schema is valid
+        assert schema["type"] == "object"
+        assert "properties" in schema
+
+        # Verify callable fields are excluded from schema
+        assert "serializer" not in schema["properties"]
+        # auth already uses exclude=True, so it shouldn't be in schema
+        assert "auth" not in schema["properties"]
+
+    def test_function_tool_json_schema_generation(self):
+        """Verify FunctionTool.model_json_schema() works without errors."""
+
+        def sample_tool(x: int, y: int) -> int:
+            """Add two numbers."""
+            return x + y
+
+        tool = FunctionTool.from_function(sample_tool)
+
+        # This should not raise an error
+        schema = tool.model_json_schema()
+
+        # Verify schema is valid
+        assert schema["type"] == "object"
+        assert "properties" in schema
+
+        # Verify callable field 'fn' is excluded from schema
+        assert "fn" not in schema["properties"]
+
+    def test_transformed_tool_json_schema_generation(self):
+        """Verify TransformedTool.model_json_schema() works without errors."""
+
+        def parent_fn(x: int) -> int:
+            return x * 2
+
+        parent_tool = FunctionTool.from_function(parent_fn)
+        transformed_tool = TransformedTool.from_tool(parent_tool, name="doubled")
+
+        # This should not raise an error
+        schema = transformed_tool.model_json_schema()
+
+        # Verify schema is valid
+        assert schema["type"] == "object"
+        assert "properties" in schema
+
+        # Verify callable fields are excluded from schema
+        assert "fn" not in schema["properties"]
+        assert "forwarding_fn" not in schema["properties"]
+        assert "parent_tool" not in schema["properties"]
+
+
+class TestResourceJsonSchema:
+    """Test JSON schema generation for Resource classes."""
+
+    def test_function_resource_json_schema_generation(self):
+        """Verify FunctionResource.model_json_schema() works without errors."""
+
+        def sample_resource() -> str:
+            """Return sample data."""
+            return "Hello, world!"
+
+        resource = FunctionResource.from_function(
+            sample_resource, uri="test://resource"
+        )
+
+        # This should not raise an error
+        schema = resource.model_json_schema()
+
+        # Verify schema is valid
+        assert schema["type"] == "object"
+        assert "properties" in schema
+
+        # Verify callable field 'fn' is excluded from schema
+        assert "fn" not in schema["properties"]
+        # auth already uses exclude=True
+        assert "auth" not in schema["properties"]
+
+    def test_function_resource_template_json_schema_generation(self):
+        """Verify FunctionResourceTemplate.model_json_schema() works without errors."""
+
+        def sample_template(name: str) -> str:
+            """Return greeting for name."""
+            return f"Hello, {name}!"
+
+        template = FunctionResourceTemplate.from_function(
+            sample_template, uri_template="greeting://{name}"
+        )
+
+        # This should not raise an error
+        schema = template.model_json_schema()
+
+        # Verify schema is valid
+        assert schema["type"] == "object"
+        assert "properties" in schema
+
+        # Verify callable field 'fn' is excluded from schema
+        assert "fn" not in schema["properties"]
+
+
+class TestPromptJsonSchema:
+    """Test JSON schema generation for Prompt classes."""
+
+    def test_function_prompt_json_schema_generation(self):
+        """Verify FunctionPrompt.model_json_schema() works without errors."""
+
+        def sample_prompt(topic: str) -> str:
+            """Generate prompt about topic."""
+            return f"Tell me about {topic}"
+
+        prompt = FunctionPrompt.from_function(sample_prompt)
+
+        # This should not raise an error
+        schema = prompt.model_json_schema()
+
+        # Verify schema is valid
+        assert schema["type"] == "object"
+        assert "properties" in schema
+
+        # Verify callable field 'fn' is excluded from schema
+        assert "fn" not in schema["properties"]
+        # auth already uses exclude=True
+        assert "auth" not in schema["properties"]
+
+
+class TestJsonSchemaIntegration:
+    """Integration tests for JSON schema generation across all classes."""
+
+    def test_all_classes_generate_valid_schemas(self):
+        """Verify all affected classes can generate valid JSON schemas."""
+
+        # Create instances of all affected classes
+        def tool_fn(x: int) -> int:
+            return x
+
+        def resource_fn() -> str:
+            return "data"
+
+        def template_fn(id: str) -> str:
+            return f"data-{id}"
+
+        def prompt_fn(input: str) -> str:
+            return f"Prompt: {input}"
+
+        tool = FunctionTool.from_function(tool_fn)
+        transformed_tool = TransformedTool.from_tool(tool)
+        resource = FunctionResource.from_function(resource_fn, uri="test://resource")
+        template = FunctionResourceTemplate.from_function(
+            template_fn, uri_template="test://{id}"
+        )
+        prompt = FunctionPrompt.from_function(prompt_fn)
+
+        # All of these should succeed without errors
+        schemas = [
+            Tool.model_json_schema(),
+            tool.model_json_schema(),
+            transformed_tool.model_json_schema(),
+            resource.model_json_schema(),
+            template.model_json_schema(),
+            prompt.model_json_schema(),
+        ]
+
+        # Verify all schemas are valid
+        for schema in schemas:
+            assert isinstance(schema, dict)
+            assert schema["type"] == "object"
+            assert "properties" in schema
+
+    def test_callable_fields_not_in_any_schema(self):
+        """Verify no callable fields appear in any generated schema."""
+
+        # Define test functions
+        def tool_fn(x: int) -> int:
+            return x
+
+        def resource_fn() -> str:
+            return "data"
+
+        def template_fn(id: str) -> str:
+            return f"data-{id}"
+
+        def prompt_fn(input: str) -> str:
+            return f"Prompt: {input}"
+
+        # Create instances
+        tool = FunctionTool.from_function(tool_fn)
+        transformed_tool = TransformedTool.from_tool(tool)
+        resource = FunctionResource.from_function(resource_fn, uri="test://resource")
+        template = FunctionResourceTemplate.from_function(
+            template_fn, uri_template="test://{id}"
+        )
+        prompt = FunctionPrompt.from_function(prompt_fn)
+
+        # List of (instance, callable_field_names) tuples
+        test_cases = [
+            (tool, ["fn", "serializer"]),
+            (transformed_tool, ["fn", "forwarding_fn", "parent_tool", "serializer"]),
+            (resource, ["fn"]),
+            (template, ["fn"]),
+            (prompt, ["fn"]),
+        ]
+
+        for instance, callable_fields in test_cases:
+            schema = instance.model_json_schema()
+            properties = schema.get("properties", {})
+
+            # Verify none of the callable fields are in the schema
+            for field in callable_fields:
+                assert field not in properties, (
+                    f"Callable field '{field}' found in schema for {type(instance).__name__}"
+                )
diff --git a/tests/test_mcp_config.py b/tests/test_mcp_config.py
new file mode 100644
index 0000000..13b8b67
--- /dev/null
+++ b/tests/test_mcp_config.py
@@ -0,0 +1,1238 @@
+import asyncio
+import gc
+import inspect
+import json
+import logging
+import os
+import sys
+import tempfile
+import time
+from collections.abc import AsyncGenerator
+from pathlib import Path
+from typing import Any
+from unittest.mock import AsyncMock, patch
+
+import psutil
+import pytest
+from mcp_types import TextContent
+
+from fastmcp import FastMCP
+from fastmcp.client.auth.bearer import BearerAuth
+from fastmcp.client.auth.oauth import OAuthClientProvider
+from fastmcp.client.client import Client
+from fastmcp.client.logging import LogMessage
+from fastmcp.client.transports import (
+    MCPConfigTransport,
+    SSETransport,
+    StdioTransport,
+    StreamableHttpTransport,
+)
+from fastmcp.mcp_config import (
+    CanonicalMCPConfig,
+    CanonicalMCPServerTypes,
+    MCPConfig,
+    MCPServerTypes,
+    RemoteMCPServer,
+    StdioMCPServer,
+    TransformingStdioMCPServer,
+)
+from fastmcp.tools.base import Tool as FastMCPTool
+
+# These tests spawn subprocess servers via stdio which can be slow under
+# parallel CI load. Give them more headroom than the 5s default, and skip
+# entirely on Windows due to process lifecycle issues.
+pytestmark = [
+    pytest.mark.timeout(15),
+    pytest.mark.skipif(
+        sys.platform.startswith("win32"),
+        reason="Windows has process lifecycle issues with stdio subprocesses",
+    ),
+]
+
+
+def running_under_debugger():
+    return os.environ.get("DEBUGPY_RUNNING") == "true"
+
+
+def gc_collect_harder():
+    gc.collect()
+    gc.collect()
+    gc.collect()
+    gc.collect()
+    gc.collect()
+    gc.collect()
+
+
+def test_parse_single_stdio_config():
+    config = {
+        "mcpServers": {
+            "test_server": {
+                "command": "echo",
+                "args": ["hello"],
+            }
+        }
+    }
+    mcp_config = MCPConfig.from_dict(config)
+    transport = mcp_config.mcpServers["test_server"].to_transport()
+    assert isinstance(transport, StdioTransport)
+    assert transport.command == "echo"
+    assert transport.args == ["hello"]
+
+
+def test_stdio_config_keep_alive_passthrough():
+    """Test that keep_alive parameter is passed through from StdioMCPServer to StdioTransport."""
+    # Test with keep_alive=False
+    server = StdioMCPServer(command="test", keep_alive=False)
+    assert server.keep_alive is False
+    transport = server.to_transport()
+    assert isinstance(transport, StdioTransport)
+    assert transport.keep_alive is False
+
+    # Test with keep_alive=True
+    server = StdioMCPServer(command="test", keep_alive=True)
+    assert server.keep_alive is True
+    transport = server.to_transport()
+    assert isinstance(transport, StdioTransport)
+    assert transport.keep_alive is True
+
+    # Test with keep_alive=None (should default to True in StdioTransport)
+    server = StdioMCPServer(command="test", keep_alive=None)
+    assert server.keep_alive is None
+    transport = server.to_transport()
+    assert isinstance(transport, StdioTransport)
+    assert transport.keep_alive is True  # StdioTransport defaults to True
+
+    # Test with keep_alive not specified (should default to None, then True in StdioTransport)
+    server = StdioMCPServer(command="test")
+    assert server.keep_alive is None
+    transport = server.to_transport()
+    assert isinstance(transport, StdioTransport)
+    assert transport.keep_alive is True  # StdioTransport defaults to True
+
+
+def test_parse_extra_keys():
+    config = {
+        "mcpServers": {
+            "test_server": {
+                "command": "echo",
+                "args": ["hello"],
+                "leaf_extra": "leaf_extra",
+            }
+        },
+        "root_extra": "root_extra",
+    }
+    mcp_config = MCPConfig.from_dict(config)
+
+    serialized_mcp_config = mcp_config.to_dict()
+    assert serialized_mcp_config["root_extra"] == "root_extra"
+    assert (
+        serialized_mcp_config["mcpServers"]["test_server"]["leaf_extra"] == "leaf_extra"
+    )
+
+
+def test_mcp_config_file_io_uses_utf8(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """MCP config files must be read and written as UTF-8.
+
+    On Windows, Path.read_text()/write_text() default to a locale encoding such
+    as cp1252. This simulates that failure mode so Unicode config values keep
+    working on every platform.
+    """
+    config_path = tmp_path / "mcp.json"
+    raw_config = {
+        "mcpServers": {
+            "emoji_server": {
+                "command": "python",
+                "args": ["serve_✅.py"],
+                "description": "Handles café data ✅",
+            }
+        }
+    }
+    config_path.write_text(json.dumps(raw_config, ensure_ascii=False), encoding="utf-8")
+
+    original_read_text = Path.read_text
+    original_write_text = Path.write_text
+
+    def strict_read_text(self: Path, *args: Any, **kwargs: Any) -> str:
+        if kwargs.get("encoding") != "utf-8":
+            raise UnicodeDecodeError(
+                "charmap", b"\x9d", 0, 1, "simulated cp1252 default"
+            )
+        return original_read_text(self, *args, **kwargs)
+
+    def strict_write_text(self: Path, data: str, *args: Any, **kwargs: Any) -> int:
+        if kwargs.get("encoding") != "utf-8":
+            raise UnicodeEncodeError("charmap", "✅", 0, 1, "simulated cp1252 default")
+        return original_write_text(self, data, *args, **kwargs)
+
+    monkeypatch.setattr(Path, "read_text", strict_read_text)
+    monkeypatch.setattr(Path, "write_text", strict_write_text)
+
+    config = MCPConfig.from_file(config_path)
+    server = config.mcpServers["emoji_server"]
+    assert isinstance(server, StdioMCPServer)
+    assert server.args == ["serve_✅.py"]
+    assert server.description == "Handles café data ✅"
+
+    output_path = tmp_path / "written" / "mcp.json"
+    config.write_to_file(output_path)
+    output = original_read_text(output_path, encoding="utf-8")
+    assert "serve_✅.py" in output
+    assert "Handles café data ✅" in output
+
+
+def test_parse_mcpservers_at_root():
+    config = {
+        "test_server": {
+            "command": "echo",
+            "args": ["hello"],
+        }
+    }
+
+    mcp_config = MCPConfig.from_dict(config)
+
+    serialized_mcp_config = mcp_config.model_dump()
+    assert serialized_mcp_config["mcpServers"]["test_server"]["command"] == "echo"
+    assert serialized_mcp_config["mcpServers"]["test_server"]["args"] == ["hello"]
+
+
+def test_parse_mcpservers_discriminator():
+    """Test that the MCPConfig discriminator produces StdioMCPServer for a non-transforming server
+    and TransformingStdioMCPServer for a transforming server."""
+
+    config = {
+        "test_server": {
+            "command": "echo",
+            "args": ["hello"],
+        },
+        "test_server_two": {"command": "echo", "args": ["hello"], "tools": {}},
+        "test_server_three": {
+            "command": "echo",
+            "args": ["hello"],
+            "include_tags": ["my_tag"],
+        },
+    }
+
+    mcp_config = MCPConfig.from_dict(config)
+
+    test_server: MCPServerTypes = mcp_config.mcpServers["test_server"]
+    assert isinstance(test_server, StdioMCPServer)
+
+    # Empty tools dict with no tags is not a meaningful transform
+    test_server_two: MCPServerTypes = mcp_config.mcpServers["test_server_two"]
+    assert isinstance(test_server_two, StdioMCPServer)
+
+    # include_tags alone triggers transforming type
+    test_server_three: MCPServerTypes = mcp_config.mcpServers["test_server_three"]
+    assert isinstance(test_server_three, TransformingStdioMCPServer)
+
+    canonical_mcp_config = CanonicalMCPConfig.from_dict(config)
+
+    canonical_test_server: CanonicalMCPServerTypes = canonical_mcp_config.mcpServers[
+        "test_server"
+    ]
+    assert isinstance(canonical_test_server, StdioMCPServer)
+
+    canonical_test_server_two: CanonicalMCPServerTypes = (
+        canonical_mcp_config.mcpServers["test_server_two"]
+    )
+    assert isinstance(canonical_test_server_two, StdioMCPServer)
+
+
+def test_parse_single_remote_config():
+    config = {
+        "mcpServers": {
+            "test_server": {
+                "url": "http://localhost:8000",
+            }
+        }
+    }
+    mcp_config = MCPConfig.from_dict(config)
+    transport = mcp_config.mcpServers["test_server"].to_transport()
+    assert isinstance(transport, StreamableHttpTransport)
+    assert transport.url == "http://localhost:8000"
+
+
+def test_parse_remote_config_with_transport():
+    config = {
+        "mcpServers": {
+            "test_server": {
+                "url": "http://localhost:8000",
+                "transport": "sse",
+            }
+        }
+    }
+    mcp_config = MCPConfig.from_dict(config)
+    transport = mcp_config.mcpServers["test_server"].to_transport()
+    assert isinstance(transport, SSETransport)
+    assert transport.url == "http://localhost:8000"
+
+
+def test_parse_remote_config_with_url_inference():
+    config = {
+        "mcpServers": {
+            "test_server": {
+                "url": "http://localhost:8000/sse/",
+            }
+        }
+    }
+    mcp_config = MCPConfig.from_dict(config)
+    transport = mcp_config.mcpServers["test_server"].to_transport()
+    assert isinstance(transport, SSETransport)
+    assert transport.url == "http://localhost:8000/sse/"
+
+
+def test_parse_multiple_servers():
+    config = {
+        "mcpServers": {
+            "test_server": {
+                "url": "http://localhost:8000/sse/",
+            },
+            "test_server_2": {
+                "command": "echo",
+                "args": ["hello"],
+                "env": {"TEST": "test"},
+            },
+        }
+    }
+    mcp_config = MCPConfig.from_dict(config)
+    assert len(mcp_config.mcpServers) == 2
+    assert isinstance(mcp_config.mcpServers["test_server"], RemoteMCPServer)
+    assert isinstance(mcp_config.mcpServers["test_server"].to_transport(), SSETransport)
+
+    assert isinstance(mcp_config.mcpServers["test_server_2"], StdioMCPServer)
+    assert isinstance(
+        mcp_config.mcpServers["test_server_2"].to_transport(), StdioTransport
+    )
+    assert mcp_config.mcpServers["test_server_2"].command == "echo"
+    assert mcp_config.mcpServers["test_server_2"].args == ["hello"]
+    assert mcp_config.mcpServers["test_server_2"].env == {"TEST": "test"}
+
+
+async def test_multi_client(tmp_path: Path):
+    server_script = inspect.cleandoc("""
+        from fastmcp import FastMCP
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        if __name__ == '__main__':
+            mcp.run()
+        """)
+
+    script_path = tmp_path / "test.py"
+    script_path.write_text(server_script)
+
+    config = {
+        "mcpServers": {
+            "test_1": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+            "test_2": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+        }
+    }
+
+    client = Client(config)
+
+    async with client:
+        tools = await client.list_tools()
+        assert len(tools) == 2
+
+        result_1 = await client.call_tool("test_1_add", {"a": 1, "b": 2})
+        result_2 = await client.call_tool("test_2_add", {"a": 1, "b": 2})
+        assert result_1.data == 3
+        assert result_2.data == 3
+
+
+async def test_multi_client_parallel_calls(tmp_path: Path):
+    server_script = inspect.cleandoc("""
+        from fastmcp import FastMCP
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        if __name__ == '__main__':
+            mcp.run()
+        """)
+
+    script_path = tmp_path / "test.py"
+    script_path.write_text(server_script)
+
+    config = {
+        "mcpServers": {
+            "test_1": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+            "test_2": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+        }
+    }
+
+    client = Client(config)
+
+    async with client:
+        _ = await client.list_tools()
+
+        tasks = [client.list_tools() for _ in range(40)]
+
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        exceptions = [result for result in results if isinstance(result, Exception)]
+        assert len(exceptions) == 0
+        assert len(results) == 40
+        assert all(len(result) == 2 for result in results)  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+
+
+async def _wait_for_process_exit(pid: int, timeout: float = 3.0) -> None:
+    """Poll until a process has exited, raising if it's still alive after timeout."""
+
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            psutil.Process(pid)
+        except psutil.NoSuchProcess:
+            return
+        await asyncio.sleep(0.05)
+    # Final check — if still alive, let the NoSuchProcess propagation fail the test clearly
+    psutil.Process(pid)
+    pytest.fail(f"Process {pid} still alive after {timeout}s")
+
+
+@pytest.mark.skipif(
+    running_under_debugger(),
+    reason="Debugger holds a reference to the transport",
+)
+@pytest.mark.timeout(15)
+async def test_multi_client_lifespan(tmp_path: Path):
+    pid_1: int | None = None
+    pid_2: int | None = None
+
+    async def test_server():
+        server_script = inspect.cleandoc("""
+            from fastmcp import FastMCP
+            import os
+
+            mcp = FastMCP()
+
+            @mcp.tool
+            def pid() -> int:
+                return os.getpid()
+
+            if __name__ == '__main__':
+                mcp.run()
+            """)
+
+        script_path = tmp_path / "test.py"
+        script_path.write_text(server_script)
+
+        config = {
+            "mcpServers": {
+                "test_1": {
+                    "command": "python",
+                    "args": [str(script_path)],
+                },
+                "test_2": {
+                    "command": "python",
+                    "args": [str(script_path)],
+                },
+            }
+        }
+        transport = MCPConfigTransport(config)
+        client = Client(transport)
+
+        async with client:
+            nonlocal pid_1
+            pid_1 = (await client.call_tool("test_1_pid")).data
+
+            nonlocal pid_2
+            pid_2 = (await client.call_tool("test_2_pid")).data
+
+    await test_server()
+
+    gc_collect_harder()
+
+    # This test will fail while debugging because the debugger holds a reference to the underlying transport
+    assert pid_1 is not None
+    assert pid_2 is not None
+    await _wait_for_process_exit(pid_1)
+    await _wait_for_process_exit(pid_2)
+
+
+@pytest.mark.timeout(15)
+async def test_multi_client_force_close(tmp_path: Path):
+    server_script = inspect.cleandoc("""
+        from fastmcp import FastMCP
+        import os
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def pid() -> int:
+            return os.getpid()
+
+        if __name__ == '__main__':
+            mcp.run()
+        """)
+
+    script_path = tmp_path / "test.py"
+    script_path.write_text(server_script)
+
+    config = {
+        "mcpServers": {
+            "test_1": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+            "test_2": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+        }
+    }
+    transport = MCPConfigTransport(config)
+    client = Client(transport)
+
+    async with client:
+        pid_1 = (await client.call_tool("test_1_pid")).data
+        pid_2 = (await client.call_tool("test_2_pid")).data
+
+    await client.close()
+
+    gc_collect_harder()
+
+    await _wait_for_process_exit(pid_1)
+    await _wait_for_process_exit(pid_2)
+
+
+async def test_remote_config_default_no_auth():
+    config = {
+        "mcpServers": {
+            "test_server": {
+                "url": "http://localhost:8000",
+            }
+        }
+    }
+    client = Client(config)
+    assert isinstance(client.transport.transport, StreamableHttpTransport)
+    assert client.transport.transport.auth is None
+
+
+async def test_remote_config_with_auth_token():
+    config = {
+        "mcpServers": {
+            "test_server": {
+                "url": "http://localhost:8000",
+                "auth": "test_token",
+            }
+        }
+    }
+    client = Client(config)
+    assert isinstance(client.transport.transport, StreamableHttpTransport)
+    assert isinstance(client.transport.transport.auth, BearerAuth)
+    assert client.transport.transport.auth.token.get_secret_value() == "test_token"
+
+
+async def test_remote_config_sse_with_auth_token():
+    config = {
+        "mcpServers": {
+            "test_server": {
+                "url": "http://localhost:8000/sse/",
+                "auth": "test_token",
+            }
+        }
+    }
+    client = Client(config)
+    assert isinstance(client.transport.transport, SSETransport)
+    assert isinstance(client.transport.transport.auth, BearerAuth)
+    assert client.transport.transport.auth.token.get_secret_value() == "test_token"
+
+
+async def test_remote_config_with_oauth_literal():
+    config = {
+        "mcpServers": {
+            "test_server": {
+                "url": "http://localhost:8000",
+                "auth": "oauth",
+            }
+        }
+    }
+    client = Client(config)
+    assert isinstance(client.transport.transport, StreamableHttpTransport)
+    assert isinstance(client.transport.transport.auth, OAuthClientProvider)
+
+
+async def test_multi_client_with_logging(tmp_path: Path, caplog):
+    """
+    Tests that logging is properly forwarded to the ultimate client.
+    """
+    caplog.set_level(logging.INFO, logger=__name__)
+
+    server_script = inspect.cleandoc("""
+        from fastmcp import FastMCP, Context
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        async def log_test(message: str, ctx: Context) -> int:
+            await ctx.log(message)
+            return 42
+
+        if __name__ == '__main__':
+            mcp.run()
+        """)
+
+    script_path = tmp_path / "test.py"
+    script_path.write_text(server_script)
+
+    config = {
+        "mcpServers": {
+            "test_server": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+            "test_server_2": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+        }
+    }
+
+    MESSAGES = []
+
+    logger = logging.getLogger(__name__)
+    # Backwards-compatible way to get the log level mapping
+    if hasattr(logging, "getLevelNamesMapping"):
+        # For Python 3.11+
+        LOGGING_LEVEL_MAP = logging.getLevelNamesMapping()  # pyright: ignore [reportAttributeAccessIssue]
+    else:
+        # For older Python versions
+        LOGGING_LEVEL_MAP = logging._nameToLevel
+
+    async def log_handler(message: LogMessage):
+        MESSAGES.append(message)
+
+        level = LOGGING_LEVEL_MAP[message.level.upper()]
+        msg = message.data.get("msg")
+        extra = message.data.get("extra")
+        logger.log(level, msg, extra=extra)
+
+    async with Client(config, log_handler=log_handler) as client:
+        result = await client.call_tool("test_server_log_test", {"message": "test 42"})
+        assert result.data == 42
+        assert len(MESSAGES) == 1
+        assert MESSAGES[0].data["msg"] == "test 42"
+
+        # Filter to only our test logger (exclude OpenTelemetry internal logs)
+        test_records = [r for r in caplog.records if r.name == __name__]
+        assert len(test_records) == 1
+        assert test_records[0].msg == "test 42"
+
+
+async def test_multi_client_with_transforms(tmp_path: Path):
+    """
+    Tests that transforms are properly applied to the tools.
+    """
+    server_script = inspect.cleandoc("""
+        from fastmcp import FastMCP
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        if __name__ == '__main__':
+            mcp.run()
+        """)
+
+    script_path = tmp_path / "test.py"
+    script_path.write_text(server_script)
+
+    config = {
+        "mcpServers": {
+            "test_1": {
+                "command": "python",
+                "args": [str(script_path)],
+                "tools": {
+                    "add": {
+                        "name": "transformed_add",
+                        "arguments": {
+                            "a": {"name": "transformed_a"},
+                            "b": {"name": "transformed_b"},
+                        },
+                    }
+                },
+            },
+            "test_2": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+        }
+    }
+
+    client = Client[MCPConfigTransport](config)
+
+    async with client:
+        tools = await client.list_tools()
+        tools_by_name = {tool.name: tool for tool in tools}
+        assert len(tools) == 2
+        assert "test_1_transformed_add" in tools_by_name
+
+        result = await client.call_tool(
+            "test_1_transformed_add", {"transformed_a": 1, "transformed_b": 2}
+        )
+        assert result.data == 3
+
+
+async def test_canonical_multi_client_with_transforms(tmp_path: Path):
+    """Test that transforms are not applied to servers in a canonical MCPConfig."""
+    server_script = inspect.cleandoc("""
+        from fastmcp import FastMCP
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        if __name__ == '__main__':
+            mcp.run()
+        """)
+
+    script_path = tmp_path / "test.py"
+    script_path.write_text(server_script)
+
+    config = CanonicalMCPConfig(
+        mcpServers={
+            "test_1": {
+                "command": "python",
+                "args": [str(script_path)],
+                "tools": {  # <--- Will be ignored as it's not valid for a canonical MCPConfig
+                    "add": {
+                        "name": "transformed_add",
+                        "arguments": {
+                            "a": {"name": "transformed_a"},
+                            "b": {"name": "transformed_b"},
+                        },
+                    }
+                },
+            },
+            "test_2": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+        }  # type: ignore[reportUnknownArgumentType]  # ty:ignore[invalid-argument-type]
+    )
+
+    client = Client(config)
+
+    async with client:
+        tools = await client.list_tools()
+        tools_by_name = {tool.name: tool for tool in tools}
+        assert len(tools) == 2
+        assert "test_1_transformed_add" not in tools_by_name
+
+
+@pytest.mark.flaky(retries=3)
+async def test_multi_client_transform_with_filtering(tmp_path: Path):
+    """
+    Tests that tag-based filtering works when using a transforming MCPConfig.
+    """
+    server_script = inspect.cleandoc("""
+        from fastmcp import FastMCP
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        @mcp.tool
+        def subtract(a: int, b: int) -> int:
+            return a - b
+
+        if __name__ == '__main__':
+            mcp.run()
+        """)
+
+    script_path = tmp_path / "test.py"
+    script_path.write_text(server_script)
+
+    config = {
+        "mcpServers": {
+            "test_1": {
+                "command": "python",
+                "args": [str(script_path)],
+                "tools": {
+                    "add": {
+                        "name": "transformed_add",
+                        "tags": ["keep"],
+                        "arguments": {
+                            "a": {"name": "transformed_a"},
+                            "b": {"name": "transformed_b"},
+                        },
+                    },
+                },
+                "include_tags": ["keep"],
+            },
+            "test_2": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+        }
+    }
+
+    client = Client[MCPConfigTransport](config)
+
+    async with client:
+        tools = await client.list_tools()
+        tools_by_name = {tool.name: tool for tool in tools}
+        assert len(tools) == 3
+        assert "test_1_transformed_add" in tools_by_name
+        assert "test_1_add" not in tools_by_name
+        assert "test_1_subtract" not in tools_by_name
+        assert "test_2_add" in tools_by_name
+        assert "test_2_subtract" in tools_by_name
+
+
+@pytest.mark.flaky(retries=3)
+async def test_single_server_config_include_tags_filtering(tmp_path: Path):
+    """include_tags should filter tools even with a single server in the config."""
+    server_script = inspect.cleandoc("""
+        from fastmcp import FastMCP
+
+        mcp = FastMCP()
+
+        @mcp.tool(tags={"keep"})
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        @mcp.tool
+        def subtract(a: int, b: int) -> int:
+            return a - b
+
+        if __name__ == '__main__':
+            mcp.run()
+        """)
+
+    script_path = tmp_path / "test.py"
+    script_path.write_text(server_script)
+
+    config = {
+        "mcpServers": {
+            "test": {
+                "command": "python",
+                "args": [str(script_path)],
+                "include_tags": ["keep"],
+            },
+        }
+    }
+
+    client = Client(config)
+
+    async with client:
+        tools = await client.list_tools()
+        tool_names = {tool.name for tool in tools}
+        assert "add" in tool_names
+        assert "subtract" not in tool_names
+
+
+async def test_multi_client_with_elicitation(tmp_path: Path):
+    """
+    Tests that elicitation is properly forwarded to the ultimate client.
+    """
+    server_script = inspect.cleandoc("""
+        from fastmcp import FastMCP, Context
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        async def elicit_test(ctx: Context) -> int:
+            result = await ctx.elicit('Pick a number', response_type=int)
+            return result.data
+
+        if __name__ == '__main__':
+            mcp.run()
+        """)
+
+    script_path = tmp_path / "test.py"
+    script_path.write_text(server_script)
+
+    config = {
+        "mcpServers": {
+            "test_server": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+            "test_server_2": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+        }
+    }
+
+    async def elicitation_handler(message, response_type, params, ctx):
+        return response_type(value=42)
+
+    async with Client(config, elicitation_handler=elicitation_handler) as client:
+        result = await client.call_tool("test_server_elicit_test", {})
+        assert result.data == 42
+
+
+async def test_multi_server_config_transport(tmp_path: Path):
+    """
+    Tests that MCPConfigTransport properly handles multi-server configurations.
+
+    Related to https://github.com/PrefectHQ/fastmcp/issues/2802 - verifies the
+    refactored architecture creates composite servers correctly.
+    """
+    server_script = inspect.cleandoc("""
+        from fastmcp import FastMCP
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        if __name__ == '__main__':
+            mcp.run()
+        """)
+
+    script_path = tmp_path / "greet_server.py"
+    script_path.write_text(server_script)
+
+    config = {
+        "mcpServers": {
+            "server1": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+            "server2": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+        }
+    }
+
+    # Create client with multiple servers
+    client = Client(config)
+    assert isinstance(client.transport, MCPConfigTransport)
+
+    # Verify both servers are accessible via prefixed tool names
+    async with client:
+        tools = await client.list_tools()
+        tool_names = [t.name for t in tools]
+        assert "server1_greet" in tool_names
+        assert "server2_greet" in tool_names
+
+        # Call tools on both servers
+        result1 = await client.call_tool("server1_greet", {"name": "World"})
+        assert isinstance(result1.content[0], TextContent)
+        assert "Hello, World!" in result1.content[0].text
+
+        result2 = await client.call_tool("server2_greet", {"name": "FastMCP"})
+        assert isinstance(result2.content[0], TextContent)
+        assert "Hello, FastMCP!" in result2.content[0].text
+
+
+async def test_multi_server_timeout_propagation():
+    """Test that timeout is correctly propagated to proxy clients in multi-server configs."""
+    # Create a config with multiple servers
+    config = MCPConfig(
+        mcpServers={
+            "server1": StdioMCPServer(command="echo", args=["test"]),
+            "server2": StdioMCPServer(command="echo", args=["test"]),
+        }
+    )
+
+    transport = MCPConfigTransport(config)
+    # SDK v2: read_timeout_seconds is a plain number of seconds, not a timedelta.
+    timeout = 42.0
+
+    # Mock _create_proxy to avoid real stdio connections and verify timeout
+    mock_create_proxy = AsyncMock(
+        return_value=(AsyncMock(), AsyncMock(), FastMCP(name="MockProxy"))
+    )
+
+    with (
+        patch.object(transport, "_create_proxy", mock_create_proxy),
+        patch(
+            "fastmcp.client.transports.FastMCPTransport.connect_session"
+        ) as mock_connect,
+    ):
+        mock_session = AsyncMock()
+        mock_connect.return_value.__aenter__ = AsyncMock(return_value=mock_session)
+        mock_connect.return_value.__aexit__ = AsyncMock(return_value=None)
+
+        async with transport.connect_session(read_timeout_seconds=timeout):
+            pass
+
+    # Verify _create_proxy was called with the timeout for each server
+    assert mock_create_proxy.call_count == 2
+    for call in mock_create_proxy.call_args_list:
+        # Third positional arg is timeout
+        call_timeout = call[0][2] if len(call[0]) > 2 else call.kwargs.get("timeout")
+        assert call_timeout == timeout, (
+            f"Expected timeout {timeout}, got {call_timeout}"
+        )
+
+
+async def test_multi_server_session_persistence(tmp_path: Path):
+    """Test that session IDs persist across tool calls in multi-server mode.
+
+    Regression test for https://github.com/PrefectHQ/fastmcp/issues/2790 —
+    MCPConfigTransport was not connecting ProxyClients before mounting, so
+    each tool call opened a new session with the backend server.
+    """
+    server_script = inspect.cleandoc("""
+        from fastmcp import FastMCP, Context
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def get_session(ctx: Context) -> str:
+            return ctx.session_id
+
+        if __name__ == '__main__':
+            mcp.run()
+        """)
+
+    script_path = tmp_path / "session_server.py"
+    script_path.write_text(server_script)
+
+    config = {
+        "mcpServers": {
+            "server1": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+            "server2": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+        }
+    }
+
+    client = Client(config)
+    async with client:
+        result1 = await client.call_tool("server1_get_session", {})
+        assert isinstance(result1.content[0], TextContent)
+        session_id_1 = result1.content[0].text
+
+        result2 = await client.call_tool("server1_get_session", {})
+        assert isinstance(result2.content[0], TextContent)
+        session_id_2 = result2.content[0].text
+
+        assert session_id_1 == session_id_2, (
+            f"Session ID changed between calls: {session_id_1} != {session_id_2}"
+        )
+
+
+async def test_single_server_config_transport():
+    """Test that single-server configs delegate directly without creating a composite."""
+    config = MCPConfig(
+        mcpServers={
+            "only_server": StdioMCPServer(command="echo", args=["test"]),
+        }
+    )
+
+    transport = MCPConfigTransport(config)
+
+    # Single server should have transport created eagerly (not at connect time)
+    assert hasattr(transport, "transport")
+    assert isinstance(transport.transport, StdioTransport)
+
+    # _transports should already contain the single transport
+    assert len(transport._transports) == 1
+
+
+@pytest.mark.parametrize(
+    "server_order",
+    [
+        {"good_server": True, "bad_server": False},
+        {"bad_server": False, "good_server": True},
+    ],
+    ids=["good_first", "bad_first"],
+)
+async def test_multi_server_partial_failure(tmp_path: Path, server_order: dict):
+    """When one server fails to connect, the others should still work."""
+    server_script = inspect.cleandoc("""
+        from fastmcp import FastMCP
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        if __name__ == '__main__':
+            mcp.run()
+        """)
+
+    script_path = tmp_path / "test.py"
+    script_path.write_text(server_script)
+
+    servers = {}
+    for name, is_good in server_order.items():
+        if is_good:
+            servers[name] = {
+                "command": "python",
+                "args": [str(script_path)],
+            }
+        else:
+            servers[name] = {
+                "command": "this-command-does-not-exist-anywhere",
+                "args": [],
+            }
+
+    client = Client({"mcpServers": servers})
+    async with client:
+        tools = await client.list_tools()
+        tool_names = [t.name for t in tools]
+        assert "good_server_add" in tool_names
+        assert len(tools) == 1
+
+
+async def test_multi_server_partial_failure_logs_warning(tmp_path: Path, caplog):
+    """A warning should be logged when a server fails to connect."""
+    server_script = inspect.cleandoc("""
+        from fastmcp import FastMCP
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        if __name__ == '__main__':
+            mcp.run()
+        """)
+
+    script_path = tmp_path / "test.py"
+    script_path.write_text(server_script)
+
+    config = {
+        "mcpServers": {
+            "good_server": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+            "bad_server": {
+                "command": "this-command-does-not-exist-anywhere",
+                "args": [],
+            },
+        }
+    }
+
+    with caplog.at_level(logging.WARNING):
+        async with Client(config):
+            pass
+
+    warning_records = [
+        r
+        for r in caplog.records
+        if r.levelno == logging.WARNING and "bad_server" in r.message
+    ]
+    assert len(warning_records) == 1
+
+
+async def test_multi_server_all_fail():
+    """When all servers fail to connect, a ConnectionError should be raised."""
+    config = MCPConfig(
+        mcpServers={
+            "bad_1": StdioMCPServer(
+                command="this-command-does-not-exist-anywhere",
+                args=[],
+            ),
+            "bad_2": StdioMCPServer(
+                command="this-other-command-does-not-exist-either",
+                args=[],
+            ),
+        }
+    )
+
+    transport = MCPConfigTransport(config)
+    with pytest.raises(ConnectionError, match="All MCP servers failed to connect"):
+        async with transport.connect_session():
+            pass
+
+
+async def test_multi_server_partial_failure_cleanup(tmp_path: Path):
+    """Transports for failed servers should not leak into _transports."""
+    server_script = inspect.cleandoc("""
+        from fastmcp import FastMCP
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def ping() -> str:
+            return "pong"
+
+        if __name__ == '__main__':
+            mcp.run()
+        """)
+
+    script_path = tmp_path / "test.py"
+    script_path.write_text(server_script)
+
+    config = {
+        "mcpServers": {
+            "working": {
+                "command": "python",
+                "args": [str(script_path)],
+            },
+            "broken": {
+                "command": "this-command-does-not-exist-anywhere",
+                "args": [],
+            },
+        }
+    }
+
+    transport = MCPConfigTransport(config)
+    async with transport.connect_session():
+        assert len(transport._transports) == 1
+
+
+def sample_tool_fn(arg1: int, arg2: str) -> str:
+    return f"Hello, world! {arg1} {arg2}"
+
+
+@pytest.fixture
+def sample_tool() -> FastMCPTool:
+    return FastMCPTool.from_function(sample_tool_fn, name="sample_tool")
+
+
+@pytest.fixture
+async def test_script(tmp_path: Path) -> AsyncGenerator[Path, Any]:
+    with tempfile.NamedTemporaryFile() as f:
+        f.write(b"""
+        from fastmcp import FastMCP
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def fetch(url: str) -> str:
+
+            return f"Hello, world! {url}"
+
+        if __name__ == '__main__':
+            mcp.run()
+        """)
+
+        yield Path(f.name)
+
+    pass
diff --git a/tests/test_settings.py b/tests/test_settings.py
new file mode 100644
index 0000000..3052a0d
--- /dev/null
+++ b/tests/test_settings.py
@@ -0,0 +1,57 @@
+import pytest
+
+from fastmcp import settings
+from fastmcp.settings import Settings
+from fastmcp.utilities.tests import temporary_settings
+
+
+def test_get_setting_reads_nested_values():
+    test_settings = Settings()
+
+    assert test_settings.get_setting("docket__name") == "fastmcp"
+    assert test_settings.get_setting("docket__redelivery_timeout__seconds") == 300
+
+
+def test_set_setting_updates_nested_values():
+    test_settings = Settings()
+
+    test_settings.set_setting("docket__name", "worker-queue")
+
+    assert test_settings.docket.name == "worker-queue"
+    assert test_settings.get_setting("docket__name") == "worker-queue"
+
+
+def test_temporary_settings_restores_nested_values():
+    original_name = settings.get_setting("docket__name")
+
+    with temporary_settings(docket__name="temporary-queue"):
+        assert settings.get_setting("docket__name") == "temporary-queue"
+
+    assert settings.get_setting("docket__name") == original_name
+
+
+def test_get_setting_raises_for_missing_nested_parent():
+    test_settings = Settings()
+
+    with pytest.raises(AttributeError) as exc_info:
+        test_settings.get_setting("docket__missing__value")
+
+    assert str(exc_info.value) == "Setting missing does not exist."
+
+
+def test_http_host_origin_protection_defaults_to_false():
+    assert Settings().http_host_origin_protection is False
+
+
+@pytest.mark.parametrize(
+    ("value", "expected"),
+    [
+        ("auto", "auto"),
+        ("true", True),
+        ("false", False),
+    ],
+)
+def test_http_host_origin_protection_env_var(value, expected, monkeypatch):
+    monkeypatch.setenv("FASTMCP_HTTP_HOST_ORIGIN_PROTECTION", value)
+
+    assert Settings().http_host_origin_protection == expected
diff --git a/tests/tools/__init__.py b/tests/tools/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/tools/test_standalone_decorator.py b/tests/tools/test_standalone_decorator.py
new file mode 100644
index 0000000..4d57919
--- /dev/null
+++ b/tests/tools/test_standalone_decorator.py
@@ -0,0 +1,202 @@
+"""Tests for the standalone @tool decorator.
+
+The @tool decorator attaches metadata to functions without registering them
+to a server. Functions can be added explicitly via server.add_tool() or
+discovered by FileSystemProvider.
+"""
+
+import subprocess
+import sys
+from typing import cast
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.tools import tool
+from fastmcp.tools.base import Tool
+from fastmcp.tools.function_tool import DecoratedTool, FunctionTool, ToolMeta
+
+
+@pytest.mark.parametrize(
+    "statement",
+    [
+        "from fastmcp.tools import tool",
+        "from fastmcp.resources import Resource, resource",
+        "from fastmcp.prompts import Prompt, prompt",
+        "import sys; import fastmcp.apps.config; assert 'fastmcp.tools.function_tool' not in sys.modules",
+        "from fastmcp.server.auth.authorization import AuthCheck",
+        "from fastmcp.server import Context, FastMCP, create_proxy",
+    ],
+)
+def test_component_import_works_in_fresh_interpreter(statement: str):
+    result = subprocess.run(
+        [sys.executable, "-c", statement],
+        capture_output=True,
+        text=True,
+    )
+
+    assert result.returncode == 0, result.stderr
+
+
+class TestToolDecorator:
+    """Tests for the @tool decorator."""
+
+    def test_tool_without_parens(self):
+        """@tool without parentheses should attach metadata."""
+
+        @tool
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        decorated = cast(DecoratedTool, greet)
+        assert callable(greet)
+        assert hasattr(greet, "__fastmcp__")
+        assert isinstance(decorated.__fastmcp__, ToolMeta)
+        assert decorated.__fastmcp__.name is None  # Uses function name by default
+
+    def test_tool_with_empty_parens(self):
+        """@tool() with empty parentheses should attach metadata."""
+
+        @tool()
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        decorated = cast(DecoratedTool, greet)
+        assert callable(greet)
+        assert hasattr(greet, "__fastmcp__")
+        assert isinstance(decorated.__fastmcp__, ToolMeta)
+
+    def test_tool_with_name_arg(self):
+        """@tool("name") with name as first arg should work."""
+
+        @tool("custom-greet")
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        decorated = cast(DecoratedTool, greet)
+        assert callable(greet)
+        assert hasattr(greet, "__fastmcp__")
+        assert decorated.__fastmcp__.name == "custom-greet"
+
+    def test_tool_with_name_kwarg(self):
+        """@tool(name="name") with keyword arg should work."""
+
+        @tool(name="custom-greet")
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        decorated = cast(DecoratedTool, greet)
+        assert callable(greet)
+        assert hasattr(greet, "__fastmcp__")
+        assert decorated.__fastmcp__.name == "custom-greet"
+
+    def test_tool_with_all_metadata(self):
+        """@tool with all metadata should store it all."""
+
+        @tool(
+            name="custom-greet",
+            title="Greeting Tool",
+            description="Greets people",
+            tags={"greeting", "demo"},
+            meta={"custom": "value"},
+        )
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        decorated = cast(DecoratedTool, greet)
+        assert callable(greet)
+        assert hasattr(greet, "__fastmcp__")
+        assert decorated.__fastmcp__.name == "custom-greet"
+        assert decorated.__fastmcp__.title == "Greeting Tool"
+        assert decorated.__fastmcp__.description == "Greets people"
+        assert decorated.__fastmcp__.tags == {"greeting", "demo"}
+        assert decorated.__fastmcp__.meta == {"custom": "value"}
+
+    @pytest.mark.parametrize(
+        "factory", [Tool.from_function, FunctionTool.from_function]
+    )
+    def test_from_function_preserves_decorator_metadata(self, factory):
+        """Direct from_function calls should respect @tool metadata."""
+
+        @tool(
+            name="custom-greet",
+            version="v1",
+            title="Greeting Tool",
+            description="Greets people",
+            tags={"greeting", "demo"},
+            meta={"custom": "value"},
+        )
+        def greet(name: str) -> str:
+            """Fallback description."""
+            return f"Hello, {name}!"
+
+        created_tool = factory(greet)
+
+        assert created_tool.name == "custom-greet"
+        assert created_tool.version == "v1"
+        assert created_tool.title == "Greeting Tool"
+        assert created_tool.description == "Greets people"
+        assert created_tool.tags == {"greeting", "demo"}
+        assert created_tool.meta == {"custom": "value"}
+
+    async def test_tool_function_still_callable(self):
+        """Decorated function should still be directly callable."""
+
+        @tool
+        def greet(name: str) -> str:
+            """Greet someone."""
+            return f"Hello, {name}!"
+
+        # The function is still callable even though it has metadata
+        result = cast(DecoratedTool, greet)("World")
+        assert result == "Hello, World!"
+
+    def test_staticmethod_metadata_is_available_on_unwrapped_function(self):
+        """@tool should attach metadata where staticmethod access can find it."""
+
+        class MyClass:
+            @tool(name="custom-static-tool")
+            @staticmethod
+            def my_method() -> str:
+                return "hello"
+
+        created_tool = FunctionTool.from_function(MyClass.my_method)
+
+        assert created_tool.name == "custom-static-tool"
+
+    def test_tool_rejects_classmethod_decorator(self):
+        """@tool should reject classmethod-decorated functions."""
+        with pytest.raises(TypeError, match="classmethod"):
+
+            class MyClass:
+                @tool
+                @classmethod
+                def my_method(cls) -> str:
+                    return "hello"
+
+    def test_tool_with_both_name_args_raises(self):
+        """@tool should raise if both positional and keyword name are given."""
+        with pytest.raises(TypeError, match="Cannot specify.*both.*argument.*keyword"):
+
+            @tool("name1", name="name2")  # type: ignore[call-overload]  # ty:ignore[invalid-argument-type]
+            def my_tool() -> str:
+                return "hello"
+
+    async def test_tool_added_to_server(self):
+        """Tool created by @tool should work when added to a server."""
+
+        @tool
+        def greet(name: str) -> str:
+            """Greet someone."""
+            return f"Hello, {name}!"
+
+        mcp = FastMCP("Test")
+        mcp.add_tool(greet)
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            assert any(t.name == "greet" for t in tools)
+
+            result = await client.call_tool("greet", {"name": "World"})
+            assert result.data == "Hello, World!"
diff --git a/tests/tools/test_tool_future_annotations.py b/tests/tools/test_tool_future_annotations.py
new file mode 100644
index 0000000..2723843
--- /dev/null
+++ b/tests/tools/test_tool_future_annotations.py
@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal, cast
+
+import mcp_types
+from pydantic import Field
+
+from fastmcp import Context, FastMCP
+from fastmcp.client import Client
+from fastmcp.tools.base import ToolResult
+from fastmcp.utilities.types import Image
+
+fastmcp_server = FastMCP()
+
+
+@fastmcp_server.tool
+def simple_with_context(ctx: Context) -> str:
+    """Simple tool with context parameter."""
+    return f"Request ID: {ctx.request_id}"
+
+
+@fastmcp_server.tool
+def complex_types(
+    data: dict[str, Any], items: list[int], ctx: Context
+) -> dict[str, str | int]:
+    """Tool with complex type annotations."""
+    return {"count": len(items), "request_id": ctx.request_id}
+
+
+@fastmcp_server.tool
+def optional_context(name: str, ctx: Context | None = None) -> str:
+    """Tool with optional context."""
+    if ctx:
+        return f"Hello {name} from request {ctx.request_id}"
+    return f"Hello {name}"
+
+
+@fastmcp_server.tool
+def union_with_context(value: int | str, ctx: Context) -> ToolResult:
+    """Tool returning ToolResult with context."""
+    return ToolResult(content=f"Value: {value}, Request: {ctx.request_id}")
+
+
+@fastmcp_server.tool
+def returns_image(ctx: Context) -> Image:
+    """Tool that returns an Image."""
+    # Create a simple 1x1 white pixel PNG
+    png_data = b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x02\x00\x00\x00\x90wS\xde\x00\x00\x00\x0cIDATx\x9cc\xf8\x0f\x00\x00\x01\x01\x00\x05\x18\xd4c\x00\x00\x00\x00IEND\xaeB`\x82"
+    return Image(data=png_data, format="png")
+
+
+@fastmcp_server.tool
+async def async_with_context(ctx: Context) -> str:
+    """Async tool with context."""
+    return f"Async request: {ctx.request_id}"
+
+
+@fastmcp_server.tool
+def annotated_with_context(
+    query: Annotated[str, Field(description="Search query")], ctx: Context
+) -> str:
+    """Tool using Annotated + Field with context."""
+    return f"Result for: {query}"
+
+
+@fastmcp_server.tool
+def literal_with_context(mode: Literal["fast", "slow"], ctx: Context) -> str:
+    """Tool using Literal with context."""
+    return f"Mode: {mode}"
+
+
+class TestFutureAnnotations:
+    async def test_simple_with_context(self):
+        async with Client(fastmcp_server) as client:
+            result = await client.call_tool("simple_with_context", {})
+            assert "Request ID:" in cast(mcp_types.TextContent, result.content[0]).text
+
+    async def test_complex_types(self):
+        async with Client(fastmcp_server) as client:
+            result = await client.call_tool(
+                "complex_types", {"data": {"key": "value"}, "items": [1, 2, 3]}
+            )
+            # Check the result is valid JSON with expected values
+            import json
+
+            data = json.loads(cast(mcp_types.TextContent, result.content[0]).text)
+            assert data["count"] == 3
+            assert "request_id" in data
+
+    async def test_optional_context(self):
+        async with Client(fastmcp_server) as client:
+            result = await client.call_tool("optional_context", {"name": "World"})
+            assert (
+                "Hello World from request"
+                in cast(mcp_types.TextContent, result.content[0]).text
+            )
+
+    async def test_union_with_context(self):
+        async with Client(fastmcp_server) as client:
+            result = await client.call_tool("union_with_context", {"value": 42})
+            assert (
+                "Value: 42, Request:"
+                in cast(mcp_types.TextContent, result.content[0]).text
+            )
+
+    async def test_returns_image(self):
+        async with Client(fastmcp_server) as client:
+            result = await client.call_tool("returns_image", {})
+            assert result.content[0].type == "image"
+            assert result.content[0].mime_type == "image/png"
+
+    async def test_async_with_context(self):
+        async with Client(fastmcp_server) as client:
+            result = await client.call_tool("async_with_context", {})
+            assert (
+                "Async request:" in cast(mcp_types.TextContent, result.content[0]).text
+            )
+
+    async def test_annotated_with_context(self):
+        """Test Annotated[str, Field(...)] works with Context and future annotations."""
+        async with Client(fastmcp_server) as client:
+            result = await client.call_tool(
+                "annotated_with_context", {"query": "hello"}
+            )
+            assert (
+                "Result for: hello"
+                in cast(mcp_types.TextContent, result.content[0]).text
+            )
+
+    async def test_literal_with_context(self):
+        """Test Literal types work with Context and future annotations."""
+        async with Client(fastmcp_server) as client:
+            result = await client.call_tool("literal_with_context", {"mode": "fast"})
+            assert "Mode: fast" in cast(mcp_types.TextContent, result.content[0]).text
+
+    async def test_modern_union_syntax_works(self):
+        """Test that modern | union syntax works with future annotations."""
+        # This demonstrates that our solution works with | syntax when types
+        # are available in module globals
+
+        # Define a tool with modern union syntax
+        @fastmcp_server.tool
+        def modern_union_tool(value: str | int | None) -> str | None:
+            """Tool using modern | union syntax throughout."""
+            if value is None:
+                return None
+            return f"processed: {value}"
+
+        async with Client(fastmcp_server) as client:
+            # Test with string
+            result = await client.call_tool("modern_union_tool", {"value": "hello"})
+            assert (
+                "processed: hello"
+                in cast(mcp_types.TextContent, result.content[0]).text
+            )
+
+            # Test with int
+            result = await client.call_tool("modern_union_tool", {"value": 42})
+            assert (
+                "processed: 42" in cast(mcp_types.TextContent, result.content[0]).text
+            )
+
+            # Test with None
+            result = await client.call_tool("modern_union_tool", {"value": None})
+            # When function returns None, FastMCP returns empty content
+            assert (
+                len(result.content) == 0
+                or cast(mcp_types.TextContent, result.content[0]).text == "null"
+            )
+
+
+def test_closure_scoped_types_with_builtins():
+    """Closure-scoped tools work when annotations only reference builtins."""
+
+    def create_closure():
+        mcp = FastMCP()
+
+        @mcp.tool
+        def closure_tool(value: str | None) -> str:
+            return str(value)
+
+        return mcp
+
+    create_closure()
diff --git a/tests/tools/test_tool_run_in_thread.py b/tests/tools/test_tool_run_in_thread.py
new file mode 100644
index 0000000..0690249
--- /dev/null
+++ b/tests/tools/test_tool_run_in_thread.py
@@ -0,0 +1,268 @@
+"""Tests for the run_in_thread flag on sync tools.
+
+Sync tools default to running on a worker thread so they don't block the
+event loop. ``run_in_thread=False`` opts out and runs them inline on the
+event loop thread — useful for libraries with thread affinity (Windows
+COM, tkinter, etc.).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from collections.abc import AsyncIterator
+
+import pytest
+from mcp_types import TextContent
+
+from fastmcp import Context, FastMCP
+from fastmcp.tools.base import Tool
+
+
+async def _loop_thread_id() -> int:
+    return threading.get_ident()
+
+
+class TestRunInThread:
+    async def test_sync_default_runs_in_worker_thread(self):
+        """Default sync dispatch runs on a thread distinct from the loop's."""
+        mcp = FastMCP()
+        loop_tid = await _loop_thread_id()
+
+        @mcp.tool
+        def where_am_i() -> int:
+            return threading.get_ident()
+
+        result = await mcp.call_tool("where_am_i")
+        assert result.structured_content is not None
+        tid = result.structured_content["result"]
+        assert tid != loop_tid
+
+    async def test_sync_run_in_thread_false_runs_on_loop_thread(self):
+        """run_in_thread=False runs the sync fn on the event loop thread."""
+        mcp = FastMCP()
+        loop_tid = await _loop_thread_id()
+
+        @mcp.tool(run_in_thread=False)
+        def where_am_i() -> int:
+            return threading.get_ident()
+
+        result = await mcp.call_tool("where_am_i")
+        assert result.structured_content is not None
+        assert result.structured_content["result"] == loop_tid
+
+    async def test_sync_with_context_runs_on_loop_thread(self):
+        """run_in_thread=False must also apply to sync tools with injected
+        Context (or Depends).
+
+        Without this, without_injected_parameters() wraps the sync fn into an
+        async wrapper that unconditionally offloads to the thread pool —
+        silently defeating run_in_thread=False for the primary thread-affinity
+        use case (COM/tkinter tools that also want a Context for logging).
+        """
+        mcp = FastMCP()
+        loop_tid = await _loop_thread_id()
+
+        @mcp.tool(run_in_thread=False)
+        def where_am_i(ctx: Context) -> int:
+            # Context is injected; returning threading.get_ident() verifies
+            # dispatch thread, not schema generation.
+            assert ctx is not None
+            return threading.get_ident()
+
+        result = await mcp.call_tool("where_am_i")
+        assert result.structured_content is not None
+        assert result.structured_content["result"] == loop_tid
+
+    def test_sync_run_in_thread_false_rejects_timeout(self):
+        """Combining timeout with run_in_thread=False on a sync fn is rejected.
+
+        Inline execution has no cancellation checkpoints, so anyio.fail_after
+        cannot preempt the call — accepting the combination would silently
+        render the timeout a no-op. We force users to make an explicit choice.
+        """
+        mcp = FastMCP()
+
+        with pytest.raises(ValueError, match="timeout cannot be enforced"):
+
+            @mcp.tool(run_in_thread=False, timeout=5.0)
+            def blocked() -> str:
+                return "unreachable"
+
+    async def test_async_tool_allows_timeout_and_run_in_thread_false(self):
+        """run_in_thread is a no-op for async fns, so pairing with timeout is fine."""
+        mcp = FastMCP()
+
+        @mcp.tool(run_in_thread=False, timeout=5.0)
+        async def ok() -> str:
+            return "ok"
+
+        result = await mcp.call_tool("ok")
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "ok"
+
+    def test_async_generator_allowed_with_timeout_and_run_in_thread_false(self):
+        """Async generators are async even though is_coroutine_function is False.
+
+        Registration must not over-block this shape — the generator's
+        iteration has await points, so timeout enforcement still works.
+        """
+        from fastmcp.tools.base import Tool
+
+        async def stream() -> AsyncIterator[str]:
+            yield "a"
+            yield "b"
+
+        # Must not raise.
+        Tool.from_function(stream, timeout=5.0, run_in_thread=False)
+
+    async def test_async_tool_unaffected_by_run_in_thread_flag(self):
+        """The flag is a no-op for async tools (they already run on the loop)."""
+        mcp = FastMCP()
+        loop_tid = await _loop_thread_id()
+
+        @mcp.tool(run_in_thread=False)
+        async def where_am_i() -> int:
+            return threading.get_ident()
+
+        result = await mcp.call_tool("where_am_i")
+        assert result.structured_content is not None
+        assert result.structured_content["result"] == loop_tid
+
+    async def test_run_in_thread_false_blocks_other_tasks(self):
+        """A sync tool with run_in_thread=False blocks the event loop.
+
+        This documents the tradeoff: while the tool runs inline, no other
+        task on the loop makes progress. Contrast with the default path,
+        where the sync call is offloaded and concurrent tasks continue.
+        """
+        mcp = FastMCP()
+
+        @mcp.tool(run_in_thread=False)
+        def blocking() -> str:
+            import time
+
+            time.sleep(0.2)
+            return "done"
+
+        ticks = 0
+
+        async def tick() -> None:
+            nonlocal ticks
+            while True:
+                await asyncio.sleep(0.02)
+                ticks += 1
+
+        task = asyncio.create_task(tick())
+        try:
+            result = await mcp.call_tool("blocking")
+        finally:
+            task.cancel()
+            with pytest.raises(asyncio.CancelledError):
+                await task
+
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "done"
+        # With inline execution, ticks should be near zero — the 200ms sleep
+        # blocks the loop. Under a thread pool (default), ticks would be ~10.
+        assert ticks <= 2
+
+    async def test_default_threadpool_permits_concurrency(self):
+        """Sanity check: the default path does not block the loop."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def blocking() -> str:
+            import time
+
+            time.sleep(0.2)
+            return "done"
+
+        ticks = 0
+
+        async def tick() -> None:
+            nonlocal ticks
+            while True:
+                await asyncio.sleep(0.02)
+                ticks += 1
+
+        task = asyncio.create_task(tick())
+        try:
+            result = await mcp.call_tool("blocking")
+        finally:
+            task.cancel()
+            with pytest.raises(asyncio.CancelledError):
+                await task
+
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "done"
+        assert ticks >= 5
+
+
+class TestRunInThreadViaStandaloneDecorator:
+    async def test_standalone_tool_decorator_accepts_run_in_thread(self):
+        from fastmcp.tools.function_tool import tool as tool_decorator
+
+        @tool_decorator(run_in_thread=False)
+        def fn() -> int:
+            return threading.get_ident()
+
+        mcp = FastMCP()
+        mcp.add_tool(fn)
+
+        loop_tid = await _loop_thread_id()
+        result = await mcp.call_tool("fn")
+        assert result.structured_content is not None
+        assert result.structured_content["result"] == loop_tid
+
+
+class TestRunInThreadViaFileSystemProvider:
+    async def test_filesystem_provider_respects_run_in_thread(self, tmp_path):
+        """Tools discovered by FileSystemProvider honor run_in_thread=False.
+
+        FileSystemProvider extends LocalProvider and registers filesystem-
+        discovered tools via add_tool(), which reads ToolMeta.run_in_thread
+        attached by the standalone @tool decorator.
+        """
+        from fastmcp.server.providers import FileSystemProvider
+
+        (tmp_path / "where.py").write_text(
+            "import threading\n"
+            "from fastmcp.tools import tool\n\n"
+            "@tool(run_in_thread=False)\n"
+            "def where_am_i() -> int:\n"
+            "    return threading.get_ident()\n"
+        )
+
+        provider = FileSystemProvider(tmp_path)
+        mcp = FastMCP(providers=[provider])
+
+        loop_tid = await _loop_thread_id()
+        result = await mcp.call_tool("where_am_i")
+        assert result.structured_content is not None
+        assert result.structured_content["result"] == loop_tid
+
+    async def test_filesystem_provider_forwards_timeout(self, tmp_path):
+        """Filesystem discovery forwards `timeout` from ToolMeta.
+
+        Previously dropped, which let sync tools discovered via the
+        filesystem bypass both timeout enforcement and the registration-time
+        guard against combining timeout with run_in_thread=False.
+        """
+        from fastmcp.server.providers import FileSystemProvider
+
+        (tmp_path / "t.py").write_text(
+            "from fastmcp.tools import tool\n\n"
+            "@tool(timeout=5.0)\n"
+            "def quick() -> str:\n"
+            "    return 'ok'\n"
+        )
+
+        provider = FileSystemProvider(tmp_path)
+        discovered = [
+            c
+            for c in provider._components.values()
+            if isinstance(c, Tool) and c.name == "quick"
+        ]
+        assert len(discovered) == 1
+        assert discovered[0].timeout == 5.0
diff --git a/tests/tools/test_tool_timeout.py b/tests/tools/test_tool_timeout.py
new file mode 100644
index 0000000..301986f
--- /dev/null
+++ b/tests/tools/test_tool_timeout.py
@@ -0,0 +1,192 @@
+"""Tests for tool timeout functionality."""
+
+import time
+
+import anyio
+import pytest
+from mcp.shared.exceptions import MCPError
+from mcp_types import TextContent
+
+from fastmcp import FastMCP
+from fastmcp.exceptions import ToolError
+
+
+class TestToolTimeout:
+    """Test tool timeout behavior."""
+
+    async def test_no_timeout_completes_normally_async(self):
+        """Tool without timeout completes normally (async)."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        async def quick_async_tool() -> str:
+            await anyio.sleep(0.01)
+            return "completed"
+
+        result = await mcp.call_tool("quick_async_tool")
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "completed"
+
+    async def test_no_timeout_completes_normally_sync(self):
+        """Tool without timeout completes normally (sync)."""
+        mcp = FastMCP()
+
+        @mcp.tool
+        def quick_sync_tool() -> str:
+            time.sleep(0.01)
+            return "completed"
+
+        result = await mcp.call_tool("quick_sync_tool")
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "completed"
+
+    async def test_timeout_not_reached_async(self):
+        """Async tool with timeout completes before timeout."""
+        mcp = FastMCP()
+
+        @mcp.tool(timeout=5.0)
+        async def fast_async_tool() -> str:
+            await anyio.sleep(0.1)
+            return "completed"
+
+        result = await mcp.call_tool("fast_async_tool")
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "completed"
+
+    async def test_timeout_not_reached_sync(self):
+        """Sync tool with timeout completes before timeout."""
+        mcp = FastMCP()
+
+        @mcp.tool(timeout=5.0)
+        def fast_sync_tool() -> str:
+            time.sleep(0.1)
+            return "completed"
+
+        result = await mcp.call_tool("fast_sync_tool")
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "completed"
+
+    async def test_async_timeout_exceeded(self):
+        """Async tool exceeds timeout and raises TimeoutError."""
+        mcp = FastMCP()
+
+        @mcp.tool(timeout=0.2)
+        async def slow_async_tool() -> str:
+            await anyio.sleep(2.0)
+            return "should not reach"
+
+        # TimeoutError is caught and converted to ToolError by FastMCP
+        with pytest.raises(ToolError) as exc_info:
+            await mcp.call_tool("slow_async_tool")
+
+        # Verify the tool raised an error (error message may be masked)
+        assert exc_info.value is not None
+
+    async def test_sync_timeout_exceeded(self):
+        """Sync tool timeout works with CPU-bound operations."""
+        pytest.skip(
+            "Sync timeouts require thread pool execution (coming in future commit)"
+        )
+        # Note: time.sleep() blocks the event loop and cannot be interrupted
+        # by anyio.fail_after(). This will work once sync functions run in
+        # thread pools (commit 8c471a49).
+
+    async def test_timeout_error_raises_tool_error(self):
+        """Timeout error is converted to ToolError and logs warning."""
+        mcp = FastMCP()
+
+        @mcp.tool(timeout=0.1)
+        async def slow_tool() -> str:
+            await anyio.sleep(1.0)
+            return "never"
+
+        # Verify that ToolError is raised (timeout warning is logged to stderr)
+        with pytest.raises(ToolError):
+            await mcp.call_tool("slow_tool")
+
+    async def test_timeout_from_tool_from_function(self):
+        """Timeout works when using Tool.from_function()."""
+        from fastmcp.tools import Tool
+
+        async def my_slow_tool() -> str:
+            await anyio.sleep(1.0)
+            return "never"
+
+        tool = Tool.from_function(my_slow_tool, timeout=0.1)
+        mcp = FastMCP()
+        mcp.add_tool(tool)
+
+        with pytest.raises(ToolError):
+            await mcp.call_tool("my_slow_tool")
+
+    async def test_timeout_zero_times_out_immediately(self):
+        """Timeout of 0 times out immediately."""
+        mcp = FastMCP()
+
+        @mcp.tool(timeout=0.0)
+        async def instant_timeout() -> str:
+            await anyio.sleep(0)  # Give the event loop a chance to check timeout
+            return "never"
+
+        with pytest.raises(ToolError):
+            await mcp.call_tool("instant_timeout")
+
+    async def test_timeout_with_task_mode(self):
+        """Tool with timeout and task mode can be configured together."""
+        mcp = FastMCP(tasks=True)
+
+        @mcp.tool(task=True, timeout=1.0)
+        async def task_with_timeout() -> str:
+            await anyio.sleep(0.1)
+            return "completed"
+
+        # Tool should be registered successfully
+        tools = await mcp.list_tools()
+        tool = next((t for t in tools if t.name == "task_with_timeout"), None)
+        assert tool is not None
+        assert tool.timeout == 1.0
+        assert tool.task_config.supports_tasks()
+
+    async def test_multiple_tools_with_different_timeouts(self):
+        """Multiple tools can have different timeout values."""
+        mcp = FastMCP()
+
+        @mcp.tool(timeout=1.0)
+        async def short_timeout() -> str:
+            await anyio.sleep(0.1)
+            return "short"
+
+        @mcp.tool(timeout=5.0)
+        async def long_timeout() -> str:
+            await anyio.sleep(0.1)
+            return "long"
+
+        @mcp.tool
+        async def no_timeout() -> str:
+            await anyio.sleep(0.1)
+            return "none"
+
+        # All should complete successfully
+        result1 = await mcp.call_tool("short_timeout")
+        result2 = await mcp.call_tool("long_timeout")
+        result3 = await mcp.call_tool("no_timeout")
+
+        assert isinstance(result1.content[0], TextContent)
+        assert isinstance(result2.content[0], TextContent)
+        assert isinstance(result3.content[0], TextContent)
+        assert result1.content[0].text == "short"
+        assert result2.content[0].text == "long"
+        assert result3.content[0].text == "none"
+
+    async def test_timeout_error_converted_to_tool_error(self):
+        """Timeout errors are converted to ToolError by FastMCP."""
+        mcp = FastMCP()
+
+        @mcp.tool(timeout=0.1)
+        async def times_out() -> str:
+            await anyio.sleep(1.0)
+            return "never"
+
+        # TimeoutError should be caught and converted to ToolError
+        with pytest.raises((ToolError, MCPError)):
+            await mcp.call_tool("times_out")
diff --git a/tests/tools/tool/__init__.py b/tests/tools/tool/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/tools/tool/test_argument_validation.py b/tests/tools/tool/test_argument_validation.py
new file mode 100644
index 0000000..8f41cea
--- /dev/null
+++ b/tests/tools/tool/test_argument_validation.py
@@ -0,0 +1,125 @@
+"""Tests for distinguishing argument-validation errors from tool-body errors.
+
+See https://github.com/PrefectHQ/fastmcp/issues/4128: a bad call (invalid
+arguments) should surface as fastmcp's ``ValidationError`` so downstream error
+taxonomy (middleware, Sentry filters) can treat it as a client error, while a
+``pydantic.ValidationError`` raised by the tool's own body is a server-side bug
+and must propagate unchanged.
+"""
+
+from typing import Annotated, Any
+
+import pytest
+from pydantic import BaseModel, Field
+from pydantic import ValidationError as PydanticValidationError
+
+from fastmcp.exceptions import ValidationError
+from fastmcp.tools.base import Tool
+
+
+class _Inner(BaseModel):
+    x: int
+
+
+class TestArgumentValidationErrors:
+    """Invalid arguments are converted to fastmcp's ValidationError."""
+
+    async def test_async_constraint_violation(self):
+        async def tool_fn(n: Annotated[int, Field(le=10)]) -> int:
+            return n
+
+        tool = Tool.from_function(tool_fn)
+        with pytest.raises(ValidationError):
+            await tool.run({"n": 20})
+
+    async def test_sync_constraint_violation(self):
+        def tool_fn(n: Annotated[int, Field(le=10)]) -> int:
+            return n
+
+        tool = Tool.from_function(tool_fn)
+        with pytest.raises(ValidationError):
+            await tool.run({"n": 20})
+
+    async def test_wrong_type_is_argument_error(self):
+        async def tool_fn(n: int) -> int:
+            return n
+
+        tool = Tool.from_function(tool_fn)
+        with pytest.raises(ValidationError):
+            await tool.run({"n": "not-an-int"})
+
+    async def test_missing_required_argument(self):
+        async def tool_fn(n: int) -> int:
+            return n
+
+        tool = Tool.from_function(tool_fn)
+        with pytest.raises(ValidationError):
+            await tool.run({})
+
+
+class TestToolBodyErrors:
+    """A pydantic error raised by the body is NOT reclassified as a bad call."""
+
+    async def test_async_body_pydantic_error_propagates(self):
+        async def tool_fn(data: str) -> int:
+            bad_value: Any = "not-an-int"
+            _Inner(x=bad_value)  # raises a pydantic ValidationError from the body
+            return 1
+
+        tool = Tool.from_function(tool_fn)
+        with pytest.raises(PydanticValidationError):
+            await tool.run({"data": "valid"})
+        # And it must not be fastmcp's ValidationError.
+        with pytest.raises(PydanticValidationError) as exc_info:
+            await tool.run({"data": "valid"})
+        assert not isinstance(exc_info.value, ValidationError)
+
+    async def test_sync_body_pydantic_error_propagates(self):
+        def tool_fn(data: str) -> int:
+            bad_value: Any = "not-an-int"
+            _Inner(x=bad_value)  # raises a pydantic ValidationError from the body
+            return 1
+
+        tool = Tool.from_function(tool_fn)
+        with pytest.raises(PydanticValidationError):
+            await tool.run({"data": "valid"})
+
+
+class TestTaskArgumentValidation:
+    """The task-execution path (coerce_task_arguments) converts arg errors too."""
+
+    def test_coerce_task_arguments_wrong_type(self):
+        def tool_fn(n: int) -> int:
+            return n
+
+        tool = Tool.from_function(tool_fn)
+        with pytest.raises(ValidationError):
+            tool.coerce_task_arguments({"n": "not-an-int"})
+
+    def test_coerce_task_arguments_constraint_violation(self):
+        def tool_fn(n: Annotated[int, Field(le=10)]) -> int:
+            return n
+
+        tool = Tool.from_function(tool_fn)
+        with pytest.raises(ValidationError):
+            tool.coerce_task_arguments({"n": 20})
+
+
+class TestValidCallsStillWork:
+    """Regression: the happy path is unaffected."""
+
+    async def test_async_valid_call(self):
+        async def tool_fn(n: Annotated[int, Field(le=10)]) -> int:
+            return n * 2
+
+        tool = Tool.from_function(tool_fn)
+        result = await tool.run({"n": 5})
+        assert result.structured_content == {"result": 10}
+
+    async def test_sync_valid_call(self):
+        def tool_fn(n: int) -> int:
+            return n + 1
+
+        tool = Tool.from_function(tool_fn)
+        result = await tool.run({"n": 5})
+        assert result.structured_content == {"result": 6}
diff --git a/tests/tools/tool/test_callable.py b/tests/tools/tool/test_callable.py
new file mode 100644
index 0000000..888ccc1
--- /dev/null
+++ b/tests/tools/tool/test_callable.py
@@ -0,0 +1,102 @@
+import asyncio
+import threading
+
+from mcp_types import TextContent
+
+from fastmcp import Context, FastMCP
+from fastmcp.tools.base import Tool
+
+
+class TestToolCallable:
+    """Test tools with callable objects."""
+
+    async def test_callable_object_sync(self):
+        """Test that callable objects with sync __call__ work."""
+
+        class MyTool:
+            def __init__(self, multiplier: int):
+                self.multiplier = multiplier
+
+            def __call__(self, x: int) -> int:
+                return x * self.multiplier
+
+        tool = Tool.from_function(MyTool(3))
+        result = await tool.run({"x": 5})
+        assert result.content == [TextContent(type="text", text="15")]
+
+    async def test_callable_object_async(self):
+        """Test that callable objects with async __call__ work."""
+
+        class AsyncTool:
+            def __init__(self, multiplier: int):
+                self.multiplier = multiplier
+
+            async def __call__(self, x: int) -> int:
+                return x * self.multiplier
+
+        tool = Tool.from_function(AsyncTool(4))
+        result = await tool.run({"x": 5})
+        assert result.content == [TextContent(type="text", text="20")]
+
+
+class TestSyncToolConcurrency:
+    """Tests for concurrent execution of sync tools without blocking the event loop."""
+
+    async def test_sync_tools_run_concurrently(self):
+        """Test that sync tools run in threadpool and don't block each other.
+
+        Uses a threading barrier to prove concurrent execution: all calls must
+        reach the barrier simultaneously for any to proceed. If they ran
+        sequentially, only one would reach the barrier and it would time out.
+        """
+        num_calls = 3
+        # Barrier requires all threads to arrive before any proceed
+        # Short timeout since concurrent threads should arrive within milliseconds
+        barrier = threading.Barrier(num_calls, timeout=0.5)
+
+        def concurrent_tool(x: int) -> int:
+            """Tool that proves concurrency via barrier synchronization."""
+            # If calls run sequentially, only 1 thread reaches barrier and times out
+            # If calls run concurrently, all 3 reach barrier and proceed
+            barrier.wait()
+            return x * 2
+
+        tool = Tool.from_function(concurrent_tool)
+
+        # Run concurrent calls - will raise BrokenBarrierError if not concurrent
+        results = await asyncio.gather(
+            tool.run({"x": 1}),
+            tool.run({"x": 2}),
+            tool.run({"x": 3}),
+        )
+
+        # Verify results
+        assert [r.content for r in results] == [
+            [TextContent(type="text", text="2")],
+            [TextContent(type="text", text="4")],
+            [TextContent(type="text", text="6")],
+        ]
+
+    async def test_sync_tool_with_context_runs_concurrently(self):
+        """Test that sync tools with Context dependency also run concurrently."""
+        num_calls = 3
+        barrier = threading.Barrier(num_calls, timeout=0.5)
+
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def ctx_tool(x: int, ctx: Context) -> str:
+            """A sync tool with context that uses barrier to prove concurrency."""
+            barrier.wait()
+            return f"{ctx.fastmcp.name}:{x}"
+
+        # Run concurrent calls through the server interface (which sets up Context)
+        results = await asyncio.gather(
+            mcp.call_tool("ctx_tool", {"x": 1}),
+            mcp.call_tool("ctx_tool", {"x": 2}),
+            mcp.call_tool("ctx_tool", {"x": 3}),
+        )
+
+        # Verify results
+        for i, result in enumerate(results, 1):
+            assert result.content == [TextContent(type="text", text=f"test:{i}")]
diff --git a/tests/tools/tool/test_content.py b/tests/tools/tool/test_content.py
new file mode 100644
index 0000000..4d9635e
--- /dev/null
+++ b/tests/tools/tool/test_content.py
@@ -0,0 +1,550 @@
+from dataclasses import dataclass
+
+import pytest
+from inline_snapshot import snapshot
+from mcp_types import (
+    AudioContent,
+    BlobResourceContents,
+    EmbeddedResource,
+    ImageContent,
+    ResourceLink,
+    TextContent,
+    TextResourceContents,
+)
+from pydantic import BaseModel
+
+from fastmcp.tools.base import Tool, _convert_to_content
+from fastmcp.utilities.types import Audio, File, Image
+
+
+class SampleModel(BaseModel):
+    x: int
+    y: str
+
+
+class TestConvertResultToContent:
+    """Tests for the _convert_to_content helper function."""
+
+    @pytest.mark.parametrize(
+        argnames=("result", "expected"),
+        argvalues=[
+            (True, "true"),
+            ("hello", "hello"),
+            (123, "123"),
+            (123.45, "123.45"),
+            ({"key": "value"}, '{"key":"value"}'),
+            (
+                SampleModel(x=1, y="hello"),
+                '{"x":1,"y":"hello"}',
+            ),
+        ],
+        ids=[
+            "boolean",
+            "string",
+            "integer",
+            "float",
+            "object",
+            "basemodel",
+        ],
+    )
+    def test_convert_singular(self, result, expected):
+        """Test that a single item is converted to a TextContent."""
+        converted = _convert_to_content(result)
+        assert converted == [TextContent(type="text", text=expected)]
+
+    @pytest.mark.parametrize(
+        argnames=("result", "expected_text"),
+        argvalues=[
+            ([None], "[null]"),
+            ([None, None], "[null,null]"),
+            ([True], "[true]"),
+            ([True, False], "[true,false]"),
+            (["hello"], '["hello"]'),
+            (["hello", "world"], '["hello","world"]'),
+            ([123], "[123]"),
+            ([123, 456], "[123,456]"),
+            ([123.45], "[123.45]"),
+            ([123.45, 456.78], "[123.45,456.78]"),
+            ([{"key": "value"}], '[{"key":"value"}]'),
+            (
+                [{"key": "value"}, {"key2": "value2"}],
+                '[{"key":"value"},{"key2":"value2"}]',
+            ),
+            ([SampleModel(x=1, y="hello")], '[{"x":1,"y":"hello"}]'),
+            (
+                [SampleModel(x=1, y="hello"), SampleModel(x=2, y="world")],
+                '[{"x":1,"y":"hello"},{"x":2,"y":"world"}]',
+            ),
+            ([1, "two", None, {"c": 3}, False], '[1,"two",null,{"c":3},false]'),
+        ],
+        ids=[
+            "none",
+            "none_many",
+            "boolean",
+            "boolean_many",
+            "string",
+            "string_many",
+            "integer",
+            "integer_many",
+            "float",
+            "float_many",
+            "object",
+            "object_many",
+            "basemodel",
+            "basemodel_many",
+            "mixed",
+        ],
+    )
+    def test_convert_list(self, result, expected_text):
+        """Test that a list is converted to a TextContent."""
+        converted = _convert_to_content(result)
+        assert converted == [TextContent(type="text", text=expected_text)]
+
+    @pytest.mark.parametrize(
+        argnames="content_block",
+        argvalues=[
+            (TextContent(type="text", text="hello")),
+            (ImageContent(type="image", data="fakeimagedata", mime_type="image/png")),
+            (AudioContent(type="audio", data="fakeaudiodata", mime_type="audio/mpeg")),
+            (
+                ResourceLink(
+                    type="resource_link",
+                    name="test resource",
+                    uri="resource://test",
+                )
+            ),
+            (
+                EmbeddedResource(
+                    type="resource",
+                    resource=TextResourceContents(
+                        uri="resource://test",
+                        mime_type="text/plain",
+                        text="resource content",
+                    ),
+                )
+            ),
+        ],
+        ids=["text", "image", "audio", "resource link", "embedded resource"],
+    )
+    def test_convert_content_block(self, content_block):
+        converted = _convert_to_content(content_block)
+        assert converted == [content_block]
+
+        converted = _convert_to_content([content_block, content_block])
+        assert converted == [content_block, content_block]
+
+    @pytest.mark.parametrize(
+        argnames=("result", "expected"),
+        argvalues=[
+            (
+                Image(data=b"fakeimagedata"),
+                [
+                    ImageContent(
+                        type="image", data="ZmFrZWltYWdlZGF0YQ==", mime_type="image/png"
+                    )
+                ],
+            ),
+            (
+                Audio(data=b"fakeaudiodata"),
+                [
+                    AudioContent(
+                        type="audio", data="ZmFrZWF1ZGlvZGF0YQ==", mime_type="audio/wav"
+                    )
+                ],
+            ),
+            (
+                File(data=b"filedata", format="octet-stream"),
+                [
+                    EmbeddedResource(
+                        type="resource",
+                        resource=BlobResourceContents(
+                            uri="file:///resource.octet-stream",
+                            blob="ZmlsZWRhdGE=",
+                            mime_type="application/octet-stream",
+                        ),
+                    )
+                ],
+            ),
+        ],
+        ids=["image", "audio", "file"],
+    )
+    def test_convert_helpers(self, result, expected):
+        converted = _convert_to_content(result)
+        assert converted == expected
+
+        converted = _convert_to_content([result, result])
+        assert converted == expected * 2
+
+    def test_convert_mixed_content(self):
+        result = [
+            "hello",
+            123,
+            123.45,
+            {"key": "value"},
+            SampleModel(x=1, y="hello"),
+            Image(data=b"fakeimagedata"),
+            Audio(data=b"fakeaudiodata"),
+            ResourceLink(
+                type="resource_link",
+                name="test resource",
+                uri="resource://test",
+            ),
+            EmbeddedResource(
+                type="resource",
+                resource=TextResourceContents(
+                    uri="resource://test",
+                    mime_type="text/plain",
+                    text="resource content",
+                ),
+            ),
+        ]
+
+        converted = _convert_to_content(result)
+
+        assert converted == snapshot(
+            [
+                TextContent(type="text", text="hello"),
+                TextContent(type="text", text="123"),
+                TextContent(type="text", text="123.45"),
+                TextContent(type="text", text='{"key":"value"}'),
+                TextContent(type="text", text='{"x":1,"y":"hello"}'),
+                ImageContent(
+                    type="image", data="ZmFrZWltYWdlZGF0YQ==", mime_type="image/png"
+                ),
+                AudioContent(
+                    type="audio", data="ZmFrZWF1ZGlvZGF0YQ==", mime_type="audio/wav"
+                ),
+                ResourceLink(
+                    name="test resource",
+                    uri="resource://test",
+                    type="resource_link",
+                ),
+                EmbeddedResource(
+                    type="resource",
+                    resource=TextResourceContents(
+                        uri="resource://test",
+                        mime_type="text/plain",
+                        text="resource content",
+                    ),
+                ),
+            ]
+        )
+
+    def test_empty_list(self):
+        """Test that an empty list results in an empty list."""
+        result = _convert_to_content([])
+        assert isinstance(result, list)
+        assert len(result) == 0
+
+    def test_empty_dict(self):
+        """Test that an empty dictionary is converted to TextContent."""
+        result = _convert_to_content({})
+        assert isinstance(result, list)
+        assert len(result) == 1
+        assert isinstance(result[0], TextContent)
+        assert result[0].text == "{}"
+
+
+class TestAutomaticStructuredContent:
+    """Tests for automatic structured content generation based on return types."""
+
+    async def test_dict_return_creates_structured_content_without_schema(self):
+        """Test that dict returns automatically create structured content even without output schema."""
+
+        def get_user_data(user_id: str) -> dict:
+            return {"name": "Alice", "age": 30, "active": True}
+
+        # No explicit output schema provided
+        tool = Tool.from_function(get_user_data)
+
+        result = await tool.run({"user_id": "123"})
+
+        # Should have both content and structured content
+        assert len(result.content) == 1
+        assert isinstance(result.content[0], TextContent)
+        assert result.structured_content == {"name": "Alice", "age": 30, "active": True}
+
+    async def test_dataclass_return_creates_structured_content_without_schema(self):
+        """Test that dataclass returns automatically create structured content even without output schema."""
+
+        @dataclass
+        class UserProfile:
+            name: str
+            age: int
+            email: str
+
+        def get_profile(user_id: str) -> UserProfile:
+            return UserProfile(name="Bob", age=25, email="bob@example.com")
+
+        # No explicit output schema, but dataclass should still create structured content
+        tool = Tool.from_function(get_profile, output_schema=None)
+
+        result = await tool.run({"user_id": "456"})
+
+        # Should have both content and structured content
+        assert len(result.content) == 1
+        assert isinstance(result.content[0], TextContent)
+        # Dataclass should serialize to dict
+        assert result.structured_content == {
+            "name": "Bob",
+            "age": 25,
+            "email": "bob@example.com",
+        }
+
+    async def test_pydantic_model_return_creates_structured_content_without_schema(
+        self,
+    ):
+        """Test that Pydantic model returns automatically create structured content even without output schema."""
+
+        class UserData(BaseModel):
+            username: str
+            score: int
+            verified: bool
+
+        def get_user_stats(user_id: str) -> UserData:
+            return UserData(username="charlie", score=100, verified=True)
+
+        # Explicitly set output schema to None to test automatic structured content
+        tool = Tool.from_function(get_user_stats, output_schema=None)
+
+        result = await tool.run({"user_id": "789"})
+
+        # Should have both content and structured content
+        assert len(result.content) == 1
+        assert isinstance(result.content[0], TextContent)
+        # Pydantic model should serialize to dict
+        assert result.structured_content == {
+            "username": "charlie",
+            "score": 100,
+            "verified": True,
+        }
+
+    async def test_self_referencing_dataclass_not_wrapped(self):
+        """Test that self-referencing dataclasses are not wrapped in result field."""
+
+        @dataclass
+        class ReturnThing:
+            value: int
+            stuff: list["ReturnThing"]
+
+        def return_things() -> ReturnThing:
+            return ReturnThing(value=123, stuff=[ReturnThing(value=456, stuff=[])])
+
+        tool = Tool.from_function(return_things)
+
+        result = await tool.run({})
+
+        # Should have structured content without wrapping
+        assert result.structured_content is not None
+        # Should NOT be wrapped in "result" field
+        assert "result" not in result.structured_content
+        # Should have the actual data directly
+        assert result.structured_content == {
+            "value": 123,
+            "stuff": [{"value": 456, "stuff": []}],
+        }
+
+    async def test_self_referencing_pydantic_model_has_type_object_at_root(self):
+        """Test that self-referencing Pydantic models have type: object at root.
+
+        MCP spec requires outputSchema to have "type": "object" at the root level.
+        Pydantic generates schemas with $ref at root for self-referential models,
+        which violates this requirement. FastMCP should resolve the $ref.
+
+        Regression test for issue #2455.
+        """
+
+        class Issue(BaseModel):
+            id: str
+            title: str
+            dependencies: list["Issue"] = []
+            dependents: list["Issue"] = []
+
+        def get_issue(issue_id: str) -> Issue:
+            return Issue(id=issue_id, title="Test")
+
+        tool = Tool.from_function(get_issue)
+
+        # The output schema should have "type": "object" at root, not $ref
+        assert tool.output_schema is not None
+        assert tool.output_schema.get("type") == "object"
+        assert "properties" in tool.output_schema
+        # Should still have $defs for nested references
+        assert "$defs" in tool.output_schema
+        # Should NOT have $ref at root level
+        assert "$ref" not in tool.output_schema
+
+    async def test_self_referencing_model_outputschema_mcp_compliant(self):
+        """Test that self-referencing model schemas are MCP spec compliant.
+
+        The MCP spec requires:
+        - type: "object" at root level
+        - properties field
+        - required field (optional)
+
+        This ensures clients can properly validate the schema.
+
+        Regression test for issue #2455.
+        """
+
+        class Node(BaseModel):
+            id: str
+            children: list["Node"] = []
+
+        def get_node() -> Node:
+            return Node(id="1")
+
+        tool = Tool.from_function(get_node)
+
+        # Schema should be MCP-compliant
+        assert tool.output_schema is not None
+        assert tool.output_schema.get("type") == "object", (
+            "MCP spec requires 'type': 'object' at root"
+        )
+        assert "properties" in tool.output_schema
+        assert "id" in tool.output_schema["properties"]
+        assert "children" in tool.output_schema["properties"]
+        # Required should include 'id'
+        assert "id" in tool.output_schema.get("required", [])
+
+    async def test_int_return_no_structured_content_without_schema(self):
+        """Test that int returns don't create structured content without output schema."""
+
+        def calculate_sum(a: int, b: int):
+            """No return annotation."""
+            return a + b
+
+        # No output schema
+        tool = Tool.from_function(calculate_sum)
+
+        result = await tool.run({"a": 5, "b": 3})
+
+        # Should only have content, no structured content
+        assert len(result.content) == 1
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "8"
+        assert result.structured_content is None
+
+    async def test_str_return_no_structured_content_without_schema(self):
+        """Test that str returns don't create structured content without output schema."""
+
+        def get_greeting(name: str):
+            """No return annotation."""
+            return f"Hello, {name}!"
+
+        # No output schema
+        tool = Tool.from_function(get_greeting)
+
+        result = await tool.run({"name": "World"})
+
+        # Should only have content, no structured content
+        assert len(result.content) == 1
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "Hello, World!"
+        assert result.structured_content is None
+
+    async def test_list_return_no_structured_content_without_schema(self):
+        """Test that list returns don't create structured content without output schema."""
+
+        def get_numbers():
+            """No return annotation."""
+            return [1, 2, 3, 4, 5]
+
+        # No output schema
+        tool = Tool.from_function(get_numbers)
+
+        result = await tool.run({})
+
+        assert result.structured_content is None
+        assert result.content == snapshot(
+            [TextContent(type="text", text="[1,2,3,4,5]")]
+        )
+
+    async def test_audio_return_creates_no_structured_content(self):
+        """Test that audio returns don't create structured content."""
+
+        def get_audio() -> AudioContent:
+            """No return annotation."""
+            return Audio(data=b"fakeaudiodata").to_audio_content()
+
+        # No output schema
+        tool = Tool.from_function(get_audio)
+
+        result = await tool.run({})
+
+        assert result.content == snapshot(
+            [
+                AudioContent(
+                    type="audio", data="ZmFrZWF1ZGlvZGF0YQ==", mime_type="audio/wav"
+                )
+            ]
+        )
+        assert result.structured_content is None
+
+    async def test_int_return_with_schema_creates_structured_content(self):
+        """Test that int returns DO create structured content when there's an output schema."""
+
+        def calculate_sum(a: int, b: int) -> int:
+            """With return annotation."""
+            return a + b
+
+        # Output schema should be auto-generated from annotation
+        tool = Tool.from_function(calculate_sum)
+        assert tool.output_schema is not None
+
+        result = await tool.run({"a": 5, "b": 3})
+
+        # Should have both content and structured content
+        assert len(result.content) == 1
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "8"
+        assert result.structured_content == {"result": 8}
+
+    async def test_client_automatic_deserialization_with_dict_result(self):
+        """Test that clients automatically deserialize dict results from structured content."""
+        from fastmcp import FastMCP
+        from fastmcp.client import Client
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def get_user_info(user_id: str) -> dict:
+            return {"name": "Alice", "age": 30, "active": True}
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("get_user_info", {"user_id": "123"})
+
+            # Client should provide the deserialized data
+            assert result.data == {"name": "Alice", "age": 30, "active": True}
+            assert result.structured_content == {
+                "name": "Alice",
+                "age": 30,
+                "active": True,
+            }
+            assert len(result.content) == 1
+
+    async def test_client_automatic_deserialization_with_dataclass_result(self):
+        """Test that clients automatically deserialize dataclass results from structured content."""
+        from fastmcp import FastMCP
+        from fastmcp.client import Client
+
+        mcp = FastMCP()
+
+        @dataclass
+        class UserProfile:
+            name: str
+            age: int
+            verified: bool
+
+        @mcp.tool
+        def get_profile(user_id: str) -> UserProfile:
+            return UserProfile(name="Bob", age=25, verified=True)
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("get_profile", {"user_id": "456"})
+
+            # Client should deserialize back to a dataclass (but type name is lost with title pruning)
+            assert result.data.__class__.__name__ == "Root"
+            assert result.data.name == "Bob"
+            assert result.data.age == 25
+            assert result.data.verified is True
diff --git a/tests/tools/tool/test_output_schema.py b/tests/tools/tool/test_output_schema.py
new file mode 100644
index 0000000..d63089b
--- /dev/null
+++ b/tests/tools/tool/test_output_schema.py
@@ -0,0 +1,608 @@
+from dataclasses import dataclass
+from typing import Annotated, Any
+
+import pytest
+from inline_snapshot import snapshot
+from mcp_types import AudioContent, EmbeddedResource, ImageContent, TextContent
+from pydantic import AnyUrl, BaseModel, Field, TypeAdapter
+from typing_extensions import TypedDict
+
+from fastmcp.tools.base import Tool, ToolResult
+from fastmcp.utilities.json_schema import compress_schema
+from fastmcp.utilities.types import Audio, File, Image
+
+
+class TestToolFromFunctionOutputSchema:
+    async def test_no_return_annotation(self):
+        def func():
+            pass
+
+        tool = Tool.from_function(func)
+        assert tool.output_schema is None
+
+    @pytest.mark.parametrize(
+        "annotation",
+        [
+            int,
+            float,
+            bool,
+            str,
+            int | float,
+            list,
+            list[int],
+            list[int | float],
+            dict,
+            dict[str, Any],
+            dict[str, int | None],
+            tuple[int, str],
+            set[int],
+            list[tuple[int, str]],
+        ],
+    )
+    async def test_simple_return_annotation(self, annotation):
+        def func() -> annotation:
+            return 1
+
+        tool = Tool.from_function(func)
+
+        base_schema = TypeAdapter(annotation).json_schema()
+
+        # Non-object types get wrapped
+        schema_type = base_schema.get("type")
+        is_object_type = schema_type == "object"
+
+        if not is_object_type:
+            # Non-object types get wrapped
+            expected_schema = {
+                "type": "object",
+                "properties": {"result": base_schema},
+                "required": ["result"],
+                "x-fastmcp-wrap-result": True,
+            }
+            assert tool.output_schema == expected_schema
+            # # Note: Parameterized test - keeping original assertion for multiple parameter values
+        else:
+            # Object types remain unwrapped
+            assert tool.output_schema == base_schema
+
+    @pytest.mark.parametrize(
+        "annotation",
+        [
+            AnyUrl,
+            Annotated[int, Field(ge=1)],
+            Annotated[int, Field(ge=1)],
+        ],
+    )
+    async def test_complex_return_annotation(self, annotation):
+        def func() -> annotation:
+            return 1
+
+        tool = Tool.from_function(func)
+
+        base_schema = TypeAdapter(annotation).json_schema()
+        expected_schema = {
+            "type": "object",
+            "properties": {"result": base_schema},
+            "required": ["result"],
+            "x-fastmcp-wrap-result": True,
+        }
+        assert tool.output_schema == expected_schema
+
+    async def test_none_return_annotation(self):
+        def func() -> None:
+            pass
+
+        tool = Tool.from_function(func)
+        assert tool.output_schema is None
+
+    async def test_any_return_annotation(self):
+        from typing import Any
+
+        def func() -> Any:
+            return 1
+
+        tool = Tool.from_function(func)
+        assert tool.output_schema is None
+
+    @pytest.mark.parametrize(
+        "annotation, expected",
+        [
+            (Image, ImageContent),
+            (Audio, AudioContent),
+            (File, EmbeddedResource),
+            (Image | int, ImageContent | int),
+            (Image | Audio, ImageContent | AudioContent),
+            (list[Image | Audio], list[ImageContent | AudioContent]),
+        ],
+    )
+    async def test_converted_return_annotation(self, annotation, expected):
+        def func() -> annotation:
+            return 1
+
+        tool = Tool.from_function(func)
+        # Image, Audio, File types don't generate output schemas since they're converted to content directly
+        assert tool.output_schema is None
+
+    async def test_tool_result_return_annotation_no_output_schema(self):
+        def func() -> ToolResult:
+            return ToolResult(content="hello")
+
+        tool = Tool.from_function(func)
+        assert tool.output_schema is None
+
+    async def test_tool_result_subclass_return_annotation_no_output_schema(self):
+        class MyToolResult(ToolResult):
+            def __init__(self, data: str):
+                super().__init__(structured_content={"content": data})
+
+        def func() -> MyToolResult:
+            return MyToolResult("hello")
+
+        tool = Tool.from_function(func)
+        assert tool.output_schema is None
+
+    async def test_optional_tool_result_subclass_no_output_schema(self):
+        class MyToolResult(ToolResult):
+            pass
+
+        def func() -> MyToolResult | None:
+            return None
+
+        tool = Tool.from_function(func)
+        assert tool.output_schema is None
+
+    async def test_dataclass_return_annotation(self):
+        @dataclass
+        class Person:
+            name: str
+            age: int
+
+        def func() -> Person:
+            return Person(name="John", age=30)
+
+        tool = Tool.from_function(func)
+        expected_schema = compress_schema(
+            TypeAdapter(Person).json_schema(), prune_titles=True
+        )
+        assert tool.output_schema == expected_schema
+
+    async def test_base_model_return_annotation(self):
+        class Person(BaseModel):
+            name: str
+            age: int
+
+        def func() -> Person:
+            return Person(name="John", age=30)
+
+        tool = Tool.from_function(func)
+
+        assert tool.output_schema == snapshot(
+            {
+                "properties": {
+                    "name": {"type": "string"},
+                    "age": {"type": "integer"},
+                },
+                "required": ["name", "age"],
+                "type": "object",
+            }
+        )
+
+    async def test_typeddict_return_annotation(self):
+        class Person(TypedDict):
+            name: str
+            age: int
+
+        def func() -> Person:
+            return Person(name="John", age=30)
+
+        tool = Tool.from_function(func)
+        assert tool.output_schema == snapshot(
+            {
+                "properties": {
+                    "name": {"type": "string"},
+                    "age": {"type": "integer"},
+                },
+                "required": ["name", "age"],
+                "type": "object",
+            }
+        )
+
+    async def test_unserializable_return_annotation(self):
+        class Unserializable:
+            def __init__(self, data: Any):
+                self.data = data
+
+        def func() -> Unserializable:
+            return Unserializable(data="test")
+
+        tool = Tool.from_function(func)
+        assert tool.output_schema is None
+
+    async def test_mixed_unserializable_return_annotation(self):
+        class Unserializable:
+            def __init__(self, data: Any):
+                self.data = data
+
+        def func() -> Unserializable | int:
+            return Unserializable(data="test")
+
+        tool = Tool.from_function(func)
+        assert tool.output_schema is None
+
+    async def test_provided_output_schema_takes_precedence_over_json_compatible_annotation(
+        self,
+    ):
+        """Test that provided output_schema takes precedence over inferred schema from JSON-compatible annotation."""
+
+        def func() -> dict[str, int]:
+            return {"a": 1, "b": 2}
+
+        # Provide a custom output schema that differs from the inferred one
+        custom_schema = {"type": "object", "description": "Custom schema"}
+
+        tool = Tool.from_function(func, output_schema=custom_schema)
+        assert tool.output_schema == custom_schema
+
+    async def test_provided_output_schema_takes_precedence_over_complex_annotation(
+        self,
+    ):
+        """Test that provided output_schema takes precedence over inferred schema from complex annotation."""
+
+        def func() -> list[dict[str, int | float]]:
+            return [{"a": 1, "b": 2.5}]
+
+        # Provide a custom output schema that differs from the inferred one
+        custom_schema = {"type": "object", "properties": {"custom": {"type": "string"}}}
+
+        tool = Tool.from_function(func, output_schema=custom_schema)
+        assert tool.output_schema == custom_schema
+
+    async def test_provided_output_schema_takes_precedence_over_unserializable_annotation(
+        self,
+    ):
+        """Test that provided output_schema takes precedence over None schema from unserializable annotation."""
+
+        class Unserializable:
+            def __init__(self, data: Any):
+                self.data = data
+
+        def func() -> Unserializable:
+            return Unserializable(data="test")
+
+        # Provide a custom output schema even though the annotation is unserializable
+        custom_schema = {
+            "type": "object",
+            "properties": {"items": {"type": "array", "items": {"type": "string"}}},
+        }
+
+        tool = Tool.from_function(func, output_schema=custom_schema)
+        assert tool.output_schema == custom_schema
+
+    async def test_provided_output_schema_takes_precedence_over_no_annotation(self):
+        """Test that provided output_schema takes precedence over None schema from no annotation."""
+
+        def func():
+            return "hello"
+
+        # Provide a custom output schema even though there's no return annotation
+        custom_schema = {
+            "type": "object",
+            "properties": {"value": {"type": "number", "minimum": 0}},
+        }
+
+        tool = Tool.from_function(func, output_schema=custom_schema)
+        assert tool.output_schema == custom_schema
+
+    async def test_provided_output_schema_takes_precedence_over_converted_annotation(
+        self,
+    ):
+        """Test that provided output_schema takes precedence over converted schema from Image/Audio/File annotations."""
+
+        def func() -> Image:
+            return Image(data=b"test")
+
+        # Provide a custom output schema that differs from the converted ImageContent schema
+        custom_schema = {
+            "type": "object",
+            "properties": {"custom_image": {"type": "string"}},
+        }
+
+        tool = Tool.from_function(func, output_schema=custom_schema)
+        assert tool.output_schema == custom_schema
+
+    async def test_provided_output_schema_takes_precedence_over_union_annotation(self):
+        """Test that provided output_schema takes precedence over inferred schema from union annotation."""
+
+        def func() -> str | int | None:
+            return "hello"
+
+        # Provide a custom output schema that differs from the inferred union schema
+        custom_schema = {"type": "object", "properties": {"flag": {"type": "boolean"}}}
+
+        tool = Tool.from_function(func, output_schema=custom_schema)
+        assert tool.output_schema == custom_schema
+
+    async def test_provided_output_schema_takes_precedence_over_pydantic_annotation(
+        self,
+    ):
+        """Test that provided output_schema takes precedence over inferred schema from Pydantic model annotation."""
+
+        class Person(BaseModel):
+            name: str
+            age: int
+
+        def func() -> Person:
+            return Person(name="John", age=30)
+
+        # Provide a custom output schema that differs from the inferred Person schema
+        custom_schema = {
+            "type": "object",
+            "properties": {"numbers": {"type": "array", "items": {"type": "number"}}},
+        }
+
+        tool = Tool.from_function(func, output_schema=custom_schema)
+        assert tool.output_schema == custom_schema
+
+    async def test_output_schema_false_allows_automatic_structured_content(self):
+        """Test that output_schema=False still allows automatic structured content for dict-like objects."""
+
+        def func() -> dict[str, str]:
+            return {"message": "Hello, world!"}
+
+        tool = Tool.from_function(func, output_schema=None)
+        assert tool.output_schema is None
+
+        result = await tool.run({})
+        # Dict objects automatically become structured content even without schema
+        assert result.structured_content == {"message": "Hello, world!"}
+        assert len(result.content) == 1
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == '{"message":"Hello, world!"}'
+
+    async def test_output_schema_none_disables_structured_content(self):
+        """Test that output_schema=None explicitly disables structured content."""
+
+        def func() -> int:
+            return 42
+
+        tool = Tool.from_function(func, output_schema=None)
+        assert tool.output_schema is None
+
+        result = await tool.run({})
+        assert result.structured_content is None
+        assert len(result.content) == 1
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "42"
+
+    async def test_output_schema_inferred_when_not_specified(self):
+        """Test that output schema is inferred when not explicitly specified."""
+
+        def func() -> int:
+            return 42
+
+        # Don't specify output_schema - should infer and wrap
+        tool = Tool.from_function(func)
+        assert tool.output_schema == snapshot(
+            {
+                "properties": {"result": {"type": "integer"}},
+                "required": ["result"],
+                "type": "object",
+                "x-fastmcp-wrap-result": True,
+            }
+        )
+
+        result = await tool.run({})
+        assert result.structured_content == {"result": 42}
+
+    async def test_explicit_object_schema_with_dict_return(self):
+        """Test that explicit object schemas work when function returns a dict."""
+
+        def func() -> dict[str, int]:
+            return {"value": 42}
+
+        # Provide explicit object schema
+        explicit_schema = {
+            "type": "object",
+            "properties": {"value": {"type": "integer", "minimum": 0}},
+        }
+        tool = Tool.from_function(func, output_schema=explicit_schema)
+        assert tool.output_schema == explicit_schema  # Schema not wrapped
+        assert tool.output_schema and "x-fastmcp-wrap-result" not in tool.output_schema
+
+        result = await tool.run({})
+        # Dict result with object schema is used directly
+        assert result.structured_content == {"value": 42}
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == '{"value":42}'
+
+    async def test_explicit_object_schema_with_non_dict_return_fails(self):
+        """Test that explicit object schemas fail when function returns non-dict."""
+
+        def func() -> int:
+            return 42
+
+        # Provide explicit object schema but return non-dict
+        explicit_schema = {
+            "type": "object",
+            "properties": {"value": {"type": "integer"}},
+        }
+        tool = Tool.from_function(func, output_schema=explicit_schema)
+
+        # Should fail because int is not dict-compatible with object schema
+        with pytest.raises(ValueError, match="structured_content must be a dict"):
+            await tool.run({})
+
+    async def test_object_output_schema_not_wrapped(self):
+        """Test that object-type output schemas are never wrapped."""
+
+        def func() -> dict[str, int]:
+            return {"value": 42}
+
+        # Object schemas should never be wrapped, even when inferred
+        tool = Tool.from_function(func)
+        expected_schema = TypeAdapter(dict[str, int]).json_schema()
+        assert tool.output_schema == expected_schema  # Not wrapped
+        assert tool.output_schema and "x-fastmcp-wrap-result" not in tool.output_schema
+
+        result = await tool.run({})
+        assert result.structured_content == {"value": 42}  # Direct value
+
+    async def test_structured_content_interaction_with_wrapping(self):
+        """Test that structured content works correctly with schema wrapping."""
+
+        def func() -> str:
+            return "hello"
+
+        # Inferred schema should wrap string type
+        tool = Tool.from_function(func)
+        assert tool.output_schema == snapshot(
+            {
+                "properties": {"result": {"type": "string"}},
+                "required": ["result"],
+                "type": "object",
+                "x-fastmcp-wrap-result": True,
+            }
+        )
+
+        result = await tool.run({})
+        # Unstructured content
+        assert len(result.content) == 1
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "hello"
+        # Structured content should be wrapped
+        assert result.structured_content == {"result": "hello"}
+
+    async def test_structured_content_with_explicit_object_schema(self):
+        """Test structured content with explicit object schema."""
+
+        def func() -> dict[str, str]:
+            return {"greeting": "hello"}
+
+        # Provide explicit object schema
+        explicit_schema = {
+            "type": "object",
+            "properties": {"greeting": {"type": "string"}},
+            "required": ["greeting"],
+        }
+        tool = Tool.from_function(func, output_schema=explicit_schema)
+        assert tool.output_schema == explicit_schema
+
+        result = await tool.run({})
+        # Should use direct value since explicit schema doesn't have wrap marker
+        assert result.structured_content == {"greeting": "hello"}
+
+    async def test_structured_content_with_custom_wrapper_schema(self):
+        """Test structured content with custom schema that includes wrap marker."""
+
+        def func() -> str:
+            return "world"
+
+        # Custom schema with wrap marker
+        custom_schema = {
+            "type": "object",
+            "properties": {"message": {"type": "string"}},
+            "x-fastmcp-wrap-result": True,
+        }
+        tool = Tool.from_function(func, output_schema=custom_schema)
+        assert tool.output_schema == custom_schema
+
+        result = await tool.run({})
+        # Should wrap with "result" key due to wrap marker
+        assert result.structured_content == {"result": "world"}
+
+    async def test_none_vs_false_output_schema_behavior(self):
+        """Test the difference between None and False for output_schema."""
+
+        def func() -> int:
+            return 123
+
+        # None should disable
+        tool_none = Tool.from_function(func, output_schema=None)
+        assert tool_none.output_schema is None
+
+        # Default (NotSet) should infer from return type
+        tool_default = Tool.from_function(func)
+        assert (
+            tool_default.output_schema is not None
+        )  # Should infer schema from dict return type
+
+        # Different behavior: None vs inferred
+        result_none = await tool_none.run({})
+        result_default = await tool_default.run({})
+
+        # None should still try fallback generation but fail for non-dict
+        assert result_none.structured_content is None  # Fallback fails for int
+        # Default should use proper schema and wrap the result
+        assert result_default.structured_content == {
+            "result": 123
+        }  # Schema-based generation with wrapping
+        assert isinstance(result_none.content[0], TextContent)
+        assert isinstance(result_default.content[0], TextContent)
+        assert result_none.content[0].text == result_default.content[0].text == "123"
+
+    async def test_non_object_output_schema_raises_error(self):
+        """Test that providing a non-object output schema raises a ValueError."""
+
+        def func() -> int:
+            return 42
+
+        # Test various non-object schemas that should raise errors
+        non_object_schemas = [
+            {"type": "string"},
+            {"type": "integer", "minimum": 0},
+            {"type": "number"},
+            {"type": "boolean"},
+            {"type": "array", "items": {"type": "string"}},
+        ]
+
+        for schema in non_object_schemas:
+            with pytest.raises(
+                ValueError, match="Output schemas must represent object types"
+            ):
+                Tool.from_function(func, output_schema=schema)
+
+
+class TestWrapResultMeta:
+    async def test_list_return_includes_wrap_result_meta(self):
+        """A tool returning list[dict] should set wrap_result in meta."""
+
+        def func() -> list[dict]:
+            return [{"a": 1}, {"b": 2}]
+
+        tool = Tool.from_function(func)
+        result = await tool.run({})
+        assert result.structured_content == {"result": [{"a": 1}, {"b": 2}]}
+        assert result.meta == {"fastmcp": {"wrap_result": True}}
+
+    async def test_int_return_includes_wrap_result_meta(self):
+        """A tool returning int should set wrap_result in meta."""
+
+        def func() -> int:
+            return 42
+
+        tool = Tool.from_function(func)
+        result = await tool.run({})
+        assert result.structured_content == {"result": 42}
+        assert result.meta == {"fastmcp": {"wrap_result": True}}
+
+    async def test_dict_return_does_not_include_wrap_result_meta(self):
+        """A tool returning dict should NOT set wrap_result in meta."""
+
+        def func() -> dict[str, int]:
+            return {"value": 42}
+
+        tool = Tool.from_function(func)
+        result = await tool.run({})
+        assert result.structured_content == {"value": 42}
+        assert result.meta is None
+
+    async def test_no_schema_dict_return_no_meta(self):
+        """A tool without output schema returning dict should not set meta."""
+
+        def func():
+            return {"key": "val"}
+
+        tool = Tool.from_function(func)
+        result = await tool.run({})
+        assert result.structured_content == {"key": "val"}
+        assert result.meta is None
diff --git a/tests/tools/tool/test_results.py b/tests/tools/tool/test_results.py
new file mode 100644
index 0000000..830d5f1
--- /dev/null
+++ b/tests/tools/tool/test_results.py
@@ -0,0 +1,395 @@
+import json
+from dataclasses import dataclass
+from typing import Annotated, Any
+
+import pytest
+from mcp_types import CallToolResult, TextContent
+from pydantic import BaseModel, ConfigDict, Field
+
+from fastmcp import Client, FastMCP
+from fastmcp.tools.base import Tool, ToolResult
+
+
+class TestToolResultCasting:
+    @pytest.fixture
+    async def client(self):
+        from fastmcp import FastMCP
+        from fastmcp.client import Client
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def test_tool(
+            unstructured: str | None = None,
+            structured: dict[str, Any] | None = None,
+            meta: dict[str, Any] | None = None,
+        ):
+            return ToolResult(
+                content=unstructured,
+                structured_content=structured,
+                meta=meta,
+            )
+
+        async with Client(mcp) as client:
+            yield client
+
+    async def test_only_unstructured_content(self, client):
+        result = await client.call_tool("test_tool", {"unstructured": "test data"})
+
+        assert result.content[0].type == "text"
+        assert result.content[0].text == "test data"
+        assert result.structured_content is None
+        assert result.meta is None
+
+    async def test_neither_unstructured_or_structured_content(self, client):
+        from fastmcp.exceptions import ToolError
+
+        with pytest.raises(ToolError):
+            await client.call_tool("test_tool", {})
+
+    async def test_structured_and_unstructured_content(self, client):
+        result = await client.call_tool(
+            "test_tool",
+            {"unstructured": "test data", "structured": {"data_type": "test"}},
+        )
+
+        assert result.content[0].type == "text"
+        assert result.content[0].text == "test data"
+        assert result.structured_content == {"data_type": "test"}
+        assert result.meta is None
+
+    async def test_structured_unstructured_and_meta_content(self, client):
+        result = await client.call_tool(
+            "test_tool",
+            {
+                "unstructured": "test data",
+                "structured": {"data_type": "test"},
+                "meta": {"some": "metadata"},
+            },
+        )
+
+        assert result.content[0].type == "text"
+        assert result.content[0].text == "test data"
+        assert result.structured_content == {"data_type": "test"}
+        assert result.meta == {"some": "metadata"}
+
+
+class TestToolResultIsError:
+    """A tool can return an error result (isError) instead of raising."""
+
+    def test_to_mcp_result_sets_iserror_and_preserves_content(self):
+        result = ToolResult(
+            content="boom", structured_content={"code": 42}, is_error=True
+        )
+        mcp_result = result.to_mcp_result()
+        assert isinstance(mcp_result, CallToolResult)
+        assert mcp_result.is_error is True
+        assert isinstance(mcp_result.content[0], TextContent)
+        assert mcp_result.content[0].text == "boom"
+        assert mcp_result.structured_content == {"code": 42}
+
+    def test_default_is_not_error(self):
+        result = ToolResult(content="ok")
+        assert result.is_error is False
+
+    async def test_returned_error_raises_on_client_by_default(self):
+        from fastmcp import FastMCP
+        from fastmcp.client import Client
+        from fastmcp.exceptions import ToolError
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def failing() -> ToolResult:
+            return ToolResult(content="upstream boom", is_error=True)
+
+        async with Client(mcp) as client:
+            with pytest.raises(ToolError):
+                await client.call_tool("failing", {})
+
+    async def test_returned_error_preserves_content_when_not_raising(self):
+        from fastmcp import FastMCP
+        from fastmcp.client import Client
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def failing() -> ToolResult:
+            return ToolResult(content="upstream boom", is_error=True)
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("failing", {}, raise_on_error=False)
+
+        assert result.is_error is True
+        assert result.content[0].text == "upstream boom"
+
+
+class TestUnionReturnTypes:
+    """Tests for tools with union return types."""
+
+    async def test_dataclass_union_string_works(self):
+        """Test that union of dataclass and string works correctly."""
+
+        @dataclass
+        class Data:
+            value: int
+
+        def get_data(return_error: bool) -> Data | str:
+            if return_error:
+                return "error occurred"
+            return Data(value=42)
+
+        tool = Tool.from_function(get_data)
+
+        # Test returning dataclass
+        result1 = await tool.run({"return_error": False})
+        assert result1.structured_content == {"result": {"value": 42}}
+
+        # Test returning string
+        result2 = await tool.run({"return_error": True})
+        assert result2.structured_content == {"result": "error occurred"}
+
+
+class TestSerializationAlias:
+    """Tests for Pydantic field serialization alias support in tool output schemas."""
+
+    def test_output_schema_respects_serialization_alias(self):
+        """Test that Tool.from_function generates output schema using serialization alias."""
+        from typing import Annotated
+
+        from pydantic import AliasChoices, BaseModel, Field
+
+        class Component(BaseModel):
+            """Model with multiple validation aliases but specific serialization alias."""
+
+            component_id: str = Field(
+                validation_alias=AliasChoices("id", "componentId"),
+                serialization_alias="componentId",
+                description="The ID of the component",
+            )
+
+        async def get_component(
+            component_id: str,
+        ) -> Annotated[Component, Field(description="The component.")]:
+            # API returns data with 'id' field
+            api_data = {"id": component_id}
+            return Component.model_validate(api_data)
+
+        tool = Tool.from_function(get_component, name="get-component")
+
+        # The output schema should use the serialization alias 'componentId'
+        # not the first validation alias 'id'
+        assert tool.output_schema is not None
+
+        # Object schemas have properties directly at root (MCP spec compliance)
+        # Root-level $refs are resolved to ensure type: object at root
+        assert "properties" in tool.output_schema
+        assert tool.output_schema.get("type") == "object"
+
+        # Should have 'componentId' not 'id' in properties
+        assert "componentId" in tool.output_schema["properties"]
+        assert "id" not in tool.output_schema["properties"]
+
+        # Should require 'componentId' not 'id'
+        assert "componentId" in tool.output_schema.get("required", [])
+        assert "id" not in tool.output_schema.get("required", [])
+
+    async def test_tool_execution_with_serialization_alias(self):
+        """Test that tool execution works correctly with serialization aliases."""
+        from typing import Annotated
+
+        from pydantic import AliasChoices, BaseModel, Field
+
+        from fastmcp import Client, FastMCP
+
+        class Component(BaseModel):
+            """Model with multiple validation aliases but specific serialization alias."""
+
+            component_id: str = Field(
+                validation_alias=AliasChoices("id", "componentId"),
+                serialization_alias="componentId",
+                description="The ID of the component",
+            )
+
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        async def get_component(
+            component_id: str,
+        ) -> Annotated[Component, Field(description="The component.")]:
+            # API returns data with 'id' field
+            api_data = {"id": component_id}
+            return Component.model_validate(api_data)
+
+        async with Client(mcp) as client:
+            # Execute the tool - this should work without validation errors
+            result = await client.call_tool(
+                "get_component", {"component_id": "test123"}
+            )
+
+            # The result should contain the serialized form with 'componentId'
+            assert result.structured_content is not None
+            # Object types may be wrapped in "result" or not, depending on schema structure
+            if "result" in result.structured_content:
+                component_data = result.structured_content["result"]
+            else:
+                component_data = result.structured_content
+            assert component_data["componentId"] == "test123"
+            assert "id" not in component_data
+
+
+class TestSerializeByAlias:
+    """Tests that a model's serialize_by_alias config is honored at runtime.
+
+    pydantic_core's serialization helpers default by_alias to True, which
+    silently ignores serialize_by_alias=False. The serialized result and the
+    generated output schema must both reflect the model's configured behavior.
+    """
+
+    async def test_serialize_by_alias_false_uses_field_names(self):
+        """serialize_by_alias=False emits field names in schema, structured, and text."""
+
+        class Biofile(BaseModel):
+            model_config = ConfigDict(serialize_by_alias=False)
+            id: str = Field(alias="_id")
+            filepath: str
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def get_biofile() -> Annotated[Biofile, Field(description="data")]:
+            return Biofile(_id="123", filepath="/p")
+
+        async with Client(mcp) as client:
+            tools = {t.name: t for t in await client.list_tools()}
+            result = await client.call_tool("get_biofile", {})
+
+        assert result.structured_content == {"id": "123", "filepath": "/p"}
+        assert json.loads(result.content[0].text) == {  # type: ignore[union-attr]
+            "id": "123",
+            "filepath": "/p",
+        }
+        assert set(tools["get_biofile"].output_schema["properties"]) == {  # type: ignore[index]
+            "id",
+            "filepath",
+        }
+
+    async def test_unset_config_preserves_alias_default(self):
+        """A model with an alias but no serialize config keeps emitting the alias."""
+
+        class Biofile(BaseModel):
+            id: str = Field(alias="_id")
+            filepath: str
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def get_biofile() -> Biofile:
+            return Biofile(_id="123", filepath="/p")
+
+        async with Client(mcp) as client:
+            tools = {t.name: t for t in await client.list_tools()}
+            result = await client.call_tool("get_biofile", {})
+
+        assert result.structured_content == {"_id": "123", "filepath": "/p"}
+        assert set(tools["get_biofile"].output_schema["properties"]) == {  # type: ignore[index]
+            "_id",
+            "filepath",
+        }
+
+    async def test_serialize_by_alias_true_uses_alias(self):
+        """serialize_by_alias=True emits aliases, same as the default."""
+
+        class Biofile(BaseModel):
+            model_config = ConfigDict(serialize_by_alias=True)
+            id: str = Field(alias="_id")
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def get_biofile() -> Biofile:
+            return Biofile(_id="123")
+
+        async with Client(mcp) as client:
+            tools = {t.name: t for t in await client.list_tools()}
+            result = await client.call_tool("get_biofile", {})
+
+        assert result.structured_content == {"_id": "123"}
+        assert set(tools["get_biofile"].output_schema["properties"]) == {"_id"}  # type: ignore[index]
+
+    async def test_nested_models_respect_config(self):
+        """serialize_by_alias=False propagates through nested models."""
+
+        class Inner(BaseModel):
+            model_config = ConfigDict(serialize_by_alias=False)
+            inner_id: str = Field(alias="_iid")
+
+        class Outer(BaseModel):
+            model_config = ConfigDict(serialize_by_alias=False)
+            id: str = Field(alias="_id")
+            inner: Inner
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def get_outer() -> Outer:
+            return Outer(_id="1", inner=Inner(_iid="2"))
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("get_outer", {})
+
+        assert result.structured_content == {"id": "1", "inner": {"inner_id": "2"}}
+
+    async def test_annotated_optional_return_stays_consistent(self):
+        """Annotated[Model, ...] | None resolves the model inside the union arm.
+
+        Regression: the union arm is a typing.Annotated object, so a naive
+        isinstance check skipped the model and the schema fell back to aliases
+        while the runtime serialized field names, breaking client validation.
+        """
+
+        class Biofile(BaseModel):
+            model_config = ConfigDict(serialize_by_alias=False)
+            id: str = Field(alias="_id")
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def get_biofile() -> Annotated[Biofile, Field(description="x")] | None:
+            return Biofile(_id="1")
+
+        async with Client(mcp) as client:
+            tools = {t.name: t for t in await client.list_tools()}
+            # client-side validation of structured content against the schema
+            # raises if they disagree
+            result = await client.call_tool("get_biofile", {})
+
+        schema_props = set(tools["get_biofile"].output_schema["properties"])  # type: ignore[index]
+        assert schema_props == set(result.structured_content)  # type: ignore[arg-type]
+        assert result.structured_content == {"result": {"id": "1"}}
+
+    @pytest.mark.parametrize("serialize_by_alias", [True, False, None])
+    async def test_schema_and_structured_content_agree(self, serialize_by_alias):
+        """The output schema field names always match the structured content keys."""
+        if serialize_by_alias is None:
+            config = ConfigDict()
+        else:
+            config = ConfigDict(serialize_by_alias=serialize_by_alias)
+
+        class Model(BaseModel):
+            model_config = config
+            id: str = Field(alias="_id")
+            name: str
+
+        mcp = FastMCP()
+
+        @mcp.tool
+        def get_model() -> Model:
+            return Model(_id="1", name="x")
+
+        async with Client(mcp) as client:
+            tools = {t.name: t for t in await client.list_tools()}
+            result = await client.call_tool("get_model", {})
+
+        schema_props = set(tools["get_model"].output_schema["properties"])  # type: ignore[index]
+        assert schema_props == set(result.structured_content)  # type: ignore[arg-type]
diff --git a/tests/tools/tool/test_title.py b/tests/tools/tool/test_title.py
new file mode 100644
index 0000000..29c0c1a
--- /dev/null
+++ b/tests/tools/tool/test_title.py
@@ -0,0 +1,95 @@
+from fastmcp.tools.base import Tool
+
+
+class TestToolTitle:
+    """Tests for tool title functionality."""
+
+    def test_tool_with_title(self):
+        """Test that tools can have titles and they appear in MCP conversion."""
+
+        def calculate(x: int, y: int) -> int:
+            """Calculate the sum of two numbers."""
+            return x + y
+
+        tool = Tool.from_function(
+            calculate,
+            name="calc",
+            title="Advanced Calculator Tool",
+            description="Custom description",
+        )
+
+        assert tool.name == "calc"
+        assert tool.title == "Advanced Calculator Tool"
+        assert tool.description == "Custom description"
+
+        # Test MCP conversion includes title
+        mcp_tool = tool.to_mcp_tool()
+        assert mcp_tool.name == "calc"
+        assert (
+            hasattr(mcp_tool, "title") and mcp_tool.title == "Advanced Calculator Tool"
+        )
+
+    def test_tool_without_title(self):
+        """Test that tools without titles use name as display name."""
+
+        def multiply(a: int, b: int) -> int:
+            return a * b
+
+        tool = Tool.from_function(multiply)
+
+        assert tool.name == "multiply"
+        assert tool.title is None
+
+        # Test MCP conversion doesn't include title when None
+        mcp_tool = tool.to_mcp_tool()
+        assert mcp_tool.name == "multiply"
+        assert not hasattr(mcp_tool, "title") or mcp_tool.title is None
+
+    def test_tool_title_priority(self):
+        """Test that explicit title takes priority over annotations.title."""
+        from mcp_types import ToolAnnotations
+
+        def divide(x: int, y: int) -> float:
+            """Divide two numbers."""
+            return x / y
+
+        # Test with both explicit title and annotations.title
+        annotations = ToolAnnotations(title="Annotation Title")
+        tool = Tool.from_function(
+            divide,
+            name="div",
+            title="Explicit Title",
+            annotations=annotations,
+        )
+
+        assert tool.title == "Explicit Title"
+        assert tool.annotations is not None
+        assert tool.annotations.title == "Annotation Title"
+
+        # Explicit title should take priority
+        mcp_tool = tool.to_mcp_tool()
+        assert mcp_tool.title == "Explicit Title"
+
+    def test_tool_annotations_title_fallback(self):
+        """Test that annotations.title is used when no explicit title is provided."""
+        from mcp_types import ToolAnnotations
+
+        def modulo(x: int, y: int) -> int:
+            """Get modulo of two numbers."""
+            return x % y
+
+        # Test with only annotations.title (no explicit title)
+        annotations = ToolAnnotations(title="Annotation Title")
+        tool = Tool.from_function(
+            modulo,
+            name="mod",
+            annotations=annotations,
+        )
+
+        assert tool.title is None
+        assert tool.annotations is not None
+        assert tool.annotations.title == "Annotation Title"
+
+        # Should fall back to annotations.title
+        mcp_tool = tool.to_mcp_tool()
+        assert mcp_tool.title == "Annotation Title"
diff --git a/tests/tools/tool/test_tool.py b/tests/tools/tool/test_tool.py
new file mode 100644
index 0000000..d877b70
--- /dev/null
+++ b/tests/tools/tool/test_tool.py
@@ -0,0 +1,612 @@
+from datetime import timedelta
+
+import pytest
+from dirty_equals import HasName
+from inline_snapshot import snapshot
+from mcp_types import (
+    AudioContent,
+    ImageContent,
+    ToolExecution,
+)
+from pydantic import BaseModel
+
+from fastmcp.tools.base import Tool, ToolResult
+from fastmcp.utilities.types import Audio, File, Image
+
+
+class TestToolFromFunction:
+    def test_basic_function(self):
+        """Test registering and running a basic function."""
+
+        def add(a: int, b: int) -> int:
+            """Add two numbers."""
+            return a + b
+
+        tool = Tool.from_function(add)
+
+        assert tool.model_dump(exclude_none=True) == snapshot(
+            {
+                "name": "add",
+                "description": "Add two numbers.",
+                "tags": set(),
+                "parameters": {
+                    "additionalProperties": False,
+                    "properties": {
+                        "a": {"type": "integer"},
+                        "b": {"type": "integer"},
+                    },
+                    "required": ["a", "b"],
+                    "type": "object",
+                },
+                "output_schema": {
+                    "properties": {"result": {"type": "integer"}},
+                    "required": ["result"],
+                    "type": "object",
+                    "x-fastmcp-wrap-result": True,
+                },
+                "fn": HasName("add"),
+                "task_config": {
+                    "mode": "forbidden",
+                    "poll_interval": timedelta(seconds=5),
+                },
+                "run_in_thread": True,
+            }
+        )
+
+    def test_meta_parameter(self):
+        """Test that meta parameter is properly handled."""
+
+        def multiply(a: int, b: int) -> int:
+            """Multiply two numbers."""
+            return a * b
+
+        meta_data = {"version": "1.0", "author": "test"}
+        tool = Tool.from_function(multiply, meta=meta_data)
+
+        assert tool.meta == meta_data
+        mcp_tool = tool.to_mcp_tool()
+
+        # MCP tool includes fastmcp meta, so check that our meta is included
+        assert mcp_tool.meta is not None
+        assert meta_data.items() <= mcp_tool.meta.items()
+
+    async def test_async_function(self):
+        """Test registering and running an async function."""
+
+        async def fetch_data(url: str) -> str:
+            """Fetch data from URL."""
+            return f"Data from {url}"
+
+        tool = Tool.from_function(fetch_data)
+
+        assert tool.model_dump(exclude_none=True) == snapshot(
+            {
+                "name": "fetch_data",
+                "description": "Fetch data from URL.",
+                "tags": set(),
+                "parameters": {
+                    "additionalProperties": False,
+                    "properties": {"url": {"type": "string"}},
+                    "required": ["url"],
+                    "type": "object",
+                },
+                "output_schema": {
+                    "properties": {"result": {"type": "string"}},
+                    "required": ["result"],
+                    "type": "object",
+                    "x-fastmcp-wrap-result": True,
+                },
+                "fn": HasName("fetch_data"),
+                "task_config": {
+                    "mode": "forbidden",
+                    "poll_interval": timedelta(seconds=5),
+                },
+                "run_in_thread": True,
+            }
+        )
+
+    def test_callable_object(self):
+        class Adder:
+            """Adds two numbers."""
+
+            def __call__(self, x: int, y: int) -> int:
+                """ignore this"""
+                return x + y
+
+        tool = Tool.from_function(Adder())
+
+        assert tool.model_dump(exclude_none=True, exclude={"fn"}) == snapshot(
+            {
+                "name": "Adder",
+                "description": "Adds two numbers.",
+                "tags": set(),
+                "parameters": {
+                    "additionalProperties": False,
+                    "properties": {
+                        "x": {"type": "integer"},
+                        "y": {"type": "integer"},
+                    },
+                    "required": ["x", "y"],
+                    "type": "object",
+                },
+                "output_schema": {
+                    "properties": {"result": {"type": "integer"}},
+                    "required": ["result"],
+                    "type": "object",
+                    "x-fastmcp-wrap-result": True,
+                },
+                "task_config": {
+                    "mode": "forbidden",
+                    "poll_interval": timedelta(seconds=5),
+                },
+                "run_in_thread": True,
+            }
+        )
+
+    def test_async_callable_object(self):
+        class Adder:
+            """Adds two numbers."""
+
+            async def __call__(self, x: int, y: int) -> int:
+                """ignore this"""
+                return x + y
+
+        tool = Tool.from_function(Adder())
+
+        assert tool.model_dump(exclude_none=True, exclude={"fn"}) == snapshot(
+            {
+                "name": "Adder",
+                "description": "Adds two numbers.",
+                "tags": set(),
+                "parameters": {
+                    "additionalProperties": False,
+                    "properties": {
+                        "x": {"type": "integer"},
+                        "y": {"type": "integer"},
+                    },
+                    "required": ["x", "y"],
+                    "type": "object",
+                },
+                "output_schema": {
+                    "properties": {"result": {"type": "integer"}},
+                    "required": ["result"],
+                    "type": "object",
+                    "x-fastmcp-wrap-result": True,
+                },
+                "task_config": {
+                    "mode": "forbidden",
+                    "poll_interval": timedelta(seconds=5),
+                },
+                "run_in_thread": True,
+            }
+        )
+
+    def test_pydantic_model_function(self):
+        """Test registering a function that takes a Pydantic model."""
+
+        class UserInput(BaseModel):
+            name: str
+            age: int
+
+        def create_user(user: UserInput, flag: bool) -> dict:
+            """Create a new user."""
+            return {"id": 1, **user.model_dump()}
+
+        tool = Tool.from_function(create_user)
+
+        assert tool.model_dump(exclude_none=True) == snapshot(
+            {
+                "name": "create_user",
+                "description": "Create a new user.",
+                "tags": set(),
+                "parameters": {
+                    "$defs": {
+                        "UserInput": {
+                            "properties": {
+                                "name": {"type": "string"},
+                                "age": {"type": "integer"},
+                            },
+                            "required": ["name", "age"],
+                            "type": "object",
+                        },
+                    },
+                    "additionalProperties": False,
+                    "properties": {
+                        "user": {"$ref": "#/$defs/UserInput"},
+                        "flag": {"type": "boolean"},
+                    },
+                    "required": ["user", "flag"],
+                    "type": "object",
+                },
+                "output_schema": {"additionalProperties": True, "type": "object"},
+                "fn": HasName("create_user"),
+                "task_config": {
+                    "mode": "forbidden",
+                    "poll_interval": timedelta(seconds=5),
+                },
+                "run_in_thread": True,
+            }
+        )
+
+    async def test_tool_with_image_return(self):
+        def image_tool(data: bytes) -> Image:
+            return Image(data=data)
+
+        tool = Tool.from_function(image_tool)
+        assert tool.parameters["properties"]["data"]["type"] == "string"
+        assert tool.output_schema is None
+
+        result = await tool.run({"data": "test.png"})
+        assert isinstance(result.content[0], ImageContent)
+
+    async def test_tool_with_audio_return(self):
+        def audio_tool(data: bytes) -> Audio:
+            return Audio(data=data)
+
+        tool = Tool.from_function(audio_tool)
+        assert tool.parameters["properties"]["data"]["type"] == "string"
+        assert tool.output_schema is None
+
+        result = await tool.run({"data": "test.wav"})
+        assert isinstance(result.content[0], AudioContent)
+
+    async def test_tool_with_file_return(self):
+        def file_tool(data: bytes) -> File:
+            return File(data=data, format="octet-stream")
+
+        tool = Tool.from_function(file_tool)
+        assert tool.parameters["properties"]["data"]["type"] == "string"
+        assert tool.output_schema is None
+
+        result: ToolResult = await tool.run({"data": "test.bin"})
+        assert result.content[0].model_dump(exclude_none=True) == snapshot(
+            {
+                "type": "resource",
+                "resource": {
+                    "uri": "file:///resource.octet-stream",
+                    "mime_type": "application/octet-stream",
+                    "blob": "dGVzdC5iaW4=",
+                },
+            }
+        )
+
+    def test_non_callable_fn(self):
+        with pytest.raises(TypeError, match="not a callable object"):
+            Tool.from_function(1)  # type: ignore
+
+    def test_lambda(self):
+        tool = Tool.from_function(lambda x: x, name="my_tool")
+        assert tool.model_dump(exclude_none=True, exclude={"fn"}) == snapshot(
+            {
+                "name": "my_tool",
+                "tags": set(),
+                "parameters": {
+                    "additionalProperties": False,
+                    "properties": {"x": {}},
+                    "required": ["x"],
+                    "type": "object",
+                },
+                "task_config": {
+                    "mode": "forbidden",
+                    "poll_interval": timedelta(seconds=5),
+                },
+                "run_in_thread": True,
+            }
+        )
+
+    def test_lambda_with_no_name(self):
+        with pytest.raises(
+            ValueError, match="You must provide a name for lambda functions"
+        ):
+            Tool.from_function(lambda x: x)
+
+    def test_private_arguments(self):
+        def add(_a: int, _b: int) -> int:
+            """Add two numbers."""
+            return _a + _b
+
+        tool = Tool.from_function(add)
+
+        assert tool.model_dump(
+            exclude_none=True, exclude={"output_schema", "fn"}
+        ) == snapshot(
+            {
+                "name": "add",
+                "description": "Add two numbers.",
+                "tags": set(),
+                "parameters": {
+                    "additionalProperties": False,
+                    "properties": {
+                        "_a": {"type": "integer"},
+                        "_b": {"type": "integer"},
+                    },
+                    "required": ["_a", "_b"],
+                    "type": "object",
+                },
+                "task_config": {
+                    "mode": "forbidden",
+                    "poll_interval": timedelta(seconds=5),
+                },
+                "run_in_thread": True,
+            }
+        )
+
+    def test_tool_with_varargs_not_allowed(self):
+        def func(a: int, b: int, *args: int) -> int:
+            """Add two numbers."""
+            return a + b
+
+        with pytest.raises(
+            ValueError, match=r"Functions with \*args are not supported as tools"
+        ):
+            Tool.from_function(func)
+
+    def test_tool_with_varkwargs_not_allowed(self):
+        def func(a: int, b: int, **kwargs: int) -> int:
+            """Add two numbers."""
+            return a + b
+
+        with pytest.raises(
+            ValueError, match=r"Functions with \*\*kwargs are not supported as tools"
+        ):
+            Tool.from_function(func)
+
+    async def test_instance_method(self):
+        class MyClass:
+            def add(self, x: int, y: int) -> int:
+                """Add two numbers."""
+                return x + y
+
+        obj = MyClass()
+
+        tool = Tool.from_function(obj.add)
+        assert "self" not in tool.parameters["properties"]
+
+        assert tool.model_dump(exclude_none=True, exclude={"fn"}) == snapshot(
+            {
+                "name": "add",
+                "description": "Add two numbers.",
+                "tags": set(),
+                "parameters": {
+                    "additionalProperties": False,
+                    "properties": {
+                        "x": {"type": "integer"},
+                        "y": {"type": "integer"},
+                    },
+                    "required": ["x", "y"],
+                    "type": "object",
+                },
+                "output_schema": {
+                    "properties": {"result": {"type": "integer"}},
+                    "required": ["result"],
+                    "type": "object",
+                    "x-fastmcp-wrap-result": True,
+                },
+                "task_config": {
+                    "mode": "forbidden",
+                    "poll_interval": timedelta(seconds=5),
+                },
+                "run_in_thread": True,
+            }
+        )
+
+    async def test_instance_method_with_varargs_not_allowed(self):
+        class MyClass:
+            def add(self, x: int, y: int, *args: int) -> int:
+                """Add two numbers."""
+                return x + y
+
+        obj = MyClass()
+
+        with pytest.raises(
+            ValueError, match=r"Functions with \*args are not supported as tools"
+        ):
+            Tool.from_function(obj.add)
+
+    async def test_instance_method_with_varkwargs_not_allowed(self):
+        class MyClass:
+            def add(self, x: int, y: int, **kwargs: int) -> int:
+                """Add two numbers."""
+                return x + y
+
+        obj = MyClass()
+
+        with pytest.raises(
+            ValueError, match=r"Functions with \*\*kwargs are not supported as tools"
+        ):
+            Tool.from_function(obj.add)
+
+    async def test_classmethod(self):
+        class MyClass:
+            x: int = 10
+
+            @classmethod
+            def call(cls, x: int, y: int) -> int:
+                """Add two numbers."""
+                return x + y
+
+        tool = Tool.from_function(MyClass.call)
+        assert tool.name == "call"
+        assert tool.description == "Add two numbers."
+        assert "x" in tool.parameters["properties"]
+        assert "y" in tool.parameters["properties"]
+
+
+class TestToolNameValidation:
+    """Tests for tool name validation per MCP specification (SEP-986)."""
+
+    @pytest.fixture
+    def caplog_for_mcp_validation(self, caplog):
+        """Capture logs from the MCP SDK's tool name validation logger."""
+        import logging
+
+        caplog.set_level(logging.WARNING)
+        logger = logging.getLogger("mcp.shared.tool_name_validation")
+        original_level = logger.level
+        logger.setLevel(logging.WARNING)
+        logger.addHandler(caplog.handler)
+        try:
+            yield caplog
+        finally:
+            logger.removeHandler(caplog.handler)
+            logger.setLevel(original_level)
+
+    @pytest.mark.parametrize(
+        "name",
+        [
+            "valid_tool",
+            "valid-tool",
+            "valid.tool",
+            "ValidTool",
+            "tool123",
+            "a",
+            "a" * 128,
+        ],
+    )
+    def test_valid_tool_names_no_warnings(self, name, caplog_for_mcp_validation):
+        """Valid tool names should not produce warnings."""
+
+        def fn() -> str:
+            return "test"
+
+        tool = Tool.from_function(fn, name=name)
+        assert tool.name == name
+        assert "Tool name validation warning" not in caplog_for_mcp_validation.text
+
+    def test_tool_name_with_spaces_warns(self, caplog_for_mcp_validation):
+        """Tool names with spaces should produce a warning."""
+
+        def fn() -> str:
+            return "test"
+
+        tool = Tool.from_function(fn, name="my tool")
+        assert tool.name == "my tool"
+        assert "Tool name validation warning" in caplog_for_mcp_validation.text
+        assert "contains spaces" in caplog_for_mcp_validation.text
+
+    def test_tool_name_with_invalid_chars_warns(self, caplog_for_mcp_validation):
+        """Tool names with invalid characters should produce a warning."""
+
+        def fn() -> str:
+            return "test"
+
+        tool = Tool.from_function(fn, name="tool@name!")
+        assert tool.name == "tool@name!"
+        assert "Tool name validation warning" in caplog_for_mcp_validation.text
+        assert "invalid characters" in caplog_for_mcp_validation.text
+
+    def test_tool_name_too_long_warns(self, caplog_for_mcp_validation):
+        """Tool names exceeding 128 characters should produce a warning."""
+
+        def fn() -> str:
+            return "test"
+
+        long_name = "a" * 129
+        tool = Tool.from_function(fn, name=long_name)
+        assert tool.name == long_name
+        assert "Tool name validation warning" in caplog_for_mcp_validation.text
+        assert "exceeds maximum length" in caplog_for_mcp_validation.text
+
+    def test_tool_name_with_leading_dash_warns(self, caplog_for_mcp_validation):
+        """Tool names starting with dash should produce a warning."""
+
+        def fn() -> str:
+            return "test"
+
+        tool = Tool.from_function(fn, name="-tool")
+        assert tool.name == "-tool"
+        assert "Tool name validation warning" in caplog_for_mcp_validation.text
+        assert "starts or ends with a dash" in caplog_for_mcp_validation.text
+
+    def test_tool_still_created_despite_warnings(self, caplog_for_mcp_validation):
+        """Tools with invalid names should still be created (SHOULD not MUST)."""
+
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        tool = Tool.from_function(add, name="invalid tool name!")
+        assert tool.name == "invalid tool name!"
+        assert tool.parameters is not None
+        assert "a" in tool.parameters["properties"]
+        assert "b" in tool.parameters["properties"]
+
+
+class TestToolExecutionField:
+    """Tests for the execution field on the base Tool class."""
+
+    def test_tool_with_execution_field(self):
+        """Test that Tool can store and return execution metadata."""
+        tool = Tool(
+            name="my_tool",
+            description="A tool with execution",
+            parameters={"type": "object", "properties": {}},
+            execution=ToolExecution(task_support="optional"),
+        )
+
+        mcp_tool = tool.to_mcp_tool()
+        assert mcp_tool.execution is not None
+        assert mcp_tool.execution.task_support == "optional"
+
+    def test_tool_without_execution_field(self):
+        """Test that Tool without execution returns None."""
+        tool = Tool(
+            name="my_tool",
+            description="A tool without execution",
+            parameters={"type": "object", "properties": {}},
+        )
+
+        mcp_tool = tool.to_mcp_tool()
+        assert mcp_tool.execution is None
+
+    def test_execution_override_takes_precedence(self):
+        """Test that explicit override takes precedence over field value."""
+        tool = Tool(
+            name="my_tool",
+            description="A tool",
+            parameters={"type": "object", "properties": {}},
+            execution=ToolExecution(task_support="optional"),
+        )
+
+        override_execution = ToolExecution(task_support="required")
+        mcp_tool = tool.to_mcp_tool(execution=override_execution)
+        assert mcp_tool.execution is not None
+        assert mcp_tool.execution.task_support == "required"
+
+    async def test_function_tool_task_config_still_works(self):
+        """FunctionTool should still derive execution from task_config."""
+
+        async def my_fn() -> str:
+            return "hello"
+
+        tool = Tool.from_function(my_fn, task=True)
+        mcp_tool = tool.to_mcp_tool()
+
+        # FunctionTool sets execution from task_config
+        assert mcp_tool.execution is not None
+        assert mcp_tool.execution.task_support == "optional"
+
+    def test_tool_execution_required_mode(self):
+        """Test that Tool can store required execution mode."""
+        tool = Tool(
+            name="my_tool",
+            description="A tool with required execution",
+            parameters={"type": "object", "properties": {}},
+            execution=ToolExecution(task_support="required"),
+        )
+
+        mcp_tool = tool.to_mcp_tool()
+        assert mcp_tool.execution is not None
+        assert mcp_tool.execution.task_support == "required"
+
+    def test_tool_execution_forbidden_mode(self):
+        """Test that Tool can store forbidden execution mode."""
+        tool = Tool(
+            name="my_tool",
+            description="A tool with forbidden execution",
+            parameters={"type": "object", "properties": {}},
+            execution=ToolExecution(task_support="forbidden"),
+        )
+
+        mcp_tool = tool.to_mcp_tool()
+        assert mcp_tool.execution is not None
+        assert mcp_tool.execution.task_support == "forbidden"
diff --git a/tests/tools/tool_transform/__init__.py b/tests/tools/tool_transform/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/tools/tool_transform/test_args.py b/tests/tools/tool_transform/test_args.py
new file mode 100644
index 0000000..7401527
--- /dev/null
+++ b/tests/tools/tool_transform/test_args.py
@@ -0,0 +1,456 @@
+"""Tests for argument transformation in tool transforms."""
+
+from dataclasses import dataclass
+from typing import Annotated, Any
+
+import pytest
+from mcp_types import TextContent
+from pydantic import BaseModel, Field
+from typing_extensions import TypedDict
+
+from fastmcp import FastMCP
+from fastmcp.client.client import Client
+from fastmcp.exceptions import ToolError
+from fastmcp.tools import Tool, forward, forward_raw
+from fastmcp.tools.function_tool import FunctionTool
+from fastmcp.tools.tool_transform import (
+    ArgTransform,
+)
+
+
+def get_property(tool: Tool, name: str) -> dict[str, Any]:
+    return tool.parameters["properties"][name]
+
+
+@pytest.fixture
+def add_tool() -> FunctionTool:
+    def add(
+        old_x: Annotated[int, Field(description="old_x description")], old_y: int = 10
+    ) -> int:
+        print("running!")
+        return old_x + old_y
+
+    return Tool.from_function(add)
+
+
+async def test_tool_transform_chaining(add_tool):
+    """Test that transformed tools can be transformed again."""
+    # First transformation: a -> x
+    tool1 = Tool.from_tool(add_tool, transform_args={"old_x": ArgTransform(name="x")})
+
+    # Second transformation: x -> final_x, using tool1
+    tool2 = Tool.from_tool(tool1, transform_args={"x": ArgTransform(name="final_x")})
+
+    result = await tool2.run(arguments={"final_x": 5})
+    assert isinstance(result.content[0], TextContent)
+    assert result.content[0].text == "15"
+
+    # Transform tool1 with custom function that handles all parameters
+    async def custom(final_x: int, **kwargs) -> str:
+        result = await forward(final_x=final_x, **kwargs)
+        assert isinstance(result.content[0], TextContent)
+        return f"custom {result.content[0].text}"  # Extract text from content
+
+    tool3 = Tool.from_tool(
+        tool1, transform_fn=custom, transform_args={"x": ArgTransform(name="final_x")}
+    )
+    result = await tool3.run(arguments={"final_x": 3, "old_y": 5})
+    assert isinstance(result.content[0], TextContent)
+    assert result.content[0].text == "custom 8"
+
+
+class MyModel(BaseModel):
+    x: int
+    y: str
+
+
+@dataclass
+class MyDataclass:
+    x: int
+    y: str
+
+
+class MyTypedDict(TypedDict):
+    x: int
+    y: str
+
+
+@pytest.mark.parametrize(
+    "py_type, json_type",
+    [
+        (int, "integer"),
+        (str, "string"),
+        (float, "number"),
+        (bool, "boolean"),
+        (MyModel, "object"),
+        (MyDataclass, "object"),
+        (MyTypedDict, "object"),
+    ],
+)
+def test_arg_transform_type_handling(add_tool, py_type, json_type):
+    new_tool = Tool.from_tool(
+        add_tool, transform_args={"old_x": ArgTransform(type=py_type)}
+    )
+    prop = get_property(new_tool, "old_x")
+    assert prop["type"] == json_type
+
+
+def test_arg_transform_annotated_types(add_tool):
+    new_tool = Tool.from_tool(
+        add_tool,
+        transform_args={
+            "old_x": ArgTransform(
+                type=Annotated[int, Field(ge=0, le=100)], description="A number 0-100"
+            )
+        },
+    )
+    prop = get_property(new_tool, "old_x")
+    assert prop["type"] == "integer"
+    assert prop["description"] == "A number 0-100"
+    assert prop["minimum"] == 0
+    assert prop["maximum"] == 100
+
+
+def test_arg_transform_precedence_over_function_without_kwargs():
+    def base(x: int) -> int:
+        return x
+
+    tool = Tool.from_function(base)
+    new_tool = Tool.from_tool(
+        tool, transform_args={"x": ArgTransform(type=str, description="String input")}
+    )
+
+    prop = get_property(new_tool, "x")
+    assert prop["type"] == "string"
+    assert prop["description"] == "String input"
+
+
+async def test_arg_transform_precedence_over_function_with_kwargs():
+    """Test that ArgTransform attributes take precedence over function signature (with **kwargs)."""
+
+    @Tool.from_function
+    def base(x: int, y: str = "base_default") -> str:
+        return f"{x}: {y}"
+
+    # Function signature has different types/defaults than ArgTransform
+    async def custom_fn(x: str = "function_default", **kwargs) -> str:
+        result = await forward(x=x, **kwargs)
+        assert isinstance(result.content[0], TextContent)
+        return f"custom: {result.content[0].text}"
+
+    tool = Tool.from_tool(
+        base,
+        transform_fn=custom_fn,
+        transform_args={
+            "x": ArgTransform(type=int, default=42),  # Different type and default
+            "y": ArgTransform(description="ArgTransform description"),
+        },
+    )
+
+    # ArgTransform should take precedence
+    x_prop = get_property(tool, "x")
+    y_prop = get_property(tool, "y")
+
+    assert x_prop["type"] == "integer"  # ArgTransform type wins over function's str
+    assert x_prop["default"] == 42  # ArgTransform default wins over function's default
+    assert (
+        y_prop["description"] == "ArgTransform description"
+    )  # ArgTransform description
+
+    # x should not be required due to ArgTransform default
+    assert "x" not in tool.parameters["required"]
+
+    # Test it works at runtime
+    result = await tool.run(arguments={"y": "test"})
+    # Should use ArgTransform default of 42
+    assert isinstance(result.content[0], TextContent)
+    assert "42: test" in result.content[0].text
+
+
+def test_arg_transform_combined_attributes(add_tool):
+    new_tool = Tool.from_tool(
+        add_tool,
+        transform_args={
+            "old_x": ArgTransform(
+                name="new_x",
+                description="New description",
+                type=str,
+            )
+        },
+    )
+
+    prop = get_property(new_tool, "new_x")
+    assert prop["type"] == "string"
+    assert prop["description"] == "New description"
+    assert "old_x" not in new_tool.parameters["properties"]
+
+
+async def test_arg_transform_type_precedence_runtime():
+    """Test that ArgTransform type changes work correctly at runtime."""
+
+    @Tool.from_function
+    def base(x: int, y: int = 10) -> int:
+        return x + y
+
+    # Transform x to string type but keep same logic
+    async def custom_fn(x: str, y: int = 10) -> str:
+        # Convert string back to int for the original function
+        result = await forward_raw(x=int(x), y=y)
+        # Extract the text from the result
+        assert isinstance(result.content[0], TextContent)
+        result_text = result.content[0].text
+        return f"String input '{x}' converted to result: {result_text}"
+
+    tool = Tool.from_tool(
+        base, transform_fn=custom_fn, transform_args={"x": ArgTransform(type=str)}
+    )
+
+    # Verify schema shows string type
+    assert get_property(tool, "x")["type"] == "string"
+
+    # Test it works with string input
+    result = await tool.run(arguments={"x": "5", "y": 3})
+    assert isinstance(result.content[0], TextContent)
+    assert "String input '5'" in result.content[0].text
+    assert "result: 8" in result.content[0].text
+
+
+async def test_arg_transform_default_factory():
+    """Test ArgTransform with default_factory for hidden parameters."""
+    import asyncio
+    import time
+
+    @Tool.from_function
+    def base_tool(x: int, timestamp: float) -> str:
+        return f"{x}_{timestamp}"
+
+    new_tool = Tool.from_tool(
+        base_tool,
+        transform_args={
+            "timestamp": ArgTransform(hide=True, default_factory=time.time)
+        },
+    )
+
+    result1 = await new_tool.run(arguments={"x": 1})
+    await asyncio.sleep(0.01)
+    result2 = await new_tool.run(arguments={"x": 2})
+
+    # Each call should get a different timestamp
+    assert isinstance(result1.content[0], TextContent)
+    assert isinstance(result2.content[0], TextContent)
+    assert result1.content[0].text != result2.content[0].text
+    assert "1_" in result1.content[0].text
+    assert "2_" in result2.content[0].text
+
+
+async def test_arg_transform_default_factory_called_each_time():
+    """Test that default_factory is called for each tool execution."""
+
+    call_count = {"count": 0}
+
+    def get_counter():
+        call_count["count"] += 1
+        return call_count["count"]
+
+    @Tool.from_function
+    def base_tool(x: int, counter: int) -> str:
+        return f"{x}_{counter}"
+
+    new_tool = Tool.from_tool(
+        base_tool,
+        transform_args={
+            "counter": ArgTransform(hide=True, default_factory=get_counter)
+        },
+    )
+
+    result1 = await new_tool.run(arguments={"x": 1})
+    result2 = await new_tool.run(arguments={"x": 2})
+    result3 = await new_tool.run(arguments={"x": 3})
+
+    # Each call should increment the counter
+    assert isinstance(result1.content[0], TextContent)
+    assert isinstance(result2.content[0], TextContent)
+    assert isinstance(result3.content[0], TextContent)
+    assert "1_1" in result1.content[0].text
+    assert "2_2" in result2.content[0].text
+    assert "3_3" in result3.content[0].text
+
+
+async def test_arg_transform_hidden_with_default_factory():
+    """Test that hidden parameters with default_factory work correctly."""
+
+    @Tool.from_function
+    def base_tool(x: int, session_id: str) -> str:
+        return f"{x}_{session_id}"
+
+    import uuid
+
+    new_tool = Tool.from_tool(
+        base_tool,
+        transform_args={
+            "session_id": ArgTransform(
+                hide=True, default_factory=lambda: str(uuid.uuid4())
+            )
+        },
+    )
+
+    result = await new_tool.run(arguments={"x": 1})
+    # Should have a UUID in the result
+    assert isinstance(result.content[0], TextContent)
+    assert "1_" in result.content[0].text
+    assert len(result.content[0].text.split("_")[1]) > 10
+
+
+async def test_arg_transform_default_and_factory_raises_error():
+    """Test that providing both default and default_factory raises an error."""
+    with pytest.raises(
+        ValueError, match="Cannot specify both 'default' and 'default_factory'"
+    ):
+        ArgTransform(default=10, default_factory=lambda: 20)
+
+
+async def test_arg_transform_default_factory_requires_hide():
+    """Test that default_factory requires hide=True."""
+    with pytest.raises(
+        ValueError, match="default_factory can only be used with hide=True"
+    ):
+        ArgTransform(default_factory=lambda: 10)
+
+
+async def test_arg_transform_required_true(add_tool):
+    """Test ArgTransform with required=True."""
+    new_tool = Tool.from_tool(
+        add_tool,
+        transform_args={"old_y": ArgTransform(required=True)},
+    )
+
+    # old_y should now be required (even though it had a default)
+    assert "old_y" in new_tool.parameters["required"]
+
+
+async def test_arg_transform_required_false():
+    """Test ArgTransform with required=False by setting a default."""
+
+    def func(x: int, y: int) -> int:
+        return x + y
+
+    tool = Tool.from_function(func)
+    # Setting a default makes it not required
+    new_tool = Tool.from_tool(tool, transform_args={"y": ArgTransform(default=0)})
+
+    # y should not be required since it has a default
+    assert "y" not in new_tool.parameters.get("required", [])
+
+
+async def test_arg_transform_required_with_rename(add_tool):
+    """Test ArgTransform with required and rename."""
+    new_tool = Tool.from_tool(
+        add_tool,
+        transform_args={"old_y": ArgTransform(name="new_y", required=True)},
+    )
+
+    # new_y should be required
+    assert "new_y" in new_tool.parameters["required"]
+    assert "old_y" not in new_tool.parameters["properties"]
+
+
+async def test_arg_transform_required_true_with_default_raises_error():
+    """Test that required=True with default raises an error."""
+    with pytest.raises(
+        ValueError, match="Cannot specify 'required=True' with 'default'"
+    ):
+        ArgTransform(required=True, default=42)
+
+
+async def test_arg_transform_required_true_with_factory_raises_error():
+    """Test that required=True with default_factory raises an error."""
+    with pytest.raises(
+        ValueError, match="default_factory can only be used with hide=True"
+    ):
+        ArgTransform(required=True, default_factory=lambda: 42)
+
+
+async def test_arg_transform_required_no_change():
+    """Test that not specifying required doesn't change existing required status."""
+
+    def func(x: int, y: int) -> int:
+        return x + y
+
+    tool = Tool.from_function(func)
+    # Both x and y are required in original
+    assert "x" in tool.parameters["required"]
+    assert "y" in tool.parameters["required"]
+
+    # Not specifying required should keep x required
+    new_tool = Tool.from_tool(
+        tool, transform_args={"x": ArgTransform(description="Updated x")}
+    )
+
+    # x should still be required, and y should still be
+    assert "x" in new_tool.parameters.get("required", [])
+    assert "y" in new_tool.parameters["required"]
+
+
+async def test_arg_transform_hide_and_required_raises_error():
+    """Test that hide=True and required=True together raises an error."""
+    with pytest.raises(
+        ValueError, match="Cannot specify both 'hide=True' and 'required=True'"
+    ):
+        ArgTransform(hide=True, required=True)
+
+
+class TestEnableDisable:
+    async def test_transform_disabled_tool(self):
+        """
+        Tests that a transformed tool can run even if the parent tool is disabled via server.
+        """
+        mcp = FastMCP()
+
+        @mcp.tool
+        def add(x: int, y: int = 10) -> int:
+            return x + y
+
+        # Get the registered Tool object from the server
+        add_tool = await mcp._local_provider.get_tool("add")
+        assert isinstance(add_tool, Tool)
+        new_add = Tool.from_tool(add_tool, name="new_add")
+        mcp.add_tool(new_add)
+
+        # Disable original tool, but new_add should still work
+        mcp.disable(names={"add"}, components={"tool"})
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            assert {tool.name for tool in tools} == {"new_add"}
+
+            result = await client.call_tool("new_add", {"x": 1, "y": 2})
+            assert isinstance(result.content[0], TextContent)
+            assert result.content[0].text == "3"
+
+            with pytest.raises(ToolError):
+                await client.call_tool("add", {"x": 1, "y": 2})
+
+    async def test_disable_transformed_tool(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def add(x: int, y: int = 10) -> int:
+            return x + y
+
+        # Get the registered Tool object from the server
+        add_tool = await mcp._local_provider.get_tool("add")
+        assert isinstance(add_tool, Tool)
+        new_add = Tool.from_tool(add_tool, name="new_add")
+        mcp.add_tool(new_add)
+
+        # Disable both tools via server
+        mcp.disable(names={"add"}, components={"tool"}).disable(
+            names={"new_add"}, components={"tool"}
+        )
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            assert len(tools) == 0
+
+            with pytest.raises(ToolError):
+                await client.call_tool("new_add", {"x": 1, "y": 2})
diff --git a/tests/tools/tool_transform/test_metadata.py b/tests/tools/tool_transform/test_metadata.py
new file mode 100644
index 0000000..36384af
--- /dev/null
+++ b/tests/tools/tool_transform/test_metadata.py
@@ -0,0 +1,244 @@
+from typing import Annotated, Any
+
+import pytest
+from pydantic import Field
+
+from fastmcp.tools import Tool
+from fastmcp.tools.function_tool import FunctionTool
+from fastmcp.tools.tool_transform import (
+    ToolTransformConfig,
+)
+
+
+def get_property(tool: Tool, name: str) -> dict[str, Any]:
+    return tool.parameters["properties"][name]
+
+
+@pytest.fixture
+def add_tool() -> FunctionTool:
+    def add(
+        old_x: Annotated[int, Field(description="old_x description")], old_y: int = 10
+    ) -> int:
+        print("running!")
+        return old_x + old_y
+
+    return Tool.from_function(add)
+
+
+@pytest.fixture
+def sample_tool():
+    """Sample tool for testing transformations."""
+
+    def sample_func(x: int) -> str:
+        return f"Result: {x}"
+
+    return Tool.from_function(
+        sample_func,
+        name="sample_tool",
+        title="Original Tool Title",
+        description="Original description",
+    )
+
+
+@pytest.fixture
+def sample_tool_no_title():
+    """Sample tool without title for testing."""
+
+    def sample_func(x: int) -> str:
+        return f"Result: {x}"
+
+    return Tool.from_function(sample_func, name="no_title_tool")
+
+
+def test_transform_inherits_title(sample_tool):
+    """Test that transformed tools inherit title when none specified."""
+    transformed = Tool.from_tool(sample_tool)
+    assert transformed.title == "Original Tool Title"
+
+
+def test_transform_overrides_title(sample_tool):
+    """Test that transformed tools can override title."""
+    transformed = Tool.from_tool(sample_tool, title="New Tool Title")
+    assert transformed.title == "New Tool Title"
+
+
+def test_transform_sets_title_to_none(sample_tool):
+    """Test that transformed tools can explicitly set title to None."""
+    transformed = Tool.from_tool(sample_tool, title=None)
+    assert transformed.title is None
+
+
+def test_transform_inherits_none_title(sample_tool_no_title):
+    """Test that transformed tools inherit None title."""
+    transformed = Tool.from_tool(sample_tool_no_title)
+    assert transformed.title is None
+
+
+def test_transform_adds_title_to_none(sample_tool_no_title):
+    """Test that transformed tools can add title when parent has None."""
+    transformed = Tool.from_tool(sample_tool_no_title, title="Added Title")
+    assert transformed.title == "Added Title"
+
+
+def test_transform_inherits_description(sample_tool):
+    """Test that transformed tools inherit description when none specified."""
+    transformed = Tool.from_tool(sample_tool)
+    assert transformed.description == "Original description"
+
+
+def test_transform_overrides_description(sample_tool):
+    """Test that transformed tools can override description."""
+    transformed = Tool.from_tool(sample_tool, description="New description")
+    assert transformed.description == "New description"
+
+
+def test_transform_sets_description_to_none(sample_tool):
+    """Test that transformed tools can explicitly set description to None."""
+    transformed = Tool.from_tool(sample_tool, description=None)
+    assert transformed.description is None
+
+
+def test_transform_inherits_none_description(sample_tool_no_title):
+    """Test that transformed tools inherit None description."""
+    transformed = Tool.from_tool(sample_tool_no_title)
+    assert transformed.description is None
+
+
+def test_transform_adds_description_to_none(sample_tool_no_title):
+    """Test that transformed tools can add description when parent has None."""
+    transformed = Tool.from_tool(sample_tool_no_title, description="Added description")
+    assert transformed.description == "Added description"
+
+
+# Meta transformation tests
+def test_transform_inherits_meta(sample_tool):
+    """Test that transformed tools inherit meta when none specified."""
+    sample_tool.meta = {"original": True, "version": "1.0"}
+    transformed = Tool.from_tool(sample_tool)
+    assert transformed.meta == {"original": True, "version": "1.0"}
+
+
+def test_transform_overrides_meta(sample_tool):
+    """Test that transformed tools can override meta."""
+    sample_tool.meta = {"original": True, "version": "1.0"}
+    transformed = Tool.from_tool(sample_tool, meta={"custom": True, "priority": "high"})
+    assert transformed.meta == {"custom": True, "priority": "high"}
+
+
+def test_transform_sets_meta_to_none(sample_tool):
+    """Test that transformed tools can explicitly set meta to None."""
+    sample_tool.meta = {"original": True, "version": "1.0"}
+    transformed = Tool.from_tool(sample_tool, meta=None)
+    assert transformed.meta is None
+
+
+def test_transform_inherits_none_meta(sample_tool_no_title):
+    """Test that transformed tools inherit None meta."""
+    sample_tool_no_title.meta = None
+    transformed = Tool.from_tool(sample_tool_no_title)
+    assert transformed.meta is None
+
+
+def test_transform_adds_meta_to_none(sample_tool_no_title):
+    """Test that transformed tools can add meta when parent has None."""
+    sample_tool_no_title.meta = None
+    transformed = Tool.from_tool(sample_tool_no_title, meta={"added": True})
+    assert transformed.meta == {"added": True}
+
+
+def test_tool_transform_config_inherits_meta(sample_tool):
+    """Test that ToolTransformConfig inherits meta when unset."""
+    sample_tool.meta = {"original": True, "version": "1.0"}
+    config = ToolTransformConfig(name="config_tool")
+    transformed = config.apply(sample_tool)
+    assert transformed.meta == {"original": True, "version": "1.0"}
+
+
+def test_tool_transform_config_overrides_meta(sample_tool):
+    """Test that ToolTransformConfig can override meta."""
+    sample_tool.meta = {"original": True, "version": "1.0"}
+    config = ToolTransformConfig(
+        name="config_tool", meta={"config": True, "priority": "high"}
+    )
+    transformed = config.apply(sample_tool)
+    assert transformed.meta == {"config": True, "priority": "high"}
+
+
+def test_tool_transform_config_removes_meta(sample_tool):
+    """Test that ToolTransformConfig can remove meta with None."""
+    sample_tool.meta = {"original": True, "version": "1.0"}
+    config = ToolTransformConfig(name="config_tool", meta=None)
+    transformed = config.apply(sample_tool)
+    assert transformed.meta is None
+
+
+# Enabled field tests
+def test_tool_transform_config_enabled_defaults_to_true(sample_tool):
+    """Test that enabled defaults to True and no visibility metadata is set."""
+    config = ToolTransformConfig(name="enabled_tool")
+    transformed = config.apply(sample_tool)
+
+    # No visibility metadata should be set when enabled=True (default)
+    meta = transformed.meta or {}
+    internal = meta.get("fastmcp", {}).get("_internal", {})
+    assert "visibility" not in internal
+
+
+def test_tool_transform_config_enabled_false_sets_visibility_metadata(sample_tool):
+    """Test that enabled=False sets visibility metadata to hide the tool."""
+    from fastmcp.server.transforms.visibility import is_enabled
+
+    config = ToolTransformConfig(name="disabled_tool", enabled=False)
+    transformed = config.apply(sample_tool)
+
+    # The is_enabled helper should return False
+    assert is_enabled(transformed) is False
+
+    # Check the raw metadata structure
+    assert transformed.meta is not None
+    assert transformed.meta["fastmcp"]["_internal"]["visibility"] is False
+
+
+def test_tool_transform_config_enabled_true_explicit_sets_visibility(sample_tool):
+    """Test that enabled=True explicitly sets visibility metadata to allow overriding earlier disables."""
+    from fastmcp.server.transforms.visibility import is_enabled
+
+    config = ToolTransformConfig(name="explicit_enabled", enabled=True)
+    transformed = config.apply(sample_tool)
+
+    # Visibility metadata should be set to True when enabled=True is explicit
+    # This allows later transforms to override earlier disables
+    assert is_enabled(transformed) is True
+    assert transformed.meta is not None
+    assert transformed.meta["fastmcp"]["_internal"]["visibility"] is True
+
+
+def test_tool_transform_config_enabled_false_preserves_existing_meta(sample_tool):
+    """Test that enabled=False preserves existing meta while adding visibility."""
+    from fastmcp.server.transforms.visibility import is_enabled
+
+    sample_tool.meta = {"custom_key": "custom_value"}
+    config = ToolTransformConfig(enabled=False)
+    transformed = config.apply(sample_tool)
+
+    # Original meta should be preserved
+    assert transformed.meta is not None
+    assert transformed.meta["custom_key"] == "custom_value"
+    # Visibility should be set
+    assert is_enabled(transformed) is False
+
+
+def test_tool_transform_config_enabled_false_merges_with_config_meta(sample_tool):
+    """Test that enabled=False works with explicit meta override."""
+    from fastmcp.server.transforms.visibility import is_enabled
+
+    sample_tool.meta = {"original": True}
+    config = ToolTransformConfig(meta={"overridden": True}, enabled=False)
+    transformed = config.apply(sample_tool)
+
+    # Config meta should override original
+    assert transformed.meta is not None
+    assert "original" not in transformed.meta
+    assert transformed.meta["overridden"] is True
+    # But visibility should still be set
+    assert is_enabled(transformed) is False
diff --git a/tests/tools/tool_transform/test_schemas.py b/tests/tools/tool_transform/test_schemas.py
new file mode 100644
index 0000000..703dd79
--- /dev/null
+++ b/tests/tools/tool_transform/test_schemas.py
@@ -0,0 +1,555 @@
+from typing import Annotated, Any
+
+import pytest
+from dirty_equals import IsList
+from inline_snapshot import snapshot
+from mcp_types import TextContent
+from pydantic import BaseModel, Field, TypeAdapter
+
+from fastmcp.tools import Tool, forward
+from fastmcp.tools.base import ToolResult
+from fastmcp.tools.function_tool import FunctionTool
+from fastmcp.tools.tool_transform import (
+    ArgTransform,
+    TransformedTool,
+)
+
+
+def get_property(tool: Tool, name: str) -> dict[str, Any]:
+    return tool.parameters["properties"][name]
+
+
+@pytest.fixture
+def add_tool() -> FunctionTool:
+    def add(
+        old_x: Annotated[int, Field(description="old_x description")], old_y: int = 10
+    ) -> int:
+        print("running!")
+        return old_x + old_y
+
+    return Tool.from_function(add)
+
+
+class TestTransformToolOutputSchema:
+    """Test output schema handling in transformed tools."""
+
+    @pytest.fixture
+    def base_string_tool(self) -> FunctionTool:
+        """Tool that returns a string (gets wrapped)."""
+
+        def string_tool(x: int) -> str:
+            return f"Result: {x}"
+
+        return Tool.from_function(string_tool)
+
+    @pytest.fixture
+    def base_dict_tool(self) -> FunctionTool:
+        """Tool that returns a dict (object type, not wrapped)."""
+
+        def dict_tool(x: int) -> dict[str, int]:
+            return {"value": x}
+
+        return Tool.from_function(dict_tool)
+
+    def test_transform_inherits_parent_output_schema(self, base_string_tool):
+        """Test that transformed tool inherits parent's output schema by default."""
+        new_tool = Tool.from_tool(base_string_tool)
+
+        # Should inherit parent's wrapped string schema
+        expected_schema = {
+            "type": "object",
+            "properties": {"result": {"type": "string"}},
+            "required": ["result"],
+            "x-fastmcp-wrap-result": True,
+        }
+        assert new_tool.output_schema == expected_schema
+        assert new_tool.output_schema == base_string_tool.output_schema
+
+    def test_transform_with_explicit_output_schema_none(self, base_string_tool):
+        """Test that output_schema=None sets output schema to None."""
+        new_tool = Tool.from_tool(base_string_tool, output_schema=None)
+
+        assert new_tool.output_schema is None
+
+    async def test_transform_output_schema_none_runtime(self, base_string_tool):
+        """Test runtime behavior with output_schema=None."""
+        new_tool = Tool.from_tool(base_string_tool, output_schema=None)
+
+        # Debug: check that output_schema is actually None
+        assert new_tool.output_schema is None, (
+            f"Expected None, got {new_tool.output_schema}"
+        )
+
+        result = await new_tool.run({"x": 5})
+        # Even with output_schema=None, structured content should be generated via fallback logic
+        assert result.structured_content == {"result": "Result: 5"}
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "Result: 5"
+
+    def test_transform_with_explicit_output_schema_dict(self, base_string_tool):
+        """Test that explicit output schema overrides parent."""
+        custom_schema = {
+            "type": "object",
+            "properties": {"message": {"type": "string"}},
+        }
+        new_tool = Tool.from_tool(base_string_tool, output_schema=custom_schema)
+
+        assert new_tool.output_schema == custom_schema
+        assert new_tool.output_schema != base_string_tool.output_schema
+
+    async def test_transform_explicit_schema_runtime(self, base_string_tool):
+        """Test runtime behavior with explicit output schema."""
+        custom_schema = {"type": "string", "minLength": 1}
+        new_tool = Tool.from_tool(base_string_tool, output_schema=custom_schema)
+
+        result = await new_tool.run({"x": 10})
+        # Non-object explicit schemas disable structured content
+        assert result.structured_content is None
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "Result: 10"
+
+    def test_transform_with_custom_function_inferred_schema(self, base_dict_tool):
+        """Test that custom function's output schema is inferred."""
+
+        async def custom_fn(x: int) -> str:
+            result = await forward(x=x)
+            assert isinstance(result.content[0], TextContent)
+            return f"Custom: {result.content[0].text}"
+
+        new_tool = Tool.from_tool(base_dict_tool, transform_fn=custom_fn)
+
+        # Should infer string schema from custom function and wrap it
+        expected_schema = {
+            "type": "object",
+            "properties": {"result": {"type": "string"}},
+            "required": ["result"],
+            "x-fastmcp-wrap-result": True,
+        }
+        assert new_tool.output_schema == expected_schema
+
+    async def test_transform_custom_function_runtime(self, base_dict_tool):
+        """Test runtime behavior with custom function that has inferred schema."""
+
+        async def custom_fn(x: int) -> str:
+            result = await forward(x=x)
+            assert isinstance(result.content[0], TextContent)
+            return f"Custom: {result.content[0].text}"
+
+        new_tool = Tool.from_tool(base_dict_tool, transform_fn=custom_fn)
+
+        result = await new_tool.run({"x": 3})
+        # Should wrap string result
+        assert result.structured_content == {"result": 'Custom: {"value":3}'}
+
+    def test_transform_custom_function_fallback_to_parent(self, base_string_tool):
+        """Test that custom function without output annotation falls back to parent."""
+
+        async def custom_fn(x: int):
+            # No return annotation - should fallback to parent schema
+            result = await forward(x=x)
+            return result
+
+        new_tool = Tool.from_tool(base_string_tool, transform_fn=custom_fn)
+
+        # Should use parent's schema since custom function has no annotation
+        assert new_tool.output_schema == base_string_tool.output_schema
+
+    def test_transform_custom_function_explicit_overrides(self, base_string_tool):
+        """Test that explicit output_schema overrides both custom function and parent."""
+
+        async def custom_fn(x: int) -> dict[str, str]:
+            return {"custom": "value"}
+
+        explicit_schema = {"type": "array", "items": {"type": "number"}}
+        new_tool = Tool.from_tool(
+            base_string_tool, transform_fn=custom_fn, output_schema=explicit_schema
+        )
+
+        # Explicit schema should win
+        assert new_tool.output_schema == explicit_schema
+
+    async def test_transform_custom_function_object_return(self, base_string_tool):
+        """Test custom function returning object type."""
+
+        async def custom_fn(x: int) -> dict[str, int]:
+            await forward(x=x)
+            return {"original": x, "transformed": x * 2}
+
+        new_tool = Tool.from_tool(base_string_tool, transform_fn=custom_fn)
+
+        # Object types should not be wrapped
+        expected_schema = TypeAdapter(dict[str, int]).json_schema()
+        assert new_tool.output_schema == expected_schema
+        assert isinstance(new_tool.output_schema, dict)
+        assert "x-fastmcp-wrap-result" not in new_tool.output_schema
+
+        result = await new_tool.run({"x": 4})
+        # Direct value, not wrapped
+        assert result.structured_content == {"original": 4, "transformed": 8}
+
+    async def test_transform_preserves_wrap_marker_behavior(self, base_string_tool):
+        """Test that wrap marker behavior is preserved through transformation."""
+        new_tool = Tool.from_tool(base_string_tool)
+
+        result = await new_tool.run({"x": 7})
+        # Should wrap because parent schema has wrap marker
+        assert result.structured_content == {"result": "Result: 7"}
+        assert isinstance(new_tool.output_schema, dict)
+        assert "x-fastmcp-wrap-result" in new_tool.output_schema
+
+    def test_transform_chained_output_schema_inheritance(self, base_string_tool):
+        """Test output schema inheritance through multiple transformations."""
+        # First transformation keeps parent schema
+        tool1 = Tool.from_tool(base_string_tool)
+        assert tool1.output_schema == base_string_tool.output_schema
+
+        # Second transformation also inherits
+        tool2 = Tool.from_tool(tool1)
+        assert (
+            tool2.output_schema == tool1.output_schema == base_string_tool.output_schema
+        )
+
+        # Third transformation with explicit override
+        custom_schema = {"type": "number"}
+        tool3 = Tool.from_tool(tool2, output_schema=custom_schema)
+        assert tool3.output_schema == custom_schema
+        assert tool3.output_schema != tool2.output_schema
+
+    async def test_transform_mixed_structured_unstructured_content(
+        self, base_string_tool
+    ):
+        """Test transformation handling of mixed content types."""
+
+        async def custom_fn(x: int):
+            # Return mixed content including ToolResult
+            if x == 1:
+                return ["text", {"data": x}]
+            else:
+                # Return ToolResult directly
+                return ToolResult(
+                    content=[TextContent(type="text", text=f"Custom: {x}")],
+                    structured_content={"custom_value": x},
+                )
+
+        new_tool = Tool.from_tool(base_string_tool, transform_fn=custom_fn)
+
+        # Test mixed content return
+        result1 = await new_tool.run({"x": 1})
+        assert result1.structured_content == {"result": ["text", {"data": 1}]}
+
+        # Test ToolResult return
+        result2 = await new_tool.run({"x": 2})
+        assert result2.structured_content == {"custom_value": 2}
+        assert isinstance(result2.content[0], TextContent)
+        assert result2.content[0].text == "Custom: 2"
+
+    def test_transform_output_schema_with_arg_transforms(self, base_string_tool):
+        """Test that output schema works correctly with argument transformations."""
+
+        async def custom_fn(new_x: int) -> dict[str, str]:
+            result = await forward(new_x=new_x)
+            assert isinstance(result.content[0], TextContent)
+            return {"transformed": result.content[0].text}
+
+        new_tool = Tool.from_tool(
+            base_string_tool,
+            transform_fn=custom_fn,
+            transform_args={"x": ArgTransform(name="new_x")},
+        )
+
+        # Should infer object schema from custom function
+        expected_schema = TypeAdapter(dict[str, str]).json_schema()
+        assert new_tool.output_schema == expected_schema
+
+    async def test_transform_output_schema_default_vs_none(self, base_string_tool):
+        """Test default (NotSet) vs explicit None behavior for output_schema in transforms."""
+        # Default (NotSet) should use smart fallback (inherit from parent)
+        tool_default = Tool.from_tool(base_string_tool)  # default output_schema=NotSet
+        assert tool_default.output_schema == base_string_tool.output_schema  # Inherits
+
+        # None should explicitly set output_schema to None but still generate structured content via fallback
+        tool_explicit_none = Tool.from_tool(base_string_tool, output_schema=None)
+        assert tool_explicit_none.output_schema is None
+
+        # Both should generate structured content now (via different paths)
+        result_default = await tool_default.run({"x": 5})
+        result_explicit_none = await tool_explicit_none.run({"x": 5})
+
+        assert result_default.structured_content == {
+            "result": "Result: 5"
+        }  # Inherits wrapping
+        assert result_explicit_none.structured_content == {
+            "result": "Result: 5"
+        }  # Generated via fallback logic
+        assert isinstance(result_default.content[0], TextContent)
+        assert isinstance(result_explicit_none.content[0], TextContent)
+        assert result_default.content[0].text == result_explicit_none.content[0].text
+
+    async def test_transform_output_schema_with_tool_result_return(
+        self, base_string_tool
+    ):
+        """Test transform when custom function returns ToolResult directly."""
+
+        async def custom_fn(x: int) -> ToolResult:
+            # Custom function returns ToolResult - should bypass schema handling
+            return ToolResult(
+                content=[TextContent(type="text", text=f"Direct: {x}")],
+                structured_content={"direct_value": x, "doubled": x * 2},
+            )
+
+        new_tool = Tool.from_tool(base_string_tool, transform_fn=custom_fn)
+
+        # ToolResult return type should result in None output schema
+        assert new_tool.output_schema is None
+
+        result = await new_tool.run({"x": 6})
+        # Should use ToolResult content directly
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "Direct: 6"
+        assert result.structured_content == {"direct_value": 6, "doubled": 12}
+
+
+class TestInputSchema:
+    """Test schema definition handling and reference finding."""
+
+    def test_arg_transform_examples_in_schema(self, add_tool: Tool):
+        # Simple example
+        new_tool = Tool.from_tool(
+            add_tool,
+            transform_args={
+                "old_x": ArgTransform(examples=[1, 2, 3]),
+            },
+        )
+        prop = get_property(new_tool, "old_x")
+        assert prop["examples"] == [1, 2, 3]
+
+        # Nested example (e.g., for array type)
+        new_tool2 = Tool.from_tool(
+            add_tool,
+            transform_args={
+                "old_x": ArgTransform(examples=[["a", "b"], ["c", "d"]]),
+            },
+        )
+        prop2 = get_property(new_tool2, "old_x")
+        assert prop2["examples"] == [["a", "b"], ["c", "d"]]
+
+        # If not set, should not be present
+        new_tool3 = Tool.from_tool(
+            add_tool,
+            transform_args={
+                "old_x": ArgTransform(),
+            },
+        )
+        prop3 = get_property(new_tool3, "old_x")
+        assert "examples" not in prop3
+
+    def test_merge_schema_with_defs_precedence(self):
+        """Test _merge_schema_with_precedence merges $defs correctly.
+
+        Note: compress_schema no longer dereferences $ref by default.
+        Used definitions are kept in $defs; unused definitions are pruned.
+        """
+        base_schema = {
+            "type": "object",
+            "properties": {"field1": {"$ref": "#/$defs/BaseType"}},
+            "$defs": {
+                "BaseType": {"type": "string", "description": "base"},
+                "SharedType": {"type": "integer", "minimum": 0},
+            },
+        }
+
+        override_schema = {
+            "type": "object",
+            "properties": {"field2": {"$ref": "#/$defs/OverrideType"}},
+            "$defs": {
+                "OverrideType": {"type": "boolean"},
+                "SharedType": {"type": "integer", "minimum": 10},  # Override
+            },
+        }
+
+        transformed_tool_schema = TransformedTool._merge_schema_with_precedence(
+            base_schema, override_schema
+        )
+
+        # SharedType should no longer be present on the schema (unused)
+        assert "SharedType" not in transformed_tool_schema.get("$defs", {})
+
+        # $ref and $defs are preserved for used definitions
+        assert transformed_tool_schema == snapshot(
+            {
+                "type": "object",
+                "properties": {
+                    "field1": {"$ref": "#/$defs/BaseType"},
+                    "field2": {"$ref": "#/$defs/OverrideType"},
+                },
+                "$defs": {
+                    "BaseType": {"type": "string", "description": "base"},
+                    "OverrideType": {"type": "boolean"},
+                },
+                "required": [],
+                "additionalProperties": False,
+            }
+        )
+
+    def test_transform_tool_with_complex_defs_pruning(self):
+        """Test that tool transformation properly handles hidden params.
+
+        Unused type definitions are pruned from $defs when their
+        corresponding parameters are hidden. Used types remain as $ref.
+        """
+
+        class UsedType(BaseModel):
+            value: str
+
+        class UnusedType(BaseModel):
+            other: int
+
+        @Tool.from_function
+        def complex_tool(
+            used_param: UsedType, unused_param: UnusedType | None = None
+        ) -> str:
+            return used_param.value
+
+        # Transform to hide unused_param
+        transformed_tool: TransformedTool = Tool.from_tool(
+            complex_tool, transform_args={"unused_param": ArgTransform(hide=True)}
+        )
+
+        # UnusedType should be pruned from $defs, but UsedType remains
+        assert "UnusedType" not in transformed_tool.parameters.get("$defs", {})
+
+        assert transformed_tool.parameters == snapshot(
+            {
+                "type": "object",
+                "properties": {
+                    "used_param": {"$ref": "#/$defs/UsedType"},
+                },
+                "$defs": {
+                    "UsedType": {
+                        "properties": {"value": {"type": "string"}},
+                        "required": ["value"],
+                        "type": "object",
+                    },
+                },
+                "required": ["used_param"],
+                "additionalProperties": False,
+            }
+        )
+
+    def test_transform_with_custom_function_preserves_needed_types(self):
+        """Test that custom transform functions preserve necessary type definitions."""
+
+        class InputType(BaseModel):
+            data: str
+
+        class OutputType(BaseModel):
+            result: str
+
+        @Tool.from_function
+        def base_tool(input_data: InputType) -> OutputType:
+            return OutputType(result=input_data.data.upper())
+
+        async def transform_function(renamed_input: InputType):
+            return await forward(renamed_input=renamed_input)
+
+        # Transform with custom function and argument rename
+        transformed = Tool.from_tool(
+            base_tool,
+            transform_fn=transform_function,
+            transform_args={"input_data": ArgTransform(name="renamed_input")},
+        )
+
+        # Used type definitions are preserved as $ref/$defs
+        assert transformed.parameters == snapshot(
+            {
+                "type": "object",
+                "properties": {
+                    "renamed_input": {"$ref": "#/$defs/InputType"},
+                },
+                "$defs": {
+                    "InputType": {
+                        "properties": {"data": {"type": "string"}},
+                        "required": ["data"],
+                        "type": "object",
+                    },
+                },
+                "required": ["renamed_input"],
+                "additionalProperties": False,
+            }
+        )
+
+    def test_chained_transforms_inline_types(self):
+        """Test that chained transformations produce correct schemas with $ref/$defs."""
+
+        class TypeA(BaseModel):
+            a: str
+
+        class TypeB(BaseModel):
+            b: int
+
+        class TypeC(BaseModel):
+            c: bool
+
+        @Tool.from_function
+        def base_tool(param_a: TypeA, param_b: TypeB, param_c: TypeC) -> str:
+            return f"{param_a.a}-{param_b.b}-{param_c.c}"
+
+        # First transform: hide param_c
+        transform1 = Tool.from_tool(
+            base_tool,
+            transform_args={"param_c": ArgTransform(hide=True, default=TypeC(c=True))},
+        )
+
+        # TypeC should be pruned from $defs, TypeA and TypeB remain
+        assert "TypeC" not in transform1.parameters.get("$defs", {})
+
+        assert transform1.parameters == snapshot(
+            {
+                "type": "object",
+                "properties": {
+                    "param_a": {"$ref": "#/$defs/TypeA"},
+                    "param_b": {"$ref": "#/$defs/TypeB"},
+                },
+                "$defs": {
+                    "TypeA": {
+                        "properties": {"a": {"type": "string"}},
+                        "required": ["a"],
+                        "type": "object",
+                    },
+                    "TypeB": {
+                        "properties": {"b": {"type": "integer"}},
+                        "required": ["b"],
+                        "type": "object",
+                    },
+                },
+                "required": IsList("param_b", "param_a", check_order=False),
+                "additionalProperties": False,
+            }
+        )
+
+        # Second transform: hide param_b
+        transform2 = Tool.from_tool(
+            transform1,
+            transform_args={"param_b": ArgTransform(hide=True, default=TypeB(b=42))},
+        )
+
+        # TypeB should be pruned from $defs, only TypeA remains
+        assert "TypeB" not in transform2.parameters.get("$defs", {})
+
+        assert transform2.parameters == snapshot(
+            {
+                "type": "object",
+                "properties": {
+                    "param_a": {"$ref": "#/$defs/TypeA"},
+                },
+                "$defs": {
+                    "TypeA": {
+                        "properties": {"a": {"type": "string"}},
+                        "required": ["a"],
+                        "type": "object",
+                    },
+                },
+                "required": ["param_a"],
+                "additionalProperties": False,
+            }
+        )
diff --git a/tests/tools/tool_transform/test_tool_transform.py b/tests/tools/tool_transform/test_tool_transform.py
new file mode 100644
index 0000000..f9e50df
--- /dev/null
+++ b/tests/tools/tool_transform/test_tool_transform.py
@@ -0,0 +1,781 @@
+"""Core tool transform functionality."""
+
+import re
+from typing import Annotated, Any
+
+import pytest
+from mcp_types import TextContent
+from pydantic import BaseModel, Field
+
+from fastmcp import FastMCP
+from fastmcp.client.client import Client
+from fastmcp.tools import Tool, forward, forward_raw, tool
+from fastmcp.tools.base import ToolResult
+from fastmcp.tools.function_tool import FunctionTool
+from fastmcp.tools.tool_transform import (
+    ArgTransform,
+    TransformedTool,
+)
+
+
+def get_property(tool: Tool, name: str) -> dict[str, Any]:
+    return tool.parameters["properties"][name]
+
+
+@pytest.fixture
+def add_tool() -> FunctionTool:
+    def add(
+        old_x: Annotated[int, Field(description="old_x description")], old_y: int = 10
+    ) -> int:
+        print("running!")
+        return old_x + old_y
+
+    return Tool.from_function(add)
+
+
+def test_tool_from_tool_no_change(add_tool):
+    new_tool = Tool.from_tool(add_tool)
+    assert isinstance(new_tool, TransformedTool)
+    assert new_tool.parameters == add_tool.parameters
+    assert new_tool.name == add_tool.name
+    assert new_tool.description == add_tool.description
+
+
+def test_from_tool_accepts_decorated_function():
+    @tool
+    def search(q: str, limit: int = 10) -> list[str]:
+        """Search for items."""
+        return [f"Result {i} for {q}" for i in range(limit)]
+
+    transformed = Tool.from_tool(
+        search,
+        name="find_items",
+        transform_args={"q": ArgTransform(name="query")},
+    )
+    assert isinstance(transformed, TransformedTool)
+    assert transformed.name == "find_items"
+    assert "query" in transformed.parameters["properties"]
+    assert "q" not in transformed.parameters["properties"]
+
+
+def test_from_tool_accepts_plain_function():
+    def search(q: str, limit: int = 10) -> list[str]:
+        return [f"Result {i} for {q}" for i in range(limit)]
+
+    transformed = Tool.from_tool(
+        search,
+        name="find_items",
+        transform_args={"q": ArgTransform(name="query")},
+    )
+    assert isinstance(transformed, TransformedTool)
+    assert transformed.name == "find_items"
+    assert "query" in transformed.parameters["properties"]
+
+
+def test_from_tool_decorated_function_preserves_metadata():
+    @tool(description="Custom description")
+    def search(q: str) -> list[str]:
+        """Original description."""
+        return []
+
+    transformed = Tool.from_tool(search)
+    assert transformed.parent_tool.description == "Custom description"
+
+
+async def test_from_tool_decorated_function_runs(add_tool):
+    @tool
+    def add(x: int, y: int = 10) -> int:
+        return x + y
+
+    transformed = Tool.from_tool(
+        add,
+        transform_args={"x": ArgTransform(name="a")},
+    )
+    result = await transformed.run(arguments={"a": 3, "y": 5})
+    assert result.structured_content == {"result": 8}
+
+
+async def test_renamed_arg_description_is_maintained(add_tool):
+    new_tool = Tool.from_tool(
+        add_tool, transform_args={"old_x": ArgTransform(name="new_x")}
+    )
+    assert (
+        new_tool.parameters["properties"]["new_x"]["description"] == "old_x description"
+    )
+
+
+async def test_tool_defaults_are_maintained_on_unmapped_args(add_tool):
+    new_tool = Tool.from_tool(
+        add_tool, transform_args={"old_x": ArgTransform(name="new_x")}
+    )
+    result = await new_tool.run(arguments={"new_x": 1})
+    # The parent tool returns int which gets wrapped as structured output
+    assert result.structured_content == {"result": 11}
+
+
+async def test_tool_defaults_are_maintained_on_mapped_args(add_tool):
+    new_tool = Tool.from_tool(
+        add_tool, transform_args={"old_y": ArgTransform(name="new_y")}
+    )
+    result = await new_tool.run(arguments={"old_x": 1})
+    # The parent tool returns int which gets wrapped as structured output
+    assert result.structured_content == {"result": 11}
+
+
+def test_tool_change_arg_name(add_tool):
+    new_tool = Tool.from_tool(
+        add_tool, transform_args={"old_x": ArgTransform(name="new_x")}
+    )
+
+    assert sorted(new_tool.parameters["properties"]) == ["new_x", "old_y"]
+    assert get_property(new_tool, "new_x") == get_property(add_tool, "old_x")
+    assert get_property(new_tool, "old_y") == get_property(add_tool, "old_y")
+    assert new_tool.parameters["required"] == ["new_x"]
+
+
+def test_tool_change_arg_description(add_tool):
+    new_tool = Tool.from_tool(
+        add_tool, transform_args={"old_x": ArgTransform(description="new description")}
+    )
+    assert get_property(new_tool, "old_x")["description"] == "new description"
+
+
+async def test_tool_drop_arg(add_tool):
+    new_tool = Tool.from_tool(
+        add_tool, transform_args={"old_y": ArgTransform(hide=True)}
+    )
+    assert sorted(new_tool.parameters["properties"]) == ["old_x"]
+    result = await new_tool.run(arguments={"old_x": 1})
+    assert result.structured_content == {"result": 11}
+
+
+async def test_dropped_args_error_if_provided(add_tool):
+    new_tool = Tool.from_tool(
+        add_tool, transform_args={"old_y": ArgTransform(hide=True)}
+    )
+    with pytest.raises(
+        TypeError, match="Got unexpected keyword argument\\(s\\): old_y"
+    ):
+        await new_tool.run(arguments={"old_x": 1, "old_y": 2})
+
+
+async def test_hidden_arg_with_constant_default(add_tool):
+    new_tool = Tool.from_tool(
+        add_tool, transform_args={"old_y": ArgTransform(hide=True)}
+    )
+    result = await new_tool.run(arguments={"old_x": 1})
+    # old_y should use its default value of 10
+    assert result.structured_content == {"result": 11}
+
+
+async def test_hidden_arg_without_default_uses_parent_default(add_tool):
+    """Test that hidden argument without default uses parent's default."""
+    new_tool = Tool.from_tool(
+        add_tool, transform_args={"old_y": ArgTransform(hide=True)}
+    )
+    # Only old_x should be exposed
+    assert sorted(new_tool.parameters["properties"]) == ["old_x"]
+    # Should pass old_x=3 and let parent use its default old_y=10
+    result = await new_tool.run(arguments={"old_x": 3})
+    assert isinstance(result.content[0], TextContent)
+    assert result.content[0].text == "13"
+    assert result.structured_content == {"result": 13}
+
+
+async def test_mixed_hidden_args_with_custom_function(add_tool):
+    async def custom_fn(new_x: int, **kwargs) -> str:
+        result = await forward(new_x=new_x, **kwargs)
+        assert isinstance(result.content[0], TextContent)
+        return f"Custom: {result.content[0].text}"
+
+    new_tool = Tool.from_tool(
+        add_tool,
+        transform_fn=custom_fn,
+        transform_args={
+            "old_x": ArgTransform(name="new_x"),
+            "old_y": ArgTransform(hide=True),
+        },
+    )
+
+    result = await new_tool.run(arguments={"new_x": 5})
+    assert isinstance(result.content[0], TextContent)
+    assert result.content[0].text == "Custom: 15"
+
+
+async def test_hide_required_param_without_default_raises_error():
+    """Test that hiding a required parameter without providing default raises error."""
+
+    @Tool.from_function
+    def tool_with_required_param(required_param: int, optional_param: int = 10) -> int:
+        return required_param + optional_param
+
+    # This should raise an error because required_param has no default and we're not providing one
+    with pytest.raises(
+        ValueError,
+        match=r"Hidden parameter 'required_param' has no default value in parent tool",
+    ):
+        Tool.from_tool(
+            tool_with_required_param,
+            transform_args={"required_param": ArgTransform(hide=True)},
+        )
+
+
+async def test_hide_required_param_with_user_default_works():
+    """Test that hiding a required parameter works when user provides a default."""
+
+    @Tool.from_function
+    def tool_with_required_param(required_param: int, optional_param: int = 10) -> int:
+        return required_param + optional_param
+
+    # This should work because we're providing a default for the hidden required param
+    new_tool = Tool.from_tool(
+        tool_with_required_param,
+        transform_args={"required_param": ArgTransform(hide=True, default=5)},
+    )
+
+    # Only optional_param should be exposed
+    assert sorted(new_tool.parameters["properties"]) == ["optional_param"]
+    # Should pass required_param=5 and optional_param=20 to parent
+    result = await new_tool.run(arguments={"optional_param": 20})
+    assert result.structured_content == {"result": 25}
+
+
+async def test_hidden_param_prunes_defs():
+    class VisibleType(BaseModel):
+        x: int
+
+    class HiddenType(BaseModel):
+        y: int
+
+    @Tool.from_function
+    def tool_with_refs(a: VisibleType, b: HiddenType | None = None) -> int:
+        return a.x + (b.y if b else 0)
+
+    # Hide parameter 'b'
+    new_tool = Tool.from_tool(
+        tool_with_refs, transform_args={"b": ArgTransform(hide=True)}
+    )
+
+    schema = new_tool.parameters
+    # Only 'a' should be visible
+    assert list(schema["properties"].keys()) == ["a"]
+    # HiddenType should be pruned from $defs
+    assert "HiddenType" not in schema.get("$defs", {})
+    # VisibleType should remain in $defs and be referenced via $ref
+    assert schema["properties"]["a"] == {"$ref": "#/$defs/VisibleType"}
+    assert schema["$defs"]["VisibleType"] == {
+        "properties": {"x": {"type": "integer"}},
+        "required": ["x"],
+        "type": "object",
+    }
+
+
+async def test_arg_transform_type_hoists_defs_to_root():
+    """Regression test for #4093: ArgTransform(type=...) must hoist any $defs
+    introduced by the new type to the schema root, not leave them nested
+    inside the property where $ref values like '#/$defs/...' would dangle.
+    """
+
+    class Filter(BaseModel):
+        value: str
+
+    @Tool.from_function
+    def search(query: str, filters: dict | None = None) -> str:
+        return ""
+
+    new_tool = Tool.from_tool(
+        search, transform_args={"filters": ArgTransform(type=list[Filter])}
+    )
+
+    schema = new_tool.parameters
+    assert "$defs" in schema
+    assert "Filter" in schema["$defs"]
+    assert "$defs" not in schema["properties"]["filters"]
+    assert schema["properties"]["filters"]["items"] == {"$ref": "#/$defs/Filter"}
+
+
+async def test_arg_transform_type_merges_with_parent_defs():
+    """When the parent tool already has $defs, ArgTransform(type=...) defs
+    should be merged into the existing root $defs alongside them."""
+
+    class Existing(BaseModel):
+        a: int
+
+    class Added(BaseModel):
+        b: int
+
+    @Tool.from_function
+    def tool_fn(x: Existing, y: dict | None = None) -> int:
+        return x.a + (y["b"] if y else 0)
+
+    new_tool = Tool.from_tool(
+        tool_fn, transform_args={"y": ArgTransform(type=list[Added])}
+    )
+
+    schema = new_tool.parameters
+    assert "Existing" in schema["$defs"]
+    assert "Added" in schema["$defs"]
+    assert "$defs" not in schema["properties"]["y"]
+
+
+async def test_arg_transform_type_raises_on_defs_name_collision():
+    """ArgTransform must not silently overwrite a parent's $defs entry when
+    the colliding name maps to a different schema; refs already copied from
+    the parent would then resolve to the wrong type."""
+
+    class Foo(BaseModel):
+        a: int
+
+    @Tool.from_function
+    def tool_fn(foo: Foo, other: dict | None = None) -> int:
+        return foo.a
+
+    # Parent already defines `Foo`; introduce a transform whose new type is
+    # also exposed under the `Foo` key in $defs but with a different schema.
+    # We do this by mutating the parent tool's parameters in place to plant a
+    # colliding definition, then applying a transform that re-introduces it.
+    tool_fn.parameters["$defs"]["Foo"] = {
+        "type": "object",
+        "properties": {"different": {"type": "string"}},
+        "required": ["different"],
+        "title": "Foo",
+    }
+
+    with pytest.raises(ValueError, match=r"\$defs collision for 'Foo'"):
+        Tool.from_tool(tool_fn, transform_args={"other": ArgTransform(type=list[Foo])})
+
+
+async def test_forward_with_argument_mapping(add_tool):
+    async def custom_fn(new_x: int, **kwargs) -> str:
+        result = await forward(new_x=new_x, **kwargs)
+        assert isinstance(result.content[0], TextContent)
+        return f"Mapped: {result.content[0].text}"
+
+    new_tool = Tool.from_tool(
+        add_tool,
+        transform_fn=custom_fn,
+        transform_args={"old_x": ArgTransform(name="new_x")},
+    )
+
+    result = await new_tool.run(arguments={"new_x": 3, "old_y": 7})
+    assert isinstance(result.content[0], TextContent)
+    assert result.content[0].text == "Mapped: 10"
+
+
+async def test_forward_with_incorrect_args_raises_error(add_tool):
+    async def custom_fn(new_x: int, new_y: int = 5) -> ToolResult:
+        # the forward should use the new args, not the old ones
+        return await forward(old_x=new_x, old_y=new_y)
+
+    new_tool = Tool.from_tool(
+        add_tool,
+        transform_fn=custom_fn,
+        transform_args={
+            "old_x": ArgTransform(name="new_x"),
+            "old_y": ArgTransform(name="new_y"),
+        },
+    )
+    with pytest.raises(
+        TypeError, match=re.escape("Got unexpected keyword argument(s): old_x, old_y")
+    ):
+        await new_tool.run(arguments={"new_x": 2, "new_y": 3})
+
+
+async def test_forward_raw_without_argument_mapping(add_tool):
+    async def custom_fn(**kwargs) -> str:
+        # forward_raw passes through kwargs as-is
+        result = await forward_raw(**kwargs)
+        assert isinstance(result.content[0], TextContent)
+        return f"Raw: {result.content[0].text}"
+
+    new_tool = Tool.from_tool(add_tool, transform_fn=custom_fn)
+
+    result = await new_tool.run(arguments={"old_x": 2, "old_y": 8})
+    assert isinstance(result.content[0], TextContent)
+    assert result.content[0].text == "Raw: 10"
+
+
+async def test_custom_fn_with_kwargs_and_no_transform_args(add_tool):
+    async def custom_fn(**kwargs) -> str:
+        result = await forward(**kwargs)
+        assert isinstance(result.content[0], TextContent)
+        return f"Custom: {result.content[0].text}"
+
+    new_tool = Tool.from_tool(add_tool, transform_fn=custom_fn)
+
+    result = await new_tool.run(arguments={"old_x": 4, "old_y": 6})
+    assert isinstance(result.content[0], TextContent)
+    assert result.content[0].text == "Custom: 10"
+
+
+async def test_fn_with_kwargs_passes_through_original_args(add_tool):
+    async def custom_fn(**kwargs) -> str:
+        # Should receive original arg names
+        assert "old_x" in kwargs
+        assert "old_y" in kwargs
+        result = await forward(**kwargs)
+        assert isinstance(result.content[0], TextContent)
+        return result.content[0].text
+
+    new_tool = Tool.from_tool(add_tool, transform_fn=custom_fn)
+
+    result = await new_tool.run(arguments={"old_x": 1, "old_y": 2})
+    assert isinstance(result.content[0], TextContent)
+    assert result.content[0].text == "3"
+
+
+async def test_fn_with_kwargs_receives_transformed_arg_names(add_tool):
+    """Test that **kwargs receives arguments with their transformed names from transform_args."""
+
+    async def custom_fn(new_x: int, **kwargs) -> ToolResult:
+        # kwargs should contain 'old_y': 3 (transformed name), not 'old_y': 3 (original name)
+        assert kwargs == {"old_y": 3}
+        result = await forward(new_x=new_x, **kwargs)
+        return result
+
+    new_tool = Tool.from_tool(
+        add_tool,
+        transform_fn=custom_fn,
+        transform_args={"old_x": ArgTransform(name="new_x")},
+    )
+    result = await new_tool.run(arguments={"new_x": 2, "old_y": 3})
+    assert isinstance(result.content[0], TextContent)
+    assert result.content[0].text == "5"
+    assert result.structured_content == {"result": 5}
+
+
+async def test_fn_with_kwargs_handles_partial_explicit_args(add_tool):
+    async def custom_fn(new_x: int, **kwargs) -> str:
+        result = await forward(new_x=new_x, **kwargs)
+        assert isinstance(result.content[0], TextContent)
+        return result.content[0].text
+
+    new_tool = Tool.from_tool(
+        add_tool,
+        transform_fn=custom_fn,
+        transform_args={"old_x": ArgTransform(name="new_x")},
+    )
+
+    # Only provide new_x, old_y should use default
+    result = await new_tool.run(arguments={"new_x": 7})
+    assert isinstance(result.content[0], TextContent)
+    assert result.content[0].text == "17"  # 7 + 10 (default)
+
+
+async def test_fn_with_kwargs_mixed_mapped_and_unmapped_args(add_tool):
+    async def custom_fn(new_x: int, old_y: int, **kwargs) -> str:
+        result = await forward(new_x=new_x, old_y=old_y, **kwargs)
+        assert isinstance(result.content[0], TextContent)
+        return result.content[0].text
+
+    new_tool = Tool.from_tool(
+        add_tool,
+        transform_fn=custom_fn,
+        transform_args={"old_x": ArgTransform(name="new_x")},
+    )
+
+    result = await new_tool.run(arguments={"new_x": 2, "old_y": 8})
+    assert isinstance(result.content[0], TextContent)
+    assert result.content[0].text == "10"
+
+
+async def test_fn_with_kwargs_dropped_args_not_in_kwargs(add_tool):
+    async def custom_fn(new_x: int, **kwargs) -> str:
+        # old_y is dropped, so it shouldn't be in kwargs
+        assert "old_y" not in kwargs
+        result = await forward(new_x=new_x, **kwargs)
+        assert isinstance(result.content[0], TextContent)
+        return result.content[0].text
+
+    new_tool = Tool.from_tool(
+        add_tool,
+        transform_fn=custom_fn,
+        transform_args={
+            "old_x": ArgTransform(name="new_x"),
+            "old_y": ArgTransform(hide=True),
+        },
+    )
+
+    result = await new_tool.run(arguments={"new_x": 3})
+    assert isinstance(result.content[0], TextContent)
+    assert result.content[0].text == "13"  # 3 + 10 (default for hidden old_y)
+
+
+async def test_forward_outside_context_raises_error():
+    """Test that forward() raises error when called outside transform context."""
+    with pytest.raises(RuntimeError, match=r"forward\(\) can only be called"):
+        await forward(x=1)
+
+
+async def test_forward_raw_outside_context_raises_error():
+    """Test that forward_raw() raises error when called outside transform context."""
+    with pytest.raises(RuntimeError, match=r"forward_raw\(\) can only be called"):
+        await forward_raw(x=1)
+
+
+def test_transform_args_with_parent_defaults():
+    """Test that transform_args with parent defaults works."""
+
+    class CoolModel(BaseModel):
+        x: int = 10
+
+    def parent_tool(cool_model: CoolModel) -> int:
+        return cool_model.x
+
+    tool = Tool.from_function(parent_tool)
+
+    new_tool = Tool.from_tool(tool)
+
+    # Both tools should have the same schema (with $ref/$defs preserved)
+    assert new_tool.parameters == tool.parameters
+
+
+def test_transform_args_validation_unknown_arg(add_tool):
+    """Test that transform_args with unknown arguments raises ValueError."""
+    with pytest.raises(
+        ValueError, match="Unknown arguments in transform_args: unknown_param"
+    ) as exc_info:
+        Tool.from_tool(
+            add_tool, transform_args={"unknown_param": ArgTransform(name="new_name")}
+        )
+
+    assert "`add`" in str(exc_info.value)
+
+
+def test_transform_args_creates_duplicate_names(add_tool):
+    """Test that transform_args creating duplicate parameter names raises ValueError."""
+    with pytest.raises(
+        ValueError,
+        match="Multiple arguments would be mapped to the same names: same_name",
+    ):
+        Tool.from_tool(
+            add_tool,
+            transform_args={
+                "old_x": ArgTransform(name="same_name"),
+                "old_y": ArgTransform(name="same_name"),
+            },
+        )
+
+
+def test_transform_args_collision_with_passthrough_name(add_tool):
+    """Test that renaming to a passthrough parameter name raises ValueError."""
+    with pytest.raises(
+        ValueError,
+        match="Multiple arguments would be mapped to the same names: old_y",
+    ):
+        Tool.from_tool(
+            add_tool,
+            transform_args={
+                "old_x": ArgTransform(name="old_y"),
+            },
+        )
+
+
+def test_function_without_kwargs_missing_params(add_tool):
+    """Test that function missing required transformed parameters raises ValueError."""
+
+    def invalid_fn(new_x: int, non_existent: str) -> str:
+        return f"{new_x}_{non_existent}"
+
+    with pytest.raises(
+        ValueError,
+        match="Function missing parameters required after transformation: new_y",
+    ):
+        Tool.from_tool(
+            add_tool,
+            transform_fn=invalid_fn,
+            transform_args={
+                "old_x": ArgTransform(name="new_x"),
+                "old_y": ArgTransform(name="new_y"),
+            },
+        )
+
+
+def test_function_without_kwargs_can_have_extra_params(add_tool):
+    """Test that function can have extra parameters not in parent tool."""
+
+    def valid_fn(new_x: int, new_y: int, extra_param: str = "default") -> str:
+        return f"{new_x}_{new_y}_{extra_param}"
+
+    # Should work - extra_param is fine as long as it has a default
+    new_tool = Tool.from_tool(
+        add_tool,
+        transform_fn=valid_fn,
+        transform_args={
+            "old_x": ArgTransform(name="new_x"),
+            "old_y": ArgTransform(name="new_y"),
+        },
+    )
+
+    # The final schema should include all function parameters
+    assert "new_x" in new_tool.parameters["properties"]
+    assert "new_y" in new_tool.parameters["properties"]
+    assert "extra_param" in new_tool.parameters["properties"]
+
+
+def test_function_with_kwargs_can_add_params(add_tool):
+    """Test that function with **kwargs can add new parameters."""
+
+    async def valid_fn(extra_param: str, **kwargs) -> str:
+        result = await forward(**kwargs)
+        return f"{extra_param}: {result}"
+
+    # This should work fine - kwargs allows access to all transformed params
+    tool = Tool.from_tool(
+        add_tool,
+        transform_fn=valid_fn,
+        transform_args={
+            "old_x": ArgTransform(name="new_x"),
+            "old_y": ArgTransform(name="new_y"),
+        },
+    )
+
+    # extra_param is added, new_x and new_y are available
+    assert "extra_param" in tool.parameters["properties"]
+    assert "new_x" in tool.parameters["properties"]
+
+
+async def test_from_tool_decorated_function_via_client():
+    @tool
+    def search(q: str, limit: int = 10) -> list[str]:
+        """Search for items."""
+        return [f"Result {i} for {q}" for i in range(limit)]
+
+    better_search = Tool.from_tool(
+        search,
+        name="find_items",
+        transform_args={
+            "q": ArgTransform(name="query", description="The search terms"),
+        },
+    )
+
+    mcp = FastMCP("Server")
+    mcp.add_tool(better_search)
+
+    async with Client(mcp) as client:
+        result = await client.call_tool("find_items", {"query": "hello", "limit": 3})
+        assert isinstance(result.content[0], TextContent)
+        assert "Result 0 for hello" in result.content[0].text
+
+
+async def test_transform_fn_result_respects_serialize_by_alias():
+    """A model returned by a transform_fn honors serialize_by_alias when no schema."""
+    from pydantic import ConfigDict
+
+    class Item(BaseModel):
+        model_config = ConfigDict(serialize_by_alias=False)
+        id: str = Field(alias="_id")
+
+    def base() -> None:
+        pass
+
+    async def transform() -> Any:
+        return Item(_id="42")
+
+    transformed = Tool.from_tool(base, transform_fn=transform, output_schema=None)
+    result = await transformed.run({})
+
+    assert result.structured_content == {"id": "42"}
+
+
+async def test_transform_fn_wrapped_result_respects_serialize_by_alias():
+    """A wrapped transform result serializes the inner model before nesting.
+
+    Optional model returns get a wrap-result schema; the inner model must be
+    serialized with its own config before being placed under "result", or the
+    wrapped dict masks the config and the data no longer matches the schema.
+    """
+    from pydantic import ConfigDict
+
+    class Item(BaseModel):
+        model_config = ConfigDict(serialize_by_alias=False)
+        id: str = Field(alias="_id")
+
+    def base() -> None:
+        pass
+
+    async def transform() -> Item | None:
+        return Item(_id="42")
+
+    transformed = Tool.from_tool(base, transform_fn=transform)
+    assert transformed.output_schema is not None
+    assert transformed.output_schema.get("x-fastmcp-wrap-result")
+    result = await transformed.run({})
+
+    assert result.structured_content == {"result": {"id": "42"}}
+
+
+class TestProxy:
+    @pytest.fixture
+    def mcp_server(self) -> FastMCP:
+        mcp = FastMCP()
+
+        @mcp.tool
+        def add(old_x: int, old_y: int = 10) -> int:
+            return old_x + old_y
+
+        return mcp
+
+    @pytest.fixture
+    def proxy_server(self, mcp_server: FastMCP) -> FastMCP:
+        from fastmcp.client.transports import FastMCPTransport
+        from fastmcp.server import create_proxy
+
+        proxy = create_proxy(FastMCPTransport(mcp_server))
+        return proxy
+
+    async def test_transform_proxy(self, proxy_server: FastMCP):
+        # when adding transformed tools to proxy servers. Needs separate investigation.
+
+        add_tool = await proxy_server.get_tool("add")
+        assert add_tool is not None
+        new_add_tool = Tool.from_tool(
+            add_tool,
+            name="add_transformed",
+            transform_args={"old_x": ArgTransform(name="new_x")},
+        )
+        proxy_server.add_tool(new_add_tool)
+
+        async with Client(proxy_server) as client:
+            # The tool should be registered with its transformed name
+            result = await client.call_tool("add_transformed", {"new_x": 1, "old_y": 2})
+            assert isinstance(result.content[0], TextContent)
+            assert result.content[0].text == "3"
+
+
+async def test_sync_transform_fn():
+    """Sync transform_fn should not crash when called (was unconditionally awaited)."""
+
+    @Tool.from_function
+    def parent(x: int, y: int = 10) -> int:
+        return x + y
+
+    def sync_transform(x: int, **kwargs) -> str:
+        return f"transformed: {x}"
+
+    transformed = Tool.from_tool(parent, transform_fn=sync_transform)
+    result = await transformed.run(arguments={"x": 7})
+    assert isinstance(result.content[0], TextContent)
+    assert result.content[0].text == "transformed: 7"
+
+
+async def test_transform_args_do_not_mutate_parent_schema():
+    """Mutating a transformed tool's schema must not corrupt the parent's schema."""
+
+    @Tool.from_function
+    def parent(x: int, y: int = 10) -> int:
+        return x + y
+
+    parent_props_before = {
+        k: dict(v) for k, v in parent.parameters["properties"].items()
+    }
+
+    transformed = Tool.from_tool(
+        parent,
+        transform_args={"x": ArgTransform(name="a")},
+    )
+
+    transformed.parameters["properties"]["a"]["description"] = "INJECTED"
+
+    parent_props_after = parent.parameters["properties"]
+    assert parent_props_after == parent_props_before
diff --git a/tests/utilities/__init__.py b/tests/utilities/__init__.py
new file mode 100644
index 0000000..e179392
--- /dev/null
+++ b/tests/utilities/__init__.py
@@ -0,0 +1 @@
+"""Tests for utilities in the fastmcp package."""
diff --git a/tests/utilities/json_schema_type/__init__.py b/tests/utilities/json_schema_type/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/utilities/json_schema_type/cluster_failures.py b/tests/utilities/json_schema_type/cluster_failures.py
new file mode 100644
index 0000000..5c6b440
--- /dev/null
+++ b/tests/utilities/json_schema_type/cluster_failures.py
@@ -0,0 +1,107 @@
+"""Cluster real-world schema failure records by exception signature.
+
+Usage
+-----
+Run the crash test with DUMP_SCHEMA_FAILURES to collect per-failure records,
+then run this script to cluster them:
+
+    # 1. Run the crash test with failure dumping enabled:
+    RUN_REAL_WORLD_SCHEMA_TEST=1 \\
+    OPENAPI_DIRECTORY_PATH=/tmp/openapi-directory \\
+    DUMP_SCHEMA_FAILURES=/tmp/schema_failures \\
+    uv run pytest tests/utilities/json_schema_type/test_real_world_schemas.py \\
+        -m integration -n auto --timeout-method=thread -q
+
+    # 2. Cluster the failures:
+    python tests/utilities/json_schema_type/cluster_failures.py
+
+    # 3. (Optional) specify a custom dump directory:
+    DUMP_SCHEMA_FAILURES=/my/path python tests/utilities/json_schema_type/cluster_failures.py
+
+Each JSONL record written by the test has the shape:
+    {
+        "provider": "amazonaws.com",
+        "name": "TagKey",
+        "bucket": "schema_errors",           # type_errors | schema_errors | timeouts | other_errors
+        "error_type": "SchemaError",
+        "error_msg": "...",
+        "schema": "{...}"                    # JSON-encoded, truncated to 2000 chars
+    }
+
+Workflow for fixing a cluster
+------------------------------
+1. Identify the top cluster(s) by count.
+2. Grab the example schema from the cluster output.
+3. Reproduce in a unit test: add a test to test_json_schema_type.py that calls
+   json_schema_to_type() with that schema and asserts the correct type is returned.
+4. Fix the root cause in fastmcp_slim/fastmcp/utilities/json_schema_type.py.
+5. Re-run the crash test — confirm the cluster count drops.
+6. Ratchet the baseline in tests/utilities/json_schema_type/conftest.py:
+   - Lower MAX_TYPE_ERRORS / MAX_SCHEMA_ERRORS to the new actual count.
+   - Add a comment with the date and what was fixed.
+7. Commit.
+"""
+
+from __future__ import annotations
+
+import collections
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+DUMP_DIR = Path(os.environ.get("DUMP_SCHEMA_FAILURES", "/tmp/schema_failures"))
+
+_NORMALIZE_RE = re.compile(r"'[^']{3,}'|\"[^\"]{3,}\"|0x[0-9a-fA-F]+|\b\d+\b")
+
+
+def normalize(msg: str) -> str:
+    head = "\n".join(msg.splitlines()[:3])
+    return _NORMALIZE_RE.sub("<X>", head)[:300]
+
+
+def main() -> None:
+    if not DUMP_DIR.exists():
+        print(f"No dump directory found at {DUMP_DIR}.")
+        print("Run the crash test with DUMP_SCHEMA_FAILURES set first.")
+        sys.exit(1)
+
+    records = []
+    for f in DUMP_DIR.glob("*.jsonl"):
+        for line in f.read_text().splitlines():
+            if line.strip():
+                records.append(json.loads(line))
+
+    if not records:
+        print(f"No failure records found in {DUMP_DIR}. All schemas passed!")
+        return
+
+    print(f"Total failures: {len(records)}")
+    print()
+
+    buckets: collections.Counter[str] = collections.Counter(
+        r["bucket"] for r in records
+    )
+    for k, v in buckets.most_common():
+        print(f"  {k}: {v}")
+    print()
+
+    clusters: collections.Counter[tuple[str, str, str]] = collections.Counter()
+    examples: dict[tuple[str, str, str], dict] = {}
+    for r in records:
+        key = (r["bucket"], r["error_type"], normalize(r["error_msg"]))
+        clusters[key] += 1
+        examples.setdefault(key, r)
+
+    print(f"=== Top clusters (of {len(clusters)} total) ===")
+    for (bucket, etype, sig), count in clusters.most_common():
+        print(f"\n[{count:>4}x] {bucket} / {etype}")
+        print(f"       sig: {sig[:150]}")
+        ex = examples[(bucket, etype, sig)]
+        print(f"       ex : provider={ex['provider']}  name={ex['name']}")
+        print(f"       msg: {ex['error_msg'][:200]}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tests/utilities/json_schema_type/conftest.py b/tests/utilities/json_schema_type/conftest.py
new file mode 100644
index 0000000..635defc
--- /dev/null
+++ b/tests/utilities/json_schema_type/conftest.py
@@ -0,0 +1,111 @@
+"""Session hooks for the real-world schema crash test.
+
+Per-provider tests in `test_real_world_schemas.py` run under `pytest-xdist` —
+each worker is a separate process, so module-level accumulators don't survive
+across workers. Each test persists its counts to `SCHEMA_CRASH_RESULTS_DIR`
+and the session-finish hook below reads them back on the xdist master after
+all workers finish.
+
+These hooks must live in conftest.py (not the test module) because pytest
+only picks up `pytest_configure` / `pytest_sessionfinish` from conftest files.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from pathlib import Path
+
+import pytest
+
+SCHEMA_CRASH_RESULTS_DIR = Path(
+    os.environ.get("SCHEMA_CRASH_RESULTS_DIR", "/tmp/schema_crash_results")
+)
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    """Clear prior per-provider results at session start (xdist master only)."""
+    if hasattr(config, "workerinput"):
+        return
+    shutil.rmtree(SCHEMA_CRASH_RESULTS_DIR, ignore_errors=True)
+    SCHEMA_CRASH_RESULTS_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def pytest_sessionfinish(session: pytest.Session, exitstatus: int) -> None:
+    """Aggregate per-provider results once all xdist workers finish."""
+    if hasattr(session.config, "workerinput"):
+        return
+    if not SCHEMA_CRASH_RESULTS_DIR.exists():
+        return
+    files = list(SCHEMA_CRASH_RESULTS_DIR.glob("*.json"))
+    if not files:
+        return
+
+    keys = ("schemas", "type_errors", "schema_errors", "timeouts", "other_errors")
+    totals = dict.fromkeys(keys, 0)
+    for f in files:
+        data = json.loads(f.read_text())
+        for k in keys:
+            totals[k] += data.get(k, 0)
+
+    crashes = (
+        totals["type_errors"]
+        + totals["schema_errors"]
+        + totals["timeouts"]
+        + totals["other_errors"]
+    )
+
+    print(f"\n{'=' * 60}")
+    print("Real-world schema crash test — aggregate results")
+    print(f"{'=' * 60}")
+    print(f"Providers tested: {len(files):,}")
+    print(f"Schemas tested:  {totals['schemas']:,}")
+    print(f"TypeErrors:      {totals['type_errors']:,}")
+    print(f"SchemaErrors:    {totals['schema_errors']:,}")
+    print(f"Timeouts:        {totals['timeouts']:,}")
+    print(f"Other errors:    {totals['other_errors']:,}")
+    print(
+        f"Total crashes:   {crashes:,} ({crashes / max(totals['schemas'], 1) * 100:.2f}%)"
+    )
+
+    # Snapshot baselines (openapi-directory@f7207cf0).
+    # Ratcheted 2026-04-17: TypeErrors 420→0 (already fixed on main).
+    # SchemaErrors 300→5: graceful pattern fallback in _create_string_type
+    # now catches unsupported Rust-regex patterns (lookahead, \p{…}, size
+    # limits) and degrades to str with a warning instead of crashing.
+    # 1 non-regex SchemaError remains: api.video's video-thumbnail-pick-payload
+    # declares `"pattern": 0.0` (a float, not a string) — a bug in the spec,
+    # intentionally not caught by the regex-only fallback guard.
+    MAX_TYPE_ERRORS = 0
+    MAX_SCHEMA_ERRORS = 5  # was 279; ~1 remains as a legitimate non-regex error
+    MAX_TIMEOUTS = 5  # was 0
+    MAX_OTHER_ERRORS = 50  # was 0
+
+    failures: list[str] = []
+    if totals["schemas"] <= 200_000:
+        failures.append(
+            f"Expected >200k schemas but only found {totals['schemas']}. "
+            f"Is the openapi-directory checkout correct?"
+        )
+    if totals["type_errors"] > MAX_TYPE_ERRORS:
+        failures.append(
+            f"TypeErrors regressed: {totals['type_errors']} > {MAX_TYPE_ERRORS}"
+        )
+    if totals["schema_errors"] > MAX_SCHEMA_ERRORS:
+        failures.append(
+            f"SchemaErrors regressed: {totals['schema_errors']} > {MAX_SCHEMA_ERRORS}"
+        )
+    if totals["timeouts"] > MAX_TIMEOUTS:
+        failures.append(f"Timeouts regressed: {totals['timeouts']} > {MAX_TIMEOUTS}")
+    if totals["other_errors"] > MAX_OTHER_ERRORS:
+        failures.append(
+            f"Other errors regressed: {totals['other_errors']} > {MAX_OTHER_ERRORS}"
+        )
+
+    if failures:
+        print("\nBASELINE VIOLATIONS:")
+        for msg in failures:
+            print(f"  - {msg}")
+        # Force a non-zero exit even though all individual tests passed.
+        session.exitstatus = pytest.ExitCode.TESTS_FAILED
diff --git a/tests/utilities/json_schema_type/test_advanced.py b/tests/utilities/json_schema_type/test_advanced.py
new file mode 100644
index 0000000..01f4900
--- /dev/null
+++ b/tests/utilities/json_schema_type/test_advanced.py
@@ -0,0 +1,941 @@
+"""Advanced JSON schema type conversion features."""
+
+from dataclasses import Field
+from typing import Union
+
+import pytest
+from pydantic import BaseModel, TypeAdapter, ValidationError
+
+from fastmcp.utilities.json_schema_type import (
+    _hash_schema,
+    _merge_defaults,
+    json_schema_to_type,
+)
+
+
+def get_dataclass_field(type: type, field_name: str) -> Field:
+    return type.__dataclass_fields__[field_name]  # ty: ignore[unresolved-attribute]
+
+
+class TestDefaultValues:
+    """Test suite for default value handling."""
+
+    @pytest.fixture
+    def simple_defaults(self):
+        return json_schema_to_type(
+            {
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string", "default": "anonymous"},
+                    "age": {"type": "integer", "default": 0},
+                },
+            }
+        )
+
+    @pytest.fixture
+    def nested_defaults(self):
+        return json_schema_to_type(
+            {
+                "type": "object",
+                "properties": {
+                    "user": {
+                        "type": "object",
+                        "properties": {
+                            "name": {"type": "string", "default": "anonymous"},
+                            "settings": {
+                                "type": "object",
+                                "properties": {
+                                    "theme": {"type": "string", "default": "light"}
+                                },
+                                "default": {"theme": "dark"},
+                            },
+                        },
+                        "default": {"name": "guest", "settings": {"theme": "system"}},
+                    }
+                },
+            }
+        )
+
+    def test_simple_defaults_empty_object(self, simple_defaults):
+        validator = TypeAdapter(simple_defaults)
+        result = validator.validate_python({})
+        assert result.name == "anonymous"
+        assert result.age == 0
+
+    def test_simple_defaults_partial_override(self, simple_defaults):
+        validator = TypeAdapter(simple_defaults)
+        result = validator.validate_python({"name": "test"})
+        assert result.name == "test"
+        assert result.age == 0
+
+    def test_nested_defaults_empty_object(self, nested_defaults):
+        validator = TypeAdapter(nested_defaults)
+        result = validator.validate_python({})
+        assert result.user.name == "guest"
+        assert result.user.settings.theme == "system"
+
+    def test_nested_defaults_partial_override(self, nested_defaults):
+        validator = TypeAdapter(nested_defaults)
+        result = validator.validate_python({"user": {"name": "test"}})
+        assert result.user.name == "test"
+        assert result.user.settings.theme == "system"
+
+
+class TestCircularReferences:
+    """Test suite for circular reference handling."""
+
+    @pytest.fixture
+    def self_referential(self):
+        return json_schema_to_type(
+            {
+                "type": "object",
+                "properties": {"name": {"type": "string"}, "child": {"$ref": "#"}},
+            }
+        )
+
+    @pytest.fixture
+    def mutually_recursive(self):
+        return json_schema_to_type(
+            {
+                "type": "object",
+                "definitions": {
+                    "Person": {
+                        "type": "object",
+                        "properties": {
+                            "name": {"type": "string"},
+                            "friend": {"$ref": "#/definitions/Pet"},
+                        },
+                    },
+                    "Pet": {
+                        "type": "object",
+                        "properties": {
+                            "name": {"type": "string"},
+                            "owner": {"$ref": "#/definitions/Person"},
+                        },
+                    },
+                },
+                "properties": {"person": {"$ref": "#/definitions/Person"}},
+            }
+        )
+
+    def test_self_ref_single_level(self, self_referential):
+        validator = TypeAdapter(self_referential)
+        result = validator.validate_python(
+            {"name": "parent", "child": {"name": "child"}}
+        )
+        assert result.name == "parent"
+        assert result.child.name == "child"
+        assert result.child.child is None
+
+    def test_self_ref_multiple_levels(self, self_referential):
+        validator = TypeAdapter(self_referential)
+        result = validator.validate_python(
+            {
+                "name": "grandparent",
+                "child": {"name": "parent", "child": {"name": "child"}},
+            }
+        )
+        assert result.name == "grandparent"
+        assert result.child.name == "parent"
+        assert result.child.child.name == "child"
+
+    def test_mutual_recursion_single_level(self, mutually_recursive):
+        validator = TypeAdapter(mutually_recursive)
+        result = validator.validate_python(
+            {"person": {"name": "Alice", "friend": {"name": "Spot"}}}
+        )
+        assert result.person.name == "Alice"
+        assert result.person.friend.name == "Spot"
+        assert result.person.friend.owner is None
+
+    def test_mutual_recursion_multiple_levels(self, mutually_recursive):
+        validator = TypeAdapter(mutually_recursive)
+        result = validator.validate_python(
+            {
+                "person": {
+                    "name": "Alice",
+                    "friend": {"name": "Spot", "owner": {"name": "Bob"}},
+                }
+            }
+        )
+        assert result.person.name == "Alice"
+        assert result.person.friend.name == "Spot"
+        assert result.person.friend.owner.name == "Bob"
+
+
+class TestIdentifierNormalization:
+    """Test suite for handling non-standard property names."""
+
+    @pytest.fixture
+    def special_chars(self):
+        return json_schema_to_type(
+            {
+                "type": "object",
+                "properties": {
+                    "@type": {"type": "string"},
+                    "first-name": {"type": "string"},
+                    "last.name": {"type": "string"},
+                    "2nd_address": {"type": "string"},
+                    "$ref": {"type": "string"},
+                },
+            }
+        )
+
+    def test_normalizes_special_chars(self, special_chars):
+        validator = TypeAdapter(special_chars)
+        result = validator.validate_python(
+            {
+                "@type": "person",
+                "first-name": "Alice",
+                "last.name": "Smith",
+                "2nd_address": "456 Oak St",
+                "$ref": "12345",
+            }
+        )
+        assert result.field_type == "person"  # @type -> field_type
+        assert result.first_name == "Alice"  # first-name -> first_name
+        assert result.last_name == "Smith"  # last.name -> last_name
+        assert (
+            result.field_2nd_address == "456 Oak St"
+        )  # 2nd_address -> field_2nd_address
+        assert result.field_ref == "12345"  # $ref -> field_ref
+
+
+class TestConstantValues:
+    """Test suite for constant value validation."""
+
+    @pytest.fixture
+    def string_const(self):
+        return json_schema_to_type({"type": "string", "const": "production"})
+
+    @pytest.fixture
+    def number_const(self):
+        return json_schema_to_type({"type": "number", "const": 42.5})
+
+    @pytest.fixture
+    def boolean_const(self):
+        return json_schema_to_type({"type": "boolean", "const": True})
+
+    @pytest.fixture
+    def null_const(self):
+        return json_schema_to_type({"type": "null", "const": None})
+
+    @pytest.fixture
+    def object_with_consts(self):
+        return json_schema_to_type(
+            {
+                "type": "object",
+                "properties": {
+                    "env": {"const": "production"},
+                    "version": {"const": 1},
+                    "enabled": {"const": True},
+                },
+            }
+        )
+
+    def test_string_const_valid(self, string_const):
+        validator = TypeAdapter(string_const)
+        assert validator.validate_python("production") == "production"
+
+    def test_string_const_invalid(self, string_const):
+        validator = TypeAdapter(string_const)
+        with pytest.raises(ValidationError):
+            validator.validate_python("development")
+
+    def test_number_const_valid(self, number_const):
+        validator = TypeAdapter(number_const)
+        assert validator.validate_python(42.5) == 42.5
+
+    def test_number_const_invalid(self, number_const):
+        validator = TypeAdapter(number_const)
+        with pytest.raises(ValidationError):
+            validator.validate_python(42)
+
+    def test_boolean_const_valid(self, boolean_const):
+        validator = TypeAdapter(boolean_const)
+        assert validator.validate_python(True) is True
+
+    def test_boolean_const_invalid(self, boolean_const):
+        validator = TypeAdapter(boolean_const)
+        with pytest.raises(ValidationError):
+            validator.validate_python(False)
+
+    def test_null_const_valid(self, null_const):
+        validator = TypeAdapter(null_const)
+        assert validator.validate_python(None) is None
+
+    def test_null_const_invalid(self, null_const):
+        validator = TypeAdapter(null_const)
+        with pytest.raises(ValidationError):
+            validator.validate_python(False)
+
+    def test_object_consts_valid(self, object_with_consts):
+        validator = TypeAdapter(object_with_consts)
+        result = validator.validate_python(
+            {"env": "production", "version": 1, "enabled": True}
+        )
+        assert result.env == "production"
+        assert result.version == 1
+        assert result.enabled is True
+
+    def test_object_consts_invalid(self, object_with_consts):
+        validator = TypeAdapter(object_with_consts)
+        with pytest.raises(ValidationError):
+            validator.validate_python(
+                {
+                    "env": "production",
+                    "version": 2,  # Wrong constant
+                    "enabled": True,
+                }
+            )
+
+
+class TestSchemaCaching:
+    """Test suite for schema caching behavior."""
+
+    def test_identical_schemas_reuse_class(self):
+        schema = {"type": "object", "properties": {"name": {"type": "string"}}}
+
+        class1 = json_schema_to_type(schema)
+        class2 = json_schema_to_type(schema)
+        assert class1 is class2
+
+    def test_different_names_different_classes(self):
+        schema = {"type": "object", "properties": {"name": {"type": "string"}}}
+
+        class1 = json_schema_to_type(schema, name="Class1")
+        class2 = json_schema_to_type(schema, name="Class2")
+        assert class1 is not class2
+        assert class1.__name__ == "Class1"
+        assert class2.__name__ == "Class2"
+
+    def test_nested_schema_caching(self):
+        schema = {
+            "type": "object",
+            "properties": {
+                "nested": {"type": "object", "properties": {"name": {"type": "string"}}}
+            },
+        }
+
+        class1 = json_schema_to_type(schema)
+        class2 = json_schema_to_type(schema)
+
+        # Both main classes and their nested classes should be identical
+        assert class1 is class2
+        assert (
+            get_dataclass_field(class1, "nested").type
+            is get_dataclass_field(class2, "nested").type
+        )
+
+
+class TestSchemaHashing:
+    """Test suite for schema hashing utility."""
+
+    def test_deterministic_hash(self):
+        schema = {"type": "object", "properties": {"name": {"type": "string"}}}
+        hash1 = _hash_schema(schema)
+        hash2 = _hash_schema(schema)
+        assert hash1 == hash2
+        assert isinstance(hash1, str)
+        assert len(hash1) == 64  # SHA-256 hash length
+
+    def test_different_schemas_different_hashes(self):
+        schema1 = {"type": "object", "properties": {"name": {"type": "string"}}}
+        schema2 = {"type": "object", "properties": {"age": {"type": "integer"}}}
+        assert _hash_schema(schema1) != _hash_schema(schema2)
+
+    def test_order_independent_hash(self):
+        schema1 = {"properties": {"name": {"type": "string"}}, "type": "object"}
+        schema2 = {"type": "object", "properties": {"name": {"type": "string"}}}
+        assert _hash_schema(schema1) == _hash_schema(schema2)
+
+    def test_nested_schema_hash(self):
+        schema = {
+            "type": "object",
+            "properties": {
+                "nested": {"type": "object", "properties": {"name": {"type": "string"}}}
+            },
+        }
+        hash1 = _hash_schema(schema)
+        assert isinstance(hash1, str)
+        assert len(hash1) == 64
+
+
+class TestDefaultMerging:
+    """Test suite for default value merging behavior."""
+
+    def test_simple_merge(self):
+        defaults = {"name": "anonymous", "age": 0}
+        data = {"name": "test"}
+        result = _merge_defaults(data, {"properties": {}}, defaults)
+        assert result["name"] == "test"
+        assert result["age"] == 0
+
+    def test_nested_merge(self):
+        defaults = {"user": {"name": "anonymous", "settings": {"theme": "light"}}}
+        data = {"user": {"name": "test"}}
+        result = _merge_defaults(data, {"properties": {}}, defaults)
+        assert result["user"]["name"] == "test"
+        assert result["user"]["settings"]["theme"] == "light"
+
+    def test_array_merge(self):
+        defaults = {
+            "items": [
+                {"name": "item1", "done": False},
+                {"name": "item2", "done": False},
+            ]
+        }
+        data = {"items": [{"name": "custom", "done": True}]}
+        result = _merge_defaults(data, {"properties": {}}, defaults)
+        assert len(result["items"]) == 1
+        assert result["items"][0]["name"] == "custom"
+        assert result["items"][0]["done"] is True
+
+    def test_empty_data_uses_defaults(self):
+        schema = {
+            "properties": {
+                "user": {
+                    "type": "object",
+                    "properties": {
+                        "name": {"type": "string", "default": "anonymous"},
+                        "settings": {"type": "object", "default": {"theme": "light"}},
+                    },
+                    "default": {"name": "guest", "settings": {"theme": "dark"}},
+                }
+            }
+        }
+        result = _merge_defaults({}, schema)
+        assert result["user"]["name"] == "guest"
+        assert result["user"]["settings"]["theme"] == "dark"
+
+    def test_property_level_defaults(self):
+        schema = {
+            "properties": {
+                "name": {"type": "string", "default": "anonymous"},
+                "age": {"type": "integer", "default": 0},
+            }
+        }
+        result = _merge_defaults({}, schema)
+        assert result["name"] == "anonymous"
+        assert result["age"] == 0
+
+    def test_nested_property_defaults(self):
+        schema = {
+            "properties": {
+                "user": {
+                    "type": "object",
+                    "properties": {
+                        "name": {"type": "string", "default": "anonymous"},
+                        "settings": {
+                            "type": "object",
+                            "properties": {
+                                "theme": {"type": "string", "default": "light"}
+                            },
+                        },
+                    },
+                }
+            }
+        }
+        result = _merge_defaults({"user": {"settings": {}}}, schema)
+        assert result["user"]["name"] == "anonymous"
+        assert result["user"]["settings"]["theme"] == "light"
+
+    def test_default_priority(self):
+        schema = {
+            "properties": {
+                "settings": {
+                    "type": "object",
+                    "properties": {"theme": {"type": "string", "default": "light"}},
+                    "default": {"theme": "dark"},
+                }
+            },
+            "default": {"settings": {"theme": "system"}},
+        }
+
+        # Test priority: data > parent default > object default > property default
+        result1 = _merge_defaults({}, schema)  # Uses schema default
+        assert result1["settings"]["theme"] == "system"
+
+        result2 = _merge_defaults({"settings": {}}, schema)  # Uses object default
+        assert result2["settings"]["theme"] == "dark"
+
+        result3 = _merge_defaults(
+            {"settings": {"theme": "custom"}}, schema
+        )  # Uses provided data
+        assert result3["settings"]["theme"] == "custom"
+
+
+class TestEdgeCases:
+    """Test suite for edge cases and corner scenarios."""
+
+    def test_empty_schema(self):
+        schema = {}
+        result = json_schema_to_type(schema)
+        assert result is object
+
+    def test_schema_without_type(self):
+        schema = {"properties": {"name": {"type": "string"}}}
+        Type = json_schema_to_type(schema)
+        validator = TypeAdapter(Type)
+        result = validator.validate_python({"name": "test"})
+        assert result.name == "test"  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+
+    def test_recursive_defaults(self):
+        schema = {
+            "type": "object",
+            "properties": {
+                "node": {
+                    "type": "object",
+                    "properties": {"value": {"type": "string"}, "next": {"$ref": "#"}},
+                    "default": {"value": "default", "next": None},
+                }
+            },
+        }
+        Type = json_schema_to_type(schema)
+        validator = TypeAdapter(Type)
+        result = validator.validate_python({})
+        assert result.node.value == "default"  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+        assert result.node.next is None  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+
+    def test_recursive_ref_in_anyof_does_not_recurse_forever(self):
+        schema = {
+            "type": "object",
+            "properties": {
+                "items": {"type": "array", "items": {"$ref": "#/$defs/JSONValue"}},
+            },
+            "$defs": {
+                "JSONValue": {
+                    "anyOf": [
+                        {"type": "string"},
+                        {"type": "array", "items": {"$ref": "#/$defs/JSONValue"}},
+                        {
+                            "type": "object",
+                            "additionalProperties": {"$ref": "#/$defs/JSONValue"},
+                        },
+                    ]
+                }
+            },
+        }
+
+        Type = json_schema_to_type(schema)
+        validator = TypeAdapter(Type)
+        result = validator.validate_python(
+            {"items": ["value", ["nested"], {"key": ["leaf"]}]}
+        )
+
+        assert result.items == ["value", ["nested"], {"key": ["leaf"]}]  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+
+    def test_mixed_type_array(self):
+        schema = {
+            "type": "array",
+            "items": [{"type": "string"}, {"type": "number"}, {"type": "boolean"}],
+        }
+        Type = json_schema_to_type(schema)
+        validator = TypeAdapter(Type)
+        result = validator.validate_python(["test", 123, True])
+        assert result == ["test", 123, True]
+
+
+class TestNameHandling:
+    """Test suite for schema name handling."""
+
+    def test_name_from_title(self):
+        schema = {
+            "type": "object",
+            "title": "Person",
+            "properties": {"name": {"type": "string"}},
+        }
+        Type = json_schema_to_type(schema)
+        assert Type.__name__ == "Person"
+
+    def test_explicit_name_overrides_title(self):
+        schema = {
+            "type": "object",
+            "title": "Person",
+            "properties": {"name": {"type": "string"}},
+        }
+        Type = json_schema_to_type(schema, name="CustomPerson")
+        assert Type.__name__ == "CustomPerson"
+
+    def test_default_name_without_title(self):
+        schema = {"type": "object", "properties": {"name": {"type": "string"}}}
+        Type = json_schema_to_type(schema)
+        assert Type.__name__ == "Root"
+
+    def test_name_only_allowed_for_objects(self):
+        schema = {"type": "string"}
+        with pytest.raises(ValueError, match="Can not apply name to non-object schema"):
+            json_schema_to_type(schema, name="StringType")
+
+    def test_nested_object_names(self):
+        schema = {
+            "type": "object",
+            "title": "Parent",
+            "properties": {
+                "child": {
+                    "type": "object",
+                    "title": "Child",
+                    "properties": {"name": {"type": "string"}},
+                }
+            },
+        }
+        Type = json_schema_to_type(schema)
+        assert Type.__name__ == "Parent"
+        child_field_type = get_dataclass_field(Type, "child").type
+        assert child_field_type.__origin__ is Union  # ty: ignore[unresolved-attribute]
+        assert child_field_type.__args__[0].__name__ == "Child"  # ty: ignore[unresolved-attribute]
+        assert child_field_type.__args__[1] is type(None)  # ty: ignore[unresolved-attribute]
+
+    def test_recursive_schema_naming(self):
+        schema = {
+            "type": "object",
+            "title": "Node",
+            "properties": {"next": {"$ref": "#"}},
+        }
+        Type = json_schema_to_type(schema)
+        assert Type.__name__ == "Node"
+
+        next_field_type = get_dataclass_field(Type, "next").type
+
+        assert next_field_type.__origin__ is Union  # ty: ignore[unresolved-attribute]
+        assert next_field_type.__args__[0].__forward_arg__ == "Node"  # ty: ignore[unresolved-attribute]
+        assert next_field_type.__args__[1] is type(None)  # ty: ignore[unresolved-attribute]
+
+    def test_name_caching_with_different_titles(self):
+        """Ensure schemas with different titles create different cached classes"""
+        schema1 = {
+            "type": "object",
+            "title": "Type1",
+            "properties": {"name": {"type": "string"}},
+        }
+        schema2 = {
+            "type": "object",
+            "title": "Type2",
+            "properties": {"name": {"type": "string"}},
+        }
+        Type1 = json_schema_to_type(schema1)
+        Type2 = json_schema_to_type(schema2)
+        assert Type1 is not Type2
+        assert Type1.__name__ == "Type1"
+        assert Type2.__name__ == "Type2"
+
+    def test_recursive_schema_with_invalid_python_name(self):
+        """Test that recursive schemas work with titles that aren't valid Python identifiers"""
+        schema = {
+            "type": "object",
+            "title": "My Complex Type!",
+            "properties": {"name": {"type": "string"}, "child": {"$ref": "#"}},
+        }
+        Type = json_schema_to_type(schema)
+        # The class should get a sanitized name
+        assert Type.__name__ == "My_Complex_Type"
+        # Create an instance to verify the recursive reference works
+        validator = TypeAdapter(Type)
+        result = validator.validate_python(
+            {"name": "parent", "child": {"name": "child", "child": None}}
+        )
+        assert result.name == "parent"  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+        assert result.child.name == "child"  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+        assert result.child.child is None  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+
+
+class TestAdditionalProperties:
+    """Test suite for additionalProperties handling."""
+
+    @pytest.fixture
+    def dict_only_schema(self):
+        """Schema with no properties but additionalProperties=True -> dict[str, Any]"""
+        return json_schema_to_type({"type": "object", "additionalProperties": True})
+
+    @pytest.fixture
+    def properties_with_additional(self):
+        """Schema with properties AND additionalProperties=True -> BaseModel"""
+        return json_schema_to_type(
+            {
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string"},
+                    "age": {"type": "integer"},
+                },
+                "additionalProperties": True,
+            }
+        )
+
+    @pytest.fixture
+    def properties_without_additional(self):
+        """Schema with properties but no additionalProperties -> dataclass"""
+        return json_schema_to_type(
+            {
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string"},
+                    "age": {"type": "integer"},
+                },
+            }
+        )
+
+    @pytest.fixture
+    def required_properties_with_additional(self):
+        """Schema with required properties AND additionalProperties=True -> BaseModel"""
+        return json_schema_to_type(
+            {
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string"},
+                    "age": {"type": "integer"},
+                },
+                "required": ["name"],
+                "additionalProperties": True,
+            }
+        )
+
+    def test_dict_only_returns_dict_type(self, dict_only_schema):
+        """Test that schema with no properties + additionalProperties=True returns dict[str, Any]"""
+        import typing
+
+        assert dict_only_schema == dict[str, typing.Any]
+
+    def test_dict_only_accepts_any_data(self, dict_only_schema):
+        """Test that pure dict accepts arbitrary key-value pairs"""
+        validator = TypeAdapter(dict_only_schema)
+        data = {"anything": "works", "numbers": 123, "nested": {"key": "value"}}
+        result = validator.validate_python(data)
+        assert result == data
+        assert isinstance(result, dict)
+
+    def test_properties_with_additional_returns_basemodel(
+        self, properties_with_additional
+    ):
+        """Test that schema with properties + additionalProperties=True returns BaseModel"""
+        assert issubclass(properties_with_additional, BaseModel)
+
+    def test_properties_with_additional_accepts_extra_fields(
+        self, properties_with_additional
+    ):
+        """Test that BaseModel with extra='allow' accepts additional properties"""
+        validator = TypeAdapter(properties_with_additional)
+        data = {
+            "name": "Alice",
+            "age": 30,
+            "extra": "field",
+            "another": {"nested": "data"},
+        }
+        result = validator.validate_python(data)
+
+        # Check standard properties
+        assert result.name == "Alice"
+        assert result.age == 30
+
+        # Check extra properties are preserved with dot access
+        assert hasattr(result, "extra")
+        assert result.extra == "field"
+        assert hasattr(result, "another")
+        assert result.another == {"nested": "data"}
+
+    def test_properties_with_additional_validates_known_fields(
+        self, properties_with_additional
+    ):
+        """Test that BaseModel still validates known fields"""
+        validator = TypeAdapter(properties_with_additional)
+
+        # Should accept valid data
+        result = validator.validate_python({"name": "Alice", "age": 30, "extra": "ok"})
+        assert result.name == "Alice"
+        assert result.age == 30
+        assert result.extra == "ok"
+
+        # Should reject invalid types for known fields
+        with pytest.raises(ValidationError):
+            validator.validate_python({"name": "Alice", "age": "not_a_number"})
+
+    def test_properties_without_additional_is_dataclass(
+        self, properties_without_additional
+    ):
+        """Test that schema with properties but no additionalProperties returns dataclass"""
+        assert not issubclass(properties_without_additional, BaseModel)
+        assert hasattr(properties_without_additional, "__dataclass_fields__")
+
+    def test_properties_without_additional_ignores_extra_fields(
+        self, properties_without_additional
+    ):
+        """Test that dataclass ignores extra properties (current behavior)"""
+        validator = TypeAdapter(properties_without_additional)
+        data = {"name": "Alice", "age": 30, "extra": "ignored"}
+        result = validator.validate_python(data)
+
+        # Check standard properties
+        assert result.name == "Alice"
+        assert result.age == 30
+
+        # Check extra property is ignored
+        assert not hasattr(result, "extra")
+
+    def test_required_properties_with_additional(
+        self, required_properties_with_additional
+    ):
+        """Test BaseModel with required fields and additional properties"""
+        validator = TypeAdapter(required_properties_with_additional)
+
+        # Should accept valid data with required field
+        result = validator.validate_python({"name": "Alice", "extra": "field"})
+        assert result.name == "Alice"
+        assert result.age is None  # Optional field
+        assert result.extra == "field"
+
+        # Should reject missing required field
+        with pytest.raises(ValidationError):
+            validator.validate_python({"age": 30, "extra": "field"})
+
+    def test_nested_additional_properties(self):
+        """Test nested objects with additionalProperties"""
+        schema = {
+            "type": "object",
+            "properties": {
+                "user": {
+                    "type": "object",
+                    "properties": {"name": {"type": "string"}},
+                    "additionalProperties": True,
+                },
+                "settings": {
+                    "type": "object",
+                    "properties": {"theme": {"type": "string"}},
+                },
+            },
+            "additionalProperties": True,
+        }
+
+        Type = json_schema_to_type(schema)
+        validator = TypeAdapter(Type)
+
+        data = {
+            "user": {"name": "Alice", "extra_user_field": "value"},
+            "settings": {"theme": "dark", "extra_settings_field": "ignored"},
+            "top_level_extra": "preserved",
+        }
+
+        result = validator.validate_python(data)
+
+        # Check top-level extra field (BaseModel)
+        assert result.top_level_extra == "preserved"  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+
+        # Check nested user extra field (BaseModel)
+        assert result.user.name == "Alice"  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+        assert result.user.extra_user_field == "value"  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+
+        # Check nested settings - should be dataclass
+        assert result.settings.theme == "dark"  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+        # Note: When nested in BaseModel with extra='allow', Pydantic may preserve extra fields
+        # even on dataclass children. The important thing is that settings is still a dataclass.
+        assert not issubclass(type(result.settings), BaseModel)  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+
+    def test_additional_properties_false_vs_missing(self):
+        """Test difference between additionalProperties: false and missing additionalProperties"""
+        # Schema with explicit additionalProperties: false
+        schema_false = {
+            "type": "object",
+            "properties": {"name": {"type": "string"}},
+            "additionalProperties": False,
+        }
+
+        # Schema with no additionalProperties key
+        schema_missing = {
+            "type": "object",
+            "properties": {"name": {"type": "string"}},
+        }
+
+        Type_false = json_schema_to_type(schema_false)
+        Type_missing = json_schema_to_type(schema_missing)
+
+        # Both should create dataclasses (not BaseModel)
+        assert not issubclass(Type_false, BaseModel)
+        assert not issubclass(Type_missing, BaseModel)
+        assert hasattr(Type_false, "__dataclass_fields__")
+        assert hasattr(Type_missing, "__dataclass_fields__")
+
+    def test_additional_properties_with_defaults(self):
+        """Test additionalProperties with default values"""
+        schema = {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "default": "anonymous"},
+                "age": {"type": "integer", "default": 0},
+            },
+            "additionalProperties": True,
+        }
+
+        Type = json_schema_to_type(schema)
+        validator = TypeAdapter(Type)
+
+        # Test with extra fields and defaults
+        result = validator.validate_python({"extra": "field"})
+        assert result.name == "anonymous"  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+        assert result.age == 0  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+        assert result.extra == "field"  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+
+    def test_additional_properties_type_consistency(self):
+        """Test that the same schema always returns the same type"""
+        schema = {
+            "type": "object",
+            "properties": {"name": {"type": "string"}},
+            "additionalProperties": True,
+        }
+
+        Type1 = json_schema_to_type(schema)
+        Type2 = json_schema_to_type(schema)
+
+        # Should be the same cached class
+        assert Type1 is Type2
+        assert issubclass(Type1, BaseModel)
+
+
+class TestFieldsWithDefaults:
+    """Test suite for fields with default values not being made nullable."""
+
+    def test_field_with_default_preserves_type(self):
+        """Test that fields with defaults preserve their original type."""
+        schema = {
+            "type": "object",
+            "properties": {"flag": {"type": "boolean", "default": False}},
+        }
+
+        generated_type = json_schema_to_type(schema)
+        regenerated_schema = TypeAdapter(generated_type).json_schema()
+
+        assert regenerated_schema["properties"]["flag"]["type"] == "boolean"
+
+    def test_field_with_default_not_nullable(self):
+        """Test that fields with defaults are not made nullable."""
+        schema = {
+            "type": "object",
+            "properties": {"flag": {"type": "boolean", "default": False}},
+        }
+
+        generated_type = json_schema_to_type(schema)
+        regenerated_schema = TypeAdapter(generated_type).json_schema()
+
+        flag_prop = regenerated_schema["properties"]["flag"]
+        assert "anyOf" not in flag_prop
+
+    def test_field_with_default_uses_default(self):
+        """Test that fields with defaults use their default values."""
+        schema = {
+            "type": "object",
+            "properties": {"flag": {"type": "boolean", "default": False}},
+        }
+
+        generated_type = json_schema_to_type(schema)
+        validator = TypeAdapter(generated_type)
+        result = validator.validate_python({})
+        assert result.flag is False  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+
+    def test_field_with_default_accepts_explicit_value(self):
+        """Test that fields with defaults accept explicit values."""
+        schema = {
+            "type": "object",
+            "properties": {"flag": {"type": "boolean", "default": False}},
+        }
+
+        generated_type = json_schema_to_type(schema)
+        validator = TypeAdapter(generated_type)
+        result = validator.validate_python({"flag": True})
+        assert result.flag is True  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
diff --git a/tests/utilities/json_schema_type/test_constraints.py b/tests/utilities/json_schema_type/test_constraints.py
new file mode 100644
index 0000000..53a1d9a
--- /dev/null
+++ b/tests/utilities/json_schema_type/test_constraints.py
@@ -0,0 +1,132 @@
+"""Tests for type constraints in JSON schema conversion."""
+
+from dataclasses import Field
+
+import pytest
+from pydantic import TypeAdapter, ValidationError
+
+from fastmcp.utilities.json_schema_type import (
+    json_schema_to_type,
+)
+
+
+def get_dataclass_field(type: type, field_name: str) -> Field:
+    return type.__dataclass_fields__[field_name]  # ty: ignore[unresolved-attribute]
+
+
+class TestStringConstraints:
+    """Test suite for string constraint validation."""
+
+    @pytest.fixture
+    def min_length_string(self):
+        return json_schema_to_type({"type": "string", "minLength": 3})
+
+    @pytest.fixture
+    def max_length_string(self):
+        return json_schema_to_type({"type": "string", "maxLength": 5})
+
+    @pytest.fixture
+    def pattern_string(self):
+        return json_schema_to_type({"type": "string", "pattern": "^[A-Z][a-z]+$"})
+
+    @pytest.fixture
+    def email_string(self):
+        return json_schema_to_type({"type": "string", "format": "email"})
+
+    def test_min_length_accepts_valid(self, min_length_string):
+        validator = TypeAdapter(min_length_string)
+        assert validator.validate_python("test") == "test"
+
+    def test_min_length_rejects_short(self, min_length_string):
+        validator = TypeAdapter(min_length_string)
+        with pytest.raises(ValidationError):
+            validator.validate_python("ab")
+
+    def test_max_length_accepts_valid(self, max_length_string):
+        validator = TypeAdapter(max_length_string)
+        assert validator.validate_python("test") == "test"
+
+    def test_max_length_rejects_long(self, max_length_string):
+        validator = TypeAdapter(max_length_string)
+        with pytest.raises(ValidationError):
+            validator.validate_python("toolong")
+
+    def test_pattern_accepts_valid(self, pattern_string):
+        validator = TypeAdapter(pattern_string)
+        assert validator.validate_python("Hello") == "Hello"
+
+    def test_pattern_rejects_invalid(self, pattern_string):
+        validator = TypeAdapter(pattern_string)
+        with pytest.raises(ValidationError):
+            validator.validate_python("hello")
+
+    def test_email_accepts_valid(self, email_string):
+        validator = TypeAdapter(email_string)
+        result = validator.validate_python("test@example.com")
+        assert result == "test@example.com"
+
+    def test_email_rejects_invalid(self, email_string):
+        validator = TypeAdapter(email_string)
+        with pytest.raises(ValidationError):
+            validator.validate_python("not-an-email")
+
+
+class TestNumberConstraints:
+    """Test suite for numeric constraint validation."""
+
+    @pytest.fixture
+    def multiple_of_number(self):
+        return json_schema_to_type({"type": "number", "multipleOf": 0.5})
+
+    @pytest.fixture
+    def min_number(self):
+        return json_schema_to_type({"type": "number", "minimum": 0})
+
+    @pytest.fixture
+    def exclusive_min_number(self):
+        return json_schema_to_type({"type": "number", "exclusiveMinimum": 0})
+
+    @pytest.fixture
+    def max_number(self):
+        return json_schema_to_type({"type": "number", "maximum": 100})
+
+    @pytest.fixture
+    def exclusive_max_number(self):
+        return json_schema_to_type({"type": "number", "exclusiveMaximum": 100})
+
+    def test_multiple_of_accepts_valid(self, multiple_of_number):
+        validator = TypeAdapter(multiple_of_number)
+        assert validator.validate_python(2.5) == 2.5
+
+    def test_multiple_of_rejects_invalid(self, multiple_of_number):
+        validator = TypeAdapter(multiple_of_number)
+        with pytest.raises(ValidationError):
+            validator.validate_python(2.7)
+
+    def test_minimum_accepts_equal(self, min_number):
+        validator = TypeAdapter(min_number)
+        assert validator.validate_python(0) == 0
+
+    def test_minimum_rejects_less(self, min_number):
+        validator = TypeAdapter(min_number)
+        with pytest.raises(ValidationError):
+            validator.validate_python(-1)
+
+    def test_exclusive_minimum_rejects_equal(self, exclusive_min_number):
+        validator = TypeAdapter(exclusive_min_number)
+        with pytest.raises(ValidationError):
+            validator.validate_python(0)
+
+    def test_maximum_accepts_equal(self, max_number):
+        validator = TypeAdapter(max_number)
+        assert validator.validate_python(100) == 100
+
+    def test_maximum_rejects_greater(self, max_number):
+        validator = TypeAdapter(max_number)
+        with pytest.raises(ValidationError):
+            validator.validate_python(101)
+
+    def test_exclusive_maximum_rejects_equal(self, exclusive_max_number):
+        validator = TypeAdapter(exclusive_max_number)
+        with pytest.raises(ValidationError):
+            validator.validate_python(100)
diff --git a/tests/utilities/json_schema_type/test_containers.py b/tests/utilities/json_schema_type/test_containers.py
new file mode 100644
index 0000000..1391245
--- /dev/null
+++ b/tests/utilities/json_schema_type/test_containers.py
@@ -0,0 +1,230 @@
+"""Tests for container types in JSON schema conversion."""
+
+from dataclasses import Field, dataclass
+from typing import Any
+
+import pytest
+from pydantic import TypeAdapter, ValidationError
+
+from fastmcp.utilities.json_schema_type import (
+    json_schema_to_type,
+)
+
+
+def get_dataclass_field(type: type, field_name: str) -> Field:
+    return type.__dataclass_fields__[field_name]  # ty: ignore[unresolved-attribute]
+
+
+class TestArrayTypes:
+    """Test suite for array validation."""
+
+    @pytest.fixture
+    def string_array(self):
+        return json_schema_to_type({"type": "array", "items": {"type": "string"}})
+
+    @pytest.fixture
+    def min_items_array(self):
+        return json_schema_to_type(
+            {"type": "array", "items": {"type": "string"}, "minItems": 2}
+        )
+
+    @pytest.fixture
+    def max_items_array(self):
+        return json_schema_to_type(
+            {"type": "array", "items": {"type": "string"}, "maxItems": 3}
+        )
+
+    @pytest.fixture
+    def unique_items_array(self):
+        return json_schema_to_type(
+            {"type": "array", "items": {"type": "string"}, "uniqueItems": True}
+        )
+
+    def test_array_accepts_valid_items(self, string_array):
+        validator = TypeAdapter(string_array)
+        assert validator.validate_python(["a", "b"]) == ["a", "b"]
+
+    def test_array_rejects_invalid_items(self, string_array):
+        validator = TypeAdapter(string_array)
+        with pytest.raises(ValidationError):
+            validator.validate_python([1, "b"])
+
+    def test_min_items_accepts_valid(self, min_items_array):
+        validator = TypeAdapter(min_items_array)
+        assert validator.validate_python(["a", "b"]) == ["a", "b"]
+
+    def test_min_items_rejects_too_few(self, min_items_array):
+        validator = TypeAdapter(min_items_array)
+        with pytest.raises(ValidationError):
+            validator.validate_python(["a"])
+
+    def test_max_items_accepts_valid(self, max_items_array):
+        validator = TypeAdapter(max_items_array)
+        assert validator.validate_python(["a", "b", "c"]) == ["a", "b", "c"]
+
+    def test_max_items_rejects_too_many(self, max_items_array):
+        validator = TypeAdapter(max_items_array)
+        with pytest.raises(ValidationError):
+            validator.validate_python(["a", "b", "c", "d"])
+
+    def test_unique_items_accepts_unique(self, unique_items_array):
+        validator = TypeAdapter(unique_items_array)
+        assert isinstance(validator.validate_python(["a", "b"]), set)
+
+    def test_unique_items_converts_duplicates(self, unique_items_array):
+        validator = TypeAdapter(unique_items_array)
+        result = validator.validate_python(["a", "a", "b"])
+        assert result == {"a", "b"}
+
+
+class TestObjectTypes:
+    """Test suite for object validation."""
+
+    @pytest.fixture
+    def simple_object(self):
+        return json_schema_to_type(
+            {
+                "type": "object",
+                "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
+            }
+        )
+
+    @pytest.fixture
+    def required_object(self):
+        return json_schema_to_type(
+            {
+                "type": "object",
+                "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
+                "required": ["name"],
+            }
+        )
+
+    @pytest.fixture
+    def nested_object(self):
+        return json_schema_to_type(
+            {
+                "type": "object",
+                "properties": {
+                    "user": {
+                        "type": "object",
+                        "properties": {
+                            "name": {"type": "string"},
+                            "age": {"type": "integer"},
+                        },
+                        "required": ["name"],
+                    }
+                },
+            }
+        )
+
+    @pytest.mark.parametrize(
+        "input_type, expected_type",
+        [
+            # Plain dict becomes dict[str, Any] (JSON Schema accurate)
+            (dict, dict[str, Any]),
+            # dict[str, Any] stays the same
+            (dict[str, Any], dict[str, Any]),
+            # Simple typed dicts work correctly
+            (dict[str, str], dict[str, str]),
+            (dict[str, int], dict[str, int]),
+            # Union value types work
+            (dict[str, str | int], dict[str, str | int]),
+            # Key types are constrained to str in JSON Schema
+            (dict[int, list[str]], dict[str, list[str]]),
+            # Union key types become str (JSON Schema limitation)
+            (dict[str | int, str | None], dict[str, str | None]),
+        ],
+    )
+    def test_dict_types_are_generated_correctly(self, input_type, expected_type):
+        schema = TypeAdapter(input_type).json_schema()
+        generated_type = json_schema_to_type(schema)
+        assert generated_type == expected_type
+
+    @pytest.mark.parametrize(
+        "input_type, expected_type",
+        [
+            # list[dict] roundtrips correctly (not list[Root()])
+            (list[dict], list[dict[str, Any]]),
+            # list[dict[str, Any]] stays the same
+            (list[dict[str, Any]], list[dict[str, Any]]),
+            # list[dict[str, str]] preserves value type
+            (list[dict[str, str]], list[dict[str, str]]),
+            # list[dict[str, int]] preserves value type
+            (list[dict[str, int]], list[dict[str, int]]),
+        ],
+    )
+    def test_list_of_dict_types_roundtrip(self, input_type, expected_type):
+        """Ensure list[dict] schemas produce dict types, not dataclasses (issue #3867)."""
+        schema = TypeAdapter(input_type).json_schema()
+        generated_type = json_schema_to_type(schema)
+        assert generated_type == expected_type
+
+    def test_list_dict_validates_data(self):
+        """list[dict] schema should validate actual dict data, not produce Root() (issue #3867)."""
+        schema = TypeAdapter(list[dict]).json_schema()
+        generated_type = json_schema_to_type(schema)
+        validator = TypeAdapter(generated_type)
+        result = validator.validate_python(
+            [{"city": "NYC", "temp": 72}, {"city": "LA", "temp": 85}]
+        )
+        assert result == [{"city": "NYC", "temp": 72}, {"city": "LA", "temp": 85}]
+
+    def test_object_accepts_valid(self, simple_object):
+        validator = TypeAdapter(simple_object)
+        result = validator.validate_python({"name": "test", "age": 30})
+        assert result.name == "test"
+        assert result.age == 30
+
+    def test_object_accepts_extra_properties(self, simple_object):
+        validator = TypeAdapter(simple_object)
+        result = validator.validate_python(
+            {"name": "test", "age": 30, "extra": "field"}
+        )
+        assert result.name == "test"
+        assert result.age == 30
+        assert not hasattr(result, "extra")
+
+    def test_required_accepts_valid(self, required_object):
+        validator = TypeAdapter(required_object)
+        result = validator.validate_python({"name": "test"})
+        assert result.name == "test"
+        assert result.age is None
+
+    def test_required_rejects_missing(self, required_object):
+        validator = TypeAdapter(required_object)
+        with pytest.raises(ValidationError):
+            validator.validate_python({})
+
+    def test_nested_accepts_valid(self, nested_object):
+        validator = TypeAdapter(nested_object)
+        result = validator.validate_python({"user": {"name": "test", "age": 30}})
+        assert result.user.name == "test"
+        assert result.user.age == 30
+
+    def test_nested_rejects_invalid(self, nested_object):
+        validator = TypeAdapter(nested_object)
+        with pytest.raises(ValidationError):
+            validator.validate_python({"user": {"age": 30}})
+
+    def test_object_with_underscore_names(self):
+        @dataclass
+        class Data:
+            x: int
+            x_: int
+            _x: int
+
+        schema = TypeAdapter(Data).json_schema()
+        assert schema == {
+            "title": "Data",
+            "type": "object",
+            "properties": {
+                "x": {"type": "integer", "title": "X"},
+                "x_": {"type": "integer", "title": "X"},
+                "_x": {"type": "integer", "title": "X"},
+            },
+            "required": ["x", "x_", "_x"],
+        }
+
+        object = json_schema_to_type(schema)
+        object_schema = TypeAdapter(object).json_schema()
+        assert object_schema == schema
diff --git a/tests/utilities/json_schema_type/test_formats.py b/tests/utilities/json_schema_type/test_formats.py
new file mode 100644
index 0000000..781b81a
--- /dev/null
+++ b/tests/utilities/json_schema_type/test_formats.py
@@ -0,0 +1,114 @@
+"""Tests for format handling in JSON schema conversion."""
+
+from dataclasses import Field
+from datetime import datetime
+
+import pytest
+from pydantic import AnyUrl, TypeAdapter, ValidationError
+
+from fastmcp.utilities.json_schema_type import (
+    json_schema_to_type,
+)
+
+
+def get_dataclass_field(type: type, field_name: str) -> Field:
+    return type.__dataclass_fields__[field_name]  # ty: ignore[unresolved-attribute]
+
+
+class TestFormatTypes:
+    """Test suite for format type validation."""
+
+    @pytest.fixture
+    def datetime_format(self):
+        return json_schema_to_type({"type": "string", "format": "date-time"})
+
+    @pytest.fixture
+    def email_format(self):
+        return json_schema_to_type({"type": "string", "format": "email"})
+
+    @pytest.fixture
+    def uri_format(self):
+        return json_schema_to_type({"type": "string", "format": "uri"})
+
+    @pytest.fixture
+    def uri_reference_format(self):
+        return json_schema_to_type({"type": "string", "format": "uri-reference"})
+
+    @pytest.fixture
+    def json_format(self):
+        return json_schema_to_type({"type": "string", "format": "json"})
+
+    @pytest.fixture
+    def mixed_formats_object(self):
+        return json_schema_to_type(
+            {
+                "type": "object",
+                "properties": {
+                    "full_uri": {"type": "string", "format": "uri"},
+                    "ref_uri": {"type": "string", "format": "uri-reference"},
+                },
+            }
+        )
+
+    def test_datetime_valid(self, datetime_format):
+        validator = TypeAdapter(datetime_format)
+        result = validator.validate_python("2024-01-17T12:34:56Z")
+        assert isinstance(result, datetime)
+
+    def test_datetime_invalid(self, datetime_format):
+        validator = TypeAdapter(datetime_format)
+        with pytest.raises(ValidationError):
+            validator.validate_python("not-a-date")
+
+    def test_email_valid(self, email_format):
+        validator = TypeAdapter(email_format)
+        result = validator.validate_python("test@example.com")
+        assert isinstance(result, str)
+
+    def test_email_invalid(self, email_format):
+        validator = TypeAdapter(email_format)
+        with pytest.raises(ValidationError):
+            validator.validate_python("not-an-email")
+
+    def test_uri_valid(self, uri_format):
+        validator = TypeAdapter(uri_format)
+        result = validator.validate_python("https://example.com")
+        assert isinstance(result, AnyUrl)
+
+    def test_uri_invalid(self, uri_format):
+        validator = TypeAdapter(uri_format)
+        with pytest.raises(ValidationError):
+            validator.validate_python("not-a-uri")
+
+    def test_uri_reference_valid(self, uri_reference_format):
+        validator = TypeAdapter(uri_reference_format)
+        result = validator.validate_python("https://example.com")
+        assert isinstance(result, str)
+
+    def test_uri_reference_relative_valid(self, uri_reference_format):
+        validator = TypeAdapter(uri_reference_format)
+        result = validator.validate_python("/path/to/resource")
+        assert isinstance(result, str)
+
+    def test_uri_reference_invalid(self, uri_reference_format):
+        validator = TypeAdapter(uri_reference_format)
+        result = validator.validate_python("not a uri")
+        assert isinstance(result, str)
+
+    def test_json_valid(self, json_format):
+        validator = TypeAdapter(json_format)
+        result = validator.validate_python('{"key": "value"}')
+        assert isinstance(result, dict)
+
+    def test_json_invalid(self, json_format):
+        validator = TypeAdapter(json_format)
+        with pytest.raises(ValidationError):
+            validator.validate_python("{invalid json}")
+
+    def test_mixed_formats_object(self, mixed_formats_object):
+        validator = TypeAdapter(mixed_formats_object)
+        result = validator.validate_python(
+            {"full_uri": "https://example.com", "ref_uri": "/path/to/resource"}
+        )
+        assert isinstance(result.full_uri, AnyUrl)
+        assert isinstance(result.ref_uri, str)
diff --git a/tests/utilities/json_schema_type/test_json_schema_type.py b/tests/utilities/json_schema_type/test_json_schema_type.py
new file mode 100644
index 0000000..c125ddc
--- /dev/null
+++ b/tests/utilities/json_schema_type/test_json_schema_type.py
@@ -0,0 +1,406 @@
+"""Core JSON schema type conversion tests."""
+
+import dataclasses
+import warnings
+from dataclasses import Field
+from enum import Enum
+from typing import Any, Literal
+
+import pytest
+from pydantic import TypeAdapter, ValidationError
+
+from fastmcp.utilities.json_schema_type import (
+    json_schema_to_type,
+)
+
+
+def get_dataclass_field(type: type, field_name: str) -> Field:
+    return type.__dataclass_fields__[field_name]  # ty: ignore[unresolved-attribute]
+
+
+class TestSimpleTypes:
+    """Test suite for basic type validation."""
+
+    @pytest.fixture
+    def simple_string(self):
+        return json_schema_to_type({"type": "string"})
+
+    @pytest.fixture
+    def simple_number(self):
+        return json_schema_to_type({"type": "number"})
+
+    @pytest.fixture
+    def simple_integer(self):
+        return json_schema_to_type({"type": "integer"})
+
+    @pytest.fixture
+    def simple_boolean(self):
+        return json_schema_to_type({"type": "boolean"})
+
+    @pytest.fixture
+    def simple_null(self):
+        return json_schema_to_type({"type": "null"})
+
+    def test_string_accepts_string(self, simple_string):
+        validator = TypeAdapter(simple_string)
+        assert validator.validate_python("test") == "test"
+
+    def test_string_rejects_number(self, simple_string):
+        validator = TypeAdapter(simple_string)
+        with pytest.raises(ValidationError):
+            validator.validate_python(123)
+
+    def test_number_accepts_float(self, simple_number):
+        validator = TypeAdapter(simple_number)
+        assert validator.validate_python(123.45) == 123.45
+
+    def test_number_accepts_integer(self, simple_number):
+        validator = TypeAdapter(simple_number)
+        assert validator.validate_python(123) == 123
+
+    def test_number_accepts_numeric_string(self, simple_number):
+        validator = TypeAdapter(simple_number)
+        assert validator.validate_python("123.45") == 123.45
+        assert validator.validate_python("123") == 123
+
+    def test_number_rejects_invalid_string(self, simple_number):
+        validator = TypeAdapter(simple_number)
+        with pytest.raises(ValidationError):
+            validator.validate_python("not a number")
+
+    def test_integer_accepts_integer(self, simple_integer):
+        validator = TypeAdapter(simple_integer)
+        assert validator.validate_python(123) == 123
+
+    def test_integer_accepts_integer_string(self, simple_integer):
+        validator = TypeAdapter(simple_integer)
+        assert validator.validate_python("123") == 123
+
+    def test_integer_rejects_float(self, simple_integer):
+        validator = TypeAdapter(simple_integer)
+        with pytest.raises(ValidationError):
+            validator.validate_python(123.45)
+
+    def test_integer_rejects_float_string(self, simple_integer):
+        validator = TypeAdapter(simple_integer)
+        with pytest.raises(ValidationError):
+            validator.validate_python("123.45")
+
+    def test_boolean_accepts_boolean(self, simple_boolean):
+        validator = TypeAdapter(simple_boolean)
+        assert validator.validate_python(True) is True
+        assert validator.validate_python(False) is False
+
+    def test_boolean_accepts_boolean_strings(self, simple_boolean):
+        validator = TypeAdapter(simple_boolean)
+        assert validator.validate_python("true") is True
+        assert validator.validate_python("True") is True
+        assert validator.validate_python("false") is False
+        assert validator.validate_python("False") is False
+
+    def test_boolean_rejects_invalid_string(self, simple_boolean):
+        validator = TypeAdapter(simple_boolean)
+        with pytest.raises(ValidationError):
+            validator.validate_python("not a boolean")
+
+    def test_null_accepts_none(self, simple_null):
+        validator = TypeAdapter(simple_null)
+        assert validator.validate_python(None) is None
+
+    def test_null_rejects_false(self, simple_null):
+        validator = TypeAdapter(simple_null)
+        with pytest.raises(ValidationError):
+            validator.validate_python(False)
+
+
+class TestBooleanSchemas:
+    """JSON Schema draft-06+ allows true/false as property schemas."""
+
+    def test_true_property_schema_accepts_any_value(self):
+        """A property with schema `true` should accept any value."""
+        schema = {
+            "type": "object",
+            "properties": {"name": {"type": "string"}, "anything": True},
+            "required": ["name", "anything"],
+        }
+        result = json_schema_to_type(schema)
+        validator = TypeAdapter(result)
+        obj = validator.validate_python({"name": "test", "anything": 42})
+        assert obj.name == "test"  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+        assert obj.anything == 42  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+
+    def test_false_property_schema_rejects_values(self):
+        """A property with schema `false` should reject any provided value."""
+        schema = {
+            "type": "object",
+            "properties": {"name": {"type": "string"}, "never": False},
+            "required": ["name"],
+        }
+        result = json_schema_to_type(schema)
+        validator = TypeAdapter(result)
+        obj = validator.validate_python({"name": "test"})
+        assert obj.name == "test"  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+
+        with pytest.raises(ValidationError):
+            validator.validate_python({"name": "test", "never": "anything"})
+
+    def test_boolean_schema_in_object_with_additional_properties(self):
+        """Boolean property schemas work alongside additionalProperties=True."""
+        schema = {
+            "type": "object",
+            "properties": {
+                "known": {"type": "string"},
+                "flexible": True,
+            },
+            "required": ["known"],
+            "additionalProperties": True,
+        }
+        result = json_schema_to_type(schema)
+        validator = TypeAdapter(result)
+        obj = validator.validate_python(
+            {"known": "hello", "flexible": [1, 2, 3], "extra": "field"}
+        )
+        assert obj.known == "hello"  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+        assert obj.flexible == [1, 2, 3]  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+
+    def test_issue_3783_boolean_property_schemas(self):
+        """Regression test for GitHub issue #3783."""
+        schema = {
+            "type": "object",
+            "properties": {
+                "ts": {"type": "integer"},
+                "level": True,
+                "app": True,
+                "tag": {"type": ["array", "null"], "items": {"type": "string"}},
+            },
+            "required": ["ts"],
+            "additionalProperties": True,
+        }
+        result = json_schema_to_type(schema)
+        validator = TypeAdapter(result)
+        obj = validator.validate_python({"ts": 123, "level": "info", "app": "myapp"})
+        assert obj.ts == 123  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+        assert obj.level == "info"  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+        assert obj.app == "myapp"  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+
+
+class TestConstrainedTypes:
+    def test_constant(self):
+        validator = TypeAdapter(Literal["x"])
+        schema = validator.json_schema()
+        type_ = json_schema_to_type(schema)
+        assert type_ == Literal["x"]
+        assert TypeAdapter(type_).validate_python("x") == "x"
+        with pytest.raises(ValidationError):
+            TypeAdapter(type_).validate_python("y")
+
+    def test_union_constants(self):
+        validator = TypeAdapter(Literal["x"] | Literal["y"])
+        schema = validator.json_schema()
+        type_ = json_schema_to_type(schema)
+        assert type_ == Literal["x"] | Literal["y"]
+        assert TypeAdapter(type_).validate_python("x") == "x"
+        assert TypeAdapter(type_).validate_python("y") == "y"
+        with pytest.raises(ValidationError):
+            TypeAdapter(type_).validate_python("z")
+
+    def test_enum_str(self):
+        class MyEnum(Enum):
+            X = "x"
+            Y = "y"
+
+        validator = TypeAdapter(MyEnum)
+        schema = validator.json_schema()
+        type_ = json_schema_to_type(schema)
+        assert type_ == Literal["x", "y"]
+        assert TypeAdapter(type_).validate_python("x") == "x"
+        assert TypeAdapter(type_).validate_python("y") == "y"
+        with pytest.raises(ValidationError):
+            TypeAdapter(type_).validate_python("z")
+
+    def test_enum_int(self):
+        class MyEnum(Enum):
+            X = 1
+            Y = 2
+
+        validator = TypeAdapter(MyEnum)
+        schema = validator.json_schema()
+        type_ = json_schema_to_type(schema)
+        assert type_ == Literal[1, 2]
+        assert TypeAdapter(type_).validate_python(1) == 1
+        assert TypeAdapter(type_).validate_python(2) == 2
+        with pytest.raises(ValidationError):
+            TypeAdapter(type_).validate_python(3)
+
+    def test_choice(self):
+        validator = TypeAdapter(Literal["x", "y"])
+        schema = validator.json_schema()
+        type_ = json_schema_to_type(schema)
+        assert type_ == Literal["x", "y"]
+        assert TypeAdapter(type_).validate_python("x") == "x"
+        assert TypeAdapter(type_).validate_python("y") == "y"
+        with pytest.raises(ValidationError):
+            TypeAdapter(type_).validate_python("z")
+
+
+class TestCrashPrevention:
+    """Schemas that previously caused crashes should now be handled gracefully."""
+
+    def test_boolean_schema_true(self):
+        """Boolean schema True should return Any (JSON Schema draft-06+)."""
+        assert json_schema_to_type(True) is Any
+
+    def test_boolean_schema_false(self):
+        """Boolean schema False should return an unsatisfiable type."""
+        result = json_schema_to_type(False)
+        with pytest.raises(ValidationError):
+            TypeAdapter(result).validate_python("anything")
+
+    def test_python_keyword_property_names(self):
+        """Properties named after Python keywords should not crash."""
+        schema = {
+            "type": "object",
+            "properties": {
+                "class": {"type": "string"},
+                "return": {"type": "integer"},
+                "import": {"type": "boolean"},
+            },
+            "required": ["class"],
+        }
+        T = json_schema_to_type(schema)
+        ta = TypeAdapter(T)
+        result = ta.validate_python({"class": "A", "return": 1, "import": True})
+        assert result.class_ == "A"  # ty:ignore[unresolved-attribute]
+
+    def test_empty_enum(self):
+        """Empty enum means no value is valid — should reject like a false schema."""
+        schema = {
+            "type": "object",
+            "properties": {"status": {"enum": []}},
+            "required": ["status"],
+        }
+        T = json_schema_to_type(schema)
+        ta = TypeAdapter(T)
+        with pytest.raises(ValidationError):
+            ta.validate_python({"status": "anything"})
+
+    def test_sanitized_name_collision(self):
+        """Properties that collide after sanitization get deduplicated."""
+        schema = {
+            "type": "object",
+            "properties": {
+                "foo-bar": {"type": "string"},
+                "foo_bar": {"type": "string"},
+            },
+        }
+        T = json_schema_to_type(schema)
+        field_names = [f.name for f in dataclasses.fields(T)]
+        assert len(field_names) == 2
+        assert len(set(field_names)) == 2
+
+    def test_empty_property_name(self):
+        """Empty and whitespace-only property names should not crash."""
+        schema = {
+            "type": "object",
+            "properties": {
+                "": {"type": "string"},
+                " ": {"type": "integer"},
+            },
+        }
+        T = json_schema_to_type(schema)
+        field_names = [f.name for f in dataclasses.fields(T)]
+        assert len(field_names) == 2
+        assert len(set(field_names)) == 2
+
+
+class TestUnsupportedPatternFallback:
+    """Patterns that Pydantic's Rust regex engine cannot compile are dropped
+    gracefully: a warning is emitted, the pattern is preserved in
+    json_schema_extra, and the field still validates as str."""
+
+    def test_lookahead_pattern_falls_back_to_str(self):
+        """Lookahead patterns (unsupported by Rust regex) degrade to plain str."""
+        schema = {"type": "string", "pattern": "^(?!aws:).+"}
+        with pytest.warns(UserWarning, match="not supported by Pydantic"):
+            T = json_schema_to_type(schema)
+        ta = TypeAdapter(T)
+        ta.validate_python("hello")
+        ta.validate_python("aws:forbidden")
+
+    def test_unsupported_pattern_preserved_in_schema_extra(self):
+        """The original pattern is preserved via json_schema_extra."""
+        schema = {"type": "string", "pattern": "^(?!aws:).+"}
+        with pytest.warns(UserWarning):
+            T = json_schema_to_type(schema)
+        json_schema = TypeAdapter(T).json_schema()
+        assert json_schema.get("x-unsupported-pattern") == "^(?!aws:).+"
+
+    def test_length_constraints_kept_when_pattern_dropped(self):
+        """minLength/maxLength are still enforced after pattern fallback."""
+        schema = {
+            "type": "string",
+            "minLength": 3,
+            "maxLength": 10,
+            "pattern": "(?!x).+",
+        }
+        with pytest.warns(UserWarning):
+            T = json_schema_to_type(schema)
+        ta = TypeAdapter(T)
+        ta.validate_python("abc")
+        with pytest.raises(ValidationError):
+            ta.validate_python("ab")
+        with pytest.raises(ValidationError):
+            ta.validate_python("a" * 11)
+
+    def test_supported_pattern_still_enforced(self):
+        """Valid patterns are not affected by the fallback logic."""
+        schema = {"type": "string", "pattern": "^[a-z]+$"}
+        T = json_schema_to_type(schema)
+        ta = TypeAdapter(T)
+        ta.validate_python("hello")
+        with pytest.raises(ValidationError):
+            ta.validate_python("HELLO")
+
+    def test_unicode_property_pattern_falls_back(self):
+        """Unicode \\p{...} patterns (unsupported by Rust regex) degrade gracefully."""
+        schema = {"type": "string", "pattern": r"[\p{Graph}\x20]*"}
+        with pytest.warns(UserWarning, match="not supported by Pydantic"):
+            T = json_schema_to_type(schema)
+        ta = TypeAdapter(T)
+        ta.validate_python("anything")
+
+    def test_object_with_unsupported_pattern_field(self):
+        """An object schema containing a field with an unsupported pattern
+        should not crash TypeAdapter construction."""
+        schema = {
+            "type": "object",
+            "properties": {
+                "tag_key": {"type": "string", "pattern": "^(?!aws:)[a-zA-Z]+$"},
+                "value": {"type": "string"},
+            },
+            "required": ["tag_key", "value"],
+        }
+        with pytest.warns(UserWarning):
+            T = json_schema_to_type(schema)
+        ta = TypeAdapter(T)
+        result = ta.validate_python({"tag_key": "Name", "value": "test"})
+        assert result.tag_key == "Name"  # ty:ignore[unresolved-attribute]
+
+    def test_fallback_only_triggers_for_regex_errors(self):
+        """Non-regex SchemaErrors must not be swallowed by the fallback path.
+
+        Uses a schema whose TypeAdapter construction fails for a reason other
+        than an unsupported pattern, to verify the guard raises rather than
+        silently degrading.  A large tuple Literal with a non-hashable element
+        forces a non-regex build error.
+        """
+
+        # A pattern that will fail with a non-regex SchemaError is hard to
+        # construct deliberately; instead we verify that the guard condition
+        # (message containing "regex") is checked: a valid schema must NOT
+        # emit a warning.
+        schema = {"type": "string", "pattern": "^[a-z]+$"}
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", UserWarning)
+            T = json_schema_to_type(schema)  # must not warn
+        TypeAdapter(T).validate_python("hello")
diff --git a/tests/utilities/json_schema_type/test_real_world_schemas.py b/tests/utilities/json_schema_type/test_real_world_schemas.py
new file mode 100644
index 0000000..9d2b975
--- /dev/null
+++ b/tests/utilities/json_schema_type/test_real_world_schemas.py
@@ -0,0 +1,423 @@
+"""Crash-test json_schema_to_type against real-world OpenAPI schemas.
+
+Uses the APIs.guru openapi-directory (https://github.com/APIs-guru/openapi-directory)
+pinned to a specific commit for reproducibility.
+
+Parametrized by API provider (~700 providers, one test each) so pytest
+shows progress and can identify which provider caused a hang.
+
+Marked as an integration test — skipped by default, run with:
+
+    uv run pytest tests/utilities/json_schema_type/test_real_world_schemas.py -m integration -n auto --timeout-method=thread -q
+
+On a 16-core machine this takes ~3-5 minutes. The CI workflow
+(.github/workflows/run-schema-crash-test.yml) runs it on push/PR when
+relevant source files change.
+
+## Aggregate baselines
+
+After each run, conftest.py compares aggregate crash counts against baseline
+caps in ``conftest.py``.  Ratchet those caps DOWN whenever a cluster of errors
+is fixed — never up.  See ``conftest.py`` for the current caps and comments
+on what was fixed.
+
+## Collecting and analysing failures
+
+Set ``DUMP_SCHEMA_FAILURES`` to a directory to write per-failure JSONL records:
+
+    RUN_REAL_WORLD_SCHEMA_TEST=1 \\
+    OPENAPI_DIRECTORY_PATH=/tmp/openapi-directory \\
+    DUMP_SCHEMA_FAILURES=/tmp/schema_failures \\
+    uv run pytest tests/utilities/json_schema_type/test_real_world_schemas.py \\
+        -m integration -n auto --timeout-method=thread -q
+
+Then cluster the results to find root causes:
+
+    python tests/utilities/json_schema_type/cluster_failures.py
+
+See ``cluster_failures.py`` for the full fix workflow (reproduce → unit test →
+fix → ratchet baseline → commit).
+
+## Cloning the corpus locally
+
+The test auto-clones when ``RUN_REAL_WORLD_SCHEMA_TEST=1``.  To pre-clone
+manually (~800 MB):
+
+    git clone --depth 1 https://github.com/APIs-guru/openapi-directory.git /tmp/openapi-directory
+
+Then point at it:
+
+    OPENAPI_DIRECTORY_PATH=/tmp/openapi-directory \\
+    RUN_REAL_WORLD_SCHEMA_TEST=1 \\
+    uv run pytest ...
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import signal
+import subprocess
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+import pytest
+import yaml
+from pydantic import TypeAdapter
+from yaml import CSafeLoader  # ty: ignore[possibly-missing-import]
+
+from fastmcp.utilities.json_schema_type import json_schema_to_type
+
+# Pin to a specific commit for reproducibility
+OPENAPI_DIRECTORY_REPO = "https://github.com/APIs-guru/openapi-directory.git"
+OPENAPI_DIRECTORY_COMMIT = "f7207cf0a5c56081d275ebae4cf615249323385d"
+CLONE_DIR = Path(os.environ.get("OPENAPI_DIRECTORY_PATH", "/tmp/openapi-directory"))
+
+# Per-schema timeout (seconds) to catch infinite loops
+SCHEMA_TIMEOUT = 5
+
+# In CI (RUN_REAL_WORLD_SCHEMA_TEST=1), _ensure_repo clones automatically.
+# Locally, skip unless the repo is already cloned to avoid a surprise 200MB download.
+_run_in_ci = os.environ.get("RUN_REAL_WORLD_SCHEMA_TEST") == "1"
+_skip_locally = not _run_in_ci and not CLONE_DIR.exists()
+
+pytestmark = [
+    pytest.mark.integration,
+    pytest.mark.skipif(
+        _skip_locally,
+        reason=(
+            f"openapi-directory not found at {CLONE_DIR}. "
+            f"Set RUN_REAL_WORLD_SCHEMA_TEST=1 to auto-clone, or: "
+            f"git clone --depth 1 {OPENAPI_DIRECTORY_REPO} {CLONE_DIR}"
+        ),
+    ),
+]
+
+
+class _SchemaTimeout(Exception):
+    pass
+
+
+def _alarm_handler(signum: object, frame: object) -> None:
+    raise _SchemaTimeout()
+
+
+# ── Helpers ──────────────────────────────────────────────────────────
+
+
+def _is_openapi_directory_clone(path: Path) -> bool:
+    """Check whether *path* looks like a clone of the openapi-directory repo."""
+    if not (path / ".git").is_dir():
+        return False
+    result = subprocess.run(
+        ["git", "-C", str(path), "remote", "get-url", "origin"],
+        capture_output=True,
+        text=True,
+    )
+    return "openapi-directory" in result.stdout
+
+
+def _ensure_repo() -> Path:
+    """Clone the openapi-directory repo if not already present at the pinned commit.
+
+    Safe under pytest-xdist: a file lock serializes the rmtree/reclone path so
+    concurrent workers don't race on the shared CLONE_DIR.
+    """
+    # Fast-path check without a lock — if HEAD already matches, skip locking entirely.
+    if _head_matches_pinned():
+        return CLONE_DIR
+
+    # fcntl is POSIX-only; imported here (not at module level) so this file
+    # collects cleanly on Windows where the integration test is skipped.
+    import fcntl
+
+    lock_path = CLONE_DIR.with_suffix(".lock")
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(lock_path, "w") as lf:
+        fcntl.flock(lf.fileno(), fcntl.LOCK_EX)
+        try:
+            # Re-check under the lock in case another worker already fixed it.
+            if _head_matches_pinned():
+                return CLONE_DIR
+
+            if CLONE_DIR.exists():
+                if not _is_openapi_directory_clone(CLONE_DIR):
+                    raise RuntimeError(
+                        f"{CLONE_DIR} exists but is not an openapi-directory clone. "
+                        f"Remove it manually or set OPENAPI_DIRECTORY_PATH to a different path."
+                    )
+                shutil.rmtree(CLONE_DIR)
+
+            subprocess.run(
+                [
+                    "git",
+                    "clone",
+                    "--depth",
+                    "1",
+                    OPENAPI_DIRECTORY_REPO,
+                    str(CLONE_DIR),
+                ],
+                check=True,
+                capture_output=True,
+            )
+            subprocess.run(
+                [
+                    "git",
+                    "-C",
+                    str(CLONE_DIR),
+                    "fetch",
+                    "--depth",
+                    "1",
+                    "origin",
+                    OPENAPI_DIRECTORY_COMMIT,
+                ],
+                check=True,
+                capture_output=True,
+            )
+            subprocess.run(
+                ["git", "-C", str(CLONE_DIR), "checkout", OPENAPI_DIRECTORY_COMMIT],
+                check=True,
+                capture_output=True,
+            )
+            return CLONE_DIR
+        finally:
+            fcntl.flock(lf.fileno(), fcntl.LOCK_UN)
+
+
+def _head_matches_pinned() -> bool:
+    """Return True when CLONE_DIR is already checked out at the pinned commit."""
+    if not (CLONE_DIR.exists() and (CLONE_DIR / ".git").is_dir()):
+        return False
+    result = subprocess.run(
+        ["git", "-C", str(CLONE_DIR), "rev-parse", "HEAD"],
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout.strip() == OPENAPI_DIRECTORY_COMMIT
+
+
+def _load_spec(spec_file: Path) -> dict | None:
+    """Load and return a spec dict, or None on failure."""
+    try:
+        if spec_file.suffix == ".yaml":
+            spec = yaml.load(spec_file.read_text(), Loader=CSafeLoader)
+        else:
+            spec = json.loads(spec_file.read_text())
+        return spec if isinstance(spec, dict) else None
+    except Exception:
+        return None
+
+
+def _extract_schemas(spec: dict) -> dict:
+    """Pull all schema definitions out of an OpenAPI spec."""
+    schemas: dict = {}
+    if "definitions" in spec:
+        schemas.update(spec["definitions"])
+    components = spec.get("components")
+    if isinstance(components, dict):
+        schemas.update(components.get("schemas", {}))
+    return {k: v for k, v in schemas.items() if isinstance(v, dict)}
+
+
+# ── Per-provider collection ──────────────────────────────────────────
+
+
+def _collect_providers() -> list[str]:
+    """List API provider directories (e.g. 'github.com', 'amazonaws.com')."""
+    apis_dir = CLONE_DIR / "APIs"
+    if not apis_dir.is_dir():
+        return []
+    return sorted(d.name for d in apis_dir.iterdir() if d.is_dir())
+
+
+def _spec_files_for_provider(provider: str) -> list[Path]:
+    """Find all spec files for a given provider."""
+    provider_dir = CLONE_DIR / "APIs" / provider
+    files: list[Path] = []
+    for name in ("openapi.yaml", "swagger.yaml", "openapi.json", "swagger.json"):
+        files.extend(provider_dir.rglob(name))
+    return sorted(files)
+
+
+# ── Test logic ───────────────────────────────────────────────────────
+
+
+@dataclass
+class ProviderResult:
+    """Crash counts for one API provider."""
+
+    schemas: int = 0
+    type_errors: int = 0
+    schema_errors: int = 0
+    timeouts: int = 0
+    other_errors: int = 0
+
+
+def _test_provider(provider: str) -> ProviderResult:
+    """Run json_schema_to_type on every schema for one provider."""
+    # Clear the module-level type cache between providers to avoid
+    # unbounded memory growth across 232K schemas.
+    from fastmcp.utilities.json_schema_type import _classes
+
+    _classes.clear()
+
+    result = ProviderResult()
+    use_alarm = hasattr(signal, "SIGALRM")
+
+    # Optional per-failure dump: when DUMP_SCHEMA_FAILURES is set to a directory,
+    # write one JSONL record per failure so we can cluster them later.
+    dump_dir_env = os.environ.get("DUMP_SCHEMA_FAILURES")
+    dump_path: Path | None = None
+    if dump_dir_env:
+        dump_path = Path(dump_dir_env) / f"{provider}.jsonl"
+        dump_path.parent.mkdir(parents=True, exist_ok=True)
+        # Truncate any prior content from a previous run of this provider.
+        dump_path.write_text("")
+
+    def _record_failure(
+        bucket: str, schema_name: str, schema_obj: dict, exc: BaseException
+    ) -> None:
+        if dump_path is None:
+            return
+        # Cap the schema snippet so huge recursive specs don't blow up disk.
+        try:
+            schema_repr = json.dumps(schema_obj, default=str)[:2000]
+        except Exception:
+            schema_repr = "<unserializable>"
+        record = {
+            "provider": provider,
+            "name": schema_name,
+            "bucket": bucket,
+            "error_type": type(exc).__name__,
+            "error_msg": str(exc)[:500],
+            "schema": schema_repr,
+        }
+        with dump_path.open("a") as fh:
+            fh.write(json.dumps(record) + "\n")
+
+    for spec_file in _spec_files_for_provider(provider):
+        spec = _load_spec(spec_file)
+        if spec is None:
+            continue
+        for _name, schema in _extract_schemas(spec).items():
+            # JSON-round-trip to simulate production: schemas arrive over
+            # MCP as JSON, so YAML-specific types (datetime, date) should
+            # not be present.  This avoids counting YAML-parser artifacts
+            # as json_schema_to_type bugs.
+            try:
+                schema = json.loads(json.dumps(schema, default=str))
+            except (TypeError, ValueError):
+                continue
+
+            result.schemas += 1
+
+            old_handler = signal.SIG_DFL
+            if use_alarm:
+                old_handler = signal.signal(signal.SIGALRM, _alarm_handler)
+                signal.alarm(SCHEMA_TIMEOUT)
+            try:
+                T = json_schema_to_type(schema)
+                TypeAdapter(T)
+            except _SchemaTimeout as e:
+                if use_alarm:
+                    signal.alarm(0)
+                result.timeouts += 1
+                _record_failure("timeouts", _name, schema, e)
+            except TypeError as e:
+                if use_alarm:
+                    signal.alarm(0)
+                result.type_errors += 1
+                _record_failure("type_errors", _name, schema, e)
+            except Exception as e:
+                if use_alarm:
+                    signal.alarm(0)
+                err_type = type(e).__name__
+                if "SchemaError" in err_type or "schema" in str(e).lower()[:50]:
+                    result.schema_errors += 1
+                    _record_failure("schema_errors", _name, schema, e)
+                else:
+                    result.other_errors += 1
+                    _record_failure("other_errors", _name, schema, e)
+            finally:
+                if use_alarm:
+                    signal.alarm(0)
+                    signal.signal(signal.SIGALRM, old_handler)
+
+    return result
+
+
+# ── Per-provider test (parametrized) ─────────────────────────────────
+#
+# ~700 test items — one per API provider.
+# Profiled on a fast MacBook (p50=0.06s, p99=8s); CI is ~3x slower.
+# Tiered timeouts so small providers fail fast while large ones get room.
+#
+# Local times → CI estimate → timeout bucket:
+#   azure/aws/github/msft/google  80-137s → 240-410s → 600s
+#   adyen                         21s     → 63s      → 120s
+#   loket/mailchimp/apisetu/k8s   6-10s   → 18-30s   → 120s
+#   everything else (p99)         <8s     → <24s     → 60s
+
+_TIER1_PROVIDERS = frozenset(
+    {
+        "azure.com",
+        "amazonaws.com",
+        "googleapis.com",
+        "github.com",
+        "microsoft.com",
+    }
+)
+
+_TIER2_PROVIDERS = frozenset(
+    {
+        "adyen.com",
+        "loket.nl",
+        "mailchimp.com",
+        "apisetu.gov.in",
+        "kubernetes.io",
+        "twilio.com",
+        "sportsdata.io",
+        "vtex.local",
+        "amadeus.com",
+    }
+)
+
+
+def _providers_with_timeouts() -> list:  # list of pytest.param
+    """Build parametrize list with per-provider timeouts."""
+    params = []
+    for p in _collect_providers():
+        if p in _TIER1_PROVIDERS:
+            t = 600
+        elif p in _TIER2_PROVIDERS:
+            t = 120
+        else:
+            t = 60
+        params.append(
+            pytest.param(p, id=p, marks=pytest.mark.timeout(t, method="thread"))
+        )
+    return params
+
+
+# Per-provider results are persisted to disk so they survive across xdist
+# workers (each worker runs in its own process). Aggregation and baseline
+# assertions happen in the pytest_sessionfinish hook in conftest.py.
+# This path is duplicated in conftest.py by design — tests shouldn't import
+# from conftest, which isn't a reliably importable module.
+_RESULTS_DIR = Path(
+    os.environ.get("SCHEMA_CRASH_RESULTS_DIR", "/tmp/schema_crash_results")
+)
+
+
+@pytest.mark.integration
+@pytest.mark.parametrize("provider", _providers_with_timeouts())
+def test_provider_schemas(provider: str):
+    """json_schema_to_type should not infinite-loop on schemas from this provider."""
+    _ensure_repo()
+    _RESULTS_DIR.mkdir(parents=True, exist_ok=True)
+    result = _test_provider(provider)
+    (_RESULTS_DIR / f"{provider}.json").write_text(json.dumps(asdict(result)))
+    assert result.timeouts == 0, (
+        f"{provider}: {result.timeouts} schema(s) timed out (possible infinite loop)"
+    )
diff --git a/tests/utilities/json_schema_type/test_unions.py b/tests/utilities/json_schema_type/test_unions.py
new file mode 100644
index 0000000..7a8c894
--- /dev/null
+++ b/tests/utilities/json_schema_type/test_unions.py
@@ -0,0 +1,128 @@
+"""Tests for union types in JSON schema conversion."""
+
+from dataclasses import Field
+
+import pytest
+from pydantic import TypeAdapter, ValidationError
+
+from fastmcp.utilities.json_schema_type import (
+    json_schema_to_type,
+)
+
+
+def get_dataclass_field(type: type, field_name: str) -> Field:
+    return type.__dataclass_fields__[field_name]  # ty: ignore[unresolved-attribute]
+
+
+class TestUnionTypes:
+    """Test suite for testing union type behaviors."""
+
+    @pytest.fixture
+    def heterogeneous_union(self):
+        return json_schema_to_type({"type": ["string", "number", "boolean", "null"]})
+
+    @pytest.fixture
+    def union_with_constraints(self):
+        return json_schema_to_type(
+            {"type": ["string", "number"], "minLength": 3, "minimum": 0}
+        )
+
+    @pytest.fixture
+    def union_with_formats(self):
+        return json_schema_to_type({"type": ["string", "null"], "format": "email"})
+
+    @pytest.fixture
+    def nested_union_array(self):
+        return json_schema_to_type(
+            {"type": "array", "items": {"type": ["string", "number"]}}
+        )
+
+    @pytest.fixture
+    def nested_union_object(self):
+        return json_schema_to_type(
+            {
+                "type": "object",
+                "properties": {
+                    "id": {"type": ["string", "integer"]},
+                    "data": {
+                        "type": ["object", "null"],
+                        "properties": {"value": {"type": "string"}},
+                    },
+                },
+            }
+        )
+
+    def test_heterogeneous_accepts_string(self, heterogeneous_union):
+        validator = TypeAdapter(heterogeneous_union)
+        assert validator.validate_python("test") == "test"
+
+    def test_heterogeneous_accepts_number(self, heterogeneous_union):
+        validator = TypeAdapter(heterogeneous_union)
+        assert validator.validate_python(123.45) == 123.45
+
+    def test_heterogeneous_accepts_boolean(self, heterogeneous_union):
+        validator = TypeAdapter(heterogeneous_union)
+        assert validator.validate_python(True) is True
+
+    def test_heterogeneous_accepts_null(self, heterogeneous_union):
+        validator = TypeAdapter(heterogeneous_union)
+        assert validator.validate_python(None) is None
+
+    def test_heterogeneous_rejects_array(self, heterogeneous_union):
+        validator = TypeAdapter(heterogeneous_union)
+        with pytest.raises(ValidationError):
+            validator.validate_python([])
+
+    def test_constrained_string_valid(self, union_with_constraints):
+        validator = TypeAdapter(union_with_constraints)
+        assert validator.validate_python("test") == "test"
+
+    def test_constrained_string_invalid(self, union_with_constraints):
+        validator = TypeAdapter(union_with_constraints)
+        with pytest.raises(ValidationError):
+            validator.validate_python("ab")
+
+    def test_constrained_number_valid(self, union_with_constraints):
+        validator = TypeAdapter(union_with_constraints)
+        assert validator.validate_python(10) == 10
+
+    def test_constrained_number_invalid(self, union_with_constraints):
+        validator = TypeAdapter(union_with_constraints)
+        with pytest.raises(ValidationError):
+            validator.validate_python(-1)
+
+    def test_format_valid_email(self, union_with_formats):
+        validator = TypeAdapter(union_with_formats)
+        result = validator.validate_python("test@example.com")
+        assert isinstance(result, str)
+
+    def test_format_valid_null(self, union_with_formats):
+        validator = TypeAdapter(union_with_formats)
+        assert validator.validate_python(None) is None
+
+    def test_format_invalid_email(self, union_with_formats):
+        validator = TypeAdapter(union_with_formats)
+        with pytest.raises(ValidationError):
+            validator.validate_python("not-an-email")
+
+    def test_nested_array_mixed_types(self, nested_union_array):
+        validator = TypeAdapter(nested_union_array)
+        result = validator.validate_python(["test", 123, "abc"])
+        assert result == ["test", 123, "abc"]
+
+    def test_nested_array_rejects_invalid(self, nested_union_array):
+        validator = TypeAdapter(nested_union_array)
+        with pytest.raises(ValidationError):
+            validator.validate_python(["test", ["not", "allowed"], "abc"])
+
+    def test_nested_object_string_id(self, nested_union_object):
+        validator = TypeAdapter(nested_union_object)
+        result = validator.validate_python({"id": "abc123", "data": {"value": "test"}})
+        assert result.id == "abc123"
+        assert result.data.value == "test"
+
+    def test_nested_object_integer_id(self, nested_union_object):
+        validator = TypeAdapter(nested_union_object)
+        result = validator.validate_python({"id": 123, "data": None})
+        assert result.id == 123
+        assert result.data is None
diff --git a/tests/utilities/openapi/__init__.py b/tests/utilities/openapi/__init__.py
new file mode 100644
index 0000000..65fb50b
--- /dev/null
+++ b/tests/utilities/openapi/__init__.py
@@ -0,0 +1 @@
+"""Tests for openapi_new utilities."""
diff --git a/tests/utilities/openapi/conftest.py b/tests/utilities/openapi/conftest.py
new file mode 100644
index 0000000..b7158dd
--- /dev/null
+++ b/tests/utilities/openapi/conftest.py
@@ -0,0 +1,222 @@
+"""Shared fixtures for openapi_new utilities tests."""
+
+import pytest
+
+
+@pytest.fixture
+def basic_openapi_30_spec():
+    """Basic OpenAPI 3.0 spec for testing."""
+    return {
+        "openapi": "3.0.0",
+        "info": {"title": "Test API", "version": "1.0.0"},
+        "servers": [{"url": "https://api.example.com"}],
+        "paths": {
+            "/users/{id}": {
+                "get": {
+                    "operationId": "get_user",
+                    "summary": "Get user by ID",
+                    "parameters": [
+                        {
+                            "name": "id",
+                            "in": "path",
+                            "required": True,
+                            "schema": {"type": "integer"},
+                        }
+                    ],
+                    "responses": {
+                        "200": {
+                            "description": "User retrieved successfully",
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "properties": {
+                                            "id": {"type": "integer"},
+                                            "name": {"type": "string"},
+                                        },
+                                    }
+                                }
+                            },
+                        }
+                    },
+                }
+            }
+        },
+    }
+
+
+@pytest.fixture
+def basic_openapi_31_spec():
+    """Basic OpenAPI 3.1 spec for testing."""
+    return {
+        "openapi": "3.1.0",
+        "info": {"title": "Test API", "version": "1.0.0"},
+        "servers": [{"url": "https://api.example.com"}],
+        "paths": {
+            "/users/{id}": {
+                "get": {
+                    "operationId": "get_user",
+                    "summary": "Get user by ID",
+                    "parameters": [
+                        {
+                            "name": "id",
+                            "in": "path",
+                            "required": True,
+                            "schema": {"type": "integer"},
+                        }
+                    ],
+                    "responses": {
+                        "200": {
+                            "description": "User retrieved successfully",
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "properties": {
+                                            "id": {"type": "integer"},
+                                            "name": {"type": "string"},
+                                        },
+                                    }
+                                }
+                            },
+                        }
+                    },
+                }
+            }
+        },
+    }
+
+
+@pytest.fixture
+def collision_spec():
+    """OpenAPI spec with parameter name collisions."""
+    return {
+        "openapi": "3.0.0",
+        "info": {"title": "Collision Test API", "version": "1.0.0"},
+        "paths": {
+            "/users/{id}": {
+                "put": {
+                    "operationId": "update_user",
+                    "parameters": [
+                        {
+                            "name": "id",
+                            "in": "path",
+                            "required": True,
+                            "schema": {"type": "integer"},
+                        }
+                    ],
+                    "requestBody": {
+                        "required": True,
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "id": {"type": "integer"},
+                                        "name": {"type": "string"},
+                                    },
+                                    "required": ["name"],
+                                }
+                            }
+                        },
+                    },
+                    "responses": {"200": {"description": "Updated"}},
+                }
+            }
+        },
+    }
+
+
+@pytest.fixture
+def deepobject_spec():
+    """OpenAPI spec with deepObject parameter style."""
+    return {
+        "openapi": "3.0.0",
+        "info": {"title": "DeepObject Test API", "version": "1.0.0"},
+        "paths": {
+            "/search": {
+                "get": {
+                    "operationId": "search",
+                    "parameters": [
+                        {
+                            "name": "filter",
+                            "in": "query",
+                            "required": False,
+                            "style": "deepObject",
+                            "explode": True,
+                            "schema": {
+                                "type": "object",
+                                "properties": {
+                                    "category": {"type": "string"},
+                                    "price": {
+                                        "type": "object",
+                                        "properties": {
+                                            "min": {"type": "number"},
+                                            "max": {"type": "number"},
+                                        },
+                                    },
+                                },
+                            },
+                        }
+                    ],
+                    "responses": {"200": {"description": "Search results"}},
+                }
+            }
+        },
+    }
+
+
+@pytest.fixture
+def complex_spec():
+    """Complex OpenAPI spec with multiple parameter types."""
+    return {
+        "openapi": "3.0.0",
+        "info": {"title": "Complex API", "version": "1.0.0"},
+        "paths": {
+            "/items/{id}": {
+                "patch": {
+                    "operationId": "update_item",
+                    "parameters": [
+                        {
+                            "name": "id",
+                            "in": "path",
+                            "required": True,
+                            "schema": {"type": "string"},
+                        },
+                        {
+                            "name": "version",
+                            "in": "query",
+                            "required": False,
+                            "schema": {"type": "integer", "default": 1},
+                        },
+                        {
+                            "name": "X-Client-Version",
+                            "in": "header",
+                            "required": False,
+                            "schema": {"type": "string"},
+                        },
+                    ],
+                    "requestBody": {
+                        "required": True,
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "title": {"type": "string"},
+                                        "description": {"type": "string"},
+                                        "tags": {
+                                            "type": "array",
+                                            "items": {"type": "string"},
+                                        },
+                                    },
+                                    "required": ["title"],
+                                }
+                            }
+                        },
+                    },
+                    "responses": {"200": {"description": "Item updated"}},
+                }
+            }
+        },
+    }
diff --git a/tests/utilities/openapi/test_allof_requestbody.py b/tests/utilities/openapi/test_allof_requestbody.py
new file mode 100644
index 0000000..65e60ef
--- /dev/null
+++ b/tests/utilities/openapi/test_allof_requestbody.py
@@ -0,0 +1,227 @@
+"""Tests for allOf handling at requestBody top level."""
+
+from fastmcp.utilities.openapi.models import (
+    HTTPRoute,
+    RequestBodyInfo,
+)
+from fastmcp.utilities.openapi.schemas import _combine_schemas
+
+
+def test_allof_at_requestbody_top_level():
+    """Test that allOf schemas at requestBody top level are properly merged."""
+
+    # Create a route with allOf at the requestBody top level
+    route = HTTPRoute(
+        path="/test",
+        method="POST",
+        operation_id="testOperation",
+        parameters=[],
+        request_body=RequestBodyInfo(
+            required=True,
+            content_schema={
+                "application/json": {
+                    "allOf": [
+                        {
+                            "type": "object",
+                            "properties": {
+                                "name": {"type": "string"},
+                                "age": {"type": "integer"},
+                            },
+                            "required": ["name"],
+                        },
+                        {
+                            "type": "object",
+                            "properties": {
+                                "email": {"type": "string"},
+                                "phone": {"type": "string"},
+                            },
+                            "required": ["email"],
+                        },
+                    ]
+                }
+            },
+        ),
+        responses={},
+    )
+
+    # Combine schemas - this should merge allOf schemas
+    combined = _combine_schemas(route)
+
+    # Check that all properties from both allOf schemas are present
+    properties = combined.get("properties", {})
+    assert "name" in properties
+    assert "age" in properties
+    assert "email" in properties
+    assert "phone" in properties
+
+    # Check property types
+    assert properties["name"]["type"] == "string"
+    assert properties["age"]["type"] == "integer"
+    assert properties["email"]["type"] == "string"
+    assert properties["phone"]["type"] == "string"
+
+    # Check that required fields are merged correctly
+    required = set(combined.get("required", []))
+    assert "name" in required
+    assert "email" in required
+
+    # allOf should be removed after merging
+    assert "allOf" not in combined
+
+
+def test_allof_with_nested_properties():
+    """Test allOf with nested object properties."""
+
+    route = HTTPRoute(
+        path="/test",
+        method="POST",
+        operation_id="testNested",
+        parameters=[],
+        request_body=RequestBodyInfo(
+            required=True,
+            content_schema={
+                "application/json": {
+                    "allOf": [
+                        {
+                            "type": "object",
+                            "properties": {
+                                "user": {
+                                    "type": "object",
+                                    "properties": {
+                                        "id": {"type": "integer"},
+                                        "name": {"type": "string"},
+                                    },
+                                }
+                            },
+                            "required": ["user"],
+                        },
+                        {
+                            "type": "object",
+                            "properties": {
+                                "metadata": {
+                                    "type": "object",
+                                    "properties": {
+                                        "created": {"type": "string"},
+                                        "updated": {"type": "string"},
+                                    },
+                                }
+                            },
+                        },
+                    ]
+                }
+            },
+        ),
+        responses={},
+    )
+
+    combined = _combine_schemas(route)
+
+    # Check nested properties are preserved
+    properties = combined.get("properties", {})
+    assert "user" in properties
+    assert "metadata" in properties
+
+    # Check nested structure
+    assert properties["user"]["type"] == "object"
+    assert "id" in properties["user"]["properties"]
+    assert "name" in properties["user"]["properties"]
+
+    assert properties["metadata"]["type"] == "object"
+    assert "created" in properties["metadata"]["properties"]
+    assert "updated" in properties["metadata"]["properties"]
+
+    # Check required
+    required = set(combined.get("required", []))
+    assert "user" in required
+    assert "metadata" not in required  # Not in any required array
+
+
+def test_allof_with_overlapping_properties():
+    """Test allOf with overlapping property names (later schemas override)."""
+
+    route = HTTPRoute(
+        path="/test",
+        method="POST",
+        operation_id="testOverlap",
+        parameters=[],
+        request_body=RequestBodyInfo(
+            required=True,
+            content_schema={
+                "application/json": {
+                    "allOf": [
+                        {
+                            "type": "object",
+                            "properties": {
+                                "name": {"type": "string", "minLength": 1},
+                                "age": {"type": "integer"},
+                            },
+                            "required": ["name"],
+                        },
+                        {
+                            "type": "object",
+                            "properties": {
+                                "name": {"type": "string", "maxLength": 50},  # Override
+                                "email": {"type": "string"},
+                            },
+                            "required": ["email"],
+                        },
+                    ]
+                }
+            },
+        ),
+        responses={},
+    )
+
+    combined = _combine_schemas(route)
+
+    properties = combined.get("properties", {})
+
+    # Later schema should win for overlapping properties
+    assert "name" in properties
+    assert properties["name"]["type"] == "string"
+    assert "maxLength" in properties["name"]  # From second schema
+    assert properties["name"]["maxLength"] == 50
+
+    # Check other properties
+    assert "age" in properties
+    assert "email" in properties
+
+    # Both name and email should be required
+    required = set(combined.get("required", []))
+    assert "name" in required
+    assert "email" in required
+
+
+def test_no_allof_passthrough():
+    """Test that schemas without allOf pass through unchanged."""
+
+    route = HTTPRoute(
+        path="/test",
+        method="POST",
+        operation_id="testNoAllOf",
+        parameters=[],
+        request_body=RequestBodyInfo(
+            required=True,
+            content_schema={
+                "application/json": {
+                    "type": "object",
+                    "properties": {"simple": {"type": "string"}},
+                    "required": ["simple"],
+                }
+            },
+        ),
+        responses={},
+    )
+
+    combined = _combine_schemas(route)
+
+    # Should pass through unchanged
+    properties = combined.get("properties", {})
+    assert "simple" in properties
+    assert properties["simple"]["type"] == "string"
+
+    required = set(combined.get("required", []))
+    assert "simple" in required
+
+    # No allOf in original or result
+    assert "allOf" not in combined
diff --git a/tests/utilities/openapi/test_circular_references.py b/tests/utilities/openapi/test_circular_references.py
new file mode 100644
index 0000000..ed08d5e
--- /dev/null
+++ b/tests/utilities/openapi/test_circular_references.py
@@ -0,0 +1,260 @@
+"""Tests for circular and self-referential schema serialization (Issues #1016, #1206, #3242)."""
+
+import httpx
+
+from fastmcp import FastMCP
+from fastmcp.utilities.openapi.models import (
+    ResponseInfo,
+)
+from fastmcp.utilities.openapi.schemas import (
+    _replace_ref_with_defs,
+    extract_output_schema_from_responses,
+)
+
+
+class TestCircularReferencesSerialization:
+    """Tests for circular/self-referential schemas surviving MCP serialization.
+
+    Issues: #1016, #1206, #3242
+
+    The crash occurs when Pydantic's model_dump() encounters the same Python
+    dict object at multiple positions in the serialization tree. This happens
+    because _replace_ref_with_defs mutates shared list objects (anyOf/allOf/oneOf)
+    in place via shallow copy, causing different tools to share internal dict
+    references.
+    """
+
+    def test_replace_ref_with_defs_does_not_mutate_input(self):
+        """_replace_ref_with_defs must not mutate its input dict's lists."""
+        schema = {
+            "oneOf": [
+                {"$ref": "#/components/schemas/Cat"},
+                {"$ref": "#/components/schemas/Dog"},
+            ]
+        }
+        original_list = schema["oneOf"]
+        original_items = list(original_list)  # snapshot
+
+        _replace_ref_with_defs(schema)
+
+        # The original list object must not have been mutated
+        assert original_list is schema["oneOf"]
+        assert original_list == original_items
+
+    def test_replace_ref_with_defs_produces_independent_results(self):
+        """Calling _replace_ref_with_defs twice on the same input must produce
+        independent dict trees with no shared mutable objects."""
+        schema = {
+            "type": "object",
+            "properties": {
+                "pet": {
+                    "oneOf": [
+                        {"$ref": "#/components/schemas/Cat"},
+                        {"$ref": "#/components/schemas/Dog"},
+                    ]
+                }
+            },
+        }
+
+        result1 = _replace_ref_with_defs(schema)
+        result2 = _replace_ref_with_defs(schema)
+
+        # The oneOf lists should be different objects
+        list1 = result1["properties"]["pet"]["oneOf"]
+        list2 = result2["properties"]["pet"]["oneOf"]
+        assert list1 is not list2
+
+        # Items within the lists should also be independent
+        assert list1[0] is not list2[0]
+
+    def test_circular_output_schema_serialization(self):
+        """Output schemas with self-referential types must survive model_dump().
+
+        This is the exact crash from issue #3242: Pydantic raises
+        ValueError('Circular reference detected (id repeated)') when
+        serializing MCP Tool objects whose schemas share Python dict references.
+        """
+        responses = {
+            "200": ResponseInfo(
+                description="A tree node",
+                content_schema={
+                    "application/json": {"$ref": "#/components/schemas/Node"}
+                },
+            )
+        }
+        schema_definitions = {
+            "Node": {
+                "type": "object",
+                "properties": {
+                    "value": {"type": "string"},
+                    "children": {
+                        "type": "array",
+                        "items": {"$ref": "#/components/schemas/Node"},
+                    },
+                },
+            },
+        }
+
+        output_schema = extract_output_schema_from_responses(
+            responses, schema_definitions=schema_definitions, openapi_version="3.0.0"
+        )
+        assert output_schema is not None
+
+        # Build an MCP Tool with this schema and try to serialize it —
+        # this is the exact path that crashes in the reported issue.
+        from mcp_types import Tool as MCPTool
+
+        tool = MCPTool(
+            name="get_node",
+            description="Get a node",
+            input_schema={"type": "object", "properties": {}},
+            output_schema=output_schema,
+        )
+        # This must not raise ValueError: Circular reference detected
+        tool.model_dump(by_alias=True, mode="json", exclude_none=True)
+
+    def test_mutual_circular_references_serialization(self):
+        """Mutually circular schemas (A→B→A) must survive serialization."""
+        responses = {
+            "200": ResponseInfo(
+                description="A pull request",
+                content_schema={
+                    "application/json": {"$ref": "#/components/schemas/PullRequest"}
+                },
+            )
+        }
+        schema_definitions = {
+            "PullRequest": {
+                "type": "object",
+                "properties": {
+                    "title": {"type": "string"},
+                    "author": {"$ref": "#/components/schemas/User"},
+                },
+            },
+            "User": {
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string"},
+                    "pull_requests": {
+                        "type": "array",
+                        "items": {"$ref": "#/components/schemas/PullRequest"},
+                    },
+                },
+            },
+        }
+
+        output_schema = extract_output_schema_from_responses(
+            responses, schema_definitions=schema_definitions, openapi_version="3.0.0"
+        )
+        assert output_schema is not None
+
+        from mcp_types import Tool as MCPTool
+
+        tool = MCPTool(
+            name="get_pr",
+            description="Get a pull request",
+            input_schema={"type": "object", "properties": {}},
+            output_schema=output_schema,
+        )
+        tool.model_dump(by_alias=True, mode="json", exclude_none=True)
+
+    async def test_multiple_tools_sharing_circular_schemas(self):
+        """Multiple tools from the same spec must not share Python dict objects
+        in their schemas, which would cause Pydantic to raise circular reference
+        errors when serializing the list_tools response."""
+        spec = {
+            "openapi": "3.0.0",
+            "info": {"title": "Test API", "version": "1.0.0"},
+            "paths": {
+                "/nodes": {
+                    "get": {
+                        "operationId": "list_nodes",
+                        "responses": {
+                            "200": {
+                                "description": "List of nodes",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "array",
+                                            "items": {
+                                                "$ref": "#/components/schemas/Node"
+                                            },
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    },
+                    "post": {
+                        "operationId": "create_node",
+                        "requestBody": {
+                            "required": True,
+                            "content": {
+                                "application/json": {
+                                    "schema": {"$ref": "#/components/schemas/Node"}
+                                }
+                            },
+                        },
+                        "responses": {
+                            "201": {
+                                "description": "Created node",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {"$ref": "#/components/schemas/Node"}
+                                    }
+                                },
+                            }
+                        },
+                    },
+                },
+                "/nodes/{id}": {
+                    "get": {
+                        "operationId": "get_node",
+                        "parameters": [
+                            {
+                                "name": "id",
+                                "in": "path",
+                                "required": True,
+                                "schema": {"type": "string"},
+                            }
+                        ],
+                        "responses": {
+                            "200": {
+                                "description": "A node",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {"$ref": "#/components/schemas/Node"}
+                                    }
+                                },
+                            }
+                        },
+                    },
+                },
+            },
+            "components": {
+                "schemas": {
+                    "Node": {
+                        "type": "object",
+                        "properties": {
+                            "value": {"type": "string"},
+                            "children": {
+                                "type": "array",
+                                "items": {"$ref": "#/components/schemas/Node"},
+                            },
+                        },
+                    }
+                }
+            },
+        }
+
+        server = FastMCP.from_openapi(spec, httpx.AsyncClient())
+        tools = await server.list_tools()
+        assert len(tools) >= 3
+
+        # Simulate what the MCP SDK does: serialize all tools together.
+        # This is the exact crash path — model_dump on a list of tools
+        # whose schemas share Python dict objects.
+
+        mcp_tools = [tool.to_mcp_tool(name=tool.name) for tool in tools]
+        for mcp_tool in mcp_tools:
+            mcp_tool.model_dump(by_alias=True, mode="json", exclude_none=True)
diff --git a/tests/utilities/openapi/test_direct_array_schemas.py b/tests/utilities/openapi/test_direct_array_schemas.py
new file mode 100644
index 0000000..b2c1a0c
--- /dev/null
+++ b/tests/utilities/openapi/test_direct_array_schemas.py
@@ -0,0 +1,323 @@
+"""Test handling of direct array schemas in request bodies (FastAPI list parameters)."""
+
+from fastmcp.utilities.openapi.models import (
+    HTTPRoute,
+    ParameterInfo,
+    RequestBodyInfo,
+)
+from fastmcp.utilities.openapi.schemas import (
+    _combine_schemas_and_map_params,
+)
+
+
+class TestDirectArraySchemas:
+    """Test handling of direct array schemas like those generated by FastAPI for list[str] parameters."""
+
+    def test_simple_direct_array_schema(self):
+        """Test route with direct array request body schema."""
+        route = HTTPRoute(
+            path="/simple_list",
+            method="POST",
+            operation_id="simple_list_tool",
+            summary="Simple List Tool",
+            description="A simple tool that takes a list of strings.",
+            parameters=[],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "items": {"type": "string"},
+                        "type": "array",
+                        "title": "Values",
+                    }
+                },
+            ),
+        )
+
+        combined_schema, param_map = _combine_schemas_and_map_params(route)
+
+        # Should create a single parameter from the title
+        assert combined_schema["type"] == "object"
+        assert "values" in combined_schema["properties"]
+        assert "values" in combined_schema["required"]
+
+        # Check the array schema is preserved
+        values_schema = combined_schema["properties"]["values"]
+        assert values_schema["type"] == "array"
+        assert values_schema["items"]["type"] == "string"
+        assert values_schema["title"] == "Values"
+
+        # Check parameter mapping
+        assert "values" in param_map
+        assert param_map["values"]["location"] == "body"
+        assert param_map["values"]["openapi_name"] == "values"
+
+    def test_int_array_schema(self):
+        """Test route with integer array request body schema."""
+        route = HTTPRoute(
+            path="/int_list",
+            method="POST",
+            operation_id="int_list_tool",
+            summary="Integer List Tool",
+            description="A simple tool that takes a list of integers.",
+            parameters=[],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "items": {"type": "integer"},
+                        "type": "array",
+                        "title": "Numbers",
+                    }
+                },
+            ),
+        )
+
+        combined_schema, param_map = _combine_schemas_and_map_params(route)
+
+        # Should create a single parameter from the title
+        assert combined_schema["type"] == "object"
+        assert "numbers" in combined_schema["properties"]
+        assert "numbers" in combined_schema["required"]
+
+        # Check the array schema is preserved
+        numbers_schema = combined_schema["properties"]["numbers"]
+        assert numbers_schema["type"] == "array"
+        assert numbers_schema["items"]["type"] == "integer"
+        assert numbers_schema["title"] == "Numbers"
+
+    def test_mixed_params_with_direct_array(self):
+        """Test route with both URL parameters and direct array request body."""
+        route = HTTPRoute(
+            path="/mixed_params",
+            method="POST",
+            operation_id="mixed_params_tool",
+            summary="Mixed Params Tool",
+            description="A tool with both list and simple parameters.",
+            parameters=[
+                ParameterInfo(
+                    name="prefix",
+                    location="query",
+                    required=True,
+                    schema={"type": "string", "title": "Prefix"},
+                )
+            ],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "title": "Values",
+                    }
+                },
+            ),
+        )
+
+        combined_schema, param_map = _combine_schemas_and_map_params(route)
+
+        # Should have both parameters
+        assert combined_schema["type"] == "object"
+        assert "prefix" in combined_schema["properties"]  # From query param
+        assert "values" in combined_schema["properties"]  # From body array
+        assert "prefix" in combined_schema["required"]
+        assert "values" in combined_schema["required"]
+
+        # Check query parameter
+        prefix_schema = combined_schema["properties"]["prefix"]
+        assert prefix_schema["type"] == "string"
+
+        # Check body array parameter
+        values_schema = combined_schema["properties"]["values"]
+        assert values_schema["type"] == "array"
+        assert values_schema["items"]["type"] == "string"
+
+        # Check parameter mappings
+        assert param_map["prefix"]["location"] == "query"
+        assert param_map["values"]["location"] == "body"
+
+    def test_direct_array_no_title(self):
+        """Test direct array schema without title."""
+        route = HTTPRoute(
+            path="/no_title",
+            method="POST",
+            operation_id="no_title_tool",
+            parameters=[],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        # No title
+                    }
+                },
+            ),
+        )
+
+        combined_schema, param_map = _combine_schemas_and_map_params(route)
+
+        # Should fall back to "body" (default title falls back)
+        assert combined_schema["type"] == "object"
+        assert "body" in combined_schema["properties"]
+        assert "body" in combined_schema["required"]
+
+        # Check parameter mapping
+        assert param_map["body"]["location"] == "body"
+        assert param_map["body"]["openapi_name"] == "body"
+
+    def test_direct_primitive_schema(self):
+        """Test direct primitive (non-array) request body schema."""
+        route = HTTPRoute(
+            path="/primitive",
+            method="POST",
+            operation_id="primitive_tool",
+            parameters=[],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {"type": "string", "title": "Message"}
+                },
+            ),
+        )
+
+        combined_schema, param_map = _combine_schemas_and_map_params(route)
+
+        # Should create a single parameter from the title
+        assert combined_schema["type"] == "object"
+        assert "message" in combined_schema["properties"]
+        assert "message" in combined_schema["required"]
+
+        # Check the primitive schema is preserved
+        message_schema = combined_schema["properties"]["message"]
+        assert message_schema["type"] == "string"
+        assert message_schema["title"] == "Message"
+
+    def test_direct_array_optional(self):
+        """Test direct array schema that's not required."""
+        route = HTTPRoute(
+            path="/optional_list",
+            method="POST",
+            operation_id="optional_list_tool",
+            parameters=[],
+            request_body=RequestBodyInfo(
+                required=False,  # Not required
+                content_schema={
+                    "application/json": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "title": "OptionalValues",
+                    }
+                },
+            ),
+        )
+
+        combined_schema, param_map = _combine_schemas_and_map_params(route)
+
+        # Should create parameter but not mark as required
+        assert combined_schema["type"] == "object"
+        assert "optionalvalues" in combined_schema["properties"]
+        assert "optionalvalues" not in combined_schema["required"]
+
+    def test_direct_array_title_sanitization(self):
+        """Test that titles with special characters are sanitized."""
+        route = HTTPRoute(
+            path="/special_chars",
+            method="POST",
+            operation_id="special_chars_tool",
+            parameters=[],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "title": "Special-Chars & Spaces!",
+                    }
+                },
+            ),
+        )
+
+        combined_schema, param_map = _combine_schemas_and_map_params(route)
+
+        # Should sanitize the title to a valid parameter name (& becomes multiple underscores)
+        assert combined_schema["type"] == "object"
+        assert "special_chars___spaces_" in combined_schema["properties"]
+
+    def test_direct_array_title_starting_with_number(self):
+        """Test that titles starting with numbers are handled."""
+        route = HTTPRoute(
+            path="/number_start",
+            method="POST",
+            operation_id="number_start_tool",
+            parameters=[],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "title": "123Values",
+                    }
+                },
+            ),
+        )
+
+        combined_schema, param_map = _combine_schemas_and_map_params(route)
+
+        # Should fall back to "body_data" since "123values" starts with a number
+        assert combined_schema["type"] == "object"
+        assert "body_data" in combined_schema["properties"]
+
+    def test_preserve_existing_behavior_object_body(self):
+        """Test that existing object-based request bodies still work."""
+        route = HTTPRoute(
+            path="/object_body",
+            method="POST",
+            operation_id="object_body_tool",
+            parameters=[],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "object",
+                        "properties": {
+                            "name": {"type": "string"},
+                            "age": {"type": "integer"},
+                        },
+                        "required": ["name"],
+                    }
+                },
+            ),
+        )
+
+        combined_schema, param_map = _combine_schemas_and_map_params(route)
+
+        # Should handle object bodies as before
+        assert combined_schema["type"] == "object"
+        assert "name" in combined_schema["properties"]
+        assert "age" in combined_schema["properties"]
+        assert "name" in combined_schema["required"]
+        assert "age" not in combined_schema["required"]
+
+    def test_preserve_existing_behavior_ref_body(self):
+        """Test that $ref-based request bodies still work."""
+        route = HTTPRoute(
+            path="/ref_body",
+            method="POST",
+            operation_id="ref_body_tool",
+            parameters=[],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {"$ref": "#/components/schemas/UserCreate"}
+                },
+            ),
+        )
+
+        combined_schema, param_map = _combine_schemas_and_map_params(route)
+
+        # Should handle $ref bodies as before (refs get converted to $defs)
+        assert combined_schema["type"] == "object"
+        assert "body" in combined_schema["properties"]
+        assert combined_schema["properties"]["body"]["$ref"] == "#/$defs/UserCreate"
diff --git a/tests/utilities/openapi/test_director.py b/tests/utilities/openapi/test_director.py
new file mode 100644
index 0000000..6e8fffb
--- /dev/null
+++ b/tests/utilities/openapi/test_director.py
@@ -0,0 +1,1491 @@
+"""Unit tests for RequestDirector."""
+
+import json
+from urllib.parse import unquote
+
+import pytest
+from jsonschema_path import SchemaPath
+
+from fastmcp.utilities.openapi.director import RequestDirector
+from fastmcp.utilities.openapi.models import (
+    HTTPRoute,
+    ParameterInfo,
+    RequestBodyInfo,
+)
+from fastmcp.utilities.openapi.parser import parse_openapi_to_http_routes
+
+
+class TestRequestDirector:
+    """Test RequestDirector request building functionality."""
+
+    @pytest.fixture
+    def basic_route(self):
+        """Create a basic HTTPRoute for testing."""
+        return HTTPRoute(
+            path="/users/{id}",
+            method="GET",
+            operation_id="get_user",
+            parameters=[
+                ParameterInfo(
+                    name="id",
+                    location="path",
+                    required=True,
+                    schema={"type": "integer"},
+                )
+            ],
+            flat_param_schema={
+                "type": "object",
+                "properties": {"id": {"type": "integer"}},
+                "required": ["id"],
+            },
+            parameter_map={"id": {"location": "path", "openapi_name": "id"}},
+        )
+
+    @pytest.fixture
+    def complex_route(self):
+        """Create a complex HTTPRoute with multiple parameter types."""
+        return HTTPRoute(
+            path="/items/{id}",
+            method="PATCH",
+            operation_id="update_item",
+            parameters=[
+                ParameterInfo(
+                    name="id",
+                    location="path",
+                    required=True,
+                    schema={"type": "string"},
+                ),
+                ParameterInfo(
+                    name="version",
+                    location="query",
+                    required=False,
+                    schema={"type": "integer", "default": 1},
+                ),
+                ParameterInfo(
+                    name="X-Client-Version",
+                    location="header",
+                    required=False,
+                    schema={"type": "string"},
+                ),
+            ],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "object",
+                        "properties": {
+                            "title": {"type": "string"},
+                            "description": {"type": "string"},
+                        },
+                        "required": ["title"],
+                    }
+                },
+            ),
+            flat_param_schema={
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string"},
+                    "version": {"type": "integer", "default": 1},
+                    "X-Client-Version": {"type": "string"},
+                    "title": {"type": "string"},
+                    "description": {"type": "string"},
+                },
+                "required": ["id", "title"],
+            },
+            parameter_map={
+                "id": {"location": "path", "openapi_name": "id"},
+                "version": {"location": "query", "openapi_name": "version"},
+                "X-Client-Version": {
+                    "location": "header",
+                    "openapi_name": "X-Client-Version",
+                },
+                "title": {"location": "body", "openapi_name": "title"},
+                "description": {"location": "body", "openapi_name": "description"},
+            },
+        )
+
+    @pytest.fixture
+    def collision_route(self):
+        """Create a route with parameter name collisions."""
+        return HTTPRoute(
+            path="/users/{id}",
+            method="PUT",
+            operation_id="update_user",
+            parameters=[
+                ParameterInfo(
+                    name="id",
+                    location="path",
+                    required=True,
+                    schema={"type": "integer"},
+                )
+            ],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "object",
+                        "properties": {
+                            "id": {"type": "integer"},
+                            "name": {"type": "string"},
+                        },
+                        "required": ["name"],
+                    }
+                },
+            ),
+            flat_param_schema={
+                "type": "object",
+                "properties": {
+                    "id__path": {"type": "integer"},
+                    "id": {"type": "integer"},
+                    "name": {"type": "string"},
+                },
+                "required": ["id__path", "name"],
+            },
+            parameter_map={
+                "id__path": {"location": "path", "openapi_name": "id"},
+                "id": {"location": "body", "openapi_name": "id"},
+                "name": {"location": "body", "openapi_name": "name"},
+            },
+        )
+
+    @pytest.fixture
+    def director(self, basic_openapi_30_spec):
+        """Create a RequestDirector instance."""
+        spec = SchemaPath.from_dict(basic_openapi_30_spec)
+        return RequestDirector(spec)
+
+    def test_director_initialization(self, basic_openapi_30_spec):
+        """Test RequestDirector initialization."""
+        spec = SchemaPath.from_dict(basic_openapi_30_spec)
+        director = RequestDirector(spec)
+
+        assert director._spec is not None
+        assert director._spec == spec
+
+    def test_build_basic_request(self, director, basic_route):
+        """Test building a basic GET request with path parameter."""
+        flat_args = {"id": 123}
+
+        request = director.build(basic_route, flat_args, "https://api.example.com")
+
+        assert request.method == "GET"
+        assert request.url == "https://api.example.com/users/123"
+        assert (
+            request.content == b""
+        )  # httpx.Request sets content to empty bytes for GET
+
+    def test_build_complex_request(self, director, complex_route):
+        """Test building a complex request with multiple parameter types."""
+        flat_args = {
+            "id": "item123",
+            "version": 2,
+            "X-Client-Version": "1.0.0",
+            "title": "Updated Title",
+            "description": "Updated description",
+        }
+
+        request = director.build(complex_route, flat_args, "https://api.example.com")
+
+        assert request.method == "PATCH"
+        assert "item123" in str(request.url)
+        assert "version=2" in str(request.url)
+
+        # Check headers
+        headers = dict(request.headers) if request.headers else {}
+        assert (
+            headers.get("x-client-version") == "1.0.0"
+        )  # httpx normalizes headers to lowercase
+
+        # Check body
+        assert request.content is not None
+        body_data = json.loads(request.content)
+        assert body_data["title"] == "Updated Title"
+        assert body_data["description"] == "Updated description"
+
+    def test_build_request_with_collisions(self, director, collision_route):
+        """Test building request with parameter name collisions."""
+        flat_args = {
+            "id__path": 123,  # Path parameter
+            "id": 456,  # Body parameter
+            "name": "John Doe",
+        }
+
+        request = director.build(collision_route, flat_args, "https://api.example.com")
+
+        assert request.method == "PUT"
+        assert "123" in str(request.url)  # Path ID should be 123
+
+        # Check body
+        body_data = json.loads(request.content)
+        assert body_data["id"] == 456  # Body ID should be 456
+        assert body_data["name"] == "John Doe"
+
+    def test_build_request_with_none_values(self, director, complex_route):
+        """Test that None values are skipped for optional parameters."""
+        flat_args = {
+            "id": "item123",
+            "version": None,  # Optional, should be skipped
+            "X-Client-Version": None,  # Optional, should be skipped
+            "title": "Required Title",
+            "description": None,  # Optional body param, should be skipped
+        }
+
+        request = director.build(complex_route, flat_args, "https://api.example.com")
+
+        assert request.method == "PATCH"
+        assert "item123" in str(request.url)
+        assert "version" not in str(request.url)  # Should not include None version
+
+        headers = dict(request.headers) if request.headers else {}
+        assert "X-Client-Version" not in headers
+
+        body_data = json.loads(request.content)
+        assert body_data["title"] == "Required Title"
+        assert "description" not in body_data  # Should not include None description
+
+    def test_build_request_fallback_mapping(self, director):
+        """Test fallback parameter mapping when parameter_map is not available."""
+        # Create route without parameter_map
+        route_without_map = HTTPRoute(
+            path="/users/{id}",
+            method="GET",
+            operation_id="get_user",
+            parameters=[
+                ParameterInfo(
+                    name="id",
+                    location="path",
+                    required=True,
+                    schema={"type": "integer"},
+                )
+            ],
+            # No parameter_map provided
+        )
+
+        flat_args = {"id": 123}
+
+        request = director.build(
+            route_without_map, flat_args, "https://api.example.com"
+        )
+
+        assert request.method == "GET"
+        assert "123" in str(request.url)
+
+    def test_build_request_suffixed_parameters(self, director):
+        """Test handling of suffixed parameters in fallback mode."""
+        route = HTTPRoute(
+            path="/users/{id}",
+            method="POST",
+            operation_id="create_user",
+            parameters=[
+                ParameterInfo(
+                    name="id",
+                    location="path",
+                    required=True,
+                    schema={"type": "integer"},
+                )
+            ],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "object",
+                        "properties": {"name": {"type": "string"}},
+                    }
+                },
+            ),
+        )
+
+        # Use suffixed parameter names
+        flat_args = {
+            "id__path": 123,
+            "name": "John Doe",
+        }
+
+        request = director.build(route, flat_args, "https://api.example.com")
+
+        assert request.method == "POST"
+        assert "123" in str(request.url)
+
+        body_data = json.loads(request.content)
+        assert body_data["name"] == "John Doe"
+
+    def test_url_building(self, director, basic_route):
+        """Test URL building with different base URLs."""
+        flat_args = {"id": 123}
+
+        # Test with trailing slash
+        request1 = director.build(basic_route, flat_args, "https://api.example.com/")
+        assert request1.url == "https://api.example.com/users/123"
+
+        # Test without trailing slash
+        request2 = director.build(basic_route, flat_args, "https://api.example.com")
+        assert request2.url == "https://api.example.com/users/123"
+
+        # Test with path in base URL
+        request3 = director.build(basic_route, flat_args, "https://api.example.com/v1")
+        assert request3.url == "https://api.example.com/v1/users/123"
+
+    def test_body_construction_single_value(self, director):
+        """Test body construction when body schema is not an object."""
+        route = HTTPRoute(
+            path="/upload",
+            method="POST",
+            operation_id="upload_file",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={"text/plain": {"type": "string"}},
+            ),
+            parameter_map={
+                "content": {"location": "body", "openapi_name": "content"},
+            },
+        )
+
+        flat_args = {"content": "Hello, World!"}
+
+        request = director.build(route, flat_args, "https://api.example.com")
+
+        assert request.method == "POST"
+        # For non-JSON content, httpx uses 'content' parameter which becomes bytes
+        assert request.content == b"Hello, World!"
+
+    def test_body_construction_multiple_properties_non_object_schema(self, director):
+        """Test body construction with multiple properties but non-object schema."""
+        route = HTTPRoute(
+            path="/complex",
+            method="POST",
+            operation_id="complex_op",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {"type": "string"}  # Non-object schema
+                },
+            ),
+            parameter_map={
+                "prop1": {"location": "body", "openapi_name": "prop1"},
+                "prop2": {"location": "body", "openapi_name": "prop2"},
+            },
+        )
+
+        flat_args = {"prop1": "value1", "prop2": "value2"}
+
+        request = director.build(route, flat_args, "https://api.example.com")
+
+        assert request.method == "POST"
+        # Should wrap in object when multiple properties but schema is not object
+        body_data = json.loads(request.content)
+        assert body_data == {"prop1": "value1", "prop2": "value2"}
+
+
+class TestContentTypeHandling:
+    """Test that request Content-Type respects the OpenAPI spec."""
+
+    @pytest.fixture
+    def director(self, basic_openapi_30_spec):
+        spec = SchemaPath.from_dict(basic_openapi_30_spec)
+        return RequestDirector(spec)
+
+    def test_application_json_uses_httpx_json(self, director):
+        """Standard application/json uses httpx's json= parameter."""
+        route = HTTPRoute(
+            path="/items",
+            method="PATCH",
+            operation_id="update_item",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "object",
+                        "properties": {"name": {"type": "string"}},
+                    }
+                },
+            ),
+            parameter_map={
+                "name": {"location": "body", "openapi_name": "name"},
+            },
+        )
+
+        request = director.build(route, {"name": "test"}, "https://example.com")
+        assert request.headers["content-type"] == "application/json"
+        assert json.loads(request.content) == {"name": "test"}
+
+    def test_json_patch_content_type_preserved(self, director):
+        """application/json-patch+json is sent as the Content-Type header."""
+        route = HTTPRoute(
+            path="/items/{id}",
+            method="PATCH",
+            operation_id="patch_item",
+            parameters=[
+                ParameterInfo(
+                    name="id",
+                    location="path",
+                    required=True,
+                    schema={"type": "string"},
+                ),
+            ],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json-patch+json": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "op": {"type": "string"},
+                                "path": {"type": "string"},
+                                "value": {},
+                            },
+                        },
+                    }
+                },
+            ),
+            parameter_map={
+                "id": {"location": "path", "openapi_name": "id"},
+                "body": {"location": "body", "openapi_name": "body"},
+            },
+        )
+
+        patch_ops = [{"op": "replace", "path": "/name", "value": "new-name"}]
+        request = director.build(
+            route, {"id": "123", "body": patch_ops}, "https://example.com"
+        )
+
+        assert request.headers["content-type"] == "application/json-patch+json"
+        assert json.loads(request.content) == patch_ops
+
+    def test_custom_json_content_type_with_dict_body(self, director):
+        """Any non-standard JSON content type gets the correct header."""
+        route = HTTPRoute(
+            path="/items",
+            method="POST",
+            operation_id="create_item",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/merge-patch+json": {
+                        "type": "object",
+                        "properties": {"name": {"type": "string"}},
+                    }
+                },
+            ),
+            parameter_map={
+                "name": {"location": "body", "openapi_name": "name"},
+            },
+        )
+
+        request = director.build(route, {"name": "test"}, "https://example.com")
+        assert request.headers["content-type"] == "application/merge-patch+json"
+        assert json.loads(request.content) == {"name": "test"}
+
+    def test_content_type_preserves_media_type_parameters(self, director):
+        """Media-type parameters like charset are preserved on the wire."""
+        route = HTTPRoute(
+            path="/items",
+            method="POST",
+            operation_id="create_item",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json-patch+json; charset=utf-8": {
+                        "type": "object",
+                        "properties": {"name": {"type": "string"}},
+                    }
+                },
+            ),
+            parameter_map={
+                "name": {"location": "body", "openapi_name": "name"},
+            },
+        )
+
+        request = director.build(route, {"name": "test"}, "https://example.com")
+        assert (
+            request.headers["content-type"]
+            == "application/json-patch+json; charset=utf-8"
+        )
+        assert json.loads(request.content) == {"name": "test"}
+
+    def test_custom_content_type_preserves_other_headers(self, director):
+        """Custom content type doesn't clobber other headers from parameters."""
+        route = HTTPRoute(
+            path="/items",
+            method="PATCH",
+            operation_id="patch_item",
+            parameters=[
+                ParameterInfo(
+                    name="X-Request-Id",
+                    location="header",
+                    required=True,
+                    schema={"type": "string"},
+                ),
+            ],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json-patch+json": {
+                        "type": "object",
+                        "properties": {"name": {"type": "string"}},
+                    }
+                },
+            ),
+            parameter_map={
+                "X-Request-Id": {
+                    "location": "header",
+                    "openapi_name": "X-Request-Id",
+                },
+                "name": {"location": "body", "openapi_name": "name"},
+            },
+        )
+
+        request = director.build(
+            route,
+            {"X-Request-Id": "abc-123", "name": "test"},
+            "https://example.com",
+        )
+        assert request.headers["content-type"] == "application/json-patch+json"
+        assert request.headers["x-request-id"] == "abc-123"
+
+    def test_no_request_body_info_defaults_to_json(self, director):
+        """When route has no request_body metadata, dict body uses application/json."""
+        route = HTTPRoute(
+            path="/items",
+            method="POST",
+            operation_id="create_item",
+            parameter_map={
+                "name": {"location": "body", "openapi_name": "name"},
+            },
+        )
+
+        request = director.build(route, {"name": "test"}, "https://example.com")
+        assert request.headers["content-type"] == "application/json"
+
+    def test_non_json_content_type_uses_native_encoding(self, director):
+        """Non-JSON types like multipart/form-data use httpx's native encoding."""
+        route = HTTPRoute(
+            path="/upload",
+            method="POST",
+            operation_id="upload",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "multipart/form-data": {
+                        "type": "object",
+                        "properties": {"file": {"type": "string"}},
+                    }
+                },
+            ),
+            parameter_map={
+                "file": {"location": "body", "openapi_name": "file"},
+            },
+        )
+
+        request = director.build(route, {"file": "data"}, "https://example.com")
+        # multipart/form-data should be sent as multipart, not JSON
+        assert "multipart/form-data" in request.headers["content-type"]
+
+
+class TestQueryParameterSerialization:
+    """Test that query parameters respect OpenAPI explode/style settings."""
+
+    @pytest.fixture
+    def director(self, basic_openapi_30_spec):
+        spec = SchemaPath.from_dict(basic_openapi_30_spec)
+        return RequestDirector(spec)
+
+    def test_explode_true_repeats_keys(self, director):
+        """Default behavior: explode=true sends values=a&values=b."""
+        route = HTTPRoute(
+            path="/items",
+            method="GET",
+            operation_id="list_items",
+            parameters=[
+                ParameterInfo(
+                    name="values",
+                    location="query",
+                    required=True,
+                    schema={"type": "array", "items": {"type": "string"}},
+                    explode=True,
+                )
+            ],
+            parameter_map={
+                "values": {"location": "query", "openapi_name": "values"},
+            },
+        )
+
+        request = director.build(
+            route, {"values": ["hello", "world"]}, "https://example.com"
+        )
+        url = str(request.url)
+        assert "values=hello" in url
+        assert "values=world" in url
+
+    def test_explode_false_comma_joins(self, director):
+        """explode=false sends values=hello,world."""
+        route = HTTPRoute(
+            path="/items",
+            method="GET",
+            operation_id="list_items",
+            parameters=[
+                ParameterInfo(
+                    name="values",
+                    location="query",
+                    required=True,
+                    schema={"type": "array", "items": {"type": "string"}},
+                    explode=False,
+                )
+            ],
+            parameter_map={
+                "values": {"location": "query", "openapi_name": "values"},
+            },
+        )
+
+        request = director.build(
+            route, {"values": ["hello", "world"]}, "https://example.com"
+        )
+        url = str(request.url)
+        assert "values=hello%2Cworld" in url or "values=hello,world" in url
+        # Must NOT have repeated keys
+        assert url.count("values=") == 1
+
+    def test_explode_none_defaults_to_true(self, director):
+        """When explode is unset, OpenAPI default for form style is explode=true."""
+        route = HTTPRoute(
+            path="/items",
+            method="GET",
+            operation_id="list_items",
+            parameters=[
+                ParameterInfo(
+                    name="tags",
+                    location="query",
+                    required=True,
+                    schema={"type": "array", "items": {"type": "string"}},
+                    explode=None,
+                )
+            ],
+            parameter_map={
+                "tags": {"location": "query", "openapi_name": "tags"},
+            },
+        )
+
+        request = director.build(route, {"tags": ["a", "b"]}, "https://example.com")
+        url = str(request.url)
+        assert "tags=a" in url
+        assert "tags=b" in url
+
+    def test_explode_false_with_integers(self, director):
+        """explode=false works with non-string values."""
+        route = HTTPRoute(
+            path="/items",
+            method="GET",
+            operation_id="list_items",
+            parameters=[
+                ParameterInfo(
+                    name="ids",
+                    location="query",
+                    required=True,
+                    schema={"type": "array", "items": {"type": "integer"}},
+                    explode=False,
+                )
+            ],
+            parameter_map={
+                "ids": {"location": "query", "openapi_name": "ids"},
+            },
+        )
+
+        request = director.build(route, {"ids": [1, 2, 3]}, "https://example.com")
+        url = str(request.url)
+        assert "ids=1%2C2%2C3" in url or "ids=1,2,3" in url
+        assert url.count("ids=") == 1
+
+    def test_scalar_query_param_unaffected_by_explode(self, director):
+        """Non-list values pass through regardless of explode setting."""
+        route = HTTPRoute(
+            path="/items",
+            method="GET",
+            operation_id="get_item",
+            parameters=[
+                ParameterInfo(
+                    name="name",
+                    location="query",
+                    required=True,
+                    schema={"type": "string"},
+                    explode=False,
+                )
+            ],
+            parameter_map={
+                "name": {"location": "query", "openapi_name": "name"},
+            },
+        )
+
+        request = director.build(route, {"name": "foo"}, "https://example.com")
+        assert "name=foo" in str(request.url)
+
+    def test_pipe_delimited_explode_false(self, director):
+        """style=pipeDelimited, explode=false sends ids=1|2|3."""
+        route = HTTPRoute(
+            path="/items",
+            method="GET",
+            operation_id="list_items",
+            parameters=[
+                ParameterInfo(
+                    name="ids",
+                    location="query",
+                    required=True,
+                    schema={"type": "array", "items": {"type": "string"}},
+                    explode=False,
+                    style="pipeDelimited",
+                )
+            ],
+            parameter_map={
+                "ids": {"location": "query", "openapi_name": "ids"},
+            },
+        )
+
+        request = director.build(route, {"ids": ["1", "2", "3"]}, "https://example.com")
+        url = str(request.url)
+        assert "ids=1%7C2%7C3" in url or "ids=1|2|3" in url
+        assert url.count("ids=") == 1
+
+    def test_space_delimited_explode_false(self, director):
+        """style=spaceDelimited, explode=false sends ids=1%202%203."""
+        route = HTTPRoute(
+            path="/items",
+            method="GET",
+            operation_id="list_items",
+            parameters=[
+                ParameterInfo(
+                    name="ids",
+                    location="query",
+                    required=True,
+                    schema={"type": "array", "items": {"type": "string"}},
+                    explode=False,
+                    style="spaceDelimited",
+                )
+            ],
+            parameter_map={
+                "ids": {"location": "query", "openapi_name": "ids"},
+            },
+        )
+
+        request = director.build(route, {"ids": ["1", "2", "3"]}, "https://example.com")
+        url = str(request.url)
+        assert "ids=1+2+3" in url or "ids=1%202%203" in url
+        assert url.count("ids=") == 1
+
+    def test_explode_false_booleans_lowercased(self, director):
+        """Booleans serialize as true/false, not True/False."""
+        route = HTTPRoute(
+            path="/items",
+            method="GET",
+            operation_id="list_items",
+            parameters=[
+                ParameterInfo(
+                    name="flags",
+                    location="query",
+                    required=True,
+                    schema={"type": "array", "items": {"type": "boolean"}},
+                    explode=False,
+                )
+            ],
+            parameter_map={
+                "flags": {"location": "query", "openapi_name": "flags"},
+            },
+        )
+
+        request = director.build(route, {"flags": [True, False]}, "https://example.com")
+        url = str(request.url)
+        assert "true" in url and "false" in url
+        assert "True" not in url and "False" not in url
+
+    def test_explode_false_empty_list_omitted(self, director):
+        """Empty list with explode=false omits the parameter entirely."""
+        route = HTTPRoute(
+            path="/items",
+            method="GET",
+            operation_id="list_items",
+            parameters=[
+                ParameterInfo(
+                    name="ids",
+                    location="query",
+                    required=False,
+                    schema={"type": "array", "items": {"type": "string"}},
+                    explode=False,
+                )
+            ],
+            parameter_map={
+                "ids": {"location": "query", "openapi_name": "ids"},
+            },
+        )
+
+        request = director.build(route, {"ids": []}, "https://example.com")
+        assert "ids" not in str(request.url)
+
+    def test_explode_false_dict_value(self, director):
+        """style=form, explode=false on objects serializes as key,value pairs."""
+        route = HTTPRoute(
+            path="/items",
+            method="GET",
+            operation_id="list_items",
+            parameters=[
+                ParameterInfo(
+                    name="color",
+                    location="query",
+                    required=True,
+                    schema={
+                        "type": "object",
+                        "properties": {
+                            "R": {"type": "integer"},
+                            "G": {"type": "integer"},
+                            "B": {"type": "integer"},
+                        },
+                    },
+                    explode=False,
+                    style="form",
+                )
+            ],
+            parameter_map={
+                "color": {"location": "query", "openapi_name": "color"},
+            },
+        )
+
+        request = director.build(
+            route,
+            {"color": {"R": 100, "G": 200, "B": 150}},
+            "https://example.com",
+        )
+        url = str(request.url)
+        assert "color=R" in url
+        assert url.count("color=") == 1
+        # Should contain alternating key,value pairs
+        assert "100" in url and "200" in url and "150" in url
+
+    def test_explode_true_dict_expands_to_separate_params(self, director):
+        """style=form, explode=true on objects expands each property as a query param."""
+        route = HTTPRoute(
+            path="/test",
+            method="GET",
+            operation_id="test_endpoint",
+            parameters=[
+                ParameterInfo(
+                    name="data",
+                    location="query",
+                    required=True,
+                    schema={
+                        "type": "object",
+                        "properties": {
+                            "myAttribute": {"type": "boolean"},
+                        },
+                    },
+                    explode=True,
+                )
+            ],
+            parameter_map={
+                "data": {"location": "query", "openapi_name": "data"},
+            },
+        )
+
+        request = director.build(
+            route, {"data": {"myAttribute": True}}, "https://example.com"
+        )
+        url = str(request.url)
+        # Should expand to myAttribute=true (not data={'myAttribute': True})
+        assert "myAttribute=true" in url
+        assert "data=" not in url
+
+    def test_explode_default_dict_expands_to_separate_params(self, director):
+        """Default explode (None → true) on objects expands properties."""
+        route = HTTPRoute(
+            path="/test",
+            method="GET",
+            operation_id="test_endpoint",
+            parameters=[
+                ParameterInfo(
+                    name="filter",
+                    location="query",
+                    required=True,
+                    schema={
+                        "type": "object",
+                        "properties": {
+                            "category": {"type": "string"},
+                            "active": {"type": "boolean"},
+                        },
+                    },
+                    # explode defaults to None → treated as true
+                )
+            ],
+            parameter_map={
+                "filter": {"location": "query", "openapi_name": "filter"},
+            },
+        )
+
+        request = director.build(
+            route,
+            {"filter": {"category": "electronics", "active": False}},
+            "https://example.com",
+        )
+        url = str(request.url)
+        assert "category=electronics" in url
+        assert "active=false" in url
+        assert "filter=" not in url
+
+    def test_explode_true_empty_dict_omitted(self, director):
+        """Empty dict with explode=true omits the parameter."""
+        route = HTTPRoute(
+            path="/items",
+            method="GET",
+            operation_id="list_items",
+            parameters=[
+                ParameterInfo(
+                    name="filter",
+                    location="query",
+                    required=False,
+                    schema={"type": "object"},
+                    explode=True,
+                )
+            ],
+            parameter_map={
+                "filter": {"location": "query", "openapi_name": "filter"},
+            },
+        )
+
+        request = director.build(route, {"filter": {}}, "https://example.com")
+        assert "filter" not in str(request.url)
+
+    def test_explode_false_empty_dict_omitted(self, director):
+        """Empty dict with explode=false omits the parameter."""
+        route = HTTPRoute(
+            path="/items",
+            method="GET",
+            operation_id="list_items",
+            parameters=[
+                ParameterInfo(
+                    name="filter",
+                    location="query",
+                    required=False,
+                    schema={"type": "object"},
+                    explode=False,
+                )
+            ],
+            parameter_map={
+                "filter": {"location": "query", "openapi_name": "filter"},
+            },
+        )
+
+        request = director.build(route, {"filter": {}}, "https://example.com")
+        assert "filter" not in str(request.url)
+
+
+class TestRequestDirectorIntegration:
+    """Test RequestDirector with real parsed routes."""
+
+    def test_with_parsed_routes(self, basic_openapi_30_spec):
+        """Test RequestDirector with routes parsed from real spec."""
+        routes = parse_openapi_to_http_routes(basic_openapi_30_spec)
+        assert len(routes) == 1
+
+        route = routes[0]
+        spec = SchemaPath.from_dict(basic_openapi_30_spec)
+        director = RequestDirector(spec)
+
+        flat_args = {"id": 42}
+        request = director.build(route, flat_args, "https://api.example.com")
+
+        assert request.method == "GET"
+        assert request.url == "https://api.example.com/users/42"
+
+    def test_with_collision_spec(self, collision_spec):
+        """Test RequestDirector with collision spec."""
+        routes = parse_openapi_to_http_routes(collision_spec)
+        assert len(routes) == 1
+
+        route = routes[0]
+        spec = SchemaPath.from_dict(collision_spec)
+        director = RequestDirector(spec)
+
+        # Use the parameter names from the actual parameter map
+        param_map = route.parameter_map
+        path_param_name = None
+        body_param_names = []
+
+        for param_name, mapping in param_map.items():
+            if mapping["location"] == "path" and mapping["openapi_name"] == "id":
+                path_param_name = param_name
+            elif mapping["location"] == "body":
+                body_param_names.append(param_name)
+
+        assert path_param_name is not None
+
+        flat_args = {path_param_name: 123, "name": "John Doe"}
+        # Add body id if it exists in the parameter map
+        for param_name in body_param_names:
+            if "id" in param_name:
+                flat_args[param_name] = 456
+
+        request = director.build(route, flat_args, "https://api.example.com")
+
+        assert request.method == "PUT"
+        assert "123" in str(request.url)
+
+    def test_with_deepobject_spec(self, deepobject_spec):
+        """Test RequestDirector with deepObject parameters."""
+        routes = parse_openapi_to_http_routes(deepobject_spec)
+        assert len(routes) == 1
+
+        route = routes[0]
+        spec = SchemaPath.from_dict(deepobject_spec)
+        director = RequestDirector(spec)
+
+        # DeepObject parameters should be flattened in the parameter map
+        flat_args = {}
+        for param_name in route.parameter_map.keys():
+            if "filter" in param_name:
+                # Set some test values based on parameter name
+                if "category" in param_name:
+                    flat_args[param_name] = "electronics"
+                elif "min" in param_name:
+                    flat_args[param_name] = 10.0
+                elif "max" in param_name:
+                    flat_args[param_name] = 100.0
+
+        if flat_args:  # Only test if we have parameters to test with
+            request = director.build(route, flat_args, "https://api.example.com")
+
+            assert request.method == "GET"
+            assert str(request.url).startswith("https://api.example.com/search")
+
+
+class TestPathTraversalPrevention:
+    """Test that path parameter values are URL-encoded to prevent SSRF/path traversal."""
+
+    @pytest.fixture
+    def director(self, basic_openapi_30_spec):
+        spec = SchemaPath.from_dict(basic_openapi_30_spec)
+        return RequestDirector(spec)
+
+    @pytest.fixture
+    def path_route(self):
+        return HTTPRoute(
+            path="/api/v1/users/{id}/profile",
+            method="GET",
+            operation_id="get_user_profile",
+            parameters=[
+                ParameterInfo(
+                    name="id",
+                    location="path",
+                    required=True,
+                    schema={"type": "string"},
+                )
+            ],
+            flat_param_schema={
+                "type": "object",
+                "properties": {"id": {"type": "string"}},
+                "required": ["id"],
+            },
+            parameter_map={"id": {"location": "path", "openapi_name": "id"}},
+        )
+
+    @pytest.mark.parametrize(
+        "malicious_id",
+        [
+            "../../../admin/delete-all?",
+            "../../secret",
+            "../../../etc/passwd",
+            "foo/../../../admin",
+            "..%2F..%2Fadmin",
+            "..%2f..%2fadmin",
+        ],
+    )
+    def test_path_traversal_encoded(self, director, path_route, malicious_id: str):
+        request = director.build(
+            path_route, {"id": malicious_id}, "https://api.example.com"
+        )
+        url = str(request.url)
+        assert "/admin" not in url
+        assert "/secret" not in url
+        assert "/etc/passwd" not in url
+        assert url.startswith("https://api.example.com/api/v1/users/")
+
+    def test_slash_in_param_is_encoded(self, director, path_route):
+        request = director.build(path_route, {"id": "a/b"}, "https://api.example.com")
+        url = str(request.url)
+        assert "/a/b/" not in url
+        assert "a%2Fb" in url
+
+    def test_dot_dot_slash_is_encoded(self, director, path_route):
+        request = director.build(
+            path_route, {"id": "../admin"}, "https://api.example.com"
+        )
+        url = str(request.url)
+        assert "%2E%2E%2Fadmin" in url or "%2e%2e%2fadmin" in url
+        assert url.startswith("https://api.example.com/api/v1/users/")
+
+    def test_question_mark_encoded(self, director, path_route):
+        request = director.build(
+            path_route, {"id": "foo?bar=baz"}, "https://api.example.com"
+        )
+        url = str(request.url)
+        assert "foo%3Fbar%3Dbaz" in url or "foo%3fbar%3dbaz" in url
+
+    def test_hash_encoded(self, director, path_route):
+        request = director.build(
+            path_route, {"id": "foo#fragment"}, "https://api.example.com"
+        )
+        url = str(request.url)
+        assert "foo%23fragment" in url
+
+    def test_normal_values_still_work(self, director, path_route):
+        request = director.build(
+            path_route, {"id": "user-123"}, "https://api.example.com"
+        )
+        assert (
+            str(request.url) == "https://api.example.com/api/v1/users/user-123/profile"
+        )
+
+    def test_dotted_values_encode_dots(self, director, path_route):
+        """Dots are encoded to prevent path normalization by urljoin."""
+        request = director.build(
+            path_route, {"id": "v1.2.3"}, "https://api.example.com"
+        )
+        url = str(request.url)
+        assert "v1%2E2%2E3" in url
+        assert url.startswith("https://api.example.com/api/v1/users/")
+
+    def test_numeric_values_still_work(self, director, path_route):
+        request = director.build(path_route, {"id": 42}, "https://api.example.com")
+        assert str(request.url) == "https://api.example.com/api/v1/users/42/profile"
+
+    def test_bare_single_dot_encoded(self, director, path_route):
+        """Bare '.' must be encoded so urljoin doesn't normalize it away."""
+        request = director.build(path_route, {"id": "."}, "https://api.example.com")
+        url = str(request.url)
+        assert "%2E" in url
+        assert url.startswith("https://api.example.com/api/v1/users/")
+
+    def test_bare_dotdot_encoded(self, director, path_route):
+        """Bare '..' must be encoded so urljoin doesn't resolve it as traversal."""
+        request = director.build(path_route, {"id": ".."}, "https://api.example.com")
+        url = str(request.url)
+        assert "%2E%2E" in url or "%2e%2e" in url
+        assert url.startswith("https://api.example.com/api/v1/users/")
+
+    def test_double_encoded_traversal(self, director, path_route):
+        request = director.build(
+            path_route,
+            {"id": "..%2F..%2Fadmin"},
+            "https://api.example.com",
+        )
+        url = str(request.url)
+        decoded = unquote(unquote(url))
+        # Verify traversal didn't escape the users/ prefix
+        assert decoded.startswith("https://api.example.com/api/v1/users/")
+        assert url.startswith("https://api.example.com/api/v1/users/")
+
+
+class TestContentTypeDispatch:
+    """Test that non-JSON content types are dispatched correctly."""
+
+    @pytest.fixture
+    def director(self):
+        spec = SchemaPath.from_dict(
+            {
+                "openapi": "3.0.0",
+                "info": {"title": "t", "version": "1"},
+                "paths": {},
+            }
+        )
+        return RequestDirector(spec)
+
+    @pytest.fixture
+    def multipart_route(self):
+        return HTTPRoute(
+            path="/upload",
+            method="POST",
+            operation_id="upload_file",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "multipart/form-data": {
+                        "type": "object",
+                        "properties": {
+                            "filename": {"type": "string"},
+                            "data": {"type": "string"},
+                        },
+                    }
+                },
+            ),
+            parameter_map={
+                "filename": {"location": "body", "openapi_name": "filename"},
+                "data": {"location": "body", "openapi_name": "data"},
+            },
+        )
+
+    @pytest.fixture
+    def form_urlencoded_route(self):
+        return HTTPRoute(
+            path="/login",
+            method="POST",
+            operation_id="login",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/x-www-form-urlencoded": {
+                        "type": "object",
+                        "properties": {
+                            "username": {"type": "string"},
+                            "password": {"type": "string"},
+                        },
+                    }
+                },
+            ),
+            parameter_map={
+                "username": {"location": "body", "openapi_name": "username"},
+                "password": {"location": "body", "openapi_name": "password"},
+            },
+        )
+
+    @pytest.fixture
+    def json_route(self):
+        return HTTPRoute(
+            path="/items",
+            method="POST",
+            operation_id="create_item",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "object",
+                        "properties": {
+                            "name": {"type": "string"},
+                        },
+                    }
+                },
+            ),
+            parameter_map={
+                "name": {"location": "body", "openapi_name": "name"},
+            },
+        )
+
+    def test_multipart_form_data_not_sent_as_json(self, director, multipart_route):
+        """multipart/form-data bodies should use httpx data= not json=."""
+        request = director.build(
+            multipart_route,
+            {"filename": "test.txt", "data": "hello"},
+        )
+        content_type = request.headers.get("content-type", "")
+        assert "multipart/form-data" in content_type
+        # Should NOT be JSON-encoded
+        assert "application/json" not in content_type
+
+    def test_form_urlencoded_not_sent_as_json(self, director, form_urlencoded_route):
+        """application/x-www-form-urlencoded bodies should use httpx data=."""
+        request = director.build(
+            form_urlencoded_route,
+            {"username": "alice", "password": "secret"},
+        )
+        content_type = request.headers.get("content-type", "")
+        assert "application/x-www-form-urlencoded" in content_type
+        assert "application/json" not in content_type
+        # Verify the body is form-encoded
+        body_text = request.content.decode("utf-8")
+        assert "username=alice" in body_text
+        assert "password=secret" in body_text
+
+    def test_multipart_stringifies_non_string_values(self, director):
+        """Non-string scalars (int, bool) must be stringified for httpx files=."""
+        route = HTTPRoute(
+            path="/submit",
+            method="POST",
+            operation_id="submit",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "multipart/form-data": {
+                        "type": "object",
+                        "properties": {
+                            "count": {"type": "integer"},
+                            "active": {"type": "boolean"},
+                        },
+                    }
+                },
+            ),
+            parameter_map={
+                "count": {"location": "body", "openapi_name": "count"},
+                "active": {"location": "body", "openapi_name": "active"},
+            },
+        )
+        # Should not raise — non-string values get str() converted
+        request = director.build(route, {"count": 42, "active": True})
+        content_type = request.headers.get("content-type", "")
+        assert "multipart/form-data" in content_type
+        # Multipart requests are streaming; read to verify content
+        request.read()
+        body = request.content.decode("utf-8")
+        assert "42" in body
+        assert "true" in body
+
+    def test_multipart_preserves_tuple_values(self, director):
+        """Tuple values (file-like) are passed through unchanged to httpx files=."""
+        route = HTTPRoute(
+            path="/upload",
+            method="POST",
+            operation_id="upload",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "multipart/form-data": {
+                        "type": "object",
+                        "properties": {"file": {"type": "string"}},
+                    }
+                },
+            ),
+            parameter_map={
+                "file": {"location": "body", "openapi_name": "file"},
+            },
+        )
+        # Tuple values represent file-like objects for httpx
+        request = director.build(route, {"file": ("report.csv", b"a,b,c")})
+        content_type = request.headers.get("content-type", "")
+        assert "multipart/form-data" in content_type
+        request.read()
+        body = request.content.decode("utf-8", errors="replace")
+        assert "report.csv" in body
+        assert "a,b,c" in body
+
+    def test_multipart_bare_bytes_not_stringified(self, director):
+        """Bare bytes values are passed directly to httpx, not repr-stringified."""
+        route = HTTPRoute(
+            path="/upload",
+            method="POST",
+            operation_id="upload_binary",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "multipart/form-data": {
+                        "type": "object",
+                        "properties": {
+                            "payload": {"type": "string", "format": "binary"},
+                        },
+                    }
+                },
+            ),
+            parameter_map={
+                "payload": {"location": "body", "openapi_name": "payload"},
+            },
+        )
+        raw = b"\x89PNG\r\n\x1a\nfake-image-data"
+        request = director.build(route, {"payload": raw})
+        content_type = request.headers.get("content-type", "")
+        assert "multipart/form-data" in content_type
+        request.read()
+        # The raw bytes should appear in the body verbatim, not as "b'\\x89PNG...'"
+        assert raw in request.content
+        assert b"b'" not in request.content
+
+    def test_json_body_still_works(self, director, json_route):
+        """application/json bodies should still be sent as JSON (regression)."""
+        request = director.build(
+            json_route,
+            {"name": "widget"},
+        )
+        content_type = request.headers.get("content-type", "")
+        assert "application/json" in content_type
+        body = json.loads(request.content.decode("utf-8"))
+        assert body == {"name": "widget"}
+
+
+class TestCookieParameters:
+    """Test that cookie parameters are properly routed."""
+
+    @pytest.fixture
+    def director(self):
+        spec = SchemaPath.from_dict(
+            {
+                "openapi": "3.0.0",
+                "info": {"title": "t", "version": "1"},
+                "paths": {},
+            }
+        )
+        return RequestDirector(spec)
+
+    @pytest.fixture
+    def cookie_route(self):
+        return HTTPRoute(
+            path="/dashboard",
+            method="GET",
+            operation_id="get_dashboard",
+            parameters=[
+                ParameterInfo(
+                    name="session_id",
+                    location="cookie",
+                    required=True,
+                    schema={"type": "string"},
+                ),
+            ],
+            parameter_map={
+                "session_id": {
+                    "location": "cookie",
+                    "openapi_name": "session_id",
+                },
+            },
+        )
+
+    def test_cookie_parameter_set_on_request(self, director, cookie_route):
+        """Cookie parameters should appear as cookies on the request."""
+        request = director.build(
+            cookie_route,
+            {"session_id": "abc123"},
+        )
+        assert "session_id" in request.headers.get("cookie", "")
+        assert "abc123" in request.headers.get("cookie", "")
+
+    def test_cookie_parameter_with_fallback_mapping(self, director):
+        """Cookie parameters should work in fallback (no parameter_map) mode."""
+        route = HTTPRoute(
+            path="/dashboard",
+            method="GET",
+            operation_id="get_dashboard",
+            parameters=[
+                ParameterInfo(
+                    name="session_id",
+                    location="cookie",
+                    required=True,
+                    schema={"type": "string"},
+                ),
+            ],
+            # No parameter_map — triggers fallback path
+        )
+        request = director.build(
+            route,
+            {"session_id": "xyz789"},
+        )
+        assert "session_id" in request.headers.get("cookie", "")
+        assert "xyz789" in request.headers.get("cookie", "")
+
+    def test_cookie_non_string_value_stringified(self, director):
+        """Non-string cookie values (e.g. int, bool) use OpenAPI serialization."""
+        route = HTTPRoute(
+            path="/api",
+            method="GET",
+            operation_id="get_api",
+            parameters=[
+                ParameterInfo(
+                    name="version",
+                    location="cookie",
+                    required=True,
+                    schema={"type": "integer"},
+                ),
+                ParameterInfo(
+                    name="debug",
+                    location="cookie",
+                    required=False,
+                    schema={"type": "boolean"},
+                ),
+            ],
+            parameter_map={
+                "version": {"location": "cookie", "openapi_name": "version"},
+                "debug": {"location": "cookie", "openapi_name": "debug"},
+            },
+        )
+        request = director.build(route, {"version": 3, "debug": True})
+        cookie = request.headers.get("cookie", "")
+        assert "version=3" in cookie
+        # Booleans use OpenAPI convention (true/false, not True/False)
+        assert "debug=true" in cookie
diff --git a/tests/utilities/openapi/test_discriminator.py b/tests/utilities/openapi/test_discriminator.py
new file mode 100644
index 0000000..f09f01d
--- /dev/null
+++ b/tests/utilities/openapi/test_discriminator.py
@@ -0,0 +1,38 @@
+from fastmcp.utilities.openapi.json_schema_converter import (
+    convert_openapi_schema_to_json_schema,
+)
+
+
+def test_discriminator_property_remains_required_when_removed():
+    schema = {
+        "oneOf": [
+            {
+                "type": "object",
+                "properties": {
+                    "kind": {"const": "comprehensive", "type": "string"},
+                },
+            },
+            {
+                "type": "object",
+                "properties": {
+                    "kind": {"const": "validate", "type": "string"},
+                    "target_id": {"type": "string"},
+                },
+                "required": ["target_id"],
+            },
+        ],
+        "discriminator": {"propertyName": "kind"},
+    }
+
+    result = convert_openapi_schema_to_json_schema(schema, "3.0.0")
+
+    assert "oneOf" not in result
+    assert "discriminator" not in result
+    for variant in result["anyOf"]:
+        assert "kind" in variant["required"]
+    validate_schema = next(
+        variant
+        for variant in result["anyOf"]
+        if variant["properties"]["kind"]["const"] == "validate"
+    )
+    assert validate_schema["required"] == ["target_id", "kind"]
diff --git a/tests/utilities/openapi/test_legacy_compatibility.py b/tests/utilities/openapi/test_legacy_compatibility.py
new file mode 100644
index 0000000..227dca2
--- /dev/null
+++ b/tests/utilities/openapi/test_legacy_compatibility.py
@@ -0,0 +1,233 @@
+"""Tests to ensure OpenAPI schema generation works correctly."""
+
+import pytest
+
+from fastmcp.utilities.openapi.models import (
+    HTTPRoute,
+    ParameterInfo,
+    RequestBodyInfo,
+)
+from fastmcp.utilities.openapi.schemas import (
+    _combine_schemas_and_map_params,
+)
+
+
+class TestSchemaGeneration:
+    """Test that OpenAPI schema generation produces correct schemas."""
+
+    def test_optional_parameter_nullable_behavior(self):
+        """Test that optional parameters are not made nullable - they can simply be omitted."""
+        route = HTTPRoute(
+            method="GET",
+            path="/test",
+            operation_id="test_op",
+            parameters=[
+                ParameterInfo(
+                    name="required_param",
+                    location="query",
+                    required=True,
+                    schema={"type": "string"},
+                ),
+                ParameterInfo(
+                    name="optional_param",
+                    location="query",
+                    required=False,
+                    schema={"type": "string"},
+                ),
+            ],
+        )
+
+        schema, _ = _combine_schemas_and_map_params(route)
+
+        # Required parameter should have simple type
+        assert schema["properties"]["required_param"]["type"] == "string"
+        assert "anyOf" not in schema["properties"]["required_param"]
+
+        # Optional parameters should preserve original schema without making it nullable
+        assert "anyOf" not in schema["properties"]["optional_param"]
+        assert schema["properties"]["optional_param"]["type"] == "string"
+
+        # Required list should only include required parameters
+        assert "required_param" in schema["required"]
+        assert "optional_param" not in schema["required"]
+
+    def test_parameter_collision_handling(self):
+        """Test that parameter collisions are handled with suffixes."""
+        route = HTTPRoute(
+            method="PUT",
+            path="/users/{id}",
+            operation_id="update_user",
+            parameters=[
+                ParameterInfo(
+                    name="id",
+                    location="path",
+                    required=True,
+                    schema={"type": "integer"},
+                )
+            ],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "object",
+                        "properties": {
+                            "id": {"type": "integer"},
+                            "name": {"type": "string"},
+                        },
+                        "required": ["name"],
+                    }
+                },
+            ),
+        )
+
+        schema, param_map = _combine_schemas_and_map_params(route)
+
+        # Should have path parameter with suffix
+        assert "id__path" in schema["properties"]
+
+        # Should have body parameter without suffix
+        assert "id" in schema["properties"]
+
+        # Should have name parameter from body
+        assert "name" in schema["properties"]
+
+        # Required should include path param (suffixed) and required body params
+        required = set(schema["required"])
+        assert "id__path" in required
+        assert "name" in required
+
+        # Parameter map should correctly map suffixed parameter
+        assert param_map["id__path"]["location"] == "path"
+        assert param_map["id__path"]["openapi_name"] == "id"
+        assert param_map["id"]["location"] == "body"
+        assert param_map["name"]["location"] == "body"
+
+    def test_non_body_parameter_collision_handling(self):
+        """Test that same-named parameters in different locations use suffixes."""
+        route = HTTPRoute(
+            method="GET",
+            path="/users/{id}",
+            operation_id="get_user",
+            parameters=[
+                ParameterInfo(
+                    name="id",
+                    location="path",
+                    required=True,
+                    schema={"type": "string"},
+                ),
+                ParameterInfo(
+                    name="id",
+                    location="query",
+                    required=False,
+                    schema={"type": "string"},
+                ),
+                ParameterInfo(
+                    name="id",
+                    location="header",
+                    required=False,
+                    schema={"type": "string"},
+                ),
+            ],
+        )
+
+        schema, param_map = _combine_schemas_and_map_params(route)
+
+        properties = schema["properties"]
+        assert "id" not in properties
+        assert "id__path" in properties
+        assert "id__query" in properties
+        assert "id__header" in properties
+
+        assert schema["required"] == ["id__path"]
+        assert param_map["id__path"] == {"location": "path", "openapi_name": "id"}
+        assert param_map["id__query"] == {"location": "query", "openapi_name": "id"}
+        assert param_map["id__header"] == {"location": "header", "openapi_name": "id"}
+
+    @pytest.mark.parametrize(
+        "param_type",
+        [
+            {"type": "integer"},
+            {"type": "number"},
+            {"type": "boolean"},
+            {"type": "array", "items": {"type": "string"}},
+            {"type": "object", "properties": {"name": {"type": "string"}}},
+        ],
+    )
+    def test_nullable_behavior_different_types(self, param_type):
+        """Test nullable behavior works for all parameter types."""
+        route = HTTPRoute(
+            method="GET",
+            path="/test",
+            operation_id="test_op",
+            parameters=[
+                ParameterInfo(
+                    name="optional_param",
+                    location="query",
+                    required=False,
+                    schema=param_type,
+                )
+            ],
+        )
+
+        schema, _ = _combine_schemas_and_map_params(route)
+
+        # Should preserve original schema without making it nullable
+        param = schema["properties"]["optional_param"]
+        assert "anyOf" not in param
+
+        # Should match the original parameter schema
+        for key, value in param_type.items():
+            assert param[key] == value
+
+    def test_no_parameters_no_body(self):
+        """Test schema generation when there are no parameters or body."""
+        route = HTTPRoute(
+            method="GET",
+            path="/health",
+            operation_id="health_check",
+        )
+
+        schema, param_map = _combine_schemas_and_map_params(route)
+
+        # Should have empty object schema
+        assert schema["type"] == "object"
+        assert schema["properties"] == {}
+        assert schema["required"] == []
+        assert param_map == {}
+
+    def test_body_only_no_parameters(self):
+        """Test schema generation with only request body, no parameters."""
+        body_schema = {
+            "application/json": {
+                "type": "object",
+                "properties": {
+                    "title": {"type": "string"},
+                    "description": {"type": "string"},
+                },
+                "required": ["title"],
+            }
+        }
+
+        route = HTTPRoute(
+            method="POST",
+            path="/items",
+            operation_id="create_item",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema=body_schema,
+            ),
+        )
+
+        schema, param_map = _combine_schemas_and_map_params(route)
+
+        # Should have body properties
+        assert "title" in schema["properties"]
+        assert "description" in schema["properties"]
+
+        # Required should match body requirements
+        assert "title" in schema["required"]
+        assert "description" not in schema["required"]
+
+        # Parameter map should map body properties
+        assert param_map["title"]["location"] == "body"
+        assert param_map["description"]["location"] == "body"
diff --git a/tests/utilities/openapi/test_models.py b/tests/utilities/openapi/test_models.py
new file mode 100644
index 0000000..4361635
--- /dev/null
+++ b/tests/utilities/openapi/test_models.py
@@ -0,0 +1,478 @@
+"""Unit tests for OpenAPI models."""
+
+import pytest
+from inline_snapshot import snapshot
+
+from fastmcp.utilities.openapi.models import (
+    HttpMethod,
+    HTTPRoute,
+    ParameterInfo,
+    ParameterLocation,
+    RequestBodyInfo,
+    ResponseInfo,
+)
+
+
+class TestParameterInfo:
+    """Test ParameterInfo model."""
+
+    def test_basic_parameter_creation(self):
+        """Test creating a basic parameter."""
+        param = ParameterInfo(
+            name="id",
+            location="path",
+            required=True,
+            schema={"type": "integer"},
+        )
+
+        assert param.name == "id"
+        assert param.location == "path"
+        assert param.required is True
+        assert param.schema_ == {"type": "integer"}
+        assert param.description is None
+        assert param.explode is None
+        assert param.style is None
+
+    def test_parameter_with_all_fields(self):
+        """Test creating parameter with all optional fields."""
+        param = ParameterInfo(
+            name="filter",
+            location="query",
+            required=False,
+            schema={"type": "object", "properties": {"name": {"type": "string"}}},
+            description="Filter criteria",
+            explode=True,
+            style="deepObject",
+        )
+
+        assert param.name == "filter"
+        assert param.location == "query"
+        assert param.required is False
+        assert param.description == "Filter criteria"
+        assert param.explode is True
+        assert param.style == "deepObject"
+
+    @pytest.mark.parametrize("location", ["path", "query", "header", "cookie"])
+    def test_valid_parameter_locations(self, location: ParameterLocation):
+        """Test that all valid parameter locations are accepted."""
+        param = ParameterInfo(
+            name="test",
+            location=location,
+            required=False,
+            schema={"type": "string"},
+        )
+        assert param.location == location
+
+    def test_parameter_defaults(self):
+        """Test parameter default values."""
+        param = ParameterInfo(
+            name="test",
+            location="query",
+            schema={"type": "string"},
+        )
+
+        # required should default to False for non-path parameters
+        assert param.required is False
+        assert param.description is None
+        assert param.explode is None
+        assert param.style is None
+
+    def test_parameter_with_empty_schema(self):
+        """Test parameter with empty schema."""
+        param = ParameterInfo(
+            name="test",
+            location="query",
+            schema={},
+        )
+
+        assert param.schema_ == {}
+
+
+class TestRequestBodyInfo:
+    """Test RequestBodyInfo model."""
+
+    def test_basic_request_body(self):
+        """Test creating a basic request body."""
+        request_body = RequestBodyInfo(
+            required=True,
+            description="User data",
+        )
+
+        assert request_body.required is True
+        assert request_body.description == "User data"
+        assert request_body.content_schema == {}
+
+    def test_request_body_with_content_schema(self):
+        """Test request body with content schema."""
+        content_schema = {
+            "application/json": {
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string"},
+                    "email": {"type": "string"},
+                },
+                "required": ["name"],
+            }
+        }
+
+        request_body = RequestBodyInfo(
+            required=True,
+            content_schema=content_schema,
+        )
+
+        assert request_body.content_schema == content_schema
+
+    def test_request_body_defaults(self):
+        """Test request body default values."""
+        request_body = RequestBodyInfo()
+
+        assert request_body.required is False
+        assert request_body.description is None
+        assert request_body.content_schema == {}
+
+    def test_request_body_multiple_content_types(self):
+        """Test request body with multiple content types."""
+        content_schema = {
+            "application/json": {
+                "type": "object",
+                "properties": {"name": {"type": "string"}},
+            },
+            "application/xml": {
+                "type": "object",
+                "properties": {"name": {"type": "string"}},
+            },
+        }
+
+        request_body = RequestBodyInfo(content_schema=content_schema)
+
+        assert len(request_body.content_schema) == 2
+        assert "application/json" in request_body.content_schema
+        assert "application/xml" in request_body.content_schema
+
+
+class TestResponseInfo:
+    """Test ResponseInfo model."""
+
+    def test_basic_response(self):
+        """Test creating a basic response."""
+        response = ResponseInfo(description="Success response")
+
+        assert response.description == "Success response"
+        assert response.content_schema == {}
+
+    def test_response_with_content_schema(self):
+        """Test response with content schema."""
+        content_schema = {
+            "application/json": {
+                "type": "object",
+                "properties": {
+                    "id": {"type": "integer"},
+                    "message": {"type": "string"},
+                },
+            }
+        }
+
+        response = ResponseInfo(
+            description="User created",
+            content_schema=content_schema,
+        )
+
+        assert response.description == "User created"
+        assert response.content_schema == content_schema
+
+    def test_response_required_description(self):
+        """Test that response description is required."""
+        # Should not raise an error - description has a default
+        response = ResponseInfo()
+        assert response.description is None
+
+
+class TestHTTPRoute:
+    """Test HTTPRoute model."""
+
+    def test_basic_route_creation(self):
+        """Test creating a basic HTTP route."""
+        route = HTTPRoute(
+            path="/users/{id}",
+            method="GET",
+            operation_id="get_user",
+        )
+
+        assert route.path == "/users/{id}"
+        assert route.method == "GET"
+        assert route.operation_id == "get_user"
+        assert route.summary is None
+        assert route.description is None
+        assert route.tags == []
+        assert route.parameters == []
+        assert route.request_body is None
+        assert route.responses == {}
+
+    def test_route_with_all_fields(self):
+        """Test creating route with all fields."""
+        parameters = [
+            ParameterInfo(
+                name="id",
+                location="path",
+                required=True,
+                schema={"type": "integer"},
+            )
+        ]
+
+        request_body = RequestBodyInfo(
+            required=True,
+            content_schema={
+                "application/json": {
+                    "type": "object",
+                    "properties": {"name": {"type": "string"}},
+                }
+            },
+        )
+
+        responses = {
+            "200": ResponseInfo(
+                description="Success",
+                content_schema={
+                    "application/json": {
+                        "type": "object",
+                        "properties": {"id": {"type": "integer"}},
+                    }
+                },
+            )
+        }
+
+        route = HTTPRoute(
+            path="/users/{id}",
+            method="PUT",
+            operation_id="update_user",
+            summary="Update user",
+            description="Update user by ID",
+            tags=["users"],
+            parameters=parameters,
+            request_body=request_body,
+            responses=responses,
+            request_schemas={"User": {"type": "object"}},
+            extensions={"x-custom": "value"},
+        )
+
+        assert route.path == "/users/{id}"
+        assert route.method == "PUT"
+        assert route.operation_id == "update_user"
+        assert route.summary == "Update user"
+        assert route.description == "Update user by ID"
+        assert route.tags == ["users"]
+        assert len(route.parameters) == 1
+        assert route.request_body is not None
+        assert "200" in route.responses
+        assert "User" in route.request_schemas
+        assert route.extensions["x-custom"] == "value"
+
+    def test_route_pre_calculated_fields(self):
+        """Test route with pre-calculated fields."""
+        route = HTTPRoute(
+            path="/test",
+            method="GET",
+            operation_id="test",
+            flat_param_schema={
+                "type": "object",
+                "properties": {"id": {"type": "integer"}},
+            },
+            parameter_map={"id": {"location": "path", "openapi_name": "id"}},
+        )
+
+        assert route.flat_param_schema["type"] == "object"
+        assert "id" in route.flat_param_schema["properties"]
+        assert "id" in route.parameter_map
+        assert route.parameter_map["id"]["location"] == "path"
+
+    @pytest.mark.parametrize(
+        "method", ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]
+    )
+    def test_valid_http_methods(self, method: HttpMethod):
+        """Test that all valid HTTP methods are accepted."""
+        route = HTTPRoute(
+            path="/test",
+            method=method,
+            operation_id="test",
+        )
+        assert route.method == method
+
+    def test_route_with_empty_collections(self):
+        """Test route with empty collections."""
+        route = HTTPRoute(
+            path="/test",
+            method="GET",
+            operation_id="test",
+            tags=[],
+            parameters=[],
+            responses={},
+            request_schemas={},
+            extensions={},
+        )
+
+        assert route.tags == []
+        assert route.parameters == []
+        assert route.responses == {}
+        assert route.request_schemas == {}
+        assert route.response_schemas == {}
+        assert route.extensions == {}
+
+    def test_route_defaults(self):
+        """Test route default values."""
+        route = HTTPRoute(
+            path="/test",
+            method="GET",
+            operation_id="test",
+        )
+
+        assert route.summary is None
+        assert route.description is None
+        assert route.tags == []
+        assert route.parameters == []
+        assert route.request_body is None
+        assert route.responses == {}
+        assert route.request_schemas == {}
+        assert route.response_schemas == {}
+        assert route.extensions == {}
+        assert route.flat_param_schema == {}
+        assert route.parameter_map == {}
+
+
+class TestModelValidation:
+    """Test model validation and error cases."""
+
+    def test_parameter_info_validation(self):
+        """Test ParameterInfo validation."""
+        # Valid parameter
+        param = ParameterInfo(
+            name="test",
+            location="query",
+            schema={"type": "string"},
+        )
+        assert param.name == "test"
+
+    def test_route_validation(self):
+        """Test HTTPRoute validation."""
+        # Valid route
+        route = HTTPRoute(
+            path="/test",
+            method="GET",
+            operation_id="test",
+        )
+        assert route.path == "/test"
+
+    def test_nested_model_validation(self):
+        """Test validation of nested models."""
+        # Create route with nested models
+        param = ParameterInfo(
+            name="id",
+            location="path",
+            required=True,
+            schema={"type": "integer"},
+        )
+
+        request_body = RequestBodyInfo(required=True)
+
+        route = HTTPRoute(
+            path="/test/{id}",
+            method="POST",
+            operation_id="test",
+            parameters=[param],
+            request_body=request_body,
+        )
+
+        assert len(route.parameters) == 1
+        assert route.parameters[0].name == "id"
+        assert route.request_body is not None
+        assert route.request_body.required is True
+
+
+class TestModelSerialization:
+    """Test model serialization and deserialization."""
+
+    def test_parameter_info_serialization(self):
+        """Test ParameterInfo serialization."""
+        param = ParameterInfo(
+            name="filter",
+            location="query",
+            required=False,
+            schema={"type": "object"},
+            description="Filter criteria",
+            explode=True,
+            style="deepObject",
+        )
+
+        # Test model_dump with alias
+        data = param.model_dump(by_alias=True)
+
+        assert data["name"] == "filter"
+        assert data["location"] == "query"
+        assert data["required"] is False
+        assert data["schema"] == {"type": "object"}  # Using alias
+        assert data["description"] == "Filter criteria"
+        assert data["explode"] is True
+        assert data["style"] == "deepObject"
+
+    def test_route_serialization(self):
+        """Test HTTPRoute serialization."""
+        param = ParameterInfo(
+            name="id",
+            location="path",
+            required=True,
+            schema={"type": "integer"},
+        )
+
+        route = HTTPRoute(
+            path="/users/{id}",
+            method="GET",
+            operation_id="get_user",
+            parameters=[param],
+        )
+
+        # Test model_dump
+        data = route.model_dump()
+
+        assert data["path"] == "/users/{id}"
+        assert data["method"] == "GET"
+        assert data["operation_id"] == "get_user"
+        assert len(data["parameters"]) == 1
+        assert data["parameters"][0]["name"] == "id"
+
+    def test_model_reconstruction(self):
+        """Test reconstructing models from serialized data."""
+        # Create original parameter
+        original_param = ParameterInfo(
+            name="test",
+            location="query",
+            schema={"type": "string"},
+            description="Test parameter",
+        )
+
+        # Serialize and reconstruct using by_alias
+        data = original_param.model_dump(by_alias=True)
+
+        data == snapshot(
+            {
+                "name": "test",
+                "location": "query",
+                "required": False,
+                "schema": {"type": "string"},
+                "description": "Test parameter",
+                "explode": None,
+                "style": None,
+            }
+        )
+
+        reconstructed_param = ParameterInfo(
+            name=data["name"],
+            location=data["location"],
+            schema=data["schema"],
+            description=data["description"],
+            explode=data["explode"],
+            style=data["style"],
+        )
+
+        assert reconstructed_param.name == original_param.name
+        assert reconstructed_param.location == original_param.location
+        assert reconstructed_param.schema_ == original_param.schema_
+        assert reconstructed_param.description == original_param.description
diff --git a/tests/utilities/openapi/test_nullable_fields.py b/tests/utilities/openapi/test_nullable_fields.py
new file mode 100644
index 0000000..ccdfe8c
--- /dev/null
+++ b/tests/utilities/openapi/test_nullable_fields.py
@@ -0,0 +1,570 @@
+"""Tests for nullable field handling in OpenAPI schemas."""
+
+import httpx
+import pytest
+from jsonschema import ValidationError, validate
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.server.providers.openapi import OpenAPIProvider
+from fastmcp.utilities.openapi.json_schema_converter import (
+    _convert_nullable_field,
+    convert_openapi_schema_to_json_schema,
+)
+
+
+class TestHandleNullableFields:
+    """Test conversion of OpenAPI nullable fields to JSON Schema format."""
+
+    def test_root_level_nullable_string(self):
+        """Test nullable string at root level."""
+        input_schema = {"type": "string", "nullable": True}
+        expected = {"type": ["string", "null"]}
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_root_level_nullable_integer(self):
+        """Test nullable integer at root level."""
+        input_schema = {"type": "integer", "nullable": True}
+        expected = {"type": ["integer", "null"]}
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_root_level_nullable_boolean(self):
+        """Test nullable boolean at root level."""
+        input_schema = {"type": "boolean", "nullable": True}
+        expected = {"type": ["boolean", "null"]}
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_property_level_nullable_fields(self):
+        """Test nullable fields in properties."""
+        input_schema = {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "company": {"type": "string", "nullable": True},
+                "age": {"type": "integer", "nullable": True},
+                "active": {"type": "boolean", "nullable": True},
+            },
+        }
+        expected = {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "company": {"type": ["string", "null"]},
+                "age": {"type": ["integer", "null"]},
+                "active": {"type": ["boolean", "null"]},
+            },
+        }
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_mixed_nullable_and_non_nullable(self):
+        """Test mix of nullable and non-nullable fields."""
+        input_schema = {
+            "type": "object",
+            "properties": {
+                "required_field": {"type": "string"},
+                "optional_nullable": {"type": "string", "nullable": True},
+                "optional_non_nullable": {"type": "string"},
+            },
+            "required": ["required_field"],
+        }
+        expected = {
+            "type": "object",
+            "properties": {
+                "required_field": {"type": "string"},
+                "optional_nullable": {"type": ["string", "null"]},
+                "optional_non_nullable": {"type": "string"},
+            },
+            "required": ["required_field"],
+        }
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_nullable_false_ignored(self):
+        """Test that nullable: false is ignored (removed but no type change)."""
+        input_schema = {"type": "string", "nullable": False}
+        expected = {"type": "string"}
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_no_nullable_field_unchanged(self):
+        """Test that schemas without nullable field are unchanged."""
+        input_schema = {
+            "type": "object",
+            "properties": {"name": {"type": "string"}},
+        }
+        expected = input_schema.copy()
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_nullable_without_type_removes_nullable(self):
+        """Test that nullable field is removed even without type."""
+        input_schema = {"nullable": True, "description": "Some field"}
+        expected = {"description": "Some field"}
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_preserves_other_fields(self):
+        """Test that other fields are preserved during conversion."""
+        input_schema = {
+            "type": "string",
+            "nullable": True,
+            "description": "A nullable string",
+            "example": "test",
+            "format": "email",
+        }
+        expected = {
+            "type": ["string", "null"],
+            "description": "A nullable string",
+            "example": "test",
+            "format": "email",
+        }
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_non_dict_input_unchanged(self):
+        """Test that non-dict inputs are returned unchanged."""
+        # These tests intentionally pass invalid types to check edge case handling
+        from typing import Any, cast
+
+        assert (
+            convert_openapi_schema_to_json_schema(cast(Any, "string"), "3.0.0")
+            == "string"
+        )
+        assert convert_openapi_schema_to_json_schema(cast(Any, 123), "3.0.0") == 123
+        assert convert_openapi_schema_to_json_schema(cast(Any, None), "3.0.0") is None
+        assert convert_openapi_schema_to_json_schema(cast(Any, [1, 2, 3]), "3.0.0") == [
+            1,
+            2,
+            3,
+        ]
+
+    def test_performance_optimization_no_copy_when_unchanged(self):
+        """Test that schemas without nullable fields return the same object (no copy)."""
+        input_schema = {
+            "type": "object",
+            "properties": {"name": {"type": "string"}},
+        }
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        # Should return the exact same object, not a copy
+        assert result is input_schema
+
+    def test_union_types_with_nullable(self):
+        """Test nullable handling with existing union types (type as array)."""
+        input_schema = {"type": ["string", "integer"], "nullable": True}
+        expected = {"type": ["string", "integer", "null"]}
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_already_nullable_union_unchanged(self):
+        """Test that union types already containing null are not modified."""
+        input_schema = {"type": ["string", "null"], "nullable": True}
+        expected = {"type": ["string", "null"]}
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_property_level_union_with_nullable(self):
+        """Test nullable handling with union types in properties."""
+        input_schema = {
+            "type": "object",
+            "properties": {"value": {"type": ["string", "integer"], "nullable": True}},
+        }
+        expected = {
+            "type": "object",
+            "properties": {"value": {"type": ["string", "integer", "null"]}},
+        }
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_complex_union_nullable_scenarios(self):
+        """Test various complex union type scenarios."""
+        # Already has null in different position
+        input1 = {"type": ["null", "string", "integer"], "nullable": True}
+        result1 = convert_openapi_schema_to_json_schema(input1, "3.0.0")
+        assert result1 == {"type": ["null", "string", "integer"]}
+
+        # Single item array
+        input2 = {"type": ["string"], "nullable": True}
+        result2 = convert_openapi_schema_to_json_schema(input2, "3.0.0")
+        assert result2 == {"type": ["string", "null"]}
+
+    def test_oneof_with_nullable(self):
+        """Test nullable handling with oneOf constructs."""
+        input_schema = {
+            "oneOf": [{"type": "string"}, {"type": "integer"}],
+            "nullable": True,
+        }
+        expected = {
+            "anyOf": [{"type": "string"}, {"type": "integer"}, {"type": "null"}]
+        }
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_anyof_with_nullable(self):
+        """Test nullable handling with anyOf constructs."""
+        input_schema = {
+            "anyOf": [{"type": "string"}, {"type": "integer"}],
+            "nullable": True,
+        }
+        expected = {
+            "anyOf": [{"type": "string"}, {"type": "integer"}, {"type": "null"}]
+        }
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_anyof_already_nullable(self):
+        """Test anyOf that already contains null type."""
+        input_schema = {
+            "anyOf": [{"type": "string"}, {"type": "null"}],
+            "nullable": True,
+        }
+        expected = {"anyOf": [{"type": "string"}, {"type": "null"}]}
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_allof_with_nullable(self):
+        """Test nullable handling with allOf constructs."""
+        input_schema = {
+            "allOf": [{"type": "string"}, {"minLength": 1}],
+            "nullable": True,
+        }
+        expected = {
+            "anyOf": [
+                {"allOf": [{"type": "string"}, {"minLength": 1}]},
+                {"type": "null"},
+            ]
+        }
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_property_level_oneof_with_nullable(self):
+        """Test nullable handling with oneOf in properties."""
+        input_schema = {
+            "type": "object",
+            "properties": {
+                "value": {
+                    "oneOf": [{"type": "string"}, {"type": "integer"}],
+                    "nullable": True,
+                }
+            },
+        }
+        expected = {
+            "type": "object",
+            "properties": {
+                "value": {
+                    "anyOf": [{"type": "string"}, {"type": "integer"}, {"type": "null"}]
+                }
+            },
+        }
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_nullable_enum_field(self):
+        """Test nullable enum field - issue #2082."""
+        input_schema = {
+            "type": "string",
+            "nullable": True,
+            "enum": ["VALUE1", "VALUE2", "VALUE3"],
+        }
+        expected = {
+            "type": ["string", "null"],
+            "enum": ["VALUE1", "VALUE2", "VALUE3", None],
+        }
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_nullable_enum_already_contains_null(self):
+        """Test nullable enum that already contains None."""
+        input_schema = {
+            "type": "string",
+            "nullable": True,
+            "enum": ["VALUE1", "VALUE2", None],
+        }
+        expected = {
+            "type": ["string", "null"],
+            "enum": ["VALUE1", "VALUE2", None],
+        }
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_nullable_enum_without_type(self):
+        """Test nullable enum without explicit type field."""
+        input_schema = {
+            "nullable": True,
+            "enum": ["VALUE1", "VALUE2", "VALUE3"],
+        }
+        expected = {
+            "enum": ["VALUE1", "VALUE2", "VALUE3", None],
+        }
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_non_nullable_enum_unchanged(self):
+        """Test that enum without nullable is unchanged."""
+        input_schema = {
+            "type": "string",
+            "enum": ["VALUE1", "VALUE2", "VALUE3"],
+        }
+        expected = {
+            "type": "string",
+            "enum": ["VALUE1", "VALUE2", "VALUE3"],
+        }
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_property_level_nullable_enum(self):
+        """Test nullable enum in object properties."""
+        input_schema = {
+            "type": "object",
+            "properties": {
+                "status": {
+                    "type": "string",
+                    "nullable": True,
+                    "enum": ["ACTIVE", "INACTIVE", "PENDING"],
+                },
+                "name": {"type": "string"},
+            },
+        }
+        expected = {
+            "type": "object",
+            "properties": {
+                "status": {
+                    "type": ["string", "null"],
+                    "enum": ["ACTIVE", "INACTIVE", "PENDING", None],
+                },
+                "name": {"type": "string"},
+            },
+        }
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_nullable_integer_enum(self):
+        """Test nullable enum with integer values."""
+        input_schema = {
+            "type": "integer",
+            "nullable": True,
+            "enum": [1, 2, 3],
+        }
+        expected = {
+            "type": ["integer", "null"],
+            "enum": [1, 2, 3, None],
+        }
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_nullable_in_definitions(self):
+        """Test nullable field inside $defs."""
+        input_schema = {
+            "type": "object",
+            "properties": {"user": {"$ref": "#/$defs/User"}},
+            "$defs": {
+                "User": {
+                    "type": "object",
+                    "properties": {
+                        "name": {"type": "string"},
+                        "bio": {"type": "string", "nullable": True},
+                    },
+                }
+            },
+        }
+        expected = {
+            "type": "object",
+            "properties": {"user": {"$ref": "#/$defs/User"}},
+            "$defs": {
+                "User": {
+                    "type": "object",
+                    "properties": {
+                        "name": {"type": "string"},
+                        "bio": {"type": ["string", "null"]},
+                    },
+                }
+            },
+        }
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+    def test_nullable_in_nested_properties(self):
+        """Test nullable field in deeply nested properties."""
+        input_schema = {
+            "type": "object",
+            "properties": {
+                "a": {
+                    "type": "object",
+                    "properties": {
+                        "b": {
+                            "type": "object",
+                            "properties": {"c": {"type": "string", "nullable": True}},
+                        }
+                    },
+                }
+            },
+        }
+        expected = {
+            "type": "object",
+            "properties": {
+                "a": {
+                    "type": "object",
+                    "properties": {
+                        "b": {
+                            "type": "object",
+                            "properties": {"c": {"type": ["string", "null"]}},
+                        }
+                    },
+                }
+            },
+        }
+        result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")
+        assert result == expected
+
+
+class TestNullableFieldValidation:
+    """Test that converted schemas validate correctly with jsonschema."""
+
+    def test_nullable_string_validates(self):
+        """Test that nullable string validates both null and string values."""
+        openapi_schema = {"type": "string", "nullable": True}
+        json_schema = convert_openapi_schema_to_json_schema(openapi_schema, "3.0.0")
+
+        # Both null and string should validate
+        validate(instance=None, schema=json_schema)
+        validate(instance="test", schema=json_schema)
+
+        # Other types should fail
+        with pytest.raises(ValidationError):
+            validate(instance=123, schema=json_schema)
+
+    def test_nullable_enum_validates(self):
+        """Test that nullable enum validates null, enum values, and rejects invalid values."""
+        openapi_schema = {
+            "type": "string",
+            "nullable": True,
+            "enum": ["VALUE1", "VALUE2", "VALUE3"],
+        }
+        json_schema = convert_openapi_schema_to_json_schema(openapi_schema, "3.0.0")
+
+        # Null and enum values should validate
+        validate(instance=None, schema=json_schema)
+        validate(instance="VALUE1", schema=json_schema)
+
+        # Invalid values should fail
+        with pytest.raises(ValidationError):
+            validate(instance="INVALID", schema=json_schema)
+
+
+class TestNullableInputSchemaIntegration:
+    """Test that nullable fields are converted in tool input schemas end-to-end.
+
+    These tests exercise the full pipeline: OpenAPI spec -> OpenAPIProvider ->
+    tool.input_schema, verifying that `nullable: true` doesn't leak through.
+    """
+
+    async def test_nullable_query_param_converted_in_tool_input_schema(self):
+        """Nullable query parameter should produce type union in tool input schema."""
+        spec = {
+            "openapi": "3.0.0",
+            "info": {"title": "Test", "version": "1.0.0"},
+            "paths": {
+                "/search": {
+                    "get": {
+                        "operationId": "search",
+                        "parameters": [
+                            {
+                                "name": "query",
+                                "in": "query",
+                                "required": True,
+                                "schema": {"type": "string"},
+                            },
+                            {
+                                "name": "category",
+                                "in": "query",
+                                "schema": {"type": "string", "nullable": True},
+                            },
+                        ],
+                        "responses": {"200": {"description": "OK"}},
+                    }
+                }
+            },
+        }
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            provider = OpenAPIProvider(openapi_spec=spec, client=client)
+            mcp = FastMCP("test")
+            mcp.add_provider(provider)
+
+            async with Client(mcp) as mcp_client:
+                tools = await mcp_client.list_tools()
+                assert len(tools) == 1
+                schema = tools[0].input_schema
+                category_prop = schema["properties"]["category"]
+                assert "nullable" not in category_prop
+                assert category_prop["type"] == ["string", "null"]
+
+    async def test_nullable_in_request_body_defs_converted(self):
+        """Nullable field inside $defs referenced by request body should be converted."""
+        spec = {
+            "openapi": "3.0.0",
+            "info": {"title": "Test", "version": "1.0.0"},
+            "paths": {
+                "/users": {
+                    "post": {
+                        "operationId": "create_user",
+                        "requestBody": {
+                            "required": True,
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "$ref": "#/components/schemas/CreateUser"
+                                    }
+                                }
+                            },
+                        },
+                        "responses": {"201": {"description": "Created"}},
+                    }
+                }
+            },
+            "components": {
+                "schemas": {
+                    "CreateUser": {
+                        "type": "object",
+                        "required": ["name"],
+                        "properties": {
+                            "name": {"type": "string"},
+                            "bio": {"type": "string", "nullable": True},
+                        },
+                    }
+                }
+            },
+        }
+        async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+            provider = OpenAPIProvider(openapi_spec=spec, client=client)
+            mcp = FastMCP("test")
+            mcp.add_provider(provider)
+
+            async with Client(mcp) as mcp_client:
+                tools = await mcp_client.list_tools()
+                assert len(tools) == 1
+                schema = tools[0].input_schema
+
+                # Find the bio property — it may be inline or in $defs
+                if "$defs" in schema:
+                    # Resolve through $defs
+                    user_schema = next(iter(schema["$defs"].values()))
+                    bio_prop = user_schema["properties"]["bio"]
+                else:
+                    bio_prop = schema["properties"]["bio"]
+
+                assert "nullable" not in bio_prop
+                assert bio_prop["type"] == ["string", "null"]
+
+
+class TestConvertNullableFieldMutation:
+    """Test that _convert_nullable_field does not mutate its input."""
+
+    def test_does_not_mutate_anyof_list(self):
+        """_convert_nullable_field should not append to the original anyOf list."""
+        schema = {"anyOf": [{"type": "string"}], "nullable": True}
+        original_len = len(schema["anyOf"])
+        _convert_nullable_field(schema)
+        assert len(schema["anyOf"]) == original_len
diff --git a/tests/utilities/openapi/test_parser.py b/tests/utilities/openapi/test_parser.py
new file mode 100644
index 0000000..a281c71
--- /dev/null
+++ b/tests/utilities/openapi/test_parser.py
@@ -0,0 +1,460 @@
+"""Unit tests for OpenAPI parser."""
+
+import pytest
+
+from fastmcp.utilities.openapi.parser import parse_openapi_to_http_routes
+
+
+class TestOpenAPIParser:
+    """Test OpenAPI parsing functionality."""
+
+    def test_parse_basic_openapi_30(self, basic_openapi_30_spec):
+        """Test parsing a basic OpenAPI 3.0 spec."""
+        routes = parse_openapi_to_http_routes(basic_openapi_30_spec)
+
+        assert len(routes) == 1
+        route = routes[0]
+
+        assert route.path == "/users/{id}"
+        assert route.method == "GET"
+        assert route.operation_id == "get_user"
+        assert route.summary == "Get user by ID"
+
+        # Check parameters
+        assert len(route.parameters) == 1
+        param = route.parameters[0]
+        assert param.name == "id"
+        assert param.location == "path"
+        assert param.required is True
+        assert param.schema_["type"] == "integer"
+
+        # Check pre-calculated fields
+        assert hasattr(route, "flat_param_schema")
+        assert hasattr(route, "parameter_map")
+        assert route.flat_param_schema is not None
+        assert route.parameter_map is not None
+
+    def test_parse_basic_openapi_31(self, basic_openapi_31_spec):
+        """Test parsing a basic OpenAPI 3.1 spec."""
+        routes = parse_openapi_to_http_routes(basic_openapi_31_spec)
+
+        assert len(routes) == 1
+        route = routes[0]
+
+        assert route.path == "/users/{id}"
+        assert route.method == "GET"
+        assert route.operation_id == "get_user"
+
+        # Same structure should work for both 3.0 and 3.1
+        assert len(route.parameters) == 1
+        param = route.parameters[0]
+        assert param.name == "id"
+        assert param.location == "path"
+
+    def test_parse_collision_spec(self, collision_spec):
+        """Test parsing spec with parameter collisions."""
+        routes = parse_openapi_to_http_routes(collision_spec)
+
+        assert len(routes) == 1
+        route = routes[0]
+
+        assert route.operation_id == "update_user"
+
+        # Should have path parameter
+        path_params = [p for p in route.parameters if p.location == "path"]
+        assert len(path_params) == 1
+        assert path_params[0].name == "id"
+
+        # Should have request body
+        assert route.request_body is not None
+        assert route.request_body.required is True
+
+        # Check that parameter map handles collisions
+        assert route.parameter_map is not None
+        # Should have entries for both path and body parameters
+        assert len(route.parameter_map) >= 2  # At least path id and body fields
+
+    def test_parse_deepobject_spec(self, deepobject_spec):
+        """Test parsing spec with deepObject parameters."""
+        routes = parse_openapi_to_http_routes(deepobject_spec)
+
+        assert len(routes) == 1
+        route = routes[0]
+
+        assert route.operation_id == "search"
+
+        # Should have deepObject parameter
+        assert len(route.parameters) == 1
+        param = route.parameters[0]
+        assert param.name == "filter"
+        assert param.location == "query"
+        assert param.style == "deepObject"
+        assert param.explode is True
+        assert param.schema_["type"] == "object"
+
+    def test_parse_complex_spec(self, complex_spec):
+        """Test parsing complex spec with multiple parameter types."""
+        routes = parse_openapi_to_http_routes(complex_spec)
+
+        assert len(routes) == 1
+        route = routes[0]
+
+        assert route.operation_id == "update_item"
+
+        # Should have multiple parameters
+        assert len(route.parameters) == 3
+
+        # Check parameter locations
+        locations = {p.location for p in route.parameters}
+        assert locations == {"path", "query", "header"}
+
+        # Check specific parameters
+        path_param = next(p for p in route.parameters if p.location == "path")
+        assert path_param.name == "id"
+        assert path_param.required is True
+
+        query_param = next(p for p in route.parameters if p.location == "query")
+        assert query_param.name == "version"
+        assert query_param.required is False
+        assert query_param.schema_.get("default") == 1
+
+        header_param = next(p for p in route.parameters if p.location == "header")
+        assert header_param.name == "X-Client-Version"
+        assert header_param.required is False
+
+        # Check request body
+        assert route.request_body is not None
+        assert route.request_body.required is True
+
+    def test_parse_empty_spec(self):
+        """Test parsing spec with no paths."""
+        empty_spec = {
+            "openapi": "3.0.0",
+            "info": {"title": "Empty API", "version": "1.0.0"},
+            "paths": {},
+        }
+
+        routes = parse_openapi_to_http_routes(empty_spec)
+        assert len(routes) == 0
+
+    def test_parse_invalid_spec(self):
+        """Test parsing invalid OpenAPI spec."""
+        invalid_spec = {
+            "openapi": "3.0.0",
+            # Missing required fields
+        }
+
+        with pytest.raises(ValueError, match="Invalid OpenAPI schema"):
+            parse_openapi_to_http_routes(invalid_spec)
+
+    def test_parse_spec_with_refs(self):
+        """Test parsing spec with $ref references."""
+        spec_with_refs = {
+            "openapi": "3.0.0",
+            "info": {"title": "Ref Test API", "version": "1.0.0"},
+            "components": {
+                "schemas": {
+                    "User": {
+                        "type": "object",
+                        "properties": {
+                            "id": {"type": "integer"},
+                            "name": {"type": "string"},
+                        },
+                    }
+                },
+                "parameters": {
+                    "UserId": {
+                        "name": "id",
+                        "in": "path",
+                        "required": True,
+                        "schema": {"type": "integer"},
+                    }
+                },
+            },
+            "paths": {
+                "/users/{id}": {
+                    "get": {
+                        "operationId": "get_user",
+                        "parameters": [{"$ref": "#/components/parameters/UserId"}],
+                        "responses": {
+                            "200": {
+                                "description": "User",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {"$ref": "#/components/schemas/User"}
+                                    }
+                                },
+                            }
+                        },
+                    }
+                }
+            },
+        }
+
+        routes = parse_openapi_to_http_routes(spec_with_refs)
+
+        assert len(routes) == 1
+        route = routes[0]
+
+        # Parameter should be resolved from $ref
+        assert len(route.parameters) == 1
+        param = route.parameters[0]
+        assert param.name == "id"
+        assert param.location == "path"
+        assert param.required is True
+
+    def test_parse_simple_transitive_refs(self):
+        """Test that A->B->C transitive references are preserved.
+
+        When a request body references schema A, which references B, which references C:
+        - A is expanded inline (expected optimization)
+        - B and C MUST be included in $defs (the bug fix for #1372)
+        """
+        spec = {
+            "openapi": "3.0.0",
+            "info": {"title": "Test", "version": "1.0.0"},
+            "components": {
+                "schemas": {
+                    "SchemaA": {
+                        "type": "object",
+                        "properties": {
+                            "refToB": {"$ref": "#/components/schemas/SchemaB"}
+                        },
+                    },
+                    "SchemaB": {
+                        "type": "object",
+                        "properties": {
+                            "refToC": {"$ref": "#/components/schemas/SchemaC"}
+                        },
+                    },
+                    "SchemaC": {
+                        "type": "string",
+                        "enum": ["value1", "value2"],
+                    },
+                }
+            },
+            "paths": {
+                "/test": {
+                    "post": {
+                        "operationId": "test_op",
+                        "requestBody": {
+                            "content": {
+                                "application/json": {
+                                    "schema": {"$ref": "#/components/schemas/SchemaA"}
+                                }
+                            }
+                        },
+                        "responses": {"200": {"description": "OK"}},
+                    }
+                }
+            },
+        }
+
+        routes = parse_openapi_to_http_routes(spec)
+        route = routes[0]
+
+        # SchemaA is expanded inline, so it's NOT in request_schemas
+        assert "SchemaA" not in route.request_schemas
+
+        # But SchemaB and SchemaC MUST be there (transitive dependencies)
+        assert "SchemaB" in route.request_schemas
+        assert "SchemaC" in route.request_schemas
+
+        # Same in the flat parameter schema
+        assert "SchemaB" in route.flat_param_schema["$defs"]
+        assert "SchemaC" in route.flat_param_schema["$defs"]
+
+    def test_parse_tspicer_issue_1372(self):
+        """Reproduce the exact bug from issue #1372 (tspicer's report).
+
+        Issue: Profile -> {countryCode, AccountInfo} transitive refs were missing from $defs.
+        """
+        spec = {
+            "openapi": "3.0.1",
+            "info": {"title": "Test", "version": "1.0.0"},
+            "components": {
+                "schemas": {
+                    "Profile": {
+                        "type": "object",
+                        "properties": {
+                            "profileId": {"type": "integer"},
+                            "countryCode": {"$ref": "#/components/schemas/countryCode"},
+                            "accountInfo": {"$ref": "#/components/schemas/AccountInfo"},
+                        },
+                    },
+                    "countryCode": {
+                        "type": "string",
+                        "enum": ["US", "UK", "CA", "AU"],
+                    },
+                    "AccountInfo": {
+                        "type": "object",
+                        "properties": {
+                            "accountId": {"type": "string"},
+                            "accountType": {"type": "string"},
+                        },
+                    },
+                }
+            },
+            "paths": {
+                "/profile": {
+                    "post": {
+                        "operationId": "create_profile",
+                        "requestBody": {
+                            "content": {
+                                "application/json": {
+                                    "schema": {"$ref": "#/components/schemas/Profile"}
+                                }
+                            },
+                        },
+                        "responses": {"200": {"description": "OK"}},
+                    }
+                }
+            },
+        }
+
+        routes = parse_openapi_to_http_routes(spec)
+        route = routes[0]
+
+        # Profile is expanded inline, NOT in schema_defs
+        assert "Profile" not in route.request_schemas
+
+        # Bug fix: countryCode and AccountInfo MUST be in schema_defs
+        assert "countryCode" in route.request_schemas  # Was missing in #1372
+        assert "AccountInfo" in route.request_schemas  # Was missing in #1372
+
+        # Same in flat parameter schema
+        assert "countryCode" in route.flat_param_schema["$defs"]
+        assert "AccountInfo" in route.flat_param_schema["$defs"]
+
+        # Verify Profile's properties were inlined correctly
+        props = route.flat_param_schema["properties"]
+        assert "profileId" in props
+        assert props["countryCode"]["$ref"] == "#/$defs/countryCode"
+        assert props["accountInfo"]["$ref"] == "#/$defs/AccountInfo"
+
+    def test_parameter_schema_extraction(self, complex_spec):
+        """Test that parameter schemas are properly extracted."""
+        routes = parse_openapi_to_http_routes(complex_spec)
+        route = routes[0]
+
+        # Check that flat_param_schema contains all parameters
+        flat_schema = route.flat_param_schema
+        assert flat_schema["type"] == "object"
+        assert "properties" in flat_schema
+
+        properties = flat_schema["properties"]
+
+        # Should contain path, query, and body parameters
+        assert "id" in properties or any("id" in key for key in properties.keys())
+        assert "title" in properties  # From request body
+
+        # Check parameter mapping
+        param_map = route.parameter_map
+        assert len(param_map) > 0
+
+        # Each mapped parameter should have location and openapi_name
+        for param_name, mapping in param_map.items():
+            assert "location" in mapping
+            assert "openapi_name" in mapping
+            assert mapping["location"] in ["path", "query", "header", "body"]
+
+
+class TestParameterLocationHandling:
+    """Test parameter location conversion and handling."""
+
+    @pytest.mark.parametrize(
+        "location_str,expected",
+        [
+            ("path", "path"),
+            ("query", "query"),
+            ("header", "header"),
+            ("cookie", "cookie"),
+            ("unknown", "query"),  # Should default to query
+        ],
+    )
+    def test_parameter_location_conversion(self, location_str, expected):
+        """Test parameter location string conversion."""
+        # Create a simple spec with the parameter location
+        spec = {
+            "openapi": "3.0.0",
+            "info": {"title": "Location Test", "version": "1.0.0"},
+            "paths": {
+                "/test": {
+                    "get": {
+                        "operationId": "test_op",
+                        "parameters": [
+                            {
+                                "name": "test_param",
+                                "in": location_str,
+                                "schema": {"type": "string"},
+                            }
+                        ],
+                        "responses": {"200": {"description": "OK"}},
+                    }
+                }
+            },
+        }
+
+        if location_str == "unknown":
+            # Should raise validation error for unknown location
+            with pytest.raises(ValueError, match="Invalid OpenAPI schema"):
+                parse_openapi_to_http_routes(spec)
+        else:
+            routes = parse_openapi_to_http_routes(spec)
+            route = routes[0]
+            param = route.parameters[0]
+            assert param.location == expected
+
+
+class TestErrorHandling:
+    """Test error handling in parser."""
+
+    def test_external_ref_error(self):
+        """Test that external references are handled gracefully."""
+        spec_with_external_ref = {
+            "openapi": "3.0.0",
+            "info": {"title": "External Ref Test", "version": "1.0.0"},
+            "paths": {
+                "/test": {
+                    "get": {
+                        "operationId": "test_op",
+                        "parameters": [
+                            {
+                                "$ref": "external-file.yaml#/components/parameters/ExternalParam"
+                            }
+                        ],
+                        "responses": {"200": {"description": "OK"}},
+                    }
+                }
+            },
+        }
+
+        # Should not crash but skip the invalid parameter
+        routes = parse_openapi_to_http_routes(spec_with_external_ref)
+        assert len(routes) == 1
+        assert (
+            len(routes[0].parameters) == 0
+        )  # External ref parameter should be skipped
+
+    def test_broken_ref_error(self):
+        """Test that broken internal references are handled gracefully."""
+        spec_with_broken_ref = {
+            "openapi": "3.0.0",
+            "info": {"title": "Broken Ref Test", "version": "1.0.0"},
+            "paths": {
+                "/test": {
+                    "get": {
+                        "operationId": "test_op",
+                        "parameters": [
+                            {"$ref": "#/components/parameters/NonExistentParam"}
+                        ],
+                        "responses": {"200": {"description": "OK"}},
+                    }
+                }
+            },
+        }
+
+        # Should handle broken refs gracefully and continue parsing
+        routes = parse_openapi_to_http_routes(spec_with_broken_ref)
+        # May have empty routes or skip the broken operation
+        assert isinstance(routes, list)
diff --git a/tests/utilities/openapi/test_propertynames_ref_rewrite.py b/tests/utilities/openapi/test_propertynames_ref_rewrite.py
new file mode 100644
index 0000000..8093634
--- /dev/null
+++ b/tests/utilities/openapi/test_propertynames_ref_rewrite.py
@@ -0,0 +1,34 @@
+from fastmcp.utilities.openapi.schemas import _replace_ref_with_defs
+
+
+def test_replace_ref_with_defs_rewrites_propertyNames_ref():
+    """
+    Regression test for issue #3303.
+
+    When using dict[StrEnum, Model], Pydantic generates:
+
+        {
+            "type": "object",
+            "propertyNames": {"$ref": "#/components/schemas/Category"},
+            "additionalProperties": {"$ref": "#/components/schemas/ItemInfo"}
+        }
+
+    _replace_ref_with_defs should rewrite BOTH refs to #/$defs/.
+    """
+
+    schema = {
+        "type": "object",
+        "propertyNames": {"$ref": "#/components/schemas/Category"},
+        "additionalProperties": {"$ref": "#/components/schemas/ItemInfo"},
+    }
+
+    result = _replace_ref_with_defs(schema)
+
+    # additionalProperties ref is rewritten
+    assert result["additionalProperties"]["$ref"] == "#/$defs/ItemInfo"
+
+    # propertyNames ref must also be rewritten (this was the bug)
+    assert result["propertyNames"]["$ref"] == "#/$defs/Category"
+
+    # Ensure no dangling OpenAPI refs remain
+    assert "#/components/schemas/" not in str(result)
diff --git a/tests/utilities/openapi/test_schemas.py b/tests/utilities/openapi/test_schemas.py
new file mode 100644
index 0000000..ceac2bd
--- /dev/null
+++ b/tests/utilities/openapi/test_schemas.py
@@ -0,0 +1,644 @@
+"""Unit tests for schema processing and parameter mapping."""
+
+import pytest
+
+from fastmcp.utilities.json_schema import compress_schema
+from fastmcp.utilities.openapi.models import (
+    HTTPRoute,
+    ParameterInfo,
+    RequestBodyInfo,
+)
+from fastmcp.utilities.openapi.schemas import (
+    _combine_schemas,
+    _combine_schemas_and_map_params,
+    _replace_ref_with_defs,
+)
+
+
+class TestSchemaProcessing:
+    """Test schema processing utilities."""
+
+    @pytest.fixture
+    def simple_route(self):
+        """Create a simple route for testing."""
+        return HTTPRoute(
+            path="/users/{id}",
+            method="GET",
+            operation_id="get_user",
+            parameters=[
+                ParameterInfo(
+                    name="id",
+                    location="path",
+                    required=True,
+                    schema={"type": "integer"},
+                )
+            ],
+        )
+
+    @pytest.fixture
+    def collision_route(self):
+        """Create a route with parameter name collisions."""
+        return HTTPRoute(
+            path="/users/{id}",
+            method="PUT",
+            operation_id="update_user",
+            parameters=[
+                ParameterInfo(
+                    name="id",
+                    location="path",
+                    required=True,
+                    schema={"type": "integer"},
+                    description="User ID in path",
+                )
+            ],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "object",
+                        "properties": {
+                            "id": {"type": "integer", "description": "User ID in body"},
+                            "name": {"type": "string"},
+                            "email": {"type": "string"},
+                        },
+                        "required": ["name"],
+                    }
+                },
+            ),
+        )
+
+    @pytest.fixture
+    def complex_route(self):
+        """Create a complex route with multiple parameter types."""
+        return HTTPRoute(
+            path="/items/{id}",
+            method="PATCH",
+            operation_id="update_item",
+            parameters=[
+                ParameterInfo(
+                    name="id",
+                    location="path",
+                    required=True,
+                    schema={"type": "string"},
+                ),
+                ParameterInfo(
+                    name="version",
+                    location="query",
+                    required=False,
+                    schema={"type": "integer", "default": 1},
+                ),
+                ParameterInfo(
+                    name="X-Client-Version",
+                    location="header",
+                    required=False,
+                    schema={"type": "string"},
+                ),
+            ],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "object",
+                        "properties": {
+                            "title": {"type": "string"},
+                            "description": {"type": "string"},
+                            "tags": {
+                                "type": "array",
+                                "items": {"type": "string"},
+                            },
+                        },
+                        "required": ["title"],
+                    }
+                },
+            ),
+        )
+
+    def test_combine_schemas_simple(self, simple_route):
+        """Test combining schemas for a simple route."""
+        combined_schema = _combine_schemas(simple_route)
+
+        assert combined_schema["type"] == "object"
+        assert "properties" in combined_schema
+
+        properties = combined_schema["properties"]
+        assert "id" in properties
+        assert properties["id"]["type"] == "integer"
+
+        required = combined_schema.get("required", [])
+        assert "id" in required
+
+    def test_combine_schemas_with_collisions(self, collision_route):
+        """Test combining schemas with parameter name collisions."""
+        combined_schema = _combine_schemas(collision_route)
+
+        assert combined_schema["type"] == "object"
+        properties = combined_schema["properties"]
+
+        # Should handle collision by suffixing
+        id_params = [key for key in properties.keys() if "id" in key]
+        assert len(id_params) >= 2  # Should have both path and body id
+
+        # Should have other body parameters
+        assert "name" in properties
+        assert "email" in properties
+
+    def test_combine_schemas_complex(self, complex_route):
+        """Test combining schemas for complex route."""
+        combined_schema = _combine_schemas(complex_route)
+
+        properties = combined_schema["properties"]
+
+        # Should have path parameter
+        assert "id" in properties
+
+        # Should have query parameter
+        assert "version" in properties
+        assert properties["version"].get("default") == 1
+
+        # Should have header parameter
+        assert "X-Client-Version" in properties
+
+        # Should have body parameters
+        assert "title" in properties
+        assert "description" in properties
+        assert "tags" in properties
+
+        # Check required fields
+        required = combined_schema.get("required", [])
+        assert "id" in required  # Path parameters are required
+        assert "title" in required  # Required body parameter
+
+    def test_combine_schemas_and_map_params_simple(self, simple_route):
+        """Test combining schemas and creating parameter map."""
+        combined_schema, param_map = _combine_schemas_and_map_params(simple_route)
+
+        # Check schema
+        assert combined_schema["type"] == "object"
+        assert "id" in combined_schema["properties"]
+
+        # Check parameter map
+        assert len(param_map) == 1
+        assert "id" in param_map
+        assert param_map["id"]["location"] == "path"
+        assert param_map["id"]["openapi_name"] == "id"
+
+    def test_combine_schemas_and_map_params_with_collisions(self, collision_route):
+        """Test parameter mapping with collisions."""
+        combined_schema, param_map = _combine_schemas_and_map_params(collision_route)
+
+        # Check that we have entries for both conflicting parameters
+        path_id_key = None
+        body_id_key = None
+
+        for key, mapping in param_map.items():
+            if mapping["location"] == "path" and mapping["openapi_name"] == "id":
+                path_id_key = key
+            elif mapping["location"] == "body" and mapping["openapi_name"] == "id":
+                body_id_key = key
+
+        assert path_id_key is not None
+        assert body_id_key is not None
+        assert path_id_key != body_id_key  # Should be different keys
+
+        # Both should exist in schema
+        assert path_id_key in combined_schema["properties"]
+        assert body_id_key in combined_schema["properties"]
+
+        # Should also have non-conflicting parameters
+        assert "name" in param_map
+        assert "email" in param_map
+
+    def test_combine_schemas_and_map_params_complex(self, complex_route):
+        """Test parameter mapping for complex route."""
+        combined_schema, param_map = _combine_schemas_and_map_params(complex_route)
+
+        # Should have all parameters mapped
+        actual_locations = {mapping["location"] for mapping in param_map.values()}
+
+        # Should have representatives from each location
+        assert "path" in actual_locations
+        assert "body" in actual_locations
+        # May or may not have query/header depending on whether they're included
+
+        # Check specific mappings
+        id_mapping = param_map["id"]
+        assert id_mapping["location"] == "path"
+        assert id_mapping["openapi_name"] == "id"
+
+        title_mapping = param_map["title"]
+        assert title_mapping["location"] == "body"
+        assert title_mapping["openapi_name"] == "title"
+
+    def test_replace_ref_with_defs(self):
+        """Test replacing $ref with $defs for JSON Schema compatibility."""
+
+        schema_with_ref = {
+            "type": "object",
+            "properties": {
+                "user": {"$ref": "#/components/schemas/User"},
+                "items": {
+                    "type": "array",
+                    "items": {"$ref": "#/components/schemas/Item"},
+                },
+            },
+        }
+
+        # Use our recursive replacement approach
+        result = _replace_ref_with_defs(schema_with_ref)
+
+        assert result["properties"]["user"]["$ref"] == "#/$defs/User"
+        assert result["properties"]["items"]["items"]["$ref"] == "#/$defs/Item"
+
+    def test_replace_ref_with_defs_nested(self):
+        """Test replacing $ref in deeply nested structures."""
+
+        nested_schema = {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "nested": {"$ref": "#/components/schemas/Nested"},
+                    },
+                },
+                "items": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "ref_prop": {"$ref": "#/components/schemas/RefProp"},
+                        },
+                    },
+                },
+            },
+        }
+
+        # Use our recursive replacement approach
+        result = _replace_ref_with_defs(nested_schema)
+
+        # Check nested object property
+        nested_prop = result["properties"]["data"]["properties"]["nested"]
+        assert nested_prop["$ref"] == "#/$defs/Nested"
+
+        # Check array item property
+        array_item_prop = result["properties"]["items"]["items"]["properties"][
+            "ref_prop"
+        ]
+        assert array_item_prop["$ref"] == "#/$defs/RefProp"
+
+    def test_replace_ref_with_defs_in_additional_properties(self):
+        """Test replacing $ref deeply in 'additionalProperties'."""
+
+        add_props_schema = {
+            "description": "An invoice with a fixed header and a flexible set of line items.",
+            "type": "object",
+            "properties": {
+                "invoice_number": {
+                    "type": "string",
+                    "description": "The unique identifier for the invoice.",
+                },
+                "customer_name": {
+                    "type": "string",
+                    "description": "The name of the customer.",
+                },
+                "total_amount": {
+                    "type": "number",
+                    "description": "The total amount of the invoice.",
+                },
+            },
+            "required": ["invoice_number", "customer_name", "total_amount"],
+            "additionalProperties": {"$ref": "#/components/schemas/Link"},
+        }
+
+        # Use our recursive replacement approach
+        result = _replace_ref_with_defs(add_props_schema)
+
+        # Check additional properties
+        add_props = result["additionalProperties"]
+        assert add_props["$ref"] == "#/$defs/Link"
+
+    def test_replace_ref_with_defs_with_bool_additional_properties(self):
+        """Test replacing a bool 'additionalProperties'."""
+
+        add_props_schema = {
+            "description": "An invoice with a fixed header and a flexible set of line items.",
+            "type": "object",
+            "properties": {
+                "invoice_number": {
+                    "type": "string",
+                    "description": "The unique identifier for the invoice.",
+                },
+                "customer_name": {
+                    "type": "string",
+                    "description": "The name of the customer.",
+                },
+                "total_amount": {
+                    "type": "number",
+                    "description": "The total amount of the invoice.",
+                },
+            },
+            "required": ["invoice_number", "customer_name", "total_amount"],
+            "additionalProperties": False,
+        }
+
+        # Use our recursive replacement approach
+        result = _replace_ref_with_defs(add_props_schema)
+
+        # Check additional properties
+        add_props = result["additionalProperties"]
+        assert add_props is False
+
+    def test_replace_ref_with_defs_with_inner_schema_additional_properties(self):
+        """Test replacing a inner schema 'additionalProperties'."""
+
+        add_props_schema = {
+            "description": "An invoice with a fixed header and a flexible set of line items.",
+            "type": "object",
+            "properties": {
+                "invoice_number": {
+                    "type": "string",
+                    "description": "The unique identifier for the invoice.",
+                },
+                "customer_name": {
+                    "type": "string",
+                    "description": "The name of the customer.",
+                },
+                "total_amount": {
+                    "type": "number",
+                    "description": "The total amount of the invoice.",
+                },
+            },
+            "required": ["invoice_number", "customer_name", "total_amount"],
+            "additionalProperties": {
+                "type": "integer",
+                "format": "int32",
+                "description": "The total amount of the invoice.",
+            },
+        }
+
+        # Use our recursive replacement approach
+        result = _replace_ref_with_defs(add_props_schema)
+
+        # Check additional properties
+        add_props = result["additionalProperties"]
+        assert add_props == {
+            "type": "integer",
+            "format": "int32",
+            "description": "The total amount of the invoice.",
+        }
+
+    def test_parameter_collision_suffixing_logic(self):
+        """Test the specific logic for parameter collision suffixing."""
+        # Create a route that would definitely cause collisions
+        route = HTTPRoute(
+            path="/test/{id}",
+            method="POST",
+            operation_id="test_collision",
+            parameters=[
+                ParameterInfo(
+                    name="id", location="path", required=True, schema={"type": "string"}
+                ),
+                ParameterInfo(
+                    name="name",
+                    location="query",
+                    required=False,
+                    schema={"type": "string"},
+                ),
+                ParameterInfo(
+                    name="name",
+                    location="header",
+                    required=False,
+                    schema={"type": "string"},
+                ),
+            ],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "object",
+                        "properties": {
+                            "id": {"type": "integer"},
+                            "name": {"type": "string"},
+                            "description": {"type": "string"},
+                        },
+                    }
+                },
+            ),
+        )
+
+        combined_schema, param_map = _combine_schemas_and_map_params(route)
+
+        # Check that all parameters are included with unique keys
+        param_keys = list(param_map.keys())
+        assert len(param_keys) == len(set(param_keys))  # All keys should be unique
+
+        # Should have some form of id and name parameters
+        id_keys = [key for key in param_keys if "id" in key]
+        name_keys = [key for key in param_keys if "name" in key]
+
+        assert len(id_keys) >= 2  # Path id and body id
+        assert len(name_keys) >= 3  # Query name, header name, and body name
+
+        # Check that locations are correctly mapped
+        path_params = [
+            key for key, mapping in param_map.items() if mapping["location"] == "path"
+        ]
+        query_params = [
+            key for key, mapping in param_map.items() if mapping["location"] == "query"
+        ]
+        header_params = [
+            key for key, mapping in param_map.items() if mapping["location"] == "header"
+        ]
+        body_params = [
+            key for key, mapping in param_map.items() if mapping["location"] == "body"
+        ]
+
+        assert len(path_params) == 1
+        assert len(query_params) == 1
+        assert len(header_params) == 1
+        assert len(body_params) >= 3  # id, name, description from body
+
+
+class TestEdgeCases:
+    """Test edge cases in schema processing."""
+
+    def test_empty_route(self):
+        """Test schema processing with empty route."""
+        empty_route = HTTPRoute(
+            path="/empty",
+            method="GET",
+            operation_id="empty_op",
+            parameters=[],
+        )
+
+        combined_schema = _combine_schemas(empty_route)
+
+        assert combined_schema["type"] == "object"
+        assert combined_schema["properties"] == {}
+        assert combined_schema.get("required", []) == []
+
+    def test_route_without_request_body(self):
+        """Test route with only parameters, no request body."""
+        route = HTTPRoute(
+            path="/test/{id}",
+            method="GET",
+            operation_id="test_get",
+            parameters=[
+                ParameterInfo(
+                    name="id", location="path", required=True, schema={"type": "string"}
+                ),
+                ParameterInfo(
+                    name="filter",
+                    location="query",
+                    required=False,
+                    schema={"type": "string"},
+                ),
+            ],
+        )
+
+        combined_schema, param_map = _combine_schemas_and_map_params(route)
+
+        assert "id" in combined_schema["properties"]
+        assert "filter" in combined_schema["properties"]
+        assert len(param_map) == 2
+
+    def test_route_with_only_request_body(self):
+        """Test route with only request body, no parameters."""
+        route = HTTPRoute(
+            path="/create",
+            method="POST",
+            operation_id="create_item",
+            parameters=[],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "object",
+                        "properties": {
+                            "name": {"type": "string"},
+                            "description": {"type": "string"},
+                        },
+                        "required": ["name"],
+                    }
+                },
+            ),
+        )
+
+        combined_schema, param_map = _combine_schemas_and_map_params(route)
+
+        assert "name" in combined_schema["properties"]
+        assert "description" in combined_schema["properties"]
+        assert "name" in combined_schema["required"]
+        assert len(param_map) == 2
+
+    def test_parameter_without_schema(self):
+        """Test handling parameters without schema."""
+        # Use minimal schema to avoid validation error
+        route = HTTPRoute(
+            path="/test",
+            method="GET",
+            operation_id="test_no_schema",
+            parameters=[
+                ParameterInfo(
+                    name="param1", location="query", required=False, schema={}
+                ),  # Empty schema
+            ],
+        )
+
+        combined_schema, param_map = _combine_schemas_and_map_params(route)
+
+        # Should handle gracefully
+        assert combined_schema["type"] == "object"
+        assert isinstance(param_map, dict)
+
+    def test_request_body_multiple_content_types(self):
+        """Test request body with multiple content types."""
+        route = HTTPRoute(
+            path="/upload",
+            method="POST",
+            operation_id="upload_file",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "object",
+                        "properties": {"metadata": {"type": "string"}},
+                    },
+                    "multipart/form-data": {
+                        "type": "object",
+                        "properties": {"file": {"type": "string", "format": "binary"}},
+                    },
+                },
+            ),
+        )
+
+        combined_schema, param_map = _combine_schemas_and_map_params(route)
+
+        # Should use the first content type found
+        properties = combined_schema["properties"]
+        assert (
+            len(properties) > 0
+        )  # Should have some properties from one of the content types
+
+    def test_oneof_reference_dereferenced(self):
+        """Test that schemas referenced in oneOf are preserved and unused defs pruned."""
+
+        schema = {
+            "type": "object",
+            "properties": {"data": {"oneOf": [{"$ref": "#/$defs/TestSchema"}]}},
+            "$defs": {
+                "TestSchema": {"type": "string"},
+                "UnusedSchema": {"type": "number"},
+            },
+        }
+
+        result = compress_schema(schema)
+
+        # UnusedSchema should be pruned, TestSchema should be kept
+        assert "UnusedSchema" not in result.get("$defs", {})
+        assert result["$defs"]["TestSchema"] == {"type": "string"}
+
+        # $ref should be preserved in oneOf
+        assert result["properties"]["data"]["oneOf"] == [{"$ref": "#/$defs/TestSchema"}]
+
+    def test_anyof_reference_dereferenced(self):
+        """Test that schemas referenced in anyOf are preserved and unused defs pruned."""
+
+        schema = {
+            "type": "object",
+            "properties": {"data": {"anyOf": [{"$ref": "#/$defs/TestSchema"}]}},
+            "$defs": {
+                "TestSchema": {"type": "string"},
+                "UnusedSchema": {"type": "number"},
+            },
+        }
+
+        result = compress_schema(schema)
+
+        # UnusedSchema should be pruned, TestSchema should be kept
+        assert "UnusedSchema" not in result.get("$defs", {})
+        assert result["$defs"]["TestSchema"] == {"type": "string"}
+
+        # $ref should be preserved in anyOf
+        assert result["properties"]["data"]["anyOf"] == [{"$ref": "#/$defs/TestSchema"}]
+
+    def test_allof_reference_dereferenced(self):
+        """Test that schemas referenced in allOf are preserved and unused defs pruned."""
+
+        schema = {
+            "type": "object",
+            "properties": {"data": {"allOf": [{"$ref": "#/$defs/TestSchema"}]}},
+            "$defs": {
+                "TestSchema": {"type": "string"},
+                "UnusedSchema": {"type": "number"},
+            },
+        }
+
+        result = compress_schema(schema)
+
+        # UnusedSchema should be pruned, TestSchema should be kept
+        assert "UnusedSchema" not in result.get("$defs", {})
+        assert result["$defs"]["TestSchema"] == {"type": "string"}
+
+        # $ref should be preserved in allOf
+        assert result["properties"]["data"]["allOf"] == [{"$ref": "#/$defs/TestSchema"}]
diff --git a/tests/utilities/openapi/test_transitive_references.py b/tests/utilities/openapi/test_transitive_references.py
new file mode 100644
index 0000000..fbb15f5
--- /dev/null
+++ b/tests/utilities/openapi/test_transitive_references.py
@@ -0,0 +1,842 @@
+"""Comprehensive tests for transitive and nested reference handling (Issue #1372)."""
+
+from fastmcp.utilities.openapi.models import (
+    HTTPRoute,
+    ParameterInfo,
+    RequestBodyInfo,
+    ResponseInfo,
+)
+from fastmcp.utilities.openapi.parser import parse_openapi_to_http_routes
+from fastmcp.utilities.openapi.schemas import (
+    _combine_schemas_and_map_params,
+    extract_output_schema_from_responses,
+)
+
+
+class TestTransitiveAndNestedReferences:
+    """Comprehensive tests for transitive and nested reference handling (Issue #1372)."""
+
+    def test_nested_refs_in_schema_definitions_converted(self):
+        """$refs inside schema definitions must be converted from OpenAPI to JSON Schema format."""
+        route = HTTPRoute(
+            path="/users/{id}",
+            method="POST",
+            operation_id="create_user",
+            parameters=[
+                ParameterInfo(
+                    name="id", location="path", required=True, schema={"type": "string"}
+                )
+            ],
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "object",
+                        "properties": {"user": {"$ref": "#/components/schemas/User"}},
+                    }
+                },
+            ),
+            request_schemas={
+                "User": {
+                    "type": "object",
+                    "properties": {"profile": {"$ref": "#/components/schemas/Profile"}},
+                },
+                "Profile": {
+                    "type": "object",
+                    "properties": {"name": {"type": "string"}},
+                },
+            },
+        )
+
+        combined_schema, _ = _combine_schemas_and_map_params(route)
+
+        # Root level refs should be converted
+        assert combined_schema["properties"]["user"]["$ref"] == "#/$defs/User"
+
+        # Refs inside schema definitions should also be converted
+        user_def = combined_schema["$defs"]["User"]
+        assert user_def["properties"]["profile"]["$ref"] == "#/$defs/Profile"
+
+    def test_transitive_dependencies_in_response_schemas(self):
+        """Transitive dependencies (A→B→C) must all be preserved in response schemas."""
+        # This mimics the exact structure reported in issue #1372
+        responses = {
+            "201": ResponseInfo(
+                description="User created",
+                content_schema={
+                    "application/json": {"$ref": "#/components/schemas/User"}
+                },
+            )
+        }
+
+        schema_definitions = {
+            "User": {
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string"},
+                    "profile": {"$ref": "#/components/schemas/Profile"},
+                },
+                "required": ["id", "profile"],
+            },
+            "Profile": {
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string"},
+                    "address": {"$ref": "#/components/schemas/Address"},
+                },
+                "required": ["name", "address"],
+            },
+            "Address": {
+                "type": "object",
+                "properties": {
+                    "street": {"type": "string"},
+                    "city": {"type": "string"},
+                    "zipcode": {"type": "string"},
+                },
+                "required": ["street", "city", "zipcode"],
+            },
+        }
+
+        result = extract_output_schema_from_responses(
+            responses, schema_definitions=schema_definitions, openapi_version="3.0.3"
+        )
+
+        # All transitive dependencies must be preserved
+        assert result is not None
+        assert "$defs" in result
+        assert "User" in result["$defs"], "User should be preserved"
+        assert "Profile" in result["$defs"], "Profile should be preserved"
+        assert "Address" in result["$defs"], "Address must be preserved (main bug)"
+
+        # All refs should be converted to #/$defs format
+        user_def = result["$defs"]["User"]
+        assert user_def["properties"]["profile"]["$ref"] == "#/$defs/Profile"
+
+        profile_def = result["$defs"]["Profile"]
+        assert profile_def["properties"]["address"]["$ref"] == "#/$defs/Address"
+
+    def test_elongl_reported_case_xref_with_nullable_function(self):
+        """Test the specific case reported by elongl with nullable function reference."""
+        responses = {
+            "200": ResponseInfo(
+                description="Success",
+                content_schema={
+                    "application/json": {
+                        "type": "array",
+                        "items": {"$ref": "#/components/schemas/Xref"},
+                    }
+                },
+            )
+        }
+
+        schema_definitions = {
+            "Xref": {
+                "type": "object",
+                "properties": {
+                    "address": {"type": "string", "title": "Address"},
+                    "type": {"type": "string", "title": "Type"},
+                    "function": {
+                        "anyOf": [
+                            {"$ref": "#/components/schemas/Function"},
+                            {"type": "null"},
+                        ]
+                    },
+                },
+                "required": ["address", "type", "function"],
+                "title": "Xref",
+            },
+            "Function": {
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string"},
+                    "address": {"type": "string"},
+                },
+                "title": "Function",
+            },
+        }
+
+        result = extract_output_schema_from_responses(
+            responses, schema_definitions=schema_definitions
+        )
+
+        # Function must be included in $defs
+        assert result is not None
+        assert "$defs" in result
+        assert "Xref" in result["$defs"], "Xref should be preserved"
+        assert "Function" in result["$defs"], (
+            "Function must be preserved (reported bug)"
+        )
+
+        # Refs in anyOf should be converted
+        xref_def = result["$defs"]["Xref"]
+        function_prop = xref_def["properties"]["function"]
+        assert function_prop["anyOf"][0]["$ref"] == "#/$defs/Function"
+
+    def test_tspicer_reported_case_profile_with_nested_refs(self):
+        """Test the specific case reported by tspicer with Profile->countryCode->AccountInfo."""
+        route = HTTPRoute(
+            path="/profile",
+            method="POST",
+            operation_id="create_profile",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {"$ref": "#/components/schemas/Profile"}
+                },
+            ),
+            request_schemas={
+                "Profile": {
+                    "type": "object",
+                    "properties": {
+                        "profileId": {"type": "integer"},
+                        "countryCode": {"$ref": "#/components/schemas/countryCode"},
+                        "accountInfo": {"$ref": "#/components/schemas/AccountInfo"},
+                    },
+                },
+                "countryCode": {
+                    "type": "string",
+                    "enum": ["US", "UK", "CA", "AU"],
+                },
+                "AccountInfo": {
+                    "type": "object",
+                    "properties": {
+                        "accountId": {"type": "string"},
+                        "accountType": {"type": "string"},
+                    },
+                },
+            },
+        )
+
+        combined_schema, _ = _combine_schemas_and_map_params(route)
+
+        # All referenced schemas must be included in $defs
+        assert "Profile" in combined_schema["$defs"], "Profile should be preserved"
+        assert "countryCode" in combined_schema["$defs"], (
+            "countryCode must be preserved"
+        )
+        assert "AccountInfo" in combined_schema["$defs"], (
+            "AccountInfo must be preserved"
+        )
+
+        # All refs should be converted
+        profile_def = combined_schema["$defs"]["Profile"]
+        assert profile_def["properties"]["countryCode"]["$ref"] == "#/$defs/countryCode"
+        assert profile_def["properties"]["accountInfo"]["$ref"] == "#/$defs/AccountInfo"
+
+    def test_transitive_refs_in_request_body_schemas(self):
+        """Transitive $refs in request body schemas must be preserved and converted."""
+        route = HTTPRoute(
+            path="/users",
+            method="POST",
+            operation_id="create_user",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {"$ref": "#/components/schemas/User"}
+                },
+            ),
+            request_schemas={
+                "User": {
+                    "type": "object",
+                    "properties": {
+                        "id": {"type": "string"},
+                        "profile": {"$ref": "#/components/schemas/Profile"},
+                    },
+                    "required": ["id", "profile"],
+                },
+                "Profile": {
+                    "type": "object",
+                    "properties": {
+                        "name": {"type": "string"},
+                        "address": {"$ref": "#/components/schemas/Address"},
+                    },
+                    "required": ["name", "address"],
+                },
+                "Address": {
+                    "type": "object",
+                    "properties": {
+                        "street": {"type": "string"},
+                        "city": {"type": "string"},
+                        "zipcode": {"type": "string"},
+                    },
+                    "required": ["street", "city", "zipcode"],
+                },
+            },
+        )
+
+        combined_schema, _ = _combine_schemas_and_map_params(route)
+
+        # All transitive dependencies should be preserved
+        assert "User" in combined_schema["$defs"]
+        assert "Profile" in combined_schema["$defs"]
+        assert "Address" in combined_schema["$defs"]
+
+        # All internal refs should be converted to #/$defs format
+        user_def = combined_schema["$defs"]["User"]
+        assert user_def["properties"]["profile"]["$ref"] == "#/$defs/Profile"
+
+        profile_def = combined_schema["$defs"]["Profile"]
+        assert profile_def["properties"]["address"]["$ref"] == "#/$defs/Address"
+
+    def test_refs_in_array_items_converted(self):
+        """$refs inside array items must be converted from OpenAPI to JSON Schema format."""
+        route = HTTPRoute(
+            path="/users",
+            method="POST",
+            operation_id="create_users",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "object",
+                        "properties": {
+                            "users": {
+                                "type": "array",
+                                "items": {"$ref": "#/components/schemas/User"},
+                            }
+                        },
+                    }
+                },
+            ),
+            request_schemas={
+                "User": {
+                    "type": "object",
+                    "properties": {"profile": {"$ref": "#/components/schemas/Profile"}},
+                },
+                "Profile": {
+                    "type": "object",
+                    "properties": {"name": {"type": "string"}},
+                },
+            },
+        )
+
+        combined_schema, _ = _combine_schemas_and_map_params(route)
+
+        # Array item refs should be converted
+        assert combined_schema["properties"]["users"]["items"]["$ref"] == "#/$defs/User"
+
+        # Nested refs should be converted
+        user_def = combined_schema["$defs"]["User"]
+        assert user_def["properties"]["profile"]["$ref"] == "#/$defs/Profile"
+
+    def test_refs_in_composition_keywords_converted(self):
+        """$refs inside oneOf/anyOf/allOf must be converted from OpenAPI to JSON Schema format."""
+        route = HTTPRoute(
+            path="/data",
+            method="POST",
+            operation_id="create_data",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "object",
+                        "properties": {
+                            "data": {
+                                "oneOf": [
+                                    {"$ref": "#/components/schemas/TypeA"},
+                                    {"$ref": "#/components/schemas/TypeB"},
+                                ]
+                            },
+                            "alternate": {
+                                "anyOf": [
+                                    {"$ref": "#/components/schemas/TypeC"},
+                                    {"$ref": "#/components/schemas/TypeD"},
+                                ]
+                            },
+                            "combined": {
+                                "allOf": [
+                                    {"$ref": "#/components/schemas/BaseType"},
+                                    {"properties": {"extra": {"type": "string"}}},
+                                ]
+                            },
+                        },
+                    }
+                },
+            ),
+            request_schemas={
+                "TypeA": {
+                    "type": "object",
+                    "properties": {"nested": {"$ref": "#/components/schemas/Nested"}},
+                },
+                "TypeB": {
+                    "type": "object",
+                    "properties": {"value": {"type": "string"}},
+                },
+                "TypeC": {"type": "string"},
+                "TypeD": {"type": "number"},
+                "BaseType": {
+                    "type": "object",
+                    "properties": {"base": {"type": "string"}},
+                },
+                "Nested": {"type": "string"},
+            },
+        )
+
+        combined_schema, _ = _combine_schemas_and_map_params(route)
+
+        # oneOf refs should be converted
+        oneof_refs = combined_schema["properties"]["data"]["oneOf"]
+        assert oneof_refs[0]["$ref"] == "#/$defs/TypeA"
+        assert oneof_refs[1]["$ref"] == "#/$defs/TypeB"
+
+        # anyOf refs should be converted
+        anyof_refs = combined_schema["properties"]["alternate"]["anyOf"]
+        assert anyof_refs[0]["$ref"] == "#/$defs/TypeC"
+        assert anyof_refs[1]["$ref"] == "#/$defs/TypeD"
+
+        # allOf refs should be converted
+        allof_refs = combined_schema["properties"]["combined"]["allOf"]
+        assert allof_refs[0]["$ref"] == "#/$defs/BaseType"
+
+        # Transitive refs should be converted
+        type_a_def = combined_schema["$defs"]["TypeA"]
+        assert type_a_def["properties"]["nested"]["$ref"] == "#/$defs/Nested"
+
+    def test_deeply_nested_transitive_refs_preserved(self):
+        """Deeply nested transitive refs (A→B→C→D→E) must all be preserved."""
+        route = HTTPRoute(
+            path="/deep",
+            method="POST",
+            operation_id="create_deep",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {"$ref": "#/components/schemas/Level1"}
+                },
+            ),
+            request_schemas={
+                "Level1": {
+                    "type": "object",
+                    "properties": {"level2": {"$ref": "#/components/schemas/Level2"}},
+                },
+                "Level2": {
+                    "type": "object",
+                    "properties": {"level3": {"$ref": "#/components/schemas/Level3"}},
+                },
+                "Level3": {
+                    "type": "object",
+                    "properties": {"level4": {"$ref": "#/components/schemas/Level4"}},
+                },
+                "Level4": {
+                    "type": "object",
+                    "properties": {"level5": {"$ref": "#/components/schemas/Level5"}},
+                },
+                "Level5": {
+                    "type": "object",
+                    "properties": {"value": {"type": "string"}},
+                },
+                "UnusedSchema": {"type": "number"},
+            },
+        )
+
+        combined_schema, _ = _combine_schemas_and_map_params(route)
+
+        # All levels should be preserved
+        assert "Level1" in combined_schema["$defs"]
+        assert "Level2" in combined_schema["$defs"]
+        assert "Level3" in combined_schema["$defs"]
+        assert "Level4" in combined_schema["$defs"]
+        assert "Level5" in combined_schema["$defs"]
+
+        # Unused should be removed (pruning is allowed for unused schemas)
+        assert "UnusedSchema" not in combined_schema["$defs"]
+
+        # All refs should be converted
+        assert (
+            combined_schema["$defs"]["Level1"]["properties"]["level2"]["$ref"]
+            == "#/$defs/Level2"
+        )
+        assert (
+            combined_schema["$defs"]["Level2"]["properties"]["level3"]["$ref"]
+            == "#/$defs/Level3"
+        )
+        assert (
+            combined_schema["$defs"]["Level3"]["properties"]["level4"]["$ref"]
+            == "#/$defs/Level4"
+        )
+        assert (
+            combined_schema["$defs"]["Level4"]["properties"]["level5"]["$ref"]
+            == "#/$defs/Level5"
+        )
+
+    def test_circular_references_handled(self):
+        """Circular references (A→B→A) must be handled without infinite loops."""
+        route = HTTPRoute(
+            path="/circular",
+            method="POST",
+            operation_id="circular_test",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {"$ref": "#/components/schemas/Node"}
+                },
+            ),
+            request_schemas={
+                "Node": {
+                    "type": "object",
+                    "properties": {
+                        "value": {"type": "string"},
+                        "children": {
+                            "type": "array",
+                            "items": {"$ref": "#/components/schemas/Node"},
+                        },
+                    },
+                },
+            },
+        )
+
+        combined_schema, _ = _combine_schemas_and_map_params(route)
+
+        # Node should be preserved
+        assert "Node" in combined_schema["$defs"]
+
+        # Self-reference should be converted
+        node_def = combined_schema["$defs"]["Node"]
+        assert node_def["properties"]["children"]["items"]["$ref"] == "#/$defs/Node"
+
+    def test_multiple_reference_paths_to_same_schema(self):
+        """Multiple paths to the same schema (diamond pattern) must preserve the schema."""
+        route = HTTPRoute(
+            path="/diamond",
+            method="POST",
+            operation_id="diamond_test",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "object",
+                        "properties": {
+                            "left": {"$ref": "#/components/schemas/Left"},
+                            "right": {"$ref": "#/components/schemas/Right"},
+                        },
+                    }
+                },
+            ),
+            request_schemas={
+                "Left": {
+                    "type": "object",
+                    "properties": {"shared": {"$ref": "#/components/schemas/Shared"}},
+                },
+                "Right": {
+                    "type": "object",
+                    "properties": {"shared": {"$ref": "#/components/schemas/Shared"}},
+                },
+                "Shared": {
+                    "type": "object",
+                    "properties": {"value": {"type": "string"}},
+                },
+            },
+        )
+
+        combined_schema, _ = _combine_schemas_and_map_params(route)
+
+        # All schemas should be preserved
+        assert "Left" in combined_schema["$defs"]
+        assert "Right" in combined_schema["$defs"]
+        assert "Shared" in combined_schema["$defs"]
+
+        # All refs should be converted
+        assert combined_schema["properties"]["left"]["$ref"] == "#/$defs/Left"
+        assert combined_schema["properties"]["right"]["$ref"] == "#/$defs/Right"
+        assert (
+            combined_schema["$defs"]["Left"]["properties"]["shared"]["$ref"]
+            == "#/$defs/Shared"
+        )
+        assert (
+            combined_schema["$defs"]["Right"]["properties"]["shared"]["$ref"]
+            == "#/$defs/Shared"
+        )
+
+    def test_refs_in_nested_content_schemas(self):
+        """$refs in nested content schemas (the original bug location) must be converted."""
+        route = HTTPRoute(
+            path="/content",
+            method="POST",
+            operation_id="content_test",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {"$ref": "#/components/schemas/Content"}
+                },
+            ),
+            request_schemas={
+                "Content": {
+                    "type": "object",
+                    "properties": {
+                        "media": {
+                            "type": "object",
+                            "properties": {
+                                "application/json": {
+                                    "$ref": "#/components/schemas/JsonContent"
+                                }
+                            },
+                        }
+                    },
+                },
+                "JsonContent": {
+                    "type": "object",
+                    "properties": {"data": {"type": "string"}},
+                },
+            },
+        )
+
+        combined_schema, _ = _combine_schemas_and_map_params(route)
+
+        # Both schemas should be preserved
+        assert "Content" in combined_schema["$defs"]
+        assert "JsonContent" in combined_schema["$defs"]
+
+        # Nested ref should be converted
+        content_def = combined_schema["$defs"]["Content"]
+        nested_ref = content_def["properties"]["media"]["properties"][
+            "application/json"
+        ]
+        assert nested_ref["$ref"] == "#/$defs/JsonContent"
+
+    def test_unnecessary_defs_preserved_when_referenced(self):
+        """Even seemingly unnecessary $defs must be preserved if they're referenced."""
+        route = HTTPRoute(
+            path="/test",
+            method="POST",
+            operation_id="test_unnecessary",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    "application/json": {
+                        "type": "object",
+                        "properties": {
+                            # Reference to a simple type schema
+                            "simple": {"$ref": "#/components/schemas/SimpleString"},
+                            # Reference to an empty object schema
+                            "empty": {"$ref": "#/components/schemas/EmptyObject"},
+                        },
+                    }
+                },
+            ),
+            request_schemas={
+                "SimpleString": {"type": "string"},
+                "EmptyObject": {"type": "object"},
+                "UnreferencedSchema": {"type": "number"},
+            },
+        )
+
+        combined_schema, _ = _combine_schemas_and_map_params(route)
+
+        # Referenced schemas should be preserved even if simple
+        assert "SimpleString" in combined_schema["$defs"]
+        assert "EmptyObject" in combined_schema["$defs"]
+
+        # Unreferenced should be removed
+        assert "UnreferencedSchema" not in combined_schema["$defs"]
+
+        # Refs should be converted
+        assert combined_schema["properties"]["simple"]["$ref"] == "#/$defs/SimpleString"
+        assert combined_schema["properties"]["empty"]["$ref"] == "#/$defs/EmptyObject"
+
+    def test_ref_only_request_body_handled(self):
+        """Request bodies that are just a $ref (not an object with properties) must work."""
+        route = HTTPRoute(
+            path="/direct-ref",
+            method="POST",
+            operation_id="direct_ref_test",
+            request_body=RequestBodyInfo(
+                required=True,
+                content_schema={
+                    # Direct $ref, not wrapped in an object
+                    "application/json": {"$ref": "#/components/schemas/DirectBody"}
+                },
+            ),
+            request_schemas={
+                "DirectBody": {
+                    "type": "object",
+                    "properties": {
+                        "field1": {"type": "string"},
+                        "nested": {"$ref": "#/components/schemas/NestedBody"},
+                    },
+                },
+                "NestedBody": {
+                    "type": "object",
+                    "properties": {"field2": {"type": "number"}},
+                },
+            },
+        )
+
+        combined_schema, _ = _combine_schemas_and_map_params(route)
+
+        # Should handle the direct ref properly
+        assert "body" in combined_schema["properties"]
+        assert combined_schema["properties"]["body"]["$ref"] == "#/$defs/DirectBody"
+
+        # Both schemas should be preserved
+        assert "DirectBody" in combined_schema["$defs"]
+        assert "NestedBody" in combined_schema["$defs"]
+
+        # Nested ref should be converted
+        assert (
+            combined_schema["$defs"]["DirectBody"]["properties"]["nested"]["$ref"]
+            == "#/$defs/NestedBody"
+        )
+
+    def test_separate_input_output_schemas(self):
+        """Test that input and output schemas contain different schema
+        definitions and don't overlap in the ultimate schema definitions."""
+        # OpenAPI spec with transitive dependencies to force schema inclusion
+        openapi_spec = {
+            "openapi": "3.0.1",
+            "info": {"title": "Test API", "version": "1.0.0"},
+            "paths": {
+                "/test": {
+                    "post": {
+                        "summary": "Test endpoint",
+                        "requestBody": {
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "$ref": "#/components/schemas/InputContainer"
+                                    }
+                                }
+                            }
+                        },
+                        "responses": {
+                            "200": {
+                                "description": "Success",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "$ref": "#/components/schemas/OutputContainer"
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                }
+            },
+            "components": {
+                "schemas": {
+                    "InputContainer": {
+                        "type": "object",
+                        "properties": {
+                            "data": {"$ref": "#/components/schemas/InputData"}
+                        },
+                    },
+                    "InputData": {
+                        "type": "object",
+                        "properties": {"input_field": {"type": "string"}},
+                    },
+                    "OutputContainer": {
+                        "type": "object",
+                        "properties": {
+                            "result": {"$ref": "#/components/schemas/OutputData"}
+                        },
+                    },
+                    "OutputData": {
+                        "type": "object",
+                        "properties": {"output_field": {"type": "string"}},
+                    },
+                    "UnusedSchema": {
+                        "type": "object",
+                        "properties": {"unused_field": {"type": "string"}},
+                    },
+                }
+            },
+        }
+
+        routes = parse_openapi_to_http_routes(openapi_spec)
+        assert len(routes) == 1
+
+        route = routes[0]
+
+        # Check that schemas are properly separated
+        input_schema_names = set(route.request_schemas.keys())
+        output_schema_names = set(route.response_schemas.keys())
+
+        # Input should contain transitive dependencies from InputContainer
+        assert "InputData" in input_schema_names, (
+            f"Expected InputData in request schemas: {input_schema_names}"
+        )
+        assert "OutputContainer" not in input_schema_names, (
+            "OutputContainer should not be in request schemas"
+        )
+        assert "OutputData" not in input_schema_names, (
+            "OutputData should not be in request schemas"
+        )
+
+        # Output should contain transitive dependencies from OutputContainer
+        assert "OutputData" in output_schema_names, (
+            f"Expected OutputData in response schemas: {output_schema_names}"
+        )
+        assert "InputContainer" not in output_schema_names, (
+            "InputContainer should not be in response schemas"
+        )
+        assert "InputData" not in output_schema_names, (
+            "InputData should not be in response schemas"
+        )
+
+        # Neither should contain unused schema
+        assert "UnusedSchema" not in input_schema_names, (
+            "UnusedSchema should not be in request schemas"
+        )
+        assert "UnusedSchema" not in output_schema_names, (
+            "UnusedSchema should not be in response schemas"
+        )
+
+        # Verify no overlap
+        overlap = input_schema_names & output_schema_names
+        assert len(overlap) == 0, (
+            f"Found overlapping schemas between input and output: {overlap}"
+        )
+
+    def test_issue_2087_top_level_response_ref_includes_all_nested_schemas(self):
+        """Issue #2087: Top-level response $ref must include itself in response_schemas."""
+        spec = {
+            "openapi": "3.0.1",
+            "info": {"title": "Test", "version": "1.0"},
+            "paths": {
+                "/persons": {
+                    "get": {
+                        "responses": {
+                            "200": {
+                                "description": "OK",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "$ref": "#/components/schemas/PersonList"
+                                        }
+                                    }
+                                },
+                            }
+                        }
+                    }
+                }
+            },
+            "components": {
+                "schemas": {
+                    "PersonList": {
+                        "properties": {
+                            "Items": {
+                                "type": "array",
+                                "items": {"$ref": "#/components/schemas/Person"},
+                            }
+                        }
+                    },
+                    "Person": {
+                        "properties": {
+                            "Name": {"$ref": "#/components/schemas/Name"},
+                            "Job": {"$ref": "#/components/schemas/Job"},
+                        }
+                    },
+                    "Name": {"properties": {"First": {"type": "string"}}},
+                    "Job": {"properties": {"Company": {"type": "string"}}},
+                }
+            },
+        }
+
+        routes = parse_openapi_to_http_routes(spec)
+        route = routes[0]
+
+        # Bug was: PersonList missing from response_schemas despite being top-level ref
+        assert "PersonList" in route.response_schemas
+        assert "Person" in route.response_schemas
+        assert "Name" in route.response_schemas
+        assert "Job" in route.response_schemas
diff --git a/tests/utilities/test_async_utils.py b/tests/utilities/test_async_utils.py
new file mode 100644
index 0000000..6d13666
--- /dev/null
+++ b/tests/utilities/test_async_utils.py
@@ -0,0 +1,141 @@
+"""Tests for fastmcp.utilities.async_utils."""
+
+import functools
+
+import pytest
+from exceptiongroup import BaseExceptionGroup
+
+from fastmcp import Client, FastMCP
+from fastmcp.prompts import prompt
+from fastmcp.resources import resource
+from fastmcp.tools import tool
+from fastmcp.utilities.async_utils import gather, is_coroutine_function
+
+
+async def _async_fn(x: int) -> int:
+    return x
+
+
+def _sync_fn(x: int) -> int:
+    return x
+
+
+class TestIsCoroutineFunction:
+    def test_plain_async(self) -> None:
+        assert is_coroutine_function(_async_fn) is True
+
+    def test_plain_sync(self) -> None:
+        assert is_coroutine_function(_sync_fn) is False
+
+    def test_partial_async(self) -> None:
+        p = functools.partial(_async_fn, x=1)
+        assert is_coroutine_function(p) is True
+
+    def test_partial_sync(self) -> None:
+        p = functools.partial(_sync_fn, x=1)
+        assert is_coroutine_function(p) is False
+
+    def test_nested_partial_async(self) -> None:
+        p = functools.partial(functools.partial(_async_fn, x=1))
+        assert is_coroutine_function(p) is True
+
+    def test_nested_partial_sync(self) -> None:
+        p = functools.partial(functools.partial(_sync_fn, x=1))
+        assert is_coroutine_function(p) is False
+
+    def test_lambda(self) -> None:
+        assert is_coroutine_function(lambda: None) is False
+
+    def test_non_callable(self) -> None:
+        assert is_coroutine_function(42) is False
+
+
+class TestGather:
+    async def test_returns_results_in_input_order(self) -> None:
+        async def value(result: int) -> int:
+            return result
+
+        assert await gather(value(1), value(2), value(3)) == [1, 2, 3]
+
+    async def test_raises_by_default(self) -> None:
+        async def fail() -> int:
+            raise RuntimeError("boom")
+
+        with pytest.raises(BaseExceptionGroup) as exc_info:
+            await gather(fail())
+
+        assert len(exc_info.value.exceptions) == 1
+        assert isinstance(exc_info.value.exceptions[0], RuntimeError)
+
+    async def test_return_exceptions_collects_exceptions(self) -> None:
+        async def fail() -> int:
+            raise ValueError("bad")
+
+        async def value() -> int:
+            return 1
+
+        result = await gather(fail(), value(), return_exceptions=True)
+
+        assert isinstance(result[0], ValueError)
+        assert result[1] == 1
+
+
+class TestAsyncPartialIntegration:
+    async def test_async_partial_tool_runs(self) -> None:
+        async def greet(greeting: str, name: str) -> str:
+            return f"{greeting}, {name}!"
+
+        greet_tool = tool(name="greet")(functools.partial(greet, "Hello"))
+
+        mcp = FastMCP()
+        mcp.add_tool(greet_tool)
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("greet", {"name": "world"})
+            assert result.content[0].text == "Hello, world!"
+
+    async def test_async_partial_resource_reads(self) -> None:
+        async def make_greeting(greeting: str) -> str:
+            return f"{greeting}, resource!"
+
+        greet_resource = resource("test://greet")(
+            functools.partial(make_greeting, "Hi")
+        )
+
+        mcp = FastMCP()
+        mcp.add_resource(greet_resource)
+
+        async with Client(mcp) as client:
+            result = await client.read_resource("test://greet")
+            assert result[0].text == "Hi, resource!"
+
+    async def test_async_partial_prompt_renders(self) -> None:
+        async def make_prompt(prefix: str) -> str:
+            return f"{prefix}: prompt content"
+
+        note_prompt = prompt(name="note")(functools.partial(make_prompt, "Note"))
+
+        mcp = FastMCP()
+        mcp.add_prompt(note_prompt)
+
+        async with Client(mcp) as client:
+            result = await client.get_prompt("note")
+            assert "Note: prompt content" in result.messages[0].content.text
+
+    async def test_async_partial_with_task_true_does_not_raise(self) -> None:
+        async def slow_task(prefix: str, x: int) -> str:
+            return f"{prefix}-{x}"
+
+        slow_tool = tool(name="slow", task=True)(functools.partial(slow_task, "ok"))
+
+        mcp = FastMCP()
+        mcp.add_tool(slow_tool)
+
+    async def test_sync_partial_with_task_true_raises(self) -> None:
+        def sync_task(prefix: str, x: int) -> str:
+            return f"{prefix}-{x}"
+
+        mcp = FastMCP()
+        with pytest.raises(ValueError, match="sync function"):
+            decorated = tool(name="slow", task=True)(functools.partial(sync_task, "ok"))
+            mcp.add_tool(decorated)
diff --git a/tests/utilities/test_auth.py b/tests/utilities/test_auth.py
new file mode 100644
index 0000000..fc83781
--- /dev/null
+++ b/tests/utilities/test_auth.py
@@ -0,0 +1,177 @@
+"""Tests for authentication utility helpers."""
+
+import base64
+import json
+
+import pytest
+
+from fastmcp.utilities.auth import (
+    decode_jwt_header,
+    decode_jwt_payload,
+    parse_scopes,
+)
+
+
+def create_jwt(header: dict, payload: dict, signature: bytes = b"fake-sig") -> str:
+    """Create a test JWT token."""
+    header_b64 = base64.urlsafe_b64encode(json.dumps(header).encode()).rstrip(b"=")
+    payload_b64 = base64.urlsafe_b64encode(json.dumps(payload).encode()).rstrip(b"=")
+    sig_b64 = base64.urlsafe_b64encode(signature).rstrip(b"=")
+    return f"{header_b64.decode()}.{payload_b64.decode()}.{sig_b64.decode()}"
+
+
+class TestDecodeJwtHeader:
+    """Tests for decode_jwt_header utility."""
+
+    def test_decode_basic_header(self):
+        """Test decoding a basic JWT header."""
+        header = {"alg": "RS256", "typ": "JWT"}
+        payload = {"sub": "user-123"}
+        token = create_jwt(header, payload)
+
+        result = decode_jwt_header(token)
+
+        assert result == header
+        assert result["alg"] == "RS256"
+        assert result["typ"] == "JWT"
+
+    def test_decode_header_with_kid(self):
+        """Test decoding header with key ID for JWKS lookup."""
+        header = {"alg": "RS256", "typ": "JWT", "kid": "key-id-123"}
+        payload = {"sub": "user-123"}
+        token = create_jwt(header, payload)
+
+        result = decode_jwt_header(token)
+
+        assert result["kid"] == "key-id-123"
+
+    def test_invalid_jwt_format_two_parts(self):
+        """Test that two-part token raises ValueError."""
+        with pytest.raises(ValueError, match="Invalid JWT format"):
+            decode_jwt_header("header.payload")
+
+    def test_invalid_jwt_format_one_part(self):
+        """Test that single-part token raises ValueError."""
+        with pytest.raises(ValueError, match="Invalid JWT format"):
+            decode_jwt_header("not-a-jwt")
+
+    def test_invalid_jwt_format_four_parts(self):
+        """Test that four-part token raises ValueError."""
+        with pytest.raises(ValueError, match="Invalid JWT format"):
+            decode_jwt_header("a.b.c.d")
+
+    def test_decode_header_length_divisible_by_4(self):
+        """Test decoding when base64 length is divisible by 4 (no padding needed).
+
+        This tests the edge case where len(part) % 4 == 0.
+        The padding calculation (-len % 4) correctly yields 0 in this case.
+        """
+        # Create a header that encodes to exactly 12 chars (divisible by 4)
+        header = {"x": ""}  # eyJ4IjogIiJ9 = 12 chars
+        payload = {"sub": "user"}
+        token = create_jwt(header, payload)
+
+        result = decode_jwt_header(token)
+        assert result == header
+
+
+class TestDecodeJwtPayload:
+    """Tests for decode_jwt_payload utility."""
+
+    def test_decode_basic_payload(self):
+        """Test decoding a basic JWT payload."""
+        header = {"alg": "RS256", "typ": "JWT"}
+        payload = {"sub": "user-123", "name": "Test User"}
+        token = create_jwt(header, payload)
+
+        result = decode_jwt_payload(token)
+
+        assert result == payload
+        assert result["sub"] == "user-123"
+        assert result["name"] == "Test User"
+
+    def test_decode_payload_with_claims(self):
+        """Test decoding payload with various claims."""
+        header = {"alg": "RS256"}
+        payload = {
+            "sub": "user-123",
+            "oid": "object-456",
+            "name": "Test User",
+            "email": "test@example.com",
+            "roles": ["admin", "user"],
+            "exp": 1234567890,
+        }
+        token = create_jwt(header, payload)
+
+        result = decode_jwt_payload(token)
+
+        assert result["sub"] == "user-123"
+        assert result["oid"] == "object-456"
+        assert result["name"] == "Test User"
+        assert result["email"] == "test@example.com"
+        assert result["roles"] == ["admin", "user"]
+        assert result["exp"] == 1234567890
+
+    def test_invalid_jwt_format(self):
+        """Test that invalid format raises ValueError."""
+        with pytest.raises(ValueError, match="Invalid JWT format"):
+            decode_jwt_payload("not-a-jwt")
+
+    def test_decode_payload_with_padding_edge_cases(self):
+        """Test that base64 padding is handled correctly."""
+        # Create payloads of different sizes to test padding
+        for payload_size in [1, 2, 3, 4, 5, 10, 100]:
+            payload = {"data": "x" * payload_size}
+            token = create_jwt({"alg": "RS256"}, payload)
+            result = decode_jwt_payload(token)
+            assert result == payload
+
+    def test_decode_payload_length_divisible_by_4(self):
+        """Test decoding when base64 length is divisible by 4 (no padding needed).
+
+        This tests the edge case where len(part) % 4 == 0.
+        The padding calculation (-len % 4) correctly yields 0 in this case.
+        """
+        # Create a payload that encodes to exactly 12 chars (divisible by 4)
+        header = {"alg": "RS256"}
+        payload = {"x": ""}  # eyJ4IjogIiJ9 = 12 chars
+        token = create_jwt(header, payload)
+
+        result = decode_jwt_payload(token)
+        assert result == payload
+
+
+class TestParseScopes:
+    """Tests for parse_scopes utility."""
+
+    def test_parse_none(self):
+        """Test that None returns None."""
+        assert parse_scopes(None) is None
+
+    def test_parse_empty_string(self):
+        """Test that empty string returns empty list."""
+        assert parse_scopes("") == []
+
+    def test_parse_space_separated(self):
+        """Test parsing space-separated scopes."""
+        assert parse_scopes("read write delete") == ["read", "write", "delete"]
+
+    def test_parse_comma_separated(self):
+        """Test parsing comma-separated scopes."""
+        assert parse_scopes("read,write,delete") == ["read", "write", "delete"]
+
+    def test_parse_json_array(self):
+        """Test parsing JSON array string."""
+        assert parse_scopes('["read", "write", "delete"]') == [
+            "read",
+            "write",
+            "delete",
+        ]
+
+    def test_parse_list(self):
+        """Test that list is returned as-is."""
+        assert parse_scopes(["read", "write"]) == ["read", "write"]
+
+    def test_parse_strips_whitespace(self):
+        """Test that whitespace is stripped."""
+        assert parse_scopes("  read  ,  write  ") == ["read", "write"]
diff --git a/tests/utilities/test_cli.py b/tests/utilities/test_cli.py
new file mode 100644
index 0000000..f463c29
--- /dev/null
+++ b/tests/utilities/test_cli.py
@@ -0,0 +1,195 @@
+"""Tests for CLI utility functions."""
+
+from pathlib import Path
+
+from fastmcp.utilities.mcp_server_config.v1.environments.uv import UVEnvironment
+
+
+class TestEnvironmentBuildUVRunCommand:
+    """Test the Environment.build_uv_run_command() method."""
+
+    def test_build_uv_run_command_basic(self):
+        """Test building basic uv command with no environment config."""
+        env = UVEnvironment()
+        cmd = env.build_command(["fastmcp", "run", "server.py"])
+        # With no config, the command should be returned unchanged
+        expected = ["fastmcp", "run", "server.py"]
+        assert cmd == expected
+
+    def test_build_uv_run_command_with_editable(self):
+        """Test building uv command with editable package."""
+        editable_path = Path("/path/to/package")
+        env = UVEnvironment(editable=[editable_path])
+        cmd = env.build_command(["fastmcp", "run", "server.py"])
+        expected = [
+            "uv",
+            "run",
+            "--with-editable",
+            str(editable_path.resolve()),
+            "fastmcp",
+            "run",
+            "server.py",
+        ]
+        assert cmd == expected
+
+    def test_build_uv_run_command_with_packages(self):
+        """Test building uv command with additional packages."""
+        env = UVEnvironment(dependencies=["pkg1", "pkg2"])
+        cmd = env.build_command(["fastmcp", "run", "server.py"])
+        expected = [
+            "uv",
+            "run",
+            "--with",
+            "pkg1",
+            "--with",
+            "pkg2",
+            "fastmcp",
+            "run",
+            "server.py",
+        ]
+        assert cmd == expected
+
+    def test_build_uv_run_command_with_python_version(self):
+        """Test building uv command with Python version."""
+        env = UVEnvironment(python="3.10")
+        cmd = env.build_command(["fastmcp", "run", "server.py"])
+        expected = [
+            "uv",
+            "run",
+            "--python",
+            "3.10",
+            "fastmcp",
+            "run",
+            "server.py",
+        ]
+        assert cmd == expected
+
+    def test_build_uv_run_command_with_requirements(self):
+        """Test building uv command with requirements file."""
+        requirements_path = Path("/path/to/requirements.txt")
+        env = UVEnvironment(requirements=requirements_path)
+        cmd = env.build_command(["fastmcp", "run", "server.py"])
+        expected = [
+            "uv",
+            "run",
+            "--with-requirements",
+            str(requirements_path.resolve()),
+            "fastmcp",
+            "run",
+            "server.py",
+        ]
+        assert cmd == expected
+
+    def test_build_uv_run_command_with_project(self):
+        """Test building uv command with project directory."""
+        project_path = Path("/path/to/project")
+        env = UVEnvironment(project=project_path)
+        cmd = env.build_command(["fastmcp", "run", "server.py"])
+        expected = [
+            "uv",
+            "run",
+            "--project",
+            str(project_path.resolve()),
+            "fastmcp",
+            "run",
+            "server.py",
+        ]
+        assert cmd == expected
+
+    def test_build_uv_run_command_with_everything(self):
+        """Test building uv command with all options."""
+        requirements_path = Path("/path/to/requirements.txt")
+        editable_path = Path("/local/pkg")
+        env = UVEnvironment(
+            python="3.10",
+            dependencies=["pandas", "numpy"],
+            requirements=requirements_path,
+            editable=[editable_path],
+        )
+        cmd = env.build_command(["fastmcp", "run", "server.py"])
+        expected = [
+            "uv",
+            "run",
+            "--python",
+            "3.10",
+            "--with",
+            "numpy",
+            "--with",
+            "pandas",
+            "--with-requirements",
+            str(requirements_path.resolve()),
+            "--with-editable",
+            str(editable_path.resolve()),
+            "fastmcp",
+            "run",
+            "server.py",
+        ]
+        assert cmd == expected
+
+    # Note: These tests are removed because build_uv_run_command now requires a command
+    # and only accepts a list, not optional or string commands
+
+    def test_build_uv_run_command_project_with_extras(self):
+        """Test that project flag works with additional dependencies."""
+        project_path = Path("/path/to/project")
+        editable_path = Path("/pkg")
+        env = UVEnvironment(
+            project=project_path,
+            python="3.10",  # Should be ignored with project
+            dependencies=["pandas"],  # Should be added on top of project
+            editable=[editable_path],  # Should be added on top of project
+        )
+        cmd = env.build_command(["fastmcp", "run", "server.py"])
+        expected = [
+            "uv",
+            "run",
+            "--project",
+            str(project_path.resolve()),
+            "--with",
+            "pandas",
+            "--with-editable",
+            str(editable_path.resolve()),
+            "fastmcp",
+            "run",
+            "server.py",
+        ]
+        assert cmd == expected
+
+
+class TestEnvironmentNeedsUV:
+    """Test the Environment.needs_uv() method."""
+
+    def test_needs_uv_with_python(self):
+        """Test that needs_uv returns True with Python version."""
+        env = UVEnvironment(python="3.10")
+        assert env._must_run_with_uv() is True
+
+    def test_needs_uv_with_dependencies(self):
+        """Test that needs_uv returns True with dependencies."""
+        env = UVEnvironment(dependencies=["pandas"])
+        assert env._must_run_with_uv() is True
+
+    def test_needs_uv_with_requirements(self):
+        """Test that needs_uv returns True with requirements."""
+        env = UVEnvironment(requirements=Path("/path/to/requirements.txt"))
+        assert env._must_run_with_uv() is True
+
+    def test_needs_uv_with_project(self):
+        """Test that needs_uv returns True with project."""
+        env = UVEnvironment(project=Path("/path/to/project"))
+        assert env._must_run_with_uv() is True
+
+    def test_needs_uv_with_editable(self):
+        """Test that needs_uv returns True with editable."""
+        env = UVEnvironment(editable=[Path("/pkg")])
+        assert env._must_run_with_uv() is True
+
+    def test_needs_uv_empty(self):
+        """Test that needs_uv returns False with empty config."""
+        env = UVEnvironment()
+        assert env._must_run_with_uv() is False
+
+    def test_needs_uv_with_empty_lists(self):
+        """Test that needs_uv returns False with empty lists."""
+        env = UVEnvironment(dependencies=None, editable=None)
+        assert env._must_run_with_uv() is False
diff --git a/tests/utilities/test_components.py b/tests/utilities/test_components.py
new file mode 100644
index 0000000..cea67ea
--- /dev/null
+++ b/tests/utilities/test_components.py
@@ -0,0 +1,442 @@
+"""Tests for fastmcp.utilities.components module."""
+
+import warnings
+
+import pytest
+from pydantic import ValidationError
+
+from fastmcp.prompts.base import Prompt
+from fastmcp.resources.base import Resource
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.tools.base import Tool
+from fastmcp.utilities.components import (
+    FastMCPComponent,
+    FastMCPMeta,
+    _convert_set_default_none,
+    get_fastmcp_metadata,
+)
+
+
+class TestConvertSetDefaultNone:
+    """Tests for the _convert_set_default_none helper function."""
+
+    def test_none_returns_empty_set(self):
+        """Test that None returns an empty set."""
+        result = _convert_set_default_none(None)
+        assert result == set()
+
+    def test_set_returns_same_set(self):
+        """Test that a set returns the same set."""
+        test_set = {"tag1", "tag2"}
+        result = _convert_set_default_none(test_set)
+        assert result == test_set
+
+    def test_list_converts_to_set(self):
+        """Test that a list converts to a set."""
+        test_list = ["tag1", "tag2", "tag1"]  # Duplicate to test deduplication
+        result = _convert_set_default_none(test_list)
+        assert result == {"tag1", "tag2"}
+
+    def test_tuple_converts_to_set(self):
+        """Test that a tuple converts to a set."""
+        test_tuple = ("tag1", "tag2")
+        result = _convert_set_default_none(test_tuple)
+        assert result == {"tag1", "tag2"}
+
+
+class TestFastMCPComponent:
+    """Tests for the FastMCPComponent class."""
+
+    @pytest.fixture
+    def basic_component(self):
+        """Create a basic component for testing."""
+        return FastMCPComponent(
+            name="test_component",
+            title="Test Component",
+            description="A test component",
+            tags={"test", "component"},
+        )
+
+    def test_initialization_with_minimal_params(self):
+        """Test component initialization with minimal parameters."""
+        component = FastMCPComponent(name="minimal")
+        assert component.name == "minimal"
+        assert component.title is None
+        assert component.description is None
+        assert component.tags == set()
+        assert component.meta is None
+
+    def test_initialization_with_all_params(self):
+        """Test component initialization with all parameters."""
+        meta = {"custom": "value"}
+        component = FastMCPComponent(
+            name="full",
+            title="Full Component",
+            description="A fully configured component",
+            tags={"tag1", "tag2"},
+            meta=meta,
+        )
+        assert component.name == "full"
+        assert component.title == "Full Component"
+        assert component.description == "A fully configured component"
+        assert component.tags == {"tag1", "tag2"}
+        assert component.meta == meta
+
+    def test_key_property_without_custom_key(self, basic_component):
+        """Test that key property returns name@version when no custom key is set."""
+        # Base component has no KEY_PREFIX, so key is just "name@version" (or "name@" for unversioned)
+        assert basic_component.key == "test_component@"
+
+    def test_get_meta_with_fastmcp_meta(self, basic_component):
+        """Test get_meta always includes fastmcp meta."""
+        basic_component.meta = {"custom": "data"}
+        basic_component.tags = {"tag2", "tag1"}  # Unordered to test sorting
+        result = basic_component.get_meta()
+        assert result["custom"] == "data"
+        assert "fastmcp" in result
+        assert result["fastmcp"]["tags"] == ["tag1", "tag2"]  # Should be sorted
+
+    def test_get_meta_preserves_existing_fastmcp_meta(self):
+        """Test that get_meta preserves existing fastmcp meta."""
+        component = FastMCPComponent(
+            name="test",
+            meta={"fastmcp": {"existing": "value"}},
+            tags={"new_tag"},
+        )
+        result = component.get_meta()
+        assert result is not None
+        assert result["fastmcp"]["existing"] == "value"
+        assert result["fastmcp"]["tags"] == ["new_tag"]
+
+    def test_get_meta_returns_dict_with_fastmcp_when_empty(self):
+        """Test that get_meta returns dict with fastmcp meta even when no custom meta."""
+        component = FastMCPComponent(name="test")
+        result = component.get_meta()
+        assert result is not None
+        assert "fastmcp" in result
+        assert result["fastmcp"]["tags"] == []
+
+    def test_get_meta_includes_version(self):
+        """Test that get_meta includes version when component has a version."""
+        component = FastMCPComponent(name="test", version="v1.0.0", tags={"tag1"})
+        result = component.get_meta()
+        assert result is not None
+        assert result["fastmcp"]["version"] == "v1.0.0"
+        assert result["fastmcp"]["tags"] == ["tag1"]
+
+    def test_get_meta_excludes_version_when_none(self):
+        """Test that get_meta excludes version when component has no version."""
+        component = FastMCPComponent(name="test", tags={"tag1"})
+        result = component.get_meta()
+        assert result is not None
+        assert "version" not in result["fastmcp"]
+        assert result["fastmcp"]["tags"] == ["tag1"]
+
+    def test_equality_same_components(self):
+        """Test that identical components are equal."""
+        comp1 = FastMCPComponent(name="test", description="desc")
+        comp2 = FastMCPComponent(name="test", description="desc")
+        assert comp1 == comp2
+
+    def test_equality_different_components(self):
+        """Test that different components are not equal."""
+        comp1 = FastMCPComponent(name="test1")
+        comp2 = FastMCPComponent(name="test2")
+        assert comp1 != comp2
+
+    def test_equality_different_types(self, basic_component):
+        """Test that component is not equal to other types."""
+        assert basic_component != "not a component"
+        assert basic_component != 123
+        assert basic_component is not None
+
+    def test_repr(self, basic_component):
+        """Test string representation of component."""
+        repr_str = repr(basic_component)
+        assert "FastMCPComponent" in repr_str
+        assert "name='test_component'" in repr_str
+        assert "title='Test Component'" in repr_str
+        assert "description='A test component'" in repr_str
+
+    def test_copy_method(self, basic_component):
+        """Test copy method creates an independent copy."""
+        copy = basic_component.copy()
+        assert copy == basic_component
+        assert copy is not basic_component
+
+        # Modify copy and ensure original is unchanged
+        copy.name = "modified"
+        assert basic_component.name == "test_component"
+
+    def test_tags_deduplication(self):
+        """Test that tags are deduplicated when passed as a sequence."""
+        component = FastMCPComponent(
+            name="test",
+            tags=["tag1", "tag2", "tag1", "tag2"],  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+        )
+        assert component.tags == {"tag1", "tag2"}
+
+    def test_validation_error_for_invalid_data(self):
+        """Test that validation errors are raised for invalid data."""
+        with pytest.raises(ValidationError):
+            FastMCPComponent()  # type: ignore[call-arg]  # ty:ignore[missing-argument]
+
+    def test_extra_fields_forbidden(self):
+        """Test that extra fields are not allowed."""
+        with pytest.raises(ValidationError) as exc_info:
+            FastMCPComponent(name="test", unknown_field="value")  # type: ignore[call-arg]  # Intentionally passing invalid field for test  # ty:ignore[unknown-argument]
+        assert "Extra inputs are not permitted" in str(exc_info.value)
+
+
+class TestKeyPrefix:
+    """Tests for KEY_PREFIX and make_key functionality."""
+
+    def test_base_class_has_empty_prefix(self):
+        """Test that FastMCPComponent has empty KEY_PREFIX."""
+        assert FastMCPComponent.KEY_PREFIX == ""
+
+    def test_make_key_without_prefix(self):
+        """Test make_key returns just identifier when KEY_PREFIX is empty."""
+        assert FastMCPComponent.make_key("my_name") == "my_name"
+
+    def test_tool_has_tool_prefix(self):
+        """Test that Tool has 'tool' KEY_PREFIX."""
+        assert Tool.KEY_PREFIX == "tool"
+        assert Tool.make_key("my_tool") == "tool:my_tool"
+
+    def test_resource_has_resource_prefix(self):
+        """Test that Resource has 'resource' KEY_PREFIX."""
+        assert Resource.KEY_PREFIX == "resource"
+        assert Resource.make_key("file://test.txt") == "resource:file://test.txt"
+
+    def test_template_has_template_prefix(self):
+        """Test that ResourceTemplate has 'template' KEY_PREFIX."""
+        assert ResourceTemplate.KEY_PREFIX == "template"
+        assert ResourceTemplate.make_key("data://{id}") == "template:data://{id}"
+
+    def test_prompt_has_prompt_prefix(self):
+        """Test that Prompt has 'prompt' KEY_PREFIX."""
+        assert Prompt.KEY_PREFIX == "prompt"
+        assert Prompt.make_key("my_prompt") == "prompt:my_prompt"
+
+    def test_tool_key_property(self):
+        """Test that Tool.key returns prefixed key with version sentinel."""
+        tool = Tool(name="greet", description="A greeting tool", parameters={})
+        assert tool.key == "tool:greet@"
+
+    def test_prompt_key_property(self):
+        """Test that Prompt.key returns prefixed key with version sentinel."""
+        prompt = Prompt(name="analyze", description="An analysis prompt")
+        assert prompt.key == "prompt:analyze@"
+
+    def test_warning_for_missing_key_prefix(self):
+        """Test that subclassing without KEY_PREFIX emits a warning."""
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+
+            class NoPrefix(FastMCPComponent):
+                pass
+
+            key_prefix_warnings = [
+                x for x in w if "does not define KEY_PREFIX" in str(x.message)
+            ]
+            assert len(key_prefix_warnings) == 1
+
+    def test_no_warning_when_key_prefix_defined(self):
+        """Test that subclassing with KEY_PREFIX does not emit a warning."""
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+
+            class WithPrefix(FastMCPComponent):
+                KEY_PREFIX = "custom"
+
+            key_prefix_warnings = [
+                x for x in w if "does not define KEY_PREFIX" in str(x.message)
+            ]
+            assert len(key_prefix_warnings) == 0
+            assert WithPrefix.make_key("test") == "custom:test"
+
+
+class TestGetFastMCPMetadata:
+    """Tests for get_fastmcp_metadata helper."""
+
+    def test_returns_fastmcp_namespace_when_dict(self):
+        meta = {"fastmcp": {"tags": ["a"]}, "_fastmcp": {"tags": ["b"]}}
+
+        assert get_fastmcp_metadata(meta) == {"tags": ["a"]}
+
+    def test_falls_back_to_legacy_namespace_when_dict(self):
+        meta = {"fastmcp": "invalid", "_fastmcp": {"tags": ["legacy"]}}
+
+        assert get_fastmcp_metadata(meta) == {"tags": ["legacy"]}
+
+    def test_ignores_non_dict_metadata(self):
+        assert get_fastmcp_metadata({"fastmcp": "invalid"}) == {}
+        assert get_fastmcp_metadata({"fastmcp": ["invalid"]}) == {}
+        assert get_fastmcp_metadata({"_fastmcp": "invalid"}) == {}
+
+
+class TestComponentEnableDisable:
+    """Tests for the enable/disable methods raising NotImplementedError."""
+
+    def test_enable_raises_not_implemented_error(self):
+        """Test that enable() raises NotImplementedError with migration guidance."""
+        component = FastMCPComponent(name="test")
+        with pytest.raises(NotImplementedError) as exc_info:
+            component.enable()
+        assert "server.enable" in str(exc_info.value)
+        assert "test" in str(exc_info.value)
+
+    def test_disable_raises_not_implemented_error(self):
+        """Test that disable() raises NotImplementedError with migration guidance."""
+        component = FastMCPComponent(name="test")
+        with pytest.raises(NotImplementedError) as exc_info:
+            component.disable()
+        assert "server.disable" in str(exc_info.value)
+        assert "test" in str(exc_info.value)
+
+    def test_tool_enable_raises_not_implemented(self):
+        """Test that Tool.enable() raises NotImplementedError."""
+        tool = Tool(name="my_tool", description="A tool", parameters={})
+        with pytest.raises(NotImplementedError) as exc_info:
+            tool.enable()
+        assert "tool:my_tool@" in str(exc_info.value)
+
+    def test_tool_disable_raises_not_implemented(self):
+        """Test that Tool.disable() raises NotImplementedError."""
+        tool = Tool(name="my_tool", description="A tool", parameters={})
+        with pytest.raises(NotImplementedError) as exc_info:
+            tool.disable()
+        assert "tool:my_tool@" in str(exc_info.value)
+
+    def test_prompt_enable_raises_not_implemented(self):
+        """Test that Prompt.enable() raises NotImplementedError."""
+        prompt = Prompt(name="my_prompt", description="A prompt")
+        with pytest.raises(NotImplementedError) as exc_info:
+            prompt.enable()
+        assert "prompt:my_prompt@" in str(exc_info.value)
+
+
+class TestFastMCPMeta:
+    """Tests for the FastMCPMeta TypedDict."""
+
+    def test_fastmcp_meta_structure(self):
+        """Test that FastMCPMeta has the expected structure."""
+        meta: FastMCPMeta = {"tags": ["tag1", "tag2"]}
+        assert meta["tags"] == ["tag1", "tag2"]
+
+    def test_fastmcp_meta_with_version(self):
+        """Test that FastMCPMeta can include version."""
+        meta: FastMCPMeta = {"tags": ["tag1"], "version": "v1.0.0"}
+        assert meta["tags"] == ["tag1"]
+        assert meta["version"] == "v1.0.0"
+
+    def test_fastmcp_meta_optional_fields(self):
+        """Test that FastMCPMeta fields are optional."""
+        meta: FastMCPMeta = {}
+        assert "tags" not in meta  # Should be optional
+        assert "version" not in meta  # Should be optional
+
+
+class TestEdgeCasesAndIntegration:
+    """Tests for edge cases and integration scenarios."""
+
+    def test_empty_tags_conversion(self):
+        """Test that empty tags are handled correctly."""
+        component = FastMCPComponent(name="test", tags=set())
+        assert component.tags == set()
+
+    def test_tags_with_none_values(self):
+        """Test tags behavior with various input types."""
+        # Test with None (through validator)
+        component = FastMCPComponent(name="test")
+        assert component.tags == set()
+
+    def test_get_meta_returns_copy(self):
+        """Test that get_meta returns a copy, not a reference to the original."""
+        component = FastMCPComponent(name="test", meta={"key": "value"})
+        meta = component.get_meta()
+        assert meta is not None
+        meta["key"] = "modified"
+        assert component.meta is not None
+        # get_meta returns a copy - mutating it doesn't affect the original
+        assert component.meta["key"] == "value"
+
+    def test_component_with_complex_meta(self):
+        """Test component with nested meta structures."""
+        complex_meta = {
+            "nested": {"level1": {"level2": "value"}},
+            "list": [1, 2, 3],
+            "bool": True,
+        }
+        component = FastMCPComponent(name="test", meta=complex_meta)
+        assert component.meta == complex_meta
+
+    def test_model_copy_preserves_all_attributes(self):
+        """Test that model_copy preserves all component attributes."""
+        component = FastMCPComponent(
+            name="test",
+            title="Title",
+            description="Description",
+            tags={"tag1", "tag2"},
+            meta={"key": "value"},
+        )
+        new_component = component.model_copy()
+
+        assert new_component.name == component.name
+        assert new_component.title == component.title
+        assert new_component.description == component.description
+        assert new_component.tags == component.tags
+        assert new_component.meta == component.meta
+        assert new_component.key == component.key
+
+    def test_model_copy_with_update(self):
+        """Test that model_copy works with update dict."""
+        component = FastMCPComponent(
+            name="test",
+            title="Original Title",
+            description="Original Description",
+            tags={"tag1"},
+        )
+
+        # Test with update (including name which affects .key)
+        updated_component = component.model_copy(
+            update={
+                "name": "new_name",
+                "title": "New Title",
+                "description": "New Description",
+            },
+        )
+
+        assert updated_component.name == "new_name"  # Updated
+        assert updated_component.title == "New Title"  # Updated
+        assert updated_component.description == "New Description"  # Updated
+        assert updated_component.tags == {"tag1"}  # Not in update, unchanged
+        assert (
+            updated_component.key == "new_name@"
+        )  # .key is computed from name with @ sentinel
+
+        # Original should be unchanged
+        assert component.name == "test"
+        assert component.title == "Original Title"
+        assert component.description == "Original Description"
+        assert component.key == "test@"  # Uses name as key with @ sentinel
+
+    def test_model_copy_deep_parameter(self):
+        """Test that model_copy respects the deep parameter."""
+        nested_dict = {"nested": {"value": 1}}
+        component = FastMCPComponent(name="test", meta=nested_dict)
+
+        # Shallow copy (default)
+        shallow_copy = component.model_copy()
+        assert shallow_copy.meta is not None
+        assert component.meta is not None
+        shallow_copy.meta["nested"]["value"] = 2
+        assert component.meta["nested"]["value"] == 2  # Original affected
+
+        # Deep copy
+        component.meta["nested"]["value"] = 1  # Reset
+        deep_copy = component.model_copy(deep=True)
+        assert deep_copy.meta is not None
+        deep_copy.meta["nested"]["value"] = 3
+        assert component.meta["nested"]["value"] == 1  # Original unaffected
diff --git a/tests/utilities/test_docstring_parsing.py b/tests/utilities/test_docstring_parsing.py
new file mode 100644
index 0000000..8fab08e
--- /dev/null
+++ b/tests/utilities/test_docstring_parsing.py
@@ -0,0 +1,562 @@
+"""Tests for docstring-to-schema parameter description extraction."""
+
+from typing import Annotated
+
+from pydantic import Field
+
+from fastmcp.tools.function_parsing import ParsedFunction
+from fastmcp.utilities.docstring_parsing import parse_docstring
+
+
+class TestGoogleStyle:
+    """Google-style docstrings (Args:/Arguments:)."""
+
+    def test_basic(self):
+        def fn(a: float, b: float) -> float:
+            """Add two numbers.
+
+            Args:
+                a: The first number.
+                b: The second number.
+            """
+            return a + b
+
+        parsed = parse_docstring(fn)
+        assert parsed.description == "Add two numbers."
+        assert parsed.parameters == {
+            "a": "The first number.",
+            "b": "The second number.",
+        }
+
+    def test_with_inline_types(self):
+        def fn(a: float, b: str) -> float:
+            """Do something.
+
+            Args:
+                a (float): The number.
+                b (str, optional): The string.
+            """
+            return a
+
+        parsed = parse_docstring(fn)
+        assert parsed.description == "Do something."
+        assert parsed.parameters == {"a": "The number.", "b": "The string."}
+
+    def test_returns_section_excluded(self):
+        def fn(a: float) -> float:
+            """Summary.
+
+            Args:
+                a: The input.
+
+            Returns:
+                The output.
+            """
+            return a
+
+        parsed = parse_docstring(fn)
+        assert parsed.description == "Summary."
+        assert parsed.parameters == {"a": "The input."}
+
+    def test_raises_section_excluded(self):
+        def fn(a: float) -> float:
+            """Summary.
+
+            Args:
+                a: The input.
+
+            Raises:
+                ValueError: If negative.
+            """
+            return a
+
+        parsed = parse_docstring(fn)
+        assert parsed.description == "Summary."
+        assert parsed.parameters == {"a": "The input."}
+
+    def test_example_section_excluded(self):
+        def fn(a: str) -> str:
+            """Run some code.
+
+            Example:
+                >>> fn("hello")
+                'hello'
+
+            Args:
+                a: The input.
+            """
+            return a
+
+        parsed = parse_docstring(fn)
+        assert parsed.description == "Run some code."
+        assert parsed.parameters == {"a": "The input."}
+
+    def test_multiline_param_description(self):
+        def fn(a: float) -> float:
+            """Summary.
+
+            Args:
+                a: A description that
+                    spans multiple lines.
+            """
+            return a
+
+        parsed = parse_docstring(fn)
+        assert parsed.description == "Summary."
+        assert "spans multiple lines" in parsed.parameters["a"]
+
+
+class TestNumpyStyle:
+    """NumPy-style docstrings (Parameters\\n----------)."""
+
+    def test_basic(self):
+        def fn(x: int, y: int) -> int:
+            """Multiply.
+
+            Parameters
+            ----------
+            x
+                The first integer.
+            y
+                The second integer.
+            """
+            return x * y
+
+        parsed = parse_docstring(fn)
+        assert parsed.description == "Multiply."
+        assert parsed.parameters == {
+            "x": "The first integer.",
+            "y": "The second integer.",
+        }
+
+    def test_with_types(self):
+        def fn(a: float, b: str) -> float:
+            """Do something.
+
+            Parameters
+            ----------
+            a : float
+                The number.
+            b : str
+                The string.
+            """
+            return a
+
+        parsed = parse_docstring(fn)
+        assert parsed.description == "Do something."
+        assert parsed.parameters == {"a": "The number.", "b": "The string."}
+
+
+class TestSphinxStyle:
+    """Sphinx-style docstrings (:param name:)."""
+
+    def test_basic(self):
+        def fn(name: str, age: int) -> str:
+            """Format a greeting.
+
+            :param name: The person's name.
+            :param age: The person's age.
+            """
+            return f"{name} is {age}"
+
+        parsed = parse_docstring(fn)
+        assert parsed.description == "Format a greeting."
+        assert parsed.parameters == {
+            "name": "The person's name.",
+            "age": "The person's age.",
+        }
+
+    def test_with_type_directive(self):
+        def fn(a: float, b: str) -> float:
+            """Summary.
+
+            :param a: The number.
+            :type a: float
+            :param b: The string.
+            :type b: str
+            """
+            return a
+
+        parsed = parse_docstring(fn)
+        assert parsed.description == "Summary."
+        assert parsed.parameters == {"a": "The number.", "b": "The string."}
+
+
+class TestEdgeCases:
+    """Unusual, malformed, or partially-correct docstrings."""
+
+    def test_no_docstring(self):
+        def fn(a: int) -> int:
+            return a
+
+        parsed = parse_docstring(fn)
+        assert parsed.description is None
+        assert parsed.parameters == {}
+
+    def test_summary_only(self):
+        def fn(a: int) -> int:
+            """Just a summary."""
+            return a
+
+        parsed = parse_docstring(fn)
+        assert parsed.description == "Just a summary."
+        assert parsed.parameters == {}
+
+    def test_multi_paragraph_description(self):
+        def fn(a: float) -> float:
+            """Summary line.
+
+            More detailed explanation here
+            spanning multiple lines.
+
+            Another paragraph.
+
+            Args:
+                a: The number.
+            """
+            return a
+
+        parsed = parse_docstring(fn)
+        # Full description (summary + body) should be preserved
+        assert parsed.description is not None
+        assert "Summary line." in parsed.description
+        assert "More detailed explanation" in parsed.description
+        assert "Another paragraph." in parsed.description
+        # Args section should not bleed into description
+        assert "The number" not in parsed.description
+        assert parsed.parameters == {"a": "The number."}
+
+    def test_multiline_summary(self):
+        def fn(a: float) -> float:
+            """Multi-line summary
+            continues on next line.
+
+            Args:
+                a: The number.
+            """
+            return a
+
+        parsed = parse_docstring(fn)
+        assert parsed.description is not None
+        assert "Multi-line summary" in parsed.description
+        assert "continues on next line" in parsed.description
+        assert parsed.parameters == {"a": "The number."}
+
+    def test_missing_colon_after_args_keyword(self):
+        """Malformed: 'Args' without colon is not a valid section."""
+
+        def fn(a: float) -> float:
+            """Summary.
+
+            Args
+                a: Maybe the number?
+            """
+            return a
+
+        parsed = parse_docstring(fn)
+        # Parser shouldn't pick this up as an Args section
+        assert parsed.parameters == {}
+
+    def test_empty_args_section(self):
+        def fn(a: float) -> float:
+            """Summary.
+
+            Args:
+            """
+            return a
+
+        parsed = parse_docstring(fn)
+        assert parsed.parameters == {}
+
+    def test_param_name_not_in_function_signature(self):
+        """Docstring documents a param that doesn't exist on the function."""
+
+        def fn(a: float) -> float:
+            """Summary.
+
+            Args:
+                nonexistent: Wrong param name.
+            """
+            return a
+
+        parsed = parse_docstring(fn)
+        # parse_docstring returns whatever the docstring says —
+        # filtering happens at the schema injection level
+        assert parsed.parameters == {"nonexistent": "Wrong param name."}
+
+    def test_async_function(self):
+        async def fn(a: float) -> float:
+            """Async summary.
+
+            Args:
+                a: The number.
+            """
+            return a
+
+        parsed = parse_docstring(fn)
+        assert parsed.description == "Async summary."
+        assert parsed.parameters == {"a": "The number."}
+
+
+class TestParsedFunctionIntegration:
+    """Tests for docstring flowing through ParsedFunction.from_function."""
+
+    def test_description_is_summary_only(self):
+        def fn(a: float) -> float:
+            """The summary line.
+
+            Args:
+                a: Some param.
+
+            Returns:
+                Something.
+            """
+            return a
+
+        p = ParsedFunction.from_function(fn)
+        assert p.description == "The summary line."
+
+    def test_param_descriptions_in_schema(self):
+        def fn(a: float, b: str) -> str:
+            """Do something.
+
+            Args:
+                a: The number.
+                b: The string.
+            """
+            return str(a) + b
+
+        p = ParsedFunction.from_function(fn)
+        assert p.input_schema["properties"]["a"]["description"] == "The number."
+        assert p.input_schema["properties"]["b"]["description"] == "The string."
+
+    def test_numpy_style_integration(self):
+        def fn(a: float, b: str) -> str:
+            """Summary.
+
+            Parameters
+            ----------
+            a : float
+                The number.
+            b : str
+                The string.
+            """
+            return str(a) + b
+
+        p = ParsedFunction.from_function(fn)
+        assert p.description == "Summary."
+        assert p.input_schema["properties"]["a"]["description"] == "The number."
+        assert p.input_schema["properties"]["b"]["description"] == "The string."
+
+    def test_sphinx_style_integration(self):
+        def fn(a: float, b: str) -> str:
+            """Summary.
+
+            :param a: The number.
+            :param b: The string.
+            """
+            return str(a) + b
+
+        p = ParsedFunction.from_function(fn)
+        assert p.description == "Summary."
+        assert p.input_schema["properties"]["a"]["description"] == "The number."
+        assert p.input_schema["properties"]["b"]["description"] == "The string."
+
+    def test_field_description_takes_precedence(self):
+        def fn(
+            a: Annotated[float, Field(description="From Field")],
+            b: float,
+        ) -> float:
+            """Add.
+
+            Args:
+                a: From docstring.
+                b: Also from docstring.
+            """
+            return a + b
+
+        p = ParsedFunction.from_function(fn)
+        assert p.input_schema["properties"]["a"]["description"] == "From Field"
+        assert (
+            p.input_schema["properties"]["b"]["description"] == "Also from docstring."
+        )
+
+    def test_annotated_string_takes_precedence(self):
+        def fn(
+            a: Annotated[float, "From annotation"],
+            b: float,
+        ) -> float:
+            """Add.
+
+            Args:
+                a: From docstring.
+                b: Also from docstring.
+            """
+            return a + b
+
+        p = ParsedFunction.from_function(fn)
+        assert p.input_schema["properties"]["a"]["description"] == "From annotation"
+        assert (
+            p.input_schema["properties"]["b"]["description"] == "Also from docstring."
+        )
+
+    def test_no_docstring_no_descriptions(self):
+        def fn(a: float) -> float:
+            return a
+
+        p = ParsedFunction.from_function(fn)
+        assert p.description is None
+        assert "description" not in p.input_schema["properties"]["a"]
+
+    def test_docstring_without_args_section(self):
+        def fn(a: float) -> float:
+            """Just a summary."""
+            return a
+
+        p = ParsedFunction.from_function(fn)
+        assert p.description == "Just a summary."
+        assert "description" not in p.input_schema["properties"]["a"]
+
+    def test_partial_params_documented(self):
+        """Only some params documented — others remain undescribed."""
+
+        def fn(a: float, b: float, c: float) -> float:
+            """Add numbers.
+
+            Args:
+                a: Documented.
+            """
+            return a + b + c
+
+        p = ParsedFunction.from_function(fn)
+        assert p.input_schema["properties"]["a"]["description"] == "Documented."
+        assert "description" not in p.input_schema["properties"]["b"]
+        assert "description" not in p.input_schema["properties"]["c"]
+
+    def test_nonexistent_param_in_docstring_ignored(self):
+        """Docstring mentions a param that doesn't exist — silently skipped."""
+
+        def fn(a: float) -> float:
+            """Summary.
+
+            Args:
+                a: The real one.
+                ghost: Doesn't exist.
+            """
+            return a
+
+        p = ParsedFunction.from_function(fn)
+        assert p.input_schema["properties"]["a"]["description"] == "The real one."
+        # No crash, no ghost in properties
+        assert "ghost" not in p.input_schema["properties"]
+
+    def test_types_in_docstring_dont_override_schema_types(self):
+        """A '(str)' in the docstring must not change the schema's type."""
+
+        def fn(a: float) -> float:
+            """Summary.
+
+            Args:
+                a (str): A description, but the type is wrong.
+            """
+            return a
+
+        p = ParsedFunction.from_function(fn)
+        # Schema type comes from the annotation, not the docstring
+        assert p.input_schema["properties"]["a"]["type"] == "number"
+        assert (
+            p.input_schema["properties"]["a"]["description"]
+            == "A description, but the type is wrong."
+        )
+
+    def test_multi_paragraph_description_preserved(self):
+        def fn(a: float) -> float:
+            """Short summary.
+
+            A longer explanation that provides
+            additional context.
+
+            Args:
+                a: The number.
+            """
+            return a
+
+        p = ParsedFunction.from_function(fn)
+        assert p.description is not None
+        assert "Short summary" in p.description
+        assert "longer explanation" in p.description
+        assert "The number" not in p.description
+
+    def test_async_function_integration(self):
+        async def fn(a: float) -> float:
+            """Async summary.
+
+            Args:
+                a: The number.
+            """
+            return a
+
+        p = ParsedFunction.from_function(fn)
+        assert p.description == "Async summary."
+        assert p.input_schema["properties"]["a"]["description"] == "The number."
+
+    def test_callable_class_sources_description_from_class(self):
+        """Class docstring drives the tool description (it describes what the
+        tool IS), while __call__'s Args section drives parameter descriptions
+        (its params are what the schema actually exposes)."""
+
+        class MyTool:
+            """Class-level description."""
+
+            def __call__(self, x: int) -> int:
+                """Internal call doc.
+
+                Args:
+                    x: From call.
+                """
+                return x
+
+        p = ParsedFunction.from_function(MyTool())
+        # Class docstring wins for the description
+        assert p.description == "Class-level description."
+        # __call__'s Args wins for the parameter description
+        assert p.input_schema["properties"]["x"]["description"] == "From call."
+
+    def test_callable_class_does_not_inherit_class_param_descriptions(self):
+        """The class docstring's Args section typically describes __init__.
+        Even when param names overlap with __call__, those descriptions must
+        not leak into __call__'s parameter schema."""
+
+        class MyTool:
+            """Describes what the tool does.
+
+            Args:
+                x: Constructor argument (should NOT appear on __call__'s x).
+            """
+
+            def __init__(self, x: str) -> None:
+                self.x = x
+
+            def __call__(self, x: int) -> int:
+                return x
+
+        p = ParsedFunction.from_function(MyTool("config"))
+        assert p.description == "Describes what the tool does."
+        # x's description does NOT come from the class's constructor-focused Args
+        assert "description" not in p.input_schema["properties"]["x"]
+
+    def test_callable_class_falls_back_to_call_description(self):
+        """If the class has no docstring, fall back to __call__'s description."""
+
+        class MyTool:
+            def __call__(self, x: int) -> int:
+                """Call-level description.
+
+                Args:
+                    x: From call.
+                """
+                return x
+
+        p = ParsedFunction.from_function(MyTool())
+        assert p.description == "Call-level description."
+        assert p.input_schema["properties"]["x"]["description"] == "From call."
diff --git a/tests/utilities/test_http.py b/tests/utilities/test_http.py
new file mode 100644
index 0000000..f03dd08
--- /dev/null
+++ b/tests/utilities/test_http.py
@@ -0,0 +1,15 @@
+"""Tests for HTTP utility helpers."""
+
+import socket
+
+from fastmcp.utilities.http import find_available_port
+
+
+def test_find_available_port_returns_bindable_loopback_port():
+    port = find_available_port()
+
+    assert isinstance(port, int)
+    assert port > 0
+
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as server:
+        server.bind(("127.0.0.1", port))
diff --git a/tests/utilities/test_inspect.py b/tests/utilities/test_inspect.py
new file mode 100644
index 0000000..9b9b70d
--- /dev/null
+++ b/tests/utilities/test_inspect.py
@@ -0,0 +1,604 @@
+"""Tests for the inspect.py module."""
+
+import importlib.metadata
+
+from mcp.server.mcpserver import MCPServer as SDKServer
+
+import fastmcp
+from fastmcp import Client, FastMCP
+from fastmcp.utilities.inspect import (
+    FastMCPInfo,
+    ToolInfo,
+    inspect_fastmcp,
+    inspect_fastmcp_v1,
+)
+
+
+class TestFastMCPInfo:
+    """Tests for the FastMCPInfo dataclass."""
+
+    def test_fastmcp_info_creation(self):
+        """Test that FastMCPInfo can be created with all required fields."""
+        tool = ToolInfo(
+            key="tool1",
+            name="tool1",
+            description="Test tool",
+            input_schema={},
+            output_schema={
+                "type": "object",
+                "properties": {"result": {"type": "string"}},
+            },
+        )
+        info = FastMCPInfo(
+            name="TestServer",
+            instructions="Test instructions",
+            fastmcp_version="1.0.0",
+            mcp_version="1.0.0",
+            server_generation=2,
+            version="1.0.0",
+            website_url=None,
+            icons=None,
+            tools=[tool],
+            prompts=[],
+            resources=[],
+            templates=[],
+            capabilities={"tools": {"listChanged": True}},
+        )
+
+        assert info.name == "TestServer"
+        assert info.instructions == "Test instructions"
+        assert info.fastmcp_version == "1.0.0"
+        assert info.mcp_version == "1.0.0"
+        assert info.server_generation == 2
+        assert info.version == "1.0.0"
+        assert len(info.tools) == 1
+        assert info.tools[0].name == "tool1"
+        assert info.capabilities == {"tools": {"listChanged": True}}
+
+    def test_fastmcp_info_with_none_instructions(self):
+        """Test that FastMCPInfo works with None instructions."""
+        info = FastMCPInfo(
+            name="TestServer",
+            instructions=None,
+            fastmcp_version="1.0.0",
+            mcp_version="1.0.0",
+            server_generation=2,
+            version="1.0.0",
+            website_url=None,
+            icons=None,
+            tools=[],
+            prompts=[],
+            resources=[],
+            templates=[],
+            capabilities={},
+        )
+
+        assert info.instructions is None
+
+
+class TestGetFastMCPInfo:
+    """Tests for the get_fastmcp_info function."""
+
+    async def test_empty_server(self):
+        """Test get_fastmcp_info with an empty server."""
+        mcp = FastMCP("EmptyServer")
+
+        info = await inspect_fastmcp(mcp)
+
+        assert info.name == "EmptyServer"
+        assert info.instructions is None
+        assert info.fastmcp_version == fastmcp.__version__
+        assert info.mcp_version == importlib.metadata.version("mcp")
+        assert info.server_generation == 2  # v2 server
+        assert info.version == fastmcp.__version__
+        assert info.tools == []
+        assert info.prompts == []
+        assert info.resources == []
+        assert info.templates == []
+        assert "tools" in info.capabilities
+        assert "resources" in info.capabilities
+        assert "prompts" in info.capabilities
+        assert "logging" in info.capabilities
+
+    async def test_server_with_instructions(self):
+        """Test get_fastmcp_info with a server that has instructions."""
+        mcp = FastMCP("InstructionsServer", instructions="Test instructions")
+        info = await inspect_fastmcp(mcp)
+        assert info.instructions == "Test instructions"
+
+    async def test_server_with_version(self):
+        """Test get_fastmcp_info with a server that has a version."""
+        mcp = FastMCP("VersionServer", version="1.2.3")
+        info = await inspect_fastmcp(mcp)
+        assert info.version == "1.2.3"
+
+    async def test_server_with_tools(self):
+        """Test get_fastmcp_info with a server that has tools."""
+        mcp = FastMCP("ToolServer")
+
+        @mcp.tool
+        def add_numbers(a: int, b: int) -> int:
+            return a + b
+
+        @mcp.tool
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        info = await inspect_fastmcp(mcp)
+
+        assert info.name == "ToolServer"
+        assert len(info.tools) == 2
+        tool_names = [tool.name for tool in info.tools]
+        assert "add_numbers" in tool_names
+        assert "greet" in tool_names
+
+    async def test_server_with_resources(self):
+        """Test get_fastmcp_info with a server that has resources."""
+        mcp = FastMCP("ResourceServer")
+
+        @mcp.resource("resource://static")
+        def get_static_data() -> str:
+            return "Static data"
+
+        @mcp.resource("resource://dynamic/{param}")
+        def get_dynamic_data(param: str) -> str:
+            return f"Dynamic data: {param}"
+
+        info = await inspect_fastmcp(mcp)
+
+        assert info.name == "ResourceServer"
+        assert len(info.resources) == 1  # Static resource
+        assert len(info.templates) == 1  # Dynamic resource becomes template
+        resource_uris = [res.uri for res in info.resources]
+        template_uris = [tmpl.uri_template for tmpl in info.templates]
+        assert "resource://static" in resource_uris
+        assert "resource://dynamic/{param}" in template_uris
+
+    async def test_server_with_prompts(self):
+        """Test get_fastmcp_info with a server that has prompts."""
+        mcp = FastMCP("PromptServer")
+
+        @mcp.prompt
+        def analyze_data(data: str) -> list:
+            return [{"role": "user", "content": f"Analyze: {data}"}]
+
+        @mcp.prompt("custom_prompt")
+        def custom_analysis(text: str) -> list:
+            return [{"role": "user", "content": f"Custom: {text}"}]
+
+        info = await inspect_fastmcp(mcp)
+
+        assert info.name == "PromptServer"
+        assert len(info.prompts) == 2
+        prompt_names = [prompt.name for prompt in info.prompts]
+        assert "analyze_data" in prompt_names
+        assert "custom_prompt" in prompt_names
+
+    async def test_comprehensive_server(self):
+        """Test get_fastmcp_info with a server that has all component types."""
+        mcp = FastMCP("ComprehensiveServer", instructions="A server with everything")
+
+        # Add a tool
+        @mcp.tool
+        def calculate(x: int, y: int) -> int:
+            return x * y
+
+        # Add a resource
+        @mcp.resource("resource://data")
+        def get_data() -> str:
+            return "Some data"
+
+        # Add a template
+        @mcp.resource("resource://item/{id}")
+        def get_item(id: str) -> str:
+            return f"Item {id}"
+
+        # Add a prompt
+        @mcp.prompt
+        def analyze(content: str) -> list:
+            return [{"role": "user", "content": content}]
+
+        info = await inspect_fastmcp(mcp)
+
+        assert info.name == "ComprehensiveServer"
+        assert info.instructions == "A server with everything"
+        assert info.fastmcp_version == fastmcp.__version__
+
+        # Check all components are present
+        assert len(info.tools) == 1
+        tool_names = [tool.name for tool in info.tools]
+        assert "calculate" in tool_names
+
+        assert len(info.resources) == 1
+        resource_uris = [res.uri for res in info.resources]
+        assert "resource://data" in resource_uris
+
+        assert len(info.templates) == 1
+        template_uris = [tmpl.uri_template for tmpl in info.templates]
+        assert "resource://item/{id}" in template_uris
+
+        assert len(info.prompts) == 1
+        prompt_names = [prompt.name for prompt in info.prompts]
+        assert "analyze" in prompt_names
+
+        # Check capabilities
+        assert "tools" in info.capabilities
+        assert "resources" in info.capabilities
+        assert "prompts" in info.capabilities
+        assert "logging" in info.capabilities
+
+    async def test_server_no_instructions(self):
+        """Test get_fastmcp_info with a server that has no instructions."""
+        mcp = FastMCP("NoInstructionsServer")
+
+        info = await inspect_fastmcp(mcp)
+
+        assert info.name == "NoInstructionsServer"
+        assert info.instructions is None
+
+    async def test_server_with_client_integration(self):
+        """Test that the extracted info matches what a client would see."""
+        mcp = FastMCP("IntegrationServer")
+
+        @mcp.tool
+        def test_tool() -> str:
+            return "test"
+
+        @mcp.resource("resource://test")
+        def test_resource() -> str:
+            return "test resource"
+
+        @mcp.prompt
+        def test_prompt() -> list:
+            return [{"role": "user", "content": "test"}]
+
+        # Get info using our function
+        info = await inspect_fastmcp(mcp)
+
+        # Verify using client
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            resources = await client.list_resources()
+            prompts = await client.list_prompts()
+
+            assert len(info.tools) == len(tools)
+            assert len(info.resources) == len(resources)
+            assert len(info.prompts) == len(prompts)
+
+            assert info.tools[0].name == tools[0].name
+            assert info.resources[0].uri == str(resources[0].uri)
+            assert info.prompts[0].name == prompts[0].name
+
+    async def test_inspect_respects_tag_filtering(self):
+        """Test that inspect omits components filtered out by include_tags/exclude_tags.
+
+        Regression test for Issue #2032: inspect command was showing components
+        that were filtered out by tag rules, causing confusion when those
+        components weren't actually available to clients.
+        """
+        # Create server with include_tags that will filter out untagged components
+        mcp = FastMCP("FilteredServer")
+        mcp.enable(tags={"fetch", "analyze", "create"}, only=True)
+
+        # Add tools with and without matching tags
+        @mcp.tool(tags={"fetch"})
+        def tagged_tool() -> str:
+            """Tool with matching tag - should be visible."""
+            return "visible"
+
+        @mcp.tool
+        def untagged_tool() -> str:
+            """Tool without tags - should be filtered out."""
+            return "hidden"
+
+        # Add resources with and without matching tags
+        @mcp.resource("resource://tagged", tags={"analyze"})
+        def tagged_resource() -> str:
+            """Resource with matching tag - should be visible."""
+            return "visible resource"
+
+        @mcp.resource("resource://untagged")
+        def untagged_resource() -> str:
+            """Resource without tags - should be filtered out."""
+            return "hidden resource"
+
+        # Add templates with and without matching tags
+        @mcp.resource("resource://tagged/{id}", tags={"create"})
+        def tagged_template(id: str) -> str:
+            """Template with matching tag - should be visible."""
+            return f"visible template {id}"
+
+        @mcp.resource("resource://untagged/{id}")
+        def untagged_template(id: str) -> str:
+            """Template without tags - should be filtered out."""
+            return f"hidden template {id}"
+
+        # Add prompts with and without matching tags
+        @mcp.prompt(tags={"fetch"})
+        def tagged_prompt() -> list:
+            """Prompt with matching tag - should be visible."""
+            return [{"role": "user", "content": "visible prompt"}]
+
+        @mcp.prompt
+        def untagged_prompt() -> list:
+            """Prompt without tags - should be filtered out."""
+            return [{"role": "user", "content": "hidden prompt"}]
+
+        # Get inspect info
+        info = await inspect_fastmcp(mcp)
+
+        # Verify only tagged components are visible
+        assert len(info.tools) == 1
+        assert info.tools[0].name == "tagged_tool"
+
+        assert len(info.resources) == 1
+        assert info.resources[0].uri == "resource://tagged"
+
+        assert len(info.templates) == 1
+        assert info.templates[0].uri_template == "resource://tagged/{id}"
+
+        assert len(info.prompts) == 1
+        assert info.prompts[0].name == "tagged_prompt"
+
+        # Verify this matches what a client would see
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            resources = await client.list_resources()
+            templates = await client.list_resource_templates()
+            prompts = await client.list_prompts()
+
+            assert len(info.tools) == len(tools)
+            assert len(info.resources) == len(resources)
+            assert len(info.templates) == len(templates)
+            assert len(info.prompts) == len(prompts)
+
+    async def test_inspect_respects_tag_filtering_with_mounted_servers(self):
+        """Test that inspect applies tag filtering to mounted servers.
+
+        Verifies that when a parent server has tag filters, those filters
+        are respected when inspecting components from mounted servers.
+        """
+        # Create a mounted server with various tagged and untagged components
+        mounted = FastMCP("MountedServer")
+
+        @mounted.tool(tags={"allowed"})
+        def allowed_tool() -> str:
+            return "allowed"
+
+        @mounted.tool(tags={"blocked"})
+        def blocked_tool() -> str:
+            return "blocked"
+
+        @mounted.tool
+        def untagged_tool() -> str:
+            return "untagged"
+
+        @mounted.resource("resource://allowed", tags={"allowed"})
+        def allowed_resource() -> str:
+            return "allowed resource"
+
+        @mounted.resource("resource://blocked", tags={"blocked"})
+        def blocked_resource() -> str:
+            return "blocked resource"
+
+        @mounted.prompt(tags={"allowed"})
+        def allowed_prompt() -> list:
+            return [{"role": "user", "content": "allowed"}]
+
+        @mounted.prompt(tags={"blocked"})
+        def blocked_prompt() -> list:
+            return [{"role": "user", "content": "blocked"}]
+
+        # Create parent server with tag filtering
+        parent = FastMCP("ParentServer")
+        parent.enable(tags={"allowed"}, only=True)
+        parent.mount(mounted)
+
+        # Get inspect info
+        info = await inspect_fastmcp(parent)
+
+        # Only components with "allowed" tag should be visible
+        tool_names = [t.name for t in info.tools]
+        assert "allowed_tool" in tool_names
+        assert "blocked_tool" not in tool_names
+        assert "untagged_tool" not in tool_names
+
+        resource_uris = [r.uri for r in info.resources]
+        assert "resource://allowed" in resource_uris
+        assert "resource://blocked" not in resource_uris
+
+        prompt_names = [p.name for p in info.prompts]
+        assert "allowed_prompt" in prompt_names
+        assert "blocked_prompt" not in prompt_names
+
+        # Verify this matches what a client would see
+        async with Client(parent) as client:
+            tools = await client.list_tools()
+            resources = await client.list_resources()
+            prompts = await client.list_prompts()
+
+            assert len(info.tools) == len(tools)
+            assert len(info.resources) == len(resources)
+            assert len(info.prompts) == len(prompts)
+
+    async def test_inspect_parent_filters_override_mounted_server_filters(self):
+        """Test that parent server tag filters apply to mounted servers.
+
+        Even if a mounted server has no tag filters of its own,
+        the parent server's filters should still apply.
+        """
+        # Create mounted server with NO tag filters (allows everything)
+        mounted = FastMCP("MountedServer")
+
+        @mounted.tool(tags={"production"})
+        def production_tool() -> str:
+            return "production"
+
+        @mounted.tool(tags={"development"})
+        def development_tool() -> str:
+            return "development"
+
+        @mounted.tool
+        def untagged_tool() -> str:
+            return "untagged"
+
+        # Create parent with exclude_tags - should filter mounted components
+        parent = FastMCP("ParentServer")
+        parent.disable(tags={"development"})
+        parent.mount(mounted)
+
+        # Get inspect info
+        info = await inspect_fastmcp(parent)
+
+        # Only production and untagged should be visible
+        tool_names = [t.name for t in info.tools]
+        assert "production_tool" in tool_names
+        assert "untagged_tool" in tool_names
+        assert "development_tool" not in tool_names
+
+        # Verify this matches what a client would see
+        async with Client(parent) as client:
+            tools = await client.list_tools()
+            assert len(info.tools) == len(tools)
+
+
+class TestFastMCP1xCompatibility:
+    """Tests for FastMCP 1.x compatibility."""
+
+    async def test_fastmcp1x_empty_server(self):
+        """Test get_fastmcp_info_v1 with an empty FastMCP1x server."""
+        mcp = SDKServer("Test1x")
+
+        info = await inspect_fastmcp_v1(mcp)
+
+        assert info.name == "Test1x"
+        assert info.instructions is None
+        assert info.fastmcp_version == fastmcp.__version__  # CLI version
+        assert info.mcp_version == importlib.metadata.version("mcp")
+        assert info.server_generation == 1  # v1 server
+        assert info.version is None
+        assert info.tools == []
+        assert info.prompts == []
+        assert info.resources == []
+        assert info.templates == []  # No templates added in this test
+        assert "tools" in info.capabilities
+
+    async def test_fastmcp1x_with_tools(self):
+        """Test get_fastmcp_info_v1 with a FastMCP1x server that has tools."""
+        mcp = SDKServer("Test1x")
+
+        @mcp.tool()
+        def add_numbers(a: int, b: int) -> int:
+            return a + b
+
+        @mcp.tool()
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        info = await inspect_fastmcp_v1(mcp)
+
+        assert info.name == "Test1x"
+        assert len(info.tools) == 2
+        tool_names = [tool.name for tool in info.tools]
+        assert "add_numbers" in tool_names
+        assert "greet" in tool_names
+
+    async def test_fastmcp1x_with_resources(self):
+        """Test get_fastmcp_info_v1 with a FastMCP1x server that has resources."""
+        mcp = SDKServer("Test1x")
+
+        @mcp.resource("resource://data")
+        def get_data() -> str:
+            return "Some data"
+
+        info = await inspect_fastmcp_v1(mcp)
+
+        assert info.name == "Test1x"
+        assert len(info.resources) == 1
+        resource_uris = [res.uri for res in info.resources]
+        assert "resource://data" in resource_uris
+        assert len(info.templates) == 0  # No templates added in this test
+        assert info.server_generation == 1  # v1 server
+
+    async def test_fastmcp1x_with_prompts(self):
+        """Test get_fastmcp_info_v1 with a FastMCP1x server that has prompts."""
+        mcp = SDKServer("Test1x")
+
+        @mcp.prompt("analyze")
+        def analyze_data(data: str) -> list:
+            return [{"role": "user", "content": f"Analyze: {data}"}]
+
+        info = await inspect_fastmcp_v1(mcp)
+
+        assert info.name == "Test1x"
+        assert len(info.prompts) == 1
+        prompt_names = [prompt.name for prompt in info.prompts]
+        assert "analyze" in prompt_names
+
+    async def test_dispatcher_with_fastmcp1x(self):
+        """Test that the main get_fastmcp_info function correctly dispatches to v1."""
+        mcp = SDKServer("Test1x")
+
+        @mcp.tool()
+        def test_tool() -> str:
+            return "test"
+
+        info = await inspect_fastmcp(mcp)
+
+        assert info.name == "Test1x"
+        assert len(info.tools) == 1
+        tool_names = [tool.name for tool in info.tools]
+        assert "test_tool" in tool_names
+        assert len(info.templates) == 0  # No templates added in this test
+        assert info.server_generation == 1  # v1 server
+
+    async def test_dispatcher_with_fastmcp2x(self):
+        """Test that the main get_fastmcp_info function correctly dispatches to v2."""
+        mcp = FastMCP("Test2x")
+
+        @mcp.tool
+        def test_tool() -> str:
+            return "test"
+
+        info = await inspect_fastmcp(mcp)
+
+        assert info.name == "Test2x"
+        assert len(info.tools) == 1
+        tool_names = [tool.name for tool in info.tools]
+        assert "test_tool" in tool_names
+
+    async def test_fastmcp1x_vs_fastmcp2x_comparison(self):
+        """Test that both versions can be inspected and compared."""
+        mcp1x = SDKServer("Test1x")
+        mcp2x = FastMCP("Test2x")
+
+        @mcp1x.tool()
+        def tool1x() -> str:
+            return "1x"
+
+        @mcp2x.tool
+        def tool2x() -> str:
+            return "2x"
+
+        info1x = await inspect_fastmcp(mcp1x)
+        info2x = await inspect_fastmcp(mcp2x)
+
+        assert info1x.name == "Test1x"
+        assert info2x.name == "Test2x"
+        assert len(info1x.tools) == 1
+        assert len(info2x.tools) == 1
+
+        tool1x_names = [tool.name for tool in info1x.tools]
+        tool2x_names = [tool.name for tool in info2x.tools]
+        assert "tool1x" in tool1x_names
+        assert "tool2x" in tool2x_names
+
+        # Check server versions
+        assert info1x.server_generation == 1  # v1
+        assert info2x.server_generation == 2  # v2
+        assert info1x.version is None
+        assert info2x.version == fastmcp.__version__
+
+        # No templates added in these tests
+        assert len(info1x.templates) == 0
+        assert len(info2x.templates) == 0
diff --git a/tests/utilities/test_inspect_icons.py b/tests/utilities/test_inspect_icons.py
new file mode 100644
index 0000000..14c37f6
--- /dev/null
+++ b/tests/utilities/test_inspect_icons.py
@@ -0,0 +1,539 @@
+"""Tests for icon extraction and formatting functions in inspect.py."""
+
+import importlib.metadata
+
+from mcp.server.mcpserver import MCPServer as SDKServer
+
+import fastmcp
+from fastmcp import FastMCP
+from fastmcp.utilities.inspect import (
+    InspectFormat,
+    format_fastmcp_info,
+    format_info,
+    format_mcp_info,
+    inspect_fastmcp,
+    inspect_fastmcp_v1,
+)
+
+
+class TestIconExtraction:
+    """Tests for icon extraction in inspect."""
+
+    async def test_server_icons_and_website(self):
+        """Test that server-level icons and website_url are extracted."""
+        from mcp_types import Icon
+
+        mcp = FastMCP(
+            "IconServer",
+            website_url="https://example.com",
+            icons=[
+                Icon(
+                    src="https://example.com/icon.png",
+                    mime_type="image/png",
+                    sizes=["48x48"],
+                )
+            ],
+        )
+
+        info = await inspect_fastmcp(mcp)
+
+        assert info.website_url == "https://example.com"
+        assert info.icons is not None
+        assert len(info.icons) == 1
+        assert info.icons[0]["src"] == "https://example.com/icon.png"
+        assert info.icons[0]["mimeType"] == "image/png"
+        assert info.icons[0]["sizes"] == ["48x48"]
+
+    async def test_server_without_icons(self):
+        """Test that servers without icons have None for icons and website_url."""
+        mcp = FastMCP("NoIconServer")
+
+        info = await inspect_fastmcp(mcp)
+
+        assert info.website_url is None
+        assert info.icons is None
+
+    async def test_tool_icons(self):
+        """Test that tool icons are extracted."""
+        from mcp_types import Icon
+
+        mcp = FastMCP("ToolIconServer")
+
+        @mcp.tool(
+            icons=[
+                Icon(
+                    src="https://example.com/calculator.png",
+                    mime_type="image/png",
+                )
+            ]
+        )
+        def calculate(x: int) -> int:
+            """Calculate something."""
+            return x * 2
+
+        @mcp.tool
+        def no_icon_tool() -> str:
+            """Tool without icon."""
+            return "no icon"
+
+        info = await inspect_fastmcp(mcp)
+
+        assert len(info.tools) == 2
+
+        # Find the calculate tool
+        calculate_tool = next(t for t in info.tools if t.name == "calculate")
+        assert calculate_tool.icons is not None
+        assert len(calculate_tool.icons) == 1
+        assert calculate_tool.icons[0]["src"] == "https://example.com/calculator.png"
+
+        # Find the no_icon tool
+        no_icon = next(t for t in info.tools if t.name == "no_icon_tool")
+        assert no_icon.icons is None
+
+    async def test_resource_icons(self):
+        """Test that resource icons are extracted."""
+        from mcp_types import Icon
+
+        mcp = FastMCP("ResourceIconServer")
+
+        @mcp.resource(
+            "resource://data",
+            icons=[Icon(src="https://example.com/data.png", mime_type="image/png")],
+        )
+        def get_data() -> str:
+            """Get data."""
+            return "data"
+
+        @mcp.resource("resource://no-icon")
+        def get_no_icon() -> str:
+            """Get data without icon."""
+            return "no icon"
+
+        info = await inspect_fastmcp(mcp)
+
+        assert len(info.resources) == 2
+
+        # Find the data resource
+        data_resource = next(r for r in info.resources if r.uri == "resource://data")
+        assert data_resource.icons is not None
+        assert len(data_resource.icons) == 1
+        assert data_resource.icons[0]["src"] == "https://example.com/data.png"
+
+        # Find the no-icon resource
+        no_icon = next(r for r in info.resources if r.uri == "resource://no-icon")
+        assert no_icon.icons is None
+
+    async def test_template_icons(self):
+        """Test that resource template icons are extracted."""
+        from mcp_types import Icon
+
+        mcp = FastMCP("TemplateIconServer")
+
+        @mcp.resource(
+            "resource://user/{id}",
+            icons=[Icon(src="https://example.com/user.png", mime_type="image/png")],
+        )
+        def get_user(id: str) -> str:
+            """Get user by ID."""
+            return f"user {id}"
+
+        @mcp.resource("resource://item/{id}")
+        def get_item(id: str) -> str:
+            """Get item without icon."""
+            return f"item {id}"
+
+        info = await inspect_fastmcp(mcp)
+
+        assert len(info.templates) == 2
+
+        # Find the user template
+        user_template = next(
+            t for t in info.templates if t.uri_template == "resource://user/{id}"
+        )
+        assert user_template.icons is not None
+        assert len(user_template.icons) == 1
+        assert user_template.icons[0]["src"] == "https://example.com/user.png"
+
+        # Find the no-icon template
+        no_icon = next(
+            t for t in info.templates if t.uri_template == "resource://item/{id}"
+        )
+        assert no_icon.icons is None
+
+    async def test_prompt_icons(self):
+        """Test that prompt icons are extracted."""
+        from mcp_types import Icon
+
+        mcp = FastMCP("PromptIconServer")
+
+        @mcp.prompt(
+            icons=[Icon(src="https://example.com/analyze.png", mime_type="image/png")]
+        )
+        def analyze(data: str) -> list:
+            """Analyze data."""
+            return [{"role": "user", "content": f"Analyze: {data}"}]
+
+        @mcp.prompt
+        def no_icon_prompt(text: str) -> list:
+            """Prompt without icon."""
+            return [{"role": "user", "content": text}]
+
+        info = await inspect_fastmcp(mcp)
+
+        assert len(info.prompts) == 2
+
+        # Find the analyze prompt
+        analyze_prompt = next(p for p in info.prompts if p.name == "analyze")
+        assert analyze_prompt.icons is not None
+        assert len(analyze_prompt.icons) == 1
+        assert analyze_prompt.icons[0]["src"] == "https://example.com/analyze.png"
+
+        # Find the no-icon prompt
+        no_icon = next(p for p in info.prompts if p.name == "no_icon_prompt")
+        assert no_icon.icons is None
+
+    async def test_multiple_icons(self):
+        """Test that components with multiple icons extract all of them."""
+        from mcp_types import Icon
+
+        mcp = FastMCP(
+            "MultiIconServer",
+            icons=[
+                Icon(
+                    src="https://example.com/icon-48.png",
+                    mime_type="image/png",
+                    sizes=["48x48"],
+                ),
+                Icon(
+                    src="https://example.com/icon-96.png",
+                    mime_type="image/png",
+                    sizes=["96x96"],
+                ),
+            ],
+        )
+
+        @mcp.tool(
+            icons=[
+                Icon(src="https://example.com/tool-small.png", sizes=["24x24"]),
+                Icon(src="https://example.com/tool-large.png", sizes=["48x48"]),
+            ]
+        )
+        def multi_icon_tool() -> str:
+            """Tool with multiple icons."""
+            return "multi"
+
+        info = await inspect_fastmcp(mcp)
+
+        # Check server icons
+        assert info.icons is not None
+        assert len(info.icons) == 2
+        assert info.icons[0]["sizes"] == ["48x48"]
+        assert info.icons[1]["sizes"] == ["96x96"]
+
+        # Check tool icons
+        assert len(info.tools) == 1
+        assert info.tools[0].icons is not None
+        assert len(info.tools[0].icons) == 2
+        assert info.tools[0].icons[0]["sizes"] == ["24x24"]
+        assert info.tools[0].icons[1]["sizes"] == ["48x48"]
+
+    async def test_data_uri_icons(self):
+        """Test that data URI icons are extracted correctly."""
+        from mcp_types import Icon
+
+        data_uri = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
+
+        mcp = FastMCP("DataURIServer")
+
+        @mcp.tool(icons=[Icon(src=data_uri, mime_type="image/png")])
+        def data_uri_tool() -> str:
+            """Tool with data URI icon."""
+            return "data"
+
+        info = await inspect_fastmcp(mcp)
+
+        assert len(info.tools) == 1
+        assert info.tools[0].icons is not None
+        assert info.tools[0].icons[0]["src"] == data_uri
+        assert info.tools[0].icons[0]["mimeType"] == "image/png"
+
+    async def test_icons_in_fastmcp_v1(self):
+        """Test that icons are extracted from FastMCP 1.x servers."""
+        from mcp_types import Icon
+
+        mcp = SDKServer("Icon1xServer")
+
+        @mcp.tool(
+            icons=[Icon(src="https://example.com/v1-tool.png", mime_type="image/png")]
+        )
+        def v1_tool() -> str:
+            """Tool in v1 server."""
+            return "v1"
+
+        info = await inspect_fastmcp_v1(mcp)
+
+        assert len(info.tools) == 1
+        # v1 servers should also extract icons if present
+        if info.tools[0].icons is not None:
+            assert info.tools[0].icons[0]["src"] == "https://example.com/v1-tool.png"
+
+    async def test_website_url_in_fastmcp_v1(self):
+        """Remote/v1 inspect surfaces the server's website_url.
+
+        The v1 path reads website_url from the SDK v2 snake_case serverInfo
+        model; a stale camelCase guard silently dropped it.
+        """
+        mcp = SDKServer("Website1xServer", website_url="https://example.com")
+
+        info = await inspect_fastmcp_v1(mcp)
+
+        assert info.website_url == "https://example.com"
+
+    async def test_no_website_url_in_fastmcp_v1(self):
+        """A v1 server with no website_url reports None rather than raising."""
+        mcp = SDKServer("NoWebsite1xServer")
+
+        info = await inspect_fastmcp_v1(mcp)
+
+        assert info.website_url is None
+
+    async def test_icons_in_formatted_output(self):
+        """Test that icons appear in formatted JSON output."""
+        from mcp_types import Icon
+
+        mcp = FastMCP(
+            "FormattedIconServer",
+            website_url="https://example.com",
+            icons=[Icon(src="https://example.com/server.png", mime_type="image/png")],
+        )
+
+        @mcp.tool(
+            icons=[Icon(src="https://example.com/tool.png", mime_type="image/png")]
+        )
+        def icon_tool() -> str:
+            """Tool with icon."""
+            return "icon"
+
+        info = await inspect_fastmcp(mcp)
+        json_bytes = format_fastmcp_info(info)
+
+        import json
+
+        data = json.loads(json_bytes)
+
+        # Check server icons in formatted output
+        assert data["server"]["website_url"] == "https://example.com"
+        assert data["server"]["icons"] is not None
+        assert len(data["server"]["icons"]) == 1
+        assert data["server"]["icons"][0]["src"] == "https://example.com/server.png"
+
+        # Check tool icons in formatted output
+        assert len(data["tools"]) == 1
+        assert data["tools"][0]["icons"] is not None
+        assert len(data["tools"][0]["icons"]) == 1
+        assert data["tools"][0]["icons"][0]["src"] == "https://example.com/tool.png"
+
+    async def test_icons_always_present_in_json(self):
+        """Test that icons and website_url fields are always present in JSON, even when None."""
+        mcp = FastMCP("AlwaysPresentServer")
+
+        @mcp.tool
+        def no_icon() -> str:
+            """Tool without icon."""
+            return "none"
+
+        info = await inspect_fastmcp(mcp)
+        json_bytes = format_fastmcp_info(info)
+
+        import json
+
+        data = json.loads(json_bytes)
+
+        # Fields should always be present, even when None
+        assert "website_url" in data["server"]
+        assert "icons" in data["server"]
+        assert data["server"]["website_url"] is None
+        assert data["server"]["icons"] is None
+
+        assert len(data["tools"]) == 1
+        assert "icons" in data["tools"][0]
+        assert data["tools"][0]["icons"] is None
+
+
+class TestFormatFunctions:
+    """Tests for the formatting functions."""
+
+    async def test_format_fastmcp_info(self):
+        """Test formatting as FastMCP-specific JSON."""
+        mcp = FastMCP("TestServer", instructions="Test instructions", version="1.2.3")
+
+        @mcp.tool
+        def test_tool(x: int) -> dict:
+            """A test tool."""
+            return {"result": x * 2}
+
+        info = await inspect_fastmcp(mcp)
+        json_bytes = format_fastmcp_info(info)
+
+        # Verify it's valid JSON
+        import json
+
+        data = json.loads(json_bytes)
+
+        # Check FastMCP-specific fields are present
+        assert "server" in data
+        assert data["server"]["name"] == "TestServer"
+        assert data["server"]["instructions"] == "Test instructions"
+        assert data["server"]["generation"] == 2  # v2 server
+        assert data["server"]["version"] == "1.2.3"
+        assert "capabilities" in data["server"]
+
+        # Check environment information
+        assert "environment" in data
+        assert data["environment"]["fastmcp"] == fastmcp.__version__
+        assert data["environment"]["mcp"] == importlib.metadata.version("mcp")
+
+        # Check tools
+        assert len(data["tools"]) == 1
+        assert data["tools"][0]["name"] == "test_tool"
+        assert "tags" in data["tools"][0]
+
+    async def test_format_mcp_info(self):
+        """Test formatting as MCP protocol JSON."""
+        mcp = FastMCP("TestServer", instructions="Test instructions", version="2.0.0")
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            """Add two numbers."""
+            return a + b
+
+        @mcp.prompt
+        def test_prompt(name: str) -> list:
+            """Test prompt."""
+            return [{"role": "user", "content": f"Hello {name}"}]
+
+        json_bytes = await format_mcp_info(mcp)
+
+        # Verify it's valid JSON
+        import json
+
+        data = json.loads(json_bytes)
+
+        # Check MCP protocol structure with camelCase
+        assert "serverInfo" in data
+        assert data["serverInfo"]["name"] == "TestServer"
+
+        # Check server version in MCP format
+        assert data["serverInfo"]["version"] == "2.0.0"
+
+        # MCP format SHOULD have environment fields
+        assert "environment" in data
+        assert data["environment"]["fastmcp"] == fastmcp.__version__
+        assert data["environment"]["mcp"] == importlib.metadata.version("mcp")
+        assert "capabilities" in data
+
+        assert "tools" in data
+        assert "prompts" in data
+        assert "resources" in data
+        assert "resourceTemplates" in data
+
+        # Check tools have MCP format (camelCase fields)
+        assert len(data["tools"]) == 1
+        assert data["tools"][0]["name"] == "add"
+        assert "inputSchema" in data["tools"][0]
+
+        # FastMCP-specific fields should not be present
+        assert "tags" not in data["tools"][0]
+        assert "enabled" not in data["tools"][0]
+
+    async def test_format_info_with_fastmcp_format(self):
+        """Test format_info with fastmcp format."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        def test() -> str:
+            return "test"
+
+        # Test with string format
+        json_bytes = await format_info(mcp, "fastmcp")
+        import json
+
+        data = json.loads(json_bytes)
+        assert data["server"]["name"] == "TestServer"
+        assert "tags" in data["tools"][0]  # FastMCP-specific field
+
+        # Test with enum format
+        json_bytes = await format_info(mcp, InspectFormat.FASTMCP)
+        data = json.loads(json_bytes)
+        assert data["server"]["name"] == "TestServer"
+
+    async def test_format_info_with_mcp_format(self):
+        """Test format_info with mcp format."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        def test() -> str:
+            return "test"
+
+        json_bytes = await format_info(mcp, "mcp")
+
+        import json
+
+        data = json.loads(json_bytes)
+        assert "serverInfo" in data
+        assert "tools" in data
+        assert "inputSchema" in data["tools"][0]  # MCP uses camelCase
+
+    async def test_format_info_requires_format(self):
+        """Test that format_info requires a format parameter."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool
+        def test() -> str:
+            return "test"
+
+        # Should work with valid formats
+        json_bytes = await format_info(mcp, "fastmcp")
+        assert json_bytes
+
+        json_bytes = await format_info(mcp, "mcp")
+        assert json_bytes
+
+        # Should fail with invalid format
+        import pytest
+
+        with pytest.raises(ValueError, match="not a valid InspectFormat"):
+            await format_info(mcp, "invalid")  # type: ignore
+
+    async def test_tool_with_output_schema(self):
+        """Test that output_schema is properly extracted and included."""
+        mcp = FastMCP("TestServer")
+
+        @mcp.tool(
+            output_schema={
+                "type": "object",
+                "properties": {
+                    "result": {"type": "number"},
+                    "message": {"type": "string"},
+                },
+            }
+        )
+        def compute(x: int) -> dict:
+            """Compute something."""
+            return {"result": x * 2, "message": f"Doubled {x}"}
+
+        info = await inspect_fastmcp(mcp)
+
+        # Check output_schema is captured
+        assert len(info.tools) == 1
+        assert info.tools[0].output_schema is not None
+        assert info.tools[0].output_schema["type"] == "object"
+        assert "result" in info.tools[0].output_schema["properties"]
+
+        # Verify it's included in FastMCP format
+        json_bytes = format_fastmcp_info(info)
+        import json
+
+        data = json.loads(json_bytes)
+        # Tools are at the top level, not nested
+        assert data["tools"][0]["output_schema"]["type"] == "object"
diff --git a/tests/utilities/test_json_schema.py b/tests/utilities/test_json_schema.py
new file mode 100644
index 0000000..1620127
--- /dev/null
+++ b/tests/utilities/test_json_schema.py
@@ -0,0 +1,1045 @@
+import copy
+from unittest.mock import patch
+
+from jsonref import replace_refs
+
+from fastmcp.utilities.json_schema import (
+    _prune_param,
+    _strip_remote_refs,
+    compress_schema,
+    dereference_refs,
+    resolve_root_ref,
+)
+
+
+class TestPruneParam:
+    """Tests for the _prune_param function."""
+
+    def test_nonexistent(self):
+        """Test pruning a parameter that doesn't exist."""
+        schema = {"properties": {"foo": {"type": "string"}}}
+        result = _prune_param(schema, "bar")
+        assert result == schema  # Schema should be unchanged
+
+    def test_exists(self):
+        """Test pruning a parameter that exists."""
+        schema = {"properties": {"foo": {"type": "string"}, "bar": {"type": "integer"}}}
+        result = _prune_param(schema, "bar")
+        assert result["properties"] == {"foo": {"type": "string"}}
+
+    def test_last_property(self):
+        """Test pruning the only/last parameter, should leave empty properties object."""
+        schema = {"properties": {"foo": {"type": "string"}}}
+        result = _prune_param(schema, "foo")
+        assert "properties" in result
+        assert result["properties"] == {}
+
+    def test_from_required(self):
+        """Test pruning a parameter that's in the required list."""
+        schema = {
+            "properties": {"foo": {"type": "string"}, "bar": {"type": "integer"}},
+            "required": ["foo", "bar"],
+        }
+        result = _prune_param(schema, "bar")
+        assert result["required"] == ["foo"]
+
+    def test_last_required(self):
+        """Test pruning the last required parameter, should remove required field."""
+        schema = {
+            "properties": {"foo": {"type": "string"}, "bar": {"type": "integer"}},
+            "required": ["foo"],
+        }
+        result = _prune_param(schema, "foo")
+        assert "required" not in result
+
+    def test_does_not_mutate_input(self):
+        """Test that _prune_param does not mutate the original schema."""
+        schema = {
+            "type": "object",
+            "properties": {"a": {"type": "string"}, "b": {"type": "integer"}},
+            "required": ["a", "b"],
+        }
+        original = copy.deepcopy(schema)
+        _prune_param(schema, "a")
+        assert schema == original
+
+
+class TestDereferenceRefs:
+    """Tests for the dereference_refs function."""
+
+    def test_dereferences_simple_ref(self):
+        """Test that simple $ref is dereferenced."""
+        schema = {
+            "properties": {
+                "foo": {"$ref": "#/$defs/foo_def"},
+            },
+            "$defs": {
+                "foo_def": {"type": "string"},
+            },
+        }
+        result = dereference_refs(schema)
+
+        # $ref should be inlined
+        assert result["properties"]["foo"] == {"type": "string"}
+        # $defs should be removed
+        assert "$defs" not in result
+
+    def test_dereferences_nested_refs(self):
+        """Test that nested $refs are dereferenced."""
+        schema = {
+            "properties": {
+                "foo": {"$ref": "#/$defs/foo_def"},
+            },
+            "$defs": {
+                "foo_def": {
+                    "type": "object",
+                    "properties": {"nested": {"$ref": "#/$defs/nested_def"}},
+                },
+                "nested_def": {"type": "string"},
+            },
+        }
+        result = dereference_refs(schema)
+
+        # All refs should be inlined
+        assert result["properties"]["foo"]["properties"]["nested"] == {"type": "string"}
+        # $defs should be removed
+        assert "$defs" not in result
+
+    def test_falls_back_for_circular_refs(self):
+        """Test that circular references fall back to resolve_root_ref."""
+        schema = {
+            "$defs": {
+                "Node": {
+                    "type": "object",
+                    "properties": {
+                        "children": {
+                            "type": "array",
+                            "items": {"$ref": "#/$defs/Node"},
+                        }
+                    },
+                }
+            },
+            "$ref": "#/$defs/Node",
+            "title": "Tree node",
+            "description": "A recursive tree node.",
+            "examples": [{"children": []}],
+        }
+        result = dereference_refs(schema)
+
+        # Should fall back to resolve_root_ref behavior
+        # Root should be resolved but nested refs preserved
+        assert result.get("type") == "object"
+        assert "$defs" in result  # $defs preserved for circular refs
+        assert result["title"] == "Tree node"
+        assert result["description"] == "A recursive tree node."
+        assert result["examples"] == [{"children": []}]
+
+    def test_falls_back_for_circular_json_pointer_refs(self):
+        """Test that circular JSON Pointer $ref (non-$defs) does not crash.
+
+        .NET/System.Text.Json emits $ref with JSON Pointer paths like
+        #/properties/nodes/items instead of $defs-based references.
+        Circular pointers must not cause a RecursionError.
+        """
+        schema = {
+            "type": "object",
+            "properties": {
+                "nodes": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "value": {"type": "string"},
+                            "children": {
+                                "type": "array",
+                                "items": {"$ref": "#/properties/nodes/items"},
+                            },
+                        },
+                    },
+                },
+            },
+        }
+        result = dereference_refs(schema)
+
+        # Should return the schema without crashing; circular refs stay unresolved
+        assert result["type"] == "object"
+        assert "properties" in result
+        # The circular $ref should be preserved (not inlined)
+        children_items = result["properties"]["nodes"]["items"]["properties"][
+            "children"
+        ]["items"]
+        assert children_items["$ref"] == "#/properties/nodes/items"
+
+    def test_preserves_sibling_keywords(self):
+        """Test that sibling keywords (default, description) are preserved.
+
+        Pydantic places description, default, examples as siblings to $ref.
+        These should not be lost during dereferencing.
+        """
+        schema = {
+            "$defs": {
+                "Status": {"type": "string", "enum": ["active", "inactive"]},
+            },
+            "properties": {
+                "status": {
+                    "$ref": "#/$defs/Status",
+                    "default": "active",
+                    "description": "The user status",
+                },
+            },
+            "type": "object",
+        }
+        result = dereference_refs(schema)
+
+        # $ref should be inlined with siblings preserved
+        status = result["properties"]["status"]
+        assert status["type"] == "string"
+        assert status["enum"] == ["active", "inactive"]
+        assert status["default"] == "active"
+        assert status["description"] == "The user status"
+        # $defs should be removed
+        assert "$defs" not in result
+
+    def test_preserves_siblings_in_lists(self):
+        """Test that siblings are preserved for $refs inside lists (allOf, anyOf, etc)."""
+        schema = {
+            "$defs": {
+                "StringType": {"type": "string"},
+                "IntType": {"type": "integer"},
+            },
+            "properties": {
+                "field": {
+                    "anyOf": [
+                        {"$ref": "#/$defs/StringType", "description": "As string"},
+                        {"$ref": "#/$defs/IntType", "description": "As integer"},
+                    ]
+                },
+            },
+        }
+        result = dereference_refs(schema)
+
+        # Both items in anyOf should have their siblings preserved
+        any_of = result["properties"]["field"]["anyOf"]
+        assert any_of[0]["type"] == "string"
+        assert any_of[0]["description"] == "As string"
+        assert any_of[1]["type"] == "integer"
+        assert any_of[1]["description"] == "As integer"
+        assert "$defs" not in result
+
+    def test_preserves_nested_siblings(self):
+        """Test that siblings on nested $refs are preserved."""
+        schema = {
+            "$defs": {
+                "Address": {
+                    "type": "object",
+                    "properties": {
+                        "country": {"$ref": "#/$defs/Country", "default": "US"},
+                    },
+                },
+                "Country": {"type": "string", "enum": ["US", "UK", "CA"]},
+            },
+            "properties": {
+                "home_address": {"$ref": "#/$defs/Address"},
+            },
+        }
+        result = dereference_refs(schema)
+
+        # The nested $ref's sibling (default) should be preserved
+        country = result["properties"]["home_address"]["properties"]["country"]
+        assert country["type"] == "string"
+        assert country["enum"] == ["US", "UK", "CA"]
+        assert country["default"] == "US"
+        assert "$defs" not in result
+
+    def test_strips_discriminator_mapping_after_inlining(self):
+        """Discriminator.mapping refs dangle after $defs are inlined (#3679)."""
+        schema = {
+            "$defs": {
+                "IdentifyPerson": {
+                    "type": "object",
+                    "properties": {
+                        "action": {"const": "identify", "type": "string"},
+                        "name": {"type": "string"},
+                    },
+                    "required": ["action", "name"],
+                },
+                "PersonDelete": {
+                    "type": "object",
+                    "properties": {
+                        "action": {"const": "delete", "type": "string"},
+                    },
+                    "required": ["action"],
+                },
+            },
+            "anyOf": [
+                {"$ref": "#/$defs/IdentifyPerson"},
+                {"$ref": "#/$defs/PersonDelete"},
+            ],
+            "discriminator": {
+                "mapping": {
+                    "identify": "#/$defs/IdentifyPerson",
+                    "delete": "#/$defs/PersonDelete",
+                },
+                "propertyName": "action",
+            },
+        }
+        result = dereference_refs(schema)
+
+        assert "$defs" not in result
+        assert "discriminator" not in result
+        # The anyOf variants should be inlined with their const values intact
+        assert len(result["anyOf"]) == 2
+        actions = {v["properties"]["action"]["const"] for v in result["anyOf"]}
+        assert actions == {"identify", "delete"}
+
+    def test_discriminator_property_remains_required_after_inlining(self):
+        schema = {
+            "$defs": {
+                "Comprehensive": {
+                    "type": "object",
+                    "properties": {
+                        "kind": {"const": "comprehensive", "type": "string"},
+                    },
+                },
+                "Validate": {
+                    "type": "object",
+                    "properties": {
+                        "kind": {"const": "validate", "type": "string"},
+                        "target_id": {"type": "string"},
+                    },
+                    "required": ["target_id"],
+                },
+            },
+            "anyOf": [
+                {"$ref": "#/$defs/Comprehensive"},
+                {"$ref": "#/$defs/Validate"},
+            ],
+            "discriminator": {
+                "mapping": {
+                    "comprehensive": "#/$defs/Comprehensive",
+                    "validate": "#/$defs/Validate",
+                },
+                "propertyName": "kind",
+            },
+        }
+        result = dereference_refs(schema)
+
+        assert "discriminator" not in result
+        for variant in result["anyOf"]:
+            assert "kind" in variant["required"]
+        validate_schema = next(
+            variant
+            for variant in result["anyOf"]
+            if variant["properties"]["kind"]["const"] == "validate"
+        )
+        assert validate_schema["required"] == ["target_id", "kind"]
+
+    def test_preserves_property_named_discriminator(self):
+        """A field *named* 'discriminator' inside properties must survive."""
+        schema = {
+            "$defs": {
+                "Inner": {
+                    "type": "object",
+                    "properties": {
+                        "discriminator": {"type": "string"},
+                    },
+                },
+            },
+            "properties": {
+                "item": {"$ref": "#/$defs/Inner"},
+            },
+        }
+        result = dereference_refs(schema)
+
+        assert "$defs" not in result
+        assert "discriminator" in result["properties"]["item"]["properties"]
+
+
+class TestCompressSchema:
+    """Tests for the compress_schema function."""
+
+    def test_preserves_refs_by_default(self):
+        """Test that compress_schema preserves $refs by default."""
+        schema = {
+            "properties": {
+                "foo": {"$ref": "#/$defs/foo_def"},
+            },
+            "$defs": {
+                "foo_def": {"type": "string"},
+            },
+        }
+        result = compress_schema(schema)
+
+        # $ref should be preserved (dereferencing is handled by middleware)
+        assert result["properties"]["foo"] == {"$ref": "#/$defs/foo_def"}
+        assert "$defs" in result
+
+    def test_prune_params(self):
+        """Test pruning parameters with compress_schema."""
+        schema = {
+            "properties": {
+                "foo": {"type": "string"},
+                "bar": {"type": "integer"},
+                "baz": {"type": "boolean"},
+            },
+            "required": ["foo", "bar"],
+        }
+        result = compress_schema(schema, prune_params=["foo", "baz"])
+        assert result["properties"] == {"bar": {"type": "integer"}}
+        assert result["required"] == ["bar"]
+
+    def test_pruning_additional_properties(self):
+        """Test pruning additionalProperties when explicitly enabled."""
+        schema = {
+            "type": "object",
+            "properties": {"foo": {"type": "string"}},
+            "additionalProperties": False,
+        }
+        # Must explicitly enable pruning now (default changed for MCP compatibility)
+        result = compress_schema(schema, prune_additional_properties=True)
+        assert "additionalProperties" not in result
+
+    def test_disable_pruning_additional_properties(self):
+        """Test disabling pruning of additionalProperties."""
+        schema = {
+            "type": "object",
+            "properties": {"foo": {"type": "string"}},
+            "additionalProperties": False,
+        }
+        result = compress_schema(schema, prune_additional_properties=False)
+        assert "additionalProperties" in result
+        assert result["additionalProperties"] is False
+
+    def test_combined_operations(self):
+        """Test all pruning operations together."""
+        schema = {
+            "type": "object",
+            "properties": {
+                "keep": {"type": "string"},
+                "remove": {"$ref": "#/$defs/remove_def"},
+            },
+            "required": ["keep", "remove"],
+            "additionalProperties": False,
+            "$defs": {
+                "remove_def": {"type": "string"},
+                "unused_def": {"type": "number"},
+            },
+        }
+        result = compress_schema(
+            schema, prune_params=["remove"], prune_additional_properties=True
+        )
+        # Check that parameter was removed
+        assert "remove" not in result["properties"]
+        # Check that required list was updated
+        assert result["required"] == ["keep"]
+        # All $defs entries are now unreferenced after pruning "remove", so they're cleaned up
+        assert "$defs" not in result
+        # Check that additionalProperties was removed
+        assert "additionalProperties" not in result
+
+    def test_prune_titles(self):
+        """Test pruning title fields."""
+        schema = {
+            "title": "Root Schema",
+            "type": "object",
+            "properties": {
+                "foo": {"title": "Foo Property", "type": "string"},
+                "bar": {
+                    "title": "Bar Property",
+                    "type": "object",
+                    "properties": {
+                        "nested": {"title": "Nested Property", "type": "string"}
+                    },
+                },
+            },
+        }
+        result = compress_schema(schema, prune_titles=True)
+        assert "title" not in result
+        assert "title" not in result["properties"]["foo"]
+        assert "title" not in result["properties"]["bar"]
+        assert "title" not in result["properties"]["bar"]["properties"]["nested"]
+
+    def test_prune_nested_additional_properties(self):
+        """Test pruning additionalProperties: false at all levels when explicitly enabled."""
+        schema = {
+            "type": "object",
+            "additionalProperties": False,
+            "properties": {
+                "foo": {
+                    "type": "object",
+                    "additionalProperties": False,
+                    "properties": {
+                        "nested": {
+                            "type": "object",
+                            "additionalProperties": False,
+                        }
+                    },
+                },
+            },
+        }
+        result = compress_schema(schema, prune_additional_properties=True)
+        assert "additionalProperties" not in result
+        assert "additionalProperties" not in result["properties"]["foo"]
+        assert (
+            "additionalProperties"
+            not in result["properties"]["foo"]["properties"]["nested"]
+        )
+
+    def test_title_pruning_preserves_parameter_named_title(self):
+        """Test that a parameter named 'title' is not removed during title pruning.
+
+        This is a critical edge case - we want to remove title metadata but preserve
+        actual parameters that happen to be named 'title'.
+        """
+        from typing import Annotated
+
+        from pydantic import Field, TypeAdapter
+
+        def greet(
+            name: Annotated[str, Field(description="The name to greet")],
+            title: Annotated[str, Field(description="Optional title", default="")],
+        ) -> str:
+            """A greeting function."""
+            return f"Hello {title} {name}"
+
+        adapter = TypeAdapter(greet)
+        schema = adapter.json_schema()
+
+        # Compress with title pruning
+        compressed = compress_schema(schema, prune_titles=True)
+
+        # The 'title' parameter should be preserved
+        assert "title" in compressed["properties"]
+        assert compressed["properties"]["title"]["description"] == "Optional title"
+        assert compressed["properties"]["title"]["default"] == ""
+
+        # But title metadata should be removed
+        assert "title" not in compressed["properties"]["name"]
+        assert "title" not in compressed["properties"]["title"]
+
+    def test_title_pruning_preserves_title_property_when_type_property_exists(self):
+        """Regression test for #3576: properties dict containing both 'title' and
+        'type' as parameter names caused the heuristic to treat 'title' as schema
+        metadata and strip the entire property definition."""
+        schema = {
+            "type": "object",
+            "properties": {
+                "dashboard_id": {"type": "string", "title": "Dashboard Id"},
+                "title": {"type": "string", "title": "Title"},
+                "type": {"type": "string", "title": "Type", "default": "vis"},
+            },
+            "required": ["dashboard_id", "title"],
+        }
+
+        compressed = compress_schema(schema, prune_titles=True)
+
+        # All three properties must survive
+        assert "dashboard_id" in compressed["properties"]
+        assert "title" in compressed["properties"]
+        assert "type" in compressed["properties"]
+
+        # 'title' is still required
+        assert "title" in compressed["required"]
+
+        # But metadata title strings inside each property schema are removed
+        assert "title" not in compressed["properties"]["dashboard_id"]
+        assert "title" not in compressed["properties"]["title"]
+        assert "title" not in compressed["properties"]["type"]
+
+    def test_prune_titles_on_bare_metadata_node(self):
+        """Pydantic emits `{"title": "X"}` for Any-typed fields with no sibling
+        `type`/`properties`. Gemini 2.5 Flash rejects these with
+        MALFORMED_FUNCTION_CALL, so we need to strip the title even without a
+        schema keyword — as long as every remaining key is metadata."""
+        schema = {
+            "type": "object",
+            "properties": {
+                "anyfield": {"title": "Anyfield"},
+                "described_any": {"title": "Described", "description": "anything"},
+            },
+        }
+
+        compressed = compress_schema(schema, prune_titles=True)
+
+        assert "title" not in compressed["properties"]["anyfield"]
+        assert "title" not in compressed["properties"]["described_any"]
+        # description survives — it's also metadata but prune_titles only
+        # targets "title" specifically
+        assert compressed["properties"]["described_any"]["description"] == "anything"
+
+    def test_prune_titles_on_draft07_and_legacy_keywords(self):
+        """Sub-schemas under draft-07 and 2019-09+ keywords that previous
+        drafts still use must be treated as schemas, not opaque payload —
+        `dependencies`, `additionalItems`, `contentSchema` all hold
+        sub-schemas in at least some JSON Schema drafts."""
+        schema = {
+            "type": "object",
+            "properties": {
+                "payload": {
+                    "type": "string",
+                    "contentMediaType": "application/json",
+                    "contentSchema": {
+                        "type": "object",
+                        "title": "Payload",
+                    },
+                },
+                "items_field": {
+                    "type": "array",
+                    "items": [{"type": "string", "title": "First"}],
+                    "additionalItems": {"type": "number", "title": "Extra"},
+                },
+            },
+            "dependencies": {
+                "credit_card": {
+                    "type": "object",
+                    "title": "HasBillingAddress",
+                    "required": ["billing_address"],
+                }
+            },
+        }
+
+        compressed = compress_schema(schema, prune_titles=True)
+
+        # title metadata stripped from sub-schemas reachable through
+        # draft-07 / 2019-09+ keywords
+        assert "title" not in compressed["properties"]["payload"]["contentSchema"]
+        assert "title" not in compressed["properties"]["items_field"]["items"][0]
+        assert "title" not in compressed["properties"]["items_field"]["additionalItems"]
+        assert "title" not in compressed["dependencies"]["credit_card"]
+
+    def test_prune_titles_preserves_user_extension_payloads(self):
+        """User extensions (json_schema_extra, x-* vendor keys) carry opaque
+        payloads that may look metadata-shaped. They must not be touched."""
+        schema = {
+            "type": "object",
+            "x-ui": {"title": "Dashboard", "description": "sidebar label"},
+            "properties": {
+                "config": {
+                    "type": "object",
+                    "x-widget": {"title": "Dropdown"},
+                }
+            },
+        }
+
+        compressed = compress_schema(schema, prune_titles=True)
+
+        assert compressed["x-ui"] == {
+            "title": "Dashboard",
+            "description": "sidebar label",
+        }
+        assert compressed["properties"]["config"]["x-widget"] == {"title": "Dropdown"}
+
+    def test_prune_titles_does_not_recurse_into_default_values(self):
+        """A user default that happens to be a dict shaped like schema metadata
+        must not be corrupted — `default` holds literal values, not sub-schemas."""
+        schema = {
+            "type": "object",
+            "properties": {
+                "config": {
+                    "type": "object",
+                    "default": {"title": "My Dashboard", "type": "vis"},
+                }
+            },
+        }
+
+        compressed = compress_schema(schema, prune_titles=True)
+
+        default = compressed["properties"]["config"]["default"]
+        assert default == {"title": "My Dashboard", "type": "vis"}
+
+    def test_title_pruning_with_nested_properties(self):
+        """Test that nested property structures are handled correctly."""
+        schema = {
+            "type": "object",
+            "title": "OuterObject",
+            "properties": {
+                "title": {  # This is a property named "title", not metadata
+                    "type": "object",
+                    "title": "TitleObject",  # This is metadata
+                    "properties": {
+                        "subtitle": {
+                            "type": "string",
+                            "title": "SubTitle",  # This is metadata
+                        }
+                    },
+                },
+                "normal_field": {
+                    "type": "string",
+                    "title": "NormalField",  # This is metadata
+                },
+            },
+        }
+
+        compressed = compress_schema(schema, prune_titles=True)
+
+        # Root title should be removed
+        assert "title" not in compressed
+
+        # The property named "title" should be preserved
+        assert "title" in compressed["properties"]
+
+        # But its metadata title should be removed
+        assert "title" not in compressed["properties"]["title"]
+
+        # Nested metadata titles should be removed
+        assert (
+            "title" not in compressed["properties"]["title"]["properties"]["subtitle"]
+        )
+        assert "title" not in compressed["properties"]["normal_field"]
+
+    def test_mcp_client_compatibility_requires_additional_properties(self):
+        """Test that compress_schema preserves additionalProperties: false for MCP clients.
+
+        MCP clients like Claude require strict JSON schemas with additionalProperties: false.
+        When tools use Pydantic models with extra="forbid", this constraint must be preserved.
+
+        Without this, MCP clients return:
+        "Invalid schema for function 'X': In context=('properties', 'Y'),
+        'additionalProperties' is required to be supplied and to be false"
+
+        See: https://github.com/PrefectHQ/fastmcp/issues/3008
+        """
+        # Schema representing a Pydantic model with extra="forbid"
+        schema = {
+            "type": "object",
+            "properties": {
+                "graph_table": {
+                    "type": "object",
+                    "properties": {
+                        "name": {"type": "string"},
+                        "columns": {"type": "array", "items": {"type": "string"}},
+                    },
+                    "required": ["name"],
+                    "additionalProperties": False,
+                }
+            },
+            "required": ["graph_table"],
+            "additionalProperties": False,
+        }
+
+        # By default, compress_schema should NOT strip additionalProperties: false
+        # This is the new expected behavior for MCP compatibility
+        result = compress_schema(schema)
+
+        # Root level should preserve additionalProperties: false
+        assert result.get("additionalProperties") is False, (
+            "Root additionalProperties: false was removed, breaking MCP compatibility"
+        )
+
+        # Nested object should also preserve additionalProperties: false
+        graph_table = result["properties"]["graph_table"]
+        assert graph_table.get("additionalProperties") is False, (
+            "Nested additionalProperties: false was removed, breaking MCP compatibility"
+        )
+
+
+class TestCompressSchemaDereference:
+    """Tests for the dereference parameter of compress_schema."""
+
+    SCHEMA_WITH_REFS = {
+        "properties": {
+            "foo": {"$ref": "#/$defs/foo_def"},
+        },
+        "$defs": {
+            "foo_def": {"type": "string"},
+        },
+    }
+
+    def test_dereference_true_inlines_refs(self):
+        result = compress_schema(self.SCHEMA_WITH_REFS, dereference=True)
+        assert result["properties"]["foo"] == {"type": "string"}
+        assert "$defs" not in result
+
+    def test_dereference_false_preserves_refs(self):
+        result = compress_schema(self.SCHEMA_WITH_REFS, dereference=False)
+        assert result["properties"]["foo"] == {"$ref": "#/$defs/foo_def"}
+        assert "$defs" in result
+
+    def test_other_optimizations_still_apply_without_dereference(self):
+        schema = {
+            "properties": {
+                "foo": {"$ref": "#/$defs/foo_def"},
+                "bar": {"type": "integer", "title": "Bar"},
+            },
+            "$defs": {
+                "foo_def": {"type": "string"},
+            },
+        }
+        result = compress_schema(
+            schema, dereference=False, prune_params=["bar"], prune_titles=True
+        )
+        assert "bar" not in result["properties"]
+        assert "$ref" in result["properties"]["foo"]
+        assert "$defs" in result
+
+
+class TestResolveRootRef:
+    """Tests for the resolve_root_ref function.
+
+    This function resolves $ref at root level to meet MCP spec requirements.
+    MCP specification requires outputSchema to have "type": "object" at root.
+    """
+
+    def test_resolves_simple_root_ref(self):
+        """Test that simple $ref at root is resolved."""
+        schema = {
+            "$defs": {
+                "Node": {
+                    "type": "object",
+                    "properties": {
+                        "id": {"type": "string"},
+                        "name": {"type": "string"},
+                    },
+                    "required": ["id"],
+                }
+            },
+            "$ref": "#/$defs/Node",
+        }
+        result = resolve_root_ref(schema)
+
+        # Should have type: object at root now
+        assert result.get("type") == "object"
+        assert "properties" in result
+        assert "id" in result["properties"]
+        assert "name" in result["properties"]
+        # Should still have $defs for nested references
+        assert "$defs" in result
+        # Should NOT have $ref at root
+        assert "$ref" not in result
+
+    def test_resolves_self_referential_model(self):
+        """Test resolving schema for self-referential models like Issue."""
+        # This is the exact schema Pydantic generates for self-referential models
+        schema = {
+            "$defs": {
+                "Issue": {
+                    "type": "object",
+                    "properties": {
+                        "id": {"type": "string"},
+                        "title": {"type": "string"},
+                        "dependencies": {
+                            "type": "array",
+                            "items": {"$ref": "#/$defs/Issue"},
+                        },
+                        "dependents": {
+                            "type": "array",
+                            "items": {"$ref": "#/$defs/Issue"},
+                        },
+                    },
+                    "required": ["id", "title"],
+                }
+            },
+            "$ref": "#/$defs/Issue",
+        }
+        result = resolve_root_ref(schema)
+
+        # Should have type: object at root
+        assert result.get("type") == "object"
+        assert "properties" in result
+        assert "id" in result["properties"]
+        assert "dependencies" in result["properties"]
+        # Nested $refs should still point to $defs
+        assert result["properties"]["dependencies"]["items"]["$ref"] == "#/$defs/Issue"
+        # Should have $defs preserved for nested references
+        assert "$defs" in result
+        assert "Issue" in result["$defs"]
+
+    def test_does_not_modify_schema_with_type_at_root(self):
+        """Test that schemas already having type at root are not modified."""
+        schema = {
+            "type": "object",
+            "properties": {"id": {"type": "string"}},
+            "$defs": {"SomeType": {"type": "string"}},
+            "$ref": "#/$defs/SomeType",  # This would be unusual but possible
+        }
+        result = resolve_root_ref(schema)
+
+        # Schema should be unchanged (returned as-is)
+        assert result is schema
+
+    def test_does_not_modify_schema_without_ref(self):
+        """Test that schemas without $ref are not modified."""
+        schema = {
+            "type": "object",
+            "properties": {"id": {"type": "string"}},
+        }
+        result = resolve_root_ref(schema)
+
+        assert result is schema
+
+    def test_does_not_modify_schema_without_defs(self):
+        """Test that schemas with $ref but without $defs are not modified."""
+        schema = {
+            "$ref": "#/$defs/Missing",
+        }
+        result = resolve_root_ref(schema)
+
+        assert result is schema
+
+    def test_does_not_modify_external_ref(self):
+        """Test that external $refs (not pointing to $defs) are not resolved."""
+        schema = {
+            "$defs": {"Node": {"type": "object"}},
+            "$ref": "https://example.com/schema.json#/definitions/Node",
+        }
+        result = resolve_root_ref(schema)
+
+        assert result is schema
+
+    def test_preserves_all_defs_for_nested_references(self):
+        """Test that $defs are preserved even if multiple definitions exist."""
+        schema = {
+            "$defs": {
+                "Node": {
+                    "type": "object",
+                    "properties": {
+                        "child": {"$ref": "#/$defs/ChildNode"},
+                    },
+                },
+                "ChildNode": {
+                    "type": "object",
+                    "properties": {"value": {"type": "string"}},
+                },
+            },
+            "$ref": "#/$defs/Node",
+        }
+        result = resolve_root_ref(schema)
+
+        # Both defs should be preserved
+        assert "$defs" in result
+        assert "Node" in result["$defs"]
+        assert "ChildNode" in result["$defs"]
+
+    def test_handles_missing_def_gracefully(self):
+        """Test that missing definition in $defs doesn't cause error."""
+        schema = {
+            "$defs": {"OtherType": {"type": "string"}},
+            "$ref": "#/$defs/Missing",
+        }
+        result = resolve_root_ref(schema)
+
+        # Should return original schema unchanged
+        assert result is schema
+
+
+class TestStripRemoteRefs:
+    """Tests for _strip_remote_refs which prevents SSRF/LFI via $ref."""
+
+    def test_preserves_local_ref(self):
+        schema = {"$ref": "#/$defs/Foo"}
+        assert _strip_remote_refs(schema) == {"$ref": "#/$defs/Foo"}
+
+    def test_strips_http_ref(self):
+        schema = {"$ref": "http://evil.com/schema.json"}
+        assert _strip_remote_refs(schema) == {}
+
+    def test_strips_https_ref(self):
+        schema = {"$ref": "https://evil.com/schema.json"}
+        assert _strip_remote_refs(schema) == {}
+
+    def test_strips_file_ref(self):
+        schema = {"$ref": "file:///etc/passwd"}
+        assert _strip_remote_refs(schema) == {}
+
+    def test_preserves_siblings_when_stripping(self):
+        schema = {
+            "$ref": "http://evil.com/schema.json",
+            "description": "keep me",
+            "default": 42,
+        }
+        result = _strip_remote_refs(schema)
+        assert result == {"description": "keep me", "default": 42}
+
+    def test_strips_nested_remote_refs(self):
+        schema = {
+            "properties": {
+                "safe": {"$ref": "#/$defs/Safe"},
+                "evil": {"$ref": "http://169.254.169.254/latest/meta-data/"},
+            }
+        }
+        result = _strip_remote_refs(schema)
+        assert result["properties"]["safe"] == {"$ref": "#/$defs/Safe"}
+        assert "$ref" not in result["properties"]["evil"]
+
+    def test_strips_remote_refs_in_lists(self):
+        schema = {
+            "anyOf": [
+                {"$ref": "#/$defs/Good"},
+                {"$ref": "file:///etc/credentials.json"},
+            ]
+        }
+        result = _strip_remote_refs(schema)
+        assert result["anyOf"][0] == {"$ref": "#/$defs/Good"}
+        assert "$ref" not in result["anyOf"][1]
+
+    def test_deep_nesting(self):
+        schema = {
+            "properties": {
+                "a": {
+                    "type": "object",
+                    "properties": {"b": {"$ref": "https://internal-service/secret"}},
+                }
+            }
+        }
+        result = _strip_remote_refs(schema)
+        assert "$ref" not in result["properties"]["a"]["properties"]["b"]
+
+
+class TestDereferenceRefsRemoteRefSafety:
+    """Verify dereference_refs never fetches remote URIs."""
+
+    def test_http_ref_not_fetched(self):
+        schema = {
+            "type": "object",
+            "properties": {
+                "name": {"$ref": "http://evil.com/schema.json"},
+            },
+        }
+        with patch(
+            "fastmcp.utilities.json_schema.replace_refs", wraps=replace_refs
+        ) as mock:
+            result = dereference_refs(schema)
+            # The remote $ref should have been stripped before replace_refs
+            if mock.called:
+                call_schema = mock.call_args[0][0]
+                assert "$ref" not in call_schema.get("properties", {}).get("name", {})
+        # Result should not contain the remote $ref
+        assert "$ref" not in result.get("properties", {}).get("name", {})
+
+    def test_file_ref_not_fetched(self):
+        schema = {
+            "type": "object",
+            "properties": {
+                "secret": {"$ref": "file:///etc/passwd"},
+            },
+        }
+        result = dereference_refs(schema)
+        assert "$ref" not in result.get("properties", {}).get("secret", {})
+
+    def test_cloud_metadata_ref_not_fetched(self):
+        schema = {
+            "type": "object",
+            "properties": {
+                "creds": {
+                    "$ref": "http://169.254.169.254/latest/meta-data/iam/security-credentials/"
+                },
+            },
+        }
+        result = dereference_refs(schema)
+        assert "$ref" not in result.get("properties", {}).get("creds", {})
+
+    def test_local_refs_still_resolved(self):
+        schema = {
+            "$defs": {"Status": {"type": "string", "enum": ["a", "b"]}},
+            "type": "object",
+            "properties": {
+                "status": {"$ref": "#/$defs/Status"},
+                "evil": {"$ref": "https://evil.com/inject"},
+            },
+        }
+        result = dereference_refs(schema)
+        # Local ref should be resolved
+        assert result["properties"]["status"] == {"type": "string", "enum": ["a", "b"]}
+        # Remote ref should be stripped
+        assert "$ref" not in result["properties"]["evil"]
+        assert "$defs" not in result
diff --git a/tests/utilities/test_logging.py b/tests/utilities/test_logging.py
new file mode 100644
index 0000000..d15b9c3
--- /dev/null
+++ b/tests/utilities/test_logging.py
@@ -0,0 +1,100 @@
+import logging
+
+import fastmcp
+from fastmcp.utilities.logging import configure_logging, get_logger
+
+
+def test_logging_doesnt_affect_other_loggers(caplog):
+    # set FastMCP loggers to CRITICAL and ensure other loggers still emit messages
+    original_level = logging.getLogger("fastmcp").getEffectiveLevel()
+
+    try:
+        logging.getLogger("fastmcp").setLevel(logging.CRITICAL)
+
+        root_logger = logging.getLogger()
+        app_logger = logging.getLogger("app")
+        fastmcp_logger = logging.getLogger("fastmcp")
+        fastmcp_server_logger = get_logger("server")
+
+        with caplog.at_level(logging.INFO):
+            root_logger.info("--ROOT--")
+            app_logger.info("--APP--")
+            fastmcp_logger.info("--FASTMCP--")
+            fastmcp_server_logger.info("--FASTMCP SERVER--")
+
+        assert "--ROOT--" in caplog.text
+        assert "--APP--" in caplog.text
+        assert "--FASTMCP--" not in caplog.text
+        assert "--FASTMCP SERVER--" not in caplog.text
+
+    finally:
+        logging.getLogger("fastmcp").setLevel(original_level)
+
+
+def test_configure_logging_with_traceback_kwargs():
+    """Test that traceback-related kwargs can be passed without causing duplicate argument errors."""
+    # This should not raise TypeError about duplicate keyword arguments
+    configure_logging(enable_rich_tracebacks=True, tracebacks_max_frames=20)
+
+    # Verify the logger was configured
+    logger = logging.getLogger("fastmcp")
+    assert logger.handlers
+    assert len(logger.handlers) == 2  # One for normal logs, one for tracebacks
+
+
+def test_configure_logging_traceback_defaults_can_be_overridden():
+    """Test that default traceback settings can be overridden by kwargs."""
+    configure_logging(
+        enable_rich_tracebacks=True,
+        tracebacks_max_frames=20,
+        show_path=True,
+        show_level=True,
+    )
+
+    logger = logging.getLogger("fastmcp")
+    assert logger.handlers
+    # The traceback handler should have been created with custom values
+    # We can't directly inspect RichHandler internals easily, but we verified no error was raised
+
+
+def test_configure_logging_with_rich_disabled():
+    """Test that disabling rich logging uses standard StreamHandler."""
+    original_enable_rich = fastmcp.settings.enable_rich_logging
+    try:
+        fastmcp.settings.enable_rich_logging = False
+        configure_logging()
+
+        logger = logging.getLogger("fastmcp")
+        assert logger.handlers
+        # Should only have one handler when rich logging is disabled
+        assert len(logger.handlers) == 1
+        # Should be a StreamHandler, not RichHandler
+        assert isinstance(logger.handlers[0], logging.StreamHandler)
+        assert not hasattr(
+            logger.handlers[0], "console"
+        )  # RichHandler has console attribute
+    finally:
+        fastmcp.settings.enable_rich_logging = original_enable_rich
+        # Reconfigure to restore state
+        configure_logging()
+
+
+def test_configure_logging_with_rich_enabled():
+    """Test that enabling rich logging uses RichHandler."""
+    original_enable_rich = fastmcp.settings.enable_rich_logging
+    try:
+        fastmcp.settings.enable_rich_logging = True
+        configure_logging()
+
+        logger = logging.getLogger("fastmcp")
+        assert logger.handlers
+        # Should have two handlers when rich logging is enabled (normal + traceback)
+        assert len(logger.handlers) == 2
+        # Both should be RichHandler instances
+        from rich.logging import RichHandler
+
+        assert all(isinstance(h, RichHandler) for h in logger.handlers)
+    finally:
+        fastmcp.settings.enable_rich_logging = original_enable_rich
+        # Reconfigure to restore state
+        configure_logging()
diff --git a/tests/utilities/test_skills.py b/tests/utilities/test_skills.py
new file mode 100644
index 0000000..62268ac
--- /dev/null
+++ b/tests/utilities/test_skills.py
@@ -0,0 +1,428 @@
+"""Tests for skills client utilities."""
+
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import Path
+from typing import cast
+
+import pytest
+from mcp_types import BlobResourceContents, TextResourceContents
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.providers.skills import SkillsDirectoryProvider
+from fastmcp.utilities.skills import (
+    SkillFile,
+    SkillManifest,
+    SkillSummary,
+    download_skill,
+    get_skill_manifest,
+    list_skills,
+    sync_skills,
+)
+
+
+class FakeResourceReader:
+    def __init__(
+        self,
+        responses: dict[str, list[TextResourceContents | BlobResourceContents]],
+    ) -> None:
+        self.responses = responses
+        self.requested_uris: list[str] = []
+
+    async def read_resource(self, uri: str):
+        self.requested_uris.append(uri)
+        return self.responses.get(uri, [])
+
+
+def text_resource(uri: str, text: str) -> TextResourceContents:
+    return TextResourceContents(uri=uri, text=text)
+
+
+def blob_resource(uri: str, data: bytes) -> BlobResourceContents:
+    return BlobResourceContents(
+        uri=uri,
+        blob=base64.b64encode(data).decode(),
+    )
+
+
+@pytest.fixture
+def skills_dir(tmp_path: Path) -> Path:
+    """Create a temporary skills directory with sample skills."""
+    skills = tmp_path / "skills"
+    skills.mkdir()
+
+    # Create pdf-processing skill
+    pdf_skill = skills / "pdf-processing"
+    pdf_skill.mkdir()
+    (pdf_skill / "SKILL.md").write_text(
+        """---
+description: Process PDF documents
+---
+
+# PDF Processing
+
+Instructions for PDF handling.
+"""
+    )
+    (pdf_skill / "reference.md").write_text("# Reference\n\nSome reference docs.")
+
+    # Create code-review skill
+    code_skill = skills / "code-review"
+    code_skill.mkdir()
+    (code_skill / "SKILL.md").write_text(
+        """---
+description: Review code for quality
+---
+
+# Code Review
+
+Instructions for reviewing code.
+"""
+    )
+
+    # Create skill with nested files
+    nested_skill = skills / "nested-skill"
+    nested_skill.mkdir()
+    (nested_skill / "SKILL.md").write_text("# Nested\n\nHas nested files.")
+    scripts = nested_skill / "scripts"
+    scripts.mkdir()
+    (scripts / "helper.py").write_text("# Helper script\nprint('hello')")
+
+    return skills
+
+
+@pytest.fixture
+def skills_server(skills_dir: Path) -> FastMCP:
+    """Create a FastMCP server with skills provider."""
+    mcp = FastMCP("Skills Server")
+    mcp.add_provider(SkillsDirectoryProvider(roots=skills_dir))
+    return mcp
+
+
+class TestListSkills:
+    async def test_lists_available_skills(self, skills_server: FastMCP):
+        async with Client(skills_server) as client:
+            skills = await list_skills(client)
+
+        assert len(skills) == 3
+        names = {s.name for s in skills}
+        assert names == {"pdf-processing", "code-review", "nested-skill"}
+
+    async def test_returns_skill_summary_objects(self, skills_server: FastMCP):
+        async with Client(skills_server) as client:
+            skills = await list_skills(client)
+
+        for skill in skills:
+            assert isinstance(skill, SkillSummary)
+            assert skill.name
+            assert skill.uri.startswith("skill://")
+            assert skill.uri.endswith("/SKILL.md")
+
+    async def test_includes_descriptions(self, skills_server: FastMCP):
+        async with Client(skills_server) as client:
+            skills = await list_skills(client)
+
+        by_name = {s.name: s for s in skills}
+        assert by_name["pdf-processing"].description == "Process PDF documents"
+        assert by_name["code-review"].description == "Review code for quality"
+
+    async def test_empty_server_returns_empty_list(self):
+        mcp = FastMCP("Empty")
+        async with Client(mcp) as client:
+            skills = await list_skills(client)
+
+        assert skills == []
+
+    async def test_filters_non_skill_resources(self):
+        mcp = FastMCP("Mixed Resources")
+
+        @mcp.resource("skill://team/pdf/SKILL.md")
+        def skill_document():
+            return "# Team PDF"
+
+        @mcp.resource("skill://team/pdf/reference.md")
+        def skill_reference():
+            return "# Reference"
+
+        @mcp.resource("file:///tmp/SKILL.md")
+        def non_skill_document():
+            return "# File"
+
+        @mcp.resource("skill://broken/SKILL.txt")
+        def wrong_suffix():
+            return "# Wrong suffix"
+
+        async with Client(mcp) as client:
+            skills = await list_skills(client)
+
+        assert skills == [
+            SkillSummary(
+                name="team/pdf",
+                description="",
+                uri="skill://team/pdf/SKILL.md",
+            )
+        ]
+
+
+class TestGetSkillManifest:
+    async def test_returns_manifest_with_files(self, skills_server: FastMCP):
+        async with Client(skills_server) as client:
+            manifest = await get_skill_manifest(client, "pdf-processing")
+
+        assert isinstance(manifest, SkillManifest)
+        assert manifest.name == "pdf-processing"
+        assert len(manifest.files) == 2
+
+        paths = {f.path for f in manifest.files}
+        assert paths == {"SKILL.md", "reference.md"}
+
+    async def test_files_have_size_and_hash(self, skills_server: FastMCP):
+        async with Client(skills_server) as client:
+            manifest = await get_skill_manifest(client, "pdf-processing")
+
+        for file in manifest.files:
+            assert isinstance(file, SkillFile)
+            assert file.size > 0
+            assert file.hash.startswith("sha256:")
+
+    async def test_nested_files_use_posix_paths(self, skills_server: FastMCP):
+        async with Client(skills_server) as client:
+            manifest = await get_skill_manifest(client, "nested-skill")
+
+        paths = {f.path for f in manifest.files}
+        assert "scripts/helper.py" in paths
+
+    async def test_nonexistent_skill_raises(self, skills_server: FastMCP):
+        async with Client(skills_server) as client:
+            with pytest.raises(Exception):
+                await get_skill_manifest(client, "nonexistent")
+
+    @pytest.mark.parametrize(
+        ("response", "match"),
+        [
+            ([], "Could not read manifest"),
+            (
+                [text_resource("skill://broken/_manifest", "not json")],
+                "Invalid manifest JSON",
+            ),
+            (
+                [blob_resource("skill://broken/_manifest", b"{}")],
+                "Unexpected manifest format",
+            ),
+            (
+                [text_resource("skill://broken/_manifest", '{"skill": "broken"}')],
+                "Invalid manifest format",
+            ),
+        ],
+    )
+    async def test_invalid_manifest_responses_raise_value_error(
+        self,
+        response: list[TextResourceContents | BlobResourceContents],
+        match: str,
+    ):
+        client = FakeResourceReader({"skill://broken/_manifest": response})
+
+        with pytest.raises(ValueError, match=match):
+            await get_skill_manifest(cast(Client, client), "broken")
+
+
+class TestDownloadSkill:
+    async def test_downloads_skill_to_directory(
+        self, skills_server: FastMCP, tmp_path: Path
+    ):
+        target = tmp_path / "downloaded"
+        target.mkdir()
+
+        async with Client(skills_server) as client:
+            result = await download_skill(client, "pdf-processing", target)
+
+        assert result == target / "pdf-processing"
+        assert result.exists()
+        assert (result / "SKILL.md").exists()
+        assert (result / "reference.md").exists()
+
+    async def test_creates_nested_directories(
+        self, skills_server: FastMCP, tmp_path: Path
+    ):
+        target = tmp_path / "downloaded"
+        target.mkdir()
+
+        async with Client(skills_server) as client:
+            result = await download_skill(client, "nested-skill", target)
+
+        assert (result / "scripts" / "helper.py").exists()
+        content = (result / "scripts" / "helper.py").read_text()
+        assert "print('hello')" in content
+
+    async def test_preserves_file_content(
+        self, skills_server: FastMCP, tmp_path: Path, skills_dir: Path
+    ):
+        target = tmp_path / "downloaded"
+        target.mkdir()
+
+        async with Client(skills_server) as client:
+            result = await download_skill(client, "pdf-processing", target)
+
+        original = (skills_dir / "pdf-processing" / "SKILL.md").read_text()
+        downloaded = (result / "SKILL.md").read_text()
+        assert downloaded == original
+
+    async def test_raises_if_exists_without_overwrite(
+        self, skills_server: FastMCP, tmp_path: Path
+    ):
+        target = tmp_path / "downloaded"
+        target.mkdir()
+        (target / "pdf-processing").mkdir()
+
+        async with Client(skills_server) as client:
+            with pytest.raises(FileExistsError):
+                await download_skill(client, "pdf-processing", target)
+
+    async def test_overwrites_with_flag(self, skills_server: FastMCP, tmp_path: Path):
+        target = tmp_path / "downloaded"
+        target.mkdir()
+        existing = target / "pdf-processing"
+        existing.mkdir()
+        (existing / "old-file.txt").write_text("old content")
+
+        async with Client(skills_server) as client:
+            result = await download_skill(
+                client, "pdf-processing", target, overwrite=True
+            )
+
+        assert (result / "SKILL.md").exists()
+
+    async def test_expands_user_path(self, skills_server: FastMCP, tmp_path: Path):
+        # This tests that ~ expansion works (though we can't actually test ~)
+        async with Client(skills_server) as client:
+            result = await download_skill(client, "code-review", tmp_path)
+
+        assert result.exists()
+
+    async def test_skips_manifest_paths_that_escape_target(self, tmp_path: Path):
+        manifest = {
+            "skill": "malicious",
+            "files": [
+                {"path": "SKILL.md", "size": 6, "hash": "sha256:safe"},
+                {"path": "../escape.txt", "size": 6, "hash": "sha256:escape"},
+                {"path": "/absolute.txt", "size": 8, "hash": "sha256:absolute"},
+            ],
+        }
+
+        client = FakeResourceReader(
+            {
+                "skill://malicious/_manifest": [
+                    text_resource("skill://malicious/_manifest", json.dumps(manifest))
+                ],
+                "skill://malicious/SKILL.md": [
+                    text_resource("skill://malicious/SKILL.md", "# Safe")
+                ],
+            }
+        )
+
+        result = await download_skill(cast(Client, client), "malicious", tmp_path)
+
+        assert (result / "SKILL.md").read_text() == "# Safe"
+        assert not (tmp_path / "escape.txt").exists()
+        assert client.requested_uris == [
+            "skill://malicious/_manifest",
+            "skill://malicious/SKILL.md",
+        ]
+
+    async def test_downloads_blob_resources(self, tmp_path: Path):
+        data = b"\x00\x01binary data"
+        manifest = {
+            "skill": "binary",
+            "files": [{"path": "data.bin", "size": len(data), "hash": "sha256:data"}],
+        }
+
+        client = FakeResourceReader(
+            {
+                "skill://binary/_manifest": [
+                    text_resource("skill://binary/_manifest", json.dumps(manifest))
+                ],
+                "skill://binary/data.bin": [
+                    blob_resource("skill://binary/data.bin", data)
+                ],
+            }
+        )
+
+        result = await download_skill(cast(Client, client), "binary", tmp_path)
+
+        assert (result / "data.bin").read_bytes() == data
+
+
+class TestSyncSkills:
+    async def test_downloads_all_skills(self, skills_server: FastMCP, tmp_path: Path):
+        target = tmp_path / "synced"
+        target.mkdir()
+
+        async with Client(skills_server) as client:
+            results = await sync_skills(client, target)
+
+        assert len(results) == 3
+        assert (target / "pdf-processing").exists()
+        assert (target / "code-review").exists()
+        assert (target / "nested-skill").exists()
+
+    async def test_skips_existing_without_overwrite(
+        self, skills_server: FastMCP, tmp_path: Path
+    ):
+        target = tmp_path / "synced"
+        target.mkdir()
+        (target / "pdf-processing").mkdir()
+
+        async with Client(skills_server) as client:
+            results = await sync_skills(client, target)
+
+        # Should skip pdf-processing, download the other two
+        assert len(results) == 2
+        names = {r.name for r in results}
+        assert "pdf-processing" not in names
+
+    async def test_overwrites_with_flag(self, skills_server: FastMCP, tmp_path: Path):
+        target = tmp_path / "synced"
+        target.mkdir()
+        (target / "pdf-processing").mkdir()
+
+        async with Client(skills_server) as client:
+            results = await sync_skills(client, target, overwrite=True)
+
+        assert len(results) == 3
+
+    async def test_returns_paths_to_downloaded_skills(
+        self, skills_server: FastMCP, tmp_path: Path
+    ):
+        target = tmp_path / "synced"
+        target.mkdir()
+
+        async with Client(skills_server) as client:
+            results = await sync_skills(client, target)
+
+        for path in results:
+            assert isinstance(path, Path)
+            assert path.exists()
+            assert (path / "SKILL.md").exists()
+
+
+class TestPathTraversal:
+    @pytest.mark.parametrize(
+        "malicious_name",
+        [
+            "../escape",
+            "../../root",
+            "../../../etc/passwd",
+            "foo/../../escape",
+        ],
+    )
+    async def test_malicious_skill_name_raises(
+        self, skills_server: FastMCP, tmp_path: Path, malicious_name: str
+    ):
+        target = tmp_path / "downloaded"
+        target.mkdir()
+
+        async with Client(skills_server) as client:
+            with pytest.raises(ValueError, match="would escape the target directory"):
+                await download_skill(client, malicious_name, target)
diff --git a/tests/utilities/test_tests.py b/tests/utilities/test_tests.py
new file mode 100644
index 0000000..6913d18
--- /dev/null
+++ b/tests/utilities/test_tests.py
@@ -0,0 +1,90 @@
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+import fastmcp
+from fastmcp import FastMCP
+from fastmcp.utilities.tests import HeadlessOAuth, temporary_settings
+
+
+class TestTemporarySettings:
+    def test_temporary_settings(self):
+        assert fastmcp.settings.log_level == "DEBUG"
+        with temporary_settings(log_level="ERROR"):
+            assert fastmcp.settings.log_level == "ERROR"
+        assert fastmcp.settings.log_level == "DEBUG"
+
+
+class TestTransportSetting:
+    def test_transport_default_is_stdio(self):
+        assert fastmcp.settings.transport == "stdio"
+
+    def test_transport_setting_can_be_changed(self):
+        with temporary_settings(transport="http"):
+            assert fastmcp.settings.transport == "http"
+        assert fastmcp.settings.transport == "stdio"
+
+    async def test_run_async_uses_transport_setting(self):
+        mcp = FastMCP("test")
+        with temporary_settings(transport="http"):
+            with patch.object(
+                mcp, "run_http_async", new_callable=AsyncMock
+            ) as mock_http:
+                await mcp.run_async()
+                mock_http.assert_called_once()
+
+    async def test_run_async_explicit_transport_overrides_setting(self):
+        mcp = FastMCP("test")
+        with temporary_settings(transport="http"):
+            with patch.object(
+                mcp, "run_stdio_async", new_callable=AsyncMock
+            ) as mock_stdio:
+                await mcp.run_async(transport="stdio")
+                mock_stdio.assert_called_once()
+
+
+class TestHeadlessOAuthCallbackHandler:
+    """Regression tests for #4056: blank query values must survive parse_qs.
+
+    The OAuth callback handler in HeadlessOAuth parses the redirect Location
+    header. parse_qs without keep_blank_values=True silently drops keys whose
+    value is empty (e.g. `?state=`), which mis-models real OAuth callbacks
+    where an empty `state` is distinct from a missing one.
+    """
+
+    def _make_oauth_with_redirect(self, location: str) -> HeadlessOAuth:
+        """Build a HeadlessOAuth with a fake stored 302 response."""
+        oauth = HeadlessOAuth.__new__(HeadlessOAuth)
+        response = MagicMock()
+        response.status_code = 302
+        response.headers = {"location": location}
+        oauth._stored_response = response
+        return oauth
+
+    async def test_callback_preserves_blank_state(self):
+        """An explicitly-empty state must round-trip as "" rather than None."""
+        oauth = self._make_oauth_with_redirect(
+            "https://example.com/callback?code=abc&state="
+        )
+        result = await oauth.callback_handler()
+        assert result.code == "abc"
+        assert result.state == ""
+
+    async def test_callback_returns_none_when_state_missing(self):
+        """A truly missing state still returns None (default)."""
+        oauth = self._make_oauth_with_redirect("https://example.com/callback?code=abc")
+        result = await oauth.callback_handler()
+        assert result.code == "abc"
+        assert result.state is None
+
+    async def test_callback_uses_blank_error_description_verbatim(self):
+        """When the OAuth provider sends an empty error_description, surface
+        it as "" rather than falling back to "Unknown error". The fallback is
+        meant for the truly-absent case; with keep_blank_values=True the
+        explicit empty value is preserved and used directly.
+        """
+        oauth = self._make_oauth_with_redirect(
+            "https://example.com/callback?error=invalid_request&error_description="
+        )
+        with pytest.raises(RuntimeError, match=r"invalid_request - $"):
+            await oauth.callback_handler()
diff --git a/tests/utilities/test_timeout.py b/tests/utilities/test_timeout.py
new file mode 100644
index 0000000..6f28860
--- /dev/null
+++ b/tests/utilities/test_timeout.py
@@ -0,0 +1,50 @@
+"""Tests for timeout normalization utilities."""
+
+import datetime
+from typing import Any, cast
+
+import pytest
+
+from fastmcp.utilities.timeout import (
+    normalize_timeout_to_seconds,
+    normalize_timeout_to_timedelta,
+)
+
+
+class TestNormalizeTimeoutToSeconds:
+    def test_none_stays_none(self):
+        assert normalize_timeout_to_seconds(None) is None
+
+    def test_numeric_values_become_float_seconds(self):
+        assert normalize_timeout_to_seconds(3) == 3.0
+        assert normalize_timeout_to_seconds(2.5) == 2.5
+
+    def test_zero_values_disable_timeout(self):
+        assert normalize_timeout_to_seconds(0) is None
+        assert normalize_timeout_to_seconds(datetime.timedelta(seconds=0)) is None
+
+    def test_timedelta_becomes_seconds(self):
+        assert (
+            normalize_timeout_to_seconds(datetime.timedelta(milliseconds=250)) == 0.25
+        )
+
+    def test_invalid_type_raises_type_error(self):
+        with pytest.raises(TypeError, match="Invalid timeout type"):
+            normalize_timeout_to_seconds(cast(Any, "1"))
+
+
+class TestNormalizeTimeoutToTimedelta:
+    def test_none_stays_none(self):
+        assert normalize_timeout_to_timedelta(None) is None
+
+    def test_timedelta_is_returned_unchanged(self):
+        timeout = datetime.timedelta(seconds=5)
+        assert normalize_timeout_to_timedelta(timeout) is timeout
+
+    def test_numeric_values_become_timedeltas(self):
+        assert normalize_timeout_to_timedelta(3) == datetime.timedelta(seconds=3)
+        assert normalize_timeout_to_timedelta(0.5) == datetime.timedelta(seconds=0.5)
+
+    def test_invalid_type_raises_type_error(self):
+        with pytest.raises(TypeError, match="Invalid timeout type"):
+            normalize_timeout_to_timedelta(cast(Any, "1"))
diff --git a/tests/utilities/test_token_cache.py b/tests/utilities/test_token_cache.py
new file mode 100644
index 0000000..93bbae4
--- /dev/null
+++ b/tests/utilities/test_token_cache.py
@@ -0,0 +1,226 @@
+"""Tests for the shared TokenCache utility."""
+
+import time
+
+import pytest
+
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.utilities.token_cache import TokenCache
+
+
+def _make_token(
+    *,
+    token: str = "tok",
+    client_id: str = "client-1",
+    scopes: list[str] | None = None,
+    expires_at: int | None = None,
+) -> AccessToken:
+    return AccessToken(
+        token=token,
+        client_id=client_id,
+        scopes=scopes or [],
+        expires_at=expires_at,
+    )
+
+
+class TestTokenCacheDisabled:
+    """Verify behaviour when caching is turned off."""
+
+    @pytest.mark.parametrize(
+        "ttl, max_size",
+        [
+            (None, None),
+            (0, 100),
+            (300, 0),
+        ],
+    )
+    def test_disabled_configurations(self, ttl: int | None, max_size: int | None):
+        cache = TokenCache(ttl_seconds=ttl, max_size=max_size)
+        assert not cache.enabled
+
+    def test_negative_ttl_raises(self):
+        with pytest.raises(ValueError, match="cache_ttl_seconds must be non-negative"):
+            TokenCache(ttl_seconds=-1)
+
+    def test_negative_max_size_raises(self):
+        with pytest.raises(ValueError, match="max_cache_size must be non-negative"):
+            TokenCache(max_size=-1)
+
+    def test_get_returns_miss_when_disabled(self):
+        cache = TokenCache(ttl_seconds=0)
+        cache.set("tok", _make_token())
+        hit, result = cache.get("tok")
+        assert not hit
+        assert result is None
+
+    def test_set_is_noop_when_disabled(self):
+        cache = TokenCache(ttl_seconds=0)
+        cache.set("tok", _make_token())
+        assert len(cache._entries) == 0
+
+
+class TestTokenCacheEnabled:
+    """Core get/set behaviour with caching on."""
+
+    @pytest.fixture
+    def cache(self) -> TokenCache:
+        return TokenCache(ttl_seconds=300, max_size=100)
+
+    def test_enabled(self, cache: TokenCache):
+        assert cache.enabled
+
+    def test_set_and_get(self, cache: TokenCache):
+        access = _make_token(client_id="user-1")
+        cache.set("tok-1", access)
+
+        hit, result = cache.get("tok-1")
+        assert hit
+        assert result is not None
+        assert result.client_id == "user-1"
+
+    def test_miss_for_unknown_token(self, cache: TokenCache):
+        hit, result = cache.get("unknown")
+        assert not hit
+        assert result is None
+
+    def test_different_tokens_cached_separately(self, cache: TokenCache):
+        cache.set("tok-a", _make_token(client_id="a"))
+        cache.set("tok-b", _make_token(client_id="b"))
+
+        _, a = cache.get("tok-a")
+        _, b = cache.get("tok-b")
+        assert a is not None and a.client_id == "a"
+        assert b is not None and b.client_id == "b"
+
+
+class TestTokenCacheDefensiveCopy:
+    """Mutating a returned token must not affect the cached value."""
+
+    def test_get_returns_deep_copy(self):
+        cache = TokenCache(ttl_seconds=300, max_size=100)
+        access = _make_token(client_id="orig")
+        access.claims = {"key": "original"}
+        cache.set("tok", access)
+
+        _, first = cache.get("tok")
+        assert first is not None
+        first.claims["key"] = "mutated"
+        first.scopes.append("admin")
+
+        _, second = cache.get("tok")
+        assert second is not None
+        assert second.claims["key"] == "original"
+        assert "admin" not in second.scopes
+
+    def test_mutating_source_does_not_affect_cache(self):
+        cache = TokenCache(ttl_seconds=300, max_size=100)
+        access = _make_token(client_id="orig")
+        access.claims = {"key": "original"}
+        cache.set("tok", access)
+
+        access.claims["key"] = "mutated"
+
+        _, cached = cache.get("tok")
+        assert cached is not None
+        assert cached.claims["key"] == "original"
+
+
+class TestTokenCacheTTL:
+    """Expiration and TTL behaviour."""
+
+    def test_expired_entry_is_evicted_on_get(self):
+        cache = TokenCache(ttl_seconds=300, max_size=100)
+        cache.set("tok", _make_token())
+
+        key = cache._hash_token("tok")
+        cache._entries[key].expires_at = time.time() - 1
+
+        hit, result = cache.get("tok")
+        assert not hit
+        assert result is None
+        assert key not in cache._entries
+
+    def test_token_expires_at_caps_ttl(self):
+        cache = TokenCache(ttl_seconds=300, max_size=100)
+        short_exp = int(time.time()) + 30
+        cache.set("tok", _make_token(expires_at=short_exp))
+
+        key = cache._hash_token("tok")
+        assert cache._entries[key].expires_at <= short_exp
+
+    def test_ttl_used_when_no_token_expiry(self):
+        cache = TokenCache(ttl_seconds=60, max_size=100)
+        before = time.time()
+        cache.set("tok", _make_token(expires_at=None))
+        after = time.time()
+
+        key = cache._hash_token("tok")
+        entry = cache._entries[key]
+        assert before + 60 <= entry.expires_at <= after + 60
+
+
+class TestTokenCacheSizeLimit:
+    """Eviction and size-limit behaviour."""
+
+    def test_evicts_oldest_when_full(self):
+        cache = TokenCache(ttl_seconds=300, max_size=2)
+        cache.set("tok-0", _make_token(client_id="0"))
+        cache.set("tok-1", _make_token(client_id="1"))
+        cache.set("tok-2", _make_token(client_id="2"))
+
+        assert len(cache._entries) == 2
+        hit_0, _ = cache.get("tok-0")
+        assert not hit_0
+
+        hit_1, _ = cache.get("tok-1")
+        hit_2, _ = cache.get("tok-2")
+        assert hit_1
+        assert hit_2
+
+    def test_cleanup_expired_before_eviction(self):
+        cache = TokenCache(ttl_seconds=300, max_size=2)
+        cache.set("tok-0", _make_token(client_id="0"))
+        cache.set("tok-1", _make_token(client_id="1"))
+
+        key_0 = cache._hash_token("tok-0")
+        cache._entries[key_0].expires_at = time.time() - 1
+
+        cache.set("tok-2", _make_token(client_id="2"))
+
+        assert len(cache._entries) == 2
+        hit_1, _ = cache.get("tok-1")
+        hit_2, _ = cache.get("tok-2")
+        assert hit_1
+        assert hit_2
+
+    def test_overwrite_does_not_evict(self):
+        """Overwriting an existing key should not evict another entry."""
+        cache = TokenCache(ttl_seconds=300, max_size=2)
+        cache.set("tok-0", _make_token(client_id="0"))
+        cache.set("tok-1", _make_token(client_id="1"))
+
+        # Overwrite tok-0 — should NOT evict tok-1
+        cache.set("tok-0", _make_token(client_id="0-updated"))
+
+        assert len(cache._entries) == 2
+        hit_0, result_0 = cache.get("tok-0")
+        hit_1, _ = cache.get("tok-1")
+        assert hit_0
+        assert hit_1
+        assert result_0 is not None
+        assert result_0.client_id == "0-updated"
+
+
+class TestTokenCacheHashing:
+    """SHA-256 key hashing."""
+
+    def test_consistent_hashing(self):
+        assert TokenCache._hash_token("abc") == TokenCache._hash_token("abc")
+
+    def test_different_tokens_different_hashes(self):
+        assert TokenCache._hash_token("abc") != TokenCache._hash_token("xyz")
+
+    def test_hash_is_64_hex_chars(self):
+        h = TokenCache._hash_token("anything")
+        assert len(h) == 64
+        int(h, 16)  # must be valid hex
diff --git a/tests/utilities/test_typeadapter.py b/tests/utilities/test_typeadapter.py
new file mode 100644
index 0000000..941cd1d
--- /dev/null
+++ b/tests/utilities/test_typeadapter.py
@@ -0,0 +1,273 @@
+"""
+This test file adapts tests from test_func_metadata.py which tested a custom implementation
+that has been replaced by pydantic TypeAdapters.
+
+The tests ensure our TypeAdapter-based approach covers all the edge cases the old custom
+implementation handled. Since we're now using standard pydantic functionality, these tests
+may be redundant with pydantic's own tests and could potentially be removed in the future.
+"""
+
+from typing import Annotated
+
+import annotated_types
+import pytest
+from pydantic import BaseModel, Field
+
+from fastmcp.utilities.json_schema import compress_schema
+from fastmcp.utilities.types import get_cached_typeadapter
+
+
+# Models must be defined at the module level for forward references to work
+class SomeInputModelA(BaseModel):
+    pass
+
+
+class SomeInputModelB(BaseModel):
+    class InnerModel(BaseModel):
+        x: int
+
+    how_many_shrimp: Annotated[int, Field(description="How many shrimp in the tank???")]
+    ok: InnerModel
+    y: None
+
+
+# Define additional models needed in tests
+class SomeComplexModel(BaseModel):
+    x: int
+    y: dict[int, str]
+
+
+class ClassWithMethods:
+    def do_something(self, x: int) -> int:
+        return x
+
+    def do_something_annotated(
+        self, x: Annotated[int, Field(description="A description")]
+    ) -> int:
+        return x
+
+    def do_something_return_none(self) -> None:
+        return None
+
+
+def complex_arguments_fn(
+    an_int: int,
+    must_be_none: None,
+    must_be_none_dumb_annotation: Annotated[None, "blah"],
+    list_of_ints: list[int],
+    # list[str] | str is an interesting case because if it comes in as JSON like
+    # "[\"a\", \"b\"]" then it will be naively parsed as a string.
+    list_str_or_str: list[str] | str,
+    an_int_annotated_with_field: Annotated[
+        int, Field(description="An int with a field")
+    ],
+    an_int_annotated_with_field_and_others: Annotated[
+        int,
+        str,  # Should be ignored, really
+        Field(description="An int with a field"),
+        annotated_types.Gt(1),
+    ],
+    an_int_annotated_with_junk: Annotated[
+        int,
+        "123",
+        456,
+    ],
+    field_with_default_via_field_annotation_before_nondefault_arg: Annotated[
+        int, Field(default=1)
+    ],
+    unannotated,
+    my_model_a: SomeInputModelA,
+    my_model_a_forward_ref: "SomeInputModelA",
+    my_model_b: SomeInputModelB,
+    an_int_annotated_with_field_default: Annotated[
+        int,
+        Field(default=1, description="An int with a field"),
+    ],
+    unannotated_with_default=5,
+    my_model_a_with_default: SomeInputModelA = SomeInputModelA(),  # noqa: B008
+    an_int_with_default: int = 1,
+    must_be_none_with_default: None = None,
+    an_int_with_equals_field: int = Field(1, ge=0),
+    int_annotated_with_default: Annotated[int, Field(description="hey")] = 5,
+) -> str:
+    _ = (
+        an_int,
+        must_be_none,
+        must_be_none_dumb_annotation,
+        list_of_ints,
+        list_str_or_str,
+        an_int_annotated_with_field,
+        an_int_annotated_with_field_and_others,
+        an_int_annotated_with_junk,
+        field_with_default_via_field_annotation_before_nondefault_arg,
+        unannotated,
+        an_int_annotated_with_field_default,
+        unannotated_with_default,
+        my_model_a,
+        my_model_a_forward_ref,
+        my_model_b,
+        my_model_a_with_default,
+        an_int_with_default,
+        must_be_none_with_default,
+        an_int_with_equals_field,
+        int_annotated_with_default,
+    )
+    return "ok!"
+
+
+def get_simple_func_adapter():
+    """Get a TypeAdapter for a simple function to avoid forward reference issues"""
+
+    def simple_func(x: int, y: str = "default") -> str:
+        return f"{x}-{y}"
+
+    return get_cached_typeadapter(simple_func)
+
+
+async def test_complex_function_runtime_arg_validation_non_json():
+    """Test that basic non-JSON arguments are validated correctly using a simpler function"""
+    type_adapter = get_simple_func_adapter()
+
+    # Test with minimum required arguments
+    args = {"x": 1}
+    result = type_adapter.validate_python(args)
+    assert (
+        result == "1-default"
+    )  # Don't call result() as TypeAdapter returns the value directly
+
+    # Test with all arguments
+    args = {"x": 1, "y": "hello"}
+    result = type_adapter.validate_python(args)
+    assert result == "1-hello"
+
+    # Test with invalid types
+    with pytest.raises(Exception):
+        type_adapter.validate_python({"x": "not an int"})
+
+
+def test_missing_annotation():
+    """Test that missing annotations don't cause errors"""
+
+    def func_no_annotations(x, y):
+        return x + y
+
+    type_adapter = get_cached_typeadapter(func_no_annotations)
+    result = type_adapter.validate_python({"x": "1", "y": "2"})
+    assert result == "12"  # String concatenation since no type info
+
+
+def test_convert_str_to_complex_type():
+    """Test that string arguments are converted to the complex type when valid"""
+
+    def func_with_str_types(string: SomeComplexModel):
+        return string
+
+    # Create a valid model instance
+    input_data = {"x": 1, "y": {1: "hello"}}
+
+    # Validate with model directly
+    SomeComplexModel.model_validate(input_data)
+
+    # Now check if type adapter validates correctly
+    type_adapter = get_cached_typeadapter(func_with_str_types)
+    result = type_adapter.validate_python({"string": input_data})
+
+    assert isinstance(result, SomeComplexModel)
+    assert result.x == 1
+    assert result.y == {1: "hello"}
+
+
+def test_skip_names():
+    """Test that skipped parameters are not included in the schema"""
+
+    def func_with_many_params(
+        keep_this: int, skip_this: str, also_keep: float, also_skip: bool
+    ):
+        return keep_this, skip_this, also_keep, also_skip
+
+    # Get schema and prune parameters
+    type_adapter = get_cached_typeadapter(func_with_many_params)
+    schema = type_adapter.json_schema()
+    pruned_schema = compress_schema(schema, prune_params=["skip_this", "also_skip"])
+
+    # Check that only the desired parameters remain
+    assert "keep_this" in pruned_schema["properties"]
+    assert "also_keep" in pruned_schema["properties"]
+    assert "skip_this" not in pruned_schema["properties"]
+    assert "also_skip" not in pruned_schema["properties"]
+
+    # The pruned parameters should also be removed from required
+    if "required" in pruned_schema:
+        assert "skip_this" not in pruned_schema["required"]
+        assert "also_skip" not in pruned_schema["required"]
+
+
+async def test_lambda_function():
+    """Test lambda function schema and validation"""
+    fn = lambda x, y=5: str(x)  # noqa: E731
+    type_adapter = get_cached_typeadapter(fn)
+
+    # Basic calls - validate_python returns the result directly
+    result = type_adapter.validate_python({"x": "hello"})
+    assert result == "hello"
+
+    result = type_adapter.validate_python({"x": "hello", "y": "world"})
+    assert result == "hello"
+
+    # Missing required arg
+    with pytest.raises(Exception):
+        type_adapter.validate_python({"y": "world"})
+
+
+def test_basic_json_schema():
+    """Test JSON schema generation for a simple function"""
+
+    def simple_func(a: int, b: str = "default") -> str:
+        return f"{a}-{b}"
+
+    type_adapter = get_cached_typeadapter(simple_func)
+    schema = type_adapter.json_schema()
+
+    # Check basic properties
+    assert "properties" in schema
+    assert "a" in schema["properties"]
+    assert "b" in schema["properties"]
+    assert schema["properties"]["a"]["type"] == "integer"
+    assert schema["properties"]["b"]["type"] == "string"
+    assert "default" in schema["properties"]["b"]
+    assert schema["properties"]["b"]["default"] == "default"
+
+    # Check required
+    assert "required" in schema
+    assert "a" in schema["required"]
+    assert "b" not in schema["required"]
+
+
+def test_str_vs_int():
+    """
+    Test that string values are kept as strings even when they contain numbers,
+    while numbers are parsed correctly.
+    """
+
+    def func_with_str_and_int(a: str, b: int):
+        return a
+
+    type_adapter = get_cached_typeadapter(func_with_str_and_int)
+    result = type_adapter.validate_python({"a": "123", "b": 123})
+    assert result == "123"
+
+
+def test_class_with_methods():
+    """Test that class methods are not included in the schema"""
+    class_with_methods = ClassWithMethods()
+    type_adapter = get_cached_typeadapter(class_with_methods.do_something)
+    schema = type_adapter.json_schema()
+    assert "self" not in schema["properties"]
+
+    type_adapter = get_cached_typeadapter(class_with_methods.do_something_annotated)
+    schema = type_adapter.json_schema()
+    assert "self" not in schema["properties"]
+
+    type_adapter = get_cached_typeadapter(class_with_methods.do_something_return_none)
+    schema = type_adapter.json_schema()
+    assert "self" not in schema["properties"]
diff --git a/tests/utilities/test_types.py b/tests/utilities/test_types.py
new file mode 100644
index 0000000..3d366aa
--- /dev/null
+++ b/tests/utilities/test_types.py
@@ -0,0 +1,691 @@
+import base64
+import os
+from typing import Annotated, Any, cast
+
+import pytest
+from mcp_types import BlobResourceContents, TextResourceContents
+from pydantic import Field
+
+from fastmcp.utilities.types import (
+    Audio,
+    File,
+    Image,
+    create_function_without_params,
+    get_cached_typeadapter,
+    is_class_member_of_type,
+    issubclass_safe,
+    replace_type,
+)
+
+
+class BaseClass:
+    pass
+
+
+class ChildClass(BaseClass):
+    pass
+
+
+class OtherClass:
+    pass
+
+
+class TestIsClassMemberOfType:
+    def test_basic_subclass_check(self):
+        """Test that a subclass is recognized as a member of the base class."""
+        assert is_class_member_of_type(ChildClass, BaseClass)
+
+    def test_self_is_member(self):
+        """Test that a class is a member of itself."""
+        assert is_class_member_of_type(BaseClass, BaseClass)
+
+    def test_unrelated_class_is_not_member(self):
+        """Test that an unrelated class is not a member of the base class."""
+        assert not is_class_member_of_type(OtherClass, BaseClass)
+
+    def test_typing_union_with_member_is_member(self):
+        """Test that Union type with a member class is detected as a member."""
+        union_type1: Any = ChildClass | OtherClass
+        union_type2: Any = OtherClass | ChildClass
+
+        assert is_class_member_of_type(union_type1, BaseClass)
+        assert is_class_member_of_type(union_type2, BaseClass)
+
+    def test_typing_union_without_member_is_not_member(self):
+        """Test that Union type without any member class is not a member."""
+        union_type: Any = OtherClass | str
+        assert not is_class_member_of_type(union_type, BaseClass)
+
+    def test_pipe_union_with_member_is_member(self):
+        """Test that pipe syntax union with a member class is detected as a member."""
+        union_pipe1: Any = ChildClass | OtherClass
+        union_pipe2: Any = OtherClass | ChildClass
+
+        assert is_class_member_of_type(union_pipe1, BaseClass)
+        assert is_class_member_of_type(union_pipe2, BaseClass)
+
+    def test_pipe_union_without_member_is_not_member(self):
+        """Test that pipe syntax union without any member class is not a member."""
+        union_pipe: Any = OtherClass | str
+        assert not is_class_member_of_type(union_pipe, BaseClass)
+
+    def test_annotated_member_is_member(self):
+        """Test that Annotated with a member class is detected as a member."""
+        annotated1: Any = Annotated[ChildClass, "metadata"]
+        annotated2: Any = Annotated[BaseClass, "metadata"]
+
+        assert is_class_member_of_type(annotated1, BaseClass)
+        assert is_class_member_of_type(annotated2, BaseClass)
+
+    def test_annotated_non_member_is_not_member(self):
+        """Test that Annotated with a non-member class is not a member."""
+        annotated: Any = Annotated[OtherClass, "metadata"]
+        assert not is_class_member_of_type(annotated, BaseClass)
+
+    def test_annotated_with_union_member_is_member(self):
+        """Test that Annotated with a Union containing a member class is a member."""
+        # Test with both Union styles
+        annotated1: Any = Annotated[ChildClass | OtherClass, "metadata"]
+        annotated2: Any = Annotated[ChildClass | OtherClass, "metadata"]
+
+        assert is_class_member_of_type(annotated1, BaseClass)
+        assert is_class_member_of_type(annotated2, BaseClass)
+
+    def test_nested_annotated_with_member_is_member(self):
+        """Test that nested Annotated with a member class is a member."""
+        annotated: Any = Annotated[Annotated[ChildClass, "inner"], "outer"]
+        assert is_class_member_of_type(annotated, BaseClass)
+
+    def test_none_is_not_member(self):
+        """Test that None is not a member of any class."""
+        assert not is_class_member_of_type(None, BaseClass)
+
+    def test_generic_type_is_not_member(self):
+        """Test that generic types are not members based on their parameter types."""
+        list_type: Any = list[ChildClass]
+        assert not is_class_member_of_type(list_type, BaseClass)
+
+
+class TestIsSubclassSafe:
+    def test_child_is_subclass_of_parent(self):
+        """Test that a child class is recognized as a subclass of its parent."""
+        assert issubclass_safe(ChildClass, BaseClass)
+
+    def test_class_is_subclass_of_itself(self):
+        """Test that a class is a subclass of itself."""
+        assert issubclass_safe(BaseClass, BaseClass)
+
+    def test_unrelated_class_is_not_subclass(self):
+        """Test that an unrelated class is not a subclass."""
+        assert not issubclass_safe(OtherClass, BaseClass)
+
+    def test_none_type_handled_safely(self):
+        """Test that None type is handled safely without raising TypeError."""
+        assert not issubclass_safe(cast(Any, None), BaseClass)
+
+
+class TestImage:
+    def test_image_initialization_with_path(self):
+        """Test image initialization with a path."""
+        # Mock test - we're not actually going to read a file
+        image = Image(path="test.png")
+        assert image.path is not None
+        assert image.data is None
+        assert image._mime_type == "image/png"
+
+    def test_image_path_expansion_with_tilde(self):
+        """Test that ~ is expanded to the user's home directory."""
+        image = Image(path="~/test.png")
+        assert image.path is not None
+        assert not str(image.path).startswith("~")
+        assert str(image.path).startswith(os.path.expanduser("~"))
+
+    def test_image_path_expansion_with_env_var(self, monkeypatch, tmp_path):
+        """Test that environment variables are expanded."""
+        test_dir = tmp_path / "test_path"
+        test_dir.mkdir()
+        monkeypatch.setenv("TEST_PATH", str(test_dir))
+        image = Image(path="$TEST_PATH/test.png")
+        assert image.path is not None
+        assert not str(image.path).startswith("$TEST_PATH")
+        expected_path = test_dir / "test.png"
+        assert image.path == expected_path
+
+    def test_image_initialization_with_data(self):
+        """Test image initialization with data."""
+        image = Image(data=b"test")
+        assert image.path is None
+        assert image.data == b"test"
+        assert image._mime_type == "image/png"  # Default for raw data
+
+    def test_image_initialization_with_format(self):
+        """Test image initialization with a specific format."""
+        image = Image(data=b"test", format="jpeg")
+        assert image._mime_type == "image/jpeg"
+
+    def test_missing_data_and_path_raises_error(self):
+        """Test that error is raised when neither path nor data is provided."""
+        with pytest.raises(ValueError, match="Either path or data must be provided"):
+            Image()
+
+    def test_both_data_and_path_raises_error(self):
+        """Test that error is raised when both path and data are provided."""
+        with pytest.raises(
+            ValueError, match="Only one of path or data can be provided"
+        ):
+            Image(path="test.png", data=b"test")
+
+    @pytest.mark.parametrize(
+        "extension,mime_type",
+        [
+            (".png", "image/png"),
+            (".jpg", "image/jpeg"),
+            (".jpeg", "image/jpeg"),
+            (".gif", "image/gif"),
+            (".webp", "image/webp"),
+            (".unknown", "application/octet-stream"),
+        ],
+    )
+    def test_get_mime_type_from_path(self, tmp_path, extension, mime_type):
+        """Test MIME type detection from file extension."""
+        path = tmp_path / f"test{extension}"
+        path.write_bytes(b"fake image data")
+        img = Image(path=path)
+        assert img._mime_type == mime_type
+
+    def test_to_image_content(self, tmp_path, monkeypatch):
+        """Test conversion to ImageContent."""
+        # Test with path
+        img_path = tmp_path / "test.png"
+        test_data = b"fake image data"
+        img_path.write_bytes(test_data)
+
+        img = Image(path=img_path)
+        content = img.to_image_content()
+
+        assert content.type == "image"
+        assert content.mime_type == "image/png"
+        assert content.data == base64.b64encode(test_data).decode()
+
+        # Test with data
+        img = Image(data=test_data, format="jpeg")
+        content = img.to_image_content()
+
+        assert content.type == "image"
+        assert content.mime_type == "image/jpeg"
+        assert content.data == base64.b64encode(test_data).decode()
+
+    def test_to_image_content_error(self, monkeypatch):
+        """Test error case in to_image_content."""
+        # Create an Image with neither path nor data (shouldn't happen due to __init__ checks,
+        # but testing the method's own error handling)
+        img = Image(data=b"test")
+        monkeypatch.setattr(img, "path", None)
+        monkeypatch.setattr(img, "data", None)
+
+        with pytest.raises(ValueError, match="No image data available"):
+            img.to_image_content()
+
+    @pytest.mark.parametrize(
+        "mime_type,fname,expected_mime",
+        [
+            (None, "test.png", "image/png"),
+            ("image/jpeg", "test.unknown", "image/jpeg"),
+        ],
+    )
+    def test_to_data_uri(self, tmp_path, mime_type, fname, expected_mime):
+        """Test conversion to data URI."""
+        img_path = tmp_path / fname
+        test_data = b"fake image data"
+        img_path.write_bytes(test_data)
+
+        img = Image(path=img_path)
+        data_uri = img.to_data_uri(mime_type=mime_type)
+
+        expected_data_uri = (
+            f"data:{expected_mime};base64,{base64.b64encode(test_data).decode()}"
+        )
+        assert data_uri == expected_data_uri
+
+
+class TestAudio:
+    def test_audio_initialization_with_path(self):
+        """Test audio initialization with a path."""
+        # Mock test - we're not actually going to read a file
+        audio = Audio(path="test.wav")
+        assert audio.path is not None
+        assert audio.data is None
+        assert audio._mime_type == "audio/wav"
+
+    def test_audio_path_expansion_with_tilde(self):
+        """Test that ~ is expanded to the user's home directory."""
+        audio = Audio(path="~/test.wav")
+        assert audio.path is not None
+        assert not str(audio.path).startswith("~")
+        assert str(audio.path).startswith(os.path.expanduser("~"))
+
+    def test_audio_path_expansion_with_env_var(self, monkeypatch, tmp_path):
+        """Test that environment variables are expanded."""
+        test_dir = tmp_path / "test_audio_path"
+        test_dir.mkdir()
+        monkeypatch.setenv("TEST_AUDIO_PATH", str(test_dir))
+        audio = Audio(path="$TEST_AUDIO_PATH/test.wav")
+        assert audio.path is not None
+        assert not str(audio.path).startswith("$TEST_AUDIO_PATH")
+        expected_path = test_dir / "test.wav"
+        assert audio.path == expected_path
+
+    def test_audio_initialization_with_data(self):
+        """Test audio initialization with data."""
+        audio = Audio(data=b"test")
+        assert audio.path is None
+        assert audio.data == b"test"
+        assert audio._mime_type == "audio/wav"  # Default for raw data
+
+    def test_audio_initialization_with_format(self):
+        """Test audio initialization with a specific format."""
+        audio = Audio(data=b"test", format="mp3")
+        assert audio._mime_type == "audio/mp3"
+
+    def test_missing_data_and_path_raises_error(self):
+        """Test that error is raised when neither path nor data is provided."""
+        with pytest.raises(ValueError, match="Either path or data must be provided"):
+            Audio()
+
+    def test_both_data_and_path_raises_error(self):
+        """Test that error is raised when both path and data are provided."""
+        with pytest.raises(
+            ValueError, match="Only one of path or data can be provided"
+        ):
+            Audio(path="test.wav", data=b"test")
+
+    def test_get_mime_type_from_path(self, tmp_path):
+        """Test MIME type detection from file extension."""
+        extensions = {
+            ".wav": "audio/wav",
+            ".mp3": "audio/mpeg",
+            ".ogg": "audio/ogg",
+            ".m4a": "audio/mp4",
+            ".flac": "audio/flac",
+            ".unknown": "application/octet-stream",
+        }
+
+        for ext, mime in extensions.items():
+            path = tmp_path / f"test{ext}"
+            path.write_bytes(b"fake audio data")
+            audio = Audio(path=path)
+            assert audio._mime_type == mime
+
+    def test_to_audio_content(self, tmp_path, monkeypatch):
+        """Test conversion to AudioContent."""
+        # Test with path
+        audio_path = tmp_path / "test.wav"
+        test_data = b"fake audio data"
+        audio_path.write_bytes(test_data)
+
+        audio = Audio(path=audio_path)
+        content = audio.to_audio_content()
+
+        assert content.type == "audio"
+        assert content.mime_type == "audio/wav"
+        assert content.data == base64.b64encode(test_data).decode()
+
+        # Test with data
+        audio = Audio(data=test_data, format="mp3")
+        content = audio.to_audio_content()
+
+        assert content.type == "audio"
+        assert content.mime_type == "audio/mp3"
+        assert content.data == base64.b64encode(test_data).decode()
+
+    def test_to_audio_content_error(self, monkeypatch):
+        """Test error case in to_audio_content."""
+        # Create an Audio with neither path nor data (shouldn't happen due to __init__ checks,
+        # but testing the method's own error handling)
+        audio = Audio(data=b"test")
+        monkeypatch.setattr(audio, "path", None)
+        monkeypatch.setattr(audio, "data", None)
+
+        with pytest.raises(ValueError, match="No audio data available"):
+            audio.to_audio_content()
+
+    def test_to_audio_content_with_override_mime_type(self, tmp_path):
+        """Test conversion to AudioContent with override MIME type."""
+        audio_path = tmp_path / "test.wav"
+        test_data = b"fake audio data"
+        audio_path.write_bytes(test_data)
+
+        audio = Audio(path=audio_path)
+        content = audio.to_audio_content(mime_type="audio/custom")
+
+        assert content.type == "audio"
+        assert content.mime_type == "audio/custom"
+        assert content.data == base64.b64encode(test_data).decode()
+
+
+class TestFile:
+    def test_file_initialization_with_path(self):
+        """Test file initialization with a path."""
+        # Mock test - we're not actually going to read a file
+        file = File(path="test.txt")
+        assert file.path is not None
+        assert file.data is None
+        assert file._mime_type == "text/plain"
+
+    def test_file_path_expansion_with_tilde(self):
+        """Test that ~ is expanded to the user's home directory."""
+        file = File(path="~/test.txt")
+        assert file.path is not None
+        assert not str(file.path).startswith("~")
+        assert str(file.path).startswith(os.path.expanduser("~"))
+
+    def test_file_path_expansion_with_env_var(self, monkeypatch, tmp_path):
+        """Test that environment variables are expanded."""
+        test_dir = tmp_path / "test_file_path"
+        test_dir.mkdir()
+        monkeypatch.setenv("TEST_FILE_PATH", str(test_dir))
+        file = File(path="$TEST_FILE_PATH/test.txt")
+        assert file.path is not None
+        assert not str(file.path).startswith("$TEST_FILE_PATH")
+        expected_path = test_dir / "test.txt"
+        assert file.path == expected_path
+
+    def test_file_initialization_with_data(self):
+        """Test initialization with data and format."""
+        test_data = b"test data"
+        file = File(data=test_data, format="octet-stream")
+        assert file.data == test_data
+        # The format parameter should set the MIME type
+        assert file._mime_type == "application/octet-stream"
+        assert file._name is None
+        assert file.annotations is None
+
+    def test_file_initialization_with_format(self):
+        """Test file initialization with a specific format."""
+        file = File(data=b"test", format="pdf")
+        assert file._mime_type == "application/pdf"
+
+    def test_file_initialization_with_name(self):
+        """Test file initialization with a custom name."""
+        file = File(data=b"test", name="custom")
+        assert file._name == "custom"
+
+    def test_missing_data_and_path_raises_error(self):
+        """Test that error is raised when neither path nor data is provided."""
+        with pytest.raises(ValueError, match="Either path or data must be provided"):
+            File()
+
+    def test_both_data_and_path_raises_error(self):
+        """Test that error is raised when both path and data are provided."""
+        with pytest.raises(
+            ValueError, match="Only one of path or data can be provided"
+        ):
+            File(path="test.txt", data=b"test")
+
+    def test_get_mime_type_from_path(self, tmp_path):
+        """Test MIME type detection from file extension."""
+        file_path = tmp_path / "test.txt"
+        file_path.write_text(
+            "test content"
+        )  # Need to write content for MIME type detection
+        file = File(path=file_path)
+        # The MIME type should be detected from the .txt extension
+        assert file._mime_type == "text/plain"
+
+    def test_to_resource_content_with_path(self, tmp_path):
+        """Test conversion to ResourceContent with path."""
+        file_path = tmp_path / "test.txt"
+        test_data = b"test file data"
+        file_path.write_bytes(test_data)
+
+        file = File(path=file_path)
+        resource = file.to_resource_content()
+
+        assert resource.type == "resource"
+        assert resource.resource.mime_type == "text/plain"
+        # Convert both to strings for comparison
+        assert str(resource.resource.uri) == file_path.resolve().as_uri()
+        if isinstance(resource.resource, BlobResourceContents):
+            assert resource.resource.blob == base64.b64encode(test_data).decode()
+
+    def test_to_resource_content_with_data(self):
+        """Test conversion to ResourceContent with data."""
+        test_data = b"test file data"
+        file = File(data=test_data, format="pdf")
+        resource = file.to_resource_content()
+
+        assert resource.type == "resource"
+        assert resource.resource.mime_type == "application/pdf"
+        # Convert URI to string for comparison
+        assert str(resource.resource.uri) == "file:///resource.pdf"
+        if isinstance(resource.resource, BlobResourceContents):
+            assert resource.resource.blob == base64.b64encode(test_data).decode()
+
+    def test_to_resource_content_with_text_data(self):
+        """Test conversion to ResourceContent with text data (TextResourceContents)."""
+        test_data = b"hello world"
+        file = File(data=test_data, format="plain")
+        resource = file.to_resource_content()
+        assert resource.type == "resource"
+        # Should be TextResourceContents for text/plain
+        assert isinstance(resource.resource, TextResourceContents)
+        assert resource.resource.mime_type == "text/plain"
+        assert resource.resource.text == "hello world"
+
+    def test_to_resource_content_error(self, monkeypatch):
+        """Test error case in to_resource_content."""
+        file = File(data=b"test")
+        monkeypatch.setattr(file, "path", None)
+        monkeypatch.setattr(file, "data", None)
+
+        with pytest.raises(ValueError, match="No resource data available"):
+            file.to_resource_content()
+
+    def test_to_resource_content_with_override_mime_type(self, tmp_path):
+        """Test conversion to ResourceContent with override MIME type."""
+        file_path = tmp_path / "test.txt"
+        test_data = b"test file data"
+        file_path.write_bytes(test_data)
+
+        file = File(path=file_path)
+        resource = file.to_resource_content(mime_type="application/custom")
+
+        assert resource.resource.mime_type == "application/custom"
+
+
+class TestReplaceType:
+    @pytest.mark.parametrize(
+        "input,type_map,expected",
+        [
+            (int, {}, int),
+            (int, {int: str}, str),
+            (int, {int: int}, int),
+            (int, {int: float, bool: str}, float),
+            (bool, {int: float, bool: str}, str),
+            (int, {int: list[int]}, list[int]),
+            (list[int], {int: str}, list[str]),
+            (list[int], {int: list[str]}, list[list[str]]),
+            (
+                list[int],
+                {int: float, list[int]: bool},
+                bool,
+            ),  # list[int] will match before int
+            (list[int | bool], {int: str}, list[str | bool]),
+            (list[list[int]], {int: str}, list[list[str]]),
+        ],
+    )
+    def test_replace_type(self, input, type_map, expected):
+        """Test replacing a type with another type."""
+        assert replace_type(input, type_map) == expected
+
+
+class TestCreateFunctionWithoutParams:
+    """Test create_function_without_params properly removes parameters from both annotations and signature."""
+
+    def test_removes_params_from_both_annotations_and_signature(self):
+        """Test that excluded parameters are removed from __annotations__ AND __signature__."""
+        import inspect
+
+        def original_func(ctx: str, query: str, limit: int = 10) -> list[str]:
+            return []
+
+        new_func = create_function_without_params(original_func, ["ctx"])
+
+        # Verify removal from annotations
+        assert "ctx" not in new_func.__annotations__
+        assert "query" in new_func.__annotations__
+        assert "limit" in new_func.__annotations__
+
+        # Verify removal from signature (regression test for #2562)
+        sig = inspect.signature(new_func)
+        assert "ctx" not in sig.parameters
+        assert "query" in sig.parameters
+        assert "limit" in sig.parameters
+
+    def test_preserves_return_annotation_in_signature(self):
+        """Test that return annotation is preserved in both annotations and signature."""
+        import inspect
+
+        def original_func(ctx: str, value: int) -> dict[str, int]:
+            return {}
+
+        new_func = create_function_without_params(original_func, ["ctx"])
+
+        sig = inspect.signature(new_func)
+        assert sig.return_annotation == dict[str, int]
+        assert new_func.__annotations__["return"] == dict[str, int]
+
+    def test_pydantic_typeadapter_compatibility(self):
+        """Test that modified function works with Pydantic TypeAdapter (regression test for #2562)."""
+        from pydantic import BaseModel
+
+        class Result(BaseModel):
+            name: str
+
+        def tool_function(ctx: str, search_query: str, limit: int = 10) -> list[Result]:
+            return []
+
+        # Remove context parameter (what FastMCP does internally)
+        new_func = create_function_without_params(tool_function, ["ctx"])
+
+        # This raised KeyError: 'ctx' before the fix
+        adapter = get_cached_typeadapter(new_func)
+        schema = adapter.json_schema()
+
+        # Verify schema excludes the removed parameter
+        assert "properties" in schema
+        assert "ctx" not in schema["properties"]
+        assert "search_query" in schema["properties"]
+        assert "limit" in schema["properties"]
+
+    def test_multiple_excluded_parameters(self):
+        """Test excluding multiple parameters simultaneously."""
+        import inspect
+
+        def func(ctx: str, session: int, query: str, limit: int = 5) -> str:
+            return ""
+
+        new_func = create_function_without_params(func, ["ctx", "session"])
+
+        sig = inspect.signature(new_func)
+
+        # Both excluded params should be removed
+        assert "ctx" not in sig.parameters
+        assert "session" not in sig.parameters
+        assert "ctx" not in new_func.__annotations__
+        assert "session" not in new_func.__annotations__
+
+        # Non-excluded params should remain
+        assert "query" in sig.parameters
+        assert "limit" in sig.parameters
+
+
+class TestAnnotationStringDescriptions:
+    """Test the new functionality for string descriptions in Annotated types."""
+
+    def test_get_cached_typeadapter_with_string_descriptions(self):
+        """Test TypeAdapter creation with string descriptions."""
+
+        def func(name: Annotated[str, "The user's name"]) -> str:
+            return f"Hello {name}"
+
+        adapter = get_cached_typeadapter(func)
+        schema = adapter.json_schema()
+
+        # Should have description in schema
+        assert "properties" in schema
+        assert "name" in schema["properties"]
+        assert schema["properties"]["name"]["description"] == "The user's name"
+
+    def test_multiple_string_annotations(self):
+        """Test function with multiple string-annotated parameters."""
+
+        def func(
+            name: Annotated[str, "User's name"],
+            email: Annotated[str, "User's email"],
+            age: int,
+        ) -> str:
+            return f"{name} ({email}) is {age}"
+
+        adapter = get_cached_typeadapter(func)
+        schema = adapter.json_schema()
+
+        # Both annotated parameters should have descriptions
+        assert schema["properties"]["name"]["description"] == "User's name"
+        assert schema["properties"]["email"]["description"] == "User's email"
+        # Non-annotated parameter should not have description
+        assert "description" not in schema["properties"]["age"]
+
+    def test_annotated_with_more_than_string_unchanged(self):
+        """Test that Annotated with more than just a string is unchanged."""
+
+        def func(name: Annotated[str, "desc", "extra"]) -> str:
+            return f"Hello {name}"
+
+        adapter = get_cached_typeadapter(func)
+        schema = adapter.json_schema()
+
+        # Should not have description since it's not exactly length 2
+        assert "description" not in schema["properties"]["name"]
+
+    def test_annotated_with_non_string_unchanged(self):
+        """Test that Annotated with non-string second arg is unchanged."""
+
+        def func(name: Annotated[str, 42]) -> str:
+            return f"Hello {name}"
+
+        adapter = get_cached_typeadapter(func)
+        schema = adapter.json_schema()
+
+        # Should not have description since second arg is not string
+        assert "description" not in schema["properties"]["name"]
+
+    def test_existing_field_unchanged(self):
+        """Test that existing Field annotations are unchanged."""
+
+        def func(name: Annotated[str, Field(description="Field desc")]) -> str:
+            return f"Hello {name}"
+
+        adapter = get_cached_typeadapter(func)
+        schema = adapter.json_schema()
+
+        # Should keep the Field description
+        assert schema["properties"]["name"]["description"] == "Field desc"
+
+    def test_kwonly_defaults_preserved_when_annotations_are_processed(self):
+        """Keyword-only defaults should survive function cloning during annotation processing."""
+
+        def func(*, limit: Annotated[int, "Maximum number of results"] = 5) -> int:
+            return limit
+
+        adapter = get_cached_typeadapter(func)
+        schema = adapter.json_schema()
+
+        assert "required" not in schema
+        assert schema["properties"]["limit"]["default"] == 5
+        assert (
+            schema["properties"]["limit"]["description"] == "Maximum number of results"
+        )
+
+        validated = adapter.validate_python({})
+        assert validated == 5
diff --git a/tests/utilities/test_version_check.py b/tests/utilities/test_version_check.py
new file mode 100644
index 0000000..9cc9aab
--- /dev/null
+++ b/tests/utilities/test_version_check.py
@@ -0,0 +1,315 @@
+"""Tests for version checking utilities."""
+
+import json
+import time
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import httpx
+import pytest
+
+from fastmcp.utilities.version_check import (
+    CACHE_TTL_SECONDS,
+    _fetch_latest_version,
+    _get_cache_path,
+    _read_cache,
+    _write_cache,
+    check_for_newer_version,
+    get_latest_version,
+)
+
+
+class TestCachePath:
+    def test_cache_path_in_home_directory(self):
+        """Cache file should be in fastmcp home directory."""
+        cache_path = _get_cache_path()
+        assert cache_path.name == "version_cache.json"
+        assert "fastmcp" in str(cache_path).lower()
+
+    def test_cache_path_prerelease_suffix(self):
+        """Prerelease cache uses different file."""
+        cache_path = _get_cache_path(include_prereleases=True)
+        assert cache_path.name == "version_cache_prerelease.json"
+
+
+class TestReadCache:
+    def test_read_cache_no_file(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        """Reading non-existent cache returns None."""
+        monkeypatch.setattr(
+            "fastmcp.utilities.version_check._get_cache_path",
+            lambda include_prereleases=False: tmp_path / "nonexistent.json",
+        )
+        version, timestamp = _read_cache()
+        assert version is None
+        assert timestamp == 0
+
+    def test_read_cache_valid(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        """Reading valid cache returns version and timestamp."""
+        cache_file = tmp_path / "version_cache.json"
+        cache_file.write_text(
+            json.dumps({"latest_version": "2.5.0", "timestamp": 1000})
+        )
+        monkeypatch.setattr(
+            "fastmcp.utilities.version_check._get_cache_path",
+            lambda include_prereleases=False: cache_file,
+        )
+
+        version, timestamp = _read_cache()
+        assert version == "2.5.0"
+        assert timestamp == 1000
+
+    def test_read_cache_invalid_json(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ):
+        """Reading invalid JSON returns None."""
+        cache_file = tmp_path / "version_cache.json"
+        cache_file.write_text("not valid json")
+        monkeypatch.setattr(
+            "fastmcp.utilities.version_check._get_cache_path",
+            lambda include_prereleases=False: cache_file,
+        )
+
+        version, timestamp = _read_cache()
+        assert version is None
+        assert timestamp == 0
+
+
+class TestWriteCache:
+    def test_write_cache_creates_file(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ):
+        """Writing cache creates the cache file."""
+        cache_file = tmp_path / "subdir" / "version_cache.json"
+        monkeypatch.setattr(
+            "fastmcp.utilities.version_check._get_cache_path",
+            lambda include_prereleases=False: cache_file,
+        )
+
+        _write_cache("2.6.0")
+
+        assert cache_file.exists()
+        data = json.loads(cache_file.read_text())
+        assert data["latest_version"] == "2.6.0"
+        assert "timestamp" in data
+
+
+class TestFetchLatestVersion:
+    def test_fetch_success(self):
+        """Successful fetch returns highest stable version."""
+        mock_response = MagicMock()
+        mock_response.json.return_value = {
+            "releases": {
+                "2.5.0": [],
+                "2.4.0": [],
+                "2.6.0b1": [],  # prerelease should be skipped
+            }
+        }
+
+        with patch("httpx.get", return_value=mock_response) as mock_get:
+            version = _fetch_latest_version()
+            assert version == "2.5.0"
+            mock_get.assert_called_once()
+
+    def test_fetch_network_error(self):
+        """Network error returns None."""
+        with patch("httpx.get", side_effect=httpx.HTTPError("Network error")):
+            version = _fetch_latest_version()
+            assert version is None
+
+    def test_fetch_invalid_response(self):
+        """Invalid response returns None."""
+        mock_response = MagicMock()
+        mock_response.json.return_value = {"unexpected": "format"}
+
+        with patch("httpx.get", return_value=mock_response):
+            version = _fetch_latest_version()
+            assert version is None
+
+    def test_fetch_prereleases(self):
+        """Fetching with prereleases returns highest version."""
+        mock_response = MagicMock()
+        mock_response.json.return_value = {
+            "info": {"version": "2.5.0"},
+            "releases": {
+                "2.5.0": [],
+                "2.6.0b1": [],
+                "2.6.0b2": [],
+                "2.4.0": [],
+            },
+        }
+
+        with patch("httpx.get", return_value=mock_response):
+            version = _fetch_latest_version(include_prereleases=True)
+            assert version == "2.6.0b2"
+
+    def test_fetch_prereleases_stable_is_highest(self):
+        """Prerelease mode still returns stable if it's highest."""
+        mock_response = MagicMock()
+        mock_response.json.return_value = {
+            "info": {"version": "2.5.0"},
+            "releases": {
+                "2.5.0": [],
+                "2.5.0b1": [],
+                "2.4.0": [],
+            },
+        }
+
+        with patch("httpx.get", return_value=mock_response):
+            version = _fetch_latest_version(include_prereleases=True)
+            assert version == "2.5.0"
+
+
+class TestGetLatestVersion:
+    def test_returns_cached_version_if_fresh(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ):
+        """Uses cached version if cache is fresh."""
+        cache_file = tmp_path / "version_cache.json"
+        cache_file.write_text(
+            json.dumps({"latest_version": "2.5.0", "timestamp": time.time()})
+        )
+        monkeypatch.setattr(
+            "fastmcp.utilities.version_check._get_cache_path",
+            lambda include_prereleases=False: cache_file,
+        )
+
+        with patch(
+            "fastmcp.utilities.version_check._fetch_latest_version"
+        ) as mock_fetch:
+            version = get_latest_version()
+            assert version == "2.5.0"
+            mock_fetch.assert_not_called()
+
+    def test_fetches_if_cache_stale(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ):
+        """Fetches from PyPI if cache is stale."""
+        cache_file = tmp_path / "version_cache.json"
+        old_timestamp = time.time() - CACHE_TTL_SECONDS - 100
+        cache_file.write_text(
+            json.dumps({"latest_version": "2.4.0", "timestamp": old_timestamp})
+        )
+        monkeypatch.setattr(
+            "fastmcp.utilities.version_check._get_cache_path",
+            lambda include_prereleases=False: cache_file,
+        )
+
+        with patch(
+            "fastmcp.utilities.version_check._fetch_latest_version",
+            return_value="2.5.0",
+        ) as mock_fetch:
+            version = get_latest_version()
+            assert version == "2.5.0"
+            mock_fetch.assert_called_once()
+
+    def test_returns_stale_cache_if_fetch_fails(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ):
+        """Returns stale cache if fetch fails."""
+        cache_file = tmp_path / "version_cache.json"
+        old_timestamp = time.time() - CACHE_TTL_SECONDS - 100
+        cache_file.write_text(
+            json.dumps({"latest_version": "2.4.0", "timestamp": old_timestamp})
+        )
+        monkeypatch.setattr(
+            "fastmcp.utilities.version_check._get_cache_path",
+            lambda include_prereleases=False: cache_file,
+        )
+
+        with patch(
+            "fastmcp.utilities.version_check._fetch_latest_version", return_value=None
+        ):
+            version = get_latest_version()
+            assert version == "2.4.0"
+
+
+class TestCheckForNewerVersion:
+    def test_returns_none_if_disabled(self, monkeypatch: pytest.MonkeyPatch):
+        """Returns None if check_for_updates is off."""
+        import fastmcp
+
+        monkeypatch.setattr(fastmcp.settings, "check_for_updates", "off")
+
+        result = check_for_newer_version()
+        assert result is None
+
+    def test_returns_none_if_current(self, monkeypatch: pytest.MonkeyPatch):
+        """Returns None if current version is latest."""
+        import fastmcp
+
+        monkeypatch.setattr(fastmcp.settings, "check_for_updates", "stable")
+        monkeypatch.setattr(fastmcp, "__version__", "2.5.0")
+
+        with patch(
+            "fastmcp.utilities.version_check.get_latest_version", return_value="2.5.0"
+        ):
+            result = check_for_newer_version()
+            assert result is None
+
+    def test_returns_version_if_newer(self, monkeypatch: pytest.MonkeyPatch):
+        """Returns new version if available."""
+        import fastmcp
+
+        monkeypatch.setattr(fastmcp.settings, "check_for_updates", "stable")
+        monkeypatch.setattr(fastmcp, "__version__", "2.4.0")
+
+        with patch(
+            "fastmcp.utilities.version_check.get_latest_version", return_value="2.5.0"
+        ):
+            result = check_for_newer_version()
+            assert result == "2.5.0"
+
+    def test_returns_none_if_older_available(self, monkeypatch: pytest.MonkeyPatch):
+        """Returns None if pypi version is older than current (dev version)."""
+        import fastmcp
+
+        monkeypatch.setattr(fastmcp.settings, "check_for_updates", "stable")
+        monkeypatch.setattr(fastmcp, "__version__", "3.0.0.dev1")
+
+        with patch(
+            "fastmcp.utilities.version_check.get_latest_version", return_value="2.5.0"
+        ):
+            result = check_for_newer_version()
+            assert result is None
+
+    def test_handles_invalid_versions(self, monkeypatch: pytest.MonkeyPatch):
+        """Handles invalid version strings gracefully."""
+        import fastmcp
+
+        monkeypatch.setattr(fastmcp.settings, "check_for_updates", "stable")
+        monkeypatch.setattr(fastmcp, "__version__", "invalid")
+
+        with patch(
+            "fastmcp.utilities.version_check.get_latest_version",
+            return_value="also-invalid",
+        ):
+            result = check_for_newer_version()
+            assert result is None
+
+    def test_prerelease_setting(self, monkeypatch: pytest.MonkeyPatch):
+        """Prerelease setting passes include_prereleases=True."""
+        import fastmcp
+
+        monkeypatch.setattr(fastmcp.settings, "check_for_updates", "prerelease")
+        monkeypatch.setattr(fastmcp, "__version__", "2.5.0")
+
+        with patch(
+            "fastmcp.utilities.version_check.get_latest_version", return_value="2.6.0b1"
+        ) as mock_get:
+            result = check_for_newer_version()
+            assert result == "2.6.0b1"
+            mock_get.assert_called_once_with(True)
+
+    def test_stable_setting(self, monkeypatch: pytest.MonkeyPatch):
+        """Stable setting passes include_prereleases=False."""
+        import fastmcp
+
+        monkeypatch.setattr(fastmcp.settings, "check_for_updates", "stable")
+        monkeypatch.setattr(fastmcp, "__version__", "2.4.0")
+
+        with patch(
+            "fastmcp.utilities.version_check.get_latest_version", return_value="2.5.0"
+        ) as mock_get:
+            result = check_for_newer_version()
+            assert result == "2.5.0"
+            mock_get.assert_called_once_with(False)
diff --git a/uv.lock b/uv.lock
new file mode 100644
index 0000000..d78c551
--- /dev/null
+++ b/uv.lock
@@ -0,0 +1,3463 @@
+version = 1
+revision = 3
+requires-python = ">=3.10"
+resolution-markers = [
+    "python_full_version >= '3.14'",
+    "python_full_version == '3.13.*'",
+    "python_full_version == '3.12.*'",
+    "python_full_version == '3.11.*'",
+    "python_full_version < '3.11'",
+]
+
+[options]
+exclude-newer = "2026-06-29T14:57:29.757967Z"
+exclude-newer-span = "P1W"
+
+[options.exclude-newer-package]
+mcp-types = false
+prefab-ui = false
+mcp = false
+
+[manifest]
+members = [
+    "fastmcp",
+    "fastmcp-remote",
+    "fastmcp-slim",
+]
+
+[[package]]
+name = "aiofile"
+version = "3.9.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "caio" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/67/e2/d7cb819de8df6b5c1968a2756c3cb4122d4fa2b8fc768b53b7c9e5edb646/aiofile-3.9.0.tar.gz", hash = "sha256:e5ad718bb148b265b6df1b3752c4d1d83024b93da9bd599df74b9d9ffcf7919b", size = 17943, upload-time = "2024-10-08T10:39:35.846Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/50/25/da1f0b4dd970e52bf5a36c204c107e11a0c6d3ed195eba0bfbc664c312b2/aiofile-3.9.0-py3-none-any.whl", hash = "sha256:ce2f6c1571538cbdfa0143b04e16b208ecb0e9cb4148e528af8a640ed51cc8aa", size = 19539, upload-time = "2024-10-08T10:39:32.955Z" },
+]
+
+[[package]]
+name = "annotated-doc"
+version = "0.0.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/57/ba/046ceea27344560984e26a590f90bc7f4a75b06701f653222458922b558c/annotated_doc-0.0.4.tar.gz", hash = "sha256:fbcda96e87e9c92ad167c2e53839e57503ecfda18804ea28102353485033faa4", size = 7288, upload-time = "2025-11-10T22:07:42.062Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1e/d3/26bf1008eb3d2daa8ef4cacc7f3bfdc11818d111f7e2d0201bc6e3b49d45/annotated_doc-0.0.4-py3-none-any.whl", hash = "sha256:571ac1dc6991c450b25a9c2d84a3705e2ae7a53467b5d111c24fa8baabbed320", size = 5303, upload-time = "2025-11-10T22:07:40.673Z" },
+]
+
+[[package]]
+name = "annotated-types"
+version = "0.7.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ee/67/531ea369ba64dcff5ec9c3402f9f51bf748cec26dde048a2f973a4eea7f5/annotated_types-0.7.0.tar.gz", hash = "sha256:aff07c09a53a08bc8cfccb9c85b05f1aa9a2a6f23728d790723543408344ce89", size = 16081, upload-time = "2024-05-20T21:33:25.928Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/78/b6/6307fbef88d9b5ee7421e68d78a9f162e0da4900bc5f5793f6d3d0e34fb8/annotated_types-0.7.0-py3-none-any.whl", hash = "sha256:1f02e8b43a8fbbc3f3e0d4f0f4bfc8131bcb4eebe8849b8e5c773f3a1c582a53", size = 13643, upload-time = "2024-05-20T21:33:24.1Z" },
+]
+
+[[package]]
+name = "anthropic"
+version = "0.87.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "distro" },
+    { name = "docstring-parser" },
+    { name = "httpx" },
+    { name = "jiter" },
+    { name = "pydantic" },
+    { name = "sniffio" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d6/8f/3281edf7c35cbac169810e5388eb9b38678c7ea9867c2d331237bd5dff08/anthropic-0.87.0.tar.gz", hash = "sha256:098fef3753cdd3c0daa86f95efb9c8d03a798d45c5170329525bb4653f6702d0", size = 588982, upload-time = "2026-03-31T17:52:41.697Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0d/02/99bf351933bdea0545a2b6e2d812ed878899e9a95f618351dfa3d0de0e69/anthropic-0.87.0-py3-none-any.whl", hash = "sha256:e2669b86d42c739d3df163f873c51719552e263a3d85179297180fb4fa00a236", size = 472126, upload-time = "2026-03-31T17:52:40.174Z" },
+]
+
+[[package]]
+name = "anyio"
+version = "4.13.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "exceptiongroup", marker = "python_full_version < '3.11'" },
+    { name = "idna" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/19/14/2c5dd9f512b66549ae92767a9c7b330ae88e1932ca57876909410251fe13/anyio-4.13.0.tar.gz", hash = "sha256:334b70e641fd2221c1505b3890c69882fe4a2df910cba14d97019b90b24439dc", size = 231622, upload-time = "2026-03-24T12:59:09.671Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/da/42/e921fccf5015463e32a3cf6ee7f980a6ed0f395ceeaa45060b61d86486c2/anyio-4.13.0-py3-none-any.whl", hash = "sha256:08b310f9e24a9594186fd75b4f73f4a4152069e3853f1ed8bfbf58369f4ad708", size = 114353, upload-time = "2026-03-24T12:59:08.246Z" },
+]
+
+[[package]]
+name = "asttokens"
+version = "3.0.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/be/a5/8e3f9b6771b0b408517c82d97aed8f2036509bc247d46114925e32fe33f0/asttokens-3.0.1.tar.gz", hash = "sha256:71a4ee5de0bde6a31d64f6b13f2293ac190344478f081c3d1bccfcf5eacb0cb7", size = 62308, upload-time = "2025-11-15T16:43:48.578Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d2/39/e7eaf1799466a4aef85b6a4fe7bd175ad2b1c6345066aa33f1f58d4b18d0/asttokens-3.0.1-py3-none-any.whl", hash = "sha256:15a3ebc0f43c2d0a50eeafea25e19046c68398e487b9f1f5b517f7c0f40f976a", size = 27047, upload-time = "2025-11-15T16:43:16.109Z" },
+]
+
+[[package]]
+name = "async-timeout"
+version = "5.0.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a5/ae/136395dfbfe00dfc94da3f3e136d0b13f394cba8f4841120e34226265780/async_timeout-5.0.1.tar.gz", hash = "sha256:d9321a7a3d5a6a5e187e824d2fa0793ce379a202935782d555d6e9d2735677d3", size = 9274, upload-time = "2024-11-06T16:41:39.6Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fe/ba/e2081de779ca30d473f21f5b30e0e737c438205440784c7dfc81efc2b029/async_timeout-5.0.1-py3-none-any.whl", hash = "sha256:39e3809566ff85354557ec2398b55e096c8364bacac9405a7a1fa429e77fe76c", size = 6233, upload-time = "2024-11-06T16:41:37.9Z" },
+]
+
+[[package]]
+name = "attrs"
+version = "26.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/9a/8e/82a0fe20a541c03148528be8cac2408564a6c9a0cc7e9171802bc1d26985/attrs-26.1.0.tar.gz", hash = "sha256:d03ceb89cb322a8fd706d4fb91940737b6642aa36998fe130a9bc96c985eff32", size = 952055, upload-time = "2026-03-19T14:22:25.026Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/64/b4/17d4b0b2a2dc85a6df63d1157e028ed19f90d4cd97c36717afef2bc2f395/attrs-26.1.0-py3-none-any.whl", hash = "sha256:c647aa4a12dfbad9333ca4e71fe62ddc36f4e63b2d260a37a8b83d2f043ac309", size = 67548, upload-time = "2026-03-19T14:22:23.645Z" },
+]
+
+[[package]]
+name = "authlib"
+version = "1.7.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cryptography" },
+    { name = "joserfc" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/36/98/7d93f30d029643c0275dbc0bd6d5a6f670661ee6c9a94d93af7ab4887600/authlib-1.7.2.tar.gz", hash = "sha256:2cea25fefcd4e7173bdf1372c0afc265c8034b23a8cd5dcb6a9164b826c64231", size = 176511, upload-time = "2026-05-06T08:10:23.116Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fb/95/adcb68e20c34162e9135f370d6e31737719c2b6f94bc953fe7ed1f10fe21/authlib-1.7.2-py2.py3-none-any.whl", hash = "sha256:3e1faedc9d87e7d56a164eca3ccb6ace0d61b94abe83e92242f8dc8bba9b4a9f", size = 259548, upload-time = "2026-05-06T08:10:21.436Z" },
+]
+
+[[package]]
+name = "azure-core"
+version = "1.39.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "requests" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/34/83/bbde3faa84ddcb8eb0eca4b3ffb3221252281db4ce351300fe248c5c70b1/azure_core-1.39.0.tar.gz", hash = "sha256:8a90a562998dd44ce84597590fff6249701b98c0e8797c95fcdd695b54c35d74", size = 367531, upload-time = "2026-03-19T01:31:29.461Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7e/d6/8ebcd05b01a580f086ac9a97fb9fac65c09a4b012161cc97c21a336e880b/azure_core-1.39.0-py3-none-any.whl", hash = "sha256:4ac7b70fab5438c3f68770649a78daf97833caa83827f91df9c14e0e0ea7d34f", size = 218318, upload-time = "2026-03-19T01:31:31.25Z" },
+]
+
+[[package]]
+name = "azure-identity"
+version = "1.25.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "azure-core" },
+    { name = "cryptography" },
+    { name = "msal" },
+    { name = "msal-extensions" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c5/0e/3a63efb48aa4a5ae2cfca61ee152fbcb668092134d3eb8bfda472dd5c617/azure_identity-1.25.3.tar.gz", hash = "sha256:ab23c0d63015f50b630ef6c6cf395e7262f439ce06e5d07a64e874c724f8d9e6", size = 286304, upload-time = "2026-03-13T01:12:20.892Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/49/9a/417b3a533e01953a7c618884df2cb05a71e7b68bdbce4fbdb62349d2a2e8/azure_identity-1.25.3-py3-none-any.whl", hash = "sha256:f4d0b956a8146f30333e071374171f3cfa7bdb8073adb8c3814b65567aa7447c", size = 192138, upload-time = "2026-03-13T01:12:22.951Z" },
+]
+
+[[package]]
+name = "backports-asyncio-runner"
+version = "1.2.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/8e/ff/70dca7d7cb1cbc0edb2c6cc0c38b65cba36cccc491eca64cabd5fe7f8670/backports_asyncio_runner-1.2.0.tar.gz", hash = "sha256:a5aa7b2b7d8f8bfcaa2b57313f70792df84e32a2a746f585213373f900b42162", size = 69893, upload-time = "2025-07-02T02:27:15.685Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a0/59/76ab57e3fe74484f48a53f8e337171b4a2349e506eabe136d7e01d059086/backports_asyncio_runner-1.2.0-py3-none-any.whl", hash = "sha256:0da0a936a8aeb554eccb426dc55af3ba63bcdc69fa1a600b5bb305413a4477b5", size = 12313, upload-time = "2025-07-02T02:27:14.263Z" },
+]
+
+[[package]]
+name = "backports-tarfile"
+version = "1.2.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/86/72/cd9b395f25e290e633655a100af28cb253e4393396264a98bd5f5951d50f/backports_tarfile-1.2.0.tar.gz", hash = "sha256:d75e02c268746e1b8144c278978b6e98e85de6ad16f8e4b0844a154557eca991", size = 86406, upload-time = "2024-05-28T17:01:54.731Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b9/fa/123043af240e49752f1c4bd24da5053b6bd00cad78c2be53c0d1e8b975bc/backports.tarfile-1.2.0-py3-none-any.whl", hash = "sha256:77e284d754527b01fb1e6fa8a1afe577858ebe4e9dad8919e34c862cb399bc34", size = 30181, upload-time = "2024-05-28T17:01:53.112Z" },
+]
+
+[[package]]
+name = "beartype"
+version = "0.22.9"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c7/94/1009e248bbfbab11397abca7193bea6626806be9a327d399810d523a07cb/beartype-0.22.9.tar.gz", hash = "sha256:8f82b54aa723a2848a56008d18875f91c1db02c32ef6a62319a002e3e25a975f", size = 1608866, upload-time = "2025-12-13T06:50:30.72Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/71/cc/18245721fa7747065ab478316c7fea7c74777d07f37ae60db2e84f8172e8/beartype-0.22.9-py3-none-any.whl", hash = "sha256:d16c9bbc61ea14637596c5f6fbff2ee99cbe3573e46a716401734ef50c3060c2", size = 1333658, upload-time = "2025-12-13T06:50:28.266Z" },
+]
+
+[[package]]
+name = "black"
+version = "26.3.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+    { name = "mypy-extensions" },
+    { name = "packaging" },
+    { name = "pathspec" },
+    { name = "platformdirs" },
+    { name = "pytokens" },
+    { name = "tomli", marker = "python_full_version < '3.11'" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e1/c5/61175d618685d42b005847464b8fb4743a67b1b8fdb75e50e5a96c31a27a/black-26.3.1.tar.gz", hash = "sha256:2c50f5063a9641c7eed7795014ba37b0f5fa227f3d408b968936e24bc0566b07", size = 666155, upload-time = "2026-03-12T03:36:03.593Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/32/a8/11170031095655d36ebc6664fe0897866f6023892396900eec0e8fdc4299/black-26.3.1-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:86a8b5035fce64f5dcd1b794cf8ec4d31fe458cf6ce3986a30deb434df82a1d2", size = 1866562, upload-time = "2026-03-12T03:39:58.639Z" },
+    { url = "https://files.pythonhosted.org/packages/69/ce/9e7548d719c3248c6c2abfd555d11169457cbd584d98d179111338423790/black-26.3.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:5602bdb96d52d2d0672f24f6ffe5218795736dd34807fd0fd55ccd6bf206168b", size = 1703623, upload-time = "2026-03-12T03:40:00.347Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/0a/8d17d1a9c06f88d3d030d0b1d4373c1551146e252afe4547ed601c0e697f/black-26.3.1-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6c54a4a82e291a1fee5137371ab488866b7c86a3305af4026bdd4dc78642e1ac", size = 1768388, upload-time = "2026-03-12T03:40:01.765Z" },
+    { url = "https://files.pythonhosted.org/packages/52/79/c1ee726e221c863cde5164f925bacf183dfdf0397d4e3f94889439b947b4/black-26.3.1-cp310-cp310-win_amd64.whl", hash = "sha256:6e131579c243c98f35bce64a7e08e87fb2d610544754675d4a0e73a070a5aa3a", size = 1412969, upload-time = "2026-03-12T03:40:03.252Z" },
+    { url = "https://files.pythonhosted.org/packages/73/a5/15c01d613f5756f68ed8f6d4ec0a1e24b82b18889fa71affd3d1f7fad058/black-26.3.1-cp310-cp310-win_arm64.whl", hash = "sha256:5ed0ca58586c8d9a487352a96b15272b7fa55d139fc8496b519e78023a8dab0a", size = 1220345, upload-time = "2026-03-12T03:40:04.892Z" },
+    { url = "https://files.pythonhosted.org/packages/17/57/5f11c92861f9c92eb9dddf515530bc2d06db843e44bdcf1c83c1427824bc/black-26.3.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:28ef38aee69e4b12fda8dba75e21f9b4f979b490c8ac0baa7cb505369ac9e1ff", size = 1851987, upload-time = "2026-03-12T03:40:06.248Z" },
+    { url = "https://files.pythonhosted.org/packages/54/aa/340a1463660bf6831f9e39646bf774086dbd8ca7fc3cded9d59bbdf4ad0a/black-26.3.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:bf9bf162ed91a26f1adba8efda0b573bc6924ec1408a52cc6f82cb73ec2b142c", size = 1689499, upload-time = "2026-03-12T03:40:07.642Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/01/b726c93d717d72733da031d2de10b92c9fa4c8d0c67e8a8a372076579279/black-26.3.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:474c27574d6d7037c1bc875a81d9be0a9a4f9ee95e62800dab3cfaadbf75acd5", size = 1754369, upload-time = "2026-03-12T03:40:09.279Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/09/61e91881ca291f150cfc9eb7ba19473c2e59df28859a11a88248b5cbbc4d/black-26.3.1-cp311-cp311-win_amd64.whl", hash = "sha256:5e9d0d86df21f2e1677cc4bd090cd0e446278bcbbe49bf3659c308c3e402843e", size = 1413613, upload-time = "2026-03-12T03:40:10.943Z" },
+    { url = "https://files.pythonhosted.org/packages/16/73/544f23891b22e7efe4d8f812371ab85b57f6a01b2fc45e3ba2e52ba985b8/black-26.3.1-cp311-cp311-win_arm64.whl", hash = "sha256:9a5e9f45e5d5e1c5b5c29b3bd4265dcc90e8b92cf4534520896ed77f791f4da5", size = 1219719, upload-time = "2026-03-12T03:40:12.597Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/f8/da5eae4fc75e78e6dceb60624e1b9662ab00d6b452996046dfa9b8a6025b/black-26.3.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:b5e6f89631eb88a7302d416594a32faeee9fb8fb848290da9d0a5f2903519fc1", size = 1895920, upload-time = "2026-03-12T03:40:13.921Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/9f/04e6f26534da2e1629b2b48255c264cabf5eedc5141d04516d9d68a24111/black-26.3.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:41cd2012d35b47d589cb8a16faf8a32ef7a336f56356babd9fcf70939ad1897f", size = 1718499, upload-time = "2026-03-12T03:40:15.239Z" },
+    { url = "https://files.pythonhosted.org/packages/04/91/a5935b2a63e31b331060c4a9fdb5a6c725840858c599032a6f3aac94055f/black-26.3.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0f76ff19ec5297dd8e66eb64deda23631e642c9393ab592826fd4bdc97a4bce7", size = 1794994, upload-time = "2026-03-12T03:40:17.124Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/0a/86e462cdd311a3c2a8ece708d22aba17d0b2a0d5348ca34b40cdcbea512e/black-26.3.1-cp312-cp312-win_amd64.whl", hash = "sha256:ddb113db38838eb9f043623ba274cfaf7d51d5b0c22ecb30afe58b1bb8322983", size = 1420867, upload-time = "2026-03-12T03:40:18.83Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/e5/22515a19cb7eaee3440325a6b0d95d2c0e88dd180cb011b12ae488e031d1/black-26.3.1-cp312-cp312-win_arm64.whl", hash = "sha256:dfdd51fc3e64ea4f35873d1b3fb25326773d55d2329ff8449139ebaad7357efb", size = 1230124, upload-time = "2026-03-12T03:40:20.425Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/77/5728052a3c0450c53d9bb3945c4c46b91baa62b2cafab6801411b6271e45/black-26.3.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:855822d90f884905362f602880ed8b5df1b7e3ee7d0db2502d4388a954cc8c54", size = 1895034, upload-time = "2026-03-12T03:40:21.813Z" },
+    { url = "https://files.pythonhosted.org/packages/52/73/7cae55fdfdfbe9d19e9a8d25d145018965fe2079fa908101c3733b0c55a0/black-26.3.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:8a33d657f3276328ce00e4d37fe70361e1ec7614da5d7b6e78de5426cb56332f", size = 1718503, upload-time = "2026-03-12T03:40:23.666Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/87/af89ad449e8254fdbc74654e6467e3c9381b61472cc532ee350d28cfdafb/black-26.3.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f1cd08e99d2f9317292a311dfe578fd2a24b15dbce97792f9c4d752275c1fa56", size = 1793557, upload-time = "2026-03-12T03:40:25.497Z" },
+    { url = "https://files.pythonhosted.org/packages/43/10/d6c06a791d8124b843bf325ab4ac7d2f5b98731dff84d6064eafd687ded1/black-26.3.1-cp313-cp313-win_amd64.whl", hash = "sha256:c7e72339f841b5a237ff14f7d3880ddd0fc7f98a1199e8c4327f9a4f478c1839", size = 1422766, upload-time = "2026-03-12T03:40:27.14Z" },
+    { url = "https://files.pythonhosted.org/packages/59/4f/40a582c015f2d841ac24fed6390bd68f0fc896069ff3a886317959c9daf8/black-26.3.1-cp313-cp313-win_arm64.whl", hash = "sha256:afc622538b430aa4c8c853f7f63bc582b3b8030fd8c80b70fb5fa5b834e575c2", size = 1232140, upload-time = "2026-03-12T03:40:28.882Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/da/e36e27c9cebc1311b7579210df6f1c86e50f2d7143ae4fcf8a5017dc8809/black-26.3.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:2d6bfaf7fd0993b420bed691f20f9492d53ce9a2bcccea4b797d34e947318a78", size = 1889234, upload-time = "2026-03-12T03:40:30.964Z" },
+    { url = "https://files.pythonhosted.org/packages/0e/7b/9871acf393f64a5fa33668c19350ca87177b181f44bb3d0c33b2d534f22c/black-26.3.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:f89f2ab047c76a9c03f78d0d66ca519e389519902fa27e7a91117ef7611c0568", size = 1720522, upload-time = "2026-03-12T03:40:32.346Z" },
+    { url = "https://files.pythonhosted.org/packages/03/87/e766c7f2e90c07fb7586cc787c9ae6462b1eedab390191f2b7fc7f6170a9/black-26.3.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b07fc0dab849d24a80a29cfab8d8a19187d1c4685d8a5e6385a5ce323c1f015f", size = 1787824, upload-time = "2026-03-12T03:40:33.636Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/94/2424338fb2d1875e9e83eed4c8e9c67f6905ec25afd826a911aea2b02535/black-26.3.1-cp314-cp314-win_amd64.whl", hash = "sha256:0126ae5b7c09957da2bdbd91a9ba1207453feada9e9fe51992848658c6c8e01c", size = 1445855, upload-time = "2026-03-12T03:40:35.442Z" },
+    { url = "https://files.pythonhosted.org/packages/86/43/0c3338bd928afb8ee7471f1a4eec3bdbe2245ccb4a646092a222e8669840/black-26.3.1-cp314-cp314-win_arm64.whl", hash = "sha256:92c0ec1f2cc149551a2b7b47efc32c866406b6891b0ee4625e95967c8f4acfb1", size = 1258109, upload-time = "2026-03-12T03:40:36.832Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/0d/52d98722666d6fc6c3dd4c76df339501d6efd40e0ff95e6186a7b7f0befd/black-26.3.1-py3-none-any.whl", hash = "sha256:2bd5aa94fc267d38bb21a70d7410a89f1a1d318841855f698746f8e7f51acd1b", size = 207542, upload-time = "2026-03-12T03:36:01.668Z" },
+]
+
+[[package]]
+name = "burner-redis"
+version = "0.1.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c8/6f/ec3eeb9e3e9d7fedc51fcb56dd09da0f164495ab6fdf4caaa3754ceed659/burner_redis-0.1.6.tar.gz", hash = "sha256:362091d98c09953ef99be8bd026d75fad42599a0f153211e1a22d3e3029c7cfb", size = 843118, upload-time = "2026-04-27T17:11:41.879Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d6/cc/061897380b88c637e4bea1f6715ffba851d10b16d6610f2832ab61fa15b5/burner_redis-0.1.6-cp310-abi3-macosx_10_12_x86_64.whl", hash = "sha256:5dc9c170b9994b8d57958041857f240d1b0b9ac1559d0d35473f03fb62386dea", size = 1275400, upload-time = "2026-04-27T17:11:27.07Z" },
+    { url = "https://files.pythonhosted.org/packages/db/24/e4c6fb37d059b268c2a26b173d3f84b49547e837340983d3d018c08191c6/burner_redis-0.1.6-cp310-abi3-macosx_11_0_arm64.whl", hash = "sha256:f29caae7f80fea2e47350df24264a049aeaa934454210cddcadc2336ee8b423a", size = 1223570, upload-time = "2026-04-27T17:11:28.782Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/be/718af7f42bbebbfbfd771ba43697526c922dff54d1b0d62654e21418b25e/burner_redis-0.1.6-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d0ce82edea4ed1ec34448a8610c62665517b3d2030254f31af32828b070a92a8", size = 1325624, upload-time = "2026-04-27T17:11:30.648Z" },
+    { url = "https://files.pythonhosted.org/packages/06/8a/4f72de7f967532d3739caa461625dc9122f0ca0d46faa883c153a10d0117/burner_redis-0.1.6-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1e3dff7d691ab0035468c17f51632e452b075065a30e026278ed1b297441ce93", size = 1356531, upload-time = "2026-04-27T17:11:32.201Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/22/369338d6372abd12dee51965566428c06f3badd95f668ff1c11680b99b30/burner_redis-0.1.6-cp310-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:3b43f983b6e8fbc208734f04b0bae8cf95323fc43105f977d20f0993fc28c1b3", size = 1526049, upload-time = "2026-04-27T17:11:33.93Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/23/0651cf86bc5ed390fef09e30ff4a4664cc3c5b88ddf4c6b8d905acc0d60e/burner_redis-0.1.6-cp310-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:5b6ba097d910effff00a4610160a4a759503ad590e2c47a580bdcdac9a325823", size = 1579068, upload-time = "2026-04-27T17:11:35.964Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/8c/302638fdad4476d4760d477b0f3c6b96c0f88d3f278e5f14d06eb048f788/burner_redis-0.1.6-cp310-abi3-win_amd64.whl", hash = "sha256:98c6b6fc397617cd5a6778ac020e4ed9985c393ad204f9f5cf524b68ae16070b", size = 1103735, upload-time = "2026-04-27T17:11:38.38Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/ba/18668d92e18210150f7f93e2930264ad77a82e4d3e5f74ca1aecc002f78f/burner_redis-0.1.6-cp310-abi3-win_arm64.whl", hash = "sha256:c2583e98f9a3836ac2c6243ea0c8d56b40e7017b46617991e329bc807c544bad", size = 1029386, upload-time = "2026-04-27T17:11:40.266Z" },
+]
+
+[[package]]
+name = "cachetools"
+version = "7.0.5"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/af/dd/57fe3fdb6e65b25a5987fd2cdc7e22db0aef508b91634d2e57d22928d41b/cachetools-7.0.5.tar.gz", hash = "sha256:0cd042c24377200c1dcd225f8b7b12b0ca53cc2c961b43757e774ebe190fd990", size = 37367, upload-time = "2026-03-09T20:51:29.451Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/06/f3/39cf3367b8107baa44f861dc802cbf16263c945b62d8265d36034fc07bea/cachetools-7.0.5-py3-none-any.whl", hash = "sha256:46bc8ebefbe485407621d0a4264b23c080cedd913921bad7ac3ed2f26c183114", size = 13918, upload-time = "2026-03-09T20:51:27.33Z" },
+]
+
+[[package]]
+name = "caio"
+version = "0.9.25"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/92/88/b8527e1b00c1811db339a1df8bd1ae49d146fcea9d6a5c40e3a80aaeb38d/caio-0.9.25.tar.gz", hash = "sha256:16498e7f81d1d0f5a4c0ad3f2540e65fe25691376e0a5bd367f558067113ed10", size = 26781, upload-time = "2025-12-26T15:21:36.501Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/6a/80/ea4ead0c5d52a9828692e7df20f0eafe8d26e671ce4883a0a146bb91049e/caio-0.9.25-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:ca6c8ecda611478b6016cb94d23fd3eb7124852b985bdec7ecaad9f3116b9619", size = 36836, upload-time = "2025-12-26T15:22:04.662Z" },
+    { url = "https://files.pythonhosted.org/packages/17/b9/36715c97c873649d1029001578f901b50250916295e3dddf20c865438865/caio-0.9.25-cp310-cp310-manylinux2010_x86_64.manylinux2014_x86_64.manylinux_2_12_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:db9b5681e4af8176159f0d6598e73b2279bb661e718c7ac23342c550bd78c241", size = 79695, upload-time = "2025-12-26T15:22:18.818Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/ab/07080ecb1adb55a02cbd8ec0126aa8e43af343ffabb6a71125b42670e9a1/caio-0.9.25-cp310-cp310-manylinux_2_34_aarch64.whl", hash = "sha256:bf61d7d0c4fd10ffdd98ca47f7e8db4d7408e74649ffaf4bef40b029ada3c21b", size = 79457, upload-time = "2026-03-04T22:08:16.024Z" },
+    { url = "https://files.pythonhosted.org/packages/88/95/dd55757bb671eb4c376e006c04e83beb413486821f517792ea603ef216e9/caio-0.9.25-cp310-cp310-manylinux_2_34_x86_64.whl", hash = "sha256:ab52e5b643f8bbd64a0605d9412796cd3464cb8ca88593b13e95a0f0b10508ae", size = 77705, upload-time = "2026-03-04T22:08:17.202Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/90/543f556fcfcfa270713eef906b6352ab048e1e557afec12925c991dc93c2/caio-0.9.25-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:d6956d9e4a27021c8bd6c9677f3a59eb1d820cc32d0343cea7961a03b1371965", size = 36839, upload-time = "2025-12-26T15:21:40.267Z" },
+    { url = "https://files.pythonhosted.org/packages/51/3b/36f3e8ec38dafe8de4831decd2e44c69303d2a3892d16ceda42afed44e1b/caio-0.9.25-cp311-cp311-manylinux2010_x86_64.manylinux2014_x86_64.manylinux_2_12_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:bf84bfa039f25ad91f4f52944452a5f6f405e8afab4d445450978cd6241d1478", size = 80255, upload-time = "2025-12-26T15:22:20.271Z" },
+    { url = "https://files.pythonhosted.org/packages/df/ce/65e64867d928e6aff1b4f0e12dba0ef6d5bf412c240dc1df9d421ac10573/caio-0.9.25-cp311-cp311-manylinux_2_34_aarch64.whl", hash = "sha256:ae3d62587332bce600f861a8de6256b1014d6485cfd25d68c15caf1611dd1f7c", size = 80052, upload-time = "2026-03-04T22:08:20.402Z" },
+    { url = "https://files.pythonhosted.org/packages/46/90/e278863c47e14ec58309aa2e38a45882fbe67b4cc29ec9bc8f65852d3e45/caio-0.9.25-cp311-cp311-manylinux_2_34_x86_64.whl", hash = "sha256:fc220b8533dcf0f238a6b1a4a937f92024c71e7b10b5a2dfc1c73604a25709bc", size = 78273, upload-time = "2026-03-04T22:08:21.368Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/25/79c98ebe12df31548ba4eaf44db11b7cad6b3e7b4203718335620939083c/caio-0.9.25-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:fb7ff95af4c31ad3f03179149aab61097a71fd85e05f89b4786de0359dffd044", size = 36983, upload-time = "2025-12-26T15:21:36.075Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/2b/21288691f16d479945968a0a4f2856818c1c5be56881d51d4dac9b255d26/caio-0.9.25-cp312-cp312-manylinux2010_x86_64.manylinux2014_x86_64.manylinux_2_12_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:97084e4e30dfa598449d874c4d8e0c8d5ea17d2f752ef5e48e150ff9d240cd64", size = 82012, upload-time = "2025-12-26T15:22:20.983Z" },
+    { url = "https://files.pythonhosted.org/packages/03/c4/8a1b580875303500a9c12b9e0af58cb82e47f5bcf888c2457742a138273c/caio-0.9.25-cp312-cp312-manylinux_2_34_aarch64.whl", hash = "sha256:4fa69eba47e0f041b9d4f336e2ad40740681c43e686b18b191b6c5f4c5544bfb", size = 81502, upload-time = "2026-03-04T22:08:22.381Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/1c/0fe770b8ffc8362c48134d1592d653a81a3d8748d764bec33864db36319d/caio-0.9.25-cp312-cp312-manylinux_2_34_x86_64.whl", hash = "sha256:6bebf6f079f1341d19f7386db9b8b1f07e8cc15ae13bfdaff573371ba0575d69", size = 80200, upload-time = "2026-03-04T22:08:23.382Z" },
+    { url = "https://files.pythonhosted.org/packages/31/57/5e6ff127e6f62c9f15d989560435c642144aa4210882f9494204bc892305/caio-0.9.25-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:d6c2a3411af97762a2b03840c3cec2f7f728921ff8adda53d7ea2315a8563451", size = 36979, upload-time = "2025-12-26T15:21:35.484Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/9f/f21af50e72117eb528c422d4276cbac11fb941b1b812b182e0a9c70d19c5/caio-0.9.25-cp313-cp313-manylinux2010_x86_64.manylinux2014_x86_64.manylinux_2_12_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:0998210a4d5cd5cb565b32ccfe4e53d67303f868a76f212e002a8554692870e6", size = 81900, upload-time = "2025-12-26T15:22:21.919Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/12/c39ae2a4037cb10ad5eb3578eb4d5f8c1a2575c62bba675f3406b7ef0824/caio-0.9.25-cp313-cp313-manylinux_2_34_aarch64.whl", hash = "sha256:1a177d4777141b96f175fe2c37a3d96dec7911ed9ad5f02bac38aaa1c936611f", size = 81523, upload-time = "2026-03-04T22:08:25.187Z" },
+    { url = "https://files.pythonhosted.org/packages/22/59/f8f2e950eb4f1a5a3883e198dca514b9d475415cb6cd7b78b9213a0dd45a/caio-0.9.25-cp313-cp313-manylinux_2_34_x86_64.whl", hash = "sha256:9ed3cfb28c0e99fec5e208c934e5c157d0866aa9c32aa4dc5e9b6034af6286b7", size = 80243, upload-time = "2026-03-04T22:08:26.449Z" },
+    { url = "https://files.pythonhosted.org/packages/69/ca/a08fdc7efdcc24e6a6131a93c85be1f204d41c58f474c42b0670af8c016b/caio-0.9.25-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:fab6078b9348e883c80a5e14b382e6ad6aabbc4429ca034e76e730cf464269db", size = 36978, upload-time = "2025-12-26T15:21:41.055Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/6c/d4d24f65e690213c097174d26eda6831f45f4734d9d036d81790a27e7b78/caio-0.9.25-cp314-cp314-manylinux2010_x86_64.manylinux2014_x86_64.manylinux_2_12_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:44a6b58e52d488c75cfaa5ecaa404b2b41cc965e6c417e03251e868ecd5b6d77", size = 81832, upload-time = "2025-12-26T15:22:22.757Z" },
+    { url = "https://files.pythonhosted.org/packages/87/a4/e534cf7d2d0e8d880e25dd61e8d921ffcfe15bd696734589826f5a2df727/caio-0.9.25-cp314-cp314-manylinux_2_34_aarch64.whl", hash = "sha256:628a630eb7fb22381dd8e3c8ab7f59e854b9c806639811fc3f4310c6bd711d79", size = 81565, upload-time = "2026-03-04T22:08:27.483Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/ed/bf81aeac1d290017e5e5ac3e880fd56ee15e50a6d0353986799d1bc5cfd5/caio-0.9.25-cp314-cp314-manylinux_2_34_x86_64.whl", hash = "sha256:0ba16aa605ccb174665357fc729cf500679c2d94d5f1458a6f0d5ca48f2060a7", size = 80071, upload-time = "2026-03-04T22:08:28.751Z" },
+    { url = "https://files.pythonhosted.org/packages/86/93/1f76c8d1bafe3b0614e06b2195784a3765bbf7b0a067661af9e2dd47fc33/caio-0.9.25-py3-none-any.whl", hash = "sha256:06c0bb02d6b929119b1cfbe1ca403c768b2013a369e2db46bfa2a5761cf82e40", size = 19087, upload-time = "2025-12-26T15:22:00.221Z" },
+]
+
+[[package]]
+name = "certifi"
+version = "2026.2.25"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/af/2d/7bf41579a8986e348fa033a31cdd0e4121114f6bce2457e8876010b092dd/certifi-2026.2.25.tar.gz", hash = "sha256:e887ab5cee78ea814d3472169153c2d12cd43b14bd03329a39a9c6e2e80bfba7", size = 155029, upload-time = "2026-02-25T02:54:17.342Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9a/3c/c17fb3ca2d9c3acff52e30b309f538586f9f5b9c9cf454f3845fc9af4881/certifi-2026.2.25-py3-none-any.whl", hash = "sha256:027692e4402ad994f1c42e52a4997a9763c646b73e4096e4d5d6db8af1d6f0fa", size = 153684, upload-time = "2026-02-25T02:54:15.766Z" },
+]
+
+[[package]]
+name = "cffi"
+version = "2.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pycparser", marker = "implementation_name != 'PyPy'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/eb/56/b1ba7935a17738ae8453301356628e8147c79dbb825bcbc73dc7401f9846/cffi-2.0.0.tar.gz", hash = "sha256:44d1b5909021139fe36001ae048dbdde8214afa20200eda0f64c068cac5d5529", size = 523588, upload-time = "2025-09-08T23:24:04.541Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/93/d7/516d984057745a6cd96575eea814fe1edd6646ee6efd552fb7b0921dec83/cffi-2.0.0-cp310-cp310-macosx_10_13_x86_64.whl", hash = "sha256:0cf2d91ecc3fcc0625c2c530fe004f82c110405f101548512cce44322fa8ac44", size = 184283, upload-time = "2025-09-08T23:22:08.01Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/84/ad6a0b408daa859246f57c03efd28e5dd1b33c21737c2db84cae8c237aa5/cffi-2.0.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:f73b96c41e3b2adedc34a7356e64c8eb96e03a3782b535e043a986276ce12a49", size = 180504, upload-time = "2025-09-08T23:22:10.637Z" },
+    { url = "https://files.pythonhosted.org/packages/50/bd/b1a6362b80628111e6653c961f987faa55262b4002fcec42308cad1db680/cffi-2.0.0-cp310-cp310-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:53f77cbe57044e88bbd5ed26ac1d0514d2acf0591dd6bb02a3ae37f76811b80c", size = 208811, upload-time = "2025-09-08T23:22:12.267Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/27/6933a8b2562d7bd1fb595074cf99cc81fc3789f6a6c05cdabb46284a3188/cffi-2.0.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:3e837e369566884707ddaf85fc1744b47575005c0a229de3327f8f9a20f4efeb", size = 216402, upload-time = "2025-09-08T23:22:13.455Z" },
+    { url = "https://files.pythonhosted.org/packages/05/eb/b86f2a2645b62adcfff53b0dd97e8dfafb5c8aa864bd0d9a2c2049a0d551/cffi-2.0.0-cp310-cp310-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:5eda85d6d1879e692d546a078b44251cdd08dd1cfb98dfb77b670c97cee49ea0", size = 203217, upload-time = "2025-09-08T23:22:14.596Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/e0/6cbe77a53acf5acc7c08cc186c9928864bd7c005f9efd0d126884858a5fe/cffi-2.0.0-cp310-cp310-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:9332088d75dc3241c702d852d4671613136d90fa6881da7d770a483fd05248b4", size = 203079, upload-time = "2025-09-08T23:22:15.769Z" },
+    { url = "https://files.pythonhosted.org/packages/98/29/9b366e70e243eb3d14a5cb488dfd3a0b6b2f1fb001a203f653b93ccfac88/cffi-2.0.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:fc7de24befaeae77ba923797c7c87834c73648a05a4bde34b3b7e5588973a453", size = 216475, upload-time = "2025-09-08T23:22:17.427Z" },
+    { url = "https://files.pythonhosted.org/packages/21/7a/13b24e70d2f90a322f2900c5d8e1f14fa7e2a6b3332b7309ba7b2ba51a5a/cffi-2.0.0-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:cf364028c016c03078a23b503f02058f1814320a56ad535686f90565636a9495", size = 218829, upload-time = "2025-09-08T23:22:19.069Z" },
+    { url = "https://files.pythonhosted.org/packages/60/99/c9dc110974c59cc981b1f5b66e1d8af8af764e00f0293266824d9c4254bc/cffi-2.0.0-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:e11e82b744887154b182fd3e7e8512418446501191994dbf9c9fc1f32cc8efd5", size = 211211, upload-time = "2025-09-08T23:22:20.588Z" },
+    { url = "https://files.pythonhosted.org/packages/49/72/ff2d12dbf21aca1b32a40ed792ee6b40f6dc3a9cf1644bd7ef6e95e0ac5e/cffi-2.0.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:8ea985900c5c95ce9db1745f7933eeef5d314f0565b27625d9a10ec9881e1bfb", size = 218036, upload-time = "2025-09-08T23:22:22.143Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/cc/027d7fb82e58c48ea717149b03bcadcbdc293553edb283af792bd4bcbb3f/cffi-2.0.0-cp310-cp310-win32.whl", hash = "sha256:1f72fb8906754ac8a2cc3f9f5aaa298070652a0ffae577e0ea9bd480dc3c931a", size = 172184, upload-time = "2025-09-08T23:22:23.328Z" },
+    { url = "https://files.pythonhosted.org/packages/33/fa/072dd15ae27fbb4e06b437eb6e944e75b068deb09e2a2826039e49ee2045/cffi-2.0.0-cp310-cp310-win_amd64.whl", hash = "sha256:b18a3ed7d5b3bd8d9ef7a8cb226502c6bf8308df1525e1cc676c3680e7176739", size = 182790, upload-time = "2025-09-08T23:22:24.752Z" },
+    { url = "https://files.pythonhosted.org/packages/12/4a/3dfd5f7850cbf0d06dc84ba9aa00db766b52ca38d8b86e3a38314d52498c/cffi-2.0.0-cp311-cp311-macosx_10_13_x86_64.whl", hash = "sha256:b4c854ef3adc177950a8dfc81a86f5115d2abd545751a304c5bcf2c2c7283cfe", size = 184344, upload-time = "2025-09-08T23:22:26.456Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/8b/f0e4c441227ba756aafbe78f117485b25bb26b1c059d01f137fa6d14896b/cffi-2.0.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:2de9a304e27f7596cd03d16f1b7c72219bd944e99cc52b84d0145aefb07cbd3c", size = 180560, upload-time = "2025-09-08T23:22:28.197Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/b7/1200d354378ef52ec227395d95c2576330fd22a869f7a70e88e1447eb234/cffi-2.0.0-cp311-cp311-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:baf5215e0ab74c16e2dd324e8ec067ef59e41125d3eade2b863d294fd5035c92", size = 209613, upload-time = "2025-09-08T23:22:29.475Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/56/6033f5e86e8cc9bb629f0077ba71679508bdf54a9a5e112a3c0b91870332/cffi-2.0.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:730cacb21e1bdff3ce90babf007d0a0917cc3e6492f336c2f0134101e0944f93", size = 216476, upload-time = "2025-09-08T23:22:31.063Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/7f/55fecd70f7ece178db2f26128ec41430d8720f2d12ca97bf8f0a628207d5/cffi-2.0.0-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:6824f87845e3396029f3820c206e459ccc91760e8fa24422f8b0c3d1731cbec5", size = 203374, upload-time = "2025-09-08T23:22:32.507Z" },
+    { url = "https://files.pythonhosted.org/packages/84/ef/a7b77c8bdc0f77adc3b46888f1ad54be8f3b7821697a7b89126e829e676a/cffi-2.0.0-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:9de40a7b0323d889cf8d23d1ef214f565ab154443c42737dfe52ff82cf857664", size = 202597, upload-time = "2025-09-08T23:22:34.132Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/91/500d892b2bf36529a75b77958edfcd5ad8e2ce4064ce2ecfeab2125d72d1/cffi-2.0.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:8941aaadaf67246224cee8c3803777eed332a19d909b47e29c9842ef1e79ac26", size = 215574, upload-time = "2025-09-08T23:22:35.443Z" },
+    { url = "https://files.pythonhosted.org/packages/44/64/58f6255b62b101093d5df22dcb752596066c7e89dd725e0afaed242a61be/cffi-2.0.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:a05d0c237b3349096d3981b727493e22147f934b20f6f125a3eba8f994bec4a9", size = 218971, upload-time = "2025-09-08T23:22:36.805Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/49/fa72cebe2fd8a55fbe14956f9970fe8eb1ac59e5df042f603ef7c8ba0adc/cffi-2.0.0-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:94698a9c5f91f9d138526b48fe26a199609544591f859c870d477351dc7b2414", size = 211972, upload-time = "2025-09-08T23:22:38.436Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/28/dd0967a76aab36731b6ebfe64dec4e981aff7e0608f60c2d46b46982607d/cffi-2.0.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:5fed36fccc0612a53f1d4d9a816b50a36702c28a2aa880cb8a122b3466638743", size = 217078, upload-time = "2025-09-08T23:22:39.776Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/c0/015b25184413d7ab0a410775fdb4a50fca20f5589b5dab1dbbfa3baad8ce/cffi-2.0.0-cp311-cp311-win32.whl", hash = "sha256:c649e3a33450ec82378822b3dad03cc228b8f5963c0c12fc3b1e0ab940f768a5", size = 172076, upload-time = "2025-09-08T23:22:40.95Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/8f/dc5531155e7070361eb1b7e4c1a9d896d0cb21c49f807a6c03fd63fc877e/cffi-2.0.0-cp311-cp311-win_amd64.whl", hash = "sha256:66f011380d0e49ed280c789fbd08ff0d40968ee7b665575489afa95c98196ab5", size = 182820, upload-time = "2025-09-08T23:22:42.463Z" },
+    { url = "https://files.pythonhosted.org/packages/95/5c/1b493356429f9aecfd56bc171285a4c4ac8697f76e9bbbbb105e537853a1/cffi-2.0.0-cp311-cp311-win_arm64.whl", hash = "sha256:c6638687455baf640e37344fe26d37c404db8b80d037c3d29f58fe8d1c3b194d", size = 177635, upload-time = "2025-09-08T23:22:43.623Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/47/4f61023ea636104d4f16ab488e268b93008c3d0bb76893b1b31db1f96802/cffi-2.0.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:6d02d6655b0e54f54c4ef0b94eb6be0607b70853c45ce98bd278dc7de718be5d", size = 185271, upload-time = "2025-09-08T23:22:44.795Z" },
+    { url = "https://files.pythonhosted.org/packages/df/a2/781b623f57358e360d62cdd7a8c681f074a71d445418a776eef0aadb4ab4/cffi-2.0.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:8eca2a813c1cb7ad4fb74d368c2ffbbb4789d377ee5bb8df98373c2cc0dee76c", size = 181048, upload-time = "2025-09-08T23:22:45.938Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/df/a4f0fbd47331ceeba3d37c2e51e9dfc9722498becbeec2bd8bc856c9538a/cffi-2.0.0-cp312-cp312-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:21d1152871b019407d8ac3985f6775c079416c282e431a4da6afe7aefd2bccbe", size = 212529, upload-time = "2025-09-08T23:22:47.349Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/72/12b5f8d3865bf0f87cf1404d8c374e7487dcf097a1c91c436e72e6badd83/cffi-2.0.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:b21e08af67b8a103c71a250401c78d5e0893beff75e28c53c98f4de42f774062", size = 220097, upload-time = "2025-09-08T23:22:48.677Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/95/7a135d52a50dfa7c882ab0ac17e8dc11cec9d55d2c18dda414c051c5e69e/cffi-2.0.0-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:1e3a615586f05fc4065a8b22b8152f0c1b00cdbc60596d187c2a74f9e3036e4e", size = 207983, upload-time = "2025-09-08T23:22:50.06Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/c8/15cb9ada8895957ea171c62dc78ff3e99159ee7adb13c0123c001a2546c1/cffi-2.0.0-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:81afed14892743bbe14dacb9e36d9e0e504cd204e0b165062c488942b9718037", size = 206519, upload-time = "2025-09-08T23:22:51.364Z" },
+    { url = "https://files.pythonhosted.org/packages/78/2d/7fa73dfa841b5ac06c7b8855cfc18622132e365f5b81d02230333ff26e9e/cffi-2.0.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:3e17ed538242334bf70832644a32a7aae3d83b57567f9fd60a26257e992b79ba", size = 219572, upload-time = "2025-09-08T23:22:52.902Z" },
+    { url = "https://files.pythonhosted.org/packages/07/e0/267e57e387b4ca276b90f0434ff88b2c2241ad72b16d31836adddfd6031b/cffi-2.0.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:3925dd22fa2b7699ed2617149842d2e6adde22b262fcbfada50e3d195e4b3a94", size = 222963, upload-time = "2025-09-08T23:22:54.518Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/75/1f2747525e06f53efbd878f4d03bac5b859cbc11c633d0fb81432d98a795/cffi-2.0.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:2c8f814d84194c9ea681642fd164267891702542f028a15fc97d4674b6206187", size = 221361, upload-time = "2025-09-08T23:22:55.867Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/2b/2b6435f76bfeb6bbf055596976da087377ede68df465419d192acf00c437/cffi-2.0.0-cp312-cp312-win32.whl", hash = "sha256:da902562c3e9c550df360bfa53c035b2f241fed6d9aef119048073680ace4a18", size = 172932, upload-time = "2025-09-08T23:22:57.188Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/ed/13bd4418627013bec4ed6e54283b1959cf6db888048c7cf4b4c3b5b36002/cffi-2.0.0-cp312-cp312-win_amd64.whl", hash = "sha256:da68248800ad6320861f129cd9c1bf96ca849a2771a59e0344e88681905916f5", size = 183557, upload-time = "2025-09-08T23:22:58.351Z" },
+    { url = "https://files.pythonhosted.org/packages/95/31/9f7f93ad2f8eff1dbc1c3656d7ca5bfd8fb52c9d786b4dcf19b2d02217fa/cffi-2.0.0-cp312-cp312-win_arm64.whl", hash = "sha256:4671d9dd5ec934cb9a73e7ee9676f9362aba54f7f34910956b84d727b0d73fb6", size = 177762, upload-time = "2025-09-08T23:22:59.668Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/8d/a0a47a0c9e413a658623d014e91e74a50cdd2c423f7ccfd44086ef767f90/cffi-2.0.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:00bdf7acc5f795150faa6957054fbbca2439db2f775ce831222b66f192f03beb", size = 185230, upload-time = "2025-09-08T23:23:00.879Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/d2/a6c0296814556c68ee32009d9c2ad4f85f2707cdecfd7727951ec228005d/cffi-2.0.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:45d5e886156860dc35862657e1494b9bae8dfa63bf56796f2fb56e1679fc0bca", size = 181043, upload-time = "2025-09-08T23:23:02.231Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/1e/d22cc63332bd59b06481ceaac49d6c507598642e2230f201649058a7e704/cffi-2.0.0-cp313-cp313-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:07b271772c100085dd28b74fa0cd81c8fb1a3ba18b21e03d7c27f3436a10606b", size = 212446, upload-time = "2025-09-08T23:23:03.472Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/f5/a2c23eb03b61a0b8747f211eb716446c826ad66818ddc7810cc2cc19b3f2/cffi-2.0.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:d48a880098c96020b02d5a1f7d9251308510ce8858940e6fa99ece33f610838b", size = 220101, upload-time = "2025-09-08T23:23:04.792Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/7f/e6647792fc5850d634695bc0e6ab4111ae88e89981d35ac269956605feba/cffi-2.0.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:f93fd8e5c8c0a4aa1f424d6173f14a892044054871c771f8566e4008eaa359d2", size = 207948, upload-time = "2025-09-08T23:23:06.127Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/1e/a5a1bd6f1fb30f22573f76533de12a00bf274abcdc55c8edab639078abb6/cffi-2.0.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:dd4f05f54a52fb558f1ba9f528228066954fee3ebe629fc1660d874d040ae5a3", size = 206422, upload-time = "2025-09-08T23:23:07.753Z" },
+    { url = "https://files.pythonhosted.org/packages/98/df/0a1755e750013a2081e863e7cd37e0cdd02664372c754e5560099eb7aa44/cffi-2.0.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:c8d3b5532fc71b7a77c09192b4a5a200ea992702734a2e9279a37f2478236f26", size = 219499, upload-time = "2025-09-08T23:23:09.648Z" },
+    { url = "https://files.pythonhosted.org/packages/50/e1/a969e687fcf9ea58e6e2a928ad5e2dd88cc12f6f0ab477e9971f2309b57c/cffi-2.0.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:d9b29c1f0ae438d5ee9acb31cadee00a58c46cc9c0b2f9038c6b0b3470877a8c", size = 222928, upload-time = "2025-09-08T23:23:10.928Z" },
+    { url = "https://files.pythonhosted.org/packages/36/54/0362578dd2c9e557a28ac77698ed67323ed5b9775ca9d3fe73fe191bb5d8/cffi-2.0.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:6d50360be4546678fc1b79ffe7a66265e28667840010348dd69a314145807a1b", size = 221302, upload-time = "2025-09-08T23:23:12.42Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/6d/bf9bda840d5f1dfdbf0feca87fbdb64a918a69bca42cfa0ba7b137c48cb8/cffi-2.0.0-cp313-cp313-win32.whl", hash = "sha256:74a03b9698e198d47562765773b4a8309919089150a0bb17d829ad7b44b60d27", size = 172909, upload-time = "2025-09-08T23:23:14.32Z" },
+    { url = "https://files.pythonhosted.org/packages/37/18/6519e1ee6f5a1e579e04b9ddb6f1676c17368a7aba48299c3759bbc3c8b3/cffi-2.0.0-cp313-cp313-win_amd64.whl", hash = "sha256:19f705ada2530c1167abacb171925dd886168931e0a7b78f5bffcae5c6b5be75", size = 183402, upload-time = "2025-09-08T23:23:15.535Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/0e/02ceeec9a7d6ee63bb596121c2c8e9b3a9e150936f4fbef6ca1943e6137c/cffi-2.0.0-cp313-cp313-win_arm64.whl", hash = "sha256:256f80b80ca3853f90c21b23ee78cd008713787b1b1e93eae9f3d6a7134abd91", size = 177780, upload-time = "2025-09-08T23:23:16.761Z" },
+    { url = "https://files.pythonhosted.org/packages/92/c4/3ce07396253a83250ee98564f8d7e9789fab8e58858f35d07a9a2c78de9f/cffi-2.0.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:fc33c5141b55ed366cfaad382df24fe7dcbc686de5be719b207bb248e3053dc5", size = 185320, upload-time = "2025-09-08T23:23:18.087Z" },
+    { url = "https://files.pythonhosted.org/packages/59/dd/27e9fa567a23931c838c6b02d0764611c62290062a6d4e8ff7863daf9730/cffi-2.0.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:c654de545946e0db659b3400168c9ad31b5d29593291482c43e3564effbcee13", size = 181487, upload-time = "2025-09-08T23:23:19.622Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/43/0e822876f87ea8a4ef95442c3d766a06a51fc5298823f884ef87aaad168c/cffi-2.0.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:24b6f81f1983e6df8db3adc38562c83f7d4a0c36162885ec7f7b77c7dcbec97b", size = 220049, upload-time = "2025-09-08T23:23:20.853Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/89/76799151d9c2d2d1ead63c2429da9ea9d7aac304603de0c6e8764e6e8e70/cffi-2.0.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:12873ca6cb9b0f0d3a0da705d6086fe911591737a59f28b7936bdfed27c0d47c", size = 207793, upload-time = "2025-09-08T23:23:22.08Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/dd/3465b14bb9e24ee24cb88c9e3730f6de63111fffe513492bf8c808a3547e/cffi-2.0.0-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:d9b97165e8aed9272a6bb17c01e3cc5871a594a446ebedc996e2397a1c1ea8ef", size = 206300, upload-time = "2025-09-08T23:23:23.314Z" },
+    { url = "https://files.pythonhosted.org/packages/47/d9/d83e293854571c877a92da46fdec39158f8d7e68da75bf73581225d28e90/cffi-2.0.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:afb8db5439b81cf9c9d0c80404b60c3cc9c3add93e114dcae767f1477cb53775", size = 219244, upload-time = "2025-09-08T23:23:24.541Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/0f/1f177e3683aead2bb00f7679a16451d302c436b5cbf2505f0ea8146ef59e/cffi-2.0.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:737fe7d37e1a1bffe70bd5754ea763a62a066dc5913ca57e957824b72a85e205", size = 222828, upload-time = "2025-09-08T23:23:26.143Z" },
+    { url = "https://files.pythonhosted.org/packages/c6/0f/cafacebd4b040e3119dcb32fed8bdef8dfe94da653155f9d0b9dc660166e/cffi-2.0.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:38100abb9d1b1435bc4cc340bb4489635dc2f0da7456590877030c9b3d40b0c1", size = 220926, upload-time = "2025-09-08T23:23:27.873Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/aa/df335faa45b395396fcbc03de2dfcab242cd61a9900e914fe682a59170b1/cffi-2.0.0-cp314-cp314-win32.whl", hash = "sha256:087067fa8953339c723661eda6b54bc98c5625757ea62e95eb4898ad5e776e9f", size = 175328, upload-time = "2025-09-08T23:23:44.61Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/92/882c2d30831744296ce713f0feb4c1cd30f346ef747b530b5318715cc367/cffi-2.0.0-cp314-cp314-win_amd64.whl", hash = "sha256:203a48d1fb583fc7d78a4c6655692963b860a417c0528492a6bc21f1aaefab25", size = 185650, upload-time = "2025-09-08T23:23:45.848Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/2c/98ece204b9d35a7366b5b2c6539c350313ca13932143e79dc133ba757104/cffi-2.0.0-cp314-cp314-win_arm64.whl", hash = "sha256:dbd5c7a25a7cb98f5ca55d258b103a2054f859a46ae11aaf23134f9cc0d356ad", size = 180687, upload-time = "2025-09-08T23:23:47.105Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/61/c768e4d548bfa607abcda77423448df8c471f25dbe64fb2ef6d555eae006/cffi-2.0.0-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:9a67fc9e8eb39039280526379fb3a70023d77caec1852002b4da7e8b270c4dd9", size = 188773, upload-time = "2025-09-08T23:23:29.347Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/ea/5f76bce7cf6fcd0ab1a1058b5af899bfbef198bea4d5686da88471ea0336/cffi-2.0.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:7a66c7204d8869299919db4d5069a82f1561581af12b11b3c9f48c584eb8743d", size = 185013, upload-time = "2025-09-08T23:23:30.63Z" },
+    { url = "https://files.pythonhosted.org/packages/be/b4/c56878d0d1755cf9caa54ba71e5d049479c52f9e4afc230f06822162ab2f/cffi-2.0.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:7cc09976e8b56f8cebd752f7113ad07752461f48a58cbba644139015ac24954c", size = 221593, upload-time = "2025-09-08T23:23:31.91Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/0d/eb704606dfe8033e7128df5e90fee946bbcb64a04fcdaa97321309004000/cffi-2.0.0-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:92b68146a71df78564e4ef48af17551a5ddd142e5190cdf2c5624d0c3ff5b2e8", size = 209354, upload-time = "2025-09-08T23:23:33.214Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/19/3c435d727b368ca475fb8742ab97c9cb13a0de600ce86f62eab7fa3eea60/cffi-2.0.0-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:b1e74d11748e7e98e2f426ab176d4ed720a64412b6a15054378afdb71e0f37dc", size = 208480, upload-time = "2025-09-08T23:23:34.495Z" },
+    { url = "https://files.pythonhosted.org/packages/d0/44/681604464ed9541673e486521497406fadcc15b5217c3e326b061696899a/cffi-2.0.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:28a3a209b96630bca57cce802da70c266eb08c6e97e5afd61a75611ee6c64592", size = 221584, upload-time = "2025-09-08T23:23:36.096Z" },
+    { url = "https://files.pythonhosted.org/packages/25/8e/342a504ff018a2825d395d44d63a767dd8ebc927ebda557fecdaca3ac33a/cffi-2.0.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:7553fb2090d71822f02c629afe6042c299edf91ba1bf94951165613553984512", size = 224443, upload-time = "2025-09-08T23:23:37.328Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/5e/b666bacbbc60fbf415ba9988324a132c9a7a0448a9a8f125074671c0f2c3/cffi-2.0.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:6c6c373cfc5c83a975506110d17457138c8c63016b563cc9ed6e056a82f13ce4", size = 223437, upload-time = "2025-09-08T23:23:38.945Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/1d/ec1a60bd1a10daa292d3cd6bb0b359a81607154fb8165f3ec95fe003b85c/cffi-2.0.0-cp314-cp314t-win32.whl", hash = "sha256:1fc9ea04857caf665289b7a75923f2c6ed559b8298a1b8c49e59f7dd95c8481e", size = 180487, upload-time = "2025-09-08T23:23:40.423Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/41/4c1168c74fac325c0c8156f04b6749c8b6a8f405bbf91413ba088359f60d/cffi-2.0.0-cp314-cp314t-win_amd64.whl", hash = "sha256:d68b6cef7827e8641e8ef16f4494edda8b36104d79773a334beaa1e3521430f6", size = 191726, upload-time = "2025-09-08T23:23:41.742Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/3a/dbeec9d1ee0844c679f6bb5d6ad4e9f198b1224f4e7a32825f47f6192b0c/cffi-2.0.0-cp314-cp314t-win_arm64.whl", hash = "sha256:0a1527a803f0a659de1af2e1fd700213caba79377e27e4693648c2923da066f9", size = 184195, upload-time = "2025-09-08T23:23:43.004Z" },
+]
+
+[[package]]
+name = "charset-normalizer"
+version = "3.4.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7b/60/e3bec1881450851b087e301bedc3daa9377a4d45f1c26aa90b0b235e38aa/charset_normalizer-3.4.6.tar.gz", hash = "sha256:1ae6b62897110aa7c79ea2f5dd38d1abca6db663687c0b1ad9aed6f6bae3d9d6", size = 143363, upload-time = "2026-03-15T18:53:25.478Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e6/8c/2c56124c6dc53a774d435f985b5973bc592f42d437be58c0c92d65ae7296/charset_normalizer-3.4.6-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:2e1d8ca8611099001949d1cdfaefc510cf0f212484fe7c565f735b68c78c3c95", size = 298751, upload-time = "2026-03-15T18:50:00.003Z" },
+    { url = "https://files.pythonhosted.org/packages/86/2a/2a7db6b314b966a3bcad8c731c0719c60b931b931de7ae9f34b2839289ee/charset_normalizer-3.4.6-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e25369dc110d58ddf29b949377a93e0716d72a24f62bad72b2b39f155949c1fd", size = 200027, upload-time = "2026-03-15T18:50:01.702Z" },
+    { url = "https://files.pythonhosted.org/packages/68/f2/0fe775c74ae25e2a3b07b01538fc162737b3e3f795bada3bc26f4d4d495c/charset_normalizer-3.4.6-cp310-cp310-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:259695e2ccc253feb2a016303543d691825e920917e31f894ca1a687982b1de4", size = 220741, upload-time = "2026-03-15T18:50:03.194Z" },
+    { url = "https://files.pythonhosted.org/packages/10/98/8085596e41f00b27dd6aa1e68413d1ddda7e605f34dd546833c61fddd709/charset_normalizer-3.4.6-cp310-cp310-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:dda86aba335c902b6149a02a55b38e96287157e609200811837678214ba2b1db", size = 215802, upload-time = "2026-03-15T18:50:05.859Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/ce/865e4e09b041bad659d682bbd98b47fb490b8e124f9398c9448065f64fee/charset_normalizer-3.4.6-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:51fb3c322c81d20567019778cb5a4a6f2dc1c200b886bc0d636238e364848c89", size = 207908, upload-time = "2026-03-15T18:50:07.676Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/54/8c757f1f7349262898c2f169e0d562b39dcb977503f18fdf0814e923db78/charset_normalizer-3.4.6-cp310-cp310-manylinux_2_31_armv7l.whl", hash = "sha256:4482481cb0572180b6fd976a4d5c72a30263e98564da68b86ec91f0fe35e8565", size = 194357, upload-time = "2026-03-15T18:50:09.327Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/29/e88f2fac9218907fc7a70722b393d1bbe8334c61fe9c46640dba349b6e66/charset_normalizer-3.4.6-cp310-cp310-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:39f5068d35621da2881271e5c3205125cc456f54e9030d3f723288c873a71bf9", size = 205610, upload-time = "2026-03-15T18:50:10.732Z" },
+    { url = "https://files.pythonhosted.org/packages/4c/c5/21d7bb0cb415287178450171d130bed9d664211fdd59731ed2c34267b07d/charset_normalizer-3.4.6-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:8bea55c4eef25b0b19a0337dc4e3f9a15b00d569c77211fa8cde38684f234fb7", size = 203512, upload-time = "2026-03-15T18:50:12.535Z" },
+    { url = "https://files.pythonhosted.org/packages/a4/be/ce52f3c7fdb35cc987ad38a53ebcef52eec498f4fb6c66ecfe62cfe57ba2/charset_normalizer-3.4.6-cp310-cp310-musllinux_1_2_armv7l.whl", hash = "sha256:f0cdaecd4c953bfae0b6bb64910aaaca5a424ad9c72d85cb88417bb9814f7550", size = 195398, upload-time = "2026-03-15T18:50:14.236Z" },
+    { url = "https://files.pythonhosted.org/packages/81/a0/3ab5dd39d4859a3555e5dadfc8a9fa7f8352f8c183d1a65c90264517da0e/charset_normalizer-3.4.6-cp310-cp310-musllinux_1_2_ppc64le.whl", hash = "sha256:150b8ce8e830eb7ccb029ec9ca36022f756986aaaa7956aad6d9ec90089338c0", size = 221772, upload-time = "2026-03-15T18:50:15.581Z" },
+    { url = "https://files.pythonhosted.org/packages/04/6e/6a4e41a97ba6b2fa87f849c41e4d229449a586be85053c4d90135fe82d26/charset_normalizer-3.4.6-cp310-cp310-musllinux_1_2_riscv64.whl", hash = "sha256:e68c14b04827dd76dcbd1aeea9e604e3e4b78322d8faf2f8132c7138efa340a8", size = 205759, upload-time = "2026-03-15T18:50:17.047Z" },
+    { url = "https://files.pythonhosted.org/packages/db/3b/34a712a5ee64a6957bf355b01dc17b12de457638d436fdb05d01e463cd1c/charset_normalizer-3.4.6-cp310-cp310-musllinux_1_2_s390x.whl", hash = "sha256:3778fd7d7cd04ae8f54651f4a7a0bd6e39a0cf20f801720a4c21d80e9b7ad6b0", size = 216938, upload-time = "2026-03-15T18:50:18.44Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/05/5bd1e12da9ab18790af05c61aafd01a60f489778179b621ac2a305243c62/charset_normalizer-3.4.6-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:dad6e0f2e481fffdcf776d10ebee25e0ef89f16d691f1e5dee4b586375fdc64b", size = 210138, upload-time = "2026-03-15T18:50:19.852Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/8e/3cb9e2d998ff6b21c0a1860343cb7b83eba9cdb66b91410e18fc4969d6ab/charset_normalizer-3.4.6-cp310-cp310-win32.whl", hash = "sha256:74a2e659c7ecbc73562e2a15e05039f1e22c75b7c7618b4b574a3ea9118d1557", size = 144137, upload-time = "2026-03-15T18:50:21.505Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/8f/78f5489ffadb0db3eb7aff53d31c24531d33eb545f0c6f6567c25f49a5ff/charset_normalizer-3.4.6-cp310-cp310-win_amd64.whl", hash = "sha256:aa9cccf4a44b9b62d8ba8b4dd06c649ba683e4bf04eea606d2e94cfc2d6ff4d6", size = 154244, upload-time = "2026-03-15T18:50:22.81Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/74/e472659dffb0cadb2f411282d2d76c60da1fc94076d7fffed4ae8a93ec01/charset_normalizer-3.4.6-cp310-cp310-win_arm64.whl", hash = "sha256:e985a16ff513596f217cee86c21371b8cd011c0f6f056d0920aa2d926c544058", size = 143312, upload-time = "2026-03-15T18:50:24.074Z" },
+    { url = "https://files.pythonhosted.org/packages/62/28/ff6f234e628a2de61c458be2779cb182bc03f6eec12200d4a525bbfc9741/charset_normalizer-3.4.6-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:82060f995ab5003a2d6e0f4ad29065b7672b6593c8c63559beefe5b443242c3e", size = 293582, upload-time = "2026-03-15T18:50:25.454Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/b7/b1a117e5385cbdb3205f6055403c2a2a220c5ea80b8716c324eaf75c5c95/charset_normalizer-3.4.6-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:60c74963d8350241a79cb8feea80e54d518f72c26db618862a8f53e5023deaf9", size = 197240, upload-time = "2026-03-15T18:50:27.196Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/5f/2574f0f09f3c3bc1b2f992e20bce6546cb1f17e111c5be07308dc5427956/charset_normalizer-3.4.6-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f6e4333fb15c83f7d1482a76d45a0818897b3d33f00efd215528ff7c51b8e35d", size = 217363, upload-time = "2026-03-15T18:50:28.601Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/d1/0ae20ad77bc949ddd39b51bf383b6ca932f2916074c95cad34ae465ab71f/charset_normalizer-3.4.6-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:bc72863f4d9aba2e8fd9085e63548a324ba706d2ea2c83b260da08a59b9482de", size = 212994, upload-time = "2026-03-15T18:50:30.102Z" },
+    { url = "https://files.pythonhosted.org/packages/60/ac/3233d262a310c1b12633536a07cde5ddd16985e6e7e238e9f3f9423d8eb9/charset_normalizer-3.4.6-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9cc4fc6c196d6a8b76629a70ddfcd4635a6898756e2d9cac5565cf0654605d73", size = 204697, upload-time = "2026-03-15T18:50:31.654Z" },
+    { url = "https://files.pythonhosted.org/packages/25/3c/8a18fc411f085b82303cfb7154eed5bd49c77035eb7608d049468b53f87c/charset_normalizer-3.4.6-cp311-cp311-manylinux_2_31_armv7l.whl", hash = "sha256:0c173ce3a681f309f31b87125fecec7a5d1347261ea11ebbb856fa6006b23c8c", size = 191673, upload-time = "2026-03-15T18:50:33.433Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/a7/11cfe61d6c5c5c7438d6ba40919d0306ed83c9ab957f3d4da2277ff67836/charset_normalizer-3.4.6-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:c907cdc8109f6c619e6254212e794d6548373cc40e1ec75e6e3823d9135d29cc", size = 201120, upload-time = "2026-03-15T18:50:35.105Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/10/cf491fa1abd47c02f69687046b896c950b92b6cd7337a27e6548adbec8e4/charset_normalizer-3.4.6-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:404a1e552cf5b675a87f0651f8b79f5f1e6fd100ee88dc612f89aa16abd4486f", size = 200911, upload-time = "2026-03-15T18:50:36.819Z" },
+    { url = "https://files.pythonhosted.org/packages/28/70/039796160b48b18ed466fde0af84c1b090c4e288fae26cd674ad04a2d703/charset_normalizer-3.4.6-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:e3c701e954abf6fc03a49f7c579cc80c2c6cc52525340ca3186c41d3f33482ef", size = 192516, upload-time = "2026-03-15T18:50:38.228Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/34/c56f3223393d6ff3124b9e78f7de738047c2d6bc40a4f16ac0c9d7a1cb3c/charset_normalizer-3.4.6-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:7a6967aaf043bceabab5412ed6bd6bd26603dae84d5cb75bf8d9a74a4959d398", size = 218795, upload-time = "2026-03-15T18:50:39.664Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/3b/ce2d4f86c5282191a041fdc5a4ce18f1c6bd40a5bd1f74cf8625f08d51c1/charset_normalizer-3.4.6-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:5feb91325bbceade6afab43eb3b508c63ee53579fe896c77137ded51c6b6958e", size = 201833, upload-time = "2026-03-15T18:50:41.552Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/9b/b6a9f76b0fd7c5b5ec58b228ff7e85095370282150f0bd50b3126f5506d6/charset_normalizer-3.4.6-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:f820f24b09e3e779fe84c3c456cb4108a7aa639b0d1f02c28046e11bfcd088ed", size = 213920, upload-time = "2026-03-15T18:50:43.33Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/98/7bc23513a33d8172365ed30ee3a3b3fe1ece14a395e5fc94129541fc6003/charset_normalizer-3.4.6-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:b35b200d6a71b9839a46b9b7fff66b6638bb52fc9658aa58796b0326595d3021", size = 206951, upload-time = "2026-03-15T18:50:44.789Z" },
+    { url = "https://files.pythonhosted.org/packages/32/73/c0b86f3d1458468e11aec870e6b3feac931facbe105a894b552b0e518e79/charset_normalizer-3.4.6-cp311-cp311-win32.whl", hash = "sha256:9ca4c0b502ab399ef89248a2c84c54954f77a070f28e546a85e91da627d1301e", size = 143703, upload-time = "2026-03-15T18:50:46.103Z" },
+    { url = "https://files.pythonhosted.org/packages/c6/e3/76f2facfe8eddee0bbd38d2594e709033338eae44ebf1738bcefe0a06185/charset_normalizer-3.4.6-cp311-cp311-win_amd64.whl", hash = "sha256:a9e68c9d88823b274cf1e72f28cb5dc89c990edf430b0bfd3e2fb0785bfeabf4", size = 153857, upload-time = "2026-03-15T18:50:47.563Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/dc/9abe19c9b27e6cd3636036b9d1b387b78c40dedbf0b47f9366737684b4b0/charset_normalizer-3.4.6-cp311-cp311-win_arm64.whl", hash = "sha256:97d0235baafca5f2b09cf332cc275f021e694e8362c6bb9c96fc9a0eb74fc316", size = 142751, upload-time = "2026-03-15T18:50:49.234Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/62/c0815c992c9545347aeea7859b50dc9044d147e2e7278329c6e02ac9a616/charset_normalizer-3.4.6-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:2ef7fedc7a6ecbe99969cd09632516738a97eeb8bd7258bf8a0f23114c057dab", size = 295154, upload-time = "2026-03-15T18:50:50.88Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/37/bdca6613c2e3c58c7421891d80cc3efa1d32e882f7c4a7ee6039c3fc951a/charset_normalizer-3.4.6-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a4ea868bc28109052790eb2b52a9ab33f3aa7adc02f96673526ff47419490e21", size = 199191, upload-time = "2026-03-15T18:50:52.658Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/92/9934d1bbd69f7f398b38c5dae1cbf9cc672e7c34a4adf7b17c0a9c17d15d/charset_normalizer-3.4.6-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:836ab36280f21fc1a03c99cd05c6b7af70d2697e374c7af0b61ed271401a72a2", size = 218674, upload-time = "2026-03-15T18:50:54.102Z" },
+    { url = "https://files.pythonhosted.org/packages/af/90/25f6ab406659286be929fd89ab0e78e38aa183fc374e03aa3c12d730af8a/charset_normalizer-3.4.6-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:f1ce721c8a7dfec21fcbdfe04e8f68174183cf4e8188e0645e92aa23985c57ff", size = 215259, upload-time = "2026-03-15T18:50:55.616Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/ef/79a463eb0fff7f96afa04c1d4c51f8fc85426f918db467854bfb6a569ce3/charset_normalizer-3.4.6-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0e28d62a8fc7a1fa411c43bd65e346f3bce9716dc51b897fbe930c5987b402d5", size = 207276, upload-time = "2026-03-15T18:50:57.054Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/72/d0426afec4b71dc159fa6b4e68f868cd5a3ecd918fec5813a15d292a7d10/charset_normalizer-3.4.6-cp312-cp312-manylinux_2_31_armv7l.whl", hash = "sha256:530d548084c4a9f7a16ed4a294d459b4f229db50df689bfe92027452452943a0", size = 195161, upload-time = "2026-03-15T18:50:58.686Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/18/c82b06a68bfcb6ce55e508225d210c7e6a4ea122bfc0748892f3dc4e8e11/charset_normalizer-3.4.6-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:30f445ae60aad5e1f8bdbb3108e39f6fbc09f4ea16c815c66578878325f8f15a", size = 203452, upload-time = "2026-03-15T18:51:00.196Z" },
+    { url = "https://files.pythonhosted.org/packages/44/d6/0c25979b92f8adafdbb946160348d8d44aa60ce99afdc27df524379875cb/charset_normalizer-3.4.6-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:ac2393c73378fea4e52aa56285a3d64be50f1a12395afef9cce47772f60334c2", size = 202272, upload-time = "2026-03-15T18:51:01.703Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/3d/7fea3e8fe84136bebbac715dd1221cc25c173c57a699c030ab9b8900cbb7/charset_normalizer-3.4.6-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:90ca27cd8da8118b18a52d5f547859cc1f8354a00cd1e8e5120df3e30d6279e5", size = 195622, upload-time = "2026-03-15T18:51:03.526Z" },
+    { url = "https://files.pythonhosted.org/packages/57/8a/d6f7fd5cb96c58ef2f681424fbca01264461336d2a7fc875e4446b1f1346/charset_normalizer-3.4.6-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:8e5a94886bedca0f9b78fecd6afb6629142fd2605aa70a125d49f4edc6037ee6", size = 220056, upload-time = "2026-03-15T18:51:05.269Z" },
+    { url = "https://files.pythonhosted.org/packages/16/50/478cdda782c8c9c3fb5da3cc72dd7f331f031e7f1363a893cdd6ca0f8de0/charset_normalizer-3.4.6-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:695f5c2823691a25f17bc5d5ffe79fa90972cc34b002ac6c843bb8a1720e950d", size = 203751, upload-time = "2026-03-15T18:51:06.858Z" },
+    { url = "https://files.pythonhosted.org/packages/75/fc/cc2fcac943939c8e4d8791abfa139f685e5150cae9f94b60f12520feaa9b/charset_normalizer-3.4.6-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:231d4da14bcd9301310faf492051bee27df11f2bc7549bc0bb41fef11b82daa2", size = 216563, upload-time = "2026-03-15T18:51:08.564Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/b7/a4add1d9a5f68f3d037261aecca83abdb0ab15960a3591d340e829b37298/charset_normalizer-3.4.6-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:a056d1ad2633548ca18ffa2f85c202cfb48b68615129143915b8dc72a806a923", size = 209265, upload-time = "2026-03-15T18:51:10.312Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/18/c094561b5d64a24277707698e54b7f67bd17a4f857bbfbb1072bba07c8bf/charset_normalizer-3.4.6-cp312-cp312-win32.whl", hash = "sha256:c2274ca724536f173122f36c98ce188fd24ce3dad886ec2b7af859518ce008a4", size = 144229, upload-time = "2026-03-15T18:51:11.694Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/20/0567efb3a8fd481b8f34f739ebddc098ed062a59fed41a8d193a61939e8f/charset_normalizer-3.4.6-cp312-cp312-win_amd64.whl", hash = "sha256:c8ae56368f8cc97c7e40a7ee18e1cedaf8e780cd8bc5ed5ac8b81f238614facb", size = 154277, upload-time = "2026-03-15T18:51:13.004Z" },
+    { url = "https://files.pythonhosted.org/packages/15/57/28d79b44b51933119e21f65479d0864a8d5893e494cf5daab15df0247c17/charset_normalizer-3.4.6-cp312-cp312-win_arm64.whl", hash = "sha256:899d28f422116b08be5118ef350c292b36fc15ec2daeb9ea987c89281c7bb5c4", size = 142817, upload-time = "2026-03-15T18:51:14.408Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/1d/4fdabeef4e231153b6ed7567602f3b68265ec4e5b76d6024cf647d43d981/charset_normalizer-3.4.6-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:11afb56037cbc4b1555a34dd69151e8e069bee82e613a73bef6e714ce733585f", size = 294823, upload-time = "2026-03-15T18:51:15.755Z" },
+    { url = "https://files.pythonhosted.org/packages/47/7b/20e809b89c69d37be748d98e84dce6820bf663cf19cf6b942c951a3e8f41/charset_normalizer-3.4.6-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:423fb7e748a08f854a08a222b983f4df1912b1daedce51a72bd24fe8f26a1843", size = 198527, upload-time = "2026-03-15T18:51:17.177Z" },
+    { url = "https://files.pythonhosted.org/packages/37/a6/4f8d27527d59c039dce6f7622593cdcd3d70a8504d87d09eb11e9fdc6062/charset_normalizer-3.4.6-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:d73beaac5e90173ac3deb9928a74763a6d230f494e4bfb422c217a0ad8e629bf", size = 218388, upload-time = "2026-03-15T18:51:18.934Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/9b/4770ccb3e491a9bacf1c46cc8b812214fe367c86a96353ccc6daf87b01ec/charset_normalizer-3.4.6-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d60377dce4511655582e300dc1e5a5f24ba0cb229005a1d5c8d0cb72bb758ab8", size = 214563, upload-time = "2026-03-15T18:51:20.374Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/58/a199d245894b12db0b957d627516c78e055adc3a0d978bc7f65ddaf7c399/charset_normalizer-3.4.6-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:530e8cebeea0d76bdcf93357aa5e41336f48c3dc709ac52da2bb167c5b8271d9", size = 206587, upload-time = "2026-03-15T18:51:21.807Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/70/3def227f1ec56f5c69dfc8392b8bd63b11a18ca8178d9211d7cc5e5e4f27/charset_normalizer-3.4.6-cp313-cp313-manylinux_2_31_armv7l.whl", hash = "sha256:a26611d9987b230566f24a0a125f17fe0de6a6aff9f25c9f564aaa2721a5fb88", size = 194724, upload-time = "2026-03-15T18:51:23.508Z" },
+    { url = "https://files.pythonhosted.org/packages/58/ab/9318352e220c05efd31c2779a23b50969dc94b985a2efa643ed9077bfca5/charset_normalizer-3.4.6-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:34315ff4fc374b285ad7f4a0bf7dcbfe769e1b104230d40f49f700d4ab6bbd84", size = 202956, upload-time = "2026-03-15T18:51:25.239Z" },
+    { url = "https://files.pythonhosted.org/packages/75/13/f3550a3ac25b70f87ac98c40d3199a8503676c2f1620efbf8d42095cfc40/charset_normalizer-3.4.6-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:5f8ddd609f9e1af8c7bd6e2aca279c931aefecd148a14402d4e368f3171769fd", size = 201923, upload-time = "2026-03-15T18:51:26.682Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/db/c5c643b912740b45e8eec21de1bbab8e7fc085944d37e1e709d3dcd9d72f/charset_normalizer-3.4.6-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:80d0a5615143c0b3225e5e3ef22c8d5d51f3f72ce0ea6fb84c943546c7b25b6c", size = 195366, upload-time = "2026-03-15T18:51:28.129Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/67/3b1c62744f9b2448443e0eb160d8b001c849ec3fef591e012eda6484787c/charset_normalizer-3.4.6-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:92734d4d8d187a354a556626c221cd1a892a4e0802ccb2af432a1d85ec012194", size = 219752, upload-time = "2026-03-15T18:51:29.556Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/98/32ffbaf7f0366ffb0445930b87d103f6b406bc2c271563644bde8a2b1093/charset_normalizer-3.4.6-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:613f19aa6e082cf96e17e3ffd89383343d0d589abda756b7764cf78361fd41dc", size = 203296, upload-time = "2026-03-15T18:51:30.921Z" },
+    { url = "https://files.pythonhosted.org/packages/41/12/5d308c1bbe60cabb0c5ef511574a647067e2a1f631bc8634fcafaccd8293/charset_normalizer-3.4.6-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:2b1a63e8224e401cafe7739f77efd3f9e7f5f2026bda4aead8e59afab537784f", size = 215956, upload-time = "2026-03-15T18:51:32.399Z" },
+    { url = "https://files.pythonhosted.org/packages/53/e9/5f85f6c5e20669dbe56b165c67b0260547dea97dba7e187938833d791687/charset_normalizer-3.4.6-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:6cceb5473417d28edd20c6c984ab6fee6c6267d38d906823ebfe20b03d607dc2", size = 208652, upload-time = "2026-03-15T18:51:34.214Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/11/897052ea6af56df3eef3ca94edafee410ca699ca0c7b87960ad19932c55e/charset_normalizer-3.4.6-cp313-cp313-win32.whl", hash = "sha256:d7de2637729c67d67cf87614b566626057e95c303bc0a55ffe391f5205e7003d", size = 143940, upload-time = "2026-03-15T18:51:36.15Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/5c/724b6b363603e419829f561c854b87ed7c7e31231a7908708ac086cdf3e2/charset_normalizer-3.4.6-cp313-cp313-win_amd64.whl", hash = "sha256:572d7c822caf521f0525ba1bce1a622a0b85cf47ffbdae6c9c19e3b5ac3c4389", size = 154101, upload-time = "2026-03-15T18:51:37.876Z" },
+    { url = "https://files.pythonhosted.org/packages/01/a5/7abf15b4c0968e47020f9ca0935fb3274deb87cb288cd187cad92e8cdffd/charset_normalizer-3.4.6-cp313-cp313-win_arm64.whl", hash = "sha256:a4474d924a47185a06411e0064b803c68be044be2d60e50e8bddcc2649957c1f", size = 143109, upload-time = "2026-03-15T18:51:39.565Z" },
+    { url = "https://files.pythonhosted.org/packages/25/6f/ffe1e1259f384594063ea1869bfb6be5cdb8bc81020fc36c3636bc8302a1/charset_normalizer-3.4.6-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:9cc6e6d9e571d2f863fa77700701dae73ed5f78881efc8b3f9a4398772ff53e8", size = 294458, upload-time = "2026-03-15T18:51:41.134Z" },
+    { url = "https://files.pythonhosted.org/packages/56/60/09bb6c13a8c1016c2ed5c6a6488e4ffef506461aa5161662bd7636936fb1/charset_normalizer-3.4.6-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ef5960d965e67165d75b7c7ffc60a83ec5abfc5c11b764ec13ea54fbef8b4421", size = 199277, upload-time = "2026-03-15T18:51:42.953Z" },
+    { url = "https://files.pythonhosted.org/packages/00/50/dcfbb72a5138bbefdc3332e8d81a23494bf67998b4b100703fd15fa52d81/charset_normalizer-3.4.6-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:b3694e3f87f8ac7ce279d4355645b3c878d24d1424581b46282f24b92f5a4ae2", size = 218758, upload-time = "2026-03-15T18:51:44.339Z" },
+    { url = "https://files.pythonhosted.org/packages/03/b3/d79a9a191bb75f5aa81f3aaaa387ef29ce7cb7a9e5074ba8ea095cc073c2/charset_normalizer-3.4.6-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5d11595abf8dd942a77883a39d81433739b287b6aa71620f15164f8096221b30", size = 215299, upload-time = "2026-03-15T18:51:45.871Z" },
+    { url = "https://files.pythonhosted.org/packages/76/7e/bc8911719f7084f72fd545f647601ea3532363927f807d296a8c88a62c0d/charset_normalizer-3.4.6-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7bda6eebafd42133efdca535b04ccb338ab29467b3f7bf79569883676fc628db", size = 206811, upload-time = "2026-03-15T18:51:47.308Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/40/c430b969d41dda0c465aa36cc7c2c068afb67177bef50905ac371b28ccc7/charset_normalizer-3.4.6-cp314-cp314-manylinux_2_31_armv7l.whl", hash = "sha256:bbc8c8650c6e51041ad1be191742b8b421d05bbd3410f43fa2a00c8db87678e8", size = 193706, upload-time = "2026-03-15T18:51:48.849Z" },
+    { url = "https://files.pythonhosted.org/packages/48/15/e35e0590af254f7df984de1323640ef375df5761f615b6225ba8deb9799a/charset_normalizer-3.4.6-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:22c6f0c2fbc31e76c3b8a86fba1a56eda6166e238c29cdd3d14befdb4a4e4815", size = 202706, upload-time = "2026-03-15T18:51:50.257Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/bd/f736f7b9cc5e93a18b794a50346bb16fbfd6b37f99e8f306f7951d27c17c/charset_normalizer-3.4.6-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7edbed096e4a4798710ed6bc75dcaa2a21b68b6c356553ac4823c3658d53743a", size = 202497, upload-time = "2026-03-15T18:51:52.012Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/ba/2cc9e3e7dfdf7760a6ed8da7446d22536f3d0ce114ac63dee2a5a3599e62/charset_normalizer-3.4.6-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:7f9019c9cb613f084481bd6a100b12e1547cf2efe362d873c2e31e4035a6fa43", size = 193511, upload-time = "2026-03-15T18:51:53.723Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/cb/5be49b5f776e5613be07298c80e1b02a2d900f7a7de807230595c85a8b2e/charset_normalizer-3.4.6-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:58c948d0d086229efc484fe2f30c2d382c86720f55cd9bc33591774348ad44e0", size = 220133, upload-time = "2026-03-15T18:51:55.333Z" },
+    { url = "https://files.pythonhosted.org/packages/83/43/99f1b5dad345accb322c80c7821071554f791a95ee50c1c90041c157ae99/charset_normalizer-3.4.6-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:419a9d91bd238052642a51938af8ac05da5b3343becde08d5cdeab9046df9ee1", size = 203035, upload-time = "2026-03-15T18:51:56.736Z" },
+    { url = "https://files.pythonhosted.org/packages/87/9a/62c2cb6a531483b55dddff1a68b3d891a8b498f3ca555fbcf2978e804d9d/charset_normalizer-3.4.6-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:5273b9f0b5835ff0350c0828faea623c68bfa65b792720c453e22b25cc72930f", size = 216321, upload-time = "2026-03-15T18:51:58.17Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/79/94a010ff81e3aec7c293eb82c28f930918e517bc144c9906a060844462eb/charset_normalizer-3.4.6-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:0e901eb1049fdb80f5bd11ed5ea1e498ec423102f7a9b9e4645d5b8204ff2815", size = 208973, upload-time = "2026-03-15T18:51:59.998Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/57/4ecff6d4ec8585342f0c71bc03efaa99cb7468f7c91a57b105bcd561cea8/charset_normalizer-3.4.6-cp314-cp314-win32.whl", hash = "sha256:b4ff1d35e8c5bd078be89349b6f3a845128e685e751b6ea1169cf2160b344c4d", size = 144610, upload-time = "2026-03-15T18:52:02.213Z" },
+    { url = "https://files.pythonhosted.org/packages/80/94/8434a02d9d7f168c25767c64671fead8d599744a05d6a6c877144c754246/charset_normalizer-3.4.6-cp314-cp314-win_amd64.whl", hash = "sha256:74119174722c4349af9708993118581686f343adc1c8c9c007d59be90d077f3f", size = 154962, upload-time = "2026-03-15T18:52:03.658Z" },
+    { url = "https://files.pythonhosted.org/packages/46/4c/48f2cdbfd923026503dfd67ccea45c94fd8fe988d9056b468579c66ed62b/charset_normalizer-3.4.6-cp314-cp314-win_arm64.whl", hash = "sha256:e5bcc1a1ae744e0bb59641171ae53743760130600da8db48cbb6e4918e186e4e", size = 143595, upload-time = "2026-03-15T18:52:05.123Z" },
+    { url = "https://files.pythonhosted.org/packages/31/93/8878be7569f87b14f1d52032946131bcb6ebbd8af3e20446bc04053dc3f1/charset_normalizer-3.4.6-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:ad8faf8df23f0378c6d527d8b0b15ea4a2e23c89376877c598c4870d1b2c7866", size = 314828, upload-time = "2026-03-15T18:52:06.831Z" },
+    { url = "https://files.pythonhosted.org/packages/06/b6/fae511ca98aac69ecc35cde828b0a3d146325dd03d99655ad38fc2cc3293/charset_normalizer-3.4.6-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f5ea69428fa1b49573eef0cc44a1d43bebd45ad0c611eb7d7eac760c7ae771bc", size = 208138, upload-time = "2026-03-15T18:52:08.239Z" },
+    { url = "https://files.pythonhosted.org/packages/54/57/64caf6e1bf07274a1e0b7c160a55ee9e8c9ec32c46846ce59b9c333f7008/charset_normalizer-3.4.6-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:06a7e86163334edfc5d20fe104db92fcd666e5a5df0977cb5680a506fe26cc8e", size = 224679, upload-time = "2026-03-15T18:52:10.043Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/cb/9ff5a25b9273ef160861b41f6937f86fae18b0792fe0a8e75e06acb08f1d/charset_normalizer-3.4.6-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:e1f6e2f00a6b8edb562826e4632e26d063ac10307e80f7461f7de3ad8ef3f077", size = 223475, upload-time = "2026-03-15T18:52:11.854Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/97/440635fc093b8d7347502a377031f9605a1039c958f3cd18dcacffb37743/charset_normalizer-3.4.6-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:95b52c68d64c1878818687a473a10547b3292e82b6f6fe483808fb1468e2f52f", size = 215230, upload-time = "2026-03-15T18:52:13.325Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/24/afff630feb571a13f07c8539fbb502d2ab494019492aaffc78ef41f1d1d0/charset_normalizer-3.4.6-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:7504e9b7dc05f99a9bbb4525c67a2c155073b44d720470a148b34166a69c054e", size = 199045, upload-time = "2026-03-15T18:52:14.752Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/17/d1399ecdaf7e0498c327433e7eefdd862b41236a7e484355b8e0e5ebd64b/charset_normalizer-3.4.6-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:172985e4ff804a7ad08eebec0a1640ece87ba5041d565fff23c8f99c1f389484", size = 211658, upload-time = "2026-03-15T18:52:16.278Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/38/16baa0affb957b3d880e5ac2144caf3f9d7de7bc4a91842e447fbb5e8b67/charset_normalizer-3.4.6-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:4be9f4830ba8741527693848403e2c457c16e499100963ec711b1c6f2049b7c7", size = 210769, upload-time = "2026-03-15T18:52:17.782Z" },
+    { url = "https://files.pythonhosted.org/packages/05/34/c531bc6ac4c21da9ddfddb3107be2287188b3ea4b53b70fc58f2a77ac8d8/charset_normalizer-3.4.6-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:79090741d842f564b1b2827c0b82d846405b744d31e84f18d7a7b41c20e473ff", size = 201328, upload-time = "2026-03-15T18:52:19.553Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/73/a5a1e9ca5f234519c1953608a03fe109c306b97fdfb25f09182babad51a7/charset_normalizer-3.4.6-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:87725cfb1a4f1f8c2fc9890ae2f42094120f4b44db9360be5d99a4c6b0e03a9e", size = 225302, upload-time = "2026-03-15T18:52:21.043Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/f6/cd782923d112d296294dea4bcc7af5a7ae0f86ab79f8fefbda5526b6cfc0/charset_normalizer-3.4.6-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:fcce033e4021347d80ed9c66dcf1e7b1546319834b74445f561d2e2221de5659", size = 211127, upload-time = "2026-03-15T18:52:22.491Z" },
+    { url = "https://files.pythonhosted.org/packages/0e/c5/0b6898950627af7d6103a449b22320372c24c6feda91aa24e201a478d161/charset_normalizer-3.4.6-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:ca0276464d148c72defa8bb4390cce01b4a0e425f3b50d1435aa6d7a18107602", size = 222840, upload-time = "2026-03-15T18:52:24.113Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/25/c4bba773bef442cbdc06111d40daa3de5050a676fa26e85090fc54dd12f0/charset_normalizer-3.4.6-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:197c1a244a274bb016dd8b79204850144ef77fe81c5b797dc389327adb552407", size = 216890, upload-time = "2026-03-15T18:52:25.541Z" },
+    { url = "https://files.pythonhosted.org/packages/35/1a/05dacadb0978da72ee287b0143097db12f2e7e8d3ffc4647da07a383b0b7/charset_normalizer-3.4.6-cp314-cp314t-win32.whl", hash = "sha256:2a24157fa36980478dd1770b585c0f30d19e18f4fb0c47c13aa568f871718579", size = 155379, upload-time = "2026-03-15T18:52:27.05Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/7a/d269d834cb3a76291651256f3b9a5945e81d0a49ab9f4a498964e83c0416/charset_normalizer-3.4.6-cp314-cp314t-win_amd64.whl", hash = "sha256:cd5e2801c89992ed8c0a3f0293ae83c159a60d9a5d685005383ef4caca77f2c4", size = 169043, upload-time = "2026-03-15T18:52:28.502Z" },
+    { url = "https://files.pythonhosted.org/packages/23/06/28b29fba521a37a8932c6a84192175c34d49f84a6d4773fa63d05f9aff22/charset_normalizer-3.4.6-cp314-cp314t-win_arm64.whl", hash = "sha256:47955475ac79cc504ef2704b192364e51d0d473ad452caedd0002605f780101c", size = 148523, upload-time = "2026-03-15T18:52:29.956Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/68/687187c7e26cb24ccbd88e5069f5ef00eba804d36dde11d99aad0838ab45/charset_normalizer-3.4.6-py3-none-any.whl", hash = "sha256:947cf925bc916d90adba35a64c82aace04fa39b46b52d4630ece166655905a69", size = 61455, upload-time = "2026-03-15T18:53:23.833Z" },
+]
+
+[[package]]
+name = "click"
+version = "8.3.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/3d/fa/656b739db8587d7b5dfa22e22ed02566950fbfbcdc20311993483657a5c0/click-8.3.1.tar.gz", hash = "sha256:12ff4785d337a1bb490bb7e9c2b1ee5da3112e94a8622f26a6c77f5d2fc6842a", size = 295065, upload-time = "2025-11-15T20:45:42.706Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/98/78/01c019cdb5d6498122777c1a43056ebb3ebfeef2076d9d026bfe15583b2b/click-8.3.1-py3-none-any.whl", hash = "sha256:981153a64e25f12d547d3426c367a4857371575ee7ad18df2a6183ab0545b2a6", size = 108274, upload-time = "2025-11-15T20:45:41.139Z" },
+]
+
+[[package]]
+name = "cloudpickle"
+version = "3.1.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/27/fb/576f067976d320f5f0114a8d9fa1215425441bb35627b1993e5afd8111e5/cloudpickle-3.1.2.tar.gz", hash = "sha256:7fda9eb655c9c230dab534f1983763de5835249750e85fbcef43aaa30a9a2414", size = 22330, upload-time = "2025-11-03T09:25:26.604Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/88/39/799be3f2f0f38cc727ee3b4f1445fe6d5e4133064ec2e4115069418a5bb6/cloudpickle-3.1.2-py3-none-any.whl", hash = "sha256:9acb47f6afd73f60dc1df93bb801b472f05ff42fa6c84167d25cb206be1fbf4a", size = 22228, upload-time = "2025-11-03T09:25:25.534Z" },
+]
+
+[[package]]
+name = "colorama"
+version = "0.4.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
+]
+
+[[package]]
+name = "coverage"
+version = "7.13.5"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/9d/e0/70553e3000e345daff267cec284ce4cbf3fc141b6da229ac52775b5428f1/coverage-7.13.5.tar.gz", hash = "sha256:c81f6515c4c40141f83f502b07bbfa5c240ba25bbe73da7b33f1e5b6120ff179", size = 915967, upload-time = "2026-03-17T10:33:18.341Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/69/33/e8c48488c29a73fd089f9d71f9653c1be7478f2ad6b5bc870db11a55d23d/coverage-7.13.5-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:e0723d2c96324561b9aa76fb982406e11d93cdb388a7a7da2b16e04719cf7ca5", size = 219255, upload-time = "2026-03-17T10:29:51.081Z" },
+    { url = "https://files.pythonhosted.org/packages/da/bd/b0ebe9f677d7f4b74a3e115eec7ddd4bcf892074963a00d91e8b164a6386/coverage-7.13.5-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:52f444e86475992506b32d4e5ca55c24fc88d73bcbda0e9745095b28ef4dc0cf", size = 219772, upload-time = "2026-03-17T10:29:52.867Z" },
+    { url = "https://files.pythonhosted.org/packages/48/cc/5cb9502f4e01972f54eedd48218bb203fe81e294be606a2bc93970208013/coverage-7.13.5-cp310-cp310-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:704de6328e3d612a8f6c07000a878ff38181ec3263d5a11da1db294fa6a9bdf8", size = 246532, upload-time = "2026-03-17T10:29:54.688Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/d8/3217636d86c7e7b12e126e4f30ef1581047da73140614523af7495ed5f2d/coverage-7.13.5-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:a1a6d79a14e1ec1832cabc833898636ad5f3754a678ef8bb4908515208bf84f4", size = 248333, upload-time = "2026-03-17T10:29:56.221Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/30/2002ac6729ba2d4357438e2ed3c447ad8562866c8c63fc16f6dfc33afe56/coverage-7.13.5-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:79060214983769c7ba3f0cee10b54c97609dca4d478fa1aa32b914480fd5738d", size = 250211, upload-time = "2026-03-17T10:29:57.938Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/85/552496626d6b9359eb0e2f86f920037c9cbfba09b24d914c6e1528155f7d/coverage-7.13.5-cp310-cp310-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:356e76b46783a98c2a2fe81ec79df4883a1e62895ea952968fb253c114e7f930", size = 252125, upload-time = "2026-03-17T10:29:59.388Z" },
+    { url = "https://files.pythonhosted.org/packages/44/21/40256eabdcbccdb6acf6b381b3016a154399a75fe39d406f790ae84d1f3c/coverage-7.13.5-cp310-cp310-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:0cef0cdec915d11254a7f549c1170afecce708d30610c6abdded1f74e581666d", size = 247219, upload-time = "2026-03-17T10:30:01.199Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/e8/96e2a6c3f21a0ea77d7830b254a1542d0328acc8d7bdf6a284ba7e529f77/coverage-7.13.5-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:dc022073d063b25a402454e5712ef9e007113e3a676b96c5f29b2bda29352f40", size = 248248, upload-time = "2026-03-17T10:30:03.317Z" },
+    { url = "https://files.pythonhosted.org/packages/da/ba/8477f549e554827da390ec659f3c38e4b6d95470f4daafc2d8ff94eaa9c2/coverage-7.13.5-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:9b74db26dfea4f4e50d48a4602207cd1e78be33182bc9cbf22da94f332f99878", size = 246254, upload-time = "2026-03-17T10:30:04.832Z" },
+    { url = "https://files.pythonhosted.org/packages/55/59/bc22aef0e6aa179d5b1b001e8b3654785e9adf27ef24c93dc4228ebd5d68/coverage-7.13.5-cp310-cp310-musllinux_1_2_ppc64le.whl", hash = "sha256:ad146744ca4fd09b50c482650e3c1b1f4dfa1d4792e0a04a369c7f23336f0400", size = 250067, upload-time = "2026-03-17T10:30:06.535Z" },
+    { url = "https://files.pythonhosted.org/packages/de/1b/c6a023a160806a5137dca53468fd97530d6acad24a22003b1578a9c2e429/coverage-7.13.5-cp310-cp310-musllinux_1_2_riscv64.whl", hash = "sha256:c555b48be1853fe3997c11c4bd521cdd9a9612352de01fa4508f16ec341e6fe0", size = 246521, upload-time = "2026-03-17T10:30:08.486Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/3f/3532c85a55aa2f899fa17c186f831cfa1aa434d88ff792a709636f64130e/coverage-7.13.5-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:7034b5c56a58ae5e85f23949d52c14aca2cfc6848a31764995b7de88f13a1ea0", size = 247126, upload-time = "2026-03-17T10:30:09.966Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/2e/b9d56af4a24ef45dfbcda88e06870cb7d57b2b0bfa3a888d79b4c8debd76/coverage-7.13.5-cp310-cp310-win32.whl", hash = "sha256:eb7fdf1ef130660e7415e0253a01a7d5a88c9c4d158bcf75cbbd922fd65a5b58", size = 221860, upload-time = "2026-03-17T10:30:11.393Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/cc/d938417e7a4d7f0433ad4edee8bb2acdc60dc7ac5af19e2a07a048ecbee3/coverage-7.13.5-cp310-cp310-win_amd64.whl", hash = "sha256:3e1bb5f6c78feeb1be3475789b14a0f0a5b47d505bfc7267126ccbd50289999e", size = 222788, upload-time = "2026-03-17T10:30:12.886Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/37/d24c8f8220ff07b839b2c043ea4903a33b0f455abe673ae3c03bbdb7f212/coverage-7.13.5-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:66a80c616f80181f4d643b0f9e709d97bcea413ecd9631e1dedc7401c8e6695d", size = 219381, upload-time = "2026-03-17T10:30:14.68Z" },
+    { url = "https://files.pythonhosted.org/packages/35/8b/cd129b0ca4afe886a6ce9d183c44d8301acbd4ef248622e7c49a23145605/coverage-7.13.5-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:145ede53ccbafb297c1c9287f788d1bc3efd6c900da23bf6931b09eafc931587", size = 219880, upload-time = "2026-03-17T10:30:16.231Z" },
+    { url = "https://files.pythonhosted.org/packages/55/2f/e0e5b237bffdb5d6c530ce87cc1d413a5b7d7dfd60fb067ad6d254c35c76/coverage-7.13.5-cp311-cp311-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:0672854dc733c342fa3e957e0605256d2bf5934feeac328da9e0b5449634a642", size = 250303, upload-time = "2026-03-17T10:30:17.748Z" },
+    { url = "https://files.pythonhosted.org/packages/92/be/b1afb692be85b947f3401375851484496134c5554e67e822c35f28bf2fbc/coverage-7.13.5-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:ec10e2a42b41c923c2209b846126c6582db5e43a33157e9870ba9fb70dc7854b", size = 252218, upload-time = "2026-03-17T10:30:19.804Z" },
+    { url = "https://files.pythonhosted.org/packages/da/69/2f47bb6fa1b8d1e3e5d0c4be8ccb4313c63d742476a619418f85740d597b/coverage-7.13.5-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:be3d4bbad9d4b037791794ddeedd7d64a56f5933a2c1373e18e9e568b9141686", size = 254326, upload-time = "2026-03-17T10:30:21.321Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/d0/79db81da58965bd29dabc8f4ad2a2af70611a57cba9d1ec006f072f30a54/coverage-7.13.5-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:4d2afbc5cc54d286bfb54541aa50b64cdb07a718227168c87b9e2fb8f25e1743", size = 256267, upload-time = "2026-03-17T10:30:23.094Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/32/d0d7cc8168f91ddab44c0ce4806b969df5f5fdfdbb568eaca2dbc2a04936/coverage-7.13.5-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:3ad050321264c49c2fa67bb599100456fc51d004b82534f379d16445da40fb75", size = 250430, upload-time = "2026-03-17T10:30:25.311Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/06/a055311d891ddbe231cd69fdd20ea4be6e3603ffebddf8704b8ca8e10a3c/coverage-7.13.5-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:7300c8a6d13335b29bb76d7651c66af6bd8658517c43499f110ddc6717bfc209", size = 252017, upload-time = "2026-03-17T10:30:27.284Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/f6/d0fd2d21e29a657b5f77a2fe7082e1568158340dceb941954f776dce1b7b/coverage-7.13.5-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:eb07647a5738b89baab047f14edd18ded523de60f3b30e75c2acc826f79c839a", size = 250080, upload-time = "2026-03-17T10:30:29.481Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/ab/0d7fb2efc2e9a5eb7ddcc6e722f834a69b454b7e6e5888c3a8567ecffb31/coverage-7.13.5-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:9adb6688e3b53adffefd4a52d72cbd8b02602bfb8f74dcd862337182fd4d1a4e", size = 253843, upload-time = "2026-03-17T10:30:31.301Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/6f/7467b917bbf5408610178f62a49c0ed4377bb16c1657f689cc61470da8ce/coverage-7.13.5-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:7c8d4bc913dd70b93488d6c496c77f3aff5ea99a07e36a18f865bca55adef8bd", size = 249802, upload-time = "2026-03-17T10:30:33.358Z" },
+    { url = "https://files.pythonhosted.org/packages/75/2c/1172fb689df92135f5bfbbd69fc83017a76d24ea2e2f3a1154007e2fb9f8/coverage-7.13.5-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:0e3c426ffc4cd952f54ee9ffbdd10345709ecc78a3ecfd796a57236bfad0b9b8", size = 250707, upload-time = "2026-03-17T10:30:35.2Z" },
+    { url = "https://files.pythonhosted.org/packages/67/21/9ac389377380a07884e3b48ba7a620fcd9dbfaf1d40565facdc6b36ec9ef/coverage-7.13.5-cp311-cp311-win32.whl", hash = "sha256:259b69bb83ad9894c4b25be2528139eecba9a82646ebdda2d9db1ba28424a6bf", size = 221880, upload-time = "2026-03-17T10:30:36.775Z" },
+    { url = "https://files.pythonhosted.org/packages/af/7f/4cd8a92531253f9d7c1bbecd9fa1b472907fb54446ca768c59b531248dc5/coverage-7.13.5-cp311-cp311-win_amd64.whl", hash = "sha256:258354455f4e86e3e9d0d17571d522e13b4e1e19bf0f8596bcf9476d61e7d8a9", size = 222816, upload-time = "2026-03-17T10:30:38.891Z" },
+    { url = "https://files.pythonhosted.org/packages/12/a6/1d3f6155fb0010ca68eba7fe48ca6c9da7385058b77a95848710ecf189b1/coverage-7.13.5-cp311-cp311-win_arm64.whl", hash = "sha256:bff95879c33ec8da99fc9b6fe345ddb5be6414b41d6d1ad1c8f188d26f36e028", size = 221483, upload-time = "2026-03-17T10:30:40.463Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/c3/a396306ba7db865bf96fc1fb3b7fd29bcbf3d829df642e77b13555163cd6/coverage-7.13.5-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:460cf0114c5016fa841214ff5564aa4864f11948da9440bc97e21ad1f4ba1e01", size = 219554, upload-time = "2026-03-17T10:30:42.208Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/16/a68a19e5384e93f811dccc51034b1fd0b865841c390e3c931dcc4699e035/coverage-7.13.5-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:0e223ce4b4ed47f065bfb123687686512e37629be25cc63728557ae7db261422", size = 219908, upload-time = "2026-03-17T10:30:43.906Z" },
+    { url = "https://files.pythonhosted.org/packages/29/72/20b917c6793af3a5ceb7fb9c50033f3ec7865f2911a1416b34a7cfa0813b/coverage-7.13.5-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:6e3370441f4513c6252bf042b9c36d22491142385049243253c7e48398a15a9f", size = 251419, upload-time = "2026-03-17T10:30:45.545Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/49/cd14b789536ac6a4778c453c6a2338bc0a2fb60c5a5a41b4008328b9acc1/coverage-7.13.5-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:03ccc709a17a1de074fb1d11f217342fb0d2b1582ed544f554fc9fc3f07e95f5", size = 254159, upload-time = "2026-03-17T10:30:47.204Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/00/7b0edcfe64e2ed4c0340dac14a52ad0f4c9bd0b8b5e531af7d55b703db7c/coverage-7.13.5-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3f4818d065964db3c1c66dc0fbdac5ac692ecbc875555e13374fdbe7eedb4376", size = 255270, upload-time = "2026-03-17T10:30:48.812Z" },
+    { url = "https://files.pythonhosted.org/packages/93/89/7ffc4ba0f5d0a55c1e84ea7cee39c9fc06af7b170513d83fbf3bbefce280/coverage-7.13.5-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:012d5319e66e9d5a218834642d6c35d265515a62f01157a45bcc036ecf947256", size = 257538, upload-time = "2026-03-17T10:30:50.77Z" },
+    { url = "https://files.pythonhosted.org/packages/81/bd/73ddf85f93f7e6fa83e77ccecb6162d9415c79007b4bc124008a4995e4a7/coverage-7.13.5-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:8dd02af98971bdb956363e4827d34425cb3df19ee550ef92855b0acb9c7ce51c", size = 251821, upload-time = "2026-03-17T10:30:52.5Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/81/278aff4e8dec4926a0bcb9486320752811f543a3ce5b602cc7a29978d073/coverage-7.13.5-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:f08fd75c50a760c7eb068ae823777268daaf16a80b918fa58eea888f8e3919f5", size = 253191, upload-time = "2026-03-17T10:30:54.543Z" },
+    { url = "https://files.pythonhosted.org/packages/70/ee/fe1621488e2e0a58d7e94c4800f0d96f79671553488d401a612bebae324b/coverage-7.13.5-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:843ea8643cf967d1ac7e8ecd4bb00c99135adf4816c0c0593fdcc47b597fcf09", size = 251337, upload-time = "2026-03-17T10:30:56.663Z" },
+    { url = "https://files.pythonhosted.org/packages/37/a6/f79fb37aa104b562207cc23cb5711ab6793608e246cae1e93f26b2236ed9/coverage-7.13.5-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:9d44d7aa963820b1b971dbecd90bfe5fe8f81cff79787eb6cca15750bd2f79b9", size = 255404, upload-time = "2026-03-17T10:30:58.427Z" },
+    { url = "https://files.pythonhosted.org/packages/75/f0/ed15262a58ec81ce457ceb717b7f78752a1713556b19081b76e90896e8d4/coverage-7.13.5-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:7132bed4bd7b836200c591410ae7d97bf7ae8be6fc87d160b2bd881df929e7bf", size = 250903, upload-time = "2026-03-17T10:31:00.093Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/e9/9129958f20e7e9d4d56d51d42ccf708d15cac355ff4ac6e736e97a9393d2/coverage-7.13.5-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:a698e363641b98843c517817db75373c83254781426e94ada3197cabbc2c919c", size = 252780, upload-time = "2026-03-17T10:31:01.916Z" },
+    { url = "https://files.pythonhosted.org/packages/a4/d7/0ad9b15812d81272db94379fe4c6df8fd17781cc7671fdfa30c76ba5ff7b/coverage-7.13.5-cp312-cp312-win32.whl", hash = "sha256:bdba0a6b8812e8c7df002d908a9a2ea3c36e92611b5708633c50869e6d922fdf", size = 222093, upload-time = "2026-03-17T10:31:03.642Z" },
+    { url = "https://files.pythonhosted.org/packages/29/3d/821a9a5799fac2556bcf0bd37a70d1d11fa9e49784b6d22e92e8b2f85f18/coverage-7.13.5-cp312-cp312-win_amd64.whl", hash = "sha256:d2c87e0c473a10bffe991502eac389220533024c8082ec1ce849f4218dded810", size = 222900, upload-time = "2026-03-17T10:31:05.651Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/fa/2238c2ad08e35cf4f020ea721f717e09ec3152aea75d191a7faf3ef009a8/coverage-7.13.5-cp312-cp312-win_arm64.whl", hash = "sha256:bf69236a9a81bdca3bff53796237aab096cdbf8d78a66ad61e992d9dac7eb2de", size = 221515, upload-time = "2026-03-17T10:31:07.293Z" },
+    { url = "https://files.pythonhosted.org/packages/74/8c/74fedc9663dcf168b0a059d4ea756ecae4da77a489048f94b5f512a8d0b3/coverage-7.13.5-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:5ec4af212df513e399cf11610cc27063f1586419e814755ab362e50a85ea69c1", size = 219576, upload-time = "2026-03-17T10:31:09.045Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/c9/44fb661c55062f0818a6ffd2685c67aa30816200d5f2817543717d4b92eb/coverage-7.13.5-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:941617e518602e2d64942c88ec8499f7fbd49d3f6c4327d3a71d43a1973032f3", size = 219942, upload-time = "2026-03-17T10:31:10.708Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/13/93419671cee82b780bab7ea96b67c8ef448f5f295f36bf5031154ec9a790/coverage-7.13.5-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:da305e9937617ee95c2e39d8ff9f040e0487cbf1ac174f777ed5eddd7a7c1f26", size = 250935, upload-time = "2026-03-17T10:31:12.392Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/68/1666e3a4462f8202d836920114fa7a5ee9275d1fa45366d336c551a162dd/coverage-7.13.5-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:78e696e1cc714e57e8b25760b33a8b1026b7048d270140d25dafe1b0a1ee05a3", size = 253541, upload-time = "2026-03-17T10:31:14.247Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/5e/3ee3b835647be646dcf3c65a7c6c18f87c27326a858f72ab22c12730773d/coverage-7.13.5-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:02ca0eed225b2ff301c474aeeeae27d26e2537942aa0f87491d3e147e784a82b", size = 254780, upload-time = "2026-03-17T10:31:16.193Z" },
+    { url = "https://files.pythonhosted.org/packages/44/b3/cb5bd1a04cfcc49ede6cd8409d80bee17661167686741e041abc7ee1b9a9/coverage-7.13.5-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:04690832cbea4e4663d9149e05dba142546ca05cb1848816760e7f58285c970a", size = 256912, upload-time = "2026-03-17T10:31:17.89Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/66/c1dceb7b9714473800b075f5c8a84f4588f887a90eb8645282031676e242/coverage-7.13.5-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:0590e44dd2745c696a778f7bab6aa95256de2cbc8b8cff4f7db8ff09813d6969", size = 251165, upload-time = "2026-03-17T10:31:19.605Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/62/5502b73b97aa2e53ea22a39cf8649ff44827bef76d90bf638777daa27a9d/coverage-7.13.5-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:d7cfad2d6d81dd298ab6b89fe72c3b7b05ec7544bdda3b707ddaecff8d25c161", size = 252908, upload-time = "2026-03-17T10:31:21.312Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/37/7792c2d69854397ca77a55c4646e5897c467928b0e27f2d235d83b5d08c6/coverage-7.13.5-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:e092b9499de38ae0fbfbc603a74660eb6ff3e869e507b50d85a13b6db9863e15", size = 250873, upload-time = "2026-03-17T10:31:23.565Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/23/bc866fb6163be52a8a9e5d708ba0d3b1283c12158cefca0a8bbb6e247a43/coverage-7.13.5-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:48c39bc4a04d983a54a705a6389512883d4a3b9862991b3617d547940e9f52b1", size = 255030, upload-time = "2026-03-17T10:31:25.58Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/8b/ef67e1c222ef49860701d346b8bbb70881bef283bd5f6cbba68a39a086c7/coverage-7.13.5-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:2d3807015f138ffea1ed9afeeb8624fd781703f2858b62a8dd8da5a0994c57b6", size = 250694, upload-time = "2026-03-17T10:31:27.316Z" },
+    { url = "https://files.pythonhosted.org/packages/46/0d/866d1f74f0acddbb906db212e096dee77a8e2158ca5e6bb44729f9d93298/coverage-7.13.5-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:ee2aa19e03161671ec964004fb74b2257805d9710bf14a5c704558b9d8dbaf17", size = 252469, upload-time = "2026-03-17T10:31:29.472Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/f5/be742fec31118f02ce42b21c6af187ad6a344fed546b56ca60caacc6a9a0/coverage-7.13.5-cp313-cp313-win32.whl", hash = "sha256:ce1998c0483007608c8382f4ff50164bfc5bd07a2246dd272aa4043b75e61e85", size = 222112, upload-time = "2026-03-17T10:31:31.526Z" },
+    { url = "https://files.pythonhosted.org/packages/66/40/7732d648ab9d069a46e686043241f01206348e2bbf128daea85be4d6414b/coverage-7.13.5-cp313-cp313-win_amd64.whl", hash = "sha256:631efb83f01569670a5e866ceb80fe483e7c159fac6f167e6571522636104a0b", size = 222923, upload-time = "2026-03-17T10:31:33.633Z" },
+    { url = "https://files.pythonhosted.org/packages/48/af/fea819c12a095781f6ccd504890aaddaf88b8fab263c4940e82c7b770124/coverage-7.13.5-cp313-cp313-win_arm64.whl", hash = "sha256:f4cd16206ad171cbc2470dbea9103cf9a7607d5fe8c242fdf1edf36174020664", size = 221540, upload-time = "2026-03-17T10:31:35.445Z" },
+    { url = "https://files.pythonhosted.org/packages/23/d2/17879af479df7fbbd44bd528a31692a48f6b25055d16482fdf5cdb633805/coverage-7.13.5-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:0428cbef5783ad91fe240f673cc1f76b25e74bbfe1a13115e4aa30d3f538162d", size = 220262, upload-time = "2026-03-17T10:31:37.184Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/4c/d20e554f988c8f91d6a02c5118f9abbbf73a8768a3048cb4962230d5743f/coverage-7.13.5-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:e0b216a19534b2427cc201a26c25da4a48633f29a487c61258643e89d28200c0", size = 220617, upload-time = "2026-03-17T10:31:39.245Z" },
+    { url = "https://files.pythonhosted.org/packages/29/9c/f9f5277b95184f764b24e7231e166dfdb5780a46d408a2ac665969416d61/coverage-7.13.5-cp313-cp313t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:972a9cd27894afe4bc2b1480107054e062df08e671df7c2f18c205e805ccd806", size = 261912, upload-time = "2026-03-17T10:31:41.324Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/f6/7f1ab39393eeb50cfe4747ae8ef0e4fc564b989225aa1152e13a180d74f8/coverage-7.13.5-cp313-cp313t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:4b59148601efcd2bac8c4dbf1f0ad6391693ccf7a74b8205781751637076aee3", size = 263987, upload-time = "2026-03-17T10:31:43.724Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/d7/62c084fb489ed9c6fbdf57e006752e7c516ea46fd690e5ed8b8617c7d52e/coverage-7.13.5-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:505d7083c8b0c87a8fa8c07370c285847c1f77739b22e299ad75a6af6c32c5c9", size = 266416, upload-time = "2026-03-17T10:31:45.769Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/f6/df63d8660e1a0bff6125947afda112a0502736f470d62ca68b288ea762d8/coverage-7.13.5-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:60365289c3741e4db327e7baff2a4aaacf22f788e80fa4683393891b70a89fbd", size = 267558, upload-time = "2026-03-17T10:31:48.293Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/02/353ca81d36779bd108f6d384425f7139ac3c58c750dcfaafe5d0bee6436b/coverage-7.13.5-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:1b88c69c8ef5d4b6fe7dea66d6636056a0f6a7527c440e890cf9259011f5e606", size = 261163, upload-time = "2026-03-17T10:31:50.125Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/16/2e79106d5749bcaf3aee6d309123548e3276517cd7851faa8da213bc61bf/coverage-7.13.5-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:5b13955d31d1633cf9376908089b7cebe7d15ddad7aeaabcbe969a595a97e95e", size = 263981, upload-time = "2026-03-17T10:31:51.961Z" },
+    { url = "https://files.pythonhosted.org/packages/29/c7/c29e0c59ffa6942030ae6f50b88ae49988e7e8da06de7ecdbf49c6d4feae/coverage-7.13.5-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:f70c9ab2595c56f81a89620e22899eea8b212a4041bd728ac6f4a28bf5d3ddd0", size = 261604, upload-time = "2026-03-17T10:31:53.872Z" },
+    { url = "https://files.pythonhosted.org/packages/40/48/097cdc3db342f34006a308ab41c3a7c11c3f0d84750d340f45d88a782e00/coverage-7.13.5-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:084b84a8c63e8d6fc7e3931b316a9bcafca1458d753c539db82d31ed20091a87", size = 265321, upload-time = "2026-03-17T10:31:55.997Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/1f/4994af354689e14fd03a75f8ec85a9a68d94e0188bbdab3fc1516b55e512/coverage-7.13.5-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:ad14385487393e386e2ea988b09d62dd42c397662ac2dabc3832d71253eee479", size = 260502, upload-time = "2026-03-17T10:31:58.308Z" },
+    { url = "https://files.pythonhosted.org/packages/22/c6/9bb9ef55903e628033560885f5c31aa227e46878118b63ab15dc7ba87797/coverage-7.13.5-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:7f2c47b36fe7709a6e83bfadf4eefb90bd25fbe4014d715224c4316f808e59a2", size = 262688, upload-time = "2026-03-17T10:32:00.141Z" },
+    { url = "https://files.pythonhosted.org/packages/14/4f/f5df9007e50b15e53e01edea486814783a7f019893733d9e4d6caad75557/coverage-7.13.5-cp313-cp313t-win32.whl", hash = "sha256:67e9bc5449801fad0e5dff329499fb090ba4c5800b86805c80617b4e29809b2a", size = 222788, upload-time = "2026-03-17T10:32:02.246Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/98/aa7fccaa97d0f3192bec013c4e6fd6d294a6ed44b640e6bb61f479e00ed5/coverage-7.13.5-cp313-cp313t-win_amd64.whl", hash = "sha256:da86cdcf10d2519e10cabb8ac2de03da1bcb6e4853790b7fbd48523332e3a819", size = 223851, upload-time = "2026-03-17T10:32:04.416Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/8b/e5c469f7352651e5f013198e9e21f97510b23de957dd06a84071683b4b60/coverage-7.13.5-cp313-cp313t-win_arm64.whl", hash = "sha256:0ecf12ecb326fe2c339d93fc131816f3a7367d223db37817208905c89bded911", size = 222104, upload-time = "2026-03-17T10:32:06.65Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/77/39703f0d1d4b478bfd30191d3c14f53caf596fac00efb3f8f6ee23646439/coverage-7.13.5-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:fbabfaceaeb587e16f7008f7795cd80d20ec548dc7f94fbb0d4ec2e038ce563f", size = 219621, upload-time = "2026-03-17T10:32:08.589Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/3e/51dff36d99ae14639a133d9b164d63e628532e2974d8b1edb99dd1ebc733/coverage-7.13.5-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:9bb2a28101a443669a423b665939381084412b81c3f8c0fcfbac57f4e30b5b8e", size = 219953, upload-time = "2026-03-17T10:32:10.507Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/6c/1f1917b01eb647c2f2adc9962bd66c79eb978951cab61bdc1acab3290c07/coverage-7.13.5-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:bd3a2fbc1c6cccb3c5106140d87cc6a8715110373ef42b63cf5aea29df8c217a", size = 250992, upload-time = "2026-03-17T10:32:12.41Z" },
+    { url = "https://files.pythonhosted.org/packages/22/e5/06b1f88f42a5a99df42ce61208bdec3bddb3d261412874280a19796fc09c/coverage-7.13.5-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:6c36ddb64ed9d7e496028d1d00dfec3e428e0aabf4006583bb1839958d280510", size = 253503, upload-time = "2026-03-17T10:32:14.449Z" },
+    { url = "https://files.pythonhosted.org/packages/80/28/2a148a51e5907e504fa7b85490277734e6771d8844ebcc48764a15e28155/coverage-7.13.5-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:380e8e9084d8eb38db3a9176a1a4f3c0082c3806fa0dc882d1d87abc3c789247", size = 254852, upload-time = "2026-03-17T10:32:16.56Z" },
+    { url = "https://files.pythonhosted.org/packages/61/77/50e8d3d85cc0b7ebe09f30f151d670e302c7ff4a1bf6243f71dd8b0981fa/coverage-7.13.5-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e808af52a0513762df4d945ea164a24b37f2f518cbe97e03deaa0ee66139b4d6", size = 257161, upload-time = "2026-03-17T10:32:19.004Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/c4/b5fd1d4b7bf8d0e75d997afd3925c59ba629fc8616f1b3aae7605132e256/coverage-7.13.5-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e301d30dd7e95ae068671d746ba8c34e945a82682e62918e41b2679acd2051a0", size = 251021, upload-time = "2026-03-17T10:32:21.344Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/66/6ea21f910e92d69ef0b1c3346ea5922a51bad4446c9126db2ae96ee24c4c/coverage-7.13.5-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:800bc829053c80d240a687ceeb927a94fd108bbdc68dfbe505d0d75ab578a882", size = 252858, upload-time = "2026-03-17T10:32:23.506Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/ea/879c83cb5d61aa2a35fb80e72715e92672daef8191b84911a643f533840c/coverage-7.13.5-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:0b67af5492adb31940ee418a5a655c28e48165da5afab8c7fa6fd72a142f8740", size = 250823, upload-time = "2026-03-17T10:32:25.516Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/fb/616d95d3adb88b9803b275580bdeee8bd1b69a886d057652521f83d7322f/coverage-7.13.5-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:c9136ff29c3a91e25b1d1552b5308e53a1e0653a23e53b6366d7c2dcbbaf8a16", size = 255099, upload-time = "2026-03-17T10:32:27.944Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/93/25e6917c90ec1c9a56b0b26f6cad6408e5f13bb6b35d484a0d75c9cf000d/coverage-7.13.5-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:cff784eef7f0b8f6cb28804fbddcfa99f89efe4cc35fb5627e3ac58f91ed3ac0", size = 250638, upload-time = "2026-03-17T10:32:29.914Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/7b/dc1776b0464145a929deed214aef9fb1493f159b59ff3c7eeeedf91eddd0/coverage-7.13.5-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:68a4953be99b17ac3c23b6efbc8a38330d99680c9458927491d18700ef23ded0", size = 252295, upload-time = "2026-03-17T10:32:31.981Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/fb/99cbbc56a26e07762a2740713f3c8f9f3f3106e3a3dd8cc4474954bccd34/coverage-7.13.5-cp314-cp314-win32.whl", hash = "sha256:35a31f2b1578185fbe6aa2e74cea1b1d0bbf4c552774247d9160d29b80ed56cc", size = 222360, upload-time = "2026-03-17T10:32:34.233Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/b7/4758d4f73fb536347cc5e4ad63662f9d60ba9118cb6785e9616b2ce5d7fa/coverage-7.13.5-cp314-cp314-win_amd64.whl", hash = "sha256:2aa055ae1857258f9e0045be26a6d62bdb47a72448b62d7b55f4820f361a2633", size = 223174, upload-time = "2026-03-17T10:32:36.369Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/f2/24d84e1dfe70f8ac9fdf30d338239860d0d1d5da0bda528959d0ebc9da28/coverage-7.13.5-cp314-cp314-win_arm64.whl", hash = "sha256:1b11eef33edeae9d142f9b4358edb76273b3bfd30bc3df9a4f95d0e49caf94e8", size = 221739, upload-time = "2026-03-17T10:32:38.736Z" },
+    { url = "https://files.pythonhosted.org/packages/60/5b/4a168591057b3668c2428bff25dd3ebc21b629d666d90bcdfa0217940e84/coverage-7.13.5-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:10a0c37f0b646eaff7cce1874c31d1f1ccb297688d4c747291f4f4c70741cc8b", size = 220351, upload-time = "2026-03-17T10:32:41.196Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/21/1fd5c4dbfe4a58b6b99649125635df46decdfd4a784c3cd6d410d303e370/coverage-7.13.5-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:b5db73ba3c41c7008037fa731ad5459fc3944cb7452fc0aa9f822ad3533c583c", size = 220612, upload-time = "2026-03-17T10:32:43.204Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/fe/2a924b3055a5e7e4512655a9d4609781b0d62334fa0140c3e742926834e2/coverage-7.13.5-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:750db93a81e3e5a9831b534be7b1229df848b2e125a604fe6651e48aa070e5f9", size = 261985, upload-time = "2026-03-17T10:32:45.514Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/0d/c8928f2bd518c45990fe1a2ab8db42e914ef9b726c975facc4282578c3eb/coverage-7.13.5-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:9ddb4f4a5479f2539644be484da179b653273bca1a323947d48ab107b3ed1f29", size = 264107, upload-time = "2026-03-17T10:32:47.971Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/ae/4ae35bbd9a0af9d820362751f0766582833c211224b38665c0f8de3d487f/coverage-7.13.5-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d8a7a2049c14f413163e2bdabd37e41179b1d1ccb10ffc6ccc4b7a718429c607", size = 266513, upload-time = "2026-03-17T10:32:50.1Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/20/d326174c55af36f74eac6ae781612d9492f060ce8244b570bb9d50d9d609/coverage-7.13.5-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e1c85e0b6c05c592ea6d8768a66a254bfb3874b53774b12d4c89c481eb78cb90", size = 267650, upload-time = "2026-03-17T10:32:52.391Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/5e/31484d62cbd0eabd3412e30d74386ece4a0837d4f6c3040a653878bfc019/coverage-7.13.5-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:777c4d1eff1b67876139d24288aaf1817f6c03d6bae9c5cc8d27b83bcfe38fe3", size = 261089, upload-time = "2026-03-17T10:32:54.544Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/d8/49a72d6de146eebb0b7e48cc0f4bc2c0dd858e3d4790ab2b39a2872b62bd/coverage-7.13.5-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:6697e29b93707167687543480a40f0db8f356e86d9f67ddf2e37e2dfd91a9dab", size = 263982, upload-time = "2026-03-17T10:32:56.803Z" },
+    { url = "https://files.pythonhosted.org/packages/06/3b/0351f1bd566e6e4dd39e978efe7958bde1d32f879e85589de147654f57bb/coverage-7.13.5-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:8fdf453a942c3e4d99bd80088141c4c6960bb232c409d9c3558e2dbaa3998562", size = 261579, upload-time = "2026-03-17T10:32:59.466Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/ce/796a2a2f4017f554d7810f5c573449b35b1e46788424a548d4d19201b222/coverage-7.13.5-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:32ca0c0114c9834a43f045a87dcebd69d108d8ffb666957ea65aa132f50332e2", size = 265316, upload-time = "2026-03-17T10:33:01.847Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/16/d5ae91455541d1a78bc90abf495be600588aff8f6db5c8b0dae739fa39c9/coverage-7.13.5-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:8769751c10f339021e2638cd354e13adeac54004d1941119b2c96fe5276d45ea", size = 260427, upload-time = "2026-03-17T10:33:03.945Z" },
+    { url = "https://files.pythonhosted.org/packages/48/11/07f413dba62db21fb3fad5d0de013a50e073cc4e2dc4306e770360f6dfc8/coverage-7.13.5-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:cec2d83125531bd153175354055cdb7a09987af08a9430bd173c937c6d0fba2a", size = 262745, upload-time = "2026-03-17T10:33:06.285Z" },
+    { url = "https://files.pythonhosted.org/packages/91/15/d792371332eb4663115becf4bad47e047d16234b1aff687b1b18c58d60ae/coverage-7.13.5-cp314-cp314t-win32.whl", hash = "sha256:0cd9ed7a8b181775459296e402ca4fb27db1279740a24e93b3b41942ebe4b215", size = 223146, upload-time = "2026-03-17T10:33:08.756Z" },
+    { url = "https://files.pythonhosted.org/packages/db/51/37221f59a111dca5e85be7dbf09696323b5b9f13ff65e0641d535ed06ea8/coverage-7.13.5-cp314-cp314t-win_amd64.whl", hash = "sha256:301e3b7dfefecaca37c9f1aa6f0049b7d4ab8dd933742b607765d757aca77d43", size = 224254, upload-time = "2026-03-17T10:33:11.174Z" },
+    { url = "https://files.pythonhosted.org/packages/54/83/6acacc889de8987441aa7d5adfbdbf33d288dad28704a67e574f1df9bcbb/coverage-7.13.5-cp314-cp314t-win_arm64.whl", hash = "sha256:9dacc2ad679b292709e0f5fc1ac74a6d4d5562e424058962c7bb0c658ad25e45", size = 222276, upload-time = "2026-03-17T10:33:13.466Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/ee/a4cf96b8ce1e566ed238f0659ac2d3f007ed1d14b181bcb684e19561a69a/coverage-7.13.5-py3-none-any.whl", hash = "sha256:34b02417cf070e173989b3db962f7ed56d2f644307b2cf9d5a0f258e13084a61", size = 211346, upload-time = "2026-03-17T10:33:15.691Z" },
+]
+
+[package.optional-dependencies]
+toml = [
+    { name = "tomli", marker = "python_full_version <= '3.11'" },
+]
+
+[[package]]
+name = "cronsim"
+version = "2.7"
+source = { registry = "https://pypi.org/simple" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fb/1a/02f105147f7f2e06ed4f734ff5a6439590bb275a53dd91fc73df6312298a/cronsim-2.7-py3-none-any.whl", hash = "sha256:1e1431fa08c51dc7f72e67e571c7c7a09af26420169b607badd4ca9677ffad1e", size = 14213, upload-time = "2025-10-21T16:38:20.431Z" },
+]
+
+[[package]]
+name = "cryptography"
+version = "49.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cffi", marker = "platform_python_implementation != 'PyPy'" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/1f/99/d1c90d6041656cc6ee229dc99cd67fd0cd5aec3c5f7d72fffc27cc750054/cryptography-49.0.0.tar.gz", hash = "sha256:f89660a348f4f78a92366240a61404e337586ef7f5909a2fef59ca88ef505493", size = 854345, upload-time = "2026-06-12T20:02:30.512Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9b/22/adf66990e63584a68dfb50c24f48a125c07b1699899381c8151e63ed458c/cryptography-49.0.0-cp311-abi3-macosx_11_0_arm64.whl", hash = "sha256:966fe0e9c67490071f14c0d2b1cb2dfb3023c5ce39457343931415f08382f2db", size = 4032100, upload-time = "2026-06-12T20:02:32.143Z" },
+    { url = "https://files.pythonhosted.org/packages/09/41/3797cfaf69cae04a13ee78ebd83f0678d9c02b4779d21ce24445326f1a69/cryptography-49.0.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:36d1709f992593689b45bda411498d62c6e365f2ca00b84657d4dadd24de16db", size = 4692978, upload-time = "2026-06-12T20:01:21.305Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/8b/43011f7ebe515a8aa20d61f290a326cd890c2e738e16e59eaff8d9c3a412/cryptography-49.0.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:0e959b578856a3924bc0cbb710fc12c387b9412a951389f3ca61704a9e25f325", size = 4716422, upload-time = "2026-06-12T20:01:48.566Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/91/01ce7303a4579e6d3a6abef01bd322848e9ea7a219adcabc5048b9033571/cryptography-49.0.0-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:53ecee2e23f7169b6117e99fc8a944e5e50f79e69758a83b52a00cb98ab2b2d2", size = 4700503, upload-time = "2026-06-12T20:02:47.091Z" },
+    { url = "https://files.pythonhosted.org/packages/62/99/a2c95cf8293f07491e9e27c20cc4dcd18176d944e674679adeb1d0173fd6/cryptography-49.0.0-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:2eda353d8a27bcbcaa4cbed18994a74ab4d19a2ca897db188ea269ab9b71419b", size = 5309779, upload-time = "2026-06-12T20:02:08.987Z" },
+    { url = "https://files.pythonhosted.org/packages/20/2c/0622f20ff02b2ef32558733443805dc82fd4c275be01b2d19d14676f3a1b/cryptography-49.0.0-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:2afe9051da7ae7bd5905da5a949280c7d2bb75682e188f650a9d0f2756b834c6", size = 4749683, upload-time = "2026-06-12T20:02:03.335Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/5b/c5246635d5fd3b64e0d45ae10e99fd32fe9676a79915ccfe5a61ba9af1a5/cryptography-49.0.0-cp311-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:0b82e28ee398a386f0807bba7884d30f25218855690f45115831bcce5d90822c", size = 4337874, upload-time = "2026-06-12T20:02:54.323Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/88/05563c7fe2e914e87d1a536d06fe83e66b4e1d95cb593e05aea375531da8/cryptography-49.0.0-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:ccac2bfebc306b862133e3bb71f3f6ee8bb525240089b2d952e4144b3a6d5da7", size = 4700283, upload-time = "2026-06-12T20:01:34.822Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/b6/d7696e4e890d6ae1469935164c9e5215c557671cb78d6e3f458ccceaa632/cryptography-49.0.0-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:d0527ce944105f257f605a827d6ebead966c752038b6e8656abb9c5edee6fc68", size = 5265844, upload-time = "2026-06-12T20:01:24.09Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/3c/f3ad17eecc1a57b0ba236dc01f90e783c51f4a2f35f64777cc4f47a184b2/cryptography-49.0.0-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:cbc77da8c523d5abd028635ba850a6966fcee2c82e2bf65a41d1d8afe0f98be9", size = 4749290, upload-time = "2026-06-12T20:01:30.848Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/01/339573cf1023163a400b0b5d16f6d507de413b9f60be6fd1b77feeaf6737/cryptography-49.0.0-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:b87e65d263b3e5d3bb92a57e2a6638e2f31110fa7aa890c7b2dbba42248d0a3f", size = 4834612, upload-time = "2026-06-12T20:01:29.246Z" },
+    { url = "https://files.pythonhosted.org/packages/71/fd/577302e213a1be9468f92d1afef66fcf1ef83d516819d9992ca547f592bd/cryptography-49.0.0-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:66ec79c3904820572d7e987abdf304281f141d37ad9a489b8e97066e7b9b6459", size = 4980804, upload-time = "2026-06-12T20:01:42.853Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/09/f42b1d190c5ba75f72062a387f8030d1d75f6ab035788f1d9c4b01de6525/cryptography-49.0.0-cp311-abi3-win_amd64.whl", hash = "sha256:e5dfc1e64de5677cec922ffa8da89c546d0415bf6efdf081842e5d44c84e1f0e", size = 3810026, upload-time = "2026-06-12T20:02:39.262Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/9e/db72b3ae7fc9cfad53e630e56c6ae83b9b6ff0bf3718ffb8012d20b3aabf/cryptography-49.0.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:73a205dce83953d131a4aa1e0fd917a2fd1c5b1eef251e9d7152efefcbf5caf7", size = 4013892, upload-time = "2026-06-12T20:02:10.735Z" },
+    { url = "https://files.pythonhosted.org/packages/86/12/c48a424f38db03027be9f7ed5c7dc5de9933dbee992865f98b13727a009d/cryptography-49.0.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:196ecd6a36e4e9aa10270393bb98d8df88fccee0bf1e5128b91ae4eb4375896d", size = 4678835, upload-time = "2026-06-12T20:02:48.743Z" },
+    { url = "https://files.pythonhosted.org/packages/68/28/8a3ad4653662c93fc44dc4e5d8fd374c25c42e07b34bbfbadf49cf57a5a8/cryptography-49.0.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:7abcee80084cda3f7691f3eb1ce480d8df49cec637b429aa35986c1de71738aa", size = 4697239, upload-time = "2026-06-12T20:02:56.03Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/b2/2193fc74f81aee4f9b62733133b73b5176718932ed8f2e4b03fa040480a6/cryptography-49.0.0-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:4ae387c9cb68ea569ca17e490d66d8142b81c3cc814bf179974b7d146e490bbb", size = 4685593, upload-time = "2026-06-12T20:02:50.666Z" },
+    { url = "https://files.pythonhosted.org/packages/47/f1/1d3eaa243bfc5de4a187b22aa8c048b3e4980bfbe830ac46e6bac2e66947/cryptography-49.0.0-cp314-cp314t-manylinux_2_28_ppc64le.whl", hash = "sha256:f37d847238971164fdbc68ade6f6574aecc9c0af714190e2083429ff68f4ce9d", size = 5289961, upload-time = "2026-06-12T20:01:46.468Z" },
+    { url = "https://files.pythonhosted.org/packages/58/39/2d51306721330c486495853eda1c567880ff036de15a14c4b74f399934af/cryptography-49.0.0-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:c2bc30226390d60ea19d9f82b19db005fe0452154a23c1c410c12ea801e43561", size = 4731145, upload-time = "2026-06-12T20:02:16.832Z" },
+    { url = "https://files.pythonhosted.org/packages/17/50/983e838c7fd0d87fd8c969bcdd328edaf5f756e38df5281637424c155873/cryptography-49.0.0-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:07cab27cc7b7e0fd28e5e26bb9eeedde5c135c868b46de4a27845abe94af6122", size = 4321719, upload-time = "2026-06-12T20:02:52.611Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/f5/8f571d7e27c55bce9f76f026143bcb1e040a4233149ecca0bea5fa5dd5f7/cryptography-49.0.0-cp314-cp314t-manylinux_2_34_aarch64.whl", hash = "sha256:b20133d204d2bb56ba047642199603876c872026ca53e79c35b83772ab2cc505", size = 4685209, upload-time = "2026-06-12T20:02:07.282Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/84/0e27016a6fc5a0886f797018b26aa42f40c09a82332bff77822a451deaaa/cryptography-49.0.0-cp314-cp314t-manylinux_2_34_ppc64le.whl", hash = "sha256:b970c6da94d5bb18629db453d14f2a1300f6bf59b61e9b82377931ef95504866", size = 5246285, upload-time = "2026-06-12T20:01:32.439Z" },
+    { url = "https://files.pythonhosted.org/packages/11/2d/5e1fb307cb5931881516b464c98774b3f2c36b5d4bb9a2830253cf553cad/cryptography-49.0.0-cp314-cp314t-manylinux_2_34_x86_64.whl", hash = "sha256:d8ecde755e2e91bf773fc94e8c9d730cd7f2007004cb492263a794ec3899a1c8", size = 4730441, upload-time = "2026-06-12T20:02:01.469Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/c0/bff5a02ee731d207d6a1ed51732549d8c53d2bc8da1d10ec6f2844201d68/cryptography-49.0.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:e3fb64c420688e5319ae25113a354015abbd8dffbfbc41781a1ea66fc7622ac3", size = 4815869, upload-time = "2026-06-12T20:01:36.574Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/26/814681d14248d95d73d5c3eea0c39a94eb8302df966f670a2c60de90974b/cryptography-49.0.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:32703d93296f5c1f4b53349ad3a250c2cae0fdecd3a3dd5d47e616d8d616af27", size = 4960948, upload-time = "2026-06-12T20:02:18.688Z" },
+    { url = "https://files.pythonhosted.org/packages/4c/fe/93ecac273d3738939d023612ad12cca9a3740a5345d69fda04134c43fd96/cryptography-49.0.0-cp314-cp314t-win_amd64.whl", hash = "sha256:33cd0565932807baddb67b96dbee92f2c374b5c89dee09fd74079aeb8c8dba61", size = 3799153, upload-time = "2026-06-12T20:01:39.059Z" },
+    { url = "https://files.pythonhosted.org/packages/19/2a/5bb823f5bedcf80718cea7fbc95ec5515cca3769633c4b01a32be7f30e7c/cryptography-49.0.0-cp39-abi3-macosx_11_0_arm64.whl", hash = "sha256:ec5e529fb80935c94fe7b729f9972b50e351a0e6b50aa294fd5cabb109fcc29a", size = 4025947, upload-time = "2026-06-12T20:01:25.745Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/df/40577043ca124e17012f408ddddaeb213b856336ac82ddb3bc915f39e29f/cryptography-49.0.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:f78ff2c9ed8dc2d036b0f4d640e22522213d047c1b14e61205a7e55c80a494d4", size = 4692429, upload-time = "2026-06-12T20:01:53.628Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/99/2d13299eb3dd27b02dcfaafcc91d6b5cb3329f7cbd6d8f51921acd566c1a/cryptography-49.0.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:35b151772baff2c74cba7fa290ceaff4c3b11c0c881eb93eb5dbc05a7cfbba18", size = 4700968, upload-time = "2026-06-12T20:02:45.383Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/4d/9c0cd02f95e2602dd5e563da149ee0830abef3537be8b34dc56281ebe27a/cryptography-49.0.0-cp39-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:0f21641cf4b30fca7aee061ced0ec7ad7b073518088b7c9969a297c0ae796c69", size = 4697758, upload-time = "2026-06-12T20:01:41.13Z" },
+    { url = "https://files.pythonhosted.org/packages/24/01/186c825898477d77e2324d5360fefe622ff1d8d1963ec0554e2cada8ec77/cryptography-49.0.0-cp39-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:9e82dcc8e56052715fb18b2429e3bca4823b1629136a2084fc45a9a5cecb9b64", size = 5298863, upload-time = "2026-06-12T20:02:24.579Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/7b/62cbbab75d0659865bf0273790031544a0b16c8072d258f9428dcd8190dc/cryptography-49.0.0-cp39-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:6f2debedf9ca60cf1d5bd466475638af5130f89965605cd818484d19987d3a21", size = 4735983, upload-time = "2026-06-12T20:01:50.14Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/72/3e798c064bc39e471008075d0f9bc9daf77a80879c092e4a8e170c585ed4/cryptography-49.0.0-cp39-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:8c25ceb16df5b9435f3f6a9829204985b0e0cbee3b48aacd432c7d2c850b44d9", size = 4334173, upload-time = "2026-06-12T20:01:44.743Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/ee/6fca21d1ac73e06f8bef71940abfd4d2f6472b4bca284d770f32bd4086f6/cryptography-49.0.0-cp39-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:28d8b15e6275f12c8a207dc309dfa957903c927d08d0cc937ee3f63f200693cc", size = 4697298, upload-time = "2026-06-12T20:02:20.918Z" },
+    { url = "https://files.pythonhosted.org/packages/67/d0/a5fcd3515f0bae49a7b6d0413cc1bdccdcc1fc0047037a0d480642cdc5d6/cryptography-49.0.0-cp39-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:6fc361c34fb6aac015ce19435876635e5c6d21db31998b0920f675f131e043b8", size = 5254338, upload-time = "2026-06-12T20:02:22.737Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/84/84fe36f19caf857d61cb7fc9c63035a47ffabd84ea12d1d393148efa3615/cryptography-49.0.0-cp39-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:2400ef9c9e2299a25614eb1dea3db54a69b1349efd043bfac9c67630d136df36", size = 4735650, upload-time = "2026-06-12T20:02:41.389Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/a0/db537264e234f7273a73ec020873d6d6b39dfd8a53db78b550ca8320440e/cryptography-49.0.0-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:67e1d20ad9ef3a563c59ef22e7a8a0b8210bd26604369ea4a30a7c66aefe504e", size = 4834820, upload-time = "2026-06-12T20:01:51.847Z" },
+    { url = "https://files.pythonhosted.org/packages/93/77/8df9eb486495979bccecd1062e2eaf435250e84437040295b57d09048b0b/cryptography-49.0.0-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:42b0684e0e40cf26122427802486f6d93aea593612603a94fbf260c7eb1e9c1b", size = 4967968, upload-time = "2026-06-12T20:02:12.524Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/e6/f60198ea8d9dfa15fff9ed4ca02ce362f6eadd9ba757dcc50634c4257b63/cryptography-49.0.0-cp39-abi3-win_amd64.whl", hash = "sha256:026ac7423e6fa66872d3bf889be5974507da3944f866f704fa200eadacd00001", size = 3785547, upload-time = "2026-06-12T20:02:26.847Z" },
+    { url = "https://files.pythonhosted.org/packages/63/d3/4a83af35d65e3fad632c926fad684c193ea4398569ccb0bbbc7fe8f5dc9a/cryptography-49.0.0-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:fc1e275c2f1d97b1a6450b8b0ea3ebfa6e087a611c2b26cb2404d48588abab7b", size = 3993685, upload-time = "2026-06-12T20:02:14.883Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/a7/f9dac0ab7f80368c56993a7bf638ef9935f825c91902798481fac0898138/cryptography-49.0.0-pp311-pypy311_pp73-manylinux_2_28_aarch64.whl", hash = "sha256:c83782480a4a9da4d0feb51950131ba32e12e70813848b3343f6e18c28a66838", size = 4676239, upload-time = "2026-06-12T20:02:28.793Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/70/2ba3769dd0ae167e2f33dfa9592d45db6ff9a61d62ca1a5b3d1bdd09068f/cryptography-49.0.0-pp311-pypy311_pp73-manylinux_2_28_x86_64.whl", hash = "sha256:b39efa323140595abd3ecca8529d321ae50f55f3aa3ba9cc81ea56a6011953d5", size = 4715584, upload-time = "2026-06-12T20:01:27.495Z" },
+    { url = "https://files.pythonhosted.org/packages/94/64/2923570ac1c0bd3a737aa366ac3abbbbde273042308b8cde95e2364a6e6a/cryptography-49.0.0-pp311-pypy311_pp73-manylinux_2_34_aarch64.whl", hash = "sha256:b47db11c2c3525083296069b98ac5221907455e989ae0c2e3008bde851921615", size = 4675885, upload-time = "2026-06-12T20:01:55.49Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/f8/614dc7e051418cfe53d55173c1e24c6b0085e89996fe90508c2fdf769aef/cryptography-49.0.0-pp311-pypy311_pp73-manylinux_2_34_x86_64.whl", hash = "sha256:084ef1af862eb07ec46d25f68689f2102a9fc0e05ce7b80f14f5fe51e4eef0f6", size = 4715449, upload-time = "2026-06-12T20:02:05.469Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/50/a9caea39ad19c431c1a3f8a31114df65b260cdfe67786b6c7e7c040c4c44/cryptography-49.0.0-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:be9fcb48a55f023493482827d4f459bd263cc20efde64f204b97c123201850c6", size = 3783731, upload-time = "2026-06-12T20:02:43.319Z" },
+]
+
+[[package]]
+name = "cyclopts"
+version = "4.10.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "attrs" },
+    { name = "docstring-parser" },
+    { name = "rich" },
+    { name = "rich-rst" },
+    { name = "tomli", marker = "python_full_version < '3.11'" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/6c/c4/2ce2ca1451487dc7d59f09334c3fa1182c46cfcf0a2d5f19f9b26d53ac74/cyclopts-4.10.1.tar.gz", hash = "sha256:ad4e4bb90576412d32276b14a76f55d43353753d16217f2c3cd5bdceba7f15a0", size = 166623, upload-time = "2026-03-23T14:43:01.098Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8a/0b/2261922126b2e50c601fe22d7ff5194e0a4d50e654836260c0665e24d862/cyclopts-4.10.1-py3-none-any.whl", hash = "sha256:35f37257139380a386d9fe4475e1e7c87ca7795765ef4f31abba579fcfcb6ecd", size = 204331, upload-time = "2026-03-23T14:43:02.625Z" },
+]
+
+[[package]]
+name = "decorator"
+version = "5.2.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/43/fa/6d96a0978d19e17b68d634497769987b16c8f4cd0a7a05048bec693caa6b/decorator-5.2.1.tar.gz", hash = "sha256:65f266143752f734b0a7cc83c46f4618af75b8c5911b00ccb61d0ac9b6da0360", size = 56711, upload-time = "2025-02-24T04:41:34.073Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/4e/8c/f3147f5c4b73e7550fe5f9352eaa956ae838d5c51eb58e7a25b9f3e2643b/decorator-5.2.1-py3-none-any.whl", hash = "sha256:d316bb415a2d9e2d2b3abcc4084c6502fc09240e292cd76a76afc106a1c8e04a", size = 9190, upload-time = "2025-02-24T04:41:32.565Z" },
+]
+
+[[package]]
+name = "dirty-equals"
+version = "0.11"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/30/1d/c5913ac9d6615515a00f4bdc71356d302437cb74ff2e9aaccd3c14493b78/dirty_equals-0.11.tar.gz", hash = "sha256:f4ac74ee88f2d11e2fa0f65eb30ee4f07105c5f86f4dc92b09eb1138775027c3", size = 128067, upload-time = "2025-11-17T01:51:24.451Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/bb/8d/dbff05239043271dbeace563a7686212a3dd517864a35623fe4d4a64ca19/dirty_equals-0.11-py3-none-any.whl", hash = "sha256:b1d7093273fc2f9be12f443a8ead954ef6daaf6746fd42ef3a5616433ee85286", size = 28051, upload-time = "2025-11-17T01:51:22.849Z" },
+]
+
+[[package]]
+name = "distro"
+version = "1.9.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/fc/f8/98eea607f65de6527f8a2e8885fc8015d3e6f5775df186e443e0964a11c3/distro-1.9.0.tar.gz", hash = "sha256:2fa77c6fd8940f116ee1d6b94a2f90b13b5ea8d019b98bc8bafdcabcdd9bdbed", size = 60722, upload-time = "2023-12-24T09:54:32.31Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/12/b3/231ffd4ab1fc9d679809f356cebee130ac7daa00d6d6f3206dd4fd137e9e/distro-1.9.0-py3-none-any.whl", hash = "sha256:7bffd925d65168f85027d8da9af6bddab658135b840670a223589bc0c8ef02b2", size = 20277, upload-time = "2023-12-24T09:54:30.421Z" },
+]
+
+[[package]]
+name = "dnspython"
+version = "2.8.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/8c/8b/57666417c0f90f08bcafa776861060426765fdb422eb10212086fb811d26/dnspython-2.8.0.tar.gz", hash = "sha256:181d3c6996452cb1189c4046c61599b84a5a86e099562ffde77d26984ff26d0f", size = 368251, upload-time = "2025-09-07T18:58:00.022Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ba/5a/18ad964b0086c6e62e2e7500f7edc89e3faa45033c71c1893d34eed2b2de/dnspython-2.8.0-py3-none-any.whl", hash = "sha256:01d9bbc4a2d76bf0db7c1f729812ded6d912bd318d3b1cf81d30c0f845dbf3af", size = 331094, upload-time = "2025-09-07T18:57:58.071Z" },
+]
+
+[[package]]
+name = "docstring-parser"
+version = "0.17.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b2/9d/c3b43da9515bd270df0f80548d9944e389870713cc1fe2b8fb35fe2bcefd/docstring_parser-0.17.0.tar.gz", hash = "sha256:583de4a309722b3315439bb31d64ba3eebada841f2e2cee23b99df001434c912", size = 27442, upload-time = "2025-07-21T07:35:01.868Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/55/e2/2537ebcff11c1ee1ff17d8d0b6f4db75873e3b0fb32c2d4a2ee31ecb310a/docstring_parser-0.17.0-py3-none-any.whl", hash = "sha256:cf2569abd23dce8099b300f9b4fa8191e9582dda731fd533daf54c4551658708", size = 36896, upload-time = "2025-07-21T07:35:00.684Z" },
+]
+
+[[package]]
+name = "docutils"
+version = "0.22.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ae/b6/03bb70946330e88ffec97aefd3ea75ba575cb2e762061e0e62a213befee8/docutils-0.22.4.tar.gz", hash = "sha256:4db53b1fde9abecbb74d91230d32ab626d94f6badfc575d6db9194a49df29968", size = 2291750, upload-time = "2025-12-18T19:00:26.443Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/02/10/5da547df7a391dcde17f59520a231527b8571e6f46fc8efb02ccb370ab12/docutils-0.22.4-py3-none-any.whl", hash = "sha256:d0013f540772d1420576855455d050a2180186c91c15779301ac2ccb3eeb68de", size = 633196, upload-time = "2025-12-18T19:00:18.077Z" },
+]
+
+[[package]]
+name = "email-validator"
+version = "2.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "dnspython" },
+    { name = "idna" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f5/22/900cb125c76b7aaa450ce02fd727f452243f2e91a61af068b40adba60ea9/email_validator-2.3.0.tar.gz", hash = "sha256:9fc05c37f2f6cf439ff414f8fc46d917929974a82244c20eb10231ba60c54426", size = 51238, upload-time = "2025-08-26T13:09:06.831Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/de/15/545e2b6cf2e3be84bc1ed85613edd75b8aea69807a71c26f4ca6a9258e82/email_validator-2.3.0-py3-none-any.whl", hash = "sha256:80f13f623413e6b197ae73bb10bf4eb0908faf509ad8362c5edeb0be7fd450b4", size = 35604, upload-time = "2025-08-26T13:09:05.858Z" },
+]
+
+[[package]]
+name = "exceptiongroup"
+version = "1.3.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8a/0e/97c33bf5009bdbac74fd2beace167cab3f978feb69cc36f1ef79360d6c4e/exceptiongroup-1.3.1-py3-none-any.whl", hash = "sha256:a7a39a3bd276781e98394987d3a5701d0c4edffb633bb7a5144577f82c773598", size = 16740, upload-time = "2025-11-21T23:01:53.443Z" },
+]
+
+[[package]]
+name = "execnet"
+version = "2.1.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/bf/89/780e11f9588d9e7128a3f87788354c7946a9cbb1401ad38a48c4db9a4f07/execnet-2.1.2.tar.gz", hash = "sha256:63d83bfdd9a23e35b9c6a3261412324f964c2ec8dcd8d3c6916ee9373e0befcd", size = 166622, upload-time = "2025-11-12T09:56:37.75Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ab/84/02fc1827e8cdded4aa65baef11296a9bbe595c474f0d6d758af082d849fd/execnet-2.1.2-py3-none-any.whl", hash = "sha256:67fba928dd5a544b783f6056f449e5e3931a5c378b128bc18501f7ea79e296ec", size = 40708, upload-time = "2025-11-12T09:56:36.333Z" },
+]
+
+[[package]]
+name = "executing"
+version = "2.2.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/cc/28/c14e053b6762b1044f34a13aab6859bbf40456d37d23aa286ac24cfd9a5d/executing-2.2.1.tar.gz", hash = "sha256:3632cc370565f6648cc328b32435bd120a1e4ebb20c77e3fdde9a13cd1e533c4", size = 1129488, upload-time = "2025-09-01T09:48:10.866Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c1/ea/53f2148663b321f21b5a606bd5f191517cf40b7072c0497d3c92c4a13b1e/executing-2.2.1-py2.py3-none-any.whl", hash = "sha256:760643d3452b4d777d295bb167ccc74c64a81df23fb5e08eff250c425a4b2017", size = 28317, upload-time = "2025-09-01T09:48:08.5Z" },
+]
+
+[[package]]
+name = "fancycompleter"
+version = "0.11.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pyreadline3", marker = "python_full_version < '3.13' and sys_platform == 'win32'" },
+    { name = "pyrepl", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/4e/4c/d11187dee93eff89d082afda79b63c79320ae1347e49485a38f05ad359d0/fancycompleter-0.11.1.tar.gz", hash = "sha256:5b4ad65d76b32b1259251516d0f1cb2d82832b1ff8506697a707284780757f69", size = 341776, upload-time = "2025-05-26T12:59:11.045Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/30/c3/6f0e3896f193528bbd2b4d2122d4be8108a37efab0b8475855556a8c4afa/fancycompleter-0.11.1-py3-none-any.whl", hash = "sha256:44243d7fab37087208ca5acacf8f74c0aa4d733d04d593857873af7513cdf8a6", size = 11207, upload-time = "2025-05-26T12:59:09.857Z" },
+]
+
+[[package]]
+name = "fastapi"
+version = "0.135.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "annotated-doc" },
+    { name = "pydantic" },
+    { name = "starlette" },
+    { name = "typing-extensions" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c4/73/5903c4b13beae98618d64eb9870c3fac4f605523dd0312ca5c80dadbd5b9/fastapi-0.135.2.tar.gz", hash = "sha256:88a832095359755527b7f63bb4c6bc9edb8329a026189eed83d6c1afcf419d56", size = 395833, upload-time = "2026-03-23T14:12:41.697Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8f/ea/18f6d0457f9efb2fc6fa594857f92810cadb03024975726db6546b3d6fcf/fastapi-0.135.2-py3-none-any.whl", hash = "sha256:0af0447d541867e8db2a6a25c23a8c4bd80e2394ac5529bd87501bbb9e240ca5", size = 117407, upload-time = "2026-03-23T14:12:43.284Z" },
+]
+
+[[package]]
+name = "fastmcp"
+source = { editable = "." }
+dependencies = [
+    { name = "fastmcp-slim", extra = ["client", "server"] },
+]
+
+[package.optional-dependencies]
+anthropic = [
+    { name = "fastmcp-slim", extra = ["anthropic"] },
+]
+apps = [
+    { name = "fastmcp-slim", extra = ["apps"] },
+]
+azure = [
+    { name = "fastmcp-slim", extra = ["azure"] },
+]
+code-mode = [
+    { name = "fastmcp-slim", extra = ["code-mode"] },
+]
+gemini = [
+    { name = "fastmcp-slim", extra = ["gemini"] },
+]
+openai = [
+    { name = "fastmcp-slim", extra = ["openai"] },
+]
+tasks = [
+    { name = "fastmcp-slim", extra = ["tasks"] },
+]
+
+[package.dev-dependencies]
+dev = [
+    { name = "dirty-equals" },
+    { name = "fastapi" },
+    { name = "fastmcp", extra = ["anthropic", "apps", "azure", "code-mode", "gemini", "openai", "tasks"] },
+    { name = "fastmcp-remote" },
+    { name = "inline-snapshot", extra = ["dirty-equals"] },
+    { name = "ipython", version = "8.39.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "ipython", version = "9.10.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.11.*'" },
+    { name = "ipython", version = "9.12.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" },
+    { name = "loq" },
+    { name = "opentelemetry-exporter-otlp-proto-grpc" },
+    { name = "opentelemetry-sdk" },
+    { name = "pdbpp" },
+    { name = "prek" },
+    { name = "psutil" },
+    { name = "pyinstrument" },
+    { name = "pyperclip" },
+    { name = "pytest" },
+    { name = "pytest-asyncio" },
+    { name = "pytest-cov" },
+    { name = "pytest-env" },
+    { name = "pytest-examples" },
+    { name = "pytest-flakefinder" },
+    { name = "pytest-httpx" },
+    { name = "pytest-report" },
+    { name = "pytest-retry" },
+    { name = "pytest-timeout" },
+    { name = "pytest-xdist" },
+    { name = "ruff" },
+    { name = "ty" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "fastmcp-slim", extras = ["anthropic"], marker = "extra == 'anthropic'", editable = "fastmcp_slim" },
+    { name = "fastmcp-slim", extras = ["apps"], marker = "extra == 'apps'", editable = "fastmcp_slim" },
+    { name = "fastmcp-slim", extras = ["azure"], marker = "extra == 'azure'", editable = "fastmcp_slim" },
+    { name = "fastmcp-slim", extras = ["client", "server"], editable = "fastmcp_slim" },
+    { name = "fastmcp-slim", extras = ["code-mode"], marker = "extra == 'code-mode'", editable = "fastmcp_slim" },
+    { name = "fastmcp-slim", extras = ["gemini"], marker = "extra == 'gemini'", editable = "fastmcp_slim" },
+    { name = "fastmcp-slim", extras = ["openai"], marker = "extra == 'openai'", editable = "fastmcp_slim" },
+    { name = "fastmcp-slim", extras = ["tasks"], marker = "extra == 'tasks'", editable = "fastmcp_slim" },
+]
+provides-extras = ["anthropic", "apps", "azure", "code-mode", "gemini", "openai", "tasks"]
+
+[package.metadata.requires-dev]
+dev = [
+    { name = "dirty-equals", specifier = ">=0.9.0" },
+    { name = "fastapi", specifier = ">=0.115.12" },
+    { name = "fastmcp", extras = ["anthropic", "apps", "azure", "code-mode", "gemini", "openai", "tasks"], editable = "." },
+    { name = "fastmcp-remote", editable = "fastmcp_remote" },
+    { name = "inline-snapshot", extras = ["dirty-equals"], specifier = ">=0.27.2" },
+    { name = "ipython", specifier = ">=8.12.3" },
+    { name = "loq", specifier = ">=0.1.0a3" },
+    { name = "opentelemetry-exporter-otlp-proto-grpc", specifier = ">=1.39.0" },
+    { name = "opentelemetry-sdk", specifier = ">=1.20.0" },
+    { name = "pdbpp", specifier = ">=0.11.7" },
+    { name = "prek", specifier = ">=0.2.12" },
+    { name = "psutil", specifier = ">=7.0.0" },
+    { name = "pyinstrument", specifier = ">=5.0.2" },
+    { name = "pyperclip", specifier = ">=1.9.0" },
+    { name = "pytest", specifier = ">=8.3.3" },
+    { name = "pytest-asyncio", specifier = ">=1.2.0" },
+    { name = "pytest-cov", specifier = ">=6.1.1" },
+    { name = "pytest-env", specifier = ">=1.1.5" },
+    { name = "pytest-examples", specifier = ">=0.0.18" },
+    { name = "pytest-flakefinder", specifier = ">=1.1.0" },
+    { name = "pytest-httpx", specifier = ">=0.35.0" },
+    { name = "pytest-report", specifier = ">=0.2.1" },
+    { name = "pytest-retry", specifier = ">=1.7.0" },
+    { name = "pytest-timeout", specifier = ">=2.4.0" },
+    { name = "pytest-xdist", specifier = ">=3.6.1" },
+    { name = "ruff", specifier = ">=0.12.8" },
+    { name = "ty", specifier = ">=0.0.55" },
+]
+
+[[package]]
+name = "fastmcp-remote"
+source = { editable = "fastmcp_remote" }
+dependencies = [
+    { name = "fastmcp-slim", extra = ["client", "server"] },
+]
+
+[package.metadata]
+requires-dist = [{ name = "fastmcp-slim", extras = ["client", "server"], editable = "fastmcp_slim" }]
+
+[[package]]
+name = "fastmcp-slim"
+source = { editable = "fastmcp_slim" }
+dependencies = [
+    { name = "mcp-types" },
+    { name = "platformdirs" },
+    { name = "pydantic", extra = ["email"] },
+    { name = "pydantic-settings" },
+    { name = "python-dotenv" },
+    { name = "rich" },
+    { name = "typing-extensions" },
+]
+
+[package.optional-dependencies]
+anthropic = [
+    { name = "anthropic" },
+]
+apps = [
+    { name = "prefab-ui" },
+]
+azure = [
+    { name = "azure-identity" },
+    { name = "pyjwt" },
+]
+client = [
+    { name = "authlib" },
+    { name = "exceptiongroup" },
+    { name = "httpx" },
+    { name = "mcp" },
+    { name = "opentelemetry-api" },
+    { name = "py-key-value-aio", extra = ["filetree", "keyring", "memory"] },
+    { name = "starlette" },
+]
+code-mode = [
+    { name = "pydantic-monty" },
+]
+gemini = [
+    { name = "google-genai" },
+    { name = "jsonref" },
+]
+mcp = [
+    { name = "exceptiongroup" },
+    { name = "httpx" },
+    { name = "mcp" },
+    { name = "opentelemetry-api" },
+    { name = "starlette" },
+]
+openai = [
+    { name = "openai" },
+]
+server = [
+    { name = "authlib" },
+    { name = "cyclopts" },
+    { name = "exceptiongroup" },
+    { name = "griffelib" },
+    { name = "httpx" },
+    { name = "joserfc" },
+    { name = "jsonref" },
+    { name = "jsonschema-path" },
+    { name = "mcp" },
+    { name = "openapi-pydantic" },
+    { name = "opentelemetry-api" },
+    { name = "packaging" },
+    { name = "py-key-value-aio", extra = ["filetree", "keyring", "memory"] },
+    { name = "pyperclip" },
+    { name = "python-multipart" },
+    { name = "pyyaml" },
+    { name = "starlette" },
+    { name = "uncalled-for" },
+    { name = "uvicorn" },
+    { name = "watchfiles" },
+    { name = "websockets" },
+]
+tasks = [
+    { name = "pydocket" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "anthropic", marker = "extra == 'anthropic'", specifier = ">=0.48.0" },
+    { name = "authlib", marker = "extra == 'client'", specifier = ">=1.6.11" },
+    { name = "authlib", marker = "extra == 'server'", specifier = ">=1.6.11" },
+    { name = "azure-identity", marker = "extra == 'azure'", specifier = ">=1.16.0" },
+    { name = "cyclopts", marker = "extra == 'server'", specifier = ">=4.0.0" },
+    { name = "exceptiongroup", marker = "extra == 'client'", specifier = ">=1.2.2" },
+    { name = "exceptiongroup", marker = "extra == 'mcp'", specifier = ">=1.2.2" },
+    { name = "exceptiongroup", marker = "extra == 'server'", specifier = ">=1.2.2" },
+    { name = "google-genai", marker = "extra == 'gemini'", specifier = ">=1.18.0" },
+    { name = "griffelib", marker = "extra == 'server'", specifier = ">=2.0.0" },
+    { name = "httpx", marker = "extra == 'client'", specifier = ">=0.28.1,<1.0" },
+    { name = "httpx", marker = "extra == 'mcp'", specifier = ">=0.28.1,<1.0" },
+    { name = "httpx", marker = "extra == 'server'", specifier = ">=0.28.1,<1.0" },
+    { name = "joserfc", marker = "extra == 'server'", specifier = ">=1.1.0" },
+    { name = "jsonref", marker = "extra == 'gemini'", specifier = ">=1.1.0" },
+    { name = "jsonref", marker = "extra == 'server'", specifier = ">=1.1.0" },
+    { name = "jsonschema-path", marker = "extra == 'server'", specifier = ">=0.3.4" },
+    { name = "mcp", marker = "extra == 'client'", specifier = "==2.0.0b1" },
+    { name = "mcp", marker = "extra == 'mcp'", specifier = "==2.0.0b1" },
+    { name = "mcp", marker = "extra == 'server'", specifier = "==2.0.0b1" },
+    { name = "mcp-types", specifier = "==2.0.0b1" },
+    { name = "openai", marker = "extra == 'openai'", specifier = ">=1.102.0" },
+    { name = "openapi-pydantic", marker = "extra == 'server'", specifier = ">=0.5.1" },
+    { name = "opentelemetry-api", marker = "extra == 'client'", specifier = ">=1.28.0" },
+    { name = "opentelemetry-api", marker = "extra == 'mcp'", specifier = ">=1.28.0" },
+    { name = "opentelemetry-api", marker = "extra == 'server'", specifier = ">=1.28.0" },
+    { name = "packaging", marker = "extra == 'server'", specifier = ">=24.0" },
+    { name = "platformdirs", specifier = ">=4.0.0" },
+    { name = "prefab-ui", marker = "extra == 'apps'", specifier = ">=0.18.0" },
+    { name = "py-key-value-aio", extras = ["filetree", "keyring", "memory"], marker = "extra == 'client'", specifier = ">=0.4.4,<0.5.0" },
+    { name = "py-key-value-aio", extras = ["filetree", "keyring", "memory"], marker = "extra == 'server'", specifier = ">=0.4.4,<0.5.0" },
+    { name = "pydantic", extras = ["email"], specifier = ">=2.12.0" },
+    { name = "pydantic-monty", marker = "extra == 'code-mode'", specifier = "==0.0.17" },
+    { name = "pydantic-settings", specifier = ">=2.0.0" },
+    { name = "pydocket", marker = "extra == 'tasks'", specifier = ">=0.20.0" },
+    { name = "pyjwt", marker = "extra == 'azure'", specifier = ">=2.12.0" },
+    { name = "pyperclip", marker = "extra == 'server'", specifier = ">=1.9.0" },
+    { name = "python-dotenv", specifier = ">=1.1.0" },
+    { name = "python-multipart", marker = "extra == 'server'", specifier = ">=0.0.26" },
+    { name = "pyyaml", marker = "extra == 'server'", specifier = ">=6.0,<7.0" },
+    { name = "rich", specifier = ">=13.9.4" },
+    { name = "starlette", marker = "extra == 'client'", specifier = ">=1.0.1" },
+    { name = "starlette", marker = "extra == 'mcp'", specifier = ">=1.0.1" },
+    { name = "starlette", marker = "extra == 'server'", specifier = ">=1.0.1" },
+    { name = "typing-extensions", specifier = ">=4.0.0" },
+    { name = "uncalled-for", marker = "extra == 'server'", specifier = ">=0.2.0" },
+    { name = "uvicorn", marker = "extra == 'server'", specifier = ">=0.35" },
+    { name = "watchfiles", marker = "extra == 'server'", specifier = ">=1.0.0" },
+    { name = "websockets", marker = "extra == 'server'", specifier = ">=15.0.1" },
+]
+provides-extras = ["anthropic", "apps", "azure", "client", "code-mode", "gemini", "mcp", "openai", "server", "tasks"]
+
+[[package]]
+name = "google-auth"
+version = "2.49.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cryptography" },
+    { name = "pyasn1-modules" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ea/80/6a696a07d3d3b0a92488933532f03dbefa4a24ab80fb231395b9a2a1be77/google_auth-2.49.1.tar.gz", hash = "sha256:16d40da1c3c5a0533f57d268fe72e0ebb0ae1cc3b567024122651c045d879b64", size = 333825, upload-time = "2026-03-12T19:30:58.135Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e9/eb/c6c2478d8a8d633460be40e2a8a6f8f429171997a35a96f81d3b680dec83/google_auth-2.49.1-py3-none-any.whl", hash = "sha256:195ebe3dca18eddd1b3db5edc5189b76c13e96f29e73043b923ebcf3f1a860f7", size = 240737, upload-time = "2026-03-12T19:30:53.159Z" },
+]
+
+[package.optional-dependencies]
+requests = [
+    { name = "requests" },
+]
+
+[[package]]
+name = "google-genai"
+version = "1.69.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "distro" },
+    { name = "google-auth", extra = ["requests"] },
+    { name = "httpx" },
+    { name = "pydantic" },
+    { name = "requests" },
+    { name = "sniffio" },
+    { name = "tenacity" },
+    { name = "typing-extensions" },
+    { name = "websockets" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/00/5e/c0a5e6ff60d18d3f19819a9b1fbd6a1ef2162d025696d8660550739168dc/google_genai-1.69.0.tar.gz", hash = "sha256:5f1a6a478e0c5851506a3d337534bab27b3c33120e27bf9174507ea79dfb8673", size = 519538, upload-time = "2026-03-28T15:33:27.308Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/42/58/ef0586019f54b2ebb36deed7608ccb5efe1377564d2aaea6b1e295d1fadc/google_genai-1.69.0-py3-none-any.whl", hash = "sha256:252e714d724aba74949647b9de511a6a6f7804b3b317ab39ddee9cc2f001cacc", size = 760551, upload-time = "2026-03-28T15:33:24.957Z" },
+]
+
+[[package]]
+name = "googleapis-common-protos"
+version = "1.73.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "protobuf" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a1/c0/4a54c386282c13449eca8bbe2ddb518181dc113e78d240458a68856b4d69/googleapis_common_protos-1.73.1.tar.gz", hash = "sha256:13114f0e9d2391756a0194c3a8131974ed7bffb06086569ba193364af59163b6", size = 147506, upload-time = "2026-03-26T22:17:38.451Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/dc/82/fcb6520612bec0c39b973a6c0954b6a0d948aadfe8f7e9487f60ceb8bfa6/googleapis_common_protos-1.73.1-py3-none-any.whl", hash = "sha256:e51f09eb0a43a8602f5a915870972e6b4a394088415c79d79605a46d8e826ee8", size = 297556, upload-time = "2026-03-26T22:15:58.455Z" },
+]
+
+[[package]]
+name = "griffelib"
+version = "2.0.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/9d/82/74f4a3310cdabfbb10da554c3a672847f1ed33c6f61dd472681ce7f1fe67/griffelib-2.0.2.tar.gz", hash = "sha256:3cf20b3bc470e83763ffbf236e0076b1211bac1bc67de13daf494640f2de707e", size = 166461, upload-time = "2026-03-27T11:34:51.091Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/11/8c/c9138d881c79aa0ea9ed83cbd58d5ca75624378b38cee225dcf5c42cc91f/griffelib-2.0.2-py3-none-any.whl", hash = "sha256:925c857658fb1ba40c0772c37acbc2ab650bd794d9c1b9726922e36ea4117ea1", size = 142357, upload-time = "2026-03-27T11:34:46.275Z" },
+]
+
+[[package]]
+name = "grpcio"
+version = "1.78.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/8a/3d098f35c143a89520e568e6539cc098fcd294495910e359889ce8741c84/grpcio-1.78.0.tar.gz", hash = "sha256:7382b95189546f375c174f53a5fa873cef91c4b8005faa05cc5b3beea9c4f1c5", size = 12852416, upload-time = "2026-02-06T09:57:18.093Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/5a/a8/690a085b4d1fe066130de97a87de32c45062cf2ecd218df9675add895550/grpcio-1.78.0-cp310-cp310-linux_armv7l.whl", hash = "sha256:7cc47943d524ee0096f973e1081cb8f4f17a4615f2116882a5f1416e4cfe92b5", size = 5946986, upload-time = "2026-02-06T09:54:34.043Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/1b/e5213c5c0ced9d2d92778d30529ad5bb2dcfb6c48c4e2d01b1f302d33d64/grpcio-1.78.0-cp310-cp310-macosx_11_0_universal2.whl", hash = "sha256:c3f293fdc675ccba4db5a561048cca627b5e7bd1c8a6973ffedabe7d116e22e2", size = 11816533, upload-time = "2026-02-06T09:54:37.04Z" },
+    { url = "https://files.pythonhosted.org/packages/18/37/1ba32dccf0a324cc5ace744c44331e300b000a924bf14840f948c559ede7/grpcio-1.78.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:10a9a644b5dd5aec3b82b5b0b90d41c0fa94c85ef42cb42cf78a23291ddb5e7d", size = 6519964, upload-time = "2026-02-06T09:54:40.268Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/f5/c0e178721b818072f2e8b6fde13faaba942406c634009caf065121ce246b/grpcio-1.78.0-cp310-cp310-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:4c5533d03a6cbd7f56acfc9cfb44ea64f63d29091e40e44010d34178d392d7eb", size = 7198058, upload-time = "2026-02-06T09:54:42.389Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/b2/40d43c91ae9cd667edc960135f9f08e58faa1576dc95af29f66ec912985f/grpcio-1.78.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:ff870aebe9a93a85283837801d35cd5f8814fe2ad01e606861a7fb47c762a2b7", size = 6727212, upload-time = "2026-02-06T09:54:44.91Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/88/9da42eed498f0efcfcd9156e48ae63c0cde3bea398a16c99fb5198c885b6/grpcio-1.78.0-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:391e93548644e6b2726f1bb84ed60048d4bcc424ce5e4af0843d28ca0b754fec", size = 7300845, upload-time = "2026-02-06T09:54:47.562Z" },
+    { url = "https://files.pythonhosted.org/packages/23/3f/1c66b7b1b19a8828890e37868411a6e6925df5a9030bfa87ab318f34095d/grpcio-1.78.0-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:df2c8f3141f7cbd112a6ebbd760290b5849cda01884554f7c67acc14e7b1758a", size = 8284605, upload-time = "2026-02-06T09:54:50.475Z" },
+    { url = "https://files.pythonhosted.org/packages/94/c4/ca1bd87394f7b033e88525384b4d1e269e8424ab441ea2fba1a0c5b50986/grpcio-1.78.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:bd8cb8026e5f5b50498a3c4f196f57f9db344dad829ffae16b82e4fdbaea2813", size = 7726672, upload-time = "2026-02-06T09:54:53.11Z" },
+    { url = "https://files.pythonhosted.org/packages/41/09/f16e487d4cc65ccaf670f6ebdd1a17566b965c74fc3d93999d3b2821e052/grpcio-1.78.0-cp310-cp310-win32.whl", hash = "sha256:f8dff3d9777e5d2703a962ee5c286c239bf0ba173877cc68dc02c17d042e29de", size = 4076715, upload-time = "2026-02-06T09:54:55.549Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/32/4ce60d94e242725fd3bcc5673c04502c82a8e87b21ea411a63992dc39f8f/grpcio-1.78.0-cp310-cp310-win_amd64.whl", hash = "sha256:94f95cf5d532d0e717eed4fc1810e8e6eded04621342ec54c89a7c2f14b581bf", size = 4799157, upload-time = "2026-02-06T09:54:59.838Z" },
+    { url = "https://files.pythonhosted.org/packages/86/c7/d0b780a29b0837bf4ca9580904dfb275c1fc321ded7897d620af7047ec57/grpcio-1.78.0-cp311-cp311-linux_armv7l.whl", hash = "sha256:2777b783f6c13b92bd7b716667452c329eefd646bfb3f2e9dabea2e05dbd34f6", size = 5951525, upload-time = "2026-02-06T09:55:01.989Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/b1/96920bf2ee61df85a9503cb6f733fe711c0ff321a5a697d791b075673281/grpcio-1.78.0-cp311-cp311-macosx_11_0_universal2.whl", hash = "sha256:9dca934f24c732750389ce49d638069c3892ad065df86cb465b3fa3012b70c9e", size = 11830418, upload-time = "2026-02-06T09:55:04.462Z" },
+    { url = "https://files.pythonhosted.org/packages/83/0c/7c1528f098aeb75a97de2bae18c530f56959fb7ad6c882db45d9884d6edc/grpcio-1.78.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:459ab414b35f4496138d0ecd735fed26f1318af5e52cb1efbc82a09f0d5aa911", size = 6524477, upload-time = "2026-02-06T09:55:07.111Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/52/e7c1f3688f949058e19a011c4e0dec973da3d0ae5e033909677f967ae1f4/grpcio-1.78.0-cp311-cp311-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:082653eecbdf290e6e3e2c276ab2c54b9e7c299e07f4221872380312d8cf395e", size = 7198266, upload-time = "2026-02-06T09:55:10.016Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/61/8ac32517c1e856677282c34f2e7812d6c328fa02b8f4067ab80e77fdc9c9/grpcio-1.78.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:85f93781028ec63f383f6bc90db785a016319c561cc11151fbb7b34e0d012303", size = 6730552, upload-time = "2026-02-06T09:55:12.207Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/98/b8ee0158199250220734f620b12e4a345955ac7329cfd908d0bf0fda77f0/grpcio-1.78.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:f12857d24d98441af6a1d5c87442d624411db486f7ba12550b07788f74b67b04", size = 7304296, upload-time = "2026-02-06T09:55:15.044Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/0f/7b72762e0d8840b58032a56fdbd02b78fc645b9fa993d71abf04edbc54f4/grpcio-1.78.0-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:5397fff416b79e4b284959642a4e95ac4b0f1ece82c9993658e0e477d40551ec", size = 8288298, upload-time = "2026-02-06T09:55:17.276Z" },
+    { url = "https://files.pythonhosted.org/packages/24/ae/ae4ce56bc5bb5caa3a486d60f5f6083ac3469228faa734362487176c15c5/grpcio-1.78.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:fbe6e89c7ffb48518384068321621b2a69cab509f58e40e4399fdd378fa6d074", size = 7730953, upload-time = "2026-02-06T09:55:19.545Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/6e/8052e3a28eb6a820c372b2eb4b5e32d195c661e137d3eca94d534a4cfd8a/grpcio-1.78.0-cp311-cp311-win32.whl", hash = "sha256:6092beabe1966a3229f599d7088b38dfc8ffa1608b5b5cdda31e591e6500f856", size = 4076503, upload-time = "2026-02-06T09:55:21.521Z" },
+    { url = "https://files.pythonhosted.org/packages/08/62/f22c98c5265dfad327251fa2f840b591b1df5f5e15d88b19c18c86965b27/grpcio-1.78.0-cp311-cp311-win_amd64.whl", hash = "sha256:1afa62af6e23f88629f2b29ec9e52ec7c65a7176c1e0a83292b93c76ca882558", size = 4799767, upload-time = "2026-02-06T09:55:24.107Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/f4/7384ed0178203d6074446b3c4f46c90a22ddf7ae0b3aee521627f54cfc2a/grpcio-1.78.0-cp312-cp312-linux_armv7l.whl", hash = "sha256:f9ab915a267fc47c7e88c387a3a28325b58c898e23d4995f765728f4e3dedb97", size = 5913985, upload-time = "2026-02-06T09:55:26.832Z" },
+    { url = "https://files.pythonhosted.org/packages/81/ed/be1caa25f06594463f685b3790b320f18aea49b33166f4141bfdc2bfb236/grpcio-1.78.0-cp312-cp312-macosx_11_0_universal2.whl", hash = "sha256:3f8904a8165ab21e07e58bf3e30a73f4dffc7a1e0dbc32d51c61b5360d26f43e", size = 11811853, upload-time = "2026-02-06T09:55:29.224Z" },
+    { url = "https://files.pythonhosted.org/packages/24/a7/f06d151afc4e64b7e3cc3e872d331d011c279aaab02831e40a81c691fb65/grpcio-1.78.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:859b13906ce098c0b493af92142ad051bf64c7870fa58a123911c88606714996", size = 6475766, upload-time = "2026-02-06T09:55:31.825Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/a8/4482922da832ec0082d0f2cc3a10976d84a7424707f25780b82814aafc0a/grpcio-1.78.0-cp312-cp312-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:b2342d87af32790f934a79c3112641e7b27d63c261b8b4395350dad43eff1dc7", size = 7170027, upload-time = "2026-02-06T09:55:34.7Z" },
+    { url = "https://files.pythonhosted.org/packages/54/bf/f4a3b9693e35d25b24b0b39fa46d7d8a3c439e0a3036c3451764678fec20/grpcio-1.78.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:12a771591ae40bc65ba67048fa52ef4f0e6db8279e595fd349f9dfddeef571f9", size = 6690766, upload-time = "2026-02-06T09:55:36.902Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/b9/521875265cc99fe5ad4c5a17010018085cae2810a928bf15ebe7d8bcd9cc/grpcio-1.78.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:185dea0d5260cbb2d224c507bf2a5444d5abbb1fa3594c1ed7e4c709d5eb8383", size = 7266161, upload-time = "2026-02-06T09:55:39.824Z" },
+    { url = "https://files.pythonhosted.org/packages/05/86/296a82844fd40a4ad4a95f100b55044b4f817dece732bf686aea1a284147/grpcio-1.78.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:51b13f9aed9d59ee389ad666b8c2214cc87b5de258fa712f9ab05f922e3896c6", size = 8253303, upload-time = "2026-02-06T09:55:42.353Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/e4/ea3c0caf5468537f27ad5aab92b681ed7cc0ef5f8c9196d3fd42c8c2286b/grpcio-1.78.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:fd5f135b1bd58ab088930b3c613455796dfa0393626a6972663ccdda5b4ac6ce", size = 7698222, upload-time = "2026-02-06T09:55:44.629Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/47/7f05f81e4bb6b831e93271fb12fd52ba7b319b5402cbc101d588f435df00/grpcio-1.78.0-cp312-cp312-win32.whl", hash = "sha256:94309f498bcc07e5a7d16089ab984d42ad96af1d94b5a4eb966a266d9fcabf68", size = 4066123, upload-time = "2026-02-06T09:55:47.644Z" },
+    { url = "https://files.pythonhosted.org/packages/ad/e7/d6914822c88aa2974dbbd10903d801a28a19ce9cd8bad7e694cbbcf61528/grpcio-1.78.0-cp312-cp312-win_amd64.whl", hash = "sha256:9566fe4ababbb2610c39190791e5b829869351d14369603702e890ef3ad2d06e", size = 4797657, upload-time = "2026-02-06T09:55:49.86Z" },
+    { url = "https://files.pythonhosted.org/packages/05/a9/8f75894993895f361ed8636cd9237f4ab39ef87fd30db17467235ed1c045/grpcio-1.78.0-cp313-cp313-linux_armv7l.whl", hash = "sha256:ce3a90455492bf8bfa38e56fbbe1dbd4f872a3d8eeaf7337dc3b1c8aa28c271b", size = 5920143, upload-time = "2026-02-06T09:55:52.035Z" },
+    { url = "https://files.pythonhosted.org/packages/55/06/0b78408e938ac424100100fd081189451b472236e8a3a1f6500390dc4954/grpcio-1.78.0-cp313-cp313-macosx_11_0_universal2.whl", hash = "sha256:2bf5e2e163b356978b23652c4818ce4759d40f4712ee9ec5a83c4be6f8c23a3a", size = 11803926, upload-time = "2026-02-06T09:55:55.494Z" },
+    { url = "https://files.pythonhosted.org/packages/88/93/b59fe7832ff6ae3c78b813ea43dac60e295fa03606d14d89d2e0ec29f4f3/grpcio-1.78.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:8f2ac84905d12918e4e55a16da17939eb63e433dc11b677267c35568aa63fc84", size = 6478628, upload-time = "2026-02-06T09:55:58.533Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/df/e67e3734527f9926b7d9c0dde6cd998d1d26850c3ed8eeec81297967ac67/grpcio-1.78.0-cp313-cp313-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:b58f37edab4a3881bc6c9bca52670610e0c9ca14e2ea3cf9debf185b870457fb", size = 7173574, upload-time = "2026-02-06T09:56:01.786Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/62/cc03fffb07bfba982a9ec097b164e8835546980aec25ecfa5f9c1a47e022/grpcio-1.78.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:735e38e176a88ce41840c21bb49098ab66177c64c82426e24e0082500cc68af5", size = 6692639, upload-time = "2026-02-06T09:56:04.529Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/9a/289c32e301b85bdb67d7ec68b752155e674ee3ba2173a1858f118e399ef3/grpcio-1.78.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:2045397e63a7a0ee7957c25f7dbb36ddc110e0cfb418403d110c0a7a68a844e9", size = 7268838, upload-time = "2026-02-06T09:56:08.397Z" },
+    { url = "https://files.pythonhosted.org/packages/0e/79/1be93f32add280461fa4773880196572563e9c8510861ac2da0ea0f892b6/grpcio-1.78.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:a9f136fbafe7ccf4ac7e8e0c28b31066e810be52d6e344ef954a3a70234e1702", size = 8251878, upload-time = "2026-02-06T09:56:10.914Z" },
+    { url = "https://files.pythonhosted.org/packages/65/65/793f8e95296ab92e4164593674ae6291b204bb5f67f9d4a711489cd30ffa/grpcio-1.78.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:748b6138585379c737adc08aeffd21222abbda1a86a0dca2a39682feb9196c20", size = 7695412, upload-time = "2026-02-06T09:56:13.593Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/9f/1e233fe697ecc82845942c2822ed06bb522e70d6771c28d5528e4c50f6a4/grpcio-1.78.0-cp313-cp313-win32.whl", hash = "sha256:271c73e6e5676afe4fc52907686670c7cea22ab2310b76a59b678403ed40d670", size = 4064899, upload-time = "2026-02-06T09:56:15.601Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/27/d86b89e36de8a951501fb06a0f38df19853210f341d0b28f83f4aa0ffa08/grpcio-1.78.0-cp313-cp313-win_amd64.whl", hash = "sha256:f2d4e43ee362adfc05994ed479334d5a451ab7bc3f3fee1b796b8ca66895acb4", size = 4797393, upload-time = "2026-02-06T09:56:17.882Z" },
+    { url = "https://files.pythonhosted.org/packages/29/f2/b56e43e3c968bfe822fa6ce5bca10d5c723aa40875b48791ce1029bb78c7/grpcio-1.78.0-cp314-cp314-linux_armv7l.whl", hash = "sha256:e87cbc002b6f440482b3519e36e1313eb5443e9e9e73d6a52d43bd2004fcfd8e", size = 5920591, upload-time = "2026-02-06T09:56:20.758Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/81/1f3b65bd30c334167bfa8b0d23300a44e2725ce39bba5b76a2460d85f745/grpcio-1.78.0-cp314-cp314-macosx_11_0_universal2.whl", hash = "sha256:c41bc64626db62e72afec66b0c8a0da76491510015417c127bfc53b2fe6d7f7f", size = 11813685, upload-time = "2026-02-06T09:56:24.315Z" },
+    { url = "https://files.pythonhosted.org/packages/0e/1c/bbe2f8216a5bd3036119c544d63c2e592bdf4a8ec6e4a1867592f4586b26/grpcio-1.78.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:8dfffba826efcf366b1e3ccc37e67afe676f290e13a3b48d31a46739f80a8724", size = 6487803, upload-time = "2026-02-06T09:56:27.367Z" },
+    { url = "https://files.pythonhosted.org/packages/16/5c/a6b2419723ea7ddce6308259a55e8e7593d88464ce8db9f4aa857aba96fa/grpcio-1.78.0-cp314-cp314-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:74be1268d1439eaaf552c698cdb11cd594f0c49295ae6bb72c34ee31abbe611b", size = 7173206, upload-time = "2026-02-06T09:56:29.876Z" },
+    { url = "https://files.pythonhosted.org/packages/df/1e/b8801345629a415ea7e26c83d75eb5dbe91b07ffe5210cc517348a8d4218/grpcio-1.78.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:be63c88b32e6c0f1429f1398ca5c09bc64b0d80950c8bb7807d7d7fb36fb84c7", size = 6693826, upload-time = "2026-02-06T09:56:32.305Z" },
+    { url = "https://files.pythonhosted.org/packages/34/84/0de28eac0377742679a510784f049738a80424b17287739fc47d63c2439e/grpcio-1.78.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:3c586ac70e855c721bda8f548d38c3ca66ac791dc49b66a8281a1f99db85e452", size = 7277897, upload-time = "2026-02-06T09:56:34.915Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/9c/ad8685cfe20559a9edb66f735afdcb2b7d3de69b13666fdfc542e1916ebd/grpcio-1.78.0-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:35eb275bf1751d2ffbd8f57cdbc46058e857cf3971041521b78b7db94bdaf127", size = 8252404, upload-time = "2026-02-06T09:56:37.553Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/05/33a7a4985586f27e1de4803887c417ec7ced145ebd069bc38a9607059e2b/grpcio-1.78.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:207db540302c884b8848036b80db352a832b99dfdf41db1eb554c2c2c7800f65", size = 7696837, upload-time = "2026-02-06T09:56:40.173Z" },
+    { url = "https://files.pythonhosted.org/packages/73/77/7382241caf88729b106e49e7d18e3116216c778e6a7e833826eb96de22f7/grpcio-1.78.0-cp314-cp314-win32.whl", hash = "sha256:57bab6deef2f4f1ca76cc04565df38dc5713ae6c17de690721bdf30cb1e0545c", size = 4142439, upload-time = "2026-02-06T09:56:43.258Z" },
+    { url = "https://files.pythonhosted.org/packages/48/b2/b096ccce418882fbfda4f7496f9357aaa9a5af1896a9a7f60d9f2b275a06/grpcio-1.78.0-cp314-cp314-win_amd64.whl", hash = "sha256:dce09d6116df20a96acfdbf85e4866258c3758180e8c49845d6ba8248b6d0bbb", size = 4929852, upload-time = "2026-02-06T09:56:45.885Z" },
+]
+
+[[package]]
+name = "h11"
+version = "0.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/01/ee/02a2c011bdab74c6fb3c75474d40b3052059d95df7e73351460c8588d963/h11-0.16.0.tar.gz", hash = "sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1", size = 101250, upload-time = "2025-04-24T03:35:25.427Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" },
+]
+
+[[package]]
+name = "httpcore"
+version = "1.0.9"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "certifi" },
+    { name = "h11" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/94/82699a10bca87a5556c9c59b5963f2d039dbd239f25bc2a63907a05a14cb/httpcore-1.0.9.tar.gz", hash = "sha256:6e34463af53fd2ab5d807f399a9b45ea31c3dfa2276f15a2c3f00afff6e176e8", size = 85484, upload-time = "2025-04-24T22:06:22.219Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7e/f5/f66802a942d491edb555dd61e3a9961140fd64c90bce1eafd741609d334d/httpcore-1.0.9-py3-none-any.whl", hash = "sha256:2d400746a40668fc9dec9810239072b40b4484b640a8c38fd654a024c7a1bf55", size = 78784, upload-time = "2025-04-24T22:06:20.566Z" },
+]
+
+[[package]]
+name = "httpx"
+version = "0.28.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "certifi" },
+    { name = "httpcore" },
+    { name = "idna" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b1/df/48c586a5fe32a0f01324ee087459e112ebb7224f646c0b5023f5e79e9956/httpx-0.28.1.tar.gz", hash = "sha256:75e98c5f16b0f35b567856f597f06ff2270a374470a5c2392242528e3e3e42fc", size = 141406, upload-time = "2024-12-06T15:37:23.222Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2a/39/e50c7c3a983047577ee07d2a9e53faf5a69493943ec3f6a384bdc792deb2/httpx-0.28.1-py3-none-any.whl", hash = "sha256:d909fcccc110f8c7faf814ca82a9a4d816bc5a6dbfea25d6591d6985b8ba59ad", size = 73517, upload-time = "2024-12-06T15:37:21.509Z" },
+]
+
+[[package]]
+name = "httpx-sse"
+version = "0.4.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/0f/4c/751061ffa58615a32c31b2d82e8482be8dd4a89154f003147acee90f2be9/httpx_sse-0.4.3.tar.gz", hash = "sha256:9b1ed0127459a66014aec3c56bebd93da3c1bc8bb6618c8082039a44889a755d", size = 15943, upload-time = "2025-10-10T21:48:22.271Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d2/fd/6668e5aec43ab844de6fc74927e155a3b37bf40d7c3790e49fc0406b6578/httpx_sse-0.4.3-py3-none-any.whl", hash = "sha256:0ac1c9fe3c0afad2e0ebb25a934a59f4c7823b60792691f779fad2c5568830fc", size = 8960, upload-time = "2025-10-10T21:48:21.158Z" },
+]
+
+[[package]]
+name = "idna"
+version = "3.18"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/cd/63/9496c57188a2ee585e0f1db071d75089a11e98aa86eb99d9d7618fc1edce/idna-3.18.tar.gz", hash = "sha256:ffb385a7e039654cef1ab9ef32c6fafe283c0c0467bba1d9029738ce4a14a848", size = 196711, upload-time = "2026-06-02T14:34:07.794Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1e/5e/d4e9f1a599fb8e573b7b87160658329fbf28d19eac2718f51fc3def3aa5a/idna-3.18-py3-none-any.whl", hash = "sha256:7f952cbe720b688055e3f87de14f5c3e5fdaa8bc3928985c4077ca689de849a2", size = 65455, upload-time = "2026-06-02T14:34:06.319Z" },
+]
+
+[[package]]
+name = "importlib-metadata"
+version = "8.7.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "zipp" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f3/49/3b30cad09e7771a4982d9975a8cbf64f00d4a1ececb53297f1d9a7be1b10/importlib_metadata-8.7.1.tar.gz", hash = "sha256:49fef1ae6440c182052f407c8d34a68f72efc36db9ca90dc0113398f2fdde8bb", size = 57107, upload-time = "2025-12-21T10:00:19.278Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fa/5e/f8e9a1d23b9c20a551a8a02ea3637b4642e22c2626e3a13a9a29cdea99eb/importlib_metadata-8.7.1-py3-none-any.whl", hash = "sha256:5a1f80bf1daa489495071efbb095d75a634cf28a8bc299581244063b53176151", size = 27865, upload-time = "2025-12-21T10:00:18.329Z" },
+]
+
+[[package]]
+name = "iniconfig"
+version = "2.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/34/14ca021ce8e5dfedc35312d08ba8bf51fdd999c576889fc2c24cb97f4f10/iniconfig-2.3.0.tar.gz", hash = "sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730", size = 20503, upload-time = "2025-10-18T21:55:43.219Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484, upload-time = "2025-10-18T21:55:41.639Z" },
+]
+
+[[package]]
+name = "inline-snapshot"
+version = "0.32.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "asttokens" },
+    { name = "executing" },
+    { name = "pytest" },
+    { name = "rich" },
+    { name = "tomli", marker = "python_full_version < '3.11'" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ca/87/62b78b49042c533038ab1bf0931a7b70fdb78d07a11c9bf159be04027df8/inline_snapshot-0.32.5.tar.gz", hash = "sha256:5025074eab5c82a88504975e2655beeb5e96fd57ed2d9ebb38538473748f2065", size = 2626796, upload-time = "2026-03-13T18:35:54.891Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/09/d3/73426dd3da75095fd071ce5c1f8e520e879a582ca04df861575c6feb9166/inline_snapshot-0.32.5-py3-none-any.whl", hash = "sha256:ac617c273e811ed5ca15abd8f8dbd3fa268296bb0642ccb1403a5df61ce2e39e", size = 84993, upload-time = "2026-03-13T18:35:52.955Z" },
+]
+
+[package.optional-dependencies]
+dirty-equals = [
+    { name = "dirty-equals" },
+]
+
+[[package]]
+name = "ipython"
+version = "8.39.0"
+source = { registry = "https://pypi.org/simple" }
+resolution-markers = [
+    "python_full_version < '3.11'",
+]
+dependencies = [
+    { name = "colorama", marker = "python_full_version < '3.11' and sys_platform == 'win32'" },
+    { name = "decorator", marker = "python_full_version < '3.11'" },
+    { name = "exceptiongroup", marker = "python_full_version < '3.11'" },
+    { name = "jedi", marker = "python_full_version < '3.11'" },
+    { name = "matplotlib-inline", marker = "python_full_version < '3.11'" },
+    { name = "pexpect", marker = "python_full_version < '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" },
+    { name = "prompt-toolkit", marker = "python_full_version < '3.11'" },
+    { name = "pygments", marker = "python_full_version < '3.11'" },
+    { name = "stack-data", marker = "python_full_version < '3.11'" },
+    { name = "traitlets", marker = "python_full_version < '3.11'" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/40/18/f8598d287006885e7136451fdea0755af4ebcbfe342836f24deefaed1164/ipython-8.39.0.tar.gz", hash = "sha256:4110ae96012c379b8b6db898a07e186c40a2a1ef5d57a7fa83166047d9da7624", size = 5513971, upload-time = "2026-03-27T10:02:13.94Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c0/56/4cc7fc9e9e3f38fd324f24f8afe0ad8bb5fa41283f37f1aaf9de0612c968/ipython-8.39.0-py3-none-any.whl", hash = "sha256:bb3c51c4fa8148ab1dea07a79584d1c854e234ea44aa1283bcb37bc75054651f", size = 831849, upload-time = "2026-03-27T10:02:07.846Z" },
+]
+
+[[package]]
+name = "ipython"
+version = "9.10.1"
+source = { registry = "https://pypi.org/simple" }
+resolution-markers = [
+    "python_full_version == '3.11.*'",
+]
+dependencies = [
+    { name = "colorama", marker = "python_full_version == '3.11.*' and sys_platform == 'win32'" },
+    { name = "decorator", marker = "python_full_version == '3.11.*'" },
+    { name = "ipython-pygments-lexers", marker = "python_full_version == '3.11.*'" },
+    { name = "jedi", marker = "python_full_version == '3.11.*'" },
+    { name = "matplotlib-inline", marker = "python_full_version == '3.11.*'" },
+    { name = "pexpect", marker = "python_full_version == '3.11.*' and sys_platform != 'emscripten' and sys_platform != 'win32'" },
+    { name = "prompt-toolkit", marker = "python_full_version == '3.11.*'" },
+    { name = "pygments", marker = "python_full_version == '3.11.*'" },
+    { name = "stack-data", marker = "python_full_version == '3.11.*'" },
+    { name = "traitlets", marker = "python_full_version == '3.11.*'" },
+    { name = "typing-extensions", marker = "python_full_version == '3.11.*'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c5/25/daae0e764047b0a2480c7bbb25d48f4f509b5818636562eeac145d06dfee/ipython-9.10.1.tar.gz", hash = "sha256:e170e9b2a44312484415bdb750492699bf329233b03f2557a9692cce6466ada4", size = 4426663, upload-time = "2026-03-27T09:53:26.244Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/01/09/ba70f8d662d5671687da55ad2cc0064cf795b15e1eea70907532202e7c97/ipython-9.10.1-py3-none-any.whl", hash = "sha256:82d18ae9fb9164ded080c71ef92a182ee35ee7db2395f67616034bebb020a232", size = 622827, upload-time = "2026-03-27T09:53:24.566Z" },
+]
+
+[[package]]
+name = "ipython"
+version = "9.12.0"
+source = { registry = "https://pypi.org/simple" }
+resolution-markers = [
+    "python_full_version >= '3.14'",
+    "python_full_version == '3.13.*'",
+    "python_full_version == '3.12.*'",
+]
+dependencies = [
+    { name = "colorama", marker = "python_full_version >= '3.12' and sys_platform == 'win32'" },
+    { name = "decorator", marker = "python_full_version >= '3.12'" },
+    { name = "ipython-pygments-lexers", marker = "python_full_version >= '3.12'" },
+    { name = "jedi", marker = "python_full_version >= '3.12'" },
+    { name = "matplotlib-inline", marker = "python_full_version >= '3.12'" },
+    { name = "pexpect", marker = "python_full_version >= '3.12' and sys_platform != 'emscripten' and sys_platform != 'win32'" },
+    { name = "prompt-toolkit", marker = "python_full_version >= '3.12'" },
+    { name = "pygments", marker = "python_full_version >= '3.12'" },
+    { name = "stack-data", marker = "python_full_version >= '3.12'" },
+    { name = "traitlets", marker = "python_full_version >= '3.12'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/3a/73/7114f80a8f9cabdb13c27732dce24af945b2923dcab80723602f7c8bc2d8/ipython-9.12.0.tar.gz", hash = "sha256:01daa83f504b693ba523b5a407246cabde4eb4513285a3c6acaff11a66735ee4", size = 4428879, upload-time = "2026-03-27T09:42:45.312Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/59/22/906c8108974c673ebef6356c506cebb6870d48cedea3c41e949e2dd556bb/ipython-9.12.0-py3-none-any.whl", hash = "sha256:0f2701e8ee86e117e37f50563205d36feaa259d2e08d4a6bc6b6d74b18ce128d", size = 625661, upload-time = "2026-03-27T09:42:42.831Z" },
+]
+
+[[package]]
+name = "ipython-pygments-lexers"
+version = "1.1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pygments", marker = "python_full_version >= '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ef/4c/5dd1d8af08107f88c7f741ead7a40854b8ac24ddf9ae850afbcf698aa552/ipython_pygments_lexers-1.1.1.tar.gz", hash = "sha256:09c0138009e56b6854f9535736f4171d855c8c08a563a0dcd8022f78355c7e81", size = 8393, upload-time = "2025-01-17T11:24:34.505Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d9/33/1f075bf72b0b747cb3288d011319aaf64083cf2efef8354174e3ed4540e2/ipython_pygments_lexers-1.1.1-py3-none-any.whl", hash = "sha256:a9462224a505ade19a605f71f8fa63c2048833ce50abc86768a0d81d876dc81c", size = 8074, upload-time = "2025-01-17T11:24:33.271Z" },
+]
+
+[[package]]
+name = "jaraco-classes"
+version = "3.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "more-itertools" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/c0/ed4a27bc5571b99e3cff68f8a9fa5b56ff7df1c2251cc715a652ddd26402/jaraco.classes-3.4.0.tar.gz", hash = "sha256:47a024b51d0239c0dd8c8540c6c7f484be3b8fcf0b2d85c13825780d3b3f3acd", size = 11780, upload-time = "2024-03-31T07:27:36.643Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7f/66/b15ce62552d84bbfcec9a4873ab79d993a1dd4edb922cbfccae192bd5b5f/jaraco.classes-3.4.0-py3-none-any.whl", hash = "sha256:f662826b6bed8cace05e7ff873ce0f9283b5c924470fe664fff1c2f00f581790", size = 6777, upload-time = "2024-03-31T07:27:34.792Z" },
+]
+
+[[package]]
+name = "jaraco-context"
+version = "6.1.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "backports-tarfile", marker = "python_full_version < '3.12'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/af/50/4763cd07e722bb6285316d390a164bc7e479db9d90daa769f22578f698b4/jaraco_context-6.1.2.tar.gz", hash = "sha256:f1a6c9d391e661cc5b8d39861ff077a7dc24dc23833ccee564b234b81c82dfe3", size = 16801, upload-time = "2026-03-20T22:13:33.922Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f2/58/bc8954bda5fcda97bd7c19be11b85f91973d67a706ed4a3aec33e7de22db/jaraco_context-6.1.2-py3-none-any.whl", hash = "sha256:bf8150b79a2d5d91ae48629d8b427a8f7ba0e1097dd6202a9059f29a36379535", size = 7871, upload-time = "2026-03-20T22:13:32.808Z" },
+]
+
+[[package]]
+name = "jaraco-functools"
+version = "4.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "more-itertools" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0f/27/056e0638a86749374d6f57d0b0db39f29509cce9313cf91bdc0ac4d91084/jaraco_functools-4.4.0.tar.gz", hash = "sha256:da21933b0417b89515562656547a77b4931f98176eb173644c0d35032a33d6bb", size = 19943, upload-time = "2025-12-21T09:29:43.6Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fd/c4/813bb09f0985cb21e959f21f2464169eca882656849adf727ac7bb7e1767/jaraco_functools-4.4.0-py3-none-any.whl", hash = "sha256:9eec1e36f45c818d9bf307c8948eb03b2b56cd44087b3cdc989abca1f20b9176", size = 10481, upload-time = "2025-12-21T09:29:42.27Z" },
+]
+
+[[package]]
+name = "jedi"
+version = "0.19.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "parso" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/72/3a/79a912fbd4d8dd6fbb02bf69afd3bb72cf0c729bb3063c6f4498603db17a/jedi-0.19.2.tar.gz", hash = "sha256:4770dc3de41bde3966b02eb84fbcf557fb33cce26ad23da12c742fb50ecb11f0", size = 1231287, upload-time = "2024-11-11T01:41:42.873Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c0/5a/9cac0c82afec3d09ccd97c8b6502d48f165f9124db81b4bcb90b4af974ee/jedi-0.19.2-py2.py3-none-any.whl", hash = "sha256:a8ef22bde8490f57fe5c7681a3c83cb58874daf72b4784de3cce5b6ef6edb5b9", size = 1572278, upload-time = "2024-11-11T01:41:40.175Z" },
+]
+
+[[package]]
+name = "jeepney"
+version = "0.9.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7b/6f/357efd7602486741aa73ffc0617fb310a29b588ed0fd69c2399acbb85b0c/jeepney-0.9.0.tar.gz", hash = "sha256:cf0e9e845622b81e4a28df94c40345400256ec608d0e55bb8a3feaa9163f5732", size = 106758, upload-time = "2025-02-27T18:51:01.684Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b2/a3/e137168c9c44d18eff0376253da9f1e9234d0239e0ee230d2fee6cea8e55/jeepney-0.9.0-py3-none-any.whl", hash = "sha256:97e5714520c16fc0a45695e5365a2e11b81ea79bba796e26f9f1d178cb182683", size = 49010, upload-time = "2025-02-27T18:51:00.104Z" },
+]
+
+[[package]]
+name = "jiter"
+version = "0.13.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/0d/5e/4ec91646aee381d01cdb9974e30882c9cd3b8c5d1079d6b5ff4af522439a/jiter-0.13.0.tar.gz", hash = "sha256:f2839f9c2c7e2dffc1bc5929a510e14ce0a946be9365fd1219e7ef342dae14f4", size = 164847, upload-time = "2026-02-02T12:37:56.441Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d0/5a/41da76c5ea07bec1b0472b6b2fdb1b651074d504b19374d7e130e0cdfb25/jiter-0.13.0-cp310-cp310-macosx_10_12_x86_64.whl", hash = "sha256:2ffc63785fd6c7977defe49b9824ae6ce2b2e2b77ce539bdaf006c26da06342e", size = 311164, upload-time = "2026-02-02T12:35:17.688Z" },
+    { url = "https://files.pythonhosted.org/packages/40/cb/4a1bf994a3e869f0d39d10e11efb471b76d0ad70ecbfb591427a46c880c2/jiter-0.13.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:4a638816427006c1e3f0013eb66d391d7a3acda99a7b0cf091eff4497ccea33a", size = 320296, upload-time = "2026-02-02T12:35:19.828Z" },
+    { url = "https://files.pythonhosted.org/packages/09/82/acd71ca9b50ecebadc3979c541cd717cce2fe2bc86236f4fa597565d8f1a/jiter-0.13.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:19928b5d1ce0ff8c1ee1b9bdef3b5bfc19e8304f1b904e436caf30bc15dc6cf5", size = 352742, upload-time = "2026-02-02T12:35:21.258Z" },
+    { url = "https://files.pythonhosted.org/packages/71/03/d1fc996f3aecfd42eb70922edecfb6dd26421c874503e241153ad41df94f/jiter-0.13.0-cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:309549b778b949d731a2f0e1594a3f805716be704a73bf3ad9a807eed5eb5721", size = 363145, upload-time = "2026-02-02T12:35:24.653Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/61/a30492366378cc7a93088858f8991acd7d959759fe6138c12a4644e58e81/jiter-0.13.0-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:bcdabaea26cb04e25df3103ce47f97466627999260290349a88c8136ecae0060", size = 487683, upload-time = "2026-02-02T12:35:26.162Z" },
+    { url = "https://files.pythonhosted.org/packages/20/4e/4223cffa9dbbbc96ed821c5aeb6bca510848c72c02086d1ed3f1da3d58a7/jiter-0.13.0-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:a3a377af27b236abbf665a69b2bdd680e3b5a0bd2af825cd3b81245279a7606c", size = 373579, upload-time = "2026-02-02T12:35:27.582Z" },
+    { url = "https://files.pythonhosted.org/packages/fe/c9/b0489a01329ab07a83812d9ebcffe7820a38163c6d9e7da644f926ff877c/jiter-0.13.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:fe49d3ff6db74321f144dff9addd4a5874d3105ac5ba7c5b77fac099cfae31ae", size = 362904, upload-time = "2026-02-02T12:35:28.925Z" },
+    { url = "https://files.pythonhosted.org/packages/05/af/53e561352a44afcba9a9bc67ee1d320b05a370aed8df54eafe714c4e454d/jiter-0.13.0-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:2113c17c9a67071b0f820733c0893ed1d467b5fcf4414068169e5c2cabddb1e2", size = 392380, upload-time = "2026-02-02T12:35:30.385Z" },
+    { url = "https://files.pythonhosted.org/packages/76/2a/dd805c3afb8ed5b326c5ae49e725d1b1255b9754b1b77dbecdc621b20773/jiter-0.13.0-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:ab1185ca5c8b9491b55ebf6c1e8866b8f68258612899693e24a92c5fdb9455d5", size = 517939, upload-time = "2026-02-02T12:35:31.865Z" },
+    { url = "https://files.pythonhosted.org/packages/20/2a/7b67d76f55b8fe14c937e7640389612f05f9a4145fc28ae128aaa5e62257/jiter-0.13.0-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:9621ca242547edc16400981ca3231e0c91c0c4c1ab8573a596cd9bb3575d5c2b", size = 551696, upload-time = "2026-02-02T12:35:33.306Z" },
+    { url = "https://files.pythonhosted.org/packages/85/9c/57cdd64dac8f4c6ab8f994fe0eb04dc9fd1db102856a4458fcf8a99dfa62/jiter-0.13.0-cp310-cp310-win32.whl", hash = "sha256:a7637d92b1c9d7a771e8c56f445c7f84396d48f2e756e5978840ecba2fac0894", size = 204592, upload-time = "2026-02-02T12:35:34.58Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/38/f4f3ea5788b8a5bae7510a678cdc747eda0c45ffe534f9878ff37e7cf3b3/jiter-0.13.0-cp310-cp310-win_amd64.whl", hash = "sha256:c1b609e5cbd2f52bb74fb721515745b407df26d7b800458bd97cb3b972c29e7d", size = 206016, upload-time = "2026-02-02T12:35:36.435Z" },
+    { url = "https://files.pythonhosted.org/packages/71/29/499f8c9eaa8a16751b1c0e45e6f5f1761d180da873d417996cc7bddc8eef/jiter-0.13.0-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:ea026e70a9a28ebbdddcbcf0f1323128a8db66898a06eaad3a4e62d2f554d096", size = 311157, upload-time = "2026-02-02T12:35:37.758Z" },
+    { url = "https://files.pythonhosted.org/packages/50/f6/566364c777d2ab450b92100bea11333c64c38d32caf8dc378b48e5b20c46/jiter-0.13.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:66aa3e663840152d18cc8ff1e4faad3dd181373491b9cfdc6004b92198d67911", size = 319729, upload-time = "2026-02-02T12:35:39.246Z" },
+    { url = "https://files.pythonhosted.org/packages/73/dd/560f13ec5e4f116d8ad2658781646cca91b617ae3b8758d4a5076b278f70/jiter-0.13.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:c3524798e70655ff19aec58c7d05adb1f074fecff62da857ea9be2b908b6d701", size = 354766, upload-time = "2026-02-02T12:35:40.662Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/0d/061faffcfe94608cbc28a0d42a77a74222bdf5055ccdbe5fd2292b94f510/jiter-0.13.0-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:ec7e287d7fbd02cb6e22f9a00dd9c9cd504c40a61f2c61e7e1f9690a82726b4c", size = 362587, upload-time = "2026-02-02T12:35:42.025Z" },
+    { url = "https://files.pythonhosted.org/packages/92/c9/c66a7864982fd38a9773ec6e932e0398d1262677b8c60faecd02ffb67bf3/jiter-0.13.0-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:47455245307e4debf2ce6c6e65a717550a0244231240dcf3b8f7d64e4c2f22f4", size = 487537, upload-time = "2026-02-02T12:35:43.459Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/86/84eb4352cd3668f16d1a88929b5888a3fe0418ea8c1dfc2ad4e7bf6e069a/jiter-0.13.0-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:ee9da221dca6e0429c2704c1b3655fe7b025204a71d4d9b73390c759d776d165", size = 373717, upload-time = "2026-02-02T12:35:44.928Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/09/9fe4c159358176f82d4390407a03f506a8659ed13ca3ac93a843402acecf/jiter-0.13.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:24ab43126d5e05f3d53a36a8e11eb2f23304c6c1117844aaaf9a0aa5e40b5018", size = 362683, upload-time = "2026-02-02T12:35:46.636Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/5e/85f3ab9caca0c1d0897937d378b4a515cae9e119730563572361ea0c48ae/jiter-0.13.0-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:9da38b4fedde4fb528c740c2564628fbab737166a0e73d6d46cb4bb5463ff411", size = 392345, upload-time = "2026-02-02T12:35:48.088Z" },
+    { url = "https://files.pythonhosted.org/packages/12/4c/05b8629ad546191939e6f0c2f17e29f542a398f4a52fb987bc70b6d1eb8b/jiter-0.13.0-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:0b34c519e17658ed88d5047999a93547f8889f3c1824120c26ad6be5f27b6cf5", size = 517775, upload-time = "2026-02-02T12:35:49.482Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/88/367ea2eb6bc582c7052e4baf5ddf57ebe5ab924a88e0e09830dfb585c02d/jiter-0.13.0-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:d2a6394e6af690d462310a86b53c47ad75ac8c21dc79f120714ea449979cb1d3", size = 551325, upload-time = "2026-02-02T12:35:51.104Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/12/fa377ffb94a2f28c41afaed093e0d70cfe512035d5ecb0cad0ae4792d35e/jiter-0.13.0-cp311-cp311-win32.whl", hash = "sha256:0f0c065695f616a27c920a56ad0d4fc46415ef8b806bf8fc1cacf25002bd24e1", size = 204709, upload-time = "2026-02-02T12:35:52.467Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/16/8e8203ce92f844dfcd3d9d6a5a7322c77077248dbb12da52d23193a839cd/jiter-0.13.0-cp311-cp311-win_amd64.whl", hash = "sha256:0733312953b909688ae3c2d58d043aa040f9f1a6a75693defed7bc2cc4bf2654", size = 204560, upload-time = "2026-02-02T12:35:53.925Z" },
+    { url = "https://files.pythonhosted.org/packages/44/26/97cc40663deb17b9e13c3a5cf29251788c271b18ee4d262c8f94798b8336/jiter-0.13.0-cp311-cp311-win_arm64.whl", hash = "sha256:5d9b34ad56761b3bf0fbe8f7e55468704107608512350962d3317ffd7a4382d5", size = 189608, upload-time = "2026-02-02T12:35:55.304Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/30/7687e4f87086829955013ca12a9233523349767f69653ebc27036313def9/jiter-0.13.0-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:0a2bd69fc1d902e89925fc34d1da51b2128019423d7b339a45d9e99c894e0663", size = 307958, upload-time = "2026-02-02T12:35:57.165Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/27/e57f9a783246ed95481e6749cc5002a8a767a73177a83c63ea71f0528b90/jiter-0.13.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:f917a04240ef31898182f76a332f508f2cc4b57d2b4d7ad2dbfebbfe167eb505", size = 318597, upload-time = "2026-02-02T12:35:58.591Z" },
+    { url = "https://files.pythonhosted.org/packages/cf/52/e5719a60ac5d4d7c5995461a94ad5ef962a37c8bf5b088390e6fad59b2ff/jiter-0.13.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:c1e2b199f446d3e82246b4fd9236d7cb502dc2222b18698ba0d986d2fecc6152", size = 348821, upload-time = "2026-02-02T12:36:00.093Z" },
+    { url = "https://files.pythonhosted.org/packages/61/db/c1efc32b8ba4c740ab3fc2d037d8753f67685f475e26b9d6536a4322bcdd/jiter-0.13.0-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:04670992b576fa65bd056dbac0c39fe8bd67681c380cb2b48efa885711d9d726", size = 364163, upload-time = "2026-02-02T12:36:01.937Z" },
+    { url = "https://files.pythonhosted.org/packages/55/8a/fb75556236047c8806995671a18e4a0ad646ed255276f51a20f32dceaeec/jiter-0.13.0-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5a1aff1fbdb803a376d4d22a8f63f8e7ccbce0b4890c26cc7af9e501ab339ef0", size = 483709, upload-time = "2026-02-02T12:36:03.41Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/16/43512e6ee863875693a8e6f6d532e19d650779d6ba9a81593ae40a9088ff/jiter-0.13.0-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:3b3fb8c2053acaef8580809ac1d1f7481a0a0bdc012fd7f5d8b18fb696a5a089", size = 370480, upload-time = "2026-02-02T12:36:04.791Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/4c/09b93e30e984a187bc8aaa3510e1ec8dcbdcd71ca05d2f56aac0492453aa/jiter-0.13.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:bdaba7d87e66f26a2c45d8cbadcbfc4bf7884182317907baf39cfe9775bb4d93", size = 360735, upload-time = "2026-02-02T12:36:06.994Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/1b/46c5e349019874ec5dfa508c14c37e29864ea108d376ae26d90bee238cd7/jiter-0.13.0-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:7b88d649135aca526da172e48083da915ec086b54e8e73a425ba50999468cc08", size = 391814, upload-time = "2026-02-02T12:36:08.368Z" },
+    { url = "https://files.pythonhosted.org/packages/15/9e/26184760e85baee7162ad37b7912797d2077718476bf91517641c92b3639/jiter-0.13.0-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:e404ea551d35438013c64b4f357b0474c7abf9f781c06d44fcaf7a14c69ff9e2", size = 513990, upload-time = "2026-02-02T12:36:09.993Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/34/2c9355247d6debad57a0a15e76ab1566ab799388042743656e566b3b7de1/jiter-0.13.0-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:1f4748aad1b4a93c8bdd70f604d0f748cdc0e8744c5547798acfa52f10e79228", size = 548021, upload-time = "2026-02-02T12:36:11.376Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/4a/9f2c23255d04a834398b9c2e0e665382116911dc4d06b795710503cdad25/jiter-0.13.0-cp312-cp312-win32.whl", hash = "sha256:0bf670e3b1445fc4d31612199f1744f67f889ee1bbae703c4b54dc097e5dd394", size = 203024, upload-time = "2026-02-02T12:36:12.682Z" },
+    { url = "https://files.pythonhosted.org/packages/09/ee/f0ae675a957ae5a8f160be3e87acea6b11dc7b89f6b7ab057e77b2d2b13a/jiter-0.13.0-cp312-cp312-win_amd64.whl", hash = "sha256:15db60e121e11fe186c0b15236bd5d18381b9ddacdcf4e659feb96fc6c969c92", size = 205424, upload-time = "2026-02-02T12:36:13.93Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/02/ae611edf913d3cbf02c97cdb90374af2082c48d7190d74c1111dde08bcdd/jiter-0.13.0-cp312-cp312-win_arm64.whl", hash = "sha256:41f92313d17989102f3cb5dd533a02787cdb99454d494344b0361355da52fcb9", size = 186818, upload-time = "2026-02-02T12:36:15.308Z" },
+    { url = "https://files.pythonhosted.org/packages/91/9c/7ee5a6ff4b9991e1a45263bfc46731634c4a2bde27dfda6c8251df2d958c/jiter-0.13.0-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:1f8a55b848cbabf97d861495cd65f1e5c590246fabca8b48e1747c4dfc8f85bf", size = 306897, upload-time = "2026-02-02T12:36:16.748Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/02/be5b870d1d2be5dd6a91bdfb90f248fbb7dcbd21338f092c6b89817c3dbf/jiter-0.13.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:f556aa591c00f2c45eb1b89f68f52441a016034d18b65da60e2d2875bbbf344a", size = 317507, upload-time = "2026-02-02T12:36:18.351Z" },
+    { url = "https://files.pythonhosted.org/packages/da/92/b25d2ec333615f5f284f3a4024f7ce68cfa0604c322c6808b2344c7f5d2b/jiter-0.13.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f7e1d61da332ec412350463891923f960c3073cf1aae93b538f0bb4c8cd46efb", size = 350560, upload-time = "2026-02-02T12:36:19.746Z" },
+    { url = "https://files.pythonhosted.org/packages/be/ec/74dcb99fef0aca9fbe56b303bf79f6bd839010cb18ad41000bf6cc71eec0/jiter-0.13.0-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:3097d665a27bc96fd9bbf7f86178037db139f319f785e4757ce7ccbf390db6c2", size = 363232, upload-time = "2026-02-02T12:36:21.243Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/37/f17375e0bb2f6a812d4dd92d7616e41917f740f3e71343627da9db2824ce/jiter-0.13.0-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9d01ecc3a8cbdb6f25a37bd500510550b64ddf9f7d64a107d92f3ccb25035d0f", size = 483727, upload-time = "2026-02-02T12:36:22.688Z" },
+    { url = "https://files.pythonhosted.org/packages/77/d2/a71160a5ae1a1e66c1395b37ef77da67513b0adba73b993a27fbe47eb048/jiter-0.13.0-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:ed9bbc30f5d60a3bdf63ae76beb3f9db280d7f195dfcfa61af792d6ce912d159", size = 370799, upload-time = "2026-02-02T12:36:24.106Z" },
+    { url = "https://files.pythonhosted.org/packages/01/99/ed5e478ff0eb4e8aa5fd998f9d69603c9fd3f32de3bd16c2b1194f68361c/jiter-0.13.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:98fbafb6e88256f4454de33c1f40203d09fc33ed19162a68b3b257b29ca7f663", size = 359120, upload-time = "2026-02-02T12:36:25.519Z" },
+    { url = "https://files.pythonhosted.org/packages/16/be/7ffd08203277a813f732ba897352797fa9493faf8dc7995b31f3d9cb9488/jiter-0.13.0-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:5467696f6b827f1116556cb0db620440380434591e93ecee7fd14d1a491b6daa", size = 390664, upload-time = "2026-02-02T12:36:26.866Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/84/e0787856196d6d346264d6dcccb01f741e5f0bd014c1d9a2ebe149caf4f3/jiter-0.13.0-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:2d08c9475d48b92892583df9da592a0e2ac49bcd41fae1fec4f39ba6cf107820", size = 513543, upload-time = "2026-02-02T12:36:28.217Z" },
+    { url = "https://files.pythonhosted.org/packages/65/50/ecbd258181c4313cf79bca6c88fb63207d04d5bf5e4f65174114d072aa55/jiter-0.13.0-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:aed40e099404721d7fcaf5b89bd3b4568a4666358bcac7b6b15c09fb6252ab68", size = 547262, upload-time = "2026-02-02T12:36:29.678Z" },
+    { url = "https://files.pythonhosted.org/packages/27/da/68f38d12e7111d2016cd198161b36e1f042bd115c169255bcb7ec823a3bf/jiter-0.13.0-cp313-cp313-win32.whl", hash = "sha256:36ebfbcffafb146d0e6ffb3e74d51e03d9c35ce7c625c8066cdbfc7b953bdc72", size = 200630, upload-time = "2026-02-02T12:36:31.808Z" },
+    { url = "https://files.pythonhosted.org/packages/25/65/3bd1a972c9a08ecd22eb3b08a95d1941ebe6938aea620c246cf426ae09c2/jiter-0.13.0-cp313-cp313-win_amd64.whl", hash = "sha256:8d76029f077379374cf0dbc78dbe45b38dec4a2eb78b08b5194ce836b2517afc", size = 202602, upload-time = "2026-02-02T12:36:33.679Z" },
+    { url = "https://files.pythonhosted.org/packages/15/fe/13bd3678a311aa67686bb303654792c48206a112068f8b0b21426eb6851e/jiter-0.13.0-cp313-cp313-win_arm64.whl", hash = "sha256:bb7613e1a427cfcb6ea4544f9ac566b93d5bf67e0d48c787eca673ff9c9dff2b", size = 185939, upload-time = "2026-02-02T12:36:35.065Z" },
+    { url = "https://files.pythonhosted.org/packages/49/19/a929ec002ad3228bc97ca01dbb14f7632fffdc84a95ec92ceaf4145688ae/jiter-0.13.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:fa476ab5dd49f3bf3a168e05f89358c75a17608dbabb080ef65f96b27c19ab10", size = 316616, upload-time = "2026-02-02T12:36:36.579Z" },
+    { url = "https://files.pythonhosted.org/packages/52/56/d19a9a194afa37c1728831e5fb81b7722c3de18a3109e8f282bfc23e587a/jiter-0.13.0-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ade8cb6ff5632a62b7dbd4757d8c5573f7a2e9ae285d6b5b841707d8363205ef", size = 346850, upload-time = "2026-02-02T12:36:38.058Z" },
+    { url = "https://files.pythonhosted.org/packages/36/4a/94e831c6bf287754a8a019cb966ed39ff8be6ab78cadecf08df3bb02d505/jiter-0.13.0-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9950290340acc1adaded363edd94baebcee7dabdfa8bee4790794cd5cfad2af6", size = 358551, upload-time = "2026-02-02T12:36:39.417Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/ec/a4c72c822695fa80e55d2b4142b73f0012035d9fcf90eccc56bc060db37c/jiter-0.13.0-cp313-cp313t-win_amd64.whl", hash = "sha256:2b4972c6df33731aac0742b64fd0d18e0a69bc7d6e03108ce7d40c85fd9e3e6d", size = 201950, upload-time = "2026-02-02T12:36:40.791Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/00/393553ec27b824fbc29047e9c7cd4a3951d7fbe4a76743f17e44034fa4e4/jiter-0.13.0-cp313-cp313t-win_arm64.whl", hash = "sha256:701a1e77d1e593c1b435315ff625fd071f0998c5f02792038a5ca98899261b7d", size = 185852, upload-time = "2026-02-02T12:36:42.077Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/f5/f1997e987211f6f9bd71b8083047b316208b4aca0b529bb5f8c96c89ef3e/jiter-0.13.0-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:cc5223ab19fe25e2f0bf2643204ad7318896fe3729bf12fde41b77bfc4fafff0", size = 308804, upload-time = "2026-02-02T12:36:43.496Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/8f/5482a7677731fd44881f0204981ce2d7175db271f82cba2085dd2212e095/jiter-0.13.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:9776ebe51713acf438fd9b4405fcd86893ae5d03487546dae7f34993217f8a91", size = 318787, upload-time = "2026-02-02T12:36:45.071Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/b9/7257ac59778f1cd025b26a23c5520a36a424f7f1b068f2442a5b499b7464/jiter-0.13.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:879e768938e7b49b5e90b7e3fecc0dbec01b8cb89595861fb39a8967c5220d09", size = 353880, upload-time = "2026-02-02T12:36:47.365Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/87/719eec4a3f0841dad99e3d3604ee4cba36af4419a76f3cb0b8e2e691ad67/jiter-0.13.0-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:682161a67adea11e3aae9038c06c8b4a9a71023228767477d683f69903ebc607", size = 366702, upload-time = "2026-02-02T12:36:48.871Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/65/415f0a75cf6921e43365a1bc227c565cb949caca8b7532776e430cbaa530/jiter-0.13.0-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:a13b68cd1cd8cc9de8f244ebae18ccb3e4067ad205220ef324c39181e23bbf66", size = 486319, upload-time = "2026-02-02T12:36:53.006Z" },
+    { url = "https://files.pythonhosted.org/packages/54/a2/9e12b48e82c6bbc6081fd81abf915e1443add1b13d8fc586e1d90bb02bb8/jiter-0.13.0-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:87ce0f14c6c08892b610686ae8be350bf368467b6acd5085a5b65441e2bf36d2", size = 372289, upload-time = "2026-02-02T12:36:54.593Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/c1/e4693f107a1789a239c759a432e9afc592366f04e901470c2af89cfd28e1/jiter-0.13.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0c365005b05505a90d1c47856420980d0237adf82f70c4aff7aebd3c1cc143ad", size = 360165, upload-time = "2026-02-02T12:36:56.112Z" },
+    { url = "https://files.pythonhosted.org/packages/17/08/91b9ea976c1c758240614bd88442681a87672eebc3d9a6dde476874e706b/jiter-0.13.0-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:1317fdffd16f5873e46ce27d0e0f7f4f90f0cdf1d86bf6abeaea9f63ca2c401d", size = 389634, upload-time = "2026-02-02T12:36:57.495Z" },
+    { url = "https://files.pythonhosted.org/packages/18/23/58325ef99390d6d40427ed6005bf1ad54f2577866594bcf13ce55675f87d/jiter-0.13.0-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:c05b450d37ba0c9e21c77fef1f205f56bcee2330bddca68d344baebfc55ae0df", size = 514933, upload-time = "2026-02-02T12:36:58.909Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/25/69f1120c7c395fd276c3996bb8adefa9c6b84c12bb7111e5c6ccdcd8526d/jiter-0.13.0-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:775e10de3849d0631a97c603f996f518159272db00fdda0a780f81752255ee9d", size = 548842, upload-time = "2026-02-02T12:37:00.433Z" },
+    { url = "https://files.pythonhosted.org/packages/18/05/981c9669d86850c5fbb0d9e62bba144787f9fba84546ba43d624ee27ef29/jiter-0.13.0-cp314-cp314-win32.whl", hash = "sha256:632bf7c1d28421c00dd8bbb8a3bac5663e1f57d5cd5ed962bce3c73bf62608e6", size = 202108, upload-time = "2026-02-02T12:37:01.718Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/96/cdcf54dd0b0341db7d25413229888a346c7130bd20820530905fdb65727b/jiter-0.13.0-cp314-cp314-win_amd64.whl", hash = "sha256:f22ef501c3f87ede88f23f9b11e608581c14f04db59b6a801f354397ae13739f", size = 204027, upload-time = "2026-02-02T12:37:03.075Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/f9/724bcaaab7a3cd727031fe4f6995cb86c4bd344909177c186699c8dec51a/jiter-0.13.0-cp314-cp314-win_arm64.whl", hash = "sha256:07b75fe09a4ee8e0c606200622e571e44943f47254f95e2436c8bdcaceb36d7d", size = 187199, upload-time = "2026-02-02T12:37:04.414Z" },
+    { url = "https://files.pythonhosted.org/packages/62/92/1661d8b9fd6a3d7a2d89831db26fe3c1509a287d83ad7838831c7b7a5c7e/jiter-0.13.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:964538479359059a35fb400e769295d4b315ae61e4105396d355a12f7fef09f0", size = 318423, upload-time = "2026-02-02T12:37:05.806Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/3b/f77d342a54d4ebcd128e520fc58ec2f5b30a423b0fd26acdfc0c6fef8e26/jiter-0.13.0-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e104da1db1c0991b3eaed391ccd650ae8d947eab1480c733e5a3fb28d4313e40", size = 351438, upload-time = "2026-02-02T12:37:07.189Z" },
+    { url = "https://files.pythonhosted.org/packages/76/b3/ba9a69f0e4209bd3331470c723c2f5509e6f0482e416b612431a5061ed71/jiter-0.13.0-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:0e3a5f0cde8ff433b8e88e41aa40131455420fb3649a3c7abdda6145f8cb7202", size = 364774, upload-time = "2026-02-02T12:37:08.579Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/16/6cdb31fa342932602458dbb631bfbd47f601e03d2e4950740e0b2100b570/jiter-0.13.0-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:57aab48f40be1db920a582b30b116fe2435d184f77f0e4226f546794cedd9cf0", size = 487238, upload-time = "2026-02-02T12:37:10.066Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/b1/956cc7abaca8d95c13aa8d6c9b3f3797241c246cd6e792934cc4c8b250d2/jiter-0.13.0-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:7772115877c53f62beeb8fd853cab692dbc04374ef623b30f997959a4c0e7e95", size = 372892, upload-time = "2026-02-02T12:37:11.656Z" },
+    { url = "https://files.pythonhosted.org/packages/26/c4/97ecde8b1e74f67b8598c57c6fccf6df86ea7861ed29da84629cdbba76c4/jiter-0.13.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1211427574b17b633cfceba5040de8081e5abf114f7a7602f73d2e16f9fdaa59", size = 360309, upload-time = "2026-02-02T12:37:13.244Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/d7/eabe3cf46715854ccc80be2cd78dd4c36aedeb30751dbf85a1d08c14373c/jiter-0.13.0-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:7beae3a3d3b5212d3a55d2961db3c292e02e302feb43fce6a3f7a31b90ea6dfe", size = 389607, upload-time = "2026-02-02T12:37:14.881Z" },
+    { url = "https://files.pythonhosted.org/packages/df/2d/03963fc0804e6109b82decfb9974eb92df3797fe7222428cae12f8ccaa0c/jiter-0.13.0-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:e5562a0f0e90a6223b704163ea28e831bd3a9faa3512a711f031611e6b06c939", size = 514986, upload-time = "2026-02-02T12:37:16.326Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/6c/8c83b45eb3eb1c1e18d841fe30b4b5bc5619d781267ca9bc03e005d8fd0a/jiter-0.13.0-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:6c26a424569a59140fb51160a56df13f438a2b0967365e987889186d5fc2f6f9", size = 548756, upload-time = "2026-02-02T12:37:17.736Z" },
+    { url = "https://files.pythonhosted.org/packages/47/66/eea81dfff765ed66c68fd2ed8c96245109e13c896c2a5015c7839c92367e/jiter-0.13.0-cp314-cp314t-win32.whl", hash = "sha256:24dc96eca9f84da4131cdf87a95e6ce36765c3b156fc9ae33280873b1c32d5f6", size = 201196, upload-time = "2026-02-02T12:37:19.101Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/32/4ac9c7a76402f8f00d00842a7f6b83b284d0cf7c1e9d4227bc95aa6d17fa/jiter-0.13.0-cp314-cp314t-win_amd64.whl", hash = "sha256:0a8d76c7524087272c8ae913f5d9d608bd839154b62c4322ef65723d2e5bb0b8", size = 204215, upload-time = "2026-02-02T12:37:20.495Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/8e/7def204fea9f9be8b3c21a6f2dd6c020cf56c7d5ff753e0e23ed7f9ea57e/jiter-0.13.0-cp314-cp314t-win_arm64.whl", hash = "sha256:2c26cf47e2cad140fa23b6d58d435a7c0161f5c514284802f25e87fddfe11024", size = 187152, upload-time = "2026-02-02T12:37:22.124Z" },
+    { url = "https://files.pythonhosted.org/packages/79/b3/3c29819a27178d0e461a8571fb63c6ae38be6dc36b78b3ec2876bbd6a910/jiter-0.13.0-graalpy311-graalpy242_311_native-macosx_10_12_x86_64.whl", hash = "sha256:b1cbfa133241d0e6bdab48dcdc2604e8ba81512f6bbd68ec3e8e1357dd3c316c", size = 307016, upload-time = "2026-02-02T12:37:42.755Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/ae/60993e4b07b1ac5ebe46da7aa99fdbb802eb986c38d26e3883ac0125c4e0/jiter-0.13.0-graalpy311-graalpy242_311_native-macosx_11_0_arm64.whl", hash = "sha256:db367d8be9fad6e8ebbac4a7578b7af562e506211036cba2c06c3b998603c3d2", size = 305024, upload-time = "2026-02-02T12:37:44.774Z" },
+    { url = "https://files.pythonhosted.org/packages/77/fa/2227e590e9cf98803db2811f172b2d6460a21539ab73006f251c66f44b14/jiter-0.13.0-graalpy311-graalpy242_311_native-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:45f6f8efb2f3b0603092401dc2df79fa89ccbc027aaba4174d2d4133ed661434", size = 339337, upload-time = "2026-02-02T12:37:46.668Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/92/015173281f7eb96c0ef580c997da8ef50870d4f7f4c9e03c845a1d62ae04/jiter-0.13.0-graalpy311-graalpy242_311_native-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:597245258e6ad085d064780abfb23a284d418d3e61c57362d9449c6c7317ee2d", size = 346395, upload-time = "2026-02-02T12:37:48.09Z" },
+    { url = "https://files.pythonhosted.org/packages/80/60/e50fa45dd7e2eae049f0ce964663849e897300433921198aef94b6ffa23a/jiter-0.13.0-graalpy312-graalpy250_312_native-macosx_10_12_x86_64.whl", hash = "sha256:3d744a6061afba08dd7ae375dcde870cffb14429b7477e10f67e9e6d68772a0a", size = 305169, upload-time = "2026-02-02T12:37:50.376Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/73/a009f41c5eed71c49bec53036c4b33555afcdee70682a18c6f66e396c039/jiter-0.13.0-graalpy312-graalpy250_312_native-macosx_11_0_arm64.whl", hash = "sha256:ff732bd0a0e778f43d5009840f20b935e79087b4dc65bd36f1cd0f9b04b8ff7f", size = 303808, upload-time = "2026-02-02T12:37:52.092Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/10/528b439290763bff3d939268085d03382471b442f212dca4ff5f12802d43/jiter-0.13.0-graalpy312-graalpy250_312_native-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ab44b178f7981fcaea7e0a5df20e773c663d06ffda0198f1a524e91b2fde7e59", size = 337384, upload-time = "2026-02-02T12:37:53.582Z" },
+    { url = "https://files.pythonhosted.org/packages/67/8a/a342b2f0251f3dac4ca17618265d93bf244a2a4d089126e81e4c1056ac50/jiter-0.13.0-graalpy312-graalpy250_312_native-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7bb00b6d26db67a05fe3e12c76edc75f32077fb51deed13822dc648fa373bc19", size = 343768, upload-time = "2026-02-02T12:37:55.055Z" },
+]
+
+[[package]]
+name = "joserfc"
+version = "1.6.8"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cryptography" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5d/ac/d4fd5b30f82900eac60d765f179f0ba005825ac462cc8ced6e13ec685ab3/joserfc-1.6.8.tar.gz", hash = "sha256:878620c553a6ebdd76ccdc356782fee3f735f21a356d079a546b42a4670ace5f", size = 232930, upload-time = "2026-05-27T03:22:37.819Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/98/8c/5cdce2cf3ce8155849baf9a5e2ce77e89dc87ec3bdb38259e5d85fbc45bd/joserfc-1.6.8-py3-none-any.whl", hash = "sha256:22fb31a69094a5e6f44632002a9df2c30c941fc6c8ce1b037e92c03de954cf9f", size = 70927, upload-time = "2026-05-27T03:22:35.796Z" },
+]
+
+[[package]]
+name = "jsonref"
+version = "1.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/aa/0d/c1f3277e90ccdb50d33ed5ba1ec5b3f0a242ed8c1b1a85d3afeb68464dca/jsonref-1.1.0.tar.gz", hash = "sha256:32fe8e1d85af0fdefbebce950af85590b22b60f9e95443176adbde4e1ecea552", size = 8814, upload-time = "2023-01-16T16:10:04.455Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0c/ec/e1db9922bceb168197a558a2b8c03a7963f1afe93517ddd3cf99f202f996/jsonref-1.1.0-py3-none-any.whl", hash = "sha256:590dc7773df6c21cbf948b5dac07a72a251db28b0238ceecce0a2abfa8ec30a9", size = 9425, upload-time = "2023-01-16T16:10:02.255Z" },
+]
+
+[[package]]
+name = "jsonschema"
+version = "4.26.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "attrs" },
+    { name = "jsonschema-specifications" },
+    { name = "referencing" },
+    { name = "rpds-py" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b3/fc/e067678238fa451312d4c62bf6e6cf5ec56375422aee02f9cb5f909b3047/jsonschema-4.26.0.tar.gz", hash = "sha256:0c26707e2efad8aa1bfc5b7ce170f3fccc2e4918ff85989ba9ffa9facb2be326", size = 366583, upload-time = "2026-01-07T13:41:07.246Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/69/90/f63fb5873511e014207a475e2bb4e8b2e570d655b00ac19a9a0ca0a385ee/jsonschema-4.26.0-py3-none-any.whl", hash = "sha256:d489f15263b8d200f8387e64b4c3a75f06629559fb73deb8fdfb525f2dab50ce", size = 90630, upload-time = "2026-01-07T13:41:05.306Z" },
+]
+
+[[package]]
+name = "jsonschema-path"
+version = "0.4.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pathable" },
+    { name = "pyyaml" },
+    { name = "referencing" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5b/8a/7e6102f2b8bdc6705a9eb5294f8f6f9ccd3a8420e8e8e19671d1dd773251/jsonschema_path-0.4.5.tar.gz", hash = "sha256:c6cd7d577ae290c7defd4f4029e86fdb248ca1bd41a07557795b3c95e5144918", size = 15113, upload-time = "2026-03-03T09:56:46.87Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/04/d5/4e96c44f6c1ea3d812cf5391d81a4f5abaa540abf8d04ecd7f66e0ed11df/jsonschema_path-0.4.5-py3-none-any.whl", hash = "sha256:7d77a2c3f3ec569a40efe5c5f942c44c1af2a6f96fe0866794c9ef5b8f87fd65", size = 19368, upload-time = "2026-03-03T09:56:45.39Z" },
+]
+
+[[package]]
+name = "jsonschema-specifications"
+version = "2025.9.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "referencing" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/19/74/a633ee74eb36c44aa6d1095e7cc5569bebf04342ee146178e2d36600708b/jsonschema_specifications-2025.9.1.tar.gz", hash = "sha256:b540987f239e745613c7a9176f3edb72b832a4ac465cf02712288397832b5e8d", size = 32855, upload-time = "2025-09-08T01:34:59.186Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/41/45/1a4ed80516f02155c51f51e8cedb3c1902296743db0bbc66608a0db2814f/jsonschema_specifications-2025.9.1-py3-none-any.whl", hash = "sha256:98802fee3a11ee76ecaca44429fda8a41bff98b00a0f2838151b113f210cc6fe", size = 18437, upload-time = "2025-09-08T01:34:57.871Z" },
+]
+
+[[package]]
+name = "keyring"
+version = "25.7.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "importlib-metadata", marker = "python_full_version < '3.12'" },
+    { name = "jaraco-classes" },
+    { name = "jaraco-context" },
+    { name = "jaraco-functools" },
+    { name = "jeepney", marker = "sys_platform == 'linux'" },
+    { name = "pywin32-ctypes", marker = "sys_platform == 'win32'" },
+    { name = "secretstorage", marker = "sys_platform == 'linux'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/43/4b/674af6ef2f97d56f0ab5153bf0bfa28ccb6c3ed4d1babf4305449668807b/keyring-25.7.0.tar.gz", hash = "sha256:fe01bd85eb3f8fb3dd0405defdeac9a5b4f6f0439edbb3149577f244a2e8245b", size = 63516, upload-time = "2025-11-16T16:26:09.482Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/81/db/e655086b7f3a705df045bf0933bdd9c2f79bb3c97bfef1384598bb79a217/keyring-25.7.0-py3-none-any.whl", hash = "sha256:be4a0b195f149690c166e850609a477c532ddbfbaed96a404d4e43f8d5e2689f", size = 39160, upload-time = "2025-11-16T16:26:08.402Z" },
+]
+
+[[package]]
+name = "loq"
+version = "0.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/97/81/a17733cc91f34192c7ebfa946df89e14385dc384952485fcacde759d0dc7/loq-0.1.0.tar.gz", hash = "sha256:2c0748bfbd0f36a7899d19bfa50af2609dbdd09351fc8951f7c4741ed4340c86", size = 73416, upload-time = "2026-03-15T15:54:52.304Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7a/24/66fb5fb05c1381d3f7006ed0f3ea02f44e18f8908f616bb4a9c4a052388d/loq-0.1.0-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:3609a7cb924fe3a91f4e2783302f103c4800fb77d3aa44f25751d7e59671b8c4", size = 1348859, upload-time = "2026-03-15T15:54:46.504Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/51/f0e99405c265dd700b6a325bd9c096a2fe6982ec251614470c10ff9ebd44/loq-0.1.0-py3-none-macosx_11_0_arm64.whl", hash = "sha256:06fbbb2d879bec68cbc3bf245ca9c0b3f1b34378520f088d43906ca4b005dcbc", size = 1264194, upload-time = "2026-03-15T15:54:42.6Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/7c/9898a91f70ba757c07395bf4827953245ad1721b03f2a88750d4d789d342/loq-0.1.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:98781f2da950c8a2f8ff1e136f7199abdfd1456b921253e97891eba1a6d8f7d7", size = 1285358, upload-time = "2026-03-15T15:54:44.035Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/a5/57f6a11fa86d3e75f16283dbdb7925796bd430ec298407d2824e23de2740/loq-0.1.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:5f37096eb4e7deb8c11928aad914a472b0b74485a5dbebd16f17f223ef973e22", size = 1389403, upload-time = "2026-03-15T15:54:50.878Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/1e/77fd1ac28d4bbb79a0006a7489aa527e6df00fef7668c47d7a69c46804e8/loq-0.1.0-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:2af38e4e503986b930d036ec867720648a8dff468d6a938b6f3579024deace9c", size = 1334234, upload-time = "2026-03-15T15:54:45.162Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/bd/eaea9d747ac43384c5e319886a23edb6b61007be6ca856f480110a57cb52/loq-0.1.0-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:97fbd077ed12627bc8a9897f863489cc0a535dee884a100c419c8039fd758b64", size = 1457837, upload-time = "2026-03-15T15:54:47.894Z" },
+    { url = "https://files.pythonhosted.org/packages/0e/84/3477378f4a22c89f4b0268ffeb45738fc67d629067bbd6ad9a7de40e0ed0/loq-0.1.0-py3-none-win_amd64.whl", hash = "sha256:dcb0da5c60ba65d8978e91fd0e8116c920c79374dff78092cd1cc6a732fbaebf", size = 1368085, upload-time = "2026-03-15T15:54:49.468Z" },
+]
+
+[[package]]
+name = "markdown-it-py"
+version = "4.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "mdurl" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5b/f5/4ec618ed16cc4f8fb3b701563655a69816155e79e24a17b651541804721d/markdown_it_py-4.0.0.tar.gz", hash = "sha256:cb0a2b4aa34f932c007117b194e945bd74e0ec24133ceb5bac59009cda1cb9f3", size = 73070, upload-time = "2025-08-11T12:57:52.854Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/94/54/e7d793b573f298e1c9013b8c4dade17d481164aa517d1d7148619c2cedbf/markdown_it_py-4.0.0-py3-none-any.whl", hash = "sha256:87327c59b172c5011896038353a81343b6754500a08cd7a4973bb48c6d578147", size = 87321, upload-time = "2025-08-11T12:57:51.923Z" },
+]
+
+[[package]]
+name = "matplotlib-inline"
+version = "0.2.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "traitlets" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c7/74/97e72a36efd4ae2bccb3463284300f8953f199b5ffbc04cbbb0ec78f74b1/matplotlib_inline-0.2.1.tar.gz", hash = "sha256:e1ee949c340d771fc39e241ea75683deb94762c8fa5f2927ec57c83c4dffa9fe", size = 8110, upload-time = "2025-10-23T09:00:22.126Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/af/33/ee4519fa02ed11a94aef9559552f3b17bb863f2ecfe1a35dc7f548cde231/matplotlib_inline-0.2.1-py3-none-any.whl", hash = "sha256:d56ce5156ba6085e00a9d54fead6ed29a9c47e215cd1bba2e976ef39f5710a76", size = 9516, upload-time = "2025-10-23T09:00:20.675Z" },
+]
+
+[[package]]
+name = "mcp"
+version = "2.0.0b1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "httpx" },
+    { name = "httpx-sse" },
+    { name = "jsonschema" },
+    { name = "mcp-types" },
+    { name = "opentelemetry-api" },
+    { name = "pydantic" },
+    { name = "pydantic-settings" },
+    { name = "pyjwt", extra = ["crypto"] },
+    { name = "python-multipart" },
+    { name = "pywin32", marker = "sys_platform == 'win32'" },
+    { name = "sse-starlette" },
+    { name = "starlette" },
+    { name = "typing-extensions" },
+    { name = "typing-inspection" },
+    { name = "uvicorn", marker = "sys_platform != 'emscripten'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d6/78/9f540a2f8f673973c9dee7977d020a0c10b97be3a6417a833bc3af166811/mcp-2.0.0b1.tar.gz", hash = "sha256:f0bb4543507117f872613fc76bd7b73cc2a8f6ddd9426f0402f268447f21b260", size = 1478434, upload-time = "2026-06-30T23:24:38.363Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ac/bb/9c5c4e428e63d40b5542cfc9c61a0438943ccb260bf9929dc02c47527235/mcp-2.0.0b1-py3-none-any.whl", hash = "sha256:7e169929da99487b1998f8f53548bb93ff5157165f2f5a10fb45202c02a91fce", size = 320414, upload-time = "2026-06-30T23:24:34.788Z" },
+]
+
+[[package]]
+name = "mcp-types"
+version = "2.0.0b1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pydantic" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/2b/88/f3e4322a5bfc382f8851e584f2e2c87354467dc17fb602dd4b13dee65b7c/mcp_types-2.0.0b1.tar.gz", hash = "sha256:6a26910a737c4cd4de36c7d5629febe7d33d4556a9d196166b5c7187a6516944", size = 65785, upload-time = "2026-06-30T23:24:39.796Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3f/05/2da79c73dd07d028163c2b24d4cc6e988da11dff83f7902a07d69a87df80/mcp_types-2.0.0b1-py3-none-any.whl", hash = "sha256:c1b22b56b0ba7b1d51c84dc99afdd603ae225c55e9e8f07477774552bf34c8cd", size = 68945, upload-time = "2026-06-30T23:24:36.671Z" },
+]
+
+[[package]]
+name = "mdurl"
+version = "0.1.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d6/54/cfe61301667036ec958cb99bd3efefba235e65cdeb9c84d24a8293ba1d90/mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba", size = 8729, upload-time = "2022-08-14T12:40:10.846Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" },
+]
+
+[[package]]
+name = "more-itertools"
+version = "10.8.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ea/5d/38b681d3fce7a266dd9ab73c66959406d565b3e85f21d5e66e1181d93721/more_itertools-10.8.0.tar.gz", hash = "sha256:f638ddf8a1a0d134181275fb5d58b086ead7c6a72429ad725c67503f13ba30bd", size = 137431, upload-time = "2025-09-02T15:23:11.018Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a4/8e/469e5a4a2f5855992e425f3cb33804cc07bf18d48f2db061aec61ce50270/more_itertools-10.8.0-py3-none-any.whl", hash = "sha256:52d4362373dcf7c52546bc4af9a86ee7c4579df9a8dc268be0a2f949d376cc9b", size = 69667, upload-time = "2025-09-02T15:23:09.635Z" },
+]
+
+[[package]]
+name = "msal"
+version = "1.37.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cryptography" },
+    { name = "pyjwt", extra = ["crypto"] },
+    { name = "requests" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/9a/99/d840198ecf6e8057bbc937f129ae940404485d736cda73253bbff9537f01/msal-1.37.0.tar.gz", hash = "sha256:1b1672a33ee467c1d70b341bb16cafd51bb3c817147a95b93263794b03971bec", size = 182444, upload-time = "2026-05-29T19:49:05.561Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/94/b0/d807279f4b55d16d1f120d5ac4344c6e39b56732e2a224d40bded7fd67ad/msal-1.37.0-py3-none-any.whl", hash = "sha256:dd17e95a7c71bce75e8108113438ba7c4a086b3bcad4f57a8c09b7af3d753c2d", size = 123725, upload-time = "2026-05-29T19:49:04.335Z" },
+]
+
+[[package]]
+name = "msal-extensions"
+version = "1.3.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "msal" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/01/99/5d239b6156eddf761a636bded1118414d161bd6b7b37a9335549ed159396/msal_extensions-1.3.1.tar.gz", hash = "sha256:c5b0fd10f65ef62b5f1d62f4251d51cbcaf003fcedae8c91b040a488614be1a4", size = 23315, upload-time = "2025-03-14T23:51:03.902Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/5e/75/bd9b7bb966668920f06b200e84454c8f3566b102183bc55c5473d96cb2b9/msal_extensions-1.3.1-py3-none-any.whl", hash = "sha256:96d3de4d034504e969ac5e85bae8106c8373b5c6568e4c8fa7af2eca9dbe6bca", size = 20583, upload-time = "2025-03-14T23:51:03.016Z" },
+]
+
+[[package]]
+name = "mypy-extensions"
+version = "1.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a2/6e/371856a3fb9d31ca8dac321cda606860fa4548858c0cc45d9d1d4ca2628b/mypy_extensions-1.1.0.tar.gz", hash = "sha256:52e68efc3284861e772bbcd66823fde5ae21fd2fdb51c62a211403730b916558", size = 6343, upload-time = "2025-04-22T14:54:24.164Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/79/7b/2c79738432f5c924bef5071f933bcc9efd0473bac3b4aa584a6f7c1c8df8/mypy_extensions-1.1.0-py3-none-any.whl", hash = "sha256:1be4cccdb0f2482337c4743e60421de3a356cd97508abadd57d47403e94f5505", size = 4963, upload-time = "2025-04-22T14:54:22.983Z" },
+]
+
+[[package]]
+name = "openai"
+version = "2.30.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "distro" },
+    { name = "httpx" },
+    { name = "jiter" },
+    { name = "pydantic" },
+    { name = "sniffio" },
+    { name = "tqdm" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/88/15/52580c8fbc16d0675d516e8749806eda679b16de1e4434ea06fb6feaa610/openai-2.30.0.tar.gz", hash = "sha256:92f7661c990bda4b22a941806c83eabe4896c3094465030dd882a71abe80c885", size = 676084, upload-time = "2026-03-25T22:08:59.96Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2a/9e/5bfa2270f902d5b92ab7d41ce0475b8630572e71e349b2a4996d14bdda93/openai-2.30.0-py3-none-any.whl", hash = "sha256:9a5ae616888eb2748ec5e0c5b955a51592e0b201a11f4262db920f2a78c5231d", size = 1146656, upload-time = "2026-03-25T22:08:58.2Z" },
+]
+
+[[package]]
+name = "openapi-pydantic"
+version = "0.5.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pydantic" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/02/2e/58d83848dd1a79cb92ed8e63f6ba901ca282c5f09d04af9423ec26c56fd7/openapi_pydantic-0.5.1.tar.gz", hash = "sha256:ff6835af6bde7a459fb93eb93bb92b8749b754fc6e51b2f1590a19dc3005ee0d", size = 60892, upload-time = "2025-01-08T19:29:27.083Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/12/cf/03675d8bd8ecbf4445504d8071adab19f5f993676795708e36402ab38263/openapi_pydantic-0.5.1-py3-none-any.whl", hash = "sha256:a3a09ef4586f5bd760a8df7f43028b60cafb6d9f61de2acba9574766255ab146", size = 96381, upload-time = "2025-01-08T19:29:25.275Z" },
+]
+
+[[package]]
+name = "opentelemetry-api"
+version = "1.40.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "importlib-metadata" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/2c/1d/4049a9e8698361cc1a1aa03a6c59e4fa4c71e0c0f94a30f988a6876a2ae6/opentelemetry_api-1.40.0.tar.gz", hash = "sha256:159be641c0b04d11e9ecd576906462773eb97ae1b657730f0ecf64d32071569f", size = 70851, upload-time = "2026-03-04T14:17:21.555Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/5f/bf/93795954016c522008da367da292adceed71cca6ee1717e1d64c83089099/opentelemetry_api-1.40.0-py3-none-any.whl", hash = "sha256:82dd69331ae74b06f6a874704be0cfaa49a1650e1537d4a813b86ecef7d0ecf9", size = 68676, upload-time = "2026-03-04T14:17:01.24Z" },
+]
+
+[[package]]
+name = "opentelemetry-exporter-otlp-proto-common"
+version = "1.40.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "opentelemetry-proto" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/51/bc/1559d46557fe6eca0b46c88d4c2676285f1f3be2e8d06bb5d15fbffc814a/opentelemetry_exporter_otlp_proto_common-1.40.0.tar.gz", hash = "sha256:1cbee86a4064790b362a86601ee7934f368b81cd4cc2f2e163902a6e7818a0fa", size = 20416, upload-time = "2026-03-04T14:17:23.801Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8b/ca/8f122055c97a932311a3f640273f084e738008933503d0c2563cd5d591fc/opentelemetry_exporter_otlp_proto_common-1.40.0-py3-none-any.whl", hash = "sha256:7081ff453835a82417bf38dccf122c827c3cbc94f2079b03bba02a3165f25149", size = 18369, upload-time = "2026-03-04T14:17:04.796Z" },
+]
+
+[[package]]
+name = "opentelemetry-exporter-otlp-proto-grpc"
+version = "1.40.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "googleapis-common-protos" },
+    { name = "grpcio" },
+    { name = "opentelemetry-api" },
+    { name = "opentelemetry-exporter-otlp-proto-common" },
+    { name = "opentelemetry-proto" },
+    { name = "opentelemetry-sdk" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8f/7f/b9e60435cfcc7590fa87436edad6822240dddbc184643a2a005301cc31f4/opentelemetry_exporter_otlp_proto_grpc-1.40.0.tar.gz", hash = "sha256:bd4015183e40b635b3dab8da528b27161ba83bf4ef545776b196f0fb4ec47740", size = 25759, upload-time = "2026-03-04T14:17:24.4Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/96/6f/7ee0980afcbdcd2d40362da16f7f9796bd083bf7f0b8e038abfbc0300f5d/opentelemetry_exporter_otlp_proto_grpc-1.40.0-py3-none-any.whl", hash = "sha256:2aa0ca53483fe0cf6405087a7491472b70335bc5c7944378a0a8e72e86995c52", size = 20304, upload-time = "2026-03-04T14:17:05.942Z" },
+]
+
+[[package]]
+name = "opentelemetry-proto"
+version = "1.40.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "protobuf" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/4c/77/dd38991db037fdfce45849491cb61de5ab000f49824a00230afb112a4392/opentelemetry_proto-1.40.0.tar.gz", hash = "sha256:03f639ca129ba513f5819810f5b1f42bcb371391405d99c168fe6937c62febcd", size = 45667, upload-time = "2026-03-04T14:17:31.194Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b9/b2/189b2577dde745b15625b3214302605b1353436219d42b7912e77fa8dc24/opentelemetry_proto-1.40.0-py3-none-any.whl", hash = "sha256:266c4385d88923a23d63e353e9761af0f47a6ed0d486979777fe4de59dc9b25f", size = 72073, upload-time = "2026-03-04T14:17:16.673Z" },
+]
+
+[[package]]
+name = "opentelemetry-sdk"
+version = "1.40.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "opentelemetry-api" },
+    { name = "opentelemetry-semantic-conventions" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/58/fd/3c3125b20ba18ce2155ba9ea74acb0ae5d25f8cd39cfd37455601b7955cc/opentelemetry_sdk-1.40.0.tar.gz", hash = "sha256:18e9f5ec20d859d268c7cb3c5198c8d105d073714db3de50b593b8c1345a48f2", size = 184252, upload-time = "2026-03-04T14:17:31.87Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2c/c5/6a852903d8bfac758c6dc6e9a68b015d3c33f2f1be5e9591e0f4b69c7e0a/opentelemetry_sdk-1.40.0-py3-none-any.whl", hash = "sha256:787d2154a71f4b3d81f20524a8ce061b7db667d24e46753f32a7bc48f1c1f3f1", size = 141951, upload-time = "2026-03-04T14:17:17.961Z" },
+]
+
+[[package]]
+name = "opentelemetry-semantic-conventions"
+version = "0.61b0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "opentelemetry-api" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/6d/c0/4ae7973f3c2cfd2b6e321f1675626f0dab0a97027cc7a297474c9c8f3d04/opentelemetry_semantic_conventions-0.61b0.tar.gz", hash = "sha256:072f65473c5d7c6dc0355b27d6c9d1a679d63b6d4b4b16a9773062cb7e31192a", size = 145755, upload-time = "2026-03-04T14:17:32.664Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b2/37/cc6a55e448deaa9b27377d087da8615a3416d8ad523d5960b78dbeadd02a/opentelemetry_semantic_conventions-0.61b0-py3-none-any.whl", hash = "sha256:fa530a96be229795f8cef353739b618148b0fe2b4b3f005e60e262926c4d38e2", size = 231621, upload-time = "2026-03-04T14:17:19.33Z" },
+]
+
+[[package]]
+name = "packaging"
+version = "26.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/65/ee/299d360cdc32edc7d2cf530f3accf79c4fca01e96ffc950d8a52213bd8e4/packaging-26.0.tar.gz", hash = "sha256:00243ae351a257117b6a241061796684b084ed1c516a08c48a3f7e147a9d80b4", size = 143416, upload-time = "2026-01-21T20:50:39.064Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b7/b9/c538f279a4e237a006a2c98387d081e9eb060d203d8ed34467cc0f0b9b53/packaging-26.0-py3-none-any.whl", hash = "sha256:b36f1fef9334a5588b4166f8bcd26a14e521f2b55e6b9de3aaa80d3ff7a37529", size = 74366, upload-time = "2026-01-21T20:50:37.788Z" },
+]
+
+[[package]]
+name = "parso"
+version = "0.8.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/81/76/a1e769043c0c0c9fe391b702539d594731a4362334cdf4dc25d0c09761e7/parso-0.8.6.tar.gz", hash = "sha256:2b9a0332696df97d454fa67b81618fd69c35a7b90327cbe6ba5c92d2c68a7bfd", size = 401621, upload-time = "2026-02-09T15:45:24.425Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b6/61/fae042894f4296ec49e3f193aff5d7c18440da9e48102c3315e1bc4519a7/parso-0.8.6-py2.py3-none-any.whl", hash = "sha256:2c549f800b70a5c4952197248825584cb00f033b29c692671d3bf08bf380baff", size = 106894, upload-time = "2026-02-09T15:45:21.391Z" },
+]
+
+[[package]]
+name = "pathable"
+version = "0.5.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/55/b748445cb4ea6b125626f15379be7c96d1035d4fa3e8fee362fa92298abf/pathable-0.5.0.tar.gz", hash = "sha256:d81938348a1cacb525e7c75166270644782c0fb9c8cecc16be033e71427e0ef1", size = 16655, upload-time = "2026-02-20T08:47:00.748Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/52/96/5a770e5c461462575474468e5af931cff9de036e7c2b4fea23c1c58d2cbe/pathable-0.5.0-py3-none-any.whl", hash = "sha256:646e3d09491a6351a0c82632a09c02cdf70a252e73196b36d8a15ba0a114f0a6", size = 16867, upload-time = "2026-02-20T08:46:59.536Z" },
+]
+
+[[package]]
+name = "pathspec"
+version = "1.0.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/fa/36/e27608899f9b8d4dff0617b2d9ab17ca5608956ca44461ac14ac48b44015/pathspec-1.0.4.tar.gz", hash = "sha256:0210e2ae8a21a9137c0d470578cb0e595af87edaa6ebf12ff176f14a02e0e645", size = 131200, upload-time = "2026-01-27T03:59:46.938Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ef/3c/2c197d226f9ea224a9ab8d197933f9da0ae0aac5b6e0f884e2b8d9c8e9f7/pathspec-1.0.4-py3-none-any.whl", hash = "sha256:fb6ae2fd4e7c921a165808a552060e722767cfa526f99ca5156ed2ce45a5c723", size = 55206, upload-time = "2026-01-27T03:59:45.137Z" },
+]
+
+[[package]]
+name = "pdbpp"
+version = "0.12.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "fancycompleter" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/95/8d/dbc2c26f9c947e3d6df82d3ee7711fb52a92000177cea22fd3e428dc0429/pdbpp-0.12.1.tar.gz", hash = "sha256:932cc5963760105e33607f44a1a3b83d28096d7dbf055b77b527c5c70a1dafef", size = 77358, upload-time = "2026-02-23T14:23:44.993Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/05/4e/0703722c46447fa03c9425386b3ef3e90254a7c1eb5da654c3c33b210317/pdbpp-0.12.1-py3-none-any.whl", hash = "sha256:3828809519439f468c9475c4c2cbb3899f2f5ba40e79c207d90eabe4c2373f5e", size = 30659, upload-time = "2026-02-23T14:23:43.66Z" },
+]
+
+[[package]]
+name = "pexpect"
+version = "4.9.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "ptyprocess" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/42/92/cc564bf6381ff43ce1f4d06852fc19a2f11d180f23dc32d9588bee2f149d/pexpect-4.9.0.tar.gz", hash = "sha256:ee7d41123f3c9911050ea2c2dac107568dc43b2d3b0c7557a33212c398ead30f", size = 166450, upload-time = "2023-11-25T09:07:26.339Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9e/c3/059298687310d527a58bb01f3b1965787ee3b40dce76752eda8b44e9a2c5/pexpect-4.9.0-py2.py3-none-any.whl", hash = "sha256:7236d1e080e4936be2dc3e326cec0af72acf9212a7e1d060210e70a47e253523", size = 63772, upload-time = "2023-11-25T06:56:14.81Z" },
+]
+
+[[package]]
+name = "platformdirs"
+version = "4.9.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/19/56/8d4c30c8a1d07013911a8fdbd8f89440ef9f08d07a1b50ab8ca8be5a20f9/platformdirs-4.9.4.tar.gz", hash = "sha256:1ec356301b7dc906d83f371c8f487070e99d3ccf9e501686456394622a01a934", size = 28737, upload-time = "2026-03-05T18:34:13.271Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/63/d7/97f7e3a6abb67d8080dd406fd4df842c2be0efaf712d1c899c32a075027c/platformdirs-4.9.4-py3-none-any.whl", hash = "sha256:68a9a4619a666ea6439f2ff250c12a853cd1cbd5158d258bd824a7df6be2f868", size = 21216, upload-time = "2026-03-05T18:34:12.172Z" },
+]
+
+[[package]]
+name = "pluggy"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f9/e2/3e91f31a7d2b083fe6ef3fa267035b518369d9511ffab804f839851d2779/pluggy-1.6.0.tar.gz", hash = "sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3", size = 69412, upload-time = "2025-05-15T12:30:07.975Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" },
+]
+
+[[package]]
+name = "prefab-ui"
+version = "0.18.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cyclopts" },
+    { name = "pydantic" },
+    { name = "rich" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/2f/a3/25fe72b9887d9c2daa0ec5e79a7971a67aad31a6f71d634e23da662343ad/prefab_ui-0.18.0.tar.gz", hash = "sha256:f72e241f52f4720baac670f8527c773e1c1f4b558bce4f77097441eecbb51b9e", size = 3998186, upload-time = "2026-03-30T01:13:33.419Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c0/dd/28be02a264c59d64086122c8b0f9fa99fc52e040682358e5e08219846961/prefab_ui-0.18.0-py3-none-any.whl", hash = "sha256:c9d01bd423b0d5bf103d9a0e6cfac135bd973d416297c32a5bbccc182161cace", size = 1824803, upload-time = "2026-03-30T01:13:31.243Z" },
+]
+
+[[package]]
+name = "prek"
+version = "0.3.8"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/62/ee/03e8180e3fda9de25b6480bd15cc2bde40d573868d50648b0e527b35562f/prek-0.3.8.tar.gz", hash = "sha256:434a214256516f187a3ab15f869d950243be66b94ad47987ee4281b69643a2d9", size = 400224, upload-time = "2026-03-23T08:23:35.981Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/00/84/40d2ddf362d12c4cd4a25a8c89a862edf87cdfbf1422aa41aac8e315d409/prek-0.3.8-py3-none-linux_armv6l.whl", hash = "sha256:6fb646ada60658fa6dd7771b2e0fb097f005151be222f869dada3eb26d79ed33", size = 5226646, upload-time = "2026-03-23T08:23:18.306Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/52/7308a033fa43b7e8e188797bd2b3b017c0f0adda70fa7af575b1f43ea888/prek-0.3.8-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:f3d7fdadb15efc19c09953c7a33cf2061a70f367d1e1957358d3ad5cc49d0616", size = 5620104, upload-time = "2026-03-23T08:23:40.053Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/b1/f106ac000a91511a9cd80169868daf2f5b693480ef5232cec5517a38a512/prek-0.3.8-py3-none-macosx_11_0_arm64.whl", hash = "sha256:72728c3295e79ca443f8c1ec037d2a5b914ec73a358f69cf1bc1964511876bf8", size = 5199867, upload-time = "2026-03-23T08:23:38.066Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/e9/970713f4b019f69de9844e1bab37b8ddb67558e410916f4eb5869a696165/prek-0.3.8-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_1_aarch64.whl", hash = "sha256:48efc28f2f53b5b8087efca9daaed91572d62df97d5f24a1c7a087fecb5017de", size = 5441801, upload-time = "2026-03-23T08:23:32.617Z" },
+    { url = "https://files.pythonhosted.org/packages/12/a4/7ef44032b181753e19452ec3b09abb3a32607cf6b0a0508f0604becaaf2b/prek-0.3.8-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:f6ca9d63bacbc448a5c18e955c78d3ac5176c3a17c3baacdd949b1a623e08a36", size = 5155107, upload-time = "2026-03-23T08:23:31.021Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/77/4d9c8985dbba84149760785dfe07093ea1e29d710257dfb7c89615e2234c/prek-0.3.8-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:1000f7029696b4fe712fb1fefd4c55b9c4de72b65509c8e50296370a06f9dc3f", size = 5566541, upload-time = "2026-03-23T08:23:45.694Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/1a/81e6769ac1f7f8346d09ce2ab0b47cf06466acd9ff72e87e5d1f0d98cd32/prek-0.3.8-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:6ff0bed0e2c1286522987d982168a86cbbd0d069d840506a46c9fda983515517", size = 6552991, upload-time = "2026-03-23T08:23:21.958Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/fa/ce2df0dd2dc75a9437a52463239d0782998943d7b04e191fb89b83016c34/prek-0.3.8-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:4fb087ac0ffda3ac65bbbae9a38326a7fd27ee007bb4a94323ce1eb539d8bbec", size = 5832972, upload-time = "2026-03-23T08:23:20.258Z" },
+    { url = "https://files.pythonhosted.org/packages/18/6b/9d4269df9073216d296244595a21c253b6475dfc9076c0bd2906be7a436c/prek-0.3.8-py3-none-manylinux_2_28_aarch64.whl", hash = "sha256:2e1e5e206ff7b31bd079cce525daddc96cd6bc544d20dc128921ad92f7a4c85d", size = 5448371, upload-time = "2026-03-23T08:23:41.835Z" },
+    { url = "https://files.pythonhosted.org/packages/60/1d/1e4d8a78abefa5b9d086e5a9f1638a74b5e540eec8a648d9946707701f29/prek-0.3.8-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:dcea3fe23832a4481bccb7c45f55650cb233be7c805602e788bb7dba60f2d861", size = 5270546, upload-time = "2026-03-23T08:23:24.231Z" },
+    { url = "https://files.pythonhosted.org/packages/77/07/34f36551a6319ae36e272bea63a42f59d41d2d47ab0d5fb00eb7b4e88e87/prek-0.3.8-py3-none-musllinux_1_1_armv7l.whl", hash = "sha256:4d25e647e9682f6818ab5c31e7a4b842993c14782a6ffcd128d22b784e0d677f", size = 5124032, upload-time = "2026-03-23T08:23:26.368Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/01/6d544009bb655e709993411796af77339f439526db4f3b3509c583ad8eb9/prek-0.3.8-py3-none-musllinux_1_1_i686.whl", hash = "sha256:de528b82935e33074815acff3c7c86026754d1212136295bc88fe9c43b4231d5", size = 5432245, upload-time = "2026-03-23T08:23:47.877Z" },
+    { url = "https://files.pythonhosted.org/packages/54/96/1237ee269e9bfa283ffadbcba1f401f48a47aed2b2563eb1002740d6079d/prek-0.3.8-py3-none-musllinux_1_1_x86_64.whl", hash = "sha256:6d660f1c25a126e6d9f682fe61449441226514f412a4469f5d71f8f8cad56db2", size = 5950550, upload-time = "2026-03-23T08:23:43.8Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/6b/a574411459049bc691047c9912f375deda10c44a707b6ce98df2b658f0b3/prek-0.3.8-py3-none-win32.whl", hash = "sha256:b0c291c577615d9f8450421dff0b32bfd77a6b0d223ee4115a1f820cb636fdf1", size = 4949501, upload-time = "2026-03-23T08:23:16.338Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/b4/46b59fe49f635acd9f6530778ce577f9d8b49452835726a5311ffc902c67/prek-0.3.8-py3-none-win_amd64.whl", hash = "sha256:bc147fdbdd4ec33fc7a987b893ecb69b1413ac100d95c9889a70f3fd58c73d06", size = 5346551, upload-time = "2026-03-23T08:23:34.501Z" },
+    { url = "https://files.pythonhosted.org/packages/53/05/9cca1708bb8c65264124eb4b04251e0f65ce5bfc707080bb6b492d5a0df7/prek-0.3.8-py3-none-win_arm64.whl", hash = "sha256:a2614647aeafa817a5802ccb9561e92eedc20dcf840639a1b00826e2c2442515", size = 5190872, upload-time = "2026-03-23T08:23:29.463Z" },
+]
+
+[[package]]
+name = "prometheus-client"
+version = "0.24.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f0/58/a794d23feb6b00fc0c72787d7e87d872a6730dd9ed7c7b3e954637d8f280/prometheus_client-0.24.1.tar.gz", hash = "sha256:7e0ced7fbbd40f7b84962d5d2ab6f17ef88a72504dcf7c0b40737b43b2a461f9", size = 85616, upload-time = "2026-01-14T15:26:26.965Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/74/c3/24a2f845e3917201628ecaba4f18bab4d18a337834c1df2a159ee9d22a42/prometheus_client-0.24.1-py3-none-any.whl", hash = "sha256:150db128af71a5c2482b36e588fc8a6b95e498750da4b17065947c16070f4055", size = 64057, upload-time = "2026-01-14T15:26:24.42Z" },
+]
+
+[[package]]
+name = "prompt-toolkit"
+version = "3.0.52"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "wcwidth" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a1/96/06e01a7b38dce6fe1db213e061a4602dd6032a8a97ef6c1a862537732421/prompt_toolkit-3.0.52.tar.gz", hash = "sha256:28cde192929c8e7321de85de1ddbe736f1375148b02f2e17edd840042b1be855", size = 434198, upload-time = "2025-08-27T15:24:02.057Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/84/03/0d3ce49e2505ae70cf43bc5bb3033955d2fc9f932163e84dc0779cc47f48/prompt_toolkit-3.0.52-py3-none-any.whl", hash = "sha256:9aac639a3bbd33284347de5ad8d68ecc044b91a762dc39b7c21095fcd6a19955", size = 391431, upload-time = "2025-08-27T15:23:59.498Z" },
+]
+
+[[package]]
+name = "protobuf"
+version = "6.33.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/66/70/e908e9c5e52ef7c3a6c7902c9dfbb34c7e29c25d2f81ade3856445fd5c94/protobuf-6.33.6.tar.gz", hash = "sha256:a6768d25248312c297558af96a9f9c929e8c4cee0659cb07e780731095f38135", size = 444531, upload-time = "2026-03-18T19:05:00.988Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fc/9f/2f509339e89cfa6f6a4c4ff50438db9ca488dec341f7e454adad60150b00/protobuf-6.33.6-cp310-abi3-win32.whl", hash = "sha256:7d29d9b65f8afef196f8334e80d6bc1d5d4adedb449971fefd3723824e6e77d3", size = 425739, upload-time = "2026-03-18T19:04:48.373Z" },
+    { url = "https://files.pythonhosted.org/packages/76/5d/683efcd4798e0030c1bab27374fd13a89f7c2515fb1f3123efdfaa5eab57/protobuf-6.33.6-cp310-abi3-win_amd64.whl", hash = "sha256:0cd27b587afca21b7cfa59a74dcbd48a50f0a6400cfb59391340ad729d91d326", size = 437089, upload-time = "2026-03-18T19:04:50.381Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/01/a3c3ed5cd186f39e7880f8303cc51385a198a81469d53d0fdecf1f64d929/protobuf-6.33.6-cp39-abi3-macosx_10_9_universal2.whl", hash = "sha256:9720e6961b251bde64edfdab7d500725a2af5280f3f4c87e57c0208376aa8c3a", size = 427737, upload-time = "2026-03-18T19:04:51.866Z" },
+    { url = "https://files.pythonhosted.org/packages/ee/90/b3c01fdec7d2f627b3a6884243ba328c1217ed2d978def5c12dc50d328a3/protobuf-6.33.6-cp39-abi3-manylinux2014_aarch64.whl", hash = "sha256:e2afbae9b8e1825e3529f88d514754e094278bb95eadc0e199751cdd9a2e82a2", size = 324610, upload-time = "2026-03-18T19:04:53.096Z" },
+    { url = "https://files.pythonhosted.org/packages/9b/ca/25afc144934014700c52e05103c2421997482d561f3101ff352e1292fb81/protobuf-6.33.6-cp39-abi3-manylinux2014_s390x.whl", hash = "sha256:c96c37eec15086b79762ed265d59ab204dabc53056e3443e702d2681f4b39ce3", size = 339381, upload-time = "2026-03-18T19:04:54.616Z" },
+    { url = "https://files.pythonhosted.org/packages/16/92/d1e32e3e0d894fe00b15ce28ad4944ab692713f2e7f0a99787405e43533a/protobuf-6.33.6-cp39-abi3-manylinux2014_x86_64.whl", hash = "sha256:e9db7e292e0ab79dd108d7f1a94fe31601ce1ee3f7b79e0692043423020b0593", size = 323436, upload-time = "2026-03-18T19:04:55.768Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/72/02445137af02769918a93807b2b7890047c32bfb9f90371cbc12688819eb/protobuf-6.33.6-py3-none-any.whl", hash = "sha256:77179e006c476e69bf8e8ce866640091ec42e1beb80b213c3900006ecfba6901", size = 170656, upload-time = "2026-03-18T19:04:59.826Z" },
+]
+
+[[package]]
+name = "psutil"
+version = "7.2.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/aa/c6/d1ddf4abb55e93cebc4f2ed8b5d6dbad109ecb8d63748dd2b20ab5e57ebe/psutil-7.2.2.tar.gz", hash = "sha256:0746f5f8d406af344fd547f1c8daa5f5c33dbc293bb8d6a16d80b4bb88f59372", size = 493740, upload-time = "2026-01-28T18:14:54.428Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/51/08/510cbdb69c25a96f4ae523f733cdc963ae654904e8db864c07585ef99875/psutil-7.2.2-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:2edccc433cbfa046b980b0df0171cd25bcaeb3a68fe9022db0979e7aa74a826b", size = 130595, upload-time = "2026-01-28T18:14:57.293Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/f5/97baea3fe7a5a9af7436301f85490905379b1c6f2dd51fe3ecf24b4c5fbf/psutil-7.2.2-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:e78c8603dcd9a04c7364f1a3e670cea95d51ee865e4efb3556a3a63adef958ea", size = 131082, upload-time = "2026-01-28T18:14:59.732Z" },
+    { url = "https://files.pythonhosted.org/packages/37/d6/246513fbf9fa174af531f28412297dd05241d97a75911ac8febefa1a53c6/psutil-7.2.2-cp313-cp313t-manylinux2010_x86_64.manylinux_2_12_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:1a571f2330c966c62aeda00dd24620425d4b0cc86881c89861fbc04549e5dc63", size = 181476, upload-time = "2026-01-28T18:15:01.884Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/b5/9182c9af3836cca61696dabe4fd1304e17bc56cb62f17439e1154f225dd3/psutil-7.2.2-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:917e891983ca3c1887b4ef36447b1e0873e70c933afc831c6b6da078ba474312", size = 184062, upload-time = "2026-01-28T18:15:04.436Z" },
+    { url = "https://files.pythonhosted.org/packages/16/ba/0756dca669f5a9300d0cbcbfae9a4c30e446dfc7440ffe43ded5724bfd93/psutil-7.2.2-cp313-cp313t-win_amd64.whl", hash = "sha256:ab486563df44c17f5173621c7b198955bd6b613fb87c71c161f827d3fb149a9b", size = 139893, upload-time = "2026-01-28T18:15:06.378Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/61/8fa0e26f33623b49949346de05ec1ddaad02ed8ba64af45f40a147dbfa97/psutil-7.2.2-cp313-cp313t-win_arm64.whl", hash = "sha256:ae0aefdd8796a7737eccea863f80f81e468a1e4cf14d926bd9b6f5f2d5f90ca9", size = 135589, upload-time = "2026-01-28T18:15:08.03Z" },
+    { url = "https://files.pythonhosted.org/packages/81/69/ef179ab5ca24f32acc1dac0c247fd6a13b501fd5534dbae0e05a1c48b66d/psutil-7.2.2-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:eed63d3b4d62449571547b60578c5b2c4bcccc5387148db46e0c2313dad0ee00", size = 130664, upload-time = "2026-01-28T18:15:09.469Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/64/665248b557a236d3fa9efc378d60d95ef56dd0a490c2cd37dafc7660d4a9/psutil-7.2.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:7b6d09433a10592ce39b13d7be5a54fbac1d1228ed29abc880fb23df7cb694c9", size = 131087, upload-time = "2026-01-28T18:15:11.724Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/2e/e6782744700d6759ebce3043dcfa661fb61e2fb752b91cdeae9af12c2178/psutil-7.2.2-cp314-cp314t-manylinux2010_x86_64.manylinux_2_12_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:1fa4ecf83bcdf6e6c8f4449aff98eefb5d0604bf88cb883d7da3d8d2d909546a", size = 182383, upload-time = "2026-01-28T18:15:13.445Z" },
+    { url = "https://files.pythonhosted.org/packages/57/49/0a41cefd10cb7505cdc04dab3eacf24c0c2cb158a998b8c7b1d27ee2c1f5/psutil-7.2.2-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e452c464a02e7dc7822a05d25db4cde564444a67e58539a00f929c51eddda0cf", size = 185210, upload-time = "2026-01-28T18:15:16.002Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/2c/ff9bfb544f283ba5f83ba725a3c5fec6d6b10b8f27ac1dc641c473dc390d/psutil-7.2.2-cp314-cp314t-win_amd64.whl", hash = "sha256:c7663d4e37f13e884d13994247449e9f8f574bc4655d509c3b95e9ec9e2b9dc1", size = 141228, upload-time = "2026-01-28T18:15:18.385Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/fc/f8d9c31db14fcec13748d373e668bc3bed94d9077dbc17fb0eebc073233c/psutil-7.2.2-cp314-cp314t-win_arm64.whl", hash = "sha256:11fe5a4f613759764e79c65cf11ebdf26e33d6dd34336f8a337aa2996d71c841", size = 136284, upload-time = "2026-01-28T18:15:19.912Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/36/5ee6e05c9bd427237b11b3937ad82bb8ad2752d72c6969314590dd0c2f6e/psutil-7.2.2-cp36-abi3-macosx_10_9_x86_64.whl", hash = "sha256:ed0cace939114f62738d808fdcecd4c869222507e266e574799e9c0faa17d486", size = 129090, upload-time = "2026-01-28T18:15:22.168Z" },
+    { url = "https://files.pythonhosted.org/packages/80/c4/f5af4c1ca8c1eeb2e92ccca14ce8effdeec651d5ab6053c589b074eda6e1/psutil-7.2.2-cp36-abi3-macosx_11_0_arm64.whl", hash = "sha256:1a7b04c10f32cc88ab39cbf606e117fd74721c831c98a27dc04578deb0c16979", size = 129859, upload-time = "2026-01-28T18:15:23.795Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/70/5d8df3b09e25bce090399cf48e452d25c935ab72dad19406c77f4e828045/psutil-7.2.2-cp36-abi3-manylinux2010_x86_64.manylinux_2_12_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:076a2d2f923fd4821644f5ba89f059523da90dc9014e85f8e45a5774ca5bc6f9", size = 155560, upload-time = "2026-01-28T18:15:25.976Z" },
+    { url = "https://files.pythonhosted.org/packages/63/65/37648c0c158dc222aba51c089eb3bdfa238e621674dc42d48706e639204f/psutil-7.2.2-cp36-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b0726cecd84f9474419d67252add4ac0cd9811b04d61123054b9fb6f57df6e9e", size = 156997, upload-time = "2026-01-28T18:15:27.794Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/13/125093eadae863ce03c6ffdbae9929430d116a246ef69866dad94da3bfbc/psutil-7.2.2-cp36-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:fd04ef36b4a6d599bbdb225dd1d3f51e00105f6d48a28f006da7f9822f2606d8", size = 148972, upload-time = "2026-01-28T18:15:29.342Z" },
+    { url = "https://files.pythonhosted.org/packages/04/78/0acd37ca84ce3ddffaa92ef0f571e073faa6d8ff1f0559ab1272188ea2be/psutil-7.2.2-cp36-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:b58fabe35e80b264a4e3bb23e6b96f9e45a3df7fb7eed419ac0e5947c61e47cc", size = 148266, upload-time = "2026-01-28T18:15:31.597Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/90/e2159492b5426be0c1fef7acba807a03511f97c5f86b3caeda6ad92351a7/psutil-7.2.2-cp37-abi3-win_amd64.whl", hash = "sha256:eb7e81434c8d223ec4a219b5fc1c47d0417b12be7ea866e24fb5ad6e84b3d988", size = 137737, upload-time = "2026-01-28T18:15:33.849Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/c7/7bb2e321574b10df20cbde462a94e2b71d05f9bbda251ef27d104668306a/psutil-7.2.2-cp37-abi3-win_arm64.whl", hash = "sha256:8c233660f575a5a89e6d4cb65d9f938126312bca76d8fe087b947b3a1aaac9ee", size = 134617, upload-time = "2026-01-28T18:15:36.514Z" },
+]
+
+[[package]]
+name = "ptyprocess"
+version = "0.7.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/20/e5/16ff212c1e452235a90aeb09066144d0c5a6a8c0834397e03f5224495c4e/ptyprocess-0.7.0.tar.gz", hash = "sha256:5c5d0a3b48ceee0b48485e0c26037c0acd7d29765ca3fbb5cb3831d347423220", size = 70762, upload-time = "2020-12-28T15:15:30.155Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/22/a6/858897256d0deac81a172289110f31629fc4cee19b6f01283303e18c8db3/ptyprocess-0.7.0-py2.py3-none-any.whl", hash = "sha256:4b41f3967fce3af57cc7e94b888626c18bf37a083e3651ca8feeb66d492fef35", size = 13993, upload-time = "2020-12-28T15:15:28.35Z" },
+]
+
+[[package]]
+name = "pure-eval"
+version = "0.2.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/cd/05/0a34433a064256a578f1783a10da6df098ceaa4a57bbeaa96a6c0352786b/pure_eval-0.2.3.tar.gz", hash = "sha256:5f4e983f40564c576c7c8635ae88db5956bb2229d7e9237d03b3c0b0190eaf42", size = 19752, upload-time = "2024-07-21T12:58:21.801Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8e/37/efad0257dc6e593a18957422533ff0f87ede7c9c6ea010a2177d738fb82f/pure_eval-0.2.3-py3-none-any.whl", hash = "sha256:1db8e35b67b3d218d818ae653e27f06c3aa420901fa7b081ca98cbedc874e0d0", size = 11842, upload-time = "2024-07-21T12:58:20.04Z" },
+]
+
+[[package]]
+name = "py-key-value-aio"
+version = "0.4.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "beartype" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/04/3c/0397c072a38d4bc580994b42e0c90c5f44f679303489e4376289534735e5/py_key_value_aio-0.4.4.tar.gz", hash = "sha256:e3012e6243ed7cc09bb05457bd4d03b1ba5c2b1ca8700096b3927db79ffbbe55", size = 92300, upload-time = "2026-02-16T21:21:43.245Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/32/69/f1b537ee70b7def42d63124a539ed3026a11a3ffc3086947a1ca6e861868/py_key_value_aio-0.4.4-py3-none-any.whl", hash = "sha256:18e17564ecae61b987f909fc2cd41ee2012c84b4b1dcb8c055cf8b4bc1bf3f5d", size = 152291, upload-time = "2026-02-16T21:21:44.241Z" },
+]
+
+[package.optional-dependencies]
+filetree = [
+    { name = "aiofile" },
+    { name = "anyio" },
+]
+keyring = [
+    { name = "keyring" },
+]
+memory = [
+    { name = "cachetools" },
+]
+redis = [
+    { name = "redis" },
+]
+
+[[package]]
+name = "pyasn1"
+version = "0.6.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/5c/5f/6583902b6f79b399c9c40674ac384fd9cd77805f9e6205075f828ef11fb2/pyasn1-0.6.3.tar.gz", hash = "sha256:697a8ecd6d98891189184ca1fa05d1bb00e2f84b5977c481452050549c8a72cf", size = 148685, upload-time = "2026-03-17T01:06:53.382Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/5d/a0/7d793dce3fa811fe047d6ae2431c672364b462850c6235ae306c0efd025f/pyasn1-0.6.3-py3-none-any.whl", hash = "sha256:a80184d120f0864a52a073acc6fc642847d0be408e7c7252f31390c0f4eadcde", size = 83997, upload-time = "2026-03-17T01:06:52.036Z" },
+]
+
+[[package]]
+name = "pyasn1-modules"
+version = "0.4.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pyasn1" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e9/e6/78ebbb10a8c8e4b61a59249394a4a594c1a7af95593dc933a349c8d00964/pyasn1_modules-0.4.2.tar.gz", hash = "sha256:677091de870a80aae844b1ca6134f54652fa2c8c5a52aa396440ac3106e941e6", size = 307892, upload-time = "2025-03-28T02:41:22.17Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/47/8d/d529b5d697919ba8c11ad626e835d4039be708a35b0d22de83a269a6682c/pyasn1_modules-0.4.2-py3-none-any.whl", hash = "sha256:29253a9207ce32b64c3ac6600edc75368f98473906e8fd1043bd6b5b1de2c14a", size = 181259, upload-time = "2025-03-28T02:41:19.028Z" },
+]
+
+[[package]]
+name = "pycparser"
+version = "3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/1b/7d/92392ff7815c21062bea51aa7b87d45576f649f16458d78b7cf94b9ab2e6/pycparser-3.0.tar.gz", hash = "sha256:600f49d217304a5902ac3c37e1281c9fe94e4d0489de643a9504c5cdfdfc6b29", size = 103492, upload-time = "2026-01-21T14:26:51.89Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0c/c3/44f3fbbfa403ea2a7c779186dc20772604442dde72947e7d01069cbe98e3/pycparser-3.0-py3-none-any.whl", hash = "sha256:b727414169a36b7d524c1c3e31839a521725078d7b2ff038656844266160a992", size = 48172, upload-time = "2026-01-21T14:26:50.693Z" },
+]
+
+[[package]]
+name = "pydantic"
+version = "2.12.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "annotated-types" },
+    { name = "pydantic-core" },
+    { name = "typing-extensions" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/69/44/36f1a6e523abc58ae5f928898e4aca2e0ea509b5aa6f6f392a5d882be928/pydantic-2.12.5.tar.gz", hash = "sha256:4d351024c75c0f085a9febbb665ce8c0c6ec5d30e903bdb6394b7ede26aebb49", size = 821591, upload-time = "2025-11-26T15:11:46.471Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/5a/87/b70ad306ebb6f9b585f114d0ac2137d792b48be34d732d60e597c2f8465a/pydantic-2.12.5-py3-none-any.whl", hash = "sha256:e561593fccf61e8a20fc46dfc2dfe075b8be7d0188df33f221ad1f0139180f9d", size = 463580, upload-time = "2025-11-26T15:11:44.605Z" },
+]
+
+[package.optional-dependencies]
+email = [
+    { name = "email-validator" },
+]
+
+[[package]]
+name = "pydantic-core"
+version = "2.41.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/71/70/23b021c950c2addd24ec408e9ab05d59b035b39d97cdc1130e1bce647bb6/pydantic_core-2.41.5.tar.gz", hash = "sha256:08daa51ea16ad373ffd5e7606252cc32f07bc72b28284b6bc9c6df804816476e", size = 460952, upload-time = "2025-11-04T13:43:49.098Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c6/90/32c9941e728d564b411d574d8ee0cf09b12ec978cb22b294995bae5549a5/pydantic_core-2.41.5-cp310-cp310-macosx_10_12_x86_64.whl", hash = "sha256:77b63866ca88d804225eaa4af3e664c5faf3568cea95360d21f4725ab6e07146", size = 2107298, upload-time = "2025-11-04T13:39:04.116Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/a8/61c96a77fe28993d9a6fb0f4127e05430a267b235a124545d79fea46dd65/pydantic_core-2.41.5-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:dfa8a0c812ac681395907e71e1274819dec685fec28273a28905df579ef137e2", size = 1901475, upload-time = "2025-11-04T13:39:06.055Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/b6/338abf60225acc18cdc08b4faef592d0310923d19a87fba1faf05af5346e/pydantic_core-2.41.5-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5921a4d3ca3aee735d9fd163808f5e8dd6c6972101e4adbda9a4667908849b97", size = 1918815, upload-time = "2025-11-04T13:39:10.41Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/1c/2ed0433e682983d8e8cba9c8d8ef274d4791ec6a6f24c58935b90e780e0a/pydantic_core-2.41.5-cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:e25c479382d26a2a41b7ebea1043564a937db462816ea07afa8a44c0866d52f9", size = 2065567, upload-time = "2025-11-04T13:39:12.244Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/24/cf84974ee7d6eae06b9e63289b7b8f6549d416b5c199ca2d7ce13bbcf619/pydantic_core-2.41.5-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:f547144f2966e1e16ae626d8ce72b4cfa0caedc7fa28052001c94fb2fcaa1c52", size = 2230442, upload-time = "2025-11-04T13:39:13.962Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/21/4e287865504b3edc0136c89c9c09431be326168b1eb7841911cbc877a995/pydantic_core-2.41.5-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:6f52298fbd394f9ed112d56f3d11aabd0d5bd27beb3084cc3d8ad069483b8941", size = 2350956, upload-time = "2025-11-04T13:39:15.889Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/76/7727ef2ffa4b62fcab916686a68a0426b9b790139720e1934e8ba797e238/pydantic_core-2.41.5-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:100baa204bb412b74fe285fb0f3a385256dad1d1879f0a5cb1499ed2e83d132a", size = 2068253, upload-time = "2025-11-04T13:39:17.403Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/8c/a4abfc79604bcb4c748e18975c44f94f756f08fb04218d5cb87eb0d3a63e/pydantic_core-2.41.5-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:05a2c8852530ad2812cb7914dc61a1125dc4e06252ee98e5638a12da6cc6fb6c", size = 2177050, upload-time = "2025-11-04T13:39:19.351Z" },
+    { url = "https://files.pythonhosted.org/packages/67/b1/de2e9a9a79b480f9cb0b6e8b6ba4c50b18d4e89852426364c66aa82bb7b3/pydantic_core-2.41.5-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:29452c56df2ed968d18d7e21f4ab0ac55e71dc59524872f6fc57dcf4a3249ed2", size = 2147178, upload-time = "2025-11-04T13:39:21Z" },
+    { url = "https://files.pythonhosted.org/packages/16/c1/dfb33f837a47b20417500efaa0378adc6635b3c79e8369ff7a03c494b4ac/pydantic_core-2.41.5-cp310-cp310-musllinux_1_1_armv7l.whl", hash = "sha256:d5160812ea7a8a2ffbe233d8da666880cad0cbaf5d4de74ae15c313213d62556", size = 2341833, upload-time = "2025-11-04T13:39:22.606Z" },
+    { url = "https://files.pythonhosted.org/packages/47/36/00f398642a0f4b815a9a558c4f1dca1b4020a7d49562807d7bc9ff279a6c/pydantic_core-2.41.5-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:df3959765b553b9440adfd3c795617c352154e497a4eaf3752555cfb5da8fc49", size = 2321156, upload-time = "2025-11-04T13:39:25.843Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/70/cad3acd89fde2010807354d978725ae111ddf6d0ea46d1ea1775b5c1bd0c/pydantic_core-2.41.5-cp310-cp310-win32.whl", hash = "sha256:1f8d33a7f4d5a7889e60dc39856d76d09333d8a6ed0f5f1190635cbec70ec4ba", size = 1989378, upload-time = "2025-11-04T13:39:27.92Z" },
+    { url = "https://files.pythonhosted.org/packages/76/92/d338652464c6c367e5608e4488201702cd1cbb0f33f7b6a85a60fe5f3720/pydantic_core-2.41.5-cp310-cp310-win_amd64.whl", hash = "sha256:62de39db01b8d593e45871af2af9e497295db8d73b085f6bfd0b18c83c70a8f9", size = 2013622, upload-time = "2025-11-04T13:39:29.848Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/72/74a989dd9f2084b3d9530b0915fdda64ac48831c30dbf7c72a41a5232db8/pydantic_core-2.41.5-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:a3a52f6156e73e7ccb0f8cced536adccb7042be67cb45f9562e12b319c119da6", size = 2105873, upload-time = "2025-11-04T13:39:31.373Z" },
+    { url = "https://files.pythonhosted.org/packages/12/44/37e403fd9455708b3b942949e1d7febc02167662bf1a7da5b78ee1ea2842/pydantic_core-2.41.5-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:7f3bf998340c6d4b0c9a2f02d6a400e51f123b59565d74dc60d252ce888c260b", size = 1899826, upload-time = "2025-11-04T13:39:32.897Z" },
+    { url = "https://files.pythonhosted.org/packages/33/7f/1d5cab3ccf44c1935a359d51a8a2a9e1a654b744b5e7f80d41b88d501eec/pydantic_core-2.41.5-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:378bec5c66998815d224c9ca994f1e14c0c21cb95d2f52b6021cc0b2a58f2a5a", size = 1917869, upload-time = "2025-11-04T13:39:34.469Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/6a/30d94a9674a7fe4f4744052ed6c5e083424510be1e93da5bc47569d11810/pydantic_core-2.41.5-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:e7b576130c69225432866fe2f4a469a85a54ade141d96fd396dffcf607b558f8", size = 2063890, upload-time = "2025-11-04T13:39:36.053Z" },
+    { url = "https://files.pythonhosted.org/packages/50/be/76e5d46203fcb2750e542f32e6c371ffa9b8ad17364cf94bb0818dbfb50c/pydantic_core-2.41.5-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:6cb58b9c66f7e4179a2d5e0f849c48eff5c1fca560994d6eb6543abf955a149e", size = 2229740, upload-time = "2025-11-04T13:39:37.753Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/ee/fed784df0144793489f87db310a6bbf8118d7b630ed07aa180d6067e653a/pydantic_core-2.41.5-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:88942d3a3dff3afc8288c21e565e476fc278902ae4d6d134f1eeda118cc830b1", size = 2350021, upload-time = "2025-11-04T13:39:40.94Z" },
+    { url = "https://files.pythonhosted.org/packages/c8/be/8fed28dd0a180dca19e72c233cbf58efa36df055e5b9d90d64fd1740b828/pydantic_core-2.41.5-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:f31d95a179f8d64d90f6831d71fa93290893a33148d890ba15de25642c5d075b", size = 2066378, upload-time = "2025-11-04T13:39:42.523Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/3b/698cf8ae1d536a010e05121b4958b1257f0b5522085e335360e53a6b1c8b/pydantic_core-2.41.5-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:c1df3d34aced70add6f867a8cf413e299177e0c22660cc767218373d0779487b", size = 2175761, upload-time = "2025-11-04T13:39:44.553Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/ba/15d537423939553116dea94ce02f9c31be0fa9d0b806d427e0308ec17145/pydantic_core-2.41.5-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:4009935984bd36bd2c774e13f9a09563ce8de4abaa7226f5108262fa3e637284", size = 2146303, upload-time = "2025-11-04T13:39:46.238Z" },
+    { url = "https://files.pythonhosted.org/packages/58/7f/0de669bf37d206723795f9c90c82966726a2ab06c336deba4735b55af431/pydantic_core-2.41.5-cp311-cp311-musllinux_1_1_armv7l.whl", hash = "sha256:34a64bc3441dc1213096a20fe27e8e128bd3ff89921706e83c0b1ac971276594", size = 2340355, upload-time = "2025-11-04T13:39:48.002Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/de/e7482c435b83d7e3c3ee5ee4451f6e8973cff0eb6007d2872ce6383f6398/pydantic_core-2.41.5-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:c9e19dd6e28fdcaa5a1de679aec4141f691023916427ef9bae8584f9c2fb3b0e", size = 2319875, upload-time = "2025-11-04T13:39:49.705Z" },
+    { url = "https://files.pythonhosted.org/packages/fe/e6/8c9e81bb6dd7560e33b9053351c29f30c8194b72f2d6932888581f503482/pydantic_core-2.41.5-cp311-cp311-win32.whl", hash = "sha256:2c010c6ded393148374c0f6f0bf89d206bf3217f201faa0635dcd56bd1520f6b", size = 1987549, upload-time = "2025-11-04T13:39:51.842Z" },
+    { url = "https://files.pythonhosted.org/packages/11/66/f14d1d978ea94d1bc21fc98fcf570f9542fe55bfcc40269d4e1a21c19bf7/pydantic_core-2.41.5-cp311-cp311-win_amd64.whl", hash = "sha256:76ee27c6e9c7f16f47db7a94157112a2f3a00e958bc626e2f4ee8bec5c328fbe", size = 2011305, upload-time = "2025-11-04T13:39:53.485Z" },
+    { url = "https://files.pythonhosted.org/packages/56/d8/0e271434e8efd03186c5386671328154ee349ff0354d83c74f5caaf096ed/pydantic_core-2.41.5-cp311-cp311-win_arm64.whl", hash = "sha256:4bc36bbc0b7584de96561184ad7f012478987882ebf9f9c389b23f432ea3d90f", size = 1972902, upload-time = "2025-11-04T13:39:56.488Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/5d/5f6c63eebb5afee93bcaae4ce9a898f3373ca23df3ccaef086d0233a35a7/pydantic_core-2.41.5-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:f41a7489d32336dbf2199c8c0a215390a751c5b014c2c1c5366e817202e9cdf7", size = 2110990, upload-time = "2025-11-04T13:39:58.079Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/32/9c2e8ccb57c01111e0fd091f236c7b371c1bccea0fa85247ac55b1e2b6b6/pydantic_core-2.41.5-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:070259a8818988b9a84a449a2a7337c7f430a22acc0859c6b110aa7212a6d9c0", size = 1896003, upload-time = "2025-11-04T13:39:59.956Z" },
+    { url = "https://files.pythonhosted.org/packages/68/b8/a01b53cb0e59139fbc9e4fda3e9724ede8de279097179be4ff31f1abb65a/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e96cea19e34778f8d59fe40775a7a574d95816eb150850a85a7a4c8f4b94ac69", size = 1919200, upload-time = "2025-11-04T13:40:02.241Z" },
+    { url = "https://files.pythonhosted.org/packages/38/de/8c36b5198a29bdaade07b5985e80a233a5ac27137846f3bc2d3b40a47360/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:ed2e99c456e3fadd05c991f8f437ef902e00eedf34320ba2b0842bd1c3ca3a75", size = 2052578, upload-time = "2025-11-04T13:40:04.401Z" },
+    { url = "https://files.pythonhosted.org/packages/00/b5/0e8e4b5b081eac6cb3dbb7e60a65907549a1ce035a724368c330112adfdd/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:65840751b72fbfd82c3c640cff9284545342a4f1eb1586ad0636955b261b0b05", size = 2208504, upload-time = "2025-11-04T13:40:06.072Z" },
+    { url = "https://files.pythonhosted.org/packages/77/56/87a61aad59c7c5b9dc8caad5a41a5545cba3810c3e828708b3d7404f6cef/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:e536c98a7626a98feb2d3eaf75944ef6f3dbee447e1f841eae16f2f0a72d8ddc", size = 2335816, upload-time = "2025-11-04T13:40:07.835Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/76/941cc9f73529988688a665a5c0ecff1112b3d95ab48f81db5f7606f522d3/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:eceb81a8d74f9267ef4081e246ffd6d129da5d87e37a77c9bde550cb04870c1c", size = 2075366, upload-time = "2025-11-04T13:40:09.804Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/43/ebef01f69baa07a482844faaa0a591bad1ef129253ffd0cdaa9d8a7f72d3/pydantic_core-2.41.5-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:d38548150c39b74aeeb0ce8ee1d8e82696f4a4e16ddc6de7b1d8823f7de4b9b5", size = 2171698, upload-time = "2025-11-04T13:40:12.004Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/87/41f3202e4193e3bacfc2c065fab7706ebe81af46a83d3e27605029c1f5a6/pydantic_core-2.41.5-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:c23e27686783f60290e36827f9c626e63154b82b116d7fe9adba1fda36da706c", size = 2132603, upload-time = "2025-11-04T13:40:13.868Z" },
+    { url = "https://files.pythonhosted.org/packages/49/7d/4c00df99cb12070b6bccdef4a195255e6020a550d572768d92cc54dba91a/pydantic_core-2.41.5-cp312-cp312-musllinux_1_1_armv7l.whl", hash = "sha256:482c982f814460eabe1d3bb0adfdc583387bd4691ef00b90575ca0d2b6fe2294", size = 2329591, upload-time = "2025-11-04T13:40:15.672Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/6a/ebf4b1d65d458f3cda6a7335d141305dfa19bdc61140a884d165a8a1bbc7/pydantic_core-2.41.5-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:bfea2a5f0b4d8d43adf9d7b8bf019fb46fdd10a2e5cde477fbcb9d1fa08c68e1", size = 2319068, upload-time = "2025-11-04T13:40:17.532Z" },
+    { url = "https://files.pythonhosted.org/packages/49/3b/774f2b5cd4192d5ab75870ce4381fd89cf218af999515baf07e7206753f0/pydantic_core-2.41.5-cp312-cp312-win32.whl", hash = "sha256:b74557b16e390ec12dca509bce9264c3bbd128f8a2c376eaa68003d7f327276d", size = 1985908, upload-time = "2025-11-04T13:40:19.309Z" },
+    { url = "https://files.pythonhosted.org/packages/86/45/00173a033c801cacf67c190fef088789394feaf88a98a7035b0e40d53dc9/pydantic_core-2.41.5-cp312-cp312-win_amd64.whl", hash = "sha256:1962293292865bca8e54702b08a4f26da73adc83dd1fcf26fbc875b35d81c815", size = 2020145, upload-time = "2025-11-04T13:40:21.548Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/22/91fbc821fa6d261b376a3f73809f907cec5ca6025642c463d3488aad22fb/pydantic_core-2.41.5-cp312-cp312-win_arm64.whl", hash = "sha256:1746d4a3d9a794cacae06a5eaaccb4b8643a131d45fbc9af23e353dc0a5ba5c3", size = 1976179, upload-time = "2025-11-04T13:40:23.393Z" },
+    { url = "https://files.pythonhosted.org/packages/87/06/8806241ff1f70d9939f9af039c6c35f2360cf16e93c2ca76f184e76b1564/pydantic_core-2.41.5-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:941103c9be18ac8daf7b7adca8228f8ed6bb7a1849020f643b3a14d15b1924d9", size = 2120403, upload-time = "2025-11-04T13:40:25.248Z" },
+    { url = "https://files.pythonhosted.org/packages/94/02/abfa0e0bda67faa65fef1c84971c7e45928e108fe24333c81f3bfe35d5f5/pydantic_core-2.41.5-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:112e305c3314f40c93998e567879e887a3160bb8689ef3d2c04b6cc62c33ac34", size = 1896206, upload-time = "2025-11-04T13:40:27.099Z" },
+    { url = "https://files.pythonhosted.org/packages/15/df/a4c740c0943e93e6500f9eb23f4ca7ec9bf71b19e608ae5b579678c8d02f/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0cbaad15cb0c90aa221d43c00e77bb33c93e8d36e0bf74760cd00e732d10a6a0", size = 1919307, upload-time = "2025-11-04T13:40:29.806Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/e3/6324802931ae1d123528988e0e86587c2072ac2e5394b4bc2bc34b61ff6e/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:03ca43e12fab6023fc79d28ca6b39b05f794ad08ec2feccc59a339b02f2b3d33", size = 2063258, upload-time = "2025-11-04T13:40:33.544Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/d4/2230d7151d4957dd79c3044ea26346c148c98fbf0ee6ebd41056f2d62ab5/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:dc799088c08fa04e43144b164feb0c13f9a0bc40503f8df3e9fde58a3c0c101e", size = 2214917, upload-time = "2025-11-04T13:40:35.479Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/9f/eaac5df17a3672fef0081b6c1bb0b82b33ee89aa5cec0d7b05f52fd4a1fa/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:97aeba56665b4c3235a0e52b2c2f5ae9cd071b8a8310ad27bddb3f7fb30e9aa2", size = 2332186, upload-time = "2025-11-04T13:40:37.436Z" },
+    { url = "https://files.pythonhosted.org/packages/cf/4e/35a80cae583a37cf15604b44240e45c05e04e86f9cfd766623149297e971/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:406bf18d345822d6c21366031003612b9c77b3e29ffdb0f612367352aab7d586", size = 2073164, upload-time = "2025-11-04T13:40:40.289Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/e3/f6e262673c6140dd3305d144d032f7bd5f7497d3871c1428521f19f9efa2/pydantic_core-2.41.5-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:b93590ae81f7010dbe380cdeab6f515902ebcbefe0b9327cc4804d74e93ae69d", size = 2179146, upload-time = "2025-11-04T13:40:42.809Z" },
+    { url = "https://files.pythonhosted.org/packages/75/c7/20bd7fc05f0c6ea2056a4565c6f36f8968c0924f19b7d97bbfea55780e73/pydantic_core-2.41.5-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:01a3d0ab748ee531f4ea6c3e48ad9dac84ddba4b0d82291f87248f2f9de8d740", size = 2137788, upload-time = "2025-11-04T13:40:44.752Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/8d/34318ef985c45196e004bc46c6eab2eda437e744c124ef0dbe1ff2c9d06b/pydantic_core-2.41.5-cp313-cp313-musllinux_1_1_armv7l.whl", hash = "sha256:6561e94ba9dacc9c61bce40e2d6bdc3bfaa0259d3ff36ace3b1e6901936d2e3e", size = 2340133, upload-time = "2025-11-04T13:40:46.66Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/59/013626bf8c78a5a5d9350d12e7697d3d4de951a75565496abd40ccd46bee/pydantic_core-2.41.5-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:915c3d10f81bec3a74fbd4faebe8391013ba61e5a1a8d48c4455b923bdda7858", size = 2324852, upload-time = "2025-11-04T13:40:48.575Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/d9/c248c103856f807ef70c18a4f986693a46a8ffe1602e5d361485da502d20/pydantic_core-2.41.5-cp313-cp313-win32.whl", hash = "sha256:650ae77860b45cfa6e2cdafc42618ceafab3a2d9a3811fcfbd3bbf8ac3c40d36", size = 1994679, upload-time = "2025-11-04T13:40:50.619Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/8b/341991b158ddab181cff136acd2552c9f35bd30380422a639c0671e99a91/pydantic_core-2.41.5-cp313-cp313-win_amd64.whl", hash = "sha256:79ec52ec461e99e13791ec6508c722742ad745571f234ea6255bed38c6480f11", size = 2019766, upload-time = "2025-11-04T13:40:52.631Z" },
+    { url = "https://files.pythonhosted.org/packages/73/7d/f2f9db34af103bea3e09735bb40b021788a5e834c81eedb541991badf8f5/pydantic_core-2.41.5-cp313-cp313-win_arm64.whl", hash = "sha256:3f84d5c1b4ab906093bdc1ff10484838aca54ef08de4afa9de0f5f14d69639cd", size = 1981005, upload-time = "2025-11-04T13:40:54.734Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/28/46b7c5c9635ae96ea0fbb779e271a38129df2550f763937659ee6c5dbc65/pydantic_core-2.41.5-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:3f37a19d7ebcdd20b96485056ba9e8b304e27d9904d233d7b1015db320e51f0a", size = 2119622, upload-time = "2025-11-04T13:40:56.68Z" },
+    { url = "https://files.pythonhosted.org/packages/74/1a/145646e5687e8d9a1e8d09acb278c8535ebe9e972e1f162ed338a622f193/pydantic_core-2.41.5-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:1d1d9764366c73f996edd17abb6d9d7649a7eb690006ab6adbda117717099b14", size = 1891725, upload-time = "2025-11-04T13:40:58.807Z" },
+    { url = "https://files.pythonhosted.org/packages/23/04/e89c29e267b8060b40dca97bfc64a19b2a3cf99018167ea1677d96368273/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:25e1c2af0fce638d5f1988b686f3b3ea8cd7de5f244ca147c777769e798a9cd1", size = 1915040, upload-time = "2025-11-04T13:41:00.853Z" },
+    { url = "https://files.pythonhosted.org/packages/84/a3/15a82ac7bd97992a82257f777b3583d3e84bdb06ba6858f745daa2ec8a85/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:506d766a8727beef16b7adaeb8ee6217c64fc813646b424d0804d67c16eddb66", size = 2063691, upload-time = "2025-11-04T13:41:03.504Z" },
+    { url = "https://files.pythonhosted.org/packages/74/9b/0046701313c6ef08c0c1cf0e028c67c770a4e1275ca73131563c5f2a310a/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:4819fa52133c9aa3c387b3328f25c1facc356491e6135b459f1de698ff64d869", size = 2213897, upload-time = "2025-11-04T13:41:05.804Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/cd/6bac76ecd1b27e75a95ca3a9a559c643b3afcd2dd62086d4b7a32a18b169/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:2b761d210c9ea91feda40d25b4efe82a1707da2ef62901466a42492c028553a2", size = 2333302, upload-time = "2025-11-04T13:41:07.809Z" },
+    { url = "https://files.pythonhosted.org/packages/4c/d2/ef2074dc020dd6e109611a8be4449b98cd25e1b9b8a303c2f0fca2f2bcf7/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:22f0fb8c1c583a3b6f24df2470833b40207e907b90c928cc8d3594b76f874375", size = 2064877, upload-time = "2025-11-04T13:41:09.827Z" },
+    { url = "https://files.pythonhosted.org/packages/18/66/e9db17a9a763d72f03de903883c057b2592c09509ccfe468187f2a2eef29/pydantic_core-2.41.5-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:2782c870e99878c634505236d81e5443092fba820f0373997ff75f90f68cd553", size = 2180680, upload-time = "2025-11-04T13:41:12.379Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/9e/3ce66cebb929f3ced22be85d4c2399b8e85b622db77dad36b73c5387f8f8/pydantic_core-2.41.5-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:0177272f88ab8312479336e1d777f6b124537d47f2123f89cb37e0accea97f90", size = 2138960, upload-time = "2025-11-04T13:41:14.627Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/62/205a998f4327d2079326b01abee48e502ea739d174f0a89295c481a2272e/pydantic_core-2.41.5-cp314-cp314-musllinux_1_1_armv7l.whl", hash = "sha256:63510af5e38f8955b8ee5687740d6ebf7c2a0886d15a6d65c32814613681bc07", size = 2339102, upload-time = "2025-11-04T13:41:16.868Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/0d/f05e79471e889d74d3d88f5bd20d0ed189ad94c2423d81ff8d0000aab4ff/pydantic_core-2.41.5-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:e56ba91f47764cc14f1daacd723e3e82d1a89d783f0f5afe9c364b8bb491ccdb", size = 2326039, upload-time = "2025-11-04T13:41:18.934Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/e1/e08a6208bb100da7e0c4b288eed624a703f4d129bde2da475721a80cab32/pydantic_core-2.41.5-cp314-cp314-win32.whl", hash = "sha256:aec5cf2fd867b4ff45b9959f8b20ea3993fc93e63c7363fe6851424c8a7e7c23", size = 1995126, upload-time = "2025-11-04T13:41:21.418Z" },
+    { url = "https://files.pythonhosted.org/packages/48/5d/56ba7b24e9557f99c9237e29f5c09913c81eeb2f3217e40e922353668092/pydantic_core-2.41.5-cp314-cp314-win_amd64.whl", hash = "sha256:8e7c86f27c585ef37c35e56a96363ab8de4e549a95512445b85c96d3e2f7c1bf", size = 2015489, upload-time = "2025-11-04T13:41:24.076Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/bb/f7a190991ec9e3e0ba22e4993d8755bbc4a32925c0b5b42775c03e8148f9/pydantic_core-2.41.5-cp314-cp314-win_arm64.whl", hash = "sha256:e672ba74fbc2dc8eea59fb6d4aed6845e6905fc2a8afe93175d94a83ba2a01a0", size = 1977288, upload-time = "2025-11-04T13:41:26.33Z" },
+    { url = "https://files.pythonhosted.org/packages/92/ed/77542d0c51538e32e15afe7899d79efce4b81eee631d99850edc2f5e9349/pydantic_core-2.41.5-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:8566def80554c3faa0e65ac30ab0932b9e3a5cd7f8323764303d468e5c37595a", size = 2120255, upload-time = "2025-11-04T13:41:28.569Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/3d/6913dde84d5be21e284439676168b28d8bbba5600d838b9dca99de0fad71/pydantic_core-2.41.5-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:b80aa5095cd3109962a298ce14110ae16b8c1aece8b72f9dafe81cf597ad80b3", size = 1863760, upload-time = "2025-11-04T13:41:31.055Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/f0/e5e6b99d4191da102f2b0eb9687aaa7f5bea5d9964071a84effc3e40f997/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3006c3dd9ba34b0c094c544c6006cc79e87d8612999f1a5d43b769b89181f23c", size = 1878092, upload-time = "2025-11-04T13:41:33.21Z" },
+    { url = "https://files.pythonhosted.org/packages/71/48/36fb760642d568925953bcc8116455513d6e34c4beaa37544118c36aba6d/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:72f6c8b11857a856bcfa48c86f5368439f74453563f951e473514579d44aa612", size = 2053385, upload-time = "2025-11-04T13:41:35.508Z" },
+    { url = "https://files.pythonhosted.org/packages/20/25/92dc684dd8eb75a234bc1c764b4210cf2646479d54b47bf46061657292a8/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5cb1b2f9742240e4bb26b652a5aeb840aa4b417c7748b6f8387927bc6e45e40d", size = 2218832, upload-time = "2025-11-04T13:41:37.732Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/09/f53e0b05023d3e30357d82eb35835d0f6340ca344720a4599cd663dca599/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:bd3d54f38609ff308209bd43acea66061494157703364ae40c951f83ba99a1a9", size = 2327585, upload-time = "2025-11-04T13:41:40Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/4e/2ae1aa85d6af35a39b236b1b1641de73f5a6ac4d5a7509f77b814885760c/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:2ff4321e56e879ee8d2a879501c8e469414d948f4aba74a2d4593184eb326660", size = 2041078, upload-time = "2025-11-04T13:41:42.323Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/13/2e215f17f0ef326fc72afe94776edb77525142c693767fc347ed6288728d/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:d0d2568a8c11bf8225044aa94409e21da0cb09dcdafe9ecd10250b2baad531a9", size = 2173914, upload-time = "2025-11-04T13:41:45.221Z" },
+    { url = "https://files.pythonhosted.org/packages/02/7a/f999a6dcbcd0e5660bc348a3991c8915ce6599f4f2c6ac22f01d7a10816c/pydantic_core-2.41.5-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:a39455728aabd58ceabb03c90e12f71fd30fa69615760a075b9fec596456ccc3", size = 2129560, upload-time = "2025-11-04T13:41:47.474Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/b1/6c990ac65e3b4c079a4fb9f5b05f5b013afa0f4ed6780a3dd236d2cbdc64/pydantic_core-2.41.5-cp314-cp314t-musllinux_1_1_armv7l.whl", hash = "sha256:239edca560d05757817c13dc17c50766136d21f7cd0fac50295499ae24f90fdf", size = 2329244, upload-time = "2025-11-04T13:41:49.992Z" },
+    { url = "https://files.pythonhosted.org/packages/d9/02/3c562f3a51afd4d88fff8dffb1771b30cfdfd79befd9883ee094f5b6c0d8/pydantic_core-2.41.5-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:2a5e06546e19f24c6a96a129142a75cee553cc018ffee48a460059b1185f4470", size = 2331955, upload-time = "2025-11-04T13:41:54.079Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/96/5fb7d8c3c17bc8c62fdb031c47d77a1af698f1d7a406b0f79aaa1338f9ad/pydantic_core-2.41.5-cp314-cp314t-win32.whl", hash = "sha256:b4ececa40ac28afa90871c2cc2b9ffd2ff0bf749380fbdf57d165fd23da353aa", size = 1988906, upload-time = "2025-11-04T13:41:56.606Z" },
+    { url = "https://files.pythonhosted.org/packages/22/ed/182129d83032702912c2e2d8bbe33c036f342cc735737064668585dac28f/pydantic_core-2.41.5-cp314-cp314t-win_amd64.whl", hash = "sha256:80aa89cad80b32a912a65332f64a4450ed00966111b6615ca6816153d3585a8c", size = 1981607, upload-time = "2025-11-04T13:41:58.889Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/ed/068e41660b832bb0b1aa5b58011dea2a3fe0ba7861ff38c4d4904c1c1a99/pydantic_core-2.41.5-cp314-cp314t-win_arm64.whl", hash = "sha256:35b44f37a3199f771c3eaa53051bc8a70cd7b54f333531c59e29fd4db5d15008", size = 1974769, upload-time = "2025-11-04T13:42:01.186Z" },
+    { url = "https://files.pythonhosted.org/packages/11/72/90fda5ee3b97e51c494938a4a44c3a35a9c96c19bba12372fb9c634d6f57/pydantic_core-2.41.5-graalpy311-graalpy242_311_native-macosx_10_12_x86_64.whl", hash = "sha256:b96d5f26b05d03cc60f11a7761a5ded1741da411e7fe0909e27a5e6a0cb7b034", size = 2115441, upload-time = "2025-11-04T13:42:39.557Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/53/8942f884fa33f50794f119012dc6a1a02ac43a56407adaac20463df8e98f/pydantic_core-2.41.5-graalpy311-graalpy242_311_native-macosx_11_0_arm64.whl", hash = "sha256:634e8609e89ceecea15e2d61bc9ac3718caaaa71963717bf3c8f38bfde64242c", size = 1930291, upload-time = "2025-11-04T13:42:42.169Z" },
+    { url = "https://files.pythonhosted.org/packages/79/c8/ecb9ed9cd942bce09fc888ee960b52654fbdbede4ba6c2d6e0d3b1d8b49c/pydantic_core-2.41.5-graalpy311-graalpy242_311_native-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:93e8740d7503eb008aa2df04d3b9735f845d43ae845e6dcd2be0b55a2da43cd2", size = 1948632, upload-time = "2025-11-04T13:42:44.564Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/1b/687711069de7efa6af934e74f601e2a4307365e8fdc404703afc453eab26/pydantic_core-2.41.5-graalpy311-graalpy242_311_native-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:f15489ba13d61f670dcc96772e733aad1a6f9c429cc27574c6cdaed82d0146ad", size = 2138905, upload-time = "2025-11-04T13:42:47.156Z" },
+    { url = "https://files.pythonhosted.org/packages/09/32/59b0c7e63e277fa7911c2fc70ccfb45ce4b98991e7ef37110663437005af/pydantic_core-2.41.5-graalpy312-graalpy250_312_native-macosx_10_12_x86_64.whl", hash = "sha256:7da7087d756b19037bc2c06edc6c170eeef3c3bafcb8f532ff17d64dc427adfd", size = 2110495, upload-time = "2025-11-04T13:42:49.689Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/81/05e400037eaf55ad400bcd318c05bb345b57e708887f07ddb2d20e3f0e98/pydantic_core-2.41.5-graalpy312-graalpy250_312_native-macosx_11_0_arm64.whl", hash = "sha256:aabf5777b5c8ca26f7824cb4a120a740c9588ed58df9b2d196ce92fba42ff8dc", size = 1915388, upload-time = "2025-11-04T13:42:52.215Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/0d/e3549b2399f71d56476b77dbf3cf8937cec5cd70536bdc0e374a421d0599/pydantic_core-2.41.5-graalpy312-graalpy250_312_native-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:c007fe8a43d43b3969e8469004e9845944f1a80e6acd47c150856bb87f230c56", size = 1942879, upload-time = "2025-11-04T13:42:56.483Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/07/34573da085946b6a313d7c42f82f16e8920bfd730665de2d11c0c37a74b5/pydantic_core-2.41.5-graalpy312-graalpy250_312_native-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:76d0819de158cd855d1cbb8fcafdf6f5cf1eb8e470abe056d5d161106e38062b", size = 2139017, upload-time = "2025-11-04T13:42:59.471Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/b0/1a2aa41e3b5a4ba11420aba2d091b2d17959c8d1519ece3627c371951e73/pydantic_core-2.41.5-pp310-pypy310_pp73-macosx_10_12_x86_64.whl", hash = "sha256:b5819cd790dbf0c5eb9f82c73c16b39a65dd6dd4d1439dcdea7816ec9adddab8", size = 2103351, upload-time = "2025-11-04T13:43:02.058Z" },
+    { url = "https://files.pythonhosted.org/packages/a4/ee/31b1f0020baaf6d091c87900ae05c6aeae101fa4e188e1613c80e4f1ea31/pydantic_core-2.41.5-pp310-pypy310_pp73-macosx_11_0_arm64.whl", hash = "sha256:5a4e67afbc95fa5c34cf27d9089bca7fcab4e51e57278d710320a70b956d1b9a", size = 1925363, upload-time = "2025-11-04T13:43:05.159Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/89/ab8e86208467e467a80deaca4e434adac37b10a9d134cd2f99b28a01e483/pydantic_core-2.41.5-pp310-pypy310_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ece5c59f0ce7d001e017643d8d24da587ea1f74f6993467d85ae8a5ef9d4f42b", size = 2135615, upload-time = "2025-11-04T13:43:08.116Z" },
+    { url = "https://files.pythonhosted.org/packages/99/0a/99a53d06dd0348b2008f2f30884b34719c323f16c3be4e6cc1203b74a91d/pydantic_core-2.41.5-pp310-pypy310_pp73-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:16f80f7abe3351f8ea6858914ddc8c77e02578544a0ebc15b4c2e1a0e813b0b2", size = 2175369, upload-time = "2025-11-04T13:43:12.49Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/94/30ca3b73c6d485b9bb0bc66e611cff4a7138ff9736b7e66bcf0852151636/pydantic_core-2.41.5-pp310-pypy310_pp73-musllinux_1_1_aarch64.whl", hash = "sha256:33cb885e759a705b426baada1fe68cbb0a2e68e34c5d0d0289a364cf01709093", size = 2144218, upload-time = "2025-11-04T13:43:15.431Z" },
+    { url = "https://files.pythonhosted.org/packages/87/57/31b4f8e12680b739a91f472b5671294236b82586889ef764b5fbc6669238/pydantic_core-2.41.5-pp310-pypy310_pp73-musllinux_1_1_armv7l.whl", hash = "sha256:c8d8b4eb992936023be7dee581270af5c6e0697a8559895f527f5b7105ecd36a", size = 2329951, upload-time = "2025-11-04T13:43:18.062Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/73/3c2c8edef77b8f7310e6fb012dbc4b8551386ed575b9eb6fb2506e28a7eb/pydantic_core-2.41.5-pp310-pypy310_pp73-musllinux_1_1_x86_64.whl", hash = "sha256:242a206cd0318f95cd21bdacff3fcc3aab23e79bba5cac3db5a841c9ef9c6963", size = 2318428, upload-time = "2025-11-04T13:43:20.679Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/02/8559b1f26ee0d502c74f9cca5c0d2fd97e967e083e006bbbb4e97f3a043a/pydantic_core-2.41.5-pp310-pypy310_pp73-win_amd64.whl", hash = "sha256:d3a978c4f57a597908b7e697229d996d77a6d3c94901e9edee593adada95ce1a", size = 2147009, upload-time = "2025-11-04T13:43:23.286Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/9b/1b3f0e9f9305839d7e84912f9e8bfbd191ed1b1ef48083609f0dabde978c/pydantic_core-2.41.5-pp311-pypy311_pp73-macosx_10_12_x86_64.whl", hash = "sha256:b2379fa7ed44ddecb5bfe4e48577d752db9fc10be00a6b7446e9663ba143de26", size = 2101980, upload-time = "2025-11-04T13:43:25.97Z" },
+    { url = "https://files.pythonhosted.org/packages/a4/ed/d71fefcb4263df0da6a85b5d8a7508360f2f2e9b3bf5814be9c8bccdccc1/pydantic_core-2.41.5-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:266fb4cbf5e3cbd0b53669a6d1b039c45e3ce651fd5442eff4d07c2cc8d66808", size = 1923865, upload-time = "2025-11-04T13:43:28.763Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/3a/626b38db460d675f873e4444b4bb030453bbe7b4ba55df821d026a0493c4/pydantic_core-2.41.5-pp311-pypy311_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:58133647260ea01e4d0500089a8c4f07bd7aa6ce109682b1426394988d8aaacc", size = 2134256, upload-time = "2025-11-04T13:43:31.71Z" },
+    { url = "https://files.pythonhosted.org/packages/83/d9/8412d7f06f616bbc053d30cb4e5f76786af3221462ad5eee1f202021eb4e/pydantic_core-2.41.5-pp311-pypy311_pp73-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:287dad91cfb551c363dc62899a80e9e14da1f0e2b6ebde82c806612ca2a13ef1", size = 2174762, upload-time = "2025-11-04T13:43:34.744Z" },
+    { url = "https://files.pythonhosted.org/packages/55/4c/162d906b8e3ba3a99354e20faa1b49a85206c47de97a639510a0e673f5da/pydantic_core-2.41.5-pp311-pypy311_pp73-musllinux_1_1_aarch64.whl", hash = "sha256:03b77d184b9eb40240ae9fd676ca364ce1085f203e1b1256f8ab9984dca80a84", size = 2143141, upload-time = "2025-11-04T13:43:37.701Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/f2/f11dd73284122713f5f89fc940f370d035fa8e1e078d446b3313955157fe/pydantic_core-2.41.5-pp311-pypy311_pp73-musllinux_1_1_armv7l.whl", hash = "sha256:a668ce24de96165bb239160b3d854943128f4334822900534f2fe947930e5770", size = 2330317, upload-time = "2025-11-04T13:43:40.406Z" },
+    { url = "https://files.pythonhosted.org/packages/88/9d/b06ca6acfe4abb296110fb1273a4d848a0bfb2ff65f3ee92127b3244e16b/pydantic_core-2.41.5-pp311-pypy311_pp73-musllinux_1_1_x86_64.whl", hash = "sha256:f14f8f046c14563f8eb3f45f499cc658ab8d10072961e07225e507adb700e93f", size = 2316992, upload-time = "2025-11-04T13:43:43.602Z" },
+    { url = "https://files.pythonhosted.org/packages/36/c7/cfc8e811f061c841d7990b0201912c3556bfeb99cdcb7ed24adc8d6f8704/pydantic_core-2.41.5-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:56121965f7a4dc965bff783d70b907ddf3d57f6eba29b6d2e5dabfaf07799c51", size = 2145302, upload-time = "2025-11-04T13:43:46.64Z" },
+]
+
+[[package]]
+name = "pydantic-monty"
+version = "0.0.17"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f4/f8/431ba0b79d02922811392c4e3d283d6508f7052ceaa1936cc34878703ecc/pydantic_monty-0.0.17.tar.gz", hash = "sha256:9c4904a8fbc63282793f3afd2d180124494c7fc371783f365e5691c9586360af", size = 1007724, upload-time = "2026-04-22T20:13:48.915Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/5e/19/8105bc0b3acb42f6cb48a29669a5e21316bc05e3e9b6fab64cf94b483712/pydantic_monty-0.0.17-cp310-cp310-macosx_10_12_x86_64.whl", hash = "sha256:3c3b6c026d8a0437eeb4d6b2d908be75e2715e0555b9a13f076b7e9ba9bbae19", size = 7344730, upload-time = "2026-04-22T20:13:24.408Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/a2/7281cdb37481c4252292b63bebf737c87d0fd463f3174499608607de0907/pydantic_monty-0.0.17-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:c80b4d34437abd209c042f81f8ecea81a097022fb9b01431ab859b877edfbc4d", size = 7334937, upload-time = "2026-04-22T20:15:06.923Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/68/0bf7c0c627a56d8653b42888a3c1fc33cd33d2532ec456d9358275d7c792/pydantic_monty-0.0.17-cp310-cp310-manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:beecc1f7e5b10db40d7b2b24a68166a36514289a2402bfef370a7984e90a2ab8", size = 7864543, upload-time = "2026-04-22T20:14:46.273Z" },
+    { url = "https://files.pythonhosted.org/packages/09/9b/5a6f006541fd3bdc64b6dfbbaeabfb2244c89a22d7077a1fc92ec497c03e/pydantic_monty-0.0.17-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:64ea7babdcc9fba93089fa52589b6d0549f755e37500f6cf4aeaeb8e56328a3e", size = 7138764, upload-time = "2026-04-22T20:15:30.516Z" },
+    { url = "https://files.pythonhosted.org/packages/01/cc/59cca979bd427d166df8c827fba9e794c4a5c08943e225a22adf9854a78f/pydantic_monty-0.0.17-cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:a7fe77a191205becb622eaecb075e8bcbbbe4dac20a916d9c58ce6d59a22a8da", size = 7444006, upload-time = "2026-04-22T20:15:23.386Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/c5/d027170fb33fcbc038febb76dfd2d9047f5194a250ea608e3ed8e5ec28d4/pydantic_monty-0.0.17-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:2cdbefc180cc83c8b8415aaf95b9099bb2cb15261f40ebe2c92f13e7d52439a4", size = 7967564, upload-time = "2026-04-22T20:14:57.315Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/01/ac0d4bc1ff00acfac14b7cb2ee322d08778c206cd57f43da8206a2f6ce78/pydantic_monty-0.0.17-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:575ce5aa31db18bbbf6275f00e9b0c005ca393bfb73a2f306a577ad490ec2d98", size = 8199021, upload-time = "2026-04-22T20:15:14.488Z" },
+    { url = "https://files.pythonhosted.org/packages/51/85/8d0c6e5f127da9ebc0fcda6e411592d12b7606347d67aecd4363df5eed6b/pydantic_monty-0.0.17-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e252ec54fc4728406045f7be36ca45dbea8e6856df9c6154b1b9821b8952dfa2", size = 7769814, upload-time = "2026-04-22T20:14:55.197Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/cc/cb4d1b14b039eab00b33a7274f15f81739c3f272e2dfbeb8fb13c6b0c85d/pydantic_monty-0.0.17-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:fba71e5cb49f15a1446ecee142c8cc11f4bd6df4fcb4926465c83181474b2fd4", size = 7317432, upload-time = "2026-04-22T20:14:19.993Z" },
+    { url = "https://files.pythonhosted.org/packages/c8/16/737c7a023abbcb21848eb4d58f7167d9f4f8cdc46858ce8ed835cc2c137c/pydantic_monty-0.0.17-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:69136647abd56f804987834e37573adcc5c3b3d05013b8b3a2939f44b3bd5199", size = 7767816, upload-time = "2026-04-22T20:13:40.002Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/9f/5302b784f882ae8a8396f29f8c5ab4c16524c173a3d777b94af33858fdf2/pydantic_monty-0.0.17-cp310-cp310-win32.whl", hash = "sha256:d5b3beb6169b59adea10fdefb1e54bfa9a66165404891dfb6fcf16f7749cda3b", size = 7230648, upload-time = "2026-04-22T20:14:27.03Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/27/8c219f619dad466ec25db365acf88e2a50450dd862e0daff0eb281b6176b/pydantic_monty-0.0.17-cp310-cp310-win_amd64.whl", hash = "sha256:50ed9561b6dd1a1863d4cac81e4eaca64cb10ab541aaab92fcb5996739bb8e7f", size = 8075073, upload-time = "2026-04-22T20:14:17.073Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/42/ca8e42d9f3318f5c454cf8b168d814ec97c6f2afc38756d4b1b806184f6d/pydantic_monty-0.0.17-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:af890d691f6055491a4e643dd5bf09e07bd7a20ad70038531aada6415ab8794a", size = 7344138, upload-time = "2026-04-22T20:13:29.155Z" },
+    { url = "https://files.pythonhosted.org/packages/56/c8/cfaf0a56087301d4e88f72cf54ea45a7eebc09c021c85b8864447f1e3755/pydantic_monty-0.0.17-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:2f38a69858dfdd2c9474156616d05e25a288e2080aee24152fa40c19ad425f0e", size = 7334903, upload-time = "2026-04-22T20:14:31.489Z" },
+    { url = "https://files.pythonhosted.org/packages/51/77/a751a6f73f854aa85fed94cfa5ecab21d7bf218c9fa03c96f9edf470cc4e/pydantic_monty-0.0.17-cp311-cp311-manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:bb88264e291cee56770a775f57125538c4713c6d362e89ee63bff506f650a0df", size = 7864258, upload-time = "2026-04-22T20:13:15.594Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/fe/2eb51eb37e9f712cada64fa8d7df4b63b1f5fc635290147ab158ff0e1ef1/pydantic_monty-0.0.17-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:54c317611454aba8be7ca96aeeea9429f4702a5c4ba89812bea82bed0d8e34fd", size = 7138153, upload-time = "2026-04-22T20:14:22.255Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/15/835b10cdec3b96b089eef9899df6850b7f84a10225c491698b0ecf8e532a/pydantic_monty-0.0.17-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:9563b5b4933f0f08c0e66ec66aaa4f43f2388bcc04b984e58aab2146dacd3829", size = 7443572, upload-time = "2026-04-22T20:13:17.951Z" },
+    { url = "https://files.pythonhosted.org/packages/16/92/aca140923fad8a2821a135cfeaa2fbb3321063bbadaa760424a016bb1ac6/pydantic_monty-0.0.17-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:35f267a501bc1910178a1515fdd3dd927273fbb44e44b8718cb3b33aee79f41b", size = 7967178, upload-time = "2026-04-22T20:14:06.032Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/ca/7c4ff1e3fe2e82a4745decfca67b54a7a61cd306875e32d8e41c5192c69e/pydantic_monty-0.0.17-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:35b000c52755f25f322ea7c4d079f09aa60635ffe24a6463899e423066a41bf3", size = 8198241, upload-time = "2026-04-22T20:15:21.2Z" },
+    { url = "https://files.pythonhosted.org/packages/30/0b/702db7b753b96ebc6713e7cbdfaecdb471df3e3cb0f0f6e828620a743b78/pydantic_monty-0.0.17-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:61b517776ad13aa4580b1dd89188b18296ceeaf88256423563bbc99e804fd83f", size = 7768859, upload-time = "2026-04-22T20:13:20.044Z" },
+    { url = "https://files.pythonhosted.org/packages/29/9c/8d16e0cc0c36d1444f25d57da68dd22216bf0961c457a482429cec32141b/pydantic_monty-0.0.17-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:5da5362ef25665a23a3b13024497719f65cafa61d696cac76429f84701bee2e2", size = 7316674, upload-time = "2026-04-22T20:14:52.579Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/4d/d47ae703d402e45475333c4bf11b117c8068305f00c1363dbaea13d0fd09/pydantic_monty-0.0.17-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:7e655b6ddd552c02b751f1d57fc291fbd5654ff8b166a8bd634857879160d0b7", size = 7767515, upload-time = "2026-04-22T20:15:16.539Z" },
+    { url = "https://files.pythonhosted.org/packages/99/9b/e17fb50d0df5cf9908f8fffa25c5909ed0eb92ca102ded06f7a6d6133e78/pydantic_monty-0.0.17-cp311-cp311-win32.whl", hash = "sha256:ea8b3ae8c42d572cefad841d3bda63cc458d9de2361cb9172914250e6dbe2c75", size = 7230347, upload-time = "2026-04-22T20:14:08.083Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/82/d3119f59652d04bcf69d671ddbd38464d5775fbc738a258d3c8f7800e29d/pydantic_monty-0.0.17-cp311-cp311-win_amd64.whl", hash = "sha256:3293c2f7524bfc7c3d8c794f1c1dc1eb4cf9c65a5e222061e2218ced85f3f6df", size = 8074183, upload-time = "2026-04-22T20:14:50.42Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/31/95827babdb35149f076c5d191b6b1e7a7c58f4bc72432f905e02e4e3231e/pydantic_monty-0.0.17-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:27c2254fa7a7b05e969f79578889230d293c62e0b1ee28371ec4f3c54b14426a", size = 7342248, upload-time = "2026-04-22T20:15:18.775Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/67/ca9cfc07cd445d22def53e9db86912f9ae3e11ef772ce41c2ff41a47eac5/pydantic_monty-0.0.17-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:445cc471ce6f5a88ef06741b7ebc7002a2253d182f55a2f47094d4adedaaf497", size = 7311255, upload-time = "2026-04-22T20:15:27.913Z" },
+    { url = "https://files.pythonhosted.org/packages/df/96/abc9c4972d91a9673435b84e12b99d038e42d1f99648fc9e5f242e09d00e/pydantic_monty-0.0.17-cp312-cp312-manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:39121038405911f59da7bf61164251f59bad3fb1b0cd28f43c42c3949eee2c8a", size = 7868109, upload-time = "2026-04-22T20:15:04.779Z" },
+    { url = "https://files.pythonhosted.org/packages/75/82/9e4d55529bb99d882b9277a721762537a8bc1345ab1d052bb614a88bd15b/pydantic_monty-0.0.17-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:dafc8ffe57c257002f623afdb7d0e41f73de850179ebd90b42611e4f2b6f9884", size = 7139709, upload-time = "2026-04-22T20:15:25.386Z" },
+    { url = "https://files.pythonhosted.org/packages/96/97/f1af6acefb7bb38d73934d6853998bbd327de7418b811372519080d9fd84/pydantic_monty-0.0.17-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:ea00838ef8f37dcd8085defcbdfe89fdd05297a6533f1d3f4cad857d13cedc7b", size = 7450444, upload-time = "2026-04-22T20:13:37.974Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/91/af92ef409e1c065345cf1451bbcf19e00f70a250b8372ec65143ca9a9238/pydantic_monty-0.0.17-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:683d18089acf14d0de293245b9e37c7f0ec64e6d266f6773144211931aa3ec97", size = 7967525, upload-time = "2026-04-22T20:13:42.674Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/1f/23ecd6e268ef24ce6b0fe4a1e76a314990d2e923ac5791e29d657418243d/pydantic_monty-0.0.17-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:c1829993dd50cf497cbed66ea9f6c8ff7d157d22592a05c7399f92fb8a549e3c", size = 8199124, upload-time = "2026-04-22T20:15:00.02Z" },
+    { url = "https://files.pythonhosted.org/packages/42/2a/36b694ea0c7e202250a81a57faf00f218738da6c5d070c752f2d81cd34ce/pydantic_monty-0.0.17-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8a7869e3f41a54cc588096c52a8a4de25ecd81e75c867ea4164b14ea1ae1a57f", size = 7739623, upload-time = "2026-04-22T20:14:37.57Z" },
+    { url = "https://files.pythonhosted.org/packages/98/e5/090357d7bc0f0751d1afbb71330695fa26554699c88ba56ecaad91657088/pydantic_monty-0.0.17-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:f9c17663e2c6f07aec5bc54cd7e39a9e20f250a97a9081e1b2b932eb00d0afc5", size = 7317755, upload-time = "2026-04-22T20:14:48.367Z" },
+    { url = "https://files.pythonhosted.org/packages/15/63/67200070cf33325ecfda81d4aee3bf312250ce80bd73058103e04e0f3587/pydantic_monty-0.0.17-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:5d2cf98afe2fb124f6ade91d9663d54277478cad417164f83df1854a41ef450c", size = 7769158, upload-time = "2026-04-22T20:14:39.611Z" },
+    { url = "https://files.pythonhosted.org/packages/58/ce/9ecfbc2f45406cfb247fafdea4f4a8412db3e559a22c4385eb15266ba2c1/pydantic_monty-0.0.17-cp312-cp312-win32.whl", hash = "sha256:b2185cc4effbbd6793eed4e0f0bcb6a3dbfbb3289ea4d47888708813f0a3dd47", size = 7227917, upload-time = "2026-04-22T20:14:15.122Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/80/9be3bef8273817ccc17da25c3ce4ff5d5d45e5629c17eacc90cdef073821/pydantic_monty-0.0.17-cp312-cp312-win_amd64.whl", hash = "sha256:7833daed757ec9b09b627cc3577a4a76b114c5148f779531d7cfdb1095bcf0a9", size = 8043469, upload-time = "2026-04-22T20:13:22.102Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/44/0e106b8b27eb93b66e4f3d279486464e05ba5ee31088848e58b5f506f879/pydantic_monty-0.0.17-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:e0cdac8c3c16477596bc96ee1cec4f2fbaccd089e2daa1e7b9f227cc89f97cb1", size = 7341507, upload-time = "2026-04-22T20:14:41.717Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/88/a0315fa08e62e2d1ef00c03d8202d7bef3f1f71543bebfb916fea265c0a2/pydantic_monty-0.0.17-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:37290d6a1c35aba5cfb8b490bb31c0d822e8ddca8f3ca9ea068e30930d80dd1e", size = 7311916, upload-time = "2026-04-22T20:13:34.022Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/e5/e4da6acb408594cbfbfb8dd3c0491b9b2ee54e9183e7ebc5f584baa07af9/pydantic_monty-0.0.17-cp313-cp313-manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:49f252b2fb918686d3e8f76cb30245e782d1560a7fa68dbc0f6940d83c12bd41", size = 7867465, upload-time = "2026-04-22T20:13:31.466Z" },
+    { url = "https://files.pythonhosted.org/packages/58/d4/64c2f8eb708a743b0944ea8f71dfd51bc655285b4be28d55577dafbb29fa/pydantic_monty-0.0.17-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:2254d25c34463d67069f5f1567157bde9311654cd5371f8933b8ea9815bfa26a", size = 7139262, upload-time = "2026-04-22T20:14:10.715Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/67/5d766f9cd304e871a5dfe5f0a85eaa533538ef07e9b2858fdf9f37f83694/pydantic_monty-0.0.17-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:f0688a1fa5dc045ac7b7e996d7269b94f74f116d7b1e352c7b5bb5ad53d4fe03", size = 7450119, upload-time = "2026-04-22T20:13:44.515Z" },
+    { url = "https://files.pythonhosted.org/packages/33/98/fa16779021d93edb19807e87cdba56bbec6adfad21f10b41a212572ce513/pydantic_monty-0.0.17-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:7b35121ac555ed201405c69d531e4cb916da6984b8cd2e15c8a319117349faf6", size = 7967398, upload-time = "2026-04-22T20:13:55.576Z" },
+    { url = "https://files.pythonhosted.org/packages/92/64/287a42720bc9e975ab5b52625aa9fc6bcef8298dd821022cc45c6ee1808d/pydantic_monty-0.0.17-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:7c97dc44af25d4392b474902fc40f78f09fe8f44ba791364670334fe12abc077", size = 8198835, upload-time = "2026-04-22T20:15:02.072Z" },
+    { url = "https://files.pythonhosted.org/packages/97/37/03edb1fd582b79b2b462afc3fea5e1c8fea73afefc4870dc35fc3c7c492e/pydantic_monty-0.0.17-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:3ed2fb365ef9ca921de9a17786ecfa2efe06e65678e6ca57be51658a2a880f31", size = 7739241, upload-time = "2026-04-22T20:13:46.925Z" },
+    { url = "https://files.pythonhosted.org/packages/11/0b/b765c9ca2ae27def1caa07345aba073ae1239fc2d9cca7a375f3dc2195f7/pydantic_monty-0.0.17-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:5bf9f07b38dd12747e3c95b169a5afb3e2e9107622e01e548246c84d19a69c99", size = 7316719, upload-time = "2026-04-22T20:14:13.058Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/3b/64fe872cd575ab5262e1ba2959554ead198c939cfaa425f7f8e9b1ad2694/pydantic_monty-0.0.17-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:a5e9bafd4b5acbc0a8e12ee8403a3ce37281c3b0fa5909d3f412bee76c69003c", size = 7769150, upload-time = "2026-04-22T20:13:57.784Z" },
+    { url = "https://files.pythonhosted.org/packages/76/b4/b6a0bb41f39bac2e11e6a2fd42ca0886893fafa6344fb17c3f0a94e22e83/pydantic_monty-0.0.17-cp313-cp313-win32.whl", hash = "sha256:1c239ae3e610d3f39cd1609285209a4e2d046b465ac1bfed0d4374c615eed0fa", size = 7227705, upload-time = "2026-04-22T20:15:12.262Z" },
+    { url = "https://files.pythonhosted.org/packages/86/e7/d8cd62f537f7ab17714ee19ea221a0e341dab407215376ab1c41d79794c9/pydantic_monty-0.0.17-cp313-cp313-win_amd64.whl", hash = "sha256:1886c3590b02f359ae991f1e76691064f167330eda4fbf22762127ce17d0eb48", size = 8043469, upload-time = "2026-04-22T20:14:24.86Z" },
+    { url = "https://files.pythonhosted.org/packages/69/c0/8354baf835e1a04c4b9e11d253f82df7d625a9305e6a23a177fb895b1484/pydantic_monty-0.0.17-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:a166bd04d1996f0d144fbb5e1391cd1c0fbdacd4fa3b689dd48931388679fe98", size = 7341303, upload-time = "2026-04-22T20:14:35.653Z" },
+    { url = "https://files.pythonhosted.org/packages/00/ac/d58221b5e17915421ca00bb08b805ac121b6accb194785d5422da4a2f5fc/pydantic_monty-0.0.17-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:d82f319e3fd79707a7b81bbb68596509d14ac73502d2f0daf4ab5d281efdfbdc", size = 7318912, upload-time = "2026-04-22T20:13:59.966Z" },
+    { url = "https://files.pythonhosted.org/packages/81/3f/8eeb8f652f6cd6e06a737aa9f00de2949e37a669b31756bc51b6182457b4/pydantic_monty-0.0.17-cp314-cp314-manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:f38b9875f7ff56fe69538b60b2ecbdcbe2b8b7780407ceb05fe0ee1414bf8d19", size = 7867027, upload-time = "2026-04-22T20:13:51.426Z" },
+    { url = "https://files.pythonhosted.org/packages/55/ba/ec6620c27c8b4cada6ce53378c52c245e238e50a20b968cafdc1b8573c4e/pydantic_monty-0.0.17-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:74a778bb5a4dcdbc85b3b9002f9a72a43fb6ffd88635bfdd502e8d3053008337", size = 7137542, upload-time = "2026-04-22T20:13:35.939Z" },
+    { url = "https://files.pythonhosted.org/packages/41/78/5419785630511b54b15cfb094871bcb53ec9025ba8d91bd7ab5b22b6c98f/pydantic_monty-0.0.17-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:9e2ab074a65738e9c1b4be9a432e7ca1e9987a6706018dc7a5af6d4ce7cecdf3", size = 7450222, upload-time = "2026-04-22T20:13:53.378Z" },
+    { url = "https://files.pythonhosted.org/packages/61/04/cec11fa96a47034da3c21af53e73f43d2270f5ce96cd710809859fe9c0b2/pydantic_monty-0.0.17-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:00fd1cd28b4200c9ccd02629868486b366af1bfe1f0584d4c9e513b7a941a868", size = 7967405, upload-time = "2026-04-22T20:14:03.826Z" },
+    { url = "https://files.pythonhosted.org/packages/81/e3/f2be0fb975100b6936ca36a8410098f10fab3b26729c0b0d1de2fac59ff3/pydantic_monty-0.0.17-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:26ea6684555bfd00cbe9d2df3e73caada3d82200c168c63cc475197b55b88401", size = 8199028, upload-time = "2026-04-22T20:13:26.802Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/43/358bdaa9c50d21fe4a25a71d43ce9af2d6796616fa47aca84f807433564e/pydantic_monty-0.0.17-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:f804a03a3bbd0cf0ade1d4ce11b50ca6858e9c4440b27c746faf1d3c0a272954", size = 7749903, upload-time = "2026-04-22T20:15:09.626Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/da/8bcd0a78abf13edceca36aaf5c180fad963e4c2e042fd7247b9e96048306/pydantic_monty-0.0.17-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:b5476e6c08b86b0bea554b97ce9b142aac1177447f2d3c5751864b27991fd1b1", size = 7312704, upload-time = "2026-04-22T20:14:33.668Z" },
+    { url = "https://files.pythonhosted.org/packages/88/49/5de8bb7f8b82c3ebb8f2485e0b7a40055b072193039d95dcb5d35fcba72c/pydantic_monty-0.0.17-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:b5fcdcca45439844bee268686f37226dbf5803ec7a5945f5536c41419f151dac", size = 7768902, upload-time = "2026-04-22T20:14:29.389Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/7c/500a002f1a52f17c8b8a989875da3e1590c18ce95c89856aa967e2348a36/pydantic_monty-0.0.17-cp314-cp314-win32.whl", hash = "sha256:4dd3e6e80a415e7272f7a7583a4f8e045096653f6074e181117eb61fc8fe3b45", size = 7227049, upload-time = "2026-04-22T20:14:01.871Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/20/b8f552f2a863778f49ebb708f18aaf0bfb275480a48965786e06efacf1c4/pydantic_monty-0.0.17-cp314-cp314-win_amd64.whl", hash = "sha256:36a8090a628e8cf91df8f66c721a71050ac8f48473d4992b9afbd9585941a647", size = 8062999, upload-time = "2026-04-22T20:14:44.006Z" },
+]
+
+[[package]]
+name = "pydantic-settings"
+version = "2.14.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pydantic" },
+    { name = "python-dotenv" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5c/b5/8f48e906c3e0205276e8bd8cb7512217a87b2685304d64be27cad5b3019f/pydantic_settings-2.14.2.tar.gz", hash = "sha256:c19dd64b19097f1de80184f0cc7b0272a13ae6e170cbf240a3e27e381ed14a5f", size = 237700, upload-time = "2026-06-19T13:44:56.324Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/77/c1/6e422f34e569cf8e18df68d1939c81c099d2b61e4f7d9621c8a77560799c/pydantic_settings-2.14.2-py3-none-any.whl", hash = "sha256:a20c97b37910b6550d5ea50fbcc2d4187defe58cd57070b73863d069419c9440", size = 61715, upload-time = "2026-06-19T13:44:55.02Z" },
+]
+
+[[package]]
+name = "pydocket"
+version = "0.20.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "burner-redis" },
+    { name = "cloudpickle" },
+    { name = "cronsim" },
+    { name = "exceptiongroup", marker = "python_full_version < '3.11'" },
+    { name = "opentelemetry-api" },
+    { name = "prometheus-client" },
+    { name = "py-key-value-aio", extra = ["memory", "redis"] },
+    { name = "python-json-logger" },
+    { name = "redis" },
+    { name = "rich" },
+    { name = "taskgroup", marker = "python_full_version < '3.11'" },
+    { name = "typer" },
+    { name = "typing-extensions" },
+    { name = "tzdata", marker = "sys_platform == 'win32'" },
+    { name = "uncalled-for" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/bc/9d/05d54dccfaa505c0bc2e480bc331c44552cdc16af3f44f5893c75293a165/pydocket-0.20.0.tar.gz", hash = "sha256:4b5132a5754ba54f894d46bf2cbdc12e237adada73bc76ca367017536098df7f", size = 361050, upload-time = "2026-05-04T00:27:34.393Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/17/cb/635665c07be980ec48c92b830907e6796012801b107cb1166a213e49ec38/pydocket-0.20.0-py3-none-any.whl", hash = "sha256:1f745278be09d3526f1bdd579c2d92f77fa0a534a39b893e9ef21dfc2ee52378", size = 102483, upload-time = "2026-05-04T00:27:32.799Z" },
+]
+
+[[package]]
+name = "pygments"
+version = "2.20.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c3/b2/bc9c9196916376152d655522fdcebac55e66de6603a76a02bca1b6414f6c/pygments-2.20.0.tar.gz", hash = "sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f", size = 4955991, upload-time = "2026-03-29T13:29:33.898Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl", hash = "sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176", size = 1231151, upload-time = "2026-03-29T13:29:30.038Z" },
+]
+
+[[package]]
+name = "pyinstrument"
+version = "5.1.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/32/7f/d3c4ef7c43f3294bd5a475dfa6f295a9fee5243c292d5c8122044fa83bcb/pyinstrument-5.1.2.tar.gz", hash = "sha256:af149d672da9493fa37334a1cc68f7b80c3e6cb9fd99b9e426c447db5c650bf0", size = 266889, upload-time = "2026-01-04T18:38:58.464Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/43/74/c66e1bf3565600d78f53195efb6f8fd31610f85a58aa3fee39c56bf71d1b/pyinstrument-5.1.2-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:f224fe80ba288a00980af298d3808219f9d246fd95b4f91729c9c33a0dc54fe6", size = 131470, upload-time = "2026-01-04T18:37:22.536Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/6b/606c5bfa311b5be74f58ef505c678216dda2be3b76a2ac770c2b0fccff77/pyinstrument-5.1.2-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:7df09fc0d5b72daf48b73cdf07738761bff7f656c81aff686b3ccdd7d2abe236", size = 124567, upload-time = "2026-01-04T18:37:24.161Z" },
+    { url = "https://files.pythonhosted.org/packages/15/70/c8a88defb77873513971f590549c48ceb70f7ef10f30a689762ef36dd877/pyinstrument-5.1.2-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:75a7e17377d4405666bbaf126b1fd7bbb7e206d7246e6db3d62864d3d4790ae3", size = 149205, upload-time = "2026-01-04T18:37:25.696Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/4b/0e64fefb939af472c3fbc63ab45224766447bde73f51579f3ecc335b0a49/pyinstrument-5.1.2-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5381cc6583d26e04d9298acded4242f4fe71986f1472c8aee6992c6816f0cac5", size = 147900, upload-time = "2026-01-04T18:37:27.343Z" },
+    { url = "https://files.pythonhosted.org/packages/38/6e/b4209711c61176acfeb6c351e9f88a37ed3d3bc3b749c374c0a655ee8f50/pyinstrument-5.1.2-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:ec08a530bef8d3492d31d8b0b12d0cfde09539f2a1c4b9678662ebc3c843e478", size = 148133, upload-time = "2026-01-04T18:37:29.047Z" },
+    { url = "https://files.pythonhosted.org/packages/26/28/f323b70789833baf0628af7b9f797b8c1a13b695bd8aa582b1312f14b602/pyinstrument-5.1.2-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:9d671168508129b472be570bc9aee361190ba917b997c703bd134bb4de445ce7", size = 147652, upload-time = "2026-01-04T18:37:30.682Z" },
+    { url = "https://files.pythonhosted.org/packages/16/cd/9b0af0307a3a2cffb48ca76275c50b8bec3f85ca6e7b996e2e6cfbda1207/pyinstrument-5.1.2-cp310-cp310-win32.whl", hash = "sha256:5957a94f84564b374a7f856d1b322345d600964280b0d687b8ddcc483f21e576", size = 125793, upload-time = "2026-01-04T18:37:31.906Z" },
+    { url = "https://files.pythonhosted.org/packages/05/89/fe4c650c252aefb8064bfdff6c0a020d33d15c55dc22abfa1f352dcc2dd1/pyinstrument-5.1.2-cp310-cp310-win_amd64.whl", hash = "sha256:38a2180a7801c51610b50e5d423674b21872efd019ccf05a11b7f9016cb1dcfc", size = 126679, upload-time = "2026-01-04T18:37:33.59Z" },
+    { url = "https://files.pythonhosted.org/packages/79/ef/0288edd620fb0cf2074d8c8e3567007a6bac66307b839d99988563de4eb8/pyinstrument-5.1.2-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:3739a05583ea6312c385eb59fe985cd20d9048e95f9eeeb6a2f6c35202e2d36e", size = 131284, upload-time = "2026-01-04T18:37:35.01Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/4e/2a90a6997d9f7a39a6998d56de72e52673ebf5a9169a1c39dbf173e95105/pyinstrument-5.1.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:7c9ee05dc75ac5fb18498c311e624f77f7f321f7ff325b251aa09e52e46f1d6a", size = 124468, upload-time = "2026-01-04T18:37:36.628Z" },
+    { url = "https://files.pythonhosted.org/packages/04/74/7bfd403e81f9b5ec523f60cced8f516ee52312752bb2e0fafabfd90bbd78/pyinstrument-5.1.2-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7a49a55ca5b75218767e29cacbe515d0b66fc18cb48a937bca0f77b8dafc7202", size = 148057, upload-time = "2026-01-04T18:37:37.998Z" },
+    { url = "https://files.pythonhosted.org/packages/50/3a/7205d7c199947d18edcd013af4ddf4d3cca85c5488fbe493050035947f7c/pyinstrument-5.1.2-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0c45c14974ff04b1bfdc6c2a448627c6da7409c7800d0eb7bd03fb435dcb41d7", size = 146526, upload-time = "2026-01-04T18:37:39.642Z" },
+    { url = "https://files.pythonhosted.org/packages/24/e8/f6864172e7ebe4bc5209bafbc574a619b4c511b9506b941789b11441be7c/pyinstrument-5.1.2-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:22b9c04b3982c41c04b1c5ed05d1bc3a2ba26533450084058119f6dc160e70a3", size = 147179, upload-time = "2026-01-04T18:37:41.332Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/04/89ef2d1c34767bfdbcc74ab0c7e0d021d7fac5e79873239e4ca26e97d6da/pyinstrument-5.1.2-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:5c4995ee0774801790c138f0dfec17d4e7a7ef09a6d56d53cbcbf0578a711021", size = 146354, upload-time = "2026-01-04T18:37:42.808Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/d4/64441547ec12391b92c739a3b0685059e7dfa088d928df8364676ef7abc7/pyinstrument-5.1.2-cp311-cp311-win32.whl", hash = "sha256:fe449e4a8ee60a2a27cf509350a584670f4c3704649601be7937598f09dbe7ca", size = 125790, upload-time = "2026-01-04T18:37:44.141Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/8b/0a5f6b239294decb0ecd932711f3470bfbd42fc2e08a94cd5c1f4f6da7f1/pyinstrument-5.1.2-cp311-cp311-win_amd64.whl", hash = "sha256:3fb839429671a42bf349335af4c1ce5cf83386ac11f04df0bc40720d4cb7d77d", size = 126578, upload-time = "2026-01-04T18:37:45.423Z" },
+    { url = "https://files.pythonhosted.org/packages/26/d9/8fa5571ddd21b2b7189bd8b0bb4e90be1659a54dda5af51c7f6bf2b5666f/pyinstrument-5.1.2-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:2519865d4bf58936f2506c1c46a82d29a20f3239aa50c941df1ca9618c7da5f0", size = 131419, upload-time = "2026-01-04T18:37:46.843Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/50/0512adb83cadfeaa1a215dc9784defff5043c5aa052d15015e3d8013af75/pyinstrument-5.1.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:059442106b8b5de29ae5ac1bdc20d044fed4da534b8caba434b6ffb119037bf5", size = 124446, upload-time = "2026-01-04T18:37:48.572Z" },
+    { url = "https://files.pythonhosted.org/packages/9b/78/c45f0b668fb3c8c0d32058a451a8e1d34737cd7586387982185e12df1977/pyinstrument-5.1.2-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:cd51f2d54fc39a4cfd73ba6be27cd0187123132ce3f445b639bff5e1b23d7e26", size = 149694, upload-time = "2026-01-04T18:37:49.876Z" },
+    { url = "https://files.pythonhosted.org/packages/91/4d/2ca3ca9906ce6e05070f431c54d54ccbaf57a980cfa58032d35b0b0ac1f8/pyinstrument-5.1.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:12af1e83795b6c640d657d339014dd1ff718b182dec736d7d1f1d8a97534eb53", size = 148461, upload-time = "2026-01-04T18:37:51.544Z" },
+    { url = "https://files.pythonhosted.org/packages/18/d2/bfe84a4326172ef68655b65b49fd041eeb94c8e59ee47258589b8b79dd3b/pyinstrument-5.1.2-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:2565513658e742c5eb691a779cb29d19d01bc9ee951d0eb76482e9f343c38c2e", size = 148560, upload-time = "2026-01-04T18:37:52.931Z" },
+    { url = "https://files.pythonhosted.org/packages/d0/00/db7f5def351e869230b0165828c4edacbf3fdda8d66aff30dd73a62082c2/pyinstrument-5.1.2-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:5afd0ba788a1d112da49fb77966918e01df1f9e7d62e72894d82f7acb0996c2d", size = 148178, upload-time = "2026-01-04T18:37:54.278Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/bc/aea3329576e20b987d205027b8e6442ece845d681b9f9d8682d5404f81f3/pyinstrument-5.1.2-cp312-cp312-win32.whl", hash = "sha256:554077b031b278593cb2301f0057be771ea62a729878c69aaf29fcdfb7b71281", size = 125927, upload-time = "2026-01-04T18:37:55.615Z" },
+    { url = "https://files.pythonhosted.org/packages/14/e2/d928434ec3a840478e95fd0d73b0dfc0b8060a07b06f4b45e9df30444e9a/pyinstrument-5.1.2-cp312-cp312-win_amd64.whl", hash = "sha256:55a905384ba43efc924b8863aa6cfd276f029e4aa70c4a0e3b7389e27b191e45", size = 126675, upload-time = "2026-01-04T18:37:57.278Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/8e/b9aea969eec67c129652000446384d550a0df45c297adc9fd74da2f8482c/pyinstrument-5.1.2-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:7b8bab2334bf1d4c9e92d61db574300b914b594588a6b6dd67c45450152dfc29", size = 131418, upload-time = "2026-01-04T18:37:58.642Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/62/76418eb29b5591f3e5500369a6777ce928135c3aa6ccdb0c861a9c6ca93b/pyinstrument-5.1.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:13dcc138a61298ef4994b7aebff509d2c06db89dfd6e2021f0b9cd96aaa44ec3", size = 124448, upload-time = "2026-01-04T18:37:59.95Z" },
+    { url = "https://files.pythonhosted.org/packages/07/73/874bccc04bcf6f4babc3de1a9568e209e7e40998563974f5030b0fb4d3e0/pyinstrument-5.1.2-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c8abd4a7ffa2e7f9e00039a5e549e8eebc80d7ca8d43f0fb51a50ff2b117ce4a", size = 149853, upload-time = "2026-01-04T18:38:01.405Z" },
+    { url = "https://files.pythonhosted.org/packages/cf/85/268446c4388d77ff4abdeaff202356e1527b3ff9576f5587443a24980bec/pyinstrument-5.1.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:eb3a05108edebc30f31e2c69c904576042f1158b2513ab80adc08f7848a7a8f0", size = 148641, upload-time = "2026-01-04T18:38:03.086Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/15/4f8dea3381483e68d00582a9b823a21a088acfe77a847a7991a1a8feed76/pyinstrument-5.1.2-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:f70d588b53f3f35829d1d1ddfa05e07fcebf1434b3b1509d542ca317d8e9a2a5", size = 148674, upload-time = "2026-01-04T18:38:04.805Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/61/72c180454b6511d5b90166f8828e1bab3b45d0489952a1fe48c5c585233d/pyinstrument-5.1.2-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:b007327e0d6a6a01d5064883dd27c19996f044ce7488d507826fee7884e6a32e", size = 148315, upload-time = "2026-01-04T18:38:06.114Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/f0/4c27cebddf22a8840bd8b419366bb321ce41f921ca1893e309c932ab28bf/pyinstrument-5.1.2-cp313-cp313-win32.whl", hash = "sha256:9ba0e6b17a7e86c3dc02d208e4c25506e8f914d9964ae89449f1f37f0b70abc0", size = 125926, upload-time = "2026-01-04T18:38:07.507Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/20/6b1bee88ddef065b0df3a3ba4ba60ed8a9ca443d5cded7152a8a9750914f/pyinstrument-5.1.2-cp313-cp313-win_amd64.whl", hash = "sha256:660d7fc486a839814db0b2f716bc13d8b99b9c780aaeb47f74a70a34adc02a7b", size = 126678, upload-time = "2026-01-04T18:38:08.826Z" },
+    { url = "https://files.pythonhosted.org/packages/66/0f/7d5154c92904bdf25be067a7fe4cad4ba48919f16ccbb51bb953d9ae1a20/pyinstrument-5.1.2-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:0baed297beee2bb9897e737bbd89e3b9d45a2fbbea9f1ad4e809007d780a9b1e", size = 131388, upload-time = "2026-01-04T18:38:10.491Z" },
+    { url = "https://files.pythonhosted.org/packages/17/28/bf83231a3f951e11b4dfaf160e1eeba1ce29377eab30e3d2eb6ee22ff3ba/pyinstrument-5.1.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:ebb910a32a45bde6c3fc30c578efc28a54517990e11e94b5e48a0d5479728568", size = 124456, upload-time = "2026-01-04T18:38:11.792Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/98/762cf10896d907268629e1db08a48f128984a53e8d92b99ea96f862597e5/pyinstrument-5.1.2-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:bad403c157f9c6dba7f731a6fca5bfcd8ca2701a39bcc717dcc6e0b10055ffc4", size = 149594, upload-time = "2026-01-04T18:38:13.434Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/1b/48580e16e623d89af58b89c552c95a2ae65f70a1f4fab1d97879f34791db/pyinstrument-5.1.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:2f456cabdb95fd343c798a7f2a56688b028f981522e283c5f59bd59195b66df5", size = 148339, upload-time = "2026-01-04T18:38:14.767Z" },
+    { url = "https://files.pythonhosted.org/packages/62/7e/38157a8a6ec67789d8ee109fd09877ea3340df44e1a7add8f249e30a8ade/pyinstrument-5.1.2-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:4e9c4dcc1f2c4a0cd6b576e3604abc37496a7868243c9a1443ad3b9db69d590f", size = 148485, upload-time = "2026-01-04T18:38:16.121Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/34/31ee72b19cfc48a82801024b5d653f07982154a11381a3ae65bbfdbf2c7b/pyinstrument-5.1.2-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:acf93b128328c6d80fdb85431068ac17508f0f7845e89505b0ea6130dead5ca6", size = 148106, upload-time = "2026-01-04T18:38:17.623Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/b4/7ab20243187262d66ab062778b1ccac4ca55090752f32a83f603f4e5e3a2/pyinstrument-5.1.2-cp314-cp314-win32.whl", hash = "sha256:9c7f0167903ecff8b1d744f7e37b2bd4918e05a69cca724cb112f5ed59d1e41b", size = 126593, upload-time = "2026-01-04T18:38:18.968Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/a0/db6a8ae3182546227f5a043b1be29b8d5f98bf973e20d922981ef206de85/pyinstrument-5.1.2-cp314-cp314-win_amd64.whl", hash = "sha256:ce3f6b1f9a2b5d74819ecc07d631eadececf915f551474a75ad65ac580ec5a0e", size = 127358, upload-time = "2026-01-04T18:38:20.28Z" },
+    { url = "https://files.pythonhosted.org/packages/59/d2/719f439972b3f80e35fb5b1bcd888c3218d60dbc91957b99ffafd7ac9221/pyinstrument-5.1.2-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:af8651b239049accbeecd389d35823233f649446f76f47fd005316b05d08cef2", size = 132317, upload-time = "2026-01-04T18:38:21.669Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/1c/0ebfef69ae926665fae635424c5647411235c3689c9a9ad69fd68de6cae2/pyinstrument-5.1.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c6082f1c3e43e1d22834e91ba8975f0080186df4018a04b4dd29f9623c59df1d", size = 124917, upload-time = "2026-01-04T18:38:23.385Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/ee/5599f769f515a0f1c97443edc7394fe2b9829bf39f404c046499c1a62378/pyinstrument-5.1.2-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c031eb066ddc16425e1e2f56aad5c1ce1e27b2432a70329e5385b85e812decee", size = 157407, upload-time = "2026-01-04T18:38:24.774Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/40/32aa865252288caef301237488ee309bd6701125888bf453d23ab764e357/pyinstrument-5.1.2-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f447ec391cad30667ba412dce41607aaa20d4a2496a7ab867e0c199f0fe3ae3d", size = 155068, upload-time = "2026-01-04T18:38:26.112Z" },
+    { url = "https://files.pythonhosted.org/packages/91/68/0b56a1540fe1c357dfcda82d4f5b52c87fada5962cbf18703ea39ccbbe69/pyinstrument-5.1.2-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:50299bddfc1fe0039898f895b10ef12f9db08acffb4d85326fad589cda24d2ee", size = 155186, upload-time = "2026-01-04T18:38:27.914Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/48/7ef84abfc3e41148cf993095214f104e75ecff585e94c6e8be001e672573/pyinstrument-5.1.2-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:a193ff08825ece115ececa136832acb14c491c77ab1e6b6a361905df8753d5c6", size = 153979, upload-time = "2026-01-04T18:38:29.236Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/cf/a28ad117d58b33c1d74bcdfbbcf1603b67346883800ac7d510cff8d3bcee/pyinstrument-5.1.2-cp314-cp314t-win32.whl", hash = "sha256:de887ba19e1057bd2d86e6584f17788516a890ae6fe1b7eed9927873f416b4d8", size = 127267, upload-time = "2026-01-04T18:38:30.619Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/97/03635143a12a5d941f545548b00f8ac39d35565321a2effb4154ed267338/pyinstrument-5.1.2-cp314-cp314t-win_amd64.whl", hash = "sha256:b6a71f5e7f53c86c9b476b30cf19509463a63581ef17ddbd8680fee37ae509db", size = 128164, upload-time = "2026-01-04T18:38:32.281Z" },
+]
+
+[[package]]
+name = "pyjwt"
+version = "2.13.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/3b/81/58d0ac84e1ef3a3843791d6954d94c0b33d526c75eeb1efbce9d0a4c4077/pyjwt-2.13.0.tar.gz", hash = "sha256:41571c89ca91598c79e8ef18a2d07367d4810fbbd6f637794879baf1b7703423", size = 107515, upload-time = "2026-05-21T19:54:36.618Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a3/5e/ecf12fdb62546d64385c158514e9b2b671f7832108ef2ecd2020ce0af2d1/pyjwt-2.13.0-py3-none-any.whl", hash = "sha256:66adcc2aff09b3f1bbd95fc1e1577df8ac8723c978552fd43304c8a290ac5728", size = 31274, upload-time = "2026-05-21T19:54:35.362Z" },
+]
+
+[package.optional-dependencies]
+crypto = [
+    { name = "cryptography" },
+]
+
+[[package]]
+name = "pyperclip"
+version = "1.11.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e8/52/d87eba7cb129b81563019d1679026e7a112ef76855d6159d24754dbd2a51/pyperclip-1.11.0.tar.gz", hash = "sha256:244035963e4428530d9e3a6101a1ef97209c6825edab1567beac148ccc1db1b6", size = 12185, upload-time = "2025-09-26T14:40:37.245Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/df/80/fc9d01d5ed37ba4c42ca2b55b4339ae6e200b456be3a1aaddf4a9fa99b8c/pyperclip-1.11.0-py3-none-any.whl", hash = "sha256:299403e9ff44581cb9ba2ffeed69c7aa96a008622ad0c46cb575ca75b5b84273", size = 11063, upload-time = "2025-09-26T14:40:36.069Z" },
+]
+
+[[package]]
+name = "pyreadline3"
+version = "3.5.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/0f/49/4cea918a08f02817aabae639e3d0ac046fef9f9180518a3ad394e22da148/pyreadline3-3.5.4.tar.gz", hash = "sha256:8d57d53039a1c75adba8e50dd3d992b28143480816187ea5efbd5c78e6c885b7", size = 99839, upload-time = "2024-09-19T02:40:10.062Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/5a/dc/491b7661614ab97483abf2056be1deee4dc2490ecbf7bff9ab5cdbac86e1/pyreadline3-3.5.4-py3-none-any.whl", hash = "sha256:eaf8e6cc3c49bcccf145fc6067ba8643d1df34d604a1ec0eccbf7a18e6d3fae6", size = 83178, upload-time = "2024-09-19T02:40:08.598Z" },
+]
+
+[[package]]
+name = "pyrepl"
+version = "0.11.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/08/4f/7088417e5465c53a30b918d30542aad89352ea0d635a5d077717c69a7d2b/pyrepl-0.11.4.tar.gz", hash = "sha256:efe988b4a6e5eed587e9769dc2269aeec2b6feec2f5d77995ee85b9ad7cf7063", size = 51089, upload-time = "2025-07-17T22:56:25.42Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/bd/a5/ce97a778f096aaa27cfcb7ad09f1198cf73277dcab6c68a4b8f332d91e48/pyrepl-0.11.4-py3-none-any.whl", hash = "sha256:ac30d6340267a21c39e1b1934f92bca6b8735017d14b17e40f903b2d1563541d", size = 55596, upload-time = "2025-07-17T22:56:24.537Z" },
+]
+
+[[package]]
+name = "pytest"
+version = "9.0.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "exceptiongroup", marker = "python_full_version < '3.11'" },
+    { name = "iniconfig" },
+    { name = "packaging" },
+    { name = "pluggy" },
+    { name = "pygments" },
+    { name = "tomli", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/7d/0d/549bd94f1a0a402dc8cf64563a117c0f3765662e2e668477624baeec44d5/pytest-9.0.3.tar.gz", hash = "sha256:b86ada508af81d19edeb213c681b1d48246c1a91d304c6c81a427674c17eb91c", size = 1572165, upload-time = "2026-04-07T17:16:18.027Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl", hash = "sha256:2c5efc453d45394fdd706ade797c0a81091eccd1d6e4bccfcd476e2b8e0ab5d9", size = 375249, upload-time = "2026-04-07T17:16:16.13Z" },
+]
+
+[[package]]
+name = "pytest-asyncio"
+version = "1.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "backports-asyncio-runner", marker = "python_full_version < '3.11'" },
+    { name = "pytest" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/90/2c/8af215c0f776415f3590cac4f9086ccefd6fd463befeae41cd4d3f193e5a/pytest_asyncio-1.3.0.tar.gz", hash = "sha256:d7f52f36d231b80ee124cd216ffb19369aa168fc10095013c6b014a34d3ee9e5", size = 50087, upload-time = "2025-11-10T16:07:47.256Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl", hash = "sha256:611e26147c7f77640e6d0a92a38ed17c3e9848063698d5c93d5aa7aa11cebff5", size = 15075, upload-time = "2025-11-10T16:07:45.537Z" },
+]
+
+[[package]]
+name = "pytest-cov"
+version = "7.1.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "coverage", extra = ["toml"] },
+    { name = "pluggy" },
+    { name = "pytest" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b1/51/a849f96e117386044471c8ec2bd6cfebacda285da9525c9106aeb28da671/pytest_cov-7.1.0.tar.gz", hash = "sha256:30674f2b5f6351aa09702a9c8c364f6a01c27aae0c1366ae8016160d1efc56b2", size = 55592, upload-time = "2026-03-21T20:11:16.284Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9d/7a/d968e294073affff457b041c2be9868a40c1c71f4a35fcc1e45e5493067b/pytest_cov-7.1.0-py3-none-any.whl", hash = "sha256:a0461110b7865f9a271aa1b51e516c9a95de9d696734a2f71e3e78f46e1d4678", size = 22876, upload-time = "2026-03-21T20:11:14.438Z" },
+]
+
+[[package]]
+name = "pytest-env"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pytest" },
+    { name = "python-dotenv" },
+    { name = "tomli", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ff/69/4db1c30625af0621df8dbe73797b38b6d1b04e15d021dd5d26a6d297f78c/pytest_env-1.6.0.tar.gz", hash = "sha256:ac02d6fba16af54d61e311dd70a3c61024a4e966881ea844affc3c8f0bf207d3", size = 16163, upload-time = "2026-03-12T22:39:43.78Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/27/16/ad52f56b96d851a2bcfdc1e754c3531341885bd7177a128c13ff2ca72ab4/pytest_env-1.6.0-py3-none-any.whl", hash = "sha256:1e7f8a62215e5885835daaed694de8657c908505b964ec8097a7ce77b403d9a3", size = 10400, upload-time = "2026-03-12T22:39:41.887Z" },
+]
+
+[[package]]
+name = "pytest-examples"
+version = "0.0.18"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "black" },
+    { name = "pytest" },
+    { name = "ruff" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/af/71/4ae972fd95f474454aa450108ee1037830e7ba11840363e981b8d48fd16a/pytest_examples-0.0.18.tar.gz", hash = "sha256:9a464f007f805b113677a15e2f8942ebb92d7d3eb5312e9a405d018478ec9801", size = 21237, upload-time = "2025-05-06T07:46:10.705Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/09/52/7bbfb6e987d9a8a945f22941a8da63e3529465f1b106ef0e26f5df7c780d/pytest_examples-0.0.18-py3-none-any.whl", hash = "sha256:86c195b98c4e55049a0df3a0a990ca89123b7280473ab57608eecc6c47bcfe9c", size = 18169, upload-time = "2025-05-06T07:46:09.349Z" },
+]
+
+[[package]]
+name = "pytest-flakefinder"
+version = "1.1.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pytest" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ec/53/69c56a93ea057895b5761c5318455804873a6cd9d796d7c55d41c2358125/pytest-flakefinder-1.1.0.tar.gz", hash = "sha256:e2412a1920bdb8e7908783b20b3d57e9dad590cc39a93e8596ffdd493b403e0e", size = 6795, upload-time = "2022-10-26T18:27:54.243Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/33/8b/06787150d0fd0cbd3a8054262b56f91631c7778c1bc91bf4637e47f909ad/pytest_flakefinder-1.1.0-py2.py3-none-any.whl", hash = "sha256:741e0e8eea427052f5b8c89c2b3c3019a50c39a59ce4df6a305a2c2d9ba2bd13", size = 4644, upload-time = "2022-10-26T18:27:52.128Z" },
+]
+
+[[package]]
+name = "pytest-httpx"
+version = "0.36.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "httpx" },
+    { name = "pytest" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ca/bc/5574834da9499066fa1a5ea9c336f94dba2eae02298d36dab192fcf95c86/pytest_httpx-0.36.0.tar.gz", hash = "sha256:9edb66a5fd4388ce3c343189bc67e7e1cb50b07c2e3fc83b97d511975e8a831b", size = 56793, upload-time = "2025-12-02T16:34:57.414Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e2/d2/1eb1ea9c84f0d2033eb0b49675afdc71aa4ea801b74615f00f3c33b725e3/pytest_httpx-0.36.0-py3-none-any.whl", hash = "sha256:bd4c120bb80e142df856e825ec9f17981effb84d159f9fa29ed97e2357c3a9c8", size = 20229, upload-time = "2025-12-02T16:34:56.45Z" },
+]
+
+[[package]]
+name = "pytest-report"
+version = "0.2.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pytest" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/3b/82/e141da085de0b6dac3f047ae009e136bcedbcfca4ada082a55359d6f735e/pytest-report-0.2.1.tar.gz", hash = "sha256:d382e8db4c52a815d39dae5f21ee5edc0da3ae8ec19a22e55e9be5c60714a39d", size = 3517, upload-time = "2016-05-11T02:08:04.665Z" }
+
+[[package]]
+name = "pytest-retry"
+version = "1.7.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pytest" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c5/5b/607b017994cca28de3a1ad22a3eee8418e5d428dcd8ec25b26b18e995a73/pytest_retry-1.7.0.tar.gz", hash = "sha256:f8d52339f01e949df47c11ba9ee8d5b362f5824dff580d3870ec9ae0057df80f", size = 19977, upload-time = "2025-01-19T01:56:13.115Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7c/ff/3266c8a73b9b93c4b14160a7e2b31d1e1088e28ed29f4c2d93ae34093bfd/pytest_retry-1.7.0-py3-none-any.whl", hash = "sha256:a2dac85b79a4e2375943f1429479c65beb6c69553e7dae6b8332be47a60954f4", size = 13775, upload-time = "2025-01-19T01:56:11.199Z" },
+]
+
+[[package]]
+name = "pytest-timeout"
+version = "2.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pytest" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ac/82/4c9ecabab13363e72d880f2fb504c5f750433b2b6f16e99f4ec21ada284c/pytest_timeout-2.4.0.tar.gz", hash = "sha256:7e68e90b01f9eff71332b25001f85c75495fc4e3a836701876183c4bcfd0540a", size = 17973, upload-time = "2025-05-05T19:44:34.99Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl", hash = "sha256:c42667e5cdadb151aeb5b26d114aff6bdf5a907f176a007a30b940d3d865b5c2", size = 14382, upload-time = "2025-05-05T19:44:33.502Z" },
+]
+
+[[package]]
+name = "pytest-xdist"
+version = "3.8.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "execnet" },
+    { name = "pytest" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/78/b4/439b179d1ff526791eb921115fca8e44e596a13efeda518b9d845a619450/pytest_xdist-3.8.0.tar.gz", hash = "sha256:7e578125ec9bc6050861aa93f2d59f1d8d085595d6551c2c90b6f4fad8d3a9f1", size = 88069, upload-time = "2025-07-01T13:30:59.346Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ca/31/d4e37e9e550c2b92a9cbc2e4d0b7420a27224968580b5a447f420847c975/pytest_xdist-3.8.0-py3-none-any.whl", hash = "sha256:202ca578cfeb7370784a8c33d6d05bc6e13b4f25b5053c30a152269fd10f0b88", size = 46396, upload-time = "2025-07-01T13:30:56.632Z" },
+]
+
+[[package]]
+name = "python-dotenv"
+version = "1.2.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/82/ed/0301aeeac3e5353ef3d94b6ec08bbcabd04a72018415dcb29e588514bba8/python_dotenv-1.2.2.tar.gz", hash = "sha256:2c371a91fbd7ba082c2c1dc1f8bf89ca22564a087c2c287cd9b662adde799cf3", size = 50135, upload-time = "2026-03-01T16:00:26.196Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0b/d7/1959b9648791274998a9c3526f6d0ec8fd2233e4d4acce81bbae76b44b2a/python_dotenv-1.2.2-py3-none-any.whl", hash = "sha256:1d8214789a24de455a8b8bd8ae6fe3c6b69a5e3d64aa8a8e5d68e694bbcb285a", size = 22101, upload-time = "2026-03-01T16:00:25.09Z" },
+]
+
+[[package]]
+name = "python-json-logger"
+version = "4.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f7/ff/3cc9165fd44106973cd7ac9facb674a65ed853494592541d339bdc9a30eb/python_json_logger-4.1.0.tar.gz", hash = "sha256:b396b9e3ed782b09ff9d6e4f1683d46c83ad0d35d2e407c09a9ebbf038f88195", size = 17573, upload-time = "2026-03-29T04:39:56.805Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/27/be/0631a861af4d1c875f096c07d34e9a63639560a717130e7a87cbc82b7e3f/python_json_logger-4.1.0-py3-none-any.whl", hash = "sha256:132994765cf75bf44554be9aa49b06ef2345d23661a96720262716438141b6b2", size = 15021, upload-time = "2026-03-29T04:39:55.266Z" },
+]
+
+[[package]]
+name = "python-multipart"
+version = "0.0.32"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/5b/42/55c32bb9b12693c092ad250a0e82edb5b31ddeda6eb772de5f308b3804ad/python_multipart-0.0.32.tar.gz", hash = "sha256:be54b7f3fa167bb83e4fcd936b887b708f4e57fe75911c02aebf53efaf8d938e", size = 46881, upload-time = "2026-06-04T16:18:58.647Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e1/04/e8135ebd1ad02c56ec633277529b2602ff99ff634be76cdba5744cf554fd/python_multipart-0.0.32-py3-none-any.whl", hash = "sha256:ff6d3f776f16878c894e52e107296ffc890e913c611b1a4ec6c44e2821fe2e23", size = 30042, upload-time = "2026-06-04T16:18:57.319Z" },
+]
+
+[[package]]
+name = "pytokens"
+version = "0.4.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b6/34/b4e015b99031667a7b960f888889c5bd34ef585c85e1cb56a594b92836ac/pytokens-0.4.1.tar.gz", hash = "sha256:292052fe80923aae2260c073f822ceba21f3872ced9a68bb7953b348e561179a", size = 23015, upload-time = "2026-01-30T01:03:45.924Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/42/24/f206113e05cb8ef51b3850e7ef88f20da6f4bf932190ceb48bd3da103e10/pytokens-0.4.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:2a44ed93ea23415c54f3face3b65ef2b844d96aeb3455b8a69b3df6beab6acc5", size = 161522, upload-time = "2026-01-30T01:02:50.393Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/e9/06a6bf1b90c2ed81a9c7d2544232fe5d2891d1cd480e8a1809ca354a8eb2/pytokens-0.4.1-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:add8bf86b71a5d9fb5b89f023a80b791e04fba57960aa790cc6125f7f1d39dfe", size = 246945, upload-time = "2026-01-30T01:02:52.399Z" },
+    { url = "https://files.pythonhosted.org/packages/69/66/f6fb1007a4c3d8b682d5d65b7c1fb33257587a5f782647091e3408abe0b8/pytokens-0.4.1-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:670d286910b531c7b7e3c0b453fd8156f250adb140146d234a82219459b9640c", size = 259525, upload-time = "2026-01-30T01:02:53.737Z" },
+    { url = "https://files.pythonhosted.org/packages/04/92/086f89b4d622a18418bac74ab5db7f68cf0c21cf7cc92de6c7b919d76c88/pytokens-0.4.1-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:4e691d7f5186bd2842c14813f79f8884bb03f5995f0575272009982c5ac6c0f7", size = 262693, upload-time = "2026-01-30T01:02:54.871Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/7b/8b31c347cf94a3f900bdde750b2e9131575a61fdb620d3d3c75832262137/pytokens-0.4.1-cp310-cp310-win_amd64.whl", hash = "sha256:27b83ad28825978742beef057bfe406ad6ed524b2d28c252c5de7b4a6dd48fa2", size = 103567, upload-time = "2026-01-30T01:02:56.414Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/92/790ebe03f07b57e53b10884c329b9a1a308648fc083a6d4a39a10a28c8fc/pytokens-0.4.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:d70e77c55ae8380c91c0c18dea05951482e263982911fc7410b1ffd1dadd3440", size = 160864, upload-time = "2026-01-30T01:02:57.882Z" },
+    { url = "https://files.pythonhosted.org/packages/13/25/a4f555281d975bfdd1eba731450e2fe3a95870274da73fb12c40aeae7625/pytokens-0.4.1-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4a58d057208cb9075c144950d789511220b07636dd2e4708d5645d24de666bdc", size = 248565, upload-time = "2026-01-30T01:02:59.912Z" },
+    { url = "https://files.pythonhosted.org/packages/17/50/bc0394b4ad5b1601be22fa43652173d47e4c9efbf0044c62e9a59b747c56/pytokens-0.4.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b49750419d300e2b5a3813cf229d4e5a4c728dae470bcc89867a9ad6f25a722d", size = 260824, upload-time = "2026-01-30T01:03:01.471Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/54/3e04f9d92a4be4fc6c80016bc396b923d2a6933ae94b5f557c939c460ee0/pytokens-0.4.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:d9907d61f15bf7261d7e775bd5d7ee4d2930e04424bab1972591918497623a16", size = 264075, upload-time = "2026-01-30T01:03:04.143Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/1b/44b0326cb5470a4375f37988aea5d61b5cc52407143303015ebee94abfd6/pytokens-0.4.1-cp311-cp311-win_amd64.whl", hash = "sha256:ee44d0f85b803321710f9239f335aafe16553b39106384cef8e6de40cb4ef2f6", size = 103323, upload-time = "2026-01-30T01:03:05.412Z" },
+    { url = "https://files.pythonhosted.org/packages/41/5d/e44573011401fb82e9d51e97f1290ceb377800fb4eed650b96f4753b499c/pytokens-0.4.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:140709331e846b728475786df8aeb27d24f48cbcf7bcd449f8de75cae7a45083", size = 160663, upload-time = "2026-01-30T01:03:06.473Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/e6/5bbc3019f8e6f21d09c41f8b8654536117e5e211a85d89212d59cbdab381/pytokens-0.4.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6d6c4268598f762bc8e91f5dbf2ab2f61f7b95bdc07953b602db879b3c8c18e1", size = 255626, upload-time = "2026-01-30T01:03:08.177Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/3c/2d5297d82286f6f3d92770289fd439956b201c0a4fc7e72efb9b2293758e/pytokens-0.4.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:24afde1f53d95348b5a0eb19488661147285ca4dd7ed752bbc3e1c6242a304d1", size = 269779, upload-time = "2026-01-30T01:03:09.756Z" },
+    { url = "https://files.pythonhosted.org/packages/20/01/7436e9ad693cebda0551203e0bf28f7669976c60ad07d6402098208476de/pytokens-0.4.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:5ad948d085ed6c16413eb5fec6b3e02fa00dc29a2534f088d3302c47eb59adf9", size = 268076, upload-time = "2026-01-30T01:03:10.957Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/df/533c82a3c752ba13ae7ef238b7f8cdd272cf1475f03c63ac6cf3fcfb00b6/pytokens-0.4.1-cp312-cp312-win_amd64.whl", hash = "sha256:3f901fe783e06e48e8cbdc82d631fca8f118333798193e026a50ce1b3757ea68", size = 103552, upload-time = "2026-01-30T01:03:12.066Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/dc/08b1a080372afda3cceb4f3c0a7ba2bde9d6a5241f1edb02a22a019ee147/pytokens-0.4.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:8bdb9d0ce90cbf99c525e75a2fa415144fd570a1ba987380190e8b786bc6ef9b", size = 160720, upload-time = "2026-01-30T01:03:13.843Z" },
+    { url = "https://files.pythonhosted.org/packages/64/0c/41ea22205da480837a700e395507e6a24425151dfb7ead73343d6e2d7ffe/pytokens-0.4.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5502408cab1cb18e128570f8d598981c68a50d0cbd7c61312a90507cd3a1276f", size = 254204, upload-time = "2026-01-30T01:03:14.886Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/d2/afe5c7f8607018beb99971489dbb846508f1b8f351fcefc225fcf4b2adc0/pytokens-0.4.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:29d1d8fb1030af4d231789959f21821ab6325e463f0503a61d204343c9b355d1", size = 268423, upload-time = "2026-01-30T01:03:15.936Z" },
+    { url = "https://files.pythonhosted.org/packages/68/d4/00ffdbd370410c04e9591da9220a68dc1693ef7499173eb3e30d06e05ed1/pytokens-0.4.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:970b08dd6b86058b6dc07efe9e98414f5102974716232d10f32ff39701e841c4", size = 266859, upload-time = "2026-01-30T01:03:17.458Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/c9/c3161313b4ca0c601eeefabd3d3b576edaa9afdefd32da97210700e47652/pytokens-0.4.1-cp313-cp313-win_amd64.whl", hash = "sha256:9bd7d7f544d362576be74f9d5901a22f317efc20046efe2034dced238cbbfe78", size = 103520, upload-time = "2026-01-30T01:03:18.652Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/a7/b470f672e6fc5fee0a01d9e75005a0e617e162381974213a945fcd274843/pytokens-0.4.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:4a14d5f5fc78ce85e426aa159489e2d5961acf0e47575e08f35584009178e321", size = 160821, upload-time = "2026-01-30T01:03:19.684Z" },
+    { url = "https://files.pythonhosted.org/packages/80/98/e83a36fe8d170c911f864bfded690d2542bfcfacb9c649d11a9e6eb9dc41/pytokens-0.4.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:97f50fd18543be72da51dd505e2ed20d2228c74e0464e4262e4899797803d7fa", size = 254263, upload-time = "2026-01-30T01:03:20.834Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/95/70d7041273890f9f97a24234c00b746e8da86df462620194cef1d411ddeb/pytokens-0.4.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:dc74c035f9bfca0255c1af77ddd2d6ae8419012805453e4b0e7513e17904545d", size = 268071, upload-time = "2026-01-30T01:03:21.888Z" },
+    { url = "https://files.pythonhosted.org/packages/da/79/76e6d09ae19c99404656d7db9c35dfd20f2086f3eb6ecb496b5b31163bad/pytokens-0.4.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:f66a6bbe741bd431f6d741e617e0f39ec7257ca1f89089593479347cc4d13324", size = 271716, upload-time = "2026-01-30T01:03:23.633Z" },
+    { url = "https://files.pythonhosted.org/packages/79/37/482e55fa1602e0a7ff012661d8c946bafdc05e480ea5a32f4f7e336d4aa9/pytokens-0.4.1-cp314-cp314-win_amd64.whl", hash = "sha256:b35d7e5ad269804f6697727702da3c517bb8a5228afa450ab0fa787732055fc9", size = 104539, upload-time = "2026-01-30T01:03:24.788Z" },
+    { url = "https://files.pythonhosted.org/packages/30/e8/20e7db907c23f3d63b0be3b8a4fd1927f6da2395f5bcc7f72242bb963dfe/pytokens-0.4.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:8fcb9ba3709ff77e77f1c7022ff11d13553f3c30299a9fe246a166903e9091eb", size = 168474, upload-time = "2026-01-30T01:03:26.428Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/81/88a95ee9fafdd8f5f3452107748fd04c24930d500b9aba9738f3ade642cc/pytokens-0.4.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:79fc6b8699564e1f9b521582c35435f1bd32dd06822322ec44afdeba666d8cb3", size = 290473, upload-time = "2026-01-30T01:03:27.415Z" },
+    { url = "https://files.pythonhosted.org/packages/cf/35/3aa899645e29b6375b4aed9f8d21df219e7c958c4c186b465e42ee0a06bf/pytokens-0.4.1-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d31b97b3de0f61571a124a00ffe9a81fb9939146c122c11060725bd5aea79975", size = 303485, upload-time = "2026-01-30T01:03:28.558Z" },
+    { url = "https://files.pythonhosted.org/packages/52/a0/07907b6ff512674d9b201859f7d212298c44933633c946703a20c25e9d81/pytokens-0.4.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:967cf6e3fd4adf7de8fc73cd3043754ae79c36475c1c11d514fc72cf5490094a", size = 306698, upload-time = "2026-01-30T01:03:29.653Z" },
+    { url = "https://files.pythonhosted.org/packages/39/2a/cbbf9250020a4a8dd53ba83a46c097b69e5eb49dd14e708f496f548c6612/pytokens-0.4.1-cp314-cp314t-win_amd64.whl", hash = "sha256:584c80c24b078eec1e227079d56dc22ff755e0ba8654d8383b2c549107528918", size = 116287, upload-time = "2026-01-30T01:03:30.912Z" },
+    { url = "https://files.pythonhosted.org/packages/c6/78/397db326746f0a342855b81216ae1f0a32965deccfd7c830a2dbc66d2483/pytokens-0.4.1-py3-none-any.whl", hash = "sha256:26cef14744a8385f35d0e095dc8b3a7583f6c953c2e3d269c7f82484bf5ad2de", size = 13729, upload-time = "2026-01-30T01:03:45.029Z" },
+]
+
+[[package]]
+name = "pywin32"
+version = "311"
+source = { registry = "https://pypi.org/simple" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7b/40/44efbb0dfbd33aca6a6483191dae0716070ed99e2ecb0c53683f400a0b4f/pywin32-311-cp310-cp310-win32.whl", hash = "sha256:d03ff496d2a0cd4a5893504789d4a15399133fe82517455e78bad62efbb7f0a3", size = 8760432, upload-time = "2025-07-14T20:13:05.9Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/bf/360243b1e953bd254a82f12653974be395ba880e7ec23e3731d9f73921cc/pywin32-311-cp310-cp310-win_amd64.whl", hash = "sha256:797c2772017851984b97180b0bebe4b620bb86328e8a884bb626156295a63b3b", size = 9590103, upload-time = "2025-07-14T20:13:07.698Z" },
+    { url = "https://files.pythonhosted.org/packages/57/38/d290720e6f138086fb3d5ffe0b6caa019a791dd57866940c82e4eeaf2012/pywin32-311-cp310-cp310-win_arm64.whl", hash = "sha256:0502d1facf1fed4839a9a51ccbcc63d952cf318f78ffc00a7e78528ac27d7a2b", size = 8778557, upload-time = "2025-07-14T20:13:11.11Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/af/449a6a91e5d6db51420875c54f6aff7c97a86a3b13a0b4f1a5c13b988de3/pywin32-311-cp311-cp311-win32.whl", hash = "sha256:184eb5e436dea364dcd3d2316d577d625c0351bf237c4e9a5fabbcfa5a58b151", size = 8697031, upload-time = "2025-07-14T20:13:13.266Z" },
+    { url = "https://files.pythonhosted.org/packages/51/8f/9bb81dd5bb77d22243d33c8397f09377056d5c687aa6d4042bea7fbf8364/pywin32-311-cp311-cp311-win_amd64.whl", hash = "sha256:3ce80b34b22b17ccbd937a6e78e7225d80c52f5ab9940fe0506a1a16f3dab503", size = 9508308, upload-time = "2025-07-14T20:13:15.147Z" },
+    { url = "https://files.pythonhosted.org/packages/44/7b/9c2ab54f74a138c491aba1b1cd0795ba61f144c711daea84a88b63dc0f6c/pywin32-311-cp311-cp311-win_arm64.whl", hash = "sha256:a733f1388e1a842abb67ffa8e7aad0e70ac519e09b0f6a784e65a136ec7cefd2", size = 8703930, upload-time = "2025-07-14T20:13:16.945Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/ab/01ea1943d4eba0f850c3c61e78e8dd59757ff815ff3ccd0a84de5f541f42/pywin32-311-cp312-cp312-win32.whl", hash = "sha256:750ec6e621af2b948540032557b10a2d43b0cee2ae9758c54154d711cc852d31", size = 8706543, upload-time = "2025-07-14T20:13:20.765Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/a8/a0e8d07d4d051ec7502cd58b291ec98dcc0c3fff027caad0470b72cfcc2f/pywin32-311-cp312-cp312-win_amd64.whl", hash = "sha256:b8c095edad5c211ff31c05223658e71bf7116daa0ecf3ad85f3201ea3190d067", size = 9495040, upload-time = "2025-07-14T20:13:22.543Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/3a/2ae996277b4b50f17d61f0603efd8253cb2d79cc7ae159468007b586396d/pywin32-311-cp312-cp312-win_arm64.whl", hash = "sha256:e286f46a9a39c4a18b319c28f59b61de793654af2f395c102b4f819e584b5852", size = 8710102, upload-time = "2025-07-14T20:13:24.682Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/be/3fd5de0979fcb3994bfee0d65ed8ca9506a8a1260651b86174f6a86f52b3/pywin32-311-cp313-cp313-win32.whl", hash = "sha256:f95ba5a847cba10dd8c4d8fefa9f2a6cf283b8b88ed6178fa8a6c1ab16054d0d", size = 8705700, upload-time = "2025-07-14T20:13:26.471Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/28/e0a1909523c6890208295a29e05c2adb2126364e289826c0a8bc7297bd5c/pywin32-311-cp313-cp313-win_amd64.whl", hash = "sha256:718a38f7e5b058e76aee1c56ddd06908116d35147e133427e59a3983f703a20d", size = 9494700, upload-time = "2025-07-14T20:13:28.243Z" },
+    { url = "https://files.pythonhosted.org/packages/04/bf/90339ac0f55726dce7d794e6d79a18a91265bdf3aa70b6b9ca52f35e022a/pywin32-311-cp313-cp313-win_arm64.whl", hash = "sha256:7b4075d959648406202d92a2310cb990fea19b535c7f4a78d3f5e10b926eeb8a", size = 8709318, upload-time = "2025-07-14T20:13:30.348Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/31/097f2e132c4f16d99a22bfb777e0fd88bd8e1c634304e102f313af69ace5/pywin32-311-cp314-cp314-win32.whl", hash = "sha256:b7a2c10b93f8986666d0c803ee19b5990885872a7de910fc460f9b0c2fbf92ee", size = 8840714, upload-time = "2025-07-14T20:13:32.449Z" },
+    { url = "https://files.pythonhosted.org/packages/90/4b/07c77d8ba0e01349358082713400435347df8426208171ce297da32c313d/pywin32-311-cp314-cp314-win_amd64.whl", hash = "sha256:3aca44c046bd2ed8c90de9cb8427f581c479e594e99b5c0bb19b29c10fd6cb87", size = 9656800, upload-time = "2025-07-14T20:13:34.312Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/d2/21af5c535501a7233e734b8af901574572da66fcc254cb35d0609c9080dd/pywin32-311-cp314-cp314-win_arm64.whl", hash = "sha256:a508e2d9025764a8270f93111a970e1d0fbfc33f4153b388bb649b7eec4f9b42", size = 8932540, upload-time = "2025-07-14T20:13:36.379Z" },
+]
+
+[[package]]
+name = "pywin32-ctypes"
+version = "0.2.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/85/9f/01a1a99704853cb63f253eea009390c88e7131c67e66a0a02099a8c917cb/pywin32-ctypes-0.2.3.tar.gz", hash = "sha256:d162dc04946d704503b2edc4d55f3dba5c1d539ead017afa00142c38b9885755", size = 29471, upload-time = "2024-08-14T10:15:34.626Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/de/3d/8161f7711c017e01ac9f008dfddd9410dff3674334c233bde66e7ba65bbf/pywin32_ctypes-0.2.3-py3-none-any.whl", hash = "sha256:8a1513379d709975552d202d942d9837758905c8d01eb82b8bcc30918929e7b8", size = 30756, upload-time = "2024-08-14T10:15:33.187Z" },
+]
+
+[[package]]
+name = "pyyaml"
+version = "6.0.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/05/8e/961c0007c59b8dd7729d542c61a4d537767a59645b82a0b521206e1e25c2/pyyaml-6.0.3.tar.gz", hash = "sha256:d76623373421df22fb4cf8817020cbb7ef15c725b9d5e45f17e189bfc384190f", size = 130960, upload-time = "2025-09-25T21:33:16.546Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f4/a0/39350dd17dd6d6c6507025c0e53aef67a9293a6d37d3511f23ea510d5800/pyyaml-6.0.3-cp310-cp310-macosx_10_13_x86_64.whl", hash = "sha256:214ed4befebe12df36bcc8bc2b64b396ca31be9304b8f59e25c11cf94a4c033b", size = 184227, upload-time = "2025-09-25T21:31:46.04Z" },
+    { url = "https://files.pythonhosted.org/packages/05/14/52d505b5c59ce73244f59c7a50ecf47093ce4765f116cdb98286a71eeca2/pyyaml-6.0.3-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:02ea2dfa234451bbb8772601d7b8e426c2bfa197136796224e50e35a78777956", size = 174019, upload-time = "2025-09-25T21:31:47.706Z" },
+    { url = "https://files.pythonhosted.org/packages/43/f7/0e6a5ae5599c838c696adb4e6330a59f463265bfa1e116cfd1fbb0abaaae/pyyaml-6.0.3-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b30236e45cf30d2b8e7b3e85881719e98507abed1011bf463a8fa23e9c3e98a8", size = 740646, upload-time = "2025-09-25T21:31:49.21Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/3a/61b9db1d28f00f8fd0ae760459a5c4bf1b941baf714e207b6eb0657d2578/pyyaml-6.0.3-cp310-cp310-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:66291b10affd76d76f54fad28e22e51719ef9ba22b29e1d7d03d6777a9174198", size = 840793, upload-time = "2025-09-25T21:31:50.735Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/1e/7acc4f0e74c4b3d9531e24739e0ab832a5edf40e64fbae1a9c01941cabd7/pyyaml-6.0.3-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9c7708761fccb9397fe64bbc0395abcae8c4bf7b0eac081e12b809bf47700d0b", size = 770293, upload-time = "2025-09-25T21:31:51.828Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/ef/abd085f06853af0cd59fa5f913d61a8eab65d7639ff2a658d18a25d6a89d/pyyaml-6.0.3-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:418cf3f2111bc80e0933b2cd8cd04f286338bb88bdc7bc8e6dd775ebde60b5e0", size = 732872, upload-time = "2025-09-25T21:31:53.282Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/15/2bc9c8faf6450a8b3c9fc5448ed869c599c0a74ba2669772b1f3a0040180/pyyaml-6.0.3-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:5e0b74767e5f8c593e8c9b5912019159ed0533c70051e9cce3e8b6aa699fcd69", size = 758828, upload-time = "2025-09-25T21:31:54.807Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/00/531e92e88c00f4333ce359e50c19b8d1de9fe8d581b1534e35ccfbc5f393/pyyaml-6.0.3-cp310-cp310-win32.whl", hash = "sha256:28c8d926f98f432f88adc23edf2e6d4921ac26fb084b028c733d01868d19007e", size = 142415, upload-time = "2025-09-25T21:31:55.885Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/fa/926c003379b19fca39dd4634818b00dec6c62d87faf628d1394e137354d4/pyyaml-6.0.3-cp310-cp310-win_amd64.whl", hash = "sha256:bdb2c67c6c1390b63c6ff89f210c8fd09d9a1217a465701eac7316313c915e4c", size = 158561, upload-time = "2025-09-25T21:31:57.406Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/16/a95b6757765b7b031c9374925bb718d55e0a9ba8a1b6a12d25962ea44347/pyyaml-6.0.3-cp311-cp311-macosx_10_13_x86_64.whl", hash = "sha256:44edc647873928551a01e7a563d7452ccdebee747728c1080d881d68af7b997e", size = 185826, upload-time = "2025-09-25T21:31:58.655Z" },
+    { url = "https://files.pythonhosted.org/packages/16/19/13de8e4377ed53079ee996e1ab0a9c33ec2faf808a4647b7b4c0d46dd239/pyyaml-6.0.3-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:652cb6edd41e718550aad172851962662ff2681490a8a711af6a4d288dd96824", size = 175577, upload-time = "2025-09-25T21:32:00.088Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/62/d2eb46264d4b157dae1275b573017abec435397aa59cbcdab6fc978a8af4/pyyaml-6.0.3-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:10892704fc220243f5305762e276552a0395f7beb4dbf9b14ec8fd43b57f126c", size = 775556, upload-time = "2025-09-25T21:32:01.31Z" },
+    { url = "https://files.pythonhosted.org/packages/10/cb/16c3f2cf3266edd25aaa00d6c4350381c8b012ed6f5276675b9eba8d9ff4/pyyaml-6.0.3-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:850774a7879607d3a6f50d36d04f00ee69e7fc816450e5f7e58d7f17f1ae5c00", size = 882114, upload-time = "2025-09-25T21:32:03.376Z" },
+    { url = "https://files.pythonhosted.org/packages/71/60/917329f640924b18ff085ab889a11c763e0b573da888e8404ff486657602/pyyaml-6.0.3-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b8bb0864c5a28024fac8a632c443c87c5aa6f215c0b126c449ae1a150412f31d", size = 806638, upload-time = "2025-09-25T21:32:04.553Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/6f/529b0f316a9fd167281a6c3826b5583e6192dba792dd55e3203d3f8e655a/pyyaml-6.0.3-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:1d37d57ad971609cf3c53ba6a7e365e40660e3be0e5175fa9f2365a379d6095a", size = 767463, upload-time = "2025-09-25T21:32:06.152Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/6a/b627b4e0c1dd03718543519ffb2f1deea4a1e6d42fbab8021936a4d22589/pyyaml-6.0.3-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:37503bfbfc9d2c40b344d06b2199cf0e96e97957ab1c1b546fd4f87e53e5d3e4", size = 794986, upload-time = "2025-09-25T21:32:07.367Z" },
+    { url = "https://files.pythonhosted.org/packages/45/91/47a6e1c42d9ee337c4839208f30d9f09caa9f720ec7582917b264defc875/pyyaml-6.0.3-cp311-cp311-win32.whl", hash = "sha256:8098f252adfa6c80ab48096053f512f2321f0b998f98150cea9bd23d83e1467b", size = 142543, upload-time = "2025-09-25T21:32:08.95Z" },
+    { url = "https://files.pythonhosted.org/packages/da/e3/ea007450a105ae919a72393cb06f122f288ef60bba2dc64b26e2646fa315/pyyaml-6.0.3-cp311-cp311-win_amd64.whl", hash = "sha256:9f3bfb4965eb874431221a3ff3fdcddc7e74e3b07799e0e84ca4a0f867d449bf", size = 158763, upload-time = "2025-09-25T21:32:09.96Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/33/422b98d2195232ca1826284a76852ad5a86fe23e31b009c9886b2d0fb8b2/pyyaml-6.0.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:7f047e29dcae44602496db43be01ad42fc6f1cc0d8cd6c83d342306c32270196", size = 182063, upload-time = "2025-09-25T21:32:11.445Z" },
+    { url = "https://files.pythonhosted.org/packages/89/a0/6cf41a19a1f2f3feab0e9c0b74134aa2ce6849093d5517a0c550fe37a648/pyyaml-6.0.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:fc09d0aa354569bc501d4e787133afc08552722d3ab34836a80547331bb5d4a0", size = 173973, upload-time = "2025-09-25T21:32:12.492Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/23/7a778b6bd0b9a8039df8b1b1d80e2e2ad78aa04171592c8a5c43a56a6af4/pyyaml-6.0.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9149cad251584d5fb4981be1ecde53a1ca46c891a79788c0df828d2f166bda28", size = 775116, upload-time = "2025-09-25T21:32:13.652Z" },
+    { url = "https://files.pythonhosted.org/packages/65/30/d7353c338e12baef4ecc1b09e877c1970bd3382789c159b4f89d6a70dc09/pyyaml-6.0.3-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5fdec68f91a0c6739b380c83b951e2c72ac0197ace422360e6d5a959d8d97b2c", size = 844011, upload-time = "2025-09-25T21:32:15.21Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/9d/b3589d3877982d4f2329302ef98a8026e7f4443c765c46cfecc8858c6b4b/pyyaml-6.0.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ba1cc08a7ccde2d2ec775841541641e4548226580ab850948cbfda66a1befcdc", size = 807870, upload-time = "2025-09-25T21:32:16.431Z" },
+    { url = "https://files.pythonhosted.org/packages/05/c0/b3be26a015601b822b97d9149ff8cb5ead58c66f981e04fedf4e762f4bd4/pyyaml-6.0.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:8dc52c23056b9ddd46818a57b78404882310fb473d63f17b07d5c40421e47f8e", size = 761089, upload-time = "2025-09-25T21:32:17.56Z" },
+    { url = "https://files.pythonhosted.org/packages/be/8e/98435a21d1d4b46590d5459a22d88128103f8da4c2d4cb8f14f2a96504e1/pyyaml-6.0.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:41715c910c881bc081f1e8872880d3c650acf13dfa8214bad49ed4cede7c34ea", size = 790181, upload-time = "2025-09-25T21:32:18.834Z" },
+    { url = "https://files.pythonhosted.org/packages/74/93/7baea19427dcfbe1e5a372d81473250b379f04b1bd3c4c5ff825e2327202/pyyaml-6.0.3-cp312-cp312-win32.whl", hash = "sha256:96b533f0e99f6579b3d4d4995707cf36df9100d67e0c8303a0c55b27b5f99bc5", size = 137658, upload-time = "2025-09-25T21:32:20.209Z" },
+    { url = "https://files.pythonhosted.org/packages/86/bf/899e81e4cce32febab4fb42bb97dcdf66bc135272882d1987881a4b519e9/pyyaml-6.0.3-cp312-cp312-win_amd64.whl", hash = "sha256:5fcd34e47f6e0b794d17de1b4ff496c00986e1c83f7ab2fb8fcfe9616ff7477b", size = 154003, upload-time = "2025-09-25T21:32:21.167Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/08/67bd04656199bbb51dbed1439b7f27601dfb576fb864099c7ef0c3e55531/pyyaml-6.0.3-cp312-cp312-win_arm64.whl", hash = "sha256:64386e5e707d03a7e172c0701abfb7e10f0fb753ee1d773128192742712a98fd", size = 140344, upload-time = "2025-09-25T21:32:22.617Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/11/0fd08f8192109f7169db964b5707a2f1e8b745d4e239b784a5a1dd80d1db/pyyaml-6.0.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:8da9669d359f02c0b91ccc01cac4a67f16afec0dac22c2ad09f46bee0697eba8", size = 181669, upload-time = "2025-09-25T21:32:23.673Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/16/95309993f1d3748cd644e02e38b75d50cbc0d9561d21f390a76242ce073f/pyyaml-6.0.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:2283a07e2c21a2aa78d9c4442724ec1eb15f5e42a723b99cb3d822d48f5f7ad1", size = 173252, upload-time = "2025-09-25T21:32:25.149Z" },
+    { url = "https://files.pythonhosted.org/packages/50/31/b20f376d3f810b9b2371e72ef5adb33879b25edb7a6d072cb7ca0c486398/pyyaml-6.0.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ee2922902c45ae8ccada2c5b501ab86c36525b883eff4255313a253a3160861c", size = 767081, upload-time = "2025-09-25T21:32:26.575Z" },
+    { url = "https://files.pythonhosted.org/packages/49/1e/a55ca81e949270d5d4432fbbd19dfea5321eda7c41a849d443dc92fd1ff7/pyyaml-6.0.3-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a33284e20b78bd4a18c8c2282d549d10bc8408a2a7ff57653c0cf0b9be0afce5", size = 841159, upload-time = "2025-09-25T21:32:27.727Z" },
+    { url = "https://files.pythonhosted.org/packages/74/27/e5b8f34d02d9995b80abcef563ea1f8b56d20134d8f4e5e81733b1feceb2/pyyaml-6.0.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0f29edc409a6392443abf94b9cf89ce99889a1dd5376d94316ae5145dfedd5d6", size = 801626, upload-time = "2025-09-25T21:32:28.878Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/11/ba845c23988798f40e52ba45f34849aa8a1f2d4af4b798588010792ebad6/pyyaml-6.0.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:f7057c9a337546edc7973c0d3ba84ddcdf0daa14533c2065749c9075001090e6", size = 753613, upload-time = "2025-09-25T21:32:30.178Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/e0/7966e1a7bfc0a45bf0a7fb6b98ea03fc9b8d84fa7f2229e9659680b69ee3/pyyaml-6.0.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:eda16858a3cab07b80edaf74336ece1f986ba330fdb8ee0d6c0d68fe82bc96be", size = 794115, upload-time = "2025-09-25T21:32:31.353Z" },
+    { url = "https://files.pythonhosted.org/packages/de/94/980b50a6531b3019e45ddeada0626d45fa85cbe22300844a7983285bed3b/pyyaml-6.0.3-cp313-cp313-win32.whl", hash = "sha256:d0eae10f8159e8fdad514efdc92d74fd8d682c933a6dd088030f3834bc8e6b26", size = 137427, upload-time = "2025-09-25T21:32:32.58Z" },
+    { url = "https://files.pythonhosted.org/packages/97/c9/39d5b874e8b28845e4ec2202b5da735d0199dbe5b8fb85f91398814a9a46/pyyaml-6.0.3-cp313-cp313-win_amd64.whl", hash = "sha256:79005a0d97d5ddabfeeea4cf676af11e647e41d81c9a7722a193022accdb6b7c", size = 154090, upload-time = "2025-09-25T21:32:33.659Z" },
+    { url = "https://files.pythonhosted.org/packages/73/e8/2bdf3ca2090f68bb3d75b44da7bbc71843b19c9f2b9cb9b0f4ab7a5a4329/pyyaml-6.0.3-cp313-cp313-win_arm64.whl", hash = "sha256:5498cd1645aa724a7c71c8f378eb29ebe23da2fc0d7a08071d89469bf1d2defb", size = 140246, upload-time = "2025-09-25T21:32:34.663Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/8c/f4bd7f6465179953d3ac9bc44ac1a8a3e6122cf8ada906b4f96c60172d43/pyyaml-6.0.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:8d1fab6bb153a416f9aeb4b8763bc0f22a5586065f86f7664fc23339fc1c1fac", size = 181814, upload-time = "2025-09-25T21:32:35.712Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/9c/4d95bb87eb2063d20db7b60faa3840c1b18025517ae857371c4dd55a6b3a/pyyaml-6.0.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:34d5fcd24b8445fadc33f9cf348c1047101756fd760b4dacb5c3e99755703310", size = 173809, upload-time = "2025-09-25T21:32:36.789Z" },
+    { url = "https://files.pythonhosted.org/packages/92/b5/47e807c2623074914e29dabd16cbbdd4bf5e9b2db9f8090fa64411fc5382/pyyaml-6.0.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:501a031947e3a9025ed4405a168e6ef5ae3126c59f90ce0cd6f2bfc477be31b7", size = 766454, upload-time = "2025-09-25T21:32:37.966Z" },
+    { url = "https://files.pythonhosted.org/packages/02/9e/e5e9b168be58564121efb3de6859c452fccde0ab093d8438905899a3a483/pyyaml-6.0.3-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:b3bc83488de33889877a0f2543ade9f70c67d66d9ebb4ac959502e12de895788", size = 836355, upload-time = "2025-09-25T21:32:39.178Z" },
+    { url = "https://files.pythonhosted.org/packages/88/f9/16491d7ed2a919954993e48aa941b200f38040928474c9e85ea9e64222c3/pyyaml-6.0.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c458b6d084f9b935061bc36216e8a69a7e293a2f1e68bf956dcd9e6cbcd143f5", size = 794175, upload-time = "2025-09-25T21:32:40.865Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/3f/5989debef34dc6397317802b527dbbafb2b4760878a53d4166579111411e/pyyaml-6.0.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7c6610def4f163542a622a73fb39f534f8c101d690126992300bf3207eab9764", size = 755228, upload-time = "2025-09-25T21:32:42.084Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/ce/af88a49043cd2e265be63d083fc75b27b6ed062f5f9fd6cdc223ad62f03e/pyyaml-6.0.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:5190d403f121660ce8d1d2c1bb2ef1bd05b5f68533fc5c2ea899bd15f4399b35", size = 789194, upload-time = "2025-09-25T21:32:43.362Z" },
+    { url = "https://files.pythonhosted.org/packages/23/20/bb6982b26a40bb43951265ba29d4c246ef0ff59c9fdcdf0ed04e0687de4d/pyyaml-6.0.3-cp314-cp314-win_amd64.whl", hash = "sha256:4a2e8cebe2ff6ab7d1050ecd59c25d4c8bd7e6f400f5f82b96557ac0abafd0ac", size = 156429, upload-time = "2025-09-25T21:32:57.844Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/f4/a4541072bb9422c8a883ab55255f918fa378ecf083f5b85e87fc2b4eda1b/pyyaml-6.0.3-cp314-cp314-win_arm64.whl", hash = "sha256:93dda82c9c22deb0a405ea4dc5f2d0cda384168e466364dec6255b293923b2f3", size = 143912, upload-time = "2025-09-25T21:32:59.247Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/f9/07dd09ae774e4616edf6cda684ee78f97777bdd15847253637a6f052a62f/pyyaml-6.0.3-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:02893d100e99e03eda1c8fd5c441d8c60103fd175728e23e431db1b589cf5ab3", size = 189108, upload-time = "2025-09-25T21:32:44.377Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/78/8d08c9fb7ce09ad8c38ad533c1191cf27f7ae1effe5bb9400a46d9437fcf/pyyaml-6.0.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c1ff362665ae507275af2853520967820d9124984e0f7466736aea23d8611fba", size = 183641, upload-time = "2025-09-25T21:32:45.407Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/5b/3babb19104a46945cf816d047db2788bcaf8c94527a805610b0289a01c6b/pyyaml-6.0.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6adc77889b628398debc7b65c073bcb99c4a0237b248cacaf3fe8a557563ef6c", size = 831901, upload-time = "2025-09-25T21:32:48.83Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/cc/dff0684d8dc44da4d22a13f35f073d558c268780ce3c6ba1b87055bb0b87/pyyaml-6.0.3-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a80cb027f6b349846a3bf6d73b5e95e782175e52f22108cfa17876aaeff93702", size = 861132, upload-time = "2025-09-25T21:32:50.149Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/5e/f77dc6b9036943e285ba76b49e118d9ea929885becb0a29ba8a7c75e29fe/pyyaml-6.0.3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:00c4bdeba853cc34e7dd471f16b4114f4162dc03e6b7afcc2128711f0eca823c", size = 839261, upload-time = "2025-09-25T21:32:51.808Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/88/a9db1376aa2a228197c58b37302f284b5617f56a5d959fd1763fb1675ce6/pyyaml-6.0.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:66e1674c3ef6f541c35191caae2d429b967b99e02040f5ba928632d9a7f0f065", size = 805272, upload-time = "2025-09-25T21:32:52.941Z" },
+    { url = "https://files.pythonhosted.org/packages/da/92/1446574745d74df0c92e6aa4a7b0b3130706a4142b2d1a5869f2eaa423c6/pyyaml-6.0.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:16249ee61e95f858e83976573de0f5b2893b3677ba71c9dd36b9cf8be9ac6d65", size = 829923, upload-time = "2025-09-25T21:32:54.537Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/7a/1c7270340330e575b92f397352af856a8c06f230aa3e76f86b39d01b416a/pyyaml-6.0.3-cp314-cp314t-win_amd64.whl", hash = "sha256:4ad1906908f2f5ae4e5a8ddfce73c320c2a1429ec52eafd27138b7f1cbe341c9", size = 174062, upload-time = "2025-09-25T21:32:55.767Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/12/de94a39c2ef588c7e6455cfbe7343d3b2dc9d6b6b2f40c4c6565744c873d/pyyaml-6.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:ebc55a14a21cb14062aa4162f906cd962b28e2e9ea38f9b4391244cd8de4ae0b", size = 149341, upload-time = "2025-09-25T21:32:56.828Z" },
+]
+
+[[package]]
+name = "redis"
+version = "7.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "async-timeout", marker = "python_full_version < '3.11.3'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/7b/7f/3759b1d0d72b7c92f0d70ffd9dc962b7b7b5ee74e135f9d7d8ab06b8a318/redis-7.4.0.tar.gz", hash = "sha256:64a6ea7bf567ad43c964d2c30d82853f8df927c5c9017766c55a1d1ed95d18ad", size = 4943913, upload-time = "2026-03-24T09:14:37.53Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/74/3a/95deec7db1eb53979973ebd156f3369a72732208d1391cd2e5d127062a32/redis-7.4.0-py3-none-any.whl", hash = "sha256:a9c74a5c893a5ef8455a5adb793a31bb70feb821c86eccb62eebef5a19c429ec", size = 409772, upload-time = "2026-03-24T09:14:35.968Z" },
+]
+
+[[package]]
+name = "referencing"
+version = "0.37.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "attrs" },
+    { name = "rpds-py" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/22/f5/df4e9027acead3ecc63e50fe1e36aca1523e1719559c499951bb4b53188f/referencing-0.37.0.tar.gz", hash = "sha256:44aefc3142c5b842538163acb373e24cce6632bd54bdb01b21ad5863489f50d8", size = 78036, upload-time = "2025-10-13T15:30:48.871Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2c/58/ca301544e1fa93ed4f80d724bf5b194f6e4b945841c5bfd555878eea9fcb/referencing-0.37.0-py3-none-any.whl", hash = "sha256:381329a9f99628c9069361716891d34ad94af76e461dcb0335825aecc7692231", size = 26766, upload-time = "2025-10-13T15:30:47.625Z" },
+]
+
+[[package]]
+name = "requests"
+version = "2.33.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "certifi" },
+    { name = "charset-normalizer" },
+    { name = "idna" },
+    { name = "urllib3" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/34/64/8860370b167a9721e8956ae116825caff829224fbca0ca6e7bf8ddef8430/requests-2.33.0.tar.gz", hash = "sha256:c7ebc5e8b0f21837386ad0e1c8fe8b829fa5f544d8df3b2253bff14ef29d7652", size = 134232, upload-time = "2026-03-25T15:10:41.586Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/56/5d/c814546c2333ceea4ba42262d8c4d55763003e767fa169adc693bd524478/requests-2.33.0-py3-none-any.whl", hash = "sha256:3324635456fa185245e24865e810cecec7b4caf933d7eb133dcde67d48cee69b", size = 65017, upload-time = "2026-03-25T15:10:40.382Z" },
+]
+
+[[package]]
+name = "rich"
+version = "14.3.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "markdown-it-py" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b3/c6/f3b320c27991c46f43ee9d856302c70dc2d0fb2dba4842ff739d5f46b393/rich-14.3.3.tar.gz", hash = "sha256:b8daa0b9e4eef54dd8cf7c86c03713f53241884e814f4e2f5fb342fe520f639b", size = 230582, upload-time = "2026-02-19T17:23:12.474Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/14/25/b208c5683343959b670dc001595f2f3737e051da617f66c31f7c4fa93abc/rich-14.3.3-py3-none-any.whl", hash = "sha256:793431c1f8619afa7d3b52b2cdec859562b950ea0d4b6b505397612db8d5362d", size = 310458, upload-time = "2026-02-19T17:23:13.732Z" },
+]
+
+[[package]]
+name = "rich-rst"
+version = "1.3.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "docutils" },
+    { name = "rich" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/bc/6d/a506aaa4a9eaa945ed8ab2b7347859f53593864289853c5d6d62b77246e0/rich_rst-1.3.2.tar.gz", hash = "sha256:a1196fdddf1e364b02ec68a05e8ff8f6914fee10fbca2e6b6735f166bb0da8d4", size = 14936, upload-time = "2025-10-14T16:49:45.332Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/13/2f/b4530fbf948867702d0a3f27de4a6aab1d156f406d72852ab902c4d04de9/rich_rst-1.3.2-py3-none-any.whl", hash = "sha256:a99b4907cbe118cf9d18b0b44de272efa61f15117c61e39ebdc431baf5df722a", size = 12567, upload-time = "2025-10-14T16:49:42.953Z" },
+]
+
+[[package]]
+name = "rpds-py"
+version = "0.30.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/20/af/3f2f423103f1113b36230496629986e0ef7e199d2aa8392452b484b38ced/rpds_py-0.30.0.tar.gz", hash = "sha256:dd8ff7cf90014af0c0f787eea34794ebf6415242ee1d6fa91eaba725cc441e84", size = 69469, upload-time = "2025-11-30T20:24:38.837Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/06/0c/0c411a0ec64ccb6d104dcabe0e713e05e153a9a2c3c2bd2b32ce412166fe/rpds_py-0.30.0-cp310-cp310-macosx_10_12_x86_64.whl", hash = "sha256:679ae98e00c0e8d68a7fda324e16b90fd5260945b45d3b824c892cec9eea3288", size = 370490, upload-time = "2025-11-30T20:21:33.256Z" },
+    { url = "https://files.pythonhosted.org/packages/19/6a/4ba3d0fb7297ebae71171822554abe48d7cab29c28b8f9f2c04b79988c05/rpds_py-0.30.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:4cc2206b76b4f576934f0ed374b10d7ca5f457858b157ca52064bdfc26b9fc00", size = 359751, upload-time = "2025-11-30T20:21:34.591Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/7c/e4933565ef7f7a0818985d87c15d9d273f1a649afa6a52ea35ad011195ea/rpds_py-0.30.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:389a2d49eded1896c3d48b0136ead37c48e221b391c052fba3f4055c367f60a6", size = 389696, upload-time = "2025-11-30T20:21:36.122Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/01/6271a2511ad0815f00f7ed4390cf2567bec1d4b1da39e2c27a41e6e3b4de/rpds_py-0.30.0-cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:32c8528634e1bf7121f3de08fa85b138f4e0dc47657866630611b03967f041d7", size = 403136, upload-time = "2025-11-30T20:21:37.728Z" },
+    { url = "https://files.pythonhosted.org/packages/55/64/c857eb7cd7541e9b4eee9d49c196e833128a55b89a9850a9c9ac33ccf897/rpds_py-0.30.0-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:f207f69853edd6f6700b86efb84999651baf3789e78a466431df1331608e5324", size = 524699, upload-time = "2025-11-30T20:21:38.92Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/ed/94816543404078af9ab26159c44f9e98e20fe47e2126d5d32c9d9948d10a/rpds_py-0.30.0-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:67b02ec25ba7a9e8fa74c63b6ca44cf5707f2fbfadae3ee8e7494297d56aa9df", size = 412022, upload-time = "2025-11-30T20:21:40.407Z" },
+    { url = "https://files.pythonhosted.org/packages/61/b5/707f6cf0066a6412aacc11d17920ea2e19e5b2f04081c64526eb35b5c6e7/rpds_py-0.30.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0c0e95f6819a19965ff420f65578bacb0b00f251fefe2c8b23347c37174271f3", size = 390522, upload-time = "2025-11-30T20:21:42.17Z" },
+    { url = "https://files.pythonhosted.org/packages/13/4e/57a85fda37a229ff4226f8cbcf09f2a455d1ed20e802ce5b2b4a7f5ed053/rpds_py-0.30.0-cp310-cp310-manylinux_2_31_riscv64.whl", hash = "sha256:a452763cc5198f2f98898eb98f7569649fe5da666c2dc6b5ddb10fde5a574221", size = 404579, upload-time = "2025-11-30T20:21:43.769Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/da/c9339293513ec680a721e0e16bf2bac3db6e5d7e922488de471308349bba/rpds_py-0.30.0-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:e0b65193a413ccc930671c55153a03ee57cecb49e6227204b04fae512eb657a7", size = 421305, upload-time = "2025-11-30T20:21:44.994Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/be/522cb84751114f4ad9d822ff5a1aa3c98006341895d5f084779b99596e5c/rpds_py-0.30.0-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:858738e9c32147f78b3ac24dc0edb6610000e56dc0f700fd5f651d0a0f0eb9ff", size = 572503, upload-time = "2025-11-30T20:21:46.91Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/9b/de879f7e7ceddc973ea6e4629e9b380213a6938a249e94b0cdbcc325bb66/rpds_py-0.30.0-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:da279aa314f00acbb803da1e76fa18666778e8a8f83484fba94526da5de2cba7", size = 598322, upload-time = "2025-11-30T20:21:48.709Z" },
+    { url = "https://files.pythonhosted.org/packages/48/ac/f01fc22efec3f37d8a914fc1b2fb9bcafd56a299edbe96406f3053edea5a/rpds_py-0.30.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:7c64d38fb49b6cdeda16ab49e35fe0da2e1e9b34bc38bd78386530f218b37139", size = 560792, upload-time = "2025-11-30T20:21:50.024Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/da/4e2b19d0f131f35b6146425f846563d0ce036763e38913d917187307a671/rpds_py-0.30.0-cp310-cp310-win32.whl", hash = "sha256:6de2a32a1665b93233cde140ff8b3467bdb9e2af2b91079f0333a0974d12d464", size = 221901, upload-time = "2025-11-30T20:21:51.32Z" },
+    { url = "https://files.pythonhosted.org/packages/96/cb/156d7a5cf4f78a7cc571465d8aec7a3c447c94f6749c5123f08438bcf7bc/rpds_py-0.30.0-cp310-cp310-win_amd64.whl", hash = "sha256:1726859cd0de969f88dc8673bdd954185b9104e05806be64bcd87badbe313169", size = 235823, upload-time = "2025-11-30T20:21:52.505Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/6e/f964e88b3d2abee2a82c1ac8366da848fce1c6d834dc2132c3fda3970290/rpds_py-0.30.0-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:a2bffea6a4ca9f01b3f8e548302470306689684e61602aa3d141e34da06cf425", size = 370157, upload-time = "2025-11-30T20:21:53.789Z" },
+    { url = "https://files.pythonhosted.org/packages/94/ba/24e5ebb7c1c82e74c4e4f33b2112a5573ddc703915b13a073737b59b86e0/rpds_py-0.30.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:dc4f992dfe1e2bc3ebc7444f6c7051b4bc13cd8e33e43511e8ffd13bf407010d", size = 359676, upload-time = "2025-11-30T20:21:55.475Z" },
+    { url = "https://files.pythonhosted.org/packages/84/86/04dbba1b087227747d64d80c3b74df946b986c57af0a9f0c98726d4d7a3b/rpds_py-0.30.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:422c3cb9856d80b09d30d2eb255d0754b23e090034e1deb4083f8004bd0761e4", size = 389938, upload-time = "2025-11-30T20:21:57.079Z" },
+    { url = "https://files.pythonhosted.org/packages/42/bb/1463f0b1722b7f45431bdd468301991d1328b16cffe0b1c2918eba2c4eee/rpds_py-0.30.0-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:07ae8a593e1c3c6b82ca3292efbe73c30b61332fd612e05abee07c79359f292f", size = 402932, upload-time = "2025-11-30T20:21:58.47Z" },
+    { url = "https://files.pythonhosted.org/packages/99/ee/2520700a5c1f2d76631f948b0736cdf9b0acb25abd0ca8e889b5c62ac2e3/rpds_py-0.30.0-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:12f90dd7557b6bd57f40abe7747e81e0c0b119bef015ea7726e69fe550e394a4", size = 525830, upload-time = "2025-11-30T20:21:59.699Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/ad/bd0331f740f5705cc555a5e17fdf334671262160270962e69a2bdef3bf76/rpds_py-0.30.0-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:99b47d6ad9a6da00bec6aabe5a6279ecd3c06a329d4aa4771034a21e335c3a97", size = 412033, upload-time = "2025-11-30T20:22:00.991Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/1e/372195d326549bb51f0ba0f2ecb9874579906b97e08880e7a65c3bef1a99/rpds_py-0.30.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:33f559f3104504506a44bb666b93a33f5d33133765b0c216a5bf2f1e1503af89", size = 390828, upload-time = "2025-11-30T20:22:02.723Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/2b/d88bb33294e3e0c76bc8f351a3721212713629ffca1700fa94979cb3eae8/rpds_py-0.30.0-cp311-cp311-manylinux_2_31_riscv64.whl", hash = "sha256:946fe926af6e44f3697abbc305ea168c2c31d3e3ef1058cf68f379bf0335a78d", size = 404683, upload-time = "2025-11-30T20:22:04.367Z" },
+    { url = "https://files.pythonhosted.org/packages/50/32/c759a8d42bcb5289c1fac697cd92f6fe01a018dd937e62ae77e0e7f15702/rpds_py-0.30.0-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:495aeca4b93d465efde585977365187149e75383ad2684f81519f504f5c13038", size = 421583, upload-time = "2025-11-30T20:22:05.814Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/81/e729761dbd55ddf5d84ec4ff1f47857f4374b0f19bdabfcf929164da3e24/rpds_py-0.30.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:d9a0ca5da0386dee0655b4ccdf46119df60e0f10da268d04fe7cc87886872ba7", size = 572496, upload-time = "2025-11-30T20:22:07.713Z" },
+    { url = "https://files.pythonhosted.org/packages/14/f6/69066a924c3557c9c30baa6ec3a0aa07526305684c6f86c696b08860726c/rpds_py-0.30.0-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:8d6d1cc13664ec13c1b84241204ff3b12f9bb82464b8ad6e7a5d3486975c2eed", size = 598669, upload-time = "2025-11-30T20:22:09.312Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/48/905896b1eb8a05630d20333d1d8ffd162394127b74ce0b0784ae04498d32/rpds_py-0.30.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:3896fa1be39912cf0757753826bc8bdc8ca331a28a7c4ae46b7a21280b06bb85", size = 561011, upload-time = "2025-11-30T20:22:11.309Z" },
+    { url = "https://files.pythonhosted.org/packages/22/16/cd3027c7e279d22e5eb431dd3c0fbc677bed58797fe7581e148f3f68818b/rpds_py-0.30.0-cp311-cp311-win32.whl", hash = "sha256:55f66022632205940f1827effeff17c4fa7ae1953d2b74a8581baaefb7d16f8c", size = 221406, upload-time = "2025-11-30T20:22:13.101Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/5b/e7b7aa136f28462b344e652ee010d4de26ee9fd16f1bfd5811f5153ccf89/rpds_py-0.30.0-cp311-cp311-win_amd64.whl", hash = "sha256:a51033ff701fca756439d641c0ad09a41d9242fa69121c7d8769604a0a629825", size = 236024, upload-time = "2025-11-30T20:22:14.853Z" },
+    { url = "https://files.pythonhosted.org/packages/14/a6/364bba985e4c13658edb156640608f2c9e1d3ea3c81b27aa9d889fff0e31/rpds_py-0.30.0-cp311-cp311-win_arm64.whl", hash = "sha256:47b0ef6231c58f506ef0b74d44e330405caa8428e770fec25329ed2cb971a229", size = 229069, upload-time = "2025-11-30T20:22:16.577Z" },
+    { url = "https://files.pythonhosted.org/packages/03/e7/98a2f4ac921d82f33e03f3835f5bf3a4a40aa1bfdc57975e74a97b2b4bdd/rpds_py-0.30.0-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:a161f20d9a43006833cd7068375a94d035714d73a172b681d8881820600abfad", size = 375086, upload-time = "2025-11-30T20:22:17.93Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/a1/bca7fd3d452b272e13335db8d6b0b3ecde0f90ad6f16f3328c6fb150c889/rpds_py-0.30.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6abc8880d9d036ecaafe709079969f56e876fcf107f7a8e9920ba6d5a3878d05", size = 359053, upload-time = "2025-11-30T20:22:19.297Z" },
+    { url = "https://files.pythonhosted.org/packages/65/1c/ae157e83a6357eceff62ba7e52113e3ec4834a84cfe07fa4b0757a7d105f/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ca28829ae5f5d569bb62a79512c842a03a12576375d5ece7d2cadf8abe96ec28", size = 390763, upload-time = "2025-11-30T20:22:21.661Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/36/eb2eb8515e2ad24c0bd43c3ee9cd74c33f7ca6430755ccdb240fd3144c44/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:a1010ed9524c73b94d15919ca4d41d8780980e1765babf85f9a2f90d247153dd", size = 408951, upload-time = "2025-11-30T20:22:23.408Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/65/ad8dc1784a331fabbd740ef6f71ce2198c7ed0890dab595adb9ea2d775a1/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:f8d1736cfb49381ba528cd5baa46f82fdc65c06e843dab24dd70b63d09121b3f", size = 514622, upload-time = "2025-11-30T20:22:25.16Z" },
+    { url = "https://files.pythonhosted.org/packages/63/8e/0cfa7ae158e15e143fe03993b5bcd743a59f541f5952e1546b1ac1b5fd45/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:d948b135c4693daff7bc2dcfc4ec57237a29bd37e60c2fabf5aff2bbacf3e2f1", size = 414492, upload-time = "2025-11-30T20:22:26.505Z" },
+    { url = "https://files.pythonhosted.org/packages/60/1b/6f8f29f3f995c7ffdde46a626ddccd7c63aefc0efae881dc13b6e5d5bb16/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:47f236970bccb2233267d89173d3ad2703cd36a0e2a6e92d0560d333871a3d23", size = 394080, upload-time = "2025-11-30T20:22:27.934Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/d5/a266341051a7a3ca2f4b750a3aa4abc986378431fc2da508c5034d081b70/rpds_py-0.30.0-cp312-cp312-manylinux_2_31_riscv64.whl", hash = "sha256:2e6ecb5a5bcacf59c3f912155044479af1d0b6681280048b338b28e364aca1f6", size = 408680, upload-time = "2025-11-30T20:22:29.341Z" },
+    { url = "https://files.pythonhosted.org/packages/10/3b/71b725851df9ab7a7a4e33cf36d241933da66040d195a84781f49c50490c/rpds_py-0.30.0-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:a8fa71a2e078c527c3e9dc9fc5a98c9db40bcc8a92b4e8858e36d329f8684b51", size = 423589, upload-time = "2025-11-30T20:22:31.469Z" },
+    { url = "https://files.pythonhosted.org/packages/00/2b/e59e58c544dc9bd8bd8384ecdb8ea91f6727f0e37a7131baeff8d6f51661/rpds_py-0.30.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:73c67f2db7bc334e518d097c6d1e6fed021bbc9b7d678d6cc433478365d1d5f5", size = 573289, upload-time = "2025-11-30T20:22:32.997Z" },
+    { url = "https://files.pythonhosted.org/packages/da/3e/a18e6f5b460893172a7d6a680e86d3b6bc87a54c1f0b03446a3c8c7b588f/rpds_py-0.30.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:5ba103fb455be00f3b1c2076c9d4264bfcb037c976167a6047ed82f23153f02e", size = 599737, upload-time = "2025-11-30T20:22:34.419Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/e2/714694e4b87b85a18e2c243614974413c60aa107fd815b8cbc42b873d1d7/rpds_py-0.30.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:7cee9c752c0364588353e627da8a7e808a66873672bcb5f52890c33fd965b394", size = 563120, upload-time = "2025-11-30T20:22:35.903Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/ab/d5d5e3bcedb0a77f4f613706b750e50a5a3ba1c15ccd3665ecc636c968fd/rpds_py-0.30.0-cp312-cp312-win32.whl", hash = "sha256:1ab5b83dbcf55acc8b08fc62b796ef672c457b17dbd7820a11d6c52c06839bdf", size = 223782, upload-time = "2025-11-30T20:22:37.271Z" },
+    { url = "https://files.pythonhosted.org/packages/39/3b/f786af9957306fdc38a74cef405b7b93180f481fb48453a114bb6465744a/rpds_py-0.30.0-cp312-cp312-win_amd64.whl", hash = "sha256:a090322ca841abd453d43456ac34db46e8b05fd9b3b4ac0c78bcde8b089f959b", size = 240463, upload-time = "2025-11-30T20:22:39.021Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/d2/b91dc748126c1559042cfe41990deb92c4ee3e2b415f6b5234969ffaf0cc/rpds_py-0.30.0-cp312-cp312-win_arm64.whl", hash = "sha256:669b1805bd639dd2989b281be2cfd951c6121b65e729d9b843e9639ef1fd555e", size = 230868, upload-time = "2025-11-30T20:22:40.493Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/dc/d61221eb88ff410de3c49143407f6f3147acf2538c86f2ab7ce65ae7d5f9/rpds_py-0.30.0-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:f83424d738204d9770830d35290ff3273fbb02b41f919870479fab14b9d303b2", size = 374887, upload-time = "2025-11-30T20:22:41.812Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/32/55fb50ae104061dbc564ef15cc43c013dc4a9f4527a1f4d99baddf56fe5f/rpds_py-0.30.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:e7536cd91353c5273434b4e003cbda89034d67e7710eab8761fd918ec6c69cf8", size = 358904, upload-time = "2025-11-30T20:22:43.479Z" },
+    { url = "https://files.pythonhosted.org/packages/58/70/faed8186300e3b9bdd138d0273109784eea2396c68458ed580f885dfe7ad/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:2771c6c15973347f50fece41fc447c054b7ac2ae0502388ce3b6738cd366e3d4", size = 389945, upload-time = "2025-11-30T20:22:44.819Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/a8/073cac3ed2c6387df38f71296d002ab43496a96b92c823e76f46b8af0543/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:0a59119fc6e3f460315fe9d08149f8102aa322299deaa5cab5b40092345c2136", size = 407783, upload-time = "2025-11-30T20:22:46.103Z" },
+    { url = "https://files.pythonhosted.org/packages/77/57/5999eb8c58671f1c11eba084115e77a8899d6e694d2a18f69f0ba471ec8b/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:76fec018282b4ead0364022e3c54b60bf368b9d926877957a8624b58419169b7", size = 515021, upload-time = "2025-11-30T20:22:47.458Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/af/5ab4833eadc36c0a8ed2bc5c0de0493c04f6c06de223170bd0798ff98ced/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:692bef75a5525db97318e8cd061542b5a79812d711ea03dbc1f6f8dbb0c5f0d2", size = 414589, upload-time = "2025-11-30T20:22:48.872Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/de/f7192e12b21b9e9a68a6d0f249b4af3fdcdff8418be0767a627564afa1f1/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9027da1ce107104c50c81383cae773ef5c24d296dd11c99e2629dbd7967a20c6", size = 394025, upload-time = "2025-11-30T20:22:50.196Z" },
+    { url = "https://files.pythonhosted.org/packages/91/c4/fc70cd0249496493500e7cc2de87504f5aa6509de1e88623431fec76d4b6/rpds_py-0.30.0-cp313-cp313-manylinux_2_31_riscv64.whl", hash = "sha256:9cf69cdda1f5968a30a359aba2f7f9aa648a9ce4b580d6826437f2b291cfc86e", size = 408895, upload-time = "2025-11-30T20:22:51.87Z" },
+    { url = "https://files.pythonhosted.org/packages/58/95/d9275b05ab96556fefff73a385813eb66032e4c99f411d0795372d9abcea/rpds_py-0.30.0-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:a4796a717bf12b9da9d3ad002519a86063dcac8988b030e405704ef7d74d2d9d", size = 422799, upload-time = "2025-11-30T20:22:53.341Z" },
+    { url = "https://files.pythonhosted.org/packages/06/c1/3088fc04b6624eb12a57eb814f0d4997a44b0d208d6cace713033ff1a6ba/rpds_py-0.30.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:5d4c2aa7c50ad4728a094ebd5eb46c452e9cb7edbfdb18f9e1221f597a73e1e7", size = 572731, upload-time = "2025-11-30T20:22:54.778Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/42/c612a833183b39774e8ac8fecae81263a68b9583ee343db33ab571a7ce55/rpds_py-0.30.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:ba81a9203d07805435eb06f536d95a266c21e5b2dfbf6517748ca40c98d19e31", size = 599027, upload-time = "2025-11-30T20:22:56.212Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/60/525a50f45b01d70005403ae0e25f43c0384369ad24ffe46e8d9068b50086/rpds_py-0.30.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:945dccface01af02675628334f7cf49c2af4c1c904748efc5cf7bbdf0b579f95", size = 563020, upload-time = "2025-11-30T20:22:58.2Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/5d/47c4655e9bcd5ca907148535c10e7d489044243cc9941c16ed7cd53be91d/rpds_py-0.30.0-cp313-cp313-win32.whl", hash = "sha256:b40fb160a2db369a194cb27943582b38f79fc4887291417685f3ad693c5a1d5d", size = 223139, upload-time = "2025-11-30T20:23:00.209Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/e1/485132437d20aa4d3e1d8b3fb5a5e65aa8139f1e097080c2a8443201742c/rpds_py-0.30.0-cp313-cp313-win_amd64.whl", hash = "sha256:806f36b1b605e2d6a72716f321f20036b9489d29c51c91f4dd29a3e3afb73b15", size = 240224, upload-time = "2025-11-30T20:23:02.008Z" },
+    { url = "https://files.pythonhosted.org/packages/24/95/ffd128ed1146a153d928617b0ef673960130be0009c77d8fbf0abe306713/rpds_py-0.30.0-cp313-cp313-win_arm64.whl", hash = "sha256:d96c2086587c7c30d44f31f42eae4eac89b60dabbac18c7669be3700f13c3ce1", size = 230645, upload-time = "2025-11-30T20:23:03.43Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/1b/b10de890a0def2a319a2626334a7f0ae388215eb60914dbac8a3bae54435/rpds_py-0.30.0-cp313-cp313t-macosx_10_12_x86_64.whl", hash = "sha256:eb0b93f2e5c2189ee831ee43f156ed34e2a89a78a66b98cadad955972548be5a", size = 364443, upload-time = "2025-11-30T20:23:04.878Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/bf/27e39f5971dc4f305a4fb9c672ca06f290f7c4e261c568f3dea16a410d47/rpds_py-0.30.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:922e10f31f303c7c920da8981051ff6d8c1a56207dbdf330d9047f6d30b70e5e", size = 353375, upload-time = "2025-11-30T20:23:06.342Z" },
+    { url = "https://files.pythonhosted.org/packages/40/58/442ada3bba6e8e6615fc00483135c14a7538d2ffac30e2d933ccf6852232/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:cdc62c8286ba9bf7f47befdcea13ea0e26bf294bda99758fd90535cbaf408000", size = 383850, upload-time = "2025-11-30T20:23:07.825Z" },
+    { url = "https://files.pythonhosted.org/packages/14/14/f59b0127409a33c6ef6f5c1ebd5ad8e32d7861c9c7adfa9a624fc3889f6c/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:47f9a91efc418b54fb8190a6b4aa7813a23fb79c51f4bb84e418f5476c38b8db", size = 392812, upload-time = "2025-11-30T20:23:09.228Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/66/e0be3e162ac299b3a22527e8913767d869e6cc75c46bd844aa43fb81ab62/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:1f3587eb9b17f3789ad50824084fa6f81921bbf9a795826570bda82cb3ed91f2", size = 517841, upload-time = "2025-11-30T20:23:11.186Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/55/fa3b9cf31d0c963ecf1ba777f7cf4b2a2c976795ac430d24a1f43d25a6ba/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:39c02563fc592411c2c61d26b6c5fe1e51eaa44a75aa2c8735ca88b0d9599daa", size = 408149, upload-time = "2025-11-30T20:23:12.864Z" },
+    { url = "https://files.pythonhosted.org/packages/60/ca/780cf3b1a32b18c0f05c441958d3758f02544f1d613abf9488cd78876378/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:51a1234d8febafdfd33a42d97da7a43f5dcb120c1060e352a3fbc0c6d36e2083", size = 383843, upload-time = "2025-11-30T20:23:14.638Z" },
+    { url = "https://files.pythonhosted.org/packages/82/86/d5f2e04f2aa6247c613da0c1dd87fcd08fa17107e858193566048a1e2f0a/rpds_py-0.30.0-cp313-cp313t-manylinux_2_31_riscv64.whl", hash = "sha256:eb2c4071ab598733724c08221091e8d80e89064cd472819285a9ab0f24bcedb9", size = 396507, upload-time = "2025-11-30T20:23:16.105Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/9a/453255d2f769fe44e07ea9785c8347edaf867f7026872e76c1ad9f7bed92/rpds_py-0.30.0-cp313-cp313t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:6bdfdb946967d816e6adf9a3d8201bfad269c67efe6cefd7093ef959683c8de0", size = 414949, upload-time = "2025-11-30T20:23:17.539Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/31/622a86cdc0c45d6df0e9ccb6becdba5074735e7033c20e401a6d9d0e2ca0/rpds_py-0.30.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:c77afbd5f5250bf27bf516c7c4a016813eb2d3e116139aed0096940c5982da94", size = 565790, upload-time = "2025-11-30T20:23:19.029Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/5d/15bbf0fb4a3f58a3b1c67855ec1efcc4ceaef4e86644665fff03e1b66d8d/rpds_py-0.30.0-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:61046904275472a76c8c90c9ccee9013d70a6d0f73eecefd38c1ae7c39045a08", size = 590217, upload-time = "2025-11-30T20:23:20.885Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/61/21b8c41f68e60c8cc3b2e25644f0e3681926020f11d06ab0b78e3c6bbff1/rpds_py-0.30.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:4c5f36a861bc4b7da6516dbdf302c55313afa09b81931e8280361a4f6c9a2d27", size = 555806, upload-time = "2025-11-30T20:23:22.488Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/39/7e067bb06c31de48de3eb200f9fc7c58982a4d3db44b07e73963e10d3be9/rpds_py-0.30.0-cp313-cp313t-win32.whl", hash = "sha256:3d4a69de7a3e50ffc214ae16d79d8fbb0922972da0356dcf4d0fdca2878559c6", size = 211341, upload-time = "2025-11-30T20:23:24.449Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/4d/222ef0b46443cf4cf46764d9c630f3fe4abaa7245be9417e56e9f52b8f65/rpds_py-0.30.0-cp313-cp313t-win_amd64.whl", hash = "sha256:f14fc5df50a716f7ece6a80b6c78bb35ea2ca47c499e422aa4463455dd96d56d", size = 225768, upload-time = "2025-11-30T20:23:25.908Z" },
+    { url = "https://files.pythonhosted.org/packages/86/81/dad16382ebbd3d0e0328776d8fd7ca94220e4fa0798d1dc5e7da48cb3201/rpds_py-0.30.0-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:68f19c879420aa08f61203801423f6cd5ac5f0ac4ac82a2368a9fcd6a9a075e0", size = 362099, upload-time = "2025-11-30T20:23:27.316Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/60/19f7884db5d5603edf3c6bce35408f45ad3e97e10007df0e17dd57af18f8/rpds_py-0.30.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:ec7c4490c672c1a0389d319b3a9cfcd098dcdc4783991553c332a15acf7249be", size = 353192, upload-time = "2025-11-30T20:23:29.151Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/c4/76eb0e1e72d1a9c4703c69607cec123c29028bff28ce41588792417098ac/rpds_py-0.30.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f251c812357a3fed308d684a5079ddfb9d933860fc6de89f2b7ab00da481e65f", size = 384080, upload-time = "2025-11-30T20:23:30.785Z" },
+    { url = "https://files.pythonhosted.org/packages/72/87/87ea665e92f3298d1b26d78814721dc39ed8d2c74b86e83348d6b48a6f31/rpds_py-0.30.0-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:ac98b175585ecf4c0348fd7b29c3864bda53b805c773cbf7bfdaffc8070c976f", size = 394841, upload-time = "2025-11-30T20:23:32.209Z" },
+    { url = "https://files.pythonhosted.org/packages/77/ad/7783a89ca0587c15dcbf139b4a8364a872a25f861bdb88ed99f9b0dec985/rpds_py-0.30.0-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:3e62880792319dbeb7eb866547f2e35973289e7d5696c6e295476448f5b63c87", size = 516670, upload-time = "2025-11-30T20:23:33.742Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/3c/2882bdac942bd2172f3da574eab16f309ae10a3925644e969536553cb4ee/rpds_py-0.30.0-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:4e7fc54e0900ab35d041b0601431b0a0eb495f0851a0639b6ef90f7741b39a18", size = 408005, upload-time = "2025-11-30T20:23:35.253Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/81/9a91c0111ce1758c92516a3e44776920b579d9a7c09b2b06b642d4de3f0f/rpds_py-0.30.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:47e77dc9822d3ad616c3d5759ea5631a75e5809d5a28707744ef79d7a1bcfcad", size = 382112, upload-time = "2025-11-30T20:23:36.842Z" },
+    { url = "https://files.pythonhosted.org/packages/cf/8e/1da49d4a107027e5fbc64daeab96a0706361a2918da10cb41769244b805d/rpds_py-0.30.0-cp314-cp314-manylinux_2_31_riscv64.whl", hash = "sha256:b4dc1a6ff022ff85ecafef7979a2c6eb423430e05f1165d6688234e62ba99a07", size = 399049, upload-time = "2025-11-30T20:23:38.343Z" },
+    { url = "https://files.pythonhosted.org/packages/df/5a/7ee239b1aa48a127570ec03becbb29c9d5a9eb092febbd1699d567cae859/rpds_py-0.30.0-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:4559c972db3a360808309e06a74628b95eaccbf961c335c8fe0d590cf587456f", size = 415661, upload-time = "2025-11-30T20:23:40.263Z" },
+    { url = "https://files.pythonhosted.org/packages/70/ea/caa143cf6b772f823bc7929a45da1fa83569ee49b11d18d0ada7f5ee6fd6/rpds_py-0.30.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:0ed177ed9bded28f8deb6ab40c183cd1192aa0de40c12f38be4d59cd33cb5c65", size = 565606, upload-time = "2025-11-30T20:23:42.186Z" },
+    { url = "https://files.pythonhosted.org/packages/64/91/ac20ba2d69303f961ad8cf55bf7dbdb4763f627291ba3d0d7d67333cced9/rpds_py-0.30.0-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:ad1fa8db769b76ea911cb4e10f049d80bf518c104f15b3edb2371cc65375c46f", size = 591126, upload-time = "2025-11-30T20:23:44.086Z" },
+    { url = "https://files.pythonhosted.org/packages/21/20/7ff5f3c8b00c8a95f75985128c26ba44503fb35b8e0259d812766ea966c7/rpds_py-0.30.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:46e83c697b1f1c72b50e5ee5adb4353eef7406fb3f2043d64c33f20ad1c2fc53", size = 553371, upload-time = "2025-11-30T20:23:46.004Z" },
+    { url = "https://files.pythonhosted.org/packages/72/c7/81dadd7b27c8ee391c132a6b192111ca58d866577ce2d9b0ca157552cce0/rpds_py-0.30.0-cp314-cp314-win32.whl", hash = "sha256:ee454b2a007d57363c2dfd5b6ca4a5d7e2c518938f8ed3b706e37e5d470801ed", size = 215298, upload-time = "2025-11-30T20:23:47.696Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/d2/1aaac33287e8cfb07aab2e6b8ac1deca62f6f65411344f1433c55e6f3eb8/rpds_py-0.30.0-cp314-cp314-win_amd64.whl", hash = "sha256:95f0802447ac2d10bcc69f6dc28fe95fdf17940367b21d34e34c737870758950", size = 228604, upload-time = "2025-11-30T20:23:49.501Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/95/ab005315818cc519ad074cb7784dae60d939163108bd2b394e60dc7b5461/rpds_py-0.30.0-cp314-cp314-win_arm64.whl", hash = "sha256:613aa4771c99f03346e54c3f038e4cc574ac09a3ddfb0e8878487335e96dead6", size = 222391, upload-time = "2025-11-30T20:23:50.96Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/68/154fe0194d83b973cdedcdcc88947a2752411165930182ae41d983dcefa6/rpds_py-0.30.0-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:7e6ecfcb62edfd632e56983964e6884851786443739dbfe3582947e87274f7cb", size = 364868, upload-time = "2025-11-30T20:23:52.494Z" },
+    { url = "https://files.pythonhosted.org/packages/83/69/8bbc8b07ec854d92a8b75668c24d2abcb1719ebf890f5604c61c9369a16f/rpds_py-0.30.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:a1d0bc22a7cdc173fedebb73ef81e07faef93692b8c1ad3733b67e31e1b6e1b8", size = 353747, upload-time = "2025-11-30T20:23:54.036Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/00/ba2e50183dbd9abcce9497fa5149c62b4ff3e22d338a30d690f9af970561/rpds_py-0.30.0-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0d08f00679177226c4cb8c5265012eea897c8ca3b93f429e546600c971bcbae7", size = 383795, upload-time = "2025-11-30T20:23:55.556Z" },
+    { url = "https://files.pythonhosted.org/packages/05/6f/86f0272b84926bcb0e4c972262f54223e8ecc556b3224d281e6598fc9268/rpds_py-0.30.0-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:5965af57d5848192c13534f90f9dd16464f3c37aaf166cc1da1cae1fd5a34898", size = 393330, upload-time = "2025-11-30T20:23:57.033Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/e9/0e02bb2e6dc63d212641da45df2b0bf29699d01715913e0d0f017ee29438/rpds_py-0.30.0-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9a4e86e34e9ab6b667c27f3211ca48f73dba7cd3d90f8d5b11be56e5dbc3fb4e", size = 518194, upload-time = "2025-11-30T20:23:58.637Z" },
+    { url = "https://files.pythonhosted.org/packages/ee/ca/be7bca14cf21513bdf9c0606aba17d1f389ea2b6987035eb4f62bd923f25/rpds_py-0.30.0-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:e5d3e6b26f2c785d65cc25ef1e5267ccbe1b069c5c21b8cc724efee290554419", size = 408340, upload-time = "2025-11-30T20:24:00.2Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/c7/736e00ebf39ed81d75544c0da6ef7b0998f8201b369acf842f9a90dc8fce/rpds_py-0.30.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:626a7433c34566535b6e56a1b39a7b17ba961e97ce3b80ec62e6f1312c025551", size = 383765, upload-time = "2025-11-30T20:24:01.759Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/3f/da50dfde9956aaf365c4adc9533b100008ed31aea635f2b8d7b627e25b49/rpds_py-0.30.0-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:acd7eb3f4471577b9b5a41baf02a978e8bdeb08b4b355273994f8b87032000a8", size = 396834, upload-time = "2025-11-30T20:24:03.687Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/00/34bcc2565b6020eab2623349efbdec810676ad571995911f1abdae62a3a0/rpds_py-0.30.0-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:fe5fa731a1fa8a0a56b0977413f8cacac1768dad38d16b3a296712709476fbd5", size = 415470, upload-time = "2025-11-30T20:24:05.232Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/28/882e72b5b3e6f718d5453bd4d0d9cf8df36fddeb4ddbbab17869d5868616/rpds_py-0.30.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:74a3243a411126362712ee1524dfc90c650a503502f135d54d1b352bd01f2404", size = 565630, upload-time = "2025-11-30T20:24:06.878Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/97/04a65539c17692de5b85c6e293520fd01317fd878ea1995f0367d4532fb1/rpds_py-0.30.0-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:3e8eeb0544f2eb0d2581774be4c3410356eba189529a6b3e36bbbf9696175856", size = 591148, upload-time = "2025-11-30T20:24:08.445Z" },
+    { url = "https://files.pythonhosted.org/packages/85/70/92482ccffb96f5441aab93e26c4d66489eb599efdcf96fad90c14bbfb976/rpds_py-0.30.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:dbd936cde57abfee19ab3213cf9c26be06d60750e60a8e4dd85d1ab12c8b1f40", size = 556030, upload-time = "2025-11-30T20:24:10.956Z" },
+    { url = "https://files.pythonhosted.org/packages/20/53/7c7e784abfa500a2b6b583b147ee4bb5a2b3747a9166bab52fec4b5b5e7d/rpds_py-0.30.0-cp314-cp314t-win32.whl", hash = "sha256:dc824125c72246d924f7f796b4f63c1e9dc810c7d9e2355864b3c3a73d59ade0", size = 211570, upload-time = "2025-11-30T20:24:12.735Z" },
+    { url = "https://files.pythonhosted.org/packages/d0/02/fa464cdfbe6b26e0600b62c528b72d8608f5cc49f96b8d6e38c95d60c676/rpds_py-0.30.0-cp314-cp314t-win_amd64.whl", hash = "sha256:27f4b0e92de5bfbc6f86e43959e6edd1425c33b5e69aab0984a72047f2bcf1e3", size = 226532, upload-time = "2025-11-30T20:24:14.634Z" },
+    { url = "https://files.pythonhosted.org/packages/69/71/3f34339ee70521864411f8b6992e7ab13ac30d8e4e3309e07c7361767d91/rpds_py-0.30.0-pp311-pypy311_pp73-macosx_10_12_x86_64.whl", hash = "sha256:c2262bdba0ad4fc6fb5545660673925c2d2a5d9e2e0fb603aad545427be0fc58", size = 372292, upload-time = "2025-11-30T20:24:16.537Z" },
+    { url = "https://files.pythonhosted.org/packages/57/09/f183df9b8f2d66720d2ef71075c59f7e1b336bec7ee4c48f0a2b06857653/rpds_py-0.30.0-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:ee6af14263f25eedc3bb918a3c04245106a42dfd4f5c2285ea6f997b1fc3f89a", size = 362128, upload-time = "2025-11-30T20:24:18.086Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/68/5c2594e937253457342e078f0cc1ded3dd7b2ad59afdbf2d354869110a02/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3adbb8179ce342d235c31ab8ec511e66c73faa27a47e076ccc92421add53e2bb", size = 391542, upload-time = "2025-11-30T20:24:20.092Z" },
+    { url = "https://files.pythonhosted.org/packages/49/5c/31ef1afd70b4b4fbdb2800249f34c57c64beb687495b10aec0365f53dfc4/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:250fa00e9543ac9b97ac258bd37367ff5256666122c2d0f2bc97577c60a1818c", size = 404004, upload-time = "2025-11-30T20:24:22.231Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/63/0cfbea38d05756f3440ce6534d51a491d26176ac045e2707adc99bb6e60a/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9854cf4f488b3d57b9aaeb105f06d78e5529d3145b1e4a41750167e8c213c6d3", size = 527063, upload-time = "2025-11-30T20:24:24.302Z" },
+    { url = "https://files.pythonhosted.org/packages/42/e6/01e1f72a2456678b0f618fc9a1a13f882061690893c192fcad9f2926553a/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:993914b8e560023bc0a8bf742c5f303551992dcb85e247b1e5c7f4a7d145bda5", size = 413099, upload-time = "2025-11-30T20:24:25.916Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/25/8df56677f209003dcbb180765520c544525e3ef21ea72279c98b9aa7c7fb/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:58edca431fb9b29950807e301826586e5bbf24163677732429770a697ffe6738", size = 392177, upload-time = "2025-11-30T20:24:27.834Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/b4/0a771378c5f16f8115f796d1f437950158679bcd2a7c68cf251cfb00ed5b/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_31_riscv64.whl", hash = "sha256:dea5b552272a944763b34394d04577cf0f9bd013207bc32323b5a89a53cf9c2f", size = 406015, upload-time = "2025-11-30T20:24:29.457Z" },
+    { url = "https://files.pythonhosted.org/packages/36/d8/456dbba0af75049dc6f63ff295a2f92766b9d521fa00de67a2bd6427d57a/rpds_py-0.30.0-pp311-pypy311_pp73-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:ba3af48635eb83d03f6c9735dfb21785303e73d22ad03d489e88adae6eab8877", size = 423736, upload-time = "2025-11-30T20:24:31.22Z" },
+    { url = "https://files.pythonhosted.org/packages/13/64/b4d76f227d5c45a7e0b796c674fd81b0a6c4fbd48dc29271857d8219571c/rpds_py-0.30.0-pp311-pypy311_pp73-musllinux_1_2_aarch64.whl", hash = "sha256:dff13836529b921e22f15cb099751209a60009731a68519630a24d61f0b1b30a", size = 573981, upload-time = "2025-11-30T20:24:32.934Z" },
+    { url = "https://files.pythonhosted.org/packages/20/91/092bacadeda3edf92bf743cc96a7be133e13a39cdbfd7b5082e7ab638406/rpds_py-0.30.0-pp311-pypy311_pp73-musllinux_1_2_i686.whl", hash = "sha256:1b151685b23929ab7beec71080a8889d4d6d9fa9a983d213f07121205d48e2c4", size = 599782, upload-time = "2025-11-30T20:24:35.169Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/b7/b95708304cd49b7b6f82fdd039f1748b66ec2b21d6a45180910802f1abf1/rpds_py-0.30.0-pp311-pypy311_pp73-musllinux_1_2_x86_64.whl", hash = "sha256:ac37f9f516c51e5753f27dfdef11a88330f04de2d564be3991384b2f3535d02e", size = 562191, upload-time = "2025-11-30T20:24:36.853Z" },
+]
+
+[[package]]
+name = "ruff"
+version = "0.15.8"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/14/b0/73cf7550861e2b4824950b8b52eebdcc5adc792a00c514406556c5b80817/ruff-0.15.8.tar.gz", hash = "sha256:995f11f63597ee362130d1d5a327a87cb6f3f5eae3094c620bcc632329a4d26e", size = 4610921, upload-time = "2026-03-26T18:39:38.675Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/4a/92/c445b0cd6da6e7ae51e954939cb69f97e008dbe750cfca89b8cedc081be7/ruff-0.15.8-py3-none-linux_armv6l.whl", hash = "sha256:cbe05adeba76d58162762d6b239c9056f1a15a55bd4b346cfd21e26cd6ad7bc7", size = 10527394, upload-time = "2026-03-26T18:39:41.566Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/92/f1c662784d149ad1414cae450b082cf736430c12ca78367f20f5ed569d65/ruff-0.15.8-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:d3e3d0b6ba8dca1b7ef9ab80a28e840a20070c4b62e56d675c24f366ef330570", size = 10905693, upload-time = "2026-03-26T18:39:30.364Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/f2/7a631a8af6d88bcef997eb1bf87cc3da158294c57044aafd3e17030613de/ruff-0.15.8-py3-none-macosx_11_0_arm64.whl", hash = "sha256:6ee3ae5c65a42f273f126686353f2e08ff29927b7b7e203b711514370d500de3", size = 10323044, upload-time = "2026-03-26T18:39:33.37Z" },
+    { url = "https://files.pythonhosted.org/packages/67/18/1bf38e20914a05e72ef3b9569b1d5c70a7ef26cd188d69e9ca8ef588d5bf/ruff-0.15.8-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:fdce027ada77baa448077ccc6ebb2fa9c3c62fd110d8659d601cf2f475858d94", size = 10629135, upload-time = "2026-03-26T18:39:44.142Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/e9/138c150ff9af60556121623d41aba18b7b57d95ac032e177b6a53789d279/ruff-0.15.8-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:12e617fc01a95e5821648a6df341d80456bd627bfab8a829f7cfc26a14a4b4a3", size = 10348041, upload-time = "2026-03-26T18:39:52.178Z" },
+    { url = "https://files.pythonhosted.org/packages/02/f1/5bfb9298d9c323f842c5ddeb85f1f10ef51516ac7a34ba446c9347d898df/ruff-0.15.8-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:432701303b26416d22ba696c39f2c6f12499b89093b61360abc34bcc9bf07762", size = 11121987, upload-time = "2026-03-26T18:39:55.195Z" },
+    { url = "https://files.pythonhosted.org/packages/10/11/6da2e538704e753c04e8d86b1fc55712fdbdcc266af1a1ece7a51fff0d10/ruff-0.15.8-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:d910ae974b7a06a33a057cb87d2a10792a3b2b3b35e33d2699fdf63ec8f6b17a", size = 11951057, upload-time = "2026-03-26T18:39:19.18Z" },
+    { url = "https://files.pythonhosted.org/packages/83/f0/c9208c5fd5101bf87002fed774ff25a96eea313d305f1e5d5744698dc314/ruff-0.15.8-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:2033f963c43949d51e6fdccd3946633c6b37c484f5f98c3035f49c27395a8ab8", size = 11464613, upload-time = "2026-03-26T18:40:06.301Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/22/d7f2fabdba4fae9f3b570e5605d5eb4500dcb7b770d3217dca4428484b17/ruff-0.15.8-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0f29b989a55572fb885b77464cf24af05500806ab4edf9a0fd8977f9759d85b1", size = 11257557, upload-time = "2026-03-26T18:39:57.972Z" },
+    { url = "https://files.pythonhosted.org/packages/71/8c/382a9620038cf6906446b23ce8632ab8c0811b8f9d3e764f58bedd0c9a6f/ruff-0.15.8-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:ac51d486bf457cdc985a412fb1801b2dfd1bd8838372fc55de64b1510eff4bec", size = 11169440, upload-time = "2026-03-26T18:39:22.205Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/0d/0994c802a7eaaf99380085e4e40c845f8e32a562e20a38ec06174b52ef24/ruff-0.15.8-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:c9861eb959edab053c10ad62c278835ee69ca527b6dcd72b47d5c1e5648964f6", size = 10605963, upload-time = "2026-03-26T18:39:46.682Z" },
+    { url = "https://files.pythonhosted.org/packages/19/aa/d624b86f5b0aad7cef6bbf9cd47a6a02dfdc4f72c92a337d724e39c9d14b/ruff-0.15.8-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:8d9a5b8ea13f26ae90838afc33f91b547e61b794865374f114f349e9036835fb", size = 10357484, upload-time = "2026-03-26T18:39:49.176Z" },
+    { url = "https://files.pythonhosted.org/packages/35/c3/e0b7835d23001f7d999f3895c6b569927c4d39912286897f625736e1fd04/ruff-0.15.8-py3-none-musllinux_1_2_i686.whl", hash = "sha256:c2a33a529fb3cbc23a7124b5c6ff121e4d6228029cba374777bd7649cc8598b8", size = 10830426, upload-time = "2026-03-26T18:40:03.702Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/51/ab20b322f637b369383adc341d761eaaa0f0203d6b9a7421cd6e783d81b9/ruff-0.15.8-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:75e5cd06b1cf3f47a3996cfc999226b19aa92e7cce682dcd62f80d7035f98f49", size = 11345125, upload-time = "2026-03-26T18:39:27.799Z" },
+    { url = "https://files.pythonhosted.org/packages/37/e6/90b2b33419f59d0f2c4c8a48a4b74b460709a557e8e0064cf33ad894f983/ruff-0.15.8-py3-none-win32.whl", hash = "sha256:bc1f0a51254ba21767bfa9a8b5013ca8149dcf38092e6a9eb704d876de94dc34", size = 10571959, upload-time = "2026-03-26T18:39:36.117Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/a2/ef467cb77099062317154c63f234b8a7baf7cb690b99af760c5b68b9ee7f/ruff-0.15.8-py3-none-win_amd64.whl", hash = "sha256:04f79eff02a72db209d47d665ba7ebcad609d8918a134f86cb13dd132159fc89", size = 11743893, upload-time = "2026-03-26T18:39:25.01Z" },
+    { url = "https://files.pythonhosted.org/packages/15/e2/77be4fff062fa78d9b2a4dea85d14785dac5f1d0c1fb58ed52331f0ebe28/ruff-0.15.8-py3-none-win_arm64.whl", hash = "sha256:cf891fa8e3bb430c0e7fac93851a5978fc99c8fa2c053b57b118972866f8e5f2", size = 11048175, upload-time = "2026-03-26T18:40:01.06Z" },
+]
+
+[[package]]
+name = "secretstorage"
+version = "3.5.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cryptography" },
+    { name = "jeepney" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/1c/03/e834bcd866f2f8a49a85eaff47340affa3bfa391ee9912a952a1faa68c7b/secretstorage-3.5.0.tar.gz", hash = "sha256:f04b8e4689cbce351744d5537bf6b1329c6fc68f91fa666f60a380edddcd11be", size = 19884, upload-time = "2025-11-23T19:02:53.191Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b7/46/f5af3402b579fd5e11573ce652019a67074317e18c1935cc0b4ba9b35552/secretstorage-3.5.0-py3-none-any.whl", hash = "sha256:0ce65888c0725fcb2c5bc0fdb8e5438eece02c523557ea40ce0703c266248137", size = 15554, upload-time = "2025-11-23T19:02:51.545Z" },
+]
+
+[[package]]
+name = "shellingham"
+version = "1.5.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/58/15/8b3609fd3830ef7b27b655beb4b4e9c62313a4e8da8c676e142cc210d58e/shellingham-1.5.4.tar.gz", hash = "sha256:8dbca0739d487e5bd35ab3ca4b36e11c4078f3a234bfce294b0a0291363404de", size = 10310, upload-time = "2023-10-24T04:13:40.426Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e0/f9/0595336914c5619e5f28a1fb793285925a8cd4b432c9da0a987836c7f822/shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686", size = 9755, upload-time = "2023-10-24T04:13:38.866Z" },
+]
+
+[[package]]
+name = "sniffio"
+version = "1.3.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a2/87/a6771e1546d97e7e041b6ae58d80074f81b7d5121207425c964ddf5cfdbd/sniffio-1.3.1.tar.gz", hash = "sha256:f4324edc670a0f49750a81b895f35c3adb843cca46f0530f79fc1babb23789dc", size = 20372, upload-time = "2024-02-25T23:20:04.057Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e9/44/75a9c9421471a6c4805dbf2356f7c181a29c1879239abab1ea2cc8f38b40/sniffio-1.3.1-py3-none-any.whl", hash = "sha256:2f6da418d1f1e0fddd844478f41680e794e6051915791a034ff65e5f100525a2", size = 10235, upload-time = "2024-02-25T23:20:01.196Z" },
+]
+
+[[package]]
+name = "sse-starlette"
+version = "3.3.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "starlette" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/26/8c/f9290339ef6d79badbc010f067cd769d6601ec11a57d78569c683fb4dd87/sse_starlette-3.3.4.tar.gz", hash = "sha256:aaf92fc067af8a5427192895ac028e947b484ac01edbc3caf00e7e7137c7bef1", size = 32427, upload-time = "2026-03-29T09:00:23.307Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f8/7f/3de5402f39890ac5660b86bcf5c03f9d855dad5c4ed764866d7b592b46fd/sse_starlette-3.3.4-py3-none-any.whl", hash = "sha256:84bb06e58939a8b38d8341f1bc9792f06c2b53f48c608dd207582b664fc8f3c1", size = 14330, upload-time = "2026-03-29T09:00:21.846Z" },
+]
+
+[[package]]
+name = "stack-data"
+version = "0.6.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "asttokens" },
+    { name = "executing" },
+    { name = "pure-eval" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/28/e3/55dcc2cfbc3ca9c29519eb6884dd1415ecb53b0e934862d3559ddcb7e20b/stack_data-0.6.3.tar.gz", hash = "sha256:836a778de4fec4dcd1dcd89ed8abff8a221f58308462e1c4aa2a3cf30148f0b9", size = 44707, upload-time = "2023-09-30T13:58:05.479Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f1/7b/ce1eafaf1a76852e2ec9b22edecf1daa58175c090266e9f6c64afcd81d91/stack_data-0.6.3-py3-none-any.whl", hash = "sha256:d5558e0c25a4cb0853cddad3d77da9891a08cb85dd9f9f91b9f8cd66e511e695", size = 24521, upload-time = "2023-09-30T13:58:03.53Z" },
+]
+
+[[package]]
+name = "starlette"
+version = "1.3.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/eb/e3/7c1dc7381d9f8ab7d854328ebfa884e62cb3f3d8549ddfd37c7814f42afa/starlette-1.3.1.tar.gz", hash = "sha256:05d0213193f2fbaae60e2ecb593b4add4262ad4e46536b54abe36f11a71724e0", size = 2703240, upload-time = "2026-06-12T09:23:11.602Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ec/bb/2799cc2ede3ed41131f8975621e7213dfc7ef4acbbaadfa440f32500c370/starlette-1.3.1-py3-none-any.whl", hash = "sha256:c7372aae11c3c3f26a42df7bd626cec2f47d03483d261d369516a615a53714c6", size = 73632, upload-time = "2026-06-12T09:23:10.017Z" },
+]
+
+[[package]]
+name = "taskgroup"
+version = "0.2.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "exceptiongroup", marker = "python_full_version < '3.11'" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f0/8d/e218e0160cc1b692e6e0e5ba34e8865dbb171efeb5fc9a704544b3020605/taskgroup-0.2.2.tar.gz", hash = "sha256:078483ac3e78f2e3f973e2edbf6941374fbea81b9c5d0a96f51d297717f4752d", size = 11504, upload-time = "2025-01-03T09:24:13.761Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d1/b1/74babcc824a57904e919f3af16d86c08b524c0691504baf038ef2d7f655c/taskgroup-0.2.2-py2.py3-none-any.whl", hash = "sha256:e2c53121609f4ae97303e9ea1524304b4de6faf9eb2c9280c7f87976479a52fb", size = 14237, upload-time = "2025-01-03T09:24:11.41Z" },
+]
+
+[[package]]
+name = "tenacity"
+version = "9.1.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/47/c6/ee486fd809e357697ee8a44d3d69222b344920433d3b6666ccd9b374630c/tenacity-9.1.4.tar.gz", hash = "sha256:adb31d4c263f2bd041081ab33b498309a57c77f9acf2db65aadf0898179cf93a", size = 49413, upload-time = "2026-02-07T10:45:33.841Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d7/c1/eb8f9debc45d3b7918a32ab756658a0904732f75e555402972246b0b8e71/tenacity-9.1.4-py3-none-any.whl", hash = "sha256:6095a360c919085f28c6527de529e76a06ad89b23659fa881ae0649b867a9d55", size = 28926, upload-time = "2026-02-07T10:45:32.24Z" },
+]
+
+[[package]]
+name = "tomli"
+version = "2.4.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/22/de/48c59722572767841493b26183a0d1cc411d54fd759c5607c4590b6563a6/tomli-2.4.1.tar.gz", hash = "sha256:7c7e1a961a0b2f2472c1ac5b69affa0ae1132c39adcb67aba98568702b9cc23f", size = 17543, upload-time = "2026-03-25T20:22:03.828Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f4/11/db3d5885d8528263d8adc260bb2d28ebf1270b96e98f0e0268d32b8d9900/tomli-2.4.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:f8f0fc26ec2cc2b965b7a3b87cd19c5c6b8c5e5f436b984e85f486d652285c30", size = 154704, upload-time = "2026-03-25T20:21:10.473Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/f7/675db52c7e46064a9aa928885a9b20f4124ecb9bc2e1ce74c9106648d202/tomli-2.4.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:4ab97e64ccda8756376892c53a72bd1f964e519c77236368527f758fbc36a53a", size = 149454, upload-time = "2026-03-25T20:21:12.036Z" },
+    { url = "https://files.pythonhosted.org/packages/61/71/81c50943cf953efa35bce7646caab3cf457a7d8c030b27cfb40d7235f9ee/tomli-2.4.1-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:96481a5786729fd470164b47cdb3e0e58062a496f455ee41b4403be77cb5a076", size = 237561, upload-time = "2026-03-25T20:21:13.098Z" },
+    { url = "https://files.pythonhosted.org/packages/48/c1/f41d9cb618acccca7df82aaf682f9b49013c9397212cb9f53219e3abac37/tomli-2.4.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5a881ab208c0baf688221f8cecc5401bd291d67e38a1ac884d6736cbcd8247e9", size = 243824, upload-time = "2026-03-25T20:21:14.569Z" },
+    { url = "https://files.pythonhosted.org/packages/22/e4/5a816ecdd1f8ca51fb756ef684b90f2780afc52fc67f987e3c61d800a46d/tomli-2.4.1-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:47149d5bd38761ac8be13a84864bf0b7b70bc051806bc3669ab1cbc56216b23c", size = 242227, upload-time = "2026-03-25T20:21:15.712Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/49/2b2a0ef529aa6eec245d25f0c703e020a73955ad7edf73e7f54ddc608aa5/tomli-2.4.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:ec9bfaf3ad2df51ace80688143a6a4ebc09a248f6ff781a9945e51937008fcbc", size = 247859, upload-time = "2026-03-25T20:21:17.001Z" },
+    { url = "https://files.pythonhosted.org/packages/83/bd/6c1a630eaca337e1e78c5903104f831bda934c426f9231429396ce3c3467/tomli-2.4.1-cp311-cp311-win32.whl", hash = "sha256:ff2983983d34813c1aeb0fa89091e76c3a22889ee83ab27c5eeb45100560c049", size = 97204, upload-time = "2026-03-25T20:21:18.079Z" },
+    { url = "https://files.pythonhosted.org/packages/42/59/71461df1a885647e10b6bb7802d0b8e66480c61f3f43079e0dcd315b3954/tomli-2.4.1-cp311-cp311-win_amd64.whl", hash = "sha256:5ee18d9ebdb417e384b58fe414e8d6af9f4e7a0ae761519fb50f721de398dd4e", size = 108084, upload-time = "2026-03-25T20:21:18.978Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/83/dceca96142499c069475b790e7913b1044c1a4337e700751f48ed723f883/tomli-2.4.1-cp311-cp311-win_arm64.whl", hash = "sha256:c2541745709bad0264b7d4705ad453b76ccd191e64aa6f0fc66b69a293a45ece", size = 95285, upload-time = "2026-03-25T20:21:20.309Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/ba/42f134a3fe2b370f555f44b1d72feebb94debcab01676bf918d0cb70e9aa/tomli-2.4.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:c742f741d58a28940ce01d58f0ab2ea3ced8b12402f162f4d534dfe18ba1cd6a", size = 155924, upload-time = "2026-03-25T20:21:21.626Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/c7/62d7a17c26487ade21c5422b646110f2162f1fcc95980ef7f63e73c68f14/tomli-2.4.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:7f86fd587c4ed9dd76f318225e7d9b29cfc5a9d43de44e5754db8d1128487085", size = 150018, upload-time = "2026-03-25T20:21:23.002Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/05/79d13d7c15f13bdef410bdd49a6485b1c37d28968314eabee452c22a7fda/tomli-2.4.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ff18e6a727ee0ab0388507b89d1bc6a22b138d1e2fa56d1ad494586d61d2eae9", size = 244948, upload-time = "2026-03-25T20:21:24.04Z" },
+    { url = "https://files.pythonhosted.org/packages/10/90/d62ce007a1c80d0b2c93e02cab211224756240884751b94ca72df8a875ca/tomli-2.4.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:136443dbd7e1dee43c68ac2694fde36b2849865fa258d39bf822c10e8068eac5", size = 253341, upload-time = "2026-03-25T20:21:25.177Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/7e/caf6496d60152ad4ed09282c1885cca4eea150bfd007da84aea07bcc0a3e/tomli-2.4.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:5e262d41726bc187e69af7825504c933b6794dc3fbd5945e41a79bb14c31f585", size = 248159, upload-time = "2026-03-25T20:21:26.364Z" },
+    { url = "https://files.pythonhosted.org/packages/99/e7/c6f69c3120de34bbd882c6fba7975f3d7a746e9218e56ab46a1bc4b42552/tomli-2.4.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:5cb41aa38891e073ee49d55fbc7839cfdb2bc0e600add13874d048c94aadddd1", size = 253290, upload-time = "2026-03-25T20:21:27.46Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/2f/4a3c322f22c5c66c4b836ec58211641a4067364f5dcdd7b974b4c5da300c/tomli-2.4.1-cp312-cp312-win32.whl", hash = "sha256:da25dc3563bff5965356133435b757a795a17b17d01dbc0f42fb32447ddfd917", size = 98141, upload-time = "2026-03-25T20:21:28.492Z" },
+    { url = "https://files.pythonhosted.org/packages/24/22/4daacd05391b92c55759d55eaee21e1dfaea86ce5c571f10083360adf534/tomli-2.4.1-cp312-cp312-win_amd64.whl", hash = "sha256:52c8ef851d9a240f11a88c003eacb03c31fc1c9c4ec64a99a0f922b93874fda9", size = 108847, upload-time = "2026-03-25T20:21:29.386Z" },
+    { url = "https://files.pythonhosted.org/packages/68/fd/70e768887666ddd9e9f5d85129e84910f2db2796f9096aa02b721a53098d/tomli-2.4.1-cp312-cp312-win_arm64.whl", hash = "sha256:f758f1b9299d059cc3f6546ae2af89670cb1c4d48ea29c3cacc4fe7de3058257", size = 95088, upload-time = "2026-03-25T20:21:30.677Z" },
+    { url = "https://files.pythonhosted.org/packages/07/06/b823a7e818c756d9a7123ba2cda7d07bc2dd32835648d1a7b7b7a05d848d/tomli-2.4.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:36d2bd2ad5fb9eaddba5226aa02c8ec3fa4f192631e347b3ed28186d43be6b54", size = 155866, upload-time = "2026-03-25T20:21:31.65Z" },
+    { url = "https://files.pythonhosted.org/packages/14/6f/12645cf7f08e1a20c7eb8c297c6f11d31c1b50f316a7e7e1e1de6e2e7b7e/tomli-2.4.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:eb0dc4e38e6a1fd579e5d50369aa2e10acfc9cace504579b2faabb478e76941a", size = 149887, upload-time = "2026-03-25T20:21:33.028Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/e0/90637574e5e7212c09099c67ad349b04ec4d6020324539297b634a0192b0/tomli-2.4.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c7f2c7f2b9ca6bdeef8f0fa897f8e05085923eb091721675170254cbc5b02897", size = 243704, upload-time = "2026-03-25T20:21:34.51Z" },
+    { url = "https://files.pythonhosted.org/packages/10/8f/d3ddb16c5a4befdf31a23307f72828686ab2096f068eaf56631e136c1fdd/tomli-2.4.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f3c6818a1a86dd6dca7ddcaaf76947d5ba31aecc28cb1b67009a5877c9a64f3f", size = 251628, upload-time = "2026-03-25T20:21:36.012Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/f1/dbeeb9116715abee2485bf0a12d07a8f31af94d71608c171c45f64c0469d/tomli-2.4.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:d312ef37c91508b0ab2cee7da26ec0b3ed2f03ce12bd87a588d771ae15dcf82d", size = 247180, upload-time = "2026-03-25T20:21:37.136Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/74/16336ffd19ed4da28a70959f92f506233bd7cfc2332b20bdb01591e8b1d1/tomli-2.4.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:51529d40e3ca50046d7606fa99ce3956a617f9b36380da3b7f0dd3dd28e68cb5", size = 251674, upload-time = "2026-03-25T20:21:38.298Z" },
+    { url = "https://files.pythonhosted.org/packages/16/f9/229fa3434c590ddf6c0aa9af64d3af4b752540686cace29e6281e3458469/tomli-2.4.1-cp313-cp313-win32.whl", hash = "sha256:2190f2e9dd7508d2a90ded5ed369255980a1bcdd58e52f7fe24b8162bf9fedbd", size = 97976, upload-time = "2026-03-25T20:21:39.316Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/1e/71dfd96bcc1c775420cb8befe7a9d35f2e5b1309798f009dca17b7708c1e/tomli-2.4.1-cp313-cp313-win_amd64.whl", hash = "sha256:8d65a2fbf9d2f8352685bc1364177ee3923d6baf5e7f43ea4959d7d8bc326a36", size = 108755, upload-time = "2026-03-25T20:21:40.248Z" },
+    { url = "https://files.pythonhosted.org/packages/83/7a/d34f422a021d62420b78f5c538e5b102f62bea616d1d75a13f0a88acb04a/tomli-2.4.1-cp313-cp313-win_arm64.whl", hash = "sha256:4b605484e43cdc43f0954ddae319fb75f04cc10dd80d830540060ee7cd0243cd", size = 95265, upload-time = "2026-03-25T20:21:41.219Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/fb/9a5c8d27dbab540869f7c1f8eb0abb3244189ce780ba9cd73f3770662072/tomli-2.4.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:fd0409a3653af6c147209d267a0e4243f0ae46b011aa978b1080359fddc9b6cf", size = 155726, upload-time = "2026-03-25T20:21:42.23Z" },
+    { url = "https://files.pythonhosted.org/packages/62/05/d2f816630cc771ad836af54f5001f47a6f611d2d39535364f148b6a92d6b/tomli-2.4.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:a120733b01c45e9a0c34aeef92bf0cf1d56cfe81ed9d47d562f9ed591a9828ac", size = 149859, upload-time = "2026-03-25T20:21:43.386Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/48/66341bdb858ad9bd0ceab5a86f90eddab127cf8b046418009f2125630ecb/tomli-2.4.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:559db847dc486944896521f68d8190be1c9e719fced785720d2216fe7022b662", size = 244713, upload-time = "2026-03-25T20:21:44.474Z" },
+    { url = "https://files.pythonhosted.org/packages/df/6d/c5fad00d82b3c7a3ab6189bd4b10e60466f22cfe8a08a9394185c8a8111c/tomli-2.4.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:01f520d4f53ef97964a240a035ec2a869fe1a37dde002b57ebc4417a27ccd853", size = 252084, upload-time = "2026-03-25T20:21:45.62Z" },
+    { url = "https://files.pythonhosted.org/packages/00/71/3a69e86f3eafe8c7a59d008d245888051005bd657760e96d5fbfb0b740c2/tomli-2.4.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7f94b27a62cfad8496c8d2513e1a222dd446f095fca8987fceef261225538a15", size = 247973, upload-time = "2026-03-25T20:21:46.937Z" },
+    { url = "https://files.pythonhosted.org/packages/67/50/361e986652847fec4bd5e4a0208752fbe64689c603c7ae5ea7cb16b1c0ca/tomli-2.4.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:ede3e6487c5ef5d28634ba3f31f989030ad6af71edfb0055cbbd14189ff240ba", size = 256223, upload-time = "2026-03-25T20:21:48.467Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/9a/b4173689a9203472e5467217e0154b00e260621caa227b6fa01feab16998/tomli-2.4.1-cp314-cp314-win32.whl", hash = "sha256:3d48a93ee1c9b79c04bb38772ee1b64dcf18ff43085896ea460ca8dec96f35f6", size = 98973, upload-time = "2026-03-25T20:21:49.526Z" },
+    { url = "https://files.pythonhosted.org/packages/14/58/640ac93bf230cd27d002462c9af0d837779f8773bc03dee06b5835208214/tomli-2.4.1-cp314-cp314-win_amd64.whl", hash = "sha256:88dceee75c2c63af144e456745e10101eb67361050196b0b6af5d717254dddf7", size = 109082, upload-time = "2026-03-25T20:21:50.506Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/2f/702d5e05b227401c1068f0d386d79a589bb12bf64c3d2c72ce0631e3bc49/tomli-2.4.1-cp314-cp314-win_arm64.whl", hash = "sha256:b8c198f8c1805dc42708689ed6864951fd2494f924149d3e4bce7710f8eb5232", size = 96490, upload-time = "2026-03-25T20:21:51.474Z" },
+    { url = "https://files.pythonhosted.org/packages/45/4b/b877b05c8ba62927d9865dd980e34a755de541eb65fffba52b4cc495d4d2/tomli-2.4.1-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:d4d8fe59808a54658fcc0160ecfb1b30f9089906c50b23bcb4c69eddc19ec2b4", size = 164263, upload-time = "2026-03-25T20:21:52.543Z" },
+    { url = "https://files.pythonhosted.org/packages/24/79/6ab420d37a270b89f7195dec5448f79400d9e9c1826df982f3f8e97b24fd/tomli-2.4.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:7008df2e7655c495dd12d2a4ad038ff878d4ca4b81fccaf82b714e07eae4402c", size = 160736, upload-time = "2026-03-25T20:21:53.674Z" },
+    { url = "https://files.pythonhosted.org/packages/02/e0/3630057d8eb170310785723ed5adcdfb7d50cb7e6455f85ba8a3deed642b/tomli-2.4.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1d8591993e228b0c930c4bb0db464bdad97b3289fb981255d6c9a41aedc84b2d", size = 270717, upload-time = "2026-03-25T20:21:55.129Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/b4/1613716072e544d1a7891f548d8f9ec6ce2faf42ca65acae01d76ea06bb0/tomli-2.4.1-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:734e20b57ba95624ecf1841e72b53f6e186355e216e5412de414e3c51e5e3c41", size = 278461, upload-time = "2026-03-25T20:21:56.228Z" },
+    { url = "https://files.pythonhosted.org/packages/05/38/30f541baf6a3f6df77b3df16b01ba319221389e2da59427e221ef417ac0c/tomli-2.4.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:8a650c2dbafa08d42e51ba0b62740dae4ecb9338eefa093aa5c78ceb546fcd5c", size = 274855, upload-time = "2026-03-25T20:21:57.653Z" },
+    { url = "https://files.pythonhosted.org/packages/77/a3/ec9dd4fd2c38e98de34223b995a3b34813e6bdadf86c75314c928350ed14/tomli-2.4.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:504aa796fe0569bb43171066009ead363de03675276d2d121ac1a4572397870f", size = 283144, upload-time = "2026-03-25T20:21:59.089Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/be/605a6261cac79fba2ec0c9827e986e00323a1945700969b8ee0b30d85453/tomli-2.4.1-cp314-cp314t-win32.whl", hash = "sha256:b1d22e6e9387bf4739fbe23bfa80e93f6b0373a7f1b96c6227c32bef95a4d7a8", size = 108683, upload-time = "2026-03-25T20:22:00.214Z" },
+    { url = "https://files.pythonhosted.org/packages/12/64/da524626d3b9cc40c168a13da8335fe1c51be12c0a63685cc6db7308daae/tomli-2.4.1-cp314-cp314t-win_amd64.whl", hash = "sha256:2c1c351919aca02858f740c6d33adea0c5deea37f9ecca1cc1ef9e884a619d26", size = 121196, upload-time = "2026-03-25T20:22:01.169Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/cd/e80b62269fc78fc36c9af5a6b89c835baa8af28ff5ad28c7028d60860320/tomli-2.4.1-cp314-cp314t-win_arm64.whl", hash = "sha256:eab21f45c7f66c13f2a9e0e1535309cee140182a9cdae1e041d02e47291e8396", size = 100393, upload-time = "2026-03-25T20:22:02.137Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/61/cceae43728b7de99d9b847560c262873a1f6c98202171fd5ed62640b494b/tomli-2.4.1-py3-none-any.whl", hash = "sha256:0d85819802132122da43cb86656f8d1f8c6587d54ae7dcaf30e90533028b49fe", size = 14583, upload-time = "2026-03-25T20:22:03.012Z" },
+]
+
+[[package]]
+name = "tqdm"
+version = "4.67.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/09/a9/6ba95a270c6f1fbcd8dac228323f2777d886cb206987444e4bce66338dd4/tqdm-4.67.3.tar.gz", hash = "sha256:7d825f03f89244ef73f1d4ce193cb1774a8179fd96f31d7e1dcde62092b960bb", size = 169598, upload-time = "2026-02-03T17:35:53.048Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/16/e1/3079a9ff9b8e11b846c6ac5c8b5bfb7ff225eee721825310c91b3b50304f/tqdm-4.67.3-py3-none-any.whl", hash = "sha256:ee1e4c0e59148062281c49d80b25b67771a127c85fc9676d3be5f243206826bf", size = 78374, upload-time = "2026-02-03T17:35:50.982Z" },
+]
+
+[[package]]
+name = "traitlets"
+version = "5.14.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/eb/79/72064e6a701c2183016abbbfedaba506d81e30e232a68c9f0d6f6fcd1574/traitlets-5.14.3.tar.gz", hash = "sha256:9ed0579d3502c94b4b3732ac120375cda96f923114522847de4b3bb98b96b6b7", size = 161621, upload-time = "2024-04-19T11:11:49.746Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/00/c0/8f5d070730d7836adc9c9b6408dec68c6ced86b304a9b26a14df072a6e8c/traitlets-5.14.3-py3-none-any.whl", hash = "sha256:b74e89e397b1ed28cc831db7aea759ba6640cb3de13090ca145426688ff1ac4f", size = 85359, upload-time = "2024-04-19T11:11:46.763Z" },
+]
+
+[[package]]
+name = "ty"
+version = "0.0.55"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/08/48/f687c8d268e3581f2f104d1f2ac5944d5b5e841b3695c613b3f263e5bbf7/ty-0.0.55.tar.gz", hash = "sha256:88ca87073825a79a8327c550efcc86cec94344890244c5946f84c9e44a969f31", size = 6040230, upload-time = "2026-06-27T00:27:29.385Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/87/a3/1a90ba7e5a61c6d09adb92346ddba97668095fc257b577af433e5ac4f404/ty-0.0.55-py3-none-linux_armv6l.whl", hash = "sha256:31e83eef512d066542fe990fe1a3b814423abd1616376c54e48af7045b3e1749", size = 11677249, upload-time = "2026-06-27T00:26:52.18Z" },
+    { url = "https://files.pythonhosted.org/packages/82/3a/669f9aa478c38243e213a2684db1502086026cfadc15bb1b29b7cbde030d/ty-0.0.55-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:ab4bca857950608fea73e269e2da369d43e6467131de85160d68e2fa466fa248", size = 11444180, upload-time = "2026-06-27T00:26:54.576Z" },
+    { url = "https://files.pythonhosted.org/packages/15/a4/6a4b2507a53ce6530c66c5b4fe0d58551eb1748ffa9e0696c32fdd55bbd4/ty-0.0.55-py3-none-macosx_11_0_arm64.whl", hash = "sha256:55032bfd31bf2c5355ee81bdc6407b144a1cc7ee41e5681dd1368e4cef2ba327", size = 10963134, upload-time = "2026-06-27T00:26:57.348Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/ae/a3b1a0f1cc83b7d258662cb98aa80a720c2e671d0e8fa0d17a4d5d057a7a/ty-0.0.55-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ef1e049f69ce65b3c269af67624607f435e1c32319786c1e453ef9611502f295", size = 11493517, upload-time = "2026-06-27T00:26:59.26Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/9f/311ce39065a979ef40a9b847f685c8e02464e53adf1671e081eea90640ca/ty-0.0.55-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:631409975c681d5a280fc5a99b7b32e9e801f33be7567c6b42ec331362f59d7d", size = 11460590, upload-time = "2026-06-27T00:27:01.425Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/8f/3bf29aa77bd78aae48275153135a2052fa7d3ccdf1ecabeb99c8773abd66/ty-0.0.55-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:e08cb0436e68b9351555ae8f2697138c9009b4d5b4ae4272232988b2a431a98f", size = 12098430, upload-time = "2026-06-27T00:27:03.596Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/6e/e88411a88240b94640bba06fb6d0d92b247fbeef47ee2bc71f39e58c2558/ty-0.0.55-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:16c215ad9f823829409b94ee188cfaa4563f6e1384f6ce3fecb1db75f6c7cf7c", size = 12673086, upload-time = "2026-06-27T00:27:05.589Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/7e/8f1762fb7f9245a68ba5ae338d73c59403ce57554e5d311b8bb55027b0ec/ty-0.0.55-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:b510eb8f4032baf11b7aee2f1d53babc3b4ca03939b9cdcf6a9d15761d575188", size = 12242559, upload-time = "2026-06-27T00:27:07.714Z" },
+    { url = "https://files.pythonhosted.org/packages/72/1f/143657daf2670d977dac83435f1fe03d4843efb798d8e1e75950e541aadd/ty-0.0.55-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0ddc05e7959709c3b9b83aa627128a80446865e3c1a4882638dcff6d776dc34a", size = 12021409, upload-time = "2026-06-27T00:27:09.881Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/30/69487c439dd1fad3a4a3d96f0a472193de297eaba6fc4b8ea687ce434ac2/ty-0.0.55-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:636e8e5078787b8c6916c94e1406719f10189a4ca6b37b813a5922ce5857a8c7", size = 12303807, upload-time = "2026-06-27T00:27:11.986Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/ca/cd88b6493dafc7db077f5e17c0438eb3af6e2d6d08f616dbb52a8ddfd567/ty-0.0.55-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:ef7d6deaacb73fec603666b5471f1dc5a5699aa84e11a6d4d644dd07ca72121e", size = 11441263, upload-time = "2026-06-27T00:27:14.087Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/fe/66b6915671653ab739f71e4f1b0528e69da64429b7ebf3840c625b6e43f2/ty-0.0.55-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:9aeea0fe5875d3cf37faf0e44d0fdf9669335467749741b8fc0103916fb5cd32", size = 11484584, upload-time = "2026-06-27T00:27:16.311Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/4f/7a9c0bbac8b899e9f6c0ec110c6612f52e4db35f6bb17ddc0ef60384fa3e/ty-0.0.55-py3-none-musllinux_1_2_i686.whl", hash = "sha256:0b699c01310dbd2705a07c97c5f4aaeedef61bd9adeea2e7c46aed32401d3576", size = 11759309, upload-time = "2026-06-27T00:27:18.471Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/de/b6f8b1b69aa631b5716ef3f985c3b56de0e46c2499cc00d30c402b41f714/ty-0.0.55-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:32cbeba543e46de2a983ec6d525d8b56514f7422bd1e1b57c44ccf7bfa72c38a", size = 12128755, upload-time = "2026-06-27T00:27:20.55Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/90/a912531e51ee7e076b42972479290fa687c0f5e747b7e773f3033164acaa/ty-0.0.55-py3-none-win32.whl", hash = "sha256:52b968e24eb4f7a5c3bd251db1f99f60dd385890356d38fc619d84f1b423446a", size = 11117501, upload-time = "2026-06-27T00:27:22.714Z" },
+    { url = "https://files.pythonhosted.org/packages/4c/7a/99d59843bf8908a7f9f4d13fda107dbad07b7faa28ecd7860eacf363fb1c/ty-0.0.55-py3-none-win_amd64.whl", hash = "sha256:bf39cbfdc0add44d94bd3fff1f53c351418d134b6a66b87efdb7876d7b7a2224", size = 12150106, upload-time = "2026-06-27T00:27:24.881Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/44/20987505cedf2a865b08482f0eabc181fd9599b062964057ec8a128a4296/ty-0.0.55-py3-none-win_arm64.whl", hash = "sha256:f7f3700a9a060e8f1af11e4fb63fafcaf272b041781f4ccdfda2b3b5c6c1e439", size = 11560157, upload-time = "2026-06-27T00:27:27.332Z" },
+]
+
+[[package]]
+name = "typer"
+version = "0.24.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "annotated-doc" },
+    { name = "click" },
+    { name = "rich" },
+    { name = "shellingham" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f5/24/cb09efec5cc954f7f9b930bf8279447d24618bb6758d4f6adf2574c41780/typer-0.24.1.tar.gz", hash = "sha256:e39b4732d65fbdcde189ae76cf7cd48aeae72919dea1fdfc16593be016256b45", size = 118613, upload-time = "2026-02-21T16:54:40.609Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/4a/91/48db081e7a63bb37284f9fbcefda7c44c277b18b0e13fbc36ea2335b71e6/typer-0.24.1-py3-none-any.whl", hash = "sha256:112c1f0ce578bfb4cab9ffdabc68f031416ebcc216536611ba21f04e9aa84c9e", size = 56085, upload-time = "2026-02-21T16:54:41.616Z" },
+]
+
+[[package]]
+name = "typing-extensions"
+version = "4.15.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/94/1a15dd82efb362ac84269196e94cf00f187f7ed21c242792a923cdb1c61f/typing_extensions-4.15.0.tar.gz", hash = "sha256:0cea48d173cc12fa28ecabc3b837ea3cf6f38c6d1136f85cbaaf598984861466", size = 109391, upload-time = "2025-08-25T13:49:26.313Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl", hash = "sha256:f0fa19c6845758ab08074a0cfa8b7aecb71c999ca73d62883bc25cc018c4e548", size = 44614, upload-time = "2025-08-25T13:49:24.86Z" },
+]
+
+[[package]]
+name = "typing-inspection"
+version = "0.4.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/55/e3/70399cb7dd41c10ac53367ae42139cf4b1ca5f36bb3dc6c9d33acdb43655/typing_inspection-0.4.2.tar.gz", hash = "sha256:ba561c48a67c5958007083d386c3295464928b01faa735ab8547c5692e87f464", size = 75949, upload-time = "2025-10-01T02:14:41.687Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/dc/9b/47798a6c91d8bdb567fe2698fe81e0c6b7cb7ef4d13da4114b41d239f65d/typing_inspection-0.4.2-py3-none-any.whl", hash = "sha256:4ed1cacbdc298c220f1bd249ed5287caa16f34d44ef4e9c3d0cbad5b521545e7", size = 14611, upload-time = "2025-10-01T02:14:40.154Z" },
+]
+
+[[package]]
+name = "tzdata"
+version = "2025.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/5e/a7/c202b344c5ca7daf398f3b8a477eeb205cf3b6f32e7ec3a6bac0629ca975/tzdata-2025.3.tar.gz", hash = "sha256:de39c2ca5dc7b0344f2eba86f49d614019d29f060fc4ebc8a417896a620b56a7", size = 196772, upload-time = "2025-12-13T17:45:35.667Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c7/b0/003792df09decd6849a5e39c28b513c06e84436a54440380862b5aeff25d/tzdata-2025.3-py2.py3-none-any.whl", hash = "sha256:06a47e5700f3081aab02b2e513160914ff0694bce9947d6b76ebd6bf57cfc5d1", size = 348521, upload-time = "2025-12-13T17:45:33.889Z" },
+]
+
+[[package]]
+name = "uncalled-for"
+version = "0.2.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/02/7c/b5b7d8136f872e3f13b0584e576886de0489d7213a12de6bebf29ff6ebfc/uncalled_for-0.2.0.tar.gz", hash = "sha256:b4f8fdbcec328c5a113807d653e041c5094473dd4afa7c34599ace69ccb7e69f", size = 49488, upload-time = "2026-02-27T17:40:58.137Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ff/7f/4320d9ce3be404e6310b915c3629fe27bf1e2f438a1a7a3cb0396e32e9a9/uncalled_for-0.2.0-py3-none-any.whl", hash = "sha256:2c0bd338faff5f930918f79e7eb9ff48290df2cb05fcc0b40a7f334e55d4d85f", size = 11351, upload-time = "2026-02-27T17:40:56.804Z" },
+]
+
+[[package]]
+name = "urllib3"
+version = "2.7.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/53/0c/06f8b233b8fd13b9e5ee11424ef85419ba0d8ba0b3138bf360be2ff56953/urllib3-2.7.0.tar.gz", hash = "sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c", size = 433602, upload-time = "2026-05-07T16:13:18.596Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7f/3e/5db95bcf282c52709639744ca2a8b149baccf648e39c8cc87553df9eae0c/urllib3-2.7.0-py3-none-any.whl", hash = "sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897", size = 131087, upload-time = "2026-05-07T16:13:17.151Z" },
+]
+
+[[package]]
+name = "uvicorn"
+version = "0.42.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+    { name = "h11" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e3/ad/4a96c425be6fb67e0621e62d86c402b4a17ab2be7f7c055d9bd2f638b9e2/uvicorn-0.42.0.tar.gz", hash = "sha256:9b1f190ce15a2dd22e7758651d9b6d12df09a13d51ba5bf4fc33c383a48e1775", size = 85393, upload-time = "2026-03-16T06:19:50.077Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0a/89/f8827ccff89c1586027a105e5630ff6139a64da2515e24dafe860bd9ae4d/uvicorn-0.42.0-py3-none-any.whl", hash = "sha256:96c30f5c7abe6f74ae8900a70e92b85ad6613b745d4879eb9b16ccad15645359", size = 68830, upload-time = "2026-03-16T06:19:48.325Z" },
+]
+
+[[package]]
+name = "watchfiles"
+version = "1.1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c2/c9/8869df9b2a2d6c59d79220a4db37679e74f807c559ffe5265e08b227a210/watchfiles-1.1.1.tar.gz", hash = "sha256:a173cb5c16c4f40ab19cecf48a534c409f7ea983ab8fed0741304a1c0a31b3f2", size = 94440, upload-time = "2025-10-14T15:06:21.08Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a7/1a/206e8cf2dd86fddf939165a57b4df61607a1e0add2785f170a3f616b7d9f/watchfiles-1.1.1-cp310-cp310-macosx_10_12_x86_64.whl", hash = "sha256:eef58232d32daf2ac67f42dea51a2c80f0d03379075d44a587051e63cc2e368c", size = 407318, upload-time = "2025-10-14T15:04:18.753Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/0f/abaf5262b9c496b5dad4ed3c0e799cbecb1f8ea512ecb6ddd46646a9fca3/watchfiles-1.1.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:03fa0f5237118a0c5e496185cafa92878568b652a2e9a9382a5151b1a0380a43", size = 394478, upload-time = "2025-10-14T15:04:20.297Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/04/9cc0ba88697b34b755371f5ace8d3a4d9a15719c07bdc7bd13d7d8c6a341/watchfiles-1.1.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:8ca65483439f9c791897f7db49202301deb6e15fe9f8fe2fed555bf986d10c31", size = 449894, upload-time = "2025-10-14T15:04:21.527Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/9c/eda4615863cd8621e89aed4df680d8c3ec3da6a4cf1da113c17decd87c7f/watchfiles-1.1.1-cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:f0ab1c1af0cb38e3f598244c17919fb1a84d1629cc08355b0074b6d7f53138ac", size = 459065, upload-time = "2025-10-14T15:04:22.795Z" },
+    { url = "https://files.pythonhosted.org/packages/84/13/f28b3f340157d03cbc8197629bc109d1098764abe1e60874622a0be5c112/watchfiles-1.1.1-cp310-cp310-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:3bc570d6c01c206c46deb6e935a260be44f186a2f05179f52f7fcd2be086a94d", size = 488377, upload-time = "2025-10-14T15:04:24.138Z" },
+    { url = "https://files.pythonhosted.org/packages/86/93/cfa597fa9389e122488f7ffdbd6db505b3b915ca7435ecd7542e855898c2/watchfiles-1.1.1-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:e84087b432b6ac94778de547e08611266f1f8ffad28c0ee4c82e028b0fc5966d", size = 595837, upload-time = "2025-10-14T15:04:25.057Z" },
+    { url = "https://files.pythonhosted.org/packages/57/1e/68c1ed5652b48d89fc24d6af905d88ee4f82fa8bc491e2666004e307ded1/watchfiles-1.1.1-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:620bae625f4cb18427b1bb1a2d9426dc0dd5a5ba74c7c2cdb9de405f7b129863", size = 473456, upload-time = "2025-10-14T15:04:26.497Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/dc/1a680b7458ffa3b14bb64878112aefc8f2e4f73c5af763cbf0bd43100658/watchfiles-1.1.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:544364b2b51a9b0c7000a4b4b02f90e9423d97fbbf7e06689236443ebcad81ab", size = 455614, upload-time = "2025-10-14T15:04:27.539Z" },
+    { url = "https://files.pythonhosted.org/packages/61/a5/3d782a666512e01eaa6541a72ebac1d3aae191ff4a31274a66b8dd85760c/watchfiles-1.1.1-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:bbe1ef33d45bc71cf21364df962af171f96ecaeca06bd9e3d0b583efb12aec82", size = 630690, upload-time = "2025-10-14T15:04:28.495Z" },
+    { url = "https://files.pythonhosted.org/packages/9b/73/bb5f38590e34687b2a9c47a244aa4dd50c56a825969c92c9c5fc7387cea1/watchfiles-1.1.1-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:1a0bb430adb19ef49389e1ad368450193a90038b5b752f4ac089ec6942c4dff4", size = 622459, upload-time = "2025-10-14T15:04:29.491Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/ac/c9bb0ec696e07a20bd58af5399aeadaef195fb2c73d26baf55180fe4a942/watchfiles-1.1.1-cp310-cp310-win32.whl", hash = "sha256:3f6d37644155fb5beca5378feb8c1708d5783145f2a0f1c4d5a061a210254844", size = 272663, upload-time = "2025-10-14T15:04:30.435Z" },
+    { url = "https://files.pythonhosted.org/packages/11/a0/a60c5a7c2ec59fa062d9a9c61d02e3b6abd94d32aac2d8344c4bdd033326/watchfiles-1.1.1-cp310-cp310-win_amd64.whl", hash = "sha256:a36d8efe0f290835fd0f33da35042a1bb5dc0e83cbc092dcf69bce442579e88e", size = 287453, upload-time = "2025-10-14T15:04:31.53Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/f8/2c5f479fb531ce2f0564eda479faecf253d886b1ab3630a39b7bf7362d46/watchfiles-1.1.1-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:f57b396167a2565a4e8b5e56a5a1c537571733992b226f4f1197d79e94cf0ae5", size = 406529, upload-time = "2025-10-14T15:04:32.899Z" },
+    { url = "https://files.pythonhosted.org/packages/fe/cd/f515660b1f32f65df671ddf6f85bfaca621aee177712874dc30a97397977/watchfiles-1.1.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:421e29339983e1bebc281fab40d812742268ad057db4aee8c4d2bce0af43b741", size = 394384, upload-time = "2025-10-14T15:04:33.761Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/c3/28b7dc99733eab43fca2d10f55c86e03bd6ab11ca31b802abac26b23d161/watchfiles-1.1.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6e43d39a741e972bab5d8100b5cdacf69db64e34eb19b6e9af162bccf63c5cc6", size = 448789, upload-time = "2025-10-14T15:04:34.679Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/24/33e71113b320030011c8e4316ccca04194bf0cbbaeee207f00cbc7d6b9f5/watchfiles-1.1.1-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:f537afb3276d12814082a2e9b242bdcf416c2e8fd9f799a737990a1dbe906e5b", size = 460521, upload-time = "2025-10-14T15:04:35.963Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/c3/3c9a55f255aa57b91579ae9e98c88704955fa9dac3e5614fb378291155df/watchfiles-1.1.1-cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:b2cd9e04277e756a2e2d2543d65d1e2166d6fd4c9b183f8808634fda23f17b14", size = 488722, upload-time = "2025-10-14T15:04:37.091Z" },
+    { url = "https://files.pythonhosted.org/packages/49/36/506447b73eb46c120169dc1717fe2eff07c234bb3232a7200b5f5bd816e9/watchfiles-1.1.1-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5f3f58818dc0b07f7d9aa7fe9eb1037aecb9700e63e1f6acfed13e9fef648f5d", size = 596088, upload-time = "2025-10-14T15:04:38.39Z" },
+    { url = "https://files.pythonhosted.org/packages/82/ab/5f39e752a9838ec4d52e9b87c1e80f1ee3ccdbe92e183c15b6577ab9de16/watchfiles-1.1.1-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9bb9f66367023ae783551042d31b1d7fd422e8289eedd91f26754a66f44d5cff", size = 472923, upload-time = "2025-10-14T15:04:39.666Z" },
+    { url = "https://files.pythonhosted.org/packages/af/b9/a419292f05e302dea372fa7e6fda5178a92998411f8581b9830d28fb9edb/watchfiles-1.1.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:aebfd0861a83e6c3d1110b78ad54704486555246e542be3e2bb94195eabb2606", size = 456080, upload-time = "2025-10-14T15:04:40.643Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/c3/d5932fd62bde1a30c36e10c409dc5d54506726f08cb3e1d8d0ba5e2bc8db/watchfiles-1.1.1-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:5fac835b4ab3c6487b5dbad78c4b3724e26bcc468e886f8ba8cc4306f68f6701", size = 629432, upload-time = "2025-10-14T15:04:41.789Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/77/16bddd9779fafb795f1a94319dc965209c5641db5bf1edbbccace6d1b3c0/watchfiles-1.1.1-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:399600947b170270e80134ac854e21b3ccdefa11a9529a3decc1327088180f10", size = 623046, upload-time = "2025-10-14T15:04:42.718Z" },
+    { url = "https://files.pythonhosted.org/packages/46/ef/f2ecb9a0f342b4bfad13a2787155c6ee7ce792140eac63a34676a2feeef2/watchfiles-1.1.1-cp311-cp311-win32.whl", hash = "sha256:de6da501c883f58ad50db3a32ad397b09ad29865b5f26f64c24d3e3281685849", size = 271473, upload-time = "2025-10-14T15:04:43.624Z" },
+    { url = "https://files.pythonhosted.org/packages/94/bc/f42d71125f19731ea435c3948cad148d31a64fccde3867e5ba4edee901f9/watchfiles-1.1.1-cp311-cp311-win_amd64.whl", hash = "sha256:35c53bd62a0b885bf653ebf6b700d1bf05debb78ad9292cf2a942b23513dc4c4", size = 287598, upload-time = "2025-10-14T15:04:44.516Z" },
+    { url = "https://files.pythonhosted.org/packages/57/c9/a30f897351f95bbbfb6abcadafbaca711ce1162f4db95fc908c98a9165f3/watchfiles-1.1.1-cp311-cp311-win_arm64.whl", hash = "sha256:57ca5281a8b5e27593cb7d82c2ac927ad88a96ed406aa446f6344e4328208e9e", size = 277210, upload-time = "2025-10-14T15:04:45.883Z" },
+    { url = "https://files.pythonhosted.org/packages/74/d5/f039e7e3c639d9b1d09b07ea412a6806d38123f0508e5f9b48a87b0a76cc/watchfiles-1.1.1-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:8c89f9f2f740a6b7dcc753140dd5e1ab9215966f7a3530d0c0705c83b401bd7d", size = 404745, upload-time = "2025-10-14T15:04:46.731Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/96/a881a13aa1349827490dab2d363c8039527060cfcc2c92cc6d13d1b1049e/watchfiles-1.1.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:bd404be08018c37350f0d6e34676bd1e2889990117a2b90070b3007f172d0610", size = 391769, upload-time = "2025-10-14T15:04:48.003Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/5b/d3b460364aeb8da471c1989238ea0e56bec24b6042a68046adf3d9ddb01c/watchfiles-1.1.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:8526e8f916bb5b9a0a777c8317c23ce65de259422bba5b31325a6fa6029d33af", size = 449374, upload-time = "2025-10-14T15:04:49.179Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/44/5769cb62d4ed055cb17417c0a109a92f007114a4e07f30812a73a4efdb11/watchfiles-1.1.1-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:2edc3553362b1c38d9f06242416a5d8e9fe235c204a4072e988ce2e5bb1f69f6", size = 459485, upload-time = "2025-10-14T15:04:50.155Z" },
+    { url = "https://files.pythonhosted.org/packages/19/0c/286b6301ded2eccd4ffd0041a1b726afda999926cf720aab63adb68a1e36/watchfiles-1.1.1-cp312-cp312-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:30f7da3fb3f2844259cba4720c3fc7138eb0f7b659c38f3bfa65084c7fc7abce", size = 488813, upload-time = "2025-10-14T15:04:51.059Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/2b/8530ed41112dd4a22f4dcfdb5ccf6a1baad1ff6eed8dc5a5f09e7e8c41c7/watchfiles-1.1.1-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:f8979280bdafff686ba5e4d8f97840f929a87ed9cdf133cbbd42f7766774d2aa", size = 594816, upload-time = "2025-10-14T15:04:52.031Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/d2/f5f9fb49489f184f18470d4f99f4e862a4b3e9ac2865688eb2099e3d837a/watchfiles-1.1.1-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:dcc5c24523771db3a294c77d94771abcfcb82a0e0ee8efd910c37c59ec1b31bb", size = 475186, upload-time = "2025-10-14T15:04:53.064Z" },
+    { url = "https://files.pythonhosted.org/packages/cf/68/5707da262a119fb06fbe214d82dd1fe4a6f4af32d2d14de368d0349eb52a/watchfiles-1.1.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1db5d7ae38ff20153d542460752ff397fcf5c96090c1230803713cf3147a6803", size = 456812, upload-time = "2025-10-14T15:04:55.174Z" },
+    { url = "https://files.pythonhosted.org/packages/66/ab/3cbb8756323e8f9b6f9acb9ef4ec26d42b2109bce830cc1f3468df20511d/watchfiles-1.1.1-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:28475ddbde92df1874b6c5c8aaeb24ad5be47a11f87cde5a28ef3835932e3e94", size = 630196, upload-time = "2025-10-14T15:04:56.22Z" },
+    { url = "https://files.pythonhosted.org/packages/78/46/7152ec29b8335f80167928944a94955015a345440f524d2dfe63fc2f437b/watchfiles-1.1.1-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:36193ed342f5b9842edd3532729a2ad55c4160ffcfa3700e0d54be496b70dd43", size = 622657, upload-time = "2025-10-14T15:04:57.521Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/bf/95895e78dd75efe9a7f31733607f384b42eb5feb54bd2eb6ed57cc2e94f4/watchfiles-1.1.1-cp312-cp312-win32.whl", hash = "sha256:859e43a1951717cc8de7f4c77674a6d389b106361585951d9e69572823f311d9", size = 272042, upload-time = "2025-10-14T15:04:59.046Z" },
+    { url = "https://files.pythonhosted.org/packages/87/0a/90eb755f568de2688cb220171c4191df932232c20946966c27a59c400850/watchfiles-1.1.1-cp312-cp312-win_amd64.whl", hash = "sha256:91d4c9a823a8c987cce8fa2690923b069966dabb196dd8d137ea2cede885fde9", size = 288410, upload-time = "2025-10-14T15:05:00.081Z" },
+    { url = "https://files.pythonhosted.org/packages/36/76/f322701530586922fbd6723c4f91ace21364924822a8772c549483abed13/watchfiles-1.1.1-cp312-cp312-win_arm64.whl", hash = "sha256:a625815d4a2bdca61953dbba5a39d60164451ef34c88d751f6c368c3ea73d404", size = 278209, upload-time = "2025-10-14T15:05:01.168Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/f4/f750b29225fe77139f7ae5de89d4949f5a99f934c65a1f1c0b248f26f747/watchfiles-1.1.1-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:130e4876309e8686a5e37dba7d5e9bc77e6ed908266996ca26572437a5271e18", size = 404321, upload-time = "2025-10-14T15:05:02.063Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/f9/f07a295cde762644aa4c4bb0f88921d2d141af45e735b965fb2e87858328/watchfiles-1.1.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:5f3bde70f157f84ece3765b42b4a52c6ac1a50334903c6eaf765362f6ccca88a", size = 391783, upload-time = "2025-10-14T15:05:03.052Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/11/fc2502457e0bea39a5c958d86d2cb69e407a4d00b85735ca724bfa6e0d1a/watchfiles-1.1.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:14e0b1fe858430fc0251737ef3824c54027bedb8c37c38114488b8e131cf8219", size = 449279, upload-time = "2025-10-14T15:05:04.004Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/1f/d66bc15ea0b728df3ed96a539c777acfcad0eb78555ad9efcaa1274688f0/watchfiles-1.1.1-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:f27db948078f3823a6bb3b465180db8ebecf26dd5dae6f6180bd87383b6b4428", size = 459405, upload-time = "2025-10-14T15:05:04.942Z" },
+    { url = "https://files.pythonhosted.org/packages/be/90/9f4a65c0aec3ccf032703e6db02d89a157462fbb2cf20dd415128251cac0/watchfiles-1.1.1-cp313-cp313-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:059098c3a429f62fc98e8ec62b982230ef2c8df68c79e826e37b895bc359a9c0", size = 488976, upload-time = "2025-10-14T15:05:05.905Z" },
+    { url = "https://files.pythonhosted.org/packages/37/57/ee347af605d867f712be7029bb94c8c071732a4b44792e3176fa3c612d39/watchfiles-1.1.1-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:bfb5862016acc9b869bb57284e6cb35fdf8e22fe59f7548858e2f971d045f150", size = 595506, upload-time = "2025-10-14T15:05:06.906Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/78/cc5ab0b86c122047f75e8fc471c67a04dee395daf847d3e59381996c8707/watchfiles-1.1.1-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:319b27255aacd9923b8a276bb14d21a5f7ff82564c744235fc5eae58d95422ae", size = 474936, upload-time = "2025-10-14T15:05:07.906Z" },
+    { url = "https://files.pythonhosted.org/packages/62/da/def65b170a3815af7bd40a3e7010bf6ab53089ef1b75d05dd5385b87cf08/watchfiles-1.1.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:c755367e51db90e75b19454b680903631d41f9e3607fbd941d296a020c2d752d", size = 456147, upload-time = "2025-10-14T15:05:09.138Z" },
+    { url = "https://files.pythonhosted.org/packages/57/99/da6573ba71166e82d288d4df0839128004c67d2778d3b566c138695f5c0b/watchfiles-1.1.1-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:c22c776292a23bfc7237a98f791b9ad3144b02116ff10d820829ce62dff46d0b", size = 630007, upload-time = "2025-10-14T15:05:10.117Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/51/7439c4dd39511368849eb1e53279cd3454b4a4dbace80bab88feeb83c6b5/watchfiles-1.1.1-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:3a476189be23c3686bc2f4321dd501cb329c0a0469e77b7b534ee10129ae6374", size = 622280, upload-time = "2025-10-14T15:05:11.146Z" },
+    { url = "https://files.pythonhosted.org/packages/95/9c/8ed97d4bba5db6fdcdb2b298d3898f2dd5c20f6b73aee04eabe56c59677e/watchfiles-1.1.1-cp313-cp313-win32.whl", hash = "sha256:bf0a91bfb5574a2f7fc223cf95eeea79abfefa404bf1ea5e339c0c1560ae99a0", size = 272056, upload-time = "2025-10-14T15:05:12.156Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/f3/c14e28429f744a260d8ceae18bf58c1d5fa56b50d006a7a9f80e1882cb0d/watchfiles-1.1.1-cp313-cp313-win_amd64.whl", hash = "sha256:52e06553899e11e8074503c8e716d574adeeb7e68913115c4b3653c53f9bae42", size = 288162, upload-time = "2025-10-14T15:05:13.208Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/61/fe0e56c40d5cd29523e398d31153218718c5786b5e636d9ae8ae79453d27/watchfiles-1.1.1-cp313-cp313-win_arm64.whl", hash = "sha256:ac3cc5759570cd02662b15fbcd9d917f7ecd47efe0d6b40474eafd246f91ea18", size = 277909, upload-time = "2025-10-14T15:05:14.49Z" },
+    { url = "https://files.pythonhosted.org/packages/79/42/e0a7d749626f1e28c7108a99fb9bf524b501bbbeb9b261ceecde644d5a07/watchfiles-1.1.1-cp313-cp313t-macosx_10_12_x86_64.whl", hash = "sha256:563b116874a9a7ce6f96f87cd0b94f7faf92d08d0021e837796f0a14318ef8da", size = 403389, upload-time = "2025-10-14T15:05:15.777Z" },
+    { url = "https://files.pythonhosted.org/packages/15/49/08732f90ce0fbbc13913f9f215c689cfc9ced345fb1bcd8829a50007cc8d/watchfiles-1.1.1-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:3ad9fe1dae4ab4212d8c91e80b832425e24f421703b5a42ef2e4a1e215aff051", size = 389964, upload-time = "2025-10-14T15:05:16.85Z" },
+    { url = "https://files.pythonhosted.org/packages/27/0d/7c315d4bd5f2538910491a0393c56bf70d333d51bc5b34bee8e68e8cea19/watchfiles-1.1.1-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ce70f96a46b894b36eba678f153f052967a0d06d5b5a19b336ab0dbbd029f73e", size = 448114, upload-time = "2025-10-14T15:05:17.876Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/24/9e096de47a4d11bc4df41e9d1e61776393eac4cb6eb11b3e23315b78b2cc/watchfiles-1.1.1-cp313-cp313t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:cb467c999c2eff23a6417e58d75e5828716f42ed8289fe6b77a7e5a91036ca70", size = 460264, upload-time = "2025-10-14T15:05:18.962Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/0f/e8dea6375f1d3ba5fcb0b3583e2b493e77379834c74fd5a22d66d85d6540/watchfiles-1.1.1-cp313-cp313t-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:836398932192dae4146c8f6f737d74baeac8b70ce14831a239bdb1ca882fc261", size = 487877, upload-time = "2025-10-14T15:05:20.094Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/5b/df24cfc6424a12deb41503b64d42fbea6b8cb357ec62ca84a5a3476f654a/watchfiles-1.1.1-cp313-cp313t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:743185e7372b7bc7c389e1badcc606931a827112fbbd37f14c537320fca08620", size = 595176, upload-time = "2025-10-14T15:05:21.134Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/b5/853b6757f7347de4e9b37e8cc3289283fb983cba1ab4d2d7144694871d9c/watchfiles-1.1.1-cp313-cp313t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:afaeff7696e0ad9f02cbb8f56365ff4686ab205fcf9c4c5b6fdfaaa16549dd04", size = 473577, upload-time = "2025-10-14T15:05:22.306Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/f7/0a4467be0a56e80447c8529c9fce5b38eab4f513cb3d9bf82e7392a5696b/watchfiles-1.1.1-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:3f7eb7da0eb23aa2ba036d4f616d46906013a68caf61b7fdbe42fc8b25132e77", size = 455425, upload-time = "2025-10-14T15:05:23.348Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/e0/82583485ea00137ddf69bc84a2db88bd92ab4a6e3c405e5fb878ead8d0e7/watchfiles-1.1.1-cp313-cp313t-musllinux_1_1_aarch64.whl", hash = "sha256:831a62658609f0e5c64178211c942ace999517f5770fe9436be4c2faeba0c0ef", size = 628826, upload-time = "2025-10-14T15:05:24.398Z" },
+    { url = "https://files.pythonhosted.org/packages/28/9a/a785356fccf9fae84c0cc90570f11702ae9571036fb25932f1242c82191c/watchfiles-1.1.1-cp313-cp313t-musllinux_1_1_x86_64.whl", hash = "sha256:f9a2ae5c91cecc9edd47e041a930490c31c3afb1f5e6d71de3dc671bfaca02bf", size = 622208, upload-time = "2025-10-14T15:05:25.45Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/f4/0872229324ef69b2c3edec35e84bd57a1289e7d3fe74588048ed8947a323/watchfiles-1.1.1-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:d1715143123baeeaeadec0528bb7441103979a1d5f6fd0e1f915383fea7ea6d5", size = 404315, upload-time = "2025-10-14T15:05:26.501Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/22/16d5331eaed1cb107b873f6ae1b69e9ced582fcf0c59a50cd84f403b1c32/watchfiles-1.1.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:39574d6370c4579d7f5d0ad940ce5b20db0e4117444e39b6d8f99db5676c52fd", size = 390869, upload-time = "2025-10-14T15:05:27.649Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/7e/5643bfff5acb6539b18483128fdc0ef2cccc94a5b8fbda130c823e8ed636/watchfiles-1.1.1-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:7365b92c2e69ee952902e8f70f3ba6360d0d596d9299d55d7d386df84b6941fb", size = 449919, upload-time = "2025-10-14T15:05:28.701Z" },
+    { url = "https://files.pythonhosted.org/packages/51/2e/c410993ba5025a9f9357c376f48976ef0e1b1aefb73b97a5ae01a5972755/watchfiles-1.1.1-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:bfff9740c69c0e4ed32416f013f3c45e2ae42ccedd1167ef2d805c000b6c71a5", size = 460845, upload-time = "2025-10-14T15:05:30.064Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/a4/2df3b404469122e8680f0fcd06079317e48db58a2da2950fb45020947734/watchfiles-1.1.1-cp314-cp314-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:b27cf2eb1dda37b2089e3907d8ea92922b673c0c427886d4edc6b94d8dfe5db3", size = 489027, upload-time = "2025-10-14T15:05:31.064Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/84/4587ba5b1f267167ee715b7f66e6382cca6938e0a4b870adad93e44747e6/watchfiles-1.1.1-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:526e86aced14a65a5b0ec50827c745597c782ff46b571dbfe46192ab9e0b3c33", size = 595615, upload-time = "2025-10-14T15:05:32.074Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/0f/c6988c91d06e93cd0bb3d4a808bcf32375ca1904609835c3031799e3ecae/watchfiles-1.1.1-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:04e78dd0b6352db95507fd8cb46f39d185cf8c74e4cf1e4fbad1d3df96faf510", size = 474836, upload-time = "2025-10-14T15:05:33.209Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/36/ded8aebea91919485b7bbabbd14f5f359326cb5ec218cd67074d1e426d74/watchfiles-1.1.1-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:5c85794a4cfa094714fb9c08d4a218375b2b95b8ed1666e8677c349906246c05", size = 455099, upload-time = "2025-10-14T15:05:34.189Z" },
+    { url = "https://files.pythonhosted.org/packages/98/e0/8c9bdba88af756a2fce230dd365fab2baf927ba42cd47521ee7498fd5211/watchfiles-1.1.1-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:74d5012b7630714b66be7b7b7a78855ef7ad58e8650c73afc4c076a1f480a8d6", size = 630626, upload-time = "2025-10-14T15:05:35.216Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/84/a95db05354bf2d19e438520d92a8ca475e578c647f78f53197f5a2f17aaf/watchfiles-1.1.1-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:8fbe85cb3201c7d380d3d0b90e63d520f15d6afe217165d7f98c9c649654db81", size = 622519, upload-time = "2025-10-14T15:05:36.259Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/ce/d8acdc8de545de995c339be67711e474c77d643555a9bb74a9334252bd55/watchfiles-1.1.1-cp314-cp314-win32.whl", hash = "sha256:3fa0b59c92278b5a7800d3ee7733da9d096d4aabcfabb9a928918bd276ef9b9b", size = 272078, upload-time = "2025-10-14T15:05:37.63Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/c9/a74487f72d0451524be827e8edec251da0cc1fcf111646a511ae752e1a3d/watchfiles-1.1.1-cp314-cp314-win_amd64.whl", hash = "sha256:c2047d0b6cea13b3316bdbafbfa0c4228ae593d995030fda39089d36e64fc03a", size = 287664, upload-time = "2025-10-14T15:05:38.95Z" },
+    { url = "https://files.pythonhosted.org/packages/df/b8/8ac000702cdd496cdce998c6f4ee0ca1f15977bba51bdf07d872ebdfc34c/watchfiles-1.1.1-cp314-cp314-win_arm64.whl", hash = "sha256:842178b126593addc05acf6fce960d28bc5fae7afbaa2c6c1b3a7b9460e5be02", size = 277154, upload-time = "2025-10-14T15:05:39.954Z" },
+    { url = "https://files.pythonhosted.org/packages/47/a8/e3af2184707c29f0f14b1963c0aace6529f9d1b8582d5b99f31bbf42f59e/watchfiles-1.1.1-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:88863fbbc1a7312972f1c511f202eb30866370ebb8493aef2812b9ff28156a21", size = 403820, upload-time = "2025-10-14T15:05:40.932Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/ec/e47e307c2f4bd75f9f9e8afbe3876679b18e1bcec449beca132a1c5ffb2d/watchfiles-1.1.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:55c7475190662e202c08c6c0f4d9e345a29367438cf8e8037f3155e10a88d5a5", size = 390510, upload-time = "2025-10-14T15:05:41.945Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/a0/ad235642118090f66e7b2f18fd5c42082418404a79205cdfca50b6309c13/watchfiles-1.1.1-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3f53fa183d53a1d7a8852277c92b967ae99c2d4dcee2bfacff8868e6e30b15f7", size = 448408, upload-time = "2025-10-14T15:05:43.385Z" },
+    { url = "https://files.pythonhosted.org/packages/df/85/97fa10fd5ff3332ae17e7e40e20784e419e28521549780869f1413742e9d/watchfiles-1.1.1-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:6aae418a8b323732fa89721d86f39ec8f092fc2af67f4217a2b07fd3e93c6101", size = 458968, upload-time = "2025-10-14T15:05:44.404Z" },
+    { url = "https://files.pythonhosted.org/packages/47/c2/9059c2e8966ea5ce678166617a7f75ecba6164375f3b288e50a40dc6d489/watchfiles-1.1.1-cp314-cp314t-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:f096076119da54a6080e8920cbdaac3dbee667eb91dcc5e5b78840b87415bd44", size = 488096, upload-time = "2025-10-14T15:05:45.398Z" },
+    { url = "https://files.pythonhosted.org/packages/94/44/d90a9ec8ac309bc26db808a13e7bfc0e4e78b6fc051078a554e132e80160/watchfiles-1.1.1-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:00485f441d183717038ed2e887a7c868154f216877653121068107b227a2f64c", size = 596040, upload-time = "2025-10-14T15:05:46.502Z" },
+    { url = "https://files.pythonhosted.org/packages/95/68/4e3479b20ca305cfc561db3ed207a8a1c745ee32bf24f2026a129d0ddb6e/watchfiles-1.1.1-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:a55f3e9e493158d7bfdb60a1165035f1cf7d320914e7b7ea83fe22c6023b58fc", size = 473847, upload-time = "2025-10-14T15:05:47.484Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/55/2af26693fd15165c4ff7857e38330e1b61ab8c37d15dc79118cdba115b7a/watchfiles-1.1.1-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8c91ed27800188c2ae96d16e3149f199d62f86c7af5f5f4d2c61a3ed8cd3666c", size = 455072, upload-time = "2025-10-14T15:05:48.928Z" },
+    { url = "https://files.pythonhosted.org/packages/66/1d/d0d200b10c9311ec25d2273f8aad8c3ef7cc7ea11808022501811208a750/watchfiles-1.1.1-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:311ff15a0bae3714ffb603e6ba6dbfba4065ab60865d15a6ec544133bdb21099", size = 629104, upload-time = "2025-10-14T15:05:49.908Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/bd/fa9bb053192491b3867ba07d2343d9f2252e00811567d30ae8d0f78136fe/watchfiles-1.1.1-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:a916a2932da8f8ab582f242c065f5c81bed3462849ca79ee357dd9551b0e9b01", size = 622112, upload-time = "2025-10-14T15:05:50.941Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/4c/a888c91e2e326872fa4705095d64acd8aa2fb9c1f7b9bd0588f33850516c/watchfiles-1.1.1-pp310-pypy310_pp73-macosx_10_12_x86_64.whl", hash = "sha256:17ef139237dfced9da49fb7f2232c86ca9421f666d78c264c7ffca6601d154c3", size = 409611, upload-time = "2025-10-14T15:06:05.809Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/c7/5420d1943c8e3ce1a21c0a9330bcf7edafb6aa65d26b21dbb3267c9e8112/watchfiles-1.1.1-pp310-pypy310_pp73-macosx_11_0_arm64.whl", hash = "sha256:672b8adf25b1a0d35c96b5888b7b18699d27d4194bac8beeae75be4b7a3fc9b2", size = 396889, upload-time = "2025-10-14T15:06:07.035Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/e5/0072cef3804ce8d3aaddbfe7788aadff6b3d3f98a286fdbee9fd74ca59a7/watchfiles-1.1.1-pp310-pypy310_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:77a13aea58bc2b90173bc69f2a90de8e282648939a00a602e1dc4ee23e26b66d", size = 451616, upload-time = "2025-10-14T15:06:08.072Z" },
+    { url = "https://files.pythonhosted.org/packages/83/4e/b87b71cbdfad81ad7e83358b3e447fedd281b880a03d64a760fe0a11fc2e/watchfiles-1.1.1-pp310-pypy310_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0b495de0bb386df6a12b18335a0285dda90260f51bdb505503c02bcd1ce27a8b", size = 458413, upload-time = "2025-10-14T15:06:09.209Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/8e/e500f8b0b77be4ff753ac94dc06b33d8f0d839377fee1b78e8c8d8f031bf/watchfiles-1.1.1-pp311-pypy311_pp73-macosx_10_12_x86_64.whl", hash = "sha256:db476ab59b6765134de1d4fe96a1a9c96ddf091683599be0f26147ea1b2e4b88", size = 408250, upload-time = "2025-10-14T15:06:10.264Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/95/615e72cd27b85b61eec764a5ca51bd94d40b5adea5ff47567d9ebc4d275a/watchfiles-1.1.1-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:89eef07eee5e9d1fda06e38822ad167a044153457e6fd997f8a858ab7564a336", size = 396117, upload-time = "2025-10-14T15:06:11.28Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/81/e7fe958ce8a7fb5c73cc9fb07f5aeaf755e6aa72498c57d760af760c91f8/watchfiles-1.1.1-pp311-pypy311_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ce19e06cbda693e9e7686358af9cd6f5d61312ab8b00488bc36f5aabbaf77e24", size = 450493, upload-time = "2025-10-14T15:06:12.321Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/d4/ed38dd3b1767193de971e694aa544356e63353c33a85d948166b5ff58b9e/watchfiles-1.1.1-pp311-pypy311_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:3e6f39af2eab0118338902798b5aa6664f46ff66bc0280de76fca67a7f262a49", size = 457546, upload-time = "2025-10-14T15:06:13.372Z" },
+]
+
+[[package]]
+name = "wcwidth"
+version = "0.6.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/35/a2/8e3becb46433538a38726c948d3399905a4c7cabd0df578ede5dc51f0ec2/wcwidth-0.6.0.tar.gz", hash = "sha256:cdc4e4262d6ef9a1a57e018384cbeb1208d8abbc64176027e2c2455c81313159", size = 159684, upload-time = "2026-02-06T19:19:40.919Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/68/5a/199c59e0a824a3db2b89c5d2dade7ab5f9624dbf6448dc291b46d5ec94d3/wcwidth-0.6.0-py3-none-any.whl", hash = "sha256:1a3a1e510b553315f8e146c54764f4fb6264ffad731b3d78088cdb1478ffbdad", size = 94189, upload-time = "2026-02-06T19:19:39.646Z" },
+]
+
+[[package]]
+name = "websockets"
+version = "16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/04/24/4b2031d72e840ce4c1ccb255f693b15c334757fc50023e4db9537080b8c4/websockets-16.0.tar.gz", hash = "sha256:5f6261a5e56e8d5c42a4497b364ea24d94d9563e8fbd44e78ac40879c60179b5", size = 179346, upload-time = "2026-01-10T09:23:47.181Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/20/74/221f58decd852f4b59cc3354cccaf87e8ef695fede361d03dc9a7396573b/websockets-16.0-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:04cdd5d2d1dacbad0a7bf36ccbcd3ccd5a30ee188f2560b7a62a30d14107b31a", size = 177343, upload-time = "2026-01-10T09:22:21.28Z" },
+    { url = "https://files.pythonhosted.org/packages/19/0f/22ef6107ee52ab7f0b710d55d36f5a5d3ef19e8a205541a6d7ffa7994e5a/websockets-16.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:8ff32bb86522a9e5e31439a58addbb0166f0204d64066fb955265c4e214160f0", size = 175021, upload-time = "2026-01-10T09:22:22.696Z" },
+    { url = "https://files.pythonhosted.org/packages/10/40/904a4cb30d9b61c0e278899bf36342e9b0208eb3c470324a9ecbaac2a30f/websockets-16.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:583b7c42688636f930688d712885cf1531326ee05effd982028212ccc13e5957", size = 175320, upload-time = "2026-01-10T09:22:23.94Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/2f/4b3ca7e106bc608744b1cdae041e005e446124bebb037b18799c2d356864/websockets-16.0-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:7d837379b647c0c4c2355c2499723f82f1635fd2c26510e1f587d89bc2199e72", size = 183815, upload-time = "2026-01-10T09:22:25.469Z" },
+    { url = "https://files.pythonhosted.org/packages/86/26/d40eaa2a46d4302becec8d15b0fc5e45bdde05191e7628405a19cf491ccd/websockets-16.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:df57afc692e517a85e65b72e165356ed1df12386ecb879ad5693be08fac65dde", size = 185054, upload-time = "2026-01-10T09:22:27.101Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/ba/6500a0efc94f7373ee8fefa8c271acdfd4dca8bd49a90d4be7ccabfc397e/websockets-16.0-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:2b9f1e0d69bc60a4a87349d50c09a037a2607918746f07de04df9e43252c77a3", size = 184565, upload-time = "2026-01-10T09:22:28.293Z" },
+    { url = "https://files.pythonhosted.org/packages/04/b4/96bf2cee7c8d8102389374a2616200574f5f01128d1082f44102140344cc/websockets-16.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:335c23addf3d5e6a8633f9f8eda77efad001671e80b95c491dd0924587ece0b3", size = 183848, upload-time = "2026-01-10T09:22:30.394Z" },
+    { url = "https://files.pythonhosted.org/packages/02/8e/81f40fb00fd125357814e8c3025738fc4ffc3da4b6b4a4472a82ba304b41/websockets-16.0-cp310-cp310-win32.whl", hash = "sha256:37b31c1623c6605e4c00d466c9d633f9b812ea430c11c8a278774a1fde1acfa9", size = 178249, upload-time = "2026-01-10T09:22:32.083Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/5f/7e40efe8df57db9b91c88a43690ac66f7b7aa73a11aa6a66b927e44f26fa/websockets-16.0-cp310-cp310-win_amd64.whl", hash = "sha256:8e1dab317b6e77424356e11e99a432b7cb2f3ec8c5ab4dabbcee6add48f72b35", size = 178685, upload-time = "2026-01-10T09:22:33.345Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/db/de907251b4ff46ae804ad0409809504153b3f30984daf82a1d84a9875830/websockets-16.0-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:31a52addea25187bde0797a97d6fc3d2f92b6f72a9370792d65a6e84615ac8a8", size = 177340, upload-time = "2026-01-10T09:22:34.539Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/fa/abe89019d8d8815c8781e90d697dec52523fb8ebe308bf11664e8de1877e/websockets-16.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:417b28978cdccab24f46400586d128366313e8a96312e4b9362a4af504f3bbad", size = 175022, upload-time = "2026-01-10T09:22:36.332Z" },
+    { url = "https://files.pythonhosted.org/packages/58/5d/88ea17ed1ded2079358b40d31d48abe90a73c9e5819dbcde1606e991e2ad/websockets-16.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:af80d74d4edfa3cb9ed973a0a5ba2b2a549371f8a741e0800cb07becdd20f23d", size = 175319, upload-time = "2026-01-10T09:22:37.602Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/ae/0ee92b33087a33632f37a635e11e1d99d429d3d323329675a6022312aac2/websockets-16.0-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:08d7af67b64d29823fed316505a89b86705f2b7981c07848fb5e3ea3020c1abe", size = 184631, upload-time = "2026-01-10T09:22:38.789Z" },
+    { url = "https://files.pythonhosted.org/packages/c8/c5/27178df583b6c5b31b29f526ba2da5e2f864ecc79c99dae630a85d68c304/websockets-16.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7be95cfb0a4dae143eaed2bcba8ac23f4892d8971311f1b06f3c6b78952ee70b", size = 185870, upload-time = "2026-01-10T09:22:39.893Z" },
+    { url = "https://files.pythonhosted.org/packages/87/05/536652aa84ddc1c018dbb7e2c4cbcd0db884580bf8e95aece7593fde526f/websockets-16.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:d6297ce39ce5c2e6feb13c1a996a2ded3b6832155fcfc920265c76f24c7cceb5", size = 185361, upload-time = "2026-01-10T09:22:41.016Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/e2/d5332c90da12b1e01f06fb1b85c50cfc489783076547415bf9f0a659ec19/websockets-16.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:1c1b30e4f497b0b354057f3467f56244c603a79c0d1dafce1d16c283c25f6e64", size = 184615, upload-time = "2026-01-10T09:22:42.442Z" },
+    { url = "https://files.pythonhosted.org/packages/77/fb/d3f9576691cae9253b51555f841bc6600bf0a983a461c79500ace5a5b364/websockets-16.0-cp311-cp311-win32.whl", hash = "sha256:5f451484aeb5cafee1ccf789b1b66f535409d038c56966d6101740c1614b86c6", size = 178246, upload-time = "2026-01-10T09:22:43.654Z" },
+    { url = "https://files.pythonhosted.org/packages/54/67/eaff76b3dbaf18dcddabc3b8c1dba50b483761cccff67793897945b37408/websockets-16.0-cp311-cp311-win_amd64.whl", hash = "sha256:8d7f0659570eefb578dacde98e24fb60af35350193e4f56e11190787bee77dac", size = 178684, upload-time = "2026-01-10T09:22:44.941Z" },
+    { url = "https://files.pythonhosted.org/packages/84/7b/bac442e6b96c9d25092695578dda82403c77936104b5682307bd4deb1ad4/websockets-16.0-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:71c989cbf3254fbd5e84d3bff31e4da39c43f884e64f2551d14bb3c186230f00", size = 177365, upload-time = "2026-01-10T09:22:46.787Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/fe/136ccece61bd690d9c1f715baaeefd953bb2360134de73519d5df19d29ca/websockets-16.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:8b6e209ffee39ff1b6d0fa7bfef6de950c60dfb91b8fcead17da4ee539121a79", size = 175038, upload-time = "2026-01-10T09:22:47.999Z" },
+    { url = "https://files.pythonhosted.org/packages/40/1e/9771421ac2286eaab95b8575b0cb701ae3663abf8b5e1f64f1fd90d0a673/websockets-16.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:86890e837d61574c92a97496d590968b23c2ef0aeb8a9bc9421d174cd378ae39", size = 175328, upload-time = "2026-01-10T09:22:49.809Z" },
+    { url = "https://files.pythonhosted.org/packages/18/29/71729b4671f21e1eaa5d6573031ab810ad2936c8175f03f97f3ff164c802/websockets-16.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:9b5aca38b67492ef518a8ab76851862488a478602229112c4b0d58d63a7a4d5c", size = 184915, upload-time = "2026-01-10T09:22:51.071Z" },
+    { url = "https://files.pythonhosted.org/packages/97/bb/21c36b7dbbafc85d2d480cd65df02a1dc93bf76d97147605a8e27ff9409d/websockets-16.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e0334872c0a37b606418ac52f6ab9cfd17317ac26365f7f65e203e2d0d0d359f", size = 186152, upload-time = "2026-01-10T09:22:52.224Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/34/9bf8df0c0cf88fa7bfe36678dc7b02970c9a7d5e065a3099292db87b1be2/websockets-16.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:a0b31e0b424cc6b5a04b8838bbaec1688834b2383256688cf47eb97412531da1", size = 185583, upload-time = "2026-01-10T09:22:53.443Z" },
+    { url = "https://files.pythonhosted.org/packages/47/88/4dd516068e1a3d6ab3c7c183288404cd424a9a02d585efbac226cb61ff2d/websockets-16.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:485c49116d0af10ac698623c513c1cc01c9446c058a4e61e3bf6c19dff7335a2", size = 184880, upload-time = "2026-01-10T09:22:55.033Z" },
+    { url = "https://files.pythonhosted.org/packages/91/d6/7d4553ad4bf1c0421e1ebd4b18de5d9098383b5caa1d937b63df8d04b565/websockets-16.0-cp312-cp312-win32.whl", hash = "sha256:eaded469f5e5b7294e2bdca0ab06becb6756ea86894a47806456089298813c89", size = 178261, upload-time = "2026-01-10T09:22:56.251Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/f0/f3a17365441ed1c27f850a80b2bc680a0fa9505d733fe152fdf5e98c1c0b/websockets-16.0-cp312-cp312-win_amd64.whl", hash = "sha256:5569417dc80977fc8c2d43a86f78e0a5a22fee17565d78621b6bb264a115d4ea", size = 178693, upload-time = "2026-01-10T09:22:57.478Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/9c/baa8456050d1c1b08dd0ec7346026668cbc6f145ab4e314d707bb845bf0d/websockets-16.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:878b336ac47938b474c8f982ac2f7266a540adc3fa4ad74ae96fea9823a02cc9", size = 177364, upload-time = "2026-01-10T09:22:59.333Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/0c/8811fc53e9bcff68fe7de2bcbe75116a8d959ac699a3200f4847a8925210/websockets-16.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:52a0fec0e6c8d9a784c2c78276a48a2bdf099e4ccc2a4cad53b27718dbfd0230", size = 175039, upload-time = "2026-01-10T09:23:01.171Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/82/39a5f910cb99ec0b59e482971238c845af9220d3ab9fa76dd9162cda9d62/websockets-16.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:e6578ed5b6981005df1860a56e3617f14a6c307e6a71b4fff8c48fdc50f3ed2c", size = 175323, upload-time = "2026-01-10T09:23:02.341Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/28/0a25ee5342eb5d5f297d992a77e56892ecb65e7854c7898fb7d35e9b33bd/websockets-16.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:95724e638f0f9c350bb1c2b0a7ad0e83d9cc0c9259f3ea94e40d7b02a2179ae5", size = 184975, upload-time = "2026-01-10T09:23:03.756Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/66/27ea52741752f5107c2e41fda05e8395a682a1e11c4e592a809a90c6a506/websockets-16.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c0204dc62a89dc9d50d682412c10b3542d748260d743500a85c13cd1ee4bde82", size = 186203, upload-time = "2026-01-10T09:23:05.01Z" },
+    { url = "https://files.pythonhosted.org/packages/37/e5/8e32857371406a757816a2b471939d51c463509be73fa538216ea52b792a/websockets-16.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:52ac480f44d32970d66763115edea932f1c5b1312de36df06d6b219f6741eed8", size = 185653, upload-time = "2026-01-10T09:23:06.301Z" },
+    { url = "https://files.pythonhosted.org/packages/9b/67/f926bac29882894669368dc73f4da900fcdf47955d0a0185d60103df5737/websockets-16.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:6e5a82b677f8f6f59e8dfc34ec06ca6b5b48bc4fcda346acd093694cc2c24d8f", size = 184920, upload-time = "2026-01-10T09:23:07.492Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/a1/3d6ccdcd125b0a42a311bcd15a7f705d688f73b2a22d8cf1c0875d35d34a/websockets-16.0-cp313-cp313-win32.whl", hash = "sha256:abf050a199613f64c886ea10f38b47770a65154dc37181bfaff70c160f45315a", size = 178255, upload-time = "2026-01-10T09:23:09.245Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/ae/90366304d7c2ce80f9b826096a9e9048b4bb760e44d3b873bb272cba696b/websockets-16.0-cp313-cp313-win_amd64.whl", hash = "sha256:3425ac5cf448801335d6fdc7ae1eb22072055417a96cc6b31b3861f455fbc156", size = 178689, upload-time = "2026-01-10T09:23:10.483Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/1d/e88022630271f5bd349ed82417136281931e558d628dd52c4d8621b4a0b2/websockets-16.0-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:8cc451a50f2aee53042ac52d2d053d08bf89bcb31ae799cb4487587661c038a0", size = 177406, upload-time = "2026-01-10T09:23:12.178Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/78/e63be1bf0724eeb4616efb1ae1c9044f7c3953b7957799abb5915bffd38e/websockets-16.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:daa3b6ff70a9241cf6c7fc9e949d41232d9d7d26fd3522b1ad2b4d62487e9904", size = 175085, upload-time = "2026-01-10T09:23:13.511Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/f4/d3c9220d818ee955ae390cf319a7c7a467beceb24f05ee7aaaa2414345ba/websockets-16.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:fd3cb4adb94a2a6e2b7c0d8d05cb94e6f1c81a0cf9dc2694fb65c7e8d94c42e4", size = 175328, upload-time = "2026-01-10T09:23:14.727Z" },
+    { url = "https://files.pythonhosted.org/packages/63/bc/d3e208028de777087e6fb2b122051a6ff7bbcca0d6df9d9c2bf1dd869ae9/websockets-16.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:781caf5e8eee67f663126490c2f96f40906594cb86b408a703630f95550a8c3e", size = 185044, upload-time = "2026-01-10T09:23:15.939Z" },
+    { url = "https://files.pythonhosted.org/packages/ad/6e/9a0927ac24bd33a0a9af834d89e0abc7cfd8e13bed17a86407a66773cc0e/websockets-16.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:caab51a72c51973ca21fa8a18bd8165e1a0183f1ac7066a182ff27107b71e1a4", size = 186279, upload-time = "2026-01-10T09:23:17.148Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/ca/bf1c68440d7a868180e11be653c85959502efd3a709323230314fda6e0b3/websockets-16.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:19c4dc84098e523fd63711e563077d39e90ec6702aff4b5d9e344a60cb3c0cb1", size = 185711, upload-time = "2026-01-10T09:23:18.372Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/f8/fdc34643a989561f217bb477cbc47a3a07212cbda91c0e4389c43c296ebf/websockets-16.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:a5e18a238a2b2249c9a9235466b90e96ae4795672598a58772dd806edc7ac6d3", size = 184982, upload-time = "2026-01-10T09:23:19.652Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/d1/574fa27e233764dbac9c52730d63fcf2823b16f0856b3329fc6268d6ae4f/websockets-16.0-cp314-cp314-win32.whl", hash = "sha256:a069d734c4a043182729edd3e9f247c3b2a4035415a9172fd0f1b71658a320a8", size = 177915, upload-time = "2026-01-10T09:23:21.458Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/f1/ae6b937bf3126b5134ce1f482365fde31a357c784ac51852978768b5eff4/websockets-16.0-cp314-cp314-win_amd64.whl", hash = "sha256:c0ee0e63f23914732c6d7e0cce24915c48f3f1512ec1d079ed01fc629dab269d", size = 178381, upload-time = "2026-01-10T09:23:22.715Z" },
+    { url = "https://files.pythonhosted.org/packages/06/9b/f791d1db48403e1f0a27577a6beb37afae94254a8c6f08be4a23e4930bc0/websockets-16.0-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:a35539cacc3febb22b8f4d4a99cc79b104226a756aa7400adc722e83b0d03244", size = 177737, upload-time = "2026-01-10T09:23:24.523Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/40/53ad02341fa33b3ce489023f635367a4ac98b73570102ad2cdd770dacc9a/websockets-16.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:b784ca5de850f4ce93ec85d3269d24d4c82f22b7212023c974c401d4980ebc5e", size = 175268, upload-time = "2026-01-10T09:23:25.781Z" },
+    { url = "https://files.pythonhosted.org/packages/74/9b/6158d4e459b984f949dcbbb0c5d270154c7618e11c01029b9bbd1bb4c4f9/websockets-16.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:569d01a4e7fba956c5ae4fc988f0d4e187900f5497ce46339c996dbf24f17641", size = 175486, upload-time = "2026-01-10T09:23:27.033Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/2d/7583b30208b639c8090206f95073646c2c9ffd66f44df967981a64f849ad/websockets-16.0-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:50f23cdd8343b984957e4077839841146f67a3d31ab0d00e6b824e74c5b2f6e8", size = 185331, upload-time = "2026-01-10T09:23:28.259Z" },
+    { url = "https://files.pythonhosted.org/packages/45/b0/cce3784eb519b7b5ad680d14b9673a31ab8dcb7aad8b64d81709d2430aa8/websockets-16.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:152284a83a00c59b759697b7f9e9cddf4e3c7861dd0d964b472b70f78f89e80e", size = 186501, upload-time = "2026-01-10T09:23:29.449Z" },
+    { url = "https://files.pythonhosted.org/packages/19/60/b8ebe4c7e89fb5f6cdf080623c9d92789a53636950f7abacfc33fe2b3135/websockets-16.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:bc59589ab64b0022385f429b94697348a6a234e8ce22544e3681b2e9331b5944", size = 186062, upload-time = "2026-01-10T09:23:31.368Z" },
+    { url = "https://files.pythonhosted.org/packages/88/a8/a080593f89b0138b6cba1b28f8df5673b5506f72879322288b031337c0b8/websockets-16.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:32da954ffa2814258030e5a57bc73a3635463238e797c7375dc8091327434206", size = 185356, upload-time = "2026-01-10T09:23:32.627Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/b6/b9afed2afadddaf5ebb2afa801abf4b0868f42f8539bfe4b071b5266c9fe/websockets-16.0-cp314-cp314t-win32.whl", hash = "sha256:5a4b4cc550cb665dd8a47f868c8d04c8230f857363ad3c9caf7a0c3bf8c61ca6", size = 178085, upload-time = "2026-01-10T09:23:33.816Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/3e/28135a24e384493fa804216b79a6a6759a38cc4ff59118787b9fb693df93/websockets-16.0-cp314-cp314t-win_amd64.whl", hash = "sha256:b14dc141ed6d2dde437cddb216004bcac6a1df0935d79656387bd41632ba0bbd", size = 178531, upload-time = "2026-01-10T09:23:35.016Z" },
+    { url = "https://files.pythonhosted.org/packages/72/07/c98a68571dcf256e74f1f816b8cc5eae6eb2d3d5cfa44d37f801619d9166/websockets-16.0-pp311-pypy311_pp73-macosx_10_15_x86_64.whl", hash = "sha256:349f83cd6c9a415428ee1005cadb5c2c56f4389bc06a9af16103c3bc3dcc8b7d", size = 174947, upload-time = "2026-01-10T09:23:36.166Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/52/93e166a81e0305b33fe416338be92ae863563fe7bce446b0f687b9df5aea/websockets-16.0-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:4a1aba3340a8dca8db6eb5a7986157f52eb9e436b74813764241981ca4888f03", size = 175260, upload-time = "2026-01-10T09:23:37.409Z" },
+    { url = "https://files.pythonhosted.org/packages/56/0c/2dbf513bafd24889d33de2ff0368190a0e69f37bcfa19009ef819fe4d507/websockets-16.0-pp311-pypy311_pp73-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:f4a32d1bd841d4bcbffdcb3d2ce50c09c3909fbead375ab28d0181af89fd04da", size = 176071, upload-time = "2026-01-10T09:23:39.158Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/8f/aea9c71cc92bf9b6cc0f7f70df8f0b420636b6c96ef4feee1e16f80f75dd/websockets-16.0-pp311-pypy311_pp73-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0298d07ee155e2e9fda5be8a9042200dd2e3bb0b8a38482156576f863a9d457c", size = 176968, upload-time = "2026-01-10T09:23:41.031Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/3f/f70e03f40ffc9a30d817eef7da1be72ee4956ba8d7255c399a01b135902a/websockets-16.0-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:a653aea902e0324b52f1613332ddf50b00c06fdaf7e92624fbf8c77c78fa5767", size = 178735, upload-time = "2026-01-10T09:23:42.259Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/28/258ebab549c2bf3e64d2b0217b973467394a9cea8c42f70418ca2c5d0d2e/websockets-16.0-py3-none-any.whl", hash = "sha256:1637db62fad1dc833276dded54215f2c7fa46912301a24bd94d45d46a011ceec", size = 171598, upload-time = "2026-01-10T09:23:45.395Z" },
+]
+
+[[package]]
+name = "zipp"
+version = "3.23.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e3/02/0f2892c661036d50ede074e376733dca2ae7c6eb617489437771209d4180/zipp-3.23.0.tar.gz", hash = "sha256:a07157588a12518c9d4034df3fbbee09c814741a33ff63c05fa29d26a2404166", size = 25547, upload-time = "2025-06-08T17:06:39.4Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2e/54/647ade08bf0db230bfea292f893923872fd20be6ac6f53b2b936ba839d75/zipp-3.23.0-py3-none-any.whl", hash = "sha256:071652d6115ed432f5ce1d34c336c0adfd6a884660d1e9712a256d3d3bd4b14e", size = 10276, upload-time = "2025-06-08T17:06:38.034Z" },
+]
diff --git a/v3-notes/get-methods-consolidation.md b/v3-notes/get-methods-consolidation.md
new file mode 100644
index 0000000..70b64c9
--- /dev/null
+++ b/v3-notes/get-methods-consolidation.md
@@ -0,0 +1,61 @@
+# 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`.
+
+```python
+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.
+
+```python
+# 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
diff --git a/v3-notes/prompt-internal-types.md b/v3-notes/prompt-internal-types.md
new file mode 100644
index 0000000..addbd01
--- /dev/null
+++ b/v3-notes/prompt-internal-types.md
@@ -0,0 +1,121 @@
+# Prompt Internal Types - Message and PromptResult
+
+**Version:** 3.0.0
+**Impact:** Breaking change for prompts returning `mcp.types.PromptMessage`
+
+## Summary
+
+Prompts now use FastMCP's `Message` and `PromptResult` types internally, following the same pattern as resources (#2734). MCP SDK types are only used at the protocol boundary.
+
+## What Changed
+
+### Before (v2.x)
+```python
+from mcp.types import PromptMessage, TextContent
+
+@mcp.prompt
+def my_prompt() -> PromptMessage:
+    return PromptMessage(
+        role="user",
+        content=TextContent(type="text", text="Hello")
+    )
+```
+
+### After (v3.0)
+```python
+from fastmcp.prompts import Message
+
+@mcp.prompt
+def my_prompt() -> Message:
+    return Message("Hello")  # role defaults to "user"
+```
+
+## Type Constraints
+
+### Prompt Function Return Types
+```python
+str | list[Message | str] | PromptResult
+```
+
+**Valid:**
+- `return "Hello"` → wrapped as single user Message
+- `return [Message("Hi"), Message("Response", role="assistant")]`
+- `return ["Hi", "Response"]` → strings auto-wrapped as user Messages
+- `return PromptResult(messages=[...], meta={...})`
+
+**Invalid (now raises error):**
+- `return PromptMessage(...)` → Use `Message` instead
+- `return Message(...)` as single value → Use `PromptResult([Message(...)])` or return a list
+
+### Message Class
+```python
+Message(
+    content: Any,  # Auto-serializes non-str to JSON
+    role: Literal["user", "assistant"] = "user"
+)
+```
+
+**Auto-Serialization:**
+- `str` → passes through as TextContent
+- `dict` → JSON-serialized to text
+- `list` → JSON-serialized to text
+- `BaseModel` → JSON-serialized to text
+- `TextContent` / `EmbeddedResource` → passes through directly
+
+### PromptResult Class
+```python
+PromptResult(
+    messages: str | list[Message],  # str wrapped as single Message
+    description: str | None = None,
+    meta: dict[str, Any] | None = None
+)
+```
+
+## Why This Change?
+
+1. **Simpler API** - `Message("Hello")` vs `PromptMessage(role="user", content=TextContent(type="text", text="Hello"))`
+2. **Auto-serialization** - Dicts/lists/models automatically become JSON
+3. **Consistent with resources** - Same pattern as `ResourceContent`/`ResourceResult`
+4. **Type safety** - Strict typing catches errors at development time
+
+## Migration Guide
+
+### Simple Message
+```python
+# Before
+from mcp.types import PromptMessage, TextContent
+return PromptMessage(role="user", content=TextContent(type="text", text="Hello"))
+
+# After
+from fastmcp.prompts import Message
+return Message("Hello")
+```
+
+### Conversation
+```python
+# Before
+return [
+    PromptMessage(role="user", content=TextContent(type="text", text="Hi")),
+    PromptMessage(role="assistant", content=TextContent(type="text", text="Hello!")),
+]
+
+# After
+return [
+    Message("Hi"),
+    Message("Hello!", role="assistant"),
+]
+```
+
+### With Metadata
+```python
+from fastmcp.prompts import Message, PromptResult
+
+return PromptResult(
+    messages=[Message("Analyze this")],
+    meta={"priority": "high"}
+)
+```
+
+## PR
+
+- #2738 - Introduce Message and PromptResult as canonical prompt types
diff --git a/v3-notes/provider-architecture.md b/v3-notes/provider-architecture.md
new file mode 100644
index 0000000..b1a0e80
--- /dev/null
+++ b/v3-notes/provider-architecture.md
@@ -0,0 +1,116 @@
+# Provider Architecture: FastMCPProvider + TransformingProvider
+
+**Version:** 3.0.0
+**Impact:** Breaking change - `MountedProvider` removed
+
+## Summary
+
+The monolithic `MountedProvider` was split into two focused, composable components:
+
+- **`FastMCPProvider`**: Wraps a FastMCP server, exposing its components through the Provider interface
+- **`TransformingProvider`**: Wraps any provider to apply namespace prefixes and tool renames
+
+## Why the Split?
+
+`MountedProvider` was doing two things:
+1. Wrapping a FastMCP server as a provider
+2. Transforming component names with prefixes
+
+Separating these concerns enables:
+- Reusing transformations on any provider (not just FastMCP servers)
+- Stacking transformations via composition
+- Clearer mental model
+
+## New API
+
+### FastMCPProvider
+
+Wraps a FastMCP server to expose it through the Provider interface:
+
+```python
+from fastmcp.server.providers import FastMCPProvider
+
+sub_server = FastMCP("Sub")
+
+@sub_server.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+# Wrap as provider
+provider = FastMCPProvider(sub_server)
+main_server.add_provider(provider)
+```
+
+### TransformingProvider
+
+Wraps any provider to apply transformations:
+
+```python
+# Apply namespace to all components
+provider = FastMCPProvider(server).with_namespace("api")
+# "my_tool" → "api_my_tool"
+# "resource://data" → "resource://api/data"
+
+# Rename specific tools (bypasses namespace)
+provider = FastMCPProvider(server).with_transforms(
+    namespace="api",
+    tool_renames={"verbose_tool_name": "short"}
+)
+# "verbose_tool_name" → "short"
+# "other_tool" → "api_other_tool"
+```
+
+### Stacking Transformations
+
+Transformations compose via stacking:
+
+```python
+provider = (
+    FastMCPProvider(server)
+    .with_namespace("inner")
+    .with_namespace("outer")
+)
+# "tool" → "outer_inner_tool"
+```
+
+## mount() Uses This Internally
+
+`FastMCP.mount()` now creates a `FastMCPProvider` + `TransformingProvider` internally:
+
+```python
+main.mount(sub, namespace="api")
+
+# Equivalent to:
+main.add_provider(
+    FastMCPProvider(sub).with_namespace("api")
+)
+```
+
+## Breaking Changes
+
+### MountedProvider Removed
+
+```python
+# Before (2.x)
+from fastmcp.server.providers import MountedProvider
+provider = MountedProvider(server, prefix="api")
+
+# After (3.x)
+from fastmcp.server.providers import FastMCPProvider
+provider = FastMCPProvider(server).with_namespace("api")
+```
+
+### prefix → namespace
+
+```python
+# Before (deprecated)
+main.mount(sub, prefix="api")
+
+# After
+main.mount(sub, namespace="api")
+```
+
+## Implementation PRs
+
+- #2653 - Split MountedProvider into FastMCPProvider + TransformingProvider
+- #2635 - Initial MountedProvider (superseded by #2653)
diff --git a/v3-notes/provider-test-pattern.md b/v3-notes/provider-test-pattern.md
new file mode 100644
index 0000000..c37c14c
--- /dev/null
+++ b/v3-notes/provider-test-pattern.md
@@ -0,0 +1,60 @@
+# Provider Tests: Direct Server Calls
+
+This document captures the design decision to test providers via direct server method calls rather than wrapping in a Client.
+
+## Problem
+
+Provider tests were using the Client pattern:
+
+```python
+async with Client(mcp) as client:
+    result = await client.call_tool("add", {"x": 1, "y": 2})
+    assert result.data == 3
+```
+
+This conflated two concerns:
+1. Does the provider/server work correctly?
+2. Does the Client-Server interaction work correctly?
+
+Additionally, ~1,200 lines of tests in `test_server_interactions.py` duplicated provider tests.
+
+## Solution
+
+Provider tests now call server methods directly:
+
+```python
+result = await mcp.call_tool("add", {"x": 1, "y": 2})
+assert result.structured_content == {"result": 3}
+```
+
+This establishes clear test ownership:
+- **Provider tests** → verify server functionality
+- **Integration tests** → verify Client-Server interaction
+
+## Result Access Patterns
+
+Direct server calls return canonical FastMCP types, not MCP protocol types:
+
+| Component | Access Pattern |
+|-----------|----------------|
+| Tool | `result.structured_content` or `result.text` |
+| Resource | `result.contents[0].content` |
+| Prompt | `result.messages[0].content.text` |
+
+## Error Types
+
+Direct calls raise FastMCP exceptions:
+- `NotFoundError` - component not found
+- `DisabledError` - component disabled by visibility
+
+Client calls raise MCP protocol errors (wrapped in `McpError`).
+
+## Implementation
+
+- Consolidated duplicate tests from `test_server_interactions.py` into provider test files
+- Reduced `test_server_interactions.py` from 1,455 → 179 lines
+- Only `TestMeta` tests remain in interactions file (require Client for context injection)
+
+## PR
+
+- #2748 - Convert provider tests to use direct server calls
diff --git a/v3-notes/resource-internal-types.md b/v3-notes/resource-internal-types.md
new file mode 100644
index 0000000..24cd632
--- /dev/null
+++ b/v3-notes/resource-internal-types.md
@@ -0,0 +1,196 @@
+# Resource Internal Types - Strict Typing for Type Safety
+
+**Version:** 3.0.0
+**Impact:** Breaking change for resources returning dict/list
+
+## Summary
+
+ResourceResult now enforces strict typing to catch errors at development time (via type checker) rather than at runtime (when a client reads a resource).
+
+## What Changed
+
+### Before (v2.x)
+```python
+@mcp.resource("data://config")
+def get_config() -> dict:  # Auto-serialized to JSON
+    return {"key": "value"}
+
+@mcp.resource("data://items")
+def get_items() -> list:  # Each item auto-wrapped
+    return ["item1", "item2"]
+
+ResourceResult({"key": "value"})  # Dict auto-converted
+ResourceResult(["a", "b"])         # List split into items
+```
+
+### After (v3.0)
+```python
+@mcp.resource("data://config")
+def get_config() -> str:  # Explicit JSON serialization
+    import json
+    return json.dumps({"key": "value"})
+
+@mcp.resource("data://items")
+def get_items() -> ResourceResult:  # Explicit multi-item response
+    return ResourceResult([
+        ResourceContent("item1"),
+        ResourceContent("item2"),
+    ])
+
+ResourceResult([ResourceContent(...)])  # Explicit list wrapping
+# Dict/list raises TypeError
+```
+
+## Type Constraints
+
+### Resource.read() Return Type
+```python
+str | bytes | ResourceResult
+```
+
+**Valid:**
+- `return "text content"`
+- `return b"binary data"`
+- `return ResourceResult([ResourceContent(...)])`
+
+**Invalid (now raises TypeError):**
+- `return {"key": "value"}` → Use `json.dumps()` instead
+- `return ["item1", "item2"]` → Use `ResourceResult([ResourceContent(...)])`
+- `return ResourceContent(...)` → Use `ResourceResult([ResourceContent(...)])`
+
+### ResourceResult Type Signature
+```python
+ResourceResult(
+    contents: str | bytes | list[ResourceContent],
+    meta: dict[str, Any] | None = None
+)
+```
+
+**Valid:**
+- `ResourceResult("plain text")`
+- `ResourceResult(b"binary")`
+- `ResourceResult([ResourceContent(...), ResourceContent(...)])`
+
+**Invalid (now raises TypeError):**
+- `ResourceResult({"key": "value"})` → Dict not supported
+- `ResourceResult(["a", "b"])` → Bare list not supported (must be list[ResourceContent])
+- `ResourceResult(resource_content_obj)` → Single item must be in list
+
+### ResourceContent Type Signature
+```python
+ResourceContent(
+    content: Any,  # Auto-serializes non-str/bytes to JSON
+    mime_type: str | None = None,
+    meta: dict[str, Any] | None = None
+)
+```
+
+**Auto-Serialization in ResourceContent.__init__:**
+- `str` → passes through (mime_type defaults to "text/plain")
+- `bytes` → passes through (mime_type defaults to "application/octet-stream")
+- `dict` → JSON-serialized string (mime_type defaults to "application/json")
+- `list` → JSON-serialized string (mime_type defaults to "application/json")
+- `BaseModel` → JSON-serialized string (mime_type defaults to "application/json")
+
+## Why This Change?
+
+The old auto-conversion behavior was convenient but hid errors:
+
+```python
+# Old behavior - silent failure
+return ["item1", "item2"]  # Client sees 2 items OR JSON array?
+# Ambiguous! Users would discover issues only when client reads resource
+
+# New behavior - caught at dev time
+return ["item1", "item2"]  # Type checker error immediately
+# Must explicitly write:
+return json.dumps(["item1", "item2"])  # Clear intent
+# OR:
+return ResourceResult([ResourceContent("item1"), ResourceContent("item2")])
+```
+
+Type checkers now catch return type mismatches during development rather than at runtime.
+
+## Migration Guide
+
+### Returning JSON Data
+**Before:**
+```python
+def get_config() -> dict:
+    return {"key": "value", "nested": {"a": 1}}
+```
+
+**After:**
+```python
+import json
+
+def get_config() -> str:
+    return json.dumps({"key": "value", "nested": {"a": 1}})
+```
+
+### Returning Multiple Items
+**Before:**
+```python
+def get_items() -> list:
+    return ["user1", "user2", "user3"]
+```
+
+**After (Option 1: Single JSON array):**
+```python
+import json
+
+def get_items() -> str:
+    return json.dumps(["user1", "user2", "user3"])
+```
+
+**After (Option 2: Multiple content items):**
+```python
+from fastmcp.resources import ResourceContent, ResourceResult
+
+def get_items() -> ResourceResult:
+    return ResourceResult([
+        ResourceContent("user1"),
+        ResourceContent("user2"),
+        ResourceContent("user3"),
+    ])
+```
+
+### Returning Structured Data with Custom MIME Types
+**Before:**
+```python
+def get_html() -> dict:
+    return {"html": "<div>content</div>"}
+```
+
+**After:**
+```python
+from fastmcp.resources import ResourceContent, ResourceResult
+
+def get_html() -> ResourceResult:
+    return ResourceResult([
+        ResourceContent(
+            content="<div>content</div>",
+            mime_type="text/html"
+        )
+    ])
+```
+
+## Type Checking
+
+Your type checker will now catch these errors:
+
+```python
+@mcp.resource("data://test")
+def bad_resource() -> dict:  # ← Type error: should be str | bytes | ResourceResult
+    return {"key": "value"}
+```
+
+This is intentional. The type system enforces correct typing at development time.
+
+## Backward Compatibility
+
+**This is a breaking change.** Code that returns dict or list from resources will:
+1. **Pass type checking**: If you ignore type warnings
+2. **Fail at runtime**: Raises `TypeError` when client reads the resource
+
+Migrate to explicit JSON serialization or ResourceResult.
diff --git a/v3-notes/task-meta-parameter.md b/v3-notes/task-meta-parameter.md
new file mode 100644
index 0000000..4678c42
--- /dev/null
+++ b/v3-notes/task-meta-parameter.md
@@ -0,0 +1,109 @@
+# Explicit task_meta Parameter for Background Tasks
+
+This document captures the design decision to add explicit `task_meta` parameters to component execution methods, replacing context variable-based task routing.
+
+## Problem
+
+Background task execution used context variables (`_task_metadata`, `_docket_fn_key`) to pass task metadata through the call stack. This was implicit and had several issues:
+
+1. **Hidden state** - Task metadata flowed through context vars, making it hard to trace
+2. **Fragile enrichment** - `fn_key` was enriched in 9 different places (component methods + provider wrappers)
+3. **Testing difficulty** - Required setting context vars to test background behavior
+4. **No programmatic API** - Users couldn't explicitly request background execution via `call_tool()`
+
+## Solution
+
+Add explicit `task_meta: TaskMeta | None` parameters to:
+- `FastMCP.call_tool()`, `FastMCP.read_resource()`, `FastMCP.render_prompt()`
+- Component methods: `Tool._run()`, `Resource._read()`, `Prompt._render()`, `ResourceTemplate._read()`
+
+```python
+from fastmcp.server.tasks import TaskMeta
+
+# Explicit background execution
+result = await server.call_tool("my_tool", {"arg": "value"}, task_meta=TaskMeta(ttl=300))
+
+# Returns CreateTaskResult for background, ToolResult for sync
+```
+
+## fn_key Enrichment Centralization
+
+Previously, `fn_key` (the Docket registry key) was set in 9 places:
+
+**Component methods (5):**
+- `Tool._run()`
+- `Resource._read()`
+- `ResourceTemplate._read()` (2 places)
+- `Prompt._render()`
+
+**Provider wrappers (4):**
+- `FastMCPProviderTool._run()`
+- `FastMCPProviderResource._read()`
+- `FastMCPProviderPrompt._render()`
+- `FastMCPProviderResourceTemplate._read()`
+
+Now, `fn_key` is set in **3 places** (server methods only):
+
+```python
+# In call_tool(), after finding the tool:
+if task_meta is not None and task_meta.fn_key is None:
+    task_meta = replace(task_meta, fn_key=tool.key)
+
+# In read_resource(), after finding resource or template:
+if task_meta is not None and task_meta.fn_key is None:
+    task_meta = replace(task_meta, fn_key=resource.key)  # or template.key
+
+# In render_prompt(), after finding the prompt:
+if task_meta is not None and task_meta.fn_key is None:
+    task_meta = replace(task_meta, fn_key=prompt.key)
+```
+
+## Why This Works for Mounted Servers
+
+For mounted servers, `provider.get_tool(name)` returns a `FastMCPProviderTool` whose `.key` is already namespaced (e.g., `"tool:child_multiply"`). So setting `fn_key = tool.key` in the parent server gives the correct namespaced key.
+
+When the provider wrapper delegates to the child server, `fn_key` is already set, so the child server won't override it.
+
+## Type-Safe Overloads
+
+Each method uses `@overload` to provide correct return types:
+
+```python
+@overload
+async def call_tool(
+    self, name: str, arguments: dict[str, Any], *, task_meta: None = None
+) -> ToolResult: ...
+
+@overload
+async def call_tool(
+    self, name: str, arguments: dict[str, Any], *, task_meta: TaskMeta
+) -> ToolResult | mcp.types.CreateTaskResult: ...
+```
+
+## Middleware Runs Before Docket
+
+A key fix from #2663: background tasks now properly pass through all middleware stacks before being submitted to Docket. Previously, background task submission bypassed middleware entirely.
+
+The flow is now:
+1. MCP handler extracts task metadata from request
+2. Server method (`call_tool`, etc.) finds component via provider
+3. Server enriches `task_meta.fn_key` with component key
+4. Component's `_run()`/`_read()`/`_render()` is called
+5. Middleware runs (logging, auth, rate limiting, etc.)
+6. `check_background_task()` submits to Docket if task_meta present
+
+For mounted servers, the wrapper components delegate to the child server, which runs the child's middleware before the actual execution or Docket submission.
+
+## Removed Dead Code
+
+- `_task_metadata` context variable
+- `_docket_fn_key` context variable
+- `get_task_metadata()` function
+- `key` parameter in `check_background_task()` (backwards compat fallback)
+
+## Implementation PRs
+
+- #2663 - Components own execution; middleware runs before Docket
+- #2749 - `task_meta` for `call_tool()`
+- #2750 - `task_meta` for `read_resource()`
+- #2751 - `task_meta` for `render_prompt()` + fn_key centralization
diff --git a/v3-notes/visibility.md b/v3-notes/visibility.md
new file mode 100644
index 0000000..fa1c040
--- /dev/null
+++ b/v3-notes/visibility.md
@@ -0,0 +1,113 @@
+# Visibility & Enable/Disable Design
+
+This document captures the design decisions for the enable/disable system in FastMCP 3.0.
+
+## Core Principle
+
+**Components describe capabilities. Servers and providers control availability.**
+
+Previously, each component had an `enabled` field that users could mutate directly. This caused a fundamental problem: when components pass through providers (especially TransformingProvider), you receive copies—and mutating a copy doesn't affect the original.
+
+## Solution: Hierarchical Visibility
+
+Both servers and providers maintain their own `VisibilityFilter`. If a component is disabled at any level, it's disabled up the chain.
+
+```
+Provider A (filters) → Provider B (filters) → Server (filters) → Client sees only enabled components
+```
+
+## VisibilityFilter
+
+The `VisibilityFilter` class (`src/fastmcp/utilities/visibility.py`) provides:
+
+### Blocklist (disable)
+```python
+server.disable(keys=["tool:my_tool"])  # Hide specific component
+server.disable(tags={"internal"})       # Hide all components with tag
+```
+
+### Allowlist (enable with only=True)
+```python
+server.enable(tags={"public"}, only=True)  # Show ONLY components with tag
+```
+
+### Blocklist Wins
+If a component is in both blocklist and allowlist, blocklist wins. This ensures you can always hide something regardless of other filters.
+
+### Change Detection
+The `VisibilityFilter` only sends notifications when visibility actually changes:
+- Disabling an already-disabled component: no notification
+- Enabling an already-enabled component: no notification
+- Actual state change: notification sent
+
+## Vocabulary
+
+Consistent verbs throughout the codebase:
+- `enable()` / `disable()` - methods on servers and providers
+- `is_enabled()` - check if component is visible
+- `_disabled_keys`, `_disabled_tags` - blocklist state
+- `_enabled_keys`, `_enabled_tags` - allowlist state
+- `_default_enabled` - True unless `only=True` was used
+
+## Notifications
+
+`VisibilityFilter` handles notifications directly via `_send_notification()`. This:
+1. Gets the current request context (if any)
+2. Queues the appropriate list-changed notification
+3. No-ops gracefully outside request context
+
+This simplifies the code—no callback wiring needed between VisibilityFilter and its owners.
+
+## Migration from 2.x
+
+### Component enable/disable removed
+
+```python
+# Before (2.x) - BROKEN: mutates a copy
+tool.disable()
+
+# After (3.x)
+server.disable(keys=["tool:my_tool"])
+```
+
+### enabled field removed
+
+```python
+# Before (2.x)
+@mcp.tool(enabled=False)
+def my_tool(): ...
+
+# After (3.x)
+@mcp.tool
+def my_tool(): ...
+
+mcp.disable(keys=["tool:my_tool"])
+```
+
+### include_tags/exclude_tags deprecated
+
+```python
+# Before (deprecated)
+mcp = FastMCP("server", exclude_tags={"internal"})
+
+# After
+mcp = FastMCP("server")
+mcp.disable(tags={"internal"})
+```
+
+## Component Keys
+
+Components use prefixed keys for enable/disable:
+- Tools: `"tool:function_name"`
+- Prompts: `"prompt:prompt_name"`
+- Resources: `"resource:resource://uri"`
+- Templates: `"template:resource://{param}/path"`
+
+Use `component.key` to get the correct key format.
+
+## Implementation Files
+
+- `src/fastmcp/utilities/visibility.py` - VisibilityFilter class
+- `src/fastmcp/server/providers/base.py` - Provider.enable/disable
+- `src/fastmcp/server/server.py` - FastMCP.enable/disable
+- `src/fastmcp/utilities/components.py` - Component.enable/disable raise NotImplementedError